企业官网建设流程全解析

• AI 技能
• AI 插件

导读

本文以 Agentic Awesome Skills 仓库中的 bitbucket-automation 技能 为核心，系统讲解如何借助 Rube MCP（Composio 的 Bitbucket toolkit）将 Bitbucket Cloud 的日常开发运维——拉取请求（PR）创建与评审、仓库与工作区管理、分支操作、Issue 跟踪——全部交由 Agent 自动执行。读完本文，你将掌握一套完整的工具调用链、全部核心参数语义、BBQL 查询语法，以及避免踩坑的 ID 格式、分页、速率限制等实战要点，可直接在自己的 Agent 配置中落地这套自动化方案。

该技能以risk: critical级别收录于仓库，标记date_added: "2026-02-27"，说明其涉及删除仓库、删除 Issue 等高风险操作，使用前务必建立充分的安全确认机制。技能同时存在于 Claude 插件 与 通用插件 两个分发目录中，内容保持一致，可随插件一起安装使用。

一、技能定位与前置条件

该技能的能力边界非常明确：自动执行 Bitbucket 上的仓库管理、Pull Request 工作流、分支操作、Issue 跟踪与工作区管理。它本身不直接调用 Bitbucket API，而是通过 Rube MCP 这一中间层完成，因此在动手前必须满足三个前置条件：

• Rube MCP 必须已连接：确认环境中存在RUBE_SEARCH_TOOLS工具；
• 存在激活的 Bitbucket 连接：通过RUBE_MANAGE_CONNECTIONS以bitbuckettoolkit 建立连接；
• 始终先调用RUBE_SEARCH_TOOLS：Composio 的工具 schema 可能随版本更新，任何工作流开始前都应先拉取最新 schema，而不是依赖本文或任何文档中的历史参数记忆。

这一"先搜索工具、再调用工具"的原则，与仓库中技能索引体系强调的 schema 漂移防护思路一致——工具契约以运行时返回为准，文档中的参数说明是理解用途的辅助，最终以RUBE_SEARCH_TOOLS的实际返回为准。

二、建立 Bitbucket 连接

Rube MCP 的接入成本极低：只需在 MCP 客户端配置中添加https://rube.app/mcp作为 MCP 服务器端点，无需任何 API Key。

连接建立的标准步骤：

1. 验证 MCP 可用：确认RUBE_SEARCH_TOOLS能够正常响应；
2. 发起连接：调用RUBE_MANAGE_CONNECTIONS，指定 toolkit 为bitbucket；
3. 完成 OAuth 授权：若返回的连接状态不是ACTIVE，跟随返回的认证链接完成 Bitbucket OAuth 授权；
4. 确认状态：在运行任何工作流之前，确认连接状态显示为ACTIVE。

连接状态是所有后续操作的前提，跳过第 4 步直接执行工具调用，会得到一堆身份认证相关的报错，且难以定位根因。

三、核心工作流一：Pull Request 全生命周期管理

适用场景：用户需要创建、评审或查看 Pull Request。

工具调用序列

关键参数语义

• workspace：工作区 slug 或 UUID，所有操作必需；
• repo_slug：URL 友好的仓库名；
• source_branch：包含待合并变更的分支；
• destination_branch：目标分支，省略时默认使用仓库的 main 分支，注意仓库的默认分支不一定叫main；
• reviewers：评审人对象数组，元素含uuid字段；
• state：BITBUCKET_LIST_PULL_REQUESTS的过滤值，取OPEN、MERGED或DECLINED；
• max_chars：BITBUCKET_GET_PULL_REQUEST_DIFF的截断上限，用于防止超大 diff 撑爆上下文窗口。

实战陷阱

• reviewers期望的是带uuid键的对象数组，而不是用户名数组：[{"uuid": "{...}"}]；
• UUID 必须带花括号：{123e4567-e89b-12d3-a456-426614174000}；
• pull_request_id在 GET/DIFF 操作中是整数，但会随 PR 列表返回；
• 大型 diff 会迅速淹没上下文窗口，务必为GET_PULL_REQUEST_DIFF设置max_chars（例如 50000），这是评审大型 PR 时最容易犯、后果也最严重的失误。

四、核心工作流二：仓库与工作区管理

适用场景：列出、创建或删除仓库，或探索工作区结构。

工具调用序列

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不可逆，且不影响 fork 出来的仓库；
• BBQL 字符串值必须用双引号包裹：name~"my-repo"，而不是name~my-repo；
• repository不是合法的 BBQL 字段，应使用name；
• 默认分页只有 10 条结果，完整列表必须显式设置pagelen；
• CREATE_REPOSITORY默认创建私有仓库，公开仓库需显式设置is_private: false。

五、核心工作流三：Issue 全生命周期管理

适用场景：创建、更新、列出或评论仓库 Issue。

工具调用序列

1. BITBUCKET_LIST_ISSUES：按 state、priority、kind、assignee 等过滤列出 Issue（必需）；
2. BITBUCKET_CREATE_ISSUE：以标题、内容、优先级、类型创建 Issue（必需）；
3. BITBUCKET_UPDATE_ISSUE：修改 Issue 属性（state、priority、assignee 等）（可选）；
4. BITBUCKET_CREATE_ISSUE_COMMENT：向现有 Issue 添加 Markdown 评论（可选）；
5. BITBUCKET_DELETE_ISSUE：永久删除Issue（可选）。

关键参数语义

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

实战陷阱

• 仓库必须启用 Issue 跟踪器（has_issues: true），否则 API 调用直接失败——这是最容易忽略的隐性前置条件；
• CREATE_ISSUE用assignee（用户名字符串），而UPDATE_ISSUE用assignee_account_id（UUID），二者是完全不同的字段，混用必然失败；
• DELETE_ISSUE永久生效，无法撤销；
• state取值含空格："on hold"而非"on_hold"；
• LIST_ISSUES中按assignee过滤时使用的是 account ID 而非用户名；查询未分配 Issue 时使用字符串"null"。

六、核心工作流四：分支管理

适用场景：创建分支或探索分支结构。

工具调用序列

1. BITBUCKET_LIST_BRANCHES：列出分支，支持 BBQL 过滤与排序（必需）；
2. BITBUCKET_CREATE_BRANCH：从指定 commit 哈希创建新分支（必需）。

关键参数语义

• name：分支名，不带refs/heads/前缀，例如feature/new-login；
• target_hash：作为分支起点的完整 SHA1 commit 哈希，必须存在于仓库中；
• q：BBQL 过滤器，例如name~"feature/"、name="main"；
• sort：按name或-target.date（提交日期降序）排序；
• pagelen：每页 1–100 条，默认 10。

实战陷阱

• CREATE_BRANCH的target_hash必须是完整 commit 哈希，而不是分支名；
• 分支名不要带refs/heads/前缀；
• 分支名必须符合 Bitbucket 命名规范（字母数字及/、.、_、-）；
• BBQL 字符串值同样需要双引号：name~"feature/"而非name~feature/。

七、核心工作流五：PR 评审评论（含行内评论）

适用场景：为 Pull Request 添加评审评论，包括针对具体代码行的行内评论。

工具调用序列

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，用于对既有评论的线程化回复。

实战陷阱

• pull_request_id在CREATE_PULL_REQUEST_COMMENT中是字符串，但在GET_PULL_REQUEST中是整数，跨工具调用时注意类型转换；
• 行内评论至少需要inline.path；from/to是可选行号；
• parent_comment_id用于线程化回复，顶层评论应省略；
• 行内评论中的行号引用的是 diff 中的行号，不是源文件中的行号——这是代码评审自动化中最容易写错位置的一处。

八、贯穿所有工作流的通用模式

ID 解析原则

在执行任何操作之前，先把人类可读的名称解析为 ID：

• 工作区：BITBUCKET_LIST_WORKSPACES获取 workspace slug；
• 仓库：BITBUCKET_LIST_REPOSITORIES_IN_WORKSPACE配合q过滤器定位 repo slug；
• 分支：PR 创建前用BITBUCKET_LIST_BRANCHES确认分支存在；
• 成员：BITBUCKET_LIST_WORKSPACE_MEMBERS获取评审人指派所需的 UUID。

分页模式

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

• 使用page（从 1 开始）与pagelen（每页条数）参数；
• 默认页大小通常为 10；显式设置pagelen（PR 最大 50，其他最大 100）；
• 通过响应中的nextURL 或总条数判断是否还有更多页；
• 完整结果必须遍历所有页——遗漏翻页是列表类操作最常见的"静默截断"问题。

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 在部分工具中是整数、部分工具中是字符串；
• commit 哈希必须是完整 SHA1（40 个字符）。

参数怪癖

• assignee与assignee_account_id：CREATE_ISSUE用用户名，UPDATE_ISSUE用 UUID；
• Issue 的state值含空格："on hold"而非"on_hold"；
• destination_branch省略时默认取仓库 main 分支，并非字面意义上的main；
• BBQL 中repository不是合法字段，请用name。

速率限制

• Bitbucket Cloud API 有速率限制，大批量操作应加入延迟；
• 分页请求同样计入速率限制，尽量减少不必要的翻页请求。

破坏性操作

• BITBUCKET_DELETE_REPOSITORY不可逆且不删除 fork；
• BITBUCKET_DELETE_ISSUE永久生效、无法恢复；
• 执行删除类操作前必须与用户确认。这也正是该技能在仓库中被标记为risk: critical的原因——Agent 在自动执行这些调用前，必须建立明确的确认闸门。

十、工具速查表

十一、典型使用场景与边界

典型请求：用户要求自动化 Bitbucket 的仓库、PR、分支、Issue 与工作区管理。

推荐调用范式：接到任务后，先RUBE_SEARCH_TOOLS刷新 schema → 确认RUBE_MANAGE_CONNECTIONS中 Bitbucket 连接为 ACTIVE → 按上文各工作流的"前置 → 必需 → 可选"顺序逐步执行，并在每次列表操作后解析 ID、在每次删除操作前与用户确认。

使用边界与限制：

• 仅在任务明确匹配上述范围时使用该技能，不要用它处理 Bitbucket 之外的领域；
• 不要把工具输出当作环境特定验证、测试或专家评审的替代品——自动化操作落地前仍需人工把关；
• 当输入、权限、安全边界或成功标准缺失时，停下来向用户澄清，而不是猜测后继续执行。

结语

这套 Bitbucket 自动化方案的核心价值，在于把"先查 schema → 解析 ID → 按序调用 → 确认破坏性操作"这一套纪律固化成了可复用的工作流。无论你是要让 Agent 自动创建 PR 并贴上行内评审意见，还是批量维护 Issue 状态、梳理仓库结构，只要遵循本文梳理的工具调用链、参数语义与陷阱清单，并在RUBE_SEARCH_TOOLS的实时 schema 指导下执行，就能在避免上下文爆炸和误删风险的前提下，稳定地跑通 Bitbucket 的日常自动化。完整技能原文可随时查阅仓库中的 bitbucket-automation/SKILL.md（Claude 插件分发版）与 通用插件版。

• AI 技能
• AI 插件