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 | 服务端 |
每个插件都要遵守的规则
- key 带命名空间。 卡片、面板、操作和 artifact 类型的 key 都是
<id>.<name>。注册表会拒绝别的插件的前缀、重复的 key,以及<id>.workspace,这个 key 留给宿主打开插件的工作区。 - 两侧都校验。 payload 和输入的 schema 写在插件的
contracts.ts里(浏览器安全)。服务端在写入或执行前校验,浏览器在渲染卡片前再校验一次。 - 没有插件也能读。 每张卡片都带纯文本摘要。插件停用或卸载后,卡片显示摘要,该插件类型的成品改为提供下载。
- 隔离。 卡片和面板渲染在错误边界里。操作有超时,同一 Run 同时只执行一个操作或回答。
plugin.server.ts 里不要引入 React 和图标,因为 agent 服务会打包它。capability、卡片和面板用 import() 按需加载,这样工作台的体积不会随插件数量增长。
构建插件
下面的例子用一个 id 为 storyboard 的插件。照着 scripts/validate/fixtures/agent-plugin-fixture 的目录结构来写,只保留上面选中的接入点。
合约与清单
contracts.ts 放两侧共同约定的内容:key 和 zod schema,不引入 React,也不引入服务端模块。
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();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 服务会打包这个文件,而它解析不了 @/ 别名。
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,
},
},
};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。
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.ts | storyboardPlugin |
src/plugins/installed.server.ts | storyboardServerPlugin |
词典条目写进两份 messages.ts,放在同样标记的区段里。
验证
pnpm validate:agent-plugin-contract通过。它还会构建参考插件,并通过宿主运行每个接入点。- 插件自己的校验器断言它的行为,
pnpm validate:all没有校验由通过变为失败。 - 在
/app/agent,选择器里有这个插件;匹配其路由的请求显示 自动 · 加插件名,并打开它的工作区 tab。 - 在 设置 → 插件 中停用它:页面重新获得焦点后它从选择器消失,它的卡片显示摘要。
常见问题
注册表启动时报 invalid_extension_key
某个 key 没有以插件 id 开头,或者用了 <id>.workspace。在 contracts.ts 里改名。两侧读的是同一个常量。
卡片只显示摘要
插件已停用,渲染器的 schemaVersion 比卡片旧,或者 payload 没通过渲染器的 schema。payload 结构变化时两侧版本号一起升。
消息被以 plugin_disabled 拒绝
选中的 agent 刚被停用。输入框保留文字并切回 自动,下一条消息不会再路由到它。