paulmil11/decks

decks 是做什麼的？

使用者在瀏覽器中審閱投影片組。他們在投影片下方輸入評論（或直接編輯文字），然後說「process changes」或點擊投影片組中的 Ask Claude，這會複製一個提示，其中包含投影片組檔案名稱和下面的 sb 步驟；將該提示視為該投影片組的「process changes」。你必須處理每一則評論，在投影片本身回覆，檢查你的工作，然後匯出。保持聊天摘要簡短：投影片上的回覆會承載詳細資訊。

檔案位置

• 應用程式資料夾是 Decks 儲存庫：此技能所在的資料夾（其中的 .claude/skills/decks/），或者，如果此技能複製在 ~/.claude/skills/ 中，則是使用者克隆它的位置。Ask Claude 提示會命名它。它包含 server.py、sb 命令列、static/ 中的瀏覽器 shell、templates/ 中的範本，以及 tools/ 中的無頭工具。從那裡執行 sb：./sb ...。
• 伺服器：python3 server.py，位於 http://localhost:8790/，除非 config.json 或 SB_PORT 另有指定。如果 sb 說伺服器無法連線，請啟動它（在背景執行）然後重試。sb 會在 SB_URL 或設定的連接埠找到它。
• 投影片組位在投影片組資料夾中（預設為 ~/slide-decks），每個投影片組一個資料夾，列在該處的 decks.json 中。./sb decks 會列出它們及其網址。
• 在 http://localhost:<port>/d/<slug>/<entry> 開啟投影片組。#s=<slide-id> 會跳到某張投影片，#v=<version>&s=<id> 則會選擇某個版本。
• 儲存的狀態存在每個投影片組旁的 .slidebuilder/ 中：
  • state.json：審閱者的編輯、評論和投影片順序，從頁面鏡像而來。請勿手動寫入。
  • review.json：你的回覆、回合和變更標記。透過 sb 寫入。
• 每個投影片組資料夾都是一個 git 儲存庫。PDF、zip 和 PPTX 檔案會被忽略。

頁面

• 四種檢視：焦點 (F)、捲動 (S)、排序器 (G) 和檢查 (C)。左側的底片條可透過拖曳重新排序。
  • 在焦點和捲動檢視中，評論框位於每張投影片下方，你的回覆則在它下面。右側欄位顯示投影片的備註和變更內容。
  • 檢查有四種檢視，按鍵 1 到 5：5 秒測試（第一印象）、10 秒測試（可讀性；失敗會在投影片上留下評論供下一輪處理）、水平流（僅標題，可原地編輯）、垂直流（先顯示標題，身體部分在揭開前隱藏），以及導引。
  • 評論可能來自檢查：「5 秒測試：…」和「10 秒測試：…」（在計時測試失敗後），以及「導引：…」（來自 Ask Claude，用以在檢查 > 導引中修正，指出投影片違反了哪些規則）。修正投影片使其通過，就像處理任何評論一樣。
  • H 隱藏除了標題以外的所有內容。? 列出所有快捷鍵。
• 新增投影片（N、「+ Slide」，或投影片之間的 +）會建議版面配置，並可新增此投影片組攜帶的投影片。其「複製」提示會提供投影片組檔案、位置以及投影片應包含的內容。當提示說「我剛剛新增了一張 … 投影片 (LIBRARY['id'])」時，填入該投影片；當它說「新增一張新投影片 …」時，在投影片組檔案中的該位置建立它。
• 當審閱者在「檢查」中編輯標題時，這是一個內嵌編輯：像處理其他編輯一樣將其合併。
• 隱藏客戶工作（控制面板上的開關，位於投影片組資料夾中的 settings.json）是為了錄製或螢幕分享。開啟後，伺服器會排除標記為 client 的投影片組以及 clientVersions 中列出的版本。開啟時切勿在螢幕上顯示客戶名稱。

一個回合（「process changes」）

1. cd 到應用程式資料夾。
2. ./sb comments <deck> 列出要處理的評論，編號與投影片組相同。草稿會被跳過。./sb edits <deck> 顯示審閱者的內嵌文字編輯和投影片移動。兩者都從磁碟讀取，因此你不需要他們的瀏覽器分頁。
3. ./sb status <deck> "正在閱讀你的 9 則評論" --done 0 --total 9。審閱者可以在頂部欄即時看到此狀態。在進行過程中更新它。
4. 對於每則評論：
   • ./sb working <deck> <slide>。
   • 在投影片組檔案中進行變更。
   • ./sb reply <deck> <slide> done "一句簡單的話說明改變了什麼"。
   • 如果你需要審閱者的決定，請使用 question 而不是 done。對於你刻意保留不動的內容，請使用 skipped 並說明原因。
   • 半打字的評論應回覆 question，而不是猜測。
5. 將審閱者的內嵌編輯合併到投影片組檔案中（他們的編輯獲勝）。Git 保留舊版本。
6. 檢查你觸及的每張投影片：
   • ./sb shot <deck> <ids…>，然後檢視每張圖片。
   • ./sb audit <deck> 會找出溢出、重疊的標籤以及導引標記的任何問題。
   • ./sb comments <deck> 應顯示沒有新的未處理評論。
7. 完成：
   • ./sb export <deck> 從投影片組檔案寫出下一個編號的 PDF，並將舊的移至 _archive/。如果瀏覽器仍持有未合併的編輯，它會發出警告：請先合併它們。--with-edits 則會匯出瀏覽器中顯示的確切內容。
   • ./sb round <deck> --summary "…" --changed id="改變了什麼" … --export vN。
   • ./sb commit <deck> "第 N 輪：…"。
   • ./sb idle <deck>。
   • 告訴使用者 PDF 的位置。
8. 一旦審閱者停止打字，頁面會自動重新載入。不要重新載入或清除他們的分頁。在聊天中：簡單幾行，加上任何需要他們決定的內容。

在你工作時，新的評論可能會出現。在完成前再次執行 ./sb comments。

審閱者會用「Looks good」來清除已處理的評論。不要將它們加入 DONE_FB；該清單僅用於在 Decks 外部開啟的副本，例如發送給其他人的檔案。

投影片組檔案

• 每個投影片組一個獨立的 HTML 檔案，包含三個你可編輯的部分：
  • content：LIBRARY 項目（'id': { cat, layout, title, …, notes }），按 cat 分組到部分中（這些部分是 CATS，在 CAT_LABELS 中命名）
  • figures：FIGS 函數，回傳內聯 SVG
  • versions：PITCHES（每個包含一個名稱和一個投影片 ID 清單）
• 預設版本是每個部分內的 LIBRARY 順序。若要重新排序，請移動 LIBRARY 項目。如果儲存的順序等於舊的預設順序，則會遵循檔案。
• 使用 alt:true 來淘汰一張投影片（它會移到排序器的架上），並將替代投影片放在它前面。不要刪除使用者的投影片。投影片的替代版本使用 prop:true, replaces:'…'（標記為「建議」）。
• 來源行透過 src:'來源：…' 放在頁尾，而不是作為副標題。
• 顏色、標題字型和標誌：投影片組檔案中的一個 <style id="deck-theme"> 區塊，以及 img/ 中投影片組標誌的 LOGO。透過編輯該區塊來重新設計樣式，而不是個別投影片。如果沒有 LOGO，投影片就沒有標誌。
• 重大的視覺變更（新的版面配置、重新設計）：先向使用者展示一個模型或兩個選項，然後再建構。
• 當使用者想要一個用來發送給他人的檔案時，那就是 ⋯ 選單中的客戶端副本：螢幕上僅投影片的版本（無備註、評論、引導投影片、其他版本或編輯），圖片內嵌，帶有「簡報」按鈕。可編輯副本是包含備註和評論的完整投影片組：切勿將此版本發送給客戶端。
• 使用 ./sb hide <deck> 將投影片組從控制面板上移除（使用 ./sb show 恢復）。./sb delete <deck> --yes 將此應用程式製作的投影片組移到垃圾桶，並且僅取消註冊使用者自己資料夾中的投影片組。僅在使用者要求時才刪除。
• 下載圖片或標誌需要每次都取得使用者的同意。告訴他們檔案名稱、來源、大小和授權，並將致謝資訊放在頁尾。

方法論

Decks 建立在 Paul Millerd 在 StrategyU 教授的方法論之上。將其應用於你撰寫或修正的每張投影片。如果已安裝 strategy-slides 技能，它包含完整版本：將其用於故事線、標題和回饋。

答案優先。 以建議開頭，然後是背景，最後是證據。只有在面對抱持懷疑態度的觀眾時，才先鋪陳（情境與困境，然後是關鍵想法）。

先做草稿投影片組。 在建立任何投影片主體之前，按順序寫下所有行動標題，並將它們作為一個段落來閱讀。如果此段落無法構成論點，請現在修正標題或順序；這是修正故事最經濟的時機。注意每個主體必須展示什麼才能證明其標題。

垂直流：標題是重點，主體證明它。

• 每個標題都是一個行動標題：一個完整的句子，說明重點。「第三季營收成長 22%，由企業擴張帶動」，而不是「第三季營收」。
• 超越模糊的標題。「公司正在進步」是第一步；「由於供應鏈投資，盈利能力在五年內首次提升」才是最終目標。
• 沒有「關鍵重點」框或底部的摘要條。見解引領頁面。
• 使用簡單動詞及其自然受詞。不要將資料擬人化，也不要將隱喻強加於數字。不要使用逗號分隔的片段（「一種思維模式，當工作需要兩種時」）。最多兩行。大聲朗讀：聽起來應該像一個人對同事說的話。
• 僅包含計數的標題是空白的。「三個風險及我們的應對方法」變成了發現：「真正的風險暴露是西岸服務，而非倉庫容量。」
• 封面、章節分隔頁和附錄分隔頁不受此限。結尾投影片則不然：「在 3 月 14 日前批准，我們就能在續約前退出這兩份租約」，而不是「後續步驟」。

水平流：僅標題就能講述故事。 按順序閱讀它們（檢查 > 水平流）。如果沒有投影片主體就無法理解，請修正標題或順序。

一張投影片一個想法。 如果一張投影片需要「而且還需要」，那麼它需要被分成兩張投影片。

五秒和十秒測試關乎可讀性。 一張被簡報的投影片應在五秒內傳達其一個要點。一張供閱讀的投影片應能在十秒內被理解：一個主要重點、可讀的層級結構、一個無需研究就能讀懂的圖表形狀。文字牆、關鍵數字隱藏在密集表格中，以及一張投影片上塞入數個不相關的想法，這些都算失敗。

「所以呢？」是另一個獨立的測試。 三個整齊的方塊寫著創新、卓越、成長，通過了十秒測試，但卻未能通過「所以呢？」（漂亮的投影片症候群）。每張投影片都要告訴觀眾該想什麼。在提供回饋時，請將這兩項發現分開。

圖表證明標題。 在繪製圖表之前先寫下訊息。長條圖、柱狀圖和折線圖幾乎涵蓋所有情況；切勿使用圓餅圖。重要的數字應該是最顯著的標記，標題中提到的任何內容（衰退、轉折點）都應在圖表上標記出來，並且任何不支持標題的內容都應刪除。不確定的資料應加上「示意圖」標籤和關於假設的備註。

執行摘要是最重要的投影片： 以建議作為標題，以及三個見解，每個見解附帶一行證據。僅在較長的投影片組（20 張以上）且具有不同章節時使用章節分隔頁。

簡報或閱讀。 簡報用：主體少於 20 個字，一個想法，大型視覺元素。閱讀用：較多的文字是可以的，使用粗體引導詞，並且每張投影片都能獨立存在，因為它可能會被轉發。

對投影片組提供回饋。 先閱讀整個投影片組。然後依序提供：故事（依序的標題、它們說明了什麼，以及缺少或順序錯誤的內容）；有問題的投影片及其修正方法（當問題是標題時，寫下新的標題）；以及最重要的三項變更，附上論證和順序，優先於字型和顏色。如果論點站不住腳，請先說明。在引用每張投影片的編號前，請先檢查。

寫作。 使用主動動詞、縮寫和數字，而非形容詞。切勿使用：深入研究、局面、槓桿、利用、至關重要的、關鍵的、強健的、無縫的、變革性的、強調、此外、而且、再者。每張投影片最多使用一個 em dash。

投影片樣式規則

在方法論之上：

• 卡片或方框底部沒有小字、灰色或斜體行。將任何重要的內容整合到它屬於的項目中。
• 沒有相同卡片的網格。改為繪製關係：流程圖、光譜圖、階梯圖、圖表或地圖。
• 指示是一個簡單的句子。反思問題是簡單的，並且關於觀眾自己的工作。
• 議程時間以 5 分鐘為單位。
• 在發明框架之前，優先使用使用者自己的材料、圖表和措辭。刪減時，先刪除發明的投影片，並保持建構/鋪陳/回報成對的完整性。
• 在備註中標記你起草的文字，以便使用者可以替換。
• 引文和數字僅來自於你在該次工作階段中開啟的來源，必須準確引用並標明出處。
• 所有內容都必須通過檢查 > 導引：保護邊框、兩行標題、沒有小於 12 px 的文字、一張投影片上最多四種文字大小。這些是指南，不是規則；修正 sb audit 列出的問題，或者說明為什麼某張投影片是例外。

開始一個新投影片組

使用者從控制面板的新投影片組表單開始，分兩步驟。步驟 1：名稱、他們正在建立的內容（簡報、培訓、演講、提案或空白投影片組），以及要同時建立的組件。步驟 2：對象是誰、他們知道什麼和關心什麼、一個要點，以及可選的長度、聽眾類型、結構、密度、顏色、標題字型、標誌和備註。建立投影片組會建立資料夾，為其提供自己的儲存前綴，將其添加到 decks.json，開始其 git 歷史，將簡報寫入 BRIEF.md，將提示複製到他們的剪貼簿，並開啟投影片組。當他們貼上該提示時：

1. 在撰寫投影片之前，先閱讀投影片組資料夾中的 BRIEF.md，並根據它調整範本。範本是起點，不是固定形式：
   • 使用方式。 簡報用：一張投影片一個想法，大字型，少文字；必須通過 5 秒測試。發送閱讀用：每張投影片都能獨立存在，有較豐富的主體；必須通過 10 秒測試。先簡報再發送：可簡報的投影片，細節放在備註或附錄中。
   • 聽眾及其所知。 調整詞彙、範例和解釋的深度；高階主管應優先獲得答案。
   • 結構。 答案優先：建議，然後是理由。情境、困境、解決方案：依序。分成幾個部分的故事：帶有分隔頁的章節。教學、練習、反思：帶有練習和反思問題的模組。
   • 密度。 稀疏、平衡或詳細，如文字所述。
   • 留空的任何內容都是你的發揮空間。請根據 Brief 做出最佳判斷。
2. 草擬故事。
3. 與他們分享草稿並取得同意後再建立。
4. 建立投影片。

附錄

• 深入連結（大綱樣式）：使用 #s=id 貼上投影片組連結，以跳到該投影片。如果連結來自其他應用程式，請不要使用 sb；直接建構它。
• sb 的每個命令都有隱藏的 --help。需要時使用它。
• 投影片組中的版本是為了比較而存在。當你想要嘗試不同的故事時使用它們。部份或完全是用備用投影片組成的版本：./sb version <deck> <name> <id ...>。使用 ./sb versions <deck> 列出它們，./sb delete-version <deck> <name> 刪除它們。