本地 coding agent 失败时，先不要同时换模型、扩大上下文、调整量化、又更换工具壳。相同的坏补丁可能来自三层：模型或运行时精度不够，上下文没有装进正确证据，或者 Harness 不能稳定完成编辑、命令、测试和反馈。先把失败归到一层，再动手修。
| 症状 | 先怀疑 | 验证办法 | 第一修复 |
|---|---|---|---|
| 小到几乎不用工具的改动也失败 | 模型、运行时或量化 | 保持文件很少，用更高精度本地设置或托管基线跑同一小任务 | 调整量化、运行时或换更强模型处理该任务 |
| 它丢掉相关文件、规则或前面已经确定的决定 | 上下文选择 | 干净会话只放目标文件、相邻接口、失败测试和约束说明 | 缩小上下文，装入精确证据，而不是继续塞仓库文本 |
| 它能说出正确方向，但补丁、命令或测试环节崩掉 | Harness 和工具反馈 | 对比模型想写的补丁、真实工具日志、命令输出和测试结果 | 修编辑器、权限、命令包装、schema、测试钩子或重试循环 |
| 只有改了很多设置之后才偶尔成功 | 还没有诊断 | 重置同仓库、同任务、干净会话、固定文件，只改一个变量 | 先重复对照，不要继续凭感觉调参 |
托管基线只用来校准。如果同一个最小任务在托管环境成功而本地失败，本地栈仍要继续分层；如果两边都失败，任务说明、验收条件或文件选择本身可能不足。对这个任务来说，只要本地路线在公平比较后仍达不到质量、速度或工具可靠性要求，就停止本地调参。
快速分层诊断
不要把本地 coding agent 看成单个模型。它至少包含模型权重、推理运行时、上下文选择、工具调用、文件编辑、shell 命令、测试、权限、回滚和复核。外表上都是“它写错了”，内部可能完全不同。
| 层 | 它负责什么 | 典型失败 | 还不能下的结论 |
|---|---|---|---|
| 模型和运行时 | 模型大小、量化、KV cache、CPU/GPU 放置、服务参数 | 小任务推理弱、结构化输出坏、推理慢、上下文一长就 OOM | 不能说本地模型都不行 |
| 上下文和检索 | 装入文件、规则、历史、摘要、工具定义和日志 | 改错文件、忘约束、漏掉近处符号、越读越乱 | 不能说窗口越大越好 |
| Harness 和反馈 | 编辑应用、命令运行、权限、schema、测试、重试、审查 | 思路对但补丁失败、目录错、测试没读懂、权限循环 | 不能说模型不会做这个任务 |
有效的第一步不是找万能设置，而是构造一个小型对照。把失败压缩到一个真实任务，保留同一仓库和同一验收标准，只换一个可疑层。
只改一个变量
诊断必须公平。固定仓库、任务、指令、文件集合和干净会话；一次只改变一层。最小任务可以是一条失败测试、一个坏编辑、一个命令调用、一个权限错误，或者一个它反复读错的文件。
记录时不要只写“失败”。要写模型名、量化方式、运行时、上下文长度设置、装入文件、Harness 名称、命令输出、测试结果和最后状态。然后只换一个变量。
| 只改的变量 | 变好时说明什么 | 不能说明什么 | | --- | --- | --- | --- | | 更高精度、更大本地模型或托管基线 | 模型或运行时很可能是瓶颈 | 不能证明上下文和 Harness 健康 | | 干净会话只放目标文件 | 原会话的上下文、历史或检索可能污染了任务 | 不能证明小模型能处理完整仓库 | | 同一模型换另一个 Harness | 工具循环、编辑应用、测试或权限可能参与失败 | 不能证明新 Harness 对所有任务更好 | | 同一提示只让模型给补丁，人手应用测试 | 模型想法可能正确，执行链路失败 | 不能让人工长期救场 |
如果你真正要做本地和云端路线选择，先完成这一层诊断，再看 本地和云端 coding agent 路线。失败层没找到之前，换路线只是把不确定性带到新工具里。
什么时候怀疑量化或运行时
当任务小到上下文和工具还没有发挥空间时，优先怀疑模型或运行时。比如两步改动都记不住、极短任务也输出坏 JSON、反复写简单语法错误、上下文稍长就速度崩或内存爆。
量化会降低内存和计算成本，也可能带来精度损失。不要把“Q4 失败”直接翻译成“本地路线没救”。先在相同小任务上试更保守的量化、更适合代码的模型，或者托管基线，并且保持上下文极小。这样你测到的是模型和运行时，而不是把检索问题混在一起。
好的运行时记录要包括模型、量化格式、上下文长度、推理服务、设备放置、显存或内存压力、prefill 速度、decode 速度、是否启用 KV cache 相关压缩，以及同一测试是否通过。没有这些字段，“量化坏了”只是猜测。
什么时候怀疑上下文
当模型单独回答没问题，但进仓库后总是拿不到正确事实，就怀疑上下文。它可能改了兄弟文件，忘了本地约定，忽略接口签名，或者不断读更多文件却没有更接近答案。
上下文工程不是把整个仓库倒进去。有效做法是把目标文件、失败测试、最近的接口或 schema、治理规则、最近命令输出压缩成证据集合。长窗口有用，但相关信息埋在中间时，模型仍可能抓不到关键线索。
做一次干净会话：只给目标文件、最近测试、相邻类型定义和必须遵守的规则，同时明确不要读哪些目录。如果结果明显变好，原运行的问题大概率是上下文污染、检索遗漏、旧历史拖累或工具定义太多。第一修复通常是减少输入和固定证据，而不是继续扩大窗口。
什么时候怀疑 Harness
当模型能讲出正确修法，执行却失败时，问题常在 Harness。它知道文件在哪里，也能描述补丁，但编辑器没有应用成功，命令在错误目录运行，权限策略拦住验证，测试输出没有反馈回去，或者重试循环只是重复同一个错误。
这类失败尤其容易被误判为模型差。把模型的“意图补丁”和实际工具日志分开看：diff 是否完整，命令是否在正确工作目录，测试是否真的执行，错误是否进入下一轮提示，权限是否可预期，失败后是否有停止条件。
可修的地方很具体：更窄的工具 schema，稳定的工作目录，清楚的权限策略，确定性的检查命令，能读懂测试输出的重试逻辑，AGENTS 或项目规则里写明约束，以及人工复核前的自动传感器。
记录可复现实验包
一次有用的求助、团队复盘或工具比较，不需要整段会话，只需要能复现的日志包。
| 字段 | 要记录什么 |
|---|---|
| 任务 | 能复现失败的最小仓库任务 |
| 模型和运行时 | 模型、量化、运行时、设备放置、上下文长度 |
| 上下文 | 装入文件、规则、历史、摘要和检索方式 |
| Harness | 工具包装、编辑方式、命令 runner、权限模式、测试命令 |
| 症状 | 精确失败，而不是解释 |
| 工具日志 | 补丁应用、命令输出、测试结果、权限或 schema 错误 |
| 对照比较 | 哪些保持不变、改了什么、结果是否变化 |
| 第一修复 | 只改一件事后的通过或失败 |
| 停止决定 | 继续调本地、换 Harness、用托管基线，还是停止本地任务 |
把证据和解释分开。“低精度本地模型在无上下文小任务失败，而更高精度设置通过”是证据；“所有量化本地 agent 都没用”不是证据。
调参、换壳还是停止
完成一到两轮对照后就要选方向，不要因为配置看起来快成功了就无限调。
如果失败在上下文和工具影响之前出现，并且更强本地基线明显改善，就调模型和运行时：降低量化激进程度，换更适合代码的模型，固定运行时参数，或把任务边界切小。
如果手选文件后成功，而宽会话失败，就缩上下文：做文件图、移除旧会话、固定测试、用命令输出作证据。需要巨大上下文才能做一个小补丁，本身就是诊断没有完成。
如果思路正确但工具链失败，就修 Harness：schema、编辑应用、命令包装、权限、项目规则、测试传感器和审查门槛都比换模型更重要。
当本地路线在公平比较后仍达不到质量或速度要求，托管基线就是交付路线，不是价值判断。若下一步变成 Claude Code 和 Codex 的选择，可以转到 Claude Code vs Codex。若问题是 Codex 的上下文和用量计数，看 Codex token usage。若是 API key 成本，使用 Codex CLI token cost estimate。
常见问题
量化是本地 coding agent 失败的最常见原因吗？
不一定。量化会影响精度，但上下文污染和 Harness 反馈断裂也会表现成同样的坏补丁。先用极小任务、最少上下文、更高精度或托管基线做一次对照。
怎么判断是上下文问题？
用干净会话，只装目标文件、最近测试和必须规则。如果表现变好，原会话很可能有噪声上下文、旧历史、检索遗漏或工具定义过多。第一修复是更精确的证据集合。
把上下文问题拆得更细一点，通常会看到四类信号。第一类是文件边界错误：agent 把同名组件、旧实现、生成文件或测试夹具当成目标。第二类是规则边界错误：项目约定、类型约束、API 兼容要求没有被放在足够靠前的位置。第三类是历史污染：前一轮失败假设留在会话里，后续补丁继续沿着错误方向修。第四类是证据稀释：日志、接口、测试、需求都在上下文里，但没有形成明确的“必须优先读取”顺序。
修复时不要只问“要不要更长窗口”，而要问“哪个证据必须出现、哪个证据必须消失、哪个证据必须放在决策前”。对代码任务来说，短 file map、目标文件片段、失败测试、最近命令输出、接口签名和本地规则，通常比一整屏无序仓库文本更有价值。如果一个小修复必须依赖完整仓库 dump 才能完成，就说明检索和约束表达还没有准备好。
什么算 Harness 失败？
模型的修复思路合理，但执行链路无法完成闭环，就是 Harness 失败。补丁应用失败、目录错误、权限循环、坏工具调用、忽略测试输出、无学习的重试都属于这一类。
Harness 失败也要拆层记录。编辑层要看 diff 是否按预期应用，是否被 formatter 或冲突处理改写；命令层要看 cwd、环境变量、shell、依赖安装状态和超时；验证层要看测试是否真的运行、失败输出是否完整返回、lint/typecheck 是否覆盖目标；重试层要看下一轮是否读取了新的错误，而不是重写同一个补丁。只要其中一个环节丢信号，模型看起来就会像“不会写代码”。
一个实用判断是：把模型生成的 patch 复制出来，用人工或另一个更可靠的 runner 应用并测试。如果 patch 思路通过，Harness 就不能把责任推给模型；如果 patch 本身也失败，再回到模型和上下文层。这个人工对照不是长期流程，而是一次定位工具链断点的探针。
本地失败时要马上换 Claude Code、Codex 或托管 agent 吗？
先把托管环境当作对照。如果同一最小任务托管通过、本地在分层诊断后仍失败，就把该任务交给托管路线。如果两边都失败，先改任务说明、文件选择、测试和验收条件。
托管对照的价值在于固定任务难度，而不是给某个工具背书。对同一 repo、同一测试、同一验收标准，如果托管路线能稳定完成，而本地路线在更保守量化、干净上下文、修过 Harness 后仍反复失败，那么本地成本已经不只是推理成本，还包括工程师复核、重跑和回滚成本。此时把该任务切到托管路线是交付判断，不是说本地路线永远不可用。
反过来，如果托管路线也失败，就不要继续在工具名之间切换。优先补齐任务边界：明确要改哪个文件、哪个测试代表完成、哪些目录不能动、哪些行为必须保留、哪些输出算失败。很多“agent 失败”其实是验收条件太松，导致任何路线都只能猜。
还有一种常见情况是“本地偶尔成功”。偶尔成功不能算诊断完成，因为它可能只是随机采样、缓存状态、文件读取顺序或重试次数碰巧有利。要把一次成功变成可用结论，至少连续复跑相同最小任务，确认同一配置、同一文件集合、同一验证命令下结果稳定。如果稳定性来自多次人工干预，就把人工步骤也记进日志，不要把它当成 agent 本身的能力。
当失败会影响生产代码、迁移脚本或安全边界时，停止阈值要更早：只要日志不能解释失败层，就不要让本地 agent 继续扩大改动范围。
先缩小任务，再扩大自动化。
先证明原因，再追求速度。
复查。
求助时应该发什么？
发最小日志包：模型、量化、运行时、上下文文件、Harness、提示、工具日志、命令输出、测试结果和一次单变量对照。不要发无关私密代码或密钥。
最好把日志包写成别人能复跑的顺序：先给最小任务和期望结果，再给环境和模型设置，然后给文件清单和限制，接着给失败日志，最后给单变量对照。这样团队成员能直接判断下一步该调模型、缩上下文、修 Harness，还是停止本地路线。没有对照的求助通常只会得到“换模型”“加上下文”“重试”的泛建议。
如果需要删掉私密内容，保留结构信息：文件类型、调用关系、测试名、错误类别、命令形状和权限边界。删掉密钥和业务数据不等于删掉可诊断性。真正有用的是让别人看到失败发生在哪一层，而不是看到完整私有代码。