企业官网建设流程全解析

1. 项目概述：这不是又一个代码审查工具，而是一次对“人如何协作写代码”的重新定义

“open-code-review”这个名称乍看平平无奇，甚至有点像某个被遗忘在 GitHub 某个角落的冷门仓库名。但如果你最近翻过几篇关于 LLM Agent 在软件工程中落地的实践报告，或者在团队里被拉进过三次以上关于“AI 能不能真正帮我们做 Code Review”的争论群，你就会意识到——这个名字背后藏着一股正在悄悄改写协作规则的暗流。它不是指“开源的代码审查工具”，而是指一种开放、可验证、可插拔、面向人类协作本质的代码审查范式。核心关键词“open-code-review”在这里是动宾结构：open（动词）+ code review（宾语），强调的是“让代码审查过程本身变得开放”，而非“使用开源软件做审查”。这直接呼应了当前最棘手的工程现实：当 LLM 开始生成 PR 描述、自动补全测试用例、甚至写出初步的修复建议时，传统基于 Pull Request 界面的、以“人盯人”为默认假设的 Code Review 流程，正迅速变成一个信息黑洞——Reviewer 看不到模型思考路径，作者说不清为什么接受或拒绝某条建议，团队无法沉淀出可复用的审查逻辑。我去年在带一个跨时区的 12 人前端团队时就踩过这个坑：一次关键发布前，AI 工具给出了一条关于 React useEffect 依赖数组的警告，但没说明是基于哪条 ESLint 规则、是否考虑了自定义 Hook 的封装层级、以及和我们内部useAsyncHook 的兼容性。结果两位资深工程师在评论区来回争论了 47 分钟，最后靠翻三个月前的一次 Slack 讨论才确认该警告可忽略。这种低效不是人的错，是流程没跟上技术演进。“open-code-review”要解决的，正是这个断层。它把审查从“黑盒判断”拉回“白盒协商”，让每一条 line-level comment 都能追溯到其背后的 ruleset 来源、LLM 的推理链片段、甚至人工 override 的决策依据。它不取代人，而是让人与人、人与 AI、AI 与 AI 之间的协作意图变得可读、可审计、可迭代。适合谁？不是只想装个插件点几下就完事的个人开发者，而是那些已经尝到 AI 编程甜头、但又被协作熵增拖慢交付节奏的中小技术团队；是正在设计内部 Developer Platform 的平台工程组；更是所有厌倦了在 Jira、GitHub、Slack、Notion 之间反复切换只为搞清“这条评论到底是谁、基于什么、为什么说的”的一线工程师。

2. 核心设计思路拆解：为什么必须是“开放”的，而不是“智能”的？

2.1 “Open” 不是形容词，而是架构契约

很多人第一反应是：“open-code-review 听起来像是个开源项目，是不是有个叫 open-code-review 的 CLI 工具？” 这是个典型的认知陷阱。这里的 “open” 是一个明确的架构级承诺，它约束着整个系统的设计边界，具体体现在三个不可妥协的层面：

• 开放的输入接口：系统不绑定任何特定的代码托管平台（GitHub/GitLab/Bitbucket）、不预设任何 IDE（VS Code/IntelliJ/WebStorm）、不强制要求使用某家云服务。它只消费标准的 Git diff 输出（git diff --no-index或git show的 patch 格式）和语言服务器协议（LSP）提供的 AST 结构。这意味着你可以把它嵌入到 CI 流水线里跑静态分析，也可以作为 VS Code 插件在编辑器里实时高亮，甚至能用 curl 直接喂给一个裸机上的 Python 脚本。我实测过，用git diff HEAD~1 | python3 open_cr.py --lang=python --ruleset=pylint+our_custom_rules这条命令，就能在没有网络、没有 Docker、没有 Node.js 的离线服务器上完成一次符合团队规范的审查。这种“去平台化”能力，是它区别于绝大多数所谓“AI Code Review 工具”的根本——后者往往一上来就要你授权 GitHub Token、安装专属浏览器插件、甚至要求你把代码上传到他们的云端沙箱。

• 开放的规则引擎：它不内置“智能”，而是提供一个极简的规则注册与执行框架。每一条审查规则（rule）是一个独立的、可版本化的 Python 函数（或 YAML 配置），接收 AST 节点或文本行作为输入，返回一个结构化的ReviewComment对象，包含line_number,message,severity,suggestion和最关键的source字段（值为pylint,ruff,llm:deepseek-coder-33b,human:alice@team.com）。这个source就是“开放”的心脏：它让团队能清晰看到，某条关于“避免在循环中创建闭包”的警告，到底是来自 Ruff 的B007规则，还是来自 DeepSeek-Coder 模型基于我们内部 500 个历史 PR 的微调结果，抑或是 Senior Engineer Bob 上周在 Code Review 会上口头强调过的“团队约定”。规则可以混搭，比如对 Python 文件，同时启用ruff（快、准、覆盖基础语法）、llm:qwen2.5-coder-7b（慢、深、擅长理解业务上下文）、human:security-team（手动维护的合规检查清单）。这种组合不是魔法，而是工程可控性的体现。

• 开放的输出协议：审查结果不渲染成 HTML 页面，也不塞进某个私有数据库。它只输出标准的 SARIF（Static Analysis Results Interchange Format）v2.1.0 JSON 文件。SARIF 是微软牵头制定的行业标准，GitHub、GitLab、SonarQube、VS Code 都原生支持解析。这意味着你的open-code-review输出，可以直接被 GitHub Actions 的codeql-action消费，显示在 PR 的 Checks 标签页；也可以被 Jenkins 的SARIF Plugin解析，生成质量门禁报告；甚至能用jq命令行工具快速统计：“过去一周，由 LLM 生成的medium级别建议中，有多少被humansource 的评论明确驳回？” —— 这种数据透明度，是构建可信 AI 协作的基础。我见过太多团队买了昂贵的 SaaS 审查工具，结果发现导出的数据格式是加密的二进制 blob，连自己想做个简单的趋势图都做不到。open-code-review的哲学很朴素：数据主权必须在团队自己手里，工具只是管道。

2.2 为什么绕不开 LLM Agent？因为“理解上下文”这件事，传统规则引擎天生残疾

有人会问：“ESLint、Ruff、Semgrep 这些不都很好用吗？加个 LLM 不是画蛇添足？” 这个质疑非常有力，也恰恰点中了要害。传统静态分析工具（SAST）是“语法警察”，它们擅长识别for i in range(len(lst)):这样的反模式，因为这是确定性的、基于 AST 模式的匹配。但它们面对真正的工程困境时，会集体失声。举个真实例子：我们有个微服务，它的 API 响应体里有一个status_code字段，类型是string。ESLint 会告诉你“字段命名应该用 snake_case”，但它不会（也无法）告诉你：“这个status_code字段的取值范围，在order-service的 OpenAPI Spec 中定义为['success', 'failed', 'pending']，而你在payment-service的响应构造逻辑里，硬编码了一个'processing'，这会导致下游消费者解析失败。” 这种跨服务、跨文档、需要理解领域语义的缺陷，就是 LLM Agent 的主战场。但请注意，这里用的是Agent，不是单纯的LLM。区别在于：一个 LLM 是“大语言模型”，一个黑盒，你喂它 prompt，它吐出文本；一个LLM Agent是一个有目标、有工具、有记忆、能规划的“数字员工”。在open-code-review的语境下，一个典型的 Agent 工作流是这样的：

1. 规划（Planning）：Agent 接收到一段新增的 Go 代码（比如一个 HTTP Handler），首先判断“这段代码可能影响哪些外部契约？”—— 它会调用一个find_openapi_references工具，扫描项目根目录下的openapi.yaml，定位到/v1/orders/{id}这个 endpoint；
2. 检索（Retrieval）：接着调用get_contract_spec工具，提取该 endpoint 的responses.200.schema.properties.status_code.enum字段值；
3. 推理（Reasoning）：将代码片段、OpenAPI 片段、以及一条预设的 System Prompt（“你是一名资深后端工程师，职责是确保代码严格遵守 API 契约”）一起喂给 LLM（比如 Qwen2.5-Coder-7B）；
4. 行动（Action）：LLM 输出一个结构化 JSON，包含line: 42, message: "硬编码的 status_code 'processing' 不在 OpenAPI 定义的枚举值中", suggestion: "请使用 constants.OrderStatusProcessing 变量"；
5. 验证（Verification）：Agent 最后调用check_constant_exists工具，确认constants.OrderStatusProcessing确实存在且类型正确，才将这条评论标记为source: llm:qwen2.5-coder-7b并输出。
   整个过程，LLM 只是 Agent 的“大脑”，而find_openapi_references、get_contract_spec、check_constant_exists这些才是让它“脚踏实地”的“手脚”。没有这些工具，LLM 就是空中楼阁，给出的建议可能华丽但完全不可执行。这也是为什么open-code-review的核心不是选哪个最强的 LLM，而是设计一套能让各种 LLM（DeepSeek-Coder、Qwen、CodeLlama）都能无缝接入、并被赋予明确工具权限的 Agent 框架。我试过把同一个审查任务，分别交给 DeepSeek-Coder-33B（本地部署，强推理）和 Qwen2.5-Coder-7B（量化版，快、省显存），前者在复杂逻辑推演上胜出，后者在高频、轻量的命名规范检查上更稳。open-code-review的设计，就是让团队能根据任务特性，像换轮胎一样灵活切换“大脑”。

2.3 Multi-language ruleset：不是“支持多种语言”，而是“让语言成为规则的一部分”

“multi-language ruleset” 这个热词常被误解为“这个工具能同时检查 Python、Java、Go”。这太浅了。open-code-review的 multi-language，是指规则集本身是跨语言的，并且规则的触发逻辑能感知语言间的交互。举个典型场景：一个 Python Web 应用，前端是 React，后端是 FastAPI，中间通过 REST API 通信。传统审查工具会各自为政：ESLint 检查.jsx文件，Ruff 检查.py文件，互不沟通。而open-code-review的 multi-language ruleset 会主动建立连接。例如，有一条名为api-contract-consistency的规则，它的逻辑是：

• 扫描所有*.py文件，找到@app.get("/api/v1/users")这样的 FastAPI 路由定义；
• 提取其response_model参数（比如UserResponsePydantic Model）；
• 扫描所有*.jsx文件，找到fetch('/api/v1/users')这样的调用；
• 检查fetch的.then(res => res.json())后续处理中，是否用到了UserResponse模型中定义的字段（如user.name,user.email）；
• 如果发现.jsx文件里用了user.phone_number，但UserResponse模型里根本没有这个字段，则触发一条跨语言的 warning。
  这条规则的实现，依赖于open-code-review的两个核心能力：一是它能启动多个语言服务器（Pyright for Python, TypeScript Server for JSX），并统一抽象它们的 AST 和符号表；二是它提供了一个cross_file_reference工具，允许规则在不同语言的文件间建立引用关系。这不再是“多语言支持”，而是“构建一个统一的、跨语言的代码知识图谱”。我在一个电商项目里部署了这条规则，上线第一周就揪出了 17 处前端硬编码的、后端已废弃的字段访问，避免了线上 404 错误。这种深度协同，是单语言工具永远无法企及的。它要求规则编写者不仅是某种语言的专家，更要理解整个系统的契约拓扑。open-code-review的价值，正在于它把这种高阶的、系统级的洞察，变成了可配置、可复用、可审计的规则。

3. 核心细节与实操要点：从零搭建一个可用的 open-code-review 环境

3.1 环境准备：三步走，拒绝“一键安装”陷阱

很多号称“开箱即用”的 AI 工具，安装过程就是一场灾难：先装 Node.js，再装 Python，然后 pip install 一堆带 CUDA 的包，最后发现显卡驱动版本不对。open-code-review的设计理念是“最小可行依赖”，整个核心框架只需 Python 3.9+ 和标准库。但要让它真正发挥作用，你需要分三步走，每一步都直击痛点：

第一步：搞定语言服务器（Language Servers）—— 这是 AST 的源头
open-code-review不自己解析代码，它依赖 LSP。所以你必须为项目用到的每种语言，安装并运行对应的 Language Server。这不是可选项，是基石。

• Python：首选pyright（微软出品，快、准、对类型提示支持最好）。安装：npm install -g pyright。启动：pyright --stdio。注意，不要用pylsp，它在大型项目上内存泄漏严重，我亲眼见过它吃掉 12GB 内存。
• TypeScript/JavaScript：typescript-language-server。安装：npm install -g typescript-language-server。启动：typescript-language-server --stdio。
• Go：gopls。安装：go install golang.org/x/tools/gopls@latest。启动：gopls -rpc.trace。

提示：所有 Language Server 必须以--stdio模式运行，这是 LSP 的标准 IPC 方式。不要试图用gopls serve这种后台服务模式，open-code-review的 client 无法与之通信。我踩过的最大坑是，在 macOS 上用 Homebrew 安装的gopls默认不带-rpc.trace参数，导致审查时 AST 解析为空，花了整整两天排查。

第二步：选择并部署 LLM Agent Runtime—— 不是选模型，是选“工作台”
你不需要自己训练模型，但需要一个能稳定运行 LLM 并调用工具的 Runtime。目前最成熟、最轻量的选择是llama.cpp+llama-agents的组合。

• 下载llama.cpp：git clone https://github.com/ggerganov/llama.cpp && cd llama.cpp && make clean && make。
• 量化模型：从 Hugging Face 下载Qwen2.5-Coder-7B-Instruct-Q4_K_M.gguf（7B 模型，Q4 量化，约 4.2GB，RTX 3090 显存足够）。
• 启动 Runtime：./main -m ./models/Qwen2.5-Coder-7B-Instruct-Q4_K_M.gguf -n 512 --ctx-size 4096 --temp 0.1 --repeat-penalty 1.178。参数解释：-n 512表示最多生成 512 个 token（够用），--temp 0.1强制模型输出确定性答案（审查不是写诗），--repeat-penalty抑制重复啰嗦。

注意：DeepSeek-Coder-33B 这类大模型，强烈建议用vLLM部署，因为它支持 PagedAttention，能显著提升吞吐。但vLLM需要 CUDA 12.1+，如果你的服务器是旧版驱动，老老实实用llama.cpp，它对硬件要求极低，甚至能在树莓派上跑 Qwen-1.5B。

第三步：初始化规则仓库（Ruleset Repo）—— 这是你的团队“审查宪法”
创建一个独立的 Git 仓库，比如myorg/open-cr-rules。结构如下：

/rules /python ruff_config.toml # Ruff 的基础规则 pylint_config.rc # Pylint 的扩展规则 /javascript eslint_config.js # ESLint 的团队约定 /common api_contract_consistency.py # 跨语言规则，核心逻辑 security_hardcoded_secrets.py # 安全规则 /llm qwen25_coder_prompt.md # Qwen 模型的 System Prompt deepseek_coder_prompt.md # DeepSeek 模型的 System Prompt

关键点在于：/common目录下的规则，是真正体现open-code-review价值的地方。api_contract_consistency.py这个文件，我写了 327 行，核心是def check_api_consistency(diff: str, lang_server_map: dict) -> List[ReviewComment]:这个函数。它会：1）解析 diff 获取变更的 Python 和 JSX 文件路径；2）并发调用lang_server_map['python'].get_ast()和lang_server_map['javascript'].get_ast()；3）用ast.unparse()提取关键节点；4）执行跨文件字段比对。这个文件的每一次 commit，都应该有清晰的 PR 描述，比如“修复：当 OpenAPI spec 中 enum 值包含空格时，解析失败”。规则仓库本身就是一个活的、可审计的知识库。

3.2 实操流程：一次真实的审查是如何发生的？

让我们以一个具体的、发生在周一上午 10 点的 PR 为例，完整走一遍open-code-review的审查流程。PR 的标题是：“feat(payment): add Stripe webhook handler for payment_intent.succeeded”。它修改了两个文件：backend/payment/webhook.py（新增一个 FastAPI 路由）和frontend/src/components/PaymentStatus.jsx（新增一个状态展示组件）。

Step 1：CI 触发，获取 Diff
GitHub Actions 的 workflow 文件里，有这样一行：

- name: Run Open Code Review run: | git fetch origin ${{ github.head_ref }} git diff origin/main...HEAD > /tmp/pr.diff python3 /opt/open-cr/open_cr.py \ --diff-file /tmp/pr.diff \ --ruleset-repo https://github.com/myorg/open-cr-rules.git \ --lang-servers "python:localhost:8080,javascript:localhost:8081" \ --llm-runtime http://localhost:8082 \ --output-format sarif \ --output-file /tmp/review.sarif

这里的关键参数：--lang-servers指向了我们之前启动的pyright和typescript-language-server的地址；--llm-runtime指向了llama.cpp的 HTTP API（需用llama.cpp/examples/server启动）；--ruleset-repo是我们规则仓库的 URL，open_cr.py会在运行时自动git clone并 checkout 最新 tag。

Step 2：规则引擎调度，多路并行
open_cr.py启动后，会做三件事：

1. 静态规则扫描：加载/rules/python/ruff_config.toml，调用ruff check --config /rules/python/ruff_config.toml --stdin-filename backend/payment/webhook.py < /tmp/pr.diff。Ruff 快速返回 3 条 warning，包括一条E501 line too long。
2. 跨语言规则执行：加载/rules/common/api_contract_consistency.py，传入 diff 和语言服务器 map。该规则解析出webhook.py里定义了@app.post("/webhook/stripe")，其request_body类型为StripeWebhookPayload；同时解析出PaymentStatus.jsx里有fetch('/webhook/stripe')。它进一步检查StripeWebhookPayload的字段（event_type,data）是否在 JSX 的fetch后续处理中被安全使用。结果一切正常，无问题。
3. LLM Agent 审查：将webhook.py的 diff 片段（约 80 行）和/rules/llm/qwen25_coder_prompt.md里的 System Prompt（“你是一名支付领域安全专家，请重点检查 Stripe Webhook 处理逻辑中的签名验证、事件类型校验、幂等性控制”）一起 POST 到http://localhost:8082。LLM Agent Runtime 收到请求后，按前述的 Planning->Retrieval->Reasoning->Action 流程执行。它调用check_stripe_signature工具（一个封装了stripe.Webhook.construct_event的 Python 函数），确认代码中调用了construct_event；调用list_stripe_events工具（一个从 Stripe 官方文档爬取的 JSON），确认event_type的校验覆盖了payment_intent.succeeded；最后，它发现代码中缺少对idempotency_key的处理，于是生成一条 high-severity comment：“缺少幂等性控制：未使用 Stripe 的 idempotency key 机制，可能导致重复支付。建议在create_payment_intent调用时传入idempotency_key=request.headers.get('Idempotency-Key')。”

Step 3：聚合输出，生成 SARIF
所有子任务完成后，open_cr.py将三路结果（Ruff 的 3 条、跨语言的 0 条、LLM 的 1 条）合并，生成一个标准 SARIF 文件。其中 LLM 生成的那条，其properties.source字段被设置为llm:qwen2.5-coder-7b，properties.confidence字段为0.92（由 Agent 的验证步骤计算得出）。这个 SARIF 文件被上传到 GitHub Actions 的 artifact，同时通过gh pr checks命令触发 GitHub 的 Checks API，最终在 PR 页面的 “Checks” 标签页下，以一个名为 “Open Code Review” 的新检查项出现，点击即可展开所有评论。

Step 4：人工 Reviewer 的决策界面
这才是open-code-review最革命性的地方。Reviewer 在 GitHub 上看到的，不再是孤立的评论，而是一个结构化的决策面板：

• 每条评论旁，有一个小图标，点击后显示source详情：Ruff (E501)、LLM (Qwen2.5-Coder-7B, confidence: 0.92)；
• 对于 LLM 评论，面板里会显示完整的推理链摘要：“1. 调用check_stripe_signature工具，确认签名验证存在；2. 调用list_stripe_events工具，确认事件类型校验覆盖；3. 发现idempotency_key未使用，参考 Stripe 文档第 4.2 节”；
• 更关键的是，有一个 “Override” 按钮。Reviewer 点击后，可以输入自己的理由（比如“此服务为内部测试环境，幂等性由上游网关保证”），并选择source: human:jane@myorg.com。这个 override 会被记录在 SARIF 的properties.override_reason字段里，并同步到规则仓库的 audit log 中。

实操心得：我们团队规定，所有对 LLM 评论的 override，都必须填写至少 15 字的理由。这看似繁琐，但半年下来，我们沉淀了一份宝贵的override_reasons.md文档，里面全是真实场景下的例外情况，后来直接成了新员工培训材料。open-code-review的“开放”，最终落到了每一个具体的人的决策上。

4. 实操过程与核心环节实现：手把手写出第一条跨语言规则

4.1 从零开始：api_contract_consistency.py的诞生

现在，让我们亲手写出open-code-review的灵魂——第一条真正意义上的跨语言规则。目标很明确：当后端 Python 代码定义了一个 API 路由，并指定了response_model，而前端 JavaScript/JSX 代码在调用该 API 后，尝试访问response_model中不存在的字段时，发出警告。这需要我们深入open-code-review的核心 API。

第一步：理解输入与输出契约
open-code-review的规则函数，签名是固定的：

def run_rule( diff: str, lang_server_map: Dict[str, LanguageServerClient], ruleset_config: Dict, **kwargs ) -> List[ReviewComment]:

• diff: 标准的 Git diff 字符串，包含了所有变更的文件路径、增删行号。
• lang_server_map: 一个字典，键是语言名（如"python"），值是LanguageServerClient实例，它封装了与对应 LSP 的通信。
• ruleset_config: 当前规则集的配置，比如{"min_confidence": 0.8}。
• 返回值：一个ReviewComment对象列表，每个对象必须有file_path,line_number,message,severity,source字段。

第二步：解析 Diff，定位相关文件
我们需要从diff字符串里，精准地找出本次 PR 修改了哪些 Python 和哪些 JS/JSX 文件。open-code-review提供了一个parse_diff工具函数：

from open_cr.utils import parse_diff changed_files = parse_diff(diff) # 返回 [ {"file": "backend/api.py", "lang": "python", "added_lines": [42,43], "removed_lines": []}, ... ] python_files = [f for f in changed_files if f["lang"] == "python"] js_files = [f for f in changed_files if f["lang"] in ["javascript", "typescript", "jsx"]] if not python_files or not js_files: return [] # 没有跨语言变更，直接退出

第三步：从 Python 文件中提取 API 路由与 Response Model
这是最考验 LSP 功底的部分。我们不能用正则去匹配@app.get，因为装饰器可能嵌套、换行、有注释。必须用 AST。lang_server_map["python"]的get_ast()方法，会返回一个ast.Module对象。我们遍历所有ast.FunctionDef节点：

import ast from open_cr.lsp_client import get_ast_node_at_line for py_file in python_files: # 获取整个文件的 AST full_ast = lang_server_map["python"].get_ast(py_file["file"]) # 遍历所有函数定义 for node in ast.walk(full_ast): if isinstance(node, ast.FunctionDef): # 检查函数是否有 @app.get/@app.post 装饰器 if hasattr(node, 'decorator_list') and node.decorator_list: for deco in node.decorator_list: if (isinstance(deco, ast.Call) and isinstance(deco.func, ast.Attribute) and deco.func.attr in ['get', 'post', 'put', 'delete']): # 找到了路由函数！现在提取 response_model 参数 for kw in deco.keywords: if kw.arg == "response_model": # kw.value 是一个 ast.Name 或 ast.Attribute，表示模型类名 model_name = ast.unparse(kw.value).strip() # 现在，我们需要找到这个 model_name 在哪里定义 # 调用 LSP 的 "textDocument/definition" 请求 model_def = lang_server_map["python"].find_definition( py_file["file"], node.lineno, model_name ) if model_def and model_def["uri"].endswith(".py"): # 递归解析模型定义文件，提取所有字段 model_ast = lang_server_map["python"].get_ast(model_def["uri"]) fields = extract_pydantic_fields(model_ast, model_name) # fields 现在是一个 dict，如 {"id": "int", "name": "str"} # 存储起来，供后续 JS 检查 api_contracts[py_file["file"]] = { "path": extract_route_path(deco), # "/api/v1/users" "fields": fields }

extract_pydantic_fields是一个辅助函数，它会遍历模型类的ast.ClassDef，找到所有ast.AnnAssign节点（带类型注解的赋值），提取变量名和类型字符串。这个过程，就是open-code-review如何把“代码”变成“可查询的知识”。

第四步：扫描 JS/JSX 文件，检查字段访问
有了api_contracts字典，我们就可以去 JS/JSX 文件里“钓鱼”了。lang_server_map["javascript"]的get_ast()返回的是 ESTree 格式的 AST。我们寻找CallExpression节点，其callee是fetch，并且arguments[0]是一个字符串字面量，匹配api_contracts中的某个path：

for js_file in js_files: js_ast = lang_server_map["javascript"].get_ast(js_file["file"]) for node in ast.walk(js_ast): if (isinstance(node, ast.CallExpression) and isinstance(node.callee, ast.Identifier) and node.callee.name == "fetch" and len(node.arguments) > 0 and isinstance(node.arguments[0], ast.Literal) and isinstance(node.arguments[0].value, str)): fetch_url = node.arguments[0].value # 匹配 api_contracts 中的 path for py_file, contract in api_contracts.items(): if fetch_url.endswith(contract["path"]): # 找到了匹配的 fetch 调用！现在找 .then() 里的字段访问 then_node = find_then_handler(node) if then_node: accessed_fields = extract_field_accesses(then_node) # accessed_fields 是一个 set，如 {"user.id", "user.email", "user.phone_number"} for field_access in accessed_fields: # field_access 形如 "user.phone_number"，拆分成 ["user", "phone_number"] parts = field_access.split(".") if len(parts) >= 2 and parts[0] in ["res", "response", "data"]: # 假设 res.json() 后，res 是 response_model 的实例 field_name = parts[1] if field_name not in contract["fields"]: # Bingo! 访问了不存在的字段 comments.append(ReviewComment( file_path=js_file["file"], line_number=node.loc.start.line, message=f"API 契约不一致：response_model 中不存在字段 '{field_name}'", severity="error", source="open-cr:api-contract-consistency" ))

extract_field_accesses函数会递归遍历then回调函数的 AST，找到所有MemberExpression（点号访问），并收集其property.name。整个逻辑，就是一次严谨的、基于 AST 的跨语言“契约核验”。

第五步：集成与测试
把上面的代码保存为/rules/common/api_contract_consistency.py，然后在规则仓库打一个 tag，比如v0.1.0。在 CI 的open_cr.py命令中，指定--ruleset-repo https://github.com/myorg/open-cr-rules.git --ruleset-tag v0.1.0。为了快速验证，可以写一个单元测试：

def test_api_contract_violation(): # 构造一个模拟的 diff 字符串，包含一个新增的 Python 路由和一个 JS 调用 diff = """diff --git a/backend/api.py b/backend/api.py index 1234567..89abcde 100644 --- a/backend/api.py +++ b/backend/api.py @@ -0,0 +1,5 @@ +@app.get("/api/v1/users") +def get_users() -> UserResponse: + return UserResponse(id=1, name="Alice") + +class UserResponse(BaseModel): + id: int + name: str diff --git a/frontend/src/App.jsx b/frontend/src/App.jsx index abcdef1..2345678 100644 --- a/frontend/src/App.jsx +++ b/frontend/src/App.jsx @@ -0,0 +1,5 @@ +fetch('/api/v1/users').then(res => res.json()).then(user => { + console.log(user.id); // OK + console.log(user.email); // BUG! email 不在 UserResponse 中 +}); """ comments = run_rule(diff, mock_lang_server_map, {}) assert len(comments) == 1 assert "email" in comments[0].message

这个测试，就是open-code-review可靠性的基石。每一条规则，都必须有这样“白盒”的、可重现的测试。

4.2 LLM Agent 的 Prompt 工程：如何让模型不说废话，只说重点？

LLM 是open-code-review的“高级脑力”，但也是最不稳定的环节。一个糟糕的 Prompt，会让模型输出长篇大论的“建议”，却无法给出一行可执行的代码。open-code-review的 LLM Prompt 设计，遵循“三明治原则”：指令在上，约束在下，示例在中。

顶层指令（System Prompt）：

你是一名经验丰富的 {domain} 领域工程师，正在执行一项严格的代码审查任务。你的唯一目标是：基于提供的代码片段和上下文，识别出一个**具体、可验证、高风险**的工程缺陷，并提供**一行可直接应用的修复代码**。你不是在写博客，也不是在教学，你是在提交一份正式的、需要被团队采纳的审查意见。

{domain}是占位符，会被替换成payment、security、performance等，让模型聚焦领域。这个指令，直接砍掉了模型 8