open-code-review 贡献指南：从本地开发环境搭建到源码贡献的完整实践

open-code-review 贡献指南从本地开发环境搭建到源码贡献的完整实践【免费下载链接】open-code-reviewFast, efficient, battle-tested at Alibabas scale. Hybrid architecture code review tool: deterministic pipelines LLM Agent, precise line-level comments, built-in multi-language ruleset (NPE, thread-safety, XSS, SQL injection), OpenAI Anthropic compatible.项目地址: https://gitcode.com/GitHub_Trending/op/open-code-review本篇技术指南以 open-code-review 官方中文贡献文档为主体结合仓库中的 Makefile、go.mod、internal/config/toolsconfig/toolsconfig.go、internal/tool/definitions.go、internal/config/rules/system_rules.json 等源码与配置文件系统讲解如何参与这一 Apache-2.0 开源项目的开发。读完你将掌握本地开发环境与构建流程、Make target 的完整含义、分支与提交规范、项目目录结构以及最关键的两种源码贡献路径——添加新工具Tool与添加新规则模式Rule Pattern的实现原理与操作步骤。贡献方式open-code-review 是 Apache-2.0 许可下的开源项目欢迎 bug 报告、文档修复与代码贡献。即使不写 Go 也能帮上忙主要贡献途径有五类Bug 报告——开一个带复现步骤的 issue附上最小复现用例维护者才能快速定位。功能请求——在 Discussions 中开帖讨论或提交 feature-request issue。文档——错别字、缺失示例、失效链接等文档类 PR 通常最快被合并是新手入门的理想切入点。评审其他 PR——非维护者的代码评审意见有助于减轻维护者负担也是理解代码库的最佳途径之一。代码——bug 修复、性能优化、新功能这是对项目最深度的贡献。本地开发环境搭建前置条件开发 open-code-review 需要三样基础工具工具要求Go≥ 1.25仓库 go.mod 中声明的模块版本为go 1.25.5Git用于版本管理与提交Make用于驱动构建与测试流程获取源码标准流程是 Fork 后在本地维护两个 remote# Fork on GitHub, then: git clone https://github.com/your-username/open-code-review.git cd open-code-review git remote add upstream https://github.com/alibaba/open-code-review.git make build # writes dist/opencodereview make test # LC_ALLC go test -v -race -count1 ./...upstreamremote 是只读的。日常开发推送到origin你的 fork并从那里发起 PR。运行本地构建构建产物输出到dist/opencodereview可直接在任意仓库中试运行./dist/opencodereview review --preview其中--preview表示只生成评审预览而不真正提交。为方便起见可以在~/bin/ocr-dev放一个指向dist/opencodereview的符号链接之后即可在任意仓库直接调用ocr-dev无需反复输入完整路径。Make target 全解析仓库的构建、测试与发布流程全部由 Makefile 驱动。官方文档给出的核心 target 如下Target作用make build为当前平台构建 →dist/opencodereview。make build-darwin-amd64交叉编译 macOS Intel。make build-darwin-arm64交叉编译 macOS Apple Silicon。make build-linux-amd64交叉编译 Linux x86_64。make build-linux-arm64交叉编译 Linux ARM64。make build-windows-amd64交叉编译 Windows x86_64。make build-windows-arm64交叉编译 Windows ARM64。make build-all全部六个交叉编译二进制linux/darwin/windows × amd64/arm64。make sha256sum为构建产物生成sha256sum.txt。make distclean → build-all → sha256sum。CI 运行的内容。make test带 race 检测运行测试。make clean删除dist/。结合 Makefile 源码还可以补充几个对日常开发同样有用的细节版本信息注入make build通过-ldflags -X main.Version... -X main.GitCommit... -X main.BuildDate...把版本号、短 commit hash 与构建时间注入二进制Makefile。版本号优先取最近的 git tag无 tag 时回退为v0.0.0-短提交哈希。make coverage运行覆盖率统计并检查总覆盖率是否达到 90% 阈值未达标直接以非零状态退出Makefile。贡献涉及行为变更时这是本地验证测试充分性的好帮手。make check一键执行license-check、english-check、go mod tidy、gofmt -s与go vet是开 PR 前的总检查项Makefile。make run/make help前者构建后以--staged模式运行对暂存区做评审后者构建后输出 CLI 帮助Makefile。make version-info打印当前注入的 VERSION、GitCommit、BuildDate 与 LD_FLAGS便于排查版本问题。测试包范围make test会通过go list ./...枚举包并排除extensions/目录Makefile——pages/因拥有独立的go.mod模块边界而天然被跳过extensions/vscode则因其中不存在本项目 Go 代码且其 eslint 依赖会引入干扰而被显式过滤。分支与提交约定分支前缀所有功能分支统一使用语义化前缀便于在 CI、changelog 中快速识别变更性质前缀用途feat/新功能fix/Bug 修复docs/仅文档refactor/无行为变更的重构test/仅测试变更chore/构建 / CI / 工具从最新的 upstream main 拉取后创建分支git checkout main git pull upstream main git checkout -b feat/anthropic-streaming提交信息提交信息遵循 Conventional Commits 格式type(scope): short summary [optional body explaining the why]官方示例feat(agent): add support for custom tool definitions fix(llm): handle timeout errors in Anthropic API calls docs(readme): clarify endpoint resolution priority refactor(viewer): extract task-card rendering into helperPR 标题也使用相同格式这样生成的 changelog 才会整洁可读。scope 通常对应internal/下的包名agent、llm、viewer等body 部分说明为什么这样做而非机械复述 diff。项目结构open-code-review 采用清晰的包边界划分官方文档给出的目录树如下open-code-review/ ├── cmd/opencodereview/ # CLI 入口——参数解析、分发 ├── internal/ │ ├── agent/ # 评审 agent 逻辑、子 agent 分发 │ ├── config/ # 模板、规则、白名单、内嵌 JSON │ ├── diff/ # Git diff 解析、三种模式 │ ├── gitcmd/ # Git 子进程运行器 │ ├── llm/ # LLM clientAnthropic 与 OpenAI、端点解析器 │ ├── model/ # 数据结构LlmComment、Diff…… │ ├── pathutil/ # 路径工具 │ ├── release/ # Release notes 生成 │ ├── session/ # JSONL 会话写入器 │ ├── stdout/ # 可静音的 stdout writer │ ├── suggestdiff/ # 建议 diff 渲染 │ ├── telemetry/ # OpenTelemetry 配置 辅助 │ ├── tool/ # 工具注册表 provider 实现 │ └── viewer/ # 内嵌 HTTP UI ├── pages/ # WebUI 营销页独立 React app ├── plugins/ # Claude Code slash 命令 ├── extensions/ # 编辑器扩展VS Code ├── examples/ # CI 配方GitHub Actions、GitLab CI ├── skills/ # Agent SDK skill manifest ├── scripts/ # NPM postinstall 跨平台构建脚本 ├── npm/ # 各平台 optional dependency 包 └── bin/ # NPM wrapperNode多数贡献触及internal/agent/、internal/tool/或internal/llm/。cmd/opencodereview/中的 CLI 层有意保持精简——它只负责参数解析随后把控制权分发到 agent 包这种薄 CLI 厚内部包的架构降低了命令行与核心逻辑的耦合也让单元测试可以聚焦于内部包。许可证头与代码质量检查许可证头每个源文件.go、.sh、.js、.mjs、.ts、.tsx都必须包含 SPDX 许可证头。创建新文件后请运行make license-add该命令由 scripts/add-license.sh 实现会自动为文件添加 Apache-2.0 头。CI 会拒绝缺少许可证头的 PR对应检查脚本为 scripts/verify-license.sh。开 PR 前的本地自检开 PR 前官方建议在本地依次运行三组命令make check # 格式化、静态检查、验证许可证头 make test # race-enabled, runs in CI on every push make build # smoke test the binary buildsCI 在每次推送时运行同一套检查因此本地先跑一遍可以避免无谓的失败循环。需要留意的是make test使用了-race -count1即开启数据竞争检测且不做结果缓存确保每次都是真实运行。添加新工具open-code-review 的评审能力由工具驱动模型通过调用工具来完成读文件、搜索代码、发表评论等动作。要添加一个新工具需要同时完成两部分工作两者都存在新工具名才能工作1. JSON 定义LLM 可见的接口在 internal/config/toolsconfig/tools.json 中添加工具的 JSON 定义包括name、description与 LLM 看到的 JSON-schema 参数。以内置的task_done工具为例{ name: task_done, plan_task: false, main_task: true, definition: { name: task_done, description: Call this tool to terminate task execution when you have completed the users task, such as when no obvious code issues are found during code review., parameters: { type: object, properties: { state: { type: string, enum: [DONE, FAILED], description: Defaults to DONE. Return FAILED if the task cannot be completed using available tools. } }, required: [state] } } }其中的plan_task与main_task字段决定工具出现在评审流水线的哪个阶段。从 toolsconfig.go 的实现看ToolDefsByPhase会按阶段过滤planOnlytrue只返回plan_task:true的工具否则只返回main_task:true的工具。也就是说同一个工具可以声明为只供 plan 阶段、只供主评审阶段或两阶段都可用。此外tools.json 通过//go:embed指令内嵌进二进制toolsconfig.go因此默认情况下运行时无需任何外部配置文件Load函数也支持传入自定义路径为空时回退到内嵌的默认定义。2. Go provider实际实现在internal/tool/definitions.go中注册对应的 Go provider包含实际实现。源码层面的核心契约有两个internal/tool/definitions.goProvider接口每个工具实现一个Provider包含Tool() Tool返回工具标识与Execute(ctx context.Context, args map[string]any) (string, error)执行工具并返回结果字符串。Registry注册表Register(p Provider)将 provider 注册进以工具名为 key 的 map注册完成后调用Freeze()冻结注册表此后任何Register调用都会 panic从机制上保证运行期工具集合不可变便于并发安全地读取。internal/tool/下现有的工具实现如 code_comment.go、file_read.go、code_search.go 等以及配套测试都可以作为新工具的模板。文档站中的工具说明列出了现有工具长什么样可当作参考。添加新规则模式open-code-review 内置了覆盖多种语言与文件类型的评审规则集。添加新的规则模式需要修改两个文件1. 更新 glob 映射编辑 internal/config/rules/system_rules.json把新的 glob 模式映射到规则文档。该文件由default_rule与path_rule_map两部分组成{ default_rule: default.md, path_rule_map: { **/*.go: go.md, **/*.java: java.md, **/*.{ts,js,tsx,jsx,mjs,cjs}: ts_js_tsx_jsx.md, **/*.{py,ipynb}: python.md, **/*.rs: rust.md, **/pom.xml: pom_xml.md, **/package.json: package_json.md, .github/workflows/**/*.{yaml,yml}: github_workflows.md } }default_rule是未匹配到任何模式时的兜底规则path_rule_map中的 key 是 doublestar 风格的 glob支持**跨目录匹配与{a,b}花括号扩展value 是rule_docs/下对应的规则文档文件名。2. 添加规则文档在internal/config/rules/rule_docs/目录下添加对应的 markdown 文档。规则文档按模式一个文件存放且为英文——每种被评审的文件类型如 go.md、java.md、yaml.md、terraform.md都有独立的规则说明文件。需要特别注意的是language配置的语义它只在 system prompt 中追加一条以该语言响应的指令不会切换 rule-doc 文件。也就是说即使配置了中文评审语言底层规则文档仍然是英文的语言设置只影响模型回复所用的语言。源码层面的一个精妙细节.m扩展名的内容嗅探从源码结构看规则解析层还有一个值得贡献者了解的细节.m扩展名在 MATLAB 与 Objective-C 之间是有歧义的。system_rules.json 将**/*.m映射到matlab.md但 sniffer.go 实现了内容嗅探当.m文件的首个非空行看起来像 Objective-C 时会改判为objc.mdsniffer.go。该嗅探器是无状态的不缓存探测结果因为它运行在并发按文件评审的 goroutine 中缓存反而需要加锁而探测每个.m文件最多只需一次读取代价可控。如果你要添加的新模式也存在扩展名歧义可以参考这个设计。PR 流程官方 PR 流程共有五步大改动先开 issue。提前对齐方向好过在代码评审时才发现分歧。每个 PR 一个逻辑变更。若有两个无关修复提两个 PR。更新测试。行为变更需测试覆盖——make test必须通过。更新文档。若变更影响参数、config key 或评审流水线同时更新本文档站与任何相关内联帮助。填写 PR 模板。维护者会评审通常几个工作日内。让你的 PR 更快被处理官方文档明确列出了几点有助于缩短审查周期的做法尽早签署 CLA— 很多首次贡献者因为忽略了 CLA bot 的评论而被卡住。一旦 bot 提示请立即签署贡献者许可协议——未签署 CLA 的 PR 无法被合并。确保所有 CI 检查通过— CI 未通过的 PR 不会被审查。推送前请在本地运行make test和make build提前发现问题。保持改动聚焦且精简— 只做一件事的 PR 远比混杂无关改动的 PR 更容易审查。越小的 PR 审查越快需要多轮修改的可能性也越低。撰写清晰、准确的描述— 说明改了什么以及为什么。描述必须与实际 diff 一致——两者不符会让审查者失去信任。如果开发过程中范围发生了变化请在请求审查前更新描述。为行为变更编写测试— 没有测试的新功能或缺陷修复会引发疑问。测试能证明正确性并帮助审查者理解预期行为。遵循现有代码风格— 与周围代码的风格、命名规范和架构保持一致。一致性降低审查者的认知负担也避免纯风格相关的评论。及时回应反馈— 审查者提出修改意见后请尽快处理以缩短审查周期。如果有不同意见请解释你的理由而不是忽略评论。贡献者许可协议CLA本项目要求 Alibaba Open Source CLA。首次开 PR 时会有 bot 在评论中贴出链接电子签署只需一分钟签署一次后后续 PR 无需重签。首次贡献如果你是第一次为项目做贡献可以寻找标了good first issue或help wanted标签的 issue。这类 issue 多数体量小且自包含描述中带有足够的上下文便于新手直接上手。另见架构——修改internal/agent/之前需要的心智模型。工具——现有工具的实现形态参考。完整贡献指南CONTRIBUTING.md。【免费下载链接】open-code-reviewFast, efficient, battle-tested at Alibabas scale. Hybrid architecture code review tool: deterministic pipelines LLM Agent, precise line-level comments, built-in multi-language ruleset (NPE, thread-safety, XSS, SQL injection), OpenAI Anthropic compatible.项目地址: https://gitcode.com/GitHub_Trending/op/open-code-review创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考