SuperAPI AI 工具集

harness

智能体与模型

查看项目

更新于 10-30 16:17

技能介绍

用途

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/ 复制并适配,不得保留占位符。
  • 将文件作为一次变更提交。

会话开始:

  1. 用 pwd 确认仓库根目录。
  2. 阅读仓库自身规则:CLAUDE.md、AGENTS.md、.agents/instructions/*.instructions.md(SessionStart 钩子会列出存在哪些)。这些规则对提交格式、PR 基分支/标题、范围限制与工具链保持权威,harness 只在其周围增加循环,绝不覆盖它们。
  3. 读取 .agents/progress.md,再读取 .agents/features.json。
  4. 运行 git log --oneline -5。SessionStart 钩子已打印状态与分支的开发平台 CI 状态。
  5. 若分支上 CI 为红,这就是基线:先修复,不在坏的起点上开始新工作。
  6. 选择优先级最高的未完成功能,设为 in_progress,一次只做一个。

工作过程:

  • 遵守仓库规则(最小变更、提交/PR 格式、CI 命名)。若与 harness 冲突,仓库规则优先,并将冲突记录到进度日志。
  • 始终停留在所选功能范围内;受阻时最多允许一个范围很窄的支撑性修复。
  • 标记 passing 需要实际运行该功能的验证步骤并记录证据(命令 + 结果,而不是“看起来没问题”)。
  • 绝不通过改写、删除或削弱功能或测试来使其通过;绝不在功能进行中放宽验证。
  • 宣称完成时,运行 harness-evaluator 智能体:以全新上下文尝试反驳该声明。

会话结束:

  • 更新 .agents/progress.md:已验证状态、执行了什么、证据、已知风险、下一步最佳动作。
  • 更新 .agents/features.json 的状态与证据。
  • 走查 templates/clean-state-checklist.md。
  • 在仓库可安全恢复后提交,遵循仓库规则中的提交与 PR 约定。分支 CI 必须为绿,或在进度日志中说明;下个会话必须无需手工修复即可开始。

适用场景

适合需要跨多个会话持续推进、要求状态可追溯、验证有证据的智能体开发工作流,尤其是由 devcontainer 驱动的仓库。

限制与边界

  • 不得编造功能、证据或验证结果;未运行不得标记 passing;不得通过编辑列表隐藏未完成工作。
  • 依赖安装不在本工具内完成;具体依赖项内容暂未提供。
  • 收费、价格、平台支持范围等细节暂未提供。