[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: diagnosed
Last updated: 2026-04-22 by idd-diagnose (batch)

---

Current Status

Phase: diagnosed / first Spectra slice ready
Last updated: 2026-05-02 by Codex

Key Decisions

• [docs/feature] 提議擴充 che-pptx-mcp + Swift 腳本工作流；references/ 放 python-pptx 當參考 #90 remains an umbrella issue and should proceed through SDD slices, not one direct implementation.
• First slice selected: cm-based PPTX geometry and picture-placement tooling.
• The first slice modifies pptx-slide-write and pptx-mcp-server capabilities only.
• Later slices remain out of scope for PR Propose che-pptx geometry tools #95: rich bullets/run styling, template handling, notes/export/rendering, Swift scripts, and references/python-pptx.

Spectra Proposal

• Change: che-pptx-geometry-tools
• PR: Propose che-pptx geometry tools #95
• Files: openspec/changes/che-pptx-geometry-tools/proposal.md, design.md, tasks.md, specs/pptx-slide-write/spec.md, and specs/pptx-mcp-server/spec.md
• Validation passed: spectra analyze che-pptx-geometry-tools --json, spectra validate che-pptx-geometry-tools, and git diff --check -- openspec/changes/che-pptx-geometry-tools

Blocking

• Waiting for PR Propose che-pptx geometry tools #95 review/merge.
• After the proposal is accepted, next action is /spectra-apply che-pptx-geometry-tools.

Commits

• 3253893 docs: propose che-pptx geometry tools

[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