@alibaba-group/open-code-review 1.0.9 → 1.1.3

package/README.zh-CN.md

@@ -0,0 +1,288 @@
+<div align="center">
+
+[English](README.md) | 简体中文
+
+</div>
+
+# OpenCodeReview
+
+AI 驱动的代码审查 CLI 工具，读取 Git diff，通过具备工具调用能力的 Agent 将变更文件发送至可配置的 LLM，生成具有行级精度的结构化审查意见。
+
+Agent 可以读取完整文件内容、搜索代码库、检查其他变更文件以获取上下文，从而进行深度审查 —— 而非仅停留在表面的 diff 反馈。
+
+![Open Benchmark](imgs/open-benchmark.png)
+
+## 安装
+
+### 通过 NPM 安装（推荐）
+
+```bash
+npm install -g @alibaba-group/open-code-review
+```
+
+安装后，`ocr` 命令即可全局使用。
+
+### 从 GitHub Release 下载
+
+从 [GitHub Releases](https://github.com/alibaba/open-code-review/releases) 下载最新二进制文件：
+
+```bash
+# macOS (Apple Silicon)
+curl -Lo ocr https://github.com/alibaba/open-code-review/releases/latest/download/opencodereview-darwin-arm64
+chmod +x ocr && sudo mv ocr /usr/local/bin/ocr
+
+# macOS (Intel)
+curl -Lo ocr https://github.com/alibaba/open-code-review/releases/latest/download/opencodereview-darwin-amd64
+chmod +x ocr && sudo mv ocr /usr/local/bin/ocr
+
+# Linux (x86_64)
+curl -Lo ocr https://github.com/alibaba/open-code-review/releases/latest/download/opencodereview-linux-amd64
+chmod +x ocr && sudo mv ocr /usr/local/bin/ocr
+
+# Linux (ARM64)
+curl -Lo ocr https://github.com/alibaba/open-code-review/releases/latest/download/opencodereview-linux-arm64
+chmod +x ocr && sudo mv ocr /usr/local/bin/ocr
+```
+
+### 从源码构建
+
+```bash
+git clone https://github.com/alibaba/open-code-review.git
+cd open-code-review
+make build
+sudo cp dist/opencodereview /usr/local/bin/ocr
+```
+
+## 快速开始
+
+### 1. 配置 LLM
+
+**在审查代码之前，必须先配置 LLM。**
+
+```bash
+# 方式 A：交互式配置
+ocr config set llm.url https://api.anthropic.com/v1/messages
+ocr config set llm.auth_token your-api-key-here
+ocr config set llm.model claude-opus-4-6
+ocr config set llm.use_anthropic true
+
+# 方式 B：环境变量（优先级最高）
+export OCR_LLM_URL=https://api.anthropic.com/v1/messages
+export OCR_LLM_TOKEN=your-api-key-here
+export OCR_LLM_MODEL=claude-opus-4-6
+export OCR_USE_ANTHROPIC=true
+```
+
+配置存储于 `~/.open-code-review/config.json`。
+
+工具也会回退使用 Claude Code 环境变量（`ANTHROPIC_BASE_URL`、`ANTHROPIC_AUTH_TOKEN`、`ANTHROPIC_MODEL`），并解析 `~/.zshrc` / `~/.bashrc` 中的相关导出。
+
+### 2. 测试连通性
+
+```bash
+ocr llm test
+```
+
+### 3. 开始审查
+
+```bash
+cd your-project
+
+# 工作区模式 —— 审查所有暂存、未暂存和未跟踪的变更
+ocr review
+
+# 分支范围 —— 比较两个引用
+ocr review --from main --to feature-branch
+
+# 单个提交
+ocr review --commit abc123
+```
+
+## 命令
+
+| 命令 | 别名 | 描述 |
+|------|------|------|
+| `ocr review` | `ocr r` | 开始代码审查 |
+| `ocr config set <key> <value>` | — | 设置配置项 |
+| `ocr llm test` | — | 测试 LLM 连通性 |
+| `ocr viewer` | `ocr v` | 启动 WebUI 会话查看器，地址 `localhost:5483` |
+| `ocr version` | — | 显示版本信息 |
+
+### `ocr review` 参数
+
+| 参数 | 缩写 | 默认值 | 描述 |
+|------|------|--------|------|
+| `--repo` | — | 当前目录 | Git 仓库根目录 |
+| `--from` | — | — | 源引用（如 `main`） |
+| `--to` | — | — | 目标引用（如 `feature-branch`） |
+| `--commit` | `-c` | — | 审查单个提交 |
+| `--format` | `-f` | `text` | 输出格式：`text` 或 `json` |
+| `--concurrency` | — | `8` | 最大并发文件审查数 |
+| `--timeout` | — | `10` | 并发任务超时时间（分钟） |
+| `--audience` | — | `human` | `human`（显示进度）或 `agent`（仅输出摘要） |
+| `--rule` | — | — | 自定义 JSON 审查规则路径 |
+| `--tools` | — | — | 自定义 JSON 工具配置路径 |
+
+## 示例
+
+```bash
+# 使用默认设置审查工作区变更
+ocr review
+
+# 以更高并发审查分支差异
+ocr review --from main --to my-feature --concurrency 4
+
+# 审查特定提交并以 JSON 格式输出详细信息
+ocr review --commit abc123 --format json --audience agent
+
+# 使用自定义审查规则
+ocr review --rule /path/to/my-rules.json
+
+# 在浏览器中查看审查会话历史
+ocr viewer
+ocr viewer --addr :3000
+```
+
+## 评审规则
+
+OCR 通过四层优先级链解析评审规则。每层采用首次匹配原则：如果文件路径匹配到某个模式，则使用该规则；否则穿透到下一层。
+
+| 优先级 | 来源 | 路径 | 描述 |
+|--------|------|------|------|
+| 1（最高） | `--rule` 参数 | 用户指定路径 | CLI 显式覆盖 |
+| 2 | 项目配置 | `<repoDir>/.open-code-review/rule.json` | 项目级规则，可提交到 git |
+| 3 | 全局配置 | `~/.open-code-review/rule.json` | 用户级个人偏好 |
+| 4（最低） | 系统默认 | 内嵌 `system_rules.json` | 覆盖常见语言和文件类型的内置规则 |
+
+### 规则文件格式
+
+第 1–3 层使用相同的 JSON 格式：
+
+```json
+{
+  "rules": [
+    {
+      "path": "force-api/**/*.java",
+      "rule": "所有新方法必须对必填参数进行空值校验"
+    },
+    {
+      "path": "**/*mapper*.xml",
+      "rule": "检查 SQL 注入风险、参数错误和缺少闭合标签"
+    }
+  ]
+}
+```
+
+- `path` 支持 `**` 递归匹配和 `{java,kt}` 大括号展开。
+- 在每一层内，规则按声明顺序评估 —— 首次匹配生效。
+- 如果规则文件不存在，将被静默跳过。
+
+## 架构
+
+审查 Agent 遵循**三阶段工作流**：
+
+1. **计划阶段** —— 对于超过 50 行的变更，Agent 会在审查前进行风险分析。较小的 diff 直接跳至主阶段。
+2. **主任务循环** —— 每个变更文件分配独立的 goroutine。LLM 在对话循环中与内置工具交互（读取文件、搜索代码、读取 diff、提交评论），直到调用 `task_done`。
+3. **记忆压缩** —— 当提示上下文超过 token 阈值（异步 60%，同步 80%）时，Agent 使用三区分区（冻结 / 压缩 / 活跃）管理上下文窗口大小。
+
+### 关键设计决策
+
+- **按文件并发处理** —— 文件并行审查（默认 8 个 worker）。超时机制防止单个文件阻塞其他文件。
+- **双协议支持** —— 同时支持 Anthropic Messages API 和 OpenAI Chat Completions API，自动 URL 规范化。
+- **工具调用 Agent** —— LLM 可以访问领域特定工具（`code_search`、`file_read`、`code_comment`、`file_find`、`file_read_diff`），实现跨引用的上下文感知审查，而非孤立的 diff 扫描。
+
+## 配置参考
+
+配置文件：`~/.open-code-review/config.json`
+
+| 键 | 类型 | 示例 |
+|----|------|------|
+| `llm.url` | string | `https://api.openai.com/v1/chat/completions` |
+| `llm.auth_token` | string | `sk-xxxxxxx` |
+| `llm.model` | string | `claude-opus-4-6` |
+| `llm.use_anthropic` | boolean | `true` \| `false` |
+| `language` | string | `English` \| `Chinese`（默认：Chinese） |
+| `telemetry.enabled` | boolean | `true` \| `false` |
+| `telemetry.exporter` | string | `console` \| `otlp` |
+| `telemetry.otlp_endpoint` | string | OTLP 采集器地址 |
+| `telemetry.content_logging` | boolean | 在遥测数据中包含提示词 |
+
+环境变量优先级高于配置文件。
+
+### 环境变量
+
+| 变量 | 用途 |
+|------|------|
+| `OCR_LLM_URL` | LLM API 端点 URL |
+| `OCR_LLM_TOKEN` | API 密钥 / 认证令牌 |
+| `OCR_LLM_MODEL` | 模型名称 |
+| `OCR_USE_ANTHROPIC` | `true` = Anthropic，`false` = OpenAI |
+
+### 模板参数
+
+内部默认值定义于 `internal/config/template/task_template.json`：
+
+| 参数 | 默认值 | 描述 |
+|------|--------|------|
+| `MAX_TOKENS` | 58888 | 每次 LLM 请求最大 token 数 |
+| `MAX_TOOL_REQUEST_TIMES` | 20 | 每个文件最大工具调用迭代次数 |
+| `PLAN_MODE_LINE_THRESHOLD` | 50 | 低于此行数跳过计划阶段 |
+| `TOOL_REQUEST_WAIT_TIME_MS` | 10000 | 单次工具请求超时时间 |
+
+## 内置工具
+
+审查过程中 LLM Agent 可调用的工具：
+
+| 工具 | 可用阶段 | 用途 |
+|------|----------|------|
+| `task_done` | main_task | 终止审查（DONE/FAILED） |
+| `code_comment` | main_task | 提交行级审查意见 |
+| `file_read` | main_task | 按行范围读取文件内容 |
+| `code_search` | plan + main | 跨文件搜索文本/正则表达式 |
+| `file_read_diff` | plan + main | 查看其他变更文件的 diff 内容 |
+| `file_find` | plan + main | 按文件名关键词查找文件 |
+
+## 系统审查规则
+
+按文件类型通过 glob 模式匹配的内置审查清单，定义于 `internal/config/rules/system_rules.json`：
+
+| 模式 | 关注领域 |
+|------|----------|
+| `*.java` | NPE 风险、死循环、switch 穿透、N+1 查询、线程安全 |
+| `*.{ts,js,tsx,jsx}` | 代码质量、React 最佳实践、异步规范、XSS/安全 |
+| `*.kt` | 空安全、协程使用、惯用模式 |
+| `*{go,py,ets,lua,dart,swift,groovy}` | 逻辑缺陷、拼写错误 |
+| `*{cpp,cc,hpp}` | 智能指针、RAII、STL、const 正确性 |
+| `*.c` | malloc/free 配对、缓冲区溢出 |
+| `pom.xml` / `build.gradle` | 禁止 SNAPSHOT 版本 |
+| `package.json` | latest/通配符版本、依赖冲突 |
+| `*mapper*.xml` / `*dao*.xml` | SQL 注入、性能、逻辑错误 |
+| `*.properties` | 拼写检测、重复键、安全问题 |
+
+可通过 `--rule path/to/rules.json` 覆盖。
+
+## 遥测
+
+OpenTelemetry 集成，用于可观测性（spans、metrics）。默认关闭。
+
+```bash
+ocr config set telemetry.enabled true
+ocr config set telemetry.exporter otlp
+ocr config set telemetry.otlp_endpoint localhost:4317
+```
+
+设置 `telemetry.content_logging` 可在导出数据中包含 LLM 提示词和响应。
+
+## 开发
+
+```bash
+make build      # 为当前平台构建
+make test       # 带竞态检测运行测试
+make clean      # 清除 dist/
+make build-all  # 交叉编译（linux/amd64, linux/arm64, darwin/amd64, darwin/arm64）
+make dist       # 完整发布流水线
+```
+
+## 许可证
+
+[Apache-2.0](LICENSE) — Copyright 2026 Alibaba

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alibaba-group/open-code-review",
-  "version": "1.0.9",
+  "version": "1.1.3",
   "description": "OpenCodeReview CLI — AI-powered code review tool",
   "bin": {
     "ocr": "bin/ocr.js"

package/CHANGELOG.md

@@ -1,111 +0,0 @@
-# Changelog
-
-## v1.0.0 (2026-05-20)
-
-First public release of OpenCodeReview.
-
-- feat: AI-powered code review with OpenAI-compatible LLM endpoints
-- feat: three review modes — workspace changes, branch range, single commit
-- feat: Agent mode with context-aware file reading and `git grep` search
-- feat: plan phase for large diffs (>50 lines) with risk analysis
-- feat: concurrent file reviews with configurable parallelism
-- feat: session viewer WebUI for inspecting review history
-- feat: cross-platform support (linux/darwin, amd64/arm64)
-- feat: npm distribution with automatic binary download
-
-## v0.2.2 (2026-05-18)
-
-- feat(viewer): Enhance session viewer UI and tool call handling (d9a425a)
-- chore(release): bump version to v0.2.1 (e58eb56)
-
-
-## v0.2.1 (2026-05-16)
-
-- fix(version): correct program name output from 'opencodereview' to 'open-code-review' (a97ff48)
-- chore(release): bump version to v0.2.0 (2911231)
-
-
-## v0.2.0 (2026-05-16)
-
-- fix(publish): use sparse checkout in git add for internal repo copy (b9278cc)
-
-
-## v0.1.8 (2026-05-16)
-
-- feat: add User-Agent header and update LLM client context handling (93e02db)
-- chore(release): bump version to v0.1.7 (3586cf7)
-
-
-## v0.1.7 (2026-05-15)
-
-- fix: display timestamps in Asia/Shanghai timezone in viewer (0e02aaf)
-- feat: rm CHANGELOG.md (32ed4f4)
-- chore(release): bump version to v0.1.6 (b36b867)
-
-
-## v0.1.6 (2026-05-14)
-
-- chore: Optimize release process and change log management (16e28fb)
-- feat: task template to english (e54c56c)
-- feat: remove llm provider (acf2bb6)
-- chore(release): bump version to v0.1.5 (c3439c2)
-
-
-## v0.1.5 (2026-05-14)
-
-- refactor: rename per-file timeout to concurrent task timeout and improve CLI help docs (067084d)
-- chore(release): bump version to v0.1.4 (b6269d9)
-
-## v0.1.4 (2026-05-13)
-
-- feat: ocr.js 可执行权限 (3b1f793)
-- chore(release): bump version to v0.1.3 (33d6380)
-- feat: update publish readme (c79d952)
-
-## v0.1.3 (2026-05-13)
-
-- feat: remove deprecated sh (0ec83ae)
-- feat: 为 llm test 增加来源和 url (f40872f)
-- chore(release): bump version to v0.1.2 (92c4119)
-- feat: fix bug (d9f9cb3)
-
-## v0.1.2 (2026-05-13)
-
-- feat: 增加发包的 readme (1d4b783)
-- feat: 增加内部打包分发的脚本 (fd3b5d3)
-- feat: 增加内部打包分发的脚本 (01a809a)
-- feat: update --audience agent (8391e1e)
-- feat: update output note (dd12b72)
-- feat: update scripts/release.sh (1319f3a)
-- feat: Adding the  parameter distinguishes between human and agent input. (5f09e5e)
-- feat: fix tokens count (b73e05c)
-- feat: add TODO note (1135690)
-- feat: update Examples (2babfe8)
-- feat: 记忆压缩三层分区 + 双阈值异步压 (14adf6f)
-- feat: 四层模型端点，适配 anthropic (8a93673)
-- feat: 增加一些边界提示 (b680c29)
-- feat: 区分没有diff和没有评论的反馈 (a217a6f)
-- feat: --format json 模式下静默进度输出，保持 stdout 纯净 (5aea3ac)
-- feat: 增加 git 仓库校验 (39d02d1)
-- feat: 修改配置项内容 (22d93ed)
-- feat: 增加评论块与diff渲染 (d0e4832)
-- chore: 移除 .claude 追踪并更新 .gitignore (e99092a)
-- feat: 增加viewer能力 (d99e3eb)
-- feat: 配置化默认允许评审的文件 (576180d)
-- feat: 大diff拦截 (21a4b66)
-- feat: add license (2cd09e6)
-- feat: 修改文件名 (84df403)
-- feat: 更新readme (49cb629)
-- feat: token used 展示拆分成 input 和 output (1c76de0)
-- feat: 移除历史文件索引 (9589cb6)
-- feat: 支持类似claude code 会话历史的能力 (daa7181)
-- feat: add .gitignore (edd6854)
-- feat: 修复一些问题 (9ecadd7)
-- feat: 修复一些问题 (52e035d)
-- feat: 修复一些问题 (07b6ba2)
-- feat: 修复一些问题 (e2d6a54)
-- feat: 增加 --debug模式 (a896ba5)
-- feat: 修复评论重复的问题 (223a6ef)
-- feat: 改名 (2f2aaa1)
-- feat: argus 改名 opencodereview (3d2029d)
-- feat: 修复了一些问题 (9e449d5)