ARTICLE DETAIL

资讯详情

深耕郑州网站建设与运营推广的一线实战洞察。

Botpress Confluence 集成中 Markdown 与 ADF(Atlas Doc Format)双向转换的测试样本解析

Botpress Confluence 集成中 Markdown 与 ADF(Atlas Doc Format)双向转换的测试样本解析 AI 应用后端【免费下载链接】botpressThe open-source hub to build deploy GPT/LLM Agents ⚡️项目地址https://gitcode.com/gh_mirrors/bo/botpress点击查看免费下载导读本文以 Botpress 开源仓库中 Confluence 集成的解析器测试文件为切入点围绕GDD_Legends_of_Eldoria_Confluence_StorageFormat.md这一真实测试样本系统讲解 Confluence「存储格式Storage Format→ Markdown」与「Markdown → HTML存储格式→ ADFAtlas Doc Format」的转换链路、AST 结构映射规则以及该链路在createPage/updatePage/transfer-file-to-botpress等实际动作中的落地方式。读完本文你将能读懂 Confluence 页面导出的 ADF JSON 结构掌握 Botpress Confluence 集成中 Markdown 与 Confluence 原生格式之间的转换机制与测试样本设计方法。一、测试样本在仓库中的定位它是什么为什么存在在 Botpress 仓库中Confluence 集成位于 integrations/confluence其源码结构包含src/parser/—— Markdown/HTML 转换解析器src/actions/implementations/—— 页面增删改查与文件传输动作src/client.ts—— 基于 Confluence REST API 的客户端封装definitions/—— 页面page、评论comment等实体的类型定义而GDD_Legends_of_Eldoria_Confluence_StorageFormat.md位于 integrations/confluence/src/parser/testFiles/ 目录是该解析器的测试样本文件test fixture。同目录下还配套存放了它的 ADF 形态 GDD_Legends_of_Eldoria_Confluence_StorageFormat.json以及另外三组jsonExample*.md/jsonExample*.json样本对。从仓库的样本命名与配对方式可以推断测试样本采用「同一内容、两种载体」的组织策略——.md文件代表开发者/LLM 侧的自然语言Markdown形态.json文件代表 Confluence 页面在 REST API 中以atlas_doc_format返回的 ADF 形态。二者一一对应正好覆盖了集成中两个方向的转换测试写入方向Markdown → HTML存储格式→ 提交给 Confluence REST API读取方向Confluence 返回的 ADF → 解析为可读内容。二、样本内容拆解一个典型的 Confluence 存储格式页面GDD_Legends_of_Eldoria_Confluence_StorageFormat.md是一个用法语撰写的「游戏设计文档GDD」测试页篇幅不长但刻意覆盖了 Confluence 存储格式中最常见的三类结构2.1 标题与元信息行# Game Design Document - Legends of Eldoria Date de création: **2025-04-10** | Auteur: **Jean Dupuis** | Version: **1.2**H1 标题对应 ADF 中的heading节点level: 1而元信息行通过**粗体**标记对应 ADF 中的marks: [{ type: strong }]嵌入同一段落用于验证「行内文本 加粗标记」的转换。2.2 表格table| Élément | Détail | | ------------ | -------------------------------------- | | Nom du jeu | Legends of Eldoria | | Genre | Action-RPG en monde semi-ouvert | | Vue | 3D isométrique | | Mode de jeu | Solo Coop en ligne jusqu’à 4 joueurs | | Durée de jeu | 25-40h de contenu principal | | Plateformes | PC (Steam), Xbox Series X/S, PS5 | | Moteur | Unity 2023 LTS |对照其 ADF 版本 GDD_Legends_of_Eldoria_Confluence_StorageFormat.json 可以看到这个 Markdown 表格被完整映射为 ADF 的嵌套结构table节点对应整张表tableRow节点对应每一行tableHeader/tableCell节点分别对应表头单元格与数据单元格单元格内部再以text节点承载具体文本内容。这正是 Confluence 存储格式Storage Format的表单表达能力表格不只是 Markdown 的|分隔文本而是一棵完整的 AST 子树。2.3 Pitch 段落paragraph hardBreakUn monde brisé. Des héros oubliés. Et un empire à reconstruire. Legends of Eldoria est un RPG coopératif où le joueur incarne un ancien héros réincarné. Explorez des terres ravagées, restaurez des cités, et défiez des entités magiques pour ramener léquilibre dans un monde en ruine.Markdown 中的连续两行文本在 ADF 中对应paragraph节点其中换行由hardBreak节点显式表达见 JSON 中第 285 行的type: hardBreak。这个细节说明Confluence 的 ADF 不会把 Markdown 的普通换行静默合并而是以显式节点保留段落内的断行语义这与 HTML 中br的语义一一对应。三、转换链路的源码级原理3.1 Markdown → HTMLconvertMarkdownToHtml解析器核心实现位于 integrations/confluence/src/parser/markdownToHtml.ts全文仅 14 行却是一条标准的 unified 处理管线import rehypeStringify from rehype-stringify import remarkGfm from remark-gfm import remarkParse from remark-parse import remarkRehype from remark-rehype import { unified } from unified export const convertMarkdownToHtml (gfm: string): Promisestring unified() .use(remarkParse) // 1. Markdown - Markdown AST (mdast) .use(remarkGfm) // 2. 启用 GFM 扩展表格、删除线、任务列表等 .use(remarkRehype) // 3. mdast - HTML AST (hast) .use(rehypeStringify) // 4. hast - HTML 字符串 .process(gfm) .then((htmlFile) htmlFile.toString())四个步骤依次完成remarkParse把 Markdown 文本解析为 mdastMarkdown 抽象语法树remarkGfm启用 GitHub Flavored Markdown 扩展这正是上文 Markdown 表格能够被正确解析的关键——标准 CommonMark 并不原生支持表格语法remarkRehype把 mdast 转换为 hastHTML 抽象语法树rehypeStringify把 hast 序列化为最终的 HTML 字符串。而测试样本 GDD_Legends_of_Eldoria_Confluence_StorageFormat.md 中的标题、粗体、表格等结构正是验证 remark-gfm 表格扩展与常用标记语法在真实文本上转换正确性的样本输入。3.2 HTML → ADF存储格式与atlas_doc_format的衔接转换产物 HTML 以representation: storage提交给 Confluence这在 integrations/confluence/src/client.ts 中体现得非常明确。以createPage为例createPage: async (input: { item: Page.InferredType }) { if (!input.item.body) { throw new Error(Body is required) } const value await convertMarkdownToHtml(input.item.body.atlas_doc_format.value) const request: CreatePageBody { spaceId: input.item.spaceId, status: current, title: input.item.title ?? Temporary title, parentId: input.item.parentId, body: { representation: storage, // Confluence 存储格式 value, // Markdown 转换而来的 HTML }, } const response await axios.post(${apiBase}/pages, request, config) return response.data }updatePage采用完全相同的转换逻辑integrations/confluence/src/client.ts只是额外带上version.number与版本消息Updated by botpress。两个写入动作共用convertMarkdownToHtml说明该解析器是集成中「Markdown 内容入站」的唯一转换入口。而读取方向Confluence REST API 支持用body-formatatlas_doc_format请求体格式例如获取页脚评论时getFooterComments: async ({ pageId }: { pageId: string }) { const response await axios.get( ${apiBase}/pages/${pageId}/footer-comments?body-formatatlas_doc_format, config ) return response?.data }在 definitions/entities/page.ts、definitions/entities/comment.ts、definitions/entities/pageToCreate.ts 中atlas_doc_format均被定义为z.object({...})的 Zod 结构用于在运行时校验 Confluence 返回的 ADF 负载。也就是说GDD_*.json这类 ADF 样本同时还是实体类型定义Zod schema的验证语料——它必须能被atlas_doc_format的 Zod 描述合法解析。3.3 ADF 样本的校验价值为何 JSON 版本不可省略对比GDD_Legends_of_Eldoria_Confluence_StorageFormat.json与jsonExample.json可以发现ADF 是带类型信息的完整文档树{ version: 1, type: doc, content: [ { type: heading, attrs: { level: 1 }, content: [...] }, { type: paragraph, content: [...] }, { type: table, content: [ { type: tableRow, content: [...] } ] } ] }根节点固定为type: doc顶层字段version: 1每个节点通过type区分语义heading / paragraph / table / tableRow / tableHeader / tableCell / text / hardBreak……行内格式如粗体由marks: [{ type: strong }]描述与 HTML 的strong一一对应复杂表格还携带attrscolspan、rowspan、background、colwidth 等例如jsonExample.json中的background: #f4f5f7、colwidth: [179]。因此测试样本文件夹中每份.md都配有一份等价的.json其意义在于同一份内容分别以「Markdown 输入」和「Confluence 原生 ADF 输出」两种形态存在既能验证convertMarkdownToHtml对复杂语法表格、换行、粗体的转换正确性又能验证atlas_doc_formatZod schema 对真实 Confluence 负载的解析兼容性。四、样本在真实动作中的闭环从页面到知识库文件转换链路不止服务于页面写入还服务于「文件同步」场景。动作实现 integrations/confluence/src/actions/implementations/transfer-file-to-botpress.ts 展示了完整闭环export const filesReadonlyTransferFileToBotpress: bp.IntegrationProps[actions][filesReadonlyTransferFileToBotpress] async ({ logger, client, ctx, input: { file, fileKey, shouldIndex } }) { debugLog(logger, filesReadonlyTransferFileToBotpress, Transferring file to botpress) const confluenceClient ConfluenceClient(ctx.configuration) const pageContents await confluenceClient.getPageHtml({ pageId: parseInt(file.id) }) if (!pageContents) { throw new RuntimeError(Page is empty or not found) } const { file: uploadedFile } await client.uploadFile({ key: fileKey, content: pageContents, contentType: text/html, // 以 HTML 存储格式传输 index: shouldIndex ?? true, }) return { botpressFileId: uploadedFile.id } }流程为getPageHtml读取页面 → 校验非空否则抛出RuntimeError→client.uploadFile以text/html内容类型上传 → 默认开启索引index: shouldIndex ?? true。这意味着 Confluence 页面被转换成 HTML 后可以进入 Botpress 的文件/知识库体系供检索与问答使用——这与 Botpress「构建与部署 GPT/LLM Agent」的项目定位直接呼应。五、样本设计要点与二次开发建议综合上述分析testFiles/目录下的样本对设计遵循了几个可复用的原则一内容双载体每个.md文件必须存在等价.json文件保证转换双向可测覆盖高频语法标题多级、粗体、表格含表头/表体、段落内换行hardBreak是 Confluence 页面最高频的四种结构样本均覆盖到携带真实业务上下文样本选用真实的「游戏设计文档」内容含项目名、版本号、作者、平台矩阵、引擎版本等比纯语法占位符更能暴露边界问题如法文重音字符、数字范围25-40h、破折号等与 Zod schema 对齐ADF 样本必须能被 definitions/entities/ 下的atlas_doc_formatschema 合法解析否则说明 schema 或样本有一方需要修正。若需自行扩展测试样本建议按以下步骤操作在 Confluence 中创建包含表格、多级标题、粗体/斜体、换行、图片的页面通过 REST APIbody-formatatlas_doc_format导出 ADF JSON将 ADF JSON 反写为 Markdown 作为.md样本将两者成对放入 integrations/confluence/src/parser/testFiles/即可为新语法如任务列表、删除线、代码块补充转换验证。六、小结GDD_Legends_of_Eldoria_Confluence_StorageFormat.md表面上只是一份游戏设计文档实质上是 Botpress Confluence 集成解析器的核心测试语料它以真实业务内容验证了「MarkdownGFM→ HTMLstorage 表示→ 提交 Confluence / 上传知识库文件」以及「Confluence ADF → Zod 校验」这一整条双向链路的正确性。其背后是由 markdownToHtml.ts 的 unified 四步管线、client.ts 的createPage/updatePage/getFooterComments调用、以及 definitions/entities/ 的 Zod schema 共同支撑的实现体系。理解这份样本就等于理解了 Botpress 集成外部文档系统时「格式互转」这一关键环节的设计范式。赞分享AI 应用后端【免费下载链接】botpressThe open-source hub to build deploy GPT/LLM Agents ⚡️项目地址https://gitcode.com/gh_mirrors/bo/botpress点击查看免费下载相关推荐剖析 Botpress Confluence 集成的页面内容解析以 jsonExample3 测试样本为例的 ADF 与 Markdown 结构映射指南剖析 Botpress Confluence 集成的页面内容解析以 jsonExample3 测试样本为例的 ADF 与 Markdown 结构映射指南 本篇AI 应用后端Botpress Confluence 集成中的 Atlas 文档格式解析从 jsonExample2.md 看面板、占位符与任务清单的 GFM 转换实战Botpress Confluence 集成中的 Atlas 文档格式解析从 jsonExample2.md 看面板、占位符与任务清单的 GFM 转换实战 导AI 应用后端炉石传说插件HsMod告别等待解锁极致游戏体验的终极方案炉石传说插件HsMod告别等待解锁极致游戏体验的终极方案 HsMod是一款基于BepInEx框架开发的炉石传说模改插件专门为那些希望在游戏中节省时间、个性游戏开发创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表