此機器執行 NixOS；所有系統配置位於 anixpkgs 儲存庫，複製在 ~/sources/anixpkgs（正式路徑）與可能另一個路徑（例如 /data/andrew/dev/claude/sources/anixpkgs）。目前的樹透過其 flake 配置部署；anix-upgrade 為較舊的樹保留基於頻道的路徑。
工作流程
- 編輯
pkgs/下相關的 Nix 模組或 Python/shell 腳本。 - 暫存新檔案 —
git-cc（由anix-upgrade使用）只會複製已追蹤的檔案（git ls-files）。請先執行git add加入新檔案，否則它們會在建置時被靜默忽略。 - 部署 透過本機
anix-upgrade-uiAPI（建議）進行，串流執行直到完成：upgrade_host="$(hostname).local" curl -si "http://${upgrade_host}/anix-upgrade/api/v1/run" -X POST \ -H 'Content-Type: application/json' \ -d '{"source": "/path/to/anixpkgs", "local": true}' # 202 → {"run_id": "<uuid>", "started": true}; 409 → 已在執行中 curl -N "http://${upgrade_host}/anix-upgrade/api/v1/stream/<run_id>" # 結束時顯示 [UPGRADE SUCCESSFUL] 或 [UPGRADE FAILED (exit N)]，然後 [DONE].local主機名稱，而非localhost：nginx 僅在機器特定的虛擬主機上暴露此路由。 CLI 備用方案（僅在 API 無法連線時使用）：anix-upgrade --local -s /path/to/anixpkgs。 - 測試 在此機器上測試結果後再提交。
"local": true 是必要的，當變更影響服務套件或 NixOS 模組時 — 沒有此設定 anix-upgrade 會讓 dependencies.nix 維持 local-build = false，因此模組的 cfg.package 預設會解析為已發佈標籤的二進位檔，變更會靜默地不生效。
重要陷阱
- NixOS 模組必須在正確位置匯入（例如
pc-base.nix的匯入清單）— 僅新增檔案是不夠的。 - 新選項必須在
pkgs/nixos/components/opts.nix中宣告，並在pc-base.nix中賦值，才能在base-dev-pkgs.nix等元件中使用。 - MCP 伺服器透過
claude mcp add -s user ...為每個使用者註冊；claude-setup腳本（位於base-dev-pkgs.nix）處理此操作，且在新增伺服器後必須重新執行。
部署到其他機器 / API 參考
每個執行 anix-upgrade-ui 的機器都執行相同的 API：http://<hostname>.local/anix-upgrade/api/v1/（無需認證）。run 請求主體欄位（均為選填）：version、commit、branch、source（本機路徑）、local、boot — 語義與 anix-upgrade 旗標相同。使用 -si 讓回應標頭顯示（某些代理會移除 -s 的 JSON 回應主體）。
對於遠端機器，請先推送並傳遞 commit（完整雜湊），而非 branch — 分支 tarball 經 CDN 快取，即使使用 --tarball-ttl 0 也可能延遲數分鐘；使用 commit 雜湊則會以內容定址的 fetchGit 繞過 CDN：
curl -si -X POST http://<hostname>.local/anix-upgrade/api/v1/run \
-H 'Content-Type: application/json' \
-d "{\"commit\": \"$(git rev-parse HEAD)\", \"local\": true}"
監控執行（run_id 在新的執行開始後會回傳 404，因此請先擷取日誌再重新觸發）：
curl -s .../api/v1/status/<run_id> | jq . # 狀態：running|success|failed
curl -N .../api/v1/stream/<run_id> # SSE：重播最後 512 KB，然後即時串流
curl -o upgrade.log .../api/v1/log/<run_id> # 完整日誌
執行記錄會出現在瀏覽器 UI（http://<hostname>.local/anix-upgrade/），並帶有 via API 徽章；每台機器一次只能執行一個工作（API 與手動 UI 會互相封鎖）。