Code Agent 如何防止编辑任务范围之外的文件？

Code Agent 会编辑任务范围之外的文件，通常不是故意违背要求，而是它在优化“把问题彻底解决”。代理搜索整个仓库后，可能顺手清理邻近模块、删除未使用导入、统一格式或重命名变量。这些改动看似合理，却没有经过当前任务的需求确认和测试，增加了审查与回滚风险。

为什么调查范围会变成编辑范围

真实调试需要跨文件追踪调用、类型和配置，因此 Agent 必须能够读取任务之外的代码。问题在于许多工具只区分“可访问”和“不可访问”，没有区分“可以读取调查”和“获得授权修改”。模型一旦发现邻近问题，就容易把它理解为解决方案的一部分。

宽泛任务也会放大倾向。“修复这个 bug”没有说明允许哪些文件、是否可重构、能否增加依赖，也没有规定发现旁支问题时如何处理。模型训练倾向奖励完整、整洁的答案，而不是最小 diff；若没有边界，顺手修复会显得符合目标。

自动格式化和生成器还可能产生非主动越界。Agent 只修改一个文件，随后执行的格式化命令却重写整个目录；包管理器更新锁文件；测试生成快照；构建工具写入产物。范围控制必须覆盖所有写入通道，不只是编辑工具。

第一层：任务中明确允许修改集

最直接做法是在请求中列出允许修改的文件或目录。例如：“修复日期格式问题，只能修改指定实现文件和对应测试；如果需要改公共工具，先停止并说明原因。”这种表达同时给出白名单与越界流程。

范围不宜过窄到阻止必要测试。可以区分三类集合：允许修改、允许创建、只读调查。实现文件与测试文件进入修改集，相关调用者可读取但不能更改，新迁移或文档若未授权则不得创建。

当任务开始时路径尚不明确，可以要求 Agent 先只读调查并提交拟修改文件清单，用户或编排器确认后再开放写权限。这种两阶段方式适合跨模块故障和大型重构。

第二层：仓库级默认规则

每个任务都重复范围要求容易遗漏。仓库可以在 AGENTS.md 或工具识别的指令文件中写入默认规则：只修改完成当前任务所必需的文件；不要重构、重命名或清理无关代码；若认为邻近文件需要调整，先报告而不是直接修改。

规则应简短、可检查，避免“保持专业”“尽量小心”等模糊措辞。嵌套指令文件可以为敏感目录增加更严格约束，例如数据库迁移、基础设施、生成代码和安全策略必须获得明确授权。

仓库规则属于行为指导，不是安全边界。模型可能误判“必要”，命令也可能产生意外文件，因此还需要工具级强制控制和事后验证。

第三层：工具权限和沙箱

提示词只是请求，文件系统权限才是执行边界。编辑工具可以接受 allowed_paths 与 denied_paths，在每次写入、重命名和删除前解析真实路径并检查。拒绝规则应优先于允许规则，避免宽泛目录授权覆盖敏感子目录。

检查必须处理符号链接、相对路径、大小写差异和路径穿越。先规范化为真实绝对路径，再判断是否落在允许根内。不能只做字符串前缀比较，否则相似目录名或链接可能绕过限制。

shell 命令是常见旁路。即使 edit 工具限制路径，Agent 仍可能通过重定向、脚本、格式化器或 git 命令改写其他文件。操作系统级沙箱、只读挂载或隔离工作树可以让命令也遵循边界。

如何处理必须越界的修复

范围控制不能让 Agent 在错误文件里打补丁。如果根因确实位于白名单之外，正确行为是暂停写入，说明目标文件、必要变更、原因和风险，并请求扩展范围。编排器确认后更新白名单，再继续执行。

越界申请应具体到路径和操作类型。例如读取无需额外批准，但修改公共接口、增加依赖或生成迁移分别需要不同授权。不要一次把整个仓库开放给 Agent，只扩展最小必要范围。

如果用户不批准，Agent 应提供范围内可行的替代方案或明确无法安全完成，而不是绕过限制。边界失败是一种正常结果，比静默修改更可靠。

为什么先看文件列表再看 diff

代码审查往往从第一段 diff 开始逐行阅读，额外文件可能藏在末尾。更有效的顺序是先检查变更文件清单和统计，再阅读内容。每个文件都必须能追溯到任务要求或已批准的范围扩展。

一个无法解释的文件就是范围异常，即使改动本身“看起来更好”。无关格式化、重命名或导入清理应拆成独立变更，接受单独测试和决策。这样后续回滚目标修复时不会连带其他修改。

自动门禁可以将实际 changed_paths 与授权集合比较，发现额外文件立即失败。新文件、删除和重命名要单独显示，因为它们比普通内容修改更容易被统计摘要掩盖。

如何捕获间接写入

任务执行前记录工作树基线，包括已存在的用户改动。执行后使用版本控制状态或文件系统快照计算新增差异，不能假设所有变化都来自 Agent。已有未提交修改必须保留并标记。

对格式化、测试和构建命令，可以先在沙箱运行并检查写集。若命令会修改白名单外文件，拒绝提交或回滚这些副作用。生成目录和缓存目录可单独配置为临时可写，但不能混入最终提交。

依赖安装经常同时更新清单与锁文件。若任务没有授权依赖变化，应禁止相关命令；若确有需要，应把两个文件都显式加入范围，并审查传递依赖变化。

范围预算比自然语言更易验证

除了路径白名单，还可以设置变更预算：最多修改多少文件、增加或删除多少行、是否允许新依赖、是否允许公共 API 变化。预算不是为了机械追求小 diff，而是让超出预期的变更进入显式确认。

例如一个日期格式 bug 预计修改一个实现文件和一个测试文件。如果结果改动十二个文件并运行全仓格式化，即使测试通过也应暂停。Agent 可以解释为何需要扩大范围，由人或上层策略决定是否接受。

最小变更如何写进验收标准

任务完成条件应同时包含功能与范围。可以要求目标测试通过、没有新增诊断、实际文件集合等于批准集合、无无关格式化，以及 diff 中每一项都能对应需求。只写“测试通过”无法阻止额外清理。

Agent 的最终摘要应列出修改文件和每个文件的理由，不能只描述功能结果。摘要可以由系统根据真实 diff 生成，避免模型遗漏。若摘要与工作树不一致，以工作树为准并阻止完成。

推荐的执行流程

• 只读调查并识别根因与候选文件。
• 建立修改、创建和只读三个路径集合。
• 将写权限限制到批准路径。
• 在隔离工作树中应用最小变更。
• 运行目标格式化、静态检查与测试。
• 比较实际文件清单和变更预算。
• 发现越界时回滚或请求扩展范围。
• 文件集合通过后再审查具体 diff。

怎样测试范围控制

测试应让 Agent 在调查时看到一个明显但无关的小问题，验证它会报告而不是修改。再构造必须改第二个文件才能完成的任务，确认 Agent 会提出范围扩展，而不是偷偷越界或在错误位置绕过。

工具层测试需要覆盖相对路径、符号链接、目录前缀碰撞、重命名、删除和 shell 写入。还要运行会生成快照或格式化全仓的命令，确认沙箱能识别并阻止白名单外变更。

在脏工作树中测试尤其重要。系统必须区分用户原有修改和 Agent 新增修改，不能为了恢复范围而覆盖用户内容。快照和回滚只应作用于本次事务。

哪些做法不够可靠

只在提示末尾写“不要改无关文件”不够，因为“无关”需要模型解释。只检查提交文件也不够，Agent 可能留下未暂存改动。只限制编辑工具同样不够，shell 和生成器仍可写入。

自动删除白名单外变化也有风险，可能误删用户并发修改。正确做法是基于事务基线识别 Agent 产生的差异，并优先阻止写入；发生冲突时停止并报告，而不是猜测所有权。

结论

防止 Code Agent 编辑任务范围之外的文件，需要四层共同工作：任务明确文件范围、仓库指令设定默认最小变更、工具或沙箱强制写入边界，以及提交前先核对真实变更文件列表。

调查权限与修改权限应分开，必要越界必须走显式申请。再配合路径规范化、事务快照、变更预算和功能验证，系统才能既允许 Agent 跨仓库定位根因，又阻止它把顺手清理和间接写入混进当前任务。