@furongjun1999/dsh-memory 0.9.7 → 0.9.9

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 (68) hide show
  1. package/README.md +150 -662
  2. package/codebuddy/CODEBUDDY.md +337 -204
  3. package/docs/README.md +21 -0
  4. package/docs/discipline/harnesses.yaml +11 -3
  5. package/docs/discipline/templates/compact.txt.tmpl +20 -18
  6. package/docs/discipline/templates/full.md.tmpl +63 -61
  7. package/docs/discipline/templates/rules.mdc.tmpl +5 -3
  8. package/docs/discipline/templates/skill.md.tmpl +25 -23
  9. package/docs/discipline/templates/spec.txt.tmpl +1 -1
  10. package/docs/discipline/templates/zcode-user.md.tmpl +1 -1
  11. package/docs//350/247/204/350/214/203/AI/347/274/226/347/250/213/351/200/232/347/224/250/350/247/204/350/214/203.md +4 -0
  12. package/dsh/cordis.yml.example +2 -2
  13. package/lib/hooks.d.ts +11 -1
  14. package/lib/hooks.js +59 -4
  15. package/lib/index.d.ts +1 -1
  16. package/lib/index.js +11 -5
  17. package/lib/init.js +28 -4
  18. package/lib/lib/hook_audit.d.ts +3 -0
  19. package/lib/lib/hook_audit.js +63 -0
  20. package/md_cg/autonomy.py +1 -1
  21. package/md_cg/config_registry.py +329 -329
  22. package/md_cg/config_registry_bulk.py +483 -482
  23. package/md_cg/config_render.py +27 -0
  24. package/md_cg/config_validate.py +456 -455
  25. package/md_cg/conflict_surface.py +127 -0
  26. package/md_cg/mcp_server.py +5324 -5227
  27. package/md_cg/mdcg.py +12 -1
  28. package/md_cg/mdcos.py +7159 -7108
  29. package/md_cg/pooling.py +487 -485
  30. package/md_cg/qmd_llm.py +334 -334
  31. package/md_cg/reach.py +10 -4
  32. package/md_cg/sleep.py +2 -2
  33. package/md_cg/sustain.py +13 -4
  34. package/md_cg/test_auto_defaults.py +463 -463
  35. package/md_cg/test_autonomy_emotion.py +328 -328
  36. package/md_cg/test_bm25_default.py +56 -0
  37. package/md_cg/test_c3_transient_read_negative.py +7 -3
  38. package/md_cg/test_conflict_surface.py +75 -0
  39. package/md_cg/test_conflict_value_untrusted.py +63 -0
  40. package/md_cg/test_exact_text_cache.py +194 -191
  41. package/md_cg/test_heartbeat_ledger.py +563 -557
  42. package/md_cg/test_hotcache_tool.py +121 -0
  43. package/md_cg/test_issue274_read_node_id_none.py +364 -341
  44. package/md_cg/test_issue561_pending_review.py +89 -5
  45. package/md_cg/test_issue578_service_info_gate.py +264 -0
  46. package/md_cg/test_n184_keys_concurrent_provision.py +1 -1
  47. package/md_cg/test_p3_legacy_closure.py +441 -438
  48. package/md_cg/test_p43_pooling.py +419 -412
  49. package/md_cg/test_reach.py +5 -1
  50. package/md_cg/test_reach_exits.py +54 -0
  51. package/md_cg/test_reach_single_char.py +74 -0
  52. package/md_cg/test_read_scope_b27.py +2 -2
  53. package/md_cg/test_search_bm25_default.py +60 -0
  54. package/md_cg/test_security_audit_v21.py +249 -249
  55. package/md_cg/test_sleep_p1.py +1032 -1032
  56. package/md_cg/test_sustain_bad_stamp.py +178 -0
  57. package/md_cg/test_untrusted_audit.py +55 -0
  58. package/md_cg/test_untrusted_classifier.py +42 -0
  59. package/md_cg/test_untrusted_enforcement.py +66 -0
  60. package/md_cg/untrusted.py +45 -0
  61. package/md_cg/untrusted_audit.py +87 -0
  62. package/md_cg/value_conflict.py +71 -0
  63. package/package.json +7 -7
  64. package/src/hooks.ts +986 -932
  65. package/src/index.ts +20 -14
  66. package/src/init.ts +21 -4
  67. package/src/lib/hook_audit.ts +334 -282
  68. package/zcode/AGENTS.md +337 -204
@@ -1,282 +1,334 @@
1
- /**
2
- * hook_audit.ts · 自动记忆钩子的**有界落盘审计**(issue #56,诊断面)
3
- *
4
- * 病灶(报告人 jiamajie,v0.7.1 实测):src/hooks.ts 的三处过滤分支(子代理会话 /
5
- * 中继消息 / `source.kind !== 'user'`)只调 `ctx.logger.info`——宿主 logger 不落盘,
6
- * 盘面完全无痕。其它插件按设计注入的 `role:"user"` 消息(如 @michengai/dsh-pua 的
7
- * PUA_RUNTIME_V1 提示)不进记忆库时,从记忆侧只能看到「少了一条」,无法区分
8
- * 「被设计滤除」与「写入失败/漏记」。
9
- *
10
- * 本模块 = **诊断面**,不参与任何写入/过滤判定(红线:哪些消息进记忆一字不动):
11
- * ① 维护一份小 JSON 状态文件(缺省 `~/.dsh/logs/dsh-memory-hook-audit.json`,
12
- * 与 `lingshu-bridge-debug.log` / `dsh-memory-apply-error.log` 同目录同惯例,
13
- * 见 README.md:110);
14
- * ② 每事件只写计数与「最近条目」摘要(action/reason/kind/role),**绝不记录
15
- * 消息内容**(内容可能含隐私/凭据,审计文件是可被随手打开的诊断件);
16
- * ③ 原子写:同目录临时文件 + rename(读者永远不会看到半截 JSON);
17
- * ④ 有界:last 截断到 MAX_LAST=20(无追加式增长);kinds 键数上限 MAX_KINDS,
18
- * 超限归并到 "other"(kind 值域理论上由宿主决定,防异常值把文件撑大);
19
- * ⑤ 静默降级:公共方法全部 try/catch 包死——审计失败绝不冒泡进记忆路径
20
- * (审计是增益,记忆写入必须照常)。
21
- *
22
- * 为什么落盘采用**同步** fs:`session/event` 回调是同步的,异步落盘会引入
23
- * 「多事件并发写同一文件」的乱序与竞态;状态文件只有几 KB,一次同步读(仅首次)
24
- * 加一次全量重写的代价远小于它守护的诊断价值。
25
- *
26
- * 与 ctx.logger.info 的关系:hook 内三行 info 日志**保留不动**(in-memory 实时
27
- * 视图),本审计是**盘面**视图(宿主 logger 不落盘时仍可复盘)。
28
- *
29
- * 边界(如实):
30
- * · 状态是「进程内缓存 + 每次全量重写」,多进程同时写同一路径会互相覆盖
31
- * (插件单实例部署下不构成问题;审计非关键路径,不做跨进程锁);
32
- * · 审计文件损坏/手改致形态不符时按空态重建(数值归零、last 逐条过滤),
33
- * 不抛错、不保留非法内容;
34
- * · `written` 记的是「**成功发起**」的写入(fire-and-forget 的发起时刻),
35
- * 发起后失败另记 `skipped.failed`——与 hooks.ts 的 memorize 两段式对应。
36
- */
37
- import { closeSync, mkdirSync, openSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync } from 'node:fs'
38
- import { homedir } from 'node:os'
39
- import { expandHome } from './datapath.js'
40
- import { dirname, join } from 'node:path'
41
-
42
- /** 三处过滤分支的成因(与 hooks.ts 一一对应:子代理会话 / 中继消息 / kind 非 user)。 */
43
- export type HookFilterReason = 'subagent' | 'relay' | 'kind'
44
- /** 写入路径的角色(与 md_cg 对 DSH 会话事件的 role 约定一致)。 */
45
- export type HookWriteRole = 'user' | 'assistant' | 'tool'
46
- /** 跳过写入的成因。 */
47
- export type HookSkipReason = 'sanitized' | 'not_ready' | 'failed'
48
-
49
- /** last 的一条摘要(**绝不含消息内容**——只有动作、成因、kind 与 role)。 */
50
- export interface HookAuditEntry {
51
- ts: string
52
- action: 'filtered' | 'written' | 'skipped'
53
- reason?: HookFilterReason | HookSkipReason
54
- kind?: string
55
- role?: HookWriteRole
56
- }
57
-
58
- /** 审计状态(= 状态文件的结构)。 */
59
- export interface HookAuditState {
60
- counts: {
61
- /** 三处过滤分支的计数。 */
62
- filtered: Record<HookFilterReason, number>
63
- /** 成功发起的写入计数(按 role 分解)。 */
64
- written: Record<HookWriteRole, number>
65
- /** 跳过写入的计数(脱敏置空 / 认知图未就绪 / 写入失败)。 */
66
- skipped: Record<HookSkipReason, number>
67
- }
68
- /** 进入消息级处理的 `source.kind` 分布(缺字段/空串/非字符串记 "undefined")。 */
69
- kinds: Record<string, number>
70
- /** 最近 ≤MAX_LAST 条摘要。 */
71
- last: HookAuditEntry[]
72
- updated_at: string
73
- }
74
-
75
- /** 缺省审计文件:与桥探针 / apply 探针同目录同惯例(README.md:110)。 */
76
- /**
77
- * 审计根:优先 `DSH_HOME`(隔离/多 home 安装必须显式给),否则 `~/.dsh`。
78
- * issue #554 §7:此前恒用 homedir,隔离 home 下审计写到生产 home,与 brain 分离。
79
- * 兼容 `~` 与 `~/x` 形态;其余按字面路径处理(不做 shell 展开)。
80
- */
81
- function defaultHookAuditPath(): string {
82
- const raw = (process.env.DSH_HOME ?? '').trim()
83
- // 唯一实现:路径展开复用 datapath.expandHome(禁止第二处判据,见 test/datapath-expandhome)。
84
- const root = raw ? expandHome(raw) : join(homedir(), '.dsh')
85
- return join(root, 'logs', 'dsh-memory-hook-audit.json')
86
- }
87
-
88
- export const DEFAULT_HOOK_AUDIT_PATH = defaultHookAuditPath()
89
-
90
- /** last 条数上限(有界性单点——没有它 audit 文件会随会话无限增长)。 */
91
- const MAX_LAST = 20
92
- /** kinds 键数上限(超限归并到 OTHER_KIND,防宿主 kind 值域异常撑大文件)。 */
93
- const MAX_KINDS = 32
94
- /** kinds 归并桶。 */
95
- const OTHER_KIND = 'other'
96
-
97
- const FILTER_REASONS: HookFilterReason[] = ['subagent', 'relay', 'kind']
98
- const WRITE_ROLES: HookWriteRole[] = ['user', 'assistant', 'tool']
99
- const SKIP_REASONS: HookSkipReason[] = ['sanitized', 'not_ready', 'failed']
100
-
101
- /** `source.kind` 的规范化取值:非字符串(含缺字段)或空串一律记 "undefined"
102
- * (不可辨认即无值——空串与缺字段在排障上同义)。 */
103
- export function kindOf(source: unknown): string {
104
- const k = (source as { kind?: unknown } | null | undefined)?.kind
105
- return typeof k === 'string' && k.length > 0 ? k : 'undefined'
106
- }
107
-
108
- function nowIso(): string {
109
- return new Date().toISOString()
110
- }
111
-
112
- function emptyState(): HookAuditState {
113
- return {
114
- counts: {
115
- filtered: { subagent: 0, relay: 0, kind: 0 },
116
- written: { user: 0, assistant: 0, tool: 0 },
117
- skipped: { sanitized: 0, not_ready: 0, failed: 0 },
118
- },
119
- kinds: {},
120
- last: [],
121
- updated_at: nowIso(),
122
- }
123
- }
124
-
125
- /** 计数位:只认有限非负整数,其余归零(防手改/坏文件把计数变成 NaN)。 */
126
- function countOf(v: unknown): number {
127
- return typeof v === 'number' && Number.isFinite(v) && v >= 0 ? Math.floor(v) : 0
128
- }
129
-
130
- /** 盘面内容 → 状态:逐字段归并,形态不符的字段一律丢弃(不信任盘面内容)。 */
131
- function mergeState(raw: unknown): HookAuditState {
132
- const s = emptyState()
133
- if (!raw || typeof raw !== 'object') return s
134
- const r = raw as { counts?: unknown; kinds?: unknown; last?: unknown }
135
- if (r.counts && typeof r.counts === 'object') {
136
- const c = r.counts as { filtered?: unknown; written?: unknown; skipped?: unknown }
137
- const buckets: Array<[Record<string, number>, string[], unknown]> = [
138
- [s.counts.filtered as Record<string, number>, FILTER_REASONS, c.filtered],
139
- [s.counts.written as Record<string, number>, WRITE_ROLES, c.written],
140
- [s.counts.skipped as Record<string, number>, SKIP_REASONS, c.skipped],
141
- ]
142
- for (const [dst, keys, src] of buckets) {
143
- if (!src || typeof src !== 'object') continue
144
- for (const key of keys) dst[key] = countOf((src as Record<string, unknown>)[key])
145
- }
146
- }
147
- if (r.kinds && typeof r.kinds === 'object') {
148
- for (const [k, v] of Object.entries(r.kinds as Record<string, unknown>)) {
149
- if (typeof v === 'number' && Number.isFinite(v) && v > 0) s.kinds[k] = Math.floor(v)
150
- }
151
- }
152
- if (Array.isArray(r.last)) {
153
- for (const e of r.last) {
154
- if (!e || typeof e !== 'object') continue
155
- const entry = e as Partial<HookAuditEntry>
156
- if (typeof entry.ts !== 'string') continue
157
- if (entry.action !== 'filtered' && entry.action !== 'written' && entry.action !== 'skipped') continue
158
- s.last.push(entry as HookAuditEntry)
159
- }
160
- if (s.last.length > MAX_LAST) s.last = s.last.slice(-MAX_LAST)
161
- }
162
- return s
163
- }
164
-
165
- /**
166
- * 有界落盘审计记录器(**静默降级**:任何公共方法都不会抛错)。
167
- *
168
- * 用法(hooks.ts 内):`new HookAuditRecorder(opts.auditPath)`,随后在
169
- * 三处过滤分支与写入/跳过路径各调一次对应方法。审计失败只影响审计自身。
170
- */
171
- export class HookAuditRecorder {
172
- /** 实际生效的审计文件路径(构造时定死,供日志/测试核对)。 */
173
- readonly path: string
174
- /** 进程内状态缓存(首次记录时从盘面载入,此后只增量改内存 + 全量重写)。 */
175
- #state: HookAuditState | null = null
176
-
177
- constructor(path?: string) {
178
- this.path = typeof path === 'string' && path.trim() ? path.trim() : DEFAULT_HOOK_AUDIT_PATH
179
- }
180
-
181
- /** 一条**被设计滤除**的消息(三处过滤分支各调一次)。 */
182
- filtered(reason: HookFilterReason, kind?: string): void {
183
- this.#mutate((s) => {
184
- s.counts.filtered[reason] += 1
185
- s.last.push(kind === undefined
186
- ? { ts: nowIso(), action: 'filtered', reason }
187
- : { ts: nowIso(), action: 'filtered', reason, kind })
188
- })
189
- }
190
-
191
- /** `source.kind` 分布(每条**进入消息级处理**的事件调一次,含被滤与放行)。 */
192
- observeKind(kind: string): void {
193
- this.#mutate((s) => {
194
- const key = this.#boundedKindKey(s, kind)
195
- s.kinds[key] = (s.kinds[key] ?? 0) + 1
196
- })
197
- }
198
-
199
- /** 成功**发起**的写入(按 role;发起后失败另记 skipped.failed)。 */
200
- written(role: HookWriteRole): void {
201
- this.#mutate((s) => {
202
- s.counts.written[role] += 1
203
- s.last.push({ ts: nowIso(), action: 'written', role })
204
- })
205
- }
206
-
207
- /** 跳过写入(脱敏置空 / 认知图未就绪 / 写入失败)。 */
208
- skipped(reason: HookSkipReason, role?: HookWriteRole): void {
209
- this.#mutate((s) => {
210
- s.counts.skipped[reason] += 1
211
- s.last.push(role === undefined
212
- ? { ts: nowIso(), action: 'skipped', reason }
213
- : { ts: nowIso(), action: 'skipped', reason, role })
214
- })
215
- }
216
-
217
- /** 键数有界:已见键原样用;新键在未达上限时收录,达限后统一归并到 "other"。 */
218
- #boundedKindKey(s: HookAuditState, kind: string): string {
219
- if (Object.prototype.hasOwnProperty.call(s.kinds, kind)) return kind
220
- return Object.keys(s.kinds).length >= MAX_KINDS ? OTHER_KIND : kind
221
- }
222
-
223
- /** 读改写 + 原子落盘;整段 try/catch——审计失败静默降级(绝不冒泡进记忆路径)。 */
224
- #mutate(fn: (s: HookAuditState) => void): void {
225
- // #563④:审计文件被同用户的多个 DSH 进程共用;此前 #state 只在首次载入、写回整份 rename 覆盖
226
- // ⇒ 并发时后写者用内存态盖掉他人计数(实测 400→201 / 400→311)。现改为锁内 重读→改→写。
227
- if (!this.#acquireLock()) return
228
- try {
229
- const s = this.#load()
230
- fn(s)
231
- if (s.last.length > MAX_LAST) s.last = s.last.slice(-MAX_LAST)
232
- s.updated_at = nowIso()
233
- this.#save(s)
234
- this.#state = s
235
- } catch { /* 审计失败静默降级:记忆路径必须照常 */ }
236
- finally { this.#releaseLock() }
237
- }
238
-
239
- /** 跨进程排他锁:独占创建 `${path}.lock`;陈旧锁(>5s)清掉;超时返回 false(静默降级)。 */
240
- #acquireLock(timeoutMs = 800): boolean {
241
- const lock = `${this.path}.lock`
242
- const t0 = Date.now()
243
- for (;;) {
244
- try {
245
- closeSync(openSync(lock, 'wx'))
246
- return true
247
- } catch {
248
- try { if (Date.now() - statSync(lock).mtimeMs > 5000) unlinkSync(lock) } catch { /* 已释放 */ }
249
- if (Date.now() - t0 > timeoutMs) return false
250
- const until = Date.now() + 5
251
- while (Date.now() < until) { /* 自旋 5ms */ }
252
- }
253
- }
254
- }
255
-
256
- #releaseLock(): void {
257
- try { unlinkSync(`${this.path}.lock`) } catch { /* 已清理 */ }
258
- }
259
-
260
- /** 盘面 → 状态;不存在/不可读/坏 JSON/形态不符 → 空态重建(不抛)。 */
261
- #load(): HookAuditState {
262
- try {
263
- return mergeState(JSON.parse(readFileSync(this.path, 'utf8')) as unknown)
264
- } catch {
265
- return emptyState()
266
- }
267
- }
268
-
269
- /** 原子写:同目录临时文件 + rename(临时文件在 rename 失败时清理)。 */
270
- #save(s: HookAuditState): void {
271
- const dir = dirname(this.path)
272
- mkdirSync(dir, { recursive: true })
273
- const tmp = `${this.path}.${process.pid.toString(36)}.${Date.now().toString(36)}.tmp`
274
- writeFileSync(tmp, `${JSON.stringify(s, null, 2)}\n`, 'utf8')
275
- try {
276
- renameSync(tmp, this.path)
277
- } catch (err) {
278
- try { unlinkSync(tmp) } catch { /* 清理失败忽略:残留 .tmp 不影响读路径 */ }
279
- throw err
280
- }
281
- }
282
- }
1
+ /**
2
+ * hook_audit.ts · 自动记忆钩子的**有界落盘审计**(issue #56,诊断面)
3
+ *
4
+ * 病灶(报告人 jiamajie,v0.7.1 实测):src/hooks.ts 的三处过滤分支(子代理会话 /
5
+ * 中继消息 / `source.kind !== 'user'`)只调 `ctx.logger.info`——宿主 logger 不落盘,
6
+ * 盘面完全无痕。其它插件按设计注入的 `role:"user"` 消息(如 @michengai/dsh-pua 的
7
+ * PUA_RUNTIME_V1 提示)不进记忆库时,从记忆侧只能看到「少了一条」,无法区分
8
+ * 「被设计滤除」与「写入失败/漏记」。
9
+ *
10
+ * 本模块 = **诊断面**,不参与任何写入/过滤判定(红线:哪些消息进记忆一字不动):
11
+ * ① 维护一份小 JSON 状态文件(缺省 `~/.dsh/logs/dsh-memory-hook-audit.json`,
12
+ * 与 `lingshu-bridge-debug.log` / `dsh-memory-apply-error.log` 同目录同惯例,
13
+ * 见 README.md:110);
14
+ * ② 每事件只写计数与「最近条目」摘要(action/reason/kind/role),**绝不记录
15
+ * 消息内容**(内容可能含隐私/凭据,审计文件是可被随手打开的诊断件);
16
+ * ③ 原子写:同目录临时文件 + rename(读者永远不会看到半截 JSON);
17
+ * ④ 有界:last 截断到 MAX_LAST=20(无追加式增长);kinds 键数上限 MAX_KINDS,
18
+ * 超限归并到 "other"(kind 值域理论上由宿主决定,防异常值把文件撑大);
19
+ * ⑤ 静默降级:公共方法全部 try/catch 包死——审计失败绝不冒泡进记忆路径
20
+ * (审计是增益,记忆写入必须照常)。
21
+ *
22
+ * 为什么落盘采用**同步** fs:`session/event` 回调是同步的,异步落盘会引入
23
+ * 「多事件并发写同一文件」的乱序与竞态;状态文件只有几 KB,一次同步读(仅首次)
24
+ * 加一次全量重写的代价远小于它守护的诊断价值。
25
+ *
26
+ * 与 ctx.logger.info 的关系:hook 内三行 info 日志**保留不动**(in-memory 实时
27
+ * 视图),本审计是**盘面**视图(宿主 logger 不落盘时仍可复盘)。
28
+ *
29
+ * 边界(如实):
30
+ * · 状态是「进程内缓存 + 每次全量重写」,多进程同时写同一路径会互相覆盖
31
+ * (插件单实例部署下不构成问题;审计非关键路径,不做跨进程锁);
32
+ * · 审计文件损坏/手改致形态不符时按空态重建(数值归零、last 逐条过滤),
33
+ * 不抛错、不保留非法内容;
34
+ * · `written` 记的是「**成功发起**」的写入(fire-and-forget 的发起时刻),
35
+ * 发起后失败另记 `skipped.failed`——与 hooks.ts 的 memorize 两段式对应。
36
+ */
37
+ import { closeSync, mkdirSync, openSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync } from 'node:fs'
38
+ import { homedir } from 'node:os'
39
+ import { expandHome } from './datapath.js'
40
+ import { dirname, join } from 'node:path'
41
+
42
+ /** 三处过滤分支的成因(与 hooks.ts 一一对应:子代理会话 / 中继消息 / kind 非 user)。 */
43
+ export type HookFilterReason = 'subagent' | 'relay' | 'kind'
44
+ /** 写入路径的角色(与 md_cg 对 DSH 会话事件的 role 约定一致)。 */
45
+ export type HookWriteRole = 'user' | 'assistant' | 'tool'
46
+ /** 跳过写入的成因。 */
47
+ export type HookSkipReason = 'sanitized' | 'not_ready' | 'failed'
48
+
49
+ /** last 的一条摘要(**绝不含消息内容**——只有动作、成因、kind 与 role)。 */
50
+ export interface HookAuditEntry {
51
+ ts: string
52
+ action: 'filtered' | 'written' | 'skipped'
53
+ reason?: HookFilterReason | HookSkipReason
54
+ kind?: string
55
+ role?: HookWriteRole
56
+ }
57
+
58
+ /** 审计状态(= 状态文件的结构)。 */
59
+ export interface HookAuditState {
60
+ counts: {
61
+ /** 三处过滤分支的计数。 */
62
+ filtered: Record<HookFilterReason, number>
63
+ /** 成功发起的写入计数(按 role 分解)。 */
64
+ written: Record<HookWriteRole, number>
65
+ /** 跳过写入的计数(脱敏置空 / 认知图未就绪 / 写入失败)。 */
66
+ skipped: Record<HookSkipReason, number>
67
+ }
68
+ /** 进入消息级处理的 `source.kind` 分布(缺字段/空串/非字符串记 "undefined")。 */
69
+ kinds: Record<string, number>
70
+ /** 最近 ≤MAX_LAST 条摘要。 */
71
+ last: HookAuditEntry[]
72
+ updated_at: string
73
+ }
74
+
75
+ /** 缺省审计文件:与桥探针 / apply 探针同目录同惯例(README.md:110)。 */
76
+ /**
77
+ * 审计根:优先 `DSH_HOME`(隔离/多 home 安装必须显式给),否则 `~/.dsh`。
78
+ * issue #554 §7:此前恒用 homedir,隔离 home 下审计写到生产 home,与 brain 分离。
79
+ * 兼容 `~` 与 `~/x` 形态;其余按字面路径处理(不做 shell 展开)。
80
+ */
81
+ function defaultHookAuditPath(): string {
82
+ const raw = (process.env.DSH_HOME ?? '').trim()
83
+ // 唯一实现:路径展开复用 datapath.expandHome(禁止第二处判据,见 test/datapath-expandhome)。
84
+ const root = raw ? expandHome(raw) : join(homedir(), '.dsh')
85
+ return join(root, 'logs', 'dsh-memory-hook-audit.json')
86
+ }
87
+
88
+ export const DEFAULT_HOOK_AUDIT_PATH = defaultHookAuditPath()
89
+
90
+ /** last 条数上限(有界性单点——没有它 audit 文件会随会话无限增长)。 */
91
+ const MAX_LAST = 20
92
+ /** kinds 键数上限(超限归并到 OTHER_KIND,防宿主 kind 值域异常撑大文件)。 */
93
+ const MAX_KINDS = 32
94
+ /** kinds 归并桶。 */
95
+ const OTHER_KIND = 'other'
96
+
97
+ const FILTER_REASONS: HookFilterReason[] = ['subagent', 'relay', 'kind']
98
+ const WRITE_ROLES: HookWriteRole[] = ['user', 'assistant', 'tool']
99
+ const SKIP_REASONS: HookSkipReason[] = ['sanitized', 'not_ready', 'failed']
100
+
101
+ /** `source.kind` 的规范化取值:非字符串(含缺字段)或空串一律记 "undefined"
102
+ * (不可辨认即无值——空串与缺字段在排障上同义)。 */
103
+ export function kindOf(source: unknown): string {
104
+ const k = (source as { kind?: unknown } | null | undefined)?.kind
105
+ return typeof k === 'string' && k.length > 0 ? k : 'undefined'
106
+ }
107
+
108
+ function nowIso(): string {
109
+ return new Date().toISOString()
110
+ }
111
+
112
+ function emptyState(): HookAuditState {
113
+ return {
114
+ counts: {
115
+ filtered: { subagent: 0, relay: 0, kind: 0 },
116
+ written: { user: 0, assistant: 0, tool: 0 },
117
+ skipped: { sanitized: 0, not_ready: 0, failed: 0 },
118
+ },
119
+ kinds: {},
120
+ last: [],
121
+ updated_at: nowIso(),
122
+ }
123
+ }
124
+
125
+ /** 计数位:只认有限非负整数,其余归零(防手改/坏文件把计数变成 NaN)。 */
126
+ function countOf(v: unknown): number {
127
+ return typeof v === 'number' && Number.isFinite(v) && v >= 0 ? Math.floor(v) : 0
128
+ }
129
+
130
+ /** 摘要只接受完整的非负安全整数桶;坏盘面不伪装成零计数。 */
131
+ function sumCounts(bucket: unknown, keys: readonly string[]): number | null {
132
+ if (!bucket || typeof bucket !== 'object' || Array.isArray(bucket)) return null
133
+ let total = 0
134
+ for (const key of keys) {
135
+ const value = (bucket as Record<string, unknown>)[key]
136
+ if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < 0) return null
137
+ total += value
138
+ if (!Number.isSafeInteger(total)) return null
139
+ }
140
+ return total
141
+ }
142
+
143
+ /** 盘面内容 → 状态:逐字段归并,形态不符的字段一律丢弃(不信任盘面内容)。 */
144
+ function mergeState(raw: unknown): HookAuditState {
145
+ const s = emptyState()
146
+ if (!raw || typeof raw !== 'object') return s
147
+ const r = raw as { counts?: unknown; kinds?: unknown; last?: unknown }
148
+ if (r.counts && typeof r.counts === 'object') {
149
+ const c = r.counts as { filtered?: unknown; written?: unknown; skipped?: unknown }
150
+ const buckets: Array<[Record<string, number>, string[], unknown]> = [
151
+ [s.counts.filtered as Record<string, number>, FILTER_REASONS, c.filtered],
152
+ [s.counts.written as Record<string, number>, WRITE_ROLES, c.written],
153
+ [s.counts.skipped as Record<string, number>, SKIP_REASONS, c.skipped],
154
+ ]
155
+ for (const [dst, keys, src] of buckets) {
156
+ if (!src || typeof src !== 'object') continue
157
+ for (const key of keys) dst[key] = countOf((src as Record<string, unknown>)[key])
158
+ }
159
+ }
160
+ if (r.kinds && typeof r.kinds === 'object') {
161
+ for (const [k, v] of Object.entries(r.kinds as Record<string, unknown>)) {
162
+ if (typeof v === 'number' && Number.isFinite(v) && v > 0) s.kinds[k] = Math.floor(v)
163
+ }
164
+ }
165
+ if (Array.isArray(r.last)) {
166
+ for (const e of r.last) {
167
+ if (!e || typeof e !== 'object') continue
168
+ const entry = e as Partial<HookAuditEntry>
169
+ if (typeof entry.ts !== 'string') continue
170
+ if (entry.action !== 'filtered' && entry.action !== 'written' && entry.action !== 'skipped') continue
171
+ s.last.push(entry as HookAuditEntry)
172
+ }
173
+ if (s.last.length > MAX_LAST) s.last = s.last.slice(-MAX_LAST)
174
+ }
175
+ return s
176
+ }
177
+
178
+ /**
179
+ * 有界落盘审计记录器(**静默降级**:任何公共方法都不会抛错)。
180
+ *
181
+ * 用法(hooks.ts 内):`new HookAuditRecorder(opts.auditPath)`,随后在
182
+ * 三处过滤分支与写入/跳过路径各调一次对应方法。审计失败只影响审计自身。
183
+ */
184
+ export class HookAuditRecorder {
185
+ /** 实际生效的审计文件路径(构造时定死,供日志/测试核对)。 */
186
+ readonly path: string
187
+ /** 进程内状态缓存(首次记录时从盘面载入,此后只增量改内存 + 全量重写)。 */
188
+ #state: HookAuditState | null = null
189
+ /** 本进程持有的锁 token;null 表示当前未持锁。 */
190
+ #lockToken: string | null = null
191
+
192
+ constructor(path?: string) {
193
+ this.path = typeof path === 'string' && path.trim() ? path.trim() : DEFAULT_HOOK_AUDIT_PATH
194
+ }
195
+
196
+ /** #606:收尾时只读最新盘面,返回一行累计计数;缺失/损坏/不可读均静默。
197
+ * written 沿用“成功发起”口径,不能当成成功落库数;不读取 last/kinds 等文本进日志。 */
198
+ summary(): string | null {
199
+ try {
200
+ const raw: unknown = JSON.parse(readFileSync(this.path, 'utf8'))
201
+ if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return null
202
+ const counts: unknown = (raw as { counts?: unknown }).counts
203
+ if (!counts || typeof counts !== 'object' || Array.isArray(counts)) return null
204
+ const buckets = counts as Record<string, unknown>
205
+ const written = sumCounts(buckets.written, WRITE_ROLES)
206
+ const filtered = sumCounts(buckets.filtered, FILTER_REASONS)
207
+ const skipped = sumCounts(buckets.skipped, SKIP_REASONS)
208
+ if (written === null || filtered === null || skipped === null) return null
209
+ return `dsh-memory: 自动记忆审计(累计)written=${written} filtered=${filtered} skipped=${skipped}`
210
+ } catch {
211
+ return null
212
+ }
213
+ }
214
+
215
+ /** 一条**被设计滤除**的消息(三处过滤分支各调一次)。 */
216
+ filtered(reason: HookFilterReason, kind?: string): void {
217
+ this.#mutate((s) => {
218
+ s.counts.filtered[reason] += 1
219
+ s.last.push(kind === undefined
220
+ ? { ts: nowIso(), action: 'filtered', reason }
221
+ : { ts: nowIso(), action: 'filtered', reason, kind })
222
+ })
223
+ }
224
+
225
+ /** `source.kind` 分布(每条**进入消息级处理**的事件调一次,含被滤与放行)。 */
226
+ observeKind(kind: string): void {
227
+ this.#mutate((s) => {
228
+ const key = this.#boundedKindKey(s, kind)
229
+ s.kinds[key] = (s.kinds[key] ?? 0) + 1
230
+ })
231
+ }
232
+
233
+ /** 成功**发起**的写入(按 role;发起后失败另记 skipped.failed)。 */
234
+ written(role: HookWriteRole): void {
235
+ this.#mutate((s) => {
236
+ s.counts.written[role] += 1
237
+ s.last.push({ ts: nowIso(), action: 'written', role })
238
+ })
239
+ }
240
+
241
+ /** 跳过写入(脱敏置空 / 认知图未就绪 / 写入失败)。 */
242
+ skipped(reason: HookSkipReason, role?: HookWriteRole): void {
243
+ this.#mutate((s) => {
244
+ s.counts.skipped[reason] += 1
245
+ s.last.push(role === undefined
246
+ ? { ts: nowIso(), action: 'skipped', reason }
247
+ : { ts: nowIso(), action: 'skipped', reason, role })
248
+ })
249
+ }
250
+
251
+ /** 键数有界:已见键原样用;新键在未达上限时收录,达限后统一归并到 "other"。 */
252
+ #boundedKindKey(s: HookAuditState, kind: string): string {
253
+ if (Object.prototype.hasOwnProperty.call(s.kinds, kind)) return kind
254
+ return Object.keys(s.kinds).length >= MAX_KINDS ? OTHER_KIND : kind
255
+ }
256
+
257
+ /** 读改写 + 原子落盘;整段 try/catch——审计失败静默降级(绝不冒泡进记忆路径)。 */
258
+ #mutate(fn: (s: HookAuditState) => void): void {
259
+ // #563④:审计文件被同用户的多个 DSH 进程共用;此前 #state 只在首次载入、写回整份 rename 覆盖
260
+ // ⇒ 并发时后写者用内存态盖掉他人计数(实测 400→201 / 400→311)。现改为锁内 重读→改→写。
261
+ if (!this.#acquireLock()) return
262
+ try {
263
+ const s = this.#load()
264
+ fn(s)
265
+ if (s.last.length > MAX_LAST) s.last = s.last.slice(-MAX_LAST)
266
+ s.updated_at = nowIso()
267
+ this.#save(s)
268
+ this.#state = s
269
+ } catch { /* 审计失败静默降级:记忆路径必须照常 */ }
270
+ finally { this.#releaseLock() }
271
+ }
272
+
273
+ /** 跨进程排他锁:独占创建 `${path}.lock`;陈旧锁(>5s)清掉;超时返回 false(静默降级)。 */
274
+ #acquireLock(timeoutMs = 800): boolean {
275
+ const lock = `${this.path}.lock`
276
+ const token = `${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`
277
+ const t0 = Date.now()
278
+ for (;;) {
279
+ try {
280
+ closeSync(openSync(lock, 'wx'))
281
+ // #563④补(ABA):把归属 token 写进锁文件,释放时据此判断锁是否仍是自己的。
282
+ // 不加 token 时:A 的锁被 B 判陈旧清掉 → B 建新锁 → A 在 finally 无条件 unlink,
283
+ // 把 B 的锁删掉,互斥窗口重新打开(回到本函数要修的丢计数问题)。
284
+ try { writeFileSync(lock, token) } catch {
285
+ // 写不进归属 token ⇒ 不持有无法验证归属的锁,立即归还(否则 releaseLock 比对失败会漏删)
286
+ try { unlinkSync(lock) } catch { /* 已被他人清理 */ }
287
+ return false
288
+ }
289
+ this.#lockToken = token
290
+ return true
291
+ } catch {
292
+ try { if (Date.now() - statSync(lock).mtimeMs > 5000) unlinkSync(lock) } catch { /* 已释放 */ }
293
+ if (Date.now() - t0 > timeoutMs) return false
294
+ const until = Date.now() + 5
295
+ while (Date.now() < until) { /* 自旋 5ms */ }
296
+ }
297
+ }
298
+ }
299
+
300
+ #releaseLock(): void {
301
+ // #563④补(ABA):只删自己的锁。锁可能已被他人判陈旧清掉并重建——
302
+ // 无条件 unlink 会删掉别人的锁,互斥窗口重新打开。
303
+ const token = this.#lockToken
304
+ this.#lockToken = null
305
+ if (!token) return
306
+ try {
307
+ if (readFileSync(`${this.path}.lock`, 'utf8') !== token) return
308
+ unlinkSync(`${this.path}.lock`)
309
+ } catch { /* 已清理 */ }
310
+ }
311
+
312
+ /** 盘面 → 状态;不存在/不可读/坏 JSON/形态不符 → 空态重建(不抛)。 */
313
+ #load(): HookAuditState {
314
+ try {
315
+ return mergeState(JSON.parse(readFileSync(this.path, 'utf8')) as unknown)
316
+ } catch {
317
+ return emptyState()
318
+ }
319
+ }
320
+
321
+ /** 原子写:同目录临时文件 + rename(临时文件在 rename 失败时清理)。 */
322
+ #save(s: HookAuditState): void {
323
+ const dir = dirname(this.path)
324
+ mkdirSync(dir, { recursive: true })
325
+ const tmp = `${this.path}.${process.pid.toString(36)}.${Date.now().toString(36)}.tmp`
326
+ writeFileSync(tmp, `${JSON.stringify(s, null, 2)}\n`, 'utf8')
327
+ try {
328
+ renameSync(tmp, this.path)
329
+ } catch (err) {
330
+ try { unlinkSync(tmp) } catch { /* 清理失败忽略:残留 .tmp 不影响读路径 */ }
331
+ throw err
332
+ }
333
+ }
334
+ }