harness 工程化实践：用 AGENTS.md 与 Makefile 把 TaoToken 接入 CI 流水线-北京尧图网络

1. 为什么要把 harness 搬进 CI从“本地能跑”到“流水线可复现”先说清楚 harness 是什么。你可以把它理解成 AI 编码代理的“编排层”它不负责写业务代码而是负责告诉代理——这个项目是什么、怎么跑、怎么验证、做完的标准是什么。AGENTS.md 是代理的着陆页Makefile 是标准操作入口PROGRESS.md 是跨会话的进度记忆。这三样东西凑齐代理才不至于每次开新会话都从零猜项目结构。我见过太多团队的做法是本地开个终端把代理跑起来改完代码手动pytest一下看着绿了就提交。问题在于这套流程完全依赖“人记得做验证”。一旦代理在 CI 里跑或者换个人接手验证步骤就丢了。更麻烦的是代理会复制仓库里已有的模式——如果仓库里没有“验证是强制的”这个信号它就会用“代码看起来没问题”代替“行为通过测试”。所以 harness 工程化的核心动作只有一个把代理的行为约束和验证步骤从“对话里的口头约定”变成“仓库里可执行的工件”。AGENTS.md 声明规则Makefile 固化命令CI 负责强制执行。代理读得到、跑得动、绕不过。这篇要解决的具体场景是你已经在用 TaoToken 作为统一通道调用模型现在想让 CI 流水线里的代理任务也走同一条通道并且用 AGENTS.md Makefile 把调用步骤固定下来。涉及的关键词包括 harness、AGENTS.md、CLAUDE.md、Makefile、PROGRESS.md以及 endpoint 和 auth.json 的配置切换。适合谁看正在把 AI 编码代理接入团队流水线的工程师被“代理本地能跑、CI 里 401”折腾过的人想让代理任务可复现、可交接的维护者。下面按“先讲清楚问题 → 再给可复制配置 → 然后验证 → 最后排障”的顺序展开每一步都能直接抄。2. TaoToken 前置统一通道与 auth.json 的定位在把 harness 接进 CI 之前得先理解 TaoToken 在这套结构里扮演什么角色。简单说它是一个统一的模型调用通道你的代理、CI 脚本、本地调试都通过同一个 endpoint 和同一套鉴权信息去请求模型。这样做的好处是换模型、调参数、看用量都只在一个地方改不用每个脚本各配一份。TaoToken 的 API 地址是https://taotoken.net/api官网在https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content。注意 API 地址不带查询参数配置里写干净的https://taotoken.net/api就行。对于 Codex 这类工具鉴权信息通常落在auth.json里。这个文件的位置和字段名不同版本可能略有差异但核心就三样Base URL、API Key、Model ID。这三件套必须同时正确缺一个就会出问题——Base URL 错了会连不上Key 错了会 401Model ID 错了会报模型不存在或 reading choices 之类的解析错误。我建议你在仓库里放一个auth.example.json作为模板真正的auth.json加进.gitignore。CI 里通过环境变量注入 Key而不是把 Key 写死在文件里。这样既安全又能让 harness 在本地和 CI 用同一套结构。具体到 Codex 的auth.json一个可参考的结构是这样的{ base_url: https://taotoken.net/api, api_key: sk-你的TaoToken密钥, model: claude-sonnet-4-20250514 }字段名请以你本地 Codex 版本实际读取的为准。有些版本用的是OPENAI_BASE_URL环境变量加OPENAI_API_KEY那就把这两项在 CI 的 secrets 里配好Makefile 里导出即可。关键是endpoint 指向 TaoTokenKey 从环境变量来Model ID 明确写死或从变量来不要留空。如果你用的是 Claude Code 或 Cline 这类工具配置入口不一样但三件套的逻辑相同。Claude Code 走的是环境变量或 settings 文件Cline 走的是 MCP 配置。无论哪种Base URL 都填https://taotoken.net/apiKey 用你的 TaoToken 密钥Model ID 填你实际要用的模型。这三样对齐了后面的 Makefile 和 CI 才有意义。还有一点容易被忽略CI 环境里没有你本地的 shell 配置也没有你本地~/.codex/auth.json。所以 harness 必须显式地把配置传进去不能指望“本地能读到”。这就是为什么下面要把配置写进 Makefile 和环境变量而不是靠隐式继承。3. 可复制配置AGENTS.md、Makefile 与 settings 片段这一节是全文的核心直接给可复制的片段。先给 AGENTS.md再给 Makefile最后给 CI 的 settings 片段。路径和字段尽量贴近真实项目结构你按自己仓库改目录名即可。3.1 AGENTS.md声明代理行为与硬约束AGENTS.md 放在仓库根目录控制在 50 到 200 行。它不需要包含所有信息但必须让代理快速回答三个问题这是什么项目、怎么跑、怎么验证。下面是一个可直接用的片段# AGENTS.md ## 项目概览 Python 3.11 FastAPI 后端PostgreSQL 15。模型调用统一走 TaoToken 通道。 ## 快速开始 - 安装依赖make setup - 运行测试make test - 完整验证make check - 启动开发服务make dev ## 模型调用约束 - 所有模型请求的 Base URL 必须是 https://taotoken.net/api - API Key 从环境变量 TAOTOKEN_API_KEY 读取禁止硬编码 - Model ID 从环境变量 TAOTOKEN_MODEL 读取默认 claude-sonnet-4-20250514 - 鉴权文件模板见 auth.example.json实际 auth.json 不提交 ## 硬约束 - 所有 API 必须走 OAuth 2.0 认证 - 所有数据库查询必须用 SQLAlchemy 2.0 语法 - 所有 PR 必须通过 make checkpytest mypy --strict ruff check - 每次只做一个功能点端到端验证通过后才能开始下一个 - 功能完成验证命令通过不是“代码写完了” ## 会话流程 ### 每次会话开始时 1. 读 PROGRESS.md 了解当前状态 2. 跑 make check 确认仓库处于一致状态 3. 从 PROGRESS.md 的“下一步”继续 ### 每次会话结束前 1. 更新 PROGRESS.md 2. 跑 make check 确认一致状态 3. 提交所有已完成的工作 ## 专题文档 - API 设计规范 (docs/api-patterns.md) — 添加新端点时必读 - 数据库操作约束 (docs/database-rules.md) — 涉及数据库修改时必读 - 测试标准 (docs/testing-standards.md) — 编写测试时参考这个文件里模型调用约束那一段就是为 TaoToken 准备的。代理读到它就知道 Base URL 和 Key 从哪来不会自己去猜。硬约束里的“每次只做一个功能点”和“完成验证通过”是防止代理过早宣告完成的关键。3.2 Makefile固化调用步骤与验证命令Makefile 的作用是把“怎么跑”变成一条命令。代理不需要记住一堆参数只需要make check。下面是一个可复制的 MakefileSHELL : /bin/bash export TAOTOKEN_BASE_URL ? https://taotoken.net/api export TAOTOKEN_MODEL ? claude-sonnet-4-20250514 .PHONY: setup test lint typecheck check dev agent-run clean setup: pip install -r requirements.txt pip install -r requirements-dev.txt test: pytest -q lint: ruff check . typecheck: mypy --strict src/ check: lint typecheck test echo check passed dev: uvicorn src.main:app --reload --port 8000 agent-run: test -n $$TAOTOKEN_API_KEY || (echo TAOTOKEN_API_KEY is required exit 1) codex exec --config base_url$$TAOTOKEN_BASE_URL \ --config model$$TAOTOKEN_MODEL \ --config api_key$$TAOTOKEN_API_KEY \ $$AGENT_TASK clean: rm -f /tmp/debug-*.log git checkout -- .env.local 2/dev/null || true这里有几个细节值得说。agent-run目标先检查TAOTOKEN_API_KEY是否存在不存在就直接失败避免代理在 CI 里跑出一个 401 却不知道为什么。check目标把 lint、typecheck、test 串起来代理只要跑这一条就知道自己有没有过关。clean目标写成幂等的重复执行结果一样。如果你用的是 Claude Code 而不是 Codexagent-run换成对应的 CLI 调用即可但 Base URL、Key、Model ID 三件套的传递方式不变。Cline 的 MCP 配置也是同理把 endpoint 指向 TaoTokenKey 从环境变量注入。3.3 CI settings 片段把配置注入流水线CI 里最关键的是环境变量注入。以 GitHub Actions 为例settings 片段如下name: harness-check on: [push, pull_request] jobs: check: runs-on: ubuntu-latest env: TAOTOKEN_BASE_URL: https://taotoken.net/api TAOTOKEN_MODEL: claude-sonnet-4-20250514 TAOTOKEN_API_KEY: ${{ secrets.TAOTOKEN_API_KEY }} steps: - uses: actions/checkoutv4 - uses: actions/setup-pythonv5 with: python-version: 3.11 - run: make setup - run: make check注意TAOTOKEN_API_KEY来自 secrets不写在文件里。TAOTOKEN_BASE_URL和TAOTOKEN_MODEL可以直接写因为它们不是敏感信息。这样本地和 CI 用的是同一套 Makefile 目标行为一致。如果你需要生成auth.json给 Codex 用可以在 CI 里加一步- name: Write auth.json run: | cat auth.json EOF { base_url: $TAOTOKEN_BASE_URL, api_key: $TAOTOKEN_API_KEY, model: $TAOTOKEN_MODEL } EOF这一步把三件套写进auth.jsonCodex 启动时就能读到。本地开发时你手动复制auth.example.json为auth.json并填入 Key 即可。4. 验证请求与成功结果从 make check 到真实调用配置写完了得验证它真的能跑通。验证分两层先验证 harness 本身Makefile 目标可用再验证模型调用TaoToken 通道可达。第一层跑make check。如果 lint、typecheck、test 都通过你会看到类似输出ruff check . All checks passed! mypy --strict src/ Success: no issues found in 12 source files pytest -q 43 passed in 2.31s check passed这说明 harness 的验证链路是通的。代理在 CI 里跑这条命令就能得到明确的通过或失败信号。第二层验证模型调用。用make agent-run跑一个简单任务比如让代理读一下 PROGRESS.md 并总结当前状态。如果配置正确你会看到代理正常返回内容而不是报错。一个成功的调用日志里应该能看到请求发往https://taotoken.net/api并且返回了模型输出。如果你想更直接地验证 endpoint可以用 curl 发一个最小请求curl -sS https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: $TAOTOKEN_MODEL, messages: [{role: user, content: ping}], max_tokens: 16 }返回里如果有choices字段和内容说明通道是通的。如果返回 401说明 Key 有问题如果返回 429说明触发了限流如果报reading choices之类的解析错误说明返回结构不符合预期通常是 endpoint 或 Model ID 写错了。验证通过后把PROGRESS.md更新一下记录当前状态和下一步。这样下一个会话接手时读一下文件就知道从哪继续。PROGRESS.md 的格式可以很简单# 项目进度 ## 当前状态 - 最新 commit: abc1234 - 测试状态: 43/43 通过 - Lint: 通过 ## 已完成 - [x] TaoToken 通道接入 - [x] AGENTS.md 与 Makefile 落地 ## 进行中 - [ ] CI 流水线接入 agent-run ## 下一步 1. 在 CI 里加 agent-run 步骤 2. 验证 401 与 429 的排障路径这份文件是跨会话连续性的关键。代理每次“下班”前更新它下次“上班”先读它重建成本能从十几分钟压到几分钟。5. 本篇常见错排查401、429 与 reading choices配置和验证都走通了但实际跑起来还是会遇到报错。这一节对照真实错误给出排查动作。重点讲三个401、429、reading choices外加一个 local proxy failed。5.1 401 Unauthorized报错长这样Error: 401 Unauthorized {error: {message: Invalid API key, type: invalid_request_error}}排查顺序第一确认TAOTOKEN_API_KEY在 CI 的 secrets 里存在且没有多余空格。第二确认auth.json里的api_key字段确实读到了环境变量而不是空字符串。第三确认 Base URL 是https://taotoken.net/api没有多写/v1或少写协议头。第四确认 Key 没有过期或被撤销。一个常见的坑是本地auth.json里有 KeyCI 里忘了配 secrets结果 CI 跑的时候 Key 是空的。Makefile 里的agent-run目标加了test -n $$TAOTOKEN_API_KEY检查就是为了让这种情况直接失败并给出明确提示而不是等到请求发出去才报 401。5.2 429 Too Many Requests报错长这样Error: 429 Too Many Requests {error: {message: Rate limit exceeded, type: rate_limit_error}}429 是限流不是配置错误。排查动作第一看是不是短时间内发了太多请求比如代理在一个循环里反复调用。第二看是不是并发会话太多多个 CI job 同时打同一个 Key。第三在 harness 里加退避重试比如指数退避。一个实用的做法是在 Makefile 或 CI 脚本里加一个简单的重试包装retry() { local n0 until $; do n$((n1)) if [ $n -ge 3 ]; then echo failed after 3 attempts return 1 fi sleep $((n * 5)) done }然后retry make agent-run。这样偶发的 429 不会直接让流水线红掉。但如果是持续 429就要考虑降低并发或联系通道方确认配额。5.3 reading choices 解析错误报错长这样Error: failed to parse response: reading choices: unexpected end of JSON input这个错误通常不是鉴权问题而是返回体不是预期的 JSON 结构。排查动作第一确认 Base URL 指向的是https://taotoken.net/api而不是某个返回 HTML 的地址。第二确认 Model ID 是通道支持的模型写错的 Model ID 可能返回错误页而不是 JSON。第三用第 4 节的 curl 命令直接打一次看原始返回是什么。如果 curl 返回的是 HTML 或空体说明 endpoint 或路径不对。5.4 local proxy failed报错长这样Error: local proxy failed: connection refused这个错误说明代理进程尝试连接一个本地端口但那个端口没有服务在听。常见原因是本地开发时配了某个本地代理端口CI 里没有这个服务。排查动作第一检查配置里有没有指向localhost或127.0.0.1的地址把它改成https://taotoken.net/api。第二检查环境变量里有没有残留的代理设置比如HTTP_PROXY指向了不存在的本地端口。第三确认 CI 环境不需要任何本地代理所有请求直接走 TaoToken 通道。5.5 OAuth 相关报错如果你的项目用了 OAuth可能会看到Error: OAuth token exchange failed这类错误和模型通道无关是应用自身的鉴权流程问题。排查动作确认 OAuth 的 client id、secret、回调地址在 CI 环境里配对了。不要把它和 TaoToken 的 401 混在一起排查两者是独立的鉴权层。把这几类错误对照着排查大部分 CI 里的失败都能定位到具体原因。关键是每次遇到新类型的错误就把它变成一条自动化检查或一条 AGENTS.md 里的约束这样 harness 会越来越强。6. 把通道固定下来从模型对话到 Coding Plan 的下一步走到这里harness 的基本结构已经成型AGENTS.md 声明规则Makefile 固化命令CI 强制执行TaoToken 作为统一通道。代理在本地和 CI 里跑的是同一套流程验证信号一致交接有 PROGRESS.md 兜底。接下来可以做的几件事。第一把agent-run真正接进 CI让代理任务也在流水线里跑而不是只在本地手动触发。第二给功能清单加一个机器可读的格式让调度器和验证器都能读这样“做完”的标准就完全外部化了。第三定期清理 harness把不再必要的约束移除保持指令信噪比。如果你还没配好 Key可以去 TaoToken 的 API Keys 页面生成一个然后按第 3 节的 settings 片段注入 CI。接入文档里有各工具的详细配置说明遇到字段名对不上时以文档为准。想先验证模型通道是否可用可以直接在模型对话里发一条消息试试。如果打算长期在 CI 里跑编码代理和 Agent 任务Coding Plan 会更适合这种持续调用的场景。最后留一个实用技巧每次 CI 失败后先看make check的输出再看模型调用的原始返回。大部分问题要么在验证链路要么在鉴权三件套很少是模型本身的问题。把这两处盯住harness 就能稳定跑下去。

harness 工程化实践：用 AGENTS.md 与 Makefile 把 TaoToken 接入 CI 流水线

相关推荐

大模型推理-基于prefill和decode阶段特性，PD分离，势在必行！TaoToken统一Key下的PD分离部署大纲

2026年5月开源模型Token服务实测榜：TaoToken统一Key下DeepSeek/GLM/Kimi三层架构性能拆解

Codex 下载与本地部署实战：从安装到运行全流程指南（TaoToken 统一 Key 接入版）

更多资讯

CentOS手动部署Tomcat完整教程：JDK配置、systemd托管与SELinux加固

化工行业数字化解决方案：从DCS数据采集到软测量与报警管理落地实践

自动驾驶决策规划全解析：从行为决策到运动规划的工程实践

Interval Bound Propagation（IBP）：神经网络鲁棒性验证的确定性边界工具

人工智能在护理领域的应用落地：风险预测与文书自动化实践

回溯去重全排列详解：Permutations II 剪枝模板与实战

今日更新

NetSpot 实战：用信道分析与频宽优化解决 Wi-Fi 卡顿

C++ split() 字符串分割的五种实现与性能实测

R语言坐标轴范围设置：从xlim/ylim到coord_cartesian的完整指南

本周精选

交通拥堵预测毕设：基于Python+LSTM的车辆流量预测系统全流程解析

MATLAB/Simulink搭建10机39节点电力系统暂态稳定仿真实战

无人机航拍三维重建全流程：从SfM到网格生成的避坑指南

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？