10 KiB

Raw Blame History

name

version

description

metadata

gitlink-code-review

1.2.0

当用户需要对 GitLink 上的 Pull Request 做代码审查时触发：获取 PR 变更/Diff、按严重程度输出结构化 Review 意见、并（经确认后）把评审评论提交到 PR。适用于收到 PR Review 请求、需要批量审查 PR、为 PR 自动生成审查报告等场景。

requires

cliHelp

bins

gitlink-cli

gitlink-cli pr --help

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

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

核心原则

用 Shortcut，不用 Raw API：提交评审用 pr +review，行内评论用 pr +create-comment，普通评论用 pr +comment。不要用 GitHub 风格的 Raw API（event:"COMMENT" / position 等字段 GitLink 不支持）。
建议优先，确认后提交：先把结构化审查报告交给用户确认，禁止未经确认直接提交 Review/评论。尤其禁止用 --yes 绕过确认，除非用户明确说「直接提交/不用确认」。
严重程度分级驱动结论：有 Critical → 评审状态用 rejected（Request changes）；仅 Suggestion/Positive → common；无问题 → approved。
安全红线零容忍：硬编码密钥、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 上下文

# 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：出审查报告（建议，不写入）

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

## 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`	批准合并

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 正式提交：

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

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

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

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。

# 普通评论（挂在 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）
不安全的反序列化

代码审查最佳实践

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

命令速查

# 获取上下文
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）：

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

字段说明详见 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 范围。

10 KiB Raw Blame History Unescape Escape