@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.
Files changed (158) hide show
  1. package/CHANGELOG.md +497 -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 +3852 -0
  19. package/dist/entry/mock-provider.js +536 -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 +632 -0
  30. package/dist/kernel/render.js +444 -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 +415 -0
  87. package/scripts/repair-session-logs.mjs +403 -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 +3852 -0
  100. package/src/entry/mock-provider.ts +536 -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 +632 -0
  111. package/src/kernel/render.ts +444 -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/kernel/obs.test.ts +329 -0
  126. package/test/kernel/parser.test.ts +450 -0
  127. package/test/loop.test.ts +1393 -0
  128. package/test/mock-provider.test.ts +386 -0
  129. package/test/ptc-bridge.test.ts +356 -0
  130. package/test/render.test.ts +418 -0
  131. package/test/s2-install-check.test.ts +46 -0
  132. package/test/scenarios/3-file-basic.json +13 -0
  133. package/test/scenarios/5-file-basic.json +22 -0
  134. package/test/scenarios/burn-more.json +9 -0
  135. package/test/scenarios/degraded-final.json +10 -0
  136. package/test/scenarios/fault-abort-xml.json +11 -0
  137. package/test/scenarios/fault-malformed-command.json +12 -0
  138. package/test/scenarios/fault-midstream-abort.json +11 -0
  139. package/test/scenarios/fault-saturating-output.json +9 -0
  140. package/test/scenarios/fault-timeout.json +9 -0
  141. package/test/scenarios/peek-first.json +11 -0
  142. package/test/scenarios/peek-second.json +11 -0
  143. package/test/scenarios/peek-third.json +10 -0
  144. package/test/scenarios/recover-final.json +10 -0
  145. package/test/scenarios/reroute-first.json +17 -0
  146. package/test/scenarios/reroute-second.json +16 -0
  147. package/test/scenarios/starvation-final.json +10 -0
  148. package/test/scenarios/starvation-promote.json +11 -0
  149. package/test/scenarios/wait-tools-continue.json +10 -0
  150. package/test/scenarios/wait-tools-xml.json +22 -0
  151. package/test/scenarios/wait-tools.json +15 -0
  152. package/test/session-format.test.ts +234 -0
  153. package/test/state.test.ts +335 -0
  154. package/test/stream-v02.test.ts +264 -0
  155. package/test/v031-display.test.ts +333 -0
  156. package/ui/client.js +576 -0
  157. package/ui/index.js +282 -0
  158. package/ui/package.json +26 -0
@@ -0,0 +1,253 @@
1
+ // kernel/modes.ts : 插件运行模式目录(v0.2.1 控制栏的事实来源)
2
+ //
3
+ // 设计约束:
4
+ // 1. 零框架依赖:不 import 任何 @deepseek-ai/*,也不碰 fs : 拷出 kernel/ 可单测。
5
+ // 2. 每个模式只映射**已存在**的驱动器/入口配置项(selfReadFeedback、enableCode、
6
+ // persistFallback、maxParallelToolCalls、maxReentries、budgetTokens),
7
+ // 不新增运行期行为:模式是"给新人看的预设",不是第二套开关。
8
+ // 3. 四种模式覆盖同一条权衡轴:省 token ↔ 可读/可排障。
9
+ // balanced 与 v0.2.0 的出厂默认逐项等价(唯一的例外是显式写死,见下)。
10
+ //
11
+ // 为什么是四个:新用户只需要回答两个问题:"我要不要极限省钱"、"我要不要程序化
12
+ // 数据加工"。两个问题给出四象限,正好四种模式;再多就需要读文档了,与"帮新人上手"
13
+ // 的目标相反。
14
+
15
+ export const MODE_IDS = ['balanced', 'lean', 'compat', 'power'] as const;
16
+ export type ModeId = (typeof MODE_IDS)[number];
17
+
18
+ export const DEFAULT_MODE: ModeId = 'balanced';
19
+
20
+ /**
21
+ * 相对省 token 幅度(定性档位,不是百分比)。
22
+ *
23
+ * 为什么不写死百分比:只有"默认参数 vs 原生 loop"有过两臂实测(v0.1.0,十任务,
24
+ * 约 29%),其余模式没有单独评测。把没测过的幅度写成百分比比不写更糟——用户会拿它
25
+ * 做预算。所以这里只给方向与档位,定量证据在 note 里注明来源与"未单独实测"。
26
+ */
27
+ export type ModeSaving = 'most' | 'more' | 'baseline' | 'least';
28
+
29
+ /** 可用性:默认模式 / 开箱可用 / 依赖宿主能力。 */
30
+ export type ModeAvailability = 'default' | 'ready' | 'needs-ptc';
31
+
32
+ export const SAVING_TEXT: Record<ModeSaving, { zh: string; en: string }> = {
33
+ most: { zh: '最高档(数据加工最省)', en: 'highest (best on data tasks)' },
34
+ more: { zh: '较高(比默认更省)', en: 'higher (more than default)' },
35
+ // 29% 是"用了原生 loop 的 29%",不是"省了 29%";行内写全,避免被反读。
36
+ baseline: { zh: '基准(约为原生 loop 的 29%)', en: 'baseline (29% of native loop)' },
37
+ least: { zh: '最低档(比默认略高)', en: 'lowest (above default)' },
38
+ };
39
+
40
+ export const AVAILABILITY_TEXT: Record<ModeAvailability, { zh: string; en: string }> = {
41
+ default: { zh: '默认模式,装好即用', en: 'Default, works out of the box' },
42
+ ready: { zh: '开箱可用,无前置', en: 'Ready, no prerequisites' },
43
+ 'needs-ptc': { zh: '需宿主 PTC(无则回落)', en: 'Needs host PTC (falls back)' },
44
+ };
45
+
46
+ /** 一个模式对驱动器配置的落点(字段名与 LoopEntryConfig / StreamDriverConfig 对齐)。 */
47
+ export interface ModeConfigPatch {
48
+ /** O7 自写回验:'receipt' = 读自己刚写过的文件只回回执;'full' = v0.1 全文回灌 */
49
+ selfReadFeedback: 'receipt' | 'full';
50
+ /** tf-code(PTC 桥接)。K1(0.3.0):默认关闭;'auto' 是 v0.2.0 的遗留值(等价 false,
51
+ * 不再由任何模式产出);true = 显式开启(power 模式或装配显式配置)。 */
52
+ enableCode: 'auto' | boolean;
53
+ /** 宿主缺 storage/sessionPersistence 时的本地文件兜底 */
54
+ persistFallback: boolean;
55
+ /** 独立命令并行度上限 */
56
+ maxParallelToolCalls: number;
57
+ /** 最大重入次数(防震荡护栏) */
58
+ maxReentries: number;
59
+ /** 任务级 token 预算(O5 阶梯分母);undefined = 阶梯关闭 */
60
+ budgetTokens?: number;
61
+ }
62
+
63
+ export interface ModeSpec {
64
+ id: ModeId;
65
+ /** 控制栏里的序号(1-4),按键直接选模式 */
66
+ order: number;
67
+ label: { zh: string; en: string };
68
+ /** 一句话是什么 */
69
+ tagline: { zh: string; en: string };
70
+ /** 什么时候选它(新人最需要的一列) */
71
+ useWhen: { zh: string; en: string };
72
+ /** 代价 / 需要注意什么 */
73
+ tradeoff: { zh: string; en: string };
74
+ /** 相对省 token 幅度(档位) */
75
+ saving: ModeSaving;
76
+ /** 可用性:默认 / 开箱 / 依赖宿主 PTC */
77
+ availability: ModeAvailability;
78
+ /** 额外标注:把"省多少、在什么前提下成立"讲清楚(含实测口径) */
79
+ note: { zh: string; en: string };
80
+ config: ModeConfigPatch;
81
+ }
82
+
83
+ export const MODES: readonly ModeSpec[] = [
84
+ {
85
+ id: 'balanced',
86
+ order: 1,
87
+ label: { zh: '均衡', en: 'Balanced' },
88
+ tagline: {
89
+ zh: '出厂默认:该省的省,该看的看得见。',
90
+ en: 'Factory default: saves where it is safe, keeps what you need to see.',
91
+ },
92
+ useWhen: {
93
+ zh: '第一次用,日常读写与查改任务、不确定选哪个时:先用它。',
94
+ en: 'First run, everyday read/write and lookup tasks, or when unsure: start here.',
95
+ },
96
+ tradeoff: {
97
+ zh: '写批任务仍会出现"读自己刚写的文件只回回执",需要全文时用 tf-peek 按行段取;tf-code 默认关闭(K1)。',
98
+ en: 'Write-batch tasks get a receipt instead of full echo when re-reading your own file; use tf-peek for line ranges. tf-code stays off by default (K1).',
99
+ },
100
+ saving: 'baseline',
101
+ availability: 'default',
102
+ note: {
103
+ zh: '不动任何配置就是它。相对原生 loop 实测约 29% token(v0.1.0 十任务两臂)。0.3.0 起 tf-code 默认关闭(协议不声明,K1);需要程序化加工选 power 模式或显式 enableCode: true。',
104
+ en: 'This is what you get without touching any config. Measured at ~29% of the native loop tokens (v0.1.0, 10 tasks, two arms). Since 0.3.0 tf-code is off by default (K1); pick power mode or set enableCode: true explicitly for programmatic data work.',
105
+ },
106
+ config: {
107
+ selfReadFeedback: 'receipt',
108
+ enableCode: false,
109
+ persistFallback: true,
110
+ maxParallelToolCalls: 3,
111
+ maxReentries: 8,
112
+ },
113
+ },
114
+ {
115
+ id: 'lean',
116
+ order: 2,
117
+ label: { zh: '精简', en: 'Lean' },
118
+ tagline: {
119
+ zh: '省钱优先:预算阶梯提前介入,注入更克制。',
120
+ en: 'Cost-first: the budget ladder engages early and injections stay minimal.',
121
+ },
122
+ useWhen: {
123
+ zh: '长会话、批量脚本、读查为主且答案明确的任务;token 账单敏感时。',
124
+ en: 'Long sessions, batch scripts, read-heavy tasks with a clear answer, or when the token bill matters.',
125
+ },
126
+ tradeoff: {
127
+ zh: '预算 60k 触发降级:70% 后只注高增益观测,90% 后只收 tf-final,可能牺牲细节。',
128
+ en: 'A 60k budget triggers degradation: after 70% only high-gain observations, after 90% only tf-final. Detail may suffer.',
129
+ },
130
+ saving: 'more',
131
+ availability: 'ready',
132
+ note: {
133
+ zh: '比默认更省:60k 阶梯 + 并行 2 + 不声明 tf-code,长会话差距最明显。未单独实测,属方向性判断。',
134
+ en: 'Saves more than the default: 60k ladder, parallelism 2, no tf-code. The gap widens in long sessions. Not separately benchmarked — this is a directional call.',
135
+ },
136
+ config: {
137
+ selfReadFeedback: 'receipt',
138
+ enableCode: false,
139
+ persistFallback: true,
140
+ maxParallelToolCalls: 2,
141
+ maxReentries: 6,
142
+ budgetTokens: 60_000,
143
+ },
144
+ },
145
+ {
146
+ id: 'compat',
147
+ order: 3,
148
+ label: { zh: '兼容', en: 'Compat' },
149
+ tagline: {
150
+ zh: '可读优先:最接近原生回合制的观感,命令串行执行。',
151
+ en: 'Visibility-first: closest to the native turn-based feel, commands run serially.',
152
+ },
153
+ useWhen: {
154
+ zh: '行为看着不对、要跟原生 loop 对照、第三方工具依赖完整读回时。',
155
+ en: 'Behavior looks off, you are diffing against the native loop, or a third-party tool needs full read-back.',
156
+ },
157
+ tradeoff: {
158
+ zh: 'token 最高:写后回验恢复全文注入,并行度降到 1,速度也更慢。',
159
+ en: 'Highest token cost: self-write read-back returns full text again and parallelism drops to 1, so it is slower.',
160
+ },
161
+ saving: 'least',
162
+ availability: 'ready',
163
+ note: {
164
+ zh: '省得最少:恢复全文回验、并行降到 1;即使如此仍低于原生 loop,因为单流协议本身在省。未单独实测。',
165
+ en: 'Saves least: full read-back is back and parallelism drops to 1. Even so it stays below the native loop — the single-stream protocol itself is where the saving comes from. Not separately benchmarked.',
166
+ },
167
+ config: {
168
+ selfReadFeedback: 'full',
169
+ enableCode: false,
170
+ persistFallback: true,
171
+ maxParallelToolCalls: 1,
172
+ maxReentries: 12,
173
+ },
174
+ },
175
+ {
176
+ id: 'power',
177
+ order: 4,
178
+ label: { zh: '增强', en: 'Power' },
179
+ tagline: {
180
+ zh: '程序化加工:单流里直接写 tf-code 程序处理重数据。',
181
+ en: 'Programmatic: write tf-code programs inside the single stream for heavy data.',
182
+ },
183
+ useWhen: {
184
+ zh: '多步数据加工(过滤/统计/变换/聚合)、大日志分析,且宿主机有 PTC runtime。',
185
+ en: 'Multi-step data work (filter/aggregate/transform) or large-log analysis, with a host PTC runtime available.',
186
+ },
187
+ tradeoff: {
188
+ zh: '宿主没有 ctx.ptcRuntime 时 tf-code 通道自动关闭(协议不声明);协议段更长,固定成本略高。',
189
+ en: 'Without ctx.ptcRuntime the tf-code channel stays off and is not declared; the protocol section is longer, so fixed cost is higher.',
190
+ },
191
+ saving: 'most',
192
+ availability: 'needs-ptc',
193
+ note: {
194
+ zh: '数据加工类任务省最多(结果句柄化,上限内首成功值完整注入,中间结果不进上下文);普通读写任务反而略高于默认。宿主无 PTC 时自动回落为默认参数。这是唯一显式开 tf-code 的模式(K1 默认关闭)。未单独实测。',
195
+ en: 'Saves most on data-processing tasks (results are handle-ized, first successful values within the cap are injected in full, intermediates never enter context); on plain read/write tasks it costs slightly more than the default. Falls back to default parameters without a host PTC runtime. The only mode that turns tf-code on explicitly (K1 default is off). Not separately benchmarked.',
196
+ },
197
+ config: {
198
+ selfReadFeedback: 'receipt',
199
+ enableCode: true,
200
+ persistFallback: true,
201
+ maxParallelToolCalls: 3,
202
+ maxReentries: 10,
203
+ },
204
+ },
205
+ ];
206
+
207
+ const BY_ID = new Map<string, ModeSpec>(MODES.map((m) => [m.id, m]));
208
+
209
+ /**
210
+ * 对外模式目录(终端 --json / 桌面页路由 / 页面渲染共用**同一份投影**)。
211
+ *
212
+ * 之前 loop 与 ui/index.js 各写一份 map,加字段时漏一处就会出现"CLI 有标注、页面没有"
213
+ * 的错位。投影只放展示需要的字段,`config` 不进网络载荷(页面不靠它推断行为)。
214
+ */
215
+ export function publicModeCatalog() {
216
+ return MODES.map(({ id, order, label, tagline, useWhen, tradeoff, saving, availability, note }) => ({
217
+ id,
218
+ order,
219
+ label,
220
+ tagline,
221
+ useWhen,
222
+ tradeoff,
223
+ saving,
224
+ savingLabel: SAVING_TEXT[saving],
225
+ availability,
226
+ availabilityLabel: AVAILABILITY_TEXT[availability],
227
+ note,
228
+ }));
229
+ }
230
+
231
+ export function isModeId(value: unknown): value is ModeId {
232
+ return typeof value === 'string' && BY_ID.has(value);
233
+ }
234
+
235
+ /** 取模式定义;未知值回落到默认模式(fail-open:控制栏永远渲染得出来)。 */
236
+ export function getMode(id: unknown): ModeSpec {
237
+ return (isModeId(id) ? BY_ID.get(id) : undefined) ?? BY_ID.get(DEFAULT_MODE)!;
238
+ }
239
+
240
+ /** 按序号取模式(1-4;越界返回 undefined)。 */
241
+ export function modeByOrder(order: number): ModeSpec | undefined {
242
+ return MODES.find((m) => m.order === order);
243
+ }
244
+
245
+ /**
246
+ * 模式 → 显式配置覆盖。
247
+ *
248
+ * 语义是"模式提供默认值",调用方用 `??` 让用户/装配显式写的值优先:
249
+ * 显式配置永远压过模式,模式压过代码内置默认。
250
+ */
251
+ export function modeConfig(id: unknown): ModeConfigPatch {
252
+ return { ...getMode(id).config };
253
+ }