OpenMAIC maic-importer 开发规范实战PPTX 解析还原质量迭代与 OOXML 陷阱排查指南【免费下载链接】OpenMAICOpen Multi-Agent Interactive Classroom — Get an immersive, multi-agent learning experience in just one click项目地址: https://gitcode.com/GitHub_Trending/op/OpenMAICmaic-importer是 OpenMAIC 中负责将.pptx文件解析为结构化 JSON、进而还原成画布可渲染Slide[]的核心包。本文以本包开发规范SKILL.md为骨架结合DESIGN.md的架构设计与src/下的实际源码实现完整讲解还原质量迭代流程、标准修 bug 流程、OOXML 陷阱、分层红线与高风险文件供开发者含 Agent在修改解析侧代码前快速建立正确的排查心智模型。maic-importer 是什么一条从 .pptx 到 JSON 的解析管线maic-importer的前身是浏览器端运行的 pptxtojsonOpenMAIC 在其parse()之上扩展了完整的 import pipelineimportPptx()→ 直接产出画布Slide[]。包内开发规范 SKILL.md 开宗明义先读 DESIGN.md 了解架构再做任何改动。按 DESIGN.md 的记载整条解析管线为.pptx (ArrayBuffer) ↓ parser/ZipParser ── 解压 zip按用途分类 PptxFiles ↓ model/* ── XML → 结构化模型位置、大小、层级 PresentationData ↓ serializer/* ── 模型 主题/模板上下文 → JSON 元素 Element[] ↓ adapter/toPptxtojson ── 组装最终输出 Output { slides, themeColors, size }入口是src/index.ts的parse(buffer, options?)。包内有两个易混目录src/是 TypeScript 主实现参与构建src1/是原版 JS 参考实现只读不改不构建。理解本包时先记住三个核心设计点详见 DESIGN.md模型层不感知样式model/*只解析是什么、在哪里、多大颜色、字体、填充等视觉样式留给 serializer 层做 theme/master/layout 级联解析Serializer 是纯映射*ToElement(node, ctx, order)输入模型 上下文、输出 JSON 元素、无副作用因此定位 bug 时只需怀疑对应的 serializer 文件单位约定对外 JSON 一律ptleft/top/width/height颜色一律#RRGGBB角度一律deg内部 EMU 在 model 层转 pxadapter 层 px → pt。单位换算集中在 parser/units.ts其中定义了 EMU→px、EMU→pt、OOXML 角度60000 分之一度→deg、百分比100000 分之一→小数等全套换算函数。还原质量迭代从低分样本到修复交付必读解析还原不可能一版到位规范要求以批次迭代的方式持续逼近真实还原效果。仓库根目录的iterate-prompt.md规定了如何从comparison_run中拉取低分样本、聚类问题、撰写报告。每批迭代需要交付两样东西iteration-version-report.md仓库根目录——批次迭代报告针对本包的解析侧修复——注意渲染问题应修在packages/openmaic/renderer不要在本包越界处理。SKILL.md 以test-0601-002deck第一节 养老服务管理概述为样例列出了四类典型问题及其排查入口现象侧查哪里Logo 上多 5 个空心圆解析layoutElements里 master 组「组合 7」子椭圆grpFill勿把父组 fill 摊到每个 child → shapeSerializer.ts照片应是圆却变方解析p:piccustGeom→ imageSerializer.resolvePresetGeom画布四周边框渲染SlideCanvaschrome截图须false文字整体偏上解析渲染bodyPranchor→vAlign→ transformParsedToSlides BaseTextElement正文偏粗、换行少解析渲染replaceFontFamilyInHtml/ 文本框width调试时有一条铁律一定要看layoutElements。Logo、页脚、master 装饰元素几乎都在layoutElements里而不是elements里只盯着elements会漏掉大量母版侧问题。对应的调试命令均在仓库根执行# 仓库根拉低分 node --env-file.env.development scripts/inspect-low-scores.mjs test-0601-002 # 本包JSON含 layoutElements npx tsx scripts/transvert.ts /path/to.pptx ./out.json node -e const srequire(./out.json).slides[1]; console.log(s.layoutElements?.length, s.elements?.length)transvert.ts是开发主力脚本直接 importsrc源码、无需构建即可出 JSON源码 内部就是parseZip → buildPresentation → toPptxtojsonFormat三步。用node -e一行即可快速核对第 2 页的layoutElements与elements数量是否与预期一致。修 bug 的标准流程解压 → 转换 → 改码 → diff规范给出了任何 bug 修复都必须遵守的四步流程# 1. 解压 pptx 看源 XML node scripts/extract-pptx-structure.js ./xxx.pptx ./out # 2. 生成修改前的 JSON npx tsx scripts/transvert.ts ./xxx.pptx ./before.json # 3. 改代码 # 4. 生成修改后的 JSONdiff 对比 npx tsx scripts/transvert.ts ./xxx.pptx ./after.json第一步的 extract-pptx-structure.js 会把.pptx本质是 zip解压并以树形打印内部结构方便直接查看ppt/slides/slideN.xml、ppt/slideMasters/、ppt/media/等原始 XML第二步与第四步的before/after.json对比则是验证修复是否生效的客观依据。规范还给出了按数值/结构/颜色/模板/装饰分类的定位思路JSON 数值错 → serializer节点类型错 → model/Slide.ts颜色错 → StyleResolver.ts utils/color.ts模板继承错 → RenderContext.tsmaster/layout 装饰→ slideSerializer.ts 的layoutElements shapeSerializer.ts 的grpFill/lnnoFillvslnRef。OOXML 陷阱清单本 deck 已踩规范将真实踩过的 OOXML 陷阱固化为四条经验每条都能在源码中找到对应实现1.a:grpFill/子形状由组级合成禁止把父组 fill 摊给每个 childgrpFill表示子形状的填充由父组grpSpPr合成因此 JSON 里每个 child 的fill应为transparent。既不能把父组 solidFill 抄到每个椭圆上也不能用fillRef补色——test-0601-002 的 5 个 Logo 圆点正是此类问题。源码 shapeSerializer.ts 在检测到grpFill时依赖ctx.groupFillNode见 RenderContext.ts继承组填充同时 StyleResolver.ts 也实现了 grpFill 从父组继承填充的逻辑。对应回归测试见 shapeSerializer.grpFill.test.ts。2.a:lna:noFill//a:ln显式无描边优先于lnRef当形状显式声明a:noFill/作者意图是无线条时即使p:style里带有lnRef也应以noFill为准。源码中通过noFillSuppressed处理这一优先级避免像 WPS 风格的兼容逻辑那样错误地继承一个绿色lnRef。3.p:pic圆形裁剪常为custGeom而非prstGeom prstellipse许多 deck 的圆形照片裁剪用的是自定义几何custGeom而不是预设几何prstGeom。若只读prstGeom会得到rect方形。imageSerializer.resolvePresetGeom 的注释明确写着Many decks use custGeom circles on p:pic instead of prstellipse实现上先查prstGeom、再查custGeom的pathLst/path两个分支都必须覆盖因为该函数的结果直接影响下游的clip。4. 分层顺序layoutElementsmasterlayout先画elementsslide后画元素的分层必须与 transformParsedToSlides 的输出顺序一致masterlayout 装饰垫底slide 内容在上。这也再次印证了调试先看layoutElements的必要性——master 装饰一旦画错会叠在每一页内容之下。代码规范与提交约定SKILL.md对本包代码质量提出了明确约束TypeScript strict不用ts-ignoreany仅在必要时局部使用并加注释说明注释解释为什么不解释做了什么描述意图而非流水账用已有工具单位换算用 parser/units.tsXML 操作用 SafeXmlNode颜色变换用 utils/color.ts避免重复造轮子引入不一致commit message 用中文、动词起头、点明修了什么好fix(text): 修复 solidFill/gradFill 互斥覆盖导致渐变遮盖文字颜色坏fix bug/update一个 commit 只做一件事重构与 bug 修复分开提。类型协议adapter/types.ts对外 JSON 的契约src/adapter/types.ts 是与下游的协议修改必须极其谨慎四条红线不改已有字段的名字或类型不把可选字段改为必选新增字段一律?:可选并附 JSDoc 说明其含义遵守单位约定长度单位 pt、颜色#RRGGBB、角度 deg。从 types.ts 源码可以看到Element是Shape | Text | Image | Table | Chart | Video | Audio | Diagram | Math与Group的联合Slide同时输出elements与layoutElements两个数组Output顶层为{ slides, themeColors, size }。这些结构一旦改变所有下游消费方渲染器、画布都会受影响。与之相对model/*的内部类型可以自由重构但必须保持模型层不感知样式的原则——视觉样式解析的复杂级联逻辑不应下放到 model 层。分层红线单向依赖规范用一张表划定了各层的职责边界层该做不该做parser解压、XML 解析、单位换算解析 OOXML 业务语义model解析几何与结构解析视觉样式serializer模型 上下文 → JSON 元素直接读 zipadapter定义类型、组装输出写业务逻辑shapes输出 SVG path决定填充/边框utils通用工具引用业务类型依赖方向为adapter → serializer → model → parser禁止反向shapes与utils是底层工具。这条红线保证了每一层都可以独立测试与替换也是定位问题只需怀疑对应 serializer的架构前提。高风险文件清单改动以下文件前需要格外谨慎规范原文标注为高风险groupSerializer.ts承担chOff/chExt缩放与 flip/rotation 烘焙。改前想清楚flipH flipV → 180°的等价规则新增 child 特殊缩放规则时要做 fast-path 短路避免性能回退。shapeSerializer.ts800 行承担 Shape/Text 判定、preset 路径、自适应、grpFill/fillRef/lnRef互斥等核心逻辑。调整 Shape vs Text 判定前先用src1跑同样的.pptx对比以原版参考实现校准行为。imageSerializer.tsresolvePresetGeom影响下游clipcustGeom与prstGeom两个分支都要覆盖。presets.ts200 preset 共享辅助函数修一个前先看调用方避免误伤其他几何。parser/units.ts被广泛依赖不要改现有函数签名需要新单位就新增函数。开发注意事项最后是规范强调的几条提交纪律*.pptx、slides.json、out/、dist/已在.gitignore中提交前用git status确认不要把调试产物带进仓库src1/是原版参考实现只读不改不构建改了 adapter/types.ts 必须在 commit body 写明协议变更改完解析逻辑后用新 version重跑 compare避免与旧批次 reply 混淆保证迭代报告的数据可追踪。整套规范的精髓可以浓缩为一句话先看layoutElements怀疑对应 serializer用before/after.jsondiff 验证提交时守住协议与分层红线。按这个流程走无论面对的是 Logo 空心圆、圆形照片还是文字偏移都能在几分钟内定位到具体的解析或渲染环节。【免费下载链接】OpenMAICOpen Multi-Agent Interactive Classroom — Get an immersive, multi-agent learning experience in just one click项目地址: https://gitcode.com/GitHub_Trending/op/OpenMAIC创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考