@hugesb/dsh-stream-agent 0.0.0-stage → 0.3.1
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/CHANGELOG.md +497 -0
- package/CONTRIBUTING.md +72 -0
- package/LICENSE +202 -0
- package/README.en.md +349 -0
- package/README.md +300 -3
- package/cordis.patch.yml +77 -0
- package/dist/entry/action-gate.js +206 -0
- package/dist/entry/adapter-kit.js +192 -0
- package/dist/entry/context-render.js +119 -0
- package/dist/entry/control-bar-cli.js +289 -0
- package/dist/entry/control-bar.js +123 -0
- package/dist/entry/control-session.js +115 -0
- package/dist/entry/control-state.js +125 -0
- package/dist/entry/cordis-compat.js +95 -0
- package/dist/entry/eval-probe.js +112 -0
- package/dist/entry/intent-log.js +121 -0
- package/dist/entry/json-persistence.js +306 -0
- package/dist/entry/loop.js +3852 -0
- package/dist/entry/mock-provider.js +536 -0
- package/dist/entry/obs-broker.js +178 -0
- package/dist/entry/ptc-bridge.js +405 -0
- package/dist/entry/state-handle.js +217 -0
- package/dist/entry/takeover-registry.js +60 -0
- package/dist/kernel/control-bar.js +559 -0
- package/dist/kernel/final.js +62 -0
- package/dist/kernel/gate.js +464 -0
- package/dist/kernel/modes.js +253 -0
- package/dist/kernel/obs.js +517 -0
- package/dist/kernel/parser.js +632 -0
- package/dist/kernel/render.js +444 -0
- package/dist/kernel/state.js +416 -0
- package/dist/version.js +9 -0
- package/docs/TEST-PROPOSITIONS.md +139 -0
- package/docs/adr-001-segment-boundary.md +61 -0
- package/docs/architecture.md +104 -0
- package/docs/desktop-ui-feasibility.md +277 -0
- package/docs/disabled-lines-audit.md +53 -0
- package/docs/limitations.md +181 -0
- package/docs/protocol.md +99 -0
- package/docs/v0.4.0-plan.md +50 -0
- package/eval/METRICS.md +128 -0
- package/eval/RESULTS.md +246 -0
- package/eval/tasks/fixtures/big-report.md +298 -0
- package/eval/tasks/fixtures/build-manifest.txt +5 -0
- package/eval/tasks/fixtures/deploy.yaml +4 -0
- package/eval/tasks/fixtures/error.log +200 -0
- package/eval/tasks/fixtures/features.yaml +4 -0
- package/eval/tasks/fixtures/pipeline.yaml +4 -0
- package/eval/tasks/fixtures/sales-q1.csv +61 -0
- package/eval/tasks/fixtures/settings.yaml +4 -0
- package/eval/tasks/fixtures/users-roster.json +304 -0
- package/eval/tasks/fixtures/users-scores.json +20 -0
- package/eval/tasks/gen-fixtures.cjs +80 -0
- package/eval/tasks/tasks.json +150 -0
- package/eval/tools/f6-kill-drill.cjs +176 -0
- package/eval/tools/f6-kill-drill.worker.cjs +131 -0
- package/eval/tools/gen-results.cjs +191 -0
- package/eval/tools/machine-test.cjs +200 -0
- package/eval/tools/manual-code-scenarios.md +59 -0
- package/eval/tools/replay-check.cjs +311 -0
- package/eval/tools/runner.cjs +219 -0
- package/eval/tools/session-log.cjs +106 -0
- package/eval/tools/summarize.cjs +185 -0
- package/eval/tools/t3-cells.cjs +173 -0
- package/package.json +73 -6
- package/patches/adapters-smoke.yml +41 -0
- package/patches/eval-account.yml +36 -0
- package/patches/eval-baseline.yml +33 -0
- package/patches/eval-stream-code-off.yml +46 -0
- package/patches/eval-stream-code-on.yml +47 -0
- package/patches/eval-stream.yml +54 -0
- package/patches/takeover.yml +42 -0
- package/patches/test-preset.yml +23 -0
- package/preset/stream/cordis.patch.yml +39 -0
- package/preset/stream/package.json +13 -0
- package/preset.yml +56 -0
- package/profiles/stream/README.md +66 -0
- package/profiles/stream/cordis.patch.yml +12 -0
- package/profiles/stream/package.json +17 -0
- package/profiles/stream-headless/package.json +16 -0
- package/scripts/build.mjs +103 -0
- package/scripts/check-consistency.mjs +146 -0
- package/scripts/gate.mjs +138 -0
- package/scripts/install-check.mjs +116 -0
- package/scripts/install-cycle.mjs +88 -0
- package/scripts/release.mjs +415 -0
- package/scripts/repair-session-logs.mjs +403 -0
- package/src/entry/action-gate.ts +206 -0
- package/src/entry/adapter-kit.ts +192 -0
- package/src/entry/context-render.ts +119 -0
- package/src/entry/control-bar-cli.ts +289 -0
- package/src/entry/control-bar.ts +123 -0
- package/src/entry/control-session.ts +115 -0
- package/src/entry/control-state.ts +125 -0
- package/src/entry/cordis-compat.ts +95 -0
- package/src/entry/eval-probe.ts +112 -0
- package/src/entry/intent-log.ts +121 -0
- package/src/entry/json-persistence.ts +306 -0
- package/src/entry/loop.ts +3852 -0
- package/src/entry/mock-provider.ts +536 -0
- package/src/entry/obs-broker.ts +178 -0
- package/src/entry/ptc-bridge.ts +405 -0
- package/src/entry/state-handle.ts +217 -0
- package/src/entry/takeover-registry.ts +60 -0
- package/src/kernel/control-bar.ts +559 -0
- package/src/kernel/final.ts +62 -0
- package/src/kernel/gate.ts +464 -0
- package/src/kernel/modes.ts +253 -0
- package/src/kernel/obs.ts +517 -0
- package/src/kernel/parser.ts +632 -0
- package/src/kernel/render.ts +444 -0
- package/src/kernel/state.ts +416 -0
- package/src/version.ts +9 -0
- package/test/activation.test.ts +187 -0
- package/test/adapters.test.ts +676 -0
- package/test/control-bar.test.ts +486 -0
- package/test/desktop-ui.test.ts +359 -0
- package/test/eval-probe.test.ts +139 -0
- package/test/f5-plan.test.ts +221 -0
- package/test/f6-intent.test.ts +168 -0
- package/test/f7-segment.test.ts +190 -0
- package/test/fix-limits.test.ts +599 -0
- package/test/gate.test.ts +380 -0
- package/test/helpers/stub-loop.ts +240 -0
- package/test/kernel/obs.test.ts +329 -0
- package/test/kernel/parser.test.ts +450 -0
- package/test/loop.test.ts +1393 -0
- package/test/mock-provider.test.ts +386 -0
- package/test/ptc-bridge.test.ts +356 -0
- package/test/render.test.ts +418 -0
- package/test/s2-install-check.test.ts +46 -0
- package/test/scenarios/3-file-basic.json +13 -0
- package/test/scenarios/5-file-basic.json +22 -0
- package/test/scenarios/burn-more.json +9 -0
- package/test/scenarios/degraded-final.json +10 -0
- package/test/scenarios/fault-abort-xml.json +11 -0
- package/test/scenarios/fault-malformed-command.json +12 -0
- package/test/scenarios/fault-midstream-abort.json +11 -0
- package/test/scenarios/fault-saturating-output.json +9 -0
- package/test/scenarios/fault-timeout.json +9 -0
- package/test/scenarios/peek-first.json +11 -0
- package/test/scenarios/peek-second.json +11 -0
- package/test/scenarios/peek-third.json +10 -0
- package/test/scenarios/recover-final.json +10 -0
- package/test/scenarios/reroute-first.json +17 -0
- package/test/scenarios/reroute-second.json +16 -0
- package/test/scenarios/starvation-final.json +10 -0
- package/test/scenarios/starvation-promote.json +11 -0
- package/test/scenarios/wait-tools-continue.json +10 -0
- package/test/scenarios/wait-tools-xml.json +22 -0
- package/test/scenarios/wait-tools.json +15 -0
- package/test/session-format.test.ts +234 -0
- package/test/state.test.ts +335 -0
- package/test/stream-v02.test.ts +264 -0
- package/test/v031-display.test.ts +333 -0
- package/ui/client.js +576 -0
- package/ui/index.js +282 -0
- 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
|
+
export type ToolFamily =
|
|
28
|
+
| 'read' | 'grep' | 'glob' | 'web' | 'test' | 'build' // 高增益候选族
|
|
29
|
+
| 'code' // tf-code 程序化结果(高增益:首个/变化结果注骨架)
|
|
30
|
+
| 'write' | 'append' | 'mkdir' // 低增益回执族
|
|
31
|
+
| 'bash' // 成功记 ledger、失败注入(README §5)
|
|
32
|
+
| 'other'; // 未识别工具:默认按 low(默认不回灌)
|
|
33
|
+
|
|
34
|
+
export type InfoGain = 'high' | 'low' | 'none';
|
|
35
|
+
|
|
36
|
+
export interface ObservationInput {
|
|
37
|
+
/** 工具名,如 'tf-read' / 'tf-write' / 'tf-bash' / 'grep' */
|
|
38
|
+
tool: string;
|
|
39
|
+
/** 执行是否成功(false 一律 high) */
|
|
40
|
+
ok: boolean;
|
|
41
|
+
/** 观测对象标识(文件路径 / URL / 命令签名),同一 key 的重复观测被识别 */
|
|
42
|
+
key: string;
|
|
43
|
+
/** 本次产出的观测原文 */
|
|
44
|
+
content: string;
|
|
45
|
+
/** 调用标识(缺省自动生成),进入句柄 obs:<family>:<callId>@v<n> */
|
|
46
|
+
callId?: string;
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
export interface Classification {
|
|
50
|
+
info_gain: InfoGain;
|
|
51
|
+
/** 机器可读的触发原因,供 ledger 审计 */
|
|
52
|
+
reason: string;
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
export interface ClassificationContext {
|
|
56
|
+
/** 该 key 上一次观测的内容哈希;无历史为 undefined */
|
|
57
|
+
lastHash?: string;
|
|
58
|
+
}
|
|
59
|
+
|
|
60
|
+
// ---------------------------------------------------------------------------
|
|
61
|
+
// 分类器(纯函数)
|
|
62
|
+
// ---------------------------------------------------------------------------
|
|
63
|
+
|
|
64
|
+
const HIGH_GAIN_FAMILIES: ReadonlySet<ToolFamily> = new Set([
|
|
65
|
+
'read', 'grep', 'glob', 'web', 'test', 'build', 'code',
|
|
66
|
+
]);
|
|
67
|
+
const LOW_RECEIPT_FAMILIES: ReadonlySet<ToolFamily> = new Set([
|
|
68
|
+
'write', 'append', 'mkdir', 'bash',
|
|
69
|
+
]);
|
|
70
|
+
|
|
71
|
+
/** 工具名 → 工具族。tf-* 命令名与其同族名一一对应;未知工具归 other。 */
|
|
72
|
+
export function classifyTool(tool: string): ToolFamily {
|
|
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: ObservationInput, ctx?: ClassificationContext): Classification {
|
|
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
|
+
export type KeyLineTag = 'error' | 'class' | 'def' | 'import' | 'heading';
|
|
126
|
+
|
|
127
|
+
export interface KeyLine {
|
|
128
|
+
line: number;
|
|
129
|
+
text: string;
|
|
130
|
+
tag: KeyLineTag;
|
|
131
|
+
}
|
|
132
|
+
|
|
133
|
+
export interface LineSkeleton {
|
|
134
|
+
totalLines: number;
|
|
135
|
+
/** 非空行区间,1-based 闭区间,已合并相邻行 */
|
|
136
|
+
nonEmptyRanges: ReadonlyArray<readonly [number, number]>;
|
|
137
|
+
keyLines: ReadonlyArray<KeyLine>;
|
|
138
|
+
}
|
|
139
|
+
|
|
140
|
+
// 关键行匹配规则。同一行命中多类时按 error > class > def > import > heading 取主标签。
|
|
141
|
+
const KEY_LINE_RULES: ReadonlyArray<readonly [KeyLineTag, RegExp]> = [
|
|
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: string): KeyLineTag | null {
|
|
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: string): LineSkeleton {
|
|
158
|
+
const lines = text.split('\n');
|
|
159
|
+
// 去掉末尾因换行产生的空行("a\n" → ['a', ''] 的最后一个空行不计入总行数)
|
|
160
|
+
if (lines.length > 0 && lines[lines.length - 1] === '') lines.pop();
|
|
161
|
+
const nonEmptyRanges: Array<[number, number]> = [];
|
|
162
|
+
let start: number | null = 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: KeyLine[] = [];
|
|
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: LineSkeleton): string {
|
|
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
|
+
export type DirStatus = 'added' | 'changed' | 'stale';
|
|
196
|
+
|
|
197
|
+
export interface HandleEntry {
|
|
198
|
+
handle: string;
|
|
199
|
+
key: string;
|
|
200
|
+
version: number;
|
|
201
|
+
/** 目录序号:directoryDelta(sinceSeq) 以此过滤 */
|
|
202
|
+
seq: number;
|
|
203
|
+
status: DirStatus;
|
|
204
|
+
}
|
|
205
|
+
|
|
206
|
+
export interface DirectoryDelta {
|
|
207
|
+
added: HandleEntry[];
|
|
208
|
+
changed: HandleEntry[];
|
|
209
|
+
stale: HandleEntry[];
|
|
210
|
+
}
|
|
211
|
+
|
|
212
|
+
/** 自 sinceSeq 以来的目录增量(O3:装配器只注入增量,不重注入整段目录)。 */
|
|
213
|
+
export interface ObservationRecord {
|
|
214
|
+
handle: string;
|
|
215
|
+
key: string;
|
|
216
|
+
family: ToolFamily;
|
|
217
|
+
version: number;
|
|
218
|
+
seq: number;
|
|
219
|
+
info_gain: InfoGain;
|
|
220
|
+
reason: string;
|
|
221
|
+
}
|
|
222
|
+
|
|
223
|
+
export type ObservationPayload =
|
|
224
|
+
| { kind: 'skeleton'; skeleton: LineSkeleton; rendered: string }
|
|
225
|
+
| { kind: 'receipt'; handle: string; note: '句柄化,不注入' }
|
|
226
|
+
| { kind: 'unchanged'; text: '内容未变化' };
|
|
227
|
+
|
|
228
|
+
export interface ObservationResult {
|
|
229
|
+
handle: string | null;
|
|
230
|
+
info_gain: InfoGain;
|
|
231
|
+
reason: string;
|
|
232
|
+
/** 本条观测的流水序号(装配器做 directoryDelta(sinceSeq) 的游标) */
|
|
233
|
+
seq: number;
|
|
234
|
+
payload: ObservationPayload;
|
|
235
|
+
}
|
|
236
|
+
|
|
237
|
+
export interface ObsCounters {
|
|
238
|
+
injected: number;
|
|
239
|
+
produced: number;
|
|
240
|
+
peeked: number;
|
|
241
|
+
}
|
|
242
|
+
|
|
243
|
+
/** none 档回灌的字面量(README O1:返回字面量"内容未变化") */
|
|
244
|
+
export const UNCHANGED_TEXT = '内容未变化' as const;
|
|
245
|
+
|
|
246
|
+
/**
|
|
247
|
+
* BlobSink:唯一 IO 出口(红线)。与 state.ts 的 BlobSink 结构兼容——
|
|
248
|
+
* 02 号工作包落地后由适配层(07)把它的实现注入进来;缺省用内存实现。
|
|
249
|
+
*/
|
|
250
|
+
export interface BlobSink {
|
|
251
|
+
put(ref: string, content: string): void;
|
|
252
|
+
}
|
|
253
|
+
|
|
254
|
+
export class InMemoryBlobSink implements BlobSink {
|
|
255
|
+
private map = new Map<string, string>();
|
|
256
|
+
put(ref: string, content: string): void {
|
|
257
|
+
this.map.set(ref, content);
|
|
258
|
+
}
|
|
259
|
+
get(ref: string): string | undefined {
|
|
260
|
+
return this.map.get(ref);
|
|
261
|
+
}
|
|
262
|
+
}
|
|
263
|
+
|
|
264
|
+
export interface ObsKernelOptions {
|
|
265
|
+
/** 饥饿防线阈值:连续 N 步无 high 注入时升级注入最近一条 low 观测(默认 5) */
|
|
266
|
+
starvationThreshold?: number;
|
|
267
|
+
/** blob 出口注入;缺省内存实现 */
|
|
268
|
+
sink?: BlobSink;
|
|
269
|
+
}
|
|
270
|
+
|
|
271
|
+
interface DirEntryInternal {
|
|
272
|
+
handle: string;
|
|
273
|
+
key: string;
|
|
274
|
+
version: number;
|
|
275
|
+
firstSeq: number;
|
|
276
|
+
lastSeq: number;
|
|
277
|
+
stale: boolean;
|
|
278
|
+
}
|
|
279
|
+
|
|
280
|
+
interface LowRecord {
|
|
281
|
+
handle: string;
|
|
282
|
+
key: string;
|
|
283
|
+
content: string;
|
|
284
|
+
seq: number;
|
|
285
|
+
}
|
|
286
|
+
|
|
287
|
+
const DEFAULT_STARVATION_THRESHOLD = 5;
|
|
288
|
+
|
|
289
|
+
/**
|
|
290
|
+
* 观测账本:登记 + 分类 + 骨架 + 目录差分 + 计数器 + 饥饿防线。
|
|
291
|
+
* 每个任务一个实例(reset() 或直接 new)。
|
|
292
|
+
*/
|
|
293
|
+
export class ObservationLedger {
|
|
294
|
+
private readonly threshold: number;
|
|
295
|
+
private readonly sink: BlobSink;
|
|
296
|
+
|
|
297
|
+
private seqCounter = 0;
|
|
298
|
+
private readonly contentByHandle = new Map<string, string>();
|
|
299
|
+
private readonly lastHashByKey = new Map<string, string>();
|
|
300
|
+
private readonly versionByKey = new Map<string, number>();
|
|
301
|
+
private readonly handleByKey = new Map<string, string>();
|
|
302
|
+
private readonly dirByKey = new Map<string, DirEntryInternal>();
|
|
303
|
+
private readonly lowRecords: LowRecord[] = [];
|
|
304
|
+
private readonly ledger: ObservationRecord[] = [];
|
|
305
|
+
|
|
306
|
+
private injectedTotal = 0;
|
|
307
|
+
private producedTotal = 0;
|
|
308
|
+
private peekedTotal = 0;
|
|
309
|
+
private drySteps = 0;
|
|
310
|
+
|
|
311
|
+
constructor(options: ObsKernelOptions = {}) {
|
|
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: ObservationInput): ObservationResult {
|
|
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: string, fromLine: number, toLine: number): string | null {
|
|
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: string): number | null {
|
|
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: number): DirectoryDelta {
|
|
427
|
+
const delta: DirectoryDelta = { 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: HandleEntry = {
|
|
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: boolean): ObservationResult | null {
|
|
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(): ObsCounters {
|
|
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(): number {
|
|
474
|
+
if (this.producedTotal === 0) return 0;
|
|
475
|
+
return this.injectedTotal / this.producedTotal;
|
|
476
|
+
}
|
|
477
|
+
|
|
478
|
+
/** 追加只读的观测流水(审计用,最旧在前) */
|
|
479
|
+
records(): readonly ObservationRecord[] {
|
|
480
|
+
return this.ledger;
|
|
481
|
+
}
|
|
482
|
+
|
|
483
|
+
/** 任务结束/新任务开始:清空全部状态(计数器一并清零,口径为"每任务") */
|
|
484
|
+
reset(): void {
|
|
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: string): string {
|
|
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
|
+
}
|