forked from Gitlink/gitlink-cli
115 lines
4.3 KiB
Markdown
115 lines
4.3 KiB
Markdown
# 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` 降序排列
|