- roles/ 与 skills/ 迁移到 .agents/ 下,AGENTS.md 引用同步 - 收录 8 篇决策笔记到 .agents/notes/ - .rgignore 排除 archived 历史快照
51 lines
3.1 KiB
Markdown
51 lines
3.1 KiB
Markdown
# 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` 为「未归属」)。
|