bitbucket-automation

通过 Rube MCP 自动化 Bitbucket

通过 Composio 的 Bitbucket 工具包自动执行 Bitbucket 操作，包括仓库管理、拉取请求工作流、分支操作、问题跟踪和工作区管理。

前提条件

• 必须已连接 Rube MCP（可用 RUBE_SEARCH_TOOLS）
• 通过工具包为 bitbucket 的 RUBE_MANAGE_CONNECTIONS 建立有效的 Bitbucket 连接
• 务必先调用 RUBE_SEARCH_TOOLS，以获取当前工具架构

设置

使用现有且已获批准的 Rube 连接；仅配置端点并不能验证 Bitbucket 身份。只有在收到请求时，才遵循主机支持的设置／身份验证流程。

1. 确认 RUBE_SEARCH_TOOLS 有响应，以验证 Rube MCP 可用
2. 调用工具包为 bitbucket 的 RUBE_MANAGE_CONNECTIONS
3. 如果连接状态不是 ACTIVE，请通过返回的身份验证链接完成 Bitbucket OAuth
4. 在运行任何工作流前，确认连接状态显示为 ACTIVE

以下历史 slug 和默认值需要通过当前架构发现来核实。每次执行用户请求的变更前，都要验证工作区／仓库／分支／PR 及可见性。评论属于消息，必须获得明确的发布授权。如果 diff 因 max_chars 而被截断，则内容不完整：在声称已完成全面审查前，请获取所有受影响的文件／片段。写入结果不确定时，请先核实，再重试。

核心工作流

1. 管理拉取请求

适用场景：用户想要创建、审查或查看拉取请求

工具调用顺序：

1. BITBUCKET_LIST_WORKSPACES - 查找可访问的工作区［前置步骤］
2. BITBUCKET_LIST_REPOSITORIES_IN_WORKSPACE - 查找目标仓库［前置步骤］
3. BITBUCKET_LIST_BRANCHES - 验证源分支和目标分支是否存在［前置步骤］
4. BITBUCKET_CREATE_PULL_REQUEST - 使用标题、源分支及可选审查者创建新的 PR［必需］
5. BITBUCKET_LIST_PULL_REQUESTS - 按状态（OPEN、MERGED、DECLINED）筛选并列出 PR［可选］
6. BITBUCKET_GET_PULL_REQUEST - 按 ID 获取特定 PR 的完整详细信息［可选］
7. BITBUCKET_GET_PULL_REQUEST_DIFF - 获取用于代码审查的统一 diff［可选］
8. BITBUCKET_GET_PULL_REQUEST_DIFFSTAT - 获取包含新增／删除行数的变更文件列表［可选］

关键参数：

• workspace：工作区 slug 或 UUID（所有操作必需）
• repo_slug：适用于 URL 的仓库名称
• source_branch：包含待合并变更的分支
• destination_branch：目标分支（省略时默认为仓库主分支）
• reviewers：包含 uuid 字段、用于指定审查者的对象列表
• state：用于筛选 LIST_PULL_REQUESTS 的条件 - OPEN、MERGED 或 DECLINED
• max_chars：GET_PULL_REQUEST_DIFF 的截断上限，用于处理大型 diff

注意事项：

• reviewers 需要包含 uuid 键的对象数组，而不是用户名：[{"uuid": "{...}"}]
• UUID 格式必须包含花括号：{123e4567-e89b-12d3-a456-426614174000}
• 如果省略 destination_branch，则默认为仓库主分支，该分支不一定是 main
• pull_request_id 在 GET／DIFF 操作中是整数，但会作为 PR 列表的一部分返回
• 大型 diff 可能超出上下文限制；调用 GET_PULL_REQUEST_DIFF 时务必设置 max_chars（例如 50000）

2. 管理代码库和工作区

使用场景：用户想要列出、创建或删除代码库，或浏览工作区

工具调用顺序：

1. BITBUCKET_LIST_WORKSPACES - 列出所有可访问的工作区 [必需]
2. BITBUCKET_LIST_REPOSITORIES_IN_WORKSPACE - 列出代码库，可选使用 BBQL 过滤 [必需]
3. BITBUCKET_CREATE_REPOSITORY - 创建代码库，并设置语言、隐私和项目 [可选]
4. BITBUCKET_DELETE_REPOSITORY - 永久删除代码库（不可撤销）[可选]
5. BITBUCKET_LIST_WORKSPACE_MEMBERS - 列出成员，以便分配审阅者或检查访问权限 [可选]

关键参数：

• workspace：工作区 slug（通过 LIST_WORKSPACES 查找）
• repo_slug：用于创建或删除的 URL 友好名称
• q：BBQL 查询过滤条件（例如，name~"api"、project.key="PROJ"、is_private=true）
• role：按用户角色过滤代码库：member、contributor、admin、owner
• sort：排序字段；可加 - 前缀表示降序（例如，-updated_on）
• is_private：用于设置代码库可见性的布尔值（默认为 true）
• project_key：Bitbucket 项目键；省略则使用工作区中最早创建的项目

注意事项：

• BITBUCKET_DELETE_REPOSITORY 不可撤销，且不会影响分支
• BBQL 字符串值必须用双引号括起来：name~"my-repo"，而不是 name~my-repo
• repository 不是有效的 BBQL 字段；请改用 name
• 默认分页大小可能较小；仅增大 pagelen 无法完成列表获取，需遍历所有受支持的后续页面
• CREATE_REPOSITORY 默认创建私有代码库；如需公开代码库，请设置 is_private: false

3. 管理问题

使用场景：用户想要创建、更新、列出代码库问题，或对问题发表评论

工具调用顺序：

1. BITBUCKET_LIST_ISSUES - 列出问题，可选按状态、优先级、类型和受理人过滤 [必需]
2. BITBUCKET_CREATE_ISSUE - 创建问题，并设置标题、内容、优先级和类型 [必需]
3. BITBUCKET_UPDATE_ISSUE - 修改问题属性（状态、优先级、受理人等）[可选]
4. BITBUCKET_CREATE_ISSUE_COMMENT - 为现有问题添加 Markdown 评论 [可选]
5. BITBUCKET_DELETE_ISSUE - 永久删除问题 [可选]

关键参数：

• issue_id：问题的字符串标识符
• title、content：创建时必填
• kind：bug、enhancement、proposal 或 task
• priority：trivial、minor、major、critical 或 blocker
• state：new、open、resolved、on hold、invalid、duplicate、wontfix、closed
• assignee：CREATE 使用 Bitbucket 用户名；UPDATE 使用 assignee_account_id（UUID）
• due_on：ISO 8601 格式的日期字符串

注意事项：

• 代码库必须启用问题跟踪器（has_issues: true），否则 API 调用会失败
• CREATE_ISSUE 使用 assignee（用户名字符串），而 UPDATE_ISSUE 使用 assignee_account_id（UUID），两者是不同的字段
• DELETE_ISSUE 会永久删除问题，无法撤销
• state 的取值可能包含空格：应使用 "on hold"，而不是 "on_hold"
• 在 LIST_ISSUES 中按 assignee 过滤时使用的是账户 ID，而不是用户名；未分配时请使用字符串 "null"

4. 管理分支

适用场景：用户希望创建分支或查看分支结构

工具调用顺序：

1. BITBUCKET_LIST_BRANCHES - 列出分支，可选使用 BBQL 筛选和排序 [必需]
2. BITBUCKET_CREATE_BRANCH - 从指定提交哈希创建新分支 [必需]

关键参数：

• name：不带 refs/heads/ 前缀的分支名称（例如，feature/new-login）
• target_hash：要从其创建分支的完整 SHA1 提交哈希（必须存在于仓库中）
• q：BBQL 筛选条件（例如，name~"feature/"、name="main"）
• sort：按 name 或 -target.date 排序（按提交日期降序）
• pagelen：每页 1-100 条结果（默认为 10）

注意事项：

• CREATE_BRANCH 的 target_hash 必须是完整提交哈希，而非分支名称
• 分支名称中不要包含 refs/heads/ 前缀
• 分支名称必须遵循 Bitbucket 命名规范（字母数字字符、/、.、_、-）
• BBQL 字符串值需要使用双引号：name~"feature/"，而不是 name~feature/

5. 带评论审查拉取请求

适用场景：用户希望为拉取请求添加审查评论，包括代码行内评论

工具调用顺序：

1. BITBUCKET_GET_PULL_REQUEST - 获取 PR 详情并确认其存在 [前置条件]
2. BITBUCKET_GET_PULL_REQUEST_DIFF - 审查实际代码更改 [前置条件]
3. BITBUCKET_GET_PULL_REQUEST_DIFFSTAT - 获取已更改文件列表 [可选]
4. BITBUCKET_CREATE_PULL_REQUEST_COMMENT - 发布审查评论 [必需]

关键参数：

• pull_request_id：PR 的字符串 ID
• content_raw：采用 Markdown 格式的评论文本
• content_markup：默认为 markdown；也支持 plaintext
• inline：包含 path、from、to 的对象，用于代码行内评论
• parent_comment_id：用于回复现有评论的整数 ID，可创建评论串

注意事项：

• CREATE_PULL_REQUEST_COMMENT 中的 pull_request_id 是字符串，而 GET_PULL_REQUEST 中的是整数
• 行内评论至少需要 inline.path；from/to 是可选的行号
• parent_comment_id 用于创建评论串回复；顶级评论请省略此参数
• 行内评论中的行号对应的是差异内容，而非源文件

常见模式

ID 解析

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

• 工作区：使用 BITBUCKET_LIST_WORKSPACES 获取工作区 slug
• 仓库：使用带 q 筛选条件的 BITBUCKET_LIST_REPOSITORIES_IN_WORKSPACE 查找仓库 slug
• 分支：创建 PR 前使用 BITBUCKET_LIST_BRANCHES 确认分支存在
• 成员：使用 BITBUCKET_LIST_WORKSPACE_MEMBERS 获取用于分配审阅者的 UUID

分页

Bitbucket 使用基于页码的分页（而非基于游标的分页）：

• 使用 page（从 1 开始）和 pagelen（每页条目数）参数
• 默认页大小通常为 10；请明确设置 pagelen（PR 最多为 50，其他最多为 100）
• 检查响应中的 next URL 或总数，以确定是否还有更多页面
• 始终遍历所有页面以获取完整结果

BBQL 筛选

列表端点支持 Bitbucket Query Language：

• 字符串值必须使用双引号：name~"pattern"
• 运算符：=（精确匹配）、~（包含）、!=（不等于）、>、>=、<、<=
• 使用 AND / OR 组合条件：name~"api" AND is_private=true

已知注意事项

ID 格式

• 工作区：slug 字符串（例如，my-workspace）或带大括号的 UUID（{uuid}）
• 审阅者 UUID 必须包含大括号：{123e4567-e89b-12d3-a456-426614174000}
• Issue ID 是字符串；在某些工具中，PR ID 是整数，在其他工具中则是字符串
• 提交哈希必须是完整 SHA1（40 个字符）

参数差异

• assignee 与 assignee_account_id：CREATE_ISSUE 使用用户名，UPDATE_ISSUE 使用 UUID
• Issue 的 state 值包含空格：使用 "on hold"，而不是 "on_hold"
• 省略 destination_branch 时，默认使用仓库的主分支，而不是字面上的 main
• BBQL 中的 repository 不是有效字段，请使用 name

速率限制

• Bitbucket Cloud API 有速率限制；大批量操作应加入延迟
• 分页请求会占用速率限制额度；应尽量减少不必要的翻页请求

破坏性操作

• BITBUCKET_DELETE_REPOSITORY 不可逆，且不会删除 fork
• BITBUCKET_DELETE_ISSUE 是永久性的，无法恢复
• 执行删除操作前务必与用户确认

快速参考

任务	工具 Slug	关键参数
列出工作区	BITBUCKET_LIST_WORKSPACES	q、sort
列出仓库	BITBUCKET_LIST_REPOSITORIES_IN_WORKSPACE	workspace、q、role
创建仓库	BITBUCKET_CREATE_REPOSITORY	workspace、repo_slug、is_private
删除仓库	BITBUCKET_DELETE_REPOSITORY	workspace、repo_slug
列出分支	BITBUCKET_LIST_BRANCHES	workspace、repo_slug、q
创建分支	BITBUCKET_CREATE_BRANCH	workspace、repo_slug、name、target_hash
列出 PR	BITBUCKET_LIST_PULL_REQUESTS	workspace、repo_slug、state
创建 PR	BITBUCKET_CREATE_PULL_REQUEST	workspace、repo_slug、title、source_branch
获取 PR 详情	BITBUCKET_GET_PULL_REQUEST	workspace、repo_slug、pull_request_id
获取 PR diff	BITBUCKET_GET_PULL_REQUEST_DIFF	workspace、repo_slug、pull_request_id、max_chars
获取 PR diffstat	BITBUCKET_GET_PULL_REQUEST_DIFFSTAT	workspace、repo_slug、pull_request_id
在 PR 上评论	BITBUCKET_CREATE_PULL_REQUEST_COMMENT	workspace、repo_slug、pull_request_id、content_raw
列出 issue	BITBUCKET_LIST_ISSUES	workspace、repo_slug、state、priority
创建 issue	BITBUCKET_CREATE_ISSUE	workspace、repo_slug、title、content
更新 issue	BITBUCKET_UPDATE_ISSUE	workspace、repo_slug、issue_id
在 issue 上评论	BITBUCKET_CREATE_ISSUE_COMMENT	workspace、repo_slug、issue_id、content
删除 issue	BITBUCKET_DELETE_ISSUE	workspace、repo_slug、issue_id
列出成员	BITBUCKET_LIST_WORKSPACE_MEMBERS	workspace

何时使用

本技能适用于执行概述中描述的工作流或操作。

示例

用户请求：

通过 Rube MCP（Composio）自动化管理 Bitbucket 仓库、pull request、分支、issue 和工作区。

限制

• 仅当任务与上述范围明确匹配时才使用本技能。
• 不要将输出视为针对特定环境的验证、测试或专家评审的替代品。
• 如果缺少必需的输入、权限、安全边界或成功标准，请停下来并请求澄清。