CodeBuddy NPC 给的改动不敢直接合——它到底读的是哪份上下文？

CodeBuddy NPC 给出的改动看起来正确，真正让人犹豫的地方，是这份改动依据的上下文说不清：该智能体通常不会去读整个仓库，而是把索引过的仓库快照、当前打开或显式附加的文件、以及检索命中的片段一起放进上下文窗口。这三者的比例决定了改动是照着最新代码写的，还是照着某次索引写的。要判断能不能合入，先别读改动的 diff，而是回到任务记录里，确认这次任务实际引用了哪些文件、这些文件是快照还是实时读取，再把上限收紧到能解释的范围。

判断 CodeBuddy NPC 的改动能不能合，先看任务记录里的引用文件清单，不要只凭代码像不像正确。用“改一个被引用文件再发起同类任务”区分快照与实时读取，再用 include/exclude 把范围收紧到可解释，最后故意移除关键文件做一次对照任务，看它是停下提问还是自行编造。这三步对得上，改动才具备合入的前提。

在任务记录里看它引用了哪些文件

多数编码智能体在任务详情里都会留下工具调用痕迹，位置通常在“任务/会话记录”面板的详情页，或改动说明里附带的引用文件列表；有的控制台还会列出每次检索的关键词与命中路径。先在这一层确认事实，再去看代码。

引用文件列表：记录里通常按“读过/检索命中/被编辑”分组，路径粒度一般是到文件，不一定带行号；带不带行号范围取决于具体工具实现，需要自己在记录里核对。
记录粒度：注意区分“全文读取”和“片段命中”。只命中片段时，智能体可能没看到同一文件后半部分的类型定义或导出语句，这是最常见的偏差来源。
最能解释偏差的缺失文件：新增的类型/接口定义文件、路由或组件注册入口、公共配置与校验 schema、数据库迁移脚本、被改动函数的调用方。改动里出现仓库中不存在的字段名或函数签名时，先回引用列表确认对应定义文件是否缺席。

判断上下文来自仓库快照还是实时读取

这一步只做一件事：制造一处可控的差异，看输出跟不跟着变。先在工作区未提交的状态下，修改一个已被引用的文件，例如把某个常量名加后缀、或在导出函数上方加一行注释标记，然后发起一次同类任务。

如果输出里出现了新名字，说明读取接近实时文件状态。
如果输出仍然引用旧符号、旧签名，说明走的是索引快照，需要先触发重新索引再复测。
如果新旧混用，说明部分文件实时、部分来自索引，这种混合状态最危险，通常要把关键文件显式附加在任务里。

建议把这次对比的两份输出和修改前后的文件哈希一起留在任务记录里，便于之后复核：git status 确认改动范围，md5sum 被引用文件 记录版本指纹。

用最小配置限定上下文范围

默认上下文范围往往过大，导致改动依据不可解释。把范围收紧到“这次任务需要的目录 + 显式附加文件”。下面是一个通用骨架，字段名与实际控制台填写为准，不要照抄后直接用于其他工具。

{
  "workspace": "./",
  "include": ["src/service/", "src/types/", "config/schema.ts"],
  "exclude": ["dist/", "node_modules/", "**/*.test.ts", "docs/"],
  "attach": ["src/service/order.ts"],
  "max_files": 20,
  "read_mode": "working_tree"
}

收紧后必须验证排除项真的没被读：在一个被 exclude 的目录里写入唯一标记字符串（例如 MARKER_EXCLUDED_7f3），发起任务让它“查找这个标记并说明出处”。如果输出里找不到该标记，说明排除生效；如果仍被引用，说明配置未落到实际检索链路，需要回到控制台确认这份配置作用于哪个环节。

构造一次上下文缺失的对照任务

目的是看智能体在信息不足时的行为，而不是看它写得好不好。做法：把一份关键文件从工作区临时移走或改名（保留可恢复的备份），其他条件不变，重发同一个任务。

最好的退化方式：明确说明“未找到 X 文件，请补充”，然后停下。
可接受：在改动说明里标注假设，例如“按推测的字段名实现，需确认”。
需要警惕：直接编造字段、配置项或函数签名，且没有任何提示。这类输出不能作为合入依据，必须补齐上下文重跑。

把这次对照的输出与正常任务的输出放在一起比对，能直观看出哪些内容是推断出来的。

把可接受的上下文范围写成合入前置条件

合入前按三项核对，缺一项就先不合：

引用文件清单：列出本次任务实际读取的文件，确认关键定义文件、注册入口、配置 schema 都在清单内，且与当前工作区版本一致。
改动范围说明：写明改动了哪些文件、依赖哪些未被读取的假设，假设部分单独标出。
人工复核点：至少覆盖新引用的符号是否存在、配置项是否被读取过、受影响调用方是否在引用清单里。

这三项建议随改动一起贴进合并说明，让审阅人复查的是上下文依据，而不只是代码本身。适用范围限于能拿到任务记录与配置的环境；如果控制台不提供引用清单，只能退回到“改动后逐文件对照”的人工核对，不要默认智能体读的是最新代码。