# gitlink-issue-triage

> GitLink Issue 自动分类 Skill — 让 AI Agent 帮你分诊堆积如山的 Issue

[![Skill](https://img.shields.io/badge/Skill-gitlink--issue--triage-blue)](./SKILL.md)
[![Compatibility](https://img.shields.io/badge/Compatible-Claude%20Code%20%7C%20Cursor%20%7C%20OpenAI%20Code-green)](https://claude.com/claude-code)

## 🎯 这是什么？

`gitlink-issue-triage` 是基于 [gitlink-cli](../../README.md) 的 **AI Agent Skill**，专门用于：

- 📥 **批量分诊** 未分类的 GitLink Issue
- 🏷️ **自动打标签** （bug / feature / question / ...）
- ⚡ **判定优先级** （urgent / high / normal / low）
- 👤 **建议指派人** （基于 @mention 和活跃贡献者）
- 🔗 **关联相似 Issue** （识别重复、相关历史）
- 📊 **生成审计报告** （JSON + 表格，可追溯）

适合**所有 Issue 堆积严重**的开源项目或团队仓库。

---

## 🚀 快速开始

### 前置条件

1. 已安装 `gitlink-cli`（参考 [主 README](../../README.md#安装与快速上手)）
2. 已完成认证（`gitlink-cli auth login`）
3. 在目标仓库目录下（自动解析 owner/repo）或显式指定 `--owner --repo`

### 5 分钟体验

向 AI Agent（如 Claude Code）说：

> "帮我用 gitlink-issue-triage 分析 owner/repo 仓库中所有 open 状态的 Issue，生成报告后等我确认。"

AI 会：

1. 拉取 Issue 列表
2. 逐个分析（应用规则 + 语义判断）
3. 展示表格报告
4. 等你确认后才应用变更

---

## 📁 Skill 结构

```
gitlink-issue-triage/
├── README.md                          # 本文件
├── SKILL.md                           # AI Agent 读取的主入口
├── references/
│   ├── gitlink-issue-triage-analyze.md  # 分析算法详解
│   └── gitlink-issue-triage-apply.md    # 应用变更手册
└── examples/
    ├── triage-batch-workflow.md       # 端到端批量分类示例
    └── triage-single-issue.md         # 单 Issue 深度分析示例
```

---

## 🧠 分类规则一览

完整规则见 [SKILL.md §4](./SKILL.md#4-分类决策规则核心算法)，摘要：

| 维度 | 决策依据 |
|------|---------|
| **类型（tracker）** | 关键词匹配（bug/错误/crash → bug；建议/希望 → feature） |
| **优先级** | 严重度信号（线上/紧急 → urgent；阻塞 → high） |
| **标签** | 仓库已有标签的语义匹配 |
| **指派人** | 正文 @mention 优先；否则不自动指派 |
| **关联 Issue** | 标题关键词 Jaccard 相似度 ≥ 0.4 |

**冲突解决**：标题优先于正文；多命中时 `bug > duplicate > feature > question > doc > support`。

---

## 🛡️ 安全设计

| 机制 | 说明 |
|------|------|
| ✅ Dry-run 默认 | 分析阶段不调用任何写 API |
| ✅ 双重确认 | 应用变更前必须表格展示 + 用户同意 |
| ✅ 不自动关闭 | 即使是 duplicate 也只评论建议 |
| ✅ 字段快照 | 每个变更保留原始值，支持回滚 |
| ✅ 批次上限 | 单批 ≤ 50 个，超出强制分批 |

---

## 🤖 AI Agent 兼容性

已在以下 Agent 平台验证：

- ✅ **Claude Code** — 主要验证目标，所有示例均可执行
- ✅ **Cursor** — 通过 SKILL.md markdown 协议兼容
- ✅ **OpenAI Code** — 通过 references/ 文档兼容

详见 [AI Agent 测试报告](../../doc/issue-triage-agent-test.md)。

---

## 📚 相关文档

- [SKILL.md — AI Agent 主入口](./SKILL.md)
- [分析算法详解](./references/gitlink-issue-triage-analyze.md)
- [应用变更手册](./references/gitlink-issue-triage-apply.md)
- [批量工作流示例](./examples/triage-batch-workflow.md)
- [单 Issue 分析示例](./examples/triage-single-issue.md)
- [上游 Skill: gitlink-issue](../gitlink-issue/SKILL.md)
- [共享规则: gitlink-shared](../gitlink-shared/SKILL.md)

---

## ❓ FAQ

**Q: 必须用 AI Agent 吗？人能用吗？**
A: 当然可以。SKILL.md 中的工作流对人类也是清晰的 SOP，你可以手动按步骤执行 gitlink-cli 命令。

**Q: 规则会误判吗？**
A: 会。规则是启发式，复杂 Issue 需要 AI 语义判断或人工复核。所有"非规则决策"会在报告中高亮。

**Q: 支持自定义规则吗？**
A: 当前版本规则内嵌在 SKILL.md，未来版本会支持外部 YAML 配置。

**Q: 与 GitHub Actions 的类似机器人有何不同？**
A: 本 Skill 是 **Agent-driven**（按需触发、人在环路），不是 **Event-driven**（自动触发、可能误判）。适合需要人工监督的高质量项目。

---

## 📄 许可证

继承 gitlink-cli 的 [MulanPSL-2.0](../../LICENSE)。
