# 示例：单 Issue 深度分析

> 本示例展示对单个复杂 Issue 的逐步分析过程，重点演示规则与 AI 语义判断的协作。

## 场景

某用户提交了如下 Issue：

```bash
gitlink-cli issue +view --owner demo --repo cli-test --number 88 --format json
```

```json
{
  "number": 88,
  "subject": "性能问题：导出 10w 行 Excel 时浏览器卡死",
  "description": "在使用导出功能时，如果数据量超过 10 万行，浏览器会卡死几分钟后崩溃。\n\n复现步骤：\n1. 进入数据管理页\n2. 选择全部数据（约 12w 行）\n3. 点击导出 Excel\n4. 浏览器卡死\n\n环境：Chrome 120，macOS 14\n\n@dev-li 麻烦看下这个，影响线上 XX 客户使用。",
  "tracker_id": null,
  "priority_id": 2,
  "issue_tags": [],
  "assigned_to_id": null
}
```

---

## 分析步骤

### Step 1 — 文本预处理

```python
text = normalize("性能问题：导出 10w 行 Excel 时浏览器卡死 " + description)
# → "性能问题 导出 10w 行 excel 时浏览器卡死 在使用导出功能时..."
```

### Step 2 — Tracker 决策

扫描关键词：

| 来源 | 命中关键词 | 规则 |
|------|-----------|------|
| 标题 | "卡死"、"崩溃" | → bug（强信号） |
| 正文 | "复现步骤"、"浏览器" | → bug（辅助信号） |
| 正文 | "影响线上" | → bug + urgent 候选 |

**结论**：`tracker = bug`（confidence 0.45）

> ⚠️ 注意："性能问题"单独出现可能让人想到 `enhancement`，但"卡死"、"崩溃"是明确的缺陷信号。

### Step 3 — Priority 决策

| 命中 | 信号强度 |
|------|---------|
| "线上" | urgent 候选 |
| "影响 XX 客户使用" | urgent 候选 |
| "浏览器卡死" + "崩溃" | high 候选 |

**冲突解决**：两个 urgent 信号 + 一个 high 信号 → 升级为 `urgent`

**结论**：`priority = urgent`（confidence 0.4）

### Step 4 — Labels 建议

仓库可用标签（`GET /v1/demo/cli-test/issue_tags.json`）：

```json
{"缺陷": 101, "性能": 102, "紧急": 103, "客户反馈": 104}
```

匹配：
- `bug` → `缺陷`（语义匹配）
- `urgent` → `紧急`（语义匹配）
- 正文"客户使用" → `客户反馈`（弱匹配，**不自动加**，仅在报告中提示）

**结论**：`labels = ["缺陷", "紧急"]`

### Step 5 — Assignee 建议

正文中 `@dev-li` 明确提及，且 `dev-li` 在 `issue_assigners.json` 中：

```bash
gitlink-cli api GET /v1/demo/cli-test/issue_assigners.json --format json \
    | jq '.data.assigners[] | select(.login=="dev-li")'
```

```json
{"login": "dev-li", "id": 20250, "name": "李四"}
```

**结论**：`assignee = "dev-li"`（confidence 0.95）
> 用户明确 @mention，可直接指派（无需额外确认）。

### Step 6 — 关联 Issue 推荐

历史 Issue 标题中扫描相似项：

| 编号 | 标题 | Jaccard 相似度 |
|------|------|---------------|
| #76 | "大数据量导出导致页面无响应" | 0.72 |
| #52 | "Excel 导出功能异常" | 0.55 |
| #41 | "浏览器内存溢出" | 0.42 |

**决策**：
- #76 相似度 ≥ 0.7，但**仍处于 open 状态** → 评论"可能与 #76 相关"
- #52 相似度 0.55，列入"可能相关"
- #41 相似度 0.42，临界值，**不关联**

### Step 7 — Confidence 计算

```python
confidence = 0.4 (title_match: bug) + \
             0.2 (body_match: 复现步骤) + \
             0.2 (urgent signal) + \
             0.15 (strong related: #76) + \
             0.1 (mention resolved) + \
             0    (description long enough)
           = 1.05 → clamp to 0.95
```

**结论**：`confidence = 0.95`，可直接应用。

---

## 最终分析结果

```json
{
  "number": 88,
  "title": "性能问题：导出 10w 行 Excel 时浏览器卡死",
  "current_tracker": null,
  "current_labels": [],
  "decisions": {
    "tracker": "bug",
    "priority": "urgent",
    "labels": ["缺陷", "紧急"],
    "assignee": "dev-li",
    "related_issues": [76, 52],
    "mark_duplicate": null
  },
  "confidence": 0.95,
  "reasoning": "标题'卡死'+'崩溃'→ bug；正文'线上'+'影响客户'→ urgent；@dev-li 明确指派；与 #76 高相似度",
  "matched_rules": [
    "title: 卡死",
    "title: 崩溃",
    "body: 线上",
    "body: 影响客户",
    "mention: @dev-li"
  ],
  "needs_review": false
}
```

---

## 应用变更

### 1. 备份原始字段

```bash
gitlink-cli issue +view --owner demo --repo cli-test --number 88 --format json \
    > /tmp/issue-88-before.json
```

### 2. 更新 tracker、priority、assignee

```bash
# 获取 subject 和 description（必须保留）
SUBJECT=$(jq -r '.data.subject' /tmp/issue-88-before.json)
DESC=$(jq -r '.data.description // ""' /tmp/issue-88-before.json)

# PATCH 更新（tracker=1 bug, priority=4 urgent, assignee=20250）
gitlink-cli api PATCH /v1/demo/cli-test/issues/88 \
    --body "$(jq -n \
        --arg s "$SUBJECT" \
        --arg d "$DESC" \
        '{subject:$s, description:$d, tracker_id:1, priority_id:4, assigned_to_id:20250}')"
```

### 3. 添加标签

```bash
gitlink-cli issue +label-add \
    --owner demo --repo cli-test \
    --number 88 \
    --labels "缺陷,紧急"
```

### 4. 评论分析摘要

```bash
gitlink-cli issue +comment \
    --owner demo --repo cli-test \
    --number 88 \
    --body "$(cat <<'EOF'
🤖 **自动分类报告**

| 字段 | 决策 | 依据 |
|------|------|------|
| 类型 | bug | 标题含"卡死"、"崩溃" |
| 优先级 | urgent | 正文提"线上"、"影响客户" |
| 标签 | 缺陷, 紧急 | 仓库标签匹配 |
| 指派 | @dev-li | 正文明确 @mention |

**关联 Issue**：
- #76「大数据量导出导致页面无响应」（相似度 0.72）
- #52「Excel 导出功能异常」（相似度 0.55）

如分类有误请回复 `/triage incorrect`。
EOF
)"
```

### 5. 验证

```bash
gitlink-cli issue +view --owner demo --repo cli-test --number 88 --format json \
    | jq '{number, tracker_id, priority_id, assigned_to_id, issue_tags}'
```

**期望输出**：
```json
{
  "number": 88,
  "tracker_id": 1,
  "priority_id": 4,
  "assigned_to_id": 20250,
  "issue_tags": [{"id": 101, "name": "缺陷"}, {"id": 103, "name": "紧急"}]
}
```

---

## AI Agent 提示词（可直接复制给 Claude Code）

```
请对 demo/cli-test 仓库的 Issue #88 执行深度分析：

1. 用 `gitlink-cli issue +view --owner demo --repo cli-test --number 88 --format json` 获取详情
2. 按以下规则分析（详见 references/gitlink-issue-triage-analyze.md）：
   - tracker、priority、labels、assignee、related_issues
3. 输出 JSON 格式的分析结果（schema 见 SKILL.md）
4. 展示人类可读的决策表，问我是否应用
5. 我确认后，按 references/gitlink-issue-triage-apply.md 执行：
   - 备份原始字段
   - PATCH 更新 tracker_id、priority_id、assigned_to_id（保留 subject/description）
   - label-add 添加标签
   - comment 评论分析摘要

所有写操作前 dry-run，确认后实际执行。
```

---

## 关键学习点

1. **冲突解决**：标题"性能问题"听起来像 enhancement，但"卡死"、"崩溃"明确指向 bug → 优先强信号
2. **优先级升级**：多个 urgent 候选 + 客户影响 → 直接 urgent，而非 high
3. **@mention 处理**：用户明确 @某人时可直接指派，无需 PM 中介
4. **关联判断**：相似度 0.7+ 是关键阈值，0.4-0.7 仅作提示
5. **审计完整**：保留原始字段是回滚的前提

---

## 反模式（不要这样做）

❌ **仅看标题**："性能问题" → feature（错误，忽略"卡死"）
❌ **忽略 @mention**：直接不指派 → 失去用户意图
❌ **关闭 duplicate**：#76 还开着就关闭 #88 → 错误
❌ **批量应用不暂停**：连续打 50 个 API → 限流
