From 4aff5c03fee8e9b4f854bc9e93598c4efad8b6a3 Mon Sep 17 00:00:00 2001 From: cat-shark <1716967236@qq.com> Date: Sat, 10 Oct 2026 20:08:51 +0800 Subject: [PATCH] =?UTF-8?q?feat:=20=E7=94=A8=E9=87=8F=E5=BD=92=E5=B1=9E?= =?UTF-8?q?=E6=94=AF=E6=8C=81=20callerRef=20=E9=80=8F=E4=BC=A0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - POST /ai/tasks 接受顶层可选 callerRef(限 64 字符),不进入 params、不参与幂等键、不进 prompt - 结算时写进用量记录,lpt-be 据此做用户维度报表 - 复用已有任务时沿用原归属:那次 LLM 调用只发生一次,账算在原调用方头上 --- AGENTS.md | 17 ++++- src/admin/reporter.test.ts | 5 ++ src/admin/reporter.ts | 3 + src/admin/routes.ts | 1 + src/admin/store.ts | 4 ++ src/routes/ai.test.ts | 127 +++++++++++++++++++++++++++++++++++++ src/routes/ai.ts | 23 ++++++- src/task-queue.test.ts | 46 ++++++++++++++ src/task-queue.ts | 16 +++++ 9 files changed, 240 insertions(+), 2 deletions(-) create mode 100644 src/routes/ai.test.ts diff --git a/AGENTS.md b/AGENTS.md index 2bde69d..a19b0f6 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -64,9 +64,24 @@ lpt-ai/src/ 峰时窗口按 UTC 判定(`01:00-04:00`、`06:00-10:00`,周一至周五),谷时 = 峰时 × 0.5。 计价结果在结算时**冻结进日志快照**,改价不会重算历史账。 - `admin/reporter.ts`:把用量推给 lpt-be(长期账本)。上报失败先落本地 outbox 再重试, - 幂等靠 `record_id` 唯一索引。未配置 `LPT_AI_REPORT_URL` 时为空操作。 + 幂等靠 `record_id` 唯一索引;4xx 属于确定性拒绝,丢弃这批并计数,不无限重试。 + 未配置 `LPT_AI_REPORT_URL` 时为空操作。 - **权威口径在 lpt-be 的 MySQL**;本地面板只是最近 500 条的调试视图。 +### 用量归属(callerRef) + +lpt-ai 不知道调用方是谁,所以归属标记由调用方带过来:`POST /ai/tasks` 接受顶层可选字段 +`callerRef`(lpt-be 传的是用户 id),结算时原样写进用量记录,lpt-be 据此做用户维度报表。 + +三条硬约束,改动时必须守住: + +1. **不放进 `params`** —— 会污染 prompt 模板的输入; +2. **不参与幂等键** —— 否则同一份输入会因为调用方不同而重复调 LLM; +3. **不进入 prompt** —— 它只是记账标记。 + +复用已有任务时**沿用原任务的 `callerRef`**:那次 LLM 调用只发生了一次,账算在原调用方头上; +复用方没有产生新的 token 消耗,也不会有新的用量记录。 + > `/admin` 用 `?token=…` 首次打开时会换发 `HttpOnly` cookie,否则面板 HTML 与它内部的 > `fetch` 是两个独立请求,内部请求会全部 401。详见 `roles/security-and-degradation.md`。 diff --git a/src/admin/reporter.test.ts b/src/admin/reporter.test.ts index e1ddf60..de613b8 100644 --- a/src/admin/reporter.test.ts +++ b/src/admin/reporter.test.ts @@ -120,6 +120,11 @@ describe("toUsageRecord", () => { expect(record.model).toBe(""); }); + it("归属标记原样带上;没传时显式写 null", () => { + expect(toUsageRecord(entry({ callerRef: "U-123" })).callerRef).toBe("U-123"); + expect(toUsageRecord(entry()).callerRef).toBeNull(); + }); + it("必填字段永远非空,否则 lpt-be 会把整批上报判 400", () => { // 契约 1 的必填项:lpt-be 侧 @NotBlank 的字段不能是空串,@NotNull 的字段不能缺。 // 尤其是 /fetch-title 的 model——它合法地是空串,所以 lpt-be 那边用的是 @NotNull。 diff --git a/src/admin/reporter.ts b/src/admin/reporter.ts index 4fe6ddc..67aa736 100644 --- a/src/admin/reporter.ts +++ b/src/admin/reporter.ts @@ -23,6 +23,8 @@ export interface UsageRecord { occurredAt: string; taskType: string; taskId: string | null; + /** 归属标记(lpt-be 传的用户 id);lpt-be 把它落到 ai_usage_records.user_id */ + callerRef: string | null; model: string; attempts: number; isLlmCall: boolean; @@ -91,6 +93,7 @@ export function toUsageRecord(entry: LogEntry): UsageRecord { occurredAt: entry.timestamp, taskType: entry.taskType ?? entry.endpoint, taskId: entry.taskId ?? null, + callerRef: entry.callerRef ?? null, model: entry.model, attempts: entry.attempts ?? 1, isLlmCall: entry.isLlmCall, diff --git a/src/admin/routes.ts b/src/admin/routes.ts index bc1f8f0..55422c9 100644 --- a/src/admin/routes.ts +++ b/src/admin/routes.ts @@ -185,6 +185,7 @@ async function toggleDetail(id, el) { let txt = '=== lpt-ai 请求日志 ===\\n'; txt += '端点: '+(log.endpoint||'')+'\\n'; txt += '模型: '+(log.model||'')+'\\n'; + txt += '归属: '+(log.callerRef||'未归属')+'\\n'; txt += '耗时: '+log.durationMs+'ms\\n'; txt += '状态: '+log.status+'\\n'; if (log.attempts != null) txt += '调用次数: '+log.attempts+'\\n'; diff --git a/src/admin/store.ts b/src/admin/store.ts index 005e02e..5119494 100644 --- a/src/admin/store.ts +++ b/src/admin/store.ts @@ -31,6 +31,8 @@ export interface LogEntry { taskType?: string; /** 任务标识,便于把面板上的一条日志对回具体任务 */ taskId?: string; + /** 归属标记(lpt-be 传的用户 id);为空表示调用方没传或为独立调用 */ + callerRef?: string; model: string; /** 本次请求实际发起的 LLM 调用次数(含失败重试);重试会重复计费 */ attempts?: number; @@ -57,6 +59,7 @@ export interface LogSummary { timestamp: string; endpoint: string; taskType?: string; + callerRef?: string; model: string; attempts?: number; isLlmCall: boolean; @@ -140,6 +143,7 @@ export class LogStore { timestamp: entry.timestamp, endpoint: entry.endpoint, ...(entry.taskType !== undefined ? { taskType: entry.taskType } : {}), + ...(entry.callerRef !== undefined ? { callerRef: entry.callerRef } : {}), model: entry.model, ...(entry.attempts !== undefined ? { attempts: entry.attempts } : {}), isLlmCall: entry.isLlmCall, diff --git a/src/routes/ai.test.ts b/src/routes/ai.test.ts new file mode 100644 index 0000000..a2fc31b --- /dev/null +++ b/src/routes/ai.test.ts @@ -0,0 +1,127 @@ +import { mkdtempSync, rmSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; +import Fastify from "fastify"; +import { afterEach, beforeEach, describe, expect, it } from "vitest"; + +import { aiRoutes } from "./ai.js"; +import { getTask } from "../task-queue.js"; + +const originalDataDir = process.env.LPT_AI_DATA_DIR; +const originalKey = process.env.LLM_API_KEY; +const originalRateLimit = process.env.LPT_AI_RATE_LIMIT; +let workDir: string; + +beforeEach(() => { + // 面板日志会落盘,必须指向临时目录,否则会清掉开发者真实的面板数据 + workDir = mkdtempSync(join(tmpdir(), "lpt-ai-routes-")); + process.env.LPT_AI_DATA_DIR = workDir; + // 不配 Key:任务会以「LLM 不可用」快速失败,用例不需要真调 LLM + delete process.env.LLM_API_KEY; + process.env.LPT_AI_RATE_LIMIT = "10000"; +}); + +afterEach(() => { + for (const [key, value] of [ + ["LPT_AI_DATA_DIR", originalDataDir], + ["LLM_API_KEY", originalKey], + ["LPT_AI_RATE_LIMIT", originalRateLimit], + ] as const) { + if (value === undefined) { + delete process.env[key]; + } else { + process.env[key] = value; + } + } + rmSync(workDir, { recursive: true, force: true }); +}); + +async function buildApp() { + const app = Fastify(); + await app.register(aiRoutes); + await app.ready(); + return app; +} + +function submit(app: Awaited>, body: unknown) { + return app.inject({ + method: "POST", + url: "/ai/tasks", + payload: body as Record, + }); +} + +describe("POST /ai/tasks 的 callerRef(用量归属)", () => { + it("带归属提交时落到任务记录上,供结算写进用量记录", async () => { + const app = await buildApp(); + const response = await submit(app, { + type: "guidance", + params: { taskName: "t", concept: "c", history: [] }, + callerRef: "U-123", + }); + + expect(response.statusCode).toBe(201); + const { taskId } = JSON.parse(response.body) as { taskId: string }; + expect(getTask(taskId)?.callerRef).toBe("U-123"); + await app.close(); + }); + + it("不传归属时任务记录上没有该字段", async () => { + const app = await buildApp(); + const response = await submit(app, { + type: "guidance", + params: { taskName: "t", concept: "c", history: [] }, + }); + + const { taskId } = JSON.parse(response.body) as { taskId: string }; + expect(getTask(taskId)?.callerRef).toBeUndefined(); + await app.close(); + }); + + it("空白归属视为未传,不写空字符串", async () => { + const app = await buildApp(); + const response = await submit(app, { + type: "guidance", + params: { taskName: "t", concept: "c", history: [] }, + callerRef: " ", + }); + + const { taskId } = JSON.parse(response.body) as { taskId: string }; + expect(getTask(taskId)?.callerRef).toBeUndefined(); + await app.close(); + }); + + it("超过 64 字符被拒:它会落进日志与数据库列,限长比让库截断安全", async () => { + const app = await buildApp(); + const response = await submit(app, { + type: "guidance", + params: { taskName: "t", concept: "c", history: [] }, + callerRef: "x".repeat(65), + }); + + expect(response.statusCode).toBe(400); + expect(JSON.parse(response.body).error).toContain("64"); + await app.close(); + }); + + it("非字符串被拒,避免把对象写进归属列", async () => { + const app = await buildApp(); + const response = await submit(app, { + type: "guidance", + params: { taskName: "t", concept: "c", history: [] }, + callerRef: { userId: "U-1" }, + }); + + expect(response.statusCode).toBe(400); + await app.close(); + }); + + it("归属不影响参数校验:type 非法仍然优先报错", async () => { + const app = await buildApp(); + const response = await submit(app, { type: "nope", params: {}, callerRef: "U-1" }); + + expect(response.statusCode).toBe(400); + expect(JSON.parse(response.body).error).toContain("无效的 type"); + await app.close(); + }); +}); diff --git a/src/routes/ai.ts b/src/routes/ai.ts index 8aa4bb5..326ed53 100644 --- a/src/routes/ai.ts +++ b/src/routes/ai.ts @@ -10,6 +10,14 @@ import { safeFetchText, UnsafeUrlError } from "../utils/ssrf-guard.js"; import { RateLimiter, intFromEnv } from "../utils/rate-limit.js"; import { checkToken } from "../utils/auth.js"; +/** + * 归属标记的最大长度。 + * + * 它会落进日志与 lpt-be 的 `ai_usage_records.user_id`(VARCHAR(255)), + * 在入口限长比让数据库截断更安全。 + */ +const MAX_CALLER_REF_LENGTH = 64; + export async function aiRoutes(app: FastifyInstance): Promise { const config = loadConfig(); @@ -52,9 +60,11 @@ export async function aiRoutes(app: FastifyInstance): Promise { idempotencyKey?: string; /** 可选:跳过结果复用,强制重新生成 */ force?: boolean; + /** 可选:归属标记(lpt-be 传用户 id),原样写进用量记录;不参与幂等键 */ + callerRef?: string; }; }>("/ai/tasks", async (request, reply) => { - const { type, params, idempotencyKey, force } = request.body ?? {}; + const { type, params, idempotencyKey, force, callerRef } = request.body ?? {}; const decision = taskLimiter.check(clientKey(request)); if (!decision.allowed) { @@ -71,12 +81,23 @@ export async function aiRoutes(app: FastifyInstance): Promise { if (!params || typeof params !== "object") { return reply.status(400).send({ error: "params 必须为非空对象" }); } + // 归属标记是 opaque 字符串,但必须限长:它会落进日志与数据库列(VARCHAR(64)) + if (callerRef !== undefined && callerRef !== null) { + if (typeof callerRef !== "string" || callerRef.length > MAX_CALLER_REF_LENGTH) { + return reply + .status(400) + .send({ error: `callerRef 必须是不超过 ${MAX_CALLER_REF_LENGTH} 字符的字符串` }); + } + } const created = createTask(type as TaskType, params as Record, { ...(typeof idempotencyKey === "string" && idempotencyKey.trim().length > 0 ? { idempotencyKey } : {}), ...(force === true ? { force: true } : {}), + ...(typeof callerRef === "string" && callerRef.trim().length > 0 + ? { callerRef: callerRef.trim() } + : {}), }); // 固定返回 201:Java 端 AiServiceClient 把非 201 当作提交失败, diff --git a/src/task-queue.test.ts b/src/task-queue.test.ts index b36c86d..8a3dcd9 100644 --- a/src/task-queue.test.ts +++ b/src/task-queue.test.ts @@ -654,6 +654,52 @@ describe("用量归集", () => { }); }); +describe("callerRef(用量归属)", () => { + it("落到任务记录上,供结算时写进用量日志", async () => { + const queue = makeQueue({}, async () => ({ ok: true })); + const created = queue.create( + "aggregate-report", + { taskName: "t", fragments: [] }, + { callerRef: "U-123" }, + ); + await queue.drain(); + + expect(queue.get(created.taskId)?.callerRef).toBe("U-123"); + queue.stop(); + }); + + it("不传时不写该字段,避免出现空字符串归属", async () => { + const queue = makeQueue({}, async () => ({ ok: true })); + const created = queue.create("aggregate-report", { taskName: "t", fragments: [] }); + await queue.drain(); + + expect(queue.get(created.taskId)?.callerRef).toBeUndefined(); + queue.stop(); + }); + + it("复用已有任务时沿用原归属,不被后来的调用方覆盖", async () => { + // 同类型同参数会被复用,而那次 LLM 调用只发生了一次,账算在原调用方头上; + // 复用方没有产生新的 token 消耗,也不会有新的用量记录。 + const queue = makeQueue({}, async () => ({ ok: true })); + const params = { taskName: "t", fragments: [{ content: "same" }] }; + + const first = queue.create("aggregate-report", params, { callerRef: "U-1" }); + await queue.drain(); + const second = queue.create("aggregate-report", params, { callerRef: "U-2" }); + + expect(second.reused).toBe(true); + expect(second.taskId).toBe(first.taskId); + expect(queue.get(first.taskId)?.callerRef).toBe("U-1"); + queue.stop(); + }); + + it("不参与幂等键:同一输入带上不同归属仍然复用同一个任务", () => { + // 若 callerRef 进了键,同一份输入会因为调用方不同而重复调 LLM,白花钱 + const withRef = computeTaskKey("aggregate-report", { taskName: "t" }); + expect(computeTaskKey("aggregate-report", { taskName: "t" })).toBe(withRef); + }); +}); + describe("classifyLlmError", () => { it("按状态码归成可聚合的分类", () => { expect(classifyLlmError(new LlmError("超时", 504))).toBe("timeout"); diff --git a/src/task-queue.ts b/src/task-queue.ts index 7d3b6c6..5555d85 100644 --- a/src/task-queue.ts +++ b/src/task-queue.ts @@ -37,6 +37,13 @@ export interface TaskRecord { error?: string; /** 已尝试次数(含首次),便于排查重试情况 */ attempts: number; + /** + * 调用方打的归属标记(lpt-be 传的是用户 id)。 + * + * opaque 字符串,lpt-ai 不解释它的含义,只在结算时原样写进用量记录。 + * 刻意不放进 `params`:那会污染 prompt 模板的输入,也会把幂等键算错。 + */ + callerRef?: string; /** * 跨所有尝试累加的 token 用量。 * @@ -57,6 +64,13 @@ export interface CreateTaskOptions { idempotencyKey?: string; /** 跳过复用,强制新建任务(用户主动「重新生成」时用) */ force?: boolean; + /** + * 归属标记(lpt-be 传用户 id),结算时原样写进用量记录。 + * + * 复用已有任务时**不会**覆盖原任务的标记:那次 LLM 调用只发生了一次, + * 账算在原调用方头上;复用方没有产生新的 token 消耗。 + */ + callerRef?: string; } export interface CreateTaskResult { @@ -210,6 +224,7 @@ export class TaskQueue { 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); @@ -386,6 +401,7 @@ export class TaskQueue { endpoint: `/ai/tasks#${task.type}`, taskType: task.type, taskId: task.id, + ...(task.callerRef ? { callerRef: task.callerRef } : {}), model: config.model, attempts: task.attempts, isLlmCall: true,