docs: add code reviewer extension design spec
This commit is contained in:
Developer
@@ -0,0 +1,232 @@
|
||||
# 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 兼容接口）
|
||||
Reference in New Issue
Block a user