Repository navigation
Plugin Extensions CN
本类目面向插件开发者，说明如何选择扩展入口、实现插件、接入宿主并验证交付。先阅读本页，再选择下面的示例。
| 文章 | 解决的问题 | 示例状态 |
|---|---|---|
| GitHub 一键登录认证插件 | 怎样增加一种登录方式，哪些职责归认证插件，哪些归宿主 | 实现设计示例；当前没有可直接安装的 GitHub 登录插件 |
| 新增模型供应商插件 | 新增大语言模型供应商要写哪些文件、实现哪些协议、如何打包验证 | 基于现有供应商实现与正式打包工具的开发指南 |
本文及两个示例均以宿主 2143c8d4 为代码基线。供应商示例另参考官方插件仓库 87c3468。日期：2026-09-09。这里只新增中文文档，其他语言待中文内容核验后再补。
插件架构可以从三个独立问题理解：提供什么能力、代码在哪里执行、宿主怎样治理它。包名或目录名不能替代这三个问题。
要扩展什么？
│
├─ 登录认证、可信身份、宿主基础设施
│ └─ HostExtension：宿主启动时装配，变更按重启边界生效
│
├─ 调用模型供应商、适配上游协议
│ └─ RuntimeExtension：使用现有 Provider 进程协议
│
└─ 已开放接口的检查、事件处理、插件自有数据
└─ 受管贡献：声明 + 宿主授权 + 执行绑定 + 有效计划
| 名称 | 主要职责 | 当前使用方式 |
|---|---|---|
HostExtension |
可信宿主扩展，例如认证、基础设施、系统级注册 | 宿主启动时注册和装配；实现必须有真实入口，不能只写 manifest |
RuntimeExtension |
在宿主提供的执行契约下完成运行时任务，例如模型供应商 | 原有供应商进程插件继续使用；新组合机制还提供受管贡献执行入口 |
CapabilityPlugin |
在宿主开放的能力契约下提供能力贡献 | 名称与输入分类保留；能做什么取决于具体槽位、契约和授权 |
新的组合架构把治理边界收敛为 可信宿主扩展 和 受管插件。原来三个名称仍会出现在源码、manifest 和目录中；这不意味着要把现有插件全部重写成两种新格式。
RuntimeExtension 和 CapabilityPlugin 的旧包分类也不再适合表达所有职责：同一个新受管包可以声明多个贡献，每个贡献分别绑定处理器和权限。多贡献声明不意味着任意贡献都已有执行支持。
Rust 的进程插件与反复卸载宿主内 .so / .dll 是不同的执行方式。现有供应商可以继续用 Rust 编写独立进程；可信宿主扩展仍按启动和重启管理，不承诺 native 库反复热卸载。
| 需求 | 选择 | 原因 |
|---|---|---|
| 用 GitHub 账号登录 1flowbase | 可信认证扩展与宿主认证装配 | 涉及外部身份验证、本地账号映射和宿主会话 |
| 给工作流新增一个大语言模型供应商 | 现有 model_provider 槽位及 Provider 协议 |
主要工作是配置、模型目录、请求和响应转换 |
| 在创建数据建模定义前执行组织规则 | 已开放的受管 Hook | 宿主已有这个业务操作的阶段契约 |
| 创建完成后通知另一插件处理 | 已开放的受管事件契约 | 需要声明订阅、获得授权并绑定事件处理器 |
供应商协议里的 auth 用于获取上游供应商凭据，例如授权一个供应商实例。它不负责让用户登录 1flowbase，不能拿来代替 GitHub 登录认证。
对新受管贡献，可以按下面的顺序理解：
安装包
→ 解析贡献声明与逐贡献执行绑定
→ 分配到工作区
→ 宿主保存逐贡献授权事实
→ 编译并发布有效执行计划
→ 冻结本次调用所用的计划和版本
→ 执行 Hook / 消费事件 / 访问已授权数据
声明回答“插件希望提供和使用什么”；授权回答“这个安装实例的这个贡献现在被允许做什么”。插件不能通过修改自己的 manifest 获得权限。
同步 Hook 和事件通知分工不同：
| 机制 | 适合做什么 | 结果由谁负责 |
|---|---|---|
| 接口 Hook | 在一次接口执行的已开放阶段做检查或观察 | 主业务结果由宿主接口负责 |
| 持久事件 | 业务提交后触发独立处理、重试和插件协作 | 业务提交与消费结果分别记录 |
| Provider 调用 | 执行一次模型生成、列模型或供应商操作 | Provider 协议与宿主运行时共同约束 |
受管事件采用持久记录、领取与确认、重试和幂等机制。涉及插件自有数据时，当前实现把受支持的数据写入与消费回执放在同一事务中。调用外部服务仍需对方支持幂等，不能由此推导出外部副作用严格只发生一次。
这些机制在技术底座协调注册、授权与交付；业务身份、会话、数据事务和供应商协议仍由各自的模块负责。
当前受管 Hook 的正式业务入口是 model_definitions.create，即创建数据建模定义。HTTP 路径是：
POST /api/console/settings/data-models/model-definitions
这里的数据建模定义是业务数据结构，不是大语言模型供应商注册，也不是一次大语言模型推理。
Hook 可以理解为宿主在这个操作中预留的回调位置：
| 阶段 | 通俗含义 | 插件边界 |
|---|---|---|
Authorization |
是否允许执行这个操作 | 增加权限约束；不能推翻核心权限拒绝 |
Admission |
这次请求是否满足接纳条件 | 在宿主契约内增加准入检查 |
Before |
主业务执行前再检查一次 | 读取受允许的上下文，可否决；不能改写请求 |
After |
主业务返回成功值后的回调 | 观察结果，不能把核心成功改成失败 |
Failure |
适用的拒绝或失败回调 | 部分前置拒绝时主业务尚未执行；不能把拒绝或失败改成成功 |
Completion |
成功或失败最终结束时的观察 | 观察终态，不能替换主结果 |
例如，创建一份“客户资料”数据建模定义时，插件可以检查是否满足组织命名规则；不满足就拒绝，满足才继续。它不能偷偷重命名字段。如果核心已经因为用户无权限而拒绝，插件返回“允许”也不能放行。
六个位置不是每次都顺序执行：前置拒绝会阻止主业务；成功与失败进入不同终态路径。观察 Hook 的错误由相应诊断或交付机制记录，不据此重写核心已经产生的结果。
宿主先读取主业务的 Ok / Err，再选择 After 或 Failure；这两个回调不负责判断主业务成败。观察插件自身也可报告失败，但“创建成功、观察失败”是两个独立结果。
基线实现覆盖创建事件及 A → B/C 的组合链，包括 acme.composition-a.processed@1，载荷和处理器受到约束。它证明了逐贡献授权、可靠交付和恢复机制，不是已经开放任意主题名、任意载荷和任意插件处理器的通用消息平台。
新增业务接口 Hook、插件事件类型或新的执行方式，都需要扩展宿主可识别的契约、处理器装配与验收，不能只在包里添加一个名字。
| 版本信息 | 表达什么 | 当前供应商示例 |
|---|---|---|
manifest_version |
安装清单格式 | 1 |
schema_version |
清单 schema 标识 | 1flowbase.plugin.manifest/v1 |
contract_version |
宿主与插件的执行协议 | 1flowbase.provider/v2 |
version |
插件发行版本 | 例如 0.1.0
|
因此，v1 清单搭配 Provider v2 协议是正常组合。新增普通供应商无需改用 manifest_version: 2。新受管多贡献清单与 Provider 协议是不同层面的版本，不能相互替换。
对受管安装，同一 plugin_id + version 的恢复需要原始归档字节完全一致。修改内容应发布新版本；重新打包得到不同校验和，也不能冒充原归档。缺少可信历史校验和时不能据当前文件认领旧身份。这个规则不能直接外推为所有纯旧版供应商重装路径都已改变。
受管插件停用或权限撤销会保留历史积压。恢复时仍需原精确目标和当前有效授权，重新启用不等于自动恢复，旧事件也不会自动交给最新版。
- 确定职责：宿主身份、运行时供应商，还是已开放的 Hook / 事件贡献。
- 找到实际契约和现有实现；区分声明入口与执行入口。
- 明确配置、凭据、数据和外部调用分别由谁拥有。
- 只声明实际实现的能力，补齐正常、拒绝、失败及停用路径。
- 使用正式安装或宿主装配路径验证；脚手架回显和独立 demo 不能证明端到端可用。
- 发布新版本，保留所需制品与证据，再验证升级行为。
- GitHub 一键登录认证插件
- 新增模型供应商插件
- 请求架构与调用生命周期
- 插件组合架构图（当前实现与覆盖边界）：包含原预期完成度、四张实现图和固定源码依据。
- 当前组合机制说明
- 受管 Hook / 事件 SDK
- Provider 协议