open-slide 詳細教學

對應 repo: https://github.com/1weiho/open-slide（3.5k stars / 248 forks / @open-slide/core@1.6.0，截至 2026-05-22）

1. 專案定位

1.1 它是什麼

1weiho (Yiwei Ho) 開源的 agent-native React 簡報框架。核心理念：「slides are visual code, agents are great at writing code; the missing runtime turns ‘make slides about X’ into a polished deck」。一行 npx @open-slide/cli init scaffold workspace，餘下交給 agent + 內建 5 個 skill。

1.2 它解決什麼問題

1.3 與其他 slide / presentation tool 差異

web-video-presentation 與 open-slide 是互補關係：前者是 skill 自己提供 scaffold；後者是 framework 提供 scaffold + 自帶 skill。

1.4 適合誰用

• 需要簡報的工程師 / DevRel / 技術寫作者：寫 conf talk / company all-hands / product demo / 教學影片預先排練
• AI 顧問 / 課程講師：用 agent 快速產內容變化（同一主題多份不同 deck）
• 設計工程師：把 deck 當 React 練習場，順便看設計細節
• 想學「agent-native framework 怎麼設計」的人：本 repo 是極佳 reference（skills-lock 機制、@slide-comment 制度、scaffold 模式）

2. 安裝指南

2.1 一行 scaffold（最快路徑）

1npx @open-slide/cli init my-slide
2cd my-slide
3pnpm dev

scaffold 出來的結構：

1my-slide/
2├── slides/intro/index.tsx          # 第一張 demo slide
3├── themes/                         # theme 設定
4├── assets/                         # images / videos / fonts
5├── open-slide.config.ts            # framework config
6├── AGENTS.md / CLAUDE.md           # agent 守則
7├── netlify.toml / vercel.json      # deploy 預設
8├── package.json
9└── tsconfig.json

2.2 既有 workspace 手動串

1# 純加 @open-slide/core 進去（不用 scaffold）
2pnpm add @open-slide/core
3# 在 vite.config.ts 加 plugin（看 packages/core/README.md）

2.3 環境需求

• Node.js >= 18（建議 20+）
• pnpm 10.x（package.json packageManager: pnpm@10.17.0）
• 一個 coding agent（Claude Code / Codex / Cursor 任一）
• 瀏覽器（Chrome / Edge / Firefox / Safari 任一現代版）

2.4 框架本身開發環境（contributor）

1git clone https://github.com/1weiho/open-slide
2cd open-slide
3pnpm install
4pnpm dev           # turbo: runs demo against local core
5pnpm build         # build all
6pnpm typecheck     # tsc across graph
7pnpm check         # biome (format + lint + organize imports)
8pnpm test          # vitest

flowchart TD
    U[使用者] -->|npx init| S[scaffold workspace]
    S --> D[my-slide/]
    D --> A[Claude Code / Codex / Cursor]
    A -->|讀 .claude/skills/| SK[5 內建 skill + 4 外部 skill]
    A -->|"/create-slide"| W[寫 slides/<id>/index.tsx]
    W --> DEV[pnpm dev]
    DEV --> B[瀏覽器 dev server
1920×1080 canvas]
    B -.in-browser inspector.- C[加 @slide-comment]
    C --> AC["/apply-comments"]
    AC --> A
    B --> BUILD[pnpm build]
    BUILD --> HTML[靜態 HTML]
    BUILD --> PDF[PDF export]
    HTML --> DEP[Vercel / Cloudflare / Netlify / Zeabur]

3. 核心架構解析

3.1 三層結構（pnpm + Turbo monorepo）

graph TB
    subgraph "Distribution (npm + GitHub Release)"
        N1["@open-slide/cli@1.2.4
scaffolder"]
        N2["@open-slide/core@1.6.0
runtime + Vite plugin + CLI"]
    end
    subgraph "packages/"
        C[core/
src/app + cli + vite + editing + files + http]
        CL[cli/
src + template + scripts]
    end
    subgraph "apps/ (private)"
        D[demo/
workspace:* 連 core
10+ 個 demo slides]
        W[web/
Next.js 行銷站
open-slide.dev]
    end
    subgraph "Tooling"
        T[turbo + pnpm-workspace]
        B[biome lint+format+organize]
        CS[changesets release]
        V[vitest test]
        SL[skills-lock.json
external skill SHA-pinning]
    end
    C --> N2
    CL --> N1
    CL -->|template/| D
    T --> C & CL & D & W
    B --> C & CL & D & W
    CS --> N1 & N2
    SL --> C

3.2 一張 slide 的渲染生命週期

sequenceDiagram
    participant U as 使用者
    participant V as Vite plugin
    participant R as React Runtime
    participant C as 1920×1080 Canvas
    participant I as Inspector
    participant E as comments.ts

    U->>V: 起 dev server
    V->>V: 掃 slides/<id>/index.{tsx,jsx,ts,js}
    V->>V: 透過 virtual module exposes
    V->>R: 啟動 React app
    R->>C: 對每張 slide 包進 1920×1080 fixed canvas
    R->>R: 計算 viewport scale factor
    Note over R,C: 不論螢幕大小，slide 永遠 1920×1080，整體 scale
    U->>I: 點任一元素加 comment
    I->>E: 解析 .tsx 找到對應行
    E->>E: 在 source 插入 @slide-comment marker
    U->>U: 跑 /apply-comments
    U->>R: agent 改 .tsx
    V->>R: HMR 自動重載
    U->>U: 重複迴圈

3.3 5 個內建 skill 的職責

3.4 4 個外部 skill（skills-lock 鎖版本）

1// skills-lock.json
2{
3  "frontend-design":              { "source": "anthropics/skills",          "computedHash": "063a0e64..." },
4  "vercel-composition-patterns":  { "source": "vercel-labs/agent-skills",   "computedHash": "575757e3..." },
5  "vercel-react-best-practices":  { "source": "vercel-labs/agent-skills",   "computedHash": "ca7b0c0c..." },
6  "web-design-guidelines":        { "source": "vercel-labs/agent-skills",   "computedHash": "f3bc47f8..." }
7}

設計意義：類似 package-lock.json 鎖 npm 版本，本檔鎖外部 skill 的「內容 hash」— 即使上游 force-push，本地裝的還是 audit 過的那個 hash。

3.5 @slide-comment marker 制度

1// slides/intro/index.tsx
2<h1 className="text-6xl font-bold">
3  {/* @slide-comment id="abc123" content="make this red" */}
4  Hello, World
5</h1>

當使用者在 dev server inspector 對 <h1> 加 comment「make this red」：

1. comments.ts 用 MARKER_RE.exec 解析每行
2. 找到對應 .tsx 行號 + element identity
3. 插入 @slide-comment id="abc123" content="..." marker
4. 跑 /apply-comments → agent 對每個 marker 套用修改 → 寫回 .tsx → 清 marker

是「跨 stage 評審」的精華系統。

4. Helper Scripts 詳細用法

4.1 npx @open-slide/cli init

1npx @open-slide/cli init my-slide              # 全互動
2npx @open-slide/cli init my-slide --yes        # 接受所有預設

行為：

1. mkdir my-slide
2. 複製 packages/cli/template/ 進去
3. package.json 設定 @open-slide/core@<pinned-version>（PR #147 修正）
4. 寫 AGENTS.md / CLAUDE.md（symlink）
5. 拷貝 5 個內建 skill 進 .claude/skills/ + .agents/skills/

4.2 open-slide CLI（從 @open-slide/core）

1# scaffold 後，在 workspace 內
2open-slide dev               # 起 dev server（hot reload）
3open-slide dev -p 3000 --host --open
4
5open-slide build             # build 靜態 HTML 到 dist/
6open-slide build --out-dir docs/
7
8open-slide preview           # serve 已 build 的靜態
9open-slide preview -p 4173 --host --open

4.3 monorepo workflow（contributor）

 1pnpm dev                       # turbo run dev（demo + 框架同時）
 2pnpm dev:web                   # 只跑行銷站
 3pnpm dev:demo                  # 只跑 demo
 4
 5pnpm core <script>             # 過濾到 @open-slide/core package
 6pnpm cli <script>              # 過濾到 @open-slide/cli package
 7
 8pnpm check                     # biome check（format + lint + organize imports）
 9pnpm check:fix                 # auto-fix
10
11pnpm changeset                 # 加新 changeset（必做：當 core / cli 改動）
12pnpm version-packages          # 跑 changeset version（apply CHANGELOG）
13pnpm release                   # build + changeset publish（**只 maintainer 跑**）

Hard rule（AGENTS.md）：core 或 cli 改了 → 必須 pnpm changeset 加 changeset，否則 CI 擋。

4.4 packages/cli/scripts/sync-template-skills.mjs

把 packages/core/skills/ 同步到 packages/cli/template/.claude/skills/ — 確保 cli 出 template 時帶最新 skill 版本。

4.5 demo workspace 的 10+ 示範 deck

 1apps/demo/slides/
 2├── claude-code-intro/
 3├── harness-engineering/
 4├── image-placeholder-demo/
 5├── llm-fundamentals/
 6├── material-design-2014/
 7├── nextjs-ppr-cache/
 8├── open-slide-anatomy/
 9├── open-slide-launch/
10├── raycast-api/
11└── ssh-explained/

每個都是「agent 真實產出」的範例 — 學 prompt 寫法 / aesthetic 變化 / interactive demo 的最好教材。

5. 應用場景

6. 資安掃描報告

掃描範圍：packages/core/src/、packages/cli/src/、scripts/、SKILL.md、SECURITY.md、scaffold template。

綜合燈號：🟢 / 🟡（無紅燈；可放心個人 / 團隊使用）

重點建議：

• 把 dev server 暴露給網路前確認防火牆（pnpm dev --host 會 bind 0.0.0.0）
• export PDF 前確認 deck 內沒有機密資訊（PDF 可分享 = 不可撤銷）
• 若公司有 internal SKILL.md / theme，fork 來鎖內部 hash 進 skills-lock.json
• 提 issue 請作者把 SECURITY.md 填實質內容

7. FAQ

Q1：跟 ConardLi/web-video-presentation 差別？ A：

• web-video-presentation 是一個 skill — 自帶 Vite + React + TS scaffold；focus 在「網頁假裝影片」（click-driven 16:9 narration）
• open-slide 是一個 framework — 自帶 5 個 skill；focus 在「正規簡報」（present mode / 演講者模式 / PDF export / 一鍵 deploy）
• 可以併用：用 web-video-presentation 出影片素材；用 open-slide 出正規 deck

Q2：跟 Slidev / reveal.js / Marp 差別？ A：

• Slidev：Vue + Markdown，agent friendly 但非 agent-native
• reveal.js：HTML / JS，自由度高但無 framework guidance
• Marp：純 Markdown，簡單但功能受限
• open-slide：React + agent-native + canvas 鎖死 1920×1080 + 內建評審迴圈 — 對「用 agent 寫」最優

Q3：1920×1080 鎖死會不會限制設計？ A：不會。所有 modern projector / screen 都能正確 scale；對視覺一致性反而有利（你不用為 4K monitor 重新調字級）。

Q4：每個 slide 一個 .tsx 不會太多檔嗎？ A：每個 slide 自帶資產（圖、子組件）放同目錄 slides/<id>/；scale 到 50+ slides 仍清晰。

Q5：作者 1weiho 是誰？ A：Yiwei Ho；本 repo 是個人 OSS + 已有多位社群 PR 貢獻者（Sam Serrien / Matt Van Horn / Kyle Chung 等）。

Q6：能不能完全離線跑（不用 npm）？ A：scaffold 後第一次 pnpm install 要連網；之後 pnpm dev / pnpm build 全本機。svgl 搜尋會發送網路請求，可關。

Q7：5 個內建 skill 哪個最常用？ A：使用者面向：/create-slide + /apply-comments。框架認知面向：/slide-authoring（讓 agent 一開始就讀對規則）。

Q8：對 enterprise 部署友善嗎？ A：MIT license，靜態 HTML output → 可放企業內網 / 私有 CDN；零 server / 零 runtime / 零 lock-in；非常適合 enterprise。

Q9：vs PowerPoint / Keynote 真實取代？ A：「描述驅動」勝；「點滑鼠拖元素」輸。適合寫程式的人 / 用 agent 的人；不適合完全不寫程式的 PM / 業務。但對「需要重複出 deck 的工程師團隊」是 game changer。

8. 進階技巧

8.1 自製 theme

1# 在 workspace 內
2/create-theme
3# agent 問 brand color / typography / spacing scale → 寫到 themes/<name>/

8.2 把 deck 改成「動態頁碼」

1import { useSlidePageNumber } from '@open-slide/core'
2
3export default function Slide() {
4  const { current, total } = useSlidePageNumber()
5  return <div>Page {current} of {total}</div>
6}

PR #137 加入的 hook；對自製 footer / progress bar 很方便。

8.3 評審改稿迴圈 SOP

1. pnpm dev 啟動
2. present mode 走過一遍
3. 看到要改的，用 inspector 點該元素 + 輸入 comment（例：「shrink headline」「move logo to right」）
4. 累積多個 comment 後，跑 /apply-comments
5. agent 把所有 comment 套用、清掉 marker
6. 重新 present → 確認結果 → 下一輪

8.4 用 svgl 找 logo

inspector 內 assets 面板有 svgl 搜尋；輸入「stripe」「openai」等品牌名直接 drop 進去。

8.5 多檔結構的 slide

1slides/llm-fundamentals/
2├── index.tsx
3├── slide-1-intro.tsx
4├── slide-2-architecture.tsx
5└── components/
6    └── attention-diagram.tsx

index.tsx 是入口；PR #142 已修「inspector selection works in multi-file slide structures by tagging all .tsx files」。

8.6 自訂 skill / 把自家 skill 加進 skills-lock

1# 在 .agents/skills/<your-skill>/SKILL.md 加好
2# 然後手動編 skills-lock.json 加一筆（source 用 GitHub repo + SHA hash）

8.7 一鍵 deploy

1# Vercel：scaffold 已含 vercel.json
2vercel
3
4# Netlify：scaffold 已含 netlify.toml
5netlify deploy --prod
6
7# Cloudflare Pages
8wrangler pages deploy dist

9. 整合進其他工作流

10. 重點摘要 Checklist

• 3.5k stars / 248 forks / MIT / 1 個月生命週期（2026-04-26）
• @open-slide/core@1.6.0 + @open-slide/cli@1.2.4（2026-05-19 雙釋出）
• pnpm + Turbo monorepo（biome + changesets + vitest）
• 5 個內建 skill：create-slide / slide-authoring / apply-comments / create-theme / current-slide
• 4 個外部 skill（SHA-pinned in skills-lock.json）
• 1920×1080 固定 canvas + 自動 scale
• @slide-comment marker + /apply-comments 評審迴圈
• svgl logo 搜尋 + assets manager
• present mode + 演講者模式 + speaker notes + timer
• 靜態 HTML / PDF 雙 export
• 一鍵 deploy（Vercel / Cloudflare / Netlify / Zeabur）
• 跨 agent（Claude / Codex / Cursor / OpenCode 等支援 SKILL.md 的）
• AGENTS.md → CLAUDE.md symlink（單一真實來源）
• 10+ 個 demo deck 可參考
• 資安綜合燈號：🟢 / 🟡（無紅燈）

11. 進一步閱讀

• 官方網站：https://open-slide.dev
• @open-slide/core npm：https://www.npmjs.com/package/@open-slide/core
• @open-slide/cli npm：https://www.npmjs.com/package/@open-slide/cli
• svgl catalogue：https://svgl.app
• changesets release flow 參考：https://github.com/changesets/changesets
• Biome：https://biomejs.dev
• Turbo：https://turbo.build
• vercel-labs/agent-skills（外部 skill 來源之一）：https://github.com/vercel-labs/agent-skills
• 對應姊妹專案 ConardLi/web-video-presentation（影片變體）：inbox/2026-05-21-github-ConardLi-garden-skills.md
• 本知識庫先前 tutorial：inbox/2026-05-21-tutorial-agency-agents.md