Pi Agent 原理

Appearance

6.3 内置工具 ​

@pi/coding-agent 基于 @pi/agent-core 的 AgentTool 契约，实现了让编码 Agent 真正"能干活"的内置工具。这一节介绍这些工具、如何创建，以及它们如何封装真实的文件系统/进程操作。

工具清单 ​

core/tools/ 提供这些工具：

工具作用文件
read读取文件内容read.ts
write写入文件write.ts
edit精确编辑（diff 定位 + 替换）edit.ts
bash执行 shell 命令bash.ts
grep内容搜索grep.ts
find文件名搜索find.ts
ls列目录ls.ts

read / bash / edit / write 是默认启用的四个主力工具（见 sdk.ts:245）。

创建工具：与 cwd 绑定 ​

工具不是全局单例，而是绑定到某个工作目录的实例。core/tools/index.ts 提供工厂：

ts
createReadTool(cwd, options)      // 只在 cwd 下工作
createBashTool(cwd, options)
createEditTool(cwd, options)
createCodingTools(cwd, options)   // 打包 read/bash/edit/write
createReadOnlyTools(cwd, options) // 打包 read/grep/find/ls

每个工具本质上是把"真实操作"（ReadOperations、BashOperations 等）封装成 AgentTool。这样同一个工具函数可以被测试替身替换，也方便在受限环境下注入不同实现。

read 工具：代表性格外重要 ​

read 是 Agent 了解代码的主要途径。为控制上下文占用，它内置截断机制（truncate.ts）：

ts
truncateHead / truncateTail / truncateLine
  • 文件太长时只返回头部/尾部，并用标记提示被截断。
  • DEFAULT_MAX_BYTES / DEFAULT_MAX_LINES 限制单次读取量。
  • Agent 可以针对性读取文件的某个区间。

edit 工具：精确而安全 ​

edit 用 diff 定位取代简单的字符串替换，避免误改：

ts
// edit-diff.ts
generateDiffString / generateUnifiedPatch

流程：找到目标上下文 → 生成精确补丁 → 校验 → 应用。配合 file-mutation-queue.ts（withFileMutationQueue）做文件变更的串行化，防止并发写同一文件。

bash 工具：进程封装 ​

bash 封装子进程执行（bash-executor.ts）：

  • 捕获 stdout/stderr、退出码。
  • 支持流式进度（通过 AgentToolUpdateCallback 上报部分输出）。
  • 超时与中断（AbortSignal）。
  • 返回结构化 details（退出码、耗时）供 UI 展示。

工具的"操作性"抽象 ​

每个工具都定义了一个操作接口，把"副作用"与"工具逻辑"分离：

ts
interface ReadOperations { readFile(path, options): Promise<...> }
interface BashOperations { execute(...): Promise<BashToolResult> }
interface EditOperations { ... }

createXxxTool 接收这些操作实现，默认用真实实现（走文件系统/进程），测试或沙箱可以注入替身。这是"工具可测试、可隔离"的关键。

如何在上层使用 ​

通过 SDK 装配：

ts
const { session } = await createAgentSession({
	cwd: process.cwd(),
	tools: ["read", "bash", "edit", "write"],   // 白名单
	// excludeTools: ["bash"]   // 或黑名单
});

AgentSession 会把这些工具挂到内部的 Agent.state.tools 上，模型就能调用它们（见 2.2 工具）。

小结 ​

  • 内置工具 = read/write/edit/bash/grep/find/ls，绑定 cwd 创建。
  • read 带截断保护上下文；edit 用 diff 精确改动；bash 封装进程。
  • 每类工具都有可注入的"操作接口"，便于测试与隔离。
  • 通过 SDK 的 tools / excludeTools 白黑名单装配。
真实源码位置
  • 工具工厂：packages/coding-agent/src/core/tools/index.ts
  • read 截断：core/tools/read.ts、truncate.ts
  • edit diff：core/tools/edit-diff.ts
  • bash 进程：core/tools/bash.ts、core/bash-executor.ts

下一步：6.4 扩展系统。