2026Technology-Competition/docs/superpowers/specs/2026-07-24-word-ppt-import-design.md

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

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

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

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

"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 文件