mirror of
https://github.com/getpaseo/paseo.git
synced 2026-10-28 12:12:47 +00:00
Mohamed Boudra
4fe006df86
* feat(plugins): unify panel props and persist tab state * refactor(plugins): make agent panel registration canonical * docs(plugins): update Chinese panel API reference and migration
2535 lines
153 KiB
Markdown
2535 lines
153 KiB
Markdown
---
|
||
title: 插件参考
|
||
description: 本地插件文件、客户端和服务端运行时、平台限制、贡献、RPC、生命周期、宿主环境和 CLI 命令。
|
||
nav: 参考
|
||
---
|
||
|
||
# 插件参考 {#plugin-reference}
|
||
|
||
从[插件快速上手](/docs/plugins)开始创建你的第一个插件。
|
||
|
||
要迁移已有的插件？请按照独立的[运行时入口迁移指南](/docs/plugins/migration)操作。
|
||
|
||
本地插件是安装到某个 Paseo daemon 中的目录来源。插件可以贡献：
|
||
|
||
- 为 Paseo 客户端添加 React Native 界面，以及侧边栏顶部和底部项；
|
||
- 作为工作区标签页打开的工作区面板和 Agent 面板；
|
||
- 用于查看或编辑匹配文件的[文件面板](#file-panels)；
|
||
- Command Center 中的全局、工作区和 Agent 操作；
|
||
- 消息 Composer 中的斜杠命令；
|
||
- 经过转换的、以及由 daemon 推送的 Agent 时间线行；
|
||
- **设置 → 外观** 中的浅色和深色主题；
|
||
- 在 daemon 旁运行、经过 schema 校验的 RPC 处理函数；
|
||
- 通过 TypeScript SDK 执行的普通 Paseo 操作；
|
||
- 消息 Composer 中可搜索的外部资源。
|
||
|
||
插件代码是受信任的，没有沙盒。客户端界面在 Paseo 应用中运行。后端贡献在一个子进程中运行，可以访问 daemon 所在的机器，包括它的文件、进程、凭据和网络。
|
||
|
||
## 已连接的主机 {#connected-hosts}
|
||
|
||
客户端界面中的 `usePaseo().hosts` 与服务端处理函数或生命周期钩子中的 `context.paseo.hosts`
|
||
使用相同的 [SDK 主机 API](/sdk/reference#clienthosts)。它们描述所选 daemon 保存的连接。
|
||
现有的 `useHosts()` 和 `getPaseoClient(serverId)` 仍描述应用已知的主机。
|
||
|
||
```ts
|
||
const remote = await context.paseo.hosts.client("srv_build_box");
|
||
try {
|
||
return await remote.workspaces.list();
|
||
} finally {
|
||
await remote.dispose();
|
||
}
|
||
```
|
||
|
||
返回的 API 拥有自己的观察。销毁插件 API 时也会释放由它派生的作用域。
|
||
远程调用应留在拥有它的处理函数或生命周期作用域内。调用 B 不会把 B 的插件生命周期钩子转发到 A。
|
||
通过路由插件创建的注册项保留其来源身份，其中包含经过认证的链路和发起调用的插件。
|
||
|
||
## 项目文件 {#project-files}
|
||
|
||
`paseo plugin init /absolute/path/to/my-plugin` 会创建：
|
||
|
||
```text
|
||
my-plugin/
|
||
paseo-plugin.json
|
||
index.client.tsx
|
||
index.server.ts
|
||
client/greeting.tsx
|
||
server/greeting.ts
|
||
shared/greeting.ts
|
||
package.json
|
||
tsconfig.json
|
||
```
|
||
|
||
必需的根 manifest 是 `paseo-plugin.json`：
|
||
|
||
```json
|
||
{
|
||
"id": "my-plugin",
|
||
"description": "Reviews changes before merge",
|
||
"requirements": { "paseo": ">=0.8.0" }
|
||
}
|
||
```
|
||
|
||
| 字段 | 是否必填 | 行为 |
|
||
| -------------- | -------- | ---------------------------------------------------------------------------------------------------------- |
|
||
| `id` | 是 | 默认的安装 ID。 |
|
||
| `name` | 否 | 注册表和网站使用的非空显示名称；与安装 ID 无关。 |
|
||
| `icon` | 否 | 插件包内 PNG 文件的相对路径。 |
|
||
| `media` | 否 | 包内图片或视频路径的数组，或 HTTPS URL。空数组是有效的。 |
|
||
| `description` | 否 | 在 **设置 → 插件** 中显示在插件 ID 下方的非空摘要。 |
|
||
| `translations` | 否 | 其他语言的展示文本，由注册表读取，Paseo 会忽略它。见[其他语言](/docs/plugins/publishing#other-languages)。 |
|
||
| `requirements` | 否 | 支持的 Paseo 版本，见下文。 |
|
||
| `build` | 否 | 准备命令，见 CLI 参考。 |
|
||
|
||
路径相对于 `paseo-plugin.json`，使用正斜杠，并且不能包含 `..` 片段。即使 `media` 在运行时 manifest 中是可选的，可视化插件的注册表展示页仍然需要一张界面图片。接受的格式和展示页要求见[图标和截图](/docs/plugins/publishing#icons-and-screenshots)。Paseo 会校验这些引用，但不会打开本地资源或获取 URL。
|
||
|
||
未知的顶层字段会被忽略。已知字段仍然会被校验，`requirements` 中的未知键会被拒绝，以免拼写错误的约束悄悄跳过兼容性检查。使用 `name`、`icon` 或 `media` 的 manifest 需要 Paseo 0.11.0 或更高版本；较旧的 daemon 会在安装时拒绝这些字段。
|
||
|
||
### 版本要求 {#requirements}
|
||
|
||
`requirements` 是一个可选对象。它目前支持的键 `paseo` 接受一个 npm semver 范围。省略 `requirements.paseo` 表示 `<0.8.0`：即该插件早于第一个破坏性的插件版本。Paseo 0.8 及更高版本会拒绝它，并附上[迁移指南](migration)的链接。空字符串、无效的范围以及未知的 manifest 要求键都会被拒绝。
|
||
|
||
| 范围 | 兼容的版本 |
|
||
| ---------------- | ---------------------------------------------------- |
|
||
| `>=0.8.0` | 0.8.0 及之后的版本，包括预发布版本和将来的破坏性版本 |
|
||
| `^0.8.0` | 0.8.x 版本，包括预发布版本 |
|
||
| `>=0.8.3 <0.9.0` | 0.8.3 到最后一个 0.8 补丁版本，包括预发布版本 |
|
||
|
||
预发布的 Paseo 版本也满足其稳定核心版本（`major.minor.patch`）所满足的范围，因此 `0.8.0-beta.1` 满足 `>=0.8.0`，但不满足 `<0.8.0`。
|
||
|
||
`>=0.12.0-beta.4` 这样的预发布最低版本也会通过稳定核心 `0.12.0` 接受 `0.12.0-beta.3`。若要排除同一核心的较早构建，请使用不同的稳定核心版本。
|
||
|
||
`paseo plugin init` 会写入 `>=` 加当前 CLI 版本，并为类型检查固定匹配的 SDK。采用更新的 API 时，请提高最低版本。当某个之后的版本不兼容时，请添加上限；只有下限并不能保证免受将来破坏性变更的影响。
|
||
|
||
daemon 会在安装、运行准备命令或加载插件之前检查自己的版本，并在启动、启用和重新加载时再次检查。被拒绝的更新会保留已安装的修订。每个已连接的应用在执行客户端代码之前会检查自己的版本，并在 **设置 → 插件** 中显示不兼容。兼容的 daemon 并不能让较旧的应用变得兼容。没有客户端入口的插件不要求已连接的应用匹配。
|
||
|
||
例如：`Plugin "review" requires Paseo >=0.8.0. Your daemon is 0.7.2.` 请使用兼容的插件修订，或更新提示中的运行时。0.8 之前的版本不理解这个 manifest 字段，也无法显示这条新的诊断信息。
|
||
|
||
### 运行时入口 {#runtime-entries}
|
||
|
||
| 入口 | 运行时 | 接收 | 何时需要 |
|
||
| ------------------ | ---------------------- | --------------------- | ------------------------------------------------ |
|
||
| `index.client.tsx` | Paseo 应用，每个客户端 | `PluginClientContext` | 插件有任何 UI、回调、主题或附件来源时 |
|
||
| `index.server.ts` | daemon 子进程 | `PluginServerContext` | 插件贡献处理函数、钩子、设置持久化或 Provider 时 |
|
||
|
||
至少需要一个入口；两者都接受 `.ts` 或 `.tsx`。仍然只有旧 `index.ts` 的目录会加载失败，并指向[迁移指南](/docs/plugins/migration)。
|
||
|
||
插件、界面、侧边栏项、工作区面板、Command Center 项、附件来源和斜杠命令的 ID 以小写字母开头，只包含小写字母、数字或连字符。
|
||
|
||
生成的 `package.json` 把 `@getpaseo/plugin` 和其他宿主模块安装为开发依赖，用于本地类型检查和测试。它们的运行时实例由 Paseo 提供。使用者在添加插件时不会安装它们。
|
||
|
||
其他每个模块都位于以下三个目录之一。在其中嵌套没有问题；位于插件根目录的模块会导致编译错误。
|
||
|
||
| 目录 | 编译进 | 用于 |
|
||
| --------- | -------------- | --------------------------------------------------- |
|
||
| `client/` | 仅应用的包 | React、React Native、hook、样式、界面、面板和回调。 |
|
||
| `server/` | 仅 daemon 的包 | Node API、本地资源、凭据和 RPC 处理函数。 |
|
||
| `shared/` | 两者 | Zod RPC 契约以及两个运行时都会导入的普通值。 |
|
||
|
||
## 运行时翻译 {#runtime-translations}
|
||
|
||
**尚未发布的 API。** 发布插件前，请将 `requirements.paseo` 设置为首次包含这些 API 的版本。[翻译示例](https://github.com/getpaseo/paseo/tree/main/plugin-examples/translations) 暂用 `>=0.12.1`，实际引入版本尚未确定。
|
||
|
||
将 JSON 资源随客户端代码一起打包。必须提供英语（`en`）；其他语言使用规范语言标签，例如 `zh-CN`。资源由嵌套对象和字符串叶节点组成。其他语言可省略键，缺失时回退到英语。定义翻译时会拒绝未知键、无效资源、非规范语言标签，以及与英语不一致的插值占位符。
|
||
|
||
```ts
|
||
// client/messages.ts
|
||
import { defineTranslations } from "@getpaseo/plugin/client";
|
||
import en from "./locales/en.json";
|
||
import zhCN from "./locales/zh-CN.json";
|
||
|
||
export const messages = defineTranslations({ resources: { en, "zh-CN": zhCN } });
|
||
```
|
||
|
||
在插件的 `tsconfig.json` 中启用 `resolveJsonModule`。Paseo 在本地打包这些导入，不通过网络加载。资源对示例：
|
||
|
||
`client/locales/en.json`:
|
||
|
||
```json
|
||
{
|
||
"title": "Workspace notes",
|
||
"add": "Add note",
|
||
"notes_one": "{{count}} note",
|
||
"notes_other": "{{count}} notes"
|
||
}
|
||
```
|
||
|
||
`client/locales/zh-CN.json`:
|
||
|
||
```json
|
||
{
|
||
"title": "工作区笔记",
|
||
"add": "添加笔记",
|
||
"notes_other": "{{count}} 条笔记"
|
||
}
|
||
```
|
||
|
||
在 React UI 中使用插件的 hook：
|
||
|
||
```tsx
|
||
import { useTranslation } from "@getpaseo/plugin/client";
|
||
import { Text } from "react-native";
|
||
import { messages } from "./messages";
|
||
|
||
function NoteCount({ count }: { count: number }) {
|
||
const { t, locale } = useTranslation(messages);
|
||
return <Text accessibilityLanguage={locale}>{t("notes", { count })}</Text>;
|
||
}
|
||
```
|
||
|
||
对于由宿主持续渲染的标签，使用 `messages.message(key, options?)`：
|
||
|
||
```tsx
|
||
client.addScreen({
|
||
id: "notes",
|
||
title: messages.message("title"),
|
||
Component: Notes,
|
||
});
|
||
```
|
||
|
||
`PluginText` 为 `string | PluginMessage`。消息引用支持界面标题（包括标题函数）、设置与侧边栏标题、工作区与文件面板标题、Command Center 标题、斜杠命令描述与参数提示、按钮标题与标签、嵌套菜单标题、附件来源标题/选择器标题/搜索占位文本，以及主题名称。现有的字符串仍然有效。保持 ID、斜杠命令名称、图标、URL 和命令搜索关键词不变。
|
||
|
||
描述符类型保留现有的字符串默认值。为翻译描述符显式标注类型时，传入文本类型参数，例如 `PluginScreenContribution<PluginText>`。内联注册会自动推导类型。
|
||
|
||
回调中的临时文本使用 `client.i18n.t(messages, "add")`，它读取调用时的应用语言。`client.i18n.locale` 和 hook 的 `locale` 返回解析后的应用语言，即使某条消息回退到英语。不要将 `t` 的返回值用作持续注册的标签。
|
||
|
||
键由英语资源推导。`notes` 等复数基础键要求数字类型的 `count`；i18next 根据语言选择 `_zero`、`_one`、`_two`、`_few`、`_many` 或 `_other` 形式。命名插值使用 `{{name}}`，调用时传入 `{ name: value }`。TypeScript 将导入 JSON 的字符串值拓宽为 `string`，因此 JSON 插值名称在运行时检查；内联字面量资源还能推导必需的插值名称。`{{amount, number}}` 等 i18next 格式化语法使用解析后语言的 `Intl` 格式化器。
|
||
|
||
显式选择的应用语言优先于设备语言；“跟随系统”使用应用支持的语言解析规则。连接到同一 daemon 的不同应用各自保留语言设置。切换语言会更新已挂载的 UI 和宿主标签，不重新加载插件、不重置组件状态，也不替换 RPC/查询缓存。网页和原生的模态框与弹出层均收到相同的安装上下文。
|
||
|
||
RPC 返回与语言无关的结构化数据，在客户端翻译呈现内容。保持用户草稿、agent 输出、原始 daemon 错误、日志与终端文本不变。manifest 列表翻译和 `OVERVIEW.<locale>.md` 是独立的发布元数据，参见[你的列表页面](publishing#your-listing-page)。
|
||
|
||
## 运行时模块 {#runtime-modules}
|
||
|
||
Paseo 从对应的入口构建每个包。把 `client/` 导入 daemon 的包、把 `server/` 导入应用的包，或在应用的包中任何位置导入 Node 模块，都会导致编译错误。服务端导入 React、React Native 或客户端 SDK 入口也会失败。共享代码只能导入共享代码：不能导入 Node、React、特定运行时的 SDK 入口或特定运行时的类型。
|
||
|
||
SDK 根入口（`@getpaseo/plugin`）只包含共享数据、schema 和与运行时无关的辅助函数。从 `/client` 导入客户端 context 和 hook，从 `/server` 导入服务端 context 和生命周期契约，从 `/client/ui` 导入 UI。这些规则同样适用于类型导入和传递依赖。`/client/host` 是应用宿主的私有模块；插件不能导入它。
|
||
|
||
### 客户端运行时 {#client-runtime}
|
||
|
||
Paseo 为客户端代码提供以下模块：
|
||
|
||
| 模块 | 用于 |
|
||
| ---------------------------- | -------------------------------------------------------------------------------------------- |
|
||
| `@getpaseo/plugin` | 共享数据、`defineRpc`、`defineSettings`、`defineAttachmentSource`、`RpcInput` 和 `RpcOutput` |
|
||
| `@getpaseo/plugin/client/ui` | Paseo UI 组件和 UI hook |
|
||
| `@getpaseo/plugin/client` | 客户端贡献 context、`usePaseo`、`useRpc`、`useSettings` 和数据 hook |
|
||
| `@tanstack/react-query` | 请求状态和缓存 |
|
||
| `react` | 组件和 hook |
|
||
| `react/jsx-runtime` | 编译后的 JSX |
|
||
| `react-native` | 跨平台 UI |
|
||
| `zod` | 共享 schema |
|
||
|
||
宿主拥有与之配套的 React 和渲染器版本。SDK 的 React peer 范围允许补丁版本差异，以便工具链和 Node 使用者使用；它不会改变应用固定的 React 版本，也不保证与其他宿主的渲染器兼容。
|
||
|
||
这些确切的模块标识符使用宿主的运行时实例。请求其他宿主模块的客户端包会以 `Module "<name>" is not available in plugin client code` 失败。
|
||
|
||
不要导入 `lucide-react-native`、`react-native-svg` 或 DOM 库。把贡献的 `icon` 字段设为一个 [Lucide 图标名称](https://lucide.dev/icons/)、内联 SVG 或组件；Paseo 会校验图标并渲染它。参见[图标](#icons)。
|
||
|
||
### 跨平台规则 {#cross-platform-rules}
|
||
|
||
客户端代码通过 React Native Web 在 iOS、Android 和浏览器中运行。在浏览器中正常、在手机上崩溃的组件是最常见的插件 bug。规则如下：
|
||
|
||
| 应该 | 不应该 |
|
||
| ------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
|
||
| 使用 `react-native` 中的 `View`、`Text`、`Pressable`、`ScrollView`、`TextInput` | 使用 `<div>`、`<span>`、`<button>` 或任何 HTML 元素 |
|
||
| 使用由 `theme.colors` 和 `layout.compact` 构建的 `style` 对象 | 使用 `className`、CSS 字符串或写死的颜色 |
|
||
| 使用 `onPress` | 使用 `onClick`、`onMouseEnter` 或其他 DOM 处理函数 |
|
||
| 使用 `Linking`、`Clipboard` 之类的 React Native API | 在组件中使用 `window`、`document`、`localStorage`、`navigator`、`location` |
|
||
|
||
脚手架的 `tsconfig.json` 省略了 DOM 库。请让跨平台组件远离 DOM 全局对象；不要添加 `/// <reference lib="dom" />`，也不要在 `lib` 中加入 `"DOM"`。`layout.platform` 携带与 React Native 的 `Platform.OS` 相同的值，用于渲染决策。
|
||
|
||
### 播放音频 {#play-audio}
|
||
|
||
调用 `client.playAudio({ base64, mimeType }): Promise<void>` 在当前客户端（浏览器、Electron、iOS 或 Android）上播放音频文件。传入插件 RPC 返回的 base64 文件即可；不需要浏览器全局对象或平台检查。
|
||
|
||
```ts
|
||
const audio = await client.rpc(renderSpeech, { text: "Your agent needs you" });
|
||
// renderSpeech returns { base64: string, mimeType: "audio/wav" }.
|
||
await client.playAudio(audio);
|
||
```
|
||
|
||
promise 在播放结束时 resolve，在文件无效、播放失败或插件卸载时 reject。调用共享 Paseo 的语音播放队列，并按顺序播放。卸载插件会取消它正在播放和排队中的音频。语音播放控件也可以中断这个共享队列。播放不会请求麦克风权限。
|
||
|
||
为了可移植性，请使用 PCM WAV 或 MP3 文件。其他编解码格式取决于客户端的解码器。接受 MIME 参数。请传入完整的音频文件；不支持原始 PCM 采样。浏览器要求用户交互后才允许播放声音；请处理 reject 并提供一个播放按钮。该函数在运行插件客户端的设备上播放，而不是在 daemon 上，并且不保证应用被挂起或关闭时仍能播放。
|
||
|
||
### 外部链接和工作区浏览器 {#external-links-and-workspace-browsers}
|
||
|
||
使用 `ExternalLink` 在 Paseo 之外打开文档：
|
||
|
||
```tsx
|
||
import { ExternalLink } from "@getpaseo/plugin/client/ui";
|
||
|
||
export function DocumentationLink() {
|
||
return <ExternalLink href="https://paseo.sh/docs">Open documentation</ExternalLink>;
|
||
}
|
||
```
|
||
|
||
该组件具有无障碍的链接语义，并使用与 `openExternalUrl(url: string): Promise<void>` 相同的打开方式：
|
||
|
||
```ts
|
||
import { openExternalUrl } from "@getpaseo/plugin/client";
|
||
|
||
export async function openDocumentation() {
|
||
await openExternalUrl("https://paseo.sh/docs");
|
||
}
|
||
```
|
||
|
||
请直接在用户交互中调用该函数，以便浏览器允许打开新标签页。
|
||
|
||
| 平台 | 外部链接 | `navigation.openBrowser` |
|
||
| ------------- | ----------------------------------- | ------------------------------------ |
|
||
| Electron | 系统浏览器 | 可用；创建一个本地工作区浏览器标签页 |
|
||
| 浏览器 Web | 带 `noopener,noreferrer` 的新标签页 | `undefined` |
|
||
| iOS / Android | 操作系统的 URL 处理程序 | `undefined` |
|
||
|
||
#### ExternalLink 属性 {#externallink-props}
|
||
|
||
| 属性 | 是否必填 | 行为 / 默认值 |
|
||
| ------------------------------- | -------- | ---------------------------------- |
|
||
| `href: string` | 是 | 绝对的 HTTP(S) 目标地址 |
|
||
| `children: ReactNode` | 是 | 链接文本或内联的 React Native 内容 |
|
||
| `accessibilityLabel: string` | 否 | 覆盖从内容推导出的无障碍名称 |
|
||
| `testID: string` | 否 | 测试标识符；默认不设置 |
|
||
| `onError(error: unknown): void` | 否 | 接收打开时的错误；默认记录到日志 |
|
||
|
||
#### 打开工作区浏览器 {#open-a-workspace-browser}
|
||
|
||
在界面或面板中使用 `navigation.openBrowser`。渲染该操作之前先检查它是否可用。下面这个工作区面板在其他平台上改用外部链接：
|
||
|
||
```tsx
|
||
import type { PluginWorkspacePanelProps } from "@getpaseo/plugin/client";
|
||
import { ExternalLink } from "@getpaseo/plugin/client/ui";
|
||
import { Pressable, Text } from "react-native";
|
||
|
||
export function DocumentationPanel({ navigation, workspaceId, theme }: PluginWorkspacePanelProps) {
|
||
const openBrowser = navigation?.openBrowser;
|
||
const url = "https://paseo.sh/docs";
|
||
|
||
if (!openBrowser) {
|
||
return <ExternalLink href={url}>Open documentation</ExternalLink>;
|
||
}
|
||
|
||
return (
|
||
<Pressable accessibilityRole="button" onPress={() => openBrowser({ url, workspaceId })}>
|
||
<Text style={{ color: theme.colors.foreground }}>Open in workspace browser</Text>
|
||
</Pressable>
|
||
);
|
||
}
|
||
```
|
||
|
||
`navigation.openBrowser({ url, workspaceId, serverId? }): void` 会创建并聚焦一个新标签页。它从不会自动退回到外部打开。
|
||
|
||
| 选项 | 是否必填 | 行为 / 默认值 |
|
||
| --------------------- | -------- | ---------------------------------------- |
|
||
| `url: string` | 是 | 绝对的 HTTP(S) 目标地址 |
|
||
| `workspaceId: string` | 是 | 已存在于目标主机应用工作区列表中的工作区 |
|
||
| `serverId: string` | 否 | 默认为界面或面板所选的主机 |
|
||
|
||
要以另一台主机为目标，请传入它的 ID 以及该主机的工作区 ID：
|
||
|
||
```ts
|
||
openBrowser({ url, workspaceId: remoteWorkspaceId, serverId: remoteServerId });
|
||
```
|
||
|
||
`serverId` 选择工作区的所有者。页面运行在你本地的桌面上，即使是远程工作区也是如此；`localhost` URL 指的是该桌面。
|
||
|
||
#### 错误与拒绝 {#errors-and-refusal}
|
||
|
||
| 条件 | 结果 |
|
||
| ------------------------------------------------ | ---------------------------------------------------------------------- |
|
||
| 外部 URL 格式错误或使用非 HTTP(S) 协议 | 被忽略；`openExternalUrl` resolve，但不会打开任何内容 |
|
||
| 操作系统打开失败 | `openExternalUrl` reject；`ExternalLink` 调用 `onError` 或记录错误 |
|
||
| 浏览器拦截了新的外部标签页 | 无法与成功的 `noopener` 打开区分 |
|
||
| 应用内浏览器的 URL 格式错误或使用非 HTTP(S) 协议 | 在创建标签页之前抛出 `Only absolute HTTP(S) URLs are supported.` |
|
||
| 应用内浏览器的工作区 ID 为空 | 在创建标签页之前抛出 `workspaceId is required.` |
|
||
| 目标主机/工作区未知，或其工作区列表尚未加载 | 在创建标签页之前抛出 `Workspace is unavailable on the requested host.` |
|
||
|
||
跨客户端的、带类型的主机范围持久化请使用[设置 API](#settings-screens)。打开你自己注册的贡献请使用 `openSettings`、`openScreen` 和 `openPanel`。
|
||
|
||
### 服务端运行时 {#server-runtime}
|
||
|
||
Paseo 为服务端代码提供 `@getpaseo/plugin`、`@getpaseo/plugin/server`、`@getpaseo/plugin/server/provider`、`@getpaseo/plugin/server/acp` 和 `zod`。后端贡献在 daemon 子进程中运行，可以通过 Node 访问宿主机器。请把文件系统、进程、凭据以及其他本机工作放在 `server/` 下。没有 `index.server.ts` 的插件不会启动子进程。
|
||
|
||
### Provider {#providers}
|
||
|
||
直接实现和 ACP 实现、会话生命周期、Composer 设置、时间线渲染器、测试和分发，见[构建 Provider 插件](/docs/plugins/providers)。
|
||
|
||
使用来自 `@getpaseo/plugin/server/provider` 的 `ProviderRegistration` 调用 `server.registerProvider()`。它的连接通过 `send()` 接收输入，并通过 `onEvent()` 发出完整的状态快照。`send()` 只报告是否接受；提示词的处理结果、轮次、配置、持久化、权限和失败都是事件。
|
||
|
||
消息、结构化命令、引导和命令副作用都使用同一个 `session.prompt` 输入。在实时的用户时间线条目上重复 `clientMessageId`，并恰好发布一个与之匹配的 `session.prompt_result`。把 Provider 创建的子会话发布为带有 `parentSessionId` 的会话。
|
||
|
||
Provider 设置是 Paseo 在 Composer 中渲染的开关/选择描述符。把 Provider 私有的选项保留在 `session.open` 的 `ProviderSessionConfig.providerOptions` 中。这个记录包含配置的默认值和针对单个 Agent 的覆盖值；请在你的 Provider 中校验并应用它。配置和合并语义见 [Provider 选项](/docs/sdk/provider-options)。宿主工具以 MCP 服务器的形式出现在完整的会话配置中。
|
||
|
||
Paseo 刷新 Agent 的方式是关闭它当前的 Provider 会话，再用当前的配置和持久化值打开它。Provider 在 `session.open` 期间重新读取外部状态。
|
||
|
||
使用 `@getpaseo/plugin/server/acp` 中的 `runAcpProvider()` 适配一个基于命令的 ACP。只针对厂商在发现、配置、通知或工具调用方面的差异添加转换器钩子。
|
||
|
||
`ProviderRegistration.icon` 是相对于插件目录的文件路径，例如 `icon.svg`。它必须解析到该目录内一个遵循 [SVG 图标规则](#svg-rules)的普通文件。Paseo 在插件启动时读取并校验该文件；这个字符串从不是内联 SVG 或 URL。
|
||
|
||
### 用量来源 {#usage-sources}
|
||
|
||
**需要 Paseo 0.11**。在服务端入口中用 `server.registerUsageSource()` 注册一个来源。从 `@getpaseo/plugin/server/usage` 导入它的契约和辅助函数。
|
||
|
||
一个来源实现两个调用：
|
||
|
||
```ts
|
||
interface UsageAccount {
|
||
key: string;
|
||
label?: string;
|
||
harness?: string;
|
||
input: JsonValue;
|
||
}
|
||
|
||
type UsageScope =
|
||
| { kind: "global" }
|
||
| { kind: "session"; provider: string; model?: string; env: Record<string, string> };
|
||
|
||
interface UsageSourceRegistration {
|
||
id: string;
|
||
label: string;
|
||
icon?: string;
|
||
input: ZodType;
|
||
discover(scope: UsageScope): Promise<UsageAccount[]>;
|
||
fetch(input: unknown): Promise<UsageReport>;
|
||
}
|
||
|
||
type UsageReport =
|
||
| {
|
||
status: "available";
|
||
planLabel?: string;
|
||
windows: UsageWindow[];
|
||
balances?: UsageBalance[];
|
||
details?: UsageDetail[];
|
||
}
|
||
| { status: "unavailable"; problem: UsageProblem }
|
||
| { status: "error"; error: string };
|
||
|
||
type UsageProblem =
|
||
| { kind: "expired"; expiresAt: string; refreshedBy?: string }
|
||
| { kind: "rejected"; status: number; refreshedBy?: string }
|
||
| { kind: "no_quota"; detail: string };
|
||
```
|
||
|
||
会话发现只返回该 Agent 运行时使用的那个登录。Agent 弹出框只使用这些输入；它从不尝试来自全局发现或其他 Agent 的登录。对于其他任何 Provider，返回 `[]`。全局发现会列出每个账号，包括已过期的登录。
|
||
|
||
从会话的启动环境中解析会话账号。没有登录时返回 `[]`。不要在会话发现中扫描默认存储，也不要在全局发现中扫描 Agent。发现是一种查询，没有 Agent 生命周期钩子。已关闭的 Agent 在恢复之前没有会话范围。
|
||
|
||
输入指定凭据存储的位置；不要把凭据放进输入或报告中。Paseo 在调用 `fetch()` 之前会按你的 schema 校验每个输入。在任何范围内，相同的键就是同一份报告；只有当有序的登录输入一致时，获取才会共享五分钟的缓存。每次登录获取有 20 秒的截止时间。
|
||
|
||
内置的会话路由：
|
||
|
||
| 来源 | 会话 | 登录存储 |
|
||
| ------------ | ---------------------------------------------- | ---------------------------------------------------------------------------- |
|
||
| Claude | `claude` | `CLAUDE_CONFIG_DIR` 或默认位置；在 macOS 上，该目录对应的钥匙串条目优先 |
|
||
| Claude | 使用 `anthropic/…` 模型的 `pi`、`omp` | 该运行环境的 Anthropic 登录存储 |
|
||
| Codex | `codex` | `CODEX_HOME/auth.json` 或默认位置 |
|
||
| Codex | 使用 `openai/…` 模型的 `pi`、`opencode`、`omp` | 该运行环境的 OpenAI 登录存储 |
|
||
| Cursor | `cursor` | 该会话的 `XDG_CONFIG_HOME`、`APPDATA` 或主目录下 cursor-agent 的 `auth.json` |
|
||
| Muse | `muse` | 该会话自己的 Muse 启动配置 |
|
||
| 其他内置来源 | 任意 | 无会话发现 |
|
||
|
||
Claude 会排除 Bedrock、Vertex 以及使用其他 `ANTHROPIC_BASE_URL` 的会话。Codex 会排除设置了 `OPENAI_BASE_URL` 的会话。Cursor 会排除通过 `CURSOR_API_KEY` 或 `CURSOR_AUTH_TOKEN` 验证的会话，以及在 macOS 上把登录保存在钥匙串中的会话（除非设置了 `AGENT_CLI_CREDENTIAL_STORE=file`，否则这是默认行为）。
|
||
|
||
使用稳定的账号键：由 `[A-Za-z0-9._-]` 中的字符组成，长度为 1–128。它标识被计量配额的账号或组织，并且在 token 轮换后保持不变。不要把凭据或原始邮箱地址用作键。对于敏感的稳定身份，请使用 `hashAccountKey()`；当账号元数据不可用时，使用存储位置标识。标签可以为账号命名，但不会成为账号的身份。
|
||
|
||
按优先顺序返回登录，并把 `harness` 设为所属运行环境的显示名称，例如 Codex、OpenCode、Pi 或 OMP。daemon 把输入视为不透明的值，从不从中推导标签。
|
||
|
||
主机范围的 Usage 弹窗会把键相同的登录归为一张账号卡片，并发尝试它们，在选择结果时优先考虑发现的顺序。如果任一登录返回 `available`，就显示用量且没有错误。如果全部失败，就把每个登录的错误分行显示，并附上它的运行环境标签和各自的解决方法。发现失败会由 daemon 记录到日志，并且不会产生卡片。
|
||
|
||
时间窗口的名称必须来自 Provider 的数据：显式的时长、具名的 API 字段（例如 `five_hour` 或 `weekly`），或 Provider 自己的周期名称。响应中的位置和重置倒计时并不能确定时长。当 Provider 省略时长时，请使用 “Rolling” 或 “Primary limit” 之类的中性名称，并在适配器旁说明缺失的元数据。
|
||
|
||
对于数值形式的时长，请使用 `@getpaseo/plugin/server/usage` 中的 `windowFromReportedDuration()`（Paseo 0.11+）。传入报告的秒数或 `null`、一个中性的 `unknown` 标识和名称，以及可选的稳定配额 `scope`。该辅助函数会一并推导出 ID、标签和短标签；它不接受对时长标签的覆盖。对于具名的 API 周期，请使用 `windowFromUsedPct()`，并采用该字段所支持的名称。
|
||
|
||
窗口 ID 标识的是配额范围和周期，而不是它在响应中的位置、使用率或重置时刻。对于特定于模型的配额，请以 Provider 稳定的功能 ID 作为范围；没有 ID 时退回到报告的限额名称。在位置移动和显示名称变化时保持 ID 不变。不要把旧的、有歧义的 ID 映射到另一个周期：已保存的固定项会在所有账号中按来源和窗口 ID 匹配，因此用户必须重新选择修正后的窗口。
|
||
|
||
在用户自定义固定项之前，`summary: true` 会选择来源的默认值。应用会为卡片、侧边栏和开关计算出同一个生效的选择。第一次编辑会把这些默认值保存为快照；显式的空选择会保持为空。
|
||
|
||
请在 `fetch()` 中重新读取所选的存储，让 CLI 的 token 轮换生效。不要兑换 refresh token，也不要写入凭据存储：在别处刷新可能会使 CLI 的副本失效，而重写解析过的文件可能会丢弃你没有建模的字段。如果存储在发现之后消失了，请抛出错误；卡片会显示该错误，直到下一次发现将其移除。
|
||
|
||
使用 `unavailable(problem)` 说明为什么某个已有的登录无法提供配额。它需要一个 problem；没有不带参数的形式。`expiresAt` 是 ISO 时间戳。被拒绝的登录会携带上游的 HTTP 状态码。`refreshedBy` 是一个 CLI 名称，例如 `claude`、`codex`、`opencode`、`omp` 或 `pi`。解决方法的句子由 Paseo 负责。不要在该字段中放入说明或面向用户的句子。对于 `no_quota`，`detail` 会原样显示。
|
||
|
||
```ts
|
||
import { z } from "zod";
|
||
import type { PluginServerContext } from "@getpaseo/plugin/server";
|
||
import { hashAccountKey, unavailable } from "@getpaseo/plugin/server/usage";
|
||
import { findLoginStores, readLogin, readQuota } from "./server/logins";
|
||
|
||
const input = z.object({ path: z.string() }).strict();
|
||
|
||
export default function contribute(server: PluginServerContext) {
|
||
server.registerUsageSource({
|
||
id: "example-usage",
|
||
label: "Example",
|
||
icon: "icon.svg",
|
||
input,
|
||
discover: async () =>
|
||
(await findLoginStores()).map((path) => ({
|
||
key: hashAccountKey(path),
|
||
input: { path },
|
||
})),
|
||
fetch: async (value) => {
|
||
const { path } = input.parse(value);
|
||
const login = await readLogin(path);
|
||
if (login.expiresAt <= Date.now())
|
||
return unavailable({
|
||
kind: "expired",
|
||
expiresAt: new Date(login.expiresAt).toISOString(),
|
||
refreshedBy: "example",
|
||
});
|
||
return readQuota(login);
|
||
},
|
||
});
|
||
return () => {};
|
||
}
|
||
```
|
||
|
||
内置的 Claude 发现优先使用 macOS 钥匙串中的登录，只有当钥匙串为空时才使用 Claude Code 的凭据文件。`CLAUDE_CONFIG_DIR` 选择该文件所在的目录。新的 token 使用 OAuth 资料中的账号和组织 ID；已过期或被拒绝的资料使用存储位置的哈希。Codex 依次优先使用 Codex CLI、OpenCode、Pi 和 OMP，并按保存的元数据或 JWT 声明中的 ChatGPT 账号 ID 分组。Pi 和 OMP 的登录在过期后仍可被发现。OMP 需要 `node:sqlite`。
|
||
|
||
不带 ID 调用 `usage.list_reports` 时会发现账号。带 ID 调用时，它会刷新已知的账号，而不重新发现身份。如果某个存储切换了账号，现有卡片会显示新登录的配额，直到下一次发现。报告会缓存五分钟；`forceRefresh` 会绕过缓存。条目携带 `id`、`account.label` 和 `fetchedAt`。失败的账号还会携带可选的 `loginErrors` 条目，其中包含 `harness` 和每个登录失败的 `report`。客户端通过 `server_info.features.usageSources` 判断是否启用此功能。较旧的 `provider.usage.list` RPC 会为 0.10 客户端映射同样的报告，并把问题渲染到它的 `error` 字符串中。
|
||
|
||
来源图标是一个文件路径，规则与 Provider 图标相同。
|
||
|
||
## 入口与清理 {#entry-point-and-cleanup}
|
||
|
||
每个存在的入口都默认导出一个贡献函数，并返回清理函数。客户端入口接收 `PluginClientContext`；服务端入口接收 `PluginServerContext`。客户端注册方法返回幂等的移除函数，但标题栏按钮和 Composer 标签除外，它们返回 `{ update, remove }` 句柄。入口的清理函数会在 Paseo 移除剩余的注册之前运行。
|
||
|
||
```ts
|
||
import type { PluginClientContext } from "@getpaseo/plugin/client";
|
||
import { Main } from "./client/main";
|
||
|
||
export default function contribute(client: PluginClientContext) {
|
||
client.addScreen({ id: "main", title: "My plugin", Component: Main });
|
||
return () => {};
|
||
}
|
||
```
|
||
|
||
清理函数可以是异步的。请释放插件创建的计时器、监听器、套接字和其他资源。在重新加载、停用、移除、断开连接或 daemon 关闭时，Paseo 还会移除注册、卸载界面、reject 待处理的 RPC、关闭插件的 daemon 会话并停止它的子进程。
|
||
|
||
## 生命周期钩子 {#lifecycle-hooks}
|
||
|
||
在 `index.server.ts` 中：
|
||
|
||
```ts
|
||
import type { PluginServerContext } from "@getpaseo/plugin/server";
|
||
|
||
export default function contribute(server: PluginServerContext) {
|
||
server.on("agent.turn_ended", (event) => {
|
||
console.log(event.agent.id, event.outcome);
|
||
});
|
||
|
||
return () => {};
|
||
}
|
||
```
|
||
|
||
| 注册 | 回调接收 | 返回 |
|
||
| ------------------------------- | ---------------------------------- | --------------------------------------------------- |
|
||
| `server.on(name, callback)` | `(event, { paseo, signal })` | `void` 或 `Promise<void>` |
|
||
| `server.before(name, callback)` | `({ request }, { paseo, signal })` | 修改后的请求，或返回 `undefined` 保持不变；支持异步 |
|
||
|
||
只要插件处于启用状态，钩子就会在 daemon 上运行，即使没有应用连接。
|
||
|
||
### 修改配置并注入 MCP 服务器 {#change-configuration-and-inject-an-mcp-server}
|
||
|
||
在 `contribute(server)` 中添加这个回调。把占位 URL 替换为你的 MCP 端点。
|
||
|
||
```ts
|
||
server.before("agent.create", ({ request }) => {
|
||
if (request.config.provider !== "codex") {
|
||
return request;
|
||
}
|
||
|
||
return {
|
||
...request,
|
||
config: {
|
||
...request.config,
|
||
providerOptions: {
|
||
...request.config.providerOptions,
|
||
sandbox_mode: "workspace-write",
|
||
approval_policy: "on-request",
|
||
},
|
||
mcpServers: {
|
||
...request.config.mcpServers,
|
||
company: {
|
||
type: "http",
|
||
url: "https://tools.example.com/mcp",
|
||
},
|
||
},
|
||
},
|
||
};
|
||
});
|
||
```
|
||
|
||
| 输入 | 结果 |
|
||
| ------------------------------------------- | ------------------- |
|
||
| `providerOptions.sandbox_mode: "read-only"` | `"workspace-write"` |
|
||
| `providerOptions.web_search: "disabled"` | 由展开运算保留 |
|
||
| 已有的 `mcpServers.search` | 由展开运算保留 |
|
||
| 已有的 `mcpServers.company` | 被替换为上面的条目 |
|
||
|
||
所选的 Provider 会校验 `providerOptions`，并且必须支持配置的 MCP 服务器。显式的 Codex 沙盒和批准选项会覆盖它的模式预设。
|
||
|
||
### 在每次打开会话时注入环境变量 {#inject-environment-variables-on-every-session-opening}
|
||
|
||
```ts
|
||
server.before("agent.session_open", ({ request }) => {
|
||
return {
|
||
...request,
|
||
env: {
|
||
...request.env,
|
||
COMPANY_ENV: "development",
|
||
},
|
||
};
|
||
});
|
||
```
|
||
|
||
它会在创建、恢复、刷新和导入时运行。如果只想在创建时注入，请改为在 `agent.create` 回调中设置 `env`。
|
||
|
||
### 选择工作区隔离方式 {#choose-workspace-isolation}
|
||
|
||
```ts
|
||
server.before("workspace.create", ({ request }) => {
|
||
if (request.source.kind !== "directory") {
|
||
return request;
|
||
}
|
||
|
||
return {
|
||
...request,
|
||
source: {
|
||
kind: "worktree",
|
||
cwd: request.source.path,
|
||
action: "branch-off",
|
||
},
|
||
};
|
||
});
|
||
```
|
||
|
||
**结果**：显式的目录创建请求会变成 worktree 请求。已有的工作区以及目录查找/导入操作不受影响。
|
||
|
||
### 在轮次结束时发送后续消息 {#send-a-follow-up-when-a-turn-ends}
|
||
|
||
把 [server/inspect.ts](https://github.com/getpaseo/paseo/blob/main/plugin-examples/lifecycle-actions/server/inspect.ts) 复制到你的插件中。该辅助文件从 `@getpaseo/protocol/agent-types` 导入类型；请把与插件 SDK 版本相同的 `@getpaseo/protocol` 加入开发依赖，并在加载插件之前安装它们。`latestOutputText` 会拼接最近一条用户消息之后的文本片段。
|
||
|
||
```ts
|
||
import type { PluginServerContext } from "@getpaseo/plugin/server";
|
||
import { latestOutputText } from "./server/inspect";
|
||
|
||
export default function contribute(server: PluginServerContext) {
|
||
server.on("agent.turn_ended", async (event, context) => {
|
||
if (event.outcome.kind === "canceled") {
|
||
return;
|
||
}
|
||
|
||
const agent = context.paseo.agents.ref(event.agent.id);
|
||
const page = await agent.timeline.refetch({ direction: "tail", limit: 20 });
|
||
const text = latestOutputText(page.entries.map(({ item }) => item));
|
||
if (/out of credits/i.test(text)) {
|
||
await agent.send("Try again.");
|
||
}
|
||
});
|
||
|
||
return () => {};
|
||
}
|
||
```
|
||
|
||
```text
|
||
Turn ends: "out of credits"
|
||
→ plugin sends "Try again."
|
||
→ a new turn starts
|
||
```
|
||
|
||
该处理函数只获取最近 20 条时间线条目，不检查这一页之前的输出。插件需要更多历史时，请用 `cursor` 和 `direction` 继续翻页。
|
||
|
||
这会用现有的 SDK 发送一条新消息。持续匹配会不断发送后续消息；需要时请在插件中添加次数限制或延迟。附件和工具的效果不会被重放。
|
||
|
||
### 回应权限请求 {#answer-a-permission-request}
|
||
|
||
使用同一个[辅助文件](https://github.com/getpaseo/paseo/blob/main/plugin-examples/lifecycle-actions/server/inspect.ts)中的 `shellCommand`：
|
||
|
||
```ts
|
||
import type { PluginServerContext } from "@getpaseo/plugin/server";
|
||
import { shellCommand } from "./server/inspect";
|
||
|
||
export default function contribute(server: PluginServerContext) {
|
||
server.on("agent.permission_requested", async (event, context) => {
|
||
const command = shellCommand(event.request);
|
||
if (command === null) {
|
||
return;
|
||
}
|
||
|
||
const agent = context.paseo.agents.ref(event.agent.id);
|
||
if (/\brm\s+-rf\b/.test(command)) {
|
||
await agent.respondToPermission({
|
||
requestId: event.request.id,
|
||
response: { behavior: "deny", message: "Recursive deletion is blocked." },
|
||
});
|
||
return;
|
||
}
|
||
|
||
if (command.trim() === "git status") {
|
||
await agent.respondToPermission({
|
||
requestId: event.request.id,
|
||
response: { behavior: "allow" },
|
||
});
|
||
}
|
||
});
|
||
|
||
return () => {};
|
||
}
|
||
```
|
||
|
||
| 请求 | 结果 |
|
||
| ---------------- | -------------------- |
|
||
| `rm -rf build` | 拒绝 |
|
||
| `git status` | 批准 |
|
||
| 其他命令或请求 | 保持待处理，留给用户 |
|
||
| 已经处理过的请求 | SDK 响应失败 |
|
||
|
||
这个正则表达式只是一个示例策略，而不是 shell 解析器。权限请求也可能是问题、计划和模式变更；请求权限不会结束当前轮次。
|
||
|
||
### 事件 {#events}
|
||
|
||
| 名称 | 事件字段 | 触发时机 |
|
||
| ---------------------------- | ----------------------------------------------------- | ----------------------------- |
|
||
| `agent.created` | `agent` | 普通创建完成；不包括导入/恢复 |
|
||
| `agent.closed` | `agent` | 一个运行中的 Agent 运行时关闭 |
|
||
| `agent.turn_started` | `agent`, `turnId` | 实时轮次开始 |
|
||
| `agent.turn_ended` | `agent`, `turnId`, `outcome`, 已弃用的 `timeline: []` | 实时轮次完成、失败或被取消 |
|
||
| `agent.permission_requested` | `agent`, `request` | 权限请求或问题进入待处理状态 |
|
||
| `agent.permission_resolved` | `agent`, `requestId`, `resolution` | 待处理的请求得到回应或被清除 |
|
||
| `agent.archived` | `agent`, `archivedAt` | 归档状态已保存 |
|
||
| `workspace.created` | `workspace` | 记录已创建；目录可用 |
|
||
| `workspace.archived` | `workspace` | 归档状态已保存 |
|
||
|
||
Agent 事件不包括 daemon 私有的一次性辅助 Agent。公开的后台工作区及其普通 Agent 与其他工作区运行相同的生命周期钩子。归档事件可能早于运行时/worktree 清理；当清理很重要时，请单独观察生命周期何时完成。
|
||
|
||
`agent.turn_ended.timeline` 已弃用，并且始终为空。需要历史时，请用 `context.paseo.agents.ref(event.agent.id).timeline.refetch({ direction: "tail", limit: 20 })` 按需获取。钩子负载的大小不会随对话历史增长。
|
||
|
||
**共享的负载结构**（`@getpaseo/plugin/server`）：
|
||
|
||
```ts
|
||
interface PluginHookAgent {
|
||
id: string;
|
||
workspaceId: string | null;
|
||
parentAgentId: string | null;
|
||
provider: string;
|
||
cwd: string;
|
||
title: string | null;
|
||
}
|
||
|
||
interface PluginHookWorkspace {
|
||
id: string;
|
||
projectId: string;
|
||
cwd: string;
|
||
name: string | null;
|
||
archivedAt: string | null;
|
||
}
|
||
|
||
type PluginTurnOutcome =
|
||
| { kind: "completed" }
|
||
| { kind: "failed"; error: { message: string; code?: string } }
|
||
| { kind: "canceled"; reason: string };
|
||
```
|
||
|
||
| 字段 | 结构 / 含义 |
|
||
| ------------ | ---------------------------------------------------------------------------------------- |
|
||
| `turnId` | Provider 报告的 `string` 或 `null`；会话重新打开后可能重复 |
|
||
| `timeline` | `readonly AgentTimelineItem[]`；包含之前对话的完整快照；文本可能跨越多个条目 |
|
||
| `request` | SDK 的 `AgentPermissionRequest`；`kind` 为 `tool`、`plan`、`question`、`mode` 或 `other` |
|
||
| `resolution` | SDK 的 `AgentPermissionResponse` |
|
||
| `archivedAt` | 时间戳字符串 |
|
||
|
||
### before 钩子 {#before-hooks}
|
||
|
||
| 名称 | 请求字段 | 可编辑 |
|
||
| -------------------- | ----------------------------------------------------------------------- | ----------------------------------- |
|
||
| `agent.create` | `config`，可选的 `env` | 除 `cwd` 外的公开 Agent 配置；`env` |
|
||
| `agent.session_open` | `agentId`, `workspaceId`, `provider`, `cwd`, `reason`, `purpose`, `env` | 仅 `env` |
|
||
| `workspace.create` | `source`，可选的 `title`，`firstAgentContext` | 整个显式创建请求 |
|
||
|
||
**`agent.create.config`** 使用 `AgentSessionConfig`：
|
||
|
||
| 字段 | 约束 |
|
||
| --------------------------------------------- | -------------------------------------------------------- |
|
||
| `provider`, `model` | 独立的字段；修改 Provider 可能需要同时修改模型/模式/选项 |
|
||
| `modeId`, `thinkingOptionId`, `featureValues` | 特定于 Provider 的选择 |
|
||
| `title`, `systemPrompt` | Agent 配置 |
|
||
| `providerOptions` | 不透明的、特定于 Provider 的选项 |
|
||
| `mcpServers`, `toolPolicy` | MCP 配置和精确的工具预批准 |
|
||
| `cwd` | 不能修改 |
|
||
|
||
**`agent.session_open` 请求示例：**
|
||
|
||
```json
|
||
{
|
||
"agentId": "agent-123",
|
||
"workspaceId": "workspace-456",
|
||
"provider": "codex",
|
||
"cwd": "/projects/shop",
|
||
"reason": "resume",
|
||
"purpose": "interactive",
|
||
"env": { "COMPANY_ENV": "development" }
|
||
}
|
||
```
|
||
|
||
| 字段 | 取值 |
|
||
| ------------- | ------------------------------------------------------------------------------------ |
|
||
| `workspaceId` | 字符串或 `null` |
|
||
| `reason` | `create`、`resume`、`refresh`、`import` |
|
||
| `purpose` | `interactive`、`history` |
|
||
| `env` | 启动覆盖映射；不包括 daemon 继承的环境变量。替换整个映射即可添加、替换或移除覆盖项。 |
|
||
|
||
### 顺序与返回值 {#ordering-and-returned-values}
|
||
|
||
```text
|
||
Creation request
|
||
→ agent.create hooks (plugin-ID order; registration order within each plugin)
|
||
→ resolve defaults and validate provider configuration
|
||
→ derive launch configuration with Paseo runtime tools and daemon prompt
|
||
→ agent.session_open hooks (same ordering; env only)
|
||
→ set PASEO_AGENT_ID and PASEO_AGENT_CWD
|
||
→ open provider session and save agent configuration
|
||
```
|
||
|
||
| 回调返回 | 下一个回调收到 |
|
||
| ------------------------------------------------------- | --------------------------------- |
|
||
| `{ ...request, env: { ...request.env, REGION: "eu" } }` | 之前的请求，添加或替换了 `REGION` |
|
||
| `{ ...request, env: { REGION: "eu" } }` | 之前的请求，整个覆盖映射被替换 |
|
||
| `undefined` | 未改变的请求 |
|
||
| 抛出错误或返回无效数据 | 操作失败；后面的回调不会运行 |
|
||
|
||
没有自动的深度合并。后面的回调可以覆盖前面的值。Agent 配置会被保存；环境变量覆盖项不会随之持久化。
|
||
|
||
### context 与清理 {#context-and-cleanup}
|
||
|
||
| 契约 | 行为 |
|
||
| -------------------------- | ----------------------------------------------------------------------------------- |
|
||
| `context.paseo` | 已连接到此 daemon 的现有 SDK |
|
||
| `context.signal` | 在调用超时或插件停止时中止；请把它传给外部请求 |
|
||
| 输入数据 | 分离的快照；通过返回的请求或 SDK 命令改变状态 |
|
||
| 注册结果 | 幂等的移除函数，例如 `const remove = server.on(...); remove();` |
|
||
| 重新加载、停用、移除、关闭 | 移除剩余的注册 |
|
||
| 未知的钩子名称 | 注册失败 |
|
||
| 钩子超时 | 30 秒；会中止 signal。before 钩子会让待处理的操作失败；事件处理函数会记录一条错误。 |
|
||
| 事件处理函数出错 | 记录在插件名下；原操作继续进行 |
|
||
| 事件投递 | 实时、尽力而为；没有重放、持久化或自动重试 |
|
||
| 事件并发 | 不同的事件可能重叠；不保证回调完成的顺序 |
|
||
|
||
### 完整示例 {#complete-examples}
|
||
|
||
| 插件 | 包含 |
|
||
| ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------ |
|
||
| [lifecycle-logger](https://github.com/getpaseo/paseo/tree/main/plugin-examples/lifecycle-logger) | 全部十一个钩子；隐去环境变量值的 JSON 日志 |
|
||
| [lifecycle-actions](https://github.com/getpaseo/paseo/tree/main/plugin-examples/lifecycle-actions) | 后续消息、权限、环境变量、切换 Provider、选择 worktree |
|
||
| [agent-configuration](https://github.com/getpaseo/paseo/tree/main/plugin-examples/agent-configuration) | MCP 注入以及 Codex 沙盒/批准选项 |
|
||
|
||
用 `paseo plugin logs lifecycle-logger` 或主机的 `daemon.log` 读取 logger 的输出。
|
||
|
||
## 界面和侧边栏项 {#screens-and-sidebar-items}
|
||
|
||
界面是一整页的插件 UI。侧边栏项是 Paseo 在侧边栏顶部或底部渲染的组件；按下它时做什么由它决定。先注册界面，再注册一个打开它的项：
|
||
|
||
`client/main.tsx`：
|
||
|
||
```tsx
|
||
import type { PluginScreenProps } from "@getpaseo/plugin/client";
|
||
import { useMemo } from "react";
|
||
import { Text, View } from "react-native";
|
||
|
||
export function Main({ theme, host, layout }: PluginScreenProps) {
|
||
const styles = useMemo(
|
||
() => ({
|
||
screen: {
|
||
flex: 1,
|
||
padding: layout.compact ? 16 : 24,
|
||
backgroundColor: theme.colors.surface0,
|
||
},
|
||
title: { color: theme.colors.foreground },
|
||
detail: { color: theme.colors.foregroundMuted },
|
||
}),
|
||
[theme, layout.compact],
|
||
);
|
||
return (
|
||
<View style={styles.screen}>
|
||
<Text style={styles.title}>{host.label}</Text>
|
||
<Text style={styles.detail}>{layout.platform}</Text>
|
||
</View>
|
||
);
|
||
}
|
||
```
|
||
|
||
`index.client.tsx`：
|
||
|
||
```tsx
|
||
import type { PluginClientContext, PluginSidebarItemProps } from "@getpaseo/plugin/client";
|
||
import { SidebarRow } from "@getpaseo/plugin/client/ui";
|
||
import { Main } from "./client/main";
|
||
|
||
function MainItem({ currentScreen, openScreen }: PluginSidebarItemProps) {
|
||
return (
|
||
<SidebarRow
|
||
icon="Blocks"
|
||
active={currentScreen?.screenId === "main"}
|
||
onPress={() => openScreen({ screenId: "main" })}
|
||
/>
|
||
);
|
||
}
|
||
|
||
export default function contribute(client: PluginClientContext) {
|
||
client.addScreen({ id: "main", title: "My plugin", Component: Main });
|
||
client.addSidebarHeaderItem({ id: "main", title: "My plugin", Component: MainItem });
|
||
return () => {};
|
||
}
|
||
```
|
||
|
||
`PluginScreenProps` 包含：
|
||
|
||
| 字段 | 含义 |
|
||
| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||
| `theme` | 当前 Paseo 主题的带类型 `PluginTheme` 颜色令牌。 |
|
||
| `host` | 所选主机的 `id` 和显示用的 `label`。 |
|
||
| `layout` | `compact` 以及 `ios`、`android` 或 `web` 平台。 |
|
||
| `params` | 打开界面时传入的参数，键和值都是字符串。没有参数时为 `{}`。 |
|
||
| `navigation` | 可选的客户端导航。`openAgent({ agentId, serverId? })` 和 `openWorkspace({ workspaceId, serverId? })` 在 `serverId` 上打开目标，省略时在所选主机上打开。`openBrowser({ url, workspaceId, serverId? })` 仅在 Electron 上可用；见[链接和浏览器](#external-links-and-workspace-browsers)。 |
|
||
|
||
路由、标题栏、关闭操作、主机选择器、错误边界和 query client 由 Paseo 负责。界面主体由插件负责。
|
||
|
||
`addScreen({ id, title, Component })` 注册一个界面。`title` 是界面标题栏的[显示文本](#runtime-translations)，也可以是接收界面参数并返回显示文本的函数。参数或语言变化时，该函数会再次运行。无效标题和空字符串标题会被拒绝。如果标题函数抛出错误或解析为空字符串，会改为显示界面 ID；界面仍然会渲染。
|
||
|
||
`openScreen({ screenId, params })` 以参数打开一个界面，例如机器人界面要显示的那个机器人。参数保存在界面 URL 的查询字符串中，因此重新加载、前进后退以及指向该界面的链接都会保留它们。任何字符串键都可以；值必须是字符串，其他类型会抛出错误。用其他参数打开同一个界面会显示新的参数。
|
||
|
||
### 侧边栏项 {#sidebar-items}
|
||
|
||
`addSidebarHeaderItem` 在侧边栏顶部的列表中添加一行。`addSidebarFooterItem` 在底部添加一行，位于 **添加 project** 和底部图标行之间。图标行是固定的；插件不能向其中添加内容。两者都接受 `{ id, title, Component }`。`title` 是该项在 **设置 → 侧边栏** 中的标签（用户在那里重新排序和隐藏各项），也是 `SidebarRow` 的默认标签和无障碍标签。设置页面为这些项显示一个通用的插件图标；来自已弃用的 `addSidebarItem` 的行保留其注册时的图标。
|
||
|
||
当插件安装在多台主机上时，侧边栏项按应用当前显示的界面所属的主机渲染。不在任何主机的界面上时，它使用最近一次在该插件的某个界面中选择的主机，或最近一次从它的某个项打开的主机，否则使用第一台主机。
|
||
|
||
`Component` 接收 `PluginSidebarItemProps`：
|
||
|
||
| 字段 | 含义 |
|
||
| ------------------------- | -------------------------------------------------------------------------------- |
|
||
| `theme`, `host`, `layout` | 与 `PluginScreenProps` 中相同。 |
|
||
| `currentScreen` | 在该项所属主机上打开的、此插件的界面的 `{ screenId, params }`，没有时为 `null`。 |
|
||
| `openScreen(input)` | 打开此插件的某个界面：`{ screenId, params? }`。未知的界面 ID 会抛出错误。 |
|
||
| `openPopover(Content)` | 在宽布局中把 `Content` 锚定在被按下的行旁边打开，在紧凑布局中以底部面板打开。 |
|
||
|
||
`Content` 接收 `theme`、`host`、`layout`、`close()` 和 `openScreen(input)`。打开界面会关闭弹出框。
|
||
|
||
用 `@getpaseo/plugin/client/ui` 中的侧边栏组件渲染该项：
|
||
|
||
| 组件 | 属性与行为 |
|
||
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||
| `SidebarRow` | 必填 `onPress`；可选 `icon`（任意一种[图标](#icons)形式）、`label`、`active`、`trailing`、`id`。占满整行宽度。`trailing` 渲染在行的可按区域旁边，因此其中的按钮可以单独按下；按下其中其他位置则相当于按下该行。`id` 用于在测试 ID 中区分同一项的多行。 |
|
||
| `SidebarSeparator` | 没有属性。侧边栏的分隔线，放在各组行之间。 |
|
||
|
||
弹出框锚定在被按下的那一行，无论按下的是行本身还是它的 `trailing` 内容，因此每行的“More”按钮会在它自己的行旁边打开弹出框。
|
||
|
||
```tsx
|
||
import type { PluginSidebarItemProps, PluginPopoverProps } from "@getpaseo/plugin/client";
|
||
import { SidebarRow } from "@getpaseo/plugin/client/ui";
|
||
import { Pressable, Text } from "react-native";
|
||
|
||
function SyncDetails({ theme, close, openScreen }: PluginPopoverProps) {
|
||
return (
|
||
<Pressable onPress={() => openScreen({ screenId: "sync" })}>
|
||
<Text style={{ color: theme.colors.foreground }}>Open sync history</Text>
|
||
</Pressable>
|
||
);
|
||
}
|
||
|
||
function SyncItem({ openPopover }: PluginSidebarItemProps) {
|
||
return <SidebarRow icon="RefreshCw" onPress={() => openPopover(SyncDetails)} />;
|
||
}
|
||
|
||
client.addSidebarFooterItem({ id: "sync", title: "Sync", Component: SyncItem });
|
||
```
|
||
|
||
抛出错误的项不会渲染任何内容；侧边栏的其余部分继续正常工作。
|
||
|
||
#### 一个项中的多行 {#several-rows-in-one-item}
|
||
|
||
项的 `Component` 可以返回 fragment、数组或 `null`，因此一个项可以渲染一个在运行时变化的列表。设置中只列出该项一次，它作为一个整体移动和隐藏。下面这个项为每个机器人显示一行，并以机器人 ID 作为参数打开该机器人的界面：
|
||
|
||
```tsx
|
||
import type {
|
||
PluginClientContext,
|
||
PluginScreenProps,
|
||
PluginSidebarItemProps,
|
||
} from "@getpaseo/plugin/client";
|
||
import { SidebarRow, SidebarSeparator } from "@getpaseo/plugin/client/ui";
|
||
import { Text } from "react-native";
|
||
import { botName, useBots } from "./client/bots";
|
||
|
||
function BotScreen({ theme, params }: PluginScreenProps) {
|
||
return <Text style={{ color: theme.colors.foreground }}>Bot {params.botId}</Text>;
|
||
}
|
||
|
||
function BotsItem({ currentScreen, openScreen }: PluginSidebarItemProps) {
|
||
const bots = useBots();
|
||
const openBotId = currentScreen?.screenId === "bot" ? currentScreen.params.botId : null;
|
||
return (
|
||
<>
|
||
<SidebarSeparator />
|
||
{bots.map((bot) => (
|
||
<SidebarRow
|
||
key={bot.id}
|
||
id={bot.id}
|
||
icon="Bot"
|
||
label={bot.name}
|
||
active={bot.id === openBotId}
|
||
onPress={() => openScreen({ screenId: "bot", params: { botId: bot.id } })}
|
||
/>
|
||
))}
|
||
</>
|
||
);
|
||
}
|
||
|
||
export default function contribute(client: PluginClientContext) {
|
||
client.addScreen({
|
||
id: "bot",
|
||
title: (params) => botName(params.botId) ?? "Bot",
|
||
Component: BotScreen,
|
||
});
|
||
client.addSidebarHeaderItem({ id: "bots", title: "Bots", Component: BotsItem });
|
||
return () => {};
|
||
}
|
||
```
|
||
|
||
#### 在运行时添加和移除项 {#add-and-remove-items-at-runtime}
|
||
|
||
`addSidebarHeaderItem` 和 `addSidebarFooterItem` 在入口返回之后仍然可用。它们各自返回一个移除函数；项会在不重新加载的情况下出现和消失：
|
||
|
||
```tsx
|
||
let removeAlerts: (() => void) | null = null;
|
||
|
||
function showAlerts(client: PluginClientContext) {
|
||
removeAlerts ??= client.addSidebarFooterItem({
|
||
id: "alerts",
|
||
title: "Alerts",
|
||
Component: AlertsItem,
|
||
});
|
||
}
|
||
|
||
function hideAlerts() {
|
||
removeAlerts?.();
|
||
removeAlerts = null;
|
||
}
|
||
```
|
||
|
||
## 宿主 UI {#host-ui}
|
||
|
||
在客户端代码中从 `@getpaseo/plugin/client/ui` 导入由 Paseo 提供的 UI。下面的示例会打开一个受控的弹窗、渲染一个宿主图标，并用 toast 确认操作：
|
||
|
||
```tsx
|
||
import type { PluginSurfaceProps } from "@getpaseo/plugin/client";
|
||
import { Icon, Modal, useToast } from "@getpaseo/plugin/client/ui";
|
||
import { useState } from "react";
|
||
import { Pressable, Text, View } from "react-native";
|
||
|
||
export function IssueActions({ theme }: PluginSurfaceProps) {
|
||
const [open, setOpen] = useState(false);
|
||
const toast = useToast();
|
||
|
||
function saveIssue() {
|
||
toast.show("Issue saved", { variant: "success" });
|
||
setOpen(false);
|
||
}
|
||
|
||
return (
|
||
<View>
|
||
<Pressable accessibilityRole="button" onPress={() => setOpen(true)}>
|
||
<View style={{ flexDirection: "row", alignItems: "center", gap: 8 }}>
|
||
<Icon name="Pencil" size={18} color={theme.colors.foreground} />
|
||
<Text style={{ color: theme.colors.foreground }}>Edit issue</Text>
|
||
</View>
|
||
</Pressable>
|
||
|
||
<Modal
|
||
title="Edit issue"
|
||
icon={<Icon name="Pencil" size={18} color={theme.colors.foreground} />}
|
||
open={open}
|
||
onOpenChange={setOpen}
|
||
>
|
||
<Modal.Content>
|
||
<Pressable accessibilityRole="button" onPress={saveIssue}>
|
||
<Text style={{ color: theme.colors.foreground }}>Save</Text>
|
||
</Pressable>
|
||
</Modal.Content>
|
||
</Modal>
|
||
</View>
|
||
);
|
||
}
|
||
```
|
||
|
||
### Markdown {#markdown}
|
||
|
||
从 `@getpaseo/plugin/client/ui` 导入 `Markdown`，即可在网页、iOS 和 Android 上
|
||
使用 Paseo 的 Markdown 样式渲染字符串：
|
||
|
||
```tsx
|
||
import { Markdown } from "@getpaseo/plugin/client/ui";
|
||
|
||
<Markdown>{"## 审查\n\n检查**通过**。"}</Markdown>;
|
||
```
|
||
|
||
`children` 是唯一的属性，必须为字符串。更新它会立即渲染新内容；空字符串不渲染任何内容。
|
||
宿主提供主题、文本选择、代码块、表格、图表和链接处理。
|
||
当所在界面提供工作区上下文时，工作区文件链接和图片会使用该上下文。
|
||
|
||
组件不添加页面内边距或滚动容器。需要时请在外层使用布局或滚动视图。
|
||
内容获取以及加载和错误状态由插件负责。
|
||
|
||
### Modal {#modal}
|
||
|
||
`Modal` 在紧凑布局中使用底部面板，否则使用居中的对话框。`open` 状态由插件负责。
|
||
|
||
| 属性 | 类型 | 是否必填 | 行为 |
|
||
| -------------- | ------------------------- | -------- | -------------------------------- |
|
||
| `title` | `string` | 是 | 为弹窗及其可见的标题栏提供标签。 |
|
||
| `icon` | `ReactNode` | 否 | 渲染在标题栏中标题的前面。 |
|
||
| `open` | `boolean` | 是 | 为 `true` 时显示弹窗内容。 |
|
||
| `onOpenChange` | `(open: boolean) => void` | 是 | 用户关闭弹窗时收到 `false`。 |
|
||
| `children` | `ReactNode` | 是 | 包含 `Modal.Content`。 |
|
||
|
||
`Modal.Content` 负责宿主渲染的标题栏下方的主体：
|
||
|
||
| 属性 | 类型 | 默认值 | 行为 |
|
||
| ----------------------- | ---------------------- | ------------------ | ------------------------------------------------------------------------ |
|
||
| `children` | `ReactNode` | 必填 | 标题栏下方的主体内容。 |
|
||
| `style` | `StyleProp<ViewStyle>` | — | 为整个主体视口（包括空白区域）设置样式。用于背景。 |
|
||
| `contentContainerStyle` | `StyleProp<ViewStyle>` | 内边距 24，间距 16 | 覆盖内容布局。要让行贴边显示，请设置 `padding: 0, gap: 0`。 |
|
||
| `scrollable` | `boolean` | `true` | 由宿主滚动主体。如果主体高度受限并使用你自己的滚动容器，请设为 `false`。 |
|
||
|
||
普通的 `Modal.Content` 已经带有内边距并且可以滚动。除非你想要再缩进一层，否则不要再添加一个带内边距的包装。主体样式不会影响宿主的标题栏、拖动手柄和关闭控件。在紧凑的原生布局中，宿主会在底部预留安全区域空间；把内容的内边距设为零只会去掉装饰性的缩进，而不会去掉这部分空间。键盘的避让是单独处理的。
|
||
|
||
使用 `scrollable={false}` 时，主体会填满底部面板的可用高度，居中对话框则使用可用高度的 85%。请在你的列表上使用 `flex: 1, minHeight: 0`。默认可滚动的对话框在宽布局中保持与内容一样的大小。呈现方式取决于窗口尺寸，包括较窄的桌面窗口和较宽的平板。
|
||
|
||
关闭按钮、背景遮罩、平台的返回操作、Web 上的 Escape 键以及紧凑布局下底部面板的手势都会关闭弹窗。关闭时会调用 `onOpenChange(false)`；插件必须更新 `open` 才能关闭它。
|
||
|
||
弹窗的子元素保留插件的运行时 context。`usePaseo`、`useRpc`、`useWorkspace` 和 `useAgent` 在其中都可以使用。
|
||
|
||
### 滚动 {#scrolling}
|
||
|
||
当内容可能出现在 Paseo 弹窗中时，请从 `@getpaseo/plugin/client/ui` 导入 `ScrollView` 和 `FlatList`。它们接受 React Native 的属性和 ref，并与底部面板的手势集成。在底部面板之外，它们使用普通的 React Native 滚动。不要直接导入底部面板库。
|
||
|
||
只使用一个垂直滚动的所有者：要么是默认的弹窗主体，要么是你自己的、配合 `scrollable={false}` 使用的列表。在默认可滚动主体中嵌套一个固定高度的垂直列表，可能会在 Android 上与底部面板争夺手势。水平滚动可以与宿主的垂直主体共存。
|
||
|
||
默认主体和 SDK 列表都共享原生底部面板的手势：先向上拖动展开，再开始滚动；在列表顶部向下拖动会收起或关闭面板。`scrollable={false}` 会移除宿主的滚动容器，但不会改变这些手势。在使用 `scrollToEnd` 等列表方法之前，请先展开底部面板；在面板达到最大高度之前，它会锁定列表的偏移量。
|
||
|
||
```tsx
|
||
import { FlatList, Modal } from "@getpaseo/plugin/client/ui";
|
||
import { Text } from "react-native";
|
||
|
||
// Inside your controlled Modal:
|
||
<Modal.Content
|
||
scrollable={false}
|
||
style={{ backgroundColor: theme.colors.surface1 }}
|
||
contentContainerStyle={{ padding: 0, gap: 0 }}
|
||
>
|
||
<FlatList
|
||
style={{ flex: 1, minHeight: 0 }}
|
||
data={items}
|
||
keyExtractor={(item) => item.id}
|
||
renderItem={({ item }) => (
|
||
<Text style={{ padding: 16, color: theme.colors.foreground }}>{item.title}</Text>
|
||
)}
|
||
/>
|
||
</Modal.Content>;
|
||
```
|
||
|
||
对于水平标签页，请把 `<ScrollView horizontal style={{ flexGrow: 0 }}>…</ScrollView>` 放在默认的 `Modal.Content` 中。让内容的垂直滚动仍由宿主负责。
|
||
|
||
### 复制和粘贴 {#copy-and-paste}
|
||
|
||
`copyText(text): Promise<void>` 写入运行应用的设备的剪贴板。请在用户操作中调用它，并在报告成功之前 await 它。如果平台拒绝复制或剪贴板不可用，它会 reject；浏览器权限和安全上下文要求仍然适用。
|
||
|
||
```tsx
|
||
import { copyText, useToast } from "@getpaseo/plugin/client/ui";
|
||
|
||
// Inside your component:
|
||
const toast = useToast();
|
||
async function copyResult() {
|
||
try {
|
||
await copyText(result);
|
||
toast.show("Copied", { variant: "success" });
|
||
} catch {
|
||
toast.error("Could not copy. Select the text and use Copy.");
|
||
}
|
||
}
|
||
```
|
||
|
||
以编程方式复制和原生文本选择是两种不同的交互。使用 `<Text selectable>` 支持长按选择和系统的复制。弹窗表单请从 `@getpaseo/plugin/client/ui` 导入 `TextInput`。它接受 React Native 的输入属性和 ref，支持系统粘贴，并向原生底部面板注册焦点，以便键盘能把表单顶上来。在底部面板之外，它使用普通的输入框。普通的 React Native 输入框也支持粘贴，但不会向底部面板注册焦点；键盘可能会遮住它。系统粘贴不需要任何读取剪贴板的 API。不要在原生插件中使用 DOM 剪贴板代码，也不要使用 `react-native` 中已弃用的 `Clipboard` 导出。
|
||
|
||
可运行的[弹窗 UI 示例](https://github.com/getpaseo/paseo/tree/main/plugin-examples/modal-ui)包含一个带内边距的表单、全宽的行、一个虚拟化列表、水平标签页和一个支持复制/粘贴的输入框。
|
||
|
||
### Toast {#toasts}
|
||
|
||
`useToast()` 返回两个方法：
|
||
|
||
| 方法 | 行为 |
|
||
| ------------------------- | ------------------------------------------------------------ |
|
||
| `show(message, options?)` | 显示一个 toast，除非提供了 `durationMs`，否则持续 2,200 ms。 |
|
||
| `error(message)` | 显示一个错误 toast，持续 3,200 ms。 |
|
||
|
||
`show` 接受以下选项：
|
||
|
||
| 选项 | 类型 | 默认值 |
|
||
| ------------ | ---------------------------------------------------------- | ----------- |
|
||
| `variant` | `"default" \| "info" \| "success" \| "warning" \| "error"` | `"default"` |
|
||
| `durationMs` | `number` | `2200` |
|
||
|
||
显示另一个 toast 会替换当前可见的 toast。空消息会被忽略。
|
||
|
||
### 图标 {#icons}
|
||
|
||
每个贡献的 `icon` 字段都接受以下三种形式之一，类型为 `@getpaseo/plugin/client` 中的 `PluginIcon`：
|
||
|
||
| 形式 | 示例 | 适用场景 |
|
||
| ----------- | --------------------------- | ----------------------------------------------- |
|
||
| Lucide 名称 | `icon: "Scan"` | 任意 [Lucide 图标](https://lucide.dev/icons/)。 |
|
||
| 内联 SVG | `icon: { svg: reviewIcon }` | 品牌标志，或 Lucide 中没有的图标。 |
|
||
| 组件 | `icon: ReviewBadge` | 随状态变化的图标，例如计数器。 |
|
||
|
||
附件来源接受 Lucide 名称或内联 SVG（`PluginSerializableIcon`），因为每个附加的条目都会保存其来源的图标。
|
||
|
||
Paseo 在贡献注册时校验图标。未知的 Lucide 名称或违反规则的 SVG 会导致插件加载失败，并给出原因：
|
||
|
||
```text
|
||
Workspace panel review has an invalid icon: script elements are not allowed
|
||
```
|
||
|
||
Paseo 按界面的图标尺寸绘制内联 SVG，并把界面的图标颜色作为 `currentColor` 传入。用 `currentColor` 绘制即可跟随主题；固定的填充色会保持原样。
|
||
|
||
组件会收到 `PluginIconProps`，即 `{ size, color }`，并在该尺寸内渲染。头部按钮和 Composer 胶囊传入的是 [`PluginButtonIconProps`](#custom-icons-and-popover-content)。
|
||
|
||
#### SVG 规则 {#svg-rules}
|
||
|
||
内联 SVG、Provider 图标和用量来源图标遵循相同的规则：
|
||
|
||
- 只有一个 `<svg>` 文档，大小不超过 64 KiB。
|
||
- 不含 `<script>`、`<style>` 或 `<foreignObject>` 元素。
|
||
- 不含 `onclick` 这类事件处理属性，也不含 `javascript:` URL。
|
||
- `href` 和 `xlink:href` 只能指向同一文档中的片段，例如 `#mark`。
|
||
|
||
#### 提供 SVG 标记 {#ship-svg-markup}
|
||
|
||
把标记放在一个客户端模块中：
|
||
|
||
```ts
|
||
// client/icons.ts
|
||
export const reviewIcon = `<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
|
||
<path d="M4 4h16v16H4z" />
|
||
</svg>`;
|
||
```
|
||
|
||
或者把一个 `.svg` 文件放进 `client/` 并导入它。插件编译器会把文件的标记打包为字符串。声明一次该模块，让 TypeScript 接受这个导入：
|
||
|
||
```ts
|
||
// client/svg.d.ts
|
||
declare module "*.svg" {
|
||
const markup: string;
|
||
export default markup;
|
||
}
|
||
```
|
||
|
||
```ts
|
||
// index.client.tsx
|
||
import reviewIcon from "./client/review.svg";
|
||
|
||
client.addWorkspacePanel({ id: "review", title: "Review", icon: { svg: reviewIcon } /* … */ });
|
||
```
|
||
|
||
#### 渲染图标 {#render-an-icon}
|
||
|
||
`@getpaseo/plugin/client/ui` 中的 `Icon` 用于在你自己的 UI 中绘制图标。插件包不导入 `lucide-react-native` 或 `react-native-svg`。
|
||
|
||
| 属性 | 类型 | 是否必填 | 行为 |
|
||
| ------- | ------------ | ----------------------- | ---------------------------------------------------------- |
|
||
| `name` | `string` | `name` 或 `icon` 二选一 | Lucide 图标名称。 |
|
||
| `icon` | `PluginIcon` | `name` 或 `icon` 二选一 | 上文任意一种图标形式。 |
|
||
| `size` | `number` | 否 | 图标的宽度和高度。默认为 24。 |
|
||
| `color` | `string` | 否 | 图标颜色，也是 SVG 的 `currentColor`。请使用插件主题令牌。 |
|
||
|
||
未知的名称或违反规则的 SVG 不会渲染任何内容。
|
||
|
||
## 时间线条目 {#timeline-items}
|
||
|
||
插件可以用自己的数据和 React Native 渲染器替换 Agent 时间线中的条目。两项注册都是客户端贡献。Paseo 在构建渲染模型时应用转换器，包括每一次实时的流式更新。
|
||
|
||
```tsx
|
||
import type { PluginClientContext, PluginTimelineItemProps } from "@getpaseo/plugin/client";
|
||
import { Text } from "react-native";
|
||
import { z } from "zod";
|
||
|
||
const schema = z.object({ label: z.string() });
|
||
|
||
function Card({ item, theme }: PluginTimelineItemProps<z.output<typeof schema>>) {
|
||
return <Text style={{ color: theme.colors.foreground }}>{item.data.label}</Text>;
|
||
}
|
||
|
||
export default function contribute(client: PluginClientContext) {
|
||
client.addTimelineTransformer({
|
||
id: "command-card",
|
||
query: { itemType: "tool_call" },
|
||
transform({ item, phase }) {
|
||
return {
|
||
items: [
|
||
{
|
||
type: "plugin",
|
||
kind: "command-card",
|
||
version: 1,
|
||
data: { label: item.name, phase },
|
||
},
|
||
],
|
||
};
|
||
},
|
||
});
|
||
client.addTimelineRenderer({
|
||
kind: "command-card",
|
||
version: 1,
|
||
schema,
|
||
Component: Card,
|
||
});
|
||
return () => {};
|
||
}
|
||
```
|
||
|
||
`query.itemType` 是稳定的、粗粒度的选择器。请在 `transform` 中检查所选的条目，以识别特定的 Provider 或工具。返回 `undefined` 会保留原条目。返回 `items` 会替换它；空数组会移除它。条目的 `data` 必须兼容 JSON。对于实时的助手消息、运行中的工具调用和加载中的推理，`phase` 输入为 `"streaming"`；对于已提交或已获取的消息以及已完成的工具或推理，它为 `"complete"`。助手和推理回调在每次更新时都会收到完整的累计文本，包括段落分隔符。Paseo 会在拆分原生 Markdown 或在 Overview 中对工具分组之前调用转换器。被认领的助手消息在整个流式过程中始终是同一个来源条目；如果最初的文本不足以识别它，请在可以识别之前返回 `undefined`。每个替换项都可以设置一个可选的、插件内部的 `id`；否则 Paseo 使用它在该来源条目输出中的索引。
|
||
|
||
渲染器接收 `agentId`、`item`、`timestamp`、`theme`、`host` 和 `layout`。Paseo 在渲染之前用注册的 schema 校验 `item.data`。请让转换器保持同步且确定。Paseo 按来源条目的引用缓存结果，并从来源行推导替换项的标识，因此对某个流式条目的更新不会重新挂载它的渲染器。要让纯文本像 Paseo 的助手行那样逐步显示，请渲染 `@getpaseo/plugin/client/ui` 中的 `<StreamedText text={item.data.text} phase={item.data.phase} />`。它接受 React Native `Text` 的属性（包括 `style`），默认使用助手消息的字体排版和前景色。完成后会立即显示全文；流式输出期间由宿主控制显示节奏。需要 Paseo 0.13 或更高版本。
|
||
|
||
当查询同时匹配原始消息时，聊天查找（Ctrl 或 Cmd+F）会在替换行中查找并高亮文本。宿主会在原始提示词文本或去掉 Markdown 语法的助手回复中搜索，然后由应用在你的渲染器绘制的文本中统计匹配。只由你的渲染器添加的文本不会被单独索引。匹配不会跨越渲染出的块，查找会跳过按钮、图标以及任何带有 `aria-hidden="true"` 的内容。查找只在 Web 和桌面应用中可用。
|
||
|
||
### 从 daemon 追加时间线行 {#append-a-timeline-row-from-the-daemon}
|
||
|
||
服务端处理函数可以向标准历史记录中添加一行由插件拥有的内容：
|
||
|
||
```ts
|
||
import type { PluginHandlerContext } from "@getpaseo/plugin/server";
|
||
|
||
async function publishReview(agentId: string, { paseo }: PluginHandlerContext) {
|
||
await paseo.agents.ref(agentId).timeline.append({
|
||
type: "plugin",
|
||
id: "review",
|
||
kind: "review-result",
|
||
version: 1,
|
||
data: { verdict: "ready" },
|
||
});
|
||
}
|
||
```
|
||
|
||
| 字段 | 类型 | 是否必填 | 行为 |
|
||
| --------- | ---------- | -------- | -------------------------------------------- |
|
||
| `type` | `"plugin"` | 是 | 选择插件时间线变体。 |
|
||
| `id` | `string` | 是 | 稳定的、插件内部的标识。复用它会替换旧的行。 |
|
||
| `kind` | `string` | 是 | 选择已注册的渲染器。 |
|
||
| `version` | 正整数 | 是 | 选择渲染器契约的版本。 |
|
||
| `data` | 兼容 JSON | 是 | 渲染器负载，JSON 序列化后最多 64 KiB。 |
|
||
|
||
daemon 会根据发起调用的插件会话写入 `pluginId`，并拒绝来自非插件会话的此 RPC。该行会实时出现，在时间线重新获取后依然保留，并且对于同一插件和 `id` 只保留最新的值。如果它的渲染器缺失，Paseo 会显示现有的“不可用”行。daemon 会拒绝超过限制的 `data`，而不是截断它。支持此操作的 daemon 会声明 `server_info.features.pluginTimelineItems`。
|
||
|
||
## 主题与布局 {#theme-and-layout}
|
||
|
||
插件 UI 运行在桌面、浏览器、iOS 和 Android 上，适用于每一个 Paseo 主题。`theme` 是由当前宿主主题映射而来的带类型 `PluginTheme`。颜色和间距必须来自这些属性。写死的颜色和没有样式的 `Text` 会在宿主主题变化时出问题。
|
||
|
||
当 `theme` 或 `layout.compact` 变化时，请重新创建样式。
|
||
|
||
| 键 | 必须用于 | 用于 |
|
||
| ------------------------------- | ------------------ | ------------------------------- |
|
||
| `theme.colors.foreground` | 每个主要的 `Text` | 标题和正文 |
|
||
| `theme.colors.foregroundMuted` | 次要的 `Text` | 标签和辅助文字 |
|
||
| `theme.colors.surface0` | 根视图 | 面板背景 |
|
||
| `theme.colors.surface1` | 凸起的表面 | 卡片和面板 |
|
||
| `theme.colors.surface2` | 控件表面 | 输入框和次要控件 |
|
||
| `theme.colors.border` | 表面边界 | 边框和分隔线 |
|
||
| `theme.colors.accent` | 主要操作的填充 | 按钮和选中状态 |
|
||
| `theme.colors.accentForeground` | 强调色填充上的文字 | 按钮标签 |
|
||
| `theme.colors.statusSuccess` | 成功反馈 | 成功消息和指示器 |
|
||
| `theme.colors.statusWarning` | 警告反馈 | 警告消息和指示器 |
|
||
| `theme.colors.statusDanger` | 失败文字 | 错误消息和破坏性操作的文字 |
|
||
| `layout.compact` | 内边距和堆叠 | 在移动端和较窄的窗口中为 `true` |
|
||
| `layout.platform` | 特定于平台的行为 | `ios`、`android` 或 `web` |
|
||
|
||
不要写死 `#000`、`#fff` 或 React Native 的默认文字颜色。主要文字使用 `foreground`。标签使用 `foregroundMuted`。当 `layout.compact` 为 true 时，收紧内边距。
|
||
|
||
工作区面板和 Agent 面板接收同样的 `theme`、`layout` 以及可选的 `navigation` 字段。
|
||
|
||
## 贡献主题 {#contribute-a-theme}
|
||
|
||
`addTheme` 向 **设置 → 外观** 添加一个浅色或深色主题，按其 `name` 列在内置主题之下。主题是数据，因此不需要组件文件：
|
||
|
||
```ts
|
||
import type { PluginClientContext } from "@getpaseo/plugin/client";
|
||
|
||
export default function contribute(client: PluginClientContext) {
|
||
client.addTheme({
|
||
id: "mocha",
|
||
name: "Catppuccin Mocha",
|
||
appearance: "dark",
|
||
colors: {
|
||
background: "#1e1e2e",
|
||
foreground: "#cdd6f4",
|
||
raised: "#313244",
|
||
control: "#45475a",
|
||
border: "#45475a",
|
||
accent: "#cba6f7",
|
||
mutedForeground: "#a6adc8",
|
||
ring: "#6c7086",
|
||
},
|
||
});
|
||
return () => {};
|
||
}
|
||
```
|
||
|
||
每种颜色都是十六进制字符串；其他格式会导致加载失败。Paseo 会把调色板扩展为内置深色主题所使用的完整令牌集合，因此贡献的主题无需逐一列出，就能覆盖面板、菜单、diff、状态颜色和终端。
|
||
|
||
| 颜色 | 用作 |
|
||
| ----------------- | ------------------------------------------------- |
|
||
| `background` | 应用、工作区和终端的背景 |
|
||
| `foreground` | 主要文字、终端前景色和光标 |
|
||
| `raised` | 卡片、弹出框和悬停的行 |
|
||
| `control` | 输入框、次要填充以及浅色主题的侧边栏 |
|
||
| `border` | 边框以及最高层凸起表面的色调 |
|
||
| `accent` | 按钮、选中和焦点。可选；省略时使用 `foreground`。 |
|
||
| `mutedForeground` | 次要文字 |
|
||
| `ring` | 焦点环、滚动条以及终端的亮黑色 |
|
||
|
||
`appearance` 为 `"light"` 或 `"dark"`。Paseo 用它选择对应的表面、状态、diff、语法高亮、终端和阴影的推导方式。
|
||
|
||
同一时间只有一个贡献的主题处于启用状态。选择一个主题会保存这项选择；如果之后插件被停用或移除，Paseo 会退回到默认主题，而不会让应用失去配色。
|
||
|
||
主题需要一个支持它们的宿主。在 `addTheme` 之前发布的客户端无法执行该客户端入口，并会报告 `client.addTheme is not a function`。请更新客户端。
|
||
|
||
## 设置界面 {#settings-screens}
|
||
|
||
在 `index.client.tsx` 中用 `client.addSettingsScreen({ id, title, icon, Component })` 注册一个组件。它会出现在该主机的 **设置 → 插件 → 你的插件** 下。`id` 在同一次安装中唯一；`icon` 可以是任意一种[图标](#icons)形式。注册返回一个幂等的移除函数，插件销毁时会移除剩余的界面。
|
||
|
||
调用 `client.openSettings(id)` 或 Command Center 回调中的 `openSettings(id)` 可以打开你自己的某个界面。即使多台主机安装了同一个插件，每次安装也有各自的值和路由。
|
||
|
||
该组件接收 `PluginSurfaceProps`。标题栏、返回导航、安全区域、滚动以及居中的设置栏由 Paseo 负责。紧凑的窗口会推入一个全屏的详情页；较宽的窗口会保留设置侧边栏。请在这个框架内用 React Native 组件渲染内容。被停用或移除的插件会留下一个“不可用”界面，其返回导航仍然可用。
|
||
|
||
### 具名 UI 组件 {#named-ui-components}
|
||
|
||
从 `@getpaseo/plugin/client/ui` 导入设置组件。它们可以配合你自己的状态和 RPC 使用；不需要表单包装或存储绑定。
|
||
|
||
```tsx
|
||
import { useState } from "react";
|
||
import { SettingsCard, SettingsSection, SettingsSwitch } from "@getpaseo/plugin/client/ui";
|
||
|
||
export function DisplaySettings() {
|
||
const [visible, setVisible] = useState(true);
|
||
return (
|
||
<SettingsSection title="Display">
|
||
<SettingsCard>
|
||
<SettingsSwitch label="Show metadata" value={visible} onValueChange={setVisible} />
|
||
</SettingsCard>
|
||
</SettingsSection>
|
||
);
|
||
}
|
||
```
|
||
|
||
| 组件 | 属性与行为 |
|
||
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------- |
|
||
| `SettingsSection` | 必填 `title`、`children`；可选 `info` 提示、`trailing` 内容、`testID`。负责分区的间距和标题。 |
|
||
| `SettingsCard` | `children`，可选 `testID`。负责卡片表面以及直接子元素之间的分隔线。请为映射生成的行提供稳定的 React key。 |
|
||
| `SettingsRow` | 必填 `label`；可选 `hint`、`error`、`children`、`testID`。用于包裹任何自定义控件或内容。 |
|
||
| `SettingsSwitch` | 行属性，外加必填的 `value: boolean`、`onValueChange`；可选 `disabled`。 |
|
||
| `SettingsSelect` | 行属性，外加必填的字符串 `value`、`options: { label, value }[]`、`onValueChange`；可选 `disabled`。使用 Paseo 的自适应菜单。 |
|
||
| `SettingsInput` | 行属性，外加必填的 `onChangeText`；可选 `initialValue`、`placeholder`、`disabled`、`secureTextEntry`、`ref`。 |
|
||
| `SettingsAction` | 行属性，外加必填的 `actionLabel`、`onPress`；可选 `disabled`。 |
|
||
|
||
`SettingsInput` 负责正在编辑中的文本。`initialValue` 在挂载时为它提供初始值。它的 ref 提供 `focus()`、`blur()`、`getText()` 和 `replaceText(text)`，用于显式的编程式修改。在用户保存之前，请把草稿文本保留在持久化值之外。自定义的预览和控件可以放在这些组件旁边或内部。
|
||
|
||
### 持久化的值 {#persisted-values}
|
||
|
||
在 `shared/` 中定义一个设置文档：
|
||
|
||
```ts
|
||
import { defineSettings } from "@getpaseo/plugin";
|
||
import { z } from "zod";
|
||
|
||
export const preferences = defineSettings({
|
||
id: "display",
|
||
scope: "host",
|
||
version: 1,
|
||
schema: z.object({ showMetadata: z.boolean().default(true) }),
|
||
});
|
||
```
|
||
|
||
在 `index.server.ts` 中、返回清理函数之前注册它。返回的句柄让服务端代码可以读取该文档并响应变化。使用自己数据的界面可以只保留在客户端。
|
||
|
||
```ts
|
||
export default function contribute(server: PluginServerContext) {
|
||
const settings = server.registerSettings(preferences);
|
||
|
||
settings.subscribe((next) => {
|
||
if (next.status === "ready") {
|
||
console.log("Settings changed", next.revision);
|
||
}
|
||
});
|
||
|
||
return () => {};
|
||
}
|
||
```
|
||
|
||
| 定义字段 | 契约 |
|
||
| ------------------------------ | --------------------------------------------------------------------------------------------- |
|
||
| `id` | 匹配 `[a-z][a-z0-9_-]*` 的小写标识符；在同一次安装中唯一。 |
|
||
| `scope` | 必须为 `"host"`。该主机所有获得授权的客户端共享这份文档。没有按用户、设备本地或跨主机的同步。 |
|
||
| `version` | 必填的正整数，描述 schema 的版本，与写入修订号无关。 |
|
||
| `schema` | JSON 值的 Zod schema。请提供默认值，使解析 `{}` 能得到一份完整的文档。 |
|
||
| `migrate(values, fromVersion)` | 可选的同步或异步函数，从较旧的存储版本转换。它的输出必须通过当前的 schema。 |
|
||
|
||
在任何贡献的组件中调用 `useSettings(preferences)`。它返回一个可区分的状态：
|
||
|
||
| `status` | 可用的数据 |
|
||
| --------- | ---------------------------------------------- |
|
||
| `loading` | 读取尚未完成；不要把默认值当作已保存的值渲染。 |
|
||
| `ready` | 带类型的 `values` 和一个不透明的 `revision`。 |
|
||
| `invalid` | `error` 和 `revision`；存储的数据会被保留。 |
|
||
| `error` | 读取或连接产生的 `error`。 |
|
||
|
||
服务端句柄提供 `read()` 和 `subscribe()`。`read()` 返回与客户端 hook 相同的 `ready` 或
|
||
`invalid` 状态，包括不透明的修订号。`subscribe()` 返回一个清理函数，并在每次成功保存、重置或迁移之后
|
||
收到新的 `ready` 状态。无效的写入和修订冲突不会通知订阅者。监听器的失败只会被记录，不会把已提交的写入
|
||
变成保存失败。
|
||
|
||
```ts
|
||
const current = await settings.read();
|
||
if (current.status === "ready") {
|
||
// Use current.values and current.revision.
|
||
}
|
||
```
|
||
|
||
每种状态还提供 `saving`、`saveError` 以及以下操作：
|
||
|
||
- `save(values, revision): Promise<boolean>` 校验并保存一份完整的文档。校验失败、冲突或传输失败时，
|
||
它返回 `false` 并设置 `saveError`；它不会抛出错误。
|
||
- `reset(): Promise<boolean>` 使用 hook 加载的修订号，显式地把文档替换为 schema 默认值。它可以用来
|
||
从无效的存储数据中恢复。
|
||
- `reload(): Promise<void>` 清除保存错误并重新读取。草稿由你的组件负责；重新加载不会自动丢弃这份草稿。
|
||
|
||
对于即时生效的开关，把 `{ ...settings.values, showMetadata }` 和 `settings.revision` 传给 `save`。
|
||
对于草稿编辑器，在打开时同时记下值和修订号。在保存成功或用户放弃草稿之前，一直保留这个修订号。过期的
|
||
修订号会让保存被拒绝，草稿和更新后的已保存值都会被保留。
|
||
|
||
写入是原子的，并在主机上校验。已连接的客户端无需重新加载插件就能收到更新。这些值在 daemon 重启、插件
|
||
重新加载、停用和更新之后依然保留。移除一次安装会删除它的设置。重新安装同一个 ID 会从默认值开始。
|
||
|
||
缺失的文档使用 schema 默认值。无效的数据、失败的迁移以及不受支持的更新版本会产生 `invalid`，而不会
|
||
悄悄重置文件。成功的迁移只会持久化一次新版本。这些文档是普通的主机端 JSON，而不是凭据保险库。
|
||
设置相关的 RPC 使用现有的 `daemon.manage` 权限来执行插件。
|
||
|
||
完整的[设置示例](https://github.com/getpaseo/paseo/tree/main/plugin-examples/settings)
|
||
包含即时生效的控件、带校验的草稿编辑器、自定义内容以及 Command Center 导航。
|
||
|
||
## 工作区面板 {#workspace-panels}
|
||
|
||
使用 `addWorkspacePanel` 注册工作区面板，使用 `addAgentPanel` 注册 Agent 面板。
|
||
两者与[文件面板](#file-panels)使用相同的面板契约。
|
||
|
||
`client/review.tsx`：
|
||
|
||
```tsx
|
||
import { type PluginAgentPanelProps, useAgent, useWorkspace } from "@getpaseo/plugin/client";
|
||
import { useMemo } from "react";
|
||
import { Text, View } from "react-native";
|
||
|
||
export function ReviewPanel({ theme, layout, workspaceId, params }: PluginAgentPanelProps) {
|
||
const workspaceName = useWorkspace(workspaceId, (workspace) => workspace.name);
|
||
const agent = useAgent(params.agentId, ({ id, title }) => ({ id, title }));
|
||
const styles = useMemo(
|
||
() => ({
|
||
screen: {
|
||
flex: 1,
|
||
padding: layout.compact ? 16 : 24,
|
||
backgroundColor: theme.colors.surface0,
|
||
},
|
||
title: { color: theme.colors.foreground },
|
||
detail: { color: theme.colors.foregroundMuted },
|
||
}),
|
||
[theme, layout.compact],
|
||
);
|
||
return (
|
||
<View style={styles.screen}>
|
||
<Text style={styles.title}>{workspaceName}</Text>
|
||
<Text style={styles.detail}>{agent?.title ?? agent?.id}</Text>
|
||
</View>
|
||
);
|
||
}
|
||
```
|
||
|
||
`index.client.tsx`：
|
||
|
||
```ts
|
||
import type { PluginClientContext } from "@getpaseo/plugin/client";
|
||
import { ReviewPanel } from "./client/review";
|
||
|
||
export default function contribute(client: PluginClientContext) {
|
||
client.addAgentPanel({
|
||
id: "review",
|
||
title: "Review",
|
||
icon: "Scan",
|
||
locations: ["workspace", "explorer"],
|
||
Component: ReviewPanel,
|
||
});
|
||
return () => {};
|
||
}
|
||
```
|
||
|
||
`addWorkspacePanel` 和 `addAgentPanel` 的字段：
|
||
|
||
| 字段 | 是否必填 | 含义 |
|
||
| ----------- | -------- | --------------------------------------------------- |
|
||
| `id` | 是 | 插件内部的面板 ID。 |
|
||
| `title` | 是 | 工作区标签页的标题。 |
|
||
| `icon` | 是 | Lucide 名称、`{ svg }` 或组件。参见[图标](#icons)。 |
|
||
| `locations` | 否 | `workspace` 和/或 `explorer`。默认为 `workspace`。 |
|
||
| `Component` | 是 | 与所选上下文的属性相匹配的 React Native 组件。 |
|
||
|
||
每个面板都接收 `PluginPanelProps<Params>`，包含 `theme`、`host`、`layout`、`navigation`、
|
||
`workspaceId`、只读的 `params`、`revision` 和 `tab`。工作区面板使用空的
|
||
`PluginWorkspacePanelParams`；Agent 面板的 `PluginAgentPanelParams` 包含 `agentId`。
|
||
每次向同一标签页重新发送 params 时，`revision` 都会递增，即使请求与上次相同。
|
||
|
||
`tab.setModified(boolean)` 标记未保存的更改，并在关闭前询问。`tab.state` 是由面板定义的持久化
|
||
JSON，初始为 `undefined`；`tab.setState(value)` 替换整个值。每个标签页拥有独立状态。
|
||
Paseo 只保存状态，不解释其内容。用 `useTabState(tab, schema, defaultState)` 验证它：
|
||
|
||
```tsx
|
||
const schema = z.object({ view: z.enum(["preview", "source"]) });
|
||
const [state, setState] = useTabState(tab, schema, { view: "preview" });
|
||
// Missing or invalid persisted state returns the default.
|
||
// In an event handler, call setState({ view: "source" }).
|
||
```
|
||
|
||
从 `@getpaseo/plugin/client` 导入 `useTabState`，从 `zod` 导入 `z`。setter 替换整个 JSON 值。
|
||
标签页恢复和应用重新加载后，状态仍然保留。
|
||
|
||
统一属性、`addAgentPanel` 和 `useTabState` 需要 Paseo 0.13.0 或更高版本。
|
||
|
||
**已弃用，将在 2027-04-23 之后移除**：0.12 面板的 `context` 和顶层 `agentId` 属性、
|
||
`addWorkspacePanel({ context: "workspace" })` 以及 `addWorkspacePanel({ context: "agent" })`
|
||
仍然有效。省略工作区的 `context`，用 `addAgentPanel` 注册 Agent 面板，并读取 `params.agentId`。
|
||
|
||
用 `useWorkspace(workspaceId, selector)` 和 `useAgent(params.agentId, selector)` 读取缓存的状态。selector 是必填的。Paseo 对它的结果做浅比较，因此选择 `{ name, status }` 时，无关字段的变化不会触发重新渲染。在一次调用中选择组件渲染的所有字段；不要选择整个快照。
|
||
|
||
当记录不可用时，两个 hook 都返回 `null`。否则它们会针对规范化的客户端状态同步运行。快照 DTO 及其嵌套值都是深度只读的，并在运行时被冻结。不要调用插件 RPC 来获取当前的工作区或 Agent。可选的或特定于厂商的补充数据，请在组件渲染之后再获取。
|
||
|
||
工作区快照字段：
|
||
|
||
| 字段 | 类型 |
|
||
| -------------------- | ----------------------------------------------------------------- |
|
||
| `id` | `string` |
|
||
| `projectId` | `string` |
|
||
| `projectDisplayName` | `string` |
|
||
| `projectRootPath` | `string` |
|
||
| `directory` | `string` |
|
||
| `projectKind` | `"git" \| "non_git" \| "directory"` |
|
||
| `kind` | `"directory" \| "local_checkout" \| "checkout" \| "worktree"` |
|
||
| `name` | `string` |
|
||
| `title` | `string \| null` |
|
||
| `status` | `"needs_input" \| "failed" \| "running" \| "attention" \| "done"` |
|
||
| `statusEnteredAt` | ISO 时间戳或 `null` |
|
||
| `archivingAt` | ISO 时间戳或 `null` |
|
||
| `diffStat` | `{ additions: number; deletions: number } \| null` |
|
||
|
||
Agent 快照字段：
|
||
|
||
| 字段 | 类型 |
|
||
| ------------------- | -------------------------------------------------------------- |
|
||
| `id` | `string` |
|
||
| `workspaceId` | `string` |
|
||
| `provider` | `string` |
|
||
| `status` | `"initializing" \| "idle" \| "running" \| "error" \| "closed"` |
|
||
| `createdAt` | ISO 时间戳 |
|
||
| `updatedAt` | ISO 时间戳 |
|
||
| `lastActivityAt` | ISO 时间戳 |
|
||
| `title` | `string \| null` |
|
||
| `cwd` | `string` |
|
||
| `model` | `string \| null` |
|
||
| `currentModeId` | `string \| null` |
|
||
| `thinkingOptionId` | `string \| null` |
|
||
| `requiresAttention` | `boolean` |
|
||
| `attentionReason` | `"finished" \| "error" \| "permission" \| null` |
|
||
| `parentAgentId` | `string \| null` |
|
||
| `labels` | `Record<string, string>` |
|
||
|
||
标签页的焦点、拆分、关闭、持久化、查询状态、API/RPC Provider 以及渲染错误边界都由 Paseo 负责。如果恢复的标签页所对应的插件、面板、上下文、工作区或 Agent 不可用，该标签页会保持打开并显示“不可用”消息，而不会让工作区崩溃。
|
||
|
||
## 文件面板 {#file-panels}
|
||
|
||
注册一个组件，把文件渲染为文件标签页的主体。组件会收到所选主机上该文件的句柄，远程主机也一样。由组件读取文件、显示自己的加载状态，并在用户编辑时写回文件。面板报告有未保存更改时，标签页会显示一个圆点。
|
||
|
||
```tsx
|
||
import type { PluginClientContext } from "@getpaseo/plugin/client";
|
||
import { PdfPanel } from "./client/pdf-panel";
|
||
|
||
export default function contribute(client: PluginClientContext) {
|
||
return client.addFilePanel({
|
||
id: "pdf",
|
||
title: "PDF",
|
||
icon: "FileText",
|
||
files: { extensions: ["pdf"] },
|
||
Component: PdfPanel,
|
||
});
|
||
}
|
||
```
|
||
|
||
`addFilePanel` 接收一个 `PluginFilePanelContribution`，并返回一个幂等的清理函数。客户端入口被卸载时，Paseo 也会移除该注册。
|
||
|
||
| 字段 | 必填 | 含义 |
|
||
| ----------- | ---- | -------------------------------------------------------------------- |
|
||
| `id` | 是 | 插件内唯一的 ID，匹配 `^[a-z][a-z0-9-]*$`。 |
|
||
| `title` | 是 | 显示在选择器、**打开方式…** 菜单和 **设置 > 文件** 中的非空标签。 |
|
||
| `icon` | 是 | Lucide 名称、`{ svg }` 或组件。参见[图标](#icons)。 |
|
||
| `files` | 是 | `{ extensions: readonly string[]; filenames?: readonly string[] }`。 |
|
||
| `Component` | 是 | 接收 `PluginFilePanelProps` 的组件。 |
|
||
|
||
扩展名不带前导点，匹配时不区分大小写。文件名按完整的 basename 匹配，区分大小写。选择器不包含路径、glob 或通配符。只按文件名选择时，请使用 `extensions: []`。至少需要一个扩展名或文件名。
|
||
|
||
### 文件面板属性 {#file-panel-props}
|
||
|
||
`PluginFilePanelProps` 包含[主题和布局](#theme-and-layout)中介绍的通用属性 `theme`、`host`、`layout` 和可选的 `navigation`，另外还有：
|
||
|
||
| 属性 | 类型 | 含义 |
|
||
| ------------- | ----------------------- | ------------------------------------------------------------------------------------------ |
|
||
| `workspaceId` | `string` | 包含该文件标签页的工作区。 |
|
||
| `params` | `PluginFilePanelParams` | 打开请求提供的只读 `path`、`lineStart?` 和 `lineEnd?`。 |
|
||
| `revision` | `number` | 每次向该标签页重新发送 params 时递增，即使是同一行。 |
|
||
| `file` | `PluginFile` | 从 `params.path` 解析的文件能力；标签页显示该文件期间保持不变。 |
|
||
| `tab` | `PluginTab` | `setModified`、持久化的自定义 `state` 和 `setState`。参见[工作区面板](#workspace-panels)。 |
|
||
|
||
Paseo 在知道文件存在及其大小后就会挂载你的面板，不会先读取文件。`file` 对象保持不变，它的 stat 字段保存 Paseo 已知的最新版本。请在渲染时读取这些字段；它们变化时不会重新渲染你的面板。面板要通过 `watch` 监听器，或 `useFileText`、`useFileBytes`、`useFileUrl` 引起的重新渲染，得知它们已变化：
|
||
|
||
| 成员 | 含义 |
|
||
| -------------------------------- | ----------------------------------------------------------------------------- |
|
||
| `path`、`name`、`extension` | 主机上的绝对路径、basename，以及不带点的小写扩展名（没有时为 `""`）。 |
|
||
| `size`、`modifiedAt`、`mimeType` | 以字节计的大小、修改时间戳，以及主机报告的 MIME 类型。 |
|
||
| `readText()` | 以 UTF-8 读取文件。字节顺序标记（BOM）会被去掉，并由 `writeText` 写回。 |
|
||
| `readBytes()` | 读取文件的字节。 |
|
||
| `url()` | 当前字节的本地 `blob:`（Web）或 `file:`（原生）URL，供 `DocumentFrame` 使用。 |
|
||
| `writeText(text, options?)` | 如果文件在磁盘上自该句柄上次读取或写入后没有变化，则以 UTF-8 写入文本。 |
|
||
| `writeBytes(bytes, options?)` | 与上面相同，但写入字节。 |
|
||
| `watch(listener)` | 用 `PluginFileEvent` 调用 `listener(event)`；返回取消订阅函数。 |
|
||
|
||
`PluginFileEvent` 是 `{ type: "changed" }` 或 `{ type: "deleted" }`。请根据 `type` 分支处理；以后的版本可能会增加字段。文件被删除时，你的面板保持挂载。`watch` 会在一次读取确认文件已不存在后报告 `{ type: "deleted" }`，因此某个程序删除文件后又写回时，只会报告 `{ type: "changed" }`。被删除的文件重新出现时，会报告 `{ type: "changed" }`。
|
||
|
||
如果文件在该句柄上次读取或写入后在磁盘上发生了变化，写入会以 `PluginFileConflictError` reject。传入 `{ force: true }` 可以强制写入。文件已不存在时，无论是否传入 `force`，写入都会以 `PluginFileDeletedError` reject。句柄自己的写入不会通知它的监听器。`url()` 返回的 URL 由 Paseo 管理：在更新版本的 URL 解析完成或标签页关闭之前，它一直有效。不要用 `file.path` 拼接 daemon URL；daemon 在远程时，本地 URL 同样可用。
|
||
|
||
### 读取文件 {#read-the-file}
|
||
|
||
大多数面板通过 hook 读取文件。每个 hook 在挂载时读取，在文件于磁盘上变化时重新读取，并在重新读取期间保留当前值：
|
||
|
||
| Hook | 就绪状态 |
|
||
| -------------------- | ---------------------------------------- |
|
||
| `useFileText(file)` | `{ status: "ready", text: string }` |
|
||
| `useFileBytes(file)` | `{ status: "ready", bytes: Uint8Array }` |
|
||
| `useFileUrl(file)` | `{ status: "ready", url: string }` |
|
||
|
||
在第一次读取之前，每个 hook 还会返回 `{ status: "loading" }`；读取失败时返回 `{ status: "error", error }`。文件已删除时，`error` 是 `PluginFileDeletedError`。在内容显示到屏幕上之前，请显示 `@getpaseo/plugin/client/ui` 中的 `Loading`；它会填满面板，所以可以把它渲染在仍在布局的内容之上。
|
||
|
||
```tsx
|
||
import { type PluginFilePanelProps, useFileUrl } from "@getpaseo/plugin/client";
|
||
import { DocumentFrame, Loading } from "@getpaseo/plugin/client/ui";
|
||
import { Text } from "react-native";
|
||
|
||
export function PdfPanel({ file, theme }: PluginFilePanelProps) {
|
||
const url = useFileUrl(file);
|
||
if (url.status === "loading") return <Loading />;
|
||
if (url.status === "error") {
|
||
return <Text style={{ color: theme.colors.statusDanger }}>{url.error.message}</Text>;
|
||
}
|
||
return <DocumentFrame url={url.url} testID="pdf-panel" />;
|
||
}
|
||
```
|
||
|
||
### 编辑文件 {#edit-the-file}
|
||
|
||
hook 的重新读取会采用磁盘上的版本，因此下一次写入会覆盖那里发生的任何变化。持有未保存编辑的面板应只用 `readText()` 读取一次，然后自己处理 `watch`：
|
||
|
||
1. 用 `file.readText()` 读取并显示文本。
|
||
2. 每次编辑时，调用 `tab.setModified(true)`，并以防抖方式用 `file.writeText(text)` 写入。
|
||
3. 写入完成且没有更新的编辑等待写入时，调用 `tab.setModified(false)`。
|
||
4. 收到 `{ type: "changed" }` 且没有未保存内容时，重新读取。有未保存的编辑时，显示冲突，让用户重新加载或用 `{ force: true }` 覆盖。
|
||
5. 遇到 `PluginFileConflictError` 时，显示同样的冲突。
|
||
6. 收到 `{ type: "deleted" }` 或遇到 `PluginFileDeletedError` 时，告诉用户文件已不存在。
|
||
|
||
请在组件卸载之前写入待保存的编辑：用其他面板打开标签页或关闭标签页都会卸载它。如果面板报告有未保存的更改，Paseo 会在关闭标签页之前询问。[Markdown 面板](https://github.com/getpaseo/paseo/tree/main/plugin-examples/markdown-panel)示例实现了这些步骤。
|
||
|
||
### 选择与打开方式 {#selection-and-open-with}
|
||
|
||
插件面板是其选择器匹配的每个文件的候选面板，无论是文本还是二进制文件。内置面板要求主机报告的文件类型：Markdown、HTML 和 **源代码** 打开文本文件，**图片** 打开图片。Markdown 和 HTML 面板各自有文件的预览视图和源代码视图，在面板的工具栏中切换。**源代码** 是 Paseo 的编辑器，是没有其他内置面板认领的文本文件的内置面板；它从不与其他内置面板一起提供。候选面板的顺序是：认领该文件的内置面板，然后按主机目录顺序排列的插件面板，最后是没有其他内置面板认领该文件时的源代码。
|
||
|
||
记住的关联在其面板于当前主机上可用时选择该面板。否则 Paseo 打开第一个候选面板。当插件面板是多个候选面板之一且没有适用的关联时，Paseo 每次打开标签页时询问一次，询问显示在它已经打开的面板上方。只有一个候选面板的文件从不询问。安装了一个 Markdown 插件后，选择器会提供 **Markdown — Paseo** 和 **Rich Markdown — markdown-panel**。认领某个没有内置面板认领的文本扩展名的插件会与源代码竞争，所以第一次打开时会询问；单独认领某个二进制文件的插件会直接打开，不询问。
|
||
|
||
**不再询问** 会在此设备上为该扩展名记住这个选择。当某个候选面板匹配了确切的文件名时，该选择改为应用于那个 basename。不可用的关联在该主机上会被忽略，并为安装了其面板的主机保留。
|
||
|
||
用户有三种方式选择面板：第一次打开时的选择器、标签页菜单中的 **打开方式…**，以及 **设置 > 文件**。打开方式会切换当前标签页，并且对于这个标签页优先于记住的关联，直到标签页被重新定向；其中的 **始终用于** 会记住当前显示的面板。从链接或搜索结果在某一行打开文件时，标签页会切换到它的内置面板，并在源代码视图中显示该行。没有候选面板的文件显示 **二进制预览不可用**；二进制文件没有源代码面板。
|
||
|
||
### DocumentFrame {#documentframe}
|
||
|
||
从 `@getpaseo/plugin/client/ui` 导入 `DocumentFrame`，用来显示 `file.url()` 或 `useFileUrl` 返回的本地文件 URL：
|
||
|
||
| 属性 | 必填 | 含义 |
|
||
| -------- | ---- | -------------------------------------------------------------------- |
|
||
| `url` | 是 | 本地文件 URL；Web 上为 `blob:`，原生上为 `file:`。其他协议会被拒绝。 |
|
||
| `testID` | 否 | 该框架的测试标识。 |
|
||
|
||
在 Web 上，挂载 iframe 之前会先检查本地 URL 的媒体类型。PDF 使用浏览器的 PDF 查看器，不加沙箱；其他所有类型，包括 HTML 和未知类型，都保持完整沙箱，不允许脚本或同源访问。原生平台使用禁用了 JavaScript、存储和后续导航的 WebView。在平台无法内联显示文档的地方，例如 Android 上的 PDF，`DocumentFrame` 会改为显示一条说明文件类型的消息，因此请在所有平台上渲染它。
|
||
|
||
内联 PDF 渲染需要 Paseo 0.13.0 或更高版本的 daemon；更早的 daemon 会把 PDF 报告为 `application/octet-stream`。
|
||
|
||
### 版本要求与示例 {#version-requirement-and-examples}
|
||
|
||
文件面板、`DocumentFrame` 和 `Loading` 需要 Paseo 0.13.0 或更高版本。请在 `paseo-plugin.json` 中声明 `"requirements": { "paseo": ">=0.13.0" }`。daemon 和应用都会检查[版本要求](#requirements)；更早的应用会在执行客户端包之前跳过它。用 `writeBytes` 写入需要 Paseo 0.13.0 或更高版本的 daemon。
|
||
|
||
完整的目录示例：
|
||
|
||
- [PDF 面板](https://github.com/getpaseo/paseo/tree/main/plugin-examples/pdf-panel)：`useFileUrl` 搭配 `Loading` 和 `DocumentFrame`。
|
||
- [Markdown 面板](https://github.com/getpaseo/paseo/tree/main/plugin-examples/markdown-panel)：打包的 CodeMirror 编辑器，只读取一次、用 `writeText` 保存并处理冲突，在原生平台上显示只读文本。
|
||
|
||
## Command Center 条目 {#command-center-items}
|
||
|
||
在 macOS 上按 **⌘K**，在 Windows 和 Linux 上按 **Ctrl+K** 打开 Command Center，然后搜索条目标题。
|
||
|
||
注册一个操作，并在回调中打开一个面板：
|
||
|
||
```tsx
|
||
import { defineRpc } from "@getpaseo/plugin";
|
||
import { z } from "zod";
|
||
|
||
const refreshReview = defineRpc({
|
||
name: "review.refresh",
|
||
input: z.object({ agentId: z.string(), scope: z.string().optional() }),
|
||
output: z.object({ refreshed: z.boolean() }),
|
||
});
|
||
|
||
client.addCommandCenterItem({
|
||
id: "open-review",
|
||
title: "Open review",
|
||
icon: "Scan",
|
||
keywords: ["inspect"],
|
||
context: "agent",
|
||
async onSelect({ paseo, rpc, workspace, agent, openPanel }) {
|
||
await paseo.workspaces.ref(workspace.id).setTitle(`Review ${agent.id}`);
|
||
await rpc(refreshReview, { agentId: agent.id });
|
||
openPanel("review");
|
||
},
|
||
});
|
||
```
|
||
|
||
`addCommandCenterItem` 的字段：
|
||
|
||
| 字段 | 是否必填 | 含义 |
|
||
| ---------- | -------- | --------------------------------------------------- |
|
||
| `id` | 是 | 插件内部的条目 ID。 |
|
||
| `title` | 是 | 搜索结果的标题。 |
|
||
| `icon` | 是 | Lucide 名称、`{ svg }` 或组件。参见[图标](#icons)。 |
|
||
| `keywords` | 否 | 额外的 Command Center 搜索词。 |
|
||
| `context` | 是 | `global`、`workspace` 或 `agent`。 |
|
||
| `onSelect` | 是 | 对应上下文的客户端回调。 |
|
||
|
||
全局条目出现在该安装所选择的主机上。只有当该主机有一个处于活动状态的缓存工作区时，工作区条目才会出现。只有当获得焦点的工作区标签页是一个 Agent，或者是一个缓存记录属于该工作区的 Agent 上下文插件面板时，Agent 条目才会出现。缺少上下文时条目会被移除，而不是调用插件去获取上下文。
|
||
|
||
每个回调都会收到：
|
||
|
||
| 字段 | 上下文 | 含义 |
|
||
| ------------------------- | -------------- | ----------------------------------------------------------------------------------------------- |
|
||
| `context` | 全部 | 对应的判别字段。 |
|
||
| `paseo` | 全部 | 所选主机现有的 `PaseoApi`。 |
|
||
| `rpc(contract, input)` | 全部 | 对此安装的 daemon 端插件处理函数的带类型调用。 |
|
||
| `openScreen(input)` | 全部 | 打开此插件注册的某个界面：`{ screenId, params? }`。 |
|
||
| `workspace` | 工作区和 Agent | 同步的工作区快照。 |
|
||
| `agent` | Agent | 同步的、与之匹配的 Agent 快照。 |
|
||
| `openPanel(id, options?)` | 工作区和 Agent | 在回调当前的上下文中打开一个已注册的面板。传入 `{ location: "explorer" }` 可以打开到 Explorer。 |
|
||
|
||
Agent 回调可以打开 Agent 面板或工作区面板。工作区回调只能打开工作区面板。未知的界面和面板 ID 会明确报错。普通的工作区、Agent、Provider 和 daemon 配置操作请使用 `paseo`。插件特有的文件系统、凭据、厂商或 daemon 本地工作请使用 `rpc`。
|
||
|
||
## 斜杠命令 {#slash-commands}
|
||
|
||
注册一个命令，当用户在消息 Composer 中提交 `/name args` 时，它会在 Paseo 客户端中运行。这段文本
|
||
永远不会发送给 Agent：
|
||
|
||
```ts
|
||
client.addSlashCommand({
|
||
name: "review",
|
||
description: "Run the review bot",
|
||
argumentHint: "[scope]",
|
||
context: "agent",
|
||
async onSubmit({ args, agent, rpc, openPanel }) {
|
||
await rpc(refreshReview, { agentId: agent.id, scope: args });
|
||
openPanel("review");
|
||
},
|
||
});
|
||
```
|
||
|
||
| 字段 | 是否必填 | 含义 |
|
||
| -------------- | -------- | ---------------------------------- |
|
||
| `name` | 是 | 不带前导斜杠的命令名称。 |
|
||
| `description` | 是 | Composer 自动补全中的描述。 |
|
||
| `argumentHint` | 是 | 显示在命令名称之后的简短用法提示。 |
|
||
| `context` | 是 | `"workspace"` 或 `"agent"`。 |
|
||
| `onSubmit` | 是 | 对应上下文的客户端回调。 |
|
||
|
||
`onSubmit` 接收对应的 Command Center 回调上下文以及 `args`。对于 `/review src`，`args` 是
|
||
`"src"`；Paseo 只去掉剩余部分首尾的空白，解析留给插件。自动补全行、清空输入框和错误 toast 由
|
||
Paseo 负责。它不会等待 `onSubmit`，也不会显示进行中的状态；如需显示，请使用 Composer 胶囊或面板。
|
||
|
||
优先级依次是内置客户端命令、插件命令、Provider 命令。优先级较低的冲突命令会被省略。内置别名也会占用
|
||
它们的名称。插件之间发生冲突时，按稳定的目录顺序排在前面的插件胜出。Composer 中有附件时，命令不会运行。
|
||
|
||
## 标题栏按钮 {#header-buttons}
|
||
|
||
试试[按钮示例](https://github.com/getpaseo/paseo/tree/main/plugin-examples/buttons)，它在标题栏和
|
||
Composer 中演示了操作、菜单、自定义图标和内容以及可见性更新。它会在几种模式之间切换一个标题栏按钮；
|
||
其他操作放在一个名为 Tools 的菜单中。
|
||
|
||
`client.addHeaderButton({ id, workspaceId, button })` 在工作区标题栏右侧的内置操作之前添加一个按钮。
|
||
它返回一个带有 `update(patch)` 和 `remove()` 的注册对象。
|
||
|
||
```tsx
|
||
const review = client.addHeaderButton({
|
||
id: "review",
|
||
workspaceId,
|
||
button: {
|
||
title: "Open review",
|
||
icon: "Scan",
|
||
label: "Review",
|
||
behavior: {
|
||
kind: "action",
|
||
onPress() {
|
||
client.openPanel("review", { workspaceId });
|
||
},
|
||
},
|
||
},
|
||
});
|
||
|
||
review.update({ label: "Review · 3" });
|
||
review.update({ visible: false });
|
||
review.update({ visible: true });
|
||
review.remove();
|
||
```
|
||
|
||
省略 `label` 即为只有图标的标题栏按钮。在宽布局中，菜单和弹出框会显示一个 V 形箭头。Paseo 会把多出来的
|
||
贡献移入一个共享的溢出菜单。在手机和较窄的窗口中，标题栏没有空间放置插件按钮，因此每个按钮都会成为工作区
|
||
菜单（`···`）中的一行，显示它的图标和标题；它的菜单和弹出框以该底部面板中的页面打开。位置和溢出由宿主决定。
|
||
|
||
## Composer 胶囊 {#composer-pills}
|
||
|
||
`client.addComposerPill({ id, workspaceId, agentId, button })` 使用同样的[按钮描述符](#button-descriptor)，
|
||
并返回同样的注册对象。它面向某个 Agent 的 Composer 栏，与 Tasks 和 Subagents 并列。Composer 胶囊始终
|
||
显示图标和 `label`（省略 `label` 时显示 `title`）。它们从不显示箭头，菜单和弹出框也一样。
|
||
|
||
```tsx
|
||
const pill = client.addComposerPill({
|
||
id: "review",
|
||
workspaceId,
|
||
agentId,
|
||
button: {
|
||
title: "Open review",
|
||
icon: "Scan",
|
||
label: "Review",
|
||
behavior: {
|
||
kind: "action",
|
||
onPress() {
|
||
client.openPanel("review", { workspaceId, agentId });
|
||
},
|
||
},
|
||
},
|
||
});
|
||
```
|
||
|
||
对于随 Agent 目录变化的胶囊，请使用显式的[自有列表订阅](/docs/sdk/events#follow-one-agents-status)。
|
||
[本地插件示例](https://github.com/getpaseo/paseo/blob/main/plugin-examples/local-plugin/client/main.tsx)
|
||
会在每次快照时替换注册，并在入口清理时中止观察，包括尚未完成的引导过程。
|
||
|
||
## 按钮描述符 {#button-descriptor}
|
||
|
||
这些契约从 `@getpaseo/plugin/client` 导出。
|
||
|
||
| 字段 | 是否必填 | 含义 |
|
||
| ---------- | -------- | ------------------------------------------------------------------ |
|
||
| `title` | 是 | 非空的无障碍标签、提示文字和底部面板标题。 |
|
||
| `icon` | 是 | Lucide 名称、`{ svg }` 或 `ComponentType<PluginButtonIconProps>`。 |
|
||
| `label` | 否 | 非空的显示文字。省略时使用该位置的默认值。 |
|
||
| `visible` | 否 | 默认为 `true`。为 false 时移除触发器及其占用的布局空间。 |
|
||
| `disabled` | 否 | 默认为 `false`。按钮保持可见，但无法交互。 |
|
||
| `behavior` | 是 | 下面三种形式之一。 |
|
||
|
||
```tsx
|
||
type PluginButtonBehavior =
|
||
| { kind: "action"; onPress(): void | Promise<void> }
|
||
| { kind: "menu"; items: readonly PluginButtonMenuEntry[] }
|
||
| { kind: "popover"; Content: React.ComponentType<PluginButtonContentProps> };
|
||
```
|
||
|
||
操作在客户端运行。在 promise 完成之前，Paseo 会把按钮标记为忙碌，阻止重复按下，并用 toast 显示失败。
|
||
失败的操作可以重试。普通操作请使用客户端的 `paseo`，插件特有的后端工作请使用 `rpc`。
|
||
|
||
菜单和弹出框在宽布局中以锚定的浮层打开，在紧凑布局中以底部面板打开。按下整个触发器都会打开浮层；没有
|
||
分体按钮的行为。
|
||
|
||
### 菜单项 {#menu-entries}
|
||
|
||
菜单包含条目和分隔线。ID 由小写字母、数字和连字符组成，以字母开头，并且在该菜单内唯一。
|
||
|
||
```tsx
|
||
const behavior: PluginButtonBehavior = {
|
||
kind: "menu",
|
||
items: [
|
||
{
|
||
kind: "item",
|
||
id: "refresh",
|
||
title: "Refresh review",
|
||
icon: "RefreshCw",
|
||
behavior: { kind: "action", onPress: refreshReview },
|
||
},
|
||
{ kind: "separator", id: "details-divider" },
|
||
{
|
||
kind: "item",
|
||
id: "details",
|
||
title: "Review details",
|
||
behavior: { kind: "popover", Content: ReviewDetails },
|
||
},
|
||
],
|
||
};
|
||
```
|
||
|
||
条目需要 `kind: "item"`、`id`、`title` 和 `behavior`。它可选的 `icon`、`visible` 和 `disabled`
|
||
遵循按钮的规则。分隔线只包含 `kind: "separator"` 和 `id`。在过滤掉隐藏的条目之后，Paseo 会移除开头、
|
||
结尾和连续的分隔线。
|
||
|
||
条目可以使用全部三种行为。嵌套菜单在宽布局中以弹出子菜单打开，在紧凑布局中则以同一个底部面板内带返回
|
||
导航的页面打开。自定义内容页面在选中时打开，不会在悬停时打开。选择一个操作会关闭菜单；打开另一个页面
|
||
则让菜单保持打开。
|
||
|
||
### 自定义图标和弹出框内容 {#custom-icons-and-popover-content}
|
||
|
||
`PluginButtonIconProps` 包含 `theme`、`host`、`layout`、`size`、`color` 以及目标上下文。请在给定的
|
||
尺寸内渲染一个 React Native 图标或指示器。图标槽的边界和所有指针交互都由 Paseo 负责。图标组件可以使用
|
||
插件 hook。
|
||
|
||
`PluginButtonContentProps` 包含 `theme`、`host`、`layout`、目标上下文以及 `close()`。只渲染主体；锚定、
|
||
滚动、内边距和底部面板的呈现由 Paseo 负责。内容可以使用 `usePaseo`、`useRpc`、`useWorkspace`、
|
||
`useAgent` 以及该安装的 React Query 缓存。
|
||
|
||
目标上下文是以下之一：
|
||
|
||
```ts
|
||
{ context: "workspace", workspaceId: string } // Header button
|
||
{ context: "agent", workspaceId: string, agentId: string } // Composer pill
|
||
```
|
||
|
||
### 更新与生命周期 {#updates-and-lifecycle}
|
||
|
||
每个注册都属于一个插件安装、一个位置、一个工作区，以及（对于胶囊）一个 Agent。`id` 在该目标内是插件
|
||
内部的，格式与菜单 ID 相同。同一个 ID 可以用于不同的目标或位置。在同一目标中重复注册会抛出错误。
|
||
|
||
`update(patch: Partial<PluginButton>)` 原地修改描述符，保留其标识和顺序。修改 `behavior` 时，请提供
|
||
完整的新 behavior 对象。无效的更新会抛出错误，并且不会改变现有按钮。订阅你自己的模型或客户端 API，并
|
||
调用 `update` 来发布响应式的变化；修改最初的描述符不会更新 UI。
|
||
|
||
隐藏或禁用按钮会关闭它的浮层。更新它的 behavior 也会关闭浮层。隐藏会保留注册，因此再次显示时会恢复它
|
||
原来的位置。它不会取消已经在进行中的操作。
|
||
|
||
`remove()` 是幂等的。移除之后的更新不起作用。当插件安装或主机连接被拆除时，Paseo 会移除尚存的按钮。
|
||
请从客户端入口返回清理函数，用来释放你的订阅、定时器和其他资源。
|
||
|
||
## 使用 Paseo SDK {#use-the-paseo-sdk}
|
||
|
||
在界面中执行普通的 Paseo 操作请使用 `usePaseo()`。它借用所选主机现有的连接；不要再创建一个客户端。
|
||
|
||
`usePaseo()` 是你的插件唯一的 Paseo 客户端，在每个界面中都与 setup 收到的 `client.paseo` 相同。
|
||
请在清理函数中释放你订阅的内容；当插件被停用、重新加载或移除，或者它的主机消失时，Paseo 会销毁该客户端，
|
||
并结束所有仍然打开的订阅。
|
||
|
||
```tsx
|
||
import { usePaseo } from "@getpaseo/plugin/client";
|
||
import { useEffect, useState } from "react";
|
||
import { Text } from "react-native";
|
||
|
||
function ProjectChanges() {
|
||
const paseo = usePaseo();
|
||
const [changes, setChanges] = useState(0);
|
||
useEffect(() => {
|
||
const observation = paseo.observeEvents(["project.update"]);
|
||
observation.subscribe({ snapshot() {}, update: () => setChanges((count) => count + 1) });
|
||
return () => void observation.release();
|
||
}, [paseo]);
|
||
return <Text>{changes} project changes</Text>;
|
||
}
|
||
```
|
||
|
||
```tsx
|
||
import { type PluginSurfaceProps, usePaseo } from "@getpaseo/plugin/client";
|
||
import { Pressable, Text } from "react-native";
|
||
|
||
function PullRequestAction({ theme }: PluginSurfaceProps) {
|
||
const paseo = usePaseo();
|
||
|
||
async function createReviewWorkspace() {
|
||
const workspace = await paseo.workspaces.create({
|
||
title: "Review PR 42",
|
||
source: {
|
||
kind: "worktree",
|
||
cwd: "/absolute/path/to/repository",
|
||
action: "checkout",
|
||
checkoutSource: { kind: "change_request", forge: "github", number: 42 },
|
||
},
|
||
});
|
||
await workspace.agents.create({
|
||
config: { provider: "codex/gpt-5.5" },
|
||
prompt: "Review PR #42.",
|
||
});
|
||
}
|
||
|
||
return (
|
||
<Pressable accessibilityRole="button" onPress={() => void createReviewWorkspace()}>
|
||
<Text style={{ color: theme.colors.foreground }}>Create review workspace</Text>
|
||
</Pressable>
|
||
);
|
||
}
|
||
```
|
||
|
||
返回的 API 涵盖项目、工作区、Agent、终端、Provider 和 daemon 配置。其方法请参阅 [SDK API 参考](/docs/sdk/reference)。这里刻意没有连接生命周期方法，因为连接由 Paseo 负责。
|
||
|
||
### 发现主机并指定另一台主机 {#discover-hosts-and-target-another-host}
|
||
|
||
使用 `useHosts()` 显示已配置的主机，并在操作回调中使用 `getPaseoClient(serverId)` 对其中一台主机
|
||
执行 SDK 操作：
|
||
|
||
```tsx
|
||
import { getPaseoClient, useHosts, type PluginSurfaceProps } from "@getpaseo/plugin/client";
|
||
import { useMemo, useState, type ReactElement } from "react";
|
||
import { Pressable, Text, View } from "react-native";
|
||
|
||
export function HostAgents({ theme }: Pick<PluginSurfaceProps, "theme">): ReactElement {
|
||
const hosts = useHosts();
|
||
const textStyle = useMemo(() => ({ color: theme.colors.foreground }), [theme]);
|
||
const [result, setResult] = useState("");
|
||
|
||
async function listAgents(serverId: string): Promise<void> {
|
||
try {
|
||
const { entries } = await getPaseoClient(serverId).agents.list();
|
||
setResult(`${entries.length} agents`);
|
||
} catch (error) {
|
||
setResult(error instanceof Error ? error.message : String(error));
|
||
}
|
||
}
|
||
|
||
const rows = hosts.map((host) => ({
|
||
host,
|
||
onPress() {
|
||
void listAgents(host.serverId);
|
||
},
|
||
}));
|
||
|
||
return (
|
||
<View>
|
||
{rows.map(({ host, onPress }) => (
|
||
<Pressable key={host.serverId} accessibilityRole="button" onPress={onPress}>
|
||
<Text style={textStyle}>
|
||
{host.label}: {host.status}
|
||
</Text>
|
||
</Pressable>
|
||
))}
|
||
<Text style={textStyle}>{result}</Text>
|
||
</View>
|
||
);
|
||
}
|
||
```
|
||
|
||
`useHosts(): readonly PluginHostSummary[]` 包括离线的主机，并在主机、标签或状态变化时更新。
|
||
|
||
| 摘要字段 | 类型或取值 | 含义 |
|
||
| ---------- | ------------------------------------------------------------ | --------------------------------------------- |
|
||
| `serverId` | `string` | 传给 `getPaseoClient` 的 ID。 |
|
||
| `label` | `string` | 主机的显示名称。 |
|
||
| `status` | `"idle"`、`"connecting"`、`"online"`、`"offline"`、`"error"` | 当前应用的连接状态。SDK 调用需要 `"online"`。 |
|
||
|
||
`getPaseoClient(serverId: string): PaseoApi` 借用该主机已认证的应用连接。请在客户端入口代码或回调中
|
||
调用它；它不会打开 socket，也不要求目标 daemon 上安装了该插件。在执行操作时再获取 API，以便使用当前的
|
||
连接。
|
||
| 事件或条件 | 结果与调用方的处理 |
|
||
| ---------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
|
||
| 未知的主机 ID | 抛出 `Unknown Paseo host: <id>`；永远不会转到另一台主机。 |
|
||
| 主机不在线 | 抛出 `Paseo host is disconnected: <id>`，通过保留的 API 发起的调用也是如此。请在主机上线后重试。 |
|
||
| 同一连接重新连接 | 保留的 API 在重新连接后仍然可用；观察会自动恢复。 |
|
||
| 连接设置变化，或应用切换了连接（包括自动故障转移） | 旧的 API 被释放。请再次调用 `getPaseoClient(serverId)` 并重新创建订阅。 |
|
||
| 主机被移除 | 它的 API 被释放；被移除的 ID 变为未知。 |
|
||
| `client.dispose()` | 释放该 API 及其观察。之后再调用获取函数会返回一个基于应用连接的新 API。再次销毁旧的 API 不会影响新 API 的使用。 |
|
||
| 发起调用的插件被卸载 | 它借用的所有 API 和观察都会被释放，包括指向其他主机的那些。保留的句柄不能比该安装存活得更久。 |
|
||
| 界面的主机选择发生变化 | `usePaseo()` 跟随所选的主机。显式获取的 API 保持其原来的目标。 |
|
||
|
||
你也可以通过普通的 SDK API 释放单个订阅。
|
||
|
||
插件是受信任的应用代码；跨主机访问是有意设计的。摘要中不包含连接 URL 或凭据，借用的 API 也不提供连接
|
||
生命周期控制。请参阅[主机 Agent 示例](https://github.com/getpaseo/paseo/tree/main/plugin-examples/hosts)。
|
||
|
||
## 添加插件特有的后端行为 {#add-plugin-specific-backend-behavior}
|
||
|
||
插件 RPC 只用于不属于普通 Paseo 操作的工作：读取厂商 API、访问 daemon 本地资源，或者让凭据不经过客户端。
|
||
|
||
用 Zod 定义一个契约，在子进程中处理它，并从界面中调用它：
|
||
|
||
`shared/greeting.ts`：
|
||
|
||
```ts
|
||
import { defineRpc } from "@getpaseo/plugin";
|
||
import { z } from "zod";
|
||
|
||
export const greeting = defineRpc({
|
||
name: "greeting.create",
|
||
input: z.object({ name: z.string() }),
|
||
output: z.object({ message: z.string() }),
|
||
});
|
||
```
|
||
|
||
`client/greeting.tsx`：
|
||
|
||
```tsx
|
||
import { useRpc } from "@getpaseo/plugin/client";
|
||
import { greeting } from "../shared/greeting";
|
||
|
||
export function GreetingButton() {
|
||
const createGreeting = useRpc(greeting);
|
||
// Call createGreeting({ name: "Ada" }) from an event or query.
|
||
return null;
|
||
}
|
||
```
|
||
|
||
`server/greeting.ts`：
|
||
|
||
```ts
|
||
import type { RpcInput } from "@getpaseo/plugin";
|
||
import { greeting } from "../shared/greeting";
|
||
|
||
export function createGreeting({ name }: RpcInput<typeof greeting>) {
|
||
return { message: `Hello, ${name}` };
|
||
}
|
||
```
|
||
|
||
`index.client.tsx`：
|
||
|
||
```ts
|
||
import type { PluginClientContext } from "@getpaseo/plugin/client";
|
||
import { GreetingButton } from "./client/greeting";
|
||
|
||
export default function contribute(client: PluginClientContext) {
|
||
client.addScreen({ id: "main", title: "Greeting", Component: GreetingButton });
|
||
return () => {};
|
||
}
|
||
```
|
||
|
||
`index.server.ts`：
|
||
|
||
```ts
|
||
import type { PluginServerContext } from "@getpaseo/plugin/server";
|
||
import { createGreeting } from "./server/greeting";
|
||
import { greeting } from "./shared/greeting";
|
||
|
||
export default function contribute(server: PluginServerContext) {
|
||
server.handle(greeting, createGreeting);
|
||
return () => {};
|
||
}
|
||
```
|
||
|
||
输入和输出在两端都会校验。RPC 名称以小写字母开头，由小写字母、数字、点、连字符或下划线组成。`useRpc()` 返回一个带类型的异步函数。请求状态、缓存和变更请使用 TanStack Query。
|
||
|
||
后端处理函数以 `{ paseo }` 的形式收到同样的 `PaseoApi`。它们的连接属于子进程，并在插件停止时关闭。在插件代码订阅之前，它不会订阅时间线或目录事件。清理和时间线替换请遵循 [SDK 事件契约](/docs/sdk/events)。后端代码可以使用 Node API 以及安装在插件目录中的依赖。
|
||
|
||
## 调试后端输出 {#debug-backend-output}
|
||
|
||
后端贡献可以用普通的 Node 日志写入 stdout 和 stderr：
|
||
|
||
```ts
|
||
console.log("Refreshing issues");
|
||
console.error("Issue refresh failed", error);
|
||
```
|
||
|
||
当插件开始加载、就绪、开始停止以及已经停止时，Paseo 会添加 `[paseo]` 条目。它把编译和加载失败记录为
|
||
stderr 条目，包括在插件子进程启动之前发生的失败。Paseo 还会捕获初始化、RPC 处理函数、清理以及进程失败
|
||
期间产生的输出。协议通信使用单独的通道，因此 `console.log()` 不会破坏插件 RPC。
|
||
|
||
打开该插件的 **设置 → 插件 → Logs**，或者通过 daemon CLI 查看同一份最近的日志尾部：
|
||
|
||
```bash
|
||
paseo plugin logs my-plugin
|
||
paseo plugin logs my-plugin --json
|
||
paseo --host <url> plugin logs my-plugin
|
||
```
|
||
|
||
该命令返回的是一份快照，而不会持续跟随实时输出。要查看更新的条目，请刷新设置视图或再次运行该命令。每个
|
||
条目都包含时间戳、stdout 或 stderr 流、序号和消息。
|
||
|
||
Paseo 在内存中为每个插件最多保留 500 个条目和 256 KiB。单行最多 16 KiB。重新加载、停用、编译失败、
|
||
初始化失败和进程失败都会保留日志尾部。移除插件会清空它，daemon 重启则会开始新的日志尾部。结构化的副本
|
||
也会写入位于 `$PASEO_HOME/daemon.log` 的 daemon 日志。
|
||
|
||
只有 daemon 端的输出会被捕获。客户端界面的日志留在应用运行时中。不要记录凭据、访问令牌或其他机密：已连接
|
||
的用户可以读取保留的日志尾部，而 daemon 日志会把它持久保存。
|
||
|
||
## 添加 Composer 附件来源 {#add-a-composer-attachment-source}
|
||
|
||
附件来源搜索外部资源，并为 Agent 提示词返回一份稳定的文本快照。请把凭据和厂商调用放在后端处理函数中。
|
||
|
||
`shared/issues.ts`：
|
||
|
||
```ts
|
||
import { defineAttachmentSource, defineRpc } from "@getpaseo/plugin";
|
||
import { z } from "zod";
|
||
|
||
export const searchIssues = defineRpc({
|
||
name: "issues.search",
|
||
input: z.object({ query: z.string() }),
|
||
output: z.object({
|
||
items: z.array(
|
||
z.object({
|
||
id: z.string(),
|
||
identifier: z.string(),
|
||
title: z.string(),
|
||
subtitle: z.string().optional(),
|
||
url: z.string().url(),
|
||
text: z.string(),
|
||
resourceType: z.string(),
|
||
}),
|
||
),
|
||
}),
|
||
});
|
||
|
||
export const issues = defineAttachmentSource({
|
||
id: "issues",
|
||
title: "Acme issue",
|
||
icon: "CircleDot",
|
||
pickerTitle: "Attach Acme issue",
|
||
searchPlaceholder: "Search by identifier or title",
|
||
search: searchIssues,
|
||
});
|
||
```
|
||
|
||
`server/issues.ts`：
|
||
|
||
```ts
|
||
import type { RpcInput } from "@getpaseo/plugin";
|
||
import { searchIssues } from "../shared/issues";
|
||
|
||
export function search({ query }: RpcInput<typeof searchIssues>) {
|
||
return searchAcmeIssues(query);
|
||
}
|
||
```
|
||
|
||
`index.client.tsx`：
|
||
|
||
```ts
|
||
import type { PluginClientContext } from "@getpaseo/plugin/client";
|
||
import { issues } from "./shared/issues";
|
||
|
||
export default function contribute(client: PluginClientContext) {
|
||
client.addAttachmentSource(issues);
|
||
return () => {};
|
||
}
|
||
```
|
||
|
||
`index.server.ts`：
|
||
|
||
```ts
|
||
import type { PluginServerContext } from "@getpaseo/plugin/server";
|
||
import { search } from "./server/issues";
|
||
import { searchIssues } from "./shared/issues";
|
||
|
||
export default function contribute(server: PluginServerContext) {
|
||
server.handle(searchIssues, search);
|
||
return () => {};
|
||
}
|
||
```
|
||
|
||
Composer 菜单、搜索选择器、选中后的胶囊、草稿状态和提交都由 Paseo 负责。`text` 的值就是发送给 Agent 的完整快照。`icon` 是 Lucide 名称或 `{ svg }`；参见[图标](#icons)。
|
||
|
||
## 主机与生命周期 {#hosts-and-lifecycle}
|
||
|
||
插件按 daemon 安装。当同一个贡献存在于多台已连接的主机上时，Paseo 只显示一个侧边栏项，并添加一个主机选择器。所选的主机提供插件包、Paseo API、RPC 传输以及查询缓存。当所选主机离线时，调用永远不会转到另一台主机。
|
||
|
||
附件来源仍然限定在各个 Composer 所在的主机上。
|
||
|
||
工作区面板和 Command Center 条目仍然限定在当前活动的主机和确切的缓存上下文中。重新加载会替换它们的
|
||
注册。停用、移除、主机断开和求值失败会移除 Command Center 条目，并清除该安装的查询状态。已经恢复的面板
|
||
标签页会保持“不可用”状态，直到与之匹配的贡献重新出现或用户关闭它。面板的渲染失败会被限制在插件的错误
|
||
边界内。
|
||
|
||
重新加载会排在 daemon 的其他插件工作之后，例如正在运行的安装或准备命令；当插件再次运行或失败时，daemon
|
||
才会给出响应。插件的状态不能当作重新加载的结果来读取：在重新加载排队期间，`plugin ls`、设置和日志
|
||
显示的是插件之前的状态；而在 daemon 停止并启动插件期间，读取状态会得到 `failed`，因为在启动完成之前插件
|
||
不在运行时目录中。
|
||
|
||
## 插件来源 {#plugin-sources}
|
||
|
||
把以下来源标识之一粘贴到 **设置 → 插件** 中，或者传给 `paseo plugin install`。
|
||
`paseo plugin add <source>` 和 `paseo plugin install <source>` 互为别名。CLI 从你当前的工作目录解析
|
||
相对目录路径，并把 `~` 展开为你本地的主目录，同时保留任何 `:plugin/path` 后缀。使用 `--host` 时，请使用
|
||
daemon 主机上存在的绝对路径；插件文件在那台主机上读取，CLI 永远不会上传它们。在设置中输入的路径相对于
|
||
daemon 的工作目录解析，`~` 会展开为 daemon 的主目录。
|
||
|
||
| 来源 | 接受的形式 | 示例 |
|
||
| ------------------ | ----------------------------------------------------------- | --------------------------------------------- |
|
||
| 插件注册表 | `owner/slug` 或 `host/owner/slug` | `acme/review` |
|
||
| 主机目录 | daemon 主机上的绝对或相对路径 | `/srv/paseo/plugins/review` |
|
||
| GitHub 仓库 | `git:owner/repository` 或 `github:owner/repository` | `github:acme/paseo-review` |
|
||
| Git 仓库 | `git:<URL 或 SCP 来源>`；对于 URL 和 SCP 来源，前缀可以省略 | `git:https://git.example.com/acme/review.git` |
|
||
| npm 包 | `npm:<name>[@<版本、标签或范围>]`；`npm:` 可以省略 | `npm:@acme/paseo-review@^1.2.0` |
|
||
| 来源根目录下的插件 | 在目录、Git 或 npm 来源后追加 `:relative/plugin/path` | `github:acme/monorepo:plugins/review` |
|
||
|
||
Git URL 使用 `https://`、`http://`、`ssh://`、`git://` 或 `file://`。SCP 来源使用 `user@host:path`。
|
||
`file://` 选择的是 Git 获取方式，而不是目录安装。
|
||
|
||
npm 名称是小写的无作用域 `name` 或有作用域的 `@scope/name`。每个部分以字母或数字开头，之后由字母、数字、
|
||
`.`、`_` 或 `-` 组成。在包名之后，可选的 `@` 引出一个确切版本、发布标签或 npm semver 范围。省略它表示
|
||
`latest`。包含空格或比较运算符的 shell 参数请加引号。npm 别名、tarball URL 和 npm 的 `file:` 规格都不是
|
||
插件来源标识；对于这些位置，请使用目录或 Git 来源。如果一个无作用域的包同时带有选择器和子目录，请使用
|
||
`npm:` 前缀（`npm:review@1.2.0:nested`）；没有前缀时，`user@host:path` 是一个 SCP Git 来源。所选的版本、
|
||
标签或范围由包注册表校验。
|
||
|
||
Paseo 按以下顺序解析标识：
|
||
|
||
1. 裸的 `owner/slug` 是注册表 ID；本地目录来源是 `.` 或 `..`，或者以 `./`、`../`、`.\`、`..\`、`/`、`~`、Windows 盘符（`C:\` 或 `C:/`）或 UNC（`\\server\share`）前缀开头。
|
||
2. 否则，在解析子目录后缀之前，先识别 `npm:`、`github:` 或 `git:`。
|
||
`git://` 是 Git URL 的 scheme。显式的前缀会选择对应类型的获取方式。
|
||
3. 只有当末尾的 `:relative/plugin/path` 后缀不包含空的、`.` 或 `..` 段时，才把它识别为后缀。单独的
|
||
`.` 选择来源根目录。`/` 和 `\` 都可以分隔后缀中的段；跨主机时请使用 `/`。URL 端口和 SCP 来源中的
|
||
分隔符仍属于来源本身。不满足这些规则的后缀仍属于标识的一部分。
|
||
4. 裸的 `owner/slug` 通过默认插件注册表解析，`host/owner/slug` 通过该注册表主机解析。Git URL 和 SCP
|
||
来源按 Git 解析。`github:` 要求 `owner/repository` 简写；`git:` 既接受简写，也接受 URL 和 SCP 来源。
|
||
5. 剩下的 npm 包名及其可选的选择器通过主机的注册表解析。其他任何内容都会被拒绝。
|
||
|
||
默认注册表是 `https://plugins.paseo.sh`。浏览[已发布的插件](https://paseo.sh/plugins)，并用
|
||
`paseo plugin add owner/slug` 安装。注册表记录决定修订版本和插件路径。显式的 GitHub 简写请使用
|
||
`git:owner/repository`，或者使用完整的 Git URL。设置 `PASEO_PLUGIN_REGISTRY` 可以使用自托管的默认 URL，
|
||
包括路径前缀。私有注册表的凭据在 daemon 配置中使用
|
||
`pluginRegistries: { "host": { "authorization": "Bearer token" } }`。修改这些启动设置后请重启 daemon。
|
||
凭据只会发送给该注册表，永远不会发送给制品主机或重定向目标。当默认值变化时，已安装的插件保留它们记录的
|
||
来源和注册表 URL。
|
||
|
||
目录查找在 daemon 主机上进行。应用使用 `paseo-plugin.json` 中的 ID；CLI 接受 `--id <runtime-id>` 来覆盖它。
|
||
已存在的安装 ID 会被拒绝，并且不会改变它的启用状态或文件。
|
||
|
||
```bash
|
||
paseo plugin install /srv/paseo/plugins/review
|
||
paseo plugin install github:acme/paseo-review
|
||
paseo plugin install git:https://git.example.com:8443/acme/monorepo.git:plugins/review --ref main
|
||
paseo plugin install git@git.example.com:acme/review.git
|
||
paseo plugin install file:///srv/repos/monorepo:plugins/review
|
||
paseo plugin install npm:paseo-review@1.2.0
|
||
paseo plugin install npm:@acme/paseo-review@next
|
||
paseo plugin install 'npm:@acme/paseo-review@>=1.2.0 <2.0.0' --id review-staging
|
||
paseo plugin install npm:@acme/plugins@^1.2.0:plugins/review
|
||
```
|
||
|
||
`--ref` 只适用于 Git，接受用于这次安装的分支、标签或提交。没有它时，Paseo 安装远程的默认 HEAD。安装时的
|
||
选择器不会约束之后的更新。旧版的 `--path relative/plugin/path` 选项等同于子目录后缀，对 npm 也是如此。
|
||
|
||
### npm 安装与发布 {#npm-installation-and-publishing}
|
||
|
||
在 **daemon 主机**上安装带有 npm 的 Node.js，并让 `npm` 出现在 daemon 的 `PATH` 中。daemon 使用该主机的
|
||
npm 用户/全局配置和环境来选择注册表和进行认证，包括特定作用域的注册表。客户端不会下载包，也不会运行 npm。
|
||
加载、启用和重新加载已安装的插件都不需要 npm。
|
||
|
||
daemon 在一个隔离的目录中安装每个候选包及其生产依赖。激活时，它会保留完整的依赖树和 `package-lock.json`。
|
||
已安装的包和 lockfile 提供它的当前版本和制品完整性。版本、标签或范围只为这一次安装选择内容。
|
||
|
||
已安装的 lockfile 记录了这次安装解析出的结果。提交带有运行时依赖的 npm 插件的作者还必须附带
|
||
[发布锁](/docs/plugins/publishing#2-lock-installed-dependencies)。关于包的内容、准备和提交，请参阅
|
||
[发布插件](/docs/plugins/publishing)。
|
||
|
||
下载、依赖安装、manifest 检查、准备命令、编译或激活中的任何一步失败，都会丢弃候选包。其他已安装的插件继续
|
||
运行。移除 npm 插件会删除它的托管文件；移除目录插件则会保留你的源目录。
|
||
|
||
## CLI 参考 {#cli-reference}
|
||
|
||
```bash
|
||
paseo plugin init /absolute/path/to/plugin
|
||
paseo plugin install /absolute/path/to/plugin
|
||
paseo plugin install /absolute/path/to/plugin --id another-runtime-id
|
||
paseo plugin add owner/slug
|
||
paseo plugin add git:owner/repository
|
||
paseo plugin add https://git.example.com/owner/repository.git --ref main
|
||
paseo plugin add git:owner/monorepo:plugins/review
|
||
paseo plugin ls [id]
|
||
paseo plugin update <id>
|
||
paseo plugin update --all --check
|
||
paseo plugin update --all --yes
|
||
paseo plugin update my-plugin --version 1.2.0
|
||
paseo plugin update my-plugin --ref v2
|
||
paseo plugin reload my-plugin
|
||
paseo plugin logs my-plugin
|
||
paseo plugin disable my-plugin
|
||
paseo plugin enable my-plugin
|
||
paseo plugin remove my-plugin
|
||
```
|
||
|
||
`ls` 和设置页面显示来源标识和当前安装的修订版本，而不会联系远程。标识包含所选的子目录，不包含安装时的
|
||
选择器。
|
||
|
||
`update <id>` 检查更新，显示当前和拟更新的修订版本以及可用的审查链接，并请求批准。拒绝则保持已安装的内容
|
||
不变。
|
||
|
||
- npm 检查包的 `latest` 版本。它只会提供更新的版本；比 latest 更新的已安装版本会保持安装状态。解析由主机的
|
||
npm 注册表/认证配置决定。
|
||
- Git 检查远程当前的默认 HEAD，不论安装时选择的是哪个分支、标签或提交。
|
||
- 目录插件会被跳过；请编辑目录并使用 `reload`。
|
||
|
||
`--check` 只做预览，即使提供了显式目标或 `--yes` 也是如此。`--yes` 跳过询问。`--all` 检查每个已配置的插件，
|
||
并分别报告结果；一个失败不会阻止其他插件。这两个标志都不允许普通的 npm 降级。
|
||
|
||
`--version <version|tag|range>` 或 `--ref <branch|tag|commit>` 为某个匹配的插件选择更新内容，并在不再询问
|
||
的情况下应用它。显式的 npm 版本可以更旧。下一次普通更新会再次检查 latest。显式目标不能与 `--all` 一起使用。
|
||
JSON 模式和非交互的普通更新需要 `--yes`。
|
||
|
||
批准后会获取被审查的那个确切提交或 npm 制品。如果它不可用，或者在审查期间已安装的插件发生了变化，更新会失败
|
||
并要求你重新检查。准备或激活失败会保留之前的安装。目前还不支持在应用中手动审查更新。
|
||
|
||
当目标不是 CLI 的默认 daemon 时，请把 `--host <url>` 放在管理命令之前。`remove` 永远不会删除目录来源；对于
|
||
Git 和 npm 来源，它会删除托管文件。安装时的 `--id` 就是运行时 ID，允许同一个目录或仓库被安装多次。
|
||
|
||
> **信任你添加的每一个插件。** `paseo plugin add` 和 `paseo plugin install` 的意思是“我信任这个代码库”。服务端代码和准备命令在 daemon 主机上以 daemon 用户的权限在沙箱外运行；客户端贡献在 Paseo 内部运行。依赖和未来的更新也属于这个决定的一部分。使用全局 `--host` 选项时，命令在远程 daemon 主机上运行。
|
||
|
||
大多数插件应省略 `build`。只有当暂存的检出必须安装 Paseo 未提供的依赖、生成源代码或资源，或者执行其他必需的
|
||
准备步骤时，才使用它：
|
||
|
||
```json
|
||
{
|
||
"id": "review",
|
||
"requirements": { "paseo": ">=0.8.0" },
|
||
"build": [["npm", "ci", "--omit=dev"]]
|
||
}
|
||
```
|
||
|
||
`build` 是一个由非空 argv 数组组成的列表。在解析出确切的提交和 manifest 之后，Paseo 从暂存的插件目录中直接
|
||
运行每个可执行文件，不经过 shell。它永远不会从 lockfile 推断包管理器或命令。安装和更新都会在校验、编译、激活
|
||
或替换之前运行 `build`。失败的命令会报告其输出、丢弃候选包，并保持已安装/正在运行的版本不变。daemon 日志会
|
||
记录每条命令及其输出；使用全局 `--host` 选项时，命令在该 daemon 主机上执行。
|
||
|
||
在安装或重新加载之前运行 `npm run typecheck`。请用 CLI 或设置页面管理插件来源条目；安装语法请参阅
|
||
[插件来源](#plugin-sources)。
|
||
|
||
daemon 级别的 **启用插件** 开关位于 **设置 → 插件** 下。只有当这个开关和插件自身的启用状态都打开时，已配置的插件才会运行，否则它会保持 `disabled`。
|
||
|
||
这个开关是 `config.json` 中根级的 `pluginsEnabled` 字段。修改后请运行 `paseo reload --json`。启用会启动所有自身 `enabled` 值不为 `false` 的已配置插件；停用会拆除所有插件。不需要重启 daemon。手动编辑的插件来源条目不会被重新加载；这些请使用插件生命周期命令。
|
||
|
||
## 加载失败 {#load-failures}
|
||
|
||
使用 `paseo plugin ls` 读取当前的状态和错误。
|
||
|
||
| 症状 | 检查 |
|
||
| --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
|
||
| `This plugin was made for an older version of Paseo` | 目录中只有 `index.ts` 入口。请按照[迁移指南](/docs/plugins/migration)操作。 |
|
||
| `Plugin entry points are missing` | 不存在名称完全一致的 `index.client.tsx` 或 `index.server.ts`。 |
|
||
| `server-only module cannot be imported into the plugin client bundle` | 客户端代码导入了 `server/`。把这部分工作移到 RPC 之后，并从 `shared/` 导入它的契约。 |
|
||
| `client-only module cannot be imported into the plugin server bundle` | 服务端代码导入了 `client/`。改为从 `index.client.tsx` 注册该贡献。 |
|
||
| `Node module cannot be imported into the plugin client bundle` | 客户端代码导入了 `node:*`。把该操作移到 `server/`，并通过 RPC 调用它。 |
|
||
| 侧边栏项缺失 | 确认插件处于 `running` 状态，该项没有在 **设置 → 侧边栏** 中被隐藏，它的组件没有抛出错误，并且客户端连接的是该安装所在的主机。 |
|
||
| 客户端模块不可用 | 只导入上面列出的、由宿主提供的客户端模块。 |
|
||
| RPC 被拒绝 | 检查两个 Zod schema 以及 daemon 端处理函数的错误。 |
|
||
| 修改后的代码没有生效 | 运行 `npm run typecheck`，然后运行 `paseo plugin reload <id>`。 |
|
||
| 重新加载失败 | 读取 `paseo plugin ls` 和 `paseo plugin logs <id>`，修复源代码错误后再重新加载；Paseo 不会恢复之前的插件包。 |
|
||
| 插件意外退出 | 读取 `paseo plugin logs <id>`，查看保留的初始化、清理、stderr 以及最终崩溃的输出。 |
|