T2-SD0403/2026Technology-Competition

Fork 0

Files

T

fzp 59e5fcde8c docs: 新增 DESIGN.md 设计文档

2026-08-21 10:58:00 +08:00

35 KiB

Raw Blame History

净码特攻 · 设计文档

AI 驱动的代码审查、修复与建议的轻量级 VSCode 插件

引擎要求：VSCode ^1.120.0 ｜依据：源码静态阅读｜生成日期：2026-08-20

目录：01 场景与价值 · 02 开发范式 · 03 架构设计 · 04 工具与 API · 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 使用日志「范式步骤」列的取值，一一对应、可逐条核验：

① 用户提出 → ② 需求澄清 → ③ 方案设计 → ④ 人类审批（必经门） → ⑤ 编码实现 → ⑥ 审查验证

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 服务，是整个系统的骨架。

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 端到端数据流

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 关系还原）

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

35 KiB Raw Blame History Unescape Escape