1. 为什么你的 Agent 总是“跑偏”从一次失败的任务说起如果你最近在折腾 AI Agent大概率遇到过这种场景你给 Agent 一句“帮我把这个项目的类型错误修一下”它信心满满地开始改代码改完告诉你“已完成”。你跑一下pnpm typecheck红了一片。再让它修它换了个地方又改错了。来回几轮你发现它根本没读项目规范也不知道自己该在哪个目录里动手。这不是模型不够聪明而是缺少一套“缰绳”。业界把围绕 Agent 构建的这套执行控制、评测与迭代体系叫做harness可以理解为“夹具”或“挽具”。它源自传统软件工程里的 Test Harness指的是在受控且可观测的环境中运行测试的脚本、Mock 和基础设施集合。放到 AI Agent 场景里harness 就是让模型从“会聊天”变成“能干活”的那层工程骨架。这篇内容聚焦 AI Agent 工程化落地以 harness 为线索把AGENTS.md和沙箱这两块最容易混淆的边界讲清楚。我会给出一份可以直接复制的 AGENTS.md 骨架、一段 Docker 沙箱配置以及一套验证动作让你在本地跑通一次 Agent 任务并亲眼看到“有 harness”和“没 harness”的行为差异。适合已经用过 Claude Code、Cursor、Codex 这类工具但总觉得 Agent 不够稳的开发者。2. 先搞清楚 harness 的边界AGENTS.md 管什么沙箱管什么很多人把 AGENTS.md 当成一个“更长的 system prompt”把沙箱当成“跑代码的地方”结果两边职责糊在一起Agent 一遇到报错就乱猜。我试过把这两者的边界画成一张表思路会清晰很多。维度AGENTS.md沙箱Sandbox本质机器可读的规则与错题本受控的执行环境管什么做什么、不做什么、怎么算完成在哪跑、能碰什么、跑完怎么反馈典型内容架构规范、Hard Stops、Definition of Done依赖锁定、网络限制、文件系统权限失败表现Agent 改错方向、过早宣布完成Agent 污染宿主环境、命令执行失败无反馈更新频率每次踩坑后追加依赖或安全策略变化时调整一句话概括AGENTS.md 是“宪法”沙箱是“无菌手术室”。宪法告诉 Agent 什么能做、什么绝对不能碰、做到什么程度才算完手术室保证它即使执行了高危命令也不会把宿主环境搞坏同时把执行结果结构化地反馈回来。harness 的核心公式可以写成Agent Model Harness。模型提供原始智能harness 负责把这份智能约束成可靠、可重复、可门禁的产出。所以判断一个工程是不是 harness engineering不看它用了什么框架而看它的“控制面”是否成立规则是否机器可读、约束是否机械可执行、反馈是否闭环。3. 前置准备用 TaoToken 拿到可用的模型接入在写 AGENTS.md 之前得先让 Agent 能稳定调用模型。我本地用的是 TaoToken 的接入方式它兼容 Anthropic 风格的接口配置起来比较直接。先去控制台创建一个 API Key地址是https://taotoken.net/api-keys。创建后复制那串 key后面配置环境变量要用。如果你还没决定用哪个模型可以先到模型对话页面https://taotoken.net/chat试几句确认响应正常再接入到 Agent 里。拿到 key 之后在项目根目录建一个.env文件记得加进.gitignore# .env TAOTOKEN_API_KEYsk-你的key TAOTOKEN_BASE_URLhttps://taotoken.net/api如果你用的是 Claude Code 这类工具它读取的是ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY可以这样映射export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEY$TAOTOKEN_API_KEY这里有个坑要注意base url 末尾不要多加/v1不同客户端对路径拼接的处理不一样多写一层容易出现 404。接入文档在https://taotoken.net/doc遇到路径问题先去那里核对。4. 可复制的 AGENTS.md 骨架把规则写成机器能读的形式下面这份骨架是我在几个小项目里迭代出来的核心思路是把“完成定义”和“禁止操作”放在最显眼的位置把验证命令固化成可执行的一行。Agent 每次开工前读它收工前对照它。# AGENTS.md ## 项目说明 这是一个 TypeScript Node 的后端服务包管理用 pnpm。 目录分层types → config → repo → service → runtime → ui依赖只能从右往左。 ## 完成定义Definition of Done 任务只有在以下命令全部退出码为 0 时才算完成 bash pnpm typecheck pnpm lint pnpm test pnpm build退出码不为 0禁止宣布任务完成。禁止操作Hard Stops禁止直接修改src/runtime和src/ui之外的数据库访问代码。禁止跳过测试直接提交。禁止修改pnpm-lock.yaml除非明确要求升级依赖。禁止在未读取 PROGRESS.md 的情况下开始新任务。工作流新会话第一件事读取 PROGRESS.md了解已完成、进行中、待办、已知问题。修改代码前先说明你打算改哪些文件、为什么。修改后立即运行对应的校验命令见下方路由表。任务完成或中断时回写 PROGRESS.md。校验路由改了类型定义 →pnpm typecheck改了业务逻辑 →pnpm test改了依赖 →pnpm install --frozen-lockfile pnpm build不确定 → 跑完整 DoD 命令上下文警戒当上下文使用率接近 40% 时停止当前动作把状态结构化写入 PROGRESS.md 然后建议开启一个干净会话继续。配套的 PROGRESS.md 可以很简单 markdown # PROGRESS ## 已完成 - 用户登录接口的类型定义 ## 进行中 - 登录接口的单元测试 ## 待办 - 补充错误码映射 ## 已知问题 - repo 层有个查询没加索引暂不影响测试这份骨架的关键不在内容多而在可执行。DoD 那一行命令是硬门槛Agent 没法用“我觉得改好了”来糊弄过去。Hard Stops 里每一条都对应一个具体的目录或文件避免模糊表述。5. 沙箱配置片段给 Agent 一个安全的执行环境AGENTS.md 管住了“该做什么”沙箱负责“在哪做、怎么安全地做”。下面是一个最小可用的 Docker 沙箱配置思路是锁定依赖、限制网络、挂载工作目录、把执行结果结构化返回。# Dockerfile.agent FROM node:20-slim WORKDIR /workspace # 只装 pnpm依赖在运行时用 frozen-lockfile 安装 RUN corepack enable corepack prepare pnpm9 --activate # 复制依赖清单先装依赖利用缓存 COPY package.json pnpm-lock.yaml ./ RUN pnpm install --frozen-lockfile # 复制源码 COPY . . # 默认不开放网络需要时通过参数覆盖 CMD [pnpm, test]启动脚本里加上资源限制和网络隔离docker build -f Dockerfile.agent -t agent-sandbox . docker run --rm \ --network none \ --memory 2g \ --cpus 2 \ -v $PWD:/workspace \ -w /workspace \ agent-sandbox \ sh -c pnpm typecheck pnpm lint pnpm test--network none是关键它让 Agent 在沙箱里跑测试时无法访问外部网络避免意外拉取依赖或泄露数据。如果任务确实需要联网查文档再单独开一个受限的网络策略而不是默认放开。沙箱的反馈机制也要设计好。理想情况下成功时只返回一个极简符号失败时才打印完整错误日志。这样能避免大量无用信息挤占上下文。你可以在启动脚本外面包一层if docker run ... ; then echo ✓ else echo ✗ 校验失败以下是错误日志 docker run ... 21 | tail -n 50 fi这样 Agent 拿到的要么是一个✓要么是聚焦的错误片段而不是几百行构建日志。6. 验证请求跑一次任务观察行为差异配置写完了得实际跑一次才知道有没有效果。我建议做一组对照实验同一个任务分别在“无 harness”和“有 harness”下执行观察差异。任务可以很简单“修复src/service/user.ts里的类型错误”。无 harness 时你直接对 Agent 说这句话。它可能会改user.ts也可能顺手改了repo层改完说“已修复”。你跑pnpm typecheck可能还有别的错误因为它没跑完整校验。有 harness 时Agent 的流程会变成先读 AGENTS.md 和 PROGRESS.md说明要改的文件改完后运行pnpm typecheck pnpm lint pnpm test pnpm build退出码为 0 才宣布完成最后回写 PROGRESS.md。你可以用一个简单的验证请求来确认接入是否正常curl https://taotoken.net/api/v1/messages \ -H x-api-key: $TAOTOKEN_API_KEY \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: claude-sonnet-4-20250514, max_tokens: 128, messages: [{role: user, content: 回复 OK 两个字母}] }如果返回里有正常的文本内容说明 key 和 base url 都没问题。接下来把 Agent 指向这个接入再跑上面的对照任务。实测下来差异最明显的地方是过早宣布完成。没有 DoD 约束时Agent 倾向于改完就收工有了退出码门槛它会自己跑校验、看报错、再修一轮。这就是 harness 把随机性转成确定性的过程。7. 本篇常见错排查配置过程中容易踩的坑集中在几个地方我按出现频率排一下。报错一401 Unauthorized或invalid api key先检查环境变量有没有真正导出。echo $ANTHROPIC_API_KEY看是不是空。如果是空说明.env没被 source或者变量名写错了。注意 TaoToken 的 key 前缀和客户端期望的变量名要对应上。报错二404 Not Found访问模型接口大概率是 base url 多写了/v1。正确写法是https://taotoken.net/api让客户端自己拼路径。去接入文档核对一下当前客户端要求的格式。报错三沙箱里pnpm install失败检查pnpm-lock.yaml是否被复制进镜像。如果只复制了package.json--frozen-lockfile会因为找不到锁文件而报错。另外--network none下无法从 registry 拉包依赖必须在构建阶段装好。报错四Agent 不读 AGENTS.md不同工具读取规则文件的路径和文件名不一样。有的认AGENTS.md有的认CLAUDE.md。确认你的工具文档里写的文件名必要时做软链接。另外文件要放在项目根目录放在子目录里可能不被扫描到。报错五校验命令一直失败但 Agent 说完成了说明 DoD 没有真正约束住它。检查 AGENTS.md 里是否明确写了“退出码不为 0 禁止宣布完成”以及 Agent 是否有权限执行这些命令。如果沙箱里没装 pnpm命令会直接失败Agent 可能误判为“环境问题”而跳过。报错六上下文很快被撑满这是缺少上下文重置机制的表现。在 AGENTS.md 里加上 40% 警戒线和 PROGRESS.md 回写约定让 Agent 在接近阈值时主动卸载状态而不是硬撑到报错。8. 把 harness 用起来从最小可用底座开始harness 不需要一上来就搭得很复杂。按优先级先把 P0 的两件事做掉一份带 DoD 的 AGENTS.md一个能跑校验的沙箱。这两样到位Agent 的“过早宣布完成”和“污染环境”两个高频问题就能压下去。等你跑顺了再往上加 P1 的状态管理PROGRESS.md 上下文重置、P2 的护栏与 Hooks、P3 的定期扫描与评估管道。每一步都对应一个具体的失败场景而不是为了架构好看。如果你想让 Agent 长期承担编码任务可以了解一下 Coding Plan它把模型调用和工程化配置打包在一起省去自己拼接入的麻烦https://taotoken.net/coding-plan。需要管理多个 key 或查看用量控制台在https://taotoken.net/console。接入过程中遇到路径或权限问题优先翻接入文档https://taotoken.net/doc大部分报错那里都有对应说明。最后留一个我自己的习惯每次 Agent 犯了一个新错误就往 AGENTS.md 的 Hard Stops 里加一条并在 PROGRESS.md 的已知问题里记一笔。harness 不是一次写完的它是跟着 Agent 的失败一起长出来的。
harness 工程设计学习与理解：从 AGENTS.md 到沙箱的 AI Agent 配置骨架
1. 为什么你的 Agent 总是“跑偏”从一次失败的任务说起如果你最近在折腾 AI Agent大概率遇到过这种场景你给 Agent 一句“帮我把这个项目的类型错误修一下”它信心满满地开始改代码改完告诉你“已完成”。你跑一下pnpm typecheck红了一片。再让它修它换了个地方又改错了。来回几轮你发现它根本没读项目规范也不知道自己该在哪个目录里动手。这不是模型不够聪明而是缺少一套“缰绳”。业界把围绕 Agent 构建的这套执行控制、评测与迭代体系叫做harness可以理解为“夹具”或“挽具”。它源自传统软件工程里的 Test Harness指的是在受控且可观测的环境中运行测试的脚本、Mock 和基础设施集合。放到 AI Agent 场景里harness 就是让模型从“会聊天”变成“能干活”的那层工程骨架。这篇内容聚焦 AI Agent 工程化落地以 harness 为线索把AGENTS.md和沙箱这两块最容易混淆的边界讲清楚。我会给出一份可以直接复制的 AGENTS.md 骨架、一段 Docker 沙箱配置以及一套验证动作让你在本地跑通一次 Agent 任务并亲眼看到“有 harness”和“没 harness”的行为差异。适合已经用过 Claude Code、Cursor、Codex 这类工具但总觉得 Agent 不够稳的开发者。2. 先搞清楚 harness 的边界AGENTS.md 管什么沙箱管什么很多人把 AGENTS.md 当成一个“更长的 system prompt”把沙箱当成“跑代码的地方”结果两边职责糊在一起Agent 一遇到报错就乱猜。我试过把这两者的边界画成一张表思路会清晰很多。维度AGENTS.md沙箱Sandbox本质机器可读的规则与错题本受控的执行环境管什么做什么、不做什么、怎么算完成在哪跑、能碰什么、跑完怎么反馈典型内容架构规范、Hard Stops、Definition of Done依赖锁定、网络限制、文件系统权限失败表现Agent 改错方向、过早宣布完成Agent 污染宿主环境、命令执行失败无反馈更新频率每次踩坑后追加依赖或安全策略变化时调整一句话概括AGENTS.md 是“宪法”沙箱是“无菌手术室”。宪法告诉 Agent 什么能做、什么绝对不能碰、做到什么程度才算完手术室保证它即使执行了高危命令也不会把宿主环境搞坏同时把执行结果结构化地反馈回来。harness 的核心公式可以写成Agent Model Harness。模型提供原始智能harness 负责把这份智能约束成可靠、可重复、可门禁的产出。所以判断一个工程是不是 harness engineering不看它用了什么框架而看它的“控制面”是否成立规则是否机器可读、约束是否机械可执行、反馈是否闭环。3. 前置准备用 TaoToken 拿到可用的模型接入在写 AGENTS.md 之前得先让 Agent 能稳定调用模型。我本地用的是 TaoToken 的接入方式它兼容 Anthropic 风格的接口配置起来比较直接。先去控制台创建一个 API Key地址是https://taotoken.net/api-keys。创建后复制那串 key后面配置环境变量要用。如果你还没决定用哪个模型可以先到模型对话页面https://taotoken.net/chat试几句确认响应正常再接入到 Agent 里。拿到 key 之后在项目根目录建一个.env文件记得加进.gitignore# .env TAOTOKEN_API_KEYsk-你的key TAOTOKEN_BASE_URLhttps://taotoken.net/api如果你用的是 Claude Code 这类工具它读取的是ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY可以这样映射export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEY$TAOTOKEN_API_KEY这里有个坑要注意base url 末尾不要多加/v1不同客户端对路径拼接的处理不一样多写一层容易出现 404。接入文档在https://taotoken.net/doc遇到路径问题先去那里核对。4. 可复制的 AGENTS.md 骨架把规则写成机器能读的形式下面这份骨架是我在几个小项目里迭代出来的核心思路是把“完成定义”和“禁止操作”放在最显眼的位置把验证命令固化成可执行的一行。Agent 每次开工前读它收工前对照它。# AGENTS.md ## 项目说明 这是一个 TypeScript Node 的后端服务包管理用 pnpm。 目录分层types → config → repo → service → runtime → ui依赖只能从右往左。 ## 完成定义Definition of Done 任务只有在以下命令全部退出码为 0 时才算完成 bash pnpm typecheck pnpm lint pnpm test pnpm build退出码不为 0禁止宣布任务完成。禁止操作Hard Stops禁止直接修改src/runtime和src/ui之外的数据库访问代码。禁止跳过测试直接提交。禁止修改pnpm-lock.yaml除非明确要求升级依赖。禁止在未读取 PROGRESS.md 的情况下开始新任务。工作流新会话第一件事读取 PROGRESS.md了解已完成、进行中、待办、已知问题。修改代码前先说明你打算改哪些文件、为什么。修改后立即运行对应的校验命令见下方路由表。任务完成或中断时回写 PROGRESS.md。校验路由改了类型定义 →pnpm typecheck改了业务逻辑 →pnpm test改了依赖 →pnpm install --frozen-lockfile pnpm build不确定 → 跑完整 DoD 命令上下文警戒当上下文使用率接近 40% 时停止当前动作把状态结构化写入 PROGRESS.md 然后建议开启一个干净会话继续。配套的 PROGRESS.md 可以很简单 markdown # PROGRESS ## 已完成 - 用户登录接口的类型定义 ## 进行中 - 登录接口的单元测试 ## 待办 - 补充错误码映射 ## 已知问题 - repo 层有个查询没加索引暂不影响测试这份骨架的关键不在内容多而在可执行。DoD 那一行命令是硬门槛Agent 没法用“我觉得改好了”来糊弄过去。Hard Stops 里每一条都对应一个具体的目录或文件避免模糊表述。5. 沙箱配置片段给 Agent 一个安全的执行环境AGENTS.md 管住了“该做什么”沙箱负责“在哪做、怎么安全地做”。下面是一个最小可用的 Docker 沙箱配置思路是锁定依赖、限制网络、挂载工作目录、把执行结果结构化返回。# Dockerfile.agent FROM node:20-slim WORKDIR /workspace # 只装 pnpm依赖在运行时用 frozen-lockfile 安装 RUN corepack enable corepack prepare pnpm9 --activate # 复制依赖清单先装依赖利用缓存 COPY package.json pnpm-lock.yaml ./ RUN pnpm install --frozen-lockfile # 复制源码 COPY . . # 默认不开放网络需要时通过参数覆盖 CMD [pnpm, test]启动脚本里加上资源限制和网络隔离docker build -f Dockerfile.agent -t agent-sandbox . docker run --rm \ --network none \ --memory 2g \ --cpus 2 \ -v $PWD:/workspace \ -w /workspace \ agent-sandbox \ sh -c pnpm typecheck pnpm lint pnpm test--network none是关键它让 Agent 在沙箱里跑测试时无法访问外部网络避免意外拉取依赖或泄露数据。如果任务确实需要联网查文档再单独开一个受限的网络策略而不是默认放开。沙箱的反馈机制也要设计好。理想情况下成功时只返回一个极简符号失败时才打印完整错误日志。这样能避免大量无用信息挤占上下文。你可以在启动脚本外面包一层if docker run ... ; then echo ✓ else echo ✗ 校验失败以下是错误日志 docker run ... 21 | tail -n 50 fi这样 Agent 拿到的要么是一个✓要么是聚焦的错误片段而不是几百行构建日志。6. 验证请求跑一次任务观察行为差异配置写完了得实际跑一次才知道有没有效果。我建议做一组对照实验同一个任务分别在“无 harness”和“有 harness”下执行观察差异。任务可以很简单“修复src/service/user.ts里的类型错误”。无 harness 时你直接对 Agent 说这句话。它可能会改user.ts也可能顺手改了repo层改完说“已修复”。你跑pnpm typecheck可能还有别的错误因为它没跑完整校验。有 harness 时Agent 的流程会变成先读 AGENTS.md 和 PROGRESS.md说明要改的文件改完后运行pnpm typecheck pnpm lint pnpm test pnpm build退出码为 0 才宣布完成最后回写 PROGRESS.md。你可以用一个简单的验证请求来确认接入是否正常curl https://taotoken.net/api/v1/messages \ -H x-api-key: $TAOTOKEN_API_KEY \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: claude-sonnet-4-20250514, max_tokens: 128, messages: [{role: user, content: 回复 OK 两个字母}] }如果返回里有正常的文本内容说明 key 和 base url 都没问题。接下来把 Agent 指向这个接入再跑上面的对照任务。实测下来差异最明显的地方是过早宣布完成。没有 DoD 约束时Agent 倾向于改完就收工有了退出码门槛它会自己跑校验、看报错、再修一轮。这就是 harness 把随机性转成确定性的过程。7. 本篇常见错排查配置过程中容易踩的坑集中在几个地方我按出现频率排一下。报错一401 Unauthorized或invalid api key先检查环境变量有没有真正导出。echo $ANTHROPIC_API_KEY看是不是空。如果是空说明.env没被 source或者变量名写错了。注意 TaoToken 的 key 前缀和客户端期望的变量名要对应上。报错二404 Not Found访问模型接口大概率是 base url 多写了/v1。正确写法是https://taotoken.net/api让客户端自己拼路径。去接入文档核对一下当前客户端要求的格式。报错三沙箱里pnpm install失败检查pnpm-lock.yaml是否被复制进镜像。如果只复制了package.json--frozen-lockfile会因为找不到锁文件而报错。另外--network none下无法从 registry 拉包依赖必须在构建阶段装好。报错四Agent 不读 AGENTS.md不同工具读取规则文件的路径和文件名不一样。有的认AGENTS.md有的认CLAUDE.md。确认你的工具文档里写的文件名必要时做软链接。另外文件要放在项目根目录放在子目录里可能不被扫描到。报错五校验命令一直失败但 Agent 说完成了说明 DoD 没有真正约束住它。检查 AGENTS.md 里是否明确写了“退出码不为 0 禁止宣布完成”以及 Agent 是否有权限执行这些命令。如果沙箱里没装 pnpm命令会直接失败Agent 可能误判为“环境问题”而跳过。报错六上下文很快被撑满这是缺少上下文重置机制的表现。在 AGENTS.md 里加上 40% 警戒线和 PROGRESS.md 回写约定让 Agent 在接近阈值时主动卸载状态而不是硬撑到报错。8. 把 harness 用起来从最小可用底座开始harness 不需要一上来就搭得很复杂。按优先级先把 P0 的两件事做掉一份带 DoD 的 AGENTS.md一个能跑校验的沙箱。这两样到位Agent 的“过早宣布完成”和“污染环境”两个高频问题就能压下去。等你跑顺了再往上加 P1 的状态管理PROGRESS.md 上下文重置、P2 的护栏与 Hooks、P3 的定期扫描与评估管道。每一步都对应一个具体的失败场景而不是为了架构好看。如果你想让 Agent 长期承担编码任务可以了解一下 Coding Plan它把模型调用和工程化配置打包在一起省去自己拼接入的麻烦https://taotoken.net/coding-plan。需要管理多个 key 或查看用量控制台在https://taotoken.net/console。接入过程中遇到路径或权限问题优先翻接入文档https://taotoken.net/doc大部分报错那里都有对应说明。最后留一个我自己的习惯每次 Agent 犯了一个新错误就往 AGENTS.md 的 Hard Stops 里加一条并在 PROGRESS.md 的已知问题里记一笔。harness 不是一次写完的它是跟着 Agent 的失败一起长出来的。
