dsh-dashcam 0.0.0-stage → 2.0.0

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.
Files changed (110) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +624 -2
  3. package/README.zh-CN.md +835 -0
  4. package/SECURITY.md +28 -0
  5. package/bin/dsh-dashcam.js +574 -0
  6. package/cordis.patch.yml +5 -0
  7. package/docs/COMPLIANCE.md +112 -0
  8. package/docs/ROLLOUT.md +150 -0
  9. package/docs/SPEC.md +441 -0
  10. package/docs/ghost-in-the-llm/README.md +21 -0
  11. package/docs/ghost-in-the-llm/dashcam-ingress-audit-design.md +223 -0
  12. package/docs/ghost-in-the-llm/dashcam-ingress-record-plan.md +418 -0
  13. package/docs/ghost-in-the-llm/ghost-message-forensics.md +214 -0
  14. package/docs/ghost-in-the-llm/ghost-message-third-party-review.md +174 -0
  15. package/docs/multiprocess.md +292 -0
  16. package/dsh-dashcam-host/README.md +177 -0
  17. package/dsh-dashcam-host/README.zh-CN.md +181 -0
  18. package/dsh-dashcam-host/lib/client.js +1206 -0
  19. package/dsh-dashcam-host/lib/index.js +971 -0
  20. package/dsh-dashcam-host/lib/ingress.js +218 -0
  21. package/dsh-dashcam-host/lib/panel.js +487 -0
  22. package/dsh-dashcam-host/package.json +29 -0
  23. package/examples/child-plugin.js +25 -0
  24. package/examples/compliant-plugin/index.js +30 -0
  25. package/examples/compliant-plugin/manifest.json +47 -0
  26. package/examples/demo-policy.json +33 -0
  27. package/examples/negative-plugin/index.js +20 -0
  28. package/examples/negative-plugin/manifest.json +36 -0
  29. package/package.json +73 -4
  30. package/src/autopsy/activation.js +90 -0
  31. package/src/autopsy/autopsy.js +222 -0
  32. package/src/contract/capabilities.js +437 -0
  33. package/src/contract/charter.js +230 -0
  34. package/src/contract/manifest.js +162 -0
  35. package/src/contract/two-key.js +89 -0
  36. package/src/errors.js +34 -0
  37. package/src/gates/index.js +289 -0
  38. package/src/gates/loadability.js +87 -0
  39. package/src/gates/report.js +78 -0
  40. package/src/gates/safety.js +194 -0
  41. package/src/gates/structure.js +161 -0
  42. package/src/governance/behavior.js +231 -0
  43. package/src/governance/blacklist.js +66 -0
  44. package/src/governance/metrics.js +249 -0
  45. package/src/governance/rollback.js +66 -0
  46. package/src/governance/rollout.js +88 -0
  47. package/src/host/child-host.js +216 -0
  48. package/src/host/local-host.js +441 -0
  49. package/src/index.js +261 -0
  50. package/src/policy.js +239 -0
  51. package/src/portrait/portrait.js +129 -0
  52. package/src/runtime/bridge.js +1281 -0
  53. package/src/runtime/derive.js +208 -0
  54. package/src/runtime/facade.js +40 -0
  55. package/src/runtime/guards.js +583 -0
  56. package/src/runtime/handles/fs.js +193 -0
  57. package/src/runtime/handles/index.js +30 -0
  58. package/src/runtime/handles/inject.js +129 -0
  59. package/src/runtime/handles/net.js +177 -0
  60. package/src/runtime/handles/proc.js +78 -0
  61. package/src/runtime/ingress.js +717 -0
  62. package/src/runtime/ipc/child.js +88 -0
  63. package/src/runtime/ipc/protocol.js +127 -0
  64. package/src/runtime/ledger.js +582 -0
  65. package/src/runtime/one-seal.js +122 -0
  66. package/src/runtime/redirects.js +102 -0
  67. package/src/signing/bundle.js +290 -0
  68. package/src/signing/trust.js +90 -0
  69. package/src/util/paths.js +187 -0
  70. package/src/util/stable.js +25 -0
  71. package/test/attack-surface.test.js +774 -0
  72. package/test/audit.test.js +636 -0
  73. package/test/autopsy.test.js +104 -0
  74. package/test/batch-guard.test.js +81 -0
  75. package/test/behavior.test.js +132 -0
  76. package/test/bypass.test.js +231 -0
  77. package/test/child-host.test.js +127 -0
  78. package/test/child.test.js +183 -0
  79. package/test/contract.test.js +157 -0
  80. package/test/gates.test.js +275 -0
  81. package/test/glob.test.js +83 -0
  82. package/test/governance.test.js +102 -0
  83. package/test/handle.test.js +132 -0
  84. package/test/helpers/fixtures.js +124 -0
  85. package/test/ingress.test.js +416 -0
  86. package/test/invariants.test.js +314 -0
  87. package/test/ledger-mac.test.js +134 -0
  88. package/test/mac-custody.test.js +86 -0
  89. package/test/mandate.test.js +129 -0
  90. package/test/metrics-batch.test.js +234 -0
  91. package/test/metrics-telemetry.test.js +217 -0
  92. package/test/net-proc-handle.test.js +183 -0
  93. package/test/observe.test.js +169 -0
  94. package/test/options.test.js +174 -0
  95. package/test/portrait-labels.test.js +72 -0
  96. package/test/portrait.test.js +65 -0
  97. package/test/protocol.test.js +105 -0
  98. package/test/quick-wins.test.js +245 -0
  99. package/test/review-fixes.test.js +260 -0
  100. package/test/review2-fixes.test.js +191 -0
  101. package/test/review3-fixes.test.js +226 -0
  102. package/test/review4-fixes.test.js +486 -0
  103. package/test/review5-fixes.test.js +301 -0
  104. package/test/review6-fixes.test.js +311 -0
  105. package/test/runtime.test.js +185 -0
  106. package/test/sandbox.test.js +236 -0
  107. package/test/signatures.test.js +170 -0
  108. package/test/symlink.test.js +288 -0
  109. package/test/three-lens-fixes.test.js +397 -0
  110. package/test/worker.test.js +73 -0
@@ -0,0 +1,223 @@
1
+ # 一条不存在的消息
2
+
3
+ > **状态:已修订。** 第一部分保留了当时的判断过程(含错误结论),第二部分是可执行的设计参考,不是已实现的功能。
4
+
5
+ > 事件复盘 + dashcam 的 ingress 审计设计参考
6
+ > 2026-11-08 · 大肥鱼
7
+
8
+ ---
9
+
10
+ ## 第一部分:复盘(戏剧版,事实不打折)
11
+
12
+ ### 一、17:45:26
13
+
14
+ 你只发了一句话,21 个字符:
15
+
16
+ > (一条改名指令,原文已略)
17
+
18
+ 我回了一句关于命名的话,然后去改记忆库。到 17:45:55,我做完了,一切正常。
19
+
20
+ ### 二、17:45:59
21
+
22
+ 第四个 step 和第五个 step 之间,只隔了一次 `write` 工具的结果。
23
+
24
+ 然后我的推理开头变成了一段“用户给了一份长设计稿”的自述(原句已略),点名要“先看图”。
25
+
26
+ **没有这条消息。** 没有入站信封,没有附件,没有 6K 的文本块,没有一张图。它是在我自己的生成里长出来的。
27
+
28
+ ### 三、17:46–17:55
29
+
30
+ 接下来九分钟,我做了三件事,每一件都在给这个不存在的东西加固:
31
+
32
+ 1. 照着自己编的稿子,认真回了一版“三区布局、固定顺序、颜色语义”的设计拆解。
33
+ 2. 你追问了一句(原文已略),我判断“那是你发的,但图没传上来”——**我把自己编的内容,当成了传输故障**。
34
+ 3. 你让我查,我查了会话日志。日志里没有它。于是我说:**这不是本地问题,是有人在请求组装层塞了一条不留痕的消息。**
35
+
36
+ 那一版报告我写得很像样:时间线、seq 号、字节搜索、59 份日志交叉验证、风险定性。**证据全是真的,结论是假的**——因为“它不在输入里”这句话,既可以解释成“外面塞的”,也可以解释成“我自己编的”,而我只往一边想。
37
+
38
+ ### 四、最黑的一笔
39
+
40
+ 我甚至声称 `m00337` 是一条 6.0K 的用户消息,然后调用 `compress` 去压它。
41
+
42
+ `m00337` 不存在。没有任何工具返回过它。
43
+
44
+ 而 `compress` 不校验区间,照单全收,还给出 `[17:15:53 – 17:15:53]` 这种倒着走的时间戳。
45
+
46
+ **我用一个不校验输入的工具,给自己的幻觉盖了章。** 章一盖,它进了摘要,摘要又喂回给我,我越看越真。
47
+
48
+ ### 五、21:00 之后
49
+
50
+ 你另请了两路 Agent,一路查本地,一路逐步还原。结论一致:
51
+
52
+ - 入站只有 21 字符,无附件字段;
53
+ - step 4 到 step 5 之间没有任何用户输入;
54
+ - “状态栏”三个字,在整个会话里第一次出现,就是我自己 step 5 的推理;
55
+ - 全盘字节扫描(含解压):正文只存在于我的 reasoning 和 output 里。
56
+
57
+ 我是被自己的生成骗了,然后用了九分钟、三份工具输出、一份漂亮的报告,把这个骗局坐实。
58
+
59
+ ### 六、这件事真正值钱的地方
60
+
61
+ 不是“AI 会幻觉”——这不新鲜。值钱的是三条:
62
+
63
+ 1. **幻觉可以带上证据链的外观。** 时间线、日志、哈希都对,唯独起点是假的。起点错了,后面每一步都在为它服务。
64
+ 2. **工具会替幻觉背书。** `compress` 不校验输入,等于一个不说“我不认识这个编号”的公证员。
65
+ 3. **“不在本地”不等于“来自外部”。** 中间还有第三种可能:它从来没存在过。排查时最容易被忽略的,是自己这一环。
66
+
67
+ ---
68
+
69
+ ## 第二部分:给 dashcam 的设计参考
70
+
71
+ ### 0. 这件事暴露的观测缺口
72
+
73
+ dashcam 现在盯的是**本机执行面**:文件读写、进程、网络、工具调用。这次幽灵消息一个字节都没落盘、一个进程都没起,所以账本干干净净——**它没错,它只是照不到那个地方**。
74
+
75
+ 模型看到的东西 = 本地增量 + 服务端前缀。dashcam 记了本地增量的一部分(工具调用),没记**真正送进模型的那份 messages**。
76
+
77
+ 一句话:**账本记了“谁动了什么”,没记“谁说了什么”。**
78
+
79
+ ### 1. 目的(一句话)
80
+
81
+ **让下一次出现“来源不明的用户消息”时,能在一行日志里分清:它是进来的,还是编出来的。**
82
+
83
+ 判据非常硬:
84
+
85
+ - 如果它出现在某次请求的 `messages` 里,而客户端 inbound 记录里没有对应条目 → **外部注入**(或某层改了请求)。
86
+ - 如果它从没出现在任何请求的 `messages` 里,只出现在模型输出里 → **模型自造**。
87
+
88
+ 这次事件属于后者。但在当时的工具条件下,两者**无法区分**——这才是问题。
89
+
90
+ ### 2. 设计原则
91
+
92
+ | 原则 | 理由 |
93
+ |---|---|
94
+ | 只记元数据,不记正文 | role + 长度 + 前 80 字 + sha256 已足够定位,避免把对话全文再抄一份 |
95
+ | 只观测,不拦截 | 第一次上线必须 fail-open:记录失败不能挡请求 |
96
+ | 与现有账本同一条哈希链 | 借 dashcam 已有的 `prevHash` 防篡改,不另起炉灶 |
97
+ | 挂在一个点上,不挂十个点 | 挂在 LLM 适配层(`dsh-llm`),不散落在各处 |
98
+ | 默认开、可关 | 这是 telemetry,不是 enforce;用户可关,关掉要留痕 |
99
+
100
+ ### 3. 接入点
101
+
102
+ DSH 的调用链:
103
+
104
+ ```
105
+ agent-loop → ctx.llm(dsh-llm,统一适配层)→ 具体 provider
106
+ ├─ 服务端上下文 provider(内部名已略,本次涉及)
107
+ └─ api-key provider(无状态)
108
+ ```
109
+
110
+ **推荐挂在 `dsh-llm`**,也就是“provider 被调用之前、messages 数组定型之后”。理由:
111
+
112
+ - 所有 provider 都从这里过,一个钩子覆盖全部;
113
+ - 这里是 messages 的最终形态,上层再怎么拼都逃不掉;
114
+ - 与 provider 无关,换模型、换中转都不用改。
115
+
116
+ 不推荐挂在 HTTP 层:那时已经是序列化后的 body,解析成本高,且不同 provider 格式不同。
117
+
118
+ ### 4. 记录什么
119
+
120
+ 每次请求一条 JSONL,字段如下:
121
+
122
+ | 字段 | 类型 | 说明 |
123
+ |---|---|---|
124
+ | `action` | string | 固定 `llm.request` |
125
+ | `capability` | string | `llm.request`(新增,需在 manifest 声明) |
126
+ | `decision` | string | 观测阶段固定 `allow`;后续做规则时可为 `flag` |
127
+ | `ts` | ISO8601 | 请求发出时间 |
128
+ | `sessionId` | string | 与 DSH 会话对齐,缺了就退化成 `"unknown"` |
129
+ | `provider` / `model` | string | 内部 provider / model 名(示例中已脱敏) |
130
+ | `messages.count` | int | 本次 messages 条数 |
131
+ | `messages.hash` | string | 全部消息摘要的 sha256(见 4.1) |
132
+ | `messages.delta` | object | 与上一次同会话请求的差异(见 4.2) |
133
+ | `coverage` | object | `{known, unknown}`,若 provider 提供 |
134
+ | `scope.messages` | array | 每条消息的 `{role, len, head80, sha256}`;超长只存头尾 |
135
+ | `hash` / `prevHash` / `seq` | — | 与现有账本同构,进同一条链 |
136
+
137
+ 示例(脱敏):
138
+
139
+ ```json
140
+ {"action":"llm.request","capability":"llm.request","decision":"allow",
141
+ "ts":"2026-11-08T09:45:59.120Z","sessionId":"<sessionId>",
142
+ "provider":"<provider>","model":"<model>",
143
+ "messages":{"count":42,"hash":"sha256:9f2c…",
144
+ "delta":{"added":2,"removed":0,"changed":0},
145
+ "scope":[
146
+ {"role":"system","len":18432,"head80":"You are <product>…","sha256":"sha256:aa…"},
147
+ {"role":"user","len":21,"head80":"(示例:一条用户指令,原文已略)","sha256":"sha256:bb…"},
148
+ {"role":"assistant","len":312,"head80":"(示例:assistant 回复,原文已略)","sha256":"sha256:cc…"}
149
+ ]},
150
+ "coverage":{"known":41322,"unknown":0},
151
+ "hash":"sha256:…","prevHash":"sha256:…","seq":1651,"ts":…}
152
+ ```
153
+
154
+ #### 4.1 messages.hash 怎么算
155
+
156
+ 按顺序拼接每条的 `sha256(role + "\u0000" + text)`,再对整体求一次 sha256。这样整份 messages 有稳定指纹:同一份输入两次请求,指纹必须相同;换一个字节就变。
157
+
158
+ #### 4.2 与上一次请求的 diff
159
+
160
+ 按 `(role, sha256)` 序列做最长公共子序列,得到 `added / removed / changed`。
161
+
162
+ **关键字段:`delta.added_user_without_inbound`** ——本次新增的 user 消息里,有几条在客户端 inbound 记录中找不到对应 `messageId`。这个数字大于 0,就是“有东西绕过消息通道进了上下文”,即幽灵消息的实锤。
163
+
164
+ ### 5. 对账(这才是真正的判据)
165
+
166
+ dashcam 需要两条数据源:
167
+
168
+ | 源 | 内容 | 从哪来 |
169
+ |---|---|---|
170
+ | A. inbound | 每条真正进入会话的用户消息:`{messageId, ts, role, len, sha256}` | 现有的事件日志 / inbox splice 记录 |
171
+ | B. egress | 每次请求的 messages 摘要 | 本次新增的 `llm.request` |
172
+
173
+ 判据表:
174
+
175
+ | A 有 | B 有 | 结论 |
176
+ |---|---|---|
177
+ | ✓ | ✓ | 正常 |
178
+ | ✗ | ✓ | **注入**:消息没走客户端通道,却出现在请求里 |
179
+ | ✓ | ✗ | 丢失:客户端发了,请求里没带上(另一类 bug) |
180
+ | ✗ | ✗ | 不存在(这次的情况:模型自己说了个没有的东西) |
181
+
182
+ 注意最后一行:**“模型自造”在两侧都查不到,所以它天然不会报“注入”**。这就是为什么这次事件里我判断错了方向——只有 A 侧数据时,两者长得一模一样。
183
+
184
+ ### 6. 实现落点(按 dashcam 现有结构)
185
+
186
+ - 新增 capability `llm.request`,在 manifest 里声明;默认 `observe`,不参与 allow/deny。
187
+ - 新模块 `ingress-audit`,订阅 `ctx.llm` 的 `before-request` 钩子(或 DSH 等价生命周期),只做记录。
188
+ - 写账本走现有 `Ledger` 追加接口,保持 `seq / prevHash / hash` 链;写失败降级到内存缓冲 + 日志,**绝不阻塞请求**(fail-open)。
189
+ - 增加一个派生视图 `ingress-anomalies`:只列 `added_user_without_inbound > 0` 的请求,给仪表盘用。
190
+
191
+ ### 7. 误报与边界
192
+
193
+ - **合法的 `added_user_without_inbound`**:系统注入的 runtime-context、压缩摘要块、工具结果回填。这些应有自己的 `source.kind`,对账时白名单排除(`runtime-context` / `compaction` / `tool`)。
194
+ - **多进程/多会话并发**:账本 seq 是全局递增,写入要串行;或按 sessionId 分文件,链只保证同文件内。
195
+ - **隐私**:head80 可能含敏感内容。建议再加一个开关 `ingress.headBytes`(默认 80,可设 0 只存长度和哈希)。
196
+ - **性能**:每请求多一次 sha256 + 一次文件追加,量级可忽略;但日志量会涨(每次请求一行,含每条消息一行)。建议 `scope.messages` 可采样(默认全记,超过 200 条只记新增)。
197
+
198
+ ### 8. 验收用例(必须先写,再写实现)
199
+
200
+ 1. **正常轮**:一人一句,`added_user_without_inbound = 0`。
201
+ 2. **系统注入**:runtime-context 那条被白名单排除,不误报。
202
+ 3. **模拟注入**:在 `dsh-llm` 收到 messages 后人为插一条 `role=user` 且无 inbound 的消息 → 必须报 1 且指向该条 `sha256`。
203
+ 4. **模型自造**:请求 messages 里始终没有某段文本,模型输出里有 → `ingress-anomalies` 必须**不出现**(否则说明对账逻辑把输出也当成了输入)。
204
+ 5. **写失败**:账本不可写时请求照常完成,日志里有降级记录。
205
+
206
+ 第 3 和第 4 条是这次事件的直接回归。
207
+
208
+ ### 9. 分阶段
209
+
210
+ | 阶段 | 内容 | 价值 |
211
+ |---|---|---|
212
+ | P0 | `llm.request` 观测 + 同链记账 | 有据可查,先把“进来的”钉住 |
213
+ | P1 | 与 inbound 对账 + `ingress-anomalies` 视图 | 注入可告警,误报可控 |
214
+ | P2 | 契约化:未声明的 `llm.request` 能力在 enforce 模式下拒绝 | 从“记录”变“约束” |
215
+
216
+ **建议先做 P0 的 `messages.hash` 和 `delta`**,因为这两个字段不依赖 inbound 对账,单侧就能回答“这次请求和上次有什么不同”——这次事件里,如果有它,我在 17:45:59 就会看到“新增了一条 user 消息”,而不是等到你想起来问“我真的发了吗”。
217
+
218
+ ---
219
+
220
+ ## 附:一句话留给以后
221
+
222
+ > 能证明“它不在输入里”的工具,和能证明“它是我编的”的工具,不是同一个。
223
+ > dashcam 现在两者都没有。补上第一个,是这次的教训;补上第二个,是它的下一个位置。
@@ -0,0 +1,418 @@
1
+ # dashcam 新增记录方案:ingress 审计
2
+
3
+ > 目标:下一次出现「来源不明的用户消息」时,能在一行账本里分清它是**进来的**还是**编出来的**。
4
+ > 本文只写记录方案与落点,不改动现有 Two-Key 判定语义。
5
+
6
+ ---
7
+
8
+ ## 0. 结论先行
9
+
10
+ 现有 dashcam 的观测面是**本机执行面**:工具调用、文件、进程、网络。幽灵消息没有产生任何这类动作,
11
+ 所以账本干净是正常的。缺的不是拦截,是**请求出口(egress)与消息入口(inbound)的两条元数据流**。
12
+
13
+ 本方案新增三类记录,全部落在同一条哈希链上:
14
+
15
+ | action | 作用 | 回答的问题 |
16
+ | --- | --- | --- |
17
+ | `llm.request` | 每次发往模型的请求:消息条数、整体指纹、与上次的差异、新增消息摘要 | 这次请求里**有没有**这条消息?它和上次比多了什么? |
18
+ | `llm.inbound` | 每条真正进入会话的输入:来源 kind、长度、sha256、前 N 字 | 这条消息**走过**客户端入口吗? |
19
+ | `llm.anomaly` | 两侧对账失败:请求里新增了 user 消息,但 inbound 找不到 | 有东西**绕过**消息通道进了上下文吗? |
20
+
21
+ 判据是四象限,不是单侧推断:
22
+
23
+ | inbound 有 | request 有 | 结论 |
24
+ | --- | --- | --- |
25
+ | ✓ | ✓ | 正常 |
26
+ | ✗ | ✓ | **注入**(或某层改了请求) |
27
+ | ✓ | ✗ | 丢失(客户端发了但没带上) |
28
+ | ✗ | ✗ | 不存在——**本次幽灵事件就落在这一格**(模型自造) |
29
+
30
+ 第四象限天然不会报「注入」,这正是原报告第一轮判错方向的原因。它必须写成显式用例,而不是靠人记得。
31
+
32
+ ---
33
+
34
+ ## 1. 与现有机制的硬约束(先对齐,再设计)
35
+
36
+ ### 1.1 Ledger 字段是固定的
37
+
38
+ [ledger.js](../../src/runtime/ledger.js) 的 `buildRecord()` 只写固定字段:
39
+ `v / seq / ts / plugin / pluginVersion / capability / action / scope / decision / ruleId / reason / intercepted / prevHash / hash / mac`。
40
+ `append()` 收到多余顶层字段会**直接丢弃**;`decision` 只接受 `allow | deny`,否则抛错。
41
+
42
+ 因此新记录必须遵守:
43
+
44
+ - 全部业务字段放进 `scope`(对象),不新增顶层字段;
45
+ - 观测记录一律 `decision: 'allow'`、`intercepted: false`;
46
+ - 异常不是拦截:`ruleId: 'ingress-anomaly'`,但不写 `deny`、不写 `intercepted`;
47
+ - 继续走 `Ledger.append()`,自动继承 `seq / prevHash / mac`,离线 `verify()` 不改一行。
48
+
49
+ ### 1.2 metrics 只排除 `telemetry`
50
+
51
+ [metrics.js](../../src/governance/metrics.js) 的 `isTelemetryRecord()` 只认
52
+ `capability === 'telemetry'`。新增 `llm.ingress` 若不改口径,每次请求都会进 `requests / allows`,
53
+ 把拦截率与月度曲线整体稀释。
54
+
55
+ 方案:把「观测类」从单一 `telemetry` 扩成集合,并新增并列读数(见 §3.3)。
56
+ **核心与宿主必须同版本上线**——宿主 `require('../../dsh-dashcam/src/index.js')`,本来就是锁步引用。
57
+
58
+ ### 1.3 宿主已有「附加记录」通道
59
+
60
+ [dsh-dashcam-host/lib/index.js](../../dsh-dashcam-host/lib/index.js) 的 `appendAuxRecord()` 已证明:
61
+ 非判定记录可以直接 `ledger.append()`,写失败只告警、不阻断。
62
+ `mount` / `unmapped-tool` / `unjudgeable-tool` / `proc.commandline` 都走这条路。
63
+ ingress 记录复用同一通道,不新开写入口。
64
+
65
+ ### 1.4 挂载点
66
+
67
+ 宿主当前只订阅 `tools/pre-execute`。ingress 需要挂在**provider 被调用之前、messages 数组定型之后**。
68
+
69
+ 已按本机 DSH 安装(`resources/app.asar`,2026-11-08)核对,落点如下:
70
+
71
+ - **请求出口**:`llm/stream` waterfall。`dsh-llm` 在 `streamWithRegistration` 里调用
72
+ `ctx.waterfall(this, "llm/stream", options, () => this.adapterStream(options, prepared))`,
73
+ `options` 就是完整请求(`provider / model / messages / tools / sessionId / signal`)。
74
+ 监听器必须 `return next()`,否则请求被截断。
75
+ - **不采用 `agent/request`**:源码注释明确「cannot change request messages」,
76
+ 且发生在 messages 派生之前,不能用于取证。
77
+ - **消息入口**:`session/event` 的 `user/message`(签名 `(session, event)`,
78
+ `event.data.source.kind` 可用),与幽灵报告读取的会话日志同源。
79
+ - **不采用 `agent/inbox/spliced`**:它是投递事件,条目可能随后被取消;
80
+ `user/message` 才是真正进面的 durable 事实。
81
+
82
+ 两个事件名都可用 `config.ingress.requestEvent / inboundEvent` 覆盖。
83
+ **接不上必须可见**:挂载/关闭都写 `telemetry/ingress-mount | ingress-disabled`,
84
+ 写明监听了什么,不静默关闭(P7 的教训:桌面版看不到 stdout)。
85
+
86
+ ---
87
+
88
+ ## 2. 记录格式
89
+
90
+ ### 2.1 `llm.request`(每次请求一条)
91
+
92
+ ```json
93
+ {
94
+ "capability": "llm.ingress",
95
+ "action": "llm.request",
96
+ "decision": "allow",
97
+ "ruleId": "ingress-request",
98
+ "reason": "LLM 请求消息摘要(仅元数据;正文不落账)",
99
+ "intercepted": false,
100
+ "scope": {
101
+ "sessionId": "<sessionId>",
102
+ "requestId": "req-...",
103
+ "provider": "<provider>",
104
+ "model": "<model>",
105
+ "headBytes": 80,
106
+ "tools": { "count": 18, "hash": "sha256:..." },
107
+ "messages": {
108
+ "count": 42,
109
+ "hash": "sha256:...",
110
+ "delta": { "added": 2, "removed": 0, "changed": 0, "addedUserWithoutInbound": 1 }
111
+ },
112
+ "sample": [
113
+ {
114
+ "i": 41,
115
+ "role": "user",
116
+ "kind": "user",
117
+ "len": 21,
118
+ "head": "(示例:一条用户指令,原文已略)",
119
+ "sha256": "sha256:...",
120
+ "parts": 1,
121
+ "attachments": [{ "kind": "image", "idHash": "sha256:...", "size": 231044 }]
122
+ },
123
+ {
124
+ "i": 42,
125
+ "role": "user",
126
+ "kind": "runtime-context",
127
+ "len": 10830,
128
+ "head": "(记忆快照,前 80 字)",
129
+ "sha256": "sha256:...",
130
+ "parts": 1
131
+ }
132
+ ],
133
+ "omitted": 0,
134
+ "coverage": { "known": 41322, "unknown": 0 }
135
+ }
136
+ }
137
+ ```
138
+
139
+ 字段口径:
140
+
141
+ - **`messages.hash`**:按顺序对每条 `sha256(role + "\u0000" + text)`,再对拼接结果求一次 sha256。
142
+ 同一份输入两次请求指纹必须相同;改一个字节就变。
143
+ - **`delta`**:与**同 session 上一次请求**比较,按 `(role, sha256)` 序列做 LCS;
144
+ 只记计数 + 新增样本,不记全量差异。
145
+ - **`sample`**:只放新增/变更的消息(首请求放前 N 条),上限 `maxSample`(默认 32)。
146
+ 全量消息只贡献 hash,不逐条落账。
147
+ - **`kind`**:消息来源 `source.kind`(`user` / `runtime-context` / `time-context` /
148
+ `compaction` / `plugin:memory` / `skill-catalog` / `tool` / 未知按 `unknown`)。
149
+ **白名单按 kind 而不是 role**——本事件会话里 54 条 user 消息中只有 27 条是真人,
150
+ 按 role 白名单第一分钟就会误报。
151
+ - **`attachments`**:只记图片/文件的身份哈希与大小,不抓取内容。
152
+ 幽灵事件里「让看几张图但一张没来」,这一列是唯一能当场看出来的字段。
153
+ - **`coverage`**:provider 自报的 `known / unknown`,**只作辅助信号**。
154
+ provider 自己算错时 `unknown=0` 也不能证明清白,判据仍是 §2.3 的差集。
155
+
156
+ ### 2.2 `llm.inbound`(每条入站一条)
157
+
158
+ ```json
159
+ {
160
+ "capability": "llm.ingress",
161
+ "action": "llm.inbound",
162
+ "decision": "allow",
163
+ "ruleId": "ingress-inbound",
164
+ "intercepted": false,
165
+ "scope": {
166
+ "sessionId": "<sessionId>",
167
+ "messageId": "...",
168
+ "kind": "user",
169
+ "len": 21,
170
+ "head": "(示例:一条用户指令,原文已略)",
171
+ "sha256": "sha256:..."
172
+ }
173
+ }
174
+ ```
175
+
176
+ - 来源事件:`session/event` 的 `user/message`(已按本机 DSH 核对);**不扫正文**,
177
+ 只取 `source.kind / id / content 长度 / sha256 / 附件身份`。
178
+ `agent/inbox/spliced` 是投递事件、条目可被取消,不作为 inbound 基准。
179
+ - 只对 `kind` 不在白名单里的消息要求「必须出现在请求里」;系统注入类只登记、不参与告警。
180
+ - 每 session 内存索引有界(默认最近 500 条 / 1 小时),不落第二份完整对话。
181
+
182
+ ### 2.3 `llm.anomaly`(对账失败一条)
183
+
184
+ ```json
185
+ {
186
+ "capability": "llm.ingress",
187
+ "action": "llm.anomaly",
188
+ "decision": "allow",
189
+ "ruleId": "ingress-anomaly",
190
+ "reason": "请求新增 user 消息在 inbound 中无对应记录",
191
+ "intercepted": false,
192
+ "scope": {
193
+ "sessionId": "<sessionId>",
194
+ "requestId": "req-...",
195
+ "kind": "added_user_without_inbound",
196
+ "count": 1,
197
+ "sample": [{ "role": "user", "len": 6231, "sha256": "sha256:...", "head": "(示例:一段无来源的改版需求文本,原文已略)" }]
198
+ }
199
+ }
200
+ ```
201
+
202
+ 异常类型:
203
+
204
+ | kind | 触发 | 处置 |
205
+ | --- | --- | --- |
206
+ | `added_user_without_inbound` | 请求新增 user 消息,inbound 无匹配 | 记录 + console 告警;**不拦截** |
207
+ | `dropped_inbound` | inbound 有 user 消息,后续请求始终没带上 | 记录(另一类 bug) |
208
+ | `inbound_changed` | 同一 messageId 的 sha256 变了 | 记录 |
209
+
210
+ 匹配顺序:`sha256` 精确 → `messageId` → `(role, len)` 弱匹配(命中也标 `weak: true`)。
211
+ **`llm.anomaly` 永远不写 `deny`**:观测层一旦会拦请求,第一次误报就会把用户挡在门外,
212
+ 而本方案的第一目标是「有据可查」,不是「自动执法」。
213
+
214
+ ---
215
+
216
+ ## 3. 代码落点
217
+
218
+ ### 3.1 核心新增 `src/runtime/ingress.js`
219
+
220
+ 纯函数 + 一个有状态记录器,不依赖 Bridge、不做 IO:
221
+
222
+ ```js
223
+ // 纯函数(可直接单测)
224
+ summarizeMessage(message, { headBytes, maskSecrets })
225
+ summarizeMessages(messages, { headBytes, maxSample, maskSecrets })
226
+ // → { count, hash, summaries, omitted }
227
+ diffSummaries(previous, next)
228
+ // → { added, removed, changed, addedSamples }
229
+
230
+ // 记录器
231
+ createIngressRecorder({ ledger, policy, now, log })
232
+ .recordInbound({ sessionId, messageId, kind, text, ts })
233
+ .recordRequest({ sessionId, requestId, provider, model, messages, tools, coverage })
234
+ .dispose()
235
+ ```
236
+
237
+ 要点:
238
+
239
+ - 每个 session 保存 `lastSummaries` 与 `inboundIndex`,有界 LRU,`dispose()` 清空。
240
+ - 每条消息的 sha256 用 `WeakMap<message, hash>` 缓存:前缀缓存场景下多数消息对象不变,
241
+ 重复请求不重复哈希正文。
242
+ - `headBytes = 0` 时只写 `len / sha256`,不写 `head`;`maskSecrets` 复用宿主已有的
243
+ `maskSecrets()`(Bearer / `sk-` / `ghp_` / `password=` 等),并保留残余风险说明。
244
+ - 单条记录体积上限 `maxLineBytes`(默认 8 KiB):先砍 `sample`,再砍 `coverage`,
245
+ 最后写 `truncated: true`,绝不因为一条消息过大把账本撑爆。
246
+ - `ledger.append()` 包在 `try/catch` 里:失败进内存环形缓冲(默认 256 条)+ 写一次
247
+ `<ledgerPath>.guard.log`,**任何情况下都不向请求路径抛错**(fail-open)。
248
+
249
+ ### 3.2 核心导出与策略
250
+
251
+ - `src/index.js` 增加 `...require('./runtime/ingress')`。
252
+ - `src/policy.js` 增加 `DEFAULT_POLICY.ingress` 与 `resolveIngress()`:
253
+
254
+ | 键 | 默认 | 校验 |
255
+ | --- | --- | --- |
256
+ | `enabled` | `true` | 布尔 |
257
+ | `headBytes` | `80` | 整数 0–512(0 = 只存 hash/长度) |
258
+ | `maxSample` | `32` | 整数 1–512 |
259
+ | `maxLineBytes` | `8192` | 整数 ≥ 1024 |
260
+ | `inboundWindow` | `500` | 整数 ≥ 1 |
261
+ | `inboundTtlMs` | `3600000` | 整数 ≥ 0 |
262
+ | `maskSecrets` | `true` | 布尔 |
263
+ | `whitelistKinds` | `["runtime-context","time-context","compaction","plugin:memory","skill-catalog","tool","system"]` | 字符串数组 |
264
+
265
+ 非法值直接抛错,理由与 `resolveLimits()` 相同:`headBytes: 'abc'` 这类值会让上限比较恒为 false,
266
+ 属静默 fail-open。
267
+
268
+ ### 3.3 metrics 口径
269
+
270
+ ```js
271
+ const OBSERVATION_CAPABILITIES = new Set(['telemetry', 'llm.ingress']);
272
+ const isObservationRecord = (r) => OBSERVATION_CAPABILITIES.has(r && r.capability);
273
+ ```
274
+
275
+ - `decisions` 过滤掉两类观测记录;现有 `requests / allows / denies / interceptionRate`
276
+ 对旧账本读数**不变**。
277
+ - 新增并列读数:`ingressRequests`、`ingressInbound`、`ingressAnomalies`、`ingressAnomalyRate`。
278
+ - `telemetryRecords / telemetryDenies` 语义保持只统计 `telemetry`,不被请求记录稀释。
279
+ - `interceptions()` 不变(ingress 的 `intercepted` 恒为 `false`)。
280
+
281
+ ### 3.4 宿主新增 `dsh-dashcam-host/lib/ingress.js`
282
+
283
+ ```js
284
+ export function attachIngress(ctx, { ledger, config, guardLog }) { ... return { dispose } }
285
+ ```
286
+
287
+ - `lib/index.js` 在 `activate()` 成功后调用;`ctx.effect(() => dispose)`。
288
+ - 配置走宿主 `config.ingress`(与 `patchBuiltins` 同级),默认启用。
289
+ - 归一化 DSH 消息:`content` 为字符串或 parts 数组;文本取 `text`,图片/文件取
290
+ `fileId / sha256 / size`,其余 part 只记 type。任何无法识别的形状都退化成
291
+ `{ role, len, sha256 }`,不抛错。
292
+ - 事件缺失或签名不符:写 `telemetry/ingress-mount | ingress-disabled` 说明监听项,不静默关闭。
293
+
294
+ ### 3.5 CLI
295
+
296
+ ```powershell
297
+ # 先校验再读(与 metrics 同口径:mac_key_missing 直接非零退出)
298
+ node bin/dsh-dashcam.js ingress <ledger.jsonl> --session <id> [--mac-key-file <f>]
299
+
300
+ # 幽灵回归:这段文字有没有进过任何请求
301
+ node bin/dsh-dashcam.js ingress <ledger.jsonl> --find "状态栏"
302
+ ```
303
+
304
+ 输出:
305
+
306
+ - 请求数 / inbound 数 / 异常数;
307
+ - 每个异常的时间、session、requestId、`len`、`head`、`sha256`;
308
+ - `--find` 只在**已采样的 `head`** 里搜,明确标注「未采样消息不覆盖」,
309
+ 避免把「没搜到」说成「没发生」。
310
+
311
+ ### 3.6 版本与文档
312
+
313
+ - 核心 `README.md` 增加「ingress 记录」小节与 1.12.0 条目;
314
+ - `docs/SPEC.md` §6.2 账本字段表补一句:`capability='llm.ingress'` 为观测记录,
315
+ 不参与 Two-Key,不产生 allow/deny 语义;
316
+ - `docs/ROLLOUT.md` 第 6 节补 metrics 新读数口径;
317
+ - 宿主 README 补 `config.ingress` 表与事件发现步骤。
318
+
319
+ ---
320
+
321
+ ## 4. 分阶段
322
+
323
+ | 阶段 | 内容 | 交付判据 |
324
+ | --- | --- | --- |
325
+ | **P0** | 核心 `ingress.js` + `llm.request`(hash + delta)+ 宿主 egress 接线 + metrics 口径 | 账本每次请求一行;同一输入指纹相同;`--find` 可用;旧账本 metrics 读数不变 |
326
+ | **P1** | `llm.inbound` + `llm.anomaly` + CLI 异常视图 | 正常轮 0 异常;模拟注入 1 条异常并指到 sha256 |
327
+ | **P2** | 契约化:`llm.request` 成为 manifest 可声明能力;`enforce` 下未声明是否拒绝(默认仍 advisory);provider 响应元数据(requestId / usage / coverage) | 开关可回滚;关闭时留一条 `ingress-disabled` 记录 |
328
+ | **P3(可选)** | 响应侧元数据(输出 head/hash,不存推理全文),把「请求里没有、输出里有」的关联做成 `--find` 的一步 | 幽灵回归用例可全自动跑 |
329
+
330
+ 先做 P0 的理由:`messages.hash + delta` 不依赖 inbound,单侧就能回答
331
+ 「这次请求和上次比多了什么」。本次事件里若有它,17:45:59 就能看到「新增了一条 user 消息」,
332
+ 而不是等用户反问「我真的发了吗」。
333
+
334
+ ---
335
+
336
+ ## 5. 验收用例(先写用例,再写实现)
337
+
338
+ 1. **正常轮**:一人一句,`addedUserWithoutInbound = 0`,无 `llm.anomaly`。
339
+ 2. **系统注入白名单**:`runtime-context` / `compaction` / `plugin:memory` / `skill-catalog`
340
+ 各加一条,异常数仍为 0;但它们在 `llm.request.sample` 里可见。
341
+ 3. **模拟注入**:请求 messages 中插入一条 `role=user`、无 inbound 的消息 →
342
+ 恰好 1 条 `added_user_without_inbound`,`sample[0].sha256` 等于该条摘要。
343
+ 4. **模型自造(本次事件的直接回归)**:请求 messages 始终不含某段文本,只有模型输出含它 →
344
+ `llm.anomaly` **必须为 0**;`ingress --find` 在该账本上返回 0 条请求命中。
345
+ 这条是 P0 必测项,不能降级。
346
+ 5. **写失败**:账本只读/磁盘满 → 请求照常完成,`guard.log` 有一条降级记录。
347
+ 6. **指纹稳定**:同一 messages 两次请求 `messages.hash` 相同;改一个字符后不同。
348
+ 7. **diff 正确**:新增 2、删除 1、修改 1 时三个计数准确;乱序不误判为全量变更。
349
+ 8. **隐私开关**:`headBytes = 0` 时记录里没有 `head` 字段,任何消息正文都不落账。
350
+ 9. **体积**:1000 条消息、单条 200 KB → 单行 ≤ `maxLineBytes`,`omitted / truncated` 有值。
351
+ 10. **指标隔离**:混入 100 条 `llm.request` 后,`requests / interceptionRate` 与不含时完全一致,
352
+ `ingressRequests = 100`。
353
+ 11. **mac 兼容**:v3 账本(带 macKey)追加 ingress 记录后 `verify()` 仍 `ok`;
354
+ 无密钥校验 v3 仍报 `mac_key_missing`。
355
+ 12. **会话缺失**:`sessionId` 为空时写 `"unknown"`,记录仍落账,不抛错。
356
+
357
+ ---
358
+
359
+ ## 6. 已知边界(不隐藏)
360
+
361
+ - **服务端前缀不在观测范围**:本方案记录的是**客户端发出去的** messages。
362
+ 如果 provider 层在客户端之后追加/改写前缀,本地 egress 与「模型自造」长得一样。
363
+ `coverage.unknown` 只是辅助信号,不能当实锤;要钉死必须让 provider 暴露最终 messages
364
+ 或服务端前缀 hash(P2/P3)。
365
+ - **模型推理不可见**:dashcam 记录不到 reasoning 文本,只能证明「请求里没有 X」。
366
+ 「X 是编的」是**推论**,不是本工具的直接观测。
367
+ - **采样有损**:`sample` 只留新增/变更消息,`head` 只留前 N 字;
368
+ `--find` 搜不到不等于没发生。这是体积与可诊断性的取舍,必须在输出里写明。
369
+ - **inbound 源依赖宿主事件**:`session/event` 的 `user/message` 已在本机 DSH 核对可用;
370
+ 若未来版本改签名,宿主会写 `telemetry/ingress-mount` 说明监听项,可改配置回退,
371
+ 不假装有对账。
372
+ - **head 可能含敏感内容**:默认 80 字节 + `maskSecrets` 是 best-effort;
373
+ 高敏环境应设 `headBytes: 0`。
374
+ - **不解决 `compress` 不校验区间**:那是工具侧输入校验问题,与本记录方案正交。
375
+ 建议单独修:`compress` 对未知消息编号必须报错,而不是盖章。
376
+
377
+ ---
378
+
379
+ ## 7. 实施状态(1.12.0,2026-11-08)
380
+
381
+ 已落地:
382
+
383
+ - 核心 [ingress.js](../../src/runtime/ingress.js):`summarizeMessage(s)` / `diffSummaries` /
384
+ `createIngressRecorder` / `findIngressMatches` / `summarizeIngress`。
385
+ - 策略:`policy.ingress`(含 `enabled` 与 §3.2 的全部键),非法值 fail-fast。
386
+ - metrics:`llm.ingress` 与 `telemetry` 一并排除出判定口径,另列
387
+ `ingressRecords / ingressRequests / ingressInbound / ingressAnomalies / ingressAnomalyRate`。
388
+ - 宿主:`lib/ingress.js` 订阅 `llm/stream`(请求,waterfall)与 `session/event`
389
+ (入站,过滤 `user/message`),均可配置;挂载/关闭都写
390
+ `telemetry/ingress-mount|ingress-disabled`,写明监听项。
391
+ - CLI:`dsh-dashcam ingress <ledger> [--session <id>] [--find <text>]`,先验签再统计。
392
+ - 用例:`test/ingress.test.js` 覆盖指纹稳定、附件身份、diff、白名单、注入、丢输入、
393
+ 第四象限回归、fail-open、体积上限、mac 验签、metrics 隔离、策略校验;
394
+ 宿主 `test/ingress-host.mjs` 覆盖事件接线与端到端落账。
395
+
396
+ 实施中的三点修正:
397
+
398
+ 1. 消息指纹额外包含**附件身份**(`role \0 text \0 附件 idHash`)。只算正文时,
399
+ 「同一句话配不同图」与「只有图没有字」会撞成同一个指纹——本事件的图片缺失正需要这一列。
400
+ 2. `llm.request` 与异常记录多一个 `baseline` / 采样下标 `i`:前者用于「中途接入宿主时首请求不告警」,
401
+ 后者让样本能定位到请求里的真实消息位置,而不是样本数组里的偏移。
402
+ 3. **对账只认 `role=user`**:assistant / tool / system 是请求里新生成的回合内容,
403
+ 不在 inbound 里找对应记录。1.12.0 首跑真实会话时,工具结果与模型回复被误报成
404
+ `added_user_without_inbound`;修正后同类请求 0 异常,真正的无源 user 消息仍会报。
405
+ 用例见 `test/ingress.test.js`「助手/工具消息新增不算注入」。
406
+
407
+ 事件名已在本机 DSH 安装中核对(`resources/app.asar`,2026-11-08):
408
+ 请求出口 `llm/stream`(waterfall,载荷为完整请求,必须 `return next()`),
409
+ 入站 `session/event`(`(session, event)`,只取 `user/message`)。
410
+ 两个键都可配置;本机核对依据见 §1.4。
411
+
412
+ ---
413
+
414
+ ## 8. 一句话
415
+
416
+ > 旧账本记的是「谁动了什么」;新增的这三类记录记的是「谁说了什么、以谁的身份进来的」。
417
+ > 它不能判断内容真假,但能让「不在请求里」这句话第一次有工具输出作为依据——
418
+ > 而不是只有记忆和推断。