@furongjun1999/dsh-memory 0.9.7 → 0.9.8
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/README.md +150 -662
- package/codebuddy/CODEBUDDY.md +333 -204
- package/docs/README.md +18 -0
- package/docs/discipline/harnesses.yaml +11 -3
- package/docs/discipline/templates/compact.txt.tmpl +20 -18
- package/docs/discipline/templates/full.md.tmpl +63 -61
- package/docs/discipline/templates/rules.mdc.tmpl +5 -3
- package/docs/discipline/templates/skill.md.tmpl +25 -23
- package/docs/discipline/templates/spec.txt.tmpl +1 -1
- package/docs/discipline/templates/zcode-user.md.tmpl +1 -1
- package/lib/hooks.js +1 -1
- package/lib/index.js +9 -3
- package/lib/init.js +19 -4
- package/lib/lib/hook_audit.js +26 -0
- package/md_cg/sustain.py +10 -1
- package/md_cg/test_heartbeat_ledger.py +563 -557
- package/md_cg/test_n184_keys_concurrent_provision.py +1 -1
- package/md_cg/test_read_scope_b27.py +2 -2
- package/md_cg/test_security_audit_v21.py +249 -249
- package/md_cg/test_sustain_bad_stamp.py +178 -0
- package/package.json +1 -1
- package/src/hooks.ts +932 -932
- package/src/index.ts +18 -12
- package/src/init.ts +16 -4
- package/src/lib/hook_audit.ts +302 -282
- package/zcode/AGENTS.md +333 -204
package/src/lib/hook_audit.ts
CHANGED
|
@@ -1,282 +1,302 @@
|
|
|
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
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
s
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
const
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
} catch
|
|
278
|
-
|
|
279
|
-
|
|
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 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
|
+
/** 本进程持有的锁 token;null 表示当前未持锁。 */
|
|
177
|
+
#lockToken: string | null = null
|
|
178
|
+
|
|
179
|
+
constructor(path?: string) {
|
|
180
|
+
this.path = typeof path === 'string' && path.trim() ? path.trim() : DEFAULT_HOOK_AUDIT_PATH
|
|
181
|
+
}
|
|
182
|
+
|
|
183
|
+
/** 一条**被设计滤除**的消息(三处过滤分支各调一次)。 */
|
|
184
|
+
filtered(reason: HookFilterReason, kind?: string): void {
|
|
185
|
+
this.#mutate((s) => {
|
|
186
|
+
s.counts.filtered[reason] += 1
|
|
187
|
+
s.last.push(kind === undefined
|
|
188
|
+
? { ts: nowIso(), action: 'filtered', reason }
|
|
189
|
+
: { ts: nowIso(), action: 'filtered', reason, kind })
|
|
190
|
+
})
|
|
191
|
+
}
|
|
192
|
+
|
|
193
|
+
/** `source.kind` 分布(每条**进入消息级处理**的事件调一次,含被滤与放行)。 */
|
|
194
|
+
observeKind(kind: string): void {
|
|
195
|
+
this.#mutate((s) => {
|
|
196
|
+
const key = this.#boundedKindKey(s, kind)
|
|
197
|
+
s.kinds[key] = (s.kinds[key] ?? 0) + 1
|
|
198
|
+
})
|
|
199
|
+
}
|
|
200
|
+
|
|
201
|
+
/** 成功**发起**的写入(按 role;发起后失败另记 skipped.failed)。 */
|
|
202
|
+
written(role: HookWriteRole): void {
|
|
203
|
+
this.#mutate((s) => {
|
|
204
|
+
s.counts.written[role] += 1
|
|
205
|
+
s.last.push({ ts: nowIso(), action: 'written', role })
|
|
206
|
+
})
|
|
207
|
+
}
|
|
208
|
+
|
|
209
|
+
/** 跳过写入(脱敏置空 / 认知图未就绪 / 写入失败)。 */
|
|
210
|
+
skipped(reason: HookSkipReason, role?: HookWriteRole): void {
|
|
211
|
+
this.#mutate((s) => {
|
|
212
|
+
s.counts.skipped[reason] += 1
|
|
213
|
+
s.last.push(role === undefined
|
|
214
|
+
? { ts: nowIso(), action: 'skipped', reason }
|
|
215
|
+
: { ts: nowIso(), action: 'skipped', reason, role })
|
|
216
|
+
})
|
|
217
|
+
}
|
|
218
|
+
|
|
219
|
+
/** 键数有界:已见键原样用;新键在未达上限时收录,达限后统一归并到 "other"。 */
|
|
220
|
+
#boundedKindKey(s: HookAuditState, kind: string): string {
|
|
221
|
+
if (Object.prototype.hasOwnProperty.call(s.kinds, kind)) return kind
|
|
222
|
+
return Object.keys(s.kinds).length >= MAX_KINDS ? OTHER_KIND : kind
|
|
223
|
+
}
|
|
224
|
+
|
|
225
|
+
/** 读改写 + 原子落盘;整段 try/catch——审计失败静默降级(绝不冒泡进记忆路径)。 */
|
|
226
|
+
#mutate(fn: (s: HookAuditState) => void): void {
|
|
227
|
+
// #563④:审计文件被同用户的多个 DSH 进程共用;此前 #state 只在首次载入、写回整份 rename 覆盖
|
|
228
|
+
// ⇒ 并发时后写者用内存态盖掉他人计数(实测 400→201 / 400→311)。现改为锁内 重读→改→写。
|
|
229
|
+
if (!this.#acquireLock()) return
|
|
230
|
+
try {
|
|
231
|
+
const s = this.#load()
|
|
232
|
+
fn(s)
|
|
233
|
+
if (s.last.length > MAX_LAST) s.last = s.last.slice(-MAX_LAST)
|
|
234
|
+
s.updated_at = nowIso()
|
|
235
|
+
this.#save(s)
|
|
236
|
+
this.#state = s
|
|
237
|
+
} catch { /* 审计失败静默降级:记忆路径必须照常 */ }
|
|
238
|
+
finally { this.#releaseLock() }
|
|
239
|
+
}
|
|
240
|
+
|
|
241
|
+
/** 跨进程排他锁:独占创建 `${path}.lock`;陈旧锁(>5s)清掉;超时返回 false(静默降级)。 */
|
|
242
|
+
#acquireLock(timeoutMs = 800): boolean {
|
|
243
|
+
const lock = `${this.path}.lock`
|
|
244
|
+
const token = `${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`
|
|
245
|
+
const t0 = Date.now()
|
|
246
|
+
for (;;) {
|
|
247
|
+
try {
|
|
248
|
+
closeSync(openSync(lock, 'wx'))
|
|
249
|
+
// #563④补(ABA):把归属 token 写进锁文件,释放时据此判断锁是否仍是自己的。
|
|
250
|
+
// 不加 token 时:A 的锁被 B 判陈旧清掉 → B 建新锁 → A 在 finally 无条件 unlink,
|
|
251
|
+
// 把 B 的锁删掉,互斥窗口重新打开(回到本函数要修的丢计数问题)。
|
|
252
|
+
try { writeFileSync(lock, token) } catch {
|
|
253
|
+
// 写不进归属 token ⇒ 不持有无法验证归属的锁,立即归还(否则 releaseLock 比对失败会漏删)
|
|
254
|
+
try { unlinkSync(lock) } catch { /* 已被他人清理 */ }
|
|
255
|
+
return false
|
|
256
|
+
}
|
|
257
|
+
this.#lockToken = token
|
|
258
|
+
return true
|
|
259
|
+
} catch {
|
|
260
|
+
try { if (Date.now() - statSync(lock).mtimeMs > 5000) unlinkSync(lock) } catch { /* 已释放 */ }
|
|
261
|
+
if (Date.now() - t0 > timeoutMs) return false
|
|
262
|
+
const until = Date.now() + 5
|
|
263
|
+
while (Date.now() < until) { /* 自旋 5ms */ }
|
|
264
|
+
}
|
|
265
|
+
}
|
|
266
|
+
}
|
|
267
|
+
|
|
268
|
+
#releaseLock(): void {
|
|
269
|
+
// #563④补(ABA):只删自己的锁。锁可能已被他人判陈旧清掉并重建——
|
|
270
|
+
// 无条件 unlink 会删掉别人的锁,互斥窗口重新打开。
|
|
271
|
+
const token = this.#lockToken
|
|
272
|
+
this.#lockToken = null
|
|
273
|
+
if (!token) return
|
|
274
|
+
try {
|
|
275
|
+
if (readFileSync(`${this.path}.lock`, 'utf8') !== token) return
|
|
276
|
+
unlinkSync(`${this.path}.lock`)
|
|
277
|
+
} catch { /* 已清理 */ }
|
|
278
|
+
}
|
|
279
|
+
|
|
280
|
+
/** 盘面 → 状态;不存在/不可读/坏 JSON/形态不符 → 空态重建(不抛)。 */
|
|
281
|
+
#load(): HookAuditState {
|
|
282
|
+
try {
|
|
283
|
+
return mergeState(JSON.parse(readFileSync(this.path, 'utf8')) as unknown)
|
|
284
|
+
} catch {
|
|
285
|
+
return emptyState()
|
|
286
|
+
}
|
|
287
|
+
}
|
|
288
|
+
|
|
289
|
+
/** 原子写:同目录临时文件 + rename(临时文件在 rename 失败时清理)。 */
|
|
290
|
+
#save(s: HookAuditState): void {
|
|
291
|
+
const dir = dirname(this.path)
|
|
292
|
+
mkdirSync(dir, { recursive: true })
|
|
293
|
+
const tmp = `${this.path}.${process.pid.toString(36)}.${Date.now().toString(36)}.tmp`
|
|
294
|
+
writeFileSync(tmp, `${JSON.stringify(s, null, 2)}\n`, 'utf8')
|
|
295
|
+
try {
|
|
296
|
+
renameSync(tmp, this.path)
|
|
297
|
+
} catch (err) {
|
|
298
|
+
try { unlinkSync(tmp) } catch { /* 清理失败忽略:残留 .tmp 不影响读路径 */ }
|
|
299
|
+
throw err
|
|
300
|
+
}
|
|
301
|
+
}
|
|
302
|
+
}
|