SoL-Pi兼容与部署完全参考如何选对并验证Pi版本【免费下载链接】SoL-PiSoL-Pi: Scaling Auto-Research Loops for Efficient Agent Harnesses项目地址: https://gitcode.com/gh_mirrors/so/SoL-PiSoL-Pi 是 Pi 编码代理的独立效率扩展安装前选对 Pi 版本、并验证兼容性是部署成功的關鍵。本文带你快速搞清 SoL-Pi 与 Pi 的版本兼容规则掌握 3 条验证命令和完整部署流程避免装完就报错。一、先搞懂 SoL-Pi 与 Pi 的关系 SoL-Pi 本身不是一个独立的编码代理它是以扩展形式安装在未修改的 Pipi-coding-agent之上的一组效率机制包含四大功能机制作用Action Fusion编辑文件后在同一调用中自动执行后续验证命令ObservationPack大段重复工具结果转为可分页召回的稳定句柄Evidence-Preserving Reducer长诊断日志压缩为紧凑回执且保留证据Online Context Compact已完成的计划步骤触发原生上下文压缩所有机制默认关闭、需显式开启且 SoL-Pi 只使用 Pi 的公开扩展 API、不打补丁。正因为如此你的 Pi 版本必须暴露这些 API——这就是版本兼容的核心含义。详见 docs/compatibility.md。二、选对Pi版本官方测试版本速查 ✅新手最容易踩的坑就是随手装了最新版 Pi。请记住这张速查表推荐版本earendil-works/pi-coding-agent0.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-agent0.85.1 pi --versionpi --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.tsnpm run check覆盖 TypeScript 类型检查、完整测试套件和包检查。其中 tests/all-mechanisms.test.ts 专门验证一份全部开启的配置能否通过 Pi 的公开扩展 API 成功注册全部四个机制。三步全绿才说明 Pi 版本与 SoL-Pi 真正兼容。四、部署 SoL-Pi 的完整流程 验证通过后部署分四步走。1. 安装 SoL-Pipi install git:github.com/NVlabs/SoL-Pi若只给当前项目安装加项目级作用域参数--local --approve。2. 确认扩展已被识别pi list --approve输出中应能看到 SoL-Pi 的来源与所选作用域。注意不要把同一份安装同时注册到两个作用域。3. 编写一份生效配置SoL-Pi 按以下顺序查找sol-pi.json项目内.pi/sol-pi.json项目被信任且文件存在时优先用户级~/.pi/agent/sol-pi.json两者都没有则使用内置默认值全部关闭项目级文件直接替换用户级文件两者不合并。新手推荐这份保守起步配置只开启不发额外模型调用、不打断运行的两个机制{ 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时省略的特性键保持关闭默认值。常见问题速查症状排查方向扩展加载报错先用pi --version确认是否为 0.85.1 / 0.84.2项目级配置不生效项目未被信任时只读用户级文件两文件不合并某机制行为异常确认sol-pi.json中对应特性键为布尔值true需要复现完整安装按 agents-install.md 的四阶段协议逐步执行自动化环境编码代理、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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考