用途
harness 属于长期运行智能体的工程化支撑工具。其核心理念是:仓库才是记录系统,聊天不是。必须跨会话保留的状态存放在文件中,新会话通过读取这些文件恢复状态,而不是靠猜测。该方案基于 Learn Harness Engineering。
主要能力
- 初始化持久状态:在仓库中一次性创建(已存在则跳过).agents/progress.md(会话日志与当前已验证状态)和 .agents/features.json(每个用户可见功能,含 id、优先级、状态、验证步骤与证据)。大型会话可选创建 .agents/handoff.md。
- 记录真实功能:features.json 中的功能需依据仓库 README、issues 或代码编写,全部以 not_started 起步;每个功能的真实验证步骤写入该文件。
- 启动钩子:一旦 progress.md 或 features.json 存在,SessionStart 钩子打印状态;Stop 钩子检查交接。
- 依赖与环境基线:依赖由 devcontainer features 安装,而非本工具;基线为仓库开发平台(GitHub、GitLab、Azure DevOps)上的 CI 状态,由钩子打印。
使用方式
初始化(每个仓库一次):
- 从模板 templates/ 复制并适配,不得保留占位符。
- 将文件作为一次变更提交。
会话开始:
- 用 pwd 确认仓库根目录。
- 阅读仓库自身规则:CLAUDE.md、AGENTS.md、.agents/instructions/*.instructions.md(SessionStart 钩子会列出存在哪些)。这些规则对提交格式、PR 基分支/标题、范围限制与工具链保持权威,harness 只在其周围增加循环,绝不覆盖它们。
- 读取 .agents/progress.md,再读取 .agents/features.json。
- 运行 git log --oneline -5。SessionStart 钩子已打印状态与分支的开发平台 CI 状态。
- 若分支上 CI 为红,这就是基线:先修复,不在坏的起点上开始新工作。
- 选择优先级最高的未完成功能,设为 in_progress,一次只做一个。
工作过程:
- 遵守仓库规则(最小变更、提交/PR 格式、CI 命名)。若与 harness 冲突,仓库规则优先,并将冲突记录到进度日志。
- 始终停留在所选功能范围内;受阻时最多允许一个范围很窄的支撑性修复。
- 标记 passing 需要实际运行该功能的验证步骤并记录证据(命令 + 结果,而不是“看起来没问题”)。
- 绝不通过改写、删除或削弱功能或测试来使其通过;绝不在功能进行中放宽验证。
- 宣称完成时,运行 harness-evaluator 智能体:以全新上下文尝试反驳该声明。
会话结束:
- 更新 .agents/progress.md:已验证状态、执行了什么、证据、已知风险、下一步最佳动作。
- 更新 .agents/features.json 的状态与证据。
- 走查 templates/clean-state-checklist.md。
- 在仓库可安全恢复后提交,遵循仓库规则中的提交与 PR 约定。分支 CI 必须为绿,或在进度日志中说明;下个会话必须无需手工修复即可开始。
适用场景
适合需要跨多个会话持续推进、要求状态可追溯、验证有证据的智能体开发工作流,尤其是由 devcontainer 驱动的仓库。
限制与边界
- 不得编造功能、证据或验证结果;未运行不得标记 passing;不得通过编辑列表隐藏未完成工作。
- 依赖安装不在本工具内完成;具体依赖项内容暂未提供。
- 收费、价格、平台支持范围等细节暂未提供。