diff --git a/skills/gitlink-issue-triage/SKILL.md b/skills/gitlink-issue-triage/SKILL.md index 4a42352..3d6a521 100644 --- a/skills/gitlink-issue-triage/SKILL.md +++ b/skills/gitlink-issue-triage/SKILL.md @@ -154,7 +154,10 @@ gitlink-cli issue +assigners --owner --repo --format json gitlink-cli issue +view --owner --repo --number --format json # Step 3b：PATCH 分配（assigned_to_id 用 assigners 返回的用户 id） -gitlink-cli api PATCH /v1///issues/ --body '{ +# ⚠️ Git Bash 用户必须加 MSYS_NO_PATHCONV=1 前缀，否则 / 开头路径会被 MSYS2 转成 +# Windows 路径（debug 实测：/v1/... 变成 /api/F:/Git/Git/v1/...），导致 404 +# 注：api 命令会自动补 .json 后缀，路径无需手动加（已实测确认） +MSYS_NO_PATHCONV=1 gitlink-cli api PATCH /v1///issues/ --body '{ "subject": "<原 subject 原样回传>", "description": "<原 description 原样回传>", "assigned_to_id": @@ -246,7 +249,8 @@ gitlink-cli issue +list --owner --repo --state open --format json ```bash # 分配责任人（issue +update 当前不支持 --assignee，必须走 Raw API） -gitlink-cli api PATCH /v1///issues/ --body '{ +# ⚠️ Git Bash 加 MSYS_NO_PATHCONV=1 前缀（见注意事项）；.json 由 api 自动补 +MSYS_NO_PATHCONV=1 gitlink-cli api PATCH /v1///issues/ --body '{ "subject": "<原标题>", "description": "<原描述>", "assigned_to_id": }' @@ -270,7 +274,8 @@ gitlink-cli notification +read --owner --id - **标签名长度限制：** 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` 字段拿）。 +- **Git Bash（MSYS2）会转换 `/` 开头的路径参数（PATCH 404 的真正原因）：** 以 `/` 开头的 Raw API 路径（如 `/v1/owner/repo/issues/9`）会被 Git Bash 自动转成 Windows 路径（debug 实测：`/v1/...` 被改成 `/api/F:/Git/Git/v1/...`），请求 URL 错误、返回 404。**这是本机 PATCH 失败的唯一原因，与 .json 无关**（`api` 命令会自动补 `.json` 后缀，已用 `--debug` 实测确认：不带 `.json` 的请求最终 URL 仍是 `.../issues/9.json`）。**解决：命令前加 `MSYS_NO_PATHCONV=1`**（实测 `MSYS_NO_PATHCONV=1 gitlink-cli api PATCH /v1/.../issues/9 ...` 返回 `ok:true`）；或路径用双斜杠 `//v1/...`。cmd.exe 无此路径转换问题（PowerShell 的坑是引号，见上一条）。 +- **`assigned_to_id` 用数字 ID：** 不是 login 字符串。从 `issue +assigners` 返回里取 `id` 字段。⚠️ **实测：个人仓库 `assigners` 为空时，用 owner user_id 兜底分配也不生效**——GitLink 校验 `assigned_to_id` 必须在 assigners 候选列表内，PATCH 虽返回 `ok:true` 但 `assigned_to` 仍为空。个人仓库需先 `member +add` 添加 collaborator 才能分配，否则跳过分配并在报告标注"无可分配成员"。 - **notification +list 是自查询限定：** 该命令查 `/users//messages`，**GitLink 平台只允许用户查询自己的通知**，跨用户查询返回 `[403] 您没有权限进行该操作`（实测：zhangqing23 查 ylly 的通知被拒）。因此无法第三方代为验证通知到达，只能由责任人本人自查。 - **分配会自动触发通知：** GitLink 平台在 `assigned_to_id` 变更时会自动给被分配人发站内消息，**无需也不存在** "send notification" 命令。`notification +list` 只用于**验证**通知已生成（且只能自验证）。 - **`assigners` 字段两个位置：** Issue 对象里 `assigners` 是已分配人列表（数组），`issue +assigners` 命令返回的是**可分配的候选人**列表。两者不同，别混淆。 diff --git a/skills/gitlink-issue-triage/examples/screenshots/00-环境确认.png b/skills/gitlink-issue-triage/examples/screenshots/00-环境确认.png new file mode 100644 index 0000000..2e0f1ee Binary files /dev/null and b/skills/gitlink-issue-triage/examples/screenshots/00-环境确认.png differ diff --git a/skills/gitlink-issue-triage/examples/screenshots/01-issue-list.png b/skills/gitlink-issue-triage/examples/screenshots/01-issue-list.png new file mode 100644 index 0000000..a1a9303 Binary files /dev/null and b/skills/gitlink-issue-triage/examples/screenshots/01-issue-list.png differ diff --git a/skills/gitlink-issue-triage/examples/screenshots/02-label-list.png b/skills/gitlink-issue-triage/examples/screenshots/02-label-list.png new file mode 100644 index 0000000..5a930ca Binary files /dev/null and b/skills/gitlink-issue-triage/examples/screenshots/02-label-list.png differ diff --git a/skills/gitlink-issue-triage/examples/screenshots/03-标签写入.png b/skills/gitlink-issue-triage/examples/screenshots/03-标签写入.png new file mode 100644 index 0000000..3779ae9 Binary files /dev/null and b/skills/gitlink-issue-triage/examples/screenshots/03-标签写入.png differ diff --git a/skills/gitlink-issue-triage/examples/screenshots/04-assigners空.png b/skills/gitlink-issue-triage/examples/screenshots/04-assigners空.png new file mode 100644 index 0000000..853f873 Binary files /dev/null and b/skills/gitlink-issue-triage/examples/screenshots/04-assigners空.png differ diff --git a/skills/gitlink-issue-triage/examples/screenshots/05-patch分配.png b/skills/gitlink-issue-triage/examples/screenshots/05-patch分配.png new file mode 100644 index 0000000..3c65916 Binary files /dev/null and b/skills/gitlink-issue-triage/examples/screenshots/05-patch分配.png differ diff --git a/skills/gitlink-issue-triage/examples/screenshots/06-列出通知.png b/skills/gitlink-issue-triage/examples/screenshots/06-列出通知.png new file mode 100644 index 0000000..3116c2b Binary files /dev/null and b/skills/gitlink-issue-triage/examples/screenshots/06-列出通知.png differ diff --git a/skills/gitlink-issue-triage/examples/screenshots/07-没有权限.png b/skills/gitlink-issue-triage/examples/screenshots/07-没有权限.png new file mode 100644 index 0000000..bc638d4 Binary files /dev/null and b/skills/gitlink-issue-triage/examples/screenshots/07-没有权限.png differ diff --git a/skills/gitlink-issue-triage/examples/verification.md b/skills/gitlink-issue-triage/examples/verification.md index 8157c08..a7d1594 100644 --- a/skills/gitlink-issue-triage/examples/verification.md +++ b/skills/gitlink-issue-triage/examples/verification.md @@ -184,9 +184,20 @@ invalid JSON body: invalid character 's' looking for beginning of object key str **已确认事实：** - `cmd/api/api.go` 的 `--body` 解析逻辑用 Go `encoding/json`，对合法 JSON 一定解析成功（源码已读） - 失败 100% 是 PowerShell 引号问题，反引号 / `--%` / 单引号 + 变量三种方式均被 PS 5 吞掉引号 -- 在 **Git Bash** 或 **Linux/macOS** 终端跑同一条命令可正常通过（bash 单引号 100% 原样保留 JSON） +- **Windows shell 双坑（后续 ylly 环境 Git Bash 补充验证）：** PowerShell 5 吞 JSON 双引号；**Git Bash/MSYS2 会把 `/` 开头的路径参数改写成 `/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`**。 -**对工作流的影响：** 仅"分配责任人"这步无法在本机 PowerShell 实跑验证；分类打标签、查看 Issue、列通知等其他命令全部实跑通过。建议团队在最终演示时用 Git Bash 跑 PATCH 完整复现。 +**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）。 --- @@ -214,7 +225,7 @@ invalid JSON body: invalid character 's' looking for beginning of object key str | 2 分配+通知 | `issue +assigners` | ✅ | 真实返回空（个人仓库场景）| | 2 分配+通知 | `notification +list`（自己）| ✅ | zhangqing23 返回 9 条 | | 2 分配+通知 | `notification +list`（他人）| ⚠️ 403 | 平台限制：只允许查自己 | -| 2 分配+通知 | `api PATCH`（分配）| ⚠️ 待完整复现 | 源码已核对，PowerShell 引号阻塞实跑，Git Bash 可跑通 | +| 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 一致）。 @@ -225,18 +236,18 @@ invalid JSON body: invalid character 's' looking for beginning of object key str ## 截图清单 -> **本任务按用户指示跳过截图存证环节**，以原始命令输出（见上文代码块）作为验证证据。如团队后续需要补截图，可在 Claude Code 中喂入 SKILL.md 让 Agent 自主执行（参照 ylly/ZxR 的做法），完整截图路径如下： +> 截图已补全（ylly 环境在 PowerShell / Git Bash 实跑），存放于 `screenshots/` 目录： -| 建议文件名 | 对应步骤 | 内容 | +| 文件名 | 对应步骤 | 内容 | |----------|---------|------| -| `screenshots/00-环境确认.png` | 第 0 步 | auth status + go build 成功 | -| `screenshots/01-issue-list.png` | 工作流 1 | issue +list 返回 8 条 | +| `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 | 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 成功（团队演示时补）| +| `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 拒绝 | ---