为什么你的 Agent 总是跑偏？问题可能根本不在模型，而在 Harness 与 Context Rot

1. 先别急着换模型Agent 跑偏的现场长什么样如果你正在做多步 Workflow 的 Agent大概率遇到过这种画面模型明明不弱Prompt 也改了好几版但任务跑到第三步就开始自作主张——该查数据库的时候去改文件该停下来确认的时候直接删记录最后给你一份看起来很像样、实际完全跑偏的结果。你以为是模型不够聪明于是换更大的模型、加更长的上下文、堆更多工具结果跑偏的概率只是从 70% 降到 60%问题依旧。这篇要讲的判断是Agent 跑偏多数时候不是模型能力问题而是 Harness 控制流和 Context Rot 上下文腐化这两个工程根因。Harness 指的是围绕 Agent 运行的那套控制流、验收标准、回退机制和反馈信号Context Rot 指的是上下文越堆越长之后关键信号被日志、废弃方案、历史尝试稀释掉的现象。这两个东西不解决换再贵的模型也只是让跑偏的过程更流畅。适合谁看正在用 Claude Code、Cursor、自建 Agent 框架跑多步 Workflow 的开发者已经接了模型 API 但发现轨迹不稳定的人以及准备把 Agent 从 demo 推到生产、被看起来在努力实际在狂奔坑过的人。下面我会先讲清楚跑偏的工程根因再给一套可复制的config.toml/settings.json骨架和统一 Key 接入配置最后用三步验证动作让你自己复现、替换、对比。2. 跑偏的两个根因Harness 控制流与 Context Rot2.1 Harness 不是框架是控制流的约束层很多人把 Harness 理解成Agent 框架其实更准确的说法是Harness 是决定 Agent 每一步能不能继续、要不要回退、算不算成功的那层逻辑。它包含四件事明确的验收标准、执行边界、反馈信号、失败后的回退机制。我见过最典型的跑偏场景是这样的一个负责整理工单的 Agent任务是读取新工单→分类→写入对应队列。代码里只写了调用模型判断分类没写如果分类结果不在枚举值内怎么办。结果模型偶尔返回一个建议人工复核这种自由文本后面的写入步骤直接把它当队列名任务静默失败。这不是模型错是 Harness 没定义边界。控制流的核心问题是下一步由谁决定。Workflow 里路径是代码写死的Agent 里路径是模型动态决定的。一旦你把控制权交给模型就必须在 Harness 里补上模型决定不了的时候怎么办。缺了这层模型越强跑偏得越高效。2.2 Context Rot上下文不是越长越好Context Rot 的直观理解把上下文想象成一张办公桌。一开始只摆当前任务最重要的资料效率很高但如果不断往上堆日志、历史尝试、废弃方案、无关文档真正有价值的信息就被埋掉了。模型不是没看到而是注意力被稀释了。在多步 Workflow 里这个问题会被放大因为每一步都会往上下文里追加工具返回结果。跑到第十步的时候上下文里可能塞了九次成功日志、三次失败重试、两版废弃方案而当前真正要判断的那条信息只占几十个 token。模型要在这一堆噪声里找信号出错概率自然上升。合理的做法是分层管理上下文常驻层放项目规则和禁止事项按需加载层放技能文档运行时层只放当前任务状态记忆层放跨会话经验系统层把能交给代码的确定性逻辑拿走。核心原则一句话能不用上下文解决的问题就不要塞给模型记。3. TaoToken 前置统一 Key 接入让 Harness 配置可复制在给配置骨架之前先说接入层。多步 Workflow 的 Agent 经常要同时调不同模型——规划用强模型、执行用快模型、评估用另一个模型。如果每个模型一套 Key、一套 base_urlHarness 配置会变得很难维护换环境时到处改。我的做法是用 TaoToken 做统一入口一个 Key 覆盖多个模型base_url 指向https://taotoken.net/api这样 Harness 里只需要维护一份凭证配置。官网在https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content注册后在控制台创建 API Key 即可。具体操作路径进入控制台https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite在 API Keys 页面https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite新建一个 Key。这个 Key 就是后面所有配置里api_key字段的值。如果你只是想先验证模型通不通可以直接用模型对话页面https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite发一条消息确认链路正常再往下配 Harness。注意Key 只放在环境变量或本地配置文件里不要硬编码进提交到仓库的代码。下面骨架里我用${TAOTOKEN_API_KEY}占位。4. 可复制配置config.toml 与 settings.json 骨架4.1 config.tomlHarness 控制流骨架这份config.toml的重点不是模型参数而是把控制流的边界写清楚最大步数、每步验收、失败回退、上下文裁剪策略。# config.toml —— Agent Harness 控制流骨架 [provider] base_url https://taotoken.net/api api_key ${TAOTOKEN_API_KEY} # 规划用强模型执行用快模型评估单独一个 model_planner claude-sonnet-4-5 model_executor claude-haiku-4-5 model_evaluator claude-sonnet-4-5 [harness] # 控制流硬边界超过步数强制停止避免无限循环 max_steps 12 # 每步必须产出结构化结果否则视为失败 require_structured_output true # 失败重试上限超过则回退到上一个稳定状态 max_retries_per_step 2 # 回退策略none / last_stable / abort on_failure last_stable [harness.verification] # 验收标准每步结束后由 evaluator 判断是否达标 enabled true # 达标阈值低于则触发重试或回退 pass_threshold 0.8 # 评估维度 criteria [task_alignment, output_schema_valid, no_side_effect_leak] [context] # Context Rot 治理分层 裁剪 strategy layered # 运行时层最大 token超过则压缩历史日志 runtime_max_tokens 6000 # 历史步骤只保留摘要不保留原始返回 history_mode summary # 工具返回结果超过该长度则截断并摘要 tool_result_max_chars 1200 [context.layers] resident [project_rules, forbidden_actions] on_demand [skill_docs, domain_knowledge] runtime [current_task_state, step_summary] memory [cross_session_experience]几个关键点解释一下。max_steps是防止 Agent 在错误方向上无限狂奔的第一道闸require_structured_output强制每步返回可校验的结构避免自由文本污染后续步骤on_failure last_stable让失败时回到上一个已知稳定状态而不是带着错误继续往下跑。[context]段是专门治 Context Rot 的history_mode summary意味着历史步骤只留摘要原始工具返回不往上下文里堆。4.2 settings.json工具与权限边界工具设计的原则是面向任务目标而不是面向底层 API。下面这份settings.json把工具收敛成一步能完成目标的粒度同时限制副作用。{ tools: [ { name: read_ticket, description: 读取指定工单的完整内容。当需要了解工单详情时使用不要用它来修改工单。, input_schema: { type: object, properties: { ticket_id: { type: string } }, required: [ticket_id] }, side_effect: none }, { name: classify_and_route, description: 将工单分类并写入对应队列一步完成。当分类结果确定时使用分类不确定时不要调用先请求人工确认。, input_schema: { type: object, properties: { ticket_id: { type: string }, queue: { type: string, enum: [billing, tech, refund] } }, required: [ticket_id, queue] }, side_effect: write, requires_confirmation: true } ], permissions: { allow_write: true, require_confirmation_for: [classify_and_route], forbidden_actions: [delete_ticket, bulk_update] }, context_policy: { drop_tool_raw_after_steps: 3, keep_only_summary: true } }注意classify_and_route的queue用了enum约束模型只能从三个值里选选不出来就得走确认流程——这就是把 Harness 的边界写进工具定义里。drop_tool_raw_after_steps: 3是 Context Rot 治理的另一半三步之前的工具原始返回直接丢掉只留摘要。5. 三步验证复现跑偏、替换 Harness、对比轨迹配置写完不算数得用三步动作验证它真的有效。5.1 第一步复现跑偏先在不改任何配置的情况下用同一批任务跑一遍记录轨迹。重点是记录每步的输入上下文长度、模型决策、工具调用、最终结果。你可以用一个简单的日志钩子import json, time def log_step(step_id, context_tokens, decision, tool_call, result): record { step: step_id, ts: time.time(), context_tokens: context_tokens, decision: decision, tool: tool_call, result_ok: result.get(ok, False), } with open(trace_before.jsonl, a, encodingutf-8) as f: f.write(json.dumps(record, ensure_asciiFalse) \n)跑 10 个任务统计跑偏率最终结果不符合验收标准的比例和平均步数。这一步的目的是拿到基线不然你没法证明后面改配置有用。5.2 第二步替换 Harness 配置把第 4 节的config.toml和settings.json接进去重点确认三件事max_steps生效、require_structured_output生效、history_mode summary生效。验证方式很简单故意让模型在某一步返回自由文本看 Harness 是否拦截并触发重试。# 用环境变量注入 Key避免硬编码 export TAOTOKEN_API_KEY你的Key # 跑同一批任务输出到 trace_after.jsonl python run_agent.py --config config.toml --settings settings.json --out trace_after.jsonl5.3 第三步对比轨迹稳定性对比trace_before.jsonl和trace_after.jsonl看三个指标跑偏率、平均步数、上下文 token 峰值。正常情况下跑偏率应该明显下降平均步数可能略降因为回退机制避免了无效重试上下文 token 峰值应该显著下降因为历史只留摘要。import json def load(path): return [json.loads(l) for l in open(path, encodingutf-8)] before, after load(trace_before.jsonl), load(trace_after.jsonl) def stats(records): total len(records) bad sum(1 for r in records if not r[result_ok]) peak max(r[context_tokens] for r in records) return {total: total, bad_rate: bad / total, peak_tokens: peak} print(before:, stats(before)) print(after:, stats(after))如果 after 的bad_rate没降先别怀疑模型回去检查 Harness 的验收标准是不是写得太松或者pass_threshold设得太低。如果peak_tokens没降检查history_mode是不是真的生效了。6. 本篇常见错排查报错一structured output validation failed。模型返回的 JSON 缺字段或类型不对。先看require_structured_output是不是开了但 schema 没给全再确认工具定义里的input_schema和模型实际输出是否对齐。常见坑是 schema 里写了enum但模型返回了枚举外的值这时候应该触发确认流程而不是直接失败。报错二max_steps exceeded。Agent 在某个循环里出不来。检查是不是某一步的验收标准永远达不到导致一直重试。把max_retries_per_step调低或者给这一步加一个连续失败两次就回退的规则。报错三context token 超限。说明 Context Rot 治理没生效。确认history_mode summary和drop_tool_raw_after_steps都配了并且摘要逻辑真的在跑。很多时候是摘要函数没接上历史还是原始返回。报错四401 unauthorized。Key 没注入或 base_url 写错。确认base_url https://taotoken.net/api以及环境变量TAOTOKEN_API_KEY在当前 shell 里可见。可以用curl先单独验证一次链路。报错五工具调用参数对但结果不对。大概率是工具粒度太细模型要拼好几步才能完成一个目标中间某步跑偏。参考第 4.2 节把工具收敛成一步完成目标的粒度。7. 接入与下一步如果你还没配 Key先去 API Keys 页面https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite建一个接入文档在https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite里面有 base_url 和鉴权的完整说明。想先验证模型通不通用模型对话页面https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite发一条消息最快。如果你是要长期跑编码类 Agent 或者多步 Workflow建议直接上 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite配额和并发更适合持续任务。用 Claude Code 的话Anthropic 兼容接入配置在https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaude-code-anthropicutm_campaignrewrite把 base_url 指过去就能复用同一套 Key。最后说个我踩过的坑一开始我总想靠调 Prompt 解决跑偏改到第十版才发现真正让轨迹稳下来的是把max_steps、结构化输出和上下文摘要这三件事配齐。模型没换跑偏率从六成降到了一成多。所以下次 Agent 再跑偏先别动模型回去看 Harness 和 Context Rot。