confluence-automation

通过 Rube MCP 自动化 Confluence

通过 Composio 的 Confluence 工具包自动执行 Confluence 操作，包括创建和更新页面、使用 CQL 搜索内容、管理空间、添加标签，以及浏览页面层级。

工具包文档：composio.dev/toolkits/confluence

前置条件

• 必须已连接 Rube MCP（可使用 RUBE_SEARCH_TOOLS）
• 通过 RUBE_MANAGE_CONNECTIONS 建立有效的 Confluence 连接，工具包为 confluence
• 始终先调用 RUBE_SEARCH_TOOLS，以获取最新的工具架构

设置

获取 Rube MCP：在客户端配置中将 https://rube.app/mcp 添加为 MCP 服务。无需 API 密钥，只需添加该端点即可使用。

1. 确认 RUBE_SEARCH_TOOLS 能够响应，以验证 Rube MCP 已可用
2. 使用工具包 confluence 调用 RUBE_MANAGE_CONNECTIONS
3. 如果连接状态不是 ACTIVE，请使用返回的授权链接完成 Confluence OAuth
4. 在运行任何工作流之前，确认连接状态显示为 ACTIVE

核心工作流

1. 创建和更新页面

适用场景：用户想要创建新文档或更新现有 Confluence 页面

工具调用顺序：

1. CONFLUENCE_GET_SPACES - 列出空间以查找目标空间 ID [前置条件]
2. CONFLUENCE_SEARCH_CONTENT - 查找现有页面，以避免重复或定位父页面 [可选]
3. CONFLUENCE_GET_PAGE_BY_ID - 更新前获取当前页面内容和版本号 [更新的前置条件]
4. CONFLUENCE_CREATE_PAGE - 在空间中创建新页面 [创建所需]
5. CONFLUENCE_UPDATE_PAGE - 使用新内容和递增后的版本号更新现有页面 [更新所需]
6. CONFLUENCE_ADD_CONTENT_LABEL - 创建页面后为其添加标签 [可选]

关键参数：

• spaceId：空间 ID 或键（例如 "DOCS"、"12345678"）-- 空间键会自动转换为 ID
• title：页面标题（在同一空间内必须唯一）
• parentId：用于创建子页面的父页面 ID；省略时，页面将置于空间首页下
• body.storage.value：采用 Confluence 存储格式的 HTML/XHTML 内容
• body.storage.representation：创建操作必须为 "storage"
• version.number：更新时，必须设为当前版本号 + 1
• version.message：可选的更改说明

注意事项：

• Confluence 要求每个空间内的页面标题唯一；创建标题重复的页面会失败
• UPDATE_PAGE 要求将 version.number 设为当前版本号 + 1；务必先使用 GET_PAGE_BY_ID 获取当前版本号
• 内容必须采用 Confluence 存储格式（XHTML），不能使用纯文本或 Markdown
• CREATE_PAGE 使用 body.storage.value，而 UPDATE_PAGE 使用 body.value 和 body.representation
• GET_PAGE_BY_ID 要求使用数字型长 ID，而不是 UUID 或字符串

2. 搜索内容

适用场景：用户想在 Confluence 中查找页面、博客文章或内容

工具调用顺序：

1. CONFLUENCE_SEARCH_CONTENT - 使用智能相关性排序进行关键词搜索 [必需]
2. CONFLUENCE_CQL_SEARCH - 使用 Confluence 查询语言进行高级搜索 [替代方案]
3. CONFLUENCE_GET_PAGE_BY_ID - 获取选定搜索结果的完整内容 [可选]
4. CONFLUENCE_GET_PAGES - 当搜索相关性较弱时，按日期浏览页面 [备用方案]

SEARCH_CONTENT 的关键参数：

• query：与页面标题匹配的搜索文本，并进行智能排序
• spaceKey：将搜索范围限定在特定空间
• limit：结果数量上限（默认 25，最大 250）
• start：分页偏移量（从 0 开始）

CQL_SEARCH 的关键参数：

• cql：CQL 查询字符串（例如，text ~ "API docs" AND space = DOCS AND type = page）
• expand：以逗号分隔的属性（例如，content.space、content.body.storage）
• excerpt：highlight、indexed 或 none
• limit：结果数量上限（最大 250；使用正文扩展时，缩减至 25-50）

CQL 运算符和字段：

• 字段：text、title、label、space、type、creator、lastModified、created、ancestor
• 运算符：=、!=、~（包含）、!~、>、<、>=、<=、IN、NOT IN
• 函数：currentUser()、now("-7d")、now("-30d")
• 示例：title ~ "meeting" AND lastModified > now("-7d") ORDER BY lastModified DESC

注意事项：

• CONFLUENCE_SEARCH_CONTENT 最多获取 300 个页面并在客户端进行筛选——这并非真正的全文搜索
• CONFLUENCE_CQL_SEARCH 才是真正的全文搜索；搜索正文内容时使用 text ~ "term"
• 可能会遇到 HTTP 429 速率限制；请将请求频率控制在每秒约 2 次，并采用退避策略
• 在 CQL_SEARCH 中使用正文扩展可能会将结果数量上限降至 25-50
• 搜索索引不会立即更新；新创建的页面可能暂时不会显示

3. 管理空间

适用场景：用户想要列出、创建或查看 Confluence 空间

工具调用顺序：

1. CONFLUENCE_GET_SPACES - 列出所有空间，可选择性地进行筛选 [必需]
2. CONFLUENCE_GET_SPACE_BY_ID - 获取特定空间的详细元数据 [可选]
3. CONFLUENCE_CREATE_SPACE - 使用键和名称创建新空间 [可选]
4. CONFLUENCE_GET_SPACE_PROPERTIES - 获取以空间属性形式存储的自定义元数据 [可选]
5. CONFLUENCE_GET_SPACE_CONTENTS - 列出空间中的页面、博客文章或附件 [可选]
6. CONFLUENCE_GET_LABELS_FOR_SPACE - 列出空间上的标签 [可选]

关键参数：

• key：空间键——仅限字母数字字符，不得包含下划线或连字符（例如，DOCS、PROJECT1）
• name：便于识别的空间名称
• type：global 或 personal
• status：current（活跃）或 archived
• spaceKey：对于 GET_SPACE_CONTENTS，按空间键筛选
• id：GET_SPACE_BY_ID 使用的数字空间 ID（不是空间键）

注意事项：

• 空间键只能包含字母数字字符（不得包含下划线、连字符或特殊字符）
• GET_SPACE_BY_ID 需要数字空间 ID，而非空间键；使用 GET_SPACES 查找数字 ID
• 可点击的空间 URL 可能需要组合生成：将 _links.webui（相对路径）与 _links.base 拼接
• 默认分页大小为 25；请显式设置 limit（空间列表的最大值为 200）

4. 浏览页面层级和标签

适用场景：用户想要浏览页面树、子页面、祖先页面或管理标签

工具调用顺序：

1. CONFLUENCE_SEARCH_CONTENT - 查找目标页面 ID【前置条件】
2. CONFLUENCE_GET_CHILD_PAGES - 列出父页面的直接子页面【必需】
3. CONFLUENCE_GET_PAGE_ANCESTORS - 获取页面的完整祖先链【可选】
4. CONFLUENCE_GET_LABELS_FOR_PAGE - 列出特定页面上的标签【可选】
5. CONFLUENCE_ADD_CONTENT_LABEL - 为页面添加标签【可选】
6. CONFLUENCE_GET_LABELS_FOR_SPACE_CONTENT - 列出空间内所有内容的标签【可选】
7. CONFLUENCE_GET_PAGE_VERSIONS - 审查页面的编辑历史【可选】

关键参数：

• id：用于子页面、祖先页面、标签和版本的页面 ID
• cursor：GET_CHILD_PAGES 的不透明分页游标（来自 _links.next）
• limit：每页项目数（子页面最多 250 项）
• sort：子页面排序选项：id、-id、created-date、-created-date、modified-date、-modified-date、child-position、-child-position

注意事项：

• GET_CHILD_PAGES 仅返回直接子页面，不返回嵌套的后代页面；要获取完整页面树，需递归调用
• GET_CHILD_PAGES 使用基于游标的分页（而非 start/limit）
• 将页面用作父页面前，请通过搜索结果确认页面 ID 正确；搜索可能返回标题相似的页面
• GET_PAGE_VERSIONS 需要页面 ID，而非版本号

常见模式

ID 解析

操作前，始终先将人类可读的名称解析为 ID：

• 空间 key -> 空间 ID：使用 CONFLUENCE_GET_SPACES 并通过 spaceKey 筛选；或者 CREATE_PAGE 可直接接受空间 key
• 页面标题 -> 页面 ID：使用 CONFLUENCE_SEARCH_CONTENT 和 query 参数，然后提取页面 ID
• 从 URL 获取空间 ID：从 Confluence URL 中提取数字 ID，或使用 GET_SPACES

分页

Confluence 使用两种分页方式：

• 基于偏移量（大多数端点）：start（从 0 开始的偏移量）+ limit（每页大小）。将 start 增加 limit，直到返回的结果数少于 limit。
• 基于游标（GET_CHILD_PAGES、GET_PAGES）：使用响应中 _links.next 的 cursor。持续获取，直到响应中不再有 next 链接。

内容格式

• 页面使用 Confluence 存储格式（XHTML），而非 Markdown
• 基本元素：<p>、<h1>-<h6>、<strong>、<em>、<code>、<ul>、<ol>、<li>
• 表格：<table><tbody><tr><th> / <td> 结构
• 宏：代码块等内容使用 <ac:structured-macro ac:name="code">
• 始终使用正确的 XHTML 标签包裹内容

已知注意事项

ID 格式

• 空间 ID 为数字（例如，557060）；空间 key 为短字符串（例如，DOCS）
• GET_PAGE_BY_ID 使用较长的数字页面 ID；某些工具接受 UUID 格式
• GET_SPACE_BY_ID 需要数字 ID，而非空间 key
• GET_PAGE_BY_ID 接受整数，而非字符串

速率限制

• 搜索端点可能返回 HTTP 429；请遵循 Retry-After 标头
• 将请求频率限制在约每秒 2 次，并使用指数退避和随机抖动
• 在 CQL_SEARCH 中扩展正文内容会将结果上限降至 25-50

内容格式

• 内容必须采用 Confluence 存储格式（XHTML），而非 Markdown 或纯文本
• XHTML 无效会导致页面创建或更新失败
• CREATE_PAGE 将正文嵌套在 body.storage.value 下；UPDATE_PAGE 使用 body.value + body.representation

版本冲突

• 更新需要精确的下一版本号（当前版本 + 1）
• 并发编辑可能导致版本冲突；更新前务必立即获取当前版本
• 更新时更改的标题在该空间内仍必须唯一

快速参考

任务	工具标识	关键参数
列出空间	CONFLUENCE_GET_SPACES	type、status、limit
按 ID 获取空间	CONFLUENCE_GET_SPACE_BY_ID	id
创建空间	CONFLUENCE_CREATE_SPACE	key、name、type
空间内容	CONFLUENCE_GET_SPACE_CONTENTS	spaceKey、type、status
空间属性	CONFLUENCE_GET_SPACE_PROPERTIES	id、key
搜索内容	CONFLUENCE_SEARCH_CONTENT	query、spaceKey、limit
CQL 搜索	CONFLUENCE_CQL_SEARCH	cql、expand、limit
列出页面	CONFLUENCE_GET_PAGES	spaceId、sort、limit
按 ID 获取页面	CONFLUENCE_GET_PAGE_BY_ID	id（整数）
创建页面	CONFLUENCE_CREATE_PAGE	title、spaceId、body
更新页面	CONFLUENCE_UPDATE_PAGE	id、title、body、version
删除页面	CONFLUENCE_DELETE_PAGE	id
子页面	CONFLUENCE_GET_CHILD_PAGES	id、limit、sort
页面祖先	CONFLUENCE_GET_PAGE_ANCESTORS	id
页面标签	CONFLUENCE_GET_LABELS_FOR_PAGE	id
添加标签	CONFLUENCE_ADD_CONTENT_LABEL	内容 ID、标签
页面版本	CONFLUENCE_GET_PAGE_VERSIONS	id
空间标签	CONFLUENCE_GET_LABELS_FOR_SPACE	空间 ID

---

由 Composio 提供支持