Skip to content

docs(plugins): 整理插件说明 #474

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
shanyuhai123 merged 1 commit into from
Oct 27, 2026
Merged

docs(plugins): 整理插件说明 #474

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
49 changes: 13 additions & 36 deletions apps/buddy/extensions/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,53 +1,30 @@
# Lexora 插件开发

## 术语与范围
插件是可安装、启用、更新和卸载的功能包，可以提供界面、文件处理、命令、Agent 工具、Skills 或主题。协议中的 `Extension` 指同一套工作台插件；它与 Agent 内部扩展的加载方式和权限边界不同。

**插件**是用户可以安装、启用、禁用、更新和卸载的功能包。代码和协议中的 `Extension`（工作台扩展）是这套插件机制的技术名称，不代表另一类可安装产品；用户界面统一使用“插件”。`extension.json`（插件清单）和 `.lexora-extension`（安装包后缀）保持不变。
- [开发文档](https://uselexora.app/plugins/)：从第一个插件到文件编辑、Agent 能力和分发。
- [本地能力索引](../service/resources/skills/plugin-creator/references/capabilities.md)：按开发目标找到接口专题。
- [清单与兼容性](../service/resources/skills/plugin-creator/references/protocol.md)、[公共类型](sdk/index.d.ts)：核对字段与调用签名。
- [Lexora Plugins](https://github.com/useLexora/plugins)：插件源码与市场目录。

**插件视图**是插件提供的界面，可以在资源面板里作为标签页打开，也可以显示为独立页面、工作台控件或装饰。资源面板是展示容器，不是插件的所属模块；一个插件可以提供多个视图，也可以只提供命令、AI 工具或后台动作。关闭标签页不等于禁用插件。
也可以在 Lexora 对话中输入 `$plugin-creator` 和需求，由伙伴生成源码与安装包，确认安装后继续迭代。

**Agent 内部扩展**是应用向底层 AI 运行时注入工具、策略和事件处理逻辑的机制，与用户安装的工作台插件不同；插件只能通过宿主开放的接口贡献 AI 能力，不能直接注入进程内扩展。
## 仓库开发工具

## 开发与安装

插件可以添加命令、上下文视图与独立配置页面。[Lexora Plugins](https://github.com/useLexora/plugins) 保存平铺的插件源码与市场目录；开发工具及创作 Skill 位于独立的 Lexora Plugin SDK。`sdk/index.d.ts` 提供公共类型，无需发布或安装单独的 npm SDK。

也可以直接在 Lexora 对话中输入 `$plugin-creator` 和需求，例如 `$plugin-creator 打字时窗口出现礼花`。内置技能生成源码并使用 Lexora 编译器打包，随后显示安装确认；源码保留在任务工作区，便于继续修改。

在 `apps/buddy` 中运行（Node.js 24+，已安装 workspace 依赖）：
使用当前仓库 `package.json` 要求的 Node.js 与 pnpm 版本，安装 workspace 依赖后，在 `apps/buddy` 中运行：

```sh
node extensions/tools.mjs check /path/to/plugin
node extensions/tools.mjs build /path/to/plugin .output/extensions/my-plugin
node extensions/tools.mjs pack .output/extensions/my-plugin .output/extensions/my-plugin.lexora-extension
```

在「插件 → 安装插件包」中安装生成的包。安装按钮右侧箭头可以加载开发目录；「更多操作 → 安装记录」查看进度、编译错误与取消操作。

`extension.json` 中的 `id` 是稳定的插件身份，创建后在修改、升级和发布时持续复用；可选的 `author` 独立保存作者署名，修改署名不改变 ID。命令和视图 ID 以插件 ID 加 `.` 开头。清单声明版本、`engines.lexora`、API 版本、贡献项、依赖与权限。`categories` 和 `tags` 用于市场分类与搜索。

`icon` 可指定包内 SVG、PNG、JPEG 或 WebP 图标（最多 64 KiB），用于导航、插件卡片与安装弹窗。未提供图标时显示默认线框图标。

包预算统一为单文件 64 MiB、压缩安装包 128 MiB、展开合计 256 MiB；最多 4096 个文件，其中非图片文件最多 512 个，归档条目最多 8192 个。对话构建自动按 256 KiB 分块传输，不增加普通插件消息的容量。大型预构建 JS 库请使用 `compiled` 包；源码编译仍有独立的时间与内存限制。

API 3 支持一个插件提供多个完整主题、可选欢迎文字与图片，以及主题编辑器接口；见 [主题开发](../service/resources/skills/plugin-creator/references/themes.md)。主题包可仅包含 JSON 和图片。

API 3 还支持原生设置模块、分组和单项，以及带权限的 Agent 指令、工具、模型请求和当前任务标题更新。先通过能力目录确认宿主支持，再声明最低应用版本；接口与示例见 [Agent 与设置](../service/resources/skills/plugin-creator/references/agent-settings.md)。

`format: "source"` 支持自包含 TS/JS 源码。Lexora 使用固定编译器，不执行 npm 安装、脚本或第三方构建配置。只能导入包内相对路径；含运行时 npm 依赖的插件需要作者预先打包为 `format: "compiled"`。已编译包直接安装，源码包确认权限后编译，失败不会替换已安装版本。`build` 和 `dev` 完整保留 `compiled` 包的目录、脚本与二进制资源，不再次打包其入口；第三方依赖应在交付 compiled 包之前完成构建。

宿主入口导出 `activate(context)`，可选 `deactivate()`。通过 `context.commands.register` 注册清单中声明的命令；订阅资源使用 `context.subscriptions` 清理。`permissions.notifications` 开放系统通知，`permissions.schedules` 开放 Lexora 运行期间的定时命令。定时配置跨重启保存，休眠或退出期间错过的提醒不会补发，卸载会删除定时任务。

视图入口导出 `render(context, container)`，在隔离页面中运行。`location: "context"` 用于上下文标签；`location: "page"` 配合 `contributes.navigation` 可在自动化下方添加入口。通过 `context.commands.execute` 调用自己的宿主命令；使用 `context.environment` 的语言、主题与颜色适配外观，通过 `context.onEnvironmentChange` 响应变化。事件和定时器随 `context.signal` 取消。

源码包在清单中添加 `"styles": { "uno": true }` 后，可直接使用 UnoCSS 和跟随宿主品牌色的语义类，例如 `flex gap-2 bg-accent text-on-accent p-3`。编译器生成并打包 `lexora-uno.css`，视图自动加载；动态类使用完整字符串或 `styles.safelist`。详见[主题与样式](../service/resources/skills/plugin-creator/references/protocol.md#主题与样式)。

`location: "window-overlay"` 提供独立挂载的透明窗口效果，需要 `permissions.windowEffects`。通过 `context.onActivity` 接收不包含输入文字或按键的对话输入活动；视图不会拦截鼠标或焦点，禁用时立即移除。
在「插件 → 安装插件包」安装输出包，或从相邻菜单加载开发目录。`check` 校验清单与包；构建和加载通过后，仍需在真实 Lexora 中验证交互、关闭和重新启用。

API 1 不开放 Node、shell 或任意 Desktop API。文件只读，仅能访问用户选中的文件；HTTPS GET 仅访问已确认的来源，不共享浏览器登录态。`context.storage` 保存私有 JSON，`dataVersion` 改变时入口提供 `migrate(previous, from, to)`，失败保留旧数据。上下文视图可用 `setState` 保存标签状态，独立配置页通过宿主命令保存设置。
先构建 Electron，再用 `node extensions/tools.mjs dev /path/to/plugin` 打开独立开发窗口。它使用临时配置，修改后重新构建并加载；不会替代正式安装包验证。

更新安装后，当前版本继续运行，点击“重启插件”应用更新。禁用停止插件，重新启用保留配置；普通卸载保留插件设置、私有 JSON 与上下文视图位置，但移除代码和定时任务。“卸载并清理”还会删除设置、私有数据和视图状态，不删除任务内容或用户文件。
## 独立 SDK

需要独立开发窗口时，先构建 Electron，再运行 `node extensions/tools.mjs dev /path/to/plugin`。开发窗口使用单独的临时配置；修改后重新加载构建目录并重启插件。SDK 快照可以通过 `node extensions/tools.mjs export-sdk /path/to/plugin-sdk/sdk` 导出。
`node extensions/tools.mjs export-sdk /path/to/plugin-sdk/sdk` 导出开发工具和公共类型快照。类型可复制为插件内的 `lexora.d.ts`，仅通过 `import type` 引用，无需安装 npm SDK 包。已取得独立 SDK 的作者使用 [SDK 工作流](../service/resources/skills/plugin-creator/references/sdk-workflow.md)。

API 2 通过 `contributes.placements` 提供装饰、工作台面板与思考等级控件。API 3 增加可替换的内容区、操作菜单、独立分屏挂载、带插件命名空间的输入命令与可取消交互。创作时用 `lexora_plugin_capabilities` 按需查询当前宿主支持的位置。内容仍在隔离视图运行；清单和调用示例见 [插件协议](../service/resources/skills/plugin-creator/references/protocol.md)。插件自行提供配置交互，内容区及控件可由插件启停并交还宿主默认内容；具体用法见 [内容插槽](../service/resources/skills/plugin-creator/references/slots.md)。旧版插件继续可用。
自包含 TS/JS 使用 `source` 包；Vue、React 和其他运行时依赖由作者预先构建为 `compiled` 包。身份、权限、生命周期与保存行为见专题说明，开发和升级时保持插件 ID 稳定。
Loading