# gitlink-stale

> GitLink Stale Issue/PR 自动处理 Skill — 让 AI Agent 帮你清理堆积如山的未活动 Issue/PR

[![Skill](https://img.shields.io/badge/Skill-gitlink--stale-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-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)。
