1. 长运行多智能体为什么总在第三小时崩掉如果你正在做多智能体框架大概率遇到过这种场景本地跑一个 Planner → Generator → Reviewer 的流水线前 40 分钟一切正常日志漂亮任务卡片一张张从 Inbox 滑到 Done。然后你出门吃个饭回来发现进程还在但 Generator 已经卡在第 87 轮工具调用上反复读同一个文件Reviewer 的输出开始自相矛盾QA 阶段直接超时。你花了 200 块 token换来一个半成品目录和一堆无法复现的日志。这不是模型能力问题而是长运行long-running场景下的工程骨架缺失。短任务靠 Prompt 就能糊过去长任务必须靠配置、状态机、可观测性和恢复策略撑住。Harness Engineering 这个说法最近被讨论得很多但大部分文章停在“把 Generator 和 Evaluator 分开”这种架构层面真正落地时你会发现配置文件写不对骨架搭不起来验证动作缺失多智能体就是一堆各说各话的进程。这篇聚焦一件事给你一套可复制的config.toml/settings.json骨架配合启动自检和长稳验证动作让你在本地能复现一套可观测、可恢复的多智能体运行结构。适合已经跑过单 Agent、准备上多智能体流水线的工程师也适合被“跑三小时就崩”折磨过的团队。下面所有配置都可以直接抄参数我会解释为什么这么设。2. 前置模型接入与密钥准备多智能体框架的第一道坎不是编排是每个 Agent 都要能稳定拿到模型。Planner 用高推理模型、Generator 用高吞吐模型、Reviewer 用独立模型做交叉验证——这意味着你的框架要同时管理多个模型端点、多把 Key、多套限流策略。如果每个 Agent 各自硬编码 endpoint配置会迅速失控。我建议把模型接入统一收敛到一个兼容 OpenAI 协议的中转层框架侧只认base_urlapi_keymodel三件套。这样切换模型、加新 Agent、做 A/B 对比都只改配置不改代码。TaoToken 就是按这个思路用的一个 API 地址覆盖多家模型Key 在控制台统一管理框架里只维护一份settings.json。具体操作路径注册并登录后进控制台创建 API Keyhttps://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite模型对话调试入口用来确认某个模型名是否可用https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite接入文档协议、参数、错误码https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite如果你要跑长期编码 / Agent 流水线Coding Plan 更划算https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewriteAPI 基地址统一用https://taotoken.net/api注意API 地址不带 UTM 参数直接写死即可。拿到 Key 后不要写进代码放进环境变量或本地settings.json后面骨架里会体现。注意多智能体框架里最忌讳把 Key 写进每个 Agent 的 Prompt 或日志。一旦某个 Agent 把配置 dump 到输出里你的 Key 就进了事件流。所有密钥只走环境变量注入。3. 可复制的配置骨架这一节是全文核心。我把骨架拆成三层全局 settings.json模型与密钥、config.tomlAgent 与流水线、state 目录约定持久化。三层分离的好处是换模型不动编排改编排不动密钥恢复状态不动配置。3.1 settings.json模型端点与密钥{ providers: { default: { base_url: https://taotoken.net/api, api_key_env: TAOTOKEN_API_KEY, timeout_seconds: 120, max_retries: 3, retry_backoff: exponential } }, models: { planner: { provider: default, name: claude-opus-4-6, max_turns: 20 }, generator: { provider: default, name: claude-sonnet-4-6, max_turns: 40 }, reviewer: { provider: default, name: gpt-5, max_turns: 15 }, security: { provider: default, name: claude-opus-4-6, max_turns: 15 }, qa: { provider: default, name: claude-sonnet-4-6, max_turns: 25 }, debugger: { provider: default, name: claude-sonnet-4-6, max_turns: 30 } }, runtime: { state_dir: ./.harness/state, log_dir: ./.harness/logs, snapshot_dir: ./.harness/snapshots, autosave_interval_seconds: 30, event_buffer_size: 200 } }几个关键取舍api_key_env而不是api_key——密钥永远从环境变量读配置文件可以进 Git密钥不行。max_turns是每个 Agent 的硬预算不是建议值。Planner 给 20 轮足够拆解Generator 给 40 轮是因为它要反复读写文件Reviewer 只给 15 轮——审查者轮次越少越不容易陷入自我说服。autosave_interval_seconds: 30是长稳验证里最容易被忽略的参数后面会讲为什么是 30 而不是 60。3.2 config.tomlAgent 定义与流水线编排[harness] name longrun-multiagent version 0.1.0 max_pipeline_hours 6 graceful_shutdown_seconds 15 [[agents]] id planner role plan model planner tools [Read, Glob, Grep] writes false output_contract json_task_list prompt_profile ambitious_scope [[agents]] id generator role generate model generator tools [Read, Write, Edit, Bash, Glob, Grep] writes true output_contract diff_summary prompt_profile incremental_testable [[agents]] id code_reviewer role review model reviewer tools [Read, Bash, Glob, Grep] writes false output_contract verdict prompt_profile critical_skeptical [[agents]] id security_reviewer role review model security tools [Read, Bash, Glob, Grep] writes false output_contract verdict prompt_profile critical_skeptical [[agents]] id qa_engineer role verify model qa tools [Read, Bash, Glob, Grep] writes false output_contract verdict prompt_profile strict_acceptance [[agents]] id debugger role fix model debugger tools [Read, Write, Edit, Bash, Glob, Grep] writes true output_contract minimal_patch prompt_profile minimal_fix [pipeline] order [planner, generator, code_reviewer, security_reviewer, qa_engineer] parallel_review true on_review_fail route_to_debugger on_qa_fail back_to_review max_debug_loops 3 [persistence] snapshot_before_task true snapshot_after_task true save_on_event true save_on_exit true keep_execution_history 20这份骨架里有三个设计决策值得单独说writes false是评审独立性的硬约束。代码审查和安全审查两个 Agent 都没有写权限。这不是权限洁癖而是防止评审者从“标记问题”滑向“顺手修一下然后放行”。一旦评审者能改代码它的判断就会偏向“改完就算过”VERDICT 协议就失效了。parallel_review true让功能审查和安全审查并行。串行的话安全问题会被功能问题掩盖——功能没过安全审查根本没机会跑。并行执行、各自独立出 VERDICT任何一方 FAIL 都能单独拦截。max_debug_loops 3是防死循环的闸门。Debugger 修完回到评审评审再 FAIL 再修理论上可以无限循环。三轮之后强制升级为人工介入避免一个任务吃掉整晚的 token。3.3 状态目录约定.harness/ ├── state/ │ ├── sprint_board.json # 任务卡片与状态 │ ├── executions/ # 每个 Agent 最近 20 次执行 │ └── chat_history.json # 对话与需求记录 ├── logs/ │ ├── events.ndjson # 事件流NDJSON 便于追加 │ └── errors.ndjson └── snapshots/ ├── task_001_before.json # 文件路径大小mtime └── task_001_after.json快照只存元信息路径、大小、修改时间不存文件内容。这样一次快照几 KB几百个任务也不会撑爆磁盘同时 Diff 时能精确识别“这次任务改了哪些文件”。这是多任务共享同一工作目录时唯一可靠的归因方式。4. 启动自检与长稳验证配置写完不代表能跑。长运行框架必须在启动阶段做自检在运行阶段做长稳验证。这两步是区分“能跑 demo”和“能跑生产”的分水岭。4.1 启动自检脚本#!/usr/bin/env bash set -euo pipefail echo [1/5] 检查环境变量 : ${TAOTOKEN_API_KEY:?TAOTOKEN_API_KEY 未设置} echo API Key 已注入长度 ${#TAOTOKEN_API_KEY} echo [2/5] 检查配置文件 python -c import json,sys; json.load(open(settings.json)); print( settings.json OK) python -c import tomllib; tomllib.load(open(config.toml,rb)); print( config.toml OK) echo [3/5] 检查状态目录 mkdir -p .harness/{state,logs,snapshots} test -w .harness/state echo state 目录可写 echo [4/5] 探测模型端点 curl -sS -o /dev/null -w HTTP %{http_code} in %{time_total}s\n \ -X POST https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer ${TAOTOKEN_API_KEY} \ -H Content-Type: application/json \ -d {model:claude-sonnet-4-6,messages:[{role:user,content:ping}],max_tokens:8} echo [5/5] 校验 Agent 工具权限 python - PY import tomllib cfg tomllib.load(open(config.toml,rb)) for a in cfg[agents]: if a[role] review and a.get(writes): raise SystemExit(f评审 Agent {a[id]} 不应有写权限) print( 权限矩阵 OK) PY echo 自检通过可以启动流水线这个脚本的价值在于把配置错误挡在启动前。我见过太多团队是跑到第 40 分钟才发现 Reviewer 有写权限、或者 Key 没注入导致某个 Agent 静默失败。自检 10 秒省下的是几小时的重跑。4.2 长稳验证30 秒自动保存 崩溃恢复长稳验证的核心是模拟崩溃并验证恢复。做法很简单跑一个 20 分钟以上的流水线中途kill -9主进程然后重启看状态是否完整恢复。# recovery_check.py import json, pathlib, time STATE pathlib.Path(.harness/state) board json.loads((STATE / sprint_board.json).read_text()) running [t for t in board[tasks] if t[status] in_progress] done [t for t in board[tasks] if t[status] done] failed [t for t in board[tasks] if t.get(qa_status) qa-failed] print(f任务总数: {len(board[tasks])}) print(f已完成: {len(done)}) print(f中断: {len(running)} - 重启后应标记为 interrupted) print(fQA 拦截: {len(failed)}) # 校验事件流完整性 events [json.loads(l) for l in open(.harness/logs/events.ndjson)] last_ts max(e[ts] for e in events) gap time.time() - last_ts print(f最后事件距今: {gap:.1f}s应 30s验证自动保存生效) assert gap 60, 自动保存间隔异常检查 autosave_interval_seconds为什么自动保存设 30 秒而不是 60 秒因为长运行任务里单个 Agent 的一次工具调用平均 15–25 秒。60 秒间隔意味着崩溃时可能丢掉 2–3 次工具调用的结果恢复后 Agent 会重复执行token 成本翻倍。30 秒是“最多丢一次调用”的临界值。4.3 可观测性事件流格式{ts: 1730000000.12, agent: generator, type: tool_use, tool: Bash, input_digest: a1b2c3, turn: 12} {ts: 1730000003.45, agent: generator, type: text, content: Implementation complete, turn: 13} {ts: 1730000005.01, agent: code_reviewer, type: verdict, value: FAIL, reason: 边界条件未覆盖, turn: 4} {ts: 1730000008.77, agent: qa_engineer, type: verdict, value: PASS, turn: 6}事件流用 NDJSON 追加写每行一个事件崩溃时最多丢最后一行。verdict事件是流水线自动决策的唯一依据——没有 VERDICT 的任务不允许进入 Done。这比“代码看起来还行”这种主观判断可靠得多。5. 本篇常见错排查报错一401 Unauthorized但 Key 明明是对的。九成是环境变量没传进子进程。多智能体框架通常用 subprocess 启动每个 Agent父进程的export不会自动继承。检查启动命令是否显式传递或在 settings.json 里确认api_key_env名字和实际变量名一致。报错二Generator 卡在第 N 轮不动日志无新事件。先看max_turns是否设得过大。40 轮是经验值超过 60 轮后模型对早期决策的记忆明显衰减容易陷入“读文件→改一点→再读”的循环。把max_turns降到 40并在 Prompt 里加“每步产出必须可验证”。报错三重启后任务状态错乱Done 的任务又回到 In Progress。这是持久化写入顺序问题。正确顺序是先写sprint_board.json的临时文件fsync后再原子 rename 覆盖。直接原地写会在崩溃时留下半截 JSON。报错四Reviewer 总是 PASS质量门禁形同虚设。检查两点一是 Reviewer 是否有写权限有就删掉二是 Prompt 里有没有“critical and skeptical”这类校准词。评审者的宽大倾向是默认行为必须显式对抗。另外建议 Reviewer 和 Generator 用不同模型同模型自评几乎必然宽松。报错五qa-failed任务堆积在 Review 列不流转。这是设计如此不是 Bug。检查on_qa_fail是否配成back_to_review以及max_debug_loops是否耗尽。如果三轮 debug 后仍 FAIL框架应标记为needs_human并停止重试而不是无限循环烧 token。报错六事件流文件涨到几百 MB。event_buffer_size只控制内存缓冲不控制磁盘。给events.ndjson加按天轮转或只保留最近 200 条到 state历史归档到冷存储。长运行框架的日志治理和状态治理同等重要。6. 把骨架跑起来之后配置骨架、自检脚本、恢复验证这三样凑齐你就有了一套能扛住 6 小时运行的多智能体结构。接下来最该做的不是加更多 Agent而是先让现有流水线稳定跑通 10 次完整任务观察事件流里的工具调用分布——如果 Generator 大量调 Bash 却很少 Write说明它在用脚本绕路生成代码这是需要干预的信号。模型接入层建议保持单一入口方便后续按 Agent 角色切换模型做对比实验。需要长期跑编码和 Agent 流水线的话Coding Plan 的额度模型比按量计费更适合这种持续消耗场景https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite。接入细节和错误码对照看文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite。Key 管理和新建入口在控制台https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite。最后一句实操建议先把max_debug_loops设成 1 跑一遍你会立刻看到哪些任务在评审阶段反复失败。这些失败点就是你 Prompt 和完成标准定义最薄弱的地方比任何架构讨论都直接。
