mastering-confluence

用途

本技能用于全面管理 Confluence 文档，覆盖下载、上传、格式转换、图表集成与搜索等常见文档工作流。适用于需要将本地 Markdown 文档同步到 Confluence，或从 Confluence 导出页面进行编辑与归档的场景。

主要能力

上传页面（含图片）：使用 upload_confluence_v2.py 脚本，支持更新已有页面或创建新页面，并可先执行 --dry-run 预览。
下载页面为 Markdown：使用 download_confluence.py，支持单页、多页以及包含子页面的下载，附件会保存到 {Page}_attachments/ 目录。
格式转换：使用 convert_markdown_to_wiki.py 在 Markdown 与 Wiki Markup 之间转换。
搜索页面：通过 MCP 的 confluence_search 使用 CQL 查询语法。
渲染 Mermaid 图表：使用 render_mermaid.py 将 Mermaid 图表渲染为 PNG/SVG。
Git 到 Confluence 同步：通过 mark CLI 实现。

使用方式

上传 Markdown 到 Confluence：

# 更新已有页面
python3 scripts/upload_confluence_v2.py document.md --id 780369923

# 创建新页面
python3 scripts/upload_confluence_v2.py document.md --space DEV --parent-id 123456

# 先预览（推荐）
python3 scripts/upload_confluence_v2.py document.md --id 780369923 --dry-run

下载 Confluence 页面为 Markdown：

# 单页
python3 scripts/download_confluence.py 123456789

# 包含子页面
python3 scripts/download_confluence.py --download-children 123456789

# 多页
python3 scripts/download_confluence.py 123456 456789 789012

转换 Markdown 为 Wiki Markup：

python3 scripts/convert_markdown_to_wiki.py input.md output.wiki

搜索 Confluence（通过 MCP）：

mcp__atlassian__confluence_search({
  query: 'space = "DEV" AND text ~ "API" AND created >= startOfYear()'
})

关键约束

不要使用 MCP 上传页面：MCP 存在约 10-20KB 的大小限制，上传大内容会失败。应改用 REST API 脚本 upload_confluence_v2.py。MCP 工具适合读取页面。
图片处理：在 Markdown 中始终使用标准 Markdown 语法引用图片，如 ![Architecture Diagram](./diagrams/architecture.png)。不要使用原始 Confluence XML（如 <ac:image>），否则会被 HTML 转义并显示为文本。
图表需先转换为 PNG/SVG，例如使用 mmdc -i diagram.mmd -o diagram.png -b transparent 或 plantuml diagram.puml -tpng，否则代码块不会渲染。

适用场景

将本地 Markdown 文档（含图片、Mermaid/PlantUML 图表）发布到 Confluence。
从 Confluence 批量导出页面及附件为 Markdown 进行本地编辑或版本管理。
在 Markdown 与 Wiki Markup 之间转换内容。
使用 CQL 在 Confluence 中检索页面。
通过 mark CLI 实现 Git 仓库与 Confluence 的同步。

限制与前置条件

需要 Atlassian MCP Server（mcp__atlassian）并配置 Confluence 凭据。
可选依赖：mark CLI（brew install kovetskiy/mark/mark）用于 Git 同步；Mermaid CLI（npm install -g @mermaid-js/mermaid-cli）用于图表渲染。
Python 依赖：pip install atlassian-python-api md2cf python-dotenv PyYAML mistune requests markdownify beautifulsoup4。
不适用场景：简单页面读取可直接使用 MCP；无图片/图表且内容较小时 MCP 可能可用；Jira 问题应使用 Jira 专用工具。

参考文档

技能包含多份参考文档，如 upload_guide.md、download_guide.md、wiki_markup_guide.md、conversion_guide.md、image_handling_best_practices.md、troubleshooting_guide.md、mark_tool_guide.md、confluence_storage_format.md、cql_reference.md、atlassian_mcp_tools.md。

版本：2.2.0 | 最后更新：2025-12-28