Agent Harness 工程方法论： AI 编程的核心不是模型
2025 年是 Agent 之年——大家都在造 Agent。是 Agent Harness 之年——大家发现 Agent 不好用，问题不在模型，在 Harness。本文结合我们团队的实践，拆解这个正在改变 AI 工程格局的方法论。
一、一句话定义：Harness = 模型之外的一切
一个裸模型（比如 Claude Opus）本身不是 Agent。但当你给它加上工具执行、状态管理、反馈循环、约束规则之后，它就变成了一个 Agent。
这些"加上去的东西"，就是 Harness。
用 Claude Code 来理解——你每天用它写代码，其实你已经在用一个精心设计的 Harness：
用户输入
↓
[Harness 层]
├── 系统提示词（System Prompt）
├── CLAUDE.md 项目规则
├── 工具集（Read/Write/Edit/Bash/Grep/Glob）
├── MCP 协议（连接外部工具）
├── 子代理（Explore/Plan 等）
├── 上下文压缩（四级 Compaction）
├── 权限检查（Permission）
├── Hook 系统（事件钩子）
└── 记忆系统（Memory）
↓
Claude 模型（大脑）
↓
工具执行 → 结果反馈 → 继续循环
模型是大脑，Harness 是大脑工作的整个环境。
就像一个天才程序员——如果你把他扔到一个没有电脑、没有文档、没有 Git、没有测试框架的荒岛上，他也写不出好代码。Harness 就是给这个天才程序员配备的完整工作环境。
二、三层分类：Framework / Runtime / Harness
Harrison Chase（LangChain 创始人）在 2025 年提出了清晰的三层分类：
┌─────────────────────────────────────┐
│ Agent Harness │ ← 最高层：开箱即用
│ (Claude Code, Devin, 我们的平台) │ 工具+状态+反馈+约束全包含
├─────────────────────────────────────┤
│ Agent Runtime │ ← 中间层：持久执行
│ (LangGraph, Temporal, 我们的 Runtime)│ 循环+状态管理+错误恢复
├─────────────────────────────────────┤
│ Agent Framework │ ← 最底层：构建块
│ (LangChain, CrewAI) │ 抽象接口+组合模式
└─────────────────────────────────────┘
用装修来类比：
- Framework = 建材市场。给你砖头、水泥、电线，你自己决定怎么盖房子。灵活但费劲。
- Runtime = 毛坯房。结构搭好，水电已通，你需要自己装修。稳定但需要定制。
- Harness = 精装房。拎包入住，灯开关按了就亮，水龙头拧了就有水。开箱即用。
我们在做的事情，就是为企业构建一个精装修的 Agent Harness。
三、Harness 的操作系统类比
Philipp Schmid（Hugging Face）给了一个更精准的类比：
| 操作系统 | Agent Harness |
|---|---|
| 内核（调度/内存管理） | Agent 循环（调度工具调用/管理上下文） |
| 文件系统 | 持久化状态/记忆（File System Memory） |
| 驱动程序 | 工具处理（Tool Handling / MCP） |
| 应用程序 | 你的 Agent 逻辑（具体任务） |
| 权限系统 | Permission Engine |
| 进程管理 | Multi-Agent 调度 |
Harness 就是 Agent 的操作系统。你不需要自己写操作系统，你只需要在上面写应用。
四、Harness 设计的六大原则
这六条原则来自 Anthropic 官方方法论 + 我们的实践验证：
原则 1：模型是大脑，平台是 Harness
含义：平台提供工具、状态、约束、反馈循环。不要试图用提示词解决所有问题。
实践：我们的 Runtime 只做编排，不做推理。约束通过 Permission Engine 机械化执行，而非在 Prompt 里写"请不要执行危险命令"。
❌ 错误做法：
"你是一个谨慎的 Agent，请不要执行 rm -rf 命令"
（模型可能忽略这条指令）
✓ 正确做法：
Permission Engine L1 静态黑名单：
if command matches ["rm -rf", "dd if=/dev/zero", ...]:
return DENY # 机械化拒绝，不经过模型判断
原则 2：上下文纪律（Context Discipline）
含义：精准注入，知道该排除什么比知道该包含什么更重要。
实践：我们的四级压缩管道 + 双层知识图谱，本质都是"只给模型最需要的上下文"。
数据说话：
- 无压缩：一次复杂对话累积 180K tokens，模型注意力分散
- 有压缩：同样对话 72K tokens，关键信息保留度 > 95%
原则 3：工具少而精
含义：通用原子工具 > 大量专用工具。
实践：Claude Code 只有 7 个核心工具（Read/Write/Edit/Bash/Grep/Glob/Agent），但覆盖了 90% 场景。我们的 Coding Agent 核心工具也只有 6 个（write_file/read_file/list_files/run_command/preview_url/code_search）。
❌ 错误做法：
create_react_component, create_vue_component, create_angular_component,
add_import, remove_import, rename_variable, ...
（50 个专用工具，模型选择困难）
✓ 正确做法：
write_file, read_file, run_command
（3 个通用工具，模型用它们组合出任何操作）
原则 4：约束靠机械而非提示词
含义：Linter + 测试 > "请不要犯错"。
实践：五层权限防御全部是代码逻辑，不是 Prompt 指令。编译检查是 mvn compile 实际执行，不是"请确保代码可以编译"。
原则 5：为删除而构建
含义：模块化，模型迭代时可替换。
实践：我们的 Model Gateway 用 Provider 抽象隔离具体模型。从 GPT-4o 换到 DeepSeek V3 只需改配置，不改任何业务代码。当更好的模型出现时，5 分钟完成切换。
原则 6：先观察失败再添加基础设施
含义：最小可行 Harness 迭代，不要过早优化。
反面教训：我们第一版花了两周做上下文缓存，后来发现瓶颈在 LLM 延迟（3-30s），缓存省的那 50ms 毫无意义。应该先跑起来，观察真正的瓶颈在哪。
五、我们的 Harness 实践全景
把六大原则落地到我们的平台：
┌─────────────────────────────────────────────────────────────────┐
│ 我们的 Agent Harness │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ 原则 1：平台是 Harness │ │
│ │ · Copilot 对话治理 + 智能路由 │ │
│ │ · Runtime ReAct/DAG/Coordinator 三模式执行 │ │
│ │ · Gateway 鉴权限流 │ │
│ └──────────────────────────────────────────────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ 原则 2：上下文纪律 │ │
│ │ · 四级压缩管道（Snip/Micro/Collapse/Auto Compact） │ │
│ │ · 双层知识图谱（Graphiti 语义 + Codebase-Memory 结构） │ │
│ │ · 三层记忆（Session/Semantic/File System） │ │
│ └──────────────────────────────────────────────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ 原则 3：工具少而精 │ │
│ │ · 4 个 MCP Server 暴露 20+ 标准化工具 │ │
│ │ · 沙箱 6 个原子工具覆盖全部文件/命令/预览操作 │ │
│ │ · MCP 协议统一，IDE 无关 │ │
│ └──────────────────────────────────────────────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ 原则 4：约束靠机械 │ │
│ │ · 五层权限防御（代码逻辑，非 Prompt 指令） │ │
│ │ · CI 门禁自动检测 Prompt Regression │ │
│ │ · 图谱质量五级校验（Schema/完整性/抽检/漂移/新鲜度） │ │
│ └──────────────────────────────────────────────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ 原则 5：为删除而构建 │ │
│ │ · Model Gateway Provider 抽象（5 分钟换模型） │ │
│ │ · Skill 系统 Markdown 定义（不绑模型/IDE） │ │
│ │ · 三阶段编排各 Agent 独立演进（PRD/Spec/Coding） │ │
│ └──────────────────────────────────────────────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ 原则 6：先观察失败 │ │
│ │ · OpenTelemetry 全链路追踪（Agent→Tool→Model） │ │
│ │ · 三层评测体系（先看哪里不行，再优化哪里） │ │
│ │ · 成本归因到 Agent 粒度 │ │
│ └──────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
六、Skill 系统：Harness 的可扩展层
Harness 如果是"操作系统"，那 Skill 就是"应用商店里的 App"。
6.1 为什么用 Markdown 定义 Skill
---
name: sid-bugfix
version: 1.1.4
trigger: "Bug 修复、问题定位、报错分析"
---
# SID Bug 修复 Skill
## Step 0: 环境检测
检测以下知识源是否可用：
- [ ] references/component-index.md
- [ ] references/global-summary.md
- [ ] sid-codegraph MCP Server
## Step 1: 定位
1. 从 component-index 匹配关键词 → 确定涉及的服务
2. 读取对应服务的 CLAUDE.md → 理解服务结构
3. 调用 codegraph_search → 精确到类/方法
...
Markdown 的哲学：
- 不绑定模型 — Claude、GPT、DeepSeek 都能消费 Markdown
- 不绑定 IDE — TRAE Work、Claude Code、Cursor 都支持 Markdown 规则文件
- 零代码门槛 — PO 和业务方都能编写和修改 Skill
- 版本化 — Git 管理，MR 审查，CI 校验
6.2 分发流程
开发者编写 Skill (skills/sid-bugfix/SKILL.md)
│
▼ git push → develop 分支
│
▼ CI 触发
├── validate: 检查 Markdown frontmatter 格式
├── build: 打包为 tar.gz，更新 manifest.json
└── deploy: 拷贝到分发服务器 (172.27.80.129:3004/tools/)
│
▼ 团队成员执行
curl -fsSL http://172.27.80.129:3004/tools/setup-trae.sh | bash
│
▼ 自动配置到 IDE
· MCP Servers（sid-codegraph + ssh-deploy + feishu-docs）
· Skills（sid-bugfix + git-publish + unit-test-gen + ...）
整个过程对使用者完全透明——开发者提交 MR，merge 后团队自动获得新版本。
6.3 与 Claude Code 的 CLAUDE.md 对比
| 维度 | Claude Code CLAUDE.md | 我们的 Skill 系统 |
|---|---|---|
| 作用域 | 单个项目 | 团队级别 |
| 分发 | 手动放在项目根目录 | CI 自动打包分发 |
| 版本管理 | 随项目 Git | 独立仓库，manifest 版本 |
| 内容 | 项目规则 + 上下文 | 完整操作流程 + 知识引用 |
| 更新 | 手动编辑 | CI 自动 bump + 分发 |
我们的 Skill 系统是 CLAUDE.md 理念的"团队级放大版"。
七、FDE：AI 时代的新工程师角色
7.1 从 Developer 到 Full-stack Development Engineer
传统开发者的工作：需求→设计→编码→测试→部署。
FDE 的工作：设计 AI Agent 的工作环境。
| 传统开发者 | FDE |
|---|---|
| 写代码 | 设计 Agent 应该用什么工具 |
| 写测试 | 设计 Agent 应该受什么约束 |
| 写文档 | 构建 Agent 需要的知识体系 |
| 优化性能 | 优化 Agent 的上下文效率 |
| 做 Code Review | 设计 Agent 如何自审 |
7.2 FDE 的能力矩阵
| 能力维度 | 具体技能 |
|---|---|
| Harness 工程 | Agent Loop 设计、上下文管理、工具编排、权限模型 |
| 知识工程 | 本体设计、图谱生成/校验、MCP Server 开发 |
| Prompt 工程 | Skill 编写、System Prompt 调优、Few-shot 设计 |
| 平台运维 | CI/CD 集成、沙箱管理、监控可观测 |
| 全栈开发 | Python(FastAPI) + TypeScript(React) + Docker + K8s |
7.3 FDE 的核心判断力
FDE 最重要的不是写代码能力，而是判断力：
- 这个任务应该让 Agent 自主决策（ReAct），还是预定义流程（DAG）？
- 这个约束应该放在 Prompt 里（软约束），还是放在代码里（硬约束）？
- 这个知识应该放在上下文（实时注入），还是放在文件系统（按需读取）？
- 这个工具应该暴露给 Agent（可能被滥用），还是藏在 Harness 内部（自动触发）？
每个判断都影响 Agent 的行为质量。这些判断力，比写代码更稀缺。
八、2026 年的行业趋势
8.1 模型差距在缩小，Harness 差距在拉大
Philipp Schmid 的原话：
"顶级模型在静态排行榜上的差距正在缩小。真正的差距在任务变长、变复杂时才显现出来。这归结为持久性：模型在执行数百次工具调用后，还能多好地遵循指令。"
换句话说：短对话看模型，长任务看 Harness。
8.2 MCP 正在成为标准
2025 年底 Anthropic 发布 MCP 协议，2026 年已被 Claude Code、Cursor、TRAE Work、Windsurf 等工具支持。
这意味着：
- 工具一次开发，多 IDE 可用
- 知识索引一次建设，多 Agent 可消费
- Skill 一次编写，跨模型可执行
我们的 4 个 MCP Server 在 TRAE Work 和 Claude Code 中同时可用，零额外适配工作。
8.3 从"配置 Agent"到"构建 Harness"
早期的 Agent 开发：写个 Prompt + 配几个工具 = 一个 Agent。
现在的 Agent 开发：
- 设计上下文策略（压缩/记忆/检索）
- 构建知识体系（图谱/索引/CLAUDE.md）
- 编排执行模式（ReAct/DAG/Multi-Agent）
- 实现安全边界（权限/审计/降级）
- 建设评测体系（Golden Test/CI 门禁）
- 设计分发机制（Skill/MCP/一键配置）
"配置 Agent"是 10 分钟的事。"构建 Harness"是 6 个月的系统工程。
九、给同行的建议
9.1 如果你刚开始做 AI 平台
- 先跑起来再优化 — 单体 + ReAct Loop + 2-3 个工具，一周内上线
- 观测先行 — 第一天就接 OpenTelemetry，知道哪里是瓶颈
- 不要自研模型调用层 — 用 litellm 或自己写一个薄 wrapper，核心精力放在 Harness
9.2 如果你已经有了基础平台
- 上下文是第一优先级 — 压缩管道的 ROI 远超其他优化
- 知识工程是差异化 — 竞品可以抄你的架构，抄不走你的知识体系
- Skill 体系比 UI 重要 — 好用的 Skill 让用户留下来，漂亮的 UI 不能
9.3 如果你是独立开发者
- 用好现有 Harness — Claude Code 的 CLAUDE.md + MCP 已经足够强大
- 投资知识沉淀 — 为你的项目写好 CLAUDE.md，比学新框架更有价值
- 理解 Harness 思维 — 当你遇到 Agent"不听话"的问题，先想是不是 Harness 的问题，而非模型的问题
十、结语
2026 年，AI 编程领域最重要的认知转变：
从"用更聪明的模型"到"建更好的 Harness"。
模型会持续进步，但模型的进步是所有人共享的——你用 Claude Opus，竞争对手也能用。
真正的护城河在 Harness：你的知识图谱、你的 Skill 体系、你的上下文策略、你的安全边界、你的评测数据。这些东西需要时间积累，需要对业务的深刻理解，需要持续迭代。
模型是水，Harness 是管道。水人人都有，管道才是基础设施。
本文观点基于我们团队的实践经验，不代表行业共识。AI 领域变化极快，六个月后可能需要重新审视。
