企业官网建设流程全解析

1. 什么是 open-code-review：一个被严重低估的工程实践新范式

“open-code-review”这个词最近在开发者社区里频繁冒头，但它不是某个具体工具的名字，也不是某家公司的私有产品，而是一种正在快速成型的、以开源精神重构代码评审流程的新范式。它背后的核心逻辑非常朴素：把原本封闭在IDE插件、内部平台或PR界面里的代码审查动作，彻底“解耦”出来，变成可编程、可组合、可审计、可复用的标准化能力单元。你可能已经用过 GitHub Copilot 的 inline suggestion，也试过 VS Code 里集成的 AI assistant，但那些都是“附着在编辑器上的智能装饰”，而 open-code-review 要做的，是让代码审查这件事本身——从 diff 解析、上下文提取、规则匹配、建议生成到反馈输出——全部暴露为清晰接口，任你调度。

我第一次意识到这个范式的价值，是在给一个金融类 SDK 做合规加固时。团队要求所有涉及资金计算的函数必须通过三重校验：类型安全检查、浮点精度告警、边界条件覆盖提示。过去我们靠人工 checklist + SonarQube 规则扫描，漏检率高达 37%。后来我把整个评审逻辑拆成三段：第一段用 git diff 提取变更行，第二段用 LLM Agent 加载 SDK 的 type stub 和业务规范文档做 embedding 检索，第三段把检索结果喂给轻量级推理模型（不是 full-size LLM）做结构化判断。整个链路跑通后，不仅漏检归零，更重要的是——每次 PR 提交后，系统自动生成的 review comment 里，每一条都带可追溯的依据来源（比如“第 42 行未处理 decimal.RoundDown 场景，依据《资金计算白皮书》v3.2 第 5.1.3 条”）。这才是 open-code-review 的本质：它不追求“代替人写代码”，而是把人的工程判断力，固化成可验证、可演进、可共享的审查契约。

它和传统 code review 的区别，不在于“有没有 AI”，而在于“谁拥有评审主权”。传统模式下，评审权牢牢掌握在 reviewer 手中；而在 open-code-review 架构下，评审权被拆解为：策略定义权（由架构师/合规官持有）、上下文供给权（由 infra 团队维护）、执行调度权（由 CI/CD 流水线控制）、结果解释权（由开发者自主解读）。这种分权设计，天然适配现代研发组织的多角色协同场景——法务要加 GDPR 合规检查项，安全团队要注入 CWE-78 注入检测规则，前端组想统一 enforce React.memo 使用规范，都不再需要提 Jira 工单等排期，而是直接提交一个 YAML 配置文件，几秒内就生效。关键词 “open-code-review” 真正指向的，是这套可插拔、可审计、可治理的评审基础设施，而不是某款 CLI 工具的名称。

2. 核心设计思路：为什么必须绕开“大模型全家桶”，坚持 CLI + Git Diff 原生路径

很多人看到 “LLM Agent” 就本能地想堆模型、上 GPU、搞 RAG pipeline，这是对 open-code-review 最典型的误读。我带过的三个落地项目里，有两个最初都走了“全模型驱动”路线，结果无一例外卡死在三个地方：响应延迟不可控（平均 8.2 秒/次 review）、上下文长度爆炸（单个 PR 平均触发 17 次 token 截断重试）、结果不可复现（同一份 diff，三次请求返回建议差异率达 41%）。后来我们彻底推倒重来，把整个架构压回到最原始的 Unix 哲学：每个程序只做一件事，并把它做好。

核心设计锚点就两个：git diffs 是唯一可信输入源，CLI 是唯一可控执行入口。为什么？因为 git diff 是版本控制系统天然生成的、结构化的、语义明确的变更描述——它不含幻觉，不依赖 prompt 工程，不产生 token 开销。一行git diff --no-index old.js new.js输出的，是经过 SHA256 校验的、可精确映射到 AST 节点的文本快照。而 CLI 则提供了最干净的进程隔离、最透明的参数传递、最稳定的错误码体系。当你运行open-code-review --rule=security --context=finance ./src/payment/时，背后发生的是：先调用 libgit2 解析 diff，提取出所有修改的函数签名；再加载 finance-context.json（含业务术语 glossary 和监管条款 mapping）；最后启动一个预编译的 WASM 模块（非 Python/JS 运行时），执行硬编码的安全规则引擎。整个过程耗时稳定在 120ms 内，错误码严格遵循 POSIX 标准（比如 rule-violation=128, context-missing=129），CI 流水线能精准捕获并分类失败原因。

这种设计带来的连锁优势极其实在。首先是调试成本断崖下降：当某条 review comment 出错时，你不需要翻 LLM 日志、查 embedding 向量相似度、比对 prompt 版本，只需要open-code-review --debug --trace ./src/payment/，就能看到完整的 diff 解析树、上下文匹配路径、规则命中链路。其次是部署极简：整个二进制只有 4.2MB，静态链接，无 Python 环境依赖，Docker 镜像 base image 可用 alpine:latest，CI runner 上curl -L https://releases.example.com/open-code-review-v1.3 | sh一行安装完即用。最重要的是——它天然兼容所有现有工作流。你不用说服团队换掉 GitHub，不必改造 Jenkins 插件，甚至不需要动一行 CI 脚本：只要在script:下加一行open-code-review --fail-on=high-risk .，就能让高危变更自动阻断合并。这正是 open-code-review 区别于其他“AI 编程助手”的根本：它不试图成为开发者的“新 IDE”，而是成为现有工程体系的“隐形加固层”。

2.1 为什么拒绝“Agent”黑盒封装，坚持显式流程编排

当前很多所谓 “LLM Agent for Code Review” 方案，本质上是把 prompt chaining、tool calling、memory management 这套抽象层，强行套在代码评审场景上。问题在于，代码评审不是客服对话，它需要确定性、可审计性和可干预性。举个真实案例：某团队引入某 Agent 框架后，发现它对空指针解引用的检测，会因 prompt 中“请用友好语气指出问题”这个修饰语，导致严重漏报——模型把obj.method()解析为“调用方法”，却忽略obj可能为 null 的前置条件。而人工 review 时，这条规则是写死在 checkstyle.xml 里的<module name="NullPointer">，毫秒级响应，零歧义。

我们选择完全绕开 Agent 抽象层，用 shell script + jq + custom binary 组装评审流水线。典型流程如下：

# step 1: 提取变更范围（精确到函数级） git diff HEAD~1 --name-only | grep '\.js$' | xargs -I{} sh -c ' echo "=== reviewing {} ===" # step 2: 获取该文件的 AST 变更摘要（用 esbuild --tree-shaking=false 生成） esbuild --bundle --format=esm {} --outfile=/tmp/ast.json 2>/dev/null # step 3: 调用 open-code-review 核心引擎 open-code-review \ --input=/tmp/ast.json \ --ruleset=finance-rules.yaml \ --context=gdpr-context.json \ --output-format=github-pr-comment '

这个流程里，每个环节都是可替换、可监控、可打点的。你可以把esbuild换成swc，把finance-rules.yaml换成pci-dss-rules.yaml，甚至把最后的--output-format切成sonarqube-json直接对接质量门禁。没有“Agent runtime”这个中间态，就没有不可知的调度延迟、没有隐式的 memory 清理、没有无法 trace 的 tool call 失败。所有决策路径都暴露在 bash 脚本里，运维同学看一眼就知道瓶颈在哪——是 AST 解析慢？还是规则匹配耗 CPU？还是上下文加载 IO 高？这种透明度，是任何黑盒 Agent 都无法提供的工程确定性。

2.2 LLM 在这里扮演什么角色？不是裁判，而是“上下文翻译器”

必须澄清一个关键认知：在 open-code-review 架构中，LLM 从不参与“是否违规”的判决，它的唯一职责是“把人类写的规则，翻译成机器可执行的 pattern”。比如业务方提交一条新规则：“禁止在支付回调中使用 setTimeout”。人工写的规则可能是模糊的：“避免异步延迟处理关键路径”。这时 LLM 的作用，就是接收这条自然语言描述，结合项目代码库的 AST 样本，生成精确的 codemod 模式：

# finance-rules.yaml - id: no-settimeout-in-callback description: "Payment callback must not use setTimeout" pattern: | (CallExpression (MemberExpression (Identifier) (Identifier "setTimeout"))) context: ["paymentCallback", "webhookHandler"]

这个过程我们称为 “rule grounding”，它只发生一次（规则入库时），而非每次 review 实时调用。实际评审时，引擎直接运行这个 pattern matcher，速度比 LLM 推理快 300 倍以上。我们实测过：用 Llama3-8B 做 rule grounding，平均耗时 2.3 秒/条；而用生成的 pattern matcher 执行 review，平均 8ms/次。更重要的是，pattern matcher 的结果 100% 可复现、可单元测试、可 diff 对比——你随时可以git diff rules/查看规则演进，而 LLM 的输出永远是个黑箱。

所以，当热搜词里出现 “agent 和 llm 和 ai模型 有什么区别” 时，我的回答很直白：在这个范式里，AI 模型是规则编译器，LLM 是高级 prompt engineer，Agent 是过时的调度框架。DeepSeek、Qwen、CodeLlama 这些模型，只在 rule grounding 阶段作为 offline compiler 使用；它们不属于 runtime，不接触生产代码，不参与实时决策。这种“离线编译 + 在线执行”的分离设计，既满足了合规审计要求（模型不碰生产数据），又保障了性能底线（review 不拖慢 CI），还解决了模型漂移风险（规则一旦编译完成，结果永不变化）。

3. 核心实现细节：从 git diff 解析到可审计 review comment 的完整链路

open-code-review 的真正技术门槛，不在模型多大，而在于如何把 git diff 这个看似简单的文本，还原成具有语义深度的变更图谱。很多人以为git diff就是几行 +/- 文本，但实际上，现代 diff 工具（如 git with-U0）输出的是包含行号偏移、函数上下文、hunk 边界、二进制标识的结构化数据。我们的解析引擎第一步，就是把这个文本流，重建为 AST-aware 的变更节点树。

3.1 git diff 深度解析：超越行号，抵达 AST 节点级定位

标准git diff输出示例：

diff --git a/src/payment/processor.js b/src/payment/processor.js index abc123..def456 100644 --- a/src/payment/processor.js +++ b/src/payment/processor.js @@ -42,6 +42,7 @@ class PaymentProcessor { async process(payment) { const fee = this.calculateFee(payment); + await this.logTransaction(payment.id); return this.execute(payment); }

传统做法是提取+42,6这样的行号范围，然后粗暴地认为“第 43 行新增了代码”。但这在 JS/TS 里极其危险——因为await this.logTransaction(payment.id);这行代码，其语义影响可能辐射到整个process函数体（比如改变 Promise chain 的错误传播路径）。我们的解析器会做三件事：

1. Hunk 语义绑定：识别@@ -42,6 +42,7 @@中的class PaymentProcessor {是函数签名起始，将此 hunk 绑定到PaymentProcessor.process这个 AST 节点，而非单纯行号。
2. AST 节点映射：用 swc 解析a/src/payment/processor.js和b/src/payment/processor.js，构建两棵 AST，然后 diff 它们的节点 ID 映射表。确认新增行实际对应CallExpression节点，且父节点是BlockStatement（函数体）。
3. 上下文快照捕获：提取该节点周围的 3 层 AST 上下文（包括父函数参数列表、所在 class 的成员变量声明、import 语句），序列化为 JSON 快照，作为后续规则匹配的 context payload。

这个过程耗时约 150ms（实测 MacBook Pro M2），但换来的是 100% 精确的语义定位。比如当规则要求“支付处理器不得调用外部日志服务”，传统行号匹配会漏掉this.logger.info()这种间接调用；而我们的 AST 绑定能准确识别this.logTransaction是PaymentProcessor类的方法，进而追溯其内部是否调用了externalLogger.send()。

提示：不要用正则解析 diff！我们踩过的最大坑，就是早期用^(\+|-)(\d+),(\d+)提取行号，结果遇到 multi-line string literal 或 template literal 时，行号偏移完全错乱。必须依赖 libgit2 或 pygit2 的原生 diff parser，它们能正确处理\ No newline at end of file、binary diff、submodule diff 等所有边缘 case。

3.2 规则引擎设计：YAML 驱动的 pattern matching，而非 LLM 实时推理

规则定义采用极简 YAML 格式，核心字段只有四个：

关键创新在于pattern字段的设计。我们没采用通用的 XPath 或 CSS selector，而是定制了一套轻量级 AST query language，专为代码评审优化。它支持：

• 节点关系限定：parent: FunctionDeclaration确保只匹配函数体内调用
• 属性值匹配：arguments.0.type == "Literal"检查第一个参数是否为字面量
• 上下文过滤：context: ["paymentCallback"]仅在标记为 paymentCallback 的函数中激活

规则引擎执行时，会将 diff 解析得到的 AST 节点树，与所有已加载规则的pattern进行批量匹配。匹配算法基于位图索引优化，1000 条规则下平均匹配耗时 < 5ms。所有匹配结果都会附带match_trace字段，记录具体命中的节点路径、上下文快照哈希、规则版本号，确保每条 review comment 都可 100% 追溯。

注意：规则 YAML 必须经过 schema validation 和 static analysis。我们内置了一个open-code-review validate-rules子命令，能检测出无效 pattern（如未闭合括号）、冲突 severity（同一 AST 节点被多个 error 规则命中）、循环 context 引用等。上线前强制校验，杜绝“规则 bug 导致误报”这种低级事故。

3.3 可审计输出：GitHub PR Comment 的结构化生成逻辑

最终输出不是一堆杂乱的 console log，而是严格符合 GitHub API v3 格式的 structured comment。关键设计点有三个：

1. 位置精准锚定：每条评论的path、line、side字段，必须与 git diff 的 hunk 信息严格对齐。我们不依赖 GitHub 的 line-based diff rendering，而是用git show commit:file.js | head -n $line | tail -n 1精确获取目标行内容，再与 AST 节点做字符级比对，确保line字段指向真正的变更起始位置。

2. 多维度元数据注入：每条评论 body 不只是 message，还包含：

   { "rule_id": "no-async-log-in-payment", "rule_version": "1.2.0", "matched_ast_node": "CallExpression@42:5", "context_hash": "sha256:abc123...", "audit_id": "ocrr-20240521-7f8a" }

   这些字段让法务/安全团队能一键跳转到规则仓库、查看历史版本、核验上下文完整性。

3. 批处理与去重：同一个 AST 节点可能被多条规则命中（比如logTransaction既违反 async 约束，又违反 GDPR 数据泄露约束），引擎会自动聚合为一条 comment，用 bullet list 展示所有违规点，并按 severity 排序。避免 PR 页面被重复 comment 刷屏。

实测效果：一个中等规模 PR（23 个文件，147 行变更），平均生成 8.3 条 review comment，99.7% 的位置锚定准确率（对比人工 review 结果），0 条因格式错误被 GitHub API 拒绝。

4. 实操部署指南：从零搭建企业级 open-code-review 流水线

部署 open-code-review 不是安装一个 CLI 就完事，而是一整套工程实践的落地。我们以某 fintech 公司的真实部署为例，完整走一遍从环境准备到生产灰度的全流程。

4.1 环境准备：最小可行依赖与安全基线

基础环境要求极低，但安全配置必须严格：

• OS 支持：Linux x86_64 / ARM64（glibc ≥ 2.28），macOS 12+，Windows Subsystem for Linux 2（WSL2）
• Git 版本：≥ 2.30（需支持--no-pager和--diff-algorithm=minimal）
• 内存限制：单次 review 进程内存上限 256MB（防止恶意超大 diff OOM）
• 网络策略：默认禁用所有外网访问，规则 context 文件必须本地挂载或通过 air-gapped 方式同步

安装命令（推荐 curl + sha256 校验）：

# 下载二进制 curl -L https://releases.example.com/open-code-review-v1.3-linux-x64 -o ocr # 校验签名（公钥已预置在 CI runner 镜像中） echo "sha256:7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b ocr" | sha256sum -c # 设置执行权限并全局可用 chmod +x ocr && sudo mv ocr /usr/local/bin/open-code-review

实操心得：绝对不要用pip install或npm install方式部署。我们曾因某次 pip 升级意外拉取了带后门的 colorama 包，导致 review comment 被注入恶意链接。静态二进制 + sha256 校验是唯一可信路径。

4.2 规则仓库建设：用 Git 管理你的工程宪法

规则不是散落在 config 文件里的字符串，而是一个独立 Git 仓库（如internal/rules），结构如下：

rules/ ├── finance/ # 金融领域规则集 │ ├── gdpr.yaml # GDPR 合规检查 │ ├── pci-dss.yaml # 支付卡行业标准 │ └── internal-audit.yaml # 内部审计要求 ├── security/ # 安全规则集 │ ├── cwe-78.yaml # 命令注入 │ └── secrets.yaml # 密钥泄露检测 └── ci/ # CI 流水线规则 └── build-timeout.yaml

关键实践：

• 分支策略：main分支只接受 signed commit，staging分支用于预发布验证
• 版本控制：每条规则 YAML 文件顶部必须声明version: 1.2.0，且遵循 SemVer
• 自动化测试：每个规则目录下放test/子目录，包含valid.js（应通过）和invalid.js（应触发）样例，CI 自动运行open-code-review --test ./rules/finance/

这样做的好处是：当法务部要求新增“禁止存储用户身份证明原文”规则时，他们只需提交一个 PR 到rules/finance/，经安全团队 CODEOWNERS 批准后，自动同步到所有 CI runner。整个过程无需 DevOps 介入，规则生命周期完全自治。

4.3 CI 集成：Jenkins/GitHub Actions 双模版配置

GitHub Actions 模版（推荐用于开源项目）

name: Open Code Review on: pull_request: branches: [main, develop] types: [opened, synchronize, reopened] jobs: review: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 with: fetch-depth: 0 # 必须获取完整 git history 用于 diff 解析 - name: Install open-code-review run: | curl -L https://releases.example.com/open-code-review-v1.3-linux-x64 | sudo sh -c 'cat > /usr/local/bin/open-code-review && chmod +x /usr/local/bin/open-code-review' - name: Run code review id: ocr run: | # 加载规则集（从 private repo 挂载，需配置 GITHUB_TOKEN） git clone https://x-access-token:${{ secrets.GITHUB_TOKEN }}@github.com/internal/rules.git /tmp/rules # 执行评审，失败时自动 post comment open-code-review \ --rules=/tmp/rules/finance/ \ --context=/tmp/rules/context/finance.json \ --output-format=github-pr-comment \ --fail-on=error \ . || true # 允许失败，由下一步处理 - name: Post review comments if: always() uses: actions/github-script@v7 with: script: | const comments = require('./ocr-output.json'); // 实际需生成此文件 for (const c of comments) { github.rest.pullRequests.createReviewComment({ owner: context.repo.owner, repo: context.repo.repo, pull_number: context.payload.pull_request.number, body: c.body, path: c.path, line: c.line, side: c.side }); }

Jenkins Pipeline 模版（推荐用于企业内网）

pipeline { agent { label 'linux' } stages { stage('Open Code Review') { steps { script { // 从 Nexus 私服下载规则包 sh "curl -u ${NEXUS_USER}:${NEXUS_PASS} -o /tmp/rules.tgz https://nexus.internal/repository/rules/finance-v1.3.tgz" sh "tar -xf /tmp/rules.tgz -C /tmp/rules" // 执行评审，捕获 exit code def exitCode = sh( script: "open-code-review --rules=/tmp/rules/ --context=/tmp/rules/context.json --fail-on=high-risk .", returnStatus: true ) if (exitCode != 0) { // 解析 ocr 输出的 structured json，调用 Jenkins REST API 发送 build failure sh "curl -X POST -H 'Content-Type: application/json' -d @/tmp/ocr-report.json http://jenkins.internal/job/${JOB_NAME}/build" error "Open Code Review failed with high-risk issues" } } } } } }

实操心得：GitHub Actions 的createReviewCommentAPI 有速率限制（5000/hour），我们在线上环境加了指数退避重试逻辑，并缓存 comment hash 避免重复提交。Jenkins 方案则更强调稳定性，所有网络请求都走公司 proxy，且规则包下载失败时自动 fallback 到本地镜像。

4.4 开发者工作流整合：VS Code 插件与 CLI 本地预检

让开发者在提交前就获得反馈，是降低修复成本的关键。我们提供两种轻量级集成：

VS Code 插件（ocrr-vscode）：

• 不依赖 Node.js runtime，纯 WebAssembly 实现
• 安装后右键菜单增加 “Run Open Code Review on File”，实时显示 AST 匹配结果
• 关键特性：点击 warning message，自动跳转到规则 YAML 文件对应行，支持 Ctrl+Click 跳转到规则文档

CLI 本地预检（推荐）：

# 提交前一键扫描 git add . open-code-review --rules=./rules/finance/ --context=./rules/context.json --output-format=console . # 生成可分享的评审报告（含 trace id） open-code-review --rules=./rules/finance/ --context=./rules/context.json --output-format=json --report-id=pr-12345 . > ocr-report.json # 将报告上传到内部知识库，供 reviewer 快速查阅 curl -X POST -H "Content-Type: application/json" --data-binary @ocr-report.json https://kb.internal/api/reports

这个本地 workflow 让开发者平均提前 2.3 小时发现高危问题，PR 一次通过率从 41% 提升至 79%。更重要的是，它把 review 从“事后审判”变成了“事前协作”——开发者看到no-async-log-in-payment规则触发时，会主动查阅rules/finance/gdpr.yaml的文档注释，理解为什么这条规则存在，而不是简单地删掉那行await。

5. 常见问题排查手册：从 “command not found” 到 “context hash mismatch”

在 12 个落地项目中，我们整理出开发者最常遇到的 7 类问题，按发生频率排序并给出根因分析与解决路径。

5.1 “open-code-review: command not found” —— 环境 PATH 陷阱

现象：CI job 报错open-code-review: command not found，但手动登录 runner 执行which open-code-review却能找到。

根因分析：Jenkins/GitHub Actions 的非交互式 shell 默认不加载~/.bashrc或/etc/environment，PATH 变量未包含/usr/local/bin。尤其在 Ubuntu 22.04+ 系统中，/usr/local/bin不再默认加入 root PATH。

解决路径：

• GitHub Actions：在run:步骤前显式设置 PATH

  - name: Set PATH run: echo "PATH=/usr/local/bin:$PATH" >> $GITHUB_ENV

• Jenkins：在 pipeline 的environment块中声明

  environment { PATH = "/usr/local/bin:/usr/bin:/bin" }

• 本地开发：用sudo install -m 0755 ocr /usr/local/bin/open-code-review替代mv，确保权限正确

注意：绝对不要用export PATH=...在脚本中临时修改，这会导致后续步骤 PATH 丢失。必须通过$GITHUB_ENV或 Jenkinsenvironment块持久化。

5.2 “Failed to parse git diff: invalid hunk header” —— diff 格式兼容性问题

现象：open-code-review报错invalid hunk header，但git diff命令在终端里能正常输出。

根因分析：某些 Git 客户端（如 SourceTree、GitKraken）或 CI 环境（如 Bitbucket Pipelines）默认启用--color=always，导致 diff 输出包含 ANSI 转义字符，破坏 hunk header 格式。

解决路径：

• 强制禁用颜色：在 CI 脚本开头添加

  git config --global color.ui false git config --global pager.diff false

• 使用 --no-pager 参数：所有 git 命令显式带上--no-pager

  git --no-pager diff HEAD~1 --name-only

• 预处理 diff 流：用sed 's/\x1b\[[0-9;]*m//g'清洗 ANSI 转义符（仅作备用）

实测：Bitbucket Pipelines 环境下，开启--no-pager后问题 100% 解决，且不影响其他 git 功能。

5.3 “Context hash mismatch: expected xxx, got yyy” —— 上下文一致性校验失败

现象：review comment 显示context hash mismatch，提示上下文文件被篡改。

根因分析：open-code-review 对--context文件做 SHA256 校验，确保评审时使用的上下文与规则编译时一致。当规则仓库更新 context 文件但未更新规则 version 时，旧规则仍引用旧 context hash，导致校验失败。

解决路径：

• 严格执行规则版本管理：每次修改context.json，必须同步 bumprules/finance/gdpr.yaml的version字段，并重新运行open-code-review compile-rules
• CI 自动化校验：在 rules 仓库的 PR 检查中加入

  open-code-review validate-context --rules=./ --context=./context/

• 开发者自查命令：open-code-review show-context-hash --context=./rules/context.json，与规则 YAML 中的context_hash字段比对

实操心得：我们曾因忘记 bump version 导致线上 CI 集体失败。现在所有 rules 仓库的 CI 都强制运行validate-context，失败则直接拒绝合并，从源头堵死这个问题。

5.4 “No rules matched” —— 规则未生效的静默陷阱

现象：明明写了规则，但open-code-review执行后无任何输出，exit code 0。

根因分析：规则pattern语法错误或上下文过滤条件过严。常见错误包括：

• AST pattern 中用了不存在的节点类型（如MethodDefinition写成MethodDecl）
• context字段值与代码中实际标记不符（如代码里写// @context paymentCallback，但规则写context: ["payment_callback"]）
• 规则文件未被--rules参数正确包含（路径拼写错误或 glob 匹配失败）

解决路径：

• 启用 debug 模式：open-code-review --debug --rules=./rules/finance/ .，查看详细匹配日志
• 规则测试先行：用open-code-review --test ./rules/finance/gdpr.yaml验证单条规则
• 可视化 pattern 调试：open-code-review --ast-tree ./src/payment/processor.js输出 AST 结构，人工确认节点类型和属性名

我们为团队编写了《AST Pattern Debugging Checklist》，列出了 12 种高频 pattern 错误及修正示例，新成员入职必考。

5.5 “GitHub API rate limit exceeded” —— 评论发布限流问题

现象：GitHub Actions 中createReviewComment报错403 rate limit exceeded。

根因分析：GitHub 的 unauthenticated API 请求限流为 60/hour，authenticated 为 5000/hour。当 PR 包含大量小文件变更时，可能单次触发超 100 条 comment，接近限流阈值。

解决路径：

• 批量提交：修改插件逻辑，将同文件的多条 comment 合并为一条，用<details><summary>3 issues</summary>...</details>折叠显示
• 指数退避重试：在 API 调用封装层加入 retry 逻辑，初始 delay 100ms，每次翻倍，最大 retry 3 次
• 本地缓存 hash：为每条评论生成唯一 hash（sha256(rule_id + path + line + message)），提交前先 GET/repos/{owner}/{repo}/pulls/{pull_number}/comments检查是否已存在，避免重复提交

实测：启用批量提交 + hash 缓存后，comment 提交成功率从 82% 提升至 99.9%，且 PR 页面更清爽。

5.6 “Rule compilation failed: unsupported LLM model” —— rule grounding 环境缺失

现象：在 rules 仓库运行open-code-review compile-rules时，报错unsupported LLM model。

根因分析：rule grounding 需要本地运行 LLM（如 CodeLlama-7b），但 CI runner 未安装 CUDA 驱动或缺少 required model weights。

解决路径：

• 离线编译模式：open-code-review compile-rules --offline --model-path=./models/codellama-7b.Q4_K_M.gguf，指定量化模型路径
• 预编译规则包：在专用编译机上运行compile-rules，生成rules-compiled.tar.gz，CI 直接解压使用
• 降级 fallback：当 LLM 不可用时，自动切换到 heuristic-based pattern generation（基于关键词匹配的简化版）

注意：生产环境严禁实时调用 LLM 进行 rule grounding。所有规则必须在 merge 到main分支前完成编译，CI 只负责加载和执行。

5.7 “AST parsing timeout: 3000ms exceeded” —