nix-flake-update-check

nix flake 软件包更新检查（通用）

检查 nix flake 仓库中各软件包的上游发布更新并执行版本升级。

本技能只包含与仓库无关的通用方法。仓库特有的环节（文档同步、维护日志、 内置插件清单等）由仓库适配层提供——见文末「仓库适配层」。

本技能的文件构成

主流程在本文档；两份配套参考按需查阅，不必通读：

文件	内容	何时读
SKILL.md（本文）	交互式澄清 + 第 0~9 步主流程 + 适配层契约	始终
builders.md	按 builder 的 hash 更新流程、flake.lock 处置	第 4 步
traps.md	nixpkgs 漂移陷阱、fail-closed 校验、外链审计、Actions 更新、补丁内版本	第 2 步末尾（Actions）与第 7 步自检命中时

交互式澄清：一次流程内解决所有待定项

在开始前先判断所运行的智能体是否支持交互式提问（如 DSH 提供 ask_user_question，可一次提出多个问题并等待用户选择）。支持就积极使用 ——凡是不确定、有多种合理做法、或必须由用户拍板的事项，当场问，不要 先按自己的猜测执行完、再让用户在下一条消息里纠正。

为什么这条是强要求：软件更新是多决策点流程（升级策略、跨大版本取舍、 依赖冲突的解法、通道选择、是否部署）。若每个决策点都退化成「猜一次 → 被纠正 → 重来」，一次更新会膨胀成多轮往返，且每次重来都要重跑构建——而构建是 本流程最贵的环节（Rust/python 包动辄数十分钟）。把决策点前置到开始之前， 整个流程才可能一次跑完。

必须提问的情形

情形	为什么必须问
跨大版本升级（3.x → 4.x）	可能含 breaking change、新的硬性要求，或需要用户接受行为变化
依赖冲突有两种以上合理解法	如「抬依赖版本」vs「跳过该包」vs「打补丁放宽校验」——代价与风险差别很大，且有的会破坏上游安全契约
需要新增 overlay / 补丁 / 额外 vendored 包	增加维护面，属结构性改动
构建时长或体积显著增加	用户可能宁愿暂缓
通道选择（stable / next / alpha）	取决于用户想跟哪条线，技能无法推断
是否部署到运行中的系统	影响生产环境
发现的信息与文档记载冲突	可能是文档过时，也可能是现状异常，需用户判断

提问的写法

• 一次问全：把本轮所有待定项合并成一批提问，不要挤牙膏式地一问一等。
• 给出可选项与代价：每个选项写清影响（尤其「破坏上游契约」这类后果）。
• 给出推荐项并说明理由：把推荐项放第一位，标注「推荐」。
• 能自己查证的不要问：先查 release notes / 上游源码 / 构建报错， 把问题收敛到真正需要人决策的那几个。

不支持交互式提问时（如纯命令行 agent）：把上述待定项汇总成一份清单 一次性输出，并说明每项的影响与推荐做法，然后停下等待——同样避免 「猜完再被纠正」的多轮往返。宁可一次问完，不要边做边猜。

与「先做完再汇报」的取舍

默认行为是自主推进，本技能是例外：因为更新流程的返工成本极高（重建代价）， 提问的成本远低于猜测的错误成本。但只问真正需要决策的——机械步骤 （取 hash、改版本号、同步文档、记日志）自行完成，不要拿流程细节去打扰用户。

适用前提

• 仓库是 nix flake（根目录存在 flake.nix）。
• 包定义以独立 .nix 文件形式存在，通常位于 packages/（或其他目录）， 由 flake.nix 经 callPackage 引用。
• 若仓库布局不同（如所有包写在单个 flake.nix、或位于 nix/ 等目录）， 以第 2 步的自动发现结果为准，不必强行套用目录名。

第 0 步：同步远端，并确认活跃 issue / PR

在做任何版本比对之前，先把本地与远端对齐，再读一遍仓库上已经被人报出来的 东西——未关闭的 issue 与 PR。

git fetch origin                      # 并行会话 / 压缩检查点可能让本地副本落后于 origin
git status -sb | head -1              # 当前分支，领先/落后多少
git log --oneline @{u}..HEAD          # 本地尚未推送的提交——它们同样是「在途工作」

# 仓库坐标从 remote 推导，不要硬编码；无 remote 时显式指定 REPO="<owner>/<repo>"
REPO=$(gh repo view --json nameWithOwner --jq .nameWithOwner)

gh issue list --repo "$REPO" --state open --limit 100 \
  --json number,title,author,createdAt,labels
gh pr list --repo "$REPO" --state open --limit 100 \
  --json number,title,author,createdAt,headRefName,isDraft