forked from Gitlink/gitlink-cli
265 lines
13 KiB
Markdown
265 lines
13 KiB
Markdown
# 验证记录 — 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 吞掉引号
|
||
- **Windows shell 双坑（后续 ylly 环境 Git Bash 补充验证）：** PowerShell 5 吞 JSON 双引号；**Git Bash/MSYS2 会把 `/` 开头的路径参数改写成 `<Git安装目录>/v1/...`**（`--debug` 实测：`/v1/ylly/gitlink-cli/issues/9` 被改成 `/api/F:/Git/Git/v1/...`），请求 URL 错误返回 404。**两个坑都不能直接跑 raw api PATCH。** 解决：`MSYS_NO_PATHCONV=1 gitlink-cli api PATCH /v1/.../issues/9 ...`（实测返回 `ok:true`），或用 cmd.exe 配合正确转义。
|
||
- **`.json` 与 404 无关：** `--debug` 实测 `api` 命令会自动补 `.json`（不带 `.json` 的请求最终 URL 仍是 `.../issues/9.json`）。PATCH 404 的唯一原因是 MSYS2 路径转换，**不是漏 `.json`**。
|
||
|
||
**owner_id 兜底实测无效（结论 B）：**
|
||
|
||
```bash
|
||
$ MSYS_NO_PATHCONV=1 gitlink-cli api PATCH /v1/ylly/gitlink-cli/issues/9 --body \
|
||
'{"subject":"bug: wiki +view...","description":"...","assigned_to_id":148899}'
|
||
{ "ok": true, "data": { "subject": "bug: wiki +view...", "assigned_to": null, "assigned_to_id": null } }
|
||
```
|
||
|
||
PATCH 返回 `ok:true`（subject 更新成功），但 `assigned_to` / `assigned_to_id` 仍为 `null`——**服务器静默忽略了 owner_id**。原因：GitLink 校验 `assigned_to_id` 必须在 `issue +assigners` 候选列表内，个人仓库该列表为空，owner 也不在其中。**因此 SKILL.md 注意事项已删除"可改用 owner user_id 兜底"，改为"个人仓库 assigners 为空时无法分配，跳过并在报告标注"。**
|
||
|
||
**对工作流的影响：** 分类打标签、查看 Issue、列通知等命令全部实跑通过；"分配责任人"在 Git Bash + `MSYS_NO_PATHCONV=1` 下 PATCH 可跑通（HTTP 200），但个人仓库场景因 assigners 为空，实际无法分配成功（需先 `member +add` 加 collaborator）。
|
||
|
||
---
|
||
|
||
## 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 用 `--body-file` / Git Bash 用 `MSYS_NO_PATHCONV=1`，实跑返回 `ok:true`（见 2.4） |
|
||
| 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 网页查看。
|
||
|
||
---
|
||
|
||
## 截图清单
|
||
|
||
> 截图已补全（ylly 环境在 PowerShell / Git Bash 实跑），存放于 `screenshots/` 目录：
|
||
|
||
| 文件名 | 对应步骤 | 内容 |
|
||
|----------|---------|------|
|
||
| `screenshots/00-环境确认.png` | 第 0 步 | auth status（ylly 登录） |
|
||
| `screenshots/01-issue-list.png` | 工作流 1 | issue +list（3 个开放，#9 未分类） |
|
||
| `screenshots/02-label-list.png` | 工作流 1 | label +list 返回 12 个标签 |
|
||
| `screenshots/03-标签写入.png` | 工作流 1 | #9 打"缺陷"标签后 view 确认 |
|
||
| `screenshots/04-assigners空.png` | 工作流 2 | assigners 返回空（个人仓库） |
|
||
| `screenshots/05-patch分配.png` | 工作流 2 | ⭐ PATCH 返回 `ok:true`（PowerShell `--body-file` / Git Bash `MSYS_NO_PATHCONV=1`） |
|
||
| `screenshots/06-列出通知.png` | 工作流 2 | notification +list 自查询（ylly 的通知） |
|
||
| `screenshots/07-没有权限.png` | 工作流 2 | 跨用户查询被 403 拒绝 |
|
||
|
||
---
|
||
|
||
## 与队友验证方式的对比
|
||
|
||
| 维度 | 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 的注意事项部分。
|