OpenCode 实战案例：用 AGENTS.md 打通 Plan 与 Build 的 TaoToken 配置

1. 为什么要在 OpenCode 里认真对待 AGENTS.mdOpenCode 是一个跑在终端里的 AI 编码代理能读你的仓库、改文件、跑命令还能在 Plan 和 Build 两种模式之间切换。很多人第一次用它会直接开一个对话丢需求进去结果要么计划太粗、要么改得乱七八糟。问题往往不在模型而在于你没有告诉它「你是谁、这个项目怎么跑、Plan 该产出什么、Build 该守什么规矩」。AGENTS.md 就是干这个的。它放在仓库根目录OpenCode 启动时会自动读取相当于给代理一份项目级的「上岗说明书」。你可以把它理解成给新同事写的 onboarding 文档技术栈、目录结构、常用命令、代码风格、禁止事项全写进去。写得好Plan 阶段产出的方案会贴着你的项目走Build 阶段也不会乱动无关文件。这篇聚焦一个具体场景用 AGENTS.md 把 Plan 和 Build 两个角色的分工固定下来再通过 TaoToken 统一 Key 和 API 通道接入让整条链路一次跑通。适合已经在用 OpenCode、但觉得「计划归计划、执行归执行、两边对不上」的同学。下面会给可直接复制的 AGENTS.md 骨架、settings.json 配置片段以及 Plan 到 Build 的验证动作。2. 前置准备TaoToken 统一 Key 与 API 通道OpenCode 支持自定义模型提供方只要兼容 OpenAI 风格的接口就能接。TaoToken 在这里扮演的角色是统一入口你不需要在多个平台之间来回切换 Key也不用为每个模型单独配一套环境变量。一个 Key、一个 API 地址Plan 和 Build 用同一套通道省掉「这个模型走这个 Key、那个模型走那个 Key」的混乱。先拿到 Key。打开控制台创建 API Key建议按用途命名比如opencode-dev方便后面排查是哪个 Key 在调用。创建后立刻复制页面刷新后就看不到了。控制台入口https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewriteAPI Key 管理https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewriteAPI 基础地址用https://taotoken.net/api注意这个地址后面不加任何查询参数。模型名按文档里列出的写别自己拼。如果你打算长期跑编码任务、频繁调用可以顺带看下 Coding Plan它更适合这种持续性的代理场景Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite注意Key 只放在本地环境变量或本地配置文件里不要提交进 Git。后面配置片段里我用占位符你替换成自己的真实值。3. 可复制的 AGENTS.md 骨架把 Plan 与 Build 分开写AGENTS.md 的关键不是写得多而是把「角色边界」写清楚。下面这份骨架分了三块项目背景、Plan 角色约定、Build 角色约定。你可以直接复制把方括号里的内容换成自己项目的实际情况。# AGENTS.md ## 项目背景 - 技术栈[TypeScript / Node.js / pnpm] - 包管理[pnpm] - 测试框架[vitest] - 关键目录 - src/ 业务源码 - src/utils/ 工具函数 - tests/ 测试用例 - 常用命令 - 安装依赖pnpm install - 跑测试pnpm test - 类型检查pnpm typecheck ## Plan 角色约定 你是 Plan 模式下的方案设计者只输出计划不修改任何文件。 - 先阅读相关文件再给方案禁止凭空猜测目录结构。 - 方案必须包含改动点清单、涉及文件路径、风险点、验证方式。 - 涉及数据库或接口变更时单独列出兼容性影响。 - 输出用编号步骤每步说明「改什么、为什么改」。 - 不确定的地方明确标注「需要确认」不要自行假设。 ## Build 角色约定 你是 Build 模式下的执行者严格按已确认的 Plan 落地。 - 只改 Plan 中列出的文件需要额外改动时先停下来说明原因。 - 保持现有代码风格不引入新的依赖除非 Plan 中已说明。 - 每次改动后运行 pnpm typecheck 和 pnpm test。 - 提交前展示 diff等待确认后再继续。 - 遇到权限确认提示逐条判断不要无脑全部允许。 ## 通用禁止事项 - 不修改 CI 配置和部署脚本。 - 不删除已有测试用例。 - 不提交任何密钥、Token、连接串。这份骨架里Plan 和 Build 的职责是互斥的Plan 只读不写Build 只按计划写。这样切模式的时候代理不会在 Plan 阶段偷偷改文件也不会在 Build 阶段自由发挥。我试过把这两段合并写结果代理经常在「计划」里就把代码改了review 的时候很难分清哪些是计划、哪些是执行。生成这份文件最省事的办法是用/init。在项目根目录执行cd /path/to/your-project opencode /init它会扫描仓库生成一份初始 AGENTS.md。生成后你手动补上 Plan 和 Build 两段角色约定因为/init默认不会区分模式。4. settings.json 配置片段接入 TaoTokenOpenCode 的模型配置放在settings.json里。不同版本路径略有差异一般在用户配置目录下比如~/.config/opencode/settings.json。下面这段是接入 TaoToken 的最小配置把apiKey换成你自己的或者用环境变量引用。{ provider: { taotoken: { type: openai, baseURL: https://taotoken.net/api, apiKey: ${TAOTOKEN_API_KEY}, models: { default: { name: 你的模型名, contextWindow: 128000 } } } }, agent: { plan: { provider: taotoken, model: default }, build: { provider: taotoken, model: default } } }几个要点说明。type用openai因为 TaoToken 走的是 OpenAI 兼容协议。baseURL就是https://taotoken.net/api结尾不要加斜杠也不要加别的路径。apiKey用${TAOTOKEN_API_KEY}引用环境变量这样配置文件本身可以安全地放进版本库如果你确实需要共享配置的话。环境变量在 shell 里设置export TAOTOKEN_API_KEY你的真实Key想让它永久生效写进~/.bashrc或~/.zshrc。Windows 下用系统环境变量面板设置或者在 PowerShell 里用$env:TAOTOKEN_API_KEY...临时设置。agent这一段是重点Plan 和 Build 都指向同一个 provider 和 model。你也可以让它们用不同模型比如 Plan 用推理强一点的、Build 用速度快一点的但通道还是同一个 TaoTokenKey 不用换。这就是「统一 Key / API 通道」的实际含义。配置改完重启 OpenCode 让它重新加载。如果启动时报 provider 找不到先检查 JSON 有没有语法错误逗号、引号是最容易出问题的地方。5. 验证 Plan 到 Build 链路一次完整跑通配置好了来跑一个真实的小需求验证整条链路。目标给一个笔记应用加「软删除」——删除时打标记而不是真删。第一步切到 Plan 模式。在 OpenCode 里按 Tab 切换确认界面提示当前是 Plan。然后输入需求When a user deletes a note, flag it as deleted in the database instead of removing the row. Then add a screen that lists recently deleted notes, where the user can restore or permanently delete.因为 AGENTS.md 里写了 Plan 的约定代理应该先读相关文件再输出编号步骤包含改动点、文件路径、风险点和验证方式。如果它直接开始改文件说明 Plan 约定没生效回去检查 AGENTS.md 是否被正确读取。第二步审阅计划。重点看三件事涉及的文件路径对不对、有没有漏掉数据库迁移、验证方式是否可执行。不满意就继续追问比如「数据库字段变更需要迁移脚本补上」。Plan 阶段可以反复迭代不消耗文件改动。第三步切回 Build。按 Tab 切到 Build 模式输入确认Sounds good. Go ahead and make the changes.这时代理会按计划改文件。遇到权限提示逐条看读文件、跑测试可以允许删文件、改 CI 配置要谨慎。改完后它会展示 diff你 review 一遍确认没问题再让它继续。第四步验证结果。让代理跑测试和类型检查pnpm typecheck pnpm test如果测试通过再手动确认一下软删除逻辑删一条笔记查数据库确认是标记而非删除再走一遍恢复流程。这一步别省代理说「完成」不等于真的对。整条链路跑通后你会看到 Plan 产出的方案和 Build 的实际改动是对得上的因为两边都受同一份 AGENTS.md 约束走的是同一个 TaoToken 通道。6. 本篇常见错误排查报错一Provider not found: taotoken多半是settings.json里 provider 名字和agent里引用的名字不一致或者 JSON 语法错误导致整段没加载。先用cat settings.json | python -m json.tool校验语法再核对名字拼写。报错二401 UnauthorizedKey 没读到或已失效。检查环境变量是否在当前 shell 生效echo $TAOTOKEN_API_KEY。如果为空说明 export 没执行或写错了文件。也可能是 Key 被删了去控制台重新创建一个。报错三Plan 模式仍然修改文件AGENTS.md 没被读取或者 Plan 约定写得太弱。确认 AGENTS.md 在项目根目录且里面有明确的「只输出计划不修改任何文件」。必要时在对话里再强调一次「你现在是 Plan 模式不要改文件」。报错四Build 阶段改了计划外的文件Build 约定不够严或者 Plan 本身没列全。回去补 AGENTS.md 里的「只改 Plan 中列出的文件」同时在 Plan 阶段把改动点列细一点。报错五请求超时或连接失败先确认baseURL是https://taotoken.net/api没有多余路径和参数。再检查本地网络是否正常。如果持续失败去接入文档核对最新的地址和参数格式接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite报错六模型名不识别模型名必须按文档里列出的写不能自己拼。去模型对话页面确认可用模型名模型对话https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite排查顺序建议先看 Key 和环境变量再看 baseURL最后看模型名。大部分问题出在前两步。7. 把配置沉淀下来长期跑编码任务一次跑通之后建议把 AGENTS.md 和 settings.json 都纳入版本管理Key 用环境变量不进库。这样团队里其他人 clone 下来设好自己的 Key 就能用同一套角色约定。Plan 和 Build 的分工一旦固定代理的行为会稳定很多review 成本也降下来。如果你打算把 OpenCode 用在日常编码、Agent 自动化这类长期场景Coding Plan 比按次调用更合适通道还是同一个不用重新配Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite最后留一个实用习惯每次大改动前先在 Plan 模式把方案跑一遍确认文件清单和验证方式再切 Build。这个动作花不了几分钟但能挡掉大部分「改了一半发现方向错了」的情况。AGENTS.md 写一次后面每次对话都在受益。