prelude-install

安装并配置 Prelude

Prelude 是一套开发 Shell UI：一个 flake-parts 模块，或供其他 flake 使用的 prelude.lib.evalModule。它提供 nix develop 欢迎横幅（MOTD）、交互式命令选择器（x）、Markdown 文档查看器和主题化的 Starship 提示符。所有内容均通过已发布的 flake 运行，无需检出 Prelude 仓库。无需克隆即可打印文档：

nix run github:darkmatter/prelude#skill -- install   # full consumer walkthrough
nix run github:darkmatter/prelude#skill -- options    # generated prelude.* reference

0. 检查现有内容

进行任何更改前，先查看仓库：

• flake.nix — flake-parts（flake-parts.lib.mkFlake）接收该模块；其他任何形式（blueprint、普通的 outputs 函数）都使用 prelude.lib.evalModule，无需重组结构。注意现有的 inputs、imports 和 devShells，并保留它们。
• prelude.nix / title.txt — 决定是否需要设置之前，先检查已有的配套文件。直接修改现有配置；重新运行向导会覆盖这两个文件。
• .envrc — 保留现有的加载器；只有采用 nix-direnv 时才添加 use flake，不要将其与其他环境加载策略并用。
• 现有的 README 和 docs/ — 设置过程不会改动它们。

1. 运行向导（全新安装）

nix run github:darkmatter/prelude -- wizard

步骤：标题文本和 FIGlet 字体、项目名称、命令、组件开关（motd/menu/prompt/docs/.envrc）、MOTD 文案和布局、主题、确认。从项目根目录运行；需要交互式终端。向导会写入：

• prelude.nix — 完整的选项模板：启用你所选的配置，其他所有选项均以注释形式提供默认值（此文件也可作为内联文档）。
• title.txt — 渲染后的字标，写在配置旁边，并以裸名称引用，因此从任何 -o 目录都能解析。
• .envrc（内容恰为 use flake）— 仅在启用该选项且文件不存在时写入。
• 启用 docs 时：在项目根目录写入起始版 README.md 和 docs/getting-started.md — 保留已有文件。

-o path 会移动配套文件和 title.txt，但生成的 docs 条目（./README.md、./docs/getting-started.md）相对于配套文件，而起始文件会放在根目录 — 使用非根目录的 -o 时，请在求值前修正这些路径。向导会拒绝 -o flake.nix，且绝不会写入或替换 flake。如果没有 flake？nix flake init -t github:darkmatter/prelude#default 会搭建一个起始模板（在内联配置 prelude.*，然后跳到 验证）。

2. 将其接入 flake（合并，而非替换）

示例展示了要合并到现有 flake.nix 中的 Prelude 专用行 — 保留所有当前的输入、导入和开发 Shell 软件包：

inputs.prelude.url = "github:darkmatter/prelude";
# Fresh repo, no pins yet: share one nixpkgs/flake-parts via inputs:
#   inputs.nixpkgs.follows = "prelude/nixpkgs";
#   inputs.flake-parts.follows = "prelude/flake-parts";
# flake.lock pins the resolved revision even with the default-branch URL.
# Preserve an existing lock; use that revision for wizard/reference commands.
# A URL ending in /<rev> may additionally select an explicit commit or tag.

# inside mkFlake's module argument:
imports = [
  inputs.prelude.flakeModules.default
  ./prelude.nix # generated sidecar; import it, never replace flake.nix
];

# inside perSystem, alongside existing packages:
devShells.default = pkgs.mkShell {
  packages = [config.packages.prelude-shell];
};

只将 config.packages.prelude-shell 添加到开发 Shell 中 — 它会捆绑所有已启用的组件，并通过 setup-hook 激活。不要添加 packages.prelude（它为 prelude 应用提供支持）。

没有 flake-parts（blueprint、普通的 outputs 函数）：保持 flake 原样，并在定义开发 Shell 的位置求值同一个配套文件。它会构建与模块相同的软件包：

# blueprint: devshell.nix (nix/devshells/default.nix with prefix = "nix/")
{pkgs, inputs, ...}: let
  prelude = inputs.prelude.lib.evalModule pkgs ./prelude.nix;
in
  pkgs.mkShell {packages = [prelude.packages.prelude-shell];}

模块会接收 pkgs，因此由软件包提供的命令可直接放入 prelude.commands；这里没有 perSystem。通过包装模块的 _module.args 传入其他模块参数（self、inputs）。参考：examples/without-flake-parts/。

若要让 nix run github:darkmatter/prelude#docs（以及 #prelude-docs）打开项目自己的文档，请暴露 prelude-docs：flake-parts 已自动处理；否则添加 legacyPackages = forAllSystems (pkgs: (prelude.lib.evalModule pkgs ./prelude.nix).packages);，或者在 blueprint 中添加 packages/prelude-docs.nix。

3. 激活路径

• nix develop — 完整的交互式开发 Shell。启用提示符组件（向导默认设置）后，设置钩子会加载生成的初始化脚本：显示 MOTD、将 x/docs 添加到 PATH，并导出 STARSHIP_CONFIG。无需额外配置。启用 prelude.workspace.enable = true 后，带 TTY 的交互式 Bash 会在前台进入工作区，并显示页脚和目录补全。Starship 是否自动启动取决于 prelude.prompt.enable。

• direnv（nix-direnv）— 生成的 .envrc（use flake）会加载缓存的环境、显示 MOTD，并在启用提示符组件时为已初始化的 Starship 提示符应用主题。进入环境时保持轻量：不会显示完整页脚，也不会启用目录补全。新开发者只需使用已有的 direnv 钩子，无需额外添加 Prelude Bash rc 钩子。保留现有的 .envrc 及其加载器。启用 prelude.workspace.enable = true 后，.envrc 仍保持 use flake；不要从 .envrc 启动工作区或加载交互式项目初始化脚本。 仅使用加载器时，MOTD 会包含“运行 nix develop 以进入完整开发 Shell”；在工作区或静默模式下会隐藏此提示。要进入已启用的工作区，请运行交互式 nix develop。对于已配置好 direnv 后的交互式交接，仍可选择使用公开的 prelude hook bash，但它并非入门要求。 每个初始化脚本都会在启动前写入标记，因此退出或失败后不会立即重新打开；离开并重新进入开发 Shell，或初始化脚本发生变化后，才会再次进入。 非交互式、envrc、lorri、zsh 和非 TTY 环境都不会自动启动工作区；PRELUDE_WORKSPACE_ACTIVE 可防止子进程递归启动。工作区模式会跳过旧版 BLE 初始化。仍支持手动运行 x prelude:workspace 和 prelude-workspace --starship。

• lorri — 在 Nix 构建器中运行 shellHook，因此应通过同一个 .envrc 路由：将 use flake 替换为 eval "$(lorri export direnv-adapter)"。

• 自定义 shellHook — eval "$(prelude-preflight)" 是可识别加载器的激活语句。切勿在 shellHook 中使用 export -f（zsh 会拒绝 BASH_FUNC_…%% 名称中的 %）；特定 Shell 的设置应放在 prelude hook 中。

4. 自定义

编辑生成的 prelude.nix（也可以在 flake.nix 中内联配置）；所有选项都以注释形式列为默认值。重点如下：

• prelude.theme — prelude（默认）、phosphor、minted、amber、solarized、nord、gruvbox、paper（浅色）、mono、apathy；可通过 prelude.palette 覆盖令牌。
• prelude.commands.<key> — x 背后的目录条目；空格或 / 会创建子命令（"db migrate" → db 条目下的 x db migrate），设置 group = "…" 可指定菜单标题。使用软件包的命令： prelude.lib.fromPkg packages.dev { description = …; motd = 1; }。
• prelude.docs.pages = [{text = ./docs/foo.md;}] — 每个文件对应一个页面。

5. 将新文件纳入 Git 跟踪，然后验证

由 Git 管理的 flake 会排除未跟踪文件。检查 git status --short，并且只暂存为此设置创建或编辑的目标文件；不要暂存无关更改，也不要忽略 git add 错误。如果引用了新建的 README.md，请将其纳入暂存；同时纳入实际的 sidecar 和同级 title.txt 文件路径（包括自定义的 -o 路径），以及任何新引用的文档。不要仅仅因为向导使用了已有的 .envrc 就将其暂存。 本地评估无需提交。

或者，使用 nix develop path:. 和 nix flake check path:. 验证，这样无需更改索引即可包含工作目录。这可能会包含通常被 Git 排除的文件，因此只应在可信的本地工作树中使用。

然后进行实际的冒烟测试：

nix develop     # MOTD renders, themed prompt appears
x --list        # catalogue table prints non-interactively
x               # picker opens (q quits)
docs            # viewer opens when docs pages exist (q quits)
motd            # banner reprints on demand
nix flake check # full build gate (heavier)

按设计，非交互式 nix develop -c … 会保持静默（构建日志中不会显示横幅）——请使用交互式 Shell 查看 MOTD。

交接

• /prelude-just <arg> — 改造现有的 justfile。
• /prelude-docs — 编写文档查看器页面。
• /prelude <anything> — 其他 Prelude 工作。