# LPT AI 服务（lpt-ai）

> TypeScript + Fastify 独立 AI 服务，集成 SiliconFlow LLM，为后端提供异步 AI 任务。

## Git 提交规范

- 提交信息必须简短且使用中文，不要使用英文长句。
- 格式：`类型: 简述`，例如 `feat: 新增思维导图生成任务`、`fix: 修复任务队列TTL清理`、`docs: 补充环境变量说明`。

## 技术栈

- 运行时：Node.js 20+
- 框架：Fastify 5
- LLM：SiliconFlow OpenAI 兼容接口（Qwen/Qwen2.5-32B-Instruct）
- 运行时依赖：除 fastify 外无其他外部依赖

## 项目结构

```text
lpt-ai/src/
├── index.ts          → 服务入口（加载 .env，启动 Fastify）
├── routes/ai.ts      → AI 路由（health, tasks, fetch-title）
├── llm/
│   ├── client.ts     → LLM 客户端（SiliconFlow 接口）
│   ├── prompts.ts    → Prompt 模板（3 种任务类型）
│   └── prompts.test.ts
├── task-queue.ts     → 异步任务队列
└── admin/
    ├── index.ts      → 管理面板路由
    ├── routes.ts
    └── store.ts      → 日志存储
```

## API 端点（5 个）

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/health` | 健康检查（返回 LLM 可用状态和模型名） |
| POST | `/ai/tasks` | 提交异步任务（返回 taskId） |
| GET | `/ai/tasks/:taskId` | 轮询任务结果 |
| POST | `/fetch-title` | 抓取网页标题 |
| GET | `/admin` | 管理面板（查看最近 200 条日志） |

## 支持的任务类型

| 类型 | 说明 | 温度 | Max Tokens |
|------|------|------|------------|
| `aggregate-report` | 残片聚合为学习报告 | 0.3 | 2048 |
| `generate-mind-map` | 从报告/残片生成思维导图大纲 | 0.3 | 4096 |
| `compare-recall` | 用户回忆 vs 标准导图语义对比 | 0.2 | 4096 |

## 任务队列设计

- 异步任务模式：submit + poll，避免 LLM 长耗时（10-60s）超时。
- 单线程 Worker：`setImmediate` 链，同一时刻只处理一个 LLM 调用，防止 API 限流。
- TTL 清理：5 分钟一次，移除完成超过 1 小时的记录。
- 异常隔离：单个任务失败不影响后续任务。
- 管理面板日志：复用 `logStore`，记录最近 200 条请求/响应。

## LLM 配置

```env
LLM_API_URL=https://api.siliconflow.cn/v1/chat/completions
LLM_API_KEY=                    # 必填，未配置时 /health 返回 llmAvailable: false
LLM_MODEL=Qwen/Qwen2.5-32B-Instruct
LLM_TIMEOUT_MS=60000            # 单次 LLM 调用超时
PORT=5199
```

## 降级策略

- LLM API Key 未配置 → `/health` 返回 `llmAvailable: false`。
- 后端（lpt-be）检测到 AI 不可用 → 自动切换到内置规则引擎（`BuiltinMindMapGenerator`）。
- Java 后端是唯一调用方；本服务不直接暴露给前端，不做鉴权（部署在内网）。

## 启动命令

```bash
npm install
npm run dev        # 开发模式（tsx watch，热重载）
npm run build      # 编译 TypeScript
npm run start      # 生产模式
npm run test       # 测试
```

## Docker

- 多阶段构建：`node:20-alpine` 编译 → `node:20-alpine` 运行。
- 暴露端口：5199。
- 健康检查：`curl http://localhost:5199/health`。

## 关联项目

| 项目 | 路径 | 端口 | 说明 |
|------|------|------|------|
| lpt-be | `../lpt-be/` | 5157 | Spring Boot 后端，通过 `lpt.ai-service.url` 调用本服务 |
| lpt-fe | `../lpt-fe/` | 5158 | Vue 3 前端，不直接调用本服务 |

## 调用关系

```text
lpt-be (5157) ──HTTP POST /ai/tasks──→ lpt-ai (5199)
lpt-be (5157) ──HTTP GET  /ai/tasks/:id──→ lpt-ai (5199)
```