什么是 harness：从 AGENTS.md 到 Claude Agent SDK 的完全理论拆解

1. 什么是 harness模型权重之外的一切工程基础设施你可能已经用过 Claude Code、Cursor、Cline 这类工具也听说过 Claude Agent SDK。但当你翻开官方文档会反复撞见一个词harness。它到底是什么为什么 OpenAI 和 Anthropic 都在强调它一句话定义harness 是模型权重之外的一切工程基础设施。模型本身只会根据输入预测下一个 token它不知道你的项目用什么框架、依赖哪个版本、测试怎么跑、代码风格是什么。这些信息不会自动出现在模型脑子里必须由 harness 负责组织、注入、约束和验证。换个类比。模型是一台性能极强的发动机但它没有方向盘、没有仪表盘、没有刹车。harness 就是把这台发动机装进车里、接上油路电路、配上操控系统的全部工程。发动机再好装不进车、接不上线也跑不起来。harness 能做什么它决定了模型能力能被发挥多少。同一个模型harness 做得好agent 能连续完成多步骤任务、自动跑测试、自己发现并修复错误harness 做得差agent 连pip install都跑不了或者反复在同一个错误上打转。它适合谁三类人最需要理解 harness一是正在用 Claude Code 或类似工具做日常开发的工程师二是想基于 Claude Agent SDK 构建自己 agent 产品的开发者三是团队里负责制定 AI 编码规范的人。如果你只是偶尔用聊天窗口问几个问题harness 的概念对你帮助有限但只要你让 agent 碰真实仓库、跑真实命令harness 就是决定成败的关键变量。OpenAI 把工程师在 agent 时代的核心工作概括为三件事设计环境、表达意图、构建反馈循环。这三件事全部属于 harness 范畴。Anthropic 更直接把 Claude Agent SDK 称为通用 agent harness。两家头部实验室在这一点上高度一致模型能力之外harness 是最大的杠杆。接下来我会从理论脉络拆解 harness 的五个子系统给出概念对照表和最小反馈循环伪代码最后用 AGENTS.md 作为切入点给出一份可执行的职责划分检查清单。2. TaoToken 前置为什么需要统一接入层在深入 harness 理论之前先解决一个现实问题你不可能只用一个模型。今天用 Claude 做代码审查明天用 GPT 做文档生成后天可能还要试 Gemini 做多模态理解。每个模型有自己的 API 格式、认证方式、计费规则。如果每个都单独对接你的 harness 里会塞满各种适配代码这本身就违背了 harness 的设计原则——约束而非微操。TaoToken 在这里扮演的角色是统一接入层。它提供 OpenAI 兼容的 API 格式你只需要一套 Base URL 和 Key就能切换不同模型。对于 harness 来说这意味着工具子系统和反馈子系统不需要为每个模型写不同的调用逻辑。具体来说TaoToken 的 API 地址是https://taotoken.net/api兼容 OpenAI 的/v1/chat/completions接口。你在 AGENTS.md 里写的验证命令、在 Claude Agent SDK 里配置的模型调用都可以指向这个统一入口。为什么这对 harness 理论很重要因为 harness 的核心矛盾是你要给 agent 足够的自由度去完成任务同时又要用可执行的规则约束它不跑偏。如果接入层本身就很复杂你不得不在 AGENTS.md 里写大量怎么调 API的说明这就变成了微操而不是约束。统一接入层让 harness 的指令子系统可以专注于表达意图而不是解释基础设施。你可以在 AGENTS.md 里写用 Claude 做代码审查用 GPT 做文档生成而不需要写Claude 的 API 格式是 XGPT 的是 Y。如果你还没有 Key可以到 TaoToken API Keys 创建一个。创建后你会得到一个以sk-开头的字符串这就是你的统一凭证。对于长期做 agent 开发的场景建议了解一下 Coding Plan它针对高频编码场景做了额度优化。如果你只是想先验证模型效果可以直接用 模型对话 快速测试。接入层就绪后我们回到 harness 本身。下面进入五子系统模型的理论拆解。3. 可复制配置五子系统模型与最小反馈循环Harness 的理论框架可以拆成五个子系统。这五个子系统缺一个agent 用起来就会别扭。下面逐个拆解并给出可复制的配置片段。3.1 指令子系统AGENTS.md 是目录页不是百科全书指令子系统的核心文件是AGENTS.mdClaude Code 里叫CLAUDE.md逻辑相同。它的作用是告诉 agent这个项目是什么、用什么技术栈、怎么跑起来、有哪些硬约束。关键原则给地图不给说明书。OpenAI 的经验是 AGENTS.md 应该是目录页100 行左右就够了。放不下的内容拆分到docs/目录让 agent 按需去读。一个可复制的 AGENTS.md 模板# 项目概览 这是一个 FastAPI 后端服务提供用户认证和订单管理接口。 # 技术栈 - Python 3.11 - FastAPI 0.104 - PostgreSQL 15 - SQLAlchemy 2.0 # 首次运行 bash python -m venv .venv source .venv/bin/activate pip install -e .[dev] cp .env.example .env alembic upgrade head硬约束禁止直接修改alembic/versions/下的迁移文件所有 API 路由必须放在app/api/下数据库操作必须通过app/crud/层禁止在路由里直接写 SQL验证命令测试pytest tests/ -x类型检查mypy src/ --strictLintruff check src/完整验证make check详细文档API 设计规范docs/api-design.md数据库迁移流程docs/migration.md注意最后一部分指向更详细文档的链接。这就是给地图的含义——agent 知道去哪里找细节而不是把所有细节塞进一个文件。 ### 3.2 工具子系统最小权限但别把 shell 禁了 工具子系统决定 agent 能用哪些工具。常见错误是因为安全考虑把 shell 禁了结果 agent 连 pip install 都跑不了。另一个极端是什么都开放agent 可以随意删库。 正确做法是**最小权限原则**给完成任务必需的工具不多给。在 Claude Agent SDK 里你可以通过 allowed_tools 参数控制 python from claude_agent_sdk import ClaudeAgent agent ClaudeAgent( modelclaude-sonnet-4-20250514, allowed_tools[read_file, write_file, run_command, search], working_directory/path/to/project )如果你用 TaoToken 作为统一接入层模型调用部分可以这样配置import os os.environ[OPENAI_API_BASE] https://taotoken.net/api os.environ[OPENAI_API_KEY] sk-your-key-here这样工具子系统里的模型调用就走统一入口不需要为每个模型写不同的适配代码。3.3 环境子系统让环境状态自描述环境子系统的目标是可重现。agent 在新会话里应该能自己搞清楚依赖是什么版本、运行时是什么版本、怎么启动。关键文件pyproject.toml或package.json锁定依赖.nvmrc或.python-version指定运行时版本Dockerfile或devcontainer.json让环境可重现一个最小devcontainer.json示例{ name: project-dev, image: mcr.microsoft.com/devcontainers/python:3.11, postCreateCommand: pip install -e .[dev], customizations: { vscode: { extensions: [ms-python.python, charliermarsh.ruff] } } }环境自描述的好处是agent 不需要你告诉它用 Python 3.11它自己读.python-version就知道了。3.4 状态子系统长任务必须有进度跟踪长任务最容易出的问题是agent 做到一半断了下一个会话不知道做到哪了。解决方案很简单用一个PROGRESS.md文件记录状态。# 进度跟踪 ## 已完成 - [x] 用户认证接口 - [x] 订单创建接口 ## 进行中 - [ ] 订单查询接口分页逻辑待完善 ## 被阻塞 - [ ] 支付回调等待第三方沙箱环境 ## 下次会话起点 从 app/api/orders.py 的 list_orders 函数开始补充分页参数校验。每个会话结束前更新下一个会话开始时读取。这个习惯能极大减少 agent 的重复劳动。3.5 反馈子系统投入产出比最高反馈子系统是五个里面投入最少、回报最高的。核心就一件事在 AGENTS.md 里显式列出验证命令。# 验证命令 - 测试pytest tests/ -x - 类型检查mypy src/ --strict - Lintruff check src/ - 完整验证make checkAgent 跑完代码后自己执行这些命令根据输出判断是否通过。这比你在对话里反复说记得跑测试有效得多。Anthropic 发现 agent 会自信地夸赞自己的工作解决方案是把干活的人和检查的人分开。在 harness 里这意味着反馈子系统应该独立于指令子系统——验证命令是客观的不依赖 agent 的自我评价。3.6 最小反馈循环伪代码把五个子系统串起来最小反馈循环的伪代码是这样的def agent_loop(task, max_iterations10): context load_agents_md() # 指令子系统 context load_progress_md() # 状态子系统 tools get_allowed_tools() # 工具子系统 env load_environment() # 环境子系统 for i in range(max_iterations): action model.decide(task, context, tools) result execute(action, env) context result verification run_verification() # 反馈子系统 if verification.passed: update_progress_md(task, done) return success else: context verification.errors update_progress_md(task, blocked) return max_iterations_reached这个循环里模型只负责decide这一步其余全部是 harness 的职责。这就是 harness 和 agent 的边界agent 是决策者harness 是决策所需的一切支撑。4. 验证请求用 AGENTS.md 检查 harness 职责划分理论讲完了怎么验证你的 harness 是否合格我整理了一份检查清单你可以逐条对照。4.1 指令子系统检查打开你的 AGENTS.md问自己项目概览是否在 3 句话以内说清楚技术栈是否包含具体版本号首次运行命令是否可以直接复制粘贴执行硬约束是否用禁止/必须这类可执行的词而不是尽量/最好是否指向了更详细的文档而不是把所有内容塞在一个文件里如果 AGENTS.md 超过 150 行大概率是百科全书而不是目录页需要拆分。4.2 工具子系统检查Agent 能否执行pip install或npm installAgent 能否运行测试命令Agent 是否有文件读写权限是否禁用了不必要的危险工具如直接操作生产数据库一个快速验证方法让 agent 执行安装依赖并跑一次测试看它是否能完成。如果卡在权限上说明工具子系统配置有问题。4.3 环境子系统检查新开一个终端能否在不看文档的情况下知道用什么 Python/Node 版本依赖是否锁定在pyproject.toml或package.json里是否有 Docker 或 devcontainer 配置验证方法删掉本地虚拟环境让 agent 从零开始搭建环境。如果它能自己完成说明环境子系统合格。4.4 状态子系统检查是否有 PROGRESS.md 或类似文件上次会话结束时的状态是否被记录下次会话开始时agent 是否能自己读取状态验证方法让 agent 做一个多步骤任务中途中断新开会话问它上次做到哪了。如果它能准确回答说明状态子系统有效。4.5 反馈子系统检查AGENTS.md 里是否列出了明确的验证命令这些命令是否可以直接执行不需要额外参数Agent 完成任务后是否会主动运行验证命令验证方法故意让 agent 写一段有类型错误的代码看它是否能通过mypy自己发现。4.6 概念对照表概念定义在 harness 中的位置对应文件/配置Agent决策者根据上下文选择动作被 harness 支撑模型本身Harness模型权重之外的一切工程基础设施整体框架AGENTS.md 工具 环境 状态 反馈指令子系统表达意图和约束五子系统之一AGENTS.md / CLAUDE.md工具子系统提供可执行能力五子系统之一allowed_tools 配置环境子系统保证可重现五子系统之一pyproject.toml / devcontainer状态子系统跟踪长任务进度五子系统之一PROGRESS.md反馈子系统验证结果正确性五子系统之一验证命令列表反馈循环agent 决策→执行→验证→修正harness 的运行机制agent_loop 伪代码这张表的核心信息是agent 只是决策者harness 是决策所需的一切支撑。两者边界清晰不要混淆。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth配置 harness 时最容易撞上的几类报错这里逐个拆解。5.1 401 Unauthorized报错原文Error: 401 Unauthorized - Invalid API key provided原因Key 不对、过期、或者 Base URL 配错了。排查步骤检查环境变量OPENAI_API_KEY是否以sk-开头检查OPENAI_API_BASE是否指向https://taotoken.net/api如果用的是 Claude Agent SDK检查ANTHROPIC_API_KEY和ANTHROPIC_BASE_URL是否配对一个常见坑在.env文件里写了 Key但 agent 运行时没有加载.env。解决方法是显式source .env或在代码里用python-dotenv加载。5.2 local proxy failed报错原文Error: local proxy failed to start: address already in use原因端口被占用通常是上一次 agent 会话没有正常退出。排查步骤找到占用端口的进程lsof -i :8080杀掉残留进程kill -9 PID或者换一个端口启动这个错误在 Claude Code 里比较常见因为 Claude Code 会在本地起一个代理进程。如果你同时开了多个会话端口冲突就不可避免。5.3 reading choices 相关报错报错原文Error: reading choices - Cannot read properties of undefined原因API 返回格式不符合预期。通常是 Base URL 配错了或者模型名称写错了。排查步骤用 curl 直接测试 APIcurl https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer sk-your-key \ -H Content-Type: application/json \ -d {model:claude-sonnet-4-20250514,messages:[{role:user,content:hi}]}如果 curl 正常但 agent 报错检查 agent 配置里的model字段是否和 API 支持的模型名一致检查是否有中间层修改了响应格式5.4 OAuth 相关报错报错原文Error: OAuth token expired或Error: invalid_grant原因如果你用的是 Claude Code 的 OAuth 登录方式token 过期后需要重新登录。排查步骤运行claude logout然后claude login重新认证如果用的是 API Key 方式检查是否误开了 OAuth 模式在 CI/CD 环境里建议直接用 API Key 而不是 OAuth5.5 CC Switch / Cline MCP / Codex auth.json 三件套如果你在用 CC Switch 切换不同模型或者在 Cline 里配置 MCP或者用 Codex 的auth.json记住三件套必须完整Base URLhttps://taotoken.net/apiKeysk-开头的字符串Model ID具体模型名称如claude-sonnet-4-20250514缺任何一个都会报错。特别是 Model ID很多人只配了 Base URL 和 Key忘了指定模型结果 agent 用默认模型跑效果不对。Codex 的auth.json示例{ api_base: https://taotoken.net/api, api_key: sk-your-key-here, model: claude-sonnet-4-20250514 }Cline 的 MCP 配置里同样需要这三项。CC Switch 切换时确保每个 profile 都包含完整三件套。6. 语义一致 CTA把 harness 理论落到你的项目里Harness 的理论框架到这里就拆完了。回到最开始的定义harness 是模型权重之外的一切工程基础设施它由指令、工具、环境、状态、反馈五个子系统组成缺一不可。如果你想立刻动手验证建议从反馈子系统开始——这是投入产出比最高的部分。打开你的项目在 AGENTS.md 里加上验证命令列表然后让 agent 跑一次任务看它是否能自己发现错误。如果你需要统一接入多个模型来测试不同 harness 配置的效果可以到 TaoToken API Keys 创建一个 KeyBase URL 用https://taotoken.net/api。接入文档在 TaoToken 文档里面有各语言 SDK 的配置示例。想先快速验证模型效果直接用 模型对话 测试。长期做 agent 开发的话Coding Plan 针对高频编码场景做了优化。最后提醒一点harness 和代码一样会腐化。今天有效的 AGENTS.md三个月后可能因为技术栈升级而失效。定期审计你的五个子系统像还技术债一样还 harness 债。用控制变量排除法逐个移除子系统看哪个移除后性能下降最多——下降最多的那个就是当前最值得加强的。但记住这个实验回答的是当前哪个组件最有价值真正定位瓶颈还要靠失败记录和归因。