@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/CHANGELOG.md ADDED
@@ -0,0 +1,497 @@
1
+ # Changelog
2
+
3
+ 本项目遵循 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/) 与 [语义化版本](https://semver.org/lang/zh-CN/)。
4
+
5
+ ## [0.3.1] - 2026-11-18
6
+
7
+ **桌面端思考过程显示修复 + 任务半途截断修复 + 第三方评审反馈修复合集。** 三部分内容并入
8
+ 同一补丁版本:评审反馈修复(只动评测产物与文档,不改运行时行为)、思考过程显示修复与
9
+ 截断修复(改运行时行为,见下)。
10
+
11
+ ### Fixed(任务半途截断 —— 占位 final / 过期 final / 重复命令)
12
+
13
+ **现象**:任务做到一半就"收尾",用户侧看到的最终答案是一句 `placeholder`;桌面端过程区
14
+ 里还能看到裸的 `</tf-bash>` 之类协议残片。取证实录:模型第 4 步写下
15
+ `<tf-final id="f1" summary="placeholder"/>`,之后又继续跑了 3 步,而那条过期 final 仍是
16
+ "最后一个 ok 的 final",回合结束时被当作交付答案落盘。
17
+
18
+ 四个根因,逐一修复:
19
+
20
+ - **占位 final 被照单全收**:`tf-final` 只要有 `id` 就算收敛,summary 是空串/占位词也照样
21
+ 交付。新增 `kernel/final.ts`(纯函数、零 IO)做 summary 质量闸:空 → `empty`,
22
+ 占位形态(`placeholder` / `占位` / `TODO` / `TBD` / `N/A` / `待补` / 纯标点 …)→
23
+ `placeholder`;判据刻意保守,`done`、`已完成` 这类短答案一律放行(不猜"答案够不够详细")。
24
+ 被拒 → 注入 `[tf-stream:error]` 结构化原因(要求写最终答案原文),同类拒绝只注入一次;
25
+ 模型屡教不改 → 回合以 `blocked` 如实收场,绝不再把占位当交付。
26
+ - **过期 final 仍被当答案**:新增回合级命令序(`#cmdOrder` / `#lastFinalOrder` /
27
+ `#lastNonFinalOrder`)——一条 final 之后又发出过任何非 final 命令,这条 final 即判
28
+ `stale`(答案已过期),必须在本流末尾重新声明;`tf-final` 候选同时按**回合归属**过滤,
29
+ 上一回合的 final(含 resume 回放 `turn=0`)不得充当本回合答案。同 id 覆盖式重发会刷新
30
+ final 序,不再被误判过期。
31
+ - **重复命令空手而归**:观测内容只在"易变尾"注入一次,跨请求即消失(历史里只剩句柄目录行);
32
+ 模型丢上下文后最自然的动作就是把同一条 read/glob 再发一次,而旧实现只回
33
+ `duplicate-idempotent(handle=…)`——内容拿不到,于是原地打转直到用占位 final 收场。
34
+ 新增 `#queueReplay` / `#materializeReplays`:幂等语义不变(**不重复执行**),但把原结果
35
+ 按既有上限回灌一次(`[tf-stream:replay]`,带 handle 与 `tf-peek` 指引),每回合上限 4 次,
36
+ 超限记 `replay-capped` 不静默。回灌**延迟物化**——只有真正要发下一次请求时才 `peek`,
37
+ 收敛/阻断路径直接丢弃,不占 `injected` 计数(口径仍是"确实进入模型上下文的观测负载")。
38
+ - **孤立闭合标签落进正文**:模型给自闭合命令又补一次闭合(或手写残片)时,`</tf-xxx>` 在
39
+ ground 态没有配对打开,旧 parser 判 prose 透传 → 以纯文本落进 assistant/message。
40
+ 现在按 `malformed(stray-close-tag:<name>)` 记账后丢弃,跨 chunk 与流末尾半截同样处理;
41
+ `</div>` 这类普通 HTML 闭合不受影响。
42
+
43
+ 回归:298 用例全绿,新增 8 条——`K1` 占位 final 被拒后重发真答案、`K2` final 后又发命令判
44
+ 过期、`K3` 重复命令回灌原结果、`K4` 屡教不改不交付占位答案;解析器侧 4 条(孤立标签 / 跨
45
+ chunk / 流末半截 / HTML 闭合不误伤)。
46
+
47
+ ### Fixed(思考过程显示 —— 桌面端"乱码"bug)
48
+
49
+ **现象**:electron 桌面端跑 stream 模式时,模型的思考过程显示错误,输出内容大多是乱码。
50
+ 取证(本机会话日志 `~/.dsh/sessions/` 真机样本 + 宿主渲染面源码)定位到三个根因,逐一修复:
51
+
52
+ - **思考过程被丢弃**:驱动器对 `reasoning-delta` 只计体积(`reasoningChars`)不落盘,
53
+ 而桌面端思考区只认 assistant 消息里的 `{type:'reasoning'}` 内容块(取证:
54
+ `dsh-client-ui-chat/src/client/conversation-nodes/event-projection.ts:117`)。本版把
55
+ reasoning delta 按块捕获,随 assistant/message 落成首个内容块(块序镜像内建
56
+ BlockAssembler:思考先于正文;中断路径的部分思考同样落盘)。
57
+ - **协议标记与 DSML 噪声进正文**:0.3.0 把整段流原文(含 `<tf-*>` 标记)落成消息文本;
58
+ 模型偶尔混入的原生调用格式 `<||DSML|| …>`(全角竖线)在桌面端渲染成乱码,协议
59
+ 标记则被 Markdown 渲染器吞掉或显示破碎。两处修复:
60
+ - **落盘正文纯 prose 化**:assistant/message 只落解析器的 prose 事件(命令事实仍完整
61
+ 记在 `plugin:tf-agent/*` 台账,会话事实层不丢、resume 重放不受影响);
62
+ - **parser DSML 归一化**:`<|…DSML…>` 形态一律不作为 prose 透传——
63
+ `<||DSML|| invoke name="tf-xxx" …>` 改写回等价 tf-* 头部(命令不丢),
64
+ 其余包装行按 `malformed(dsml-wrapper)` 记账后丢弃(只进台账,不注入、不打断流)。
65
+ - 协议文本补第 7 条规则:禁止输出 DSML/原生调用格式(省输出 token,治本)。
66
+ - **无实时流**:驱动器从不发 `agent/assistant-stream` 帧,桌面端在整个流期间没有 live
67
+ 内容(内建 loop 的思考区 live 数据源就是这套帧)。本版补发:start → 逐 reasoning-delta
68
+ chunk → end。契约对齐宿主两端 fold(`SessionAssistantStreamAccumulator.accept` 要求
69
+ revision 逐帧 +1、chunk index 逐块 +1;客户端 `ClientAssistantStream.acceptFrame`)。
70
+ 两条自保语义:**正文不逐帧透传**(流文本是协议标记,实时显示会闪现乱码);**工具广告
71
+ 前收束 attempt**(广告是流中落盘的 assistant/message,落在活跃 attempt 内会被客户端
72
+ fold 暂存进 pending 且 end 帧只消费一条结算 → 滞留到下一步触发 `events.restart()` 整窗
73
+ 重建)。发射异常熔断(本会话不再发),无端口/无监听器是 no-op——headless/离线零影响。
74
+
75
+ ### Fixed(评审反馈)
76
+
77
+ - **评测产物 GBK 乱码**:`eval/tools/runner.cjs` 有 7 处输出文案、`eval/RESULTS.md` 有 10 行
78
+ 「cached 字段」取证行是早期 GBK 编码残留的替换字符(U+FFFD),grep 不到、无法检索。
79
+ 已还原为中文;并把 46 个 `metrics.json` 与 5 个 `summary.json` 里的同类 `note` 字段一并迁移
80
+ (**只改文案,数字与口径未动**)。`runner.cjs` 的**代码注释**仍有历史乱码(不可逆,不影响执行),
81
+ 后续重写该文件时清理。
82
+ - **`gen-results.cjs` 覆盖证据文档**:它默认写 `eval/RESULTS.md`,而 §6(0.3.0 复算)是人工追加段,
83
+ 重跑新批次会整段丢失。新增 `--out <路径>`,并对「目标含 §6」直接拒写(需 `--force` 才覆盖)。
84
+ - **RESULTS.md 两处误读点**:`replay` 列改为 `metrics.json` 回填后的复算值(对照臂 10/10 PASS),
85
+ 并加注记说明与历史 FAIL 快照的区别;`stream/W1`、`stream/C2` 的 `exit=1` 行链到
86
+ [docs/limitations.md](docs/limitations.md) 第 2 条(重入预算护栏耗尽,产物 checks 判 PASS,不是任务失败)。
87
+ - **`eval/GATE-0.3.0.md` 自相矛盾**:模板写「回退演练:已执行」但复选框是 `[ ]`,等于假记录。
88
+ 改为「未执行(待真机)」,与 G6 判定一致。
89
+ - **§6.1 的 `summary.json` 没写路径**:补成 `eval/runs/2026-11-15-v02/summary.json`(该文件本已入库)。
90
+
91
+ ### Added
92
+
93
+ - **`eval/tools/machine-test.cjs`**:单项目实机对照——默认配置下「插件关 / 插件开」两臂各跑 1 次,
94
+ 自动 `summarize` + `gen-results --out`(不碰 `eval/RESULTS.md`),产出
95
+ `eval/runs/<stamp>/machine-test-report.md`。支持 `--plan`(不读 key)/ `--report-only` / `--runs`;
96
+ key 只进子进程环境变量,日志只印后 4 位。
97
+ - **`eval/machine-test-2026-11-17.md`**:本轮实机测试手册(两臂定义、命令、判读顺序、红线、故障排查)。
98
+
99
+ ### Changed
100
+
101
+ - **CI 覆盖面**:`.github/workflows/ci.yml` 新增 `npm run check` 与 `npm run gate -- --offline`;
102
+ `gate.mjs` 增加 `--offline`(只判 G1–G3:装配一致性 / 单 loop 权威 / 卸载原子)。
103
+ G4(tag=package)只在发布提交上成立、G5/G6 需真机数据,故不进 CI,仍由发布流程与真机复测守。
104
+
105
+ ## [0.3.0] - 2026-11-17
106
+
107
+ **独立模式 + 全量升级条目。** 交付形态固定为 A-1(专用 profile);按
108
+ `upgrade-plan/`(alpha.1 → alpha.2 → beta.1 → beta.2 → 0.3.0)完成 M/S/K/F/R 五组全部条目,
109
+ 并把 **0.4.0 规划的 F5/F6/F7 一并实施**(合并产出,最终版本号标记 0.3.0,
110
+ 实施对照见 `docs/v0.4.0-plan.md`)。
111
+
112
+ 另含**会话日志格式修复(发布前并入,不单独发版)**:0.3.0 开发期写出的会话日志在宿主
113
+ v4 校验下被判 corrupt(`tool/call <id> has no advertised tool lifecycle`),桌面端点开历史
114
+ 对话报"加载失败";本版修正写入路径,并附存量日志修复脚本。
115
+
116
+ ### Added
117
+
118
+ - **独立装配(S 组)**
119
+ - **专用 profile 模板(S1)**:`profiles/stream`(web 入口)与 `profiles/stream-headless`;
120
+ 组合顺序 `dsh-base → 主 bundle → preset bundle → 入口`;`agent-loop` 停用只在主 bundle
121
+ patch(C4 卸载原子),profile patch 只承载 registry 默认值覆盖。
122
+ - **安装前置校验(S2)**:`scripts/install-check.mjs` —— 允许列表只有 `stream` /
123
+ `stream-headless`;误装 `web`/`desktop` 100% 被拒(含原因与允许列表);dry-run 打印
124
+ 目标 profile、组合包、patch 与受影响 entry;只读不写,无"强制安装"开关。
125
+ - **`preset-stream` 独立 bundle(S4)**:`preset/stream/` —— 只声明映射工具面
126
+ (tool-fs(applyPatch 开)+ tool-fs-search + pwsh/bash 平台二选一);preset 行不进主
127
+ bundle patch(B 形态不污染既有 profile);registry 默认值由 profile patch 覆盖指向
128
+ `stream`;headless 不引入 preset。
129
+ - **装卸与回退(S6)**:`scripts/install-cycle.mjs` —— 10 轮 add → 启动自证 → remove →
130
+ 恢复验证;回退路径 = 回退 0.2.x 产物或删 profile,不手工修 profile。
131
+ - **双 loop 具名诊断(S3)**:`setFactory` 冲突转 `E_DOUBLE_LOOP`(Error.name),
132
+ 携带 profile 标识(宿主 profileContext / env DSH_PROFILE)、冲突来源与处置建议;
133
+ 不 catch 后继续、不自动重试。
134
+ - **禁用行审计(S5)**:`docs/disabled-lines-audit.md` —— 逐行记录依赖与结论;审计后
135
+ 放弃 0.2.x 计划的全部"候选停用行"(宿主提示行不进请求,停用无 token 收益);
136
+ PTC 四行 / compaction 四行同族同进同退。
137
+ - **能力面(F1–F4)**
138
+ - **`tf-edit` / `tf-append`(F1)**:精确替换(OLD/NEW 标记块,映射宿主 `edit`)与
139
+ 只追加(anchor 锚点插入或 EOF 追加,映射宿主 `edit` / `apply_patch` `*** End of File`
140
+ 锚);匹配失败结构化报错,不做模糊匹配、不静默改全文;编辑成功只回回执。
141
+ - **`tf-grep` / `tf-glob`(F2)**:映射宿主 fs-search,只回匹配行(带行号)/ 路径,
142
+ 不回全文;协议文本明写"不要用 tf-bash 做搜索"。
143
+ - **code 结果可见性(F3)**:仅 tf-code 显式开启时,首成功/变化值 ≤4000 字符
144
+ (`codeValueInjectLimit` 可配)完整注入,省一次 tf-peek 往返;超限转骨架 + 句柄。
145
+ - **原生通道上限(F4)**:声明 `nativeToolSchemas` 时,原生 tool_call 单块结果
146
+ > 6000 字符(`nativeResultLimit` 可配)→ obs 句柄化 + 骨架,杜绝全量回灌后门。
147
+ - **中性能力(0.4.0 规划条目,随本版实施)**
148
+ - **计划与验收(F5)**:`tf-plan` 命令(body = `- [id] 验收项` 行)+ 公共属性
149
+ `accepts`(任意命令可声明验收关联);计划状态放驱动器侧,请求**只注差分**
150
+ (新计划全量一次,此后只注新增/已验证/已移除;无变化不产生块);验收项只能被
151
+ **命令成功回执**验证(模型自述不算证据);有未验证验收项时 `tf-final` 判过早;
152
+ `enablePlan: false` 回退点。
153
+ - **恢复意图(F6)**:新增 `entry/intent-log.ts` —— 变更类命令(tf-write/tf-edit/tf-append)
154
+ 派发**前**意图 fsync 落盘(`<stateRoot>/intents/<session>.jsonl`:op/path/内容指纹),
155
+ 落定即回执;resume 发现"有意图无回执" → **停机核对**(`runTurn` 直接 blocked,
156
+ 不发请求、零注入、不自动重放);CLI `dsh-stream-agent intents`(三态判定列出)/
157
+ `intents --ack <session>` 人工确认闭合;三态 = 未发生 / 已发生 / 不确定(强杀三时点
158
+ 可区分);`enableIntents: false`、`resumeIntentPolicy: 'ignore'` 回退点;
159
+ 强杀演练 `eval/tools/f6-kill-drill.cjs`(10 轮 SIGKILL × before/mid/after-write 三时点,
160
+ 离线零 API 已跑:0 重放、0 重复写)。
161
+ - **长会话段边界(F7)**:先出 **ADR-001**(`docs/adr-001-segment-boundary.md`,
162
+ 采纳"整块丢弃"、拒绝宿主压缩与摘要改写);`render.ts` 新增 `dropAppendHead()`
163
+ (整块 + policyLog 记录 + 前缀基线重置——唯一合法的前缀重置入口,未记录的漂移仍
164
+ fail-closed);驱动器 `segmentMaxChars`(默认 160k 字符 ≈ 40k tokens,0 = 关闭)在
165
+ 新回合开始处整块丢弃旧段;被丢弃原文 obs 句柄化(`obs:read:seg-*`)可
166
+ `tf-peek` / `peekHandle()` 回取;`appendBlockCount` / `appendChars` 只读投影;
167
+ 测试:50 回合 × 2 请求 = **100 请求 0 前缀违规**,末/首请求 ≤1.5×。
168
+ - **计量与治理(M 组 / R 组)**
169
+ - **M1 四分量计量**:`eval/tools/summarize.cjs` —— 逐请求 usage 原文求和
170
+ (输入/缓存读/缓存写/输出),标题旁路剔除,缺失分量标"不可得"不按 0 计;
171
+ 产出 `summary.json` + Markdown 表;`eval/RESULTS.md` §6 以 2026-11-15-v02 批次复算
172
+ (基线 446,410 → 插件 129,178 = 28.9%,与历史 22.3% 批次的不可比性如实说明)。
173
+ - **M3 replay 修复**:对照臂提取器两个根因——①属性序敏感(path 必须在 id 前);
174
+ ②`text-delta` 增量字段读错(`textDelta` → 实际 `text`)——修复后对照臂回放一致性
175
+ **10/10**(树哈希 == 实跑,含 64 次写入回放);支持 tf-edit/tf-append 回放;
176
+ 提取器错误如实记"提取失败";零写入任务种子树 == 结果树即通过。
177
+ - **M2 T3 三格采集**:`eval/tools/t3-cells.cjs`(首请求拆分 system/协议段/工具 schema/
178
+ 任务四部分 + A-1a==B 逐字节判定 + 差值 == code 段长度判定);三臂 patch:
179
+ `patches/eval-stream-code-on.yml`(A-1a)/ `eval-stream-code-off.yml`(A-1b);
180
+ B 格用 v0.2.1 tag 产物;tf-code 协议段实测 1,175 字符。
181
+ - **R2 一致性检查**:`scripts/check-consistency.mjs`(`npm run check`)—— entry 集 /
182
+ inject / 装载顺序 / README 命令表四项,一条命令复跑;当前 4/4 全绿。
183
+ - **R4 发布门禁**:`scripts/gate.mjs`(`npm run gate`)—— 装配一致性 / C2 单 loop /
184
+ C8 卸载原子 / C9 tag=package / C1 token 门槛 / 回退演练六项;离线项就地判定,
185
+ 真机项(G5/G6)如实标"待人工复测",未过不发布。
186
+ - **K6 真机五场景**:`eval/tools/manual-code-scenarios.md`(成功/失败/取消/拒绝/partial,
187
+ 每场景记录 kind/账本/最终状态)。
188
+ - **测试命题**:`docs/TEST-PROPOSITIONS.md` —— A 组回归 + B 组新能力(B1 编辑、B3 搜索、
189
+ B4 计划、B5 幻觉检查、B6 五场景、B7 强杀、B8 段边界、B9 双 loop、B10 校验)+
190
+ C 组成本对照;≈2 元/命题,供人工复测。
191
+ - **会话日志修复工具(发布前并入)**
192
+ - **`scripts/repair-session-logs.mjs`:存量日志修复**。默认 dry-run,`--write` 落盘;
193
+ 为缺失广告的 `tool/call` 补入同 turn/step 的 `assistant/message`(tool-call 块),
194
+ 把误写在 `step/end` 之后的 final 答案移回 step 内,重排 seq 与全部 seq 引用
195
+ (`sourceEventSeqs` / `messageSeqs` / `throughSeq` / `headerSeq` / 压缩范围),
196
+ 写前备份 `.bak-<时间戳>`、写后清除投影缓存;设 `DSH_HOST_MODULES` 时用宿主自己的
197
+ v4 校验器复核(`restoreReleasedV4Artifact` + `assertReleasedV4Relationships`)。
198
+ 实测:本机 10 条历史会话全部修复为可读,27/27 会话通过宿主校验。
199
+ - **`test/session-format.test.ts`**:S1 正常回合的广告顺序、S2 派发前异常的
200
+ `TOOL_NOT_STARTED` 闭合、S3 final 答案早于 `step/end`;用"宿主同款"假工具管线
201
+ (start → tool/call,commit → tool/result)复核生命周期。
202
+
203
+ ### Changed
204
+
205
+ - **K1:`tf-code` 默认关闭**。`balanced` 模式的 `enableCode` 从 `'auto'` 改为 `false`
206
+ (`'auto'` 保留为兼容值、等价 false);驱动器语义改为"仅显式 `enableCode: true` 且
207
+ `executeCode` 端口在位才启用";`cordis.patch.yml` / `preset.yml` / `patches/eval-stream.yml`
208
+ 显式写 `enableCode: false`(装配断言)。默认装配协议段 0 字符,模型不会幻觉调用;
209
+ 关闭 ≠ 删除通道:`ptc-runtime` 等四行保留,`no-code-channel` 命令级失败引导改道。
210
+ - **K2 策略透传与沙箱记账**:`ptc-bridge` resolve 透传会话 cwd(session header.cwd →
211
+ workingDirectory 服务默认目录,不复制宿主优先级规则);`result.sandbox` 的
212
+ `mode`/`denied`/`enforcement` 逐次记账(新增 `sandbox` 台账记录与 DriverRecord 类型),
213
+ `enforcement=partial` 显式可见。
214
+ - **K3 失败分类保真**:`CodeOutcome` 结构化(`kind`/`retryable`/`advice`);
215
+ `classifyCodeFailure()` 逐类给出可重试结论(八类 kind 原样保留 + `ptc-runtime-misuse` /
216
+ `quota-exceeded`);注入文案 `[kind=... retry=yes|no]` + 日志尾 200 字符;
217
+ 沙箱拒绝与代码错误分开引导。
218
+ - **K4 取消链路**:驱动器新增回合级 `#turnController`(runTurn 创建、cancel abort、
219
+ finally drain 等待在途清理再释放);tf-code 与 executeTools 派发共用回合 signal,
220
+ 替换原"独立且永不触发的 AbortController";取消类错误识别(`isAbortError`)与超时分账。
221
+ - **K5 配额**:`codeQuota`(maxSubcalls/maxOutputBytes/maxWallMs,缺省 64 / 256KiB / 300s);
222
+ 配额在绑定调用与结果两侧硬终止(程序内吞掉配额错误也照样结构化终止),
223
+ 墙钟经自铸 controller abort 传导,与宿主 timeout 独立记账。
224
+ - **协议文本**:命令表新增 tf-edit/tf-append/tf-grep/tf-glob/tf-plan 与"计划与验收"节;
225
+ 修正 v0.1 遗留的过时描述("tf-read 成功不回灌"→ 实际首版/变化完整注入);
226
+ tf-code 段补配额与沙箱事实说明。
227
+ - **护栏按回合重置(F7 测试实抓的真 bug)**:`#reentryCount` / `#finalNudges` /
228
+ `#finalOnlyRequests` 在 `#turnLoop` 入口清零——此前跨回合累计,多任务长会话会在
229
+ 第 N 个回合被历史计数误杀(blocked 重入上限)。
230
+ - **版本**:`package.json` / `src/version.ts` → 0.3.0;`files` 增加 `profiles/` 与 `preset/`;
231
+ `scripts` 增加 `check` / `gate`(另有并入的 `repair-session-logs.mjs` 存量日志修复);
232
+ engines 维持 `dsh >= 0.2.2-rc.1`。
233
+ - `preset.yml` 与 `cordis.patch.yml` 对齐(stream-agent inject 补 `sessionProjections`,
234
+ 与 0.2.1 真机验证过的装配形态一致)。
235
+ - **兼容性(会话日志)**:装配、协议、配置项全部不变(`enableCode` 仍默认关闭)。0.3.0 起
236
+ 写出的日志可被 0.2.x 读取(新增的只是合法的 `assistant/message` 事件);0.2.x 及 0.3.0
237
+ 发布前的开发期产物写出的旧日志仍需跑一次 `repair-session-logs.mjs` 才能加载。
238
+
239
+ ### Fixed
240
+
241
+ - **M3 对照臂 replay 0/10 → 10/10**(详见 Added/M3)。
242
+ - **多回合护栏误杀**(详见 Changed/护栏按回合重置)。
243
+ - **F6 演练脚本与 t3-cells 的 Windows 路径 / 事件循环问题**(file:// URL 导入、
244
+ Atomics.wait 阻塞 stdout 事件)。
245
+ - **会话日志 v4 工具生命周期(致命,桌面端"历史加载失败"的直接原因)**
246
+ - **工具调用生命周期缺失**:驱动器把 tf-* 命令映射成宿主工具后直接调
247
+ `ctx.tools.execute`,由宿主管线写 `tool/call` + `tool/result`,却从未写 v4 格式要求的
248
+ `assistant/message`(content 带 `tool-call` 块)。`dsh-session-format-v3-to-v4` 的
249
+ `tool()` 在读取时抛 `tool/call <id> has no advertised tool lifecycle` → 整条日志被判
250
+ corrupt;表现是会话列表能列出、点开却"历史加载失败"。现在每次派发**前**先广告同名
251
+ 同参的 tool-call 块(`advertiseToolCalls`);派发异常 / 批次缺项时用 `repairToolCall`
252
+ 闭合生命周期——未开始 = 宿主唯一接受的 `TOOL_NOT_STARTED` 修复形状
253
+ (`message.id = interrupted-tool-result-<callId>-<n>`、`isError:true`、
254
+ `error.code = TOOL_NOT_STARTED`),已开始 = 普通错误结果,已有 result 不重复写。
255
+ 原生 `tool_call` 通道的调用块随同一条 assistant 消息一起广告。
256
+ - **final 答案写在 step/end 之后(同类 corrupt)**:`finalAnswer` 原在 `step/end` 之后写
257
+ `assistant/message`;v4 要求该事件落在打开的 turn+step 内(否则读取时抛
258
+ `assistant/message does not match an open turn and step`)。收束判定前移到
259
+ `step/end` 之前写出。
260
+ - **不可重试流错误的 step/end 早于在途工具**:fail-fast 分支先写 `step/end` 再结束,
261
+ 流中途已派发的 `tool/call` 会在 `step/end` 之后才落 `tool/result`(同一类 corrupt)。
262
+ 现在先 `drain()` 等在途工具落定,再写 `step/end`。
263
+
264
+ ### Security
265
+
266
+ - 安全声明收口为"文件效果边界 + 事实记账"(C5):`docs/limitations.md` §5b-1 明确
267
+ ①只覆盖文件效果(网络/进程不在范围);②Windows 档 `enforcement=partial`;
268
+ ③`danger-full-access` 无约束;④preset/profile 不是安全边界;⑤`partial` 与
269
+ `danger-full-access` 在账本与文档中显式可见;全文无"隔离/等权"表述。
270
+
271
+ ### 测试
272
+
273
+ - 275/275 全绿(+5 F5 计划验收、+5 F6 意图、+4 F7 段边界、+3 会话格式回归)。
274
+ - 离线演练:F6 强杀 10 轮通过;M3 对照臂 replay 10/10;M1 复算一致。
275
+ - 真机复测项(不阻塞本版提交,阻塞正式发布):R3 评测矩阵重跑、M2 三格、K6 五场景、
276
+ S6 十轮装卸、回退演练 —— 全部命令与命题见 `docs/TEST-PROPOSITIONS.md` 与
277
+ `eval/GATE-0.3.0.md`。
278
+
279
+ ## [0.2.1] - 2026-11-16
280
+
281
+ **装载期热修 + 控制栏。** 0.2.0 在 dsh 桌面 profile 里"装了但完全不能用"
282
+ (`1 entry did not activate stream-agent`),根因是两个独立的 Cordis 4.x 契约违约;
283
+ 本版把两者都修掉,并补上给新用户看的控制栏(四模式 + 中英切换 + 桌面控制页)。
284
+
285
+ > 注:本节末尾的"模式标注(saving/availability)"与 `wrapText()` 重写两节在 v0.2.1 tag
286
+ > 之后完成,随 0.3.0 一并发布(R1 纪律:不追溯移动已发布 tag)。
287
+
288
+ ### Fixed
289
+
290
+ - **可选服务裸读(致命,桌面端装载失败的直接原因)**:`apply()` 里写的是
291
+ `(ctx as { ptcRuntime?: unknown }).ptcRuntime ?? ctx.get?.('ptcRuntime')`——
292
+ `??` 左侧先求值,而 Cordis 4.x 的 context 是 Proxy,对未 inject 的属性读取直接抛
293
+ `cannot get property "ptcRuntime" without inject`(`cordis/lib/index.js:1251-1280` 的 get trap),
294
+ 右侧兜底永远到不了。`ptcRuntime` 是可选服务(宿主不挂 PTC 时不存在),于是 entry 装载期抛错。
295
+ 新增 `entry/cordis-compat.ts` 的 `getService()`:只走 `ctx.get(name)`(reflect.get 无 inject 要求),
296
+ 属性回退包在 try/catch 里兼容测试桩;loop / state-handle / action-gate 的
297
+ `ptcRuntime` / `loader` / `sessionProjections` / `agentDefaultModel` / `storage` / `logger`
298
+ 全部改走它。
299
+ - **函数式插件返回值违约(致命,被第一个缺陷掩盖)**:五个 entry 结尾都 `return { ...句柄 }`。
300
+ Cordis 把函数式插件的返回值当 **effect** 收集(`cordis/lib/index.js:431-459`),
301
+ 只接受 function / null / thenable / iterator,普通对象直接
302
+ `TypeError: Invalid effect`(:460)。新增 `asPluginEffect()`:把句柄包成一个可调用 disposer,
303
+ 句柄属性原样挂在函数上——测试与调用方读取方式不变,Cordis 侧拿到合法 effect。
304
+ - **后果链(如实记录)**:entry 抛错 → fiber 进 failed 态 → `setFactory` 注册被回滚 →
305
+ bundle 里内建 `agent-loop` 已被停用 → 该 profile 一个 agent 都创建不出来。
306
+ 两个缺陷任一存在都会导致同一现象,日志只显示先抛出的那一个。
307
+
308
+ ### Added
309
+
310
+ - **控制栏(`entry/control-bar.ts` + `dsh-stream-agent` 命令)**:装载时在 stderr 打印
311
+ 引导面板(接管状态 / 当前模式 / 上手四步 / 打开方式),并提供交互栏
312
+ `dsh-stream-agent bar`——1-4 切模式、Up/Down 移动、Enter 应用、`l` 中英切换、
313
+ `?` 全模式指南、`r` 重置、`q` 退出;另有 `status` / `mode <id>` / `lang <zh|en>` / `--json`。
314
+ - **四个运行模式**(`kernel/modes.ts`,只映射既有配置项):`balanced` 均衡(默认)、
315
+ `lean` 精简(60k 预算阶梯)、`compat` 兼容(全文回验 + 串行)、`power` 增强(显式开 tf-code)。
316
+ 模式只提供默认值,装配里显式写的配置永远压过模式。
317
+ - **每个模式标注「省多少 token / 能不能用」**:`saving`(most / more / baseline / least,四档)
318
+ + `availability`(默认模式 / 开箱可用 / 需宿主 PTC)+ 一段 `note` 说明口径。四处渲染同源
319
+ (`modeBadges()`):装载引导面板一行、交互面板展开当前模式全文、`?` 帮助页逐模式一行、
320
+ 桌面模式卡两行 + 标注块。**口径如实**:只有「默认参数 vs 原生 loop」有十任务两臂实测
321
+ (约 29%),其余三档是方向性判断并明写"未单独实测"——不把没测过的数字写成百分比。
322
+ - **模式目录单一投影**(`publicModeCatalog()`):此前 loop 与 `ui/index.js` 各写一份 map,
323
+ 加字段必漏一处;现在 CLI `--json`、控制路由、桌面页共用同一份字段(`config` 不进网络载荷)。
324
+ - **中英双语**(`kernel/control-bar.ts`):面板、引导、帮助、状态条、`--json` 全量双语;
325
+ `l` 键或 `dsh-stream-agent lang en` 即时切换,落盘到 `control.json`,三个面(装载横幅 /
326
+ CLI / 桌面控制页)共用同一份状态与文案表——不存在"横幅中文、命令英文"的错位。
327
+ - **桌面客户端控制页(`ui/` 子包)**:左侧栏新增「控制栏 / Control bar」滑杆图标,点开是整页:
328
+ 接管状态、当前模式与来源、六个生效参数、状态文件路径、更新时间、四张模式卡(含"什么时候选 /
329
+ 代价")、中文/English 切换、刷新与 CLI 等价命令。页面走 dsh 自己的客户端插件机制
330
+ (`dsh.client` + `ctx.slots` 的 `main` / `sidebar.panellist`),**不修改 Electron 壳、不重打包
331
+ 客户端**。写路径经 `streamAgentRuntime` 服务回到 loop(内存 + `control.json` 单一事实源),
332
+ 支持 `updatedAt` 并发栅栏(多窗口 409 刷新;文件尚未写入时以 `null` 作为期望值,
333
+ 语义是"首次写入",别人先写过就判过期)、装配/环境变量锁定置灰、loop 未接管时的只读降级。
334
+ **已在真实桌面窗口完成人工验收**(左侧栏图标 / 整页 / 四张模式卡 / 中英切换 /
335
+ 明暗主题 / 重启后保留)。可行性评估与边界见 `docs/desktop-ui-feasibility.md`。
336
+ - **状态落盘**:`<stateDir>/control.json`(`{ mode, lang, schema, updatedAt }`),
337
+ 优先级 `装配 config > STREAM_AGENT_MODE/LANG > control.json > 内置默认`;坏文件告警后回默认,
338
+ 绝不让"配置文件坏了"阻断装载。
339
+ - **接管事实登记**(`entry/takeover-registry.ts`):控制栏横幅的"接管生效 / 未接管"读实时事实,
340
+ 不靠时序猜测;`onTakeover` 订阅保证控制栏排在 loop 前后挂载都能正确显示。
341
+ - 测试 +47 例(`test/activation.test.ts` 10 例 + `test/control-bar.test.ts` 26 例 +
342
+ `test/desktop-ui.test.ts` 11 例),含"严格 inject 守卫 ctx"的装载回归与
343
+ "主包不得声明 dsh.client / UI bundle 语法 / 路由鉴权与 409 / 首次写入语义 / 中英文案键集对齐 /
344
+ 模式标注与投影一致 / 折行不切英文单词且行首无标点"的桌面页回归。
345
+ 全量 255/255。
346
+
347
+ ### Changed
348
+
349
+ - `package.json`:版本 0.2.1;新增 `bin: { "dsh-stream-agent": "./dist/entry/control-bar-cli.js" }`;
350
+ `files` 增加 `ui/`。
351
+ - `cordis.patch.yml` / `preset.yml` / `patches/takeover.yml`:新增 `stream-agent-control-bar` 与
352
+ `stream-agent-ui` 两个 entry(共 7 个),control-bar 排在 loop 之前装载;UI 必须独立成子包,
353
+ 因为 `dsh-client-modules` 以包为单位扫描,同包多 entry + `dsh.client` 会抛多源错误。
354
+ `preset.yml` 的行序同步调回 `sidecar → control-bar → ui → loop`(原文件把 loop 排在 sidecar
355
+ 之前,与文件自己的装载顺序注释相矛盾)。
356
+ - `loop` 配置新增 `mode` / `lang`;`maxParallelToolCalls` / `maxReentries` / `budgetTokens` /
357
+ `selfReadFeedback` / `enableCode` / `persistFallback` 的取值改为
358
+ `显式配置 ?? 模式预设 ?? 内置默认`;`resolveEffective()` 改为每次创建 driver 时重算,
359
+ 桌面页切模式后新会话立即生效。
360
+ - `control-state.ts`:新增 `langSource` 与 `updatedAt`(并发栅栏);来源联合类型增加
361
+ `runtime`,表示"本进程内已生效但落盘失败"。
362
+ - `scripts/build.mjs`:增加桌面页构建闸门(主包禁止 `dsh.client`、UI 包声明、
363
+ `ui/index.js` 可导入、`ui/client.js` 语法与模块 id)。
364
+ - 接管横幅追加 `mode=<id> (<来源>)`,排障时一眼看出模式从哪来。
365
+ - `wrapText()` 重写为"先切单位再贪心填充":宽字符逐字可断、ASCII 单词/路径不切开、
366
+ 闭合标点粘住前一个字(行首不出现标点)、末行不留孤字;`labeled()` 支持统一标签宽度,
367
+ 同一块里"当前/适合/省 token/可用性/标注"的值列左对齐。旧实现遇空格回退,中文里夹
368
+ `ctx.ptcRuntime` 这类 token 时行尾会留十几列空白,一屏里好几行右端参差。
369
+
370
+ ## [0.2.0] - 2026-11-16
371
+
372
+ 四个已知限制的定向修复(README「已知限制」1–4 ↔ `docs/limitations.md` 1/3/5/7),
373
+ 外加 `tf-code` 程序化执行通道(PTC 桥接)。
374
+
375
+ ### Added
376
+
377
+ - **自写回验 receipt(O7,修「写批任务 token 偏重」)**:`tf-read` 命中本任务 `tf-write`
378
+ 已写过的路径时,不再回灌全文——全文本来就在模型上下文里,改为注入回执
379
+ (`[tf-stream:receipt]`,行数 + sha256 指纹),掐断"写 → 读回验 → 再改"循环;
380
+ 协议文本新增"回验纪律"。读外部文件的完整反馈保持不变;`selfReadFeedback: 'full'`
381
+ 可恢复 v0.1 行为。默认开启。
382
+ - **steer 语义对齐内建(修"插队队首、回合边界生效")**:回合运行中收到 steer → 注入
383
+ 运行中回合的**下一请求**(追加区 `[tf-stream:steer]` 用户块,前缀单调不破;带未消费
384
+ steer 时不允许收敛);单流"流内不打断"(不掐当前流)前提不变。空闲时保持原语义
385
+ (插队队首、当新回合任务)。`inbox.nextStep` 如实暴露未消费 steer。
386
+ - **本地持久化兜底(修"持久化依赖宿主 storage")**:新增 `entry/json-persistence.ts`
387
+ (零依赖)——宿主缺 storage backend 时 state-handle 降级本地 JSON 文件 KvUnit
388
+ (durable,跨会话 resume 可用);宿主缺 `sessionPersistence` 时 AgentFactory 用本地
389
+ JSONL 会话日志(create 落盘、resume 冷读,事件经 `withEventCapture` 镜像),headless
390
+ 跨会话 resume 真正可用。状态根目录:`STREAM_AGENT_STATE_DIR` env → `~/.dsh-stream-agent`;
391
+ `persistFallback: false` / `localFallback: false` 可关闭(回 v0.1 内存降级)。
392
+ - **本地文件台账(修"bundle 形态 plugin record 降级内存")**:`attachSessionLedger` 改走
393
+ 宿主 loader 三级同源解析(`loader.import` → `loader.internal.import` → 动态 import,
394
+ 与 dsh-scope 同款);仍不可达时降级**本地 JSONL 文件台账**(可重放,不再是易失内存),
395
+ resume 时 `rehydrateRecords` 把 final 答案回灌新驱动器(同 id 新 summary 覆盖,
396
+ last-wins 语义与运行中一致)。
397
+ - **`tf-code` 程序化工具调用(PTC 桥接)**:把宿主 PTC runtime(`ctx.ptcRuntime` 服务缝,
398
+ `@deepseek-ai/dsh-ptc-runtime`)收编为单流协议的执行通道——模型在流里写
399
+ `<tf-code id="c1" description="...">(async TS 函数体)</tf-code>`,闭合即派发到 runtime
400
+ 沙箱执行,返回值(无损 JSON)句柄化进 obs 账本(新 `code` 族:首个/变化结果注骨架,
401
+ 失败一律 high),中间结果不进上下文。
402
+ - 绑定命名空间 `tools`(write/read/pwsh)走驱动器同一条 `executeTools` 通道——宿主
403
+ guard/工作区策略/凭据全部生效(安全面与 PTC 模式等权:程序自身不做任何直接 IO)。
404
+ - 协议文本按通道可用性声明:`executeCode` 端口在位才追加 tf-code 段(稳定前缀构造期
405
+ 冻结,通道不存在就不会被模型幻觉调用);`enableCode: false` 强制关闭。
406
+ - 通道缺失/形状不符时 tf-code 命令级失败(`no-code-channel`)并引导改道 tf-bash,
407
+ 告警不静默(fail-open,红线 5)。
408
+ - 测试 208 用例(新增 `test/fix-limits.test.ts` 11 例 + `test/ptc-bridge.test.ts` 10 例 +
409
+ A2/A4 更新为修复后语义)。
410
+
411
+ ### Changed
412
+
413
+ - `apply` 配置新增 `selfReadFeedback` / `persistFallback` / `stateDir`;
414
+ `state-handle` 配置新增 `localFallback` / `stateDir`。
415
+ - 本地兜底默认开启:首次使用会在状态目录创建 `sessions/`、`ledger/`、`storage/` 子目录。
416
+
417
+ ### Design
418
+
419
+ - 与官方 PTC 模式(`run_code` 工具,`dsh-tool-executor-ptc`)正交互补:PTC 改"工具调用
420
+ 介质",tf-code 改"循环层"——单流协议负责编排(depends_on / 隐式写序 / 前缀单调),
421
+ 重型数据加工下沉到 PTC runtime,两层优势叠加而非二选一。
422
+
423
+ ## [0.1.1] - 2026-11-15
424
+
425
+ 首次发布到 npm(`@hugesb/dsh-stream-agent`)。
426
+
427
+ ### Fixed
428
+
429
+ - **桌面端 preset 层工具解析失败**:agent 作用域改用宿主同源 `dsh-scope` 铸造,key 取 agent
430
+ 实例本身(镜像内建 `createScope(loopCtx, this)`)。此前作用域 key 不是 agent 实例,
431
+ 宿主工具执行器 `selectExecutor(input.agent)` 与守卫 `chainLayers(exec.agent)` 走
432
+ `scopeChainOf(agent)` 时永远落到根层,而 desktop/web 组合的根层不含 `write`/`edit`/`pwsh`
433
+ (这些在 `standard.patch.yml` 的 preset 层),表现为「工具已注册但不可达」。作用域在
434
+ `dispose` 时一并释放;铸造失败回退 ownerCtx 并留痕告警,不影响 headless/fake host。
435
+ Electron 桌面客户端真连实测通过。
436
+
437
+ ### Added
438
+
439
+ - `README.en.md`:英文 README,与中文版同结构。
440
+ - 仓库发布脚本(一条命令完成构建 → 测试 → 版本校验 → GitHub 推送 + tag + Release → npm 发布)。
441
+
442
+ ### Changed
443
+
444
+ - npm 包名从 `@54dsb1/dsh-stream-agent` 改为 `@hugesb/dsh-stream-agent`(`54dsb1` 是 GitHub
445
+ 账号,npm 侧对应账号为 `hugesb`,scope 必须与 npm 账号一致)。README、`preset.yml` 注释与
446
+ 架构图中的包名同步更新;GitHub 链接保持 `54dsb1` 不变。
447
+
448
+ ## [0.1.0] - 2026-11-15
449
+
450
+ 首个可安装版本。上游锚点 `@deepseek-ai/dsh@0.2.2-rc.1`(类型)/ rc.3(运行时实测)。
451
+
452
+ ### Added
453
+
454
+ - **内核层**(`src/kernel/`,零框架依赖,可单独摘出单测)
455
+ - `state.ts` 内容寻址状态树与句柄
456
+ - `obs.ts` `info_gain` 分类与观测账本
457
+ - `parser.ts` `tf-*` 单流协议解析器(协议语法的唯一权威)
458
+ - `gate.ts` 可逆性判定(read/spec/commit/fatal)与一次性凭据
459
+ - `render.ts` 三段式装配与 prefix 单调校验器
460
+ - **适配层**(`src/entry/`,薄壳只做翻译):`loop.ts` AgentFactory + 单流驱动器、`obs-broker.ts`
461
+ 泄漏扫描与结果登记、`action-gate.ts` ToolsService guard、`state-handle.ts` `ctx.state` 服务、
462
+ `context-render.ts` O6 第二见证与 O4 动态冻结、`mock-provider.ts` 离线假模型、`eval-probe.ts`
463
+ 评测取证。
464
+ - **`tf-*` 命令集**:`tf-write` / `tf-read`(支持 `offset`/`limit`)/ `tf-bash` / `tf-peek` / `tf-final`。
465
+ - **O1–O6 token 优化**:观测三档返回与行骨架、`tf-peek` 按需取回、句柄目录差分注入、
466
+ 动态上下文冻结、预算分级降级、preflight 前缀断言(fail-closed)。
467
+ - **上游语义对齐**:隐式写序、重复 id 幂等、乐观 peek 延迟重试、`tf-final` 同 id 覆盖、
468
+ 过早 final 检测、错误取因。
469
+ - **官方 bundle 形态**:`dsh.manifestVersion: 1` + `dsh.bundle.patch: ./cordis.patch.yml` +
470
+ `engines.dsh`,卸载即回原生行为。
471
+ - **桌面端/web 组合适配**:agent 作用域铸造(key = agent 实例本身,镜像内建
472
+ `createScope(loopCtx, this)`——宿主工具执行器与守卫按 `scopeChainOf(agent)` 选层,
473
+ preset 层的 write/edit/pwsh 由此可达)、`modelSelection` 会话投影注册(客户端模型选择器的
474
+ 数据面)、resume 序号对账(seed 占位事件立即落盘,根除 "append seq mismatch")、
475
+ create 冲突回退 resume(桌面端草稿重试不再报 "already exists")、`steer`/`inbox`/
476
+ `runMaintenance` prompt 面补齐、默认模型三级回退与无路由 fail-fast。桌面客户端
477
+ Electron 真连实测通过。
478
+ - 测试 187 用例(`node:test`,零 API 调用),`eval/` 指标口径与 10 任务集两臂 runner。
479
+
480
+ ### Changed
481
+
482
+ - 仓库结构整理:开发/评测用的组合补丁统一收进 `patches/`,根目录只留 bundle 入口
483
+ `cordis.patch.yml` 与生产装配清单 `preset.yml`。
484
+ - 文档拆分为 [`docs/architecture.md`](docs/architecture.md)、[`docs/protocol.md`](docs/protocol.md)、
485
+ [`docs/limitations.md`](docs/limitations.md),README 只保留结论与入口。
486
+ - `engines.node` 从 `>=24` 放宽到 `>=22.18`(构建与 187 用例在 Node 22.22 上实测通过)。
487
+ - 新增 CI、`.gitignore`、`.gitattributes`、`CONTRIBUTING.md`。
488
+
489
+ ### Known limitations
490
+
491
+ 见 [README「已知限制」](README.md#已知限制) 与 [`docs/limitations.md`](docs/limitations.md),
492
+ 其中需重点注意:写批任务 token 偏重、`replay` 对真连 session log 0 命中、
493
+ bundle 形态下 plugin record 通道可能降级内存。
494
+
495
+ [0.2.0]: https://github.com/54dsb1/dsh-stream-agent/releases/tag/v0.2.0
496
+ [0.1.1]: https://github.com/54dsb1/dsh-stream-agent/releases/tag/v0.1.1
497
+ [0.1.0]: https://github.com/54dsb1/dsh-stream-agent/releases/tag/v0.1.0
@@ -0,0 +1,72 @@
1
+ # Contributing
2
+
3
+ 欢迎 issue 与 PR。改动前请先读完这几条,能省掉大部分返工。
4
+
5
+ ## 红线
6
+
7
+ 1. **不改上游源码**。一切以 plugin entry + patch 形式存在;需要新能力就加 entry,不动 `@deepseek-ai/*`。
8
+ 2. **`src/kernel/` 零框架依赖**。不许 import 任何 `@deepseek-ai/*`;它必须能被单独拷出去跑单测。
9
+ 3. **禁止"智能压缩 / 摘要历史"**。上下文只允许整块丢弃尾部,任何编辑中间内容的行为都会摧毁前缀缓存,直接拒。
10
+ 4. **每个 entry 必须 fail-open**。自身异常时退回默认行为,并在 ledger 或 stderr 留一条,不许静默吞掉。
11
+ 5. **如实报告**。测试不过就写不过,评测不好看就写不好看。
12
+
13
+ ## 本地开发
14
+
15
+ ```bash
16
+ npm test # 187 用例,零 API 调用
17
+ npm run build # src/*.ts → dist/*.js(Node 原生类型擦除,无第三方依赖)
18
+ ```
19
+
20
+ **改完 `src/` 必须重新 build 并提交 `dist/`**:patch 直接引用 `dist/`,源码与产物不一致时 CI 会用 `git diff --exit-code -- dist` 拦下。
21
+
22
+ ## 目录约定
23
+
24
+ | 目录 | 放什么 | 不放什么 |
25
+ |---|---|---|
26
+ | `src/kernel/` | 纯函数、内存态、可独立单测的逻辑 | 任何宿主 import、任何 IO |
27
+ | `src/entry/` | Cordis 薄壳:事件 → 内核调用 → 事件回写 | 业务逻辑(应下沉到 kernel) |
28
+ | `patches/` | 开发与评测用的组合补丁 | 生产装配(那是根目录 `cordis.patch.yml`) |
29
+ | `docs/` | 架构、协议、限制 | 变更日志(那是 `CHANGELOG.md`) |
30
+ | `eval/` | 指标口径、任务集、runner | 跑出来的批次(`eval/runs/` 除判定批次外不入库) |
31
+
32
+ ## 写 patch 的四个坑
33
+
34
+ 改 patch 之前务必知道,这些都是宿主实测结论:
35
+
36
+ 1. **新增行必须写在 `insert:` 下**。裸的 `- id: X` 是覆盖行,目标不存在会被**静默跳过**。
37
+ 2. **`inject` 只能写在行内**。loader 只读 `entry.options.inject`,模块导出的 `inject` 不进 patch 行。
38
+ 3. **相对路径以 patch 文件自身目录为 baseUrl**。所以根目录的 `cordis.patch.yml` 写 `./dist/`,`patches/` 下的写 `../dist/`。
39
+ 4. **preset 的嵌套行在创建路径上没有消费点**。关键行(尤其是 loop 接管)绝不藏进 preset。
40
+
41
+ 验证方式:`dsh --profile <name> --patch <文件> --dump-config`,能看到 `- id:` 行与解析后的绝对 `file:///` 路径才算挂上。
42
+
43
+ ## 提交
44
+
45
+ - 提交信息用 `<type>: <中文摘要>`,`type` 取 `feat` / `fix` / `docs` / `refactor` / `chore` / `test` / `eval`。
46
+ - 一个提交只做一件事;结构调整与逻辑改动分开。
47
+ - 涉及行为变化时同步更新 `CHANGELOG.md` 与受影响文档。
48
+
49
+ ## 发布
50
+
51
+ **Windows 双击 `release.cmd`** 即可,依次完成:构建 → 测试 → 版本 → 提交 → 打标签 → 推 GitHub → 建 Release → 发 npm。
52
+
53
+ 命令行等价:
54
+
55
+ ```bash
56
+ npm run release # 版本已手动 bump 就沿用,否则 patch+1
57
+ npm run release -- --minor # 或 --major / --set 0.2.0-rc.1
58
+ npm run release:dry # 只演练:跑构建测试 + 打印将执行的步骤
59
+ ```
60
+
61
+ 脚本会拦下这几类事故(都是实际踩过的):
62
+
63
+ | 拦截 | 原因 |
64
+ |---|---|
65
+ | 不在 `main` 分支 | 从特性分支发版会让 tag 落在错误提交上 |
66
+ | npm 未登录 / scope 与账号不符 | `@xxx/` 只能发到自己的用户名或所属组织 |
67
+ | `dist/` 与刚构建的结果不一致 | dist 入库且被 patch 直接引用,旧 dist 会让安装版本静默落后 |
68
+ | 测试未通过 | 先修再发 |
69
+ | npm 上该版本已存在 | 版本号必须递增,重复发布会 403 |
70
+ | 标签已存在且不指向 HEAD | 链接会错位;确需覆盖加 `--force-tag` |
71
+
72
+ 版本规则:`package.json` 的 version 大于最近 tag 时视为**已手动 bump**,直接沿用;否则按 `--patch/--minor/--major` 递增。tag 名固定为 `v<version>`,预发布版本(带 `-rc.1`)自动发到 npm 的 `alpha` dist-tag,稳定版才占 `latest`。