# 我把「截圖寫操作手冊」這件苦差事做成 Claude Code skill：screendoc 拆解
TL;DR
- 我把「給前端專案截圖、寫操作手冊」這件每次改版都要重做一遍的苦差事，做成一個 Claude Code skill：
/screendoc。 - 一句指令
/screendoc .，它會自己偵測你的前端框架、跑 Playwright 截圖、對每張圖寫敘事說明、再用 4 個審查視角（UI/UX、系統分析、新手、開發者）逐張比對「截圖 vs 說明 vs 原始碼」，不一致就局部重截、迭代到全過，最後吐一份對外可發表的 HTML 操作手冊。 - 它解決的核心痛點是手寫手冊的三個老問題：截圖跟當前 UI 對不上、說明文字跟截圖內容不一致、改版後整本要重截。
- 已經包進我的 Claude Code plugin yc-plugin，裝了 plugin 就自動有這個 skill，下方有完整安裝步驟。
- 這篇講三件事：它在幹嘛、為什麼要這樣設計（4 視角 + 強制對齊不是過度設計）、你怎麼把它裝起來用。
---
手寫操作手冊的三個老問題
我教職訓局，也接案做內部系統。每次系統交付都要附一份操作手冊給不寫 code 的使用者看 —— 醫護人員、行政、業務。手冊長這樣：一張截圖配一段「點這裡、填這個、按送出」。
聽起來很簡單，做過的人都知道有三個坑：
這三個坑的共通點：手冊是「手工拼貼」的，截圖、文字、真實系統三者各走各的，沒有任何機制保證它們同步。
我想要的是：手冊的每張圖都從真實渲染的頁面來、每句說明都對得上截圖裡實際存在的元素、改版後一句指令重跑。這就是 screendoc。
---
screendoc 在幹嘛：一句話到一份 HTML
最短的描述：
/screendoc .. 是你的前端專案根目錄。下完這句，screendoc 一條龍跑完，產出一份 manual.html，丟給使用者或掛上內網就能看。
它不是「幫你截圖的工具」那麼簡單。截圖只是第一步，真正的價值在後面的對齊與審查：
- 截圖：用 Playwright 開真實的 dev server、走頁面、截圖。不是你手動按 PrintScreen，是程式化地走過每個頁面、每個狀態。
- 對齊：每張圖配一段敘事性說明（caption），而且強制要求 caption 講的元素真的出現在那張圖裡。
- 審查：4 個視角輪流看每一張圖 + 對應的 caption + 對應的原始碼，挑出「圖跟說明對不上」「說明跟程式行為對不上」的地方，標出來、局部重截、再審，迭代到全部通過。
- 產出：通過審查後全部重跑一次，產出最終 HTML。
---
Phase 0 到 5：它到底跑了什麼
screendoc 內部分成 6 個階段，每階段都有明確產出物落檔，斷了可以續跑：
| Phase | 名稱 | 做什麼 |
|---|---|---|
| 0 | PRECHECK | 偵測專案類型：前端框架（React / Next / Vue / 其他）、dev server 怎麼啟、有沒有現成的 e2e 測試可以接 |
| 1 | ANALYZE | 產出截圖清單（shotlist），每一張鎖定一個 DOM anchor，確保截到的是對的頁面、對的狀態 |
| 2 | SCREENSHOT | 跑 Playwright spec 截圖，外加一次全頁面樹掃描（確認沒漏掉重要畫面） |
| 3 | CAPTION | 對每張圖寫敘事性說明，並產一份縮圖審查手冊（給後面審查用） |
| 4 | REVIEW LOOP | 4 視角並行審查 → 找問題 → 局部重截 → 再審，迭代到全數通過（預設上限 20 輪） |
| 5 | FULL REBUILD | 全部通過後清空重跑一次，產出最終 manual.html |
Phase 1 鎖 anchor。截圖最容易出包的是「截到一半的 loading 畫面」或「截錯頁」。screendoc 在分析階段就為每張圖指定一個必須出現的 DOM 元素當錨點，Playwright 等到那個元素出現才截 —— 截到的保證是穩定狀態。
Phase 4 是個迴圈不是一次性。審查發現問題不是丟給你「這裡有 12 個問題自己改」，而是自動局部重截、重寫 caption、再送審，直到通過或達上限。這個「死磕到對」的精神來自社群的 ralph-loop。
---
為什麼要 4 個審查視角
這是整個 skill 最不像「過度設計」的過度設計 —— 一開始我也覺得一個視角夠了，實際跑才發現不同視角抓到的問題完全不重疊：
- UI/UX 視角：看視覺。這張圖構圖有沒有切到、重點元素在不在畫面裡、有沒有截到無關的彈窗。
- 系統分析（SA）視角：看流程完整性。功能名稱對不對、頁面之間的跳轉邏輯有沒有斷、權限頁面有沒有漏。
- 新手視角：看「看得懂嗎」。一個第一次用這系統的人，照著這段 caption 能不能找到按鈕、做完這一步知不知道下一步去哪。
- 開發者視角：看真實性。這是最關鍵的一條 —— caption 說的功能、欄位、預設值，跟原始碼裡實際寫的對不對得上。它會去讀對應的 component / schema，揪出「手冊寫了一個 UI 上根本不存在的欄位」這種 schema 與 UI 不同步的問題。
4 個視角不是為了「看起來嚴謹」，是因為一個 LLM 一次戴一頂帽子看得比較準。同時要它「又看美感又看流程又看新手又看程式碼」，它會每個都看得淺。分開跑、各司其職，抓出來的問題才有深度。
---
為什麼縮圖審查、發布內嵌兩種模式
產 HTML 的時候有個現實問題：審查階段要讓 reviewer 看圖，但全尺寸 PNG base64 內嵌會讓 HTML 肥到讀不動。
所以 screendoc 的 HTML 建置器有兩個模式：
- 審查模式：圖縮成 800×500 的 WebP（q80）、走相對路徑引用。HTML 輕、reviewer（包括 AI reviewer 用 Read 讀）載得動、看得清。
- 發布模式：圖以 base64 直接內嵌進 HTML。產出單一檔案、完全離線可看 —— 使用者拿到一個 .html 雙擊就開，不依賴任何外部圖檔、不怕圖檔搬家後失聯。
thumbnails/xxx.webp 引縮圖，這個相對路徑是相對 HTML 檔所在目錄的。HTML 如果輸出到別的地方，瀏覽器跟 reviewer 都會 404、圖全壞。所以審查 HTML 必須跟縮圖目錄輸出在同一層 —— 這條約定我寫死在 skill 裡了，免得每次重踩。
---
我真的在一個 React 專案上跑了一次
寫工具最怕「只在自己熟的專案上能跑」。screendoc 早期是為了我接的一個 NocoBase 系統寫的，所以我刻意找了一個完全無關的 React + Vite + Tailwind 純前端單頁站來驗證它在非原生環境跑不跑得通。
結果（round-trip 驗證，不是看 log 綠燈）：
- 框架偵測：Phase 0 正確認出是 React + Vite，用對的 dev server 啟法。
- 設計系統適配：screendoc 內建一組設計系統 adapter（generic / antd / mui / chakra / radix / mantine），靠環境變數選。這個站沒用 UI 框架，走 generic preset，
shot()/waitReady()這些 helper 一樣生效。 - 兩種模式：審查模式產縮圖手冊、發布模式產 base64 單檔，都正確生成。
- 瀏覽器渲染：最後我開瀏覽器點開產出的 manual，4 張縮圖
naturalWidth > 0、零 broken image —— 這才算「人看得到的輸出」，不是 build 成功就喊好。
@playwright/test 要隔離安裝、審查 HTML 路徑約定），都回寫進 skill 文件了。一個工具值不值得分享，標準就是「在我沒預期的環境也站得住」。
---
怎麼裝、怎麼用
screendoc 包在我的 Claude Code plugin yc-plugin 裡。Claude Code 的 plugin 支援內嵌 skill（auto-discovered），所以裝了 plugin，/screendoc 就自動可用，不用額外設定。
安裝
在 Claude Code 裡：
/plugin marketplace add yanchen184/yc-plugin
/plugin install yc-plugin裝完重啟 session，輸入 /screendoc 就會觸發。
使用
/screendoc . # 當前目錄就是前端專案根
/screendoc /path/to/my-react-app # 指定專案路徑
/screendoc ./apps/web --code-mode=write # 審查發現 UI bug 時允許改 source
/screendoc . --max-iterations=30 # 放寬審查迭代上限（預設 20）| 參數 | 預設 | 說明 |
|---|---|---|
<入口路徑> | 必填 | 專案根目錄、或現成的 e2e/ 目錄 |
--code-mode | read | read 只改 spec/caption 不動你的 source；write 審查發現 UI bug 可改 source |
--max-iterations | 20 | 4 視角審查 → 修 → 局部重截 的迴圈上限 |
系統需求
- Node.js + Playwright —— skill 會引導在隔離目錄裝
@playwright/test，不污染你的專案。 - Python 3.10+ + Pillow —— 產縮圖手冊用（
pip install pillow）。
跟其他做法比較
| 做法 | 截圖來源 | 圖文同步保證 | 改版重做成本 | 適合誰 |
|---|---|---|---|---|
| 手動截圖 + Word/Notion | 人手按 PrintScreen | 無，全靠你記得 | 高，整本重來 | 一次性、不會再改的系統 |
| 錄影 + 旁白 | 螢幕錄影 | 無，且不能 grep | 極高，要重錄重剪 | 操作示範影片 |
| Storybook / 元件文件 | 元件層截圖 | 元件層對齊，但非「使用者流程」 | 中 | 給開發者看的元件庫 |
| screendoc | Playwright 跑真實頁面 | 4 視角審查強制對齊圖/文/碼 | 低，一句指令重跑 | 要給終端使用者、會持續改版的系統 |
---
FAQ
（見頁面下方 FAQ 區塊）
---
延伸資源
- yc-plugin（含 screendoc）：github.com/yanchen184/yc-plugin ——
/plugin install就能拿到。 - Claude Code Plugins 官方文件：code.claude.com/docs —— 想了解 plugin 怎麼內嵌 skill。
- Playwright：playwright.dev —— screendoc 的截圖引擎。
- ralph-loop（迭代精神來源）：screendoc 的 Phase 4「死磕到對」迴圈，概念來自社群的 ralph-wiggum loop。
- 想看我怎麼用 Claude Code skill 做其他自動化，可以看 Claude Code 第三堂：Skill / Subagent / Slash Command 差在哪。