使用 Agent-Harness-Kit 扩展 AI 代理工作流

从单提示 AI 助手向多代理系统的转变是当今软件工程中最重要的变革之一。虽然单个代理可以编写函数或解释 bug，但复杂的全仓库更改需要协同工作——一种模拟专业工程团队的分工。然而，搭建这种协作的基础设施——状态管理、权限边界和交接协议——往往是繁琐的手动过程。

于是出现了 agent-harness-kit (ahk)，一个旨在成为 “AI 代理编排的 Vite” 的工具。通过提供标准化的脚手架流程，它让开发者能够快速部署多代理 harness，将一组单独的代理转化为一个连贯的系统。

协作架构

从本质上讲，agent-harness-kit 关注的是 “harness”——一种让代理在定义好的环境中运行的结构支撑。该套件不依赖单一的单体代理，而是基于四种专门角色搭建系统，每个角色都有明确的权限边界：

Lead Orchestrator: 项目经理。它挑选任务并协调其他代理。
Explorer (Read-Only): 研究员。它在任何代码被修改前了解仓库并映射依赖关系。
Builder (Write: src/): 实现者。它仅被限制写入 src/ 和 tests/ 目录。
Reviewer (Gatekeeper): 验证者。它确保没有任务在通过测试前被标记为完成。

这种关注点分离可以防止 “幻觉循环”，即代理尝试修复一个 bug，却引入新的 bug，然后在没有宏观目标视角的情况下去修复新出现的 bug。

关键技术特性

为了超越简单提示，agent-harness-kit 实现了若干基础设施原语：

SQLite 作为唯一可信来源

系统不依赖 LLM 易变的上下文窗口，而是使用 SQLite 数据库来维护状态。这提供了持久的记忆层，存储代理活动、任务状态和协作规则，使系统能够从故障中恢复，并在不同代理回合之间保持一致的历史记录。

Model Context Protocol (MCP) 集成

套件内置 MCP 服务器，使代理能够以标准化方式与外部工具和数据源交互。这使系统与供应商无关，支持 Claude Code、OpenCode 等工具，同时在 MCP 不可用的环境中提供 Markdown 备选方案。

自动化脚手架

部署通过一个简单的 CLI 命令 (npx @cardor/agent-harness-kit init) 完成，该命令生成所需的基础设施：用于角色定义的 AGENTS.md、类型化配置文件、SQLite 数据库，以及用于系统监控的 health.sh 脚本。

关键视角与工程挑战

虽然脚手架方法前景可观，但社区提出了若干技术考量，涉及代理工作流的长期可行性。

“LLM 判官”问题

主要批评之一涉及验证过程。如果 Lead 代理仅读取子代理的输出以判断任务是否完成，Lead 就会成为隐式审阅者。正如社区成员所指出的，这引发了系统是基于 typed state（硬数据）还是 raw output（自然语言）进行推理的问题。要实现真正稳健的系统，后置条件必须通过程序检查，而不能仅依赖 LLM 的批准。

状态转换与错误处理

管理代理之间的 “handoff” 是一个众所周知的痛点。常见的失败模式是 “无尽重试循环”，即代理失败但未报告具体错误，导致调度器无限重试。

"最棘手的部分是被停止却没有出现明显的错误……你必须有办法说明‘发生了某事，但这不是我们想要的’，例如，'blocked_quota' 或 'blocked_no_credentials'。"

有效的编排需要一种纪律，即代理永不写入 “半状态”，并且每次运行都以记录在案的终端状态结束。

沙箱化与隔离

为防止代理在本地环境中导致灾难性故障，强烈建议集成自动 worktree 创建和沙箱化。使用 git worktrees 和 Bubblewrap 等工具可以隔离代理的环境，确保代理的实验不会污染主开发分支。

路线图与未来方向

项目目前正在扩展其集成能力，以超越本地文件系统。计划中的 Jira、Linear 和 GitHub Issues 适配器表明系统正向直接与项目管理软件绑定的方向发展，使代理能够直接从待办列表中获取任务并将更新推送回工单。

通过标准化 “harness”，agent-harness-kit 试图降低多代理系统的入门门槛，使行业更接近于 AI 代理作为可扩展且有纪律的工程团队运作的世界。