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
package/CHANGELOG.md ADDED
@@ -0,0 +1,20 @@
1
+ # 更新日志 / Changelog
2
+
3
+ ## 0.3.0
4
+
5
+ ### 宿主接入
6
+
7
+ - 新增 Codex CLI、pi、Kimi Code 和 OpenCode 接入;Claude Code 与 DSH 插件一并升至 `0.3.0`。各宿主适配自己的事件和返回格式,剪枝、停滞、失效纠偏与收尾判定共用核心规则。
8
+ - Codex 只能改写 MCP 工具输出,不能改写 shell 输出;回合内 MCP 工具与剪枝未在真实模型回合中验证。pi 的收尾最多请求一次续跑,不能阻断。Kimi 的剪枝只记账,收尾阻断需要 exit-2 shim。OpenCode 的 `session.idle` 不能阻断收尾。Kimi 与 OpenCode 的宿主接入仅做了离线契约测试。详见 [能力对照](README.md#宿主能力对照)。
9
+
10
+ ### DSH 插件
11
+
12
+ - System One 改用连接配置:可维护多条连接,每条连接可从模型列表中选定一个模型。全新配置预置并启用 `JEV official`,凭证只读取 `JEV_API_KEY`;不会覆盖已有连接或显式停用的设置。命名凭证变量后不会回退到其他变量,面板不回显密钥。
13
+ - 设置面板编辑后自动保存,只写本次改动。保存失败时保留草稿并显示原因;只读状态不会写入。重复选择当前模型不会丢掉正在输入的文本。
14
+ - 工具结果与账本记录逐次判定的连接、请求模型及结果来源;缺少证据时不推断来源。
15
+ - 推理强度按回合判定,参考当前提示、对话历史与上一次强度。`reflex_delegate` 是单独的可选工具,需要显式开启 Delegation,且宿主工具须开放模型选择。
16
+
17
+ ### 升级与分发
18
+
19
+ - 从 `0.1.0` 直接升至 `0.3.0`,没有发布过 `0.2.0`。旧账本可继续读取;旧 alpha 包 `dsh-reflex` 与 `dsh-harness-reflex` 是不同的安装,配置不会自动迁移。DSH 插件要求 `>=0.2.2-rc.1 <0.2.3`;同版本重装须加 `--force`。
20
+ - 发布构建生成七份 tarball。`harness-reflex`、`dsh-harness-reflex`、`pi-reflex` 可作为 npm 包发布;Claude Code、Codex、Kimi Code 和 OpenCode 的配置或插件包标记为 `private`,按各自 README 接入。仓库内的 `release/RELEASE-0.3.0.md` 提供安装与验证背景。
package/README.md CHANGED
@@ -1,3 +1,267 @@
1
- # Temporary Holding Version
1
+ # Harness Reflex (System One Decision Runtime for Codex / Claude Code / AGY)
2
+
3
+ 跨 Harness(**Codex CLI**、**Claude Code**、**Antigravity / AGY**)的 System One 快速决策与判定运行时插件。
4
+
5
+ 统一支持各类 **System One API**(包括官方 Jev、vLLM/OpenAI logits 读出、自托管模型与本地启发式决策后端),让 Harness 在不调用笨重 System Two 推理的情况下,毫秒级实现门禁验证、上下文剪枝与死循环拦截。
6
+
7
+ ---
8
+
9
+ ## 先分清两个「面」(写文档、剪视频、写脚本前必看)
10
+
11
+ 同一个插件在不同宿主里露出不同形状,**工具数量与自动化程度都不同**,混着讲会自相矛盾:
12
+
13
+ | | A. MCP 面(Claude Code / Codex / AGY) | B. DSH 宿主插件面(`dsh-harness-reflex`) |
14
+ |---|---|---|
15
+ | 工具 | **8 个**:`choice` `score` `route` `screen` `gate` `prune` `detect_stagnation` `status_ledger` | **5 个可开关**:`choice` `score` `route` `screen` `gate`;默认开 4 个,`route` 默认关 |
16
+ | 剪枝 / 停滞 / 收尾核验 | 需要模型**主动调用工具** | **自动干预**:`tools/post-execute`、`agent/pre-step`、`agent/turn-stopping` 钩子执行,模型不调也会发生 |
17
+ | 账本 | `reflex_status_ledger` 工具 | `/reflex-ledger` 命令 或 设置面板「账本」页(不占工具位) |
18
+ | 模型与思考等级 | 不涉及(由宿主决定) | 自动:虚拟 Provider 候选池 + 自适应 `reasoningEffort` |
19
+ | 设置面板 | 无 | **8 个页签**:概览 / 虚拟 Provider / 推理强度 / System 1 后端 / 自动干预 / 工具开关 / 账本 / 使用说明 |
20
+
21
+ 一句话:**A 面是工具集,B 面是「工具 + 自动干预 + 路由」**。讲到具体数字前,先说清在讲哪个面。
22
+
23
+ ---
24
+
25
+ ## 宿主能力对照
26
+
27
+ v0.3.0 产物覆盖下表六个宿主。**它们的能力并不对等**——宿主没有给出对应钩子时,
28
+ 这个能力就是做不到,而不是「配置一下就好」。下表按「能力在模型侧是否真的生效」写:
29
+
30
+ | 能力 | Claude Code | DSH(`dsh-harness-reflex`) | Codex CLI | pi | Kimi Code | OpenCode |
31
+ |---|---|---|---|---|---|---|
32
+ | 8 个 / 5 个 `reflex_*` 工具(MCP) | ✅ 8 个 MCP 工具 | ✅ 5 个可开关(默认 4) | ⚠️ 8 个 MCP 工具已声明,**本机未进回合内工具清单** | ✅ 工具集在本进程内 | ⚠️ 8 个 MCP 工具已声明,**未在真机验证** | ⚠️ 8 个 MCP 工具已声明,**未在真机验证** |
33
+ | 停滞拦截(拒绝重复调用) | ✅ 拒绝 | ✅ 自动 | ✅ 拒绝 | ✅ 拒绝 | ✅ 拒绝 | ✅ 抛错拒绝 |
34
+ | 结果剪枝(改写工具输出) | ✅ 生效 | ✅ 自动生效 | ⚠️ **只能改 MCP 工具输出,不能改 shell 工具输出** | ✅ 生效 | ❌ **`PostToolUse` 是 observation-only:只记账不生效** | ✅ 生效(`tool.execute.after` 替换输出) |
35
+ | 失效纠偏 | ✅ 生效 | ✅ 自动生效 | — | ✅ 生效 | ❌ 只记账(`PostToolUseFailure` observation-only) | ❌ 宿主无工具失败钩子 |
36
+ | 收尾核验(阻断「我完成了」) | ✅ **真阻断** | ✅ **真阻断** | ✅ 可 block | ⚠️ **只能续跑一次,从不阻断**:记为 `closing-degraded-pass`,永不记 `closing-block` | ⚠️ 需 `hooks/reflex-stop-exit2.sh` shim 转 exit 2 才能阻断 | ❌ **Stop 无法拦截**(`session.idle` 无插件级否决权,只记 warn 日志) |
37
+ | 接入形态 | 配置 hooks + MCP | 进程内 Cordis 插件 | 配置 `hooks.json` + `config.toml` | 进程内 TS 扩展 | 配置 `hooks.toml` + shim + `mcp.json` | **JS 插件**(宿主无 shell 钩子机制) |
38
+
39
+ 读法:
40
+
41
+ - **Claude Code / DSH 是完整能力**:六项能力全部在模型侧真实生效。
42
+ - **Codex 的剪枝只作用于 MCP 工具输出。** 宿主的 `PostToolUse` 只接受 `updatedMCPToolOutput` 一个决定字段,
43
+ 且只对 MCP 工具生效;**shell(`exec_command`)的结果改不了**。这不是接线缺陷,而是宿主的契约。
44
+ `reflex_prune` 仍可作为工具由模型自己调用。另:本机没有可用模型端点,**MCP 工具从未进入 Codex 回合内的
45
+ 工具清单**,故「回合内剪枝」与「回合内 MCP 工具」均未真机验证。
46
+ - **Kimi 的剪枝只记账不生效。** `PostToolUse` / `PostToolUseFailure` / `SubagentStop` 在 Kimi Code 里是
47
+ observation-only:宿主忽略返回值,判定仍写进账本,但改变不了模型看到的内容。只有 `PreToolUse`(拒绝)
48
+ 和 `Stop`(**经 `hooks/reflex-stop-exit2.sh` 把我们的 `decision:"block"` JSON 转成 exit 2**)能真正干预。
49
+ - **OpenCode 没有 shell 钩子机制**,唯一扩展点是 JS 插件(`Plugin = (input) => Promise<Hooks>`),所以它
50
+ 拿到的是插件而不是配置片段。剪枝与停滞**在 OpenCode 上是生效的**(这是少见的非 Claude 宿主优势);
51
+ 但 **Stop 无法拦截**——`session.idle` 事件不带助手文本,宿主也没有插件级否决权,异议只能写进日志。
52
+ - **pi 的收尾只会降级放行。** pi 没有任何 API 能拒绝结束一个回合;`agent_before_settle` 只能请求
53
+ **一次**续跑,它不能否决 settle。因此矛盾未被纠正时会放行并记 `closing-degraded-pass`——
54
+ **pi 永远不会写 `closing-block`**,扩展不会假装自己做到了。
55
+
56
+ > ⚠️ **未验证项不要当已验证**:Kimi / OpenCode 的整机安装与钩子触发、Codex 的回合内 MCP 工具,
57
+ > 本机都没有对应的可用宿主,均未真机验证;验证方法逐条写在各包 README 的
58
+ > 「Verification status」小节。Claude Code 与 pi 有真机 e2e。
59
+
60
+ ---
61
+
62
+ ## 核心特性与架构
63
+
64
+ ```
65
+ ┌────────────────────────────────────────────────────────┐
66
+ │ Harness Layer (Codex / Claude / AGY) │
67
+ └───────────┬────────────────────────────────┬───────────┘
68
+ │ Stdio MCP / Hooks │
69
+ ┌───────────▼────────────────────────────────▼───────────┐
70
+ │ Harness Reflex Core │
71
+ │ - Gate: 逐条声明-证据核对 (Fail-Closed, Latch) │
72
+ │ - Stagnation: 停滞与死循环检测 (振荡/反复失败打断) │
73
+ │ - Prune: 工具超长结果剪枝 (Fail-Open, Shadow 模式) │
74
+ │ - Route: 技能/工具概率排序 (只排序,不卡死阈值) │
75
+ │ - Ledger: 台账与净节省 Token/成本审计 │
76
+ └───────────┬────────────────────────────────┬───────────┘
77
+ │ DecisionBackend Interface │
78
+ ┌───────────────────┼────────────────────────────────┼───────────────────┐
79
+ ▼ ▼ ▼ ▼
80
+ [官方 Jev API] [simple-jev / vLLM] [本地 Mock / 启发式] [自托管模型]
81
+ (POST /v1/systemone (max_tokens: 1, (用于测试、开发与 (Qwen / DeepSeek)
82
+ single endpoint) next-token logprobs) 离线基准跑分)
83
+ ```
84
+
85
+ 1. **跨 Harness 零门槛适配**:
86
+ - **Claude Code**:标准 MCP 协议(`.mcp.json`),提供 `reflex_gate`、`reflex_prune`、`reflex_detect_stagnation` 等工具。
87
+ - **Codex CLI**:`.codex/config.json` 原生 MCP 挂载。
88
+ - **Antigravity (AGY)**:Bundle 插件(`.agents/plugins/harness-reflex/`),内嵌 `plugin.json`、`mcp_config.json`、`hooks.json` 与 `rules/AGENTS.md`;hooks 调用与 Claude Code 相同的 `harness-reflex hook <event>` 分发器,自动干预能力取决于 AGY 是否消费 hook 输出(以宿主实测为准)。
89
+
90
+ 2. **全套 System One 工具链(MCP 面 8 个工具,由根包 stdio server 暴露给外部客户端)**:
91
+ - **底层通用 API**:
92
+ - `reflex_choice`:多选一概率分布预测,毫秒级得出答案,零生成开销。
93
+ - `reflex_score`:对代码/陈述进行 0.0 ~ 1.0 的连续标准评分。
94
+ - `reflex_screen`:对不可信外部输入(工具输出、网页、PR 注释)做提示注入与指令劫持筛查。
95
+ - **高阶工作流工具**:
96
+ - `reflex_gate`:声明-证据核对门禁(反向 Fail-Closed,且支持加载离线校准曲线)。
97
+ - `reflex_prune`:长输出提炼与剪枝(容错 Fail-Open,支持 Shadow 模式)。
98
+ - `reflex_detect_stagnation`:停滞与死循环检测(识别重复重试、振荡与零进展)。
99
+ - `reflex_route`:技能与工具的意图排序(只排序,不卡死阈值)。
100
+ - `reflex_status_ledger`:决策台账与净节省 Token/成本统计。
101
+
102
+ > 这 8 个工具**只属于 MCP 面**。DSH 宿主插件面只有 5 个可开关工具,见下面第 4 条。
103
+
104
+ 3. **离线拟合校准闭环(Isotonic PAVA & Platt 回归)**:
105
+ - 内置 `calibrate` 引擎,可基于历史标注集拟合单调映射曲线,计算 ECE 误差并输出校准配置;
106
+ - 线上运行时自动修正过度自信的模型原始概率,杜绝盲目放行。
107
+
108
+ 4. **DSH Host 插件(进程内集成,`dsh-harness-reflex`)**:
109
+ - 除 stdio MCP 之外,同一套 System One 能力还以 **DSH Cordis Host 插件**形式在 `dsh` 进程内注册:
110
+ `packages/dsh-harness-reflex/` 通过 `ctx.tools` 注册 **5 个可开关工具** `reflex_choice` / `reflex_score` /
111
+ `reflex_route` / `reflex_screen` / `reflex_gate`,**默认开启前 4 个、`route` 默认关闭**。
112
+ - **剪枝、停滞拦截、收尾核验与失效纠偏是自动干预**,不是工具:它们由宿主的
113
+ `tools/post-execute`、`agent/pre-step`、`agent/turn-stopping` 钩子按 `interventions.mode`
114
+ (`off` / `observe` / `active`,默认 `observe`)执行;DSH 面**没有** `reflex_prune` /
115
+ `reflex_detect_stagnation` / `reflex_status_ledger` 三个工具。
116
+ - 账本用 **`/reflex-ledger` 命令**(或设置面板「账本」页)读取,不经模型、不占工具位。
117
+ - 严格参数校验沿用 Host 的 `defineTool`(必填/类型/枚举/嵌套 `additionalProperties`),工具层再拦截
118
+ 顶层未声明参数;卸载时通过单个 `ctx.effect` 摘除观察者、逆序注销工具、释放运行时,完全可逆。
119
+ - 同时提供**虚拟 Provider 与动态模型路由**:注册虚拟 provider(默认 `reflex`),把 `reflex-auto` /
120
+ `reflex-fast` 这类虚拟模型按配置的物理候选池用 System 1 在 `agent/request` 上毫秒级改写成真实
121
+ `provider/model`(主代理与 subagent 都覆盖,每条决策写 `type: 'model-route'` 台账);
122
+ 未配置候选池时**不注册**该 provider,池为空且无 `routing.fallback` 时 **Fail-Closed**。
123
+ - 路由**上下文感知且带会话粘性**:决策请求带上本会话累积的上下文规模与当前物理模型,提示词写明
124
+ 「保留当前模型可省缓存、非必要不切」,名次相近(未超出 `stickyMargin`,默认 15%)时守住已在用的
125
+ 模型,只有明显更合适才切换;`model-route` 台账记 `currentModel` / `switched` / `contextTokens`。
126
+ - 详见 [`docs/dsh-plugin.md`](docs/dsh-plugin.md) 与 [`packages/dsh-harness-reflex/README.md`](packages/dsh-harness-reflex/README.md)。
127
+
128
+ 5. **Claude Code 插件三件套(v0.3.0)**:
129
+ - `packages/claude-reflex/` 同时携带 **mod**(`turn.step` effort 接线)、**settings hooks**
130
+ (PreToolUse / PostToolUse / PostToolUseFailure / Stop / SubagentStop(默认关)/ SessionStart / SessionEnd,
131
+ 逐事件调用 `harness-reflex hook <event>`)与 **MCP server**(根包 8 个 `reflex_*` 工具)。
132
+ - 剪枝、停滞、失效纠偏 **active**;收尾核验默认 **observe**,可在插件配置里 opt-in 成 `active`。
133
+ - 安装、配置、限制与「本环境已验证 / 需你本机验证」两栏见
134
+ [`docs/claude-code.md`](docs/claude-code.md);真实 `claude -p` e2e 见 `scripts/claude-e2e.sh`。
135
+
136
+ ---
137
+
138
+ ## 快速安装与配置
139
+
140
+ 在 `0.3.0` 上架 npm 后,可运行 `npm install -g harness-reflex@0.3.0` 安装核心 CLI 与 stdio MCP。
141
+ 上架前可从发布产物安装:`npm install -g ./release/harness-reflex-0.3.0.tgz`。
142
+ 以下构建和配置示例从源码仓库根目录运行。
143
+
144
+ ### 1. 构建
145
+ ```bash
146
+ npm install
147
+ npm run build
148
+ ```
149
+
150
+ ### 2. 构建(含 DSH Host 插件)
151
+ ```bash
152
+ # 根包 tsc → 链接本机 DSH 依赖(离线可用的软链,无需 registry)→ 插件 tsc
153
+ npm run build:all
154
+ ```
155
+
156
+ ### 3. 一键配置 Harness
157
+ ```bash
158
+ # 自动为 Claude Code, Codex, Antigravity 全部生成配置文件与规则
159
+ node dist/cli/index.js setup all
160
+
161
+ # 或单独配置某一个
162
+ node dist/cli/index.js setup claude
163
+ node dist/cli/index.js setup codex
164
+ node dist/cli/index.js setup agy
165
+ ```
166
+
167
+ ### 4. 安装 DSH 插件(可选,进程内集成)
168
+
169
+ ```bash
170
+ # 从本仓库产物安装;同版本重装必须加 --force(pnpm 不会静默覆盖同版本)
171
+ dsh plugin --profile web add --force ./release/dsh-harness-reflex-0.3.0.tgz
172
+
173
+ # 首次发布到 npm 后(包名 dsh-harness-reflex):
174
+ dsh plugin --profile web add dsh-harness-reflex@0.3.0
175
+ ```
176
+
177
+ 安装后重启 / 重载 `dsh`,设置页会出现「Reflex 决策运行时」面板;`/dsh-reflex/api/health`
178
+ 应返回 `{"ok":true,"name":"dsh-reflex","version":"0.3.0"}`。
179
+
180
+ ### 5. 配置核心 CLI / MCP 的 System One 决策后端(可选)
181
+ DSH 插件使用设置面板中的连接配置;全新配置预置并启用 `JEV official`,凭证读取 `JEV_API_KEY`。
182
+ 默认内置本地快速启发式决策器(`<5ms` 延迟,零外部依赖)。可随时无缝切换到其他 System One API:
183
+
184
+ ```bash
185
+ # 切换 Provider A:官方 Jev API(只有 key 是必填,地址与模型都有默认值)
186
+ export SYSTEM_ONE_API_KEY="your-api-key"
187
+
188
+ # 切换 Provider B:通用 open-weights 模型 logits 读出 (vLLM / simple-jev / OpenAI 兼容接口)
189
+ export SYSTEM_ONE_BASE_URL="http://localhost:8000" # 只有地址是必填
190
+ export SYSTEM_ONE_BACKEND=simple-jev # 或不写:检测到 VLLM_BASE_URL/OPENAI_BASE_URL 会自动选中
191
+
192
+ # 切换 Provider C:离线/本地基准模拟后端(什么都不设时的默认)
193
+ export SYSTEM_ONE_BACKEND=mock
194
+ ```
195
+
196
+ 不设 `SYSTEM_ONE_BACKEND` 时按顺序自动判定:有 `SYSTEM_ONE_API_KEY`/`JEV_API_KEY` → `jev`;
197
+ 有 `VLLM_BASE_URL`/`OPENAI_BASE_URL` → `simple-jev`;都没有 → `mock`。
198
+
199
+ | 变量 | 默认值 |
200
+ | --- | --- |
201
+ | `SYSTEM_ONE_BASE_URL` | `jev`:`https://api.typesafe.ai/v1/systemone`;`simple-jev`:`http://localhost:8000` |
202
+ | `SYSTEM_ONE_MODEL` | `jev`:`jev-latest`;`simple-jev`:`Qwen/Qwen2.5-7B-Instruct` |
203
+ | `SYSTEM_ONE_API_KEY` | `jev`:无(空串,请求会被服务端拒绝);`simple-jev`:`dummy`(本地服务通常不校验) |
204
+
205
+ ---
206
+
207
+ ## 实验基准对比运行
208
+
209
+ 我们内置了有无插件在真实典型场景下的对比基准:
210
+
211
+ ```bash
212
+ node --experimental-strip-types experiments/index.ts
213
+ ```
214
+
215
+ 查看决策台账:
216
+ ```bash
217
+ node dist/cli/index.js ledger
218
+ ```
219
+
220
+ ---
221
+
222
+ ## 测试
223
+
224
+ ```bash
225
+ npm test # 根包:ledger / score / route / route-prompt / MCP 表面 / 打包清单
226
+ npm run test:plugin # DSH 插件:注册、严格校验、工具面与 /reflex-ledger、生命周期、虚拟 provider 路由(含上下文感知与会话粘性)、设置面板与使用说明
227
+ npm run test:claude-plugin # Claude Code 插件:manifest/hooks/.mcp.json、7 事件、observe diff=0、崩溃放行
228
+ npm run test:all # 构建后运行七套测试:核心、DSH、Claude Code、Codex、pi、Kimi Code、OpenCode
229
+ npm run test:mutation # 负向对照:注入故障,要求被测试(或编译器)抓住
230
+ ```
231
+
232
+ ---
233
+
234
+ ## 使用说明与发布产物
235
+
236
+ - 版本变更见 [`CHANGELOG.md`](CHANGELOG.md)。
237
+
238
+ - **[`USER_GUIDE.md`](USER_GUIDE.md)**(中文)与 **[`docs/USER_GUIDE.en.md`](docs/USER_GUIDE.en.md)**(English):
239
+ 插件架构、虚拟 Provider 模型池配置、自适应思考等级(`reflex` / `auto`)、System 1 后端接入、
240
+ MCP 与原生 DSH 工具对照、决策账本、测试与发布流程。这两份文档会被嵌入插件前端,
241
+ 可在 DSH 设置页 **Reflex → 使用说明 / Guide** 标签页内直接切换中英文阅读。
242
+
243
+ ```bash
244
+ npm run release:pack -- --keep # 构建后打包七份 tarball;保留已跟踪的发布草稿和打包暂存目录
245
+ npm run release -- --keep # 全量构建、七套测试及变异测试通过后再以相同方式打包
246
+ ```
247
+
248
+ 产物路径:
249
+
250
+ | 产物 | 说明 |
251
+ | --- | --- |
252
+ | `release/harness-reflex-<version>.tgz` | 根包:核心运行时、CLI、stdio MCP、适配器、`dist/`(含类型与自包含 source map)、`USER_GUIDE.md`、`docs/` |
253
+ | `release/dsh-harness-reflex-<version>.tgz` | DSH Host 插件 `dsh-harness-reflex`(npm pack 命名):`dist/`、单文件浏览器端 `client.js`(含内嵌使用说明)、`cordis.patch.yml`、`locale/` |
254
+ | `release/harness-reflex-claude-code-<version>.tgz` | Claude Code 插件(`private`) |
255
+ | `release/harness-reflex-codex-<version>.tgz` | Codex 配置包(`private`) |
256
+ | `release/pi-reflex-<version>.tgz` | pi 扩展 |
257
+ | `release/harness-reflex-kimi-code-<version>.tgz` | Kimi Code 配置包与 shim(`private`) |
258
+ | `release/harness-reflex-opencode-<version>.tgz` | OpenCode JS 插件与配置(`private`) |
259
+ | `release/SHA256SUMS` | 七份 tarball 的 SHA-256 校验和;在 `release/` 内运行 `sha256sum -c SHA256SUMS` |
260
+ | `release/release-report.json` | 逐项打包核验记录(文件清单、死链、依赖声明、安装冒烟) |
261
+ | `release/RELEASE-<version>.artifacts.md` | 自动生成的产物与核验说明 |
262
+
263
+ `npm run release:pack` 不止于「打包成功」:它解压七份 tarball,核对必需文件、
264
+ 拒绝测试构建产物、临时目录与本地绝对路径,解析全部相对引用与 source map 目标(零死链,
265
+ 且不允许未声明的运行时依赖),再对根包做一次真实 `npm install`(`bin`、具名 import 与
266
+ stdio MCP `tools/list` 冒烟)。
2
267
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.