diff --git a/README.md b/README.md index e47f41e..bae317e 100644 --- a/README.md +++ b/README.md @@ -7,8 +7,10 @@ LPT 学习进度跟踪系统的独立 AI 服务。将 LLM 相关能力从 Java | 端点 | 方法 | 说明 | |------|------|------| | `/health` | GET | 健康检查,返回 LLM 可用状态 | -| `/ai/aggregate-report` | POST | 将学习残片聚合为学习报告 | -| `/ai/generate-mind-map` | POST | 从报告/残片生成思维导图大纲 | +| `/ai/tasks` | POST | 提交异步 AI 任务(聚合报告/生成导图/回忆对比) | +| `/ai/tasks/:taskId` | GET | 轮询任务状态和结果 | +| `/fetch-title` | GET | 抓取 URL 页面标题 | +| `/admin` | GET | 管理面板(任务日志、Prompt 调试) | ## 快速开始 @@ -21,21 +23,71 @@ npm run dev 未配置 `LLM_API_KEY` 时服务可启动,但 AI 端点返回 503,由调用方(Java 后端)降级到内置规则。 -## 请求示例 +## 异步任务架构 + +由于 LLM 调用耗时长(可达数十秒),所有 AI 任务采用异步模式: + +### 1. 提交任务 ```bash -curl -X POST http://localhost:5199/ai/aggregate-report \ +curl -X POST http://localhost:5199/ai/tasks \ -H "Content-Type: application/json" \ -d '{ - "taskName": "Java 并发编程", - "expectation": "理解线程池核心参数", - "fragments": [ - {"content": "corePoolSize 是核心线程数,即使空闲也不回收"}, - {"content": "workQueue 满了之后才会创建超过 core 的线程"} - ] + "type": "aggregate-report", + "params": { + "taskName": "Java 并发编程", + "expectation": "理解线程池核心参数", + "fragments": [ + {"content": "corePoolSize 是核心线程数,即使空闲也不回收"}, + {"content": "workQueue 满了之后才会创建超过 core 的线程"} + ] + } }' ``` +响应: +```json +{ + "taskId": "550e8400-e29b-41d4-a716-446655440000", + "status": "pending" +} +``` + +### 2. 轮询结果 + +```bash +curl http://localhost:5199/ai/tasks/550e8400-e29b-41d4-a716-446655440000 +``` + +响应(进行中): +```json +{ + "taskId": "550e8400-e29b-41d4-a716-446655440000", + "status": "running", + "progress": 50 +} +``` + +响应(完成): +```json +{ + "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` | + ## 架构位置 ``` @@ -44,6 +96,37 @@ LPT 前端 (Vue) ──► LPT 后端 (Java/Spring Boot) ──► lpt-ai (TS/Fa Java 后端是唯一调用方;本服务不直接暴露给前端,不做鉴权(部署在内网)。 +## 任务队列机制 + +- 任务提交后进入内存队列,返回 taskId +- 后台异步执行,Java 端通过轮询获取结果 +- 任务超时时间:5 分钟 +- 任务结果保留时间:30 分钟(自动清理) +- 失败重试:无(由 Java 端决定是否重试或降级) + +## 降级策略 + +``` +AI 服务不可用 + ↓ +Java 后端捕获 503/超时 + ↓ +自动切换到内置生成器 + ↓ +- 聚合报告:简单拼接残片 +- 生成导图:按 session 分组 + 规则去重 +- 回忆对比:字符串相似度匹配 +``` + +确保系统在 AI 服务异常时仍可正常工作。 + +## 管理面板 + +访问 `http://localhost:5199/admin` 查看: +- 任务执行日志(状态、耗时、token 消耗) +- Prompt 模板预览与调试 +- 队列状态监控 + ## 后续规划 - 输入内容安全过滤(Prompt 注入防护)