@vetta-org/plugin-sdk 0.2.0 → 0.3.1

package/docs/ability-details.md

@@ -0,0 +1,424 @@
+# 能力详情页（ability.json）
+
+`ability.json` 是插件在 Desktop「能力」页里的**可选展示描述**。它不参与插件加载，也不授予权限：
+
+- `plugin.json` 决定插件身份、入口、权限、命令和 Agent 贡献；
+- `ability.json` 只决定能力详情中的介绍内容；
+- 安装、启停、权限、命令、版本和贡献项仍由宿主固定渲染，详情文件不能覆盖这些交互。
+
+没有 `ability.json` 的插件仍能正常安装和运行。能力页会显示 `plugin.json` 提供的名称、简介、图标、作者，
+以及宿主自动生成的权限和贡献信息，但不会出现 showcase、功能网格或长篇说明。
+
+## 推荐目录
+
+```text
+my-plugin/
+├── plugin.json
+├── ability.json
+├── presentation/
+│   ├── README.md
+│   ├── README.en.md
+│   └── preview.webp
+├── src/
+└── dist/
+```
+
+`@vetta-org/plugin-vite` 发现根目录的 `ability.json` 后，会把它和整个 `presentation/` 目录打进插件 zip。
+因此，插件的 Markdown 与图片展示资源应放在 `presentation/` 下。
+
+## 最小详情
+
+身份字段必须和 `plugin.json` 保持一致：`slug = plugin.json.id`，`version = plugin.json.version`。
+
+```json
+{
+  "schemaVersion": 1,
+  "type": "plugin",
+  "slug": "my-plugin",
+  "version": "0.1.0",
+  "detail": {
+    "blocks": [
+      {
+        "type": "markdown",
+        "path": "presentation/README.md"
+      }
+    ]
+  }
+}
+```
+
+Markdown 区块可以二选一：
+
+```json
+{ "type": "markdown", "content": "## 使用方法\n\n直接写短内容。" }
+```
+
+```json
+{ "type": "markdown", "path": "presentation/README.md" }
+```
+
+`content` 与 `path` 必须且只能提供一个。长正文优先使用 `path`，避免在 JSON 字符串里手工转义换行、引号和代码块。
+路径相对插件根目录解析，不能是绝对路径，也不能用 `..` 越出插件目录。
+
+## 推荐的丰富详情
+
+```json
+{
+  "schemaVersion": 1,
+  "type": "plugin",
+  "slug": "my-plugin",
+  "version": "0.1.0",
+  "detail": {
+    "blocks": [
+      {
+        "type": "showcase",
+        "showcase": {
+          "template": "workbench",
+          "canvas": "code",
+          "user_prompt": "检查这个页面在手机上的效果。",
+          "assistant_reply": "我会打开预览并检查响应式布局。"
+        }
+      },
+      {
+        "type": "feature-grid",
+        "title": "主要能力",
+        "items": [
+          {
+            "title": "实时预览",
+            "description": "在工作区中直接查看页面。",
+            "icon": "solar:monitor-smartphone-linear"
+          },
+          {
+            "title": "继续交给 Agent",
+            "description": "把检查结果带回当前任务继续修改。",
+            "icon": "solar:magic-stick-3-linear"
+          }
+        ]
+      },
+      {
+        "type": "markdown",
+        "path": "presentation/README.md"
+      },
+      {
+        "type": "links",
+        "title": "相关资源",
+        "items": [
+          { "label": "使用文档", "href": "https://example.com/docs" }
+        ]
+      }
+    ],
+    "meta": [
+      { "key": "homepage", "value": "https://example.com" },
+      { "key": "repository", "value": "https://github.com/example/my-plugin" }
+    ]
+  }
+}
+```
+
+## 区块参考
+
+区块按数组顺序渲染。宿主只接受下列白名单类型，不执行包内 HTML、JavaScript、CSS、iframe 或自定义操作。
+如果需要兼容尚未支持新区块的旧版客户端，请在整页 `format: "blocks"` 声明中提供 `fallback` Markdown；旧版校验失败时会回退到该文件。
+
+### hero
+
+封面承诺，适合详情页开头。它只描述一句主张、徽章和可选配图；宿主把它画成带侧线的引言，而不是能力清单或右侧 Logo 栏。
+
+```json
+{
+  "type": "hero",
+  "eyebrow": "REAL BROWSER AUTOMATION",
+  "title": "让 Agent 在你看得见的浏览器里工作",
+  "description": "复用登录态，完成多步骤网页任务；提交前始终确认。",
+  "image": "presentation/preview.webp",
+  "image_alt": "在可见窗口中完成登录",
+  "layout": "stacked",
+  "badges": ["可见窗口", "会话隔离"]
+}
+```
+
+`layout` 可选 `stacked`（默认：主张在上、配图在下）或 `split`（有配图时文案与图片左右分栏）。没有 `image` 时不会留下空栏。配图必须是场景静帧；`icon.png` / `logo.svg` 以及与能力图标同一张图会被宿主忽略，避免再画一遍页头 Logo。
+
+### stats
+
+用少量数字或短词概括适用范围、规模和关键约束。宿主把 `value` 放进色块，右边跟标签和说明，排成度量行；不拉成通栏 KPI，也不需要填写列数。
+
+```json
+{
+  "type": "stats",
+  "title": "适合哪些任务",
+  "items": [
+    { "value": "真实", "label": "页面环境", "description": "不是静态 HTML" },
+    { "value": "多步", "label": "任务流程" },
+    { "value": "可控", "label": "关键动作", "description": "提交前人工确认" }
+  ]
+}
+```
+
+最多 6 项。`value` 和 `label` 必填，`description` 可省略。
+
+### gallery
+
+展示多张界面截图或流程图。图片可以是插件包内的 `presentation/**` 文件，也可以是 HTTPS 地址；不接受 HTML、iframe 或脚本。
+
+```json
+{
+  "type": "gallery",
+  "title": "工作流预览",
+  "items": [
+    {
+      "src": "presentation/step-1.webp",
+      "alt": "打开网站并等待登录",
+      "caption": "1. 在可见窗口中完成登录"
+    },
+    {
+      "src": "presentation/step-2.webp",
+      "alt": "读取页面快照",
+      "caption": "2. Agent 根据页面结构定位内容"
+    }
+  ]
+}
+```
+
+图片按自适应网格排列，最多 8 张；`alt` 和 `caption` 可省略，但建议为截图提供有意义的 `alt`。
+
+### comparison
+
+解释两种方式、适用边界或「之前 / 之后」。左右是两份独立论点，宿主不会按行一一对应。`tone` 决定这一列是不是选中面板：中性列是带减号的未选列表，强调列是带勾选和主色描边的选中面板。默认左列 `neutral`、右列 `accent`。
+
+```json
+{
+  "type": "comparison",
+  "title": "从查资料到完成任务",
+  "left": {
+    "title": "只做网页搜索",
+    "items": ["返回搜索结果", "遇到登录态就中断"]
+  },
+  "right": {
+    "title": "使用 Browser",
+    "tone": "accent",
+    "items": ["打开真实网站", "提交前交还人工确认"]
+  }
+}
+```
+
+`tone` 可选 `neutral` 或 `accent`；默认左列为 `neutral`、右列为 `accent`。每列最多 8 条。
+
+### feature-grid
+
+能力清单：并列主张，不是先后步骤。宿主按短条目自动并排，不需要填写列数。`items` 至少一项，图标可省略；图标支持 `solar:` 或包内/HTTPS 图片。
+
+```json
+{
+  "type": "feature-grid",
+  "title": "主要能力",
+  "items": [
+    { "title": "读取页面", "description": "提取页面结构与文字。", "icon": "solar:document-text-linear" }
+  ]
+}
+```
+
+### steps
+
+有先后顺序的流程。宿主画成带序号和连线的步骤轨，文案一次全部可见。
+
+```json
+{
+  "type": "steps",
+  "title": "开始使用",
+  "items": [
+    { "title": "安装插件" },
+    { "title": "授予权限", "description": "只开启任务实际需要的权限。" }
+  ]
+}
+```
+
+### showcase
+
+宿主生成的场景头图，不是真实截图，也不能由插件注入 CSS。插件只选择 `template`、`canvas` 和文案；
+窗体外形、舞台和对话样式全部由 Desktop 绘制。
+
+`template` 决定构图，不只是「一问一答」：
+
+| template | 构图 |
+| --- | --- |
+| `canvas-hero` | 大号产品窗口 + 一句说明；提示词收成角标 |
+| `prompt-result` | 左侧提示词卡片，右侧变成产物窗口 |
+| `spotlight` | 居中命令面板：检索条 + 高亮结果 |
+| `workbench` | 迷你工作台：活动栏 + 窗口 + 助手批注 |
+| `chat-over-canvas` | 产品窗口为主角，对话作为附注 |
+| `chat-thread` | 完整会话窗口（顶栏、消息、输入条） |
+
+需要产品窗口的模板再选 `canvas`。每种 canvas 是可辨认的窗体外形，不是同一外壳里换几根色条：
+
+| canvas | 窗体 |
+| --- | --- |
+| `design` | 点状画板 + 带控制点的 Frame |
+| `code` | 编辑器：文件页签、行号、状态栏 |
+| `docs` | 纸页文档 + 清单 |
+| `browser` | 浏览器：标签、地址栏、页面列表 |
+| `terminal` | 深色终端与提示符 |
+| `board` | 三列看板 |
+| `generic` | 指标卡 + 趋势图的仪表盘 |
+
+```json
+{
+  "type": "showcase",
+  "showcase": {
+    "template": "canvas-hero",
+    "canvas": "browser",
+    "brand_name": "Orders",
+    "user_prompt": "打开后台订单页。",
+    "assistant_reply": "我会在真实浏览器里读取页面，提交前先停下来确认。"
+  }
+}
+```
+
+`user_prompt` 与 `assistant_reply` 在非对话模板里也会用到：分别作为提示词/检索条和结果说明。
+可选 `brand_name`、`brand_icon_url` 会出现在窗体标题或页签上。
+
+### image
+
+展示真实图片。包内资源建议放进 `presentation/`；也可使用 HTTPS 图片。
+
+```json
+{
+  "type": "image",
+  "src": "presentation/preview.webp",
+  "alt": "插件界面预览",
+  "caption": "工作区主界面"
+}
+```
+
+### callout
+
+提示块；`tone` 支持 `info`、`success`、`warning`。
+
+```json
+{
+  "type": "callout",
+  "tone": "info",
+  "title": "首次使用",
+  "content": "启用前需要完成本地运行时安装。"
+}
+```
+
+### markdown
+
+Markdown 正文，支持内联 `content` 或包内文件 `path`。代码块由宿主统一高亮。
+
+```json
+{ "type": "markdown", "path": "presentation/README.md" }
+```
+
+### links
+
+HTTP(S) 外链按钮。
+
+```json
+{
+  "type": "links",
+  "title": "继续阅读",
+  "items": [{ "label": "文档", "href": "https://example.com/docs" }]
+}
+```
+
+## 整页引用文件
+
+如果详情只有 Markdown，不需要 `blocks`：
+
+```json
+{
+  "schemaVersion": 1,
+  "type": "plugin",
+  "slug": "my-plugin",
+  "version": "0.1.0",
+  "detail": {
+    "format": "markdown",
+    "path": "presentation/README.md"
+  }
+}
+```
+
+也可以把全部结构化区块放进独立 JSON：
+
+```json
+{
+  "detail": {
+    "format": "blocks",
+    "path": "presentation/detail.json",
+    "fallback": "presentation/README.md"
+  }
+}
+```
+
+此时 `presentation/detail.json` 的格式为：
+
+```json
+{
+  "schemaVersion": 1,
+  "blocks": [
+    { "type": "markdown", "path": "presentation/README.md" }
+  ]
+}
+```
+
+`fallback` 只在结构化详情文件无法读取或校验失败时生效。
+
+## 多语言
+
+详情页的 `i18n` 与 `plugin.json` 的 `%catalogKey%`/`locales/*.json` 是两套合同。详情文件不解析
+`%catalogKey%`；应在 `ability.json#detail.i18n` 中提供本地化内容或文件路径。
+
+```json
+{
+  "detail": {
+    "blocks": [
+      { "type": "markdown", "path": "presentation/README.md" }
+    ],
+    "i18n": {
+      "en": {
+        "blocks": [
+          { "type": "markdown", "path": "presentation/README.en.md" }
+        ]
+      }
+    }
+  }
+}
+```
+
+本地化字段采用**整体覆盖**：一旦 `i18n.en.blocks` 存在，它会替换默认的整个 `blocks` 数组，不做逐项合并。
+因此，多语言丰富详情需要在每个 locale 中给出完整区块序列。
+
+## 元信息
+
+`detail.meta` 是有序数组。预置 `key` 支持 `homepage`、`repository`、`docs`、`license`；也可使用
+`label` 创建自定义文本项。以 `http://` 或 `https://` 开头的值会渲染成链接。
+
+```json
+{
+  "meta": [
+    { "key": "docs", "value": "https://example.com/docs" },
+    { "label": "维护团队", "value": "Example Team" }
+  ]
+}
+```
+
+## 安全与大小限制
+
+- `ability.json` 最大 64 KiB；
+- 单个 Markdown/结构化详情文件最大 512 KiB；
+- 单张本地图片最大 8 MiB；
+- 包内引用必须留在插件根目录；
+- 图片只接受 AVIF、GIF、ICO、JPEG、JPG、PNG、SVG、WebP；
+- 外部图片只接受 HTTPS；链接按钮接受 HTTP(S)；
+- 详情损坏不会阻断插件或能力页启动，宿主会忽略该插件的自定义介绍并记录诊断日志。
+
+## 发布前检查
+
+- `ability.json` 的 `slug`、`version` 与 `plugin.json` 完全一致；
+- 长 Markdown 使用 `path`，文件位于 `presentation/`；
+- `i18n` 中的 `blocks` 是完整数组；
+- 图片路径大小写与归档中的真实文件一致；
+- `bunx vite build` 生成的 zip 包含 `ability.json` 和 `presentation/**`；
+- 安装后在「能力 → 我的」打开插件详情，核对宿主自动生成的权限和贡献项是否符合预期。

package/docs/ai.md

@@ -0,0 +1,121 @@
+# AI 文本能力
+
+`ctx.ai` 让插件调用用户已经在 Vetta 中配置的文本模型。模型发现、默认模型解析、API Key 与登录凭据注入、实际请求都由 Desktop 主进程负责；插件只能看到脱敏后的模型描述与完成结果。
+
+## 权限
+
+- `ai.models.list`：调用 `ctx.ai.listModels()`。
+- `ai.complete`：调用 `ctx.ai.complete()`、`ctx.ai.stream()` 或 `ctx.ai.chat()`，可能产生模型费用或消耗用户额度。
+
+两项权限独立。只知道固定模型标识的插件可以仅声明 `ai.complete`；需要展示模型选择器时再同时声明 `ai.models.list`。
+
+## 列出模型
+
+```ts
+const { defaultModel, models } = await ctx.ai.listModels();
+
+const options = models.map((model) => ({
+  value: model.modelKey,
+  label: model.name,
+  provider: model.provider,
+}));
+```
+
+列表只包含当前可用且支持文本输入的模型。`modelKey` 使用 `provider/model` 格式；`defaultModel` 只有在用户设置的默认模型当前可用时才返回，否则为 `null`。
+
+## 完成文本
+
+```ts
+const result = await ctx.ai.complete({
+  modelKey: selectedModelKey,
+  systemPrompt: "在不改变含义的前提下优化用户提示词。只返回优化结果。",
+  prompt: userPrompt,
+  temperature: 0.3,
+  maxTokens: 1200,
+});
+
+console.log(result.text, result.usage.totalTokens);
+```
+
+`modelKey` 可省略，此时宿主使用用户明确设置且当前可用的默认模型；没有可用默认模型时调用会失败。`reasoning` 只会传给声明支持推理的模型，`maxTokens` 不会超过该模型自身的输出上限。
+
+`complete` 是单轮契约（`systemPrompt + prompt`），不接受工具或图片。多轮对话使用下方的 `chat`；插件提供 API Key 仍然不被接受——凭据永远由宿主注入。
+
+## 流式完成
+
+`ctx.ai.stream()` 与 `complete()` 接受相同请求并返回相同的最终结果，但会在生成期间通过
+`onTextDelta` 交付增量文本。`delta` 是本次新增片段，`text` 是截至当前事件的完整文本；UI 通常直接使用
+`text` 更新同一条消息，完成后再使用 Promise 返回值保存最终结果。
+
+```ts
+const controller = new AbortController();
+
+const result = await ctx.ai.stream(
+  {
+    modelKey: selectedModelKey,
+    systemPrompt: "使用 Markdown 回答；公式使用 LaTeX。",
+    prompt: userPrompt,
+    maxTokens: 1600,
+  },
+  {
+    signal: controller.signal,
+    onTextDelta: ({ text }) => updatePreview(text),
+  },
+);
+
+await saveAnswer(result.text);
+```
+
+传入的 `AbortSignal` 取消时，宿主会中止主进程中的 Provider 请求，而不只是停止 UI 更新。事件与最终结果
+仍经过 Capability Schema 校验；模型选择、凭据、额度、错误与 usage 语义均和 `complete()` 相同。
+
+## 多轮对话 chat
+
+`ctx.ai.chat()` 是**无状态**的多轮文本完成：宿主不保存任何会话状态，插件自己持有完整消息转写（需要跨重启保留时配合 `ctx.storage` 持久化），每次调用都发送全量 `messages`。权限沿用 `ai.complete`。当前 `chat()` 只返回完整结果；需要边生成边展示的单轮文本使用 `stream()`。
+
+```ts
+const messages: PluginAiChatMessage[] = [
+  { role: "user", content: "轮到你走棋了。当前局面：…" },
+];
+
+const result = await ctx.ai.chat({
+  modelKey: selectedModelKey, // 可省略，同 complete 的默认模型解析
+  systemPrompt: "你是中国象棋棋手。",
+  messages,
+  tools: [
+    {
+      name: "make_move",
+      description: "落子。走法使用 ICCS 坐标，如 h2e2。",
+      parameters: {
+        type: "object",
+        properties: { move: { type: "string" } },
+        required: ["move"],
+      },
+    },
+  ],
+});
+```
+
+- `messages` 为全量转写，元素是 `user` / `assistant` / `toolResult` 三种角色；`assistant` 消息可携带其历史 `toolCalls`，`toolResult` 通过 `toolCallId` 与之对应。
+- `tools` 是**插件内部工具**：只对本次请求可见，模型触发时宿主不执行任何东西，只把 `toolCalls` 原样返回（`stopReason: "toolUse"`）。插件自行执行，把结果作为 `toolResult` 消息追加进 `messages` 后再次调用 `chat`，形成插件内部 loop。这类工具**不会**注册进宿主 Agent，不影响正常会话。
+- `temperature` / `maxTokens` / `reasoning` 语义与 `complete` 一致。
+
+典型 loop：
+
+```ts
+for (;;) {
+  const turn = await ctx.ai.chat({ systemPrompt, messages, tools });
+  messages.push({ role: "assistant", content: turn.text, toolCalls: turn.toolCalls });
+  if (turn.stopReason !== "toolUse") break;
+  for (const call of turn.toolCalls) {
+    const outcome = runLocalTool(call); // 插件内部执行，例如校验并落子
+    messages.push({
+      role: "toolResult",
+      toolCallId: call.id,
+      toolName: call.name,
+      content: outcome.text,
+      isError: outcome.isError,
+    });
+  }
+}
+```

package/docs/app-actions.md

@@ -0,0 +1,111 @@
+# 动态 App Action
+
+插件可在 `activate(ctx)` 中调用 `ctx.appActions.register()`，把 Action 动态加入 Desktop 的 Action 目录。宿主会先暂存本次 activation 的全部 Action，待 `activate` 和所有注册都成功后一次发布；任一注册失败则整次 activation 回滚。插件重载、停用、卸载或权限被撤销时，宿主会同步注销 Action 并取消执行中的请求。
+
+这使官方 Action 插件可以作为独立制品从插件服务更新，不必等待 Desktop 发版。Desktop 只维护稳定的注册协议、审批和执行边界。
+
+## 权限
+
+插件必须声明并获得两个权限：
+
+```json
+{
+  "permissions": ["app.actions.register", "app.actionHandler.execute"]
+}
+```
+
+- `app.actions.register`：向宿主 Action 目录提交可序列化声明。
+- `app.actionHandler.execute`：允许宿主把通过校验和审批的请求送到插件 handler。
+
+## 注册示例
+
+```ts
+import { definePlugin } from "@vetta-org/plugin-sdk";
+
+export default definePlugin({
+  activate(ctx) {
+    ctx.appActions.register({
+      id: "notes.list",
+      title: "List notes",
+      summary: "List notes from this plugin",
+      usage: {
+        target: "Notes stored by this plugin",
+        useWhen: "The user wants to inspect this plugin's notes.",
+        avoidWhen: "Reading repository files or creating notes.",
+        alternatives: "Use file tools for repository files; use the note editor to create notes.",
+      },
+      effect: "read",
+      inputSchema: {
+        type: "object",
+        properties: {
+          limit: { type: "integer", minimum: 1, maximum: 100 },
+        },
+        additionalProperties: false,
+      },
+      examples: [{ description: "List ten notes", input: { limit: 10 } }],
+      async handler({ input, signal }) {
+        if (signal.aborted) throw new Error("Action cancelled");
+        return { notes: await listNotes(input.limit ?? 10, signal) };
+      },
+    });
+  },
+});
+```
+
+插件局部 id `notes.list` 会被宿主公开为 `plugin.<pluginId>.notes.list`，避免插件之间及插件与公共 Action 冲突。`describe` 会返回原始 `inputSchema`，调用方可据此生成输入。
+
+可信官方插件还可声明 `publicId`，例如 `publicId: "general.query"`。若该 id 已被其它实现占用，后到的注册会被忽略并记日志（先注册为准）。普通插件使用 `publicId` 会被拒绝。门控依据宿主生成的 `trustLevel: "official"`，而不是插件 id 或安装来源；当前随包系统插件会获得该级别，远端和本地插件不会。
+
+官方插件需要读写宿主数据时使用 `ctx.official`。该 API 在 SDK 中可见，但普通插件调用会被宿主拒绝；宿主按领域提供窄 API，并通过 `pluginApiVersion` 做主版本兼容检查。`vetta-actions` 当前要求 `^2.0.0`，旧主版本或高于宿主能力的版本不会激活。
+
+## 模型选择边界
+
+`usage` 是可选的模型可见说明；建议每个 Action 声明。提供时，`target`、`useWhen`、`avoidWhen`、`alternatives` 必须都是非空字符串，宿主在 IPC 边界校验并去除首尾空白。`search` 与 `describe` 均返回这四项，因此模型在选择候选时即可知道作用对象、适用场景、排除场景与替代路径，而不只看到参数 Schema。
+
+官方 `vetta-actions` 的所有 Action 都声明使用边界。需要区分 Vetta 自身的项目、主题、插件和定时任务，与用户正在开发的软件：例如开发网页深色模式应编辑项目样式，不应修改 Vetta 主题。查询能力或解释功能也不等于要求创建、修改或执行。已有对话中明确的目标与操作意图可以继续使用，不应反复确认。
+
+检索使用能力名称、关键词、摘要、描述与操作名，不使用内部权限标识，也不索引 `usage`，避免“不要用于安装插件”等排除说明反而成为命中理由。Schema 联合分支中的 `operation` / `type` 常量及枚举仍可用于查找操作。搜索结果只是候选；调用方应核对使用说明，再通过 `describe` 获取参数，不能把命中当作执行指令。缺少 `usage` 时，需从详细说明确认目标，不能推定适用。
+
+这组字段不是授权、可信身份或执行门禁，不能关闭校验、扩大插件权限或替代审批。不要为了判断用户意图先调用写入 Action，把选择错误交给用户在审批框中处理。
+
+## effect 与审批
+
+`effect` 必须是：
+
+- `read`：只读，不触发 Action 审批。
+- `write`：修改应用或用户数据；从本地 Action RPC 调用时必须审批。
+- `execute`：启动外部执行或有明显副作用；从本地 Action RPC 调用时必须审批。
+
+插件不能绕过审批。宿主根据 `effect` 决定是否审批，并在用户批准后再次使用同一 JSON Schema 校验输入。普通插件固定使用通用审批；可信官方插件可通过 `approval` 引用宿主已有 presentation，并用 `presentationByOperation` 自动选择领域专用界面。operation 映射是宿主执行时的权威选择；调用方只能使用映射结果、通用审批或声明在 `alternativePresentationsByOperation` 中的备选界面。该能力不能注入新组件，也不能把 `write` / `execute` 改为免审批。
+
+## 运行时边界
+
+- `inputSchema` 使用 JSON Schema，由主进程在注册时编译、在执行前校验。
+- 输入、示例和返回值都必须可 JSON 序列化；否则宿主返回稳定 Action 错误。
+- `timeoutMs` 默认 30 秒，最大 120 秒。
+- 超时、调用方取消、插件重载或注销会触发 `signal.abort()`。
+- 每次执行都会重新检查插件是否启用以及两个权限是否仍有效。
+- Action 按 activation 两阶段发布，不会把注册到一半的声明暴露给 search/describe/run。
+- 同一 provider 的 staging 会完整校验后原子替换旧快照；新 activation 失败时继续使用上一版，不先卸载旧版。
+- 可选 `assertReady` 在审批前执行；审批 UI 改写输入后会再次执行。适合检查待编辑、删除或取消的实体是否仍存在。
+- `assertReady` 或 `handler` 可抛 `PluginAppActionError(code, message, details)`，宿主保留稳定错误码和 JSON 详情。`assertReady` 失败不会展示审批。
+- handler 在插件 renderer 运行，可以继续使用闭包中的 `ctx.fs`、`ctx.storage` 等 API；这些 API 各自的权限边界不变。
+
+## 迁移状态
+
+全部内置领域已由随包系统插件 `vetta-actions` 提供；Desktop **不再保留静态领域 Action 实现**。
+
+Catalog 规则：
+
+- 每个 action id **仅一份**实现。
+- **先注册为准**；后到的同 id 注册只写主进程日志（`action id conflict, keeping first registration`）并忽略。
+- 同一插件 commit 新 activation 时原子替换该 provider 的完整快照，既不被自己的旧注册挡住，也不产生热更新空窗。
+- `vetta-actions` 是 required 系统插件，不能被停用或卸载；未激活时 Catalog 返回 `ACTION_RUNTIME_NOT_READY`，而不是返回一个看似正常的空结果。
+
+## 独立发布建议
+
+官方 Action 插件可以由 Desktop 的首装流程放入插件注册表，也可以由插件服务下发更新。更新服务负责版本、灰度、回滚和签名验证；Action Runtime 不承担下载职责，只消费已经通过插件安装链验证并激活的版本。这样发布机制与执行机制解耦，远端协议变化不会扩大 Action Runtime 的可信边界。
+
+产品意义上的“内置 Action 插件”最终应当是**官方托管插件**：可附带 bootstrap 版本，更新包经过签名验证后获得 `trustLevel: "official"`。远端更新服务最后实施；在此之前远端插件不能使用公共 Action id。
+
+当前 Module Federation 插件与宿主共享 renderer JavaScript realm。`ctx.official` 的 trust gate 是宿主能力门控，但不是针对恶意插件的进程级安全隔离；同 realm 的普通插件仍可能尝试访问宿主已暴露的通用 preload API。若要把第三方插件视为不可信代码，必须另建 Worker、utility process 或独立受限 renderer，并让所有宿主能力经过按插件身份授权的消息通道。该隔离属于插件运行时演进，不应以 renderer token 代替。