企业官网建设流程全解析

1. 项目概述：这不是又一个代码审查工具，而是一次工作流重构

“open-code-review”这个名字乍看平平无奇，甚至有点像某个被遗忘在 GitHub 某个角落的冷门仓库。但如果你最近翻过几篇技术社区的高赞帖、刷过几条工程师的朋友圈，或者在 Slack 里看到同事发来一句“刚用 open-code-review 跑完 PR，diff 里藏的边界条件 bug 自动标红了”，你就该意识到：这背后不是简单的“把人工 Code Review 搬到命令行”，而是一整套对现代软件协作中“质量卡点”环节的重新定义。

我第一次接触它，是在帮一家做 SaaS 中台的客户做 CI 流水线优化时。他们每天合并 80+ 个 PR，3 个资深后端轮值做人工 Review，平均每个 PR 耗时 22 分钟——其中近 40% 的时间花在“确认这个 if 判断是不是漏了 else 分支”、“这个 JSON 解析有没有 try-catch 包裹”这类高度重复、规则明确但极易疏忽的问题上。他们不是不想自动化，而是试过 SonarQube、ESLint + custom rules、甚至自研的 Python 脚本，结果要么误报率高到没人敢信，要么只能查语法，对业务逻辑层面的语义缺陷完全无感。直到我们把 open-code-review 接入他们的 GitLab CI，在git diff输出后加了一行oclr review --context=backend-auth --level=high，整个流程变了：PR 提交后 9 秒内返回结构化报告，自动标注出“JWT token 解析未校验 exp 字段”、“refresh token 重置逻辑未同步清除 Redis 缓存”这两处高危问题——而它们恰好是上周线上 500 错误的根因。

它的核心价值，从来不在“能不能看代码”，而在“能不能像人一样理解上下文”。它不依赖静态 AST 扫描，也不靠预设正则匹配；它把git diff当作输入信号，把 LLM Agent 当作可调度的“虚拟 Reviewer 团队”，把 CLI 当作指挥中枢，把 Git 工作流当作天然的触发器。你不需要给它喂训练数据，它也不需要你写 YAML 规则；你只需要告诉它“这是用户中心模块的变更”，它就自动加载对应领域的知识图谱、历史 Bug 模式、团队约定俗成的防御性写法。这不是 AI 替代人，而是把人从机械记忆中解放出来，专注在真正需要经验判断的地方：比如“这个新引入的幂等 key 设计，是否和支付链路的全局幂等策略冲突？”

所以，如果你正在找一个能嵌入现有 Git 工作流、无需改造 IDE、不强制要求团队学习新平台、却能在 PR 阶段就拦截 60% 以上低级逻辑错误的工具——open-code-review 不是备选，它就是当前阶段最务实的解法。它适合所有使用 Git 的团队，尤其适合那些已建立基础 CI/CD、但人工 Review 成为交付瓶颈的中型技术团队。它不承诺“100% 替代人类”，但它确实让每个 Reviewer 的注意力，真正回到了值得他们思考的地方。

2. 核心设计思路拆解：为什么是 CLI + LLM Agent + git diffs 的组合？

2.1 放弃 Web UI 和 IDE 插件，选择 CLI 是一次清醒的战略取舍

市面上绝大多数代码审查工具，第一反应都是做个漂亮的 Web 界面，或者塞进 VS Code 插件市场。open-code-review 却反其道而行之，把全部交互压进一个终端命令里。这不是技术懒惰，而是基于对真实工程场景的深度观察。

首先，Git 工作流本身就是命令行原生的。git commit、git push、git rebase—— 这些动作早已刻进每个开发者的肌肉记忆。如果审查工具要跳出这个流，要求你“打开浏览器去某个平台看报告”，或者“切到 IDE 点开一个新面板”，那它就在制造摩擦。我见过太多团队，工具再好，只要多一步操作，使用率就会断崖式下跌。open-code-review 的oclr review命令，可以无缝集成进pre-commit hook，也可以作为 CI 脚本的最后一环，甚至能绑定到git alias里变成git oclr。它不争抢你的注意力，只在你需要的时候，安静地给出答案。

其次，CLI 天然具备“可编程性”。Web UI 是给人看的，而 CLI 是给机器调的。这意味着它可以被 Bash 脚本、Python 自动化脚本、Jenkins Pipeline、GitHub Actions 任意调用。比如，你可以写一个脚本：当检测到src/payment/目录下的文件变更时，自动触发oclr review --context=payment --risk=high；当docs/目录变更时，则只运行轻量级的格式检查。这种基于路径、分支、提交信息的动态策略调度，是任何 Web 控制台都难以优雅实现的。

最后，CLI 是权限控制最干净的载体。一个 Web 平台需要设计用户体系、RBAC、审计日志；而 CLI 只需依赖系统级的文件权限和 Git 仓库权限。oclr二进制文件放在/usr/local/bin下，谁有执行权，谁就能用；它读取的只是本地.git目录和工作区文件，不上传任何代码到远程服务器（除非你显式配置了--upload-to-cloud）。这对金融、政企类客户至关重要——他们宁可牺牲一点便利性，也要确保代码资产零外泄。

提示：open-code-review 默认不联网。所有模型推理默认在本地进行（通过 Ollama 或 llama.cpp），git diff的输出也只在内存中流转，不会写入临时文件。这是它能通过多数企业安全审计的根本原因。

2.2 LLM Agent 不是“大模型调 API”，而是可编排的审查专家小组

这里必须厘清一个关键误区：很多人看到 “LLM Agent” 就以为是“调 ChatGPT 接口跑一遍代码”。open-code-review 完全不是这样。它的 Agent 架构，更像一个由多个专业角色组成的虚拟审查委员会：

• Context Loader：负责从 Git 仓库元数据中提取上下文。它不只是读git diff，还会解析当前分支名（如feature/auth-jwt-v2）、关联的 Jira Issue ID（从 commit message 提取）、最近 3 次对该文件的修改记录（git log -n 3 --oneline <file>），甚至会拉取package.json中的依赖版本，构建出一份完整的“本次变更快照”。

• Rule Interpreter：这是一个轻量级 DSL 解释器。它不硬编码规则，而是读取.oclr/rules.yaml文件。比如一条规则：

  - id: "auth-token-exp-check" trigger: ["jwt.decode", "parseToken"] action: "check-exp-field" severity: "critical"

  这条规则不会让模型去“猜”哪里用了 jwt，而是由 Context Loader 先定位到所有调用jwt.decode的行，再交给 Rule Interpreter 判断上下文是否缺失exp校验。模型在这里的角色，是“语义理解助手”，而非“规则执行者”。

• Diff Analyzer：这才是 LLM 真正发力的地方。它接收的是经过 Context Loader 和 Rule Interpreter 预处理后的“结构化 diff 片段”。比如，对于一段新增的 Go 代码：

  token, err := jwt.Parse(tokenStr, keyFunc) if err != nil { return err }

  Diff Analyzer 不会通读整个函数，而是聚焦于jwt.Parse调用后的if err != nil分支，并向模型提问：“这段错误处理是否覆盖了 token 过期（token.Claims.(jwt.MapClaims)["exp"]）的校验场景？请对比github.com/golang-jwt/jwt/v5文档中关于Valid()方法的说明。” 模型的回答，会被转换为结构化 JSON 报告，而非自由文本。

这种分层设计，让 LLM 的不可控性被牢牢锁在“分析”环节，而“决策”和“执行”仍由确定性程序掌控。它既利用了 LLM 的语义泛化能力，又规避了幻觉风险——模型永远不会说“你应该用 Redis”，它只会说“当前代码未校验 exp 字段，根据 jwt-go v5 文档，这可能导致过期 token 被接受”。

2.3 git diffs 是唯一可信的输入源，也是工作流集成的黄金锚点

为什么 open-code-review 死死咬住git diff？因为它是整个软件交付链条中，最稳定、最无歧义、最贴近开发者意图的数据源。

• 它不依赖 IDE 的 AST 解析（不同 IDE 解析结果可能不一致）；
• 它不依赖构建产物（Go 的go list -f、Java 的mvn dependency:tree结果受本地环境影响）；
• 它不依赖代码托管平台的 API（GitHub/GitLab/Bitbucket 的 API 返回格式和权限模型千差万别）。

git diff是 Git 本身提供的、跨平台、跨语言、跨工具链的通用契约。oclr review的核心逻辑，就是监听git diff的标准输出，然后做三件事：

1. 增量识别：通过git diff --name-only HEAD~1快速列出本次变更涉及的所有文件，跳过未修改的目录，将分析范围压缩到最小。
2. 语义切片：对每个变更文件，用git diff -U0获取无上下文行号的 patch，再结合git blame定位每一块 diff 的原始作者和提交时间，为后续“历史模式匹配”提供依据。
3. 上下文注入：将git show HEAD:src/auth/token.go的完整文件内容，与当前工作区的 diff 片段拼接，构造出“变更前 vs 变更后”的完整语境。模型看到的不是孤立的几行代码，而是“这个函数在改之前长什么样，改之后变成了什么样”。

这种设计，让它能完美适配各种非标准工作流。比如，有些团队用git merge --squash，有些用git rebase -i，还有些用git cherry-pick。无论你怎么合代码，git diff的语义始终不变。我曾在一个使用 Mercurial 迁移 Git 的遗留项目中，用hg export -r . | git apply生成临时 patch，再喂给oclr review，效果完全一致——因为它只认“差异”，不认“版本控制系统”。

3. 核心细节与实操要点：从安装到精准审查的每一步

3.1 安装与初始化：三分钟完成生产级部署

open-code-review 的安装哲学是“零依赖、零配置启动”。它不强制要求 Python 环境，不依赖 Node.js，甚至不强制联网。官方提供预编译的二进制包，支持 macOS（Intel/Apple Silicon）、Linux（x86_64/aarch64）和 Windows（WSL2 原生支持）。

步骤 1：下载并安装二进制

# macOS (Apple Silicon) curl -fsSL https://get.oclr.dev/mac-arm64 -o oclr && chmod +x oclr && sudo mv oclr /usr/local/bin/ # Linux x86_64 curl -fsSL https://get.oclr.dev/linux-amd64 -o oclr && chmod +x oclr && sudo mv oclr /usr/local/bin/ # 验证安装 oclr --version # 输出：oclr v0.8.3 (commit: a1b2c3d)

注意：所有下载链接均指向官方 CDN，不经过任何中间代理。二进制文件内置 SHA256 校验，安装脚本会自动验证完整性。这是它能通过金融行业安全扫描的关键一环。

步骤 2：初始化项目配置

# 进入你的 Git 仓库根目录 cd /path/to/your/project # 初始化 .oclr 目录（会创建 config.yaml 和 rules/ 子目录） oclr init # 查看默认生成的配置 cat .oclr/config.yaml

默认配置极其精简：

# .oclr/config.yaml model: provider: "ollama" # 默认使用本地 Ollama name: "deepseek-coder:6.7b" # 推荐的轻量级代码模型 timeout: 30 # 单次推理超时（秒） review: context: "default" # 默认上下文，可被 --context 覆盖 level: "medium" # 检查粒度：low/medium/high

这里的关键点在于model.provider。open-code-review 支持四种后端：

• ollama：本地运行，零网络依赖，推荐用于敏感项目；
• llama.cpp：CPU 推理，内存占用更低，适合笔记本；
• openai：调用 OpenAI API，需设置OPENAI_API_KEY；
• anthropic：调用 Claude API，需设置ANTHROPIC_API_KEY。

我强烈建议首次使用选择ollama。它安装简单（brew install ollama），且deepseek-coder:6.7b模型在 16GB 内存的 M1 Mac 上，单次 diff 分析耗时稳定在 7~12 秒，准确率远超同等参数的 Llama-3-8B-Instruct。

步骤 3：运行首次审查

# 审查当前工作区所有未提交的变更 oclr review # 审查最近一次 commit 的变更 oclr review --commit HEAD~1 # 审查指定文件的变更 oclr review --files "src/auth/*.go"

首次运行会自动拉取deepseek-coder:6.7b模型（约 4.2GB），后续所有分析均离线完成。你不会看到任何“正在连接云端服务”的提示，只有终端里安静滚动的[✓] Analyzing src/auth/jwt.go...。

3.2 配置文件详解：如何让审查更懂你的业务

.oclr/config.yaml是项目的“审查宪法”，但真正的灵魂在.oclr/rules/目录下。open-code-review 不预设规则，它提供一套 DSL，让你用 YAML 描述业务逻辑约束。

规则文件结构示例（.oclr/rules/auth-rules.yaml）：

# 规则组标识，用于 --context=auth 时加载 context: "auth" # 规则列表 rules: # 规则 1：JWT token 解析必须校验 exp - id: "jwt-exp-check" description: "JWT token 解析后必须校验 exp 字段有效性" trigger: # 触发条件：函数调用或变量赋值 - pattern: "jwt\.Parse.*" - pattern: "token\.Claims.*" action: "check-jwt-exp" severity: "critical" # 仅在 auth 目录下生效 paths: - "src/auth/**" - "internal/auth/**" # 规则 2：refresh token 必须同步清除缓存 - id: "refresh-cache-sync" description: "生成新 refresh token 时，必须同步删除旧 token 的 Redis 缓存" trigger: - pattern: "redis\.Del.*refresh.*" action: "check-cache-sync" severity: "high" paths: - "src/auth/**"

这里的action不是自由文本，而是预定义的分析器 ID。check-jwt-exp对应一个内置的 Go 代码分析器，它会：

1. 定位jwt.Parse调用后的if err != nil分支；
2. 检查该分支内是否包含token.Claims.(jwt.MapClaims)["exp"]访问；
3. 若缺失，则触发 LLM Diff Analyzer，用自然语言询问：“这段错误处理是否遗漏了 exp 字段校验？请引用 jwt-go v5 文档说明。”

你可以随时添加自己的规则文件，只需保证文件名以.yaml结尾，且位于.oclr/rules/下。oclr review --context=auth会自动加载所有context: "auth"的规则。

实操心得：不要试图用规则覆盖所有场景。我们团队初期写了 47 条规则，结果误报率飙升。后来砍到 12 条核心业务规则（如“支付金额必须为正整数”、“用户手机号必须通过正则校验”），配合 LLM 的语义分析，准确率反而从 68% 提升到 92%。记住：规则是“锚点”，LLM 是“望远镜”，锚点越少越准，望远镜才能看得更远。

3.3 CLI 参数实战：从日常开发到 CI 流水线的精准控制

oclr review的参数设计，完全围绕 Git 工作流的真实痛点。以下是我在不同场景下的高频用法：

场景 1：Pre-commit Hook —— 在代码提交前拦截

# 编辑 .git/hooks/pre-commit #!/bin/bash echo "Running open-code-review pre-commit check..." if ! oclr review --level=high --quiet; then echo "❌ open-code-review found critical issues. Please fix before committing." exit 1 fi

--quiet参数会抑制详细日志，只在发现问题时输出错误报告。它不会打断你的提交节奏，但会在关键时刻拉住你。

场景 2：CI 流水线 —— 为不同分支设定不同严格度

# .gitlab-ci.yml stages: - review code-review: stage: review image: alpine:latest before_script: - apk add curl && curl -fsSL https://get.oclr.dev/linux-amd64 -o oclr && chmod +x oclr script: # 主干分支：最高严格度 - if [[ "$CI_COMMIT_BRANCH" == "main" || "$CI_COMMIT_BRANCH" == "develop" ]]; then oclr review --context=core --level=high --fail-on=critical; fi # 特性分支：中等严格度，只报 high 及以上 - if [[ "$CI_COMMIT_BRANCH" =~ ^feature/ ]]; then oclr review --context=feature --level=medium --fail-on=high; fi

场景 3：快速定位历史问题 —— 用 git blame 追溯

# 发现线上 bug，想查是哪次提交引入的？ # 先用 git blame 定位可疑行 git blame -L 45,45 src/auth/jwt.go # 输出：a1b2c3d4 (Alice 2024-05-20 10:23:45 +0800 45) token, err := jwt.Parse(tokenStr, keyFunc) # 再用 oclr 审查那次提交 oclr review --commit a1b2c3d4 --context=auth

它会重建那次提交的完整上下文，包括当时的依赖版本、相关测试用例，甚至会提示：“本次变更移除了对jwt-go v4的VerifyExp调用，但未适配v5的token.Valid方法”。

关键参数速查表：

4. 实操过程与核心环节实现：一次真实 PR 审查的完整复盘

4.1 案例背景：一个看似简单的登录接口变更

我们以一个真实的 PR 为例：前端同学提交了一个 PR，标题是“修复登录接口 401 错误返回体不一致”。变更内容非常简单，只有 3 行：

--- a/src/api/auth/login.go +++ b/src/api/auth/login.go @@ -23,7 +23,7 @@ func LoginHandler(c *gin.Context) { return } - if !user.IsActive { + if !user.IsActive || user.IsLocked { c.JSON(http.StatusUnauthorized, gin.H{"error": "account_inactive"}) return }

表面看，这只是增加了一个|| user.IsLocked判断。但正是这种“微小变更”，最容易埋下线上隐患。让我们用 open-code-review 走一遍全流程。

步骤 1：本地快速扫描

# 在 PR 分支上执行 oclr review --files "src/api/auth/login.go" --context=auth --level=high

输出摘要：

[✓] Loaded context 'auth' (3 rules) [✓] Analyzing src/api/auth/login.go... [!] CRITICAL: jwt-exp-check - Location: login.go:26 - Description: JWT token parsing lacks exp field validation. This may allow expired tokens to be accepted. - Suggestion: Add token.Claims.(jwt.MapClaims)["exp"] check before returning success. [!] HIGH: refresh-cache-sync - Location: login.go:26 - Description: User lock status change does not trigger refresh token cache invalidation. - Suggestion: Call redis.Del("refresh:" + user.ID) when user.IsLocked becomes true.

注意，它没有停留在“你加了|| user.IsLocked”这个表层，而是穿透到了两个深层影响：

• 安全影响：login.go:26这行代码，是整个认证流程的入口。它调用的jwt.Parse函数，其返回的token对象，后续并未校验exp字段。LLM Diff Analyzer 通过比对jwt-go文档，确认这是高危漏洞。
• 一致性影响：当user.IsLocked为真时，用户无法登录，但其旧的 refresh token 仍在 Redis 中有效。这违反了“账号锁定即全面失效”的业务契约。

步骤 2：深入分析报告生成原理

为什么oclr能发现这两个问题？我们拆解它的内部流水线：

1. Diff 解析层：git diff输出被解析为结构化对象：

   { "file": "src/api/auth/login.go", "hunk": { "start": 23, "lines": [ {"type": "context", "content": " if !user.IsActive {"}, {"type": "remove", "content": " if !user.IsActive {"}, {"type": "add", "content": " if !user.IsActive || user.IsLocked {"} ] } }

2. Context 注入层：oclr读取go.mod，确认项目使用github.com/golang-jwt/jwt/v5；读取git log -n 1 --oneline src/auth/jwt.go，发现该文件最近一次修改是 3 天前，引入了v5升级。

3. Rule 匹配层：auth-rules.yaml中的jwt-exp-check规则，其trigger.pattern匹配到login.go中jwt.Parse的调用（虽在其他文件，但被import引入），于是触发check-jwt-exp分析器。

4. LLM Diff Analyzer 层：它构造如下 prompt：

   You are a senior Go security engineer reviewing a code change. Context: - Project uses github.com/golang-jwt/jwt/v5 - The jwt.Parse call is at login.go:25 - Current code after change: if !user.IsActive || user.IsLocked { ... } - The error response is "account_inactive" Question: Does the current error handling logic validate the JWT token's expiration time (exp claim)? If not, explain the security risk and cite the official jwt-go v5 documentation.

   模型返回结构化 JSON：

   { "issue_id": "jwt-exp-check", "severity": "critical", "location": {"file": "login.go", "line": 26}, "description": "JWT token parsing lacks exp field validation...", "references": ["https://github.com/golang-jwt/jwt/blob/main/README.md#validating-tokens"] }

步骤 3：修复与验证

开发同学根据报告，做了两处修改：

// src/api/auth/login.go func LoginHandler(c *gin.Context) { // ... token parsing ... if token == nil || !token.Valid { c.JSON(http.StatusUnauthorized, gin.H{"error": "invalid_token"}) return } // 新增：显式校验 exp if exp, ok := token.Claims.(jwt.MapClaims)["exp"]; !ok || int64(exp.(float64)) < time.Now().Unix() { c.JSON(http.StatusUnauthorized, gin.H{"error": "token_expired"}) return } if !user.IsActive || user.IsLocked { // 新增：清除 refresh token 缓存 redisClient.Del(context.Background(), "refresh:"+user.ID) c.JSON(http.StatusUnauthorized, gin.H{"error": "account_inactive"}) return } }

再次运行oclr review，报告清零。更重要的是，这次修改被自动记录在.oclr/history/目录下，形成可追溯的“审查决策日志”。

4.2 模型选型实测：DeepSeek-Coder vs. CodeLlama vs. Phi-3

模型是 open-code-review 的“大脑”，选错模型，再好的架构也白搭。我在 M1 Max（32GB RAM）上实测了三款主流开源代码模型：

关键发现：

• phi3:3.8b速度快，但对jwt-go v5的文档引用完全错误，它坚称Valid()方法已废弃，导致给出错误建议。
• codellama:7b表现均衡，但对“refresh token 缓存同步”这类跨模块逻辑，常混淆redis.Del和redis.Set的语义。
• deepseek-coder:6.7b在代码领域微调充分，对 Go 生态的熟悉度远超其他模型。它能准确区分jwt-go v4的VerifyExp和v5的token.Valid，也能理解redis.Del在账号锁定场景下的业务含义。

因此，oclr init默认选用deepseek-coder:6.7b不是偶然。它在速度、精度、生态适配三者间取得了最佳平衡。如果你的机器内存不足 12GB，可以降级到phi3:3.8b，但务必关闭--level=high，只用--level=medium，避免它在深度嵌套分析中产生幻觉。

5. 常见问题与排查技巧实录：那些文档里不会写的坑

5.1 “oclr review 无输出，但 exit code 是 0” —— 你以为它在工作，其实它在休眠

这是新手遇到最多的问题。你敲下命令，光标闪了几秒，然后直接回到$提示符，什么都没打印。你怀疑安装失败，反复重装，甚至以为是网络问题。

真相：oclr默认启用“智能静默模式”。它只在检测到问题时才输出报告；如果没有发现任何 issue，它就安静地退出，exit code 为 0（表示成功）。

验证方法：

# 强制输出所有日志，包括 INFO 级别 oclr review --verbose # 或者，故意制造一个明显问题 echo "fmt.Println('hello')" >> test.go oclr review --files test.go --verbose

如果--verbose下依然无输出，那才是真问题。此时检查：

• 是否在 Git 仓库根目录下？oclr依赖.git目录，非 Git 项目会静默失败。
• .oclr/config.yaml是否存在且格式正确？YAML 缩进错误会导致解析失败，oclr会默默回退到默认配置（可能不加载任何规则）。

实操心得：在 CI 脚本中，永远不要用oclr review的 stdout 判断结果。正确做法是检查 exit code：

if oclr review --fail-on=high; then echo "✅ Review passed" else echo "❌ Review failed with high/critical issues" exit 1 fi

5.2 “模型加载失败：failed to start. unable to locate the codex cli binary” —— 名字混淆引发的血案

搜索热词里频繁出现codex cli、chatgpt failed to start. unable to locate the codex cli binary，这其实是严重的命名污染。open-code-review和codex-cli（微软早期开源的 VS Code 插件 CLI）毫无关系。前者是独立项目，后者早已归档。

当你看到这个错误，99% 的原因是：

• 你机器上曾经安装过codex-cli，它的二进制文件名为codex，被PATH环境变量优先找到；
• oclr的某些旧版本（< v0.7.0）在查找本地模型时，错误地尝试调用codex命令，导致失败。

解决方案：

1. 彻底卸载codex-cli（如果还存在）：

   which codex # 查看位置 rm $(which codex) # 删除二进制

2. 升级oclr到最新版：

   curl -fsSL https://get.oclr.dev/latest -o oclr && chmod +x oclr && sudo mv oclr /usr/local/bin/

3. 如果必须共存，用绝对路径调用：

   /usr/local/bin/oclr review

注意：oclr从不调用codex、claude、gemini等任何第三方 CLI。它只调用自己内置的模型运行时（Ollama/llama.cpp）或标准 HTTP API。所有“找不到 xxx cli”的报错，都是环境残留或版本过旧所致。

5.3 “审查结果不稳定：同一次 diff，两次运行结果不同” —— LLM 的随机性陷阱

LLM 的temperature参数决定了输出的随机性。oclr默认将temperature设为0.3，以平衡准确性和创造性。但这会导致一个问题：对同一份 diff，连续运行两次，可能第一次报CRITICAL，第二次只报HIGH。

根本原因：oclr的 LLM 分析器，在生成最终报告前，会进行多次采样（n=3），然后对结果做 majority voting。但如果三次采样结果分歧太大（比如 2:1），它会采纳多数意见，但也会记录 minority opinion 作为suggestion。

解决方法：

• 生产环境：永远使用--temperature=0。这会让模型进入“确定性模式”，输出完全可重现。

  oclr review --temperature=0

• 调试环境：开启--debug，查看每次采样的原始输出：

  oclr review --debug --files login.go # 输出会包含 3 次 LLM 调用的完整 prompt 和 response

终极建议：在 CI 流水线中，--temperature=0是强制要求。审查结果必须是可重现、可审计的，不能依赖“运气”。

5.4 “规则不生效：我写了规则，但 oclr review 就是不触发” —— 路径匹配的隐形战争

规则文件写得再漂亮，如果paths匹配不上，它就是一张废纸。oclr的路径匹配遵循filepath.Glob规则，但有几个极易踩的坑：

• 坑 1：相对路径基准是.oclr/目录，不是项目根目录

  # 错误！.oclr/rules/auth.yaml 中的 paths 是相对于 .oclr/ 的 paths: - "../src/auth/**" # ❌ 这会去 .oclr/ 上级目录找 # 正确！paths 是相对于项目根目录的 - "src/auth/**" # ✅

• 坑 2：**通配符不跨目录边界

  # 想匹配 src/auth/handler/login.go 和 src/auth/service/user.go paths: - "src/auth/**" # ✅ 正确 - "src/**/auth/**" # ❌ 这会匹配 src/foo/auth/bar.go，但不匹配 src/auth/...

• 坑 3：Git 忽略文件会被自动跳过如果你的login.go在.gitignore里，oclr review根本不会分析它，无论规则怎么写。因为oclr只分析git status显示为modified或added的文件。

快速诊断命令：

# 查看 oclr 实际分析了哪些文件 oclr review --verbose