★ FEATURED ARTICLE AI 应用后端【免费下载链接】botpressThe open-source hub to build deploy GPT/LLM Agents ⚡️项目地址https://gitcode.com/gh_mirrors/bo/botpress点击查看免费下载本指南以 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定义了一个固定且简洁的六段式骨架# Plugin TitleH1 标题## Configuration配置说明## Usage使用说明## Limitations限制与已知问题## Changelog变更日志### Plugin publication checklist发布自检清单这个顺序遵循了“是什么 → 怎么配 → 怎么用 → 有什么坑 → 版本演进 → 发布合规”的自然认知路径能让读者在最短时间内完成“评估插件是否适合我 → 接入 → 排障”的闭环。下文将逐节说明每部分的撰写要点并给出对应的源码验证依据。标题与一句话简介定义插件的“身份”模板开篇# Plugin Title Describe the plugins 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 plugins purpose.用 12 句话说明插件解决什么问题、面向什么场景。这句话是 Hub 列表页的摘要来源建议直接点明“输入是什么、产出是什么、典型使用方是谁”避免空泛宣传语。模板package.json中botpress/sdk依赖版本为7.2.6PluginDefinition正是来自该 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.这一节需要覆盖三类信息前置条件Prerequisites例如需要用户先注册的外部账号、API Key、网络环境、需要先安装的 Botpress 版本等。配置项清单插件配置通常在plugin.definition.ts的configuration字段中声明SDK 侧由ConfigurationDefinition承载见 packages/sdk/src/plugin/definition.ts。文档中应逐一列出每个配置键的名称、类型、必填/可选、默认值、含义及合法取值范围。特定用例的配置细节如果插件有多个使用形态例如“仅接收事件”与“同时执行动作”可在此给出各自的最小配置示例。一个值得强调的源码约束模板发布自检清单第一项要求“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校验失败时应抛出带说明的RuntimeErrorregister: 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.0package.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模板各占位符替换为真实内容后一篇合格的插件文档应具备以下特征结构完整六段骨架齐全不省略 Configuration 或 Limitations信息自洽标题/描述与plugin.definition.ts的name、title、description一致配置项与configurationschema 一致版本号与 Changelog 条目一一对应可验证每个 action、event 都能在src/index.ts的bp.Plugin({ actions, events })实现中找到对应定义配置校验逻辑真实存在并抛出RuntimeError面向读者Usage 提供可直接复制的接入示例Limitations 诚实列出边界Changelog 明确标注破坏性变更通过自检清单逐项勾选发布 checklist尤其确认“配置校验抛 RuntimeError”“schema 有标题描述”“事件携带会话三 ID”“提供 Bot 名称与头像字段”等硬性要求。把这份 hub.md 与 plugin.definition.ts、src/index.ts 一同提交你的插件就同时具备了“可运行”与“可理解”两个发布条件——前者由源码保证后者正是这份文档的职责所在。赞分享AI 应用后端【免费下载链接】botpressThe open-source hub to build deploy GPT/LLM Agents ⚡️项目地址https://gitcode.com/gh_mirrors/bo/botpress点击查看免费下载相关推荐material-components-web 组件 README 模板从占位符到发布级组件文档的完整编写指南material components web 组件 README 模板从占位符到发布级组件文档的完整编写指南 导读 本文以 material compone前端UI组件设计系统Telegraf Serializer 插件开发指南基于 EXAMPLE_README 模板编写高质量序列化器文档Telegraf Serializer 插件开发指南基于 EXAMPLE_README 模板编写高质量序列化器文档 Telegraf 的 Serializer可观测性指标监控运维Ray 文档示例 Notebook 编写指南基于 MyST 模板 template.md 的完整实战Ray 文档示例 Notebook 编写指南基于 MyST 模板 template.md 的完整实战 本指南以 Ray 仓库中的文档模板 template.m人工智能分布式训练强化学习任务调度模型推理服务后端上一篇【亲测免费】探索高效C构建工具Hunter——让依赖管理一键到位的终极方案下一篇【亲测免费】 探索MarzipanoGoogle打造的全景图像处理库创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
阅读完成 · 觉得有帮助？
