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），僅供參考 OpenMAIC maic-importer 開發規范實戰：PPTX 解析還原質量迭代與 OOXML 陷阱排查指南
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），僅供參考