forked from Gitlink/gitlink-cli
314 lines
9.2 KiB
Markdown
314 lines
9.2 KiB
Markdown
# Workflow: Issue Triage（Issue 自动分类）
|
||
|
||
> **前置条件：** 先阅读 [`../../gitlink-shared/SKILL.md`](../../../gitlink-shared/SKILL.md) 了解认证、全局参数和安全规则。
|
||
> **AI Agent 工作流**：此工作流专为 AI Agent 设计，用于自动化 Issue 分类和管理。
|
||
|
||
AI Agent 自动为新建的 Issue 添加标签和分类，提高项目管理效率。
|
||
|
||
## 工作流概述
|
||
|
||
Issue Triage 工作流通过分析 Issue 的标题和描述内容，自动为 Issue 分配合适的标签，帮助项目维护者更好地组织和管理 Issue。
|
||
|
||
## 适用场景
|
||
|
||
- **项目维护**：自动分类新提交的 Issue
|
||
- **标签管理**：确保 Issue 有正确的分类标签
|
||
- **优先级排序**：基于分类快速识别高优先级 Issue
|
||
- **团队协作**：减少手动分类工作量，提高效率
|
||
|
||
## 工作流步骤
|
||
|
||
### 步骤 1：获取未标记的 Issue 列表
|
||
|
||
```bash
|
||
# 获取所有开放的 Issue
|
||
gitlink-cli issue +list --state open --format json
|
||
|
||
# 筛选出没有标签的 Issue
|
||
gitlink-cli issue +list --state open --format json | \
|
||
jq '.data.issues[] | select(.issue_tags == null or .issue_tags == [])'
|
||
```
|
||
|
||
### 步骤 2：分析 Issue 内容
|
||
|
||
```bash
|
||
# 获取特定 Issue 的详细信息
|
||
gitlink-cli issue +view --id 123 --format json
|
||
|
||
# 分析标题和描述
|
||
gitlink-cli issue +view --id 123 --format json | \
|
||
jq '{subject: .data.subject, description: .data.description}'
|
||
```
|
||
|
||
### 步骤 3：智能分类
|
||
|
||
基于 Issue 内容的分析，应用以下分类规则：
|
||
|
||
**Bug 分类规则**：
|
||
- 标题/描述包含关键词：`bug`、`错误`、`失败`、`异常`、`crash`、`issue`、`problem`
|
||
- 行为模式：描述功能失效或异常行为
|
||
- 示例：`登录时遇到错误`、`页面加载失败`
|
||
|
||
**Feature 分类规则**：
|
||
- 标题/描述包含关键词：`feature`、`新增`、`建议`、`request`、`enhancement`、`improve`
|
||
- 行为模式：建议新功能或改进
|
||
- 示例：`添加用户权限管理`、`建议支持暗色主题`
|
||
|
||
**Question 分类规则**：
|
||
- 标题/描述包含关键词：`question`、`如何`、`怎么`、`how`、`帮助`、`help`、`疑问`
|
||
- 行为模式：询问使用方法或寻求帮助
|
||
- 示例：`如何配置环境变量`、`怎么部署到服务器`
|
||
|
||
**Documentation 分类规则**：
|
||
- 标题/描述包含关键词：`doc`、`文档`、`README`、`tutorial`、`guide`、`example`
|
||
- 行为模式：与文档相关的问题或建议
|
||
- 示例：`更新安装文档`、`添加使用示例`
|
||
|
||
### 步骤 4：添加标签
|
||
|
||
```bash
|
||
# 获取项目的标签列表
|
||
gitlink-cli api GET /:owner/:repo/issue_tags --format json
|
||
|
||
# 为 Issue 添加标签
|
||
gitlink-cli api POST /:owner/:repo/issues/123 --body \
|
||
'{"issue_tag_ids":[1, 2]}'
|
||
|
||
# 添加单个标签
|
||
gitlink-cli api POST /:owner/:repo/issues/123 --body \
|
||
'{"issue_tag_ids":[1]}'
|
||
```
|
||
|
||
## 完整工作流示例
|
||
|
||
```bash
|
||
#!/bin/bash
|
||
|
||
# Issue Triage 自动化脚本
|
||
|
||
OWNER="myuser"
|
||
REPO="myproject"
|
||
|
||
# 1. 获取所有开放的 Issue
|
||
ISSUES=$(gitlink-cli issue +list --owner $OWNER --repo $REPO --state open --format json)
|
||
|
||
# 2. 遍历每个 Issue
|
||
echo "$ISSUES" | jq -c '.data.issues[]' | while read -r issue; do
|
||
ISSUE_ID=$(echo "$issue" | jq -r '.id')
|
||
SUBJECT=$(echo "$issue" | jq -r '.subject')
|
||
DESCRIPTION=$(echo "$issue" | jq -r '.description')
|
||
TAGS=$(echo "$issue" | jq -r '.issue_tags // []')
|
||
|
||
# 跳过已有标签的 Issue
|
||
if [ "$TAGS" != "[]" ]; then
|
||
echo "Issue $ISSUE_ID 已有标签，跳过"
|
||
continue
|
||
fi
|
||
|
||
echo "分析 Issue $ISSUE_ID: $SUBJECT"
|
||
|
||
# 分析内容并确定标签
|
||
TAG_IDS=()
|
||
CONTENT="$SUBJECT $DESCRIPTION"
|
||
|
||
# 分类逻辑
|
||
if echo "$CONTENT" | grep -iqE "bug|错误|失败|异常|crash|issue|problem"; then
|
||
TAG_IDS+=("1") # 假设 1 是 bug 标签
|
||
echo " → 分类为: bug"
|
||
fi
|
||
|
||
if echo "$CONTENT" | grep -iqE "feature|新增|建议|request|enhancement|improve"; then
|
||
TAG_IDS+=("2") # 假设 2 是 enhancement 标签
|
||
echo " → 分类为: enhancement"
|
||
fi
|
||
|
||
if echo "$CONTENT" | grep -iqE "question|如何|怎么|how|帮助|help|疑问"; then
|
||
TAG_IDS+=("3") # 假设 3 是 question 标签
|
||
echo " → 分类为: question"
|
||
fi
|
||
|
||
if echo "$CONTENT" | grep -iqE "doc|文档|README|tutorial|guide|example"; then
|
||
TAG_IDS+=("4") # 假设 4 是 documentation 标签
|
||
echo " → 分类为: documentation"
|
||
fi
|
||
|
||
# 添加标签到 Issue
|
||
if [ ${#TAG_IDS[@]} -gt 0 ]; then
|
||
echo " → 为 Issue $ISSUE_ID 添加标签: ${TAG_IDS[*]}"
|
||
# 实际执行时取消注释
|
||
# gitlink-cli api POST "/$OWNER/$REPO/issues/$ISSUE_ID" --body \
|
||
# "{\"issue_tag_ids\":[${TAG_IDS[*]}]}"
|
||
else
|
||
echo " → 无法自动分类，需要人工处理"
|
||
fi
|
||
|
||
echo ""
|
||
done
|
||
```
|
||
|
||
## AI Agent 集成示例
|
||
|
||
Claude Code 等 AI Agent 可以直接执行此工作流：
|
||
|
||
```python
|
||
# AI Agent 执行 Issue Triage
|
||
def issue_triage(owner, repo):
|
||
"""AI Agent 自动分类 Issue"""
|
||
|
||
# 1. 获取开放的 Issue
|
||
issues = gitlink_cli_issue_list(owner, repo, state="open")
|
||
|
||
for issue in issues:
|
||
# 2. 跳过已有标签的
|
||
if issue.get('issue_tags'):
|
||
continue
|
||
|
||
# 3. AI 分析内容
|
||
content = f"{issue['subject']} {issue.get('description', '')}"
|
||
classification = analyze_issue_content(content)
|
||
|
||
# 4. 添加标签
|
||
if classification:
|
||
add_issue_tags(owner, repo, issue['id'], classification)
|
||
|
||
def analyze_issue_content(content):
|
||
"""AI 分析 Issue 内容"""
|
||
# 使用 AI 模型分析文本
|
||
labels = []
|
||
|
||
if any(word in content.lower() for word in ['bug', 'error', 'fail']):
|
||
labels.append('bug')
|
||
|
||
if any(word in content.lower() for word in ['feature', 'enhancement']):
|
||
labels.append('enhancement')
|
||
|
||
return labels
|
||
```
|
||
|
||
## 高级分类策略
|
||
|
||
### 多标签分类
|
||
一个 Issue 可以有多个标签：
|
||
|
||
```bash
|
||
# 同时添加多个标签
|
||
gitlink-cli api POST /:owner/:repo/issues/123 --body \
|
||
'{"issue_tag_ids":[1, 2, 5]}'
|
||
|
||
# 示例：既严重又是功能请求
|
||
# bug + enhancement + high-priority
|
||
```
|
||
|
||
### 优先级分类
|
||
基于紧急程度添加优先级标签：
|
||
|
||
**高优先级关键词**：
|
||
- `urgent`、`紧急`、`严重`、`critical`、`blocking`、`阻塞`
|
||
|
||
**中优先级关键词**：
|
||
- `moderate`、`中等`、`normal`、`常规`
|
||
|
||
**低优先级关键词**：
|
||
- `low`、`较低`、`minor`、`次要`、`nice-to-have`
|
||
|
||
### 复杂度分类
|
||
基于实现难度分类：
|
||
|
||
**简单**：
|
||
- 关键词：`简单`、`easy`、`quick`、`minor`
|
||
- 预估时间：1-2 天
|
||
|
||
**中等**：
|
||
- 关键词：`中等`、`moderate`、`normal`
|
||
- 预估时间：3-7 天
|
||
|
||
**复杂**：
|
||
- 关键词：`复杂`、`complex`、`hard`、`major`、`重构`
|
||
- 预估时间：8+ 天
|
||
|
||
## 自定义分类规则
|
||
|
||
根据项目特点定制分类规则：
|
||
|
||
```bash
|
||
# Web 项目特定分类
|
||
WEB_KEYWORDS=("前端" "frontend" "UI" "界面" "页面")
|
||
if grep -qE "${WEB_KEYWORDS[*]}" <<< "$CONTENT"; then
|
||
TAG_IDS+=("10") # frontend 标签
|
||
fi
|
||
|
||
# 后端项目特定分类
|
||
BACKEND_KEYWORDS=("后端" "backend" "API" "接口" "数据库")
|
||
if grep -qE "${BACKEND_KEYWORDS[*]}" <<< "$CONTENT"; then
|
||
TAG_IDS+=("11") # backend 标签
|
||
fi
|
||
|
||
# DevOps 相关分类
|
||
DEVOPS_KEYWORDS=("部署" "deploy" "CI" "CD" "Docker" "Kubernetes")
|
||
if grep -qE "${DEVOPS_KEYWORDS[*]}" <<< "$CONTENT"; then
|
||
TAG_IDS+=("12") # devops 标签
|
||
fi
|
||
```
|
||
|
||
## 错误处理
|
||
|
||
常见问题处理：
|
||
|
||
| 问题 | 原因 | 解决方案 |
|
||
|------|------|----------|
|
||
| 标签 ID 不存在 | 标签未创建 | 先创建项目标签 |
|
||
| 权限不足 | 无修改 Issue 权限 | 联系项目管理员 |
|
||
| 分类不准确 | 关键词匹配失败 | 优化分类规则或人工审核 |
|
||
|
||
## 质量保证
|
||
|
||
确保分类质量的措施：
|
||
|
||
1. **定期审查**：定期审查自动分类结果
|
||
2. **反馈学习**：根据反馈调整分类规则
|
||
3. **人工确认**：对不确定的分类进行人工确认
|
||
4. **规则优化**：持续优化关键词匹配规则
|
||
|
||
## 最佳实践
|
||
|
||
1. **渐进式部署**：先小范围测试，再全面应用
|
||
2. **规则透明**：记录分类规则，便于团队理解和调整
|
||
3. **性能监控**：监控分类准确率和效率
|
||
4. **用户反馈**：收集用户反馈，持续改进
|
||
|
||
## 扩展功能
|
||
|
||
### 自动分配
|
||
基于分类自动分配给合适的开发者：
|
||
|
||
```bash
|
||
# Bug 分配给核心开发者
|
||
if [[ " ${TAG_IDS[@]} " =~ " 1 " ]]; then
|
||
ASSIGNEE="senior_developer"
|
||
fi
|
||
|
||
# 文档问题分配给技术写作
|
||
if [[ " ${TAG_IDS[@]} " =~ " 4 " ]]; then
|
||
ASSIGNEE="tech_writer"
|
||
fi
|
||
```
|
||
|
||
### 自动设置优先级
|
||
基于分类和关键词自动设置优先级：
|
||
|
||
```bash
|
||
# 严重 bug 设置为高优先级
|
||
if [[ " ${TAG_IDS[@]} " =~ " 1 " ]] && echo "$CONTENT" | grep -iq "严重"; then
|
||
PRIORITY_ID="1" # 高优先级
|
||
fi
|
||
```
|
||
|
||
## References
|
||
|
||
- [workflow-pr-review](workflow-pr-review.md) — PR 审查工作流
|
||
- [workflow-release-notes](workflow-release-notes.md) — Release Notes 生成
|
||
- [gitlink-workflow](../SKILL.md) — 工作流总览
|
||
- [gitlink-shared](../../gitlink-shared/SKILL.md) — 认证和全局参数
|
||
- [issue +list](../../gitlink-issue/references/gitlink-issue-list.md) — Issue 列表
|
||
- [issue +view](../../gitlink-issue/references/gitlink-issue-view.md) — 查看 Issue
|