Agent 一接文件树就开始改错目录：从 Working Directory Claim 到 Path Scope Fence 的工程实战

不少团队把文件树接进 Agent 后第一次翻车往往不是改不动代码而是改到了错误目录。一个修复本该落在services/api结果模型顺手把infra/terraform里的同名文件也改了一个看似无害的批量替换把 monorepo 里另一条产品线一起带偏。 根因不是模型不懂路径而是系统没有把当前工作区变成可验证的约束。图 1文件树可见不等于目标目录已经被绑定问题拆解很多 Agent 产品默认把用户当前看到的文件树当操作范围但执行链路里模型拿到的往往只是路径字符串和搜索结果。只要仓库里有重名目录、多个src或多个config路径解析就会漂移。⚠️ 漂移通常不会立刻报错因为改错目录同样能写成功。工程上常见三类错误一是相对路径借位从上次命令残留的工作目录继续执行二是检索命中污染搜索先命中相似目录后续 patch 直接沿用三是跨工具混用浏览器、终端、编辑器各自维护一套 cwd状态不一致。 只做展示当前路径远远不够必须让 Agent 执行前先声明目标根目录。图 2重名目录、跨工具状态与检索污染会共同放大误改风险实战验证一套更稳的做法是两层保护先做Working Directory Claim再做Path Scope Fence。前者在任务开始时把目标根目录写成显式状态后者拦住所有越界写操作。✅方案约束点典型问题建议仅靠当前终端 cwd执行时浏览器、编辑器不同步不足以做最终约束仅靠文件树选中态UI 层搜索/补全后容易漂移只能做提示Claim Fence任务级 写入级需要多一步校验最稳适合生产frompathlibimportPath ALLOWED_ROOTPath(/workspace/repo/services/api).resolve()defassert_write_scope(target_path:str)-Path:targetPath(target_path).resolve()ifALLOWED_ROOTnotin[target,*target.parents]:raisePermissionError(fblocked by path scope fence:{target})returntarget落地时系统先要求 Agent 产出claim_root/workspace/repo/services/api后续所有write_file、patch、terminal mv都要经过同一层校验。️ 某代码代理团队在 2 周灰度里加上这套机制误改目录告警从每千次任务 11.8 次降到 1.6 次真正落到错误仓库的事故归零代价是平均多一次路径确认耗时增加约 3%。再往前一步可以把只读搜索和可写修改分层搜索允许跨仓库命中但一旦进入编辑阶段就只保留 claim 根目录内的候选文件如果模型想越界必须重新发起 claim。这样既保留检索效率又不会让一次模糊命中直接变成错误提交。图 3把搜索范围和写入范围拆开才能真正压住误改目录深度思考笔者以为很多团队把权限控制理解成能不能调用工具却忽略了路径本身就是权限对象。对代码 Agent 来说/repo-a/app和/repo-b/app的区别不是字符串差异而是业务边界。只要系统没有把边界编码成强约束模型越聪明越可能在相似文件之间自信地犯错。真正可靠的方案不是让模型记住更多目录而是让系统每次副作用发生前回答两个问题这是不是当前任务认领的根目录这次写入有没有越过允许边界只要这两问答不清回滚、审计、人工复核都会越来越贵。趋势预估未来 3 到 6 个月代码 Agent 平台会把cwd从进程级状态升级成任务级契约进一步和 diff 预演、审批流、提交签名串起来。 另一个明显趋势是 IDE、浏览器工作台、远程执行器共享同一份workspace claim token避免多工具各管一套状态。对正在做 Agent 编排或 IDE 助手的团队更值得优先建设的不是更复杂的规划器而是可验证的目录边界、越界重认领和写前证明链。 你们的 Agent 是否已经把“改哪个目录”当成一等公民来治理如果还没有这往往比再堆一个反思循环更值得先做。