T2-SD0403/2026Technology-Competition

Fork 0

Files

T

Developer 6a64aece24 docs: add code reviewer extension design spec

2026-07-10 18:55:36 +08:00

5.6 KiB

Raw Blame History

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 接口

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 审查代码。

配置

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

工作流

用户触发 AI 审查（整个文件或选中代码）
收集代码 + 上下文 → 构建 Prompt
调用 LLM API → 解析 JSON 响应
结果转为 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 提供：

快速修复 — 若 analyzer 提供了 fix() 方法
AI 解释 — 调用 AI 翻译/解释问题
添加忽略注释 — 自动插入 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 兼容接口）

5.6 KiB Raw Blame History Unescape Escape