From 1ae613717bf4fb8a10c61ef5cd1decf5e465c623 Mon Sep 17 00:00:00 2001
From: Ct201314 <1195214305@qq.com>
Date: Sat, 6 Jun 2026 15:31:10 +0800
Subject: [PATCH] feat(skills): add gitlink-stale skill

---
 skills/gitlink-stale/SKILL.md                 | 82 +++++++++++++++++++
 .../gitlink-stale/references/api-reference.md | 55 +++++++++++++
 skills/gitlink-stale/references/grading.md    | 34 ++++++++
 3 files changed, 171 insertions(+)
 create mode 100644 skills/gitlink-stale/SKILL.md
 create mode 100644 skills/gitlink-stale/references/api-reference.md
 create mode 100644 skills/gitlink-stale/references/grading.md

diff --git a/skills/gitlink-stale/SKILL.md b/skills/gitlink-stale/SKILL.md
new file mode 100644
index 0000000..585720b
--- /dev/null
+++ b/skills/gitlink-stale/SKILL.md
@@ -0,0 +1,82 @@
+---
+name: gitlink-stale
+version: 1.0.0
+description: "陈旧 Issue/PR 清理：检测久未更新的开放 Issue 与 PR，按陈旧度分级（活跃/留意/陈旧/僵尸），生成清理建议清单。当用户提到「陈旧 Issue」「积压」「久未更新」「清理 Issue」「stale」「僵尸 PR」「待清理」时触发。"
+metadata:
+  requires:
+    bins: ["gitlink-cli"]
+    optional_bins: ["python"]
+  cliHelp: "gitlink-cli issue --help"
+---
+
+# gitlink-stale（陈旧 Issue/PR 清理）
+
+**CRITICAL — 开始前先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md)，其中包含认证、权限处理和 API 注意事项。**
+**CRITICAL — GitLink 操作只能用 `gitlink-cli`。禁止用 `gh`（GitHub CLI）操作 GitLink 资源。**
+**CRITICAL — 关闭 Issue/PR 属于写操作，执行前必须征得用户确认。本技能只生成建议清单，不自动关闭。**
+
+> **前置条件：** 先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md)。
+
+## 何时使用本技能
+
+- 维护者想清理长期无人跟进的 Issue/PR，控制积压
+- 用户问「有哪些 Issue 很久没动了」「该清理哪些 PR」
+- 定期做 backlog 健康检查
+
+## 何时不使用
+
+- 项目综合健康度 → 用 `gitlink-health` / `gitlink-insight`
+- 普通列出 Issue/PR → 用 `gitlink-issue` / `gitlink-pr`
+
+## 陈旧度分级
+
+| 等级 | 停滞时长 | 含义 |
+|:----:|:--------:|------|
+| 🟢 活跃 | ≤ 14 天 | 近期有更新 |
+| 🟡 留意 | ≤ 45 天 | 开始放缓 |
+| 🟠 陈旧 | ≤ 120 天 | 需要跟进 |
+| 🔴 僵尸 | > 120 天 | 建议评估关闭 |
+
+## 工作流：扫描陈旧项
+
+### 方式 A：配套脚本（推荐）
+
+```bash
+python scripts/stale.py --owner Gitlink --repo gitlink-cli
+python scripts/stale.py --owner Gitlink --repo gitlink-cli --format json
+```
+
+参数说明：
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|:----:|------|
+| `--owner` / `--repo` | string | 是* | 仓库（*或用 `--slug`） |
+| `--slug` | string | 否 | `owner/repo` 或完整 URL |
+| `--format` | string | 否 | `markdown`（默认）或 `json` |
+| `--output` | string | 否 | 输出文件 |
+
+### 方式 B：用 gitlink-cli 命令
+
+```bash
+gitlink-cli issue +list --owner Gitlink --repo gitlink-cli --state open --format json
+gitlink-cli pr +list --owner Gitlink --repo gitlink-cli --state open --format json
+```
+
+### 处理建议（写操作，需确认）
+
+```bash
+# 确认后关闭陈旧 Issue（web 序号）
+gitlink-cli issue +close --owner Gitlink --repo gitlink-cli --number <web序号>
+```
+
+## API 注意事项
+
+- 停滞天数依据 `updated_at` / `created_at` 的相对时间（如"2个月前"）估算，为粗略值。
+- 只扫描开放项（Issue 状态非「关闭」、PR `pull_request_status=0`）。
+- 关闭操作是写操作，本技能只给建议，需用户确认后执行。
+
+## References
+
+- [api-reference.md](references/api-reference.md) — 采集接口与字段
+- [grading.md](references/grading.md) — 陈旧度分级与时间估算规则
+- [gitlink-shared](../gitlink-shared/SKILL.md) — 认证、全局参数、安全规则
diff --git a/skills/gitlink-stale/references/api-reference.md b/skills/gitlink-stale/references/api-reference.md
new file mode 100644
index 0000000..d5bbe73
--- /dev/null
+++ b/skills/gitlink-stale/references/api-reference.md
@@ -0,0 +1,55 @@
+# gitlink-stale API 参考
+
+> **前置条件：** 先阅读 [`../../gitlink-shared/SKILL.md`](../../gitlink-shared/SKILL.md)。
+
+本技能采集只读；关闭操作由维护者确认执行。
+
+## 采集的接口
+
+### Issue 列表
+
+```
+GET /:owner/:repo/issues.json?page=1&limit=50
+```
+
+使用字段：
+
+| 字段 | 用途 |
+|------|------|
+| `id` / `name` / `subject` | 编号与标题 |
+| `issue_status` | 过滤已关闭（含"关"/closed 的跳过） |
+| `updated_at` / `created_at` | 相对时间，估算停滞天数 |
+| `author_login` | 作者 |
+
+### PR 列表
+
+```
+GET /:owner/:repo/pulls.json?page=1&limit=50
+```
+
+| 字段 | 用途 |
+|------|------|
+| `pull_request_number` | 编号 |
+| `pull_request_status` | 仅取 0（open） |
+| `pr_time` / `updated_at` | 相对时间，估算停滞天数 |
+
+## 时间估算
+
+`updated_at`/`created_at` 多为相对时间字符串（"3天前"/"2个月前"/"1年前"），
+本技能用正则换算为天数：天/周(×7)/月(×30)/年(×365)，"刚刚/小时"记为 0。
+这是粗略估算，用于分级而非精确计时。
+
+## 写操作（关闭）
+
+```
+gitlink-cli issue +close --owner <o> --repo <r> --number <web序号>
+```
+
+属写操作，需用户确认。本技能只生成建议清单。
+
+## 输出字段（JSON）
+
+```json
+{"total_open": 27, "by_grade": {"活跃":20,"留意":6,"陈旧":1},
+ "cleanup_count": 1, "cleanup": [{"kind","id","title","age_days","grade","author"}]}
+```
diff --git a/skills/gitlink-stale/references/grading.md b/skills/gitlink-stale/references/grading.md
new file mode 100644
index 0000000..4c5ca46
--- /dev/null
+++ b/skills/gitlink-stale/references/grading.md
@@ -0,0 +1,34 @@
+# 陈旧度分级与时间估算规则
+
+## 分级阈值
+
+按"最近更新距今天数"分四级：
+
+| 等级 | 停滞天数 | emoji | 处理建议 |
+|:----:|:--------:|:-----:|----------|
+| 活跃 | ≤ 14 | 🟢 | 无需处理 |
+| 留意 | 15 – 45 | 🟡 | 关注进展 |
+| 陈旧 | 46 – 120 | 🟠 | 跟进或补充信息 |
+| 僵尸 | > 120 | 🔴 | 评估关闭 |
+| 未知 | 无法解析时间 | ⚪ | 人工核对 |
+
+阈值集中在 `scripts/stale.py` 的 `grade()` 函数，可按项目节奏调整。
+
+## 时间估算规则
+
+停滞天数来自 `updated_at`/`created_at` 的相对时间字符串：
+
+| 文本 | 换算 |
+|------|------|
+| 刚刚 / N 秒前 / N 分钟前 / N 小时前 | 0 天 |
+| N 天前 | N |
+| N 周前 | N × 7 |
+| N 个月前 / N月前 | N × 30 |
+| N 年前 | N × 365 |
+
+无法解析时记为"未知"，不计入清理建议。
+
+## 清理清单
+
+「陈旧」+「僵尸」项进入清理建议清单，按停滞天数降序，最多展示 30 条。
+报告同时给出分等级的处理建议与关闭命令示例。