后端插件源清单

fh2-plugin.json 放在后端插件目录根，是后端插件的源清单：写清插件是谁、有哪些流程、脚本、事件订阅。构建时工具链把它改写成运行时清单 dist/plugin.json（宿主装载那份，不要手改）。源清单被严格解析——任何一个不认识的字段都会导致整包拒绝装载。

语义详解（什么时候用什么、为什么这么设计）见源清单指南；本页是字段速查。

顶层字段

字段	必填	说明
`pluginId`	✅	插件身份；创建/交付要求 `^(official\|exp)_[a-z0-9]+([_-][a-z0-9]+)*$`，跨包唯一。源 Schema 的结构限制为 `^[A-Za-z0-9_.-]{1,64}$` 且禁冒号；这不是可交付 ID 的完整规则
`name`	✅	展示名（日志和插件管理页用）
`version`	✅	整包统一版本，是发布/回滚的单位
`description`		说明文字
`puid`		插件管理服务下发的版本唯一 ID；内建包省略，本地开发不用填
`contractsRange`		声明兼容的宿主契约版本范围，见下文
`flows`		流程 JSON 相对路径列表，如 `["workflows/main.json"]`；白名单制：只装载列出的文件，不扫目录
`connections`		外部系统连接声明（只有形状，值在部署配置）；可为空数组
`scripts`		流程用脚本声明；可为空数组。脚本是 `.ts` 源文件
`events`		消息订阅声明，见下文
`eventStatuses`		本包用到的事件状态值词汇，供流程状态步骤和事件筛选校验
`allowlist`		包级权限，HTTP 接口与事件处理脚本共用
`evaluators`		只读判定脚本（无任何能力注入），供流程条件使用
`entities`		不要写。存储契约由 `schema.sql` 单点定义，构建时自动投影进运行时清单

必填只有 pluginId、name、version。数组字段没有对应内容时可以不写，写空数组也不是装载要求。

⚠️ 旧文档 / 旧实现里的这些字段会被拒装：handlers[]、triggers[]、whitheList（拼写也是错的）、side、capabilityId、manifest。HTTP 接口按 handlers/ 目录约定登记（见 HTTP 接口），触发器写在每个流程 JSON 自己的 trigger 段里（见流程触发器参考）。

宿主契约版本范围（`contractsRange`）

宿主有一个契约版本。插件声明自己兼容的范围，装载时比对，不在范围内则拒绝装载：

{ "contractsRange": ">=1.1.0 <2.0.0" }

只支持 >=、>、<=、<、=、==，多个比较式用空格连接（AND）。

不支持 ^、~、||、通配符。

留空表示不检查；能装，但失去一层保护，不建议省略。

流程脚本（`scripts[]`）

{
  "scripts": [
    {
      "name": "example-script",
      "path": "adapters/example-script.ts",
      "entry": "handle",
      "allowlist": ["track:read", "video:process"],
      "io": {
        "inputs": [{"name": "event_id", "type": "string", "required": true}],
        "outputs": [{"name": "post_status", "type": "string"}]
      }
    }
  ]
}

字段	说明
`name`	脚本名；流程步骤用 `{"script": {"const": "<名>"}}` 引用。留空取文件名（去后缀）
`path`	插件内相对路径（约定放 `adapters/`），`.ts` 源文件
`entry`	入口导出函数名，缺省 `handle`
`allowlist`	只给这个脚本的权限；留空回落包级 `allowlist`，写了就只用自己声明的（不是合并）
`io`	输入输出契约；`inputs[].required` 校验必填，`outputs` 声明了就必须产出

注意：运行环境没有模块系统加载运行时构建产物的约束不适用于你的源码——你写 TypeScript，可以相对导入 shared/，构建会打平。详见源码与模块策略。

消息订阅（`events[]`）

{
  "events": [
    {
      "type": "media.video_created",
      "match": {"sub_file_type": "0"},
      "consumer": [{"handler": "events/on-video.ts", "entry": "onVideoCreated"}]
    }
  ]
}

字段	说明
`type`	消息类型，平台指定（如 `media.photo_created`、`media.video_created`）；包内唯一，只能选订不能自造
`match`	消息体顶层字段的等值筛选（AND）；不写 = 全收
`consumer`	后端运行时对命中的消费方并发执行、各自独立重试；全部结束后按最坏结果聚合消息处置
`consumer.handler`	脚本路径（约定放 `events/`），`.ts` 源文件
`consumer.entry`	入口导出函数名，缺省 `handle`

consumer 数组不表达业务先后依赖；需要先后执行的逻辑应放在同一个消费函数内调用，或使用显式流程编排。入口必须返回对象，通常为 {}；失败信封的处置见事件处理函数。消息队列的并发、重试和消息处置语义需在已部署的测试环境验证。

外部连接（`connections[]`）

{
  "connections": [
    {
      "id": "traffic.connector.cascade",
      "requires": [
        {"name": "baseUrl", "type": "string", "required": true},
        {"name": "password", "type": "string", "required": true, "secret": true}
      ]
    }
  ]
}

只声明形状；真实值写在部署配置里，装载期校验缺键/多键/类型，不过就起不来。secret: true 只是不打印进日志，不是加密。

不要手写存储实体（`entities`）

存储契约由包内 schema.sql 单点定义（数据存储），构建时自动投影成运行时清单的 entities。在源清单手写一份会和派生结果冲突。运行期修改 entities 的包会被拒绝热更。

装载期检查清单

发布前自查，装载时全部会检查：

字段名拼写正确（严格模式，多一个都不行）

flows[]、scripts[].path、events[].consumer[].handler 指向的文件都存在

entry 指向的导出函数真的在 TS 源文件里

所有 TS 能通过类型检查和构建

allowlist 里的能力名真实存在（见能力目录），申报了授不出的名字整包起不来

流程名、连接 ID、脚本键、实体名不与其他插件包冲突

路径段不以 _ 开头

常见问题

现象	原因与处理
装载报未知字段	严格解析；对照本页字段表逐个检查，尤其别抄旧文档的 `handlers[]`、`triggers[]`、`whitheList`
装载报契约不符	`contractsRange` 不含宿主契约版本；调整范围或先升级宿主
装载报能力名不可授予	`allowlist` 里有拼错或不存在的权限名
流程没被装载	`flows[]` 是白名单制，确认路径已列出且文件存在
校验报存储实体冲突	从源清单删掉手写的 `entities`；存储契约只写 `schema.sql`

顶层字段#

宿主契约版本范围（contractsRange）#

流程脚本（scripts[]）#

消息订阅（events[]）#

外部连接（connections[]）#

不要手写存储实体（entities）#

装载期检查清单#

常见问题#