# gitlink-faq 分类与聚类

> 本文档说明 AI 如何对 Issue 先分类（Bug/功能请求/使用问题），再在同一类型内聚类。

## 分析前提

**聚类仅基于 `subject` + `description` 两个字段**。GitLink API 不支持读取 Issue 评论（journals），无法获取讨论/解决方案。但优秀的 description 往往包含：复现步骤、环境信息、修复建议、详细场景描述——这些都是高质量聚类的基础。

## 两步流程

```
┌─────────────────────────────────────────┐
│ Step 1: 类型分类                         │
│   每条 Issue → AI 判断类型               │
│   Bug / Feature Request / Usage Question │
│   不确定的归入"其他"但保留，不丢弃        │
└──────────────────┬──────────────────────┘
                   ▼
┌─────────────────────────────────────────┐
│ Step 2: 类型内聚类                       │
│   Bug → 按出问题的模块分类               │
│   Feature → 按功能领域分类               │
│   Usage → 按操作场景分类                 │
└─────────────────────────────────────────┘
```

## Step 1: 类型分类

### 分类 Prompt

```
你正在分析一个项目的已关闭 Issue。请对每条 Issue 判断它属于以下哪种类型：

类型定义：
- bug: 描述异常行为、报错、行为与预期不符、数据缺失/错误
- feature: 建议新增功能、增强现有能力、改进体验
- question: 不知道如何使用、配置不清楚、询问是否支持某能力
- other: 不属于以上三类（如测试、讨论、公告）

返回 JSON 数组：
[{
  "issue_number": N,
  "subject": "标题",
  "type": "bug|feature|question|other",
  "reason": "一句话判断依据"
}]
```

### 分类规则

| 类型 | 判断信号 | 反例（容易误判） |
|------|----------|-----------------|
| **bug** | 含"报错""不生效""异常""不一致""缺失""无法"等 | "希望能 xx"是 feature 不是 bug |
| **feature** | 含"希望""建议""能否支持""加一个""要是能"等 | "xx 不支持"可能是 question |
| **question** | 含"怎么""如何""能不能""是否支持"等，且是咨询性质 | "xx 报错怎么办"→ 先确认是不是 bug |
| **other** | 标题含"test""测试""讨论""收集"等 | 不确定时归为 other |

## Step 2: 类型内聚类

### Bug 聚类

按**出问题的模块/组件/功能**归类，找出高频 Bug 模式。

聚类维度：
- 影响的是哪个命令/接口（如 `issue +view`、`pr +list`、`api` 命令）
- 问题类型是否相同（数据显示错误 ×4 / 命令执行失败 ×2 / 平台兼容 ×1）
- Bug 之间是否存在共同根因

输出格式：

```json
{
  "module": "Issue/PR 数据展示",
  "bug_count": 4,
  "pattern": "CLI 返回数据字段与网页端不一致或字段缺失",
  "affected_issues": [5, 7, 15, 18],
  "typical_symptom": "使用 view 命令查看详情时，部分字段（如关闭时间、描述等）缺失或与网页端不一致"
}
```

### 功能请求聚类

按**请求的功能领域**归类，找出用户需求热度。

聚类维度：
- 请求的是哪个能力方向（API 增强 / 命令扩展 / 平台支持）
- 是否指向同一个需求的不同表述
- 是否有用户点赞/讨论热度叠加

输出格式：

```json
{
  "feature_area": "API 查询能力增强",
  "request_count": 3,
  "pattern": "用户希望 API 支持更丰富的查询和操作",
  "affected_issues": [9, 14, 21],
  "common_ask": "支持按序号查询、返回完整时间字段、读取仓库文件"
}
```

### 使用问题聚类（传统 Q&A）

与传统 FAQ 一致：按操作场景归类，提炼"问题 → 答案"。

仅当同类 ≥ 2 条时生成 Q&A 条目。

## 批次合并

多批次处理后的合并规则：

1. 同类型的相同模块/领域 → 合并，更新 issue_count
2. 跨类型的关联 Issue 标注引用（如一个 Bug 可能由某个 Feature Request 修复）
3. 最终按 `bug_count` / `request_count` 降序排列
