四个工具怎样在同一个 workspace 里完成文件任务

#同一个 task.txt 经过四次调用

第 07 章用返回固定 README 内容的内存 read 闭合了反馈回路。现在把它换成访问 同一个 workspace 的 read、write、edit 和 bash；Agent Loop 的接口不变。

下面的 workspace 是测试临时创建的目录。目录里只有一个文件：

workspace/
└── task.txt        内容是 status: draft

createCodingTools() 为这个目录创建一张工具表：

const tools = createCodingTools({
  cwd: workspace,
  containment: "workspace",
});

四次调用始终使用同一个 tools 和同一个相对路径 task.txt。为了让代码短一些，下面的 run() 只负责构造 ToolCall 并交给第 06 章的 executor：

async function run(id: string, name: string, argumentsValue: unknown) {
  return executeToolCall({
    type: "toolCall",
    id,
    name,
    arguments: argumentsValue,
  }, tools);
}

const readResult = await run("read-1", "read", {
  path: "task.txt",
});

const writeResult = await run("write-1", "write", {
  path: "task.txt",
  content: "status: draft\ncheck: pending",
});

const editResult = await run("edit-1", "edit", {
  path: "task.txt",
  oldText: "status: draft",
  newText: "status: done",
});

const bashResult = await run("bash-1", "bash", {
  command:
    "node -e \"const fs=require('node:fs'); const s=fs.readFileSync('task.txt','utf8'); if(!s.includes('status: done')) process.exit(2); process.stdout.write('verified')\"",
});

四条结果的正文依次是：

read   →    1│ status: draft
write  → 已写入 28 bytes
edit   → 已完成 1 处精确替换
bash   → verified

磁盘上的最终内容是：

status: done
check: pending

这四次调用已经形成一条完整的正常路径。read 返回自己实际看见的内容；write 整体 覆盖文件；edit 替换一处经过检查的精确文本；bash 从同一个 workspace 启动，并读到修改 后的文件。

每条结果还有结构化的 details。其中的绝对路径随临时目录变化，下面用 $workspace/task.txt 表示同一个文件：

read.details  = { path: "$workspace/task.txt", bytes: 13,
                  lines: 1, startLine: 1, endLine: 1, truncated: false }
write.details = { path: "$workspace/task.txt", bytes: 28 }
edit.details  = { path: "$workspace/task.txt", oldBytes: 28,
                  newBytes: 27, edits: 1 }
bash.details  = { exitCode: 0, timedOut: false,
                  aborted: false, truncated: false, ... }

正文给下一轮模型阅读，details 给程序检查。四条结果仍沿用原 call 的 id 和 name；这项 配对工作已经由第 06、07 章完成。coding-tools.ts 只负责把文件或进程的实际结果填进 这两个位置。

#read 只返回能够完整显示的行

开头的一行文件没有触发截断。文件变成两行以后，可以把同一个 task.txt 放进更小的 读取窗口：

const limitedTools = createCodingTools({
  cwd: workspace,
  containment: "workspace",
  maxReadLines: 1,
});

await executeToolCall({
  type: "toolCall",
  id: "read-page-1",
  name: "read",
  arguments: { path: "task.txt" },
}, limitedTools);

第一份正文是：

   1│ status: done

[已显示第 1-1 行，共 2 行；继续读取：offset=2]

第二次传入 offset: 2，就会从下一条尚未显示的完整行开始：

   2│ check: pending

read 同时接受行数上限和字节上限。实现逐行生成带编号的候选正文，并把续读提示也 算进字节数。只有整条候选仍在 maxReadBytes 内，这一行才进入结果。

因此，endLine 记录实际显示的最后一条完整行。它不能记录循环原本准备读取到哪里。 文件还有内容时，续读位置为 endLine + 1。这两个值都从已经加入正文的行推导，所以 下一次读取不会漏掉被字节上限挡住的内容。

如果第一条编号行连同续读提示也放不下，工具返回错误。当前接口只提供按行续读的 offset，没有一行内部的字节游标；返回半行后将无法准确继续。

ReadDetails 中的 bytes 和 lines 描述整个文件，startLine/endLine 描述这次真正 显示的窗口，truncated 表示文件后面是否仍有内容。这些字段与正文说的是同一次观察。

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

#三个文件工具从同一个 root 解析路径

正常轨迹中的 task.txt 是相对路径。path.resolve(workspace, "task.txt") 把它变成 $workspace/task.txt。在 containment: "workspace" 下，read、write 和 edit 都调用 同一个 resolvedPath()，所以三者以相同方式理解这个名字。

路径检查分两层。第一层处理字符串路径：

workspace + task.txt       → $workspace/task.txt       接受
workspace + ../secret.txt → $parent/secret.txt         拒绝
绝对的 /outside/file.txt  → /outside/file.txt          拒绝

第二层处理符号链接。字符串 $workspace/link/secret.txt 看起来仍在 root 里面，但 link 可能指向外部目录。目标存在时，realpath() 取得目标的真实位置；目标尚未存在时， nearestExistingPath() 向父目录查找，直到找到一个能取得真实位置的祖先。真实位置仍在 root 内，文件工具才继续。

新文件也要检查最近的已存在祖先。否则，write 可以沿一个指向外部的目录链接创建 link/new.txt，即使 read 已经挡住同一条路径。

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

这层检查会减少练习中的路径误操作。检查路径与真正打开文件之间仍有时间窗口，其他 进程可以在这个窗口修改符号链接。它是一层课程 containment，不是操作系统安全边界。

#write 用 rename 提交完整内容

开头的 write 把 task.txt 从一行整体覆盖成两行。它不会推测“这段 content 是追加 还是合并”；传入的字符串就是文件的新内容。

atomicWrite() 先创建父目录，再在目标文件旁边写一个临时文件：

"status: draft\ncheck: pending"
        │
        ├─ mkdir($workspace)
        ├─ write($workspace/task.txt.pi-tmp-...)
        ├─ rename(temp, $workspace/task.txt)
        └─ details.bytes = 28

rename 替换目录项，成功后目标路径才指向新内容。测试为旧文件创建一个硬链接作为 见证：直接改写旧 inode 时，硬链接也会变化；使用 rename 后，硬链接仍保存旧版本。 测试还让一次 rename 提交失败，随后确认原目录内容未变，而且旁边没有残留临时文件。

write 和 edit 都会修改文件。现在让三项修改几乎同时到达：

A: write(task.txt)   已进入写入步骤
B: edit(task.txt)    等待 A
C: write(notes.txt)  立即进入写入步骤

A 抛错并退出
B 随即进入写入步骤

B 等待，是因为它和 A 指向同一个解析后的绝对路径；C 指向另一个路径，因此可以和 A 同时前进。A 即使抛错，B 也会在它退出后取得执行权。

MutationQueue 保存的正是这组等待关系。解析后的绝对路径是 key，每个 key 对应一条 Promise gate；操作离开临界区时释放 gate，同 key 的下一项便能继续。

MutationQueue 的职责到这组 Promise 等待关系为止：它只协调当前进程中由课程工具 发起的修改。进程间互斥、多文件事务和断电持久性是另外三层问题；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 在当前 task.txt 中查找 status: draft。这个例子里只有这一处，所以它 产生新字符串 status: done，然后通过同一个 atomicWrite() 提交。

edit 也接受数组。下面两项按数组顺序作用于同一个内存副本：

[
  { oldText: "status: draft", newText: "status: ready" },
  { oldText: "status: ready", newText: "status: done" },
]

第二项可以匹配第一项刚生成的 status: ready。循环只改变局部变量 next：

let next = current;
for (const edit of edits) {
  // 找到第一处，并确认其后没有第二个非重叠匹配
  next = applyExactReplacement(next, edit);
}
await atomicWrite(file, next);

每一项的 oldText 都要非空。实现找到第一处后，会从这段文本的结束位置继续查找； 零次匹配表示当前文件已经和调用者的观察不同，第二个非重叠匹配表示定位不够具体。 任意一项失败时，代码还没有调用 atomicWrite()，磁盘上的 task.txt 保持原样。 空 newText 是合法值，它表示删除找到的那段文本。

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

#bash 从同一个 cwd 启动并结算进程

正常轨迹里的命令只读取 task.txt，然后输出 verified。spawn() 使用 cwd: workspace，所以命令中的相对路径仍指向前三个工具看到的目录。

进程退出以后，bash 工具把正文与状态分开保存：

content = "verified"
details = {
  exitCode: 0,
  timedOut: false,
  aborted: false,
  truncated: false,
  ...
}
isError = false

退出码非零时，已经产生的 stdout/stderr 仍留在 content，exitCode 保存具体数字， isError 变成 true。这样下一轮模型既能看到命令说了什么，也能区分正常退出与失败。

一个已经启动的进程会同时产生 stdout、stderr、close、timeout 和 abort 事件。 runCommand() 同时订阅两条输出流，并把收到的字节放进同一预算。stdout、stderr 与截断说明共用 maxBashOutputBytes。达到上限后，监听器仍继续消费后续数据，只是不再 保存；否则未被排空的管道可能让子进程停在那里。

发生截断时，结果先为 … [输出已截断] 留出空间，再从已捕获内容中取能放下的 UTF-8 前缀。正文连同提示不超过配置的字节数。两条输出流谁先到由实际进程调度决定，课程 没有为 stdout 与 stderr 重新规定稳定顺序。

#取消和超时结束同一个进程组

signal 在调用前已经 aborted 时，工具不执行 spawn()，而是直接返回 aborted: true 的结果。进程启动后收到 abort，或者 timer 到达 bashTimeoutMs，都会调用同一个 terminate()。

在 POSIX 系统上，子进程以独立进程组启动。terminate() 先向进程组发送 SIGTERM， 100 毫秒后再发送 SIGKILL，并等待强杀步骤结算。测试会启动一个忽略 SIGTERM 的后代进程； bash 工具返回后，这个后代不能再写出存活标记。Windows 没有使用这条负 pid 进程组路径，当前实现退回到直接进程信号。

timer 和 abort listener 最终在 finally 中移除。timeout、abort 与进程自行退出可能 靠得很近，forceKillDone 让重复终止请求共享同一个延迟任务。最终只返回一条 ToolResultMessage。

#workspace 模式对命令做有限的字符串检查

containment: "workspace" 还会检查 command 中显式出现的绝对路径、../ 和 ~/。 命中时，bash 在 spawn 之前返回工具错误。这个检查能挡住练习中最直接的越界写法， 但 shell 仍可以通过环境变量、程序参数或系统调用访问 cwd 之外；固定 cwd 也不会隔离 网络、当前用户权限和密钥。

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

#四个工具回到 Agent Loop

四个工具都来自 ToolRegistry，所以第 07 章不需要知道当前执行的是 echo 还是文件操作。 聚焦测试用 ScriptedModel 安排下面四轮：

assistant(read task.txt)  → toolResult(read)
assistant(edit task.txt)  → toolResult(edit)
assistant(bash verify)    → toolResult(bash)
assistant(final)          → stop

临时 workspace 起初包含 task.txt = "draft"。edit 把它改成 "done"，bash 在同一 cwd 读取并验证新值。最终有两类证据：文件确实等于 done；三条 tool result 的 id/name 分别与原 call 配对。

最终 role 顺序是：

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

这条测试使用固定本地命令，不访问模型 API。model.requests.length 是 4，说明每个工具 结果都在下一轮请求前写回了 transcript。

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

#这四个工具的边界停在哪里

本章的 12 项测试把四个工具固定在三个范围内。

• resolvedPath() 约束课程进程准备访问的路径。检查完成后，另一个进程仍可能改动 符号链接；操作系统沙箱是更外层的能力。
• MutationQueue 只排列经过同一队列、使用同一解析路径 key 的修改。rename 让目录项 一次切到完整新文件，但没有把多文件、多进程或断电恢复变成一笔持久化事务。
• bash 的输出、超时和进程组清理以本章的测试平台与 fixture 为准。Windows 进程树、命令 审批、网络和密钥隔离属于产品入口的另一层设计。

重叠 edit、超大文件流式读取和更多字符编码可以作为这四个接口之上的扩展；它们不会 改变本章已经建立的 call/result 配对与 workspace 边界。

#去掉第二个非重叠匹配检查

完成正常 edit 后，可以临时删掉“发现第二个非重叠匹配时报错”的分支。对内容 same same 执行 same → X，两种行为会分开：

正常：匹配 2 次 → isError=true  → 文件仍是 same same
改坏：匹配 2 次 → isError=false → 文件变成 X same

#本章验收

npm run build -w @pi/course
node --test packages/pi-course/dist/test/08-*.test.js

#可选迁移练习

#小结

同一个临时 workspace 让四个动作连成一条可观察轨迹。read 从 task.txt 返回完整行； write 用临时文件和 rename 提交整体内容；edit 在内存里排除第二个非重叠匹配，再提交一次； bash 从相同 cwd 启动，并把输出、退出码、超时和取消收进一个有界的终态。

workspace containment 让三个文件工具共用 root，也为 bash 加了一层有限 guardrail。 它保护练习输入，但没有替代操作系统隔离。第 09 章会让同一个 Agent 对象跨多次运行 保存消息，并处理新的用户输入时序。