企业官网建设流程全解析

SoL-Pi兼容与部署完全参考：如何选对并验证Pi版本

【免费下载链接】SoL-PiSoL-Pi: Scaling Auto-Research Loops for Efficient Agent Harnesses项目地址: https://gitcode.com/gh_mirrors/so/SoL-Pi

SoL-Pi 是 Pi 编码代理的独立效率扩展，安装前选对 Pi 版本、并验证兼容性，是部署成功的關鍵。本文带你快速搞清 SoL-Pi 与 Pi 的版本兼容规则，掌握 3 条验证命令和完整部署流程，避免装完就报错。

一、先搞懂 SoL-Pi 与 Pi 的关系 🧩

SoL-Pi 本身不是一个独立的编码代理，它是以扩展形式安装在未修改的 Pi（pi-coding-agent）之上的一组效率机制，包含四大功能：

所有机制默认关闭、需显式开启，且 SoL-Pi 只使用 Pi 的公开扩展 API、不打补丁。正因为如此，你的 Pi 版本必须暴露这些 API——这就是"版本兼容"的核心含义。详见 docs/compatibility.md。

二、选对Pi版本：官方测试版本速查 ✅

新手最容易踩的坑就是随手装了最新版 Pi。请记住这张速查表：

• 推荐版本：@earendil-works/pi-coding-agent@0.85.1—— 官方完整测试通过的版本，19 个测试文件、140 个用例全数通过
• 兼容版本：0.84.2—— 原始支持版本，验证无需任何源码改动即可运行
• 运行时底线：Node.js 22.19 或更高
• ⚠️ 其他版本：官方明确"视为兼容性变更"，需自行重跑完整测试套件后再用

版本范围以 peer dependency（同辈依赖）形式声明，意味着 Pi 的包安装与升级仍由 Pi 自己负责，SoL-Pi 不替你锁定运行时版本。

三、三步验证 Pi 版本是否兼容 🔍

在部署 SoL-Pi 之前，按顺序跑完下面三步，就能确认当前 Pi 版本可用。

1. 检查 Pi 版本是否匹配

npm install --global @earendil-works/pi-coding-agent@0.85.1 pi --version

pi --version应准确报告0.85.1。如果你手上是 0.84.2 也没关系，它属于官方兼容范围；其他版本建议先升级到 0.85.1。

2. 运行公开 API 兼容检查脚本

node scripts/check-pi-compat.mjs

这个脚本（见 scripts/check-pi-compat.mjs）会检查当前 Pi 是否提供 SoL-Pi 所需的公开 API，包括工具定义函数、SessionManager会话目录方法、模型注册表等。任何一项缺失都会直接报错——这就是最直接的"版本能不能用"判定。

3. 跑完整测试与机制注册测试

npm ci --ignore-scripts npm run check npx vitest run tests/all-mechanisms.test.ts

npm run check覆盖 TypeScript 类型检查、完整测试套件和包检查。其中 tests/all-mechanisms.test.ts 专门验证：一份"全部开启"的配置能否通过 Pi 的公开扩展 API 成功注册全部四个机制。三步全绿，才说明 Pi 版本与 SoL-Pi 真正兼容。

四、部署 SoL-Pi 的完整流程 🚀

验证通过后，部署分四步走。

1. 安装 SoL-Pi

pi install git:github.com/NVlabs/SoL-Pi

若只给当前项目安装，加项目级作用域参数--local --approve。

2. 确认扩展已被识别

pi list --approve

输出中应能看到 SoL-Pi 的来源与所选作用域。注意：不要把同一份安装同时注册到两个作用域。

3. 编写一份生效配置

SoL-Pi 按以下顺序查找sol-pi.json：

1. 项目内.pi/sol-pi.json（项目被信任且文件存在时优先）
2. 用户级~/.pi/agent/sol-pi.json
3. 两者都没有则使用内置默认值（全部关闭）

项目级文件直接替换用户级文件，两者不合并。新手推荐这份保守起步配置，只开启不发额外模型调用、不打断运行的两个机制：

{ "version": 1, "actionFusion": true, "observationPack": true, "evidencePreservingReducer": false, "onlineContextCompact": false, "cacheWriteReadRatio": 12.5 }

完整字段说明见 docs/configuration.md，全量模板见 sol-pi.example.json。⚠️ 配置中出现未知键、版本号不是 1、JSON 格式错误，都会直接让扩展加载失败——这是刻意设计，帮你尽早暴露问题。

4. 离线启动冒烟测试

用--offline启动 Pi、不发任何提示词，确认没有扩展加载错误后退出，安装即告成功。

五、部署后验证与常见排查 🩺

用脚本核验配置

node scripts/check-sol-pi-config.mjs --config /path/to/sol-pi.json --require-all-enabled

见 scripts/check-sol-pi-config.mjs。它会套用 SoL-Pi 默认值、拒绝未知键和类型错误，并输出生效配置。不带--require-all-enabled时，省略的特性键保持关闭默认值。

常见问题速查

自动化环境（编码代理、CI）请直接遵循 agents-install.md 中的规范安装协议：它定义了"检查仓库 → 安装 Pi 与 SoL-Pi → 全开配置 → 四项验证"的可复现流程，任何一项缺失都不算安装成功。

写在最后 📌

选对版本、跑通验证、再谈部署——这三步顺序不能乱。记住核心要点：

• 认准0.85.1（推荐）与 0.84.2（兼容）两个 Pi 版本，Node.js ≥ 22.19
• 部署前跑check-pi-compat.mjs与all-mechanisms.test.ts双重验证
• 从保守配置起步，逐个开启机制，配置错误会让加载直接失败以便尽早发现

按这份参考操作，你的 SoL-Pi 部署就不会再被版本问题卡住。

【免费下载链接】SoL-PiSoL-Pi: Scaling Auto-Research Loops for Efficient Agent Harnesses项目地址: https://gitcode.com/gh_mirrors/so/SoL-Pi