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

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

好的 Manifest 让插件知道自己在什么时候被调用、能访问什么资源、需要声明什么依赖、暴露什么 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 机制，插件可以注册自己的路由。

执行顺序不可控

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

配置格式不透明

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

资源边界不清晰

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

管理接口不统一

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

第一，插件类型分类

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 摘要），还是依赖某个数据库表（需要预先创建审计表）。

第六，权限模型

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

认证方式声明

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

凭证引用机制

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

连接测试接口

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

操作能力列表

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

速率限制和重试策略

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

契约是自动化的前提

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

契约是版本治理的基础

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

契约是可组合性的保障

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

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

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

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

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

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