Gitlink
/
gitlink-cli
0
0
Fork 49
Code Issues Pull Requests 11 Packages Projects Releases 10 Wiki Activity
gitlink-cli/skills/gitlink-issue-triage/examples/verification.md

13 KiB
Raw Blame History

验证记录 — 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. 环境确认

PS> .\gitlink-cli.exe auth status
✓ Logged in as zhangqing23

构建过程（Go 之前已不在系统中，本次重新安装）：

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（只读）

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 中 "Issue 列表 state 行为" 的注意事项一致。

1.2 读取 Issue 详情（只读）

PS> .\gitlink-cli.exe issue +view --owner ylly --repo gitlink-cli --number 8 --format json

返回完整 subject + description（用于 AI 分类判断），tags 字段名是 tags（不是 issue_tags，注意区分）。

1.3 查找现有标签（只读）

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 打"缺陷"标签

PS> .\gitlink-cli.exe issue +update --owner ylly --repo gitlink-cli --number 7 --label 327264

真实返回（关键字段）：

{
  "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）：

"tags": [{ "color": "#d92d4c", "id": 327264, "name": "缺陷" }]

✅ 工作流 1 通过：list → view → label-list → update 全链路实跑成功，#7 真实写入"缺陷"标签。

2. 验证工作流 2：自动分配 + 通知

2.1 列出可分配成员（只读）

PS> .\gitlink-cli.exe issue +assigners --owner ylly --repo gitlink-cli --format json

真实返回：

{ "ok": true, "data": { "assigners": [], "total_count": 0 } }

⚠️ 真实发现：本仓库 assigners 返回空数组。原因：ylly/gitlink-cli 是个人项目，GitLink 的 /issue_assigners 端点只返回具有显式项目角色的成员（如 collaborator），不隐式包含 owner。SKILL.md 已据此设计分支：列表为空时跳过分配，在报告中标注"无可分配成员"，避免误判为命令失败。

类似的真实场景：开源个人仓库、未配置团队成员的组织仓库。

2.2 验证 notification（自查询）

PS> .\gitlink-cli.exe notification +list --owner zhangqing23 --format json

真实返回： total_count: 9，含 source: ProjectIssue / ProjectMemberJoined / ProjectJoined / ProjectRole / ProjectOpenDevOps 等多种通知类型。节选：

{
  "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

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 引号限制未跑通

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）：

$ 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 已真实打上"缺陷"标签，可在 ylly/gitlink-cli#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 的注意事项部分。