Pi 的扩展机制

Pi Coding Agent 通过工具、Skills、TypeScript Extensions、提示模板和 Packages 适配不同任务。这些机制处在不同层次：有的提供可执行动作，有的提供操作说明，有的改变运行时行为，还有的负责分发。

以下按 2026 年 9 月 17 日的官方扩展文档及各专项文档说明。

工具与 Extension

工具是模型可以请求执行的动作，通常具有名称、用途、参数定义和执行实现。例如“查询工单”需要真正连接工单系统并返回结果。

Extension 是在 Pi 进程中运行的 TypeScript 模块。它可以用 pi.registerTool() 注册工具，也可以监听生命周期事件、添加用户命令或调整交互界面。因此，一个 Extension 可以提供多个工具，也可以只改变行为而不增加工具。

例如，“运行某类操作前展示确认框”适合由 Extension 实现。这里的确认逻辑是开发者编写的运行时代码，不是要求模型记住一句话。

Skill：按需加载的操作知识

Skills 以 SKILL.md 为入口，可以包含操作步骤、参考资料、脚本和资产。Pi 在启动时发现名称与描述，相关任务出现时再加载完整说明，也可以通过 /skill:名称 明确调用。

例如，一个“测试失败分析”Skill 可以告诉模型先阅读测试输出，再定位断言与实现，最后核对修复范围。它表达的是如何使用已有能力完成任务。仅在说明中写下“调用工单系统”，不会自动生成可执行的工单工具。

按需加载能减少常驻上下文，但是否正确选择和遵循 Skill 仍受模型行为影响。官方文档也提示模型并非总会自行读取匹配的 Skill。

提示模板：复用输入

提示模板 是可以展开的 Markdown 提示文本。假设创建 review.md，用户输入 /review 就可以展开预先整理的审查要求。

它适合复用短而稳定的任务表达，例如“检查当前改动的边界条件，并给出文件位置”。与 Skill 相比，模板重点是输入复用；与 Extension 相比，模板本身不会注册运行时事件处理器。

Packages：组合与分发

Pi Packages 可以把扩展、Skills、提示模板和主题放在同一个包里，经 npm 或 Git 分发。包使用约定目录，或在 package.json 的 pi 字段中声明资源。

Package 是打包方式，不代表其中所有内容都是工具，也不保证它提供独立运行的 Agent。阅读一个包时，应查看它具体包含哪些资源和依赖。

如何选择机制

同一场景可以组合使用。例如，代码审查 Package 可以含有审查模板、项目审查 Skill，以及查询 CI 状态的工具。这里是机制组合示例，不指某个已经安装的官方包。

内置能力与扩展能力

Pi 的设计说明将 MCP、子 Agent 和计划模式等工作方式留给扩展或外部工具。讨论“Pi 支持某能力”时，应明确是核心默认提供，还是安装某个扩展后实现，见官方设计原则。

Extensions 可以执行程序，Skills 也可能引导模型运行脚本。因此，安装包是引入代码与指令的行为；扩展中的确认框不能取代操作系统级隔离。

资源怎样被发现和加载

Pi 会从全局目录、项目目录、设置中指定的路径和已配置的 Packages 发现资源。项目本地资源需要先通过项目信任；全局资源与项目资源的加载条件并不完全相同。

以 Extension 为例，全局目录 ~/.pi/agent/extensions/ 适用于所有项目，项目目录 .pi/extensions/ 适用于当前项目。开发时还可以通过 pi -e ./my-extension.ts 临时加载。具体位置与支持格式见Extension Locations。

“文件存在”“被发现”“成功加载”“实际被调用”是四个不同状态。排查时应逐层确认。

从加载到产生效果

不同资源产生效果的时机不同：

• Extension 加载后可以注册工具、命令、事件处理和界面组件；
• Skill 被发现后，其名称与描述用于匹配任务，完整正文通常按需读取；
• 提示模板在用户调用对应命令时展开；
• 主题影响终端显示；
• Package 只是携带和声明上述资源。

例如安装一个含有 review Skill 和 CI 工具的 Package 后，Skill 可能在审查任务中才被读取，而 CI 工具已经注册为可选动作。不能因为 Package 已安装，就认定每个资源都在当前任务中被模型使用。

重载与开发验证

将 Extension 放入自动发现目录后，可以使用 /reload 重新加载扩展、Skills、提示模板、主题和上下文文件。用 -e 临时加载更适合验证单个 Extension，避免先写入长期配置。

验证资源是否生效，可以检查：

1. 启动信息是否列出资源；
2. Extension 命令是否出现在命令补全中；
3. 自定义工具是否出现在当前可用工具集合中；
4. Skill 是否能通过 /skill:名称 明确调用；
5. 运行时是否出现 Extension 报错。

冲突与来源排查

如果出现同名命令、Skill 或工具，先列出资源来自全局目录、项目目录、设置路径还是 Package，再缩小加载范围。Packages 可以筛选需要加载的 Extensions、Skills、提示模板和主题；项目设置也可能加入额外路径。

排查时可暂时只加载目标资源：

pi --no-extensions -e ./target-extension.ts

这用于隔离 Extension 问题，不会同时禁用 Skills 或其他类型资源。若要得到更小的运行环境，应分别使用相应的 --no-* 参数，并核对启动信息。

扩展错误的边界

Extension 运行在 Pi 进程内，可以读取环境、执行代码或拦截工具调用。一个扩展报错可能影响自己的事件处理或功能，具体影响取决于报错阶段和扩展实现。

因此，第三方扩展出现问题时，最有用的证据包括 Extension 名称与版本、加载来源、触发动作、错误消息和最小复现场景。仅报告“Pi 失效”通常不足以定位是核心、模型、工具还是扩展的问题。