2026Technology-Competition/docs/superpowers/specs/2026-07-21-converter-architecture-design.md

规则导入转换器架构设计

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 接口

// 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

// 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 基础设施不变