Files

44 lines
3.4 KiB
Markdown
Raw Permalink 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 异步任务队列(Worker 池、退避重试、相同输入幂等复用、TTL 清理)的行为与不可改契约。
- **何时用**:改动 `/ai/tasks` 的提交/轮询、并发度、重试、幂等复用、TTL 清理、管理面板日志,或调整任务响应契约与单次调用参数(温度 / 思考强度)时。
## 任务队列设计
- 异步任务模式: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` 周期移除过期记录,同时清理幂等索引。
- **单次调用参数**:温度与输出上限按任务类型固定;思考强度(`reasoning_effort`)按 prompt 总字符数自适应,
短输入直接 `none` 关掉思考(DeepSeek 缺省 `high`,不显式指定就会满档思考)。
调用参数不参与幂等键,改阈值不会让已有缓存失效。映射实现在 `src/llm/thinking.ts`。
- 异常隔离:单个任务失败不影响后续任务。
- 管理面板日志:复用 `logStore`,记录最近 200 条请求/响应。
### 不要改动的契约
- `/ai/tasks` **必须固定返回 201**。Java 端 `AiServiceClient.submitTask()` 把非 201 视为提交失败,
所以不能用 200 表达「复用了已有任务」;复用信息放在响应体的 `reused` / `status` 字段里。
- `TaskRecord` 的 `status` / `result` / `error` 字段名被 Java 端轮询逻辑依赖,新增字段可以,改名不行。
### 跨分支契约差异(`dev` 与 `master` 配对不同的 lpt-be)
**分支即契约版本**:`dev` 配 lpt-be `dev`,`master` 配 lpt-be `master`。
下面两处是本仓库历史上唯一让旧版 lpt-be 静默降级的地方,改动前必须确认对应分支的 lpt-be 能读新形状。
| 能力 | `dev`(新 lpt-be) | `master`(旧 lpt-be) | 旧端读不到时的表现 |
|---|---|---|---|
| `aggregate-report` 结果 | `{sessionSummary, expectationVerdict, freeSummary, model}` | `{report: "<纯文本>", model}` | 旧 be 读 `result.report` 得 null → 降级为内置按序拼接,界面无报错 |
| `generate-mind-map` 的 `reports` 入参 | 对象数组 `{ref, taskName, sessionSummary, expectationVerdict, freeSummary}` | `string[]`(纯报告正文) | 新提示词把字符串渲染成 `[报告 undefined]`,报告正文被丢弃 |
- `compare-recall` 的入参(`taskName` / `standardOutline` / `recallOutline`)与结果 JSON 字段两侧一致,可放心改提示词但不要改字段名。
- 从 `dev` 合并到 `master`(= 上生产)时必须与 lpt-be 的升级同步进行。