mastering-confluence

Confluence 管理技能

类型：项目 | 版本：2.2.0

管理 Confluence 文档：将页面下载为 Markdown、上传页面及图片、在格式间转换、集成图表，以及使用 CQL 搜索。

目录

• 重要限制
• 快速入门
• 核心功能
• 检查清单
• 参考文档
• 脚本

重要限制

请勿使用 MCP 上传页面——受大小限制（最大约 10–20 KB）

# Use REST API scripts instead:
python3 scripts/upload_confluence_v2.py document.md --id PAGE_ID

MCP 工具适合读取页面，但上传较大的内容时会失败。

快速入门

将 Markdown 上传到 Confluence

# Update existing page
python3 scripts/upload_confluence_v2.py document.md --id 780369923

# Create new page
python3 scripts/upload_confluence_v2.py document.md --space DEV --parent-id 123456

# Preview first (recommended)
python3 scripts/upload_confluence_v2.py document.md --id 780369923 --dry-run

将 Confluence 下载为 Markdown

# Single page
python3 scripts/download_confluence.py 123456789

# With child pages
python3 scripts/download_confluence.py --download-children 123456789

# Multiple pages
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()'
})

核心功能

功能	工具/脚本	参考
上传带图片的页面	upload_confluence_v2.py	上传指南
将页面下载为 Markdown	download_confluence.py	下载指南
转换 Markdown ↔ Wiki	convert_markdown_to_wiki.py	转换指南
搜索页面（CQL）	MCP confluence_search	CQL 参考
Wiki Markup 语法	-	Wiki Markup 指南
渲染 Mermaid 图表	render_mermaid.py	图片处理
Git 与 Confluence 同步	mark CLI	mark 工具指南
故障排除	-	故障排除指南

检查清单

上传检查清单

复制并跟踪进度：

Upload Progress:
- [ ] Diagrams converted to PNG/SVG (if Mermaid/PlantUML present)
- [ ] All images use markdown syntax: ![alt](path)
- [ ] No raw Confluence XML in markdown
- [ ] All image files verified to exist
- [ ] Dry-run tested: `--dry-run`
- [ ] Upload executed with v2 script (not MCP)
- [ ] Page URL verified accessible

下载检查清单

Download Progress:
- [ ] Page ID obtained from Confluence URL
- [ ] Credentials configured in .env file
- [ ] Output directory specified
- [ ] --download-children flag set (if hierarchy needed)
- [ ] Download completed successfully
- [ ] Attachments downloaded to {Page}_attachments/
- [ ] Frontmatter contains correct metadata

图片处理

标准工作流：

1. 转换图表（如果是 Mermaid/PlantUML）：

   # Mermaid
   mmdc -i diagram.mmd -o diagram.png -b transparent
   
   # PlantUML
   plantuml diagram.puml -tpng
   

2. 在 Markdown 中引用（始终使用 Markdown 语法）：

   ![Architecture Diagram](./diagrams/architecture.png)
   

3. 上传（脚本会处理附件）：

   python3 scripts/upload_confluence_v2.py document.md --id PAGE_ID
   

常见错误：

• 使用原始 XML：<ac:image>...——会被 HTML 转义，并以文本形式显示
• 使用 MCP 上传——大小限制会导致失败
• 忘记转换图表——代码块不会渲染

参考文档

文档	用途
upload_guide.md	完整的上传工作流
download_guide.md	完整的下载工作流
wiki_markup_guide.md	Wiki Markup 语法参考
conversion_guide.md	Markdown ↔ Wiki Markup 转换规则
image_handling_best_practices.md	图表和图片
troubleshooting_guide.md	常见错误及修复方法
mark_tool_guide.md	Git 与 Confluence 同步
confluence_storage_format.md	API 存储格式
cql_reference.md	CQL 查询语法
atlassian_mcp_tools.md	MCP 工具参考

脚本

脚本	用途
upload_confluence_v2.py	上传带图片的 Markdown（无大小限制）
download_confluence.py	将页面及附件下载为 Markdown
convert_markdown_to_wiki.py	将 Markdown 转换为 Wiki Markup
render_mermaid.py	将 Mermaid 图表渲染为 PNG/SVG
generate_mark_metadata.py	生成 mark CLI 元数据标头
confluence_auth.py	共享身份验证实用工具

依赖项

pip install atlassian-python-api md2cf python-dotenv PyYAML mistune \
            requests markdownify beautifulsoup4

前提条件

必需

• Atlassian MCP Server（mcp__atlassian），并配置 Confluence 凭据

可选

• mark CLI：Git 与 Confluence 同步

  brew install kovetskiy/mark/mark
  

• Mermaid CLI：图表渲染

  npm install -g @mermaid-js/mermaid-cli
  

不适用场景

• 读取简单页面 → 直接使用 MCP
• 没有图片或图表、内容较少 → 可以使用 MCP
• Jira 问题 → 使用 Jira 专用工具

---

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