设计理念
核心原则
模型提供智能，Harness 提供可靠性 — 这不是一句营销口号。它是塑造本系统每一行代码的架构约束。
这个原则源于一个基本的观察：大型语言模型在推理、规划和生成适当响应方面表现出色，但它们缺乏安全、可靠系统运行所需的属性。它们没有超时概念，不理解资源约束，没有内置的安全保证，也没有跨会话的记忆。与此同时，传统软件系统在这些可靠性属性方面表现出色，但无法推理用户意图或选择适当的行动。
本系统位于这个边界上。模型处理认知工作 — 理解用户想要什么，决定调用哪些工具，解释结果，规划下一步。Harness 处理可靠性工作 — 确保操作在边界内执行，防止资源耗尽，维护会话状态，并强制执行安全边界。
这种分离不仅仅是方便的。它是必要的，因为模型可能会出错，但 Harness 绝不能失败。
飞行员与自动驾驶仪类比
想象一架飞机：飞行员提供判断力、决策能力和态势感知 — 读取仪表、评估天气条件、决定行动方案。自动驾驶仪提供可靠性 — 保持高度、遵循飞行计划、防止飞机失速或超速、在安全参数范围内处理气流。
飞行员或自动驾驶仪单独都无法安全运行飞机。没有自动驾驶仪的飞行员会很快疲劳并犯错误。没有飞行员的自动驾驶仪无法处理意外情况、评估飞行路径的合理性或做出判断。
这正是模型与 Harness 之间的关系：
| 方面 | 飞行员（模型） | 自动驾驶仪（Harness） |
|---|---|---|
| 角色 | 决策、判断 | 有界执行、安全保证 |
| 优势 | 灵活性、上下文理解 | 可预测性、可靠性 |
| 局限性 | 可能做出错误决策 | 无法推理意图 |
| 失败模式 | 错误的工具选择、幻觉 | 永不应失败 |
| 信任模型 | 概率性 | 确定性 |
模型（飞行员）决定做什么 — 要编辑哪些文件、要运行哪些命令、要尝试哪种方法。Harness（自动驾驶仪）确保执行保持在安全边界内 — 工具在超时内完成、输出适合上下文、操作符合策略允许。
我们选择这个而非其他方案的原因：一个模型直接控制执行而没有 Harness 的单体系统相当于没有自动驾驶仪的飞机 — 在理想条件下可能工作，但会在边缘情况下失败。一个 Harness 做所有决策的系统相当于从不服从飞行员的自动驾驶仪 — 无法应对新颖情况。
模型提供什么：智能
当说模型提供"智能"时，我们指的是本系统委托给 LLM 的特定能力集：
意图理解
模型解释自然语言输入并提取用户实际想要完成的任务。"让这个函数更快"不是精确的指令 — 模型必须在上下文中理解"更快"的含义，引用的是哪个函数，以及当前存在什么性能特征。这是一个无法用基于规则的解析替换的智能任务。
工具选择
给定可用的工具集（Read、Write、Edit、Glob、Grep、Bash，加上任何 MCP 工具），模型决定调用哪些工具以及按什么顺序。这需要理解工具能力，将它们与当前任务匹配，并制定计划。Harness 提供可用工具列表，但由模型决定使用哪些。
结果解释
工具输出不是不言自明的。grep 搜索返回文本行；模型必须解释这些结果是表示成功、失败还是部分进度。文件写入操作返回简单的确认；模型必须决定是否验证写入，继续下一步，或向用户报告完成。
下一步规划
代理循环是迭代的。在每个工具执行后，模型必须决定：继续下一步，尝试不同的方法，要求澄清，或宣布任务完成。这是一个需要理解整体目标和当前进度的规划和推理任务。
这四种能力 — 意图理解、工具选择、结果解释和下一步规划 — 构成了我们在这个架构上下文中所说的"智能"。它们是 LLM 执行的认知工作，而且无法用确定性代码实现。
Harness 提供什么：可靠性
可靠性不是单一属性，而是传统软件系统长期以来提供的一系列保证：
权限控制
模型可能请求任何操作，但由 Harness 决定哪些操作实际执行。权限控制不是建议性的 — 它是一个硬门，阻止用户未批准的操作执行。模型可能要求删除项目中的所有文件，但 Harness 会拦截此请求，并且只有在用户的权限策略允许的情况下才继续。
这是最关键的可靠性属性，因为模型以用户的完整权限运行。没有权限控制，人工智能代理将与恶意脚本无法区分。
超时保护
模型没有时间概念。它可能在百万个文件上调用 grep 搜索并无限期等待结果。它可能执行一个永远不会终止的 shell 命令。Harness 强制执行超时边界 — 如果工具在配置的时间内未完成，它会被终止并返回错误给模型。
没有超时保护，单个行为不当的工具可以无限期地挂起整个会话。
输出截断
工具输出可能任意大。读取二进制文件，运行产生兆字节输出的命令，或在大型代码库上 grep 搜索可能产生大于上下文窗口的结果。Harness 截断工具输出以防止它们消耗整个可用上下文。
这不仅仅是性能优化 — 它是正确性保证。没有截断，系统可能无法向模型提供完成任务所需的信息。
会话持久化
模型在 API 调用之间是无状态的。Harness 在回合之间维护对话历史，并可以将会话持久化到磁盘以便后续恢复。这允许用户断开连接和重新连接而不会丢失长时间运行的任务的进度。
错误恢复
工具可能由于与模型推理无关的原因失败 — 网络超时、文件权限问题、无效的工具输入。Harness 捕获这些错误，适当格式化它们，并以使模型能够恢复的方式呈现它们。模型可以决定重试、尝试不同的方法，或向用户报告错误。
为什么这种分离很重要
智能和可靠性的分离不是实现细节 — 它源于当前人工智能系统性质的基本架构要求。
模型可能会出错
LLM 是概率系统。它们可能产生幻觉、误解指令、选择次优工具并犯错误。模型可能：
- 为任务调用错误的工具
- 误解工具的输出
- 进入无限循环的工具调用
- 误解用户的意图
这些失败是预期的，应该优雅地处理。Harness 无法防止模型错误，但可以控制其影响。
Harness 绝不能失败
与模型不同，Harness 是确定性软件。它应该永远不要：
- 在权限检查期间崩溃
- 无法执行超时
- 由于会话故障丢失用户数据
- 允许未经授权的操作
- 产生不可预测的行为
这些与任何生产系统必须提供的可靠性保证相同。Harness 的工作是无论模型做什么都维护这些保证。
它们之间的接口
模型和 Harness 通过定义良好的接口通信。模型接收工具定义（名称、描述、输入模式）并决定调用哪些工具。Harness 执行工具并返回结构化结果（文本输出、错误、成功/失败状态）。
这个接口故意是窄的。模型无法绕过 Harness，无法检查 Harness 内部，也无法修改 Harness 行为。Harness 是一个硬边界，而不是一个软层。
与其他方法的对比
| 范式 | 模型角色 | Harness 角色 | 自动化水平 | 安全模型 |
|---|---|---|---|---|
| 聊天机器人 | 仅生成文本响应 | 无（用户手动执行） | 最低 | 最高（用户控制所有操作） |
| 脚本运行器 | 生成脚本参数 | 执行预定义脚本 | 中等 | 用户监督 |
| IDE 助手 | 完全访问开发环境 | 最小（用户监督） | 最高 | 用户监督 |
| claude-code-Go | 控制执行流程、选择工具 | 强制安全边界、资源限制 | 高 | 自动权限执行 + 可选人工在环 |
我们选择这个而非聊天机器人方案的原因：纯聊天机器人要求用户手动执行每个操作。这提供最高安全性但零自动化。本系统需要直接执行操作才能作为编码助手有用。
我们选择这个而非脚本运行器方案的原因：脚本运行器将模型限制为为预定义脚本选择参数。这限制了模型的灵活性 — 它无法适应新颖情况或以意外方式组合工具。模型必须控制执行流程。
我们选择这个而非完整 IDE 方案的原因：在完整 IDE 中，人工智能完全访问开发环境，安全性通过用户监督来管理。这给用户带来太多负担，无法扩展到自动化工作流程。Harness 提供深度防御，而不需要持续关注。
我们选择这个而非基础框架的原因：许多"代理框架"只提供代理循环，将安全、持久化和权限留给用户。这适用于实验但不适用于生产使用。本系统是一个包含所有可靠性功能的代理产品。
设计决策
| 决策 | 我们为什么选择这个 | 权衡 |
|---|---|---|
| 三级权限模型 | 二进制允许/拒绝对于不同的开发工作流程是不够的。开发者可能希望在工作区中自动编辑文件，同时对 shell 命令要求确认。 | 配置更复杂，但支持实际使用 |
| 路径的 glob 规则匹配 | 允许对哪些文件可以被修改进行细粒度控制。策略可以允许 /src/ 同时阻止 /config/。 | 需要用户理解 glob 模式 |
| 250 字符工具描述 | 强制能力沟通的纪律；防止上下文膨胀。模型收到简洁、可操作的工具定义。 | 可能遗漏有用的工具细节 |
| MAX_TURNS = 50 | 防止无限循环导致的资源耗尽。模型没有内在的资源约束理解。 | 复杂任务可能需要更多迭代 |
| 三级消息压缩 | 在管理 token 限制的同时保留语义内容。完整消息直到阈值，然后是摘要。 | 压缩是有损的；某些上下文可能丢失 |
| 纯 Go 实现 | 无运行时依赖；单二进制部署；可预测的内存使用和低延迟。与本地优先理念一致。 | 不如解释型语言灵活 |
| MCP 作为外部适配器 | 协议无关的工具发现；生态系统集成。实现在不修改核心代码的情况下扩展能力。 | MCP 服务器添加外部依赖 |
实践中的理念
在构建功能时，智能/可靠性分离用作决策框架：
- 如果一个能力需要理解用户意图 → 模型责任
- 如果一个能力需要在选项之间选择 → 模型责任
- 如果一个能力需要保证安全 → Harness 责任
- 如果一个能力需要资源管理 → Harness 责任
- 如果一个能力需要跨会话持久化 → Harness 责任
这个框架并不完美 — 某些能力跨越边界。但它为架构决策提供了一致的启发式方法。
相关文档
- 架构概览 — 系统组件和数据流
- Agent Loop — 状态机机制和执行周期
- 工具系统 — 三级模型和策略配置