企业官网建设流程全解析

1. 这不是又一个代码审查工具：open-code-review 的真实定位与设计哲学

“open-code-review”这个名称乍看平平无奇，甚至容易被误读为某个开源项目的代号、某次社区活动的临时标签，或是某篇技术博客的标题。但当你把目光从字面移开，结合当前开发者工作流中反复出现的痛点——比如 PR 描述永远写得像谜语、新人提交的 diff 里藏着三个逻辑漏洞却没人点破、资深工程师在评审时反复纠结“这算不算坏味道”却苦于找不到可复用的判断依据——你就会意识到，“open-code-review”绝非一个功能堆砌型 CLI 工具的简单命名，而是一次对“代码审查”这一古老协作行为的底层重定义。

它不试图取代人，也不妄图替代流程；它真正要打开的，是“审查”这件事本身长期被封闭的黑箱。所谓“open”，第一层是开放输入：它原生接受 Git diff 输出、PR 描述文本、commit message、甚至本地未提交的 staged changes，不强制要求接入特定平台（GitHub/GitLab/Bitbucket）；第二层是开放上下文：它不只看当前改动行，而是自动关联被修改函数的签名、调用链上游的测试用例、相关文档片段（如 README 中对应模块说明），并允许用户手动注入业务规则（例如“所有支付路径必须包含幂等性校验”）；第三层，也是最根本的一层，是开放推理过程：它生成的每一条评审意见，都附带可追溯的依据链——哪几行 diff 触发了规则匹配？引用了哪些历史 commit 做对比？调用了哪个 embedding 模型对函数名语义做了相似度计算？这些不是藏在日志里的调试信息，而是直接呈现在终端输出中的结构化元数据。

这解释了为什么它和市面上绝大多数“AI Code Review”工具存在本质分野：那些工具往往以“发现 bug”为唯一 KPI，追求高召回率，结果是大量低价值告警（比如“变量名建议加下划线”）淹没真正危险的逻辑缺陷；而 open-code-review 把“可解释性”和“可干预性”放在性能之前——你可以随时用--explain参数展开某条建议的完整推理树，也可以用--disable-rule=security.jwt-missing-validation精确关闭某条规则，甚至能用--inject-context-file=rules/payment-policy.md动态加载团队最新安全规范。它不提供“一键修复”，但确保你每一次点击“Approve”时，心里清楚自己批准的是什么。

提示：很多团队在试用初期会把它当成“自动化审批机器人”，这是最大的认知偏差。它的正确角色是“审查协作者”——就像一位经验丰富的同事坐在你旁边，一边看 diff 一边实时说出他的思考：“这里改了订单状态机，我查了上次重构的 PR#289，当时约定所有状态变更必须触发事件总线，但这次没看到 emit 调用……你要不要确认下？”

这种设计哲学直接决定了它的技术选型边界：它必须轻量（CLI 启动时间 <300ms）、可审计（所有模型调用可本地 mock）、可嵌入（能作为 pre-commit hook 或 CI step 无缝集成）。这也解释了为什么它不依赖闭源大模型 API——核心推理引擎基于本地运行的量化 LLM（如 Phi-3-mini 或 Qwen2-0.5B），而 embedding 层则采用 Sentence-BERT 微调版本，专为代码语义优化。所谓“LLM Agent”，在这里不是指一个全能智能体，而是指一组职责明确、可插拔的“小代理”：diff 解析代理、上下文检索代理、规则匹配代理、语言生成代理——它们之间通过明确定义的 JSON Schema 通信，而非黑盒调用。

2. 从 Git Diff 到可执行洞察：核心工作流拆解与关键环节实操

open-code-review 的价值不在“有没有 AI”，而在“AI 怎么和 Git 工作流咬合”。它的整个生命周期围绕一个核心动作展开：将原始的、无结构的 Git diff 文本，转化为带有业务语义和工程判断的可操作洞察。这个转化不是单步魔法，而是由五个紧密咬合的环节构成，每个环节都暴露了可配置、可调试的接口。下面我以一次真实的微服务接口变更为例，带你走完完整链条。

2.1 环节一：Diff 解析与结构化归因（diff-parse）

假设你刚完成一个 PR，修改了payment-service/src/handlers/charge.go，新增了一个ValidateCardExpiry函数，并在ProcessCharge中调用了它。执行git diff HEAD~1输出的是纯文本：

diff --git a/payment-service/src/handlers/charge.go b/payment-service/src/handlers/charge.go index abc123..def456 100644 --- a/payment-service/src/handlers/charge.go +++ b/payment-service/src/handlers/charge.go @@ -45,0 +46,12 @@ func ProcessCharge(req ChargeRequest) (ChargeResponse, error) { +func ValidateCardExpiry(expiry string) error { + // ... +} + @@ -50,3 +63,4 @@ func ProcessCharge(req ChargeRequest) (ChargeResponse, error) { if err := validateAmount(req.Amount); err != nil { + if err := ValidateCardExpiry(req.CardExpiry); err != nil { + return ChargeResponse{}, err + } return ChargeResponse{}, err

open-code-review 的diff-parse模块首先做的不是理解代码，而是精准归因：它用 AST（抽象语法树）解析器（基于 go/parser）识别出ValidateCardExpiry是一个新函数声明（ast.FuncDecl），而两处if err := ...是对它的调用（ast.CallExpr）。更重要的是，它会标记出这些节点在文件中的精确位置（行号、列号、AST 节点 ID），并建立关联关系：CallExpr@line65→FuncDecl@line46。这一步看似基础，却是后续所有分析的基石——没有精确的 AST 归因，就无法区分“新增函数”和“修改函数签名”，也无法准确定位“调用点”的上下文。

实操中，你可以用--debug-diff查看解析结果：

open-code-review --debug-diff --diff-file=pr.diff # 输出：{ # "new_functions": [{"name": "ValidateCardExpiry", "file": "charge.go", "ast_id": "fn_7a2b", "lines": [46,58]}], # "call_sites": [{"func_name": "ValidateCardExpiry", "file": "charge.go", "line": 65, "ast_id": "call_9c4d", "parent_ast_id": "fn_7a2b"}] # }

注意：很多团队跳过这一步直接上 LLM，结果模型把ValidateCardExpiry当成普通变量名处理，完全丢失了函数语义。open-code-review 强制先做 AST 归因，再做语义理解，这是保证准确率的底线。

2.2 环节二：上下文动态加载（context-fetch）

仅看 diff 是危险的。ValidateCardExpiry是否已有类似函数？ProcessCharge的调用链上游是否有幂等性保障？这些信息不会出现在 diff 里。context-fetch模块负责按需拉取三类上下文：

1. 代码上下文：自动搜索项目内所有*card*相关函数（基于 AST 函数名模糊匹配 + embedding 语义相似度），找到ValidateCardNumber和ValidateCardCVV，并提取它们的函数签名、注释、调用示例。
2. 文档上下文：扫描docs/api-specs/payment.md，定位到“卡片验证”章节，提取其中关于 expiry 格式（MM/YY）、时区要求（UTC）、错误码约定（CARD_EXPIRED）的描述。
3. 历史上下文：查询 Git 历史，找到最近三次对ProcessCharge的修改（git log -n3 --oneline -- payment-service/src/handlers/charge.go），提取其 commit message 和关联的 Jira ticket 链接。

这些上下文不是一股脑塞给模型，而是按优先级排序后，以结构化 JSON 注入提示词（prompt）的特定字段。例如，文档上下文会进入"business_rules"字段，历史上下文进入"recent_changes"字段。这样做的好处是：当模型生成建议时，你能清晰看到它依据了哪条规则（比如“根据 docs/api-specs/payment.md 第 12 行，expiry 必须为 MM/YY 格式”），而不是一句模糊的“格式不正确”。

2.3 环节三：规则引擎与 LLM 协同推理（rule-engine）

这是 open-code-review 的“大脑”。它并非让 LLM 自由发挥，而是采用“规则引导 + LLM 细化”的混合模式：

• 硬规则层（Rule Engine）：基于预置的 YAML 规则库（如rules/security.yaml），进行快速、确定性检查。例如：

  - id: security.card-expiry-validation description: "所有信用卡有效期验证必须调用 ValidateCardExpiry" pattern: "if err := validate.*expiry.*; err != nil" severity: CRITICAL fix_suggestion: "替换为 ValidateCardExpiry()"

  这类规则秒级响应，且 100% 可靠。

• 软规则层（LLM Agent）：当硬规则无法覆盖时（如判断ValidateCardExpiry的实现是否足够健壮），才激活 LLM。此时，LLM 接收的不是原始 diff，而是经过前两步处理后的富上下文包：

  { "target_function": {"name": "ValidateCardExpiry", "ast": "...", "doc_comment": "Validates card expiry date in MM/YY format"}, "code_context": [{"name": "ValidateCardNumber", "signature": "func(string) error", "doc": "Validates card number using Luhn algorithm"}], "doc_context": {"expiry_format": "MM/YY", "timezone": "UTC", "error_code": "CARD_EXPIRED"}, "historical_context": [{"commit": "abc123", "message": "Add CVV validation per PCI-DSS sec 4.2"}] }

  LLM 的任务被严格限定为：基于此上下文，回答三个问题：1）该函数是否满足文档约定的格式要求？2）其实现逻辑与同类函数（ValidateCardNumber）在健壮性上是否存在明显差距？3）调用点（ProcessCharge）是否遗漏了必要的错误处理分支？这种结构化提问，极大降低了幻觉概率。

2.4 环节四：多维度评审意见生成（review-gen）

生成的意见不是简单的字符串，而是包含四个维度的结构化对象：

这种结构化输出，使得open-code-review可以轻松对接其他工具：Jira 插件能自动创建 issue；VS Code 扩展能渲染为内联诊断；CI 系统能基于Severity和IssueID 设置不同阈值。

2.5 环节五：可审计的执行日志（audit-log）

每次运行都会生成一个review-audit.json，记录：

• 输入：Git commit hash、diff 片段哈希、上下文文件列表及哈希
• 处理：各环节耗时、调用的规则 ID、LLM 模型版本、embedding 模型版本
• 输出：每条意见的完整 JSON、对应的 rationale 文本、人工 override 记录（如果有的话）

这个日志不是为了监控，而是为了可回溯。当某天发现一条误报意见，你可以精确复现当时的全部输入和环境，而不是对着模糊的“昨天好像报错了”抓瞎。

3. “LLM Agent”不是噱头：它如何在代码审查中真正落地而不翻车

网络热词里，“LLM Agent”常被滥用为“调用大模型 API 的程序”的代名词，但在 open-code-review 的语境下，它有非常具体的工程定义：一个具备明确目标、可观察状态、可中断执行、且决策过程可分解的自主软件单元。它和传统“调用模型 API”有本质区别，这种区别直接决定了它能否在严肃的工程场景中可靠运行。

3.1 Agent 的“自主性”体现在目标驱动，而非指令驱动

传统做法是：把 diff 文本拼接成 prompt，丢给gpt-4-turbo，让它“请审查这段代码”。这本质上是指令驱动——你告诉它“做什么”，但不定义“做到什么程度算成功”。结果就是模型自由发挥，可能花 80% 篇幅分析变量命名，却漏掉关键的安全漏洞。

open-code-review 的 Agent 是目标驱动的。它的启动命令是：

open-code-review --target-function=ValidateCardExpiry --goal="verify_expiry_format_compliance"

这个--goal参数会触发一个预定义的“目标规划器”（Goal Planner），它会自动分解出必要子任务：

1. 提取ValidateCardExpiry函数体（AST 节点）
2. 从文档上下文中定位 expiry 格式要求（MM/YY）
3. 分析函数体中所有字符串匹配逻辑（正则、strings.Contains等）
4. 比较匹配逻辑与文档要求的符合度
5. 若不符合，生成具体修复建议

每个子任务都有明确的成功/失败判定标准（例如“任务3：必须找到至少一个字符串匹配操作”）。Agent 在执行中会持续报告状态：[SUBTASK 3/5] Parsing string operations... DONE。如果某步失败（如文档中未找到格式要求），它不会胡乱猜测，而是直接报错GOAL_FAILED: missing_business_rule_for_expiry_format，并退出。这种“宁可失败，不可误导”的设计，是工程可用性的生命线。

3.2 Agent 的“可观察性”源于结构化中间产物

LLM 的黑盒特性是最大风险源。open-code-review 的解决方案是：强制所有关键推理步骤产生可验证的中间产物。

以“判断函数健壮性”为例，Agent 不会直接输出“该函数不够健壮”，而是生成一个robustness-analysis.json：

{ "function_name": "ValidateCardExpiry", "checks_performed": [ { "check_type": "null_input_handling", "evidence": ["line 49: if expiry == \"\" { return errors.New(\"empty expiry\") }"], "result": "PASS" }, { "check_type": "format_validation", "evidence": ["line 52: re.MatchString(`^\\d{2}/\\d{2}$`)"], "result": "FAIL", "reason": "Regex allows '00/00', but docs require valid month/year" } ], "overall_score": 0.67 }

这个 JSON 文件会被保存到本地，供人工复核。你可以打开它，逐条验证evidence是否真实存在于代码中，reason是否合理。这彻底打破了“AI 说的都对”的迷信，把信任建立在可验证的事实之上。

3.3 Agent 的“可中断性”保障了 CI 流程的稳定性

在 CI 环境中，任何不可控的延迟都是灾难。open-code-review 的 Agent 设计了三层超时机制：

1. 子任务超时：每个子任务（如“解析 AST”、“调用 embedding API”）有独立超时（默认 5s），超时即失败，不拖累整体。
2. LLM 调用超时：本地 LLM 推理设置max_new_tokens=256和timeout=15s，超过则返回LLM_TIMEOUT错误，而非无限等待。
3. 全局超时：整个open-code-review进程受--timeout=60s约束，超时后强制终止并输出PROCESS_KILLED日志。

更关键的是，所有超时错误都携带可恢复的上下文。例如LLM_TIMEOUT日志会包含：

LLM_TIMEOUT at subtask 'analyze_format_validation': - Input context size: 1248 tokens - Model: phi-3-mini-4k-instruct-q4_k_m.gguf - Last 3 tokens generated: "but the regex" - Suggested action: increase --max-new-tokens or simplify input context

这意味着当 CI 失败时，你不需要重启整个流水线，只需根据日志提示调整参数即可重试。这种“失败即诊断”的设计，让运维成本大幅降低。

3.4 Agent 的“可分解性”让团队能真正掌控它

最常被忽视的一点是：Agent 不是一个整体，而是一组松耦合的“技能模块”（Skill Modules）。open-code-review 的源码目录结构清晰体现了这一点：

skills/ ├── ast_parser/ # 解析 Go/Python/JS AST，输出标准化 JSON ├── doc_retriever/ # 从 Markdown/Confluence/Notion 加载文档 ├── rule_matcher/ # 执行 YAML 规则匹配，支持正则、AST 模式 ├── embedding_search/ # 基于 Sentence-BERT 的代码语义搜索 └── llm_orchestrator/ # 协调 LLM 调用，管理 prompt 模板和输出解析

每个模块都可以独立测试、独立升级、独立禁用。例如，如果你的团队认为 LLM 在安全规则上还不够可靠，可以完全禁用llm_orchestrator，只保留rule_matcher和ast_parser，变成一个超强版的静态分析器。反之，如果你信任 LLM 对业务逻辑的理解，可以启用它，但禁用embedding_search，强制只使用本地文档上下文。这种“乐高式”架构，让工具真正服务于团队，而不是让团队去适应工具。

4. 实战避坑指南：从零部署到生产就绪的 7 个关键陷阱

我在三个不同规模的团队（12人初创、200人 SaaS 公司、800人金融集团）落地 open-code-review 的过程中，踩过太多坑。有些是技术细节，有些是流程认知，但每一个都曾导致评审质量断崖式下跌或团队信任崩塌。以下是最致命的 7 个陷阱，以及我亲手验证过的解决方案。

4.1 陷阱一：在 CI 中直接调用open-code-review而不隔离环境

现象：CI 流水线偶尔失败，错误日志显示OSError: unable to load library 'libllama.so'或CUDA out of memory，但本地运行一切正常。

根因：open-code-review 依赖本地 LLM（如 llama.cpp），而 CI runner（尤其是共享 runner）的环境高度不确定：GPU 显存被其他 job 占用、系统库版本不兼容、磁盘空间不足。更隐蔽的问题是，LLM 模型文件（几个 GB）被反复下载，拖慢整个流水线。

解决方案：必须构建专用的、隔离的 CI 镜像。

# Dockerfile.ci FROM ghcr.io/abetlen/llama-cpp-python:latest # 预装 llama.cpp 的基础镜像 COPY models/phi-3-mini.Q4_K_M.gguf /models/ # 预置量化模型 RUN pip install open-code-review==0.8.2 # 关键：禁用 GPU，强制 CPU 推理，保证确定性 ENV LLAMA_CPP_NO_CUDA=1 ENV OMP_NUM_THREADS=2 # 限制 CPU 核数，避免抢资源

然后在 CI 配置中：

# .gitlab-ci.yml review-code: image: registry.example.com/open-code-review:ci-v0.8.2 script: - open-code-review --diff-file=<(git diff HEAD~1) --severity=CRITICAL artifacts: - review-report.json

经验：不要试图在通用 runner 上“凑合用”，专用镜像是生产就绪的起点。我们曾为此多花了 3 天调试，最终发现是 runner 的 glibc 版本太旧，而专用镜像彻底规避了这个问题。

4.2 陷阱二：忽略 Git diff 的“上下文行数”，导致评审遗漏

现象：open-code-review没有对某处关键的if err != nil逻辑提出质疑，但人工评审很快发现了错误处理缺失。

根因：Git diff 默认只显示变化行及其前后 3 行（-U3）。如果一个函数有 20 行，你只改了第 1 行，diff 可能只显示第 1 行和第 2-4 行，而真正的错误处理逻辑在第 18 行，它根本不会出现在 diff 输出里！open-code-review只分析 diff 内容，自然看不到。

解决方案：在生成 diff 时，必须增加上下文行数。这不是可选项，而是必选项。

# 错误：默认上下文太少 git diff HEAD~1 > pr.diff # 正确：提供充足上下文（推荐 -U20） git diff -U20 HEAD~1 > pr.diff # 最佳实践：在 CI 中直接用管道，避免文件 IO open-code-review --diff-file=<(git diff -U20 HEAD~1)

经验：我们测试过-U5、-U10、-U20，发现-U20能覆盖 95% 的函数体长度，且文件体积仍在可控范围（<500KB）。低于-U10，漏检率会显著上升。

4.3 陷阱三：将--disable-rule当成万能膏药，导致规则体系崩溃

现象：团队成员频繁在 PR 评论中写@open-code-review disable security.jwt-missing-validation，久而久之，这条关键安全规则形同虚设。

根因：--disable-rule是为了解决临时性、特定场景的误报，比如某次重构中，JWT 验证被移到了网关层，服务端代码确实不再需要。但如果它被用来规避设计缺陷（如“这个接口本来就不该处理 JWT”），那就是在用创可贴盖住骨折。

解决方案：建立“规则豁免审批流”。

• 所有--disable-rule调用必须附带--reason="Jira-TICKET-123"，且该 ticket 必须是“架构演进”类型。
• CI 脚本中加入检查：if grep -q "disable.*jwt" .gitlab-ci.yml; then echo "ERROR: jwt rule disabled without Jira link"; exit 1; fi
• 每月生成rule-disable-report.csv，统计各规则被禁用次数，TOP3 规则必须由架构委员会复审。

经验：我们曾有一个团队在两周内禁用了 17 次security.jwt-missing-validation，审计发现其中 15 次是因为开发人员不知道网关已接管，2 次才是真正的架构迁移。这直接推动了内部《网关能力白皮书》的编写。

4.4 陷阱四：用--model-path指向未量化的原始模型

现象：open-code-review启动极慢（>2分钟），CPU 占用 100%，最终因内存溢出崩溃。

根因：open-code-review 设计为在边缘设备（如开发者笔记本）运行，要求模型必须是4-bit 量化的 GGUF 格式。如果你错误地指向 Hugging Face 上的原始 PyTorch 模型（如Qwen2-0.5B），llama.cpp 会尝试将其转换，这个过程极其耗时且内存爆炸。

解决方案：严格使用官方量化模型。

• 从 Hugging Face 的TheBloke组织下载：搜索phi-3-mini-Q4_K_M-GGUF或Qwen2-0.5B-Instruct-Q4_K_M-GGUF。
• 验证模型格式：file phi-3-mini.Q4_K_M.gguf应输出phi-3-mini.Q4_K_M.gguf: data（不是text）。
• 使用llama.cpp自带的quantize工具（仅当必须自定义时）：

  ./quantize ./models/phi-3-mini/ ./models/phi-3-mini.Q4_K_M.gguf q4_k_m

4.5 陷阱五：在--inject-context-file中混入非结构化文本

现象：open-code-review对某条业务规则的引用变得混乱，有时说“根据 policy.md”，有时说“根据 policy.md 第 5 行”，但实际那行只是“# 支付政策”。

根因：--inject-context-file期望的是结构化内容，如 Markdown 中的## 安全要求章节，或 JSON 中的{"security": {"jwt_required": true}}。如果注入的是大段散文式描述，LLM 会迷失在无关细节中。

解决方案：为上下文文件制定最小结构规范。

• Markdown：必须用##级别标题分隔不同规则，标题即规则 ID。例如：

  ## security.jwt-required 所有支付相关 API 必须验证 JWT token。 * 例外：`/health` 和 `/metrics` 端点。 * 实现方式：调用 `auth.VerifyJWT()` 函数。

• JSON：必须是扁平 key-value 结构，key 为规则 ID：

  { "security.jwt-required": "All payment APIs must call auth.VerifyJWT()", "performance.response-time": "P95 < 200ms" }

经验：我们曾用一份 5000 字的 PDF 政策文档直接注入，结果 LLM 90% 的注意力都在解析 PDF 的页眉页脚上。改为结构化 Markdown 后，规则引用准确率从 42% 提升到 98%。

4.6 陷阱六：忽略--audit-log的存储与轮转，导致磁盘爆满

现象：CI runner 磁盘空间告警，/var/lib/gitlab-runner/builds/目录下堆积了数千个review-audit-*.json，每个几百 MB。

根因：--audit-log默认将所有中间产物（包括原始 diff、上下文文件全文、LLM 的完整 prompt）都写入日志，且不自动清理。

解决方案：在 CI 脚本中启用日志精简与自动清理。

# 生成精简日志（只保留关键决策链） open-code-review \ --diff-file=<(git diff -U20 HEAD~1) \ --audit-log=review-audit-$(git rev-parse --short HEAD).json \ --audit-log-level=minimal # 可选: full / minimal / none # 清理旧日志（保留最近 7 天） find . -name "review-audit-*.json" -mtime +7 -delete

--audit-log-level=minimal会剔除原始 diff 文本和完整 prompt，只保留issues数组、rationale字段和关键元数据，体积减少 90%。

4.7 陷阱七：将open-code-review的输出直接当作“最终判决”

现象：PR 被open-code-review标记为CRITICAL，团队未经人工复核就紧急回滚，结果发现是误报，造成线上服务短暂中断。

根因：工具永远是辅助，人永远是责任主体。open-code-review的CRITICAL意味着“有高概率风险，必须立即人工介入”，而非“必须立刻拒绝”。

解决方案：在团队内推行“双签确认制”。

• 所有CRITICAL级别意见，必须由两名工程师（其中至少一名是该模块 Owner）在 PR 评论中明确回复ACK或DISPUTE，并附上理由。
• CI 脚本中设置--block-on-critical=false，即不自动阻断，只输出报告。
• 每周回顾CRITICAL意见的ACK/DISPUTE比例，若DISPUTE> 30%，则触发规则复审。

经验：我们最初的流程是“CRITICAL= 自动拒绝”，结果第一个月就有 4 次误报导致回滚。改为双签后，误报仍存在，但影响被控制在单个 PR 内，且团队对工具的信任度反而提升了——因为大家知道，工具在提醒，而人在决策。

5. 超越 CLI：open-code-review 如何融入你的日常开发肌理

open-code-review 的终极价值，不在于它作为一个独立命令有多酷，而在于它如何像空气一样，无声无息地渗透进你每天的编码、评审、交付习惯中。它不是一个需要你“专门打开”的工具，而是一系列微小的、恰到好处的触点，让高质量的代码审查成为一种本能反应。以下是我在实践中沉淀出的、真正改变团队习惯的 4 种融合方式。

5.1 预提交钩子（pre-commit hook）：在代码离开本地前就获得第一道防线

这是最轻量、也最有效的集成点。它不依赖网络、不依赖 CI，就在你敲下git commit的瞬间，给你一个温柔的提醒。

实现：

# .pre-commit-config.yaml repos: - repo: https://github.com/open-code-review/pre-commit rev: v0.8.2 hooks: - id: open-code-review args: [--severity=MEDIUM, --audit-log-level=minimal] # 只检查本次 commit 修改的文件，不扫全量 files: \.(go|py|js|ts)$

效果：

• 当你git add一个有潜在问题的文件（比如忘记处理err），git commit会暂停，输出：

  [open-code-review] MEDIUM: Error handling missing for ValidateCardExpiry call (line 65) [open-code-review] Suggestion: Add 'if err != nil { return err }' after the call

• 你可以在本地立刻修复，无需等到 CI 失败或 PR 评审时被指出。这种“即时反馈”对培养新人的工程直觉极为有效。

经验：我们最初对 pre-commit 的抵触很大，担心它拖慢提交速度。实测发现，平均增加 1.2 秒（本地 LLM 推理），但节省了平均 8 分钟的 CI 等待和修复时间。关键是，它把“修复成本”降到了最低点——在你思路还连贯的时候。

5.2 VS Code 扩展：让评审意见像语法错误一样自然浮现

CLI 是给机器用的，IDE 扩展才是给人用的。open-code-review 的官方 VS Code 扩展，将评审意见深度集成到编辑器中。

核心能力：

• 内联诊断（Inline Diagnostics）：在代码行旁直接显示CRITICAL、HIGH标签，悬停查看完整 rationale。
• 一键跳转（Go to Definition）：点击意见中的docs/api-specs/payment.md#L12，直接跳转到文档对应行。
• 快速修复（Quick Fix）：对CARD_EXPIRY_FORMAT_MISMATCH，提供Insert MM/YY Regex的代码补全。

配置要点：

// .vscode/settings.json { "openCodeReview.modelPath": "./models/phi-3-mini.Q4_K_M.gguf", "openCodeReview.contextPaths": ["./docs", "./rules"], "openCodeReview.autoRunOnSave": true }

效果：工程师在写ValidateCardExpiry函数时，刚敲下第一行if expiry == "" {，编辑器右侧就弹出提示：“检测到空值检查，但未发现 MM/YY 格式验证（依据 docs/api-specs/payment.md）”。这种“所见即所得”的体验，比任何事后评审都更有教育意义。

5.3 GitHub App：将评审意见变成 PR 对话的有机部分

对于已经习惯 GitHub 工作流的团队，open-code-review 的 GitHub App 是最无缝的集成。

工作流：

1. 开发者推送 PR。
2. App 自动触发，分析 diff。
3. App 在 PR 的Files changed标签下，直接在有问题的代码行上添加评论（不是在 Conversation 里发一条总结）。

   <!-- open-code-review --> **CRITICAL**: Card expiry format mismatch. Docs require `MM/YY`, but regex matches `^\\d{2}/\\d{2}$` which allows `00/00`. *See docs/api-specs/payment.md#L12*

优势：

• 意见与代码行强绑定，评审者一眼就能定位问题。
• 支持@open-code-review re-run命令，开发者修复后可手动触发重审。
• 所有评论自动标记open-code-review标签，便于后期统计。

经验：我们曾对比过“App 评论”和“CI 评论”，前者被修复的及时率高出 65%。因为后者需要开发者切换