套用數位廳設計系統
從已核准的官方 Markdown 快照中，只選取請託所需的依據來套用。
將一般作業與官方更新確認分開，未經使用者核准不得啟用更新候選。
以下 <skill-root> 會替換為此 SKILL.md 所在目錄的絕對路徑。
以下 <python> 會替換為可執行 Python 3.10 以上版本的指令。
在 macOS 與 Linux 上通常使用 python3，在 Windows 上通常使用 py -3。
資訊邊界
references/source-manifest.json中active_snapshot.path所指向的，即為一般作業使用的有效快照。- 有效快照中的
source-index.json、references/task-index.md與references/foundation-map.md為衍生資料。 其官方意涵請以有效快照內的對應 Markdown 為準。 - 官方 Markdown 是為 AI 參考而重新建構的內容，並非官方網站的完整替代品。 若本地資料缺乏所需敘述，應回報為未確認事項。
- 此技能為非官方性質，不代表數位廳的提供、核准、合作或推薦。
- 現有專案的當前值應從 CSS 變數、主題設定、通用樣式與通用元件中確認， 不要複製到技能內部。
- 建立、修改、審查為操作權限的分類。 新建、既有改修、個別元件為資料選擇的分類，兩者不可混淆。
啟動時的更新期限判定
首先執行下列指令。 此指令僅讀取本地檔案，不會連接網路。
<python> <skill-root>/scripts/manage_upstream.py status
將輸出中的 status 記為 status_at_start，並在該次請託期間保留。
fresh：不提示更新，繼續一般作業。due、never_checked、unknown：不中斷一般作業，但於結束時重新確認狀態。- 若使用者一開始就明確表示「請確認最新版」等：將此明確要求視為同意外部確認，並進入維護程序。
期限係以 last_successful_check_at 起算 30 日來判斷。
提案日期、失敗日期、或由此衍生的下次確認日期，均不得作為期限起點。
一般作業
- 將請託分類為建立、修改或審查，並確定允許的操作範圍。
- 確認目標的技術架構、既有樣式、品牌限制與畫面結構。
- 依下列優先順序決定資料選擇路徑。
- 若目標僅限於單一 UI 元件及其狀態，則視為個別元件。
- 若已有通用樣式存在，則視為既有改修。
- 其他情況則視為新建。
- 從
references/task-index.md中選擇目標文件。 若無對應項目，則以下列指令搜尋有效快照。
<python> <skill-root>/scripts/search_guidance.py \
--query '<將搜尋詞以空白分隔>' \
--manifest-file <skill-root>/references/source-manifest.json
- 根據資料選擇路徑使用
references/foundation-map.md。- 新建：將 8 個分類標示為採用、不適用或保留，並閱讀決定值的分類之官方 Markdown。
- 既有改修：先調查既有值，僅閱讀受影響的分類，並區分為維持、遷移或刻意偏離。
- 個別元件：僅閱讀既有的通用基準、目標元件及受影響的基本設計。 不要在元件內部重新決定通用值。
- 區分官方提供的選項、預設值、範例、原則、需求與固定值，並建立採用值與其依據的對應關係。
- 在既有的技術架構下實作。 不要將官方範例一律當作固定值套用，也不要將官方需求軟化為外觀偏好。
- 根據目標，確認多種畫面寬度、鍵盤操作、焦點、狀態變化、縮放與回流。
- 審查請託時不修改檔案，僅回傳附有依據的指摘事項。
一般作業完成報告
簡潔報告以下事項：
- 參考版本：
source-manifest.json中的快照 ID、數位廳設計系統版本、Markdown 發布日期。 - 確認範圍：所閱讀的官方文件與執行的確認項目。
- 未確認事項：實際裝置、輔助技術、外部現行頁面等未確認的範圍。
- 偏離事項：因專案特定理由而變更官方範例或建議的內容。
僅在啟動狀態為 due、never_checked 或 unknown 時，才在報告前重新執行 status。
若因其他處理而變成 fresh，則在最終報告末尾僅提案一次更新確認。
距離上次官方更新確認已超過 30 天。本次作業已使用已核准的現行版本完成。是否也要進行更新確認？
若狀態為 never_checked 或 unknown，則不確定經過天數，應說明原因。
僅提案不會進行外部通訊或狀態更新。
即使使用者拒絕，也不會儲存拒絕日期，因此下次仍會持續提案直到確認成功為止。
確認官方更新
僅在使用者同意時，才執行下列指令。
--network-approved 必須在確認使用者同意後才附加。
若未滿 30 天但明確要求確認最新版，則加入 --force。
取得後端採用預設的 auto。
auto 若找到 ax，則將官方頁面取得、連結提取與 ZIP 儲存交由 ax 處理；若找不到，則使用 Python 標準函式庫。
ax 為建議選項但非必要，不應將安裝 ax 作為更新確認的前提。
ax 路徑會驗證重新導向後的最終 URL，但無法在通訊前驗證中途的轉送目標。
若需對轉送目標也預先設限，請使用 --fetch-backend stdlib。
一旦選擇的後端失敗，不會隱含地切換至其他後端。
取得後的 URL、容量、ZIP 格式驗證、雜湊計算、差異建立與狀態儲存均由 Python 處理。
僅在為進行動作確認等目的而需固定方式時，才附加 --fetch-backend ax 或 --fetch-backend stdlib。
<python> <skill-root>/scripts/manage_upstream.py check \
--network-approved
unchanged：更新確認成功日期，並報告取得後端與無變更。candidate_created或candidate_exists：報告取得後端、候選 ID、取得來源、雜湊值、新增、修改與刪除的數量。skipped_fresh：因未滿 30 天而省略外部確認，並報告此情況。- 失敗：不修改
last_successful_check_at與有效快照，並報告失敗的取得來源與原因。
同意外部確認不代表同意採用候選。 即使找到候選，只要官方來源確認與候選儲存已完成，確認成功日期仍會更新。
手動取得 ZIP
僅在自動取得最終失敗，且 check 能識別官方 ZIP 的 URL 並引導手動取得時，才將此程序作為最後手段提出。
若在識別 URL 前就已失敗，則不應從 URL 或檔名推測取得來源，僅報告失敗。
向使用者展示下列內容：
ZIP 自動取得失敗。您可以從下列官方 URL 手動取得。
<官方 ZIP URL>
請將 ZIP 儲存於任意資料夾。儲存後，請提供包含檔名的絕對路徑。
收到 ZIP 後，將在不連接網路的情況下進行驗證，並儲存為更新候選。切換為有效版本則需另行確認。
收到使用者的絕對路徑後，執行下列指令。 若僅得知相對路徑，請先確認絕對路徑再執行。
<python> <skill-root>/scripts/manage_upstream.py import-archive \
--archive-file '<ZIP 的絕對路徑>'
import-archive 會將本地 ZIP 關聯至失敗時記錄的官方 URL，在不連接網路的情況下進行容量、ZIP 格式、內部路徑、Markdown 集合與雜湊值的驗證，並建立候選。
不會修改或刪除原始 ZIP。
本地匯入不視為外部確認成功，因此不會更新 last_successful_check_at 與已確認的合約版本。
即使結果為 candidate_created 或 candidate_exists，也不會自動晉升，而是進入「更新候選評估與晉升」。
若自官方 URL 識別後已超過 30 天，或更新合約已變更，則不繞過匯入程序，而要求新的更新確認同意。
即使手動取得或本地匯入失敗，也不會修改 last_successful_check_at 與有效快照。
更新候選評估與晉升
- 讀取候選內的
candidate-manifest.json與diff-summary.json。 - 使用
verify_snapshot.py驗證候選。
候選的預設儲存位置為使用者專用狀態目錄下的 candidates。
<python> <skill-root>/scripts/verify_snapshot.py \
--snapshot-dir <state-dir>/candidates/<候選 ID>/snapshot \
--index-file <state-dir>/candidates/<候選 ID>/source-index.json
- 閱讀新增、修改與刪除的官方文件，確認其對
task-index.md與foundation-map.md的影響。 - 使用舊版與候選版分別測試代表性的建立、修改與審查請託。
- 向使用者展示候選 ID、意義變更、衍生資料的修改與驗證結果，並明確確認是否採用。
- 僅在使用者指定候選 ID 並核准後，才執行下列指令。
<python> <skill-root>/scripts/manage_upstream.py promote \
--candidate-id '<候選 ID>' \
--human-approved
晉升後不刪除前一個快照。
晉升操作不會修改 last_successful_check_at。
判斷規則
- 不以
MANIFEST.md作為檔案清單的正本， 應掃描所有 Markdown。 - 文件 ID 使用正規化的
source_url。slug在本文與更新紀錄中會重複，故不作為單獨 ID。 - 不要將找不到的元件、代碼（token）或類別名稱當作官方規格來建立。
- 當既有值與官方需求衝突時，不要默默維持或取代，應顯示影響範圍與修改範圍。
- 僅以畫面確認作為依據，不得宣稱完全符合數位廳設計系統或 WCAG。
- 在公開物中標示出處時，請閱讀有效快照中的
introduction/notices/index.md。 - 更新狀態與候選應儲存於使用者專用的本地區域，不要混入技能本體的發布檔案中。
僅在需要變更儲存位置時，使用環境變數
DADS_SKILL_STATE_DIR。