Powei Lee

Sprint 4 完成：Slidev 簡報系統整合

2025年11月18日 ｜5 分鐘閱讀 ｜ Drafted by Claude Code ｜ 草稿 ｜專案紀錄｜Slidev｜Obsidian

Sprint 目標

建立完整的 Slidev 簡報系統，讓我可以快速建立、編輯、審查、建立與部署簡報。

完成項目

1. Obsidian Vault 設定

建立獨立的 slides/ vault，與 blog vault 分離：

  • Blog vault: site/src/content/blog/
  • Slides vault: slides/

兩個 vault 都配置了：

  • 圖片自動貼上設定 (app.json)
  • 簡報模板 (.obsidian/templates/presentation.md)
  • Workspace gitignore 規則

2. Slidev 主題系統

完成品牌主題 slides/shared-theme/：

  • Flow/Drain 雙色模式
  • 設計代幣 (Design Tokens) 完整實作
  • 自訂 layouts (cover, center, default, two-cols)
  • 無障礙設計 (WCAG AA 對比度標準)

3. Landing Page 自動生成

build-all.js 腳本功能：

  • 自動發現所有簡報 (slides/*/slides.md)
  • 建立每個簡報為獨立子目錄
  • 生成 Landing Page (dist/index.html)
  • 按日期排序，最新優先
  • 使用品牌設計系統

4. Blog 指令重新命名

所有 blog 相關指令加上 /blog-* 前綴：

  • /blog-generate-seo - SEO metadata 生成
  • /blog-validate - 文章格式驗證
  • /blog-review - AI 品質審查
  • /blog-publish - 完整發布流程
  • /blog-optimize-images - 圖片優化檢查

5. Slides 完整工作流程

建立 6 個新指令：

/slides-create [name]

建立新簡報專案：

  • 複製模板結構
  • 互動式設定 frontmatter
  • 生成初始投影片
  • 安裝依賴

/slides-restructure [file]

AI 重構簡報內容：

  • 使用 Context7 查詢 Slidev 最佳實踐
  • 分析內容密度、佈局、動畫
  • 生成具體重構建議
  • Human-in-the-loop 確認後執行

/slides-validate [file]

格式驗證：

  • Frontmatter 完整性
  • Markdown 結構
  • Layout 語法
  • 程式碼區塊
  • v-clicks 正確性
  • 圖片路徑檢查

/slides-review [file]

AI 品質審查：

  • 敘事結構 (8 個維度)
  • 內容品質
  • 視覺設計
  • 互動節奏
  • 品牌一致性
  • 觀眾體驗
  • 生成評分與具體建議

/slides-build [name]

建立簡報：

  • 執行 Slidev build
  • 輸出到 dist/[name]/
  • 設定 base URL (子路徑部署)
  • 驗證建立結果

/slides-publish [name]

完整發布流程：

  1. 格式驗證
  2. 品質審查
  3. 圖片檢查
  4. 建立簡報
  5. 預覽確認
  6. Git commit & push
  7. Vercel 自動部署

技術架構

Monorepo 結構

/
├── site/                      # Astro 網站
│   └── src/content/blog/      # Blog Obsidian vault
│       └── .obsidian/
├── slides/                    # Slidev 簡報系統
│   ├── .obsidian/             # Slides Obsidian vault
│   │   └── templates/
│   ├── shared-theme/          # 品牌主題
│   │   ├── layouts/
│   │   └── styles/
│   ├── template/              # 簡報模板
│   ├── [presentation-1]/      # 簡報專案
│   ├── [presentation-2]/
│   ├── build-all.js           # 建立腳本
│   └── vercel.json            # Vercel 設定
└── .claude/commands/          # Claude Code 指令
    ├── blog-*.md              # Blog 工作流程
    └── slides-*.md            # Slides 工作流程

部署架構

  • Blog: powei.me (Vercel, 根專案)
  • Slides: slides.pwlee.xyz (Vercel, 獨立專案)

兩者共用同一個 Git repository，但部署到不同的 Vercel 專案。

使用流程

Blog 工作流程

# 1. 在 Obsidian 中撰寫文章
# 2. 執行 SEO 生成
/blog-generate-seo path/to/post.md

# 3. 驗證格式
/blog-validate path/to/post.md

# 4. 審查品質
/blog-review path/to/post.md

# 5. 發布
/blog-publish path/to/post.md

Slides 工作流程

# 1. 建立新簡報
/slides-create my-talk

# 2. 在 Obsidian 中撰寫內容
# 3. AI 重構優化
/slides-restructure slides/my-talk/slides.md

# 4. 驗證格式
/slides-validate slides/my-talk/slides.md

# 5. 品質審查
/slides-review slides/my-talk/slides.md

# 6. 建立 & 部署
/slides-publish slides/my-talk/slides.md

關鍵設計決策

1. 為什麼分離 Obsidian vaults?

決策: 兩個獨立的 vault

原因:

  • Blog 與 Slides 內容性質完全不同
  • 避免模板、設定混淆
  • 方便在 Obsidian 中快速切換

替代方案:

  • 單一 vault 用資料夾分類 → 太混亂

2. 為什麼 /blog-* 和 /slides-* 前綴?

決策: 明確的命名空間

原因:

  • 清楚區分工作流程
  • 避免指令名稱衝突
  • 使用者容易記憶與自動完成

替代方案:

  • 無前綴 → 容易混淆 (/validate 是 blog 還是 slides?)

3. 為什麼使用 Context7 in /slides-restructure?

決策: 查詢 Slidev 最新文件

原因:

  • Slidev 持續更新，API 可能變化
  • 確保遵循最新最佳實踐
  • AI 知識可能過時

效果:

  • 重構建議基於官方文件
  • 避免使用已棄用的語法

4. 為什麼 Human-in-the-loop?

決策: 所有 AI 建議需使用者確認

原因:

  • 尊重作者的表達風格
  • AI 不應自動改變內容語意
  • 給予使用者完全控制權

實作:

  • /slides-restructure: 逐項確認修改
  • /slides-review: 僅提供建議，不自動執行

學到的經驗

1. 模板設計很重要

問題: 初期模板過於複雜 (36 張投影片)

解決: 建立簡化版模板 (4 張投影片)

  • Cover slide
  • 大綱
  • 內容範例
  • 結尾

效果: 使用者更快上手

2. 驗證應分層

發現: 格式驗證 vs 品質審查是兩回事

實作:

  • /slides-validate: 技術正確性 (語法、結構)
  • /slides-review: 內容品質 (敘事、設計)

效果: 錯誤訊息更清晰

3. 自動化但保留彈性

平衡:

  • 完整流程: /slides-publish (6 步驟自動化)
  • 單步執行: 可單獨執行任意指令
  • 跳過選項: --quick, --skip-validation

效果: 適合不同使用情境

效能指標

  • 建立時間: 單個簡報 2-4 秒
  • 檔案大小: 平均 250 KB
  • 部署時間: Vercel 自動部署 10-15 秒

下一步 (Sprint 5?)

可能的改進方向：

  1. 簡報版本控制

    • 自動備份歷史版本
    • Rollback 功能

  2. 簡報分析

    • 投影片使用統計
    • 觀眾互動追蹤

  3. 匯出格式

    • PDF export
    • PPTX export (使用 Slidev export)

  4. 協作功能

    • 多人評論系統
    • 版本比較

總結

Sprint 4 成功建立完整的 Slidev 簡報系統，整合 Obsidian 雙 vault 架構，實作 /blog-* 和 /slides-* 兩套完整工作流程。

關鍵成就:

  • ✅ 6 個新指令全部實作完成
  • ✅ Context7 整合用於最佳實踐查詢
  • ✅ Human-in-the-loop 設計確保使用者控制
  • ✅ 品牌一致性維持 (Flow/Drain 雙色系統)
  • ✅ 完整文檔與使用範例

可用性驗證: 本篇文章即是使用 /blog-* 工作流程撰寫與發布！

常見問題

Sprint 4 的主要目標是什麼？
建立完整的 Slidev 簡報系統，包含雙 Obsidian vault 架構、品牌主題、自動建立腳本，以及完整的 /slides-* 工作流程指令，讓簡報的建立、審查與部署變得快速且系統化。

為什麼要分離 Blog 和 Slides 的 Obsidian vault？
因為 Blog 與 Slides 內容性質完全不同。分離 vault 可以避免模板和設定混淆，方便在 Obsidian 中快速切換工作環境，讓內容管理更清晰。

什麼是 Context7？為什麼用在 /slides-restructure？
Context7 是查詢最新技術文件的工具。在 /slides-restructure 中使用 Context7 查詢 Slidev 官方文件，確保重構建議基於最新最佳實踐，避免使用已棄用的語法。

Human-in-the-loop 設計是什麼意思？
所有 AI 建議都需要使用者確認後才執行。這尊重作者的表達風格與創作意圖，給予使用者完全控制權，AI 不會自動改變內容語意。

這個簡報系統可以試用嗎？
簡報系統已部署到 slides.pwlee.xyz。你可以參考文章中的技術架構與工作流程，用 Slidev 和 Obsidian 建立類似的系統。完整程式碼在 monorepo 中，包含所有 Claude Code 指令與主題設定。