從螢幕截圖建立使用者手冊 / Screenshot → User Manual
輸入：螢幕截圖 + 一份範例使用者手冊。輸出：一份新手冊，其風格和結構模仿範例手冊，但內容來自螢幕截圖。
此檔案為雙語：指令為繁體中文，關鍵規則以英文重複。生成的手冊語言為使用者要求的語言；若未指定，則使用參考手冊的語言。
1. 輸入 / Inputs
| 輸入 | 必要 | 備註 |
|---|---|---|
| 螢幕截圖 | ✅ | 資料夾或檔案清單。排序提示：檔名、時間戳、EXIF。 |
| 範例使用者手冊 | ✅ | .pdf、.docx、.md、.txt、.html。是風格和結構的來源。 |
| 產品/流程名稱 | ➖ | 若無，從螢幕截圖推斷，並請使用者確認。 |
| 目標受眾和語言 | ➖ | 若無，從參考手冊推斷。 |
| 輸出格式 | ➖ | 預設：Markdown（可選 .docx / 可列印 .html）。 |
| 品牌資訊 | ➖ | 公司、文件編號、修訂版 — 若未提供，則保留佔位符。 |
在提問前，先嘗試從輸入中推斷缺失資訊。 僅針對無法從螢幕截圖和參考手冊中推斷的內容提問；最多 3 個問題。
Infer before you ask. Ask at most 3 questions, only for what the images and the reference manual cannot answer.
資訊優先級 / Source priority
若有衝突，依此順序決定 — 排在上面的優先：
- 使用者明確提供的資訊
- 螢幕截圖
- 機器/產品照片
- 參考手冊的範本資訊
- 一般技術知識（僅可用於避免保留佔位符；不算編造，但需要確認）
On conflict: user's explicit statements > screenshots > photos > reference template > general knowledge.
兩種模式 / Two modes
| 模式 | 何時使用 | 保留什麼 |
|---|---|---|
| 風格模式 | 參考是簡單的 .md/.txt | 標題佈局、步驟語氣、警告格式 |
| 樣板模式 | 參考是企業 PDF/DOCX（含封面、目錄、頁首、文件編號） | 章節順序、編號、文件識別碼、表格/警告格式 完全保留；內容以實際產品填充 |
在樣板模式下，不要複製 PDF 的內容。 將樣板作為骨架，從螢幕截圖生成內容。如果章節已存在，保留並完善；如果缺失，則以符合文件設計的方式新增章節。
In template mode: keep the section order, numbering and document identity; never copy the PDF's sentences — fill it with what the screenshots show.
2. 輸出 / Outputs
<output-folder>/
├── manual.md # 主要交付 — 新的使用者手冊
├── images/ # 複製/重新命名的螢幕截圖
├── manual.html # （可選）可從瀏覽器列印的版本
├── manual.docx # （可選）Word 版本
└── 00-analysis.md # 工作筆記：螢幕截圖清單 + 風格約定
00-analysis.md 不是交付文件，而是可審計的證據：它顯示哪些螢幕截圖對應到哪個步驟，以及從參考中採用了哪些風格決策。請始終生成它。
3. 工具對應 / Tool mapping
此技能並非為特定工具編寫。請使用你手邊可用的工具：
| 需求 | Claude Code | Cursor | Codex / DeepSeek Harness | 其他 |
|---|---|---|---|---|
| 查看圖片 | Read（圖片） | Read | read_image | 將圖片附加到訊息中 |
| 寫入檔案 | Write / Edit | Write | write / edit | 編輯器 |
| 執行腳本 | Bash | 終端機 | pwsh / bash | 終端機 |
讀取 .docx / .pdf | Bash + python | 終端機 | pwsh + python | python |
關鍵： 必須實際查看圖片。切勿根據檔名或你事先知道的介面來推測內容。
Always actually view the images. Never infer screen content from file names.
4. 工作流程 / Workflow
使用此清單追蹤進度：
- [ ] 1. 收集並驗證輸入
- [ ] 2. 從參考中提取風格約定
- [ ] 3. 逐一讀取每個螢幕截圖
- [ ] 4. 將螢幕截圖排序成流程，標記缺口
- [ ] 5. 撰寫手冊草稿
- [ ] 6. QA 關卡 — `check_manual.py`
- [ ] 7. 交付（+ 可選的 docx/html）
步驟 1 — 收集並驗證輸入 / Intake & validate
- 列出所有螢幕截圖檔案；報告數量與格式。
- 讀取參考手冊（
.docx→ python-docx，.pdf→ pypdf/pdftotext，純文字 → 直接讀取）。 - 若有無法讀取或損毀的檔案，立即告知，不要默默略過。
- 確定輸出資料夾，並建立
images/子資料夾。 - 複製圖片： 將手冊中會用到的每張螢幕截圖複製到
images/下。 保留檔名（例如01-login.png→images/01-login.png）；若重新命名，QA 腳本會用內容雜湊進行比對，但保留檔名以確保順序更安全。不要寫入原始資料夾的相對路徑。
List every screenshot, read the reference manual, report unreadable files, create the output folder, then COPY each screenshot into images/ keeping its file name. Never link back to the original screenshots folder.
步驟 2 — 從參考中提取風格約定 / Extract the style contract
先測量，再解釋：
python <skill-directory>/scripts/read_reference.py <sample-manual> \
--out 00-analysis-reference.md --json 00-analysis-reference.json
此腳本從 PDF/DOCX/MD 中提取經過測量的側寫：文件資訊、標題層級、編號深度、每頁重複的頁首/頁尾（文件編號、修訂版）、圖/表標題樣式、字型大小與顏色。將輸出移入 reference/style-contract.md 表格。
read_reference.py 需要 PyMuPDF（用於 PDF）和 python-docx（用於 DOCX）；若兩者皆無，請向使用者索取 .md/.txt 版本（腳本會輸出安裝命令）。
你將不會複製參考手冊的內容，而是複製其格式。
填入 reference/style-contract.md 中的欄位，並將其寫入 00-analysis.md：
- 標題層級與編號（
1.、1.1、步驟 1、章節） - 步驟句子的語氣（命令式、'按一下'、敬語'請按一下'）與長度
- 螢幕截圖位置：步驟前或步驟後、是否有標題、是否編號
- 警告/提示框類型（注意、警告、提示、小心）及其標記方式
- 表格、清單、粗體字的使用
- 前置內容：封面、版本、日期、目錄
- 後置內容：常見問題、疑難排解、詞彙表
- 語氣：正式/非正式、'您'/'你'
- 術語詞彙表（參考中使用的命名方式）
- 文件識別碼： 文件編號、修訂版、日期、公司區塊（在樣板模式下完全保留；若值未知則保留佔位符）
- 編號深度： 若參考使用 4 層編號（如
6.5.1.1），新手冊也應使用相同深度
Extract form, not content: hierarchy, numbering, step voice, image placement, callout types, tables, front/back matter, tone, terminology, document identity.
步驟 3 — 逐一讀取每個螢幕截圖 / Read every screenshot
根據 reference/screenshot-analysis.md 綱要為每個圖片記錄：
| 欄位 | 範例 |
|---|---|
| 檔案 | 03-settings.png |
| 螢幕/頁面名稱 | 設定 |
| 可見的主要元件 | 左側選單、儲存按鈕、語言下拉選單 |
| 所執行的動作 | 從 '語言' 下拉選單中選取繁體中文 |
| 狀態 | 前 / 後 / 中間步驟 |
| 高亮 / 箭頭 / 框線 | '儲存' 按鈕上的紅色框線 |
| 無法讀取 / 不明確 | 欄位名稱模糊 → [?] |
| 步驟編號（草稿） | 4 |
禁止編造： 不要寫出螢幕上看不到的按鈕名稱、選單路徑、欄位標籤或錯誤訊息。若不確定，請使用 [?] 並將其加入「待解決問題」章節。
針對介面/HMI 手冊的每個螢幕說明區塊。 為每個螢幕截圖撰寫以下五個部分（這是操作員文件中預期的結構）：
### <螢幕名稱>
**用途。** 此螢幕的用途 — 1–2 句話。
**螢幕上的資訊。** 顯示的值、指示器、狀態顏色。
**按鈕功能。**
| 按鈕 | 功能 | 說明 |
|---|---|---|
**操作員使用說明。** 逐步說明如何操作。
**注意。** 若有錯誤使用則提供警告；若無，則不寫此行。
使用參考的標題格式（例如 圖 12 – 交流馬達頁面）。
透過編號來說明圖片中的重要元素（1 – START、2 – STOP），但不要縮小到影響可讀性，或直接在圖片上書寫。
For UI/HMI manuals, describe every screen with the five-part block: purpose, displayed values, button table, operator steps, cautions. Number callouts only when it improves clarity.
Never invent a button label, menu path, field name or message that is not visible in the image. Mark uncertainty with [?] and list it under Open questions.
步驟 4 — 將螢幕截圖排序成流程 / Order into a flow
- 使用排序信號：檔名編號 → 時間戳 → 螢幕狀態（前/後） → 邏輯流程。
- 將螢幕截圖分組為章節（例如：安裝、初始設定、日常使用）。
- 標記缺口： 例如「從步驟 1 到步驟 3 缺少中間螢幕」。不要編造缺少的步驟；請向使用者要求，或將其寫入「待解決問題」章節。
- 將每張螢幕截圖恰好對應到一個步驟。如果同一張螢幕截圖涵蓋多個步驟，請在一個步驟中使用該圖片，並在文字中引用另一個步驟。
Order with file names → timestamps → before/after state. Group into sections. Flag gaps instead of inventing steps. One screenshot maps to exactly one step.
步驟 5 — 撰寫手冊草稿 / Draft the manual
使用 templates/manual-template.md 結構，並以步驟 2 的風格約定填寫。規則：
- 每個步驟 = 一個動作 + 顯示該動作的一張螢幕截圖。
- 步驟文字簡短：1–3句話。若需要說明理由/理論，請移到獨立的「為什麼？」備註中。
- 圖片路徑使用相對路徑且可攜帶：
。將標題調整為參考的格式。 - 保持與參考相同的標題和編號方案；內容則來自螢幕截圖。
- 嚴格使用參考詞彙表中的術語 — 不要使用同義詞。
- 若參考中有前置內容（標題、版本、目標受眾）和後置內容（常見問題、疑難排解、詞彙表），則加入；否則不加。
- 任何無法從螢幕截圖驗證的資訊都必須標記：短暫不明確用
[?]，缺失資訊則使用reference/placeholders.md詞彙表中的說明性佔位符（[待製造商填寫]、[需要驗證]…）。 - 在手冊末尾加入 「待解決問題 / Open Questions」 章節（若無內容則寫「無。」）。 此章節是 QA 附錄，非參考風格的一部分；使用者可以在發佈前將其刪除。請在交付訊息中說明。
- 區分操作員和技術服務資訊。 PLC 程式設計、標籤名稱、伺服參數、軟體演算法和通訊細節不應放在提供給操作員的主要章節中；如有需要，請在「技術服務 / 維護人員」標題下另闢章節。
One step = one action + one screenshot. Relative image paths. Mirror the reference's numbering and terminology. Mark unverifiable claims with [?].
步驟 6 — QA 關卡 / QA gate
從專案根目錄執行命令，並根據技能資料夾指定腳本的完整路徑 — 腳本與手冊位於不同資料夾：
python <skill-directory>/scripts/check_manual.py <output>/manual.md \
--screenshots <screenshots-folder> --reference <sample-manual.md>
腳本會檢查：圖片路徑是否存在、每張螢幕截圖是否至少被使用一次（透過名稱或內容雜湊）、標題/章節編號是否連續、步驟編號是否一致（全局或按章節）、是否殘留 TODO/XXX/<佔位符>、[?] 標記是否在「待解決問題」章節中、還有多少欄位佔位符待填寫。
若有錯誤，修正並重新執行。未通過前不要交付。
不要將 .docx/.pdf 作為 --reference 傳遞；請先使用 read_reference.py 提取側寫以進行風格比較（腳本會發出警告）。
Run the checker; fix and re-run until it passes. Do not deliver a failing manual.
步驟 7 — 交付 / Deliver
manual.md+images/+00-analysis.md已就緒。- 若要求：
python <skill-directory>/scripts/convert.py <output>/manual.md --format docx,html（若--out指定其他資料夾，圖片也會複製到該處；--lang用於指定 HTML 語言）。.docx需要 python-docx；若無，腳本會輸出安裝命令。.html始終可生成，並可從瀏覽器使用 Ctrl+P → PDF 列印。
- 在樣板模式下，將文件編號/修訂版放入
.docx的頁首，頁碼放入頁尾（請參閱convert.py --doc-no、--header、--footer）。 - 交付訊息中說明：多少張螢幕截圖、多少個步驟、多少個章節、多少個
[?]、多少個欄位佔位符，以及缺失的螢幕截圖清單（如有）。
5. 硬性規則 / Hard rules
- 未查看前不寫作。 必須實際查看每張螢幕截圖；不要從檔名推測內容。
- 禁止編造。 不要寫出螢幕上不存在的標籤、選單、訊息、版本或數字。
- 格式來自參考，內容來自螢幕截圖。 不要複製參考手冊中的句子。
- 不明確的內容必須可見。 使用
[?]+ 「待解決問題」章節；不要默默猜測。 - 一張螢幕截圖 = 一個步驟。 不留任何未使用的圖片。
- 可攜帶的路徑。 使用
images/...相對路徑；不要使用 Windows 絕對路徑。 - 使用使用者的語言。 手冊語言為要求的語言；非技能說明的語言。
- 報告缺失的輸入。 若有無法讀取的檔案或缺少中間螢幕截圖，請告知。
- 若無法查看則停止。 如果你無法讀取圖片（因工具或模型不支援），不要開始撰寫手冊。告知使用者你無法在此工作階段讀取圖片，並要求切換到具有圖片讀取能力的工作階段。禁止從檔名推測內容。
1 Never write without viewing. 2 Never invent UI. 3 Form from reference, content from images. 4 Surface uncertainty with [?] or an explicit placeholder. 5 One screenshot = one step, none unused. 6 Relative image paths. 7 Manual language = requested language. 8 Report …