「Agent」一词常被混用：有时指整个产品（Cursor Agent、Devin），有时仅指模型的一次调用。工程讨论需要区分：
- Model：可替换的推理引擎（GPT、Claude、开源权重等）。
- Harness：围绕模型搭建、使其能可靠完成工作的系统层。
Harness = Agent − Model
同一 Model 配上不同 Harness，表现可以天差地别；反之，升级 Model 时，Harness 往往可以大部分保留。这是 Harness Engineering 作为独立学科的依据。
| 层 | 职责 | 典型资产 |
|---|---|---|
| Model | 理解、规划、生成、决定是否调用工具 | API、权重、温度、max tokens |
| Harness | 上下文、工具、约束、记忆、编排、安全 | rules、skills、MCP、CLI、hooks |
| Environment | Harness 作用的现实世界 | 代码库、浏览器、云 API、用户机器 |
Agent 的一次「运行」（run）= Model 在多轮 loop 中与 Harness、Environment 交互直至停止条件。
Harness Engineering 是设计、实现、测试和演进 Harness 的学科，目标包括：
- 可靠性：同样任务重复成功率可度量、可提升。
- 可维护性：规则、技能、工具契约可版本化、可 code review。
- 可替换性：换 Model 时 Harness 接口稳定。
- 可观测性：知道失败发生在检索、工具、权限还是推理。
它不等于 Prompt Engineering（那只是 Harness 的一个子集），也不等于「微调模型」。
| 术语 | 定义 |
|---|---|
| Run | 一次从用户输入到 Agent 停止的完整会话 |
| Turn | Run 内一轮 user/assistant 交换 |
| Tool call | Model 输出结构化调用，由 Harness 执行 |
| Context window | Model 单次可见的 token 上限 |
| System prompt | Harness 注入的、通常最高优先级的指令层 |
| Grounding | 用检索或工具结果把回答锚定在事实源上 |
| Compaction | 压缩历史上下文以腾出窗口 |
| Subagent | 由主编排器派生的专用 Agent 实例 |
- Prompt Engineering → Harness 的「语言接口」层。
- Context Engineering → Harness 的「带宽管理」层。
- RAG → Harness 的「外部知识接入」层。
- Fine-tuning → 改 Model，不是 Harness（但训练数据可来自 Harness 日志）。
- 默认显式：约束写在 rules/skills，而非指望模型「记得」。
- 工具优于长篇解释：能执行就不让模型猜。
- 可测试：Harness 组件应能单独做集成测试（evaluation）。
- 失败可定位：检索空、工具超时、权限拒绝应各有清晰信号。
- 组合优于单体：小模块（skill、MCP server）可独立演进。
下一篇：architecture.md