Files
lpt-ai/AGENTS.md
T

135 lines
5.6 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# LPT AI 服务(lpt-ai)
> TypeScript + Fastify 独立 AI 服务,集成 DeepSeek LLM,为后端提供异步 AI 任务。
## Git 提交规范
- 提交信息必须简短且使用中文,不要使用英文长句。
- 格式:`类型: 简述`,例如 `feat: 新增思维导图生成任务`、`fix: 修复任务队列TTL清理`、`docs: 补充环境变量说明`。
## 技术栈
- 运行时:Node.js 20+
- 框架:Fastify 5
- LLM:DeepSeek OpenAI 兼容接口(`deepseek-flash`)
- 运行时依赖:除 fastify 外无其他外部依赖
## 项目结构
```text
lpt-ai/src/
├── index.ts → 服务入口(加载 .env,启动 Fastify)
├── routes/ai.ts → AI 路由(health, tasks, fetch-title)
├── llm/
│ ├── client.ts → LLM 客户端(DeepSeek 接口)
│ ├── retry.ts → 退避重试(哪些错误可重试、等多久)
│ ├── prompts.ts → Prompt 模板(3 种任务类型)
│ └── prompts.test.ts
├── task-queue.ts → 异步任务队列(Worker 池 + 幂等复用)
├── task-queue.test.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 池**:并发度由 `LPT_AI_CONCURRENCY` 控制(默认 2)。
不要改回单 worker 串行:N 个请求会等 N × LLM 耗时,客户端会先超时。
- **退避重试**:429 / 5xx / 超时等瞬时抖动会重试(`LPT_AI_MAX_ATTEMPTS`,默认 3),
4xx 客户端错误与「API Key 未配置」不重试。服务端返回的 `Retry-After` 优先于自算退避。
- **相同输入复用**:以 `type + params` 的稳定哈希为幂等键。
- 同键任务 pending/running → 合并为同一个任务,不重复调用 LLM(不重复计费)
- 同键任务已完成且在 `LPT_AI_RESULT_CACHE_MS` 窗口内 → 复用结果
- 同键任务已失败 → 新建(失败必须可重试)
- 请求体传 `force: true` 可跳过复用(用户主动「重新生成」)
- 也可传 `idempotencyKey` 显式指定幂等键
- TTL 清理:按 `LPT_AI_CLEANUP_MS` 周期移除过期记录,同时清理幂等索引。
- 异常隔离:单个任务失败不影响后续任务。
- 管理面板日志:复用 `logStore`,记录最近 200 条请求/响应。
### 不要改动的契约
- `/ai/tasks` **必须固定返回 201**。Java 端 `AiServiceClient.submitTask()` 把非 201 视为提交失败,
所以不能用 200 表达「复用了已有任务」;复用信息放在响应体的 `reused` / `status` 字段里。
- `TaskRecord` 的 `status` / `result` / `error` 字段名被 Java 端轮询逻辑依赖,新增字段可以,改名不行。
## LLM 配置
```env
LLM_API_URL=https://api.deepseek.com/v1/chat/completions
LLM_API_KEY= # 必填,未配置时 /health 返回 llmAvailable: false
LLM_MODEL=deepseek-flash
LLM_TIMEOUT_MS=60000 # 单次 LLM 调用超时
PORT=5199
# 任务队列(完整注释见 .env.example)
LPT_AI_CONCURRENCY=2 # Worker 池并发度
LPT_AI_MAX_ATTEMPTS=3 # 单任务总尝试次数(含首次)
LPT_AI_RETRY_BASE_MS=1000 # 退避首次等待,之后 ×2
LPT_AI_RETRY_MAX_MS=20000 # 单次退避上限
LPT_AI_RESULT_CACHE_MS=600000 # 已完成结果可被相同请求复用的窗口
```
> 部署侧的变量在 `lpt-infra` 的 `dev/`、`prod/` configmap 里;本服务只读环境变量,默认值写在 `src/llm/client.ts` 与 `loadQueueConfig()` 里。
## 降级策略
- 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 # 测试
npm run typecheck # 同时校验 src 与测试文件
```
> `tsconfig.json` 排除 `*.test.ts`(不入打包产物),因此测试的类型检查走单独的 `tsconfig.test.json`;
> 新增测试后靠 `npm run typecheck` 把关,不要只跑 `tsc --noEmit`。
## 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)
```