Community程式設計與開發github.com

sheets-to-playbook

將工作坊或社群活動的紙本工作表照片(加上承諾卡存根照片與選用的語音備忘錄)轉換成劇本書網站草稿,逐行與照片比對,然後發布。

sheets-to-playbook 是什麼?

sheets-to-playbook 是一個 AI Agent 技能,用於將工作坊或社群活動中拍攝的紙本工作表照片(以及承諾卡存根照片和選用的語音備忘錄)自動化轉換成一份可供發布的「劇本書」網站。此技能專為特定紙本工具包設計,強調速度與可追溯性:網站上的每一行文字都必須能追溯到一張照片或一段語音備忘錄,並透過內建驗證工具 (`ingest.py verify`) 強制執行。技能支援 Claude Code、Cursor、Codex 等開發平台,工作流程包含照片準備、標籤與覆蓋率檢查、平行轉錄、劇本書撰寫、驗證與審查,最後發布靜態網站。使用者只需提供包含照片的資料夾路徑,AI Agent 會自動執行 `prepare`、`transcribe`、`draft`、`verify` 等指令,並在每個階段回報進度。此技能的核心原則是「絕不發明任何內容」:任何無法從原始資料追溯的文字都不會被加入,確保產出內容的真實性與準確性。

相容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Chris-Keene/sheets-to-playbook/tree/HEAD/.claude/skills/sheets-to-playbook

Installed? Explore more 程式設計與開發 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

工作表變劇本書 (Sheets to playbook)

儲存庫:存放 ingest/ingest.py 的資料夾(如果 Claude Code 是在該複製專案中開啟的,即為當前專案)。以下所有路徑都是相對於它。在進入階段 3 之前,請務必閱讀 ingest/RAW_FORMAT.md:其中包含了轉錄格式與撰寫劇本書的規則。

目標是當天快速完成,而且絕不發明任何內容。網站上的每一行都必須追溯到一張照片或一段語音備忘錄;ingest.py verify 會強制執行這項要求。

請用一兩行文字告知使用者你正在進行的每個階段。以下各階段的時間僅供參考,約適用於十二張桌子。

活動開始前,playbook.config.json 應設定好主辦單位名稱,並提供劇本書的網址(承諾卡上的 QR Code 會指向該網址)。如果該檔案仍保留中立的預設值,請告知使用者,但繼續進行:這些設定只會改變名稱和顏色,不會影響內容。verify、draft 和 publish 指令可使用 --config <file> 參數來指定不同的設定檔。

1. 準備(1 至 2 分鐘)

python3 ingest/ingest.py prepare "<資料夾>"
python3 ingest/ingest.py transcribe      # 僅當資料夾中有語音備忘錄時執行;讓它在背景執行

prepare 會在 runs/ 目錄下建立一個新的執行記錄(並將 runs/latest 指向它):包括照片旋轉至正立、HEIC 格式轉換、每張照片的清晰度分數、供近距離閱讀用的 2x2 拼貼圖、contact/ 目錄下的聯絡頁縮圖,以及語音備忘錄轉換為 16 kHz WAV 格式。transcribe 使用本機 Whisper 模型(small.en,離線使用,首次執行後會快取),並根據語音開頭的「第七桌…」等資訊推測每段備忘錄所屬的桌子。

第二批內容(在第一批處理進行到一半後,新增更多照片或卡片):使用 python3 ingest/ingest.py prepare "<資料夾>" --into <執行記錄名稱> 指令,將它們加入相同的執行記錄中。新的 ID 會從上一個 ID 繼續編號(例如 P022…),原有的標籤和原始檔案會保留,且已存在於執行記錄中的檔案將會被跳過。然後僅標記新的 ID。

2. 標籤與檢查覆蓋率(約 5 分鐘;請先執行此步驟,此為時間關鍵)

查看每一張聯絡頁(contact/sheet-*.jpg),如果某張縮圖不清楚,則查看 view/ 目錄中的原始照片。在執行記錄資料夾中撰寫 labels.json:

{"photos": {"P001": {"table": 7, "sheet": "S2"}, "P014": {"kind": "stubs"}, "P020": {"kind": "other", "note": "房間照片"}},
 "audio":  {"A01": {"table": 7, "by": "speech"}}}
  • 每張工作表底部角落都印有代碼(S1、S2、S3、SS)和印好的標題;桌子編號則由桌長手寫在右上角的圓圈內以及代碼旁邊(例如 S2 · Table 7)。工具包預設的標題如下:S1「支援在哪裡卡住了?」、S2「什麼有幫助,或沒有幫助?」、S3「人們現在可以嘗試什麼,以及如何讓它持續?」、SS 為側邊頁「聽到什麼好東西了嗎?請寫在這裡。」(引言 · 問題 · 資源)。如果主辦單位更改了問題,請依據印好的代碼為準。當圓圈和角落的數字不一致時,以筆跡顏色和內容來判斷:檢查該桌的其他工作表。
  • 保留 transcribe 已填寫的任何音訊標籤,但在檢查過其與轉錄內容第一行的一致性之後再保留。
  • 兩張不同的工作表具有相同的代碼和桌子編號(status 會列出任何有多張照片的工作表:請檢查):如果國家/地區和內容有重疊,代表同一桌使用了兩份副本;將兩者都標記為同一個桌子編號,並且轉錄人員要轉錄兩份。如果它們顯然是兩張不同的桌子,則給予第二張從 91 開始的備用編號,並加上 "note": "寫了 22;第二張桌子",然後告知使用者。任何一張都可以是「第二張桌子」:選擇一個,並在備註中描述兩者的差異(領域、筆跡顏色),以便審查時可以區分。
  • 特寫照片中沒有桌子編號(例如只有計數框):將其標記為與之相符的工作表代碼,並加上 "note": "從 <相符的依據> 推斷桌子"。
  • 一張照片中有兩張工作表(釘在一起並排):將其標記為 "sheet": ["S2", "S3"],以便 status 為兩者計數,並在 note 中說明,讓轉錄人員知道哪一半是哪一張。
  • prepare 無法旋轉在畫面中上下顛倒的照片(因為沒有可讀取的旋轉標記)。轉錄人員可以應付,但請在 note 中說明。卡片照片的清晰度分數通常比工作表低(卡片材質、筆跡較細),因此在要求重拍之前,請先在 view/ 中檢查標示為「模糊」的卡片。

然後執行 python3 ingest/ingest.py status(如果桌子不是 12 張,請加上 --tables <n> 參數),並立即告知使用者是否有任何遺失或模糊的工作表。聯絡頁也會標示低解析度(經由通訊應用程式轉發:如果字體夠大就沒問題)和太暗(通常仍可閱讀):請提及這些情況,但它們不需要重拍。理想情況下,此檢查應在工作表仍掛在牆上且可以重新拍攝時進行。

3. 轉錄每一桌(平行進行,約 5 至 10 分鐘)

為每一桌生成一個子代理(使用 Agent 工具,general-purpose,在背景執行,全部在一個訊息中完成),如果有的話,再為卡片存根生成一個子代理。請勿降低模型等級:手寫辨識準確度至關重要。每個提示都必須獨立完整,並包含以下內容:

  • 絕對儲存庫路徑、執行記錄資料夾、桌子編號、其照片 ID(view/<id>.jpg 以及 manifest.json 中列出的拼貼圖)以及任何語音轉錄檔案路徑。
  • 「請閱讀 ingest/RAW_FORMAT.md 的階段 1,並嚴格遵循。在執行記錄資料夾中撰寫 raw/T<nn>.json,然後執行 python3 ingest/ingest.py verify --run <執行記錄名稱> 並修正它回報的關於你檔案的所有錯誤。回覆一份簡短總結:每張工作表的項目數、每個 unclear 條目,以及你省略的每個劃掉的字。」
  • 對於存根:請按照階段 1 結尾的描述撰寫 raw/commitments.json,包括卡片上選填的姓名和組織欄位,完全按照所寫內容記錄,並遵守那裡關於卡片的規則(未撕毀的卡片、簽署、一張卡片出現在兩張照片中)。

在子代理執行期間,請自行閱讀語音轉錄內容(如果有的話),以便在開始撰寫之前了解現場情況。

4. 撰寫劇本書(約 10 至 15 分鐘)

遵循 RAW_FORMAT.md 的階段 2。撰寫 <執行記錄名稱>/session.json,並設定 meta.status: "draft"。從 examples/session-template.json 開始填入 meta,並根據使用者提供的資訊填入活動的詳細資料(活動名稱、日期、場地);如果使用者知道實際參與人數,則將 people 設為實際人數。絕不要猜測這些資訊:將欄位保留為範本中的值,並將其列出給使用者。

5. 驗證、修正、建立審查包

python3 ingest/ingest.py verify --links
python3 ingest/ingest.py draft            # <執行記錄名稱>/playbook-draft.html:虛線框 = 缺口,標籤 = 來源
python3 ingest/ingest.py review           # <執行記錄名稱>/review.html:每個項目及其照片並列顯示

修正每一個錯誤(無法追溯的行、偏離的引言、遺留的名稱),並重新執行直到 verify 通過。警告則留給人工審查:報告它們,不要掩蓋它們。

然後向使用者提供審查摘要:挑戰點和哪些桌子合併了、每個 unclear 的讀取結果及其照片 ID、轉錄人員省略的每個劃掉的字、未使用的原始項目、連結問題,以及任何你不確定如何分組的內容。review.html 會顯示每位轉錄人員的註記以及每個桌子下方的「這桌有誰?」統計。為使用者開啟 review.html 和 playbook-draft.html。

有很多不確定的字詞? 審查應用程式比從頭到尾閱讀 review.html 更快:python3 tools/review/make_review.py --run <執行記錄名稱> 會建立 <執行記錄名稱>/review/index.html,每個不確定的讀取結果對應一張卡片,並附上手寫字的特寫。使用者確認或修正每個項目,儲存決定檔案,然後執行 python3 tools/review/apply_review.py --run <執行記錄名稱> <決定.json> 將讀取結果寫回原始檔案和 session.json。之後重新執行 verify 和 draft。不屬於不確定字詞的問題(例如一個勾選記號可能代表劃掉、是否合併兩張桌子、是否命名某個資源)則在建立應用程式之前放入 <執行記錄名稱>/review/extra.json 作為檢查和決策事項;apply_review.py 會將答案列在 <執行記錄名稱>/review/to-action.md 中供你處理。請參閱 tools/review/README.md。

6. 發布(在人類檢查過草稿之後)

將審查者的修正套用到 session.json,將 meta.status 設為 "final",然後:

python3 ingest/ingest.py publish --links  # 如果任何內容無法追溯或任何區段為空,則拒絕執行

這會撰寫 data/session.json 和 playbook/index.html。playbook/ 資料夾是一個靜態網站:將其部署到任何地方都是一個獨立的步驟,因此請先詢問。頁面中的所有連結都由腳本處理,因此直接從磁碟開啟也能正常運作。

絕對禁止

  • 根據一般知識添加內容,即使是「有幫助的」背景資訊。留空也比發明內容好。
  • 默默猜測一個字詞:使用 [?字詞] 或 [無法辨識] 並列出它。
  • 在已發布的頁面上放置任何人的姓名或雇主名稱,但承諾者在其卡片上親自書寫的姓名和組織名稱除外(verify 會檢查這些內容是否與卡片相符)。
  • 在 verify 通過且人類已閱讀過草稿之前發布。

後續工作

照片和語音備忘錄可能包含姓名和臉孔。一旦劇本書定稿,請提醒使用者刪除 runs/*/audio、原始照片和語音備忘錄,以及主辦單位同意不保留的任何其他內容。

相關技能