架构概览

核心原则

Harness-First 工程 — Harness 不是事后考虑，而是基础。

在快速演进的人工智能辅助软件工程领域，模型所知道的东西与系统所保证的东西之间的区别，已成为定义架构问题的关键。本项目秉持一个根本原则：模型提供智能，Harness 提供可靠性。

这不仅仅是劳动分工——它是一种架构约束，从权限系统保护危险操作到上下文管理最大化有限上下文窗口的利用率，每个设计决策都遵循这一原则。

五大架构优势

a. Harness-First 工程

当构建一个与用户具有相同权限的人工智能代理系统时，可靠性不能层层叠加——它必须从第一行代码开始就嵌入其中。

权限控制、超时保护、输出截断和会话持久化不是功能——它们是使人工智能代理能够投入生产的安全网。模型可能会产生幻觉、误解指令或选择错误的工具。但 Harness 绝不能在未授权的情况下允许破坏性操作，绝不能无限期挂起，绝不能丢失用户的工作。

属性	保证
权限控制	无用户同意或策略批准，破坏性操作不执行
超时保护	行为不当的工具（失控的 grep、无限循环）无法挂起会话
输出截断	单个工具响应无法消耗整个上下文窗口
会话持久化	代理中断后恢复，不丢失对话历史

b. 上下文窗口作为稀缺资源

现代大语言模型提供慷慨的上下文窗口，但"慷慨"是一个相对术语，当需要代表整个代码库、多个文件和持续的对话历史时。本架构将上下文视为需要管理的稀缺资源，而不是可以随意挥霍的奢侈品。

延迟工具加载：工具注册在中央注册表中；只有工具定义（名称、描述、输入模式）被发送给模型——而非其实现
250 字符工具描述：强制在与模型沟通功能时保持严谨
三级压缩：消息在达到阈值之前保持完整，然后被压缩成在保留关键信息的同时减少 token 计数的摘要

c. 分层权限防御

信任不是二元的，授权也不是。本系统实施了反映现实安全思维的三级权限模型：

级别	功能	使用场景
只读	文件读取、glob 搜索、grep 搜索	安全探索代码库
工作区写入	文件创建、修改、编辑	受控的开发工作
危险完全访问	shell 执行、删除、网络操作	需要明确批准的全自动化

权限系统不仅仅检查级别——它根据 glob 规则匹配 评估每个操作，以确定是否允许特定路径或操作。策略可能允许编辑 /src/ 中的文件，同时阻止修改 /config/ 或 /tests/。

会话记忆意味着系统记住会话内的批准决策，防止对同一操作重复提示。存在一种人工在环（Human-in-the-Loop）批准模式，用于需要在执行前明确确认的操作——对于可能危及系统的破坏性操作或 shell 命令至关重要。

d. 本地优先执行

本系统作为纯 Go 二进制文件运行，零运行时依赖。无需配置 Python 环境，无需维护 Node.js 运行时，无需管理虚拟机。代理在主机完整环境中执行，可以访问所有系统资源、环境变量和已安装的工具。

这种本地优先方法消除了虚拟化开销并提供最大性能。代理可以调用开发者日常使用的相同构建工具、linter 和测试运行器。模型的意图与系统的实际能力之间没有抽象层。

e. MCP 作为通用桥

模型上下文协议（MCP）不是一个封闭的生态系统——它是一个互操作性中心。本系统将 MCP 视为外部工具生态系统的桥梁，使代理能够发现和利用其内置功能之外的能力。

可以配置 MCP 服务器来提供专门的工具：数据库访问、API 集成、云服务管理或领域特定的分析器。代理以与内置工具相同的方式对待 MCP 工具——具有完全相同的权限执行保证。

代理循环：状态机

┌──────────┐  tool_use  ┌──────────────┐
│ REQUEST  │───────────▶│ TOOL_EXEC    │
│          │◀───────────│              │
└────┬─────┘  result    └──────┬───────┘
     │                         │
end_turn│                 error│
     ▼                         ▼
┌──────────┐           ┌──────────────┐
│ TERMINATE│           │ CONTINUE     │
└──────────┘           └──────────────┘

状态	转换	条件
REQUEST	→ TOOL_EXEC	模型调用工具 (tool_use)
REQUEST	→ TERMINATE	任务完成 (end_turn)
TOOL_EXEC	→ CONTINUE	工具成功，继续循环
TOOL_EXEC	→ CONTINUE	工具失败但可恢复
TOOL_EXEC	→ TERMINATE	不可恢复的失败

设计决策

决策	理由	权衡
Go 实现	静态链接、单二进制部署、可预测的内存使用	不如解释型语言灵活
三级权限	二进制允许/拒绝对于不同的开发工作流程是不够的	配置更复杂，但支持实际使用
Glob 规则匹配	允许对哪些文件可以被修改进行细粒度控制	需要用户理解 glob 模式
250 字符工具描述	强制能力沟通的纪律；防止上下文膨胀	可能遗漏有用的工具细节
MAX_TURNS = 50	防止无限循环导致的资源耗尽	复杂任务可能需要更多迭代
三级消息压缩	在管理 token 限制的同时保留语义内容	压缩是有损的；某些上下文可能丢失
MCP 作为外部适配器	协议无关的工具发现；生态系统集成	MCP 服务器添加外部依赖

目标读者

本文档面向：

人工智能代理架构研究者 — 研究 Harness 设计如何影响代理能力
评估生产系统 Harness-First 工程模式的高级工程师
寻求生产级人工智能工具参考实现的技术负责人

贯穿始终的重点是 为什么 而不是 是什么 — 代码揭示实现细节，但这些页面解释的是其背后的 reasoning。

架构概览 ​

核心原则 ​

五大架构优势 ​

a. Harness-First 工程 ​

b. 上下文窗口作为稀缺资源 ​

c. 分层权限防御 ​

d. 本地优先执行 ​

e. MCP 作为通用桥 ​

代理循环：状态机 ​

设计决策 ​

目标读者 ​

相关文档 ​