Files
lpt-be/.agents/notes/implemented/architecture/2026-10-10-usage-attribution-callerref.md
T
cat-shark 27ddf8be5a docs: 规则与技能迁入 .agents/,并接入决策笔记
- roles/ 与 skills/ 迁移到 .agents/ 下,AGENTS.md 引用同步
- 收录 8 篇决策笔记到 .agents/notes/
- .rgignore 排除 archived 历史快照
2026-11-18 15:01:05 +08:00

3.1 KiB
Raw Blame History

Agent Note: 用量归属 mark 跟着请求走,路由信息不进 params

Status: implemented

Problem

用量要能按用户切分,但 lpt-ai 不知道调用方是谁:它只收到一个 POST /ai/tasks 的请求体(type + params)。 在 lpt-be 侧「提交后再写回归属」也不成立——lpt-ai 可能比 lpt-be 的写回更早结算,形成归属与账目赛跑。

Decision

归属标记由调用方带过来:POST /ai/tasks 接受顶层可选字段 callerRef(限 64 字符),lpt-be 的 AiServiceClient 填当前用户 id,lpt-ai 原样透传,结算时写进用量记录,lpt-be 落到 user_id。

三条硬约束,改动时必须同时守住:

  1. 不放进 params —— params 会喂给 prompt 模板,混进去等于把内部 id 塞进模型输入;
  2. 不参与幂等键 —— 幂等键是 type + params,callerRef 进去会让同一份输入因调用方不同而重复调 LLM;
  3. 不进 prompt —— 它只是记账标记,不是上下文。

配套两条:

  • 取不到身份就不带:currentCallerRef() 拿不到登录态时返回 null,请求体里整个键都不写,这笔用量记为「未归属」。 绝不能因为取不到用户让 AI 调用失败。
  • 复用已有任务沿用原 callerRef:那次 LLM 调用只发生了一次,账算在原调用方头上;复用方没有产生新 token, 也就不会有新的用量记录。

Alternatives considered

  • lpt-be 提交任务后写回归属,等结算时再查 — 不用改 AI 侧协议。但它依赖「写回早于结算」的时序假设, 而任务是异步的,lpt-ai 完全可能先结算;一旦发生就是归属丢失或错挂,且没有信号提示。
  • 把 callerRef 塞进 params 顺带透传 — 不必新增顶层字段,实现最省事。放弃是因为 params 同时是 prompt 模板输入和幂等键的组成部分,一个记账字段混进去会同时污染模型输入和去重语义。
  • 让 lpt-ai 反查 lpt-be 拿归属 — 归属只在一处定义。但那是服务间反向依赖,AI 服务要为此持有一个 lpt-be 的 查询凭据与失败降级路径,为一个记账字段引入的耦合远大于收益。

Consequences

  • 收益:归属在 LLM 调用之前就已确定,没有「上报先到、归属还没写回」的竞态;AI 服务不需要知道 lpt-be 的任何 用户概念,只透传一个不透明字符串。
  • 代价与已知上限:归属完全依赖调用方老实带上,callerRef 是自由字符串——lpt-ai 不做校验也不该做校验, 伪造与错填由 lpt-be 侧负责(它填的是 StpUtil 里取到的登录 id)。未归属记录必须作为单独一行存在, 不能为了报表好看塞给某个用户。

Verification

  • 调用方:src/main/java/com/guo/learningprogresstracker/service/impl/AiServiceClient.java 的 currentCallerRef() 与请求体组装(顶层 callerRef),AiServiceClientAttributionTest。
  • 承接方:lpt-ai src/routes/ai.ts 与 src/task-queue.ts 的 callerRef 透传,报表侧 breakdown?groupBy=user(未归属 key 为 null、label 为「未归属」)。