开发插件与 MCP 工具

创建工具插件#

zioon extensions init my-tool --kind plugin
zioon extensions dev my-tool

模板带有 handler、SDK helper 和 npm 脚本。编辑 runtime.mjs 后自动构建，成功版本安装到当前账户，Workbench 可直接调试。源码保存在账户工作区；构建失败继续使用上一个成功版本。

注册一个工具#

import { defineToolPlugin } from "./plugin-runtime.mjs";
export const runtimePluginApiVersion = 2;
export const activateRuntimePlugin = defineToolPlugin({
  name: "hello", description: "Say hello",
  inputSchema: { type: "object", properties: { name: { type: "string" } }, required: ["name"], additionalProperties: false },
  execution: { effect: "read", idempotency: "safe" },
  async invoke({ name }) { return { ok: true, content: "Hello, " + name }; }
});

工具 effect 声明实际行为：read、write、process 或 external。平台负责权限检查、超时、取消与 durable receipt。只读示例可声明 read；不要把写入伪装成只读。

校验、打包与安装#

zioon extensions publish my-tool
zioon extensions publish my-tool --public
zioon extensions install LISTING_ID@0.1.0
zioon extensions call LISTING_ID --tool hello --args '{"name":"Zioon"}'

publish 发布当前账户的固定私有版本；--public 提交同一制品审核，要求提供来源 URL，审核通过后其他账号可安装。开发构建与发布版本分别保存，互不覆盖。

制品最多 64 个 UTF-8 文件、200KB；Runtime 开发构建含元数据最多 190KB。第三方依赖需 bundle。更新时同时提高两个 manifest 的版本。validate、pack --out 与 upload 可用于离线构建。

内网模型与设备依赖#

zioon extensions init intranet-model --kind model
zioon extensions dev intranet-model
zioon extensions configure LISTING_ID --node NODE_ID

模型 handler 接收请求 body，返回 HTTP Response；平台负责 JSON/SSE、usage、取消和流量回压。仅 JSON 的服务声明 supportsStreaming: false。模型请求走所选设备，文件和 Bash 仍可使用账户工作区。

公开设置通过 settingsSchema 声明。密钥保存在执行端私有文件，--credentials-file 只登记连接引用；模型模块固定上游地址并拒绝重定向。

接入 MCP#

zioon extensions init my-mcp --kind mcp --transport stdio
zioon extensions init my-http-mcp --kind mcp --transport http

stdio 模板提供最小服务，HTTP 模板提供 endpoint 配置。共享设备支持打包的 Node stdio 入口，并限制其文件与进程权限；其他可执行程序需账户独立工作区。当前支持工具发现与调用；resources / prompts 和服务专属 OAuth 需另外接入。

凭据值保留在 Node 本地私有文件。configure --credentials-file 只登记绝对路径；HTTP 凭据绑定扩展与精确 endpoint，连接不跟随重定向。

开发完整 Runtime 插件#

账户 SDK API 2 可注册工具、必要上下文、Run controllers、完成后后台处理、持久 jobs/events、模型和命令；可附带 Workbench 静态界面。声明所有实际能力。平台内置完整插件继续从 /v1/capabilities/tools 发现。

与会话无关的连接或设置命令可声明 requiresSession: false；依赖会话的命令保持默认要求。UI 应显示等待状态与持久错误，避免在新会话中静默失败。

Host、配置、版本和资源 epoch 由平台管理。必要上下文失败会阻止模型请求；后台处理通过持久 outbox 执行。静态 UI、Skill 与声明的模型目录在执行工作区休眠时仍可读取。