pi-candy-extensions 🍬

个人 pi 插件集合仓库。

⚠️ 开发验证版本：pi 0.85.1

本仓库所有插件均在此版本下开发、验证（扩展 API 与 TUI 内部机制以该版本为准）。pi 后续更新可能导致部分插件不可用（尤其是依赖 TUI 内部机制的 pi-candy-toolbox 的 click-cursor 工具）；若更新后出现问题，可临时回退到本版本：

# 以 npm 全局安装为例（按你的实际安装方式调整）
npm install -g @earendil-works/pi-coding-agent@0.85.1

回退验证正常后，如需升级请逐个插件回归测试后再升。

🖥️ 验证环境：fullscreen 模式

本仓库所有插件均在全屏（alt-screen）模式下开发与验证，推荐在全局 ~/.pi/agent/settings.json 中启用：

{ "tuiMode": "fullscreen" }

pi 的默认模式为 regular（inline）。鼠标上报只在 fullscreen 下由 pi 开启（regular 模式 TUI 不捕获鼠标），因此依赖鼠标的功能——如 pi-candy-toolbox 的 click-cursor 点击定位、transcript-jump 跳转——在 regular 模式下不可用；各插件的模式差异见其自身文档。

推荐使用的 pi 版本

下表选的是 pi 本体（@earendil-works/pi-coding-agent）的版本，与本仓库插件的版本无关，按所需功能选：

你要的功能	建议版本	说明
全量功能 + 官方原生点击定位（推荐）	0.85.1（或 ≥ 0.85.0）	pi 自 0.85.0 起原生支持「点击输入框定位光标」，且额外覆盖 autocomplete 条目点击、拖拽选区、双击/三击选词；0.85.1 修掉了原生点击的 hover 误选条目问题。此类版本上 pi-candy-toolbox 的 click-cursor 工具可关闭（{"click-cursor": false}），官方稳定后退役（见文档）
想用 click-cursor 工具（官方无原生支持的场景）	0.84.3 / 0.84.4	0.84.x 及以下官方没有原生点击定位，该功能只能由工具提供（工具即验证于 0.84.3）；0.85.x 上工具也能继续用（与官方能力重叠）
win-notify「等待用户」精确识别	≥ 0.84.4	官方新增 ui_prompt_start / ui_prompt_end 扩展事件，可精确识别“阻塞等待用户输入”（覆盖所有 ctx.ui 提问交互，如 ask、plan、permission 等插件），不再依赖插件名猜测；旧版回退为按 waitingTools 工具名匹配，对新插件/改名工具可能漏判

# 按需选择，以 npm 全局安装为例（按你的实际安装方式调整）
npm install -g @earendil-works/pi-coding-agent@0.85.1   # 推荐：官方原生点击定位
npm install -g @earendil-works/pi-coding-agent@0.84.4   # 需要 click-cursor 工具（官方无原生支持）

插件列表

插件	npm 安装	说明	文档
pi-candy-themes	pi install npm:pi-candy-themes	Selenized 配色主题包	README
pi-candy-win-notify	pi install npm:pi-candy-win-notify	Windows 桌面通知 + 终端标签页状态显示	README
pi-candy-toolbox	pi install npm:pi-candy-toolbox	小工具聚合箱：一个插件收纳零散小功能，每个工具独立开关与配置	README
pi-candy-undo	pi install npm:pi-candy-undo	文件级撤销/重做（对标 Claude Code /rewind）：/undo、/redo，回退对话与 agent 改过的文件	README

安装

本仓库是 monorepo：多个插件同处一个仓库、各自独立安装。pi 不支持从 git 仓库的某个子文件夹安装插件（pi install git:... 只能装仓库根目录的包），而这里不想一个仓库只放一个插件，因此请按下面的方式逐个安装。

npm 安装

包名与目录名相同：

pi install npm:pi-candy-undo      # 包名见上方插件列表

pi -e npm:pi-candy-undo           # 临时试用，不写入配置

npm 安装由 pi 自动执行 npm install，无需手动处理依赖。

本地安装

git clone https://github.com/CandyMuj/pi-candy-extensions.git
cd pi-candy-extensions/pi-candy-undo   # 目录名见上方插件列表
npm install --omit=dev                 # 可选：只装运行时依赖（仅带第三方依赖的插件需要）
pi install .                           # 安装当前目录

pi -e .                                # 临时试用，不写入配置

本地路径安装不会自动安装依赖，是否需要安装见各插件 README；上面的命令仅为示例。

⚠️ 精简依赖只用 --omit=dev，不要加 --omit=optional：本仓库有插件依赖 optionalDependencies 里的平台二进制，跳过会导致安装失败或运行时不可用。

各插件的依赖与配置细节见各自 README；pi-candy-toolbox 内各工具的详细文档见其 docs/ 目录。

仓库约定

• 新插件命名统一 pi-candy- 前缀
• 每个插件独立成目录、独立安装、互不依赖
• 插件细节不进本 README，直接看各自文档