Pi Coding Agent 如何做只读代码审查

Pi Coding Agent 做代码审查时，最重要的不是让模型修改更多文件，而是限制它只能读取、搜索并输出证据。本文从只读模式开始，说明工具白名单、工作区规则、审查结果和人工复核如何组成一个可回滚流程。文中只讨论可在本地复现的步骤，不把单次结果扩展成产品承诺；每个结论都标注前提、证据和无法覆盖的边界。读者可以先完成最小验证，再根据自己的版本、权限和数据补充实验，避免把配置示例误当成普遍结论。

重点不是让 Agent 获得越多权限越好，而是先把工作流拆成只读、修改和执行三个阶段，再按风险逐步放开工具。这样即使模型判断失误，也不会一开始就拥有整个工作区和生产凭证的写入权限。

1. Pi Coding Agent 适合什么任务

Pi Coding Agent 不是只会补全代码的编辑器插件。根据官方 CLI 文档，它可以在终端中运行交互模式、打印模式、JSON 事件模式和 RPC 模式，并通过内置工具、项目上下文、Skills 和 Extensions 组织任务。

一个代码审查任务可以拆成：

读取项目上下文
  -> 搜索相关文件
  -> 理解实现和测试
  -> 输出风险与证据
  -> 人工决定是否修改

模型本身并不直接拥有“审查权限”。权限来自 Pi 启用的工具、进程的操作系统权限、当前工作目录和外部沙箱配置。

PowerShell：

$env:API_KEY = "你的上游 API令牌"
$env:MODEL_ID = "你的上游 API编程模型精确ID"

Linux/macOS：

export API_KEY='你的上游 API令牌'
export MODEL_ID='你的上游 API编程模型精确ID'

先检查模型列表：

pi --list-models provider

3. 四种 CLI 模式怎么选

3.1 交互模式

直接运行：

pi --model provider/<精确模型ID>

适合人工观察每一步，临时补充约束，确认是否允许某个工具调用。

3.2 Print 模式

一次性任务可以使用 -p：

pi --model provider/<精确模型ID> \
  -p "审查当前项目的错误处理，只输出问题、证据和建议，不修改文件。"

适合脚本、CI 前置审查和批处理。它不等于“自动批准所有动作”，工具权限仍然应该用 --tools 控制。

3.3 JSON 模式

需要让上游程序消费事件时：

pi --mode json \
  --model provider/<精确模型ID> \
  -p "检查当前项目是否存在未处理的异常分支。"

JSON 模式适合保存结构化事件、生成审计记录或交给另一个工作流节点。生产系统要对输出做 schema 校验，不要把模型文本直接当成数据库命令。

3.4 RPC 模式

需要长期运行的外部控制器可以启动：

pi --mode rpc

RPC 使用 JSONL 进行进程间通信。调用方要严格处理每行 JSON，并自行管理超时、会话 ID、错误和退出状态。

4. 第一个任务只开放只读工具

Pi CLI 支持通过 --tools 设置允许的工具。代码审查先使用：

pi --tools read,grep,find,ls \
  --model provider/<精确模型ID> \
  -p """
请审查当前项目的错误处理。
要求：
1. 只读取文件，不修改文件，不执行命令。
2. 每个问题给出文件路径、行号和触发条件。
3. 区分确定性 Bug、潜在风险和改进建议。
4. 如果证据不足，明确写出需要补充的信息。
"""

PowerShell 多行字符串写法：

$prompt = @"
请审查当前项目的错误处理。
要求：
1. 只读取文件，不修改文件，不执行命令。
2. 每个问题给出文件路径、行号和触发条件。
3. 区分确定性 Bug、潜在风险和改进建议。
4. 如果证据不足，明确写出需要补充的信息。
"@

pi --tools read,grep,find,ls `
  --model "provider/$env:MODEL_ID" `
  -p $prompt

这里的 --tools 是硬边界之一。提示词可以进一步约束模型，但不能替代工具白名单。即使提示词写着“不要修改文件”，也不应该在只读审查阶段启用 edit。

5. 只读审查的验收格式

为了让结果可以复核，不要只要求模型“看看有没有问题”。可以要求固定输出：

## Findings

### [高/中/低] 标题
- 文件：path/to/file.ts:42
- 触发条件：
- 证据：
- 影响：
- 建议：
- 验证方式：

## Unknowns
- 当前证据无法确认的内容

## Suggested Tests
- 建议新增或运行的测试

人类审查时重点看三件事：

路径和行号是否真实存在。
结论能否从代码和测试复现。
建议是否超出当前任务范围。

如果模型输出了大量没有文件证据的“可能问题”，不要直接交给开发者修改。先要求它重新读取相关代码，或者缩小任务范围。

6. AGENTS.md 让规则进入项目上下文

Pi 会从用户目录、父目录和当前目录加载 AGENTS.md 或 CLAUDE.md 上下文文件。项目可以使用它声明审查规则，例如：

# Project Agent Rules

## Scope

- 先读取与任务直接相关的文件和测试。
- 只读审查阶段不得修改文件，不得运行部署命令。
- 所有结论必须带文件路径和证据。

## Security

- 不读取 `.env`、私钥、云凭证和生产配置。
- 日志和示例中不得输出 API Key。

## Review format

- 先列确定性问题，再列风险和建议。
- 没有证据时写明未知，不要补全事实。

上下文文件应该描述项目规则，不应该放真实凭证。它也不能替代操作系统层的权限隔离：如果进程本身能读整个磁盘，提示词规则不是安全边界。

7. Skills 和 Extensions 的分工

Pi 的 Skill 适合沉淀可复用的工作方法，Extension 适合注册工具、命令、事件处理和 UI。代码审查可以拆成：

Skill      -> 审查顺序、输出格式、验收标准
Extension  -> 注册项目专用工具、写入审计事件
上游 API      -> 模型 API、Key 分组、调用日志和预算

例如，一个项目级 Skill 可以要求 Agent 每次先做：

读取 package.json 或构建文件
读取目标模块
读取相关测试
搜索调用方
输出证据和未知项

Skill 不应该暗含“自动部署”“删除临时目录”之类高风险动作。需要高风险动作时，把它放在显式 Extension 工具里，并增加参数校验和人工确认。

8. 什么时候可以开放 edit

只读审查结束后，如果要让 Pi 修改代码，建议采用二阶段流程：

阶段一：read, grep, find, ls
  -> 输出审查结果
  -> 人工确认具体文件和修改范围

阶段二：read, grep, find, ls, edit
  -> 只允许修改确认过的文件
  -> 运行测试
  -> 查看 diff
  -> 人工确认提交

编辑权限需要配合四个检查：

检查	目的
文件白名单	防止修改配置、凭证和构建产物
diff 审查	确认模型没有扩大修改范围
测试命令	验证行为没有回归
回滚点	在结果不符合预期时恢复

如果 Pi 的内置配置不能满足文件级限制，就不要把 edit 当作足够的权限控制。可以使用临时 Git worktree、容器或微型虚拟机，把 Agent 的工作目录隔离出来。

9. 为什么不建议直接开放 bash

bash 不只是“运行测试”的按钮。它可能访问网络、读取环境变量、修改工作区、启动子进程或触发部署脚本。Pi 官方 README 也明确提醒：它默认继承启动进程的文件、进程、网络和凭证权限，不自带完整的沙箱系统。

如果确实需要执行命令，至少满足：

工作目录是临时测试项目
没有生产凭证
网络权限按需关闭
命令有白名单
超时和退出码可观察
输出经过脱敏
执行前有人确认

一个团队可以按风险和成本拆分令牌：

上游 API-PI-REVIEW
用途：只读代码审查和 Pull Request 摘要
工具：read, grep, find, ls

上游 API-PI-CODING
用途：测试项目代码修改
工具：read, grep, find, ls, edit

上游 API-PI-NIGHTLY
用途：夜间文档整理和低成本摘要
工具：只读工具

这样做有三个好处：

发生 429 或余额异常时，只影响一个工作流。
不同工作流可以使用不同能力和成本的模型。

Key 分组不等于本地权限。它解决的是模型 API 侧的额度和调用审计；本地工具白名单和沙箱解决的是文件、进程和网络边界。

11. 一次上线前验收

把下面的检查写成每个项目的上线门槛：

[ ] API_KEY 没有出现在仓库、日志和截图中
[ ] 模型 ID 来自当前 上游 API 模型广场
[ ] 只读阶段未启用 edit 或 bash
[ ] 每个结论都有文件和行号证据
[ ] 复杂任务设置了最大 Agent 轮数
[ ] 上游 API Key 已按项目或工作流拆分
[ ] 429、5xx 和超时有明确停止条件
[ ] 写操作在测试目录或外部沙箱执行
[ ] diff、测试结果和调用日志都能复核
[ ] 高风险动作保留人工确认

12. 本篇小结

Pi Coding Agent 的可靠用法不是“让模型自动改完整个仓库”，而是把工作拆成可检查的权限阶段：

只读理解 -> 人工确认 -> 有限修改 -> 测试与 diff -> 人工提交

资料来源

Pi Coding Agent README：https://github.com/earendil-works/pi/blob/main/packages/coding-agent/README.md
Pi Providers：https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/providers.md
Pi Security：https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/security.md

结论

本文给出了问题定位、配置或验证的可执行路径。实际结果仍取决于当前版本、权限和运行环境，提交前应按官方文档复核可变字段，并保留失败证据和回滚边界。