扩展与 Pi 包

用 TypeScript 扩展给 Pi 添加工具、命令、事件处理和界面，用 Pi 包通过 npm 或 git 分发扩展、技能、提示模板和主题。

扩展

扩展是给 Pi 添加可执行行为的 TypeScript 模块；当工作流需要工具、命令、事件处理器、模型服务商、会话状态或终端界面（而不只是指令）时使用。扩展在 Pi 进程内运行，拥有相同的操作系统权限，可以检查提示、工具调用、文件、凭证和会话历史，所以只从你信任的来源加载。典型用途：添加智能体工具、保护路径、确认危险命令、响应会话事件、修改上下文、暴露命令、显示持久状态。扩展导出一个接收 ExtensionAPI 的默认工厂函数，工厂注册当前扩展运行时的能力（工具、命令、快捷键、服务商、事件处理器、渲染器、终端界面）。位置：用户 <agent-dir>/extensions/（默认 ~/.pi/agent/extensions/）、项目 .pi/extensions/（需项目信任）。官方扩展页还涵盖运行时生命周期、选择集成点、事件与并发、工具及工具暴露（可动态激活）、MCP 服务器、上下文与会话变化、状态、界面与模式、错误与清理。

Pi 包

Pi 包把扩展、技能、提示模板和主题作为一个单元安装和分发；当某项定制应通过 npm 或 git 共享、或几项资源属于一起时使用。包是普通目录或 npm 包，可以暴露约定的资源目录（extensions/、skills/、prompts/、themes/），或在 package.json 的 pi 键下声明显式路径，并自带运行时依赖。

pi install npm:@example/pi-tools@1.0.0
pi install git:github.com/example/pi-tools@v1
pi install ./local-package
pi list
pi remove <source>
pi update --extensions
pi -e npm:@example/pi-tools      # 只在本次调用试用，不写入设置

个人安装写入 ~/.pi/agent/settings.json；加 --local/-l 则写入 .pi/settings.json（项目包仅在项目信任之后才安装和加载）。来源：npm（指定版本即固定）、git（标签和提交也固定，更新会协调检出但不移动已配置的 ref）、URL（按 git 源处理）、本地路径（不复制，从解析路径加载）。包可以执行扩展代码，也可能含让模型运行程序的技能，安装第三方包前务必审查源码。