插件 Manifest 应该怎么设计？开源 ITSM 的扩展契约

云与数字化 | 开源 ITSM 的插件市场与扩展契约设计

开源 ITSM 插件系统能不能做好，不取决于插件市场 UI 好不好看，而取决于 Manifest 契约设计得够不够清晰。

好的 Manifest 让插件知道自己在什么时候被调用、能访问什么资源、需要声明什么依赖、暴露什么 API。差的 Manifest 让插件和核心系统耦合在一起，变成“改不动、拆不掉、升不起”。

上一篇文章讲可安装能力包，我提到连接器是零件、插件是扩展边界、能力包是面向场景的交付单元。但这三个层次都有一个前提条件：它们必须通过一个清晰的 Manifest 契约来声明自己是谁、依赖什么、能做什么。

这篇文章，我想从 Apache APISIX 的插件机制出发，聊聊一个好的插件 Manifest 应该包含哪些要素，以及开源 ITSM 的插件系统可以从中借鉴什么。

01、APISIX 的五层插件契约

Apache APISIX 是一个云原生 API 网关，它的插件机制在开源世界里算是设计得比较成熟的。我仔细看了它的插件开发文档，发现它的 Manifest 设计其实有五层清晰的契约，每一层解决一个问题。

第一层：身份层 — name + version + priority

每个插件必须声明自己的唯一标识（name）、版本（version）和优先级（priority）。优先级决定了同一个执行阶段内多个插件的调用顺序。比如 APISIX 里 ip-restriction 插件优先级是 3000，example-plugin 是 0，所以 ip-restriction 会先执行。

第二层：配置层 — schema + check_schema

插件的配置必须通过 JSON Schema 声明，并且要实现 check_schema 方法来做运行时校验。这解决了“配置能不能进来、格式对不对”的问题。没有这一层，插件配置就是无序的，运行时错误不可预测。

第三层：阶段层 — phase (rewrite/access/header_filter/logger)

插件必须声明自己在哪个阶段执行。APISIX 把请求处理分为 rewrite、access、header_filter、body_filter、log 等阶段。一个插件可以声明在多个阶段执行，但必须明确。这是解决“什么时候被调用”的关键。

第四层：资源层 — lua_shared_dict + dependencies

如果插件需要共享内存（比如限流计数器），必须在插件里声明 lua_shared_dict。如果依赖外部库，必须在插件加载时检查依赖是否存在。这是解决“插件能访问什么资源”的边界。

第五层：API 层 — admin_api + control_api

插件可以声明自己的管理接口，比如查询状态、动态修改配置、暴露控制平面。APISIX 提供了完整的 Admin API 和 Control API 机制，插件可以注册自己的路由。

这五层契约加起来，形成了一个完整的插件生命周期定义：从“我是谁”到“我在哪执行”到“我能用什么资源”到“我怎么被管理”。

02、这五层契约解决了什么问题？

表面看，这是 APISIX 的技术实现细节。但如果你把视角抬高一点，会发现这五层契约实际上解决的是所有插件系统都会遇到的四个核心问题。

执行顺序不可控

没有优先级声明，插件执行顺序就是随机的。限流插件在认证之前执行还是之后执行，行为完全不一样。APISIX 用 priority 解决了这个问题。

在开源 ITSM 里，这个问题同样存在。一个通知插件在工单创建时触发，另一个通知插件在工单关闭时触发，但如果它们都叫“通知插件”，系统怎么知道哪个先执行？所以 ITSM 插件也必须有明确的阶段定义和优先级。

配置格式不透明

没有 Schema，插件配置就是黑盒。运维人员不知道必须填什么字段、字段类型对不对、有没有默认值。APISIX 用 JSON Schema 解决了这个问题。

在开源 ITSM 里，一个飞书连接器插件需要配置 Webhook URL、Secret Key、Agent ID。如果没有 Schema，运维只能看文档猜，或者等到运行时报错才知道配置错了。这对企业级产品是不可接受的。

资源边界不清晰

没有声明共享内存和依赖，插件可能和核心系统抢资源，或者因为缺少依赖而崩溃。APISIX 用 lua_shared_dict 声明和 dependencies 检查解决了这个问题。

在开源 ITSM 里，这个问题更明显。一个 AI 摘要插件可能需要调用大模型 API，一个流程引擎插件需要数据库连接，一个通知插件需要消息队列。如果不声明资源依赖，插件可能把系统资源耗尽，或者在缺少配置时无声无息地失败。

管理接口不统一

没有统一的 API 层，每个插件自己定义管理方式，有的用 CLI，有的用数据库，有的用配置文件。APISIX 用 Admin API 统一了插件的管理入口。

在开源 ITSM 里，一个连接器市场如果每个连接器都自己定义一套管理 UI，运维人员就要学会十几种不同的操作方式。统一的管理 API 是插件生态能不能做起来的基础设施。

03、开源 ITSM 能从中学到什么？

APISIX 是 API 网关，它的插件机制针对的是请求处理场景。开源 ITSM 是服务管理平台，插件针对的是流程、连接器、AI Skill 等场景。场景不同，契约细节自然不同，但思路完全可以迁移。

我总结了开源 ITSM 插件 Manifest 应该包含的六个核心要素。

第一，插件类型分类

ITSM 里的插件不只有一种。有流程插件（决定工单怎么流转）、连接器插件（决定和外部系统怎么交互）、AI Skill 插件（决定 AI 怎么参与处理）、通知插件（决定什么时候发消息）、审计插件（决定记录什么动作）。Manifest 必须声明插件属于哪种类型。

第二，数据契约（Schema）

每个插件必须声明自己需要什么配置、配置的类型和约束是什么。对于连接器，这可能是 API 地址、认证方式、轮询间隔。对于 AI Skill，这可能是模型名称、温度参数、Prompt 模板。

第三，生命周期阶段

插件必须声明自己在什么事件触发。常见的阶段包括：工单创建前（pre-create）、工单创建后（post-create）、工单审批时（on-approve）、工单关闭时（on-close）、SLA 告警时（on-sla-warning）、定时任务触发时（cron）。

第四，优先级和互斥

同一个阶段可能有多个插件都想执行。比如工单创建后，可能同时有飞书通知插件、企业微信通知插件、审计日志插件、AI 摘要插件。优先级决定了执行顺序。互斥规则则决定了哪些插件不能同时启用（比如两个 AI 摘要插件同时运行会重复处理）。

第五，资源依赖声明

插件必须声明自己依赖什么：是依赖某个连接器（必须先安装飞书连接器才能用飞书通知插件），还是依赖某个 AI 模型（必须配置大模型 API 才能用 AI 摘要），还是依赖某个数据库表（需要预先创建审计表）。

第六，权限模型

插件必须声明自己能访问什么数据、谁能管理这个插件。一个审计插件可能需要读取所有工单数据，但一个通知插件只需要读取发起人信息。一个插件可能被限制为只有管理员才能配置。

04、连接器的生命周期管理

在开源 ITSM 里，连接器是一个特殊的插件类型。它不是“扩展功能”，而是“基础设施”。没有连接器，ITSM 就只是一个孤立的工单系统，无法和外部世界交互。

但连接器的管理比其他插件更复杂，因为它涉及认证、凭证、网络和安全。APISIX 在这一块的处理方式是：连接器（在这个语境里更接近“上游”或“服务发现”）通过独立的配置机制管理，插件不直接持有凭证，而是通过引用访问。

我认为开源 ITSM 的连接器也应该采用类似的模式。连接器的 Manifest 应该包含：

认证方式声明

连接器支持哪些认证方式：API Key、Bearer Token、OAuth2、Basic Auth、签名算法。

凭证引用机制

连接器不存储凭证，只引用凭证 ID。凭证本身由 ITSM 核心的凭证管理模块统一管理。

连接测试接口

连接器应该提供一个 test_connection 方法，用于在配置完凭证后立即验证连接是否可用。

操作能力列表

连接器能做什么：发送消息、查询用户、创建工单、同步数据。Manifest 应该声明每个操作的能力和返回格式。

速率限制和重试策略

连接外部 API 通常有频率限制。Manifest 应该声明默认的重试次数、退避策略和超时时间。

有了这些声明，连接器市场就可以做很多事情：自动检查凭证是否配置完整、自动测试连接是否可用、根据操作能力自动生成可用的插件列表。

05、为什么契约设计比文档更重要？

很多开源项目在插件市场上投入大量精力做 UI、做分类、做搜索、做评分，但忽略了 Manifest 契约的设计。结果是插件市场看起来很丰富，但实际用起来问题不断：插件和核心版本不兼容、插件之间互相冲突、升级一个插件导致其他插件失效。

这些问题不是 UI 能解决的。UI 只能让“发现插件”变得更容易，但“正确使用插件”必须靠契约。

契约是自动化的前提

没有清晰的 Manifest，插件市场就无法自动检查插件兼容性、无法自动生成配置表单、无法自动验证依赖关系。所有这些“智能”功能，都建立在契约之上。

比如，当一个 AI Skill 插件声明自己依赖“大模型 API”，系统可以自动检查企业是否已经配置了模型，如果没配置就提示先去配置。当一个通知插件声明自己依赖“飞书连接器”，系统可以自动检查飞书连接器是否已安装并启用。

契约是版本治理的基础

当核心系统升级时，契约声明可以让系统知道哪些插件需要升级、哪些插件可能不兼容、哪些插件可以保留。没有契约，升级就是一个黑盒操作。

APISIX 的插件机制之所以稳定，很大程度上是因为它把契约定义得非常清晰。插件开发者只要按照契约开发，核心系统就能正确加载、调度、管理插件。即使核心版本升级，只要契约不变，插件就能继续工作。

契约是可组合性的保障

当插件市场发展到一定阶段，插件之间需要组合。一个能力包可能包含多个插件，它们之间有依赖关系。清晰的契约让系统能够自动解析这些依赖，生成正确的安装顺序和配置。

比如，员工入职能力包可能包含：HR 系统连接器插件、账号开通流程插件、飞书通知插件、AI 摘要插件。当用户安装这个能力包时，系统应该能自动检查这些插件的依赖关系，确保 HR 系统连接器在账号开通流程插件之前安装，飞书通知插件在 AI 摘要插件之后初始化。

06、当前项目的建设方向

我正在做的开源 AI Native ITSM 项目，正在围绕飞书、企业微信、钉钉、Webhook 等国内企业常见入口建设连接器能力。但坦率地说，当前的 Manifest 设计仍处在早期阶段，更多是在验证“能不能跑起来”，还没有到“契约足够清晰”的程度。

接下来如果要把插件市场做成真正可扩展的能力层，Manifest 至少要回答几个工程问题：

配置如何声明：连接器需要哪些字段，类型和约束是什么，缺少配置时系统如何阻止错误安装。

触发点如何定义：连接器和 AI Skill 在工单生命周期的哪个节点被调用，是否允许多个阶段复用。

冲突如何处理：多个插件在同一个阶段执行时，优先级、互斥关系和失败兜底应该如何表达。

依赖如何检查：安装插件前，系统能不能自动判断连接器、模型、权限和数据库资源是否满足。

管理如何统一：配置、启用、禁用、测试、升级和回滚是否都能通过统一接口完成。

结语

开源 ITSM 的插件市场，最终能不能成气候，不取决于 UI 做得有多炫，而取决于 Manifest 契约设计得有多清晰。

APISIX 给了我们一个很好的参考：身份层、配置层、阶段层、资源层、管理层，这五层契约构成了一个可靠插件系统的基础。开源 ITSM 需要在此基础上增加插件类型分类和权限模型，形成适合服务管理场景的契约体系。

当契约清晰以后，插件市场才能真正实现自动化：自动检查依赖、自动验证配置、自动管理版本、自动处理升级和回滚。在此之上，能力包才有可能成为面向业务场景的交付单元。

项目地址：

https://github.com/heidsoft/itsm