@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,289 @@
1
+ #!/usr/bin/env node
2
+ // entry/control-bar-cli.ts —— 控制栏命令行(v0.2.1)
3
+ //
4
+ // dsh-stream-agent 进入交互控制栏(TTY)
5
+ // dsh-stream-agent bar 同上(显式)
6
+ // dsh-stream-agent bar --once 打印一次面板就退出(非 TTY 自动如此)
7
+ // dsh-stream-agent status 一行状态(--json 输出机器可读)
8
+ // dsh-stream-agent mode lean 直接切模式(balanced / lean / compat / power)
9
+ // dsh-stream-agent lang en 直接切语言(zh / en)
10
+ // dsh-stream-agent help 全模式指南
11
+ //
12
+ // 交互键位:1-4 选模式 · ↑↓/jk 移动 · Enter 应用 · l 中/英 · ? 帮助 · r 重置 · q 退出
13
+ //
14
+ // 零依赖:只用 node:process 与内核渲染(kernel/control-bar.ts 是唯一输出源,
15
+ // 保证 CLI 与插件装载横幅的中英文案、宽度、语义完全一致)。
16
+
17
+ import { readdirSync } from 'node:fs';
18
+ import { MODES, getMode, isModeId } from '../kernel/modes.ts';
19
+ import {
20
+ createControlState,
21
+ isLang,
22
+ renderBanner,
23
+ renderHelp,
24
+ renderJson,
25
+ renderPanel,
26
+ renderStatusBar,
27
+ t,
28
+ } from '../kernel/control-bar.ts';
29
+ import type { ControlState, Lang } from '../kernel/control-bar.ts';
30
+ import { VERSION } from '../version.ts';
31
+ import { controlFileOf, readPersistedControl, writePersistedControl } from './control-state.ts';
32
+ import { ControlSession } from './control-session.ts';
33
+ import { resolveStateDir } from './json-persistence.ts';
34
+ import { appendIntentRecord, intentFileOf, loadIntentRecords, pendingIntents } from './intent-log.ts';
35
+
36
+ const CLEAR = '\x1b[2J\x1b[H';
37
+
38
+ function columns(): number {
39
+ return process.stdout.columns ?? 80;
40
+ }
41
+
42
+ function loadState(): ControlState {
43
+ const { state } = readPersistedControl();
44
+ return createControlState(state);
45
+ }
46
+
47
+ function save(state: ControlState): string {
48
+ return writePersistedControl(state);
49
+ }
50
+
51
+ function print(lines: readonly string[]): void {
52
+ process.stdout.write(`${lines.join('\n')}\n`);
53
+ }
54
+
55
+ function usage(lang: Lang): string[] {
56
+ const zh = lang === 'zh';
57
+ return [
58
+ zh ? '用法' : 'Usage',
59
+ ' dsh-stream-agent [bar] [--once] [--json] ' + (zh ? '控制栏(交互 / 一次性)' : 'control bar (interactive / once)'),
60
+ ' dsh-stream-agent status [--json] ' + (zh ? '当前模式与语言' : 'current mode and language'),
61
+ ' dsh-stream-agent mode <balanced|lean|compat|power>',
62
+ ' dsh-stream-agent lang <zh|en>',
63
+ ' dsh-stream-agent intents [--ack <sessionId>] ' + (zh ? 'F6 意图核对:列出"有意图无回执"(--ack 人工确认后闭合)' : 'F6 intent triage: list intents without receipts (--ack to close)'),
64
+ ' dsh-stream-agent help ' + (zh ? '全模式指南' : 'full mode guide'),
65
+ '',
66
+ zh ? '状态文件' : 'State file',
67
+ ` ${controlFileOf()}`,
68
+ '',
69
+ zh
70
+ ? '发布提示:v0.2.1 的 npm 源最多 3 天内可用;在此之前请用仓库路径安装'
71
+ : 'Release note: the v0.2.1 npm source lands within 3 days; install from the repo path until then',
72
+ ];
73
+ }
74
+
75
+ // ---------------------------------------------------------------------------
76
+ // 交互模式
77
+ // ---------------------------------------------------------------------------
78
+
79
+ function runInteractive(initial: ControlState): void {
80
+ const session = new ControlSession(initial, {
81
+ save: (next) => save(next),
82
+ columns: () => process.stdout.columns,
83
+ });
84
+
85
+ const draw = (): void => {
86
+ process.stdout.write(session.frame());
87
+ };
88
+
89
+ const stdin = process.stdin;
90
+ stdin.setRawMode?.(true);
91
+ stdin.resume();
92
+ stdin.setEncoding('utf8');
93
+
94
+ draw();
95
+
96
+ let finished = false;
97
+ const cleanup = (): void => {
98
+ if (finished) return;
99
+ finished = true;
100
+ stdin.off('data', onData);
101
+ stdin.setRawMode?.(false);
102
+ stdin.pause();
103
+ process.stdout.write(`${CLEAR}${renderStatusBar(session.state, { version: VERSION })}\n`);
104
+ process.exit(0);
105
+ };
106
+
107
+ function onData(chunk: string): void {
108
+ for (const key of splitKeys(chunk)) {
109
+ const result = session.handle(key);
110
+ if (result.quit) {
111
+ cleanup();
112
+ return;
113
+ }
114
+ if (result.changed) draw();
115
+ }
116
+ }
117
+
118
+ process.on('SIGINT', cleanup);
119
+ stdin.on('data', onData);
120
+ }
121
+
122
+ /** 把一次 data chunk 拆成按键序列(方向键是 \x1b[A / \x1b[B 三字节)。 */
123
+ export function splitKeys(chunk: string): string[] {
124
+ const keys: string[] = [];
125
+ let i = 0;
126
+ while (i < chunk.length) {
127
+ if (chunk[i] === '\x1b' && chunk[i + 1] === '[' && i + 2 < chunk.length) {
128
+ keys.push(chunk.slice(i, i + 3));
129
+ i += 3;
130
+ continue;
131
+ }
132
+ keys.push(chunk[i]);
133
+ i += 1;
134
+ }
135
+ return keys;
136
+ }
137
+
138
+ // ---------------------------------------------------------------------------
139
+ // 命令分发
140
+ // ---------------------------------------------------------------------------
141
+
142
+ function main(argv: readonly string[]): number {
143
+ const args = [...argv];
144
+ const json = args.includes('--json');
145
+ const once = args.includes('--once');
146
+ const rest = args.filter((a) => a !== '--json' && a !== '--once');
147
+ const command = rest[0] ?? 'bar';
148
+ const state = loadState();
149
+
150
+ switch (command) {
151
+ case '--version':
152
+ case '-v':
153
+ case 'version':
154
+ process.stdout.write(`${VERSION}\n`);
155
+ return 0;
156
+
157
+ case '--help':
158
+ case '-h':
159
+ case 'help': {
160
+ // 帮助 = 全模式指南(新人真正要看的)+ 用法;不再重复引导横幅
161
+ print(renderHelp(state, { version: VERSION, columns: columns() }));
162
+ print(['', ...usage(state.lang)]);
163
+ return 0;
164
+ }
165
+
166
+ case 'status': {
167
+ if (json) {
168
+ process.stdout.write(`${renderJson(state, { version: VERSION })}\n`);
169
+ } else {
170
+ print([
171
+ renderStatusBar(state, { version: VERSION }),
172
+ `${t('docs', state.lang)}: README.md#control-bar`,
173
+ ]);
174
+ }
175
+ return 0;
176
+ }
177
+
178
+ case 'mode': {
179
+ const target = rest[1];
180
+ if (target === undefined) {
181
+ print([`${t('mode', state.lang)}: ${MODES.map((m) => `${m.order}=${m.id}`).join(' ')}`]);
182
+ return 1;
183
+ }
184
+ if (!isModeId(target)) {
185
+ print([t('unknownMode', state.lang)]);
186
+ return 2;
187
+ }
188
+ const next: ControlState = { ...state, mode: target };
189
+ const file = save(next);
190
+ if (json) {
191
+ process.stdout.write(`${renderJson(next, { version: VERSION })}\n`);
192
+ } else {
193
+ print([`${t('mode', state.lang)} → ${getMode(target).order} ${getMode(target).label[state.lang]}(${target})`,
194
+ `${t('saved', state.lang)}: ${file}`]);
195
+ }
196
+ return 0;
197
+ }
198
+
199
+ case 'lang': {
200
+ const target = rest[1];
201
+ if (!isLang(target)) {
202
+ print([t('unknownLang', state.lang)]);
203
+ return 2;
204
+ }
205
+ const next: ControlState = { ...state, lang: target };
206
+ save(next);
207
+ print([renderStatusBar(next, { version: VERSION, columns: columns() })]);
208
+ return 0;
209
+ }
210
+
211
+ case 'intents': {
212
+ // F6 停机核对出口:列出各会话"有意图无回执"(pending)与失败意图(failed);
213
+ // --ack <sessionId> 追加 ack 记录闭合全部 pending(人工确认"未发生/放弃"后执行)。
214
+ const stateRoot = resolveStateDir();
215
+ const intentsDir = `${stateRoot}/intents`;
216
+ const ackTarget = rest[1] === '--ack' ? rest[2] : undefined;
217
+ const zh = state.lang === 'zh';
218
+ let sessions: string[] = [];
219
+ try {
220
+ sessions = readdirSync(intentsDir).filter((f) => f.endsWith('.jsonl')).map((f) => f.replace(/\.jsonl$/, ''));
221
+ } catch {
222
+ sessions = [];
223
+ }
224
+ if (sessions.length === 0) {
225
+ print([zh ? '没有意图日志(无写入或 F6 未启用)。' : 'No intent logs (no writes, or F6 disabled).']);
226
+ return 0;
227
+ }
228
+ if (ackTarget !== undefined) {
229
+ const file = intentFileOf(stateRoot, ackTarget);
230
+ if (!sessions.includes(ackTarget)) {
231
+ print([zh ? `未知会话:${ackTarget}` : `Unknown session: ${ackTarget}`]);
232
+ return 2;
233
+ }
234
+ const { records } = loadIntentRecords(file);
235
+ const open = pendingIntents(records).filter((p) => p.state === 'pending');
236
+ if (open.length === 0) {
237
+ print([zh ? `会话 ${ackTarget} 没有待核对的意图。` : `Session ${ackTarget} has no pending intents.`]);
238
+ return 0;
239
+ }
240
+ appendIntentRecord(file, { type: 'ack', seq: records.length + 1, at: new Date().toISOString(), intentSeqs: open.map((p) => p.intent.seq), note: 'cli --ack' });
241
+ print([zh
242
+ ? `已确认 ${open.length} 条意图(会话 ${ackTarget}):下一次 resume 不再停机核对。`
243
+ : `Acked ${open.length} intent(s) for session ${ackTarget}: next resume will not halt.`]);
244
+ return 0;
245
+ }
246
+ const lines: string[] = [zh ? '写前意图核对(F6):' : 'Intent triage (F6):'];
247
+ for (const session of sessions) {
248
+ const { records, badLines } = loadIntentRecords(intentFileOf(stateRoot, session));
249
+ const pending = pendingIntents(records).filter((p) => p.state === 'pending');
250
+ const failed = pendingIntents(records).filter((p) => p.state === 'failed');
251
+ lines.push(` ${session}: ${zh ? '待核对' : 'pending'} ${pending.length} · ${zh ? '失败已闭合' : 'failed(closed)'} ${failed.length}${badLines > 0 ? ` · ${zh ? '坏行' : 'bad lines'} ${badLines}` : ''}`);
252
+ for (const p of pending) {
253
+ lines.push(` - [seq ${p.intent.seq}] ${p.intent.op} ${p.intent.path} (cmd=${p.intent.cmdId} fp=${p.intent.fingerprint} at=${p.intent.at})`);
254
+ }
255
+ }
256
+ lines.push('', zh
257
+ ? '待核对 = 写入可能已发生(进程在写入中被杀)。人工核对文件后:dsh-stream-agent intents --ack <sessionId> 闭合;'
258
+ : 'Pending = the write MAY have happened (process killed mid-write). Verify files, then run: dsh-stream-agent intents --ack <sessionId>');
259
+ print(lines);
260
+ return 0;
261
+ }
262
+
263
+ case 'bar': {
264
+ const interactive = process.stdin.isTTY === true && process.stdout.isTTY === true && !once;
265
+ if (!interactive) {
266
+ print(renderPanel(state, { version: VERSION, columns: columns() }));
267
+ if (process.stdin.isTTY !== true) print(['', ` ${t('notTty', state.lang)}`]);
268
+ return 0;
269
+ }
270
+ runInteractive(state);
271
+ return 0;
272
+ }
273
+
274
+ default:
275
+ print([`${t('usage', state.lang)}: dsh-stream-agent [bar|status|mode|lang|help]`, t('unknownMode', state.lang)]);
276
+ return 2;
277
+ }
278
+ }
279
+
280
+ const invokedDirectly = (process.argv[1] ?? '').endsWith('control-bar-cli.js')
281
+ || (process.argv[1] ?? '').endsWith('control-bar-cli.ts');
282
+
283
+ if (invokedDirectly) {
284
+ // 管道下游提前关闭(`| head`)不是错误:安静退出,别把 EPIPE 栈打到用户脸上
285
+ process.stdout.on('error', (error: { code?: string }) => {
286
+ if (error?.code === 'EPIPE') process.exit(0);
287
+ });
288
+ process.exitCode = main(process.argv.slice(2));
289
+ }
@@ -0,0 +1,123 @@
1
+ // entry/control-bar.ts —— 控制栏 entry(v0.2.1)
2
+ //
3
+ // 三件事,全部 fail-open:
4
+ // ① 装载时把控制栏打到 stderr:接管状态 + 当前模式 + 上手四步 + 打开方式。
5
+ // bundle 激活对 CLI 是静默的(v0.2.0 的教训:用户只看到一条 warning),
6
+ // 控制栏是插件"自证已装载 + 教怎么用"的唯一直观出口。
7
+ // ② 提供 ctx.streamAgentControl 服务:其它 entry / 诊断脚本可读当前模式与语言。
8
+ // ③ 状态与 loop 共用同一份 control.json(control-state.ts),改模式不需要重启。
9
+ //
10
+ // 红线:本 entry 不得因为"配置坏了"而装载失败。resolveControlState 全程 fail-open,
11
+ // 告警走 logger/stderr,绝不上抛(v0.2.1 事故链见 cordis-compat.ts)。
12
+
13
+ import { createControlState, renderBanner, renderStatusBar } from '../kernel/control-bar.ts';
14
+ import type { ControlState } from '../kernel/control-bar.ts';
15
+ import { getMode } from '../kernel/modes.ts';
16
+ import type { ModeId, ModeSpec } from '../kernel/modes.ts';
17
+ import { VERSION } from '../version.ts';
18
+ import { asPluginEffect } from './cordis-compat.ts';
19
+ import type { HostCtxLike } from './adapter-kit.ts';
20
+ import { resolveControlState, writePersistedControl } from './control-state.ts';
21
+ import { isTakeoverActive, onTakeover } from './takeover-registry.ts';
22
+
23
+ export interface ControlBarConfig {
24
+ /** 装配里写死的模式(优先于 control.json 与环境变量;一般留空交给控制栏) */
25
+ mode?: string;
26
+ /** 装配里写死的界面语言:zh | en */
27
+ lang?: string;
28
+ /** 打印装载横幅(默认 true;patch 里显式 false 可静音) */
29
+ announce?: boolean;
30
+ /** 状态根目录(与 loop 的 stateDir 保持一致;缺省 STREAM_AGENT_STATE_DIR → ~/.dsh-stream-agent) */
31
+ stateDir?: string;
32
+ /** 覆盖版本号(测试用;生产缺省 VERSION) */
33
+ version?: string;
34
+ }
35
+
36
+ export interface ControlBarService {
37
+ state(): ControlState;
38
+ mode(): ModeSpec;
39
+ setMode(mode: ModeId, persist?: boolean): ControlState;
40
+ setLang(lang: ControlState['lang'], persist?: boolean): ControlState;
41
+ statusLine(active?: boolean): string;
42
+ active(): boolean;
43
+ file: string;
44
+ }
45
+
46
+ export const name = 'stream-agent-control-bar';
47
+ export const inject: string[] = [];
48
+
49
+ export default function apply(ctx: HostCtxLike, config: ControlBarConfig = {}): ControlBarService & (() => void) {
50
+ const version = config.version ?? VERSION;
51
+ const warn = (message: string, detail?: unknown): void => {
52
+ const logger = (ctx.get?.('logger') ?? null) as { warn?(m: string): void } | null;
53
+ const text = `[control-bar] ${message}${detail === undefined ? '' : ` :: ${String(detail)}`}`;
54
+ if (logger?.warn !== undefined) logger.warn(text);
55
+ else console.error(text);
56
+ };
57
+
58
+ const resolved = resolveControlState({ mode: config.mode, lang: config.lang }, config.stateDir, warn);
59
+ let state: ControlState = createControlState({ mode: resolved.mode, lang: resolved.lang });
60
+ const file = resolved.file;
61
+
62
+ const persist = (): void => {
63
+ try {
64
+ writePersistedControl(state, config.stateDir);
65
+ } catch (error) {
66
+ warn(`控制栏状态写入失败(本次运行内仍然生效):${file}`, error);
67
+ }
68
+ };
69
+
70
+ const service: ControlBarService = {
71
+ state: () => ({ ...state }),
72
+ mode: () => getMode(state.mode),
73
+ setMode: (mode, shouldPersist = true) => {
74
+ state = { ...state, mode: getMode(mode).id };
75
+ if (shouldPersist) persist();
76
+ return { ...state };
77
+ },
78
+ setLang: (lang, shouldPersist = true) => {
79
+ state = { ...state, lang: lang === 'en' ? 'en' : 'zh' };
80
+ if (shouldPersist) persist();
81
+ return { ...state };
82
+ },
83
+ statusLine: (active) => renderStatusBar(state, {
84
+ version,
85
+ ...(active === undefined ? { active: isTakeoverActive() } : { active }),
86
+ columns: process.stderr.columns,
87
+ }),
88
+ active: () => isTakeoverActive(),
89
+ file,
90
+ };
91
+
92
+ // 横幅时机(不靠定时器猜):控制栏排在 loop 之前挂载,因此先订阅"接管成立"事件;
93
+ // 若 loop 已经接管(控制栏后挂载的组合),onTakeover 会立即回调。
94
+ // 兜底:若 1.5s 内没有任何接管(bundle 只挂了一半),打印一次"未接管",便于定位。
95
+ let printed = false;
96
+ const printBanner = (): void => {
97
+ if (printed) return;
98
+ printed = true;
99
+ const active = isTakeoverActive();
100
+ for (const line of renderBanner(state, { version, active, columns: process.stderr.columns })) console.error(line);
101
+ };
102
+ const announce = config.announce !== false && process.env.STREAM_AGENT_NO_BANNER !== '1';
103
+ const offTakeover = announce ? onTakeover(printBanner) : () => {};
104
+ const fallbackTimer = announce
105
+ ? setTimeout(printBanner, 1500)
106
+ : undefined;
107
+ fallbackTimer?.unref?.();
108
+
109
+ // 服务提供是可选能力:宿主没有 provide(或已被占用)时只告警,不影响装载。
110
+ try {
111
+ if (typeof ctx.provide === 'function') ctx.provide('streamAgentControl', service);
112
+ } catch (error) {
113
+ warn('ctx.provide(streamAgentControl) 失败(其余功能不受影响)', error);
114
+ }
115
+
116
+ return asPluginEffect({
117
+ ...service,
118
+ dispose: () => {
119
+ offTakeover();
120
+ if (fallbackTimer !== undefined) clearTimeout(fallbackTimer);
121
+ },
122
+ });
123
+ }
@@ -0,0 +1,115 @@
1
+ // entry/control-session.ts —— 交互栏的会话状态机(v0.2.1)
2
+ //
3
+ // 把"按键 → 状态 → 画面"从终端 IO 里剥出来:runInteractive 只负责 raw mode 与写 stdout,
4
+ // 状态机本身可被 node --test 直接驱动(无需 pty),中英切换与落盘行为因此可被钉死。
5
+ //
6
+ // 一次 handle() 的返回值:
7
+ // { quit: true } 调用方收尾退出
8
+ // { changed: true } 画面需要重绘(状态变了)
9
+ // { changed: false } 按键无副作用(未知键)
10
+
11
+ import { DEFAULT_MODE, getMode } from '../kernel/modes.ts';
12
+ import type { ModeId } from '../kernel/modes.ts';
13
+ import { createControlState, interpretKey, moveFocus, otherLang, renderHelp, renderPanel, t } from '../kernel/control-bar.ts';
14
+ import type { ControlState, Lang } from '../kernel/control-bar.ts';
15
+ import { VERSION } from '../version.ts';
16
+
17
+ export interface ControlSessionDeps {
18
+ /** 落盘当前状态;返回文件路径(失败抛错,由会话转成一行提示) */
19
+ save(state: ControlState): string;
20
+ /** 终端列数(undefined = 未知,按默认宽度排版) */
21
+ columns(): number | undefined;
22
+ version?: string;
23
+ }
24
+
25
+ export class ControlSession {
26
+ state: ControlState;
27
+ focus: ModeId;
28
+ helpOpen = false;
29
+ note = '';
30
+ readonly #deps: ControlSessionDeps;
31
+
32
+ constructor(initial: ControlState, deps: ControlSessionDeps) {
33
+ this.state = createControlState(initial);
34
+ this.focus = this.state.mode;
35
+ this.#deps = deps;
36
+ }
37
+
38
+ get version(): string {
39
+ return this.#deps.version ?? VERSION;
40
+ }
41
+
42
+ /** 整屏文本(含清屏序列),直接 write 即可。 */
43
+ frame(): string {
44
+ const columns = this.#deps.columns();
45
+ const body = this.helpOpen
46
+ ? renderHelp(this.state, { version: this.version, columns })
47
+ : renderPanel(this.state, { version: this.version, columns, focus: this.focus });
48
+ const footer = this.note === '' ? [] : ['', ` ${this.note}`];
49
+ return `\x1b[2J\x1b[H${[...body, ...footer].join('\n')}\n`;
50
+ }
51
+
52
+ /** 应用一个模式并落盘(digit / Enter / r 共用)。 */
53
+ applyMode(mode: ModeId): void {
54
+ this.state = { ...this.state, mode: getMode(mode).id };
55
+ this.focus = this.state.mode;
56
+ const lang = this.state.lang;
57
+ try {
58
+ const file = this.#deps.save(this.state);
59
+ const spec = getMode(mode);
60
+ this.note = `${t('saved', lang)}: ${t('mode', lang)} ${spec.order} ${spec.label[lang]} | ${file}`;
61
+ } catch (error) {
62
+ this.note = `${t('writeFailed', lang)}: ${String(error)}`;
63
+ }
64
+ }
65
+
66
+ /** 切语言并落盘:中英两个方向都必须即时反映到画面与盘上。 */
67
+ toggleLang(): void {
68
+ this.state = { ...this.state, lang: otherLang(this.state.lang) as Lang };
69
+ try {
70
+ this.#deps.save(this.state);
71
+ this.note = t(this.state.lang === 'zh' ? 'noteLangZh' : 'noteLangEn', this.state.lang);
72
+ } catch (error) {
73
+ this.note = `${t('writeFailed', this.state.lang)}: ${String(error)}`;
74
+ }
75
+ }
76
+
77
+ /** 重置:模式回默认,语言保持不变(语言是阅读偏好,不该被"重置模式"带走)。 */
78
+ reset(): void {
79
+ this.applyMode(DEFAULT_MODE);
80
+ }
81
+
82
+ handle(key: string): { quit: boolean; changed: boolean } {
83
+ const action = interpretKey(key, { helpOpen: this.helpOpen });
84
+ switch (action.kind) {
85
+ case 'quit':
86
+ return { quit: true, changed: false };
87
+ case 'toggle-help':
88
+ this.helpOpen = !this.helpOpen;
89
+ this.note = '';
90
+ return { quit: false, changed: true };
91
+ case 'close-help':
92
+ this.helpOpen = false;
93
+ this.note = '';
94
+ return { quit: false, changed: true };
95
+ case 'toggle-lang':
96
+ this.toggleLang();
97
+ return { quit: false, changed: true };
98
+ case 'reset':
99
+ this.reset();
100
+ return { quit: false, changed: true };
101
+ case 'move':
102
+ this.focus = moveFocus(this.focus, action.delta);
103
+ this.note = '';
104
+ return { quit: false, changed: true };
105
+ case 'apply':
106
+ this.applyMode(this.focus);
107
+ return { quit: false, changed: true };
108
+ case 'select':
109
+ this.applyMode(action.mode);
110
+ return { quit: false, changed: true };
111
+ default:
112
+ return { quit: false, changed: false };
113
+ }
114
+ }
115
+ }
@@ -0,0 +1,125 @@
1
+ // entry/control-state.ts —— 控制栏状态的落盘与解析(v0.2.1)
2
+ //
3
+ // 状态只有一个文件:<stateDir>/control.json(默认 ~/.dsh-stream-agent/control.json,
4
+ // STREAM_AGENT_STATE_DIR 可改)。内容刻意极小,便于用户手改与排障:
5
+ // { "mode": "balanced", "lang": "zh", "updatedAt": "2026-11-16T13:00:00.000Z", "schema": 1 }
6
+ //
7
+ // 读写纪律:
8
+ // · 读:任何异常(不存在 / 坏 JSON / 未知模式)一律 fail-open 回默认值,并给出可选告警。
9
+ // 插件装载期不能因为一个"配置文件坏了"而失败——这是 v0.2.0 事故的直接教训。
10
+ // · 写:先写临时文件再 rename(原子替换),避免半截文件。
11
+ // · 优先级(高 → 低):装配显式 config > 环境变量 > control.json > 内置默认。
12
+ // 显式配置永远压过控制栏,模式只是"给没写配置的人一个好默认"。
13
+
14
+ import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
15
+ import { join } from 'node:path';
16
+ import { DEFAULT_LANG, isLang } from '../kernel/control-bar.ts';
17
+ import type { ControlState, Lang } from '../kernel/control-bar.ts';
18
+ import { DEFAULT_MODE, isModeId } from '../kernel/modes.ts';
19
+ import type { ModeId } from '../kernel/modes.ts';
20
+ import { resolveStateDir } from './json-persistence.ts';
21
+
22
+ export const CONTROL_SCHEMA = 1;
23
+ export const CONTROL_FILE = 'control.json';
24
+
25
+ export interface PersistedControl {
26
+ schema: number;
27
+ mode: ModeId;
28
+ lang: Lang;
29
+ updatedAt: string;
30
+ }
31
+
32
+ export interface ControlStateWithSource extends ControlState {
33
+ /** 值从哪来:排障时一眼看出"为什么是这个模式"(runtime = 本次进程内改过但没落盘) */
34
+ modeSource: 'config' | 'env' | 'file' | 'default' | 'runtime';
35
+ /** 语言同源诊断(桌面控制页据此判断"能不能在界面里改") */
36
+ langSource: 'config' | 'env' | 'file' | 'default' | 'runtime';
37
+ file: string;
38
+ }
39
+
40
+ export function controlFileOf(stateDir?: string): string {
41
+ return join(resolveStateDir(stateDir), CONTROL_FILE);
42
+ }
43
+
44
+ /** 读取落盘状态;文件缺失/损坏/字段非法一律回默认(不抛错)。 */
45
+ export function readPersistedControl(
46
+ stateDir?: string,
47
+ onWarning?: (message: string, detail?: unknown) => void,
48
+ ): { state: ControlState; found: boolean; file: string; updatedAt?: string } {
49
+ const file = controlFileOf(stateDir);
50
+ const fallback: ControlState = { mode: DEFAULT_MODE, lang: DEFAULT_LANG };
51
+ if (!existsSync(file)) return { state: fallback, found: false, file };
52
+ try {
53
+ const raw = JSON.parse(readFileSync(file, 'utf8')) as Partial<PersistedControl>;
54
+ const state: ControlState = {
55
+ mode: isModeId(raw.mode) ? raw.mode : fallback.mode,
56
+ lang: isLang(raw.lang) ? raw.lang : fallback.lang,
57
+ };
58
+ return {
59
+ state,
60
+ found: true,
61
+ file,
62
+ updatedAt: typeof raw.updatedAt === 'string' ? raw.updatedAt : undefined,
63
+ };
64
+ } catch (error) {
65
+ // 坏文件不阻断装载,也不静默:告警后回默认值(下次写入会修复它)
66
+ onWarning?.(`控制栏状态文件不可解析,已回默认模式/语言:${file}`, error);
67
+ return { state: fallback, found: false, file };
68
+ }
69
+ }
70
+
71
+ /** 原子写入(tmp + rename);返回落盘路径。失败抛错由 CLI 呈现给用户。 */
72
+ export function writePersistedControl(state: ControlState, stateDir?: string): string {
73
+ const file = controlFileOf(stateDir);
74
+ mkdirSync(resolveStateDir(stateDir), { recursive: true });
75
+ const payload: PersistedControl = {
76
+ schema: CONTROL_SCHEMA,
77
+ mode: state.mode,
78
+ lang: state.lang,
79
+ updatedAt: new Date().toISOString(),
80
+ };
81
+ const tmp = `${file}.${process.pid}.tmp`;
82
+ writeFileSync(tmp, `${JSON.stringify(payload, null, 2)}\n`, 'utf8');
83
+ renameSync(tmp, file);
84
+ return file;
85
+ }
86
+
87
+ /**
88
+ * 解析生效状态:显式 config → 环境变量 → 落盘 → 默认。
89
+ *
90
+ * @param explicit 装配里写死的值(LoopEntryConfig.mode / .lang;undefined 表示没写)
91
+ * @param stateDir 状态根目录(与 loop 的 stateDir 配置保持一致)
92
+ */
93
+ export function resolveControlState(
94
+ explicit: { mode?: string; lang?: string } = {},
95
+ stateDir?: string,
96
+ onWarning?: (message: string, detail?: unknown) => void,
97
+ ): ControlStateWithSource {
98
+ const persisted = readPersistedControl(stateDir, onWarning);
99
+ const envMode = process.env.STREAM_AGENT_MODE;
100
+ const envLang = process.env.STREAM_AGENT_LANG;
101
+
102
+ let mode = persisted.state.mode;
103
+ let modeSource: ControlStateWithSource['modeSource'] = persisted.found ? 'file' : 'default';
104
+ if (isModeId(envMode)) {
105
+ mode = envMode;
106
+ modeSource = 'env';
107
+ }
108
+ if (isModeId(explicit.mode)) {
109
+ mode = explicit.mode;
110
+ modeSource = 'config';
111
+ }
112
+
113
+ let lang = persisted.state.lang;
114
+ let langSource: ControlStateWithSource['langSource'] = persisted.found ? 'file' : 'default';
115
+ if (isLang(envLang)) {
116
+ lang = envLang;
117
+ langSource = 'env';
118
+ }
119
+ if (isLang(explicit.lang)) {
120
+ lang = explicit.lang;
121
+ langSource = 'config';
122
+ }
123
+
124
+ return { mode, lang, modeSource, langSource, file: persisted.file };
125
+ }