源码篇第8章 收银台排队——pi-coding-agent ​

小A把两个文件夹排上同一条传送带,老Z依次处理;旁侧的授权关口独立检查一个扩展组件。

本章导读: 源码路线第 ⑦ 站(产品层)。仍在 pi-coding-agent,但聚焦 core/ 下的三个子系统,读 tools/file-mutation-queue.ts、extensions/runner.ts 和 project-trust.ts。这一站要划清三条容易混的线:同一文件的写入怎么排队、扩展加载成功不等于可信、项目授权到底拦的是什么。

启动链把会话和资源装配起来了,但小A心里还有两个疙瘩。第一个:他让 Agent 连续两次读同一个文件然后改它,忽然想到,两个写请求几乎同时到达同一个文件,会不会互相覆盖?第二个:他在项目里放了一个扩展目录,扩展确实加载成功了,但“加载成功”就等于“可以信任”吗?

“两个问题的答案都在代码里。”老Z说,“一个看文件写入怎么排队,一个看扩展和项目授权怎么接入。先说清楚:这些机制不构成完整沙箱。”

本章源码证据均来自上游 pi 标签 v1.0.0(提交 a13d35a742c6ef8462812a28fbe1d8c8b7431c32,包版本 1.0.0,2026-10-01)。本章跟读工具输出截断、同一文件写入排队、扩展的发现加载绑定,以及项目信任的判定顺序;不覆盖每个内置工具的参数 schema、扩展包管理、具体沙箱实现和第三方扩展审计。

内置工具通过会话进入循环 ​

小A先把工具的事摆上桌:“那内置工具从哪来?全都塞给模型吗?”

“先看工具输出怎么控制体积。”老Z打开 packages/coding-agent/src/core/tools/truncate.ts:

ts
export const DEFAULT_MAX_LINES = 2000;
export const DEFAULT_MAX_BYTES = 50 * 1024;
export function truncateHead(content: string, options = {}): TruncationResult {
  // 返回 content、truncated、totalLines、totalBytes 等元数据
}

“这两个默认值写死,是这个快照里的源码事实,但函数接受 options,不能把它外推成所有调用的绝对限制。关键是结果包含截断元数据,让上层区分‘命令只有这些输出’和‘显示只保留这些输出’。”

“两条线是怎么算的?”

“两条独立线,谁先到谁先截。”老Z说,“splitLinesForCounting 数行,Buffer.byteLength(content, 'utf-8') 数字节。maxLines 或 maxBytes 任一超限就切,truncatedBy 字段记下是 'lines' 还是 'bytes'。文件读用 truncateHead 留头部,命令输出用 truncateTail 留尾部:日志末尾通常是结论,文件开头通常是声明,两边‘最有信息量’的方向不一样。”

“truncateHead 和 truncateTail 的边界行为也不一样?”

“对,这正是它们不可互换的原因。”老Z说,“truncateHead 承诺不返回半行:第一行本身就超过字节上限时,它直接返回空内容并置 firstLineExceedsLimit: true。truncateTail 允许例外,它从文件末尾往回攒,最后一行太大时,会从行尾截出 maxBytes 那段并把 lastLinePartial 置位,因为 bash 输出的最后一行往往是最重要的错误消息。连‘截断从哪头算’都影响元数据语义。”

再看 OutputAccumulator.snapshot():

ts
snapshot(options = {}): OutputSnapshot {
  const truncation = truncateTail(this.getSnapshotText(), ...);
  if (options.persistIfTruncated && truncation.truncated) this.ensureTempFile();
  return { content: truncation.content, truncation, fullOutputPath: this.tempFilePath };
}

“它把滚动中的原始字节、可显示尾部和可能的完整输出路径分开。v1.0.0 还加了 readFullOutput(maxBytes),给能接收更多内容的调用方读完整输出:超过上限时保留头尾各一半,中间换成省略标记,并按字符边界切。正常路径返回可放入上下文的快照;超限时仍保留截断事实。临时文件创建或写入失败属于执行层必须处理的失败,不是模型可以忽略的文本。”

“为什么 OutputAccumulator 要单独维护 totalLines 和 totalDecodedBytes,而不是直接读 snapshot 的结果?”

“因为 snapshot 的 truncation 是对已组装文本算的,OutputAccumulator 累积的却是流式字节,append 时一边解码一边累加 totalDecodedBytes,遇到不完整的 UTF-8 边界会暂存到下一个 chunk。”老Z说,“所以 truncated 的判定用 this.totalLines > maxLines || this.totalDecodedBytes > maxBytes,跟 tailTruncation.truncated 可能不一致:前者是‘原始流超了’,后者是‘组装后文本超了’。这种分离让中间的坏字节不至于撑爆上下文。”

“那它怎么控制内存?”

“maxRollingBytes = maxBytes * 2,append 后如果 tailBytes 超过 maxRollingBytes * 2 就 trimTail(),只留尾部一块,并从 UTF-8 边界处切,尽量对齐行边界。”老Z说,“shouldUseTempFile() 只要任一线超了就开始写临时文件,ensureTempFile() 把此前攒的 rawChunks 一次性回填进文件流。所以内存占用有上限,完整输出不丢,前提是临时文件能写得成,那属于执行层的失败。”

core/tools/index.ts 汇集内置工具;read.ts、write.ts、edit.ts、bash.ts、powershell.ts、grep.ts、find.ts 与 ls.ts 分别实现具体能力,由 AgentSession 的工具配置和会话运行时接入模型循环。allToolNames 定义这八个工具名,powershell 是 v1.0.0 新增的,createToolDefinition/createCodingToolDefinitions 按工具名把 schema 和执行器组装出来。

要点:收益与代价

收益是上下文不会被单个命令输出轻易占满;代价是模型看到的是删节结果,可能遗漏位于中间的关键信息。截断信息及完整输出位置必须作为结果的一部分,不能伪装成完整日志。

同一文件的写入被显式排队 ​

小A:“回到我的第一个疙瘩。”

“看 withFileMutationQueue()。”老Z打开 packages/coding-agent/src/core/tools/file-mutation-queue.ts:

ts
const currentQueue = fileMutationQueues.get(key) ?? Promise.resolve();
const chainedQueue = currentQueue.then(() => nextQueue);
fileMutationQueues.set(key, chainedQueue);
await currentQueue;
try { return await fn(); }
finally { releaseNext(); /* 清理同一 queue */ }

“逐段解释:先登记 key 对应的前序 Promise,再安装后继 Promise,之后才等待前序,最后无论 fn 成功或抛错都释放后继。这个 finally 是队列不会因失败永久堵塞的关键。正常路径是同 key 的 mutation 按提交顺序执行;边界一是 key 归一化失败;边界二是 fn 抛错,后续 mutation 仍必须获得释放。”

“这个伪码省略了什么?”

“省略了 registrationQueue。”老Z说,“实际代码不直接读写 fileMutationQueues。登记阶段把“算 key、读旧值、写新值”套进 registrationQueue.then(...) 串行执行,用来安装该 key 的队列链;真正读写文件内容的 mutation 本体,之后由这条 Promise 链串行执行。原因是 getMutationQueueKey 是 async 的(要 realpath),两个调用并发进入时可能在 Map 上 race:A 读到空,B 也读到空,两个都装自己的后继,互相看不见,后装的把先装的覆盖掉。registrationQueue 把这段登记串成原子操作,同 key 的链才不会断。”

把队列时序画出来,registrationQueue 的作用更直观:

text
两次几乎同时的 withFileMutationQueue("/x.txt", fn)(理想化时序):
  mutation A 进入                mutation B 进入
  registrationQueue.then(...)     registrationQueue.then(...)   ← 串行登记
   |   keyA = realpath → /real    |(等 A 的登记完成)
   |   查 Map → 空               |   keyB = realpath → /real
   |   建 current=A0             |   查 Map → 已是 A 的链
   |   Map[key] = A0 → nextA     |   Map[key] = nextA → nextB
   |   完成登记                   |   完成登记
   |   await current(A0)          |   await current(nextA)
   |   fn()                       |   fn()                      ← 严格串行
   |   finally: releaseNext()     |   finally: releaseNext()

“释放端也有讲究。”老Z接着说,“finally 里 release 后继之后,只有 fileMutationQueues.get(key) === chainedQueue 才删 key,链仍是当前链时才清理,否则会把别人刚装的链删掉。”

小A:“key 归一化怎么做?我猜是直接拿传进来的路径当 key?”

“先 resolve(filePath),再 realpath。”老Z说,“realpath 会解开符号链接,所以软链指向同一文件的两次写落到同一个 key、被串行。已存在路径会先经 realpath 归一;但文件不存在时 realpath 抛 ENOENT/ENOTDIR,isMissingPathError 捕获后回退用 resolvedPath,创建前的软链等价性会丢失。外部进程写入也不受这条队列管理。代价在这:写一个还没创建的文件,符号链接等价性就丢了,/tmp/new.txt 和软链 /link/new.txt 在创建前是两个不同的 key,可能并发执行。”

“所以不同文件不共享队列?”

“对。withFileMutationQueue(filePath, fn) 先将路径解析为队列 key,再等待该 key 的当前 Promise。不同 key 各走各的队列,互不共享。”

比喻:收银台排队

同一文件像同一队收银台,同 key 依次结账;不同的队之间没有承诺。

小A:“那我把所有写文件的操作都套上这个队列,写入就安全了?”

“安全谈不上。”老Z说,“它为同一规范化文件目标的 mutation 提供串行化,这是一条可核对的边界;不同路径指向同一资源、外部进程修改、业务语义冲突、跨文件原子性,都还在它外面。别把‘按文件排队’听成‘所有写入都安全’。”

本章其余小节为付费内容

登录后可购买;已购 Pi Cookbook Pro?登录即解锁完整章节。