包、技能与插件

本页说明 pi-webapp 里能看到的四种扩展内容、各自在哪里管理，以及如何开关内置工具。

它们分别是什么

这几个词在界面里挨得很近，很容易混淆。

术语	它是什么	在哪里管理
Pi 包	从 npm、Git 或本地目录安装的一组内容，可以同时包含扩展和技能。	Pi 设置 → 包与扩展
Pi 扩展	给 Pi 本身增加能力的代码，例如新的指令和工具。可以来自某个包，也可以单独通过路径加载。	Pi 设置 → 包与扩展
技能	一个文件夹或一个 SKILL.md 文件，里面是 Pi 可以按需加载的任务指引。	Pi 设置 → 技能
插件	pi-webapp 里有自己界面的功能：内置的文件、终端和 Git 工具，以及 Excalidraw 这类可选工具。	侧栏里的 插件

安装一个包，和开关一个插件不是一回事，两者故意放在不同的位置。

包与扩展

打开 Pi 设置 → 包与扩展。页面列出：

• 已安装的包，以及每个包包含的扩展。
• 独立扩展，即不属于任何包的扩展，各自标着 已启用 或 未启用，以及 项目 或全局。
• 添加包，在这里输入来源。
• 扩展路径，用来加载单个扩展文件或目录。

添加一个包

在 添加包 输入框里填入下面任意一种，然后点 添加：

来源	示例
npm 包	npm:@scope/package-name
Git 仓库	git:github.com/user/repo 或 https://github.com/user/repo
SSH	ssh://git@github.com/user/repo 或 git@github.com:user/repo
本地目录	/path/to/package

之后 Pi 会重新加载它的资源。这条记录会保存到 Pi 的全局设置（~/.pi/agent/settings.json），所以终端里的 Pi 也能看到。要移除某一项，请使用列表里它自己的移除操作。

如果你把包来源（任何以 npm:、git:、http(s)://、ssh:// 或 git@ 开头的内容）填进扩展或技能的输入框，对话框会拦住你并提供 转到包，因为那两个输入框只接受文件路径。

通过路径加载扩展

在 扩展路径 下填入扩展文件或目录的路径，点 添加。填进这里的包来源会被拒绝，并标为 未加载：请改用 添加包。

技能

Pi 设置 → 技能 列出 Pi 已发现并加载的技能及其路径。要添加一个没有被自动发现的技能，在 手动配置技能 下填入 SKILL.md 文件，或包含它的目录的路径。

技能也会以 skill:<名称> 的形式出现在对话的指令菜单里。

插件

点击侧栏里 新会话 下面的 插件。页面分两组，刷新按钮会读取两组的最新状态。

内置能力

工作区文件、终端 和 Git 默认都是开启的，各有一个开关。

• 开关是全局的：它对这个服务上的每个工作区和会话都生效，并且重启后依然保持。
• 切换需要所有会话都处于空闲。页面里有说明；等它们结束后再试。
• 关闭一个工具会关掉它已打开的标签页，并拒绝它的请求。关闭 终端 还会结束服务上的所有终端：此时会弹出 停用终端？ 对话框，提醒未保存的 Shell 工作可能丢失，你点 停用并结束终端 才会确认。
• 开关显示的是服务确认过的状态，而不是你刚才点的结果。

官方插件

按需下载的可选插件。目前只有 Excalidraw（官方）。请先点 下载，再启用；在插件安装之前，开关是不可用的。点击一行可以查看它的说明、版本、检查更新 和 卸载。完整流程见用 Excalidraw 画图。

已安装的插件可以自行更新，不会替换页面，也不会打断你的会话。打开的编辑器会推迟版本切换；下载失败不会自动重试，也不会丢掉你现有的版本。

改动什么时候生效？

• 添加、移除或修改包、扩展和技能：Pi 的资源会立即重新加载，对话框会报告问题。
• 某个包在你加载之后修改了自己的代码，或者你正在开发的插件：页面不会替换后端代码。请重启服务（pi-webapp stop，再启动），或者在终端会话里运行 /reload 和 /web。

插件作者可以在开发者页面找到开发环境的设置方法。