1. 长程任务 Agent 为什么总在第三轮开始跑偏如果你正在做长程任务 Agent大概率遇到过这种场景第一轮 Agent 干得挺漂亮第二轮还能接上到第三轮开始重复劳动第五轮开始自己骗自己第十轮直接跑飞。你盯着日志看半天发现它既不是模型不行也不是 prompt 写得差而是整个循环系统缺了几根骨头。这就是 Loop 工程要解决的问题。Loop 不是“让 Agent 反复跑”而是“让 Agent 自己识别差距、自己验证产出、自己调整策略”。它和 Cron Job 的根本区别在于Cron 关心“做了没”Loop 关心“成了没”。一个定时备份脚本失败七次没人管那是 Cron一个“让备份成功率 100%”的系统失败后自动分析原因、换策略、再试那才是 Loop。这篇聚焦 Loop 工程的五要素架构与运转机理把 Automations、Worktrees、Skills、Connectors、Sub-Agents 加上贯穿全局的 State 拆开讲清楚然后给你一份可以直接复制的config.toml骨架配上 TaoToken 统一 Key/API 通道的配置示例最后跑一次完整的循环链路验证。适合已经在写 Agent、但被“多轮迭代失控”折磨过的开发者也适合想把单次 Agent 升级成长程任务系统的团队。我试过最笨的办法把 Agent 塞进一个 while 循环里反复跑结果第三轮就开始重复提交同一个补丁。后来才明白问题不在循环本身在于循环里没有“记忆”和“质疑”。2. TaoToken 前置统一 Key 与 API 通道在搭 Loop 之前先把模型调用通道理顺。长程任务 Agent 的一个特点是一次任务可能跑几十轮每轮都要调模型如果每轮都换 Key、换 endpoint、换计费口径排障会变成噩梦。TaoToken 在这里的作用是提供一个统一的 API 通道把不同模型的调用收敛到一个 Key 上方便在 Loop 里做 token 预算控制和调用审计。官网入口https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentAPI 基址https://taotoken.net/api你需要准备的东西不多一个 TaoToken 账号、一个 API Key、以及本地能跑 Python 或 Node 的环境。Key 的创建入口在控制台的 API Keys 页面建议给 Loop 单独建一个 Key不要和日常调试混用这样后面做 token 上限统计时能一眼看出是哪个 Loop 烧的。注意Loop 场景下建议给每个长程任务单独分配 Key 或至少单独打标签否则一个失控的 Loop 能在几小时内把月度预算烧穿。这不是危言耸听是真实踩过的坑。拿到 Key 之后先做一次最小连通性验证确认通道可用再往 Loop 里塞。这一步别省否则后面 Loop 跑飞了你分不清是模型问题还是网络问题。export TAOTOKEN_API_KEYsk-你的key curl -s https://taotoken.net/api/v1/models \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ | head -c 500返回模型列表就说明通道通了。如果返回 401检查 Key 是否复制完整如果超时检查本地网络出口。这一步过了再往下走。3. 五要素架构Loop 的骨架长什么样Loop 工程的五要素不是五个零件是五条契约。缺任何一条Loop 都会从“自动化系统”退化成“会反复犯错的 Agent”。Automations 是起搏器决定“何时启动”。它不参与 PDCA 循环本身只负责在合适时机把任务塞进队列。Worktrees 是隔离层保证并发 Agent 不互相覆盖代码。Skills 是记忆层把项目约定、常见陷阱、历史经验注入每一轮。Connectors 是手脚让 Agent 能真的读 Issue、写 PR、查日志。Sub-Agents 是监督者独立评估产出是否真的达标。State 是贯穿所有要素的介质把每一轮的 Plan、Do、Check、Act 记录外置。这五者正交任何一个都不能被另一个替代。你不能用“更聪明的 Agent”替代 Automations因为 Agent 不会自己决定何时启动不能用“更全的 Skills”替代 Connectors因为知识不能替代动作不能用“更严的 Sub-Agents”替代 Worktrees因为评估 Agent 也需要独立环境。3.1 PDCA 在 Loop 里的具体落法Plan 阶段的职责不是“列步骤”是“识别差距 设计验证”。差距要结构化比如不是“修 flaky 测试”而是“login flow 测试失败率 12%”。验证要在 Plan 阶段就设计好Check 阶段直接调用这叫验证前置。Do 阶段除了执行还要记录关键决策点。每次工具调用附一句 reason 和 observation下一轮 Plan 读 State 时才知道“为什么改这个文件而不是那个”。Check 阶段是 PDCA 的灵魂。它不是看 exit code是对照目标评估。exit 0 经常撒谎——测试全绿不等于产品可用。Check 要输出三态 verdictpassed / failed / needs_human每个 criterion 都要给 evidence。Act 阶段不是“通过就退出失败就重试”是“基于失败调整策略”。它要生成 next_iteration_hint告诉下一轮 Plan“别再走 pool.ts 这条死路看看 Redis”。3.2 Sub-Agents 的 Maker-Checker 分离Sub-Agents 必须是“一次性无状态”的。每次评估都是新进程、新会话、新 prompt。如果评估 Agent 和执行 Agent 在同一会话里评估 Agent 会被执行 Agent 的叙事带跑失去独立性。这是 Maker-Checker 分离的工程铁律不是性能考虑。评估 Agent 最好用不同的模型。执行用 Sonnet评估用 OpusOpus 更强能挑出 Sonnet 的偏差。任务越关键独立性要求越高。修 flaky 测试这种非关键任务同模型不同 prompt 够用合并到 main、删除生产数据这种关键操作必须不同模型加不同 worktree。4. 可复制配置config.toml 骨架与 TaoToken 接入下面这份config.toml是 Loop 工程的骨架可以直接复制改。它把五要素和 State 都显式声明出来方便你逐项对照。# loop-config.toml # Loop 工程五要素 State 配置骨架 [loop] name flaky-test-fixer goal auth-service E2E 测试连续 50 次重跑全绿 max_iter 200 max_token 2000000 max_time_hours 12 [automations] # 起搏器定时 事件双触发 schedule */10 * * * * # 每 10 分钟巡检一次 event_trigger ci_failure # CI 失败时立即触发 debounce_seconds 30 # 事件合并窗口防 Loop 风暴 lock_key flaky-fixer-lock # 并发锁防多实例并行 [worktrees] # 隔离层每个 Agent 独立 worktree base_branch main branch_pattern fix/flaky-{timestamp} cleanup_after_merge true [skills] # 记忆层项目知识注入 files [ CLAUDE.md, SKILLS.md, docs/flaky-patterns.md ] inject_every_iteration true # 每轮重新注入防漂移 [connectors] # 手脚外部系统连接 github_mcp true log_query_api https://internal.example.com/logs slack_webhook https://hooks.slack.com/services/xxx [sub_agents] # 监督者Maker-Checker 分离 maker_model claude-sonnet checker_model claude-opus checker_worktree independent # 评估 Agent 独立 worktree checker_session fresh # 每次评估新会话 confidence_threshold 0.7 # 低于此值转 needs_human [state] # 持久化贯穿所有要素 state_file STATE.md log_db loop-logs.sqlite format markdown # 人类可读 AI 可解析 [model] # TaoToken 统一通道 provider taotoken base_url https://taotoken.net/api api_key_env TAOTOKEN_API_KEY default_model claude-sonnet这份配置的关键点max_iter、max_token、max_time_hours三个上限是硬约束任何一个触发就强制退出。debounce_seconds防事件风暴lock_key防 Loop 风暴。inject_every_iteration true保证每轮重新注入 Skills防止 Agent 在长循环里忘记项目约定。4.1 TaoToken 通道在 Loop 里的接入把 TaoToken 的调用封装成一个函数Loop 里所有模型调用都走它方便统一做 token 统计和预算控制。import os import httpx TAOTOKEN_BASE https://taotoken.net/api API_KEY os.environ[TAOTOKEN_API_KEY] class TokenBudget: def __init__(self, max_token): self.max_token max_token self.used 0 def consume(self, n): self.used n if self.used self.max_token: raise RuntimeError(ftoken budget exceeded: {self.used}/{self.max_token}) budget TokenBudget(max_token2_000_000) def call_model(prompt, modelclaude-sonnet, max_tokens4096): resp httpx.post( f{TAOTOKEN_BASE}/v1/messages, headers{ Authorization: fBearer {API_KEY}, Content-Type: application/json, }, json{ model: model, max_tokens: max_tokens, messages: [{role: user, content: prompt}], }, timeout120, ) resp.raise_for_status() data resp.json() usage data.get(usage, {}) total usage.get(input_tokens, 0) usage.get(output_tokens, 0) budget.consume(total) return data[content][0][text]这个封装做了两件事统一走 TaoToken 通道统一做 token 预算控制。Loop 里任何一次模型调用都经过call_model预算超了直接抛异常Loop 捕获后走 needs_human 流程。4.2 State 文件的格式State 用 Markdown人类可读、AI 可解析、版本可 diff。每轮迭代追加一段不要覆盖。# STATE.md ## Iteration 47 - gap: login flow 失败率 12% - hypothesis: 数据库连接池 race condition (confidence 0.7) - plan: 修改 src/db/pool.ts加 mutex - do_log: - read src/db/pool.ts: pool 在首次调用时 lazy 初始化无锁 - modify src/db/pool.ts: 加 async mutex - test: npm test auth-e2e -- --rerun50 - check: - patch_targets_root_cause: true - no_sleep_or_retry_hack: true - failure_rate_after: 0% - verdict: passed (confidence 0.85) - next_iteration_hint: 无目标达成这个格式的关键是next_iteration_hint字段。Act 阶段必须填填不出就转 needs_human。强迫 Agent 写 hint是防止无脑重试的关键。5. 验证请求跑通一次完整循环链路配置写完跑一次最小循环验证。目标不用复杂就验证“Loop 能启动、能调模型、能写 State、能终止”。5.1 最小循环脚本import time from pathlib import Path STATE_FILE Path(STATE.md) def assess_gap(goal, state): # 简化版读 State 判断是否达成 if verdict: passed in state: return 0 return 1 def make_plan(gap, state): return f当前差距 {gap}请基于 State 生成下一步计划 def execute(plan): return call_model(plan) def verify(result, goal): # 简化版让独立模型评估 verdict call_model( f目标{goal}\n产出{result}\n请判断是否达成输出 passed 或 failed, modelclaude-opus, ) return passed in verdict.lower() def loop(goal, max_iter5): state STATE_FILE.read_text() if STATE_FILE.exists() else for i in range(max_iter): gap assess_gap(goal, state) if gap 0: print(f[iter {i}] 目标达成退出) return SUCCESS plan make_plan(gap, state) result execute(plan) passed verify(result, goal) record f\n## Iteration {i}\n- plan: {plan}\n- result: {result[:200]}\n- verdict: {passed if passed else failed}\n with STATE_FILE.open(a) as f: f.write(record) state record if passed: print(f[iter {i}] 验证通过退出) return SUCCESS return MAX_ITER_REACHED if __name__ __main__: outcome loop(用一句话说明 Loop 工程的核心价值) print(fLoop 结束{outcome})5.2 预期输出跑起来后你应该看到类似这样的输出[iter 0] 验证通过退出 Loop 结束SUCCESS同时STATE.md里会多出一段 Iteration 0 的记录包含 plan、result、verdict。如果第一次没通过会继续跑第二轮直到 max_iter 或验证通过。这个最小验证跑通了说明四件事TaoToken 通道可用、模型调用正常、State 能写、循环能终止。这四件事是 Loop 工程的地基地基稳了再往上加 Worktrees、Sub-Agents、Connectors。5.3 验证 Sub-Agents 独立性把verify函数里的模型换成和执行不同的模型再跑一次。观察评估结果是否和执行 Agent 的自我评价一致。如果不一致说明 Maker-Checker 分离起作用了如果永远一致检查是不是评估 Agent 和执行 Agent 共享了会话上下文。def verify(result, goal): # 强制用不同模型 新会话 verdict call_model( f你是独立评估 Agent。目标{goal}\n产出{result}\n f请严格判断是否达成不要被产出的看起来合理欺骗。输出 passed 或 failed。, modelclaude-opus, # 与 maker 的 sonnet 不同 ) return passed in verdict.lower()6. 本篇常见错排查6.1 Loop 跑飞token 烧穿最常见的原因是没设max_token硬上限或者设了但没在每次调用后检查。检查TokenBudget.consume是否真的在每次call_model后被调用。另一个原因是max_iter设得太大比如 10000Loop 失控了也要跑完才停。建议max_iter不超过 500。6.2 每轮重复尝试同一个失败方案这是 State 没写全或没读全。检查STATE.md里是否记录了next_iteration_hint以及下一轮 Plan 是否真的读了 State。常见错误是 State 写了但 Plan 阶段没读Agent 每轮从零开始自然重复。6.3 评估 Agent 永远说 passed检查评估 Agent 和执行 Agent 是否共享会话。如果共享评估 Agent 会被执行 Agent 的叙事带跑。修复方法是每次评估都开新会话、新进程最好换模型。另一个原因是评估 prompt 太宽松没有要求给 evidence。加上“每个 criterion 必须给证据”能显著提升评估质量。6.4 Loop 风暴同一任务被反复启动Automations 的debounce_seconds和lock_key没配好。检查事件触发是否有合并窗口以及是否有并发锁。没有锁的情况下多个 Loop 实例会同时启动互相覆盖代码。6.5 目标漂移Agent 跑去做无关的事Skills 没有每轮重新注入。长循环里 Agent 会逐渐忘记原始目标被中间细节带跑。把inject_every_iteration设为 true每轮重新读 PROMPT 和 Skills把 Agent 拉回原点。6.6 TaoToken 调用返回 401 或超时401 通常是 Key 没复制完整或环境变量没生效。超时检查本地网络出口和timeout参数。Loop 场景下建议把timeout设到 120 秒以上因为长 prompt 的响应时间会更长。7. 把 Loop 跑起来之后Loop 工程的核心不是“让 Agent 反复跑”是“设计 Agent 该在何时启动、何时停下、何时被质疑”。五要素加 State 是骨架PDCA 是呼吸节律Sub-Agents 是免疫系统。骨架搭好节律调顺免疫系统在线Loop 才能从“会反复犯错的 Agent”变成“会自己迭代的系统”。下一步可以做的把 Worktrees 从 git worktree 升级到 Docker 隔离把 Connectors 从 GitHub MCP 扩展到内部日志系统把 Sub-Agents 从单评估 Agent 扩展到多评估 Agent 投票。每加一个要素Loop 的自治度上一个台阶。如果你在搭 Loop 的过程中卡在模型调用通道上可以先用 TaoToken 的统一 Key 把通道理顺再往上叠五要素。通道稳了排障才有意义。模型对话入口https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentmodel_chatCoding Plan 入口https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentcoding_plan控制台入口https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentconsoleAPI Keys 入口https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentapi_keys接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentdocClaudeCodeAnthropic 入口https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentclaude_code
