Shangshui0302/some-NixOS-skills

Nix 包开发

铁律：在记录目标 nixpkgs 接口和上游源代码/发布证据之前，不得更改任何包表达式；没有该证据的构建不是可重现的打包结果。

出现以下任何红色标志时，请返回证据步骤：

• 仅根据单个标记文件或内存选择构建器。
• 浮动通道、注册表结果或“最新”URL 是唯一的源代码证据。
• 哈希、包装器、桌面条目或运行时依赖项是猜测的。
• nix develop 成功，但未构建派生、输出布局或可执行文件。
• 将成功的 dry-build 报告为已部署或实时运行时测试。

范围边界

本技能负责包表达式、其构建输入、输出契约以及面向包的 flake 或 overlay 集成。将 NixOS/Home Manager 模块视为消费者：检查它们的包接口并在范围内时对它们进行 dry-build，但将系统配置和激活留给 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 时运行系统 dry-build。
  • 保持构建、冒烟、dry-build 以及激活后/实时状态分离。
• 步骤 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 或其他消费者的 dry-build。

升级和新鲜度维护

对于重复更新，加载 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 检查、构建、输出/冒烟、dry-build 和实时状态分别列出。
5. 下一步操作 — 仍需要的精确手动命令或用户决策。

当缺少必要检查时，切勿声称包“已完成”；而是标记阻塞项和最小的下一步实验。