企业官网建设流程全解析

1. 这不是另一个“AI代码审查工具”，而是一套可落地的开源协作新范式

“open-code-review”这个词组乍一看像某个新发布的CLI工具名，但真正把它拆开来看——open（开放）、code（代码）、review（评审）——它指向的其实是一场正在 quietly 发生的工程文化迁移。我从2018年开始带团队做代码质量体系建设，经历过从人工走查、Jenkins+SonarQube流水线卡点、到GitHub PR模板强制填写checklist的各个阶段。直到去年底，我们把内部一个叫“diff-scout”的小工具开源后，收到最多的一句反馈是：“你们这个 review 流程，怎么看起来不像在用AI，倒像是把人和AI重新编排了一遍？”——这恰恰就是 open-code-review 的本质：它不追求用大模型全自动“批改作业”，而是把代码评审这件事，从“人等PR、人看diff、人写comment”的被动等待态，重构为“diff自动触发、上下文自动加载、评论建议分层生成、人专注决策与权衡”的主动协同态。

核心关键词里，“LLM Agent”不是噱头，而是架构锚点；“git diffs”不是输入格式，而是最小可信单元；“CLI”不是终端玩具，而是连接开发者心智与工程系统的神经接口。它解决的不是“能不能自动写comment”，而是“为什么每次CR都卡在‘这个函数要不要拆’这种需要上下文权衡的问题上”。适合三类人直接抄作业：一是中小型技术团队的工程效能负责人，想用最低侵入成本提升CR通过率；二是独立开发者或开源维护者，需要在没有专职QA的情况下守住主干质量水位；三是CLI工具链重度用户，厌倦了在IDE插件、网页界面、命令行之间反复切换上下文。它不替代Code Review本身，而是让Review这件事，第一次真正具备了可沉淀、可回溯、可复用的工程属性——就像当年Git让代码变更可追溯一样，open-code-review让评审决策本身也变成了一等公民。

2. 整体设计思路：为什么必须放弃“全自动评审”的幻觉？

2.1 从三个失败案例看清技术选型的底层逻辑

我见过太多团队踩坑：A团队用某云厂商的“智能CR”服务，结果90%的comment集中在空格/换行/命名规范上，真正该讨论的并发安全问题一条没提；B团队自研LLM评审bot，训练数据全来自历史PR，结果模型学会了“复制粘贴老同事的模糊评语”，比如“建议优化”“考虑可读性”这种无效话术；C团队强行把整个repo喂给本地Qwen-32B，单次diff分析耗时47秒，开发者早切到下一个任务了。这些失败背后，是同一个认知偏差：把Code Review当成NLP任务，而不是软件工程决策过程。

open-code-review的设计起点，恰恰是反其道而行之——它默认LLM不具备独立决策能力，只承担“信息重组员”角色。真正的决策权，永远留在开发者手中。具体拆解为三层架构：

• 输入层严格限定为git diffs：不是整文件、不是AST、更不是整个commit history。只取git diff --no-index <old> <new>生成的原始文本。原因很实在：diff是Git世界里唯一被所有工具、所有平台、所有开发者共同认可的“变更事实”载体。它天然具备原子性（一次只改一处）、可逆性（能反向patch）、可比性（不同分支diff可并列展示）。我们试过用AST diff，结果发现Python的ast.unparse()在处理装饰器时会丢掉换行，导致diff失真；也试过用semantic diff，但CI环境里安装clangd太重，光依赖就占200MB。最终回归diff，是因为它足够“丑陋但可靠”。

• Agent层不做推理，只做路由与组装：这里的关键转折点，是把“LLM Agent”理解成“规则驱动的管道工”，而非“自主思考的AI”。比如当diff中出现threading.Lock()时，Agent不自己判断是否线程安全，而是触发预设的“并发模式检查器”——这个检查器可能是调用Bandit的特定规则，也可能是查询内部知识库里的《高并发模块设计规范》PDF页码，最后才把结构化结果喂给LLM生成自然语言comment。我们用YAML定义了37个这样的“检查器路由规则”，覆盖日志、权限、序列化、资源释放等高频风险域。实测下来，这种“规则+LLM”的混合模式，比纯LLM prompt engineering的准确率高出62%，且误报率从31%压到4.7%。

• CLI层作为唯一入口，强制统一工作流：拒绝提供Web UI或IDE插件。所有操作必须通过ocrr review --pr=123或ocrr diff HEAD~1 HEAD触发。表面看是增加学习成本，实际解决了两个致命问题：一是避免不同IDE插件版本导致的评审结果不一致（曾有团队因VS Code插件更新，导致同一份diff在Mac和Windows上生成完全不同的security warning）；二是让评审行为天然进入Git操作流——你可以把它加到pre-commit hook里，也可以集成进CI的post-build阶段，甚至用ocrr watch监听本地分支变动自动触发。CLI不是妥协，而是把“评审”这件事，从偶发的人工动作，固化为可编程的工程事件。

2.2 为什么拒绝“端到端大模型”方案？一次真实的性能测算

很多人问：既然有DeepSeek-Coder、Qwen2.5-Coder这些专为代码优化的模型，为什么不直接调用？我们做过一组硬核对比测试：用相同prompt模板，分别跑通Qwen2.5-7B-Instruct、DeepSeek-Coder-6.7B-Instruct、以及本地部署的Phi-3-mini-4k-instruct，在16GB显存的RTX4090上处理同一份含3个函数修改的diff（约120行代码）。

*注：有效信息密度 = 生成comment中被开发者实际采纳的建议条数 / 总生成条数，基于10名资深工程师盲评

结果很反直觉：参数量最大的Qwen反而表现最差。深挖发现，大模型在处理diff这种高度结构化的文本时，大量算力浪费在理解“@@ -12,5 +12,7 @@”这类Git元信息上。而Phi-3虽然通用能力弱，但它的tokenizer对符号（如+-@@）做了特殊优化，能更快定位变更行。更重要的是，Phi-3的context window只有4K，反而逼我们把prompt设计得极度精简——去掉所有修饰词，只留“你是一个资深Java工程师，请针对以下diff指出：1. 是否存在空指针风险；2. 是否违反公司日志规范；3. 是否有资源泄漏可能”。这种“窄口径、强约束”的提示方式，比大模型自由发挥更可靠。

所以open-code-review的模型策略很务实：核心检查器用Phi-3-mini跑在本地，保证毫秒级响应；复杂场景（如跨文件调用链分析）才调用云端API，但必须带超时熔断（默认3s）和降级开关。我们甚至预留了--model=rule-based参数，当网络异常时，自动切回纯正则匹配的老派方案——毕竟，宁可给出“未检测到风险”的保守结论，也不能让评审流程卡死。

2.3 CLI设计背后的工程哲学：为什么“命令即契约”

CLI不是功能堆砌，而是把工程约定翻译成可执行指令。以ocrr review --pr=123 --context=full为例，这个命令背后藏着三层契约：

• 与Git的契约：--pr=123不直接调GitHub API，而是先执行git fetch origin pull/123/head:pr-123，确保本地有完整分支快照。这样即使GitHub宕机，只要Git repo在线，评审就能继续。我们甚至支持ocrr review --commit=abc123，直接分析任意commit，这对修复线上bug后的紧急回溯特别有用。

• 与团队规范的契约：--context=full触发的不是简单地cat文件，而是按预设规则加载上下文：自动提取被修改函数的调用栈（用pycparser解析AST）、关联最近3次对该函数的修改（git log -n 3 --grep="func_name"）、抓取相关单元测试文件（按命名约定匹配test_*_func_name.py）。这些规则写在.ocrr/config.yaml里，每个团队可以定制。比如金融团队会额外加载风控规则引擎的schema文件，游戏团队则优先加载Unity AssetBundle依赖图。

• 与开发者注意力的契约：所有输出强制分块渲染。第一屏只显示“高危风险摘要”（如“发现1处未处理的InterruptedException”），按回车展开“中风险详情”，再按回车才看到“低风险建议”。我们统计过，83%的开发者只看第一屏就决定是否立即修复，剩下17%才会深入。这种设计不是偷懒，而是尊重人类注意力的生理极限——把最关键的信号放在最前面，避免信息过载导致决策疲劳。

这种“命令即契约”的思想，让我们在接入飞书机器人时少走了很多弯路。飞书Bot接收/ocrr pr-123指令后，不是转发给后端API，而是直接在飞书服务器上执行ocrr review --pr=123 --output=markdown，生成带emoji状态图标（✅/⚠️/❌）的富文本消息。因为CLI本身已封装了所有上下文加载逻辑，飞书侧无需理解任何业务规则，纯粹做命令透传。同理，VS Code插件也只需调用CLI，不用重复实现diff解析、上下文检索等逻辑——CLI成了所有接入方的“协议转换器”。

3. 核心细节解析：从diff解析到评论生成的七步实操链

3.1 Step 1：diff标准化——为什么连空格都要较真？

Git diff看似简单，实则暗藏陷阱。git diff默认输出格式受core.autocrlf、core.whitespace等配置影响，Windows换行符\r\n和Linux的\n混用会导致LLM误判“新增了空行”。open-code-review的第一步，是把原始diff喂给ocrr normalize子命令：

# 原始diff可能包含： # + def process_data(self, data): # Windows下可能带\r # + if not data:\r\n # + return None\r\n # normalize后强制统一为： # + def process_data(self, data): # + if not data: # + return None

这个过程不只是替换\r\n，还包括：

• 移除diff header中的时间戳、路径绝对路径（统一转为相对路径）
• 标准化tab与空格（全部转为4空格，符合PEP8）
• 对二进制文件diff打标记（Binary files a/file.png and b/file.png differ），跳过LLM分析，直接触发“需人工确认”流程

我们专门写了diff-normalizer模块，用Rust实现核心逻辑（比Python快8倍），关键在于它不依赖Git binary，而是直接解析diff文本流。实测处理10MB diff文件（常见于大型重构）仅需210ms，而调用git apply --check验证要1.8秒。这个“预处理快于验证”的设计，让整个流水线不会被单个大diff拖垮。

3.2 Step 2：变更粒度切片——把diff切成“可评审单元”

LLM处理长文本效果差，但把diff粗暴切分成每行一个单元又丢失语义。我们的解决方案是“语法感知切片”（Syntax-Aware Chunking）：

• 对Python/JS/Java等主流语言，用tree-sitter解析AST，识别出函数、类、方法、if块等语法节点
• 将diff中+行和-行映射回AST节点，按节点边界切片
• 每个切片包含：变更前代码（-）、变更后代码（+）、所在文件路径、所属AST节点类型、节点起始行号

例如这段diff：

@@ -15,6 +15,8 @@ def calculate_total(self, items): total = 0 for item in items: - total += item.price * item.quantity + if item.price > 0 and item.quantity > 0: + total += item.price * item.quantity return total

会被切为一个切片：

{ "file": "cart.py", "node_type": "function", "node_name": "calculate_total", "lines_before": ["total = 0", "for item in items:", " total += item.price * item.quantity"], "lines_after": ["total = 0", "for item in items:", " if item.price > 0 and item.quantity > 0:", " total += item.price * item.quantity"], "start_line": 15 }

这种切片方式，让LLM每次只聚焦一个逻辑单元，避免了“看到for循环就报警说性能问题”的误判。我们测试过，相比按行切片，AST切片使LLM生成的comment相关性提升53%，且减少了72%的“建议拆分函数”这类泛泛而谈的废话。

3.3 Step 3：上下文注入——不是塞更多代码，而是塞更精准的线索

很多工具号称“提供上下文”，结果把整个文件甚至整个module都扔给LLM。open-code-review的上下文注入策略是“三阶精准匹配”：

• 一阶：变更直接影响域（Immediate Impact Zone）
  自动提取被修改函数的所有调用点（用pyan3生成调用图），只加载这些调用点所在的代码片段。比如修改validate_user()，就只加载所有user_service.py中调用它的5处位置，而非整个service文件。

• 二阶：历史变更线索（Historical Trail）
  执行git log -p -n 5 --grep="validate_user" -- cart.py，提取最近5次对该函数的修改diff，合并成“变更演进摘要”。LLM看到的不是孤立的当前修改，而是“第3次修改增加了邮箱格式校验，本次又增加了手机号校验”。

• 三阶：规范锚点（Policy Anchors）
  根据文件路径匹配预设规则，自动注入对应规范。如/src/api/下的文件，自动附加《REST API设计规范》PDF中“错误码设计”章节的文本摘要；/src/core/下的文件，则注入《核心模块安全红线》Markdown片段。

这个过程由ocrr context子命令完成，所有上下文文本经过context-compressor压缩（保留关键变量名、函数名、错误码，删减注释和空行），确保总token数控制在LLM context window的70%以内。我们甚至支持--context-mode=light参数，只加载一阶上下文，适合CI流水线快速扫描。

3.4 Step 4：检查器路由——让规则引擎成为LLM的“外挂大脑”

这才是open-code-review区别于其他工具的核心。我们不写prompt让LLM自己找问题，而是用YAML定义检查器规则库：

# .ocrr/checkers/security.yaml - name: "SQL Injection Risk" trigger: - pattern: ".*cursor\.execute\(.*\+.*\)" - language: ["python"] action: - type: "bandit_scan" rule: "B601" - type: "llm_prompt" template: | 你是一名安全专家。以下代码使用字符串拼接构造SQL查询： {{diff_lines}} 请指出：1. 是否存在SQL注入风险；2. 推荐的参数化查询写法；3. 如果必须拼接，请给出白名单校验方案。

当diff匹配到cursor.execute(... + ...)模式时，系统自动：

1. 调用Bandit执行B601规则扫描（检测动态SQL）
2. 提取Bandit报告中的风险行号
3. 把原始diff、Bandit结果、安全规范片段一起喂给LLM
4. LLM只负责把技术发现翻译成开发者能懂的语言

这种设计带来三个好处：

• 可验证：Bandit的结果是确定性的，LLM只做表达层转换，避免“AI幻觉”导致误报
• 可审计：所有检查器规则开源，团队可随时审查、修改、增删
• 可替换：某天发现Bandit漏报，换成Semgrep只需改YAML里的type字段，LLM prompt完全不用动

我们内置了28个检查器，覆盖安全、性能、可维护性、合规性四大维度。最常用的是“资源泄漏检查器”，它结合tracemalloc分析diff中新增的open()、socket()调用，自动检查是否匹配with语句或close()调用——这种深度集成，是纯prompt无法实现的。

3.5 Step 5：LLM生成——用“约束式生成”对抗AI幻觉

LLM生成环节，我们彻底放弃自由发挥式prompt。所有请求都走structured output pipeline：

1. 先用ocrr llm schema生成JSON Schema，定义输出结构：

{ "type": "object", "properties": { "risk_level": {"enum": ["critical", "high", "medium", "low"]}, "explanation": {"type": "string"}, "suggestion": {"type": "string"}, "code_snippet": {"type": "string", "nullable": true} } }

2. 调用LLM时强制指定response_format={"type": "json_object"}（OpenAI API）或--json参数（Ollama）

3. 后处理阶段用JSON Schema校验，失败则重试（最多2次），仍失败则返回{"risk_level": "unknown", "explanation": "LLM生成异常，请手动检查"}

这种“Schema先行”策略，让生成结果100%可解析，前端能直接渲染成带颜色标签的卡片式评论。更重要的是，它杜绝了LLM编造不存在的函数名、行号、错误码等幻觉内容——因为JSON Schema明确要求code_snippet字段必须是diff中真实存在的代码片段。

我们还做了个狠招：在prompt里嵌入“自我验证指令”。例如安全类prompt末尾固定加一句：“请再次检查你的建议是否与提供的Bandit扫描结果一致，如果不一致，请修正。”实测使幻觉率从12.3%降到0.8%。

3.6 Step 6：评论分级——不是所有建议都值得推送到PR

生成的评论不是一股脑全发出去。open-code-review内置三级过滤：

• Level 1：规则硬过滤
  如risk_level == "critical"且explanation包含“空指针”“越界”“SQL注入”等关键词，直接标记为must_fix

• Level 2：上下文可信度加权
  计算每个评论的“上下文支撑度”：如果Bandit扫描结果、历史变更摘要、规范锚点三者都指向同一风险，则权重+0.3；如果只有LLM单独提出，则权重-0.2。权重<0.5的评论自动降级为info

• Level 3：团队偏好过滤
  读取.ocrr/team-preferences.yaml，例如：

  ignore_patterns: - "建议添加类型注解" # 团队暂不强制Type Hints - "考虑使用f-string" # 允许format()写法

最终输出到PR的评论，只有must_fix和should_fix两级，且每条评论附带“依据来源”图标：🔍（来自Bandit）、📜（来自规范）、⏳（来自历史变更）。开发者一眼就知道这条建议是机器扫描发现的，还是AI推测的，还是团队共识的。

3.7 Step 7：结果持久化——让每次评审都成为团队知识资产

所有评审结果不只停留在PR页面。ocrr review命令执行后，自动生成.ocrr/reports/2024-06-15-pr-123.json，内容包括：

{ "pr_id": 123, "author": "zhangsan", "reviewer": "ocrr-v1.2.0", "timestamp": "2024-06-15T14:22:31Z", "diff_hash": "a1b2c3...", "comments": [ { "id": "sec-sql-001", "file": "api/user.py", "line": 45, "level": "must_fix", "text": "检测到动态SQL拼接，存在SQL注入风险...", "sources": ["bandit-B601", "security-policy-3.2"], "resolved": false } ], "stats": { "critical": 1, "high": 2, "medium": 5, "low": 0 } }

这个JSON文件被自动提交到.ocrr/reports/目录，并推送到专用分支。它带来的价值远超评审本身：

• 质量趋势分析：用ocrr stats --since=last-month生成团队月度质量报告，比如“SQL注入类问题下降40%，但空指针问题上升22%”，直接驱动专项改进
• 新人培训素材：把resolved: true的历史报告整理成《典型问题案例库》，新成员入职第一周就学这些真实PR
• 自动化闭环：CI检测到critical问题且resolved: false，自动在PR添加DO-NOT-MERGE标签，并@对应模块Owner

我们甚至用这些报告训练了一个轻量级分类模型，预测“哪些PR大概率需要返工”，准确率达89%。这不是AI取代人，而是让人的经验，通过数据沉淀下来，变成团队可复用的集体智慧。

4. 实操过程详解：从零部署到融入日常开发流

4.1 环境准备——三分钟完成本地验证

不要被“LLM”“Agent”吓住，open-code-review的最小可行环境只需要：

• Python 3.9+（官方支持3.9/3.10/3.11）
• Git 2.25+（确保支持git worktree）
• 一台能跑Phi-3-mini的机器（16GB内存+4GB显存，或纯CPU模式）

安装命令极其简单：

pip install open-code-review # 或从源码安装（推荐，便于定制） git clone https://github.com/your-org/open-code-review.git cd open-code-review pip install -e .

验证安装：

ocrr --version # 应输出 v1.2.0 ocrr help # 查看所有子命令

提示：首次运行ocrr review会自动下载Phi-3-mini模型（约2.1GB），建议在非高峰时段执行。下载路径默认为~/.ocrr/models/phi-3-mini-4k-instruct.Q4_K_M.gguf，可修改.ocrr/config.yaml中的model_path指向NAS共享目录，避免多台机器重复下载。

4.2 初始化项目——一份配置文件搞定团队规范

在项目根目录创建.ocrr/config.yaml，这是整个评审体系的“宪法”：

# .ocrr/config.yaml version: "1.0" # 模型配置 model: type: "llama.cpp" # 支持 llama.cpp / ollama / openai path: "~/.ocrr/models/phi-3-mini-4k-instruct.Q4_K_M.gguf" n_ctx: 4096 n_threads: 8 # 检查器配置 checkers: enable: ["security", "performance", "maintainability"] disable: ["style"] # 团队已用prettier统一代码风格 # 上下文配置 context: max_files: 5 # 最多加载5个相关文件 max_lines_per_file: 100 # 每个文件最多加载100行 include_history: true # 启用历史变更线索 # 输出配置 output: format: "github" # 支持 github / gitlab / markdown / json show_sources: true # 在评论中显示依据来源

关键技巧：配置文件支持环境变量插值。比如在CI环境中：

model: type: "openai" api_key: "${OPENAI_API_KEY}" base_url: "https://api.openai.com/v1"

这样本地用Phi-3，CI用GPT-4-turbo，无需改代码。

4.3 日常使用场景——覆盖开发者90%的评审需求

场景1：PR提交前自助检查（推荐给所有开发者）

# 切换到PR分支 git checkout feat/login-validation # 生成本次变更的评审报告 ocrr review --pr=123 --output=markdown > review-report.md # 用VS Code打开报告，逐条检查 code review-report.md

实操心得：我们要求所有PR必须附带ocrr review生成的报告。不是为了甩锅给AI，而是让开发者在提PR前，先和自己的代码“对话”一次。数据显示，采用此流程后，PR首次通过率从58%提升到82%。

场景2：CI流水线自动卡点（推荐给工程效能团队）

在.gitlab-ci.yml或.github/workflows/ci.yml中加入：

review: stage: test script: - pip install open-code-review - ocrr review --pr=$CI_MERGE_REQUEST_IID --fail-on=critical allow_failure: false

--fail-on=critical参数是关键：只要检测到critical问题，CI直接失败，阻止合并。注意不是--fail-on=all，避免因低风险问题阻塞交付。

场景3：紧急线上问题回溯（推荐给SRE/运维）

当线上出现5xx错误，快速定位最近变更：

# 找到报错时间段内的commit git log --since="2024-06-14" --until="2024-06-15" --oneline # 分析可疑commit ocrr review --commit=abc123def456 --context=full

这时--context=full会自动加载该commit涉及的所有文件、调用链、历史变更，帮你3分钟内判断是不是这次发布引入的问题。

场景4：飞书/钉钉机器人接入（推荐给技术负责人）

以飞书为例，创建Bot后，在bot.py中：

from open_code_review.cli import review_pr @app.post("/webhook") def handle_webhook(): event = request.json if event.get("type") == "message": text = event["event"]["message"]["text"] if text.startswith("/ocrr pr-"): pr_id = int(text.split("-")[1]) report = review_pr(pr_id, output_format="markdown") send_to_feishu(report)

注意：飞书Bot需开通“消息发送”权限，且review_pr函数内部会自动处理Git克隆、上下文加载等耗时操作，建议异步执行并返回“正在分析…”提示。

4.4 高级定制——让open-code-review真正属于你的团队

定制检查器：三步添加一个新规则

假设团队要求所有数据库查询必须有超时设置，新建.ocrr/checkers/db-timeout.yaml：

- name: "Database Query Timeout" trigger: - pattern: ".*\.execute\(.*\)|.*\.fetch\(.*\)" - language: ["python"] action: - type: "grep" pattern: "timeout=|query_timeout=" invert: true - type: "llm_prompt" template: | 你是一名DBA。以下代码执行数据库查询： {{diff_lines}} 请指出：1. 是否缺少查询超时设置；2. 推荐的timeout参数值（根据操作类型：读操作建议3s，写操作建议10s）；3. 如果使用ORM，请给出对应的超时配置方式。

然后在主配置中启用：

checkers: enable: ["security", "db-timeout"] # 添加新检查器

定制输出模板：让评论更符合团队语言习惯

编辑.ocrr/templates/github.j2（Jinja2模板）：

{% if comment.level == 'must_fix' %} 🚨 **必须修复** {{ comment.text }} 💡 依据：{% for src in comment.sources %}{{ src }} {% endfor %} {% endif %}

这样生成的PR评论，会自动带上醒目的🚨图标和依据来源，比纯文字更易被关注。

定制CLI别名：降低新人使用门槛

在团队共享的setup.sh中加入：

# 创建常用别名 alias cr='ocrr review --pr' alias crd='ocrr diff HEAD~1 HEAD --context=light' alias crw='ocrr watch --interval=30'

新人只需记住cr 123就能启动评审，大幅降低使用门槛。

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

5.1 “LLM没反应”——90%的问题出在上下文加载

现象：执行ocrr review --pr=123后卡住10秒以上，无输出。

排查步骤：

1. 先运行ocrr diff --pr=123 --raw，确认能否正常获取diff文本（排除Git权限问题）
2. 再运行ocrr context --pr=123 --dry-run，查看上下文加载日志
   • 如果卡在Loading call graph for validate_user...，说明pyan3解析失败，检查是否安装了正确版本的pyan3（需>=1.0.0）
   • 如果卡在Fetching historical commits...，检查Git remote是否配置正确（git remote get-url origin）
3. 最后运行ocrr llm --test，验证模型加载是否成功

独家技巧：在.ocrr/config.yaml中添加debug: true，所有子命令会输出详细日志。我们发现73%的“卡顿”问题，其实是网络代理导致的Ollama模型拉取超时，解决方案是在config.yaml中指定model.type: "llama.cpp"并提前下载好模型。

5.2 “评论不准确”——不是模型问题，是切片错了

现象：LLM对一段简单的if-else修改，给出了“建议改为switch语句”的错误建议。

根本原因：AST切片把整个if块当成了一个单元，但LLM看到的只是if condition: ... else: ...，缺乏函数签名和调用上下文。

解决方案：

• 运行ocrr diff --pr=123 --show-ast，查看切片详情
• 如果发现切片过大，手动在.ocrr/config.yaml中调整：

  chunking: max_lines_per_chunk: 15 # 从默认30降到15 force_function_boundary: true # 强制按函数切分

• 或临时用--chunk-size=10参数缩小切片

实操心得：我们团队规定，所有涉及算法逻辑的修改，必须用ocrr review --chunk-size=5精细切片。因为LLM在10行代码内做决策，准确率比50行高3倍。

5.3 “CI里失败”——环境差异导致的隐性依赖

现象：本地ocrr review成功，CI里报错ModuleNotFoundError: No module named 'pyan3'。

原因分析：CI镜像里没装pyan3，而本地开发机有。open-code-review的检查器是按需加载的，只有触发对应规则时才import模块。

解决方案：

• 在CI脚本中显式安装所有检查器依赖：

  pip install open-code-review[all-checkers]

• 或更稳妥的方式，在.ocrr/config.yaml中禁用CI不需要的检查器：

  checkers: enable: ["security", "performance"] # 禁用需要pyan3的maintainability

5.4 “飞书机器人不响应”——权限与网络的双重陷阱

现象：飞书Bot收到/ocrr pr-123指令，但无回复。

排查清单：

• ✅ 飞书Bot是否开通“消息发送”权限（管理后台→Bot设置→权限管理）
• ✅ Bot是否被添加到目标群聊（不是私聊！）
• ✅ 服务器是否能访问飞书API（curl -X POST https://open.feishu.cn/open-apis/bot/v2/hook/xxx）
• ✅review_pr()函数是否捕获了异常（我们建议在Bot代码中加全局try-catch，失败时发"评审失败：{error}"到群聊）

独家避坑：飞书Webhook有频率限制（100次/分钟），我们用Redis做请求去重，同一PR 5分钟内只处理一次。代码片段：

import redis r = redis.Redis() key = f"ocrr:pr:{pr_id}" if r.exists(key): return "已在处理中，请稍候" r.setex(key, 300, "processing") # 5分钟过期

5.5 “模型输出乱码”——编码与token的隐形战争

现象：评论中出现``符号，或中文显示为\\u5efa\\u8bae。

根源：LLM模型文件用UTF-8编码，但某些终端或CI环境默认用GBK。更隐蔽的是，llama.cpp