forked from Gitlink/gitlink-cli
133 lines
4.6 KiB
Markdown
133 lines
4.6 KiB
Markdown
# gitlink-issue-triage
|
||
|
||
> GitLink Issue 自动分类 Skill — 让 AI Agent 帮你分诊堆积如山的 Issue
|
||
|
||
[](./SKILL.md)
|
||
[](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)。
|