Agent 插件

把一项 agent 能力做成插件:接入唯一的工作台输入框,带上自己的卡片、面板和操作,运行时随时启停,宿主不用改代码。

一个 agent 插件就是 src/plugins/<id>/ 下的一个目录,有两个入口:给 agent 宿主的 plugin.server.ts 和给浏览器的 plugin.ts。宿主代码里不出现任何插件名。它读取每个已启用插件声明的内容(场景、Skill、卡片、面板、操作),并在内容展示给读者之前逐项校验。它是插件一文所说的后台内核里的一个插件,kind 为 "agent"。图片 Agent 是一个小插件。scripts/validate/fixtures/agent-plugin-fixture 是用到全部接入点的参考插件,校验器会实际运行它。

准备工作

  • 已安装并能运行 Agent 启动模板。
  • 为插件建一个 OpenSpec 变更:openspec-cn new change "<id>-plugin"。
  • 想好插件 id:小写短横线形式,同时也是它的模块 key。插件声明的所有 key 都以它开头。

读者看到什么

只有一个工作台 /app/agent、一个输入框。输入框旁的选择器列出 自动、通用 和所有已启用的 agent 插件。

  • 选中某个 agent,输入框换上它的附加控件,已输入的文字保留。选择随消息保存,重试旧消息时仍交给当时的 agent。
  • 选 自动 时由服务端路由。创建 Run 的响应和线程快照会给出这个 Run 所属的插件,工作台切换到该插件,并在本线程后续沿用。
  • 插件的卡片在消息流里渲染,它的工作区作为面板 tab 打开。一个线程里可以有多个插件的 Run。
  • 在 设置 → 插件 中停用插件后,页面重新获得焦点时它从选择器消失,新的 Run 和操作被拒绝,旧卡片显示摘要。重新启用后恢复。

像 /app/image 这样的插件页面,是预先选好该 agent 的工作台快捷入口。

选择接入点

只声明插件需要的部分。

插件需要声明位置
被选中和被路由到scenes、capabilityRoutes(按文字、文件类型或两者)、skills服务端
自己的输入框控件和空线程引导agent,capability 按需加载浏览器
在消息流里放结构化、可交互的内容cards(payload schema)/ cardRenderers两侧
在线程旁打开面板surfaces / surfaces两侧
让读者不经模型直接操作operations(输入、Run 状态、超时)服务端
把确认绑定到读者看到的内容validateUserAnswer(守卫、审批凭据)服务端
由服务端决定 Run 级策略hostPinnedContext服务端
保存自己类型的成品artifactKinds / artifactRenderers(<id>.<kind>)两侧
通过 HTTP 提供下载或预览/api/plugins/<id>/ 下的 api.routes服务端

每个插件都要遵守的规则

  1. key 带命名空间。 卡片、面板、操作和 artifact 类型的 key 都是 <id>.<name>。注册表会拒绝别的插件的前缀、重复的 key,以及 <id>.workspace,这个 key 留给宿主打开插件的工作区。
  2. 两侧都校验。 payload 和输入的 schema 写在插件的 contracts.ts 里(浏览器安全)。服务端在写入或执行前校验,浏览器在渲染卡片前再校验一次。
  3. 没有插件也能读。 每张卡片都带纯文本摘要。插件停用或卸载后,卡片显示摘要,该插件类型的成品改为提供下载。
  4. 隔离。 卡片和面板渲染在错误边界里。操作有超时,同一 Run 同时只执行一个操作或回答。

plugin.server.ts 里不要引入 React 和图标,因为 agent 服务会打包它。capability、卡片和面板用 import() 按需加载,这样工作台的体积不会随插件数量增长。

构建插件

下面的例子用一个 id 为 storyboard 的插件。照着 scripts/validate/fixtures/agent-plugin-fixture 的目录结构来写,只保留上面选中的接入点。

合约与清单

contracts.ts 放两侧共同约定的内容:key 和 zod schema,不引入 React,也不引入服务端模块。

src/plugins/storyboard/contracts.ts
import { z } from "zod";

export const STORYBOARD_PLUGIN_ID = "storyboard";
export const STORYBOARD_SCENE_KEY = "agent.storyboard";
export const STORYBOARD_SKILL_PACKAGE_ID = "platform.storyboard";
export const STORYBOARD_SKILL_DIRECTORY = "src/plugins/storyboard/skills/storyboard-studio";
export const STORYBOARD_CARD_KEY = `${STORYBOARD_PLUGIN_ID}.summary`;
export const STORYBOARD_CARD_SCHEMA_VERSION = 1;

export const StoryboardSummaryPayload = z
  .object({ shots: z.number().int().min(0).max(100) })
  .strict();
src/plugins/storyboard/manifest.ts
import { defineManifest } from "../kernel/types";

export const storyboardManifest = defineManifest({
  id: "storyboard",
  version: "0.1.0",
  kind: "agent",
  requires: ["agent-starter"],
});

插件在 /app 或 /admin 下有自己的页面时,再加上 routes。

服务端

声明 AgentHostExtension 并贡献到 agent.host。使用相对路径 import,因为 agent 服务会打包这个文件,而它解析不了 @/ 别名。

src/plugins/storyboard/server/extension.ts
import type { AgentHostExtension } from "../../../server/agent-extensions/types";
import {
  STORYBOARD_CARD_KEY,
  STORYBOARD_CARD_SCHEMA_VERSION,
  STORYBOARD_SCENE_KEY,
  STORYBOARD_SKILL_DIRECTORY,
  STORYBOARD_SKILL_PACKAGE_ID,
  StoryboardSummaryPayload,
} from "../contracts";

export const storyboardExtension: AgentHostExtension = {
  id: "storyboard",
  scenes: [{ sceneKey: STORYBOARD_SCENE_KEY, readinessRequired: false }],
  capabilityRoutes: [{ scene: STORYBOARD_SCENE_KEY, pattern: /\bstoryboard\b/iu }],
  skills: [{ packageId: STORYBOARD_SKILL_PACKAGE_ID, directory: STORYBOARD_SKILL_DIRECTORY }],
  cards: {
    [STORYBOARD_CARD_KEY]: {
      payload: StoryboardSummaryPayload,
      schemaVersion: STORYBOARD_CARD_SCHEMA_VERSION,
    },
  },
};
src/plugins/storyboard/plugin.server.ts
import { defineServerPlugin } from "../kernel/types";
import { storyboardManifest } from "./manifest";
import { storyboardExtension } from "./server/extension";

export const storyboardServerPlugin = defineServerPlugin({
  manifest: storyboardManifest,
  contributes: { "agent.host": [storyboardExtension] },
});

readinessRequired: false 让一个还没配模型的插件不会拖住整个 agent 服务。插件要在 /api/plugins/storyboard/ 下提供 HTTP 接口时,在同一个 contributes 里加上 api.routes。不要在任何地方检查插件自己的启停状态。插件停用期间,宿主会拒绝它的场景、Skill、操作和 API 路由。

浏览器

plugin.ts 只放元数据和加载函数。capability、卡片渲染器和面板在工作台第一次用到时才 import。

src/plugins/storyboard/plugin.ts
import { Clapperboard } from "lucide-react";
import { definePlugin } from "../kernel/types";
import {
  STORYBOARD_CARD_KEY,
  STORYBOARD_CARD_SCHEMA_VERSION,
  STORYBOARD_SCENE_KEY,
  STORYBOARD_SKILL_PACKAGE_ID,
} from "./contracts";
import { storyboardManifest } from "./manifest";

export const storyboardPlugin = definePlugin({
  manifest: storyboardManifest,
  contributes: {
    "agent.workbench": [
      {
        id: "storyboard",
        agent: {
          id: "storyboard",
          labelKey: "appConsole.storyboard",
          icon: Clapperboard,
          order: 30,
          scenes: [STORYBOARD_SCENE_KEY],
          skillPackageId: STORYBOARD_SKILL_PACKAGE_ID,
          load: () =>
            import("./workbench/capability").then(({ storyboardCapability }) => storyboardCapability),
        },
        cardRenderers: {
          [STORYBOARD_CARD_KEY]: {
            schemaVersion: STORYBOARD_CARD_SCHEMA_VERSION,
            load: () => import("./workbench/summary-card").then(({ summaryCard }) => summaryCard),
          },
        },
      },
    ],
  },
});

卡片和面板只能通过收到的 actions 操作(回答待答问题、打开 artifact 或面板、引用到输入框、runOperation),或使用 src/components/agent/extension-card.tsx 里的 useWorkbenchOperation。文案 key 要加进两份词典。

Skill

把 Skill 放在插件目录里,这里是 src/plugins/storyboard/skills/storyboard-studio,包含 skill.json 和 SKILL.md。在 skill.json 的 scenes 里写上插件的场景,allowedTools 里只写真实存在的工具。src/plugins/image-agent/skills/image-studio 是一个可用的例子。然后发布:

pnpm agent:publish-skills

扩展在 skills 里声明了这个目录,所以命令会把它和平台 Skill 一起发布,卸载插件时 Skill 也随之移除。

登记

把两半分别加进安装列表,各自写在 // @module:storyboard … // @end-module:storyboard 区段里,import 语句也放在自己的区段里:

文件条目
src/plugins/installed.tsstoryboardPlugin
src/plugins/installed.server.tsstoryboardServerPlugin

词典条目写进两份 messages.ts,放在同样标记的区段里。

分发与校验

编写 modules/storyboard/module.json:files 包含 src/plugins/storyboard/**,fragments 包含两份安装列表和两份词典,requires: ["agent-starter"],version 与清单一致,docs 写插件指南的完整地址。再加上 scripts/validate/storyboard.ts(通过真实的注册表断言插件的行为)、validate:storyboard 脚本和 validate:all 里的一段,然后运行 pnpm registry:build。参见构建模块。

验证

  1. pnpm validate:agent-plugin-contract 通过。它还会构建参考插件,并通过宿主运行每个接入点。
  2. 插件自己的校验器断言它的行为,pnpm validate:all 没有校验由通过变为失败。
  3. 在 /app/agent,选择器里有这个插件;匹配其路由的请求显示 自动 · 加插件名,并打开它的工作区 tab。
  4. 在 设置 → 插件 中停用它:页面重新获得焦点后它从选择器消失,它的卡片显示摘要。

常见问题

注册表启动时报 invalid_extension_key

某个 key 没有以插件 id 开头,或者用了 <id>.workspace。在 contracts.ts 里改名。两侧读的是同一个常量。

卡片只显示摘要

插件已停用,渲染器的 schemaVersion 比卡片旧,或者 payload 没通过渲染器的 schema。payload 结构变化时两侧版本号一起升。

消息被以 plugin_disabled 拒绝

选中的 agent 刚被停用。输入框保留文字并切回 自动,下一条消息不会再路由到它。

下一步