范智鹏
9c676e46e6
- AI 修复预生成：静态/custom/AI 条目审查时预生成修复片段（originalText/newText），展开问题即显示行级 diff，无预生成时展示占位提示，匹配失败回退实时 LLM 生成 - 修复前 diff 预览：侧边新建编辑器组打开内置 diff，确认后写入（两步确认），不覆盖当前文件 - fix: sqlfluff 在 jinja 标签位于注释内时 JJ01 JSON 缺失 end_line_no/end_line_pos，适配器 Range 构造产生 NaN 被 VSCode 交换 start/end 导致行号 LNaN；新增 resolveSqlFluffRange 兜底 + 面板/report 行号 Number.isFinite 防御 - fix: 从 PMD 内置 ruleset 移除 5 条实际不可触发规则（AvoidAssertAsIdentifier、AvoidEnumAsIdentifier、AccessorClassGeneration、AccessorMethodGeneration、LoosePackageCoupling），内置配置 274→269 条全部可触发，同步 static-rules.json 与翻译脚本 - docs: README/DESIGN 更新
317 lines
35 KiB
Markdown
317 lines
35 KiB
Markdown
# 净码特攻 · 设计文档
|
||
|
||
> **AI 驱动的代码审查、修复与建议的轻量级 VSCode 插件**
|
||
>
|
||
> 引擎要求：VSCode ^1.120.0 ｜ 依据：源码静态阅读 ｜ 生成日期：2026-08-20
|
||
|
||
**目录**：[01 场景与价值](#01-场景描述与业务价值) · [02 开发范式](#02-开发范式sdad-闭环工作流) · [03 架构设计](#03-架构设计) · [04 工具与 API](#04-使用的工具--api-清单及调用方式) · [05 附录](#05-附录)
|
||
|
||
---
|
||
|
||
## 01 场景描述与业务价值
|
||
|
||
### 1.1 场景描述
|
||
|
||
**目标用户**：使用 VSCode 的企业开发团队，尤其是同时维护 **Java、JSP、JavaScript/TypeScript、CSS、SQL** 多语言混合工程（典型如运营商城域后台、金融核心等遗留系统）的开发者。
|
||
|
||
**日常工作流**：开发者在编辑器中编码，插件在后台以 `修改 1000ms 防抖 / 保存 500ms 防抖` 自动执行静态分析，结果实时落入 VSCode「问题」面板；随后通过 `Ctrl+Shift+R`、右键菜单或命令面板触发 AI 深度审查——AI 将英文机器诊断翻译为母语并附加修复建议，同时挖掘静态工具覆盖不到的语义级问题；结果在树形审查面板中按严重级分组展示，可对单条或全部问题执行**分级修复**——linter 原生 fix 优先、AI 修复兜底、自定义/AI 条目走 AI 重检收敛；面板触发的修复先弹出 diff 预览、经面板内两步确认后写入并自动保存（按来源 linter/custom/ai 撤销），hover 波浪线可直接快速修复，最终一键导出 Markdown 审查报告。方法级 CodeLens 入口支持仅对当前方法做正确性/安全/设计/性能/约定五维聚焦审查。
|
||
|
||
**运行约束**：内置 **8 家 AI 供应商**（DeepSeek / OpenAI / Google Gemini / Anthropic Claude / 腾讯混元 / 智谱AI / 月之暗面 / 阿里通义），经 `providers.json` 注册表管理；工作区 `.code-review/providers.json` 可注册**自定义供应商**（同 id 覆盖内置、文件监听热生效）；AI 服务地址（`ai.baseUrl`）可配置以支持内网/私有化部署；API Key 经 `SecretStorage` 加密存储；断网或未配置 Key 时静态通道独立可用，AI 通道优雅降级（`degraded`）不阻塞主流程。
|
||
|
||
### 1.2 业务价值：痛点 → 方案映射
|
||
|
||
| 痛点 | 插件方案（代码事实） |
|
||
|---|---|
|
||
| Linter 报错是英文机器语言，非母语开发者阅读成本高 | AI 深度审查通道将静态诊断**翻译为输出语言**（zh-CN/en/ja）并注入修复建议，合并时按 `originalRuleId` 回贴（精确匹配 → `normalizeRuleId` 前缀归一化兜底）；520 条内置规则自带中/日双语描述 |
|
||
| 静态规则覆盖不了语义级安全漏洞、逻辑错误、设计缺陷 | LLM 深度审查通道专注 security / logic / performance / design 四类增量发现，并被要求**不重复**静态分析已报告的问题 |
|
||
| 团队私有编码规范无法进入通用 linter | **YAML 自定义规则**：自然语言描述 + 严重级 + 语言过滤，由 AI 按语义（而非文本匹配）判定违规，支持热加载 |
|
||
| 发现问题后修复仍靠人工逐条处理 | **分级修复闭环**：linter 原生 fix 优先（`fixEngine` 多轮循环收敛）→ 无原生 fix 项走 AI 修复（原文匹配 + 重 lint 验证收敛）→ custom/AI 条目走 AI 重检收敛（失败降级接受最后有效修复）；面板触发先 **diff 预览两步确认** 再写入、自动保存、按来源撤销（`fixSession` 多片段合并） |
|
||
| 多语言多工具（ESLint/PMD/Stylelint/SQLFluff）碎片化 | **统一适配器层** + 配置驱动路由 `linters.<language>`，5 个适配器覆盖 7 类语言映射，JSP 由 PMD+ESLint+Stylelint 组合适配器承接 |
|
||
| 审查结果难以留档与汇报 | `MergedReport` 统一模型一键导出 Markdown 报告（含数量统计、降级状态、耗时） |
|
||
|
||
> **能力速览（均来自源码）**：10 个面板命令 + 5 个内部命令 · 5 个 linter 适配器 · 7 类语言映射（javascript/typescript → ESLint，java → PMD，css → Stylelint，sql/plsql → SQLFluff 含 28 方言可配，jsp/html → JSP 组合适配器）· 3 种输出语言 · 双通道并行 AI 审查（8 家内置供应商 · providers.json 注册表 · 自定义供应商热加载）· 分级修复（原生 fix → AI 回退 → AI 重检）+ diff 预览两步确认 · 编辑器波浪线实时标记 · 111 个测试用例。
|
||
|
||
---
|
||
|
||
## 02 开发范式：SDAD 闭环工作流
|
||
|
||
团队采用自定义方法论 **SDAD（Stage-Driven Agent Development，阶段驱动智能体开发）**，定义于仓库根目录 `AGENTS.md`，以 AI 编码智能体（DeepSeek `deepseek-v4-flash / deepseek-v4-pro`）作为执行主体、人类作为阶段守门人。流程**顺序执行、不可跳过或合并**；②需求澄清为自循环、可能重复多次直至共识，④人类审批为**必经门**。**范式步骤名称即 AI 使用日志「范式步骤」列的取值**，一一对应、可逐条核验：
|
||
|
||
**① 用户提出 → ② 需求澄清 → ③ 方案设计 → ④ 人类审批 → ⑤ 编码实现 → ⑥ 审查验证**
|
||
|
||
```mermaid
|
||
flowchart TB
|
||
subgraph LINE["主线：顺序执行，不可跳过或合并"]
|
||
direction LR
|
||
S1["① 用户提出<br/>load skill :: stage-1-propose<br/>──────────────<br/>Human：描述任务目标<br/>Agent：等待输入，不做预设"]
|
||
S2["② 需求澄清<br/>⟳ 自循环·可重复多次<br/>load skill :: stage-2-clarify<br/>──────────────<br/>Human：回答追问，确认共识<br/>Agent：探索代码库·一次一问·推荐选项"]
|
||
S3["③ 方案设计<br/>load skill :: stage-3-design<br/>──────────────<br/>Human：此阶段不介入<br/>Agent：产出完整方案（架构·文件清单·接口·选型·影响范围）"]
|
||
S4["④ 人类审批「必经门」<br/>load skill :: stage-4-approve<br/>──────────────<br/>Human：评审方案，通过/否决/修改<br/>Agent：呈现变更摘要，等待决策"]
|
||
S5["⑤ 编码实现<br/>load skill :: stage-5-implement<br/>──────────────<br/>Human：被动介入，仅回应遗漏/矛盾<br/>Agent：严格按方案编码，矛盾即暂停提问"]
|
||
S6["⑥ 审查验证<br/>load skill :: stage-6-verify<br/>──────────────<br/>Human：最终验收确认<br/>Agent：lint/编译/测试 + AI 自审"]
|
||
|
||
S1 --> S2
|
||
S2 --> S3
|
||
S3 --> S4
|
||
S4 --> S5
|
||
S5 --> S6
|
||
S4 -.->|"否决 → 回退②"| S2
|
||
S4 -.->|"方案层面问题 → 回退③"| S3
|
||
S6 -.->|"严重代码问题 → 回退⑤"| S5
|
||
S6 -.->|"修改建议 → 回退③"| S3
|
||
end
|
||
|
||
LOG["日志规则（每阶段完成后自动执行）<br/>立即向 _AI_USAGE_LOG.md 追加：日期时间（不可乱填或估算）· 范式步骤 · 修改摘要 · 中间产物 · 涉及文件 · 使用模型；完成记录后方可进入下一步"]
|
||
|
||
LINE -.->|"每阶段完成即记录"| LOG
|
||
|
||
classDef gate stroke:#111,stroke-width:3px
|
||
class S4 gate
|
||
```
|
||
|
||
*图 2-1 SDAD 开发范式工作流（团队开发过程的工作流设计，非产品架构图）：六个范式步骤名与 `_AI_USAGE_LOG.md`「范式步骤」列一一对应，供评委对照验证；实线为正向推进，虚线为回退路径，② 需求澄清为自循环（节点内 ⟳ 标记，可能重复多次直至共识达成），④ 人类审批为必经门（未通过不得进入编码）*
|
||
|
||
### 2.1 六阶段执行技能与人机职责映射
|
||
|
||
| 范式步骤（日志取值） | SDAD 执行技能（.opencode/skills） | Human 职责 | Agent 职责 |
|
||
|---|---|---|---|
|
||
| ① 用户提出 | `stage-1-propose` | 描述任务目标 | 不做任何操作（等待输入，不做预设） |
|
||
| ② 需求澄清 | `stage-2-clarify`（自循环·可能重复多次） | 回答追问、补充信息，确认或否决推荐答案，最终确认共识达成 | 从代码库探索，沿设计树逐步追问、一次一问、给出推荐选项，逐层解决依赖 |
|
||
| ③ 方案设计 | `stage-3-design` | 此阶段不介入 | 基于共识产出完整方案：架构概览、文件变更清单、关键接口/API 定义、技术选型与依赖、变更影响范围 |
|
||
| ④ 人类审批 | `stage-4-approve`（**必经门**） | 评审方案摘要与变更理由，决策通过 / 否决 / 修改 | 呈现变更摘要与理由，等待决策；未通过审批不得进入编码 |
|
||
| ⑤ 编码实现 | `stage-5-implement`（implementation plan → 20 个逐文件步骤） | 被动介入，仅当 Agent 发现遗漏/矛盾时回应 | 严格按方案编码不自行发挥，发现遗漏/矛盾即暂停提问；遵循项目代码风格 |
|
||
| ⑥ 审查验证 | `stage-6-verify`（含缺陷回归迭代） | 最终验收确认 | 运行 lint / 类型检查 / 编译 / 已有测试；AI 自审潜在 bug、边界与安全；汇总结果 |
|
||
|
||
### 2.2 日志实证摘录（范式 ↔ 日志对照）
|
||
|
||
| 范式步骤 | _AI_USAGE_LOG.md 中的典型记录 | 产出物 | 使用工具 |
|
||
|---|---|---|---|
|
||
| ① 用户提出 → ② 需求澄清 | 「阅读 AGENTS.md、需求描述、原型图、参考代码片段」「阅读需求文档并归纳需求要点，确定交付物」「编写开源库调研（六个选项）」 | `docs/superpowers/specs/2026-07-10-code-reviewer-design.md` | deepseek-v4-flash |
|
||
| ③ 方案设计 | 「输出功能模块、技术选型、接口约定」「设计 AI 技术方案（Provider 多态、流式支持、Prompt 工程）」「生成界面原型 HTML + UI 需求分析」「实施步骤 6 个 Phase 生成完毕」「拆分步骤：逐文件开发计划（20 个）」 | design spec、原型 HTML、implementation plan、20 个 step 文档 | deepseek-v4-flash |
|
||
| ④ 人类审批 | 方案摘要与变更理由呈报人类评审，用户明确确认「通过」后方放行编码（必经门：未通过审批不得进入 ⑤） | 审批通过的设计方案与逐文件开发计划 | 人工评审 |
|
||
| ⑤ 编码实现 | 「Phase 1 基础层：类型定义 + 配置模块」「Phase 2.2 ESLint 适配器落地」「Phase 3 编排器」「Phase 4.2 AI 引擎 + Schema：流式逐块解析 + 验证 JSON」「Phase 5.1 命令注册器 + extension.ts 骨架：8 个命令注册」「Phase 6.1 构建脚本」 | `src/` 各模块源码 | deepseek-v4-flash / deepseek-v4-pro |
|
||
| ⑥ 审查验证 | 「编译/测试（lint & compile & test）」「美化 VSIX：修复 .vscodeignore 体积和 README」「交付检查：打标 VSIX」；回归记录「Bug fix: codeReviewer.openSetup 命令 catch 与用户交互不足」「Bug fix: stylelint 规则列表不存在 → .vscodeignore 忽略 .mjs」「修复界面原型：TreeView 和 Webview 不同步」「面板语言不匹配以及交互卡顿（分组延迟推送）」「AI 引擎重试逻辑优化」 | 通过 lint+test 的构建产物、.vsix 包、回归后的修复代码 | npm / F5 / vsce / deepseek-v4-flash |
|
||
|
||
> **闭环反馈机制**：① 顺序执行、不可跳过或合并，每个阶段完成后立即向 `_AI_USAGE_LOG.md` 追加一条记录（日期时间 / 范式步骤 / 修改摘要 / 中间产物 / 涉及文件 / 使用模型）方可进入下一步；② 需求澄清为自循环——沿设计树一次一问、重复多次直至共识达成；③ 人类审批为必经门——方案层面问题回退③方案设计、否决回退②需求澄清，未通过不得进入编码；④ 审查验证发现严重代码问题回退⑤编码实现（必要时上溯③方案设计），修改建议回退对应环节修复后回归验证；⑤ 线上缺陷作为新任务回到①用户提出重新走流程——由此构成「提出→澄清→设计→审批→编码→验证」的完整闭环。
|
||
|
||
---
|
||
|
||
## 03 架构设计
|
||
|
||
### 3.1 插件 / 工具整体架构（六层）
|
||
|
||
插件整体采用六层单向依赖架构，自上而下为表现层、激活调度层、编排层、适配层、AI Provider 层与支撑层；适配层与 AI Provider 层分别以子进程/HTTPS 方式对接外部静态分析工具与 AI 服务，是整个系统的骨架。
|
||
|
||
```mermaid
|
||
flowchart TB
|
||
L1["L1 表现层 · VSCode UI<br/>SetupViewProvider（配置 Webview：供应商/Key/模型/语言/规则开关 · 供应商清单来自注册表并监听 .code-review/providers.json 热更新）<br/>ReviewPanel（审查面板 Webview：树形分组 · 深色主题 · 外置 reviewPanel.js 脚本规避 CSP 屏蔽）<br/>DiagnosticMarkers（Problems 实时标记）· MethodCodeLensProvider（方法级入口）<br/>10 个命令 · 编辑器右键菜单 · Ctrl+Shift+R · 活动栏视图容器「净码特攻」"]
|
||
L2["L2 激活调度层 · extension.ts<br/>activate / deactivate · 启动即扫描已打开文档<br/>事件订阅：onDidOpen / onDidChange(清除标记+防抖) / onDidSave / onDidClose(清缓存)<br/>防抖调度 1000ms·500ms · document.version 版本守卫丢弃过期结果 · i18n 热切换"]
|
||
L3["L3 编排层 · Pipeline<br/>Orchestrator（runStaticAnalysis 配置驱动路由）<br/>AI Engine（runAIReview 双通道 / runMethodReview 方法级）<br/>Merger（mergeResults → MergedReport：译文注入·排序·可修复索引）<br/>Fix 引擎组：fixEngine 原生多轮收敛 · aiFixEngine AI 回退 · customFixEngine 重检收敛<br/>fixPreview Diff 预览 · fixPending 两步确认 · fixSession 撤销 · codeActionProvider hover 修复<br/>Report 导出 · degraded 降级标记"]
|
||
L4["L4 适配层 · LinterAdapter<br/>契约：id · supportedLanguages · check(document, workingDir) · isAvailable()<br/>ESLintAdapter(JS/TS) · PmdAdapter(Java·PmdRunner.java+XML 规则集)<br/>StylelintAdapter(CSS) · SqlFluffAdapter(SQL·方言检测) · JspAdapter(JSP 组合)<br/>状态契约 AdapterStatus：ok / tool-unavailable / execution-failed —— 工具缺失优雅降级"]
|
||
L5["L5 AI Provider 层 · 协议驱动 + 注册表<br/>abstract AIProvider.chat(systemPrompt, userPrompt, ChatOptions)<br/>registry 供应商注册表：内置 providers.json（8 家）+ 工作区 .code-review/providers.json 覆盖合并<br/>createProvider 按 protocol 路由 PROTOCOL_MAP：OpenAICompatibleProvider / GeminiProvider / ClaudeProvider<br/>流式逐块解析 · 空响应重试(EmptyContentError)<br/>结构化输出加固：JSON 区段提取 + repairJsonEscapes 转义修复 + 失败降级记录"]
|
||
L6["L6 支撑层 · Foundation<br/>config（ai · linter · pmd · sqlfluff · fixer）· secret（SecretStorage 封装）<br/>rules（YAML 解析与规则转换）· i18n（zh-CN / en / ja）<br/>scope（method-extractor 方法提取 · status-cache 状态缓存）<br/>utils（debounce 防抖 · report 报告导出 · mockDocument 修复内存模拟）· types（跨模块类型契约）"]
|
||
|
||
EXT["外部系统<br/>Node 运行时（ESLint/Stylelint 库直调）<br/>Java + PMD.jar（java 子进程 + XML 规则集）<br/>SQLFluff CLI（sqlfluff 子进程 + 方言参数）<br/>8 家 AI 供应商 API（HTTPS：OpenAI 兼容协议 ×6 · Gemini · Claude）<br/>Maven/Gradle classpath 自动注入 PMD"]
|
||
|
||
L1 --> L2
|
||
L2 --> L3
|
||
L3 --> L4
|
||
L4 --> L5
|
||
L5 --> L6
|
||
L4 -. 子进程/直调 .-> EXT
|
||
L5 -. HTTPS .-> EXT
|
||
```
|
||
|
||
*图 3-1 插件整体六层架构与外部系统。单向依赖：上层仅依赖相邻下层接口；适配层与 AI Provider 层可被编排层等价替换/扩展（新增 linter 或模型只需实现契约 + 注册工厂）。打包：esbuild 单文件 bundle → vsce 生成 .vsix（.vscodeignore 裁剪运行时依赖体积）。*
|
||
|
||
### 3.2 组件划分
|
||
|
||
| 模块（src/） | 职责 | 关键接口 / 类型（代码实证） |
|
||
|---|---|---|
|
||
| `extension.ts` + `activation/commands.ts` | 生命周期、事件订阅、防抖调度、命令注册 | `activate()` / `scheduleAnalysis(doc, delay)` / 10 个 `registerCommand` |
|
||
| `orchestrator/` | 配置驱动的静态分析编排 | `runStaticAnalysis(document, workingDir): StaticAnalysisResult` |
|
||
| `adapters/` | 统一封装 5 个 linter（Node API / CLI 进程） | `LinterAdapter.check()` / `isAvailable()` / `AdapterResult` |
|
||
| `ai/` | AI 审查引擎（双通道 + 方法级） | `runAIReview()`（Promise.allSettled 双请求）/ `runMethodReview()` / `parseJsonResponse()` |
|
||
| `ai/registry.ts` | 供应商注册表 | `getProviders()`（内置 providers.json 8 家 + 工作区 `.code-review/providers.json` 按 id 覆盖合并）/ `invalidateProviderCache()` / `getAllProviderMeta()` |
|
||
| `ai/providers/` + `ai/factory.ts` | 三协议接入抽象与协议工厂 | `AIProvider.chat()` → OpenAICompatible / Gemini / Claude；`createProvider(providerId, apiKey, baseUrl, extensionUri)` 按 `protocol` 路由 `PROTOCOL_MAP` 实例化 |
|
||
| `merger/` | 三通道结果统一合并 | `mergeResults(input): MergedReport`（译文注入 + `normalizeRuleId` 归一化回贴、严重级+行号排序、native/aiFixable 修复索引） |
|
||
| `fix/`（8 模块） | 分级修复引擎组：原生 fix 多轮循环、AI 修复回退、custom/ai 条目重检、diff 预览、两步确认、撤销会话、hover 快捷修复 | `fixDiagnostic()`（原生）/ `aiFixDiagnostic()`（AI 回退）/ `aiFixReviewIssue()`（重检收敛）/ `FixPendingStore` / `fixSession.recordFixes()` |
|
||
| `rules/` | 自定义规则解析与转换 | YAML → `CustomRule`（id/severity/description/语言过滤） |
|
||
| `scope/` | 方法级作用域与状态 | method-extractor（括号配对）/ `ReviewStatusCache` |
|
||
| `views/` + `panel/` | 配置 Webview、CodeLens、审查面板 | `SetupViewProvider` / `MethodCodeLensProvider` / webview `postMessage` / `reviewPanel.js`（外置脚本） |
|
||
| `diagnostics/` | 问题面板标记同步 | `DiagnosticMarkers.apply(uri, diagnostics)` / `clear()` |
|
||
| `config/ · secret/ · i18n/ · utils/ · types.ts` | 配置、密钥、国际化、防抖、契约 | `getAIProvider()` 等 getter / SecretStorage / `t()` / `debounce` |
|
||
|
||
### 3.3 端到端数据流
|
||
|
||
```mermaid
|
||
flowchart TB
|
||
E["编辑器事件<br/>打开/修改/保存/选区"] --> D["防抖 + 版本守卫<br/>1000/500ms · 丢弃过期"]
|
||
D --> S["静态分析<br/>适配器 check() → 诊断集"]
|
||
S --> AI["AI 双通道并行<br/>规则匹配 + 深度审查"]
|
||
AI --> J["JSON 提取修复<br/>区段截取 + 转义修复 + 重试"]
|
||
J --> MR0["mergeResults<br/>合并·译文注入·排序"]
|
||
S -. "实时旁路：诊断直接落 Problems 标记（无需等待 AI）" .-> PR["Problems 实时标记"]
|
||
MR0 --> MR["MergedReport<br/>三通道统一报告模型"]
|
||
MR --> V["多端呈现<br/>面板/Problems/CodeLens"]
|
||
V --> F["修复分派 resolveFix<br/>原生 fix 优先 → AI 修复回退<br/>→ custom/ai 条目 AI 重检收敛"]
|
||
F --> P["Diff 预览 + 两步确认<br/>dryRun 计算 newText · 内置 diff 编辑器<br/>FixPendingStore 面板内应用/取消"]
|
||
P --> U["写入 + 撤销会话<br/>单次 WorkspaceEdit · 自动保存<br/>fixSession 多片段合并撤销"]
|
||
U --> RA["修复后重分析<br/>验证修复效果 · 闭环回到静态分析"]
|
||
RA --> X["导出报告<br/>Markdown"]
|
||
RA -. "修复后自动重分析（行动结果回流感知，形成审查-修复闭环）" .-> S
|
||
```
|
||
|
||
*图 3-2 端到端数据流：从编辑器事件到报告导出的完整管道与两条闭环。*
|
||
|
||
### 3.4 关键设计决策
|
||
|
||
| 决策 | 设计说明 |
|
||
|---|---|
|
||
| **D1 配置驱动的适配器编排** | `linters.<language>` 配置项决定路由，适配器数组按 `id` 查找；JSP 作为组合适配器复用 PMD/ESLint/Stylelint 三者，而非新写解析器。 |
|
||
| **D2 双通道并行而非单 Prompt** | `runAIReview` 用 `Promise.allSettled` 并行「规则匹配」「深度审查」两请求：职责隔离、单通道失败不影响另一通道，`degraded` 标记降级。 |
|
||
| **D3 结构化输出加固** | 对 LLM 返回做 JSON 区段截取、`repairJsonEscapes` 转义修复、`chatWithRetry` 空响应重试三层防御，保证结构化结果可解析。 |
|
||
| **D4 翻译注入式合并** | AI 译文与建议按 `originalRuleId` 回贴到静态诊断上（`translationsByRule` Map），Prompt 同时要求「不重复静态已报告问题」，避免双通道结果重复。 |
|
||
| **D5 原生优先的分级修复与两步确认** | `resolveFix` 三级分派：linter 原生 fix（ESLint/Stylelint `msg.fix`）走 `fixEngine` 多轮循环——`mockDocument` 内存模拟迭代、修复区域重叠判定收敛、单次 WorkspaceEdit 提交；无原生 fix 的静态项走 `aiFixEngine`（全文匹配 + 重 lint 验证收敛）；custom/AI 条目走 `customFixEngine`（AI 重检收敛，未收敛但有有效修复则降级接受）。面板触发先 dryRun → 内置 diff 预览 → `FixPendingStore` 两步确认再写入并自动保存；hover 直接应用；`fixSession` 按来源（linter/custom/ai）多片段合并撤销。 |
|
||
| **D6 防抖 + 版本守卫** | 修改 1000ms、保存 500ms 双阈值防抖；分析返回后比对 `document.version`，过期结果直接丢弃，防止旧结果覆盖新代码标记。 |
|
||
| **D7 供应商注册表 + 协议工厂** | `registry` 将内置 `providers.json`（DeepSeek / OpenAI / Gemini / Claude / 腾讯混元 / 智谱AI / 月之暗面 / 阿里通义 8 家）与工作区 `.code-review/providers.json` 按 id 覆盖合并，`FileSystemWatcher` 监听文件变化 + 缓存失效实现热更新；`createProvider` 按 `ProviderConfig.protocol` 从 `PROTOCOL_MAP` 实例化 openai-compatible / gemini / claude 三协议类——**新增供应商零代码**，写一份 providers.json 即可接入；`ai.baseUrl` 可改写，天然支持内网网关。 |
|
||
| **D8 分层单向依赖** | 表现/激活/编排/适配/Provider/支撑六层单向依赖，适配层与模型层均为可替换契约，扩展新 linter 或新模型零侵入上层。 |
|
||
|
||
---
|
||
|
||
## 04 使用的工具 / API 清单及调用方式
|
||
|
||
### 4.1 静态分析工具矩阵（适配器调用方式）
|
||
|
||
| 语言（languageId） | linter（配置默认值） | 调用方式（代码事实） | 关键配置 |
|
||
|---|---|---|---|
|
||
| javascript / typescript | ESLint `^9.39.3`（+ `@eslint/js`、`typescript-eslint ^8.56.1`） | **Node API 进程内直调**：适配器内实例化 ESLint Linter，加载 `eslint.config.mjs`（typescript-eslint parser），对文档文本执行 lint | `linters.eslint.enabled`、`linters.eslintConfigPath` |
|
||
| css / scss 等 | Stylelint `^17.14.0`（+ `stylelint-config-recommended`） | **Node API 直调**：lint() API，配置文件可选（默认用插件内置 recommended 配置），编译期以 tsconfig `skipLibCheck` 兼容 | `linters.stylelint.enabled`、`linters.stylelintConfigPath` |
|
||
| java | PMD（外部 Java 工具） | **子进程调用**：`java -jar pmd.jar`，通过随包分发的 `jars/pmd/PmdRunner.java` 包装器 + 自定义 XML 规则集执行；`pmd.autoAuxClasspath` 自动把 Maven/Gradle 依赖注入 PMD classpath；JAR 由 `scripts/download-pmd.mjs` 下载（支持网络代理） | `pmd.jarPath`、`pmd.rulesetPath`、`pmd.autoAuxClasspath` |
|
||
| sql / plsql | SQLFluff（外部 CLI） | **子进程调用**：CLI 执行 + 自动方言检测（支持 mysql/postgresql/oracle/db2/hive 等 28 种方言枚举），可指定配置文件 | `sqlfluff.configFile`、`sqlfluff.dialect`、`linter.sqlfluff.enabled` |
|
||
| jsp / html | JSP 组合适配器 | **组合调用**：先经 `jsp-extractor` 提取 JSP 内嵌脚本，再复用 **PMD（JSP 规则集）+ ESLint + Stylelint** 三者结果合并 | `pmd.jspRulesetPath`、`linters.jsp`、`linters.html` |
|
||
|
||
> 统一契约：`LinterAdapter { id · supportedLanguages · check(document, workingDir) · isAvailable() }`；返回 `AdapterResult { diagnostics · status · errorMessage }`，状态含 `ok / tool-unavailable / execution-failed`——外部工具缺失时报告而非崩溃。
|
||
|
||
### 4.2 AI 模型 API 及调用方式
|
||
|
||
| 项目 | 说明 |
|
||
|---|---|
|
||
| 提供商与协议 | **内置 8 家供应商**（`providers.json` 注册表，随 VSIX 分发）：DeepSeek（默认）/ OpenAI / Google Gemini / Anthropic Claude / 腾讯混元 / 智谱AI / 月之暗面 / 阿里通义；**三种协议实现**：`openai-compatible`（6 家通用）· `gemini` · `claude`；工作区 `.code-review/providers.json` 同 id 覆盖内置实现自定义供应商（`FileSystemWatcher` 监听 + 缓存失效热生效） |
|
||
| 调用入口 | `createProvider(providerId, apiKey, baseUrl, extensionUri)` 查注册表按 `protocol` 实例化 → `AIProvider.chat(systemPrompt, userPrompt, ChatOptions)`；审查走 `runAIReview()` 双通道并行（`Promise.allSettled`），修复走 `fix/` 三级引擎（原生 fix 优先 → `aiFixDiagnostic()` AI 回退 → `aiFixReviewIssue()` custom/ai 条目重检收敛），方法级走 `runMethodReview()` |
|
||
| Prompt 工程 | 系统提示按输出语言（zh-CN/en/ja）三语模板构建：深度审查通道要求「翻译静态诊断为输出语言+补修复建议」与「挖掘安全/逻辑/性能/设计增量问题且不重复静态结果」；用户提示注入**带行号代码**、静态诊断清单（`ruleId L行号: 消息`）、自定义规则清单 |
|
||
| 解码参数 | `model`（默认 deepseek-chat）· `temperature 0.2` · `maxTokens 8192` · `timeout 300s`，均可经 VSCode 设置覆盖 |
|
||
| 健壮性 | 流式逐块解析；空响应触发重试（`chatWithRetry` + `EmptyContentError` 附 finish_reason 诊断）；`max_tokens` 截断专用报错；JSON 区段截取 + `repairJsonEscapes` 转义修复；修复链路空输出自动重试一次 + 宽松验证（`fixed === true \|\| String(f) === "true"`）+ 收敛降级接受最后有效修复；失败标记 `degraded` 并保留静态通道结果 |
|
||
| 密钥管理 | API Key 存于 VSCode `SecretStorage`（加密），配置面板可视化设置并测试连通性 |
|
||
|
||
### 4.3 VSCode 扩展 API 清单
|
||
|
||
| 能力域 | API（代码实证） | 用途 |
|
||
|---|---|---|
|
||
| 命令与菜单 | `commands.registerCommand` × 10、`package.json contributes`（commands/menus/keybindings/viewsContainers/views/configuration） | 注册 10 个命令、右键菜单、Ctrl+Shift+R、活动栏「净码特攻」容器与配置视图 |
|
||
| 文档事件 | `workspace.onDidOpen/onChange/Save/CloseTextDocument` | 触发防抖分析 / 清除标记 / 清理缓存 |
|
||
| 编辑器交互 | `window.activeTextEditor`、`Selection`、`languages.registerCodeActionsProvider`、`TextDocumentContentProvider`、`window.showTextDocument` + `visibleTextEditors` | 选区审查、hover 快速修复链接（CodeAction）、diff 预览（`codeReviewerPreview` scheme）、行号跳转复用已开编辑器防新开副本 |
|
||
| 诊断标记 | DiagnosticCollection（`DiagnosticMarkers` 封装） | 静态诊断实时同步「问题」面板（`markers.enabled`） |
|
||
| Webview | `window.registerWebviewViewProvider`、`webview.postMessage` | 配置面板（`codeReviewer.setupView`）与审查面板的渲染和双向通信 |
|
||
| CodeLens | `languages.registerCodeLensProvider` | 方法级「审查此方法」快捷入口（ts/js/java/python） |
|
||
| 工作区编辑 | `WorkspaceEdit` + `workspace.applyEdit` | 修复单次提交（整文档替换）、diff 预览确认后写入（`applyNewText`）、撤销回滚 |
|
||
| 配置与密钥 | `workspace.getConfiguration`、`context.secrets`（SecretStorage）、`onDidChangeConfiguration`、`workspace.createFileSystemWatcher` | 读取 30+ 配置项、加密存 Key、语言热切换、监听 `.code-review/providers.json` 供应商清单热更新 |
|
||
| 基础类型 | `TextDocument / Range / Position / Uri`（`lineAt / getText / version`） | 诊断定位、版本守卫、文件路径处理 |
|
||
|
||
### 4.4 命令清单（10 个面板命令 + 5 个内部命令）
|
||
|
||
| 命令 ID | 标题 | 说明 |
|
||
|---|---|---|
|
||
| `codeReviewer.review` | 手动代码审查 | 全文档三通道审查（快捷键 Ctrl+Shift+R，亦可右键触发） |
|
||
| `codeReviewer.reviewSelection` | 审查选中代码 | 仅对选区执行（右键，需有选中） |
|
||
| `codeReviewer.reviewMethod` | 审查当前方法 | 方法级五维聚焦审查（CodeLens 入口） |
|
||
| `codeReviewer.openPanel` | 打开审查面板 | 树形结果面板（Webview） |
|
||
| `codeReviewer.openSetup` | 打开配置面板 | 可视化配置向导 |
|
||
| `codeReviewer.fixIssue` | 一键修复问题 | 单条三级分派：原生 fix → AI 回退 → custom/ai 重检；面板来源经 diff 预览两步确认 |
|
||
| `codeReviewer.fixAll` | 全部一键修复 | 分 tab 批量（linter/custom/ai 各自批量）→ 合并 diff 预览 → 确认后一次写入 |
|
||
| `codeReviewer.exportReport` | 导出审查报告 | MergedReport → Markdown |
|
||
| `codeReviewer.addCustomRule` | 添加自定义规则 | YAML 规则录入 |
|
||
| `codeReviewer.exportTemplate` | 导出配置模板 | 规则/配置模板文件 |
|
||
|
||
另有 **5 个内部命令**经 `registerCommand` 注册、由面板按钮直接调用（不出现在命令面板）：`codeReviewer.undoFix`（撤销最近修复）、`codeReviewer.applyFixPreview` / `cancelFixPreview`（单条 diff 预览的应用/取消）、`codeReviewer.applyAllPreview` / `cancelAllPreview`（批量 diff 预览的应用/取消）。
|
||
|
||
### 4.5 运行时依赖与工程化工具
|
||
|
||
| 类别 | 工具 / 库（版本） | 用途与调用方式 |
|
||
|---|---|---|
|
||
| 打包进 VSIX 的运行时依赖 | eslint `^9.39.3` · @eslint/js · typescript-eslint `^8.56.1` | JS/TS 静态分析（Node API 直调） |
|
||
| 打包进 VSIX 的运行时依赖 | stylelint `^17.14.0` · stylelint-config-recommended `^18.0.0` | CSS 静态分析（Node API 直调） |
|
||
| 打包进 VSIX 的运行时依赖 | mammoth `^1.12.0` · officeparser `^7.5.0` · xlsx `^0.18.5` | Office/Excel 文档解析运行时库（随插件分发） |
|
||
| 构建链 | esbuild `^0.28.1`（`scripts/build.mjs`）+ tsc | 单文件 bundle + 类型检查；`copy-webview-js.mjs` 拷贝前端资源 |
|
||
| 构建链 | @vscode/vsce + `package-prod.mjs` + `.vscodeignore` | VSIX 生产打包与体积裁剪（迭代中修复过 .mjs 误打包问题） |
|
||
| 质量与测试 | eslint（自检 `npm run lint`）· mocha + @vscode/test-cli + @vscode/test-electron（`out/test/**/*.test.js`）· F5 扩展开发宿主 | 范式第⑥步「审查验证」的固定工具链：lint & compile & test & 手动实测（当前 111 个测试用例） |
|
||
| 外部工具分发 | `scripts/download-pmd.mjs`（含网络代理支持）· `jars/pmd/PmdRunner.java` + 2 个 XML 规则集 | PMD 运行时下载与 Java 包装执行 |
|
||
|
||
### 4.6 开发期 AI 工具链（范式执行载体）
|
||
|
||
| 工具 | 角色与调用方式 |
|
||
|---|---|
|
||
| DeepSeek（`deepseek-v4-flash` / `deepseek-v4-pro`） | AI 编码智能体本体：由人类下达阶段指令，按 SDAD 技能逐步执行需求归纳、方案生成、原型生成、逐文件编码、缺陷修复（日志「使用工具」列全程留痕） |
|
||
| `AGENTS.md` | 方法论载体：五大铁律、六阶段技能加载规则、常用命令表；每次会话注入给智能体 |
|
||
| `.opencode/skills/stage-1-propose … stage-6-verify` | 六阶段执行技能：按阶段 `load skill stage-N-*` 切换智能体行为模式 |
|
||
| `_AI_USAGE_LOG.md` | 过程留痕账本：日期时间｜范式步骤｜修改摘要｜中间产物｜涉及文件｜使用模型，与范式图步骤名一一对应 |
|
||
| `docs/superpowers/specs/` | 阶段产物库：design spec、implementation plan、20 个逐文件 step 文档、原型 HTML——「严禁提前实现」的依据 |
|
||
|
||
---
|
||
|
||
## 05 附录
|
||
|
||
### 5.1 源码目录结构（依据 import 关系还原）
|
||
|
||
```text
|
||
src/
|
||
├─ extension.ts # activate / deactivate 入口
|
||
├─ types.ts # LinterAdapter / LinterDiagnostic / CustomRule 契约
|
||
├─ activation/commands.ts # 10 个命令注册
|
||
├─ orchestrator/orchestrator.ts # 配置驱动静态编排（5 适配器）
|
||
├─ adapters/ # adapter.ts(契约) · eslint · pmd · stylelint · sqlfluff · jsp
|
||
├─ ai/ # engine.ts(双通道) · schema.ts · registry.ts(供应商注册表) · factory.ts(协议工厂) · types.ts(ProviderConfig/协议类型)
|
||
│ └─ providers/ # base.ts(抽象+EmptyContentError) · openai-compatible.ts · gemini.ts · claude.ts
|
||
├─ merger/merger.ts # mergeResults → MergedReport（归一化译文回贴）
|
||
├─ fix/ # 分级修复引擎组（8 模块）
|
||
│ ├─ fixEngine.ts # 原生 fix 多轮循环（内存模拟+单次提交）
|
||
│ ├─ aiFixEngine.ts # AI 修复回退（linter 无原生 fix 项）
|
||
│ ├─ customFixEngine.ts # custom/ai 条目 AI 生成+重检收敛
|
||
│ ├─ fixPrompt.ts # 共享修复/重检 Prompt（三语）
|
||
│ ├─ fixPreview.ts # Diff 预览（TextDocumentContentProvider）
|
||
│ ├─ fixPending.ts # 两步确认待修复存储（FixPendingStore）
|
||
│ ├─ fixSession.ts # 撤销会话（source: linter/custom/ai）
|
||
│ └─ codeActionProvider.ts # hover 快速修复 CodeAction
|
||
├─ rules/yaml-parser.ts # 自定义规则解析（+ converters）
|
||
├─ scope/ # method-extractor · status-cache
|
||
├─ views/ # setupView.ts · setupView.js · reviewPanel.js(外置脚本) · codeLensProvider.ts
|
||
├─ panel/webview.ts # 审查面板
|
||
├─ diagnostics/diagnosticMarkers.ts # Problems 标记
|
||
├─ config/ # index · ai · linter · fixer · secret
|
||
├─ i18n/messages.ts # zh-CN / en / ja
|
||
├─ services/auxClasspath.ts # Maven/Gradle 依赖 classpath 自动探测（注入 PMD）
|
||
└─ utils/ # debounce · report(Markdown 导出) · mockDocument(修复内存模拟)
|
||
|
||
providers.json # 内置 8 家 AI 供应商清单（id/name/protocol/defaultBaseUrl/models，随 VSIX 分发）
|
||
jars/pmd/ # PmdRunner.java · pmd-java-ruleset.xml · pmd-jsp-ruleset.xml
|
||
scripts/ # build.mjs · download-pmd.mjs · package-prod.mjs · copy-webview-js.mjs
|
||
# translations/(7 个规则翻译数据) · add-static-translations.mjs(520 条三语)
|
||
```
|
||
|
||
### 5.2 常用命令
|
||
|
||
| 命令 | 作用 |
|
||
|---|---|
|
||
| `npm run compile / watch` | tsc 编译 / 监视（+ 拷贝 Webview 资源） |
|
||
| `npm run lint` | ESLint 自检 src/（范式⑥固定动作） |
|
||
| `npm test` | 扩展测试（mocha + vscode-test-electron，先 compile&lint） |
|
||
| `npm run download-pmd` | 下载 PMD JAR（支持代理） |
|
||
| `npm run build / package-prod` | esbuild 打包 / vsce 生产打包 VSIX |
|
||
| F5（VSCode） | 扩展开发宿主实测 |
|
||
|
||
> **文档依据声明**：本设计文档全部内容基于工程**源代码**逐文件阅读整理（package.json、src/extension.ts、src/orchestrator/orchestrator.ts、src/ai/engine.ts、src/ai/registry.ts、src/ai/factory.ts、src/ai/types.ts、src/ai/providers/（base / openai-compatible / gemini / claude）、根目录 providers.json、src/merger/merger.ts、src/fix/fixEngine.ts、src/fix/ 下其余 7 模块、src/diagnostics/diagnosticMarkers.ts、src/services/auxClasspath.ts、src/types.ts、src/adapters/adapter.ts 及 adapters 目录清单，以及开发过程资产 AGENTS.md 与 _AI_USAGE_LOG.md），未依赖仓库既有说明文档的叙述。
|
||
|
||
---
|
||
|
||
*净码特攻 · 设计文档 ｜ 生成日期 2026-08-20*
|