/** * 异步任务队列 —— 接收任务,后台 Worker 池并发处理,提供查询与幂等复用。 * * 设计要点: * - **Worker 池**:并发度可配置。原实现用单个 processing 标志串行, * N 个请求要等 N × LLM 耗时,客户端很容易先超时。 * - **退避重试**:429 / 5xx / 超时等瞬时抖动不再直接判失败,见 llm/retry.ts。 * - **相同输入复用**:同一 type + 同参数的请求会复用同一个任务, * 避免重复计费;进行中的请求直接合并,已完成的结果在窗口内复用。 * - **TTL 清理**:定期移除过期的完成记录,同时清理幂等索引。 * - 依赖以构造参数注入,便于单测;生产使用文件末尾的单例。 */ import { randomUUID, createHash } from "node:crypto"; import { chat, isAvailable, loadConfig, LlmError, type ChatMessage, type ChatOptions } from "./llm/client.js"; import { accumulateUsage, combineSource, emptyUsage, type TokenUsage, type UsageSource } from "./llm/usage.js"; import { withRetry, isRetryableLlmError, type RetryOptions } from "./llm/retry.js"; import { aggregateReportPrompt, compareRecallPrompt, generateMindMapPrompt, guidancePrompt } from "./llm/prompts.js"; import { loadThinkingConfig, promptLength, reasoningEffortFor, type ThinkingConfig } from "./llm/thinking.js"; import { logStore } from "./admin/store.js"; import { loadPricingConfig, priceUsage, type PricingSnapshot } from "./admin/pricing.js"; // ---- 类型 ---- export type TaskType = "aggregate-report" | "generate-mind-map" | "compare-recall" | "guidance"; 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; /** * 调用方打的归属标记(lpt-be 传的是用户 id)。 * * opaque 字符串,lpt-ai 不解释它的含义,只在结算时原样写进用量记录。 * 刻意不放进 `params`:那会污染 prompt 模板的输入,也会把幂等键算错。 */ callerRef?: string; /** * 跨所有尝试累加的 token 用量。 * * 重试会重复计费,所以这里是「这个任务一共花了多少」,不是「最后一次花了多少」; * 某个字段为 null 表示所有尝试都没拿到该维度(不要当成 0)。 */ usage?: TokenUsage; usageSource?: UsageSource; /** 失败分类(timeout / rate_limited / ...),便于按错误类型聚合用量 */ errorCode?: string; createdAt: string; // ISO 8601 startedAt?: string; completedAt?: string; } export interface CreateTaskOptions { /** 显式幂等键;不传则由 type + params 计算 */ idempotencyKey?: string; /** 跳过复用,强制新建任务(用户主动「重新生成」时用) */ force?: boolean; /** * 归属标记(lpt-be 传用户 id),结算时原样写进用量记录。 * * 复用已有任务时**不会**覆盖原任务的标记:那次 LLM 调用只发生了一次, * 账算在原调用方头上;复用方没有产生新的 token 消耗。 */ callerRef?: string; } export interface CreateTaskResult { taskId: string; /** true 表示复用了已有任务,调用方不应按「新任务」处理 */ reused: boolean; /** 复用的任务当前状态,便于调用方决定返回 200 还是 201 */ status: TaskStatus; } export interface QueueConfig { /** 并发处理的任务数 */ concurrency: number; /** 单任务总尝试次数(含首次) */ maxAttempts: number; retryBaseMs: number; retryMaxMs: number; /** 完成记录的保留时长 */ ttlMs: number; cleanupIntervalMs: number; /** 已完成结果可被复用的时间窗口 */ resultCacheMs: number; } 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), }; } /** 任务执行器:给定任务与参数返回结果,失败时抛出 */ 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; } // ---- 幂等键 ---- /** * 稳定序列化:键名排序后再序列化,避免对象键顺序不同导致同一输入算出不同键。 */ 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(",")}}`; } export function computeTaskKey(type: TaskType, params: Record): string { const payload = stableStringify({ type, params }); return createHash("sha256").update(payload).digest("hex").slice(0, 32); } // ---- 队列 ---- 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(), ...(options.callerRef ? { callerRef: options.callerRef } : {}), }; 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(this.now()).toISOString(); const config = loadConfig(); 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(); task.usage = emptyUsage(); task.usageSource = "missing"; this.settle(task); return; } const messages = buildMessages(task); const callOptions = callOptionsFor(task.type, messages); 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; }, }; // 每次尝试的用量都要留下:重试 N 次就是 N 次计费,失败尝试也可能已经产生了 token const attemptUsages: TokenUsage[] = []; const attemptSources: UsageSource[] = []; try { const runOnce = this.deps.runOnce ?? (async (t, ctx) => { try { const result = await chat(ctx.config, ctx.messages, callOptions); attemptUsages.push(result.usage); attemptSources.push(result.usageSource); return parseResult(t.type, result.content, result.model); } catch (err) { // 上游返回 200 但内容为空这类失败已经计费,用量挂在 LlmError 上带回来 if (err instanceof LlmError && err.usage) { attemptUsages.push(err.usage); attemptSources.push("upstream"); } else { attemptUsages.push(emptyUsage()); attemptSources.push("missing"); } throw err; } }); 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.errorCode = classifyLlmError(err); task.completedAt = new Date(this.now()).toISOString(); } finally { task.usage = accumulateUsage(attemptUsages); task.usageSource = combineSource(attemptSources); this.settle(task, config); } } private settle(task: TaskRecord, config = loadConfig()): void { if (this.deps.onSettled) { this.deps.onSettled(task); return; } const durationMs = task.startedAt && task.completedAt ? Date.parse(task.completedAt) - Date.parse(task.startedAt) : 0; const usage = task.usage ?? emptyUsage(); // 计价在结算时冻结:价格表会变,历史账不能被新价格改写。 // 重试跨越峰谷分界时整单按结算时刻计价,偏差上限是一个任务的执行时长。 const priced = priceUsage(usage, new Date(this.now()), loadPricingConfig()); logStore.add({ timestamp: new Date(this.now()).toISOString(), endpoint: `/ai/tasks#${task.type}`, taskType: task.type, taskId: task.id, ...(task.callerRef ? { callerRef: task.callerRef } : {}), model: config.model, attempts: task.attempts, isLlmCall: true, usage, usageSource: task.usageSource ?? "missing", costUsd: priced.costUsd, pricing: priced.snapshot, durationMs, status: task.status === "done" ? 200 : 500, requestBody: task.params, responseBody: task.status === "done" ? (task.result ?? {}) : {}, ...(task.error ? { error: task.error } : {}), ...(task.errorCode ? { errorCode: task.errorCode } : {}), }); } // ---- 清理 ---- /** 移除过期的完成记录与对应幂等索引;返回移除条数便于测试 */ 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; } } // ---- 失败分类 ---- /** * 把失败原因归成可聚合的短分类。 * * 面板要能回答「这个月有多少次是被限流打掉的」;把整句错误文案当分类是聚合不起来的。 * 上游原文仍然留在 `error` 字段里,分类只用于分组统计。 */ export function classifyLlmError(error: unknown): string { if (!(error instanceof LlmError)) return "unknown"; if (error.message.includes("API Key 未配置")) return "not_configured"; switch (error.statusCode) { case 408: case 504: return "timeout"; case 429: return "rate_limited"; case 402: return "insufficient_balance"; case 401: case 403: return "auth_failed"; case 400: case 404: case 422: return "bad_request"; default: return error.statusCode >= 500 ? "upstream_error" : "unknown"; } } // ---- 结果解析与 Prompt ---- function baseCallOptions(type: TaskType): ChatOptions { if (type === "compare-recall") return { temperature: 0.2, maxTokens: 4096 }; if (type === "generate-mind-map") return { temperature: 0.3, maxTokens: 4096 }; if (type === "guidance") return { temperature: 0.7, maxTokens: 1024 }; return { temperature: 0.3, maxTokens: 2048 }; } /** * 单次调用参数:温度与输出上限按任务类型固定,思考强度按 prompt 总长度自适应。 * * 短输入(几句碎片、单轮引导)直接 `none` 关掉思考,不再跟随供应商的默认 `high`, * 避免为一点点内容付满档思考的额度与延迟;阈值全部走 `LPT_AI_REASONING_*`。 */ export function callOptionsFor( type: TaskType, messages: ChatMessage[], thinking: ThinkingConfig = loadThinkingConfig(), ): ChatOptions { const base = baseCallOptions(type); if (!thinking.enabled) return base; return { ...base, reasoningEffort: reasoningEffortFor(promptLength(messages), thinking) }; } /** 把模型原文转成结构化结果 */ /** * 解析结构化的报告草稿。 * * 报告是结构化的(会话摘要 / 预期达成判断 / 自由总结),但 LLM 不一定老实返回 JSON: * 这里对「带代码块围栏」「返回了纯文本」两种情况都做降级,把整段文本当作自由总结, * 保证用户至少拿到一份可编辑的草稿,而不是一个报错。 */ export function parseReportDraft(raw: string, model = ""): { sessionSummary: string; expectationVerdict: string; freeSummary: string; model: string; } { const text = raw.trim(); const jsonText = text.replace(/^```(?:json)?\s*/, "").replace(/\s*```$/, ""); try { const parsed = JSON.parse(jsonText) as Record; const pick = (key: string): string => { const value = parsed[key]; return typeof value === "string" ? value : ""; }; const draft = { sessionSummary: pick("sessionSummary"), expectationVerdict: pick("expectationVerdict"), freeSummary: pick("freeSummary"), model, }; if (draft.sessionSummary || draft.expectationVerdict || draft.freeSummary) { return draft; } } catch { // 不是 JSON:按纯文本降级处理 } return { sessionSummary: "", expectationVerdict: "", freeSummary: text, model }; } export function parseResult(type: TaskType, raw: string, model = ""): unknown { const text = raw.trim(); if (type === "aggregate-report") { return parseReportDraft(text, model); } if (type === "generate-mind-map") { return { outline: text, model }; } if (type === "guidance") { return { reply: 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": { const fragments = p.fragments as Array<{ content: string }> | undefined; return aggregateReportPrompt( p.taskName as string, fragments ?? [], p.expectation as string | undefined, ); } case "generate-mind-map": { // 素材为「该任务名下的知识碎片」(按内容归属取),不再用按会话产生的报告 const fragments = p.fragments as string[] | undefined; return generateMindMapPrompt( p.taskName as string, (p.taskDescription as string) ?? "", fragments ?? [], ); } case "guidance": { const history = (p.history as ChatMessage[] | undefined) ?? []; return guidancePrompt(p.taskName as string, p.concept as string, history); } case "compare-recall": { return compareRecallPrompt( p.taskName as string, p.standardOutline as string, p.recallOutline as string, ); } } } // ---- 生产单例 ---- export const taskQueue = new TaskQueue(); 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 };