branch-manager

star 1

分支隔离管理工具 - F016 Phase 1 & 2 & 3 完整实现。提供 feature 分支创建、PR 提交、PR 合并、状态追踪、列表查询和状态面板功能。分支命名规范: <agent>/task-<id>-<short-desc>

G3niusYukki By G3niusYukki schedule Updated 3/7/2026
play_arrow Run Skill in Manus View GitHub

name: branch-manager description: "分支隔离管理工具 - F016 Phase 1 & 2 & 3 完整实现。提供 feature 分支创建、PR 提交、PR 合并、状态追踪、列表查询和状态面板功能。分支命名规范: /task--"

Branch Manager Skill

分支隔离机制 Phase 1 & 2 & 3 完整工具。管理功能分支的生命周期，确保多 Agent 协作时代码变更隔离。

分支命名规范

<agent-id>/task-<timestamp>-<short-description>

示例:

  • hephaestus/task-20250308-a1b2-implement-auth
  • apollo/task-20250307-c3d4-fix-bug

核心功能

1. create_branch - 创建功能分支

参数:

  • agentId (string, required): 创建分支的 Agent ID
  • taskDescription (string, required): 任务描述，将用于生成分支名
  • baseBranch (string, optional): 基于哪个分支创建，默认 main

返回:

{
  "branchName": "hephaestus/task-20250308-a1b2-test-branch",
  "taskId": "20250308-a1b2",
  "success": true
}

使用方式:

import { createBranch } from './create_branch.ts';

const result = createBranch({
  agentId: 'hephaestus',
  taskDescription: '测试分支功能',
  baseBranch: 'main'
});

if (result.success) {
  console.log(`Created: ${result.branchName}`);
}

或通过 CLI:

deno run --allow-run --allow-read --allow-write create_branch.ts \
  --agentId=hephaestus \
  --taskDescription="测试分支功能" \
  --baseBranch=main

2. rollback_branch - 分支回滚 (Phase 3)

三级回滚机制，根据分支状态自动选择合适的回滚级别：

  • Level 1: git reset --hard HEAD~N - 开发中回滚
  • Level 2: 标记分支为 "aborted" - 废弃分支
  • Level 3: git revert -m 1 <merge-commit> - 合并后紧急回滚

参数:

  • branchName (string, required): 要回滚的分支名称
  • toCommit (string, optional): 目标 commit (Level 1 使用，默认 HEAD~1)
  • mode (string, optional): 重置模式 soft 或 hard (Level 1)，默认 hard
  • level (number, optional): 指定回滚级别 1|2|3，未指定时自动根据分支状态决定
  • mergeCommit (string, optional): 合并 commit SHA (Level 3 必需)
  • reason (string, optional): 回滚原因

返回:

{
  "success": true,
  "previousHead": "abc123def456",
  "newHead": "def789abc012",
  "backupTag": "backup/feature/test/2025-03-08T01-30-00-000Z",
  "level": 1,
  "message": "Level 1 rollback completed: reset feature/test to HEAD~1 (hard mode)\nBackup tag: backup/feature/test/2025-03-08T01-30-00-000Z"
}

使用方式:

import { rollbackBranch } from './rollback_branch.ts';

// Level 1: 开发中回滚到上一个 commit
const result = rollbackBranch({
  branchName: 'hephaestus/task-20250308-a1b2-test',
  level: 1,
  mode: 'hard'
});

// Level 1: 回滚到指定 commit
const result = rollbackBranch({
  branchName: 'hephaestus/task-20250308-a1b2-test',
  level: 1,
  toCommit: 'abc123def456',
  mode: 'soft'
});

// Level 2: 废弃分支
const result = rollbackBranch({
  branchName: 'hephaestus/task-20250308-a1b2-test',
  level: 2,
  reason: 'Task cancelled by PM'
});

// Level 3: 紧急回滚已合并的 PR
const result = rollbackBranch({
  branchName: 'hephaestus/task-20250308-a1b2-test',
  level: 3,
  mergeCommit: 'def789abc012',
  reason: 'Critical bug found in production'
});

或通过 CLI:

# Level 1: Reset to previous commit (hard)
deno run --allow-run --allow-read --allow-write rollback_branch.ts \
  --branchName=feature/test \
  --level=1

# Level 1: Soft reset to specific commit
deno run --allow-run --allow-read --allow-write rollback_branch.ts \
  --branchName=feature/test \
  --toCommit=abc123 \
  --mode=soft \
  --level=1

# Level 2: Abort branch
deno run --allow-run --allow-read --allow-write rollback_branch.ts \
  --branchName=feature/test \
  --level=2 \
  --reason="No longer needed"

# Level 3: Revert merge commit
deno run --allow-run --allow-read --allow-write rollback_branch.ts \
  --branchName=feature/test \
  --level=3 \
  --mergeCommit=def789 \
  --reason="Critical bug found"

3. submit_pr - 提交 PR

参数:

  • branchName (string, required): 功能分支名称
  • title (string, required): PR 标题
  • description (string, required): PR 描述 (What/Why/Tradeoff)
  • reviewers (string[], required): 审查者列表 (如 ["zeus", "athena"])
  • draft (boolean, optional): 是否创建为草稿 PR

返回:

{
  "prNumber": 42,
  "prUrl": "https://github.com/org/repo/pull/42",
  "success": true
}

使用方式:

import { submitPR } from './submit_pr.ts';

const result = submitPR({
  branchName: 'hephaestus/task-20250308-a1b2-test-branch',
  title: 'Add new authentication feature',
  description: 'Implements OAuth2 login flow',
  reviewers: ['zeus', 'athena'],
  draft: false
});

或通过 CLI:

deno run --allow-run --allow-read --allow-write submit_pr.ts \
  --branchName=hephaestus/task-20250308-a1b2-test-branch \
  --title="Add new authentication feature" \
  --description="Implements OAuth2 login flow" \
  --reviewers=zeus,athena

4. merge_pr - 合并 PR

参数:

  • prNumber (number, required): PR 编号
  • mergeStrategy (string, optional): 合并策略 (merge, squash, rebase)，默认 merge
  • deleteBranch (boolean, optional): 合并后是否删除功能分支，默认 false

返回:

{
  "success": true,
  "commitSha": "a1b2c3d4",
  "message": "Successfully merged PR #42 (commit: a1b2c3d)"
}

使用方式:

import { mergePR } from './merge_pr.ts';

const result = mergePR({
  prNumber: 42,
  mergeStrategy: 'squash',
  deleteBranch: true
});

if (result.success) {
  console.log(`Merged: ${result.message}`);
}

或通过 CLI:

deno run --allow-run --allow-read --allow-write merge_pr.ts \
  --prNumber=42 \
  --mergeStrategy=squash \
  --deleteBranch

5. list_branches - 查询分支状态

参数:

  • agentId (string, optional): 按 Agent 筛选
  • status (string, optional): 按状态筛选 (working | pr_open | merged | aborted)

返回:

{
  "branches": [...],
  "total": 5
}

使用方式:

import { listBranches, listBranchesByStatus, getActiveBranches } from './list_branches.ts';

// 列出所有分支
const all = listBranches();

// 按 Agent 筛选
const mine = listBranches({ agentId: 'hephaestus' });

// 按状态筛选
const working = listBranches({ status: 'working' });

// 分组查看
const grouped = listBranchesByStatus();

// 仅活跃分支
const active = getActiveBranches();

或通过 CLI:

# 列出所有分支
deno run --allow-run --allow-read list_branches.ts

# 按 Agent 筛选
deno run --allow-run --allow-read list_branches.ts --agentId=hephaestus

# 按状态筛选
deno run --allow-run --allow-read list_branches.ts --status=working

# 分组显示
deno run --allow-run --allow-read list_branches.ts --grouped

分支状态流转

working → pr_open → merged
   ↓         ↓         ↓
aborted   aborted   reverted (via Level 3 rollback)
  • working: 开发中，分支已创建
  • pr_open: PR 已提交
  • merged: 已合并到主分支
  • aborted: 已废弃

回滚机制

级别 场景 Git 操作 结果
Level 1 开发中需要回退 git reset --hard HEAD~N 重写分支历史
Level 2 放弃当前分支 标记 aborted 分支保留，状态变更
Level 3 合并后发现严重问题 git revert -m 1 <merge> 创建反向提交

注册表

分支信息存储在 workspace 根目录的 .branch-registry.json:

{
  "version": "1.0",
  "branches": [
    {
      "taskId": "20250308-a1b2",
      "agentId": "hephaestus",
      "branchName": "hephaestus/task-20250308-a1b2-test-branch",
      "description": "测试分支功能",
      "baseBranch": "main",
      "status": "pr_open",
      "prNumber": 42,
      "prUrl": "https://github.com/org/repo/pull/42",
      "createdAt": "2026-03-08T00:00:00.000Z",
      "updatedAt": "2026-03-08T01:00:00.000Z"
    }
  ],
  "lastUpdated": "2026-03-08T01:00:00.000Z"
}

技术细节

错误处理

  • 非 git 仓库: 返回 success: false, error: "Not a git repository"
  • 基础分支不存在: 自动检查本地和远程分支
  • 工作区有修改: 自动 stash 并在创建后恢复
  • PR 不存在: 返回 success: false, error: "PR #N not found"
  • PR 已合并/关闭: 返回相应错误信息

Git 操作

  • 自动 fetch origin 确保基础分支最新
  • 支持从 origin/<branch> 创建
  • 自动同步注册表与 git 实际状态
  • 使用 gh pr merge 命令合并 PR
  • 支持 --merge, --squash, --rebase 策略

权限控制

  • 只有授权 Agent (zeus, athena) 可以执行合并操作
  • 可通过环境变量 AGENT_ID 或 --agentId 参数指定执行者

测试

# 创建测试分支
cd /Users/peterzhang/.openclaw/workspace
deno run --allow-run --allow-read --allow-write skills/branch-manager/create_branch.ts \
  --agentId=hephaestus \
  --taskDescription="测试分支功能"

# 提交 PR
deno run --allow-run --allow-read --allow-write skills/branch-manager/submit_pr.ts \
  --branchName=hephaestus/task-20250308-a1b2-test-branch \
  --title="Test PR" \
  --description="Test description" \
  --reviewers=zeus

# 合并 PR
deno run --allow-run --allow-read --allow-write skills/branch-manager/merge_pr.ts \
  --prNumber=42 \
  --mergeStrategy=squash \
  --deleteBranch

# 列出所有分支
deno run --allow-run --allow-read skills/branch-manager/list_branches.ts

集成到 Agent

Agents 可以在完成任务时自动管理分支生命周期:

// 在 Agent 任务开始时
const branch = createBranch({
  agentId: 'hephaestus',
  taskDescription: context.taskDescription,
  baseBranch: 'main'
});

// 存储 branch.taskId 用于后续关联
context.currentBranch = branch;

// 任务完成后提交 PR
const pr = submitPR({
  branchName: branch.branchName,
  title: context.taskTitle,
  description: generatePRDescription(context),
  reviewers: ['zeus']
});

// 审查通过后合并 (通常由 zeus/athena 执行)
const merge = mergePR({
  prNumber: pr.prNumber,
  mergeStrategy: 'squash',
  deleteBranch: true
});

5. dashboard - 状态面板 (Phase 3)

参数:

  • --watch (optional): 启用实时刷新模式
  • --interval=5000 (optional): 刷新间隔（毫秒），默认 5000ms
  • --json (optional): 输出 JSON 格式（用于程序化使用）

输出格式:

┌─────────────────────────────────────────┐
│ 🐱 六猫分支状态面板                    │
├─────────────────────────────────────────┤
│ 🎀 Athena: 2 working, 1 pr_open        │
│ 🐯 Hephaestus: 1 merged                │
│ ...                                    │
├─────────────────────────────────────────┤
│ 📊 Total: 4 branches, 2 agents         │
│ 🟡 Active: 3 branches                  │
│ 🔵 PR Review: 1 awaiting               │
│ 🟢 Merged Today: 1                     │
├─────────────────────────────────────────┤
│ Updated: 10:30:45 AM                   │
└─────────────────────────────────────────┘

使用方式:

import { generateDashboard, getDashboardData, watchDashboard } from './dashboard.ts';

// 获取格式化字符串
const dashboardText = generateDashboard();
console.log(dashboardText);

// 获取结构化数据
const data = getDashboardData();
console.log(data.stats);
console.log(data.agents);

// 启动 watch 模式
await watchDashboard(5000); // 每 5 秒刷新

或通过 CLI:

# 显示状态面板
deno run --allow-read skills/branch-manager/dashboard.ts

# JSON 输出
deno run --allow-read skills/branch-manager/dashboard.ts --json

# 实时刷新模式（5秒间隔）
deno run --allow-read skills/branch-manager/dashboard.ts --watch

# 自定义刷新间隔
deno run --allow-read skills/branch-manager/dashboard.ts --watch --interval=10000

Agent Emoji 映射:

  • Athena: 🎀
  • Hephaestus: 🐯
  • Apollo: 🌞
  • Artemis: 🌙
  • Hermes: 📯
  • Zeus: ⚡

未来扩展

Phase 4 计划:

  • cleanup_branches: 清理已合并分支
  • sync_branches: 与 GitHub PR 状态同步
  • validate_branch: 检查分支命名规范
  • request_review: 请求审查并发送通知
Install via CLI
npx skills add https://github.com/G3niusYukki/BranchCafe --skill branch-manager
Repository Details
star Stars 1
call_split Forks 0
navigation Branch main
article Path SKILL.md
More from Creator
G3niusYukki
G3niusYukki Explore all skills →