# Issue 批量自动分拣完整工作流示例

**场景**：仓库 `z2_cc/gitlink-cli` 积压了一批未分类的 open Issue，需要批量分流：自动判定类别、打标签、指派责任人、添加引导评论。

> 本示例遵循 SKILL.md 的核心原则：**语义分类为主、建议优先确认后写入、幂等、批量为主**。所有写入操作都经过「方案→确认→dry-run→执行」四步。

## 前置条件

- `gitlink-cli` 已安装并登录（`gitlink-cli auth status` 正常）
- 对目标仓库有写入权限
- 已阅读 [`../../gitlink-shared/SKILL.md`](../../gitlink-shared/SKILL.md)

---

## Step 1：解析 ID（建立 名称→ID 映射）

```bash
gitlink-cli label +list --format json
gitlink-cli label +assigners --format json
gitlink-cli label +priorities --format json
```

**`label +list` 输出示例：**
```json
{
  "ok": true,
  "data": { "labels": [
    {"id": 1, "name": "bug"},
    {"id": 2, "name": "enhancement"},
    {"id": 3, "name": "documentation"},
    {"id": 4, "name": "question"},
    {"id": 5, "name": "performance"}
  ]}
}
```

**`label +assigners` 输出示例：**
```json
{
  "ok": true,
  "data": { "assigners": [
    {"id": 101, "login": "alice", "name": "前端组"},
    {"id": 102, "login": "bob", "name": "后端组"},
    {"id": 103, "login": "carol", "name": "文档组"}
  ]}
}
```

→ 建立映射：标签 `bug→1, enhancement→2, question→4`；指派人 `alice→101, bob→102, carol→103`。

## Step 2：取未分拣 Issue（客户端筛掉已打标签的）

```bash
gitlink-cli issue +list --owner z2_cc --repo gitlink-cli --state open --format json
```

筛出**尚未打标签**的 3 个（已分类的跳过，保证幂等）：

| number | subject | labels |
|--------|---------|--------|
| 12 | 登录后页面白屏，控制台报 500 | （空） |
| 13 | 希望能支持暗黑模式 | （空） |
| 14 | 请问怎么配置 webhook？ | （空） |

## Step 3：语义分析（逐个读详情）

```bash
gitlink-cli issue +view --owner z2_cc --repo gitlink-cli --number 12 --format json
```

```json
{
  "ok": true,
  "data": { "issue": {
    "number": 12,
    "subject": "登录后页面白屏，控制台报 500",
    "description": "输入账号密码点登录后页面直接白屏，浏览器控制台显示 500 Internal Server Error。Chrome 120 / macOS。"
  }}
}
```

**语义判定（注意 #12 没有「bug」字眼，靠语义识别）：**
- **#12**：500 + 阻断登录主流程 → **Bug**；500 是服务端响应 → 后端 bob
- **#13**：「希望支持暗黑模式」→ **功能需求 enhancement**；UI/样式 → 前端 alice
- **#14**：「请问怎么配置 webhook」→ **问题咨询 question**；答疑 → 文档 carol

## Step 4：出「分拣方案表」（建议，不写入，等用户确认）

```
分拣方案（共 3 个 Issue，请确认后我将 dry-run 预览）：

| #   | 标题                  | 类别     | 标签(id)        | 责任人(id)   |
|-----|----------------------|----------|-----------------|-------------|
| 12  | 登录后白屏 500        | Bug      | bug(1)          | bob(102)    |
| 13  | 希望支持暗黑模式      | Feature  | enhancement(2)  | alice(101)  |
| 14  | 请问怎么配置 webhook  | Question | question(4)     | carol(103)  |

引导评论将分别请求：#12 复现步骤/后端日志；#13 主题范围确认；#14 直接答复+文档化。
确认执行吗？（回复「确认」我进入 dry-run 预览；如需调整请指出）
```

> ⏸️ **停在此处等用户确认。禁止用 `--yes` 自行推进。**

## Step 5：打标签（用户确认方案后）

> ⚠️ 各 Issue 标签不同，**用 Raw API 逐个打**（实测 `issue +update --label` 不可用、`+batch-update --label` 是集合式，见 SKILL.md 红线）。务必回带 `subject`/`description` 防清空。

```bash
# #12 → bug(1)
gitlink-cli api PATCH /:owner/:repo/issues/12 --body '{
  "issue_tag_ids": [1], "subject": "登录后页面白屏，控制台报 500",
  "description": "输入账号密码点登录后页面直接白屏，控制台显示 500 Internal Server Error。Chrome 120/macOS。"
}'
# #13 → enhancement(2)
gitlink-cli api PATCH /:owner/:repo/issues/13 --body '{
  "issue_tag_ids": [2], "subject": "希望能支持暗黑模式", "description": "希望加暗黑主题切换。"
}'
# #14 → question(4)
gitlink-cli api PATCH /:owner/:repo/issues/14 --body '{
  "issue_tag_ids": [4], "subject": "请问怎么配置 webhook？", "description": "想把推送事件通知到群机器人。"
}'
```

> 多个 Issue **共用同一标签**时，可改用批量：`issue +batch-update --numbers <a,b,c> --label <单个id> --dry-run` → 去 `--dry-run`。
> 指派人：`issue +update --number <n> --assignee <user_id>`（`user_id` 来自 `label +assigners`；无可指派人则留空）。

**验证打标结果：**

```bash
gitlink-cli issue +view --number 12 --format json   # data.issue.tags 应为 [{"id":1,"name":"bug"}]
```

## Step 6：引导评论（逐个添加）

```bash
# #12 Bug
gitlink-cli issue +comment --owner z2_cc --repo gitlink-cli --number 12 \
  --body "已自动分拣为 **Bug**，转交 @bob。为加快定位，请补充：运行环境、稳定复现步骤、浏览器控制台与后端对应时间点的报错日志。"

# #13 Feature
gitlink-cli issue +comment --owner z2_cc --repo gitlink-cli --number 13 \
  --body "已自动分拣为 **enhancement**，转交 @alice。落地前请确认范围：① 全局暗黑主题还是特定页面；② 是否跟随系统 prefers-color-scheme；③ 配色基准。"

# #14 Question
gitlink-cli issue +comment --owner z2_cc --repo gitlink-cli --number 14 \
  --body "已自动分拣为 **question**，转交 @carol。快速回答：Webhook 在「仓库设置 → Webhooks」新增，填回调 URL、选触发事件，GitLink 会向该 URL 发 POST。完整字段说明将补充到 docs/。"
```

---

## 命令速览

```bash
# 1. 解析 ID
gitlink-cli label +list --format json
gitlink-cli label +assigners --format json

# 2. 取未分拣 Issue（客户端筛无标签的）
gitlink-cli issue +list --state open --format json

# 3. 语义分析
gitlink-cli issue +view --number <n> --format json

# 4. 出方案表 → 用户确认（不写入）

# 5. 打标签：各 Issue 不同标签 → 逐个 Raw API（issue_tag_ids 整体替换）
gitlink-cli api PATCH /:owner/:repo/issues/<n> --body '{"issue_tag_ids":[<id>],"subject":"<原>","description":"<原>"}'
#    多 Issue 共用同一标签 → 批量（先 --dry-run）
gitlink-cli issue +batch-update --numbers <a,b,c> --label <单个id> --dry-run

# 6. 引导评论
gitlink-cli issue +comment --number <n> --body "<评论>"
```

## 退化场景：单个 Issue

只需分拣一个 Issue 时：

```bash
# 打标签（Raw API；+update --label 实测不可用）
gitlink-cli api PATCH /:owner/:repo/issues/<n> --body '{"issue_tag_ids":[<id>],"subject":"<原标题>","description":"<原描述>"}'
# 指派人（可选）
gitlink-cli issue +update --number <n> --assignee <user_id>
# 引导评论
gitlink-cli issue +comment --number <n> --body "<评论>"
```

同样遵循「方案→确认→执行」，不要直接 `--yes`。
