插件开发
插件可以提供操作说明、外部工具、消息入口、智能体运行时和 Capsule 界面。业务程序、凭据和文件访问在选定 Desktop / Runner 上执行;声明的 UI 模块在当前客户端运行。服务端管理账户、安装、权限和路由。
从哪里开始
- 想用 OpenSDL 跑第一次仿真实验:读 OpenSDL 桌面实验快速开始。
- 想创建第一个插件:读 Quickstart,用
liyan plugin init创建独立项目,构建、导入并调用plugin.ping。 - 想确认可用接口和限制:读本页的能力类型。
- 想接入工具或排查运行问题:读开发与排障。
- 想修改宿主实现:查运行与安全和数据模型。
第三方本地工具可通过独立包开发、验证、打包和设备本地导入,使用共同的配置与执行链。这个流程无需提交 PR、合入宿主、加入官方目录或接入官方 CI。飞书提供业务工具参考,科学数据提供安装驱动的 Capsule 客户端模块参考。Quickstart 分别验证创建包、安装确认和实际调用。公共第三方下载发布、新平台消息适配和新 Agent Runtime 属于后续能力。
基本概念
以一个读取 GitHub issue 的插件为例:作者声明工具,用户安装一个版本,在自己的 Desktop 上配置 GitHub 身份,再批准读取权限。调用时,LiyanLabs 检查这些条件,并把请求发给该设备。
版本和能力属于作者声明;权限属于用户的许可。声明工具不会自动取得权限。本地 provider 即使没有外部账号,也需要在原生窗口保存真实空 profile;不应制造账号、连接或配置版本。
本文中的“摘要”(digest)是内容的 SHA-256 校验值,用来确认文件或配置没有变化。“修订”(revision)是状态修改次数;“设备代次”(generation)用于拒绝旧连接的请求;“回执”(receipt)记录设备实际完成了哪次操作。这些是校验机制,不是额外的用户授权类型。
名称与图标
作者在 plugin.json 中声明展示信息;用户导入项目目录或 package.tar.gz 时自动读取。安装表单无需另填标识、名称或上传一张独立图标。
名称与图标随版本保存。缺少展示名称时显示标识;缺少图标时使用内置品牌或通用图标。修改这些信息后提高版本并重新打包。图片格式、大小和目录要求见 Quickstart。
能力类型
本地工具 provider 没有语言白名单,但须实现私有 bootstrap、stdio MCP 初始化、完整工具发现和调用。Go 是官方模板;Python / Node.js 裸脚本没有自动收集解释器和依赖的打包支持,需交付可直接启动的产物。工具名称、输入 schema 与只读分类必须匹配声明。provider 标签可跨安装重复,一个包内须唯一。
插件聊天当前只接入本地 provider 连接器;根目录 mcp.json 的 HTTP 声明可以解析,但不代表远程 MCP 已能调用。Channel 仅支持现有飞书/GitHub 契约,外部 Runtime 声明仅保留 Claude Agent、OpenClaw、Hermes 内置适配器,聊天接管尚未接通;Codex 已通过本地 provider 提供普通异步编程工具。新平台仍需宿主实现。
科学数据的 provider 和 Web / 原生 Capsule 入口是一个插件。UI 直接运行在客户端 JavaScript 环境中,并非隔离沙箱;通过 apply(ctx, config) 注册视图和共享资源,业务调用限定于当前安装的获准只读工具。参考 plugins/science-data/client/。
OpenSDL 同样是一个完整插件:原生运行程序、官方图标、仿真、实验设备与实验流程三个 Capsule 界面一起分发,Web/Desktop 与原生移动端各有入口。它沿用专用 opensdl/2 CLI/gRPC 协议,作者声明为 nativeRuntime: "opensdl/2",没有伪造 stdio provider。这个封闭协议仅供已有 OpenSDL 适配;第三方普通工具仍使用通用本地 provider 契约。安装、启用、权限和设备在线条件全部满足后才加载 UI;未安装时不注册这些界面,也不轮询设备或加载场景。宿主的“电脑与沙箱”管理独立保留。
模块可用 ctx.files.read 读取自己的声明资源,宿主按 256 KiB 分段获取并核对完整摘要。每模块最多 128 个文件、单文件 8 MiB、合计 32 MiB。OpenSDL 的配置、启动、设备操作和摄像头调用通过当前安装的封闭接口完成;写操作遵循权限并由宿主确认。开发与验收步骤见仓库 plugins/opensdl/README.md。
第三方交付匹配目标设备的项目目录或 package.tar.gz。导入登记私有版本,之后仍须安装、确认、配置和实际调用。第一方可下载运行包按 Desktop 构建固定、按需取得,不随安装器预装。公共市场、自助远程发布和跨设备自动迁移尚未提供,均不是本地开发前置条件。
查看提供给 AI 的工具
在 Web、Desktop 或移动端打开插件详情,点击 提供给 AI 的工具 → 查看工具清单,可以展开或收起该版本声明的具体工具。右上角数量按工具计算,不是 provider 进程或 capability 的数量;一个 provider 可以提供多个工具。
每项显示原始工具名称、用途,以及“声明只读”或“可能产生修改”。例如,未修改的最小 CLI 模板显示 plugin.ping。这些信息来自作者的 toolCatalog;“声明只读”是作者的分类,不能代替用户授权或实际调用验证。
安装前、绑定设备离线时也能预览已发布的清单。展开只读取当前版本的展示元数据,不启动 provider、不连接 Runner,也不授予权限。工具要真正提供给 AI 调用,仍须安装并启用、完成配置、保持绑定设备在线,并取得当前权限。
清单在展开时按需加载并复用账户与版本缓存;加载失败可点击“重试”。未声明工具目录时显示“数量未声明”和对应说明,不能把它解释成一个工具或零个工具。预览清单也不是当前会话中已获准工具的实时列表。
第一方插件
目录来自 service/pkg/core/plugin/builtin/catalog.json;OpenSDL 的独立发行定义在 service/pkg/core/plugin/packageartifact/opensdl.json。可下载的第一方能力统一使用 desktop/scripts/plugin-release-registry.mjs 构建路径。目录可见不表示已安装或设备就绪。Codex 的 CLI 和辅助程序由选定 Runner 按需下载,登录目录由用户明确授权。OpenClaw、Hermes、Zotero 使用已有服务;目录安装与本地包导入均遵循同一设备授权和运行边界。
安装与运行
- 选择在线 Desktop 和具体版本。Desktop 使用自己的 Runner;Web / Mobile 选择在线 Desktop。
- 安装包。Runner 验证本地文件,服务端保存设备回执,再确认启用。
- 为本地 provider 保存真实设备配置(包括空配置)并审查权限。包内 setup Skill 引导 AI 初始化,原生确认仍由用户完成。首次安装保存启用意图,稍后配置不会自动禁用它。
- 检查配置是否完成,以及设备和服务连接是否健康。
- 发起业务调用。系统再次检查版本、权限和设备状态,再由绑定的 Runner 执行。
“已启用”说明包取得执行许可;“配置完成”说明所需配置和权限已保存;“健康”说明当前设备或服务可用。三者分别检查。更新或修复后需要重新启用。
选定设备离线时,界面应显示不可用。系统不会自动换设备、转到服务器执行或排队等待设备上线。如何恢复见开发与排障。
源码依据
2026-10-17 核对当前实现,包括 OpenSDL 0.5.0 安装包中的原生运行时和客户端模块。本章描述当前源码接口,不代表旧安装包已包含新能力;Quickstart 先检查 CLI 命令与模板文件。OpenSDL 上游源码固定版本记录在 service/pkg/core/plugin/packageartifact/opensdl.json。
- 作者契约与 CLI:
runner/crates/liyanlabs-plugin/、runner/crates/liyanlabs-cli/src/plugin.rs。 - 安装与模型工具:
service/pkg/core/plugin/packagecommand/、service/pkg/worker/wire_toolprep_plugin.go、service/pkg/worker/chatdriver/pluginsurface/。 - 工具预览:
service/pkg/web/views/plugins/projection.go、frontend/shared/src/hooks/usePluginToolDetails.ts、Web 的PluginToolsCard.tsx与移动端的PluginToolsNative.tsx。 - 配置与进程:
desktop/electron/src/plugins/device/、runner/crates/liyanlabs-runner/src/plugins/provider/。 - Capsule:
service/pkg/core/plugin/clientmodule/、frontend/shared/src/core/pluginClientModules/。 - 第一方发行:
desktop/scripts/plugin-release-registry.mjs、.github/workflows/plugins.yaml。完整索引见开发与排障。