附录 D · 失败模式速查
用法：按「症状」查表 → 先做「第一动作」→ 再按根因修。
铁律：先取证据，再下结论；先跑极简对照，再说模型不行。
D.1 上下文与循环类
| # |
症状 |
第一动作 |
高频根因 |
修复 |
章 |
| 1 |
反复读同一个文件 / 无限重试 |
查 tool/call 序列 |
停止条件缺失、inbox 重复投递 |
加 max_steps；检查 agent/turn-stopping |
02 / 06 |
| 2 |
长任务后半段开始胡说 |
比对 PreCompact 归档与压缩后提示词 |
关键规则被压掉 |
把规则迁到 hook，或设为常驻 section |
08 / 10 |
| 3 |
「你好」都要上万 token |
看上下文面板 |
20+ 工具 schema 常驻 |
按需准入、Skills、极简模式 |
09 |
| 4 |
上下文越跑越长直到截断 |
看 tool/result 总量 |
中间结果全量回灌 |
用 PTC 只 return 聚合；工具结果落盘 |
09 |
| 5 |
同一 turn 前后行为矛盾 |
查 assistant/attempt 与各 step 的 request/context |
attempt 间运行时事实刷新 |
固定运行时事实，或缩短 turn |
03 / 06 |
| 6 |
模型提到没给过的文件/人名 |
Trajectory 按来源逐个关闭，二分 |
插件注入了幽灵上下文 |
关掉注入源；走 agent.inject() 正规入口 |
06 / 10 |
D.2 工具与权限类
| # |
症状 |
第一动作 |
高频根因 |
修复 |
章 |
| 7 |
写了「只读」还是改了文件 |
看权限预设与 hook 是否真的生效 |
把约束写成建议 |
迁到 PreToolUse + 沙箱 denyWrite |
02 / 08 |
| 8 |
hook 挡不住用 Bash 写文件 |
看 matcher |
只匹配 Write\|Edit，Bash 不触发 |
加 sandbox 文件系统规则，双层覆盖 |
08 / 17 |
| 9 |
工具参数格式总错 |
看 step-admitted schema |
描述歧义、枚举不全、无示例 |
收窄 schema + one-shot 示例 |
09 |
| 10 |
工具返回「成功」但结果不对 |
看 tool/result 原始字节 |
输出被截断 / 只回摘要 |
调大上限或落盘再读 |
06 |
| 11 |
插件一加载 Agent 就什么都不做 |
检查监听器 |
waterfall 漏写 next() |
补 next() 委托 |
11 / 12 |
| 12 |
插件卸载后仍有重复工具/监听器 |
重新 dump 工具注册表 |
注册没走 ctx.effect() |
全部改走可逆注册 |
11 / 12 |
| 13 |
../ 能写出工作区 |
检查路径校验 |
只靠提示词约束 |
is_relative_to + OS 沙箱双层 |
02 / 17 |
| 14 |
提示注入让 Agent 外联 |
查网络日志与出站域名 |
默认允许网络 |
默认 deny + allowedDomains |
17 |
D.3 模式与环境类
| # |
症状 |
第一动作 |
高频根因 |
修复 |
章 |
| 15 |
极简里能做对、标准里做不对 |
保持这个对照，别急着换模型 |
工具 schema / 提示词冲突 / 压缩 / 注入污染 |
逐项关能力，二分定位 |
05 / 06 |
| 16 |
极简里也做不对 |
检查题面是否可机器判定 |
模型能力 / 题面歧义 |
换题面或换模型，才轮到这一步 |
05 / 15 |
| 17 |
切到 PTC 后审批失效的错觉 |
查审批日志 |
误以为托管进程绕过流水线 |
确认子调用仍走统一流水线 |
05 / 09 |
| 18 |
Code mode / PTC 文档对不上 |
固定版本号 |
版本改名（曾伴随 session API 变化、SQLite 后端移除） |
锁版本，以本机 dump 为准 |
04 / 05 |
| 19 |
配置改了不生效 |
dsh --dump-config |
patch 层叠顺序 / 被上层覆盖 |
按 profile→bundle→patch→overlay 顺序排查 |
13 |
| 20 |
自定义预设起不来 |
dump 真实树 |
row id 写错 / 依赖未声明 |
补 inject，核对 config-catalog |
12 / 13 |
D.4 编排与调度类
| # |
症状 |
第一动作 |
高频根因 |
修复 |
章 |
| 21 |
并行 Agent 互相覆盖文件 |
检查是否共用工作目录 |
共享可变状态 |
一 Agent 一 worktree |
14 / 18 |
| 22 |
定时任务没执行 |
查宿主是否在运行 |
宿主关闭期间调度停止 |
always-on 宿主；补投只覆盖最近一次 |
06 / 14 |
| 23 |
简报/通知发了两遍 |
查投递记录 |
投递不保证恰好一次 |
业务层幂等检查；任务当触发器 |
06 / 14 |
| 24 |
子 Agent 说没有定时工具 |
看委派 deny 列表 |
schedule_* 已被 deny |
由主 Agent 统一调度 |
06 / 14 |
| 25 |
时区不对 / 夏令时错位 |
看是否显式 IANA |
依赖浏览器上报时区 |
显式写 Asia/Shanghai 等 |
06 |
| 26 |
汇总结果格式不齐 |
查状态契约 |
输出 schema 没约定 |
补齐六字段状态契约 |
14 |
| 27 |
多个 DSH 进程操作同一团队冲突 |
查团队状态文件位置 |
状态默认在当前工作区、不自动同步 |
单进程持有 + 外置状态 |
14 |
D.5 评测与生产类
| # |
症状 |
第一动作 |
高频根因 |
修复 |
章 |
| 28 |
「感觉变快了」但说不出数字 |
停止优化，先建基线 |
没有指标 |
记录耗时/工具次数/输入输出 token/测试全绿/改动行数 |
15 |
| 29 |
A/B 结果不可复现 |
检查 git status |
漏了 git clean -fd |
重置脚本化，跑前校验 |
15 |
| 30 |
同时改模型与 Harness 后归因不清 |
拆实验 |
违反单变量 |
一次只动一个变量 |
15 |
| 31 |
Agent 宣布完成但测试是红的 |
查 Stop 条件 |
Done 是感觉不是状态 |
Stop hook 自检 |
08 / 15 |
| 32 |
月底才发现超支 |
查按 session 记账 |
只有账单级可见性 |
实时 token/USD 看板 + 熔断 |
18 |
| 33 |
告警一上线就误报 |
查阈值来源 |
静态阈值 / 单事件触发 |
时间窗 + 最近 24h backtest |
16 |
| 34 |
出了问题查不到证据 |
查日志是否外送 |
只在容器 stdout |
audit 外送持久存储 |
16 / 17 |
| 35 |
凭据出现在日志里 |
全库搜 token 字样 |
未脱敏 / 未 mask |
*** redaction + envVars mask |
17 |
D.6 万能三步（症状不在表里时用）
1. 取证据 → 读 Trajectory / trace，别复述现象
2. 做对照 → 极简模式同题面跑一次，判模型 vs 环境
3. 固化 → 一条规则 + 一个确定性检查 + 一条 eval 用例
第 3 步不可省。只修好这一次，不叫修好。
回到 第 06 章 · 第 07 章 · 总目录
本系列为本站原创教程，基线为微信公众号《DeepSeek Harness 最新高阶指南》（2026-11-05），并汇总 DeepSeek 官方仓库与文档站、Cordis / arXiv:2608.25512、以及 OpenAI / Anthropic / LangChain / Martin Fowler 等一手资料。每条引用均标证据等级，完整清单见
附录 B；未定位到一手来源的线索单列，未编造补位。DeepSeek Harness 为 developer preview，官方 SAFETY.md 明确「未经过安全审计、不得视为生产就绪」，命令与配置键可能随版本失效。资料截止 2026-11-06。姊妹篇：
《FDE 入门到精通》。