Files
lpt-ai/src/task-queue.ts
T
cat-shark 4aff5c03fe feat: 用量归属支持 callerRef 透传
- POST /ai/tasks 接受顶层可选 callerRef(限 64 字符),不进入 params、不参与幂等键、不进 prompt
- 结算时写进用量记录,lpt-be 据此做用户维度报表
- 复用已有任务时沿用原归属:那次 LLM 调用只发生一次,账算在原调用方头上
2026-10-10 20:08:51 +08:00

607 lines
20 KiB
TypeScript
Raw 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.
/**
* 异步任务队列 —— 接收任务,后台 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<string, unknown>;
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<typeof loadConfig> },
) => Promise<unknown>;
export interface TaskQueueDeps {
config?: QueueConfig;
/** 执行单次 LLM 调用;默认走 chat() */
runOnce?: TaskRunner;
/** 任务最终结束(成功或失败)时的回调,默认写管理面板日志 */
onSettled?: (task: TaskRecord) => void;
/** 是否可用 LLM;默认看 API Key 是否配置。注入以便测试 */
isLlmAvailable?: (config: ReturnType<typeof loadConfig>) => boolean;
sleep?: (ms: number) => Promise<void>;
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<string, unknown>)
.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, unknown>): 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<string, TaskRecord>();
/** 幂等键 → 任务 id */
private readonly keyIndex = new Map<string, string>();
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<void> {
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<string, unknown>,
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<void> {
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<void> {
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<string, unknown>;
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<string, unknown>,
options: CreateTaskOptions = {},
): CreateTaskResult {
return taskQueue.create(type, params, options);
}
export function getTask(id: string): TaskRecord | undefined {
return taskQueue.get(id);
}
export { LlmError };