SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场synthesis-bitbucket

synthesis-bitbucket

编程与开发

查看项目

更新于 10-22 16:15

技能介绍

用途

Synthesis Bitbucket 是一个供 AI 智能体使用的技能，定义智能体如何通过 bkt 与 Bitbucket Cloud 交互。bkt 是一个开源社区 CLI，在 Bitbucket 场景中扮演 gh 在 GitHub 中的角色。

该技能存在的原因是：跨多个仓库工作的智能体，如果不加约束，往往会退化为手写原始 REST 调用或使用错误的 CLI，每次会话都要重新手工拼装认证、URL 编码和分页逻辑，行为不一致。

核心规则一句话：如果 bkt 能做，就用 bkt。REST API 是逃生通道（bkt api），不是默认方式。

团队可以在此技能之上叠加一个私有配套技能，携带自己的工作区名称、默认上下文和发布约定。本技能保持通用。

绑定规则

规则 1 至 3 是 1.2.2 安全规则，编号保持不变。

  1. 读取自由，写入需谨慎。未经操作者对特定 PR 的明确意图，绝不批准、合并、拒绝或创建。
  2. 单一命令面。不要在同一工作流中混用 bkt、原始 curl 和 Git 托管 Web UI——状态会漂移，认证面会增多。
  3. 仓库级技能不会随行。签入某个仓库的技能在会话于别处工作时不会被加载。请将本技能（以及团队的配套技能）安装在个人/智能体级别，使命令面在每个会话中都存在。
  4. 每个作用于仓库的 bkt 命令都必须恰好命名一个字面量 --repo <slug>（api 则使用其规范字面路径）。共享默认上下文永远不能选择仓库，即使对于读取或循环也不行：下一个会话可能改变它。
  5. 命名仓库仅标识目标，不授予发送、审查、合并或发布权限。
  6. bkt pipeline run 可能触发部署。先核实其影响和适用的部署授权。
  7. 固定一个经过审查的 bkt 版本，升级前重新审查差异：它是社区工具，对你的仓库有写权限。
  8. Git 使用 SSH 密钥；bkt 使用令牌。REST 令牌不一定能认证 git HTTPS，且上下文主机必须与 bkt auth status 完全匹配。

内容文件

  • references/setup.md：安装与固定版本、认证（OAuth 或限定范围的 API 令牌）、配置连接上下文，以及上下文主机的坑。当 bkt 尚未安装或认证，或调用失败并提示 "host not found" 时阅读。
  • references/pr-queue.md：scripts/pr_queue.py 如何构建每日例程 PR 队列，以及何时报告 unscanned。在处理或解读 PR 队列扫描时阅读。
  • references/coverage-map.md：1.2.2 文本各部分现在的位置，以及里程碑 M3 的脚本变更。
  • references/preserved.md：已退役的绑定校验器文本，逐字保留。仅在审查被删减内容时阅读。

显式仓库绑定

每个受支持的仓库读取或写入都必须携带一个字面量 --repo <slug>。选择该命名空间时，Cloud 提供 --workspace <workspace>，Data Center 提供 --project <key>。绝不要使用可变的活跃上下文作为仓库证据，包括只读调用、pr ls 之类的别名，或循环中的重复调用。在此仓库范围策略下运行时，bkt pr list --mine 也需要指定目标仓库。对于组合读取，应枚举已授权的仓库清单，而不是静默扩大其覆盖范围。

认证、连接上下文管理、help/version 以及 api /user GET 属于非仓库操作。实际的 api 命令不支持 --repo：请使用其规范字面路径 /repositories/<workspace>/<repo>/... 或 Data Center 的 /rest/api/1.0/projects/<key>/repos/<repo>/... 路径。未解析、被重定向或穿越的路径不构成绑定。绝不要添加不支持的标志来制造绑定。

这是智能体自行应用的规则，而非机械检查：在运行作用于仓库的命令之前，回读该命令并确认它恰好命名一个 --repo（或一个规范 api 路径）。命名仓库仅标识目标：它不授予发送、审查、合并或发布权限。采用其他 bkt 版本时，请对照其自身的 --help 重新检查文档化标志。

命令目录

任何命令的全局标志：--json · --yaml · --template '<Go template>' · --jq '<expr>'（配合 --json）· --format json|yaml · -c <context>。上下文覆盖：--workspace、--repo。

读取（安全，可自由使用）：

  • bkt pr list --repo <repo> — --state OPEN|MERGED|DECLINED · --limit <n>（0 表示全部）· --mine
  • bkt pr view <id> --repo <repo> · bkt pr diff <id> [--stat] --repo <repo> · bkt pr comments <id> [--state unresolved] --repo <repo> · bkt pr checks <id> [--wait] --repo <repo>
  • bkt repo view --repo <repo> · bkt branch list --repo <repo> · bkt pipeline list|view --repo <repo>

写入（有后果——运行前确认意图）：

  • bkt pr create --title <t> --description <d> --source <branch> --target <branch> [--reviewer <user|{UUID}>]… [--with-default-reviewers] [--draft] --repo <repo>
  • bkt pr comment <id> --text <msg> [--parent <comment-id>] [--file <path> --to-line <n>] --repo <repo>
  • bkt pr edit <id> --repo <repo> · bkt pr approve <id> --repo <repo> · bkt pr merge <id> [--strategy <server-supported-id>] --repo <repo> · bkt pr decline <id> --repo <repo> · bkt pr reopen <id> --repo <repo>
  • bkt pipeline run --repo <repo> --ref <branch|tag|commit> — 启动流水线并可能部署；先核实其影响和适用的部署授权。

合并策略 ID 取决于服务器和仓库。CLI 接受字符串；其帮助文档使用 rebase_fast_forward 作为示例，并非通用支持值列表。

逃生通道

bkt api /repositories/<ws>/<repo>/... — 原始 REST，认证已处理。仅用于目录缺少的接口；当某个缺口成为常规需求时，优先在团队的配套技能中添加说明。

gh → bkt 对照

  • gh pr list → bkt pr list --repo <repo>
  • gh pr view N → bkt pr view N --repo <repo>
  • gh pr diff N → bkt pr diff N --repo <repo>
  • gh pr create → bkt pr create --repo <repo>
  • gh pr review --approve → bkt pr approve N --repo <repo>
  • gh pr merge N → bkt pr merge N --repo <repo>
  • gh pr comment N -b … → bkt pr comment N --text … --repo <repo>
  • gh api … → bkt api …

Bitbucket Cloud 没有 PR 标签，其 PR 状态为 OPEN、MERGED、DECLINED、SUPERSEDED——请相应调整 gh 习惯。

适用场景

适用于需要通过 bkt 操作 Bitbucket Cloud 仓库的智能体会话，包括 PR 生命周期管理、仓库与分支读取、流水线查看与运行，以及使用 bkt api 访问目录未覆盖的 REST 接口。

限制

  • 不适用于 GitHub 或 GitLab 仓库（那里应使用 gh / glab）。
  • 不适用于超出 bkt 支持范围的 Bitbucket Data Center 特殊情况——请先查看项目 README。
  • 本技能保持通用，不包含具体团队的工作区名称、默认上下文或发布约定，这些需由私有配套技能提供。
  • 关于安装、认证、定价、平台支持等具体信息，资料中暂未提供。