harness-reflex 0.0.0-stage → 0.3.0

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 (164) hide show
  1. package/CHANGELOG.md +20 -0
  2. package/README.md +266 -2
  3. package/USER_GUIDE.md +639 -0
  4. package/dist/adapters/agy.d.ts +8 -0
  5. package/dist/adapters/agy.js +80 -0
  6. package/dist/adapters/agy.js.map +1 -0
  7. package/dist/adapters/claude.d.ts +13 -0
  8. package/dist/adapters/claude.js +46 -0
  9. package/dist/adapters/claude.js.map +1 -0
  10. package/dist/adapters/codex.d.ts +139 -0
  11. package/dist/adapters/codex.js +368 -0
  12. package/dist/adapters/codex.js.map +1 -0
  13. package/dist/backend/defaults.d.ts +31 -0
  14. package/dist/backend/defaults.js +32 -0
  15. package/dist/backend/defaults.js.map +1 -0
  16. package/dist/backend/factory.d.ts +11 -0
  17. package/dist/backend/factory.js +40 -0
  18. package/dist/backend/factory.js.map +1 -0
  19. package/dist/backend/jev.d.ts +524 -0
  20. package/dist/backend/jev.js +1486 -0
  21. package/dist/backend/jev.js.map +1 -0
  22. package/dist/backend/mock.d.ts +26 -0
  23. package/dist/backend/mock.js +320 -0
  24. package/dist/backend/mock.js.map +1 -0
  25. package/dist/backend/route-prompt.d.ts +37 -0
  26. package/dist/backend/route-prompt.js +42 -0
  27. package/dist/backend/route-prompt.js.map +1 -0
  28. package/dist/backend/simple-jev.d.ts +35 -0
  29. package/dist/backend/simple-jev.js +273 -0
  30. package/dist/backend/simple-jev.js.map +1 -0
  31. package/dist/backend/types.d.ts +270 -0
  32. package/dist/backend/types.js +5 -0
  33. package/dist/backend/types.js.map +1 -0
  34. package/dist/cli/index.d.ts +2 -0
  35. package/dist/cli/index.js +278 -0
  36. package/dist/cli/index.js.map +1 -0
  37. package/dist/core/calibrate.d.ts +56 -0
  38. package/dist/core/calibrate.js +144 -0
  39. package/dist/core/calibrate.js.map +1 -0
  40. package/dist/core/closing.d.ts +90 -0
  41. package/dist/core/closing.js +111 -0
  42. package/dist/core/closing.js.map +1 -0
  43. package/dist/core/evidence.d.ts +119 -0
  44. package/dist/core/evidence.js +209 -0
  45. package/dist/core/evidence.js.map +1 -0
  46. package/dist/core/gate.d.ts +25 -0
  47. package/dist/core/gate.js +114 -0
  48. package/dist/core/gate.js.map +1 -0
  49. package/dist/core/judge.d.ts +221 -0
  50. package/dist/core/judge.js +251 -0
  51. package/dist/core/judge.js.map +1 -0
  52. package/dist/core/ledger.d.ts +67 -0
  53. package/dist/core/ledger.js +173 -0
  54. package/dist/core/ledger.js.map +1 -0
  55. package/dist/core/orchestrate-closing.d.ts +237 -0
  56. package/dist/core/orchestrate-closing.js +250 -0
  57. package/dist/core/orchestrate-closing.js.map +1 -0
  58. package/dist/core/orchestrate-correction.d.ts +209 -0
  59. package/dist/core/orchestrate-correction.js +141 -0
  60. package/dist/core/orchestrate-correction.js.map +1 -0
  61. package/dist/core/orchestrate-host.d.ts +225 -0
  62. package/dist/core/orchestrate-host.js +80 -0
  63. package/dist/core/orchestrate-host.js.map +1 -0
  64. package/dist/core/orchestrate-stagnation.d.ts +259 -0
  65. package/dist/core/orchestrate-stagnation.js +270 -0
  66. package/dist/core/orchestrate-stagnation.js.map +1 -0
  67. package/dist/core/orchestrate.d.ts +357 -0
  68. package/dist/core/orchestrate.js +418 -0
  69. package/dist/core/orchestrate.js.map +1 -0
  70. package/dist/core/policy.d.ts +122 -0
  71. package/dist/core/policy.js +102 -0
  72. package/dist/core/policy.js.map +1 -0
  73. package/dist/core/prune-plan.d.ts +141 -0
  74. package/dist/core/prune-plan.js +390 -0
  75. package/dist/core/prune-plan.js.map +1 -0
  76. package/dist/core/prune.d.ts +30 -0
  77. package/dist/core/prune.js +73 -0
  78. package/dist/core/prune.js.map +1 -0
  79. package/dist/core/route.d.ts +35 -0
  80. package/dist/core/route.js +39 -0
  81. package/dist/core/route.js.map +1 -0
  82. package/dist/core/score.d.ts +40 -0
  83. package/dist/core/score.js +49 -0
  84. package/dist/core/score.js.map +1 -0
  85. package/dist/core/screen.d.ts +22 -0
  86. package/dist/core/screen.js +117 -0
  87. package/dist/core/screen.js.map +1 -0
  88. package/dist/core/stagnation.d.ts +23 -0
  89. package/dist/core/stagnation.js +93 -0
  90. package/dist/core/stagnation.js.map +1 -0
  91. package/dist/core/text.d.ts +36 -0
  92. package/dist/core/text.js +66 -0
  93. package/dist/core/text.js.map +1 -0
  94. package/dist/hook/cli.d.ts +9 -0
  95. package/dist/hook/cli.js +52 -0
  96. package/dist/hook/cli.js.map +1 -0
  97. package/dist/hook/contract.d.ts +125 -0
  98. package/dist/hook/contract.js +159 -0
  99. package/dist/hook/contract.js.map +1 -0
  100. package/dist/hook/decision.d.ts +97 -0
  101. package/dist/hook/decision.js +955 -0
  102. package/dist/hook/decision.js.map +1 -0
  103. package/dist/hook/memory-store.d.ts +81 -0
  104. package/dist/hook/memory-store.js +157 -0
  105. package/dist/hook/memory-store.js.map +1 -0
  106. package/dist/hook/payload.d.ts +55 -0
  107. package/dist/hook/payload.js +129 -0
  108. package/dist/hook/payload.js.map +1 -0
  109. package/dist/hook/run.d.ts +48 -0
  110. package/dist/hook/run.js +218 -0
  111. package/dist/hook/run.js.map +1 -0
  112. package/dist/hook/store-port.d.ts +72 -0
  113. package/dist/hook/store-port.js +2 -0
  114. package/dist/hook/store-port.js.map +1 -0
  115. package/dist/index.d.ts +18 -0
  116. package/dist/index.js +19 -0
  117. package/dist/index.js.map +1 -0
  118. package/dist/mcp/server.d.ts +12 -0
  119. package/dist/mcp/server.js +368 -0
  120. package/dist/mcp/server.js.map +1 -0
  121. package/dist/ports/audit.d.ts +18 -0
  122. package/dist/ports/audit.js +11 -0
  123. package/dist/ports/audit.js.map +1 -0
  124. package/dist/ports/clock.d.ts +14 -0
  125. package/dist/ports/clock.js +11 -0
  126. package/dist/ports/clock.js.map +1 -0
  127. package/dist/ports/decision.d.ts +75 -0
  128. package/dist/ports/decision.js +2 -0
  129. package/dist/ports/decision.js.map +1 -0
  130. package/dist/ports/index.d.ts +14 -0
  131. package/dist/ports/index.js +2 -0
  132. package/dist/ports/index.js.map +1 -0
  133. package/dist/ports/log.d.ts +22 -0
  134. package/dist/ports/log.js +12 -0
  135. package/dist/ports/log.js.map +1 -0
  136. package/dist/ports/state.d.ts +46 -0
  137. package/dist/ports/state.js +13 -0
  138. package/dist/ports/state.js.map +1 -0
  139. package/dist/state/clock.d.ts +40 -0
  140. package/dist/state/clock.js +43 -0
  141. package/dist/state/clock.js.map +1 -0
  142. package/dist/state/file-store.d.ts +340 -0
  143. package/dist/state/file-store.js +849 -0
  144. package/dist/state/file-store.js.map +1 -0
  145. package/dist/state/paths.d.ts +41 -0
  146. package/dist/state/paths.js +73 -0
  147. package/dist/state/paths.js.map +1 -0
  148. package/docs/USER_GUIDE.en.md +721 -0
  149. package/docs/claude-code.md +281 -0
  150. package/docs/design/v0.2.0-harness-plugins.md +381 -0
  151. package/docs/design/v0.3.0-orchestration-unification.md +580 -0
  152. package/docs/dsh-plugin.md +578 -0
  153. package/docs/reflex-ui-regression-2026-10-20.md +34 -0
  154. package/docs/release-checklist-v0.1.0.md +315 -0
  155. package/docs/release-handbook-porting-notes.md +106 -0
  156. package/docs/release-handbook.md +393 -0
  157. package/docs/release-notes-v0.1.0.md +63 -0
  158. package/docs/release-notes-v0.3.0.md +152 -0
  159. package/docs/research/claude-code-harness.md +607 -0
  160. package/docs/research/pi-harness.md +621 -0
  161. package/experiments/data/calibration_sample.json +14 -0
  162. package/experiments/index.ts +29 -0
  163. package/experiments/runner.ts +156 -0
  164. package/package.json +82 -4
@@ -0,0 +1,34 @@
1
+ # Reflex UI regression investigation — 2026-10-20
2
+
3
+ ## Observed sessions
4
+
5
+ - `session-3ffdeb23-4326-4ff7-a139-661831a983d4`: the persisted log contains one Reflex decision, in turn 1. Its requested route is virtual `reflex/reflex-1`; its executed route is `openai-codex/gpt-6.1-sol`, effort `medium`. No explicit `model/selection` record exists in that log. Later turns have no Reflex decision records. The live GUI shows that historical turn-1 card and a physical GPT Medium selector. The log alone does not establish what the user intended when initially creating the session.
6
+ - `session-a038ed13-fdb4-4d45-a227-09f1f1f9aaf6`: earlier turns contain physical routing decisions. Turn 4 has a virtual `request/header`, no effort audit record, and a `request/context` without `contextWindow`. The live GUI shows `实际: 实际: ...` and no context percentage. Missing historical decision evidence must not be fabricated.
7
+
8
+ ## Contract findings
9
+
10
+ 1. Cordis waterfalls execute outermost-first, and post-`next()` rewrites happen in reverse order. The host model-selection listener overwrites provider/model/effort after awaiting `next()`. A Reflex listener appended after an existing session's selection listener can therefore be overwritten after plugin reload. Registering Reflex as an outer/prepended listener makes the final routing rewrite independent of initial activation order. A read-only reproduction with the actual installed Cordis, agent model-selection listener, and agent scope reproduced the regression after remove/reappend and recovered with `prepend: true`; the historical session does not record the exact time its listener was reloaded.
11
+ 2. The host session controller restores pending durable model selection first, otherwise the last request header. An implicit default virtual selection is lost after routing writes a physical header unless the original adaptive intent is persisted through the host's model-selection path.
12
+ 3. Composer actual values must be session-local and corroborated by physical execution metadata, not inferred from the global settings panel's latest decision. User selection and executed request metadata are different facts.
13
+ 4. A virtual pool does not have an arbitrary one-million-token capacity. Before physical routing, a conservative known capacity may be advertised only when all candidate windows are known; unknown capacity remains unknown. Normal routed requests should use the selected physical model's metadata.
14
+
15
+ ## Display policy
16
+
17
+ - Fixed physical model + fixed effort: no new adaptive decision and no adaptive composer indicator.
18
+ - Fixed physical model + explicitly adaptive effort: adaptive effort remains supported.
19
+ - Virtual model: preserve the virtual selection independently of the physical execution header.
20
+ - Historical decisions remain attached to their original turns; changing today's selector must not erase genuine history.
21
+ - No physical execution evidence: no fabricated actual model, effort, or percentage.
22
+
23
+ ## Deployment boundary
24
+
25
+ Repository changes and rebuilt tarballs do not update an independently installed profile plugin. Host changes require loading the updated installed module; browser-only refresh cannot do that. A full DSH restart is the most reliable way to load changed host code, but must be performed by the owner or with explicit authorization. Old logs missing an audit record cannot acquire a truthful historical decision merely by restarting.
26
+
27
+ ## Verification status
28
+
29
+ - `npm run build:all`: passed, including host/client TypeScript builds and the browser bundle.
30
+ - `npm run test`: 58 passed, zero failures or skips.
31
+ - `npm run test:plugin`: 235 passed, zero failures or skips. Coverage includes actual host model-selection ordering across reload, durable implicit intent, physical fixed-effort transparency, physical adaptive-effort support, session-local composer projection and stale-evidence invalidation, and conservative virtual context metadata.
32
+ - Packaging and mutation-control checks are run separately; their execution logs and release report are the authoritative results.
33
+
34
+ Live GUI observations above are baseline observations of the installed package, not proof that a rebuilt package has been deployed. No running-host installation, reload, or restart was performed. On the old plugin, a toggle can recreate the ordering problem; with the patched prepended listener and a genuine module reload, existing agents use the live listener registry, so a full DSH restart is not inherently required. After updating the installed package, a full restart remains the reliable alternative when module reload behavior is uncertain. For an older session whose implicit virtual intent was already lost, explicitly reselect the virtual model/adaptive effort; do not infer it from the current physical Medium selection.
@@ -0,0 +1,315 @@
1
+ # Harness Reflex 0.1.0 发布检查清单
2
+
3
+ > 配套手册: [`release-handbook.md`](release-handbook.md)。
4
+ > 用法:在仓库根逐节执行;`V=0.1.0`。标注 **[自动可验]** 的项有命令和机器判据;**[人工 gate]** 的项必须由负责人确认,不能由执行代理代替。
5
+ > 状态:**代码面已收口**(版本/改名/文档/打包自检已执行,见 §1–§4 的已勾项);**发布动作未执行**(tag/npm/GitHub/商店仍勾选为负责人 gate)。
6
+ > 事实基准:`integration/v0.1.0` @ `9235039` + 本次 0.1.0 改动,2026-10-21。
7
+
8
+ ```bash
9
+ cd /path/to/harness-reflex # 仓库根
10
+ V=0.1.0
11
+ ```
12
+
13
+ ---
14
+
15
+ ## 1. 版本号与元数据
16
+
17
+ > 版本号与包名变更已由执行代理完成;**tag / 发布动作**仍属负责人 gate。
18
+
19
+ - [x] 根包与插件包版本同步:
20
+
21
+ ```bash
22
+ npm pkg set version="$V"
23
+ (cd packages/dsh-harness-reflex && npm pkg set version="$V")
24
+ node -p "require('./package.json').version + ' / ' + require('./packages/dsh-harness-reflex/package.json').version"
25
+ # 期望:0.1.0 / 0.1.0
26
+ ```
27
+
28
+ - [x] 版本常量与测试引用同步(执行记录):
29
+
30
+ - `packages/dsh-harness-reflex/src/panel-api.ts` → `REFLEX_PLUGIN_VERSION = '0.1.0'`
31
+ - `src/release-packaging.test.ts` 产物名改为按 manifest 版本动态生成(插件包为 `dsh-harness-reflex-<version>.tgz`)
32
+ - `packages/dsh-harness-reflex/package.json` → `name: dsh-harness-reflex`、`cordis.patch.yml` 的 `name` 同步(`id` 不变)
33
+ - `USER_GUIDE.md`、`docs/USER_GUIDE.en.md`、`packages/dsh-harness-reflex/README.md` 的当前版本声明
34
+ - `package-lock.json`:`npm install --package-lock-only --ignore-scripts`
35
+
36
+ - [x] 当前版本引用不再有 alpha.2 残留(只查会随版本变化的文件,发布文档本身可保留历史引用):
37
+
38
+ ```bash
39
+ grep -n "0\.1\.0-alpha\.2" \
40
+ package.json packages/dsh-harness-reflex/package.json \
41
+ packages/dsh-harness-reflex/src/panel-api.ts src/release-packaging.test.ts \
42
+ USER_GUIDE.md docs/USER_GUIDE.en.md packages/dsh-harness-reflex/README.md
43
+ # 期望:无输出
44
+ ```
45
+
46
+ 通过判据:上述文件无 alpha.2;`docs/dsh-plugin.md` 的历史章节、本发布文档中的历史引用不计入。
47
+
48
+ - [x] 包名/渠道现状复核(**已完成 2026-10-22**):
49
+
50
+ ```bash
51
+ npm view dsh-harness-reflex version # 已占名并发布 0.1.0(维护者 miuzel)
52
+ npm view harness-reflex version # 已发布 0.1.0
53
+ npm whoami # 期望打印用户名;E401 即未登录
54
+ ```
55
+
56
+ 通过判据:负责人已复核插件包名并明确 0.1.0 的发布渠道(tarball 直发 / registry)。
57
+
58
+ > **实测结果(2026-10-22)**:`dsh-harness-reflex@0.1.0` 与 `harness-reflex@0.1.0` 均已发布到 npm;旧名 `@miuzel/dsh-reflex@0.1.0` 与占位版 `0.0.0-stage` 保留并建议 deprecate。上游发布的插件 tarball 与本仓库 `release/dsh-harness-reflex-0.1.0.tgz` **逐文件内容一致**(file-list 与 per-file sha256 均为 0 差异);根包 0.1.0 早于最终改名发布,仅文档内的包名不同,负责人已确认不重发。
59
+
60
+ ---
61
+
62
+ ## 2. 构建与测试 [自动可验]
63
+
64
+ - [ ] 构建:
65
+
66
+ ```bash
67
+ npm run build:all
68
+ ```
69
+
70
+ 通过判据:exit 0;`packages/dsh-harness-reflex/client.js` 生成且 >100 000 字节。
71
+
72
+ - [ ] 根包测试:
73
+
74
+ ```bash
75
+ npm test
76
+ ```
77
+
78
+ 通过判据:`fail 0`。当前基线:113 pass / 0 fail。
79
+
80
+ - [ ] 插件测试:
81
+
82
+ ```bash
83
+ npm run test:plugin
84
+ ```
85
+
86
+ 通过判据:`fail 0`。当前基线:419 pass / 0 fail。
87
+
88
+ - [ ] 负向对照:
89
+
90
+ ```bash
91
+ npm run test:mutation
92
+ ```
93
+
94
+ 通过判据:出现 `negative control OK: 51/51 injected faults were caught`(当前基线 50 测试 + 1 编译器)。版本变更后数字可变,但不得出现未捕获故障。
95
+
96
+ > 发布前打包会先检查“构建比源码新”。任何测试/构建之后的源码改动都必须重新 `npm run build:all`。
97
+
98
+ ---
99
+
100
+ ## 3. 打包与产物核验 [自动可验 + 人工记录]
101
+
102
+ - [ ] 归档上一版 tarball(`release-pack.mjs` 会清空 `release/`):
103
+
104
+ ```bash
105
+ mkdir -p tmp/release-archive
106
+ cp -a release/harness-reflex-0.1.0-alpha.2.tgz release/dsh-reflex-0.1.0-alpha.2.tgz \
107
+ release/SHA256SUMS tmp/release-archive/ 2>/dev/null || true
108
+ # 0.1.0 的插件产物名是 dsh-harness-reflex-0.1.0.tgz
109
+ (cd tmp/release-archive && sha256sum -c SHA256SUMS 2>/dev/null || true)
110
+ ```
111
+
112
+ 通过判据:上一版 tarball 已存在于 `tmp/release-archive/`,作为回滚素材。
113
+
114
+ - [ ] 打包并跑 27 项自检:
115
+
116
+ ```bash
117
+ node scripts/release-pack.mjs
118
+ ```
119
+
120
+ 通过判据:末行 `release-pack: 27/27 checks passed`,且 exit 0。
121
+
122
+ - [ ] 机器报告复核:
123
+
124
+ ```bash
125
+ node -e "const r=require('./release/release-report.json');\
126
+ if(r.checks.length!==27) throw new Error('checks '+r.checks.length);\
127
+ if(r.failures.length) throw new Error(r.failures.join(';'));\
128
+ console.log('version',r.version,'artifacts',r.artifacts.map(a=>a.file+':'+a.entries).join(','))"
129
+ ```
130
+
131
+ 通过判据:`checks=27`、`failures=[]`、`version=0.1.0`。
132
+
133
+ - [ ] 指纹与成员数记录:
134
+
135
+ ```bash
136
+ sha256sum release/*.tgz
137
+ (cd release && sha256sum -c SHA256SUMS)
138
+ tar -tzf release/harness-reflex-$V.tgz | wc -l
139
+ tar -tzf release/dsh-harness-reflex-$V.tgz | wc -l
140
+ ```
141
+
142
+ 通过判据:`sha256sum -c` 两行 OK;把两个字节数、entry 数、sha256 抄进 release notes 与发布记录。**alpha.2 的旧指纹不得复用**。
143
+
144
+ ---
145
+
146
+ ## 4. 全新 profile 安装与启动 [自动可验]
147
+
148
+ ```bash
149
+ export DSH_HOME="$PWD/tmp/dsh-pub-check"
150
+ rm -rf "$DSH_HOME" && mkdir -p "$DSH_HOME"
151
+ ```
152
+
153
+ - [ ] 用 tarball 安装(同版本必须 `--force`):
154
+
155
+ ```bash
156
+ dsh plugin --profile web add --force "$PWD/release/dsh-harness-reflex-$V.tgz"
157
+ ```
158
+
159
+ 通过判据:pnpm 安装成功;`dsh plugin` 输出 `+ dsh-harness-reflex 0.1.0`(或等价的 file: 链接)。
160
+
161
+ - [ ] 组合树里出现插件:
162
+
163
+ ```bash
164
+ dsh --profile web --dump-config | grep -A2 -- '- id: dsh-reflex'
165
+ ```
166
+
167
+ 通过判据:输出 `id: dsh-reflex` 且 `config` 节点存在。
168
+
169
+ - [ ] 启动隔离实例并核验健康/面板:
170
+
171
+ ```bash
172
+ dsh web --no-open --port 3987 & WEB_PID=$!
173
+ sleep 6
174
+ curl -s http://127.0.0.1:3987/dsh-reflex/api/health; echo
175
+ curl -s http://127.0.0.1:3987/dsh-reflex/api/panel | node -e '
176
+ let s=""; process.stdin.on("data",d=>s+=d).on("end",()=>{
177
+ const j=JSON.parse(s);
178
+ if(j.plugin.version!=="0.1.0") throw new Error("version "+j.plugin.version);
179
+ if(!j.tools.active.includes("reflex_gate")) throw new Error("gate missing");
180
+ if(j.tools.active.includes("reflex_prune")) throw new Error("reflex_prune must not be a DSH tool");
181
+ if(!j.interventions || !j.systemOne) throw new Error("projection missing");
182
+ console.log("panel ok:", j.plugin.version, j.tools.active.join(","), j.interventions.mode);
183
+ })'
184
+ kill $WEB_PID
185
+ ```
186
+
187
+ 通过判据:
188
+
189
+ - health 返回 `{"ok":true,"name":"dsh-reflex","version":"0.1.0"}`;
190
+ - panel 解析通过,`tools.active` 默认含 `reflex_choice`、`reflex_score`、`reflex_screen`、`reflex_gate`,**不含** `reflex_prune`;
191
+ - `interventions.mode` 为 `observe`(默认);
192
+ - `systemOne.active` 为 `mock-heuristic-v1`(无环境变量时);`systemOne.health` 对 mock 缺省属正常。
193
+
194
+ - [ ] MCP 面仍是 8 工具:
195
+
196
+ ```bash
197
+ printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' \
198
+ | SYSTEM_ONE_BACKEND=mock node dist/cli/index.js mcp 2>/dev/null \
199
+ | tail -1 \
200
+ | node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>{
201
+ const t=JSON.parse(s).result.tools.map(x=>x.name).sort();
202
+ if(t.length!==8) throw new Error("expected 8 tools, got "+t.length);
203
+ console.log(t.join(","));
204
+ })'
205
+ ```
206
+
207
+ 通过判据:输出 8 个 `reflex_*` 工具:`reflex_choice`、`reflex_score`、`reflex_route`、`reflex_screen`、`reflex_gate`、`reflex_prune`、`reflex_detect_stagnation`、`reflex_status_ledger`。
208
+
209
+ ---
210
+
211
+ ## 5. 命令与真机自动干预 [人工 gate]
212
+
213
+ - [ ] `/reflex-ledger` 命令:
214
+
215
+ 在隔离 profile 的 web/TUI 会话里输入 `/reflex-ledger`。
216
+ 通过判据:Host 直接渲染账本汇总文本(总调用数、类型分布、时延、节省 token、门禁/停滞、最近 5 条);账本为空时显示“暂无记录”而不是一排 0;**不产生工具调用、不发起模型回合**。
217
+
218
+ - [ ] 14.5K 剪枝真机验证(active 模式):
219
+
220
+ 1. 在设置面板「Reflex → 自动干预」把 `mode` 设为 `active` 并保存(或按 profile patch 语法覆盖 `interventions.mode`);
221
+ 2. 在会话里让 Agent 执行一条产生约 14.5K 字符的命令,例如:
222
+
223
+ ```bash
224
+ node -e "console.log(Array.from({length:205},(_,i)=>'progress '+i+' '+'.'.repeat(60)).join('\n'))"
225
+ ```
226
+
227
+ 3. 检查会话:工具结果被改写且含 `plugin:dsh-reflex/pruned-original#<digest>` 定位符;面板「决策账本」出现 `prune` 记录,`applied=true`,`actualSavedTokens>0`。
228
+
229
+ 通过判据:出现定位符;可用 `readPrunedOriginal()` 按定位符读回逐字节原文;同一载荷重复出现时复用第一次的原件。若只看到 `observe` 的账本而无改写,说明 `mode` 未生效,**不得**判定通过。
230
+
231
+ - [ ] 四能力冒烟(active 模式,至少各一次):
232
+
233
+ | 能力 | 触发 | 通过判据 |
234
+ |---|---|---|
235
+ | stagnation | 连续重复同一调用 ≥ `repeatThreshold` | 第三次被拒绝并给出纠正,而非原样执行 |
236
+ | prune | 上述 14.5K 输出 | 结果被替换且可定位原文 |
237
+ | gate | 连续失败调用达阈值 | 结果被改写为纠正反馈 |
238
+ | closing | 回合收尾声明与证据冲突 | 收到一次异议/纠正,而非静默通过 |
239
+
240
+ - [ ] 平台记录:Linux/WSL2 已实测;原生 Windows / macOS **本版未验证**(勾选此项表示已在 release notes 如实标注)。
241
+
242
+ ---
243
+
244
+ ## 6. 发布动作 [人工 gate]
245
+
246
+ - [ ] 合并与 tag(负责人):
247
+
248
+ ```bash
249
+ git checkout main
250
+ git merge --no-ff integration/v0.1.0
251
+ git tag -a v0.1.0 -m "harness-reflex / dsh-harness-reflex v0.1.0"
252
+ git push origin main && git push origin v0.1.0
253
+ ```
254
+
255
+ - [ ] 发布树与 tag 内容一致:
256
+
257
+ ```bash
258
+ git worktree add --detach .worktrees/release-v0.1.0 v0.1.0
259
+ ln -sfn "$PWD/node_modules" .worktrees/release-v0.1.0/node_modules
260
+ [ "$(git rev-parse 'v0.1.0^{tree}')" = "$(git -C .worktrees/release-v0.1.0 rev-parse 'HEAD^{tree}')" ]
261
+ (cd .worktrees/release-v0.1.0 && npm run build:all && node scripts/release-pack.mjs)
262
+ ```
263
+
264
+ 通过判据:tree 相等;发布树内 27/27 通过;记录发布树产物的 sha256。
265
+
266
+ - [ ] GitHub Release(正文真源 `docs/release-notes-v0.1.0.md`):
267
+
268
+ ```bash
269
+ gh release create v0.1.0 -R miuzel/harness-reflex \
270
+ release/harness-reflex-0.1.0.tgz release/dsh-harness-reflex-0.1.0.tgz release/SHA256SUMS \
271
+ --title "v0.1.0" --notes-file docs/release-notes-v0.1.0.md
272
+ diff <(gh release view v0.1.0 -R miuzel/harness-reflex --json body --jq .body) \
273
+ docs/release-notes-v0.1.0.md
274
+ ```
275
+
276
+ 通过判据:release 创建成功;正文与真源逐字一致(仅末尾换行归一化)。
277
+
278
+ - [ ] registry(仅当 B4/B5 已关闭,**负责人 gate**):`npm login` → `npm whoami` 打印用户名 → 发布两个已验 tarball(非 scoped,**不加 `--access public`**):
279
+
280
+ ```bash
281
+ npm publish ./release/dsh-harness-reflex-0.1.0.tgz
282
+ npm publish ./release/harness-reflex-0.1.0.tgz
283
+ npm view dsh-harness-reflex version # 期望 0.1.0
284
+ npm view dsh-harness-reflex dist.integrity # 与 release/SHA256SUMS 对账
285
+ ```
286
+
287
+ 通过判据:两条 `npm view` 与本地记录一致;若返回 `E403 Package name too similar`,按手册 §1.1 换名,不要重试。未关闭 B5 则**明确记录“本版不发布到 registry”**,不得含糊。
288
+
289
+ - [ ] awesome-dsh-plugin PR:按手册 §9 提交 `data/plugins/miuzel__harness-reflex.yml` 与重生成的 README;通过判据:PR 模板清单全部勾选,CI(仓库年龄/commits)通过。
290
+
291
+ ---
292
+
293
+ ## 7. 回滚演练 [人工 gate]
294
+
295
+ - [ ] 用归档的上一版 tarball 回退:
296
+
297
+ ```bash
298
+ dsh plugin --profile web add --force "$PWD/tmp/release-archive/dsh-reflex-0.1.0-alpha.2.tgz"
299
+ dsh web --no-open --port 3988 & RPID=$!
300
+ sleep 6
301
+ curl -s http://127.0.0.1:3988/dsh-reflex/api/health; echo
302
+ kill $RPID
303
+ ```
304
+
305
+ 通过判据:health 返回 `0.1.0-alpha.2`,面板可打开;随后可再 `--force` 装回 0.1.0。
306
+
307
+ - [ ] 回滚成本留档:账本 JSONL 只追加、无 schema 迁移;tag 已推送则不移动,修复走 `0.1.1`;registry 已发布则用 `npm deprecate` + 补丁版本,不依赖 unpublish。
308
+
309
+ ---
310
+
311
+ ## 8. 收尾
312
+
313
+ - [ ] 清理隔离环境:`rm -rf "$DSH_HOME" .worktrees/release-v0.1.0`
314
+ - [ ] 把本次实测的 tarball 字节数、entry 数、sha256、测试计数写进 `docs/release-notes-v0.1.0.md` 的「验证与产物」。
315
+ - [ ] 发布记录归档:`release/release-report.json`、`release/SHA256SUMS`、`release/RELEASE-0.1.0.md` 随 release 附件或 CI 产物保存。
@@ -0,0 +1,106 @@
1
+ # 发布手册移植差异表(dsh-graph → harness-reflex)
2
+
3
+ > 对应产物:[`release-handbook.md`](release-handbook.md)、[`release-checklist-v0.1.0.md`](release-checklist-v0.1.0.md)、[`release-notes-v0.1.0.md`](release-notes-v0.1.0.md)。
4
+ > 目的:说明哪些沿用 `dsh-graph/docs/release-handbook.md` 的体例,哪些按本仓库事实改写,哪些明确不适用。
5
+ > 核对基准:`integration/v0.1.0` @ `9235039` + 本次 0.1.0 改动,2026-10-21。
6
+
7
+ ## 1. 沿用(结构 / 思想,不照抄结论)
8
+
9
+ | dsh-graph 的做法 | 在本仓库的沿用 |
10
+ |---|---|
11
+ | 手册按“总体路径 → 阻塞清单 → 元数据 → 打包 → 发布树/tag → 渠道 → notes → 本地验收 → 兼容性 → 商店 → 回滚 → checklist”组织 | 采用同一骨架(0–11 节),保证评审者可逐节对照 |
12
+ | 阻塞清单逐条写“状态 + 证据/待办”,已完成与待办分开 | 保留;但每一条按本仓库重新取证,未照搬 B1–B8 结论 |
13
+ | 发布必须从 **tag 的独立 worktree** 构建,避免“发布物 ≠ tag 内容” | 保留;命令改为本仓库的 `npm run build:all` + `release-pack.mjs` |
14
+ | release notes 以 `docs/release-notes-v<版本>.md` 为唯一真源,线上正文由文件发布 | 保留;新增 `docs/release-notes-v0.1.0.md` |
15
+ | 发布后核对线上正文与真源逐字一致(仅末尾换行归一化) | 保留;命令改用本仓库占位仓库名 |
16
+ | 宿主兼容性必须多维判定,不能只看“装上了、起得来” | 保留三维度框架;维度内容改为本插件的“工具面 / MCP 面 / 真机自动干预” |
17
+ | awesome-dsh-plugin 的 YAML 字段、README 再生成、PR 自查清单 | 保留;条目名与描述改为 `harness-reflex` |
18
+ | 回滚保留上一版 tarball、tag 不移动、修复走补丁版本 | 保留;补充了 `release-pack.mjs` 会清空 `release/`,必须先归档旧 tarball 这一本仓库细节 |
19
+
20
+ ## 2. 按本仓库改写(事实不同)
21
+
22
+ | 主题 | dsh-graph | 本仓库(已核对) |
23
+ |---|---|---|
24
+ | 包结构 | 单包(`dsh-graph`,host/client 合并) | **双包**:根 `harness-reflex`(core + stdio MCP + CLI)+ `packages/dsh-harness-reflex`(DSH 插件 + 客户端面板) |
25
+ | 打包入口 | `bash scripts/build.sh` + `dist/` + `pnpm pack/publish` | **`node scripts/release-pack.mjs`**(`npm run release:pack`),产物直接落 `release/*.tgz` |
26
+ | 产物 | `dsh-graph-<v>.tgz` 单包 | `release/harness-reflex-<v>.tgz` + `release/dsh-harness-reflex-<v>.tgz`(npm pack 命名)+ `SHA256SUMS` + `release-report.json` + `RELEASE-<v>.md` |
27
+ | 自检 | 冻结验收脚本 / dist freshness 测试 | **27 项自检**(构建新鲜度 2、产物/版本 4、结构审计 10、内容断言 4、安装冒烟 7) |
28
+ | 测试 | `scripts/run-tests.mjs` 等 | `npm test`(当前 113)、`npm run test:plugin`(当前 419)、`npm run test:mutation`(51/51) |
29
+ | 安装 | `dsh plugin --profile web add dsh-graph` | `dsh plugin --profile <p> add --force <tarball>`;同版本必须 `--force`(插件包名 `dsh-harness-reflex`) |
30
+ | 健康检查 | `/api/dsh-graph` | `/dsh-reflex/api/health`(插件身份)+ `/dsh-reflex/api/panel`(快照:`systemOne` / `interventions` / `tools` 等) |
31
+ | 账本 | 看板/工具 | DSH 侧 `/reflex-ledger` 命令;MCP 侧 `reflex_status_ledger` 工具 |
32
+ | 工具面 | 单套 14 工具 | **两套**:MCP 8 工具;DSH 5 个可开关(默认 4,`route` 关),无 `reflex_prune` |
33
+ | 插件核心依赖 | 包内 `core/` 副本经 sync 脚本同步 | 插件 `dist/vendor/harness-reflex/**` 内联核心;tarball 安装**不依赖根包**(仅 zod/schemastery + Host peers) |
34
+ | 版本同步 | 单包 version + 常量 + 文档 | 已完成:根包/插件 `package.json`、`REFLEX_PLUGIN_VERSION`、两份指南、插件 README、`src/release-packaging.test.ts`、`package-lock.json`、重建 `client.js` |
35
+ | registry 现状 | 官方 registry 已发布过,仅登录态问题 | 根包名 `harness-reflex` 可用(404);**插件名 `dsh-reflex` 已被他人占用(0.3.0)** → 本版改用 `dsh-harness-reflex`;登录态待负责人处理;包名 `dsh-harness-reflex` 已确认可用 |
36
+ | 推荐渠道 | 单包 registry 发布 | 0.1.0 两包都可发布到 npm;也可先走 **tarball / GitHub Release 直发**,registry 待负责人登录 |
37
+ | 发布正文模板 | 平台门禁指向 `docs/platform-gate.md` | 本仓库无该文件;平台结论直接写进 notes(Linux/WSL2 实测、Windows/macOS 未验证) |
38
+ | 商店前置 | 已有公开 repo / topic | 仓库尚未创建、无 remote/tag、无 awesome 条目;gh 已登录 `miuzel` |
39
+
40
+ ## 3. 不适用(明确不要照抄)
41
+
42
+ | dsh-graph 内容 | 不适用原因 |
43
+ |---|---|
44
+ | `bash scripts/build.sh`、`docs/dist`、`dist/` 内 `pnpm publish` | 本仓库没有这些入口;发布物由 `release-pack.mjs` 直接打包,`dist/` 只是构建中间层 |
45
+ | `pnpm publish` / `npm publish dist` 流程 | 本仓库用 `release-pack.mjs` 打包后直发 tarball;registry 发布需负责人登录,不能照抄 `dist/` 内发布 |
46
+ | `dsh-graph-host/` 目录、`sync-core.sh`、跨包 `boardPayload` 问题(B7) | 本仓库结构不同:插件 side 自带 vendor,根包与插件各自打包 |
47
+ | B8“发布包带 .ts 不可加载” | 本仓库发布 `dist/*.js` + `.d.ts`,release-pack 已断言无测试构建与死链;该阻塞不存在 |
48
+ | `GIT_SSH_COMMAND="ssh -F /dev/null"` 等本机 ssh 配置绕过 | 属 dsh-graph 作者环境特例,本仓库无此记录;不要写入通用流程 |
49
+ | `docs/platform-gate.md`、`docs/fixture-versioning-checklist.md` 等 dsh-graph 专属文档 | 本仓库没有这些文件;平台结论写 release notes,fixture/版本策略写本手册 |
50
+ | `dsh-graph` 包名、topic、商店条目 `miuzel__dsh-graph.yml` | 本仓库应为 `miuzel__harness-reflex.yml`,且当前尚未提交 |
51
+ | dsh-graph 的 B1–B8 阻塞项结论 | 本仓库对应项要么已具备(27 项自检、真机安装),要么是不同阻塞(包名冲突、无 remote),不得照搬 |
52
+
53
+ ## 4. 章节映射
54
+
55
+ | dsh-graph 手册 | 本仓库手册 |
56
+ |---|---|
57
+ | §0 总体路径 | §0 总体路径 |
58
+ | §1 前置阻塞清单 | §1 前置阻塞清单 |
59
+ | §2 发布缺口补齐 | §2 版本号与包元数据 |
60
+ | §3 建 repo + topic | §4 发布树与 tag(拆出) |
61
+ | §4 发布(含 notes) | §5 渠道 + §6 notes 真源 |
62
+ | §5 本地验收 + §5.1 兼容性 | §7 全新 profile 验收 + §8 三维度判定 |
63
+ | §6 打包结构 | §3 打包与产物核验 |
64
+ | §7 商店上架 | §9 商店与 awesome |
65
+ | §8 总 checklist | §10 回滚 + §11 总 checklist |
66
+ | — | 新增 §10 回滚(本仓库需要明确 tarball 回滚路径) |
67
+
68
+ ## 5. 0.1.0 版本号同步涉及的文件(本次已执行)
69
+
70
+ | 文件 | 需要处理的引用 |
71
+ |---|---|
72
+ | `package.json` | ✅ `"version": "0.1.0"` |
73
+ | `packages/dsh-harness-reflex/package.json` | ✅ `name: dsh-harness-reflex`、`version: 0.1.0` |
74
+ | `packages/dsh-harness-reflex/src/panel-api.ts` | ✅ `REFLEX_PLUGIN_VERSION = '0.1.0'` |
75
+ | `USER_GUIDE.md` | ✅ 标题、§13、安装命令、包名与工具面 |
76
+ | `docs/USER_GUIDE.en.md` | ✅ 同中文版;已 `npm run build:all` 重新内嵌 |
77
+ | `packages/dsh-harness-reflex/README.md` | ✅ 包名、vendor 说明、安装命令 |
78
+ | `src/release-packaging.test.ts` | ✅ 产物名按 manifest 版本动态生成 |
79
+ | `package-lock.json` | ✅ `npm install` 重新生成,根版本 `0.1.0` |
80
+ | `packages/dsh-harness-reflex/client.js` | ✅ `npm run build:all` 重建(bundle id = `dsh-harness-reflex`) |
81
+ | `docs/dsh-plugin.md` | ✅ 顶部现行口径 + 历史章节标注 + 版本/产物/路由更新 |
82
+
83
+ > 不存在的文件:本仓库没有 `pnpm-lock.yaml`(根用 `package-lock.json`,插件无独立 lock);没有 `CHANGELOG.md`;没有 `LICENSE` 文件(`package.json` 声明 MIT,发布前是否补 LICENSE 由负责人决定)。
84
+
85
+ ## 6. 本次实测指纹与复现性
86
+
87
+ 2026-10-21 在 0.1.0 工作树构建并打包:
88
+
89
+ | 文件 | entries | 体积 |
90
+ |---|---:|---:|
91
+ | `harness-reflex-0.1.0.tgz` | 73 | 219 KiB |
92
+ | `dsh-harness-reflex-0.1.0.tgz` | 102 | 578 KiB |
93
+
94
+ 根包 entry 数从 69 变为 73,是因为本次新增的 4 份 `docs/release-*.md` 会按 `files: ["docs/**/*.md"]` 进入根包;插件包不含这些文档,条目数不变。具体 sha256 见 `release/SHA256SUMS`。**不在文档里固化根包 hash**:文档本身在根包内,任何后续编辑都会改变它;0.1.0 以发布树实测为准。
95
+
96
+ 连续两次 `release-pack` 的 sha256 完全一致(同一构建树内本地可复现),但 tarball 跨构建树并非字节可复现
97
+ (`client.js`、文件 mtime/入口顺序都可能影响);本手册与清单统一以**发布树实测**为准,不复用任何旧指纹。
98
+
99
+ ## 7. 移植时发现的仓库不一致(本次已处理)
100
+
101
+ 1. ✅ 根 `README.md` 已改为「MCP 面 8 工具 / DSH 面 5 个可开关(默认 4,`route` 关)」,并说明剪枝/停滞为自动干预。
102
+ 2. ✅ 插件 `README.md` 已改为「运行时零 `harness-reflex` 依赖,核心 vendored 进 `dist/vendor`」。
103
+ 3. ✅ `docs/dsh-plugin.md` 顶部新增现行口径,历史章节保留并标注以现行口径为准。
104
+ 4. ✅ `package-lock.json` 已由 `npm install` 重新生成,根版本 `0.1.0`。
105
+ 5. 仍待负责人决定:`packages/dsh-harness-reflex/client.js` 是否入库(当前分支未跟踪,发布树必须先构建)。
106
+ 6. ✅ `USER_GUIDE.md` §2 架构表已改为「5 个可开关工具,默认 4 个」。