系统架构与 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 通常包含三个正交层面:
- 感知与上下文层(Context Plane):负责仓库索引、AST 符号提取以及历史对话的滑动窗口摘要。
- 决策与编排层(Control Plane):管理状态机流转、工具调用权限边界以及最大重试预算(Retry Budget)。
- 确定性验证层(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 并行开发下的工作区隔离策略与冲突消解机制。