pi-plugins-manager

Pi 插件（Pi package：extension / skill / prompt / theme）的按项目插件管理器。

目标：新建项目时从目录里挑插件、自动装进 .pi/settings.json（项目域）；日常在项目里按需增删； 全局只保留真正通用的少数插件，避免 ~/.pi/agent 越装越臃肿。

• 用 Pi 自己的包管理器写设置和装包，格式、目录、锁定、信任流程与 pi install -l 完全一致
• 内置 Pi 插件画廊快照（200 个包）+ npm registry 实时搜索
• 内置预设（starter / memory / agents / planning / quality / …），也可以把当前项目存成自己的预设
• 原生 TUI：多选列表（空格勾选、输入即过滤）、预设菜单、进度面板、pi config 联动
• 支持 /plugins 斜杠命令、pi --plugins 启动参数、以及给模型用的 plugins 工具

安装

# 全局安装一次，之后任意项目都能用 /plugins
pi install npm:pi-plugins-manager

# 本项目内开发调试
pi -e ./src/index.ts

安装后在 Pi 里输入：

/plugins

30 秒上手

/plugins                  # 打开管理面板（推荐入口，全部操作都有）
/plugins init             # 新项目向导：选预设或从目录里挑插件
/plugins add pi-web-access pi-memory     # 装到当前项目（.pi/settings.json）
/plugins add pi-web-access --global      # 装到全局（~/.pi/agent/settings.json）
/plugins remove pi-memory                # 多选删除
/plugins list             # 查看项目 + 全局插件（含资源数量、安装状态）
/plugins doctor           # 体检：信任状态、npm 缓存、缺失安装、版本固定

装完（或删完）会有 “Reload Pi now?” 询问，确认即执行 /reload，新插件立即生效。

命令参考

| 命令 | 说明 | | --- | --- | | /plugins | 交互式管理面板：添加/删除/预设/同步/诊断/重载/pi config | | /plugins list [--all\|--global] [--json] | 列出插件，标注 scope、是否已安装、资源数量 | | /plugins search <关键词> | 搜索插件目录（自定义清单 + 快照 + npm registry），可多选直接安装 | | /plugins add <引用...> [--global] | 安装并写入 settings | | /plugins remove <引用...> [--global] | 从 settings 与磁盘移除 | | /plugins init [预设] | 新项目向导；带预设名则直接按预设安装 | | /plugins presets [apply <名>\|save <名>\|rm <名>] | 查看/应用/保存/删除预设 | | /plugins catalogs | 查看自定义插件清单源（文件/URL/关键词） | | /plugins catalog add\|rm\|refresh\|export | 管理自定义清单，详见下面「自定义插件清单」 | | /plugins sync [--global] | 补齐“已配置但未安装”的插件（clone 别人的项目后很有用） | | /plugins doctor [--json\|fix] | 体检；fix 会修 npm 缓存导致安装失败的问题 | | /plugins refresh | 从 npm 刷新插件目录缓存 | | /plugins trust | 本次会话允许改动项目域（等价 pi install -l --approve） | | /plugins autoinit [预设\|off] | 设置“新项目自动询问的预设” | | /plugins resources | 说明如何用 pi config 开关单个 extension/skill/prompt/theme | | /plugins help | 帮助 |

引用格式（add / remove 都接受）：

pi-web-access                     # npm 包名（自动补 npm:）
@scope/[email protected]                  # 带版本固定
npm:@scope/pkg                    # 显式 npm
git:github.com/user/repo@v1       # git（也接受 https:// 与 ssh://）
./extensions/my-ext               # 本地路径

预设（Preset）

内置预设（/plugins presets 可看全部）：

| 预设 | 内容 | | --- | --- | | starter | pi-web-access + pi-mcp-adapter + todo 列表 | | web-research | 网页搜索/抓取/爬虫/文献研究 | | memory | 持久记忆 + 语义检索 | | context | 上下文压缩、旁问、会话归档 | | agents | 子智能体、并行/后台任务、动态工作流 | | planning | plan 模式、目标跟踪、计划评审 | | quality | 实时诊断、权限闸门、危险命令防护 | | ui | 状态栏、用量显示、TUI 组件 | | integrations | Telegram、文档桥、LangSmith/Braintrust 追踪 | | power-user | 模糊搜索、锚定编辑、工具运行时 |

自己的预设：

/plugins presets save 我的后端项目     # 把当前项目的插件列表存成预设
/plugins presets apply 我的后端项目    # 另一个项目里一键复现
/plugins presets rm 我的后端项目       # 删除（内置预设不可删）
/plugins autoinit 我的后端项目         # 以后没有 .pi/settings.json 的项目会主动问要不要套用

用户预设存在 ~/.pi/agent/plugin-manager.json，可手动编辑、可提交到 dotfiles。

自定义插件清单（Catalog）

除了内置画廊快照和 npm registry，管理器还支持“自定义清单”——团队/个人自己的插件列表， 搜索、/plugins init 和目录多选都会包含它们，并优先排序、标注来源。

支持三种来源：

| 类型 | 写法 | 用途 | | --- | --- | --- | | 本地 JSON 文件 | ./pi-plugins.json、file:~/lists/team.json | 提交到仓库、放在共享盘 | | 远程 URL | https://example.com/pi-plugins.json | 团队统一维护、随时更新 | | npm 关键词 | registry:acme-pi-plugin | 私有 registry / 公司包前缀 |

清单文件格式（字符串或对象都行）：

{
  "title": "Platform team plugins",
  "packages": [
    "@acme/pi-tools",
    { "name": "@acme/pi-secrets", "description": "内部密钥助手", "tags": ["security"] },
    "git:github.com/acme/pi-internal@v1"
  ]
}

命令：

/plugins catalogs                                  # 查看已配置的清单源（id、类型、条数、错误）
/plugins catalog add ./pi-plugins.json --id team    # 注册到项目（.pi/plugins.json，可提交）
/plugins catalog add https://intra/pi-list.json --id platform --global
/plugins catalog add registry:acme-pi-plugin --id acme --global
/plugins catalog rm acme                            # 删除定义
/plugins catalog refresh [id]                       # 重新拉取 URL / 关键词来源
/plugins catalog export ./pi-plugins.json           # 把当前项目插件导成清单文件
/plugins catalog export ./team.json --preset starter --register

其他要点：

• --global 写 ~/.pi/agent/plugin-manager.json，默认为项目域、写 .pi/plugins.json（可以随仓库提交，队友 clone 后 /plugins sync 或 /plugins init 即可复现）。
• 项目域同名 id 优先于全局域；doctor 会提示被覆盖的全局定义。
• URL/关键词来源首次会联网获取，结果缓存到 ~/.pi/agent/plugin-manager-catalogs.json（12 小时 TTL），之后离线也能搜索、浏览；catalog refresh 强制刷新。
• 自定义清单里的条目在搜索结果里带来源标签（如 Platform team plugins），并且排序优先于画廊结果。
• .pi/plugins.json 还能放项目预设与默认预设：

{
  "catalogs": [{ "id": "team", "file": "./pi-plugins.json" }],
  "presets": { "backend": { "title": "Backend", "description": "", "packages": ["@acme/pi-tools", "pi-memory"] } },
  "defaultPreset": "backend"
}

设了 defaultPreset 后，在这个仓库里启动 Pi 且项目还没有 .pi/settings.json 时，会主动问 是否按该预设安装（等价于把“新项目自动装哪些插件”写进仓库共享给团队）。

CLI 集成

pi --plugins                            # 启动后直接打开管理面板
pi --plugins-cmd "list"                 # 启动时执行命令
pi --plugins-cmd "init starter"         # 新项目一条命令装好预设
pi --plugins-cmd "doctor --json"        # print 模式下输出去 stdout，可管道给 jq
pi --plugins-cmd "add pi-web-access --yes --no-reload" --approve

• print（-p）模式下管理器输出走 stdout，方便脚本；TUI/JSON/RPC 模式下走 stderr，不干扰 Pi 的协议流。
• --yes：跳过“项目未受信任”的交互确认（等价于 pi install -l --approve）。
• --no-reload：只安装不重载（脚本里常用）。
• 写项目域时如果项目未被信任，会先询问一次（或用 --yes/--trust）。未信任状态下只读命令仍可用，安装状态会标注为不可用。

让模型自己管插件

扩展注册了 plugins 工具，可以直接对 Pi 说：

给这个项目加上网页搜索和记忆插件，别装全局的。 看看这个项目装了哪些插件，有没有缺失的。

规则：list / search / doctor / presets 只读，直接执行； add / remove / sync / init / 预设应用等写操作必须经过你的确认对话框，无 UI 环境（脚本、CI）会拒绝执行并提示改用 /plugins 命令。 安装完成后工具会提醒你 /reload。

npm 缓存问题（doctor --fix）

Pi 通过调用 npm 安装包。如果 npm 的 cache 目录不可写（例如 ~/.npmrc 里 cache=D:\nodejs，而该目录只有管理员可写），所有安装都会以 EPERM 失败， Pi 启动时自动安装项目包也会直接崩掉。

管理器做了两件事：

1. 运行时探测：安装前发现缓存不可写，就把 npm_config_cache 指到 ~/.pi/agent/npm-cache，本次安装照常成功（/plugins add 因此可以直接用）。
2. /plugins doctor --fix：把 npmCommand: ["npm", "--cache", "<可写目录>"] 写进全局 Pi 设置， 从此连 Pi 自己的安装（含启动时自动安装项目缺失包）都能正常工作。

~/.npmrc 里的 cache 指向一个不可写目录时，/plugins doctor 会明确报出来。

应急：如果某个项目因为缺包无法启动（启动时自动安装失败）， 用 pi --no-approve 先进去（忽略项目设置），跑 /plugins doctor --fix，再正常启动。

作用域与信任

• 默认写项目域：<项目>/.pi/settings.json，可提交进仓库，队友 clone 后 Pi 会自动装齐。
• --global 写全局域：~/.pi/agent/settings.json。
• 同名包在两边都存在时，项目条目生效（Pi 的既有规则），doctor 会提示“shadowed”。
• 项目域改动需要信任：Pi 启动时的信任询问、--approve、或 /plugins trust 任一种即可。
• 安装目录：项目 → .pi/npm，全局 → ~/.pi/agent/npm（都由 Pi 管理）。

工作原理

• 设置读写与安装/卸载都委托给 Pi 的 DefaultPackageManager / SettingsManager， 所以 pi list、pi install -l、pi config 与管理器互相可见、不会打架。
• 插件目录 = 内置快照 catalog/seed.json（Pi 官方画廊前 200 名，含描述、标签、下载量）
  • 自定义清单（文件 / URL / npm 关键词，见下节，12 小时缓存）
  • 实时 npm registry 搜索（keywords:pi-package），结果缓存到 ~/.pi/agent/plugin-manager-catalog.json（6 小时 TTL，离线可用）。
• 资源数量（1 ext, 2 skills）来自包内 package.json 的 pi 清单，或约定目录扫描。
• 修改后需要 /reload 才会加载新扩展；管理器会主动询问。

安全

插件会以你的完整权限执行代码（extension 可执行任意操作，skill 可指示模型执行命令）。 管理器给的是可见性与确认：安装前确认、写操作确认、doctor 暴露来源与状态、 来源不明的包会被标注 “not in the catalog snapshot”。仍然请只安装你信任的包。

目录结构

src/index.ts      扩展入口：/plugins 命令、plugins 工具、--plugins/--plugins-cmd 参数、新项目提示
src/commands.ts   子命令解析、交互面板、各流程编排与输出
src/service.ts    业务层（增删、同步、预设、体检、npm 修复），可注入依赖、便于测试
src/packages.ts   包装 Pi 的 DefaultPackageManager / SettingsManager，资源数量统计
src/catalog.ts    画廊快照 + 自定义清单 + npm registry 搜索 + 磁盘缓存 + 预设
src/catalog-sources.ts  自定义清单源（文件/URL/关键词）解析、加载与缓存
src/registry.ts   npm registry 搜索原语
src/sources.ts    引用解析（npm/git/本地）、去重标识、显示名
src/settings.ts   Pi 设置、管理器配置、项目 `.pi/plugins.json` 的读写
src/npm.ts        npm 缓存探测与回退
src/ui.ts         TUI 组件：多选列表、进度面板、文本查看器、SelectList 菜单
src/format.ts     纯文本/带色渲染（列表、目录、预设、诊断）
catalog/          seed.json（画廊快照）、presets.json（内置预设）
scripts/          generate-catalog.mjs（刷新快照）、e2e.mjs（真实 CLI 端到端测试）
test/             vitest 单测（172 个）：解析、设置、目录、自定义清单、服务、命令、UI、扩展注册

开发

npm install
npm run check        # tsc --noEmit
npm test             # vitest run（174 个单测）
npm run e2e          # 用真实 pi CLI 跑端到端（隔离的 agent 目录，25 步）
npm run e2e -- --with-network   # 追加 npm 安装/卸载与远程清单用例（29 步）
npm run catalog      # 从 pi.dev/packages + npm registry 重新生成 catalog/seed.json

发布 / 上传到 GitHub

第一次使用 Git 或 GitHub，请直接看 docs/git-github-guide.md（中文，含概念说明、逐步命令、常见报错、Release / Actions / npm 发布）。

最短路径：

git config --global user.name "你的名字"
git config --global user.email "你的邮箱@example.com"   # 与 GitHub 账号一致
git add -A && git commit -m "feat: my change"
git push
git tag -a v0.1.0 -m "v0.1.0: first public release" && git push origin v0.1.0

标签推送后，别人就能按版本安装：pi install git:github.com/lzh100-dot/[email protected]。 发布到 npm（pi install npm:pi-plugins-manager）的步骤见指南第 5.3 节。

本机备注：项目里的 .pi/sandbox.json（{"enabled": false}）是为了让 pi-landstrip 沙箱 在这台机器上能正常启动 shell；与插件管理器本身无关，已在 .gitignore 中排除。

已知限制

• /plugins doctor --fix 只修 npm 缓存这一类问题（写入全局 npmCommand），不会替你改 ~/.npmrc。
• 插件启用/禁用单个资源（例如只启用某个包里的一个 skill）仍由 pi config -l 负责，管理器只做跳转说明。
• 预设引用的是 npm 名或原始 source，不做版本锁定；需要复现性请在 add 时写死版本（doctor 会提示未固定的包）。
• 目录快照不会自动刷新：/plugins refresh 或重新 npm run catalog；自定义清单用 /plugins catalog refresh。
• 自定义清单条目只做展示与搜索，不校验包是否真的可安装（安装时由 Pi/npm 报错）；清单里的 version/repository 字段仅用于展示。

变更记录（相对首个版本新增）

• 自定义插件清单（Catalog）：本地 JSON / 远程 URL / npm 关键词三种来源，可全局或按项目配置， 项目清单可提交仓库；搜索结果优先展示并标注来源；远程来源带磁盘缓存（12h）与 catalog refresh。
• .pi/plugins.json：项目级清单 + 项目预设 + defaultPreset（新人 clone 后自动提示安装）。
• 命令：/plugins catalogs、/plugins catalog add|rm|refresh|export，管理面板新增 “Catalog sources…” 入口。
• 工具：plugins 新增 catalogs / catalog_add / catalog_remove / catalog_refresh / catalog_export， 写操作同样需要用户确认。
• doctor 会报告自定义清单的加载错误、过期状态与被项目覆盖的全局定义。