prelude

Prelude

Prelude 是一套 devshell UI 套件——它是一个 flake-parts 模块，也可以在任何其他 flake 中使用 prelude.lib.evalModule pkgs ./prelude.nix。它让 Nix devshell 更易于使用：提供欢迎横幅（MOTD）、交互式命令选择器和非交互式分发器（x）、全屏 Markdown 文档查看器，以及主题化提示符。配置以 Nix 中的 prelude.* 选项编写（在构建时验证）；小型 Go 二进制程序使用规范化的 JSON。开发者只需记住一个命令：nix develop。

此技能的参数是用户的任务描述——请先理解，不要执行它或将其插值到 shell 命令中。首先回答任务本身；仅在与任务相关时使用下方各节。

公共架构

• 配置由 Nix 管理。 所有选项都位于使用者的 flake 中，作为 prelude.* 选项（通常是向导生成的旁置文件 prelude.nix，与 prelude.flakeModules.default 一同导入）。Go 二进制程序负责渲染，不负责重新管理策略。
• 一个 devshell 软件包。 packages.prelude-shell 捆绑所有已启用的组件，并通过其 setup-hook 激活（nix develop 使用 $PRELUDE_INIT；nix-direnv 则评估缓存的 shellHook）。只将该软件包添加到 devshell 中，绝不要添加 packages.prelude。
• Shell 集成。 direnv 只需在 .envrc 中使用 use flake。对于自定义 rc 文件，使用 prelude hook [bash|zsh] 输出 hook——Prelude 加入 PATH 之前不要对其执行 eval。切勿在 devshell 的 shellHook 中使用 export -f（这会导致 zsh 出错）；应改用 prelude hook 进行 shell 专属设置。

使用者入口

在 shell 内（每个命令都有一个单键快捷方式）：x（m）打开选择器，x <key> 分发目录中的命令，x --list 打印表格；motd（?）重新显示横幅；docs（d）打开查看器；portal（p）启动带健康状态指示灯的应用。

从 shell 外引导：nix run github:darkmatter/prelude -- wizard 会写入旁置文件 prelude.nix（以及 title.txt、.envrc），不会修改 flake.nix。该 flake 还导出 apps.prelude，包含子命令 wizard、hook、preflight、title、title-previews，以及用于已启用组件的直通命令。nix run github:org/repo#prelude-docs（或 #prelude -- docs）会为任何启用了 prelude 的依赖生成文档；nix run github:darkmatter/prelude#docs 则会通过该 flake 自带的 prelude-docs（如果有）为当前所在的 checkout 生成文档。

命令目录规则

• 目录键就是公共标识：必须全局唯一，且可通过 x <words> 调用。空格或 / 会创建子命令（"db migrate" → x db migrate；菜单中显示一行 db，用于打开其子命令）；: 是普通名称字符（x go:test）。分组仅由命令的 group 字段（或 just 配方的 [group()]）决定。
• x <words> 是每个命令都保证支持的公共调用形式。除 x 分发器外，只有已声明且不含 : 的顶层命令才会生成指向 x 的精简 PATH 包装器（因此，已声明 db 时，可以直接运行 db migrate）；如果某个父命令仅由其子命令声明，则不会加入 PATH。
• 导入，不导出。 现有的 package.json 脚本、Justfile 配方和 flake 应用仍是权威来源。prelude.lib.fromPkg pkgs.foo { … } 会适配现有软件包（并保留其运行时闭包）；prelude.menu.just.enable = true 会在运行时导入公开的 Justfile 配方（显式的 Nix 条目在名称冲突时优先）。导入是单向的——绝不要将目录条目写回这些文件。
• 规范命令保持规范。 Nix 构建环境；x 只负责发现和分发。实际执行工作流的是其所属工具（bun、just、go、nix run …）。如果项目的工作流已有所属工具，不要将其改写为新的 prelude 命令。

文档基础

prelude.docs.pages 会在构建时嵌入 Markdown：叶节点如 { text = ./README.md; }、分组、可选的 { generate = "nixosOptions"; } 节点，以及用于按 H2 标题拆分并识别代码围栏的 prelude.lib.mdSplit ./file.md。将根 README 路径设为 prelude.docs.rootReadme，即可显示带样式的项目介绍。查看器按键：数字键跳转页面，Tab 切换，j/k 滚动，q 退出。sync-docs 等文档重新生成命令属于上游 prelude 仓库；下游仓库仅在自身项目工作流（如果有）中重新生成自己的文档。

配置归属

请勿编辑 Go 内部实现或生成的文档来更改行为——应在使用者的 Nix 配置中通过公开的 prelude.* 选项配置受支持的使用者行为：prelude.theme/prelude.palette（主题：prelude、phosphor、minted、amber、solarized、nord、gruvbox、paper、mono、apathy）、prelude.colorProfile（默认值为 truecolor）、prelude.commands、prelude.motd.*（标题、标语、状态探测、配方）、prelude.docs.*、prelude.prompt.enable。向导生成的 sidecar 会将每个选项都列为注释掉的默认值。

与版本匹配的参考资料

相关时，优先使用使用者自身锁定的输入：检查项目 flake.lock 中固定的 prelude rev，然后通过 nix run github:darkmatter/prelude/<rev>#skill -- <topic> 阅读文档。主题包括：list、install、options、commands、configuration、guide command-conventions、guide title-rendering。#skill 应用会直接输出上游 Markdown，无需检出仓库或启动 TUI。一般参考资料请使用已发布的文档：

• README（快速入门、目录、文档用法）：https://github.com/darkmatter/prelude/blob/main/README.md
• 使用者指南（flake 接线、软件包、shell 钩子）：https://github.com/darkmatter/prelude/blob/main/docs/your-own-repo.md
• 选项参考（生成）：https://github.com/darkmatter/prelude/blob/main/docs/reference/options.md
• 命令约定：https://github.com/darkmatter/prelude/blob/main/docs/guides/command-conventions.md
• 完整的使用者示例：https://github.com/darkmatter/prelude/tree/main/examples/reference

转交给专门技能

• 在仓库中安装或接入 prelude（向导、flake 接线、devshell）→ /prelude-install。
• 导入或调试 Justfile 集成（prelude.menu.just）→ /prelude-just。
• 编写或重构文档页面／查看器行为 → /prelude-docs。

这些技能都可以独立使用；此技能只负责引导，不会要求使用它们。

原则

• 用户的原始请求优先。使用 Prelude 知识为其提供帮助（例如，通过 x <key> 运行项目任务，将更改限制在 prelude.* 选项内），不要扩大请求范围。
• 除非用户明确要求，否则绝不安装、重新运行向导或重新配置主题／命令／文档。
• 保持项目现有的工具链和归属边界：使用 prelude.lib.fromPkg 调整命令，不要重复定义命令，也不要重命名规范工作流。