Larch 視覺小說本機預覽：larch-preview 講義

1線上改，卡在哪

單次改一句其實不慢。卡的是一部作品要來回改上百次：

• 寫入限流：agent 連續寫入官方 API，第 13 次會回：

  HTTP 429  retry-after: 51
  {"error":"Agent 專案寫入過於頻繁，請稍後再試"}

  要等 49～52 秒才能繼續，等完又能寫 12 次。連續改 50 次會被擋 4 次。
• 改完要自己重整：線上預覽重新整理後回到標題畫面，要按「開始遊戲」，再走回剛剛那張卡。
• 講不清楚哪一句：打字描述「第二幕他講的那句怪怪的」，AI 常常找錯卡。

2不用 AI 也能用

預覽本身不呼叫 AI，不花松果幣，也不吃 token。要直接改 JSON，得先看得懂卡片結構。

1. 準備專案檔：
   • 已經有作品：從 Larch 匯出專案 JSON，存到自己的資料夾。
   • 先試試看：複製範本：

     mkdir -p ~/my-story && cp ~/larch-preview/fixtures/bench_demo/* ~/my-story/

2. 啟動本機預覽：

   python3 ~/larch-preview/serve.py ~/my-story/project.json

   終端機會印出網址，預設是 http://127.0.0.1:8790/，被佔用會自動換一個，以終端機印的為準。
3. 左右兩個視窗：左邊 VS Code 開 project.json，右邊 Chrome 開上面那個網址。
4. 改台詞存檔：找到卡片的 data.text 或 data.dialogueLines 改字，按 Ctrl + S（Mac 是 Cmd + S）。右邊大約 1 秒後自己重整，停在原本那一句。JSON 改壞的話，畫面停在上一版，上方會寫錯在哪。
5. 兩個快捷鍵：
   • B：切到白板，看整個分支，點卡片上的 ▶ 從那張卡開始播。白板只能看，不能在上面改。
   • F：留一句修稿筆記，附截圖，寫進專案旁邊的 feedback/。

3跟 agent 說哪裡要改：按 F

• 按 F：跳出回饋面板，先帶出現在這張卡、這一句（猜錯可以從清單改選），附上截圖。專案用了自訂對話框介面的話對不到卡，要從清單自己選。
• 第一次按：Chrome 會問要不要分享這個分頁，按分享才截得到圖，截的只有預覽這個分頁。不允許也能送，只是沒有截圖。
• 送出後：寫進 feedback/feedback.jsonl，截圖是同資料夾的 png，每筆都有卡片 ID 和第幾句。
• 叫 agent 處理：

  cd ~/larch-preview
  python3 -m lp.feedback list ~/my-story
  python3 -m lp.feedback done ~/my-story <回饋id> "改了什麼"

  要在 ~/larch-preview 底下跑；在別的資料夾就在前面加 PYTHONPATH=~/larch-preview。 agent 照卡片 ID 去改 JSON，改完存檔，右邊的預覽自己會更新。

4頂欄的「雲端」按鈕

按鈕或快捷鍵 S 打開同步面板。要先設好 Larch API 金鑰（環境變數 LARCH_API_KEY，或 ~/.config/larch/key）。

• 拉取：把雲端專案抓下來蓋掉本機檔。蓋之前先把本機檔備份成 project.json.bak.<時間>。
• 推送：把本機檔整包取代雲端專案，一次 API。推之前一樣先備份本機檔。

5角色與素材

看：預覽頁頂欄按「素材庫」，另開一頁列出角色的立繪與差分、專案所有的圖片音訊影片，每個標出被卡片用到幾次，沒用到的標紅。專案檔一改，兩秒內自己更新。只能看，不能在上面改。

改：抓下來的 project.json 是整個專案，角色在 characters，素材在 media，有三種改法：

• 直接改 JSON：VS Code 改或叫 agent 改。角色的 id 不要動，卡片靠它對到角色。2026-10-06 沙盒實測：本機改角色名字與描述推回去，雲端更新，角色 id、差分、立繪網址沒被動到。
• 在 Larch 網頁上改：改完回本機按頂欄「雲端」→ 拉取，再繼續改本機。沒拉就推送，網頁上的改動會被本機的舊版蓋掉。
• 叫 agent 用 MCP 改（例如 larch_upsert_character）：改完一樣先拉取回本機。

"characters": [{ "id": "character-…", "name": "…", "portraitUrl": "…",
  "expressions": [{ "id": "expression-…", "kind": "pose", "name": "窗邊等", "imageUrl": "…" }] }],
"media": [{ "id": "…", "url": "https://cdn.jsdelivr.net/gh/<帳號>/<repo>@<分支>/<路徑>", "name": "…", "type": "image" }]

6安裝

MIT 授權。repo 不放 Larch 官方的前端檔案，sync.py 會在自己的電腦上從 larch.ink 抓（第一次大約 26 MB、一分鐘左右）。

macOS / Linux（終端機）

git clone https://github.com/yazelin/larch-preview ~/larch-preview
cd ~/larch-preview && python3 sync.py

# Claude Code
mkdir -p ~/.claude/skills && ln -s ~/larch-preview ~/.claude/skills/larch-preview
# Codex、agy、GitHub Copilot CLI
mkdir -p ~/.agents/skills && ln -s ~/larch-preview ~/.agents/skills/larch-preview

Windows（PowerShell）

git clone https://github.com/yazelin/larch-preview "$HOME\larch-preview"
cd "$HOME\larch-preview"; python sync.py

# Claude Code
New-Item -ItemType Junction -Path "$HOME\.claude\skills\larch-preview" -Target "$HOME\larch-preview" -Force
# Codex、agy、GitHub Copilot CLI
New-Item -ItemType Junction -Path "$HOME\.agents\skills\larch-preview" -Target "$HOME\larch-preview" -Force

7改完怎麼推回 Larch

本機改的時候不打雲端 API，改完推一次。50 次寫入變成 1 次，就不會撞到限流。兩條路都是整包取代：

8常見問答

9現場補充（直播時講到、原本講義沒寫的）

• 官方桌面版：Yapi 10/6 早上在 Discord 說打算出離線的桌面版 Larch。我做這套是因為之前不知道有這個計畫；桌面版出來之後，我可能會考慮改用官方的，要看官方的功能用起來有沒有我現在這套順。
• 為什麼有限流：上一屆我請 AI 幫幾千句台詞配音，原本限制同時 3 條，AI 想快點做完，自己把並行數一路調到 6、9、15，Larch 那邊看起來像被攻擊，帳號就被停權了。後來 Yapi 幫我恢復，也調高了上限。伺服器限制寫入頻率是為了不被單一使用者拖垮，很正常；本機改完再推一次，就不會撞到。
• 為什麼看中位數：平均數會被最大值、最小值拉走。中位數是把量到的結果排好，取正中間那一筆，比較能代表一般情況。
• 回饋可以一次留很多筆：一張對話卡如果有 20 句，可以 20 句都按 F 留完，再跟 AI 說「看完了，讀一下回饋」，讓它一次處理完，自己先去做別的事。AI 改的時候，也可能把你的偏好（例如「不要寫得那麼文言」）記進它自己的 memory.md 或 AGENTS.md，下次比較不會再犯。
• 素材別都放在 Larch：卡片和圖一多，線上快轉預覽會很卡。我的做法是 Larch 上只放 JSON 劇本，跟一定要放在平台上的東西（作品封面、RPG 地圖）；CG 和語音放 GitHub，請 AI 用 jsDelivr 的網址（cdn.jsdelivr.net/gh/…）填回劇本。要特別跟 AI 講用 jsDelivr，不然它可能直接用 GitHub 的原始網址：那也有 CDN，但只快取 5 分鐘，速度很不穩（見第 11 節第 2 階）。
• PNG 先轉 WebP：AI 生的圖通常是沒壓縮的 PNG，一張好幾 MB。卡片做到上千張，玩家看一部小說就要載好幾 GB。轉成 WebP 會壓縮、保留透明背景，肉眼很難看出差別，檔案小很多。檔名用英文比較保險（中文檔名的實測見第 10 節）。用 16 倍速快轉測分支時，沒壓縮的圖常常還沒載好就跳過了，畫面一片空白。
• 網頁編輯器跟 AI 不要同時開：AI 推上去之後，開著的網頁編輯器有時會把它手上的舊版又存回去，看起來像沒改到。我的做法：AI 在改的時候，不開那個專案（可以去作者茶館晃晃）；AI 推完之後，按 Ctrl + F5 強制重新整理，再點一張剛改過的卡確認內容對了。
• 白板卡片太多很難找：上一屆有作品做到 900 張卡，白板縮到最小還是看不完，每張看起來都一樣。
• Larch 有許願池：版本更新頁（larch.ink/changelog）會貼每次的大更新，右上角有「功能許願」，想要什麼功能可以在那裡提，也可以幫別人的願望按「我想要」。直接打開許願池：larch.ink/changelog?wishes=1。小的更新會先累積，到大更新才貼一篇，所以有些實驗中的功能不會出現在頁面上。
• Windows 和 macOS：我自己用 Linux，Windows、macOS 是 AI 幫我寫的，沒有實機跑過。裝起來不能用的話，可以請你的 AI 照錯誤訊息修，不用回報給我。

10會後補充（10/7）：jsDelivr 的兩個坑

補充：素材放 GitHub 走 jsDelivr 有一些限制，作品一大就會遇到。

• repo 超過 50 MB 會 403：jsDelivr 的 gh 網址把整個 repo 當成一個套件，算的是整個 repo 的大小，不是單一檔案。超過就回 Package size exceeded the configured limit of 50 MB（jsDelivr 自己的 API 文件寫的是 GitHub 50 MB、npm 150 MB，跟實際一致；主說明文件那句「150 MB」講的是 npm。需要更高的上限，可以到 jsDelivr 的 GitHub repo 開 issue 申請）。之前被抓過的檔案還在快取裡，所以症狀是有些圖慢、有些出不來、重新整理又好了。香布纏的圖 repo 250 MB、音樂 repo 180 MB，兩個都超過。
• 解法：孤兒 tag，先整部一個，超過才拆。做一個只放作品用到的檔案的孤兒 commit，打 tag，網址的 @main 換成 @<tag名>。tag 用的是 main 上現成的檔案，repo 不會變大。作品用到的檔案 40 MB 以內，整部一個 tag 就好；超過才一張卡片一個 tag。香布纏用到 430 MB，所以一張卡片一個（@card-v3-8 這種），好幾張卡共用的圖或配樂放在第一張用到它的卡片，網址只有一個，換卡時不會重抓。同一批 64 張圖實測：只放卷五的測試用孤兒分支（31 MB）64 張全部拿到，整個大 repo 掛了 8 張。詳細分組見第 11 節第 3 階。
• tag 名別用「v＋數字」開頭：v2-act1 會被 jsDelivr 當成版本號，找不到檔案，回 404。第一輪 969 個網址掛了 71 個，全部是卷二。前面加 card- 之後全部拿得到。
• 中文檔名：原本第 9 節寫「jsDelivr 遇到中文檔名會 404」，這句不準。這次 969 個網址大部分是中文檔名，改成小 tag 之後全部拿得到；10/7 另外抽香布纏小 tag 裡 3 個中文檔名的圖（例如 cg3_地窖插曲一_1_c_v2.webp），也都回 200。唐詩小旅行（repo 只有 15.9 MB）10/6 撞到中文檔名 404 的那張圖，10/7 用當時的 commit 和 @main 重抓也都是 200。中文檔名本身不會 404；10/6 那次的原因還沒找到，也不是 repo 太大。檔名用英文還是比較保險。
• 跟 AI 講的一句話：「素材 repo 超過 50 MB，就用孤兒 tag：作品用到的檔案 40 MB 以內打一個 tag，超過就一張卡片一個 tag。tag 名不要用 v 加數字開頭，改完每個網址都實際下載一次。」

11會後補充（10/7）：素材載入加速，有需要才往下一步

不是每部作品都要做到最後一階。每往下一階都多一件要自己管的事（雖然也是叫 AI 做啦），所以照順序來：看到「往下一步」的症狀才往下走，作品小就停在第 0 或第 1 階。下面的數字都是 2026-10-07 量的。

第 0 階：不優化

• 做法：在 Larch 上用 AI 生圖、生配音，直接存在 Larch 的素材庫。最省事，什麼都不用管。
• 實測：素材庫的檔案放在 Cloudflare R2 的公開網址（pub-….r2.dev），回應裡沒有 CDN 快取。一張 1376×768、918 KB 的 PNG 連抓三次，每次都要 1.2～1.4 秒，第二次沒有變快。Larch 生的配音本來就是 MP3，一句 47～96 KB，不用動。
• 會遇到的情況：預覽換卡時背景黑一下、用 16 倍速快轉測分支時圖還沒出來就跳過了。不優化的話這幾乎一定會發生。
• 什麼時候往下一步：想讓圖載入順一點，就換 WebP（第 1 階）。

第 1 階：換格式（還是放在 Larch）

• 做法：圖從 PNG 轉 WebP（q85），透明背景會保留；自己做的配樂（例如 Suno 生的）轉成 128 kbps 的 MP3。換好之後重新上傳到素材庫，把卡片的網址換掉。
• 實測：同一張 918 KB 的 PNG 轉 WebP 剩 199 KB，少 78%。一首 3 分鐘、192 kbps 的配樂 4.2 MB，轉 128 kbps 剩 2.8 MB。
• 品質要設對：轉成 WebP 不等於變小，品質參數設太高或用無損模式，檔案一樣很大。香布纏有一張 1536×1024 的 CG，WebP 存成 2.4 MB；同一張用 q85 重存，剩 245 KB。轉完看一下檔案大小，一張 CG 通常幾百 KB 以內。
• 跟 AI 講：「把專案裡的 PNG 都轉成 WebP q85，配樂轉 128k MP3，換掉卡片上的網址。轉完列出每個檔案的大小。」
• 什麼時候往下一步：圖檔小了，但素材庫沒有 CDN 快取，每張還是要等 1 秒多；或是素材多到上傳很花時間。

第 2 階：素材搬到 GitHub，走 jsDelivr

• 做法：素材放進 GitHub 的公開 repo，卡片網址改成 https://cdn.jsdelivr.net/gh/<帳號>/<repo>@main/<路徑>。Larch 上只留 JSON 劇本，跟一定要放平台的東西（作品封面、RPG 地圖）。本機預覽直接載得到。
• 跟 AI 講：「素材放到我的 GitHub 公開 repo，網址用 jsDelivr，不要用 GitHub 原始網址。」一定要講 jsDelivr，不然 AI 可能直接用 GitHub 的原始網址（raw.githubusercontent.com）。
• 為什麼不用 GitHub 原始網址或 GitHub Pages：它們其實也有 CDN，差在快取時間和速度穩不穩。10/7 用同一個檔案交錯量三次：
  • 2.4 MB 的圖：GitHub 原始網址 3.0、48.9、2.5 秒（只快取 5 分鐘）；jsDelivr 三次都是 0.27 秒。
  • 4.3 MB 的配樂：GitHub Pages 95.9、7.3、1.8 秒（快取 10 分鐘）；jsDelivr 0.31～0.37 秒。
  • jsDelivr 那邊的檔案之前就抓過，量到的是熱快取的速度；它讓觀眾瀏覽器快取 7 天，回來的玩家直接用快取。
• 要注意：
  • repo 要公開，私有的 jsDelivr 拿不到。
  • 單一檔案超過 20 MB，jsDelivr 預設不提供。影片、沒壓縮的 WAV 不要放；jsDelivr 的使用條款也寫明不能拿來放影片、當圖床或大量備份。
  • 換圖要換檔名：@main 的網址，jsDelivr 會快取 12 小時，觀眾的瀏覽器會快取 7 天（實測 max-age=604800, s-maxage=43200）。purge.jsdelivr.net 只清得到 jsDelivr 那一層，清不到觀眾瀏覽器裡的舊圖。
  • 檔名用英文比較保險（見第 10 節）。
  • GitHub 本身的門檻：單一檔案超過 50 MiB 會警告，超過 100 MiB 推不上去，整個 repo 建議 1 GB 以內。
• 什麼時候往下一步：repo 裡的檔案加起來逼近 50 MB。症狀是有些圖慢、有些出不來（403）、重新整理又好了（第 10 節）。

第 3 階：孤兒 tag（先整部一個，超過才拆）

• 為什麼釘 commit 沒用：jsDelivr 算的是 @ 後面那個版本當下整個 repo 有哪些檔案（不算歷史）。把網址從 @main 改成大 repo 的某個 commit，那個 commit 一樣超過 50 MB。
• 做法：在原本的素材 repo 裡做一個孤兒 commit（沒有上一層，裡面只放作品用到的檔案），對它打 tag，只把 tag 推上去，網址的 @main 換成 @<tag名>。不用另開 repo，也不會建立分支；用的是 main 上現成的檔案，repo 不會變大。指令在 larch-preview 的 SKILL.md（「素材放 GitHub 走 jsDelivr」那一節）。
• 分幾個 tag，看作品實際用到多少：
  • 用到的檔案加起來 40 MB 以內：整部作品打一個 tag 就好。jsDelivr 上限 50 MB，留 10 MB 給之後補圖。repo 本身多大沒關係，算的是 tag 裡放了什麼。
  • 超過 40 MB：一張卡片一個 tag（例如 @card-<卡片id>），每張卡只放它用到的檔案。好幾張卡共用的圖或配樂，放在第一張用到它的卡，網址只有一個，換卡時不會重抓、配樂不會被打斷。
• 要注意：tag 名不要用「v＋數字」開頭（第 10 節）。jsDelivr 把 card- 開頭的 tag 當成 branch，一樣快取 12 小時、瀏覽器 7 天，所以 tag 打了就不改內容，要改就打下一版（-r2、-r3），舊網址照樣能用。
• 實測：《仙泉．香布纏》用到的圖 250 MB、音樂 180 MB，遠超過 40 MB，所以一張卡片一個 tag（圖和音樂各自在自己的 repo 打同名的 tag）。改完之後 969 個網址逐一下載，全部拿得到。其中一首 4.3 MB 的配樂，熱快取時 0.31～0.37 秒載完。
• 跟 AI 講：「素材 repo 超過 50 MB，就用孤兒 tag：作品用到的檔案 40 MB 以內打一個 tag，超過就一張卡片一個 tag。tag 名不要用 v 加數字開頭，改完每個網址都實際下載一次。」

素材都在本機時，上傳的順序

製作中素材放在本機，project.json 寫相對路徑（例如 bg/night.webp），larch-preview 直接讀得到。要推上 Larch 時照這個順序，不能反過來：

1. 素材推上 GitHub 公開 repo（jsDelivr 只抓得到已經推上去的 commit）。
2. 用到的素材超過 40 MB，打孤兒 tag（第 3 階）。
3. 把相對路徑換成 jsDelivr 網址，釘在 tag 或 commit 上（@card-… 或 @<commit>），不要用 @main。
4. 每個網址實際抓一次，確認回 200，順便把快取暖起來（冷快取第一次可能要等好幾十秒）。
5. 最後才推 project.json。先推的話，玩家打開時有些圖還抓不到。

• 換網址只在上傳的那一份做：本機的 project.json 保留相對路徑，本機預覽才能繼續讀自己電腦上的檔、離線也能改。
• 頂欄「雲端」→ 推送不會幫你換網址：它把本機的 project.json 原樣推上去。裡面還是相對路徑的話，Larch 上的圖會全部抓不到。素材在本機的作品，叫 AI 照上面五步推。
• 跟 AI 講：「推上 Larch 之前，先把素材推到 GitHub，相對路徑換成釘在 commit 的 jsDelivr 網址，每個網址抓一次確認 200，最後才推 project.json。本機的 project.json 不要改。」

12連結