工作表變劇本書 (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、原始照片和語音備忘錄,以及主辦單位同意不保留的任何其他內容。