harness-reflex 0.1.0 → 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 (121) hide show
  1. package/CHANGELOG.md +20 -0
  2. package/README.md +103 -23
  3. package/USER_GUIDE.md +121 -43
  4. package/dist/adapters/agy.js +1 -1
  5. package/dist/adapters/agy.js.map +1 -1
  6. package/dist/adapters/codex.d.ts +133 -4
  7. package/dist/adapters/codex.js +325 -2
  8. package/dist/adapters/codex.js.map +1 -1
  9. package/dist/backend/defaults.d.ts +31 -0
  10. package/dist/backend/defaults.js +32 -0
  11. package/dist/backend/defaults.js.map +1 -0
  12. package/dist/backend/jev.js +6 -5
  13. package/dist/backend/jev.js.map +1 -1
  14. package/dist/backend/mock.d.ts +12 -1
  15. package/dist/backend/mock.js +34 -0
  16. package/dist/backend/mock.js.map +1 -1
  17. package/dist/backend/simple-jev.js +5 -4
  18. package/dist/backend/simple-jev.js.map +1 -1
  19. package/dist/backend/types.d.ts +34 -0
  20. package/dist/backend/types.js.map +1 -1
  21. package/dist/cli/index.js +5 -3
  22. package/dist/cli/index.js.map +1 -1
  23. package/dist/core/closing.d.ts +90 -0
  24. package/dist/core/closing.js +111 -0
  25. package/dist/core/closing.js.map +1 -0
  26. package/dist/core/evidence.d.ts +119 -0
  27. package/dist/core/evidence.js +209 -0
  28. package/dist/core/evidence.js.map +1 -0
  29. package/dist/core/judge.d.ts +221 -0
  30. package/dist/core/judge.js +251 -0
  31. package/dist/core/judge.js.map +1 -0
  32. package/dist/core/orchestrate-closing.d.ts +237 -0
  33. package/dist/core/orchestrate-closing.js +250 -0
  34. package/dist/core/orchestrate-closing.js.map +1 -0
  35. package/dist/core/orchestrate-correction.d.ts +209 -0
  36. package/dist/core/orchestrate-correction.js +141 -0
  37. package/dist/core/orchestrate-correction.js.map +1 -0
  38. package/dist/core/orchestrate-host.d.ts +225 -0
  39. package/dist/core/orchestrate-host.js +80 -0
  40. package/dist/core/orchestrate-host.js.map +1 -0
  41. package/dist/core/orchestrate-stagnation.d.ts +259 -0
  42. package/dist/core/orchestrate-stagnation.js +270 -0
  43. package/dist/core/orchestrate-stagnation.js.map +1 -0
  44. package/dist/core/orchestrate.d.ts +357 -0
  45. package/dist/core/orchestrate.js +418 -0
  46. package/dist/core/orchestrate.js.map +1 -0
  47. package/dist/core/policy.d.ts +122 -0
  48. package/dist/core/policy.js +102 -0
  49. package/dist/core/policy.js.map +1 -0
  50. package/dist/core/prune-plan.d.ts +141 -0
  51. package/dist/core/prune-plan.js +390 -0
  52. package/dist/core/prune-plan.js.map +1 -0
  53. package/dist/core/score.d.ts +2 -2
  54. package/dist/core/score.js.map +1 -1
  55. package/dist/core/text.d.ts +36 -0
  56. package/dist/core/text.js +66 -0
  57. package/dist/core/text.js.map +1 -0
  58. package/dist/hook/cli.d.ts +9 -0
  59. package/dist/hook/cli.js +52 -0
  60. package/dist/hook/cli.js.map +1 -0
  61. package/dist/hook/contract.d.ts +125 -0
  62. package/dist/hook/contract.js +159 -0
  63. package/dist/hook/contract.js.map +1 -0
  64. package/dist/hook/decision.d.ts +97 -0
  65. package/dist/hook/decision.js +955 -0
  66. package/dist/hook/decision.js.map +1 -0
  67. package/dist/hook/memory-store.d.ts +81 -0
  68. package/dist/hook/memory-store.js +157 -0
  69. package/dist/hook/memory-store.js.map +1 -0
  70. package/dist/hook/payload.d.ts +55 -0
  71. package/dist/hook/payload.js +129 -0
  72. package/dist/hook/payload.js.map +1 -0
  73. package/dist/hook/run.d.ts +48 -0
  74. package/dist/hook/run.js +218 -0
  75. package/dist/hook/run.js.map +1 -0
  76. package/dist/hook/store-port.d.ts +72 -0
  77. package/dist/hook/store-port.js +2 -0
  78. package/dist/hook/store-port.js.map +1 -0
  79. package/dist/index.d.ts +1 -0
  80. package/dist/index.js +1 -0
  81. package/dist/index.js.map +1 -1
  82. package/dist/ports/audit.d.ts +18 -0
  83. package/dist/ports/audit.js +11 -0
  84. package/dist/ports/audit.js.map +1 -0
  85. package/dist/ports/clock.d.ts +14 -0
  86. package/dist/ports/clock.js +11 -0
  87. package/dist/ports/clock.js.map +1 -0
  88. package/dist/ports/decision.d.ts +75 -0
  89. package/dist/ports/decision.js +2 -0
  90. package/dist/ports/decision.js.map +1 -0
  91. package/dist/ports/index.d.ts +14 -0
  92. package/dist/ports/index.js +2 -0
  93. package/dist/ports/index.js.map +1 -0
  94. package/dist/ports/log.d.ts +22 -0
  95. package/dist/ports/log.js +12 -0
  96. package/dist/ports/log.js.map +1 -0
  97. package/dist/ports/state.d.ts +46 -0
  98. package/dist/ports/state.js +13 -0
  99. package/dist/ports/state.js.map +1 -0
  100. package/dist/state/clock.d.ts +40 -0
  101. package/dist/state/clock.js +43 -0
  102. package/dist/state/clock.js.map +1 -0
  103. package/dist/state/file-store.d.ts +340 -0
  104. package/dist/state/file-store.js +849 -0
  105. package/dist/state/file-store.js.map +1 -0
  106. package/dist/state/paths.d.ts +41 -0
  107. package/dist/state/paths.js +73 -0
  108. package/dist/state/paths.js.map +1 -0
  109. package/docs/USER_GUIDE.en.md +79 -36
  110. package/docs/claude-code.md +281 -0
  111. package/docs/design/v0.2.0-harness-plugins.md +381 -0
  112. package/docs/design/v0.3.0-orchestration-unification.md +580 -0
  113. package/docs/dsh-plugin.md +54 -54
  114. package/docs/release-checklist-v0.1.0.md +32 -21
  115. package/docs/release-handbook-porting-notes.md +11 -11
  116. package/docs/release-handbook.md +55 -30
  117. package/docs/release-notes-v0.1.0.md +27 -14
  118. package/docs/release-notes-v0.3.0.md +152 -0
  119. package/docs/research/claude-code-harness.md +607 -0
  120. package/docs/research/pi-harness.md +621 -0
  121. package/package.json +16 -7
@@ -0,0 +1,381 @@
1
+ # v0.2.0 Harness 插件设计:Claude Code 与 pi
2
+
3
+ > 定位:**决策文档,不是资料堆**。依据是两份调研
4
+ > `docs/research/claude-code-harness.md`(下称 **CC**)与 `docs/research/pi-harness.md`(下称 **PI**),
5
+ > 加上本仓库现行实现(下称 **DSH**:`packages/dsh-harness-reflex/src/interventions.ts`、`docs/dsh-plugin.md`)。
6
+ > 边界:只写设计与范围,不写实现代码,不改版本号。所有「❌ / 做不到」都指向调研的具体章节;
7
+ > 由事实推导的结论显式标 **推断**,不冒充官方承诺。
8
+ >
9
+ > 状态:**待负责人拍板**(§6 共 5 件事);快照 2026-10-22;设计基线 `0.2.0-test`(两份调研与
10
+ > `packages/dsh-harness-reflex/src/interventions.ts` 均以该分支为准,发布基线 `96ee842` 缺 `interventions.ts`)。
11
+
12
+ ## 0. 结论速览
13
+
14
+ - **能力面**:pi 能复刻 10 项中的 7 项、3 项部分、0 项做不到;Claude Code 4/5/1,唯一 ❌ 是设置面板;
15
+ DSH 自身 8/2/0(剪枝与收尾在 DSH 里也不是「满格」——剪枝靠留存契约、收尾只是 steering)。
16
+ - **代码共享**:判定面可共享 **85%–90%**;单 harness 端到端 **~78%**;第二个 harness 的新增代码只有
17
+ **~20%–25%**(纯适配层)。所以「三 harness 共享 80%」对判定面成立,对端到端是**上限而非保证**(§2.2)。
18
+ - **状态**:Claude Code 的 command hook 每次都是新进程(CC §2.1/§2.7),**必须**有外部会话状态;
19
+ pi 是进程内模块可放内存,但为了账本/面板同口径,两者统一走同一 `StatePort`(§3)。
20
+ - **MVP**:内核 + 状态 + `hook` 子命令 + **Claude Code 三件套的自动层**(剪枝/停滞/纠偏 active,
21
+ 收尾核验默认 observe),不含虚拟模型、思考等级、面板、pi(§4.2)。
22
+ - **建议先做 Claude Code**,理由见 §4.3:它逼出无状态 hook + 外部存储这条最难的路,pi 在其后只需薄适配。
23
+
24
+ ## 1. 能力矩阵(10 行 × 3 列)
25
+
26
+ 读法:`✅` 语义等价 · `🟡` 能做但语义降级或需自建 · `❌` 做不了。
27
+ DSH 列是「现行实现」,CC/PI 列是「能否复刻 DSH 这一格」。
28
+
29
+ | # | 能力 | DSH(现行) | Claude Code | pi |
30
+ |---|---|---|---|---|
31
+ | 1 | **8 工具面**(MCP:含 prune / detect_stagnation / status_ledger) | 🟡 根包 stdio MCP 有 8 个,但 DSH 宿主面只有 5 个;prune/停滞/账本不占工具位 | ✅ 同一 stdio server 原样暴露,模型以 `mcp__<server>__<tool>` 调用(CC §3.1/§3.2/§5.3) | ✅ `registerTool()` 直接注册,参数用 TypeBox 校验,`exposure` 可调(PI §3.1/§3.4) |
32
+ | 2 | **5 工具面**(可开关的进程内工具) | ✅ `defineTool` × 5,route 默认关(DSH §1–§2) | ✅ 同一批 5 工具走 MCP;开关靠 allowlist / `disabledMcpServers` / tool search(CC §3.2/§5.3) | ✅ `setActiveTools()` + `exposure:"hidden"`;注意**工具不能反注册**(PI §3.1/§3.4/§8) |
33
+ | 3 | **剪枝** | ✅ `tools/post-execute` 自动改写,原文进 session log + digest locator,缩短才记 saved(DSH) | 🟡 `PostToolUse.updatedToolOutput` 可改模型可见输出,但原文留存/locator/「验证后才记 saved」全要自建;失败结果走 `PostToolUseFailure`,**不能替换错误文本**(CC §2.3/§5.2) | ✅ `tool_result` 返回替换后的 `content/details/structuredContent`,handler 链式组合;改 content 必须同时处理 structuredContent(PI §3.2/§3.3) |
34
+ | 4 | **停滞检测** | ✅ `tools/pre-execute` deny + `agent/pre-step` 注入纠偏;三态 + per-turn/per-session 预算(DSH) | ✅ `PreToolUse` deny(bypass 模式仍生效)+ `PostToolUse.additionalContext` 软纠偏;判定与调用历史要自建(CC §2.2/§2.6/§5.2) | ✅ `tool_call` 返回 `{block:true,reason}`,handler 抛错也 fail-closed;状态须自维护,按 `toolCallId` 隔离(PI §3.2/§7.1/§8) |
35
+ | 5 | **收尾核验** | 🟡 `agent/turn-stopping` 只做 steering(提出异议),不硬阻断(DSH) | ✅ `Stop` 的 `decision:"block"` 可硬阻断——比 DSH 更硬;但有 **8 次连续上限**、必须处理 `stop_hook_active`、证据要自己跨调用累积(CC §2.4/§2.7) | 🟡 `agent_before_settle` 只能追加条目 + `continue:true` 请求**一次**续跑,**无 veto**;须自限次数防循环(PI §4.4/§3.3/§10-1) |
36
+ | 6 | **失效纠偏** | ✅ `tools/post-execute` 把重复失败转成 `kind:"block"` + feedback(DSH) | 🟡 `PostToolUseFailure` 只支持 `additionalContext`,不能替换错误文本;成功结果的重复失败模式可在 `PostToolUse` 用 `decision:block`+reason 注入(CC §2.3/§2.5/§5.2) | ✅ 同一 `tool_result` 可把错误输出替换成「纠正提示 + `isError:true`」,或 `message_end` 替换最终消息(PI §7.1/§9 抓手1) |
37
+ | 7 | **账本** | ✅ `DecisionLedger`:JSONL 追加 + 可选纯内存模式,`/reflex-ledger` 与面板读取(DSH) | 🟡 无内建台账;hook 无状态 → 必须自建外部存储 + 自定义命令/工具读取;`$.store` 只有 4 MiB(CC §7-2/§5.2) | 🟡 无 DSH 那种按 agent/attempt 隔离的账本;事件里没有 `agentId/attemptId`,须以 session + `toolCallId` 自建;`appendEntry` 可持久化非上下文数据(PI §7.3-2/§10-3/§2.4) |
38
+ | 8 | **虚拟模型** | ✅ 虚拟 provider + System 1 逐请求路由(DSH §1) | 🟡 无 provider 注册 API;**只有 mod 的 `turn.step`** 能 `next({...e, model})` 逐请求换模型;MCP 与 settings hook 都不能(CC §4.2) | ✅ `registerVirtualModel({route})` 是官方逐请求路由点,返回 `{model, thinkingLevel, state}`,粘性可保 prompt cache(PI §5.2/§9 抓手3) |
39
+ | 9 | **思考等级** | ✅ `agent/request` 改 `reasoningEffort`,并按模型词表投影(DSH §1) | 🟡 仅 mod 的 `turn.step` 能 `next({...e, effort})`;settings hook 只能读 `effort.level` 不能设,MCP 完全不能;非法等级行为未验证(CC §4.2/§8-2/§9) | ✅ `setThinkingLevel()`(按模型 clamp)+ `route()` 返回等级;无「任意字符串投影到模型词表」的 API,需自己约束(PI §5.1/§5.2/§7.2) |
40
+ | 10 | **设置面板** | ✅ Web 设置面板 6 个 tab(概览/Provider/强度/后端/账本/说明)(DSH §1) | ❌ plugin 组件清单里没有任何 UI/面板载体(CC §1.1),hook 进程也没有控制终端(CC §6.3)→ 只能退化为斜杠命令的文本输出(**推断**) | 🟡 `ctx.ui` 可 `setStatus/setWidget/notify/custom` + `registerCommand`,是 TUI 内联面而非独立面板;RPC/JSON/print 模式无 UI(PI §2.4) |
41
+
42
+ **矩阵自检**:Claude Code 4✅/5🟡/1❌,pi 7✅/3🟡/0❌,DSH 8✅/2🟡/0❌。
43
+ 唯一 ❌ 的两条依据都是「组件/终端面」的事实(CC §1.1、§6.3),不是「没找到就说不行」。
44
+ 反过来,**pi 没有 ❌ 不等于 pi 更强**:pi 的 3 个 🟡 里有两个是 DSH 语义的硬缺口(收尾无 veto、账本无隔离域)。
45
+
46
+ ## 2. 架构方案
47
+
48
+ ### 2.1 分层与依赖方向
49
+
50
+ ```
51
+ ┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐
52
+ │ Claude Code 载体 │ │ pi 载体 │ │ DSH 载体(已有) │
53
+ │ plugin 三件套 │ │ 一个 extension │ │ Cordis 插件 │
54
+ └────────┬─────────┘ └────────┬─────────┘ └────────┬─────────┘
55
+ │ │ │
56
+ └──────────┬───────────┴──────────┬───────────┘
57
+ ▼ 只允许向下依赖(编译期单向)
58
+ ┌──────────────────────────────────────────────────────┐
59
+ │ adapters/<harness>/ 事件名与载荷解析 · 决策→动作编码 │
60
+ │ claude-code/{mod.ts, hooks.ts, mcp} pi/{extension.ts}│
61
+ └──────────────────────────┬───────────────────────────┘
62
+ ▼
63
+ ┌──────────────────────────────────────────────────────┐
64
+ │ core/ 判定 · 三态与预算 · 剪枝计划 · 停滞 · 纠偏 · │
65
+ │ 收尾核验 · 证据组装 · 账本 · 路由/评分/筛查 │
66
+ │ (纯逻辑;不得 import adapters/ 或 state/) │
67
+ └───────┬──────────────────────────────────┬───────────┘
68
+ ▼ ▼
69
+ ┌───────────────┐ ┌──────────────────────┐
70
+ │ ports/ 接口 │◄────────────────│ state/ 实现 StatePort │
71
+ │ HarnessPort │ state 实现端口 │ FileStateStore │
72
+ │ StatePort │ 而不是被 core │ MemoryStateStore │
73
+ │ OriginalStore │ 反向依赖 │ │
74
+ └───────┬───────┘ └──────────────────────┘
75
+ ▼
76
+ ┌───────────────┐
77
+ │ backend/ 判定 │ jev · simple-jev · mock(可离线、可注错)
78
+ └───────────────┘
79
+ ```
80
+
81
+ 规则(可用一条测试自动守住):
82
+
83
+ 1. `core/` 的 import 只允许 `core/`、`ports/`、`backend/types`;**禁止** `adapters/*`、`state/*`、`node:fs`。
84
+ 2. `adapters/a` 不得 import `adapters/b`;跨 harness 的唯一共享物是 `core/` + `ports/`。
85
+ 3. `state/` 可 import `ports/` 与 `node:fs`,但**不得** import `adapters/`。
86
+ 4. 判定后端的选型(jev / mock / simple-jev)只由配置注入,适配层不得读环境变量决定判定语义。
87
+
88
+ ### 2.2 共享内核 vs 适配层:目录与共享度量化
89
+
90
+ 目标态目录(★ 新增 / 需重写;⛔ 既有,复用或微调):
91
+
92
+ ```
93
+ src/
94
+ ├── backend/ 判定后端(已有,不动)
95
+ ├── core/ ★ 共享内核(harness 无关)
96
+ │ ├── policy.ts ★ 三态 off/observe/active + per-turn/per-session 预算 + 失败放行
97
+ │ ├── judge.ts ★ 一次判定 = 输入(候选/证据) → verdict;带幂等键与缓存
98
+ │ ├── prune-plan.ts ★ 剪枝**计划**(保留原文 → 产出 locator + 缩减文本),不含改写动作
99
+ │ ├── stagnation.ts ⛔ 判据复用,补「签名 + 滑动窗口」纯函数
100
+ │ ├── gate.ts ⛔ 证据核验(fail-closed)复用
101
+ │ ├── closing.ts ★ 收尾核验:声明 vs 证据 → {contradicted|insufficient|ok}
102
+ │ ├── evidence.ts ★ 证据组装(工具结果 → 可核验断言)
103
+ │ ├── ledger.ts ⛔ 追加/摘要/内存模式复用,schema 增 harness 字段
104
+ │ └── {route,score,screen,calibrate}.ts ⛔ 原样复用
105
+ ├── ports/ ★ 端口(接口 + 纯类型,零实现)
106
+ │ ├── harness.ts 事件 → 内核输入的归一,内核输出 → 动作语义(三态动作)
107
+ │ ├── state.ts 会话状态读写(含预算扣减、dedupe)
108
+ │ └── originals.ts 原文留存/还原(locator)
109
+ ├── state/ ★ 端口实现
110
+ │ ├── file-store.ts 无状态进程用(Claude Code hook)
111
+ │ ├── memory-store.ts 进程内用(pi / DSH)
112
+ │ └── locator.ts
113
+ ├── adapters/
114
+ │ ├── {claude,codex,agy}.ts ⛔ 既有安装器适配,不动
115
+ │ ├── claude-code/ ★ hooks 协议编码 + mod 注册 + `.mcp.json` 生成
116
+ │ └── pi/ ★ extension 工厂 + 事件注册 + 工具注册
117
+ └── cli/index.ts ⛔ 新增 `hook <event>` 子命令(已有空壳,见 src/cli/index.ts:260)
118
+ ```
119
+
120
+ **共享度量化**(按需实现的代码行估算,不含测试):
121
+
122
+ | 功能块 | 估算行数 | 可共享 | 说明 |
123
+ |---|---|---|---|
124
+ | 判定调度 / 三态 / 预算 / verdict 缓存 | 900–1200 | 90% | 唯一差异是「时钟 + 锁」,端口可吸收 |
125
+ | 剪枝计划 + 留存契约 | ~300 | 85% | 「怎么改写输出」是适配层的 15% |
126
+ | 停滞签名与判定 | ~250 | 95% | 纯函数 |
127
+ | 失效纠偏文本与触发 | ~200 | 85% | 注入点不同 |
128
+ | 收尾核验(声明 vs 证据) | ~250 | 80% | 裁决→动作映射三份(见下) |
129
+ | 证据组装 | ~200 | 95% | 纯函数 |
130
+ | 账本 / 路由 / 评分 / 筛查 / 校准 | ~1500 | 100% | 已有 |
131
+ | **判定面小计** | **~3600** | **≈89%** | |
132
+ | 适配层(每个 harness) | 600–1200 | 0% | 事件解析 · 输出编码 · 状态载体 · 模型设定 · 分发 |
133
+ | **单 harness 端到端** | **~4500** | **≈78%(首个)** | 第二个 harness 追加 ~20%–22% |
134
+
135
+ **结论(回答「能否共享 80%」)**:判定面 85%–90%,可以;端到端 78%,**80% 是上限**。
136
+ 三处结构性不可共享,必须写三份:
137
+
138
+ 1. **裁决 → 动作**:DSH 是 `agent/turn-stopping` 的 steering;Claude Code 是 `{"decision":"block"}` 硬闸;
139
+ pi 是「追加一条 custom_message + `continue:true`」。同一个 verdict,三种动作,**不能抽成同一段代码**,
140
+ 只能抽到「ActionPlan 三态(放行/附注/阻断-或-续跑)」再由适配层展开(能再吃掉 5–8 个百分点)。
141
+ 2. **状态载体**:DSH 有 per-agent `AgentState`;Claude Code 只有 stdin 的 `session_id`;pi 有进程内
142
+ `ctx` + `appendEntry`。
143
+ 3. **输出编码**:Claude Code 的 `hookSpecificOutput` 嵌套(`permissionDecision` / `updatedToolOutput` /
144
+ `additionalContext`)vs pi 的扁平 `{block, reason}` / `{content, details}`。
145
+
146
+ ### 2.3 Claude Code 载体:plugin 三件套
147
+
148
+ 一个 plugin 目录同时携带三种组件(CC §1.1 确认可同装):
149
+
150
+ | 载体 | 职责 | 能做 | 明确不能 |
151
+ |---|---|---|---|
152
+ | **mod**(`hooks/hooks.json` → `modules:["./register.js"]`,进程内) | 自动干预的**主路径**:`tool.call` deny/改写、`session.append` 改写输出、`turn.step` 设模型/effort | 状态在内存里,零 fork;可改 model/effort(CC §4.2) | 需要 v2.1.287+;WSL 桌面会话不加载;`classic.Stop` 无 block 保证(CC §7/§9) |
153
+ | **MCP server**(`.mcp.json`,stdio) | 决策**工具面**(8 个 `reflex_*` 原样) | 模型主动调用 | 纯 MCP **不能**做任何自动干预(CC §8-1),不能设模型/effort(CC §8-2) |
154
+ | **settings hooks**(`hooks/hooks.json` 的 command 类型) | **硬闸与兜底**:`Stop` 阻断、`PreToolUse` deny、无 mod 时的降级通道 | Stop 可硬阻断(CC §2.4) | 每次 fork;默认 600s 超时;默认 fail-open(CC §2.7) |
155
+
156
+ **hook 事件表**(`harness-reflex hook <event>`,契约见 §2.5):
157
+
158
+ | 事件 | 子命令 | 读取的 stdin 字段 | stdout | 失败策略 | 内部预算 / hook timeout |
159
+ |---|---|---|---|---|---|
160
+ | `PreToolUse` | `pretooluse` | `session_id` `tool_name` `tool_input` `tool_use_id` | 有 verdict:`{"hookSpecificOutput":{"permissionDecision":"deny","permissionDecisionReason":…}}`;否则 `{}` | **F1 放行** | 300 ms / 1 s |
161
+ | `PostToolUse` | `posttooluse` | 上列 + `tool_response` `duration_ms` | `hookSpecificOutput.updatedToolOutput`(剪枝)、`additionalContext`(纠偏) | **F1 放行** | 800 ms / 2 s |
162
+ | `PostToolUseFailure` | `postfailure` | `tool_name` `tool_input` `error` | 仅 `additionalContext`(官方不支持替换错误文本) | **F1 放行** | 300 ms / 1 s |
163
+ | `Stop` | `stop` | `stop_hook_active` `last_assistant_message` `transcript_path` `background_tasks` | `{"decision":"block","reason":…}` 或 `{}` | **F3**:只有决策本身能阻断,内部错误一律放行 | 1000 ms / 2 s |
164
+ | `SubagentStop` | `substop` | 同 Stop + `agent_id` `agent_type` | 同 Stop(首发默认关闭) | **F3** | 1000 ms / 2 s |
165
+ | `SessionStart` | `sessionstart` | `session_id` `source` `cwd` | `additionalContext`(仅告知当前三态,不注入业务文本) | **F2 静默放行** | 1200 ms / 2 s |
166
+ | `SessionEnd` | `sessionend` | `session_id` `reason` | `{}`(flush + gc) | **F2 静默放行** | 1200 ms / 2 s(官方 SessionEnd 共享 1.5 s) |
167
+
168
+ 失败策略定义:
169
+
170
+ - **F1 放行 + 审计**:超时/崩溃/坏 JSON → exit 0、stdout `{}`,把错误写进账本 `type:"error"`。
171
+ 不设 `onFailure:"block"`——`onFailure` 有版本门槛(v2.1.295),且判定类 hook 崩溃即阻断会把
172
+ 「反射层」变成「单点故障」。
173
+ - **F2 静默放行**:连审计都只写本地文件,绝不阻塞会话起止。
174
+ - **F3 决策式**:「能阻断」只来自子命令**正常算出**的 `decision:"block"`,不来自崩溃。
175
+ 每次 block 都记 `turnNo`,并在 `stop_hook_active === true` 时直接放行(官方用它防死循环,
176
+ 另有 8 次硬上限,CC §2.4)。
177
+
178
+ 接线要点(都是官方契约约束,不是口味):
179
+
180
+ - `if` 匹配器只订阅会产出大结果/重复调用的工具(`Bash` / `Edit` / `Write` / `MultiEdit` / MCP 通配),
181
+ 不匹配时**不 spawn**(CC §2.8)。
182
+ - `PostToolUse` 改写前必须**先把原文落盘成功**,否则不替换(复刻 DSH「没有留存就不记 saved」)。
183
+ - 多个 PreToolUse 同时改 `updatedInput` 的顺序不确定(CC §6.1),因此**我们永远不返回 `updatedInput`**,
184
+ 只返回 `deny` 或附加 `additionalContext`。
185
+ - 输出文本受 10,000 字符上限约束(CC §2.7),长证据只给 locator + 摘要。
186
+
187
+ ### 2.4 pi 载体:一个 extension 包
188
+
189
+ 包形态:`pi install npm:harness-reflex-pi`(或 `pi -e ./ext`),peer 依赖宿主包(PI §2.2)。
190
+ 注册面:
191
+
192
+ | 注册项 | 内容 | 说明 |
193
+ |---|---|---|
194
+ | 工具 × 5 | `reflex_choice / score / route / screen / gate` | 与 DSH 宿主面一致;`route` 默认 `exposure:"hidden"`。**不注册** prune/detect_stagnation/status_ledger——pi 里这三项是自动层 + `/reflex-ledger` 命令,避免 pull 版与自动版双重干预 |
195
+ | 命令 × 1 | `/reflex-ledger [--last N] [--json]` | 读同一账本实现;`ctx.mode !== "tui"` 时降级为纯文本 |
196
+ | 虚拟模型(S5,默认关) | `registerVirtualModel({provider:"reflex", id:"auto", route})` | `route()` 内调内核路由,返回物理 `{model, thinkingLevel}`;粘性用 `request.previous/failed` 保 cache(PI §5.2) |
197
+
198
+ 事件订阅:
199
+
200
+ | 事件 | 用途 | 返回/动作 | 依据 |
201
+ |---|---|---|---|
202
+ | `session_start` | 建 `MemoryStateStore`,装配置;`session_shutdown` 幂等释放 | — | PI §2.1 |
203
+ | `tool_call` | 停滞判定 → 拒绝 | `{block:true, reason}` | PI §3.2 |
204
+ | `tool_result` | 剪枝(改写 content,**同时**带 `structuredContent`)与失效纠偏(`isError:true` + 纠正文本) | `{content, details, structuredContent, isError}` | PI §3.2/§3.3 |
205
+ | `turn_end` | 回合级续跑边界(可动作) | `{entries:[…], continue:true}` | PI §4.2 |
206
+ | `agent_before_settle` | 收尾核验:不通过则追加纠偏消息 + 续跑 | 同上,**上限 1 次/回合、2 次/会话** | PI §4.4 |
207
+ | `model_select` / `thinking_level_select` | 只观察,写账本(不改用户选择) | 无返回 | PI §5.3 |
208
+ | `session_compact` / `session_shutdown` | 账本 flush + 留存 gc | — | PI §2.1 |
209
+
210
+ **「收尾只能续跑不能否决」怎么用**(这是 pi 侧最容易被写错的语义):
211
+
212
+ 1. 在 `agent_before_settle` 用内核 `closing` 判 verdict;`ok` / `insufficient` → 放行(`insufficient`
213
+ 只记账,不打扰用户)。
214
+ 2. `contradicted` 且本回合续跑次数 `< 1` → 往 `event.entries` 追加一条
215
+ `custom_message`(`customType:"reflex.verdict"`,内容 = 可执行的反证清单 + 期望动作),
216
+ 返回 `continue:true`。**必须**同时追加非 assistant 条目,否则 `canContinue` 为假、续跑被丢弃(PI §4.4)。
217
+ 3. 第二轮无论结论如何都放行,账本记 `closing:unresolved`。绝不无条件 `continue`(无宿主熔断,PI §4.4)。
218
+ 4. 语义差写进 README:Claude Code 是「不通过不许结束」,pi 是「不通过再给一次机会,然后记账放行」。
219
+
220
+ ### 2.5 `harness-reflex hook <event>` CLI 契约
221
+
222
+ ```
223
+ harness-reflex hook <event> # event ∈ pretooluse|posttooluse|postfailure|stop|substop|sessionstart|sessionend
224
+ stdin : 宿主原始事件 JSON(不加 wrapper,便于用真实录制事件回放)
225
+ env : HARNESS_REFLEX_STATE_DIR 状态根
226
+ HARNESS_REFLEX_MODE off|observe|active(缺省 active,config 可覆盖)
227
+ HARNESS_REFLEX_CLOCK ISO 时间,测试用固定时钟
228
+ stdout : 只输出协议 JSON;诊断一律 stderr
229
+ exit : 0 = 正常(决策以 JSON 表达);非 0 仅表示「已放弃」,宿主按 F1/F2 放行
230
+ ```
231
+
232
+ 硬约束:① stdout **永远**不能出现非 JSON 字节(会被当作 deny reason 拼进模型上下文);
233
+ ② 任何异常都 exit 0 + `{}`;③ 幂等——`dedupeKey = sha256(session_id + event + tool_use_id + tool_name +
234
+ input_digest)` 命中则直接 `{}`,防 hook 重试导致双剪枝/双阻断。
235
+
236
+ ## 3. 状态与存储(hook 无状态进程的关键难点)
237
+
238
+ ### 3.1 为什么必须有外部载体
239
+
240
+ - Claude Code 的 command hook **每次都是新进程**,事件之间没有任何共享内存(CC §2.1/§2.7);
241
+ `Stop` 里要用的「本轮工具证据」必须由先前的 hook 落盘,`transcript_path` 异步且可能滞后(CC §7 抓手3)。
242
+ - pi 扩展是进程内,可以放内存,但 `session_shutdown` 后 `/reflex-ledger` 与面板要能读同一份账本(PI §2.4),
243
+ 所以统一抽象成 `StatePort`,两套实现:`FileStateStore`(hook 进程)/ `MemoryStateStore`(进程内)。
244
+ - DSH 已有 per-agent `AgentState`,其 `StatePort` 实现就是内存 + session log 投影。
245
+
246
+ ### 3.2 目录布局
247
+
248
+ ```
249
+ $HARNESS_REFLEX_STATE_DIR # 默认 ${XDG_STATE_HOME:-~/.local/state}/harness-reflex
250
+ └── sessions/
251
+ └── cc-3f9a1c2b7d4e5f60/ # sha256(harness + "\0" + session_id)[:16](防路径穿越)
252
+ ├── meta.json {harness, sessionId 明文, createdAt, harnessVersion, mode}
253
+ ├── state.json 派生缓存:{turnNo, appliedSignatures[], budgets{}, continues{}}
254
+ ├── events.jsonl 追加:每次工具事件一行(停滞窗口 / 证据组装的唯一来源)
255
+ ├── ledger.jsonl 追加:决策与节省(权威账本,DSH 同 schema + harness 字段)
256
+ ├── originals/<digest>.txt 剪枝原文(locator = digest + 行区间)
257
+ ├── lock/ mkdir 原子锁(内含 pid + 起始时间)
258
+ ├── corrupt-<ts>.log 解析失败行的隔离副本
259
+ └── ../orphans/<hash>/ 目录名与 meta 不一致的会话目录迁入此处,等人读,不自动删
260
+ ```
261
+
262
+ **放哪、为什么这么放**:用户态(`XDG_STATE_HOME`)而不是项目目录——`.reflex/` 已用于项目级账本,
263
+ 把它塞进仓库会污染 git;而 Claude Code 的 `${CLAUDE_PLUGIN_DATA}` 有容量与生命周期约束(CC §7 抓手2 提到
264
+ `$.store` 4 MiB / `$.fs` 单文件 4 MiB),不适合当剪枝原文仓库。用 `HARNESS_REFLEX_STATE_DIR` 可整体迁移到
265
+ 插件 data 目录,作为「小体积、随插件卸载清理」的备选部署形态。
266
+
267
+ ### 3.3 写协议:日志追加优先,状态只是缓存
268
+
269
+ | 数据 | 写法 | 并发安全 | 备注 |
270
+ |---|---|---|---|
271
+ | `events.jsonl` / `ledger.jsonl` | `appendFileSync`,单行 ≤ 4 KiB,一次 write | **天然并发安全**(O_APPEND 单写原子) | 权威数据;读取用尾部 N 行,绝不整文件载入 |
272
+ | `originals/<digest>.txt` | `wx` 独占创建(同名即已存在,视为成功) | 安全 | 内容不可变,天然幂等 |
273
+ | `state.json` | `state.json.tmp` → `fsync` → `rename` | 读改写需 `lock/` | Windows 上 rename-over-existing 可能失败 → unlink 重试 |
274
+ | 预算扣减 | 先 `lock/`(mkdir 原子),再读改写 | mkdir 锁 + 5 s stale 判定 | 拿不到锁 → **跳过本回合判定**并记 `skippedLockContention` |
275
+
276
+ 两条决定性规则:
277
+
278
+ 1. **预算是抑制旋钮,不是正确性前提**。拿不到锁/写失败时,宁可这回合不判定,也不阻塞工具调用。
279
+ 2. **`state.json` 永不是权威**:删掉它、损坏它、落后它,都能从 `events.jsonl` + `ledger.jsonl` 重算。
280
+ 这一条把「并发丢更新」从正确性问题降级成性能问题。
281
+
282
+ ### 3.4 并发、回合号、清理、损坏恢复
283
+
284
+ - **并发模型**:同一事件的多个 handler 并行、工具调用也可并行(CC §2.1/§6.1;PI §3.2 兄弟调用会交错)。
285
+ 因此同 session 目录会被多进程写:日志并行追加、`state.json` 由锁串行、读取允许脏。
286
+ - **回合号**:Claude Code 的事件里**没有** turn 号,唯一可靠的回合边界是 `Stop`。故 `turnNo` 只在
287
+ `stop`/`substop` 子命令里 `++`,其他事件只读;per-turn 预算在 `Stop` 写入时重置。
288
+ pi 侧对应 `turn_end`。
289
+ - **清理**:`sessionend` + `sessionstart` 时 gc `mtime > 7d` 的会话目录;`harness-reflex ledger gc` 手动可跑。
290
+ 单会话 `originals/` 上限 32 MiB,超限按 mtime LRU 删除并记 `retention:"evicted"`——被驱逐后的剪枝
291
+ **降级为「只缩减不留存、不计 saved」**(与 DSH 的审计纪律一致,不产生无法还原的 locator)。
292
+ - **损坏恢复**:JSONL 逐行 `try/parse`,坏行进 `corrupt-*.log` 并继续;某文件坏行 > 5 则整份作废重算;
293
+ `state.json` 损坏直接删除重算;`meta.json` 与目录名不一致(session_id 哈希不匹配)则整目录迁入 `orphans/`。
294
+ - **安全**:目录 0700、文件 0600;`session_id` 只用于哈希,明文只在 `meta.json`;路径分隔符与 `..`
295
+ 在家目录之外一律拒绝;任何进入模型可见文本的内容只含 digest 与文件名,**不含绝对路径**(避免泄露本机布局)。
296
+ - **可测试性**:`HARNESS_REFLEX_STATE_DIR` + `HARNESS_REFLEX_CLOCK` 让「并发写 / kill -9 / 损坏文件 /
297
+ 时钟回拨」四类场景都能用子进程夹具复现。
298
+
299
+ ## 4. 实现分片与顺序
300
+
301
+ ### 4.1 五个切片
302
+
303
+ | 切片 | 范围 | 验收方式(可执行) | 风险 |
304
+ |---|---|---|---|
305
+ | **S1 内核抽取 + 端口**(中) | 把 `interventions.ts` 的判定/三态/预算抽到 `core/`;新增 `core/{policy,judge,closing,evidence,prune-plan}.ts` 与 `ports/`;DSH 适配层改为消费内核(行为零变化) | `npm run build:all` exit 0;`npm test` 113/113、`test:plugin` 419/419 **零回归**;新增内核单测 ≥ 20;**架构依赖测试 1 条**(禁止 `core → adapters/state`、禁止 adapter 互引);mutation-check 通过 | 中(大范围搬迁但语义不变) |
306
+ | **S2 `hook` 子命令 + FileStateStore**(高) | §2.5 契约 + §3 全部写协议与恢复;先只用 mock 后端 | 夹具 12 例:正常/无决策/坏 JSON/超大 stdin/信号中断/超时/重复投递(幂等)/`stop_hook_active`/三态各一;**50 并发进程写同一 session**,`ledger.jsonl` 行数守恒且每行可解析;`kill -9` 后重放不丢不重;损坏文件 3 例仍能出决策 | **高**(并发与原子写) |
307
+ | **S3 Claude Code 三件套**(最高) | plugin 目录 + mod + settings hooks + `.mcp.json`;剪枝/停滞/纠偏 active,收尾核验默认 observe | `claude plugin validate` 通过;`claude -p` 脚本 e2e:Stop block 一次(含 `stop_hook_active` 第二次放行)、PostToolUse 剪枝后模型可见长度下降且 locator 可还原;**observe 模式与关闭态 diff=0**;hook 崩溃注入后仍放行且账本记 error | **最高**(见下) |
308
+ | **S4 pi extension**(中) | §2.4 的包、5 工具、`/reflex-ledger`、三个自动能力 | `pi --extension ./dist/ext.js --help` 加载成功(已证 jiti 免构建);`tool_result` 剪枝前后字符数断言;`agent_before_settle` 只续跑 1 次(第 3 次调用不 continue);`tool_call` block 后模型收到 reason | 中(API 1.x 仍有 breaking,PI §8) |
309
+ | **S5 模型面 + 观察面**(低) | pi 虚拟模型 `reflex/auto`(默认关)、Claude mod 的 `turn.step` effort(opt-in);`harness-reflex ledger --session` | 同一份 `ledger.jsonl` 输入 → CLI 摘要与 DSH 面板数字**逐字段相等**(口径一致性测试);effort 越界按模型词表 clamp | 低 |
310
+
311
+ **风险最高:S3**。理由:① 同一插件要同时踩三个载体,任一版本门槛(mods v2.1.287、`onFailure` v2.1.295、
312
+ `PreModelSwitch` v2.1.251)都改变可用面(CC §6.1);② 企业策略可整体关门(`disableAllHooks`、
313
+ `allowManagedHooksOnly`、`--safe-mode`),作者不可控(CC §6.4);③ 8 次 Stop 上限 + WSL 桌面不加载 plugin,
314
+ 让「装了就一定生效」不成立(CC §1.3/§2.4);④ 无法在 CI 完整验证(需要真实 `claude` 二进制与模型凭据),
315
+ 只能靠「脚本化 `-p` e2e + observe diff=0」逼近。S2 的并发风险虽高,但它是**纯本地、可完全自动化验证**的风险。
316
+
317
+ ### 4.2 MVP 定义(最小可发布范围)
318
+
319
+ > **MVP = S1 + S2 + S3 的闭环**,一个安装包、一份状态、一个账本,四项干预里有三项真正生效。
320
+
321
+ 包含:
322
+
323
+ - 自动层:**剪枝 active**、**停滞 active**、**失效纠偏 active**、**收尾核验默认 observe**(opt-in 可 active);
324
+ - 工具面:根包 8 个 `reflex_*` MCP 工具**原样不动**(不新增、不改契约);
325
+ - 账本:`ledger.jsonl` 落盘 + `harness-reflex ledger --session <id>` 可读(含 `saved` 只在留存成功时出现);
326
+ - 三态:`off / observe / active`,`observe` 保证**零模型可见变化**(这是发布前必须验证的一条)。
327
+
328
+ 不包含:虚拟模型、思考等级、设置面板、pi 载体、Windows 原生、云会话、子代理隔离域。
329
+
330
+ MVP 发布判据(可逐条验收):① 测试与负向对照全绿;② 真机 observe diff=0;③ 判定后端人为抛错仍放行并记账;
331
+ ④ 卸载后不新建状态目录、不留残留进程;⑤ 未引入任何运行时依赖(根包 `package.json` 现无 `dependencies`)。
332
+
333
+ ### 4.3 建议先做哪个 harness:**Claude Code**
334
+
335
+ 1. **它逼出最难的路**:无状态 hook + 外部存储 + 输出编码。先做它,内核抽象会在最苛刻的约束下成型;
336
+ 反过来先做 pi(进程内、可放内存)会把内存假设固化进内核,之后为 Claude Code 返工。
337
+ 2. **风险前置**:S3 是风险最高项,按「最高风险先验证」排序,它决定 v0.2.0 能不能发布;pi 无论何时做都不阻塞发布。
338
+ 3. **可交付性最强**:三件套可分别验证(MCP 工具面 → mod → hooks),每一步都有独立可观测产出。
339
+ 4. **pi 成本最低**:S4 只需 ~600–900 行适配层 + 复用内核(§2.2 的 20%–25%),放在后面做的**边际成本最小**;
340
+ 且它没有硬闸,晚做不影响「防护」这个核心卖点。
341
+
342
+ ## 5. 不做什么(本轮明确排除)
343
+
344
+ | 不做 | 理由 / 依据 |
345
+ |---|---|
346
+ | 撤销 Claude Code 上**已发生**的副作用 | `PostToolUse` 只能改模型看到的内容,文件/命令/网络副作用已发生(CC §2.3/§8-3) |
347
+ | 在 pi 上做**硬否决收尾** | `agent_before_settle` 无 veto,只有 `continue:true`(PI §4.4/§10-1);只做「续跑一次 + 记账放行」 |
348
+ | 做任何**设置面板 UI** | Claude Code 无 UI 载体(CC §1.1/§6.3);pi 只有 TUI 内联 `ctx.ui`(PI §2.4);DSH 面板复用既有,不新做 |
349
+ | 用 MCP 影响模型 / 思考等级 | 官方无此能力(CC §4.2/§8-2);Claude 侧只有 mod `turn.step` |
350
+ | 改写已流式产出的 token(pi) | `provider_stream_event` 只读(PI §10-2) |
351
+ | 替换 pi 内置 MCP 客户端 | 无需求;调用同走 `tool_call`/`tool_result` 管线即可(PI §6.2) |
352
+ | 做按 agent/attempt 的隔离域(pi) | 事件载荷无 `agentId/attemptId`(PI §7.3-2/§10-3);只用 session + `toolCallId` 做 key |
353
+ | Windows 原生首发支持 | hooks 依赖 Git Bash,缺失时 PreToolUse 会**阻止调用**(CC §6.1/§6.3);首发只保 Linux/macOS/WSL2,Windows 标 experimental |
354
+ | 支持 pi 1.4.0 之外的版本 | 1.x 频繁 breaking(PI §8);钉死 `@earendil-works/pi-coding-agent@1.4.0`,事件适配集中在一个文件 |
355
+ | 云端 / Remote Control 会话 | 云会话不读本地 settings(CC §1.3),无法保证状态目录存在 |
356
+ | 改根包 8 工具契约 / 改版本号 | 本目标只写设计;0.2.0 版本号由发布流程决定,不在设计里动 |
357
+ | 引入运行时依赖 | 根包当前零 `dependencies`;原子写/哈希/JSONL 全部用 `node:fs` + `node:crypto` 实现 |
358
+
359
+ ## 6. 待负责人拍板的 5 件事
360
+
361
+ | # | 事项 | 默认建议 |
362
+ |---|---|---|
363
+ | 1 | 首发 harness 顺序 | **Claude Code 先行**(§4.3),pi 排 S4 |
364
+ | 2 | 收尾核验首发默认档位 | **observe**:先积累一轮误报率再转 active;Claude 的 Stop 硬阻断杀伤面最大 |
365
+ | 3 | pi 是否只出 5 工具面 | **是**;三个 pull 版工具与自动层重复,后续可用 `exposure:"hidden"` 补 |
366
+ | 4 | 状态目录默认位置 | **用户态 XDG**,不用项目内 `.reflex/`(避免污染仓库);提供 `HARNESS_REFLEX_STATE_DIR` 覆盖 |
367
+ | 5 | 是否接受 pi「只能续跑一次」的语义上限 | **接受**并写进 README,不承诺与 Claude 等价的硬闸 |
368
+
369
+ 以上 5 项确认后,S1–S5 可直接按 §4.1 的表派单:每片都有「范围 → 验收命令 → 风险」三栏,
370
+ 不需要再回头补充设计。
371
+
372
+ ## 附录 A:两份调研的引用索引
373
+
374
+ | 记号 | 文件 | 本文引用点 |
375
+ |---|---|---|
376
+ | CC §x | `docs/research/claude-code-harness.md` | §1 矩阵、§2.3 三件套、§2.3 事件表预算、§3 状态、§5 不做 |
377
+ | PI §x | `docs/research/pi-harness.md` | §1 矩阵、§2.4 事件表、§3 状态、§5 不做 |
378
+ | DSH | `packages/dsh-harness-reflex/src/interventions.ts`、`docs/dsh-plugin.md` | 判定语义基线、三态、预算、留存契约 |
379
+
380
+ > 两份调研里标 **【未验证】** 的项(MCP sampling、`classic.Stop` 能否 block、command hook 单次 fork 耗时、
381
+ > `turn.step` 非法 effort、pi 真实会话下的 block/continue)**不影响本设计成立**:设计里没有任何一处依赖它们。