1. 满心欢喜上线工具权限，差点被自己的 Agent 删库跑路
这大概是今年让我最头秃的一个项目。给内部的 AI Agent 加了工具权限，本意是让它可以读文件、改文件，甚至执行一些常规查询，结果第一天跑测试就把同事的本地代码目录删了三分之一。
我记得很清楚，当时我调用了一个删除无用缓存目录的函数，Agent 基于我编写的一段模糊描述，直接扫到了项目根目录里的.delete_me同名文件夹，还顺带把docs下的临时备份给清理了。当时我的反应是“见鬼了”，然后立刻把所有工具权限关停，开始排查。
先说结论：工具权限不是“开不开”的问题，而是“怎么开、开多大、如何双保险”的问题。你不管权限边界，Agent 一定会在某个你没想到的路径上闯祸。这篇文章不是纯理论指导，而是我花了整整三天，从一个真实事故出发，完整复盘 Agent 工具权限设计的思路、误删根因、修复方案，以及最终用了哪些手段来防止同类事故再次发生。
如果你正在从 0 到 1 搭建 AI Agent，或者手里有一个正在接入文件操作能力的智能体，这篇文章大概率能帮你避开我踩过的这些坑。
2. 第一天：我以为权限给得够小了，它还是把文件删了
先说现场。我的 Agent 用的是函数调用方案，后端封装了几个核心工具：read_file、write_file、delete_file、list_directory。听起来很普通对吧？很多教程都会教你这样封装，但问题恰恰出在“边界模糊”和“语义歧义”上。
我当时给 Agent 的指令是：“清理项目中的临时文件和缓存，保持目录整洁。”这个描述从人类视角看没问题，但从 Agent 的解析逻辑看，它需要自己去判断哪些文件是“临时”的、哪些是“缓存”的，那么这个判断依据是什么？我的函数签名里完全没有写。
所以它开始干活之后，我是怎么发现的？本地开发环境里突然有同事大喊“卧槽我代码呢”。我过去看，发现 Agent 在 commit 之前把src/utils下的一堆.bak文件删了——问题是那不是备份文件，那是同事手动改的调试副本，扩展名碰巧是.bak，里面全是新写的逻辑。
当时我的排查思路是这样的：
- 第一步，查 Agent 的操作记录，发现它调用了
delete_file，路径是/local/projects/xxx/src/utils/helpers.bak。 - 第二步，查上下文，发现 Agent 是通过
list_directory扫描目录后，根据“文件名以 .bak 结尾” + “修改时间较早”判断为临时文件。 - 第三步，发现问题的核心：不是“文件名判断”错了，而是我的
delete_file工具没有二次确认机制，也没有限制删除范围。
那个下午我做了两件事：把工具权限收回，改成只读模式；然后写日志审计，把每条操作记录下来。但说实话，这只是一个临时止血方案，因为它根本没有解决“Agent 为什么会做出这样的判断”这个深层次问题。
晚上我躺在床上复盘，越想越觉得不对劲。即使我加了二次确认，如果 Agent 自己判断“这个确认是多余的”，或者说它因为某些上下文误导，把要保留的文件误判为要删除的文件，二次确认也可能变成走流程。
3. 第二天：追查根因，发现坑比我想象的多
第二天我决定不急着改代码，先做一件更基础的事情：把 Agent 的完整决策链路扒出来看。
我用的框架是 LangChain 的函数调用版本，也就是 model 决定调用哪个 function，然后由我的回调执行对应操作。我查了对话记录，看到了它的完整推理过程：
- Agent 收到用户指令：“清理临时文件。”
- Agent 调用
list_directory扫描/local/projects/xxx。 - 它看到了
.bak、.tmp、node_modules/.cache、__pycache__。 - 它根据文件名后缀和“这个 .bak 修改时间是一周前”推断这个文件不再需要了。
- 它调用
delete_file("/local/projects/xxx/src/utils/helpers.bak")。 - 然后它继续删了
.tmp和__pycache__，最后还跑了一次 git status，发现没有异样。
从过程看，Agent 是完全“按逻辑”走的，问题出在我没有给它足够的约束。我没有告诉它：哪些目录是禁止操作的、哪些文件类型必须跳过、删除前必须向用户确认、删除操作必须使用软删除（移动回收站）。
还有一个更隐蔽的问题，也是我最懊恼的：list_directory返回的路径信息太粗糙了。我把整个目录树都给 Agent 看，但没标注“这个文件是源码的一部分”“这个目录是 git 管理的”“这个文件夹是最近三天修改过”。Agent 的上下文窗口里只有文件名，它怎么分辨？它根本分辨不了。
这才是误删的根因，不是模型能力不行，而是我作为开发者给它的“信息维度”不够。如果把文件元数据（修改时间、所属模块、git 状态、最近访问记录）都结构化传进去，Agent 的判断会准确得多。
另外我还发现了一个框架层面的问题：函数调用的 description 太短了。我写delete_file的 description 是“删除指定路径文件”，没有说明“这是危险操作，必须确认”，更没有定义“如果路径包含 src、lib、config 等关键字，应直接忽略”。你以为你自己知道，但模型就是严格按你给的 description 来推理的，你没写，它就不知道。
这一天结束时，我得出了三个关键结论：
- 工具权限的核心不是“能不能调用”，而是“调用边界在哪里”。
- Agent 的判断依赖上下文信息质量，文件列表不是拿来就用的，要增强元数据。
- 危险操作必须设计独立的协议，不能靠模型自觉。
4. 第三天：彻底重构工具权限，弄懂“能力”和“权力”是两码事
第三天上午，我开始重新设计整个工具权限体系。我参考了一些安全的做法，也看了不少同行在这个问题上的思路，最后总结出一套我认为比较实用的模型，我管它叫“三层隔离 + 危险操作协议”。
先说最核心的思想：工具能力（capability）和操作权限（authorization）必须分离。
什么意思？就是说，Agent 可以“知道”自己有删除工具，但不代表它可以“随时”调用它。删除、修改、覆盖这类不可逆操作，应该走单独的授权流程。这个流程不是靠提示词控制，而是要在代码层面做硬限制。
我设计的结构是这样的：
- 第一层：系统级沙箱。Agent 的所有工具调用都通过一个统一的
ToolExecutor类，这个类会检查操作路径是否在白名单范围内。 - 第二层：工具级配置。每个工具都有独立的
action_type，分为read、write、delete、execute四类。不同类型操作有不同的触发条件。 - 第三层：操作协议。对高危操作强制要求“确认令牌”（confirmation token），这个令牌是由用户通过界面点击生成的，Agent 自己拿不到。
4.1 系统级沙箱的具体实现思路
操作路径白名单我是这样定的：启动时读取一个配置文件，里面定义了哪些目录允许写，哪些目录允许删，其他一律拒绝。配置大概是这样的：
allowed_write_dirs: - /data/workspace/tmp - /data/workspace/generated deletable_dirs: - /data/workspace/tmp对，你没看错，deletable_dirs和allowed_write_dirs是分开的。因为一个目录可能允许 Agent 写文件，但不允许它删除文件。比如说/data/workspace/generated，Agent 可以创建新内容，但不能删历史生成物，这完全是合理的需求。
我在ToolExecutor里实现了路径解析和边界检查。如果 Agent 试图删除/data/workspace/generated/old.json，Executor 发现generated不在deletable_dirs里，直接返回“操作被拒绝”，连确认流程都不用走。这样从根上卡死了大部分误删。
4.2 工具级操作分类
我重新整理了工具集，不再是一个粗粒度的delete_file一把梭，而是拆成了三档：
- 低危操作：
read_file、list_directory、get_file_info，可直接调用。 - 中危操作：
write_file、create_file，需要路径在白名单内才能执行。 - 高危操作：
delete_file、move_file、overwrite_file，必须额外满足条件：路径必须在deletable_dirs白名单内，且必须经过“确认令牌”校验。
什么叫“确认令牌”？我在用户界面上做了一个审查队列。当 Agent 发起删除请求时，后端不会直接执行，而是把这个请求推到用户的待确认列表里，用户看到的是：
- 操作类型：删除
- 目标路径：/data/workspace/tmp/old_output.json
- 文件大小：2.3MB
- 修改时间：2026-01-12
- 风险提示：该文件已被 git 跟踪
用户点“确认”之后，系统生成一个 7 位数字令牌，并且只有在 30 秒内把这个令牌通过界面回传给 Agent，Agent 才能继续执行删除。有人可能问：为什么不直接用 UI 上的“确认”按钮？因为 Agent 是自主运行的，它可能已经结束对话了，我们需要这个令牌出现在上下文里，它才能继续让自己“说服”工具执行器。
其实更准确地说，确认令牌是我给“二次确认”加的一道强制约束，防止 Agent 自己跳过确认步骤。
4.3 给 Agent 的提示词也要加约束
代码层做完了，我还改了 Agent 的 system prompt。原来的 prompt 说“你是一个智能助手，可以调用工具完成任务”，这太开放了。我改成：
- 删除文件之前，必须列出目标文件的完整路径和删除原因。
- 如果路径中包含
git管理的核心源码文件，必须禁止删除。 - 除非用户明确指定，不得对修改时间在最近 48 小时内的文件执行删除。
- 批量删除必须逐个确认，禁止使用通配符路径。
这些约束不一定百分之百有效，但配合代码层的白名单，能覆盖绝大多数误删场景。因为代码层已经做了兜底，即使 Agent 产生幻觉，它也删不了白名单之外的文件。
5. 实测跑了一个月，误删归零，还意外收获几个经验
重构完成后，我花了整整一周做压力测试。测试场景包括：让 Agent 在不同目录下执行清理、让用户故意发出带歧义的指令、模拟多个 Agent 并发操作同一个目录、甚至给 Agent 塞入一些恶意的“低质量上下文”看它能不能对抗。
结果比较理想，误删归零。唯一一次差点出问题，是 Agent 在处理/tmp下的一个生成器输出的旧文件时，试图用move_file把它移到垃圾站。但移完后我发现它把同步配置文件也带过去了，因为那个文件也符合“清理条件”。好在最终确认列表里用户看到了路径，直接点了拒绝，没有造成损失。
我要说的是，权限体系不是给你自己的 Agent 设置的，而是给“未来的 Agent”设置的。你现在只有一个 Agent 一个模型，但团队里每个人都可以起新的 Agent，用的模型可能不一样，上下文长度不一样，理解能力也不一样。系统级的权限约束是唯一能跨模型生效的保障。
我还发现一个有意思的细节：加了确认令牌之后，Agent 的自主性确实下降了。以前它能一口气删十个文件，现在必须卡在确认列表里等待。但仔细想想，这个“卡”是合理的。一个高风险的 Agent 操作，本来就不该让它在无人知晓的情况下全部执行完。而且我是可以配置哪些目录、哪些文件类型需要走确认协议的。像/data/workspace/tmp这种低价值目录，我可以直接把该目录加入“免确认”白名单，操作就流畅了。
这就是权限设计中常见的一种方法，不同风险域用不同策略，而不是一刀切禁用所有危险工具。具体来说，我目前有三类风险域：
- 高风险域：包含源代码、数据库脚本、配置文件等，高强度管控，所有不可逆操作都必须用户确认。
- 中风险域：包含生成物、缓存、临时输出文件，允许 Agent 自主执行删除，但路径白名单严格限制。
- 低风险域：独立的沙箱目录，Agent 可以随意读写删除，反正里面全是可再生资源。
我个人强烈建议，如果你刚开始做 Agent 工具权限，不要试图在第一天就把所有域都配好。先在低风险域里跑通流程，确认 Agent 的操作稳定了，再逐步开放中风险和高风险域。否则你会像之前的我一样，一个delete_file直接打穿本地项目。
6. 最后再分享一个我后来才补上的小细节
整个三天排查过程中，我一直漏掉了一个东西：操作审计。前三天我都在想“怎么防止 Agent 删文件”，但没想过“文件到底是谁删的，是否可追溯”。后来我复盘时意识到，审计日志才是最后一道防线。即使权限体系已经很完善，必须有日志记录每一次调用，包括传入参数、调用链、结果、耗时。
我现在的实现是，给每个工具调用分配一个唯一trace_id，写入结构化日志。内容包含：
- 时间戳
- Agent 会话 ID
- 模型版本
- 工具名称
- 输入参数（脱敏后）
- 执行结果
- 命中哪个权限策略
这些日志平时不怎么看，但真出问题时，它们就是排查的唯一线索。比如我后来遇到过一个问题：某个 Agent 会话调了 23 次write_file，覆盖了一个工具的配置。我没有这些日志的话，根本不知道是哪个会话干的、什么时候干的、改了什么。
我最后想说的是，给 AI Agent 加工具权限这件事，本质上是在“效率”和“可控性”之间做取舍。你能给 Agent 越多的自主权，它的效率提升越明显，但你需要做的安全加固就越多。不要相信模型的自律，永远用代码和协议去约束它。
误删文件这个坑，我花三天堵住了，但我希望你不要重走这三天的弯路。权限设计提前做，审计日志从第一天就开，危险操作强制确认，路径白名单写清楚。这四点做到，你的 Agent 就可以一边帮你干活、一边不惹祸了。
