lpt-ai/AGENTS.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 配置

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 后端是唯一调用方；本服务不直接暴露给前端，不做鉴权（部署在内网）。

启动命令

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)