@lingda-ai/dsh-plugin-ledger 0.1.11 → 0.1.13

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.
@@ -0,0 +1,124 @@
1
+ # 对账 PoC 作战手册(2 周 / 3 家)
2
+
3
+ > 目的:用**接近零的工程成本**验证一个假设——
4
+ > **"跨工具、可对账的成本表"有人愿意付钱。**
5
+ >
6
+ > 不做服务端、不做多租户、不做 UI。只有一份报告和六个问题。
7
+
8
+ ## 0. 为什么先做这个,而不是先写服务端
9
+
10
+ 团队版要投 8–12 人日(上报通道 + 聚合服务)。在写之前必须先知道:**谁付钱、为什么付、付多少。**
11
+ 这三件事只能靠真人对话回答,不能靠代码回答。一份手工报告就能把对话变成证据。
12
+
13
+ ## 1. 目标客户画像(必须先满足,否则聊了也白聊)
14
+
15
+ | 条件 | 为什么 |
16
+ |---|---|
17
+ | 5–50 人研发团队 | 少于 5 人没人管账;多于 50 人走采购流程,周期太长 |
18
+ | **同时用 2 种以上 AI 编程工具** | 单一工具的用户厂商控制台就够了,那是我们唯一的结构性差异 |
19
+ | 月 AI 支出 ≥ ¥2000 | 低于这个数,"管账"是伪需求 |
20
+ | **能拿到上个月的账单**(CSV 或明细页) | 拿不到账单的人,永远不会有对账需求 |
21
+
22
+ > 反例:个人开发者、纯订阅制(按席位)团队、还没有账单的人。这三类直接跳过。
23
+
24
+ ## 2. 找到 3 家(不要冷启动)
25
+
26
+ 优先级:① 你认识的技术负责人 → ② 社区里问过"AI 账单怎么管"的人 → ③ 朋友圈/群里的团队 leader。
27
+
28
+ 开场话术(不要推销,要数据):
29
+
30
+ > 我在做一个 AI 编程成本的对账工具,想免费帮你出一份上个月的对账报告——
31
+ > 你把账单 CSV 给我,我给你一份"每天本地估算 vs 账单实际"的差异表,加三条洞察。
32
+ > 不需要你装任何东西,数据我当场处理完就删。你只要给我 30 分钟聊一下结论准不准。
33
+
34
+ **这一步的目标不是成交,是拿到 3 份真实账单。**
35
+
36
+ ## 3. 客户要给什么(最小集)
37
+
38
+ 1. 上个月账单导出(CSV 最好;截图也行,人工转录);
39
+ 2. 30 分钟访谈;
40
+ 3. (可选)一份"你觉得这钱花得值不值"的主观判断。
41
+
42
+ **不要**代码、不要对话记录、不要账号权限。只要金额。
43
+
44
+ ## 4. 我们交付什么
45
+
46
+ 用 `scripts/reconcile.mjs` 生成一份报告(示例见下):
47
+
48
+ ```bash
49
+ # 1) 客户装了插件的话,直接读本地归档
50
+ node scripts/reconcile.mjs --bill 客户账单.csv --from 2026-11-01 --to 2026-11-30 --out 报告.md
51
+
52
+ # 2) 客户没装:先用他给的用量明细(模型+token)估一份本地口径
53
+ # 这一步在 PoC 阶段允许人工做——我们的目标不是自动化,是验证价值
54
+ ```
55
+
56
+ 报告结构(脚本已生成):
57
+
58
+ - 按天的 **本地采集 / 厂商账单 / 差异 / 差异率**
59
+ - **未计价条数**(算不出来的部分,绝不当 0 混进总额)
60
+ - 模型分布(哪些模型在吃钱)
61
+ - "怎么读这份报告"三行说明(把口径写在客户眼前,这本身是信任来源)
62
+
63
+ **再补三条人工洞察**(这才是客户愿意付钱的部分):
64
+
65
+ 1. 差异最大的一天,那天发生了什么(模型切换?批量任务?缓存失效?)
66
+ 2. 有没有"贵但没产出"的模式(同一段上下文反复重发)
67
+ 3. 如果换一种用法(缓存友好 / 模型降级),这个月大概能省多少
68
+
69
+ ## 5. 30 分钟访谈提纲(按顺序问,别跳)
70
+
71
+ 1. **现在你怎么知道这个月 AI 花了多少?**(听他说"看厂商后台/月底才知道/不知道")
72
+ 2. **上一次你因为 AI 成本做过什么决定?**(没有决定 = 没有痛点)
73
+ 3. **如果发现某个项目/某个人花的钱明显超标,你会怎么处理?**(听"管不管得动")
74
+ 4. **这份报告和你现在看到的账单,差在哪?**(评估我们的信息增量)
75
+ 5. **如果不给你这份报告,你会怎么把这件事做出来?**(替代成本 → 定价锚点)
76
+ 6. **这份报告如果每月一份,谁批这个预算?大概什么量级?**(不要问"你会付吗")
77
+
78
+ > 第 5、6 题是定价探针。**不要主动报价**,让他先说数字或让沉默多停 3 秒。
79
+
80
+ ## 6. 信号判定(2 周后看这个)
81
+
82
+ | 结论 | 判据 |
83
+ |---|---|
84
+ | **PASS** | ≥1 家愿意付 ¥2000 试水(哪怕只是买 3 个月报告);或 ≥2 家明确说"下个月还要"并愿意给账单 |
85
+ | **WEAK** | 3 家都说"有意思",但没人愿意给钱或给数据 |
86
+ | **FAIL** | 拿不到 3 份账单;或都说"厂商后台够了" |
87
+
88
+ - PASS → 立刻投 P3(上报通道 + 聚合服务),因为付费意愿已验证。
89
+ - WEAK → 回头做 P0/P1(把单机体验做到值得付费),**不要**写服务端。
90
+ - FAIL → 停止 SaaS 方向,转"高质量开源工具 + 内容/咨询"。
91
+
92
+ ## 7. 合规与隐私(第一次沟通就要说清)
93
+
94
+ - 只处理**汇总金额**;不碰代码、不碰对话、不碰账号。
95
+ - 数据在**本地**处理,报告发出后删除原件(或客户自己保管)。
96
+ - 客户若已装插件:归档在 `~/.dsh/ledger/archive/`,只有 token 数与金额,没有对话内容;`actor`(git email)默认不写。
97
+ - 报告里不出现人名(除非客户明确要求做"按人"视图)。
98
+
99
+ ## 8. 时间盒
100
+
101
+ | 天 | 动作 |
102
+ |---|---|
103
+ | D1–D2 | 列出 10 个候选,按"有账单 + 多工具"筛出 3 个,发出开场话术 |
104
+ | D3–D7 | 收账单、跑报告、补三条洞察 |
105
+ | D8–D12 | 三家各 30 分钟访谈,记录原话(尤其是第 5、6 题) |
106
+ | D13–D14 | 汇总信号 → PASS / WEAK / FAIL,写进 `docs/poc-results.md` |
107
+
108
+ ## 9. 你会得到什么(即使全部 FAIL)
109
+
110
+ 1. 3 份真实账单的**口径差异**(价表准不准、缓存计价对不对)——这是产品最缺的校验数据;
111
+ 2. 一句能写进 README 的话:「我们和 3 家团队对过账,差异率从 X% 降到 Y%」;
112
+ 3. 一个明确决定:写不写服务端。**这比再写 10 个功能值钱。**
113
+
114
+ ## 附:报告样例(合成数据)
115
+
116
+ ```markdown
117
+ | 日期 | 本地采集 | 厂商账单 | 差异 | 差异率 | 条数 | 未计价 |
118
+ |---|---:|---:|---:|---:|---:|---:|
119
+ | 2026-11-18 | 0.0084 | 0.0087 | -0.0003 | -3.4% | 3 | 1 |
120
+ | 2026-11-19 | 0.0051 | 0.0053 | -0.0002 | -3.8% | 1 | 0 |
121
+ | **合计** | **0.0135** | **0.0140** | **-0.0005** | **-3.6%** | | **1** |
122
+ ```
123
+
124
+ 差异为负的解释固定两条:**价表滞后**、**未计价条目**——这两条恰好也是我们要在 P0 里修的东西。
@@ -0,0 +1,216 @@
1
+ # 产品迭代路线(0.2 → 1.0)
2
+
3
+ > 定位不变:**AI 编程的成本仪表盘,从"这个会话为什么贵"做到"这个团队的钱花得值不值"。**
4
+ > 本文只写"按什么顺序做、做到什么算完",商业模型见 `business-plan.md`,技术取舍见 `technical.md`。
5
+
6
+ ## 0. 现状(0.1.12,2026-11)
7
+
8
+ 已经能回答"这次会话花了多少",但只回答了**一个会话**、**一个瞬间**、**一个屏幕**。
9
+
10
+ | 能力 | 状态 | 限制 |
11
+ |---|---|---|
12
+ | 单会话四档计价 + 缓存节省 | ✅ | 依赖价表命中模型名;未知一律显式 `—` |
13
+ | 右栏面板(标题/约几分/距现在/复制摘要) | ✅ | 只读一个会话;数据来自 3 秒节流的快照 |
14
+ | `ledger_query`(4 个 op) | ✅ | Agent 主动查,不是用户主动看 |
15
+ | 费率覆盖 `pricing.json` | ✅ | boot 时读一次,改完要重启 |
16
+ | 预算守卫(阈值 + 降级) | ⚠️ 代码在,**产品上没有入口** | 需手写 YAML;通道 A 还需宿主提供 messageFactory |
17
+ | 行为流水 trace | ⚠️ 默认关,开了会累积 | 字节上限按字符算(CJK 会超),会话结束不清理 |
18
+ | 历史 / 跨会话总账 | ❌ | 会话结束**快照即删**,昨天花了多少无从查起 |
19
+ | 导出 / 周报 | ❌ | 只有一个"复制摘要"按钮 |
20
+ | 团队聚合 / 上报 | ❌ | `wire.js` 协议是死代码,一条不发 |
21
+
22
+ **一句话**:单点体验刚跑通,产品能力还是一条竖线(一个会话),不是一个面(时间 × 项目 × 人)。
23
+
24
+ ## 1. 判断依据(为什么是这个顺序)
25
+
26
+ 三条来自真实使用与三轮审计的证据:
27
+
28
+ 1. **"装完看不到数"是最大流失点**。这件事我们花了 5 个版本才修好(ESM 产物 → inject → remote 访问 → 轮询竞态)。**同类问题不能靠人肉排查**,必须有自检和门禁。
29
+ 2. **用户看完数字不会改行为**。面板给出"缓存已省 97%",但没人因此改过一次用法。价值闭环缺"下一步该做什么"。
30
+ 3. **没有历史就没有商业**。团队版要卖的是"这周花了多少、该不该管",而当前连"昨天"都查不到。
31
+
32
+ ## 2. 路线图总览
33
+
34
+ | 阶段 | 版本 | 主题 | 工程量 | 出口标准 |
35
+ |---|---|---|---|---|
36
+ | **P0** | 0.2.x | 把地基打牢:可信、可查、可诊断 | 8–10 人日 | 崩溃 0;面板首次有数率 ≥95%;CI 门禁不再假红 |
37
+ | **P1** | 0.3.x | 从"看见"到"改变":预算 + 省钱建议 | 10–12 人日 | 有用户因为面板改了行为(预算配置率/建议采纳率 >0) |
38
+ | **P2** | 0.4.x | 个人版完整:历史、总账、导出 | 12–15 人日 | 能回答"本周/本月花了多少",可导出周报 |
39
+ | **P3** | 0.5.x–1.0 | 团队版底座:上报 + 聚合 + License | 8–12 周 | 3–5 家种子客户能用一页总表 |
40
+
41
+ **闸门**:P3 不先开工。触发条件是 `business-plan.md` 的 M2 验证——**≥5 个外部用户持续使用两周**。达不到就回补 P1/P2。
42
+
43
+ ---
44
+
45
+ ## P0 · 0.2.x 打地基(先做这个)
46
+
47
+ > 目标:让"这个面板是不是坏了"从一个人肉排查的问题,变成一个能自己说话的产品。
48
+
49
+ ### P0-1 自检报告(doctor)|S|下一项
50
+
51
+ **问题**:过去 5 轮故障里,用户能看到的只有"没数据"或一句英文错误。
52
+
53
+ **做法**:面板底部加一个可折叠的「诊断」区,一行一项,绿/黄/红:
54
+
55
+ | 检查项 | 判据 |
56
+ |---|---|
57
+ | Host 半已加载 | `ctx.ledger` 服务存在(面板能拿到快照就说明在) |
58
+ | 快照通道 | 最近一次 `fetchView` 的耗时与结果(成功/错误码) |
59
+ | 快照新鲜度 | `generatedAt` 距今 > 60s 标黄,> 10min 标红 |
60
+ | 费率来源 | 内置 / 自定义文件 / 自定义文件被拒(附原因码) |
61
+ | 价表命中 | 最近 N 条里有几条 `no-rate`;模型名与价表差在哪 |
62
+ | 预算 | 未配置 / 已用 X% |
63
+ | 落盘目录 | 实际路径 + 文件是否存在 |
64
+
65
+ **验收**:新增 `test/panel-doctor.test.mjs`(三种状态各断言一次);README 加一节「面板没数怎么自查」,把支持成本从"问我"变成"看这里"。
66
+
67
+ **为什么不先做别的**:它直接决定"用户遇到问题会不会卸载",而且实现只是把已有信息组织起来,风险最低。
68
+
69
+ ### P0-2 历史落到磁盘(持久化)|M|✅ 0.1.13 已落地
70
+
71
+ **问题**:`session/disposed` 时快照被删除,账本只在内存。昨天、上周的钱查不到。
72
+
73
+ **做法**:新增 `<dshHome>/ledger/archive/YYYY-MM-DD.jsonl`(或一个 SQLite,二选一):
74
+
75
+ - 每条 = `{ sessionId, sessionTitle, at, kind, route, usage, cost, attribution }`(**不含任何对话文本**,与 trace 同口径)
76
+ - 写盘走现有 `trace-file` 的"入队 + 合并写",热路径零 IO
77
+ - 会话结束把当次快照并入归档,再删除工作区快照
78
+ - 保留策略:默认 90 天,超出按日期裁剪
79
+
80
+ **验收**:`test/archive.test.mjs`——跨会话写入、按天分片、90 天裁剪、损坏行跳过不炸、热路径基准不退化(`bench --gate` 相对基线)。
81
+
82
+ **取舍**:不做数据库迁移框架,先 JSONL;真到百万行再换 SQLite(那时正好是团队版)。
83
+
84
+ ### P0-3 修掉审计遗留的中危项|S|一次性清账
85
+
86
+ | 项 | 现状 | 修法 |
87
+ |---|---|---|
88
+ | trace 字节上限用字符数 | CJK 下 64KB 上限写出 120KB | 改用 `Buffer.byteLength`,并补 CJK 用例 |
89
+ | trace 文件不回收 | 单文件 4MB 封顶,但会话结束不删 | 归档/删除策略与 P0-2 合并 |
90
+ | `pricingMetaOf` 丢 `detail` | `read-failed` 的 `EACCES` 到不了面板(两处死代码) | 透传 `detail`,面板显示原因 |
91
+ | `store.recordEntry` 收未归一化 usage | `cacheRead` 可能是 NaN,污染整会话汇总 | 入口归一化或断言 |
92
+ | `panel.dir` 与客户端读路径 | 已告警,但自定义 dir 面板仍读不到 | 客户端从 payload 里的 `panelDir` 读,或干脆禁用非默认值 |
93
+ | LRU / 8 步窗口 / 容量边界 | 无测试 | 按审计清单补 `store-bounds.test.mjs` |
94
+
95
+ **验收**:以上每条都有对应测试;`bash scripts/ci.sh` 全绿。
96
+
97
+ ### P0-4 门禁不再假红|S
98
+
99
+ **问题**:`bench --gate` 用绝对阈值,机器一忙就红(实测 load 88 时 LRU 抖动 15.8µs vs 阈值 15µs),久了大家会忽略它。
100
+
101
+ **做法**:改成**相对基线**——记录上次通过的基线(`.bench-baseline.json`),本次超过基线 1.3 倍才失败;基线只在 main 上更新。
102
+
103
+ **验收**:同一台机器连跑 5 次不出现假红;人为注入 2 倍退化时必红。
104
+
105
+ ### P0-5 300px 与暗色|S|打磨
106
+
107
+ - 300px 是硬约束,目前只有截图没有自动化:加样式契约断言(关键行 `nowrap + ellipsis`、区块顺序、不出现横向滚动)。
108
+ - 暗色模式:宿主有主题服务时跟随(`prefers-color-scheme` 兜底),颜色集中成一组 token。
109
+
110
+ ---
111
+
112
+ ## P1 · 0.3.x 从"看见"到"改变"
113
+
114
+ > 目标:用户第一次因为面板**改了行为**。这是留存的分水岭。
115
+
116
+ ### P1-1 预算入口(不写用户配置)|S
117
+
118
+ 面板内给三档预设(¥0.5 / ¥2 / ¥5),点一下 → **生成可复制的配置片段** + 一句"粘到 profile 的 cordis.patch.yml"。
119
+ 不直接改用户配置文件:插件没有写 profile 的合法通道,硬写属于越权。
120
+
121
+ **验收**:复制内容能被 `resolveConfig` 正确解析(用真实 YAML 解析断言);`budget.limit=0` 不当作启用。
122
+
123
+ ### P1-2 超预算提醒(两条通道都做)|M
124
+
125
+ - **面板**:合计条转琥珀 + 一句"已超预算 X%,还可约 Y 次"。
126
+ - **Agent 侧**:走通道 A(`agent.inject` 一条预算事实),前提是宿主提供 `messageFactory`;拿不到就只做面板 + `ledger_query` 主动查询提示。
127
+
128
+ **验收**:`test/budget-alert.test.mjs`;回滞语义(跨阈值只提醒一次,低于 0.9×阈值才重新武装)保持不变。
129
+
130
+ ### P1-3 省钱建议(这是产品真正值钱的地方)|M
131
+
132
+ 三条可以从现有数据算出来的建议,每条都带**可执行动作**与**预计节省**:
133
+
134
+ | 建议 | 触发条件 | 话术 |
135
+ |---|---|---|
136
+ | 缓存前缀失效 | 某步 `cacheRead` 骤降到 <10% 且上下文 > 5 万 tok | "第 7 步前缀变了,这步多花了 ¥X;把系统提示/开场放在最前能恢复命中" |
137
+ | 工具结果过大 | 单步 `contextChars > 20k` | "这步的工具结果 24k 字符,占这一步成本的 62%;让它只返回摘要" |
138
+ | 模型错配 | 某模型单价 > 全局均价 3 倍且单步 < 2k 输出 | "这一步用了 pro 但只产出 800 tok,换 flash 可省 ¥X" |
139
+
140
+ **验收**:每条建议有"为什么这么判断"的依据行(不能是黑箱);建议必须在**能算出来时**才出现,算不出来就闭嘴(沿用"未知即未知"铁律)。
141
+
142
+ ### P1-4 首次引导(1 分钟上手)|S
143
+
144
+ 装完第一次打开面板 → 三屏卡片(这是什么 / 会记录什么 / 关了面板也在记账),可跳过,只出现一次(记在 storage)。
145
+
146
+ ---
147
+
148
+ ## P2 · 0.4.x 个人版完整
149
+
150
+ ### P2-1 总账视图|M
151
+ 跨会话、按天、按项目(`identity.project` 已有)的聚合页;时间范围切换(今天/7 天/30 天)。
152
+
153
+ ### P2-2 导出|S
154
+ CSV(明细)+ Markdown 周报(复用"复制摘要"的排版)。周报模板固定,不引入模板引擎。
155
+
156
+ ### P2-3 保留与清理|S
157
+ 默认 90 天;面板里能看"占用多少、下次清理时间",提供"立即清空"。
158
+
159
+ ### P2-4 性能与内存门禁|S
160
+ 300k 事件后 <32MB 已在 bench 里;再补"长会话 100 万事件"的门槛,防止历史归档拖慢热路径。
161
+
162
+ ---
163
+
164
+ ## P3 · 0.5.x → 1.0 团队版底座(有闸门)
165
+
166
+ 只做一件事:**本地流水 → 批量上报 → 一页「本周按人/按项目」**。
167
+
168
+ | 子项 | 说明 | 工程量 |
169
+ |---|---|---|
170
+ | 上报通道 | `wire.js` 协议现成(`measures[]` + 幂等键),加旁路队列、批量、断网续传、失败退避 | 4–6 人日 |
171
+ | 聚合服务 | 最小实现:接收 + 按人/项目/天分组 + 一页 HTML | 4–6 人日 |
172
+ | 身份与隐私开关 | deviceId/actor/project 已采集;上报需显式开启 + 文档说明字段清单 | 1 人日 |
173
+ | License(企业版) | 私有化安装包 + 激活码校验 + 等保材料清单 | 见 business-plan M7 |
174
+
175
+ **硬约束**:上报不得进入热路径(旁路定时器),`bench --gate` 不得退化。
176
+
177
+ ## 3. 每版的 Definition of Done
178
+
179
+ 一个版本能发,必须同时满足:
180
+
181
+ 1. **三种状态都有渲染断言**:正常 / 空 / 错误(少一种就是"用户会看到空白")。
182
+ 2. **至少一条跨模块端到端**测试(Host 写 → 客户端读;或产物渲染)。单模块测试全绿不算过。
183
+ 3. **产物测试通过**:`lib/client.js` 由源码重建后与提交一致(CI 已强制)。
184
+ 4. **门禁全绿**:`bash scripts/ci.sh`(bench 用相对基线)。
185
+ 5. **文档同步**:README 的开关表、technical 的取舍、本文的进度勾选。
186
+ 6. **崩溃零容忍**:任何客户端改动都必须过 `client-artifact-render`。
187
+
188
+ ## 4. 衡量"用户喜欢"的指标(先埋点,再谈值)
189
+
190
+ | 指标 | 怎么来 | 目标 |
191
+ |---|---|---|
192
+ | 面板首次打开有数率 | 快照存在且 `entries>0` 的比例 | ≥95% |
193
+ | 崩溃/错误率 | 客户端 `[ledger]` warn 计数(本地) | 0 |
194
+ | 复制摘要使用率 | 按钮点击(本地计数) | ≥15% 会话 |
195
+ | 预算配置率 | 配置了 `budget.limit` 的比例 | ≥20%(P1 后) |
196
+ | 建议采纳率 | 建议出现后 7 天内相关指标改善 | 先观察,不设目标 |
197
+ | 7 日留存 | 安装后第 7 天仍有面板访问 | ≥40% |
198
+
199
+ > 全部**本地统计、不上报**(团队版才谈上报,且需显式开启)。
200
+
201
+ ## 5. 风险与不做的事
202
+
203
+ | 风险 | 应对 |
204
+ |---|---|
205
+ | 厂商自带成本面板 | 我们的差异是**跨工具 + 敢说不知道 + 可对账**,不跟厂商比"余额" |
206
+ | 做成计费系统 | 死守边界:不给"你应该付的钱",只做归因与对账 |
207
+ | 数据采集越界 | 只记体积不记内容;绝对路径不入账;历史默认 90 天 |
208
+ | 宿主契约再变 | 每类契约都留一条"真机语义"回归测试(已三次教训) |
209
+
210
+ **不做**:prompt 内容分析、模型效果评估、余额查询、按 token 自动省钱(替用户做决定)。
211
+
212
+ ## 6. 现在就要拍板的三件事
213
+
214
+ 1. **P0-1 自检** vs **P0-2 持久化**:我建议先 P0-1(1–2 天,立刻降低支持成本),再做 P0-2(3–4 天,是 P2/P3 的地基)。
215
+ 2. **归档格式**:JSONL(简单、可 grep、零依赖)还是 SQLite(查询快、要引依赖)。建议先 JSONL。
216
+ 3. **P3 闸门**:是否坚持"5 个持续用户"再动上报通道——这条决定要不要现在花 10 人日写服务端。
package/docs/technical.md CHANGED
@@ -242,6 +242,19 @@ token 只是 `measures` 里的一种单位。计划中的第二个来源(Trae
242
242
 
243
243
  ---
244
244
 
245
+ ### 7.4 历史归档为什么按天分片、为什么默认开
246
+
247
+ 账本只在内存里,`session/disposed` 时快照被删——**昨天花了多少无从查起**。归档补的正是这一层。
248
+
249
+ - **按天分片** `archive/<YYYY-MM-DD>.jsonl`:单文件有界;`prune()` 直接按文件名删(不读内容);
250
+ 用户能 `grep` 自查;将来换 SQLite 时按天导入是最自然的迁移。
251
+ - **热路径零 IO**:与 trace 同一套路,`enqueue` 只入队,定时器合并成一次 `appendFileSync`;
252
+ 队列有界(满了丢最旧的并计数),异常吞掉。
253
+ - **默认开启**的理由与面板一致:默认关的真实后果是"功能存在但没人能用到"。隐私边界靠字段约束保证——
254
+ 只存体积与金额、不存内容、不存绝对路径,`actor`(git email)默认不写。
255
+ - **两条写入时机**:`session/disposed`(会话结束)与每 60 秒补写一次(进程被杀最多丢一分钟)。
256
+ - **未知成本原样保留 `reason`**:归档里出现 0 就等于把"不知道"说成"没花钱",对账时会变成假精度。
257
+
245
258
  ### 8.0 面板默认开启(0.1.11 起)
246
259
 
247
260
  `panel.enabled` 的默认值从 `false` 改成 `true`。这不是"顺手改个默认值",而是一次真机教训:
@@ -286,6 +299,8 @@ Host 会显式告警"面板读不到",而不是让用户对着空面板猜。
286
299
  | `test/client-lifecycle.test.mjs` | 客户端生命周期 | 登记可逆、重复 apply、无 slots 降级、登记抛错不冒泡 |
287
300
  | `test/snapshot-roundtrip.test.mjs` | 写盘→读回全链路 | 20 条明细(400+ 行)分页读回、truncated 落盘、二级降级不超 maxBytes |
288
301
  | `test/guard-downgrade.test.mjs` | 预算降级矩阵 | provider/model/maxTokens 覆盖、阈值、未知成本不判、next 抛错冒泡 |
302
+ | `test/archive.test.mjs` | 历史归档 | 按天分片、队列有界、保留裁剪、隐私字段、插件级 e2e |
303
+ | `test/reconcile.test.mjs` | 对账 PoC | CSV/日期解析、未计价单列、差异率符号 |
289
304
  | `test/client-artifact-render.test.mjs` | 产物渲染 | 用 `lib/client.js` + 真 React 渲染有数据态与组件首帧(抓出过重名常量导致的 SyntaxError) |
290
305
 
291
306
  **SKIP 不等于通过**:冒烟脚本找不到 DSH 运行时用退出码 2 表示 SKIP,`prepublish.sh` 第 6 步把 SKIP 判 FAIL。
package/lib/archive.js ADDED
@@ -0,0 +1,189 @@
1
+ /**
2
+ * 历史账本归档(JSONL)。
3
+ *
4
+ * 为什么需要它:
5
+ * 账本只在内存里,`session/disposed` 时快照被删——**昨天花了多少无从查起**。
6
+ * 没有历史就没有"本周/本月"、没有周报、没有团队聚合,也就没有商业化的地基。
7
+ *
8
+ * 为什么按天分片:
9
+ * - 单文件不会无限长,`prune()` 直接按文件名删,不需要读内容;
10
+ * - 用户能 `grep 2026-11-21` 自查,零工具;
11
+ * - 以后换 SQLite 时,按天导入是最自然的迁移路径。
12
+ *
13
+ * 为什么落盘不在热路径:
14
+ * 与 trace 同一套路:`append()` 只把已序列化的行推进队列,由定时器合并成一次
15
+ * `appendFileSync`。任何异常都吞掉并计数——采集失败绝不能影响宿主。
16
+ *
17
+ * 隐私边界(比 trace 更严):
18
+ * - 只记**体积与金额**,不记任何对话内容;
19
+ * - 不记绝对路径;
20
+ * - `actor`(git email)默认**不落盘**,只有 `includeActor: true` 才带。
21
+ */
22
+ import { appendFileSync, mkdirSync, readdirSync, rmSync } from 'node:fs'
23
+ import { homedir } from 'node:os'
24
+ import { join } from 'node:path'
25
+
26
+ /** 默认目录:与 device-id、pricing.json 同级 */
27
+ export function defaultArchiveDir() {
28
+ return join(homedir(), '.dsh', 'ledger', 'archive')
29
+ }
30
+
31
+ /** 一天的分片文件名:2026-11-21.jsonl */
32
+ export function shardNameOf(at) {
33
+ const d = new Date(at)
34
+ const y = d.getFullYear()
35
+ const m = String(d.getMonth() + 1).padStart(2, '0')
36
+ const day = String(d.getDate()).padStart(2, '0')
37
+ return `${y}-${m}-${day}.jsonl`
38
+ }
39
+
40
+ /**
41
+ * 一条账本条目 → 一行归档记录。字段名刻意缩短:归档是要长期存的。
42
+ * @param {object} entry - store 里的账本条目
43
+ * @param {{ sessionId?: string, title?: string|null, project?: string|null, device?: string|null, actor?: string|null }} ctx
44
+ */
45
+ export function archiveRecordOf(entry, ctx = {}) {
46
+ const usage = entry?.usage ?? null
47
+ const cost = entry?.cost ?? null
48
+ const record = {
49
+ v: 1,
50
+ at: entry?.at ?? null,
51
+ sid: ctx.sessionId ?? entry?.sessionId ?? null,
52
+ turn: entry?.turn ?? null,
53
+ step: entry?.step ?? null,
54
+ kind: entry?.kind ?? null,
55
+ }
56
+ if (typeof ctx.title === 'string' && ctx.title.length > 0) record.title = ctx.title
57
+ if (entry?.route?.provider || entry?.route?.model) {
58
+ record.provider = entry.route.provider ?? null
59
+ record.model = entry.route.model ?? null
60
+ }
61
+ if (usage !== null) {
62
+ // 四档全部保留:少一档就没法用归档重算金额(对账的前提)
63
+ record.tok = {
64
+ i: usage.inputTokens ?? null,
65
+ o: usage.outputTokens ?? null,
66
+ cr: usage.cacheReadTokens ?? 0,
67
+ cw: usage.cacheWriteTokens ?? 0,
68
+ }
69
+ if (usage.complete !== true) record.tokIncomplete = true
70
+ }
71
+ if (cost?.kind === 'known') {
72
+ record.cost = cost.amount
73
+ record.cur = cost.currency ?? null
74
+ record.parts = cost.parts ?? null
75
+ } else {
76
+ // 未知必须原样保留原因:归档里出现 0 就等于把"不知道"说成"没花钱"
77
+ record.cost = null
78
+ record.reason = cost?.reason ?? 'no-cost'
79
+ }
80
+ const attribution = entry?.attribution
81
+ if (typeof attribution?.primary?.plugin === 'string') record.plugin = attribution.primary.plugin
82
+ if (typeof attribution?.system === 'string') record.system = attribution.system
83
+ if (typeof ctx.project === 'string') record.project = ctx.project
84
+ if (typeof ctx.device === 'string') record.device = ctx.device
85
+ if (typeof ctx.actor === 'string') record.actor = ctx.actor
86
+ return record
87
+ }
88
+
89
+ /**
90
+ * @param {object} [options]
91
+ * @param {string} [options.dir] - 归档目录(默认 ~/.dsh/ledger/archive)
92
+ * @param {number} [options.flushMs] - 合并写盘间隔
93
+ * @param {number} [options.maxQueued] - 队列上限(满了丢最旧的并计数,绝不拖慢热路径)
94
+ * @param {number} [options.retentionDays] - 保留天数(默认 90,0 表示不裁剪)
95
+ * @param {() => number} [options.now]
96
+ */
97
+ export function createArchive(options = {}) {
98
+ const dir = options.dir ?? defaultArchiveDir()
99
+ const flushMs = Math.max(200, Number(options.flushMs ?? 5000))
100
+ const maxQueued = Math.max(100, Number(options.maxQueued ?? 20000))
101
+ const retentionDays = Math.max(0, Number(options.retentionDays ?? 90))
102
+ const now = options.now ?? Date.now
103
+
104
+ /** @type {{at:number, line:string}[]} */
105
+ let queue = []
106
+ const stats = { written: 0, dropped: 0, errors: 0, pruned: 0, flushes: 0 }
107
+ let timer = null
108
+
109
+ function enqueue(record) {
110
+ const at = typeof record?.at === 'number' ? record.at : now()
111
+ queue.push({ at, line: JSON.stringify(record) })
112
+ // 队列满了丢最旧的:宁可少历史,也不让内存无界增长
113
+ while (queue.length > maxQueued) {
114
+ queue.shift()
115
+ stats.dropped += 1
116
+ }
117
+ if (timer === null) {
118
+ timer = setInterval(() => flush(), flushMs)
119
+ // Node 环境下不阻止进程退出;浏览器/测试环境没有 unref
120
+ if (typeof timer.unref === 'function') timer.unref()
121
+ }
122
+ }
123
+
124
+ /** 把队列按天分片写出;返回写出的行数。 */
125
+ function flush() {
126
+ if (queue.length === 0) return 0
127
+ const byShard = new Map()
128
+ for (const item of queue) {
129
+ const name = shardNameOf(item.at)
130
+ const bucket = byShard.get(name)
131
+ if (bucket === undefined) byShard.set(name, [item.line])
132
+ else bucket.push(item.line)
133
+ }
134
+ queue = []
135
+ let written = 0
136
+ for (const [name, lines] of byShard) {
137
+ try {
138
+ mkdirSync(dir, { recursive: true })
139
+ appendFileSync(join(dir, name), `${lines.join('\n')}\n`, 'utf8')
140
+ written += lines.length
141
+ } catch {
142
+ stats.errors += 1
143
+ }
144
+ }
145
+ stats.written += written
146
+ stats.flushes += 1
147
+ return written
148
+ }
149
+
150
+ /**
151
+ * 按保留天数裁剪。只删文件名像日期的分片,绝不碰目录里别的东西。
152
+ * @returns {number} 删除的文件数
153
+ */
154
+ function prune() {
155
+ if (retentionDays <= 0) return 0
156
+ const cutoff = now() - retentionDays * 86_400_000
157
+ let removed = 0
158
+ let names = []
159
+ try {
160
+ names = readdirSync(dir)
161
+ } catch {
162
+ return 0 // 目录还不存在
163
+ }
164
+ for (const name of names) {
165
+ const match = /^(\d{4})-(\d{2})-(\d{2})\.jsonl$/.exec(name)
166
+ if (match === null) continue
167
+ const at = new Date(Number(match[1]), Number(match[2]) - 1, Number(match[3]), 12).getTime()
168
+ if (!Number.isFinite(at) || at >= cutoff) continue
169
+ try {
170
+ rmSync(join(dir, name), { force: true })
171
+ removed += 1
172
+ } catch {
173
+ stats.errors += 1
174
+ }
175
+ }
176
+ stats.pruned += removed
177
+ return removed
178
+ }
179
+
180
+ function dispose() {
181
+ if (timer !== null) {
182
+ clearInterval(timer)
183
+ timer = null
184
+ }
185
+ flush()
186
+ }
187
+
188
+ return { dir, enqueue, flush, prune, dispose, stats, get pending() { return queue.length } }
189
+ }
package/lib/config.js CHANGED
@@ -37,6 +37,15 @@ export const DEFAULT_CONFIG = Object.freeze({
37
37
  maxBytes: 4194304, // 单文件 4MB 封顶
38
38
  },
39
39
  },
40
+ // 历史归档:会话结束(或每分钟)把账本追加到 ~/.dsh/ledger/archive/<日期>.jsonl。
41
+ // 只存体积与金额,不存任何对话内容;默认保留 90 天。没有它就没有"昨天花了多少"。
42
+ archive: {
43
+ enabled: true,
44
+ dir: null, // null = ~/.dsh/ledger/archive
45
+ retentionDays: 90,
46
+ flushMs: 5000,
47
+ includeActor: false, // true 才会把 git email 写进归档(团队对账用,默认不写)
48
+ },
40
49
  attribution: {
41
50
  toolOwners: {}, // 工具名 → 所属插件(唯一可得的归因依据,见 docs/spikes.md)
42
51
  },
package/lib/index.js CHANGED
@@ -24,6 +24,7 @@ import { createBudgetGuard } from './guard.js'
24
24
  import { createLedgerQueryTool } from './audit-tool.js'
25
25
  import { makeBudgetMessage } from './budget-message.js'
26
26
  import { createSnapshotPublisher } from './snapshot-file.js'
27
+ import { createArchive, archiveRecordOf } from './archive.js'
27
28
  import { PANEL_DIR } from './panel-path.js'
28
29
  import { createTraceSink } from './trace-file.js'
29
30
 
@@ -158,6 +159,71 @@ export function apply(ctx, rawConfig) {
158
159
  // 读的是 .git/config 与 ~/.gitconfig 两个小文件,**不起 git 子进程**。
159
160
  const identity = createIdentity()
160
161
 
162
+ // 历史归档:会话结束(以及每分钟)把账本并入 ~/.dsh/ledger/archive/<日期>.jsonl。
163
+ // 热路径零 IO:enqueue 只入队,定时器合并写。
164
+ const archive =
165
+ config.archive?.enabled === false
166
+ ? null
167
+ : createArchive({
168
+ dir: config.archive?.dir ?? undefined,
169
+ retentionDays: config.archive?.retentionDays,
170
+ flushMs: config.archive?.flushMs,
171
+ })
172
+ /** sessionId → 已归档条数(增量游标,避免重复写) */
173
+ const archivedCount = new Map()
174
+ /** sessionId → { project, device, actor },每会话解析一次 */
175
+ const archiveIdentity = new Map()
176
+
177
+ function archiveContextOf(sessionId) {
178
+ let ctx = archiveIdentity.get(sessionId)
179
+ if (ctx === undefined) {
180
+ const cwd = sessionRoots.get(sessionId)
181
+ const resolved = typeof identity?.resolve === 'function' ? identity.resolve(cwd ?? null) : null
182
+ ctx = {
183
+ project: resolved?.project?.key ?? null,
184
+ device: resolved?.deviceId ?? null,
185
+ // actor 是 git email:默认不落盘,只有显式配置才带
186
+ actor: config.archive?.includeActor === true ? (resolved?.actor?.email ?? null) : null,
187
+ }
188
+ archiveIdentity.set(sessionId, ctx)
189
+ }
190
+ return ctx
191
+ }
192
+
193
+ /** 把某会话自上次以来新增的条目写进归档。失败只计数,绝不抛出。 */
194
+ function archiveSession(sessionId) {
195
+ if (archive === null || typeof sessionId !== 'string') return 0
196
+ const entries = store.entriesOf(sessionId)
197
+ if (entries === null || entries.length === 0) return 0
198
+ const from = archivedCount.get(sessionId) ?? 0
199
+ if (entries.length <= from) return 0
200
+ const ctx = { sessionId, title: titles.get(sessionId) ?? null, ...archiveContextOf(sessionId) }
201
+ let written = 0
202
+ try {
203
+ for (const entry of entries.slice(from)) {
204
+ archive.enqueue(archiveRecordOf(entry, ctx))
205
+ written += 1
206
+ }
207
+ archivedCount.set(sessionId, entries.length)
208
+ } catch {
209
+ // 归档失败不影响采集:下一轮再试
210
+ }
211
+ return written
212
+ }
213
+
214
+ // 每分钟补写一次:不等到 disposed,进程被杀最多丢一分钟
215
+ let archiveTimer = null
216
+ if (archive !== null) {
217
+ try {
218
+ archive.prune()
219
+ } catch {}
220
+ archiveTimer = setInterval(() => {
221
+ for (const id of store.sessionIds()) archiveSession(id)
222
+ archive.flush()
223
+ }, 60_000)
224
+ if (typeof archiveTimer.unref === 'function') archiveTimer.unref()
225
+ }
226
+
161
227
  const ledger = createLedger({
162
228
  store,
163
229
  pricing,
@@ -173,7 +239,14 @@ export function apply(ctx, rawConfig) {
173
239
  if (typeof sid === 'string' && !sessionRoots.has(sid) && typeof session?.header?.cwd === 'string') {
174
240
  sessionRoots.set(sid, session.header.cwd)
175
241
  }
176
- if (event?.type === 'session/title' && typeof sid === 'string') {
242
+ if (typeof sid === 'string' && !titles.has(sid)) {
243
+ // 两条来源都试:标题事件(新会话)、会话对象上的现成标题(老会话,插件启动前就有标题的)
244
+ const fromEvent = event?.type === 'session/title' ? (event?.data ?? event)?.title : null
245
+ const fromSession = session?.title ?? session?.header?.title
246
+ const title = typeof fromEvent === 'string' && fromEvent.length > 0 ? fromEvent : fromSession
247
+ if (typeof title === 'string' && title.length > 0) titles.set(sid, title)
248
+ } else if (event?.type === 'session/title' && typeof sid === 'string') {
249
+ // 标题会被重新生成(例如更好的一条),已存在时也要更新
177
250
  const payload = event?.data ?? event
178
251
  if (typeof payload?.title === 'string' && payload.title.length > 0) titles.set(sid, payload.title)
179
252
  }
@@ -196,6 +269,10 @@ export function apply(ctx, rawConfig) {
196
269
  // 会话消失即释放内存:账本不跨会话累积,避免长期运行的内存增长
197
270
  publisher?.remove(id)
198
271
  // 按会话索引的状态必须一起释放,否则长跑进程里这几张 Map 只增不减
272
+ // 先把剩余条目并进归档,再释放内存——否则最后一个会话的尾巴会丢
273
+ archiveSession(id)
274
+ archivedCount.delete(id)
275
+ archiveIdentity.delete(id)
199
276
  guard.forget(id)
200
277
  ledger.forget(id)
201
278
  traceSink?.remove(id)
@@ -219,6 +296,8 @@ export function apply(ctx, rawConfig) {
219
296
  stats: () => ({ ...ledger.stats(), sessions: store.sessionCount }),
220
297
  // 面板诊断:面板读不到数据时,先看这里是 enabled 还是 dir 不对
221
298
  panel: publisher === null ? { enabled: false } : { enabled: true, dir: publisher.dir, stats: publisher.stats },
299
+ // 归档状态:写了几条、丢了几条、错了几次(面板/自查用)
300
+ archive: archive === null ? { enabled: false } : { enabled: true, dir: archive.dir, stats: archive.stats },
222
301
  // 费率来源与拒收明细:对外可查,避免"我改了价但数字没变"变成悬案
223
302
  pricing: pricingMeta,
224
303
  config,
@@ -237,10 +316,12 @@ export function apply(ctx, rawConfig) {
237
316
  // 幂等:宿主可能既跑 effect 清理又触发 dispose 事件,重复释放会二次 flush/close
238
317
  if (disposed) return
239
318
  disposed = true
319
+ if (archiveTimer !== null) clearInterval(archiveTimer)
320
+ archive?.dispose()
240
321
  publisher?.dispose()
241
322
  traceSink?.dispose()
242
323
  }
243
- if (publisher !== null || traceSink !== null) {
324
+ if (publisher !== null || traceSink !== null || archive !== null) {
244
325
  if (typeof ctx.effect === 'function') ctx.effect(() => cleanup)
245
326
  else ctx.on('dispose', cleanup)
246
327
  }
package/lib/store.js CHANGED
@@ -320,6 +320,25 @@ export class LedgerStore {
320
320
  return this.#sessions.get(sessionId)?.entries.toArray() ?? []
321
321
  }
322
322
 
323
+ /**
324
+ * 该会话当前保留的全部账本条目(环形缓冲里的副本)。
325
+ *
326
+ * 给归档用:只读,不 touch LRU——面板轮询与定时归档都不该让会话"续命",
327
+ * 否则 maxSessions 的淘汰策略会被读操作废掉。
328
+ * @param {string} sessionId
329
+ * @returns {object[]|null}
330
+ */
331
+ entriesOf(sessionId) {
332
+ const bucket = this.#sessions.get(sessionId)
333
+ if (bucket === undefined) return null
334
+ return bucket.entries.last(bucket.entries.size) ?? []
335
+ }
336
+
337
+ /** 当前有状态的会话 id(归档定时器遍历用,不 touch LRU)。 */
338
+ sessionIds() {
339
+ return [...this.#sessions.keys()]
340
+ }
341
+
323
342
  drop(sessionId) {
324
343
  this.#sessions.delete(sessionId)
325
344
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@lingda-ai/dsh-plugin-ledger",
3
- "version": "0.1.11",
3
+ "version": "0.1.13",
4
4
  "description": "DSH 插件搜索入口:运行时账本(成本/用量观测)。自包含单包,不依赖其他 npm 包,便于从镜像源安装。",
5
5
  "license": "Apache-2.0",
6
6
  "keywords": [