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

51 lines
3.1 KiB
Markdown
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.
# 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` 为「未归属」)。