---
name: gitlink-multi-repo-coordination
version: 1.0.0
description: "多仓库协同：统一 Issue 追踪 → PR 状态看板 → Release 协调发布。跨多个仓库聚合 Issue/PR/Release 数据，生成协同看板与协调发版建议。"
metadata:
  requires:
    bins: ["gitlink-cli", "jq"]
  cliHelp: "gitlink-cli issue --help / gitlink-cli pr --help / gitlink-cli release --help"
---

# gitlink-multi-repo-coordination（多仓库协同）

> **前置条件：** 先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md) 了解认证、全局参数和 API 注意事项。
>
> **CRITICAL — 所有 GitLink 操作必须使用 `gitlink-cli`，禁止使用 `gh`（GitHub CLI）操作 GitLink 资源。**

## 说明

本 Skill 面向**跨多仓库协同**场景，把分散在多个 `owner/repo` 的 Issue、PR、Release 数据聚合为统一看板，并给出协调发版建议：

1. **统一 Issue 追踪** — 遍历多个仓库聚合打开的 Issue，按仓库分组、按优先级/标签汇总，识别跨仓库重复/关联 Issue
2. **PR 状态看板** — 聚合各仓库打开/已合并 PR，识别长期未合并 PR
3. **Release 协调发布** — 汇总各仓库最新版本，做版本对齐分析，给出协调发布建议（dry-run 下只生成建议，不真正发版）

**与单仓库 Skill 的区别：** 单仓库 Skill（issue-triage、project-health、release-auto）只看一个仓库；本工作流把多个仓库视为一个整体协同视图。

---

## 三阶段工作流总览

```mermaid
flowchart LR
    A[多仓库列表 REPOS] --> B[Phase 1: 统一 Issue 追踪]
    B --> C[Phase 2: PR 状态看板]
    C --> D[Phase 3: Release 协调发布]

    subgraph B[Phase 1: 统一 Issue 追踪]
        B1[遍历每个仓库采集 open Issue] --> B2[按仓库分组聚合]
        B2 --> B3[标题相似度识别跨仓库关联]
        B3 --> B4[生成统一 Issue 看板]
    end

    subgraph C[Phase 2: PR 看板]
        C1[遍历每个仓库采集 open/merged PR] --> C2[聚合 PR 状态]
        C2 --> C3[按更新时间识别长期未合并]
        C3 --> C4[生成 PR 看板]
    end

    subgraph D[Phase 3: Release 协调]
        D1[遍历每个仓库采集 release] --> D2[版本对齐分析]
        D2 --> D3[识别落后/可同步发版仓库]
        D3 --> D4[生成协调发布建议]
    end
```

---

## Phase 1：统一 Issue 追踪

### 命令清单

```bash
# 遍历 REPOS 中每个仓库采集打开的 Issue
for repo_full in $(echo $REPOS | tr ',' ' '); do
    owner=${repo_full%/*}
    repo=${repo_full#*/}
    gitlink-cli issue +list --owner "$owner" --repo "$repo" --state open --format json
done
```

### 聚合逻辑

- 按仓库分组展示打开的 Issue
- 按 Issue 数量/标签汇总各仓库状态
- 通过**标题关键词相似度**识别跨仓库可能重复/关联的 Issue（如多仓库都出现"登录失败"类 Issue）
- 输出 `issue-tracker.md`

---

## Phase 2：PR 状态看板

### 命令清单

```bash
for repo_full in $(echo $REPOS | tr ',' ' '); do
    owner=${repo_full%/*}
    repo=${repo_full#*/}
    gitlink-cli pr +list --owner "$owner" --repo "$repo" --state open   --format json
    gitlink-cli pr +list --owner "$owner" --repo "$repo" --state merged --format json
done
```

### 聚合逻辑

- 统计每个仓库打开 PR / 已合并 PR 数量
- 按 `updated_at` 排序识别长期未合并 PR（默认阈值 > 14 天 🔴）
- 汇总到 PR 看板表（仓库 | 标题 | 状态 | 更新时间）
- 输出 `pr-dashboard.md`

---

## Phase 3：Release 协调发布

### 命令清单

```bash
for repo_full in $(echo $REPOS | tr ',' ' '); do
    owner=${repo_full%/*}
    repo=${repo_full#*/}
    gitlink-cli release +list --owner "$owner" --repo "$repo" --format json
done
```

### 协调逻辑

- 提取每个仓库最新 `tag_name`，按语义化版本比较
- 标记版本**落后**的仓库（最新版本明显低于中位数）
- 识别**可同步发版**的仓库组（最新版本相近、上次发版时间相近）
- dry-run 下只生成协调发布建议报告 `release-coordination.md`，**不调用 `release +create`**

---

## 可复现脚本

本 Skill 提供可直接执行的 Bash 脚本，位于 `scripts/` 目录：

| 脚本 | 功能 | 使用方式 |
|------|------|----------|
| `01-unified-issue-tracker.sh` | Phase 1 统一 Issue 追踪 | `REPOS=z2_cc/gitlink-cli bash 01-unified-issue-tracker.sh` |
| `02-pr-dashboard.sh` | Phase 2 PR 看板 | `REPOS=z2_cc/gitlink-cli bash 02-pr-dashboard.sh` |
| `03-release-coordination.sh` | Phase 3 Release 协调 | `REPOS=z2_cc/gitlink-cli bash 03-release-coordination.sh` |
| `multi-repo-full.sh` | 全流程串联 + HTML 报告 | `REPOS=z2_cc/gitlink-cli bash multi-repo-full.sh` |
| `dashboard-gen.js` | 多仓库聚合引擎（Node） | 由 full 脚本调用 |

### 环境变量

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `REPOS` | `z2_cc/gitlink-cli` | 逗号分隔的 `owner/repo` 列表 |
| `DRY_RUN` | `true` | dry-run 模式（不实际创建 Release） |

```bash
# Dry-run（默认，安全）—— 单仓库
REPOS="z2_cc/gitlink-cli" bash scripts/multi-repo-full.sh

# 多仓库协同
REPOS="z2_cc/gitlink-cli,z2_cc/gitlink-bisync" DRY_RUN=true bash scripts/multi-repo-full.sh
```

---

## 注意事项

1. **dry-run 优先**：Phase 3 的 `release +create` 默认不执行，dry-run=false 时才实际发版
2. **Token 有效**：运行前确认 `gitlink-cli auth status` 返回正常；未认证时脚本会优雅降级（采集失败 → 写空 JSON → 仍生成报告）
3. **离线兼容**：本机 Windows Node 不识别 MSYS 绝对路径，因此 `dashboard-gen.js` 全程使用 `path.join(dir, ...)` 相对路径
4. **相似度判断为辅助**：跨仓库 Issue 关联仅基于标题关键词相似度，最终结论建议人工复核
5. **输出文件**：所有 JSON 数据保存到 `scripts/_output/` 目录供审计
