小白学 AI Agent 第 3 期：让 Pi 读文件、改文件、跑命令

前两期里，Pi 已经装好，也完成了登录和模型选择。到这里，它还只是一个能聊天的终端程序。

Pi 真正像 Agent 的地方，在于它可以调用工具。默认工具里最需要先弄懂的是 read、write、edit 和 bash。

这四个词看起来简单，但风险完全不同。读文件通常只是查看，写文件会创建或覆盖内容，编辑文件会改动已有内容，运行 Bash 命令则可能影响系统、网络和其他程序。

所以这一期不直接碰重要资料，只在 Windows 上新建一个空的练习目录。

一、四个工具分别做什么

`read`：先看，再判断

read 用来读取文件内容。你可以让 Pi 查看一个文本、配置或代码文件，再让它解释其中的内容。

它适合做第一步，因为你能先看到 Pi 读了什么。对新手来说，任何修改任务都应该先从 read 开始。

`write`：创建或覆盖文件

write 用来创建文件，也可能覆盖已有文件。它不是“保存一下回答”，而是实实在在地把内容写入电脑。

如果文件已经存在，覆盖操作可能会抹掉原来的内容。因此第一次练习时只使用新文件名，例如 notes.txt，不要让 Pi 直接处理工作资料。

`edit`：修改已有内容

edit 用来修改文件中的一部分内容。它通常比整文件覆盖更精细，但仍然会改变磁盘上的文件。

“只改一行”听起来风险较小，实际仍然要确认文件路径和修改前后的差异。不要因为改动范围小就跳过检查。

`bash`：运行命令

bash 让 Pi 在终端里执行命令。它能列出目录、运行检查脚本、安装依赖，也可能删除文件、访问网络或启动程序。

Pi 默认使用启动它的用户权限。它不是一个自动隔离的安全沙箱。看到命令时，先读懂命令和目标路径，再决定是否执行。

二、先建一个专门的练习目录

在 Git Bash 中运行：

mkdir -p ~/pi-tools-test
cd ~/pi-tools-test

然后启动 Pi：

pi

这个目录只用来练习。里面没有重要文件，也不放 API Key 、照片、合同或项目源码。

进入后先输入：

请确认当前工作目录，并列出你现在能使用的工具。只查看，不要修改文件，也不要运行安装命令。

这一步的目的不是测试模型有多聪明，而是确认 Pi 是否在正确目录里，并观察它是否会先解释计划。

三、第一次练习：让 Pi 创建一个小文件

现在让 Pi 创建一个只有几行内容的文件：

请在当前练习目录创建 notes.txt，写入三行：
第一行：这是 Pi 的工具练习。
第二行：先读，再改，最后执行命令。
第三行：所有写入操作都要先确认路径。
创建前请告诉我目标路径，等我确认后再写入。

这里故意要求它先说路径，再等待确认。即使你已经知道这是安全目录，也保留这个习惯。

Pi 如果准备调用 write，界面里应该出现工具调用提示。确认路径正确后再允许执行。

然后让 Pi 读取：

请读取 notes.txt，并逐行告诉我文件里有什么。不要修改文件。

这次应该使用 read。你可以对照工具结果，确认它读取的确实是刚才创建的文件。

四、第二次练习：只改一处

接着让 Pi 把第二行中的“执行命令”改成“运行检查”：

请只修改 notes.txt 的第二行，把“最后执行命令”改成“最后运行检查”。
先告诉我当前文字、新文字和文件路径，等我确认后再执行。

这是 edit 的典型场景。确认时看三件事：

文件路径是不是 notes.txt。
要替换的文字是否真的存在。
新文本有没有扩大到其他段落。

修改完成后，再用 read 读取文件。不要只相信 Pi 的一句“修改成功”。

五、第三次练习：运行一个无害命令

最后让 Pi 列出当前目录中的文件：

请运行一个只查看当前目录文件名的命令，不要安装、删除、移动或联网。
执行前先告诉我具体命令。

这会触发 bash。你要看清楚它准备运行的命令。只查看目录的命令和删除目录的命令，风险不是一个级别。

在 Git Bash 中，下面这种命令通常只查看文件名：

ls

但不要把“看起来简单”当作永远安全。命令前面的脚本、别名、路径和参数都可能改变结果。

六、工具调用时你要看什么

每次 Pi 准备调用工具时，按这个顺序检查：

工具名：它是 read、write、edit 还是 bash？
路径：目标是不是你刚才指定的练习目录？
参数：有没有多出来的文件、命令或网络地址？
结果：工具返回后，结果是否符合预期？

模型会根据上下文决定下一步，但最终承担电脑操作后果的人还是你。

七、哪些任务先不要交给 Pi

刚开始练习时，先避开这些任务：

批量重命名或删除文件。
修改系统目录和注册表。
安装来源不明的软件包。
让 Pi 读取包含密码、 Key 或个人信息的文件。
让 Pi 直接在生产项目里运行命令。

等你熟悉工具调用、工作目录和项目权限后，再逐步扩大范围。 Agent 的效率来自边界清楚，不是来自“什么都允许”。

这一期你已经完成了一个最小闭环：write 创建文件，read 查看文件，edit 修改一处，bash 运行只读命令。

下一期会解释 Pi 为什么知道项目规则，以及会话为什么能继续上次的工作。我们会认识工作目录、AGENTS.md、会话和上下文。