# 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
