万字深研 ｜Harness 工程实践：指令遵从率 20%，Hook 执行率 100%

SessionStart → 加载上下文、重置风险状态
PreToolUse   → 拦截危险部署、门控审查 agent
PostToolUse  → 编辑时路由上下文、检测循环
Stop         → 验证完成候选品（transcript × git diff）
SessionEnd   → 反思、持久化进度

G0 问题 → G1 设计 → G2 审查★
  → G3 方案 → G4 审查+锁定★
  → G5 任务 → G6 审查★
  → G7 执行 → G8 终审★

★ = 独立审查者（独立上下文、只读工具）

git clone https://github.com/NatureBlueee/wow-harness.git
cd wow-harness
python3 scripts/install/phase2_auto.py /path/to/your/project --tier drop-in

your-project/
├── .claude/
│   ├── settings.json    # Hook 注册（追加模式，不覆盖已有）
│   ├── skills/          # 16 个 agent 行为定义
│   └── rules/           # 路径作用域上下文规则
├── scripts/
│   ├── hooks/           # 16 个生命周期 hook
│   └── checks/          # 15 个自动化验证器
└── CLAUDE.md            # 治理指南（自动生成，可编辑）

---
name: lead                           # 技能名称
description: 开发流程统领...           # 描述（用于触发匹配）
status: active                       # 状态
tier: entry                          # 层级
owner: nature                        # 维护者
last_audited: 2026-04-09             # 最后审计日期
triggers:                            # 触发条件
  - 新功能
  - 方向讨论
outputs:                             # 输出契约
  - Gate 包
  - 决策缺口
truth_policy:                        # 真相策略
  - 不复制实时仓库事实
---

meta 层（自省与进化）
  crystal-learn    → 提取失败模式，形成不变量
  skill-discovery  → 发现重复模式，提议新技能

entry 层（入口与编排）
  lead             → 9 Gate 状态机，流程阻塞者
  arch             → 架构设计，本质判断
  harness-dev-handoff → 新 session 接手入口

execution 层（执行与实现）
  harness-dev      → 全栈开发，代码实现
  guardian-fixer   → Guardian issue 自动修复管道
  task-arch        → WP 拆分
  plan-lock        → 计划冻结

# crystal-learn 的定位
"""
我是 harness 的适应性免疫系统。
我不修具体 bug，也不写产品代码。
我提取"这类错误为什么总会回来"，把它们压成不变量。
"""

## Truth Policy

我不是新的权威副本。我只负责把新 agent 引到当前仍然活着的真相源上。

SessionStart  →  session 开始时
PreToolUse    →  每次工具调用之前
PostToolUse   →  每次工具调用之后
PreCompact    →  上下文压缩之前
Stop          →  agent 尝试停止时
SessionEnd    →  session 结束时
PostToolUseFailure → 工具调用失败后

Claude Code 原生 Hook 事件

会话生命周期
  SessionStart     ← 会话开始时触发
  SessionEnd       ← 会话结束时触发
  Stop             ← AI 回复完成后触发
  PreCompact       ← 上下文压缩前触发

工具调用
  PreToolUse       ← 工具调用前触发
  PostToolUse      ← 工具调用后触发
  PostToolUseFailure ← 工具调用失败时触发

用户交互
  UserPromptSubmit ← 用户提交 prompt 时触发
  PermissionRequest ← 权限请求时触发

文件/环境
  FileChanged      ← 文件变更时触发
  WorktreeCreate/Remove ← Worktree 生命周期

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "*",
        "hooks": [
          { "type": "command", "command": "python3 scripts/hooks/session-start-reset-risk.py" }
        ]
      }
    ],
    "PreToolUse": [...],
    "PostToolUse": [...]
  }
}

用户打开新对话
      ↓
Claude Code 初始化会话
      ↓
读取 .claude/settings.json
      ↓
执行 SessionStart hooks
      ↓
hook 脚本的 stdout 被注入到会话的初始上下文
      ↓
会话正式开始，AI 可以看到 hook 输出的内容
这就是 wow-harness 所有魔法的根基——它不是"建议 AI 做什么"，而是在 AI 调用工具的瞬间，物理上允许或拒绝，同时在上下文中注入信息。

① session-start-reset-risk.py
  → 删除上次 session 的 risk-snapshot.json
  → exit 0（静默，不注入）
  → 作用：每个 session 从 R0 风险起步

② session-start-magic-docs.py
  → 检查自动生成的文档是否与源码同步
  → 如果有漂移：stdout 输出漂移告警 → 注入 AI 上下文
  → 如果无漂移：exit 0（静默）
  → 作用：防止 AI 基于过期文档工作

③ session-start-toolkit-reminder.py
  → 输出可用 skills 和工具清单
  → stdout 注入 → AI 知道自己有什么技能
  → 作用：防止 AI 忘记自己能做什么

[SessionStart 注入]
=== ADR-038 D5 Magic Doc Drift Alert ===
  DRIFT: docs/magic/api-routes.md (source: backend/product/routes/ changed)

[toolkit-reminder 注入]
可用 Skills: lead, arch, plan-lock, bug-triage, crystal-learn ...

④ tool-call-counter.py
  → 计数器 +1（第 1 次调用）
  → 每 50 次调用才注入 Objective Recitation
  → 第 1 次：exit 0（静默）

⑤ sanitize-on-read.py
  → 读取目标文件，扫描敏感内容
  → 无 SECRET/TRADE_SECRET：exit 0
  → 有 PII/NETWORK：warn 但放行
  → 作用：防止密钥/密码进入 AI 上下文

（Read 操作不触发 guard-feedback.py，因为它只监听 Edit/Write）

⑥ tool-call-counter.py
  → 计数器 +1，仍不是 50 的倍数 → 静默

⑦ review-agent-gatekeeper.py
  → 检查是否在 spawn 审查 subagent
  → 当前是 Edit 不是 Task → exit 0（放行）

⑧ guard-feedback.py
  → 机制 A：上下文路由
    路由表查 "backend/product/routes/" → 匹配 "contract-consumers" 片段
    加载 context-fragments/contract-consumers.md
    → 注入 AI 上下文："改这个文件会影响以下消费方..."

  → 机制 B：guard 检查
    路由表查 "backend/product/routes/" → 匹配 "check_doc_freshness"
    运行 check_doc_freshness.run() → 如果文档过期，报告 finding
    → 注入 AI 上下文："文档可能需要同步更新"

  → Fragment 去重：同一 session 内同一片段只注入一次
  → exit 2（有输出，注入上下文）

⑨ loop-detection.py
  → 检查 backend/product/routes/protocol.py 被编辑次数
  → 第 1 次编辑：不触发告警 → exit 0
  → 如果同一文件编辑 ≥5 次：
    注入 "[LoopDetection] 你已经编辑 X 5 次了。考虑换方法。"

⑩ risk-tracker.py
  → 分析被编辑文件的路径
    "backend/product/routes/" → 匹配 RISK_ELEVATORS → R2
    → 写入 .towow/state/risk-snapshot.json:
      {"risk_level": "R2", "files_touched": [...]}
  → exit 0（不注入，纯记录）
  → 作用：风险只升不降（棘轮机制）

[guard-feedback 注入]
## Context
--- 此文件是 API 契约定义点，以下模块消费此契约：
- backend/product/bridge/bridge_client.py
- mcp-server/towow_mcp/client.py
- website/app/api/ 代理层
修改此文件时必须同步更新所有消费方。

## Guard Findings
- P2 doc_integrity: routes/protocol.py 变更后文档可能需要同步更新

⑪ deploy-guard.py
  → 解析 Bash 命令，发现包含受保护 IP "47.118.31.230"
  → 检测到 scp 上传操作
  → exit 1 + stderr: "BLOCKED: 禁止手动 scp 上传到受保护服务器"
  → Claude Code **物理阻止**这个 Bash 调用
  → AI 看到错误信息，被迫使用 deploy.sh

⑨ loop-detection.py
  → 计数器显示 protocol.py 已编辑 5 次
  → 注入："你已经编辑 protocol.py 5 次了。考虑换方法。"
  → AI 被迫停下来重新思考方案

⑫ stop-evaluator.py  →  整体流程：

  Step -1: 检查 stop_hook_active（CC 防循环字段）
           → 如果上一次 stop 已经注入过反馈 → 放行，避免无限循环

  Step 0: D8 机械化第一关（零 LLM 成本）
           → 调用 initializer-agent.py stop-check
           → 读取 .towow/progress/current.json
           → 检查所有 feature 的 status 是否 == "passing"
           → 检查所有 passing feature 是否有 evidence

           如果有 feature 不是 passing：
             → exit 2 + stderr: "D8 机械化第一关失败，以下 features 未 passing..."
             → **AI 被迫继续工作，不能 Stop**

           如果所有 feature 都 passing 且有 evidence：
             → 进入 Step 1

  Step 1: Completion Candidate 判定
           → 读取 session transcript（CC 提供的 .jsonl 文件）
           → 提取本 session 用 Edit/Write 写过的文件集合 A
           → 运行 git diff --name-only 获取未提交变更集合 B
           → A ∩ B 非空 → 是 completion candidate → 进入 Step 2
           → A ∩ B 为空 → 不是 completion candidate → 放行（纯聊天/研究场景）

  Step 2: 注入 stop-evaluator.md 检查清单
           → exit 2 + stderr: 完整的 completion review 流程

⑬ review-agent-gatekeeper.py
  → 检测到 spawn 的是 review subagent
  → 检查 prompt 中是否包含只读指令
  → 如果没有：exit 2，**阻止 spawn**
  → 如果有：记录 active-review-agent 标记 → exit 0
  → 作用：物理确保审查 agent 的 prompt 包含只读约束

⑭ precompact.sh
  → 输出必须保留的信息：
    - 当前 PLAN/TASK 状态
    - Sprint Contract 验收标准
    - 不可降级规则（guard > memory, 一个事实一个定义...）
    - Objective Recitation：从 progress.json 读取原始目标

  → 作用：压缩后 AI 不会丢失关键约束
  → 防止 "改着改着忘了原始目标" 的问题

⑮ session-reflection.py
  → 收集 guard 命中统计 + loop 统计
  → 写入 metrics JSONL
  → 如果有频繁编辑的文件：输出改进建议

⑯ trace-analyzer.py
  → 聚合 trace 数据用于 harness 优化

⑰ deploy-progress-on-session-end.py
  → 持久化部署进度

指令方式（CLAUDE.md 写 "修改后必须跑测试"）：
  AI 读取 → 理解 → 决定是否遵守 → ~20% 概率遵守
  ↑ 失败原因：AI 可能忘记、误解、或"创造性"忽略

Hook 方式（stop-evaluator.py 检查 progress.json）：
  AI 尝试 Stop → hook 运行 → 检查结果 → 100% 执行
  ↑ 无法绕过：hook 在 AI 的工具调用路径上，物理拦截

你是审查 agent。请只读代码，不要修改任何文件。

---
name: review-readonly
tools:
  - Read
  - Search  
  - Grep
  - ListFiles
  # 注意：没有 Edit、Write、Bash、NotebookEdit
---

# 来源: ADR-038 D11
# 审查 agent must use schema-level tool isolation (frontmatter `tools:` whitelist),
# not prompt-level constraint. OpenDev arXiv 2603.05344 showed:
# prompt约束 ~70% adherence vs schema-level 100%.

# 对于本地 agent（frontmatter 可修改）→ 直接在 tools 白名单里排除
# 对于插件 agent（frontmatter 不可修改）→ 在 spawn 边界用 hook 强制检查

Prompt 级：你的手机上有微信，但老板说"上班别刷微信"
           → 你可能忍住，也可能偷偷刷

Schema 级：你的手机上根本没装微信
           → 想刷也刷不了

LOCAL_REVIEW_EXEMPT = ("review-readonly",)
# 本地 agent 的 frontmatter 已经强制了 → 免检放行

# 当 AI 尝试 spawn 一个审查 subagent 时
# hook 检查 prompt 中是否包含只读指令
REQUIRED_DIRECTIVES = (
    "MUST NOT call Edit",
    "MUST NOT use Edit", 
    "read-only reviewer",
    "read-only mode",
    "schema-level read-only",
    "ADR-038 D11",
)

# 如果 prompt 里没有这些指令 → 阻止 spawn（exit 2）
# 如果 prompt 里有 → 放行，但记录一个标记让下游 hook 知道

{
  "tool_name": "Task",
  "tool_input": {
    "subagent_type": "review-readonly",
    "description": "Completion review",
    "prompt": "你是独立的 Completion Reviewer（ADR-044 L4）。你的任务是验证..."
  }
}

.claude/
├── agents/           # 本地自定义 agent
│   ├── review-readonly.md    # 只读审查 agent
│   └── ...
└── plugins/          # 插件提供的 agent
    └── pr-review-toolkit/
        ├── code-reviewer.md
        ├── silent-failure-hunter.md
        └── ...

---
name: review-readonly
model: claude-opus-4-6      # 指定用哪个模型
tools:                       # ← 这就是 Schema 级隔离的关键
  - Read
  - Search
  - Grep
  - ListFiles
  # 没有 Edit / Write / Bash / NotebookEdit
---

你是一个独立的审查 agent...

主 agent 判断"这个任务需要子 agent"
  ↓
调用 Task 工具（subagent_type + prompt）
  ↓
  PreToolUse Task hook 触发
  review-agent-gatekeeper.py
  检查：是不是审查类 agent？
  是 → prompt 里有没有只读指令？
  没有 → exit 2 阻止 spawn
  有 → exit 0 放行
  ↓
Claude Code 按照定义文件 spawn 子 agent
  - 加载 agent 定义文件的 frontmatter（tools 白名单、model 等）
  - 创建独立上下文（不是主 agent 的对话历史）
  - 子 agent 只能用 tools 白名单里的工具
  ↓
子 agent 执行任务，返回结果给主 agent