mcpField
A
apidog-branch

apidog-branch

github.com/apidog开发456 次安装18 周前更新
代码仓库

关于 apidog-branch

通过 Apidog CLI 管理分支协作和 AI 编写的资源变更，强调明确分支上下文、在 AI 分支验证、处理写入权限，并在合并或创建合并请求前取得用户确认。

主要功能

  1. 01管理分支范围内的操作
  2. 02创建并填充 AI 分支
  3. 03使用 pick-to 导入资源
  4. 04在同一分支验证变更
  5. 05处理写入权限与合并确认

适用场景

  1. 01在 AI 分支编辑 API 资源
  2. 02创建合并请求前验证变更
  3. 03排查分支专属资源查询问题
  4. 04为受保护分支选择变更策略

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/apidog/apidog-cli-skills --skill apidog-branch

安装后在 Claude Code 中输入/apidog-branch确认已加载。

详细介绍

分支协作与 AI 写入

前置条件：请先阅读 ../apidog-cli/SKILL.md。如果稳定入口技能与此领域技能冲突，请以当前 CLI 帮助和此技能为准。

始终使用当前 CLI 帮助确认准确参数。此技能补充了最容易被误用的分支协作规则：分支上下文、AI 分支、pick-to、写入权限、受保护分支和合并确认。在分支上写入后，Agent 必须使用相同的 --branch 回读并验证；不要根据默认分支视图判断资源是否存在。

适用场景

  • 用户指定 --branch 或要求在某个分支上操作。
  • 创建、查看、更新、归档或删除分支。
  • 创建 AI 分支，并从源分支修改资源。
  • 将源分支资源 pick 到 AI 分支。
  • 合并分支或创建／批准合并请求。
  • 遇到 AI 写入权限限制。

命令入口

  • 分支管理：apidog branch --help
  • 合并请求：apidog merge-request --help
  • 资源命令通常支持 --branch <branchName>。查询、创建、更新和测试运行时，请保持相同的分支上下文。

先确定变更策略

在分支上写入前，请先确认用户希望采用哪种策略：

  • 直接编辑目标分支：适用于用户明确允许直接变更，且目标分支未受保护或权限限制的情况。
  • 通过 AI 分支编辑：适用于 AI 生成的 API、测试用例、测试场景或配置变更；也适用于目标分支受保护、禁止外部 AI 直接写入，或用户希望在合并前隔离验证的情况。

开始写入前，请确认：

  • 项目 ID。
  • 源分支和目标分支。
  • 要修改的资源范围。
  • 是否允许创建合并请求或稍后合并。

AI 分支工作流

AI 分支可隔离 AI 变更，避免污染源分支。

Confirm source branch and target change
  -> create AI branch
  -> pick-to existing resources
  -> modify on AI branch
  -> validate with get/run/report
  -> preview merge-request
  -> after user confirmation, create merge-request or merge

标准步骤：

  1. 创建 AI 分支时，使用 --from <sourceBranchName> 指定其源分支。
  2. 使用清晰的名称，例如 ai/YYYYMMDD-from-source-feature，如 ai/20260312-from-main-userRegister。
  3. 修改现有源分支资源前，使用 branch pick-to 将其导入 AI 分支；新资源无需 pick-to。
  4. 在 AI 分支上修改、查询或验证时，始终传入 --branch <aiBranchName>。
  5. 按资源类型进行验证，例如使用 get、run、本地报告或云端报告检查。
  6. 合并前，运行 merge-request preview，并让用户确认影响。
  7. 用户确认后，创建合并请求或执行合并；对于受保护的 main 分支，优先使用合并请求。

AI 分支说明：

  • AI 分支初始为空，不会自动复制源分支的所有资源。
  • branch get 可能返回 type: SPRINT 和 isAiBranch: true；这不代表操作时应使用 --type sprint。AI 分支操作仍应遵循当前帮助，并在需要时使用 --type ai。

分支参数规则

  • 优先使用分支名称：--branch <branchName>。
  • 数字 branchId 可能也兼容，但分支名称更便于在日志中查看和诊断。
  • 同一任务中，查询、创建、更新和运行测试时，请使用相同的分支上下文，以免误从 main／默认分支查找资源。

Pick-To 规则

  • 必须传入 --type ai。
  • 仅支持将 main 或常规 sprint 分支中的资源导入 AI 分支。
  • 不能导入 main。
  • 不能将 AI 分支用作源分支。
  • 使用 --include-endpoint-cases 可同时导入端点及其用例。

写入权限规则

  • main、sprint 和常规分支可能需要启用外部 AI 编辑权限。
  • 常见错误包括 Automation caller branch required。
  • 创建 AI 分支可能成功，但如果禁用了 AI 分支的 AI 编辑功能，仍可能无法向 AI 分支写入内容。
  • 写入受限时，不要自动切换策略；应询问用户是启用直接编辑权限，还是使用 AI 分支。
  • 如果目标 main 分支受到保护，优先使用 merge-request preview/create；不要直接运行 branch merge。

不得违反的规则

  1. 未经用户确认，不得创建 AI 分支。
  2. 在 AI 分支中修改现有源分支资源前，必须先使用 pick-to。
  3. 在针对分支的任务中，不得省略 --branch <branchName>。
  4. 未经用户确认，不得合并、创建合并请求或批准合并请求。
  5. 除非用户明确要求，否则不得删除或归档分支。
  6. 遇到 Automation caller branch required 时，应停止并询问用户选择权限策略；不得自动创建或切换到 AI 分支。

常见问题恢复

现象操作
不指定分支执行 get 时找不到资源使用 --branch <branchName> 重试
AI 分支中缺少源资源先使用 branch pick-to
分支状态显示有计数，但 AI 分支页面为空不要认为资源已导入；AI 分支仍需要执行 pick-to
分支上的运行配置返回 404确认 case/endpoint/environment/branch 均存在，然后切换到 apidog-cli-checkup
受保护分支阻止合并改用 merge-request

评论

支持 Markdown