From 65b9e1915b17611c5d3e5993970f0922ada7a7ac Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E8=8C=83=E6=99=BA=E9=B9=8F?= Date: Thu, 20 Aug 2026 22:34:13 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E9=87=8D=E5=86=99=20README=20=E8=A1=A5?= =?UTF-8?q?=E9=BD=90=E5=AE=89=E8=A3=85/=E8=BF=90=E8=A1=8C/=E7=8E=AF?= =?UTF-8?q?=E5=A2=83=E8=A6=81=E6=B1=82/API=20=E5=AF=86=E9=92=A5=E9=85=8D?= =?UTF-8?q?=E7=BD=AE/=E4=BE=9D=E8=B5=96=E6=B8=85=E5=8D=95/=E5=89=8D?= =?UTF-8?q?=E7=AB=AF=E9=9D=A2=E6=9D=BF=E8=AF=B4=E6=98=8E?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 新增运行环境要求（VS Code ^1.120.0、Node、Java、sqlfluff、内置 ESLint/Stylelint） - 新增安装步骤（VSIX 安装 + 源码构建两方式） - 新增运行方法（端用户命令表 + 开发者命令表） - 新增前端 Webview 面板启动方式说明 - 新增 API 密钥配置说明（SecretStorage 存储 + 配置项表 + 自定义供应商） - 新增依赖清单（运行时/开发依赖表）及 linter/PMD/SQLFluff 等配置项 --- README.md | 145 ++++++++++++++++++++++++++++++++++++++++++++--- _AI_USAGE_LOG.md | 2 + 2 files changed, 138 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index b2749be..8ed4dd5 100644 --- a/README.md +++ b/README.md @@ -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 +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` 查看。 diff --git a/_AI_USAGE_LOG.md b/_AI_USAGE_LOG.md index 115cc90..91b2515 100644 --- a/_AI_USAGE_LOG.md +++ b/_AI_USAGE_LOG.md @@ -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 |