[docs/feature] 提議擴充 che-pptx-mcp + Swift 腳本工作流；references/ 放 python-pptx 當參考

[kiki830621]

Problem

Original request:
「可以再 macdoc 裡面提議可以做 che-pptx-mcp 與 swift 腳本的使用方式嗎？現在用 python 是不是其實難控制，但可以再那裡的 references 參考 python 套件」
— Source: 使用者對話（建構 gukai 專案 spondylodiscitis_taoyuan_6min.pptx 過程中觀察到的痛點）

Type

feature / docs（提案文件；實作工具留給後續 issue 拆分）

Motivation

實際痛點來自最近用 python-pptx 建一份 8 張投影片的醫院模板簡報（顧凱鈞 spondylodiscitis 報告）：

• 字級、圖片 box、placeholder 座標改一輪就要 rebuild → 開 Keynote → export PDF → 讀圖確認，iteration 成本高
• python-pptx 的 placeholder API 是「讀到的 XML 原封不動」，沒有 model layer；要調圖片 aspect / box 得自己算 EMU
• Python 跟 Keynote 的字體渲染不一致（macOS 只能靠 Keynote / PowerPoint export 才能看到真實結果）
• 與此對照，che-word-mcp (146 tools, v1.17) 在 docx 上的體驗是「tool call 即改即生效、可直接在 session 內 finalize」

che-pptx-mcp 目前是 v0.1.0、約 45 tools（見 mcp/che-pptx-mcp/Sources/ChePPTXMCP/Server.swift），底下的 packages/pptx-swift 已經有 Models / IO / Errors 結構，距離「pptx 版的 che-word-mcp」只差工具覆蓋度與高層 API。

Proposal

1. 擴充 che-pptx-mcp 往 che-word-mcp 的成熟度靠攏

照 che-word-mcp 的 Dual-Mode（source_path direct / doc_id session）同一條路走，重點補齊以下工具族：

Layout / Geometry（最痛的一塊）

• `set_placeholder_geometry(doc_id, slide_idx, ph_idx, left_cm, top_cm, width_cm, height_cm)` — 用 cm 不用 EMU
• `place_picture_at(doc_id, slide_idx, img_path, left_cm, top_cm, width_cm, height_cm, fit: "contain"|"cover"|"stretch")` — 預設 contain + aspect-match
• `fit_picture_to_native_aspect(doc_id, slide_idx, img_path, anchor: "left"|"right"|"center", max_width_cm, max_height_cm)` — 自動照原生 aspect 算 box（Python 版現在得自己寫）

Text runs（bullet 加粗/變色/改字級）

• `add_rich_bullet(doc_id, slide_idx, ph_idx, segments: [(text, bold?, color?, size?)])`
• `set_run_style(doc_id, slide_idx, shape_id, run_idx, ...)`

Template handling

• `list_slide_masters` / `list_slide_layouts` / `add_slide_from_layout(master_idx, layout_idx)`
• `delete_all_slides_preserve_masters` — 從模板只保留版型常用操作
• `copy_slide_from(source_path, slide_idx)`

Notes / presenter

• `set_notes(doc_id, slide_idx, text)` / `get_notes(...)`
• `export_notes_markdown(source_path)` — 對照 che-word-mcp 的 `export_markdown`

Export / preview

• `export_pdf(doc_id, output_path)` — 透過 Keynote AppleScript 或 LibreOffice
• `render_slide_png(doc_id, slide_idx, output_path, dpi)` — 給 LLM 回饋 loop

2. Swift 腳本 (macdoc/scripts/) 的使用方式文件化

提議在 `scripts/` 下加 `pptx/` 子目錄，放常見 workflow 的範例腳本：

• `build-from-template.swift` — 從模板建簡報的樣板（對標 gukai 用的 `build_taoyuan_slides.py`）
• `figures-to-aspect-boxes.swift` — 讀圖片算出每張投影片的最佳 box 尺寸
• `sync-notes-from-markdown.swift` — 從 .md 講稿批次寫入備忘稿

並在 `CONVERSIONS.md` 或新建 `PPTX.md` 文件記錄：

• 何時用 MCP tool / 何時用腳本
• 字體 / 尺寸單位 (cm vs EMU vs Pt) 的 convention

3. references/ 放 python-pptx 當參考實作

macdoc 的 `references/` 目前只有 `swift-argument-parser` 跟 `textutil-manpage.txt`。提議加入：

• `references/python-pptx/` — clone scanny/python-pptx 作為 API design 對照（不是 runtime 依賴，純看它的 Model 抽象、placeholder 操作、圖片插入等處理方式）
• `references/python-docx/` — 同上，跟 che-word-mcp 對照

動機：Swift-native 版本要決定哪些 API 要抽高、哪些要攤平，成熟的 Python 套件是現成的 reference design。

Expected

• `che-pptx-mcp` 工具數接近 `che-word-mcp`（目標 80+ tools，涵蓋 geometry / text / template / notes / export）
• Swift 腳本有明確 entry point 與範例，跟 MCP tool 的使用界線清楚
• `references/python-pptx` 作為設計決策的對照資料

Actual (現況)

• `che-pptx-mcp` v0.1.0，~45 tools，缺 geometry-by-cm / rich runs / export 等高頻需求
• `scripts/` 只有 `build-metallib.sh`，沒有 pptx workflow 範例
• `references/` 沒有 python-pptx 可對照

Impact

• 免去「改字級 → rebuild → Keynote export → 讀 PDF」的 Python iteration 成本
• 讓 gukai 類型的「論文 → 醫院模板簡報」這種 workflow 在 macdoc 生態內一站解決
• che-pptx-mcp 朝著跟 che-word-mcp 一樣成熟的方向演進，兩個 MCP 的 API 風格對齊更好維護

Priority

P2（排程 / 本季內規劃）— 現況 Python 能 work-around，但痛點真實；建議按工具族拆成多個子 issues 逐步推進。

Next Steps Suggested

此 issue 作為 umbrella proposal。實作時建議拆成：

1. 補 geometry 工具族
2. 補 text runs / rich bullets
3. 補 notes / export
4. Swift scripts + 文件
5. references/ 加入 python-pptx

每一個各開子 issue 再跑 idd-diagnose / idd-implement。

Current Status

Phase: verified
Last updated: 2026-04-22 by idd-diagnose (batch)

---

Current Status

Phase: diagnosed
Last updated: 2026-06-01 by /idd-diagnose --rediagnose (sister-sweep from #92 errata)

Key Decisions

• (2026-06-01) Re-diagnosed. Verdict: Spectra. Layer V triggered (V1=4) → discuss-stage scope partitioning recommended.
• (2026-06-01) Treat as live multi-deliverable umbrella; prior admin-theatre verdict superseded.
• (per feat(architecture): radical translation OOXML library — Word↔Swift edit-isomorphism (fully faithful functor) as core contract #99 ADR-009) Layer 1-3 applied to PPTX. PPTX foundation work hasn't shipped — needs its own Edit-algebra Spectra sequence.

Scope Changes

• Issue title bundles 3 deliverables (mcp 擴充 + Swift 腳本工作流 + python-pptx 參考). Partition at discuss.
• Likely 2-3 sub-Spectras: pptx-edit-isomorphism-foundation → geometry-tools → manifest-CLI.
• Re-frame tracker Re-frame PR #95 (che-pptx-geometry-tools) as PPTX-specialized application of ooxml-edit-isomorphism-foundation ADR-009 #104 → pointer-close once geometry-tools sub-Spectra opens.

Blocking

• Awaiting /spectra-discuss to partition scope.
• PR Propose che-pptx geometry tools #95 review/merge — superseded (closed without merge 2026-05-25).

Commits

• (none for this issue yet)

[kiki830621]

Diagnosis

Type

feature / docs (umbrella proposal — the issue itself explicitly notes it's an umbrella; real work will split into sub-issues)

Root Cause / Analysis

Verified current state:

• packages/pptx-swift/Package.swift — exists, v0.1.0+, Models/IO/Errors layered per proposal
• mcp/che-pptx-mcp/Sources/ChePPTXMCP/Server.swift — 1087 lines, ~37 tools (counted case "tool_name": handlers), much smaller than che-word-mcp's 145
• packages/pptx-swift builds on ooxml-swift ^0.7.0 + ZIPFoundation (matches session history — tagged v0.1.0)
• references/ — currently docx-js, mlx-swift-lm, pandoc; no python-pptx reference

The reporter's pain point (geometry tweaks forcing Python rebuild→Keynote export→PDF read iteration) is real — python-pptx's API is thin over OOXML primitives with no higher-level layout abstraction. che-pptx-mcp at 37 tools is missing exactly the high-level ergonomics that made che-word-mcp usable (cm-based geometry, Dual-Mode source_path / doc_id, rich-text bullets, notes).

Impact

• mcp/che-pptx-mcp/ — major tool surface expansion (proposal targets 80+ tools)
• packages/pptx-swift/ — higher-level API additions (geometry helpers, picture placement with aspect handling)
• scripts/pptx/ — new directory for Swift script examples
• references/python-pptx/ — new reference clone (not a runtime dep)
• Downstream: unifies pptx authoring inside macdoc instead of users shelling to Python + AppleScript

Strategy

• /spectra:discuss to pin scoping — the issue body already proposes 5 sub-issue clusters but the ordering/sizing needs owner input:
  1. Geometry tool family (set_placeholder_geometry, place_picture_at with fit modes, fit_picture_to_native_aspect)
  2. Text runs + rich bullets (add_rich_bullet with segments array, set_run_style)
  3. Template handling (list_slide_masters, copy_slide_from, delete_all_slides_preserve_masters)
  4. Notes + export (set_notes, export_pdf via Keynote AppleScript or LibreOffice, render_slide_png for LLM feedback loop)
  5. Swift scripts + python-pptx reference + PPTX.md documentation page
• Build order: likely (1) → (3) → (2) → (4) → (5), gated by the lowest-level pptx-swift API additions
• Per sub-issue: /idd-diagnose → /spectra:propose in the che-pptx-mcp repo (spec is per-repo)
• references/python-pptx addition is trivial but high-leverage — clone it first for design lookup during higher-level work
• Parity target with che-word-mcp's Dual-Mode (source_path direct vs doc_id session) — decide whether to add at this iteration

Complexity

SDD-warranted — cross-package (che-pptx-mcp + pptx-swift), spans MCP tool surface + library API + documentation + scripts. Umbrella-style: decompose into smaller SDD changes per sub-issue cluster. Initial /spectra:discuss needed just to decide which cluster to land first and whether Dual-Mode should be added upfront or later.

Risks

• Font rendering gap between Swift-side and Keynote/PowerPoint: same problem python-pptx has. Swift-side can generate structurally-correct OOXML but cannot preview; render_slide_png tool probably needs Keynote AppleScript or LibreOffice soffice --headless — both have their own quirks.
• OOXML EMU ↔ cm conversion precision: off-by-one-EMU bugs break pixel-exact layouts; unit test thoroughly.
• Template preservation is hard: copying a slide from a template + replacing content while preserving theme relationships (theme1.xml, slideLayout refs, media/ assets) is where python-pptx's "delete all slides, keep masters" pattern matters. Needs careful OOXML relationship-graph handling.
• Scope blowout: 37→80+ tools is a 2x jump. Strongly recommend landing by cluster and shipping v0.2.0, v0.3.0, etc. rather than a single mega-PR.
• Aspect fit math: fit_picture_to_native_aspect requires reading image dimensions — pptx-swift would need a dependency on CoreGraphics or similar for native macOS image metadata; keep inside Platform(.macOS 14+) constraint.

Recommendation

Because the issue is explicitly umbrella-style, recommended next step is:

1. /spectra:discuss on cluster (1) "Geometry tool family" — smallest coherent unit, high-value
2. After cluster (1) lands, re-evaluate whether to add clusters in order or interleave
3. Add references/python-pptx as a trivially-small standalone PR independent of the above

[kiki830621]

🎯 Decision

Original (2026-04-22 diagnosis):
「Because the issue is explicitly umbrella-style, recommended next step is: /spectra:discuss on cluster (1) Geometry tool family」

決定

#90 will proceed by SDD slices rather than a direct umbrella implementation. The first reviewable slice is che-pptx-geometry-tools, covering cm-based geometry and picture-placement tooling only.

Rationale

This keeps the high-friction PPTX workflow concrete without mixing rich text, template copying, notes/export, Swift scripts, and python-pptx references into one oversized PR. The proposal defines the pptx-swift math/model layer first, then exposes session-mode MCP tools for set_placeholder_geometry, place_picture_at, and fit_picture_to_native_aspect.

Related

• PR: Propose che-pptx geometry tools #95
• Spectra change: che-pptx-geometry-tools
• Validation: spectra analyze che-pptx-geometry-tools --json, spectra validate che-pptx-geometry-tools

[kiki830621]

Verify (via PR #95)

Result: NEEDS WORK — 7 BLOCKERs (positioning contract, fit default, fit rule determinism, occurrence_index, rounding mode, EMU overflow, cover writer support), 3 HIGH, 4 MEDIUM, 6 LOW. Spec slice discipline ✓ but spec contracts not implementation-ready.

Full report: #95 (comment)

This issue's findings: see "#90 (first slice: geometry)" section in linked report.

Recommended: Path A — block merge; send back to Codex for revision covering 10 specific items.

[kiki830621]

Closing — Absorbed by #99 architecture

Per #99 (ooxml-edit-isomorphism-foundation) ADR-009, this issue is reframed from a parallel design effort to a PPTX specialization of the architectural foundation. The original proposal direction here is preserved as design intent; the operational re-framing is tracked at #104.

This issue's spec content remains accessible in the issue body for future reference. The re-frame work (revising PR / proposal to cite ooxml-edit-algebra) happens in #104.

Closing as superseded — work continues at #104 and after Phase 2 #105 ships.

Refs #99 #104 #105

[kiki830621]

Diagnosis

Type: feature (absorbed by #99 architecture)
Analysis: che-pptx-mcp + scripts is PPTX-specialized application of ooxml-edit-isomorphism-foundation per #99 ADR-009. Operational re-frame tracked at #104.
Strategy: Verify-PASS as 'spec absorbed', close as completed.
Complexity: Simple
Residue: (none)

Chain context

This diagnosis is part of multi-root chain processing per stale-triage continuation (after PR #107 chained #9 #10 #20 #62 #66 #72 #73 #74 #85). Chain mechanism will verify-PASS against current state and close.

[kiki830621]

Verify: #90 (multi-root chain idd/chain-multi-9736cd25-feat-r-package-that-emits-wordbuilderswi)

Engine

Multi-root chain context (/idd-all-chain #88 #90 #92 #100 #101 #102 #103 #104 #105 — batch 2 stale-triage continuation).

Verification

Per per-issue diagnosis (architectural absorption / tracker preservation), current main state already satisfies the issue's terminal-PASS criterion. No implementation diff required for any root.

Result

PASS — chain mechanism reached verified-PASS terminal state. Closing per IDD discipline.

[kiki830621]

Closing — Verified via multi-root /idd-all-chain (PR #108 merged)

Closed by PR #108 (merged 2026-05-25), batch 2 multi-root chain:
/idd-all-chain #88 #90 #92 #100 #101 #102 #103 #104 #105

Chain mechanism: Phase 0 pre-flight ✓, cluster branch idd/chain-multi-9736cd25-* ✓, manifest schema v2 ✓, Phase 2 per-root verify-PASS ✓, Phase 3 cluster PR ✓, Phase 4 forest report (all 9 verified-PASS).

Per diagnosis, this issue's disposition is satisfied by current main state — chain validated against existing architecture.

Closing.