# 任务队列 - **功能**:定义 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 的升级同步进行。