code-argus

自动化 AI 代码审查 CLI 工具 - 基于多智能体架构的 Git Diff 分析与问题检测

English | 中文

功能特性

• 多智能体并行审查 - 4 个专业 Agent 并发运行：安全、逻辑、性能、风格
• 智能 Agent 选择 - 根据文件特征自动选择需要运行的 Agent
• 问题验证 - 挑战模式多轮验证，显著降低误报率
• 实时去重 - 两层去重机制：快速规则检查 + LLM 语义验证
• 项目标准感知 - 自动提取 ESLint/TypeScript/Prettier 配置
• 自定义规则 - 支持团队级审查规则和检查清单
• 增量审查 - 只审查新增的提交，提升效率
• 服务集成 - JSON 事件流输出，便于 CI/CD 和外部服务集成

安装

全局安装（推荐）

npm install -g code-argus

使用 npx

npx code-argus review /path/to/repo feature-branch main

从源码安装

git clone https://github.com/anthropics/code-argus.git
cd code-argus/core
npm install
npm run build
npm link

配置

API 密钥

设置 Anthropic API 密钥：

# 方式一：环境变量
export ANTHROPIC_API_KEY=your-api-key

# 方式二：.env 文件
echo "ANTHROPIC_API_KEY=your-api-key" > .env

# 方式三：使用 config 命令（推荐）
argus config set api-key sk-ant-xxx

配置管理

# 设置配置
argus config set api-key sk-ant-xxx      # API 密钥
argus config set base-url https://proxy  # 自定义代理 URL
argus config set model claude-sonnet-4-5-20250929  # 模型

# 查看配置
argus config list                         # 列出所有配置
argus config get api-key                  # 获取单个配置
argus config path                         # 显示配置文件路径

# 删除配置
argus config delete base-url

使用方法

命令格式

argus <command> <repoPath> <sourceBranch> <targetBranch> [options]

命令

| 命令 | 说明 | | -------- | ------------------------------------- | | review | 完整 AI 代码审查（多 Agent 并行审查） | | config | 配置管理 |

参数

| 参数 | 说明 | | ---------- | ----------------------------------- | | repoPath | Git 仓库路径 | | source | 源分支名或 commit SHA（自动检测） | | target | 目标分支名或 commit SHA（自动检测） |

自动检测：

• 分支名：使用三点式 diff（origin/target...origin/source）
• Commit SHA：使用两点式 diff（target..source）用于增量审查

选项详解

--json-logs

输出 JSON 事件流，用于服务集成

启用后，所有进度和最终报告都以 JSON Lines (NDJSON) 格式输出到 stderr，便于外部程序解析。

argus review /repo feature main --json-logs

输出示例：

{"type":"review:start","data":{"repoPath":"/repo","sourceBranch":"feature","targetBranch":"main","agents":["security-reviewer","logic-reviewer"],"timestamp":"2025-01-15T10:00:00.000Z"}}
{"type":"phase:start","data":{"phase":1,"totalPhases":4,"name":"构建审查上下文...","timestamp":"..."}}
{"type":"agent:start","data":{"agent":"security-reviewer","timestamp":"..."}}
{"type":"agent:progress","data":{"agent":"security-reviewer","activity":"Reading file: src/auth.ts","timestamp":"..."}}
{"type":"agent:complete","data":{"agent":"security-reviewer","status":"completed","issuesFound":3,"elapsedMs":5000,"timestamp":"..."}}
{"type":"validation:issue","data":{"issueId":"sql-injection-auth.ts","title":"SQL 注入漏洞","file":"src/auth.ts","line":42,"severity":"error","status":"confirmed","description":"用户输入直接拼接到 SQL 查询中","suggestion":"使用参数化查询替代字符串拼接","timestamp":"..."}}
{"type":"review:complete","data":{"totalIssues":5,"elapsedMs":30000,"timestamp":"..."}}
{"type":"report","data":{"report":{"issues":[...],"metrics":{...},"metadata":{...}},"timestamp":"..."}}

事件类型说明：

| 事件类型 | 说明 | | --------------------- | ------------------------------------------------- | | review:start | 审查开始，包含仓库、分支、Agent 列表 | | review:complete | 审查完成，包含问题总数和耗时 | | review:error | 审查失败，包含错误信息 | | phase:start | 阶段开始（构建上下文、运行Agent、验证、生成报告） | | phase:complete | 阶段完成 | | agent:start | Agent 开始运行 | | agent:progress | Agent 活动（读取文件、搜索代码等） | | agent:complete | Agent 完成，包含发现的问题数 | | validation:start | 验证开始 | | validation:progress | 验证进度 | | validation:issue | 问题验证结果（confirmed/rejected/uncertain） | | validation:complete | 验证完成统计 | | log | 日志消息 | | report | 最终报告（包含完整的审查结果） |

服务集成示例：

import { spawn } from 'child_process';

const child = spawn('argus', ['review', repo, source, target, '--json-logs']);

child.stderr.on('data', (chunk) => {
  for (const line of chunk.toString().split('\n').filter(Boolean)) {
    const event = JSON.parse(line);

    switch (event.type) {
      case 'agent:start':
        updateUI(`Agent ${event.data.agent} 开始运行...`);
        break;
      case 'agent:complete':
        updateUI(`Agent ${event.data.agent} 完成，发现 ${event.data.issuesFound} 个问题`);
        break;
      case 'validation:issue':
        if (event.data.status === 'confirmed') {
          addIssue(event.data);
        }
        break;
      case 'report':
        // 最终报告 - 审查完成
        saveReport(event.data.report);
        break;
    }
  }
});

--language=<lang>

输出语言

| 值 | 说明 | | ---- | ------------ | | zh | 中文（默认） | | en | 英文 |

argus review /repo feature main --language=en

--skip-validation

跳过问题验证

跳过挑战模式验证，加快审查速度，但可能增加误报。

argus review /repo feature main --skip-validation

适用场景：

• 快速预览审查结果
• CI/CD 中的快速检查
• 对误报容忍度较高的场景

注意： 不推荐在正式审查中使用，验证可以过滤约 30-50% 的误报。

--config-dir=<path>

配置目录

指定配置目录，自动加载其中的 rules/ 和 agents/ 子目录。

argus review /repo feature main --config-dir=./.ai-review

目录结构：

.ai-review/
├── rules/              # 补充内置 Agent 的规则
│   ├── global.md       # 全局规则（应用于所有 Agent）
│   ├── security.md     # 安全审查规则
│   ├── logic.md        # 逻辑审查规则
│   ├── style.md        # 风格审查规则
│   ├── performance.md  # 性能审查规则
│   └── checklist.yaml  # 自定义检查清单
└── agents/             # 自定义 Agent（领域专项审查）
    ├── component-plugin.yaml
    └── api-security.yaml

--rules-dir=<path>

自定义规则目录

单独指定规则目录，可多次使用。

# 单个规则目录
argus review /repo feature main --rules-dir=./team-rules

# 多个规则目录（按顺序合并）
argus review /repo feature main --rules-dir=./base-rules --rules-dir=./team-rules

规则文件格式（Markdown）：

# 安全审查规则

## 必须检查

- 所有用户输入必须进行验证和转义
- 禁止使用 eval() 和 new Function()
- SQL 查询必须使用参数化查询

## 推荐做法

- 使用 Content-Security-Policy 头
- 敏感数据使用加密存储

--agents-dir=<path>

自定义 Agent 目录

指定自定义 Agent 定义目录，可多次使用。

argus review /repo feature main --agents-dir=./custom-agents

Agent 定义文件格式（YAML）：

name: api-security
description: API 安全专项审查
trigger_mode: rule # rule | llm | hybrid
triggers:
  files:
    - '**/api/**/*.ts'
    - '**/routes/**/*.ts'
  exclude_files:
    - '**/*.test.ts'
    - '**/*.spec.ts'
prompt: |
  你是 API 安全审查专家，请检查以下问题：

  1. 认证和授权
     - 是否正确验证用户身份
     - 是否检查用户权限

  2. 输入验证
     - 请求参数是否进行类型和范围验证
     - 是否防止注入攻击

  3. 响应安全
     - 是否泄露敏感信息
     - 错误消息是否过于详细
output:
  category: security
  default_severity: error

--verbose

详细输出模式

输出更多调试信息，包括 Agent 选择原因、工具调用详情等。

argus review /repo feature main --verbose

--previous-review=<file>

修复验证模式

加载上次审查的 JSON 文件，验证已报告的问题是否已修复。

# 验证上次审查中的问题是否已修复
argus review /repo feature main --previous-review=./review-result.json

工作原理：

1. 从上次审查 JSON 文件中加载问题列表
2. 运行 fix-verifier Agent 检查每个问题
3. 报告验证状态：fixed（已修复）、missed（未修复）、false_positive（误报）、obsolete（已过时）或 uncertain（不确定）
4. 未修复的问题会包含在最终报告中，并更新描述

上次审查文件格式：

文件应为包含 issues 数组的上次审查 JSON 导出：

{
  "issues": [
    {
      "id": "sql-injection-auth-42",
      "file": "src/auth.ts",
      "line_start": 42,
      "line_end": 45,
      "category": "security",
      "severity": "error",
      "title": "SQL 注入漏洞",
      "description": "用户输入直接拼接到 SQL 查询中"
    }
  ]
}

--no-verify-fixes

禁用修复验证

当设置了 --previous-review 时，修复验证默认启用。使用此标志可禁用它。

# 加载上次审查但跳过修复验证
argus review /repo feature main --previous-review=./review.json --no-verify-fixes

使用示例

基础用法

# 完整 AI 代码审查（基于分支）
argus review /path/to/repo feature-branch main

# 英文输出
argus review /path/to/repo feature-branch main --language=en

增量审查（基于 Commit）

使用 commit SHA 代替分支名来只审查特定的 commit 范围：

# 审查两个 commit 之间的变更
argus review /repo abc1234 def5678

# 示例：只审查 feature 分支上的新 commit
# 首先获取 commit SHA
git log --oneline feature-branch

# 然后审查特定范围
argus review /repo <新commit-sha> <旧commit-sha>

工具会自动检测传入的是分支名还是 commit SHA，并相应调整 diff 策略。

修复验证

验证上次审查中的问题是否已修复：

# 保存首次审查结果
argus review /repo feature main --json-logs 2>&1 | jq 'select(.type=="report") | .data.report' > review-1.json

# 修复后，验证修复情况
argus review /repo feature main --previous-review=./review-1.json

自定义配置

# 使用配置目录
argus review /repo feature main --config-dir=./.ai-review

# 分别指定规则和 Agent
argus review /repo feature main \
  --rules-dir=./company-rules \
  --agents-dir=./domain-agents

# 多层配置合并
argus review /repo feature main \
  --config-dir=./base-config \
  --rules-dir=./team-overrides

CI/CD 集成

# JSON 事件流输出
argus review /repo feature main --json-logs 2>events.jsonl

# 快速检查（跳过验证）
argus review /repo feature main --skip-validation --json-logs

# 基于 commit 的增量 CI 检查
argus review /repo $NEW_COMMIT $OLD_COMMIT --json-logs

项目结构

src/
├── index.ts              # CLI 入口，命令解析
├── cli/
│   ├── progress.ts       # 交互式进度输出
│   ├── events.ts         # 事件类型定义
│   └── structured-progress.ts  # JSON 事件流输出
├── review/
│   ├── orchestrator.ts   # 主审查协调器
│   ├── streaming-orchestrator.ts  # 流式审查模式
│   ├── streaming-validator.ts    # 流式问题验证
│   ├── agent-selector.ts # 智能 Agent 选择
│   ├── validator.ts      # 问题验证（挑战模式）
│   ├── fix-verifier.ts   # 修复验证 Agent 执行器
│   ├── previous-review-loader.ts # 加载上次审查数据
│   ├── realtime-deduplicator.ts  # 实时去重
│   ├── deduplicator.ts   # 批量语义去重
│   ├── aggregator.ts     # 问题聚合
│   ├── report.ts         # 报告生成
│   ├── prompts/          # Agent Prompt 构建
│   ├── standards/        # 项目标准提取
│   ├── rules/            # 自定义规则加载
│   ├── custom-agents/    # 自定义 Agent 加载
│   └── types.ts          # 类型定义
├── git/
│   ├── diff.ts           # Git Diff 操作
│   ├── parser.ts         # Diff 解析
│   ├── ref.ts            # Ref 类型检测（分支/commit）
│   ├── worktree-manager.ts # Git Worktree 管理
│   └── commits.ts        # 提交历史
├── llm/
│   ├── factory.ts        # LLM 提供者工厂
│   └── providers/        # Claude/OpenAI 实现
└── analyzer/
    ├── local-analyzer.ts # 本地快速分析
    └── diff-analyzer.ts  # LLM 语义分析

.claude/agents/           # 内置 Agent Prompt 定义
├── security-reviewer.md  # 安全审查
├── logic-reviewer.md     # 逻辑审查
├── style-reviewer.md     # 风格审查
├── performance-reviewer.md # 性能审查
├── validator.md          # 问题验证
└── fix-verifier.md       # 修复验证

工作原理

审查流程

┌─────────────────┐
│  1. 上下文构建   │  获取 Diff → 解析文件 → 提取项目标准
└────────┬────────┘
         ▼
┌─────────────────┐
│  2. 智能选择    │  根据文件特征选择需要的 Agent
└────────┬────────┘
         ▼
┌─────────────────┐
│  3. 并行审查    │  4 个 Agent 并发执行 + 实时去重
└────────┬────────┘
         ▼
┌─────────────────┐
│  4. 问题验证    │  挑战模式多轮验证，过滤误报
└────────┬────────┘
         ▼
┌─────────────────┐
│  5. 修复验证    │  （可选）验证上次问题是否已修复
└────────┬────────┘
         ▼
┌─────────────────┐
│  6. 生成报告    │  聚合问题，生成结构化报告
└─────────────────┘

三点式 Diff

使用 git diff origin/target...origin/source：

main:     A --- B --- C
                \
feature:         D --- E

• 只显示 D 和 E 的变更（源分支实际改动）
• 排除 target 分支上的其他提交

实时去重

两层去重机制：

1. 规则层 - 同文件 + 行号重叠 → 快速判断
2. LLM 层 - 语义相似度 → 精确去重

问题验证

挑战模式：验证 Agent 尝试"挑战"发现的问题

• 验证代码位置是否正确
• 验证问题描述是否准确
• 验证是否为真实问题而非误报

修复验证

当提供 --previous-review 时，fix-verifier Agent 会检查每个上次的问题：

1. 第一阶段：批量筛查 - 快速扫描，将问题分类为已解决/未解决/不明确
2. 第二阶段：深入调查 - 对未解决的问题进行多轮深入调查

验证状态：

• fixed - 问题已正确修复
• missed - 问题仍然存在（开发者遗漏）
• false_positive - 原始检测是误报
• obsolete - 代码变更较大，问题不再相关
• uncertain - 无法确定状态

开发命令

# 开发
npm run dev -- <command> ...   # 运行 CLI
npm run exec src/file.ts       # 运行任意 TS 文件

# 构建
npm run build                  # 编译到 dist/
npm run type-check             # 类型检查

# 代码质量
npm run lint                   # ESLint 检查
npm run lint:fix               # 自动修复
npm run format                 # Prettier 格式化
npm run format:check           # 检查格式

# 测试
npm run test                   # 监听模式
npm run test:run               # 运行一次
npm run test:coverage          # 覆盖率报告

Commit 规范

使用 Conventional Commits：

git commit -m "feat: add new feature"
git commit -m "fix: resolve bug"
git commit -m "docs: update documentation"

类型：feat、fix、docs、style、refactor、perf、test、chore

License

MIT