@hugesb/dsh-stream-agent 0.0.0-stage → 0.3.2

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 (161) hide show
  1. package/CHANGELOG.md +622 -0
  2. package/CONTRIBUTING.md +72 -0
  3. package/LICENSE +202 -0
  4. package/README.en.md +349 -0
  5. package/README.md +300 -3
  6. package/cordis.patch.yml +77 -0
  7. package/dist/entry/action-gate.js +206 -0
  8. package/dist/entry/adapter-kit.js +192 -0
  9. package/dist/entry/context-render.js +119 -0
  10. package/dist/entry/control-bar-cli.js +289 -0
  11. package/dist/entry/control-bar.js +123 -0
  12. package/dist/entry/control-session.js +115 -0
  13. package/dist/entry/control-state.js +125 -0
  14. package/dist/entry/cordis-compat.js +95 -0
  15. package/dist/entry/eval-probe.js +112 -0
  16. package/dist/entry/intent-log.js +121 -0
  17. package/dist/entry/json-persistence.js +306 -0
  18. package/dist/entry/loop.js +4163 -0
  19. package/dist/entry/mock-provider.js +549 -0
  20. package/dist/entry/obs-broker.js +178 -0
  21. package/dist/entry/ptc-bridge.js +405 -0
  22. package/dist/entry/state-handle.js +217 -0
  23. package/dist/entry/takeover-registry.js +60 -0
  24. package/dist/kernel/control-bar.js +559 -0
  25. package/dist/kernel/final.js +62 -0
  26. package/dist/kernel/gate.js +464 -0
  27. package/dist/kernel/modes.js +253 -0
  28. package/dist/kernel/obs.js +517 -0
  29. package/dist/kernel/parser.js +1081 -0
  30. package/dist/kernel/render.js +466 -0
  31. package/dist/kernel/state.js +416 -0
  32. package/dist/version.js +9 -0
  33. package/docs/TEST-PROPOSITIONS.md +139 -0
  34. package/docs/adr-001-segment-boundary.md +61 -0
  35. package/docs/architecture.md +104 -0
  36. package/docs/desktop-ui-feasibility.md +277 -0
  37. package/docs/disabled-lines-audit.md +53 -0
  38. package/docs/limitations.md +181 -0
  39. package/docs/protocol.md +99 -0
  40. package/docs/v0.4.0-plan.md +50 -0
  41. package/eval/METRICS.md +128 -0
  42. package/eval/RESULTS.md +246 -0
  43. package/eval/tasks/fixtures/big-report.md +298 -0
  44. package/eval/tasks/fixtures/build-manifest.txt +5 -0
  45. package/eval/tasks/fixtures/deploy.yaml +4 -0
  46. package/eval/tasks/fixtures/error.log +200 -0
  47. package/eval/tasks/fixtures/features.yaml +4 -0
  48. package/eval/tasks/fixtures/pipeline.yaml +4 -0
  49. package/eval/tasks/fixtures/sales-q1.csv +61 -0
  50. package/eval/tasks/fixtures/settings.yaml +4 -0
  51. package/eval/tasks/fixtures/users-roster.json +304 -0
  52. package/eval/tasks/fixtures/users-scores.json +20 -0
  53. package/eval/tasks/gen-fixtures.cjs +80 -0
  54. package/eval/tasks/tasks.json +150 -0
  55. package/eval/tools/f6-kill-drill.cjs +176 -0
  56. package/eval/tools/f6-kill-drill.worker.cjs +131 -0
  57. package/eval/tools/gen-results.cjs +191 -0
  58. package/eval/tools/machine-test.cjs +200 -0
  59. package/eval/tools/manual-code-scenarios.md +59 -0
  60. package/eval/tools/replay-check.cjs +311 -0
  61. package/eval/tools/runner.cjs +219 -0
  62. package/eval/tools/session-log.cjs +106 -0
  63. package/eval/tools/summarize.cjs +185 -0
  64. package/eval/tools/t3-cells.cjs +173 -0
  65. package/package.json +73 -6
  66. package/patches/adapters-smoke.yml +41 -0
  67. package/patches/eval-account.yml +36 -0
  68. package/patches/eval-baseline.yml +33 -0
  69. package/patches/eval-stream-code-off.yml +46 -0
  70. package/patches/eval-stream-code-on.yml +47 -0
  71. package/patches/eval-stream.yml +54 -0
  72. package/patches/takeover.yml +42 -0
  73. package/patches/test-preset.yml +23 -0
  74. package/preset/stream/cordis.patch.yml +39 -0
  75. package/preset/stream/package.json +13 -0
  76. package/preset.yml +56 -0
  77. package/profiles/stream/README.md +66 -0
  78. package/profiles/stream/cordis.patch.yml +12 -0
  79. package/profiles/stream/package.json +17 -0
  80. package/profiles/stream-headless/package.json +16 -0
  81. package/scripts/build.mjs +103 -0
  82. package/scripts/check-consistency.mjs +146 -0
  83. package/scripts/gate.mjs +138 -0
  84. package/scripts/install-check.mjs +116 -0
  85. package/scripts/install-cycle.mjs +88 -0
  86. package/scripts/release.mjs +428 -0
  87. package/scripts/repair-session-logs.mjs +498 -0
  88. package/src/entry/action-gate.ts +206 -0
  89. package/src/entry/adapter-kit.ts +192 -0
  90. package/src/entry/context-render.ts +119 -0
  91. package/src/entry/control-bar-cli.ts +289 -0
  92. package/src/entry/control-bar.ts +123 -0
  93. package/src/entry/control-session.ts +115 -0
  94. package/src/entry/control-state.ts +125 -0
  95. package/src/entry/cordis-compat.ts +95 -0
  96. package/src/entry/eval-probe.ts +112 -0
  97. package/src/entry/intent-log.ts +121 -0
  98. package/src/entry/json-persistence.ts +306 -0
  99. package/src/entry/loop.ts +4163 -0
  100. package/src/entry/mock-provider.ts +549 -0
  101. package/src/entry/obs-broker.ts +178 -0
  102. package/src/entry/ptc-bridge.ts +405 -0
  103. package/src/entry/state-handle.ts +217 -0
  104. package/src/entry/takeover-registry.ts +60 -0
  105. package/src/kernel/control-bar.ts +559 -0
  106. package/src/kernel/final.ts +62 -0
  107. package/src/kernel/gate.ts +464 -0
  108. package/src/kernel/modes.ts +253 -0
  109. package/src/kernel/obs.ts +517 -0
  110. package/src/kernel/parser.ts +1081 -0
  111. package/src/kernel/render.ts +466 -0
  112. package/src/kernel/state.ts +416 -0
  113. package/src/version.ts +9 -0
  114. package/test/activation.test.ts +187 -0
  115. package/test/adapters.test.ts +676 -0
  116. package/test/control-bar.test.ts +486 -0
  117. package/test/desktop-ui.test.ts +359 -0
  118. package/test/eval-probe.test.ts +139 -0
  119. package/test/f5-plan.test.ts +221 -0
  120. package/test/f6-intent.test.ts +168 -0
  121. package/test/f7-segment.test.ts +190 -0
  122. package/test/fix-limits.test.ts +599 -0
  123. package/test/gate.test.ts +380 -0
  124. package/test/helpers/stub-loop.ts +240 -0
  125. package/test/host-conformance.test.ts +418 -0
  126. package/test/kernel/obs.test.ts +329 -0
  127. package/test/kernel/parser.test.ts +451 -0
  128. package/test/loop.test.ts +1393 -0
  129. package/test/mock-provider.test.ts +386 -0
  130. package/test/ptc-bridge.test.ts +356 -0
  131. package/test/render.test.ts +418 -0
  132. package/test/s2-install-check.test.ts +46 -0
  133. package/test/scenarios/3-file-basic.json +13 -0
  134. package/test/scenarios/5-file-basic.json +22 -0
  135. package/test/scenarios/burn-more.json +9 -0
  136. package/test/scenarios/degraded-final.json +10 -0
  137. package/test/scenarios/fault-abort-xml.json +11 -0
  138. package/test/scenarios/fault-malformed-command.json +12 -0
  139. package/test/scenarios/fault-midstream-abort.json +11 -0
  140. package/test/scenarios/fault-saturating-output.json +9 -0
  141. package/test/scenarios/fault-timeout.json +9 -0
  142. package/test/scenarios/peek-first.json +11 -0
  143. package/test/scenarios/peek-second.json +11 -0
  144. package/test/scenarios/peek-third.json +10 -0
  145. package/test/scenarios/recover-final.json +10 -0
  146. package/test/scenarios/reroute-first.json +17 -0
  147. package/test/scenarios/reroute-second.json +16 -0
  148. package/test/scenarios/starvation-final.json +10 -0
  149. package/test/scenarios/starvation-promote.json +11 -0
  150. package/test/scenarios/wait-tools-continue.json +10 -0
  151. package/test/scenarios/wait-tools-xml.json +22 -0
  152. package/test/scenarios/wait-tools.json +15 -0
  153. package/test/session-format.test.ts +234 -0
  154. package/test/state.test.ts +335 -0
  155. package/test/stream-v02.test.ts +264 -0
  156. package/test/v031-display.test.ts +333 -0
  157. package/test/v032-conflict.test.ts +191 -0
  158. package/test/v032-truncation.test.ts +291 -0
  159. package/ui/client.js +576 -0
  160. package/ui/index.js +282 -0
  161. package/ui/package.json +26 -0
@@ -0,0 +1,517 @@
1
+ /**
2
+ * kernel/obs.ts —— 观测登记与信息增益分类(M2)
3
+ *
4
+ * 内核层纪律:零框架依赖(不 import 任何 @deepseek-ai/*)、无 IO 副作用、
5
+ * 全部依赖走构造注入(BlobSink 是唯一 IO 出口,默认内存实现)。
6
+ * 本文件不 import 任何模块(连 node:crypto 都不用)——内容寻址(sha256)
7
+ * 归 state.ts 管,这里只需要一个"内容是否变化"的判定哈希(FNV-1a 足够)。
8
+ *
9
+ * info_gain 三档规则表(写死,规则式分类,禁止调用模型):
10
+ * | info_gain | 触发条件 | 处理 |
11
+ * |-----------|-----------------------------------------------|--------------------------|
12
+ * | high | read/grep/glob/web/test/build 的首次输出; | 放行注入(行骨架) |
13
+ * | | 一切执行失败 | |
14
+ * | low | write/append/mkdir(含 bash)的成功回执 | 句柄化,不注入 |
15
+ * | none | 重复观测、内容哈希未变、空输出 | 连句柄目录都不更新,只记 ledger |
16
+ *
17
+ * 计数器口径(对齐 08 号任务书 eval/METRICS.md:injected_ratio = injected / produced):
18
+ * - produced:observe() 收到的每一条观测(含 none);
19
+ * - injected:实际交给装配器进入模型上下文的观测负载条数——
20
+ * high 首次骨架、饥饿升级骨架、tf-peek 取回片段、以及 none 时回灌的
21
+ * "内容未变化"字面量(它同样占请求体积,如实计入);
22
+ * - peeked:peek() 调用次数(peek 的产出同时计入 injected,见上)。
23
+ * 口径若变,只改上报层,不改本文件逻辑。
24
+ */
25
+
26
+ /** 工具族:分类器的输入粒度 */
27
+
28
+       
29
+                      
30
+       
31
+               
32
+ // 未识别工具:默认按 low(默认不回灌)
33
+
34
+
35
+
36
+
37
+      
38
+
39
+             
40
+
41
+                              
42
+
43
+          
44
+
45
+                  
46
+
47
+
48
+
49
+
50
+
51
+               
52
+
53
+
54
+
55
+
56
+                  
57
+
58
+
59
+
60
+ // ---------------------------------------------------------------------------
61
+ // 分类器(纯函数)
62
+ // ---------------------------------------------------------------------------
63
+
64
+ const HIGH_GAIN_FAMILIES = new Set([
65
+ 'read', 'grep', 'glob', 'web', 'test', 'build', 'code',
66
+ ]);
67
+ const LOW_RECEIPT_FAMILIES = new Set([
68
+ 'write', 'append', 'mkdir', 'bash',
69
+ ]);
70
+
71
+ /** 工具名 → 工具族。tf-* 命令名与其同族名一一对应;未知工具归 other。 */
72
+ export function classifyTool(tool ) {
73
+ const t = tool.toLowerCase();
74
+ if (t === 'tf-read' || t === 'read' || t === 'read_file' || t === 'cat') return 'read';
75
+ if (t === 'tf-write' || t === 'write' || t === 'write_file' || t === 'edit' || t === 'tf-edit' || t === 'apply_patch') return 'write';
76
+ if (t === 'tf-peek' || t === 'peek') return 'read';
77
+ if (t === 'tf-bash' || t === 'bash' || t === 'shell') return 'bash';
78
+ if (t === 'tf-code' || t === 'run_code') return 'code';
79
+ if (t === 'tf-append' || t === 'append') return 'append';
80
+ if (t === 'mkdir') return 'mkdir';
81
+ if (t === 'tf-grep' || t === 'grep' || t === 'search' || t === 'grep_search') return 'grep';
82
+ if (t === 'tf-glob' || t === 'glob' || t === 'list' || t === 'ls') return 'glob';
83
+ if (t.startsWith('web') || t === 'fetch' || t === 'http') return 'web';
84
+ if (t === 'test' || t === 'run_tests') return 'test';
85
+ if (t === 'build' || t === 'compile') return 'build';
86
+ return 'other';
87
+ }
88
+
89
+ /**
90
+ * 规则式分类。规则表见文件头注释,顺序即优先级:
91
+ * 失败 > 空输出 > 族别(high 族结合"是否首次/内容是否变化"判定)。
92
+ */
93
+ export function classify(input , ctx ) {
94
+ if (!input.ok) {
95
+ return { info_gain: 'high', reason: 'execution-failure' };
96
+ }
97
+ if (input.content === '') {
98
+ return { info_gain: 'none', reason: 'empty-output' };
99
+ }
100
+ const family = classifyTool(input.tool);
101
+ if (LOW_RECEIPT_FAMILIES.has(family)) {
102
+ return family === 'bash'
103
+ ? { info_gain: 'low', reason: 'successful-exec-receipt' }
104
+ : { info_gain: 'low', reason: 'successful-write-receipt' };
105
+ }
106
+ if (HIGH_GAIN_FAMILIES.has(family)) {
107
+ const hash = hashContent(input.content);
108
+ // 首次(无历史)或内容已变化(新版本)→ high;重复且哈希未变 → none
109
+ if (ctx?.lastHash === undefined) {
110
+ return { info_gain: 'high', reason: `first-observation:${family}` };
111
+ }
112
+ if (ctx.lastHash === hash) {
113
+ return { info_gain: 'none', reason: 'duplicate-observation' };
114
+ }
115
+ return { info_gain: 'high', reason: `content-changed:${family}` };
116
+ }
117
+ // other:未知工具,保守处理为低增益回执(默认不回灌哲学)
118
+ return { info_gain: 'low', reason: 'unknown-tool-receipt' };
119
+ }
120
+
121
+ // ---------------------------------------------------------------------------
122
+ // 行骨架(O1:观测三档返回)
123
+ // ---------------------------------------------------------------------------
124
+
125
+
126
+
127
+
128
+
129
+
130
+
131
+
132
+
133
+
134
+
135
+                  
136
+
137
+
138
+
139
+
140
+ // 关键行匹配规则。同一行命中多类时按 error > class > def > import > heading 取主标签。
141
+ const KEY_LINE_RULES = [
142
+ ['error', /error|fail/i],
143
+ ['class', /^\s*(export\s+)?(abstract\s+)?class\b|\bclass\b/],
144
+ ['def', /^\s*(export\s+)?(async\s+)?function\b|^\s*(pub\s+|pub(?:\(crate\))?\s+)?def\s|^\s*(export\s+)?(const|let|var)\s+\w+\s*=\s*(async\s*)?\(/],
145
+ ['import', /^\s*(import\b|from\s+\S+\s+import\b)|\brequire\s*\(|^\s*#include\b|^\s*using\s+/],
146
+ ['heading', /^#{1,6}\s+/],
147
+ ];
148
+
149
+ function matchKeyLine(line ) {
150
+ for (const [tag, re] of KEY_LINE_RULES) {
151
+ if (re.test(line)) return tag;
152
+ }
153
+ return null;
154
+ }
155
+
156
+ /** 行骨架渲染:信息密度优先于字符截断(O1)。 */
157
+ export function renderSkeleton(text ) {
158
+ const lines = text.split('\n');
159
+ // 去掉末尾因换行产生的空行("a\n" → ['a', ''] 的最后一个空行不计入总行数)
160
+ if (lines.length > 0 && lines[lines.length - 1] === '') lines.pop();
161
+ const nonEmptyRanges = [];
162
+ let start = null;
163
+ for (let i = 0; i < lines.length; i++) {
164
+ if (lines[i].trim() !== '') {
165
+ if (start === null) start = i + 1;
166
+ } else if (start !== null) {
167
+ nonEmptyRanges.push([start, i]);
168
+ start = null;
169
+ }
170
+ }
171
+ if (start !== null) nonEmptyRanges.push([start, lines.length]);
172
+ const keyLines = [];
173
+ for (let i = 0; i < lines.length; i++) {
174
+ const tag = matchKeyLine(lines[i]);
175
+ if (tag !== null) keyLines.push({ line: i + 1, text: lines[i], tag });
176
+ }
177
+ return { totalLines: lines.length, nonEmptyRanges, keyLines };
178
+ }
179
+
180
+ /** 骨架 → 确定性文本(装配器注入用;同一骨架渲染结果逐字节一致)。 */
181
+ export function skeletonToText(s ) {
182
+ const ranges = s.nonEmptyRanges
183
+ .map(([a, b]) => (a === b ? `${a}` : `${a}-${b}`))
184
+ .join(', ');
185
+ const keys = s.keyLines
186
+ .map((k) => ` L${k.line} [${k.tag}] ${k.text}`)
187
+ .join('\n');
188
+ return `[骨架] 共 ${s.totalLines} 行\n非空区间: ${ranges || '(空)'}\n关键行:\n${keys || ' (无)'}`;
189
+ }
190
+
191
+ // ---------------------------------------------------------------------------
192
+ // 句柄目录与差分(O3)
193
+ // ---------------------------------------------------------------------------
194
+
195
+
196
+
197
+
198
+
199
+
200
+
201
+           
202
+
203
+
204
+
205
+
206
+
207
+
208
+
209
+
210
+
211
+
212
+ /** 自 sinceSeq 以来的目录增量(O3:装配器只注入增量,不重注入整段目录)。 */
213
+
214
+
215
+
216
+
217
+
218
+
219
+
220
+
221
+
222
+
223
+
224
+
225
+        
226
+      
227
+
228
+
229
+
230
+
231
+
232
+                    
233
+
234
+
235
+
236
+
237
+
238
+
239
+
240
+
241
+
242
+
243
+ /** none 档回灌的字面量(README O1:返回字面量"内容未变化") */
244
+ export const UNCHANGED_TEXT = '内容未变化' ;
245
+
246
+ /**
247
+ * BlobSink:唯一 IO 出口(红线)。与 state.ts 的 BlobSink 结构兼容——
248
+ * 02 号工作包落地后由适配层(07)把它的实现注入进来;缺省用内存实现。
249
+ */
250
+
251
+
252
+
253
+
254
+ export class InMemoryBlobSink {
255
+ map = new Map ();
256
+ put(ref , content ) {
257
+ this.map.set(ref, content);
258
+ }
259
+ get(ref ) {
260
+ return this.map.get(ref);
261
+ }
262
+ }
263
+
264
+
265
+                                 
266
+
267
+            
268
+
269
+
270
+
271
+
272
+
273
+
274
+
275
+
276
+
277
+
278
+
279
+
280
+
281
+
282
+
283
+
284
+
285
+
286
+
287
+ const DEFAULT_STARVATION_THRESHOLD = 5;
288
+
289
+ /**
290
+ * 观测账本:登记 + 分类 + 骨架 + 目录差分 + 计数器 + 饥饿防线。
291
+ * 每个任务一个实例(reset() 或直接 new)。
292
+ */
293
+ export class ObservationLedger {
294
+ threshold ;
295
+ sink ;
296
+
297
+ seqCounter = 0;
298
+ contentByHandle = new Map ();
299
+ lastHashByKey = new Map ();
300
+ versionByKey = new Map ();
301
+ handleByKey = new Map ();
302
+ dirByKey = new Map ();
303
+ lowRecords = [];
304
+ ledger = [];
305
+
306
+ injectedTotal = 0;
307
+ producedTotal = 0;
308
+ peekedTotal = 0;
309
+ drySteps = 0;
310
+
311
+ constructor(options = {}) {
312
+ const t = options.starvationThreshold ?? DEFAULT_STARVATION_THRESHOLD;
313
+ if (!Number.isInteger(t) || t < 1) {
314
+ throw new RangeError(`starvationThreshold must be an integer >= 1, got ${options.starvationThreshold}`);
315
+ }
316
+ this.threshold = t;
317
+ this.sink = options.sink ?? new InMemoryBlobSink();
318
+ }
319
+
320
+ /** 登记一条工具产出观测,返回三档结果(O1)。 */
321
+ observe(input ) {
322
+ this.producedTotal++;
323
+ const family = classifyTool(input.tool);
324
+ const cls = classify(input, { lastHash: this.lastHashByKey.get(input.key) });
325
+ const seq = ++this.seqCounter;
326
+
327
+ if (cls.info_gain === 'none') {
328
+ // none:连句柄目录都不更新,只记 ledger。回灌字面量计入 injected(占请求体积)。
329
+ this.ledger.push({
330
+ handle: this.handleByKey.get(input.key) ?? '',
331
+ key: input.key,
332
+ family,
333
+ version: this.versionByKey.get(input.key) ?? 0,
334
+ seq,
335
+ info_gain: 'none',
336
+ reason: cls.reason,
337
+ });
338
+ this.injectedTotal++;
339
+ return {
340
+ handle: this.handleByKey.get(input.key) ?? null,
341
+ info_gain: 'none',
342
+ reason: cls.reason,
343
+ seq,
344
+ payload: { kind: 'unchanged', text: UNCHANGED_TEXT },
345
+ };
346
+ }
347
+
348
+ // high / low:新版本入库(内容哈希变化才到这里)
349
+ const version = (this.versionByKey.get(input.key) ?? 0) + 1;
350
+ const callId = input.callId ?? `c${seq}`;
351
+ const handle = `obs:${family}:${callId}@v${version}`;
352
+ const hash = hashContent(input.content);
353
+
354
+ this.contentByHandle.set(handle, input.content);
355
+ this.sink.put(handle, input.content);
356
+ this.versionByKey.set(input.key, version);
357
+ this.lastHashByKey.set(input.key, hash);
358
+ this.handleByKey.set(input.key, handle);
359
+
360
+ const prev = this.dirByKey.get(input.key);
361
+ if (prev) {
362
+ prev.handle = handle;
363
+ prev.version = version;
364
+ prev.lastSeq = seq;
365
+ prev.stale = false;
366
+ } else {
367
+ this.dirByKey.set(input.key, {
368
+ handle, key: input.key, version, firstSeq: seq, lastSeq: seq, stale: false,
369
+ });
370
+ }
371
+
372
+ this.ledger.push({
373
+ handle, key: input.key, family, version, seq,
374
+ info_gain: cls.info_gain, reason: cls.reason,
375
+ });
376
+
377
+ if (cls.info_gain === 'high') {
378
+ const skeleton = renderSkeleton(input.content);
379
+ this.injectedTotal++;
380
+ return {
381
+ handle,
382
+ info_gain: 'high',
383
+ reason: cls.reason,
384
+ seq,
385
+ payload: { kind: 'skeleton', skeleton, rendered: skeletonToText(skeleton) },
386
+ };
387
+ }
388
+
389
+ // low:句柄化,不注入;登记进 lowRecords 供饥饿防线升级
390
+ this.lowRecords.push({ handle, key: input.key, content: input.content, seq });
391
+ return {
392
+ handle,
393
+ info_gain: 'low',
394
+ reason: cls.reason,
395
+ seq,
396
+ payload: { kind: 'receipt', handle, note: '句柄化,不注入' },
397
+ };
398
+ }
399
+
400
+ /**
401
+ * tf-peek:按行段取回句柄内容(O2 内核侧支持)。1-based 闭区间,越界收敛。
402
+ * 未知句柄返回 null(调用方决定如何上报,内核不静默吞)。
403
+ */
404
+ peek(handle , fromLine , toLine ) {
405
+ const content = this.contentByHandle.get(handle);
406
+ if (content === undefined) return null;
407
+ this.peekedTotal++;
408
+ this.injectedTotal++; // peek 产出进入上下文,按口径计入 injected
409
+ const lines = content.split('\n');
410
+ const from = Math.max(1, Math.floor(fromLine));
411
+ const to = Math.min(lines.length, Math.floor(toLine));
412
+ if (from > to) return '';
413
+ return lines.slice(from - 1, to).join('\n');
414
+ }
415
+
416
+ /** 标记句柄失效(如文件被外部删除/覆盖)。返回新 seq 供装配器推进游标;未知 key 返回 null。 */
417
+ markStale(key ) {
418
+ const entry = this.dirByKey.get(key);
419
+ if (!entry) return null;
420
+ entry.stale = true;
421
+ entry.lastSeq = ++this.seqCounter;
422
+ return entry.lastSeq;
423
+ }
424
+
425
+ /** 句柄目录差分(O3):added / changed / stale 三列表,按 seq 升序。 */
426
+ directoryDelta(sinceSeq ) {
427
+ const delta = { added: [], changed: [], stale: [] };
428
+ const entries = [...this.dirByKey.values()].sort((a, b) => a.lastSeq - b.lastSeq);
429
+ for (const e of entries) {
430
+ if (e.lastSeq <= sinceSeq) continue;
431
+ const out = {
432
+ handle: e.handle, key: e.key, version: e.version, seq: e.lastSeq,
433
+ status: e.stale ? 'stale' : e.version === 1 ? 'added' : 'changed',
434
+ };
435
+ if (e.stale) delta.stale.push(out);
436
+ else if (e.version === 1) delta.added.push(out);
437
+ else delta.changed.push(out);
438
+ }
439
+ return delta;
440
+ }
441
+
442
+ /**
443
+ * 饥饿防线(M2 关键防线):每个 step 结束时由 loop 调用。
444
+ * 连续 threshold 步没有任何 high 注入 → 把最近一条 low 观测的骨架
445
+ * 升格注入,防止模型在信息真空中瞎猜。触发后计数清零(再连续 N 步可再次触发)。
446
+ * 无 low 观测可升级时不触发、不清零(继续等待)。
447
+ */
448
+ noteStep(highInjectedThisStep ) {
449
+ if (highInjectedThisStep) {
450
+ this.drySteps = 0;
451
+ return null;
452
+ }
453
+ this.drySteps++;
454
+ if (this.drySteps < this.threshold || this.lowRecords.length === 0) return null;
455
+ this.drySteps = 0;
456
+ const rec = this.lowRecords[this.lowRecords.length - 1];
457
+ const skeleton = renderSkeleton(rec.content);
458
+ this.injectedTotal++;
459
+ return {
460
+ handle: rec.handle,
461
+ info_gain: 'high',
462
+ reason: 'starvation-promotion',
463
+ seq: rec.seq,
464
+ payload: { kind: 'skeleton', skeleton, rendered: skeletonToText(skeleton) },
465
+ };
466
+ }
467
+
468
+ counters() {
469
+ return { injected: this.injectedTotal, produced: this.producedTotal, peeked: this.peekedTotal };
470
+ }
471
+
472
+ /** injected_ratio = injected / produced(08 号 METRICS.md 口径;produced=0 时为 0) */
473
+ injectedRatio() {
474
+ if (this.producedTotal === 0) return 0;
475
+ return this.injectedTotal / this.producedTotal;
476
+ }
477
+
478
+ /** 追加只读的观测流水(审计用,最旧在前) */
479
+ records() {
480
+ return this.ledger;
481
+ }
482
+
483
+ /** 任务结束/新任务开始:清空全部状态(计数器一并清零,口径为"每任务") */
484
+ reset() {
485
+ this.seqCounter = 0;
486
+ this.contentByHandle.clear();
487
+ this.lastHashByKey.clear();
488
+ this.versionByKey.clear();
489
+ this.handleByKey.clear();
490
+ this.dirByKey.clear();
491
+ this.lowRecords.length = 0;
492
+ this.ledger.length = 0;
493
+ this.injectedTotal = 0;
494
+ this.producedTotal = 0;
495
+ this.peekedTotal = 0;
496
+ this.drySteps = 0;
497
+ }
498
+ }
499
+
500
+ // ---------------------------------------------------------------------------
501
+ // 内部工具
502
+ // ---------------------------------------------------------------------------
503
+
504
+ /**
505
+ * FNV-1a 64bit,仅用于"内容是否变化"判定(碰撞概率对去重场景足够)。
506
+ * 不做内容寻址——那归 state.ts 的 sha256。
507
+ */
508
+ function hashContent(s ) {
509
+ let h = 0xcbf29ce484222325n;
510
+ const prime = 0x100000001b3n;
511
+ const mask = 0xffffffffffffffffn;
512
+ for (let i = 0; i < s.length; i++) {
513
+ h ^= BigInt(s.charCodeAt(i));
514
+ h = (h * prime) & mask;
515
+ }
516
+ return h.toString(16).padStart(16, '0');
517
+ }