@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,104 @@
1
+ # 架构
2
+
3
+ ## 一个包,两层
4
+
5
+ ```
6
+ ┌──────────────────────────────────────────────┐
7
+ │ @hugesb/dsh-stream-agent │
8
+ DSH 宿主 │ ┌──── 内核层(零框架依赖,纯函数 + 内存态)──┐ │
9
+ ┌────────┐ │ │ kernel/state.ts 内容寻址状态树 + 句柄 │ │
10
+ │ Cordis │ 注入 │ │ kernel/obs.ts info_gain 分类 + 账本 │ │
11
+ │Runtime │◄────►│ │ kernel/parser.ts tf-* 单流协议解析器 │ │
12
+ └────────┘ │ │ kernel/gate.ts 可逆性判定 + 一次性凭据│ │
13
+ │ │ kernel/render.ts 三段式装配 + prefix 断言│ │
14
+ llm.stream() │ └──────────────────┬─────────────────────────┘ │
15
+ tools.execute() │ ┌──────────────────▼─────────────────────────┐ │
16
+ session 事件流 │ │ 适配层(薄壳 entry,只做翻译) │ │
17
+ │ │ loop.ts state-handle.ts obs-broker.ts │ │
18
+ │ │ action-gate.ts context-render.ts │ │
19
+ │ │ control-bar.ts(v0.2.1) │ │
20
+ │ │ ui/index.js + ui/client.js(桌面页,独立子包)│ │
21
+ │ │ mock-provider.ts eval-probe.ts │ │
22
+ │ └────────────────────────────────────────────┘ │
23
+ └──────────────────────────────────────────────┘
24
+ ```
25
+
26
+ **这条边界是第一纪律**:`src/kernel/` 不 import 任何 `@deepseek-ai/*`(`obs.ts` / `parser.ts` 连 import 语句都没有),把这个目录单独拷出去就能跑单测。上游 API 漂移只打在 entry 薄壳上,内核资产不受损。
27
+
28
+ ## 内核七个模块
29
+
30
+ | 模块 | 职责 | 关键不变量 |
31
+ |---|---|---|
32
+ | `state.ts` | 内容寻址的状态树、句柄分配、blob 寻址 | 同一内容必然得到同一 hash,句柄稳定可重算 |
33
+ | `obs.ts` | 工具观测归类(`info_gain` = high / low / none)、行骨架、目录差分 | 分类是纯函数,输入相同结果必相同 |
34
+ | `parser.ts` | `tf-*` 命令的逐 chunk 解析 | 协议语法的唯一权威;命令闭合才派发,不等流结束 |
35
+ | `gate.ts` | 动作准入:read / spec / commit / fatal 四级 + 一次性凭据 | 缺 reversibility 声明在 `registry.freeze()` 就抛错(启动期失败,不是运行期惊喜) |
36
+ | `render.ts` | 上下文三段式装配 + 前缀单调断言 | 动态内容不得进入稳定前缀;hash 不单调即 fail-closed |
37
+ | `modes.ts` | 四个运行模式目录(balanced / lean / compat / power):只映射既有配置项,附中英双语说明 | 模式是默认值来源,装配里的显式配置永远压过它 |
38
+ | `control-bar.ts` | 控制栏的纯渲染与按键状态机:文案表、宽度计算、面板/引导/帮助/JSON、按键意图 | 中英文案成对存在;结构字符只用 ASCII,CJK 记 2 列 |
39
+
40
+ ## 适配层:十个 entry + 六个库
41
+
42
+ | entry | 挂载方式 | 作用 |
43
+ |---|---|---|
44
+ | `loop.ts` | `insert`,最后装载 | AgentFactory + 单流驱动器(唯一"改地基"的部件) |
45
+ | `state-handle.ts` | `insert`,最先装载 | 提供 `ctx.state`:句柄、blob 落 storage、resume 重建 |
46
+ | `obs-broker.ts` | `insert` | 工具结果出口登记 + `llm/stream` 泄漏扫描(依赖 `state`) |
47
+ | `action-gate.ts` | `insert` | `ToolsService` guard:spec 暂存、凭据签发与吊销、deny 层 |
48
+ | `context-render.ts` | `insert` | O6 preflight 前缀断言(第二见证) |
49
+ | `control-bar.ts` | `insert`,排在 loop 前 | 装载横幅(读接管事实)+ `ctx.streamAgentControl` 服务;模式/语言状态与 loop 共用 control.json |
50
+ | `ui/index.js` | `insert`,排在 loop 前 | 桌面控制页宿主半边:同源路由 `/stream-agent/control`、`connection.admit` 鉴权、`streamAgentRuntime` 读写、无 loop 时降级;**独立子包**,不声明在主包 |
51
+ | `ui/client.js` | `dsh.client` 浏览器半边(不单独挂载) | `__ModuleLoader__` bundle:`main` 整页 + `sidebar.panellist` 滑杆图标;四模式、中英切换、409 并发栅栏 |
52
+ | `control-bar-cli.ts` | `bin`(不挂载) | `dsh-stream-agent` 命令:交互栏 / status / mode / lang / help / --json |
53
+ | `mock-provider.ts` | **仅** `patches/test-preset.yml` | 离线假模型,绝不进生产组合 |
54
+ | `eval-probe.ts` | **仅** `patches/eval-*.yml` | 评测探针,只读透传 |
55
+ | `json-persistence.ts` | 被 state-handle / loop 引用的本地持久化兜底库(不单独挂载) | 本地 JSON KvUnit + JSONL 会话日志 + 文件台账(0.2.0,修复限制 3/4) |
56
+ | `cordis-compat.ts` | 被五个 entry 引用的适配纪律库(不单独挂载) | 可选服务只走 ctx.get(裸读会撞 inject 守卫);句柄经 asPluginEffect 包成合法 effect(0.2.1 装载修复) |
57
+ | `control-session.ts` | 被 CLI 引用的会话状态机(不单独挂载) | 按键 → 状态 → 画面 → 落盘,与终端 IO 解耦;l 键中英往返可单测(无需 pty) |
58
+ | `control-state.ts` | 被 loop / control-bar / CLI 引用的状态库(不单独挂载) | control.json 读写与优先级:装配 config > env > 文件 > 默认;坏文件 fail-open |
59
+ | `takeover-registry.ts` | 被 loop / control-bar 引用的进程内登记(不单独挂载) | 接管事实 + onTakeover 订阅:横幅按事件打印,不靠时序猜 |
60
+ | `ptc-bridge.ts` | 被 loop 引用的 PTC 桥接库(不单独挂载) | `ctx.ptcRuntime` duck-type 镜像 + tf-code 执行器(0.2.0):bindings 走宿主同一条 executeTools 守卫管线 |
61
+
62
+ ## 装配顺序
63
+
64
+ profile 启动时按层叠加,后者覆盖前者(同 id 整行替换,`config` 不深合并):
65
+
66
+ ```
67
+ @deepseek-ai/dsh-base → 各 bundle patch(本包在这一层)→ profile 自己的 cordis.patch.yml
68
+ → $DSH_HOME/cordis.patch.yml → 命令行 --patch(优先级最高)
69
+ ```
70
+
71
+ `dsh --profile <name> --dump-config` 可以看到每一层的来源与最终结果。
72
+
73
+ **装载顺序有讲究**:四个 sidecar 先,`control-bar` / `ui` 其后,`loop` 最后。loop 接管后如果单流很快终止,进程退出会截断尚未挂载 entry 的激活。控制栏因此排在 loop 之前挂载,但横幅由 `takeover-registry.onTakeover()` 事件触发——**不靠装载时序猜**:loop 先挂载则立即打印,控制栏先挂载则等 `setFactory` 成功后再打印;1.5s 内没有任何接管时兜底打印一次"未接管",便于定位半装载。
74
+
75
+ `ui` 必须是独立子包(`ui/package.json` 声明 `dsh.client`):`dsh-client-modules` 以包为单位扫描,主包已被六个 entry 引用,若主包再声明 `dsh.client` 会抛
76
+ `resolves from multiple active Loader sources`,整个客户端 boot 失败。`scripts/build.mjs` 与
77
+ `test/desktop-ui.test.ts` 都钉住了这条约束。
78
+
79
+ ## 接管与卸载
80
+
81
+ `AgentRegistry.setFactory` 是全局唯一的工厂槽位。插件 init 时注册,卸载时该层消失——**不挂 patch 就回到内建回合制 loop,零残留**。这也是"不改上游源码"红线的落地方式。
82
+
83
+ ## 桌面端 / web 组合的适配面
84
+
85
+ 桌面端(Electron 套壳 web 应用,profile `desktop`)与 headless 的组合差异显著,以下都已在真机验证:
86
+
87
+ | 差异点 | 本包做法 |
88
+ |---|---|
89
+ | setup 回调需要 agent 自己的 scoped context | 经宿主 loader 取同源 `dsh-scope`,为每个 agent 铸造真实作用域上下文;不可达时降级 ownerCtx 并告警(headless 不受影响) |
90
+ | 客户端模型选择器硬依赖 `modelSelection` 会话投影 | 注册宿主同源投影定义;服务或模块不可达则告警跳过(fail-open) |
91
+ | resume 时 seed 会补一个占位事件,导致 seq 错位 | 进入公告前立即 `appendUnstoredSuffix` 落盘对齐 cursor,避免 "append seq mismatch" |
92
+ | web/desktop 把 tool-fs / tool-pwsh 挪进 agent preset 层 | setup 完成后用 `agentCtx.tools` 重绑驱动器执行器;headless 下解析回根服务,行为不变 |
93
+ | PTC 模式组合(宿主挂 `dsh-tool-executor-ptc` / `ctx.ptcRuntime`) | tf-code 通道自动启用:单流协议负责编排(depends_on / 隐式写序 / 前缀单调),重型数据加工下沉 PTC runtime;runtime 缺失时通道关闭、协议不声明(fail-open) |
94
+ | 客户端 prompt 面要求 `steer` / `inbox` / `runMaintenance` | 全部补齐;0.2.0 起 `steer` 对齐内建——注入运行中回合的下一请求(追加区 `[tf-stream:steer]`),空闲时插队当新回合任务;"流内不打断"(不掐当前流)是单流结构前提 |
95
+ | 默认模型可能为空 | 三级回退(agentOptions → entry config → 宿主 currentSelection),仍为空则 fail-fast 出 `NO_MODEL_ROUTE`,不烧流 |
96
+ | 生命周期时序与内建不一致 | 镜像内建全序:`sessions.prepare` → `persistence.create/open` → 双公告 → setup commit → `{agent, dispose}` |
97
+
98
+ ## 红线
99
+
100
+ 1. 不改上游源码——一切以 plugin entry + patch 形式存在。
101
+ 2. `src/kernel/` 零框架依赖,单独摘出可测。
102
+ 3. 禁止"智能压缩 / 摘要历史"——只允许整块丢弃尾部,任何中途改写都会摧毁前缀缓存。
103
+ 4. 每个 entry 必须有 fail-open 开关:自身异常时退回默认行为并留账,不许静默。本地持久化兜底(0.2.0)同样逐级告警:宿主 storage/sessionPersistence/plugin record 模块 → 本地 JSON 文件 → 内存。
104
+ 5. 不如实报告等同失败:判定不过就写"不过"。
@@ -0,0 +1,277 @@
1
+ # 桌面客户端控制栏 UI 页面:可行性评估(v0.2.1)
2
+
3
+ > 结论先说:**可行,而且不需要修改 Electron 壳**。桌面端的 renderer 本身就是一套由本地 Host
4
+ > 提供的 Web 客户端,插件可以通过 `dsh.client` + `ctx.slots` 增加一整页内嵌界面。
5
+ > v0.2.1 已按这个路径实现了一个可用的垂直切片,并做了宿主侧与扫描侧的实证;
6
+ > 视觉部分仍需在真实桌面窗口里人工确认一次(见 §7)。
7
+
8
+ ---
9
+
10
+ ## 1. 现有应用结构(实测,不是推测)
11
+
12
+ ### 1.1 Electron 壳只负责“起 Host + 装页面”
13
+
14
+ 实测对象:`D:\$Applications\dsh`,`resources/app.asar` 内 `package.json` 为
15
+ `@deepseek-ai/dsh-desktop@0.2.2-rc.3`。
16
+
17
+ | 事实 | 证据 | 对 UI 的含义 |
18
+ |---|---|---|
19
+ | 主窗口不是 `file://` 静态页 | `lib/main.js` 在 `host.start()` 后取 `ready.url`,赋值 `hostUrl`;窗口导航走 `dsh-app://app/` 自定义协议 | renderer 是**本地 Host 提供的 Web 客户端** |
20
+ | 静态资源与 API 分离 | `dsh-app://app/` 的协议处理器:`/assets/*` 从 `dsh-web-frontend/dist` 读;其余请求 `forwardWebRequest(request, hostUrl, hostCookie)` | 插件页面和普通 Web 页面同源,可 `fetch('/...')` |
21
+ | 鉴权由壳注入 | `forwardWebRequest` 把 `origin` 改成 Host origin,并写入 `cookie: hostCookie` | 页面不需要自己管 token;Host 侧仍能用会话 cookie 鉴权 |
22
+ | 主窗口 CSP 允许内联样式 | app 内 CSP:`style-src 'self' 'unsafe-inline' devtools:`;`connect-src ... 'self' ...` | 客户端插件注入 `<style>`、同源 `fetch` 都合法 |
23
+ | 壳没有“插件 UI API” | `preload-app.cjs` + IPC 只服务文件、浏览器、更新等原生能力 | 想做 UI 不应走 Electron IPC,应走 Web 客户端插件 |
24
+
25
+ 因此有两条路:
26
+
27
+ 1. **改 `app.asar`**:加 `BrowserWindow`/原生面板/菜单。可行,但插件无法分发这种改动,
28
+ 每次升级都要跟着客户端发版——不可接受。
29
+ 2. **加一个 Web 客户端插件**:由 Host 动态装载,`dsh plugin add` 即可分发,卸载即消失。
30
+ 这是本文选的路,也是 dsh 自己拆 `dsh-client-ui-*` 的方式。
31
+
32
+ ### 1.2 客户端插件装载链路
33
+
34
+ `dsh-client-modules` 是这条链路的枢纽(`packages/client/modules`):
35
+
36
+ 1. 监听 Cordis Loader 的 `internal/plugin` 事件,按 **entry 的模块名** 增量扫描;
37
+ 2. 对每个 entry 找最近的 `package.json`,读 `dsh.client` 声明;
38
+ 3. 只接受 `platform: "web"`,并要求包 `exports["./client"]` 指向浏览器 bundle;
39
+ 4. 把 bundle 组成 `window.__DSH_BOOT__` 图,经 `/plugins/...` 路由提供;
40
+ 5. 浏览器侧的 `__ModuleLoader__` 是懒加载 CJS 表,按 id 物化 bundle;`react` 是平台 seed。
41
+
42
+ 这解释了三件事:
43
+
44
+ - **为什么不用重新打包客户端**:bundle 是运行时从插件目录读的,Host 重启即重新扫描。
45
+ - **为什么 UI 必须独立成包**:扫描以“包”为单位,同一个包被多个 Loader 行引用会抛
46
+ `resolves from multiple active Loader sources`。主包已有 6 个 entry,再加 `dsh.client`
47
+ 会直接让整个客户端 boot 失败。所以 UI 放在 `ui/` 子包,主包保持不声明 `dsh.client`。
48
+ - **为什么 Settings 里的插件页能做成纯 UI 包**:`dsh-client-ui-settings-shell` 的宿主半边
49
+ `apply()` 是空函数,页面完全由 `exports["./client"]` 提供——这就是“表面插件”的官方形状。
50
+
51
+ ### 1.3 页面挂载点
52
+
53
+ `dsh-client-ui-layout` 声明了 `main`(keyed 主面板)、`sidebar`、`rightbar`、`shell.overlay`;
54
+ `dsh-client-ui-sidebar` 声明 `sidebar.panellist`(左侧栏图标)。`dsh-client-ui-plugin-manager`
55
+ 就是“`main` + `sidebar.panellist`”这一对的标准范例:
56
+
57
+ ```js
58
+ ctx.slots.register({ name: 'sidebar.panellist', id: 'plugins', order: 0, label: ... }, Icon)
59
+ ctx.slots.register({ name: 'main', key: 'plugins', ... }, Page)
60
+ ```
61
+
62
+ 控制页复用同一对:`key/id = "stream-agent"`,点击左侧栏滑杆图标即打开整页。
63
+
64
+ ---
65
+
66
+ ## 2. 可复用组件
67
+
68
+ | 能力 | 来源 | 在本页的用法 | 复用程度 |
69
+ |---|---|---|---|
70
+ | 主面板 + 左侧栏图标 | `ctx.slots`(`main` / `sidebar.panellist`) | 整页与入口图标 | 直接复用,零改动 |
71
+ | 面板选中/几何 | `ctx.layout.selectPanel` / `panelInfo` | 可选:页内跳转;本版未依赖 | 可复用 |
72
+ | 设置卡片位 | `ctx.slots`(`plugins.item`) | 后续可加“控制栏”设置卡;本版未用 | 可复用 |
73
+ | 全局浮层 | `ctx.slots`(`shell.overlay`) | 后续可做 toast/状态胶囊 | 可复用 |
74
+ | 插件状态读取 | `ctx.remote.pluginInventory.list()` | 交叉核对 entry 的 `fiberPhase`/`diagnostic` | 直接复用 |
75
+ | 客户端语言 | `ctx.locale.getSnapshot().locale` | 左侧栏标签跟随界面语言 | 直接复用 |
76
+ | 表单/校验 | `ctx.configForms` + `ctx.settings` | **未用**:控制状态的事实源是 `control.json`,不是 entry config | 可复用但不合适 |
77
+ | 主题令牌 | `--dsw-alias-*` / `--dsw-radius-*` / `--dsw-font-*` | 明暗主题下的颜色、圆角、字体 | 直接复用 |
78
+ | Host 鉴权 | `ctx.connection.admit(req)` | 控制路由的 401/403 | 直接复用 |
79
+ | 客户端模块格式 | `window.__ModuleLoader__.load` + 懒 CJS | 浏览器 bundle 的外壳 | 直接复用 |
80
+
81
+ 刻意**没有**复用 `@deepseek-ai/dsh-client-ui-primitives` 的 React 组件:它需要额外的包注入,
82
+ 而本页只需要 `react` 一个平台 seed。少一个依赖,就少一个“版本对不上导致整页不渲染”的故障面。
83
+
84
+ ---
85
+
86
+ ## 3. 需要改动的范围
87
+
88
+ ### 3.1 新增
89
+
90
+ | 文件 | 作用 | 规模 |
91
+ |---|---|---|
92
+ | `ui/package.json` | 独立子包;声明 `dsh.client`(web)、`exports["./client"]`、`external: ["react"]` | ~25 行 |
93
+ | `ui/index.js` | 宿主半边:`/stream-agent/control` 同源路由、鉴权、读写、降级 | ~300 行 |
94
+ | `ui/client.js` | 浏览器半边:`__ModuleLoader__` bundle、整页 React、左侧栏图标、样式 | ~580 行(27 KB) |
95
+ | `test/desktop-ui.test.ts` | 包声明、bundle 契约、中英文案对称、模式标注、路由 7 组用例 | ~359 行 |
96
+ | `docs/desktop-ui-feasibility.md` | 本文 | — |
97
+
98
+ ### 3.2 修改
99
+
100
+ | 文件 | 改动 |
101
+ |---|---|
102
+ | `src/entry/loop.ts` | `resolveEffective()` 改为每次创建 driver 时重算;提供 `streamAgentRuntime` 服务(status/setMode/setLang);服务注册失败只告警,不影响 loop |
103
+ | `src/entry/control-state.ts` | 增加 `langSource`、`updatedAt`(并发栅栏);来源联合类型增加 `runtime`(本次运行未落盘) |
104
+ | `src/kernel/modes.ts` / `control-bar.ts` | 每模式新增 `saving` / `availability` / `note` 标注(三处渲染同源);模式目录收敛为 `publicModeCatalog()`,CLI 与页面共用一份字段 |
105
+ | `cordis.patch.yml` | 第 7 个 entry `stream-agent-ui`(`./ui/index.js`) |
106
+ | `preset.yml` / `patches/takeover.yml` | 同步第 7 个 entry;`preset.yml` 行序调回 `sidecar → control-bar → ui → loop`;顺手修掉 preset 里一处 `config:/n` 的坏 YAML |
107
+ | `package.json` | `files` 加 `ui/` |
108
+ | `scripts/build.mjs` | 构建闸门:主包不得有 `dsh.client`;UI 包声明合规;`ui/index.js` 可导入;`ui/client.js` 语法可编译 |
109
+ | `README.md` / `README.en.md` | 新增「桌面客户端控制页」章节与三个面的对照表 |
110
+ | `CHANGELOG.md` / `docs/architecture.md` / `docs/limitations.md` | 0.2.1 条目、模块清单与「桌面页依赖动态客户端插件机制」限制 |
111
+
112
+ ### 3.3 明确不改
113
+
114
+ - `app.asar`、`lib/main.js`、`preload-app.cjs`、Electron 版本、窗口/菜单/托盘;
115
+ - `@deepseek-ai/*` 任何包;
116
+ - 用户 profile 的 `cordis.patch.yml`(仍由 `dsh plugin add` 管理);
117
+ - CLI 行为:`mode`/`lang`/`bar`/`status` 的语义与输出保持兼容,只是多了一个写 `control.json` 的入口。
118
+
119
+ ---
120
+
121
+ ## 4. 与现有控制逻辑的交互
122
+
123
+ ### 4.1 单一事实源
124
+
125
+ ```
126
+ 装配 config.mode/lang ─┐
127
+ STREAM_AGENT_MODE/LANG ─┤
128
+ control.json ─┼─→ resolveControlState() → control { mode, lang, modeSource, langSource }
129
+ 内置默认 ─┘ │
130
+ ├─→ 控制页 GET 状态
131
+ ├─→ CLI status/bar
132
+ └─→ loop 每次创建 driver 时 resolveEffective()
133
+ ```
134
+
135
+ - UI **不直接读文件**:它调 `streamAgentRuntime.status()`,拿到的是 loop 内存里的 `control`
136
+ 以及 `resolveEffective()` 的实时结果。这样页面显示的模式一定等于“下一个 agent 会用的模式”。
137
+ - UI 的写也**不直接改文件**:它调 `setMode`/`setLang`,由 loop 更新内存、`markTakeover()`、
138
+ 再原子写 `control.json`。CLI 与页面因此不会各写一套。
139
+ - 只有 loop 缺席(装载失败/headless)时,UI 才降级为直接写文件,并明确标注
140
+ `takeover: false` + “重启后生效”。
141
+
142
+ ### 4.2 生效时机
143
+
144
+ `resolveEffective()` 从“装载时算一次”改成“每次 `createDriver` 时算一次”:
145
+
146
+ - 切模式后,**之后创建的 agent** 用新参数;
147
+ - 已开的会话保持创建时的 driver 配置(不在会话中途突变,避免上下文/预算跳变);
148
+ - `persistFallback` 是四个模式里唯一不变的值(全为 `true`),因此仍按装载时决定,
149
+ 不影响“切模式立即生效”的语义。
150
+
151
+ ### 4.3 锁定规则
152
+
153
+ - `modeSource === 'config' | 'env'` → 页面模式卡置灰,路由返回 409 `locked`;
154
+ - `langSource === 'config' | 'env'` → 语言开关置灰;
155
+ - 原因写在页面上(“装配配置/环境变量写死了这个值”),不静默失败;
156
+ - CLI 仍可直接改文件,但下一次 `resolveControlState` 仍会被更高优先级的 config/env 压回去——
157
+ 这与 0.2.1 既有的优先级纪律一致。
158
+
159
+ ### 4.4 与横幅/CLI 的一致性
160
+
161
+ - `setMode` 会调用 `markTakeover(next)`,控制栏 entry 的 `statusLine()` 立即读到新值;
162
+ - 语言/模式写入后,`dsh-stream-agent status` 与 `bar` 读取同一份 `control.json`;
163
+ - 装载横幅只在启动时打印一次,不会因为页面切模式而重印——这是预期行为(横幅是“装载自证”,
164
+ 不是实时仪表盘)。
165
+
166
+ ---
167
+
168
+ ## 5. 权限与状态同步
169
+
170
+ ### 5.1 鉴权
171
+
172
+ - 路由处理第一步调用 `ctx.get('connection').admit(req)`,复用桌面/Web 共用的会话鉴权:
173
+ - 无 cookie/launch token → 401;
174
+ - Host/Origin 不可信 → 403;
175
+ - 通过 → 继续。
176
+ - `connection` 缺席时(极简宿主/测试)只允许回环地址,避免把写接口暴露到网络。
177
+ - 不实现自定义 token:复用宿主已有的 cookie 机制,少一套密钥生命周期。
178
+
179
+ ### 5.2 CSRF / 跨站
180
+
181
+ - 只接受 `POST` + `content-type: application/json`:跨站表单无法直接构造,跨源请求会先触发
182
+ preflight,而路由不返回 CORS 头;
183
+ - `sec-fetch-site` 存在且不是 `same-origin`/`none` → 403;
184
+ - 不返回任何 CORS 头,浏览器跨源读不到响应;
185
+ - 请求体上限 4 KB,字段只接受 `mode` / `lang` / `expectedUpdatedAt` 三个白名单键。
186
+
187
+ ### 5.3 并发与多窗口
188
+
189
+ - `control.json` 写入是“临时文件 + rename”的原子替换;
190
+ - GET 返回 `updatedAt`;POST 可带 `expectedUpdatedAt`,不匹配返回 **409 + 最新状态**;
191
+ - 页面收到 409 后直接刷新为最新值并提示“已被其他窗口或 CLI 修改”,不重试覆盖;
192
+ - 多进程(CLI + 桌面 + 另一个窗口)同样是“最后写入者赢”,但至少有一次显式冲突提示,
193
+ 不会在用户不知情时把 lean 改回 balanced。
194
+
195
+ ### 5.4 故障隔离
196
+
197
+ | 故障 | 行为 |
198
+ |---|---|
199
+ | `ui/index.js` 装载失败 | 只该 entry failed;loop/sidebar 仍工作;客户端页面不出现 |
200
+ | `ui/client.js` 语法错误 | **会**让客户端 boot 失败——因此构建期 `new Function` 闸门 + 扫描测试是硬要求 |
201
+ | `streamAgentRuntime` 注册失败 | loop 只告警;页面降级为文件视图 |
202
+ | 路由 handler 抛错 | 该请求 500;不影响 Host 其他路由 |
203
+ | 状态文件损坏 | `readPersistedControl` fail-open 回默认并告警;页面显示默认值 |
204
+
205
+ ---
206
+
207
+ ## 6. 风险与约束
208
+
209
+ | 风险 | 等级 | 缓解 |
210
+ |---|---|---|
211
+ | 同包多 entry + `dsh.client` → 多源抛错,整页 boot 失败 | **高** | UI 独立子包;主包禁止 `dsh.client`;构建闸门 + `test/desktop-ui.test.ts` 断言 |
212
+ | 浏览器 bundle 语法错误 → 客户端 boot 失败 | **高** | `new Function` 只编译不执行;`__ModuleLoader__` 包装与 id 断言;真实 `ClientModuleRegistry` 扫描测试 |
213
+ | `connection.admit`、slot 名、`--dsw-*` 令牌属于宿主内部契约 | 中 | 版本锚定 `>=0.2.2-rc.1`;所有可选服务走 `ctx.get`;失败降级不阻断 loop |
214
+ | 桌面 bundle 无 HMR | 中 | 文档明确“升级后重启客户端”;页面显示版本,便于核对 |
215
+ | 主题令牌在明暗主题下表现不同 | 中 | 全部给 fallback;明暗主题已人工过一遍(§7) |
216
+ | 页面只影响新会话,用户误以为旧会话也变了 | 低 | 页头/保存提示明确写“对新会话生效”;文档同口径 |
217
+ | 原生菜单/托盘/快捷键不可用 | 低 | 明确列为非目标;需要时只能改 Electron,另立方案 |
218
+ | Web 部署的 CSP 与桌面不同 | 低 | 桌面 CSP 已实测允许内联样式;Web 部署需按同一 CSP 复核 |
219
+
220
+ ---
221
+
222
+ ## 7. 验收:已实证(脚本/测试 + 真机)
223
+
224
+ ### 已实证(脚本/测试)
225
+
226
+ 1. **7/7 entry 在真实 Cordis 4.1 上 active**(state 2),`setFactory` 已注册;
227
+ 2. **控制路由 GET 200**:`takeover: true`、`modes.length === 4`;
228
+ 3. **`setMode('lean')` 返回 `{ok:true, persisted:true}`**,再次读状态为 `lean`;
229
+ 4. **真实 `dsh-client-modules` 扫描**:7 个 Loader 行 + UI 子包 → boot 图里**恰好 1 条**
230
+ `@hugesb/dsh-stream-agent-ui`,无多源错误;
231
+ 5. **255/255 测试通过**,含 11 条桌面页用例(鉴权/跨站/JSON/非法值/锁定/409/首次写入/降级/中英文案对称/模式标注);
232
+ 6. **构建闸门**:主包无 `dsh.client`、UI 包声明合规、`ui/client.js` 语法可编译。
233
+
234
+ 复现命令(工作区根目录):
235
+
236
+ ```bash
237
+ node scratch/repro-all-entries.mjs # 7 entry + 路由 + setMode
238
+ node scratch/repro-client-scan.mjs # 真实 client-modules 扫描
239
+ npm test # 255 用例
240
+ npm run build # 含 UI 闸门
241
+ ```
242
+
243
+ ### 已人工验收(2026-11-16,真实桌面窗口)
244
+
245
+ headless 环境渲染不了 React 客户端,以下项由人工在 dsh 桌面里逐条确认:
246
+
247
+ - 左侧栏出现滑杆图标,点击打开整页;
248
+ - 四张模式卡可点击切换,切换后 `dsh-stream-agent status` 同步;
249
+ - 中文 / English 双向切换,文案与页面一致;
250
+ - 明暗主题下对比度正常;
251
+ - 重启客户端后页面仍在(bundle 无 HMR,必须重启)。
252
+
253
+ > 验收结论:桌面控制页可作为客户端内嵌界面直接使用,不需要修改 Electron 壳。
254
+ > 双窗口 409 提示属"有则更好"的保护,逻辑已在 `test/desktop-ui.test.ts` 里覆盖,未列入本次人工项。
255
+
256
+ ---
257
+
258
+ ## 8. 分期建议
259
+
260
+ | 阶段 | 内容 | 状态 |
261
+ |---|---|---|
262
+ | P0(v0.2.1) | 左侧栏整页、状态、四模式、中英切换、409 并发栅栏、降级诊断 | 已实现 |
263
+ | P1 | Settings → Plugins 里加一张“控制栏”卡(`plugins.item`);页内高级参数编辑;会话级临时覆盖 | 可选 |
264
+ | P2 | 原生托盘/菜单/全局快捷键;多用户远程部署的细粒度权限 | 需要 Electron 改动或 Host 权限模型,另立方案 |
265
+
266
+ ---
267
+
268
+ ## 9. 结论
269
+
270
+ - **技术可行性:高**。dsh 桌面端已经把“UI 作为客户端插件”做成了一等扩展面,控制页只是
271
+ 按既有 `main` + `sidebar.panellist` 形状再加一个消费者。
272
+ - **改动风险:可控**。不动 Electron,不动宿主包;最大的坑(同包多源)用独立子包 + 构建闸门
273
+ + 回归测试封死。
274
+ - **产品价值:中高**。新用户不必记 CLI 参数,打开就能看到“我现在是什么模式、为什么、怎么换”;
275
+ 同时保留 CLI 作为脚本化/排障通道。
276
+ - **不建议**为了这个页面去改 `app.asar`:收益是原生窗口/菜单,成本是插件失去独立分发能力,
277
+ 与“`dsh plugin add` 一条命令装卸”的产品形态冲突。
@@ -0,0 +1,53 @@
1
+ # 禁用行审计表(S5,0.3.0-beta.1 交付)
2
+
3
+ > 审计对象:`cordis.patch.yml`(主 bundle patch)中全部停用行 + 全部"候选停用未停用"行。
4
+ > 判定规则(升级方案 §10.2):不确定就保留;同族同进同退;按 id+name 双重匹配;
5
+ > 不以 token 为由停宿主提示行;每条停用必须带启动用例。
6
+ > 宿主服务面锚点:`@deepseek-ai/dsh-base`(rc.3)`dsh-web-app/cordis.patch.yml`、`presets/standard.patch.yml`。
7
+
8
+ ## 1. 已停用行(主 bundle patch)
9
+
10
+ | 行 id | 插件 name | 被谁 inject / 依赖 | 停用后哪条路径不可用 | 验证用例 | 结论 | 依据 |
11
+ |---|---|---|---|---|---|---|
12
+ | `agent-loop` | `@deepseek-ai/dsh-agent-loop` | `agents` 服务消费 factory;loop entry 接管后由 `setFactory` 全局唯一槽位决定 | 内建回合制 loop(本插件以单流协议替代) | `test/activation.test.ts`(严格 inject 守卫 ctx 装载回归 + factory 冲突 `E_DOUBLE_LOOP` 具名失败);真机装卸回归 `scripts/install-cycle.mjs` | **必须停用** | C2 单 loop 权威;停用留在 bundle 层(C4),卸载原子恢复 |
13
+
14
+ 停用行总数:**1**。审计结论:主 bundle 只停内建 loop 一行;不存在"批量 disabled"。
15
+
16
+ ## 2. 候选停用但保留的行(含保留依据)
17
+
18
+ 以下行在 standard preset / host 平面中存在,对本协议"不消费",但**全部保留**——
19
+ 宿主提示行不进本驱动器请求(升级方案已核实),停用只缩小装配面、不省 token,
20
+ 而每停一行都要一张启动用例证明"运行期不缺服务"。风险收益不成比,宁可保留。
21
+
22
+ | 行 id / 族 | 保留依据(谁在用、停了会怎样) | 风险 | 结论 |
23
+ |---|---|---|---|
24
+ | `persona` / `agent-instructions` / `time-context` | 宿主 system 组装面;驱动器自建 system,这些行不进请求 | 停用影响同 profile 其它 preset 使用者 | 保留 |
25
+ | `tool-jobs` / `tool-schedule` / `tool-goal` / `command-goal` | 宿主平面工具;协议不声明,模型不会调用(未列工具 0 调用,S4) | 停用后宿主其它入口(jobs API)缺服务 | 保留 |
26
+ | `tool-web` / `tool-skill` / `tool-present` / `tool-office` | 同上;协议面只有 tf-* | 同上 | 保留 |
27
+ | `tool-todo` / `tool-ask-user` | 同上 | 同上 | 保留 |
28
+ | `tool-subagent*` / `tool-agent-team` | delegation 族(宿主 isolate 组);本驱动器不派发子代理 | 族内行同进同退,单停任一行会破坏 isolate 组挂点 | 保留(族) |
29
+ | `plan-mode`(planning 组) | planMode isolate 组挂点 | 组拆散 = 装配面漂移 | 保留 |
30
+ | `compaction-basic` / `command-compact` / `tool-result-pruner`(compaction 族) | compaction isolate 组挂点;本驱动器不触发压缩 | 若宿主在 `llm/stream` 层挂压缩钩子则须停用(否则改写历史破 C7 前缀);rc.3 实测挂点在 agent 层、本驱动器路径不触发 | 保留(族)+ 监控:任何"历史被改写"都会被 preflight fail-closed 拦截 |
31
+ | `workflow-ptc` / `tool-workflow` / `tool-executor-ptc` / `ptc-runtime`(PTC 族,四行) | PTC 四行同进同退(升级方案强制);K1 后默认 `enableCode=false`(协议不声明 tf-code),四行**全保留**且不动 | 只停任一行会留下悬空依赖(启动期缺服务) | 保留(族,全进全退);`tf-code` 通道由 `enableCode` 配置控制,不由装配禁行控制 |
32
+ | `tool-pwsh` / `tool-bash`(平台二选一) | `tf-bash` 映射目标(preset 内按平台 disabled) | 全停 = tf-bash 无映射目标 | 保留其一 |
33
+ | `tool-fs` / `tool-fs-search` | `tf-write/tf-read/tf-edit/tf-append` 与 `tf-grep/tf-glob` 的映射目标 | 全停 = 全部文件命令无映射 | 保留 |
34
+ | `agent-preset-registry`(仅 web) | `preset-stream` 的注册与默认值(S4) | 停用 = preset 面不可用 | 保留 |
35
+ | `llm` / `session` / `storage` / `settings` / `credentials` / `fs-sandbox` / `sandbox` / `sandboxPolicy` | 服务层(S 组保留清单,驱动器 inject 依赖) | — | 保留 |
36
+
37
+ ## 3. 判定过程记录(为什么没有更多停用行)
38
+
39
+ 1. 0.2.x 曾计划"停用 tool-web 等候选行以缩小装配面"——0.3.0 审计后**全部放弃**:
40
+ 这些行不进驱动器请求(无 token 收益),停用唯一效果是装配面变化 + 每行一个
41
+ 启动回归的维护成本。把"装配面缩小"写成"token 优化"属于虚报(C5)。
42
+ 2. PTC 四行与 compaction 四行按族处理(升级方案 §10.1 强制),本版全保留;
43
+ `tf-code` 的开关在配置层(`enableCode`,K1 默认 false),通道关闭 = 协议段
44
+ 0 字符 + 命令级失败引导改道,不需要动装配行。
45
+ 3. compaction 族的"挂点验证":宿主 rc.3 的 compaction 组挂在 agent isolate 层,
46
+ 本驱动器路径不触发;若未来宿主把压缩挂到 `llm/stream` 层,preflight 断言
47
+ (`PrefixBrokenError`)会立即 fail-closed 暴露——届时按本表"族同进同退"停用。
48
+
49
+ ## 4. 回归锚点
50
+
51
+ - 装载回归:`test/activation.test.ts`(严格 inject 守卫 + 可选服务探测)
52
+ - 装配一致性:`npm run check`(R2 四项,含"停用只在 bundle 层"结构检查)
53
+ - 真机装卸:`scripts/install-cycle.mjs`(10 轮,卸载后宿主 loop 恢复、0 残留)
@@ -0,0 +1,181 @@
1
+ # 已知限制
2
+
3
+ 按"你会不会踩到"排序,每条都给出取证位置与缓解方式。**判定不过就写不过**——这份清单不做美化。
4
+
5
+ > 0.2.0 已定向修复原 1 / 3 / 5 / 7 四条(自写回验 receipt、steer 运行中注入、本地持久化兜底、
6
+ > 本地文件台账)。原条目保留修复说明,新增限制排在对应位置。
7
+
8
+ ## 一、成本与正确性的取舍
9
+
10
+ ### 1. 写批任务 token 偏重(0.2.0 已修复)
11
+
12
+ - **原现象**:写多文件的任务收益不稳定,模型拿到完整反馈后自发做"写 → 读回验 → 再改"循环。
13
+ - **修复**:自写回验 receipt(O7)——`tf-read` 命中本任务 `tf-write` 已写过的路径时只注入回执
14
+ (行数 + sha256 指纹),不重复回灌全文(全文就在模型上下文里);协议文本新增"回验纪律"。
15
+ 读**外部文件**的完整反馈保持不变,正确率路径不受影响。
16
+ - **取证**:`src/entry/loop.ts` 的 `#writtenPaths` 与 `#buildInjections` receipt 分支;
17
+ `test/fix-limits.test.ts` R1–R3。
18
+ - **余留**:真连收益需重跑两臂评测确认(本仓库 eval 数据是 0.1.0 口径);`selfReadFeedback: 'full'`
19
+ 可回退旧行为。
20
+
21
+ ### 2. W1 / C2 退出码 1,但产物正确
22
+
23
+ - **现象**:任务在重入预算(`maxReentries: 8`)内没有收敛,进程 `exit=1`,但 checks 判 PASS。
24
+ - **原因**:防荡护栏按设计拦截——写批任务用满 9 次请求后不再放行。
25
+ - **影响**:自动化流水线里会看到"失败退出码 + 正确产物"的组合。
26
+ - **缓解**:把护栏理解为"预算耗尽"而非"任务失败";需要更长回验循环时调 `maxReentries`。
27
+
28
+ ## 二、行为语义偏离
29
+
30
+ ### 3. `steer` 语义(0.2.0 已对齐内建)
31
+
32
+ - **原偏离**:插队到队首,在回合边界生效。
33
+ - **修复**:回合运行中收到 steer → 注入运行中回合的**下一请求**(追加区 `[tf-stream:steer]`
34
+ 用户块;带未消费 steer 时不允许收敛),对齐内建"注入运行中回合的下一步";单流
35
+ "流内不打断"(不掐当前流)前提不变。空闲时保持原语义(插队队首、当新回合任务)。
36
+ - **取证**:`src/entry/loop.ts` 的 `pushSteer` / `#pendingSteers` 与 `StreamLoopAgent.steer`;
37
+ `test/fix-limits.test.ts` S1–S2。
38
+ - **余留**:内建 steer 会在流间立即接管下一步;本实现保证"下一请求可见",不保证
39
+ "当前流中途打断"——这是单流协议的结构性前提,不是缺陷。
40
+
41
+ ## 三、环境依赖
42
+
43
+ ### 4. `dsh plugin` 需要 pnpm
44
+
45
+ - PATH 里没有 `pnpm` 时安装/卸载会失败。按 dsh-plugin-manager 配置 `pnpmCommand` 可绕开。
46
+
47
+ ### 5. 持久化依赖宿主 storage(0.2.0 已修复)
48
+
49
+ - **原现象**:headless 未挂 storage backend / sessionPersistence 时降级内存,跨会话 resume 不可用。
50
+ - **修复**:本地持久化兜底(`src/entry/json-persistence.ts`,零依赖)——
51
+ ① state-handle 降级本地 JSON 文件 KvUnit(durable,resume 可重建句柄目录);
52
+ ② AgentFactory 降级本地 JSONL 会话日志(create 落盘、resume 冷读)。
53
+ 状态根目录:`STREAM_AGENT_STATE_DIR` env → `~/.dsh-stream-agent`(子目录 `storage/`、`sessions/`、`ledger/`)。
54
+ - **取证**:`test/adapters.test.ts` A4(KvUnit 兜底 + 跨"重启" resume)、`test/fix-limits.test.ts` P1–P2。
55
+ - **余留**:本地兜底的会话日志格式是插件私有的 JSONL,与宿主 zstd session log 不互通;
56
+ 宿主持久化在位时优先宿主。`persistFallback: false` / `localFallback: false` 可关闭(回内存降级)。
57
+
58
+ ### 5b. `tf-code` 依赖宿主 PTC runtime(0.2.0 新增;0.3.0 默认关闭,fail-open)
59
+
60
+ - **0.3.0 起(K1)**:`enableCode` 默认 **false**——默认装配的协议段 0 字符,模型不会幻觉调用;
61
+ 开启必须显式(`power` 模式或装配 `enableCode: true`),且以 K2–K6 收口为前提。
62
+ 不做会话级动态开关(协议段构造期冻结,动态切换会破坏前缀单调)。
63
+ - **现象**:宿主未挂 `@deepseek-ai/dsh-ptc-runtime`(`ctx.ptcRuntime` 缺失)或形状不符时,tf-code 通道整体关闭。
64
+ - **行为**:关闭是**装配期**的——协议文本不声明 tf-code(稳定前缀里不存在这个命令,模型不会幻觉调用);
65
+ 若模型仍输出 `<tf-code>`(跨装配漂移),命令级失败注入 `no-code-channel` 并建议改道 tf-bash。告警不静默。
66
+ - **缓解**:挂载 PTC runtime 后端(如 `@deepseek-ai/dsh-ptc-runtime-node`)+ 显式 `enableCode: true`;
67
+ 关闭路径 `enableCode: false`(默认)。
68
+ - **取证**:`src/entry/ptc-bridge.ts`、`src/entry/loop.ts` 的 tf-code 分支;`test/ptc-bridge.test.ts`。
69
+
70
+ ### 5b-1. tf-code 沙箱的事实边界(0.3.0 K2/K6 声明,如实陈述)
71
+
72
+ 只声明"文件效果边界 + 事实记账",**不承诺隔离/等权**:
73
+
74
+ 1. **只覆盖文件效果**:宿主 `SandboxMode` 不包含网络与进程可见性——程序仍可联网、可见进程;
75
+ 把"沙箱"理解成"隔离"是错误的使用方式。
76
+ 2. **Windows 只部分强制**:ACL 档报告 `enforcement=partial`(硬链接别名、读取不受限、
77
+ AppContainer 边界)。需要绝对边界的任务必须显式拒绝或提示;插件不做"绝对只读"承诺。
78
+ `partial` 在账本与协议错误里**显式可见**(K2:`mode` / `denied` / `enforcement` 逐次记账)。
79
+ 3. **`danger-full-access` 无约束力**:全权限模式下插件没有任何文件边界;账本与 UI 如实标注
80
+ "无约束",使用前自己确认后果。
81
+ 4. **preset/profile 不是安全边界**:它们只是组合边界,YAML 与插件仍执行宿主代码;安全声明
82
+ 只能引用 sandbox 事实(`docs/disabled-lines-audit.md`),不能引用"独立模式"。
83
+ 5. **插件级配额(K5)**:子调用次数 / 输出字节 / 墙钟三项硬限制(缺省 64 次 / 256KiB / 300s),
84
+ 超限结构化终止(`kind: quota-exceeded`)——配额是插件侧护栏,不是宿主沙箱的一部分。
85
+ 6. **取消窗口(K4)**:回合取消直通 resolve 与绑定调用(回合 signal);abort 后 drain 等待
86
+ 在途清理再收束(0 后置写是验收目标);kill -9 级强杀的窗口语义见 5b-2。
87
+
88
+ ### 5b-2. 写前意图与强杀窗口(0.3.0 F6,零注入)
89
+
90
+ - 变更类命令(tf-write/tf-edit/tf-append)派发**之前**把意图落盘并 fsync
91
+ (`<stateRoot>/intents/<sessionId>.jsonl`:op/path/内容指纹);命令落定即写回执。
92
+ - **强杀(kill -9)三时点语义**:写入前杀 = 文件不在(oracle 可证"未发生");
93
+ 写入中杀 = 磁盘可能有半个文件(三态判"不确定");写入后回执前杀 = 文件已全量落盘
94
+ 但账面"有意图无回执"——同样判"不确定",**不自动重放**。
95
+ - **resume 停机核对**:恢复会话时发现"有意图无回执"→ `runTurn` 直接 blocked(不发请求、
96
+ 零注入),人工核对文件后 `dsh-stream-agent intents --ack <session>` 闭合。
97
+ 零注入纪律:意图与回执永不进入模型上下文。
98
+ - 回退点:`enableIntents: false`(不落盘、不核对)/ `resumeIntentPolicy: 'ignore'`(只告警)。
99
+ - 取证:`src/entry/intent-log.ts`、`eval/tools/f6-kill-drill.cjs`(10 轮强杀演练,0 重放 0 重复写)。
100
+
101
+ ### 5c. 桌面控制页依赖动态客户端插件机制(0.2.1 新增)
102
+
103
+ - **依赖**:dsh `>=0.2.2-rc.1` 的 `dsh-client-modules`(扫描 `dsh.client`、组 `__DSH_BOOT__`)与
104
+ `dsh-client-ui-layout` / `dsh-client-ui-sidebar` 的 `main` / `sidebar.panellist` 槽位;桌面 `rc.3` 实测在位。
105
+ - **装载**:页面在 `ui/` 独立子包,主包**不能**声明 `dsh.client`(同包多 entry 会触发
106
+ `resolves from multiple active Loader sources`,整个客户端 boot 失败)。构建闸门与
107
+ `test/desktop-ui.test.ts` 都钉住这条。
108
+ - **生效**:bundle 无 HMR,升级插件后必须重启客户端;页面只影响新会话;装配 config/env 的值
109
+ 会锁定对应控件(界面不覆盖显式配置)。
110
+ - **边界**:不是原生窗口,没有托盘/菜单/全局快捷键;这些需要改 Electron `app.asar`,不在插件能力内。
111
+ - **降级**:loop 未接管时页面仍可打开,显示"未接管"、允许写 `control.json`,并提示修复装载后重启;
112
+ 路由鉴权复用 `ctx.connection.admit`,跨站/非 JSON 请求被拒。
113
+
114
+ ### 6. `tf-bash` 可能被沙箱拒
115
+
116
+ - 部分目录下 pwsh grant 失败(Win32 5)。基线臂同样受限,属环境因素而非插件缺陷。
117
+ - 缓解:把工作区放到 DSH 已授权的目录下。
118
+
119
+ ### 7b. 长会话段边界的缓存重置(0.3.0 F7,ADR-001)
120
+
121
+ - **行为**:追加区超过 `segmentMaxChars`(缺省 160k 字符 ≈ 40k tokens;0/负数关闭)时,
122
+ 在**新回合开始处**把旧段整块丢弃(ADR-001 整块丢弃路线;原文句柄化 `obs:read:seg-*` 可
123
+ tf-peek 回取,绝不摘要改写)。
124
+ - **代价(如实陈述)**:丢弃后的第一条请求是缓存冷请求(cacheWrite 重新计费)——这是
125
+ "整块丢弃"路线的固有代价;阈值越高重置越少。发生时 policyLog + 台账显式记录,不是静默修复。
126
+ - **边界纪律**:丢弃只落在完整回合边界(当前回合的块永不丢弃,工具调用与结果不被拆开);
127
+ preflight 对"未记录的"前缀不一致仍然 fail-closed。
128
+ - 取证:`docs/adr-001-segment-boundary.md`、`src/kernel/render.ts` 的 `dropAppendHead`、
129
+ `test/f7-segment.test.ts`(50 回合 × 2 请求,0 前缀违规)。
130
+
131
+ ## 四、降级通道(有告警,不静默)
132
+
133
+ ### 7. bundle 形态下 plugin record 通道降级(0.2.0 已修复为文件台账)
134
+
135
+ - **原现象**:bare import `@deepseek-ai/dsh-session` 拿不到宿主同一模块实例 → 降级易失内存台账,
136
+ resume 后 `tf-*` 状态不可重放。
137
+ - **修复**:`attachSessionLedger` 先走宿主 loader 三级同源解析(`loader.import` →
138
+ `loader.internal.import` → 动态 import);仍不可达时降级**本地 JSONL 文件台账**(可重放),
139
+ resume 时 `rehydrateRecords` 把 final 答案回灌新驱动器。每级降级都告警,不静默。
140
+ - **取证**:`src/entry/loop.ts` 的 `attachSessionLedger` / `collectTfAgentRecords` /
141
+ `SingleStreamDriver.rehydrateRecords`;`test/fix-limits.test.ts` L1–L3。
142
+ - **余留**:命令记录刻意不回放(属性不回放则幂等指纹永不匹配,回放反而占用 id 命名空间);
143
+ final 答案与句柄目录可跨 resume 续用。
144
+
145
+ ## 五、评测工具自身的缺陷
146
+
147
+ ### 8. replay 一致性对真连 session log 0 命中(0.3.0 对照臂已修复)
148
+
149
+ - **0.2.x 现象**:`replay-check.cjs` 对照臂提取 0 命中 → replay 列全 FAIL。
150
+ - **0.3.0 修复(M3)**:两个根因——①提取正则要求 `path` 在 `id` 之前(属性序敏感);
151
+ ②`text-delta` 增量字段读错(`textDelta` → 实际是 `text`)。修复后对照臂 10/10 通过
152
+ (树哈希 == 实跑,`eval/RESULTS.md` §6.2);基线臂(原生 loop 的 v4 session log)
153
+ write 调用未以可解析形态出现,如实标注"不可回放"(4/10),写入正确性由 checks 判定。
154
+ - **取证**:`eval/tools/replay-check.cjs`、`eval/runs/2026-11-15-v02/*/metrics.json` 的 replay 字段。
155
+
156
+ ### 9. `injected_ratio` 口径偏差
157
+
158
+ - 驱动器 snapshot 计数在 peek / 完整反馈场景下会偏大或偏小。
159
+ - **口径**:以驱动器 turn-end snapshot 为权威值,`eval/METRICS.md` 有定义;不要用它单独论证收益,token 总量才是判据。
160
+
161
+ ## 六、桌面显示面(0.3.1)
162
+
163
+ ### 10. 实时帧只送思考过程,正文在落盘后显示
164
+
165
+ - **现象**:stream 模式下,桌面端流式显示的是思考过程(reasoning-delta 实时帧);回答正文
166
+ 在该步 assistant/message 落盘后才出现(一次性)。
167
+ - **原因**:流文本是 tf-* 协议标记——逐帧透传会让标记在界面上闪现成乱码(0.3.1 修的正是
168
+ 这个)。内建 loop 的流文本是最终答案本身,所以可以逐帧透传;两种模式的流文本语义不同,
169
+ 不宜对齐。
170
+ - **取证**:`src/entry/loop.ts` 的 `#frameReasoningDelta`(只发 reasoning-delta)与
171
+ `#consumeStream` 的落盘注释;`test/v031-display.test.ts` R3。
172
+ - **缓解**:思考过程全程实时可见;正文延迟与 0.3.0 相同(0.3.0 是全程无实时显示)。
173
+
174
+ ### 11. 有工具执行的步骤,live attempt 在首个工具广告前收束
175
+
176
+ - **现象**:一条流内一旦开始派发工具(工具广告落盘),思考过程的实时帧即停止(该步后续
177
+ 的思考不再实时出现,只在落盘消息里可见);无工具的步骤全程实时。
178
+ - **原因**:客户端 fold(`ClientAssistantStream`)把活跃 attempt 期间到达的 assistant/message
179
+ 暂存进 pending,而 end 帧只消费一条结算——广告消息不收束会滞留到下一步,触发
180
+ `events.restart()` 整窗重建(比"提前收束"更伤体验)。
181
+ - **取证**:`src/entry/loop.ts` 的 `#frameEndAbandonedIfOpen`;`test/v031-display.test.ts` R3。