89 lines
7.4 KiB
Markdown
89 lines
7.4 KiB
Markdown
# 标准格式导入 — 手动验证结果报告（8 种格式全量）
|
||
|
||
## 验证信息
|
||
|
||
| 项 | 值 |
|
||
|---|---|
|
||
| 验证日期 | 2026-09-06 |
|
||
| 验证功能 | 自定义规则导入——同一规则集的 8 种文件格式逐一导入 |
|
||
| 导入素材 | `data/import-verification/02-standard-formats/team-coding-rules.*`（8 个文件） |
|
||
| 导入结果 | `data/import-verification/02-standard-formats/results/standard-rules-*.yaml`（8 个文件，已全部移出激活目录归档） |
|
||
| 规则基准 | 12 条规则（安全 3 + 命名 2 + 性能 2 + 风格 2 + 团队约定 3），severity 基准 error×2 / warning×5 / info×5 |
|
||
| 验证方式 | 在 Extension Development Host 中手动执行完整导入流程（含预览确认），每轮结果落盘核对后归档 |
|
||
|
||
## 素材矩阵
|
||
|
||
| # | 文件 | 格式 | 导入路径 | AI 内容转换 |
|
||
|---|---|---|---|---|
|
||
| 1 | team-coding-rules.yaml | YAML | YamlConverter 直读 | 否 |
|
||
| 2 | team-coding-rules.md | Markdown | 读文本 → AI（freeform） | 是 |
|
||
| 3 | team-coding-rules.txt | 纯文本 | 读文本 → AI（freeform） | 是 |
|
||
| 4 | team-coding-rules.docx | Word | mammoth 提取 → AI（freeform） | 是 |
|
||
| 5 | team-coding-rules.pptx | PowerPoint | officeparser 提取 → AI（freeform） | 是 |
|
||
| 6 | team-coding-rules.xlsx | Excel 单表 | 表格 → Markdown → AI（spreadsheet） | 是 |
|
||
| 7 | team-coding-rules-multi-sheet.xlsx | Excel 5 表 | 逐表渲染合并 → AI（spreadsheet） | 是 |
|
||
| 8 | team-coding-rules-template.xlsx | Excel 模板 | 严格表头校验直读（仅去重走 AI） | 否 |
|
||
|
||
## 逐轮结果总表
|
||
|
||
| 轮 | 格式（规则名） | 检出条数 | severity | languages | id 与基准 | 去重标注 | 结论 |
|
||
|---|---|---|---|---|---|---|---|
|
||
| 1 | yaml（standard-rules-yaml） | 12/12 | ✅ 全对 | ✅ 全对 | 逐字节一致 | 直读不去重，预览阶段独立去重 | 通过 |
|
||
| 2 | md | 12/12 | ✅ 全对 | ✅ 全对 | 6 处不同（语义等价） | 3 exact，指向真实 | 通过 |
|
||
| 3 | txt | 12/12 | ✅ 全对 | ✅ 全对 | 6 处不同 | 3 exact，同构 | 通过 |
|
||
| 4 | docx | 12/12 | ✅ 全对 | ✅ 全对 | 5 处不同 | 3 exact，同构 | 通过 |
|
||
| 5 | pptx | 12/12 | ✅ 全对 | ⚠️ 丢 6 处 | 6 处不同 | 3 exact，同构 | 通过（有降级） |
|
||
| 6 | xlsx 单表 | 12/12 | ✅ 全对 | ✅ 全对 | **完全一致** | 3 exact，同构 | 通过 |
|
||
| 7 | xlsx 5 表 | 12/12 | ✅ 全对 | ✅ 全对 | **完全一致** | 3 exact，同构 | 通过 |
|
||
| 8 | template | 13 有效 + 3 错误行 + 1 空行 | ✅ 全对 | ✅ 全对（列直读） | **完全一致** | 4 exact（多 1 条 no-console-log 附加行） | 通过 |
|
||
|
||
## 关键发现
|
||
|
||
### 1. pptx 无语言字段：根因定位为源文件本身不含语言标注，AI 行为正确（非降级）
|
||
|
||
表现：5 处 languages + 1 处 excludeLanguages 留空（constant-case / boolean-prefix / nested-loops / sync-in-async / throw-context 的 languages，todo 规则的 excludeLanguages: [sql]），类型注解规则正确保留 [typescript]。
|
||
|
||
**根因定位（2026-09-07，两步验证）**：
|
||
|
||
1. 重测复现：同文件再次导入，留空模式与首测逐字段一致，而同期 id 照例漂移——排除 AI 随机性，锁定文件因素。归档：`results/standard-rules-pptx-retest.yaml`。
|
||
2. 提取文本比对：用与插件相同的 officeparser 调用链提取该 pptx，全文 950 字符中**不含任何「适用语言/排除语言」标注**（severity 有 `[error]/[warning]/[info]` 前缀标注，语言没有）——幻灯片源内容本身就没写语言信息。
|
||
|
||
**最终定性**：源文件没有的数据不存在「丢失」。AI 行为完全正确——描述含语义线索的规则正确推断（如「显式标注 TypeScript 类型」→ [typescript]），无线索的规则按「严禁猜测，留空比猜测错误更安全」留空。对照场景③ pptx（幻灯片含「严重级别 | 语言」成组标注）AI 全部正确映射，进一步证明 AI 侧无缺陷。**制作 pptx 规则素材时，如需语言限定必须在幻灯片中显式标注适用语言**。
|
||
|
||
### 2. 表格类格式 id 收敛到与基准完全一致
|
||
|
||
xlsx 单表、multi-sheet、template 三轮的 id 与 yaml 基准完全一致；而 md/txt/docx/pptx 四轮 AI 生成的 id 每轮都不同（语义等价，如 require-constant-case ↔ constant-screaming-snake-case ↔ boolean-naming-prefix 波动）。结构化表格让 AI 的 id 生成收敛到规范命名。multi-sheet 轮落盘文件与 xlsx 单表轮**逐字节一致**（fc 二进制比对 0 差异），证明多表拆分 + 合并链路对 AI 转换零干扰。
|
||
|
||
### 3. 模板路径严格校验精准命中
|
||
|
||
模板文件自带 4 行校验测试数据（设计见其「填写说明」Sheet），校验器全部精准捕获且无误报：
|
||
|
||
| 测试行 | 校验表现 |
|
||
|---|---|
|
||
| 缺 id 行 | 生成占位 ID `rule-14` + 黄色提示「占位 ID：请修改为有意义的标识」 |
|
||
| 非法 severity 行（no-deep-inheritance，`critical`） | 红色「severity 非法： 'critical'」，下拉框置空待修 |
|
||
| 空 description/message 行（empty-desc-rule） | 双红框标记两个字段 |
|
||
| 空行 | 静默跳过（17 行 → 检出 16 条） |
|
||
|
||
确认导入时未修复的错误行被丢弃，不静默混入（本次验证选择直接确认；修复后添加的工作流另行演示）。
|
||
|
||
### 4. 去重标注跨格式高度稳定
|
||
|
||
除 yaml 直读外，7 轮去重结果完全同构：no-hardcoded-credentials → custom/no-hardcoded-secret、no-eval(-usage) → eslint/no-eval、no-magic-numbers → custom/no-magic-numbers，全部 exact 且指向经核实真实存在（security-rules.yaml / coding-conventions.yaml / 内置静态规则）。模板轮附加行 no-console-log 额外命中 custom/no-console-log 为第 4 条 exact，验证模板路径去重正常。
|
||
|
||
## 已知观察
|
||
|
||
- **AI 生成 id 跨格式不保证一致**：自由文本格式（md/txt/docx/pptx）每轮 id 均有波动。含义相同的规则若以不同格式多次导入并共存于激活目录，将因 id 不同而双报——建议同一规则集只保留一种格式的导入结果（本验证每轮归档移出即为此目的）。
|
||
- **模板路径注释块元数据形态**：注释块内 `duplicateLevel` 行未逐条写入（exact 信息由注释头 `[DUPLICATE: exact]` 承载），与通用路径的块内元数据略有差异，功能等价。
|
||
- **验证弹性对照**：galaxy 素材验证中曾出现去重轮次波动（第 1 轮漏标 2 条、第 2 轮无遗漏）；本套标准格式素材因规则语义清晰、边界分明，7 轮 AI 去重结果零波动，说明输入质量是 AI 稳定性的重要变量。
|
||
|
||
## 结论
|
||
|
||
**通过**。8 种格式全部成功导入 12 条规则基准：条数零丢失、severity 零偏差、去重标注跨格式稳定且指向真实。pptx 轮 languages 留空经两步验证（重测复现 + 提取文本比对）定位为源文件本身不含语言标注，AI 行为正确非缺陷；制作 pptx 素材时如需语言限定须在幻灯片中显式标注。yaml / xlsx / template 三种结构化格式表现最优（id 与基准完全一致）。
|
||
|
||
## 关联
|
||
|
||
- galaxy 素材验证报告：`data/import-verification/01-galaxy-nonstandard/result-report.md`（真实世界非标准格式场景）
|
||
- 自动化测试：`tests/excel-converter.test.ts`（转换器渲染层）
|
||
- 设计 spec：`docs/superpowers/specs/2026-07-26-custom-rule-import-ux-design.md`、`docs/superpowers/specs/2026-07-30-export-template-design.md`
|