建立並發佈 Coursmith 課程

您將課程撰寫為一個包含 course.json 和 assets/ 目錄的資料夾，並使用 coursmith CLI 進行檢查與提交。Coursmith 入口網站上的審閱代理會核准、要求修訂或拒絕該課程。當課程被核准，或者您已向使用者說明審閱結果時，您的工作即告完成。

請以 npx --yes coursmith@latest <command> --json 執行 CLI。公開的 npm 套件包含此 CLI 和此技能；無需 GitHub 存取權或全域安裝。如果缺少 npx，請要求使用者安裝 Node.js 20 或更新版本，並依照 /install 的指南操作。使用 --json 參數時，每個命令會輸出一個 JSON 文件；請直接讀取該文件，而非自行猜測。

請參閱此技能資料夾中的參考檔案（當您執行到對應步驟時請閱讀它們）：

檔案	用途
`references/course.schema.json`	`course.json` 的確切結構。未知的鍵會被拒絕。
`references/block-catalog.md`	每個內容區塊和視覺元素，附有有效的 JSON 範例和規則。
`references/animation-presets.md`	7 種動畫預設及其使用時機。
`references/writing-guide.md`	如何撰寫能通過審閱的步驟、詞彙表和測驗。
`references/content-policy.md`	哪些內容不被允許，以及如何處理敏感主題。
`examples/sample-course/`	一個通過驗證的完整課程。請模仿其結構。

1. 登入

執行 npx --yes coursmith@latest whoami --json。如果輸出 username，請繼續執行步驟 2。
否則，執行 npx --yes coursmith@latest login --no-wait --json。向使用者顯示 verificationUri 和 userCode，並請他們開啟連結、核對代碼，然後點擊核准。
當使用者確認後，執行 npx --yes coursmith@latest login --resume --json，並檢查其是否輸出 logged_in。

2. 與使用者協商課程內容

在一則訊息中，詢問使用者尚未提供的任何資訊：

主題，以及（若有幫助的話）切入角度或目標受眾。
課程的語言（任何語言；您需要其 BCP-47 代碼，例如 it、en、pt-BR）。
難度：beginner、intermediate 或 advanced。
可選：期望長度（預設約 30 分鐘）、先備知識、應包含或避免的事項。

請根據 references/content-policy.md 檢查主題。如果不被允許，請告知使用者並停止。如果是敏感主題（健康、法律、金融、政治、宗教……），請規劃中立的表述方式及免責聲明。

3. 提出大綱並獲得核准

向使用者展示：

標題、一行副標題、2–6 個學習目標；
3–6 個章節，每個章節包含一行摘要和 2–5 個步驟標題；
每個步驟規劃的視覺類型（圖表、圖示、動畫預設、圖片或無）；
規劃的測驗題數（至少 10 題，涵蓋每個章節）。

根據使用者意見進行修訂，直到他們同意。在此之前請勿撰寫 course.json。

4. 撰寫課程

建立一個以課程名稱命名的新資料夾（使用 kebab-case），內含 course.json 和 assets/。請嚴格遵循 references/course.schema.json，並模仿 examples/sample-course/course.json 的結構。

驗證器強制執行的規則（詳見 references/block-catalog.md）：

schemaVersion 為 "1.0"。請勿撰寫 courseId：CLI 會自行管理。
所有 ID 皆由小寫字母、數字和連字號組成，且在整個課程中必須唯一（章節、步驟、素材、測驗題目）。
每個步驟都有 title 和至少一個區塊；大多數步驟也應有 visual。
詞彙表：每個章節都有一個 glossary，用於定義該章節引入的每個概念以及所使用的每個技術或領域術語。在文字中，將每個術語標記為 [[term]]，或當顯示文字不同時標記為 [[term|text shown]]（使用 aliases 處理複數和詞形變化）。標記的術語必須在同一個章節或更早的章節中定義。定義應自成一體，並使用課程語言撰寫。
視覺元素：圖表是內含 data.values（無 URL）的 Vega-Lite 規格；圖示是沒有 click 或 %%{init}%% 的 Mermaid；動畫使用 7 種預設之一；圖片透過 ID 引用素材。
Markdown：無原始 HTML，無 Markdown 圖片（請使用圖片區塊），連結必須為 https://。
最終測驗：至少 10 題；每個章節至少被一題測驗（sectionRef）涵蓋；每題都有一個 explanation。類型：single、multiple、true_false、ordering（排序題的項目以正確順序列出；入口網站會將其打亂）。
可選的 check 問題可置於步驟結尾，為學習者提供快速回饋，且不計分。

請逐章節撰寫，並確保語言、難度和術語在整個課程中保持一致（參見 references/writing-guide.md）。

5. 建立素材

封面圖片是必需的（meta.coverImage），理想尺寸為 1200×630。
如果您有圖片生成工具，請產出 PNG、JPEG 或 WebP 檔案。否則，請手寫乾淨的 SVG：簡單的形狀、清晰的色板、設定 viewBox、無腳本、無外部連結或字型、無內嵌圖片。
若是 highlight-svg 動畫，請為要凸顯的元素加上 id 屬性。
將每個檔案直接放入 assets/ 目錄，並在 assets[] 中宣告，包含 kind（image 或 svg）、file（assets/<name>）以及有意義的 alt 文字。對於 AI 生成的圖片，請填寫 generatedBy。
每個檔案必須小於 3 MB；整個套件小於 25 MB。

6. 持續驗證直到無誤

執行 npx --yes coursemith@latest validate <folder> --json。它會輸出 { "ok": ..., "issues": [...] }；每個問題都有 severity、code、path（例如 sections[1].steps[0].blocks[2]）和 message。

修復所有 error，然後再次執行。重複直到 ok 為 true。如果修復成本不高（例如 glossary.unreferenced：在使用該術語的地方用 [[...]] 標記它），也請修復警告。

7. 提交並依審閱結果處理

執行 npx --yes coursemith@latest submit <folder> --json。它會上傳課程並輸出 status: "in_review" 以及一個 submissionId。CLI 會在該資料夾中寫入 .coursmith.json；請保留該檔案，因為它會將後續提交連結到同一個課程。
執行 npx --yes coursemith@latest status --dir <folder> --wait --json（它會等待最多 10 分鐘；如果狀態仍是 in_review，請再次執行）。
根據 status 採取行動：
- approved：將 courseUrl 提供給使用者。若有任何在 review.issues 中的可選建議，請一併提及。
- needs_revision：針對 review.issues 中的每個問題，開啟 path 指定的元素，套用 suggestion（或修復 message 所述的問題），然後再次驗證並提交。告知使用者您做了哪些變更。severity: "warning" 的問題為可選。
- rejected：向使用者說明 review.summary。請勿重新提交相同的內容。

如果 submit 回報 review_in_progress，請先用 status --wait 等待目前的審閱完成。

更新已發佈的課程

編輯同一個資料夾（保留 .coursmith.json）並再次提交。新版本會進入審閱流程，同時當前版本保持線上；請保持步驟 ID 穩定，以便學習者維持他們的學習進度。

疑難排解

CLI 輸出	處理方式
`not_logged_in` / 退出代碼 3	回到步驟 1。
`client_outdated`	使用 `npx --yes coursemith@latest` 重試，讓 npm 取得最新 CLI。
`submit` 回報的 `validation_failed`	執行 `validate` 並修復其列出的問題。
`rate_limited`	使用者已達到每日提交上限；請隔天再試。
`assets.content_type` / `assets.invalid`	檔案內容與其副檔名不相符，或檔案已損毀。請重新匯出。
`animation.unknown_element`	SVG 缺少具有該 `id` 的元素（ID 會被保留，腳本和外部連結會被移除）。

coursmith-course