深入理解 Agent：从 Token 到 Harness 的六层工程底座

一、问题不在“聪明”，而在“能不能交付”

一个典型的场景是这样的：你让一个智能体去完成“给订单模块加一个优惠券核销能力”。演示环境里它表现很好，能定位到订单服务，能补全数据传输对象，甚至还能自动生成单元测试。可一旦接入真实代码仓库，问题开始集中爆发。

它读取二十个文件之后，开始忘记前面看过什么。接口文档里明确写了“核销接口需要幂等键”，但生成的代码没有带上。工具调用过程中出现权限错误，它没有停止，而是继续用错误上下文往下写。业务方只说“优惠券核销”，它却自行脑补了退款逻辑。最终生成的代码也许能运行，但无法合入主干。

这个现象背后有一个非常直接的判断：智能体工程的核心，不是把模型换大，而是把基础设施搭稳。模型能力决定上限，但工程链路决定下限。很多智能体不是不够聪明，而是缺少稳定交付的工程条件。

这里涉及六个关键词：Token、Skill、RAG、MCP、SDD、Harness。它们不是六个并列概念，而是同一个系统从“能回答”走向“能交付”的六层约束。

二、六层约束分别解决什么问题

Token 决定智能体当前能看见多少东西。
它不只是计费单位，更是智能体的工作台。模型在一次推理中能参考的指令、历史对话、工具返回、代码片段、错误日志、检索材料，全部要摆在这张工作台上。工作台越大，同时处理的材料越多；但它再大，也不是无限仓库。

Skill 决定智能体遇到重复任务时按什么规矩做。
它解决的是“流程一致性”问题。一个代码变更任务不是自由发挥，而是有固定步骤的：先定位、再确认接口、再修改、再补充测试、最后生成变更说明。Skill 把这些步骤固化下来，减少智能体每次重新发明流程。

RAG 决定智能体缺知识时从哪里补证据。
模型参数里的知识是有限的，也无法覆盖企业内部最新的接口文档、代码规范、历史故障记录。RAG 的作用是在推理之前或过程中，从可信来源检索相关材料，作为证据注入上下文，让智能体基于“查到的内容”而不是“猜到的内容”来行动。

MCP 决定智能体怎么安全、标准地接触外部系统。
智能体需要调用代码仓库、测试平台、工单系统、日志服务等。如果没有统一连接规范，每个集成都要单独适配。MCP 提供一种标准化的连接方式，让工具调用有边界、有权限、有错误处理，而不是随意访问。

SDD 决定智能体写代码之前有没有明确规格。
很多失败案例的共同点是：需求描述太模糊，智能体只能靠脑补。SDD 要求在实施之前先产出规格说明，明确输入输出、边界条件、异常路径、验收标准。规格越清楚，后续生成越可控。

Harness 决定这些能力能不能稳定跑成一个闭环。
它把 Token 管理、Skill 执行、RAG 检索、MCP 工具调用、SDD 规格校验串在一起，形成可重复运行的工程流水线。没有 Harness，这些能力只能停留在演示脚本里，无法稳定、可观测、可恢复地运行。

这六层不是孤立的。它们从下往上，构成一个完整的工程底座。下面逐层拆解。

三、Token：智能体的工作台，而不是单纯计费

Token 最常被理解为“模型按量计费的单位”。这个理解没错，但对智能体工程来说太浅了。更准确的理解是：Token 是模型单次推理的工作台面积。

所有要参与本次决策的信息，都要占用工作台空间。如果工作台不够大，就会出现“看了后面忘前面”的情况。这正是真实项目中常见的问题：智能体读了二十个文件，上下文已经溢出，早期读取的接口定义被后续内容挤掉，生成代码时就出现了遗漏。

但工作台也不是越大越好。更大的上下文意味着更高的成本、更慢的响应，也可能引入更多噪声。工程上要做的不是“尽量塞满”，而是做上下文预算管理。

具体来说，有几种思路：

1. 摘要压缩：对已经读过的文件生成结构化摘要，只保留关键符号、依赖关系和约束条件。
2. 分阶段加载：先加载目录结构和入口文件，定位到相关模块后，再按需加载更多细节。
3. 显式记忆区：把重要的跨步骤信息放到专门区域，避免被后续内容冲刷。

示意流程如下：

第一轮：
输入：任务描述 + 仓库结构概览
输出：候选模块列表 + 需要进一步查看的文件
第二轮：
输入：候选文件摘要 + 接口文档关键片段
输出：变更方案草案
第三轮：
输入：变更方案草案 + 测试失败日志
输出：修改计划 + 需要补充的规格项

每一轮的工作台内容都是经过筛选的，不是把整个仓库倒进去。这样即使上下文规模有限，也能保持关键信息不丢失。

四、Skill：把流程固化成可复用规范

如果每一次代码变更都让智能体自由发挥，结果会非常不稳定。Skill 的核心作用是把重复性任务变成标准流程。

以代码变更助手为例，一个完整的 Skill 可能定义为：

名称：代码变更交付
触发条件：用户提出代码修改需求
执行步骤：
1. 需求澄清：识别变更范围、影响模块、验收条件
2. 代码定位：检索相关文件、类、接口
3. 接口核对：查询接口文档，确认参数、返回值、约束
4. 变更实施：按规格修改代码
5. 测试补充：生成或更新单元测试
6. 变更自检：检查权限、幂等、异常处理等约束
7. 生成变更说明：输出 PR 描述和风险提示

Skill 的价值在于：它把“一次成功”变成了“每次都按同一套规矩做”。即使某一步失败，也能知道是哪个环节出了问题，而不是整个任务不可控。

Skill 与提示词的区别在于：提示词是单次输入的指令，Skill 是可编排的执行单元。Skill 可以包含条件分支、重试逻辑、前置校验和后置检查。它可以被组合，也可以被版本化管理。

rag-">五、RAG：缺知识时从证据源补，而不是靠脑补

模型参数中的知识有两个明显局限。第一，无法覆盖企业内部动态变化的文档。第二，无法区分“通用知识”和“当前项目约定”。

例如，“幂等键”是通用概念，模型可能理解。但“本项目核销接口的幂等键字段叫什么、放在哪个位置、是否必须由调用方传入”，这些是项目级知识，只能从文档或代码中检索。

RAG 的工作方式通常包括：

1. 构建知识索引：把接口文档、设计规范、代码注释、历史变更记录等分成块，建立向量索引或关键词索引。
2. 查询改写：把当前任务中的模糊需求改写成可检索的查询。
3. 相关性检索：从索引中召回最相关的材料。
4. 证据注入：把检索结果作为上下文的一部分，让模型基于证据生成结果。
5. 引用与校验：在输出中标注依据来源，便于人工核对。

对于“核销接口需要幂等键”这个问题，如果 RAG 能从文档中检索到确切要求，并把它放进上下文，智能体生成代码时就能带上这个约束。如果没有 RAG，模型只能靠通用经验猜测，漏掉就很正常。

六、MCP：工具接入的标准化与安全边界

智能体不能只靠模型推理，它需要调用外部系统。工具调用本身不复杂，复杂的是如何管理大量工具、如何统一权限、如何处理错误。

MCP 的本质是一种工具接入规范。它定义了工具如何描述自己的能力、如何接收参数、如何返回结果、如何报告错误。通过这个规范，智能体可以用一致的方式调用不同系统，而不需要为每个系统写专门的适配层。

安全边界同样关键。智能体在自动执行任务时，可能误调用生产环境的写操作，或者访问没有权限的资源。MCP 层的价值就是把“能做什么、不能做什么”显式化。

一个工具调用的安全流程可以抽象为：

调用请求 → 权限校验 → 参数校验 → 执行 → 结果封装 → 错误处理

任何一步失败，都应该返回明确的状态，而不是让智能体继续用错误上下文往下走。这正是原文中提到的问题：工具调用报权限错误时，智能体没有停下来，反而继续脑补。这不是模型能力问题，而是工程链路缺少阻断机制。

七、SDD：先用规格锁定“要做什么”

SDD 的核心思想很简单：在写代码之前，先写清楚要做什么。听起来像老生常谈，但在智能体场景下尤其重要。

因为智能体的“自主性”会放大模糊需求的危害。当业务方只说“优惠券核销”，智能体会根据训练数据里的常见模式自行补全。处理正常路径时也许没问题，但边界条件、异常路径、冲突场景就可能出错。

SDD 要求把需求转化为可验证的规格。一个简单的规格模板可以包括：

功能名称：优惠券核销
输入：订单编号、优惠券编号、幂等键
前置条件：订单状态为待支付或已支付，优惠券状态为未使用
处理逻辑：校验幂等键 → 锁定优惠券 → 更新订单金额 → 记录核销流水
异常处理：重复核销返回成功，不做二次扣减；优惠券已过期返回错误码
验收标准：核销后订单金额正确、优惠券状态为已使用、核销流水可追溯

有了这样的规格，智能体生成代码时就有了明确约束。它不是在“自由发挥”，而是在“按规格实施”。即便生成结果不完全正确，也能对照规格快速定位偏差。

SDD 并不要求规格一次写完整，而是要求先有规格再实施。规格本身可以被评审、被修改，但必须显式存在。

八、Harness：让能力跑成稳定闭环

前面五层解决的是“能力是什么”，Harness 解决的是“能力怎么稳定运行”。

Harness 是一个编排与执行框架，它负责把 Token 管理、Skill 执行、RAG 检索、MCP 工具调用、SDD 规格校验串成一个可重复的流程。

一个完整的执行闭环大致如下：

输入任务 → SDD 规格生成 → RAG 证据检索 → 上下文预算分配
→ Skill 步骤执行 → MCP 工具调用 → 输出校验 → 交付物生成
→ 日志记录 → 失败重试 → 结果反馈

Harness 的关键能力包括：

1. 可观测性：每一步的输入输出、Token 消耗、工具调用结果、错误信息都要有记录。
2. 可恢复性：某一步失败后，可以从断点重试，而不是从头再跑。
3. 可评估性：输出结果可以对照规格做自动化检查，判断是否达标。
4. 可配置性：不同项目可以配置不同的 Skill、知识源、工具权限和校验规则。

没有 Harness，前面的能力都只能存在演示脚本里。有了 Harness，智能体才能作为工程系统中的一环持续运行。

九、六层之间的关系：从下往上逐层支撑

这六层可以这样理解：

Harness     → 闭环与运行保障
SDD         → 规格与目标定义
MCP         → 外部系统接入边界
RAG         → 知识补充与证据来源
Skill       → 流程固化与复用
Token       → 上下文预算与工作台

越往下越基础，越往上越接近交付。但每一层都不能缺。上下文不够，规格再清楚也读不完整；工具接入不规范，检索再准确也可能执行出错；没有 Harness，单次成功也无法转化为稳定交付。

这也是为什么“换个大模型”解决不了所有问题。模型能力提升，可以改善单步推理质量，但无法自动解决上下文预算、流程固化、知识检索、工具安全、规格明确、闭环运行这些工程问题。

十、典型适用场景

这套六层结构不只适用于代码变更助手。凡是需要智能体从“回答问题”走向“执行任务”的场景，都可以用这个框架来审视。

智能运维：Token 决定一次能看多少监控告警；Skill 定义故障排查步骤；RAG 检索历史工单与处理方案；MCP 规范登录生产系统的权限；SDD 明确故障处理目标与回滚条件；Harness 保证排查过程可追溯、可恢复。

智能客服：Token 管理多轮对话上下文；Skill 定义标准服务流程；RAG 检索产品知识与政策文档；MCP 对接工单系统与订单系统；SDD 明确问题解决标准；Harness 保证服务链路可监控。

数据分析助手：Token 管理数据表结构与查询结果的上下文；Skill 定义从取数到分析的固定步骤；RAG 检索数据字典与指标口径；MCP 规范数据库访问权限；SDD 定义分析输出格式；Harness 保证任务可调度、结果可校验。

十一、容易混淆的概念区分

Token 与 RAG 的区别：Token 是上下文空间，RAG 是往这个空间里放什么内容。Token 解决“能放多少”，RAG 解决“放什么才是对的”。没有 RAG，Token 再大也可能装满无关内容；没有 Token，RAG 检索到的内容也放不进去。

Skill 与提示词的区别：提示词是单次指令，Skill 是可编排的流程。Skill 可以包含多个步骤、条件分支、重试策略和产出校验。提示词更轻量，Skill 更工程化。

MCP 与普通工具调用的区别：普通工具调用通常是一次性的、接口各异的。MCP 提供统一规范，解决工具发现、参数规范、错误处理、权限边界等问题。它是一种工程标准，而不是某个具体工具。

SDD 与需求文档的区别：需求文档面向人，SDD 面向机器可验证。SDD 通常包含结构化字段、约束条件、验收标准，可以被自动化检查。需求文档可以模糊，SDD 不能模糊。

Harness 与工作流的区别：工作流侧重步骤编排，Harness 侧重运行保障。Harness 包含可观测性、可恢复性、可评估性等工程能力，不只是把步骤串起来。

十二、使用中的注意点

上下文预算要提前规划，不要默认无限。即使上下文很长，也要做预算管理。要预留空间给系统提示、工具返回、检索材料和输出结果。

Skill 需要版本化，不要散落在提示词里。流程固化之后要能复用、能修改、能追溯。

RAG 的质量取决于索引和检索策略。不是把文档塞进去就行。要关注分块方式、索引质量、相关性和引用校验。

MCP 要格外注意最小权限与错误阻断。工具调用失败要能中止流程，而不是让智能体继续用错误上下文生成。

SDD 要可验证，不要写空泛描述。“优化体验”不是规格，“响应时间不超过 500ms”才是。规格越可验证，生成结果越可控。

Harness 要记录关键节点，避免黑盒运行。每一步的输入输出、Token 消耗、工具结果都要留痕，方便复盘和改进。

十三、总结

智能体的聪明程度只是上限，工程底座决定下限。Token、Skill、RAG、MCP、SDD、Harness 这六层，分别解决上下文、流程、知识、工具、规格、运行这六个问题。它们共同构成了智能体从“能回答”到“能交付”的基础设施。

理解这六层关系，不是为了堆砌术语，而是为了在工程实践中有一个清晰的诊断框架。当一个智能体在真实场景中表现不佳时，可以逐层排查：是上下文不够，还是流程不固定？是缺证据，还是工具接入不安全？是规格不明确，还是运行闭环没搭好？答案往往就在这条链里。