feat(skills): 新增 gitlink-pr-deep-review PR 深度审查 Skill

- 编排 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 能力清单
2026-06-21 10:22:19 +08:00 · 2026-06-21 10:22:19 +08:00 · 955e8dd2b7
parent f1e237ad18
commit 955e8dd2b7
3 changed files with 359 additions and 0 deletions
--- 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)）

 ---

--- a/skills/gitlink-pr-deep-review/SKILL.md
+++ 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 <Web#>`、`--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 <Web#>` | 关联 Issue 需求锚点 |
+| `git grep`（本地） | `git grep -n "<symbol>" -- '*.ext'` | 跨模块**直接调用方** |
+| 本地文件 `git show`/Read | — | 设计文档读取 |
+
+> ⚠️ `--id` 取 **Web 编号**（`pr +list` 的 `pull_request_number`），非内部 `id`。
+
+## 工作流程
+
+```
+1. pr +view --id <N>               → 取标题/正文（issue.subject / issue.description）
+2. pr +files --id <N>              → 变更文件清单
+   pr +versions --id <N>           → 取 version_id
+   pr +version-diff --id <N> --version-id <V>  → 真实 diff
+3. 锚点获取（见下「锚点获取流程」）  → 需求/设计一致性依据
+4. 编排实现层：按 gitlink-code-review/SKILL.md 跑实现层审查
+   → 取分级问题清单（Critical/Warning/Suggestion）作为风险输入
+5. 跨模块影响：对改动符号 git grep 找直接调用方 → 标破坏性变更
+6. 推理层：需求/设计一致性 + 业务安全/合规一致性（对照锚点）
+7. 综合裁决：实现层 + 影响 + 一致性 + 安全 交叉 → 风险评分 + 动作建议
+   ----- 以上为只读分析，默认到此为止 -----
+8. （确认后）pr +review --id <N> --status common --content "<综合报告>" [--dry-run]
+```
+
+## 锚点获取流程（需求一致性审查的依据）
+
+需求/设计一致性需要一个"锚点"（正确性的参照）。按下列**交互式决策树**获取：
+
+```
+Step A：询问使用者 —— 仓库中是否有与该 PR 相关的设计/需求文档？
+  ├─ 有 → 使用者提供文档路径（仓库内相对路径）→ 本地读取（git show <path> / 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 "<symbol>" -- '<glob>'` 找**直接调用方**（仅一层，不追传递依赖）。
+- 标注破坏性变更：签名改变/删除/重命名 → 受影响调用方清单 + 影响范围分级（核心模块/边缘/无）。
+
+### ③ 需求/设计一致性（推理，自研）
+- 以**锚点**判断：PR 是否真正实现了需求？设计是否与现有架构一致？有无过度设计/设计缺陷？
+- 锚点缺失时降级（见上），结论标注低置信度。
+
+### ④ 业务级安全/合规一致性（推理，自研）
+- 非通用红线（注入/硬编码密钥等属 code-review），而是**结合需求上下文**判断业务约束是否对齐（如：该改动是否绕过了应有的权限校验、是否合规留痕）。
+
+### ⑤ 综合裁决（合成）
+| 综合风险 | 触发条件（任一） | 动作建议 |
+|---|---|---|
+| 🔴 高 | 实现层有 Critical / 破坏性变更影响核心模块 / 需求未实现 | **阻断**合入 |
+| 🟡 中 | 实现层有 Warning / 影响边缘模块 / 设计有改进点 | **谨慎**：修改后再合 |
+| 🟢 低 | 实现层仅 Suggestion / 无跨模块破坏 / 与锚点一致 | **放行** |
+
+## 综合评审报告模板
+
+````markdown
+## 🔍 PR 深度审查 — #<N> <标题>
+
+**关联锚点**：<Issue #X / 设计文档 path / ⚠️ 无外部锚点（置信度低）>
+
+### 📎 实现层（编排 gitlink-code-review）
+- Critical: <n> | Warning: <n> | Suggestion: <n>（详见 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 <path> 读取
+
+# 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 是最可靠的需求源；设计文档次之；两者皆无才降级。
--- a/skills/gitlink-pr-deep-review/examples/pr-deep-review-workflow.md
+++ 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 <path>` 读取后与 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 不具备）。参赛验证基于本地源码编译产物。