# Code Reviewer — VSCode Extension Design Spec

## 1. 概述

VSCode 代码审查与规范检查一体化工具。集成多语言静态分析器与 AI 智能审查，为开发团队提供代码质量保障。

### 核心能力

- 多语言代码静态分析（ESLint、Ruff、Clippy 等）
- AI 辅助深度审查与问题解释
- 自定义规则检查
- 自动修复建议与批量修复
- 可视化审查报告面板

---

## 2. 架构总览

插件分为三层：

```
UI 层 — TreeView 面板 / Inline Diagnostic / Code Action
核心层 — Linter 管理器 + AI 审查引擎（均实现 Analyzer 接口）
基础层 — 配置管理 / 规则管理 / 报告导出
```

所有 linter 和 AI 审查器统一实现 `Analyzer` 接口，结果聚合后通过 VSCode `DiagnosticCollection` 展示。

---

## 3. Analyzer 接口

```typescript
interface AnalyzerResult {
  file: string;
  line: number;
  column: number;
  severity: 'error' | 'warning' | 'info' | 'hint';
  message: string;
  ruleId: string;
  source: string;
  fix?: Fix;
  aiExplanation?: string;
}

interface Analyzer {
  readonly name: string;
  readonly language: string[];
  analyze(document: vscode.TextDocument): Promise<AnalyzerResult[]>;
  fix?(result: AnalyzerResult): vscode.TextEdit[];
}
```

### 内置 Analyzer

| Analyzer | 语言 | 调用方式 |
|----------|------|---------|
| EslintAnalyzer | JS/TS/JSX/TSX | eslint CLI --format json |
| RuffAnalyzer | Python | ruff check --output-format json |
| ClippyAnalyzer | Rust | cargo clippy --message-format json |
| AiAnalyzer | 通用 | LLM API |

---

## 4. Linter 管理器

### 自动检测

插件扫描工作区根目录，根据配置文件自动识别启用的 linter：

| Linter | 检测标志 |
|--------|---------|
| ESLint | `.eslintrc*` 或 `package.json` 中的 `eslintConfig` |
| Ruff | `ruff.toml` 或 `pyproject.toml` 中的 `[tool.ruff]` |
| Clippy | `Cargo.toml` 含 clippy 依赖 |

未检测到配置时可降级为默认配置运行。

### 执行策略

- **保存触发**：文件保存时自动运行，debounce 500ms（可配置）
- **手动触发**：命令面板、右键菜单、文件树右键
- **进度反馈**：运行时显示 `withProgress`

---

## 5. AI 审查引擎

`AiAnalyzer` 作为特殊 Analyzer 注册，通过 LLM API 审查代码。

### 配置

```typescript
interface AiReviewConfig {
  provider: 'openai' | 'custom';
  apiKey: string;
  model: string;
  maxTokens: number;
  customEndpoint?: string;
}
```

### 工作流

1. 用户触发 AI 审查（整个文件或选中代码）
2. 收集代码 + 上下文 → 构建 Prompt
3. 调用 LLM API → 解析 JSON 响应
4. 结果转为 `AnalyzerResult[]` → 注入 Diagnostic

### Prompt 策略

- System Prompt：审查专家角色 + JSON 格式约束
- 支持传入自定义规则列表
- 响应强制 JSON 格式

---

## 6. 插件贡献点

### Commands

| 命令 | 说明 |
|------|------|
| `codeReviewer.analyzeFile` | 审查当前文件 |
| `codeReviewer.analyzeWorkspace` | 审查整个工作区 |
| `codeReviewer.aiReview` | AI 深度审查 |
| `codeReviewer.aiExplain` | AI 解释选中问题 |
| `codeReviewer.fixAll` | 批量修复 |
| `codeReviewer.exportReport` | 导出报告 |

### Views

- `codeReviewProblems` — 审查问题树视图（按文件分组）
- `codeReviewSummary` — 审查概况树视图（统计信息 + 导出/批量修复入口）

### Configuration

| 配置项 | 类型 | 说明 |
|--------|------|------|
| `codeReviewer.linters` | object | 启用的 linter 配置 |
| `codeReviewer.ai.enabled` | boolean | 启用 AI 审查 |
| `codeReviewer.ai.provider` | enum | AI 提供商 |
| `codeReviewer.ai.apiKey` | string | API 密钥 |
| `codeReviewer.ai.model` | string | 模型名 |

---

## 7. 审查报告面板

### 问题列表视图（codeReviewProblems）

- 按文件分组展示所有问题
- 每个问题显示：严重级别图标、规则 ID、消息、行号、来源标记
- 点击跳转到对应位置
- 右键菜单：AI 解释 / 快速修复 / 忽略规则

### 概况视图（codeReviewSummary）

- 总计、按严重级别分布、按来源分布、按文件分布
- 导出报告按钮、批量修复按钮

---

## 8. Code Action 与批量修复

### Code Action 提供者

`CodeReviewCodeActionProvider` 为 diagnostic 提供：

1. **快速修复** — 若 analyzer 提供了 `fix()` 方法
2. **AI 解释** — 调用 AI 翻译/解释问题
3. **添加忽略注释** — 自动插入 linter 忽略标记

### 批量修复

- 遍历所有含 `fix` 的问题，按文件分组
- 使用 `WorkspaceEdit` 批量应用 TextEdit
- 显示修复总结

### 忽略机制

- 右键"忽略此规则" → 写入 `.codereviewerignore`

---

## 9. 文件结构

```
src/
├── extension.ts
├── activation/
│   ├── registerCommands.ts
│   ├── registerViews.ts
│   └── registerCodeActions.ts
├── analyzers/
│   ├── analyzer.ts
│   ├── eslintAnalyzer.ts
│   ├── ruffAnalyzer.ts
│   ├── clippyAnalyzer.ts
│   └── aiAnalyzer.ts
├── manager/
│   └── linterManager.ts
├── views/
│   ├── problemTreeProvider.ts
│   └── summaryTreeProvider.ts
├── services/
│   ├── aiService.ts
│   └── configService.ts
├── utils/
│   ├── diagnosticHelper.ts
│   └── linterDetector.ts
└── types.ts
```

---

## 10. 排除范围（非本期实现）

- 与 GitHub/GitLab PR Review API 集成
- 多人协作审查工作流
- WebView 可视化报告页面
- 自定义规则 DSL

---

## 11. 技术栈

- VSCode Extension API (^1.120.0)
- TypeScript (ES2022, Node16 module)
- ESLint + typescript-eslint
- Mocha + @vscode/test-electron
- LLM API（openai 兼容接口）