运行与调试

最后更新：2026-10-10

本章覆盖本地安装、构建检查、测试、运行时权限边界与供应链加固。Pi 对安全与可复现性非常较真：安装即加固、发布即隔离，这与它「代理能读写文件、执行命令」的特性直接相关——能力越强，越要把边界管住。

安装依赖（安全优先）

npm install --ignore-scripts   # 开发
npm ci --ignore-scripts         # CI

--ignore-scripts 会跳过依赖的生命周期脚本，避免执行不可信代码。本地安装、文档安装、pi update --self 都应尽量带此参数。环境要求 Node 18+；无 API key 时可用 MockModel 离线跑通循环。

npm run build   # 构建所有包
npm run check   # Biome lint + 格式化 + 类型检查

Pi 使用 Biome 做代码检查与格式化，用 Husky 管理 Git hooks。构建产物会覆盖四个核心包，构建通过后再启动编码代理更稳妥。

./test.sh        # 运行测试（无 API key 时跳过依赖 LLM 的用例）
./pi-test.sh     # 从源码运行 pi（可从任意目录执行）

启动后，编码代理会进入当前仓库，阅读代码、修改文件、执行命令并自我纠错。核心概念里的消息流与上下文压缩，都可以在这里实时观察。

排错提示：没有配置模型 API key 时，依赖真实模型的测试会自动跳过；若想跑通真实模型烟测，需先在环境中配置对应供应商的 key。

Pi 默认没有内置权限系统，会以启动用户的权限运行。要让代理写文件、跑命令而不危及本机，必须用容器化 / 沙箱加强边界。官方提供三种模式：

务必注意：在不受信环境直接以本机用户运行编码代理有风险。生产或共享环境请始终配合上述沙箱之一。

没有 API key 能跑 Pi 吗？

能。pi-ai 提供 MockModel，在完全没有密钥的情况下也能跑通从请求模型到工具调用再到回写结果的完整循环。无 key 时，依赖真实模型的测试会自动跳过，便于离线学习与 CI。

为什么安装要加 --ignore-scripts？

--ignore-scripts 会跳过依赖的生命周期脚本，避免执行不可信代码，是供应链加固的一环。本地安装、文档安装以及 pi update --self 都应尽量带此参数，CI 中用 npm ci --ignore-scripts。

沙箱应该怎么选（Gondolin / Docker / OpenShell）？

Pi 默认没有内置权限系统，会以启动用户权限运行，因此生产或共享环境必须配合沙箱。官方提供三种：Gondolin（推荐、边界更细）、Plain Docker（标准容器隔离）、OpenShell（面向开放 shell 场景）。按需选择即可。

Pi 默认有权限系统吗？

没有。Pi 默认以启动用户的权限运行，不会内置细粒度权限控制。要让代理写文件、跑命令而不危及本机，请用容器化或沙箱（Gondolin / Docker / OpenShell）加强边界。

供应链加固都做了什么？

以 package-lock.json 为真相源并配合 --ignore-scripts；用 Biome 做 lint/格式化/类型检查，Husky 管理 Git hooks；发布前在隔离环境做测试；新贡献者 Issue/PR 默认自动关闭待每日审查。