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 为准）。不要删 flake.lock——2026-10-21 起它是已提交的受测基线；要更新输入请显式 nix flake update <input> 并同批提交新的 lock。

语言要求

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

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

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

项目定位

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

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

核心规则

flake 相关

• flake.lock 提交（2026-10-21 起）：唯一的浮动输入 llama-cpp-ver 已迁到 impure 分支，main 因此可以锁死——lock 就是受测基线。升级输入要显式 nix flake update <input> 并同批提交新的 lock。
• 本地操作直接用已提交的 flake.lock：不要 rm -f flake.lock（那是旧约定）。若 lock 里的 nixpkgs 缺某个包（例如 godot-ai 尚未进入该 snapshot），正确做法是 nix flake update nixpkgs 并把新 lock 一起提交——不是删掉 lock 让结果不可复现。CI 用同一份 lock。
• llama-cpp-rocm 不在本仓（2026-10-21 起）：llama-cpp-ver 浮动输入、overlay 与 NixOS 模块都已迁到 impure 分支（github:Kihara777/NixKits/impure；orphan 分支、不提交 lock、只装这一个包）。本仓 README 与文档不再提供它，用法见该分支的 README。
• impure 分支里 overlay 的 curried 形式仍是有意的：{ llama-cpp-ver }: (final: prev: ...) — 勿改为标准 overlay（要改请在该分支改）。
• 新模块/包/overlay 加入 flake.nix 后必须 nix flake check 验证。
• 新增文件先 git add 再跑 nix flake check：flake 源＝git 跟踪的文件集合，未跟踪的新文件不会进入 store——典型症状是检查里报 ERR_MODULE_NOT_FOUND 或「文件缺失」，而本地直接跑同一脚本却通过。先暂存（git add -A <路径>）再检查；CI 只看跟踪文件，所以这一步只在本地生效。
• Overlay 的 patches 列表必须用 lib.unique 去重。

包