范智鹏
458647d82e
- 新增 measurement/ 测量协议入口（baseline.md + timing-log.md） - 新增 docs/demo-storyboard.md 演示视频分镜 - README 新增背景与痛点、挂接测量协议/设计文档/分镜链接
197 lines
11 KiB
Markdown
197 lines
11 KiB
Markdown
# vscode-code-reviewer · 净码特工 (Code Purifier)
|
||
|
||
> **项目性质：新规**（从零开发的全新作品）
|
||
|
||
AI 驱动的代码审查与规范检查一体化 VS Code 插件。集成 ESLint、Stylelint、PMD、SQLFluff 等多种 linter，并支持 AI 辅助审查与自动修复。
|
||
|
||
## 项目概述
|
||
|
||
「净码特工 (Code Purifier)」是一款面向企业级多语言代码库的一体化代码审查与规范检查 VS Code 扩展。它将传统静态检查（ESLint、Stylelint、PMD、SQLFluff）与 AI 大模型审查深度融合，覆盖 JavaScript、TypeScript、Java、JSP、HTML、CSS、SQL、PL/SQL 八类语言，提供一键审查、方法级审查、AI 自动修复与修复预览、报告导出、自定义规则导入等能力，并内置 Webview 面板实现"配置—审查—修复—导出"的闭环体验。
|
||
|
||
> 完整设计见 [DESIGN.md](DESIGN.md)，实现时间线见 [docs/2026-08-27-implementation-timeline.md](docs/2026-08-27-implementation-timeline.md)。
|
||
|
||
## 背景与痛点
|
||
|
||
企业多语言混合工程（典型如运营商城域后台、金融核心等遗留系统）中，Java、JSP、JavaScript/TypeScript、CSS、SQL 长期共存，代码审查面临以下痛点，本插件逐一给出对应方案：
|
||
|
||
| 痛点 | 插件方案 |
|
||
|---|---|
|
||
| Linter 报错是英文机器语言，非母语开发者阅读成本高 | AI 将静态诊断翻译为输出语言（中/英/日）并附加修复建议 |
|
||
| 静态规则覆盖不了语义级安全漏洞、逻辑错误、设计缺陷 | LLM 深度审查通道专注安全/逻辑/性能/设计四类增量发现，且不重复静态结果 |
|
||
| 团队私有编码规范无法进入通用 linter | YAML 自定义规则：自然语言描述 + AI 语义判定 + 热加载 |
|
||
| 发现问题后修复仍靠人工逐条处理 | 分级修复闭环：原生 fix 优先 → AI 修复兜底 → diff 预览两步确认写入 |
|
||
|
||
> 详细场景与完整痛点-方案映射见 [DESIGN.md](DESIGN.md) §1。
|
||
|
||
## 效果总结（核心指标摘要）
|
||
|
||
> 数据来源：A3 提效对比实验（23 个多语言样例，`data/efficiency-samples/`）。「提效后」= 插件静态分析实测（`tests/measure/results/a3-plugin-results.json`，可复现 `node tests/measure/measure-plugin-samples.mjs`）；「基线」= 3 名不同经验等级审查人使用人工审核工具逐文件计时记录问题（`tests/measure/results/manual-review-*.json`）；聚合对比见 `tests/measure/performance-comparison.md` 与 `tests/measure/results/a3-comparison.json`。测量协议详见 [measurement/baseline.md](measurement/baseline.md)（人工基线）与 [measurement/timing-log.md](measurement/timing-log.md)（计时日志与可重演命令）。
|
||
|
||
| 指标 | 基线（人工审查，3 人均值） | 提效后（插件静态分析） | 提升幅度 |
|
||
|------|---------------------------|------------------------|----------|
|
||
| 全量审查耗时（23 文件） | 38.1 分钟 | 8.6 秒 | **约 266 倍** |
|
||
| 检出规范问题数（23 文件） | 76 条 | 283 条 | 检出量约 3.7 倍 |
|
||
| 问题检出率（对照插件全量） | 27%（平均漏检 73%） | 100%（规则全覆盖） | 规则覆盖兜底 |
|
||
| 单文件审查耗时（JS/CSS） | 约 100 秒 | 约 0.01 秒 | 约 3400–8500 倍 |
|
||
| 单文件审查耗时（Java/SQL） | 约 100 秒 | 约 1.1 / 0.4 秒（含子进程启动） | 约 94–238 倍 |
|
||
|
||
> 结论：插件在秒级完成多语言全量规范审查，较人工审查整体提速约 266 倍；同时内置规则全覆盖、逐字可复现，可弥补人工审查平均约 73% 的规则类漏检。
|
||
|
||
## 团队分工
|
||
|
||
| 成员 | 分工 |
|
||
| ------ | ----------------------------------------------------------- |
|
||
| 范智鹏 | 框架设计与核心技术开发，功能实现落地，测试方案设计与实行 |
|
||
| 苏洪旭 | 前期调研与可行性分析，插件功能的拓展与优化，进行测试验证 |
|
||
| 董爱卿 | 需求分析与场景定义，用户体验与UI设计，文档撰写，Gitee库管理 |
|
||
|
||
## 规模与技术难度自我评估
|
||
|
||
- **代码规模**：源码约 65 个 TypeScript 文件、约 1.1 万行，按 17 个模块分层组织（`activation` / `adapters` / `ai` / `config` / `diagnostics` / `fix` / `i18n` / `jsp` / `merger` / `orchestrator` / `panel` / `rules` / `scope` / `services` / `types` / `utils` / `views`）。
|
||
- **技术难度**：（整体偏高）涉及多 linter 统一适配层抽象、多 AI 供应商动态注册（Provider 策略模式 + 运行期注册表）、AI 修复链路（生成—校验—预览—快照撤销）、Office 文档（Word/Excel/PPT）规则导入解析、PMD 的 Java 辅助类路径探测、SQLFluff 方言映射等跨语言、跨进程、跨服务的复杂工程问题。
|
||
- **可运行性**：依赖清单与锁文件（`package.json` / `package-lock.json`）随仓库提供，源码经 `npm install && npm run compile` 即可构建，按 `F5` 启动调试。
|
||
|
||
## 功能特性
|
||
|
||
- 一键运行代码审查
|
||
- 选中代码片段 / 单个方法审查
|
||
- Webview 面板展示审查结果与 AI 审查详情
|
||
- 自动修复（含 AI 修复、修复预览）
|
||
- 报告导出
|
||
- 自定义规则管理与导入（Word / Excel / PPT / Markdown / TXT / YAML）
|
||
- 支持语言：JavaScript、TypeScript、Java、JSP、HTML、CSS、SQL、PL/SQL
|
||
- 多 AI 供应商（DeepSeek / OpenAI / Gemini / Claude / 腾讯混元 / 智谱 / 月之暗面 / 阿里通义）
|
||
- 方法级 CodeLens 审查按钮、编辑器波浪线标记
|
||
|
||
## 运行环境要求
|
||
|
||
| 组件 | 要求 |
|
||
|------|------|
|
||
| VS Code | `^1.120.0` |
|
||
| Node.js | 构建源码需要（打包产物无需） |
|
||
| Java | 检查 Java / JSP 需要，`java` 命令需在 PATH 中 |
|
||
| SQLFluff | 检查 SQL / PL/SQL 需要，`sqlfluff` 命令需在 PATH 中 |
|
||
| ESLint / Stylelint | 随插件内置，无需单独安装 |
|
||
|
||
PMD 与内置规则集通过 `npm run download-pmd` 获取（默认位于 `jars/pmd`）。
|
||
|
||
## 安装
|
||
|
||
### 方式一：从 VSIX 安装（端用户）
|
||
|
||
1. 安装 VS Code 1.120 或更高版本。
|
||
2. 安装 VS Code 扩展依赖环境（Java、SQLFluff，见上文运行环境要求）。
|
||
3. 命令行安装：
|
||
```bash
|
||
code --install-extension vscode-code-reviewer-1.3.0.vsix
|
||
```
|
||
或在 VS Code 扩展面板点击右上角 `...` → 「从 VSIX 安装…」，选择生成的 `.vsix` 文件。
|
||
|
||
### 方式二：从源码构建安装（开发者）
|
||
|
||
```bash
|
||
git clone <repo-url>
|
||
cd vscode-code-reviewer
|
||
npm install
|
||
npm run download-pmd # 下载 PMD jar（可选，需要 PMD 时执行）
|
||
npm run compile # TypeScript 编译
|
||
```
|
||
|
||
按 `F5` 启动 Extension Development Host 进行调试。
|
||
|
||
## 运行方法
|
||
|
||
### 端用户
|
||
|
||
| 操作 | 说明 |
|
||
|------|------|
|
||
| `Ctrl+Shift+R` | 运行代码审查（当前文件） |
|
||
| 命令面板 → `Code Purifier: 审查选中代码` | 仅审查选中的代码 |
|
||
| 命令面板 → `Code Purifier: 审查此方法` | 审查光标所在方法（或点击函数声明上方的 CodeLens 按钮） |
|
||
| 命令面板 → `Code Purifier: 打开审查面板` | 打开审查结果面板 |
|
||
| 命令面板 → `Code Purifier: 修复此问题` / `批量修复` | 修复问题 |
|
||
| 命令面板 → `Code Purifier: 导出报告` / `导出规则模板` | 导出报告 / 模板 |
|
||
|
||
全部命令前缀为 `Code Purifier:`，可在命令面板中搜索使用。
|
||
|
||
### 开发者
|
||
|
||
```bash
|
||
npm run compile # TypeScript 编译 + 复制 webview JS
|
||
npm run watch # tsc watch 模式
|
||
npm run lint # ESLint 检查 src/
|
||
npm test # 编译 → lint → 运行测试（@vscode/test-cli）
|
||
npm run package-prod # 生产打包：build + vsce package，产出 .vsix
|
||
```
|
||
|
||
## 前端界面（Webview）启动方式
|
||
|
||
插件内置 Webview 面板，无需启动独立前端服务：
|
||
|
||
- **设置面板**：点击左侧活动栏「净码特工 / Code Purifier」图标，或在命令面板执行 `Code Purifier: 打开设置面板`。
|
||
- **审查面板**：执行 `Code Purifier: 打开审查面板` 或运行一次审查后自动展示。
|
||
|
||
Webview 资源在编译/打包时自动复制到 `out/webview/`，随插件加载。
|
||
|
||
## API 密钥配置
|
||
|
||
1. 打开设置面板（见上文）。
|
||
2. 在「API 配置」区域选择 AI 供应商（默认 `deepseek`），填入 API Key（`sk-...`）。
|
||
3. API Key 通过 VS Code SecretStorage 安全存储，**不会写入** `settings.json`。
|
||
4. 其他参数可在 `settings.json` 中配置：
|
||
|
||
| 配置项 | 默认值 | 说明 |
|
||
|--------|--------|------|
|
||
| `vscode-code-reviewer.ai.provider` | `deepseek` | AI 供应商 |
|
||
| `vscode-code-reviewer.ai.model` | `deepseek-chat` | 模型名称 |
|
||
| `vscode-code-reviewer.ai.baseUrl` | `https://api.deepseek.com/v1` | API Base URL |
|
||
| `vscode-code-reviewer.ai.temperature` | `0.2` | 温度参数 |
|
||
| `vscode-code-reviewer.ai.maxTokens` | `8192` | 单次最大输出 Token |
|
||
| `vscode-code-reviewer.ai.timeout` | `300` | 请求超时（秒） |
|
||
| `vscode-code-reviewer.ai.outputLanguage` | `zh-CN` | 插件语言（zh-CN / en / ja） |
|
||
|
||
支持自定义 AI 供应商：在工作区根目录创建 `.code-review/providers.json`，按 `providers.json` 的格式追加 provider，即可覆盖或新增供应商。
|
||
|
||
## 依赖清单
|
||
|
||
**运行时依赖（dependencies）**
|
||
|
||
| 依赖 | 版本 | 用途 |
|
||
|------|------|------|
|
||
| `@eslint/js` | ^9.39.3 | ESLint 内置规则集 |
|
||
| `eslint` | ^9.39.3 | JS/TS 规范检查 |
|
||
| `mammoth` | ^1.12.0 | Word 规则文档解析 |
|
||
| `officeparser` | ^7.5.0 | Office 文档解析 |
|
||
| `stylelint` | ^17.14.0 | CSS 规范检查 |
|
||
| `stylelint-config-recommended` | ^18.0.0 | Stylelint 推荐规则 |
|
||
| `typescript-eslint` | ^8.56.1 | TypeScript ESLint 规则 |
|
||
| `xlsx` | ^0.18.5 | Excel 规则导入导出 |
|
||
|
||
**开发依赖（devDependencies）**
|
||
|
||
| 依赖 | 版本 | 用途 |
|
||
|------|------|------|
|
||
| `typescript` | ^5.9.3 | TypeScript 编译器 |
|
||
| `esbuild` | ^0.28.1 | 生产构建打包 |
|
||
| `@types/vscode` | ^1.120.0 | VS Code API 类型 |
|
||
| `@types/node` | 22.x | Node 类型定义 |
|
||
| `@types/mocha` | ^10.0.10 | Mocha 类型定义 |
|
||
| `@vscode/test-cli` | ^0.0.12 | 测试运行器 |
|
||
| `@vscode/test-electron` | ^2.5.2 | 测试用 Electron |
|
||
| `@vscode/vsce` | ^3.9.2 | VSIX 打包 |
|
||
|
||
## 其他配置项
|
||
|
||
- **linter 选择**：`vscode-code-reviewer.linters.*`（javascript / typescript / java / jsp / html / css / sql / plsql），留空则禁用对应语言检查。
|
||
- **PMD**：`vscode-code-reviewer.pmd.jarPath` / `rulesetPath` / `jspRulesetPath` / `autoAuxClasspath`。
|
||
- **SQLFluff**：`vscode-code-reviewer.sqlfluff.configFile` / `dialect`。
|
||
- **修复**：`vscode-code-reviewer.fixer.maxIterations`。
|
||
- **CodeLens**：`vscode-code-reviewer.codelens.enabled` / `codelens.languages`。
|
||
- **波浪线标记**：`vscode-code-reviewer.markers.enabled`。
|
||
|
||
详细配置项可在 VS Code 设置页搜索 `vscode-code-reviewer` 查看。
|
||
|
||
## 演示视频
|
||
|
||
演示视频（`docs/demo.mp4`，≤5 分钟：完整工作流 + IDE 集成效果 + 异常处理）**进行中**，将在后续提交中补齐。分镜脚本见 [docs/demo-storyboard.md](docs/demo-storyboard.md)（三段式：完整工作流 / IDE 集成 / 异常处理）。
|