module

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 平台骨架例外，需注明原因）。

共享辅助函数

NixOS 系统模块从 modules/lib.nix 导入，不要本地重定义：

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

resolvePkg — 安全解析 nixpkgs 路径（替代手动 tryEval） validUserName — POSIX 用户名格式校验 managedUserNames — 从 mcb.users 解析用户，空列表回退 mcb.user

Home Manager 用户模块属于 /home/admin/mcbctl，其 homeModules.default 是 portable core；homeModules.linux、homeModules.niri 和 homeModules.nixos 分别提供 Linux、Niri 与 NixOS integration 能力。用户入口校验、能力 provider 与输出聚合由 mcbctl 的 flake/default.nix 维护，不从 NixOS 仓库导入。

创建步骤

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

Home Manager 用户模块模板

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

在 /home/admin/mcbctl/home/default.nix 的 imports 中加入 ./<feature>.nix，再按模块是否依赖宿主能力选择 homeModules.linux、homeModules.niri 或 homeModules.nixos，然后在 mcbctl 目录运行 nix flake check。

命名约定

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