SoL-Pi 源码原理与技术学习文档

仓库入口 src/sol-pi/index.ts 在 session_start 时读取配置，然后按开关注册四类扩展。所有机制默认关闭；项目级配置只有在 Pi 判断项目可信时才会读取。

项目页公开的方法是一个规模化的 Harness 自动研究流程：从大量候选方向出发，每个方向形成独立 lineage，经过 rollout、证据分析、实现、审查以及两层验证。首轮提出 152 个方向，最终只有 4 个机制进入 SoL-Pi。

入口注册逻辑

session_start
  └─ loadSolPiConfig(ctx.cwd, getAgentDir(), ctx.isProjectTrusted())
      ├─ actionFusion            → registerActionFusion()
      ├─ observationPack         → registerObservationPack()
      ├─ evidencePreservingReducer → registerEvidencePreservingReducer()
      └─ onlineContextCompact    → registerOnlineContextCompact()

注意：入口通过 initialized 防止重复注册；Online Context Compact 在其它 context transformer 之后注册，以便它观察经过前序转换后的上下文。

Plan 数据契约

[
  { "id": "step-1", "goal": "定位问题", "status": "completed" },
  { "id": "step-2", "goal": "实现修复", "status": "in_progress" },
  { "id": "step-3", "goal": "验证",     "status": "pending" }
]

• step id 必须唯一；同一个 id 不应换 goal。
• 建议最多一个 in_progress。
• 有 pending 时，最好明确一个 in_progress。
• 状态写入 Pi session log 的 versioned custom entries，不另建 OCC sidecar 文件。

Action Fusion 的机会估计

项目页公开的研究轨迹显示：Oracle Analysis 在 cross-turn transition 中发现约 12.3% 是“edit/write 后紧跟 command”的候选；如果所有 149 个候选都触发，轨迹反事实估计 model turns 可从 1,386 降至 1,237（约 -10.8%），总 tokens 从 32.38M 降至 28.64M（约 -11.5%）。这是轨迹反事实，不是实际重跑结果。

Online Context Compact 的成本直觉

提前 compaction 本身也有成本，因为它会产生摘要写入并破坏一部分 KV-cache 复用。因此 SoL-Pi 不把“子任务完成”直接等同于“立刻压缩”，而是使用配置项 cacheWriteReadRatio（默认 12.5）作为单一经济决策比率，并结合未来 horizon 与 window pressure 判断未来读取节省是否能偿还本次重写成本。

环境要求

npm install --global @earendil-works/pi-coding-agent@0.85.1
pi install git:github.com/NVlabs/SoL-Pi

# 项目本地安装
pi install git:github.com/NVlabs/SoL-Pi --local --approve

推荐从低风险机制开始

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

官方 README 也把这组配置作为保守起点：前两者不额外调用模型，也不会停止一个正在运行的 Agent run。

配置查找顺序

1. 可信项目中的 .pi/sol-pi.json
2. ~/.pi/agent/sol-pi.json
3. 都没有时使用内置默认值（四机制关闭）

项目配置覆盖全局配置，不做 merge。未知 key、错误 version、非 boolean feature、非法 ratio 等都会直接阻止扩展加载，而不是悄悄忽略。

源码验证命令

npm ci --ignore-scripts
npm run check
npm audit --audit-level=high
node scripts/check-pi-compat.mjs

npm run check = TypeScript typecheck + 完整 Vitest + npm pack --dry-run。

A. 把 Runtime 优化拆成四层

如果移植到 Java Agent Runtime，可抽象成这些接口

interface ContextProjector {
    List<Message> project(Session session, List<Message> history);
}

interface ObservationArchive {
    ObservationHandle archive(byte[] content);
    byte[] recall(ObservationHandle id, int page);
}

interface ToolDecorator {
    Tool decorate(Tool original);
}

interface CompactionPolicy {
    CompactionDecision evaluate(PlanState plan, ContextUsage usage, Economics economics);
}

interface EvidenceVerifier<T> {
    VerificationResult verify(T candidate, ArchivedSource source);
}

这样可以把 SoL-Pi 的思想迁移到任何 Think → Action → Tool → Observation 循环，而不绑定 TypeScript 或 Pi。

Action Fusion 消掉无信息增益的模型轮次；ObservationPack 把“可访问”与“每轮重放”分离；Evidence-Preserving Reducer 把便宜模型的阅读能力放在确定性证据验证之后；Online Context Compact 则把 compaction 从纯粹的 token-window 事件升级为“语义边界 + 经济判断”。四者共同说明：Agent 系统的成本优化空间，很大一部分存在于 Harness 的数据生命周期与控制流，而不一定要重新训练模型。

主要资料

• NVlabs/SoL-Pi GitHub：README、src/sol-pi、docs/configuration.md、docs/compatibility.md、SECURITY.md
• 论文：SoL-Pi: Recursively Scaling Auto-Research Loops for Efficient Agent Harness，arXiv:2609.20519
• NVIDIA Research 项目页：SoL-Pi 方法、四机制研究过程与实验图表

本文将“源码可直接确认的实现”与“论文/项目页公开的实验数据”分开表述；实验结果不等同于对任意模型、任意任务和任意 Pi 版本的性能保证。