narumiruna/pi-extensions · 上手攻略

  • 仓库：narumiruna/pi-extensions
  • 链接：https://github.com/narumiruna/pi-extensions
  • 分类：ai
  • 作者：Tom
  • 更新：2026-08-22

这是什么

pi-extensions 是一个 TypeScript monorepo，为 Pi Coding Agent（一款 AI 编程助手，支持 Claude Code、Codex CLI、ChatGPT 等）提供可独立安装的扩展包生态。覆盖编程自动化、规划协作、浏览器控制、Web 研究、Git 工作流、跨供应商 API 编排、终端体验和可观测性等场景。每个包独立发布在 @narumitw npm 作用域下，按需安装，不污染基础环境。

解决什么问题

Pi Coding Agent 本身功能有限，社区通过扩展机制增强其实用性。痛点包括：

  • 长任务可靠性：Agent 处理复杂多步任务时容易跑偏，需要 /goal 目标追踪和 /plan 规划审查机制。
  • 多供应商 API 编排：Claude Code、OpenAI Codex、Copilot 等各自需要独立配置，缺乏统一账户管理。
  • 浏览器自动化盲区：Pi 原生不包含 Chrome DevTools 控制能力，需要独立扩展。
  • 上下文断裂：文件修改历史、工作树切换时上下文丢失，pi-file-context 和 pi-worktree 解决此问题。
  • 可观测性缺失：无法查看 Token 消耗、成本、工具调用频率，pi-analytics 和 pi-stamp 提供本地指标。

快速安装

Pi Coding Agent 需要先安装（参考 pi.dev）。扩展安装有两种模式：

# 永久安装（重启后保留）
pi install npm:@narumitw/pi-goal

# 临时试用（当前会话有效，不写入配置）
pi -e npm:@narumitw/pi-statusline

多个扩展可以组合：

pi -e npm:@narumitw/pi-goal \
 -e npm:@narumitw/pi-statusline \
 -e npm:@narumitw/pi-lsp

⚠️ 注意：扩展运行在完整用户权限下，安装前务必审查源码，只安装信任的第三方扩展。

核心用法

规划与目标追踪

pi-goal — 让 Agent 持续工作直到目标验证完成：

pi install npm:@narumitw/pi-goal
# 触发 /goal 命令，Agent 会自动追踪子目标直到完成

pi-plan-mode — 实现类似 Codex 的只读 /plan 协作，在实现前让人类审查方案：

pi install npm:@narumitw/pi-plan-mode
# 输入长任务后 Agent 输出 /plan，等待人类确认再执行

pi-workflow — 整合 /plan + /goal 于一身，带可恢复的交接机制。注意：与 pi-plan-mode 或 pi-goal 互斥，不能同时安装。

pi install npm:@narumitw/pi-workflow

编程与语言工具

pi-lsp — 跨多语言的语言服务器诊断和代码修复，支持 JavaScript/TypeScript/Python/Rust/Go/Ruby/C/C++/JVM/.NET/Swift/shell 等：

pi install npm:@narumitw/pi-lsp

pi-codex-compact — 使用 OpenAI Codex Remote Compaction V2 持久化和回放有界不透明检查点，手动控制 /codex-compact，带 Pi 原生安全降级：

pi install npm:@narumitw/pi-codex-compact

子代理与委托

pi-subagents — 将隔离的工作委托给独立 Agent，支持单执行、并行执行、链式执行三种模式：

pi install npm:@narumitw/pi-subagents

浏览器控制

pi-chrome-devtools — 通过 Chrome DevTools Protocol 检查标签页、导航页面、执行 JavaScript、截图：

pi install npm:@narumitw/pi-chrome-devtools

pi-firecrawl — 用 Firecrawl 抓取页面、爬取网站、发现 URL、搜索网络：

pi install npm:@narumitw/pi-firecrawl

Git 工作流

pi-worktree — 创建、切换、删除和修剪 Git worktree，同时将 Pi 会话带入另一个工作区：

pi install npm:@narumitw/pi-worktree

pi-github-pr — 通过已认证的 gh CLI 显示当前分支的 PR 检查、Review 和评论数：

pi install npm:@narumitw/pi-github-pr

可观测性与状态

pi-stamp — 在 TUI 转录中显示可配置时间戳，含可选助手元数据、响应耗时和工具耗时：

pi install npm:@narumitw/pi-stamp

pi-statusline — 在页脚显示模型、工具、Git 状态、上下文用量、Token 数、成本和时间：

pi install npm:@narumitw/pi-statusline

⚠️ 注意：pi-starship（原生 Starship 风格页脚）和 pi-statusline 二选一，不能同时启用。

pi-analytics — 通过 /analytics 查看本地私密指标：模型调用次数、技能使用、工具活动、响应周期、观察到的供应商可靠性：

pi install npm:@narumitw/pi-analytics

跨供应商账户管理

pi-accounts — 用 /account 切换命名的 OpenAI Codex、Anthropic Claude 和 GitHub Copilot 订阅 OAuth 账户：

pi install npm:@narumitw/pi-accounts

pi-usage — 用 /usage 查看当前账户的 Codex 订阅限额或 OpenRouter API Key 消费限额：

pi install npm:@narumitw/pi-usage

pi-sync — 通过 Cloudflare R2 或 S3 兼容存储同步白名单化的 Pi 设置和可选会话：

pi install npm:@narumitw/pi-sync

终端体验增强

pi-tui-kit — 扩展 @earendil-works/pi-tui，提供可复用导航助手和声明式操作/详情/设置/多选流程。扩展作者而非最终用户使用的新标准菜单库：

npm install @narumitw/pi-tui-kit

实验性扩展

pi-chat — 加入临时点对点聊天室，与 Pi 会话、提示和模型上下文完全隔离：

pi install npm:@narumitw/pi-chat

pi-file-context — 浏览项目文件、预览文本、选择精确行或 Git diff 块，并将带 Git 溯源的不可变快照附加到下一条提示（F8 或 /file-context 打开）：

pi install npm:@narumitw/pi-file-context

pi-fleet — 在独立 Pi 进程中启动 Ghos…（内容被截断，原始项目此处描述"在独立 Ghos…进程中运行"）

pi-recall — 长上下文召回与检索（README 未提供完整描述）。

典型适用场景

场景 推荐扩展
复杂多步重构任务 pi-goal + pi-plan-mode
跨语言大型项目 pi-lsp
自动化 PR Review pi-github-pr + pi-lsp
浏览器驱动的 AI 研究 pi-chrome-devtools + pi-firecrawl
Git 分支隔离开发 pi-worktree
多云供应商 API 管理 pi-accounts + pi-usage
AI 工具链可观测性 pi-analytics + pi-stamp
团队配置同步 pi-sync

坑与注意

  1. pi-workflow 与 pi-plan-mode / pi-goal 互斥：三者共享命令、工具、标志、事件通道和会话状态名，同时安装会产生重复处理器和状态竞争。
  2. pi-starship 与 pi-statusline 互斥：两者的页脚模块不能同时启用。
  3. 扩展权限风险：扩展运行在完整用户权限下，不审查就安装第三方扩展等于授予其完整文件系统访问权。
  4. 实验性扩展 API 可能变更：README 明确标注实验包的行为和 API 在版本间可能破坏性变更。
  5. pi-firecrawl 依赖 Firecrawl 服务：需自行准备或使用 Firecrawl Cloud API。
  6. pi-codex-compact 依赖 OpenAI Codex Remote Compaction V2：非 OpenAI Codex 用户无法使用此功能。

与同类对比

方案 定位 安装方式 扩展数量
narumiruna/pi-extensions Pi Coding Agent 扩展生态 pi install npm:@narumitw/... 20+ 包
@earendil-works/pi-tui Pi TUI 底层库 npm 独立安装 基础库
Pi 内置技能 Pi 原生能力 内置 有限

pi-extensions 的优势在于覆盖了从编程辅助（pi-lsp、pi-codex-compact）到团队协作（pi-sync、pi-accounts）的完整工具链，且每个包可独立安装、不污染环境。相比直接在 Pi 配置中写脚本，扩展包有版本管理和独立更新的优势。

一句话推荐结论

如果你使用 Pi Coding Agent，pi-extensions 是目前最完整的社区扩展生态，按需安装 pi-goal（长任务追踪）和 pi-lsp（多语言支持）两个核心包即可显著提升 Agent 可靠性和编程效率。

⚠️ 数字核验：本仓库当前 Stars ~390（2026-08 周增 +53）；实验性包 API 可能变更，安装前建议检查 npm 页面版本号。