@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
package/README.md CHANGED
@@ -1,3 +1,300 @@
1
- # Temporary Holding Version
2
-
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
1
+ # dsh-stream-agent
2
+
3
+ ![ci](https://github.com/54dsb1/dsh-stream-agent/actions/workflows/ci.yml/badge.svg)
4
+
5
+ ![license](https://img.shields.io/badge/license-Apache--2.0-blue.svg)
6
+
7
+ | | |
8
+ | -------- | ------------------------------------ |
9
+ | 简体中文 | [English](./README.en.md) |
10
+
11
+ **给 DeepSeek Harness 换一颗单流的心。** 把"模型看到什么、何时被打断"从回合制改成单流协议:
12
+ 一次请求内写完全部操作命令,边流边执行,只在真正需要信息时才发下一次请求。
13
+
14
+ 真连实测(10 任务、两臂同模型 `deepseek-flash`,2026-11-15-v02 批次,四分量口径由
15
+ `summarize.cjs` 复算):**token 用量降到原生 loop 的 28.9%,任务正确性持平**。
16
+ 历史批次的 22.3% 口径见 [eval/RESULTS.md](eval/RESULTS.md) §6 的如实说明——两批不可混用,
17
+ R3 重跑后以同批双臂复算为准。
18
+
19
+ | | |
20
+ | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
21
+ | 宿主 | DeepSeek Harness `0.2.2-rc.1`(类型锚点)/ `rc.3`(运行时实测) |
22
+ | 依赖 | 零 npm 依赖;Node ≥ 22.18(原生类型擦除) |
23
+ | 测试 | 275 用例全绿,零 API 调用(mock 全链路 + 20 个场景 + 装载/桌面页/新能力/会话格式回归) |
24
+ | 形态 | 单 bundle 包 + **专用 profile**(`profiles/stream` 模板);`dsh plugin remove` 整层消失、宿主 loop 原子恢复 |
25
+ | 控制栏 | `dsh-stream-agent bar`:四模式 + 中英切换 + 意图核对,装载时自动打印上手引导 |
26
+ | 桌面页 | 客户端左侧栏「控制栏 / Control bar」:状态 + 四模式 + 中英切换,**不改 Electron 壳** |
27
+ | 计量 | 四分量脚本出数 + 回放一致性对照臂 10/10 + 发布门禁 6 项 |
28
+ | 发布 | GitHub [Releases](https://github.com/54dsb1/dsh-stream-agent/releases) · npm `@hugesb/dsh-stream-agent` **尚未发布**(当前唯一安装路径见 §2) |
29
+
30
+ > **0.3.0 安装方式变更(重要)**:独立模式下本插件**只允许装进专用 profile**
31
+ > (`profiles/stream` / `profiles/stream-headless`)。0.2.x 的"plugin add 进既有
32
+ > profile"装法不再支持——安装前置校验会拒绝 `web` / `desktop`,双 loop 冲突以
33
+ > `E_DOUBLE_LOOP` 具名失败。迁移:删旧安装 → 建专用 profile → 重装(见 §2)。
34
+
35
+ ---
36
+
37
+ ## 1. 它解决什么问题
38
+
39
+ 原生 loop 是回合制的:每一步发一次请求,工具结果全量塞回上下文,模型看完再决定下一步。
40
+ 于是三件事同时发生——**请求次数多、观测重复回灌、前缀缓存被反复打断**。
41
+
42
+ 本插件把这一层接管掉,只改三件事:
43
+
44
+ 1. **单流** —— 模型在一次流里连续写完所有 `tf-*` 命令,解析器逐 chunk 解析、命令闭合即
45
+ 派发,独立命令并行执行,不等流结束。
46
+ 2. **观测不回灌** —— 工具产出默认只回句柄,模型要细节就发 `tf-peek` 按行段取回。注入量
47
+ 从"我们猜"变成"模型自己要"。
48
+ 3. **前缀单调** —— 上下文装配只做尾部追加,发请求前做逐字节断言,不单调就拒绝发送
49
+ (fail-closed),宁可任务失败也不烧缓存。
50
+
51
+ 不重训模型,不改上游源码,全部以 plugin entry + patch 形式存在。
52
+
53
+ ## 2. 安装:专用 profile(唯一支持形态)
54
+
55
+ ```bash
56
+ # 1) 复制专用 profile 模板(本地开发用 link:;npm 安装改精确版本号,不用 ^/~ 浮动范围)
57
+ cp -r profiles/stream ~/.dsh/profiles/stream
58
+
59
+ # 2) 安装前置校验(S2):只读检查;目标必须是 stream / stream-headless
60
+ node scripts/install-check.mjs --profile ~/.dsh/profiles/stream --dry-run
61
+
62
+ # 3) 启动自证:装载横幅应含 TAKEOVER-ACTIVE … code=off … profile=stream
63
+ dsh --profile stream
64
+
65
+ # 4) 装卸回归(可选,10 轮 add → 自证 → remove → 恢复验证)
66
+ node scripts/install-cycle.mjs --dsh dsh --profile stream --rounds 10
67
+
68
+ # 卸载:bundle 层整层消失,宿主 loop 原子恢复;彻底移除删 profile 目录
69
+ dsh plugin remove @hugesb/dsh-stream-agent --profile stream
70
+ ```
71
+
72
+ - headless 入口用 `profiles/stream-headless`(不引入 preset bundle:宿主 headless 无 preset
73
+ registry,工具面由 profile 决定)。
74
+ - 组合顺序 `dsh-base → 主 bundle → preset bundle → 入口` 是契约,改变顺序视为装配变更需
75
+ 重新验收;完整说明见 [profiles/stream/README.md](profiles/stream/README.md)。
76
+ - `agent-loop` 的停用**只在主 bundle 的 cordis.patch.yml**——`plugin remove` 整层消失、
77
+ 卸载原子(C4);profile 的 patch 层只承载 registry 默认值覆盖,永不接管 loop。
78
+ - 误装到 `web` / `desktop` 会被 `install-check` 拒绝;若绕过校验强行装入,宿主会以
79
+ `E_DOUBLE_LOOP`(带 profile 标识与处置建议)具名失败——不静默共存(C2/S3)。
80
+ - `dsh plugin` 依赖 `pnpm` 在 PATH 中(或按 dsh-plugin-manager 配置 `pnpmCommand`)。
81
+ - **旧会话日志(0.2.x 及 0.3.0 发布前的产物)**:0.3.0 起修正了会话日志的 v4 工具生命周期
82
+ 写入——此前写出的日志在桌面端点开历史对话会报"会话加载失败"
83
+ (`tool/call … has no advertised tool lifecycle`,宿主把整条日志判 corrupt,并非数据丢失)。
84
+ 升级后跑一次 `node scripts/repair-session-logs.mjs --write`(先不加 `--write` 看清单;
85
+ 写前自动备份 `.bak-<时间戳>`、写后清投影缓存),日志即可正常加载。
86
+
87
+ 开发/验证用的临时叠加(不进 profile)仍可用:
88
+ `dsh --profile headless --patch ./patches/takeover.yml headless "任务"`。
89
+
90
+ ## 3. 运行模式(控制栏四模式)
91
+
92
+ `dsh-stream-agent bar` 交互面板 / `dsh-stream-agent mode lean` / 桌面控制页三处同源
93
+ (同一份 `kernel/modes.ts`)。模式只提供默认值;**装配里显式写的配置永远压过模式**。
94
+
95
+ 省多少、能不能用(口径如实:只有「默认参数 vs 原生 loop」有十任务两臂实测约 29%,
96
+ 其余三档是方向性判断并明写"未单独实测"——不把没测过的数字写成百分比):
97
+
98
+ | 模式 | 省 token | 可用性 | 标注 |
99
+ | --- | --- | --- | --- |
100
+ | `balanced`(默认) | 基准(约为原生 loop 的 29%) | 默认模式,装好即用 | tf-code 默认关闭(K1);该省的省、该看的看得见 |
101
+ | `lean` | 较高(比默认更省) | 开箱可用 | 60k 阶梯 + 并行 2 + 不声明 tf-code;长会话差距最明显 |
102
+ | `compat` | 最低档(比默认略高) | 开箱可用 | 全文回验恢复、并行 1;即便如此仍低于原生 loop(单流协议本身在省) |
103
+ | `power` | 最高档(数据加工最省) | 需宿主 PTC runtime | **唯一显式开 tf-code 的模式**;普通读写反而略高于默认 |
104
+
105
+ 模式 → 配置对应(改模式 = 改这些值;显式配置 > 模式 > 内置默认):
106
+
107
+ | 模式 | `selfReadFeedback` | `enableCode` | `persistFallback` | 并行 | 重入 | `budgetTokens` |
108
+ | --- | --- | --- | --- | --- | --- | --- |
109
+ | `balanced` | `receipt` | `false` | `true` | 3 | 8 | — |
110
+ | `lean` | `receipt` | `false` | `true` | 2 | 6 | 60,000 |
111
+ | `compat` | `full` | `false` | `true` | 1 | 12 | — |
112
+ | `power` | `receipt` | `true` | `true` | 3 | 10 | — |
113
+
114
+ 一句话决策:**默认 `balanced`;账单敏感换 `lean`;排障对照换 `compat`;写程序处理数据换 `power`。**
115
+
116
+ ## 4. tf-* 协议(11 条命令)
117
+
118
+ 语法权威是 `src/kernel/parser.ts`;完整闭环语义见 [docs/protocol.md](docs/protocol.md)。
119
+
120
+ | 命令 | 作用 | 结果去向 |
121
+ | --- | --- | --- |
122
+ | `tf-write` | 写文件(body = 正文原文) | 成功只记台账,失败注入 `[tf-stream:error]` |
123
+ | `tf-read` | 读文件(可 offset/limit 行段) | 首次/变化完整注入(≤8000 字符截断保头尾);自写路径只回回执(行数+指纹,O7) |
124
+ | `tf-edit` | 精确替换(body 用 `<<<<<<< OLD` / `=======` / `>>>>>>> NEW` 标记块;映射宿主 edit) | 成功只记台账;匹配失败结构化报错,**不做模糊匹配、不静默改全文** |
125
+ | `tf-append` | 只追加(可选 anchor 锚点;映射宿主 edit / apply_patch 的 EOF 锚) | 成功只记台账;追加位置与换行规则确定 |
126
+ | `tf-grep` | 内容搜索(映射宿主 fs-search),只回匹配行(带行号) | 首次/变化完整注入;超限句柄化 |
127
+ | `tf-glob` | 文件名搜索,只回路径 | 同上 |
128
+ | `tf-bash` | 执行命令(Windows → pwsh) | 成功只记台账;要看输出用 `tf-peek` |
129
+ | `tf-peek` | 按句柄取回行段 | 按需注入 |
130
+ | `tf-plan` | 声明/修订计划与验收项(`- [id] 描述` 行) | 状态在驱动器侧,请求只注差分 |
131
+ | `tf-final` | 收尾(summary 必须含答案原文) | 有未验证验收项时判过早(F5) |
132
+ | `tf-code` | 程序化工具调用(**默认关闭**;`power` 或显式开启) | 上限内值完整注入;超限骨架+句柄;失败 `kind` + 可重试结论 |
133
+
134
+ 公共属性:`id`(缺省自动编号)、`depends_on`(依赖,环会被检测并具名失败)、
135
+ `accepts`(验收关联,F5)。两条省 token 的纪律写在协议文本里:**不要读自己刚写过的文件**
136
+ (只回回执)、**不要用 tf-bash 做搜索**(tf-grep/tf-glob 更省且只回匹配行)。
137
+
138
+ ## 5. 计划、恢复、长会话(默认开启,各有关闭点)
139
+
140
+ **计划与验收(F5)**——复合任务的完成判定,"声称完成但无回执"被结构性拦截:
141
+
142
+ ```
143
+ <tf-plan id="p1">
144
+ - [a1] 生成 intro.md
145
+ - [a2] 生成 summary.md
146
+ </tf-plan>
147
+ <tf-write path="intro.md" id="w1" accepts="a1">…</tf-write>
148
+ ```
149
+
150
+ - 验收项只能被**命令成功回执**(`accepts="..."`)验证——模型自述"已完成"不算证据;
151
+ - 全部验收项有回执后 `tf-final` 才会收敛,缺项/未验证注入过早提示引导补齐或修订计划;
152
+ - 计划状态放驱动器侧,请求**只注差分**(新计划全量一次,之后只注新增/已验证/已移除);
153
+ - 关闭:`enablePlan: false`(tf-plan 命令级失败,accepts 忽略,tf-final 不做验收拦截)。
154
+
155
+ **恢复意图(F6)**——强杀后的诚实状态,零注入:
156
+
157
+ - 变更类命令(tf-write/tf-edit/tf-append)派发**前**把意图(op/path/内容指纹)fsync 落盘
158
+ (`~/.dsh-stream-agent/intents/<session>.jsonl`),命令落定即写回执;
159
+ - 强杀(kill -9)三时点语义:写入前杀 = 未发生;写入中杀 = 不确定;写入后回执前杀 =
160
+ 文件已全量但账面"有意图无回执"——**不自动重放**;
161
+ - resume 发现"有意图无回执" → 回合直接 blocked(不发请求、零注入);人工核对文件后
162
+ `dsh-stream-agent intents`(列出 pending)→ `dsh-stream-agent intents --ack <session>` 闭合;
163
+ - 强杀演练(离线可跑):`node eval/tools/f6-kill-drill.cjs --rounds 10` —— 10 轮 SIGKILL
164
+ 三时点,0 重放、0 重复写、三态可判定;
165
+ - 关闭:`enableIntents: false`;只告警不阻断:`resumeIntentPolicy: 'ignore'`。
166
+
167
+ **长会话段边界(F7)**——上下文体积有界([ADR-001](docs/adr-001-segment-boundary.md)):
168
+
169
+ - 追加区超 `segmentMaxChars`(默认 160k 字符 ≈ 40k tokens)时,在**新回合开始处**把旧段
170
+ **整块丢弃**——不摘要、不改写历史(ADR 采纳"整块丢弃"路线、拒绝宿主压缩);
171
+ - 被丢弃原文句柄化(`obs:read:seg-*`),`tf-peek` / `peekHandle()` 按行段回取;
172
+ - 代价如实陈述:丢弃后的第一条请求是缓存冷请求;发生时 policyLog + 台账显式记录,
173
+ 绝不静默;丢弃只落完整回合边界(工具调用与结果不被拆开);
174
+ - 50 回合 × 2 请求实测:0 前缀违规、末/首请求 ≤1.5×;
175
+ - 关闭:`segmentMaxChars: 0`。
176
+
177
+ ## 6. tf-code:默认关闭的可选通道(K1–K6)
178
+
179
+ - **开启**:`power` 模式,或装配 `enableCode: true`(前提:宿主挂载
180
+ `@deepseek-ai/dsh-ptc-runtime`)。默认装配协议段 0 字符——模型不会幻觉调用;
181
+ 不做会话级动态开关(协议段构造期冻结)。
182
+ - **执行边界(如实声明,不承诺隔离/等权)**:沙箱只覆盖**文件效果**——程序可联网、可见
183
+ 进程;Windows 档报告 `enforcement=partial`(部分强制);`danger-full-access` 下无约束。
184
+ 这些事实逐次记账(`mode` / `denied` / `enforcement`),账本与协议错误里 `partial` 显式可见。
185
+ - **失败语义(K3)**:八类 `kind` 原样保留(exception / timeout / abort / worker-exit /
186
+ invalid-output / output-limit / protocol / sandbox-unavailable)+ 插件级 `quota-exceeded`;
187
+ 逐类给出可重试结论;沙箱拒绝 ≠ 代码错误,不引导改代码重试权限问题。
188
+ - **配额(K5)**:子调用 ≤64 次、输出 ≤256 KiB、墙钟 ≤300 s(`codeQuota` 可配);
189
+ 超限结构化终止,不靠提示。
190
+ - **取消(K4)**:回合 signal 直通 resolve 与绑定调用;abort 后等待在途清理再收束;
191
+ abort 与 timeout 分账。
192
+ - **结果可见性(F3)**:上限内(4000 字符)首成功/变化值完整注入——省一次 tf-peek 往返;
193
+ 超限转骨架 + 句柄,不恢复全量回灌。
194
+ - 真机五场景(成功/失败/取消/拒绝/partial):
195
+ [eval/tools/manual-code-scenarios.md](eval/tools/manual-code-scenarios.md)。
196
+
197
+ ## 7. 计量与评测(数字怎么来的)
198
+
199
+ 工具链全部零 API 依赖、可复算;真机批次由人工执行
200
+ (命题清单见 [docs/TEST-PROPOSITIONS.md](docs/TEST-PROPOSITIONS.md),≈2 元/命题)。
201
+
202
+ | 工具 | 用途 | 当前证据 |
203
+ | --- | --- | --- |
204
+ | `eval/tools/summarize.cjs` | M1 四分量汇总(输入/缓存读/缓存写/输出;缺失分量标"不可得") | 2026-11-15-v02 stamp:基线 446,410 → 插件 129,178(28.9%),逐任务见 summary.json |
205
+ | `eval/tools/replay-check.cjs` | M3 回放一致性(重放树哈希 == 实跑树哈希) | 对照臂 **10/10**(修复属性序敏感与增量字段名两个根因后);基线臂取证面受限如实标注 |
206
+ | `eval/tools/t3-cells.cjs` | M2 T3 三格(B / A-1a / A-1b 首请求拆分归因) | 脚本 + 三臂 patch 就绪;tf-code 段实测 1,175 字符;三格数字待同批真机 |
207
+ | `eval/tools/runner.cjs` | R3 评测矩阵(双臂 10 任务 + 哨兵) | 0.3.0 重跑待真机(新协议面) |
208
+ | `eval/tools/f6-kill-drill.cjs` | F6 强杀演练(SIGKILL × 10 轮 × 三时点) | 离线已跑:0 重放、0 重复写、三态可判定 |
209
+ | `npm run check` | R2 装配与文档一致性(entry 集/inject/顺序/README 命令表 4 项) | 一条命令复跑 |
210
+ | `npm run gate` | R4 发布门禁(C1/C2/C8/C9 + 装配一致 + 回退演练) | 离线项就地判定;真机项(G5/G6)如实标待复测,未过不发布 |
211
+
212
+ 口径纪律:单位任务 token = Σ(input + cacheRead + cacheWrite + output)(四分量,逐请求
213
+ usage 原文留存可复算);缓存分量缺失标"不可得"不按 0 计;标题旁路请求两臂同剔;
214
+ 二分量只能作参考并显式标注。
215
+
216
+ ## 8. 控制栏与桌面页
217
+
218
+ - **装载横幅**:stderr 打印引导面板(接管状态 / 当前模式 / 上手四步 / 意图提示),
219
+ `announce: true` 给每个 entry 打 mounted 行——排障时插件自证已装载。
220
+ - **CLI**(`dsh-stream-agent`):
221
+ - `bar` 交互面板:1-4 切模式、↑↓ 移动、`l` 中英切换、`?` 全模式指南、`r` 重置、`q` 退出;
222
+ - `status` / `mode <balanced|lean|compat|power>` / `lang <zh|en>` / `--json`;
223
+ - `intents` 列出各会话"有意图无回执"(F6 停机核对);`intents --ack <session>` 人工确认后闭合;
224
+ - `help` 全模式指南。
225
+ - **桌面页**:客户端左侧栏「控制栏 / Control bar」——接管状态、当前模式与来源、六个生效
226
+ 参数、四张模式卡("什么时候选 / 代价" + 省 token 档位 + 可用性标注)、中英切换;
227
+ 写路径经 `streamAgentRuntime` 服务回 loop(内存 + `control.json` 单一事实源),
228
+ 多窗口并发栅栏(409),装配/环境变量锁定的控件置灰,loop 未接管时只读降级。
229
+ - **状态落盘**:`<stateDir>/control.json`,优先级 `装配 config > STREAM_AGENT_MODE/LANG >
230
+ control.json > 内置默认`;坏文件告警回默认,绝不阻断装载。
231
+
232
+ ## 9. 目录结构
233
+
234
+ ```
235
+ dsh-stream-agent/
236
+ ├── src/
237
+ │ ├── kernel/ # 内核:parser / render / obs / gate / state / modes / control-bar
238
+ │ │ # (零依赖、无 IO、可独立单测)
239
+ │ └── entry/ # Cordis 薄壳:loop(驱动器+工厂)/ ptc-bridge / intent-log /
240
+ │ # json-persistence / state-handle / obs-broker / action-gate /
241
+ │ # context-render / eval-probe / mock-provider / control-bar* /
242
+ │ # cordis-compat / takeover-registry
243
+ ├── ui/ # 桌面控制页子包(独立 dsh.client;主包不得声明)
244
+ ├── dist/ # 构建产物(25 个文件,提交入库,patch 直接引用)
245
+ ├── profiles/
246
+ │ ├── stream/ # S1 专用 profile 模板(web 入口 + registry 默认值覆盖)
247
+ │ └── stream-headless/ # S1 headless 入口变体
248
+ ├── preset/stream/ # S4 preset-stream 独立 bundle(映射工具面;不进主 bundle patch)
249
+ ├── patches/ # 开发/评测组合补丁(takeover / eval-baseline / eval-stream /
250
+ │ # eval-stream-code-on / eval-stream-code-off)
251
+ ├── eval/ # METRICS(口径)/ RESULTS(数字)/ tasks / tools
252
+ │ # (runner / summarize / replay-check / t3-cells / f6-kill-drill)
253
+ ├── docs/ # protocol / limitations / architecture / adr-001 /
254
+ │ # disabled-lines-audit / v0.4.0-plan / TEST-PROPOSITIONS
255
+ ├── scripts/ # build / check-consistency / gate / install-check / install-cycle /
256
+ │ # repair-session-logs / release
257
+ └── test/ # 275 用例(kernel 2 套 + entry 15 套 + 20 mock 场景;零 API)
258
+ ```
259
+
260
+ ## 10. 开发
261
+
262
+ ```bash
263
+ npm test # 275/275,零 API 调用
264
+ npm run build # 产出 dist/ 25 个文件 + 全量 smoke import + 桌面页构建闸门
265
+ npm run check # R2:装配与文档一致性 4 项
266
+ npm run gate # R4:发布门禁 6 项(真机项如实标待复测)
267
+ node eval/tools/f6-kill-drill.cjs --rounds 10 # F6 强杀演练(离线,零 API)
268
+ npm run release:dry
269
+ ```
270
+
271
+ ## 11. 文档索引
272
+
273
+ | 文档 | 内容 |
274
+ | --- | --- |
275
+ | [docs/protocol.md](docs/protocol.md) | 协议语法与闭环语义(11 条命令 + F5/F6/F7 语义) |
276
+ | [docs/limitations.md](docs/limitations.md) | 已知限制(按"你会不会踩到"排序,每条带取证) |
277
+ | [docs/adr-001-segment-boundary.md](docs/adr-001-segment-boundary.md) | 长会话段边界 ADR(整块丢弃 vs 宿主压缩的决策) |
278
+ | [docs/disabled-lines-audit.md](docs/disabled-lines-audit.md) | 禁用行审计表(S5:每条停用/保留的依据) |
279
+ | [docs/v0.4.0-plan.md](docs/v0.4.0-plan.md) | 0.4.0 规划条目实施对照(F5–F7 已随 0.3.0 落地) |
280
+ | [docs/TEST-PROPOSITIONS.md](docs/TEST-PROPOSITIONS.md) | 人工测试命题与提示词(≈2 元/命题,复测用) |
281
+ | [profiles/stream/README.md](profiles/stream/README.md) | 专用 profile 的安装/选择/卸载/回退 |
282
+ | [eval/RESULTS.md](eval/RESULTS.md) · [eval/METRICS.md](eval/METRICS.md) | 评测数字与口径(全部可复算) |
283
+ | [CONTRIBUTING.md](CONTRIBUTING.md) | 提交纪律(R1:逐版独立提交、tag、CHANGELOG 段) |
284
+
285
+ ## 12. 已知限制(摘要)
286
+
287
+ 完整清单见 [docs/limitations.md](docs/limitations.md)(按"你会不会踩到"排序),要点:
288
+
289
+ 1. **写批任务**用满重入预算时进程 `exit=1` 但产物正确——护栏语义是"预算耗尽"而非"任务失败"。
290
+ 2. **tf-code 沙箱只覆盖文件效果**:程序可联网、可见进程;Windows 档 `partial`;
291
+ `danger-full-access` 无约束——使用前自己确认后果。
292
+ 3. **段边界缓存重置**:丢弃旧段后的第一条请求是缓存冷请求("整块丢弃"路线的固有代价)。
293
+ 4. **原生 loop 臂的回放取证受限**:v4 session log 中 write 调用不可解析(如实标注"不可回放",
294
+ 写入正确性由 checks 判定)。
295
+ 5. **多任务排队 + 段边界**:连续 `pushUserTask` 时段边界取最后一个任务块;需要跨任务上下文
296
+ 请合并为一条任务文本。
297
+
298
+ ## License
299
+
300
+ Apache-2.0
@@ -0,0 +1,77 @@
1
+ # cordis.patch.yml —— bundle 组合层入口(package.json > dsh.bundle.patch 指向本文件)
2
+ #
3
+ # 本插件的全部接管都发生在这里:停用内建 agent-loop,插入七个 entry。
4
+ # 卸载(dsh plugin remove)即整层消失,回到原生回合制 loop,零残留。
5
+ # 开发期想临时叠加、不动用户 profile 时,用 patches/takeover.yml。
6
+ #
7
+ # 方言规则(宿主实测得出的硬约束):
8
+ # · 停用既有行:裸 "- id: X" 配 disabled: true
9
+ # · 新增行:必须写在 insert: 下,裸新增行会被静默跳过
10
+ # · inject 必须写在行内——loader 只读行选项,模块导出的 inject 不生效
11
+ # · ./dist/... 以本文件所在目录为 baseUrl 解析,故本文件必须留在包根
12
+ #
13
+ # 装载顺序:四个 sidecar → control-bar → ui(桌面控制页宿主半边)→ loop。loop 排最后(它接管后
14
+ # 单流若很快终止,进程退出会截断尚未挂载 entry 的激活);控制栏排在 loop 之前,但横幅由
15
+ # takeover-registry 的 onTakeover 事件触发——不依赖装载时序,也不靠定时器猜。
16
+ #
17
+ # announce: true 给每个 entry 打一行 mounted 横幅——bundle 激活对 CLI 是静默的,
18
+ # 插件必须自证已装载;排障后可逐行去掉。
19
+ #
20
+ # 红线:mock-provider / eval-probe 是测试设施,不得进入本组合。
21
+
22
+ - id: agent-loop
23
+ name: '@deepseek-ai/dsh-agent-loop'
24
+ disabled: true
25
+
26
+ - insert:
27
+ # 装载顺序(07 号宿主冒烟实证):sidecar entry 全部先行挂载,stream-agent(loop)最后——
28
+ # loop 接管后单流若快速终止,进程退出会截断尚未挂载 entry 的激活。
29
+ # inject 必须逐行显式声明(loader 只读 entry.options.inject,模块导出不进 patch 行——
30
+ # cordis-plugin-loader/lib/index.js:768,06 号 §4 实测)。
31
+ # 可选服务(ptcRuntime / loader / sessionProjections / agentDefaultModel)一律不进 inject:
32
+ # 数组形式在 Cordis 里是"必需",服务缺席会把 entry 挂起(v0.2.1 修复,见 dist/entry/cordis-compat.js)。
33
+ - id: stream-agent-state
34
+ name: ./dist/entry/state-handle.js
35
+ inject: [storage]
36
+ config:
37
+ unit: tfAgentState
38
+ announce: true
39
+ - id: stream-agent-obs-broker
40
+ name: ./dist/entry/obs-broker.js
41
+ inject: [tools, state]
42
+ config:
43
+ announce: true
44
+ - id: stream-agent-action-gate
45
+ name: ./dist/entry/action-gate.js
46
+ inject: [tools, storage]
47
+ config:
48
+ announce: true
49
+ - id: stream-agent-context-render
50
+ name: ./dist/entry/context-render.js
51
+ inject: []
52
+ config:
53
+ announce: true
54
+ - id: stream-agent-control-bar
55
+ name: ./dist/entry/control-bar.js
56
+ inject: []
57
+ config:
58
+ announce: true
59
+ # 桌面控制页(v0.2.1):必须住在独立子包 ui/(有自己的 package.json 与 dsh.client)。
60
+ # 原因:dsh-client-modules 以“包”为单位扫描;主包已被上面六个 entry 引用,
61
+ # 若主包再声明 dsh.client,会抛 "resolves from multiple active Loader sources"。
62
+ # 这一行本身没有 inject 要求;webServer 由 ui/index.js 内部可选等待。
63
+ - id: stream-agent-ui
64
+ name: ./ui/index.js
65
+ inject: []
66
+ - id: stream-agent
67
+ name: ./dist/entry/loop.js
68
+ inject: [llm, tools, agents, sessions, sessionProjections]
69
+ config:
70
+ announceTakeover: true
71
+ maxParallelToolCalls: 3
72
+ maxReentries: 8
73
+ streamIdleTimeoutMs: 30000
74
+ # K1(0.3.0):tf-code 默认关闭——协议段 0 字符,模型不会幻觉调用。
75
+ # 显式开启走 power 模式,或把本行改为 true(前提:宿主挂载 @deepseek-ai/dsh-ptc-runtime,
76
+ # 且 K2-K6 五项已验收,见 docs/protocol.md 的开启说明)。
77
+ enableCode: false
@@ -0,0 +1,206 @@
1
+ // entry/action-gate.ts —— 动作门(M4 适配,分派 07)
2
+ //
3
+ // 挂点:ToolsService 管线 guard(F6,dsh-tools/lib/types/index.d.ts:136; ToolGuard 契约
4
+ // contracts.d.ts:374:同步、只拒绝不放行、不可改写——探针 B 实测,参数改写需 executor 层)。
5
+ // 职责:翻译内核 gate 的判定为管线语义:
6
+ // 1. 未声明 reversibility 的受治理动作 → deny + 可读理由(内核 UnknownActionError 原文透传);
7
+ // 非本插件治理空间的宿主工具(grep/web/…)不表意见(返回 undefined,放行权归宿主策略层)。
8
+ // 2. spec 级:写暂存区(StagingSink 接 DSH storage,绝不触碰真实工作区)+ 产 diff +
9
+ // 领一次性凭据;默认 stage-commit 模式在本守卫内完成 speculate→commit 自洽闭环后放行
10
+ // (否则 tf-write 永远无法落地);strict 模式走内核 admit(),拒绝透传(留给驱动器侧两段式)。
11
+ // 3. commit 凭据校验:kernel gate.commit 的结构化拒绝(already_used / expired /
12
+ // hash_mismatch / unknown)原样透传为可读拒绝串。
13
+ // 4. fatal 级:无批准通道 → deny(内核 admit 同款理由)。
14
+ // fail-open(红线 5):守卫自身异常 → 不表意见(放行)+ ledger 记 gate_error,绝不静默。
15
+ // 红线:本 entry 不写业务逻辑——判定/凭据/暂存泄漏探测全在 kernel/gate.ts。
16
+
17
+ import { createHash } from 'node:crypto';
18
+ import { readFileSync } from 'node:fs';
19
+ import { join } from 'node:path';
20
+ import { ActionRegistry, ActionGate, SystemClock } from '../kernel/gate.js';
21
+
22
+ import { makeWarn, EntryLedger, kernelDiffer, openKvUnit } from './adapter-kit.js';
23
+ import { asPluginEffect, getService } from './cordis-compat.js';
24
+
25
+
26
+
27
+                  
28
+
29
+                    
30
+
31
+                 
32
+
33
+                                  
34
+
35
+                                        
36
+
37
+                         
38
+
39
+                          
40
+
41
+
42
+
43
+
44
+
45
+
46
+
47
+
48
+
49
+
50
+ /** StagingSink 适配:暂存区在 DSH storage(per-record 表),工作区探针走 fs(只读)。 */
51
+ function makeStagingSink(workspaceRoot , getUnit , faults ) {
52
+ const staged = new Map (); // path -> content(暂存区内存面;storage 异步落盘)
53
+ const sha = (text ) => createHash('sha256').update(text, 'utf8').digest('hex');
54
+ const safeKey = (p ) => p.replace(/[^a-zA-Z0-9_-]/g, '_') || 'root';
55
+ return {
56
+ writeStaged(path, content) {
57
+ staged.set(path, content);
58
+ const receipt = { path, hash: sha(content) };
59
+ void getUnit()
60
+ ?.putRecord('staged', safeKey(path), { path, content })
61
+ .catch((error) => faults.push('staging-persist-error', { path, error: String(error) })); // diff/凭据以内存为准;落盘失败不静默
62
+ return receipt;
63
+ },
64
+ diffStaged() {
65
+ if (staged.size === 0) return '';
66
+ const differ = kernelDiffer(); // 复用内核逐行 diff(零业务逻辑重写)
67
+ const out = [];
68
+ for (const [path, content] of staged) {
69
+ const before = readWorkspace(path, workspaceRoot);
70
+ if (before === content) continue;
71
+ const hFrom = differ.put(before);
72
+ const hTo = differ.put(content);
73
+ out.push(differ.diff(hFrom, hTo));
74
+ }
75
+ return out.join('\n');
76
+ },
77
+ workspaceHash(path) {
78
+ return sha(readWorkspace(path, workspaceRoot));
79
+ },
80
+ };
81
+ }
82
+
83
+ function readWorkspace(path , root ) {
84
+ try {
85
+ return readFileSync(join(root, path), 'utf8');
86
+ } catch {
87
+ return ''; // 不存在视为空串 hash(内核 StagingSink 契约 :74-75)
88
+ }
89
+ }
90
+
91
+ /** 默认声明(配置可覆盖);受治理集合 = 声明集合 ∪ tf-* 前缀。
92
+ * tf-code 本体按 read 级准入(程序内的 tools.write 绑定走宿主管线,各自受原生守卫治理)。 */
93
+ function defaultActions() {
94
+ return {
95
+ 'tf-write': 'spec', write: 'spec',
96
+ 'tf-read': 'read', read: 'read',
97
+ 'tf-peek': 'read', 'tf-final': 'read',
98
+ 'tf-bash': 'read', bash: 'read',
99
+ 'tf-code': 'read',
100
+ };
101
+ }
102
+
103
+ export const name = 'stream-agent-action-gate';
104
+ export const inject = ['tools', 'storage'];
105
+
106
+ export default function apply(ctx , config = {}) {
107
+ const warn = makeWarn(ctx, 'action-gate');
108
+ const faults = new EntryLedger();
109
+ const workspaceRoot = config.workspaceRoot ?? process.cwd();
110
+
111
+ // staging unit 异步接驳(失败降级为纯内存暂存区,内核泄漏探测仍生效)
112
+ let unit ;
113
+ const storage = getService (ctx, 'storage');
114
+ openKvUnit(storage, config.unit ?? 'tfAgentStaging', ['staged'])
115
+ .then((opened) => {
116
+ unit = opened;
117
+ faults.push('staging-attached', { attached: unit !== undefined });
118
+ })
119
+ .catch((error) => faults.push('staging-degraded', { error: String(error) }));
120
+
121
+ const registry = new ActionRegistry();
122
+ const actions = config.actions ?? defaultActions();
123
+ for (const [action, rev] of Object.entries(actions)) registry.declare({ name: action, reversibility: rev });
124
+ registry.freeze(); // 装配期失败趁早暴露(缺声明在此抛 MissingReversibilityError)
125
+ const gate = new ActionGate({ registry, staging: makeStagingSink(workspaceRoot, () => unit, faults), clock: new SystemClock(), ...(config.credentialTtlMs === undefined ? {} : { credentialTtlMs: config.credentialTtlMs }) });
126
+ const mode = config.mode ?? 'stage-commit';
127
+ const governed = (name ) => name.startsWith('tf-') || name in actions;
128
+
129
+ /** 拒绝串:内核 reason/detail 原样内嵌("结构化可读理由,内核输出透传")。 */
130
+ const denial = (reason , detail ) => `[action-gate] ${reason}: ${detail}`;
131
+
132
+ /** spec/commit 级执行体的守卫翻译(stage-commit 闭环或 strict 透传)。 */
133
+ function gateSpecLevel(rev , name , args ) {
134
+ const taskId = typeof args['__taskId'] === 'string' ? (args['__taskId'] ) : 'ungoverned-task';
135
+ if (mode === 'strict') {
136
+ // strict 模式:两段式上移驱动器侧,守卫只透传内核 admit() 的拒绝语义。
137
+ // 内核 admit 是 async(fatal 批准通道),而 ToolGuard 是同步面——此处按内核
138
+ // gate.ts admit() :455-462 的 reason/detail 原文镜像,异步批准走 pre-execute waterfall(v2)。
139
+ const detail = rev === 'commit'
140
+ ? `action "${name}" 是 commit 级:先由 spec 级动作产出一次性凭据,再走 gate.commit() 放行,不允许直接准入`
141
+ : `action "${name}" 是 spec 级:走 gate.speculate() 写暂存区并领取一次性凭据,不允许直接准入`;
142
+ return denial(rev === 'commit' ? 'commit-requires-credential' : 'spec-via-speculate', detail);
143
+ }
144
+ const writes = specWritesOf(args);
145
+ if (writes === null) return denial('unparseable-spec', `动作 "${name}" 的参数缺 file_path/path + content,无法落暂存区`);
146
+ const spec = gate.speculate({ action: name, taskId, writes });
147
+ if (spec.verdict === 'deny') return denial(spec.reason, spec.detail);
148
+ const commit = gate.commit({ action: name, taskId, credential: spec.credential }); // 一次性凭据即领即验
149
+ return commit.verdict === 'deny' ? denial(commit.rejection.reason, commit.rejection.detail) : undefined;
150
+ }
151
+
152
+ // ---- ToolsService guard(F6;同步、只拒绝)--------------------------------
153
+ const guard = (execution ) => {
154
+ try {
155
+ if (config.faultInjection === true) throw new Error('injected gate fault');
156
+ const name = execution.name;
157
+ let rev ;
158
+ try {
159
+ rev = registry.reversibilityOf(name);
160
+ } catch (error) {
161
+ // 未声明:受治理动作 deny(内核错误原文透传);宿主自有工具不表意见
162
+ return governed(name) ? denial('undeclared-reversibility', error instanceof Error ? error.message : String(error)) : undefined;
163
+ }
164
+ const args = (execution.arguments ?? {}) ;
165
+ if (rev === 'read') return undefined; // 直接放行(内核 admit 的 read 语义)
166
+ if (rev === 'fatal') {
167
+ // 守卫是同步面,人工批准通道需异步 waterfall;headless v1 无通道 → 内核同款拒绝
168
+ return denial('fatal-no-approval-channel', `action "${name}" 是 fatal 级(不可逆),当前装配没有人工批准通道,直接拒绝`);
169
+ }
170
+ if (rev === 'commit') {
171
+ const credential = args['__credential'] ;
172
+ if (credential === undefined || typeof credential.id !== 'string') {
173
+ return denial('commit-requires-credential', `action "${name}" 是 commit 级:须携带 speculate 签发的一次性凭据(arguments.__credential.id)`);
174
+ }
175
+ const commit = gate.commit({ action: name, taskId: typeof args['__taskId'] === 'string' ? (args['__taskId'] ) : 'ungoverned-task', credential: credential });
176
+ return commit.verdict === 'deny' ? denial(commit.rejection.reason, commit.rejection.detail) : undefined;
177
+ }
178
+ return gateSpecLevel('spec', name, args); // 走到这里 rev 必为 spec(read/fatal/commit 已处理)
179
+ } catch (error) {
180
+ faults.push('gate_error', { action: execution?.name ?? '', error: error instanceof Error ? error.message : String(error) });
181
+ warn('守卫异常:放行(fail-open)', error);
182
+ return undefined;
183
+ }
184
+ };
185
+
186
+ if (typeof (ctx.get?.('tools') )?.guard !== 'function') {
187
+ throw new Error('[action-gate] ctx.tools.guard 不可用:无法接入工具管线(需要 dsh-tools 服务在位)');
188
+ }
189
+ (ctx.get('tools') ).guard(guard);
190
+ if (config.announce === true) console.error(`[action-gate] mounted: guard registered (actions: ${Object.keys(actions).join(',')}; mode=${mode})`);
191
+
192
+ return asPluginEffect({
193
+ registry,
194
+ gate,
195
+ faults,
196
+ dispose: () => {},
197
+ });
198
+ }
199
+
200
+ /** write 类参数 → SpecWrite[](dsh-tool-fs write schema:file_path/content;兼容 path)。 */
201
+ function specWritesOf(args ) {
202
+ const path = args['file_path'] ?? args['path'];
203
+ const content = args['content'];
204
+ if (typeof path !== 'string' || path === '' || typeof content !== 'string') return null;
205
+ return [{ path, content }];
206
+ }