从泄漏源码看AI智能体Harness工程设计

一、背景：一份源码为何值得逐行精读

近期，业内流传出一份主流智能编程工具的源码。对工程团队而言，这份源码的价值不在于“吃瓜”，而在于研究对象与研究方法高度同构：它本身就是用Harness工程思想打造出来的智能体，反过来又恰好可以用来拆解Harness的设计哲学。本文以其中的核心机制为线索，聊清楚一个问题——一个生产级AI编程智能体，到底是由什么构成的。

二、什么是Harness：从Prompt到工程系统的三级跳

Harness原意是“马具”，即让一匹马从散养状态进入可驾驭、可服役状态所需的一整套装备。映射到AI工程领域，Harness指的是围绕模型建立的一整套规则、框架与运行时：它约束模型行为，为模型提供工具、状态、记忆与安全边界，让模型按照预先制定的逻辑与策略工作，最终完成“模型裸跑”根本无法完成的任务。

理解Harness最清晰的视角，是看智能体开发的三级演化：

1. Prompt阶段：所有智能都写进一段提示词。启动成本低，但上下文一长、任务一复杂，提示词就会失控，且无法与外部世界稳定交互。
2. Skills阶段：把领域知识、操作手册、示例模板从主提示词中剥离，形成可挂载、可组合的“技能包”，模型按需取用。
3. Harness阶段：不再满足于“教模型怎么做”，而是为模型建一套操作系统级的运行环境——工具注册、权限控制、状态管理、上下文压缩、任务调度、失败恢复全部工程化。

一句话概括：Prompt解决“说什么”，Skills解决“会什么”，Harness解决“怎么稳定地把事做成”。

三、全局架构：生产级编程智能体的模块地图

表面上看，这类工具是一个独立的命令行智能体；但透过源码可以发现，它本质上是一个被深度工程化的Harness，内部远不止一个Agent。其核心模块大致可分为七类：

• 查询引擎：处理用户输入、调用大模型接口、执行工具调用的主循环，是整个系统的心脏；
• 工具系统：数十种工具，每个工具都带有独立的权限检查逻辑；
• 命令系统：上百个斜杠命令，构成用户与智能体之间的高频交互入口；
• 协议化外部接入：通过标准化的模型-工具互联协议，把外部服务动态挂载进来；
• 权限系统：逐工具、逐操作的细粒度授权；
• 会话桥接：本地会话与远程会话之间的通信通道；
• 插件与技能系统：面向第三方的扩展机制与自定义命令。

一种典型的工程组织方式如下：

agent-harness/
├── engine/        # 查询引擎：主循环、事件流、状态机
├── tools/         # 工具注册表、子智能体生成器
├── commands/      # 斜杠命令
├── services/      # 外部协议客户端
├── permissions/   # 权限与审计
├── bridge/        # 本地-远程会话桥接
└── plugins/       # 插件与技能

下面按“主循环—状态管理—上下文压缩—多智能体—权限与扩展”的顺序逐一拆解。

四、核心机制一：AsyncGenerator驱动的查询引擎

为什么查询引擎普遍采用异步生成器？因为智能体的执行过程天然是“流式+可中断”的：模型输出是逐token的流，工具执行是耗时的异步操作，用户随时可能打断，界面需要实时渲染中间状态。用同步函数把这些串起来很快会陷入回调地狱；用AsyncGenerator则可以把整个过程表达为一条可被消费的事件流。

示意代码：

async function* query(input: UserInput, state: SessionState) {
  yield { type: "status", phase: "thinking" };
  while (true) {
    const stream = await llm.stream({
      messages: state.messages,
      tools: toolRegistry.listFor(state.permissions),
    });
    for await (const ev of stream) {
      if (ev.type === "tool_call") {
        yield { type: "tool_start", name: ev.name };
        const result = await executor.run(ev, state.permissions);
        state.pushToolResult(result);
        yield { type: "tool_end", name: ev.name };
      } else {
        yield { type: "text_delta", text: ev.delta };
      }
    }
    if (!state.hasPendingToolCalls()) break;   // 模型给出最终回答
    if (state.tokenUsage() > COMPRESS_THRESHOLD) {
      state.messages = await compressor.compress(state.messages);
    }
  }
}

这种设计带来三个直接收益：

1. 天然的背压控制：消费端（UI）处理不过来时，事件流可以暂停；
2. 中断即退出：外部只需停止消费，生成器内部的清理逻辑（finally块）即可优雅收尾；
3. 可测试性：整条链路是纯事件流，单元测试只需断言事件序列。

五、核心机制二：while(true)主循环与状态管理

如果把Harness抽到只剩一个东西，那就是Agentic Loop——一个不断“感知→决策→执行→观察”的while(true)循环。模型在每一轮决定：直接回答，还是调用某个工具；工具结果回填后进入下一轮，直到模型认为任务完成。

示意状态机：

type AgentState =
  | "idle"          // 等待用户输入
  | "reasoning"     // 模型推理中
  | "awaiting_tool" // 工具执行中
  | "compressing"   // 上下文压缩中
  | "interrupted";  // 被用户打断

看似朴素的while(true)，真正工程化时要处理大量边界：

• 终止条件：除了“模型给出最终回答”，还必须有最大轮数、最大token消耗、超时三重保险，防止循环失控；
• 中断恢复：用户打断时，当前工具调用是立即丢弃还是执行完再停？被中断的任务如何留下“断点快照”供下次续跑？
• 错误分级：工具报错应作为观察结果回填给模型，让它自行纠正，而不是直接抛异常终止会话——这是智能体“自我修复”能力的关键来源；
• 状态持久化：会话状态需要可序列化，以支持跨进程、跨设备的会话迁移，这正是会话桥接模块存在的意义。

六、核心机制三：五层上下文压缩策略

长任务注定撑爆上下文窗口：一次大型重构动辄产生几十万token的工具输出。源码反映出的压缩策略，其思想可以归纳为五层：

• L0 近期原文层：最近若干轮对话与工具结果完整保留，保证模型对当前局面的精确感知；
• L1 轮次摘要层：较早的对话按轮折叠为摘要，保留意图与结论、丢弃冗余措辞；
• L2 工具输出提炼层：大体积工具输出（日志、文件内容、搜索结果）只保留结构化要点，原文落盘；
• L3 任务档案层：把目标、约束、关键决策、已验证的结论固化为一份“任务档案”，作为跨压缩存活的长期记忆；
• L4 外部检索层：被压缩掉的内容持久化到外部存储，需要时按需检索拉回。

值得注意的是压缩的执行者：压缩本身由一个专门fork出来的、上下文干净的子智能体完成。好处是压缩任务不会污染主对话上下文，且可以为它定制专门的提示词与工具集。

async function maybeCompress(state: SessionState) {
  if (state.tokenUsage() < COMPRESS_THRESHOLD) return;
  const summarizer = forkAgent({ preset: "context-compressor" });
  state.messages = await summarizer.run({
    recent:  state.messages.slice(-KEEP_RECENT), // L0 原样保留
    older:   state.messages.slice(0, -KEEP_RECENT),
    archive: state.taskArchive,                  // L3 任务档案
  });
  await persist(state.evicted);                  // L4 落盘供检索
}

工程上的两个关键参数是触发阈值与保留窗口：阈值太晚会请求超限，太早则频繁压缩损失信息；保留窗口太短模型会“失忆”，太长则压缩收益有限，需结合任务形态反复权衡。

七、多智能体体系：单Agent表象下的协作网络

透过源码可以看到，这类工具并非单Agent，而是一张协作网络：

• 主智能体：持有与用户的主对话，负责拆解任务与最终交付；
• 可派生的子智能体：主智能体按需spawn子智能体去执行探索型、高噪声型任务（如大规模代码检索），子智能体在隔离上下文中工作，只把结论带回主线，避免海量中间输出污染主上下文；
• 专职压缩智能体：负责上下文折叠；
• 后台任务智能体：承接测试、构建、批量修改等长耗时任务，与主对话异步解耦；
• 群体协作工具：提供多智能体并行协作的调度原语。

核心设计权衡是上下文隔离与通信成本：拆得越细，单个智能体的上下文越干净，但任务描述与结果回传的开销越大。经验法则是：探索型、可并行的任务适合下放子智能体；强依赖全局状态、需要多轮交互的任务留在主智能体。

八、工具系统与权限体系：安全边界的工程化

工具是智能体的“手脚”，权限是“缰绳”。源码体现出的两条原则非常值得借鉴：

第一，每个工具自带权限检查逻辑，权限不是集中在一个大switch里，而是作为工具定义的一部分：

interface Tool {
  name: string;
  schema: JSONSchema;                                   // 参数契约
  riskLevel: "readonly" | "write" | "execute" | "network";
  check(ctx: InvokeContext): PermissionDecision;        // 独立权限检查
}

第二，按风险分级实施差异化策略：只读工具默认放行；写入工具需要确认或白名单；执行类工具默认拦截、逐次授权；网络类工具额外审计。配合完整的调用日志，形成“最小权限+可审计”的闭环。权限模型越早建立，后期重构成本越小。

九、命令、插件与技能：可扩展性的三层设计

• 斜杠命令层：上百个斜杠命令本质是“高频操作的快捷方式”，把复杂的多步工具调用封装为一条指令，大幅降低交互成本；
• 技能层：把领域知识（代码规范、部署手册、调试套路）打包成可挂载的技能，模型在相关场景自动引用；
• 插件层：面向第三方开放注册，通过标准协议接入外部工具与数据源，同时继承统一的权限与审计框架。

三层共同遵循声明式注册、权限继承、向后兼容三个原则，这也是所有可扩展Agent平台的通用设计范式。

十、可落地的工程启示

综合以上拆解，Harness工程的经验可以浓缩为五条：

1. 模型负责决策，Harness负责确定性：凡是能用代码保证的（权限、阈值、重试、格式校验），绝不依赖模型自觉；
2. 一切皆事件流：用AsyncGenerator式的事件流统一模型输出、工具执行与UI渲染，中断、恢复、测试都变得自然；
3. 压缩不是可选项：只要任务够长，上下文管理就是第一等公民，分层压缩+专职压缩智能体是被验证过的方案；
4. 多智能体是上下文管理手段，不是炫技：拆分子智能体的首要动机是隔离噪声、保护主上下文；
5. 权限默认最小化：从第一个工具开始就建立分级授权与审计，而不是上线后再补。

对国内开发者而言，搭建此类系统不必从零造轮子：模型底座可以直接选用云上大模型服务，例如百度智能云提供的大模型推理与编排能力，开发者把精力聚焦在Harness层的设计上——这一层往往决定了一个智能体产品的最终上限。

十一、结语

Harness工程的本质，是把“不可靠的单次生成”工程化为“可靠的任务执行系统”。源码细节会随版本演进，但其背后的设计哲学——事件流驱动的主循环、显式的状态机、分层的上下文管理、隔离式多智能体、细粒度权限——具有相当的普适性。读懂这套哲学，比读懂任何一次泄漏本身都更有价值。