Node.js SDK

处理器、调用、面板 UI 构建器与上下文对象 —— agentty-plugin.mjs 的全部能力。

agentty-plugin.mjs 是一个无依赖的单文件,类型定义在同目录的 agentty-plugin.d.ts 中。在插件页面点击开发者指南,Agentty 会把两者解压到 ~/.agentty/plugins/.sdk/。

Note

这样写出来的插件会在用户机器上以程序方式运行,需要 PATH 里有 Node.js 18 及以上,并且从文件夹或 Git 仓库安装。插件市场只收录 WebAssembly 模块——那条路见 Rust 与 WebAssembly。

js
import { createPlugin, ui } from './agentty-plugin.mjs';

const plugin = createPlugin();
// 注册处理器…
plugin.start();

所有处理器都要在调用 start() 之前注册。

处理器#

处理器都可以是 async 的。错误会被记录,并作为通知显示给用户。

处理器触发时机
onActivate(info => …)插件已启动;info 中有 plugin.dataDir、language、context
command(id, ({ context, args }) => …)命令从命令面板被执行
tool(name, handler)AI 智能体调用工具;处理器接收 { args, context } 并返回答复。错误作为工具错误发送
onPanelOpen(context => …)面板变为可见 —— 在这里绘制
onPanelClose(context => …)面板被隐藏
onEvent(elementId, (event, context) => …)该 id 的 UI 元素被操作
onAnyEvent((event, context) => …)onEvent 未处理的所有 UI 事件
onContextChange(context => …)聚焦窗格、其状态或文件夹发生变化
onUrl(path, ({ path, query, url }) => …)agentty://plugin/<id>/<path>?… 被打开
onShutdown(() => …)Agentty 正在停止插件

调用#

所有调用都返回 promise。

调用权限
setPanel(tree) —— 替换面板内容
showPanel() —— 打开本插件的面板
notify(message, kind) —— info、success、warning、error
setBadge(text) —— 标签栏按钮上最多 8 个字符
getContext()
hostInfo() — Agentty 版本、API 版本、语言,以及能绘制的面板元素(uiFeatures)
openUrl(url) —— http/https
copy(text) —— 复制到剪贴板
revealPath(path) —— 在文件管理器中显示workspace.read
injectPrompt(request)prompt.inject
sendToTerminal({ paneId, text, submit })terminal.write
setTerminalProxy({ port, token }) · setTerminalProxy({ port: null })terminal.proxy
getSession({ paneId, maxTurns })session.read
listWorkspaces()workspace.read
fetch(request) —— HTTP 请求net.request
log(...) —— 写入插件日志(stderr)

协议里还有 storage/get、storage/set 和 storage/keys(插件自己文件夹里的一个 JSON 文档,不需要权限;打开设置同步后会同步到用户的其他电脑),以及从 API 版本 2 起的 host/timer 和 pane/status。Node 插件也可以自己写文件,但 storage 对两种插件的行为是一样的。见协议。

plugin.info 保存 initialize 的数据,plugin.context 是最新的上下文。

面板#

面板宽 360px,可纵向滚动。插件用一棵树来描述它,由 Agentty 原生绘制,因此外观与应用一致,也不需要网页视图。任何变化时发送一棵新树即可;除非你发送不同的 value,文本框会保留用户输入的内容。

构建器元素事件
ui.column(children, { gap }) / ui.row(children, { gap, wrap })布局。gap: none、small、medium、large
ui.section(title, children)带标题的分组
ui.text(text, style)body、title、muted、small、code、error、success
ui.button(id, label, { icon, variant, disabled })primary、secondary、ghost、dangerclick
ui.input(id, { placeholder, value, rows })单行输入;rows 大于 1 时为该行数的文本域(最多 24)停止输入后 change,回车时 submit;event.value 为文本
ui.list(id, items, { empty })行 { id, title, subtitle, detail, icon, tone, actions }带 event.item 的 select;行内按钮发送带 event.item 和 event.action 的 action
ui.choice(id, [{ value, label }], value)分段选择带取值的 change
ui.toggle(id, label, value)开关带新布尔值的 change
ui.badge(text, tone)neutral、info、success、warning、error
ui.spinner(text)
ui.divider()
ui.flow(id, steps)步骤 { id, title, subtitle, icon, state, selected, side };state: off、on、active、done、error带 event.item 的 select
ui.popover(id, title, children)面板旁边的卡片close
ui.card(children, { title, subtitle, icon, tone })浮起的方框;tone 决定图标和边框颜色(API 4)
ui.grid(children, { columns, gap })1–6 个等宽列(API 4)
ui.tabs(id, [{ id, label, icon, badge }], value, children)标签页;children 是选中标签页的内容(API 4)带标签页 id 的 change
ui.table(id, [{ label, align, grow }], [{ id, cells, tone }], { empty, selected })表头下的行(API 4)带 event.item 的 select
ui.keyValue([{ label, value, tone, mono }])标签与值(API 4)
ui.stat(label, value, { detail, icon, tone })醒目显示的一个数字(API 4)
ui.progress(value, { label, detail, tone })进度条,value 取 0 到 1(API 4)
ui.callout(text, { title, icon, tone })带颜色的提示,默认 info(API 4)
ui.select(id, [{ value, label }], value, { placeholder, disabled })下拉框(API 4)带取值的 change
ui.checkbox(id, label, value, { description, disabled })复选框(API 4)带新布尔值的 change
ui.code(text, { language, title })着色的代码和复制按钮(API 4)

null 与 false 的子元素会被跳过,因此 条件 && ui.text('…') 可以直接使用。

什么内容该用哪个元素,以及可以直接起步的完整界面,见 设计面板。标为 API 4 的元素需要在清单中写上 "apiVersion": 4。

js
plugin.onPanelOpen(async (context) => {
  const notes = await search('');
  plugin.setPanel(
    ui.column([
      ui.input('q', { placeholder: 'Search notes' }),
      ui.list('notes', notes.map((n) => ({
        id: n.path,
        title: n.title,
        subtitle: n.folder,
        icon: 'notebook',
        actions: [{ id: 'insert', icon: 'send', tooltip: 'Insert into the focused pane' }],
      })), { empty: 'No notes yet' }),
    ]),
  );
});

plugin.onEvent('notes', (event, context) => {
  if (event.event === 'action' && event.action === 'insert') {
    return plugin.injectPrompt({ text: read(event.item), target: 'ask' });
  }
});
Note

限制:2,000 个元素、12 层深度、每个字符串 20,000 字符;choice 的选项和列表项的按钮也计入元素。面板最快每 50ms 重绘一次,通知最快每 700ms 一条。每秒发送超过 240 条消息的插件会被视为失控并停止。

上下文#

每个命令、事件和面板调用都会带上聚焦窗口的上下文:

json
{
  "workspace": { "id": 3, "name": "agentty", "cwd": "/Users/me/agentty", "active": true },
  "pane": {
    "id": 12,
    "kind": "claude",
    "tool": "claude",
    "title": "Claude Code",
    "cwd": "/Users/me/agentty",
    "sessionId": "…",
    "status": "idle",
    "running": true
  },
  "language": "zh"
}

能看到多少取决于你声明的权限。文件夹与名称字段(workspace.cwd、workspace.name、pane.cwd、pane.title)需要 workspace.read,pane.sessionId 需要 session.read。没有这些权限时,上下文仍带有 id、kind、tool、status、running 和语言:足以知道哪个窗格处于焦点,但不知道用户在哪里工作。

kind 为 claude、codex 或 shell;其他智能体 CLI 运行在 shell 窗格中,由 tool 标明名称。

status含义
idle等待输入
working正在运行工具
thinking一轮进行中,处于工具调用之间
finished本轮结束
permission正在请求许可
question正在向用户提问
interrupted被用户中断
shell普通 shell
exited程序已退出

判断是否打扰时,把 working 和 thinking 同等看待。

发送提示词#

js
await plugin.injectPrompt({
  text: 'Continue the release checklist.',
  title: 'Release',          // 新会话的工作区名称,也是对话框标题
  target: 'ask',             // ask | active | newWorkspace | newTab | pane | workspace
  agent: 'claude',           // 新会话使用的 claude | codex | shell
  cwd: '/Users/me/project',  // 新会话的文件夹
  submit: true,              // 按回车(仅限智能体)
});
  • ask(默认)会弹出发送到…,由用户选择目的地。
  • active 输入到聚焦窗格,pane 输入到 paneId,workspace 输入到 workspaceId,newWorkspace / newTab 则用该提示词开启新会话。
  • 终端永远只会被输入文本 —— injectPrompt 不会按回车。
  • 超过 60,000 字节的提示词会保存到 ~/.agentty/prompts/,并让智能体去读取该文件。在 Windows 上,长到放不进智能体命令行的提示词(约 30,000 个字符)也会这样处理。

凡是由其他应用或链接发起的,请使用 ask。

AI 智能体的工具#

js
plugin.tool('list_containers', async ({ args }) => {
  const containers = await listContainers({ all: args.all === true });
  return containers.map((c) => `${c.name}: ${c.state}`).join('\n');
});

在调用 plugin.start() 前注册工具。当智能体调用工具时,它会获得你的答复(字符串、任意 JSON 值或 MCP 格式的内容)。处理器中抛出的错误会作为工具错误发送给智能体。

为了提供工具,插件必须声明 mcp.tools 权限和 apiVersion: 5。每个插件最多 32 个工具。查看清单参考了解架构和限制。

会话与终端#

要让新开的终端经过代理,请声明 terminal.proxy 权限和 apiVersion: 6,然后调用 plugin.setTerminalProxy({ port, token })。plugin.setTerminalProxy({ port: null }) 用于停止代理。地址由 Agentty 根据端口在 127.0.0.1 上生成,插件无法把终端指向别处。详见权限。

js
const session = await plugin.getSession({ paneId: context.pane.id, maxTurns: 200 });
// { agent, sessionId, title, cwd, status, turnCount, turns: [{ role: 'user' | 'assistant', text }] }

await plugin.sendToTerminal({
  paneId: context.pane.id,
  text: 'Summarize what we did.',
  submit: true,
});

向智能体输入前请检查 pane.status:不要打断 working、permission 或 question。

接下来#