插件中心对接与接口清单

April 8, 2026 · View on GitHub

本文档描述 CodexManager 当前插件中心的对接方式，并列出当前系统里与插件相关的全部对外接口。当前实现是“市场层 + Rhai 运行时”结构：市场负责分发清单，Rhai 负责执行脚本。

1. 接入前提

默认市场模式为 builtin，使用内置精选插件。
若要接入私有仓库或自定义仓库，需要把市场模式切到 private 或 custom。
远程市场源支持返回：
- 顶层数组
- { "items": [...] }
插件脚本目前以 Rhai 执行为主，运行时按权限开放少量内建函数。

2. 市场模式

值	含义	行为
`builtin`	内置精选	忽略外部 URL，只返回内置市场
`private`	企业私有	使用保存的远程仓库地址
`custom`	自定义源	使用保存的远程仓库地址

3. 前端入口

项	值
路由	`/plugins/`
页面名称	插件中心
侧边栏入口	插件中心

4. Tauri 命令接口

命令名	参数	说明
`service_plugin_catalog_list`	`addr?`, `source_url?`	拉取插件市场清单
`service_plugin_catalog_refresh`	`addr?`	刷新插件市场
`service_plugin_install`	`addr?`, `entry`	安装插件
`service_plugin_update`	`addr?`, `entry`	更新插件
`service_plugin_uninstall`	`addr?`, `plugin_id`	卸载插件
`service_plugin_list`	`addr?`	获取已安装插件
`service_plugin_enable`	`addr?`, `plugin_id`	启用插件
`service_plugin_disable`	`addr?`, `plugin_id`	停用插件
`service_plugin_tasks_update`	`addr?`, `task_id`, `interval_seconds`	更新任务间隔
`service_plugin_tasks_list`	`addr?`, `plugin_id?`	获取任务列表
`service_plugin_tasks_run`	`addr?`, `task_id`, `input?`	手动运行任务
`service_plugin_logs_list`	`addr?`, `plugin_id?`, `task_id?`, `limit?`	获取运行日志

5. Service JSON-RPC 接口

RPC 方法	说明
`plugin/catalog/list`	获取市场清单
`plugin/catalog/refresh`	刷新市场清单
`plugin/install`	安装插件
`plugin/update`	更新插件
`plugin/uninstall`	卸载插件
`plugin/list`	已安装插件列表
`plugin/enable`	启用插件
`plugin/disable`	停用插件
`plugin/tasks/update`	更新任务
`plugin/tasks/list`	任务列表
`plugin/tasks/run`	运行任务
`plugin/logs/list`	运行日志

6. 市场清单 JSON 结构

6.1 插件字段

字段	类型	必填	说明
`id`	string	是	插件唯一 ID
`name`	string	否	插件名称，缺省回退到 `id`
`version`	string	否	版本号，缺省 `0.0.0`
`description`	string	否	描述
`author`	string	否	作者
`homepageUrl`	string	否	首页地址
`scriptUrl`	string	否	脚本远程地址
`scriptBody`	string	否	脚本文本
`permissions`	string[]	否	权限列表
`tasks`	task[]	否	任务定义
`manifestVersion`	string	否	清单版本，缺省 `1`
`category`	string	否	分类
`runtimeKind`	string	否	运行时，当前默认 `rhai`
`tags`	string[]	否	标签
`sourceUrl`	string	否	来源地址

6.2 任务字段

字段	类型	必填	说明
`id`	string	是	任务 ID
`name`	string	否	任务名称
`description`	string	否	任务描述
`entrypoint`	string	否	脚本入口函数名，缺省 `run`
`scheduleKind`	string	否	`manual` / `interval`
`intervalSeconds`	number	否	间隔秒数
`enabled`	bool	否	默认启用

7. 已安装插件返回结构

字段	说明
`pluginId`	插件 ID
`sourceUrl`	来源 URL
`name`	名称
`version`	版本
`description`	描述
`author`	作者
`homepageUrl`	首页
`scriptUrl`	脚本 URL
`permissions`	权限列表
`status`	`enabled` / `disabled` / `broken`
`installedAt`	安装时间
`updatedAt`	更新时间
`lastRunAt`	最近执行时间
`lastError`	最近错误
`taskCount`	任务总数
`enabledTaskCount`	已启用任务数
`manifestVersion`	清单版本
`category`	分类
`runtimeKind`	运行时
`tags`	标签

8. 任务与日志返回结构

8.1 任务

字段	说明
`id`	任务 ID
`pluginId`	插件 ID
`pluginName`	插件名称
`name`	任务名称
`description`	描述
`entrypoint`	入口函数名
`scheduleKind`	调度类型
`intervalSeconds`	间隔秒数
`enabled`	是否启用
`nextRunAt`	下次执行时间
`lastRunAt`	上次执行时间
`lastStatus`	上次状态
`lastError`	上次错误

8.2 日志

字段	说明
`id`	日志 ID
`pluginId`	插件 ID
`pluginName`	插件名称
`taskId`	任务 ID
`taskName`	任务名称
`runType`	`manual` / `scheduled`
`status`	`ok` / `error`
`startedAt`	开始时间
`finishedAt`	结束时间
`durationMs`	耗时
`output`	输出 JSON
`error`	错误信息

9. 插件运行上下文

运行时调用入口函数时会传入一个 context 对象，结构如下：

{
  "plugin": {
    "id": "cleanup-banned-accounts",
    "name": "清理封禁账号",
    "version": "1.0.0",
    "sourceUrl": "builtin://codexmanager",
    "permissions": ["accounts:cleanup"]
  },
  "task": {
    "id": "cleanup-banned-accounts::run",
    "name": "定时自动清理",
    "description": "每 60 秒自动清理一次所有封禁账号",
    "entrypoint": "run",
    "scheduleKind": "interval",
    "intervalSeconds": 60,
    "enabled": true
  },
  "input": null,
  "runStartedAt": 1710000000
}

10. Rhai 内建函数

当前仅在满足对应权限时开放：

权限	函数	说明
`settings:read`	`get_setting(key)`	读取单个设置
`settings:read`	`list_settings()`	获取全部设置
`network`	`http_get(url)`	发送 GET 请求
`network`	`http_post(url, body)`	发送 POST 请求
`accounts:cleanup`	`cleanup_banned_accounts()`	清理封禁账号
`accounts:cleanup`	`cleanup_unavailable_free_accounts()`	清理不可用免费账号

公共函数：

log(message)：写入运行日志

11. 对接建议

如果你要做官方精选市场，优先给插件补 category、tags、manifestVersion。
如果你要做企业私有市场，推荐直接返回顶层 items 数组，方便后端容错。
如果你要做自定义仓库，保持 scriptBody 或 scriptUrl 二选一即可。
当前运行时是 Rhai，适合轻量自动化，不建议把重型插件逻辑直接堆到脚本里。
系统当前内置了两个账号治理脚本：封禁账号定时清理、不可用免费账号定时清理。
Capabilities such as user lists, usage lists, and request logs are already listed in System Internal Interface Inventory under their common names. They are host-side internal interfaces, not default built-in Rhai functions.