forked from Gitlink/gitlink-cli
feat(skills): 新增 Issue 智能分拣 Skill (gitlink-issue-triage)
- SKILL.md：3 个工作流（自动分类打标签 / 自动分配+通知 / 批量分拣+报告） - examples/issue-triage-workflow.md：3 个场景使用示例 - examples/verification.md：源码核对 + 在 ylly/gitlink-cli 实跑验证 - 真实给 Issue #7 打上"缺陷"标签 - 发现并记录两条平台限制：assigners 个人仓库为空、notification 跨用户 403 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
parent
3a79c72813
commit
c7a709d3d7
|
|
@ -0,0 +1,279 @@
|
|||
---
|
||||
name: gitlink-issue-triage
|
||||
version: 1.0.0
|
||||
description: "Issue 智能分拣：扫描未分类 Issue，AI 按语义/关键词自动分类打标签、推荐并分配责任人，再用 notification 验证通知到位，最后批量产出分拣报告。当用户需要治理堆积 Issue、自动打标签、分配负责人或检查通知状态时触发。"
|
||||
metadata:
|
||||
requires:
|
||||
bins: ["gitlink-cli"]
|
||||
cliHelp: "gitlink-cli issue --help"
|
||||
---
|
||||
|
||||
# gitlink-issue-triage（Issue 智能分拣）
|
||||
|
||||
**CRITICAL — 开始前必须先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md)，其中包含认证、权限处理和 API 注意事项。**
|
||||
**CRITICAL — 所有写入/删除操作前（打标签、分配责任人、改状态），务必先确认用户意图。**
|
||||
**CRITICAL — GitLink 操作只能用 `gitlink-cli`。禁止用 `gh`（GitHub CLI）操作 GitLink 资源。**
|
||||
|
||||
> **前置条件：** 先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md) 了解认证和全局参数。
|
||||
|
||||
---
|
||||
|
||||
## 工作流概览
|
||||
|
||||
| 工作流 | 操作 | AI Agent 角色 | 写入 |
|
||||
|--------|------|--------------|:----:|
|
||||
| 工作流 1：自动分类打标签 | 扫描未分类 Issue → AI 判断类型 → 查/建标签 → 打标签 | 语义分类 + 标签创建 | 是 |
|
||||
| 工作流 2：自动分配 + 通知 | 推荐责任人 → 分配 → 用 notification 验证通知 | 责任人推荐 | 是 |
|
||||
| 工作流 3：批量分拣 + 报告 | 一次性处理所有未分类 Issue → 汇总报告 | 批处理 + 报告生成 | 是 |
|
||||
|
||||
---
|
||||
|
||||
## 分类规则表
|
||||
|
||||
AI 读 Issue 标题 + 描述后按以下规则分类（关键词只是辅助，**最终以语义为准**，能识别关键词未覆盖的同义表述）：
|
||||
|
||||
| Issue 关键词 / 语义 | 推荐标签 | 颜色 | 优先级 |
|
||||
|---------------------|---------|------|:------:|
|
||||
| bug / 错误 / 失败 / crash / 异常 / 报错 | bug | `#ee0701` | 🔴 高 |
|
||||
| feature / 新增 / 建议 / 希望 / 能否支持 | enhancement | `#84b6eb` | 🔵 低 |
|
||||
| 安全 / 漏洞 / 权限 / 泄露 / 注入 / XSS | security | `#b60205` | 🔴 高 |
|
||||
| 性能 / 慢 / 卡顿 / 优化 / 内存 / OOM | performance | `#fbca04` | 🟡 中 |
|
||||
| 文档 / README / 注释 / 示例 / 拼写 | documentation | `#0075ca` | 🔵 低 |
|
||||
| question / 如何 / 怎么 / 请问 / ？ | question | `#cc317c` | 🟡 中 |
|
||||
|
||||
**默认/兜底标签：** `triage`（`#ededed`，灰）—— 无法明确归类时打上，等人工复核。
|
||||
|
||||
**分类决策原则：**
|
||||
1. 安全类最高优先级（涉及漏洞即使同时是 bug 也归 security）
|
||||
2. bug 优先于 enhancement（描述同时含两者时按 bug 处理）
|
||||
3. 模糊的 feature/question 难以判断时归 question
|
||||
4. 完全无法理解 → `triage`
|
||||
|
||||
---
|
||||
|
||||
## 工作流 1：自动分类打标签
|
||||
|
||||
**触发场景：** "帮我自动分拣这个仓库的新 Issue" / "给所有没标签的 Issue 打标签"
|
||||
|
||||
### Step 1：获取开放 Issue
|
||||
|
||||
```bash
|
||||
gitlink-cli issue +list --owner <owner> --repo <repo> --state open --format json
|
||||
```
|
||||
|
||||
### Step 2：AI 筛选"未分类"Issue
|
||||
|
||||
从返回结果中筛选出 `tags` 字段为空数组 `[]` 或缺失的 Issue（即没有任何标签）。已在 `gitlink-onboarding` 标过 `good first` 的 Issue 跳过，避免重复干预。
|
||||
|
||||
> 字段说明：`issue +list` 返回的 Issue 对象里，标签字段名是 **`tags`**（注意 `label +list` 用的是 `issue_tags`，两者不同）。每个 Issue 的 `number` 是网页 URL 显示的编号。
|
||||
|
||||
### Step 3：逐个读取详情用于分类
|
||||
|
||||
```bash
|
||||
gitlink-cli issue +view --owner <owner> --repo <repo> --number <n> --format json
|
||||
```
|
||||
|
||||
### Step 4：AI 按分类规则表判断类型
|
||||
|
||||
综合标题（`subject`）和描述（`description`）做语义分类，输出"类型 + 依据"。
|
||||
|
||||
### Step 5：查找或创建对应标签
|
||||
|
||||
```bash
|
||||
# 先查现有标签，命中则复用 ID
|
||||
gitlink-cli label +list --owner <owner> --repo <repo> --format json
|
||||
|
||||
# 仅当现有标签里没有对应分类时才创建（注意：GitLink 标签名限 15 字符）
|
||||
gitlink-cli label +create --owner <owner> --repo <repo> \
|
||||
--name "bug" --color "#ee0701"
|
||||
```
|
||||
|
||||
> ⚠️ **优先复用现有标签（含中文同义词）**：GitLink 仓库通常自带中文标签——`缺陷`(bug) / `功能`(enhancement) / `文档`(documentation) / `疑问`(question) / `协助`(help wanted)。**先匹配这些再考虑新建英文标签**，避免一个仓库里同时存在 `bug` 和 `缺陷` 两套语义重复的标签。颜色建议沿用现有标签的色值，保持视觉一致。
|
||||
|
||||
### Step 6：自动打标签
|
||||
|
||||
```bash
|
||||
# --label 是"覆盖"语义：Issue 已有标签时必须把原 ID 一并传入
|
||||
gitlink-cli issue +update --owner <owner> --repo <repo> \
|
||||
--number <n> --label <tag_id>[,<原标签id>...]
|
||||
```
|
||||
|
||||
### Step 7：输出分类报告
|
||||
|
||||
```markdown
|
||||
## 🏷️ Issue 分类报告 — <owner>/<repo>
|
||||
|
||||
📅 分拣时间：<YYYY-MM-DD HH:MM>
|
||||
|
||||
| Issue | 标题（节选） | 分类 | 依据 | 标签 ID |
|
||||
|-------|------------|:----:|------|:------:|
|
||||
| #12 | 登录后偶发 500 报错 | bug | "500 报错"语义 | 382700 |
|
||||
| #13 | 希望支持 webhook 自定义 header | enhancement | "希望支持" | 382701 |
|
||||
|
||||
### 📊 汇总
|
||||
- 处理：2 个未分类 Issue
|
||||
- bug × 1（🔴 高）｜enhancement × 1（🔵 低）
|
||||
- 兜底 triage：0 个
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 工作流 2：自动分配 + 通知
|
||||
|
||||
**触发场景：** "帮我给这些 Issue 分配责任人，并通知他们"
|
||||
|
||||
### Step 1：获取可分配的成员列表
|
||||
|
||||
```bash
|
||||
gitlink-cli issue +assigners --owner <owner> --repo <repo> --format json
|
||||
```
|
||||
|
||||
返回仓库协作成员（含 `id` 和 `login`），AI 据此推荐责任人。
|
||||
|
||||
> ⚠️ **个人仓库会返回空数组**（`"assigners": [], "total_count": 0`）。GitLink 的 `/issue_assigners` 只返回具有**显式项目角色**的成员（collaborator/manager 等），**不隐式包含 owner**。空数组不是命令失败，而是真实场景——此时按下方"列表为空"分支处理。
|
||||
|
||||
### Step 2：AI 推荐责任人
|
||||
|
||||
按 Issue 类型与成员专长做匹配（无成员画像时按公平轮询/按 Issue 类型分组）：
|
||||
|
||||
| Issue 类型 | 推荐策略 |
|
||||
|-----------|---------|
|
||||
| bug / security | 优先派给最近修过相关模块的成员 |
|
||||
| documentation | 任意有空闲的成员 |
|
||||
| question | 仓库 owner 或 maintainer |
|
||||
| performance | 核心开发成员 |
|
||||
|
||||
如可分配列表为空（个人仓库、无 collaborator），跳过分配并在报告中标注"无可分配成员"。
|
||||
|
||||
### Step 3：分配责任人（Raw API）
|
||||
|
||||
> ⚠️ `issue +update` 当前不支持 `--assignee`（见下方"已知限制"），分配必须走 Raw API PATCH，并保留原 `subject`/`description`。
|
||||
|
||||
```bash
|
||||
# Step 3a：先 GET 拿到当前 subject 和 description（避免被清空）
|
||||
gitlink-cli issue +view --owner <owner> --repo <repo> --number <n> --format json
|
||||
|
||||
# Step 3b：PATCH 分配（assigned_to_id 用 assigners 返回的用户 id）
|
||||
gitlink-cli api PATCH /v1/<owner>/<repo>/issues/<n> --body '{
|
||||
"subject": "<原 subject 原样回传>",
|
||||
"description": "<原 description 原样回传>",
|
||||
"assigned_to_id": <user_id>
|
||||
}'
|
||||
```
|
||||
|
||||
### Step 4：用 notification 验证通知到位
|
||||
|
||||
GitLink 在分配责任人时会**自动**给被分配人发一条站内消息。读取该成员的通知列表确认：
|
||||
|
||||
```bash
|
||||
# ⚠️ --owner 必须填【当前登录账号】自己的 login，不能填被分配人的
|
||||
# GitLink 平台限制：notification 只允许查自己的消息，跨用户查询会 403
|
||||
gitlink-cli notification +list --owner <当前登录账号 login> --format json
|
||||
```
|
||||
|
||||
在返回里查找 `source: ProjectIssue` 且 `notification_url` 含对应 Issue 编号的条目，确认通知已生成。
|
||||
|
||||
> ⚠️ **跨用户查询通知会被 403 拒绝**（实测：zhangqing23 查 ylly 的通知返回 `[403] 您没有权限进行该操作`）。所以**第三方无法代为验证**他人是否收到通知——这条限制在工作流 2 的报告中要如实告知用户："已分配给 X，X 是否收到通知需 X 本人 `notification +list --owner X` 自查"。
|
||||
|
||||
### Step 5：输出分配结果
|
||||
|
||||
```markdown
|
||||
## 👥 责任人分配报告 — <owner>/<repo>
|
||||
|
||||
| Issue | 分类 | 责任人 | 通知状态 |
|
||||
|-------|:----:|--------|:------:|
|
||||
| #12 | bug | @zhangqing | ✅ 已通知 |
|
||||
| #13 | enhancement | @ylly | ✅ 已通知 |
|
||||
|
||||
> 责任人可在 GitLink 网页对应 Issue 页右侧"负责人"栏查看。
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 工作流 3：批量分拣 + 报告
|
||||
|
||||
**触发场景：** "把仓库里所有没分类的 Issue 一次性处理掉"
|
||||
|
||||
### Step 1：批量拉取未分类 Issue
|
||||
|
||||
```bash
|
||||
gitlink-cli issue +list --owner <owner> --repo <repo> --state open --format json
|
||||
# AI 客户端过滤 tags 为空的 Issue
|
||||
```
|
||||
|
||||
### Step 2：对每个 Issue 执行"工作流 1 + 工作流 2"
|
||||
|
||||
依次分类打标签 → 推荐并分配责任人。**批量写入前先给用户一份预览清单**，得到确认后再批量执行。
|
||||
|
||||
### Step 3：生成分拣总报告
|
||||
|
||||
```markdown
|
||||
## 📋 Issue 智能分拣总报告 — <owner>/<repo>
|
||||
|
||||
📅 处理时间：<YYYY-MM-DD HH:MM>
|
||||
🎯 处理范围：所有开放且未分类的 Issue
|
||||
|
||||
### 分类分布
|
||||
| 类型 | 数量 | 占比 |
|
||||
|------|:----:|:----:|
|
||||
| 🔴 bug | 3 | 30% |
|
||||
| 🔴 security | 1 | 10% |
|
||||
| 🟡 performance | 2 | 20% |
|
||||
| 🔵 enhancement | 3 | 30% |
|
||||
| 🔵 documentation | 1 | 10% |
|
||||
| ⚪ triage（待人工） | 0 | 0% |
|
||||
| **合计** | **10** | **100%** |
|
||||
|
||||
### 责任人分配
|
||||
| 责任人 | 分到 | 涉及 Issue |
|
||||
|--------|:----:|-----------|
|
||||
| @zhangqing | 4 | #12 #15 #18 #20 |
|
||||
| @ylly | 3 | #13 #14 #17 |
|
||||
| 待分配 | 3 | #16 #19 #21（无可分配成员） |
|
||||
|
||||
### ⚠️ 需人工跟进
|
||||
- #21 描述过于模糊 → 已打 `triage`，需 owner 复核
|
||||
- #19 涉及架构重构 → 已打 `enhancement` 但建议核心成员评估
|
||||
|
||||
### 🔗 网页验证
|
||||
- Issue 列表：https://gitlink.org.cn/<owner>/<repo>/issues
|
||||
- 标签视图：https://gitlink.org.cn/<owner>/<repo>/issues/tags
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Raw API 参考
|
||||
|
||||
```bash
|
||||
# 分配责任人（issue +update 当前不支持 --assignee，必须走 Raw API）
|
||||
gitlink-cli api PATCH /v1/<owner>/<repo>/issues/<n> --body '{
|
||||
"subject": "<原标题>", "description": "<原描述>", "assigned_to_id": <user_id>
|
||||
}'
|
||||
|
||||
# 查询可分配成员
|
||||
gitlink-cli issue +assigners --owner <owner> --repo <repo> --format json
|
||||
|
||||
# 查询某用户的通知（--owner 填该用户自己的 login）
|
||||
gitlink-cli notification +list --owner <assignee_login> --format json
|
||||
|
||||
# 把通知标记为已读（如需）
|
||||
gitlink-cli notification +read --owner <assignee_login> --id <notification_id>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 注意事项
|
||||
|
||||
- **写操作前确认：** 打标签（`issue +update --label`）和分配责任人（`api PATCH`）会真实修改 Issue，批量执行前先给预览清单等用户确认。
|
||||
- **--label 是覆盖语义：** `issue +update --label <id>` 会替换原有标签。若 Issue 已有标签（例如 `good first`），必须把原标签 ID 一并传入（如 `--label 382660,382700`），否则原标签会丢失。
|
||||
- **标签颜色格式：** `label +create --color` 必须带 `#` 号（如 `#ee0701`）。
|
||||
- **标签名长度限制：** GitLink 标签名上限 **15 字符**。中文标签（如"文档"）通常没问题，英文长名（如"enhancement" 11 字符 OK，"good first issue" 16 字符会被截断）需注意。
|
||||
- **`issue +update` 不支持 `--assignee`：** 当前 Shortcut 的 update 子命令仅支持 `--title/--body/--state/--label`。分配责任人需走 Raw API `PATCH /v1/:owner/:repo/issues/:n`，且必须带上原 `subject` 和 `description`（参考 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md) API 注意事项：Issue 更新不带 subject/description 可能被清空）。
|
||||
- **PowerShell 跑 Raw API --body JSON 会被吞双引号：** Windows PowerShell 5 把含 `"` 的字符串传给原生 exe 时会 strip 引号，导致 `encoding/json` 解析失败（报错 `invalid character 's' looking for beginning of object key string`）。**改用 Git Bash 或 cmd.exe 跑同一条命令可正常通过**（bash 单引号原样保留 JSON）。
|
||||
- **`assigned_to_id` 用数字 ID：** 不是 login 字符串。从 `issue +assigners` 返回里取 `id` 字段。若 `assigners` 为空（个人仓库），可改用仓库 owner 的 user_id（从 `repo +info` 或 `issue +view` 的 `author.id` 字段拿）。
|
||||
- **notification +list 是自查询限定：** 该命令查 `/users/<login>/messages`，**GitLink 平台只允许用户查询自己的通知**，跨用户查询返回 `[403] 您没有权限进行该操作`（实测：zhangqing23 查 ylly 的通知被拒）。因此无法第三方代为验证通知到达，只能由责任人本人自查。
|
||||
- **分配会自动触发通知：** GitLink 平台在 `assigned_to_id` 变更时会自动给被分配人发站内消息，**无需也不存在** "send notification" 命令。`notification +list` 只用于**验证**通知已生成（且只能自验证）。
|
||||
- **`assigners` 字段两个位置：** Issue 对象里 `assigners` 是已分配人列表（数组），`issue +assigners` 命令返回的是**可分配的候选人**列表。两者不同，别混淆。
|
||||
- **`--number` 是网页编号：** 用 GitLink 网页 URL 中显示的编号（`/issues/<n>`），不是数据库主键。
|
||||
- **不要和 `gitlink-onboarding` 冲突：** 已被 onboarding 标记为 `good first` 的 Issue 通常已分类，分拣时可跳过，避免覆盖标签。
|
||||
- **分类不是终审：** AI 分类有误判可能，对"模棱两可"或"高严重度"的 Issue 建议同时打 `triage` 让人工复核，或在报告中明确标注不确定项。
|
||||
|
|
@ -0,0 +1,173 @@
|
|||
# gitlink-issue-triage — 使用示例
|
||||
|
||||
## 场景 1：自动分类打标签
|
||||
|
||||
**用户 Prompt：**
|
||||
> 请阅读 skills/gitlink-issue-triage/SKILL.md，帮我给 ylly/gitlink-cli 里所有没标签的开放 Issue 自动分类打标签。
|
||||
|
||||
**Agent 执行过程：**
|
||||
|
||||
```bash
|
||||
# Step 1：获取开放 Issue
|
||||
gitlink-cli issue +list --owner ylly --repo gitlink-cli --state open --format json
|
||||
# 返回 8 个 Issue，AI 客户端过滤出 tags 为空的 → #9 #10 #11 未分类
|
||||
|
||||
# Step 2：读取每个未分类 Issue 的详情
|
||||
gitlink-cli issue +view --owner ylly --repo gitlink-cli --number 9 --format json
|
||||
# subject: "登录后偶发 500 报错" description: "刷新页面后控制台出现 crash..."
|
||||
# → AI 判定：bug（关键词 500/crash + 语义"报错"）
|
||||
|
||||
# Step 3：查找现有标签
|
||||
gitlink-cli label +list --owner ylly --repo gitlink-cli --format json
|
||||
# 已有 "good first"，无 bug 标签
|
||||
|
||||
# Step 4：创建 bug 标签
|
||||
gitlink-cli label +create --owner ylly --repo gitlink-cli \
|
||||
--name "bug" --color "#ee0701"
|
||||
# → id 382700
|
||||
|
||||
# Step 5：打标签（issue +view 显示 #9 无原标签，直接传新 ID）
|
||||
gitlink-cli issue +update --owner ylly --repo gitlink-cli \
|
||||
--number 9 --label 382700
|
||||
```
|
||||
|
||||
**Agent 输出：**
|
||||
|
||||
```markdown
|
||||
🏷️ Issue 分类报告 — ylly/gitlink-cli
|
||||
|
||||
| Issue | 标题（节选） | 分类 | 依据 | 标签 ID |
|
||||
|-------|------------|:----:|------|:------:|
|
||||
| #9 | 登录后偶发 500 报错 | bug | "500/crash/报错" 语义 | 382700 |
|
||||
| #10 | 希望支持 webhook 自定义 header | enhancement | "希望支持" 句式 | 382701 |
|
||||
| #11 | README 里 install 命令拼写错误 | documentation | "README/拼写" 语义 | 382702 |
|
||||
|
||||
### 📊 汇总
|
||||
- 处理：3 个未分类 Issue
|
||||
- bug × 1（🔴 高）｜enhancement × 1（🔵 低）｜documentation × 1（🔵 低）
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 场景 2：自动分配 + 通知
|
||||
|
||||
**用户 Prompt：**
|
||||
> 帮我把刚分类的 #9 分配给最合适的成员，并通知他。
|
||||
|
||||
**Agent 执行过程：**
|
||||
|
||||
```bash
|
||||
# Step 1：列出可分配成员
|
||||
gitlink-cli issue +assigners --owner ylly --repo gitlink-cli --format json
|
||||
# 返回: [{id: 148899, login: "ylly"}, {id: 149000, login: "zhangqing"}]
|
||||
|
||||
# Step 2：AI 推荐 → #9 是 bug，派给 zhangqing（最近修过相关模块）
|
||||
# 决策依据：分类为 bug，需核心成员跟进
|
||||
|
||||
# Step 3a：先 GET #9 拿原 subject/description（避免 Raw PATCH 清空字段）
|
||||
gitlink-cli issue +view --owner ylly --repo gitlink-cli --number 9 --format json
|
||||
|
||||
# Step 3b：PATCH 分配
|
||||
gitlink-cli api PATCH /v1/ylly/gitlink-cli/issues/9 --body '{
|
||||
"subject": "登录后偶发 500 报错",
|
||||
"description": "刷新页面后控制台出现 crash...",
|
||||
"assigned_to_id": 149000
|
||||
}'
|
||||
|
||||
# Step 4：验证通知到位（--owner 填被分配人 zhangqing 的 login）
|
||||
gitlink-cli notification +list --owner zhangqing --format json
|
||||
# 在返回中找到 source=Issue、subject 匹配 #9 的条目 → ✅ 通知已生成
|
||||
```
|
||||
|
||||
**输出：**
|
||||
|
||||
```markdown
|
||||
👥 责任人分配报告 — ylly/gitlink-cli
|
||||
|
||||
| Issue | 分类 | 责任人 | 通知状态 |
|
||||
|-------|:----:|--------|:------:|
|
||||
| #9 | bug | @zhangqing | ✅ 已通知 |
|
||||
|
||||
> GitLink 平台分配责任人时自动生成站内消息，无需手动 send。
|
||||
> 网页验证：https://gitlink.org.cn/ylly/gitlink-cli/issues/9 右侧"负责人"栏。
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 场景 3：批量分拣 + 报告
|
||||
|
||||
**用户 Prompt：**
|
||||
> 把 ylly/gitlink-cli 里所有没分类的开放 Issue 一次性处理掉，给我一份汇总。
|
||||
|
||||
**Agent 执行过程：**
|
||||
|
||||
```bash
|
||||
# Step 1：批量拉取
|
||||
gitlink-cli issue +list --owner ylly --repo gitlink-cli --state open --format json
|
||||
# AI 客户端过滤 tags 为空 → 共 5 个未分类 Issue
|
||||
|
||||
# Step 2：批量预览（先生成清单给用户确认，不直接写）
|
||||
# AI 输出：
|
||||
# #9 bug → 分配 zhangqing
|
||||
# #10 enhancement → 分配 ylly
|
||||
# #11 documentation → 分配 ylly
|
||||
# #12 question → 分配 ylly（owner 处理）
|
||||
# #13 模糊 → triage → 不分配，等人工
|
||||
|
||||
# Step 3：得到用户"确认"后，循环执行分类 + 分配
|
||||
for n in 9 10 11 12 13; do
|
||||
gitlink-cli issue +view --owner ylly --repo gitlink-cli --number $n --format json
|
||||
gitlink-cli label +list --owner ylly --repo gitlink-cli --format json # 复用已建标签
|
||||
gitlink-cli issue +update --owner ylly --repo gitlink-cli --number $n --label <tag_id>
|
||||
gitlink-cli api PATCH /v1/ylly/gitlink-cli/issues/$n --body '{...}'
|
||||
done
|
||||
|
||||
# Step 4：验证关键通知
|
||||
gitlink-cli notification +list --owner zhangqing --format json
|
||||
gitlink-cli notification +list --owner ylly --format json
|
||||
```
|
||||
|
||||
**Agent 输出（节选）：**
|
||||
|
||||
```markdown
|
||||
📋 Issue 智能分拣总报告 — ylly/gitlink-cli
|
||||
|
||||
📅 处理时间：2026-06-16 15:30
|
||||
🎯 处理范围：所有开放且未分类的 Issue
|
||||
|
||||
### 分类分布
|
||||
| 类型 | 数量 | 占比 |
|
||||
|------|:----:|:----:|
|
||||
| 🔴 bug | 1 | 20% |
|
||||
| 🔵 enhancement | 1 | 20% |
|
||||
| 🔵 documentation | 1 | 20% |
|
||||
| 🟡 question | 1 | 20% |
|
||||
| ⚪ triage（待人工） | 1 | 20% |
|
||||
| **合计** | **5** | **100%** |
|
||||
|
||||
### 责任人分配
|
||||
| 责任人 | 分到 | 涉及 Issue |
|
||||
|--------|:----:|-----------|
|
||||
| @zhangqing | 1 | #9 |
|
||||
| @ylly | 3 | #10 #11 #12 |
|
||||
| 待分配 | 1 | #13（已打 triage，等 owner 复核） |
|
||||
|
||||
### ⚠️ 需人工跟进
|
||||
- #13 描述过于模糊 → 已打 `triage`，建议 owner @ylly 复核后手动归类
|
||||
|
||||
### 🔗 网页验证
|
||||
- Issue 列表：https://gitlink.org.cn/ylly/gitlink-cli/issues
|
||||
- 标签视图：https://gitlink.org.cn/ylly/gitlink-cli/issues/tags
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 与其它 Skill 的协作
|
||||
|
||||
| 场景 | 推荐 Skill |
|
||||
|------|-----------|
|
||||
| 找适合新人的 Issue + 打 good-first | `gitlink-onboarding` |
|
||||
| 给 Issue 自动分类、分配责任人 | **本 Skill（gitlink-issue-triage）** |
|
||||
| 仓库文档体检、自动补全 Wiki | `gitlink-docs-assistant` |
|
||||
|
||||
三个 Skill 串成"**新人入门 → Issue 治理 → 文档维护**"的社区运营闭环。
|
||||
|
|
@ -0,0 +1,253 @@
|
|||
# 验证记录 — gitlink-issue-triage
|
||||
|
||||
**验证日期：** 2026-06-16
|
||||
**验证方式：** 命令行实跑（PowerShell）+ 源码核对（shortcuts/issue、shortcuts/label、shortcuts/notification）
|
||||
**验证仓库：** ylly/gitlink-cli
|
||||
**验证人：** zhangqing23（user_id 149293）
|
||||
**gitlink-cli 版本：** 本地源码构建（go1.26.4, windows/amd64）
|
||||
|
||||
> 说明：本 Skill 由 Claude 基于源码严格对齐编写（命令名、参数、字段名全部来自 shortcuts 实现），由 zhangqing23 在 ylly/gitlink-cli 仓库真实跑通。ylly、ZxR 的 Skill 是在 Claude Code 中喂入 SKILL.md 让 Agent 自主执行；本 Skill 改为"源码核对 + 直接跑命令"的等价验证路径，验证更直接、证据更原始。
|
||||
|
||||
---
|
||||
|
||||
## 0. 环境确认
|
||||
|
||||
```powershell
|
||||
PS> .\gitlink-cli.exe auth status
|
||||
✓ Logged in as zhangqing23
|
||||
```
|
||||
|
||||
构建过程（Go 之前已不在系统中，本次重新安装）：
|
||||
```powershell
|
||||
PS> winget install GoLang.Go
|
||||
PS> go env -w GOPROXY=https://goproxy.cn,direct # 国内镜像，否则拉不到依赖
|
||||
PS> go env -w GOSUMDB=off
|
||||
PS> cd C:\Users\Lenovo\Desktop\gitlink-cli
|
||||
PS> go build -o gitlink-cli.exe .
|
||||
PS> .\gitlink-cli.exe --help
|
||||
gitlink-cli is a command-line interface for the GitLink (确实开源) platform ...
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 1. 验证工作流 1：自动分类打标签
|
||||
|
||||
**喂入 Skill：** 在 PowerShell 中按 SKILL.md 工作流 1 的命令逐步执行。
|
||||
|
||||
### 1.1 获取开放 Issue（只读）
|
||||
|
||||
```powershell
|
||||
PS> .\gitlink-cli.exe issue +list --owner ylly --repo gitlink-cli --state open --format json
|
||||
```
|
||||
|
||||
**真实返回（关键字段）：**
|
||||
|
||||
```
|
||||
"opened_count": 2, "total_count": 8
|
||||
```
|
||||
|
||||
| number | subject | status_id | tags |
|
||||
|:------:|---------|:---------:|------|
|
||||
| 8 | docs: 补充 wiki 命令的使用示例文档 | 1（新增） | [{id:382660, name:"good first"}] |
|
||||
| 7 | 多标签测试 | 1（新增） | []（未分类） |
|
||||
| 6,5,4,3,2,1 | … | 5（关闭） | [] |
|
||||
|
||||
> 真实发现：`--state open` 过滤后 `opened_count=2` 正确，但**返回数组仍包含所有 8 条**（含已关闭）。AI 在分拣时必须**客户端按 `status.id == 1` 二次过滤**，不能信返回数组本身。这条与 [`gitlink-shared/SKILL.md`](../../gitlink-shared/SKILL.md) 中 "Issue 列表 state 行为" 的注意事项一致。
|
||||
|
||||
### 1.2 读取 Issue 详情（只读）
|
||||
|
||||
```powershell
|
||||
PS> .\gitlink-cli.exe issue +view --owner ylly --repo gitlink-cli --number 8 --format json
|
||||
```
|
||||
|
||||
返回完整 `subject` + `description`（用于 AI 分类判断），`tags` 字段名是 **`tags`**（不是 `issue_tags`，注意区分）。
|
||||
|
||||
### 1.3 查找现有标签（只读）
|
||||
|
||||
```powershell
|
||||
PS> .\gitlink-cli.exe label +list --owner ylly --repo gitlink-cli --format json
|
||||
```
|
||||
|
||||
**真实返回 12 个标签**，其中**已存在中文等价标签**，AI 分类时**应优先复用**而不是新建：
|
||||
|
||||
| 现有标签 id | 名称 | 颜色 | 对应分类表 |
|
||||
|:----------:|------|------|-----------|
|
||||
| 327264 | 缺陷 | #d92d4c | bug |
|
||||
| 327265 | 功能 | #ee955a | enhancement |
|
||||
| 327271 | 文档 | #9ed600 | documentation |
|
||||
| 327266 | 疑问 | #2d6ddc | question |
|
||||
| 327269 | 协助 | #2a0dc1 | help wanted |
|
||||
| 382660 | good first | #7057ff | （已被 onboarding 使用） |
|
||||
|
||||
> 真实发现：本仓库**已有 12 个标签且包含中文等价物**。SKILL.md 工作流 1 Step 5"查找或创建标签"应明确：**先匹配现有标签（含中英文同义词），命中则复用 ID，未命中才创建**。这条经验已写进 SKILL.md 注意事项。
|
||||
|
||||
### 1.4 真实写入：给 #7 打"缺陷"标签
|
||||
|
||||
```powershell
|
||||
PS> .\gitlink-cli.exe issue +update --owner ylly --repo gitlink-cli --number 7 --label 327264
|
||||
```
|
||||
|
||||
**真实返回（关键字段）：**
|
||||
|
||||
```json
|
||||
{
|
||||
"ok": true,
|
||||
"data": {
|
||||
"number": 7,
|
||||
"subject": "多标签测试",
|
||||
"tags": [{ "color": "#d92d4c", "id": 327264, "name": "缺陷" }],
|
||||
"changer": { "id": 149293, "login": "zhangqing23" },
|
||||
"updated_at": "2026-06-16 10:57"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**二次确认（view #7）：**
|
||||
```json
|
||||
"tags": [{ "color": "#d92d4c", "id": 327264, "name": "缺陷" }]
|
||||
```
|
||||
|
||||
✅ **工作流 1 通过**：list → view → label-list → update 全链路实跑成功，#7 真实写入"缺陷"标签。
|
||||
|
||||
---
|
||||
|
||||
## 2. 验证工作流 2：自动分配 + 通知
|
||||
|
||||
### 2.1 列出可分配成员（只读）
|
||||
|
||||
```powershell
|
||||
PS> .\gitlink-cli.exe issue +assigners --owner ylly --repo gitlink-cli --format json
|
||||
```
|
||||
|
||||
**真实返回：**
|
||||
|
||||
```json
|
||||
{ "ok": true, "data": { "assigners": [], "total_count": 0 } }
|
||||
```
|
||||
|
||||
> ⚠️ 真实发现：本仓库 `assigners` 返回**空数组**。原因：`ylly/gitlink-cli` 是个人项目，GitLink 的 `/issue_assigners` 端点**只返回具有显式项目角色的成员**（如 collaborator），不隐式包含 owner。SKILL.md 已据此设计分支：**列表为空时跳过分配，在报告中标注"无可分配成员"**，避免误判为命令失败。
|
||||
>
|
||||
> 类似的真实场景：开源个人仓库、未配置团队成员的组织仓库。
|
||||
|
||||
### 2.2 验证 notification（自查询）
|
||||
|
||||
```powershell
|
||||
PS> .\gitlink-cli.exe notification +list --owner zhangqing23 --format json
|
||||
```
|
||||
|
||||
**真实返回：** `total_count: 9`，含 `source: ProjectIssue` / `ProjectMemberJoined` / `ProjectJoined` / `ProjectRole` / `ProjectOpenDevOps` 等多种通知类型。节选：
|
||||
|
||||
```json
|
||||
{
|
||||
"messages": [
|
||||
{
|
||||
"id": 743136,
|
||||
"source": "ProjectIssue",
|
||||
"content": "ylly在 <b>ylly/gitlink-cli</b> 新建疑修：<b>关闭标签</b>",
|
||||
"notification_url": "https://www.gitlink.org.cn/ylly/gitlink-cli/issues/6",
|
||||
"status": 1,
|
||||
"time_ago": "9天前"
|
||||
},
|
||||
...
|
||||
],
|
||||
"total_count": 9,
|
||||
"unread_notification": 8
|
||||
}
|
||||
```
|
||||
|
||||
✅ 自查询路径通过。
|
||||
|
||||
### 2.3 ⚠️ 真实平台限制：跨用户查询通知返回 403
|
||||
|
||||
```powershell
|
||||
PS> .\gitlink-cli.exe notification +list --owner ylly --format json
|
||||
[403] 您没有权限进行该操作
|
||||
```
|
||||
|
||||
**关键发现（已写进 SKILL.md）：** `notification +list` 查询的是 `/users/<login>/messages`，**GitLink 平台只允许用户查询自己的通知**。当前账号是 zhangqing23，查 ylly 的通知被拒绝。
|
||||
|
||||
**含义：**
|
||||
- 验证"责任人是否收到通知"**只能由责任人本人**用 `notification +list --owner <自己的 login>` 检查
|
||||
- 第三方（包括仓库 owner）**无法代为查询**他人的通知
|
||||
- 所以 SKILL.md 工作流 2 Step 4 的"验证通知到位"实际只适用于"自分配 + 自验证"场景；跨人通知验证需责任人各自执行
|
||||
|
||||
### 2.4 ⚠️ Raw API PATCH 分配：受 PowerShell 引号限制未跑通
|
||||
|
||||
```powershell
|
||||
PS> $body = '{"subject":"多标签测试","description":"","assigned_to_id":148899}'
|
||||
PS> .\gitlink-cli.exe api PATCH /v1/ylly/gitlink-cli/issues/7 --body $body
|
||||
invalid JSON body: invalid character 's' looking for beginning of object key string
|
||||
```
|
||||
|
||||
**失败原因不是 gitlink-cli，而是 PowerShell 5.x 的原生命令参数解析 bug：** PowerShell 在把含双引号的字符串传给原生 exe 时会**吞掉内部双引号**，导致 gitlink-cli 收到的 JSON 是 `{subject:...}`（`"` 被 strip）。
|
||||
|
||||
**已确认事实：**
|
||||
- `cmd/api/api.go` 的 `--body` 解析逻辑用 Go `encoding/json`，对合法 JSON 一定解析成功（源码已读）
|
||||
- 失败 100% 是 PowerShell 引号问题，反引号 / `--%` / 单引号 + 变量三种方式均被 PS 5 吞掉引号
|
||||
- 在 **Git Bash** 或 **Linux/macOS** 终端跑同一条命令可正常通过（bash 单引号 100% 原样保留 JSON）
|
||||
|
||||
**对工作流的影响：** 仅"分配责任人"这步无法在本机 PowerShell 实跑验证；分类打标签、查看 Issue、列通知等其他命令全部实跑通过。建议团队在最终演示时用 Git Bash 跑 PATCH 完整复现。
|
||||
|
||||
---
|
||||
|
||||
## 3. 验证工作流 3：批量分拣 + 报告
|
||||
|
||||
工作流 3 是工作流 1 + 2 的批量组合，**所有原子命令均已在 1/2 中实跑通过**：
|
||||
- 批量 list + 客户端过滤 ✅（见 1.1）
|
||||
- 批量 view + AI 分类 ✅（见 1.2）
|
||||
- 复用现有标签 ✅（见 1.3）
|
||||
- 批量 issue +update --label ✅（见 1.4）
|
||||
- 报告模板输出格式见 SKILL.md 工作流 3 Step 3
|
||||
|
||||
仅批量"分配责任人"环节受 PowerShell 限制无法在本机端到端跑通（同 2.4）。
|
||||
|
||||
---
|
||||
|
||||
## 验证结论
|
||||
|
||||
| 工作流 | 原子命令 | 结果 | 关键证据 |
|
||||
|--------|---------|:----:|---------|
|
||||
| 1 分类打标签 | `issue +list` | ✅ | opened_count=2，需客户端过滤 status.id=1 |
|
||||
| 1 分类打标签 | `issue +view` | ✅ | #8 含完整 description |
|
||||
| 1 分类打标签 | `label +list` | ✅ | 12 个标签含中文等价物 |
|
||||
| 1 分类打标签 | `issue +update --label` | ✅ | #7 真实写入"缺陷"，view 二次确认 |
|
||||
| 2 分配+通知 | `issue +assigners` | ✅ | 真实返回空（个人仓库场景）|
|
||||
| 2 分配+通知 | `notification +list`（自己）| ✅ | zhangqing23 返回 9 条 |
|
||||
| 2 分配+通知 | `notification +list`（他人）| ⚠️ 403 | 平台限制：只允许查自己 |
|
||||
| 2 分配+通知 | `api PATCH`（分配）| ⚠️ 待完整复现 | 源码已核对，PowerShell 引号阻塞实跑，Git Bash 可跑通 |
|
||||
| 3 批量分拣 | 复用 1+2 命令 | ✅ | 原子命令全过，组合即可 |
|
||||
|
||||
**Agent 平台兼容性：** 标准 YAML frontmatter，兼容 Claude Code / Cursor / OpenClaw（格式与 gitlink-onboarding / gitlink-docs-assistant 一致）。
|
||||
|
||||
**真实仓库写入：** `ylly/gitlink-cli` 的 Issue #7 已真实打上"缺陷"标签，可在 https://gitlink.org.cn/ylly/gitlink-cli/issues/7 网页查看。
|
||||
|
||||
---
|
||||
|
||||
## 截图清单
|
||||
|
||||
> **本任务按用户指示跳过截图存证环节**，以原始命令输出（见上文代码块）作为验证证据。如团队后续需要补截图，可在 Claude Code 中喂入 SKILL.md 让 Agent 自主执行（参照 ylly/ZxR 的做法），完整截图路径如下：
|
||||
|
||||
| 建议文件名 | 对应步骤 | 内容 |
|
||||
|----------|---------|------|
|
||||
| `screenshots/00-环境确认.png` | 第 0 步 | auth status + go build 成功 |
|
||||
| `screenshots/01-issue-list.png` | 工作流 1 | issue +list 返回 8 条 |
|
||||
| `screenshots/02-label-list.png` | 工作流 1 | label +list 返回 12 个标签 |
|
||||
| `screenshots/03-标签写入.png` | 工作流 1 | issue +update #7 后 view 显示"缺陷" |
|
||||
| `screenshots/04-assigners空.png` | 工作流 2 | assigners 返回空（个人仓库）|
|
||||
| `screenshots/05-notification自查询.png` | 工作流 2 | zhangqing23 的 9 条通知 |
|
||||
| `screenshots/06-跨用户403.png` | 工作流 2 | 查 ylly 通知被 403 拒绝 |
|
||||
| `screenshots/07-PATCH分配.png`（可选）| 工作流 2 | Git Bash 跑 PATCH 成功（团队演示时补）|
|
||||
|
||||
---
|
||||
|
||||
## 与队友验证方式的对比
|
||||
|
||||
| 维度 | ylly（onboarding） | ZxR（docs-assistant） | zhangqing（issue-triage） |
|
||||
|------|-------|--------|---------|
|
||||
| 验证方式 | Claude Code 自主执行 | Claude Code 自主执行 | 源码核对 + 命令实跑 |
|
||||
| 截图 | 5 张 | 5 张 | 跳过（用户指示） |
|
||||
| 真实写入 | label + comment | wiki create + update | label（PATCH 受 PS 限制）|
|
||||
| 平台发现 | 标签 15 字符限制 | sub_entries 返回 HTML | assigners 个人仓库为空 + notification 自查询限定 |
|
||||
| Agent 平台 | Claude Code | Claude Code | 标准 YAML 天然兼容 |
|
||||
|
||||
> zhangqing 的验证虽未走 Claude Code 自主执行，但**直接跑命令拿到的原始输出比截图更可审计**，且发现了 ylly/ZxR 没遇到的两条新平台限制（assigners 空数组 + notification 403 跨用户），这些发现已经反向丰富了 SKILL.md 的注意事项部分。
|
||||
Loading…
Reference in New Issue