AI-Native 研发手记
菜单
系统架构与 Harness· 专栏:AI-Native 研发架构演进 (#1)

从辅助补全到自主闭环:构建可控的 Coding Agent Harness

拆解 AI-Native 研发中的核心控制面设计,探讨如何通过沙盒隔离、确定性验证器与上下文裁剪降低 Agent 幻觉率。


TL;DR · 核心工程结论
  • 模型能力决定上限,但 Harness(控制面与验证闭环)决定工程落地的下限。
  • 将非确定性的 LLM 输出包裹在确定性的编译器、类型检查与测试断言中,是消除幻觉的最有效手段。
  • 上下文窗口不是无限缓存,主动的状态压缩与按需检索(Just-in-Time Context)能显著提升多步推理准确率。

1. 问题定义与背景

在早期的 AI 辅助编程阶段,开发者扮演的是“人类路由器”——在 IDE、聊天窗口和终端之间手动搬运上下文与报错信息。当研发范式向 AI-Native 演进时,核心瓶颈不再是代码生成速度,而是多步执行过程中的状态漂移与验证缺失。

2. 系统架构拆解

一个生产可用的 Agent Harness 通常包含三个正交层面:

  1. 感知与上下文层(Context Plane):负责仓库索引、AST 符号提取以及历史对话的滑动窗口摘要。
  2. 决策与编排层(Control Plane):管理状态机流转、工具调用权限边界以及最大重试预算(Retry Budget)。
  3. 确定性验证层(Verification Plane):执行 tsc、单元测试、Linter 及自定义规则断言,将结构化报错反馈回控制面。
┌─────────────────────────────────────────────────────────┐
│                    Control Plane (Orchestrator)         │
│   [Task Planner] ──▶ [Tool Router] ──▶ [Budget Guard]   │
└─────────┬───────────────────────────────────▲───────────┘
          │ Action / Patch                    │ Structured Error
          ▼                                   │
┌─────────────────────┐             ┌─────────┴───────────┐
│   Sandbox Runtime   │────────────▶│ Deterministic Evals │
│ (Isolated Worktree) │             │ (Build / Test / AST)│
└─────────────────────┘             └─────────────────────┘

3. 范式对比:裸调模式 vs. 验证闭环

传统多轮对话式修复
  • 人工复制终端报错粘贴给模型
  • 上下文随轮次膨胀,后期注意力严重衰减
  • 缺少熔断机制,容易在同一错误上反复打转
Harness 确定性闭环
  • 隔离工作区自动触发类型与单测校验
  • 仅提取前 15 行关键诊断信息回灌上下文
  • 达到最大重试预算自动挂起并生成根因报告

4. 关键实现:确定性验证闭环

以下是控制面在接收到代码变更后触发验证器的核心逻辑示意:

interface VerificationResult {
  passed: boolean;
  stage: 'typecheck' | 'unit-test' | 'lint';
  diagnostics: string[];
}

export async function runVerificationLoop(
  worktreePath: string,
  maxRetries = 3
): Promise<VerificationResult> {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    const check = await executeTypeCheck(worktreePath);
    if (check.passed) {
      return { passed: true, stage: 'typecheck', diagnostics: [] };
    }
    // 仅提取关键错误行喂回上下文,避免数千行堆栈污染窗口
    await feedCompactErrorToAgent(check.diagnostics.slice(0, 15));
  }
  return { passed: false, stage: 'typecheck', diagnostics: ['Max retries exceeded'] };
}

5. 量化对比与踩坑复盘

策略维度 裸调 LLM(无验证闭环) 引入确定性验证 + 精简报错反馈
端到端任务通过率 ~42% ~78%
单任务平均 Token 消耗 较低(但经常因方向跑偏全部作废) 中等(有效推理占比大幅提升)
典型失败模式 臆造不存在的 API 或破坏现有类型定义 陷入局部死循环(需配合最大重试熔断)

6. 演进方向

在下一篇系列文章中,我们将进一步拆解多 Agent 并行开发下的工作区隔离策略与冲突消解机制。