docs: 重写 README 补齐安装/运行/环境要求/API 密钥配置/依赖清单/前端面板说明

- 新增运行环境要求（VS Code ^1.120.0、Node、Java、sqlfluff、内置 ESLint/Stylelint） - 新增安装步骤（VSIX 安装 + 源码构建两方式） - 新增运行方法（端用户命令表 + 开发者命令表） - 新增前端 Webview 面板启动方式说明 - 新增 API 密钥配置说明（SecretStorage 存储 + 配置项表 + 自定义供应商） - 新增依赖清单（运行时/开发依赖表）及 linter/PMD/SQLFluff 等配置项
2026-08-20 22:34:13 +08:00
parent d16d680f0f
commit 65b9e1915b
2 changed files with 138 additions and 9 deletions
@@ -1,16 +1,143 @@
-# vscode-code-reviewer
+# vscode-code-reviewer · 净码特工 (Code Purifier)

-VS Code 代码审查与规范检查一体化插件。集成 ESLint、Stylelint、PMD、SQLFluff 等多种 linter，并支持 AI 辅助审查。
+AI 驱动的代码审查与规范检查一体化 VS Code 插件。集成 ESLint、Stylelint、PMD、SQLFluff 等多种 linter，并支持 AI 辅助审查与自动修复。

-## 功能
+## 功能特性

 - 一键运行代码审查
- 选中代码片段审查
- TreeView 面板展示审查结果
- 自动修复
+- 选中代码片段 / 单个方法审查
+- Webview 面板展示审查结果与 AI 审查详情
+- 自动修复（含 AI 修复、修复预览）
 - 报告导出
- 自定义规则管理
+- 自定义规则管理与导入（Word / Excel / PPT / Markdown / TXT / YAML）
+- 支持语言：JavaScript、TypeScript、Java、JSP、HTML、CSS、SQL、PL/SQL
+- 多 AI 供应商（DeepSeek / OpenAI / Gemini / Claude / 腾讯混元 / 智谱 / 月之暗面 / 阿里通义）
+- 方法级 CodeLens 审查按钮、编辑器波浪线标记

-## 配置
+## 运行环境要求

-通过 `Ctrl+Shift+P` → `净码特工: 打开设置面板` 进行配置，或编辑 `.vscode/settings.json`。
+| 组件 | 要求 |
+|------|------|
+| 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` 查看。
@@ -219,3 +219,5 @@
 | 2026-08-20 20:18 | ① 用户提出 → ② 需求澄清 → ③ 方案设计 → ④ 人类审批 → ⑤ 编码实现 → ⑥ 审查验证 | 修复功能扩展到自定义规则与 AI 审查：面板 custom/ai 条目标题支持 AI 修复，分 tab 批量（各 tab 各自「全部修复」），两步确认复用，各 tab 显示已修复+撤销。新建 src/fix/fixPrompt.ts（共享修复/重检 prompt builder 三语 + ReviewIssueInput 接口，从 aiFixEngine 提取）+ src/fix/customFixEngine.ts（aiFixReviewIssue：AI 生成修复→indexOf 匹配替换→AI 重检 {fixed,reason} 收敛，未消除带反馈重试 ≤maxIterations，无 adapter，支持 dryRun）+ src/test/customFixEngine.test.ts（4 用例）。aiFixEngine.ts 改用共享 fixPrompt（requestFix 内构造 ReviewIssueInput 适配 range→line）。fixSession.ts FixedEntry 加 source:'linter'|'custom'|'ai'，recordFixes 加 source 参数；fixPending.ts PendingFix/PendingBatch 加 source。commands.ts 新增 resolveReviewIssueFix/findCustomIssue/findAIIssue，fixIssue 按 payload.source 分流（custom/ai 走 AI 重检），fixAll 分 tab 批量（payload.source），applyFixPreview/applyAllPreview recordFixes 传 source，refreshAfterFix 保留 custom suggestion（原映射丢 suggestion）。webview.ts custom/ai 列表启用 aiFixable 渲染修复按钮+各 tab fixAll 按钮传 source+已修复区块按 source 过滤与徽章+FixedEntryView 接口。删除 codeDiff：schema.ts 两字段、engine.ts 完整+方法审查 prompt 全部 codeDiff 行、report.ts ```diff``` 展示块。spec：docs/superpowers/specs/2026-08-20-custom-ai-fix-design.md。npm test 110 passing / lint 0 error / compile 通过 | 中间产物：①澄清阶段用户在「AI 生成后不验证」与「AI 重检收敛」间两轮选择，最终定为 AI 重检收敛（无 linter 可重 lint，用 AI 重检替代）；②codeDiff 去留讨论——用户问「带着有需要吗」，说明其现状仅报告展示用，用户决定删除；③refreshAfterFix 的 customRuleResults 映射初版未含 suggestion，审查中发现会破坏上轮 custom 展开功能，补上；④aiFixEngine requestFix 传入 LinterDiagnostic 与 fixPrompt.ReviewIssueInput 类型不匹配（line vs range）编译报错 TS2345，改为构造 ReviewIssueInput | src/fix/fixPrompt.ts(新建) src/fix/customFixEngine.ts(新建) src/fix/aiFixEngine.ts src/fix/fixSession.ts src/fix/fixPending.ts src/activation/commands.ts src/panel/webview.ts src/ai/schema.ts src/ai/engine.ts src/utils/report.ts src/test/customFixEngine.test.ts(新建) docs/superpowers/specs/2026-08-20-custom-ai-fix-design.md(新建) | deepseek-v4-flash |
 | 2026-08-20 21:56 | ① 用户提出 → ② 需求澄清 → ③ 方案设计 → ④ 人类审批 → ⑤ 编码实现 → ⑥ 审查验证 | 修复面板「修复」按钮卡 ⏳ 不恢复的 bug（实测：custom 修复失败 ai-no-fix 后按钮永久卡 ⏳、点取消后也卡 ⏳）。根因双处：①reviewPanel.js pending/batchPending 消息翻转只切 display，从不重置「修复」按钮的 textContent/disabled——点击时 JS 设 disabled=true+textContent='⏳...'（webview.ts buildIssueItem onclick），取消(on:false)恢复显示后仍停留在 ⏳+disabled；②fixIssue/fixAll 命令层失败路径（!result.success、success===0、catch）只 showWarningMessage 就 return，从不 postMessage 恢复按钮。修复：webview.ts buildIssueItem 修复按钮加 data-label 存原始文案（🔧 修复/🤖 AI 修复，esc 转义）；reviewPanel.js pending 消息 on:false 时对非 confirm 按钮（data-label）恢复 textContent+disabled=false；commands.ts fixIssue custom/linter 分支失败+catch 补 postMessage {type:'pending',key,on:false}（key=ruleId@line），fixAll 两处 success===0+catch 补 {type:'batchPending',on:false}。npm test 110 passing / lint 0 error / compile 通过。ai-no-fix 与「聚焦文件才生效」的关系仍在排查（用户复现：不聚焦连点 3 次必现失败；聚焦后成功，但代码逻辑 panel 来源取文档不依赖焦点，待进一步定位） | 中间产物：①初版考虑在失败弹窗后靠 refreshAfterFix 全量重建面板恢复按钮，发现失败路径根本不走 refreshAfterFix，改显式 postMessage；②data-label 文案初版直接拼 emoji+t()，审查确认 esc() 转义 & < > " 后 dataset 读取自动解码安全；③是否给 catch 也补恢复曾有犹豫，确认异常路径同样需恢复故一并补上 | src/panel/webview.ts src/views/reviewPanel.js src/activation/commands.ts | deepseek-v4-flash |
 | 2026-08-20 22:20 | ① 用户提出 → ② 需求澄清 → ③ 方案设计 → ④ 人类审批 → ⑤ 编码实现 → ⑥ 审查验证 | 修复 custom/ai 修复不稳定（用户实测「有时能修有时不能」，排除聚焦因素后确认是 AI 链路稳定性问题）。根因三处：①fixPrompt.buildFixSystemPrompt 只要求「无法修复就输出空」，给了 AI 轻易放弃的空间（→ ai-no-fix）；②customFixEngine.verifyFixed 用 parsed.fixed === true 严格相等，AI 返回字符串 "true" 永不收敛（→ max-iterations）；③收敛失败整体回滚，一次不确定的 AI 重检否定已生成的有效修复。修复（按用户确认的 C1 方案）：①prompt 三语加硬性要求「必须输出修复片段，禁止输出空修复；即使无法完全消除也要给缓解/改善的最小片段」；②requestFix 对空修复/解析失败自动重试 1 次（customFixEngine 与 aiFixEngine 同步，前者重试后仍空才 null）；③verifyFixed 宽松判定 f===true || String(f)==='true'；④C1 收敛降级——循环结束未收敛时若 appliedFixes.length>0 则接受最后一次修复（返回 success+newText 走正常 diff 预览），仅从未生成出可匹配修复才失败；⑤每轮加 console.log('[code-reviewer] review-fix', ruleId, round, {ai-no-fix/ai-match-failed/no-change/applied/verify}) 诊断日志。测试：customFixEngine.test.ts 原 max-iterations 用例改为「accepts last fix when verify never passes」（断言 success=true+newText），新增「retries empty fix once then fails with ai-no-fix」用例（两次空响应）。npm test 111 passing / lint 0 error / compile 通过 | 中间产物：①TS2367 类型不重叠——parsed.fixed 类型 boolean|undefined 与 'true' 字符串比较报错，用 & { fixed?: unknown } 断言 + String(f) 收窄解决；②aiFixEngine 的 ai-no-fix 测试用例只给 1 次空响应，重试后取默认 '{}'（无 originalText）仍返回 ai-no-fix，无需改断言；③C1 实现位置纠结——先想在循环外统一处理，实际把降级分支写在 !converged 内并与 dryRun/apply 复用收尾 | src/fix/fixPrompt.ts src/fix/customFixEngine.ts src/fix/aiFixEngine.ts src/test/customFixEngine.test.ts | deepseek-v4-flash |
+| 2026-08-20 22:32 | ① 用户提出 → ② 需求澄清 → ③ 方案设计 → ④ 人类审批 → ⑤ 编码实现 → ⑥ 审查验证 | 重写 README.md：补齐运行环境要求（VSCode 1.120+/Node/Java/sqlfluff）、安装步骤（VSIX 安装 + 源码构建）、运行方法（端用户命令表 + 开发者命令表）、前端 Webview 面板启动方式、API 密钥配置（SecretStorage + 配置项表 + 自定义供应商）、依赖清单（运行/开发依赖表）、其他配置项 | 无 | README.md | deepseek-v4-flash |
+| 2026-08-20 22:33 | ① 用户提出 → ② 需求澄清 → ③ 方案设计 → ④ 人类审批 → ⑤ 编码实现 → ⑥ 审查验证 | 审查验证阶段修正 README：devDependencies 清单中移除不存在的 eslint 条目（eslint 仅存在于 dependencies） | 初版 README 依赖清单误列 eslint 于 dev 表 → 核对 package.json 后移除 | README.md | deepseek-v4-flash |