在智能体应用开发领域，如何让多个 AI 代理协同工作且避免相互干扰，一直是工程化落地的核心挑战。agent-harness-kit 作为一款基于 MCP（Model Context Protocol）的多智能体脚手架工具，通过 CLI 自动生成完整的基础设施，支持 SQLite 状态持久化、MCP 工具暴露以及细粒度的权限边界控制。其核心设计理念是 provider-agnostic，能够同时兼容 Claude Code 与 OpenCode 等多种模型供应商，为团队提供了统一编排层的同时保留了供应商选择灵活性。
核心架构：四角色协同的代理网络
agent-harness-kit 生成的脚手架定义了四个专业化代理角色，每个角色拥有明确的职责边界与工具访问权限。Lead 代理担任编排核心，负责从任务队列中提取任务并分发给其他代理，同时维护整体工作流状态；Explorer 代理采用只读模式，在任务执行前仅映射与当前任务相关的代码路径，避免将整个代码库上下文塞入提示词从而导致 token 浪费；Builder 代理拥有 src/ 和 tests/ 目录的写入权限，负责实现 Lead 分配的具体功能；Reviewer 代理则扮演质量门禁角色，任何任务必须通过测试并获得 Reviewer 批准后才能标记为完成。
这种四角色设计解决了多智能体协作的三个典型痛点。首先是会话遗忘问题 —— 传统单代理模式下，每次对话都是全新上下文，agent-harness-kit 通过共享的 SQLite 数据库维护持久状态，Lead 始终知道前序任务完成情况与后续待办事项。其次是代理冲突问题 —— 文件级权限边界而非口头约定确保 Builder 不会误改配置、Explorer 不会意外写入代码。最后是验证缺失问题 ——Reviewer 的审批机制将「完成」定义从「代码写完」提升为「代码通过测试且经过评审」。
MCP 协议层设计：跨供应商能力的技术基础
agent-harness-kit 的 provider-agnostic 能力根植于 MCP 协议的标准化接口设计。MCP 作为模型上下文协议，定义了客户端与服务端之间的通信规范，使得智能体与外部工具、资源之间的交互不依赖于特定模型实现。脚手架内置的 MCP Server 在初始化时自动生成，暴露两类核心工具：一类是状态管理工具，包括任务队列读写、历史记录查询与会话上下文恢复；另一类是文件操作工具，按照代理角色授予不同的目录访问权限。
在实际工程落地中，provider-agnostic 架构的关键参数包括模型供应商配置与工具调用超时阈值。脚手架支持通过环境变量指定默认供应商，例如设置 AGENT_PROVIDER=claude-code 或 AGENT_PROVIDER=opencode，框架内部通过统一的适配器层将请求路由至对应供应商。工具调用的超时参数建议设为 30 秒至 60 秒区间，具体数值取决于网络环境与模型响应速度 —— 生产环境中可监控 tool_execution_duration_seconds 指标，当 P99 延迟超过阈值时触发告警。
状态管理：SQLite 持久化与上下文注入
无状态是 AI 编码代理的先天缺陷，agent-harness-kit 通过 SQLite 实现了三种维度的状态记忆。短期记忆存储当前会话内的任务队列与执行上下文，支持任务中断后的续接；情景记忆记录每个任务的执行步骤、产出文件与评审意见，供后续回顾与审计；长期记忆沉淀跨会话的模式，例如某个代码模块的常见问题、Reviewer 代理的评审偏好等。
初始化后，脚手架会在项目根目录生成 agent-harness.db 文件，默认使用 Node 22+ 的 node:sqlite 或 Bun 环境的 bun:sqlite，无需额外部署数据库服务。对于高并发场景，可通过配置将 SQLite 替换为分布式存储，但在大多数团队级使用场景下，单文件 SQLite 的读写性能已足够支撑数十个并发任务。状态持久化的关键参数是 db_connection_pool_size，默认值为 5，生产环境建议根据并发代理数量调高至 10 至 20。
权限边界配置：从声明到强制执行
传统的智能体协作往往依赖 prompt 中的自然语言约束，如「请勿修改配置文件」，这类软约束在复杂场景下极易失效。agent-harness-kit 将权限边界固化为文件系统级别的强制控制：Explorer 代理的工具调用被限制在 read 操作且仅限 **/*.ts、**/*.js 等代码文件；Builder 代理的写入权限被严格限定在 src/ 与 tests/ 子目录；任何超出权限范围的工具调用会在 MCP 协议层被拒绝并记录审计日志。
这种设计使得权限策略从「建议」变为「规则」。团队可根据项目需求自定义权限配置文件，定义新的代理角色及其对应的工具白名单。监控层面建议开启 permission_violation_total 指标统计，当某个代理频繁触发权限拒绝时，可能意味着任务分配不合理或权限配置需要调整。
监控与可观测性：生产落地的必要组件
将多智能体系统投入生产环境意味着必须建立完整的可观测性体系。agent-harness-kit 内置的健康检查脚本支持两种探测模式：基础探测验证 SQLite 连接、MCP Server 响应与磁盘空间；深度探测执行一个完整的「任务创建→分配→执行→评审」闭环，验证各代理之间的协作链路是否通畅。
关键监控指标分为三个层面。代理层面包括 agent_task_queue_size（待处理任务数）、agent_task_duration_seconds（任务执行时长）与 agent_review_approval_rate（评审通过率）。工具层面包括 tool_call_total（工具调用总次数）、tool_call_success_rate（工具调用成功率）与 tool_execution_duration_seconds（工具执行延迟）。系统层面包括 db_query_duration_seconds（数据库查询延迟）与 mcp_server_health_status（MCP 服务健康状态）。告警阈值建议设置如下：任务队列积压超过 50 时触发黄色告警、评审通过率低于 70% 时触发橙色告警、工具调用成功率低于 95% 时触发红色告警。
落地方案：从初始化到持续运营
团队采用 agent-harness-kit 的典型流程包含五个阶段。第一阶段是初始化，在目标代码仓库根目录执行 npx @cardor/agent-harness-kit init，脚手架会在一分钟内生成完整的目录结构与配置文件。第二阶段是角色定制，根据项目需求修改 agents/ 目录下的各代理指令文件，调整工具权限与任务分配策略。第三阶段是集成测试，通过内置健康检查脚本验证 MCP Server 与 SQLite 的连通性。第四阶段是试运行，以小流量任务验证四角色协作链路是否通畅。第五阶段是持续运营，监控关键指标并根据实际运行数据调优超时参数与权限配置。
对于希望进一步扩展的团队，脚手架支持自定义 MCP 工具的注册 —— 只需在 tools/ 目录下添加新的工具定义文件并重启 MCP Server，即可让所有代理访问新增的工具能力。这种插件化设计使得 agent-harness-kit 能够适应从简单代码审查到复杂系统构建等多种场景。
资料来源：agent-harness-kit 项目主页（cardor.dev/project/agent-harness-kit）