---
name: gitlink-issue-triage
version: 1.2.0
description: "当用户需要批量处理新提交的 GitLink Issue（自动分类、打标签、分配责任人、添加引导评论）时触发。适用于 Issue 积压无人分流、新 Issue 缺少分类标签、需要按类别指派维护者等场景。"
metadata:
  requires:
    bins: ["gitlink-cli"]
  cliHelp: "gitlink-cli issue --help"
---

# gitlink-issue-triage（Issue 自动分拣）

**CRITICAL — 开始前必须先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md)，其中包含认证、权限处理和 API 注意事项。**
**CRITICAL — 所有写入/删除操作前，务必先确认用户意图；分拣属于批量写入，必须先出方案→用户确认→dry-run 预览→再执行。**
**CRITICAL — GitLink 操作只能用 `gitlink-cli`。禁止用 `gh`（GitHub CLI）操作 GitLink 资源。`gh` 仅适用于 GitHub 平台。**

## 核心原则

1. **语义分类为主，关键词表为辅**：你是 AI Agent，价值在于读懂 Issue 意图（如「登录后白屏、控制台报 500」即使没有「bug」字眼也应判为 Bug）。下方关键词表只是兜底/加速，不要退化成正则匹配。
2. **建议优先，确认后写入**：先输出「分拣方案表」给用户确认，**禁止未经确认直接打标签/改指派人**。尤其禁止用 `--yes` 绕过确认，除非用户明确说「直接应用/不用确认」。
3. **幂等**：只处理「尚未分拣」的 Issue（无标签或仅有默认标签），避免对已分拣 Issue 重复操作。
4. **打标签用 Raw API，批量仅限同标签**：实测 `issue +update --label` 不可用、`+batch-update --label` 是集合式（整组标签打到每个 Issue），故各 Issue 不同标签时用 Raw API `issue_tag_ids`（详见 Step 5）；仅当多 Issue 共用同一标签时才用 `+batch-update`。

## 工作流概览

| 阶段 | 操作 | 命令 |
|------|------|------|
| ① 解析 ID（必做前置） | 取仓库标签/可指派人/优先级，建立 名称→ID 映射 | `label +list` / `label +assigners` / `label +priorities` |
| ② 取未分拣 Issue | 拉取 open Issue，客户端筛掉已打标签的 | `issue +list` |
| ③ 语义分析 | 逐个读标题+描述，判类别/标签/责任人/评论 | `issue +view` |
| ④ 出方案 | 输出「分拣方案表」，等用户确认 | （无写入） |
| ⑤ 打标签 | 用户确认后，逐 Issue 用 Raw API 打标签（不同标签）；同标签可批量 | `api PATCH .../issues/:n` / `+batch-update` |
| ⑥ 引导评论 | 为每个 Issue 添加分类引导评论 | `issue +comment` |

---

## 详细工作流

### Step 1：解析 ID（**必做前置，切勿跳过**）

GitLink 的标签、指派人、优先级参数都吃 **ID 而非名称**。先拉取并建立映射：

```bash
# 标签：name → id（返回在 data.issue_tags[]；标签名因仓库而异，如某仓库为 缺陷/功能/疑问/文档…）
gitlink-cli label +list --format json

# 可指派人：login → id（如 alice→101）
gitlink-cli label +assigners --format json

# 优先级：name → id（数值因仓库而异，如某仓库为 低→1/正常→2/高→3/紧急→4，以实际输出为准）
gitlink-cli label +priorities --format json
```

> 没有 ID 映射就无法正确执行 Step ⑤⑥。若目标标签不存在，见 Step 4「补建标签」。

### Step 2：取未分拣 Issue（幂等筛选）

```bash
# 拉取所有 open Issue
gitlink-cli issue +list --state open --format json
```

筛选规则（客户端过滤）：**保留尚未打标签的 Issue**（`tags` 字段为空），跳过已有分类标签的，避免重复分拣。

### Step 3：语义分析

对每个待分拣 Issue：

```bash
gitlink-cli issue +view --number <issue_number> --format json
```

读取 `subject` + `description`，按下方「分类规则参考」判断类别、推荐标签、推荐责任人角色、引导评论要点。

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

输出一张表给用户确认，**此阶段不执行任何写入**：

```markdown
| # | 标题 | 判定类别 | 标签(id) | 责任人(id) | 评论文案要点 |
|---|------|---------|----------|-----------|-------------|
| 12 | 登录后白屏 500 | Bug | bug(1) | bob(102) | 请补浏览器/复现步骤/后端日志 |
| 13 | 希望支持暗黑模式 | Feature | enhancement(2) | alice(101) | 请确认范围：全局/页面级、是否跟随系统 |
```

**补建标签（可选）**：若方案需要的标签在 `label +list` 中不存在（如缺 `bug`），不要静默跳过，也**不要擅自创建**——在方案表中标注「标签缺失」，待用户确认后用 `gitlink-cli label +create --name bug` 创建，再继续。

**等待用户确认**：用户没说「确认/执行」前，停在 Step 4。**禁止用 `--yes` 自行推进。**

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

> ⚠️ **实测要点（2026-06-15 端到端验证）**：
> - `issue +update --label <id>` **不可用**——CLI 发送单数 `issue_tag_id`，平台忽略，标签打不上。
> - `issue +batch-update --label a,b,c` 是**集合式**：把 `{a,b,c}` 打到 `--numbers` 里**每一个** Issue，**不是**按位置对应。仅适合「多个 Issue 共用同一(组)标签」。
> - 可用的打标签方式是 Raw API 的 `issue_tag_ids`（复数数组）。

**情形 A：各 Issue 标签不同（最常见）→ 逐 Issue 用 Raw API（已验证）：**

```bash
gitlink-cli api PATCH /:owner/:repo/issues/<number> --body '{
  "issue_tag_ids": [<标签id>],
  "subject": "<原标题>",
  "description": "<原描述>"
}'
```

`issue_tag_ids` 是数组，**整体替换**该 Issue 的标签集；务必回带 `subject`/`description`，否则描述会被清空（见 gitlink-shared 已知坑）。

**情形 B：多个 Issue 共用同一标签 → 批量（先 dry-run 再执行）：**

```bash
# dry-run 预览（同一标签打到这批所有 Issue）
gitlink-cli issue +batch-update --numbers <a,b,c> --label <单个id> --dry-run --format json
# 核对后去掉 --dry-run 正式执行
```

**指派人**：`issue +update --number <n> --assignee <user_id>`（`user_id` 来自 `label +assigners`）。若 `label +assigners` 为空（如个人仓库无可指派成员），**留空并在方案表注明**，不要乱指派。

### Step 6：引导评论

为每个 Issue 添加分类引导评论（语气专业，包含分类理由 + 需要补充的信息）：

```bash
gitlink-cli issue +comment --number 12 --body "已自动分拣为 **Bug**，转交 @bob。
为加快定位，请补充：运行环境、复现步骤、浏览器控制台与后端日志。维护者会尽快处理。"
```

---

## 分类规则参考

### 类别判定（语义优先，关键词兜底）

| 类别 | 语义信号 | 关键词兜底 | 建议标签 | 责任人角色 |
|------|---------|-----------|----------|-----------|
| Bug | 运行时报错、崩溃、行为异常、阻断主流程 | 错误/失败/异常/crash/报错/500/白屏 | bug | 后端或前端（按错误来源） |
| 功能需求 | 希望新增能力、改进现有行为 | 建议/希望/需要/feature/支持 | enhancement | PM / 对应模块开发 |
| 文档 | 文档缺失/错误/拼写 | 文档/README/拼写 | documentation | 文档负责人 |
| 问题咨询 | 询问用法、求助 | 请问/怎么/如何/help/question | question | 社区支持 / 文档 |
| 性能 | 慢、卡顿、资源占用 | 慢/卡顿/性能/优化/performance | performance | 核心开发者 |

> 上表「建议标签」是语义类别名，**实际标签名以 `label +list` 为准**——GitLink 默认标签是中文（缺陷/功能/疑问/文档/任务…），需先把类别映射到仓库实际标签的 ID 再打。

### 角色 → 默认责任人映射（需用 `label +assigners` 的实际 ID 替换）

| 角色 | 何时指派 |
|------|---------|
| 后端 | 服务端错误、API、数据库相关 |
| 前端 | UI、样式、浏览器端错误 |
| PM | 需求范围、优先级决策 |
| 文档 | 文档/问答类 |
| 核心开发者 | 性能、架构、安全 |

> 实际指派时，把「角色」替换为 `label +assigners` 中对应的 **user_id**。若角色无对应成员，**留空并在方案表注明**，不要乱指派。

---

## 命令速查

```bash
# 前置：解析 ID
gitlink-cli label +list --format json           # 标签 name→id
gitlink-cli label +assigners --format json      # 可指派人 login→id
gitlink-cli label +priorities --format json     # 优先级 name→id
gitlink-cli label +create --name <name> --color <hex>   # 补建缺失标签（确认后）

# 分拣主体
gitlink-cli issue +list --state open --format json      # 取未分拣（客户端筛 tags 为空的）
gitlink-cli issue +view --number <n> --format json      # 读详情做语义分析（标签字段为 tags）

# 打标签（已验证可用）：
#   - 各 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

gitlink-cli issue +comment --number <n> --body "<引导评论>"   # 引导评论
gitlink-cli issue +update --number <n> --assignee <user_id>   # 指派人（user_id 来自 label +assigners）
```

> ⚠️ `issue +update --label` 与 `+batch-update --label a,b,c`（多标签）均不可靠，详见红线。

---

## Raw API 参考

打标签的**主要可用方式**是 Raw API（Shortcut 的 `--label` 不可靠，见红线）。务必回带 `subject`/`description` 防清空：

```bash
# 打标签（issue_tag_ids 为标签 ID 数组，整体替换该 Issue 标签集）
gitlink-cli api PATCH /:owner/:repo/issues/:number --body '{
  "issue_tag_ids": [<tag_id>, ...],
  "subject": "<原标题>",
  "description": "<原描述>"
}'
```

> 字段说明详见 [`REFERENCE.md`](REFERENCE.md)。

---

## 红线与常见错误

- ❌ **未经用户确认就打标签/指派**——必须方案表→确认→执行。
- ❌ **用 `--yes` 绕过确认门**——除非用户明确要求「直接应用」。
- ❌ **用 `issue +update --label` 打标签**——实测 CLI 发单数 `issue_tag_id` 被平台忽略，标签打不上；改用 Raw API `issue_tag_ids`（Step 5）。
- ❌ **用 `+batch-update --label a,b,c` 给不同 Issue 打不同标签**——它是集合式，会把 {a,b,c} 全打到每个 Issue；仅用于多 Issue 共用同一标签。
- ❌ **把标签名称当 ID 传**——必须先用 `label +list` 解析为 ID（返回在 `data.issue_tags[]`，标签名以实际为准）。
- ❌ **重复分拣已分类 Issue**——Step 2 客户端筛掉 `tags` 非空的。
- ❌ **用 `gh` 操作 GitLink**——只用 `gitlink-cli`。
- 所有命令加 `--format json` 便于解析；输出为 `{ok, data, meta}` envelope。

## 注意事项

- 分拣是批量写入，评论会通知 Issue 相关人，内容请专业、可操作。
- `issue +list` 的 `--state` 仅影响统计计数，列表可能含全部状态，需客户端二次过滤。
- 若 Issue 描述信息不足以判定类别，在方案表标注「信息不足，建议先发评论索取复现信息」，不要强行分类。
