From bf56c2bd464a8b0ad7007eb54e3edde36caecbae Mon Sep 17 00:00:00 2001 From: cat Date: Thu, 8 Oct 2026 17:31:09 +0800 Subject: [PATCH] =?UTF-8?q?feat:=20=E4=BB=BB=E5=8A=A1=E9=98=9F=E5=88=97?= =?UTF-8?q?=E6=94=B9=E4=B8=BA=E5=B9=B6=E5=8F=91=E6=B1=A0=E5=B9=B6=E6=94=AF?= =?UTF-8?q?=E6=8C=81=E5=B9=82=E7=AD=89=E5=A4=8D=E7=94=A8=E4=B8=8E=E9=80=80?= =?UTF-8?q?=E9=81=BF=E9=87=8D=E8=AF=95?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .env.example | 24 +- AGENTS.md | 42 +++- package.json | 4 +- src/llm/client.ts | 37 ++- src/llm/retry.test.ts | 196 ++++++++++++++++ src/llm/retry.ts | 124 +++++++++++ src/routes/ai.ts | 25 ++- src/task-queue.test.ts | 496 +++++++++++++++++++++++++++++++++++++++++ src/task-queue.ts | 463 +++++++++++++++++++++++++++++--------- tsconfig.test.json | 8 + 10 files changed, 1296 insertions(+), 123 deletions(-) create mode 100644 src/llm/retry.test.ts create mode 100644 src/llm/retry.ts create mode 100644 src/task-queue.test.ts create mode 100644 tsconfig.test.json diff --git a/.env.example b/.env.example index 6e1d1b7..bc05472 100644 --- a/.env.example +++ b/.env.example @@ -1,11 +1,27 @@ -# LLM 提供商配置(SiliconFlow OpenAI 兼容接口) -LLM_API_URL=https://api.siliconflow.cn/v1/chat/completions +# LLM 提供商配置(DeepSeek OpenAI 兼容接口) +LLM_API_URL=https://api.deepseek.com/v1/chat/completions # API Key(必填,未配置时服务返回 503) LLM_API_KEY= -# 模型名(32B 级别即可满足残片聚合需求) -LLM_MODEL=Qwen/Qwen2.5-32B-Instruct +# 模型名(轻量快速即可满足残片聚合需求) +LLM_MODEL=deepseek-flash # 请求超时(毫秒) LLM_TIMEOUT_MS=60000 # 服务端口 PORT=5199 + +# ---- 任务队列 ---- +# 并发处理的任务数。设得越高吞吐越高,但要注意 LLM 服务商的限流配额 +LPT_AI_CONCURRENCY=2 +# 单个任务的总尝试次数(含首次);1 表示不重试 +LPT_AI_MAX_ATTEMPTS=3 +# 退避重试的首次等待(毫秒),之后按 2 倍增长 +LPT_AI_RETRY_BASE_MS=1000 +# 单次退避上限(毫秒) +LPT_AI_RETRY_MAX_MS=20000 +# 完成记录的保留时长(毫秒) +LPT_AI_TTL_MS=3600000 +# 已完成结果可被相同请求复用的时间窗口(毫秒) +LPT_AI_RESULT_CACHE_MS=600000 +# 过期记录清理间隔(毫秒) +LPT_AI_CLEANUP_MS=300000 diff --git a/AGENTS.md b/AGENTS.md index 9e0b54e..7deeb7f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,6 +1,6 @@ # LPT AI 服务(lpt-ai) -> TypeScript + Fastify 独立 AI 服务,集成 SiliconFlow LLM,为后端提供异步 AI 任务。 +> TypeScript + Fastify 独立 AI 服务,集成 DeepSeek LLM,为后端提供异步 AI 任务。 ## Git 提交规范 @@ -11,7 +11,7 @@ - 运行时:Node.js 20+ - 框架:Fastify 5 -- LLM:DeepSeek OpenAI 兼容接口(deepseek-flash / DeepSeek-V4.1-Flash) +- LLM:DeepSeek OpenAI 兼容接口(`deepseek-flash`) - 运行时依赖:除 fastify 外无其他外部依赖 ## 项目结构 @@ -21,10 +21,12 @@ lpt-ai/src/ ├── index.ts → 服务入口(加载 .env,启动 Fastify) ├── routes/ai.ts → AI 路由(health, tasks, fetch-title) ├── llm/ -│ ├── client.ts → LLM 客户端(SiliconFlow 接口) +│ ├── client.ts → LLM 客户端(DeepSeek 接口) +│ ├── retry.ts → 退避重试(哪些错误可重试、等多久) │ ├── prompts.ts → Prompt 模板(3 种任务类型) │ └── prompts.test.ts -├── task-queue.ts → 异步任务队列 +├── task-queue.ts → 异步任务队列(Worker 池 + 幂等复用) +├── task-queue.test.ts └── admin/ ├── index.ts → 管理面板路由 ├── routes.ts @@ -52,11 +54,26 @@ lpt-ai/src/ ## 任务队列设计 - 异步任务模式:submit + poll,避免 LLM 长耗时(10-60s)超时。 -- 单线程 Worker:`setImmediate` 链,同一时刻只处理一个 LLM 调用,防止 API 限流。 -- TTL 清理:5 分钟一次,移除完成超过 1 小时的记录。 +- **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 端轮询逻辑依赖,新增字段可以,改名不行。 + ## LLM 配置 ```env @@ -65,8 +82,17 @@ LLM_API_KEY= # 必填,未配置时 /health 返回 llmAvaila LLM_MODEL=deepseek-flash LLM_TIMEOUT_MS=60000 # 单次 LLM 调用超时 PORT=5199 + +# 任务队列(完整注释见 .env.example) +LPT_AI_CONCURRENCY=2 # Worker 池并发度 +LPT_AI_MAX_ATTEMPTS=3 # 单任务总尝试次数(含首次) +LPT_AI_RETRY_BASE_MS=1000 # 退避首次等待,之后 ×2 +LPT_AI_RETRY_MAX_MS=20000 # 单次退避上限 +LPT_AI_RESULT_CACHE_MS=600000 # 已完成结果可被相同请求复用的窗口 ``` +> 部署侧的变量在 `lpt-infra` 的 `dev/`、`prod/` configmap 里;本服务只读环境变量,默认值写在 `src/llm/client.ts` 与 `loadQueueConfig()` 里。 + ## 降级策略 - LLM API Key 未配置 → `/health` 返回 `llmAvailable: false`。 @@ -81,8 +107,12 @@ npm run dev # 开发模式(tsx watch,热重载) npm run build # 编译 TypeScript npm run start # 生产模式 npm run test # 测试 +npm run typecheck # 同时校验 src 与测试文件 ``` +> `tsconfig.json` 排除 `*.test.ts`(不入打包产物),因此测试的类型检查走单独的 `tsconfig.test.json`; +> 新增测试后靠 `npm run typecheck` 把关,不要只跑 `tsc --noEmit`。 + ## Docker - 多阶段构建:`node:20-alpine` 编译 → `node:20-alpine` 运行。 diff --git a/package.json b/package.json index 4e9d215..aaa2209 100644 --- a/package.json +++ b/package.json @@ -9,7 +9,7 @@ "build": "tsc", "start": "node --env-file=.env dist/index.js", "test": "vitest run", - "typecheck": "tsc --noEmit" + "typecheck": "tsc --noEmit && tsc -p tsconfig.test.json" }, "dependencies": { "fastify": "^5.2.0" @@ -23,4 +23,4 @@ "engines": { "node": ">=20" } -} +} \ No newline at end of file diff --git a/src/llm/client.ts b/src/llm/client.ts index cd3122e..1501fe3 100644 --- a/src/llm/client.ts +++ b/src/llm/client.ts @@ -36,11 +36,40 @@ export class LlmError extends Error { constructor( message: string, public readonly statusCode: number, + /** + * 服务端给出的建议重试等待(毫秒)。 + * + * 来自 429/503 的 `Retry-After` 头;有值时退避重试应优先采用它, + * 而不是用自己的指数退避——服务商限流时自己的退避往往偏短。 + */ + public readonly retryAfterMs?: number, ) { super(message); + this.name = "LlmError"; } } +/** + * 解析 `Retry-After` 头。 + * + * 规范允许秒数或 HTTP 日期两种形式,两种都支持;解析不出来时返回 undefined。 + */ +export function parseRetryAfter(value: string | null, now: number = Date.now()): number | undefined { + if (!value) return undefined; + const trimmed = value.trim(); + if (trimmed.length === 0) return undefined; + + // 纯数字:秒 + if (/^\d+$/.test(trimmed)) { + return Number(trimmed) * 1000; + } + + // HTTP 日期 + const at = Date.parse(trimmed); + if (Number.isNaN(at)) return undefined; + return Math.max(0, at - now); +} + /** * 非流式调用,返回完整文本 */ @@ -75,7 +104,13 @@ export async function chat( if (!response.ok) { const body = await response.text().catch(() => ""); - throw new LlmError(`LLM 请求失败 (${response.status}): ${body.slice(0, 200)}`, 502); + const retryAfterMs = parseRetryAfter(response.headers.get("retry-after")); + // 保留上游真实状态码:重试策略靠它区分 429/5xx(可重试)与 4xx(不可重试) + throw new LlmError( + `LLM 请求失败 (${response.status}): ${body.slice(0, 200)}`, + response.status, + retryAfterMs, + ); } const data = (await response.json()) as { diff --git a/src/llm/retry.test.ts b/src/llm/retry.test.ts new file mode 100644 index 0000000..4ee36a5 --- /dev/null +++ b/src/llm/retry.test.ts @@ -0,0 +1,196 @@ +import { describe, expect, it } from "vitest"; +import { LlmError, parseRetryAfter } from "./client.js"; +import { computeBackoffMs, isRetryableLlmError, withRetry } from "./retry.js"; + +describe("parseRetryAfter", () => { + it("解析秒数形式", () => { + expect(parseRetryAfter("5")).toBe(5000); + expect(parseRetryAfter("0")).toBe(0); + }); + + it("解析 HTTP 日期形式", () => { + const now = Date.parse("2026-10-08T10:00:00Z"); + expect(parseRetryAfter("Thu, 08 Oct 2026 10:00:03 GMT", now)).toBe(3000); + }); + + it("空值与非法值返回 undefined", () => { + expect(parseRetryAfter(null)).toBeUndefined(); + expect(parseRetryAfter("")).toBeUndefined(); + expect(parseRetryAfter(" ")).toBeUndefined(); + expect(parseRetryAfter("soon")).toBeUndefined(); + }); + + it("已过期的日期不会返回负数", () => { + const now = Date.parse("2026-10-08T10:00:10Z"); + expect(parseRetryAfter("Thu, 08 Oct 2026 10:00:00 GMT", now)).toBe(0); + }); +}); + +describe("isRetryableLlmError", () => { + it("限流与服务端错误可重试", () => { + for (const status of [408, 429, 500, 502, 503, 504]) { + expect(isRetryableLlmError(new LlmError("x", status))).toBe(true); + } + }); + + it("客户端错误不重试", () => { + for (const status of [400, 401, 403, 404, 422]) { + expect(isRetryableLlmError(new LlmError("x", status))).toBe(false); + } + }); + + it("未配置 API Key 不重试(重试也不会成功)", () => { + expect(isRetryableLlmError(new LlmError("LLM API Key 未配置", 503))).toBe(false); + }); + + it("非 LlmError 不重试", () => { + expect(isRetryableLlmError(new Error("boom"))).toBe(false); + expect(isRetryableLlmError("boom")).toBe(false); + expect(isRetryableLlmError(undefined)).toBe(false); + }); +}); + +describe("computeBackoffMs", () => { + const base = { baseDelayMs: 1000, maxDelayMs: 20000, factor: 2, jitterRatio: 0 }; + + it("按指数增长", () => { + expect(computeBackoffMs(1, base)).toBe(1000); + expect(computeBackoffMs(2, base)).toBe(2000); + expect(computeBackoffMs(3, base)).toBe(4000); + }); + + it("受上限约束", () => { + expect(computeBackoffMs(10, base)).toBe(20000); + }); + + it("服务端给的建议等待优先于指数退避", () => { + expect(computeBackoffMs(1, base, 7000)).toBe(7000); + }); + + it("服务端建议同样受上限约束", () => { + expect(computeBackoffMs(1, base, 999999)).toBe(20000); + }); + + it("抖动落在 ±比例范围内且不为负", () => { + const jittered = { ...base, jitterRatio: 0.2 }; + // random()=0 → 减满抖动;random()=1 → 加满抖动 + expect(computeBackoffMs(1, jittered, undefined, () => 0)).toBe(800); + expect(computeBackoffMs(1, jittered, undefined, () => 1)).toBe(1200); + expect(computeBackoffMs(1, jittered, undefined, () => 0.5)).toBe(1000); + }); +}); + +describe("withRetry", () => { + const noSleep = async (): Promise => {}; + + it("首次成功不重试", async () => { + let calls = 0; + const result = await withRetry( + async () => { + calls += 1; + return "ok"; + }, + { maxAttempts: 3, baseDelayMs: 1, maxDelayMs: 10, sleep: noSleep }, + ); + expect(result).toBe("ok"); + expect(calls).toBe(1); + }); + + it("可重试错误会重试直到成功", async () => { + let calls = 0; + const result = await withRetry( + async () => { + calls += 1; + if (calls < 3) throw new LlmError("限流了", 429); + return "ok"; + }, + { maxAttempts: 5, baseDelayMs: 1, maxDelayMs: 10, sleep: noSleep }, + ); + expect(result).toBe("ok"); + expect(calls).toBe(3); + }); + + it("不可重试错误立即抛出,不浪费重试", async () => { + let calls = 0; + await expect( + withRetry( + async () => { + calls += 1; + throw new LlmError("参数错误", 400); + }, + { maxAttempts: 5, baseDelayMs: 1, maxDelayMs: 10, sleep: noSleep }, + ), + ).rejects.toThrow("参数错误"); + expect(calls).toBe(1); + }); + + it("重试次数用尽后抛出最后一次的错误", async () => { + let calls = 0; + await expect( + withRetry( + async () => { + calls += 1; + throw new LlmError(`第 ${calls} 次`, 503); + }, + { maxAttempts: 3, baseDelayMs: 1, maxDelayMs: 10, sleep: noSleep }, + ), + ).rejects.toThrow("第 3 次"); + expect(calls).toBe(3); + }); + + it("maxAttempts 为 1 时等价于不重试", async () => { + let calls = 0; + await expect( + withRetry( + async () => { + calls += 1; + throw new LlmError("x", 503); + }, + { maxAttempts: 1, baseDelayMs: 1, maxDelayMs: 10, sleep: noSleep }, + ), + ).rejects.toThrow(); + expect(calls).toBe(1); + }); + + it("每次重试前回调,带上尝试序号与等待时长", async () => { + const seen: Array<{ attempt: number; delayMs: number }> = []; + await expect( + withRetry( + async () => { + throw new LlmError("x", 503); + }, + { + maxAttempts: 3, + baseDelayMs: 100, + maxDelayMs: 10_000, + jitterRatio: 0, + sleep: noSleep, + onRetry: (info) => seen.push({ attempt: info.attempt, delayMs: info.delayMs }), + }, + ), + ).rejects.toThrow(); + expect(seen).toEqual([ + { attempt: 1, delayMs: 100 }, + { attempt: 2, delayMs: 200 }, + ]); + }); + + it("服务端 Retry-After 会覆盖指数退避的等待时长", async () => { + const delays: number[] = []; + await expect( + withRetry( + async () => { + throw new LlmError("限流", 429, 5000); + }, + { + maxAttempts: 2, + baseDelayMs: 10, + maxDelayMs: 10_000, + sleep: noSleep, + onRetry: (info) => delays.push(info.delayMs), + }, + ), + ).rejects.toThrow(); + expect(delays).toEqual([5000]); + }); +}); diff --git a/src/llm/retry.ts b/src/llm/retry.ts new file mode 100644 index 0000000..bfc5079 --- /dev/null +++ b/src/llm/retry.ts @@ -0,0 +1,124 @@ +/** + * LLM 调用的退避重试。 + * + * 背景:LLM 服务商的 429(限流)与 5xx(瞬时故障)是常态抖动, + * 把它们当成永久失败会让用户看到「AI 失败」而实际上只是被限流了一下。 + * 本模块只负责「哪些错误值得重试」与「等多久再试」,不关心任务队列。 + */ + +import { LlmError } from "./client.js"; + +/** 默认值得重试的上游状态码 */ +const RETRYABLE_STATUS = new Set([ + 408, // 请求超时 + 425, // Too Early + 429, // 限流 + 500, // 上游内部错误 + 502, // 网关错误 + 503, // 服务不可用 + 504, // 网关超时 +]); + +/** + * 判断一个错误是否值得重试。 + * + * 原则:只有「重试可能成功」的错误才重试。 + * - 429 / 5xx / 网络异常 / 超时 → 可重试 + * - 400 / 401 / 403 / 404 等客户端错误 → 不可重试(重试多少次都一样) + * - 未配置 API Key(503 但属配置问题)→ 不可重试 + */ +export function isRetryableLlmError(error: unknown): boolean { + if (!(error instanceof LlmError)) { + // 非 LlmError 的异常(例如 JSON 解析失败)不重试,避免无限循环 + return false; + } + if (error.message.includes("API Key 未配置")) { + return false; + } + // 超时统一为 504,属于可重试 + return RETRYABLE_STATUS.has(error.statusCode); +} + +export interface RetryOptions { + /** 总尝试次数(含首次)。<=1 表示不重试 */ + maxAttempts: number; + /** 首次退避基准(毫秒),之后按倍数增长 */ + baseDelayMs: number; + /** 单次退避上限(毫秒) */ + maxDelayMs: number; + /** 指数倍数,默认 2 */ + factor?: number; + /** 抖动比例 0~1,默认 0.2,避免多个任务同时重试造成共振 */ + jitterRatio?: number; + /** 判断是否重试,默认 isRetryableLlmError */ + isRetryable?: (error: unknown) => boolean; + /** 注入以便测试 */ + sleep?: (ms: number) => Promise; + /** 注入以便测试 */ + random?: () => number; + /** 每次重试前的回调,用于日志 */ + onRetry?: (info: { attempt: number; delayMs: number; error: unknown }) => void; +} + +const defaultSleep = (ms: number): Promise => + new Promise((resolve) => { + setTimeout(resolve, ms); + }); + +/** + * 计算第 attempt 次重试(attempt 从 1 开始)应等待的毫秒数。 + * + * 优先采用服务端给的 `Retry-After`,否则用指数退避 + 抖动,并受 maxDelayMs 限制。 + */ +export function computeBackoffMs( + attempt: number, + options: Pick, + serverHintMs?: number, + random: () => number = Math.random, +): number { + const factor = options.factor ?? 2; + const jitterRatio = options.jitterRatio ?? 0.2; + const base = Math.min(options.baseDelayMs * factor ** (attempt - 1), options.maxDelayMs); + + // 服务端明确要求等待时以它为准(同样受上限约束),此时不再叠加抖动 + if (serverHintMs !== undefined && serverHintMs >= 0) { + return Math.min(serverHintMs, options.maxDelayMs); + } + + const jitter = base * jitterRatio * (random() * 2 - 1); + return Math.max(0, Math.round(Math.min(base + jitter, options.maxDelayMs))); +} + +/** + * 执行 fn,失败且可重试时按退避策略重试。 + * + * 最后一次失败会原样抛出,调用方据此判断任务最终状态。 + */ +export async function withRetry( + fn: () => Promise, + options: RetryOptions, +): Promise { + const isRetryable = options.isRetryable ?? isRetryableLlmError; + const sleep = options.sleep ?? defaultSleep; + const random = options.random ?? Math.random; + const attempts = Math.max(1, Math.floor(options.maxAttempts)); + + let lastError: unknown; + for (let attempt = 1; attempt <= attempts; attempt += 1) { + try { + return await fn(); + } catch (error) { + lastError = error; + const isLast = attempt >= attempts; + if (isLast || !isRetryable(error)) { + throw error; + } + const serverHint = error instanceof LlmError ? error.retryAfterMs : undefined; + const delayMs = computeBackoffMs(attempt, options, serverHint, random); + options.onRetry?.({ attempt, delayMs, error }); + await sleep(delayMs); + } + } + // 理论不可达:循环内要么返回要么抛出 + throw lastError; +} diff --git a/src/routes/ai.ts b/src/routes/ai.ts index bbef803..3e6032b 100644 --- a/src/routes/ai.ts +++ b/src/routes/ai.ts @@ -17,8 +17,17 @@ export async function aiRoutes(app: FastifyInstance): Promise { })); /** 提交 AI 任务,立即返回 taskId */ - app.post<{ Body: { type: string; params: Record } }>("/ai/tasks", async (request, reply) => { - const { type, params } = request.body ?? {}; + app.post<{ + Body: { + type: string; + params: Record; + /** 可选:显式幂等键,用于跨请求去重 */ + idempotencyKey?: string; + /** 可选:跳过结果复用,强制重新生成 */ + force?: boolean; + }; + }>("/ai/tasks", async (request, reply) => { + const { type, params, idempotencyKey, force } = request.body ?? {}; if (!type || !["aggregate-report", "generate-mind-map", "compare-recall"].includes(type)) { return reply.status(400).send({ error: "无效的 type,允许: aggregate-report, generate-mind-map, compare-recall" }); @@ -27,8 +36,16 @@ export async function aiRoutes(app: FastifyInstance): Promise { return reply.status(400).send({ error: "params 必须为非空对象" }); } - const taskId = createTask(type as TaskType, params as Record); - return reply.status(201).send({ taskId }); + const created = createTask(type as TaskType, params as Record, { + ...(typeof idempotencyKey === "string" && idempotencyKey.trim().length > 0 + ? { idempotencyKey } + : {}), + ...(force === true ? { force: true } : {}), + }); + + // 固定返回 201:Java 端 AiServiceClient 把非 201 当作提交失败, + // 所以不能改用 200 表达「复用」。复用信息放在响应体里。 + return reply.status(201).send(created); }); /** 查询任务状态与结果 */ diff --git a/src/task-queue.test.ts b/src/task-queue.test.ts new file mode 100644 index 0000000..aa040f7 --- /dev/null +++ b/src/task-queue.test.ts @@ -0,0 +1,496 @@ +import { describe, expect, it } from "vitest"; +import { LlmError } from "./llm/client.js"; +import { TaskQueue, computeTaskKey, loadQueueConfig, type QueueConfig, type TaskRecord } from "./task-queue.js"; + +/** 测试用队列:不碰真实 LLM、不写管理面板日志、不启定时器 */ +function makeQueue( + overrides: Partial = {}, + runOnce?: (task: TaskRecord) => Promise, +): TaskQueue { + return new TaskQueue({ + config: { + concurrency: 2, + maxAttempts: 3, + retryBaseMs: 1, + retryMaxMs: 10, + ttlMs: 60_000, + cleanupIntervalMs: 60_000, + resultCacheMs: 10_000, + ...overrides, + }, + enableCleanup: false, + isLlmAvailable: () => true, + sleep: async () => {}, + onSettled: () => {}, + ...(runOnce ? { runOnce: async (task) => runOnce(task) } : {}), + }); +} + +function ok(params: Record = { taskName: "t", fragments: [] }) { + return params; +} + +describe("loadQueueConfig", () => { + it("缺省值可用", () => { + const config = loadQueueConfig({}); + expect(config.concurrency).toBe(2); + expect(config.maxAttempts).toBe(3); + expect(config.resultCacheMs).toBe(600_000); + }); + + it("环境变量可覆盖", () => { + const config = loadQueueConfig({ + LPT_AI_CONCURRENCY: "5", + LPT_AI_MAX_ATTEMPTS: "7", + LPT_AI_RETRY_BASE_MS: "250", + }); + expect(config.concurrency).toBe(5); + expect(config.maxAttempts).toBe(7); + expect(config.retryBaseMs).toBe(250); + }); + + it("非法值回退到缺省", () => { + const config = loadQueueConfig({ LPT_AI_CONCURRENCY: "-1", LPT_AI_MAX_ATTEMPTS: "abc" }); + expect(config.concurrency).toBe(2); + expect(config.maxAttempts).toBe(3); + }); +}); + +describe("computeTaskKey", () => { + it("同输入得到同键", () => { + const a = computeTaskKey("aggregate-report", { taskName: "t", fragments: [{ content: "x" }] }); + const b = computeTaskKey("aggregate-report", { taskName: "t", fragments: [{ content: "x" }] }); + expect(a).toBe(b); + }); + + it("对象键顺序不影响结果", () => { + const a = computeTaskKey("compare-recall", { taskName: "t", standardOutline: "s" }); + const b = computeTaskKey("compare-recall", { standardOutline: "s", taskName: "t" }); + expect(a).toBe(b); + }); + + it("参数不同则键不同", () => { + const a = computeTaskKey("aggregate-report", { taskName: "t", fragments: [{ content: "x" }] }); + const b = computeTaskKey("aggregate-report", { taskName: "t", fragments: [{ content: "y" }] }); + expect(a).not.toBe(b); + }); + + it("类型不同则键不同", () => { + const a = computeTaskKey("aggregate-report", { taskName: "t" }); + const b = computeTaskKey("generate-mind-map", { taskName: "t" }); + expect(a).not.toBe(b); + }); +}); + +describe("TaskQueue 并发", () => { + it("并发度内的任务同时执行,不再串行", async () => { + let inFlight = 0; + let maxInFlight = 0; + const started: string[] = []; + + const queue = makeQueue({ concurrency: 3 }, async (task) => { + inFlight += 1; + maxInFlight = Math.max(maxInFlight, inFlight); + started.push(task.id); + await new Promise((resolve) => setTimeout(resolve, 20)); + inFlight -= 1; + return { ok: true }; + }); + + for (let i = 0; i < 3; i += 1) { + queue.create("aggregate-report", { taskName: `t${i}`, fragments: [{ content: `c${i}` }] }); + } + await queue.drain(); + + // 三个任务应同时在跑,而不是一个个来 + expect(maxInFlight).toBe(3); + expect(started).toHaveLength(3); + queue.stop(); + }); + + it("超出并发度的任务排队等待", async () => { + let inFlight = 0; + let maxInFlight = 0; + + const queue = makeQueue({ concurrency: 2 }, async () => { + inFlight += 1; + maxInFlight = Math.max(maxInFlight, inFlight); + await new Promise((resolve) => setTimeout(resolve, 15)); + inFlight -= 1; + return { ok: true }; + }); + + for (let i = 0; i < 6; i += 1) { + queue.create("aggregate-report", { taskName: `t${i}`, fragments: [{ content: `c${i}` }] }); + } + await queue.drain(); + + expect(maxInFlight).toBe(2); + queue.stop(); + }); + + it("并发 N 个任务的总耗时明显小于串行累加", async () => { + const perTaskMs = 30; + const n = 6; + + const queue = makeQueue({ concurrency: n }, async () => { + await new Promise((resolve) => setTimeout(resolve, perTaskMs)); + return { ok: true }; + }); + + const t0 = Date.now(); + for (let i = 0; i < n; i += 1) { + queue.create("aggregate-report", { taskName: `t${i}`, fragments: [{ content: `c${i}` }] }); + } + await queue.drain(); + const elapsed = Date.now() - t0; + + // 串行需要 n * perTaskMs;并发后应接近单次耗时 + expect(elapsed).toBeLessThan(perTaskMs * n * 0.6); + queue.stop(); + }); + + it("drain 在队列空闲时立即返回", async () => { + const queue = makeQueue(); + await queue.drain(); + expect(queue.pendingCount).toBe(0); + queue.stop(); + }); +}); + +describe("TaskQueue 相同输入复用", () => { + it("进行中的相同请求被合并,不重复执行", async () => { + let calls = 0; + const queue = makeQueue({ concurrency: 1 }, async () => { + calls += 1; + await new Promise((resolve) => setTimeout(resolve, 20)); + return { ok: true }; + }); + + const params = { taskName: "t", fragments: [{ content: "same" }] }; + const first = queue.create("aggregate-report", params); + const second = queue.create("aggregate-report", params); + + expect(second.taskId).toBe(first.taskId); + expect(second.reused).toBe(true); + expect(second.status).toBe("pending"); + + await queue.drain(); + expect(calls).toBe(1); + queue.stop(); + }); + + it("参数不同则各自新建", async () => { + const queue = makeQueue({}, async () => ({ ok: true })); + const a = queue.create("aggregate-report", { taskName: "t", fragments: [{ content: "a" }] }); + const b = queue.create("aggregate-report", { taskName: "t", fragments: [{ content: "b" }] }); + expect(a.taskId).not.toBe(b.taskId); + expect(b.reused).toBe(false); + await queue.drain(); + queue.stop(); + }); + + it("已完成且在窗口内的结果被复用", async () => { + let calls = 0; + const queue = makeQueue({}, async () => { + calls += 1; + return { value: calls }; + }); + const params = { taskName: "t", fragments: [{ content: "same" }] }; + + const first = queue.create("aggregate-report", params); + await queue.drain(); + + const second = queue.create("aggregate-report", params); + expect(second.taskId).toBe(first.taskId); + expect(second.reused).toBe(true); + expect(second.status).toBe("done"); + expect(calls).toBe(1); + queue.stop(); + }); + + it("超出结果复用窗口后重新执行", async () => { + let nowMs = 1_000_000; + let calls = 0; + const queue = new TaskQueue({ + config: { + concurrency: 1, + maxAttempts: 1, + retryBaseMs: 1, + retryMaxMs: 10, + ttlMs: 10_000_000, + cleanupIntervalMs: 60_000, + resultCacheMs: 5_000, + }, + enableCleanup: false, + isLlmAvailable: () => true, + sleep: async () => {}, + onSettled: () => {}, + now: () => nowMs, + runOnce: async () => { + calls += 1; + return { value: calls }; + }, + }); + + const params = { taskName: "t", fragments: [{ content: "same" }] }; + queue.create("aggregate-report", params); + await queue.drain(); + + nowMs += 10_000; // 超过窗口 + const again = queue.create("aggregate-report", params); + await queue.drain(); + + expect(again.reused).toBe(false); + expect(calls).toBe(2); + queue.stop(); + }); + + it("失败的任务不进入复用,用户能重试", async () => { + let calls = 0; + const queue = makeQueue({ maxAttempts: 1 }, async () => { + calls += 1; + throw new LlmError("上游 400", 400); + }); + const params = { taskName: "t", fragments: [{ content: "same" }] }; + + const first = queue.create("aggregate-report", params); + await queue.drain(); + expect(queue.get(first.taskId)?.status).toBe("failed"); + + const second = queue.create("aggregate-report", params); + await queue.drain(); + expect(second.reused).toBe(false); + expect(calls).toBe(2); + queue.stop(); + }); + + it("force 强制新建,跳过复用", async () => { + let calls = 0; + const queue = makeQueue({}, async () => { + calls += 1; + return { value: calls }; + }); + const params = { taskName: "t", fragments: [{ content: "same" }] }; + + queue.create("aggregate-report", params); + await queue.drain(); + const forced = queue.create("aggregate-report", params, { force: true }); + await queue.drain(); + + expect(forced.reused).toBe(false); + expect(calls).toBe(2); + queue.stop(); + }); + + it("显式幂等键可跨不同参数去重", async () => { + let calls = 0; + const queue = makeQueue({}, async () => { + calls += 1; + return { ok: true }; + }); + + const first = queue.create("aggregate-report", { taskName: "a", fragments: [] }, { idempotencyKey: "k1" }); + const second = queue.create("aggregate-report", { taskName: "b", fragments: [] }, { idempotencyKey: "k1" }); + await queue.drain(); + + expect(second.taskId).toBe(first.taskId); + expect(calls).toBe(1); + queue.stop(); + }); +}); + +describe("TaskQueue 重试", () => { + it("429 抖动后成功,任务最终为 done 而不是 failed", async () => { + let calls = 0; + const queue = makeQueue({ maxAttempts: 3 }, async () => { + calls += 1; + if (calls < 3) throw new LlmError("限流", 429); + return { ok: true }; + }); + + const created = queue.create("aggregate-report", { taskName: "t", fragments: [] }); + await queue.drain(); + + const task = queue.get(created.taskId); + expect(task?.status).toBe("done"); + expect(calls).toBe(3); + expect(task?.attempts).toBe(3); + queue.stop(); + }); + + it("不可重试错误只尝试一次", async () => { + let calls = 0; + const queue = makeQueue({ maxAttempts: 5 }, async () => { + calls += 1; + throw new LlmError("请求体非法", 400); + }); + + const created = queue.create("aggregate-report", { taskName: "t", fragments: [] }); + await queue.drain(); + + expect(queue.get(created.taskId)?.status).toBe("failed"); + expect(calls).toBe(1); + queue.stop(); + }); + + it("重试用尽后为 failed", async () => { + let calls = 0; + const queue = makeQueue({ maxAttempts: 2 }, async () => { + calls += 1; + throw new LlmError("上游挂了", 503); + }); + + const created = queue.create("aggregate-report", { taskName: "t", fragments: [] }); + await queue.drain(); + + const task = queue.get(created.taskId); + expect(task?.status).toBe("failed"); + expect(task?.error).toContain("上游挂了"); + expect(calls).toBe(2); + queue.stop(); + }); + + it("LLM 不可用时直接失败,不空跑重试", async () => { + let calls = 0; + const queue = new TaskQueue({ + config: { + concurrency: 1, + maxAttempts: 3, + retryBaseMs: 1, + retryMaxMs: 10, + ttlMs: 60_000, + cleanupIntervalMs: 60_000, + resultCacheMs: 10_000, + }, + enableCleanup: false, + isLlmAvailable: () => false, + sleep: async () => {}, + onSettled: () => {}, + runOnce: async () => { + calls += 1; + return { ok: true }; + }, + }); + + const created = queue.create("aggregate-report", { taskName: "t", fragments: [] }); + await queue.drain(); + + const task = queue.get(created.taskId); + expect(task?.status).toBe("failed"); + expect(task?.error).toContain("API Key"); + expect(calls).toBe(0); + queue.stop(); + }); +}); + +describe("TaskQueue 清理", () => { + it("只清理过期的完成记录,进行中的不动", async () => { + let nowMs = 1_000_000; + const queue = new TaskQueue({ + config: { + concurrency: 1, + maxAttempts: 1, + retryBaseMs: 1, + retryMaxMs: 10, + ttlMs: 1_000, + cleanupIntervalMs: 60_000, + resultCacheMs: 10, + }, + enableCleanup: false, + isLlmAvailable: () => true, + sleep: async () => {}, + onSettled: () => {}, + now: () => nowMs, + runOnce: async () => ({ ok: true }), + }); + + const created = queue.create("aggregate-report", { taskName: "t", fragments: [] }); + await queue.drain(); + expect(queue.size()).toBe(1); + + nowMs += 5_000; + const removed = queue.cleanup(); + + expect(removed).toBe(1); + expect(queue.size()).toBe(0); + expect(queue.get(created.taskId)).toBeUndefined(); + queue.stop(); + }); + + it("清理后同输入可以重新提交,不会命中已删记录的索引", async () => { + let nowMs = 1_000_000; + let calls = 0; + const queue = new TaskQueue({ + config: { + concurrency: 1, + maxAttempts: 1, + retryBaseMs: 1, + retryMaxMs: 10, + ttlMs: 1_000, + cleanupIntervalMs: 60_000, + resultCacheMs: 10, + }, + enableCleanup: false, + isLlmAvailable: () => true, + sleep: async () => {}, + onSettled: () => {}, + now: () => nowMs, + runOnce: async () => { + calls += 1; + return { value: calls }; + }, + }); + + const params = { taskName: "t", fragments: [{ content: "x" }] }; + queue.create("aggregate-report", params); + await queue.drain(); + + nowMs += 5_000; + queue.cleanup(); + + const again = queue.create("aggregate-report", params); + await queue.drain(); + + expect(again.reused).toBe(false); + expect(calls).toBe(2); + queue.stop(); + }); +}); + +describe("TaskQueue 基本行为", () => { + it("get 返回拷贝,外部修改不影响内部状态", async () => { + const queue = makeQueue({}, async () => ({ ok: true })); + const created = queue.create("aggregate-report", ok()); + await queue.drain(); + + const task = queue.get(created.taskId); + expect(task).toBeDefined(); + if (task) { + task.status = "failed"; + } + expect(queue.get(created.taskId)?.status).toBe("done"); + queue.stop(); + }); + + it("不存在的任务返回 undefined", () => { + const queue = makeQueue(); + expect(queue.get("nope")).toBeUndefined(); + queue.stop(); + }); + + it("任务记录带类型、参数、尝试次数与时间戳", async () => { + const queue = makeQueue({}, async () => ({ ok: true })); + const params = { taskName: "Java 并发", fragments: [{ content: "x" }] }; + const created = queue.create("aggregate-report", params); + await queue.drain(); + + const task = queue.get(created.taskId); + expect(task?.type).toBe("aggregate-report"); + expect(task?.params).toEqual(params); + expect(task?.attempts).toBe(1); + expect(Number.isNaN(Date.parse(task?.createdAt ?? ""))).toBe(false); + expect(Number.isNaN(Date.parse(task?.completedAt ?? ""))).toBe(false); + queue.stop(); + }); +}); diff --git a/src/task-queue.ts b/src/task-queue.ts index fa75060..a8c710d 100644 --- a/src/task-queue.ts +++ b/src/task-queue.ts @@ -1,15 +1,19 @@ /** - * 异步任务队列 —— 接收任务,后台 Worker 顺序处理,提供查询。 + * 异步任务队列 —— 接收任务,后台 Worker 池并发处理,提供查询与幂等复用。 * * 设计要点: - * - 单线程 Worker(setImmediate 链),同一时刻只处理一个 LLM 调用 - * - TTL 清理:5 分钟一次,移除完成超过 1 小时的记录 - * - 异常隔离:单个任务失败不影响后续任务 - * - 日志复用 logStore,与管理面板日志统一 + * - **Worker 池**:并发度可配置。原实现用单个 processing 标志串行, + * N 个请求要等 N × LLM 耗时,客户端很容易先超时。 + * - **退避重试**:429 / 5xx / 超时等瞬时抖动不再直接判失败,见 llm/retry.ts。 + * - **相同输入复用**:同一 type + 同参数的请求会复用同一个任务, + * 避免重复计费;进行中的请求直接合并,已完成的结果在窗口内复用。 + * - **TTL 清理**:定期移除过期的完成记录,同时清理幂等索引。 + * - 依赖以构造参数注入,便于单测;生产使用文件末尾的单例。 */ -import { randomUUID } from "node:crypto"; -import { chat, isAvailable, loadConfig, LlmError } from "./llm/client.js"; +import { randomUUID, createHash } from "node:crypto"; +import { chat, isAvailable, loadConfig, LlmError, type ChatMessage } from "./llm/client.js"; +import { withRetry, isRetryableLlmError, type RetryOptions } from "./llm/retry.js"; import { aggregateReportPrompt, compareRecallPrompt, generateMindMapPrompt } from "./llm/prompts.js"; import { logStore } from "./admin/store.js"; @@ -21,133 +25,379 @@ export type TaskStatus = "pending" | "running" | "done" | "failed"; export interface TaskRecord { id: string; + /** 幂等键:同一 type + 同参数的记录共享同一个键 */ + key: string; type: TaskType; params: Record; status: TaskStatus; result?: unknown; error?: string; + /** 已尝试次数(含首次),便于排查重试情况 */ + attempts: number; createdAt: string; // ISO 8601 startedAt?: string; completedAt?: string; } -// ---- 存储 ---- +export interface CreateTaskOptions { + /** 显式幂等键;不传则由 type + params 计算 */ + idempotencyKey?: string; + /** 跳过复用,强制新建任务(用户主动「重新生成」时用) */ + force?: boolean; +} -const records = new Map(); -const queue: TaskRecord[] = []; -let processing = false; +export interface CreateTaskResult { + taskId: string; + /** true 表示复用了已有任务,调用方不应按「新任务」处理 */ + reused: boolean; + /** 复用的任务当前状态,便于调用方决定返回 200 还是 201 */ + status: TaskStatus; +} -// ---- 公开 API ---- +export interface QueueConfig { + /** 并发处理的任务数 */ + concurrency: number; + /** 单任务总尝试次数(含首次) */ + maxAttempts: number; + retryBaseMs: number; + retryMaxMs: number; + /** 完成记录的保留时长 */ + ttlMs: number; + cleanupIntervalMs: number; + /** 已完成结果可被复用的时间窗口 */ + resultCacheMs: number; +} -export function createTask(type: TaskType, params: Record): string { - const id = randomUUID(); - const task: TaskRecord = { - id, - type, - params, - status: "pending", - createdAt: new Date().toISOString(), +function intFrom(value: string | undefined, fallback: number): number { + if (value === undefined || value.trim() === "") return fallback; + const parsed = Number(value); + return Number.isFinite(parsed) && parsed > 0 ? Math.floor(parsed) : fallback; +} + +export function loadQueueConfig(env: NodeJS.ProcessEnv = process.env): QueueConfig { + return { + concurrency: intFrom(env.LPT_AI_CONCURRENCY, 2), + maxAttempts: intFrom(env.LPT_AI_MAX_ATTEMPTS, 3), + retryBaseMs: intFrom(env.LPT_AI_RETRY_BASE_MS, 1_000), + retryMaxMs: intFrom(env.LPT_AI_RETRY_MAX_MS, 20_000), + ttlMs: intFrom(env.LPT_AI_TTL_MS, 60 * 60 * 1000), + cleanupIntervalMs: intFrom(env.LPT_AI_CLEANUP_MS, 5 * 60 * 1000), + resultCacheMs: intFrom(env.LPT_AI_RESULT_CACHE_MS, 10 * 60 * 1000), }; - records.set(id, task); - queue.push(task); - setImmediate(() => tryProcessNext()); - return id; } -export function getTask(id: string): TaskRecord | undefined { - const t = records.get(id); - if (!t) return undefined; - // 返回浅拷贝,防止外部修改 - return { ...t }; +/** 任务执行器:给定任务与参数返回结果,失败时抛出 */ +export type TaskRunner = ( + task: TaskRecord, + context: { attempt: number; messages: ChatMessage[]; config: ReturnType }, +) => Promise; + +export interface TaskQueueDeps { + config?: QueueConfig; + /** 执行单次 LLM 调用;默认走 chat() */ + runOnce?: TaskRunner; + /** 任务最终结束(成功或失败)时的回调,默认写管理面板日志 */ + onSettled?: (task: TaskRecord) => void; + /** 是否可用 LLM;默认看 API Key 是否配置。注入以便测试 */ + isLlmAvailable?: (config: ReturnType) => boolean; + sleep?: (ms: number) => Promise; + random?: () => number; + now?: () => number; + /** 是否启用定时清理,测试里通常关掉 */ + enableCleanup?: boolean; } -// ---- 后台 Worker ---- +// ---- 幂等键 ---- -async function tryProcessNext(): Promise { - if (processing || queue.length === 0) return; - processing = true; +/** + * 稳定序列化:键名排序后再序列化,避免对象键顺序不同导致同一输入算出不同键。 + */ +function stableStringify(value: unknown): string { + if (value === null || typeof value !== "object") { + return JSON.stringify(value) ?? "null"; + } + if (Array.isArray(value)) { + return `[${value.map(stableStringify).join(",")}]`; + } + const entries = Object.entries(value as Record) + .filter(([, v]) => v !== undefined) + .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)); + return `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${stableStringify(v)}`).join(",")}}`; +} - const task = queue.shift()!; +export function computeTaskKey(type: TaskType, params: Record): string { + const payload = stableStringify({ type, params }); + return createHash("sha256").update(payload).digest("hex").slice(0, 32); +} - try { +// ---- 队列 ---- + +export class TaskQueue { + private readonly config: QueueConfig; + private readonly deps: TaskQueueDeps; + private readonly records = new Map(); + /** 幂等键 → 任务 id */ + private readonly keyIndex = new Map(); + private readonly queue: string[] = []; + private running = 0; + private cleanupTimer: NodeJS.Timeout | null = null; + private readonly idleWaiters: Array<() => void> = []; + + constructor(deps: TaskQueueDeps = {}) { + this.deps = deps; + this.config = deps.config ?? loadQueueConfig(); + if (deps.enableCleanup ?? true) { + this.cleanupTimer = setInterval(() => this.cleanup(), this.config.cleanupIntervalMs); + // 不要因为清理定时器让进程无法退出 + this.cleanupTimer.unref?.(); + } + } + + private now(): number { + return this.deps.now ? this.deps.now() : Date.now(); + } + + private sleep(ms: number): Promise { + if (this.deps.sleep) return this.deps.sleep(ms); + return new Promise((resolve) => { + setTimeout(resolve, ms); + }); + } + + /** + * 提交任务。 + * + * 复用规则: + * - 同键任务处于 pending/running → 直接复用(合并重复请求,不重复计费) + * - 同键任务已完成且在 resultCacheMs 窗口内 → 复用结果 + * - 同键任务已失败 → 新建(失败不该被缓存) + * - force=true → 一律新建 + */ + create( + type: TaskType, + params: Record, + options: CreateTaskOptions = {}, + ): CreateTaskResult { + const key = options.idempotencyKey?.trim() || computeTaskKey(type, params); + + if (!options.force) { + const existingId = this.keyIndex.get(key); + const existing = existingId ? this.records.get(existingId) : undefined; + if (existing && this.isReusable(existing)) { + return { taskId: existing.id, reused: true, status: existing.status }; + } + } + + const id = randomUUID(); + const task: TaskRecord = { + id, + key, + type, + params, + status: "pending", + attempts: 0, + createdAt: new Date(this.now()).toISOString(), + }; + this.records.set(id, task); + this.keyIndex.set(key, id); + this.queue.push(id); + setImmediate(() => this.pump()); + return { taskId: id, reused: false, status: "pending" }; + } + + private isReusable(task: TaskRecord): boolean { + if (task.status === "pending" || task.status === "running") { + return true; + } + if (task.status !== "done") { + // 失败的任务不进入复用,否则用户拿不到重试机会 + return false; + } + if (!task.completedAt) return false; + return this.now() - Date.parse(task.completedAt) <= this.config.resultCacheMs; + } + + get(id: string): TaskRecord | undefined { + const task = this.records.get(id); + return task ? { ...task } : undefined; + } + + /** 待处理 + 处理中的任务数,便于观测与测试 */ + get pendingCount(): number { + return this.queue.length + this.running; + } + + /** 当前并发度 */ + get concurrency(): number { + return this.config.concurrency; + } + + /** + * 等待队列跑空。仅用于测试与静态工具场景,生产不应阻塞请求。 + */ + drain(): Promise { + if (this.pendingCount === 0) { + return Promise.resolve(); + } + return new Promise((resolve) => { + this.idleWaiters.push(resolve); + }); + } + + stop(): void { + if (this.cleanupTimer) { + clearInterval(this.cleanupTimer); + this.cleanupTimer = null; + } + } + + // ---- Worker 池 ---- + + /** 在并发额度允许的范围内尽量多启动 Worker */ + private pump(): void { + while (this.running < this.config.concurrency && this.queue.length > 0) { + const id = this.queue.shift(); + if (!id) break; + const task = this.records.get(id); + if (!task) continue; + this.running += 1; + void this.runTask(task).finally(() => { + this.running -= 1; + this.pump(); + this.notifyIfIdle(); + }); + } + this.notifyIfIdle(); + } + + private notifyIfIdle(): void { + if (this.pendingCount > 0) return; + const waiters = this.idleWaiters.splice(0, this.idleWaiters.length); + for (const resolve of waiters) resolve(); + } + + private async runTask(task: TaskRecord): Promise { task.status = "running"; - task.startedAt = new Date().toISOString(); + task.startedAt = new Date(this.now()).toISOString(); const config = loadConfig(); - - if (!isAvailable(config)) { - throw new LlmError("LLM API Key 未配置", 503); + const available = this.deps.isLlmAvailable + ? this.deps.isLlmAvailable(config) + : isAvailable(config); + if (!available) { + task.status = "failed"; + task.error = "LLM API Key 未配置"; + task.completedAt = new Date(this.now()).toISOString(); + this.settle(task); + return; } const messages = buildMessages(task); - let callOptions: { temperature?: number; maxTokens?: number } | undefined; - if (task.type === "compare-recall") { - callOptions = { temperature: 0.2, maxTokens: 4096 }; - } else if (task.type === "generate-mind-map") { - callOptions = { temperature: 0.3, maxTokens: 4096 }; - } else { - callOptions = { temperature: 0.3, maxTokens: 2048 }; + const callOptions = callOptionsFor(task.type); + + const retryOptions: RetryOptions = { + maxAttempts: this.config.maxAttempts, + baseDelayMs: this.config.retryBaseMs, + maxDelayMs: this.config.retryMaxMs, + isRetryable: isRetryableLlmError, + sleep: (ms) => this.sleep(ms), + ...(this.deps.random ? { random: this.deps.random } : {}), + onRetry: () => { + task.attempts += 1; + }, + }; + + try { + const runOnce = + this.deps.runOnce ?? (async (t, ctx) => parseResult(t.type, await chat(ctx.config, ctx.messages, callOptions))); + const result = await withRetry( + () => runOnce(task, { attempt: task.attempts + 1, messages, config }), + retryOptions, + ); + task.attempts += 1; + task.status = "done"; + task.result = result; + task.completedAt = new Date(this.now()).toISOString(); + } catch (err: unknown) { + task.attempts += 1; + task.status = "failed"; + task.error = err instanceof Error ? err.message : String(err); + task.completedAt = new Date(this.now()).toISOString(); + } finally { + this.settle(task, config); } + } - const raw = await chat(config, messages, callOptions); - - let result: unknown; - if (task.type === "aggregate-report") { - result = { report: raw.trim(), model: config.model }; - } else if (task.type === "generate-mind-map") { - result = { outline: raw.trim(), model: config.model }; - } else { - // compare-recall: 清理可能的 ```json 包裹 - const clean = raw.trim().replace(/^```(?:json)?\s*/, "").replace(/\s*```$/, ""); - result = JSON.parse(clean); + private settle(task: TaskRecord, config = loadConfig()): void { + if (this.deps.onSettled) { + this.deps.onSettled(task); + return; } - - task.status = "done"; - task.result = result; - task.completedAt = new Date().toISOString(); - - // 记录到管理面板日志 + const durationMs = + task.startedAt && task.completedAt + ? Date.parse(task.completedAt) - Date.parse(task.startedAt) + : 0; logStore.add({ - timestamp: new Date().toISOString(), + timestamp: new Date(this.now()).toISOString(), endpoint: `/ai/tasks#${task.type}`, model: config.model, - durationMs: task.startedAt ? Date.parse(task.completedAt) - Date.parse(task.startedAt) : 0, - status: 200, + durationMs, + status: task.status === "done" ? 200 : 500, requestBody: task.params, - responseBody: result, - messages, - params: callOptions, + responseBody: task.status === "done" ? (task.result ?? {}) : {}, + ...(task.error ? { error: task.error } : {}), }); + } - } catch (err: unknown) { - const errMsg = err instanceof Error ? err.message : String(err); - task.status = "failed"; - task.error = errMsg; - task.completedAt = new Date().toISOString(); + // ---- 清理 ---- - const config = loadConfig(); - logStore.add({ - timestamp: new Date().toISOString(), - endpoint: `/ai/tasks#${task.type}`, - model: config.model, - durationMs: task.startedAt ? Date.parse(task.completedAt) - Date.parse(task.startedAt) : 0, - status: err instanceof LlmError ? err.statusCode : 500, - requestBody: task.params, - responseBody: {}, - error: errMsg, - }); - } finally { - processing = false; - // 处理下一个任务 - if (queue.length > 0) { - setImmediate(() => tryProcessNext()); + /** 移除过期的完成记录与对应幂等索引;返回移除条数便于测试 */ + cleanup(): number { + const cutoff = this.now() - this.config.ttlMs; + let removed = 0; + for (const [id, task] of this.records) { + if (task.status !== "done" && task.status !== "failed") continue; + const completed = task.completedAt ? Date.parse(task.completedAt) : 0; + if (completed > 0 && completed < cutoff) { + this.records.delete(id); + // 索引只在该键仍指向这条记录时才删,避免误删后续新任务的索引 + if (this.keyIndex.get(task.key) === id) { + this.keyIndex.delete(task.key); + } + removed += 1; + } } + return removed; + } + + /** 供测试断言内部状态 */ + size(): number { + return this.records.size; } } -// ---- Prompt 构建 ---- +// ---- 结果解析与 Prompt ---- -function buildMessages(task: TaskRecord) { +function callOptionsFor(type: TaskType): { temperature: number; maxTokens: number } { + if (type === "compare-recall") return { temperature: 0.2, maxTokens: 4096 }; + if (type === "generate-mind-map") return { temperature: 0.3, maxTokens: 4096 }; + return { temperature: 0.3, maxTokens: 2048 }; +} + +/** 把模型原文转成结构化结果 */ +export function parseResult(type: TaskType, raw: string, model = ""): unknown { + const text = raw.trim(); + if (type === "aggregate-report") { + return { report: text, model }; + } + if (type === "generate-mind-map") { + return { outline: text, model }; + } + const clean = text.replace(/^```(?:json)?\s*/, "").replace(/\s*```$/, ""); + return JSON.parse(clean); +} + +export function buildMessages(task: TaskRecord): ChatMessage[] { const p = task.params; switch (task.type) { case "aggregate-report": { @@ -176,19 +426,20 @@ function buildMessages(task: TaskRecord) { } } -// ---- TTL 清理 ---- +// ---- 生产单例 ---- -const TTL_MS = 60 * 60 * 1000; // 1 小时 -const CLEANUP_INTERVAL_MS = 5 * 60 * 1000; // 5 分钟 +export const taskQueue = new TaskQueue(); -setInterval(() => { - const cutoff = Date.now() - TTL_MS; - for (const [id, task] of records) { - if (task.status === "done" || task.status === "failed") { - const completed = task.completedAt ? Date.parse(task.completedAt) : 0; - if (completed > 0 && completed < cutoff) { - records.delete(id); - } - } - } -}, CLEANUP_INTERVAL_MS); +export function createTask( + type: TaskType, + params: Record, + options: CreateTaskOptions = {}, +): CreateTaskResult { + return taskQueue.create(type, params, options); +} + +export function getTask(id: string): TaskRecord | undefined { + return taskQueue.get(id); +} + +export { LlmError }; diff --git a/tsconfig.test.json b/tsconfig.test.json new file mode 100644 index 0000000..10ef9f4 --- /dev/null +++ b/tsconfig.test.json @@ -0,0 +1,8 @@ +{ + "extends": "./tsconfig.json", + "compilerOptions": { + "noEmit": true + }, + "include": ["src/**/*"], + "exclude": ["node_modules", "dist"] +}