From c12875ac260bdb56a2df5b905f76efb050b048f7 Mon Sep 17 00:00:00 2001 From: Martin Date: Tue, 23 Jun 2026 22:38:30 +0800 Subject: [PATCH] =?UTF-8?q?docs(review):=20REFERENCE=20=E5=9B=9E=E5=A1=AB?= =?UTF-8?q?=20reviews=20API=20=E5=AE=9E=E6=B5=8B=E7=BB=93=E8=AE=BA=20+=20?= =?UTF-8?q?=E7=9C=9F=E5=AE=9E=E8=B5=B0=E6=9F=A5=E7=A4=BA=E4=BE=8B?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- skills/gitlink-review/REFERENCE.md | 24 +++--- .../examples/review-workflow.md | 83 +++++++++++++++++++ 2 files changed, 94 insertions(+), 13 deletions(-) create mode 100644 skills/gitlink-review/examples/review-workflow.md diff --git a/skills/gitlink-review/REFERENCE.md b/skills/gitlink-review/REFERENCE.md index 7a20799..c313b27 100644 --- a/skills/gitlink-review/REFERENCE.md +++ b/skills/gitlink-review/REFERENCE.md @@ -80,25 +80,23 @@ ## 四、reviews API 实测结论（决定行内评论） -> ⏳ **待 live 验证**：本节需在测试 PR 上实测 `POST /pulls/:id/reviews` 后填入真实结论。当前 GitLink API 处于 403 网关拦截（疑似本会话高频调用触发限流），实测暂缓。 - -**预期（依据 `gitlink-triage` 记录的已知问题）**：`gitlink-cli api POST` 存在 URL 注入 bug（git exec-path 被拼入 API URL → 404），因此行内评论**预计不可用**。 - -**实测命令**（待 API 恢复后执行）： +**实测（2026-06-23，测试 PR chroe/gitlink-cli#3）**： ```bash -gitlink-cli api POST ///pulls//reviews \ +gitlink-cli api POST /chroe/gitlink-cli/pulls/3/reviews \ --body '{"body":"...","event":"COMMENT"}' +# → 404 Not Found（{"status":404,"error":"Not Found"}） + +gitlink-cli api GET /chroe/gitlink-cli/pulls/3/reviews +# → 返回 HTML 前端页面（非 JSON API 端点） ``` -**待填字段**（实测后替换）： -- `REVIEWS_API` = ``（实测结果） -- `REVIEWS_NOTES` = `<观察到的响应或错误>` -- 是否支持行内定位（`line/path/side`）= `<是/否>` +**结论**：**行内评论不可用**。两层原因： -**设计影响**： -- 若**不可用**（预期）→ 行内评论关闭，仅用 `pr +comment` 发总结评论；`--inline` 被忽略并提示原因。 -- 若**可用** → `--inline` 时对 🔴/🟡 发现调用上述 API 发行内评论；请求体按实测支持的字段构造。 +1. `gitlink-cli api POST` 存在已知 URL 注入 bug（git exec-path 被拼入 API URL），所有 `api POST` 返回 404——与 `gitlink-triage` 记录一致。 +2. `api GET /pulls/:id/reviews` 返回 HTML（前端路由），说明该路径不是有效的 JSON API 端点。 + +**设计影响**：行内评论关闭，**仅用 `pr +comment` 发总结评论**（已在 PR #3 实测：评论 id 477757 成功发布，PR 评论数 0→1）。`--inline` 参数被忽略并提示"行内评论不可用，已降级为总结评论"。 --- diff --git a/skills/gitlink-review/examples/review-workflow.md b/skills/gitlink-review/examples/review-workflow.md new file mode 100644 index 0000000..cad1ee8 --- /dev/null +++ b/skills/gitlink-review/examples/review-workflow.md @@ -0,0 +1,83 @@ +# 示例：对植入缺陷 PR 的智能审查（真实数据） + +> 基于 `chroe/gitlink-cli` 测试 PR #3（`test/review-fixture` 分支）于 2026-06-23 实际执行。 +> 该 PR 故意植入 4 个问题用于验证 gitlink-review skill：空指针、硬编码 Token、缺测试、伪阳性。 + +--- + +## Step 1：取上下文 + +```bash +gitlink-cli pr +view --owner chroe --repo gitlink-cli --id 3 --format json +gitlink-cli pr +files --owner chroe --repo gitlink-cli --id 3 --format json +gitlink-cli pr +diff --owner chroe --repo gitlink-cli --id 3 --format json +``` + +**范围**：1 文件 `review_fixture.go`，+47/-0，head sha `00dee19`，无噪音文件需跳过。 + +## Step 2：6 视角扫描 + 对抗式自检 + +| 候选发现 | 视角 | 自检结果 | +|----------|------|----------| +| `Greet` 中 `u.Name` 解引用可能为 nil 的 `u` | correctness | ✅ 成立（`CurrentUser` 对空 token 返回 nil，无外层判空）→ 保留 🔴 | +| `AdminToken` 硬编码 `glpat-...` | security | ✅ 成立（硬编码凭据）→ 保留 🔴 | +| `Welcome`/`Greet`/`Divide` 等新函数无 `_test.go` | tests | ✅ 成立（本 PR 无测试文件）→ 保留 🟡 | +| `Divide(a,b)` 除零风险 | correctness | ❌ **被反驳**：`DoMath` 已保证调用时 `x≠0`，真实路径除数非 0 → 丢弃 | + +**自检丢弃：1 条（refuted=1）**。 + +## Step 3：发布报告卡（真实输出） + +```bash +gitlink-cli pr +comment --owner chroe --repo gitlink-cli --id 3 \ + --body "<报告卡全文>" +``` + +**真实结果**：`ok: true`，评论 id `477757`，PR 评论数 0→1。 + +报告卡全文（实际发布内容）： + +````markdown +🤖 **gitlink-review 报告** + +**结论**：⚠️ 建议修改（2 🔴阻塞 / 1 🟡建议 / 0 🔵nit） +**范围**：1 文件，+47/-0（跳过 0 噪音文件）｜视角：6｜自检丢弃：1 + +| 严重度 | 视角 | 位置 | 问题 | +|:---:|---|---|---| +| 🔴 | correctness | review_fixture.go:18 | 空指针解引用 | +| 🔴 | security | review_fixture.go:23 | 硬编码 Token | +| 🟡 | tests | review_fixture.go:26 | 新函数无测试 | + +### 🔴 阻塞（合并前需处理） +1. **[correctness] review_fixture.go:18** — `Greet` 中 `u := CurrentUser(token)` 后直接 `u.Name`；`token==""` 时 `CurrentUser` 返回 nil，解引用 panic。 + - **建议**：`if u := CurrentUser(token); u != nil { return "hello " + u.Name }; return ""` +2. **[security] review_fixture.go:23** — `var AdminToken = "glpat-FAKEFAKEFAKE0000000000"` 硬编码凭据。 + - **建议**：改 `os.Getenv("ADMIN_TOKEN")`，移除占位串。 + +### 🟡 建议 +1. **[tests] review_fixture.go:26** — 新函数无 `_test.go`，建议补表驱动测试。 + +### ✅ 未发现问题的方面 +- 性能：无热点循环 / N+1 +- 生产风险：本文件带 `//go:build ignore`，不参与构建 + +### 🗑 对抗式自检丢弃（1） +- ~~[correctness] review_fixture.go:30 `Divide` 除零~~：`DoMath` 调用前已 `if x==0 {return 0}`，真实路径不除零 → 伪阳性丢弃。 + +--- + +```` + +## Step 4：幂等与过期 + +报告卡内嵌哨兵 ``： + +- 重跑（不带 `--refresh`）时检测到哨兵 → 提示"已存在审查，使用 --refresh 更新"，不重复发布。 +- `sha` 字段记录审查所基于的 head commit；PR 有新提交（sha 不匹配）时提示"审查已过期，建议重审"。 + +## 关键结论 + +- **3 个真实缺陷被对应视角命中**（correctness / security / tests），**1 个伪阳性被对抗式自检丢弃**（refuted=1）——验证了"质量门"有效降低误报。 +- **行内评论不可用**（`api POST /pulls/:id/reviews` → 404；`api GET` → HTML），自动降级为 `pr +comment` 总结评论，实测发布成功（评论 id 477757）。 +- 报告卡带哨兵，支持幂等与"过期重审"提示。