mz038197 Readmoo 階段一：從流程說明到截圖腳本完成
本 skill 對齊 wiki《Readmoo 網頁版匯出（Playwright）》中 人工起點 → 儲存 storage state → 純截圖腳本跑完並驗證 的範圍。不含 OCR（readmoo_ocr_pages.py）與組章（readmoo_assemble_markdown.py）；若使用者要全管線，先讀同一 wiki 的後半段。
權威來源
- Wiki（完整細節、話術、禁止事項）：
G:\我的雲端硬碟\Obsidian\Agent\wiki\Readmoo-網頁版匯出-Playwright流程.md - 階段一截圖腳本與本 skill 同捆，固定路徑：
- 相對於 skill 目錄：
scripts/readmoo_capture_snapshots.py - Windows 範例：
%USERPROFILE%\.cursor\skills\readmoo-capture\scripts\readmoo_capture_snapshots.py
- 相對於 skill 目錄：
readmoo-auth.json：預設放在專案根目錄（與 wiki／state-save慣例一致）。Agent 進入流程時先檢查該路徑是否存在且為一般檔案；有則優先走「直接截圖」嘗試，無或截圖判定過期再走playwright-cli登入與state-save。- playwright-cli（
open／state-save）：在同一專案根目錄（workspace 根）執行。 - 執行截圖腳本：仍在該專案根目錄下用
uv run呼叫 skill 內腳本的絕對路徑（見關卡 4）。不要改用專案根目錄的readmoo_capture_snapshots.py或其他複本，以免與本 skill／manifest.json的capture_script欄位約定不一致。 - 專案尚無 uv 環境時：Agent 應在專案根先依 關卡 3 完成
uv init（僅當無pyproject.toml）與uv add playwright pillow，再uv sync與安裝 Chromium；不要在未確認依賴前就跳去關卡 4。
Agent 行為原則（本階段）
- 先說明階段目標，再給指令；不要一次混談 OCR／分章。
- 一次只推進一個關卡；下一關前確認產物存在。
- 進入後第一步：在專案根目錄（已
cdworkspace 根）檢查readmoo-auth.json是否存在。- 存在：向使用者簡短說明「先沿用既有登入狀態嘗試截圖；若失敗再請你登入重存」→ 確認依賴後優先執行截圖腳本（關卡 4）。
- 不存在：進入 關卡 1–2（
open→ 登入與第一頁 →state-save），再截圖。
- 過期／無效判定：截圖腳本若因仍停在登入頁而結束（stderr 提示
signin、或程序退出碼 2），視為readmoo-auth.json已過期或不適用 → 不要重複盲跑；改引導使用者走 關卡 1–2 重新製作readmoo-auth.json，再執行關卡 4。 - 絕不代替使用者決定「第一頁」：僅在需重新
state-save時（B 路徑），必須由使用者在playwright-cli開出的視窗內手動翻到起點頁。若走 A 路徑（沿用既有 json），起點為當初存 state 時的頁面；若要改起點，必須重走 B 路徑並在存檔前翻到新起點。 - 在 B 路徑中，於使用者明確回覆「已登入且已到第一頁」且瀏覽器仍開著之前，不要執行
state-save。 - Python 依賴與腳本執行：優先 在專案根用 uv（見關卡 3：
uv init→uv add→uv sync→uv run …）；與 wiki 一致。使用者若堅持以全域python執行可配合，但 Agent 預設仍走 uv。 readmoo-auth.json含 cookie／儲存狀態，勿提交 git；若專案尚未忽略，提醒列入.gitignore。
階段閘門檢查清單
| 關卡 | 進入條件 | 產物／狀態 |
|---|---|---|
| 0 說明對齊 | 使用者要開始 Readmoo 匯出 | 使用者理解：優先沿用 readmoo-auth.json；必要時才登入重存；階段一只截圖 |
| 0a 檢查 auth | 已 cd 專案根 |
確認 readmoo-auth.json 有／無；決定走 A 或 B 路徑（見下） |
| 0b uv 專案就緒 | 將執行關卡 4 前 | 專案根有 pyproject.toml 且已納入 playwright、pillow（見關卡 3）；否則先 uv init／uv add／uv sync |
| A 直接截圖 | 有 readmoo-auth.json；依賴已就緒；已對齊 --max-pages |
執行關卡 4；成功則產物齊；若 signin／exit 2 → 轉 B |
| B1 開閱讀器 | 無 auth 或 A 失敗；有 mooreader 網址 | 可見 headed 視窗 |
| B2 登入與第一頁 | 使用者完成 | 網址為 mooreader、可見內文、非 signin；視窗勿關 |
| B3 state-save | 上列皆真 | readmoo-auth.json 寫入專案根 |
| 4 截圖腳本 | readmoo-auth.json 存在；已確認 --max-pages |
readmoo_<ID>/assets/*.png、manifest.json、run.log |
路徑摘要：0a → 0b（必要時）→ 若有 auth → A → 4；若無 auth 或 A 判定過期 → B1 → B2 → B3 → 4（關卡 4 前仍須滿足 0b）。
關卡 1：開啟閱讀器（playwright-cli，僅 B 路徑）
在專案根目錄開終端機，執行（將書籍 ID 換成實際數字）：
playwright-cli open --headed --persistent "https://new-read.readmoo.com/mooreader/你的書籍ID"
Agent 應提示使用者：只用這個視窗登入；翻到要當起點的第一頁；完成後回覆「已登入並到第一頁」。必須 --headed（避免看不到視窗）；建議 --persistent 以利與後續 state-save 一致。
若使用者看不到視窗：Alt+Tab、第二螢幕、確認有 --headed。
關卡 2：儲存 storage state（僅 B 路徑）
同一專案目錄，瀏覽器仍為 playwright-cli 開啟且已完成登入與第一頁定位：
cd <專案根目錄>
playwright-cli state-save readmoo-auth.json
完成後 agent 必須確認檔案存在；若不存在，停止，不要跑截圖腳本。
重點：state 必須來自 playwright-cli 這個 Chromium，不是一般 Chrome 手動匯出。
關卡 3：依賴（僅首次、環境變更，或專案尚無 pyproject.toml）
Agent 進入流程時：在專案根檢查是否存在 pyproject.toml，且依賴是否已含 playwright、pillow（截圖腳本與末頁指紋所需）。未就緒則依序完成下列步驟，再進關卡 4。
3a 專案根尚無 pyproject.toml
在專案根目錄初始化並加入依賴（非互動；目錄已非空時仍可執行）：
cd <專案根目錄>
uv init --no-readme
uv add "playwright>=1.49.0" "pillow>=11.0.0"
若使用者已手動建立空專案、僅缺依賴，可略過 uv init，直接 3b。
3b 已有 pyproject.toml 但尚未加入 playwright／pillow
cd <專案根目錄>
uv add "playwright>=1.49.0" "pillow>=11.0.0"
3c 同步與瀏覽器二進位
cd <專案根目錄>
uv sync
uv run playwright install chromium
完成後以 uv run python -c "import playwright; import PIL" 快速自檢（無錯誤即可）。
關卡 4：純截圖腳本（階段一）
進入前再次確認：專案根目錄有 readmoo-auth.json；與使用者對齊本次 --max-pages（主要停止條件）。
若剛從 A 路徑失敗轉入 B 路徑，須在 B3 完成後再執行本關。
建議（有視窗，方便觀察翻頁）：在已通過關卡 3 的專案根目錄（通常即 Cursor workspace 根）執行；腳本本體在 skill 目錄。
$CAP = Join-Path $env:USERPROFILE '.cursor\skills\readmoo-capture\scripts\readmoo_capture_snapshots.py'
cd <專案根目錄>
uv run $CAP --storage-state readmoo-auth.json --url "https://new-read.readmoo.com/mooreader/你的書籍ID" --max-pages 120
（$CAP 可改為你機器上該 skill 的實際絕對路徑；重點是 uv run 的目標檔必須是 skill 內的 scripts/readmoo_capture_snapshots.py。）
可選參數（與腳本一致）：
--out-dir：輸出根目錄。未指定時，預設為目前工作目錄（Path.cwd()）下的readmoo_exports；在 Cursor 內建終端若已cd到專案根，即等同 workspace 根目錄（對應_default_out_root()）。若要寫入 wiki 的 raw，請自行傳--out-dir "G:\我的雲端硬碟\Obsidian\Agent\raw\readmoo_exports"。--headless：無頭模式（launch(headless=True)）。--pause-ms（預設 900）、--same-streak（預設 1）有無 headless 都會生效：前者控制每步等待；後者用於翻頁後 viewport 指紋連續相同達該次數則視為末頁。- 停止條件（腳本已移除依章節停止）：主要為
--max-pages；另可因--same-streak判定末頁而提前結束。
執行後常見結束原因
- 達
--max-pages - 末頁偵測（連續翻頁畫面指紋不變達
--same-streak） - 網址仍含
signin→ state 無效或過期，應回到關卡 1–2 重做，不要硬跑 OCR
完成驗證（階段一「完成」的定義）
在輸出目錄下檢查（預設為 workspace（目前工作目錄） 下 readmoo_exports/readmoo_<書籍ID>/，有傳 --out-dir 則依該路徑）：
assets/內有預期數量的p*.pngmanifest.json存在run.log存在（若腳本有寫入）
Agent 應向使用者簡報：張數、是否有 manifest、停止原因（max-pages／末頁／錯誤）。
僅有舊截圖、沒有 manifest
不要直接進 OCR。先：
uv run readmoo_backfill_manifest.py --book-dir <readmoo_書籍目錄>
本階段應避免（對齊 wiki 第八節之精簡版）
- 專案根明明已有
readmoo-auth.json，仍一律從頭逼使用者登入（應先嘗試 A 路徑） - signin／exit 2 後仍反覆執行截圖而不引導重存 state
- 在 B 路徑中，使用者未確認登入與第一頁就執行
state-save - Agent 自行假設「現在就是第一頁」
- 把截圖、OCR、分章同一則訊息講完
- 缺
manifest.json仍帶使用者跑readmoo_ocr_pages.py
話術骨架（僅到階段一結束）
若已有 readmoo-auth.json（A 路徑）
- 「專案裡已有
readmoo-auth.json，我先沿用這份登入狀態跑階段一截圖；若登入已過期，再請你依流程重新登入並存檔。」 - 「這次要抓幾頁？我會用
--max-pages設定。」 - （若失敗）「狀態可能過期了。請依下面步驟用
playwright-cli登入、翻到你要的起點頁，再state-save，我們再跑一次截圖。」
若沒有 auth 或 A 失敗後（B 路徑）
- 「請在
playwright-cli開出的視窗登入，並翻到你要當起點的第一頁。完成後告訴我。」 - 「接下來在同一專案目錄執行
playwright-cli state-save readmoo-auth.json。」 - 「然後我只跑階段一截圖，不做 OCR。這次要抓幾頁？我會用
--max-pages設定。」 - 「跑完後我會確認
assets/與manifest.json。」
後續（本 skill 不展開執行）
- 階段二：
uv run readmoo_ocr_pages.py --book-dir <readmoo_書籍目錄> - 階段三：
uv run readmoo_assemble_markdown.py --book-dir <readmoo_書籍目錄>
細節與 OCR 引擎選擇見 wiki 第四、五節。