Claude Code 103秒删4.8万文件：Directory Junction 与 Agent 安全防护

1. 103秒删掉4.8万个文件，这事到底怎么发生的

先把这件事的核心事实摆出来：一个基于 Claude Code 的 Agent 在 Windows 环境下执行任务时，用 103 秒删除了 4.8 万个文件，而且连.git目录都没能幸免。这不是段子，是真实发生的工程事故。我第一时间看到这个消息的时候，第一反应不是"AI 太危险了"，而是"这个目录结构一定有问题"。

为什么这么说？因为在 Windows 上，一个正常的项目目录，哪怕你装了node_modules，文件数量撑死也就几万个，但要在 103 秒内被批量删除，说明删除操作走的是一条极短路径——它没有逐层遍历，而是直接命中了一个"看起来像普通文件夹、实际上是整个盘符入口"的东西。这个东西，就是Directory Junction（目录联接）。

Directory Junction 是 NTFS 文件系统的一个特性，你可以把它理解成 Windows 版的"软链接"，但它比符号链接更底层、更"透明"。对绝大多数程序来说，Junction 和真实目录没有任何区别——你cd进去、你dir列文件、你Remove-Item -Recurse递归删除，操作系统都不会给你任何警告。问题就出在这个"透明"上。

我举个具体的场景你就明白了。假设你的项目放在D:\projects\myapp，但你的依赖缓存、构建产物、甚至整个用户目录被 Junction 到了C:\Users\xxx。当 Agent 拿到一个"清理临时文件"的任务，它扫描到D:\projects\myapp\temp，发现这是个目录，于是执行递归删除。如果temp恰好是一个指向C:\Users\xxx的 Junction，那么 Agent 以为自己在删项目里的临时文件，实际上它在删你整个用户目录下的所有东西——包括.git、包括配置、包括其他项目。

103 秒删 4.8 万个文件，平均每秒 466 个文件。这个速度说明删除操作几乎没有遇到任何阻碍：没有权限拦截、没有文件占用、没有回收站确认。这三点在 Windows 上同时成立，通常意味着操作是以高权限运行的，而且用的是底层删除 API（比如DeleteFile直接调用，而不是走资源管理器）。

这里有个很多人忽略的细节：.git目录为什么也会被删？因为.git在文件系统层面就是一个普通目录，它没有任何"保护标记"。Agent 不会因为"这是版本控制目录"就手下留情——它根本不知道.git意味着什么。这就是当前 Agent 架构的一个根本性缺陷：它理解语义，但不理解文件系统的物理边界。

2. Agent 的"理解力"和文件系统的"物理边界"之间的鸿沟

2.1 Agent 眼里的目录树，和操作系统眼里的目录树不是一回事

这是整件事最核心的技术点，也是我觉得最值得所有做 Agent 开发的人反复咀嚼的地方。

当 Claude Code 这类 Agent 拿到一个任务，比如"帮我清理项目里的临时文件"，它的工作流程大致是这样的：先通过工具调用（通常是 shell 命令或文件系统 API）列出目录结构，然后基于语言模型的理解判断哪些是"临时文件"，最后执行删除。问题在于，它看到的目录树是逻辑视图，不是物理视图。

逻辑视图是什么？就是ls或者dir命令输出的那个树状结构。在这个视图里，Junction 就是一个普通文件夹，符号链接也是一个普通文件夹。Agent 看到temp/下面有一堆文件，它不会知道这些文件实际存储在另一个物理位置。

物理视图是什么？是 NTFS 的 MFT（主文件表）里记录的真实扇区分布。在物理视图里，Junction 是一个重解析点（Reparse Point），它有一个特殊的标记位，告诉操作系统"这个目录的内容不在本地，请跳转到另一个路径"。

绝大多数文件操作 API 默认工作在逻辑视图下。Remove-Item -Recurse、rm -rf、shutil.rmtree，这些命令在遇到 Junction 或符号链接时，行为是不一样的：

你看，几乎所有"顺手"的删除命令，默认都是跟随链接的。这就是为什么 103 秒能删掉 4.8 万个文件——Agent 大概率用了一条rm -rf或者Remove-Item -Recurse，而这条命令恰好命中了一个 Junction。

2.2 为什么 Agent 特别容易踩这个坑

人类工程师也会踩 Junction 的坑，但人类有几个天然的保护机制：

第一，人类在删除前会犹豫。看到temp目录，人类会想"这个 temp 是什么时候建的？里面有什么？"这种犹豫虽然低效，但救命。

第二，人类对路径长度有直觉。如果D:\projects\myapp\temp这个路径下的文件数量异常多，人类会警觉。但 Agent 不会，它只会觉得"任务要求清理，我清理就是了"。

第三，人类有上下文记忆。你可能记得三天前自己手动建过一个 Junction 来做测试。但 Agent 的上下文窗口里没有这个信息，除非你明确告诉它。

第四，也是最关键的：Agent 被设计成"高效执行"。它的目标函数里，"完成任务"的权重远高于"谨慎操作"。当你给它一个清理任务，它会用最直接的方式达成目标，而不是用最安全的方式。

我实测过几个主流的 Agent 框架，在 Windows 环境下处理文件删除任务时，默认行为都偏向激进。有的框架甚至会在 prompt 里写"尽量用一条命令完成操作"，这直接鼓励了 Agent 使用rm -rf这种大杀器。

2.3 Directory Junction 在 Windows 上的特殊地位

为什么这个问题在 Windows 上特别突出？因为 Windows 的 Junction 使用场景比 Linux 的符号链接更"隐蔽"。

在 Linux 上，符号链接通常有明显的视觉标识——ls -l会显示->，颜色也不一样。而且 Linux 社区对符号链接的风险有广泛认知，很多工具默认不跟随链接。

但在 Windows 上，Junction 的创建非常简单：mklink /J一条命令就搞定，而且创建出来的东西在资源管理器里看起来和普通文件夹完全一样。没有箭头标识，没有特殊图标，双击进去和普通目录无异。

更麻烦的是，Windows 上有大量系统级和工具级的 Junction：

• C:\Users\All Users是指向C:\ProgramData的 Junction
• C:\Documents and Settings是指向C:\Users的 Junction
• 很多开发工具（如 Docker Desktop、WSL）会在用户目录下创建 Junction
• 一些包管理器（如 Chocolatey、Scoop）也会用 Junction 来做版本切换

这意味着，即使你的项目目录本身很干净，只要它下面有任何一层是 Junction，删除操作就可能"越界"。

3. 从这次事故里能提炼出的具体防护措施

3.1 删除前的"物理边界检查"

如果你在做 Agent 开发，或者你在用 Agent 做自动化任务，第一件要做的事是：在删除任何目录之前，检查它是不是重解析点。

在 Windows 上，可以用 PowerShell 这样检查：

function Test-ReparsePoint { param([string]$Path) $item = Get-Item -LiteralPath $Path -Force return ($item.Attributes -band [System.IO.FileAttributes]::ReparsePoint) -ne 0 }

这个函数的核心是读取文件的Attributes属性，然后和ReparsePoint标志位做按位与运算。如果结果非零，说明这个目录是一个重解析点（Junction 或符号链接），删除时必须特别小心。

更安全的做法是，在 Agent 的工具层直接禁用"跟随链接删除"。比如你自己封装一个删除函数：

import os import stat def safe_rmtree(path): if os.path.islink(path): os.unlink(path) return for root, dirs, files in os.walk(path, topdown=False): for name in files: fp = os.path.join(root, name) if not os.path.islink(fp): os.remove(fp) for name in dirs: dp = os.path.join(root, name) if os.path.islink(dp): os.unlink(dp) else: os.rmdir(dp)

这段代码的关键在于：遇到链接时只删除链接本身，不递归进去。os.path.islink在 Windows 上对 Junction 的检测可能不完美，更可靠的方式是用os.lstat检查st_reparse_tag，或者直接调用 Windows API。

3.2 给 Agent 加一道"删除确认"闸门

我在自己的 Agent 项目里加了一个硬性规则：任何删除操作，如果目标路径下的文件数量超过 100 个，必须先输出预览，等待人工确认。

这个规则的实现很简单，在工具调用层加一个拦截器：

def delete_with_guard(path, max_files=100): file_count = sum(len(files) for _, _, files in os.walk(path)) if file_count > max_files: preview = generate_preview(path, limit=20) raise NeedsConfirmation( f"即将删除 {file_count} 个文件，预览如下：\n{preview}" ) return do_delete(path)

这个闸门救过我至少两次。一次是 Agent 想删一个node_modules，另一次是它想清理一个被 Junction 指向的缓存目录。两次都是因为文件数量异常触发了确认，我才发现路径不对。

3.3 用"白名单"而不是"黑名单"来限定操作范围

很多 Agent 框架用的是黑名单策略：禁止删除C:\Windows、禁止删除C:\Program Files等等。但黑名单永远列不全，而且 Junction 可以让任何路径"变成"敏感路径。

更可靠的是白名单：只允许 Agent 在指定的工作目录内操作。具体做法是，在每次文件操作前，把目标路径解析成绝对路径，然后检查它是否以工作目录为前缀：

def is_within_workspace(target, workspace): target = os.path.realpath(target) workspace = os.path.realpath(workspace) return os.path.commonpath([target, workspace]) == workspace

注意这里用了os.path.realpath，它会解析掉所有的符号链接和 Junction，得到真实的物理路径。这一步至关重要——如果不用realpath，一个指向外部的 Junction 就能轻松绕过白名单检查。

3.4 Git 仓库的额外保护

.git目录被删是这次事故里最让人心疼的部分，因为代码本身可能还有备份，但 Git 历史一旦丢失就很难恢复。

我的做法是给.git目录加一层额外的保护：在 Agent 的工具层，任何删除操作如果目标路径包含.git，直接拒绝，除非用户显式覆盖。

def guard_git(path): parts = os.path.realpath(path).split(os.sep) if '.git' in parts: raise PermissionError("禁止删除 .git 目录，请先确认")

这个规则看起来简单粗暴，但非常有效。因为正常的工作流里，没有任何理由让 Agent 去删.git。如果它想删，一定是出了问题。

另外，我强烈建议所有用 Agent 做自动化的人，把 Git 仓库的远程备份做成自动化的。比如每次 Agent 执行完任务后，自动git push到一个私有远程仓库。这样即使本地.git被删，历史还在。

4. 如果你正在用 Claude Code 或类似工具，现在该做什么

4.1 检查你项目里的 Junction

打开 PowerShell，在你项目根目录执行：

Get-ChildItem -Recurse -Force -Directory | Where-Object { $_.Attributes -band [System.IO.FileAttributes]::ReparsePoint } | Select-Object FullName, Target

这条命令会列出所有重解析点及其目标。如果你看到任何指向项目外部路径的 Junction，就要特别小心。

我自己的项目里就发现过几个：一个是 Docker Desktop 创建的，一个是 WSL 的挂载点，还有一个是我自己之前做测试时留下的。这些在平时不影响开发，但一旦 Agent 执行删除操作，就是定时炸弹。

4.2 给 Agent 配置"安全模式"

Claude Code 本身有一些安全配置选项，但默认值偏宽松。我建议至少做这几件事：

第一，在项目根目录放一个.claudeignore或者类似的配置文件，明确排除敏感目录。虽然这不是万能的，但能挡住大部分误操作。

第二，把 Agent 的执行权限降级。不要用管理员权限运行 Agent，用普通用户权限。这样即使它想删系统目录，也会被权限拦截。

第三，开启操作日志。Claude Code 支持记录所有工具调用，把这些日志保存下来，出事后能追溯。

4.3 建立"删除前快照"机制

这是我从这次事故里学到的最实用的一招：在任何批量删除操作前，自动创建一个快照。

在 Windows 上，可以用robocopy做增量备份，速度很快：

robocopy "D:\projects\myapp" "D:\backups\myapp_%date:~0,4%%date:~5,2%%date:~8,2%" /MIR /R:0 /W:0

这个命令会在备份目录下创建一个镜像。/MIR表示镜像模式，/R:0表示不重试，/W:0表示不等待。对于几万个文件的项目，通常几秒钟就能完成。

如果你觉得每次删除都备份太重，可以只备份.git目录和关键配置文件。.git目录通常不大，但包含了全部历史，是最值得保护的部分。

4.4 重新审视你的 Agent 任务设计

最后，也是最根本的：不要让 Agent 做"清理"这种模糊任务。

"清理临时文件"这个指令对人类来说很明确，但对 Agent 来说充满了歧义。什么是临时文件？.tmp后缀的？temp目录下的？还是超过 7 天没访问的？每一种理解都可能导致不同的删除范围。

我的做法是把任务拆解成具体的、可验证的步骤：

• 第一步：列出所有.tmp文件，输出清单
• 第二步：人工确认清单
• 第三步：删除确认过的文件

这样虽然慢一点，但安全。Agent 的价值在于处理重复性工作，不在于替你做决策。把决策权留在人手里，把执行权交给 Agent，这才是正确的分工。

5. 这次事故对整个 Agent 生态的启示

5.1 Agent 的"能力边界"需要重新定义

当前 Agent 框架普遍在追求"更强的自主性"——能自己规划、自己执行、自己纠错。但这次事故说明，自主性和安全性之间存在根本性张力。

一个真正安全的 Agent，应该在关键操作前"停下来问一问"。但"停下来"意味着中断流程，意味着降低效率，意味着用户体验变差。这是产品设计上的两难。

我的判断是，未来的 Agent 会分化成两类：一类是"高自主、低风险"的，比如写代码、查资料、做分析；另一类是"低自主、高风险"的，比如文件操作、系统配置、部署上线。后一类必须有人工确认环节，这不是技术问题，是产品定位问题。

5.2 文件系统抽象层的缺失

这次事故暴露了一个更深层的问题：Agent 缺少一个理解文件系统物理结构的抽象层。

现在的 Agent 看到的文件系统，本质上还是 1970 年代 Unix 的那套抽象——目录树、文件、权限。但这套抽象没有表达"链接"、"挂载"、"重解析点"这些现代文件系统的核心概念。

我认为未来的 Agent 框架需要引入一个"文件系统感知层"，它能够：

• 区分逻辑路径和物理路径
• 识别链接、Junction、挂载点
• 理解删除操作的"影响范围"
• 在操作前评估风险等级

这个层不需要很复杂，但必须有。否则类似的悲剧还会重演。

5.3 给 Agent 开发者的具体建议

如果你正在做 Agent 开发，我建议在架构层面做这几件事：

第一，工具层做安全封装。不要让 Agent 直接调用rm -rf或Remove-Item，而是调用你自己封装的safe_delete。这个函数内部处理链接检测、路径校验、数量限制。

第二，引入"影响范围预估"。在执行任何破坏性操作前，先计算它会影响到多少个文件、多大空间、哪些路径。如果超出阈值，触发确认。

第三，记录完整的操作审计日志。包括操作时间、操作类型、目标路径、影响范围、执行结果。这些日志在出事后是唯一的追溯依据。

第四，做"沙盒预演"。对于高风险操作，先在一个隔离环境里执行一遍，观察结果，再决定是否在真实环境执行。这在技术上完全可行，成本也不高。

6. 我自己的防护配置分享

最后分享一下我目前在用的配置，供参考。

在 Claude Code 的项目配置里，我加了这样一段：

{ "permissions": { "deny": [ "Bash(rm -rf:*)", "Bash(Remove-Item -Recurse:*)", "Bash(rd /s:*)", "Bash(del /f /s /q:*)" ], "allow": [ "Bash(git status:*)", "Bash(git diff:*)", "Bash(ls:*)", "Bash(dir:*)" ] } }

核心思路是：禁止所有递归删除命令，只允许查看类命令。如果 Agent 确实需要删除文件，它必须用我提供的自定义工具，那个工具内部有安全检查。

另外，我在项目根目录放了一个SAFETY.md，里面写清楚了哪些目录不能碰、哪些操作需要确认。虽然 Agent 不一定会读，但至少在我 review 它的操作时，有个参照。

还有一个小技巧：我会定期用fsutil reparsepoint query扫描项目目录，把所有 Junction 记录下来。如果发现新的、不是我创建的 Junction，就立即排查来源。这个习惯帮我发现过几次工具自动创建的链接，避免了潜在风险。

说到底，Agent 是个强大的工具，但工具越强大，使用者的责任就越大。103 秒删 4.8 万个文件这件事，与其说是 AI 的问题，不如说是我们这些做工具、用工具的人，还没有建立起与之匹配的安全意识。这个坑，值得每个做 Agent 的人认真踩一遍——当然，是在别人的事故里踩，不是在自己的生产环境里踩。