这份指南解决一个具体问题：有软件工程基础的开发者，如何从「会调 API、会用 Claude Code」系统性地进入 Agent 工程。它把整条路组织成六个互为前置的阶段——用户视角起步，手写 agent 建立肌肉记忆，逐项加能力，评测驱动迭代，生产化，最后专精一条赛道——每个阶段都有明确的过关标准，达标再进下一阶段。全职投入约 4–6 个月，在职每天 1.5–2 小时约 8–12 个月。读完并做完，你手里会有一个可部署、可评测、可审计的 agent，和一套比代码更值钱的自建评测集。

核心原则一句话：吃透不变的（循环、工具、上下文、评测），跟紧在变的（协议、平台、编排范式），用自建评测集校准一切结论。

先交代时效边界：本文内容以 2026 年 7 月为准。原理与训练方法（基础、核心知识、实战路线、常见坑）预计 2027 年之后依然成立；前沿趋势与资源清单是快变层，需每季度对照一手信源刷新。凡涉及具体工具、模型、数字的表述，文中保留了「截至」时标；二手数据未能交叉核实的，显式标注「待核」。

怎么用这份指南.

  • —适用对象：有软件工程基础、想系统进入 Agent 工程（而非停留在「会调 API / 会用 Claude Code」）的开发者。此前完全没接触过 LLM 开发的读者，请再预留 1–2 个月补第 0 部分。
  • —过关制：每个阶段附「过关标准」，达标再进下一阶段。宁可慢，不可跳——尤其不能跳过阶段 3（评测），它是「agent 工程师」与「调 prompt 的人」的分水岭。
  • —两条独立的轴：知识模块的星级表示重要度（★★★★★ 必修 → ★★★ 按需），分组表示学习时序（内功最先 → 门槛在生产化前补齐 → 进阶按需）。两者独立——例如「安全」重要度 ★★★★★，但学习时序在门槛组：不必最先学，但上线前必须补齐。

学习路径总览.

六阶段学习路径：用户视角、手写 Agent、逐项加能力，跨过评测分水岭，进入生产化与专精赛道。 AGENT ENGINEERING · 六阶段 评测是分水岭：六个阶段互为前置. 用户视角 手写 Agent 逐项加能力 专精赛道 生产化 评测驱动 分水岭
六个阶段互为前置；阶段 3（评测）是分水岭——它决定你是在做工程，还是在调玄学。

每个阶段的前置条件与目标产出如下；第 1 部分的 13 个知识模块，按「首次需要」的时点挂到对应阶段：

阶段时长前置条件要吃透的模块目标产出
0 用户视角1–2 周（可全程并行）软件工程基础第 0 部分全部≥3 个真实任务的分析笔记 + trace 标注
1 手写 Agent1–2 周阶段 0模块 1200–300 行零框架 agent 修掉一个真实 bug；3–5 任务冒烟集
2 逐项加能力3–5 周阶段 1模块 2、3、11agent 具备 ≥6 项能力；同任务成本优化 ≥3 倍（有数据）
3 评测驱动3–5 周阶段 2模块 4「改动 → 指标 → 归因」报告；10–30 题评测集一键复跑
4 生产化4–6 周阶段 3模块 5–9、12他人可独立部署的交付物 + 安全说明 + 评测进 CI
5 专精赛道长期阶段 4模块 10、13 按赛道一条赛道上的深度作品

如果你想要一条与这份路线对口的「动手构建」主线，书库里的《从零构建一个完整 Agent》正是按同一条弧线展开的：从只会聊天的 LLM 一步步加到工具、记忆、MCP、多 agent、上线，直到企业级——适合作为阶段 1–4 的实战伴读。

第 0 部分 · 基础与坐标系（1–2 周，可与全程并行）.

目标不是「学完再动手」，而是建立最小必要的心智模型与坐标系，缺哪补哪。

工程基础自查.

对照清单自查，缺项即补：

  • —Python：async/await、subprocess、类型标注、venv/uv。TypeScript 可选（Agent SDK 与 gemini-cli 为 TS；注意 codex CLI 是 Rust）。
  • —Linux / Bash：管道、进程与信号、grep/find/sed 基本功——你的 agent 主要靠它们干活。
  • —Docker：镜像 / 容器 / volume / 网络隔离，能独立写 Dockerfile——这是沙箱的起点。
  • —其他：Git、HTTP 语义、SSE 流式、JSON Schema（工具定义的语言）。
  • —数据与分布式最小集：Postgres / Redis / 消息队列的基本使用；幂等性、重试语义、至少一次 vs 至多一次投递——生产 agent 本质上是一个分布式服务，这些概念会在模块 6 兑现。
  • —补救路径：Python 薄弱者先补到能独立写 async 脚本再进阶段 1；主力 TS / Go 的读者可全程用 TS 实现（Agent SDK 有 TS 版），概念完全同构；Windows 原生环境建议 WSL2。

LLM 工作原理最小必要集.

不需要会训模型，但以下心智模型直接决定后面工程决策的质量：

  • —token 与自回归生成；context window 为何有限、超限会发生什么。
  • —采样参数（temperature / top_p）对 agent 行为稳定性的影响。
  • —KV cache 原理：为什么「稳定前缀 + append-only」的上下文设计能把成本与延迟降低数倍到一个数量级——这是后面上下文工程的物理基础，务必先懂原理再学技巧。
  • —幻觉的成因与边界；模型能力随版本跳变（这决定了 harness 假设会过期，见第 3 部分）。

资源：Karpathy 的 LLM 入门视频（如 Deep Dive into LLMs）、3Blue1Brown 的 Transformer 可视化系列、Anthropic 文档中的模型概览部分。

API 与 Tool Use 协议（动手为主）.

  • —Messages API：system / user / assistant 回合制、streaming。
  • —Tool use 全流程：JSON Schema 定义工具 → 模型返回 tool_use → 你执行 → 回填 tool_result → 模型继续。用原始 HTTP 请求（不借助任何 SDK）亲手完整走一遍——这是理解一切 agent 框架的钥匙，之后你看任何框架都能「透视」到这一层。
  • —Prompt caching 的用法与计费差异；extended / interleaved thinking；结构化输出。

资源：Anthropic 官方文档（docs.claude.com）与官方免费课程（github.com/anthropics/courses）；OpenAI 对应文档扫读一遍，建立跨平台视野。用户侧的补充：如果你手里有 OpenAI 订阅，书库里的《OpenAI · 一份订阅，几个产品》梳理了其中真正该用的那几个产品。

提示工程基础.

清晰指令、正反例、XML 结构化、先想后答、指定输出格式与长度。读一遍 Anthropic 的 prompt engineering 文档即可——真正的训练在后面：工具的命名、参数、description、报错信息本质上全是提示词，阶段 1–2 会反复实践。

领域简史（建立坐标系）.

  • —2022：ReAct 确立「推理 + 行动」范式。
  • —2023：AutoGPT 证明了需求，也证明了当时的模型撑不住长程自主。
  • —2024：tool use 原生化；SWE-agent 提出 ACI（Agent-Computer Interface），「为 agent 设计接口」成为学科起点；MCP 于 11 月发布。
  • —2025：agentic coding 爆发；MCP 成为事实标准；context engineering 从技巧升格为核心学科；Agent Skills 发布并于年底开放为跨产品标准；小时级长时程运行开始出现。
  • —2026：orchestration era——工程师角色从「写代码」转向「指挥与验收 agent」；多智能体回潮；托管化 harness（Managed Agents 类服务）出现；行业焦点从模型竞赛转向 harness 竞赛。

术语速查见文末附录，遇到生词随时查。

第 1 部分 · 核心知识体系.

十三个模块，三组时序：内功四件套最先，上线门槛在生产化前补齐，进阶按需。

内功四件套（时序最先；均 ★★★★★）.

1. 执行循环与自验证。 循环本身只是 while + tool call，复杂度全在周边：错误恢复策略、停止条件、中断与取消，以及最终自验证——让 agent 跑测试自证完成，而不是自我宣布完成。经验法则：提升反馈回路的质量，往往比调 prompt 更有效。这一条会在阶段 1 用 200–300 行代码完整走一遍。

2. 工具工程（2026 年已是三层结构）。 基本功不变：工具的命名、参数设计、description、报错信息本质全是提示词；少量正交的工具优于大量重叠的工具；报错要告诉 agent「下一步该怎么办」而不是只抛 stack trace；严格控制工具输出的 token 量。设计新能力时先问一个三选一的问题——这该是 tool、MCP server，还是 skill：

层定位一句话
原生 function calling模型边界单个动作的结构化出入口
MCP系统连接层给 agent 接入一个活的系统
Agent Skills方法论封装层教 agent 怎么做一类事（SKILL.md + progressive disclosure，跨产品开放标准，见 agentskills.io）
  • —Code mode：当工具数量到几十上百个时，让模型写脚本编排工具而不是逐个链式调用——token 消耗与错误率都大幅下降。读 Anthropic《Code Execution with MCP》。
  • —工具可靠性工程：把工具当 API 产品做全生命周期管理——schema 版本化与向后兼容、契约测试与 mock tool、超时 / 重试 / 幂等语义的显式约定。大量 agent 失败源于工具质量而非模型能力；工具需要自己的测试与回归。
  • —经典深坑专题：文件编辑器设计（str_replace vs diff vs 整文件重写），值得专门对比各家实现。
  • —想在动手前先从用户侧感受「给 agent 接入一个活的系统」是什么体验，书库里的《Warp · 长得像终端的元工具》写的正是一个带 agent、接 MCP 的终端型元工具——接上一个 server 用起来，比读十遍协议文档更快建立直觉。

3. 上下文工程。 2025 年以来最核心的差异化能力。实践武器库：

  • —KV cache 友好设计：稳定前缀、append-only、工具定义不动态变化——对成本与延迟的影响可达数倍到十倍量级。
  • —文件系统当外部记忆：大结果落盘，上下文只留路径引用。
  • —todo 复述：把计划反复写到上下文末尾，对抗 lost-in-the-middle。
  • —压缩（compaction）与 API 层 context editing；子 agent 做上下文隔离（各自独立 context window，返回结论而非过程）。
  • —Progressive disclosure：Skills 的核心机制——先给模型一行摘要，需要时才展开全文，本质是「按需加载」的上下文工程。
  • —平台能力优先：API 层的 context editing 与 memory tool 已产品化，先用平台的，再考虑自建。
  • —检索取舍：agentic search vs 向量 RAG：让模型用 grep / read 式工具自主迭代检索（Claude Code 路线）在代码与有结构语料中通常优于向量检索；向量 RAG 适合海量非结构化语料与模糊语义匹配。判断维度：语料是否有天然结构、查询能否迭代细化、索引维护成本。coding agent 的代码检索栈（repo map、tree-sitter、LSP）是这里的专题深坑。

4. 评测与 trace 分析。 没有 eval 的优化都是玄学。

  • —离线基准：SWE-bench Verified（人工校验过的 500 题，用它而不是 Lite）、Terminal-Bench（终端任务）、τ-bench（工具调用 + 用户模拟，pass^k 的出处）、OSWorld / WebArena（computer use 方向）。
  • —自建任务集最重要：10–30 个来自你真实工作的任务，比任何公开基准都值钱。
  • —判定方式：程序化判定优先于 LLM-as-judge（后者自身需要校准）。
  • —指标：pass@k 衡量能力上限，pass^k 衡量可靠性（k 次全对的概率）——生产系统看后者。
  • —失败归因分类学：上下文丢失 / 工具误用 / 过早放弃 / 验证缺失 / 环境问题——归因比分数更重要。
  • —基准污染与成本归一化：公开基准可能已混入训练数据，分数要打折看待，自建评测集不公开原题、定期换血；跨方案比较必须成本归一化——同预算比效果，或同效果比成本，否则结论无意义。
  • —确定性与可复现：temperature=0 也不保证逐 token 确定（浮点归约顺序、动态批处理、MoE 路由都会引入非确定性），评测结论必须建立在多次采样之上；固定能固定的（seed、模型版本、环境），报告不能固定的（样本数与方差）。
  • —统计显著性：30–50 题样本下，通过率 60% → 70% 的「提升」，95% 置信区间约 ±14 个点、彼此重叠——根本检不出显著差异。工程处理：同题前后配对比较（如 McNemar 检验）比独立比例检验更有功效；先算最小可检测效应再定样本量；关键结论用扩大样本或多次采样确认。不会算就先记住一条：小样本上的个位数点差不构成结论。

上线门槛（生产化前补齐）.

5. 安全、权限与隔离（★★★★★）。 demo 到生产的最大门槛。

  • —心智模型：致命三要素（Lethal Trifecta，Simon Willison）——私有数据访问、不可信内容、对外通道；三者共存才构成致命的 prompt injection 风险，架构上砍掉任意一个就能降级。设计任何 agent 之前先画这三个圈。
  • —层次化防御：权限分级与人工审批（哪些自动执行、哪些必须确认）→ 沙箱隔离（Docker 起步 → gVisor / Firecracker microVM → E2B / Modal / Daytona 类托管沙箱）→ 网络出口白名单 → secrets 管理（注入而非硬编码）。
  • —把一切进入上下文的外部内容当不可信输入：网页、文件、工具返回值里的指令绝不能被当成用户指令执行。截至 2026 年，prompt injection 没有根治方案，架构性防御是唯一解——这也是最保值的职业技能方向之一。
  • —Confused deputy / 权限混淆：agent 是「代理人」——用户、agent、每个工具三者的权限主体必须显式建模。工具 A 返回的内容，不应能间接触发只有用户本人才可授权的工具 B 操作；为每个工具标注「权限属于谁、可被谁的输出触发」，是权限审计的前提，也是致命三要素在工具间的细化版本。
  • —2026 新增注意：社区 skill 自带可执行脚本，未经审计的 skill 就是未经审计的依赖，按开源包的标准审查后再装（供应链攻击面：恶意 MCP server 与恶意 skill 同理）。

6. Harness / 运行时与状态工程（★★★★）。 流式输出、并行工具调用、中断与取消、重试超时、成本预算是基本盘。生产 harness 的真正形态是状态机而非裸循环：任务状态显式建模 → 状态转移 → checkpoint → 恢复 → 续跑；配套概念是 durable execution 与 event sourcing（把每次模型调用与工具调用作为事件持久化，状态可从事件流重建，天然获得可回放与可审计），人工审批本身也是状态机里的一个节点。可参考 Temporal 类 durable execution 引擎与 LangGraph 的图执行语义——不必采用这些框架，但要理解它们真正解决的问题：可靠地执行长流程。同时记住：生产 agent 是一个分布式服务，第 0 部分的幂等 / 队列 / 投递语义在这里兑现（多实例并发、写冲突、任务去重）。

并发正确性三件套——任何副作用都要假设自己会被执行两次：① 幂等键去重（同一逻辑操作只生效一次）；② 先查后写由工具内部完成，别指望模型记得；③ 不可逆动作配补偿路径（git revert 优于物理删除）。

何时不该用 agent（决策框架）：

任务特征用什么
步骤可预先枚举、判定标准确定、失败代价高确定性工作流 / 管道
路径无法预知、需要探索与自适应自由循环的 agent
多数生产系统混合体：工作流做骨架，agent 填充开放式子任务

发布工程：agent 上线后是持续演进的服务——SLO 与降级策略、prompt / harness 的版本管理（与评测集版本对应）、评测集接入 CI 做回归门禁、灰度发布与一键回滚。没有这一层，每次改 prompt 都是在生产上做实验。

2026 元教训：harness 编码的是「模型做不到什么」的假设，而这些假设会随模型进步过期——典型案例：Sonnet 4.5 临近上下文上限会提前草草收尾（context anxiety），当时靠在 harness 里加 context reset 缓解；到下一代模型，这个 workaround 可能就该删了。给你写的每个 workaround 标注前提假设，每季度重新质疑一遍。

7. 人机协作设计 HITL（★★★★）。 何时追问澄清 vs 直接执行、危险操作审批流、进度外显（todo list 展示给用户）、中途接管与纠偏、审批疲劳的权衡（审批点太多等于没有审批）。Agent 产品之间的体验差距很大程度在这里。2026 年的新语境：越来越多使用者是非工程背景（法务、市场也在编排 agent），「结构化意图规格」正在成为他们替代代码级理解的安全带——这是产品设计的新课题。更进一步的视角是 agent 产品工程：信任校准（让用户对能力边界建立正确预期）、失败时的体验设计、首次使用引导——agent 最终是产品，不只是技术栈。

8. 环境工程与可验证反馈（★★★★）。 给 agent 一个能自我验证的环境：测试、编译器、linter、截图比对。项目级上下文文件（CLAUDE.md / AGENTS.md）、可复现的执行环境。再强调一次：反馈回路质量 > prompt 技巧。

9. Observability（★★★★）。 全链路 trace（每次模型调用与工具调用的完整输入输出）、token / 成本 / 延迟统计、会话回放。工具：Langfuse、OpenTelemetry GenAI 语义规范、Braintrust。没有观测就没有阶段 3 的归因。

进阶方向（按需）.

10. 多智能体编排（★★★，趋势↑）。 默认立场依旧是「多数场景单 agent + 好的上下文管理就够」，它不构成上线门槛；但趋势明确向上，需要持续跟进。

  • —单写者原则（2026 军规）：Cognition 在《Multi-Agents: What's Actually Working》（2026-04，对《Don't Build Multi-Agents》的修正）中给出可用多智能体的边界——写保持单线程，其余 agent 只贡献智能不贡献动作（干净上下文的审查者、更强模型的 smart friend、map-reduce-and-manage 的管理者）；无结构 swarm 仍是干扰项。工程落地：git worktree / 独立分支隔离写域，合并由 orchestrator 串行执行。
  • —学习顺序：先精通单 agent → 读《Don't Build Multi-Agents》理解风险 → 读 2026 修正版理解可用窄类 → 再学 Claude Agent SDK 的 subagent 机制（每个子 agent 独立 context window，父级只收结论不收过程）。

11. Memory（★★★）。 从「全行业不成熟」更新为「平台层密集产品化」：API 层 memory tool 与各家托管记忆方案在 2025 底–2026 年陆续落地。原则：会话内上下文管理的优先级仍高于跨会话记忆；优先用平台能力，别急着自建记忆栈；真正难的是写入策略（何时记、记什么、如何过期），不是存储实现。

12. 模型策略与成本工程（★★★★）。

  • —路由：廉价档模型做检索 / 摘要 / 分类，旗舰档做规划 / 编码（用档位相对表述以防过期；2026-07 的对应示例——廉价档如 Haiku 4.5，旗舰档如 Opus 4.8 / Fable 5）；配好 fallback 链路。
  • —thinking budget 的调配；结构化输出约束。
  • —把缓存命中率当一级指标监控——它经常比换模型更能降成本。单位经济学（单任务成本 × 通过率）是付费产品上线评审的硬项。
  • —跨厂商可移植性：单一厂商假设是常见的隐性技术债——compaction、tool calling、缓存在各家语义并不相同。尽早做 provider 抽象层；核心评测集 × 多家模型的回归矩阵进 CI，换模型才不等于重写。
  • —本地与开源支线：数据不能出域或调用量极大时，走自托管路线——vLLM / SGLang 类推理引擎 + 开源模型。随之而来的解码层知识：constrained decoding / grammar 约束保证结构化输出、speculative decoding 降延迟、logprobs 用于置信度估计与重排序。注意生态差异：logprobs 是 OpenAI 生态与开源推理引擎的能力，Claude API 并不暴露 logprobs，跨生态迁移方案时要留意。纯 API 路线的读者可先跳过本条，转自托管时再补。
  • —选型的用户侧功课，书库里有两本对口：《Anthropic · 会员里真正该用的那部分》讲一份 Claude 订阅里覆盖八成场景的那两成能力——知道每一档能干什么，路由才有依据；《Kimi · K3 与一套 agent 栈》则覆盖国内可达、长上下文与双兼容 API 的那条支线，中文长材料与国内部署场景下的现实选项。

13. 数据飞轮（★★★，长期壁垒）。 线上每个失败案例 → 归因分类 → 沉淀为回归评测用例 →（更远期）用于 RL / 微调。前沿实验室已在 agent 轨迹上做强化学习；对个人和小团队，先把「失败 → 用例」的闭环建起来——这条飞轮转起来之后才是真正的护城河。

  • —配套的数据基础设施：轨迹存储（trajectory store）、评测集版本化（数据也要进版本控制，与 harness 版本对应）、人工反馈标注流水线——没有这三件，飞轮只是比喻。
  • —训练侧接口：飞轮远端的具体形态——SFT on traces（把高质量成功轨迹整理成训练数据，质量门槛高于数量）、rejection sampling（多次采样只留判据通过的轨迹）、RLVR（以可验证奖励做强化学习，编码类任务天然适配）、蒸馏路由（把强模型的判断蒸馏到廉价档做分类 / 路由，成本降一个量级）。个人与小团队的现实边界：前两者可及，后两者先攒够 trace 再说。工程参考：Agent Lightning（Microsoft，2025）。

第 2 部分 · 六阶段实战路线.

阶段 0（1–2 周，与全程并行）：用户视角 + 基础补齐.

前置：软件工程基础。目标产出：≥3 个真实任务的分析笔记 + trace 标注。

  • —每天高强度使用 Claude Code（或同级 CLI agent）做真实工作，边用边记录：它何时压缩上下文？todo 怎么维护？失败后怎么恢复？何时向你求助？什么时候派子 agent？想把这份观察做得更系统，书库里的《Claude Code · 终端里的编排台》把它当「指挥并验收一支 agent 队」的编排台来拆：子 agent、MCP、评审循环——正是这一步该记录的机制。
  • —同级形态不止终端：《Cursor · 一台元工具》展示 agentic IDE 的日常工作流——代码之外的调研、写作、数据也能一窗干完，适合把「用户视角」扩展到编码之外。
  • —补齐第 0 部分的缺口；用原始 HTTP 手写一次完整的 tool use 调用。
  • —过关标准：能对着白板给别人讲清 agent loop 每一步的数据流；用 Claude Code 完成 ≥3 个真实任务并产出分析笔记，包含——对其中一次会话的 trace 标注（模型调用边界、tool_use / tool_result 配对、上下文压缩发生点）、一条真实失败任务的过程复盘、一个 harness 设计取舍的剖析并附 trace 证据（哪次会话、哪个环节）。

阶段 1（1–2 周）：零框架手写 agent.

前置：阶段 0。目标产出：真的能修 bug 的最小 agent + 冒烟测试集。

  • —200–300 行：消息循环 + 四个工具（bash、read_file、write_file、edit_file）+ 最简权限确认。
  • —让它真的修掉你某个 repo 里的一个小 bug。目标是肌肉记忆：agent = 模型 + 工具 + 循环，没有魔法。
  • —参考：Anthropic《Building Effective Agents》；mini-swe-agent（约百行却能在 SWE-bench 拿分）。
  • —从现在起维护一个 3–5 个任务的冒烟测试集：每次改动 agent 后复跑一遍。它就是阶段 3 正式评测集的种子——评测习惯从第一行代码开始养，而不是到阶段 3 才补。
  • —过关标准：不手动改它写的任何一行代码，端到端修复 ≥1 个真实 bug；能解释你的 edit 工具为什么这样设计（以及踩了什么坑）；冒烟测试集已建立并至少复跑过一次。

阶段 2（3–5 周）：读源码 + 逐项加能力.

前置：阶段 1。目标产出：具备 ≥6 项能力的 agent + 成本优化数据。

  • —源码阅读（精读 2 + 选读）：精读 mini-swe-agent（Python，最小可用实现）与 Claude Agent SDK（Python / TS，就是 Claude Code 抽成库的工业级 harness：内置工具、权限模式、hooks、subagent，2026 年最值得精读的生产形态）；选读 smolagents（Python）、Aider（Python，只重点看 repo map 实现）、OpenHands（Python）、codex CLI（注意是 Rust）、gemini-cli（TypeScript），对比不同工业级 harness 的取舍。
  • —能力清单（逐项加到自己的 agent 上，每加一项写一篇笔记）：
    1. 01上下文压缩（compaction）
    2. 02todo planning + 复述
    3. 03权限分级与审批
    4. 04checkpoint / 断点续跑
    5. 05子 agent（上下文隔离）
    6. 06Skills 加载（SKILL.md + progressive disclosure）
    7. 07code mode 工具编排
    8. 08prompt caching 优化（实测缓存命中率）
  • —过关标准：你的 agent 具备以上 ≥6 项；同一任务优化前后 token 成本相差 ≥3 倍，且有数据记录。

阶段 3（3–5 周）：评测驱动迭代（分水岭）.

前置：阶段 2。目标产出：完整归因报告 + 一键复跑的正式评测集。

  • —从 SWE-bench Verified 抽 30–50 题（不用 Lite——题目质量问题已是共识）。非编码方向的读者：方法论完全不变，载体可换成 τ-bench 类工具调用基准，或直接用纯自建的域内任务集。
  • —搭 trace 记录（Langfuse 或自建 JSONL 均可），先跑基线。
  • —失败归因：逐条 trace 标注失败类型（上下文丢失 / 工具误用 / 过早放弃 / 验证缺失 / 环境问题）。
  • —针对最大类别做改进 → 复测 pass@1 与 pass^k 变化（多次采样，报告方差）→ 写归因报告。
  • —显著性判定：报告结论前先过统计关——配对比较、置信区间、最小可检测效应（方法见模块 4）；30–50 题上检不出的差异，要么扩样本重测，要么如实写「未检出显著差异」。
  • —同时把阶段 1 起维护的冒烟集扩充为 10–30 个真实任务的正式评测集并做到一键复跑——这个评测集比你的代码更值钱，也是作品集的核心。
  • —过关标准：能出示一份「改动 → 指标变化 → 归因」的完整报告；自建评测集可一键复跑并输出报表。

阶段 4（4–6 周）：生产化专题.

前置：阶段 3。目标产出：他人可独立部署的交付物。

  • —沙箱落地：Docker 起步，按需上 gVisor / 托管沙箱；网络出口白名单；secrets 注入而非硬编码。
  • —注入防御演练：自己构造 ≥5 个 prompt injection 用例（藏在网页 / 文件 / 工具返回值里）攻击自己的 agent，修到全部拦截。
  • —观测接入 + 成本看板；HITL 审批流；发布工程落地：评测集接入 CI 做回归门禁，prompt / harness 变更版本化且可一键回滚。
  • —并发正确性验收：在任意工具调用后直接 kill -9，恢复运行不产生重复副作用——过不去这条，谈不上生产就绪。
  • —合规与数据治理：交付前核对数据驻留与 retention 政策（例：Mythos 级模型要求全流量 30 天保留且 ZDR 不覆盖）、PII 处理、行业要求（如 BAA）、生成代码的 license 归属——「交给他人使用」的交付物绕不开这一页。
  • —选一个方向做深：复刻一个 mini coding agent（最锻炼综合能力），或做垂直 agent（数据分析 / 运维巡检 / 深度调研 / 内容工作流）；也可选异步后台形态（云端沙箱 + 通知与验收流），其工程问题域见第 3 部分。
  • —过关标准：一名未参与开发的测试者仅凭 README 在 2 小时内完成部署并独立跑通 ≥3 个任务（你全程不介入）；在 ≥10 个真实任务上通过率 ≥80%（多次采样取均值）；每次运行 trace 可查看，附单任务 P50 / P95 延迟与成本；附评测集（已接入 CI）、安全说明（致命三要素逐项分析 + 注入用例拦截证据 + 权限分级表 + 合规核对）与部署文档。

阶段 5（长期）：专精赛道任选其一.

coding agent 深耕 ｜ 垂直行业 agent ｜ 异步后台 agent（云端沙箱、repo 预热、通知与验收流——2026 年的主流形态之一）｜ browser & computer use（另一套评测体系：OSWorld、WebArena）｜ 多智能体系统（在单写者原则内做深）｜ agent infra（沙箱、记忆、评测工具本身）。2026 年每条赛道都在招人，优先选「你能天天接触真实任务与真实用户」的那条。

第 3 部分 · 2026–2027 前沿地图与方向判断.

事实与判断分开写。判断可证伪，请用你自己的评测集校准。

已确立的事实（截至 2026 年中；各条均于 2026-07 联网核实，来源随条标注）.

  • —主战场从模型竞赛转向 harness 竞赛：同一个模型，不同 harness 的成绩与体验差距巨大；「脑与手解耦」的托管服务已出现，harness 由平台持续演进。（来源：Anthropic Engineering Blog《Scaling Managed Agents》，2026-04）
  • —Orchestration era 与 delegation gap：开发者约 60% 的工作已借助 AI，但能完全委托的仅 0–20%；弥合这个差距是未来两年最大的工程机会面。（来源：Anthropic《2026 Agentic Coding Trends Report》）
  • —长时程成为常态：小时级自主运行普遍化——报告案例是在约 1250 万行规模的代码库中单次自主运行 7 小时完成一次变更（注意口径：1250 万行是代码库体量而非改动量，具体改动规模与人工介入程度以报告原文为准）；checkpoint、自验证、进度外显是配套刚需。（来源：同上报告）
  • —MCP 走向生产级协议：截至 2026-07，面向无状态传输的规范修订已出候选版本，TS SDK v2 进入 beta，tasks 以扩展形式落地，.well-known 服务发现在推进；「为 agent 的工作流设计，而不是包一层 REST」成为服务端设计共识。协议面不只有工具：client 侧原语（sampling、elicitation、resources / prompts）同样承载真实 agent 交互；跨 agent 协议（如 Google 的 A2A，2025-04 发布）仍处早期。（来源：MCP 官方路线图与 SDK 发布说明；稳定版规范 2025-11-25）
  • —Skills 成为跨产品开放标准：Codex、Copilot、Cursor、Gemini CLI 等数十个产品兼容；社区目录已索引海量 skill，但质量参差——精选 skill 能显著提升通过率（约 +16 个点，二手源间数字略有出入），而低质量的自生成 skill 反而可能拖低通过率（约 −8~−11 个点，二手数据待核）：审计与精选比数量重要，垃圾 skill 同时还是安全隐患。（来源：agentskills.io，标准发布于 2025-12-18；SkillsBench 2026 年分析）
  • —异步 / 后台 agent 成为主流形态之一：交互式 CLI 之外，fire-and-forget 的后台 agent（云端沙箱、repo 预热、scoped secrets、完成后通知与验收流）已产品化——Claude Code 的 web / background 形态与 Devin 类产品同属此列；其特有工程问题（环境快照、验收 UX、「Docker 不总是够」的隔离要求）与本地交互形态显著不同。（来源：Latent Space《The Age of Async Agents》，2026-05）想看这条形态的一个成体系活样本，书库里的《Codex · 跨界面的异步编码 agent》覆盖 CLI/IDE/云/GitHub 四面：沙箱审批、AGENTS.md 与配置、云端并行、exec/SDK/CI、PR 评审——异步与无人值守工程问题的一手材料。
  • —记忆平台化（来源：Anthropic API memory tool 文档及各家托管方案发布）；prompt injection 依旧无根治方案（来源：Simon Willison 的持续追踪与业界共识）。

判断（2027 展望，中低置信度，显式可证伪）.

  1. 01保值技能排序：评测工程 > 上下文 / 成本工程 > 安全 > HITL 产品设计 > 多智能体编排。理由：前三者不依赖任何具体框架或模型代际。
  2. 02框架层继续洗牌；押协议（MCP / Skills）与一手能力，不押具体框架。
  3. 03「会用 agent 的人」将过剩，「能评测并系统性改进 agent 的人」持续稀缺——这是阶段 3 作为分水岭的原因，也是招聘信号的变化方向（面试越来越问「你的 eval 怎么做」，而不是「你用过什么框架」）。
  4. 04多智能体从「别用」走向「何时用 + 怎么用」的工程学；长期记忆可能在 2027 年出现类似 MCP 的标准化尝试（低置信度）。
  5. 05验证与可机器判定的产出会升温——凡是能把「对不对」变成程序化判定的领域，agent 渗透最快。

职业方向指引.

  • —岗位光谱：Agent / AI Engineer（产品团队）｜ Agent Infra（沙箱 / 记忆 / 评测工具）｜ Forward-Deployed / Solutions Engineer（实验室与大客户之间，近两年扩张最快的岗位类型之一）｜ DevRel & Community（需要真实工程可信度打底）｜ AI 安全工程（注入与权限方向缺口大）。
  • —作品集公式：公开 repo（你的 agent）+ 自建评测集与数据 + 3–5 篇深度技术复盘（过程与归因，胜过教程复读）。
  • —若目标含 DevRel / 社区方向：把阶段 1–4 全程 build in public——每个阶段的踩坑记录都是天然内容素材，而工程可信度是社区岗位最稀缺的资产。评测数据 + 亲手复现实验，是内容创作者与「转述者」的分界线。

第 4 部分 · 资源库（2026-07 校准）.

必读（都不长，按序；链接为 2026-07 核实的官方地址）.

  1. 01Anthropic《Building Effective Agents》——一切的起点。
  2. 02Anthropic《Writing Effective Tools for Agents》——工具工程。
  3. 03Anthropic《Effective Context Engineering for AI Agents》——上下文工程官方版。
  4. 04Manus《Context Engineering for AI Agents: Lessons from Building Manus》——KV cache / 文件即记忆 / todo 复述，全是实战干货。
  5. 05Anthropic《Code Execution with MCP》——code mode。
  6. 06Anthropic《Demystifying Evals for AI Agents》（2026-01）——评测方法学官方版：评分器类型、轨迹 vs 结果、judge 校准、评测进 CI。
  7. 07对照阅读三部曲：Cognition《Don't Build Multi-Agents》（2025-06）→ Anthropic《How We Built Our Multi-Agent Research System》（2025-06）→ Cognition《Multi-Agents: What's Actually Working》（2026-04，单写者原则出处）。
  8. 08长时程三部曲：Anthropic《Effective Harnesses for Long-Running Agents》（2025-11-26）、《Harness Design for Long-Running Application Development》（2026-03）、《Scaling Managed Agents》（2026-04）——长时程与「harness 假设会过期」。
  9. 09Claude Code Best Practices；12-Factor Agents（Dex Horthy / HumanLayer）——生产工程守则。
  10. 10论文：ReAct（arxiv.org/abs/2210.03629）、SWE-bench（arxiv.org/abs/2310.06770）、SWE-agent / ACI（arxiv.org/abs/2405.15793）、τ-bench / pass^k（arxiv.org/abs/2406.12045）；训练侧参考 Agent Lightning（Microsoft，2025，arXiv 检索标题）。
  11. 11Anthropic《2026 Agentic Coding Trends Report》——年度趋势坐标系。
  12. 12播客特辑：《The Age of Async Agents》（Latent Space × Cognition Walden Yan，2026-05）——背景 agent 架构实战：harness-in-the-box、repo 预热、scoped secrets、「Docker 不总是够」。

书（可选打底）.

Chip Huyen《AI Engineering》（O'Reilly，2025）——系统性补全 AI 工程全景。

源码.

mini-swe-agent（Python，github.com/SWE-agent/mini-swe-agent）｜ smolagents（Python，github.com/huggingface/smolagents）｜ Aider（Python，github.com/Aider-AI/aider，重点读 repo map）｜ OpenHands（Python，github.com/All-Hands-AI/OpenHands）｜ Claude Agent SDK（Python 包 claude-agent-sdk / TS 包 @anthropic-ai/claude-agent-sdk；github.com/anthropics/claude-agent-sdk-python；文档 code.claude.com/docs/en/agent-sdk/overview）｜ codex CLI（Rust，github.com/openai/codex）｜ gemini-cli（TypeScript，github.com/google-gemini/gemini-cli）

工具与标准.

  • —观测：Langfuse（langfuse.com）、OpenTelemetry GenAI 语义规范（opentelemetry.io）、Braintrust（braintrust.dev）
  • —评测：Inspect（UK AISI，github.com/UKGovernmentBEIS/inspect_ai）、promptfoo（promptfoo.dev）、自建评测 harness
  • —沙箱：Docker / gVisor（gvisor.dev）/ Firecracker（firecracker-microvm.github.io）；托管：E2B（e2b.dev）、Modal（modal.com）、Daytona（daytona.io）
  • —协议与标准：MCP（modelcontextprotocol.io）、Agent Skills（agentskills.io）
  • —确定性与复现：Thinking Machines《Defeating Nondeterminism in LLM Inference》（Horace He，2025；thinkingmachines.ai）

保持前沿的信息流与方法.

  • —一手信源：Anthropic engineering blog 与 release notes、MCP 官方 spec 与 blog、各家 model card。
  • —聚合与解读：Latent Space + AINews、Import AI、Simon Willison（安全方向必读）、TLDR AI、The Batch、Stratechery。
  • —播客：Latent Space、Dwarkesh、The AI Daily Brief、Hard Fork。
  • —社区：Anthropic Discord、r/ClaudeAI、r/LocalLLaMA、Hacker News。
  • —方法比清单重要：每周固定 2–3 小时扫读；每月精读并动手复现 1 篇工程文章的核心结论；每逢重大模型或平台发布，用自建评测集实测，而不是转述他人结论——这既是工程习惯，也是内容创作的护城河。

第 5 部分 · 常见坑与反脆弱原则.

八个常见坑.

  1. 01框架先行：从重型编排框架起手，学到的是框架 API 而不是本质。先裸写，后用框架。
  2. 02无评测优化：「改了感觉变好」= 玄学。先有基线再动手。
  3. 03过早多智能体：单 agent 还没调明白就上编排，债务翻倍。
  4. 04过早自建记忆：跨会话记忆先用平台能力。
  5. 05无视 KV cache 的上下文设计：动态改前缀、工具定义频繁变化，成本静默爆炸。
  6. 06demo 直上生产：无沙箱、无权限分级、无出口白名单。
  7. 07教程地狱：只看不做。本指南每个阶段的过关标准都是「做出来的东西」，不是「看完的清单」。
  8. 08内容只做二手转述（对创作者）：没有一手实验与数据支撑的内容，2026 年已无竞争力。

反脆弱原则（2027 之后依然成立）.

  1. 01学范式与原理，不押注框架版本。
  2. 02一手材料 > 二手解读；官方文档与源码是终审。
  3. 03一切外部结论用自建评测集复核。
  4. 04假设 harness 里每个 workaround 都会过期——标注前提，定期删代码。
  5. 05提升反馈回路质量 > 调 prompt。
  6. 06评测与安全是复利技能，越早开始越值钱。

下一步：本周就可以开始.

不用等「准备好」，三件事今天就能启动：

  1. 01换一种方式用你手里的 agent：从今天起，每次用 Claude Code（或同级工具）做真实工作时，记录它何时压缩上下文、todo 怎么维护、失败后怎么恢复——这就是阶段 0 的全部入口。
  2. 02用原始 HTTP 手走一遍 tool use：不借助任何 SDK，从定义工具的 JSON Schema 到回填 tool_result，完整跑通一轮。做完这一件，你看任何框架都能透视到协议层。
  3. 03建一个 3–5 个任务的冒烟集：从你真实工作里挑任务，写下判定标准。它会一路长成阶段 3 的正式评测集——那份比代码更值钱的资产。

然后按过关制走：每个阶段做出过关标准要求的东西，再进下一阶段。维护上，本文的原理部分（第 0、1、2、5 部分）预计可以安心用到 2027 之后；第 3、4 部分请每季度对照一手信源自行刷新——或者更好：用你自己的评测集，把每个「已确立的事实」重新测一遍。

延伸阅读 · 书库.

正文提到的几本都在我维护的书库（library.aklman.com）里，按本文的使用位置汇总：

书库还在扩（基础原理、知识工作、开发循环、自托管 agent 等主题在陆续成稿），新书目见 library.aklman.com。

附录 · 术语表（速查）.

  • —Agent：模型 + 工具 + 循环，在环境中自主多步完成任务的系统。
  • —Harness：包裹模型的全部运行时工程——循环、工具、上下文管理、权限、恢复策略。
  • —Trajectory / Trace：一次任务执行的完整轨迹（全部模型调用与工具调用的输入输出）。
  • —Tool use / Function calling：模型以结构化方式请求调用外部函数的协议。
  • —ACI（Agent-Computer Interface）：为 agent（而非人类）设计的接口，SWE-agent 论文提出。
  • —MCP（Model Context Protocol）：连接 agent 与外部系统的开放协议，事实标准。
  • —MCP Server / Client：提供工具与资源的服务端 / 接入它的宿主。
  • —Agent Skills：以 SKILL.md 封装「如何做某类事」的可移植方法论包，开放标准见 agentskills.io。
  • —Progressive disclosure：先给摘要、按需展开全文的上下文加载策略。
  • —Code mode：让模型写代码来编排工具，替代逐个链式 tool call。
  • —Context window：模型单次可处理的 token 上限。
  • —KV cache / Prompt caching：复用已计算的前缀注意力状态以降本提速；工程上要求稳定前缀。
  • —Compaction：把历史上下文压缩成摘要以腾出窗口。
  • —Sub-agent：拥有独立上下文窗口的子任务 agent，用于上下文隔离与并行。
  • —Orchestrator-Worker：主 agent 分派、子 agent 执行的多智能体模式。
  • —HITL（Human-in-the-loop）：人工审批 / 接管点的设计。
  • —Sandbox：隔离执行环境（Docker / gVisor / Firecracker / 托管沙箱）。
  • —Prompt injection：不可信内容中的指令劫持 agent 行为；截至 2026 年无根治方案。
  • —致命三要素（Lethal Trifecta）：私有数据 + 不可信内容 + 对外通道同时存在时，注入才致命。
  • —Eval / 评测集：可重复执行、可判定通过与否的任务集合。
  • —pass@k / pass^k：k 次尝试至少一次成功的概率（能力）/ k 次全部成功的概率（可靠性）。
  • —LLM-as-judge：用模型判定输出质量，自身需要校准。
  • —SWE-bench（Verified）：真实 GitHub issue 修复基准；Verified 为人工校验的 500 题子集。
  • —Checkpoint / 断点续跑：持久化中间状态以支持中断恢复。
  • —CLAUDE.md / AGENTS.md：项目级 agent 上下文说明文件。
  • —Computer use：agent 通过截图 + 鼠标键盘操作图形界面的能力方向。
  • —数据飞轮：失败 → 归因 → 评测用例 →（远期）微调的闭环。
  • —Durable execution / Event sourcing：把长流程建模为可持久化、可恢复的状态机；每次调用作为事件落盘，状态可从事件流重建。
  • —Confused deputy（权限混淆）：拥有权限的代理被不可信方诱导滥用其权限；agent 安全的核心攻击模式之一。
  • —Benchmark contamination（基准污染）：评测题目混入训练数据导致分数虚高，公开基准的固有风险。
  • —冒烟测试集（Smoke set）：3–5 个任务的最小回归集，每次改动后复跑，阶段 1 起维护。
  • —单写者原则（Single-writer principle）：多智能体系统中写操作保持单线程，其余 agent 只贡献智能不贡献动作；Cognition 2026 年提出的可用多智能体边界。
  • —发布工程（Release engineering）：SLO、版本管理、评测进 CI、灰度与回滚——把 agent 当持续演进的服务来治理。