本机器运行 NixOS；所有系统配置均位于 anixpkgs 仓库中，该仓库克隆在 ~/sources/anixpkgs（规范路径）以及其他可能路径（例如 /data/andrew/dev/claude/sources/anixpkgs）。当前树通过其 flake 配置部署；anix-upgrade 为旧树保留基于 channel 的路径。
工作流
- 编辑
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。 - 测试 结果在本机器上提交之前进行。
当变更涉及服务包或 NixOS 模块时，"local": true 是必须的 — 没有此选项，anix-upgrade 会将 dependencies.nix 中的 local-build = false 保留，因此模块的 cfg.package 默认解析为已发布标签的二进制文件，变更静默不生效。
重要陷阱
- NixOS 模块必须在正确位置导入（例如
pc-base.nix的 imports 列表）— 仅仅添加文件是不够的。 - 新选项必须在
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 参考
同一 API 运行在每台托管 anix-upgrade-ui 的机器上：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 也可能在几分钟内是过时的；提交哈希使用内容寻址的 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 . # status: 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 互斥）。