agent-harness

English

让 AI coding agent 在真实仓库里更可控，而不只是“更会写代码”。

agent-harness 面向 Codex、Claude Code、Gemini CLI 等宿主，提供一层统一的任务控制与交付约束。 当前产品方向已经明确：能力中心逐步前移到 agent / host runtime，CLI 收敛为初始化、诊断和人工 fallback 的兼容层。 当前仓库已经进入维护态：保持可用、可试用、可维护，不再继续扩张为下一代 harness 主产品。

它解决的核心问题是：

• 让 agent 先 intake、再澄清、再执行，而不是一上来就改文件
• 让任务有状态、有门禁、有验证、有交付收口
• 让越界写入、高风险操作、未验证完成这类问题尽量前置暴露
• 让不同宿主下的工作节奏尽量一致，而不是每换一个 agent 就换一套纪律

如果一句话概括它的价值：

它不是帮 agent 写更多代码，而是减少 agent 在真实项目里写错、跑偏、忘验证、乱收口。

它解决什么问题

大部分 AI coding agent 在 demo 里都很强，但进入真实仓库后，常见问题会立刻出现：

• 不知道当前是不是同一个任务
• 需求和范围还没闭合就开始动文件
• 写到了 scope 之外或者高风险目录
• 做完没有证据、没有验证、没有收口
• 口头说“完成”，但没有 report、没有交付边界、没有提交策略

agent-harness 给这些问题补的是一层最小但明确的控制面：

• intake / clarify / observe / verify / report
• state / audit / gate / delivery
• protected_paths / risk_rules / output_policy / delivery_policy

适合谁

这个项目最适合：

• 已经在真实仓库里使用 AI coding agent 的个人开发者或小团队
• 需要在 Codex / Claude Code / Gemini CLI 之间复用一套任务纪律的人
• 维护中大型仓库、低测试覆盖仓库、历史包袱仓库的人
• 更关心“可控、可验证、可交付”而不是单纯“更快”的人

不适合谁

如果你的场景是下面这些，这个项目的价值会弱很多：

• 一次性 PoC、玩具项目、临时脚本
• 只把 agent 当问答助手，不让它真正执行写操作
• 不想接受任何流程约束、验证门禁或状态记录
• 只追求速度，不在乎 scope、验证、交付质量

你会得到什么

从用户视角，agent-harness 交付的不是“新模型能力”，而是 4 个结果：

• 更不容易改错地方
• 更不容易丢掉当前任务上下文
• 更不容易没验证就宣称完成
• 更容易在不同宿主之间复用同一套执行规则

两种接入方式

1. 只接入协议规则

适合：

• 先低成本试用
• 只想引入行为规则，不想先上 CLI
• 先验证团队是否接受这套工作方式

做法：

1. 把 packages/protocol/rules/base.md 或 packages/protocol/rules/full.md 复制到项目的 AGENTS.md、CLAUDE.md 或 GEMINI.md
2. 按需引用：
   • packages/protocol/templates
   • packages/protocol/schemas
   • packages/protocol/adapters

你会获得：

• intake / clarify / observe / verify / report 的规则约束
• 任务模板与 schema
• 各宿主的接入示例

2. 协议规则 + repo-local hooks + 兼容 CLI

适合：

• 希望任务有状态持久化
• 希望执行前有门禁，完成前有验证
• 希望把 agent 工作流真正接进工程交付流程
• 接受 CLI 主要负责初始化、状态诊断和人工兜底，而不是长期主入口

当前 npm 入口：

npx @brawnen/agent-harness-cli init
npx @brawnen/agent-harness-cli init --protocol-only

本地源码入口：

node packages/cli/bin/agent-harness.js init --dry-run
node packages/cli/bin/agent-harness.js init --host codex
node packages/cli/bin/agent-harness.js status

说明：

• 当前 npm 包已发布
• 推荐把 CLI 理解为 bootstrap / status / fallback 入口，而不是产品主形态
• 本地运行要求 Node.js >= 18
• 如果你只想复用规则与模板，也可以直接安装 @brawnen/agent-harness-protocol

快速开始

Protocol only

1. 复制规则文件到目标仓库的 AGENTS.md / CLAUDE.md / GEMINI.md
2. 根据需要复制模板和 schema
3. 在宿主里开始按规则使用

npm CLI

如果你要在一个现有项目里正式使用 agent-harness，现在推荐直接走 npm：

npx @brawnen/agent-harness-cli init --host codex
npx @brawnen/agent-harness-cli status

或先安装到项目里：

npm install -D @brawnen/agent-harness-cli
npx agent-harness init --host codex

Local CLI

如果你想直接复用本机源码仓库里的开发版 CLI，也可以继续用本地路径：

node /abs/path/to/agent-harness/packages/cli/bin/agent-harness.js init --host codex
node /abs/path/to/agent-harness/packages/cli/bin/agent-harness.js status

更完整的跨项目接入说明见：

• How To Use Agent Harness In This Repository And Other Projects
• Agent Harness Runtime 小团队试用清单
• Agent Harness Runtime 稳定面与冻结面

在本仓库里怎么用

当前仓库已经把 agent-harness 用在自己身上，并作为 Agent Harness Runtime 的参考实现维护。

这里最重要的不是“怎么跑 CLI”，而是理解当前仓库的真实运行形态：

• harness.yaml 是项目策略入口
• .harness/hosts/* 与 .harness/rules/* 是宿主脚本和规则的 source of truth
• .codex/.claude/.gemini 只是宿主发现所需的薄壳入口
• packages/cli 现在是 compatibility CLI，主要负责 init / sync / status / verify / report / delivery
• repo-local hooks 现在通过稳定入口 @brawnen/agent-harness-cli/runtime-host 接入 runtime

如果你是在当前仓库里日常使用，最常用的是这几类命令：

codex
node packages/cli/bin/agent-harness.js status
node packages/cli/bin/agent-harness.js sync --check
npm run runtime:p0:check
npm run runtime:p1:check
node packages/cli/bin/agent-harness.js delivery ready

各命令的含义：

• codex：进入当前仓库默认宿主，依赖 repo-local Codex hooks 恢复和续接任务
• status：看当前仓库的宿主接入、运行时目录、交付门禁是否处于正确状态
• sync --check：确认当前仓库仍然收敛到参考实现布局，没有 source/generate 漂移
• runtime:p0:check：跑 task-core + host-hooks + init/status 最小回归
• runtime:p1:check：补跑 sync/status 的兼容边界回归
• delivery ready / delivery commit：在任务已 verify/report 收口后检查并执行本地提交

当前仓库的宿主状态是：

• Codex：默认启用 SessionStart / UserPromptSubmit，工具级 hooks 仍默认关闭以避免前台噪音
• Claude Code：已接入 SessionStart / UserPromptSubmit / PreToolUse / PostToolUse / Stop
• Gemini CLI：已接入 SessionStart / BeforeAgent / BeforeTool / AfterTool / AfterAgent

当前维护要求也很明确：

• 当前仓库应保持 node packages/cli/bin/agent-harness.js sync --check 通过
• 关键调整后优先跑 npm run runtime:p0:check，涉及兼容边界时再跑 npm run runtime:p1:check
• 新增宿主逻辑或规则时，优先改 .harness/hosts/* 和 .harness/rules/*，不要反过来把根目录薄壳当 source of truth

如果你想看更完整的自举与跨项目接入方式，见：

• How To Use Agent Harness In This Repository And Other Projects
• Agent Harness Runtime 稳定面与冻结面

Codex

当前仓库已经内置：

• .codex/config.toml
• .codex/hooks.json
• .harness/hosts/codex/hooks/user_prompt_submit_intake.js
• .harness/hosts/codex/hooks/session_start_restore.js
• .harness/hosts/codex/hooks/pre_tool_use_gate.js
• .harness/hosts/codex/hooks/post_tool_use_record_evidence.js

其中：

• 根目录 .codex/ 只保留宿主发现需要的薄壳配置
• 真实 hook 实现在 .harness/hosts/codex/

在当前仓库内直接运行：

codex

或：

codex exec "继续推进当前任务"

当前 Codex 已接入：

• SessionStart：恢复 active task 摘要
• UserPromptSubmit：自动 intake / continue / clarify / override

当前暂时关闭：

• PreToolUse：前置 gate before-tool
• PostToolUse：自动 evidence 记录

原因：

• 当前 Codex 还不支持禁用 statusMessage，工具级 hook 会带来较明显的视觉噪音
• 等 Codex 支持后，再重新放开这两个自动调用

相关设计规范见：

• CLI 收口与 agent-native runtime 迁移方案
• Codex Hook 可见性规范 v0.1

Claude Code

当前仓库已具备 Claude Code 宿主接入的最小闭环：

• init --host claude-code 会注入 CLAUDE.md 规则块
• init --host claude-code 会创建或合并 .claude/settings.json
• .claude/settings.json 当前接入：
  • SessionStart：恢复 active task 摘要
  • UserPromptSubmit：自动 intake / continue / clarify / override
  • PreToolUse：前置 gate before-tool
  • PostToolUse：工具后写入 repo-local evidence
  • Stop：完成宣告前的最小完成门禁

当前边界：

• Claude Code 现在已经具备 session / prompt / tool / stop 四层 hook 接入
• 但 Stop 仍是“完成宣告门禁”，不是对所有自然语言回复做全面语义审查
• 相比当前仓库内置的 Codex 链路，Claude Code 仍缺少同等级的回归脚本沉淀

Gemini CLI

当前仓库已具备 Gemini CLI 宿主接入的最小闭环：

• init --host gemini-cli 会注入 GEMINI.md 规则块
• init --host gemini-cli 会创建或合并 .gemini/settings.json
• 默认会创建 .harness/ 运行时目录与任务模板
• status 会明确识别 Gemini CLI 的 hook 接入状态
• .gemini/settings.json 当前接入：
  • SessionStart：恢复 active task 摘要
  • BeforeAgent：自动 intake / continue / clarify / override
  • BeforeTool：前置 gate before-tool
  • AfterTool：自动记录 shell evidence
  • AfterAgent：完成宣告前的最小完成门禁

当前边界：

• Gemini CLI 当前接入的是最小 hook 闭环，不是完整宿主抽象能力对齐
• AfterTool 当前只对 shell 工具记录高价值 evidence，不把所有工具结果都写入 state
• 即便有 hooks，GEMINI.md 规则与兼容 CLI 仍是协议约束的最后兜底

Current Status

当前 Runtime closeout 的 P0 / P1 已完成。

这意味着当前状态已经不是“继续扩 CLI”，而是一个已经收尾、进入维护态的 Agent Harness Runtime：

• 当前正式产品定位是 Agent Harness Runtime
• CLI 已明确降级为 compatibility layer
• 当前仓库作为 Runtime 参考实现维护
• repo-local hooks 已成为宿主接入主路径
• repo-local hooks 通过稳定入口 @brawnen/agent-harness-cli/runtime-host 接入 runtime
• 当前仓库只接受必要的 bug fix、兼容修复、文档澄清和发布维护
• 下一代 harness 不再在本仓库继续演化

当前三宿主状态：

• Codex：默认启用 SessionStart / UserPromptSubmit；PreToolUse / PostToolUse 仍默认关闭，原因是工具级 hook 的前台噪音
• Claude Code：已接入 SessionStart / UserPromptSubmit / PreToolUse / PostToolUse / Stop
• Gemini CLI：已接入 SessionStart / BeforeAgent / BeforeTool / AfterTool / AfterAgent

当前稳定面：

• 核心命令：init / sync / status / verify / report / delivery
• 运行时源目录：.harness/hosts/*、.harness/rules/*
• 当前仓库应保持 sync --check 收敛
• 关键调整后至少可跑：
  • npm run runtime:p0:check
  • npm run runtime:p1:check

当前已形成的最小可试用闭环包括：

• task intake / confirm / suspend-active
• state
• verify
• report
• delivery ready / request / commit
• docs scaffold
• 三宿主最小 hook 链路
• status 对新旧宿主接入方式的识别
• sync 对参考实现布局的收敛检查

当前边界：

• CLI 不再继续扩张成更大的产品中心
• push 仍保留为人工动作，不自动化
• 旧版 CLI hook 命令仍兼容识别，但新接入默认生成 repo-local hooks
• runtime-host 目前仍位于 CLI 包内，还没有拆成独立 runtime 包
• 组织级策略中心、审批、洞察和控制台能力属于后续 Control Plane

如果你现在评估这个项目，应把它理解为：

• 一个已经可用的 repo-local agent runtime
• 一个可供小团队试用和参考接入的实现
• 一个进入维护态的第一代产品，而不是持续扩张中的主线平台

Repository Layout

.
├── docs/           # 设计文档、ADR、roadmap、策略说明
├── .harness/       # 运行时 state / audit / reports / tasks
├── packages/
│   ├── protocol/   # rules / schemas / templates / adapters
│   └── cli/        # Node.js CLI
└── package.json    # workspace 根配置

Current Commands

packages/cli 当前已具备这些核心命令：

• init
• status
• task
• state
• verify
• report
• gate
• audit
• delivery
• docs

更细的命令边界见：

• packages/cli/README.zh-CN.md
• packages/protocol/README.zh-CN.md

How To Use It In A Project

最推荐的接入路径是：

1. 在目标项目执行 npx @brawnen/agent-harness-cli init --host codex
2. 让 CLI 生成：
   • harness.yaml
   • .harness/
   • 宿主规则 block
   • 宿主支持时的 hooks 配置
3. 日常使用：
   • agent-harness status
   • agent-harness task intake
   • agent-harness verify
   • agent-harness report
   • agent-harness delivery commit

如果你只想要协议规则，不想引入运行时目录：

1. 安装或复制 @brawnen/agent-harness-protocol
2. 把 rules/base.md 或 rules/full.md 写入 AGENTS.md / CLAUDE.md / GEMINI.md
3. 按需复用 templates/ 与 schemas/

What Is Still Missing Before Broader Open Source Adoption

当前项目已经具备个人与团队试用条件，欢迎更多开发者在真实项目中尝试接入并反馈。

主要还差：

• README / Quick Start 的进一步收口
• 更多宿主支持
  • Antigravity
• Claude Code 与 Codex 之间更高等级的能力对齐
• Gemini CLI 与 Claude Code / Codex 之间更高等级的能力对齐
• 更完整的 CI / release 流程
• 更丰富的宿主 E2E 与误判样本回归

Documentation

• Agent Harness Design v0.3
• Open Source Architecture ADR
• Codex Auto Intake Design
• Codex Hooks Workflow
• Codex v0.3 Roadmap
• CHANGELOG Maintenance Policy
• Workflow Policy Design v0.1
• Task Core Misclassification Fixture Workflow
• How To Use Agent Harness In This Repository And Other Projects
• CLI README（中文）
• Protocol README（中文）
• CLI README（English）
• Protocol README（English）

Historical drafts and early specs are archived under docs/archive/.