---
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 是最可靠的需求源；设计文档次之；两者皆无才降级。
