232 lines
5.6 KiB
Markdown
232 lines
5.6 KiB
Markdown
# 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 兼容接口） |