docs: 规则分离到 roles 目录

This commit is contained in:
2026-10-10 15:08:45 +08:00
parent a70625267d
commit 09d16dfb98
3 changed files with 59 additions and 47 deletions
+27
View File
@@ -0,0 +1,27 @@
# 任务队列
- **功能**:定义 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` 周期移除过期记录,同时清理幂等索引。
- 异常隔离:单个任务失败不影响后续任务。
- 管理面板日志:复用 `logStore`,记录最近 200 条请求/响应。
### 不要改动的契约
- `/ai/tasks` **必须固定返回 201**。Java 端 `AiServiceClient.submitTask()` 把非 201 视为提交失败,
所以不能用 200 表达「复用了已有任务」;复用信息放在响应体的 `reused` / `status` 字段里。
- `TaskRecord` 的 `status` / `result` / `error` 字段名被 Java 端轮询逻辑依赖,新增字段可以,改名不行。