SuperAPI AI 工具集

github-worktree

编程与开发

查看项目

更新于 10-16 09:40

技能介绍

用途

GitHub Issue Worktree 是一个在 Cursor IDE 中运行的开发工作流技能,服务于蓝盾(bk-ci)仓库。当用户在 master 分支上提出需要改动代码的需求时,本流程会引导先建立工作分支与 worktree,而不是直接改动 master。技能适配蓝盾 GitHub Issue 驱动的开发模式。

触发条件

须用户 @ 本 skill,或明确表示要按 GitHub Issue worktree 流程执行时才会读取。此外还需满足前置检查:本 skill 仅在 Cursor IDE 中生效(判断方式为用户信息中存在 Workspace Path 且 Shell 可执行 cursor --version 命令);当前分支必须是 master;需要确认 user-github MCP 服务器可用。如果不在 Cursor IDE 或不在 master 分支,则跳过工作流,直接执行用户需求。若 GitHub MCP 不可用,会提醒用户在 Cursor Settings → MCP 中添加 GitHub 服务器后重试,或由用户手动提供分支名跳过 issue 关联步骤。

硬性约束

一旦用户选择创建分支,Agent 在本次对话轮次中禁止对项目文件做任何内容修改,包括写入、编辑、创建文件。工作流结束后,提示用户在新打开的 worktree 窗口中继续操作。仅当用户明确选择“直接在 master 上改”时,才跳过工作流、正常执行需求。

固定参数

  • 仓库 owner = TencentBlueKing,repo = bk-ci
  • 远端 = origin,新分支基线 = origin/master
  • 当前 GitHub 用户:通过 get_me 获取 login(用于 issue assignee)
  • GitHub MCP server = user-github

工作流

Step 1:询问是否创建分支

使用 AskQuestion 工具向用户确认如何关联 GitHub Issue,选项包括:关联已有 Issue 建分支(需提供 issue 号);新建 Issue 后建分支(在上游公开仓库建单,需二次确认);不关联 Issue 直接建分支(需提供分支名);不建分支直接在 master 上改(给出风险提示后继续)。

Step 2:确定关联的 Issue

A. 关联已有 Issue:用户提供 issue 号后,通过 user-github MCP 的 issue_read 读取标题,从返回中取 title 与(如有)labels、issue_type,用于推断 type 与提炼关键词。

B. 新建 Issue(上游公开仓库,需二次确认):在公开上游 TencentBlueKing/bk-ci 创建 Issue 前,必须用 AskQuestion 让用户确认标题/正文,确认后才调用创建接口。Issue 标题规范为 {type}: {简短描述}(英文冒号后保留一个空格),type 与分支前缀一致,取值为 feat(新功能、能力增强)、bug(缺陷修复)、pref(性能、参数、配置优化)、refactor(重构,不改外部行为)、issue(类型不明确、杂项跟踪)。标题中不要再写 issue 号;编号由 GitHub 分配。正文用背景/需求/验收等结构。get_me 获取当前用户 login 作为 assignee。可选地通过 list_issue_types 确认组织是否启用 issue type。通过 user-github MCP 的 issue_write 以 create 方法创建,从返回中取新 issue 的 number。

C. 不关联 Issue:让用户直接提供分支名,或根据需求描述生成分支名(不含 issue 号后缀),跳到 Step 4。

Step 3:生成分支名

命名规则为 {type}-{issue号} 或 {type}-{keywords}-{issue号}。type 推断优先级:标题前缀(feat:、bug:、pref:、refactor:、issue:,不区分大小写)→ GitHub issue_type(Feature → feat,Bug → bug)→ labels(kind/bug → bug,kind/enhancement → feat)→ 仍无法判断则用 issue。keywords 为去掉 type 前缀后从标题提取 1~3 个英文关键词(全小写、- 连接),中文标题可据语义翻译或缩写,例如“知识库”→ knowledge。issue 号为 GitHub Issue 编号(纯数字),必须为分支名末段。示例:bug-12994、feat-11524、feat-tenant-3-11524、feat-knowledge-13058。若用户选择不关联 Issue,则分支名末段可不含 issue 号。

Step 4:创建 Worktree 并同时创建分支

先拉取最新代码:

git remote set-url origin https://github.com/TencentBlueKing/bk-ci.git git fetch origin master

执行脚本前先确认目标分支名在本地尚不存在;本步骤要求创建 worktree 时同时新建分支,不复用已有本地分支。如果本地已存在同名分支,应提示用户改名,或先手动清理旧分支/旧 worktree 后再重试。按操作系统选择脚本,基线指定 origin/master:

Windows(PowerShell):

powershell -File .cursor/skills/github-worktree/scripts/git-worktree.ps1 -Action Add -Branch "<分支名>" -Base origin/master

macOS / Linux(Bash):

bash .cursor/skills/github-worktree/scripts/git-worktree.sh add -b "<分支名>" -B origin/master

脚本会显式执行“基于 origin/master 新建分支 + 创建 worktree”两个动作;成功后自动从主仓库同步 .idea 和 .cursor 到新 worktree,保证 IDEA 项目配置、Gradle 导入配置、本地运行配置以及当前工程下的 Cursor rules/skills/config 尽量与主仓库窗口一致。脚本随后进入新 worktree 的 src/backend/ci,对所有使用 task-gen-jooq 的模型模块执行 jOOQ 生成任务;如果数据库不可访问或 jOOQ 生成失败,脚本会失败退出,需先处理数据库连接或生成错误。操作系统判断:OS Version 包含 win32 用 PowerShell 脚本,包含 darwin 或 linux 用 Bash 脚本。

Step 5:在新窗口打开 Worktree

从 Step 4 脚本输出中提取 Created worktree: <path> 的实际路径(不要自己拼路径),用以下命令在 Cursor 新窗口打开:

cursor --new-window "<从脚本输出中提取的 worktree 路径>"

告知用户新窗口已打开,可以在新窗口中继续开发。本次对话到此结束,不要再对任何文件做修改。

脚本说明

脚本 git-worktree.ps1(Windows,路径 .cursor/skills/github-worktree/scripts/git-worktree.ps1)与 git-worktree.sh(macOS/Linux,路径 .cursor/skills/github-worktree/scripts/git-worktree.sh)功能一致,支持三个操作:add(基于 -B/-Base 指定的 base 同时新建分支与 worktree,若本地已存在同名分支则直接失败,避免误复用旧分支);list(列出所有 worktree);remove(移除 worktree,支持按分支名或路径)。

适用场景与限制

适用于在 Cursor IDE、master 分支上按 GitHub Issue 驱动方式为 bk-ci 仓库建立隔离工作分支与 worktree 的开发场景。限制包括:仅在 Cursor IDE 生效;仅当前分支为 master 时触发;issue 关联步骤依赖 GitHub MCP 服务可用;在上游公开仓库建单需二次确认;脚本执行依赖数据库可访问以完成 jOOQ 生成。关于收费、价格、平台范围等信息资料暂未提供。