第 1 章 · 01 安装与首次运行

第 1 章 · 01 安装与首次运行

本节摘要:本节带你几分钟内跑通第一次 AI 代码评审。我们走四步:用 npm 全局安装 ocr CLI、配置 LLM provider(或用委托模式跳过)、测试连通性、对一次 git diff 运行评审。读完本节,你会得到第一份带行级精度的评审报告,并理解 OCR 的最小工作闭环。

内容来源:原项目中文文档 pages/src/content/docs/zh/quickstart.md + installation.md,套用体系化模板改写。

学习目标

阅读完本节,你应当能够:

1. 完成 OCR CLI 的安装与版本验证。
2. 配置好一个 LLM provider(或说明何时用委托模式免配置)。
3. 用 ocr llm test 验证连通性并解读常见错误。
4. 对一次 git diff 运行第一次评审并读懂输出。

一、前置条件

开始前确认:

• Git ≥ 2.41
• Node.js ≥ 18
• 一个 LLM API key(使用委托模式时可不要,见第 5 章)

💡 没有这些?Git 与 Node.js 各自官网安装即可;LLM key 可用 OpenAI / Anthropic / OpenRouter 任一家。委托模式(在 Claude Code 里跑)连 key 都不用。

二、安装 CLI

npm install -g @alibaba-group/open-code-review
​

验证安装:

ocr version
​

更多安装方式(各平台二进制、源码构建)详见第 2 章「安装」一节。

三、配置 LLM

如果你打算用委托模式(如在 Claude Code 中运行),宿主 agent 会提供模型——可直接跳到第五步。

交互式配置(推荐首次使用):

ocr config provider
​

它会让你:选择一个内置或自定义 provider → 填入 API key → 挑选 model → 保存到配置文件 → 自动跑一次 ocr llm test 验证端点。

之后想换模型:

ocr config model
​

非交互式备选(CI 友好)

在 CI 或无 TUI 的环境里,用 ocr config set 直接写入同一份配置:

ocr config set provider                    anthropic
ocr config set model                       claude-opus-4-6
ocr config set providers.anthropic.api_key sk-ant-xxxxxxxxxx
​

💡 为什么要非交互式:CI 环境没有终端交互,ocr config set 让你用一行行命令把配置写死,这对 GitHub Actions / GitLab CI 集成(第 5 章)至关重要。

四、测试连通性

ocr llm test
​

常见错误解读:

• no valid LLM endpoint configured → 回到第三步检查配置。
• 401 / 403 → token 错误或已过期,换一个有效 key。

五、运行第一次评审

在任意 git 仓库(有未提交的改动或刚 commit 的变更)目录下:

ocr review
​

OCR 会:读取当前 git diff → 把变更文件发给配置好的 LLM agent → 产出带行级精度的结构化评审意见(指出具体文件、具体行、问题类型、建议修改)。

⚠️ 第一次评审的预期管理:OCR 审的是「这次变更引入了什么问题」,不是「整个代码库好不好」。它聚焦 diff,所以对新加的代码最有效;对历史遗留代码的全面审查要配合其它工具。

本节要点回顾

1. 前置:Git ≥ 2.41、Node.js ≥ 18、一个 LLM key(委托模式可免)。
2. 安装:npm install -g @alibaba-group/open-code-review + ocr version 验证。
3. 配置:首次用 ocr config provider 交互式;CI 用 ocr config set 非交互式。
4. 连通性:ocr llm test,401/403 多半是 key 问题。
5. 首次评审:ocr review 读 diff → 发 agent → 行级结构化意见。
6. 定位:OCR 审的是「这次变更引入的问题」,聚焦 diff,对新代码最有效。

下一节(若展开 installation)会讲各平台二进制与源码构建;接下来进入第 2 章,我们把所有配置项与 CLI 参数讲透,让你把工具调到顺手。