forked from Gitlink/gitlink-cli
145 lines
6.0 KiB
Markdown
145 lines
6.0 KiB
Markdown
# gitlink-stale
|
||
|
||
> GitLink Stale Issue/PR 自动处理 Skill — 让 AI Agent 帮你清理堆积如山的未活动 Issue/PR
|
||
|
||
[](./SKILL.md)
|
||
[](https://claude.com/claude-code)
|
||
|
||
## 🎯 这是什么？
|
||
|
||
`gitlink-stale` 是基于 [gitlink-cli](../../README.md) 的 **AI Agent Skill**，专门用于：
|
||
|
||
- 🔍 **扫描识别** 长期未活动的 GitLink Issue / PR（默认 60 天）
|
||
- 🧠 **AI 智能判断** 区分"真僵尸"和"等维护者回复"（不是简单按时间一刀切）
|
||
- 🏷️ **自动打 stale 标签** 通知作者/相关者
|
||
- 💬 **友好催办评论** 避免简单粗暴的"过期警告"
|
||
- 🔒 **过期自动关闭** 超过宽限期（默认 14 天）仍未响应才关闭
|
||
- 🛡️ **白名单豁免** `pinned`/`security`/`roadmap` 永不动
|
||
- 📊 **生成审计报告** JSON + 表格，可追溯
|
||
|
||
适合**所有 Issue/PR 长期堆积**的开源项目或团队仓库，承担类似 GitHub `stale` bot 的角色，但通过 AI Agent 实现"人在环路"和"智能判断"。
|
||
|
||
---
|
||
|
||
## 🚀 快速开始
|
||
|
||
### 前置条件
|
||
|
||
1. 已安装 `gitlink-cli`（参考 [主 README](../../README.md#安装与快速上手)）
|
||
2. 已完成认证（`gitlink-cli auth login`）
|
||
3. 在目标仓库目录下（自动解析 owner/repo）或显式指定 `--owner --repo`
|
||
|
||
### 5 分钟体验
|
||
|
||
向 AI Agent（如 Claude Code）说：
|
||
|
||
> "帮我用 gitlink-stale 扫描 owner/repo 仓库中所有 60 天以上未活动的 open Issue，生成报告后等我确认。"
|
||
|
||
AI 会：
|
||
|
||
1. 拉取所有 open Issue/PR
|
||
2. 按时间过滤 + 白名单豁免 + AI 判断
|
||
3. 展示表格报告（含 confidence）
|
||
4. 等你确认后才执行 mark_stale / auto_close 动作
|
||
|
||
---
|
||
|
||
## 📁 Skill 结构
|
||
|
||
```
|
||
gitlink-stale/
|
||
├── README.md # 本文件
|
||
├── SKILL.md # AI Agent 读取的主入口
|
||
├── references/
|
||
│ ├── gitlink-stale-scan.md # 扫描算法详解
|
||
│ ├── gitlink-stale-judge.md # AI 判断规则详解
|
||
│ ├── gitlink-stale-actions.md # 动作执行手册
|
||
│ └── gitlink-stale-exempt.md # 白名单豁免规则
|
||
├── examples/
|
||
│ ├── weekly-cleanup-workflow.md # 每周清理工作流
|
||
│ ├── pr-stale-workflow.md # PR 催办工作流
|
||
│ └── ai-judgment-demo.md # AI 判断示例
|
||
└── skill_test.md # 测试指南
|
||
```
|
||
|
||
---
|
||
|
||
## 🧠 核心差异化（vs GitHub stale-bot）
|
||
|
||
| 维度 | GitHub stale-bot | gitlink-stale（本 Skill） |
|
||
|------|-----------------|------------------------|
|
||
| **触发** | 事件驱动（cron），自动跑 | Agent 驱动（按需），人在环路 |
|
||
| **判断** | 仅看时间（>= 60 天） | 时间 + AI 判断"真僵尸" |
|
||
| **白名单** | 简单 label 匹配 | 多信号（label + tracker + priority + 作者活跃度） |
|
||
| **评论** | 固定模板 | 根据上下文动态生成 |
|
||
| **回滚** | 难（已自动关闭） | 字段快照，一键恢复 |
|
||
| **审计** | 日志在 Actions | JSON 报告 + 备份文件 |
|
||
|
||
**关键差异**：本 Skill 不是简单按时间一刀切，而是通过 AI 判断评论历史、活跃度等信号决定"是否真应该处理"。
|
||
|
||
---
|
||
|
||
## 🛡️ 安全设计
|
||
|
||
| 机制 | 说明 |
|
||
|------|------|
|
||
| ✅ Dry-run 默认 | 分析阶段不调用任何写 API |
|
||
| ✅ 双重确认 | 应用动作前必须表格展示 + 用户同意 |
|
||
| ✅ 白名单豁免 | pinned/security/roadmap 永不动 |
|
||
| ✅ AI 双重判断 | 不仅看时间，还要 AI 判断"真僵尸" |
|
||
| ✅ 低置信度跳过 | confidence < 0.6 不自动处理 |
|
||
| ✅ 字段快照 | 每个变更保留原始标签和状态，支持回滚 |
|
||
| ✅ 批次上限 | 单批 ≤ 20 个，超出强制分批 |
|
||
|
||
---
|
||
|
||
## 🤖 AI Agent 兼容性
|
||
|
||
已在以下 Agent 平台设计兼容：
|
||
|
||
- ✅ **Claude Code** — 主要验证目标，所有示例均可执行
|
||
- ✅ **Cursor** — 通过 SKILL.md markdown 协议兼容
|
||
- ✅ **OpenAI Code** — 通过 references/ 文档兼容
|
||
|
||
---
|
||
|
||
## 📚 相关文档
|
||
|
||
- [SKILL.md — AI Agent 主入口](./SKILL.md)
|
||
- [扫描算法详解](./references/gitlink-stale-scan.md)
|
||
- [AI 判断规则详解](./references/gitlink-stale-judge.md)
|
||
- [动作执行手册](./references/gitlink-stale-actions.md)
|
||
- [白名单豁免规则](./references/gitlink-stale-exempt.md)
|
||
- [每周清理工作流示例](./examples/weekly-cleanup-workflow.md)
|
||
- [PR 催办示例](./examples/pr-stale-workflow.md)
|
||
- [AI 判断演示](./examples/ai-judgment-demo.md)
|
||
- [测试指南](./skill_test.md)
|
||
- [上游 Skill: gitlink-issue](../gitlink-issue/SKILL.md)
|
||
- [互补 Skill: gitlink-issue-triage](../gitlink-issue-triage/SKILL.md)
|
||
- [共享规则: gitlink-shared](../gitlink-shared/SKILL.md)
|
||
|
||
---
|
||
|
||
## ❓ FAQ
|
||
|
||
**Q: 必须用 AI Agent 吗？人能用吗？**
|
||
A: 当然可以。SKILL.md 中的工作流对人类也是清晰的 SOP，你可以手动按步骤执行 gitlink-cli 命令。AI 的价值在 Stage C "真假僵尸判断"，但人类读评论历史同样能做。
|
||
|
||
**Q: PR 没有 label 接口怎么打 stale？**
|
||
A: GitLink PR 端点暂不支持 PR 维度的标签。对 PR 只做评论催办，在评论标题写"⏰ Stale"作为视觉提示。
|
||
|
||
**Q: 用户回复后会自动去掉 stale 标签吗？**
|
||
A: 默认不会自动响应。下次扫描时看到新活动会自动跳过；如需立刻移除，手动调用 `issue +label-remove`。
|
||
|
||
**Q: 与 GitHub Actions 的 stale-bot 有何不同？**
|
||
A: 本 Skill 是 **Agent-driven**（按需触发、人在环路、AI 智能判断），不是 **Event-driven**（自动触发、机械规则）。适合需要人工监督和精准判断的高质量项目。
|
||
|
||
**Q: 误关了重要 Issue 怎么办？**
|
||
A: 见 SKILL.md §8 回滚策略。所有动作都保留原始字段快照，可重新打开。强烈建议 urgent/roadmap 类 Issue 打上对应标签加入白名单。
|
||
|
||
---
|
||
|
||
## 📄 许可证
|
||
|
||
继承 gitlink-cli 的 [MulanPSL-2.0](../../LICENSE)。
|