Bitbucket DevOps 技能

这个技能提供了使用直接 Node.js API 调用的全面 Bitbucket DevOps 自动化，通过 Bash 工具实现。监控流水线状态，分析失败原因，下载日志，并触发构建。当用户要求检查流水线状态、查找失败的流水线、下载日志、触发构建或调试流水线失败时，请使用这项技能。不需要 MCP 批准提示 - 使用带有 node 命令的 Bash 工具。

关键优势： 使用直接 Node.js 调用（自动批准）而不是 MCP 工具，消除了 GitHub Issue #10801 中提到的批准提示问题。

⚠️ 强制：如何处理用户请求

你必须遵循这个三重后备策略来执行所有 Bitbucket 操作。这是必需的，不是可选的。

关键规则：

• 不要为 Bitbucket API 调用创建新的 .js 文件
• 不要使用 node -e 进行内联 Bitbucket API 操作
• 只使用下面列出的预构建 CLI 工具
• 始终从第一层开始，如果需要，退回到第二层，仅作为最后手段使用第三层

第一层：高级辅助函数（必需的第一步）

你必须首先检查这些助手。

这些解决了单一命令中的常见工作流程。如果用户的请求与这些模式中的任何一个匹配，你必须使用相应的助手。

位置： ~/.claude/skills/bitbucket-devops/lib/helpers.js

可用命令：

• get-latest-failed <workspace> <repo> - 获取最近的失败流水线
• get-latest <workspace> <repo> - 获取最近的流水线（任何状态）
• get-by-number <workspace> <repo> <build-number> - 通过构建编号查找流水线
• get-failed-steps <workspace> <repo> <pipeline-uuid> - 获取所有失败的步骤
• download-failed-logs <workspace> <repo> <pipeline-uuid> <build-number> - 下载所有失败步骤的日志
• get-info <workspace> <repo> <pipeline-uuid> - 获取格式化的流水线 + 步骤信息

必须用于： “最新的失败构建”, “下载流水线 #123 的日志”, “这个构建中什么失败了”, “通过编号获取流水线”

用法：

node ~/.claude/skills/bitbucket-devops/lib/helpers.js <command> <args>

示例：

# 用户："最新的失败流水线是什么？"
# 你必须使用：
node ~/.claude/skills/bitbucket-devops/lib/helpers.js get-latest-failed "workspace" "repo"

# 不要创建新脚本
# 不要使用 node -e
# 不要编写自定义 API 调用

第二层：低级 CLI 命令（如果第一层不能解决）

如果没有任何第一层助手匹配用户的请求，只使用第二层。

特定操作的直接 API 包装器。如果第一层助手没有涵盖的操作，你必须使用这些。

位置： ~/.claude/skills/bitbucket-devops/bitbucket-mcp/dist/index-cli.js

关键命令（见 docs/REFERENCE.md 以获取完整列表）：

流水线操作：

• list-pipelines <workspace> <repo> [limit]
• get-pipeline <workspace> <repo> <pipeline-uuid>
• get-pipeline-steps <workspace> <repo> <pipeline-uuid>
• get-step-logs <workspace> <repo> <pipeline-uuid> <step-uuid>
• run-pipeline <workspace> <repo> <branch> [pipeline-name] [variables-json]
• stop-pipeline <workspace> <repo> <pipeline-uuid>

拉取请求操作：

• list-prs <workspace> <repo> [state] [limit]
• get-pr <workspace> <repo> <pr_id>
• approve-pr <workspace> <repo> <pr_id>
• merge-pr <workspace> <repo> <pr_id> [message] [strategy]
• decline-pr <workspace> <repo> <pr_id> [message]

仓库操作：

• get-branching-model <workspace> <repo>
• list-repositories <workspace>

用法：

node ~/.claude/skills/bitbucket-devops/bitbucket-mcp/dist/index-cli.js <command> <args>

你可以链式多个第二层命令 - 见 docs/PATTERNS.md 以获取示例。

第三层：直接 Bitbucket API 调用（仅当第一层和第二层失败时）

如果第一层和第二层都不能解决请求，只使用第三层。这应该是罕见的。

在使用第三层之前，你必须：

1. 验证没有第一层助手存在
2. 验证没有第二层 CLI 命令存在
3. 验证没有第一层 + 第二层的组合可以解决它

文档： ~/.claude/skills/bitbucket-devops/bitbucket-mcp/docs/

• api-overview.md - 认证，基础 URL，速率限制
• pipelines-api.md - 完整的流水线 API 参考
• repositories-api.md - 仓库操作
• pull-requests-api.md - PR 操作（未来）

---

必需的决策过程

在执行任何 Bitbucket 操作之前，你必须：

1. 检查第一层助手 - 回顾上面的 6 个助手。有一个能解决这个问题吗？

   • 是 → 立即使用 node ~/.claude/skills/bitbucket-devops/lib/helpers.js <command>
   • 否 → 继续第二步

2. 检查第二层 CLI - 回顾上面的 CLI 命令。一个或多个能解决这个问题吗？

   • 是 → 使用它们与 node ~/.claude/skills/bitbucket-devops/bitbucket-mcp/dist/index-cli.js <command>
   • 否 → 继续第三步

3. 检查第三层文档 - 阅读 API 文档。需要直接 API 调用吗？

   • 是 → 阅读文档，使用 curl 带凭据
   • 否 → 向用户请求澄清

永远不要跳过这个过程。永远不要创建新的 .js 文件。始终使用预构建的工具。

---

已知限制

流水线工件不能通过 API 下载

重要： Bitbucket Cloud 不提供下载流水线工件的 API。

如果用户要求下载构建工件：

1. 告知他们通过 API 下载工件是不可能的
2. 引导他们到 Bitbucket Web UI：
   • 仓库 → 流水线 → 构建 # → 步骤 → 工件部分 → 下载按钮
3. 注意：工件在 14 天后自动过期

提示： 对于程序化的工件访问，考虑在流水线期间上传到 S3/Azure Blob Storage。

不要： 寻找未记录的端点 - 这已经经过彻底研究，没有 API 存在。

---

DevOps REPL 优势

传统的流水线调试是缓慢的：推送代码 → 等待 → 失败 → 调查日志 → 修复 → 重复（每个周期数小时）。

这项技能使得 DevOps REPL 体验成为可能：Claude 实时观察流水线，立即分析失败，建议精确的修复措施，并与你迭代直到构建通过 - 将调试周期从数小时减少到数分钟。

循环：

1. 读取：监控流水线执行并捕获失败
2. 评估：AI 分析日志并确定根本原因
3. 打印：Claude 展示发现并建议修复措施
4. 循环：应用修复，触发构建，重复直到绿色 ✅

这将 DevOps 从缓慢的批量处理转变为交互式、对话式开发。

---

先决条件

这项技能使用 Bash 工具（在 Claude Code 中自动批准）来运行 Node.js 命令。所需：

• Node.js (v18+)
• Git（用于子模块管理）

注意： 不需要 MCP 服务器 - bitbucket-mcp 用作库通过 git 子模块。

---

配置

技能目录位于：~/.claude/skills/bitbucket-devops/

凭据按优先级加载（首先找到的获胜）：

1. 项目级别：./credentials.json 或 ./.bitbucket-credentials（当前工作目录）
2. 用户级别：~/.bitbucket-credentials（主目录）
3. 技能级别：~/.claude/skills/bitbucket-devops/credentials.json

凭据格式

重要： 不同操作的不同凭据

{
  "url": "https://api.bitbucket.org/2.0",
  "workspace": "your-workspace-name",
  "user_email": "your-email@example.com",
  "username": "your-workspace-name",
  "password": "your-bitbucket-app-password"
}

字段解释：

• user_email：你的 Bitbucket 账户电子邮件（用于 API 认证） - 必须包含 @
• username：你的 Bitbucket 工作区 slug（用于 git 操作） - 不得包含 @
• password：来自 https://bitbucket.org/account/settings/app-passwords/ 的应用密码
  • 所需权限：Repositories: Read, Pipelines: Read

见 docs/GIT_OPERATIONS.md 了解 API vs git 操作的凭据要求详情。

---

快速开始：基本模式

模式 0：始终首先检测工作区和仓库

在任何流水线操作之前，确定工作区和仓库。

从 git 远程自动检测：

git_url=$(git config --get remote.origin.url 2>/dev/null)
if [[ "$git_url" =~ bitbucket.org[:/]([^/]+)/([^/.]+) ]]; then
  WORKSPACE="${BASH_REMATCH[1]}"
  REPO="${BASH_REMATCH[2]}"
  echo "Detected: $WORKSPACE/$REPO"
fi

或询问用户： “你的 Bitbucket 工作区和仓库名称是什么？”

重要： 在命令中使用实际值。永远不要使用字面字符串 "workspace" 或 "repo"。

模式 1：查找最新的失败流水线

node ~/.claude/skills/bitbucket-devops/lib/helpers.js \
  get-latest-failed "workspace" "repo"

向用户展示：

最新的失败流水线：
- 流水线 #123
- 分支：main
- 提交：abc123d - "Fix bug in deployment"
- 状态：FAILED

模式 2：下载失败流水线的日志

# 第 1 步：通过构建编号获取流水线
node ~/.claude/skills/bitbucket-devops/lib/helpers.js \
  get-by-number "workspace" "repo" 123

# 第 2 步：下载所有失败步骤的日志
node ~/.claude/skills/bitbucket-devops/lib/helpers.js \
  download-failed-logs "workspace" "repo" "{pipeline-uuid}" 123

向用户展示：

下载了 2 个失败步骤的日志：

1. Deploy
   - 保存到：.pipeline-logs/pipeline-123-Deploy.log
   - 大小：12.4 KB

2. Integration_Tests
   - 保存到：.pipeline-logs/pipeline-123-Integration_Tests.log
   - 大小：45.2 KB

重要： 在显示之前检查日志文件大小。如果 > 50KB，只显示摘要：

tail -n 100 .pipeline-logs/pipeline-123-Deploy.log
grep -i "error\|failed\|exception" .pipeline-logs/pipeline-123-Deploy.log

模式 3：DevOps REPL 循环（完整的调试工作流程）

用户：“修复失败的构建”

1. 读取 - 找到并分析失败：

node ~/.claude/skills/bitbucket-devops/lib/helpers.js get-latest-failed "workspace" "repo"
node ~/.claude/skills/bitbucket-devops/lib/helpers.js get-failed-steps "workspace" "repo" "{uuid}"
node ~/.claude/skills/bitbucket-devops/lib/helpers.js download-failed-logs "workspace" "repo" "{uuid}" 123

2. 评估 - 分析日志：

grep -i "error\|failed\|exception\|fatal" .pipeline-logs/*.log
grep -i -A 5 -B 5 "error" .pipeline-logs/pipeline-*.log

3. 打印 - 建议修复：

在流水线 #123 中找到问题：

错误类型：TypeScript 编译错误
位置：src/auth/service.ts:42
错误：属性 'userId' 不存在于类型 'User' 上

根本原因：用户接口已更新，但此文件没有

建议修复：
将第 42 行从：
  return user.userId
更改为：
  return user.id

我应该应用这个修复吗？

4. 循环 - 应用修复并重新测试：

# 使用编辑工具应用修复
# 提交更改
git add src/auth/service.ts
git commit -m "Fix: Update User property reference from userId to id"

# 触发新的流水线运行
node ~/.claude/skills/bitbucket-devops/bitbucket-mcp/dist/index-cli.js \
  run-pipeline "workspace" "repo" "branch-name"

# 监控新构建
node ~/.claude/skills/bitbucket-devops/lib/helpers.js get-by-number "workspace" "repo" <new-build-number>

5. 重复或庆祝：

• 如果新构建失败：用新日志回到步骤 1
• 如果新构建成功：✅ 成功！构建是绿色的
• 如果新构建正在进行中：使用模式 9 监控

这将数小时的手动调试转变为数分钟的 AI 辅助迭代。

---

完整文档

有关全面覆盖，请参阅这些详细指南：

• docs/REFERENCE.md - 所有第一层、第二层和第三层操作的完整命令参考
• docs/PATTERNS.md - 所有 11 个使用模式，带有详细示例和 bash 脚本
• docs/TROUBLESHOOTING.md - 常见错误，诊断命令和解决方案
• docs/GIT_OPERATIONS.md - API vs git 操作的凭据要求

---

日志存储

日志下载到 .pipeline-logs/ 在 VSCode 打开的目录中（你的工作目录）。

结构：

/path/to/open-project/
├── .pipeline-logs/           ← 在这里自动创建
│   ├── pipeline-123-Deploy.log
│   ├── pipeline-123-Test.log
│   └── errors-only.txt
├── src/
└── ...

重要：

• 日志存储在当前工作目录
• 始终使用相对路径：.pipeline-logs/filename.log
• 告诉用户将 .pipeline-logs/ 添加到他们项目的 .gitignore
• 日志跨会话持久保存，方便参考

---

常见错误（快速参考）

错误	原因	解决方案
“流水线未找到”	构建编号太旧	使用 get-latest-failed 代替
“日志不可用”	流水线仍在运行	等待完成
“未找到凭据文件”	缺少 credentials.json	从 credentials.json.template 复制
“未找到 Node.js”	Node 未安装	安装 Node.js v18+
“子模块未初始化”	Git 子模块缺失	运行 bash install.sh
“401 未授权”	错误的凭据	检查 credentials.json 中的 user_email（不是用户名）
“Git 认证失败”	错误的用户名	检查 git 操作的用户名（不是电子邮件）

详细故障排除： 见 docs/TROUBLESHOOTING.md

---

最佳实践

1. 始终确认工作区/仓库 - 从 git 自动检测或询问用户
2. 在日志之前检查流水线状态 - 不要为运行中的流水线请求日志
3. 限制初始结果 - 从 10 个最近的流水线开始，如需要增加
4. 智能日志过滤 - 使用 grep 首先找到错误
5. 缓存结果 - 将 JSON 响应存储在变量中以避免冗余调用
6. 使用辅助函数 - 优先使用第一层助手进行常见操作

---

性能说明

• 无需批准提示：Bash 工具带 node 命令自动批准
• 直接 API 调用：无 MCP 协议开销
• 凭据缓存：每次调用加载一次
• Bitbucket 速率限制：每小时每用户 60 个请求（标准层）

---

致谢

这项技能建立在 bitbucket-mcp 由 Apra Labs 构建，分支自 @MatanYemini 的原始工作。

架构： 将 bitbucket-mcp 作为库（git 子模块）使用，而不是作为 MCP 服务器。这种方法消除了批准提示，同时保持了完整的 API 功能。

许可证：CC BY 4.0 维护者：Apra Labs