ai-cr-viewer

ai-cr-viewer 是一个本地企业级 AI Code Review CLI。它面向前端项目，在本地扫描文件、识别 Vue2 / Vue3 / React / Mixed / Unknown，构建项目上下文与 Review Packet，结合静态扫描和 DeepSeek / OpenAI 生成标准化审查报告，并打开浏览器 Dashboard。

不包含 Git、GitHub、GitLab、PR、Webhook、CI/CD、数据库、登录系统或用户系统。

功能特性

• 本地项目、单文件、多文件、单目录、多目录审查
• Vue2 / Vue3 / React / Mixed / Unknown 自动识别
• Project Scanner：识别 language、packageManager、buildTool、internalPackages
• Context Builder：解析 import / export / require，识别 api、types、store、router、config、component、style 文件
• Static Analyzer：本地检测语法错误、import 不存在、重复 key、eval、innerHTML、接口字段命名风险等
• Review Packet Builder：按目标文件和相关上下文切分，减少 Token 消耗
• AI Review Engine：DeepSeek / OpenAI Provider 抽象
• Reviewer 架构：BugReviewer、APIContractReviewer、DataSafetyReviewer、FrontendReviewer
• Result Processor：合并、去重、风险分类、置信度与证据链标准化
• Dashboard：Overview、Findings、Risk Distribution、File Distribution、Finding Detail、Review History
• Dashboard 支持中文 / English 手动切换
• Mock 模式：无 API Key 也能演示完整流程
• 本地报告：.ai-cr/review-result.json、.ai-cr/latest.json、.ai-cr/latest.md

npm 使用方式

直接运行：

npx ai-cr-viewer

本地安装：

npm install ai-cr-viewer -D

添加脚本：

{
  "scripts": {
    "ai-cr": "ai-cr-viewer"
  }
}

运行：

npm run ai-cr

yarn 使用方式

yarn dlx ai-cr-viewer
yarn add ai-cr-viewer -D
yarn ai-cr

pnpm 使用方式

pnpm dlx ai-cr-viewer
pnpm add ai-cr-viewer -D
pnpm ai-cr

DeepSeek API Key 配置

DeepSeek 是默认 Provider，使用 OpenAI SDK 兼容模式。

baseURL: https://api.deepseek.com
default model: deepseek-chat

API Key 读取顺序：

1. --api-key
2. DEEPSEEK_API_KEY
3. OPENAI_API_KEY 兼容兜底

示例：

ai-cr-viewer --provider deepseek --api-key sk-xxxx

PowerShell：

$env:DEEPSEEK_API_KEY="sk-xxxx"
ai-cr-viewer.cmd --provider deepseek

OpenAI API Key 配置

OpenAI 需要显式指定 Provider。

default model: gpt-4.1

API Key 读取顺序：

1. --api-key
2. OPENAI_API_KEY

示例：

ai-cr-viewer --provider openai --api-key sk-xxxx

PowerShell：

$env:OPENAI_API_KEY="sk-xxxx"
ai-cr-viewer.cmd --provider openai

Mock 模式

无 API Key 时演示完整 Dashboard：

ai-cr-viewer --mock

Mock 模式仍然会扫描项目、识别框架、生成报告、启动 Dashboard，但不会调用 DeepSeek 或 OpenAI。

审查范围

整体项目检查：

ai-cr-viewer
ai-cr-viewer --mock

单文件检查：

ai-cr-viewer --file ./src/App.tsx
ai-cr-viewer --mock --file ./src/App.tsx

多文件检查：

ai-cr-viewer --files ./src/App.tsx ./src/main.tsx
ai-cr-viewer --files ./src/App.tsx,./src/main.tsx
ai-cr-viewer --mock --files ./src/App.tsx ./src/main.tsx
ai-cr-viewer --mock --files ./src/App.tsx,./src/main.tsx

单目录检查：

ai-cr-viewer --dir ./src
ai-cr-viewer --mock --dir ./src

多目录检查：

ai-cr-viewer --dirs ./src ./web/src
ai-cr-viewer --dirs ./src,./web/src
ai-cr-viewer --mock --dirs ./src ./web/src

参数优先级：

1. --files
2. --file
3. --dirs
4. --dir
5. 默认整个项目

扫描限制

默认单文件最大 80 KB。

ai-cr-viewer --max-file-size 120
ai-cr-viewer --max-files 50
ai-cr-viewer --max-chars 200000

超过限制的文件会被跳过，CLI 会输出 skipped files，Dashboard 也会展示 Skipped Files。

Dashboard 语言

Dashboard 顶部提供语言选择：

• 中文
• English

也可以通过 CLI 指定初始语言：

ai-cr-viewer --language zh-CN
ai-cr-viewer --language en-US

用户在页面上的选择会保存在浏览器 localStorage。

配置文件

推荐在项目根目录创建 ai-cr.config.json。旧文件名 .ai-cr-viewer.json 仍然兼容，但当两个文件都存在时优先读取 ai-cr.config.json。

{
  "include": ["src/**/*", "web/src/**/*"],
  "exclude": ["node_modules", "dist", "build", "coverage", ".git", "**/*.d.ts", "**/*.min.js"],
  "provider": "deepseek",
  "model": "deepseek-chat",
  "reviewMode": "enterprise",
  "riskPolicy": "balanced",
  "language": "zh-CN",
  "projectContext": {
    "projectType": "enterprise-b-system",
    "frontendFrameworks": ["Vue2", "Vue3", "React"],
    "businessDomain": "工业自动化 / B端管理系统",
    "apiStyle": "REST",
    "tableDataKeys": ["Datas", "Items", "Total"],
    "permissionStyle": "按钮权限 / 菜单权限 / 操作权限"
  },
  "internalPackages": ["lt-baseui", "lt-rest", "lt-monitor", "lt-request", "lt-ui-table"],
  "focusAreas": ["保存逻辑", "删除逻辑", "导入导出", "权限控制", "接口参数", "数据覆盖", "批量操作"],
  "ignoreAreas": ["组件体积", "代码风格", "内网 IP", "UI 细节"],
  "riskRules": {
    "P0": ["项目无法启动、无法构建、页面白屏"],
    "P1": ["可能造成业务数据覆盖", "可能误删数据"],
    "P2": ["边界场景异常", "字段类型转换不稳定"],
    "P3": ["可维护性建议", "低风险体验优化"]
  },
  "outputFormat": {
    "summary": true,
    "enterpriseVerdict": true,
    "findings": {
      "fields": ["priority", "file", "line", "problem", "impact", "fixSuggestion", "confidence"]
    },
    "requireEvidence": true,
    "avoidGuessing": true,
    "maxFindings": 30
  }
}

仓库中提供了 ai-cr.config.example.json 和兼容旧文件名的 .ai-cr-viewer.example.json。

配置规则：

• 无配置文件时使用内置默认企业配置。
• 只写部分字段时会与默认配置深度合并。
• include、exclude、focusAreas、ignoreAreas、internalPackages 会数组合并并去重。
• riskRules 会按 P0/P1/P2/P3 合并，用户规则会追加到默认规则。
• outputFormat 会补齐默认字段。
• 未识别字段或非法字段会产生 warning，不会直接中断审查。
• JSON 语法错误会明确报错并退出。
• CLI 参数优先级高于配置文件，例如 --provider openai --model gpt-4.1 会覆盖配置中的 provider/model。

企业级审查流程

Project Scanner
  ↓
Context Builder
  ↓
Static Analyzer
  ↓
Review Packet Builder
  ↓
BugReviewer / APIContractReviewer / DataSafetyReviewer / FrontendReviewer
  ↓
Result Processor
  ↓
latest.json / latest.md / Dashboard

AI 不会直接接收整个项目，而是接收当前目标文件、相关 api/types/store/router/config/component 文件、本地静态扫描结果和业务上下文。

Finding Schema

核心输出字段：

{
  "priority": "P1",
  "severity": "P1",
  "category": "api_contract",
  "riskType": "api_contract",
  "file": "src/api/user.ts",
  "line": 12,
  "lineStart": 12,
  "lineEnd": 12,
  "title": "分页参数命名不一致",
  "evidence": [
    {
      "file": "src/api/user.ts",
      "line": 12,
      "code": "PageSize: params.pageSize"
    }
  ],
  "impact": "可能导致后端分页参数无法识别",
  "fixSuggestion": "确认后端契约并统一 Page/PageSize 或 page/pageSize",
  "suggestion": "确认后端契约并统一 Page/PageSize 或 page/pageSize",
  "confidence": 0.82
}

confidence < 0.6 会自动标记 needsHumanCheck=true。

最终 JSON 报告还会包含：

• enterpriseSummary
• manualChecks
• ignoredByPolicy
• configWarnings

Vue2 / Vue3 / React 支持

Vue2 重点关注：

• data 函数
• props 直接修改
• watch 问题
• 响应式限制
• single-spa / 微前端生命周期风险

Vue3 重点关注：

• ref / reactive 使用
• 响应式解构
• watch 清理
• setup 逻辑

React 重点关注：

• Hooks 规则
• useEffect 依赖
• stale closure
• key 问题
• 重复渲染

Dashboard

默认地址：

http://localhost:5178

如果端口被占用，会自动尝试后续端口。

Dashboard 展示：

• Provider / Model / Mock Mode / Framework / Review Scope / Targets
• Total / P0 / P1 / P2 / P3 / Files / Targets / Skipped Files
• Priority / Severity 筛选
• RiskType 筛选
• Target 筛选
• 搜索 file / title / problem / suggestion / verificationComment
• Evidence、confidence、verificationComment、needsHumanCheck
• Enterprise Summary
• Priority Groups
• Manual Checks
• Ignored By Policy
• Config Warnings
• Risk Distribution
• File Distribution
• Review History
• Export Markdown

Windows PowerShell

如果 PowerShell 拦截 npm 生成的 ai-cr-viewer.ps1：

cannot be loaded because running scripts is disabled on this system

使用 .cmd：

ai-cr-viewer.cmd --mock
ai-cr-viewer.cmd --provider deepseek --dir ./src

常见错误排查

缺少 DeepSeek Key：

Missing DeepSeek API key. Pass --api-key or set DEEPSEEK_API_KEY.

缺少 OpenAI Key：

Missing OpenAI API key. Pass --api-key or set OPENAI_API_KEY.

没有可审查文件：

• 检查 --file、--files、--dir、--dirs
• 检查文件扩展名是否在支持范围内
• 调整 --max-file-size、--max-files、--max-chars

Provider 调用失败：

• 检查 API Key 是否有效
• 检查网络是否可访问 Provider
• 先运行 ai-cr-viewer --mock 验证本地流程

发布前检查命令

npm run build
npm run typecheck
npm pack --dry-run

Package 检查：

• bin.ai-cr-viewer 指向 dist/cli.js
• files 包含 dist、web/dist、README.md
• 当前版本：1.4.0