Botpress Confluence 集成实战：从项目计划模板 jsonExample.md 到 Markdown→HTML 渲染管线-平芜编程栈

AI 应用
后端

【免费下载链接】botpress

The open-source hub to build & deploy GPT/LLM Agents ⚡️

项目地址：https://gitcode.com/gh_mirrors/bo/botpress

导读

本文聚焦 Botpress 开源仓库中 Confluence 集成（integrations/confluence）的测试文档integrations/confluence/src/parser/testFiles/jsonExample.md，深入拆解这份 Confluence 项目计划模板的内容结构、它与同目录jsonExample.json（Confluence 存储格式 JSON）的对应关系，以及 Botpress 集成中真正消费这类 Markdown 内容的转换管线markdownToHtml.ts。读完本文，你将掌握：这类模板在集成测试中扮演什么角色、其背后的 Markdown→HTML 转换原理，以及该转换结果如何被createPage/updatePage动作写入 Confluence 页面。

文档定位：一份为集成测试而生的 Confluence 项目计划模板

jsonExample.md位于 integrations/confluence/src/parser/testFiles/ 目录，与jsonExample.json、jsonExample2.md/.json、jsonExample3.md/.json以及GDD_Legends_of_Eldoria_Confluence_StorageFormat.md/.json同处一地，构成该目录下 parser 功能的测试样例集合。从内容看，这份文档本身是一份典型的 Confluence 项目计划模板（Project Plan Template，法语版本），用于承载项目的背景、范围、时间线、里程碑等信息——这正是 Confluence 作为团队协作与文档中心最常见的页面形态之一。

文档开头有一句法文提示，说明其用途：

Nous avons ajouté un exemple de contenu pour vous aider à démarrer les tests de votre plan de projet. Explorez ce contenu et modifiez-le pour vous l'approprier.

（大意：我们添加了示例内容，帮助你启动项目计划的测试。请探索这些内容并修改以使其适合自己。）

这句话揭示了它的真实角色：它不是生产文档，而是用来测试的示例内容——验证 Botpress Confluence 集成能否正确解析、转换这类包含复杂格式（表格、提及、状态、日期、路线图宏等）的页面内容。结合 markdownToHtml.ts 的存在，可以推断该模板用于验证"Confluence 富内容 → Markdown → HTML（storage 格式）"这一转换链路。

模板内容逐段解析

模板结构完整覆盖了项目计划的核心要素，以下按原文顺序展开。

1. 项目元信息表

文档顶部是一张两列信息表，用 Markdown 表格语法表达 Confluence 的"字段定义表"（label/value 对）：

🚗 Meneur（负责人）	@Michael Masson
⚡️ Équipe（团队）	Mentionnez les contributeurs (p. ex., @xavier)（提及贡献者，如 @xavier）
📆 Date d'échéance（截止日期）	03/04/2025
État（状态）	[en cours]（进行中）

这段内容在 jsonExample.json 中有对应的富文本结构：左侧单元格为strong加粗文本，右侧分别使用mention（提及 @Michael Masson）、placeholder（占位符）、date（时间戳1743724800000，即 2025-04-04）和status（颜色 yellow、样式 bold、文本 "en cours"）节点类型。也就是说，表格中的@Michael Masson对应 Confluence 的 mention 节点、[en cours]对应 status 节点、日期对应 date 节点——模板在 Markdown 层的"降级"表示，还原了 Confluence 编辑器中的交互式元素。

2. 问题陈述（Énoncé du problème）

## 🤔 Énoncé du problème _Décrivez le problème et son impact. Incluez l'hypothèse qui sous-tend votre travail（« Nous pensons que X fera Y, et nous saurons que nous avons réussi si Z »）._ D'après une récente étude menée auprès de clients, nous souhaitons augmenter le chiffre d'affaires de nos secteurs d'activité.

该小节给出问题背景，并内置了撰写假设的提示（"我们相信 X 将带来 Y，若 Z 发生则说明成功"）。斜体部分是 Confluence placeholder（占位提示文本）的 Markdown 呈现，在 JSON 中对应placeholder节点；正文段落则是实际写入的真实内容。

3. 范围（Portée）

范围以"三栏语义"表格组织，区分必做（Requis）、期望（Souhaitable）、超出范围（Hors périmètre）：

Requis：通过创新识别并捕获新细分市场，重振客户增长与收入；
Souhaitable：重振客户多个细分市场；
Hors périmètre：与主营业务无关的一切工作。

在 JSON 源中，这三行分别是tableHeader（背景#e3fcef）、普通tableCell（背景#fffae6）和tableCell（背景#ffebe6），内容为bulletList列表项，其中既有placeholder提示也有实际文本。这展示了 Confluence 存储格式如何用节点嵌套（table → tableRow → tableCell → bulletList → listItem → paragraph → text）表达复杂排版。

4. 时间线（Chronologie）与路线图宏

这是模板中结构最复杂、最能体现 Confluence 特色的部分。正文提示用户可输入/planificateur创建可视化路线图，随后以 Markdown 形式"平铺"了一个名为Planificateur de feuille de route（路线图规划器）的 Roadmap Planner 宏：

Timeline：2024-03-01 00:00:00 至 2024-11-30 00:00:00；
Phase 1：identification du problème（问题识别，颜色 #654982），含 6 条 bar：Nouvelle barre（2020-01-01，1 个月）、Lancement de projet（2024-03-01，1 个月）、Analyse des entreprises concurrentes（2024-03-31，3 个月）、Analyser les données produit（2024-04-01，3 个月）、Réfléchir à des solutions（2024-06-12，2 个月）、Nouvelle barre（2020-01-01，1 个月）；
Phase 2：élaboration de la solution（方案制定，颜色 #3b7fc4），含 5 条 bar：Nouvelle barre、Recherches sur les clients de type entreprise（2024-07-24，2 个月）、Peaufiner les solutions（2024-08-17，2 个月）、Lancement de produit（2024-10-15，2 个月）、Nouvelle barre；
Milestones（里程碑）：Atelier avec des parties prenantes（2024-07-30）、Revue du leadership nº 1（2024-10-16）。

对照 JSON 可以发现，这个宏在 Confluence 存储格式中是extension节点（extensionType: com.atlassian.confluence.macro.core、extensionKey: roadmap），所有路线图数据（lane 颜色、bar 起始日期与时长、marker 日期与标题）都被 URL 编码后塞进parameters.macroParams.source.value字段，并附带hash与macroMetadata。换句话说，Markdown 中的平铺列表正是该宏 JSON 数据的"人类可读"投影——这也是为什么这份模板对解析器测试极具价值：它必须处理extension、panel、mention、status、date、inlineCard等十余种节点类型。

5. 重要里程碑与截止日期表

## 🚩 Étapes importantes et échéances | Étape importante | Propriétaire | Échéance | État | | --- | --- | --- | --- | | p. ex., Finaliser les conceptions pour la v1 | @propriétaires | Saisissez // pour ajouter une date | | | ➕ Invitez des membres de l'équipe à rejoindre votre projet | | 03/04/2025 | **[À faire]** | | 🥳 Terminez le plan du projet et assignez des tâches | | 03/04/2025 | **[À faire]** |

该表四列（里程碑 / 负责人 / 截止日期 / 状态），首行是占位示例，后两行是真实待办，状态列使用[À faire]（待办）标记——对应 JSON 中status节点（颜色 red、样式 bold）。

6. 相关支持（Supports connexes）

文档末尾只有一个内联卡片链接（inlineCard节点），指向 Atlassian 草稿页 URL：

https://botpress.atlassian.net/wiki/pages/resumedraft.action?draftId=131178

注意：这是模板自身携带的示例链接，仅存在于测试样例中，并非本文可引用的外部资源。

测试文件的孪生结构：Markdown 与 JSON 一一对应

jsonExample.md并非孤立存在，它与 jsonExample.json 是同一份文档的两种表示：.json是 Confluence 新编辑器（Atlas/ProseMirror 系）的atlas_doc_format 存储格式，.md是其渲染后的 Markdown 视图。二者的对应关系整理如下：

Markdown 元素	JSON 节点类型	说明
```info ... ```	`panel`（panelType: info）	提示面板
表格	`table`→`tableRow`→`tableCell`/`tableHeader`	含背景色、colwidth 等 attrs
`@Michael Masson`	`mention`	人员提及，带 account id
斜体提示语	`placeholder`	编辑器占位文本
`03/04/2025`	`date`（timestamp）	日期选择器
`[en cours]`/`[À faire]`	`status`（color/style/text）	状态徽章
`# Planificateur de feuille de route`	`extension`（roadmap 宏）	路线图宏，数据在 URL 编码的 source 中
末尾链接	`inlineCard`	智能链接卡片

这份孪生结构正是 parser 测试的抓手：给定 JSON 存储格式，能否无损渲染出对应的 Markdown；给定 Markdown，能否还原为可在 Confluence 落地的 HTML。

源码纵深：Markdown→HTML 转换管线是如何工作的

真正消费这类 Markdown 的代码是 integrations/confluence/src/parser/markdownToHtml.ts，全文仅 13 行，却串联起完整的 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): Promise<string> => unified() .use(remarkParse) .use(remarkGfm) .use(remarkRehype) .use(rehypeStringify) .process(gfm) .then((htmlFile) => htmlFile.toString())

各环节职责：

remarkParse：把 Markdown 文本解析为 mdast 语法树；
remarkGfm：启用 GitHub Flavored Markdown 扩展——这是模板中表格、任务列表等元素能被正确解析的关键，例如上文所有元信息表、里程碑表都依赖 GFM 表格语法；
remarkRehype：将 mdast 转换为 hast（HTML 抽象语法树）；
rehypeStringify：将 hast 序列化为 HTML 字符串。

该函数在 client.ts 中被引用：createPage与updatePage两个动作都会先调用convertMarkdownToHtml(input.item.body.atlas_doc_format.value)，把页面正文的 atlas_doc_format 值转成 HTML，再以representation: 'storage'（即 HTML 存储格式）随页面数据提交给 Confluence REST API v2（POST /wiki/api/v2/pages与POST /wiki/api/v2/page/{id}）。在 create-page.ts 中，动作从输入item中取出id，创建ConfluenceClient（基于配置的user、host、apiToken构造 Basic Auth 头），然后调用client.createPage(input)。

由此形成完整链路：

Confluence 页面 (atlas_doc_format) → 集成读取 body 值（如模板 Markdown） → convertMarkdownToHtml()：Markdown → GFM → HTML → 以 storage 格式写回 Confluence 页面（创建/更新）

jsonExample.md这类测试文件正是为了验证该链路对复杂模板的兼容性：表格、提及、状态、日期、路线图宏平铺文本、内联卡片等全部出现于同一份文档中，任何解析环节的遗漏都会在转换结果中暴露。

测试样例家族的横向对比

testFiles目录下的其他样例共同勾勒出 parser 的测试覆盖面：

jsonExample2.md：另一份法文项目模板（Mural 提供），结构更偏"空白问卷"——非满足需求、目标、用户画像、待完成工作、历史背景、约束、探索与决策、版本、后续步骤、影响、其他文档等 11 个章节，大量使用斜体占位提示，用于测试占位符密集内容的解析；
jsonExample3.md/.json：第三组样例，进一步覆盖不同模板变体；
GDD_Legends_of_Eldoria_Confluence_StorageFormat.md/.json：以游戏设计文档（GDD）为内容的更大型样例，标题为# 🧙 Game Design Document - Legends of Eldoria，覆盖较长篇幅的富格式文档解析。

可以推断，这组样例的设计意图是覆盖从简短模板到长篇文档、从稀疏占位到密集宏内容的各种真实 Confluence 页面形态，为convertMarkdownToHtml提供回归测试语料。

小结

jsonExample.md看似只是一份法语项目计划模板，实则是 Botpress Confluence 集成中具有双重身份的测试资产：一方面，它完整呈现了 Confluence 项目计划页面的标准信息架构（元信息表、问题陈述、范围、时间线、里程碑、相关支持）；另一方面，它与jsonExample.json构成同一内容的两视图，是验证 markdownToHtml.ts 转换管线的理想语料——该管线通过 unified + remarkGfm 解析模板中复杂的 GFM 表格与富文本语法，并将结果以storage格式经createPage/updatePage动作写回 Confluence。理解这份模板，等于同时理解了 Botpress 集成在"读取 Confluence 富内容 → 转换为 Markdown → 再以 HTML 落回 Confluence"这条闭环中的核心数据流。