@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,1081 @@
1
+ /**
2
+ * kernel/parser.ts —— tf-* 单流协议解析器(M3 解析半边)
3
+ *
4
+ * 内核层纪律:零框架依赖、无 IO 副作用、不执行任何东西,只解析。
5
+ *
6
+ * 协议文本格式(README §5 的语义在此落成 wire format,写进系统提示):
7
+ *
8
+ * <tf-read path="src/app.ts" id="r1" depends_on="w1,w2"/>
9
+ * <tf-write path="src/app.ts" id="w1" depends_on="r1">
10
+ * 文件正文(原文,直到闭合标签)
11
+ * </tf-write>
12
+ * <tf-edit path="src/app.ts" id="e1">
13
+ * <<<<<<< OLD
14
+ * 被替换的原文(精确字面量,必须唯一)
15
+ * =======
16
+ * >>>>>>> NEW
17
+ * 替换后的新文
18
+ * </tf-edit>
19
+ * <tf-append path="notes.md" id="a1" anchor="最后一节"/>
20
+ * 追加正文(原文,直到闭合标签)
21
+ * </tf-append>
22
+ * <tf-grep pattern="TODO" path="src" include="*.ts" id="g1"/>
23
+ * <tf-glob pattern="src/**" id="gl1"/>
24
+ * <tf-bash cmd="npm test" id="b1"/>
25
+ * <tf-peek handle="obs:read:c3@v1" from_line="10" to_line="20" id="p1"/>
26
+ * <tf-final id="f1" summary="任务完成说明"/>
27
+ *
28
+ * 规则:
29
+ * - 有正文的命令:tf-write / tf-edit / tf-append / tf-code;其余自闭合(`/>`)
30
+ * 或空元素配对(`></...>`);非 body 命令带非空正文 → malformed;
31
+ * - 属性值用双引号,值内可含 `>`(如 shell 重定向)——头部扫描引号感知;
32
+ * - id 可省略(自动编号 cmd1、cmd2...);depends_on 是逗号分隔的命令 id
33
+ * 列表,可空;重复依赖去重保序;
34
+ * - `<tf-` 开头但命令名未知的标签按 malformed 上报(协议尝试失败,不静默);
35
+ * 非 tf- 前缀的 '<' 一律视为模型 prose 原样透传,绝不丢弃
36
+ * (代价:恰好以 "<tf-xxx" 开头且全文无 '>' 的 prose 会被判为 truncated,
37
+ * 但内容仍在 raw 里,不丢失);
38
+ * - DSML 噪声(v0.3.1):模型偶尔把原生调用格式 `<||DSML|| …>`(U+FF5C 全角竖线)
39
+ * 混进文本流——协议里没有任何合法形式以 "<|" 开头,一律按协议违规处理,
40
+ * 绝不作为 prose 透传(透传会在桌面端渲染成乱码)。其中
41
+ * `<||DSML|| invoke name="tf-xxx" ...>` 形态改写回等价 tf-* 头部(命令不丢);
42
+ * 其余(calls 包装行等)以 malformed(dsml-wrapper) 上报后丢弃,只记台账不注入。
43
+ * - 未闭合即流终止 → truncated 事件(loop 据此决定重入策略);
44
+ * - depends_on 环 → cycle 事件(路径首尾相同,如 [a, b, a])。
45
+ * - 孤立闭合标签(v0.3.1 截断修复):ground 模式下出现的 `</tf-xxx>`(前面没有配对打开,
46
+ * 典型是模型把自闭合命令又"关闭"了一次)一律按 malformed(stray-close-tag) 记账后丢弃,
47
+ * 绝不作 prose 透传——0.3.1 真机证据:这类残片会以纯文本落进 assistant/message,
48
+ * 桌面端正文里出现裸的 `</tf-bash>`。
49
+ * - DSML 参数式调用(v0.3.2 截断修复):模型原生调用格式还有"父标签 + parameter 子标签"
50
+ * 形态(真机取证 session-e4b9a89c 第 6/9 步):
51
+ * <||DSML|| invoke name="tf-read">
52
+ * <||DSML|| parameter name="path" string="true">README.md</||DSML|| parameter>
53
+ * </||DSML|| invoke>
54
+ * 0.3.1 只认「invoke 头部内联属性」形态,parameter 子标签被逐条判 malformed,而标签之间的
55
+ * 属性值(README.md / r10 / 命令行)作为 prose 漏进正文——用户侧看到的就是"截断的正文 +
56
+ * `README.md r10` 这种残片",且命令根本没执行。本版把整个 invoke 块缓冲到闭合,按
57
+ * parameter 归集成属性后一次性发命令;块内文本不再作为 prose 透传。块未闭合即流终止时,
58
+ * 非正文命令(属性已齐)照常发命令(能救则救),正文命令按 truncated 丢弃(不写半截文件)。
59
+ * - 非正文命令的配对开标签(v0.3.2):`<tf-read ...>` 少了 `/` 时,0.3.1 会进入 body 模式
60
+ * 一直吞到流末尾(整个后续输出消失)。现在非正文命令一旦出现下一个 `<tf-` / `</tf-`
61
+ * 即视为已闭合(命令照常派发),流末尾仍未闭合也发命令并把剩余文本按 prose 归还。
62
+ *
63
+ * 事件类型:text / command / malformed / truncated / cycle / done。
64
+ * 命令闭合立即 emit,不等流结束;"当前可执行集合"用 readyCommands() 查询
65
+ * (命令闭合 + markDone() 后依赖全部满足的命令)。
66
+ */
67
+
68
+ // ---------------------------------------------------------------------------
69
+ // 协议 schema(显式定义;解析失败产出 malformed,绝不静默丢弃)
70
+ // ---------------------------------------------------------------------------
71
+
72
+ export type TfCommandName =
73
+ | 'tf-write' | 'tf-read' | 'tf-edit' | 'tf-append' | 'tf-grep' | 'tf-glob'
74
+ | 'tf-bash' | 'tf-peek' | 'tf-final' | 'tf-code' | 'tf-plan';
75
+
76
+ interface CommandSchema {
77
+ required: readonly string[];
78
+ optional: readonly string[];
79
+ hasBody: boolean;
80
+ }
81
+
82
+ /** id / depends_on / accepts 是所有命令的公共属性,不计入各命令 schema。
83
+ * accepts(F5):逗号分隔的验收项 id 列表——命令成功(有回执)时对应验收项记为已验证。 */
84
+ const COMMON_ATTRS: readonly string[] = ['id', 'depends_on', 'accepts'];
85
+
86
+ const COMMAND_SCHEMAS: Readonly<Record<TfCommandName, CommandSchema>> = {
87
+ 'tf-write': { required: ['path'], optional: [], hasBody: true },
88
+ 'tf-read': { required: ['path'], optional: ['offset', 'limit'], hasBody: false },
89
+ // F1:精确替换(body 用 OLD/NEW 标记行分隔两段字面量)与追加(body = 追加正文;
90
+ // anchor 给出插入锚点字面量,缺省 = 追加到文件末尾)。两者都映射宿主 edit/apply_patch,
91
+ // 不自建文件 IO。
92
+ 'tf-edit': { required: ['path'], optional: ['replace_all'], hasBody: true },
93
+ 'tf-append': { required: ['path'], optional: ['anchor'], hasBody: true },
94
+ // F2:搜索只回匹配行/路径(宿主 fs-search 的 grep/glob 映射),不回全文。
95
+ 'tf-grep': { required: ['pattern'], optional: ['path', 'include'], hasBody: false },
96
+ 'tf-glob': { required: ['pattern'], optional: ['path'], hasBody: false },
97
+ 'tf-bash': { required: ['cmd'], optional: [], hasBody: false },
98
+ 'tf-peek': { required: ['handle'], optional: ['from_line', 'to_line'], hasBody: false },
99
+ 'tf-final': { required: [], optional: ['summary'], hasBody: false },
100
+ // F5:计划与验收——body 按行声明验收项(`- [id] 描述`);计划状态在驱动器(宿主侧)持有,
101
+ // 请求只注差分;tf-final 在存在未验证验收项时判定为过早。
102
+ 'tf-plan': { required: [], optional: [], hasBody: true },
103
+ // 程序体 = PTC 的 async TS 函数体(可擦除语法);description 只进台账,timeout 为毫秒数
104
+ 'tf-code': { required: [], optional: ['timeout', 'description'], hasBody: true },
105
+ };
106
+
107
+ const COMMAND_NAMES: readonly TfCommandName[] =
108
+ ['tf-write', 'tf-read', 'tf-edit', 'tf-append', 'tf-grep', 'tf-glob', 'tf-bash', 'tf-peek', 'tf-final', 'tf-code', 'tf-plan'];
109
+
110
+ export interface TfCommand {
111
+ name: TfCommandName;
112
+ /** 协议 id;缺省时自动编号(cmd1、cmd2...) */
113
+ id: string;
114
+ /** 除 depends_on 外的全部属性(path/cmd/handle/from_line/...) */
115
+ attrs: Readonly<Record<string, string>>;
116
+ /** 仅 tf-write / tf-code 有;原文,无转义还原(tf-code = PTC 程序体) */
117
+ body?: string;
118
+ /** 依赖命令 id 列表(去空、去重、保序) */
119
+ depends_on: readonly string[];
120
+ /** 闭合序号 */
121
+ seq: number;
122
+ }
123
+
124
+ export type ParserEvent =
125
+ | { type: 'text'; text: string }
126
+ | { type: 'command'; command: TfCommand }
127
+ | { type: 'malformed'; raw: string; reason: string }
128
+ | { type: 'truncated'; raw: string; reason: string }
129
+ | { type: 'cycle'; cycle: readonly string[] }
130
+ | { type: 'done' };
131
+
132
+ // ---------------------------------------------------------------------------
133
+ // 流式解析器
134
+ // ---------------------------------------------------------------------------
135
+
136
+ type Mode = 'ground' | 'header' | 'body' | 'dsml';
137
+ type TagProbe = 'tag' | 'prose' | 'tf-unknown' | 'close-tag' | 'need-more' | 'dsml';
138
+
139
+ export class TfStreamParser {
140
+ private buf = '';
141
+ private mode: Mode = 'ground';
142
+ private ended = false;
143
+
144
+ /** DSML 参数式调用块缓冲(v0.3.2):从无内联属性的 invoke 开标签起,缓冲到块闭合。 */
145
+ private dsmlBuf = '';
146
+ private dsmlName: TfCommandName | null = null;
147
+
148
+ // body 中间态
149
+ private bodyName: TfCommandName | null = null;
150
+ private bodyAttrs: Record<string, string> | null = null;
151
+ private bodyDeps: readonly string[] | null = null;
152
+ private bodyRawOpen = '';
153
+ private bodyBuf = '';
154
+
155
+ private readonly commands = new Map<string, TfCommand>();
156
+ private readonly doneIds = new Set<string>();
157
+ private readonly emittedCycleKeys = new Set<string>();
158
+ private autoIdCounter = 0;
159
+ private seqCounter = 0;
160
+
161
+ /** 增量喂入;命令跨 chunk 边界闭合,闭合即产出事件。 */
162
+ feed(delta: string): ParserEvent[] {
163
+ if (this.ended) {
164
+ throw new Error('parser already ended; create a new TfStreamParser for the next stream');
165
+ }
166
+ this.buf += delta;
167
+ const events: ParserEvent[] = [];
168
+ // 一种模式内的推进可能连锁(header 闭合 → body 打开 → 同一 buf 里 body 闭合)
169
+ for (;;) {
170
+ if (!this.step(events)) break;
171
+ }
172
+ return events;
173
+ }
174
+
175
+ /** 流终止:冲刷剩余文本;未闭合产出 truncated;最后必发 done。 */
176
+ end(): ParserEvent[] {
177
+ if (this.ended) return [];
178
+ this.ended = true;
179
+ const events: ParserEvent[] = [];
180
+ if (this.mode === 'dsml') {
181
+ // v0.3.2:DSML 参数式块未闭合即流终止。非正文命令只要属性齐全就照常发(能救则救);
182
+ // 正文命令(tf-write/tf-edit/tf-append/tf-code)不写半截内容——按 truncated 上报。
183
+ const block = this.dsmlBuf + this.buf;
184
+ const expected = this.dsmlName;
185
+ this.dsmlBuf = '';
186
+ this.dsmlName = null;
187
+ this.buf = '';
188
+ this.mode = 'ground';
189
+ const parsed = parseDsmlBlock(block, expected, { allowIncompleteBody: false });
190
+ for (const bad of parsed.malformed) {
191
+ events.push({ type: 'malformed', raw: bad.raw, reason: bad.reason });
192
+ }
193
+ for (const cmd of parsed.commands) {
194
+ this.emitCommand(events, cmd.name, cmd.attrs, cmd.dependsOn, cmd.body, cmd.raw);
195
+ }
196
+ events.push({ type: 'truncated', raw: block, reason: 'unclosed-dsml-invoke' });
197
+ } else if (this.mode === 'header') {
198
+ if (isDsmlTag(this.buf)) {
199
+ // DSML 尾巴(feed 期间已进 header 模式但流终止):malformed 上报,不进 prose
200
+ events.push({ type: 'malformed', raw: this.buf, reason: 'dsml-wrapper' });
201
+ this.buf = '';
202
+ } else {
203
+ events.push({ type: 'truncated', raw: this.buf, reason: 'unclosed-command-tag' });
204
+ }
205
+ } else if (this.mode === 'body') {
206
+ if (!COMMAND_SCHEMAS[this.bodyName!].hasBody) {
207
+ // v0.3.2:非正文命令的配对开标签缺闭合——命令本身是完整的(属性齐),
208
+ // 不能因为模型少写一个 '/' 就把整条命令连同后续输出一起丢掉。
209
+ const name = this.bodyName!;
210
+ const attrs = this.bodyAttrs!;
211
+ const deps = this.bodyDeps!;
212
+ const rawOpen = this.bodyRawOpen;
213
+ const trailing = this.bodyBuf + this.buf;
214
+ this.buf = '';
215
+ this.bodyName = null;
216
+ this.bodyAttrs = null;
217
+ this.bodyDeps = null;
218
+ this.bodyRawOpen = '';
219
+ this.bodyBuf = '';
220
+ this.mode = 'ground';
221
+ if (trailing.trim() !== '') {
222
+ events.push({ type: 'malformed', raw: trailing, reason: 'unexpected-body' });
223
+ }
224
+ this.emitCommand(events, name, attrs, deps, undefined, rawOpen + trailing);
225
+ if (trailing.trim() !== '') events.push({ type: 'text', text: trailing });
226
+ } else {
227
+ events.push({
228
+ type: 'truncated',
229
+ raw: this.bodyRawOpen + this.bodyBuf + this.buf,
230
+ reason: `unclosed-command-body:${this.bodyName}`,
231
+ });
232
+ }
233
+ } else {
234
+ // ground:残留的 "<tf-" 片段(尚无法判定是否标签)→ truncated;
235
+ // DSML 尾巴(协议违规,v0.3.1)→ malformed 上报后丢弃,不作为 prose 泄漏;
236
+ // 其余(含普通 '<')全部按 prose 透传
237
+ const lt = this.buf.lastIndexOf('<');
238
+ const tail = lt >= 0 ? this.buf.slice(lt) : '';
239
+ const tailProbe = tail === '' ? 'prose' : probeTag(tail);
240
+ if (tail.startsWith('<tf-') && tailProbe === 'need-more') {
241
+ if (lt > 0) events.push({ type: 'text', text: this.buf.slice(0, lt) });
242
+ events.push({ type: 'truncated', raw: tail, reason: 'unclosed-command-tag' });
243
+ } else if (tailProbe === 'dsml') {
244
+ if (lt > 0) events.push({ type: 'text', text: this.buf.slice(0, lt) });
245
+ events.push({ type: 'malformed', raw: tail, reason: 'dsml-wrapper' });
246
+ } else if (tail.startsWith('</tf-') && (tailProbe === 'close-tag' || tailProbe === 'need-more')) {
247
+ // v0.3.1:孤立闭合标签(含被流截断的半截)——记账丢弃,不进 prose
248
+ if (lt > 0) events.push({ type: 'text', text: this.buf.slice(0, lt) });
249
+ events.push({ type: 'malformed', raw: tail, reason: `stray-close-tag:${closeTagName(tail)}` });
250
+ } else if (this.buf !== '') {
251
+ events.push({ type: 'text', text: this.buf });
252
+ }
253
+ this.buf = '';
254
+ }
255
+ events.push({ type: 'done' });
256
+ return events;
257
+ }
258
+
259
+ /** 标记命令执行完成(由 loop 调用);未注册的 id 忽略。 */
260
+ markDone(id: string): void {
261
+ this.doneIds.add(id);
262
+ }
263
+
264
+ /**
265
+ * 当前可执行集合:已闭合、未完成、且 depends_on 全部完成的命令(按闭合序)。
266
+ * 依赖指向未出现过的 id → 永不就绪(模型声明了不存在的依赖,交 loop 层处理)。
267
+ */
268
+ readyCommands(): TfCommand[] {
269
+ const out: TfCommand[] = [];
270
+ for (const cmd of this.commands.values()) {
271
+ if (this.doneIds.has(cmd.id)) continue;
272
+ if (cmd.depends_on.every((d) => this.doneIds.has(d))) out.push(cmd);
273
+ }
274
+ return out.sort((a, b) => a.seq - b.seq);
275
+ }
276
+
277
+ // -------------------------------------------------------------------------
278
+
279
+ /** 状态机推进一步;有进展返回 true(events 可能追加 0..n 条)。 */
280
+ private step(events: ParserEvent[]): boolean {
281
+ if (this.mode === 'ground') return this.stepGround(events);
282
+ if (this.mode === 'header') return this.stepHeader(events);
283
+ if (this.mode === 'dsml') return this.stepDsml(events);
284
+ return this.stepBody(events);
285
+ }
286
+
287
+ private stepGround(events: ParserEvent[]): boolean {
288
+ const lt = this.buf.indexOf('<');
289
+ if (lt === -1) {
290
+ if (this.buf !== '') events.push({ type: 'text', text: this.buf });
291
+ this.buf = '';
292
+ return false;
293
+ }
294
+ const probe = probeTag(this.buf.slice(lt));
295
+ if (probe === 'need-more') return false;
296
+ if (probe === 'close-tag') {
297
+ // v0.3.1:孤立闭合标签——前面没有配对打开(自闭合命令被多关一次、或模型手写了
298
+ // 残片)。按协议违规记账后丢弃,绝不作为 prose 落进正文。
299
+ const gt = this.buf.indexOf('>', lt);
300
+ const raw = gt === -1 ? this.buf.slice(lt) : this.buf.slice(lt, gt + 1);
301
+ if (lt > 0) events.push({ type: 'text', text: this.buf.slice(0, lt) });
302
+ this.buf = gt === -1 ? '' : this.buf.slice(gt + 1);
303
+ events.push({ type: 'malformed', raw, reason: `stray-close-tag:${closeTagName(raw)}` });
304
+ return true;
305
+ }
306
+ if (probe === 'prose') {
307
+ // '<' 是普通文本的一部分:原样透传,从 '<' 之后继续扫
308
+ events.push({ type: 'text', text: this.buf.slice(0, lt + 1) });
309
+ this.buf = this.buf.slice(lt + 1);
310
+ return true;
311
+ }
312
+ // tag / tf-unknown / dsml:都进入 header 模式(后两者闭合时判 malformed 或改写)
313
+ if (lt > 0) events.push({ type: 'text', text: this.buf.slice(0, lt) });
314
+ this.buf = this.buf.slice(lt);
315
+ this.mode = 'header';
316
+ return true;
317
+ }
318
+
319
+ private stepHeader(events: ParserEvent[]): boolean {
320
+ const close = scanHeaderClose(this.buf);
321
+ if (!close) return false; // 等更多数据
322
+ const raw = this.buf.slice(0, close.end + 1);
323
+ this.buf = this.buf.slice(close.end + 1);
324
+ this.mode = 'ground';
325
+
326
+ // DSML 噪声(v0.3.1):先于普通解析处理——`invoke name="tf-xxx" ...` 形态改写回
327
+ // 等价 tf-* 头部(命令不丢);其余包装行按 malformed 上报后丢弃(不进 prose)。
328
+ if (isDsmlTag(raw)) {
329
+ // v0.3.2:参数式 invoke → 进入块缓冲,按 parameter 归集属性。
330
+ // 0.3.1 只认内联属性形态,parameter 子标签之间的值会作为 prose 泄漏(真机残片
331
+ // `README.md r10` / `Get-ChildItem ... b902` 均由此产生)。
332
+ // v0.3.2 补充:带内联属性的 invoke 同样缓冲(parseDsmlBlock 本就合并内联属性与
333
+ // parameter——parameter 覆盖同名内联键)。此前内联属性走 parseDsmlHeader 进 body
334
+ // 模式,非正文命令的 DSML 包装残片会被吞到流末才以 malformed 露出
335
+ // (真机 session-8f22c7a0 step 2:三条闭合标签残片)。
336
+ const dsml = parseDsmlTag(raw, close.selfClosing);
337
+ if (
338
+ dsml !== null
339
+ && dsml.name === 'invoke'
340
+ && !dsml.closing
341
+ && !close.selfClosing
342
+ && dsml.commandName !== null
343
+ ) {
344
+ this.dsmlBuf = raw;
345
+ this.dsmlName = dsml.commandName;
346
+ this.mode = 'dsml';
347
+ return true;
348
+ }
349
+ const inline = parseDsmlHeader(raw, close.selfClosing);
350
+ if (inline === null) {
351
+ events.push({ type: 'malformed', raw, reason: 'dsml-wrapper' });
352
+ return true;
353
+ }
354
+ const parsed = parseHeader(inline.synthetic);
355
+ if ('error' in parsed || parsed.name === null) {
356
+ events.push({ type: 'malformed', raw, reason: 'dsml-wrapper' });
357
+ return true;
358
+ }
359
+ if (close.selfClosing) {
360
+ this.emitCommand(events, parsed.name, parsed.attrs, parsed.dependsOn, undefined, raw);
361
+ } else {
362
+ this.bodyName = parsed.name;
363
+ this.bodyAttrs = parsed.attrs;
364
+ this.bodyDeps = parsed.dependsOn;
365
+ this.bodyRawOpen = raw;
366
+ this.bodyBuf = '';
367
+ this.mode = 'body';
368
+ }
369
+ return true;
370
+ }
371
+
372
+ const parsed = parseHeader(raw);
373
+ if ('error' in parsed) {
374
+ events.push({ type: 'malformed', raw, reason: parsed.error });
375
+ return true;
376
+ }
377
+ if (parsed.name === null) {
378
+ // <tf- 前缀但命令名未知(probeTag 已判定 tf-unknown)
379
+ events.push({ type: 'malformed', raw, reason: 'unknown-command' });
380
+ return true;
381
+ }
382
+ if (close.selfClosing) {
383
+ this.emitCommand(events, parsed.name, parsed.attrs, parsed.dependsOn, undefined, raw);
384
+ return true;
385
+ }
386
+ // 配对形式打开:进入 body 模式(body 内容是否合法在闭合时判定)
387
+ this.bodyName = parsed.name;
388
+ this.bodyAttrs = parsed.attrs;
389
+ this.bodyDeps = parsed.dependsOn;
390
+ this.bodyRawOpen = raw;
391
+ this.bodyBuf = '';
392
+ this.mode = 'body';
393
+ return true;
394
+ }
395
+
396
+ private stepBody(events: ParserEvent[]): boolean {
397
+ const name = this.bodyName!;
398
+ const schema = COMMAND_SCHEMAS[name];
399
+ const closeTag = `</${name}>`;
400
+ const closeIdx = this.buf.indexOf(closeTag);
401
+ // v0.3.2:非正文命令的配对开标签(少写 '/')不得吞掉后续输出——遇到下一个
402
+ // `<tf-` / `</tf-` 即视为本命令结束,命令照常派发,剩余文本回到 ground 继续解析。
403
+ // v0.3.2 补充:DSML 标签同样是边界(包装残片立即露出,不吞到流末)。
404
+ if (!schema.hasBody) {
405
+ const boundary = findNonBodyBoundaryWithDsml(this.buf);
406
+ if (boundary !== -1 && (closeIdx === -1 || boundary < closeIdx)) {
407
+ const body = this.bodyBuf + this.buf.slice(0, boundary);
408
+ const raw = this.bodyRawOpen + body;
409
+ this.buf = this.buf.slice(boundary);
410
+ this.mode = 'ground';
411
+ const attrs = this.bodyAttrs!;
412
+ const deps = this.bodyDeps!;
413
+ this.bodyName = null;
414
+ this.bodyAttrs = null;
415
+ this.bodyDeps = null;
416
+ this.bodyRawOpen = '';
417
+ this.bodyBuf = '';
418
+ if (body.trim() !== '') {
419
+ events.push({ type: 'malformed', raw: body, reason: 'unexpected-body' });
420
+ // 非正文命令后面的文本是模型 prose(不是命令输入)——归还正文,避免"输出变少"。
421
+ events.push({ type: 'text', text: body });
422
+ }
423
+ this.emitCommand(events, name, attrs, deps, undefined, raw);
424
+ return true;
425
+ }
426
+ }
427
+ if (closeIdx === -1) {
428
+ // 闭合标签可能被拆在 chunk 边界上:扣留末尾至多 closeTag.length-1 个字符
429
+ const keep = Math.min(closeTag.length - 1, this.buf.length);
430
+ this.bodyBuf += this.buf.slice(0, this.buf.length - keep);
431
+ this.buf = this.buf.slice(this.buf.length - keep);
432
+ return false;
433
+ }
434
+ const body = this.bodyBuf + this.buf.slice(0, closeIdx);
435
+ const raw = this.bodyRawOpen + body + closeTag;
436
+ this.buf = this.buf.slice(closeIdx + closeTag.length);
437
+ this.mode = 'ground';
438
+ const attrs = this.bodyAttrs!;
439
+ const deps = this.bodyDeps!;
440
+ this.bodyName = null;
441
+ this.bodyAttrs = null;
442
+ this.bodyDeps = null;
443
+ this.bodyRawOpen = '';
444
+ this.bodyBuf = '';
445
+
446
+ if (!schema.hasBody && body !== '') {
447
+ // 非正文命令带正文:命令本身仍有效(属性齐),正文只记账不当作命令输入。
448
+ // v0.3.2 起不再丢弃命令——0.3.1 会整条判 malformed,模型侧表现为"命令没执行"。
449
+ events.push({ type: 'malformed', raw, reason: 'unexpected-body' });
450
+ this.emitCommand(events, name, attrs, deps, undefined, raw);
451
+ return true;
452
+ }
453
+ this.emitCommand(events, name, attrs, deps, schema.hasBody ? body : undefined, raw);
454
+ return true;
455
+ }
456
+
457
+ /**
458
+ * v0.3.2:DSML 参数式 invoke 块。缓冲到块闭合后一次性归集为命令:
459
+ * 块内 `<||DSML|| parameter name="k">value</...>` 的 value 归入属性 k,
460
+ * 不再作为 prose 泄漏;块内裸文本按命令正文处理(hasBody 命令)。
461
+ */
462
+ private stepDsml(events: ParserEvent[]): boolean {
463
+ if (this.buf !== '') {
464
+ this.dsmlBuf += this.buf;
465
+ this.buf = '';
466
+ }
467
+ const term = findDsmlInvokeEnd(this.dsmlBuf, this.dsmlName);
468
+ if (term === null) return false;
469
+ const block = this.dsmlBuf.slice(0, term.end);
470
+ const rest = this.dsmlBuf.slice(term.end);
471
+ const expected = this.dsmlName;
472
+ this.dsmlBuf = '';
473
+ this.dsmlName = null;
474
+ this.mode = 'ground';
475
+ this.buf = rest;
476
+ const parsed = parseDsmlBlock(block, expected, { allowIncompleteBody: true });
477
+ for (const bad of parsed.malformed) {
478
+ events.push({ type: 'malformed', raw: bad.raw, reason: bad.reason });
479
+ }
480
+ for (const cmd of parsed.commands) {
481
+ this.emitCommand(events, cmd.name, cmd.attrs, cmd.dependsOn, cmd.body, cmd.raw);
482
+ }
483
+ return true;
484
+ }
485
+
486
+ private emitCommand(
487
+ events: ParserEvent[],
488
+ name: TfCommandName,
489
+ attrs: Record<string, string>,
490
+ deps: readonly string[],
491
+ body: string | undefined,
492
+ raw: string,
493
+ ): void {
494
+ const seq = ++this.seqCounter;
495
+ const id = attrs['id'] ?? `cmd${++this.autoIdCounter}`;
496
+ // 重复 id 不在 parser 层拦截(v0.2 起移交驱动器裁决):同 id 同内容 = 幂等返回原回执,
497
+ // 同 id 不同内容 = 拒绝换新 id,被拒命令可用原 id 修正重发(上游 ThinkFlow 分层语义:
498
+ // "parser 仅在语义校验成功后登记 id",id 幂等是 context/账本层职责)。
499
+ const isDuplicate = this.commands.has(id);
500
+ const { id: _ignored, ...rest } = attrs;
501
+ const command: TfCommand = { name, id, attrs: rest, body, depends_on: deps, seq };
502
+ this.commands.set(id, command);
503
+ events.push({ type: 'command', command });
504
+
505
+ // 命令闭合后立即做环检测(depends_on 图只含已闭合命令)
506
+ const cycle = this.findCycle();
507
+ if (cycle) {
508
+ const key = cycle.join('>');
509
+ if (!this.emittedCycleKeys.has(key)) {
510
+ this.emittedCycleKeys.add(key);
511
+ events.push({ type: 'cycle', cycle });
512
+ }
513
+ }
514
+ }
515
+
516
+ /** 在已闭合命令的依赖图中找环(DFS 三色标记),返回路径 [a, ..., a] 或 null。 */
517
+ private findCycle(): readonly string[] | null {
518
+ const state = new Map<string, 0 | 1 | 2>();
519
+ const path: string[] = [];
520
+ let found: string[] | null = null;
521
+ const dfs = (id: string): void => {
522
+ if (found) return;
523
+ const st = state.get(id) ?? 0;
524
+ if (st === 1) {
525
+ found = [...path.slice(path.indexOf(id)), id];
526
+ return;
527
+ }
528
+ if (st === 2) return;
529
+ state.set(id, 1);
530
+ path.push(id);
531
+ for (const d of this.commands.get(id)!.depends_on) {
532
+ if (this.commands.has(d)) dfs(d);
533
+ if (found) return;
534
+ }
535
+ path.pop();
536
+ state.set(id, 2);
537
+ };
538
+ for (const id of this.commands.keys()) {
539
+ if (found) break;
540
+ dfs(id);
541
+ }
542
+ return found;
543
+ }
544
+ }
545
+
546
+ // ---------------------------------------------------------------------------
547
+ // 头部扫描与属性解析
548
+ // ---------------------------------------------------------------------------
549
+
550
+ /**
551
+ * 引号感知地找头部结束 '>'。
552
+ * 属性值(如 cmd="a > b")里的 '>' 不终止头部。返回 null 表示需要更多数据。
553
+ */
554
+ function scanHeaderClose(buf: string): { end: number; selfClosing: boolean } | null {
555
+ let inQuote = false;
556
+ for (let i = 1; i < buf.length; i++) {
557
+ const ch = buf[i];
558
+ if (inQuote) {
559
+ if (ch === '"') inQuote = false;
560
+ continue;
561
+ }
562
+ if (ch === '"') {
563
+ inQuote = true;
564
+ } else if (ch === '>') {
565
+ return { end: i, selfClosing: buf[i - 1] === '/' };
566
+ }
567
+ }
568
+ return null;
569
+ }
570
+
571
+ // ---------------------------------------------------------------------------
572
+ // DSML 噪声归一化(v0.3.1)
573
+ // ---------------------------------------------------------------------------
574
+
575
+ /** DSML 前缀:"<" 后跟全角竖线(U+FF5C)串 + "DSML" + 全角竖线串。观察到的真机形态:
576
+ * `<||DSML|| calls>`、`<||DSML|| invoke name="tf-plan" id="p1">`。 */
577
+ const DSML_TAG_RE = /^<\/?|+DSML|*/;
578
+
579
+ /** 判定一段头部原文是否是 DSML 噪声标签(probeTag 'dsml' 的闭合侧复核)。 */
580
+ function isDsmlTag(raw: string): boolean {
581
+ return DSML_TAG_RE.test(raw);
582
+ }
583
+
584
+ /** 从孤立闭合标签原文取命令名(`</tf-bash>` → `tf-bash`;半截标签 → `?`)。 */
585
+ function closeTagName(raw: string): string {
586
+ const m = /^<\/\s*(tf-[a-z0-9-]*)/.exec(raw);
587
+ return m === null ? '?' : m[1]!;
588
+ }
589
+
590
+ /**
591
+ * 尝试把 DSML 头部改写为等价 tf-* 头部。
592
+ * 可改写形态:`<||DSML|| invoke name="tf-xxx" 其余属性/>`(或配对打开)——
593
+ * 返回合成头部原文(`<tf-xxx 其余属性...>`);包装行(calls 等)与无法解析的
594
+ * 属性段返回 null(调用方按 malformed 上报丢弃,绝不作为 prose 透传)。
595
+ */
596
+ function parseDsmlHeader(raw: string, selfClosing: boolean): { synthetic: string } | null {
597
+ // 去掉 '<' 与结尾 '>'(或 '/>'),取 DSML 前缀之后的剩余段
598
+ let inner = raw.slice(1);
599
+ if (selfClosing && inner.endsWith('/>')) inner = inner.slice(0, -2);
600
+ else if (inner.endsWith('>')) inner = inner.slice(0, -1);
601
+ const rest = inner.replace(/^\/?|+DSML|*/, '');
602
+ const invoke = rest.match(/^\s*invoke\s+name="(tf-[a-z]+)"([\s\S]*)$/);
603
+ if (invoke === null) return null;
604
+ const [, name, attrsPart] = invoke as unknown as [string, string, string];
605
+ if (!COMMAND_NAMES.includes(name as TfCommandName)) return null;
606
+ // 属性段原样拼接:dsml 属性语法与 tf 协议一致(key="value"),交 parseHeader 统一校验
607
+ return { synthetic: `<${name}${attrsPart}${selfClosing ? '/>' : '>'}` };
608
+ }
609
+
610
+ // ---------------------------------------------------------------------------
611
+ // DSML 参数式 invoke(v0.3.2)
612
+ // ---------------------------------------------------------------------------
613
+
614
+ interface DsmlTag {
615
+ /** 标签名(invoke / calls / parameter …,已去掉 DSML 前缀) */
616
+ name: string;
617
+ closing: boolean;
618
+ selfClosing: boolean;
619
+ /** 标签内 key="value" 属性 */
620
+ attrs: Record<string, string>;
621
+ /** invoke 的 name 属性是合法 tf-* 命令名时给出 */
622
+ commandName: TfCommandName | null;
623
+ }
624
+
625
+ /** 解析单个 DSML 标签原文(不含前后空白)。非 DSML 形态返回 null。 */
626
+ function parseDsmlTag(raw: string, selfClosing: boolean): DsmlTag | null {
627
+ if (!isDsmlTag(raw)) return null;
628
+ let inner = raw.slice(1);
629
+ const closing = inner.startsWith('/');
630
+ if (closing) inner = inner.slice(1);
631
+ if (inner.endsWith('/>')) inner = inner.slice(0, -2);
632
+ else if (inner.endsWith('>')) inner = inner.slice(0, -1);
633
+ const m = inner.match(/^|+DSML|*\s*([a-zA-Z][a-zA-Z0-9_-]*)([\s\S]*)$/);
634
+ if (m === null) return null;
635
+ const name = m[1]!;
636
+ const attrs = parseAttrPairs(m[2]!);
637
+ const commandName = attrs['name'] !== undefined && COMMAND_NAMES.includes(attrs['name'] as TfCommandName)
638
+ ? (attrs['name'] as TfCommandName)
639
+ : null;
640
+ return { name, closing, selfClosing, attrs, commandName };
641
+ }
642
+
643
+ /** v0.3.2:属性值的 XML 实体解码。模型带 XML 习惯输出属性(真机 session-8f22c7a0
644
+ * step 5:`command="... Write-Output &quot;EXIT=$LASTEXITCODE&quot;"`——实体原样进了
645
+ * PowerShell,命令解析报错,白白烧一步)。只解码有界实体集 + 数字引用;`&` 本身
646
+ * 不在实体里的原样保留(不猜)。 */
647
+ function decodeXmlEntities(value: string): string {
648
+ return value
649
+ .replace(/&(lt|gt|quot|apos|amp);/g, (_, name: string) => (
650
+ name === 'lt' ? '<' : name === 'gt' ? '>' : name === 'quot' ? '"' : name === 'apos' ? '\'' : '&'
651
+ ))
652
+ .replace(/&#x([0-9a-fA-F]+);/g, (_, hex: string) => String.fromCodePoint(parseInt(hex, 16)))
653
+ .replace(/&#(\d+);/g, (_, dec: string) => String.fromCodePoint(parseInt(dec, 10)));
654
+ }
655
+
656
+ /** 从 `k="v" k2="v2"` 属性段提取键值(引号内允许 '>';重复键后者覆盖,交由 schema 兜底)。 */
657
+ function parseAttrPairs(segment: string): Record<string, string> {
658
+ const attrs: Record<string, string> = {};
659
+ const re = /([a-zA-Z][a-zA-Z0-9_-]*)\s*=\s*"([^"]*)"/g;
660
+ let m: RegExpExecArray | null;
661
+ while ((m = re.exec(segment)) !== null) attrs[m[1]!] = decodeXmlEntities(m[2]!);
662
+ return attrs;
663
+ }
664
+
665
+ /**
666
+ * 非正文命令配对开标签的恢复边界(基础版,仅 tf 标签):下一个 `<tf-` / `</tf-` 的
667
+ * 位置(-1 = 没有)。DSML 块缓冲的消费(findDsmlInvokeEnd)也用它——缓冲块内部的
668
+ * DSML 标签属于块本身,绝不能当边界(否则 `<|` 即块结束 = 解析死循环)。
669
+ */
670
+ function findNonBodyBoundary(buf: string): number {
671
+ const a = buf.indexOf('<tf-');
672
+ const b = buf.indexOf('</tf-');
673
+ if (a === -1) return b;
674
+ if (b === -1) return a;
675
+ return Math.min(a, b);
676
+ }
677
+
678
+ /**
679
+ * v0.3.2:body 模式的扩展边界(tf 标签 + DSML 标签)。只在 stepBody 的非正文分支
680
+ * 使用——真机(session-8f22c7a0 step 2)里 DSML invoke 走完内联路径后,parameter/
681
+ * invoke/closes 包装残片被 body 模式整体吞掉、到流末才以 malformed 露出;DSML 标签
682
+ * 出现即视为本命令结束(残片按既有 malformed 纪律处理,绝不作为 prose 透传)。
683
+ */
684
+ function findNonBodyBoundaryWithDsml(buf: string): number {
685
+ const base = findNonBodyBoundary(buf);
686
+ const c = buf.indexOf('<|');
687
+ const d = buf.indexOf('</|');
688
+ let min = base;
689
+ for (const v of [c, d]) {
690
+ if (v === -1) continue;
691
+ if (min === -1 || v < min) min = v;
692
+ }
693
+ return min;
694
+ }
695
+
696
+ /** DSML 段结束位置(含结束标签本身):`</invoke>` / `</tf-name>` / (非正文)下一个 tf 标签。 */
697
+ function findDsmlInvokeEnd(buf: string, name: TfCommandName | null): { end: number } | null {
698
+ let end = -1;
699
+ const invokeClose = /<\/\s*|+DSML|*\s*invoke\s*>/g;
700
+ const m = invokeClose.exec(buf);
701
+ if (m !== null) end = m.index + m[0].length;
702
+ if (name !== null) {
703
+ const tagClose = buf.indexOf(`</${name}>`);
704
+ if (tagClose !== -1 && (end === -1 || tagClose + name.length + 3 < end)) {
705
+ end = tagClose + name.length + 3;
706
+ }
707
+ if (!COMMAND_SCHEMAS[name].hasBody) {
708
+ const boundary = findNonBodyBoundary(buf);
709
+ if (boundary !== -1 && (end === -1 || boundary < end)) end = boundary;
710
+ }
711
+ }
712
+ return end === -1 ? null : { end };
713
+ }
714
+
715
+ interface DsmlCommand {
716
+ name: TfCommandName;
717
+ attrs: Record<string, string>;
718
+ dependsOn: readonly string[];
719
+ body?: string;
720
+ raw: string;
721
+ }
722
+
723
+ type DsmlToken =
724
+ | { kind: 'tag'; tag: DsmlTag; raw: string }
725
+ | { kind: 'text'; text: string };
726
+
727
+ /** 把 DSML 块切成「DSML 标签 / 文本」两类 token;非 DSML 的 '<' 留在文本里。 */
728
+ function tokenizeDsmlBlock(block: string): DsmlToken[] {
729
+ const out: DsmlToken[] = [];
730
+ let i = 0;
731
+ while (i < block.length) {
732
+ const lt = block.indexOf('<', i);
733
+ if (lt === -1) {
734
+ out.push({ kind: 'text', text: block.slice(i) });
735
+ break;
736
+ }
737
+ if (lt > i) out.push({ kind: 'text', text: block.slice(i, lt) });
738
+ const after = block.slice(lt);
739
+ if (!/^<\/?|/.test(after)) {
740
+ out.push({ kind: 'text', text: '<' });
741
+ i = lt + 1;
742
+ continue;
743
+ }
744
+ const close = scanHeaderClose(after);
745
+ if (close === null) {
746
+ out.push({ kind: 'text', text: after });
747
+ break;
748
+ }
749
+ const raw = after.slice(0, close.end + 1);
750
+ const tag = parseDsmlTag(raw, close.selfClosing);
751
+ if (tag === null) out.push({ kind: 'text', text: raw });
752
+ else out.push({ kind: 'tag', tag, raw });
753
+ i = lt + close.end + 1;
754
+ }
755
+ return out;
756
+ }
757
+
758
+ /**
759
+ * 解析一个 DSML invoke 块(可能含 parameter 子标签)。
760
+ *
761
+ * - `parameter name="k"` 的标签间文本 → 属性 k(多行原样,去掉首尾各一个换行);
762
+ * - 正文类参数(content/body/code/text)→ 命令 body(hasBody 命令);
763
+ * - 块内裸文本 → hasBody 命令的 body;tf-final 无 summary 时兜底为最终答案;
764
+ * - 非正文命令带正文 → malformed(unexpected-body) 但命令仍发(不丢工作);
765
+ * - `allowIncompleteBody=false` 时,未闭合的正文命令不回放(避免写半截文件)。
766
+ */
767
+ function parseDsmlBlock(
768
+ block: string,
769
+ expected: TfCommandName | null,
770
+ opts: { allowIncompleteBody: boolean },
771
+ ): { commands: DsmlCommand[]; malformed: Array<{ raw: string; reason: string }> } {
772
+ const commands: DsmlCommand[] = [];
773
+ const malformed: Array<{ raw: string; reason: string }> = [];
774
+ let cur: {
775
+ name: TfCommandName | null;
776
+ attrs: Record<string, string>;
777
+ text: string;
778
+ params: Record<string, string>;
779
+ paramName: string | null;
780
+ paramValue: string;
781
+ raw: string;
782
+ complete: boolean;
783
+ } | null = null;
784
+
785
+ const flush = (complete: boolean): void => {
786
+ if (cur === null) return;
787
+ const item = cur;
788
+ cur = null;
789
+ if (item.paramName !== null) item.params[item.paramName] = trimParamValue(item.paramValue);
790
+ const name = item.name ?? expected;
791
+ if (name === null) {
792
+ malformed.push({ raw: item.raw, reason: 'dsml-unknown-invoke' });
793
+ return;
794
+ }
795
+ const schema = COMMAND_SCHEMAS[name];
796
+ const attrs: Record<string, string> = { ...item.attrs };
797
+ const bodyKeys = ['content', 'body', 'code', 'text'];
798
+ let bodyFromParam: string | undefined;
799
+ for (const key of bodyKeys) {
800
+ if (item.params[key] !== undefined) {
801
+ bodyFromParam = item.params[key];
802
+ delete item.params[key];
803
+ }
804
+ }
805
+ for (const [k, v] of Object.entries(item.params)) attrs[k] = v;
806
+ if (!complete && schema.hasBody && !opts.allowIncompleteBody) {
807
+ malformed.push({ raw: item.raw + item.text, reason: 'unclosed-dsml-body' });
808
+ return;
809
+ }
810
+ let body: string | undefined;
811
+ if (schema.hasBody) {
812
+ // v0.3.2:块以命令自身的配对闭合(</name>)终止时,闭合标签会被 tokenizer 当作
813
+ // 块内文本累积——剥掉尾部闭合,正文才干净(与 body 模式的消费语义一致)。
814
+ let text = item.text;
815
+ if (bodyFromParam === undefined) {
816
+ const closeTag = `</${name}>`;
817
+ const closeIdx = text.lastIndexOf(closeTag);
818
+ if (closeIdx !== -1 && text.slice(closeIdx).trim() === closeTag) {
819
+ text = text.slice(0, closeIdx);
820
+ }
821
+ }
822
+ body = bodyFromParam ?? text.replace(/^\r?\n/, '').replace(/\r?\n$/, '');
823
+ } else if (bodyFromParam !== undefined || item.text.trim() !== '') {
824
+ malformed.push({ raw: item.raw + item.text, reason: 'unexpected-body' });
825
+ if (name === 'tf-final' && attrs['summary'] === undefined) {
826
+ attrs['summary'] = (bodyFromParam ?? item.text).trim();
827
+ }
828
+ }
829
+ const validated = validateCommandAttrs(name, attrs);
830
+ if ('error' in validated) {
831
+ malformed.push({ raw: item.raw, reason: `dsml-invoke:${validated.error}` });
832
+ return;
833
+ }
834
+ commands.push({ name, attrs: validated.attrs, dependsOn: validated.dependsOn, body, raw: item.raw });
835
+ };
836
+
837
+ for (const token of tokenizeDsmlBlock(block)) {
838
+ if (token.kind === 'text') {
839
+ if (cur === null) {
840
+ if (token.text.trim() !== '') malformed.push({ raw: token.text, reason: 'dsml-text' });
841
+ continue;
842
+ }
843
+ if (cur.paramName !== null) cur.paramValue += token.text;
844
+ else cur.text += token.text;
845
+ continue;
846
+ }
847
+ const tag = token.tag;
848
+ if (tag.name === 'calls') continue;
849
+ if (tag.name === 'invoke') {
850
+ if (tag.closing) {
851
+ flush(true);
852
+ continue;
853
+ }
854
+ flush(true);
855
+ if (tag.commandName === null) {
856
+ malformed.push({ raw: token.raw, reason: 'dsml-unknown-invoke' });
857
+ continue;
858
+ }
859
+ const { name: _n, ...rest } = tag.attrs;
860
+ cur = {
861
+ name: tag.commandName,
862
+ attrs: rest,
863
+ text: '',
864
+ params: {},
865
+ paramName: null,
866
+ paramValue: '',
867
+ raw: token.raw,
868
+ complete: false,
869
+ };
870
+ if (tag.selfClosing) flush(true);
871
+ continue;
872
+ }
873
+ if (tag.name === 'parameter') {
874
+ if (tag.closing) {
875
+ if (cur !== null && cur.paramName !== null) {
876
+ cur.params[cur.paramName] = trimParamValue(cur.paramValue);
877
+ cur.paramName = null;
878
+ cur.paramValue = '';
879
+ }
880
+ continue;
881
+ }
882
+ if (cur === null) {
883
+ malformed.push({ raw: token.raw, reason: 'dsml-stray-parameter' });
884
+ continue;
885
+ }
886
+ const key = tag.attrs['name'];
887
+ if (key === undefined) {
888
+ malformed.push({ raw: token.raw, reason: 'dsml-parameter-without-name' });
889
+ continue;
890
+ }
891
+ cur.paramName = key;
892
+ cur.paramValue = '';
893
+ if (tag.selfClosing) {
894
+ cur.params[key] = '';
895
+ cur.paramName = null;
896
+ }
897
+ continue;
898
+ }
899
+ malformed.push({ raw: token.raw, reason: `dsml-unknown-tag:${tag.name}` });
900
+ }
901
+ flush(false);
902
+ return { commands, malformed };
903
+ }
904
+
905
+ /** parameter 值:去掉首尾各一个换行(模型习惯把值写在标签下一行)。 */
906
+ function trimParamValue(value: string): string {
907
+ return value.replace(/^\r?\n/, '').replace(/\r?\n$/, '');
908
+ }
909
+
910
+ /** 属性 schema 校验(parseHeader 与 DSML 块共用;校验失败返回结构化 error)。 */
911
+ function validateCommandAttrs(
912
+ name: TfCommandName,
913
+ attrs: Record<string, string>,
914
+ ): { attrs: Record<string, string>; dependsOn: readonly string[] } | { error: string } {
915
+ const schema = COMMAND_SCHEMAS[name];
916
+ const allowed = new Set([...COMMON_ATTRS, ...schema.required, ...schema.optional]);
917
+ for (const key of Object.keys(attrs)) {
918
+ if (!allowed.has(key)) return { error: `unknown-attribute:${key}` };
919
+ }
920
+ for (const req of schema.required) {
921
+ if (attrs[req] === undefined) return { error: `missing-attribute:${req}` };
922
+ }
923
+ for (const key of ['from_line', 'to_line']) {
924
+ if (attrs[key] !== undefined && !/^\d+$/.test(attrs[key])) {
925
+ return { error: `bad-integer-attribute:${key}` };
926
+ }
927
+ }
928
+ return { attrs, dependsOn: buildDependsOn(attrs) };
929
+ }
930
+
931
+ /** depends_on:逗号分隔,去空、去重、保序。 */
932
+ function buildDependsOn(attrs: Record<string, string>): string[] {
933
+ const dependsOn: string[] = [];
934
+ if (attrs['depends_on'] === undefined) return dependsOn;
935
+ const seen = new Set<string>();
936
+ for (const part of attrs['depends_on'].split(',')) {
937
+ const d = part.trim();
938
+ if (d === '' || seen.has(d)) continue;
939
+ seen.add(d);
940
+ dependsOn.push(d);
941
+ }
942
+ return dependsOn;
943
+ }
944
+
945
+ type HeaderParse =
946
+ | { name: TfCommandName; attrs: Record<string, string>; dependsOn: readonly string[] }
947
+ | { name: null; attrs: Record<string, string>; dependsOn: readonly string[] }
948
+ | { error: string };
949
+
950
+ /**
951
+ * 解析头部原文(形如 `<tf-read path="a.ts" id="r1"/>`)。
952
+ * 自闭合与否由调用方判定,这里只取名字与属性;schema 校验失败返回 error。
953
+ */
954
+ function parseHeader(raw: string): HeaderParse {
955
+ // 去掉 '<'、结尾的 '>' 或 '/>'
956
+ let inner = raw.slice(1);
957
+ if (inner.endsWith('/>')) inner = inner.slice(0, -2);
958
+ else if (inner.endsWith('>')) inner = inner.slice(0, -1);
959
+
960
+ const nameMatch = inner.match(/^tf-[a-z]+/);
961
+ if (!nameMatch) return { error: 'bad-command-name' };
962
+ const nameCandidate = nameMatch[0];
963
+ const known = COMMAND_NAMES.find((n) => n === nameCandidate) ?? null;
964
+
965
+ let rest = inner.slice(nameCandidate.length);
966
+ const attrs: Record<string, string> = {};
967
+ for (;;) {
968
+ const ws = rest.match(/^\s+/);
969
+ if (ws) {
970
+ rest = rest.slice(ws[0].length);
971
+ continue;
972
+ }
973
+ if (rest === '') break;
974
+ const attr = rest.match(/^([a-zA-Z][a-zA-Z0-9_-]*)\s*=\s*"([^"]*)"/);
975
+ if (!attr) return { error: `bad-attribute-syntax:${rest.slice(0, 20)}` };
976
+ const key = attr[1];
977
+ if (key in attrs) return { error: `duplicate-attribute:${key}` };
978
+ attrs[key] = decodeXmlEntities(attr[2]);
979
+ rest = rest.slice(attr[0].length);
980
+ }
981
+
982
+ // depends_on:逗号分隔,去空、去重、保序
983
+ const dependsOn = buildDependsOn(attrs);
984
+
985
+ if (known === null) return { name: null, attrs, dependsOn };
986
+
987
+ const validated = validateCommandAttrs(known, attrs);
988
+ if ('error' in validated) return { error: validated.error };
989
+ return { name: known, attrs: validated.attrs, dependsOn: validated.dependsOn };
990
+ }
991
+
992
+ /**
993
+ * 判定 ground 模式下 '<' 起始的文本是否是协议标签的开始。
994
+ * need-more:数据不足以判定,等待下一个 chunk。
995
+ */
996
+ function probeTag(s: string): TagProbe {
997
+ if (!s.startsWith('<')) return 'prose';
998
+ if (s.length === 1) return 'need-more';
999
+ // DSML 噪声(v0.3.1):"<" 后直接跟全角竖线(U+FF5C)——协议没有任何合法形式以
1000
+ // "<|"(或 "</|")开头,无需等待更多数据即可判定(不再作为 prose 透传)。
1001
+ if (s[1] === '|' || (s[1] === '/' && s[2] === '|')) return 'dsml';
1002
+ // 孤立闭合标签(v0.3.1 截断修复):'</tf-xxx>' 只在 body 模式由 stepBody 消费;
1003
+ // 出现在 ground = 没有配对打开。判 'close-tag' 后调用方记账丢弃(绝不落进 prose)。
1004
+ // 必须放在已知命令名扫描之前:'</tf-' 永远不匹配 '<tf-' 候选,留到最后会被误判 prose。
1005
+ if (s.startsWith('</')) {
1006
+ if ('</tf-'.startsWith(s)) return 'need-more'; // '</' / '</t' / '</tf' / '</tf-':闭合标签开头
1007
+ if (/^<\/tf-[a-z0-9-]*\s*>/.test(s)) return 'close-tag';
1008
+ if (/^<\/tf-?[a-z0-9-]*$/.test(s)) return 'need-more'; // 还没等到 '>'
1009
+ return 'prose'; // '</div>' 之类:确属正文
1010
+ }
1011
+ for (const name of COMMAND_NAMES) {
1012
+ const open = `<${name}`;
1013
+ if (s.length <= open.length) {
1014
+ // 还没长过这个候选:仍是其前缀 → 待定;已分叉 → 换下一个候选
1015
+ if (open.startsWith(s)) return 'need-more';
1016
+ continue;
1017
+ }
1018
+ if (s.startsWith(open)) {
1019
+ const c = s[open.length];
1020
+ if (c === ' ' || c === '\t' || c === '\n' || c === '\r' || c === '/' || c === '>') {
1021
+ return 'tag';
1022
+ }
1023
+ // 该候选名后跟了非法字符(如 '<tf-writex')→ 换下一个候选(实际不会命中)
1024
+ }
1025
+ }
1026
+ if (s.startsWith('<tf-')) {
1027
+ // tf- 前缀但不是已知名,且已长到足以排除所有候选 → 协议尝试失败
1028
+ //(若仍是某个已知名的前缀,上面的循环已返回 need-more)
1029
+ return 'tf-unknown';
1030
+ }
1031
+ return 'prose';
1032
+ }
1033
+
1034
+ // ---------------------------------------------------------------------------
1035
+ // 便捷入口:AsyncIterable<string> → 事件列表
1036
+ // ---------------------------------------------------------------------------
1037
+
1038
+ /** 整流解析(测试/重放用)。生产路径走 feed()/end() 以便闭合即派发。 */
1039
+ export async function parseStream(src: AsyncIterable<string>): Promise<ParserEvent[]> {
1040
+ const parser = new TfStreamParser();
1041
+ const events: ParserEvent[] = [];
1042
+ for await (const delta of src) {
1043
+ events.push(...parser.feed(delta));
1044
+ }
1045
+ events.push(...parser.end());
1046
+ return events;
1047
+ }
1048
+
1049
+ // ---------------------------------------------------------------------------
1050
+ // tf-edit body 的标记切分(F1;纯函数,映射层与测试共用)
1051
+ // ---------------------------------------------------------------------------
1052
+
1053
+ /** tf-edit body 的三行标记(各占一行;正文里恰好出现该行时按结构化失败处理,不猜测)。 */
1054
+ export const TF_EDIT_MARKERS = { old: '<<<<<<< OLD', split: '=======', end: '>>>>>>> NEW' } as const;
1055
+
1056
+ export interface EditBodySplit {
1057
+ /** 待替换的精确字面量(宿主 edit 的 old_string)。 */
1058
+ old: string;
1059
+ /** 替换后的字面量(宿主 edit 的 new_string)。 */
1060
+ new: string;
1061
+ }
1062
+
1063
+ /**
1064
+ * 切分 tf-edit body:`<<<<<<< OLD` 与 `>>>>>>> NEW` 两行之间以 `=======` 行为界,
1065
+ * 前段 = old、后段 = new。标记行必须各出现一次且顺序正确;正文换行结构原样保留。
1066
+ * 解析失败返回 null(调用方必须回结构化失败,不得静默改成全文重写)。
1067
+ */
1068
+ export function splitEditBody(body: string): EditBodySplit | null {
1069
+ const lines = body.split('\n');
1070
+ const idxOld = lines.indexOf(TF_EDIT_MARKERS.old);
1071
+ const idxSplit = lines.indexOf(TF_EDIT_MARKERS.split);
1072
+ const idxEnd = lines.indexOf(TF_EDIT_MARKERS.end);
1073
+ if (idxOld === -1 || idxSplit === -1 || idxEnd === -1) return null;
1074
+ if (!(idxOld < idxSplit && idxSplit < idxEnd)) return null;
1075
+ if (lines.indexOf(TF_EDIT_MARKERS.old, idxOld + 1) !== -1) return null;
1076
+ if (lines.indexOf(TF_EDIT_MARKERS.split, idxSplit + 1) !== -1) return null;
1077
+ if (lines.indexOf(TF_EDIT_MARKERS.end, idxEnd + 1) !== -1) return null;
1078
+ const old = lines.slice(idxOld + 1, idxSplit).join('\n');
1079
+ const $new = lines.slice(idxSplit + 1, idxEnd).join('\n');
1080
+ return { old, new: $new };
1081
+ }