文字講不清楚的，就讓讀者自己操作。
【技術領域】
【0001】本工作台用於撰寫與閱讀技術筆記：流程、比較、架構、策略，這些只用文字很難講清楚的知識。
【先前技術】
【0002】傳統筆記工具只能顯示文字。想把一段流程講清楚、把兩個方案並排比較，或讓讀者親手拖動看兩種策略的差異，只能貼一張靜態圖，或附一個連結。
【0003】靜態圖會過時、改不動、也不能互動；而存在雲端服務裡的筆記，離開那個服務就讀不到，AI agent 也碰不到。
【內容】
【0004】
筆記留在你的 git repo 10。在需要圖的地方寫一段 @ai-visualize 標記 30，描述你想要的樣子；
作者在本機的 Claude Code 對話裡處理它，生成一個 React 元件 16，驗證通過後寫回筆記。
元件是原始碼，跟筆記一起 commit。它可以被 review、被鎖定不再重生，也能原樣搬進放大畫布與簡報 62、64。
一段描述，一個能操作的元件。
標記寫在筆記裡要放圖的位置。處理完，標記下方多了一行 import 和一行 JSX，status 改成 generated； 之後想重做就改 prompt，不想再動就改成 locked。
30{/* @ai-visualize32id: visualize-pipeline34type: | | 36prompt: | 畫出 @ai-visualize 從標記到寫回筆記的流程： 四個 subagent 依序接力， 驗證沒過就不寫回。38status: generated*/}40<VisualizePipeline client:visible />
點上面的 type，右邊的元件就換成那一種。
- 失敗自動修，最多 3 次
- 驗證通過才往下
掃描 MDX，找出 status 是 pending 的標記，順便列出孤兒元件。
@ai-visualize · visualize-pipeline · type: diagram畫出 @ai-visualize 從標記到寫回筆記的流程：四個 subagent 依序接力，驗證沒過就不寫回。
在 Claude Code 對話中處理後，這裡會換成元件。
文件，像程式碼一樣管理。
在 AI 時代，文件最好的位置是 repo 50。筆記 52、生成元件 54、plugin 與系列設定 56 都是純文字檔，放在同一個 git repo 裡：可以 diff、可以開 PR review、可以回到任何一個版本。
【0007】Claude Code 讀得懂整個資料夾，所以它能找到待處理的標記、生成元件、再寫回原處。npx notecraftapp init-skill 會把需要的 skill 與 subagent 裝進 .claude/ 58。
這是一次生成在 git 裡留下的樣子：筆記裡改了 status、多了 import 和外框，元件是一個新檔。
{/* @ai-visualize
id: oauth-flow
type: diagram
- status: pending
+ status: generated
*/}
+ import OauthFlow from '@notes/components/oauth-flow'
+ <GeneratedFrame id="oauth-flow" type="diagram">
+ <OauthFlow client:visible />
+ </GeneratedFrame>FIG. 3 與 FIG. 4
- my-project/50
- notes/52
- guides/oauth/flow.mdx
- http-caching.mdx
- schema.er.json
- .notecraft/
- components/oauth-flow.tsx54
- plugins.json · series.json56
- .claude/ skills · agents58
- notes/52
實施方式：從你想做的事開始。
點上面換一件事，點右邊的步驟看細節。
【實施例一】在本機閱讀與寫作
【0009】view 開 Astro dev server：新增、編輯、刪除筆記即時反映，標籤可以直接在頁面上改。
serve 服務 build 好的靜態站，背景 rebuild 並自動重新整理；Claude Code 在另一個終端機寫檔，這邊的瀏覽器跟著更新。
【實施例二】部署給團隊
【0011】build 輸出純靜態網站，沒有 Function、沒有執行期 API，任何靜態主機都能放。本站的 Demo 工作台 就是用同一套 build 出來、放在 GitHub Pages 上的。
【實施例三】結構化資料
【0012】同一種形狀的資料反覆出現時，交給 plugin：官方提供 ER 圖與 OpenAPI 文件兩個渲染器，資料檔放在筆記資料夾裡，build 時驗證 schema，不符就直接失敗。
【0013】多篇筆記可以串成系列，有順序、有進度；資料檔頁也能是其中一章。
指令一覽
npx notecraftapp view ./docs在本機開 Astro dev server。新增、編輯、刪除筆記即時反映，標籤可以直接在頁面上改。
它做得到的事，一條一張圖。
- 1.
你的資料夾原封不動，npx 一行就開。
請求項 1一種筆記工作台，讀取使用者既有之 md／mdx 資料夾，不搬移、不轉存，以單一指令啟動。
- 2.
寫一段描述，得到一個能操作的元件，而且是你 repo 裡看得到的原始碼。
請求項 2如請求項 1 所述之工作台，其中筆記內以 @ai-visualize 標記描述圖表，經作者本機之 Claude Code 生成 React 元件並寫回該筆記。
- 3.
壞掉的元件不會出現在你的筆記裡。
請求項 3如請求項 2 所述之工作台，其中元件未通過型別檢查與建置驗證前，不寫回筆記。
- 4.
一張圖畫一次，讀筆記、放大看、上台報告都是同一個。
請求項 4如請求項 2 所述之工作台，其中同一元件得於筆記、放大畫布及簡報中原樣使用，互動功能保留。
- 5.
ER 圖、OpenAPI 文件交給 plugin，不必手寫成筆記。
請求項 5如請求項 1 所述之工作台，其中結構化 JSON 資料檔由可安裝之 plugin 渲染為頁面。
- 6.
GitHub Pages、Netlify 或任何靜態主機都能放。
請求項 6如請求項 1 所述之工作台，其輸出為純靜態網站，不依賴執行期 API。
- 7.
文件就是 codebase：可以 diff、review、回溯，AI agent 也直接讀寫。
請求項 7如請求項 1 所述之工作台，其中筆記、生成元件及資料檔皆以 git 管理。
本頁借用專利說明書的版面形式來介紹功能；NoteCraftApp 是 MIT 授權的開源專案，並未申請專利。
持續在改。
2026-07-09 第一次發佈，到 2026-10-07 共 38 個版本。每一版都記在 repo 的 CHANGELOG.md。
1.12.0
- 1.12.0 10/07
- 1.11.0 10/06
- 1.10.1 10/04
- 1.10.0 10/04
- 1.9.0 10/03
- 1.8.5 10/02
- 1.8.4 10/02
- 1.8.2 10/02
- 1.8.1 10/02
- 1.8.0 10/02
- 1.7.0 10/01
- 1.6.0 10/01
- 1.5.1 09/30
- 1.5.0 09/30
- 1.4.1 09/29
- 1.4.0 09/29
- 1.3.0 09/27
- 1.2.3 09/26
- 1.2.2 09/25
- 1.2.1 09/25
- 1.2.0 09/22
- 1.1.1 09/22
- 1.1.0 09/22
- 1.0.1 09/22
- 1.0.0 09/22
- 0.6.0 09/18
- 0.5.1 08/12
- 0.5.0 08/12
- 0.4.0 08/02
- 0.3.0 07/31
- 0.2.4 07/10
- 0.2.3 07/10
- 0.2.2 07/10
- 0.2.0 07/10
- 0.1.3 07/09
- 0.1.2 07/09
- 0.1.1 07/09
- 0.1.0 07/09