module

name	module
description	Create or edit NixOS/Home Manager modules. Use when asked to create modules, add new modules, split modules, or manage the module architecture.

Module

系统模块模板

# modules/<name>.nix — <职责>
{ config, lib, pkgs, ... }:
let cfg = config.mcb.<选项>;
in {
  config = lib.mkIf cfg.enable {
    # 实现
  };
}

规则：lib.mkIf 条件启用、不用 with lib;；需要机器覆盖的共享默认值用 lib.mkDefault，合并型列表/条件接线按语义选择优先级；普通模块不声明 options.mcb.*（impermanence/secrets 平台骨架例外，需注明原因）。

共享辅助函数

从 modules/lib.nix 导入，不要本地重定义：

inherit (import ./lib.nix { inherit lib; }) resolvePkg validUserName;

resolvePkg — 安全解析 nixpkgs 路径（替代手动 tryEval）
validUserName — POSIX 用户名格式校验

创建步骤

1. 如需新开关 → modules/options.nix 的 options.mcb 下声明
2. 创建 modules/<name>.nix
3. 在 modules/default.nix imports 中注册（按分组顺序：核心→系统基础→包服务→桌面扩展→平台级）
4. nix fmt && statix check && deadnix --fail . && nix flake check

用户模块模板

# users/<name>/<feature>.nix
{ config, lib, pkgs, ... }:
{
  config = {
    home.packages = with pkgs; [ ... ];
    programs.xxx.enable = true;
    xdg.configFile."..." = { ... };
  };
}

在 users/<name>/default.nix 的 imports 中加入 ./<feature>.nix。

命名约定

类型	文件	示例
系统功能	modules/<name>.nix	gaming.nix
系统服务	modules/services/<name>.nix	services/desktop.nix
用户功能	users/<user>/<name>.nix	desktop.nix
选项声明	modules/options.nix（唯一）	—