diff --git a/skills/gitlink-issue-tag/SKILL.md b/skills/gitlink-issue-tag/SKILL.md new file mode 100644 index 0000000..7f5b775 --- /dev/null +++ b/skills/gitlink-issue-tag/SKILL.md @@ -0,0 +1,615 @@ +--- +name: gitlink-issue-tag +version: 2.0.0 +description: "项目标记管理:查看、创建、修改、删除 GitLink 仓库的项目标记(Issue 标签)。当用户需要管理仓库的 Issue 标签/标记时触发,如添加标签、修改标签颜色、删除标签等。" +metadata: + requires: + bins: ["gitlink-cli"] + cliHelp: "gitlink-cli api --help" +--- + +# gitlink-tag(项目标记管理) + +**CRITICAL — 开始前必须先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md),其中包含认证、权限处理和 API 注意事项。** +**CRITICAL — 所有写入/删除操作前,务必先确认用户意图。** +**CRITICAL — 项目标记通过 `gitlink-cli api` 操作,无需本地 git 命令。** + +> **前置条件:** 先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md) + +## 功能概述 + +本技能覆盖 GitLink 项目标记(Issue 标签)的完整生命周期管理,包括: + +1. **查看标记** — 列出仓库所有项目标记,支持关键词搜索和精简模式 +2. **创建标记** — 创建新标记,设置名称、描述和颜色 +3. **修改标记** — 修改已有标记的名称、描述或颜色 +4. **删除标记** — 删除不再需要的标记 + +--- + +## API 能力说明 + +GitLink API 对项目标记(issue_tags)的完整支持: + +| 操作 | HTTP 方法 | API 路径 | 说明 | +|------|-----------|---------|------| +| 查询标记列表 | GET | `/v1/{owner}/{repo}/issue_tags` | 支持 keyword/only_name/sort_by/sort_direction/limit/page 参数 | +| 创建标记 | POST | `/v1/{owner}/{repo}/issue_tags` | 请求体:{name, description, color} | +| 修改标记 | PATCH | `/v1/{owner}/{repo}/issue_tags/{id}` | 请求体:{name, description, color},路径参数 id 为标记 ID | +| 删除标记 | DELETE | `/v1/{owner}/{repo}/issue_tags/{id}` | 路径参数 id 为标记 ID | + +> **核心原则:** 所有操作均通过 `gitlink-cli api` 调用,无需本地 git 命令。 + +--- + +## 一、查看标记 + +### 1.1 列出仓库所有项目标记 + +```bash +# 获取项目标记完整列表(含描述、颜色、关联 Issue 数量等) +gitlink-cli api GET /v1/:owner/:repo/issue_tags --format json +``` + +**返回数据结构**: + +| 字段 | 类型 | 说明 | +|------|------|------| +| total_count | integer | 标记总数 | +| issue_tags | array | 标记列表 | +| issue_tags[].id | integer | 标记 ID(修改/删除时使用) | +| issue_tags[].name | string | 标记名称 | +| issue_tags[].description | string | 标记描述 | +| issue_tags[].color | string | 标记颜色(十六进制色值,如 #F17013) | +| issue_tags[].issues_count | integer | 关联的 Issue 数量 | +| issue_tags[].pull_requests_count | integer | 关联的 PR 数量 | +| issue_tags[].user | object | 创建者信息(id/name/login/image_url) | +| issue_tags[].created_at | string | 创建时间(如 2023-02-15 11:02) | +| issue_tags[].updated_at | string | 更新时间 | + +### 1.2 按关键词搜索标记 + +```bash +# 搜索名称中包含关键词的标记 +gitlink-cli api GET /v1/:owner/:repo/issue_tags --query 'keyword=bug' --format json +``` + +**支持的查询参数**: + +| 参数 | 类型 | 必选 | 说明 | +|------|------|------|------| +| keyword | string | 否 | 搜索关键词,匹配标记名称 | +| only_name | string | 否 | 设为 `true` 时只返回名称和 ID,不返回描述等详细信息 | +| sort_by | string | 否 | 排序字段:`updated_on`(更新时间)/ `created_on`(创建时间)/ `issues_count`(Issue 数量) | +| sort_direction | string | 否 | 排序方向:`desc`(倒序)/ `asc`(正序) | + +### 1.3 仅获取标记名称和 ID + +```bash +# 仅返回名称和 ID(适用于选择标记、快速浏览等场景) +gitlink-cli api GET /v1/:owner/:repo/issue_tags --query 'only_name=true' --format json +``` + +**返回示例**: + +```json +{ + "total_count": 3, + "issue_tags": [ + { "id": 1, "name": "bug" }, + { "id": 2, "name": "feature" }, + { "id": 3, "name": "documentation" } + ] +} +``` + +### 1.4 按指定字段排序 + +```bash +# 按 Issue 数量倒序排列(找出最常用的标记) +gitlink-cli api GET /v1/:owner/:repo/issue_tags --query 'order_by=issues_count&order_direction=desc' --format json + +# 按创建时间正序排列(最早创建的排前面) +gitlink-cli api GET /v1/:owner/:repo/issue_tags --query 'order_by=created_on&order_direction=asc' --format json + +# 按更新时间倒序排列(最近更新的排前面) +gitlink-cli api GET /v1/:owner/:repo/issue_tags --query 'order_by=updated_on&order_direction=desc' --format json +``` + +--- + +## 二、创建标记 + +### 2.1 创建单个标记 + +```bash +# 创建一个项目标记 +gitlink-cli api POST /v1/:owner/:repo/issue_tags --body '{"name":"测试11","description":"111","color":"#54ff85"}' --format json +``` + +**请求体参数**: + +| 参数 | 类型 | 必选 | 说明 | +|------|------|------|------| +| name | string | 是 | 标记名称 | +| description | string | 是 | 标记描述 | +| color | string | 是 | 标记颜色(十六进制色值,如 #54ff85) | + +**返回示例**: + +```json +{ + "status": 0, + "message": "success" +} +``` + +> **注意**:创建成功后 API 仅返回 status 和 message,建议立即调用查询接口确认新标记已生效。 + +### 2.2 标记颜色选择 + +AI 创建标记时,如用户未指定颜色,可按标记用途推荐默认颜色: + +| 标记类型 | 推荐颜色 | 色值 | 示例用途 | +|---------|---------|------|---------| +| 🐛 缺陷 | 红色 | `#ee0701` | bug、critical、security | +| ✨ 新功能 | 蓝色 | `#0075ca` | feature、enhancement | +| 📝 文档 | 深青 | `#0075ca` | documentation、docs | +| ❓ 疑问 | 绿色 | `#008672` | question、help-wanted | +| 🎨 优化 | 紫 | `#5319e7` | refactor、performance | +| ⚠️ 待确认 | 黄色 | `#fbca04` | wontfix、invalid、duplicate | +| 🚀 发布 | 橙色 | `#f17013` | release、milestone | +| 🧪 测试 | 青 | `#54ff85` | testing、experimental | + +### 2.3 创建后验证 + +```bash +# 创建标记后,通过关键词搜索确认 +gitlink-cli api GET /v1/:owner/:repo/issue_tags --query 'keyword=测试11' --format json +``` + +### 2.4 批量创建标记 + +当用户需要一次创建多个标记时,逐个调用创建 API: + +```bash +# 批量创建标记(逐个调用) +gitlink-cli api POST /v1/:owner/:repo/issue_tags --body '{"name":"bug","description":"Bug 修复","color":"#ee0701"}' --format json +gitlink-cli api POST /v1/:owner/:repo/issue_tags --body '{"name":"feature","description":"新功能","color":"#0075ca"}' --format json +gitlink-cli api POST /v1/:owner/:repo/issue_tags --body '{"name":"documentation","description":"文档相关","color":"#0075ca"}' --format json + +# 验证创建结果 +gitlink-cli api GET /v1/:owner/:repo/issue_tags --query 'only_name=true' --format json +``` + +> **⚠️ 批量创建前,先查询现有标记,避免创建重复名称的标记。** + +--- + +## 三、修改标记 + +### 3.1 修改标记 + +修改标记需要使用标记的 **ID**(不是名称)。先查询获取 ID,再调用修改接口。 + +```bash +# Step 1:查询标记列表,获取目标标记的 ID +gitlink-cli api GET /v1/:owner/:repo/issue_tags --format json +# 在返回结果中找到目标标记的 id 字段 + +# Step 2:使用 ID 修改标记 +gitlink-cli api PATCH /v1/:owner/:repo/issue_tags/:id --body '{"name":"测试11","description":"1112","color":"#54ff85"}' --format json +``` + +**请求体参数**(与创建相同): + +| 参数 | 类型 | 必选 | 说明 | +|------|------|------|------| +| name | string | 是 | 修改后的标记名称 | +| description | string | 是 | 修改后的标记描述 | +| color | string | 是 | 修改后的标记颜色 | + +**返回示例**: + +```json +{ + "status": 0, + "message": "success" +} +``` + +### 3.2 常见修改场景 + +**修改标记名称**: + +```bash +# 查询获取 ID +gitlink-cli api GET /v1/:owner/:repo/issue_tags --query 'keyword=旧名称' --format json +# 假设返回 id=5 + +# 修改名称(保持描述和颜色不变) +gitlink-cli api PATCH /v1/:owner/:repo/issue_tags/5 --body '{"name":"新名称","description":"原描述","color":"#ee0701"}' --format json +``` + +**修改标记颜色**: + +```bash +# 查询获取 ID +gitlink-cli api GET /v1/:owner/:repo/issue_tags --query 'keyword=bug' --format json +# 假设返回 id=3 + +# 修改颜色(保持名称和描述不变) +gitlink-cli api PATCH /v1/:owner/:repo/issue_tags/3 --body '{"name":"bug","description":"Bug 修复","color":"#ff0000"}' --format json +``` + +**修改标记描述**: + +```bash +# 查询获取 ID +gitlink-cli api GET /v1/:owner/:repo/issue_tags --query 'keyword=feature' --format json +# 假设返回 id=7 + +# 修改描述 +gitlink-cli api PATCH /v1/:owner/:repo/issue_tags/7 --body '{"name":"feature","description":"新的功能需求描述","color":"#0075ca"}' --format json +``` + +### 3.3 修改后验证 + +```bash +# 修改后查询确认变更已生效 +gitlink-cli api GET /v1/:owner/:repo/issue_tags --query 'keyword=修改后的名称' --format json +``` + +> **⚠️ 修改标记名称后,已关联该标记的 Issue 会自动更新为新名称。** + +--- + +## 四、删除标记 + +### 4.1 删除单个标记 + +删除标记需要使用标记的 **ID**。先查询获取 ID,再调用删除接口。 + +```bash +# Step 1:查询标记列表,获取目标标记的 ID +gitlink-cli api GET /v1/:owner/:repo/issue_tags --query 'keyword=要删除的标记名' --format json +# 在返回结果中找到目标标记的 id 字段 + +# Step 2:删除标记 +gitlink-cli api DELETE /v1/:owner/:repo/issue_tags/:id --format json +``` + +**返回示例**: + +```json +{ + "status": 0, + "message": "success" +} +``` + +### 4.2 完整删除流程 + +```bash +# Step 1:查看所有标记,确认要删除的目标 +gitlink-cli api GET /v1/:owner/:repo/issue_tags --format json + +# Step 2:记录目标标记的 ID 和关联 Issue 数量 +# 假设目标标记 id=5, name="deprecated", issues_count=3 + +# Step 3:向用户确认删除意图(特别是 issues_count > 0 的标记) +# ⚠️ 删除标记后,关联的 Issue 将失去该标记 + +# Step 4:执行删除 +gitlink-cli api DELETE /v1/:owner/:repo/issue_tags/5 --format json + +# Step 5:验证删除结果 +gitlink-cli api GET /v1/:owner/:repo/issue_tags --query 'keyword=deprecated' --format json +# total_count 应为 0 +``` + +### 4.3 批量删除标记 + +```bash +# Step 1:查询所有标记 +gitlink-cli api GET /v1/:owner/:repo/issue_tags --format json + +# Step 2:AI 根据用户意图筛选要删除的标记,列出 ID 列表 +# 假设要删除 id=3, id=5, id=8 + +# Step 3:逐个删除 +gitlink-cli api DELETE /v1/:owner/:repo/issue_tags/3 --format json +gitlink-cli api DELETE /v1/:owner/:repo/issue_tags/5 --format json +gitlink-cli api DELETE /v1/:owner/:repo/issue_tags/8 --format json + +# Step 4:验证删除结果 +gitlink-cli api GET /v1/:owner/:repo/issue_tags --format json +``` + +> **⚠️ 批量删除是危险操作,必须先列出待删除标记清单让用户确认后再执行。** + +--- + +## 五、高级操作 + +### 5.1 项目标记健康度检查 + +```bash +# 获取所有标记及关联 Issue 数量 +gitlink-cli api GET /v1/:owner/:repo/issue_tags --query 'order_by=issues_count&order_direction=asc' --format json +``` + +**AI 分析规则**: + +| 检查项 | 条件 | 建议 | +|--------|------|------| +| 未使用标记 | `issues_count == 0` | 考虑删除或合并 | +| 过度使用标记 | `issues_count` 为所有标记中最大值 | 考虑拆分为更细粒度的标记 | +| 标记过少 | `total_count < 3` | 建议补充常见分类标记 | +| 标记过多 | `total_count > 15` | 建议合并相似标记 | +| 无描述标记 | `description` 为空 | 建议补充描述说明 | + +### 5.2 标记规范化建议 + +当项目缺少标准标记时,AI 可推荐创建以下基础标记集: + +```bash +# 基础标记集(适用于大多数项目) +gitlink-cli api POST /v1/:owner/:repo/issue_tags --body '{"name":"bug","description":"Bug 修复或问题报告","color":"#ee0701"}' --format json +gitlink-cli api POST /v1/:owner/:repo/issue_tags --body '{"name":"feature","description":"新功能需求","color":"#0075ca"}' --format json +gitlink-cli api POST /v1/:owner/:repo/issue_tags --body '{"name":"enhancement","description":"功能优化或改进","color":"#5319e7"}' --format json +gitlink-cli api POST /v1/:owner/:repo/issue_tags --body '{"name":"documentation","description":"文档相关","color":"#0075ca"}' --format json +gitlink-cli api POST /v1/:owner/:repo/issue_tags --body '{"name":"good-first-issue","description":"适合新贡献者的问题","color":"#008672"}' --format json +gitlink-cli api POST /v1/:owner/:repo/issue_tags --body '{"name":"help-wanted","description":"需要帮助的问题","color":"#008672"}' --format json +gitlink-cli api POST /v1/:owner/:repo/issue_tags --body '{"name":"question","description":"使用疑问","color":"#fbca04"}' --format json +gitlink-cli api POST /v1/:owner/:repo/issue_tags --body '{"name":"wontfix","description":"不会处理的问题","color":"#fbca04"}' --format json +``` + +### 5.3 合并相似标记 + +当项目存在语义重复的标记时(如 "bug" 和 "defect"),AI 可建议合并: + +```bash +# Step 1:查询所有标记,AI 识别相似标记对 +gitlink-cli api GET /v1/:owner/:repo/issue_tags --format json + +# Step 2:假设 "bug"(id=3) 和 "defect"(id=7) 需要合并,保留 "bug" + +# Step 3:将 "defect" 关联的 Issue 改为 "bug"(需逐个修改 Issue 的标记) +# 先查找 "defect" 关联的 Issue 列表 +gitlink-cli issue +list --state open --owner --repo --format json +# AI 筛选标记为 "defect" 的 Issue,将其改为 "bug" + +# Step 4:删除 "defect" 标记 +gitlink-cli api DELETE /v1/:owner/:repo/issue_tags/7 --format json + +# Step 5:验证 +gitlink-cli api GET /v1/:owner/:repo/issue_tags --format json +``` + +### 5.4 查询参数组合使用 + +```bash +# 搜索关键词 + 仅返回名称 +gitlink-cli api GET /v1/:owner/:repo/issue_tags --query 'keyword=bug&only_name=true' --format json + +# 按 Issue 数量倒序 + 仅返回名称(快速查看热门标记) +gitlink-cli api GET /v1/:owner/:repo/issue_tags --query 'order_by=issues_count&order_direction=desc&only_name=true' --format json + +# 按更新时间倒序(查看最近活跃的标记) +gitlink-cli api GET /v1/:owner/:repo/issue_tags --query 'order_by=updated_on&order_direction=desc' --format json +``` + +--- + +## 六、执行步骤总览 + +### 6.1 查看标记流程 + +```bash +# Step 1:获取项目标记完整列表 +gitlink-cli api GET /v1/:owner/:repo/issue_tags --format json + +# Step 2(可选):搜索特定标记 +gitlink-cli api GET /v1/:owner/:repo/issue_tags --query 'keyword=bug' --format json + +# Step 3(可选):查看精简列表 +gitlink-cli api GET /v1/:owner/:repo/issue_tags --query 'only_name=true' --format json +``` + +### 6.2 创建标记流程 + +```bash +# Step 1:查看现有标记,避免重复 +gitlink-cli api GET /v1/:owner/:repo/issue_tags --query 'only_name=true' --format json + +# Step 2:创建标记 +gitlink-cli api POST /v1/:owner/:repo/issue_tags --body '{"name":"新标记","description":"标记描述","color":"#54ff85"}' --format json + +# Step 3:验证创建结果 +gitlink-cli api GET /v1/:owner/:repo/issue_tags --query 'keyword=新标记' --format json +``` + +### 6.3 修改标记流程 + +```bash +# Step 1:查询目标标记,获取 ID +gitlink-cli api GET /v1/:owner/:repo/issue_tags --query 'keyword=要修改的标记' --format json +# 记录目标标记的 id + +# Step 2:修改标记(使用 ID) +gitlink-cli api PATCH /v1/:owner/:repo/issue_tags/:id --body '{"name":"修改后名称","description":"修改后描述","color":"#ff0000"}' --format json + +# Step 3:验证修改结果 +gitlink-cli api GET /v1/:owner/:repo/issue_tags --query 'keyword=修改后名称' --format json +``` + +### 6.4 删除标记流程 + +```bash +# Step 1:查询目标标记,获取 ID 和关联 Issue 数量 +gitlink-cli api GET /v1/:owner/:repo/issue_tags --query 'keyword=要删除的标记' --format json +# 记录目标标记的 id 和 issues_count + +# Step 2:确认删除意图(⚠️ 如 issues_count > 0 需特别提醒) +# ⚠️ 删除标记后,关联的 Issue 将失去该标记 + +# Step 3:删除标记 +gitlink-cli api DELETE /v1/:owner/:repo/issue_tags/:id --format json + +# Step 4:验证删除结果 +gitlink-cli api GET /v1/:owner/:repo/issue_tags --format json +``` + +--- + +## 七、操作报告模板 + +### 7.1 查看标记报告 + +```markdown +## 📋 项目标记概览 + +**仓库:** / +**标记总数:** 8 + +| ID | 名称 | 描述 | 颜色 | 关联 Issue | 创建时间 | +|----|------|------|------|-----------|---------| +| 1 | bug | Bug 修复或问题报告 | 🟡 #ee0701 | 12 | 2025-01-10 | +| 2 | feature | 新功能需求 | 🔵 #0075ca | 8 | 2025-01-10 | +| 3 | documentation | 文档相关 | 🔵 #0075ca | 3 | 2025-02-15 | +| ... | ... | ... | ... | ... | ... | + +**健康度分析:** +- ⚠️ "deprecated" 标记关联 0 个 Issue,建议删除 +- ✅ 标记分类覆盖完整 +``` + +### 7.2 创建标记报告 + +```markdown +## ➕ 标记创建报告 + +**仓库:** / +**操作时间:** 2025-06-12 16:00:00 + +| 项目 | 详情 | +|------|------| +| 标记名称 | 测试11 | +| 标记描述 | 111 | +| 标记颜色 | 🟢 #54ff85 | +| 创建结果 | ✅ 成功 | + +**验证:** +- 查询确认:✅ 标记已存在于仓库 +- 重复检查:✅ 无同名标记 +``` + +### 7.3 修改标记报告 + +```markdown +## ✏️ 标记修改报告 + +**仓库:** / +**操作时间:** 2025-06-12 16:05:00 + +| 项目 | 修改前 | 修改后 | +|------|--------|--------| +| 标记 ID | 5 | 5 | +| 标记名称 | 测试11 | 测试11 | +| 标记描述 | 111 | 1112 | +| 标记颜色 | 🟢 #54ff85 | 🟢 #54ff85 | +| 修改结果 | — | ✅ 成功 | + +**影响范围:** 关联 Issue 3 个,已自动更新标记信息 +``` + +### 7.4 删除标记报告 + +```markdown +## 🗑️ 标记删除报告 + +**仓库:** / +**操作时间:** 2025-06-12 16:10:00 + +| 项目 | 详情 | +|------|------| +| 删除标记 ID | 5 | +| 删除标记名称 | deprecated | +| 关联 Issue 数 | 0 | +| 删除结果 | ✅ 成功 | +| 删除原因 | 标记未被使用 | + +⚠️ 已关联该标记的 Issue 将失去此标记。 +``` + +--- + +## 八、常见场景示例 + +### 场景 1:为新项目创建标准标记 + +``` +用户:"帮我的新仓库创建一套 Issue 标签" + +AI 执行: +1. gitlink-cli api GET /v1/:owner/:repo/issue_tags --query 'only_name=true' --format json + → 确认当前标记列表为空 +2. 逐个创建基础标记(bug/feature/enhancement/documentation/good-first-issue/help-wanted/question/wontfix) +3. 验证创建结果 +4. 输出创建报告 +``` + +### 场景 2:修改标记颜色 + +``` +用户:"把 bug 标签的颜色改成红色" + +AI 执行: +1. gitlink-cli api GET /v1/:owner/:repo/issue_tags --query 'keyword=bug' --format json + → 获取 id 和当前信息 +2. gitlink-cli api PATCH /v1/:owner/:repo/issue_tags/:id --body '{"name":"bug","description":"原描述","color":"#ee0701"}' --format json +3. 验证修改结果 +4. 输出修改报告 +``` + +### 场景 3:清理未使用的标记 + +``` +用户:"删除没有关联任何 Issue 的标签" + +AI 执行: +1. gitlink-cli api GET /v1/:owner/:repo/issue_tags --query 'order_by=issues_count&order_direction=asc' --format json +2. AI 筛选 issues_count == 0 的标记 +3. 列出待删除标记清单,请用户确认 +4. 确认后逐个删除 +5. 输出删除报告 +``` + +### 场景 4:搜索并合并重复标记 + +``` +用户:"检查有没有重复的标签" + +AI 执行: +1. gitlink-cli api GET /v1/:owner/:repo/issue_tags --format json +2. AI 分析语义相似的标记对(如 bug/defect、feature/enhancement) +3. 列出建议合并的标记对,请用户确认 +4. 执行合并(迁移 Issue 标记 → 删除冗余标记) +5. 输出合并报告 +``` + +--- + +## 注意事项 + +- ✅ **修改和删除需要 ID**:`PATCH` 和 `DELETE` 接口使用标记 ID(非名称),操作前必须先查询获取 ID +- ✅ **创建前检查重复**:先查询现有标记列表,避免创建同名标记 +- ✅ **删除前确认影响**:查看标记的 `issues_count`,如大于 0 需提醒用户删除后关联 Issue 会丢失该标记,待用户确认后再执行 +- ✅ **请求体三个字段**:创建和修改的请求体均需包含 `name`、`description`、`color` 三个字段 +- ✅ **颜色格式**:使用十六进制色值,格式为 `#RRGGBB`(如 `#ee0701`) +- ✅ **创建/修改后验证**:API 仅返回 `{status, message}`,需查询确认操作是否生效 +- ⚠️ **标记名称唯一**:同一仓库下标记名称不能重复 +- ✅ **排序参数**:`sort_by` 支持 `updated_on`、`created_on`、`issues_count`,`sort_direction` 支持 `desc`、`asc` +- ✅ **所有操作通过 gitlink-cli api**:无需本地 git 命令,所有增删查改均通过 API 完成 + diff --git a/skills/gitlink-stale-issue-manager/SKILL.md b/skills/gitlink-stale-issue-manager/SKILL.md new file mode 100644 index 0000000..431a6f1 --- /dev/null +++ b/skills/gitlink-stale-issue-manager/SKILL.md @@ -0,0 +1,562 @@ +--- +name: gitlink-stale-issue-manager +version: 1.0.0 +description: "过期 Issue 管理:自动识别长期无活动的 Issue,按过期等级标记/提醒/批量关闭,支持白名单保护和干运行模式。当用户需要清理过期 Issue、管理社区积压、维护仓库活跃度时触发。" +metadata: + requires: + bins: ["gitlink-cli"] + cliHelp: "gitlink-cli issue --help" +--- + +# gitlink-stale-issue-manager(过期 Issue 管理) + +**CRITICAL — 开始前必须先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md),其中包含认证、权限处理和 API 注意事项。** +**CRITICAL — 关闭操作不可逆,务必先以干运行模式确认再执行。** +**CRITICAL — GitLink 操作只能用 `gitlink-cli`。** + +> **前置条件:** 先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md) + +--- + +## 功能概述 + +本技能解决活跃仓库的 Issue 积压问题,提供完整的过期项管理流程: + +1. **过期扫描** — 获取所有打开的 Issue,按最后活动时间分类 +2. **分级标记** — 按过期天数自动打标签和发提醒评论 +3. **批量关闭** — 对超期严重的 Issue 执行关闭 +4. **白名单保护** — 保护特定标签的 Issue 不被关闭 +5. **干运行模式** — 先预览操作结果,确认后再执行 +6. **执行报告** — 统计本次操作的详细结果 + +--- + +## 一、过期扫描:获取所有打开的 Issue + +### 1.1 获取 Issue 列表 + +```bash +# 获取所有打开的 Issue, 如果列表数量过大(>20),需要翻页处理 +gitlink-cli issue +list --state open --owner --repo --page 1 --limit 20 --format json +``` + +**AI 必须提取的关键字段**: +- `number`:Issue ID(后续打标签/评论/关闭时使用) +- `subject`:Issue 标题(用于判断是否值得保留) +- `created_at`:创建时间 +- `updated_at`:最后更新时间(**核心判断依据**) +- `tags`:已有标签(打标签时需要保留原有tags / 白名单判断) + + +### 1.2 获取 Issue 评论(精确判断最后活动时间) + +```bash +# 获取某个 Issue 的评论列表(如果数据量过大,可能需要翻到最后一页取最后十条) +gitlink-cli api GET /v1/:owner/:repo/issues/:number/journals?category=comment&page=1&limit=50 --format json +``` + +**AI 判断逻辑**: + +``` +只有当 Issue 的 created_at 和 updated_at 不同时,才需要查询评论列表。 +如果 created_at == updated_at,说明没有任何更新,直接使用 created_at 作为最后活动时间。 +``` + +**评论列表返回数据结构**: + +| 字段 | 类型 | 说明 | +|------|------|------| +| journals | array | 评论列表 | +| journals[].id | integer | 评论 ID | +| journals[].notes | string | 评论内容 | +| journals[].created_at | string | 评论创建时间 | +| journals[].user | object | 评论者信息 | + +> **注意**:评论列表按创建时间正序排列,取最后一条即为最新评论。 + +### 1.4 计算过期天数 + +``` +过期天数 = 当前日期 - 最后活动日期 + +最后活动日期的确定优先级: +1. Issue 最新一条评论的时间(优先)— 只有当 created_at != updated_at 时才查询评论 +2. Issue 的 updated_at 字段(其次) +3. Issue 的 created_at 字段(保底) + +判断流程: +├─ created_at == updated_at? +│ └─ 是 → 最后活动日期 = created_at(无任何更新,无需查询评论) +│ └─ 否 → 查询评论列表 +│ ├─ 有评论?→ 最后活动日期 = 最新一条评论的 created_at +│ └─ 无评论?→ 最后活动日期 = updated_at +``` + +> **注意**:此处需要额外注意,必须排除掉该skill自动发送的评论!如果排除掉之后没有其他评论,则以create_at作为最后活动日期。 + +--- + +## 二、分级标记:按过期等级自动处理 + +### 2.1 过期等级定义 + +| 等级 | 过期天数 | 标签 | 操作 | 评论内容 | +|------|---------|------|------|---------| +| 🟢 健康 | 0-29 天 | 无 | 无 | 无 | +| 🟡 迟缓 | 30-59 天 | `迟缓` | 打标签 + 发提醒 | 温和提醒,7天内回复可移除标签 | +| 🟠 不活跃 | 60-89 天 | `不活跃` | 更新标签 + 再次提醒 | 严重警告,即将被关闭 | +| 🔴 过期 | ≥90 天 | `过期` | 更新标签 + 关闭 | 关闭通知,可随时重新打开 | + +### 2.2 打标签操作 + +**CRITICAL — 打标签前必须先确保标签存在,不存在则创建。** + +#### 2.2.1 标签预创建流程 + +``` +打标签前,必须执行以下流程: +1. 获取仓库现有标签列表 +2. 检查目标标签(迟缓/不活跃/过期)是否已存在 +3. 如果标签不存在,先创建标签 +4. 获取标签 ID 后,再为 Issue 打标签 +``` + +```bash +# Step 1:获取仓库现有标签列表 +gitlink-cli api GET /v1/:owner/:repo/issue_tags --format json + +# Step 2:检查目标标签是否已存在(AI 在返回结果中查找) +# 如果目标标签不存在,则创建: + +# 创建"迟缓"标签(30-59天) +gitlink-cli api POST /v1/:owner/:repo/issue_tags --body '{"name":"迟缓","description":"近期活动频率明显下降,需关注但尚未停滞","color":"#fbca04"}' --format json + +# 创建"不活跃"标签(60-89天) +gitlink-cli api POST /v1/:owner/:repo/issue_tags --body '{"name":"不活跃","description":"长期无更新或互动,可能已失去推进动力","color":"#d93f0b"}' --format json + +# 创建"过期"标签(≥90天) +gitlink-cli api POST /v1/:owner/:repo/issue_tags --body '{"name":"过期","description":"已超出合理响应周期,建议关闭或重新评估","color":"#b60205"}' --format json + +# Step 3:重新获取标签列表,确认标签 ID +gitlink-cli api GET /v1/:owner/:repo/issue_tags --format json +``` + +**标签与过期等级对应关系**: + +| 过期等级 | 标签名 | 颜色 | 描述 | +|---------|--------|------|------| +| 🟡 迟缓(30-59天) | 迟缓 | `#fbca04` | 近期活动频率明显下降,需关注但尚未停滞 | +| 🟠 不活跃(60-89天) | 不活跃 | `#d93f0b` | 长期无更新或互动,可能已失去推进动力 | +| 🔴 过期(≥90天) | 过期 | `#b60205` | 已超出合理响应周期,建议关闭或重新评估 | + +#### 2.2.2 为 Issue 打标签 + +```bash +# 为 Issue 打标签,通过 PATCH 修改 Issue 的 issue_tag_ids 字段 +# 注意:issue_tag_ids 是数组,追加标签时需包含已有标签 ID +gitlink-cli api PATCH /v1/:owner/:repo/issues/:id --body '{"issue_tag_ids":[]}' --format json + +# 示例:为 Issue 追加"迟缓"标签(假设迟缓标签 ID 为 374033) +gitlink-cli api PATCH /v1/:owner/:repo/issues/:id --body '{"issue_tag_ids":[374033]}' --format json + +# 示例:Issue 已有标签 ID 315216,追加迟缓标签 ID 374033 +gitlink-cli api PATCH /v1/:owner/:repo/issues/:id --body '{"issue_tag_ids":[315216,374033]}' --format json +``` + +> **⚠️ 重要**:`issue_tag_ids` 是完整替换而非追加,设置时必须包含 Issue 已有的所有标签 ID,否则已有标签会被移除。操作前需先查询 Issue 当前的标签列表。 + +### 2.3 提醒评论模板 + +**🟡 30-59 天(stale 提醒)**: + +```markdown +**⚠️ Stale Issue 提醒** + +此 Issue 已 **{days}** 天无活动。 + +为保持仓库 Issue 列表的整洁,如果 **7 天内** 没有新的回复,此 Issue 将被标记为 `不活跃`。 + +**如果你仍在关注此问题**,请留下一条评论(哪怕只是 "仍在关注"),即可重置活动计时。 + +--- +*此消息由 [gitlink-stale-issue-manager] 自动发送* +``` + +**🟠 60-89 天(inactive 警告)**: + +```markdown +**🔴 Inactive Issue 警告** + +此 Issue 已 **{days}** 天无活动。 + +如果 **7 天内** 没有新的回复,此 Issue 将被自动关闭。 + +**如何保留此 Issue**: +- 留下评论说明当前进展 +- 分配责任人 +- 添加 `置顶` 标签永久保留 + +--- +*此消息由 [gitlink-stale-issue-manager] 自动发送* +``` + +**🔴 ≥90 天(关闭通知)**: + +```markdown +**🔒 过期 Issue 关闭通知** + +此 Issue 已 **{days}** 天无活动,现被自动关闭。 + +这不是对问题本身的否定,而是为了保持 Issue 列表的清晰度。 + +**如果你认为此问题仍然有效**: +- 留下评论说明原因 +- 项目维护者可随时重新打开此 Issue + +--- +*此消息由 [gitlink-stale-issue-manager] 自动发送* +``` + +### 2.4 发送提醒评论 + +```bash +# 发送提醒评论 +gitlink-cli issue +comment \ + --number \ + --owner \ + --repo \ + --body "<上述评论模板内容>" +``` + +--- + +## 三、批量关闭:对超期严重的 Issue 执行关闭 + +### 3.1 关闭单个 Issue + +```bash +# 关闭 Issue +gitlink-cli issue +close \ + --number \ + --owner \ + --repo +``` + +### 3.2 批量关闭流程 + +**AI 必须遵循以下流程**,禁止跳步: + +``` +Step 1:扫描 — 获取所有 ≥90 天无活动的 Issue +Step 2:过滤 — 排除白名单中的 Issue(见第四章) +Step 3:预览 — 列出将被关闭的 Issue(干运行模式) +Step 4:确认 — 询问用户是否确认关闭 +Step 5:执行 — 逐一发送关闭评论 + 关闭 Issue +Step 6:报告 — 输出本次操作统计 +``` + +### 3.3 关闭前必须发送通知评论 + +**CRITICAL**:关闭 Issue 前必须先发送关闭通知评论,再执行关闭操作。 + +```bash +# 先发评论 +gitlink-cli issue +comment \ + --number \ + --owner \ + --repo \ + --body "<关闭通知模板>" + +# 再关闭 +gitlink-cli issue +close \ + --number \ + --owner \ + --repo +``` + +--- + +## 四、白名单保护:防止误关闭重要 Issue + +### 4.1 白名单标签 + +以下标签的 Issue **不会被标记为过期,也不会被关闭**: + +| 标签 | 含义 | 保护级别 | +|------|------|---------| +| `pinned` | 置顶/长期跟踪 | 永久保护 | +| `security` | 安全相关 | 永久保护 | +| `bug` | 确认的 Bug | 永久保护 | +| `enhancement` | 已确认的功能需求 | 永久保护 | +| `help-wanted` | 寻求社区帮助 | 永久保护 | +| `good-first-issue` | 新人友好 | 永久保护 | +| `wontfix` | 不修复但需保留 | 永久保护 | + +### 4.2 白名单判断逻辑 + +``` +对每个 Issue: +1. 读取其标签列表(tags 字段) +2. 如果包含白名单标签中的任意一个 → 跳过,不做任何操作 +3. 如果不包含白名单标签 → 按过期等级处理 +``` + +### 4.3 自定义白名单 + +用户可指定额外的保护标签: + +```bash +# 用户可以在对话中指定自定义白名单标签,如果不指定,则使用默认的标签 +``` + +### 4.4 Issue 标题关键词保护 + +以下标题关键词的 Issue 也应保护(即使无白名单标签): + +``` +保护关键词(标题包含即跳过): +- "[Security]" / "[安全]" +- "[Pinned]" / "[长期]" +- "[Tracking]" / "[跟踪]" +- "严重" / "紧急" / "critical" / "urgent" +``` + +--- + +## 五、干运行模式:先预览再执行 + +### 5.1 干运行逻辑 + +**CRITICAL**:首次执行时必须使用干运行模式,让用户确认后再真正执行。 + +``` +干运行模式下,AI 仅输出以下信息,不执行任何写操作: +1. 将被标记为 stale 的 Issue 列表(30-59 天) +2. 将被标记为 inactive 的 Issue 列表(60-89 天) +3. 将被关闭的 Issue 列表(≥90 天) +4. 被白名单保护的 Issue 列表 +5. 本次操作统计 +``` + +### 5.2 干运行报告格式 + +```markdown +## 🔍 过期 Issue 扫描报告(干运行) + +**仓库**:`/` +**扫描时间**:2026-06-11 +**扫描范围**:所有打开的 Issue + +--- + +### 📊 统计概览 + +| 类别 | 数量 | +|------|------| +| 打开的 Issue | 42 | +| 🟡 迟缓(30-59天) | 12 | +| 🟠 不活跃(60-89天) | 5 | +| 🔴 过期(≥90天) | 3 | +| 🛡️ 白名单保护 | 4 | + +--- + +### 🟡 将标记为 `迟缓`(12 个) + +| # | Issue | 标题 | 最后活动 | 过期天数 | +|---|-------|------|---------|---------| +| 1 | #156 | 文档中示例代码过期 | 2026-04-25 | 47 | +| 2 | #178 | 请求支持暗色模式 | 2026-04-18 | 54 | +| ... | ... | ... | ... | ... | + +### 🟠 将标记为 `不活跃`(5 个) + +| # | Issue | 标题 | 最后活动 | 过期天数 | +|---|-------|------|---------|---------| +| 1 | #98 | 首页加载速度优化 | 2026-03-15 | 88 | +| ... | ... | ... | ... | ... | + +### 🔴 将被关闭(3 个) + +| # | Issue | 标题 | 最后活动 | 过期天数 | +|---|-------|------|---------|---------| +| 1 | #45 | 旧版 API 兼容问题 | 2025-12-20 | 173 | +| 2 | #67 | 建议添加 X 功能 | 2025-11-05 | 218 | +| 3 | #89 | 拼写错误 | 2025-10-01 | 253 | + +### 🛡️ 白名单保护(4 个) + +| # | Issue | 标题 | 保护原因 | +|---|-------|------|---------| +| 1 | #12 | [Security] XSS 漏洞 | 标签:security | +| 2 | #34 | 跟踪 v2.0 发布计划 | 标签:pinned | +| 3 | #56 | 用户认证失败 | 标签:bug | +| 4 | #78 | 添加国际化支持 | 标题含 "紧急" | + +--- + +### ⚠️ 即将执行的操作 + +1. 对 12 个 Issue 添加 `迟缓` 标签并发送提醒评论 +2. 对 5 个 Issue 更新为 `不活跃` 标签并发送警告评论 +3. 对 3 个 Issue 发送关闭通知并关闭 + +**确认后将执行以上操作。是否继续?** +``` + +--- + +## 六、执行步骤总览 + +### 6.1 完整流程 + +```bash +# Step 1:获取所有打开的 Issue +gitlink-cli issue +list --state open --owner --repo --format json + +# Step 2:判断 Issue 最后活动时间 +# a. 如果 created_at == updated_at → 最后活动时间 = created_at(无需查询评论) +# b. 如果 created_at != updated_at → 查询评论列表获取最新评论时间 +gitlink-cli api GET /v1/:owner/:repo/issues/:number/journals --format json +# - 有评论 → 最后活动时间 = 最新评论的 created_at +# - 无评论 → 最后活动时间 = updated_at +# 需注意排除skill自动发送的评论内容 + +# Step 3:AI 计算过期天数,按等级分类,排除白名单 + +# Step 4(干运行):输出扫描报告,等待用户确认 + +# Step 5(执行 — 用户确认后): +# a. 预创建标签(确保标签存在) +gitlink-cli api GET /v1/:owner/:repo/issue_tags --format json +# 检查迟缓/不活跃/过期标签是否存在,不存在则创建: +gitlink-cli api POST /v1/:owner/:repo/issue_tags --body '{"name":"迟缓","description":"近期活动频率明显下降,需关注但尚未停滞","color":"#fbca04"}' --format json +gitlink-cli api POST /v1/:owner/:repo/issue_tags --body '{"name":"不活跃","description":"长期无更新或互动,可能已失去推进动力","color":"#d93f0b"}' --format json +gitlink-cli api POST /v1/:owner/:repo/issue_tags --body '{"name":"过期","description":"已超出合理响应周期,建议关闭或重新评估","color":"#b60205"}' --format json + +# b. 对 30-59 天 Issue:打"迟缓"标签 + 发提醒评论 +gitlink-cli api PATCH /v1/:owner/:repo/issues/:id --body '{"issue_tag_ids":[]}' --format json +gitlink-cli issue +comment --number --owner --repo --body "" + +# c. 对 60-89 天 Issue:打"不活跃"标签 + 发警告评论 +gitlink-cli api PATCH /v1/:owner/:repo/issues/:id --body '{"issue_tag_ids":[]}' --format json +gitlink-cli issue +comment --number --owner --repo --body "" + +# d. 对 ≥90 天 Issue:打"过期"标签 + 发关闭通知 + 关闭 +gitlink-cli api PATCH /v1/:owner/:repo/issues/:id --body '{"issue_tag_ids":[]}' --format json +gitlink-cli issue +comment --number --owner --repo --body "<关闭通知>" +gitlink-cli issue +close --number --owner --repo +``` + +### 6.2 可选:仅扫描模式 + +如果用户只想查看过期情况,不执行任何操作: + +```bash +# 仅扫描,输出报告,不修改任何 Issue +# 在干运行报告末尾提示:"本次仅扫描,未修改任何 Issue。如需执行,请告知。" +``` + +### 6.3 可选:按标签过滤扫描 + +如果用户只想扫描特定类型的 Issue: + +```bash +# 获取所有打开的 Issue(客户端按标签过滤) +gitlink-cli issue +list --state open --owner --repo --format json +# AI 在结果中筛选包含特定标签的 Issue +``` + +--- + +## 七、执行报告 + +操作完成后,输出以下格式的执行报告: + +```markdown +## ✅ 过期 Issue 管理执行报告 + +**仓库**:`/` +**执行时间**:2026-06-11 18:30 +**执行模式**:正式执行 / 仅扫描 + +--- + +### 📊 操作统计 + +| 操作 | 数量 | 成功 | 失败 | +|------|------|------|------| +| 添加 迟缓 标签 | 12 | 12 | 0 | +| 添加 不活跃 标签 | 5 | 5 | 0 | +| 发送提醒评论 | 17 | 17 | 0 | +| 关闭 Issue | 3 | 3 | 0 | +| 白名单保护跳过 | 4 | - | - | + +### 📋 已关闭的 Issue + +| # | Issue | 标题 | 过期天数 | 关闭状态 | +|---|-------|------|---------|---------| +| 1 | #45 | 旧版 API 兼容问题 | 173 | ✅ 已关闭 | +| 2 | #67 | 建议添加 X 功能 | 218 | ✅ 已关闭 | +| 3 | #89 | 拼写错误 | 253 | ✅ 已关闭 | + +### ⚠️ 失败记录 + +(无失败记录) + +--- + +### 📈 仓库健康度变化 + +| 指标 | 操作前 | 操作后 | 变化 | +|------|--------|--------|------| +| 打开的 Issue | 42 | 39 | -3 | +| 过期 Issue 占比 | 47.6% | 38.5% | -9.1% | + +--- + +*下次建议执行时间:7 天后(2026-06-18)* +``` + +--- + +## 八、可配置参数 + +用户可在对话中指定以下参数调整行为: + +| 参数 | 默认值 | 说明 | +|------|--------|------| +| `stale_days` | 30 | 标记为 stale 的天数阈值 | +| `inactive_days` | 60 | 标记为 inactive 的天数阈值 | +| `expire_days` | 90 | 自动关闭的天数阈值 | +| `grace_period` | 7 | 标记后等待回复的天数(stale → inactive 的缓冲期) | +| `dry_run` | true | 是否为干运行模式(首次必须为 true) | +| `close_expired` | false | 是否关闭过期 Issue(需用户显式确认后改为 true) | +| `protect_labels` | pinned,security,bug,enhancement,help-wanted,good-first-issue,wontfix | 白名单标签 | + +### 配置示例 + +``` +用户:"扫描过期 Issue,stale 设为 45 天,不关闭 " + +AI 应解析为: +- stale_days = 45 +- inactive_days = 75 +- expire_days = 105 +- close_expired = false +- dry_run = true(首次必须) +``` + +--- + + +## 注意事项 + +- ✅ **首次执行必须干运行**:先输出预览报告,用户确认后再执行 +- ✅ **关闭前必须发评论**:给 Issue 作者留下重新打开的途径 +- ✅ **白名单保护不可绕过**:即使过期天数超过阈值,白名单内的 Issue 也不处理 +- ✅ **批量操作逐条执行**:避免 API 限流,每条操作间隔 1 秒 +- ✅ **关闭操作不可逆**:虽然维护者可以重新打开,但评论通知已发出,应谨慎 +- ✅ **建议定期执行**:推荐每周执行一次,保持 Issue 列表健康 +- ⚠️ **标签操作**:打标签通过 `gitlink-cli api PATCH /v1/:owner/:repo/issues/:id --body '{"issue_tag_ids":[]}'` 完成,`issue_tag_ids` 为完整替换,需包含已有标签 ID +- ⚠️ **标签预创建**:打标签前必须先查询标签列表,确认目标标签存在,不存在则先通过 `POST /v1/:owner/:repo/issue_tags` 创建