MAIC 导入器开发规范技能
让 AI 助手按照 OpenMAIC maic-importer 包的架构、调试与提交规范，参与 PPTX 解析代码的开发与还原质量迭代。
SKILL.md 本身是开发规范文档，不要求高危权限或外部副作用；配套脚本仅读写本地文件。扣分点：toPptxto.ts 中 prefetchTexmath 会向外部 /api/texmath 端点发送 OMML 数据（虽为 best-effort 且有回退），数据流在 SKILL.md 未披露；发布者身份未经验证；无回滚/确认机制说明。
文档引用的 transvert.ts、extract-pptx-structure.js 等脚本在包内真实存在，指令自洽；package. 有 vitest 测试脚本，且仓库 CI（ci.yml）明确运行 importer 单元测试，构成可审计的执行证据，故可略超静态基线。扣分点：测试文件内容未随附、错误反馈细节和边界用例覆盖无法静态核实，远未达 20 分锚点。
该 SKILL.md 实质是面向本仓库导入器包的开发者规范（还原质量迭代、修 bug 流程、代码规范），不是面向终端用户的可语义触发 Agent 技能；触发条件与不适用边界仅隐含。加分：中文文档完整、环境要求明确。扣分：作为 Agent Skill 的场景/触发精度不足，能力边界声明薄弱。
文档分层清晰（SKILL.md → DESIGN.md → README.md），分层红线、类型协议、高风险文件清单完备；MIT 许可与仓库归属明确，且诚实标注了 fork 自 pptxto（原许可与致谢保留）。扣分点：SKILL.md 面向开发者而非使用者，缺少 FAQ、变更日志与维护责任声明；README 中上游与 fork 的版本叙事有一定混淆。
核心任务（引导开发者安全地修改导入器、调试解析差异）路径具体、可操作，附带命令与定位表，边际价值明确。扣分点：'还原质量'效果仅引用单个测试 deck（test-0601-002），无静态可验证的代表性输出证据，且 README 自述解析结果与源文件在样式上仍有差异。
有仓库内 CI 工作流、可运行的调试脚本和具体测试用例编号作为一级材料，属可审计。扣分点：关键质量声明（还原迭代得分、OOXML 陷阱案例）无法静态独立复现，测试文件本身未提供，多源交叉验证缺失，静态上限 5 分亦未及。
- 此 SKILL.md 是开发者规范而非终端用户 Agent 技能，语义触发与通用适用性有限。
- 解析流程会向外部 /api/texmath 端点发送 OMML 公式数据（不可达时回退），使用前请确认数据出站是否符合你的策略。
- README 声明浏览器专用，Node 进程直接引入会在加载时抛错；部署依赖 postinstall 生成 vendor 产物，缺失将 404。
- 字体白名单与视频编码检测为 stub，HEVC 等场景可能产出坏的视频元素；中文字体仅透传。
- 还原质量声明仅基于单一测试 deck，静态评审未执行任何代码，实际效果需自行验证。
这个 Skill 能做什么，适合哪些场景？
这是 OpenMAIC 仓库中 packages/@openmaic/importer 包的开发规范技能，面向参与该包开发的 AI 编程助手。它要求先阅读 DESIGN.md 了解架构，并规定了还原质量迭代的流程、OOXML 解析陷阱、bug 修复标准流程、代码规范与分层红线。OpenMAIC 是清华团队开源的多智能体互动课堂平台，MIT 许可，其 v0.3.0 将 @openmaic/importer 等 SDK 发布到了 npm。此技能本身不是面向最终用户的产品功能，而是服务贡献者的工程规约。
该技能是一份可被 AI 助手读取的开发指令文档：它指定开发前必读 DESIGN.md 与 iterate-prompt.md；提供从 comparison_run 拉低分、聚类、写迭代报告的还原质量迭代流程（含 test-0601-002 等真实案例）；给出用 extract-pptx-structure.js 解压 pptx、用 transvert.ts 生成修改前后 JSON 并 diff 的标准调试流程；总结 grpFill 组级填充、ln noFill 优先级、p:pic custGeom 圆形裁剪等 OOXML 陷阱；规定 adapter→serializer→model→parser 的单向依赖与各层职责边界；列出 shapeSerializer.ts、groupSerializer.ts、parser/units.ts 等高风险文件及改动注意事项。
- 贡献者希望让 Claude Code 等 AI 助手在 OpenMAIC importer 包内修复 PPTX 解析 bug，需要一套统一的工作流和约束。
- 开发者在做还原质量迭代时，需要按 iterate-prompt.md 规定的流程拉取低分样本、聚类分析并产出迭代报告。
- 工程师排查 pptx 转 JSON 的还原差异，需要 SKILL.md 中的 OOXML 陷阱清单（如 grpFill、custGeom）快速定位 serializer 问题。
- 团队新人接手 importer 包，需要了解分层架构、类型协议和 commit 规范（中文动词起头、一事一 commit）。
这个 Skill 有哪些优点和局限？
- 包含真实案例（test-0601-002）与具体文件定位路径，AI 助手可按图索骥而非盲目搜索。
- 明确了分层红线与依赖方向（adapter→serializer→model→parser），有效防止 AI 改坏架构。
- 沉淀了 grpFill、custGeom、lnRef/noFill 优先级等 OOXML 实战陷阱，短平快避免重复踩坑。
- 对高风险文件（shapeSerializer 800+ 行、presets 200+ preset 等）给出改动前检查建议。
- 强内部导向：脱离 OpenMAIC 仓库（DESIGN.md、src1 参考实现、scripts 脚本）几乎无法使用。
- 面向包的贡献者而非最终用户，不会给普通使用者带来任何功能。
- SKILL.md 未包含 YAML frontmatter 元信息，需要依赖外部路径定位其用途。
- 部分脚本（inspect-low-scores.mjs 需要 .env.development）的具体配置在文档中未完整说明。
如何安装这个 Skill？
该技能属于 OpenMAIC monorepo 内部的开发规范文档，位于 packages/@openmaic/importer/SKILL.md，并非独立安装的通用技能。使用方式是克隆整个仓库：git clone https://github.com/THU-MAIC/OpenMAIC.git && cd OpenMAIC && pnpm install（要求 Node.js >= 20、pnpm >= 10）。仓库另有面向最终用户的 skills/openmaic OpenClaw 技能，但那是另一项技能，不承担本包的开发职责。
如何使用这个 Skill？
让 AI 助手读取 packages/@openmaic/importer/SKILL.md 作为工作规范，典型触发语句如『按照 importer 包的 SKILL.md，修复 test-0601-002 中照片圆形裁剪变方的问题』。具体操作包括：先用 node scripts/extract-pptx-structure.js 解压源 pptx 查看 XML；用 npx tsx scripts/transvert.ts 生成修改前后的 JSON 并 diff；调试 master/layout 装饰时查看 layoutElements；修改 adapter/types.ts 后在 commit body 写明协议变更；改解析逻辑后用新 version 重跑 compare。渲染侧问题位于 packages/@openmaic/renderer，不在本包范围。