Read、Write、Edit 与 Bash

#你将得到什么

第 07 章的 Agent Loop 已经能可靠执行抽象工具，但 echo 只会返回一段文字。真正的 编程 Agent 还要读取文件、修改文件并运行命令。接入这些能力后，错误不再只存在于 消息列表里：一次调用可能覆盖文件、只写入半份内容，或启动一个不会自行结束的进程。

本章只增加一种复杂性：对学习环境产生副作用。你会实现 createCodingTools()，让它注册四个工具：

四个工具共用第 06 章的参数验证与错误结果，也由第 07 章的循环负责 call/result 配对。本章不重新实现这两层，只处理文件和进程自己的边界。

涉及文件或进程的测试都会创建临时目录；MutationQueue 的纯内存测试不接触磁盘。 不要把教材仓库、工作项目或个人目录当作练习数据。

#开始前：只认一条练习路线

在教学历史仓库运行：

npm run practice -w @pi/course -- 08 <新目录>
cd <新目录>
npm install

生成器会保留第 07 章的实现，注入第 08 章测试，并放入一份学习脚手架。脚手架声明 公共类型、createCodingTools() 和六段 Lab 的施工位置，但不包含路径解析、文件 提交、编辑或进程管理算法。

需要重来时，创建另一个练习目录。隔离目录没有 Git 历史，不要运行恢复 commit 的 命令，也不要查看 target diff。

本章要守住三个不变量：

1. read 只报告完整显示的行，续读位置必须紧接最后一条完整观察；
2. write/edit 在检查完成前不提交文件变化，同一路径的修改按登记顺序执行；
3. bash 无论成功、非零退出、超时还是取消，都只形成一个有界的终态结果。

#先建立全景

#四个工具共享一条处理路径

工具名称不同，处理步骤却可以统一：

ToolCall
  │
  ├─ 第 06 章：验证参数，绑定 callId 与 signal
  │
  ├─ 本章：解析路径或准备进程
  │
  ├─ 本章：执行有界观察或提交副作用
  │
  └─ 第 06/07 章：形成 ToolResult，再写入 transcript

read 只观察环境；write 和 edit 修改环境；bash 启动另一个执行主体。因此， 它们需要的限制也不同：

#第一步：让 Read 只报告完整观察

read 同时受行数和字节数限制。行数限制防止一次返回整份大文件；字节限制防止少数 超长行占满模型上下文。两种限制都必须落到同一个可恢复结果上：

   3│ gamma
   4│ delta

[已显示第 3-4 行，共 9 行；继续读取：offset=5]

startLine 和 endLine 描述真正显示的完整行。若字节上限只容纳第 3 行， endLine 必须是 3，续读位置必须是 4。不能先算出“准备读取到第 4 行”，再把输出 从中间截断，却仍告诉模型从第 5 行继续；那会永久跳过第 4 行的一部分。

一个稳妥的算法是逐行构造带行号的文本：

1. 从 offset 指定的行开始；
2. 先格式化下一条完整行；
3. 只有加入它后仍不超过字节上限，才把它计入结果；
4. endLine 取最后一条已加入的行；
5. 文件还有内容时，续读位置为 endLine + 1。

如果第一条编号行连同必要的续读提示都放不进上限，就返回明确错误。课程不返回半行， 因为当前接口只有按行续读的 offset，没有从一行中间继续的字节游标。

npm run build -w @pi/course
node --test --test-name-pattern="Lab 8.1" \
  packages/pi-course/dist/test/08-*.test.js

#第二步：让路径判断覆盖符号链接

path.resolve(cwd, input) 可以处理 ../ 和绝对路径，却只看字符串。假设 workspace/link 是一个指向外部目录的符号链接，那么 workspace/link/secret.txt 在字符串上仍位于 workspace 内。

课程的 "workspace" 模式分两层检查：

1. 先把输入解析为绝对路径，拒绝词法上位于 cwd 外的结果；
2. 再取得真实路径。如果目标已经存在，就对目标调用 realpath。如果目标尚不存在， 就从它的父目录逐层向上，找到第一个已存在的目录，再对该目录调用 realpath。 这样可以避免通过指向外部的符号链接创建文件。

read、write 和 edit 必须共用这一段解析逻辑。三个工具各写一份近似判断， 很容易出现“读被挡住，写却能越界”的缝隙。

这仍是一层学习环境保护，不是无法绕过的安全边界。检查与实际打开文件之间存在 时间窗口；另一个进程可以改动符号链接。强隔离要交给操作系统级沙箱。

npm run build -w @pi/course
node --test --test-name-pattern="Lab 8.2" \
  packages/pi-course/dist/test/08-*.test.js

#第三步：把 Write 变成一次明确提交

write 的语义应当简单：父目录不存在就创建；目标存在就整体覆盖。它不猜测用户想 追加、合并还是保留哪一段。

直接向目标文件写入时，其他读者可能看见半截内容。课程先在同一目录写临时文件， 再用 rename 替换目标：

content
  → mkdir(parent)
  → write(path.pi-tmp-...)
  → rename(temp, path)
  → { path, bytes }

同一组工具里的 write 和 edit 还要共享修改队列。对同一路径，先登记的操作完成 后，下一项才进入自己的读取或提交阶段。不同路径不需要共用一把全局锁。

这里的“同一路径”是同一个解析后的绝对路径键。测试不靠大文件或计时制造竞态。 一项测试记录默认 MutationQueue.run() 的实例和路径键，证明同一次 createCodingTools() 注册的 write/edit 共用队列；另一项直接用 Promise gate 控制执行顺序，分别观察同路径等待、不同路径继续执行，以及失败后释放下一项。 本章不规定两个独立 Registry 是否还要共用队列。

测试还会为旧文件创建一个硬链接作为见证。若实现直接改写目标，见证文件也会跟着 变化；若实现用 rename 替换目标路径，见证文件仍保留旧内容。另一个输入会故意让 rename 失败，再检查旧目录没有变化，课程临时文件也已经清理。这样可以观察提交 与清理行为，而不用猜测文件操作需要多长时间。

这项设计缩小了半成品可见窗口，但它不等于数据库事务。课程没有证明断电持久性、 权限继承、跨文件原子性，也无法阻止课程之外的进程同时写同一文件。

npm run build -w @pi/course
node --test --test-name-pattern="Lab 8.3" \
  packages/pi-course/dist/test/08-*.test.js

#第四步：Edit 先验证整批，再写一次

edit 接受精确的 oldText → newText。零次匹配表示当前观察已经过期；多次匹配 表示定位信息不足。两种情况都应失败，不能擅自挑第一处。

批量编辑按数组顺序作用于一份内存副本。后一项能看见前一项的结果：

let next = current;
for (const edit of edits) {
  // oldText 必须在 next 中恰好出现一次
  next = applyExactReplacement(next, edit);
}
// 全部成功后才提交一次
await atomicWrite(file, next);

这条顺序规则允许第二项修改第一项刚生成的文本。任何一项失败时，函数在进入 atomicWrite() 前结束，磁盘文件应与调用前逐字节相同。oldText 不能为空， 否则空字符串会在每个位置“匹配”，唯一性也失去意义；newText 可以为空，因为 删除是一种合法编辑。

npm run build -w @pi/course
node --test --test-name-pattern="Lab 8.4" \
  packages/pi-course/dist/test/08-*.test.js

#第五步：把 Bash 当成一段生命周期

spawn() 返回子进程对象，只表示进程已经开始。工具还要同时管理 stdout、stderr、 非零退出、启动失败、timeout、外部 abort 和输出上限。

预取消 ───────────────→ 不 spawn → aborted result

spawn
  ├─ stdout/stderr ───→ 持续消费，只保留上限内的字节
  ├─ exit 0 ──────────→ success result
  ├─ exit 非 0 ───────→ error result
  ├─ timeout ─────────→ 请求终止进程组 → timedOut result
  └─ abort ───────────→ 请求终止进程组 → aborted result

stdout 和 stderr 都要持续读取，否则其中一个管道写满后，子进程可能一直等待。 对已经启动的命令，捕获的 stdout、stderr 与截断说明共用 maxBashOutputBytes。发生截断时，先给说明留出字节，再用剩余空间保存子进程输出。 工具执行器在外层生成的错误说明，以及预取消时的固定提示，不属于这项输出预算。 测试会让两路同时产生输出并检查共同预算；它没有把管道写满。达到上限后仍继续排空 两条管道，要从你的数据监听代码中确认。

"workspace" 模式还会拒绝命令字符串中显式出现的绝对路径、~/ 和 ../。测试用 目录外标记文件确认绝对路径和 ../ 命令没有启动；~/ 分支由源码审查确认。这只是 防止练习时常见误操作的字符串检查；shell 仍能使用环境变量、程序参数和系统调用 访问工作目录之外的资源。

timeout 与 abort 可能同时到达，进程也可能恰好自行退出。清理动作要幂等：多次请求 终止不会生成多个结果，timer 与 abort listener 最终都要移除。在 POSIX 系统上， 课程先向同一进程组发送 SIGTERM，短暂等待后再发送 SIGKILL，并等这段清理结束 才返回。测试还会启动一个忽略 SIGTERM 的后代进程，确认它不能在工具返回后继续 写标记文件。测试直接观察终止处理器与后代标记；是否等待 close 和强杀步骤、 是否移除 timer 与 listener，还要从源码中的 await 和 finally 确认。测试命令 全部固定，不会拼接外部输入，也不会访问网络。

npm run build -w @pi/course
node --test --test-name-pattern="Lab 8.5" \
  packages/pi-course/dist/test/08-*.test.js

#第六步：让真实工具走完 Agent Loop

前五步分别验证工具。最后还要证明它们能进入第 07 章的消息协议。使用 ScriptedModel 安排四轮确定行为：

assistant(read)  → toolResult(read)
assistant(edit)  → toolResult(edit)
assistant(bash)  → toolResult(bash)
assistant(final) → stop

测试使用临时文件和固定本地命令，不调用模型 API。它要同时观察两类事实：

• 环境事实：文件确实被 edit 改写，bash 确实在指定目录检查到新内容；
• 协议事实：每个 call 都有同 id/name 的 result，最后一轮才以 stop 结束。

npm run build -w @pi/course
node --test --test-name-pattern="Lab 8.6" \
  packages/pi-course/dist/test/08-*.test.js
node --test packages/pi-course/dist/test/08-*.test.js

#故意把它弄坏

编辑测试会创建一份包含两个相同片段的临时文件。暂时把“多次匹配时报错”改成只替换 第一处，再运行 Lab 8.4：

正确：匹配 2 次 → isError=true → 文件不变
错误：匹配 2 次 → isError=false → 第一处被悄悄修改

#本章没有证明什么

12 项测试没有把课程变成安全沙箱，也没有覆盖以下性质：

• 文件路径检查与实际打开之间的符号链接竞态；
• 断电持久性、权限与时间戳继承、跨文件事务；
• 课程外进程同时修改同一文件；
• 两个独立 Registry 同时修改同一路径时是否共用队列；
• 通过不同硬链接或内部符号链接别名访问同一物理文件时的统一排队；
• 并发读者是否在所有文件系统上都看不到提交中的临时状态；
• 文件操作的运行中取消；
• stdout 与 stderr 混合后的稳定先后顺序；
• spawn 启动失败，以及 timeout 与 abort 同时到达时的优先级；
• timer、abort listener 与延迟强杀任务是否在每条异常路径都完成清理；
• 脱离原进程组的后代，以及 Windows 上完整的子进程树回收；
• 任意 shell 输入的转义、命令审批、网络或密钥隔离；
• 超大文件的流式读取和所有 UTF-8 异常输入。

测试通过只说明：在本章固定环境和输入下，列出的路径、提交、编辑、进程与消息行为 符合约定。

#本章验收

#可选迁移练习

#小结

文件和进程工具的难点不在 Node API 的调用方式，而在结果是否可恢复、修改是否能 确定提交、进程是否一定结算。Read 只报告完整观察；Write 明确整体覆盖；Edit 先验证 整批；Bash 管理输出和终点。课程 containment 能减少练习时的误操作，但不能代替 操作系统隔离。下一章会在这个循环外增加可持续的 Agent 状态和用户时序控制。