feat: dxedit — declarative docx edit CLI + library (manifest-driven, ooxml-swift direct, peer to che-word-mcp MCP front-end)

[kiki830621]

Problem

che-word-mcp exposes ~218 OOXML editing tools over MCP stdio JSON-RPC. Two real-world workflows have hit the limits of going through the MCP transport:

1. Replicable docx-edit pipelines — running the same edit plan against different docx baselines (e.g. template-population, content backfill, batch caption fix-ups) currently means either:
   • Manually re-driving 30+ MCP calls per run (lossy, error-prone), or
   • Writing one-off Python/Bash scripts that wrap MCP stdio (fragile, JSON-escape pain especially for CJK anchor text).
2. che-word-mcp integration testing — RealWorldDocxRoundTripSmokeTests covers open → save round-trip but not edit-path tests with non-trivial sequences (insert+replace+insert with anchors). A scriptable surface that drives the same ooxml-swift API che-word-mcp uses would let us assert end-to-end behaviour declaratively.

Both share the same need: a declarative way to describe a docx edit plan and execute it against ooxml-swift directly (no MCP transport overhead, no JSON escaping). MCP and this CLI become two front-ends on the same library.

Type

feature

Proposal

A new CLI + library inside macdoc/, sibling to mcp/che-word-mcp/:

macdoc/
├── mcp/che-word-mcp/         # existing (MCP front-end)
└── cli/dxedit/               # NEW
    ├── Package.swift         # depends on ooxml-swift (same dep as che-word-mcp)
    ├── Sources/
    │   ├── DxEditLib/        # library target — importable
    │   │   ├── Manifest.swift   # YAML/JSON decoding
    │   │   ├── Step.swift       # InsertImage / ReplaceText / InsertParagraph / InsertEquation / Verify
    │   │   ├── Executor.swift   # plan → execute → verify
    │   │   └── Verify.swift     # part-count, libxml2 validity, bookmark, font preservation checks
    │   └── dxedit/           # executable target — `dxedit` binary
    │       └── main.swift    # ArgumentParser → DxEditLib calls
    └── Tests/DxEditLibTests/

CLI surface

dxedit apply manifest.yaml --in baseline.docx --out output.docx
dxedit plan  manifest.yaml --in baseline.docx          # dry-run
dxedit verify --in baseline.docx --out output.docx     # post-condition assertions
dxedit diff a.docx b.docx                              # uses ooxml-swift compare API

Manifest sketch

baseline: archived/baseline.docx
output: docs/output.docx
steps:
  - insert_image:
      path: assets/figure_1.png
      anchor: { before_text: "<unique caption substring>" }
      width: 520
      name: fig_1
  - replace_text_batch:
      - { find: "<old>", replace: "<new>" }
  - insert_paragraph:
      anchor: { after_text: "<unique sentence>" }
      text: "<paragraph body>"
verify:
  expected_images: 23
  expected_bookmarks_min: 44
  libxml2_valid: true
  byte_preserved_parts:
    - word/header*.xml
    - word/footer*.xml
    - word/fontTable.xml
    - word/theme/*.xml

Why this lives in macdoc/ rather than a separate repo

• Same SPM dep graph as che-word-mcp (both depend on ooxml-swift)
• CLI changes often co-evolve with ooxml-swift API changes — atomic commits possible
• che-word-mcp integration tests can shell out to dxedit for declarative E2E coverage
• Workspace-style monorepo already established (macdoc/mcp/, macdoc/lib/, etc.)

A separate repo can be extracted later if the CLI grows beyond docx (e.g. unified dxedit / pxedit / pptedit toolkit), following the same pattern as #78 (NoteCore extraction) and #79 (pdf-to-latex-swift extraction).

Use cases

1. Template population — given a docx template with anchor markers, populate with structured content from a manifest.
2. Batch fix-up — apply caption format normalization across many docx files.
3. Reproducible workflows — a docx-edit pipeline checked into a project repo (scripts/edit/manifest.yaml + dxedit apply) is replayable and version-controlled.
4. che-word-mcp integration tests — declarative assertions about edit-path behaviour that supplement the existing round-trip XCTest suite.

Implementation phases

• Phase 1: minimal apply command, supports insert_image, replace_text, replace_text_batch, insert_paragraph steps. YAML manifest. SPM library target.
• Phase 2: verify command with post-condition harness (libxml2 validity, byte-preservation checks, content presence).
• Phase 3: plan (dry-run), diff (using ooxml-swift compare), archive-first integration (auto-snapshot baseline before mutating writes).
• Phase 4: extend step types as ooxml-swift API matures — insert_equation, wrap_caption_seq (depends on P2: helper to wrap plain-text captions in SEQ field for downstream TOF/TOT generation che-word-mcp#62), section/header/footer manipulation.

Caveats

• Anchor reliability: depends on ooxml-swift text-anchor support being uniform across all step types. P2: insert_paragraph / insert_equation lack after_text/before_text anchors — paragraph_index alone unreliable in real-world docx che-word-mcp#61 tracks the gap where insert_paragraph / insert_equation lack after_text / before_text anchors that insert_image_from_path already has. Phase 1 of dxedit may have to ship with paragraph_index only for those step types until feat: add --full and --css flags to SRT→HTML and MD→HTML output #61 is resolved.
• Manifest format choice (YAML vs JSON): leaning YAML for CJK anchor readability; JSON has stricter parsing but worse for human-edited multi-line strings. Open for discussion.

Priority

P2 — useful for downstream replicable workflows; not blocking any current work.

Related

• PsychQuant/che-word-mcp — same ooxml-swift dep, alternate MCP front-end
• P0 CRITICAL: save_document lossy re-serialization of document.xml — strips 32/34 namespace decls, wipes all bookmarks, drops text content che-word-mcp#56 (lossless round-trip — fixed in v3.13.5; baseline for dxedit verify)
• P2: insert_paragraph / insert_equation lack after_text/before_text anchors — paragraph_index alone unreliable in real-world docx che-word-mcp#61 (text anchors for insert_paragraph / insert_equation — affects dxedit step type completeness)
• P2: helper to wrap plain-text captions in SEQ field for downstream TOF/TOT generation che-word-mcp#62 (SEQ caption helper — natural dxedit step type once available)
• refactor: extract NoteCore / NoteToPDF as separate PsychQuant repos (packages 應該要是獨立套件) #78 / refactor: extract pdf-to-latex-swift + ocr-swift to PsychQuant repos; commit Tests/WordToMDTests fixtures (continues #78 pattern) #79 (pattern of extracting standalone packages; dxedit could be extracted similarly later)
• feat: R package that emits WordBuilderSwift scripts from R analysis results #88 (R package that emits WordBuilderSwift scripts — adjacent vision; manifest-driven dxedit is the "reader" half of that pipeline)

---

Current Status

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

Key Decisions

• feat: dxedit — declarative docx edit CLI + library (manifest-driven, ooxml-swift direct, peer to che-word-mcp MCP front-end) #92 remains SDD-warranted and now has a validated Spectra proposal.
• Phase 1 product entry is integrated macdoc docx ... subcommands, not a standalone dxedit binary.
• Scope covers build, patch, and apply workflows under one command namespace, plus plan, verify, and diff.
• Manifest contract is JSON/Codable-first for Phase 1; YAML remains out of scope until the schema has real usage.
• Library boundary is explicit: DocxWorkflowLib owns manifest decoding, planning, execution, verification, and diff; MacDocCLI stays thin.

Spectra Proposal

• Change: macdoc-docx-workflow-cli
• PR: Propose macdoc docx workflow CLI #94
• Files: openspec/changes/macdoc-docx-workflow-cli/proposal.md, design.md, tasks.md, and specs/docx-workflow-cli/spec.md
• Validation passed: spectra analyze macdoc-docx-workflow-cli --json, spectra validate macdoc-docx-workflow-cli, and git diff --check -- openspec/changes/macdoc-docx-workflow-cli

Blocking

• Waiting for PR Propose macdoc docx workflow CLI #94 review/merge.
• After the proposal is accepted, next action is /spectra-apply macdoc-docx-workflow-cli.
• Known limitation, not blocker: P3 enhancement: H₀ Unicode subscript anchors don't match flatten output (post-#85 follow-up) che-word-mcp#90 for anchors involving Unicode subscript forms such as H₀.

Commits

• 08d55b0 docs: propose macdoc docx workflow spec

[kiki830621]

Diagnosis

Type

feature

Root Cause / Analysis

本次診斷對象選定為 #92。原因：你沒有提供 issue 編號；搜尋 che-word-mcp 後，#75 是 umbrella 且已有註記「umbrella 不重複診斷」、#70 已關閉且已有 RCA，#92 則是開放中、尚無 diagnosis，且 Problem 直接描述 che-word-mcp 走 MCP transport 的限制。

#92 的核心問題不是「che-word-mcp 缺一兩個工具」，而是 replayable edit plan / deterministic test harness / direct Swift API surface 三件事目前沒有共同載體。che-word-mcp 仍適合 AI agent 互動式操作；dxedit 要補的是「把一串 Word 編輯動作變成可檢查、可重跑、可放進 CI 的 manifest」。

目前狀態與 issue body 建議之間有幾個重要差異：

• che-word-mcp 已前進到 v3.17.1（2026-04-28），README 宣稱 233 MCP tools，且 feat: add --full and --css flags to SRT→HTML and MD→HTML output #61/srt-to-html: 支援方括號 Speaker 格式 [Speaker N] #62 這批 anchor / caption workflow 已多數落地。feat: dxedit — declarative docx edit CLI + library (manifest-driven, ooxml-swift direct, peer to che-word-mcp MCP front-end) #92 不能再假設 che-word-mcp 僅有早期 v3.13.x 的能力邊界。
• macdoc root package 目前是一個既有 CLI：Package.swift 只輸出 macdoc executable，主入口在 Sources/MacDocCLI/MacDoc.swift，子命令是 convert/pdf/bib/config/ocr。issue body 提的 cli/dxedit/Package.swift 是新的 package 佈局，與現有 repo 風格不同，需要先做架構決策。
• 本工作樹的 mcp/che-word-mcp 是空的 submodule checkout；實作時不能假設可直接讀本地子模組原始碼。診斷改用 GitHub 上 PsychQuant/che-word-mcp 的目前 main 與 issue 狀態。
• root Package.swift 目前沒有 YAML parser dependency；現有 manifest 型 workflow（PDF pipeline）走 Swift Codable / JSON 風格。feat: dxedit — declarative docx edit CLI + library (manifest-driven, ooxml-swift direct, peer to che-word-mcp MCP front-end) #92 manifest 要選 YAML 還是 JSON，應在 spec 階段明確決定，而不是實作時順手加 dependency。

需求拆解如下：

• dxedit apply：讀 manifest，對 baseline .docx 執行一串 deterministic edit steps，寫出 output。
• dxedit plan：dry-run，解析 manifest 與 anchors，但不寫檔。
• dxedit verify：檢查 output 的 post-conditions，例如可被 ooxml-swift 讀回、預期圖片數、預期 bookmark 數、必要文字存在、關鍵 OOXML parts 未被非預期改動。
• dxedit diff：若 Phase 1 要做，應明確定義是 structural diff、revision diff，還是只是呼叫既有 compare API。
• DxEditLib：可被 che-word-mcp integration tests 或其他 Swift test target import，避免 CLI-only 設計造成測試只能 shell out。
• Manifest schema：需要穩定 enum / Codable model / versioning / validation error 格式。
• Anchor 語意：必須對齊 ooxml-swift / che-word-mcp 的 InsertLocation，避免 dxedit 重做一套相似但不完全相同的 anchor 規則。

目前仍開放、會影響 dxedit API 完整度的上游議題：

• PsychQuant/che-word-mcp#84：insertEquation lib API 仍未直接接受 InsertLocation，external Swift consumer 需要自己做 text anchor → index 轉換。
• PsychQuant/che-word-mcp#86：findBodyChildContainingText 類 helper 未公開，dxedit / rescue CLI 等外部 Swift consumer 會重複實作 anchor lookup，行為容易分歧。
• PsychQuant/che-word-mcp#85：Paragraph.flattenedDisplayText() 會漏掉 inline OMML 可見文字，before_text / after_text 若跨 inline math 會 silent mismatch。學術論文文件很容易踩到。

Impact

影響檔案（預估）：

• Package.swift：新增 DxEditLib library target 與 dxedit executable product，或改採 cli/dxedit/Package.swift 的 nested package。這是第一個必須決定的架構點。
• Sources/DxEditLib/ 或 cli/dxedit/Sources/DxEditLib/：manifest model、step model、executor、verify harness、anchor resolution adapter。
• Sources/DxEditCLI/ 或 cli/dxedit/Sources/dxedit/：ArgumentParser command surface。
• Tests/DxEditLibTests/：manifest validation、step execution、round-trip / verify tests。
• README.md / docs：新增 dxedit 使用方式與與 che-word-mcp 的責任分界。
• openspec/changes/...：需要正式 spec，因為這不是單點修補。

影響使用者流程：

• template population / thesis rescue / batch caption fix-up 可從「手動重打 MCP calls」轉為「manifest 可重跑」。
• che-word-mcp 的 integration tests 可用 declarative plan 描述複雜編輯序列，不必在測試中塞大量 JSON-RPC plumbing。
• CI 可直接跑 dxedit apply && dxedit verify，降低真實 .docx workflow 靠手動檢查的比例。

Strategy

• 先走 /spectra-discuss：決定 package placement（root package 新 target vs nested cli/dxedit package）、manifest 格式（JSON-first vs YAML dependency）、Phase 1 step 範圍、anchor 語意是否等待 fix: PageOCRRunner uses OCRCore.backend API (unblocks main build) #84/test: strengthen Note→HTML smoke assertions (media/ dir + size floor) #86/docs: skill 文件漏列 HTML→PDF via playwright（#69 已實作但 skill.md 仍標 textutil） #85。
• 用 /spectra-propose 寫正式 proposal：proposal 要引用 macdoc#92，並把 fix: PageOCRRunner uses OCRCore.backend API (unblocks main build) #84/test: strengthen Note→HTML smoke assertions (media/ dir + size floor) #86/docs: skill 文件漏列 HTML→PDF via playwright（#69 已實作但 skill.md 仍標 textutil） #85 標為 feature gates / known limitations。
• Phase 1 建議收斂：apply + plan + 最小 verify；step type 先放 replace_text_batch、insert_paragraph、insert_image，insert_equation 視 fix: PageOCRRunner uses OCRCore.backend API (unblocks main build) #84 決定是否先只支援 paragraph_index。
• 建立 DxEditLib，讓 manifest decode / validation / executor 不綁 CLI；CLI 只負責參數與輸出。
• 以 generated fixture 測試，不把私人 thesis / manuscript docx 放進 repo。測試要覆蓋 CJK anchor text、table cell、SDT、以及「anchor 找不到時不寫 output」。
• verify 先做可機械驗證的 post-conditions：ooxml-swift 讀回、必要文字/圖片/bookmark/SEQ fields 數量、指定 parts byte-preservation；不要把「Word UI 看起來正確」當自動驗收。
• 若採 YAML，必須在 proposal 中指定 dependency、錯誤訊息格式、與 JSON round-trip/範例產生策略；若採 JSON-first，文件要說明 CJK anchor readability 的取捨與後續 YAML 相容策略。

Complexity

SDD-warranted

原因：

• 改動跨 3+ 檔案且邏輯互相依賴：package manifest、library target、CLI target、tests、docs。
• 需要新的共用抽象：manifest model、step executor、verify result、anchor adapter。
• 有架構決策與 trade-off：root package vs nested package、YAML vs JSON、直接相依 ooxml-swift vs 透過 che-word-mcp semantics 對齊。
• 影響既有 capability / specs：che-word-mcp-insertion-tools、ooxml-content-insertion-primitives、word-builder-swift、E2E test infrastructure。
• Strategy 超過 5 個步驟且有順序依賴；若直接 implement，容易在 package 佈局或 manifest schema 上留下難改的早期決策。

Risks

• 重做 anchor 邏輯造成分歧：若 test: strengthen Note→HTML smoke assertions (media/ dir + size floor) #86 未解，dxedit 可能自己實作 findBodyChildContainingText，日後與 MCP / ooxml-swift 行為不一致。
• 誤以為 direct Swift = MCP parity：che-word-mcp 有 handler-level validation、tool error format、autosave / session semantics；dxedit 直接呼叫 lib 時需要自己定義等價的失敗語意。
• YAML dependency 決策過早：YAML 對人工編輯友善，但 Swift 生態的 YAML dependency 與錯誤訊息品質需要先評估。root package 目前沒有 YAML dependency。
• .docx 寫入安全：dxedit 是批次 writer，必須沿用 ooxml-swift atomic-save / byte-preservation 假設，並在 verify 階段針對未觸碰 parts 做檢查。
• 測試資料風險：真實學術文件常含個資與投稿內容；應使用 synthetic fixtures 或最小重現 docx。
• submodule checkout 狀態：本 repo 的 mcp/che-word-mcp 目前未 checkout。實作若需要 cross-repo test，必須先明確決定是初始化 submodule、用 GitHub release、還是只測 DxEditLib。

Recommended Next Action

Diagnosis 已完成並建議走 SDD：

/spectra-discuss

建議 topic：

dxedit manifest-driven docx edit CLI (#92): package placement, manifest schema, anchor API dependencies

如果你已經確定三個決策（root package、新增 YAML dependency、Phase 1 step 範圍），才適合 opt-out 直接走：

/spectra-propose

[kiki830621]

🎯 Decision

Original (2026-05-01)：
「對我想要都做，你可以建議怎麼整合成一個指令比較好」

決定

dxedit 不再作為第一階段的獨立使用者入口；第一階段收斂成 macdoc docx 子命令群，並同時承接三種 Word 工作流：新建 .docx、模板填值、既有 .docx 的 manifest-driven 編輯。底層仍應拆出可測試、可匯入的 library target，例如 DocxWorkflowLib 或 DxEditLib，讓 CLI 只處理參數、輸出與錯誤呈現。

Rationale

這個方向保留「都做」的產品野心，但避免讓使用者面對 macdoc、dxedit、word-builder-swift、che-word-mcp 多個彼此重疊的入口。npm docx 的優點是宣告式 builder 與 packer，適合新建文件；docx.js patcher 的優點是模板 placeholder 替換；che-word-mcp / ooxml-swift 的優點是讀既有文件、保留 OOXML 結構並做 anchor-based 修改。這三者應該整合在同一個 macdoc docx 命名空間，而不是拆成多個頂層指令。

建議的使用者介面如下：

macdoc docx build manifest.json --out output.docx
macdoc docx patch template.docx manifest.json --out output.docx
macdoc docx apply baseline.docx manifest.json --out output.docx
macdoc docx plan  baseline.docx manifest.json
macdoc docx verify baseline.docx output.docx --manifest manifest.json
macdoc docx diff a.docx b.docx

build 對應 word-builder-swift / npm docx 類的新建文件能力；patch 對應 template placeholder workflow；apply 對應原 #92 的 dxedit manifest-driven edit plan；plan、verify、diff 則提供可重跑與 CI 所需的檢查面。獨立 dxedit binary 可保留為未來 thin wrapper，一旦 macdoc docx apply 的 manifest schema 穩定，再視實際使用量決定是否公開。

Related

• feat: dxedit — declarative docx edit CLI + library (manifest-driven, ooxml-swift direct, peer to che-word-mcp MCP front-end) #92
• Tracking: Manuscript review automation (che-word-mcp + ooxml-swift + upstream clients) #75
• P3 enhancement: H₀ Unicode subscript anchors don't match flatten output (post-#85 follow-up) che-word-mcp#90

[kiki830621]

🎯 Decision

Original (2026-05-01):
「dxedit 要不要直接整合成macdoc而不要分指令」

決定

#92 now has a validated Spectra proposal in PR #94. Phase 1 uses integrated macdoc docx ... subcommands rather than a standalone dxedit binary, while keeping a future dxedit thin wrapper possible after the manifest contract stabilizes.

Rationale

The proposal keeps the product surface inside macdoc, which is simpler for agents and plugin documentation, and it separates the reusable implementation into DocxWorkflowLib so a later wrapper or tool front-end can call the same manifest/planning/execution code. The proposal also makes JSON/Codable the Phase 1 manifest contract, defines build/patch/apply as distinct workflows, and adds plan/verify/diff as first-class review commands before implementation begins.

Related

• PR: Propose macdoc docx workflow CLI #94
• Spectra change: macdoc-docx-workflow-cli
• Validation: spectra analyze macdoc-docx-workflow-cli --json, spectra validate macdoc-docx-workflow-cli
• Non-blocking upstream limitation: P3 enhancement: H₀ Unicode subscript anchors don't match flatten output (post-#85 follow-up) che-word-mcp#90 for Unicode subscript anchors