我的本机 Pi：配置与插件工作流实录

在《Pi 的完善之路：Package 生态折腾指南》里，重点是 Pi 的 Package 生态和各种扩展方向。本文换一个角度，只记录这台机器当前实际使用的 Pi：它怎么安装、配置文件放在哪里、哪些包真正写进了全局配置，以及这些东西在日常工作中如何配合。

这不是一份“推荐安装全部插件”的教程，而是一份会随版本变化的本机快照。本文记录时间为 2026-09-15；版本、包和配置以本机的 pi --version、pi list 以及 ~/.pi/agent/ 实际内容为准。

本文只展示非敏感配置。认证信息、模型密钥、完整会话和私有模型目录不放进文章。

Pi 是什么

Pi 是一个极简的终端 Coding Agent。它的核心故意保持很小，默认只给模型四个主要工具：

• read：读取文件
• write：创建或覆盖文件
• edit：修改文件
• bash：执行 shell 命令

MCP、子代理、计划模式、待办、权限询问和后台 Bash 等能力，并不是 Pi 核心的一部分，而是通过 Extension、Skill、Prompt Template、Theme 或 Package 按需补上。这样做的好处是上下文和界面不会被一堆自己用不到的功能占满，代价是第一次使用需要自己搭工作流。

我比较喜欢 Pi 的地方也在这里：它不是一个功能固定的成品，而是一个可以按个人习惯拼装的 Agent 基座。当前本机的组合大致分成四层：

1. Pi 本体：负责模型对话、文件修改、命令执行和会话保存。
2. Package：通过 npm 或 Git 安装的可复用扩展、主题和技能。
3. 本地 Extension：直接放在 ~/.pi/agent/extensions/ 下，服务于本机的定制需求。
4. 项目上下文：项目中的 AGENTS.md、信任设置和项目级 .pi/ 配置。

本机环境

当前实际环境如下：

验证当前版本只需要：

node --version
pi --version

因为 Pi 是挂在 fnm 当前 Node 版本下的全局安装，切换 Node 版本后如果出现 pi: command not found，先检查当前版本对应的全局包目录。按官方方式重新安装：

npm install -g --ignore-scripts @earendil-works/pi-coding-agent

--ignore-scripts 是 Pi 官方文档给出的普通 npm 安装方式。安装后可以用下面的命令确认 Package 状态：

pi list

配置目录：实际使用软链接管理

本机不是把配置散落在默认目录里，而是让 ~/.pi 指向 dotfiles 仓库：

~/.pi -> ~/dotfiles/pi/.pi

因此 Pi 看到的目录仍然是标准的 ~/.pi/agent/，配置本身则可以和其他 dotfiles 一起管理。当前目录中比较重要的内容是：

~/.pi/agent/
├── AGENTS.md                         # 全局上下文和工作规则
├── settings.json                     # 全局设置和 Package 列表
├── settings-extensions.json          # 部分扩展的设置
├── extensions/                       # 本机直接加载的扩展
├── npm/                              # Pi Package 的 npm 安装目录
├── git/                              # Pi Package 的 Git 安装目录
├── sessions/                         # 按工作目录保存的 JSONL 会话
├── state/                            # 运行时状态
├── subagent-runs/                    # 子代理运行记录
├── pi-vcc-config.json                # pi-vcc 配置
├── sol-pi.json                       # SoL-Pi 配置
└── native-responses-web-search.json  # 本地搜索扩展配置

需要特别注意：settings.json、会话文件和模型目录不是一回事。要备份工作流可以同步 Package 配置和扩展源码，但不要把认证文件、API Key 或完整会话无差别公开。

当前 settings.json

本机全局设置的关键部分如下，省略了与本文无关的内容：

{
  "compaction": {
    "enabled": true
  },
  "defaultModel": "gpt-5.6-luna",
  "defaultProvider": "cpa",
  "defaultThinkingLevel": "max",
  "hideThinkingBlock": true,
  "theme": "alien-candy",
  "transport": "websocket-cached",
  "tuiMode": "regular",
  "footer": {
    "preset": "custom",
    "segments": [
      "model",
      "context_pct",
      "session",
      "token_total",
      "time_spent",
      "extension_statuses"
    ]
  }
}

这套配置的取向比较明确：

• 默认使用 cpa/gpt-5.6-luna，思考级别为 max。
• 隐藏思考块，把终端空间留给真正的回答、工具调用和 diff。
• 使用 websocket-cached transport，配合缓存相关扩展。
• 开启 Pi 的上下文压缩入口，但具体的长会话压缩还会经过 pi-vcc 的处理。
• 使用 alien-candy 主题和自定义 footer，底部显示模型、上下文占用、会话、Token、耗时与扩展状态。

已安装的 Package

当前 settings.json 里有 10 个全局 Package。pi list 展示的是这些通过 Pi Package 机制登记的来源；extensions/ 下的本地扩展不会出现在这个列表里。

Package 的安装、查看和更新入口都是 Pi 自己的命令：

pi install npm:@narumitw/pi-btw
pi install git:https://github.com/NVlabs/SoL-Pi.git
pi list
pi config
pi update --extensions

权限系统：先把边界立起来

@gotgenes/pi-permission-system 是这套配置里最重要的基础设施之一。它不是完整的操作系统沙箱，而是给 Pi 的工具调用增加一层规则判断。

当前配置的几个取向是：

• 常规操作默认允许，减少日常工作中的重复确认。
• 对 grep、find 等不希望使用的工具设置拒绝规则。
• 对敏感路径、认证文件和环境配置设置拒绝规则。
• 对 rm、移动文件、git restore 等可能造成损失的操作要求询问。
• 对强制 push、危险的合并参数等操作直接拒绝或限制。

这套规则解决的是“Agent 不要顺手做错事”，不是“Agent 被完全隔离”。Pi 官方文档也明确说明：Pi 没有内置沙箱，Extension 与 Package 仍然以当前用户权限运行。处理不可信仓库或无人值守任务时，应该使用容器、虚拟机或其他操作系统级隔离。

上下文和输出：分层处理，而不是只装一个压缩器

本机同时用了几种上下文相关工具，但它们处理的层次不同。

pi-rtk-optimizer：先压缩工具输出

本机可以找到 /usr/bin/rtk，pi-rtk-optimizer 当前配置为重写模式，并开启工具输出压缩。主要策略包括：

• 把可重写的 Bash 命令交给 rtk。
• 去掉 ANSI 控制字符。
• 聚合测试、构建、Git、Lint 和搜索输出。
• 对过长结果做约 12000 字符的硬截断。
• 暂时关闭 read 结果压缩，避免普通文件阅读被过度裁剪。

它解决的是“工具每次吐太多内容”的问题，发生在结果进入上下文之前。

pi-vcc：用确定性摘要保留历史可检索性

pi-vcc 的特点是不额外调用 LLM，而是通过提取和格式化生成结构化摘要。当前配置为：

{
  "overrideDefaultCompaction": true,
  "smartKeepTail": true,
  "continueAfterThresholdCompact": true,
  "debug": false
}

常用命令：

/pi-vcc
/pi-vcc keep:3
/pi-vcc-recall 关键词

压缩后会保留会话目标、文件变化、提交、未完成事项和用户偏好等结构化信息；旧会话仍可以通过 vcc_recall 从原始 JSONL 中检索。相比完全交给模型自由总结，这种方式更确定，也不会为了压缩本身再消耗一次模型调用。

SoL-Pi：把动作、观察和诊断日志拆开处理

SoL-Pi 是通过 Git Package 安装的独立扩展，不修改 Pi 本体。当前 sol-pi.json 为：

{
  "version": 1,
  "actionFusion": true,
  "observationPack": true,
  "evidencePreservingReducer": true,
  "evidencePreservingReducerProvider": "cpa",
  "evidencePreservingReducerModel": "gpt-5.6-luna",
  "onlineContextCompact": false,
  "cacheWriteReadRatio": 40
}

实际启用的功能包括：

• Action Fusion：edit 或 write 可以在同一次工具调用中执行后续验证命令。
• ObservationPack：重复出现的大段工具结果变成可分页召回的本地观察记录。
• Evidence-Preserving Reducer：对较长的诊断日志做带原文证据的压缩；当前会使用 cpa/gpt-5.6-luna 这条 Pi 模型路线。
• Online Context Compact：当前关闭，避免和 pi-vcc 的会话压缩、自动继续机制叠加。

SoL-Pi 的证据保留机制会在本地保存原始观察；如果压缩失败，原始工具结果不会被静默替换。需要注意的是，启用诊断日志 Reducer 意味着符合条件的日志可能会发送给配置的模型，涉及敏感内容时应关闭它或改用合适的本地模型。

pi-cache-optimizer：优化请求的缓存形状

pi-cache-optimizer 处理的是 Provider 端 Prompt/KV Cache，而不是会话摘要。它会检查模型和 Provider 的兼容项，并提供：

/cache-optimizer doctor
/cache-optimizer compat
/cache-optimizer fix
/cache-optimizer rollback

其中 doctor 和 compat 主要用于诊断；fix 涉及修改 models.json，执行前应该先确认预览、备份和目标模型，不要把它当成无条件的“一键修复”。

本地 Extension：三个真正有入口的目录

本机的 ~/.pi/agent/extensions/ 里有一些配置目录和历史目录，但按“存在可加载入口文件”的口径，当前有三个本地 Extension：

本地 Web Search

native-responses-web-search 当前配置为启用状态，只允许一个匹配当前模型的 channel：

{
  "enabled": true,
  "transport": "auto",
  "channels": [
    {
      "provider": "cpa",
      "endpoint": "standard",
      "modelPrefix": "gpt-5.6-luna",
      "enabled": true
    }
  ]
}

它不是把第三方搜索服务的全部工具定义塞进主上下文，而是注册一个本地 web_search 工具；模型需要搜索时，扩展再用当前 Provider 发起一个独立的 Responses 请求。这样主 Agent 只看到一个简单工具，搜索结果也不会自动把父会话和父工具列表一起复制给嵌套请求。

Plan Mode 和锁定子代理

本机的 pi-plan-mode 是官方 Plan Mode 示例的本地改版，保留只读探索和状态恢复，但把执行跟踪交给普通 Agent。使用：

/plan
/plan status
/plan off

或者启动时直接：

pi --plan

进入计划模式后，edit 和 write 会被禁用，退出时恢复进入计划模式前的工具集合。对于先阅读代码、再确认方案的任务，这比让 Agent 一上来就修改文件更稳。

pi-locked-subagents 则不是一个开放的“随便创建任意子代理”功能。它从 locked-subagents.json 读取本机预先配置的角色、模型、工具和隔离选项，并限制子代理的最大嵌套深度（默认值为 2）。/subagents 可以查看当前配置，实际派发通过 subagent 工具完成。

日常使用流程

我现在比较常用的流程是：

1. 先规划，再执行

/plan

让 Pi 先读取项目结构、上下文文件和相关实现，输出方案。确认方向后再交回普通 Agent，避免“边猜边改”。

2. 执行时让权限系统守住边界

普通模式下，Pi 可以使用 read、edit、write 和 bash。权限扩展会检查路径和命令；SoL-Pi 则可以把修改后的验证命令合并到动作中，减少一轮无意义的来回。

3. 大输出先在工具层收敛

测试、构建、Git 和搜索结果优先交给 rtk/pi-rtk-optimizer 做压缩；需要查看完整原文时，再使用 ObservationPack 或重新读取源文件，而不是让每次命令都把整段日志塞进上下文。

4. 长会话使用 VCC，必要时主动召回

上下文接近上限时让 pi-vcc 处理压缩，之后用 /pi-vcc-recall 搜索旧决策、文件名或错误信息。这样压缩不是一次性丢弃历史，而是把常用信息保留在摘要，把原文留在本地会话中。

5. 主任务之外的问题用 /btw

/btw 这个 API 的错误码是什么意思？

pi-btw 会创建侧线问题线程。回答默认不会写入主对话，只有明确带回的内容才会进入主编辑器，适合查一个小问题而不打断正在进行的重构。

6. 大段文本用 /paste

/paste

先执行 /paste，再粘贴模板、日志或长 Prompt，可以让内容以完整可编辑的原文进入编辑器，而不是被终端的普通粘贴逻辑压缩成标记。

7. 用 footer 和主题观察会话状态

当前 footer 会显示模型、上下文占用、会话 ID、Token 总量、耗时和扩展状态。主题只影响显示，不改变 Agent 行为；需要切换时可以使用 /settings 或 pi-footer 提供的 /footer 命令。

它们之间如何分工

把当前配置画成一条链，大致是：

用户请求
   ↓
Plan Mode（可选，只读规划）
   ↓
Pi 核心 Agent
   ├── Permission System：检查工具、路径和危险命令
   ├── SoL-Pi Action Fusion：修改后顺手执行验证
   ├── RTK Optimizer：收敛工具输出
   ├── ObservationPack：保存可召回的长观察
   ├── VCC：压缩会话并保留历史索引
   └── Footer / Theme：显示当前状态

pi-btw、/paste 和本地 Web Search 属于交互侧能力；pi-locked-subagents 属于任务分派能力；pi-cache-optimizer 作用在 Provider 请求和缓存形状上。它们不应该被笼统地称为“上下文压缩插件”，否则很容易重复安装、重复截断，最后反而让模型看不到关键证据。

统计口径和没有计入的目录

这次清单有意区分了三类东西：

1. Package：settings.json 的 packages 数组中登记的 10 项，可由 pi list 列出。
2. 本地 Extension：extensions/ 下存在 index.ts 或等效入口、会被 Pi 自动发现的目录。
3. 辅助文件或依赖：例如空的 pi-guard/ 目录、只保存配置的目录，以及 Agent 根目录 package.json 里的 pi-agent-browser-native / agent-browser 依赖。

第三类不等于默认加载的 Pi Package，所以没有把它们直接算进“当前启用扩展”。如果要确认某个目录是否真的参与启动，最简单的办法是看 Pi 启动头部、运行 /reload 后的扩展状态，或者检查它是否被写入全局/项目 Package 配置。

安全和维护建议

• 第三方 Package 会以当前用户权限执行代码，安装前至少看一眼源码和依赖。
• Project Trust 只控制是否加载项目本地配置和扩展，不是沙箱。
• 不要提交认证文件、模型密钥、私有会话和包含密钥的日志。
• 启用 SoL-Pi 的远程诊断日志压缩前，先确认日志中没有 Cookie、Token 或用户数据。
• 只想临时试用时可以使用 pi --no-session，避免留下会话记录。
• 新装扩展后先做一个小任务，确认工具名、权限规则、TUI 和上下文压缩没有互相覆盖。
• pi --version、pi list 和 pi config 是最小的本机自查组合；不要只根据几个月前的文章复制旧包清单。

写在最后

这套本机 Pi 配置并不是插件越多越好，而是把功能放到对应的层：安全交给权限规则，规划交给 Plan Mode，输出交给 RTK，长会话交给 VCC，观察证据交给 SoL-Pi，零碎交互交给 /btw 和 /paste。

Pi 的魅力仍然是它的“毛坯房”属性。真正稳定的工作流不在于安装一张很长的插件清单，而在于知道每个扩展修改了哪一层，并且在出现上下文缺失、工具冲突或权限异常时，能关闭其中一层而不是继续叠加功能。

参考

• Pi 的完善之路：Package 生态折腾指南
• Pi 官网（pi.dev）
• Pi 官方文档
• SoL-Pi
• Pi Packages 文档