時隔四個月左右，我重新回到 MD2DOC-Evolution。
這次不是從零開始做一個新工具，而是把已經有人使用的 MD2DOC-Evolution 再往前推一段：新增更完整的功能、整理內部結構、補強測試與 CI，讓它從「能用」變得更穩、更像一個可以長期維護的開源專案。
最大的差異是，這次我改用 Codex 協助開發與重構。
它不是只幫我生幾段程式碼，而是參與規劃、改 React / TypeScript、整理 UI、補測試、跑驗證、協助我把專案推向更穩定的版本。
所以這篇文章想記錄的，不是版本流水帳，而是這次我實際新增了哪些功能，以及 Codex 如何讓這個開源專案變得更強大。
本文依據我在 2026-06-15 查閱的 GitHub README 與專案狀態整理。開源專案仍會持續變動，所以這篇記錄的是這一輪改造的功能與設計取捨。
這次新增與強化了什麼
這輪改造的目標很清楚：讓 MD2DOC-Evolution 更像一個真的可以每天打開使用的技術寫作工作台。
我主要做了幾件事：
- 重構成專業工具台 UI，讓寫作、預覽、匯出更集中。
- 重設 AI Agent Prompt，讓外部 AI 更容易產出符合工具格式的 Markdown。
- 建立
syntaxSpec，讓語法規格有單一來源。 - 加入匯出前驗證，降低 DOCX 匯出前的格式風險。
- 改善首次載入效能，把 DOCX 與 Mermaid 相關能力延後到需要時才載入。
- 補強 README、CI 與測試，讓專案更容易維護，也更適合接受後續改動。
如果要用一句話總結：
這次不是把功能堆上去，而是讓功能、規格、測試與開發流程開始站在同一條線上。
這次改造的核心：不要做成 landing page，要做成工作台
MD2DOC-Evolution 的定位一直很清楚：它不是一個展示頁，也不是一個只給人看 feature list 的產品頁。
使用者打開它，是要寫稿、預覽、匯出。
所以這次 UI 重構的方向，不是把首頁做得更像行銷網站，而是把它整理成更像日常會使用的專業工具台：
- 上方是 command bar，放專案狀態、主要操作與 AI Prompt 入口。
- 左側是 Markdown 快速鍵，讓常用語法可以直接插入。
- 中間是稿件編輯區，保留主要寫作節奏。
- 右側是 Word print preview，讓使用者不用一直匯出才知道版面長怎樣。
這個方向對我來說很重要。
很多工具長得很漂亮，但使用者一進來還要先穿過一堆介紹、按鈕、卡片與轉場，才終於開始工作。對 MD2DOC-Evolution 這種工具來說，那些東西反而是摩擦。
我想要的第一畫面，是「可以直接開始寫」。
這次 Codex 幫我把原本比較鬆散的 editor、preview、command、quick action 結構重新整理，也補上幾個會影響操作體驗的 UI 細節，例如左側 Markdown 快速鍵的層級、AI Agent Prompt modal 的顯示與互動。
這些不一定是最炫的改動，但它們會直接影響使用者願不願意待在這個工具裡繼續寫。
AI Prompt 不再只是提示詞，而是工具的外部協作入口
這次我特別重做了 Header 裡的 AI Prompt。
原本的 Prompt 比較像一段靜態說明：告訴使用者可以怎麼請 AI 產生稿件。但這樣其實還不夠，因為 AI 很容易產出「看起來像 Markdown，但不完全符合工具支援格式」的內容。
所以新的 AI Agent Prompt 做了幾件事。
第一，它直接附上 GitHub Repo：
https://github.com/eric861129/MD2DOC-Evolution
這讓使用者可以把 Prompt 丟給 ChatGPT、Claude、Codex 或其他 AI Agent，請它依照 MD2DOC-Evolution 的格式產出內容。
第二，它不只說「請產生 Markdown」，而是更明確地定義輸出 contract。
它會提醒 AI 要遵守 Frontmatter、TOC、Heading、Code block、Mermaid、Callout、Table、Chat / Dialogue、Image / Link 等格式，也會要求最後只輸出 Markdown 原稿，不要混入額外解釋。
這個小改動背後其實有一個更大的想法：
如果工具要和 AI Agent 協作，Prompt 就不能只是文案，它要變成規格的一部分。
Prompt 寫得含糊，AI 就會發散。Prompt 寫得像 contract，AI 才比較有機會產出可直接進工具的稿件。
syntaxSpec：把語法規格集中，避免文件、UI、Prompt 各講各的
這次我也新增了 syntaxSpec，把 MD2DOC-Evolution 支援的 Markdown 語法集中管理。
它涵蓋的範圍包含：
- Frontmatter
- TOC
- Heading
- Code block
- Mermaid
- Callout
- Table
- Chat / Dialogue
- Image / Link
為什麼這件事重要？
因為一個工具做久了，很容易出現規格漂移。
README 寫一套，AI Prompt 寫一套，slash command 插入的模板又是另一套，測試 fixture 再長出第四套。短期看只是小差異，長期就會變成維護成本。
這次我讓 slash command、quick action、AI Prompt 都開始往同一份語法規格靠攏。未來如果要新增或調整 Markdown 語法，理想狀態不是到處搜尋字串改文案，而是先回到語法規格源頭。
對開源工具來說，這很像把「使用說明」升級成「可被程式使用的規格」。
匯出前驗證：不要等 Word 打開才發現怪怪的
MD2DOC-Evolution 的使用情境很明確：最後要匯出 DOCX。
這代表使用者最怕的不是「畫面上暫時有一點小問題」，而是辛苦寫完後匯出 Word，才發現內容格式不對、圖片出不來、表格壞掉、程式碼區塊少了語言標籤。
所以這次新增了匯出前驗證。
它的設計不是阻擋使用者，而是「警告但不阻擋」。匯出 DOCX 前會提醒可能有問題的地方，例如：
- Frontmatter 缺少
title或author。 - Code block 沒有指定語言。
- Mermaid 語法可能有問題。
- 圖片可能無法匯出。
- 表格分隔列格式可能錯誤。
這對非工程使用者很重要。
工程師看到錯誤可能會自己猜原因，但一般內容創作者更需要工具在匯出前先講清楚：「這裡可能會影響輸出結果，你要不要先看一下？」
驗證不是越吵越好。
好的驗證應該像一個可靠的編輯提醒你：「這裡可能怪怪的。」而不是每次都把正常內容喊成災難現場。
首次載入效能：把重的東西延後到真的需要時
這次改造也處理了首次載入負擔。
MD2DOC-Evolution 會牽涉到 DOCX builder、Mermaid renderer、DOCX 匯出時的 Mermaid builder。這些能力很重要，但不是使用者一打開工具的第一秒就全部需要。
所以我把幾個重點路徑改成 lazy load：
- DOCX builder 只在使用者真的匯出 DOCX 時載入。
- Mermaid renderer 只在內容真的有 Mermaid block 時載入。
- DOCX 匯出中的 Mermaid builder 也改成遇到 Mermaid block 才載入。
這類調整看起來不像 UI 改版那麼有存在感，但對工具體驗很有感。
使用者最先需要的是進入編輯狀態，而不是先下載所有可能用到、但這次也許根本不會用到的能力。
README、CI、測試：讓開源專案不只「我這台能跑」
開源專案要能讓別人接近，文件和驗證流程就不能太隨性。
這次我更新了中英文 README，讓功能描述、啟動方式、測試命令、版本資訊更一致，也新增 npm run verify 作為統一驗證入口。
現在驗證流程不再只看 build。
npm run verify 會串起 typecheck、unit/component tests 與 production build。CI 也改成跑完整 verify，Deploy workflow 在部署前會先跑 typecheck 和 test。
測試也補強了幾個方向：
- AI Prompt modal 測試。
- command model 測試。
- syntax spec 測試。
- export validation 測試。
- lazy boundary 測試。
- README / public content smoke test。
- parser fixture 測試。
- DOCX smoke assertion。
這些測試不是為了讓數字看起來漂亮，而是為了讓後續改動比較敢動。
特別是這種「Markdown 語法、Preview、DOCX 匯出」互相牽連的工具，如果沒有測試，很容易修了畫面，壞了輸出；修了 Prompt，壞了語法範例；修了 lazy load，壞了匯出流程。
AI Agent 可以加速寫程式，但越是讓 AI 幫忙改，越需要穩定的驗證入口。
四個月後，我改用 Codex 參與開發與重構
我覺得這次最值得記錄的，不只是 MD2DOC-Evolution 新增了哪些功能，而是我開發方式的改變。
四個月前，我比較常把 AI 當成「幫我產生某段程式碼」的工具。這次我改成把 Codex 放進完整開發流程：先拆方向，再進入程式碼，最後用測試與實測收斂。
更接近這樣的節奏：
- 我先描述想把工具往專業工作台推進。
- Codex 幫我把需求拆成可執行計畫。
- 它直接修改 React / TypeScript 程式碼。
- 我用瀏覽器實測，確認實際操作體驗。
- 我把實測觀察回饋給 Codex。
- Codex 沿著既有程式碼繼續修正，而不是從頭猜一套新架構。
- 它協助跑
npm run typecheck、npm run test:run、npm run build、npm run verify。 - 最後整理變更內容，確認本地結果與 GitHub 上的版本一致。
這個流程很像真實開發。
不是一次完美生成，而是一直把「實測發現」放回工程循環裡。
以前我用 AI 寫程式時，最麻煩的是它很容易脫離現場。它可能可以回答問題，但不一定真的知道目前 repo 的狀態、測試結果、瀏覽器畫面與版本脈絡。
這次比較有感的是：Codex 可以跟著 repo 狀態往下走。
我不用每次重講整個專案。只要把新的問題說清楚，它就能回到現有檔案、現有測試、現有 diff 裡繼續處理。
我這次真正學到的事
這次我更確定一件事：
AI Agent 對開源專案最大的價值，不是替你省掉所有工程判斷，而是讓你更快把判斷落到程式碼、測試與驗證裡。
如果只是讓 AI 產出一段 code，效果有限。
但如果你把它放進完整開發流程，它可以幫你：
- 把模糊想法拆成任務。
- 沿著既有架構改程式。
- 依照實測回饋調整細節。
- 跑驗證命令。
- 補測試。
- 把每一次迭代留下可追蹤的紀錄。
這才是我覺得有趣的地方。
MD2DOC-Evolution 這次不是忽然變成一個巨大產品，它還是那個專門解決 Markdown 到 Word 技術書稿流程的小工具。
但它變得更像一個我願意拿來長時間工作的地方。
對 Side Project 來說，這是一個很重要的轉折。
你不一定要把它做大。
但你可以把它做得更穩、更清楚、更像真的有人會每天打開來用。
而這次 Codex 幫我做的，就是把這個小工具往那個方向又推了一段。