Debug 侦探任务集
Debug 不是学习失败，而是工程学习真正开始的地方。很多新人觉得枯燥，是因为教程总展示成功路径；但真实项目里，最有价值的能力往往来自“为什么它没按预期工作”。
这页把常见错误包装成侦探任务。每个任务都有案件、线索、嫌疑原因、侦查步骤、真相和修复记录。你可以先自己猜，再看建议排查方向。
侦探任务怎么玩
遇到案件时，不要急着看答案。先 按这四步做：保存完整现象，提出 2～3 个嫌疑原因，用最小实验排除，最后把真相写成修复记录。
每个侦探任务都要留下一个证据文件，例如 failure_cases.md、debug_notes.md、retrieval_logs.jsonl、agent_traces.jsonl 或 README 中的一段排障记录。
案件 1：失踪的命令
| 项目 | 内容 |
|---|---|
| 案发现场 | 终端输入 python、pip、npm 或 docusaurus 后提示 command not found |
| 线索 | 同一台电脑上有时能运行，有时不能运行；换终端后现象不同 |
| 嫌疑原因 | 命令没安装、PATH 没生效、不在项目根目录、虚拟环境没激活 |
| 侦查步骤 | 运行 pwd、which python、python --version、npm --version，确认当前目录和工具位置 |
| 真相方向 | 环境和路径问题，不是代码逻辑问题 |
| 修复证据 | README 增加安装命令、运行目录和版本说明 |
这个案件训练的是环境意识。新人第一关不是写复杂代码，而是知道自己在哪个目录、用哪个解释器、运行哪个命令。
案件 2：打不开的 JSON 宝箱
| 项目 | 内容 |
|---|---|
| 案发现场 | 程序读取 tasks.json 时报 JSONDecodeError |
| 线索 | 文件存在，但打开后发现少了括号、多了逗号，或者是空文件 |
| 嫌疑原因 | 文件被手动改坏、程序写入中断、把 JSONL 当 JSON 读 |
| 侦查步骤 | 用最小脚本 json.loads 读取一小段内容，检查文件是否为空，确认格式是 JSON 还是 JSONL |
| 真相方向 | 数据文件格式损坏，程序缺少异常处理 |
| 修复证据 | 增加损坏文件提示、备份逻辑或重建逻辑 |
这个案件训练的是输入防御。真实项目里，文件、接口和用户输入都可能坏掉，程序不能只在理想输入下工作。
案件 3：DataFrame 列名失踪案
| 项目 | 内容 |
|---|---|
| 案发现场 | Pandas 报 KeyError: 'minutes' 或某列不存在 |
| 线索 | CSV 打开看起来有这一列，但程序就是读不到 |
| 嫌疑原因 | 列名有空格、大小写不同、分隔符错误、header 行读错、编码异常 |
| 侦查步骤 | 打印 df.columns.tolist()，查看 df.head()，确认 read_csv 参数 |
| 真相方向 | 数据读取和字段规范问题 |
| 修复证据 | 增加列名清洗、数据字典和读取参数说明 |
这个案件训练的是数据第一眼检查。做分析前先看列名、行数、缺失和 样例，比直接建模更重要。
案件 4：高得离谱的模型分数
| 项目 | 内容 |
|---|---|
| 案发现场 | 模型准确率 99%，但换一点数据就不稳定 |
| 线索 | 特征里可能包含答案，训练集和测试集有重复，切分发生在错误步骤之后 |
| 嫌疑原因 | 数据泄漏、重复样本、目标变量进入特征、评估集太小 |
| 侦查步骤 | 检查 train/test 是否先切分，删除可疑特征，训练 Dummy baseline，对比重复样本 |
| 真相方向 | 分数不可信，不是模型真的很强 |
| 修复证据 | 泄漏检查记录、baseline 指标、错误样本分析 |
这个案件训练的是评估警觉。好看的分数不一定是好模型，能解释分数来源才是能力。
案件 5：JSON 漂移事件
| 项目 | 内容 |
|---|---|
| 案发现场 | LLM 有时输出合法 JSON，有时多解释一句，有时少字段 |
| 线索 | Prompt 只说“请输出 JSON”，但没有字段 schema、示例和校验 |
| 嫌疑原因 | 约束不够、输出没有校验、没有失败重试、测试输入太少 |
| 侦查步骤 | 固定 10 个输入，保存原始输出，用 JSON parser 和 schema 校验 |
| 真相方向 | Prompt 不是一次性文案，而是需要测试的组件 |
| 修复证据 | Prompt 版本表、schema 校验通过率、失败样本 |
这个案件训练的是 Prompt 工程的可靠性。一次成功不代表稳定，固定测试集才说明问题。
案件 6：RAG 找不到证据
| 项目 | 内容 |
|---|---|
| 案发现场 | 用户问的问题明明在文档里，RAG 却答非所问或说不知道 |
| 线索 | 检索结果没有命中正确 chunk，或者命中了但 metadata 丢失 |
| 嫌疑原因 | 文档未导入、chunk 太大或太小、query 表达不匹配、top-k 太小、embedding 不适合 |
| 侦查步骤 | 暂时关闭生成，只打印检索结果；用原文关键词检索；检查 chunk 内容和 metadata |
| 真相方向 | 生成之前，检索已经失败 |
| 修复证据 | retrieval_logs、chunk 样例、eval_questions、失败类型统计 |
这个案件训练的是 RAG 分层排查。先看检索，再看生成，再看引用，不要把所有问题都归因给模型。
案件 7：引用幻觉案
| 项目 | 内容 |
|---|---|
| 案发现场 | RAG 回答看起来正确，但引用片段并不能支持答案 |
| 线索 | 答案可 能来自模型常识，而不是检索资料；引用只是装饰 |
| 嫌疑原因 | Prompt 没要求逐句依据，citation 粒度太粗，检索片段和答案没有对齐 |
| 侦查步骤 | 对每个答案句子标注支持片段，增加 citation_ok 字段 |
| 真相方向 | 有引用不等于有证据支持 |
| 修复证据 | citation_check.csv、失败问题和修复 Prompt |
这个案件训练的是事实一致性。作品集里的 RAG 项目，必须能展示引用检查，而不是只展示答案。
案件 8：Agent 原地转圈案
| 项目 | 内容 |
|---|---|
| 案发现场 | Agent 一直重复计划、调用同一个工具，迟迟不结束 |
| 线索 | 每一步 thought 和 observation 很像，目标没有完成条件 |
| 嫌疑原因 | 任务过宽、停止条件不清、工具返回不明确、没有最大步数 |
| 侦查步骤 | 限制 3 步运行，打印 action、input、observation 和 done 判断 |
| 真相方向 | Agent 缺少边界，不是模型需要更多自由 |
| 修复证据 | agent_traces.jsonl、停止条件说明、失败前后 trace 对比 |
这个案件训练的是可控 Agent 设计。Agent 越能行动，越需要边界。
案件 9：偷偷越权的工具
| 项目 | 内容 |
|---|---|
| 案发现场 | Agent 调用了不该调用的删除、发送、写入或外部操作 |
| 线索 | 工具描述没有风险等级，系统没有人工确认，测试只覆盖成功路径 |
| 嫌疑原因 | 工具白名单太宽、权限没有分级、缺少 dry-run、没有审计日志 |
| 侦查步骤 | 把工具按只读、写入、发送、删除分级，高风险工具默认人工确认 |
| 真相方向 | 权限设计问题，不是单个 Prompt 能彻底解决 |
| 修复证据 | 工具权限表、越权测试样例、人工确认截图或日志 |
这个案件训练的是安全边界。作品集里的 Agent 项目如果能展示如何防止越权，会比只展示自动化更有说服力。
案件 10：本地能跑，别人跑不了
| 项目 | 内容 |
|---|---|
| 案发现场 | 你电脑上能跑，换同学或部署环境就失败 |
| 线索 | README 漏了依赖、环境变量、数据文件、启动目录或版本 |
| 嫌疑原因 | 隐式依赖、本地绝对路径、未提交样例数据、缺少 .env.example |
| 侦查步骤 | 在干净目录重新 clone，按 README 从零运行 |
| 真相方向 | 项目交付不完整，不是使用者不会用 |
| 修复证据 | 更新 README、依赖文件、.env.example、启动日志 |
这个案件训练的是交付意识。能在自己电脑跑通只是第一步，别人能复现才是作品集项目。
侦探笔记模板
## 案件：RAG 找不到证据
### 案发现场
用户问“Agent 和 RAG 有什么区别”，系统回答很泛，没有引用正确章节。
### 已知线索
检索结果只命中了 RAG 章节，没有命中 Agent 章节。
### 嫌疑原因
导入文档范围太窄，metadata 没有保存 stage 信息，query 没有改写。
### 侦查步骤
关闭生成，只打印 top-5 检索结果；用“Agent 工具调用”和“智能体”关键词重新检索。
### 真相
索引只导入了 stage8b，没有导入 stage9。
### 修复
扩大文档导入范围，并在 metadata 中保存 stage 和 title。
### 回归检查
把这个问题加入 eval_questions.csv。
Debug 侦探任务的目标是让错误变得可玩、可查、可复盘。每破一个案，你就多一条真实工程经验。