stevelin-notes
個人筆記庫。筆記以 Markdown / MDX 撰寫，由 NoteCraftApp 呈現；
筆記內的 @ai-visualize 標記交給 Claude Code 生成可互動的 React 視覺化元件（圖表、示意圖為主），
也能把筆記轉成簡報播放。
內容
| 系列 / 筆記 | 路徑 | 說明 |
|---|
| 開始使用這個筆記庫 | docs/getting-started.mdx | 寫作流程：先寫文字，需要時下標記，由 AI 生成互動圖表 |
| 專案管理筆記（第零～五章） | docs/knowledge/project/ | 專案 vs 產品、Waterfall vs Agile、R&R、Waterfall SDLC、專案管理工具 |
| ER Diagram 範例 | docs/sample/ | 示範 er-diagram-renderer plugin，以 *.erd.json 描述資料表 |
快速開始
需求：Node.js ≥ 22（notecraftapp ≥ 1.2.1）。
npm install
npm run notes:dev
首次執行會把 viewer app 複製到 ~/.notecraft/app-<version>/ 並安裝相依套件，約需 3 分鐘。
常用指令
| 指令 | 作用 |
|---|
npm run notes:dev | 開發模式（HMR，可在 UI 新增／編輯筆記） |
npm run notes:dev:lan | 同上，綁 0.0.0.0 讓區網裝置瀏覽 |
npm run notes:serve | build 後靜態服務，背景 rebuild 並自動刷新（AI 生成元件時建議用這個觀察） |
npm run notes:serve:static | 純靜態、唯讀，不監看 |
npm run notes:build / notes:build:force | build 靜態站到 ~/.notecraft/cache/<hash>/dist/（force 忽略快取） |
npm run skill:install / skill:check / skill:update | 安裝、檢查、升級 Claude Code skill 到 .claude/ |
npm run plugin:list / plugin:install / plugin:remove <id> | 管理結構化 JSON 渲染 plugin |
額外參數用 -- 傳入，例如 npm run notes:dev -- --port 5000。
專案結構
stevelin-notes/
├─ docs/ 筆記根目錄（slug = 相對路徑去副檔名）
│ ├─ <主題>/<筆記>.mdx
│ └─ assets/illustrations/ 筆記用的獨立插圖（SVG）
├─ .notecraft/
│ ├─ components/<id>.tsx AI 生成的視覺化元件
│ ├─ components/<slug>.deck.tsx 筆記轉簡報產物
│ ├─ plugins/ 已安裝的渲染 plugin
│ ├─ series.json 系列閱讀路徑
│ └─ plugins.json plugin 映射
├─ .claude/ skill 與 subagent（由 skill:install 安裝）
├─ CLAUDE.md 撰寫與視覺化規範
└─ package.json
viewer app 與 build 快取放在 ~/.notecraft/，不在專案內。
寫作流程
-
在 docs/ 下新增筆記：有互動元件用 .mdx，純文字可用 .md；檔名 kebab-case，frontmatter 建議寫 title、description、tags。
-
內容有變化、取捨、流程或比較時，插入 @ai-visualize 標記：
{/* @ai-visualize
id: rate-limit-token-bucket
type: motion
prompt: |
核心洞察：token bucket 允許短暫爆量，但長期速率被固定。
互動：slider 調整請求速率，按鈕「突發 20 個請求」。
圖形：bucket 容量示意 + 請求時間軸 + token 數折線圖。
caption: 拖動速率，看 bucket 何時被耗盡
status: pending
*/}
-
對 Claude Code 說「處理 docs/xxx.mdx 的視覺化標記」，content-visualize skill 會生成元件並寫回筆記。
-
想轉成簡報時說「把 docs/xxx.mdx 轉成簡報」（content-present），或「用 note-deck 做 docs/xxx.mdx 的簡報」（先出設計構想再實作），於 /present/<slug> 播放。
完整的撰寫規範、視覺風格與 NoteCraft Markdown 擴充語法（Admonition、Tabs、Steps、Badge 等），請見 CLAUDE.md。
疑難排解
- 找不到
node：本機以 nvm 管理，先執行 nvm use 22.16.0。
- build 異常或想重來：刪除
~/.notecraft/cache/；舊版的 ~/.notecraft/app-<舊版>/ 可直接刪除。
- 新增的
.deck.tsx 需重啟 npm run notes:dev 才會被收錄。
