---
name: shelf
description: 製作 lotion 動畫書並上架到 Shelf ( 動畫書架網站 ), 或依讀者回饋修改書架上的書。使用者說「做一本動畫書 / 做成會動的書 / 放上書架 / 上架 shelf / 看讀者回饋改書」, 或要把解說、教材、故事做成可逐秒閱讀的動畫時使用。需要 shelf MCP ( 工具名稱以 shelf 開頭, 例如 publish_book )。
---

# Shelf：做一本動畫書並上架

Shelf 上的每一本書都是一個 lotion 動畫頁面：讀者可以拖到任何一秒、在畫面上圈畫、留言。
這個 skill 帶你從構想走到上架。工具都來自 shelf MCP；若還沒安裝，見最後一節。

## 0. 先拿規範

呼叫 `lotion_guide`（一個 session 一次即可）。它包含 lotion 的 API（`player`、`seek(t)` 純函式、`track`、`put`、`vis` 等）、
檔案結構與書架的慣例。**動畫一律寫成 `seek(t)` 的純函式**：同一個 t 永遠畫出同一個畫面，這樣讀者才能拖動、截圖才準。

## 1. 構想

和使用者確認（不清楚才問，能合理推定就直接做並說明）：

- 主題與要讓讀者帶走的一件事
- 長度（預設 30–60 秒）、章節（每章一個重點，3–5 章）
- 風格：若沒指定，挑一個符合主題的；`lotion_guide` 裡有風格說明
- 是否需要配圖 / 音訊（會花錢，見第 3 節）

## 2. 撰寫

在工作目錄建立一個資料夾，例如 `./book-<主題>/`：

    book-<主題>/
      index.html     進入點：載入 /assets/lib/@plotdb/lotion/main/index.min.js 與 index.min.css
      index.md       作品文稿（lotion document，寫法見 lotion_guide 的「作品文稿」）
      assets/        圖片、音訊（相對路徑引用）

- 舞台尺寸用 1920×1080；文字要在這個尺寸下清楚可讀。
- 用 `chapters` 標出章節，讀者的時間軸會顯示。
- `<title>` 寫書名。
- 附上作品文稿（`index.md`，或頁面裡的 `<script type="text/markdown" id="lotion-doc">`）：每章的旁白、畫面、資料與出處。書架用它搜尋、生成簡介和審查。

## 3. 素材（選用，會花錢）

- `generate_image`：生成插圖；`remove_background`：去背（來源是 `generate_image` 的 `id`，或用 `create_upload` 傳上來的圖的 `upload_id`）。
- `generate_audio`：配樂、音效、旁白（預設台灣華語；英文旁白給 `language: en`）。
- 回傳的 `save` 是下載指令，把 `<書的目錄>/assets/<檔名>` 換成實際路徑後執行，例如：

      curl -sS --fail -o ./book-foehn/assets/mountain.png 'https://<shelf 網域>/media/xxxx.png'
- 生成類工具是非同步工作，依回傳說明等待完成。只生成真正需要的，先告訴使用者大概的數量。

## 4. 自我檢查（上架前一定要做）

用 lotion CLI 在幾個時間點截圖，親眼確認畫面：

    npx lotion sheet ./book-<主題>/ /tmp/sheet.png 0 5 12 20 30 --width 1920 --height 1080

看拼圖（Read 圖片）確認：
- 每個時間點的文字沒有重疊、沒有超出畫面、在 1920×1080 下讀得清楚
- 章節切換時沒有殘影或空白
- 結尾停在完整的畫面

有問題就修，再截一次。

## 5. 上架

1. 打包：`cd book-<主題> && zip -r ../book-<主題>.zip .`（index.html 在 zip 的根目錄）。
2. `create_upload` 拿到上傳網址，照回傳的 curl 指令上傳：

       curl -sS --fail-with-body -X PUT -H 'content-type: application/octet-stream' --data-binary @book-<主題>.zip '<url>'

3. `publish_book { upload_id }`。

- 檔案不要用 base64 塞進工具參數（一本 2 MB 的書就是 70 萬 token）。沒有素材的小頁面可以直接給 `html`。
- 上傳網址 15 分鐘內有效、只能用一次。
- 書名、簡介、標籤不給會自動生成；想指定就一併給 `title` / `summary` / `tags`。
- 更新既有的書：帶 `id`（讀者筆記會保留）。
- 回傳的 `url` 交給使用者。網址可以加 `&t=<秒>` 指到某個時間點。

## 6. 依讀者回饋修改

1. `search_books` / `list_books` 找到書，`get_book` 看概況。
2. `get_book_notes` 讀留言、畫重點（每則都有時間點 t 與位置）。
3. 把回饋整理給使用者，確認要改哪些。
4. 修改後同步更新作品文稿，照「5. 上架」打包上傳，再用 `publish_book { id, upload_id }` 更新，並說明改了什麼。

## 安裝 shelf MCP

先在 Shelf 的帳號頁產生個人 API token：

    claude mcp add --transport http shelf https://<shelf 網域>/mcp -s user --header "Authorization: Bearer <token>"

說明頁：`/agent`。