企业官网建设流程全解析

1. 项目概述：这不是一个工具，而是一套可落地的开源代码评审实践体系

“open-code-review”这个词乍看像某个GitHub仓库名，或是某款新发布的CLI工具，但实际它代表的是一种正在快速演化的工程实践范式——把代码评审（Code Review）这件事，从传统意义上由资深工程师人工完成的、高成本、低频次、强主观性的“质量守门”动作，转变为一种可编程、可复用、可嵌入开发流程的开放协作机制。它不是单纯地把GitHub PR评论框换成AI对话框，而是重构了评审的发起逻辑、参与角色、反馈粒度和知识沉淀路径。我过去三年在三个不同规模的技术团队里推动过类似实践，最深的体会是：真正卡住团队交付节奏的，从来不是写不出代码，而是代码写出来之后，没人愿意看、看不懂、不敢批、批不准。而open-code-review要解决的，正是这个“评审真空带”。

核心关键词“open-code-review”背后藏着三层含义：第一层是开放性——评审规则、检查清单、反馈模板全部对外可见，新人能快速理解“什么样的代码算好”，老手能基于已有规则做增量优化；第二层是可编程性——评审逻辑不再依赖个人经验，而是以YAML规则、正则表达式、AST遍历脚本、LLM提示词模板等形式固化下来，能被CI/CD自动调用，也能被开发者本地CLI一键触发；第三层是可协作性——评审结果不是单向输出，而是结构化数据，能自动同步到Jira任务、飞书多维表格、甚至生成团队技术债看板。你不需要等PR合并后才看到问题，而是在git commit后就能拿到一份带行号标注、引用规范条款、附带修复建议的PDF格式评审报告。它不取代人，但让人的注意力聚焦在真正需要判断的业务逻辑和架构权衡上，而不是反复核对空指针、命名风格或日志埋点是否遗漏。

这个实践特别适合三类人：一是中小团队的Tech Lead，想统一代码质量但没人力做逐行Review；二是外包或跨团队协作项目，需要明确、可验证的质量契约；三是正在搭建DevOps流水线的SRE同学，希望把质量左移做到极致。它不是给“AI写代码”配的装饰品，而是给“人写代码”配的基础设施。接下来我会从设计思路、核心模块、实操步骤和真实踩坑记录四个维度，带你把这套体系从概念变成你团队明天就能跑起来的流水线。

2. 整体设计思路：为什么必须放弃“AI自动审代码”的幻想

很多人第一次接触open-code-review，第一反应是：“是不是找个大模型API，把diff丢进去，让它吐几句评语？”我试过，也见过太多团队踩进这个坑——花两周接入Claude API，结果产出的评论90%是废话：“这段代码逻辑清晰”、“变量命名合理”，或者更糟：“建议增加日志”，却没说清该在哪加、加什么内容、为什么加。这不是AI的问题，而是对评审本质的误判。真正的代码评审，从来不是“理解代码”，而是“验证意图”。它要回答三个问题：这段代码是否实现了需求文档里写的业务目标？它是否符合我们团队约定的架构约束（比如不允许跨域调用、必须走统一鉴权中间件）？它是否能在未来6个月被另一个工程师无痛维护？

所以open-code-review的设计起点，不是选哪个LLM模型，而是定义评审契约（Review Contract）。这个契约包含三部分：检查项（Checklist）、证据链（Evidence Chain）、决策树（Decision Tree）。检查项是静态规则，比如“所有HTTP请求必须设置5秒超时”、“数据库查询必须有分页限制”，这类规则用Shell脚本+grep就能100%覆盖；证据链是动态上下文，比如“当前PR修改了订单服务，而订单服务最近3个月出现过5次支付状态不一致故障，因此需重点检查状态机流转逻辑”，这部分需要结合Git历史、监控告警、线上日志聚合数据生成；决策树则是人机协同的临界点，比如当静态检查发现“未处理空指针风险”，LLM只需生成一句：“检测到UserService.findById()调用未判空，参考《Java健壮性规范》第3.2条，建议添加Optional.ofNullable()包装”，而是否采纳、如何修改，则由开发者在IDE里点击“应用建议”按钮完成，整个过程留痕可追溯。

这种设计带来的最大收益，是把评审从“主观意见”变成了“客观验证”。我上一家公司推行后，PR平均停留时间从42小时降到8.3小时，但关键缺陷检出率反而提升了37%。因为工程师不再纠结“张工觉得这里该用Stream，李工觉得for循环更直观”，而是直接看检查项：“是否满足《并发安全规范》第5条：集合操作必须使用线程安全容器”。规则即共识，共识即效率。下面我们就拆解这套体系的四大核心模块：规则引擎、上下文注入器、CLI驱动器和反馈归档器。

2.1 规则引擎：用YAML+AST替代“大模型猜题”

规则引擎是open-code-review的基石，它的核心任务是把模糊的“好代码”标准，翻译成机器可执行的布尔表达式。很多人以为这得写一堆Python AST解析器，其实大可不必。我们采用分层策略：L0基础层用Shell/grep/sed覆盖80%高频问题，L1语义层用Tree-sitter做精准AST匹配，L2智能层才用LLM做语义补全。

L0层规则示例（存于.review/rules/basic.yaml）：

- id: "java-null-check" language: "java" description: "方法返回值未进行null检查" pattern: ".*\\.get.*\\(.*\\)\\s*;?\\s*if\\s*\\(.*==\\s*null\\)" severity: "high" fix_hint: "使用Optional或Objects.requireNonNull()"

这条规则用正则匹配“调用get方法后紧跟null判断”的模式，命中即报高危。它不关心get方法内部逻辑，只验证“防御性编程”这一行为是否存在。实测在Spring Boot项目中，能捕获73%的NPE隐患，且零误报。

L1层规则示例（存于.review/rules/ast.yaml）：

- id: "spring-transaction-propagation" language: "java" ast_query: | (method_declaration (modifiers (annotation (name) @annotation-name)) (identifier) @method-name) (#eq? @annotation-name "Transactional") condition: | def has_propagation = node.children.find { it.type == 'annotation_argument' && it.text.contains('propagation') } !has_propagation severity: "critical" fix_hint: "Transactional注解必须显式指定propagation属性"

这里用Tree-sitter的S-expression语法，精准定位@Transactional注解节点，再检查其参数列表是否包含propagation。相比正则，它能穿透代码格式变化（换行、空格、注释），准确率接近100%。

L2层规则才是LLM的用武之地，但它只处理前两层无法覆盖的场景。比如“这个Service方法是否违反了单一职责原则？”——这需要理解业务语义。我们的做法是：先用L0/L1规则提取出方法签名、调用的外部服务列表、SQL查询数量、DTO字段数等结构化特征，再把这些特征拼成提示词喂给LLM：

请基于以下代码特征，判断是否违反单一职责原则（SRP）： - 方法名：processOrderPayment - 调用外部服务：3个（支付网关、库存服务、短信平台） - 执行SQL：2条（更新订单状态、插入支付流水） - DTO字段数：12个 - 是否包含业务规则判断：是（优惠券校验、风控拦截、余额扣减） 请用“是/否”回答，并给出不超过20字的理由。

注意，这里LLM只做二分类+极简理由，不生成代码、不提建议。因为SRP判断本身就有争议，我们的目标是暴露分歧点，而非替代决策。实测用Qwen2-7B本地部署，准确率稳定在82%，但更重要的是，它把原本需要30分钟的架构讨论，压缩成5分钟的确认对话。

提示：不要试图用LLM覆盖所有规则。我们统计过，超过65%的代码缺陷，用L0层Shell脚本能10秒内搞定。把LLM当成“最后一位专家”，而不是“第一位实习生”。

2.2 上下文注入器：让评审知道“为什么这条规则在此刻特别重要”

没有上下文的规则是冰冷的教条。同样的“空指针检查”规则，在用户中心模块触发是常规提醒，在支付回调模块触发就是紧急阻断。上下文注入器的作用，就是为每条规则动态附加“时空坐标”，让评审结论具备情境感知能力。

我们构建了三层上下文源：代码层、变更层、环境层。代码层最简单，就是当前文件的AST节点、所在包路径、继承关系；变更层来自Git元数据，比如git log -n 5 --oneline --grep="payment"能获取最近5次支付相关提交，从而识别出“这是支付链路第3次重构”；环境层则对接公司内部系统，比如从监控平台API拉取“过去24小时订单服务P99延迟突增200ms”，或从CI系统读取“该分支最近3次构建失败均因数据库连接池耗尽”。

这些数据最终汇聚成一个JSON上下文对象，注入到LLM提示词中：

{ "rule_id": "java-db-connection-pool", "file_path": "order-service/src/main/java/com/company/order/OrderService.java", "git_context": { "recent_commits": ["feat(payment): add retry logic", "refactor(payment): split payment handler"], "branch_name": "release/v2.3-payment-stability" }, "env_context": { "monitoring_alerts": ["DB connection pool usage > 95% for 15min"], "ci_failures": ["Build #452 failed: java.sql.SQLTimeoutException"] } }

有了这个，LLM的反馈就不再是泛泛而谈：“建议优化数据库连接”。而是：“检测到订单服务连接池持续高负载（>95%），且当前PR新增了3处数据库调用。根据《高并发服务规范》第7.1条，必须为新调用配置独立连接池或启用连接复用。否则将加剧现有瓶颈。”——这才是工程师真正需要的 actionable feedback。

实操中，我们用一个轻量级Go服务（context-injector）统一管理这些数据源。它不存储数据，只做实时聚合和权限过滤。比如飞书机器人调用它时，会自动剥离敏感监控指标，只返回脱敏后的告警摘要。这点很重要：评审系统必须遵守最小权限原则，避免成为新的安全入口。

2.3 CLI驱动器：把评审变成git commit后的一键动作

CLI是open-code-review的“最后一公里”。它必须足够轻量（单二进制文件）、足够快（10秒内完成全量检查）、足够傻瓜（review --fix就能自动修复80%的格式问题）。我们放弃Node.js或Python方案，选择Rust编写，最终编译出的oc-review二进制仅12MB，启动时间<100ms。

CLI的核心命令只有三个：

• oc-review check：执行全量规则扫描，输出Markdown格式报告，支持--format=html生成网页版
• oc-review diff：只扫描当前Git暂存区变更，适合Pre-commit Hook
• oc-review fix：自动修复L0/L1层可修复问题（如导入排序、空行删除、TODO标记清理）

关键设计在于增量计算。首次运行时，CLI会为每个规则生成一个“指纹文件”（.review/fingerprints/<rule-id>.sha256），记录该规则上次扫描的代码哈希。下次运行时，只重新计算指纹变化的文件，其余直接复用缓存结果。在万行级项目中，check命令从47秒降至6.2秒。

Pre-commit Hook配置示例（.pre-commit-config.yaml）：

- repo: local hooks: - id: open-code-review name: Open Code Review entry: oc-review diff --fail-on-high language: system types: [java, python, javascript] pass_filenames: false

这里--fail-on-high是关键开关：当检测到高危（high/critical）问题时，Hook直接中断提交，强制开发者修复。我们发现，这个简单策略让NPE类缺陷在开发阶段拦截率提升至94%，远高于CI阶段的61%。

注意：CLI必须与IDE深度集成。我们在VS Code插件里实现了oc-review的实时诊断功能——当你在编辑器里修改一行代码，左侧 gutter 就会实时显示该行触发的规则ID（如java-null-check），悬停即可查看规则详情和修复示例。这种“所见即所得”的体验，比PR评论框里的滞后反馈有效10倍。

2.4 反馈归档器：让每次评审都变成团队知识资产

传统评审的最大浪费，是评论随PR关闭而消失。open-code-review的反馈归档器，要把每一次评审结论，转化为可检索、可关联、可演进的知识单元。

我们采用“三元组归档法”：[代码片段Hash] + [规则ID] + [上下文快照]。当oc-review check生成报告时，归档器会：

1. 对报告中每个问题定位的代码行，计算SHA256哈希（如a1b2c3d4...）
2. 关联触发的规则ID（如java-db-connection-pool）
3. 保存当时的Git Commit ID和上下文JSON（脱敏后）

这些三元组存入一个轻量级SQLite数据库（.review/archive.db），并提供CLI查询接口：

# 查找所有关于“数据库连接池”的历史问题 oc-review archive search --rule "java-db-connection-pool" # 查找某段代码（通过哈希）在过去3个月被多少次规则命中 oc-review archive search --hash "a1b2c3d4..." --since "3 months ago"

更进一步，我们把归档数据同步到飞书多维表格，自动生成“团队技术债看板”：X轴是规则ID（按严重等级分组），Y轴是模块名，单元格数字表示该模块触发该规则的次数。运维同学一眼就能看出：“用户中心模块的空指针问题发生频率是订单模块的5倍”，从而精准投放培训资源。

这个设计的深层价值在于：它让“代码质量”从定性描述变为定量指标。新同学入职时，不再听主管说“我们重视代码质量”，而是直接打开看板，看到“支付模块NPE问题已连续3周清零”，这就是最有力的文化宣言。

3. 核心模块实现：从零开始搭建你的open-code-review流水线

现在我们进入实操环节。以下步骤基于Ubuntu 22.04 + Java 17 + Git 2.30+ 环境，所有工具均为开源且免License费用。整个过程控制在30分钟内，你可以边看边敲命令。

3.1 环境准备：安装核心依赖与初始化项目

首先确保基础工具链就位：

# 安装Tree-sitter CLI（用于AST解析） curl -fsSL https://github.com/tree-sitter/tree-sitter/releases/download/v0.22.4/tree-sitter-linux-x64.gz | gunzip > tree-sitter && chmod +x tree-sitter sudo mv tree-sitter /usr/local/bin/ # 安装jq（JSON处理必备） sudo apt-get install -y jq # 验证Git版本（需2.30+以支持稀疏检出） git --version

接着，为你的项目初始化open-code-review目录结构：

# 在项目根目录创建.review目录 mkdir -p .review/{rules,contexts,archive} # 初始化规则仓库（我们提供预置模板） curl -sL https://raw.githubusercontent.com/open-code-review/templates/main/basic-java.yaml \ -o .review/rules/basic.yaml curl -sL https://raw.githubusercontent.com/open-code-review/templates/main/ast-java.yaml \ -o .review/rules/ast.yaml # 创建CLI配置文件 cat > .review/config.yaml << 'EOF' --- language: "java" rules_dir: ".review/rules" archive_db: ".review/archive.db" context_sources: - type: "git" enabled: true - type: "monitoring" enabled: false # 生产环境再启用 api_url: "https://your-monitoring-api/v1/alerts" EOF

此时目录结构如下：

your-project/ ├── .review/ │ ├── config.yaml # 主配置 │ ├── rules/ │ │ ├── basic.yaml # L0层规则 │ │ └── ast.yaml # L1层规则 │ ├── contexts/ # 上下文缓存目录 │ └── archive.db # 归档数据库（首次运行自动生成）

实操心得：不要跳过tree-sitter安装。很多团队卡在AST解析这步，根源是没装对版本。我们测试过v0.20.x在Java 17项目中会解析失败，v0.22.4是目前最稳定的版本。

3.2 规则引擎实战：编写第一条可执行规则

我们以“禁止硬编码密码”为例，演示如何从零编写一条L0规则并验证效果。

在.review/rules/basic.yaml末尾添加：

- id: "no-hardcoded-password" language: "java" description: "代码中存在硬编码密码字符串" pattern: '["\'](?i:password|pwd|passwd)["\']\\s*[:=]\\s*["\'].*["\']' severity: "critical" fix_hint: "使用配置中心或环境变量注入密码"

这条规则用正则匹配形如"password": "123456"或pwd = 'abc'的赋值语句。注意(?i:)启用大小写不敏感，\\s*匹配任意空白符，确保能捕获换行和缩进。

现在创建一个测试文件src/test/java/TestPassword.java：

public class TestPassword { private static final String DB_PASSWORD = "my-secret-pwd"; // 应该被检测 private static final String API_KEY = "sk_live_abc123"; // 不应被检测（非密码关键词） }

执行检查：

oc-review check --file src/test/java/TestPassword.java

预期输出：

❌ CRITICAL: no-hardcoded-password File: src/test/java/TestPassword.java:2:38 Description: 代码中存在硬编码密码字符串 Fix hint: 使用配置中心或环境变量注入密码

验证成功！你会发现，API_KEY行没被报错，因为正则中的(?i:password|pwd|passwd)只匹配密码相关关键词。这就是规则引擎的价值：精准、可控、可解释。

常见问题：如果没输出，先检查oc-review是否在PATH中。我们的Rust CLI发布包里包含install.sh脚本，运行curl -sL https://github.com/open-code-review/cli/releases/download/v1.0.0/install.sh | bash即可全局安装。

3.3 CLI驱动器集成：配置Pre-commit Hook实现提交即审

Pre-commit Hook是让open-code-review真正落地的关键。我们采用pre-commit框架（Python生态最成熟的Hook管理器），因为它支持跨语言、易调试、社区活跃。

安装pre-commit：

pip3 install pre-commit

创建.pre-commit-config.yaml：

repos: - repo: https://github.com/pre-commit/pre-commit-hooks rev: v4.4.0 hooks: - id: trailing-whitespace - id: end-of-file-fixer - repo: local hooks: - id: open-code-review name: Open Code Review entry: oc-review diff --fail-on-critical language: system types: [java] pass_filenames: false

关键点解析：

• --fail-on-critical：只对critical级别问题中断提交，避免开发体验受损
• types: [java]：限定只在Java文件变更时触发，防止误伤前端代码
• pass_filenames: false：让CLI自己决定扫描范围（基于git diff），而非传入文件名列表

初始化Hook：

pre-commit install

现在尝试提交一个含硬编码密码的文件：

git add src/test/java/TestPassword.java git commit -m "test: add password test"

你会看到：

Open Code Review.......................................................Failed - hook id: open-code-review - exit code: 1 ❌ CRITICAL: no-hardcoded-password File: src/test/java/TestPassword.java:2:38 Description: 代码中存在硬编码密码字符串 Fix hint: 使用配置中心或环境变量注入密码

提交被拒绝！开发者必须先修复问题才能继续。这就是“质量门禁”的威力。

实操心得：首次部署时，建议先用--fail-on-high（而非critical），给团队适应期。我们观察到，2周后团队对high级别问题的修复率就达到90%，此时再升级到critical，阻力会小很多。

3.4 上下文注入器对接：让评审知道“这次为什么特别重要”

上下文注入器的最小可行版本，只需对接Git元数据。我们用Shell脚本实现，无需额外服务。

创建.review/scripts/context-git.sh：

#!/bin/bash # 生成Git上下文JSON echo "{" echo " \"recent_commits\": [$(git log -n 3 --pretty=format:'\"%s\"' --grep="$1" | jq -s '.')]," echo " \"branch_name\": \"$(git branch --show-current)\"," echo " \"commit_count\": $(git rev-list --count HEAD)" echo "}"

在.review/config.yaml中启用Git上下文：

context_sources: - type: "git" enabled: true script: ".review/scripts/context-git.sh"

现在修改规则，加入上下文判断。编辑.review/rules/basic.yaml，找到no-hardcoded-password规则，添加context_condition：

- id: "no-hardcoded-password" # ... 其他字段保持不变 ... context_condition: | if [[ "$(jq -r '.branch_name' "$CONTEXT_FILE")" == "main" ]]; then echo "critical" else echo "high" fi

这个条件的意思是：只有在main分支提交时，硬编码密码才标为critical；其他分支（如feature/*）降级为high，允许开发者先提交再修复。

验证效果：

# 切换到main分支 git checkout main # 再次提交TestPassword.java git commit -m "test: hardcode pwd on main" # 此时会因critical级别被拒绝 # 切换到feature分支 git checkout -b feature/test-context git commit -m "test: hardcode pwd on feature" # 此时只报high级别，提交成功

你看到了吗？评审结论不再是静态的，而是随分支策略动态调整。这才是真正的“情境感知”。

注意：生产环境中，你会把context-git.sh升级为Go服务，对接Jira、飞书、监控API。但原理完全一致：用结构化数据替换模糊的“我觉得这里有问题”。

3.5 反馈归档器启用：把每次评审变成可追溯的知识

归档器的启用只需一行命令。首次运行oc-review check时，它会自动创建SQLite数据库：

oc-review check --file src/test/java/TestPassword.java

查看归档内容：

# 查询所有归档记录 sqlite3 .review/archive.db "SELECT rule_id, code_hash, created_at FROM reviews ORDER BY created_at DESC LIMIT 5;"

你会看到类似输出：

no-hardcoded-password|a1b2c3d4e5f6...|2024-06-15 10:23:45

现在，我们用归档数据生成团队看板。创建一个简单的HTML报告生成脚本.review/scripts/gen-report.sh：

#!/bin/bash # 生成Markdown格式的周报 echo "# 📊 Open Code Review 周报" echo "" echo "## 🚨 高危问题 Top 3" sqlite3 -line .review/archive.db " SELECT rule_id, COUNT(*) as cnt FROM reviews WHERE created_at >= datetime('now', '-7 days') GROUP BY rule_id ORDER BY cnt DESC LIMIT 3; " | sed 's/|/ /g' echo "" echo "## 📈 模块问题分布" sqlite3 -line .review/archive.db " SELECT SUBSTR(file_path, 1, INSTR(file_path, '/')-1) as module, COUNT(*) as cnt FROM reviews WHERE created_at >= datetime('now', '-7 days') GROUP BY module; " | sed 's/|/ /g'

运行它：

chmod +x .review/scripts/gen-report.sh ./.review/scripts/gen-report.sh > weekly-report.md

这份报告可以自动发送到飞书群，让所有人看到：“本周order-service模块的java-null-check问题最多（12次），建议下周安排专项培训”。知识就这样沉淀下来了。

4. 常见问题与排查技巧实录：那些官方文档不会告诉你的坑

在20+个团队落地open-code-review的过程中，我们整理出一份“血泪清单”。这些问题看似琐碎，却能让整个体系瘫痪。下面按发生频率排序，附带真实排查路径和解决方案。

4.1 问题：oc-review diff在CI环境中总是超时，本地却正常

现象：在GitLab CI的ubuntu-latestrunner上，oc-review diff命令执行超过10分钟被kill，但本地MacBook Pro上只要3秒。

排查路径：

1. 首先确认CI环境是否安装了tree-sitter：tree-sitter --version→ 报错“command not found”
2. 检查CI镜像：docker images ubuntu:latest→ 发现是ubuntu:24.04，而我们的tree-sitter二进制是为22.04编译的
3. 运行ldd $(which tree-sitter)→ 显示libc.so.6 => not found，证实glibc版本不兼容

解决方案：

• 方案A（推荐）：在CI脚本中动态下载对应版本

  before_script: - curl -fsSL https://github.com/tree-sitter/tree-sitter/releases/download/v0.22.4/tree-sitter-linux-x64.gz | gunzip > tree-sitter && chmod +x tree-sitter - sudo mv tree-sitter /usr/local/bin/

• 方案B：改用Docker镜像open-code-review/base:22.04，预装所有依赖

实操心得：永远不要假设CI环境和本地一致。我们后来在.review/config.yaml里加了一条ci_mode: true，开启后CLI会自动跳过某些耗时的AST解析，改用更轻量的正则方案，牺牲一点精度换取稳定性。

4.2 问题：LLM提示词中注入的上下文JSON被截断，导致模型“看不懂”

现象：当监控告警数据很长时（如包含100行堆栈跟踪），LLM返回{"error": "context too long"}，而不是预期的评审结论。

根本原因：我们使用的Qwen2-7B模型，上下文窗口为32K tokens，但JSON序列化后，单个告警的堆栈跟踪就占28K tokens，留给代码分析的空间只剩4K。

解决方案：

• 前置压缩：在注入前，用Python脚本对JSON做智能裁剪

  import json from llm_context_compressor import compress_alert with open("context.json") as f: ctx = json.load(f) # 只保留告警的summary、severity、top3_service_names compressed = compress_alert(ctx["monitoring_alerts"][0]) ctx["monitoring_alerts"] = [compressed]

• 动态分片：当总token数>25K时，CLI自动将上下文拆分为多个请求，分别处理“规则验证”和“语义分析”两个子任务

我们把这个压缩逻辑封装进context-injector服务，开发者完全无感。关键是：永远假设LLM的输入是受限的，而不是去换更大的模型。

4.3 问题：Pre-commit Hook在Windows上失效，报错'oc-review' is not recognized

现象：Windows开发者执行git commit时，Hook报错找不到oc-review，尽管已通过install.sh安装。

原因分析：

• install.sh默认将二进制放到/usr/local/bin/，而Windows的PATH不包含此路径
• Windows的Git Bash默认不加载/etc/profile，导致PATH未更新

终极解决方案：

1. 在Windows上，改用Chocolatey安装：

   choco install open-code-review

2. 或手动将oc-review.exe放入项目根目录，并修改.pre-commit-config.yaml：

   - id: open-code-review entry: ./oc-review.exe diff --fail-on-critical # ... 其他配置

注意：我们后来在CLI里加了oc-review self-install命令，它会自动检测OS类型，选择最优安装路径。这是团队协作的底线——不能要求每个成员都是系统管理员。

4.4 问题：归档数据库.review/archive.db越来越大，查询变慢

现象：运行半年后，archive.db达2GB，oc-review archive search命令从0.2秒升至8秒。

优化措施：

• 自动分区：CLI每月自动创建新表reviews_2024_06，旧表设为只读
• 索引优化：为高频查询字段添加复合索引

  CREATE INDEX idx_rule_time ON reviews(rule_id, created_at); CREATE INDEX idx_hash_rule ON reviews(code_hash, rule_id);

• 冷数据归档：用oc-review archive prune --older-than "6 months"定期清理

执行后，查询速度恢复至0.3秒。关键认知：数据库不是黑盒，它是评审体系的“记忆器官”，需要定期体检。

4.5 问题：飞书机器人收到评审报告，但链接指向404

现象：飞书消息里的“查看详情”按钮，点击后跳转到https://your-domain.com/reports/abc123.html，返回404。

根因：oc-review check --format=html生成的HTML报告，默认存放在.review/reports/目录，而Web服务器未配置此路径的静态文件服务。

三步解决：

1. 在Nginx配置中添加：

   location /reports/ { alias /path/to/your/project/.review/reports/; autoindex off; }

2. CLI增加--report-url参数，生成绝对URL：

   oc-review check --format=html --report-url "https://your-domain.com/reports/"

3. 飞书机器人发送消息时，拼接完整URL

实操心得：所有外部集成点（飞书、Jira、GitLab），都要遵循“URL即服务”的原则。不要让接收方去猜路径。

5. 工具选型深度解析：为什么我们不用Codex CLI、Claude CLI或VS Code Gemini Companion

网络热词里频繁出现的codex-cli、claude-cli、vs-code-gemini-companion，本质上都是“LLM Wrapper”——把大模型API封装成命令行工具。它们能做什么？回答技术问题、生成代码片段、解释错误日志。但它们无法构建open-code-review所需的规则引擎、上下文注入和反馈归档。下面用一张表对比核心能力：

举个具体例子：你想让评审系统检查“所有Redis操作必须设置超时”，用Codex CLI怎么做？你只能写一个Prompt：“请检查以下Java代码是否有Redis操作未设置超时”，然后把整个文件丢给它。它可能漏掉jedis.set("key", "val")这种无参调用，也可能把redisTemplate.opsForValue().set("k","v",10, TimeUnit.SECONDS)误判为未超时。而open-code-review的AST规则，能精准匹配Jedis.set()方法调用，并验证其参数列表长度是否≥3（第三个参数是timeout），准确率100%。

再看trae-cli（新兴的AI编程助手），它主打“CLI Anything”，即把自然语言转成命令。比如trae "find all files modified in last 24h"→find . -type f -mtime -1。这很酷，但它解决的是“命令行效率”，而非“代码质量保障”。open-code-review和trae-cli是互补关系：前者保证你写的代码正确，后者帮你