企业官网建设流程全解析

• AI 应用
• 后端

本指南以 Botpress 开源仓库中packages/cli/templates/empty-plugin/hub.md这一官方插件文档模板为骨架，结合仓库内真实的插件脚手架源码（plugin.definition.ts、src/index.ts、package.json）与 SDK 实现（PluginDefinition、RuntimeError），系统讲解如何为即将发布到 Botpress Hub 的插件编写一份结构完整、信息密度高、可被开发者直接参照使用的技术文档。读完本文，你将掌握 hub.md 六大板块（简介、Configuration、Usage、Limitations、Changelog、发布自检清单）的写法、对应的源码支撑点，以及如何把发布自检清单落地到实际插件代码中。

为什么插件需要一个 hub.md 文档

Botpress 的插件（Plugin）是可复用的功能单元，通过PluginDefinition定义元信息，并借助 SDK 提供的运行时能力注入到 Bot 应用中。当插件要对外发布时，hub.md是它的“门面”——它既是人类开发者的阅读入口，也是 Hub 平台收录、展示插件能力时的信息源。

从 SDK 源码可以看到，PluginDefinition类在构造时会保存readme、title、description、icon等展示字段（见 packages/sdk/src/plugin/definition.ts），其中readme正是承载长文说明的字段。也就是说，hub.md所编写的内容与插件定义中的元数据是配套关系：plugin.definition.ts负责结构化信息（名称、版本、标题、描述、图标），hub.md负责完整的说明文档。

从脚手架角度看，empty-plugin模板是 CLI 官方提供的插件起点：在 packages/cli/src/project-templates.ts 中，plugin类型注册了 “Empty Plugin” 模板（identifier 为empty，默认项目名empty-plugin），其目录就位于packages/cli/templates/empty-plugin/，包含hub.md、plugin.definition.ts、src/index.ts、package.json、tsconfig.json五个文件。因此，本篇所讲解的 hub.md 结构，正是你使用 CLI 初始化插件项目后即可获得的文档骨架。

模板整体结构一览

empty-plugin/hub.md定义了一个固定且简洁的六段式骨架：

1. # Plugin Title（H1 标题）
2. ## Configuration（配置说明）
3. ## Usage（使用说明）
4. ## Limitations（限制与已知问题）
5. ## Changelog（变更日志）
6. ### Plugin publication checklist（发布自检清单）

这个顺序遵循了“是什么 → 怎么配 → 怎么用 → 有什么坑 → 版本演进 → 发布合规”的自然认知路径，能让读者在最短时间内完成“评估插件是否适合我 → 接入 → 排障”的闭环。下文将逐节说明每部分的撰写要点，并给出对应的源码验证依据。

标题与一句话简介：定义插件的“身份”

模板开篇：

# Plugin Title > Describe the plugin's purpose.

这里有两件事要做：

• # Plugin Title：替换为插件的实际名称，应与plugin.definition.ts中的name字段保持一致。模板中该字段来自package.json的pluginName：

// packages/cli/templates/empty-plugin/plugin.definition.ts import { PluginDefinition } from '@botpress/sdk' import { pluginName } from './package.json' export default new PluginDefinition({ name: pluginName, version: '0.1.0', })

• > Describe the plugin's purpose.：用 1～2 句话说明插件解决什么问题、面向什么场景。这句话是 Hub 列表页的摘要来源，建议直接点明“输入是什么、产出是什么、典型使用方是谁”，避免空泛宣传语。模板package.json中@botpress/sdk依赖版本为7.2.6，PluginDefinition正是来自该 SDK 包，说明元信息与文档是同一发布物的一部分。

Configuration：讲清楚“怎么把它跑起来”

模板要求：

## Configuration > Explain how to configure your plugin and list prerequisites `ex: accounts, etc.`. > You might also want to add configuration details for specific use cases.

这一节需要覆盖三类信息：

1. 前置条件（Prerequisites）：例如需要用户先注册的外部账号、API Key、网络环境、需要先安装的 Botpress 版本等。
2. 配置项清单：插件配置通常在plugin.definition.ts的configuration字段中声明，SDK 侧由ConfigurationDefinition承载（见 packages/sdk/src/plugin/definition.ts）。文档中应逐一列出每个配置键的名称、类型、必填/可选、默认值、含义及合法取值范围。
3. 特定用例的配置细节：如果插件有多个使用形态（例如“仅接收事件”与“同时执行动作”），可在此给出各自的最小配置示例。

一个值得强调的源码约束：模板发布自检清单第一项要求“The register handler is implemented and validates the configuration”（实现 register 处理器并校验配置）。虽然empty-plugin/src/index.ts中的最小实现只声明了空 actions：

// packages/cli/templates/empty-plugin/src/index.ts import * as bp from '.botpress' const plugin = new bp.Plugin({ actions: {}, }) export default plugin

但一旦插件引入外部资源，就需要在register阶段校验配置合法性。参考empty-integration模板的做法（packages/cli/templates/empty-integration/src/index.ts），校验失败时应抛出带说明的RuntimeError：

register: async () => { throw new sdk.RuntimeError('Invalid configuration') // replace this with your own validation logic }

RuntimeError在 Botpress 运行时的语义是“已处理、面向用户展示的失败”：从 packages/sdk/src/serve.ts 的注释与实现可以看到，显式抛出的RuntimeError会保留其 4xx 状态码并原样返回给调用方，让插件使用方立刻知道是“配置问题”而非“服务端偶发故障”；而其他未处理异常会被包装成 500 响应。因此，文档的 Configuration 一节若能说明“哪些配置错误会触发 RuntimeError 及对应的错误文案”，对使用者排障会非常有价值。

Usage：给出可复制的接入路径

模板要求：

## Usage > Explain how to use your plugin. > You might also want to include an example if there is a specific use case.

撰写建议：

• 从“安装 → 配置 → 在 Bot 中调用”的视角组织步骤，每一步给出可直接复制的代码或配置片段；
• 插件对外暴露的能力集中在actions（动作）与events（事件）上，二者在PluginDefinition中分别对应actions与events属性（见 packages/sdk/src/plugin/definition.ts）。文档应列出每个 action 的输入输出 schema 要点、每个 event 的触发时机与载荷结构；
• 如果插件依赖外部服务，给出典型调用链示例（例如：Bot 收到消息 → 调用插件 action → 插件调用外部 API → 通过事件回传结果）。

发布自检清单中与之相关的条款也提示了文档的覆盖范围：事件应尽量携带conversationId、userId、messageId；与channels、entities、user、conversations、messages相关的能力应实现为对应的事件与动作；与消息相关的事件应实现为消息形式。这些约束意味着 Usage 一节不仅要写“怎么调用”，还应写“事件里能拿到哪些上下文字段”。

Limitations：诚实声明边界

模板要求：

## Limitations > List the known bugs. > List known limits `ex: rate-limiting, payload sizes, etc.` > List unsupported use cases.

这一节应当明确列出：

• 已知缺陷（Known bugs）：尚未修复的问题及规避办法；
• 硬性限制：如外部 API 的 rate-limiting、请求/响应 payload 大小上限、超时时间、并发数等；
• 不支持的场景：明确“本插件不做 X”，避免使用者产生错误预期。

Limitations 是与 Changelog 联动的：每次修复了某个已知问题，就应把该项从 Limitations 移除并在 Changelog 中标注修复版本。这种“限制清单 + 变更日志”的双轨维护是模板刻意设计的闭环。

Changelog：记录版本演进

模板要求：

## Changelog > If some versions of your plugin introduce changes worth mentionning (breaking changes, bug fixes), describe them here. This will help users to know what to expect when updating the plugin.

Changelog 的核心目标是让使用者“升级前知道会发生什么”。建议记录以下变更类型：

• 破坏性变更（Breaking changes）：如配置键重命名、action 输入 schema 收紧、事件载荷结构调整、依赖的 Botpress SDK 主版本升级；
• Bug 修复：与 Limitations 中的已知问题对应；
• 新能力：新增的 action、事件或配置项。

模板本身对版本号的起点有明确参考：empty-plugin/plugin.definition.ts中version为0.1.0，package.json中name为@bp-templates/empty-plugin、pluginName为empty-plugin，并提供了check:type脚本（tsc --noEmit）用于发布前类型检查。在正式发布插件时，plugin.definition.ts的version需要随每次发布递增，并保持与 Changelog 条目一一对应。

Plugin publication checklist：发布前的硬性合规清单

模板以 “Plugin publication checklist” 作为收尾，这是一份发布审核清单，逐项对照可确保插件满足 Hub 的发布要求：

• register 处理器已实现并校验配置：参考 packages/cli/templates/empty-integration/src/index.ts 的RuntimeError校验写法；
• plugin.definition.ts中所有 schema 都有标题与描述：这些标题/描述会直接展示给 Hub 使用者，是ConfigurationDefinition、ActionDefinition等 schema 元数据的一部分（见 packages/sdk/src/plugin/definition.ts 附近对actions、tables、workflows的声明结构）；
• 事件在可用时存储conversationId、userId与messageId：保证事件具备完整的会话上下文；
• 与channels、entities、user、conversations、messages相关的能力已实现为对应的事件与动作：这是 Botpress 领域模型对插件能力边界的约定；
• 与消息相关的事件实现为消息：确保消息类事件遵循统一的消息格式；
• 当需要 Bot 开发者执行某个操作时，抛出附带修复指引的RuntimeError：从 packages/sdk/src/serve.ts 可知，RuntimeError会保留 4xx 状态原样返回，错误信息可直接指导使用方修正配置；
• 插件配置中提供 Bot 名称与 Bot 头像 URL 字段：这两项是 Hub 展示与 Bot 个性化所必需的标准配置。

从模板文件所在的仓库位置 packages/cli/templates/empty-plugin/hub.md 可以看出，这份清单与empty-integration/hub.md中的 “Integration publication checklist” 结构完全一致（见 packages/cli/templates/empty-integration/hub.md），说明它是 Botpress 对插件与集成两类发布物统一的合规基线。

从模板到成稿：一篇合格 hub.md 的最终形态

综合以上分析，将empty-plugin/hub.md模板各占位符替换为真实内容后，一篇合格的插件文档应具备以下特征：

1. 结构完整：六段骨架齐全，不省略 Configuration 或 Limitations；
2. 信息自洽：标题/描述与plugin.definition.ts的name、title、description一致，配置项与configurationschema 一致，版本号与 Changelog 条目一一对应；
3. 可验证：每个 action、event 都能在src/index.ts的bp.Plugin({ actions, events })实现中找到对应定义，配置校验逻辑真实存在并抛出RuntimeError；
4. 面向读者：Usage 提供可直接复制的接入示例，Limitations 诚实列出边界，Changelog 明确标注破坏性变更；
5. 通过自检清单：逐项勾选发布 checklist，尤其确认“配置校验抛 RuntimeError”“schema 有标题描述”“事件携带会话三 ID”“提供 Bot 名称与头像字段”等硬性要求。

把这份 hub.md 与 plugin.definition.ts、src/index.ts 一同提交，你的插件就同时具备了“可运行”与“可理解”两个发布条件——前者由源码保证，后者正是这份文档的职责所在。

• AI 应用
• 后端