Ruflo 的 Project Board Sync 技能：把 AI Swarm 与 GitHub Projects 看板做双向同步

本文基于仓库中的技能文档 .agents/skills/agent-project-board-sync/SKILL.md 展开，讲清 ruflo（原 claude-flow）体系中 “project-board-sync” 协调技能的完整工作流：如何通过 gh CLI 与 npx ruv-swarm 命令族把 AI 蜂群（swarm）的任务、代理负载和优先级映射到 GitHub Projects 看板，并覆盖看板初始化、状态映射配置、实时同步、自动化规则、分析报表、冲刺/里程碑管理以及故障诊断等全部实操内容。读完本文，你可以按技能文档原样搭建一个“蜂群状态可视化 + 任务双向同步”的项目看板体系，并理解该技能在 ruflo 技能生态与 MCP 集成中的位置。

1. 技能定位：一个协调型 Agent 技能

该技能以 $agent-project-board-sync 作为调用入口，声明如下（摘自 SKILL.md 的前置元数据）：

name: project-board-sync
description: Synchronize AI swarms with GitHub Projects for visual task management, progress tracking, and team coordination
type: coordination
color: "#A8E6CF"

它的定位是 coordination（协调型）技能：目标不是执行编码任务，而是把“AI 蜂群内部的任务状态”与“GitHub Projects 看板”打通，实现可视化任务管理、进度跟踪与团队协作。整个文档给出的操作分三层：

• gh CLI 层：负责与 GitHub 认证、项目和 Issue 的原始交互（取项目 ID、列 Issue、加项目条目等）；
• npx ruv-swarm github ... 命令层：技能文档规定的蜂群侧操作接口，覆盖看板初始化、同步、实时推送、自动分配、分析与报表；
• 配置文件层：以 .github/board-sync.yml 等 YAML/JSON 配置定义状态映射、代理标签、自定义字段与视图。

仓库中另有佐证：ruflo 的初始化引导器 v3/@claude-flow/cli/src/init/executor.ts 在生成项目脚手架文档时，把 project-board-sync 与 github-modes、issue-tracker、workflow-automation、multi-repo-swarm 等并列列为内置协调技能之一；同文件还把 ruv-swarm 文档化为可选 MCP 集成（claude mcp add ruv-swarm -- npx -y ruv-swarm mcp start）。也就是说，该技能既可作为 Agent 技能在会话中调用，也可配合 ruv-swarm MCP Server 作为常驻服务使用。

2. 前置钩子（pre/post hooks）：环境与状态自检

技能元数据里声明了执行前（pre）与执行后（post）两组钩子命令，用于在同步动作前后自动校验环境：

hooks:
  pre:
    - "gh auth status || (echo 'GitHub CLI not authenticated' && exit 1)"
    - "gh project list --owner @me --limit 1 > /dev/null || echo 'No projects accessible'"
    - "git status --porcelain || echo 'Not in git repository'"
    - "gh api user | jq -r '.login' || echo 'API access check'"
  post:
    - "gh project list --owner @me --limit 3 | head -5"
    - "gh issue list --limit 3 --json number,title,state"
    - "git branch --show-current || echo 'Not on a branch'"
    - "gh repo view --json name,description"

• pre 钩子逐条检查：gh 是否已认证（未认证直接退出）、当前账号是否至少能访问一个 Project、当前目录是否处于 git 仓库内、API 是否能取到当前登录名。这保证任何看板同步命令运行时，认证与仓库上下文都已就绪；
• post 钩子则输出一份“执行后快照”：最近的 3 个可访问项目、最近的 3 个 Issue（含编号/标题/状态）、当前分支名、仓库基本信息，便于人工核对同步结果落在正确的仓库与分支上。

3. 看板初始化（Board Initialization）

第一步是把蜂群与一个 GitHub Project 关联起来。技能文档给出的标准流程是：

# Connect swarm to GitHub Project using gh CLI
# Get project details
PROJECT_ID=$(gh project list --owner @me --format json | \
  jq -r '.projects[] | select(.title == "Development Board") | .id')

# Initialize swarm with project
npx ruv-swarm github board-init \
  --project-id "$PROJECT_ID" \
  --sync-mode "bidirectional" \
  --create-views "swarm-status,agent-workload,priority"

# Create project fields for swarm tracking
gh project field-create $PROJECT_ID --owner @me \
  --name "Swarm Status" \
  --data-type "SINGLE_SELECT" \
  --single-select-options "pending,in_progress,completed"

要点解析：

1. 用 gh project list 按标题取项目 ID：--format json 输出后经 jq 按 title == "Development Board" 过滤，拿到 GraphQL 项目 ID（$PROJECT_ID），避免手工从网页 URL 里抄 ID；
2. board-init 建立双向同步：--sync-mode "bidirectional" 表示蜂群任务状态变化会更新看板，看板侧的卡片移动也会回写蜂群；--create-views 一次性创建 swarm-status（蜂群状态）、agent-workload（代理负载）、priority（优先级）三个视图；
3. 补充自定义字段：gh project field-create 给项目增加单选字段 “Swarm Status”，选项固定为 pending / in_progress / completed，作为蜂群侧状态在看板上的落点。

4. 任务同步（Task Synchronization）与状态映射

初始化之后，日常同步由 board-sync 承担：

# Sync swarm tasks with project cards
npx ruv-swarm github board-sync \
  --map-status '{
    "todo": "To Do",
    "in_progress": "In Progress",
    "review": "Review",
    "done": "Done"
  }' \
  --auto-move-cards \
  --update-metadata

• --map-status 传入一个 JSON 映射表，把蜂群内部的任务状态（todo / in_progress / review / done）翻译为看板列名；
• --auto-move-cards 让同步引擎在状态变化时自动把卡片移动到对应列；
• --update-metadata 表示同步时刷新卡片的元数据（字段、标签等），而不只是改列。

5. 实时更新（Real-time Updates）

若需要低延迟推送，用 board-realtime：

# Enable real-time board updates
npx ruv-swarm github board-realtime \
  --webhook-endpoint "https://api.example.com/github-sync" \
  --update-frequency "immediate" \
  --batch-updates false

--webhook-endpoint 指向你的中转服务（示例用占位域名 api.example.com，实际需替换为可达地址）；--update-frequency "immediate" 表示事件即时推送；--batch-updates false 关闭批量化，保证逐条实时刷新。若事件量大、希望降低 API 消耗，可以把 batch 打开并降低频率，技能文档将这两者作为一对权衡参数。

6. 配置文件详解：.github/board-sync.yml

除命令行参数外，技能文档定义了一份完整的看板映射配置（board-sync.yml），建议放在仓库 .github/board-sync.yml，内容覆盖四类映射：

# .github/board-sync.yml
version: 1
project:
  name: "AI Development Board"
  number: 1

mapping:
  # Map swarm task status to board columns
  status:
    pending: "Backlog"
    assigned: "Ready"
    in_progress: "In Progress"
    review: "Review"
    completed: "Done"
    blocked: "Blocked"

  # Map agent types to labels
  agents:
    coder: "🔧 Development"
    tester: "🧪 Testing"
    analyst: "📊 Analysis"
    designer: "🎨 Design"
    architect: "🏗️ Architecture"

  # Map priority to project fields
  priority:
    critical: "🔴 Critical"
    high: "🟡 High"
    medium: "🟢 Medium"
    low: "⚪ Low"

  # Custom fields
  fields:
    - name: "Agent Count"
      type: number
      source: task.agents.length
    - name: "Complexity"
      type: select
      source: task.complexity
    - name: "ETA"
      type: date
      source: task.estimatedCompletion

逐段说明：

• project：声明要同步的目标项目名与编号（name: "AI Development Board"、number: 1），与第 3 节 board-init 中关联的项目对应；
• mapping.status：比 board-sync --map-status 更完整的一套状态映射，多出 pending → Backlog、assigned → Ready、blocked → Blocked 三个状态，覆盖任务从入列到阻塞的全生命周期；
• mapping.agents：把代理类型映射为看板标签（coder→Development、tester→Testing 等），卡片上即可直接看出由哪类代理负责；
• mapping.priority：把 critical / high / medium / low 四级优先级映射为带颜色的项目字段值；
• mapping.fields：自定义字段声明，source 是取自蜂群任务对象的表达式路径，例如 Agent Count 取 task.agents.length（数字型）、Complexity 取 task.complexity（下拉型）、ETA 取 task.estimatedCompletion（日期型）。这让看板卡片可以展示蜂群侧的计算结果，而不只是 GitHub 原生字段。

7. 视图配置（View Configuration）

技能文档同时给出了一段 JSON 风格的视图定义，用于创建三类自定义看板视图：

// Custom board views
{
  "views": [
    {
      "name": "Swarm Overview",
      "type": "board",
      "groupBy": "status",
      "filters": ["is:open"],
      "sort": "priority:desc"
    },
    {
      "name": "Agent Workload",
      "type": "table",
      "groupBy": "assignedAgent",
      "columns": ["title", "status", "priority", "eta"],
      "sort": "eta:asc"
    },
    {
      "name": "Sprint Progress",
      "type": "roadmap",
      "dateField": "eta",
      "groupBy": "milestone"
    }
  ]
}

• Swarm Overview（board 型）：按状态分列、只过滤 is:open、按优先级降序，是日常总览视图；
• Agent Workload（table 型）：按 assignedAgent 分组、展示 title/status/priority/eta 四列、按 ETA 升序，用于查看每个代理“背了多少活”；
• Sprint Progress（roadmap 型）：以 eta 作为日期字段、按 milestone 分组，用于冲刺进度路线化展示。

这与 board-init --create-views "swarm-status,agent-workload,priority" 创建的三个默认视图一一对应：命令行快速建视图，配置化定义则提供更精细的过滤与排序。

8. 自动化能力

8.1 自动分配（Auto-Assignment）

# Automatically assign cards to agents
npx ruv-swarm github board-auto-assign \
  --strategy "load-balanced" \
  --consider "expertise,workload,availability" \
  --update-cards

--strategy "load-balanced" 指定负载均衡策略；--consider 列出参与决策的维度：专业度（expertise）、当前负载（workload）、可用性（availability）；--update-cards 表示决策结果直接回写卡片。

8.2 进度跟踪（Progress Tracking）

# Track and visualize progress
npx ruv-swarm github board-progress \
  --show "burndown,velocity,cycle-time" \
  --time-period "sprint" \
  --export-metrics

支持展示燃尽图（burndown）、速率（velocity）、周期时间（cycle-time），统计窗口按“sprint”（--time-period "sprint"），并可用 --export-metrics 导出指标数据供外部分析。

8.3 智能移动卡片（Smart Card Movement）

# Intelligent card state transitions
npx ruv-swarm github board-smart-move \
  --rules '{
    "auto-progress": "when:all-subtasks-done",
    "auto-review": "when:tests-pass",
    "auto-done": "when:pr-merged"
  }'

--rules 声明条件触发的状态迁移：所有子任务完成 → 自动推进（auto-progress）；测试通过 → 自动进 Review；PR 合并 → 自动标记 Done。这类规则把“人在 GitHub 上手动拖卡片”的动作收敛为事件驱动，是双向同步模式下看板保持“真值”的关键。

9. 卡片操作命令族

9.1 从 Issue 批量建卡

# Convert issues to project cards using gh CLI
# List issues with label
ISSUES=$(gh issue list --label "enhancement" --json number,title,body)

# Add issues to project
echo "$ISSUES" | jq -r '.[].number' | while read -r issue; do
  gh project item-add $PROJECT_ID --owner @me --url "https://github.com/$GITHUB_REPOSITORY/issues/$issue"
done

# Process with swarm
npx ruv-swarm github board-import-issues \
  --issues "$ISSUES" \
  --add-to-column "Backlog" \
  --parse-checklist \
  --assign-agents

流程分三步：先用 gh issue list 按 label（如 enhancement）取 Issue 清单；再用 gh project item-add 逐个把 Issue URL 挂进项目（注意这里依赖环境变量 GITHUB_REPOSITORY，通常在 GitHub Actions 上下文或由本地 gh 环境提供）；最后 board-import-issues 让蜂群接管处理：把卡片放进 Backlog 列、解析 Issue 正文中的 checklist、并按映射规则分配代理。

9.2 批量操作（Bulk Operations）

# Bulk card operations
npx ruv-swarm github board-bulk \
  --filter "status:blocked" \
  --action "add-label:needs-attention" \
  --notify-assignees

按 status:blocked 过滤出阻塞卡片，批量打 needs-attention 标签并通知负责人——适合定期巡检“卡在 Blocked 列的任务”。

9.3 卡片模板（Card Templates）

# Create cards from templates
npx ruv-swarm github board-template \
  --template "feature-development" \
  --variables '{
    "feature": "User Authentication",
    "priority": "high",
    "agents": ["architect", "coder", "tester"]
  }' \
  --create-subtasks

基于 feature-development 模板与变量（功能名、优先级、代理名单）批量生成卡片，--create-subtasks 会按模板结构拆出子任务，与第 8.3 节的 “all-subtasks-done” 自动推进规则形成闭环。

10. 高级同步：多板、跨组织、外部工具

10.1 多看板同步

# Sync across multiple boards
npx ruv-swarm github multi-board-sync \
  --boards "Development,QA,Release" \
  --sync-rules '{
    "Development->QA": "when:ready-for-test",
    "QA->Release": "when:tests-pass"
  }'

--sync-rules 声明板间流转条件：Development 的任务满足 ready-for-test 后流入 QA 板；QA 板满足 tests-pass 后流入 Release 板。适合“开发/测试/发布”分板管理的大型团队。

10.2 跨组织同步

# Sync boards across organizations
npx ruv-swarm github cross-org-sync \
  --source "org1/Project-A" \
  --target "org2/Project-B" \
  --field-mapping "custom" \
  --conflict-resolution "source-wins"

支持以 org/Project 形式指定源/目标板，--field-mapping "custom" 使用自定义字段映射，--conflict-resolution "source-wins" 规定冲突时以源板为准。

10.3 外部工具集成

# Sync with external tools
npx ruv-swarm github board-integrate \
  --tool "jira" \
  --mapping "bidirectional" \
  --sync-frequency "5m" \
  --transform-rules "custom"

技能文档给出了与 Jira 的双向集成示例：每 5 分钟同步一次（--sync-frequency "5m"），并应用自定义转换规则处理两套系统间的字段差异。

11. 可视化与报表

11.1 看板分析（Board Analytics）

# Generate board analytics using gh CLI data
# Fetch project data
PROJECT_DATA=$(gh project item-list $PROJECT_ID --owner @me --format json)

# Get issue metrics
ISSUE_METRICS=$(echo "$PROJECT_DATA" | jq -r '.items[] | select(.content.type == "Issue")' | \
  while read -r item; do
    ISSUE_NUM=$(echo "$item" | jq -r '.content.number')
    gh issue view $ISSUE_NUM --json createdAt,closedAt,labels,assignees
  done)

# Generate analytics with swarm
npx ruv-swarm github board-analytics \
  --project-data "$PROJECT_DATA" \
  --issue-metrics "$ISSUE_METRICS" \
  --metrics "throughput,cycle-time,wip" \
  --group-by "agent,priority,type" \
  --time-range "30d" \
  --export "dashboard"

先由 gh project item-list 拉取项目条目，再用 gh issue view 补齐每个 Issue 的 createdAt / closedAt / labels / assignees（用于计算周期时间与吞吐），最后交给 board-analytics 计算 throughput、cycle-time、WIP 三项指标，按 agent/priority/type 分组，回看 30 天，导出为 dashboard 格式。

11.2 自定义仪表盘

// Dashboard configuration
{
  "dashboard": {
    "widgets": [
      {
        "type": "chart",
        "title": "Task Completion Rate",
        "data": "completed-per-day",
        "visualization": "line"
      },
      {
        "type": "gauge",
        "title": "Sprint Progress",
        "data": "sprint-completion",
        "target": 100
      },
      {
        "type": "heatmap",
        "title": "Agent Activity",
        "data": "agent-tasks-per-day"
      }
    ]
  }
}

仪表盘由三种 widget 组成：按日完成量的折线图、以 100 为目标的冲刺进度仪表、代理活动热力图（按天统计每代理任务量）。

11.3 报表分发

# Generate reports
npx ruv-swarm github board-report \
  --type "sprint-summary" \
  --format "markdown" \
  --include "velocity,burndown,blockers" \
  --distribute "slack,email"

生成 sprint-summary 类型、markdown 格式的报表，内容包含 velocity、burndown、blockers，并可分发到 Slack 与邮件。

12. 与工作流集成：冲刺、里程碑、发布

# Manage sprints with swarms
npx ruv-swarm github sprint-manage \
  --sprint "Sprint 23" \
  --auto-populate \
  --capacity-planning \
  --track-velocity

--auto-populate 自动把看板任务填入冲刺、--capacity-planning 做容量规划、--track-velocity 跟踪速率。

# Track milestone progress
npx ruv-swarm github milestone-track \
  --milestone "v2.0 Release" \
  --update-board \
  --show-dependencies \
  --predict-completion

里程碑跟踪：联动看板更新、展示依赖关系、并基于历史速率预测完成时间。

# Plan releases using board data
npx ruv-swarm github release-plan-board \
  --analyze-velocity \
  --estimate-completion \
  --identify-risks \
  --optimize-scope

发布规划基于看板数据：分析速率、估算完成时间、识别风险、优化发布范围。

13. 团队协作命令

# Distribute work among team
npx ruv-swarm github board-distribute \
  --strategy "skills-based" \
  --balance-workload \
  --respect-preferences \
  --notify-assignments

按技能匹配（skills-based）分配工作，同时平衡负载、尊重个人偏好并通知被分配者。

# Generate standup reports
npx ruv-swarm github standup-report \
  --team "frontend" \
  --include "yesterday,today,blockers" \
  --format "slack" \
  --schedule "daily-9am"

为 frontend 团队生成“昨日/今日/阻塞”三段式站会报告，推送到 Slack，计划为每天 9 点。

# Coordinate reviews via board
npx ruv-swarm github review-coordinate \
  --board "Code Review" \
  --assign-reviewers \
  --track-feedback \
  --ensure-coverage

以 “Code Review” 板为中心协调评审：自动指派评审人、跟踪反馈、确保覆盖。

14. 最佳实践（技能文档原文要点）

技能文档给出的三条实践主线：

1. 看板组织：列定义清晰、标签体系统一、定期梳理看板（grooming）、用自动化规则代替手工拖卡；
2. 数据完整性：对双向同步做校验、定义冲突解决策略、保留审计轨迹、定期备份；
3. 团队采用：准备培训材料、明确工作流、定期回顾、建立反馈闭环。

15. 故障排查与运维命令

15.1 诊断同步问题

# Diagnose sync problems
npx ruv-swarm github board-diagnose \
  --check "permissions,webhooks,rate-limits" \
  --test-sync \
  --show-conflicts

依次检查权限、Webhook、API 速率限制，执行一次测试同步，并列出当前冲突项。

15.2 性能优化

# Optimize board performance
npx ruv-swarm github board-optimize \
  --analyze-size \
  --archive-completed \
  --index-fields \
  --cache-views

分析看板规模、归档已完成卡片、为字段建索引、缓存视图，用于大看板场景的提速。

15.3 数据恢复

# Recover board data
npx ruv-swarm github board-recover \
  --backup-id "2024-01-15" \
  --restore-cards \
  --preserve-current \
  --merge-conflicts

从指定备份恢复卡片，保留当前数据并对冲突做合并处理。

16. 示例场景与 KPI

16.1 三种典型看板

# Setup agile board
npx ruv-swarm github agile-board \
  --methodology "scrum" \
  --sprint-length "2w" \
  --ceremonies "planning,review,retro" \
  --metrics "velocity,burndown"

Scrum 型看板：两周冲刺，启用规划/评审/回顾三个仪式，跟踪速率与燃尽。

# Setup kanban board
npx ruv-swarm github kanban-board \
  --wip-limits '{
    "In Progress": 5,
    "Review": 3
  }' \
  --cycle-time-tracking \
  --continuous-flow

看板流（Kanban）：给 “In Progress” 设 WIP 上限 5、“Review” 上限 3，跟踪周期时间、按持续流动模式运行。

# Setup research board
npx ruv-swarm github research-board \
  --phases "ideation,research,experiment,analysis,publish" \
  --track-citations \
  --collaborate-external

研究型看板：五阶段流水线（构思→研究→实验→分析→发表），跟踪引用并支持外部协作。

16.2 指标与 KPI

# Track board performance
npx ruv-swarm github board-kpis \
  --metrics '[
    "average-cycle-time",
    "throughput-per-sprint",
    "blocked-time-percentage",
    "first-time-pass-rate"
  ]' \
  --dashboard-url

跟踪平均周期时间、每冲刺吞吐、阻塞时长占比、一次通过率四类 KPI。

# Track team performance
npx ruv-swarm github team-metrics \
  --board "Development" \
  --per-member \
  --include "velocity,quality,collaboration" \
  --anonymous-option

对 “Development” 板按成员维度输出速率、质量、协作指标，并保留匿名选项（--anonymous-option），兼顾数据透明与个人意愿。

17. 在 ruflo 仓库中的位置：技能族、MCP 工具与关联技能

从源码结构看，该技能在 ruflo 的生态中由三部分组成：

1. 技能文件：.agents/skills/agent-project-board-sync/SKILL.md，即本文主体。其 frontmatter 声明了 12 个工具权限，其中 mcp__claude-flow__swarm_init、mcp__claude-flow__agent_spawn、mcp__claude-flow__task_orchestrate、mcp__claude-flow__swarm_status、mcp__claude-flow__memory_usage 是 ruflo MCP Server 的蜂群协调原语，mcp__claude-flow__github_repo_analyze、mcp__claude-flow__github_pr_manage、mcp__claude-flow__github_issue_track、mcp__claude-flow__github_metrics、mcp__claude-flow__workflow_create、mcp__claude-flow__workflow_execute 则覆盖 GitHub 分析与工作流编排——也就是说，技能在执行时既可走 gh + ruv-swarm 命令行，也可调用 MCP 工具完成同样的协调动作。

2. 初始化引导集成：v3/@claude-flow/cli/src/init/executor.ts 在生成项目引导文档时把 project-board-sync 列为内置协调技能之一，并在 同文件 的 “Optional Integrations” 中给出 ruv-swarm MCP Server 的接入方式：

   claude mcp add ruv-swarm -- npx -y ruv-swarm mcp start
   

   这解释了技能文档中大量 npx ruv-swarm github ... 命令的运行前提：ruv-swarm 以 npx 临时拉取或作为已注册 MCP Server 常驻运行。

3. 关联技能：文档尾部 “See also” 指向的两篇姊妹技能，在本仓库中的实际路径为 .agents/skills/agent-swarm-issue/SKILL.md（swarm-issue，把 GitHub Issue 转成蜂群任务）与 .agents/skills/agent-multi-repo-swarm/SKILL.md（multi-repo-swarm，跨仓库蜂群）。其中 swarm-issue 技能提供了与本技能直接衔接的命令：

   # Sync with project board
   npx ruv-swarm github issue-board-sync \
     --project "Development" \
     --column-mapping '{
       "To Do": "pending",
       "In Progress": "active",
       "Done": "completed"
     }'
   

   即“Issue → 蜂群任务”（swarm-issue 负责）与“蜂群任务 → 项目看板”（本技能负责）构成完整链路：Issue 侧完成分解与代理分配，看板侧完成可视化、状态回流与报表。

18. 小结：适用前提与落地清单

• 前提：已安装并认证 gh CLI（gh auth status）、对目标 Project 有读写权限、当前目录为目标 git 仓库；使用 ruv-swarm 命令族时需能访问 npx 包源，或按仓库引导文档将其注册为 MCP Server；
• 落地顺序：board-init 建板并建 “Swarm Status” 字段 → 配置 .github/board-sync.yml 的状态/代理/优先级/自定义字段映射 → board-sync 或 board-realtime 启动同步 → board-smart-move 与 board-auto-assign 上自动化规则 → 用 board-analytics、board-report、board-kpis 建立度量闭环；
• 排障入口：同步异常先跑 board-diagnose --check "permissions,webhooks,rate-limits"，大板性能问题用 board-optimize 归档与缓存，数据事故走 board-recover 备份恢复；
• 边界说明：本文所有命令与配置均以技能文档 SKILL.md 为规范来源，其中 ruv-swarm 的子命令语义（如 --sync-mode、--rules）按该文档声明描述；实际取值范围与默认行为以所安装的 ruv-swarm 版本帮助输出为准。