---
name: gitlink-code-review
version: 1.2.0
description: "当用户需要对 GitLink 上的 Pull Request 做代码审查时触发：获取 PR 变更/Diff、按严重程度输出结构化 Review 意见、并（经确认后）把评审评论提交到 PR。适用于收到 PR Review 请求、需要批量审查 PR、为 PR 自动生成审查报告等场景。"
metadata:
  requires:
    bins: ["gitlink-cli"]
  cliHelp: "gitlink-cli pr --help"
---

# gitlink-code-review（智能代码审查）

**CRITICAL — 开始前必须先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md)，其中包含认证、权限处理和 API 注意事项。**
**CRITICAL — 所有写入/删除操作前，务必先确认用户意图；提交 Review 会通知 PR 相关人，必须先出报告→用户确认→dry-run→再提交。**
**CRITICAL — GitLink 操作只能用 `gitlink-cli`。禁止用 `gh`（GitHub CLI）操作 GitLink 资源。`gh` 仅适用于 GitHub 平台。**

## 核心原则

1. **用 Shortcut，不用 Raw API**：提交评审用 `pr +review`，行内评论用 `pr +create-comment`，普通评论用 `pr +comment`。不要用 GitHub 风格的 Raw API（`event:"COMMENT"` / `position` 等字段 GitLink 不支持）。
2. **建议优先，确认后提交**：先把结构化审查报告交给用户确认，**禁止未经确认直接提交 Review/评论**。尤其禁止用 `--yes` 绕过确认，除非用户明确说「直接提交/不用确认」。
3. **严重程度分级驱动结论**：有 Critical → 评审状态用 `rejected`（Request changes）；仅 Suggestion/Positive → `common`；无问题 → `approved`。
4. **安全红线零容忍**：硬编码密钥、SQL/命令注入、XSS、路径遍历、不安全反序列化必须标 Critical。

## 工作流概览

| 阶段 | 操作 | 命令 |
|------|------|------|
| ① 获取上下文 | PR 详情 / 变更文件 / Diff | `pr +view` / `pr +files` / `pr +diff` |
| ② 逐文件分析 | 按语言检查项审查 | （AI 分析） |
| ③ 出审查报告 | 按严重程度分级，**等用户确认** | （无写入） |
| ④ dry-run 预览 | 用户确认后，预览评审 | `pr +review --dry-run` |
| ⑤ 提交评审 | 用户再次确认后提交 | `pr +review`（去 `--dry-run`） |
| ⑥ 行内评论（可选） | 针对具体行追加 | `pr +create-comment --path --line` |

---

## 详细工作流

### Step 1：获取 PR 上下文

```bash
# PR 详情
gitlink-cli pr +view --id <pr_id> --format json

# 变更文件列表（含增删行数、是否新建）
gitlink-cli pr +files --id <pr_id> --format json

# Diff 内容（先取补丁集版本，再看版本差异；pr +diff 已移除）
gitlink-cli pr +versions --id <pr_id> --format json          # 拿 version_id
gitlink-cli pr +version-diff --id <pr_id> --version-id <vid> --format json   # 逐行 diff
```

> `--id` 是 PR 编号（web URL 中的编号）。Diff 在 `files[].sections[].lines[]`，`type`：2=新增、3=删除、4=hunk 头（`@@ ...`）；按文件分组逐文件分析，大型 PR 分段处理。
>
> ⚠️ **实测（2026-06-21）**：`pr +diff` 已被移除（与 `file` 冗余），由 `pr +version-diff` 替代。`--file <path>` 过滤不稳定，建议整份取 diff 后客户端按文件名筛。需要读某文件全文时用 `file +get --ref <head分支> --path <文件>`。

### Step 2：逐文件分析

对每个变更文件，按语言执行针对性检查：

**Python**：未用/循环 import；PEP8 偏离与过长行；硬编码密钥、SQL 注入、`eval()`/`exec()`；裸 `except`、吞异常；N+1 查询。
**JS/TS**：`innerHTML` 直赋、`eval()`；`any` 滥用；未处理 Promise；废弃 API。
**Go**：未检查的 error return、panic 滥用；goroutine 泄漏、缺 sync；未关闭 file/conn；导出标识符缺注释。
**通用**：硬编码配置/密钥/URL；边界条件缺失；圈复杂度过高；魔法数字；DRY 违反；注释过时；测试覆盖不足。

### Step 3：出审查报告（建议，不写入）

按严重程度分级输出，**此阶段不执行任何写入**：

```markdown
## PR #<id> 代码审查报告

### 🔴 Critical（必须修改）
- <问题> — <文件>:<行号>
  > <修改建议>

### 🟡 Warning（建议修改） / 🔵 Suggestion（可选优化） / ✅ Positive（值得肯定）
- ...

### 总体结论
<评审状态建议：rejected / common / approved；是否阻塞合并>
```

**等待用户确认**：用户没说「确认/提交」前停在 Step 3。**禁止用 `--yes` 自行推进。**

### Step 4：dry-run 预览（用户确认报告后）

根据报告的严重程度选择评审状态，dry-run 预览（不实际提交）：

| 报告含 Critical | 评审状态 | 含义 |
|-----------------|----------|------|
| 是 | `rejected` | Request changes，阻塞合并 |
| 否，仅 Warning/Suggestion | `common` | 普通评审评论 |
| 无问题 | `approved` | 批准合并 |

```bash
gitlink-cli pr +review --id <pr_id> \
  --status <common|approved|rejected> \
  --content "<把审查报告 Markdown 作为 content>" \
  --dry-run --format json
```

> `--content` 放整体审查报告（Markdown）。`--commit <sha>` 可选，把评审挂到具体 commit。核对 dry-run 输出无误。

### Step 5：提交评审（用户确认 dry-run 后）

去掉 `--dry-run` 正式提交：

```bash
gitlink-cli pr +review --id <pr_id> \
  --status <common|approved|rejected> \
  --content "<审查报告>" \
  --format json
```

### Step 6：行内评论（可选，针对具体行）

需要把某条意见精准挂在某一行时，用 `pr +create-comment`：

```bash
gitlink-cli pr +create-comment --id <pr_id> \
  --path <文件路径> --line <行号> \
  --body "<针对该行的意见>" --format json
```

> ⚠️ `--line` 是**文件中的行号**。Diff 输出给的可能是补丁内位置，需换算为文件真实行号（注意文件头部 import/license 偏移）。**若行号不确定，不要盲目发**——把该意见并入 Step 5 的 `--content` 总报告，或改用 `pr +comment`（普通评论，不挂行）。
>
> ⚠️ **实测（2026-06-21）**：`pr +create-comment --line` 会返回 `ok:true`，但返回的 `line_code` 为 `null`，**评论未真正锚定到该行**（仅挂在文件级）。因此优先用 `pr +review --content` 提交总报告；行内评论不可靠时改用 `pr +comment`。

```bash
# 普通评论（挂在 PR 下，不绑定行；行号不确定时的安全 fallback）
gitlink-cli pr +comment --id <pr_id> --body "<评论>" --format json
```

---

## 评审状态与严重程度的映射

| 报告内容 | `--status` | 合并建议 |
|---------|-----------|---------|
| 含任何 Critical | `rejected` | 阻塞，修复后复审 |
| 仅 Warning/Suggestion | `common` | 可合并，建议跟进 |
| 全部 Positive / 无问题 | `approved` | 可合并 |

## 安全红线（必须标 Critical）

- 硬编码的密钥 / Token / 密码 / 数据库连接串
- SQL / NoSQL 注入（用户输入直接拼接进查询）
- 命令注入（shell 命令拼接用户输入）
- 路径遍历（用户输入直接用于文件路径）
- XSS（未转义的用户输入直接渲染，如 `innerHTML`）
- 不安全的反序列化

## 代码审查最佳实践

1. **先大局后细节**：先理解 PR 目的与整体变更范围，再逐文件审查。
2. **关注行为而非风格**：风格问题交给 linter/formatter。
3. **提供可操作的建议**：不只指出问题，给出具体修改方案。
4. **肯定好的代码**：清晰命名、完善测试、良好设计给予正面反馈。
5. **控制评论量**：最严重的 3–5 个问题比 20 个小问题更有价值。

## 命令速查

```bash
# 获取上下文
gitlink-cli pr +view  --id <pr_id> --format json
gitlink-cli pr +files --id <pr_id> --format json
gitlink-cli pr +versions     --id <pr_id> --format json                          # 拿 version_id
gitlink-cli pr +version-diff --id <pr_id> --version-id <vid> --format json       # 逐行 diff（替代已移除的 pr +diff）

# 提交评审（首选）
gitlink-cli pr +review --id <pr_id> --status <common|approved|rejected> --content "<报告>" [--commit <sha>] [--dry-run]

# 行内评论（绑定文件+行；行号不确定时勿用）
gitlink-cli pr +create-comment --id <pr_id> --path <path> --line <n> --body "<意见>"

# 普通评论（不绑行；安全 fallback）
gitlink-cli pr +comment --id <pr_id> --body "<评论>"

# 查看已有评审（复审时用）
gitlink-cli pr +reviews --id <pr_id> --format json
```

## Raw API 参考

评审相关操作**优先用上述 Shortcut**。Shortcut 未覆盖时才用 Raw API，且字段需符合 GitLink（**不是** GitHub 的 `event:"COMMENT"`/`position`）：

```bash
# 列出已有评审
gitlink-cli api GET /:owner/:repo/pulls/:id/reviews --format json
```

> 字段说明详见 [`REFERENCE.md`](REFERENCE.md)。

## 红线与常见错误

- ❌ **用 GitHub 风格 Raw API 提交评审**（`event:"COMMENT"`、`position`、`commit_id`+`path`）——GitLink 用 `pr +review --status` 与 `pr +create-comment --path --line`。
- ❌ **未经用户确认就提交 Review/评论**——必须 报告→确认→dry-run→提交。
- ❌ **用 `--yes` 绕过确认门**——除非用户明确要求「直接提交」。
- ❌ **行号不确定却发 `+create-comment --line`**——会挂错行或被拒；改并入总报告或用 `+comment`。
- ❌ **有 Critical 却用 `--status common/approved`**——Critical 必须配 `rejected`。
- ❌ **用 `gh` 操作 GitLink**——只用 `gitlink-cli`。
- 所有命令加 `--format json` 便于解析；输出为 `{ok, data, meta}` envelope。

## 注意事项

- Review/评论提交后会通知 PR 所有相关人，内容请专业、可操作。
- 大型 PR 的 diff 可能非常大，按文件分段处理，避免一次性塞满上下文。
- `pr +diff` / `+files` 接口有频率限制，避免短时间内重复请求。
- 对 draft PR，提示用户先标记为 Ready for Review 再审查。
- 审查范围限于 PR 本身（代码审查）；仓库整体健康度、Issue 分拣等场景见各自专用 Skill，不在本 Skill 范围。
