---
name: gitlink-issue-triage
version: 1.0.0
description: "Issue 自动分类（Issue Triage）：根据 Issue 标题与正文，自动判定类型（bug/feature/question 等）、优先级、建议标签与指派人，并生成可审计的分析报告。当用户需要对一批未分类 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 — 所有"应用"动作（apply）默认 dry-run；只有用户明确确认后才执行写入。**
**CRITICAL — GitLink 操作只能用 `gitlink-cli`。禁止用 `gh`（GitHub CLI）操作 GitLink 资源。`gh` 仅适用于 GitHub 平台。**

> **前置依赖：** 先阅读 [`../gitlink-issue/SKILL.md`](../gitlink-issue/SKILL.md) 了解 Issue 基础操作和字段映射。

---

## 1. 这个 Skill 做什么？

`gitlink-issue-triage` 是一个 **AI Agent 驱动的 Issue 自动分类工作流**，解决开源/协作项目中常见的"Issue 堆积无人分诊"问题：

- 📥 **批量拉取未分类 Issue**（`tracker_id` 缺失、无标签、无 assignee）
- 🧠 **基于内容判定**：类型（bug/feature/...）、优先级（low/normal/high/urgent）、建议标签
- 👤 **指派建议**：基于关键词匹配仓库内活跃贡献者
- 🔗 **关联 Issue**：识别重复或相关 Issue，附在评论中
- 📊 **输出结构化报告**（JSON），便于人工复核与审计
- ✅ **Dry-run 优先**：所有写入操作默认预览，确认后才落地

---

## 2. 工作流总览

```
                 ┌─────────────────────────┐
                 │ 1. 拉取未分类 Issue 列表  │  issue +list --state open
                 └────────────┬────────────┘
                              ▼
       ┌──────────────────────────────────────────┐
       │ 2. 对每个 Issue 执行分析（AI + 规则）       │
       │    - 关键词匹配 → tracker_id              │
       │    - 严重度信号 → priority_id             │
       │    - 标签建议 → issue_tag_ids             │
       │    - 活跃贡献者 → assigned_to_id          │
       │    - 文本相似度 → related issues          │
       └────────────────┬─────────────────────────┘
                        ▼
       ┌──────────────────────────────────────────┐
       │ 3. 生成分析报告（JSON）                    │
       │    { issue_number, decisions, confidence }│
       └────────────────┬─────────────────────────┘
                        ▼
       ┌──────────────────────────────────────────┐
       │ 4. 用户确认 → 应用变更                     │
       │    issue +update / +label-add / +comment │
       └──────────────────────────────────────────┘
```

---

## 3. Shortcuts 与 Raw API 速查

本 Skill 复用 gitlink-cli 已有命令，**不新增 shortcut**，确保单一可信源。

### 3.1 读操作（只读，可放心使用）

| 命令 | 用途 |
|------|------|
| `issue +list --state open --format json` | 获取待分类 Issue 列表 |
| `issue +view --number <N> --format json` | 获取 Issue 详情（标题/正文/标签） |
| `issue +label-list --number <N> --format json` | 查看 Issue 当前标签 |
| `api GET /v1/:owner/:repo/issue_tags.json` | 获取仓库可用标签（name→id 映射） |
| `api GET /v1/:owner/:repo/issue_assigners.json` | 获取可指派用户列表 |
| `api GET /users/:login` | login → user_id 解析 |

### 3.2 写操作（默认 dry-run，确认后执行）

| 命令 | 用途 |
|------|------|
| `issue +update --number <N> --state <s>` | 改状态（如 in-progress） |
| `issue +label-add --number <N> --labels "<csv>"` | 加标签 |
| `issue +comment --number <N> --body "<text>"` | 评论（关联 Issue 链接、分析摘要） |
| `issue +batch-label --label <name> --numbers <csv>` | 批量改 tracker |

---

## 4. 分类决策规则（核心算法）

> 以下规则同时给 AI Agent 和人类审阅者参考。AI Agent 应**优先**遵循规则，对规则无法覆盖的情况使用语义判断。

### 4.1 类型（tracker_id）决策

| 关键词（标题或正文，大小写不敏感） | tracker_id | 说明 |
|----------------------------------|------------|------|
| `bug`, `错误`, `失败`, `崩溃`, `异常`, `报错`, `不能`, `无法`, `crash`, `error`, `exception` | 1 (bug) | 缺陷报告 |
| `feature`, `希望`, `建议`, `新增`, `支持`, `能否添加`, `enhancement`, `proposal` | 2 (feature) | 功能请求 |
| `怎么`, `如何`, `哪里`, `？`, `?`, `question`, `文档`, `help`, `请问` | 7 (question) | 求助/疑问 |
| `重复`, `duplicate`, `已有`, `same as` | 6 (duplicate) | 重复 Issue |
| `文档`, `README`, `教程`, `doc`, `typo`, `拼写` | 4 (doc) | 文档类 |
| `支持`, `求助`, `support`, `咨询` | 3 (support) | 支持请求 |

**冲突解决**：标题命中优先于正文命中；多个命中时优先级 `bug > duplicate > feature > question > doc > support`。

### 4.2 优先级（priority_id）决策

| 信号 | priority_id |
|------|-------------|
| 含 `紧急`, `urgent`, `ASAP`, `线上`, `production`, `数据丢失`, `安全`, `security`, `CVE` | 4 (urgent) |
| 含 `重要`, `阻塞`, `block`, `无法工作`, `完全不能用`, `high` | 3 (high) |
| 默认（无强信号） | 2 (normal) |
| 含 `minor`, `小问题`, `建议`, `nice to have`, `low` | 1 (low) |

### 4.3 标签建议（issue_tag_ids）

1. 调用 `GET /v1/:owner/:repo/issue_tags.json` 获取仓库已有标签
2. 根据分类结果匹配语义相近的标签：
   - tracker=bug → 优先匹配 `缺陷`/`bug`
   - tracker=feature → 优先匹配 `功能`/`enhancement`
   - 优先级=urgent → 加上 `紧急`/`urgent`（如存在）
3. 若仓库无对应标签，**跳过标签步骤**，仅在报告中提示

### 4.4 指派人（assigned_to_id）建议

1. 调用 `GET /v1/:owner/:repo/issue_assigners.json` 获取可指派列表
2. 若 Issue 正文中 `@username`，优先指派该用户
3. 否则：**不自动指派**，仅在报告中提示"建议由 PM 分配"
4. AI Agent **不应**自动指派到具体个人，除非用户明确同意

### 4.5 关联 Issue 推荐

1. 调用 `issue +list --state all --format json` 获取近期 Issue 标题
2. 对当前 Issue 标题做关键词提取（去停用词）
3. 与历史 Issue 标题计算 Jaccard 相似度
4. 相似度 ≥ 0.4 的 Top-3 作为"可能相关"
5. 若相似度 ≥ 0.7 且其中之一已关闭 → 建议标记 `duplicate`

---

## 5. 标准工作流（AI Agent 执行模板）

> **AI Agent 看这里**：以下是你被请求"分类 Issue"时应遵循的标准流程。

### Step 1 — 上下文与确认范围

```bash
# 确认 owner/repo（自动从 git remote 解析或用户指定）
gitlink-cli issue +list --state open --limit 5 --format json
```

向用户确认："发现 N 个 open 状态 Issue，是否对全部执行分类分析？或指定编号范围（如 100-120）？"

### Step 2 — 拉取仓库元数据

```bash
# 获取标签 ID 映射（缓存到内存）
gitlink-cli api GET /v1/:owner/:repo/issue_tags.json --format json

# 获取可指派用户列表
gitlink-cli api GET /v1/:owner/:repo/issue_assigners.json --format json
```

### Step 3 — 逐个分析

对每个目标 Issue：

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

应用第 4 节决策规则，生成分析结果：

```json
{
  "number": 142,
  "title": "登录页面点击登录无反应",
  "current_tracker": null,
  "current_labels": [],
  "decisions": {
    "tracker": "bug",
    "priority": "high",
    "labels": ["缺陷"],
    "assignee": null,
    "related_issues": [138, 119]
  },
  "confidence": 0.85,
  "reasoning": "标题含'无反应'，正文含'点击'、'登录'，符合 bug 特征；用户描述'线上不能登录'触发 high 优先级"
}
```

### Step 4 — 汇总报告

把所有 Issue 的分析结果合并：

```json
{
  "repository": "owner/repo",
  "analyzed_at": "2026-06-16T10:00:00Z",
  "total": 15,
  "by_tracker": {"bug": 7, "feature": 4, "question": 3, "duplicate": 1},
  "by_priority": {"urgent": 1, "high": 4, "normal": 9, "low": 1},
  "items": [ /* Step 3 的结果数组 */ ]
}
```

**用表格形式向用户展示摘要**（人类可读），等待用户确认。

### Step 5 — 应用变更（用户确认后）

```bash
# 改 tracker（一次只能改一个，循环执行）
gitlink-cli issue +update --number 142 --state in-progress   # 标记处理中

# 加标签
gitlink-cli issue +label-add --number 142 --labels "缺陷"

# 评论（含分析摘要和关联 Issue）
gitlink-cli issue +comment --number 142 --body "🤖 自动分类报告\n- 类型: bug\n- 优先级: high\n- 关联: #138 #119\n\n如分类有误请回复修正。"
```

---

## 6. 安全规则

| 规则 | 说明 |
|------|------|
| ✅ **Dry-run 优先** | 分析阶段只读，不调用任何写 API |
| ✅ **用户确认** | 应用变更前必须展示报告并征得同意 |
| ✅ **不自动关闭** | 即使识别为 duplicate，也只评论建议，不主动关闭 |
| ✅ **不自动指派个人** | assignee 建议由 PM 决定，除非用户明确指定 |
| ✅ **可回滚** | 每次应用变更记录原始字段，便于人工撤销 |
| ❌ **禁止** | 批量修改超过 50 个 Issue 而不分批确认 |

---

## 7. 与现有 Skills 的关系

| Skill | 关系 |
|-------|------|
| [`gitlink-shared`](../gitlink-shared/SKILL.md) | 前置必读：认证、错误处理、安全规则 |
| [`gitlink-issue`](../gitlink-issue/SKILL.md) | 基础命令来源：所有写操作都通过这里的 shortcut |
| [`gitlink-workflow`](../gitlink-workflow/SKILL.md) | 上游模板：本 Skill 是 workflow 中"Issue Triage"的完整实现 |

---

## 8. 参考文档

- [详细操作手册](references/gitlink-issue-triage-analyze.md) — 分析算法的完整伪代码与字段映射
- [应用变更手册](references/gitlink-issue-triage-apply.md) — 写操作命令清单与回滚策略
- [完整工作流示例](examples/triage-batch-workflow.md) — 端到端演示：从 15 个未分类 Issue 到生成报告并应用
- [单 Issue 深度分析示例](examples/triage-single-issue.md) — 单个复杂 Issue 的逐步分析过程

---

## 9. 常见问题

**Q: 规则与 AI 语义判断冲突时怎么办？**
A: AI 语义判断优先，但必须在 `reasoning` 字段说明依据。报告展示时高亮"非规则决策"项供人工复核。

**Q: 仓库没有 `缺陷` 标签怎么办？**
A: 跳过标签步骤，在报告中提示用户"建议在仓库设置中创建标签 X 以提升分类效果"。

**Q: 一次处理多少 Issue 合适？**
A: 建议 10-30 个/批。超过 50 个时强制分批，每批之间用户确认。

**Q: 如何回退已应用的变更？**
A: 报告中保留每个 Issue 的原始字段快照，可用 `issue +update` 反向恢复。
