AI 编码 Agent 的 Harness 对比与选型

一、为什么”Harness”值得单独做一次对比

当模型本身趋同后，决定一个 AI 编码工具在真实项目中”能不能用”的，往往不再是模型能力，而是包裹在模型外面的那一层系统——通常被称为 Harness。它至少承担六件事：上下文装载与裁剪、工具（读写文件、执行命令、检索）的注册与调度、权限判定、长任务的流程编排、跨会话的记忆维护，以及结果的评测与回归。

Harness 的价值恰恰在于它可被显式设计，因此也存在多条互相竞争的实现路径。这些路径并非”谁对谁错”，而是不同的取舍：有的把安全性与摩擦度作为主轴，有的把上下文吞吐与复用性作为主轴。本文选择其中最常被争论、也最容易踩坑的两个层面做对比。

二、本文的对比对象

本文不比较任何具体产品，而是比较四类”实现路径”，它们分别位于 Harness 的不同层：

• 对象一（权限层）：默认开放模式 vs 声明式受控模式（allow / ask / deny 三段式 + 沙箱）
• 对象二（能力组织层）：单一主 Agent 单体模式 vs “主 Agent + 子 Agent + Skills”分层组合模式
• 对象三（规则载体层）：全局配置优先 vs 项目内配置作为单一事实来源
• 对象四（记忆层）：无持久记忆（每会话重建） vs 文件化 / 外部化记忆

对象一与对象二是主对比线；对象三、对象四是两条支撑线，因为它们直接决定前两者的落地成本。

三、相同点：两条路径共享的底层逻辑

• 都建立在”模型 + 工具调用循环”之上：读取、修改、执行、观察结果、再决策，只是编排的复杂度不同。
• 都受同一个硬约束——上下文窗口预算。任何 Harness 都是在有限窗口内做信息取舍，区别只是把预算花在”主对话”还是”子流程”。
• 都需要人类在环。无论权限多严或能力多强，涉及破坏性操作、生产变更、密钥读取时，人工确认是不可省的环节。
• 都必须配评测。没有任务集与基线，任何”改进”都只是主观感受。
• 都不改变模型的概率性本质。Harness 能约束行为边界，但不能保证一次做对，因此都依赖测试与类型检查这类确定性校验兜底。

四、核心差异分析

4.1 安全边界：从”能力上限”到”最小权限”

关键差异不在”是否危险”，而在危险被发现的时机。默认开放模式把风险前移到人的经验判断；声明式受控模式把风险前移到配置声明，再由工具在执行前拦截。

需要特别注意的是一个容易被忽略的事实：默认情况下，编码 Agent 的可访问范围通常不等于”当前项目目录”。若不做限制，它可能读取家目录下的凭证文件、本地密钥、其他仓库甚至挂载的共享盘。对编码 Agent 来说，最高频的安全事件往往不是恶意攻击，而是凭证被读入上下文后被回显、被写入日志、或被随代码提交。

受控模式通常通过三类规则收敛范围：

• 路径级：可读写的工作根目录白名单，敏感文件模式（凭证、私钥、环境变量文件）显式拒绝读取。
• 命令级：按命令族而非单条命令授权，破坏性操作（强制推送、删除、部署、格式化全仓）进入强制确认。
• 网络级：默认拒绝出网，仅放行依赖源与必要接口域名。

代价是摩擦。过严的 deny 列表会让 Agent 频繁中断，反而促使人把权限整体放宽——这是实践中最常见的”安全配置退化”。因此受控模式的真正难点是分层：把低风险高频操作放进 allow，把不可判定后果的操作放进 ask，deny 只保留绝对禁区。

4.2 上下文经济学：共享上下文与隔离上下文的取舍

单体模式下，所有子任务共用一份对话历史。优点是信息无损、无需复述；缺点是随着任务推进，历史线性膨胀，无关内容持续占用窗口，长任务的后期决策质量容易被稀释。

子 Agent 模式改变了信息的流动方式：主 Agent 派发任务，子 Agent 在独立上下文中完成探索（例如”在两百个文件里找到所有调用点”），只把结构化结论回传。收益是把高熵的中间过程挡在主上下文之外；代价是信息衰减——子 Agent 看到的细节未必被摘要保留，而主 Agent 无法追问它已经关闭的上下文。

Skills 则是另一种裁剪：把流程性知识从”每轮常驻提示”变成”按需加载的文档单元”。它的经济性来自描述字段的精准度：描述写得模糊，就会在该触发时未触发、或在不该触发时挤占上下文。

一个实践判据：任务之间共享状态多、需要反复追问细节，倾向单体；任务之间耦合弱、以检索或验证为主、结果可结构化，倾向子 Agent。

4.3 能力复用与版本管理

Skills 的本质是把提示工程、脚本与参考资料打包成可版本化的资产。相比”每次在对话里重写一遍要求”，它的优势体现在三点：可评审（进代码仓库、走 code review）、可复用（跨项目共享同一套发布检查流程）、可测试（给定输入，验证产出格式与校验点是否被遵守）。

与之相关的是两类内置的流程型能力，抽象后可归纳为：循环执行型（周期性拉取状态并推进）、目标驱动型（以验收条件为终止判据反复迭代）、批量处理型（对同类条目并发处理并汇总）。它们与 Skills 处在不同抽象层：前者是运行时提供的通用原语，后者是项目自定义的领域流程。混淆这两者，会导致把领域规则硬塞进循环参数里，难以维护。

4.4 扩展性、故障隔离与并发

子 Agent 天然带来三个工程属性：失败隔离（探索任务跑偏只污染局部上下文）、并行能力（多个只读检索任务可并发，缩短长任务墙钟时间）、权限下移（子 Agent 继承并收窄父级权限，只读探索子 Agent 无需写权限）。

反面的风险同样明确：子 Agent 的失败更静默。它可能返回一份”看起来完整、实则缺项”的摘要，而主 Agent 无从核实。缓解手段是要求结构化输出（明确列出检查项与未找到项），并在主流程里保留一次确定性校验。

4.5 可观测性与成本归因

单体模式下，成本归因简单：一个会话、一份历史、一次计费。子 Agent 与 Skills 会让归因变难：一次用户请求可能触发多个子会话与多份中间上下文，总消耗显著放大，且日志分散在不同层级。

因此分层模式落地时必须补三件事：统一的请求级追踪标识（把父子调用串起来）、子流程的 token 与耗时统计、以及子 Agent 输出的事后抽查。企业场景还应把审计留痕、身份认证与操作日志交给通用云上能力承载（如日志服务、监控告警、对象存储归档、容器平台运行、身份认证与权限管理），避免把合规责任留在个人终端上。在百度智能云上落地时，这类通用能力可作为标准化的承载底座，团队只需关注 Harness 自身的策略定义与评测体系。

4.6 接入与运维成本

• 配置复杂度：受控模式前期投入高（梳理路径与命令清单），单体模式前期近乎零成本。
• 迁移成本：单体到分层属于增量改造，Skills 与子 Agent 都是”新增目录/新增文件”，不破坏既有对话习惯；反过来，从分层退回单体则会丢失资产。
• 长期维护：Skills 会腐化——项目结构变化后，过时描述比没有描述更糟。子 Agent 数量增长后，路由歧义（该派给谁）成为主要问题。
• 版本升级：模型或 Harness 升级可能改变提示遵循行为，导致原本稳定的 Skills 突然失效，必须靠回归评测发现。

五、关键差异对比表

维度	默认开放模式 + 单体 Agent	声明式受控模式 + 子 Agent / Skills
安全边界	依赖使用者经验，风险后知后觉	执行前拦截，风险前移到配置
上下文利用	线性膨胀，长任务后期易被稀释	隔离子上下文，主链路保持精简
前期投入	极低	中高（权限清单、流程资产编写）
长期维护	低，但能力不可沉淀	高，需持续评审与回归
失败可见性	集中在主对话，问题易观察	子流程失败更静默，需抽查
并发能力	基本串行	只读任务可并发
成本可归因	简单	需父子追踪与分层统计
适配对象	个人、一次性探索、受控环境	团队、长周期项目、有合规要求
主要风险	误读凭证、误改文件、越权执行	配置过严导致中断、路由歧义、资产腐化

六、典型场景选择

• 个人一次性脚本或纯只读探索：开放权限加单体模式往往够用，强行加沙箱的收益低于摩擦成本。
• 单仓库中等规模重构：单体为主，把重复出现的流程抽成两三个 Skills。
• 长期演进的多仓库或平台级项目：分层模式收益明显，因为上下文隔离与流程资产化能对抗复杂度增长。
• 有审计与合规要求的生产相关变更：受控模式近乎必需，且变更应进入分支与流水线，由确定性校验把关。
• 批量同类任务（依赖升级、日志与接口迁移）：批量处理型流程 + 只读子 Agent 检索，配合可回滚的提交粒度。
• 需要周期性推进的长任务（定时巡检、待办跟进）：循环执行型能力配合明确的终止条件与失败上限，避免无限循环消耗。

七、选型建议（条件化）

1. 先安全，后效率。任何模式的起点都应是”默认最小权限”，再按需逐步放行，而不是先全开再收。
2. 从 ask 列表起步。不确定后果的操作放进确认区，观察一两周后按真实分布收敛到 allow，比一次性设计完整策略更可靠。
3. Skills 的抽取以”重复三次以上且有明确验收标准”为门槛，过早抽象会变成维护负担。
4. 子 Agent 优先用于只读且结果可结构化的任务；写操作与跨模块强耦合改动尽量留在主上下文。
5. 记忆机制先人工维护。让 Agent 自主写入长期记忆，需要明确更新策略与冲突处理，否则记忆会迅速退化为噪声。
6. 在团队协同时，把项目内配置作为单一事实来源，全局配置只放个人偏好，避免两层配置互相覆盖导致行为不可复现。

八、示意性配置与落地注意事项

权限与沙箱（示意，字段名仅表达语义）：

agent:
  working_root: "./"
permissions:
  allow:
    - read:  ["src/**", "tests/**", "docs/**"]
    - write: ["src/**", "tests/**"]
    - exec:  ["package-manager install", "test-runner run"]
  ask:
    - read:  ["./**"]              # 工作目录之外需人工确认
    - exec:  ["git push", "release", "deploy"]
  deny:
    - read:  [".env*", "**/*secret*", "**/id_rsa", "~/.config/**"]
    - write: ["**/.git/**", "dist/**", "**/node_modules/**"]
sandbox:
  network: deny-by-default
  allowed_domains: []              # 按需放行依赖源
  tmp_dir: ".agent-tmp"
memory:
  file: ".agent/MEMORY.md"
  update_policy: confirm-then-append

子 Agent（示意）：

---
name: repo-reviewer
description: 只读检索仓库结构与历史变更，返回结构化摘要
tools: [read, search, list]
permission: read-only
max_turns: 20
output_format: markdown-summary
---
职责：定位相关文件、说明调用关系、指出未找到的项。
约束：不修改任何文件；结论必须附文件路径与行号；找不到时明确写"未找到"。

Skills 目录（示意）：

.agent/skills/
  release-check/
    SKILL.md          # 名称、描述、触发条件、步骤、验收标准
    scripts/verify.sh
    references/checklist.md

必须提前评估的落地风险：

• 配置优先级：项目级配置与全局配置的覆盖关系、路径相对基准、变量展开规则不一致，会导致”在我机器上能跑”。
• 沙箱与工具链冲突：容器化或受限文件系统下，构建工具需要的临时目录、缓存路径、网络访问可能被误拦，表现为难以归因的构建失败。
• 凭证边界：即使禁止读取敏感文件，命令输出仍可能回显凭证；应同时约束可执行命令范围并做输出脱敏。
• 提示继承丢失：子 Agent 常不继承主对话约定（代码风格、禁止事项），需在子 Agent 定义中显式复述关键约束。
• 幂等与回滚：批量与循环型流程必须设计”部分失败”语义与提交粒度，否则返工成本高于收益。

九、如何评测 Harness 的改进是否真的有效

建议建立一套小规模、可重复的回归任务集（覆盖新增功能、修缺陷、读代码问答、跨文件重构四类），并固定记录六项指标：任务完成率、人工干预次数、平均交互轮次、单任务 token 与成本、危险操作拦截率、以及回归失败率。

判断标准不是绝对数值，而是相对基线。特别注意两类”看起来更好”的假象：一是子 Agent 让主对话变干净但总消耗翻倍；二是 Skills 提升了格式一致性，却降低了根因分析质量。只有把成本与安全指标一并纳入，Harness 的演进才不会退化为反复调提示词。

十、总结

Harness 的两条主流路径，本质上是”把复杂性放在配置里”与”把复杂性放在对话里”的选择。受控权限用前期配置成本换取可审计的安全下界；子 Agent 与 Skills 用资产化与隔离化换取长任务的稳定性，代价是归因难度与持续维护。二者不冲突，也不必然同时启用：安全与分层可以按项目生命周期渐进引入，从全局最小权限起步，在真实任务分布上收敛策略，再沉淀可复用的流程资产，最后用回归评测把改进变成可验证的工程实践，而不是难以复述的个人经验。