模型 vs 骨架：为什么 Harness 决定上限
同一个模型，不同的智能体骨架（harness/scaffold），在真实任务上的表现可以相差数倍。本文用 SWE-bench 上的硬数据论证：在模型能力相同时，harness 是智能体能力的主要变量，并讨论模型进步如何反过来改写 harness 设计。
外观
Skip to content✨ 推荐 ✨ 推荐 ✨ 推荐 ✨ 推荐 ✨ 推荐 ✨ 推荐 ✨ 推荐 ✨ 推荐 ✨ 推荐 ✨ 推荐
AGENT HARNESS HANDBOOK
Agent Harness 手册
模型之外，让智能体真正干活的那套系统 —— 智能体循环 · 上下文工程 · 工具系统 · 记忆 · 子代理 · 安全边界
从哪条路开始
40+ 篇内容不是要你通读的图书馆，而是可以按需组合的路线图
✨ 编辑推荐
只读十篇的话，读这些
01020304050607080910
🧭 什么是 Agent Harness
Agent Harness（智能体挽具）是包裹 LLM 的完整系统：上下文、工具、循环、记忆与护栏。本文给出精确定义、词源考据、与 model/agent/framework/scaffolding/wrapper 的辨析，以及 harness 决定 agent 能力上限的实证。
导读🧭 学习路径：三条路线
本站 40 余页内容不是要你通读的图书馆，而是可以按需组合的路线图：为三个月内要面试的人准备求职冲刺线，为想打牢底子的人准备六周系统转兵线，为在职建造者准备「问题 → 页面」的案头速查索引。
导读🧭 总体架构解剖
一张图看懂 Agent Harness 的总体架构：用户、环境、智能体循环、八大组件与 LLM 的关系，附完整数据流走查与分角色阅读导航。
导读⚙️ 上下文工程
上下文是 agent 最稀缺的资源，harness 的核心职责是决定每个 step 模型看到什么：解剖上下文的真实构成、poisoning/distraction/confusion/clash 四种失效模式、压缩与截断策略、KV cache 命中率的工程考量，以及 RAG 与 just-in-time 检索的取舍。
核心组件⚙️ 智能体循环（Agent Loop）
Agent Loop 是 Harness 的心脏：一个 while 循环如何组装上下文、调用模型、执行工具、处理错误并决定何时停止——从 ReAct 论文到生产级实现的完整拆解。
核心组件🔍 Claude Code 案例
深度剖析 Claude Code 的 harness 设计：极简 Unix 风格工具集、TodoWrite 与 plan mode 的规划机制、CLAUDE.md 记忆文件、子代理、hooks、MCP 与权限模式，以及它为什么选择终端而非 IDE——本站组件框架在一个真实产品里的完整组合。
经典案例📄 经典论文精读
精读 7 篇塑造 Agent Harness 设计范式的经典论文：ReAct、MRKL、Toolformer、Reflexion、Generative Agents、Voyager、SWE-agent，讲透机制、数据与对系统设计的启示。
论文精读🛠️ 从零构建一个最小 Harness
用一个约 130 行、无需框架的 Python 文件从零实现最小 agent harness：上下文组装、模型调用、工具解析与执行、结果回写、人工审批五个环节逐一拆解，再沿"什么症状加什么组件"的路径把 todo 规划、记忆压缩、子代理、观测逐个挂载上去。
实践指南💼 JD 清单：国内外大厂在招岗位
2026 年 8 月国内外 22 家公司 44 个 Agent/LLM 工程在招岗位完整清单：官方全文、官方标题级、聚合站快照三级来源标注，附总览速查表与失效免责说明。
求职与JD📚 精选资源清单
一份策展式而非罗列式的 Agent Harness 阅读地图：只收录一手、有立场的工程博客、开源实现、协议规范与论文入口，每条都注明为什么值得读、什么时候读。
资源全站内容
按模块浏览，或直接搜索
什么是 Agent Harness
Agent Harness（智能体挽具）是包裹 LLM 的完整系统：上下文、工具、循环、记忆与护栏。本文给出精确定义、词源考据、与 model/agent/framework/scaffolding/wrapper 的辨析，以及 harness 决定 agent 能力上限的实证。
学习路径：三条路线
本站 40 余页内容不是要你通读的图书馆，而是可以按需组合的路线图：为三个月内要面试的人准备求职冲刺线，为想打牢底子的人准备六周系统转兵线，为在职建造者准备「问题 → 页面」的案头速查索引。
演进简史
从 2022 年 ReAct 与 Toolformer 到 2026 年的 harness 话语：梳理智能体骨架五年演化中的每个关键转折点——当时大家以为的解法，以及后来被证伪或证实的东西。
总体架构解剖
一张图看懂 Agent Harness 的总体架构：用户、环境、智能体循环、八大组件与 LLM 的关系，附完整数据流走查与分角色阅读导航。
工具系统与 MCP
工具是模型与环境之间的界面，也是 harness 设计中最被低估的部分：本文拆解什么该做成工具、schema 与返回结果如何塑造模型行为、工具数量的选择困难、MCP 协议的价值与局限、computer use 类通用工具的取舍，以及 TodoWrite 式纯提示工具的特殊形态。
规划与任务分解
深入解析 AI Agent 的规划机制：无规划、Plan-and-Execute、规划-执行交织三种模式的对比，Todo List 作为显式工作记忆的实现原理，以及推理模型时代显式规划是否仍然必要。
记忆系统
拆解 Agent Harness 的记忆系统：三层记忆模型、记忆文件模式的兴起、写入时机与遗忘策略、记忆与 RAG 的分工，以及 Claude Code、ChatGPT、Letta 三种代表性实现。
技能与知识注入
Agent 获取领域知识的三种途径——静态注入（系统提示与规则文件）、动态检索（RAG）、能力包（Agent Skills），详解 Anthropic 的渐进式披露设计、规则优先级与冲突解决，以及何时该用哪种方式。
模型选型与成本工程
给哪个步骤配哪个模型，是 harness 里直接影响能力与账单的设计决策：旗舰与小模型的能力/价格/延迟三维权衡、规则路由/级联/学习型路由器三种模式、fallback 与重试纪律、prompt 缓存与批处理等成本旋钮，以及"换模型必须跑回归"的评测纪律。
评测与可观测性
为什么 agent 评测难、轨迹记录与回放、主流 benchmark（SWE-bench、Terminal-Bench、τ-bench、WebArena/WorkArena）、LLM-as-judge 的用法与偏差，以及如何建立 evals 驱动的 harness 迭代工作流。
权限、安全与人类在环
深入解析 Agent Harness 的信任机制：权限模式从全人工审批到 yolo 的谱系、Claude Code 的四级模式与 hooks 护栏、文件系统与网络双重沙箱、prompt injection 与 lethal trifecta 的威胁模型，以及人类在环闸口与读写工具分离的设计原则。
上下文工程
上下文是 agent 最稀缺的资源，harness 的核心职责是决定每个 step 模型看到什么：解剖上下文的真实构成、poisoning/distraction/confusion/clash 四种失效模式、压缩与截断策略、KV cache 命中率的工程考量，以及 RAG 与 just-in-time 检索的取舍。
智能体循环（Agent Loop）
Agent Loop 是 Harness 的心脏：一个 while 循环如何组装上下文、调用模型、执行工具、处理错误并决定何时停止——从 ReAct 论文到生产级实现的完整拆解。
子代理与多智能体编排
子代理的本质是上下文隔离与并行化，而不是"多个 AI 开会"。本文拆解 Claude Code 的委托-摘要机制、Anthropic 多智能体研究系统的 orchestrator-worker 架构与实测数据、Cognition《Don't Build Multi-Agents》的反方论证，并给出单线程强 agent 与多智能体之间的决策框架。
案例：扣子（Coze）
拆解字节跳动扣子的 harness 设计——把循环、工具、记忆、规划、子代理全部做成可视化产品功能的「平台型」路线，与 Claude Code 的 CLI 原语型构成设计空间的两极，以及低代码 harness 的能力天花板在哪里。
案例：Aider
Aider 是最适合研究 harness 细节的开源 CLI 结对编程 agent——它的编辑格式（edit format）取舍、tree-sitter repo map、lint/test 反馈环和 git 深度集成，每一项都有可核查的 benchmark 数据支撑。
案例：Codex
Codex 不是「模型直接给答案」，而是一个由 Harness 驱动的闭环系统——本文逐步拆解它交互时每一步的原理与产出，画出 Harness 与 LLM 之间最清晰的一条责任边界。
案例：Dify
拆解 Dify 的 harness 设计——把 agent 循环、RAG 管线、工具插件与模型适配层做成「可自托管的中间件」，以及它在 LangGraph（代码框架）与扣子（托管 SaaS）之间的谱系位置。
案例：LangGraph
深入拆解 LangGraph 的 harness 设计——用状态图显式建模 agent 控制流的「框架派」思路，与 Claude Code 式自由 loop 的哲学对比，以及什么时候该用框架、什么时候该手写循环。
案例：OpenHands
深入剖析开源 agent 平台 OpenHands（原 OpenDevin）的 harness 架构：事件流、Docker 沙箱运行时、CodeAct 统一动作空间、microagent 与可插拔设计，以及它作为「harness 实验平台」的学术价值。
案例：SWE-agent
普林斯顿团队的 SWE-agent 是"harness 设计即研究"的典范：它提出 Agent-Computer Interface（ACI）概念，用为语言模型专门设计的命令与反馈格式，在 SWE-bench 上取得了远超非交互式基线的成绩。
Claude Code 案例
深度剖析 Claude Code 的 harness 设计：极简 Unix 风格工具集、TodoWrite 与 plan mode 的规划机制、CLAUDE.md 记忆文件、子代理、hooks、MCP 与权限模式，以及它为什么选择终端而非 IDE——本站组件框架在一个真实产品里的完整组合。
Cursor 案例
剖析 IDE 系 agent 的 harness 设计：Cursor 如何用 Merkle 树索引与 embedding 检索供给大规模代码库上下文、用 IDE 独有的编辑器状态喂养模型、用专门训练的 apply 模型解决"改对代码"这个工程问题，以及 Tab 补全与 agent 模式如何在同一套 harness 里分工。
Devin 案例
剖析"全自主软件工程师"Devin 的 harness：shell/浏览器/编辑器/规划器组合的长时程架构、2024 年发布时的演示与打假争议、Cognition 工程博客中关于 context engineering 与模型选型的一手经验，以及"自主性 vs 可控性"这条产品化光谱上最激进的一次押注。
Manus 案例
剖析"通用 AI 智能体"Manus 的 harness：每个任务一台云端虚拟机的隔离执行架构、团队公开的上下文工程六条经验与其背后的成本逻辑、Wide Research 的百 agent 并行实验，以及从病毒式发布到 Meta 收购再被中国监管叫停的完整弧线——一个 harness-first 团队如何用上下文工程对抗模型同质化。
从这里开始
论文精读栏目入口：按你的目标选择阅读路径，或直接进入论文地图、经典精读与前沿进展。
经典论文精读
精读 7 篇塑造 Agent Harness 设计范式的经典论文：ReAct、MRKL、Toolformer、Reflexion、Generative Agents、Voyager、SWE-agent，讲透机制、数据与对系统设计的启示。
论文地图
Agent Harness 相关研究的学术地图：按主题分组的代表论文、范式迁移时间轴，帮助判断一篇新论文落在哪个坐标上。
前沿进展
梳理 2025–2026 年 Agent Harness 研究的七条前沿主线：长时程执行、上下文工程、记忆基础设施、多智能体协作、自我改进 agent、训练内生化与评测纪律，逐篇标注问题、方法与对 harness 设计的启示。
阅读纪律与 FAQ
读 Agent Harness 论文时的常见问题：成功率数字能否横向比较、Reflexion 91% 的前提条件、怎么读一篇基准论文。
阅读路径
面向三类读者的论文阅读顺序：4 小时快速入门、2 周深入研究、1 周工程落地，每条路径标注读什么、为什么、读完回到哪里。
常见陷阱与反模式
Agent Harness 开发中的十个高频反模式：过度框架化、工具爆炸、上下文垃圾堆积、无终止条件、静默失败、过度自动化、Prompt 银弹、Demo 驱动开发、忽视成本与延迟、过早多智能体化——每条附症状、根因与解药。
从零搭一套 Agent 评测
动手搭建 agent 评测的完整路径：单元级、轨迹级、结果级三层评测各自断言什么，评测数据集如何从真实失败回流、为什么 20 条就够起步，程序化断言与 LLM-as-judge 的分工边界，以及如何接入 CI 做回归并在成本与抽样之间做权衡——最后给 mini_harness 配上一个最小评测脚本。
从零构建一个最小 Harness
用一个约 130 行、无需框架的 Python 文件从零实现最小 agent harness：上下文组装、模型调用、工具解析与执行、结果回写、人工审批五个环节逐一拆解，再沿"什么症状加什么组件"的路径把 todo 规划、记忆压缩、子代理、观测逐个挂载上去。
渐进式教程：三版跑起来
把一个 130 行的最小 harness 拆成三个可独立运行的版本：v1 只有 agent loop 骨架，v2 挂上工具注册表、输出截断与审批闸口，v3 再补 todo 规划与会话摘要压缩——每版都能直接跑，每个组件都有它对应的可观察症状。
框架与平台怎么选
做 agent 该选哪个底座？本文把「自己写循环、代码框架、平台」摆成一条光谱，横评 LangGraph、CrewAI、AutoGen、OpenAI Agents SDK、Claude Agent SDK、Dify、扣子的抽象层级、控制权与锁入风险，并按场景给出决策树。
写好 CLAUDE.md / AGENTS.md
讲透「给 agent 看的配置文件」：它的本质是持久化的提示层而非强制配置，写什么不写什么、为什么越短越有效、如何分层组织与团队共享，以及它与 skills、hooks 的分工——附一份可直接套用的模板。
作品集项目：三个能写进简历的 Agent 项目
为求职转型的工程师设计三个难度递进的 Agent 作品集项目：带评测体系的 mini harness、生产级 MCP server、多智能体/长时程任务 agent——每个项目标注覆盖的 JD 高频要求、技术要点、验收标准与 STAR 简历写法，附低配/完整两档投入估算。
Harness 设计原则
提炼自 Anthropic、Cognition、12-Factor Agents 与主流编码 Agent 实践的可操作 Harness 设计原则，每条附理由与正反例。
面试题库：Agent/LLM 工程岗怎么考
基于 44 份真实在招 JD 的高频要求归纳出的 10 道 Agent Harness 系统设计题：每题附考察点、好答案骨架与踩坑回答，并逐一映射回手册对应章节。
能力对标：简历该突出什么
从 44 份真实在招 JD 反推 Agent 工程岗的能力模型：七项核心能力的 JD 证据、简历好差写法对比、面试考点，三类候选人画像的对标分析与补课路径，附逐条自查清单。
求职与 JD 分析
从 2026 年 8 月国内外 22 家公司 44 个真实在招岗位 JD 反推 Agent Harness 学习路径：岗位版图、技能需求全景、以及"Agent Harness 工程师"成为正式岗位名这一行业信号。
JD 清单：国内外大厂在招岗位
2026 年 8 月国内外 22 家公司 44 个 Agent/LLM 工程在招岗位完整清单：官方全文、官方标题级、聚合站快照三级来源标注，附总览速查表与失效免责说明。
JD 知识点拆解：大厂到底在考什么
基于 44 个国内外真实在招 Agent/LLM 工程岗 JD 的词频统计，拆解高频知识点与国内外的考察差异，并把每个知识点逐一映射回本手册的对应章节，给出「掌握到什么程度算够」的标尺。
学习论坛
Agent Harness 手册的站内圈子：单一信息流随手发言，可选
精选资源清单
一份策展式而非罗列式的 Agent Harness 阅读地图：只收录一手、有立场的工程博客、开源实现、协议规范与论文入口，每条都注明为什么值得读、什么时候读。
术语表
Agent Harness 领域核心术语表：智能体、挽具、上下文工程、工具、记忆、安全与评测等 50+ 术语的准确定义与辨析。
系统提示词档案
一份带评注的系统提示词逆向档案：收录 Claude Code、Cursor、Devin、Manus、v0、Perplexity 六款产品的公开逆向材料，逐条标注可信度，并用 harness 组件框架拆解每份提示词背后的设计取舍。