Shangshui0302/some-NixOS-skills

Nix 套件開發

鐵律：在目標 Nixpkgs 介面與上游原始碼/發行版證據被記錄之前，切勿更改套件表達式；未附該證據的建置不是可重現的封裝結果。

出現以下任何紅旗時，返回證據步驟：

• 建置器是僅依據單一標記檔案或記憶體選取的。
• 浮動頻道、註冊表結果或「最新」URL 是唯一的來源證據。
• 雜湊值、包裝器、桌面項目或執行時期依賴項是猜測的。
• nix develop 成功，但衍生項、輸出佈局或可執行檔未實際建置。
• 成功的乾建置被報告為已部署或實際運行測試。

範圍邊界

此技能擁有套件表達式、其建置輸入、輸出合約以及面向套件的 flake 或 overlay 整合。將 NixOS/Home Manager 模組視為消費者：檢查其套件介面並在範圍內對其進行乾建置，但將系統配置和啟用留給 nixos-ecosystem。

當請求針對上游 NixOS/nixpkgs 維護流程（例如分類更新或損壞、接手套件、檢查受影響的依賴項或準備 nixpkgs PR）時，請使用 nixpkgs-maintainer。如果兩者都涉及，此技能提供衍生證據，而維護技能負責上游工作流程。

進度檢查清單

將此檢查清單複製到工作備註中，並在任務進展時標記：

• 步驟 0：載入儲存庫政策並定義範圍 ⚠️ 必填
  • 尋找 AGENTS.md、貢獻規則、髒檔案、套件消費者以及請求的可觀察行為。
  • 將任務分類為新增、升級、修復或審查。
  • 識別表達式存在於套件儲存庫、獨立檔案、flake、overlay 或 nixpkgs 樹中。
• 步驟 1：通過新鮮度閘門 ⛔ 阻塞
  • 從 flake.lock、固定的套件儲存庫輸入或 nixpkgs 檢出記錄目標的 nixpkgs 修訂版；當不存在時說明備用方案。
  • 檢查鎖定的建置器/輔助介面，並與當前的官方文件進行比較。
  • 報告偏移和遷移影響；切勿在較舊的鎖定上靜默應用較新的 API。
• 步驟 2：收集來源和套件證據 ⚠️ 必填
  • 在目標樹、相關的 nixpkgs 輸入、overlay 和現有輔助程式中搜尋現有套件或實作。
  • 驗證上游標籤/提交、建置命令、CI、授權、平台、工件、可執行檔名稱和安裝佈局。
  • 選擇最狹窄的路徑：原始碼、預建 ELF、AppImage、Electron/ASAR、資料、字型/主題或外掛。
• 步驟 3：呈現最小計畫 ⚠️ 非平凡編輯必填
  • 說明檔案、依賴項、風險、驗證命令以及將保持未驗證的內容。
  • 在進行破壞性編輯、安裝、系統啟用、提交、推送或建立 PR 之前先詢問。
• 步驟 4：實作最小的衍生項
  • 固定 pname、version、來源/修訂版和 SRI 雜湊值；在 URL 和檔案名稱中一致地使用 pname/version。
  • 使用最狹窄的 nixpkgs 建置器和預設階段；自訂階段必須執行其匹配的鉤子。
  • 分離建置工具、連結/執行時期函式庫、測試工具和包裝器提供的命令。
  • 將 GUI 整合完成為一個單元：包裝器、桌面項目、圖示、Exec 和執行時期標誌。
  • 僅當在範圍內時，保留或暴露目標的現有套件介面（flake 輸出、overlay 或套件屬性）。
• 步驟 5：分層驗證 ⚠️ 必填
  • 解析、評估/檢查、建置、檢查儲存區輸出，並執行一次安全冒煙測試。
  • 僅當套件整合到 NixOS/Home Manager 時，執行系統乾建置。
  • 分別記錄建置、冒煙、乾建置和啟用後/運行狀態。
• 步驟 6：報告與維護
  • 報告證據、更改的檔案、雜湊值、檢查項、阻塞項以及確切的手動下一步。
  • 對於升級，重新檢查變更日誌、鎖定檔案、授權、工件佈局和所有雜湊值。
  • 僅在更新路徑證明穩定且確定性之後，才新增更新腳本。

新鮮度閘門

在選取建置器或編寫新雜湊值之前，載入 references/freshness-and-evidence.md。使用 gh 進行 GitHub 調查。優先使用鎖定的 nixpkgs 來源獲取 API 事實，並使用當前的官方 Nixpkgs/nix.dev 文件來檢測流程變更。當它們不一致時，暫停並解釋該變更是否與鎖定相容、是否需要鎖定更新，或者應保持為記錄在案的例外。

建置器和實作路由

在證據步驟之後，僅載入 references/builder-routing.md 的相關部分。不要新增廣泛的依賴項集來隱藏未知的階段失敗。當維護可行時，優先使用原始碼建置；僅當上游原始碼路由不可用或實質上可靠性較低時，才使用發行版二進位或 AppImage。

對於自訂的 buildPhase、checkPhase 或 installPhase，保留相應的 runHook preX 和 runHook postX。對於預建的原生程式碼，記錄來源並檢查架構、直譯器、NEEDED 函式庫和捆綁的組件授權。

驗證

載入 references/validation.md 以獲取套件類型矩陣和輸出檢查。根據目標的套件介面調整以下檢查：

nix-instantiate --parse path/to/package.nix
nix flake check path:. --no-build       # 當目標暴露一個 flake 時
nix build path:.#pname -L --no-link --print-out-paths  # 使用目標輸出名稱
git diff --check

如果套件已接入 NixOS/Home Manager 設定，也請執行：

nixos-rebuild dry-build --flake path:.

使用 scripts/validate-skill.py 檢查此技能儲存庫本身。這是一個確定性 lint，不是取代建置目標套件。

當使用者要求「執行驗證」但未指定消費者時，預設為套件評估、建置、輸出檢查和安全冒煙測試。僅當該消費者在範圍內時，才新增 NixOS/Home Manager 或其他消費者的乾建置。

升級與新鮮度維護

對於重複更新，載入 references/update-policy.md。固定來源和文件輸入，使更新檢查明確，並預設保持自動化工作唯讀。自動化作業可以在檢查通過後開啟可審查的更新變更；它不得靜默重寫技能、切換系統、提交或推送。

四種具體請求形狀

當請求不明確時，載入 references/examples.md。支援的形狀為：將套件新增到套件儲存庫、獨立表達式、flake 或 overlay；升級現有衍生項並重新整理來源/依賴項雜湊值；修復預建/AppImage、Electron、字型/主題或外掛套件；以及透過現有的 flake 或 overlay 為消費者整合套件。

反模式

• 不要使用 nix develop 成功作為 nix build 有效的證明。
• 不要僅從 Cargo.toml、package.json 或一個猜測的依賴項來選取建置器。
• 不要在沙箱建置期間線上獲取依賴項（cargo fetch、npm install、pip install 等）。
• 不要使用浮動來源 URL、可變分支、舊式雜湊值或在表達式中重複的版本字面量。
• 不要使用 autoPatchelfIgnoreMissingDeps、預設的 FHS 包裝器或過大的 buildInputs 列表來隱藏缺少的函式庫。
• 不要僅因衍生項已建置，就聲稱桌面、IPC、播放、Wayland 或合成器行為已測試。
• 不要將套件表達式檢查視為 nixpkgs 整合或 PR 審查；使用 nixpkgs-maintainer 處理該上游工作流程。
• 未經明確授權，不要執行 nixos-rebuild switch、提交、推送、刪除檔案或建立 PR。

交付格式

回傳一份精簡的證據報告：

1. 範圍與路由 — 目標儲存庫/公開介面、任務類型、套件類型以及選擇此建置器的原因。
2. 證據 — 鎖定的 nixpkgs 修訂版/API、上游修訂版/工件/授權以及相關雜湊值。
3. 變更 — 套件表達式、flake 或 overlay 介面、消費者以及文件。
4. 驗證 — 分別列出解析、flake 檢查、建置、輸出/冒煙、乾建置和運行狀態。
5. 下一步行動 — 確切需要的手動命令或使用者決定。

當必要的檢查缺失時，切勿稱套件「完成」；改為標記阻塞項和最小的下一步實驗。