端点	方法	说明
`/health`	GET	健康检查，返回 LLM 可用状态
`/ai/tasks`	POST	提交异步 AI 任务（聚合报告/生成导图/回忆对比）
`/ai/tasks/:taskId`	GET	轮询任务状态和结果
`/fetch-title`	GET	抓取 URL 页面标题
`/admin`	GET	管理面板（任务日志、Prompt 调试）

快速开始

cp .env.example .env
# 编辑 .env，填入 LLM_API_KEY
npm install
npm run dev

未配置 LLM_API_KEY 时服务可启动，但 AI 端点返回 503，由调用方（Java 后端）降级到内置规则。

异步任务架构

由于 LLM 调用耗时长（可达数十秒），所有 AI 任务采用异步模式：

1. 提交任务

curl -X POST http://localhost:5199/ai/tasks \
  -H "Content-Type: application/json" \
  -d '{
    "type": "aggregate-report",
    "params": {
      "taskName": "Java 并发编程",
      "expectation": "理解线程池核心参数",
      "fragments": [
        {"content": "corePoolSize 是核心线程数，即使空闲也不回收"},
        {"content": "workQueue 满了之后才会创建超过 core 的线程"}
      ]
    }
  }'

响应：

{
  "taskId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "pending"
}

2. 轮询结果

curl http://localhost:5199/ai/tasks/550e8400-e29b-41d4-a716-446655440000

响应（进行中）：

{
  "taskId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "running",
  "progress": 50
}

响应（完成）：

{
  "taskId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "result": {
    "summary": "本次学习主要掌握了线程池的核心参数配置...",
    "keyPoints": ["corePoolSize 核心线程数", "workQueue 工作队列"]
  }
}

3. 支持的任务类型

type	说明	params 字段
`aggregate-report`	聚合学习残片为报告	`taskName`, `expectation`, `fragments[]`
`generate-mind-map`	生成思维导图大纲	`taskName`, `reports[]`, `fragments[]`, `applications[]`
`compare-recall`	对比用户回忆与标准导图	`taskName`, `standardOutline`, `recallOutline`

架构位置

LPT 前端 (Vue) ──► LPT 后端 (Java/Spring Boot) ──► lpt-ai (TS/Fastify) ──► SiliconFlow API

Java 后端是唯一调用方；本服务不直接暴露给前端，不做鉴权（部署在内网）。

任务队列机制

任务提交后进入内存队列，返回 taskId
后台异步执行，Java 端通过轮询获取结果
任务超时时间：5 分钟
任务结果保留时间：30 分钟（自动清理）
失败重试：无（由 Java 端决定是否重试或降级）

降级策略

AI 服务不可用
    ↓
Java 后端捕获 503/超时
    ↓
自动切换到内置生成器
    ↓
- 聚合报告：简单拼接残片
- 生成导图：按 session 分组 + 规则去重
- 回忆对比：字符串相似度匹配

确保系统在 AI 服务异常时仍可正常工作。

管理面板

访问 http://localhost:5199/admin 查看：

任务执行日志（状态、耗时、token 消耗）
Prompt 模板预览与调试
队列状态监控

后续规划

输入内容安全过滤（Prompt 注入防护）
输出审核
多模型路由（按任务复杂度选择模型）
用量与成本监控
SSE 流式输出