1. 为什么单次 Prompt 撑不起 AIAgent 工程如果你已经在用 Claude Code、Codex 或者 OpenCode 写代码大概率经历过这个阶段一开始觉得「让 AI 帮我改代码」很爽写个 Prompt 就能生成函数、补测试、修 bug。但当你试图让它每天自动巡检仓库、自动处理 PR、自动清理依赖时问题就来了——单次 Prompt 没有记忆没有状态没有验证跑完一次就断了。这就是 loop-engineering 想解决的问题。它不是一个框架也不是一个 SDK而是一套「循环工程」的参考实现和 CLI 工具集。核心思路是把 AIAgent 的工作从「写一次 Prompt」变成「设计一个能自动跑起来的循环」调度什么时候跑、任务怎么发现、状态存在哪、产物怎么隔离、结果谁来验证、高风险操作谁来审批。我试过把这套东西接到自己的仓库里最直观的感受是以前是「我盯着 AI 改代码」现在是「AI 按循环跑我只看报告和审批」。适合谁适合已经在用 AI 编码工具、想让 Agent 从「单次对话」升级到「持续自动化」的开发者。不适合完全没接触过 Git 和 CLI 的小白因为你需要理解 worktree、状态文件、MCP 这些概念。这篇文章会按「问题场景 → 前置准备 → 可复制配置 → 验证请求 → 常见报错 → 工具入口」的顺序展开重点放在 CLI 工作流和 Git Worktree 隔离上最后说明 MCP 通道怎么统一接入 TaoToken。所有命令和配置都可以直接复制。2. loop-engineering 的 CLI 工作流与 Git Worktree 隔离机制loop-engineering 的核心不是某个单一命令而是一组 CLI 工具配合 Git Worktree 形成的闭环。理解这个闭环比记住命令更重要。先说 CLI 三件套。loop-init负责在目标仓库里生成 Loop 所需的目录结构、STATE.md 状态文件和 Pattern 配置loop-audit负责给仓库的「Loop 就绪度」打分告诉你缺什么loop-cost负责估算不同 Pattern 的 Token 预算。这三个命令构成了「初始化 → 评估 → 控成本」的基础链路。再说 Git Worktree 隔离。这是整个工程里最容易被忽略、但最关键的机制。传统做法是 Agent 直接在主干上改代码改坏了要回滚多个任务并行还会互相踩。loop-engineering 的做法是每次自动修复或迭代都在独立的 Git Worktree 里执行。Worktree 是 Git 的原生能力允许你在同一个仓库下挂载多个工作目录每个目录对应不同的分支互不干扰。具体到目录结构初始化后大致是这样your-repo/ ├── .loop/ │ ├── STATE.md # Loop 持久化状态记录每轮运行结果 │ ├── patterns/ │ │ └── daily-triage.yaml # Pattern 配置 │ ├── skills/ │ │ └── loop-triage.md # Skill 定义 │ └── logs/ │ └── 2025-01-01.jsonl # 运行日志 ├── worktrees/ │ ├── triage-20250101/ # 本轮迭代的隔离工作区 │ └── pr-fix-20250101/ # PR 修复的隔离工作区 └── scripts/ └── before-after-demo.shworktrees/目录下每个子目录都是一个独立的 Git Worktree对应一个临时分支。Agent 在里面改代码、跑测试、生成 diff验证通过后才由人工决定是否合并回主干。这样即使 Agent 改崩了删掉 worktree 就行主干完全不受影响。MCP 通道在这里的角色是「连接外部系统」。比如 Daily Triage 需要读 GitHub IssuePR Babysitter 需要读 PR 评论这些通过 MCP Connector 完成。项目建议初期只给只读权限避免 Agent 误操作。而 MCP 背后的模型调用可以统一走 TaoToken 的 API 通道这样你不需要在多个工具里分别配 Key。整个循环的运转逻辑是调度触发 → 发现任务 → 在 Worktree 里执行 → Verifier 验证 → 更新 STATE.md → 人工审批 → 合并或丢弃。每一轮都是独立的状态通过 STATE.md 传递产物通过 Worktree 隔离。3. 可复制配置从安装到 MCP 接入 TaoToken这一节给出可以直接复制的命令和配置片段。路径和原文保持一致你只需要替换仓库路径和 Key。第一步在目标 Git 仓库里初始化 Loop。进入你的仓库根目录执行cd /path/to/your-repo npx cobusgreyling/loop-init . --pattern daily-triage --tool claude-code--pattern指定生产模式--tool指定运行工具。初始化完成后你会看到 Loop Ready Score 和首次运行建议。如果只想先看看生成什么不加--pattern也行默认生成基础结构。第二步评估就绪度npx cobusgreyling/loop-audit . --suggest这个命令会检查 STATE.md、Skills、Verifier、安全策略、预算、运行日志等输出评分和改进建议。评分低不代表不能用只是说明自动化程度还不高。第三步估算 Token 成本npx cobusgreyling/loop-cost --pattern daily-triage第四步配置 MCP 接入 TaoToken。loop-engineering 的 MCP Connector 配置通常放在.loop/mcp.json或项目根目录的 MCP 配置文件里。以下是一个可复制的 JSON 片段把模型调用指向 TaoToken 的 API 通道{ mcpServers: { taotoken: { command: npx, args: [-y, taotoken/mcp-server], env: { TAOTOKEN_BASE_URL: https://taotoken.net/api, TAOTOKEN_API_KEY: sk-your-key-here, TAOTOKEN_MODEL: claude-sonnet-4-20250514 } } } }如果你用的是 Claude Code配置写在~/.claude/settings.json或项目级.claude/settings.json{ mcpServers: { taotoken: { command: npx, args: [-y, taotoken/mcp-server], env: { TAOTOKEN_BASE_URL: https://taotoken.net/api, TAOTOKEN_API_KEY: sk-your-key-here, TAOTOKEN_MODEL: claude-sonnet-4-20250514 } } } }如果你用的是 Codex配置写在~/.codex/auth.json{ base_url: https://taotoken.net/api, api_key: sk-your-key-here, model: claude-sonnet-4-20250514 }三件套必须齐全Base URL 指向https://taotoken.net/apiKey 换成你在控制台生成的Model ID 填你要用的模型。缺任何一个都会导致 401 或模型找不到。第五步本地运行参考实现验证配置node tools/loop-audit/dist/cli.js . --suggest bash scripts/before-after-demo.shbefore-after-demo.sh会跑一轮完整的 before/after 对比你能看到 Agent 在 Worktree 里改了什么、Verifier 怎么验证的、STATE.md 怎么更新的。4. 验证一轮完整循环从触发到 STATE.md 更新配置好之后最重要的是验证一轮循环真的能跑通。这一节给出完整的验证步骤和预期输出。先确认 Worktree 目录已经生成。执行git worktree list预期输出类似/path/to/your-repo abc1234 [main] /path/to/your-repo/worktrees/triage-20250101 def5678 [loop/triage-20250101]如果只看到 main说明 Worktree 还没创建需要先跑一轮 Loop。接着手动触发一轮 Daily Triage。参考实现里通常有一个入口脚本或者你可以直接调用 Skillnpx cobusgreyling/loop-init . --pattern daily-triage --tool claude-code初始化后按参考实现的说明运行 triage Skill。运行过程中Agent 会做几件事读取 STATE.md 了解上一轮状态通过 MCP 拉取 GitHub Issue在 Worktree 里生成巡检报告调用 Verifier 验证报告格式最后更新 STATE.md。一轮跑完后检查 STATE.mdcat .loop/STATE.md预期看到类似内容# Loop State ## Last Run - timestamp: 2025-01-01T08:00:00Z - pattern: daily-triage - worktree: worktrees/triage-20250101 - status: success - issues_found: 3 - report: .loop/logs/2025-01-01.jsonl ## Next Run - scheduled: 2025-01-02T08:00:00Z - mode: report-only再检查运行日志tail -n 5 .loop/logs/2025-01-01.jsonl预期看到每轮的详细记录包括模型调用、Token 消耗、验证结果。最后检查 Worktree 里的产物ls worktrees/triage-20250101/ git -C worktrees/triage-20250101 diff main如果一切正常你会看到 Agent 生成的报告文件以及和主干的 diff。确认没问题后可以手动合并或者直接删掉 Worktreegit worktree remove worktrees/triage-20250101这一轮验证的核心是Worktree 隔离生效、STATE.md 正确更新、Verifier 通过、人工审批环节保留。任何一环断了Loop 就不完整。5. 常见报错排查401、local proxy failed 与 reading choices实际跑的时候最容易卡在几个报错上。这一节对照真实报错给出排查路径。401 Unauthorized。这个最常见通常是 Key 没配对或者 Base URL 写错了。检查三件套Base URL 必须是https://taotoken.net/apiKey 必须是从控制台生成的完整字符串Model ID 必须是通道支持的模型。如果用的是 Claude Code检查settings.json里的env字段有没有拼错如果用 Codex检查auth.json的base_url和api_key。还有一种情况是 Key 过期了去控制台重新生成一个。local proxy failed。这个报错通常出现在 MCP Server 启动阶段说明本地代理进程没起来。先确认npx taotoken/mcp-server能单独跑起来TAOTOKEN_BASE_URLhttps://taotoken.net/api TAOTOKEN_API_KEYsk-your-key npx -y taotoken/mcp-server如果这条命令报错说明是 MCP Server 本身的问题检查 Node 版本建议 18和网络。如果单独能跑但集成到 loop-engineering 里报错检查配置文件路径对不对以及env字段有没有被正确传递。reading choices 相关报错。这个通常出现在模型返回格式不符合预期时比如返回了空响应或者非 JSON 格式。先检查 Model ID 是否写对有些模型名在通道里需要用完整 ID。再检查请求参数比如max_tokens设得太小会导致返回被截断。如果用的是流式响应确认客户端支持 SSE。OAuth 相关报错。如果你用的是需要 OAuth 的工具比如某些 GitHub 集成报错通常是因为 token 过期或权限不足。loop-engineering 建议初期只给只读权限所以检查你的 OAuth scope 是不是开太大了或者 token 是不是失效了。重新授权一次通常能解决。Worktree 创建失败。如果git worktree add报错常见原因是分支名冲突或者路径已存在。先清理git worktree prune rm -rf worktrees/triage-20250101再重新跑一轮。排查的核心思路是先确认单点能跑通MCP Server 单独启动、API 单独调用再确认集成配置路径、env、Model ID最后确认运行时状态Worktree、STATE.md、日志。不要一上来就怀疑框架大部分问题出在配置三件套上。6. 把循环跑起来TaoToken 通道与工具入口loop-engineering 的价值不在于它提供了多少 Pattern而在于它把「循环」这件事拆成了可复制的组件调度、状态、隔离、验证、审批。你可以只用其中一部分也可以全套接上。如果你想让 MCP 通道统一走 TaoToken先去控制台生成 Key然后按第 3 节的配置片段填好三件套。需要排障或接入细节看接入文档想先验证模型通不通用模型对话试一条请求如果是长期跑编码 Loop 或者 Agent 任务直接上 Coding Plan 更省心。工具入口按需取用生成 Key 和管理通道https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite接入文档和配置说明https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite验证模型对话https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite长期编码与 Agent 任务https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite控制台总览https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite最后一句话经验第一周一定用 report-only 模式让 Loop 只生成报告不自动改代码。等你看过几轮报告、确认 Verifier 靠谱了再逐步放开自动化程度。Worktree 隔离是你的安全网但前提是你真的去检查每一轮的 diff。