feat: 适配器 i18n + Provider 动态注册 + SetupView 重构 + jars 资源
- 适配器 i18n 接入（eslint/pmd/sql-lint/stylelint） - Provider 动态注册机制（registry.ts + providers.json + factory 重构） - SetupView 全面重构（setupView.ts 新增 600+ 行） - i18n 消息扩展（messages.ts +210 行） - 规则导入流程优化（import-service / prompt-builder） - 新增 PMD jars 依赖及测试用例
This commit is contained in:
范智鹏
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
@@ -0,0 +1,116 @@
|
||||
# 规则导入转换器架构设计
|
||||
|
||||
## 1. 背景
|
||||
|
||||
当前 `src/views/setupView.ts` 的 `addRule()` 方法（~97 行）将所有文件类型的导入逻辑硬编码在一起：
|
||||
|
||||
- `.yaml/.yml`：直接复制
|
||||
- `.md/.txt`：读取 → AI 转换 → 写入
|
||||
|
||||
每增加一种文件类型就得修改 `addRule()`，导致方法膨胀、可维护性下降。同时 AI 转换逻辑（system prompt、异常处理、清理）也与 UI 层耦合。
|
||||
|
||||
## 2. 目标
|
||||
|
||||
将文件导入逻辑从 UI 层解耦，设计统一的 **Converter 接口 + 注册机制**，使新增文件类型只需添加一个 converter 实现并注册。
|
||||
|
||||
## 3. 架构
|
||||
|
||||
```
|
||||
setupView.ts (addRule)
|
||||
│
|
||||
▼
|
||||
ImportService.convert(srcPath, yamlPath, context)
|
||||
│
|
||||
├── 查表: ext → RuleConverter
|
||||
│
|
||||
▼
|
||||
RuleConverter (接口)
|
||||
├── YamlConverter (直接复制)
|
||||
├── MdConverter (AI 转换)
|
||||
└── TxtConverter (AI 转换)
|
||||
```
|
||||
|
||||
### 3.1 RuleConverter 接口
|
||||
|
||||
```typescript
|
||||
// src/rules/converters/converter.ts
|
||||
|
||||
export interface RuleConverter {
|
||||
supportedExtensions: string[];
|
||||
convert(srcPath: string, yamlPath: string, context: vscode.ExtensionContext): Promise<boolean>;
|
||||
}
|
||||
```
|
||||
|
||||
- `supportedExtensions`：声明支持的扩展名列表（如 `['.yaml', '.yml']`）
|
||||
- `convert()`：源文件 → 写 YAML 到 `yamlPath`，返回是否成功；失败时内部可弹错误提示
|
||||
- 沿用 `LinterAdapter` 风格的接口约定
|
||||
|
||||
### 3.2 ImportService
|
||||
|
||||
```typescript
|
||||
// src/rules/import-service.ts
|
||||
|
||||
class ImportService {
|
||||
private converters: Map<string, RuleConverter> = new Map();
|
||||
|
||||
registerConverter(converter: RuleConverter): void;
|
||||
convert(srcPath: string, yamlPath: string, context: vscode.ExtensionContext): Promise<boolean>;
|
||||
}
|
||||
```
|
||||
|
||||
- `registerConverter()` 遍历 converter 的 `supportedExtensions`，建立 ext → converter 映射
|
||||
- `convert()` 根据 `path.extname(srcPath)` 查找 converter，找不到则返回 false 并弹错误
|
||||
- 重复扩展名注册时后者覆盖前者（允许用户自定义覆盖）
|
||||
|
||||
### 3.3 各 Converter 职责
|
||||
|
||||
| Converter | 扩展名 | 行为 |
|
||||
|-----------|--------|------|
|
||||
| `YamlConverter` | `.yaml`, `.yml` | `fs.copyFileSync(srcPath, yamlPath)` |
|
||||
| `MdConverter` | `.md` | 读文件 → AI 转换 → 写 YAML（逻辑从 `addRule()` 原样移入） |
|
||||
| `TxtConverter` | `.txt` | 同上，共享 AI 转换逻辑 |
|
||||
|
||||
AI 转换逻辑（system prompt、API 调用、清理）提取到 `md-converter.ts` 和 `txt-converter.ts` 中，不再耦合 UI。
|
||||
|
||||
### 3.4 setupView.ts 变化
|
||||
|
||||
`addRule()` 缩减为：
|
||||
|
||||
```
|
||||
1. showOpenDialog（弹窗选文件，保持不变）
|
||||
2. 检查 yamlPath 是否已存在（保持不变）
|
||||
3. 调用 ImportService.convert(srcPath, yamlPath, context)
|
||||
4. refreshRules() 刷新列表（保持不变）
|
||||
```
|
||||
|
||||
AI 转换、文件复制等细节从 `addRule()` 中删除。
|
||||
|
||||
## 4. 文件变更清单
|
||||
|
||||
| 文件 | 操作 | 说明 |
|
||||
|------|------|------|
|
||||
| `src/rules/converters/converter.ts` | 新增 | RuleConverter 接口 |
|
||||
| `src/rules/converters/yaml-converter.ts` | 新增 | .yaml/.yml 转换器 |
|
||||
| `src/rules/converters/md-converter.ts` | 新增 | .md AI 转换器 |
|
||||
| `src/rules/converters/txt-converter.ts` | 新增 | .txt AI 转换器 |
|
||||
| `src/rules/import-service.ts` | 新增 | ImportService 类 |
|
||||
| `src/views/setupView.ts` | 修改 | addRule() 简化，注册 converter |
|
||||
| `src/extension.ts` | 无变更（setupView 自行注册 converters） |
|
||||
|
||||
## 5. 未来扩展（Phase 2 — Excel）
|
||||
|
||||
Converter 架构天然支持扩展。后续添加 Excel 只需：
|
||||
|
||||
1. 新增 `src/rules/converters/excel-converter.ts`
|
||||
2. 实现 `RuleConverter` 接口（依赖 `xlsx` 库）
|
||||
3. 在 `setupView.ts` 或 `extension.ts` 中 `registerConverter(new ExcelConverter())`
|
||||
4. `showOpenDialog` 的 filter 中添加 `xlsx`
|
||||
|
||||
无需修改任何现有 converter 或 import-service 逻辑。
|
||||
|
||||
## 6. 不涉及变更
|
||||
|
||||
- 运行时规则加载（`yaml-parser.ts`）不变，仍只读 `.yaml/.yml`
|
||||
- 文件选择弹窗的 filter 不变（仍为 yaml/yml/md/txt），等 Excel 阶段再扩展
|
||||
- 规则命名逻辑（自动追加 `.yaml`）不变
|
||||
- `getApiKey`、`createProvider` 等 AI 基础设施不变
|
||||
@@ -0,0 +1,46 @@
|
||||
# Excel AI 转换器设计
|
||||
|
||||
## 1. 背景
|
||||
|
||||
当前 ExcelConverter 通过固定列名（id、severity、description、message）解析 Excel 并程序化生成 YAML。非技术人员无法随意使用自己习惯的表头命名，体验受限。
|
||||
|
||||
## 2. 目标
|
||||
|
||||
去掉对固定列名的依赖，将 Excel 内容以 Markdown 表格形式喂给 AI，让 AI 理解任意表头结构并生成 YAML 规则。与 `.md`/`.txt` 的 AI 转换模式保持一致。
|
||||
|
||||
## 3. 设计
|
||||
|
||||
### 3.1 数据流
|
||||
|
||||
```
|
||||
用户选择 .xlsx/.xls 文件
|
||||
↓
|
||||
ExcelConverter.convert()
|
||||
├── XLSX.readFile → sheet_to_json
|
||||
├── 行数据序列化为 Markdown 表格字符串
|
||||
├── 调用 convertContentWithAI(content, context) // 复用 import-service.ts
|
||||
└── AI 返回 YAML → 写入 yamlPath
|
||||
```
|
||||
|
||||
### 3.2 变更范围
|
||||
|
||||
只改一个文件：`src/rules/converters/excel-converter.ts`
|
||||
|
||||
- 删除：列名白名单校验（REQUIRED_FIELDS）、severity 合法值校验（VALID_SEVERITIES）、程序化 YAML 拼接逻辑
|
||||
- 新增：`buildMarkdownTable(rows)` 将 JSON 行转 Markdown 表格
|
||||
- 复用：`convertContentWithAI()` 做 AI 转换并写文件
|
||||
- 保留：`XLSX.readFile` 的 try/catch 错误处理
|
||||
|
||||
### 3.3 Markdown 表格格式示例
|
||||
|
||||
```
|
||||
| id | severity | description | message | languages |
|
||||
|----|----------|-------------|---------|-----------|
|
||||
| rule-1 | warning | 禁止直接使用 console.log | 请使用 logger 代替 | javascript, typescript |
|
||||
```
|
||||
|
||||
### 3.4 不涉及变更
|
||||
|
||||
- `setupView.ts`：ExcelConverter 已注册、过滤器已含 xlsx/xls，无需改动
|
||||
- `import-service.ts`：`convertContentWithAI` 已存在，无需改动
|
||||
- 其他 converter：不受影响
|
||||
@@ -0,0 +1,1230 @@
|
||||
# 自定义规则优化设计（语言预过滤 + 导入去重）
|
||||
|
||||
> 适用项目：vscode-code-reviewer（净码特工 · Code Purifier）
|
||||
> 设计日期：2026-07-23
|
||||
> 参考文档：`docs/superpowers/specs/2026-07-10-code-reviewer-design.md` §5.3
|
||||
> 关联日志：`_AI_USAGE_LOG.md` 2026-07-17 / 2026-07-21 自定义规则演进记录
|
||||
> 源码基准：`src/`（第二个上传包，含完整源码）
|
||||
|
||||
> **⚠ 现状澄清（编码前必读）**
|
||||
>
|
||||
> 设计文档 §12 描述的 config.yaml 两级过滤机制（文件级 `enabled` 列表 + 规则级 `rules.<id>.enabled` 覆盖）**已废弃**，不再使用。
|
||||
>
|
||||
> 当前自定义规则采用**全启用模式**：
|
||||
> - `loadActiveRules(workspaceRoot)` 直接扫描 `.code-review/rules/*.yaml`，加载其中的**全部规则**，不做任何启用/禁用过滤。
|
||||
> - 规则文件**存在即生效**，删除整个 `.yaml` 文件即禁用该文件内所有规则。
|
||||
> - `.code-review/config.yaml` 即便仍存在于工程中，也不再被 `loadActiveRules` 读取（属历史遗留文件，编码时忽略）。
|
||||
>
|
||||
> 本设计分两部分：
|
||||
> - **Part A（语言预过滤）**：在 `loadActiveRules` 之后新增按语言裁剪环节，`loadActiveRules` 本身不改动。
|
||||
> - **Part B（导入去重）**：在 Converter 的 AI 转换流程中新增重复检测，重复规则以注释形式写入 YAML。
|
||||
>
|
||||
> 两者修改的文件几乎不重叠（唯一交集是 converters 的 prompt），可合并为一次实施。
|
||||
|
||||
---
|
||||
|
||||
# Part A：语言预过滤与字段容错
|
||||
|
||||
## A1. 背景与目标
|
||||
|
||||
### A1.1 现状问题
|
||||
|
||||
当前 `commands.ts` 第 41-43 行直接将 `loadActiveRules` 返回的全部规则传给 `runAIReview`：
|
||||
|
||||
```typescript
|
||||
const customRules = loadActiveRules(workspaceRoot);
|
||||
const aiResult = await runAIReview(context, code, staticResult.diagnostics, customRules);
|
||||
```
|
||||
|
||||
无论审查什么语言，全部规则都注入 AI 引擎请求 A（自定义规则评估）的 prompt。导致两个问题：
|
||||
|
||||
1. **浪费 token 且可能误导 AI**：审查 Java 文件时，只对 JS 生效的 `no-console-log` 也被塞进 prompt，既消耗 token，又可能让 AI 对 Java 代码套用 JS 规则。
|
||||
2. **无规则语言仍发请求 A**：`engine.ts` 第 141-148 行已有 `customRules.length > 0 ? provider.chat(...) : Promise.resolve('{}')` 的空规则处理，但预过滤前 customRules 永远不为空（只要有规则文件），所以 CSS/SQL 文件仍会触发请求 A 的 API 调用。
|
||||
|
||||
### A1.2 引出的依赖风险
|
||||
|
||||
预过滤的可靠性完全建立在规则 `languages` 字段准确这一前提上。而该字段由 AI 导入转换（`rules/converters/*`）生成，质量不可控。若 AI 错误标注 `languages`，预过滤会**主动制造漏报**（该触发的规则被误剔除），比不做预过滤更糟。
|
||||
|
||||
### A1.3 设计目标
|
||||
|
||||
- 在注入 prompt 前按文档语言裁剪无关规则，节省 token。
|
||||
- 无相关规则时，传入空数组触发 `engine.ts` 已有的 `Promise.resolve('{}')` 路径，省一整次 API 调用。
|
||||
- **核心容错原则**：`languages` 字段准就省 token，字段不准就退化为现状（全注入），**只让情况变好，不让情况变坏**。
|
||||
- 导入端（Part B）与过滤端双重加固，引导 AI 在不确定时留空而非猜测。
|
||||
|
||||
### A1.4 非目标
|
||||
|
||||
- 规则的确定性兜底（正则/AST 快通道）——另立设计。
|
||||
- 规则命中率统计反馈。
|
||||
- 规则 id 去重告警。
|
||||
|
||||
---
|
||||
|
||||
## A2. 可靠性传递链与风险分析
|
||||
|
||||
### A2.1 传递链
|
||||
|
||||
```
|
||||
源文件（md/txt/excel）质量
|
||||
↓
|
||||
AI 转换质量（Converter）
|
||||
↓
|
||||
languages 字段准确性 ← 预过滤的前提
|
||||
↓
|
||||
预过滤裁剪正确性
|
||||
↓
|
||||
是否漏报 / 误报
|
||||
```
|
||||
|
||||
### A2.2 languages 字段三种状态及后果
|
||||
|
||||
| 状态 | 来源 | 对预过滤的影响 | 危险等级 |
|
||||
|------|------|--------------|---------|
|
||||
| 缺失/空 | AI 未能判断，或源文件无语言线索 | 全语言生效，规则保留注入 | **低**（退化为现状，不漏报） |
|
||||
| 错误标注 | AI 猜错（如把通用规则标成仅 java） | 规则被误剔除，该触发的没触发 | **高**（主动制造漏报） |
|
||||
| 正确标注 | AI 准确识别语言线索 | 预过滤生效，理想状态 | 无风险 |
|
||||
|
||||
**关键结论**：缺失是安全的（退化为现状），错误标注是危险的（比现状更差）。所有设计应引导行为朝"留空"方向倾斜。
|
||||
|
||||
### A2.3 AI 导入转换的能力边界
|
||||
|
||||
| 规则描述特征 | 例子 | AI 能否正确推断 languages | 风险 |
|
||||
|-------------|------|-------------------------|------|
|
||||
| 含明确语言关键词 | "Java 类名用 PascalCase" | 能 | 低 |
|
||||
| 含语言线索但不唯一 | "变量名用驼峰" | 难（驼峰 JS/Java 都有） | 中 |
|
||||
| 纯通用语义 | "禁止硬编码密码" | 不能确定 | 高 |
|
||||
| 完全无语言信息 | "函数不超过 50 行" | 不能 | 高 |
|
||||
|
||||
---
|
||||
|
||||
## A3. 整体设计
|
||||
|
||||
### A3.1 容错原则
|
||||
|
||||
> **软过滤而非硬过滤**：对 `languages` 非空的规则才裁剪，`languages` 为空的规则始终保留。这样即使 AI 乱标，最坏情况是"留空规则过多导致预过滤不生效"（退化为现状），而不会误剔除任何规则。
|
||||
|
||||
### A3.2 数据流
|
||||
|
||||
```
|
||||
loadActiveRules(workspaceRoot) ← 返回全部激活规则（不变）
|
||||
↓
|
||||
filterForDocument(rules, document) ← 新增：按语言裁剪（软过滤）
|
||||
↓
|
||||
runAIReview(context, code, diag, relevantRules)
|
||||
↓
|
||||
engine.ts 内部：customRules.length === 0 ?
|
||||
├─ 是 → Promise.resolve('{}') ← 已有逻辑，不发 API 调用
|
||||
└─ 否 → provider.chat(...) ← 正常发请求 A
|
||||
```
|
||||
|
||||
> **重要**：`engine.ts` 不需要改动。现有第 141-148 行已正确处理空规则数组。预过滤只需在 `commands.ts` 调用 `runAIReview` 前插入过滤步骤。
|
||||
|
||||
### A3.3 双重加固
|
||||
|
||||
- **导入端（Part B）**：Converter prompt 约束 + 导入后预览确认 + 可选 `excludeLanguages` 黑名单。
|
||||
- **过滤端（Part A）**：软过滤 + 语言别名映射 + JSP 并集 + 运行时反馈。
|
||||
|
||||
---
|
||||
|
||||
## A4. 详细设计
|
||||
|
||||
### A4.1 数据结构变更
|
||||
|
||||
在 `src/types.ts` 的 `CustomRule` 接口新增 `excludeLanguages` 字段：
|
||||
|
||||
```typescript
|
||||
// src/types.ts
|
||||
export interface CustomRule {
|
||||
id: string; // 不含 custom: 前缀，运行时自动拼接
|
||||
severity: Severity; // 'error' | 'warning' | 'info'
|
||||
description: string; // AI 评估依据（自然语言）
|
||||
message: string; // 触发时显示
|
||||
languages?: string[]; // 白名单：适用语言，空/缺省=全语言
|
||||
excludeLanguages?: string[]; // 黑名单（新增）：明确排除的语言
|
||||
}
|
||||
```
|
||||
|
||||
**字段语义**：
|
||||
|
||||
| languages | excludeLanguages | 生效范围 |
|
||||
|-----------|------------------|---------|
|
||||
| 空/缺省 | 空/缺省 | 全语言生效 |
|
||||
| `[java, javascript]` | 空 | 仅 java、javascript |
|
||||
| 空/缺省 | `[css, sql]` | 除 css、sql 外全部 |
|
||||
| `[java]` | `[css]` | 仅 java（先按白名单保留，再按黑名单剔除） |
|
||||
|
||||
> 两者同时存在时，先按白名单保留，再按黑名单剔除。实践中建议二选一，导入时由 AI 判断哪种更明确。
|
||||
|
||||
### A4.2 YAML schema 扩展
|
||||
|
||||
```yaml
|
||||
# 白名单（适用于明确单一/少数语言的规则）
|
||||
- id: no-console-log
|
||||
severity: warning
|
||||
description: 生产代码不应保留 console.log 调试语句
|
||||
message: 请使用日志框架替代 console.log
|
||||
languages: [javascript, typescript]
|
||||
|
||||
# 黑名单（新增字段，适用于通用规则排除明确不适用语言）
|
||||
- id: no-hardcoded-secret
|
||||
severity: error
|
||||
description: 禁止在代码中硬编码 API Key、密码等敏感信息
|
||||
message: 检测到硬编码密钥，请使用环境变量或密钥管理工具
|
||||
excludeLanguages: [css, sql] # 这条规则除 CSS/SQL 外都适用
|
||||
```
|
||||
|
||||
### A4.3 过滤模块设计
|
||||
|
||||
#### A4.3.1 新建文件
|
||||
|
||||
`src/rules/rule-filter.ts`
|
||||
|
||||
#### A4.3.2 语言别名映射
|
||||
|
||||
```typescript
|
||||
// src/rules/rule-filter.ts
|
||||
import * as vscode from 'vscode';
|
||||
import type { CustomRule } from '../types';
|
||||
|
||||
const LANGUAGE_ALIASES: Record<string, string[]> = {
|
||||
typescriptreact: ['typescript', 'typescriptreact', 'tsx'],
|
||||
javascriptreact: ['javascript', 'javascriptreact', 'jsx'],
|
||||
};
|
||||
|
||||
const LANGUAGE_GROUPS: Record<string, string[]> = {
|
||||
sql: ['sql', 'plsql'],
|
||||
plsql: ['sql', 'plsql'],
|
||||
};
|
||||
|
||||
function expandLanguageId(languageId: string): string[] {
|
||||
const aliases = LANGUAGE_ALIASES[languageId] ?? [languageId];
|
||||
const groups = LANGUAGE_GROUPS[languageId] ?? [];
|
||||
return [...new Set([...aliases, ...groups, languageId])];
|
||||
}
|
||||
```
|
||||
|
||||
#### A4.3.3 JSP 子语言集合
|
||||
|
||||
```typescript
|
||||
const JSP_SUB_LANGUAGES = ['java', 'javascript', 'typescript', 'css', 'jsp', 'html'];
|
||||
const JSP_EXTENSIONS = ['.jsp', '.jspx'];
|
||||
|
||||
function isJspFile(document: vscode.TextDocument): boolean {
|
||||
return JSP_EXTENSIONS.some(ext => document.fileName.toLowerCase().endsWith(ext));
|
||||
}
|
||||
```
|
||||
|
||||
#### A4.3.4 单条规则匹配函数
|
||||
|
||||
```typescript
|
||||
function matchesLanguage(rule: CustomRule, expandedLangs: string[]): boolean {
|
||||
// 1. 黑名单优先：规则明确排除当前语言 → 剔除
|
||||
if (rule.excludeLanguages && rule.excludeLanguages.length > 0) {
|
||||
if (rule.excludeLanguages.some(l => expandedLangs.includes(l))) {
|
||||
return false;
|
||||
}
|
||||
}
|
||||
// 2. 白名单为空 → 全语言保留（软过滤的安全默认）
|
||||
if (!rule.languages || rule.languages.length === 0) {
|
||||
return true;
|
||||
}
|
||||
// 3. 白名单非空 → 检查是否包含当前语言
|
||||
return rule.languages.some(l => expandedLangs.includes(l));
|
||||
}
|
||||
```
|
||||
|
||||
#### A4.3.5 主过滤函数
|
||||
|
||||
```typescript
|
||||
export function filterForDocument(
|
||||
rules: CustomRule[],
|
||||
document: vscode.TextDocument
|
||||
): CustomRule[] {
|
||||
const langId = document.languageId;
|
||||
if (langId === 'html' && isJspFile(document)) {
|
||||
return rules.filter(rule => matchesLanguage(rule, JSP_SUB_LANGUAGES));
|
||||
}
|
||||
const expandedLangs = expandLanguageId(langId);
|
||||
return rules.filter(rule => matchesLanguage(rule, expandedLangs));
|
||||
}
|
||||
```
|
||||
|
||||
#### A4.3.6 导出汇总（用于运行时反馈）
|
||||
|
||||
```typescript
|
||||
export interface FilterResult {
|
||||
relevant: CustomRule[];
|
||||
filteredOut: CustomRule[];
|
||||
skippedRequestA: boolean;
|
||||
}
|
||||
|
||||
export function filterAndSummarize(
|
||||
rules: CustomRule[],
|
||||
document: vscode.TextDocument
|
||||
): FilterResult {
|
||||
const relevant = filterForDocument(rules, document);
|
||||
const filteredOut = rules.filter(r => !relevant.includes(r));
|
||||
return {
|
||||
relevant,
|
||||
filteredOut,
|
||||
skippedRequestA: relevant.length === 0,
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
### A4.4 调用处接入
|
||||
|
||||
在 `src/activation/commands.ts` 的 `review` 命令中插入过滤。当前第 41-43 行：
|
||||
|
||||
```typescript
|
||||
// 现状
|
||||
const customRules = loadActiveRules(workspaceRoot);
|
||||
const code = document.getText();
|
||||
const aiResult = await runAIReview(context, code, staticResult.diagnostics, customRules);
|
||||
```
|
||||
|
||||
改为：
|
||||
|
||||
```typescript
|
||||
// 改造后
|
||||
const allRules = loadActiveRules(workspaceRoot);
|
||||
const filterResult = filterAndSummarize(allRules, document);
|
||||
const code = document.getText();
|
||||
const aiResult = await runAIReview(context, code, staticResult.diagnostics, filterResult.relevant);
|
||||
```
|
||||
|
||||
> `runAIReview` 签名不变（`context, code, staticDiagnostics, customRules`）。传入空数组时 `engine.ts` 已有的 `Promise.resolve('{}')` 逻辑会跳过请求 A 的 API 调用。
|
||||
|
||||
### A4.5 yaml-parser 适配
|
||||
|
||||
`src/rules/yaml-parser.ts` 第 5-11 行的 `RuleYamlItem` 接口和第 72-78 行的解析逻辑需新增 `excludeLanguages` 字段。
|
||||
|
||||
> **注意**：`loadActiveRules` 的全启用加载逻辑（直接扫描 `rules/*.yaml` 返回全部规则）**保持不变**，不要引入任何 config.yaml 过滤。
|
||||
|
||||
```typescript
|
||||
// src/rules/yaml-parser.ts
|
||||
|
||||
interface RuleYamlItem {
|
||||
id: string;
|
||||
severity: string;
|
||||
description: string;
|
||||
message: string;
|
||||
languages?: string[];
|
||||
excludeLanguages?: string[]; // 新增
|
||||
}
|
||||
|
||||
// loadActiveRules 内部 push 时增加字段
|
||||
allRules.push({
|
||||
id: item.id,
|
||||
severity,
|
||||
description: item.description,
|
||||
message: item.message,
|
||||
languages: item.languages,
|
||||
excludeLanguages: item.excludeLanguages, // 新增
|
||||
});
|
||||
```
|
||||
|
||||
> 现有 `parseYamlSimple` 已能解析 `[a, b]` 格式的数组（第 28-31 行、第 43-46 行），`excludeLanguages` 的解析无需额外代码。
|
||||
|
||||
### A4.6 运行时反馈
|
||||
|
||||
#### A4.6.1 MergedReport 扩展
|
||||
|
||||
当前 `src/merger/merger.ts` 的 `MergedReport` 接口（第 5-21 行）新增字段：
|
||||
|
||||
```typescript
|
||||
export interface MergedReport {
|
||||
// ... 现有字段不变 ...
|
||||
linterDiagnostics: LinterDiagnostic[];
|
||||
customRuleDiagnostics: LinterDiagnostic[];
|
||||
// ...
|
||||
|
||||
// 新增：规则过滤信息
|
||||
customRuleFilterInfo?: {
|
||||
totalActive: number;
|
||||
injected: number;
|
||||
filteredOut: number;
|
||||
skippedRequestA: boolean;
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
#### A4.6.2 MergeInput 扩展
|
||||
|
||||
```typescript
|
||||
interface MergeInput {
|
||||
// ... 现有字段不变 ...
|
||||
customRuleFilterInfo?: {
|
||||
totalActive: number;
|
||||
injected: number;
|
||||
filteredOut: number;
|
||||
skippedRequestA: boolean;
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
#### A4.6.3 commands.ts 传入
|
||||
|
||||
```typescript
|
||||
currentReport = mergeResults({
|
||||
// ... 现有参数 ...
|
||||
customRuleFilterInfo: {
|
||||
totalActive: allRules.length,
|
||||
injected: filterResult.relevant.length,
|
||||
filteredOut: filterResult.filteredOut.length,
|
||||
skippedRequestA: filterResult.skippedRequestA,
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
#### A4.6.4 面板展示
|
||||
|
||||
在 `src/panel/webview.ts` 自定义规则 Tab 的 header 中追加：
|
||||
|
||||
```
|
||||
自定义规则 · 2 个问题（注入 4/7 条规则）
|
||||
```
|
||||
|
||||
若 `skippedRequestA` 为 true，显示提示：
|
||||
|
||||
```
|
||||
当前文件语言无匹配的自定义规则，已跳过规则评估
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## A5. 边界情况
|
||||
|
||||
| 场景 | 处理方式 |
|
||||
|------|---------|
|
||||
| `languages` 与 `excludeLanguages` 同时非空 | 先按白名单保留，再按黑名单剔除 |
|
||||
| 规则 `languages` 含拼写错误 | 不匹配任何语言，规则被剔除。依赖导入预览纠正 |
|
||||
| `.tsx` 文件 | `LANGUAGE_ALIASES` 映射到 `typescript`，规则 `languages: [typescript]` 命中 |
|
||||
| `.plsql` 文件 | `LANGUAGE_GROUPS` 与 `sql` 同组，规则 `languages: [sql]` 命中 |
|
||||
| JSP 文件（html ID + .jsp 扩展名） | 取 `JSP_SUB_LANGUAGES` 并集，保留 Java/JS/CSS 相关规则 |
|
||||
| 普通 HTML 文件（html ID，非 .jsp） | 走正常 `expandLanguageId('html')`，无 JSP 扩展名检测 |
|
||||
| 全部规则被过滤（如 CSS 文件） | `skippedRequestA = true`，engine.ts 走 `Promise.resolve('{}')` |
|
||||
| `loadActiveRules` 返回空 | 同上 |
|
||||
| 规则 `languages` 为空数组 `[]` | 视同缺失，全语言保留 |
|
||||
| 工程中残留 `config.yaml` | **忽略**，不读取 |
|
||||
|
||||
---
|
||||
|
||||
# Part B：导入去重与注释化
|
||||
|
||||
## B1. 背景与目标
|
||||
|
||||
### B1.1 问题
|
||||
|
||||
当前导入流程（`setupView.ts` 第 181-210 行 `addRule` 方法）只做三件事：选文件 → 查重名 → 调用 `importService.convert(srcPath, yamlPath, context)` 转换写盘。**没有任何与静态分析规则的比对**。
|
||||
|
||||
用户导入的规则可能与 linter 内置规则检测同样的问题（如"禁止未使用变量"重复 ESLint `no-unused-vars`），导致 AI 请求 A 和静态分析重复报告同一问题。
|
||||
|
||||
### B1.2 设计目标
|
||||
|
||||
- 导入时自动检测自定义规则是否与 linter 内置规则重复。
|
||||
- 重复规则以注释形式写入 YAML（`yaml-parser` 已跳过 `#` 开头的行），不进入激活规则集。
|
||||
- 非重复规则正常写入。
|
||||
- 用户可在预览面板一键恢复被注释的规则。
|
||||
- 导入后用户确认才写盘，防止 AI 误判静默禁用规则。
|
||||
|
||||
### B1.3 已确认决策
|
||||
|
||||
| 决策项 | 选择 | 理由 |
|
||||
|--------|------|------|
|
||||
| 检测范围 | 只对 md/txt/excel（AI 转换路径） | YamlConverter 直接复制，用户手写 YAML 说明知道在做什么 |
|
||||
| 确认流程 | 强制预览确认 | 误判会静默禁用规则，风险高 |
|
||||
| 判定结果分档 | 三档：exact / overlap / none | 二元判定丢失"部分重叠"信息，overlap 交用户决定 |
|
||||
| 规则清单来源 | 离线提炼，手工定稿打包 | 四个 linter 内置且版本固定，规则集是确定常量，无需运行时提取 |
|
||||
| 全部重复 | 仍写盘（全是注释） | 预览提示"全部规则与静态分析重复"，用户可取消注释恢复 |
|
||||
|
||||
---
|
||||
|
||||
## B2. 整体设计
|
||||
|
||||
### B2.1 数据流
|
||||
|
||||
```
|
||||
源文件（md/txt/xlsx）
|
||||
↓
|
||||
Converter AI 转换（prompt 含语言约束 + 规则清单 + 重复检测）
|
||||
↓
|
||||
中间 YAML（含 duplicateOf + duplicateLevel + duplicateReason）
|
||||
↓
|
||||
后处理：解析规则列表，按 exact/overlap/none 分组
|
||||
↓
|
||||
预览 Webview 面板（三分区展示，用户确认，可翻转规则状态）
|
||||
↓
|
||||
注释化（保留 duplicateLevel 信息）+ 写盘
|
||||
```
|
||||
|
||||
### B2.2 静态规则清单（离线提炼）
|
||||
|
||||
四个 linter 是插件内置的，版本固定，规则集是确定常量。**一次性离线提炼**成 `static-rules.json`，打包进插件，运行时直接 import。不需要构建脚本、不需要运行时提取、不需要构建环境装任何工具。
|
||||
|
||||
#### 规则来源与提炼方法
|
||||
|
||||
| Linter | 版本（源码确定） | 规则集权威来源 | 预计规则数 |
|
||||
|--------|---------------|-------------|----------|
|
||||
| ESLint | `@eslint/js` recommended | `npx eslint --print-config` 或官方规则页 | ~50 条 |
|
||||
| ts-eslint | `typescript-eslint` recommended | 官方 rules 页 recommended 标记 | ~40 条 |
|
||||
| Stylelint | 源码 `DEFAULT_CONFIG` 硬编码 | `stylelint.ts` 第 17-32 行直接读 | 13 条 |
|
||||
| PMD | 7.26.0，6 个 category | `pmd-java-ruleset.xml` + `java -jar pmd --rules` | ~100+ 条 |
|
||||
| sqlfluff | CLI 默认 | `sqlfluff rules --dialect ansi` | ~60 条 |
|
||||
|
||||
提炼时在装有对应版本工具的环境中跑一次上述命令，将输出整理成 `id + description` 格式，人工验收后定稿。
|
||||
|
||||
#### 产物文件
|
||||
|
||||
`src/rules/static-rules.json`：
|
||||
|
||||
```json
|
||||
{
|
||||
"version": "1.0.0",
|
||||
"linterVersion": {
|
||||
"eslint": "9.x (recommended)",
|
||||
"ts-eslint": "8.x (recommended)",
|
||||
"stylelint": "16.x (内置13条)",
|
||||
"pmd": "7.26.0 (6 categories)",
|
||||
"sqlfluff": "3.x (default)"
|
||||
},
|
||||
"rules": {
|
||||
"eslint": [
|
||||
{ "id": "eslint:no-unused-vars", "description": "未使用的变量" },
|
||||
{ "id": "eslint:no-console", "description": "console 语句" },
|
||||
{ "id": "eslint:no-debugger", "description": "debugger 语句" },
|
||||
{ "id": "eslint:eqeqeq", "description": "要求严格相等 ===" }
|
||||
],
|
||||
"ts-eslint": [
|
||||
{ "id": "ts-eslint:no-explicit-any", "description": "禁止显式 any 类型" },
|
||||
{ "id": "ts-eslint:no-non-null-assertion", "description": "禁止非空断言 !" }
|
||||
],
|
||||
"stylelint": [
|
||||
{ "id": "stylelint:block-no-empty", "description": "空规则块" },
|
||||
{ "id": "stylelint:declaration-block-no-duplicate-properties", "description": "重复属性" }
|
||||
],
|
||||
"pmd": [
|
||||
{ "id": "pmd:EmptyCatchBlock", "description": "空 catch 块" },
|
||||
{ "id": "pmd:AvoidDuplicateLiterals", "description": "重复字符串字面量" },
|
||||
{ "id": "pmd:ExcessiveMethodLength", "description": "过长方法" }
|
||||
],
|
||||
"sql-lint": [
|
||||
{ "id": "sql-lint:L001", "description": "不必要的空格" },
|
||||
{ "id": "sql-lint:L010", "description": "关键字大小写" }
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 维护策略
|
||||
|
||||
linter 升级时重新提炼。文件中的 `linterVersion` 字段记录对应版本，便于追溯。因为 linter 版本随插件发布绑定，不会在用户侧变化，所以不需要运行时校验。
|
||||
|
||||
#### 运行时加载
|
||||
|
||||
```typescript
|
||||
// src/rules/converters/prompt-builder.ts（新建）
|
||||
import staticRules from '../static-rules.json';
|
||||
|
||||
export function buildDedupPromptSection(): string {
|
||||
const lines: string[] = ['## 静态分析规则清单（用于重复检测）\n'];
|
||||
|
||||
for (const [linter, rules] of Object.entries(staticRules.rules)) {
|
||||
lines.push(`### ${linter} (${rules.length} 条)`);
|
||||
for (const rule of rules) {
|
||||
lines.push(`- ${rule.id}: ${rule.description}`);
|
||||
}
|
||||
lines.push('');
|
||||
}
|
||||
|
||||
lines.push('判定时请精确匹配上述规则 ID，而非模糊匹配分类。');
|
||||
|
||||
return lines.join('\n');
|
||||
}
|
||||
```
|
||||
|
||||
### B2.3 三档判定机制
|
||||
|
||||
"重复"不是二元的，有程度差异。AI 判定结果分三档，每档处理方式不同：
|
||||
|
||||
| 等级 | 含义 | 例子 | 默认处理 |
|
||||
|------|------|------|---------|
|
||||
| **exact** | 检测目标 + 触发条件完全一致 | "禁止 console.log" ↔ `eslint/no-console` | 注释化 |
|
||||
| **overlap** | 检测目标相同但触发条件有差异 | "禁止 console 输出，需用 logger 替代" ↔ `no-console`（自定义规则有额外要求） | **预览标注，用户决定** |
|
||||
| **none** | 检测目标不同 | "禁止 console.log 输出敏感信息" ↔ `no-console`（检测目标不同） | 保留 |
|
||||
|
||||
AI 输出三档字段：
|
||||
|
||||
```yaml
|
||||
- id: no-console-log
|
||||
description: 禁止 console.log
|
||||
duplicateOf: eslint/no-console
|
||||
duplicateLevel: exact
|
||||
duplicateReason: 检测目标完全一致，均为禁止 console 语句
|
||||
|
||||
- id: no-console-with-context
|
||||
description: 禁止 console 输出，需用 logger 替代并记录上下文
|
||||
duplicateOf: eslint/no-console
|
||||
duplicateLevel: overlap
|
||||
duplicateReason: 检测目标相同，但本规则额外要求用 logger 替代并记录上下文
|
||||
|
||||
- id: no-sensitive-console
|
||||
description: 禁止在 console.log 中输出敏感信息
|
||||
duplicateLevel: none
|
||||
```
|
||||
|
||||
后处理默认行为：
|
||||
|
||||
```typescript
|
||||
function getDefaultKeep(rule: ImportableRule): boolean {
|
||||
if (rule.duplicateLevel === 'exact') return false; // 确定重复 → 注释
|
||||
if (rule.duplicateLevel === 'overlap') return true; // 部分重叠 → 默认保留，预览标注
|
||||
return true; // 不重复 → 保留
|
||||
}
|
||||
```
|
||||
|
||||
**判定标准（写进 prompt）**：
|
||||
|
||||
> 只有当自定义规则的检测目标、触发条件与某个 linter 内置规则**高度一致**（会报出同样的问题行）时，标记 `exact`。检测目标相同但自定义规则有额外要求或更窄范围时，标记 `overlap`。检测目标不同时，标记 `none`。
|
||||
>
|
||||
> 仅"话题相似"不算重复。例如：
|
||||
> - "未使用变量应删除" → exact（重复 eslint/no-unused-vars）
|
||||
> - "未使用变量需要记录到日志" → none（检测目标不同，后者有额外动作）
|
||||
> - "禁止 console.log" → exact（重复 eslint/no-console）
|
||||
> - "禁止在 console.log 中输出敏感信息" → none（检测目标不同）
|
||||
|
||||
### B2.4 注释化机制
|
||||
|
||||
`yaml-parser.ts` 第 19 行已跳过所有 `#` 开头的行：
|
||||
|
||||
```typescript
|
||||
if (!trimmed || trimmed.startsWith('#')) { continue; }
|
||||
```
|
||||
|
||||
注释化的规则天然不会被加载，**无需改 parser**。后处理对被注释的规则整块加 `#` 前缀，注释头保留 `duplicateLevel` 和 `duplicateReason`。
|
||||
|
||||
最终文件示例：
|
||||
|
||||
```yaml
|
||||
# [DUPLICATE: exact] 重复 eslint/no-console（检测目标完全一致）
|
||||
# 如需启用，删除以下每行开头的 # 即可
|
||||
# - id: no-console-log
|
||||
# severity: warning
|
||||
# description: 禁止 console.log
|
||||
# message: 请使用日志框架替代 console.log
|
||||
# languages: [javascript, typescript]
|
||||
|
||||
# [DUPLICATE: overlap] 与 eslint/no-console 部分重叠
|
||||
# 重叠原因：检测目标相同，但本规则额外要求用 logger 替代并记录上下文
|
||||
# - id: no-console-with-context
|
||||
# severity: warning
|
||||
# description: 禁止 console 输出，需用 logger 替代并记录上下文
|
||||
# message: 请使用 logger 替代 console 并记录上下文
|
||||
# languages: [javascript, typescript]
|
||||
- id: no-hardcoded-secret
|
||||
severity: error
|
||||
description: 禁止硬编码 API Key
|
||||
message: 检测到硬编码密钥
|
||||
languages: [java, javascript]
|
||||
```
|
||||
|
||||
用户想恢复某条规则，手动删掉 `#` 前缀即可——parser 会重新加载它。`duplicateLevel` 和 `duplicateReason` 保留在注释头，方便追溯。
|
||||
|
||||
---
|
||||
|
||||
## B3. 详细设计
|
||||
|
||||
### B3.1 数据结构
|
||||
|
||||
`duplicateOf` 是导入中间态字段，不属于 `CustomRule` 运行时接口。定义独立的导入中间类型：
|
||||
|
||||
```typescript
|
||||
// src/rules/import-types.ts（新建）
|
||||
|
||||
import type { CustomRule } from '../types';
|
||||
|
||||
/**
|
||||
* 导入中间态规则：AI 转换输出、后处理、预览使用。
|
||||
* 写盘后 duplicateOf 不出现在最终 YAML 规则体中（重复规则整块被注释）。
|
||||
*/
|
||||
export interface ImportableRule extends CustomRule {
|
||||
duplicateOf?: string; // 格式 "linter/ruleId"，如 "eslint/no-unused-vars"
|
||||
duplicateLevel?: 'exact' | 'overlap' | 'none'; // 重复程度
|
||||
duplicateReason?: string; // AI 给出的重叠原因（overlap 档必填）
|
||||
}
|
||||
|
||||
export interface ConversionResult {
|
||||
rules: ImportableRule[];
|
||||
yamlContent: string; // AI 输出的原始 YAML 文本（含 duplicate* 字段）
|
||||
sourceFileName: string;
|
||||
exactCount: number; // duplicateLevel=exact 的规则数
|
||||
overlapCount: number; // duplicateLevel=overlap 的规则数
|
||||
}
|
||||
|
||||
export interface PreviewDecision {
|
||||
/** 用户最终确认的规则状态：ruleId → 是否保留（true=激活，false=注释） */
|
||||
keepRule: Record<string, boolean>;
|
||||
confirmed: boolean;
|
||||
}
|
||||
```
|
||||
|
||||
### B3.2 Converter prompt（语言约束 + 重复检测合并）
|
||||
|
||||
在 `md-converter.ts`、`txt-converter.ts`、`excel-converter.ts` 的 AI 转换 prompt 中追加以下内容。**语言约束（Part A）和重复检测（Part B）在同一次 prompt 修改中一起加入**：
|
||||
|
||||
```text
|
||||
## 语言字段规则（严格遵守）
|
||||
|
||||
对于每条规则的 languages 字段，按以下优先级判断：
|
||||
|
||||
1. 规则描述中含明确语言关键词（如 "Java"、"JavaScript"、"TypeScript"、"CSS"）：
|
||||
→ 使用 languages 白名单，列出明确提到的语言。
|
||||
|
||||
2. 规则适用于大多数语言，只有少数明确不适用：
|
||||
→ 使用 excludeLanguages 黑名单，列出明确不适用者。
|
||||
|
||||
3. 无法确定适用语言，或规则为通用规范（如命名、安全、复杂度）：
|
||||
→ languages 与 excludeLanguages 均留空（表示全语言生效）。
|
||||
→ 严禁猜测。留空比猜测错误更安全。
|
||||
|
||||
输出 YAML 中，languages 和 excludeLanguages 不可同时非空。
|
||||
语言名使用小写：java, javascript, typescript, css, sql, plsql, jsp。
|
||||
|
||||
## 静态分析重复检测
|
||||
|
||||
本插件的静态分析已覆盖以下 linter 内置规则。请精确匹配规则 ID，而非模糊匹配分类。
|
||||
|
||||
${buildDedupPromptSection()}
|
||||
|
||||
对于每条规则，判断其检测目标与触发条件是否与上述某个 linter 规则重复，并标注重复程度：
|
||||
|
||||
- **exact**：检测目标与触发条件完全一致（会报出同样的问题行）→ 输出 duplicateOf + duplicateLevel: exact
|
||||
- **overlap**：检测目标相同，但本规则有额外要求或更窄范围 → 输出 duplicateOf + duplicateLevel: overlap + duplicateReason（说明差异）
|
||||
- **none**：检测目标不同 → 输出 duplicateLevel: none（不输出 duplicateOf）
|
||||
|
||||
仅"话题相似"不算重复。例如：
|
||||
- "未使用变量应删除" → exact（重复 eslint/no-unused-vars）
|
||||
- "未使用变量需要记录到日志" → none（检测目标不同，后者有额外动作）
|
||||
- "禁止 console.log" → exact（重复 eslint/no-console）
|
||||
- "禁止在 console.log 中输出敏感信息" → none（检测目标不同）
|
||||
```
|
||||
|
||||
### B3.3 ImportService 改造
|
||||
|
||||
当前 `importService.convert(srcPath, yamlPath, context)` 直接转换写盘。拆分为两步：先转换返回结果，再由调用方预览确认后写盘。
|
||||
|
||||
```typescript
|
||||
// src/rules/import-service.ts（改造）
|
||||
|
||||
export class ImportService {
|
||||
private converters: Map<string, RuleConverter> = new Map();
|
||||
|
||||
registerConverter(converter: RuleConverter): void {
|
||||
for (const ext of converter.supportedExtensions) {
|
||||
this.converters.set(ext, converter);
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* 转换源文件为规则列表 + YAML 文本（不写盘）。
|
||||
* YamlConverter 直接复制源文件内容。
|
||||
* Md/Txt/Excel Converter 调用 AI 转换。
|
||||
*/
|
||||
async convert(
|
||||
srcPath: string,
|
||||
context: vscode.ExtensionContext,
|
||||
): Promise<ConversionResult> {
|
||||
const ext = path.extname(srcPath).slice(1).toLowerCase();
|
||||
const converter = this.converters.get(ext);
|
||||
if (!converter) {
|
||||
throw new Error(`不支持的文件格式: .${ext}`);
|
||||
}
|
||||
|
||||
const yamlContent = await converter.convert(srcPath, context);
|
||||
const rules = parseImportableYaml(yamlContent);
|
||||
const exactCount = rules.filter(r => r.duplicateLevel === 'exact').length;
|
||||
const overlapCount = rules.filter(r => r.duplicateLevel === 'overlap').length;
|
||||
|
||||
return {
|
||||
rules,
|
||||
yamlContent,
|
||||
sourceFileName: path.basename(srcPath),
|
||||
exactCount,
|
||||
overlapCount,
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* 根据用户预览决策，注释化重复规则后写盘。
|
||||
*/
|
||||
applyConversion(
|
||||
result: ConversionResult,
|
||||
decision: PreviewDecision,
|
||||
targetPath: string,
|
||||
): void {
|
||||
const finalYaml = buildFinalYaml(result.yamlContent, result.rules, decision);
|
||||
const dir = path.dirname(targetPath);
|
||||
if (!fs.existsSync(dir)) {
|
||||
fs.mkdirSync(dir, { recursive: true });
|
||||
}
|
||||
fs.writeFileSync(targetPath, finalYaml, 'utf-8');
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### B3.4 注释化后处理
|
||||
|
||||
对 AI 输出的 YAML 文本做行级操作，将用户标记为注释的规则整块加 `#` 前缀。
|
||||
|
||||
```typescript
|
||||
// src/rules/import-service.ts
|
||||
|
||||
/**
|
||||
* 根据用户决策构建最终 YAML 文本。
|
||||
* 默认行为：有 duplicateOf 的规则注释，无 duplicateOf 的规则保留。
|
||||
* 用户可在预览中翻转任意规则的状态。
|
||||
*/
|
||||
function buildFinalYaml(
|
||||
yamlContent: string,
|
||||
rules: ImportableRule[],
|
||||
decision: PreviewDecision,
|
||||
): string {
|
||||
// 默认：exact → 注释；overlap → 保留（预览标注）；none → 保留
|
||||
const defaultKeep = (rule: ImportableRule) => rule.duplicateLevel !== 'exact';
|
||||
// 用户决策覆盖默认
|
||||
const shouldKeep = (rule: ImportableRule) =>
|
||||
decision.keepRule[rule.id] ?? defaultKeep(rule);
|
||||
|
||||
const lines = yamlContent.split('\n');
|
||||
const output: string[] = [];
|
||||
let currentRuleId: string | null = null;
|
||||
let currentRuleKeep = true;
|
||||
let ruleLines: string[] = [];
|
||||
|
||||
function flushRule(): void {
|
||||
if (currentRuleId === null) {
|
||||
// 非规则行（空行、注释等），直接输出
|
||||
output.push(...ruleLines);
|
||||
} else if (currentRuleKeep) {
|
||||
// 保留规则：移除 duplicateOf 行，其余原样输出
|
||||
const filtered = ruleLines.filter(
|
||||
line => !line.trim().startsWith('duplicateOf:')
|
||||
);
|
||||
output.push(...filtered);
|
||||
} else {
|
||||
// 注释规则：加说明头（含 duplicateLevel + duplicateReason）+ 整块加 # 前缀
|
||||
const rule = rules.find(r => r.id === currentRuleId);
|
||||
const level = rule?.duplicateLevel ?? 'exact';
|
||||
const dupInfo = rule?.duplicateOf ?? 'unknown';
|
||||
const reason = rule?.duplicateReason ?? '';
|
||||
if (level === 'exact') {
|
||||
output.push(`# [DUPLICATE: exact] 重复 ${dupInfo}（检测目标完全一致）`);
|
||||
} else {
|
||||
output.push(`# [DUPLICATE: ${level}] 与 ${dupInfo} 部分重叠`);
|
||||
if (reason) { output.push(`# 重叠原因：${reason}`); }
|
||||
}
|
||||
output.push('# 如需启用，删除以下每行开头的 # 即可');
|
||||
for (const line of ruleLines) {
|
||||
output.push(line.trim() ? `# ${line}` : '#');
|
||||
}
|
||||
}
|
||||
ruleLines = [];
|
||||
}
|
||||
|
||||
for (const line of lines) {
|
||||
const ruleStart = line.match(/^-\s+id:\s*(.+)/);
|
||||
if (ruleStart) {
|
||||
flushRule();
|
||||
currentRuleId = ruleStart[1].trim();
|
||||
currentRuleKeep = shouldKeep({ id: currentRuleId } as ImportableRule);
|
||||
ruleLines = [line];
|
||||
} else if (currentRuleId) {
|
||||
ruleLines.push(line);
|
||||
} else {
|
||||
ruleLines.push(line);
|
||||
}
|
||||
}
|
||||
flushRule();
|
||||
|
||||
return output.join('\n');
|
||||
}
|
||||
```
|
||||
|
||||
### B3.5 YAML 解析（导入中间态）
|
||||
|
||||
复用 `yaml-parser.ts` 的 `parseYamlSimple` 逻辑，额外读取 `duplicateOf` 字段：
|
||||
|
||||
```typescript
|
||||
// src/rules/import-service.ts
|
||||
|
||||
function parseImportableYaml(content: string): ImportableRule[] {
|
||||
// 复用 parseYamlSimple 的解析逻辑（可导出或内联）
|
||||
const items = parseSimpleYaml(content);
|
||||
return items
|
||||
.filter(item => item.id && item.severity && item.description && item.message)
|
||||
.map(item => ({
|
||||
id: item.id,
|
||||
severity: item.severity,
|
||||
description: item.description,
|
||||
message: item.message,
|
||||
languages: item.languages,
|
||||
excludeLanguages: item.excludeLanguages,
|
||||
duplicateOf: item.duplicateOf, // 导入中间态字段
|
||||
}));
|
||||
}
|
||||
```
|
||||
|
||||
> `parseSimpleYaml` 已能解析 `key: value` 和 `key: [a, b]` 格式，`duplicateOf: eslint/no-unused-vars` 会被正确解析为字符串。
|
||||
|
||||
### B3.6 预览 Webview 面板
|
||||
|
||||
用 `vscode.window.createWebviewPanel` 创建临时面板，展示规则卡片列表，用户确认后才写盘。
|
||||
|
||||
```typescript
|
||||
// src/rules/import-preview.ts（新建）
|
||||
|
||||
import * as vscode from 'vscode';
|
||||
import type { ConversionResult, PreviewDecision } from './import-types';
|
||||
|
||||
export async function showImportPreview(
|
||||
result: ConversionResult,
|
||||
extensionUri: vscode.Uri,
|
||||
): Promise<PreviewDecision | null> {
|
||||
return new Promise((resolve) => {
|
||||
const panel = vscode.window.createWebviewPanel(
|
||||
'ruleImportPreview',
|
||||
'规则导入预览',
|
||||
vscode.ViewColumn.Active,
|
||||
{ enableScripts: true },
|
||||
);
|
||||
|
||||
const keepRule: Record<string, boolean> = {};
|
||||
for (const rule of result.rules) {
|
||||
// 默认：exact → 注释（false）；overlap/none → 保留（true）
|
||||
keepRule[rule.id] = rule.duplicateLevel !== 'exact';
|
||||
}
|
||||
|
||||
panel.webview.html = renderPreviewHtml(result, keepRule);
|
||||
|
||||
panel.webview.onDidReceiveMessage((msg) => {
|
||||
if (msg.type === 'toggleRule') {
|
||||
keepRule[msg.ruleId] = msg.keep;
|
||||
// 更新 UI 状态由前端处理
|
||||
} else if (msg.type === 'confirm') {
|
||||
resolve({ keepRule, confirmed: true });
|
||||
panel.dispose();
|
||||
} else if (msg.type === 'cancel') {
|
||||
resolve(null);
|
||||
panel.dispose();
|
||||
}
|
||||
});
|
||||
|
||||
panel.onDidDispose(() => resolve(null));
|
||||
});
|
||||
}
|
||||
```
|
||||
|
||||
#### 预览 HTML 结构
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────┐
|
||||
│ 规则导入预览 · 来源：team-conventions.md │
|
||||
│ 检测到 7 条规则 │
|
||||
│ · 2 条与静态分析完全重复（将注释） │
|
||||
│ · 2 条与静态分析部分重叠（请确认） │
|
||||
│ · 3 条无重复（将保留） │
|
||||
├─────────────────────────────────────────────────┤
|
||||
│ ⛔ 完全重复 (2 条) — 将以注释导入 │
|
||||
│ ┌─────────────────────────────────────────┐ │
|
||||
│ │ no-console-log warning │ │
|
||||
│ │ 重复：eslint/no-console │ │
|
||||
│ │ [恢复此规则] │ │
|
||||
│ └─────────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ ⚠️ 部分重叠 (2 条) — 默认保留，请确认 │
|
||||
│ ┌─────────────────────────────────────────┐ │
|
||||
│ │ no-console-with-context warning │ │
|
||||
│ │ 与 eslint/no-console 部分重叠 │ │
|
||||
│ │ 重叠原因：检测目标相同，但本规则额外要求 │ │
|
||||
│ │ 用 logger 替代并记录上下文 │ │
|
||||
│ │ [保留] [注释] ← 用户选择 │ │
|
||||
│ └─────────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ ✅ 无重复 (3 条) — 将保留 │
|
||||
│ ┌─────────────────────────────────────────┐ │
|
||||
│ │ no-hardcoded-secret error │ │
|
||||
│ │ 禁止硬编码 API Key │ │
|
||||
│ └─────────────────────────────────────────┘ │
|
||||
│ [确认导入] [取消] │
|
||||
└─────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
**关键交互**：
|
||||
- exact 档规则默认折叠（反正重复了），用户点"展开"才看详情，有「恢复此规则」按钮
|
||||
- overlap 档规则默认展开并高亮（需用户判断），置顶展示，有「保留」「注释」两个按钮
|
||||
- none 档规则默认折叠，点击可展开查看
|
||||
- 用户操作后即时更新"X 条保留 / Y 条注释"计数
|
||||
- 状态变更通过 `postMessage({ type: 'toggleRule', ruleId, keep })` 通知扩展端
|
||||
|
||||
### B3.7 setupView.ts 接入
|
||||
|
||||
当前 `addRule` 方法（第 181-210 行）改为：
|
||||
|
||||
```typescript
|
||||
// src/views/setupView.ts — addRule 方法改造
|
||||
|
||||
private async addRule(name: string): Promise<void> {
|
||||
if (!name.trim()) { return; }
|
||||
const workspaceRoot = vscode.workspace.workspaceFolders?.[0]?.uri.fsPath;
|
||||
if (!workspaceRoot) { return; }
|
||||
|
||||
const result = await vscode.window.showOpenDialog({
|
||||
canSelectMany: false,
|
||||
openLabel: '选择规则文件',
|
||||
filters: { '规则文件': ['yaml', 'yml', 'md', 'txt', 'xlsx', 'xls'] },
|
||||
});
|
||||
if (!result || result.length === 0) { return; }
|
||||
|
||||
const srcPath = result[0].fsPath;
|
||||
const ext = path.extname(srcPath).slice(1).toLowerCase;
|
||||
|
||||
const rulesDir = path.join(workspaceRoot, '.code-review', 'rules');
|
||||
if (!fs.existsSync(rulesDir)) {
|
||||
fs.mkdirSync(rulesDir, { recursive: true });
|
||||
}
|
||||
const yamlFileName = name.endsWith('.yaml') ? name : `${name}.yaml`;
|
||||
const yamlPath = path.join(rulesDir, yamlFileName);
|
||||
if (fs.existsSync(yamlPath)) {
|
||||
vscode.window.showErrorMessage(`文件 ${yamlFileName} 已存在`);
|
||||
return;
|
||||
}
|
||||
|
||||
// 分支：YAML 直接复制（不预览）；其他格式 AI 转换 + 预览
|
||||
if (ext === 'yaml' || ext === 'yml') {
|
||||
fs.copyFileSync(srcPath, yamlPath);
|
||||
vscode.window.showInformationMessage(`规则文件已导入: ${yamlFileName}`);
|
||||
} else {
|
||||
// AI 转换
|
||||
const conversion = await this.importService.convert(srcPath, this.context);
|
||||
|
||||
// 预览确认
|
||||
const decision = await showImportPreview(conversion, this.context.extensionUri);
|
||||
if (!decision || !decision.confirmed) {
|
||||
vscode.window.showInformationMessage('导入已取消');
|
||||
return;
|
||||
}
|
||||
|
||||
// 注释化 + 写盘
|
||||
this.importService.applyConversion(conversion, decision, yamlPath);
|
||||
vscode.window.showInformationMessage(
|
||||
`规则已导入: ${yamlFileName}（${conversion.rules.length} 条，` +
|
||||
`${conversion.exactCount} 条完全重复已注释，` +
|
||||
`${conversion.overlapCount} 条部分重叠已标注）`
|
||||
);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## B4. 边界情况
|
||||
|
||||
| 场景 | 处理方式 |
|
||||
|------|---------|
|
||||
| AI 未输出 `duplicateLevel` 字段 | 视为 none，规则正常保留 |
|
||||
| AI 输出 `duplicateLevel: exact` 但无 `duplicateOf` | 注释化时 dupInfo 显示 unknown，不影响注释行为 |
|
||||
| AI 输出 `duplicateLevel: overlap` 但无 `duplicateReason` | 预览中 overlap 区显示"未提供重叠原因"，仍允许用户决定 |
|
||||
| AI 对所有规则都标记 `exact` | 全部注释，文件仅含注释行。预览提示"全部规则与静态分析完全重复" |
|
||||
| AI 对所有规则都标记 `overlap` | 全部保留（overlap 默认保留），预览全部置顶展示供用户确认 |
|
||||
| AI 误判（非重复标为 exact） | 用户在预览面板点「恢复此规则」一键纠正 |
|
||||
| AI 漏判（重复标为 none） | 规则正常激活，运行时与 linter 重复报告同一问题。可接受——漏判不造成数据丢失 |
|
||||
| `duplicateOf` 格式不规范 | 后处理时原样写入注释头，不影响功能 |
|
||||
| 源文件为空或无有效规则 | Converter 返回空规则列表，预览提示"未检测到有效规则"，不写盘 |
|
||||
| 用户在预览中取消 | 不写盘，不创建文件 |
|
||||
| YAML 直接导入 | 跳过 AI 转换和预览，直接复制到目标路径 |
|
||||
| `static-rules.json` 缺失或格式错误 | `buildDedupPromptSection` 返回空字符串，prompt 不含规则清单，AI 降级为模糊判断 |
|
||||
|
||||
---
|
||||
|
||||
# 合并章节
|
||||
|
||||
## C1. 完整改动清单
|
||||
|
||||
### Part A 改动
|
||||
|
||||
| 文件 | 操作 | 内容 |
|
||||
|------|------|------|
|
||||
| `src/types.ts` | 修改 | `CustomRule` 新增 `excludeLanguages?: string[]` |
|
||||
| `src/rules/rule-filter.ts` | **新建** | `filterForDocument` + `filterAndSummarize` + 语言别名/JSP 处理 |
|
||||
| `src/activation/commands.ts` | 修改 | review 命令中 load → filterAndSummarize → runAIReview |
|
||||
| `src/rules/yaml-parser.ts` | 修改 | `RuleYamlItem` + 解析新增 `excludeLanguages` |
|
||||
| `src/merger/merger.ts` | 修改 | `MergedReport` + `MergeInput` 新增 `customRuleFilterInfo` |
|
||||
| `src/panel/webview.ts` | 修改 | 自定义规则 Tab 展示过滤信息 |
|
||||
| `src/test/rule-filter.test.ts` | **新建** | 过滤模块单元测试 |
|
||||
|
||||
### Part B 改动
|
||||
|
||||
| 文件 | 操作 | 内容 |
|
||||
|------|------|------|
|
||||
| `src/rules/static-rules.json` | **新建（离线定稿）** | 四个 linter 的规则 ID + 描述清单，人工提炼验收 |
|
||||
| `src/rules/converters/prompt-builder.ts` | **新建** | `buildDedupPromptSection` 从 static-rules.json 生成 prompt 片段 |
|
||||
| `src/rules/import-types.ts` | **新建** | `ImportableRule`（含 duplicateLevel/duplicateReason）+ `ConversionResult` + `PreviewDecision` |
|
||||
| `src/rules/import-preview.ts` | **新建** | `showImportPreview` Webview 面板（三分区展示） |
|
||||
| `src/rules/import-service.ts` | 修改 | 拆分 `convert`（不写盘）+ 新增 `applyConversion`（三档注释化写盘） |
|
||||
| `src/rules/converters/md-converter.ts` | 修改 | prompt 追加语言约束 + 规则清单注入 + 三档重复检测 |
|
||||
| `src/rules/converters/txt-converter.ts` | 修改 | 同上 |
|
||||
| `src/rules/converters/excel-converter.ts` | 修改 | 同上 |
|
||||
| `src/views/setupView.ts` | 修改 | `addRule` 分支：YAML 直接复制 / 其他 AI 转换+预览 |
|
||||
| `src/test/import-dedup.test.ts` | **新建** | 注释化后处理单元测试（含三档场景） |
|
||||
|
||||
### 两部分共享
|
||||
|
||||
| 文件 | 说明 |
|
||||
|------|------|
|
||||
| `src/types.ts` | Part A 加 `excludeLanguages`，Part B 不改此文件（`duplicateLevel` 等在 `import-types.ts`） |
|
||||
| `src/rules/converters/*.ts` | Part A 加语言约束 prompt，Part B 加规则清单 + 重复检测 prompt——**同一次 prompt 修改** |
|
||||
|
||||
**改动统计**：新建 7 文件（含 `static-rules.json`），修改 9 文件。
|
||||
|
||||
---
|
||||
|
||||
## C2. 测试要求
|
||||
|
||||
### C2.1 Part A 单元测试
|
||||
|
||||
文件：`src/test/rule-filter.test.ts`
|
||||
|
||||
| # | 用例 | 输入 | 预期 |
|
||||
|---|------|------|------|
|
||||
| 1 | 白名单命中 | rule.languages=[java]，document=java | 保留 |
|
||||
| 2 | 白名单未命中 | rule.languages=[javascript]，document=java | 剔除 |
|
||||
| 3 | 白名单为空 | rule.languages=[]，document=任意 | 保留 |
|
||||
| 4 | 白名单缺失 | rule 无 languages 字段，document=任意 | 保留 |
|
||||
| 5 | 黑名单命中剔除 | rule.excludeLanguages=[css]，document=css | 剔除 |
|
||||
| 6 | 黑名单未命中保留 | rule.excludeLanguages=[css]，document=java | 保留 |
|
||||
| 7 | 黑名单为空 | rule.excludeLanguages=[]，document=任意 | 保留 |
|
||||
| 8 | 白名单+黑名单交集 | languages=[java]，excludeLanguages=[java]，document=java | 剔除 |
|
||||
| 9 | tsx 别名 | rule.languages=[typescript]，document=typescriptreact | 保留 |
|
||||
| 10 | plsql 同组 | rule.languages=[sql]，document=plsql | 保留 |
|
||||
| 11 | JSP 并集-java规则 | rule.languages=[java]，document=html+.jsp | 保留 |
|
||||
| 12 | JSP 并集-css规则 | rule.languages=[css]，document=html+.jsp | 保留 |
|
||||
| 13 | 普通HTML不触发JSP | rule.languages=[java]，document=html（非.jsp） | 剔除 |
|
||||
| 14 | 全部过滤 | 7条规则，document=css | relevant=[]，skippedRequestA=true |
|
||||
| 15 | 部分过滤 | 7条规则，document=java | relevant=5，filteredOut=2 |
|
||||
|
||||
### C2.2 Part B 单元测试
|
||||
|
||||
文件：`src/test/import-dedup.test.ts`
|
||||
|
||||
| # | 用例 | 输入 | 预期 |
|
||||
|---|------|------|------|
|
||||
| 1 | 无重复规则 | 5 条规则均为 duplicateLevel=none | 全部保留，无注释行 |
|
||||
| 2 | 全部 exact | 3 条规则均为 duplicateLevel=exact | 全部注释，文件仅含 # 行 |
|
||||
| 3 | 全部 overlap | 3 条规则均为 duplicateLevel=overlap | 全部保留（overlap 默认保留），无注释行 |
|
||||
| 4 | 混合三档 | 2 exact + 2 overlap + 3 none | 2 条注释，5 条保留 |
|
||||
| 5 | 用户恢复 exact 规则 | 默认注释的 exact 规则，用户 toggle 为保留 | 该规则无 # 前缀，其余不变 |
|
||||
| 6 | 用户注释 overlap 规则 | 默认保留的 overlap 规则，用户 toggle 为注释 | 该规则加 # 前缀，含 overlap 注释头 |
|
||||
| 7 | 用户注释 none 规则 | 默认保留的 none 规则，用户 toggle 为注释 | 该规则加 # 前缀 |
|
||||
| 8 | duplicateLevel 行移除 | 保留规则的 YAML 中含 duplicateLevel 行 | 写盘后该行被移除 |
|
||||
| 9 | 注释规则含 duplicateReason | overlap 规则被注释 | 注释头含"重叠原因"行 |
|
||||
| 10 | 空规则列表 | Converter 返回 0 条规则 | 不写盘，返回取消 |
|
||||
| 11 | YAML 直接导入 | ext=yaml | 直接复制，不调 AI，不弹预览 |
|
||||
| 12 | static-rules.json 缺失 | buildDedupPromptSection 调用时文件不存在 | 返回空字符串，不中断 |
|
||||
|
||||
### C2.3 集成测试
|
||||
|
||||
在 `src/test/pipeline.test.ts` 中追加：
|
||||
|
||||
- 审查 CSS 文件时，验证请求 A 被跳过（`customRuleResults` 为空，`degraded` 为 false）。
|
||||
- 审查 Java 文件时，验证只有 Java 相关规则出现在 `customRuleResults` 中。
|
||||
- 导入含重复规则的 md 文件，验证预览面板显示重复标记，确认后文件中重复规则被注释。
|
||||
|
||||
---
|
||||
|
||||
## C3. 验证标准
|
||||
|
||||
| 验证项 | 方法 | 通过标准 |
|
||||
|--------|------|---------|
|
||||
| 编译 | `npm run compile` | 无 TypeScript 错误 |
|
||||
| Lint | `npm run lint` | 无 ESLint 错误 |
|
||||
| Part A 单测 | `npm test` | rule-filter.test.ts 全部通过 |
|
||||
| Part B 单测 | `npm test` | import-dedup.test.ts 全部通过 |
|
||||
| 预过滤-Java | 用 `src/test/manual/Buggy.java` 审查 | 自定义规则 Tab 显示"注入 5/7 条"，custom 结果非空 |
|
||||
| 预过滤-CSS | 用 `src/test/manual/buggy.css` 审查 | 自定义规则 Tab 显示"已跳过规则评估" |
|
||||
| 预过滤-JSP | 用 `src/test/manual/buggy.jsp` 审查 | Java+JS 规则均保留注入 |
|
||||
| 容错验证 | 构造 languages 误标的规则 | 留空规则始终保留，不因误标漏报 |
|
||||
| 导入-YAML | 导入 .yaml 文件 | 直接复制，不弹预览 |
|
||||
| 导入-MD-exact | 导入含完全重复规则的 .md 文件 | 预览显示"完全重复"区，确认后该规则被注释 |
|
||||
| 导入-MD-overlap | 导入含部分重叠规则的 .md 文件 | 预览显示"部分重叠"区并置顶，含重叠原因，用户可选保留/注释 |
|
||||
| 导入-恢复 | 在预览中点「恢复此规则」 | 该规则在写盘后无 # 前缀，可被 yaml-parser 加载 |
|
||||
| 导入-取消 | 在预览中点「取消」 | 不写盘，不创建文件 |
|
||||
| static-rules.json | 检查文件存在且格式正确 | 含五个 linter 分区，每条规则有 id + description |
|
||||
|
||||
---
|
||||
|
||||
## C4. 实施顺序
|
||||
|
||||
两部分合并实施，按依赖关系排序：
|
||||
|
||||
**第一批：Part A 最小闭环（预过滤 + 跳过请求 A）**
|
||||
|
||||
1. `types.ts` — 扩展 CustomRule 接口（加 `excludeLanguages`）
|
||||
2. `rule-filter.ts` — 新建过滤模块（核心，可独立测试）
|
||||
3. `rule-filter.test.ts` — 编写单元测试
|
||||
4. `yaml-parser.ts` — 适配 `excludeLanguages` 解析
|
||||
5. `commands.ts` — review 命令接入 `filterAndSummarize`
|
||||
|
||||
> 步骤 1-5 完成后，预过滤即可生效。`engine.ts` 不需要改动（现有空规则处理已足够）。
|
||||
|
||||
**第二批：Part B 导入去重**
|
||||
|
||||
6. `static-rules.json` — 离线提炼四个 linter 规则集，人工验收定稿
|
||||
7. `prompt-builder.ts` — 新建，从 static-rules.json 生成 prompt 片段
|
||||
8. `import-types.ts` — 新建导入中间态类型（含三档字段）
|
||||
9. `import-service.ts` — 拆分 convert/applyConversion + 三档注释化后处理
|
||||
10. `import-dedup.test.ts` — 编写注释化单元测试（含三档场景）
|
||||
11. `converters/*.ts` — prompt 追加语言约束 + 规则清单注入 + 三档重复检测（一次改完三个）
|
||||
12. `import-preview.ts` — 新建预览 Webview 面板（三分区展示）
|
||||
13. `setupView.ts` — addRule 分支改造
|
||||
|
||||
**第三批：体验增强（可后续迭代）**
|
||||
|
||||
14. `merger.ts` — MergedReport 新增 `customRuleFilterInfo`
|
||||
15. `webview.ts` — 审查面板展示过滤信息
|
||||
16. 集成测试 + 功能验证
|
||||
|
||||
> 第一批和第二批可并行开发（文件不重叠），第三批依赖第一批完成。
|
||||
|
||||
---
|
||||
|
||||
## C5. 设计决策记录
|
||||
|
||||
### Part A 决策
|
||||
|
||||
| 决策项 | 选择 | 理由 |
|
||||
|--------|------|------|
|
||||
| config.yaml 过滤机制 | 不实现/不保留（已废弃） | 全启用模式，规则文件存在即生效 |
|
||||
| 过滤位置 | load 与 execute 之间（独立纯函数） | 不耦合加载逻辑，不改 runAIReview 签名 |
|
||||
| engine.ts 改动 | **不需要** | 现有 `customRules.length > 0 ? ... : Promise.resolve('{}')` 已处理空规则 |
|
||||
| 过滤策略 | 软过滤（留空规则始终保留） | 字段不准时退化为现状，不会误剔除 |
|
||||
| languages 为空语义 | 全语言生效 | 安全默认 |
|
||||
| 新增 excludeLanguages | 是 | 通用规则用黑名单比白名单更安全 |
|
||||
| JSP 处理 | 子语言并集 | AI 一次评估整个 JSP，需看到所有相关规则 |
|
||||
| SQL/PLSQL | 同组 | 与 sql-lint 适配器覆盖范围一致 |
|
||||
|
||||
### Part B 决策
|
||||
|
||||
| 决策项 | 选择 | 理由 |
|
||||
|--------|------|------|
|
||||
| 检测范围 | 只对 md/txt/excel | YamlConverter 直接复制，用户手写 YAML 无需检测 |
|
||||
| 确认流程 | 强制预览确认 | 误判会静默禁用规则，风险高 |
|
||||
| 判定结果分档 | 三档：exact / overlap / none | 二元判定丢失"部分重叠"信息，overlap 交用户决定 |
|
||||
| 规则清单来源 | 离线提炼，手工定稿打包 | 四个 linter 内置且版本固定，规则集是确定常量，无需运行时提取 |
|
||||
| 规则清单精度 | 规则 ID + 一句话描述（Level 2） | 精确映射比模糊概述更准，prompt 增加约 1500 token 可接受 |
|
||||
| 全部重复 | 仍写盘（全是注释） | 用户可取消注释恢复 |
|
||||
| 注释化机制 | 行级 `#` 前缀 | yaml-parser 已跳过 `#` 行，无需改 parser |
|
||||
| duplicateLevel 字段位置 | 导入中间态（`import-types.ts`），不加到 CustomRule | 它是导入时信息，不是运行时规则属性 |
|
||||
| 预览形式 | Webview 结构化面板，三分区展示 | exact 折叠 / overlap 置顶展开 / none 折叠 |
|
||||
| 预览交互 | 每条规则可 toggle 保留/注释 | 用户可一键纠正 AI 误判 |
|
||||
| Converter prompt | 语言约束 + 规则清单 + 重复检测合并 | 同一次 AI 调用，一次 prompt 修改 |
|
||||
| static-rules.json 维护 | linter 升级时重新提炼 | 版本随插件发布绑定，不会在用户侧变化 |
|
||||
@@ -0,0 +1,217 @@
|
||||
# 自定义规则导入去重增强方案
|
||||
|
||||
## 1. 架构概览
|
||||
|
||||
### 现状
|
||||
|
||||
```
|
||||
static-rules.json ──→ buildDedupPromptSection() ──→ 嵌入 AI 提示词 → AI 判断 exact/overlap/none
|
||||
```
|
||||
|
||||
### 目标
|
||||
|
||||
```
|
||||
static-rules.json ──┐
|
||||
├──→ buildDedupPromptSection(existingRules) ──→ AI 判断 exact/overlap/none
|
||||
已导入自定义规则 ────┘
|
||||
↑
|
||||
loadActiveRules() ── 自动加载 .code-review/rules/*.yaml
|
||||
```
|
||||
|
||||
### 数据流
|
||||
|
||||
```
|
||||
ImportService.convert()
|
||||
│ ① 调用 loadActiveRules(workspaceRoot) 加载已有自定义规则
|
||||
│ ② 将 existingRules 传递给 converter.convert()
|
||||
│ │
|
||||
│ └─ converter.buildSystemPrompt(existingRules)
|
||||
│ │
|
||||
│ └─ buildDedupPromptSection(existingRules)
|
||||
│ │
|
||||
│ ├─ 输出静态 linter 规则（不变）
|
||||
│ └─ 追加已导入自定义规则，ID 前缀 custom/
|
||||
│
|
||||
│ ③ AI 返回结果，含 duplicateOf: custom/xxx、duplicateLevel 等字段
|
||||
│ ④ parseImportableYaml() 解析，字段不变
|
||||
│
|
||||
▼
|
||||
showImportPreview()
|
||||
│ ⑤ 识别 duplicateOf 的 custom/ 前缀，显示不同文案
|
||||
│
|
||||
▼
|
||||
buildFinalYaml()
|
||||
│ ⑥ 注释头文案区分 custom/ 前缀
|
||||
│
|
||||
▼
|
||||
applyConversion() → 写入 .yaml
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. 文件变更清单
|
||||
|
||||
| 文件 | 变更类型 | 说明 |
|
||||
|------|----------|------|
|
||||
| `src/rules/converters/prompt-builder.ts` | 修改 | `buildDedupPromptSection()` 增加 `existingCustomRules` 参数 |
|
||||
| `src/rules/converters/converter.ts` | 修改 | `convert()` 增加可选参数 `existingRules` |
|
||||
| `src/rules/converters/md-converter.ts` | 修改 | 传递 `existingRules` 至 `buildSystemPrompt()` |
|
||||
| `src/rules/converters/txt-converter.ts` | 修改 | 同上 |
|
||||
| `src/rules/converters/excel-converter.ts` | 修改 | 同上 |
|
||||
| `src/rules/converters/docx-converter.ts` | 修改 | 同上 |
|
||||
| `src/rules/converters/pptx-converter.ts` | 修改 | 同上 |
|
||||
| `src/rules/import-service.ts` | 修改 | `convert()` 加载已有规则；`buildFinalYaml()` 格式化 custom 注释头 |
|
||||
| `src/rules/import-preview.ts` | 修改 | 识别 `custom/` 前缀显示区分文案 |
|
||||
| `src/test/import-dedup.test.ts` | 修改 | 追加测试用例（自定义规则 exact/overlap/none） |
|
||||
|
||||
---
|
||||
|
||||
## 3. 关键接口变更
|
||||
|
||||
### 3.1 `prompt-builder.ts`
|
||||
|
||||
```typescript
|
||||
import type { CustomRule } from '../../types';
|
||||
|
||||
// 新增参数
|
||||
export function buildDedupPromptSection(existingCustomRules?: CustomRule[]): string;
|
||||
```
|
||||
|
||||
输出格式变更：
|
||||
|
||||
```
|
||||
## 已知规则清单（用于重复检测）
|
||||
|
||||
### 内置 Linter 规则
|
||||
#### eslint (XX 条)
|
||||
- eslint/rule-id: description
|
||||
...
|
||||
|
||||
### 已导入的自定义规则 (N 条)
|
||||
- custom/my-rule: 禁止 console.log
|
||||
- custom/no-var: 使用 const/let 替代 var
|
||||
|
||||
判定时请精确匹配上述规则 ID，而非模糊匹配分类。
|
||||
```
|
||||
|
||||
### 3.2 `converter.ts`
|
||||
|
||||
```typescript
|
||||
import type { CustomRule } from '../../types';
|
||||
|
||||
export interface RuleConverter {
|
||||
supportedExtensions: string[];
|
||||
convert(
|
||||
srcPath: string,
|
||||
context: vscode.ExtensionContext,
|
||||
existingRules?: CustomRule[], // 新增参数
|
||||
): Promise<string | null>;
|
||||
}
|
||||
```
|
||||
|
||||
### 3.3 Converters（5 个文件，模式一致）
|
||||
|
||||
每个 converter 的 `buildSystemPrompt` 改为接受 `existingRules` 参数并向下传递。
|
||||
|
||||
**改前：**
|
||||
```typescript
|
||||
function buildSystemPrompt(): string {
|
||||
return `...${buildDedupPromptSection()}...`;
|
||||
}
|
||||
```
|
||||
|
||||
**改后：**
|
||||
```typescript
|
||||
function buildSystemPrompt(existingRules?: CustomRule[]): string {
|
||||
return `...${buildDedupPromptSection(existingRules)}...`;
|
||||
}
|
||||
```
|
||||
|
||||
对应 `convert()` 方法：
|
||||
```typescript
|
||||
async convert(srcPath: string, context: vscode.ExtensionContext, existingRules?: CustomRule[]): Promise<string | null> {
|
||||
const content = fs.readFileSync(srcPath, 'utf-8');
|
||||
return convertContentWithAI(content, context, buildSystemPrompt(existingRules));
|
||||
}
|
||||
```
|
||||
|
||||
### 3.4 `import-service.ts`
|
||||
|
||||
#### `ImportService.convert()` — 新增加载已有规则
|
||||
|
||||
```typescript
|
||||
import { loadActiveRules } from './yaml-parser';
|
||||
|
||||
async convert(srcPath: string, context: vscode.ExtensionContext): Promise<ConversionResult> {
|
||||
const workspaceRoot = vscode.workspace.workspaceFolders?.[0]?.uri.fsPath;
|
||||
const existingRules = workspaceRoot ? loadActiveRules(workspaceRoot) : [];
|
||||
|
||||
const ext = path.extname(srcPath).toLowerCase();
|
||||
const converter = this.converters.get(ext);
|
||||
// ...
|
||||
const yamlContent = await converter.convert(srcPath, context, existingRules);
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
#### `buildFinalYaml()` — 注释头区分 custom 前缀
|
||||
|
||||
在生成 `# [DUPLICATE]` 注释头时，判断 `duplicateOf` 是否以 `custom/` 开头：
|
||||
|
||||
- `custom/xxx` → `# [DUPLICATE: exact] 重复自定义规则 xxx（检测目标完全一致）`
|
||||
- `eslint/xxx` → `# [DUPLICATE: exact] 重复 eslint/xxx（检测目标完全一致）`（不变）
|
||||
- overlap 同理
|
||||
|
||||
### 3.5 `import-preview.ts`
|
||||
|
||||
新增辅助函数，在 `renderRuleCard` 中调用：
|
||||
|
||||
```typescript
|
||||
function formatDuplicateOf(dupOf: string | undefined): { type: 'custom' | 'linter'; ruleName: string } {
|
||||
if (!dupOf) return { type: 'linter', ruleName: 'unknown' };
|
||||
if (dupOf.startsWith('custom/')) {
|
||||
return { type: 'custom', ruleName: dupOf.slice(7) };
|
||||
}
|
||||
return { type: 'linter', ruleName: dupOf };
|
||||
}
|
||||
```
|
||||
|
||||
UI 显示规则：
|
||||
|
||||
| duplicateOf | type | 显示文案 |
|
||||
|-------------|------|----------|
|
||||
| `custom/no-console-log` | custom | `重复：自定义规则 no-console-log` |
|
||||
| `eslint/no-console` | linter | `重复：eslint/no-console`（不变） |
|
||||
| overlap + custom | custom | `与自定义规则 no-console-log 部分重叠` |
|
||||
| overlap + linter | linter | `与 eslint/no-console 部分重叠`（不变） |
|
||||
|
||||
---
|
||||
|
||||
## 4. 不变的部分
|
||||
|
||||
- `ImportableRule` 接口（字段不变，duplicateOf 的值新加 `custom/` 前缀由 AI 输出）
|
||||
- `PreviewDecision` 接口
|
||||
- `ConversionResult` 接口
|
||||
- `YamlConverter`（YAML 直接复制不走 AI，不需要去重）
|
||||
- `parseImportableYaml()`（解析逻辑不变，duplicateOf 字段值变化不影响解析）
|
||||
- `buildFinalYaml()` 的保留逻辑（去重字段剥离、# 注释前缀）不变
|
||||
|
||||
---
|
||||
|
||||
## 5. 影响范围
|
||||
|
||||
### 正面
|
||||
- 导入新规则时自动对比已有自定义规则，避免重复导入
|
||||
- 已导入规则之间交叉重复也可检测（规则文件 A 和 B 之间有重复 ID/语义）
|
||||
|
||||
### 风险与应对
|
||||
- **提示词长度增加**：如果已有规则很多（>50条），prompt 会变长。应对：当前实测 1788 条静态规则 + 50 条自定义规则约 80KB token，主流模型可承受。如果未来规则量过大，可考虑只传 ID 列表。
|
||||
- **自参考**：正在导入的文件尚未写入 `.code-review/rules/`，不会出现自己检测自己的情况。
|
||||
- **custom/ 前缀规范**：需要 AI 理解并准确输出，已在 prompt 中明确指定格式，并在已有示例中示范。
|
||||
|
||||
### 测试覆盖
|
||||
需要在 `src/test/import-dedup.test.ts` 中新增：
|
||||
1. 自定义规则 exact → 默认注释
|
||||
2. 自定义规则 overlap → 默认保留
|
||||
3. 自定义规则 exact 用户恢复 → 取消注释
|
||||
4. 混合场景（部分与 linter 重复、部分与 custom 重复）
|
||||
@@ -0,0 +1,66 @@
|
||||
# Excel 多 Sheet 导入设计
|
||||
|
||||
## 1. 背景
|
||||
|
||||
当前 `ExcelConverter.convert()` 仅读取 Excel 文件的第一个 Sheet（`workbook.SheetNames[0]`），后续 Sheet 被忽略。用户需要导入包含多个 Sheet 的 Excel 文件，将全部规则合并输出。
|
||||
|
||||
## 2. 目标
|
||||
|
||||
支持多 Sheet Excel 导入，所有 Sheet 合并为一份 YAML 输出。不改变 `RuleConverter` 接口签名。
|
||||
|
||||
## 3. 设计
|
||||
|
||||
### 3.1 数据流
|
||||
|
||||
```
|
||||
用户选择 .xlsx/.xls 文件（多 Sheet）
|
||||
↓
|
||||
ExcelConverter.convert()
|
||||
├── XLSX.readFile → 获取 workbook
|
||||
├── 遍历 workbook.SheetNames
|
||||
│ ├── 每个 sheet → sheet_to_json → buildMarkdownTable
|
||||
│ └── 添加 "## SheetName" 标题分隔
|
||||
├── 合并为一张大 Markdown 文本
|
||||
├── 调用 convertContentWithAI(combined, context)
|
||||
└── AI 返回 YAML（合并所有规则）→ 写入 yamlPath
|
||||
```
|
||||
|
||||
### 3.2 变更范围
|
||||
|
||||
只改一个文件：`src/rules/converters/excel-converter.ts`
|
||||
|
||||
| 变更 | 说明 |
|
||||
|------|------|
|
||||
| 删除 `const sheetName = workbook.SheetNames[0]` | 不再只取第一个 Sheet |
|
||||
| 新增 `buildSheetsMarkdown(workbook)` | 遍历所有 Sheet，逐个转 Markdown 表格并拼接 |
|
||||
| 修改 `convert()` 内部 | 调用 `buildSheetsMarkdown` 替代单 Sheet 逻辑 |
|
||||
| 保留 `buildMarkdownTable(rows)` | 复用现有单 Sheet 转表格函数 |
|
||||
| 保留错误处理 | try/catch、空 Sheet 校验 |
|
||||
|
||||
### 3.3 合并格式示例
|
||||
|
||||
```
|
||||
## Sheet1 - 命名规范
|
||||
| id | severity | description | message |
|
||||
|----|----------|-------------|---------|
|
||||
| naming-1 | error | 类名使用 PascalCase | 请修改为 PascalCase |
|
||||
|
||||
## Sheet2 - 安全规范
|
||||
| id | severity | description | message |
|
||||
|----|----------|-------------|---------|
|
||||
| security-1 | error | 禁止硬编码密码 | 请将密码移入配置文件 |
|
||||
```
|
||||
|
||||
### 3.4 边界处理
|
||||
|
||||
- **空 Sheet**：跳过（不报错），继续处理其他 Sheet
|
||||
- **全部 Sheet 为空**：报错提示"Excel 工作表中没有数据"
|
||||
- **不同 Sheet 列结构不同**：各自独立转 Markdown 表格，AI 自主理解
|
||||
- **单 Sheet 文件**：行为不变，兼容现有功能
|
||||
|
||||
### 3.5 不涉及变更
|
||||
|
||||
- `setupView.ts`：ExcelConverter 已注册，无需改动
|
||||
- `import-service.ts`：`convertContentWithAI` 已存在，无需改动
|
||||
- `converter.ts`：`RuleConverter` 接口不变
|
||||
- 其他 converter：不受影响
|
||||
@@ -0,0 +1,136 @@
|
||||
# Word / PPT 规则导入设计
|
||||
|
||||
## 1. 背景
|
||||
|
||||
当前自定义规则导入支持 YAML、Markdown、TXT、Excel（.xlsx/.xls）格式，用户需要补充 Word（.docx）和 PowerPoint（.pptx）文件导入能力。
|
||||
|
||||
## 2. 目标
|
||||
|
||||
- 支持 .docx 文件导入：通过 mammoth 提取 Markdown 文本，AI 转换为规则 YAML
|
||||
- 支持 .pptx 文件导入：通过 officeparser 提取幻灯片文本，AI 转换为规则 YAML
|
||||
- 沿用现有 Converter 架构（RuleConverter 接口 + ImportService 注册机制）
|
||||
|
||||
## 3. 架构
|
||||
|
||||
### 3.1 数据流
|
||||
|
||||
```
|
||||
setupView.ts (addRule)
|
||||
│
|
||||
▼
|
||||
ImportService.convert(srcPath, context)
|
||||
│
|
||||
├── path.extname → DocxConverter (.docx)
|
||||
│ └── mammoth.extractRawText() / convertToMarkdown()
|
||||
│ └── Markdown 文本 → convertContentWithAI() → YAML
|
||||
│
|
||||
├── path.extname → PptxConverter (.pptx)
|
||||
│ └── officeparser.parsePptx()
|
||||
│ └── 纯文本（幻灯片逐页分隔）→ convertContentWithAI() → YAML
|
||||
│
|
||||
└── parseImportableYaml() → 预览 → 写入 .code-review/rules/<name>.yaml
|
||||
```
|
||||
|
||||
### 3.2 现有架构映射
|
||||
|
||||
| 组件 | 文件 | 说明 |
|
||||
|------|------|------|
|
||||
| RuleConverter 接口 | `src/rules/converters/converter.ts` | 不变 |
|
||||
| ImportService | `src/rules/import-service.ts` | 不变 |
|
||||
| convertContentWithAI | `src/rules/import-service.ts` | 复用 |
|
||||
| setupView 注册 | `src/views/setupView.ts` | 新增两个 converter 注册 + 更新文件过滤器 |
|
||||
|
||||
## 4. 文件变更清单
|
||||
|
||||
| 文件 | 操作 | 说明 |
|
||||
|------|------|------|
|
||||
| `src/rules/converters/docx-converter.ts` | **新建** | .docx → mammoth → AI → YAML |
|
||||
| `src/rules/converters/pptx-converter.ts` | **新建** | .pptx → officeparser → AI → YAML |
|
||||
| `src/views/setupView.ts` | **修改** | 注册两个新 converter + 更新文件过滤器 |
|
||||
| `package.json` | **修改** | 添加 mammoth + officeparser 依赖 |
|
||||
|
||||
## 5. 关键实现
|
||||
|
||||
### 5.1 DocxConverter
|
||||
|
||||
```typescript
|
||||
// src/rules/converters/docx-converter.ts
|
||||
// 依赖：mammoth（将 .docx 提取为 Markdown/HTML）
|
||||
//
|
||||
// 行为：
|
||||
// 1. mammoth.convertToMarkdown() 提取 Markdown（含表格→Markdown 表格）
|
||||
// 2. 将 Markdown 文本传入 convertContentWithAI()
|
||||
// 3. AI 按已有 prompt 生成 YAML 规则
|
||||
//
|
||||
// 复用现有 buildSystemPrompt() 模式
|
||||
// systemPrompt 与 md-converter.ts 相同（自然语言规则描述 → YAML）
|
||||
// 由于 mammoth 已产出 Markdown，AI 可识别表格/段落/列表结构
|
||||
```
|
||||
|
||||
### 5.2 PptxConverter
|
||||
|
||||
```typescript
|
||||
// src/rules/converters/pptx-converter.ts
|
||||
// 依赖：officeparser（将 .pptx 提取为纯文本）
|
||||
//
|
||||
// 行为：
|
||||
// 1. officeparser.parsePptx() 提取所有幻灯片文本
|
||||
// 2. 幻灯片之间用 "\n\n--- Slide N ---\n\n" 分隔
|
||||
// 3. 合并文本传入 convertContentWithAI()
|
||||
// 4. AI 按已有 prompt 生成 YAML 规则
|
||||
//
|
||||
// systemPrompt 与 md-converter.ts 相同
|
||||
```
|
||||
|
||||
### 5.3 setupView.ts 变更
|
||||
|
||||
```typescript
|
||||
// 1. 导入新 converter
|
||||
import { DocxConverter } from '../rules/converters/docx-converter';
|
||||
import { PptxConverter } from '../rules/converters/pptx-converter';
|
||||
|
||||
// 2. 构造函数中注册
|
||||
this.importService.registerConverter(new DocxConverter());
|
||||
this.importService.registerConverter(new PptxConverter());
|
||||
|
||||
// 3. addRule() 文件过滤器增加扩展名
|
||||
filters: { '规则文件': ['yaml', 'yml', 'md', 'txt', 'xlsx', 'xls', 'docx', 'pptx'] },
|
||||
```
|
||||
|
||||
### 5.4 package.json 依赖
|
||||
|
||||
```json
|
||||
"dependencies": {
|
||||
...,
|
||||
"mammoth": "^1.8.0",
|
||||
"officeparser": "^4.2.0"
|
||||
}
|
||||
```
|
||||
|
||||
## 6. 错误处理
|
||||
|
||||
| 场景 | 处理方式 |
|
||||
|------|----------|
|
||||
| docx 文件损坏 | mammoth 抛出异常 → try/catch 弹错误提示 → return null |
|
||||
| pptx 文件损坏 | officeparser 抛出异常 → try/catch 弹错误提示 → return null |
|
||||
| docx 无内容 | mammoth 返回空字符串 → convertContentWithAI 检测到空内容 → 弹"所选文件为空" |
|
||||
| pptx 无内容 | officeparser 返回空字符串 → 同上 |
|
||||
| officeparser 未安装依赖 | 运行时缺 jszip 报错 → catch 弹提示 |
|
||||
|
||||
## 7. 不涉及变更
|
||||
|
||||
- `converter.ts`：RuleConverter 接口不变
|
||||
- `import-service.ts`：ImportService、convertContentWithAI、parseImportableYaml 均不变
|
||||
- `import-preview.ts`：预览 Webview 不变
|
||||
- `yaml-parser.ts`：运行时加载不变
|
||||
- `rule-filter.ts`：规则过滤不变
|
||||
- 其他 converter：不受影响
|
||||
- 前端 webview JS（`src/views/setupView.js`）：无变更
|
||||
|
||||
## 8. 测试
|
||||
|
||||
新增文件不涉及现有测试变更。可通过以下方式验证：
|
||||
1. 准备一个含规则表格的 .docx 文件和一个含规则列表的 .pptx 文件
|
||||
2. 在设置面板中点击"+ 添加"，分别选择 .docx 和 .pptx 文件
|
||||
3. 检查预览是否正确解析规则，命中等
|
||||
4. 确认 .code-review/rules/ 下生成正确的 .yaml 文件
|
||||
@@ -0,0 +1,263 @@
|
||||
# 规则导入预览编辑设计
|
||||
|
||||
> 适用项目：vscode-code-reviewer
|
||||
> 设计日期：2026-07-25
|
||||
> 参考文档：`docs/superpowers/specs/2026-07-23-rule-prefilter-design.md` Part B（导入去重）
|
||||
|
||||
## 1. 现状
|
||||
|
||||
`import-preview.ts` 中预览 Webview 面板仅支持：
|
||||
|
||||
- 按 exact/overlap/none 三区展示规则卡片
|
||||
- overlap 规则可切换「保留/注释」
|
||||
- exact 规则有「恢复」按钮
|
||||
- **无字段编辑能力**
|
||||
|
||||
用户确认后，`buildFinalYaml` 对原始 `yamlContent` 做行级操作（加/去 `#` 前缀）。编辑后的字段值无法传入。
|
||||
|
||||
## 2. 目标
|
||||
|
||||
导入预览中支持：
|
||||
|
||||
- 每条规则卡片默认证折叠，点击展开完整编辑表单
|
||||
- 可编辑字段：severity（下拉框）、description（多行文本）、message（多行文本）、languages（标签式输入）、excludeLanguages（标签式输入）
|
||||
- id 只读显示（不可编辑）
|
||||
- 所有规则类型（exact/overlap/none）均可编辑
|
||||
- 展开表单右上角显示「保留/注释」切换，两种状态下都可编辑字段
|
||||
- 确认后基于修改后的 rules 数组直接生成最终 YAML 写盘
|
||||
|
||||
## 3. 数据流变更
|
||||
|
||||
```
|
||||
现状：
|
||||
importService.convert() → ConversionResult → showImportPreview() → PreviewDecision{keepRule}
|
||||
↓
|
||||
buildFinalYaml(操作原始 yamlContent 行)
|
||||
|
||||
改造后：
|
||||
importService.convert() → ConversionResult → showImportPreview() → PreviewDecision{keepRule, editedRules}
|
||||
↓
|
||||
renderRulesToYaml(从 rules 数组生成新 YAML)
|
||||
```
|
||||
|
||||
关键变化：写盘不再基于原始 `yamlContent` 文本行操作，而是从（可能被用户编辑过的）rules 数组渲染出完整 YAML。
|
||||
|
||||
## 4. 数据结构变更
|
||||
|
||||
### 4.1 PreviewDecision 扩展
|
||||
|
||||
```typescript
|
||||
// src/rules/import-types.ts
|
||||
|
||||
export interface PreviewDecision {
|
||||
keepRule: Record<string, boolean>;
|
||||
confirmed: boolean;
|
||||
editedRules?: ImportableRule[]; // 用户编辑后的完整规则数组（含未修改的规则）
|
||||
}
|
||||
```
|
||||
|
||||
`editedRules` 为 `undefined` 表示用户未做任何字段修改，回退到原始 rules。非 `undefined` 时用于生成最终 YAML。
|
||||
|
||||
## 5. 预览 Webview 重设计
|
||||
|
||||
### 5.1 卡片结构
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────┐
|
||||
│ no-console-log [▼ 展开] │ ← 折叠态：id + severity 标签 + 描述摘要
|
||||
│ ⚠ warning │
|
||||
│ 禁止在 console.log 中输出敏感信息 │
|
||||
└─────────────────────────────────────────────┘
|
||||
|
||||
展开态： ← 点击卡片任意位置展开
|
||||
┌─────────────────────────────────────────────┐
|
||||
│ no-console-log [保留] [注释] │ ← 顶部：id + 保留/注释切换
|
||||
├─────────────────────────────────────────────┤
|
||||
│ severity │
|
||||
│ [▼ error ▼] ← 下拉框 │
|
||||
│ │
|
||||
│ description │
|
||||
│ ┌─────────────────────────────────────────┐│
|
||||
│ │ 禁止在 console.log 中输出敏感信息 ││ ← textarea
|
||||
│ │ ││
|
||||
│ └─────────────────────────────────────────┘│
|
||||
│ │
|
||||
│ message │
|
||||
│ ┌─────────────────────────────────────────┐│
|
||||
│ │ 检测到敏感信息输出到 console，请移除 ││ ← textarea
|
||||
│ │ ││
|
||||
│ └─────────────────────────────────────────┘│
|
||||
│ │
|
||||
│ languages │
|
||||
│ [java ×] [typescript ×] [▌ ] │ ← 标签式输入
|
||||
│ │
|
||||
│ excludeLanguages │
|
||||
│ [▌ ] │ ← 标签式输入
|
||||
└─────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### 5.2 交互行为
|
||||
|
||||
| 操作 | 行为 |
|
||||
|------|------|
|
||||
| 点击折叠卡片 | 展开表单，其余卡片不受影响 |
|
||||
| 展开状态下再次点击顶部 | 折叠回摘要 |
|
||||
| 修改字段 | 实时保存在前端 `modifiedRules` map 中 |
|
||||
| 切换保留/注释 | 更新 keepRule，不影响已编辑的字段值 |
|
||||
| 点「确认导入」 | 发送 `confirm` 消息 + 全部修改后的 rules 数据 |
|
||||
| 点「取消」 | 不写盘 |
|
||||
|
||||
### 5.3 标签式输入实现
|
||||
|
||||
languages / excludeLanguages 使用纯 HTML/CSS/JS 实现：
|
||||
|
||||
- 文本输入框 + 已添加标签的行内显示
|
||||
- 输入语言名后按 `Enter` 或 `,` 添加为标签
|
||||
- 标签显示为 chip 样式，右侧 `×` 按钮删除
|
||||
- 去重（同名不重复添加）
|
||||
- 支持粘贴逗号分隔列表
|
||||
|
||||
### 5.4 字段校验（确认时）
|
||||
|
||||
| 字段 | 规则 |
|
||||
|------|------|
|
||||
| severity | 必须是 `error` / `warning` / `info` 之一（下拉框天然保证） |
|
||||
| description | 非空，trim() 后长度 > 0 |
|
||||
| message | 非空，trim() 后长度 > 0 |
|
||||
| languages | 可选，每个值非空字符串 |
|
||||
| excludeLanguages | 可选，每个值非空字符串 |
|
||||
|
||||
校验不通过时弹 `vscode.window.showErrorMessage` 提示具体字段名，不关闭面板。
|
||||
|
||||
## 6. YAML 生成函数
|
||||
|
||||
新增 `renderRulesToYaml` 替代原有行级操作逻辑：
|
||||
|
||||
```typescript
|
||||
// src/rules/import-service.ts
|
||||
|
||||
function renderRulesToYaml(
|
||||
rules: ImportableRule[],
|
||||
decision: PreviewDecision,
|
||||
): string {
|
||||
const lines: string[] = [];
|
||||
|
||||
for (const rule of rules) {
|
||||
const keep = decision.keepRule[rule.id] ?? rule.duplicateLevel !== 'exact';
|
||||
|
||||
// 构造该规则的标准 YAML 行
|
||||
const ruleLines: string[] = [];
|
||||
ruleLines.push(`- id: ${rule.id}`);
|
||||
ruleLines.push(` severity: ${rule.severity}`);
|
||||
ruleLines.push(` description: ${rule.description}`);
|
||||
ruleLines.push(` message: ${rule.message}`);
|
||||
if (rule.languages && rule.languages.length > 0) {
|
||||
ruleLines.push(` languages: [${rule.languages.join(', ')}]`);
|
||||
}
|
||||
if (rule.excludeLanguages && rule.excludeLanguages.length > 0) {
|
||||
ruleLines.push(` excludeLanguages: [${rule.excludeLanguages.join(', ')}]`);
|
||||
}
|
||||
|
||||
if (keep) {
|
||||
lines.push(...ruleLines);
|
||||
} else {
|
||||
// 注释化：加注释头 + 每行加 #
|
||||
const dupLevel = rule.duplicateLevel ?? 'none';
|
||||
const dupOf = rule.duplicateOf ?? 'manual';
|
||||
if (dupLevel === 'exact') {
|
||||
lines.push(`# [DUPLICATE: exact] 重复 ${dupOf}（检测目标完全一致）`);
|
||||
} else if (dupLevel === 'overlap') {
|
||||
lines.push(`# [DUPLICATE: overlap] 与 ${dupOf} 部分重叠`);
|
||||
if (rule.duplicateReason) {
|
||||
lines.push(`# 重叠原因：${rule.duplicateReason}`);
|
||||
}
|
||||
} else {
|
||||
lines.push(`# [手动注释] 用户选择不启用此规则`);
|
||||
}
|
||||
lines.push(`# 如需启用，删除以下每行开头的 # 即可`);
|
||||
for (const rl of ruleLines) {
|
||||
lines.push(`# ${rl}`);
|
||||
}
|
||||
}
|
||||
|
||||
lines.push(''); // 规则间空行
|
||||
}
|
||||
|
||||
return lines.join('\n');
|
||||
}
|
||||
```
|
||||
|
||||
`buildFinalYaml` 改为判断入口：
|
||||
|
||||
```typescript
|
||||
export function buildFinalYaml(
|
||||
yamlContent: string,
|
||||
rules: ImportableRule[],
|
||||
decision: PreviewDecision,
|
||||
): string {
|
||||
if (decision.editedRules && decision.editedRules.length > 0) {
|
||||
// 用户编辑过字段，从编辑后的 rules 渲染
|
||||
return renderRulesToYaml(decision.editedRules, decision);
|
||||
}
|
||||
// 无字段编辑，使用原始 yamlContent（保持向后兼容）
|
||||
return buildFinalYamlFromRaw(yamlContent, rules, decision);
|
||||
}
|
||||
|
||||
// 原 buildFinalYaml 逻辑重命名为 buildFinalYamlFromRaw
|
||||
```
|
||||
|
||||
## 7. 前端消息协议扩展
|
||||
|
||||
```typescript
|
||||
// 新增消息类型
|
||||
interface UpdateRuleMessage {
|
||||
type: 'updateRule';
|
||||
ruleId: string;
|
||||
rule: ImportableRule; // 该规则的完整最新字段值
|
||||
}
|
||||
|
||||
// confirm 消息扩展：确认时携带编辑数据
|
||||
interface ConfirmMessage {
|
||||
type: 'confirm';
|
||||
editedRules?: ImportableRule[]; // 附加全部规则的最新字段值
|
||||
}
|
||||
```
|
||||
|
||||
## 8. 文件变更清单
|
||||
|
||||
| 文件 | 操作 | 内容 |
|
||||
|------|------|------|
|
||||
| `src/rules/import-types.ts` | 修改 | `PreviewDecision` 新增 `editedRules?: ImportableRule[]` |
|
||||
| `src/rules/import-preview.ts` | 重写 | 可折叠卡片 + 展开编辑表单 + 校验 + 传递编辑数据 |
|
||||
| `src/rules/import-service.ts` | 修改 | 新增 `renderRulesToYaml`，`buildFinalYaml` 做入口判断 |
|
||||
| `src/views/setupView.ts` | 不改 | `applyConversion` 调用不变（PreviewDecision 接口向后兼容） |
|
||||
| `src/test/import-dedup.test.ts` | 修改 | 补充编辑后生成 YAML 的测试用例 |
|
||||
|
||||
## 9. 测试用例
|
||||
|
||||
追加到 `src/test/import-dedup.test.ts`：
|
||||
|
||||
| # | 用例 | 输入 | 预期 |
|
||||
|---|------|------|------|
|
||||
| 13 | 编辑 description 后确认 | rule 的 description 被修改为新值 | 最终 YAML 中该规则的 description 为新值 |
|
||||
| 14 | 编辑 severity 后确认 | rule 的 severity 从 warning 改为 error | 最终 YAML 中 severity 为 error |
|
||||
| 15 | 编辑 languages 后确认 | 添加 javascript 到 languages | 最终 YAML 含 `languages: [javascript]` |
|
||||
| 16 | 编辑后切换为注释 | 编辑字段后 toggle 为注释 | 规则被注释，注释内容为编辑后的值 |
|
||||
| 17 | 无编辑场景回退 | `editedRules` 为 undefined | 行为与当前 `buildFinalYamlFromRaw` 一致 |
|
||||
|
||||
## 10. 实施顺序
|
||||
|
||||
1. `import-types.ts` — PreviewDecision 扩展
|
||||
2. `import-service.ts` — 新增 `renderRulesToYaml`，改造 `buildFinalYaml`
|
||||
3. `import-preview.ts` — 重写 Webview（卡片展开 + 编辑表单 + 校验 + 传递编辑数据）
|
||||
4. `import-dedup.test.ts` — 补充测试
|
||||
|
||||
## 11. 设计决策记录
|
||||
|
||||
| 决策项 | 选择 | 理由 |
|
||||
|--------|------|------|
|
||||
| 编辑数据传递方式 | confirm 时携带 editedRules 数组 | 无需逐字段实时回传，减少消息往返 |
|
||||
| 无编辑时行为 | 回退到原始 yamlContent 行操作 | 保证未编辑场景零变化、零风险 |
|
||||
| languages 输入 | 标签式 chip 输入（Enter/, 添加） | 比逗号分隔文本框更直观，防格式错误 |
|
||||
| 展开方式 | 点击卡片切换展开/折叠 | 简单直接，不增加额外按钮 |
|
||||
| 保留/注释与编辑 | 共存，互不影响 | 出用户需求：保留/注释状态不影响字段编辑 |
|
||||
@@ -0,0 +1,263 @@
|
||||
# 自定义规则导入体验改进设计
|
||||
|
||||
## 背景与问题
|
||||
|
||||
当前自定义规则导入功能支持六种文件格式,其中五种(`.md` / `.txt` / `.docx` / `.xlsx` / `.pptx`)经由 AI 转换为结构化 YAML,`.yaml` / `.yml` 则直接复制落盘。转换流水线本身已跑通,但用户体验存在一个隐性断层:文件扩展名虽宽松,为了让 AI 准确识别规则字段,用户实际上仍需按某种"事实上的格式"组织内容——Excel 要表头语义化、文本要分段清晰、字段顺序要合理。格式门槛从文件扩展名转移到了内容结构上,用户不知道该怎么写,AI 转换结果也因此不稳定。
|
||||
|
||||
具体表现有两点。其一,系统提示词只规定了输出字段(id / severity / description / message 等),对输入几乎没有任何描述与容忍说明,AI 遇到松散内容时行为不可预期。其二,解析侧 `parseImportableYaml` 对必填字段采取"缺一即丢弃"的静默策略,`severity` 缺失或非法、`id` 缺失都会让整条规则消失,用户在预览面板根本看不到被丢弃的规则,无从修正。
|
||||
|
||||
## 目标
|
||||
|
||||
降低输入内容组织门槛,让 AI 能处理自然语言段落、松散列表、混合表格等各种写法;同时给用户最小化的内容指引,消除"不知道怎么组织内容"的困惑。核心字段(id / severity)由 AI 基于规则内容自动推断,解析侧提供兜底,预览阶段可人工修正。
|
||||
|
||||
## 方案概览
|
||||
|
||||
三处改动协同发挥作用:
|
||||
|
||||
1. **提示词增强** — 明确告知 AI 接受松散输入,主动推断 id 与 severity
|
||||
2. **解析侧兜底** — severity 缺失降级为 warning,id 缺失生成占位符,丢弃可见
|
||||
3. **预览与入口** — id 改可编辑,占位 id 高亮提示,导入入口加简短指引
|
||||
|
||||
设计原则是"AI 推断为主,解析兜底为底,人工预览为终"。AI 推断承担大部分场景,解析兜底保证下限不崩,预览阶段保留人工否决权。
|
||||
|
||||
## 改动一:提示词增强
|
||||
|
||||
位置:`src/rules/converters/prompt-builder.ts` 与六个转换器的 `buildSystemPrompt`。
|
||||
|
||||
当前提示词只规定了输出字段清单,对输入形态只字未提。增强内容如下。
|
||||
|
||||
### 输入容忍说明
|
||||
|
||||
在系统提示词开头增加输入形态描述,告知 AI 接受以下任一形态:
|
||||
|
||||
- 自然语言段落(一段话描述多条规则)
|
||||
- 无序列表(每条规则一行或一段)
|
||||
- 表格(列名不固定,语义可推断)
|
||||
- 混合形式(段落 + 列表 + 表格组合)
|
||||
|
||||
明确要求 AI 不得因输入形态非标准而拒绝转换,应主动从松散描述中提取规则语义。
|
||||
|
||||
### 非规则内容过滤
|
||||
|
||||
导入文件的内容不全是规则,可能混入项目介绍、背景说明、代码示例、章节标题等非规则内容。增加要求:
|
||||
|
||||
- AI 应识别并跳过非规则内容,只将真正的规则转为 YAML 条目
|
||||
- 代码示例、项目介绍等仅作为上下文帮助理解规则语义,本身不输出为规则
|
||||
- 若某段内容无法判断为规则(既无规则意图也无违反提示),直接忽略,不强行转成规则
|
||||
- 此要求与解析侧兜底呼应:即使 AI 误将非规则内容输出为条目,解析时因 description 与 message 同时缺失会被丢弃
|
||||
|
||||
### id 推断要求
|
||||
|
||||
当前提示词仅说明"id: 规则唯一标识(kebab-case 英文)",未要求 AI 主动生成。改为:
|
||||
|
||||
- 每条规则**必须**输出 `id`,基于规则描述内容自动生成
|
||||
- id 规范:kebab-case 英文、语义化、简短(如 `no-console-log`、`avoid-magic-number`、`require-error-handling`)
|
||||
- 输入中即使无显式 id 标识,也要根据 description / message 的语义推断出合适的 id
|
||||
- 多条规则间 id 不得重复
|
||||
|
||||
### severity 推断要求
|
||||
|
||||
当前提示词仅列出 severity 三档,未说明缺失时如何处理。增加:
|
||||
|
||||
- severity 必须输出,按规则语义推断:`error`(会导致 bug / 安全问题 / 数据损坏)、`warning`(潜在问题 / 不良实践)、`info`(风格 / 可读性建议)
|
||||
- 输入中即使无显式严重级别,也要根据规则描述的后果严重程度推断
|
||||
|
||||
### description / message 互推要求
|
||||
|
||||
当前提示词将 description 与 message 视为两个独立必填字段。两者本意相近:description 偏"规则是什么",message 偏"违反时说什么"。增加:
|
||||
|
||||
- 两者必须至少输出一项;若输入只暗示了规则内容而未区分"描述"与"提示",AI 应据已有信息推断并补全另一项
|
||||
- description 缺失时,由 message 反推简短描述;message 缺失时,由 description 推导违反提示
|
||||
- 两者语义可相近,无需强行区分口吻
|
||||
|
||||
### 输入输出对照示例
|
||||
|
||||
在提示词中附 2-3 个"松散输入 → 标准输出"的对照示例,锚定 AI 的行为预期。示例应覆盖不同输入形态,包括含非规则内容的混合输入:
|
||||
|
||||
```
|
||||
输入(松散段落):
|
||||
"不要用 console.log,生产环境会泄露信息。还有不要留下未使用的变量,看着乱。"
|
||||
|
||||
输出:
|
||||
- id: no-console-log
|
||||
severity: warning
|
||||
description: 禁止使用 console.log
|
||||
message: 请使用 logger 工具替代 console.log
|
||||
duplicateLevel: none
|
||||
- id: no-unused-vars
|
||||
severity: warning
|
||||
description: 禁止未使用的变量
|
||||
message: 未使用的变量应删除或注释
|
||||
duplicateOf: eslint/no-unused-vars
|
||||
duplicateLevel: exact
|
||||
```
|
||||
|
||||
```
|
||||
输入(含非规则内容的混合输入):
|
||||
"本项目是一个电商后台管理系统,主要使用 Java + Spring Boot 开发。
|
||||
代码规范要求:Service 层方法必须有日志记录,方便排查问题。
|
||||
示例代码:
|
||||
public void createOrder(Order order) { ... }
|
||||
另外,Controller 层返回值统一用 Result 包装,不要直接返回 Map。"
|
||||
|
||||
输出:
|
||||
- id: require-service-logging
|
||||
severity: warning
|
||||
description: Service 层方法必须有日志记录
|
||||
message: Service 方法缺少日志记录,请补充以便排查问题
|
||||
languages: [java]
|
||||
duplicateLevel: none
|
||||
- id: require-result-wrapper
|
||||
severity: warning
|
||||
description: Controller 返回值必须用 Result 包装
|
||||
message: 请用 Result 包装返回值,不要直接返回 Map
|
||||
languages: [java]
|
||||
duplicateLevel: none
|
||||
```
|
||||
|
||||
第二个示例中,项目介绍与代码示例均未转为规则,仅提取出两条真正的代码规范。示例的作用是让 AI 理解"一段话也能拆成多条规则"且"非规则内容应跳过",而非要求用户按此格式输入。
|
||||
|
||||
## 改动二:解析侧兜底
|
||||
|
||||
位置:`src/rules/import-service.ts` 的 `parseImportableYaml`。
|
||||
|
||||
### 当前行为
|
||||
|
||||
`parseImportableYaml` 过滤条件为 `item.id && item.severity && item.description && item.message`,缺任一即丢弃,且丢弃不可见。
|
||||
|
||||
### 新行为
|
||||
|
||||
| 字段 | 缺失或非法时 | 处理 |
|
||||
|------|-------------|------|
|
||||
| `id` | 缺失 | 生成占位 id `rule-${序号}`(rule-1、rule-2…) |
|
||||
| `severity` | 缺失或非三档之一 | 降级为 `warning` |
|
||||
| `description` / `message` | 仅一项缺失 | 用存在的那个填充缺失项(description↔message 互为兜底) |
|
||||
| `description` 与 `message` | 同时缺失 | 丢弃该条 |
|
||||
|
||||
`description` 与 `message` 本意相近,均为规则的文本表达:前者偏"规则是什么",后者偏"违反时说什么"。两者只要有一项存在,即可作为另一项的兜底来源(直接复制,或由 AI 在转换阶段据一项推断另一项);两者同时缺失,说明这段内容根本不是一条规则,丢弃合理。id 与 severity 属于"可推断字段",缺失时兜底补全而非丢弃。
|
||||
|
||||
### 丢弃无需可视化
|
||||
|
||||
被丢弃的内容因"既无 description 也无 message",本就不是规则,不属于"字段不全的规则",因此不设 `droppedCount` 字段,预览面板也不提示丢弃数。解析后的 `ImportableRule` 数组只包含确为规则的内容,预览展示与确认流程保持简洁。
|
||||
|
||||
## 改动三:预览与入口
|
||||
|
||||
位置:`src/rules/import-preview.ts`、`src/views/setupView.ts`、`src/i18n/messages.ts`。
|
||||
|
||||
### 预览面板 id 可编辑
|
||||
|
||||
当前预览面板的 id 显示为只读 `<span>`(`import-preview.ts` 的 `renderRuleCard`)。改为 `<input>` 元素:
|
||||
|
||||
- id 输入框可编辑,用户可修改 AI 生成的 id 或补充占位 id
|
||||
- 占位 id(`rule-N`)用高亮样式提示"请补充或确认"(如橙色边框 + 提示文案)
|
||||
- `collectEditedRules()` 已收集 id,无需改动收集逻辑
|
||||
|
||||
### 确认校验扩展
|
||||
|
||||
当前 `validate()` 仅校验 description 与 message 非空。扩展为:
|
||||
|
||||
- id 非空(占位 id `rule-N` 视为非空,但高亮提示用户确认)
|
||||
- description 非空
|
||||
- message 非空
|
||||
|
||||
任一为空则阻止提交,在 `validationError` 区域显示具体提示。
|
||||
|
||||
### 导入入口指引
|
||||
|
||||
`setupView.ts` 的文件选择按钮旁增加一行简短说明,告知用户:
|
||||
|
||||
- 支持自由文本:一段话、列表、表格均可
|
||||
- 每条规则尽量说清"查什么 + 违反时提示什么"
|
||||
- 不强制字段顺序和格式,id 与严重级别可由系统自动推断
|
||||
|
||||
文案走 i18n,新增对应 key。
|
||||
|
||||
## 字段处理策略总表
|
||||
|
||||
改动完成后,四个核心字段的全链路处理策略如下:
|
||||
|
||||
| 字段 | AI 推断 | 解析兜底 | 预览可编辑 | 确认校验 |
|
||||
|------|---------|---------|-----------|---------|
|
||||
| `id` | 必生成,基于内容语义 | 缺则占位 `rule-N` | 是(改为 input) | 非空 |
|
||||
| `severity` | 必输出,按语义推断 | 缺/非法→`warning` | 是(已可) | — |
|
||||
| `description` | 必输出,缺失时由 message 推 | 缺则用 message 填充 | 是(已可) | 非空 |
|
||||
| `message` | 必输出,缺失时由 description 推 | 缺则用 description 填充 | 是(已可) | 非空 |
|
||||
|
||||
`description` 与 `message` 同时缺失时丢弃该条(非规则,不提示)。`languages` / `excludeLanguages` / `duplicateOf` / `duplicateLevel` / `duplicateReason` 字段处理逻辑不变,维持现状。
|
||||
|
||||
## 改动文件清单
|
||||
|
||||
| 文件 | 改动内容 |
|
||||
|------|---------|
|
||||
| `src/rules/converters/prompt-builder.ts` | 提示词增强:输入容忍说明 + 非规则内容过滤 + id/severity 推断要求 + description/message 互推要求 + 对照示例 |
|
||||
| `src/rules/converters/md-converter.ts` | 同步 `buildSystemPrompt` 增强内容(与 prompt-builder 对齐) |
|
||||
| `src/rules/converters/txt-converter.ts` | 同上 |
|
||||
| `src/rules/converters/docx-converter.ts` | 同上 |
|
||||
| `src/rules/converters/excel-converter.ts` | 同上,表格输入说明略调 |
|
||||
| `src/rules/converters/pptx-converter.ts` | 同上 |
|
||||
| `src/rules/import-service.ts` | `parseImportableYaml` 放宽:severity 兜底、id 占位、description/message 互填 |
|
||||
| `src/rules/import-preview.ts` | id 改可编辑 input + 占位 id 高亮 + 确认校验加 id 非空 |
|
||||
| `src/views/setupView.ts` | 导入入口加简短内容指引文案 |
|
||||
| `src/i18n/messages.ts` | 新增文案 key:占位提示、指引文案 |
|
||||
|
||||
注:六个转换器的 `buildSystemPrompt` 当前各自重复了完整提示词。改动一时可考虑将公共部分抽到 `prompt-builder.ts` 统一构建,减少重复;但为控制改动范围,本次仍保持各转换器独立维护提示词,仅同步增强内容。是否抽公共函数留待实现阶段判断。
|
||||
|
||||
## 测试更新
|
||||
|
||||
### 现有测试核查
|
||||
|
||||
| 测试文件 | 核查点 |
|
||||
|---------|-------|
|
||||
| `src/test/import-dedup.test.ts` | 是否依赖"缺 id 即丢弃"的旧行为;若是,同步调整断言 |
|
||||
| `src/test/rule-filter.test.ts` | 是否依赖 severity 严格校验;`loadActiveRules` 行为不变,预期无影响 |
|
||||
|
||||
### 新增测试
|
||||
|
||||
| 测试场景 | 验证点 |
|
||||
|---------|-------|
|
||||
| severity 缺失 | 解析后降级为 `warning`,规则保留 |
|
||||
| severity 非法值 | 解析后降级为 `warning`,规则保留 |
|
||||
| id 缺失 | 解析后生成占位 id `rule-N`,规则保留 |
|
||||
| description 缺失、message 存在 | 解析后 description 由 message 填充,规则保留 |
|
||||
| message 缺失、description 存在 | 解析后 message 由 description 填充,规则保留 |
|
||||
| description 与 message 同时缺失 | 该条被丢弃(非规则) |
|
||||
| 正常完整输入 | 行为不变,无回归 |
|
||||
|
||||
## 不改动的部分
|
||||
|
||||
- 文件格式扩展名范围不变(仍六种)
|
||||
- YAML 直传路径不变(不经 AI,本就最宽松)
|
||||
- 预览 Webview 的整体布局与交互逻辑不变(仅 id 区域改动)
|
||||
- 去重检测逻辑不变(`prompt-builder.ts` 的 `buildDedupPromptSection` 不动)
|
||||
- 规则应用阶段不变(`rule-filter.ts` 的 `filterForDocument` 不动)
|
||||
|
||||
## 风险与权衡
|
||||
|
||||
### AI 推断的不确定性
|
||||
|
||||
改动一依赖 AI 行为,效果有不确定性:AI 可能生成不理想的 id(如过长、非 kebab-case、语义不准)。缓解措施:解析兜底保证下限(规则不丢失),预览阶段用户可逐条修正 id。即使 AI 推断不完美,也比"规则直接消失"好。
|
||||
|
||||
### 放宽丢弃条件的副作用
|
||||
|
||||
改动二放宽了丢弃条件,可能引入语义不完整的规则(如 id 为占位符、severity 兜底为 warning 但实际应是 error、description 与 message 文本雷同)。缓解措施:预览阶段用户仍可逐条删除/注释/修正,占位 id 高亮提示用户确认。可控。
|
||||
|
||||
### 提示词膨胀
|
||||
|
||||
六个转换器各维护一份完整提示词,改动一需同步六处,提示词长度增加。缓解措施:实现阶段评估是否抽公共函数到 `prompt-builder.ts`,若改动范围可控则保持现状。
|
||||
|
||||
### 兼容性
|
||||
|
||||
预览面板 id 改可编辑为向后兼容改动(原 `<span>` 改 `<input>`,收集逻辑已支持)。`parseImportableYaml` 放宽丢弃条件不影响现有调用方,原"完整字段才进入预览"的规则仍正常通过。
|
||||
|
||||
## 验证顺序
|
||||
|
||||
按项目规范 `lint → compile → test`:
|
||||
|
||||
1. `npm run lint` — ESLint 通过
|
||||
2. `npm run compile` — TypeScript 编译通过
|
||||
3. `npm test` — 全部测试通过,含新增测试用例
|
||||
4. F5 启动 Extension Dev Host,手动验证:
|
||||
- 导入松散文本(一段话描述多条规则),确认 AI 正确拆分并生成 id
|
||||
- 导入缺 severity 的 YAML,确认降级为 warning 且规则保留
|
||||
- 预览面板修改 id,确认可编辑
|
||||
- 确认校验阻止空 id 提交
|
||||
@@ -0,0 +1,983 @@
|
||||
# 静态分析适配器优化设计书（AI 编码用）
|
||||
|
||||
> 面向 AI 编码助手的技术实现规格。覆盖三种配置模式优先级机制、侧边栏适配器配置面板、外部依赖检测、配置文件模板生成等全部优化项。包含 TypeScript 接口定义、方法签名、文件级变更规格和实现伪代码。
|
||||
|
||||
- **项目**: vscode-code-reviewer (Code Purifier)
|
||||
- **分支**: vscode-code-reviewer
|
||||
- **日期**: 2026-07-27
|
||||
- **版本**: 1.0.1 → 1.1.0
|
||||
|
||||
---
|
||||
|
||||
## 目录
|
||||
|
||||
- [01 设计目标与范围](#01-设计目标与范围)
|
||||
- [02 现有架构分析](#02-现有架构分析)
|
||||
- [03 配置模式优先级机制](#03-配置模式优先级机制)
|
||||
- [04 数据结构设计](#04-数据结构设计)
|
||||
- [05 配置项 Schema 变更](#05-配置项-schema-变更)
|
||||
- [06 状态检测逻辑](#06-状态检测逻辑)
|
||||
- [07 侧边栏面板实现](#07-侧边栏面板实现)
|
||||
- [08 文件级变更规格](#08-文件级变更规格)
|
||||
- [09 默认配置模板](#09-默认配置模板)
|
||||
- [10 测试要点](#10-测试要点)
|
||||
|
||||
---
|
||||
|
||||
## 01 设计目标与范围
|
||||
|
||||
本次优化在不破坏现有代码审查流程的前提下，为四个静态分析适配器（ESLint、Stylelint、PMD、SQL-Lint）增加统一的三层配置模式机制，并在侧边栏设置面板中新增"静态分析适配器"可视化配置区域。用户无需查阅外部文档即可完成全部适配器配置。
|
||||
|
||||
### 优化项清单
|
||||
|
||||
| # | 优化项 | 涉及文件 | 变更类型 |
|
||||
|---|--------|----------|----------|
|
||||
| 1 | 三层配置模式优先级（全局 > 项目级 > 内置） | `config/linter.ts`、各适配器文件 | 新增逻辑 |
|
||||
| 2 | 适配器启用/禁用开关 | `package.json`、`config/linter.ts`、`orchestrator/*` | 新增配置 + 逻辑 |
|
||||
| 3 | 侧边栏适配器配置面板（4 张卡片） | `views/setupView.ts`、`views/setupView.js` | 新增 UI + 逻辑 |
|
||||
| 4 | 配置模式自动检测 | `views/setupView.ts` | 新增方法 |
|
||||
| 5 | 外部依赖检测（Java / Python+sqlfluff） | `views/setupView.ts` | 新增方法 |
|
||||
| 6 | 配置文件模板创建与打开 | `views/setupView.ts` | 新增方法 |
|
||||
| 7 | 配置变更实时刷新 | `views/setupView.ts` | 新增监听器 |
|
||||
| 8 | ESLint / Stylelint 自定义配置路径支持 | `package.json`、`config/linter.ts`、`adapters/eslint.ts`、`adapters/stylelint.ts` | 新增配置 + 逻辑 |
|
||||
|
||||
> **零破坏性原则**：所有变更均为新增或追加，不修改任何现有逻辑分支。现有的 AI 配置、规则文件导入、连接测试、代码审查命令等功能完全不受影响。适配器卡片列表由独立的 `<div id="adapter-list">` 容器渲染，即使渲染函数出错也不影响其他区域。
|
||||
|
||||
---
|
||||
|
||||
## 02 现有架构分析
|
||||
|
||||
### 源码目录结构
|
||||
|
||||
```
|
||||
src/
|
||||
├── activation/ # 插件激活逻辑
|
||||
├── adapters/ # 静态分析适配器
|
||||
│ ├── adapter.ts # 类型 re-export
|
||||
│ ├── eslint.ts # ESLint 适配器
|
||||
│ ├── stylelint.ts # Stylelint 适配器
|
||||
│ ├── pmd.ts # PMD 适配器
|
||||
│ ├── sql-lint.ts # SQL-Lint 适配器
|
||||
│ └── jsp.ts # JSP 适配器
|
||||
├── ai/ # AI 审查引擎
|
||||
├── config/ # 配置读取层
|
||||
│ ├── index.ts
|
||||
│ ├── ai.ts
|
||||
│ ├── linter.ts # ← 本次重点变更
|
||||
│ ├── fixer.ts
|
||||
│ └── secret.ts
|
||||
├── orchestrator/ # 审查编排器（调度适配器）
|
||||
├── views/
|
||||
│ ├── setupView.ts # ← 本次重点变更
|
||||
│ └── setupView.js # ← 本次重点变更
|
||||
├── panel/ # 审查结果面板
|
||||
├── types.ts # 核心类型定义
|
||||
├── extension.ts # 插件入口
|
||||
└── ...
|
||||
```
|
||||
|
||||
### 现有核心类型（src/types.ts）
|
||||
|
||||
```typescript
|
||||
import * as vscode from 'vscode';
|
||||
|
||||
export type Severity = 'error' | 'warning' | 'info';
|
||||
|
||||
export type AdapterStatus = 'ok' | 'tool-unavailable' | 'execution-failed';
|
||||
|
||||
export interface LinterDiagnostic {
|
||||
severity: Severity;
|
||||
ruleId: string;
|
||||
message: string;
|
||||
range: vscode.Range;
|
||||
suggestion?: string;
|
||||
}
|
||||
|
||||
export interface AdapterResult {
|
||||
diagnostics: LinterDiagnostic[];
|
||||
status: AdapterStatus;
|
||||
errorMessage?: string;
|
||||
}
|
||||
|
||||
export interface LinterAdapter {
|
||||
id: string;
|
||||
supportedLanguages: string[];
|
||||
check(document: vscode.TextDocument, workingDir: string): Promise<AdapterResult>;
|
||||
isAvailable(): boolean;
|
||||
}
|
||||
```
|
||||
|
||||
### 现有配置读取层（src/config/linter.ts）
|
||||
|
||||
```typescript
|
||||
import * as vscode from 'vscode';
|
||||
|
||||
const ROOT = 'vscode-code-reviewer';
|
||||
|
||||
export function getLinterForLanguage(language: string): string {
|
||||
return vscode.workspace.getConfiguration(ROOT).get<string>(`linters.${language}`, '');
|
||||
}
|
||||
|
||||
export function getPmdJarPath(): string {
|
||||
return vscode.workspace.getConfiguration(ROOT).get<string>('pmd.jarPath', '');
|
||||
}
|
||||
|
||||
export function getPmdRulesetPath(): string {
|
||||
return vscode.workspace.getConfiguration(ROOT).get<string>('pmd.rulesetPath', '');
|
||||
}
|
||||
|
||||
export function getPmdJspRulesetPath(): string {
|
||||
return vscode.workspace.getConfiguration(ROOT).get<string>('pmd.jspRulesetPath', '');
|
||||
}
|
||||
|
||||
export function getSqlLintConfigFile(): string {
|
||||
return vscode.workspace.getConfiguration(ROOT).get<string>('sql-lint.configFile', '');
|
||||
}
|
||||
```
|
||||
|
||||
### 现有 package.json 配置项（相关部分）
|
||||
|
||||
| 配置键 | 类型 | 默认值 | 说明 |
|
||||
|--------|------|--------|------|
|
||||
| `linters.javascript` | string (enum) | `"eslint"` | JS 语言的 linter 选择 |
|
||||
| `linters.typescript` | string (enum) | `"eslint"` | TS 语言的 linter 选择 |
|
||||
| `linters.java` | string (enum) | `"pmd"` | Java 语言的 linter 选择 |
|
||||
| `linters.css` | string (enum) | `"stylelint"` | CSS 语言的 linter 选择 |
|
||||
| `linters.sql` | string (enum) | `"sql-lint"` | SQL 语言的 linter 选择 |
|
||||
| `pmd.jarPath` | string | `""` | PMD jar 目录路径 |
|
||||
| `pmd.rulesetPath` | string | `""` | PMD 规则集 XML 路径 |
|
||||
| `pmd.jspRulesetPath` | string | `""` | JSP 规则集 XML 路径 |
|
||||
| `sql-lint.configFile` | string | `""` | sqlfluff 配置文件路径 |
|
||||
|
||||
> **现有缺口**：ESLint 和 Stylelint 适配器目前没有自定义配置路径的设置项（只有 `linters.javascript` 等语言级 linter 选择开关），无法通过 VS Code Settings 指定自定义 ESLint/Stylelint 配置文件路径。也没有适配器级别的启用/禁用开关。
|
||||
|
||||
---
|
||||
|
||||
## 03 配置模式优先级机制
|
||||
|
||||
每个适配器支持三种配置模式，优先级从高到低。高优先级配置存在时，低优先级配置自动忽略。
|
||||
|
||||
| 优先级 | 模式名称 | 配置来源 | 徽章标识 |
|
||||
|--------|----------|----------|----------|
|
||||
| **最高** | 全局配置（VS Code Settings） | `linters.eslintConfigPath` / `linters.stylelintConfigPath` / `pmd.rulesetPath` / `sql-lint.configFile` 等设置项 | 全局配置 |
|
||||
| **中** | 项目级配置 | 项目根目录下的配置文件（`.eslintrc.*` / `.stylelintrc.*` / `ruleset.xml` / `.sqlfluff`） | 项目配置 |
|
||||
| **最低** | 内置规则（零配置） | 插件打包的内置规则集 | 内置规则 |
|
||||
|
||||
### 各适配器的配置文件探测列表
|
||||
|
||||
`detectConfigMode()` 方法需要按以下列表在项目根目录探测文件是否存在：
|
||||
|
||||
| 适配器 | 项目级配置文件名（按探测顺序） | VS Code Settings 键 |
|
||||
|--------|-------------------------------|---------------------|
|
||||
| **ESLint** | `.eslintrc.js` → `.eslintrc.json` → `.eslintrc.yaml` → `.eslintrc.yml` → `.eslintrc` → `eslint.config.js` → `eslint.config.mjs` | `linters.eslintConfigPath` |
|
||||
| **Stylelint** | `.stylelintrc.js` → `.stylelintrc.json` → `.stylelintrc.yaml` → `.stylelintrc.yml` → `.stylelintrc` → `stylelint.config.js` | `linters.stylelintConfigPath` |
|
||||
| **PMD** | `ruleset.xml` | `pmd.rulesetPath` |
|
||||
| **SQL-Lint** | `.sqlfluff` | `sql-lint.configFile` |
|
||||
|
||||
### PMD 特殊处理：双配置项
|
||||
|
||||
PMD 适配器有两类独立配置项：**规则集（rulesetPath）**和**运行时（jarPath）**。两者独立配置，组合关系如下：
|
||||
|
||||
| jarPath | rulesetPath | 结果 |
|
||||
|---------|-------------|------|
|
||||
| 空 | 空 | 内置引擎 + 内置规则集 |
|
||||
| 空 | 有值 | 内置引擎 + 自定义规则集 |
|
||||
| 有值 | 空 | 自定义引擎 + 内置规则集 |
|
||||
| 有值 | 有值 | 自定义引擎 + 自定义规则集 |
|
||||
|
||||
> **jarPath 回退规则**：`jarPath` 指向的目录中必须存在 `PmdRunner.class` 文件，否则插件回退到内置 PMD。如果只设置了 `jarPath` 而没设置 `rulesetPath`，规则集仍使用内置的 `pmd-java-ruleset.xml`。
|
||||
|
||||
---
|
||||
|
||||
## 04 数据结构设计
|
||||
|
||||
### 新增类型定义
|
||||
|
||||
以下接口需添加到 `src/types.ts` 或 `src/views/setupView.ts` 顶部（推荐放在 setupView.ts 内部，因为仅该文件使用）：
|
||||
|
||||
```typescript
|
||||
/** 配置模式枚举 */
|
||||
export type ConfigMode = 'builtin' | 'project' | 'global';
|
||||
|
||||
/** 外部依赖就绪状态 */
|
||||
export type DependencyStatus = 'ready' | 'missing' | 'none';
|
||||
|
||||
/** 单个适配器的配置面板状态 */
|
||||
export interface AdapterConfigStatus {
|
||||
/** 适配器唯一标识 */
|
||||
id: string;
|
||||
/** 显示名称（PMD / SQL-Lint / ESLint / Stylelint） */
|
||||
name: string;
|
||||
/** 是否已启用 */
|
||||
enabled: boolean;
|
||||
/** 当前生效的配置模式 */
|
||||
configMode: ConfigMode;
|
||||
/** 外部依赖状态（ESLint/Stylelint 为 'none'） */
|
||||
dependencyStatus: DependencyStatus;
|
||||
/** 外部依赖显示文本（如 "Java"、"Python + sqlfluff"） */
|
||||
dependencyLabel?: string;
|
||||
/** 配置是否已完成（全局或项目级配置存在时为 true） */
|
||||
configured: boolean;
|
||||
/** 面板显示的操作指南文本 */
|
||||
guideText: string;
|
||||
/** 项目级配置文件名（用于"配置文件"按钮创建/打开） */
|
||||
projectConfigFileName: string;
|
||||
/** VS Code Settings 跳转目标键 */
|
||||
settingsTarget: string;
|
||||
}
|
||||
|
||||
/** 侧边栏消息：适配器操作类型 */
|
||||
export type AdapterMessageAction =
|
||||
| 'openAdapterConfig'
|
||||
| 'openSettings'
|
||||
| 'toggleAdapter';
|
||||
|
||||
/** 侧边栏消息：适配器操作载荷 */
|
||||
export interface AdapterMessage {
|
||||
action: AdapterMessageAction;
|
||||
adapterId: string;
|
||||
}
|
||||
```
|
||||
|
||||
### 适配器元数据常量表
|
||||
|
||||
在 `setupView.ts` 中定义一个静态常量表，描述四个适配器的元信息，供 `collectAdapterStatus()` 使用：
|
||||
|
||||
```typescript
|
||||
const ADAPTER_METADATA: Record<string, {
|
||||
name: string;
|
||||
projectConfigFileName: string;
|
||||
settingsTarget: string;
|
||||
guideText: string;
|
||||
hasExternalDependency: boolean;
|
||||
dependencyLabel?: string;
|
||||
configFileTemplate: string;
|
||||
}> = {
|
||||
pmd: {
|
||||
name: 'PMD',
|
||||
projectConfigFileName: 'ruleset.xml',
|
||||
settingsTarget: 'vscode-code-reviewer.pmd',
|
||||
guideText: '需要 Java 运行环境；项目根目录创建 ruleset.xml 或在设置中配置 pmd.rulesetPath',
|
||||
hasExternalDependency: true,
|
||||
dependencyLabel: 'Java',
|
||||
configFileTemplate: PMD_RULESET_TEMPLATE,
|
||||
},
|
||||
'sql-lint': {
|
||||
name: 'SQL-Lint',
|
||||
projectConfigFileName: '.sqlfluff',
|
||||
settingsTarget: 'vscode-code-reviewer.sql-lint',
|
||||
guideText: '需要 Python 环境和 sqlfluff；运行 pip install sqlfluff，项目根目录创建 .sqlfluff',
|
||||
hasExternalDependency: true,
|
||||
dependencyLabel: 'Python + sqlfluff',
|
||||
configFileTemplate: SQLFLUFF_TEMPLATE,
|
||||
},
|
||||
eslint: {
|
||||
name: 'ESLint',
|
||||
projectConfigFileName: '.eslintrc.js',
|
||||
settingsTarget: 'vscode-code-reviewer.linters',
|
||||
guideText: '项目根目录创建 .eslintrc.js 或在 VS Code 设置中配置 eslintConfigPath',
|
||||
hasExternalDependency: false,
|
||||
configFileTemplate: ESLINT_TEMPLATE,
|
||||
},
|
||||
stylelint: {
|
||||
name: 'Stylelint',
|
||||
projectConfigFileName: '.stylelintrc.js',
|
||||
settingsTarget: 'vscode-code-reviewer.linters',
|
||||
guideText: '项目根目录创建 .stylelintrc 或在 VS Code 设置中配置 stylelintConfigPath',
|
||||
hasExternalDependency: false,
|
||||
configFileTemplate: STYLELINT_TEMPLATE,
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 05 配置项 Schema 变更
|
||||
|
||||
### package.json — 新增配置项
|
||||
|
||||
在 `contributes.configuration.properties` 中追加以下配置项：
|
||||
|
||||
```jsonc
|
||||
// ESLint 自定义配置路径
|
||||
"vscode-code-reviewer.linters.eslintConfigPath": {
|
||||
"type": "string",
|
||||
"default": "",
|
||||
"description": "ESLint 自定义配置文件路径（绝对路径）。留空则使用项目 .eslintrc 或内置规则"
|
||||
}
|
||||
|
||||
// Stylelint 自定义配置路径
|
||||
"vscode-code-reviewer.linters.stylelintConfigPath": {
|
||||
"type": "string",
|
||||
"default": "",
|
||||
"description": "Stylelint 自定义配置文件路径（绝对路径）。留空则使用项目 .stylelintrc 或内置规则"
|
||||
}
|
||||
|
||||
// 适配器启用/禁用开关（4 项）
|
||||
"vscode-code-reviewer.linter.pmd.enabled": {
|
||||
"type": "boolean",
|
||||
"default": true,
|
||||
"description": "启用/禁用 PMD 适配器"
|
||||
}
|
||||
"vscode-code-reviewer.linter.sql-lint.enabled": {
|
||||
"type": "boolean",
|
||||
"default": true,
|
||||
"description": "启用/禁用 SQL-Lint 适配器"
|
||||
}
|
||||
"vscode-code-reviewer.linter.eslint.enabled": {
|
||||
"type": "boolean",
|
||||
"default": true,
|
||||
"description": "启用/禁用 ESLint 适配器"
|
||||
}
|
||||
"vscode-code-reviewer.linter.stylelint.enabled": {
|
||||
"type": "boolean",
|
||||
"default": true,
|
||||
"description": "启用/禁用 Stylelint 适配器"
|
||||
}
|
||||
```
|
||||
|
||||
> **命名空间注意**：现有配置使用 `linters.*`（复数）作为语言级 linter 选择，`pmd.*` / `sql-lint.*` 作为各适配器的独立配置。新增的启用/禁用开关统一放在 `linter.*`（单数）命名空间下，避免与现有 `linters.*` 冲突。ESLint 和 Stylelint 的自定义配置路径放在 `linters.*` 下，与现有 `linters.javascript` 等保持同级。
|
||||
|
||||
### config/linter.ts — 新增读取函数
|
||||
|
||||
```typescript
|
||||
/** 获取 ESLint 自定义配置路径 */
|
||||
export function getEslintConfigPath(): string {
|
||||
return vscode.workspace.getConfiguration(ROOT).get<string>('linters.eslintConfigPath', '');
|
||||
}
|
||||
|
||||
/** 获取 Stylelint 自定义配置路径 */
|
||||
export function getStylelintConfigPath(): string {
|
||||
return vscode.workspace.getConfiguration(ROOT).get<string>('linters.stylelintConfigPath', '');
|
||||
}
|
||||
|
||||
/** 获取适配器启用状态 */
|
||||
export function isAdapterEnabled(adapterId: string): boolean {
|
||||
return vscode.workspace.getConfiguration(ROOT).get<boolean>(`linter.${adapterId}.enabled`, true);
|
||||
}
|
||||
|
||||
/** 设置适配器启用状态（写入 Global Settings） */
|
||||
export async function setAdapterEnabled(adapterId: string, enabled: boolean): Promise<void> {
|
||||
await vscode.workspace.getConfiguration(ROOT).update(
|
||||
`linter.${adapterId}.enabled`,
|
||||
enabled,
|
||||
vscode.ConfigurationTarget.Global
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
### 适配器集成：启用/禁用检查
|
||||
|
||||
在 `orchestrator/` 中调度适配器前，需检查该适配器是否已启用。在调用 `adapter.check()` 之前添加守卫：
|
||||
|
||||
```typescript
|
||||
import { isAdapterEnabled } from '../config/linter';
|
||||
|
||||
// 在 orchestrator 的适配器调度循环中
|
||||
for (const adapter of adapters) {
|
||||
if (!isAdapterEnabled(adapter.id)) {
|
||||
continue; // 跳过已禁用的适配器
|
||||
}
|
||||
if (!adapter.isAvailable()) {
|
||||
continue; // 跳过不可用的适配器
|
||||
}
|
||||
const result = await adapter.check(document, workingDir);
|
||||
// ... 处理结果
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 06 状态检测逻辑
|
||||
|
||||
### detectConfigMode() — 配置模式检测
|
||||
|
||||
该方法检测指定适配器当前生效的配置模式。优先检查全局配置，其次项目级配置，最后回退到内置。
|
||||
|
||||
```typescript
|
||||
import * as path from 'path';
|
||||
import * as fs from 'fs';
|
||||
import * as vscode from 'vscode';
|
||||
import { getEslintConfigPath, getStylelintConfigPath, getPmdRulesetPath, getSqlLintConfigFile }
|
||||
from '../config/linter';
|
||||
|
||||
/** 各适配器项目级配置文件探测列表 */
|
||||
const PROJECT_CONFIG_FILES: Record<string, string[]> = {
|
||||
eslint: ['.eslintrc.js', '.eslintrc.json', '.eslintrc.yaml', '.eslintrc.yml', '.eslintrc', 'eslint.config.js', 'eslint.config.mjs'],
|
||||
stylelint: ['.stylelintrc.js', '.stylelintrc.json', '.stylelintrc.yaml', '.stylelintrc.yml', '.stylelintrc', 'stylelint.config.js'],
|
||||
pmd: ['ruleset.xml'],
|
||||
'sql-lint': ['.sqlfluff'],
|
||||
};
|
||||
|
||||
/** 各适配器全局配置路径读取函数 */
|
||||
const GLOBAL_CONFIG_GETTERS: Record<string, () => string> = {
|
||||
eslint: getEslintConfigPath,
|
||||
stylelint: getStylelintConfigPath,
|
||||
pmd: getPmdRulesetPath,
|
||||
'sql-lint': getSqlLintConfigFile,
|
||||
};
|
||||
|
||||
function detectConfigMode(adapterId: string): ConfigMode {
|
||||
// 1. 检查全局配置（VS Code Settings）
|
||||
const globalPath = GLOBAL_CONFIG_GETTERS[adapterId]?.();
|
||||
if (globalPath && globalPath.trim() !== '') {
|
||||
return 'global';
|
||||
}
|
||||
|
||||
// 2. 检查项目级配置文件
|
||||
const workspaceFolders = vscode.workspace.workspaceFolders;
|
||||
if (workspaceFolders && workspaceFolders.length > 0) {
|
||||
const rootPath = workspaceFolders[0].uri.fsPath;
|
||||
const configFiles = PROJECT_CONFIG_FILES[adapterId] ?? [];
|
||||
for (const fileName of configFiles) {
|
||||
const filePath = path.join(rootPath, fileName);
|
||||
if (fs.existsSync(filePath)) {
|
||||
return 'project';
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// 3. 回退到内置
|
||||
return 'builtin';
|
||||
}
|
||||
```
|
||||
|
||||
### checkJavaReady() — Java 环境检测
|
||||
|
||||
通过执行 `java -version` 检测 Java 运行环境是否可用。使用 `child_process.execSync` 同步执行，捕获 stderr 输出（Java 版本信息输出到 stderr）。
|
||||
|
||||
```typescript
|
||||
import { execSync } from 'child_process';
|
||||
|
||||
function checkJavaReady(): boolean {
|
||||
try {
|
||||
const output = execSync('java -version', {
|
||||
encoding: 'utf-8',
|
||||
timeout: 5000,
|
||||
stdio: ['pipe', 'pipe', 'pipe'],
|
||||
});
|
||||
return true;
|
||||
} catch {
|
||||
// java -version 输出到 stderr，execSync 会因非零退出码抛错
|
||||
// 但即使版本信息在 stderr 中，只要命令存在就算就绪
|
||||
try {
|
||||
const result = execSync('java -version 2>&1', {
|
||||
encoding: 'utf-8',
|
||||
timeout: 5000,
|
||||
});
|
||||
return result.includes('version');
|
||||
} catch {
|
||||
return false;
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### checkPythonReady() — Python + sqlfluff 检测
|
||||
|
||||
先检测 Python（尝试 `python3` 和 `python`），再检测 `sqlfluff` 命令是否可用。
|
||||
|
||||
```typescript
|
||||
function checkPythonReady(): boolean {
|
||||
// 1. 检测 Python
|
||||
let pythonCmd = '';
|
||||
for (const cmd of ['python3', 'python']) {
|
||||
try {
|
||||
execSync(`${cmd} --version`, { encoding: 'utf-8', timeout: 5000, stdio: 'pipe' });
|
||||
pythonCmd = cmd;
|
||||
break;
|
||||
} catch { continue; }
|
||||
}
|
||||
if (!pythonCmd) return false;
|
||||
|
||||
// 2. 检测 sqlfluff
|
||||
try {
|
||||
execSync('sqlfluff --version', { encoding: 'utf-8', timeout: 5000, stdio: 'pipe' });
|
||||
return true;
|
||||
} catch {
|
||||
return false;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
> **依赖检测注意事项**：依赖检测仅验证运行环境是否存在，不验证具体版本。`java -version` 能正常输出即判定为就绪，但不检查是否满足 Java 8+ 要求。检测操作使用 `execSync` 同步执行，需设置 5 秒超时防止卡死。检测结果需缓存，避免每次刷新面板都执行命令行检测（建议在 `collectAdapterStatus()` 中缓存，配置变更时重新检测）。
|
||||
|
||||
### collectAdapterStatus() — 汇总适配器状态
|
||||
|
||||
遍历 `ADAPTER_METADATA`，调用上述检测方法，组装 `AdapterConfigStatus[]` 数组。
|
||||
|
||||
```typescript
|
||||
function collectAdapterStatus(): AdapterConfigStatus[] {
|
||||
const statuses: AdapterConfigStatus[] = [];
|
||||
|
||||
for (const [id, meta] of Object.entries(ADAPTER_METADATA)) {
|
||||
const configMode = detectConfigMode(id);
|
||||
const enabled = isAdapterEnabled(id);
|
||||
|
||||
let dependencyStatus: DependencyStatus = 'none';
|
||||
if (meta.hasExternalDependency) {
|
||||
if (id === 'pmd') {
|
||||
dependencyStatus = checkJavaReady() ? 'ready' : 'missing';
|
||||
} else if (id === 'sql-lint') {
|
||||
dependencyStatus = checkPythonReady() ? 'ready' : 'missing';
|
||||
}
|
||||
}
|
||||
|
||||
const configured = configMode !== 'builtin' || !meta.hasExternalDependency;
|
||||
|
||||
statuses.push({
|
||||
id,
|
||||
name: meta.name,
|
||||
enabled,
|
||||
configMode,
|
||||
dependencyStatus,
|
||||
dependencyLabel: meta.dependencyLabel,
|
||||
configured,
|
||||
guideText: meta.guideText,
|
||||
projectConfigFileName: meta.projectConfigFileName,
|
||||
settingsTarget: meta.settingsTarget,
|
||||
});
|
||||
}
|
||||
|
||||
return statuses;
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 07 侧边栏面板实现
|
||||
|
||||
### 面板位置
|
||||
|
||||
新增区域位于侧边栏中**"审核引擎"区域之后、"AI 模型配置"区域之前**。视线流程为：快速开始引导 → 引擎状态总览 → **适配器配置引导（本节）** → AI 模型配置 → 规则文件管理。
|
||||
|
||||
### setupView.ts — pushConfig() 变更
|
||||
|
||||
在 `pushConfig()` 方法中追加 `adapterStatus` 字段，将采集的适配器状态推送到前端：
|
||||
|
||||
```typescript
|
||||
private pushConfig() {
|
||||
// ... 现有配置推送逻辑保持不变 ...
|
||||
|
||||
// 追加适配器状态
|
||||
const adapterStatus = this.collectAdapterStatus();
|
||||
this.view?.webview.postMessage({
|
||||
type: 'initConfig',
|
||||
// ... 现有字段 ...
|
||||
adapterStatus,
|
||||
});
|
||||
}
|
||||
```
|
||||
|
||||
### setupView.ts — onDidReceiveMessage 新增消息处理
|
||||
|
||||
在 `resolveWebviewView` 的 `onDidReceiveMessage` 回调中，新增三个 case：
|
||||
|
||||
```typescript
|
||||
this.view.webview.onDidReceiveMessage(async (message) => {
|
||||
switch (message.type) {
|
||||
// ... 现有 case 保持不变 ...
|
||||
|
||||
case 'openAdapterConfig': {
|
||||
await this.handleAdapterConfig(message.adapterId);
|
||||
break;
|
||||
}
|
||||
|
||||
case 'openSettings': {
|
||||
await vscode.commands.executeCommand(
|
||||
'workbench.action.openSettings',
|
||||
message.settingsTarget
|
||||
);
|
||||
break;
|
||||
}
|
||||
|
||||
case 'toggleAdapter': {
|
||||
await setAdapterEnabled(message.adapterId, message.enabled);
|
||||
// 配置变更后 pushConfig 会由 onDidChangeConfiguration 触发
|
||||
break;
|
||||
}
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
### handleAdapterConfig() — 配置文件创建/打开
|
||||
|
||||
```typescript
|
||||
private async handleAdapterConfig(adapterId: string) {
|
||||
const meta = ADAPTER_METADATA[adapterId];
|
||||
if (!meta) return;
|
||||
|
||||
const workspaceFolders = vscode.workspace.workspaceFolders;
|
||||
if (!workspaceFolders || workspaceFolders.length === 0) {
|
||||
vscode.window.showWarningMessage('请先打开一个工作区文件夹');
|
||||
return;
|
||||
}
|
||||
|
||||
const rootPath = workspaceFolders[0].uri.fsPath;
|
||||
const filePath = path.join(rootPath, meta.projectConfigFileName);
|
||||
|
||||
if (!fs.existsSync(filePath)) {
|
||||
// 文件不存在 → 创建默认模板
|
||||
fs.writeFileSync(filePath, meta.configFileTemplate, 'utf-8');
|
||||
vscode.window.showInformationMessage(`配置文件已创建: ${meta.projectConfigFileName}`);
|
||||
}
|
||||
|
||||
// 打开文件
|
||||
const doc = await vscode.workspace.openTextDocument(filePath);
|
||||
await vscode.window.showTextDocument(doc);
|
||||
}
|
||||
```
|
||||
|
||||
### resolveWebviewView — 配置变更监听
|
||||
|
||||
在 `resolveWebviewView` 方法中注册 `onDidChangeConfiguration` 监听器，当 `vscode-code-reviewer.linter` 或 `vscode-code-reviewer.linters` 或 `vscode-code-reviewer.pmd` 或 `vscode-code-reviewer.sql-lint` 命名空间下的配置变更时，触发 `pushConfig()` 刷新：
|
||||
|
||||
```typescript
|
||||
resolveWebviewView(view: vscode.WebviewView) {
|
||||
this.view = view;
|
||||
// ... 现有初始化逻辑 ...
|
||||
|
||||
// 新增：配置变更监听
|
||||
const configChangeDisposable = vscode.workspace.onDidChangeConfiguration((e) => {
|
||||
if (
|
||||
e.affectsConfiguration('vscode-code-reviewer.linter') ||
|
||||
e.affectsConfiguration('vscode-code-reviewer.linters') ||
|
||||
e.affectsConfiguration('vscode-code-reviewer.pmd') ||
|
||||
e.affectsConfiguration('vscode-code-reviewer.sql-lint')
|
||||
) {
|
||||
this.pushConfig();
|
||||
}
|
||||
});
|
||||
|
||||
// 随 webview 销毁自动清理
|
||||
view.onDidDispose(() => {
|
||||
configChangeDisposable.dispose();
|
||||
});
|
||||
}
|
||||
```
|
||||
|
||||
### setupView.ts — getHtml() 模板变更
|
||||
|
||||
在 `getHtml()` 方法返回的 HTML 模板中，在"审核引擎"区域和"AI 模型配置"区域之间插入以下 HTML：
|
||||
|
||||
```html
|
||||
<!-- 适配器配置面板 -->
|
||||
<div class="section adapter-section-panel">
|
||||
<h3 class="section-title">静态分析适配器</h3>
|
||||
<div id="adapter-list"></div>
|
||||
</div>
|
||||
```
|
||||
|
||||
同时在 `<style>` 块中追加适配器卡片样式（约 55 行 CSS）：
|
||||
|
||||
```css
|
||||
/* 适配器卡片 */
|
||||
.adapter-card {
|
||||
background: var(--bg2);
|
||||
border: 1px solid var(--rule);
|
||||
border-radius: 8px;
|
||||
padding: 12px;
|
||||
margin-bottom: 8px;
|
||||
transition: opacity 0.2s;
|
||||
}
|
||||
.adapter-card.disabled { opacity: 0.45; }
|
||||
.adapter-card-header {
|
||||
display: flex; align-items: center; justify-content: space-between;
|
||||
margin-bottom: 6px;
|
||||
}
|
||||
.adapter-card-name { font-size: 12px; font-weight: 600; color: #ccc; }
|
||||
.adapter-toggle {
|
||||
width: 30px; height: 16px; border-radius: 8px;
|
||||
background: #3fb950; position: relative; cursor: pointer;
|
||||
transition: background 0.2s;
|
||||
}
|
||||
.adapter-toggle.off { background: #3c3c3c; }
|
||||
.adapter-toggle::after {
|
||||
content: ''; position: absolute; top: 2px; left: 2px;
|
||||
width: 12px; height: 12px; border-radius: 50%; background: #fff;
|
||||
transition: transform 0.2s;
|
||||
transform: translateX(14px);
|
||||
}
|
||||
.adapter-toggle.off::after { transform: translateX(0); background: #ccc; }
|
||||
.adapter-badges { display: flex; gap: 4px; flex-wrap: wrap; margin-bottom: 5px; }
|
||||
.adapter-badge {
|
||||
display: inline-flex; align-items: center; padding: 1px 5px;
|
||||
border-radius: 3px; font-size: 9px; font-weight: 600;
|
||||
font-family: var(--font-mono);
|
||||
}
|
||||
.adapter-badge-info { background: rgba(139,92,246,0.15); color: #8b5cf6; }
|
||||
.adapter-badge-ok { background: rgba(63,185,80,0.15); color: #3fb950; }
|
||||
.adapter-badge-warn { background: rgba(210,153,34,0.15); color: #d29922; }
|
||||
.adapter-badge-error { background: rgba(248,81,73,0.15); color: #f48771; }
|
||||
.adapter-guide { font-size: 10px; color: #9d9d9d; line-height: 1.4; margin-bottom: 7px; }
|
||||
.adapter-actions { display: flex; gap: 5px; }
|
||||
.adapter-btn {
|
||||
padding: 2px 8px; border-radius: 3px; font-size: 10px;
|
||||
border: 1px solid #3c3c3c; background: transparent; color: #ccc;
|
||||
cursor: pointer; font-family: var(--font);
|
||||
}
|
||||
.adapter-btn:hover { background: var(--bg3); }
|
||||
```
|
||||
|
||||
### setupView.js — renderAdapters() 前端渲染函数
|
||||
|
||||
在 `setupView.js` 中新增 `renderAdapters()` 函数，接收 `adapterStatus` 数组并渲染卡片 HTML：
|
||||
|
||||
```javascript
|
||||
function renderAdapters(adapterStatus) {
|
||||
const container = document.getElementById('adapter-list');
|
||||
if (!container || !adapterStatus) return;
|
||||
|
||||
const modeBadgeMap = {
|
||||
builtin: { class: 'adapter-badge-info', text: '内置规则' },
|
||||
project: { class: 'adapter-badge-ok', text: '项目配置' },
|
||||
global: { class: 'adapter-badge-warn', text: '全局配置' },
|
||||
};
|
||||
|
||||
const html = adapterStatus.map(a => {
|
||||
const modeBadge = modeBadgeMap[a.configMode];
|
||||
const depBadge = a.dependencyStatus === 'none' ? '' :
|
||||
a.dependencyStatus === 'ready'
|
||||
? `<span class="adapter-badge adapter-badge-ok">${a.dependencyLabel} ✓</span>`
|
||||
: `<span class="adapter-badge adapter-badge-error">${a.dependencyLabel} ✗</span>`;
|
||||
const configBadge = a.configured
|
||||
? '<span class="adapter-badge adapter-badge-ok">已配置</span>'
|
||||
: '<span class="adapter-badge adapter-badge-warn">未配置</span>';
|
||||
|
||||
return `
|
||||
<div class="adapter-card ${a.enabled ? '' : 'disabled'}">
|
||||
<div class="adapter-card-header">
|
||||
<span class="adapter-card-name">${a.name}</span>
|
||||
<div class="adapter-toggle ${a.enabled ? '' : 'off'}"
|
||||
data-adapter-id="${a.id}"></div>
|
||||
</div>
|
||||
<div class="adapter-badges">
|
||||
<span class="adapter-badge ${modeBadge.class}">${modeBadge.text}</span>
|
||||
${depBadge}
|
||||
${configBadge}
|
||||
</div>
|
||||
<div class="adapter-guide">${a.guideText}</div>
|
||||
<div class="adapter-actions">
|
||||
<button class="adapter-btn" data-action="openAdapterConfig"
|
||||
data-adapter-id="${a.id}">配置文件</button>
|
||||
<button class="adapter-btn" data-action="openSettings"
|
||||
data-settings-target="${a.settingsTarget}">VS Code 设置</button>
|
||||
</div>
|
||||
</div>
|
||||
`;
|
||||
}).join('');
|
||||
|
||||
container.innerHTML = html;
|
||||
|
||||
// 绑定事件
|
||||
container.querySelectorAll('.adapter-toggle').forEach(el => {
|
||||
el.addEventListener('click', () => {
|
||||
const adapterId = el.dataset.adapterId;
|
||||
const isEnabled = !el.classList.contains('off');
|
||||
vscode.postMessage({
|
||||
type: 'toggleAdapter',
|
||||
adapterId,
|
||||
enabled: !isEnabled,
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
container.querySelectorAll('.adapter-btn').forEach(el => {
|
||||
el.addEventListener('click', () => {
|
||||
const action = el.dataset.action;
|
||||
const adapterId = el.dataset.adapterId;
|
||||
const settingsTarget = el.dataset.settingsTarget;
|
||||
if (action === 'openAdapterConfig') {
|
||||
vscode.postMessage({ type: 'openAdapterConfig', adapterId });
|
||||
} else if (action === 'openSettings') {
|
||||
vscode.postMessage({ type: 'openSettings', settingsTarget });
|
||||
}
|
||||
});
|
||||
});
|
||||
}
|
||||
|
||||
// 在 initConfig 消息处理中调用
|
||||
window.addEventListener('message', event => {
|
||||
const message = event.data;
|
||||
if (message.type === 'initConfig') {
|
||||
// ... 现有初始化逻辑 ...
|
||||
renderAdapters(message.adapterStatus);
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 08 文件级变更规格
|
||||
|
||||
### [MODIFY] package.json
|
||||
|
||||
**范围**: `configuration.properties`
|
||||
|
||||
在 `contributes.configuration.properties` 对象中追加 6 个新配置项：
|
||||
|
||||
- `linters.eslintConfigPath` — ESLint 自定义配置路径（string, default: ""）
|
||||
- `linters.stylelintConfigPath` — Stylelint 自定义配置路径（string, default: ""）
|
||||
- `linter.pmd.enabled` — PMD 启用开关（boolean, default: true）
|
||||
- `linter.sql-lint.enabled` — SQL-Lint 启用开关（boolean, default: true）
|
||||
- `linter.eslint.enabled` — ESLint 启用开关（boolean, default: true）
|
||||
- `linter.stylelint.enabled` — Stylelint 启用开关（boolean, default: true）
|
||||
|
||||
不修改任何现有配置项。版本号从 `1.0.1` 升至 `1.1.0`。
|
||||
|
||||
### [MODIFY] src/config/linter.ts
|
||||
|
||||
**范围**: 新增 4 个导出函数
|
||||
|
||||
- `getEslintConfigPath(): string` — 读取 `linters.eslintConfigPath`
|
||||
- `getStylelintConfigPath(): string` — 读取 `linters.stylelintConfigPath`
|
||||
- `isAdapterEnabled(adapterId: string): boolean` — 读取 `linter.{adapterId}.enabled`
|
||||
- `setAdapterEnabled(adapterId: string, enabled: boolean): Promise<void>` — 写入 Global Settings
|
||||
|
||||
不修改任何现有函数。新增函数追加在文件末尾。
|
||||
|
||||
### [MODIFY] src/views/setupView.ts
|
||||
|
||||
**范围**: `SetupViewProvider` 类
|
||||
|
||||
变更内容（全部为新增或追加）：
|
||||
|
||||
| 变更位置 | 变更内容 |
|
||||
|----------|----------|
|
||||
| 文件顶部 | 新增 `import` 语句（path、fs、execSync、linter 配置函数） |
|
||||
| 类外部 | 新增 `ConfigMode`、`DependencyStatus`、`AdapterConfigStatus` 类型定义 |
|
||||
| 类外部 | 新增 `ADAPTER_METADATA` 常量表 |
|
||||
| 类外部 | 新增 `PROJECT_CONFIG_FILES` 和 `GLOBAL_CONFIG_GETTERS` 常量 |
|
||||
| 类内部 — 新增方法 | `detectConfigMode(adapterId): ConfigMode` |
|
||||
| 类内部 — 新增方法 | `checkJavaReady(): boolean` |
|
||||
| 类内部 — 新增方法 | `checkPythonReady(): boolean` |
|
||||
| 类内部 — 新增方法 | `collectAdapterStatus(): AdapterConfigStatus[]` |
|
||||
| 类内部 — 新增方法 | `handleAdapterConfig(adapterId: string): Promise<void>` |
|
||||
| 类内部 — 修改方法 | `pushConfig()` 追加 `adapterStatus` 字段到 postMessage |
|
||||
| 类内部 — 修改方法 | `resolveWebviewView()` 的 `onDidReceiveMessage` 新增 `openAdapterConfig` / `openSettings` / `toggleAdapter` 三个 case |
|
||||
| 类内部 — 修改方法 | `resolveWebviewView()` 新增 `onDidChangeConfiguration` 监听器 |
|
||||
| 类内部 — 修改方法 | `getHtml()` 模板新增 HTML（`<div id="adapter-list">`）和 CSS（约 55 行样式） |
|
||||
|
||||
### [MODIFY] src/views/setupView.js
|
||||
|
||||
**范围**: 前端脚本
|
||||
|
||||
- 新增 `renderAdapters(adapterStatus)` 函数
|
||||
- 在 `initConfig` 消息处理回调中追加 `renderAdapters(message.adapterStatus)` 调用
|
||||
|
||||
不修改任何现有函数的逻辑分支。
|
||||
|
||||
### [MODIFY] src/adapters/eslint.ts
|
||||
|
||||
**范围**: `ESLintAdapter` 类
|
||||
|
||||
在 `check()` 方法中，优先使用 `getEslintConfigPath()` 返回的自定义配置路径。如果为空，再检测项目根目录的 `.eslintrc.*` 文件。如果两者都不存在，使用内置 `eslint:recommended` 规则集。
|
||||
|
||||
### [MODIFY] src/adapters/stylelint.ts
|
||||
|
||||
**范围**: `StylelintAdapter` 类
|
||||
|
||||
同 ESLint，在 `check()` 方法中优先使用 `getStylelintConfigPath()` 返回的自定义配置路径。如果为空，再检测项目根目录的 `.stylelintrc.*` 文件。如果两者都不存在，使用内置 11 条默认规则。
|
||||
|
||||
### [MODIFY] src/orchestrator/*
|
||||
|
||||
**范围**: 审查编排器
|
||||
|
||||
在适配器调度循环中，调用 `adapter.check()` 之前新增 `isAdapterEnabled(adapter.id)` 守卫，跳过已禁用的适配器。
|
||||
|
||||
---
|
||||
|
||||
## 09 默认配置模板
|
||||
|
||||
点击"配置文件"按钮时，如果项目根目录尚不存在对应配置文件，插件自动创建以下默认模板并打开。模板内容作为字符串常量定义在 `setupView.ts` 中。
|
||||
|
||||
### PMD 默认模板（ruleset.xml）
|
||||
|
||||
```typescript
|
||||
const PMD_RULESET_TEMPLATE = `<?xml version="1.0" encoding="UTF-8"?>
|
||||
<ruleset xmlns="http://pmd.sourceforge.net/ruleset/2.0.0"
|
||||
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
|
||||
xsi:schemaLocation="http://pmd.sourceforge.net/ruleset/2.0.0 https://pmd.sourceforge.io/ruleset_2_0_0.xsd">
|
||||
<description>Custom PMD Ruleset</description>
|
||||
<rule ref="category/java/bestpractices.xml" />
|
||||
<rule ref="category/java/codestyle.xml" />
|
||||
</ruleset>`;
|
||||
```
|
||||
|
||||
### SQL-Lint 默认模板（.sqlfluff）
|
||||
|
||||
```typescript
|
||||
const SQLFLUFF_TEMPLATE = `[sqlfluff]
|
||||
dialect = postgres
|
||||
rules = all`;
|
||||
```
|
||||
|
||||
### ESLint 默认模板（.eslintrc.js）
|
||||
|
||||
```typescript
|
||||
const ESLINT_TEMPLATE = `module.exports = {
|
||||
root: true,
|
||||
env: { node: true, es2022: true },
|
||||
parserOptions: { ecmaVersion: 2022, sourceType: 'module' },
|
||||
rules: {
|
||||
'no-unused-vars': 'warn',
|
||||
'no-console': 'off',
|
||||
'semi': ['error', 'always'],
|
||||
},
|
||||
};`;
|
||||
```
|
||||
|
||||
### Stylelint 默认模板（.stylelintrc.js）
|
||||
|
||||
```typescript
|
||||
const STYLELINT_TEMPLATE = `module.exports = {
|
||||
extends: 'stylelint-config-standard',
|
||||
rules: {
|
||||
'indentation': 2,
|
||||
'no-empty': true,
|
||||
},
|
||||
};`;
|
||||
```
|
||||
|
||||
> **文件存在时不覆盖**：如果项目根目录已存在对应配置文件，点击"配置文件"按钮会直接打开该文件，不会覆盖已有内容。创建新文件时会弹出 `showInformationMessage` 通知提示"配置文件已创建"。
|
||||
|
||||
---
|
||||
|
||||
## 10 测试要点
|
||||
|
||||
### 配置模式检测测试
|
||||
|
||||
| 测试场景 | 前置条件 | 期望结果 |
|
||||
|----------|----------|----------|
|
||||
| 全局配置优先 | Settings 中 `eslintConfigPath` 有值 + 项目根有 `.eslintrc.js` | `detectConfigMode('eslint')` 返回 `'global'` |
|
||||
| 项目配置次之 | Settings 中 `eslintConfigPath` 为空 + 项目根有 `.eslintrc.json` | 返回 `'project'` |
|
||||
| 内置回退 | Settings 为空 + 项目根无配置文件 | 返回 `'builtin'` |
|
||||
| PMD 双配置组合 | `jarPath` 有值但目录无 `PmdRunner.class` | 回退到内置引擎 |
|
||||
|
||||
### 外部依赖检测测试
|
||||
|
||||
| 测试场景 | 期望结果 |
|
||||
|----------|----------|
|
||||
| Java 已安装（`java -version` 正常输出） | `checkJavaReady()` 返回 `true` |
|
||||
| Java 未安装（命令不存在） | 返回 `false` |
|
||||
| Python3 + sqlfluff 均已安装 | `checkPythonReady()` 返回 `true` |
|
||||
| Python 已安装但 sqlfluff 未安装 | 返回 `false` |
|
||||
| 仅 python（无 python3）+ sqlfluff 已安装 | 返回 `true` |
|
||||
|
||||
### 侧边栏面板交互测试
|
||||
|
||||
| 测试场景 | 操作步骤 | 期望结果 |
|
||||
|----------|----------|----------|
|
||||
| 切换适配器开关 | 点击 PMD 卡片的开关 | 卡片变半透明 + `linter.pmd.enabled` 写入 `false` + 代码审查时 PMD 被跳过 |
|
||||
| 创建配置文件 | 点击 ESLint 的"配置文件"按钮（项目根无 .eslintrc.js） | 项目根创建 `.eslintrc.js` + 文件在编辑器中打开 + 弹出通知 |
|
||||
| 打开已有配置文件 | 点击 Stylelint 的"配置文件"按钮（项目根已有 .stylelintrc.js） | 直接打开文件，不覆盖内容 |
|
||||
| 跳转 VS Code 设置 | 点击 SQL-Lint 的"VS Code 设置"按钮 | VS Code 设置面板打开，定位到 `vscode-code-reviewer.sql-lint` |
|
||||
| 配置变更实时刷新 | 在 VS Code 设置面板修改 `pmd.rulesetPath` | 侧边栏 PMD 卡片徽章自动更新为"全局配置" |
|
||||
|
||||
### 零破坏性回归测试
|
||||
|
||||
> **回归验证清单**：以下功能在本次变更后必须仍然正常工作：AI 代码审查命令（`Ctrl+Shift+R`）、选中代码审查、审查结果面板导出、自定义规则管理、AI 模型配置与连接测试、规则文件导入。适配器卡片渲染失败时不应影响侧边栏其他区域的正常显示。
|
||||
|
||||
---
|
||||
|
||||
*本设计书基于 vscode-code-reviewer 插件 vscode-code-reviewer 分支（v1.0.1）编写，覆盖静态分析适配器三层配置模式机制和侧边栏适配器配置面板的全部技术实现规格。AI 编码助手应按第 08 节文件级变更规格逐文件实施，以第 04-06 节的数据结构和检测逻辑为实现依据。*
|
||||
@@ -0,0 +1,174 @@
|
||||
# 适配器面板 UI + 配置文件模板 i18n 设计书
|
||||
|
||||
> - **项目**: vscode-code-reviewer
|
||||
> - **日期**: 2026-07-28
|
||||
> - **设计范围**: 适配器面板 UI 文本 + 配置文件模板注释的国际化接入
|
||||
|
||||
---
|
||||
|
||||
## 01 问题
|
||||
|
||||
适配器优化引入的新 UI 文本和配置文件模板注释为硬编码中文，未走 `t()` 通路，英文/日语用户看到的是中文文本。
|
||||
|
||||
涉及范围：
|
||||
1. **`setupView.ts`** HTML 模板中 3 处硬编码（tooltip、图例、子标题）
|
||||
2. **`setupView.js`** 前端渲染中 ~8 处硬编码（徽章、按钮、标签、tooltip）
|
||||
3. **`setupView.ts`** 配置文件模板常量中 ~9 处中文注释
|
||||
|
||||
---
|
||||
|
||||
## 02 方案
|
||||
|
||||
### 2.1 数据流
|
||||
|
||||
```
|
||||
用户切换语言 → pushConfig() 发送 initConfig 消息
|
||||
├─ 已有字段：config, providers, ruleFiles, adapterStatus
|
||||
└─ 新增字段：i18n（包含前端需要的全部翻译文本）
|
||||
|
||||
setupView.js 从 msg.i18n.* 读取文本，不再硬编码
|
||||
```
|
||||
|
||||
### 2.2 setupView.ts HTML 模板变更
|
||||
|
||||
直接在 `getHtml()` 模板字符串中将硬编码文本替换为 `${t('key')}`，与现有 pattern 一致。
|
||||
|
||||
涉及键：
|
||||
| 位置 | 当前文本 | i18n 键 |
|
||||
|------|---------|---------|
|
||||
| `data-tooltip` | 点击展开/收起静态分析适配器 | `setup.adapter.tooltipTab` |
|
||||
| `.engine-subtitle` | 静态分析适配器 | `setup.adapter.subtitle` |
|
||||
| `.mode-legend-item` 图例 x3 | 内置规则 / 项目配置 / 全局配置 | `setup.adapter.modeBuiltin` / `modeProject` / `modeGlobal` |
|
||||
| `.mode-legend-desc` | 插件按 内置<全局<项目的优先级... | `setup.adapter.modeLegend` |
|
||||
|
||||
### 2.3 setupView.js 前端变更
|
||||
|
||||
`pushConfig()` 在 `initConfig` 消息中新增 `i18n` 对象：
|
||||
|
||||
```typescript
|
||||
// pushConfig() 中
|
||||
this._view.webview.postMessage({
|
||||
type: 'initConfig',
|
||||
// ... 现有字段 ...
|
||||
i18n: {
|
||||
configured: t('setup.configured'),
|
||||
notConfigured: t('setup.notConfigured'),
|
||||
connected: t('setup.connected'),
|
||||
retry: t('setup.retry'),
|
||||
saveTest: t('setup.saveAndTest'),
|
||||
ruleCount: t('setup.ruleCountFormat'),
|
||||
noRuleFiles: t('setup.noRuleFiles'),
|
||||
// 适配器相关
|
||||
modeBuiltin: t('setup.adapter.modeBuiltin'),
|
||||
modeProject: t('setup.adapter.modeProject'),
|
||||
modeGlobal: t('setup.adapter.modeGlobal'),
|
||||
configYes: t('setup.adapter.configYes'),
|
||||
configNo: t('setup.adapter.configNo'),
|
||||
langLabel: t('setup.adapter.langLabel'),
|
||||
btnCreateConfig: t('setup.adapter.btnCreateConfig'),
|
||||
btnEditGlobal: t('setup.adapter.btnEditGlobal'),
|
||||
tooltipCreatePrefix: t('setup.adapter.tooltipCreate'),
|
||||
tooltipEdit: t('setup.adapter.tooltipEdit'),
|
||||
tooltipToggleEnable: t('setup.adapter.toggleEnable'),
|
||||
tooltipToggleDisable: t('setup.adapter.toggleDisable'),
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
`setupView.js` 中所有 `'硬编码文本'` 替换为 `msg.i18n.xxx`。
|
||||
|
||||
### 2.4 配置文件模板变更
|
||||
|
||||
四个模板常量从静态字符串改为**运行时函数**，使用 `t()` 生成注释：
|
||||
|
||||
```typescript
|
||||
function getPmdRulesetTemplate(): string {
|
||||
return `<?xml version="1.0" encoding="UTF-8"?>
|
||||
<ruleset ...>
|
||||
<description>Custom PMD Ruleset</description>
|
||||
<!-- ${t('setup.template.pmdBestPractices')} -->
|
||||
<rule ref="category/java/bestpractices.xml" />
|
||||
<!-- ${t('setup.template.pmdCodeStyle')} -->
|
||||
<rule ref="category/java/codestyle.xml" />
|
||||
</ruleset>`;
|
||||
}
|
||||
```
|
||||
|
||||
`ADAPTER_METADATA` 中的 `configFileTemplate` 改为 getter 函数（`() => string`），`handleAdapterConfig()` 在写入时调用。
|
||||
|
||||
### 2.5 修复已有硬编码
|
||||
|
||||
顺便修复 `setupView.js` 中已有的硬编码字符串：
|
||||
|
||||
| 行 | 当前文本 | i18n 键 |
|
||||
|----|---------|---------|
|
||||
| 131, 136 | '已配置' / '未配置' | `setup.configured` / `setup.notConfigured` (已存在) |
|
||||
| 142 | '✓ 已连接' | `setup.connected` |
|
||||
| 144 | '✗ 重试' | `setup.retry` |
|
||||
| 146 | '保存并测试连接' | `setup.saveAndTest` (已存在) |
|
||||
| 153 | '{n} 个文件' | `setup.ruleCountFormat` |
|
||||
| 161 | '0 个文件' | 同上 |
|
||||
| 163 | '暂无规则文件' | `setup.noRuleFiles` |
|
||||
|
||||
---
|
||||
|
||||
## 03 新增 i18n 键清单
|
||||
|
||||
### 面板 UI（约12条）
|
||||
|
||||
| 键 | zh-CN | en | ja |
|
||||
|---|-------|----|----|
|
||||
| `setup.configured` | 已配置 | Configured | 設定済み |
|
||||
| `setup.connected` | ✓ 已连接 | ✓ Connected | ✓ 接続済み |
|
||||
| `setup.retry` | ✗ 重试 | ✗ Retry | ✗ 再試行 |
|
||||
| `setup.ruleCountFormat` | {0} 个文件 | {0} file(s) | {0} ファイル |
|
||||
| `setup.noRuleFiles` | 暂无规则文件 | No rule files | ルールファイルなし |
|
||||
| `setup.adapter.subtitle` | 静态分析适配器 | Static Analysis Adapters | 静的解析アダプター |
|
||||
| `setup.adapter.modeBuiltin` | 内置规则 | Built-in Rules | 組み込みルール |
|
||||
| `setup.adapter.modeProject` | 项目配置 | Project Config | プロジェクト設定 |
|
||||
| `setup.adapter.modeGlobal` | 全局配置 | Global Config | グローバル設定 |
|
||||
| `setup.adapter.modeLegend` | 插件按 内置<全局<项目的优先级自动选择配置来源 | Auto-selects config by priority: Built-in < Global < Project | 優先順位に従って自動選択: 組み込み < グローバル < プロジェクト |
|
||||
| `setup.adapter.configYes` | 已配置 | Configured | 設定済み |
|
||||
| `setup.adapter.configNo` | 未配置 | Not configured | 未設定 |
|
||||
| `setup.adapter.langLabel` | 可审查的语言： | Languages: | 対応言語： |
|
||||
| `setup.adapter.tooltipTab` | 点击展开/收起静态分析适配器 | Click to expand/collapse static analysis adapters | クリックで静的解析アダプターを展開/折りたたむ |
|
||||
| `setup.adapter.btnCreateConfig` | 创建项目配置 | Create Project Config | プロジェクト設定を作成 |
|
||||
| `setup.adapter.btnEditGlobal` | 修改全局设置 | Modify Global Settings | グローバル設定を変更 |
|
||||
| `setup.adapter.tooltipCreate` | 在项目根目录创建 {0} | Create {0} in project root | プロジェクトルートに {0} を作成 |
|
||||
| `setup.adapter.tooltipEdit` | 修改 VS Code 设置中的全局参数 | Modify global parameters in VS Code settings | VS Code設定のグローバルパラメータを変更 |
|
||||
| `setup.adapter.toggleEnable` | 启用 {0} 适配器 | Enable {0} adapter | {0} アダプターを有効化 |
|
||||
| `setup.adapter.toggleDisable` | 禁用 {0} 适配器 | Disable {0} adapter | {0} アダプターを無効化 |
|
||||
|
||||
### 模板注释（约6条）
|
||||
|
||||
| 键 | zh-CN | en | ja |
|
||||
|---|-------|----|----|
|
||||
| `setup.template.pmdBestPractices` | Java 最佳实践（如：避免空 catch、关闭流等） | Java best practices (avoid empty catch, close streams, etc.) | Javaベストプラクティス（空のcatch回避、ストリームクローズ等） |
|
||||
| `setup.template.pmdCodeStyle` | Java 代码风格（如：命名规范、花括号位置等） | Java code style (naming conventions, brace placement, etc.) | Javaコードスタイル（命名規則、ブレース位置等） |
|
||||
| `setup.template.sqlfluffDialect` | 数据库方言：postgres / mysql / bigquery / snowflake 等 | Database dialect: postgres / mysql / bigquery / snowflake etc. | データベース方言：postgres / mysql / bigquery / snowflake など |
|
||||
| `setup.template.sqlfluffRules` | all = 启用全部规则，也可指定规则名逗号分隔 | all = enable all rules, or specify rule names separated by commas | all = すべてのルールを有効、ルール名をカンマ区切りで指定可 |
|
||||
| `setup.template.eslintComment1` | 未使用的变量 → 警告 | Unused variables → warning | 未使用変数 → 警告 |
|
||||
| `setup.template.eslintComment2` | 允许使用 console | Allow console | consoleを許可 |
|
||||
| `setup.template.eslintComment3` | 强制分号 | Enforce semicolons | セミコロンを強制 |
|
||||
| `setup.template.stylelintComment1` | 缩进 2 空格 | Indentation: 2 spaces | インデント: 2スペース |
|
||||
| `setup.template.stylelintComment2` | 禁止空规则 | No empty rules | 空ルールを禁止 |
|
||||
|
||||
---
|
||||
|
||||
## 04 文件变更清单
|
||||
|
||||
| 文件 | 变更类型 | 说明 |
|
||||
|------|---------|------|
|
||||
| `src/i18n/messages.ts` | 修改 | 新增 ~28 条 i18n 键（面板 UI + 模板注释） |
|
||||
| `src/views/setupView.ts` | 修改 | HTML 模板硬编码替换为 `t()`；模板常量改为函数 |
|
||||
| `src/views/setupView.js` | 修改 | 从 `msg.i18n` 读取文本替换全篇硬编码字符串 |
|
||||
|
||||
零破坏性原则：不修改任何现有 i18n 键，不修改现有逻辑分支，不修改 HTML 结构/JS 事件绑定逻辑。
|
||||
|
||||
---
|
||||
|
||||
## 05 风险与注意事项
|
||||
|
||||
- `ADAPTER_METADATA` 中 `configFileTemplate` 的类型从 `string` 改为 `() => string`，调用方 `handleAdapterConfig()` 需相应调整
|
||||
- 部分键与已有键重复（如 `setup.configured` / `setup.notConfigured`），需确认是否复用现有 `setup.notConfigured`
|
||||
- 模板中 XML/JS 注释 `<!-- -->` / `//` / `#` 本身不翻译，仅注释内容翻译
|
||||
@@ -0,0 +1,855 @@
|
||||
# AI 供应商与模型动态化设计书
|
||||
|
||||
> 将写死的供应商注册表外置为 JSON 配置文件，模型下拉框改为可编辑输入框，并修复 `package.json` 不一致问题。
|
||||
|
||||
- **项目**: vscode-code-reviewer (Code Purifier)
|
||||
- **分支**: vscode-code-reviewer
|
||||
- **日期**: 2026-07-28
|
||||
- **版本**: 1.1.0 → 1.2.0
|
||||
|
||||
---
|
||||
|
||||
## 目录
|
||||
|
||||
- [01 问题分析](#01-问题分析)
|
||||
- [02 设计目标与范围](#02-设计目标与范围)
|
||||
- [03 方案 A：模型输入框可编辑化](#03-方案-a模型输入框可编辑化)
|
||||
- [04 方案 B：供应商注册表外置化](#04-方案-b供应商注册表外置化)
|
||||
- [05 修复 package.json 不一致](#05-修复-packagejson-不一致)
|
||||
- [06 数据结构设计](#06-数据结构设计)
|
||||
- [07 注册表加载器实现](#07-注册表加载器实现)
|
||||
- [08 工厂函数改造](#08-工厂函数改造)
|
||||
- [09 侧边栏面板改造](#09-侧边栏面板改造)
|
||||
- [10 文件级变更规格](#10-文件级变更规格)
|
||||
- [11 迁移路径](#11-迁移路径)
|
||||
- [12 测试要点](#12-测试要点)
|
||||
|
||||
---
|
||||
|
||||
## 01 问题分析
|
||||
|
||||
当前 `src/ai/factory.ts` 中的 `registry` 是一个纯静态对象，硬编码了 8 个供应商及其模型列表。这种写法在大模型快速迭代的环境下存在三类问题。
|
||||
|
||||
### 1.1 模型列表过期
|
||||
|
||||
`factory.ts` 中的模型列表是编码时手写的快照，一旦供应商发布新模型或下线旧模型，插件无法感知。用户只能使用列表中预置的模型名，即使供应商 API 已经支持新模型，也必须等插件发版后才能选用。
|
||||
|
||||
### 1.2 默认值不一致
|
||||
|
||||
| 位置 | 内容 | 问题 |
|
||||
|------|------|------|
|
||||
| `package.json` 第 92-96 行 | `ai.provider` enum 仅有 `deepseek`、`openai` | 工厂注册了 8 个供应商，但配置 schema 只声明了 2 个 |
|
||||
| `package.json` 第 100 行 | 默认模型 `deepseek-chat` | `factory.ts` 中 DeepSeek 的模型列表为 `deepseek-v4-pro`、`deepseek-v4-flash`，不包含 `deepseek-chat` |
|
||||
|
||||
用户首次安装后，默认模型在下拉框中找不到对应项，`populateModelOptions()` 会回退到列表第一个模型，导致实际使用的模型与配置中记录的不一致。
|
||||
|
||||
### 1.3 无法使用列表外模型
|
||||
|
||||
`setupView.ts` 中模型选择是 `<select>` 元素，只能从预置列表中选择。如果用户想使用新发布的模型、供应商列表中不存在的 OpenAI 兼容服务（如本地 Ollama、vLLM 部署），无法手动输入模型名。
|
||||
|
||||
---
|
||||
|
||||
## 02 设计目标与范围
|
||||
|
||||
### 优化项清单
|
||||
|
||||
| # | 优化项 | 方案 | 涉及文件 | 变更类型 |
|
||||
|---|--------|------|----------|----------|
|
||||
| 1 | 模型选择改为可编辑输入框 | A | `views/setupView.ts`、`views/setupView.js` | 修改 UI + 逻辑 |
|
||||
| 2 | 供应商注册表外置为 JSON | B | 新增 `providers.json`、`ai/registry.ts` | 新增文件 |
|
||||
| 3 | 工厂函数改为动态加载 | B | `ai/factory.ts` | 重构 |
|
||||
| 4 | 支持用户自定义供应商覆盖 | B | `ai/registry.ts` | 新增逻辑 |
|
||||
| 5 | 修复 `package.json` 不一致 | 附加 | `package.json` | 修改 schema |
|
||||
|
||||
### 零破坏性原则
|
||||
|
||||
所有变更不改变 AI 审查引擎的消费侧接口。`engine.ts` 调用 `createProvider()` 和 `getAIModel()` 的方式不变，`runAIReview()` 的逻辑分支不受影响。现有用户的配置（provider、model、baseUrl、apiKey）在升级后自动保留，无需重新配置。
|
||||
|
||||
---
|
||||
|
||||
## 03 方案 A：模型输入框可编辑化
|
||||
|
||||
### 现状
|
||||
|
||||
`setupView.ts` 第 889-891 行渲染模型选择器：
|
||||
|
||||
```html
|
||||
<select id="modelSelect">${(providers[config.provider]?.models ?? []).map(m =>
|
||||
`<option value="${m}"${config.model === m ? ' selected' : ''}>${m}</option>`
|
||||
).join('\n ')}</select>
|
||||
```
|
||||
|
||||
`setupView.js` 第 88-102 行的 `populateModelOptions()` 向 `<select>` 填充 `<option>`：
|
||||
|
||||
```javascript
|
||||
function populateModelOptions(providerId, selectModel) {
|
||||
var modelSelect = document.getElementById('modelSelect');
|
||||
if (!modelSelect) { return; }
|
||||
var models = (PROVIDERS[providerId] && PROVIDERS[providerId].models) || [];
|
||||
modelSelect.innerHTML = '';
|
||||
for (var i = 0; i < models.length; i++) {
|
||||
var opt = document.createElement('option');
|
||||
opt.value = models[i];
|
||||
opt.textContent = models[i];
|
||||
modelSelect.appendChild(opt);
|
||||
}
|
||||
if (models.length > 0) {
|
||||
modelSelect.value = selectModel && models.indexOf(selectModel) !== -1 ? selectModel : models[0];
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 改造方案
|
||||
|
||||
将 `<select>` 替换为 `<input type="text" list="...">` + `<datalist>`。`datalist` 提供预置建议列表，同时允许用户手动输入任意模型名。
|
||||
|
||||
#### HTML 变更（setupView.ts `getHtml()`）
|
||||
|
||||
```html
|
||||
<div class="field">
|
||||
<label class="field-label">${t('setup.model')}</label>
|
||||
<input type="text" id="modelInput" list="modelOptions"
|
||||
value="${config.model || ''}"
|
||||
placeholder="${t('setup.modelPlaceholder')}"
|
||||
onchange="postMsg('setModel', this.value)">
|
||||
<datalist id="modelOptions">
|
||||
${(providers[config.provider]?.models ?? []).map(m =>
|
||||
`<option value="${m}">`
|
||||
).join('\n ')}
|
||||
</datalist>
|
||||
</div>
|
||||
```
|
||||
|
||||
#### JS 变更（setupView.js `populateModelOptions()`）
|
||||
|
||||
```javascript
|
||||
function populateModelOptions(providerId, currentModel) {
|
||||
var datalist = document.getElementById('modelOptions');
|
||||
var input = document.getElementById('modelInput');
|
||||
if (!datalist || !input) { return; }
|
||||
|
||||
var models = (PROVIDERS[providerId] && PROVIDERS[providerId].models) || [];
|
||||
|
||||
// 刷新 datalist 选项
|
||||
datalist.innerHTML = '';
|
||||
for (var i = 0; i < models.length; i++) {
|
||||
var opt = document.createElement('option');
|
||||
opt.value = models[i];
|
||||
datalist.appendChild(opt);
|
||||
}
|
||||
|
||||
// 保留用户已输入的模型名，仅当为空时填入第一个建议
|
||||
if (!input.value && models.length > 0) {
|
||||
input.value = models[0];
|
||||
postMsg('setModel', models[0]);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 事件绑定变更
|
||||
|
||||
`setupView.js` 第 109-111 行原来监听 `modelSelect` 的 `change` 事件，改为监听 `modelInput`：
|
||||
|
||||
```javascript
|
||||
document.getElementById('modelInput').addEventListener('change', function () {
|
||||
postMsg('setModel', this.value.trim());
|
||||
});
|
||||
```
|
||||
|
||||
#### initConfig 消息处理变更
|
||||
|
||||
`setupView.js` 第 143-147 行原来调用 `populateModelOptions(c.provider, c.model)` 并设置 `select.value`。改为直接设置 `input.value`：
|
||||
|
||||
```javascript
|
||||
if (c.provider && PROVIDERS[c.provider]) {
|
||||
populateModelOptions(c.provider, c.model);
|
||||
var mi = document.getElementById('modelInput');
|
||||
if (mi && c.model) { mi.value = c.model; }
|
||||
var ps = document.getElementById('providerSelect');
|
||||
if (ps) { ps.value = c.provider; }
|
||||
}
|
||||
```
|
||||
|
||||
### 新增国际化键
|
||||
|
||||
| 键 | zh-CN | en | ja |
|
||||
|----|-------|-----|-----|
|
||||
| `setup.modelPlaceholder` | 输入或选择模型名 | Enter or select model name | モデル名を入力または選択 |
|
||||
|
||||
---
|
||||
|
||||
## 04 方案 B：供应商注册表外置化
|
||||
|
||||
### 整体架构
|
||||
|
||||
```
|
||||
插件内置 providers.json（随 VSIX 打包）
|
||||
↓
|
||||
registry.ts 加载并解析
|
||||
↓
|
||||
用户工作区 .code-review/providers.json（可选覆盖）
|
||||
↓
|
||||
合并后的 ProviderConfig[] 供 factory.ts 和 setupView.ts 消费
|
||||
```
|
||||
|
||||
### providers.json 格式
|
||||
|
||||
```json
|
||||
{
|
||||
"providers": [
|
||||
{
|
||||
"id": "deepseek",
|
||||
"name": "DeepSeek",
|
||||
"protocol": "openai-compatible",
|
||||
"defaultBaseUrl": "https://api.deepseek.com/v1",
|
||||
"models": ["deepseek-chat", "deepseek-reasoner"]
|
||||
},
|
||||
{
|
||||
"id": "openai",
|
||||
"name": "OpenAI",
|
||||
"protocol": "openai-compatible",
|
||||
"defaultBaseUrl": "https://api.openai.com/v1",
|
||||
"models": ["gpt-4o", "gpt-4o-mini", "gpt-4-turbo"]
|
||||
},
|
||||
{
|
||||
"id": "gemini",
|
||||
"name": "Google Gemini",
|
||||
"protocol": "gemini",
|
||||
"defaultBaseUrl": "https://generativelanguage.googleapis.com/v1",
|
||||
"models": ["gemini-2.0-flash", "gemini-1.5-pro"]
|
||||
},
|
||||
{
|
||||
"id": "claude",
|
||||
"name": "Anthropic Claude",
|
||||
"protocol": "claude",
|
||||
"defaultBaseUrl": "https://api.anthropic.com/v1",
|
||||
"models": ["claude-sonnet-4-20250514", "claude-opus-4-20250514"]
|
||||
},
|
||||
{
|
||||
"id": "hunyuan",
|
||||
"name": "腾讯混元",
|
||||
"protocol": "openai-compatible",
|
||||
"defaultBaseUrl": "https://api.hunyuan.cloud.tencent.com/v1",
|
||||
"models": ["hunyuan-pro"]
|
||||
},
|
||||
{
|
||||
"id": "zhipu",
|
||||
"name": "智谱AI",
|
||||
"protocol": "openai-compatible",
|
||||
"defaultBaseUrl": "https://open.bigmodel.cn/api/paas/v4",
|
||||
"models": ["glm-4-plus", "glm-4-flash"]
|
||||
},
|
||||
{
|
||||
"id": "moonshot",
|
||||
"name": "月之暗面",
|
||||
"protocol": "openai-compatible",
|
||||
"defaultBaseUrl": "https://api.moonshot.cn/v1",
|
||||
"models": ["moonshot-v1-8k", "moonshot-v1-32k"]
|
||||
},
|
||||
{
|
||||
"id": "tongyi",
|
||||
"name": "阿里通义",
|
||||
"protocol": "openai-compatible",
|
||||
"defaultBaseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1",
|
||||
"models": ["qwen-plus", "qwen-turbo"]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### 字段说明
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| `id` | string | 是 | 供应商唯一标识，用于配置存储和工厂查找 |
|
||||
| `name` | string | 是 | 显示名称，出现在侧边栏下拉框 |
|
||||
| `protocol` | string | 是 | 协议类型，决定实例化哪个 Provider 类。可选值：`openai-compatible`、`gemini`、`claude` |
|
||||
| `defaultBaseUrl` | string | 是 | 该供应商的默认 API 端点 |
|
||||
| `models` | string[] | 是 | 预置模型列表，作为 datalist 建议项。用户可输入列表外的模型名 |
|
||||
|
||||
### 用户覆盖机制
|
||||
|
||||
用户可在工作区根目录的 `.code-review/providers.json` 中放置同名文件，格式与内置文件一致。加载器按以下规则合并：
|
||||
|
||||
| 情况 | 合并结果 |
|
||||
|------|----------|
|
||||
| 用户文件包含内置中已有的供应商（id 相同） | 用户配置完整覆盖该供应商的所有字段 |
|
||||
| 用户文件包含内置中没有的供应商 | 追加为新供应商 |
|
||||
| 用户文件缺少内置中的某供应商 | 保留内置的该供应商 |
|
||||
|
||||
示例：用户想添加本地 Ollama 服务，在工作区放置 `.code-review/providers.json`：
|
||||
|
||||
```json
|
||||
{
|
||||
"providers": [
|
||||
{
|
||||
"id": "ollama",
|
||||
"name": "Ollama (本地)",
|
||||
"protocol": "openai-compatible",
|
||||
"defaultBaseUrl": "http://localhost:11434/v1",
|
||||
"models": ["llama3.1", "qwen2.5"]
|
||||
},
|
||||
{
|
||||
"id": "deepseek",
|
||||
"name": "DeepSeek (自定义代理)",
|
||||
"protocol": "openai-compatible",
|
||||
"defaultBaseUrl": "https://my-proxy.example.com/v1",
|
||||
"models": ["deepseek-chat", "deepseek-coder"]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
合并后：`ollama` 作为新供应商追加，`deepseek` 的 name/baseUrl/models 被用户配置完整覆盖，其余 6 个内置供应商保留。
|
||||
|
||||
---
|
||||
|
||||
## 05 修复 package.json 不一致
|
||||
|
||||
### `ai.provider` 配置项
|
||||
|
||||
去掉 `enum` 限制，改为自由 string，因为供应商列表现在是动态的：
|
||||
|
||||
```jsonc
|
||||
"vscode-code-reviewer.ai.provider": {
|
||||
"type": "string",
|
||||
"default": "deepseek",
|
||||
"description": "AI 模型提供商"
|
||||
}
|
||||
```
|
||||
|
||||
#### `ai.model` 配置项
|
||||
|
||||
去掉 `enum` 限制（如果有），保持为自由 string：
|
||||
|
||||
```jsonc
|
||||
"vscode-code-reviewer.ai.model": {
|
||||
"type": "string",
|
||||
"default": "deepseek-chat",
|
||||
"description": "AI 模型名称"
|
||||
}
|
||||
```
|
||||
|
||||
> 默认模型保持 `deepseek-chat`，与内置 `providers.json` 中 DeepSeek 的第一个模型对齐。用户升级后如果之前未手动改过模型，会自动匹配到列表中的建议项。
|
||||
|
||||
---
|
||||
|
||||
## 06 数据结构设计
|
||||
|
||||
### ProviderConfig 接口
|
||||
|
||||
```typescript
|
||||
export type ProviderProtocol = 'openai-compatible' | 'gemini' | 'claude';
|
||||
|
||||
export interface ProviderConfig {
|
||||
id: string;
|
||||
name: string;
|
||||
protocol: ProviderProtocol;
|
||||
defaultBaseUrl: string;
|
||||
models: string[];
|
||||
}
|
||||
|
||||
export interface ProvidersFile {
|
||||
providers: ProviderConfig[];
|
||||
}
|
||||
```
|
||||
|
||||
### ProviderMeta 接口（供 UI 消费）
|
||||
|
||||
```typescript
|
||||
export interface ProviderMeta {
|
||||
name: string;
|
||||
models: string[];
|
||||
}
|
||||
```
|
||||
|
||||
`getAllProviderMeta()` 的返回类型保持 `Record<string, ProviderMeta>`，与现有结构一致。
|
||||
|
||||
---
|
||||
|
||||
## 07 注册表加载器实现
|
||||
|
||||
### 新建文件：`src/ai/registry.ts`
|
||||
|
||||
```typescript
|
||||
import * as vscode from 'vscode';
|
||||
import * as fs from 'fs';
|
||||
import * as path from 'path';
|
||||
import type { ProviderConfig, ProvidersFile, ProviderMeta } from './types';
|
||||
|
||||
let cachedProviders: ProviderConfig[] | null = null;
|
||||
|
||||
/** 读取插件内置的 providers.json */
|
||||
function loadBuiltinProviders(extensionUri: vscode.Uri): ProviderConfig[] {
|
||||
const filePath = vscode.Uri.joinPath(extensionUri, 'providers.json').fsPath;
|
||||
try {
|
||||
const raw = fs.readFileSync(filePath, 'utf-8');
|
||||
const data = JSON.parse(raw) as ProvidersFile;
|
||||
return data.providers ?? [];
|
||||
} catch {
|
||||
return [];
|
||||
}
|
||||
}
|
||||
|
||||
/** 读取用户工作区的 .code-review/providers.json */
|
||||
function loadUserProviders(): ProviderConfig[] {
|
||||
const workspaceRoot = vscode.workspace.workspaceFolders?.[0]?.uri.fsPath;
|
||||
if (!workspaceRoot) { return []; }
|
||||
|
||||
const filePath = path.join(workspaceRoot, '.code-review', 'providers.json');
|
||||
if (!fs.existsSync(filePath)) { return []; }
|
||||
|
||||
try {
|
||||
const raw = fs.readFileSync(filePath, 'utf-8');
|
||||
const data = JSON.parse(raw) as ProvidersFile;
|
||||
return data.providers ?? [];
|
||||
} catch {
|
||||
return [];
|
||||
}
|
||||
}
|
||||
|
||||
/** 合并内置与用户配置：用户配置按 id 覆盖内置 */
|
||||
function mergeProviders(
|
||||
builtin: ProviderConfig[],
|
||||
user: ProviderConfig[]
|
||||
): ProviderConfig[] {
|
||||
const map = new Map<string, ProviderConfig>();
|
||||
|
||||
for (const p of builtin) {
|
||||
map.set(p.id, p);
|
||||
}
|
||||
|
||||
for (const p of user) {
|
||||
map.set(p.id, p);
|
||||
}
|
||||
|
||||
return Array.from(map.values());
|
||||
}
|
||||
|
||||
/**
|
||||
* 获取合并后的供应商列表。
|
||||
* 首次调用时加载并缓存，后续调用直接返回缓存。
|
||||
* extensionUri 仅首次调用时需要传入。
|
||||
*/
|
||||
export function getProviders(extensionUri?: vscode.Uri): ProviderConfig[] {
|
||||
if (cachedProviders) { return cachedProviders; }
|
||||
|
||||
if (!extensionUri) {
|
||||
return [];
|
||||
}
|
||||
|
||||
const builtin = loadBuiltinProviders(extensionUri);
|
||||
const user = loadUserProviders();
|
||||
cachedProviders = mergeProviders(builtin, user);
|
||||
return cachedProviders;
|
||||
}
|
||||
|
||||
/** 清除缓存，强制下次调用时重新加载 */
|
||||
export function invalidateProviderCache(): void {
|
||||
cachedProviders = null;
|
||||
}
|
||||
|
||||
/** 按 id 查找单个供应商 */
|
||||
export function getProviderById(
|
||||
extensionUri: vscode.Uri,
|
||||
id: string
|
||||
): ProviderConfig | undefined {
|
||||
return getProviders(extensionUri).find(p => p.id === id);
|
||||
}
|
||||
|
||||
/** 获取所有供应商的 UI 元数据 */
|
||||
export function getAllProviderMeta(
|
||||
extensionUri: vscode.Uri
|
||||
): Record<string, ProviderMeta> {
|
||||
const result: Record<string, ProviderMeta> = {};
|
||||
for (const p of getProviders(extensionUri)) {
|
||||
result[p.id] = {
|
||||
name: p.name,
|
||||
models: p.models,
|
||||
};
|
||||
}
|
||||
return result;
|
||||
}
|
||||
```
|
||||
|
||||
### 缓存失效策略
|
||||
|
||||
在 `setupView.ts` 的 `resolveWebviewView()` 中注册文件系统监听器，当用户编辑 `.code-review/providers.json` 后自动刷新：
|
||||
|
||||
```typescript
|
||||
const watcher = vscode.workspace.createFileSystemWatcher(
|
||||
'**/.code-review/providers.json'
|
||||
);
|
||||
|
||||
watcher.onDidChange(() => {
|
||||
invalidateProviderCache();
|
||||
this.pushConfig();
|
||||
});
|
||||
|
||||
watcher.onDidCreate(() => {
|
||||
invalidateProviderCache();
|
||||
this.pushConfig();
|
||||
});
|
||||
|
||||
webviewView.onDidDispose(() => {
|
||||
watcher.dispose();
|
||||
});
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 08 工厂函数改造
|
||||
|
||||
### 现状
|
||||
|
||||
`factory.ts` 中的 `registry` 是静态对象，每个供应商的 `cls` 字段直接引用具体类。`createProvider()` 通过 `new info.cls(apiKey, baseUrl)` 实例化。
|
||||
|
||||
### 改造方案
|
||||
|
||||
`factory.ts` 不再持有静态注册表，改为从 `registry.ts` 动态加载。`protocol` 字段决定实例化哪个类。
|
||||
|
||||
### 改造后的 factory.ts
|
||||
|
||||
```typescript
|
||||
import * as vscode from 'vscode';
|
||||
import type { AIProvider } from './providers/base';
|
||||
import type { ProviderConfig, ProviderMeta, ProviderProtocol } from './types';
|
||||
import { OpenAICompatibleProvider } from './providers/openai-compatible';
|
||||
import { GeminiProvider } from './providers/gemini';
|
||||
import { ClaudeProvider } from './providers/claude';
|
||||
import {
|
||||
getProviders,
|
||||
getProviderById,
|
||||
getAllProviderMeta as getAllProviderMetaFromRegistry,
|
||||
invalidateProviderCache,
|
||||
} from './registry';
|
||||
|
||||
const PROTOCOL_MAP: Record<ProviderProtocol,
|
||||
new (apiKey: string, baseUrl: string, id: string, name: string) => any
|
||||
> = {
|
||||
'openai-compatible': OpenAICompatibleProvider,
|
||||
gemini: GeminiProvider,
|
||||
claude: ClaudeProvider,
|
||||
};
|
||||
|
||||
export function createProvider(
|
||||
providerId: string,
|
||||
apiKey: string,
|
||||
baseUrl: string,
|
||||
extensionUri: vscode.Uri
|
||||
): AIProvider {
|
||||
const config = getProviderById(extensionUri, providerId);
|
||||
if (!config) {
|
||||
throw new Error(`未知的 Provider: ${providerId}`);
|
||||
}
|
||||
|
||||
const Cls = PROTOCOL_MAP[config.protocol];
|
||||
if (!Cls) {
|
||||
throw new Error(`未知的协议类型: ${config.protocol}`);
|
||||
}
|
||||
|
||||
if (config.protocol === 'openai-compatible') {
|
||||
return new Cls(apiKey, baseUrl, config.id, config.name);
|
||||
}
|
||||
return new Cls(apiKey, baseUrl);
|
||||
}
|
||||
|
||||
export function getProviderModels(extensionUri: vscode.Uri, providerId: string): string[] {
|
||||
return getProviderById(extensionUri, providerId)?.models ?? [];
|
||||
}
|
||||
|
||||
export function getAllProviderMeta(
|
||||
extensionUri: vscode.Uri
|
||||
): Record<string, ProviderMeta> {
|
||||
return getAllProviderMetaFromRegistry(extensionUri);
|
||||
}
|
||||
|
||||
export { invalidateProviderCache };
|
||||
```
|
||||
|
||||
### GeminiProvider / ClaudeProvider 适配
|
||||
|
||||
现有的 `GeminiProvider` 和 `ClaudeProvider` 构造函数签名为 `constructor(apiKey, baseUrl)`，不接收 `id` 和 `name`。保持不变，在 `createProvider()` 中根据 protocol 分别调用不同的构造方式。
|
||||
|
||||
### engine.ts 调用链变更
|
||||
|
||||
`engine.ts` 第 195 行调用 `createProvider()` 时需要传入 `extensionUri`：
|
||||
|
||||
```typescript
|
||||
// 现状
|
||||
provider = createProvider(providerId, apiKey, baseUrl);
|
||||
|
||||
// 改造后
|
||||
provider = createProvider(providerId, apiKey, baseUrl, context.extensionUri);
|
||||
```
|
||||
|
||||
`runAIReview()` 已经接收 `context: vscode.ExtensionContext` 参数（第 173 行），`context.extensionUri` 可直接获取。
|
||||
|
||||
### testConnection() 调用链变更
|
||||
|
||||
`setupView.ts` 第 380 行的 `testConnection()` 同样需要传入 `extensionUri`：
|
||||
|
||||
```typescript
|
||||
const provider = createProvider(config.provider, apiKey, config.baseUrl, this.context.extensionUri);
|
||||
```
|
||||
|
||||
### convertContentWithAI() 调用链变更
|
||||
|
||||
`src/rules/import-service.ts` 第 382 行的 `convertContentWithAI()` 也调用了 `createProvider()`。该函数已接收 `context: vscode.ExtensionContext` 参数（第 367 行），可直接使用 `context.extensionUri`：
|
||||
|
||||
```typescript
|
||||
// 现状
|
||||
const provider = createProvider(config.provider, apiKey, config.baseUrl);
|
||||
|
||||
// 改造后
|
||||
const provider = createProvider(config.provider, apiKey, config.baseUrl, context.extensionUri);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 09 侧边栏面板改造
|
||||
|
||||
### setupView.ts 变更
|
||||
|
||||
#### resolveWebviewView() — 初始化时传入 extensionUri
|
||||
|
||||
第 203 行：
|
||||
|
||||
```typescript
|
||||
// 现状
|
||||
const providers = getAllProviderMeta();
|
||||
|
||||
// 改造后
|
||||
const providers = getAllProviderMeta(this.context.extensionUri);
|
||||
```
|
||||
|
||||
#### pushConfig() — 推送供应商元数据
|
||||
|
||||
第 335 行：
|
||||
|
||||
```typescript
|
||||
// 现状
|
||||
providers: getAllProviderMeta(),
|
||||
|
||||
// 改造后
|
||||
providers: getAllProviderMeta(this.context.extensionUri),
|
||||
```
|
||||
|
||||
#### setProvider 消息处理 — 传入 extensionUri
|
||||
|
||||
第 245 行：
|
||||
|
||||
```typescript
|
||||
// 现状
|
||||
const models = getProviderModels(msg.value);
|
||||
|
||||
// 改造后
|
||||
const models = getProviderModels(this.context.extensionUri, msg.value);
|
||||
```
|
||||
|
||||
#### getHtml() — 供应商下拉框渲染
|
||||
|
||||
供应商下拉框保持 `<select>` 不变（供应商数量有限，且不允许用户手动输入供应商 id），但 `providers` 数据来源改为 `getAllProviderMeta(this.context.extensionUri)`。
|
||||
|
||||
模型区域改为方案 A 中的 `<input> + <datalist>`。
|
||||
|
||||
#### resolveWebviewView() — 新增 FileSystemWatcher
|
||||
|
||||
新增对 `.code-review/providers.json` 的文件系统监听，在 `onDidDispose` 中一并释放。
|
||||
|
||||
### setupView.js 变更
|
||||
|
||||
#### modelSelect → modelInput
|
||||
|
||||
按方案 A 的改造方案，将所有 `modelSelect` 引用替换为 `modelInput`，`populateModelOptions()` 改为填充 `datalist`。
|
||||
|
||||
#### initConfig 消息处理 — 设置 modelInput 值
|
||||
|
||||
```javascript
|
||||
if (c.provider && PROVIDERS[c.provider]) {
|
||||
populateModelOptions(c.provider, c.model);
|
||||
var mi = document.getElementById('modelInput');
|
||||
if (mi) { mi.value = c.model || ''; }
|
||||
var ps = document.getElementById('providerSelect');
|
||||
if (ps) { ps.value = c.provider; }
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 10 文件级变更规格
|
||||
|
||||
### [NEW] `providers.json`（项目根目录）
|
||||
|
||||
插件内置的供应商配置文件，随 VSIX 打包。内容见 04 节的 JSON 示例。包含 8 个供应商的完整配置。
|
||||
|
||||
### [NEW] `src/ai/types.ts`
|
||||
|
||||
提取 `ProviderConfig`、`ProvidersFile`、`ProviderMeta`、`ProviderProtocol` 类型定义。`factory.ts` 和 `registry.ts` 均从此文件导入。
|
||||
|
||||
```typescript
|
||||
export type ProviderProtocol = 'openai-compatible' | 'gemini' | 'claude';
|
||||
|
||||
export interface ProviderConfig {
|
||||
id: string;
|
||||
name: string;
|
||||
protocol: ProviderProtocol;
|
||||
defaultBaseUrl: string;
|
||||
models: string[];
|
||||
}
|
||||
|
||||
export interface ProvidersFile {
|
||||
providers: ProviderConfig[];
|
||||
}
|
||||
|
||||
export interface ProviderMeta {
|
||||
name: string;
|
||||
models: string[];
|
||||
}
|
||||
```
|
||||
|
||||
### [NEW] `src/ai/registry.ts`
|
||||
|
||||
注册表加载器，实现内置 JSON 读取、用户覆盖合并、缓存管理。完整实现见 07 节。
|
||||
|
||||
### [MODIFY] `src/ai/factory.ts`
|
||||
|
||||
| 变更位置 | 变更内容 |
|
||||
|----------|----------|
|
||||
| 删除 | 静态 `registry` 对象及其全部内容 |
|
||||
| 删除 | `ProviderInfo` 接口定义 |
|
||||
| 修改 | `createProvider()` 签名新增 `extensionUri` 参数，改为从 registry 动态查找 |
|
||||
| 修改 | `getProviderModels()` 签名新增 `extensionUri` 参数 |
|
||||
| 修改 | `getAllProviderMeta()` 签名新增 `extensionUri` 参数，委托给 registry.ts |
|
||||
| 新增 | `PROTOCOL_MAP` 常量，映射 protocol → Provider 类 |
|
||||
| 新增 | `invalidateProviderCache` re-export |
|
||||
| 删除 | `getProviderIds()`、`getProviderInfo()`、`getProviderDefaultBaseUrl()`（改为通过 registry.ts 获取） |
|
||||
|
||||
### [MODIFY] `src/ai/engine.ts`
|
||||
|
||||
| 变更位置 | 变更内容 |
|
||||
|----------|----------|
|
||||
| 第 195 行 | `createProvider(providerId, apiKey, baseUrl)` → `createProvider(providerId, apiKey, baseUrl, context.extensionUri)` |
|
||||
|
||||
### [MODIFY] `src/rules/import-service.ts`
|
||||
|
||||
| 变更位置 | 变更内容 |
|
||||
|----------|----------|
|
||||
| 第 382 行 | `createProvider(config.provider, apiKey, config.baseUrl)` → `createProvider(config.provider, apiKey, config.baseUrl, context.extensionUri)` |
|
||||
|
||||
### [MODIFY] `src/views/setupView.ts`
|
||||
|
||||
| 变更位置 | 变更内容 |
|
||||
|----------|----------|
|
||||
| 第 203 行 | `getAllProviderMeta()` 调用改为传入 `this.context.extensionUri` |
|
||||
| 第 245 行 | `getProviderModels(msg.value)` 调用改为传入 `this.context.extensionUri, msg.value` |
|
||||
| 第 335 行 | `getAllProviderMeta()` 调用改为传入 `this.context.extensionUri` |
|
||||
| 第 380 行 | `createProvider()` 调用新增 `this.context.extensionUri` 参数 |
|
||||
| `resolveWebviewView()` | 新增 `FileSystemWatcher` 监听 `.code-review/providers.json` 变更 |
|
||||
| 第 889-891 行 | 模型区域 `<select id="modelSelect">` 替换为 `<input id="modelInput" list="modelOptions">` + `<datalist id="modelOptions">` |
|
||||
|
||||
### [MODIFY] `src/views/setupView.js`
|
||||
|
||||
| 变更位置 | 变更内容 |
|
||||
|----------|----------|
|
||||
| 第 88-102 行 `populateModelOptions()` | 改为填充 `<datalist>` 而非 `<select>`，保留用户已输入的值 |
|
||||
| 第 109-111 行 `modelSelect` change 事件 | 改为 `modelInput` change 事件 |
|
||||
| 第 143-147 行 `initConfig` 消息处理 | `modelSelect.value` 设置改为 `modelInput.value` 设置 |
|
||||
|
||||
### [MODIFY] `package.json`
|
||||
|
||||
| 变更位置 | 变更内容 |
|
||||
|----------|----------|
|
||||
| 第 92-96 行 `ai.provider` 配置项 | 删除 `enum` 数组，改为自由 string |
|
||||
| 版本号 | `1.1.0` → `1.2.0` |
|
||||
|
||||
### [MODIFY] `src/i18n/messages.ts`
|
||||
|
||||
新增 `setup.modelPlaceholder` 国际化键（三语言）。
|
||||
|
||||
### `.vscodeignore`
|
||||
|
||||
确认 `providers.json` 不在忽略列表中，确保随 VSIX 打包。
|
||||
|
||||
---
|
||||
|
||||
## 11 迁移路径
|
||||
|
||||
### 11.1 内置 providers.json 中的模型名修正
|
||||
|
||||
当前 `factory.ts` 中的模型名（如 `deepseek-v4-pro`、`GPT-5.6 Sol`、`Claude Fable 5`）并非真实模型名。新的 `providers.json` 中应使用各供应商 API 实际接受的模型标识符：
|
||||
|
||||
| 供应商 | 当前（虚构） | 修正为（真实） |
|
||||
|--------|-------------|---------------|
|
||||
| DeepSeek | `deepseek-v4-pro`, `deepseek-v4-flash` | `deepseek-chat`, `deepseek-reasoner` |
|
||||
| OpenAI | `GPT-5.6 Sol`, `GPT-5.6 Terra` 等 | `gpt-4o`, `gpt-4o-mini`, `gpt-4-turbo` |
|
||||
| Gemini | `Gemini 3.1 Pro` 等 | `gemini-2.0-flash`, `gemini-1.5-pro` |
|
||||
| Claude | `Claude Fable 5` 等 | `claude-sonnet-4-20250514`, `claude-opus-4-20250514` |
|
||||
| 混元 | `Hy3` | `hunyuan-pro` |
|
||||
| 智谱 | `GLM-5.2` 等 | `glm-4-plus`, `glm-4-flash` |
|
||||
| 月之暗面 | `Kimi K2.7 Code` 等 | `moonshot-v1-8k`, `moonshot-v1-32k` |
|
||||
| 通义 | `Qwen3-2507` 等 | `qwen-plus`, `qwen-turbo` |
|
||||
|
||||
> 以上模型名基于截至 2026-07 各供应商 API 文档的公开模型标识符。实际发布前需再次验证各供应商 API 文档的最新模型列表。
|
||||
|
||||
### 11.2 用户配置兼容性
|
||||
|
||||
| 用户已有配置 | 升级后行为 |
|
||||
|-------------|-----------|
|
||||
| `ai.provider` = `deepseek` | 保留，`providers.json` 中存在该 id，正常工作 |
|
||||
| `ai.model` = `deepseek-chat` | 保留，新 `providers.json` 中 DeepSeek 列表包含此项，datalist 中可见 |
|
||||
| `ai.model` = `deepseek-v4-pro`（旧列表中的值） | 保留，`modelInput` 中显示该值，但不在 datalist 建议中。用户可继续使用或手动修改。API 是否接受取决于供应商 |
|
||||
| `ai.baseUrl` 有值 | 保留不变，切换供应商时不自动覆盖 |
|
||||
| API Key（SecretStorage） | 保留不变 |
|
||||
| `ai.outputLanguage` | 保留不变 |
|
||||
|
||||
### 11.3 向后兼容保证
|
||||
|
||||
`createProvider()` 的调用方（`engine.ts`、`setupView.ts`）需要传入 `extensionUri`。这是签名变更，但均在插件内部调用，不影响用户侧 API。`runAIReview()` 的外部调用签名不变。
|
||||
|
||||
---
|
||||
|
||||
## 12 测试要点
|
||||
|
||||
### 方案 A：模型输入框
|
||||
|
||||
| 测试场景 | 操作步骤 | 期望结果 |
|
||||
|----------|----------|----------|
|
||||
| 选择预置模型 | 点击模型输入框，从 datalist 建议中选择一个 | 输入框填入选中值，`ai.model` 配置更新 |
|
||||
| 手动输入模型名 | 在模型输入框中输入 `my-custom-model` 并失焦 | 输入框保留输入值，`ai.model` 更新为 `my-custom-model` |
|
||||
| 切换供应商后保留手输模型 | 先手动输入模型名，再切换供应商 | 模型输入框清空并填入新供应商的第一个建议模型 |
|
||||
| 空值处理 | 清空模型输入框并失焦 | `ai.model` 更新为空字符串，AI 审查时报错提示需配置模型 |
|
||||
|
||||
### 方案 B：供应商注册表
|
||||
|
||||
| 测试场景 | 前置条件 | 期望结果 |
|
||||
|----------|----------|----------|
|
||||
| 内置 JSON 加载 | 无用户覆盖文件 | `getProviders()` 返回 8 个内置供应商 |
|
||||
| 用户追加供应商 | 工作区有 `.code-review/providers.json`，包含 `ollama` | 合并后返回 9 个供应商，`ollama` 出现在下拉框 |
|
||||
| 用户覆盖内置供应商 | 用户文件中 `deepseek` 的 `defaultBaseUrl` 改为代理地址 | 合并后 DeepSeek 的 `defaultBaseUrl` 为用户配置的代理地址 |
|
||||
| 用户文件格式错误 | `.code-review/providers.json` 内容为非法 JSON | 加载器静默返回空数组，不影响内置供应商加载 |
|
||||
| 用户文件不存在 | 工作区无 `.code-review/` 目录 | 仅返回内置 8 个供应商 |
|
||||
| 文件监听刷新 | 编辑并保存 `.code-review/providers.json` | 缓存失效，侧边栏自动刷新供应商列表 |
|
||||
| 缓存命中 | 连续调用两次 `getProviders()` | 第二次直接返回缓存，不重复读取文件系统 |
|
||||
|
||||
### 附加修复项
|
||||
|
||||
| 测试场景 | 操作步骤 | 期望结果 |
|
||||
|----------|----------|----------|
|
||||
| package.json 无 enum 限制 | 在 settings.json 中手动写入 `ai.provider: "custom-provider"` | VS Code 不报 schema 校验错误，插件正常加载 |
|
||||
| 连接测试使用 extensionUri | 配置完 API Key 后点击"保存并测试" | `createProvider()` 正确接收 extensionUri，测试请求发送到正确端点 |
|
||||
|
||||
### 回归测试
|
||||
|
||||
| 测试场景 | 期望结果 |
|
||||
|----------|----------|
|
||||
| AI 代码审查（`Ctrl+Shift+R`） | 正常运行，使用配置的供应商和模型 |
|
||||
| 选中代码审查 | 正常运行 |
|
||||
| 审查结果面板导出 | 正常导出报告 |
|
||||
| 自定义规则管理 | 规则文件导入、删除正常 |
|
||||
| 静态分析适配器面板 | 4 张适配器卡片正常渲染，不受供应商改造影响 |
|
||||
| 保存文件自动分析 | 500ms 防抖后触发静态分析 |
|
||||
|
||||
---
|
||||
|
||||
*本设计书基于 vscode-code-reviewer 插件 v1.1.0 编写，覆盖方案 A（模型输入框可编辑化）、方案 B（供应商注册表外置化）及 `package.json` 修复的全部技术实现规格。实施时按第 10 节文件级变更规格逐文件执行，以第 06-09 节的数据结构和逻辑为实现依据。*
|
||||
Reference in New Issue
Block a user