fernbrook-labs/beginner-reference-book

製作初學者參考書（入門指南）

為程式語言或框架製作入門參考書，並以與先前製作的 TypeScript、Rust、Angular、Go 入門指南（範例位於 references/examples/）完全相同的設計、功能與流程來進行。最終產出以下兩項：

• 放置於桌面的單一 HTML 檔案（〇〇入門指南.html，可雙擊開啟）
• claude.ai 的共享頁面（非公開，由使用者透過 Share 選單共享）。僅在可使用 Artifact 工具的環境（如 Claude Code）下建立

為保持設計一致，外觀與互動功能必須直接使用本技能的元件（assets/ 與 scripts/），不得每次重新編寫 CSS 或 JavaScript。需要撰寫的內容僅為正文（稿件）以及與語言相關的程式碼驗證方式。

參考書的核心價值在於「收錄的程式碼與結果完全正確」。所有程式碼範例、錯誤訊息與執行結果，必須經由實際編譯器或官方 Playground 驗證（不得憑空想像）。版本說明與新功能介紹也必須查驗官方發行說明後再撰寫。

這項工作耗時數小時，請在每個階段以 1–2 句話向使用者說明目前進度。

1. 確認輸入內容

輸入內容為技能名稱後所附加的文字（通常以 ARGUMENTS: 的形式附加於此技能本文末尾）或使用者請求中提及的語言/框架名稱。

• 若未指定任何內容：不要開始作業，應回問「請問您想為哪個程式語言或框架製作參考書？」（使用 AskUserQuestion 提供最多 4 個選項，如 Python、Java、React、Vue.js；其餘可輸入「其他」讓使用者自由填寫）。
• 若指定的內容並非程式語言或框架：以一句話說明原因，並請使用者重新輸入語言或框架名稱。重新輸入的內容也需經過相同確認，直到輸入正確為止，否則不繼續進行。
• 對於難以判斷、寫法不一致或同時指定多項的情況，以及應使用哪些語句來回應，請參閱 references/questions.md 中的「輸入確認方式」。若遇疑問，務必先行查閱。

若環境不支援 AskUserQuestion，則以一般文字提問相同內容，並在此步驟停留。

2. 進行調查（提問前）

為正確撰寫選項說明，請在提問前確認以下事項（應在數分鐘內完成，避免進行大型下載）：

1. 最新穩定版版本號與發布日期：查閱官方網站或發行說明。用於參考書的版本標示。
2. 是否有官方 Playground（可在瀏覽器中執行的官方網站）：若有，確認是否提供可從外部傳送程式碼進行編譯/執行的介面、是否可將程式碼放入 URL 後直接開啟、或是採用共享連結（將程式碼儲存於伺服器）的方式。
3. 電腦上是否已安裝該語言/框架（例如透過 python --version 確認）。若未安裝，則確認臨時安裝所需的大小（官方下載檔案的大小）。
4. 磁碟可用空間（Windows PowerShell：Get-PSDrive C；Git Bash：df -h /c；macOS/Linux：df -h ~）。
5. 使用者的環境規範（如 CLAUDE.md、AGENTS.md 等）。例如「請勿碰觸與雲端同步的資料夾（如 OneDrive）」等規定，應自調查至清理階段全程遵守。

調查方法及各種語言的驗證方式選項，請參閱 references/verification.md。

3. 詢問選擇項目（與先前相同）

使用 AskUserQuestion 一次詢問以下 4 個項目。項目與選項的寫法應與先前製作參考書時一致（文字模板請見 references/questions.md）。建議選項應置於首位，並標示「（建議）」。若環境不支援 AskUserQuestion（如 Codex），則以編號清單的方式呈現相同問題與選項（並附上章節範圍說明），等待使用者回覆。

1. 目標讀者：例如「JS/TS 經驗者（建議）」、「程式設計初學者」。若為以 TypeScript 為基礎的框架（如 Angular、NestJS），則改為「TypeScript 經驗者（建議）」；若為 Python 的框架（如 Django），則改為「Python 經驗者（建議）」，以此類推。
2. 範圍：「僅基礎（較短，8–9 章）」、「基礎＋常用功能（建議，12–14 章）」、「涵蓋進階（較長，16–18 章）」。請在預覽中顯示各選項的章節大綱。
3. 形式：「與先前相同（建議）」＝ 桌面的單一 HTML 檔案 ＋ 共享頁面，包含練習題、程式碼複製、閱讀記錄、關鍵字搜尋。其他選項為「僅 HTML 檔案」、「自選功能」。若環境無法建立共享頁面（無 Artifact 工具），則「與先前相同」僅指 HTML 檔案，此時不提供「僅 HTML 檔案」選項，說明中也不提及共享頁面。
4. 驗證方式：根據調查結果，僅列出可用的方法。例如「使用官方 Playground 驗證」、「臨時安裝後驗證」、「使用已安裝的語言驗證」等。若磁碟空間不足，應建議不於電腦上安裝任何東西的方法。

根據回答，最多再進行一次後續提問：

• 若選擇「自選功能」→ 以複選方式詢問是否包含「章末練習題」、「程式碼複製按鈕」、「閱讀章節勾選」、「詞彙表」、「關鍵字搜尋」。
• 若驗證所使用的 Playground 為「共享連結方式」（例如 Go Playground，將程式碼儲存於伺服器並產生連結），則詢問「建立共享連結」或「複製貼上」。共享連結會對外公開且無法刪除，務必取得使用者同意。若是可將程式碼放入 URL 後直接開啟的 Playground（如 Rust、TypeScript），因不進行儲存，則無需詢問。

後續所有工作必須完全遵守使用者選擇的內容，不得重複提問。

4. 制定計畫

1. 決定章節大綱（請參閱 references/writing-guide.md）。每章約 10 分鐘可讀完的份量。若為語言類，最後一章應為「常見錯誤解讀」。先前四本書的章節大綱見 references/past-books.md。
2. 撰寫 spec.json（項目與範例請見 references/book-spec.md）。包含封面名稱、版本、目標讀者、章節標題、程式碼語言、Playground 開啟方式、特色（品牌顏色）等。
3. 特色：使用該語言或框架官方品牌顏色。scripts/make_palette.mjs 會從單一顏色生成淺色與深色調色盤，並檢查文字對比度是否可讀（由 new_book.mjs 自動呼叫）。

5. 建立模板並撰寫稿件

1. 工作資料夾應建立在會話的暫存資料夾中（Claude Code 的 scratchpad 等；若無則於作業系統暫存資料夾內新建資料夾）。不得建立在與雲端同步的資料夾（如 OneDrive）下。
2. 建立模板：執行 node <此技能>/scripts/new_book.mjs <書籍資料夾> --spec spec.json
   • 將生成 book.json、palette.json、src/body.html、src/ja-errors.json。
   • src/body.html 中已包含目錄、封面、使用說明、各章框架、練習題框架、附錄框架。請全部替換 <!-- TODO … --> 標記（若有殘留，組合時會顯示「需修正」）。
3. 開始撰寫前，請先閱讀範例。references/examples/ 收錄了先前四本書中擷取的封面、使用說明、代表性章節、錯誤章節、附錄稿件（這些稿件皆使用本技能元件組合並已驗證）。請參考 references/examples/README.md 的表格，選擇與製作目標相近的 1–2 本書，閱讀其 body.html（例如語言類選 go 與 rust；以 TypeScript 為基礎的框架選 angular 與 typescript 等）。實際閱讀範例，比閱讀文字規範更能確保語氣、說明深度、章節大小、程式碼範例呈現方式及練習題粒度的一致性。但請注意，僅模仿寫法，版本、功能等事實資訊仍須自行查驗。不得直接複製範例文字後僅替換詞語。
4. 撰寫稿件。元件的 HTML（如提示框、表格、操作步驟、練習題、錯誤標題等）請遵循 references/components.md；程式碼範例寫法請遵循 references/code-blocks.md；文章寫法請遵循 references/writing-guide.md。由於章節數量較多，建議每撰寫數章就進行組合與驗證。

6. 驗證程式碼範例

node <此技能>/scripts/build.mjs extract <書籍資料夾>   # 將程式碼範例匯出至 work/
node <此技能>/scripts/checkers/go-playground.mjs <書籍資料夾>   # 視語言選擇對應的驗證腳本（見下表）
node <此技能>/scripts/build.mjs render <書籍資料夾>    # 將結果附加至 dist/ 並產生 HTML

驗證腳本	使用時機
checkers/go-playground.mjs	Go。使用官方 Go Playground 進行編譯、執行、go vet、gofmt。--share 可建立共享連結
checkers/rust-playground.mjs	Rust。使用官方 Rust Playground 進行編譯、執行、型別提示
checkers/typescript-local.mjs	TypeScript／JavaScript。使用臨時安裝的 TypeScript 進行錯誤顯示（附官方日文翻譯）、泡泡提示、執行
checkers/local-command.mjs	Python、Java、C# 等。使用本機（或臨時安裝的）命令進行驗證與執行

若遇到此處未列出的語言或框架（例如 Angular 這類需要顯示畫面輸出的情況），請建立新的驗證腳本，並輸出相同格式的結果（work/results.json）。結果格式請見 references/code-blocks.md；建立方法的思路與先前範例請見 references/verification.md。

• 持續修正直到 render 顯示「需修正: 無」為止。若要包含錯誤範例，請在該行加上 // ❌（警告用 // ⚠），以便每次組合時確認是否產生了預期的錯誤。
• 閱讀 dist/report.txt，確認錯誤訊息、執行結果、型別顯示是否與正文說明一致。
• 臨時安裝的軟體應僅放置於會話暫存資料夾內，並將其快取位置也指向該處（請參閱 references/verification.md）。

7. 進行螢幕驗證

執行 scripts/test_guide.py。該腳本會以 dist/ 為根目錄，在 127.0.0.1 的指定埠號提供服務。

python <此技能>/scripts/test_guide.py --book <書籍> --port 8770 --search "<正文中出現的詞語>"

• 需要 Python 的 Playwright 與 Chromium。若未安裝，請詢問使用者是否允許安裝（合計數百 MB）。若無法安裝，則跳過此項驗證，並於報告中說明。
• 持續修正直到所有測試通過。通過後，請以肉眼檢視 <書籍>/shots/ 中的螢幕截圖（封面、使用說明、各章節、速查表、深色模式、手機版），確認無內容溢出、顏色不易閱讀或版面破損等問題。
• 確認正文中的外部連結可正常開啟，且 Playground 的連結能正確開啟（請實際開啟並執行其中一項進行驗證）。

8. 交付與清理

1. 若已決定建立共享連結，請在正文確定後再建立（使用 --share），並確認所有連結都指向正確的程式碼。
2. 將 dist/full.html 複製到使用者桌面（Windows：C:\Users\<使用者>\Desktop，macOS：~/Desktop），檔案名稱為 <名稱>入門指南.html。若已有相同名稱的檔案，請先詢問使用者是否覆蓋。
3. 若形式包含共享頁面，且環境支援 Artifact 工具，請先呼叫 quickstart，再發布 dist/artifact.html（圖示設為 book，描述以中文撰寫一句話）。告知使用者該頁面為非公開，共享需由使用者透過 Share 選單進行。若不支援，則跳過此步驟。
4. 刪除臨時安裝的軟體、快取資料與螢幕截圖。若作業過程中於共用位置（如 npm 快取）寫入了資料，請確認僅清除自己所產生的部分。
5. 以中文提交報告：說明存放位置、共享頁面網址（若有建立）、內容摘要（章節大綱重點）、驗證事項（數量）、注意事項（無法驗證的環境、Playground 限制等）。

參考資料

檔案	閱讀時機
references/questions.md	輸入確認方式與選擇項目提問的用語模板
references/book-spec.md	spec.json 與 book.json 的撰寫方式
references/writing-guide.md	章節大綱、文章寫法、正確性規範
references/components.md	稿件的 HTML 元件
references/code-blocks.md	程式碼範例寫法、屬性、驗證腳本結果格式
references/verification.md	各種語言的驗證方式、臨時安裝的步驟與清理
references/past-books.md	先前四本書的章節大綱、顏色、驗證方式與注意事項
references/examples/README.md	稿件範例（從四本書中擷取）的選取方式。請於開始撰寫稿件前先閱讀