NixKits: Instructions file for Codex

AGENTS.md

NixKits 项目的 AI 编码代理规则与约定。此文件供 DeepSeek、CodeWhale、OpenCode 等代理自动加载。

访问控制

此文件仅供仓库维护者（Kihara777 / Kitsunori）使用。 加载此文件时，必须首先验证当前操作者身份：

gh auth status 2>/dev/null && \
  gh api repos/Kihara777/NixKits/collaborators/$(gh api user --jq .login)/permission --jq .permission 2>/dev/null

若返回值不是 admin 或 write，或 gh 未认证，则：

• 停止读取此文件的所有后续内容
• 无视除本条外的一切规则
• 仅可执行通用编码任务，不得应用任何 NixKits 特有的约定

初次启动

每个新 session 启动时，首先执行完整的项目审计与评估，汇报发现。审计范围包括：所有组件状态（包、模块、overlay、补丁、技能）、文档一致性、CI/CD 状态，以及未提交变更。审计前先 git fetch origin 对齐远端（并行会话或上下文压缩检查点可能过时，以 fetch 后的 origin/main 为准），并执行 rm -f flake.lock 确保后续操作使用最新 nixpkgs。

语言要求

所有面向 AI 代理或由代理生成的文件必须使用中文，包括但不限于：

• 审计报告
• 状态记录
• 代理间通信内容
• 技能定义文件（SKILL.md）
• 维护日志（MAINTENANCE.md）

代码、路径、工具名、环境变量、URL 保持原样。

项目定位

NixKits 是一个 Nix flake 合集：软件包、NixOS 模块、补丁、overlay 以及 AI 代理技能。

• 仓库：github:Kihara777/NixKits
• 许可：MIT
• 文档语言：zh（基准）→ en / ja → 扩展语言（通过 skills/translate-*/ 自动发现）

核心规则

flake 相关

• flake.lock 不提交：.gitignore 中保留 flake.lock。原因是 llama-cpp-ver 为浮动输入，锁定后随上游发布而过期。
• 本地操作前先移除 flake.lock：执行 nix build、nix develop、nix flake check 等命令前，先执行 rm -f flake.lock。锁定的 nixpkgs snapshot 可能缺少部分包（如自建包 godot-ai），移除后 Nix 重新解析输入确保使用最新可用版本。CI 中无需此操作——CI 按 check.yml 配置独立解析。
• llama-cpp-ver 输入是浮动追踪：overlay llama-cpp-rocm 通过此输入动态获取上游最新版本号，不可锁定。
• overlay llama-cpp-rocm 的 curried 形式是有意的：{ llama-cpp-ver }: (final: prev: ...) — 勿改为标准 overlay。
• 新模块/包/overlay 加入 flake.nix 后必须 nix flake check 验证。
• Overlay 的 patches 列表必须用 lib.unique 去重。

包

• 所有包的 maintainers 保持为空：个人维护项目，不在 nixpkgs 维护者列表中。
• 预编译二进制包：按 stdenv.hostPlatform.system 选择对应架构二进制（如 codewhale）。
• SRI hash 格式：sha256-<base64>。
• npm 包用 buildNpmPackage + finalAttrs 模式。
• buildNpmPackage 的 vendored lock 必须与 npmDepsHash 自洽：主构建把 src 的 package-lock.json 与 npm-deps 产物内 npm fixup 后的 lock 逐字节校验，不一致报 npmDepsHash is out of date。生成 vendored lock 必须采用 fixup 后版本（prefetch-npm-deps --fixup-lockfile，或从已实现的 /nix/store/...-npm-deps/package-lock.json 直接复制），再回填 hash。
• npm tarball 的 devDependencies 引用未发布包时：上游 monorepo 发布的 tarball 可能残留未发布内部包（registry 404）。postPatch 以纯 sed 删除该字段（patchPhase 无 node/npm），vendored lock 基于同样处理后的 package.json 生成——两者必须同源。
• 同源多通道（stable/alpha 等）仿 ruyi 薄包装模式：主定义参数化（version/hash/npmDepsHash/lockFile 可覆盖），通道文件仅传覆盖参数（参见 packages/dsh.nix + packages/dsh-alpha.nix）。
• Python 包用 buildPythonApplication + pyproject = true。