lpt-ai/.pi/SYSTEM.md

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）

---

项目结构

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）

---

启动命令

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 前端，不直接调用本服务

调用关系

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