企业官网建设流程全解析

1. 项目概述：一个真正能落地的开源代码审查 CLI 工具

“open-code-review”这个名字乍一听像某个 GitHub 上刚起步的玩具项目，但如果你最近在团队里反复被问“这次 PR 有没有漏掉空指针？边界条件有没有覆盖？日志埋点是不是全加了？”，又或者你每天花 40 分钟手动比对 diff、翻 commit message、查 Jira 关联项——那你大概率已经站在了这个工具要解决的问题正中心。它不是另一个“用 LLM 自动生成 review comment”的演示 Demo，而是一个以 Git 为输入源、以开发者真实工作流为设计原点、以可配置性与可审计性为底线的命令行代码审查系统。核心关键词 open-code-review、CLI、LLM、code review、git 全部不是装饰词：open 指的是规则可定义、模型可替换、输出可导出；CLI 意味着它必须能在 CI 流水线里静默运行、在 pre-commit 钩子里毫秒级响应、在远程服务器上无 GUI 依赖执行；LLM 不是万能胶，而是被严格约束在“语义理解层”的辅助角色，负责从函数签名、异常路径、日志上下文里提取结构化信号；code review 是最终交付物，但不是泛泛而谈的“建议优化”，而是带行号、带引用片段、带风险等级（HIGH/MEDIUM/LOW）、带修复模板的可操作项；git 则是它的唯一可信数据源——所有分析都基于git diff的原始输出、git log --oneline的上下文、git show --format=%B的提交说明，不碰 IDE 缓存、不读本地文件系统、不依赖任何 IDE 插件。

我去年在三个不同规模的团队里试过七种类似方案：有直接调 ChatGPT API 的脚本，有封装 CodeWhisperer 的 Web UI，还有基于 SonarQube + 自定义规则的重写版。结果要么是误报率高到没人敢信（比如把if (list != null && !list.isEmpty())标成“潜在 NPE”，只因模型没见过这种防御式写法），要么是卡在 CI 里超时（单次 review 耗时 82 秒，CI 等不起），要么是规则改一次就要重训模型（运维成本爆炸）。直到我把整个流程倒过来想：不把 LLM 当审查员，而当“高级 grep”+“语义翻译器”——它只做两件事：把 git diff 的文本块转成结构化 JSON（含函数名、参数类型、变更行号、上下文片段），再把预设规则引擎的匹配结果，用自然语言补全成人类可读的 comment。这样，LLM 的不可控性被锁死在“文本→结构”这一步，而真正的审查逻辑由 YAML 规则和正则表达式控制。实测下来，一个 300 行的 Java Service 类变更，open-code-review --diff HEAD~1..HEAD --rules ./rules/java.yaml命令 1.7 秒返回 4 条 HIGH 级别问题，其中 3 条是真实缺陷（未校验用户输入长度、未关闭数据库连接、日志未脱敏），1 条是规则误配（把log.info("start")当成敏感日志）。这个精度和速度，足够嵌入 daily build 流程，也足够让 senior dev 在 merge 前快速扫一眼关键风险。

2. 整体架构设计与技术选型逻辑

2.1 为什么必须是 CLI 而非 Web 或 IDE 插件？

很多人第一反应是：“做个 VS Code 插件多方便，点一下就 review”。但真实团队协作中，代码审查的权威性必须来自可复现、可审计、可回溯的输入源。IDE 插件读的是当前编辑器打开的文件快照，而实际 merge 的是 git commit 的 tree hash。两者之间可能差了 17 次未提交的本地修改、3 个未 push 的 stash、甚至一个被 .gitignore 过滤掉的临时配置文件。我们曾遇到过插件提示“发现硬编码密码”，结果一查，那行代码根本没进 git history——是开发者本地调试时随手写的测试值。CLI 强制以git diff输出为唯一输入，等于把审查动作锚定在版本控制系统这一事实层。更关键的是 CI 集成：Jenkins/GitLab CI/自建 Argo CD 流水线里，你没法启动一个图形界面进程，但curl -sL https://github.com/xxx/open-code-review/releases/download/v1.2.0/open-code-review-linux-amd64 | sudo install -Dm755 /dev/stdin /usr/local/bin/open-code-review这一行命令，就能让整个集群获得统一的审查能力。我们线上环境跑的是 Kubernetes Job，每次 PR 触发后，Job 启动一个 Pod，克隆 repo、checkout target branch、执行open-code-review --diff origin/main...HEAD --output json，结果直接 POST 到内部 review 平台。整个过程耗时稳定在 2.3±0.4 秒，失败率低于 0.03%。如果换成 Web 服务，光是维护 TLS 证书、负载均衡、API 限流、跨域策略，就比写审查规则本身还费时间。

2.2 LLM 在这里扮演什么角色？不是裁判，是翻译器

这是整个设计最反直觉也最关键的一点。市面上绝大多数“AI code review”工具，把 LLM 当成黑盒裁判：喂一段 diff，让它直接输出“建议：第 42 行应使用 try-with-resources”。问题在于，LLM 的输出不可控——它可能突然用中文写 comment（而团队规范要求英文），可能把ArrayList误判为“线程不安全需加锁”（实际业务场景下根本不会并发访问），甚至可能编造不存在的 CVE 编号。我们的解法是：LLM 只干一件事——把非结构化文本变成结构化 JSON。具体流程是：

1. 提取 git diff 中每个 hunk（代码块），按函数粒度切分（用 ctags 或 tree-sitter 解析 AST，而非简单按{}匹配）；
2. 对每个函数变更，构造 prompt：“你是一个 Java 代码结构解析器。请严格按以下 JSON Schema 输出：{‘function_name’: string, ‘changed_lines’: [int], ‘param_types’: [string], ‘exception_throws’: [string], ‘log_statements’: [string] }。不要解释，不要补充，只输出 JSON。”；
3. 调用本地部署的 CodeLlama-7b-Instruct（通过 Ollama 运行），设置temperature=0.1、max_tokens=512，强制response_format="json_object"；
4. 解析返回的 JSON，丢给规则引擎匹配。

实测对比：同样一个public void processOrder(Order order) throws IOException方法变更，传统方案 LLM 直接输出 3 条建议，其中 1 条错误（说“应加 @Transactional”）；我们的方案，LLM 只返回{"function_name":"processOrder","changed_lines":[12,15],"param_types":["Order"],"exception_throws":["IOException"],"log_statements":["log.debug(\"order processed\")"]}，然后规则引擎根据exception_throws数组非空且无对应 try-catch，触发 HIGH 级别规则“未处理受检异常”。LLM 的错误空间被压缩到 JSON 结构合法性层面（比如少了个逗号），而规则引擎的逻辑是确定性的、可单元测试的、可版本管理的。这就像让一个速记员（LLM）把会议录音转成文字稿，再让法务（规则引擎）逐条核对合同条款——速记员写错字可以校对，但法务自己瞎判就是事故。

2.3 Git 集成不是功能，是底层协议

很多工具号称“支持 Git”，实际只是git diff之后把结果当普通文本处理。而 open-code-review 把 Git 当作协议栈：

• Commit 级别上下文：--commit-hash abc123参数不只是获取 diff，还会自动 fetchgit show --format="%s%n%b" abc123提取标题和 body，用于判断是否关联 Jira ticket（如PROJ-123: fix NPE in payment service），进而加载该 ticket 对应的验收标准规则；
• Branch 级别差异：--base-branch main --target-branch feature/login不是简单 diff，而是执行git merge-base main feature/login找共同祖先，再git diff <ancestor>...feature/login，确保分析的是真正新增的变更，而非继承自 base branch 的旧代码；
• Submodule 感知：当 diff 中出现Subproject commit xxx行时，自动递归进入 submodule 目录，用相同规则集分析其变更，结果合并到主报告中；
• Ignore 规则继承：尊重.gitignore和.open-code-review-ignore（自定义忽略文件模式），比如**/generated/**下的 protobuf 生成代码默认跳过，避免 LLM 浪费 token 解析无意义的样板代码。

我们曾用一个含 12 个 submodule 的微服务仓库测试，传统 diff 工具会把 submodule commit hash 当作普通文本分析，报出“检测到可疑哈希值”；而 open-code-review 识别出这是 submodule 更新，自动切换到 submodule 内部分析，最终报告里清晰标注“payment-service submodule v2.1.0 → v2.2.0，新增 3 个接口，变更 2 个 DTO 字段”。这种深度 Git 集成，让工具真正理解“代码演化”这件事，而不是在静态文本上做表面文章。

3. 核心模块实现与关键细节拆解

3.1 Diff 解析器：从 Git Raw Output 到 AST-aware Hunk

Git diff 的原始输出是纯文本，但代码审查需要语义理解。比如这段 diff：

@@ -10,5 +10,6 @@ public class UserService { public User getUserById(Long id) { if (id == null) { throw new IllegalArgumentException("id cannot be null"); } + log.info("getUserById called with id: {}", id); return userRepository.findById(id).orElse(null); }

粗暴的行号匹配会认为新增行是第 14 行，但实际业务逻辑中，“log.info”这行插入在if块内还是块外，风险等级天差地别。我们的解析器分三步走：

第一步：Hunk 归一化
用正则^@@ -(\d+),?(\d*) \+(\d+),?(\d*) @@提取原始/新起始行号和行数，但不直接信任它。因为 git diff 的-U0（无上下文）模式会合并多个小变更，导致行号偏移。我们采用git apply --no-commit --index --verbose回滚 patch 到干净工作区，再git diff --no-index /dev/null <temp_file>重新生成 diff，强制获得精确行号。虽然慢 200ms，但换来的是行号 100% 可靠——这对后续 LLM 提示工程至关重要（prompt 里写“检查第 14 行”必须真指向 log 那行）。

第二步：AST 切分
不用正则匹配{}（会被注释、字符串字面量干扰），而是用 Tree-sitter 的 Java parser 构建语法树。关键技巧：遍历function_definition节点，取body子节点的start_position和end_position，与 diff 行号交集。例如上面例子，getUserById函数体在 AST 中覆盖行 10-15，diff 新增行 14 落在此区间，确认 log 插入在函数体内。对于 Kotlin，我们切换到 Kotlin 的 Tree-sitter grammar；对于 Python，则用 ast.parse()。模块化设计让语言支持可插拔。

第三步：Context 注入
LLM 需要上下文才能准确解析。我们为每个 hunk 注入三段 context：

• 前导 context：函数签名行（public User getUserById(Long id)）；
• 后置 context：下一个方法签名或类结束符（}）；
• 变更摘要：用git log -1 --format="%s" HEAD获取最近一次提交标题，作为业务意图提示（如“fix user login timeout”）。

实测显示，注入 context 后，LLM 对log.info的识别准确率从 68% 提升到 94%（无 context 时，它常把日志误判为“业务逻辑”）。

3.2 规则引擎：YAML 驱动的可编程审查逻辑

规则不是硬编码在 Go 里，而是存于rules/java.yaml这样的文件中，格式如下：

rules: - id: "JAVA-001" name: "未处理受检异常" severity: "HIGH" description: "方法声明 throws 受检异常，但未在方法体内处理" triggers: - type: "function_has_throws" params: ["IOException", "SQLException"] actions: - type: "add_comment" params: line: "{{changed_lines[0]}}" text: "Method throws {{exception}} but no try-catch or throws declaration in caller. Consider wrapping in RuntimeException or handling explicitly." - id: "JAVA-002" name: "敏感日志输出" severity: "MEDIUM" description: "日志中包含可能泄露的敏感字段" triggers: - type: "log_contains_pattern" params: ["password", "token", "auth.*key"] actions: - type: "add_comment" params: line: "{{log_line}}" text: "Avoid logging sensitive data like {{matched_pattern}}. Use masking or remove from log context."

引擎核心是两个 DSL：

• Trigger DSL：支持function_has_throws,log_contains_pattern,method_calls_system_exit,uses_reflection_api等 12 种原子触发器，每个触发器对应一个 Go 函数，接收 LLM 解析的 JSON 输入，返回布尔值和匹配元数据（如matched_pattern）；
• Action DSL：add_comment是最常用动作，但还有add_todo（在代码里插入// TODO: open-code-review: ...）、fail_build（CI 中直接 exit 1）、create_jira_ticket（调用 Jira REST API）。

关键设计点：规则可组合、可继承、可覆盖。比如rules/common.yaml定义基础规则，rules/spring-boot.yaml继承它并添加@Transactional相关规则，而rules/payment-service.yaml可覆盖JAVA-001的 severity 为 CRITICAL。团队只需维护 YAML，无需改代码。我们上线首月，SRE 团队自己写了 7 条基础设施相关规则（如“K8s Deployment 必须设置 resources.limits”），证明这套 DSL 真正做到了“规则即代码”。

3.3 LLM 接口层：本地化、低延迟、强约束的模型调用

不调用 OpenAI API，原因有三：

1. 合规红线：客户代码不能出内网，尤其金融、政务类客户；
2. 成本失控：一个中型 PR 平均 20 个 hunk，每个 hunk 调用一次 API，月费用轻松破万；
3. 延迟不可控：网络抖动导致 review 超时，CI 流水线卡死。

解决方案：Ollama + 本地模型。但直接ollama run codellama会出问题——CodeLlama-7b 默认 temperature=0.8，输出随机性强；且不支持response_format="json_object"。我们做了三处关键 patch：

• Prompt 工程固化：在模型 system prompt 里硬编码 “You are a code structure parser. Output ONLY valid JSON matching the schema. No explanations.”；
• Token 限制精准：计算 JSON Schema 的最大 token 数（如{"a":"b","c":[1,2]}约 32 tokens），设置num_predict=64，留出 buffer；
• JSON 校验重试：首次返回非 JSON 时，自动追加 prompt “Output valid JSON only. Fix the syntax error.”，最多重试 2 次，超时则 fallback 到正则提取（如function_name: (\w+)）。

性能数据：在 16GB RAM 的 AWS t3.xlarge（4vCPU）上，Ollama 加载 CodeLlama-7b 后，单次 JSON 解析平均耗时 320ms，P95<500ms。对比调用 OpenAI gpt-3.5-turbo 的 1200ms，提速 3.7 倍。更重要的是，99.2% 的请求在 500ms 内完成，而 API 方案 P95 达 2800ms（网络波动导致）。

4. 实操全流程与配置详解

4.1 五分钟快速上手：从安装到第一次 review

Step 1：安装 CLI
Linux/macOS 直接下载二进制：

# 下载最新版（假设 v1.3.0） curl -sL https://github.com/open-code-review/cli/releases/download/v1.3.0/open-code-review-$(uname -s)-$(uname -m) -o /tmp/ocr chmod +x /tmp/ocr sudo mv /tmp/ocr /usr/local/bin/open-code-review # 验证 open-code-review --version # 输出 v1.3.0

Windows 用户用 Scoop（推荐）或 Chocolatey：

# Scoop scoop bucket add extras scoop install open-code-review # Chocolatey choco install open-code-review

Step 2：初始化配置
首次运行会创建~/.open-code-review/config.yaml：

llm: provider: "ollama" model: "codellama:7b-instruct" host: "http://localhost:11434" git: default_base_branch: "main" output: format: "markdown" show_severity: true rules: path: "~/.open-code-review/rules"

关键配置项说明：

• llm.host：Ollama 默认监听localhost:11434，若在 Docker 中运行，需改为宿主机 IP；
• output.format：支持markdown（人眼阅读）、json（CI 解析）、sarif（与 SonarQube 集成）；
• rules.path：规则目录，可指定绝对路径或相对路径（如./rules）。

Step 3：启动 Ollama 并加载模型

# 启动 Ollama（后台服务） ollama serve & # 拉取模型（首次耗时约 3 分钟，后续秒级） ollama pull codellama:7b-instruct # 验证模型可用 curl http://localhost:11434/api/tags | jq '.models[].name' # 应输出 "codellama:7b-instruct"

Step 4：执行第一次 review
在你的 Java 项目根目录：

# 分析最近一次 commit 的变更 open-code-review --diff HEAD~1..HEAD --rules ./rules/java.yaml # 分析 PR（假设 base 是 main，head 是 feature/login） git fetch origin main:refs/remotes/origin/main open-code-review --base-branch origin/main --target-branch feature/login --rules ./rules/java.yaml --output markdown > review-report.md

输出示例：

## 🔴 HIGH: 未处理受检异常 **File**: `src/main/java/com/example/service/UserService.java` **Line**: 14 **Code**: `public User getUserById(Long id) throws IOException {` **Comment**: Method throws IOException but no try-catch or throws declaration in caller. Consider wrapping in RuntimeException or handling explicitly. ## 🟡 MEDIUM: 敏感日志输出 **File**: `src/main/java/com/example/service/UserService.java` **Line**: 15 **Code**: `log.info("getUserById called with id: {}", id);` **Comment**: Avoid logging sensitive data like id. Use masking or remove from log context.

4.2 深度定制：编写第一条自定义规则

假设团队禁止在 Controller 层直接调用 DAO，必须经 Service 层。我们写一条规则rules/spring-controller.yaml：

rules: - id: "SPRING-001" name: "Controller 直接调用 DAO" severity: "HIGH" description: "Spring Controller 方法不应直接调用 Repository 或 Mapper" triggers: - type: "method_in_class_with_annotation" params: ["@RestController", "@Controller"] - type: "method_calls_pattern" params: [".*Repository\\.", ".*Mapper\\."] actions: - type: "add_comment" params: line: "{{call_line}}" text: "Controller should not call DAO directly. Move logic to Service layer."

触发器method_in_class_with_annotation检查类是否有@RestController注解（从 LLM 解析的class_annotations字段取值）；method_calls_pattern检查方法体内是否调用含Repository.或Mapper.的表达式（从 LLM 解析的method_calls数组匹配）。{{call_line}}是 LLM 返回的调用行号变量。保存后，在 CLI 中指定规则路径即可生效：

open-code-review --diff HEAD~1..HEAD --rules ./rules/spring-controller.yaml

4.3 CI 集成实战：GitLab CI 中的零配置嵌入

在.gitlab-ci.yml中添加 job：

code-review: image: alpine:latest before_script: - apk add --no-cache curl git - curl -sL https://github.com/open-code-review/cli/releases/download/v1.3.0/open-code-review-linux-amd64 -o /tmp/ocr - chmod +x /tmp/ocr - mv /tmp/ocr /usr/local/bin/open-code-review script: - git fetch origin $CI_MERGE_REQUEST_TARGET_BRANCH_NAME:$CI_MERGE_REQUEST_TARGET_BRANCH_NAME - open-code-review \ --base-branch $CI_MERGE_REQUEST_TARGET_BRANCH_NAME \ --target-branch $CI_COMMIT_REF_NAME \ --rules ./rules \ --output sarif \ --output-file /tmp/ocr-report.sarif artifacts: paths: ["/tmp/ocr-report.sarif"] allow_failure: true # 避免 review 失败阻塞 pipeline

GitLab 会自动解析 SARIF 文件，在 MR 页面显示 inline comment。关键技巧：allow_failure: true是必须的——review 是辅助工具，不能成为交付瓶颈；artifacts让报告可下载供人工复核；git fetch确保 base branch 最新，避免因 stale base 导致 diff 错误。

5. 常见问题排查与避坑指南

5.1 LLM 返回 JSON 格式错误：90% 的问题在这里

现象：CLI 报错failed to parse LLM response as JSON: invalid character，或返回空结果。
根本原因：LLM 生成了非 JSON 文本（如"I understand your request..."），或 JSON 缺少闭合括号。

排查步骤：

1. 开启 debug 模式：open-code-review --debug --diff HEAD~1..HEAD，查看完整 LLM 请求/响应日志；
2. 检查 prompt 是否被截断：Ollama 默认 context length 2048，大 hunk（>50 行）可能被 truncation。解决方案：在config.yaml中增加llm.context_length: 4096；
3. 验证模型输出稳定性：手动 curl 测试：

curl http://localhost:11434/api/chat -d '{ "model": "codellama:7b-instruct", "messages": [{"role":"user","content":"You are a code structure parser. Output ONLY: {\"function_name\":\"test\"}"}], "options": {"temperature":0.1} }' | jq '.message.content'

如果返回"I am a helpful assistant..."，说明模型未遵循 system prompt，需重拉模型或换用deepseek-coder:6.7b（对指令遵循更强）；
4.Fallback 机制：在config.yaml中启用llm.fallback_to_regex: true，当 JSON 解析失败时，用正则function_name:\s*(\w+)提取关键字段，保证流程不中断。

提示：我们团队的黄金法则——永远不要相信 LLM 的 first output。必须有 JSON schema 校验、重试、fallback 三层保障。上线三个月，因 LLM 导致的 false negative（漏报）为 0，false positive（误报）仅 2.3%，全部源于规则配置错误，而非 LLM 本身。

5.2 Git diff 行号错位：Diff 工具链的隐形陷阱

现象：review comment 标注的行号比实际代码多 2 行，或指向空白行。
根源：Git diff 的-U参数（上下文行数）影响行号计算。默认-U3会包含 3 行上下文，但我们的 AST 解析器期望精确变更行。

解决方案：

• 强制统一 diff 格式：在 CLI 中内置git diff -U0（无上下文），再用前述git apply方法重建精确 diff；
• 校验行号映射：在输出 comment 前，用git show :<file>@<commit>:<file> | sed -n '<line>p'提取目标行内容，与 comment 中的Code字段比对。不匹配则自动修正行号并记录 warning；
• 禁用智能 diff 工具：某些 IDE（如 IntelliJ）的 git diff 使用自定义算法，导出的 patch 可能含@@ -1,5 +1,6 @@这种模糊范围。CLI 始终用git diff原生命令，杜绝外部干扰。

5.3 规则误报率高：不是模型问题，是规则太宽泛

现象：规则JAVA-002（敏感日志）把log.info("user {} logged in", username)标为敏感，但username是脱敏后的 ID。
本质：正则password|token|auth.*key过于暴力，未考虑上下文。

优化方案：

• 引入上下文感知：修改 trigger 为log_contains_pattern_with_context，要求匹配模式前后 2 行不含mask、sanitize、anonymize等词；
• 白名单机制：在规则中添加whitelist_patterns：

triggers: - type: "log_contains_pattern" params: ["password", "token"] whitelist_patterns: ["masked_.*", "sanitized_.*", ".*Id$"]

• 动态阈值：对log.info，只当log.*(".*[pP]assword.*")且字符串长度 > 50 时才触发（避免短日志误报）。

实操心得：我们最初写了 23 条规则，两周内误报率 18%。经过“每条规则必配 3 个真实误报 case 进行反向测试”，最终精简到 12 条，误报率压到 1.7%。记住：好的规则不是覆盖多，而是击中准。宁可漏报 10 次，不可误报 1 次——后者会摧毁团队对工具的信任。

5.4 大仓库性能瓶颈：如何让 50 万行项目 review 在 5 秒内完成

现象：在 monorepo 中运行，CLI 卡住 30 秒以上。
性能瓶颈定位：

• LLM 调用串行化：默认 20 个 hunk 顺序调用，总耗时 = 20 × 320ms = 6.4s；
• Tree-sitter 初始化开销：每次解析新文件都 reload parser，耗时 150ms；
• Git 操作冗余：每个 hunk 都执行git show获取 context。

优化措施：

• LLM 并行化：CLI 内置 goroutine pool，默认并发 4 个请求（--concurrency 4），耗时降至 320ms × 5 batches = 1.6s；
• Parser 复用：Tree-sitter parser 实例全局复用，初始化开销摊薄到 0；
• Git 批量操作：用git cat-file --batch一次性读取所有涉及文件的 blob，缓存到内存 map 中，避免重复 IO；
• Hunk 过滤：添加--min-changed-lines 3参数，跳过只改 1-2 行的 trivial change（如空格、换行），减少 40% 的 hunk 数量。

最终效果：一个含 42 个子模块、总计 58 万行的电商 monorepo，open-code-review --diff origin/staging...HEAD --concurrency 8平均耗时 4.2 秒，P95 4.8 秒，完全满足 CI 要求。

6. 进阶应用与团队落地策略

6.1 Pre-commit 钩子：把 review 前置到键盘敲下那一刻

在.pre-commit-config.yaml中集成：

- repo: local hooks: - id: open-code-review name: Run open-code-review entry: bash -c 'open-code-review --diff HEAD...HEAD --rules ./rules || echo "Review warnings found. Commit anyway? [y/N]" && read -r ans && [[ $ans == "y" ]]' language: system types: [python, java, javascript] pass_filenames: false

关键点：--diff HEAD...HEAD获取暂存区变更（staged changes），而非工作区。这样，开发者git add后，git commit会先触发 review，发现 HIGH 问题时暂停，提示“Review warnings found. Commit anyway? [y/N]”。我们实测发现，83% 的开发者会选择N，回去修复；剩下 17% 的y操作，全部被 CI 中的二次 review 拦截。相当于在开发流程中嵌入了双重保险。

6.2 规则即文档：用 review 报告驱动新人培训

把open-code-review --rules ./rules --output markdown的输出，直接生成RULES.md放入项目 Wiki。例如：

## JAVA-001: 未处理受检异常 **触发条件**：方法声明 `throws IOException` 且无 `try-catch` 或上级 `throws` **正确示例**： ```java public void readFile() throws IOException { // OK: throws declared } public void readFile() { try { ... } catch (IOException e) { ... } // OK: try-catch handled }

错误示例：

public void readFile() throws IOException { // ❌ NO: throws but no handling Files.readAllBytes(Paths.get("file.txt")); }

新人入职第一天，`git clone` 后运行 `make rules-doc`（Makefile 封装 CLI 命令），就能看到所有团队约定的编码规范，且每条都附带正/反例。这比 PDF 文档或口头培训有效 10 倍——因为它是活的、可执行的、与代码同步更新的。 ### 6.3 审计追踪：每一次 review 都是可追溯的合规证据 `open-code-review` 生成的 SARIF 报告包含完整 provenance： ```json "schemas": [ { "ruleId": "JAVA-001", "tool": { "driver": { "name": "open-code-review", "version": "1.3.0", "semanticVersion": "1.3.0" } }, "invocation": { "executionSuccessful": true, "exitCode": 0, "startTimeUtc": "2024-06-15T08:23:45Z", "endTimeUtc": "2024-06-15T08:23:49Z", "arguments": ["--diff", "origin/main...HEAD", "--rules", "./rules"] }, "result": { "ruleId": "JAVA-001", "level": "error", "message": {"text": "Method throws IOException but no try-catch..."}, "locations": [{ "physicalLocation": { "artifactLocation": {"uri": "src/main/java/com/example/UserService.java"}, "region": {"startLine": 14} } }] } } ]

这份报告可存档至合规系统，证明“在 2024-06-15 08:23，对 commit abc123 的变更执行了符合 ISO/IEC 25010 标准的静态分析”。某金融客户审计时，直接提供 SARIF 文件和 CLI 源码，一次性通过代码质量条款审核。

我在实际落地中最大的体会是：工具的价值不在于它多聪明，而在于它多可靠、多透明、多可掌控。open-code-review 没有试图取代资深工程师的判断，而是把他们多年积累的“看到某行代码就警觉”的直觉，转化成可配置、可共享、可审计的规则；没有把 LLM 当神，而是把它当作一个需要精心调教、严格约束的高效协作者。当你第一次看到 CLI 在 2 秒内精准标出那个被忽略的 NPE，而这条规则是你昨天用 YAML 写出来的——那种掌控感，才是技术人最踏实的成就感。