Wiki AI

插件系统（Plugin）

7分钟阅读

Botmux Plugin 用一个可发布的 npm 包同时交付五种扩展能力：Skill、MCP server、CLI 命令、Dashboard 页面和 Host Service。本页覆盖加载机制、manifest、各扩展点开发要点、生命周期命令与插件市场登记。

当前边界（重要）

  • 插件市场（Plugin Market）是独立的发现索引：发布到 npm 不会自动登记市场。
  • 当前稳定版安装时不读取市场索引；plugin install <short-id> 只按命名约定展开为 @botmux-ai/plugin-<short-id>。
  • 完整 npm 包名始终是最可靠的安装入口（第三方插件尤其如此）。

加载机制

插件根 package.json 是开发、校验与 npm 发布外壳；Botmux 安装时读取 manifest，只把包内 dist/ 保存为运行单元。扩展能力按固定目录扫描：

能力源目录安装入口
Skillskills/<name>/SKILL.mddist/skills/<name>/SKILL.md
MCPsrc/mcp/dist/mcp/index.json
CLI 命令src/cli/dist/cli/{index.js,commands.json}
Dashboardsrc/dashboard/dist/dashboard/index.js
Host Servicesrc/service/dist/service/index.js

没有通用的 worker/daemon hook 扩展点：长期进程放 Host Service，Agent 工具放 MCP 或 Skill，运维入口放 CLI。

安装与启用是两个动作：

  1. plugin install — 下载、校验 manifest、扫描扩展点、保存 dist/；
  2. plugin enable — 绑定到机器默认或指定 Bot，为后续会话生成 Skill/MCP 快照。

安装阶段不会调用插件的任何入口，但从 npm 安装时底层 npm install 可能执行 lifecycle scripts——安装第三方插件等于信任其发布者。

manifest 要点（package.json#botmux）

安装器校验：version 合法 SemVer、keywords 含 botmux-plugin、botmux.id 匹配 ^[a-z][a-z0-9._-]{0,63}$、存在 dist/、service.mode 仅 manual|auto、各扩展点固定入口存在且合法。

  • 建议 files 只含 dist/，发布前 npm pack --dry-run 检查。
  • botmux.dependencies.plugins 只声明 Plugin ID（不支持版本范围）：启用时依赖插件须已安装并在同一作用域启用；卸载/禁用仍被依赖的插件会被拒绝。
  • 官方 scope @botmux-ai 无第三方发布权限，应改成自己控制的包名，Plugin ID 可保留。

扩展点开发要点

CLI 命令

src/cli/index.js 默认导出 handler map；命令名须匹配 ^[a-z][a-z0-9._:-]{0,63}$。Botmux 不自动加命名空间，同名命令直接冲突，建议统一 <plugin-id>: 前缀。handler 可读 pluginId / pluginDir / version / manifest / args 及 api.logger、api.resolve()、api.config.get/set/replace、api.settingsPath。插件私有配置在 ~/.botmux/plugins/<id>/。

Skill

入口 skills/<name>/SKILL.md，构建后必须位于 dist/skills/<name>/SKILL.md。已运行的 Agent 不会热加载新 Skill——启用/更新后需新建会话，让 Botmux 重新生成 Plugin/Skill 快照（见 skill-cli）。

MCP（与 MCP Gateway 聚合）

每个插件最多贡献一个 MCP server，dist/mcp/index.json 支持两种 transport：

{ "transport": "stdio", "command": ["node", "./mcp/server.js"], "env": {} }
{ "transport": "streamable-http", "url": "https://example.com/mcp", "headers": {} }

约束：MCP 名称自动用 Plugin ID（不写 name）；./... 路径相对安装后的 dist/；不支持 ${VAR} 模板；本地运行依赖必须打包进 dist/；密钥不得写进包，应从受控环境或插件私有配置读取。

Botmux 通过统一 MCP Gateway 聚合当前会话已启用插件的 MCP server；插件集合与凭证快照以 CLI 进程为边界，修改绑定或配置后应新建会话。

Dashboard

src/dashboard/index.js 默认导出组件，固定路由 #/plugins/<plugin-id>（见 dashboard）。Plugin API 提供 getServiceStatus / startService / stopService / restartService。Dashboard 代码在安装 Botmux 的系统用户权限内运行，勿把敏感配置渲染进页面。

Host Service

需同时有 package.json#botmux.service.mode 与 dist/service/index.js。导出对象含 mode（须与 manifest 一致）、port、pm2（script/env/autorestart）、urls({host, port})（host 已含 IPv6 方括号）。

  • manual：仅 plugin service start 显式启动；auto：botmux start/restart 确保在线。
  • 普通 botmux stop 默认保留插件 Service；botmux stop --with-plugin 才一并停止 auto Service。

生命周期命令

# 安装（第三方用完整包名，建议固定精确版本）
botmux plugin install @your-org/plugin-my-plugin@1.2.3
botmux plugin install my-plugin            # 官方短 ID → @botmux-ai/plugin-my-plugin
botmux plugin install . --link             # 本地目录开发（链接到项目 dist/）
 
# 启用/禁用（无 --bot 即机器默认作用域，无需 --global）
botmux plugin enable my-plugin [--bot <name|index|all>]
botmux plugin disable my-plugin [--bot <name|index|all>]
 
# Service
botmux plugin service status | start <id> | stop <id> | restart <id>
 
# 卸载（清理绑定与 ~/.botmux/plugins/<id>/，含插件配置）
botmux plugin service stop my-plugin && botmux plugin uninstall my-plugin
  • 已在机器默认作用域启用的插件，须先关闭机器默认绑定才能按 Bot 单独配置。
  • 更新 = 重新 install；有 Service 必须先停。Botmux 不会在安装/更新/卸载时隐式停止运行中的 Service。
  • 验收重点不是”仓库里能跑”，而是解压后的 dist/ 脱离源码与 node_modules 仍可运行（本地 --link 与真实 npm pack tarball 都要验收）。

市场登记

市场是独立静态仓库 botmux-ai/plugin-market：只存发现元数据、不托管代码、不是安全信任边界。流程：fork 市场仓库 → 新增 plugins/<id>.json（必填 id/package/displayName/description/repo/categories/compatibility.botmux，docs 可选；repo、docs 必须 HTTPS URL；分类名匹配 ^[a-z][a-z0-9-]{0,31}$ 不重复；官方 scope 包名须严格等于 @botmux-ai/plugin-<id>）→ npm run build 重新生成 index.json → PR 同时提交条目与 index.json。

CLI 当前边界（截至 botmux@3.8.0）

  • search / info / register / publish 尚未实现。
  • 可用 verbs：list / init / install / uninstall / enable / disable / emit / service；emit 是 legacy Codex Notifier 兼容入口，不是通用事件/hook 扩展点。
  • compatibility.botmux 当前仅是市场元数据，安装器不执行 SemVer 判断。
  • 以 botmux plugin --help 为准。

安全清单（摘要）

安装插件等于信任其代码：npm lifecycle scripts 可能执行；CLI/MCP/Dashboard/Service 都以安装 Botmux 的系统用户权限运行。生产环境只装可信发布者的包、固定精确版本、核对 registry integrity；不把 token/密钥/用户数据打进 dist/；发布前逐项检查 npm pack --dry-run；市场登记只是发现机制，不能代替代码审计。

相关页面

  • skill-cli — 插件 Skill 如何注入 CLI 会话
  • dashboard — Dashboard 管控面（插件页面挂载处）
  • cli-commands — botmux CLI 命令参考
  • cli — plugin 子命令源码实现

关系图谱

反向链接