# 多仓库协同工作流 — 端到端示例

**场景**：组织维护多个相关仓库（如 `z2_cc/gitlink-cli` 和 `z2_cc/gitlink-bisync`），希望把它们视为一个整体，统一追踪 Issue、聚合 PR 状态、协调发版节奏。

## 前置条件

- `gitlink-cli` 已安装并登录（`gitlink-cli auth status`）
- 通过环境变量 `REPOS` 指定要协同的仓库列表
- `jq` 已安装（用于 JSON 解析）
- 离线/未认证时脚本会优雅降级（采集失败 → 写空 JSON → 仍生成报告）

## 环境变量

```bash
# 单仓库（默认）
export REPOS="z2_cc/gitlink-cli"

# 多仓库协同
export REPOS="z2_cc/gitlink-cli,z2_cc/gitlink-bisync"

# dry-run（默认 true，不实际创建 Release）
export DRY_RUN=true
```

## 工作流步骤

### Step 1：统一 Issue 追踪（Phase 1）

```bash
# 遍历 REPOS 中每个仓库采集 open 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 \
        > "_output/issues-${owner}-${repo}.json"
done
```

**输出示例（issues-z2_cc-gitlink-cli.json）：**
```json
{
  "ok": true,
  "data": {
    "issues": [
      {"number": 42, "subject": "登录页面 500 报错", "state": 1, "created_at": "2026-06-20"},
      {"number": 43, "subject": "建议增加 webhook 投递监控", "state": 1, "created_at": "2026-06-22"}
    ]
  }
}
```

**输出示例（issues-z2_cc-gitlink-bisync.json）：**
```json
{
  "ok": true,
  "data": {
    "issues": [
      {"number": 7, "subject": "登录接口 500 报错", "state": 1, "created_at": "2026-06-21"}
    ]
  }
}
```

**AI 分析逻辑：**
```
按仓库分组：
  z2_cc/gitlink-cli       → 2 个 open Issue
  z2_cc/gitlink-bisync    → 1 个 open Issue

跨仓库关联（标题关键词相似度）：
  #42 (cli) "登录页面 500 报错"  ↔  #7 (bisync) "登录接口 500 报错"
  关键词重叠 = {登录, 500, 报错} → 3 个重叠 → 高度疑似跨仓库关联 Issue
```

**Expected:** `_output/issues-<owner>-<repo>.json` 每仓库一份；`issue-tracker.md` 含分组表 + 关联表。

### Step 2：PR 状态看板（Phase 2）

```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
```

**AI 分析逻辑：**
```
PR 汇总：
  z2_cc/gitlink-cli       打开 4 / 已合并 12 → 合并率 75%  🟢
  z2_cc/gitlink-bisync    打开 8 / 已合并  2 → 合并率 20%  🔴

长期未合并（> 14 天）：
  PR #15 (bisync) "重构同步引擎" 上次更新 32 天前 → 🔴
  PR #11 (cli)    "添加 wiki 模板" 上次更新 21 天前 → 🟡
```

**Expected:** `pr-dashboard.md` 含汇总表 + 长期未合并 PR 排行 + 各仓库明细。

### Step 3：Release 协调发布（Phase 3）

```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
```

**输出示例（releases-z2_cc-gitlink-cli.json）：**
```json
{
  "ok": true,
  "data": {
    "releases": [
      {"tag_name": "v0.3.0", "name": "v0.3.0", "created_at": "2026-06-24"}
    ]
  }
}
```

**输出示例（releases-z2_cc-gitlink-bisync.json）：**
```json
{
  "ok": true,
  "data": {
    "releases": [
      {"tag_name": "v0.1.2", "name": "v0.1.2", "created_at": "2026-05-10"}
    ]
  }
}
```

**AI 分析结果：**
```
版本对齐分析：
  z2_cc/gitlink-cli       v0.3.0  ✅
  z2_cc/gitlink-bisync    v0.1.2  🔴 主版本 0.1 < 中位数主版本 0.x？ 同主版本
  （主版本均为 0，落后判断依赖次版本差异）

协调发布建议：
  1. z2_cc/gitlink-bisync 落后较多，建议优先发版追赶 cli
  2. dry-run 模式下不调用 release +create，需人工确认后实际发版
```

```bash
# dry-run：只生成建议（默认）
echo "[DRY-RUN] 仅生成 release-coordination.md，未创建任何 Release"

# 实际发版需 DRY_RUN=false 且由人工逐仓库执行（脚本不会自动批量 create）
```

**Expected:** `release-coordination.md` 含各仓库版本表 + 对齐分析 + 协调建议列表；不实际创建 Release。

## 完整命令速览

```bash
# 一键全流程（dry-run，多仓库）
REPOS="z2_cc/gitlink-cli,z2_cc/gitlink-bisync" bash skills/gitlink-multi-repo-coordination/scripts/multi-repo-full.sh

# 等价的手动步骤
REPOS="z2_cc/gitlink-cli,z2_cc/gitlink-bisync"
bash skills/gitlink-multi-repo-coordination/scripts/01-unified-issue-tracker.sh
REPOS=$REPOS bash skills/gitlink-multi-repo-coordination/scripts/02-pr-dashboard.sh
REPOS=$REPOS bash skills/gitlink-multi-repo-coordination/scripts/03-release-coordination.sh
node skills/gitlink-multi-repo-coordination/scripts/dashboard-gen.js \
    skills/gitlink-multi-repo-coordination/scripts/_output
```

## 注意事项

- 所有写操作（特别是 `release +create`）默认 dry-run，确认后通过 `DRY_RUN=false` 由人工逐仓库执行
- 跨仓库 Issue 关联仅基于标题关键词相似度，最终结论建议人工复核
- 未认证/无网络时脚本会优雅降级：采集失败写空 JSON，聚合引擎仍能跑完产出空报告
- 本机 Windows Node 不识别 MSYS `/c/...` 路径，`dashboard-gen.js` 全程使用相对路径
