From 955e8dd2b7ab446ec73c762a55aa9eb33b3fac2b Mon Sep 17 00:00:00 2001 From: z2_cc Date: Sun, 21 Jun 2026 10:22:19 +0800 Subject: [PATCH] =?UTF-8?q?feat(skills):=20=E6=96=B0=E5=A2=9E=20gitlink-pr?= =?UTF-8?q?-deep-review=20PR=20=E6=B7=B1=E5=BA=A6=E5=AE=A1=E6=9F=A5=20Skil?= =?UTF-8?q?l?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 编排 gitlink-code-review 取实现层结果 + 自研推理层（设计/需求一致性、跨模块影响、业务安全合规） - 综合裁决：实现质量 × 跨模块影响 × 一致性 × 安全 → 风险评分 + 阻断/谨慎/放行建议 - 需求一致性锚点：交互式获取（设计文档 + PR 关联 Issue，皆无则降级标注低置信度） - 跨模块仅追直接调用方（git grep），写动作默认 dry-run 且 --status common 不越权 - 与 code-review 职责正交（实现层 vs 设计/一致性层） - 命令面/字段均基于本地源码编译产物实测（z2_cc/gitlink-cli PR#1 全链路验证后已清理） - 注册到 skills/README.md 目录树与 AI Agent 能力清单 --- skills/README.md | 5 + skills/gitlink-pr-deep-review/SKILL.md | 205 ++++++++++++++++++ .../examples/pr-deep-review-workflow.md | 149 +++++++++++++ 3 files changed, 359 insertions(+) create mode 100644 skills/gitlink-pr-deep-review/SKILL.md create mode 100644 skills/gitlink-pr-deep-review/examples/pr-deep-review-workflow.md diff --git a/skills/README.md b/skills/README.md index ab7b3d7..dc22dda 100644 --- a/skills/README.md +++ b/skills/README.md @@ -112,6 +112,10 @@ skills/ │ ├── SKILL.md # 重复检测与关联收敛指南 │ └── examples/ │ └── duplicate-detection-workflow.md # 端到端工作流与验证记录 +├── gitlink-pr-deep-review/ # PR 深度审查 +│ ├── SKILL.md # 编排 code-review + 设计/一致性推理 +│ └── examples/ +│ └── pr-deep-review-workflow.md # 端到端工作流与验证记录 └── gitlink-workflow/ # AI 自动化工作流 └── SKILL.md # 工作流模板（Issue 分类、PR Review、Release Notes） ``` @@ -306,6 +310,7 @@ AI 代理可以： - ✅ 自动生成 Release Notes - ✅ 自动执行代码审查 - ✅ 自动检测并收敛重复 Issue（[gitlink-duplicate-detector](gitlink-duplicate-detector/SKILL.md)） +- ✅ PR 深度审查：实现质量 + 设计/需求一致性 + 跨模块影响（[gitlink-pr-deep-review](gitlink-pr-deep-review/SKILL.md)） --- diff --git a/skills/gitlink-pr-deep-review/SKILL.md b/skills/gitlink-pr-deep-review/SKILL.md new file mode 100644 index 0000000..b8dfed6 --- /dev/null +++ b/skills/gitlink-pr-deep-review/SKILL.md @@ -0,0 +1,205 @@ +--- +name: gitlink-pr-deep-review +version: 1.0.0 +description: "PR 深度审查：编排代码质量审查 + 自研推理层，综合评估一个 PR 的实现质量、跨模块影响、需求/设计一致性、业务安全合规，给出综合裁决与动作建议。当用户需要深度审查 Pull Request、判断改动是否对得起需求/是否影响其他模块时触发。" +metadata: + requires: + bins: ["gitlink-cli"] + cliHelp: "gitlink-cli pr --help" + requiresVersion: "需要 gitlink-cli 含 `pr +versions/+version-diff/+review` 的版本（本仓库源码已具备；npm 发布版 v0.1.13 能力不全，需源码编译版或 ≥ v0.2.0）" +--- + +# gitlink-pr-deep-review（PR 深度审查） + +**CRITICAL — 开始前必须先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md)，其中包含认证、权限处理和 API 注意事项。** +**CRITICAL — 所有 Shortcuts 在执行写入操作（回贴评审/评论）前，务必先确认用户意图；默认 dry-run，综合评审一律用 `--status common`（评论），不替人 approve/reject。** +**CRITICAL — GitLink 操作只能用 `gitlink-cli`，禁止用 `gh`（GitHub CLI）操作 GitLink 资源。** + +## 说明 + +本 Skill 围绕 **PR 审查**提供深度服务：对给定 PR，**编排** `gitlink-code-review`（或 linter）取得"实现层"质量结果，再叠加本 Skill 的**自研推理层**——跨模块影响、需求/设计一致性、业务级安全/合规——交叉合成一份综合评审报告，给出风险评分与动作建议（阻断/谨慎/放行），并可在确认后回贴到 PR。 + +它**不重复** code-review 的风格/缺陷检测，而是**消费**其结果作为风险输入，专注于 code-review 回答不了的问题：**这个改动该不该这样改、会牵动什么、对不对得起它的目标。** + +## 前置条件 + +- 已 `gitlink-cli auth login`（`auth status` 为已登录）。 +- gitlink-cli 版本需支持 `pr +versions` / `+version-diff` / `+review`（本仓库源码已具备；npm 发布版 v0.1.13 不具备）。 +- **本地有目标仓库的 clone**（跨模块调用方用 `git grep`、设计文档用本地读取）。 +- （可选）读过 [`../gitlink-code-review/SKILL.md`](../gitlink-code-review/SKILL.md)，便于编排其实现层工作流。 + +## 与 `gitlink-code-review` 的边界 + +| 维度 | `gitlink-code-review`（被编排） | `gitlink-pr-deep-review`（本 Skill） | +|---|---|---| +| 审查对象 | 代码**本身**（diff 内在质量） | 改动的**意图、设计、跨模块影响** | +| 核心问题 | 代码写得对不对/好不好 | 该不该这样改、会牵动什么、对不对得起目标 | +| 视角 | 单文件、当下 | 跨文件、关联需求/架构 | +| 工作性质 | 机械检测为主 | 推理判断为主 | +| 关系 | 上游信号 | 编排者 + 综合裁决 | + +> 职责正交：code-review 管"实现质量"，本 Skill 管"设计/意图/影响一致性"，可串联。 + +## 依赖的 Shortcuts + +| Shortcut | 关键参数 | 用途 | +|----------|----------|------| +| `pr +view` | `--id `、`--format json` | 标题=`data.issue.subject`，**正文=`data.issue.description`（嵌套）**；`comments_count` | +| `pr +files` | `--id` | 变更文件列表 | +| `pr +version-diff` | `--id`、`--version-id` | **真实 diff 内容**（version_id 来自 `+versions`） | +| `pr +versions` | `--id` | patchset 列表，取 `version_id` | +| `pr +reviews` | `--id` | 已有评审（避免重复回贴） | +| `pr +review` | `--id`、`--status common`、`--content`、`--dry-run` | 回贴综合评审（默认 dry-run） | +| `pr +commits` / `pr +comments` | `--id` | 提交 / 评审行内评论（上下文） | +| `issue +view` | `--number ` | 关联 Issue 需求锚点 | +| `git grep`（本地） | `git grep -n "" -- '*.ext'` | 跨模块**直接调用方** | +| 本地文件 `git show`/Read | — | 设计文档读取 | + +> ⚠️ `--id` 取 **Web 编号**（`pr +list` 的 `pull_request_number`），非内部 `id`。 + +## 工作流程 + +``` +1. pr +view --id → 取标题/正文（issue.subject / issue.description） +2. pr +files --id → 变更文件清单 + pr +versions --id → 取 version_id + pr +version-diff --id --version-id → 真实 diff +3. 锚点获取（见下「锚点获取流程」） → 需求/设计一致性依据 +4. 编排实现层：按 gitlink-code-review/SKILL.md 跑实现层审查 + → 取分级问题清单（Critical/Warning/Suggestion）作为风险输入 +5. 跨模块影响：对改动符号 git grep 找直接调用方 → 标破坏性变更 +6. 推理层：需求/设计一致性 + 业务安全/合规一致性（对照锚点） +7. 综合裁决：实现层 + 影响 + 一致性 + 安全 交叉 → 风险评分 + 动作建议 + ----- 以上为只读分析，默认到此为止 ----- +8. （确认后）pr +review --id --status common --content "<综合报告>" [--dry-run] +``` + +## 锚点获取流程（需求一致性审查的依据） + +需求/设计一致性需要一个"锚点"（正确性的参照）。按下列**交互式决策树**获取： + +``` +Step A：询问使用者 —— 仓库中是否有与该 PR 相关的设计/需求文档？ + ├─ 有 → 使用者提供文档路径（仓库内相对路径）→ 本地读取（git show / Read）→ design_doc + └─ 无 → design_doc = ∅ + +Step B：自动检测 PR 关联 Issue + └─ pr +view 的 issue.description 里正则提取 #N → issue +view --number N → linked_issue + （无 #N 则 linked_issue = ∅） + +Step C：组合锚点 + ├─ design_doc ✓ + linked_issue ✓ → 锚点 = 两者合并（Issue=需求源，文档=设计源）【置信度高】 + ├─ 仅其一 → 锚点 = 该单一来源【置信度中】 + └─ 两者皆无 → 锚点 = PR 标题/描述自述目标；报告显著标注 + 「⚠️ 无外部需求锚点，一致性结论置信度降低」【置信度低】 +``` + +> 无锚点时**不要拒绝审查**，而是降级为"以 PR 自述目标为准"，并明确标注置信度。 + +## 评审维度与规则 + +### ① 实现层（编排 `gitlink-code-review`） +- 调度 code-review 工作流（或项目 linter），取其分级问题清单。 +- 本 Skill **不重新检测**风格/缺陷，只**消费**：把 Critical/Warning 数量与位置作为风险输入。 + +### ② 跨模块影响（机械，自研） +- 从 diff 提取**改动符号**（函数名、类型名、导出标识）。 +- 对每个符号 `git grep -n "" -- ''` 找**直接调用方**（仅一层，不追传递依赖）。 +- 标注破坏性变更：签名改变/删除/重命名 → 受影响调用方清单 + 影响范围分级（核心模块/边缘/无）。 + +### ③ 需求/设计一致性（推理，自研） +- 以**锚点**判断：PR 是否真正实现了需求？设计是否与现有架构一致？有无过度设计/设计缺陷？ +- 锚点缺失时降级（见上），结论标注低置信度。 + +### ④ 业务级安全/合规一致性（推理，自研） +- 非通用红线（注入/硬编码密钥等属 code-review），而是**结合需求上下文**判断业务约束是否对齐（如：该改动是否绕过了应有的权限校验、是否合规留痕）。 + +### ⑤ 综合裁决（合成） +| 综合风险 | 触发条件（任一） | 动作建议 | +|---|---|---| +| 🔴 高 | 实现层有 Critical / 破坏性变更影响核心模块 / 需求未实现 | **阻断**合入 | +| 🟡 中 | 实现层有 Warning / 影响边缘模块 / 设计有改进点 | **谨慎**：修改后再合 | +| 🟢 低 | 实现层仅 Suggestion / 无跨模块破坏 / 与锚点一致 | **放行** | + +## 综合评审报告模板 + +````markdown +## 🔍 PR 深度审查 — # <标题> + +**关联锚点**： + +### 📎 实现层（编排 gitlink-code-review） +- Critical: | Warning: | Suggestion: （详见 code-review 报告） +- 摘要：<最关键的 1–3 条> + +### 🧩 跨模块影响 +- 改动符号：<列表> +- 直接调用方受影响：<文件:行 列表 / 无> +- 影响范围：核心模块 / 边缘 / 无 + +### 🎯 需求/设计一致性 +- 需求达成：✅/⚠️/❌ <理由> +- 设计一致性：✅/⚠️/❌ <理由> + +### 🔒 业务安全/合规 +- <结论 + 理由> + +### 🏁 综合裁决 +| 维度 | 结果 | +|---|---| +| 实现质量 | ✅/⚠️/❌ | +| 跨模块影响 | ✅/⚠️/❌ | +| 一致性 | ✅/⚠️/❌ | +| 安全合规 | ✅/⚠️/❌ | +**综合风险：🔴高/🟡中/🟢低 → 建议：<阻断/谨慎/放行>。一句话理由：<...>** +```` + +## 使用示例 + +> 在目标仓库的 git 目录下可省略 `--owner/--repo`。AI 场景统一 `--format json`。 + +```bash +# 0) 前置 +gitlink-cli auth status +gitlink-cli pr +versions --help # 存在 → 版本满足 +git config pull.rebase false 2>/dev/null; cd <目标仓库 clone> + +# 1) 取 PR 上下文（N = Web 编号，来自 pr +list 的 pull_request_number） +N=1 +gitlink-cli pr +view --id $N --format json # 标题=issue.subject, 正文=issue.description +gitlink-cli pr +files --id $N --format json # 变更文件 +VID=$(gitlink-cli pr +versions --id $N --format json | node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>{const d=JSON.parse(s).data;const a=Array.isArray(d)?d:d.versions;process.stdout.write(String((a[0]||{}).id));});') +gitlink-cli pr +version-diff --id $N --version-id $VID --format json # 真实 diff + +# 2) 锚点：从 PR body 提取关联 Issue → 取需求 +ISSUE_N=$(gitlink-cli pr +view --id $N --format json | node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>{const b=JSON.parse(s).data.issue.description;const m=b.match(/#(\d+)/);process.stdout.write(m?m[1]:"");});') +[ -n "$ISSUE_N" ] && gitlink-cli issue +view --number $ISSUE_N --format json +# 另：询问使用者是否有设计文档，有则 git show 读取 + +# 3) 跨模块直接调用方（对每个改动符号） +git grep -n "ChangedFunction" -- '*.go' + +# 4) 编排实现层：按 ../gitlink-code-review/SKILL.md 跑一遍，取分级问题清单 + +# 5) 综合裁决后，确认 → 回贴（默认 dry-run；--status common 不替人 approve/reject） +gitlink-cli pr +review --id $N --status common \ + --content "## 🔍 PR 深度审查 ..." --dry-run # 先预览 +# 确认无误后去掉 --dry-run 正式回贴 +``` + +## 已知限制（实测，v0.2.0-dev / 本地源码版） + +- **`pr +diff` 不存在**：本地版无此子命令（`skills/gitlink-pr/SKILL.md` 里的 `+diff` 已过时）。用 `pr +files` + `pr +version-diff`。 +- **`pr +view` 正文嵌套**：标题在 `data.issue.subject`、正文在 `data.issue.description`，**非顶层**字段。 +- **`pr +comments` 只列评审行内评论**，不含普通评论。普通 `pr +comment` 是否落地，用 `pr +view` 的 `comments_count` 验证。 +- **CLI 远程文件读取不可用**：`api GET .../sub_entries` 返回 404、`.../raw/...` 返回空。设计文档**一律走本地**（`git show`/Read）。 +- **跨模块仅直接调用方**：不追多层传递依赖（按设计，控制规模）。 +- **无锚点降级**：PR 未关联 Issue 且无设计文档时，一致性结论置信度低，须显著标注。 + +## 注意事项 + +- **默认 dry-run**：综合评审先 `--dry-run` 预览，确认后再正式回贴。 +- **不越权**：回贴用 `--status common`（评论），**不**用 `approved`/`rejected` 替人决定合入。 +- **编排而非复制**：实现层交给 code-review/linter，本 Skill 只消费其结果，不重写检测规则（避免与 code-review 重合）。 +- **大 PR**：`pr +version-diff` 输出可能很大，分段处理；`git grep` 限定文件 glob 控制规模。 +- **锚点优先级**：关联 Issue 是最可靠的需求源；设计文档次之；两者皆无才降级。 diff --git a/skills/gitlink-pr-deep-review/examples/pr-deep-review-workflow.md b/skills/gitlink-pr-deep-review/examples/pr-deep-review-workflow.md new file mode 100644 index 0000000..1a72c89 --- /dev/null +++ b/skills/gitlink-pr-deep-review/examples/pr-deep-review-workflow.md @@ -0,0 +1,149 @@ +# PR 深度审查 — 端到端工作流示例与验证记录 + +> 配套文档：[`../SKILL.md`](../SKILL.md) +> 本文记录一次**真实跑通**的完整工作流（只读分析 + 写动作），含真实命令输出，作为「使用示例 + Agent 平台验证结果」交付物。 + +## 验证环境 + +| 项 | 值 | +|----|----| +| Agent 平台 | Claude Code | +| gitlink-cli | `local-build`（本仓库源码编译产物，**非** npm 发布版 v0.1.13） | +| 登录用户 | `z2_cc`（`auth status` ✓） | +| 测试目标 | `z2_cc/gitlink-cli`（z2_cc 有写权限，Owner） | +| 测试 PR | #1（`feat(auth): 登录态过期自动跳转登录页`，body 引用 `#17`） | +| 验证日期 | 2026-06-17 | + +## 测试数据构造（造一个"PR + 关联 Issue"的真实样本） + +为覆盖「关联 Issue 锚点」+「写链路」，先造测试数据（验证后已清理）： + +```bash +# 1) 造需求锚点 Issue（→ Web #17） +gitlink-cli issue +create --owner z2_cc --repo gitlink-cli \ + -t "[deep-review-test] 登录态过期未自动跳转" -b "## 需求 ..." # → id=144670, #17 + +# 2) 造带 diff 的分支并 push（提交署名 z2_cc） +git checkout -b test/pr-deep-review-probe +# <新增 _deep_review_probe.md> +git commit -m "test(pr-deep-review): ...（关联 #17）" +git push -u origin test/pr-deep-review-probe + +# 3) 建 PR，body 引用 #17（→ Web #1） +gitlink-cli pr +create --owner z2_cc --repo gitlink-cli \ + --head test/pr-deep-review-probe --base master \ + --title "feat(auth): 登录态过期自动跳转登录页（含回跳）" \ + --body "## 关联需求\n修复 #17 ：登录态过期未自动跳转。..." # → id=144671, #1 +``` + +## 步骤 1：取 PR 上下文（实测输出） + +```bash +N=1 +gitlink-cli pr +view --owner z2_cc --repo gitlink-cli --id $N --format json +``` +→ 标题在 `data.issue.subject`、**正文在 `data.issue.description`**（嵌套，非顶层）： +``` +PR 标题: feat(auth): 登录态过期自动跳转登录页（含回跳） +body 长度: 153 ← data.issue.description +``` + +```bash +gitlink-cli pr +files --id 1 --format json # → 变更文件: 1 (_deep_review_probe.md) +VID=$(gitlink-cli pr +versions --id 1 --format json | ...) # → version_id=17388 +gitlink-cli pr +version-diff --id 1 --version-id 17388 # → diff 条目: 1 +``` + +## 步骤 2：锚点获取（实测：从 body 提取 #N → 取需求） + +```bash +# 从 PR body 提取关联 Issue 编号 +BODY=$(gitlink-cli pr +view --id 1 --format json | ... data.issue.description) +ISSUE_N=$(echo "$BODY" | ... match /#(\d+)/) # → 17 +``` +实测：从 153 字 body 提取到 **`#17`** ✓ + +```bash +gitlink-cli issue +view --number 17 --format json # 取需求锚点 +``` +→ 锚点 Issue：`[deep-review-test] 登录态过期未自动跳转`，需求正文 120 字（含验收标准）✓ + +> （若使用者还提供了设计文档路径，则 `git show ` 读取后与 Issue 合并为锚点；本次测试仅 Issue 锚点。） + +## 步骤 3：跨模块直接调用方（实测机制） + +```bash +git grep -n "<改动符号>" -- '*.go' +``` +→ `git grep` 机制可用（本仓库实测命中准确）。本测试 PR 仅改文档无代码符号，故无调用方受影响。 + +## 步骤 4：编排实现层 + 推理层 → 综合裁决（示例输出） + +```markdown +## 🔍 PR 深度审查 — #1 feat(auth): 登录态过期自动跳转登录页 + +**关联锚点**：#17（从 PR body 自动识别） + +### 📎 实现层（编排 gitlink-code-review） +- Critical: 0 | Warning: 0 | Suggestion: 0（本 PR 仅新增说明文档，无逻辑代码） + +### 🧩 跨模块影响 +- 改动符号：无（仅文档） +- 直接调用方受影响：无 + +### 🎯 需求/设计一致性 +- 需求达成：❌ #17 要求 401→自动跳转，本 PR 尚无实际拦截/跳转代码（仅文档占位） + +### 🏁 综合裁决 +| 维度 | 结果 | +|---|---| +| 实现质量 | ✅ | +| 跨模块影响 | ✅ | +| 一致性 | ❌ 未实现 | +**综合风险：🟡中 → 建议：谨慎，补全实现后再合入。** +``` + +## 步骤 5：写动作（实测：真实回贴 + 验证落地） + +```bash +# 回贴综合评审（--status common = 评论，不替人 approve/reject） +gitlink-cli pr +review --owner z2_cc --repo gitlink-cli --id 1 \ + --status common --content "## 🔍 PR 深度审查 ..." --format json +``` +→ `评审已回贴 ✓` + +```bash +# 验证评审落地 +gitlink-cli pr +reviews --id 1 --format json # → 已有 reviews: 1，含「深度审查」 ✓ +``` + +```bash +# 补充普通评论 +gitlink-cli pr +comment --owner z2_cc --repo gitlink-cli --id 1 \ + --body "💡 提示：补全 401 拦截逻辑后可重新触发深度审查。" --format json +``` +→ `评论已发布 ✓`；落地验证用 `pr +view` 的 `comments_count`（=1）。 +> ⚠️ `pr +comments` 只列**评审行内评论**，不含普通评论——普通评论落地看 `pr +view` 的 `comments_count`。 + +## 关键验证结论 + +| 能力 | 命令 | 状态 | +|------|------|------| +| 取 PR 标题/正文 | `pr +view`（`data.issue.subject`/`data.issue.description`） | ✅ 真实返回 | +| 变更文件 | `pr +files` | ✅ | +| 真实 diff | `pr +version-diff --version-id` | ✅（`pr +diff` 不存在） | +| patchset | `pr +versions` | ✅ | +| **关联 Issue 锚点** | `pr +view` body→`#N`→`issue +view` | ✅ 端到端跑通 | +| 跨模块直接调用方 | `git grep` | ✅ 机制可用 | +| **回贴综合评审** | `pr +review --status common` | ✅ 实际回贴 + `pr +reviews` 验证 | +| 普通评论 | `pr +comment` | ✅（落地看 `pr +view` `comments_count`） | + +## 清理 + +测试产物已全部清理，`z2_cc/gitlink-cli` 无残留： +- `pr +close --id 1`（关闭测试 PR） +- `git push origin --delete test/pr-deep-review-probe`（删远端分支） +- `issue +delete --number 17`（删测试 Issue） +- 本地切回 `master`、删本地分支（工作树干净，`master == origin/master`） + +> ⚠️ 版本前提：以上能力依赖含 `pr +versions/+version-diff/+review` 的 gitlink-cli（本仓库源码已具备；npm 发布版 v0.1.13 不具备）。参赛验证基于本地源码编译产物。