ReMe/docs/zh/plugin_management.md

插件管理

ReMe 插件是通过 reme.plugins entry-point group 发现的普通 Python distribution。安装插件只表示它在当前 Python 环境中可用，并不会让所有 ReMe Application 自动启用该插件。

需要区分两个操作：

reme plugins install ...        将插件包安装到当前 Python 环境
plugins: [auto-fin]             为一个 Application 启用已安装插件

插件包管理仅在本地 CLI 执行，不经过 ReMe HTTP 或 MCP service，也不会自动修改应用配置文件。

典型的插件使用流程分为三个阶段：

1. 安装 ReMe 和插件 distribution。
2. 按照 ReMe 环境变量说明配置插件运行所需的环境变量。
3. 启动 Application 时显式启用插件，例如 reme start plugins='["auto-fin"]'。

查看已安装插件

reme plugins list

输出包含插件 entry-point 名称、Python distribution、版本和插件契约：

PLUGIN    DISTRIBUTION   VERSION  FORMAT
--------  -------------  -------  --------
auto-fin  reme-auto-fin  0.1.0    manifest

manifest 表示插件使用当前的 package-level plugin.yaml 契约；legacy 表示插件使用仍然兼容的 Python descriptor 契约。

manifest 将 backend 注册与应用配置分开：

backends:
  example_step: example_plugin.steps:ExampleStep

application_defaults:
  jobs:
    example:
      backend: base
      steps:
        - backend: example_step

application_defaults 是一段不完整的 ApplicationConfig。它与 manifest 的 backends 命名空间分开，因为 backend 导入声明属于插件发现协议，并不是应用配置。

本地工具需要结构化结果时可以使用 JSON：

reme plugins list --json

对照某个应用配置查看启用状态：

reme plugins list --config daily_cookbook

可选的 ENABLED 列只反映该配置解析出的 plugins 列表。其他运行中进程使用的 CLI override 不是全局启用状态。

安装插件包

安装已发布的 distribution：

reme plugins install reme-auto-fin

安装指定版本或升级：

reme plugins install 'reme-auto-fin==0.1.0'
reme plugins install reme-auto-fin --upgrade

安装本地插件项目：

reme plugins install ./plugins/auto-fin

开发插件时使用 editable 模式：

reme plugins install ./plugins/auto-fin --editable

ReMe 会通过运行 reme 命令的同一个 Python 解释器调用 pip。包解析、下载、依赖变更和构建执行仍由 pip 负责。请只安装 可信的包和本地项目。

安装后确认 ReMe 实际发现的插件名：

reme plugins list
reme plugins validate auto-fin

查看插件详情

reme plugins show auto-fin

对于 manifest 插件，结果包含注册的 backend 名称和默认 Job 名称。也可以输出 JSON：

reme plugins show auto-fin --json

show 只检查包契约，不构造 ReMe Application。

校验插件

校验已安装插件：

reme plugins validate auto-fin

安装前校验本地插件项目：

reme plugins validate ./plugins/auto-fin

校验范围包括 entry point、plugin.yaml、backend 导入和组件类型、registry 冲突、application_defaults 合并以及最终的 ApplicationConfig。校验过程会导入插件 backend 模块，因此只能对可信代码执行。

在服务中启用插件

只安装插件不会将插件代码加载到 Application。需要在配置中显式启用：

plugins:
  - auto-fin

也可以只为本次服务启动追加插件：

reme start plugins='["auto-fin"]'

未传入 config 时，ReMe 加载 default.yaml。插件的 application_defaults 合并在该配置之下，因此显式配置和 CLI override 优先。这个 mapping 是 ApplicationConfig 配置片段，并不是另一套配置 schema。插件 backend 只注册到该 Application 的局部 registry。

默认 HTTP service 启动后，可以通过 ReMe CLI client 或 HTTP 访问插件 Job：

reme auto_fin topics="黄金,AI,存储芯片"

curl -s http://127.0.0.1:2333/auto_fin \
  -H 'Content-Type: application/json' \
  -d '{"topics":"黄金,AI,存储芯片"}'

当应用使用 MCP service 时，允许对外服务的插件 Job 会显示为 MCP tool。

如果需要将插件叠加到其他应用配置，则显式选择该配置：

reme start config=daily_cookbook plugins='["auto-fin"]'

卸载插件

这里使用插件 entry-point 名称，它不一定等于 distribution 名称：

reme plugins uninstall auto-fin

需要跳过 pip 确认时：

reme plugins uninstall auto-fin --yes

ReMe 会将 auto-fin 解析为提供它的 distribution，例如 reme-auto-fin。如果一个 distribution 提供多个插件 entry point，命令会列出同时被移除的其他插件。

卸载不会重写用户配置。请自行从相关 plugins 列表中删除插件，否则下一次启动 Application 时会因为配置的插件未安装而明确 失败。安装、升级或卸载包后，需要重启已经运行的 ReMe 进程。

常见问题

插件已经安装，但 ReMe 找不到

检查 reme 命令与安装插件使用的 pip 是否属于同一个 Python 解释器：

reme plugins list
python -c 'import sys; print(sys.executable)'

使用 reme plugins install 可以避免最常见的解释器不一致问题，因为它通过 ReMe 自己的解释器运行 python -m pip。

插件已经安装，但没有加载

将插件 entry-point 名称加入 Application 的 plugins 列表。ReMe 刻意不提供全局 enable/disable 状态。

启动时报插件未安装

当前配置仍然启用了缺失插件。请重新安装插件，或者从 plugins 中删除对应名称。

运行中的服务看不到插件变化

插件发现和 backend 注册发生在 Application 构造阶段。修改已安装包后需要重启服务。