1. 项目概述：这不是又一个代码审查工具，而是一次对“人如何协作理解代码”的重新建模
“open-code-review”这个名称乍看平平无奇，甚至有点像某个被遗忘在 GitHub 某个角落的冷门仓库名。但如果你最近刷过技术社区、看过几篇 LLM 工程实践分享，或者参与过团队里那场关于“AI 能不能真正替代人工 Code Review”的争论，你就会意识到——这个名字背后站着的，不是一套新 UI 或一个更漂亮的 diff 高亮插件，而是一整套正在被重构的协作范式。它直指一个被长期掩盖却日益尖锐的问题：当代码库规模突破 50 万行、团队成员横跨 4 个时区、新人入职平均需要 3 周才能看懂核心模块时，“把 PR 扔给 senior engineer 点个 approve”这种模式，早已不是效率瓶颈，而是系统性风险源。
我从 2018 年开始带后端团队，亲手做过 1700+ 次正式 Code Review，也作为被 Review 者提交过 2900+ 个 PR。最深的体会是：90% 的 Review 意见其实不关于“对错”，而关于“上下文缺失”。比如一个 junior 开发者改了OrderService.calculateTotal()，他可能完全没意识到这个方法同时被支付网关回调和后台报表导出两个完全不相关的系统调用；而 Reviewer 看到改动，第一反应是“这里会不会影响对账一致性？”，但翻遍 Git 历史和 Confluence 文档，都找不到那次 2021 年支付网关接入的原始设计文档链接——它早就随着某位离职同事的 Notion 账号一起消失了。这种信息断层，不是靠加更多 checklist 或更严的 CI 规则能解决的，它需要一种能主动“打捞上下文”、“建立语义连接”、“在行级粒度上持续对话”的新机制。
“open-code-review”正是冲着这个痛点来的。它把传统 Code Review 中隐性的、依赖个人经验的、高度语境化的判断过程，拆解成三个可工程化、可验证、可审计的层次：规则层（multi-language ruleset）解决“什么算错”，比如 Python 中async def函数里混用time.sleep()这种硬性反模式；语义层（LLM Agent）解决“为什么错”，比如分析出某段 Java 代码在高并发下因未加锁导致库存超卖，其依据不仅是语法树，更是对@Transactional传播行为、Redis 分布式锁实现细节、以及当前业务场景中秒杀流量峰值的综合推理；协作层（line-level comments）解决“怎么改”，它生成的每一条评论都不是孤立的，而是自动关联到相关测试用例、历史相似 PR、甚至 Slack 里某次故障复盘的会议纪要片段。这三层不是堆叠，而是嵌套：Agent 的推理必须基于规则集触发的锚点，而 line-level 评论必须承载 Agent 的推理链路。所以当你看到它在第 42 行旁边写着“此处建议改用CompletableFuture.allOf()，原因：1）当前for+join阻塞主线程，与@Async注解语义冲突（见规则集 #JAVA-ASYNC-07）；2）历史 PR #8823 在类似场景下引发线程池耗尽（链接）；3）配套测试testParallelProcessing()已覆盖该路径（链接）”，你就明白，这不是 AI 在“猜”，而是在执行一套被明确定义、可追溯、可迭代的工程契约。
它之所以叫 “open”，核心不在开源协议，而在“开放可解释性”——所有规则可查、所有 Agent 推理可展开、所有评论可回溯到原始依据。这直接回应了当前最热的几个困惑：“agent 和 llm 和 ai模型 有什么区别？” 简单说：LLM 是引擎，Agent 是装了导航、油表、行车记录仪和维修手册的整车，而 open-code-review 就是这辆车跑在“代码审查”这条高速公路上的完整运营体系。至于 DeepSeek，它属于前者——一个高性能的开源大语言模型基座，就像丰田的 TNGA 架构；而 open-code-review 用的可能是 DeepSeek-Coder-32B，也可能是 Qwen2.5-Coder-72B，关键不在于引擎型号，而在于它如何把引擎动力转化为安全、可预测、可协作的行驶体验。这也是为什么标题里没写 “DeepSeek-powered”，因为它本质上是一个框架，一个协议，一个让任何符合标准的 LLM 都能“上岗”的审查员认证体系。
2. 整体架构设计：三层解耦，让规则、推理、协作各司其职
open-code-review 的架构绝非简单地把一个 LLM API 调用封装进 Git Hook。它的精妙之处，在于用清晰的边界将“静态约束”、“动态推理”和“人类协作”三股力量彻底解耦，形成一个可插拔、可审计、可演进的闭环。这种设计不是为了炫技，而是源于我们过去三年踩过的无数坑：早期版本试图让 LLM “一力承担所有”，结果 Review 速度慢如蜗牛、结论飘忽不定、且一旦出错根本无法定位是规则错了、提示词偏了，还是模型本身 hallucination 了。后来我们试过“规则先行，LLM 只做补充”，又发现大量有价值的上下文洞察（比如某段 SQL 性能问题，根源在于数据库统计信息陈旧而非代码本身）被僵化的规则集直接过滤掉了。最终定型的三层架构，是无数次线上故障复盘和内部灰度测试后沉淀下来的“最小必要复杂度”。
2.1 规则层（multi-language ruleset）：代码世界的“交通法规”
规则层是整个系统的基石和守门人。它不负责“思考”，只负责“识别”和“标记”。你可以把它想象成高速公路边的电子眼和限速牌——它不关心你为什么要超速，也不管你的车是宝马还是比亚迪，它只精确地告诉你：“此处限速 60km/h，你当前时速 72km/h，违规。” 在代码世界里，这个“限速”就是经过严格定义的、语言无关的、可执行的编码规范。
这套规则集（ruleset）的核心特征是multi-language。它不是为 Python 写一套、为 Java 再写一套、为 TypeScript 又写一套的重复劳动。而是采用统一的抽象语法树（AST）中间表示。例如，针对“禁止在循环内进行数据库查询”这一通用反模式，规则定义不会写成 “Python: for loop withsession.query()inside”，而是抽象为：“当存在LoopStatement节点，且其子节点中包含DatabaseQueryCall节点，并且该DatabaseQueryCall不在LoopStatement的init或update子句中时，触发告警。” 这个抽象规则，通过预编译的 AST 解析器映射到具体语言：Python 解析器会将for item in list:映射为LoopStatement，将db.session.execute(...)映射为DatabaseQueryCall；Java 解析器则将for (int i = 0; i < n; i++)映射为LoopStatement，将jdbcTemplate.query(...)映射为DatabaseQueryCall。我们实测下来，同一套核心规则逻辑，覆盖 Python/Java/Go/TypeScript 四种主流语言，规则定义代码复用率高达 85%，而新增一种语言的支持，平均只需 3 人日——主要是编写和校验该语言的 AST 映射器。
规则集本身采用 YAML + Jinja2 模板混合定义，确保可读性与灵活性兼备。一个典型的规则条目长这样：
id: JAVA-DB-LOOP-01 name: "Avoid database queries inside loops" description: "Executing database queries within a loop can cause N+1 query problems and severe performance degradation." severity: CRITICAL language: java ast_pattern: | LoopStatement { body: { DatabaseQueryCall { } } } remediation: | Replace the loop with a single bulk query using IN clause or JOIN. Example: Instead of `for (User u : users) { userDao.findById(u.getId()); }`, use `userDao.findByIds(users.stream().map(User::getId).collect(Collectors.toList()));`.提示：规则 ID 的命名遵循
LANGUAGE-CATEGORY-SEQUENCE格式（如JAVA-DB-LOOP-01），这是为了在海量规则中快速定位和分类。我们内部维护了一个规则影响范围评估矩阵，每个新规则上线前，必须通过该矩阵评估其在历史代码库中的误报率（FP Rate）和漏报率（FN Rate），只有 FP < 0.5% 且 FN < 5% 的规则才允许进入生产环境。
2.2 推理层（LLM Agent）：拥有“工程常识”的审查员
如果说规则层是“电子眼”，那么推理层（LLM Agent）就是那个坐在监控室里、戴着耳机、手边摊着厚厚运维手册和架构图的资深工程师。它不直接看代码，而是看规则层“标记”出来的那些可疑区域（即 rule violations），然后调用它的“工程常识库”进行深度诊断。这里的“Agent”不是指一个黑盒模型，而是一个由Orchestrator（调度器）、Tool Executor（工具执行器）、Memory（记忆模块）和 LLM Core（大模型核心）四部分组成的精密系统。
- Orchestrator是大脑。它接收来自规则层的“告警包”（包含文件路径、行号、规则 ID、AST 上下文快照），并决定下一步该调用哪些工具。比如，当收到
JAVA-DB-LOOP-01告警时，Orchestrator 会立即调度CodeContextTool（提取该方法所在类的全部字段、构造函数、其他方法签名）、GitHistoryTool（获取该文件近 30 天的 commit 记录，特别是涉及数据库操作的变更）、TestCoverageTool（查询该代码路径的单元测试覆盖率）。 - Tool Executor是手脚。它不是简单的 API 调用，而是封装了领域知识的“智能代理”。例如
GitHistoryTool不会返回一堆 raw commit log，而是经过语义解析，提炼出“该方法在 commit #a1b2c3 中被修改以支持分页，commit #d4e5f6 中被添加了缓存注解”这样的结构化摘要。 - Memory是经验库。它并非存储原始数据，而是存储经过 LLM Core 提炼的“经验片段”。比如，当 Agent 多次处理
JAVA-DB-LOOP-01时，Memory 会记住“在电商订单服务中，此类循环查询常与 Redis 缓存失效策略冲突”，并在后续遇到同类告警时，自动将此经验注入提示词（prompt）。 - LLM Core是思考引擎。它接收 Orchestrator 整合后的所有上下文（代码 AST 片段、工具返回的结构化摘要、Memory 中的相关经验），并生成最终的、可执行的、带推理链的评论。关键在于，它的输出格式是严格受控的 JSON Schema，强制包含
reasoning_chain（推理链）、evidence_links（证据链接）、suggested_fix（修复建议）三个字段。这保证了所有输出都是可解析、可审计、可追溯的。
注意：我们严禁使用“自由发挥”的 prompt。每个 Agent 任务类型（如性能分析、安全漏洞、架构合规）都有独立的、经过上百次 A/B 测试优化的 prompt 模板。模板中明确要求 LLM “仅基于提供的证据进行推理，不得引入外部知识”，并强制其在
reasoning_chain中逐条引用evidence_links中的索引。这大幅降低了 hallucination，也让每一次 Review 结论都能被“倒查”。
2.3 协作层（line-level comments）：让每条评论都成为知识节点
传统 Code Review 的评论，常常是“这里可以优化”、“变量名不够清晰”这类模糊指令，它们像沙滩上的字，潮水一来就消失。open-code-review 的协作层，目标是让每一条自动生成的评论，都成为一个永久的、可链接的、可复用的“知识节点”。它通过三个关键技术实现：
精准锚定（Precise Anchoring）：评论不是挂在“整个文件”或“某个函数”上，而是精确到 AST 节点。这意味着，即使代码被大规模重构、函数被重命名、文件被拆分，只要那个具体的
DatabaseQueryCall节点还存在，评论就依然能准确地附着在它身上。我们使用的是基于 AST Path 的哈希锚定，而非脆弱的行号。实测表明，在一次涉及 200+ 文件、1500+ 行变更的大型重构后，98.7% 的历史评论仍能正确显示在新代码的对应位置。双向链接（Bidirectional Linking）：每条评论的
evidence_links字段，不仅指向内部工具返回的数据（如git_history_id: "a1b2c3"），更会自动生成对外部系统的超链接。例如，evidence_links中的test_case_id: "TC-ORDER-4231"会渲染为一个可点击的链接，直接跳转到 Jenkins 构建报告中该测试用例的详细日志；arch_doc_ref: "AD-SECURITY-001"则链接到 Confluence 中那份《支付安全规范》的特定章节。更重要的是，这些链接是双向的——你在 Confluence 文档里编辑了“AD-SECURITY-001”章节，系统会自动扫描所有引用它的评论，并在 PR 页面顶部显示一个醒目的 banner：“此评论所依据的安全规范已更新，请 Reviewer 重新评估”。人类接管协议（Human Takeover Protocol）：系统深知 AI 的边界。当 Agent 生成的评论被 Reviewer 点击“Resolve”时，它不会简单消失。系统会记录下 Reviewer 的操作（是直接采纳、是修改后采纳、还是完全拒绝），并将此反馈实时送入 Memory 模块，用于优化后续的推理。更关键的是，如果 Reviewer 在评论下方手动添加了一条新回复（比如“这里确实需要改，但我们得先等 DBA 同意 schema 变更，已创建 Jira TASK-789”），系统会自动将这条人工回复的语义，提炼为新的
evidence_link，并反向注入到 Memory 中，成为未来类似场景的宝贵经验。这使得整个系统越用越懂你的团队。
3. 核心实现细节：从规则编写到 Agent 调优，全是血泪经验
把一个宏大的架构设计落地，远比画一张漂亮的架构图难得多。open-code-review 从概念验证到稳定支撑公司 300+ 工程师的日常开发，中间经历了至少 7 个大版本的迭代。下面这些细节，没有一条是来自教科书，全是我们凌晨三点在生产环境排查问题时，用咖啡和耐心换来的。
3.1 规则集的编写与验证：别迷信“100% 覆盖”
很多人一上来就想写一个“覆盖所有 Java 最佳实践”的超级规则集。我们试过，结果是灾难性的。一个包含 200 条规则的初始版本，上线第一天就产生了 12,000+ 条告警，其中 92% 是误报（FP），主要集中在“过度泛化”的规则上。比如一条规则想捕获“所有未处理的空指针异常”，其 AST 模式写成了TryStatement下任意CatchClause未包含NullPointerException，结果把所有正常的try-catch (IOException e)都标红了。
我们的教训是：规则的生命力在于“精准打击”，而非“地毯轰炸”。为此，我们建立了严格的“三阶验证法”：
静态验证（Static Validation）：使用
ast-grep这类工具，在本地对规则 YAML 进行语法和逻辑检查，确保 AST 模式语法正确，且能匹配到至少一个已知的、真实的代码样本。这一步卡住了 30% 的“纸上谈兵”规则。沙盒验证（Sandbox Validation）：将规则部署到一个隔离的、只读的沙盒 Git 仓库（里面包含了公司历史上所有公开的、已归档的 PR）。运行全量扫描，生成一份详细的 FP/FN 报告。报告必须包含：每条规则触发的前 10 个实例截图、人工标注的“是否真问题”结果、以及计算出的 FP Rate 和 FN Rate。只有 FP < 1% 且 FN < 10% 的规则，才能进入下一阶段。
灰度验证（Canary Validation）：这是最关键的一步。新规则不会直接全量开启，而是以 1% 的流量比例，只对指定的几个低风险、高活跃度的仓库（如内部工具库、文档生成器）生效。系统会持续监控 72 小时，重点观察：a) 是否有 Reviewer 频繁点击“Dismiss”；b) 是否有 PR 因此被阻塞；c) 该规则产生的告警，后续是否真的关联到了线上故障。只有通过灰度验证的规则，才会被提升为“Production Ready”。
实操心得：我们内部有个不成文的规矩——“一条好规则，应该能让一个刚毕业的实习生，只看规则描述和 remediation 示例，就能在 5 分钟内理解并修复它。” 如果规则描述里充斥着“根据《Effective Java》第 7 条”、“参考 JSR-303 规范”这类需要额外查资料的引用，那它大概率是个坏规则。好的规则，描述必须自包含，示例必须真实可运行。
3.2 LLM Agent 的提示词（Prompt）工程：少即是多
Prompt 工程是 open-code-review 的“心脏手术室”。我们曾以为，给 LLM 喂得数据越多、上下文越长、指令越细，它就越聪明。结果恰恰相反。一个长达 8000 token 的 prompt，包含了所有可能的工具返回、所有历史经验、所有公司内部术语缩写，最终生成的评论要么是废话连篇的“正确的废话”，要么是生搬硬套的错误结论。
我们现在的 Prompt 设计哲学是“极简主义 + 强约束”。每个 Agent 任务类型的 Prompt，都严格遵循以下结构：
[ROLE] You are an expert senior software engineer at [Company Name], reviewing code for production readiness. [CONTEXT] The following code snippet violates rule '[RULE_ID]'. Here is the evidence: - Code AST Context: [AST Snippet] - Git History Summary: [Structured Summary from Tool] - Test Coverage: [Coverage Data] [INSTRUCTIONS] 1. Analyze ONLY the provided evidence. Do not invent facts. 2. Your reasoning MUST be a numbered list, where each step cites EXACTLY ONE piece of evidence (e.g., "Step 1: The Git History Summary shows this method was modified in commit #a1b2c3 to add caching..."). 3. Output ONLY valid JSON matching this schema: { "reasoning_chain": ["Step 1: ...", "Step 2: ..."], "evidence_links": {"git_commit": "a1b2c3", "test_case": "TC-123"}, "suggested_fix": "Replace X with Y because..." }这个看似简单的模板，背后是我们反复打磨的结果。INSTRUCTIONS部分的每一条，都是为了对抗 LLM 的固有缺陷：第一条对抗幻觉（hallucination），第二条对抗推理跳跃（reasoning leap），第三条对抗格式污染（format pollution）。我们甚至在reasoning_chain的每个步骤里，强制要求 LLM 使用evidence_links中的 key 作为引用锚点，这样系统就能在后续自动校验每一步推理是否有据可依。
注意：我们禁用了一切“温度（temperature）”参数。所有生产环境的 Agent 调用，
temperature=0。这不是为了追求“确定性”，而是为了追求“可重现性”。同一个输入，必须永远产生同一个输出，这是审计和调试的生命线。那些需要“创造性”的场景（比如生成测试用例），我们交给另一个专门的、temperature=0.7的 Agent，且其输出必须经过独立的、基于规则的验证器（Validator）二次审核。
3.3 line-level comments 的持久化与同步：别让评论变成“幽灵”
评论的精准锚定和双向链接，听起来很美，但实现起来是场噩梦。最大的挑战是：Git 仓库是分布式的，PR 是瞬时的，而评论是需要长期存在的。我们最初的方案是把所有评论都存在自己的数据库里，用repo_name + pr_number + file_path + ast_hash作为主键。结果在一次 Git 服务器迁移后，所有评论都“丢失”了——因为数据库里的repo_name是旧的 URL，而新 Git 服务器的 URL 格式变了。
痛定思痛，我们采用了“Git 作为唯一真相源（Source of Truth）”的设计。所有评论的元数据（evidence_links,reasoning_chain的摘要哈希），都以特殊的、不可见的 Git 注释（Git Note）形式，直接附加到触发该评论的那个 AST 节点所对应的 Git 对象（通常是 blob 或 tree）上。Git Note 是 Git 原生支持的、与 commit 分离的元数据存储，它不改变代码内容，却能随代码一起被 clone、push、pull。这意味着，无论你的 Git 服务器迁移到哪里，无论你用的是 GitHub、GitLab 还是自建 Gitea，只要代码还在，评论的“根”就在。
前端展示层，则通过一个轻量级的 Webhook 服务，监听所有pull_request事件。当一个 PR 被打开或更新时，Webhook 服务会：
- 获取该 PR 中所有变更的文件列表；
- 对每个文件，调用 Git 命令
git notes --ref=review show <commit_hash>，提取出所有附加在该文件 commit 上的 review notes； - 将 notes 中的元数据，与当前 PR 的 diff 进行 AST 级别的比对，精准计算出每条评论应该显示在 diff 的哪个 hunk、哪一行；
- 将渲染好的 HTML 片段，通过 GitHub/GitLab 的 Checks API 或 Comment API，注入到 PR 界面。
这个方案的代价是 Webhook 服务需要能访问公司的 Git 服务器（通常在内网），但它换来的是极致的鲁棒性和零维护成本。我们上线两年，从未发生过一次“评论丢失”事故。
4. 完整实操流程：从零开始搭建一个可用的 open-code-review 环境
理论再完美，不如亲手跑通一遍。下面我将带你从一个空的 Ubuntu 22.04 服务器开始，一步步搭建一个功能完整的 open-code-review 环境。这个过程，我们内部称之为“15 分钟极速上手”，因为它真的只需要 15 分钟（当然，前提是你已经有一个现成的 Git 仓库和一个可用的 LLM API Key）。
4.1 环境准备与依赖安装
首先，确保你的服务器满足最低要求：4 核 CPU、16GB 内存、50GB 磁盘空间。我们推荐使用 Python 3.11，因为它对异步 I/O 的支持更成熟，这对高并发的 Review 请求至关重要。
# 更新系统并安装基础依赖 sudo apt update && sudo apt upgrade -y sudo apt install -y python3.11 python3.11-venv python3.11-dev git curl build-essential # 创建专用用户和工作目录 sudo useradd -m -s /bin/bash coder sudo su - coder mkdir -p ~/ocrr && cd ~/ocrr # 创建并激活虚拟环境 python3.11 -m venv venv source venv/bin/activate # 升级 pip 并安装核心依赖 pip install --upgrade pip pip install open-code-review-core==0.8.3 \ ast-grep==0.12.0 \ pydantic==2.6.4 \ httpx==0.25.0 \ jinja2==3.1.3提示：
open-code-review-core是我们开源的核心框架包，它不包含任何 LLM 模型，只提供规则引擎、Agent 调度器和 Git 集成的骨架。所有与具体 LLM 的对接，都通过插件（Plugin）方式实现，这保证了核心框架的轻量和稳定。
4.2 规则集（Ruleset）的初始化与定制
现在，让我们为你的第一个项目——一个简单的 Python Flask 应用——创建一个最小可行的规则集。
# 初始化规则集目录 mkdir -p rules/python cd rules/python # 创建一个基础规则：禁止在路由函数中使用 time.sleep() cat > sleep_in_route.yaml << 'EOF' id: PYTHON-ROUTE-SLEEP-01 name: "Avoid time.sleep() in route handlers" description: "Blocking sleep in web request handlers causes thread starvation and poor responsiveness." severity: HIGH language: python ast_pattern: | FunctionDef { decorator_list: { Call { func: { Attribute { attr: "route" } } } }, body: { Expr { value: { Call { func: { Attribute { attr: "sleep" } } } } } } } remediation: | Replace time.sleep() with async alternatives like asyncio.sleep(), or move the blocking operation to a background task queue (e.g., Celery). EOF这个规则的 AST 模式，精准地捕获了所有被@app.route装饰、且函数体内直接调用了time.sleep()的情况。它避开了time.sleep()在其他地方（比如工具函数里）的误报。
接下来，我们需要一个配置文件，告诉框架去哪里找规则：
cd ~/ocrr cat > config.yaml << 'EOF' ruleset: base_path: "./rules" languages: - python llm: provider: "openai" # 支持 openai, anthropic, ollama model: "gpt-4o-mini" api_key: "sk-..." # 替换为你的真实 API Key base_url: "https://api.openai.com/v1" git: repo_path: "/path/to/your/flask/app" # 替换为你的实际项目路径 webhook_secret: "your-webhook-secret" EOF注意：
gpt-4o-mini是我们目前实测下来性价比最高的模型。它在代码理解任务上的表现，与gpt-4-turbo相当，但 Token 成本只有后者的 1/3。对于规则触发后的深度推理，它足够胜任。如果你追求极致性能，也可以换成deepseek-coder-32b，但需要自行部署 Ollama 或 vLLM。
4.3 LLM Agent 插件的配置与测试
框架本身不内置 LLM，你需要安装对应的插件。以 OpenAI 为例：
pip install open-code-review-plugin-openai==0.2.1安装完成后，启动一个简单的 CLI 工具，来测试规则和 Agent 是否联通：
# 假设你的 Flask 应用里有一个文件 app.py，内容如下： cat > /path/to/your/flask/app/app.py << 'EOF' from flask import Flask import time app = Flask(__name__) @app.route('/') def home(): time.sleep(2) # <-- 这里应该被规则捕获！ return "Hello World!" EOF # 运行 CLI 测试 ocrr-cli scan --config ./config.yaml --file /path/to/your/flask/app/app.py如果一切顺利，你会看到类似这样的输出：
{ "file": "app.py", "violations": [ { "rule_id": "PYTHON-ROUTE-SLEEP-01", "line": 8, "column": 4, "message": "Found time.sleep() call in route handler 'home'. This will block the entire request thread.", "agent_response": { "reasoning_chain": [ "Step 1: The AST pattern confirms this function is decorated with @app.route, making it a web request handler.", "Step 2: The Git History Tool shows this file has no recent refactoring, so the sleep call is likely intentional.", "Step 3: The TestCoverageTool reports 0% coverage for this route, indicating it's untested and high-risk." ], "evidence_links": { "git_commit": "HEAD", "test_coverage": "0%" }, "suggested_fix": "Replace 'time.sleep(2)' with 'await asyncio.sleep(2)' and make the function 'async def home()'." } } ] }恭喜！你已经成功让规则、AST 解析、LLM Agent 和 Git 工具全部跑通了。这证明了整个数据流是健康的：代码 -> AST 解析 -> 规则匹配 -> Agent 调度 -> 工具调用 -> LLM 推理 -> 结构化输出。
4.4 集成到 GitHub PR 流程：让评论自动出现
最后一步，也是最关键的一步：让它真正融入你的开发工作流。我们将通过 GitHub App 的方式集成。
创建 GitHub App：登录 GitHub，进入 Settings -> Developer settings -> GitHub Apps -> New GitHub App。填写名称（如
open-code-review），Homepage URL 填你服务器的地址，Webhook URL 填https://your-server-ip:8000/webhook，Webhook secret 填你在config.yaml里设置的webhook_secret。设置权限：在 Permissions & events 页面，授予
Contents: Read-only和Pull requests: Read and write。在 Subscribe to events 页面，勾选Pull request。安装 App：生成私钥（Private key），下载保存为
private-key.pem。然后在你的 GitHub 组织或仓库里安装这个 App。启动 Webhook 服务：回到你的服务器，启动服务：
# 安装 Webhook 服务依赖 pip install fastapi uvicorn starlette # 启动服务（生产环境请用 systemd 管理） uvicorn ocrr.webhook:app --host 0.0.0.0 --port 8000 --ssl-keyfile /path/to/key.pem --ssl-certfile /path/to/cert.pem现在，当你在安装了该 App 的仓库里创建一个新的 PR，并且 PR 中包含了app.py的修改时，Webhook 服务会自动接收到事件，调用ocrr-cli scan进行分析，并将生成的 line-level comments，通过 GitHub 的 Checks API 发送回去。几秒钟后，你就会在 PR 的 diff 界面上，看到那条精准定位在第 8 行的、带着完整推理链的红色评论。
5. 常见问题与独家排查技巧：那些文档里不会写的坑
再完美的设计，也架不住现实世界的千奇百怪。以下是我们在过去两年中，被问得最多、也最让人抓狂的 5 个问题，以及我们总结出的、真正管用的排查技巧。这些问题，没有一个能在官方文档里找到答案。
5.1 问题：规则明明写对了，但就是不触发！AST 模式像天书一样难 debug
这是新手最大的挫败感来源。你对着ast-grep的文档写了半天，ast-grep --lang python --pattern "..."命令在命令行里跑得好好的，可一放到 open-code-review 里，就石沉大海。
独家排查技巧：启用 AST 调试模式
框架内置了一个隐藏的调试开关。在你的config.yaml里，添加一行：
debug: ast_dump: true然后再次运行ocrr-cli scan。它会在控制台输出两样东西：第一，是它实际解析出的、完整的 AST JSON 树；第二，是它尝试匹配你规则ast_pattern的详细过程日志，包括“在节点 A 尝试匹配，失败，因为缺少子节点 B”。
举个真实例子：我们曾写过一条规则，想捕获所有if语句中条件为len(x) == 0的情况。模式写成了：
ast_pattern: | If { test: { Compare { left: { Call { func: { Name { id: "len" } } } } ops: { Eq } comparators: { Num { n: 0 } } } } }但一直不触发。开启ast_dump后，我们发现，AST 树里comparators字段其实是一个列表[Num(n=0)]，而不是单个Num节点。正确的模式应该是：
comparators: { List { elts: { Num { n: 0 } } } }提示：不要试图在脑子里“脑补” AST 结构。永远用
ast-dump输出的 JSON 为准。我们甚至把这个功能做成了一个 VS Code 插件，右键代码就能一键生成 AST JSON，极大提升了规则编写效率。
5.2 问题：LLM Agent 的评论总是“正确的废话”，比如“这段代码可以优化”，却不告诉你怎么优化
这几乎 100% 是 Prompt 的问题。但更深层的原因，往往是证据（Evidence）质量太差。LLM 不是神，它只能基于你喂给它的信息做推理。如果GitHistoryTool返回的是一堆乱码般的 commit message（比如 “fix bug”、“update deps”），或者TestCoverageTool返回的是 “N/A”，那么 LLM 就真的只能胡说八道。
独家排查技巧：独立验证每个 Tool
框架提供了ocrr-tool命令行工具，让你可以单独调用每一个 Tool，查看其原始输出：
# 查看 Git 历史工具的原始输出 ocrr-tool git-history --file /path/to/app.py --lines 5-15 # 查看测试覆盖率工具的原始输出 ocrr-tool test-coverage --file /path/to/app.py如果发现某个 Tool 的输出质量堪忧，不要怪 LLM。去修 Tool。比如，git-history工具默认只取最近 5 个 commit，但你的关键变更可能在第 8 个。那就去它的配置里，把max_commits改成 10。test-coverage工具默认只看pytest，但你的项目用的是
