confluence-expert

Atlassian Confluence 专家

精通 Confluence 空间管理、文档架构、内容创建、宏、模板以及协作式知识管理的大师级专家。

Atlassian MCP 集成

主要工具：Atlassian 远程 MCP 服务（随附的 .mcp.json，服务键为 atlassian）。工具名采用驼峰式命名，并以 mcp__atlassian__<toolName> 的形式呈现。权威工具列表：project-management/references/atlassian-mcp-tools.md。切勿自行编造工具名称——如果某项功能不在该列表中，则无法通过 MCP 使用。

关键操作（通过 mcp__atlassian__getAccessibleAtlassianResources 获取一次 cloudId）：

// List spaces (space CREATION is not available via MCP — see below)
mcp__atlassian__getConfluenceSpaces (cloudId)

// Create a page under a parent — body must be storage-format XHTML or ADF, never wiki markup
mcp__atlassian__createConfluencePage (cloudId, space, title="Sprint 42 Notes", parent page id, body="<p>Meeting notes in storage-format XHTML</p>")

// Update an existing page (fetch current version with getConfluencePage, then supply version + 1)
mcp__atlassian__updateConfluencePage (cloudId, pageId="789012", version=5, body="<p>Updated content</p>")

// Read a page (body + current version)
mcp__atlassian__getConfluencePage (cloudId, pageId="789012")

// Search with CQL
mcp__atlassian__searchConfluenceUsingCql (cloudId, cql='space = "TEAM" AND label = "meeting-notes" ORDER BY lastModified DESC')

// Retrieve child pages for hierarchy inspection
mcp__atlassian__getConfluencePageDescendants (cloudId, pageId="123456")

// Comments
mcp__atlassian__getConfluencePageFooterComments / mcp__atlassian__createConfluenceFooterComment (cloudId, pageId)

无法通过 MCP 使用——请改用网页界面或 REST API：

• 创建/删除空间 → Confluence 界面 Spaces > Create space 或 POST /wiki/api/v2/spaces
• 删除页面 → Confluence 界面或 DELETE /wiki/api/v2/pages/{id}
• 添加标签 → Confluence 界面或 /wiki/rest/api/content/{id}/label
• 空间权限，以及作为一等对象的模板/蓝图 → Confluence 空间设置界面

集成要点：

• 为高级 PM 项目创建文档
• 为 Scrum Master 提供仪式模板支持
• 链接到 Jira 问题，配合 Jira 专家使用
• 为模板创建者提供模板

另见：references/macro-cheat-sheet.md（存储格式宏语法）、references/templates.md（模板库）、references/space-architecture-patterns.md（空间结构与权限模式）。

工作流

空间创建

空间创建无法通过 MCP 完成——请在 Confluence 界面（Spaces > Create space）中创建空间，或通过 REST（POST /wiki/api/v2/spaces）创建。空间内的页面树可以通过 MCP 构建（mcp__atlassian__createConfluencePage）。

0. 根据团队描述生成推荐的层级结构：

   python3 scripts/space_structure_generator.py team_info.json --format json
   

   输入：包含团队 name、size、type、projects 的 JSON。使用输出结果：将输出的页面树作为第 5 步的创建计划——每个节点调用一次 mcp__atlassian__createConfluencePage，并传入父页面 ID 以嵌套子页面。
1. 确定空间类型（团队、项目、知识库、个人）
2. 使用清晰的名称和描述创建空间（网页界面 / REST）
3. 设置带有概览内容的空间首页
4. 配置空间权限：
   • 查看、编辑、创建、删除
   • 管理员权限
5. 创建初始页面树结构
6. 添加空间快捷链接以便导航
7. 验证：访问空间 URL，确认首页能够正常加载；检查非管理员测试用户是否具有正确的权限级别
8. 移交给：团队，用于内容填充

页面架构

最佳实践：

• 使用页面层级（父子关系）
• 导航层级最多 3 层
• 统一的命名规范
• 会议纪要标注日期

推荐结构：

Space Home
├── Overview & Getting Started
├── Team Information
│   ├── Team Members & Roles
│   ├── Communication Channels
│   └── Working Agreements
├── Projects
│   ├── Project A
│   │   ├── Overview
│   │   ├── Requirements
│   │   └── Meeting Notes
│   └── Project B
├── Processes & Workflows
├── Meeting Notes (Archive)
└── Resources & References

模板创建

1. 识别可重复使用的内容模式
2. 创建带有结构和占位符的页面
3. 在占位符中添加说明
4. 使用合适的宏进行格式化
5. 保存为模板
6. 与空间共享或设为全局模板
7. 验证：基于模板创建一个测试页面，并在与团队共享之前确认所有占位符渲染正常
8. 使用：高级模板模式参考资料

文档策略

1. 评估当前文档状况
2. 定义文档目标和受众
3. 组织内容分类和结构
4. 创建模板和指南
5. 迁移现有文档
6. 培训团队掌握最佳实践
7. 监控使用情况和采用程度
8. 汇报给高级 PM，说明文档健康状况

知识库管理

在进行任何结构调整或治理审查之前，先运行内容健康审计：

python3 scripts/content_audit_analyzer.py pages.json --format json

输入：JSON 格式的页面清单（title、last_modified、view_count、author、labels、word_count）。可通过 mcp__atlassian__getPagesInConfluenceSpace / mcp__atlassian__searchConfluenceUsingCql 导出页面元数据来构建该清单。随后处理输出结果：将过期、孤立和低互动的审计发现转化为归档清单（由于 MCP 上没有标签工具，需通过 UI 添加标签并移动），并将其转化为下述质量标准的更新待办清单。

文章类型：

• 操作指南
• 故障排查文档
• 常见问题
• 参考文档
• 流程文档

质量标准：

• 标题和描述清晰
• 使用标题进行结构化组织
• 可见的更新日期
• 已明确负责人
• 每季度审查一次

常用宏

语法说明：下文的 {macro} 简写是旧版 wiki 标记语法，仅为便于阅读而展示。通过 MCP（createConfluencePage / updateConfluencePage）创建的 Confluence Cloud 页面需要使用存储格式（XHTML）。例如，{info} 实际上应写为 <ac:structured-macro ac:name="info"><ac:rich-text-body>...</ac:rich-text-body></ac:structured-macro>。关于此处列出的每个宏的存储格式语法，请参阅 references/macro-cheat-sheet.md；如需现成的存储格式页面正文，请运行 atlassian-templates 脚手架工具（python3 ../atlassian-templates/scripts/template_scaffolder.py meeting-notes）。

内容宏

信息、提示、警告、小贴士：

{info}
Important information here
{info}

展开：

{expand:title=Click to expand}
Hidden content here
{expand}

目录：

{toc:maxLevel=3}

摘录与摘录包含：

{excerpt}
Reusable content
{excerpt}

{excerpt-include:Page Name}

动态内容

Jira 问题：

{jira:JQL=project = PROJ AND status = "In Progress"}

Jira 图表：

{jirachart:type=pie|jql=project = PROJ|statType=statuses}

最近更新：

{recently-updated:spaces=@all|max=10}

按标签查看内容：

{contentbylabel:label=meeting-notes|maxResults=20}

协作宏

状态：

{status:colour=Green|title=Approved}

任务列表：

{tasks}
- [ ] Task 1
- [x] Task 2 completed
{tasks}

用户提及：

@username

日期：

{date:format=dd MMM yyyy}

页面布局与格式

双栏布局：

{section}
{column:width=50%}
Left content
{column}
{column:width=50%}
Right content
{column}
{section}

面板：

{panel:title=Panel Title|borderColor=#ccc}
Panel content
{panel}

代码块：

{code:javascript}
const example = "code here";
{code}

模板库

完整的模板库及其完整标记，请参阅 references/templates.md。主要模板概述如下。

模板	用途	关键章节
会议纪要	迭代/团队会议	议程、讨论、决策、待办事项（任务宏）
项目概览	项目启动与状态	快速信息面板、目标、干系人表格、里程碑（Jira 宏）、风险
决策日志	架构/战略决策	背景、考虑过的方案、决策、影响、后续步骤
迭代回顾	敏捷仪式文档	做得好的部分（信息）、做得不好的部分（警告）、待办事项（任务）、指标

空间权限

按空间类型划分的权限模式，请参阅 references/space-architecture-patterns.md。注意：空间权限需在 Confluence UI 中配置（Space settings > Permissions），无法通过 MCP 设置。

权限方案

公开空间：

• 所有用户：查看
• 团队成员：编辑、创建
• 空间管理员：管理

团队空间：

• 团队成员：查看、编辑、创建
• 团队负责人：管理
• 其他人：无访问权限

项目空间：

• 干系人：查看
• 项目团队：编辑、创建
• 项目经理：管理

内容治理

审查周期：

• 关键文档：每月
• 标准文档：每季度
• 归档文档：每年

归档策略：

• 将过时内容移至归档空间
• 使用“archived”标签并标注日期
• 保留 2 年后删除
• 保留审计记录

内容质量检查清单：

• 标题清晰、描述准确
• 已明确负责人/作者
• 可见的最后更新日期
• 已应用适当的标签
• 链接可用
• 格式一致
• 未暴露敏感数据

决策框架

何时升级至 Atlassian 管理员:

• 需要组织范围的模板
• 需要跨空间权限
• 模板(Blueprint)配置
• 全局自动化规则
• 空间导出/导入

何时与 Jira 专家协作:

• 嵌入 Jira 查询和图表
• 将页面链接到 Jira 工单
• 创建基于 Jira 的报告
• 将文档与工单同步

何时支持 Scrum Master:

• Sprint 文档模板
• 回顾会页面
• 团队工作协议
• 流程文档

何时支持高级 PM:

• 高管报告页面
• 项目组合文档
• 利益相关方沟通
• 战略规划文档

交接协议

来自高级 PM:

• 文档需求
• 空间结构需求
• 模板需求
• 知识管理策略

交给高级 PM:

• 文档覆盖率报告
• 内容使用分析
• 已识别的知识缺口
• 模板采用指标

来自 Scrum Master:

• Sprint 仪式模板
• 团队文档需求
• 会议纪要结构
• 回顾格式

交给 Scrum Master:

• 已配置的模板
• 团队文档空间
• 最佳实践培训
• 文档指南

与 Jira 专家协同:

• Jira 与 Confluence 链接
• 嵌入的 Jira 报告
• 工单与页面的关联
• 跨工具工作流

最佳实践

组织:

• 统一的命名规范
• 有意义的标签
• 合理的页面层级
• 关联页面相互链接
• 清晰的导航

维护:

• 定期进行内容审计
• 删除重复内容
• 更新过时信息
• 归档废弃内容
• 监控页面分析数据

分析与指标

使用指标:

• 每个空间的页面浏览量
• 最常访问的页面
• 搜索查询
• 贡献者活跃度
• 孤立页面

健康指标:

• 长期未更新的页面
• 没有负责人的页面
• 重复内容
• 失效链接
• 空白空间

相关技能

• Jira Expert（project-management/jira-expert/）— Jira 工单宏和链接是对 Confluence 文档的补充
• Atlassian Templates（project-management/atlassian-templates/）— 用于创建 Confluence 内容的模板模式