@lingda-ai/dsh-plugin-ledger 0.1.3 → 0.1.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +17 -0
- package/cordis.patch.yml +3 -2
- package/docs/business-plan.md +237 -0
- package/docs/spikes.md +373 -0
- package/docs/technical.md +364 -0
- package/docs/wire-format.md +95 -0
- package/lib/attribution.js +73 -0
- package/lib/audit-tool.js +184 -0
- package/lib/budget-message.js +28 -0
- package/lib/client.js +217 -0
- package/lib/config.js +74 -0
- package/lib/guard.js +102 -0
- package/lib/identity.js +119 -0
- package/lib/index.js +217 -0
- package/lib/ledger.js +260 -0
- package/lib/panel-path.js +39 -0
- package/lib/panel-view.js +717 -0
- package/lib/pricing-file.js +169 -0
- package/lib/pricing-table.js +55 -0
- package/lib/pricing.js +84 -0
- package/lib/ring.js +54 -0
- package/lib/snapshot-file.js +293 -0
- package/lib/store.js +330 -0
- package/lib/tool-size.js +25 -0
- package/lib/trace-file.js +139 -0
- package/lib/trace.js +82 -0
- package/lib/usage.js +67 -0
- package/lib/wire.js +87 -0
- package/package.json +25 -5
|
@@ -0,0 +1,364 @@
|
|
|
1
|
+
# 账本(@lingda-ai/ledger)技术文档
|
|
2
|
+
|
|
3
|
+
> 版本 0.1.0 · 代码仓 `gitee.com/linzhengtong/dsh-plugin-ledger` · 协议见 `docs/wire-format.md`
|
|
4
|
+
> 本文只写**为什么这么设计**和**数字怎么来的**,不写安装步骤(见 README)。
|
|
5
|
+
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
## 1. 问题定义
|
|
9
|
+
|
|
10
|
+
DSH 一次对话的成本不是「一条消息一个价」,而是四类互不重叠的 token 各自计价:
|
|
11
|
+
|
|
12
|
+
| 计量档 | 来源字段 | 单价(deepseek-v4-flash) |
|
|
13
|
+
|---|---|---|
|
|
14
|
+
| 未缓存输入 | `inputTokens` | 1 元 / 百万 |
|
|
15
|
+
| 缓存命中 | `cacheReadTokens` | 0.02 元 / 百万 |
|
|
16
|
+
| 缓存写 | `cacheWriteTokens` | 0(官方无独立写价) |
|
|
17
|
+
| 输出(含 reasoning) | `outputTokens` | 2 元 / 百万 |
|
|
18
|
+
|
|
19
|
+
宿主的 `TokenUsage` 注释明确 **counts are DISJOINT**(`@deepseek-ai/dsh-llm`),即 `inputTokens` 只含未命中部分。
|
|
20
|
+
这个事实决定了三件事:
|
|
21
|
+
|
|
22
|
+
1. **不能用平均价乘总数**。缓存命中的价格是未命中的 1/50,命中率越高,用平均价算出的金额错得越离谱。
|
|
23
|
+
2. **`cacheWriteTokens` 必须记 0 而不是"未命中价打折"**。DeepSeek 的缓存写入 token 已计入未命中输入,再给一个价就是重复计费。
|
|
24
|
+
3. **`reasoningTokens` 不单独计价**,它已含在 `outputTokens` 里(适配器口径)。
|
|
25
|
+
|
|
26
|
+
所以计价只有一种正确做法:**四档分开乘,再相加**。`lib/pricing.js` 的 `costOf()` 返回 `parts` 而不是单一金额,
|
|
27
|
+
就是因为面板必须能按四档分行显示,而费率只在 Host 进程里,浏览器半不能自己乘。
|
|
28
|
+
|
|
29
|
+
---
|
|
30
|
+
|
|
31
|
+
## 2. 三种「未知」必须区分
|
|
32
|
+
|
|
33
|
+
这是整个插件最核心的设计原则。同一个"没有数字",有三种完全不同的含义:
|
|
34
|
+
|
|
35
|
+
| 语义 | 表示 | 面板表现 | 为什么不能混 |
|
|
36
|
+
|---|---|---|---|
|
|
37
|
+
| 真的没有 | `0` | `¥0.0000` | cacheWrite 恒为 0,是事实 |
|
|
38
|
+
| 算不出来 | `null` + `reason` | `— no-rate` | 费率缺失,乘任何数都是编 |
|
|
39
|
+
| 完全不适用 | 不出现 | 不画这一行 | 压缩条目的金额本就不该对比 |
|
|
40
|
+
|
|
41
|
+
具体契约:
|
|
42
|
+
|
|
43
|
+
- `cost` 是联合类型:`{kind:'known', amount, parts, tier}` 或 `{kind:'unknown', reason}`,**永不退化成 0**
|
|
44
|
+
- `reason` 有四种:`no-usage`(事件没带 usage)、`usage-incomplete`(缺输入或输出)、`no-rate`(价表没这个模型)、`no-cost`(无成本字段)
|
|
45
|
+
- 合计金额在**一条已知条目都没有**时返回 `null`,面板显示「未计价」而不是 `¥0.0000`
|
|
46
|
+
- 有未知条目时合计旁边必须写「其中 N 条费率未知,合计偏低」——否则那个数字会被当成确定值
|
|
47
|
+
|
|
48
|
+
这条原则的代价是面板会出现"不完整"的观感,收益是:**一个敢说"我不知道"的账本,才配被拿去做决策。**
|
|
49
|
+
|
|
50
|
+
---
|
|
51
|
+
|
|
52
|
+
## 3. 缓存节省额:唯一能严格算出来的「省了多少钱」
|
|
53
|
+
|
|
54
|
+
### 3.1 数学
|
|
55
|
+
|
|
56
|
+
同一份 token,命中与未命中的差价是确定的:
|
|
57
|
+
|
|
58
|
+
```
|
|
59
|
+
saved = cacheReadTokens × (rate.input − rate.cacheRead)
|
|
60
|
+
= 15,660 × (1 − 0.02) 元/百万
|
|
61
|
+
= ¥0.0153
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
两个单价都在同一张价表里,**不需要任何假设**。这是账本里唯一一笔可以这样算出来的收益。
|
|
65
|
+
|
|
66
|
+
### 3.2 为什么压缩节省不给金额
|
|
67
|
+
|
|
68
|
+
压缩省下的是上下文 token(`contextBeforeTokens − 后续 input+cacheRead`),但**省下的那部分 token 属于"命中"还是"未命中"无法推断**:
|
|
69
|
+
|
|
70
|
+
- 压缩后第一次请求的命中率会被整体重算(摘要不再命中旧前缀)
|
|
71
|
+
- 省下的 token 若原本是缓存命中,价值只有 0.02 元/百万;若是未命中,是 1 元/百万
|
|
72
|
+
- 两者差 50 倍,硬乘任一个单价都是编数字
|
|
73
|
+
|
|
74
|
+
所以压缩只报 token 差(`压缩前 42.0k` / `↓省 24.0k`),**不折算金额**。这条边界写进了代码注释和 README。
|
|
75
|
+
|
|
76
|
+
### 3.3 占比
|
|
77
|
+
|
|
78
|
+
面板显示 `缓存命中已省 ¥0.0153 · 占应花 25.1%`:
|
|
79
|
+
|
|
80
|
+
```
|
|
81
|
+
savedShare = saved / (实花 + saved)
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
分母是「假如没有缓存本来要花的钱」。占比比绝对值有感知力——"省了三分之一"比"省了 1 分钱"更能让人相信缓存值得开。
|
|
85
|
+
|
|
86
|
+
`amount` 为 `null` 或 `≤ 0` 时整行不画,不写「已省 ¥0.0000」。
|
|
87
|
+
|
|
88
|
+
---
|
|
89
|
+
|
|
90
|
+
## 4. 处理链路与时序
|
|
91
|
+
|
|
92
|
+
```
|
|
93
|
+
宿主 session/event(post-commit 广播)
|
|
94
|
+
│
|
|
95
|
+
├─ ledger.onSessionEvent(session, event)
|
|
96
|
+
│ ├─ normalizeUsage() 归一 usage(disjoint 语义)
|
|
97
|
+
│ ├─ pricing.costOf() 四档计价 → known | unknown
|
|
98
|
+
│ ├─ pricing.savingsOf() 缓存节省额
|
|
99
|
+
│ ├─ attribution.forStep() 归因到插件
|
|
100
|
+
│ ├─ store.note() 入环形缓冲 + 累加 totals
|
|
101
|
+
│ ├─ guard.onEntry() 预算回滞判定
|
|
102
|
+
│ └─ trace.project() 脱敏 + 不可逆字段(可关)
|
|
103
|
+
│
|
|
104
|
+
├─ publisher.schedule(sessionId) 节流落盘(默认 3s)
|
|
105
|
+
│ └─ buildPanelPayload() → <cwd>/.dsh/ledger/<safe>.json
|
|
106
|
+
│
|
|
107
|
+
└─ 浏览器半:workspaceFiles.read() → renderPayload() → 面板
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
关键点:**所有订阅都在 post-commit 之后**,任何一环抛错都不会影响 Agent 主流程(`trace` 层全程 try/catch,
|
|
111
|
+
`ledger` 用 `failures` 计数而不是抛出)。
|
|
112
|
+
|
|
113
|
+
### 4.1 数据通道为什么落文件
|
|
114
|
+
|
|
115
|
+
浏览器半与 Host 是两个进程。已验证的事实(`docs/spikes.md` C-1..C-3):
|
|
116
|
+
|
|
117
|
+
- 浏览器侧不能直接读 `ctx.ledger`(跨进程)
|
|
118
|
+
- 自定义 Typert remote 需要生成产物 + zod 校验,纯 JS 仓库不划算
|
|
119
|
+
- `workspaceFiles` remote 可用:`list / stat / read(sessionId, absolutePath, range)`,相对路径以 Session 的 `cwd` 为基准
|
|
120
|
+
|
|
121
|
+
所以通道是「Host 落 JSON → 浏览器读回」。代价是面板数据有一个节流窗口(默认 3 秒),
|
|
122
|
+
收益是零自定义协议、零握手、断线仍能显示最后一帧。
|
|
123
|
+
|
|
124
|
+
---
|
|
125
|
+
|
|
126
|
+
## 5. 幂等与身份:三件不可逆的事
|
|
127
|
+
|
|
128
|
+
现在一条都不上报,但以下三项在采集时就写入(`docs/wire-format.md`),因为它们是**事后补不回来**的:
|
|
129
|
+
|
|
130
|
+
### 5.1 幂等键
|
|
131
|
+
|
|
132
|
+
```
|
|
133
|
+
eventId = sha1(sessionId | turn | step | operation)[0:16]
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
同一会话同一 `turn/step/类型`只可能产生一条事件。这条设计的唯一目标是应对**双端重复上报**
|
|
137
|
+
(Desktop + 云主机同时跑同一会话)——没有幂等键,金额会翻倍,而双端是这个产品最常见的真实场景。
|
|
138
|
+
|
|
139
|
+
### 5.2 中性计量
|
|
140
|
+
|
|
141
|
+
```
|
|
142
|
+
measures: [{unit:'token.input', value:9260}, {unit:'token.cache_read', value:15660}]
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
token 只是 `measures` 里的一种单位。计划中的第二个来源(Trae / Qoder / WorkBuddy / Cursor)多数**按席位订阅**,
|
|
146
|
+
没有 token 成本。单位表预留:`seat.month` / `seat.day`(席位)、`request`(按次)、`minute`(按时长)。
|
|
147
|
+
|
|
148
|
+
值为 0 不进数组(既无成本也无信息量),"缺字段"与"值为 0"由 `usage.complete` 区分。
|
|
149
|
+
|
|
150
|
+
### 5.3 身份线索
|
|
151
|
+
|
|
152
|
+
| 维度 | 首选 | 兜底 |
|
|
153
|
+
|---|---|---|
|
|
154
|
+
| `actor` | 仓库 `.git/config` 的 `user.email` | `~/.gitconfig` 的 `user.email` |
|
|
155
|
+
| `project` | git remote 归一成 `host/owner/repo` | `dir/<目录名>-<路径短hash>` |
|
|
156
|
+
| `deviceId` | `~/.dsh/ledger/device-id` | `sha1(hostname\|platform\|arch)` |
|
|
157
|
+
|
|
158
|
+
用 `git user.email` 的理由:所有 coding agent 都在 git 仓库里工作,这个线索跨工具一致,
|
|
159
|
+
**不依赖各工具自己的登录态**(Trae/Qoder 未必给你账号)。
|
|
160
|
+
|
|
161
|
+
实现上有两条硬约束:
|
|
162
|
+
|
|
163
|
+
1. **绝不 fork `git config` 子进程**。只同步读 `.git/config` 与 `~/.gitconfig` 两个几十字节的文件。
|
|
164
|
+
2. **绝不把绝对路径写进账本**。无 remote 时用 `dir/<basename>-<sha1(cwd)[:6]>`,hash 不可逆但稳定。
|
|
165
|
+
|
|
166
|
+
解析只发生在会话第一条事件(`identityBySession` 缓存),`session/disposed` 时释放。
|
|
167
|
+
|
|
168
|
+
---
|
|
169
|
+
|
|
170
|
+
## 6. 归因模型:为什么只认同轮上一步
|
|
171
|
+
|
|
172
|
+
`attribution.toolOwners` 把工具名映射到插件(唯一可得的归因依据)。默认按当前 step 的工具调用归因,
|
|
173
|
+
且**只认同一轮的上一步**(`store.toolsForStep(sessionId, turn, step − 1)`),跨轮不继承。
|
|
174
|
+
|
|
175
|
+
理由:模型调用发生在工具结果之后,归因链是「模型这次读了谁的结果」。上一步是对的;
|
|
176
|
+
再往前追是猜测——你无法证明第三步的模型调用是因为第一步的工具结果。
|
|
177
|
+
|
|
178
|
+
面板上因此有「多个插件共同(拆不开)」这一桶:一次调用读了 3 个插件的工具结果时,金额按结果体积分摊,
|
|
179
|
+
但标注为不可精确归因。
|
|
180
|
+
|
|
181
|
+
---
|
|
182
|
+
|
|
183
|
+
## 7. 性能设计
|
|
184
|
+
|
|
185
|
+
用户对性能的要求是硬约束:**热路径不许 IO、不许分配**。
|
|
186
|
+
|
|
187
|
+
### 7.1 环形缓冲
|
|
188
|
+
|
|
189
|
+
`store` 每会话保留固定容量(默认 2000 条),满了覆盖最旧一条。容量与事件数无关,
|
|
190
|
+
所以内存是**有界**的,不随会话变长而增长。`ring.js` 是纯数组 + 双指针,不用 `Array.shift()`(O(n))。
|
|
191
|
+
|
|
192
|
+
### 7.2 零分配热路径
|
|
193
|
+
|
|
194
|
+
踩过的一个坑:`trace.project()` 的参数是一个 15 字段对象字面量,**即使 trace 关闭也会构造**。
|
|
195
|
+
改为 `trace.enabled ? trace.project({...}) : null` 后:
|
|
196
|
+
|
|
197
|
+
| 场景 | 短路前 | 短路后 |
|
|
198
|
+
|---|---|---|
|
|
199
|
+
| 4 会话 / 20 万事件 | 1.76 µs | **1.35 µs** |
|
|
200
|
+
| 64 会话 / 20 万事件 | 1.41 µs | **1.28 µs** |
|
|
201
|
+
| 无限新会话(触发 LRU 淘汰) | 5.09 µs | **3.8 µs** |
|
|
202
|
+
| 单会话 1 万条 | 1.76 µs | 1.88 µs |
|
|
203
|
+
|
|
204
|
+
长会话略慢的 0.12µs 是身份与压缩字段的代价,仍在 8µs 阈值内。另一处优化:`pendingCompaction.size === 0`
|
|
205
|
+
时直接跳过 Map 访问,长会话从 2.37µs 回到 1.88µs。
|
|
206
|
+
|
|
207
|
+
### 7.3 实测基线(`node --expose-gc scripts/bench.mjs --gate`)
|
|
208
|
+
|
|
209
|
+
```
|
|
210
|
+
4 会话 / 混合同步事件 1.35 µs/event
|
|
211
|
+
64 会话 / 混合同步事件 1.28 µs/event
|
|
212
|
+
无限新会话 3.8 µs/event
|
|
213
|
+
单会话 1 万条 1.88 µs/event heap 增量 4.4 MB
|
|
214
|
+
300k 事件后留存 3.7 MB(强制 GC 后)
|
|
215
|
+
```
|
|
216
|
+
|
|
217
|
+
> 门禁必须带 `--expose-gc`。不带的话测到的是未回收垃圾(同一次跑能测出 42MB),
|
|
218
|
+
> 会把"GC 还没跑"误判成泄漏。
|
|
219
|
+
|
|
220
|
+
门禁阈值:稳定态 <6µs、LRU 抖动 <15µs、长会话 <8µs 且 <20MB/万条、留存 <32MB。
|
|
221
|
+
|
|
222
|
+
---
|
|
223
|
+
|
|
224
|
+
## 8. 面板的信息架构
|
|
225
|
+
|
|
226
|
+
自下而上四层,每层回答一个问题:
|
|
227
|
+
|
|
228
|
+
| 层 | 内容 | 回答 |
|
|
229
|
+
|---|---|---|
|
|
230
|
+
| 合计 | 总额 + 条数 + 偏低提示 + 缓存已省 | 这次会话贵不贵 |
|
|
231
|
+
| 预算 | 进度条 + 「已用 92% · 还可约 5 次」 | 还能问几次 |
|
|
232
|
+
| 四档 | 未缓存/命中/写/输出 + 命中率 | 钱花在哪一类 token |
|
|
233
|
+
| 谁花的 | 插件来源 + 占比(>6 个才出现「展开」) | 哪个插件在偷 |
|
|
234
|
+
| 最近 | 时间 + 轮次 + 金额 + `↑18.4k 字符` / `压缩前 42.0k` / `↓省 24.0k` | 哪一步、为什么贵 |
|
|
235
|
+
| 其他会话 | 跨会话对比 + 脚注(价表日期) | 别的会话什么水平 |
|
|
236
|
+
|
|
237
|
+
设计约束:
|
|
238
|
+
|
|
239
|
+
- **300px 极窄下必须能用**,所以明细第二行用 ellipsis 且把"为什么贵"的信息放最前(体量),归属放最后
|
|
240
|
+
- **「还能问几次」用 `knownEntries` 算均价**,未知条目不进均价,否则会把"还能问 8 次"算成"还能问 3 次"
|
|
241
|
+
- 余量为 0 时写「余量不足一问」,不写「还可约 0 次」
|
|
242
|
+
|
|
243
|
+
---
|
|
244
|
+
|
|
245
|
+
## 9. 验证手段
|
|
246
|
+
|
|
247
|
+
| 手段 | 覆盖 | 产出 |
|
|
248
|
+
|---|---|---|
|
|
249
|
+
| `node --test test/*.test.mjs` | 158 例断言 | 计价、归因、预算回滞、幂等、身份、卸载残留、面板 SSR |
|
|
250
|
+
| `scripts/bench.mjs --gate` | 热路径 + 内存 | 上表数字 |
|
|
251
|
+
| `scripts/smoke-registry.mjs` | 插件装配契约 | 假 ctx 下工具注册/提供不抛 |
|
|
252
|
+
| `scripts/smoke-dsh.mjs` | 宿主契约 | 右栏 tab、seat、事件形状 |
|
|
253
|
+
| `scripts/smoke-panel.mjs` | 面板链路 | PANEL-1..10:落盘 → 读回口径一致 |
|
|
254
|
+
| `scripts/render-panel.mjs` | 视觉 | 真实 `renderPayload()` 输出,三列宽度 |
|
|
255
|
+
|
|
256
|
+
**SKIP 不等于通过**:冒烟脚本找不到 DSH 运行时用退出码 2 表示 SKIP,`prepublish.sh` 第 6 步把 SKIP 判 FAIL。
|
|
257
|
+
这条是为了避免"换台机器 CI 照样全绿,但契约一条没验"。
|
|
258
|
+
|
|
259
|
+
---
|
|
260
|
+
|
|
261
|
+
|
|
262
|
+
## 10. 费率覆盖:把"算错钱"变成可见事件
|
|
263
|
+
|
|
264
|
+
内置价表带一个固定基准日(`BUILTIN_AS_OF`)。厂商一调价,所有用户看到的金额就**静默地**错了——
|
|
265
|
+
这是成本类产品最危险的一种错:数字还在,看起来还挺精确。`pricing.json` 解决的就是这件事。
|
|
266
|
+
|
|
267
|
+
**为什么整条生效或整条拒绝,不逐档合并。**
|
|
268
|
+
四档费率(`input` / `output` / `cacheRead` / `cacheWrite`)共同定义一个模型的价格语义。缺一档就合并,
|
|
269
|
+
等于拿旧价补新价——最终数字既不是旧价也不是新价,而且没有任何痕迹说明它是混合出来的。
|
|
270
|
+
所以校验失败时整条进 `rejected`:该模型 `costOf()` 返回 `unknown(no-rate)`,面板显示 `—`,
|
|
271
|
+
而不是一个"看起来像真的"数字。
|
|
272
|
+
|
|
273
|
+
**为什么 boot 时读一次,不 watch 文件。**
|
|
274
|
+
计价发生在每条 `assistant/message` 的热路径上,热路径不做 IO 是硬约束(见第 7 节)。
|
|
275
|
+
代价是改完费率要重启会话。这个代价换的是"每一笔计价都稳定"——而计价不稳定,
|
|
276
|
+
比多等一次重启危险得多。
|
|
277
|
+
|
|
278
|
+
**为什么失败也要显形(这是本节的重点)。**
|
|
279
|
+
"文件写坏了 → 静默回退内置价 → 面板照常显示金额",看起来是个体贴的降级,
|
|
280
|
+
实际上是在骗人:用户以为自己调过价了,拿着错数字去做判断。所以 `pricingMetaOf()` 对三种状态
|
|
281
|
+
**都**产出元信息(`kind:'file'` / `kind:'builtin'` / `kind:'builtin'` + `error`),面板据它在顶部画
|
|
282
|
+
琥珀色警示条,页脚只留"现在按什么价算"。信息层级是刻意的:异常在上,来源在下,
|
|
283
|
+
不把原因塞进 10.5px 的灰字里。
|
|
284
|
+
|
|
285
|
+
**自查出口。** `ledger_query` 的 `op: 'rates'` 返回当前生效表(还原成元/百万,和官方公告同单位)、
|
|
286
|
+
来源与基准日、被忽略的模型及原因码(`fields-missing` / `field-invalid` / `negative` / `bad-json` / …)。
|
|
287
|
+
这样"我改了价但数字没变"有了一条可查证的路径,不会变成悬案。
|
|
288
|
+
|
|
289
|
+
---
|
|
290
|
+
|
|
291
|
+
## 11. 已知限制
|
|
292
|
+
|
|
293
|
+
1. **归因只到插件级**:宿主不提供工具归属信息,跨轮不继承。
|
|
294
|
+
2. **面板数据有 3 秒节流**:故意如此,热路径不落盘。
|
|
295
|
+
3. **内置价表带固定基准日** `2026-11-19`:厂商调价可写 `~/.dsh/ledger/pricing.json` 覆盖,
|
|
296
|
+
无需改代码;写坏了会在面板顶部警示而不是静默回退。仍是"人工提供价格",不假装实时。
|
|
297
|
+
4. **`private: true` 未改**:npm registry 未定。代码仓已在 Gitee。
|
|
298
|
+
5. **未真机验证五项**(`ctx.tools.register` 真注册、真进程全量派发、`ctx.provide` 冲突、
|
|
299
|
+
宿主是否真给 `ctx.slots`、插件侧 `workspaceFiles` 权限)——都需能 boot DSH 且带凭据的进程。
|
|
300
|
+
6. **团队版零代码**:身份、上报、聚合、对账均未开工(有意为之,见商业计划书)。
|
|
301
|
+
|
|
302
|
+
---
|
|
303
|
+
|
|
304
|
+
|
|
305
|
+
## 12. 真机作为最终裁判:四处被单测掩盖的偏差
|
|
306
|
+
|
|
307
|
+
第一次把插件装进真实宿主跑通之后,暴露了四个单测没有任何办法发现的问题。
|
|
308
|
+
本节留档不是为了追责,而是因为**同一个错误模式还会再犯**:用自己假设的契约写测试,
|
|
309
|
+
测试全绿,线上全空。
|
|
310
|
+
|
|
311
|
+
**12.1 `session/event` 的载荷在 `data` 里。**
|
|
312
|
+
类型声明写的是扁平 `{turn, step, message}`;运行时实际派发
|
|
313
|
+
`{type, seq, time, data: {turn, step, message, usage, stream}, surfaceOp}`。
|
|
314
|
+
后果是灾难性的安静:每条模型调用都记成 `unknown(no-usage)`、金额整片 `null`,
|
|
315
|
+
而 158 例单测依然全绿——因为它们喂的是扁平形状。
|
|
316
|
+
修法不是二选一,而是两种都认(`payloadOf()`:`data` 是普通对象就用它,否则退回事件本身),
|
|
317
|
+
并用真机抓到的原始事件建立一个专门的 `event/shape` 测试文件固定它。
|
|
318
|
+
|
|
319
|
+
**12.2 金额精度不能吞掉小额。**
|
|
320
|
+
单步模型调用常在 1e-5 量级,缓存命中那一档只有 `3.2e-5` 元。`toFixed(4)` 把它显示成
|
|
321
|
+
`¥0.0000` —— 用户读到的是"这一步没花钱"。这和"未知显示成 0"是同一类错误:
|
|
322
|
+
**显示一个不存在的 0,就是撒谎。** 改为按量级自适应(<0.001 给 6 位,<1e-6 给科学计数)。
|
|
323
|
+
|
|
324
|
+
**12.3 `generatedAt` 类型不一致。**
|
|
325
|
+
`store.snapshot()` 给 `Date.now()` 数字,面板按字符串截取显示。真机上页脚是
|
|
326
|
+
"快照生成于 —" —— 数据明明在,看起来却像坏了。在快照组装层统一转 ISO,让消费方只面对一种类型。
|
|
327
|
+
|
|
328
|
+
**12.4 同一块面板两套时间口径。**
|
|
329
|
+
页脚用 UTC 的 ISO(`07:35`),明细行用本地时间戳(`15:35`)。差 8 小时,用户只会以为数据错。
|
|
330
|
+
新增 `formatLocalTime()`,一律本地时区——**同一个面板里只能有一套时间口径**。
|
|
331
|
+
|
|
332
|
+
### 工程侧的一条硬约束
|
|
333
|
+
|
|
334
|
+
`dsh plugin --profile <p> add file:<path>` 是 pnpm 的 `file:` 依赖:**文件硬链接、目录复制**。
|
|
335
|
+
所以改已有文件即时生效,**新增文件不会同步**,重装才能看到。
|
|
336
|
+
副作用是反的也要小心:直接改 profile 里的副本,等于在改源仓库(同 inode)。
|
|
337
|
+
症状是启动告警 `failed to import`。
|
|
338
|
+
|
|
339
|
+
---
|
|
340
|
+
|
|
341
|
+
## 附:文件职责
|
|
342
|
+
|
|
343
|
+
```
|
|
344
|
+
lib/index.js 装配、取数、清理(session/disposed 统一释放 guard/store/publisher/ledger)
|
|
345
|
+
lib/ledger.js 事件订阅 → 归一 → 计价 → 归因 → 入账;压缩对照与身份缓存
|
|
346
|
+
lib/store.js 环形缓冲、totals 累加、跨会话 overview、trace 窗口
|
|
347
|
+
lib/pricing.js 四档计价 + 缓存节省额;未知一律返回 reason
|
|
348
|
+
lib/pricing-table.js 内置官方价(含来源与日期)
|
|
349
|
+
lib/pricing-file.js pricing.json 覆盖:元/百万入、整条校验、失败留痕(boot 读一次)
|
|
350
|
+
lib/attribution.js 工具 → 插件映射,同轮上一步归因,不可归因分桶
|
|
351
|
+
lib/guard.js 预算回滞(超阈值只投递一次,ratio < 0.9×阈值才重新武装)
|
|
352
|
+
lib/budget-message.js 预算消息文案(降级建议)
|
|
353
|
+
lib/snapshot-file.js 快照构建/压缩/落盘/读回;withPanelTotals 派生字段
|
|
354
|
+
lib/panel-view.js 纯展示函数 + 组件工厂(renderPayload 为纯函数,可 SSR 断言)
|
|
355
|
+
lib/client.js 浏览器半入口:createFetchView / apply
|
|
356
|
+
lib/panel-path.js 安全文件名与目录解析
|
|
357
|
+
lib/trace.js 脱敏 + 不可逆字段落盘
|
|
358
|
+
lib/trace-file.js JSONL 缓冲写盘(队列有界,满了丢最旧并计数)
|
|
359
|
+
lib/wire.js 上报协议(measures/幂等键/白名单投影)
|
|
360
|
+
lib/identity.js actor/project/deviceId 线索(不 fork 子进程)
|
|
361
|
+
lib/tool-size.js 工具结果体积(只数 text 块)
|
|
362
|
+
lib/usage.js usage 归一(disjoint 语义)
|
|
363
|
+
lib/ring.js 定容环形缓冲
|
|
364
|
+
```
|
|
@@ -0,0 +1,95 @@
|
|
|
1
|
+
# 上报协议 v1(已冻结,未启用)
|
|
2
|
+
|
|
3
|
+
现在一条数据都不发。这个文件存在的唯一理由:**协议形状是不可逆的**。字段名一旦写进历史流水,
|
|
4
|
+
后面想从 `inputTokens` 改成 `measures[]`,老数据永远迁不干净。
|
|
5
|
+
|
|
6
|
+
代码:`lib/wire.js`(协议)、`lib/identity.js`(身份线索)、`lib/trace.js`(落盘行)。
|
|
7
|
+
|
|
8
|
+
## 为什么要先冻结,哪怕只有 DSH 一个来源
|
|
9
|
+
|
|
10
|
+
计划中的第二个来源(Trae / Qoder / WorkBuddy / Cursor)**大多不按 token 计费**,而是席位订阅。
|
|
11
|
+
如果协议主键是 token,第二类工具根本进不来。所以计量的载体必须是「单位 + 数值」:
|
|
12
|
+
|
|
13
|
+
```jsonc
|
|
14
|
+
// 本地流水行(.trace.jsonl,已带全部不可逆字段)
|
|
15
|
+
{
|
|
16
|
+
"timestamp": "2026-11-19T05:52:00.000Z",
|
|
17
|
+
"sessionId": "session-9f2a41",
|
|
18
|
+
"turn": 2, "step": 1,
|
|
19
|
+
"wireVersion": 1,
|
|
20
|
+
"eventId": "9c1e4f7a2b3d8e05", // 幂等键
|
|
21
|
+
"measures": [ // 中性计量,token 只是其中一种单位
|
|
22
|
+
{ "unit": "token.input", "value": 9260 },
|
|
23
|
+
{ "unit": "token.output", "value": 1462 },
|
|
24
|
+
{ "unit": "token.cache_read", "value": 15660 }
|
|
25
|
+
],
|
|
26
|
+
"deviceId": "a1b2c3d4e5f60789",
|
|
27
|
+
"actor": { "email": "lin@example.com", "source": "git-local" },
|
|
28
|
+
"project": { "key": "github.com/lingdaai/dsh-plugin-ledger", "source": "git-remote" },
|
|
29
|
+
"gen_ai.operation.name": "chat",
|
|
30
|
+
"gen_ai.agent.name": "@lingzhi/tools/hr",
|
|
31
|
+
"cost": { "amount": 0.0235, "currency": "CNY" },
|
|
32
|
+
"costUnknownReason": null,
|
|
33
|
+
"summary": "deepseek/deepseek-v4-pro" // 已脱敏截断,**不上报**
|
|
34
|
+
}
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
## 三条硬规则
|
|
38
|
+
|
|
39
|
+
### 1. 幂等键
|
|
40
|
+
|
|
41
|
+
```
|
|
42
|
+
eventId = sha1(sessionId | turn | step | operation)[0:16]
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
同一会话同一 turn/step/类型只可能产生一条。双端(Desktop + 云主机)重复上报必须落成同一个 id,
|
|
46
|
+
服务端主键冲突即丢弃。**没有这条,账会翻倍**——而双端重复是这个产品最常见的真实场景。
|
|
47
|
+
|
|
48
|
+
### 2. 计量用 `measures[]`,不用 token 专用字段
|
|
49
|
+
|
|
50
|
+
| 单位 | 含义 |
|
|
51
|
+
|---|---|
|
|
52
|
+
| `token.input` / `token.output` / `token.cache_read` / `token.cache_write` | 按量(DSH 类) |
|
|
53
|
+
| `seat.month` / `seat.day` | 席位订阅(Cursor / WorkBuddy 类) |
|
|
54
|
+
| `request` | 按次 |
|
|
55
|
+
| `minute` | 按时长(云开发环境) |
|
|
56
|
+
|
|
57
|
+
值为 0 不进数组(既没成本也没信息量)。「字段缺失」与「值为 0」的区别由 `usage.complete` 承载。
|
|
58
|
+
|
|
59
|
+
**席位成本与按量成本不能加成一个「单价」**:把 $20/月的 seat 摊到 token 上,必须先假设「这个月跑了多少
|
|
60
|
+
token」,那个假设就是编数字。两轨各自出账,汇总时给两个数(边际成本 / 总拥有成本),并明示口径。
|
|
61
|
+
|
|
62
|
+
### 3. 上报投影走白名单,服务端结构上收不到文本
|
|
63
|
+
|
|
64
|
+
`wireEventOf(row)` 只输出:`wireVersion / eventId / timestamp / source / deviceId / actor / project /
|
|
65
|
+
sessionId / turn / step / operation / plugin / measures / cost / costUnknownReason`。
|
|
66
|
+
|
|
67
|
+
**不带 `summary`,不带 `gen_ai.*` 原始字段**。工具输出原文永远不出本地(只有 `contextChars` 这个数字
|
|
68
|
+
会进快照,且从不进流水)。
|
|
69
|
+
|
|
70
|
+
## 身份线索的优先级
|
|
71
|
+
|
|
72
|
+
| 维度 | 首选 | 兜底 | 为什么 |
|
|
73
|
+
|---|---|---|---|
|
|
74
|
+
| actor(是谁) | 仓库 `.git/config` 的 `user.email` | `~/.gitconfig` 的 `user.email` | 所有 coding agent 都在 git 仓库里工作,这个线索跨工具一致,不依赖各工具自己的登录态 |
|
|
75
|
+
| project(哪个项目) | git remote 归一成 `host/owner/repo` | `dir/<目录名>-<路径短hash>` | remote 跨机器、跨目录重命名都一致;兜底键**绝不带绝对路径**(用户目录结构属隐私) |
|
|
76
|
+
| deviceId | `~/.dsh/ledger/device-id` | `sha1(hostname\|platform\|arch)` | 换进程不变;写不了盘时仍稳定,不用随机数 |
|
|
77
|
+
|
|
78
|
+
实现细节:**只读几十字节的配置文件,绝不 fork `git config` 子进程**。解析在会话第一条事件上发生一次,
|
|
79
|
+
之后只有一次 Map 读。缓存有界(默认 64 个 cwd)。
|
|
80
|
+
|
|
81
|
+
## 新增一个来源要做什么
|
|
82
|
+
|
|
83
|
+
1. 写映射:把该工具的事件 → 上面那个行结构(`measures` 用对应单位,`cost` 允许 unknown);
|
|
84
|
+
2. 提供身份线索:能拿到 git email / 工作区路径就给,拿不到就给 `deviceId`,**不许猜一个人出来**;
|
|
85
|
+
3. 复用 `wire.js` 的 `eventIdOf` / `measuresOf` / `wireEventOf`,不要自己发明幂等规则。
|
|
86
|
+
|
|
87
|
+
一个 adapter 的合理体量是 200 行左右的映射函数,重活(幂等、游标、重试、脱敏)都在共享层。
|
|
88
|
+
|
|
89
|
+
## 尚未做的部分(等验证通过再做)
|
|
90
|
+
|
|
91
|
+
- 上报客户端(读 `.trace.jsonl` → 批量 POST → 游标推进,旁路定时器,**热路径零改动**)
|
|
92
|
+
- 聚合服务(`POST /v1/ingest`、`events` 表、rollup、对账)
|
|
93
|
+
- 席位摊销的会计口径与「边际成本 / 总拥有成本」两个视图
|
|
94
|
+
|
|
95
|
+
这些都可逆,不提前垫资。先让单工具的账本被真正用起来。
|
|
@@ -0,0 +1,73 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* 归因。
|
|
3
|
+
*
|
|
4
|
+
* P-2 探针结论(源码证据见 docs/spikes.md):
|
|
5
|
+
* - `tool/call` 会话事件只带 {turn, step, callId, name, arguments},**没有插件身份**;
|
|
6
|
+
* - `tools/change` 是无载荷的全局通知,不告诉你是谁注册/注销;
|
|
7
|
+
* - `tools.register()` 返回 disposer,但注册来源只存在于调用方的 ctx scope,
|
|
8
|
+
* 外部插件无法从公开 API 反查。
|
|
9
|
+
*
|
|
10
|
+
* 结论:**插件级归因无法从公开契约获得**。首版只做两种可信粒度:
|
|
11
|
+
* 1) exact —— 配置里显式声明 toolOwners 的工具名映射;
|
|
12
|
+
* 2) none —— 其余一律 unresolved,宁可空着也不编。
|
|
13
|
+
*
|
|
14
|
+
* "共享上下文"不是精度问题,是事实:多个插件共同贡献 prompt/schema 时,
|
|
15
|
+
* 成本无法拆分,只能标注。
|
|
16
|
+
*/
|
|
17
|
+
|
|
18
|
+
/**
|
|
19
|
+
* @param {{toolOwners?: Record<string, string>}} config
|
|
20
|
+
*/
|
|
21
|
+
export function createAttribution(config = {}) {
|
|
22
|
+
const owners = new Map(Object.entries(config.toolOwners ?? {}))
|
|
23
|
+
|
|
24
|
+
function forTool(name) {
|
|
25
|
+
const owner = owners.get(name)
|
|
26
|
+
if (owner) {
|
|
27
|
+
return { primary: { plugin: owner, confidence: 'exact' }, sharedContext: [], system: null }
|
|
28
|
+
}
|
|
29
|
+
return { primary: null, sharedContext: [], system: null, unresolvedReason: 'no-origin' }
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
/**
|
|
33
|
+
* 模型调用归因。
|
|
34
|
+
* @param {{toolNames?: string[]}} input 触发本次请求的上一轮工具集
|
|
35
|
+
*/
|
|
36
|
+
function forModel({ toolNames = [] } = {}) {
|
|
37
|
+
const owned = []
|
|
38
|
+
const unknown = []
|
|
39
|
+
for (const name of toolNames) {
|
|
40
|
+
const owner = owners.get(name)
|
|
41
|
+
if (owner) {
|
|
42
|
+
if (!owned.includes(owner)) owned.push(owner)
|
|
43
|
+
} else {
|
|
44
|
+
unknown.push(name)
|
|
45
|
+
}
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
if (owned.length === 1 && unknown.length === 0) {
|
|
49
|
+
return { primary: { plugin: owned[0], confidence: 'exact' }, sharedContext: [], system: null }
|
|
50
|
+
}
|
|
51
|
+
if (owned.length > 1) {
|
|
52
|
+
return {
|
|
53
|
+
primary: null,
|
|
54
|
+
// 多插件共同贡献 → 只能标注为共享成本,不排序、不给百分比
|
|
55
|
+
sharedContext: owned.map((plugin) => ({ plugin, note: 'shared-context-cost' })),
|
|
56
|
+
system: null,
|
|
57
|
+
unresolvedReason: 'multi-contributor',
|
|
58
|
+
}
|
|
59
|
+
}
|
|
60
|
+
return {
|
|
61
|
+
primary: null,
|
|
62
|
+
sharedContext: unknown.map((tool) => ({ plugin: `tool:${tool}`, note: 'unlisted-tool' })),
|
|
63
|
+
system: null,
|
|
64
|
+
unresolvedReason: unknown.length ? 'no-origin' : 'no-signal',
|
|
65
|
+
}
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
function forCompaction() {
|
|
69
|
+
return { primary: null, sharedContext: [], system: 'compaction' }
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
return { forTool, forModel, forCompaction }
|
|
73
|
+
}
|