范智鹏
effcf30802
- 适配器 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 依赖及测试用例
137 lines
4.7 KiB
Markdown
137 lines
4.7 KiB
Markdown
# 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 文件
|