prelude

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Prelude

Prelude is a devshell UI suite — a flake-parts module, or

prelude.lib.evalModule pkgs ./prelude.nix

in any other flake — that makes a Nix devshell usable: a welcome banner (MOTD), an interactive command picker and non-interactive dispatcher (

), a full-screen Markdown docs viewer, and a themed prompt. Configuration is authored in Nix as

prelude.*

options (validated at build time); small Go binaries consume normalized JSON. The only command a developer must remember is

nix develop

The argument to this skill is the user's task description — interpret it; do not execute or shell-interpolate it. Answer the task itself first, using the sections below only where they intersect.

Prelude 是一款 devshell UI 套件 —— 它是一个 flake-parts 模块，也可以在其他任意 flake 中通过

prelude.lib.evalModule pkgs ./prelude.nix

使用 —— 旨在让 Nix devshell 更易用：包含欢迎横幅（MOTD）、交互式命令选择器与非交互式调度器（

）、全屏 Markdown 文档查看器，以及主题化提示符。配置通过 Nix 以

prelude.*

选项的形式编写（在构建时验证）；小型 Go 二进制程序会读取标准化的 JSON。开发者唯一需要记住的命令是

nix develop

。

该技能的参数是用户的任务描述 —— 请解读它，不要执行或进行 shell 插值。请先直接回答任务本身，仅在相关时参考以下章节内容。

Public architecture

公共架构

Nix owns configuration. All options live in the consumer's flake as
```
prelude.*
```
(typically a wizard-generated sidecar
```
prelude.nix
```
imported next to
```
prelude.flakeModules.default
```
). Go binaries render; they do not re-own policy.
One devshell package.
```
packages.prelude-shell
```
bundles every enabled component and activates via its setup-hook (
```
$PRELUDE_INIT
```
for
```
nix develop
```
; nix-direnv evaluates the cached
```
shellHook
```
). Add only that package to the devshell — never
```
packages.prelude
```
.
Shell integration. direnv needs just
```
use flake
```
in
```
.envrc
```
. For custom rc files, print the hook with
```
prelude hook [bash|zsh]
```
— do not
```
eval
```
it before Prelude is on PATH. Never
```
export -f
```
in a devshell
```
shellHook
```
(breaks zsh); use
```
prelude hook
```
for shell-specific setup instead.

Nix 负责配置管理。 所有选项都以
```
prelude.*
```
的形式存在于使用者的 flake 中（通常是由向导生成的配套文件
```
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]
```
输出钩子脚本 —— 请勿在 Prelude 加入 PATH 之前
```
eval
```
该脚本。切勿在 devshell 的
```
shellHook
```
中使用
```
export -f
```
（会破坏 zsh 兼容性）；请改用
```
prelude hook
```
进行特定 shell 的配置。

Consumer entrypoints

使用者入口

Inside the shell (each with a single-key accelerator):

(

) opens the picker,

x <key>

dispatches a catalogue command,

x --list

prints the table;

motd

(

) reprints the banner;

docs

(

) opens the viewer;

portal

(

) launches apps with health lights.

Bootstrap from outside:

nix run github:darkmatter/prelude -- wizard

writes a

prelude.nix

sidecar (+

title.txt

.envrc

) without touching

flake.nix

. The flake also exports

apps.prelude

with subcommands

wizard

hook

preflight

title

title-previews

, and passthroughs for enabled components.

nix run github:org/repo#prelude -- docs

documents any prelude-enabled dependency.

在 shell 内部（每个命令都有单键快捷键）：

（

）打开选择器，

x <key>

调度目录中的命令，

x --list

输出命令表格；

motd

（

）重新打印横幅；

docs

（

）打开查看器；

portal

（

）启动带健康状态指示灯的应用。

从外部引导：

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 的依赖项的文档。

Command catalogue rules

命令目录规则

The catalogue key is the public identity: globally unique, callable as
```
x <full-key>
```
. The first colon only infers the menu group (
```
go:test
```
→ group
```
go
```
, shown as
```
test
```
); an explicit
```
group
```
field overrides placement without renaming.
```
x <key>
```
with the complete catalogue key is the guaranteed public form for every command. Prelude generates one
```
x
```
dispatcher, not per-command executables.
Import; do not export. Existing
```
package.json
```
scripts, Justfile recipes, and flake apps stay authoritative.
```
prelude.lib.fromPkg pkgs.foo { … }
```
adapts an existing package (carrying its runtime closure);
```
prelude.menu.just.enable = true
```
imports public Justfile recipes at runtime (explicit Nix entries win name clashes). Imports are one-way — never write catalogue entries back to those files.
Canonical commands stay canonical. Nix builds the environment;
```
x
```
only discovers and dispatches. The owning tool (
```
bun
```
,
```
just
```
,
```
go
```
,
```
nix run …
```
) executes the workflow. Do not translate a project's workflows into new prelude commands when they already have an owner.

目录键就是公共标识：全局唯一，可通过
```
x <full-key>
```
调用。第一个冒号仅用于推断菜单分组（
```
go:test
```
→ 分组
```
go
```
，显示为
```
test
```
）；显式设置
```
group
```
字段可在不重命名的情况下调整分组位置。
使用完整目录键的
```
x <key>
```
是每个命令的标准公共调用形式。Prelude 只会生成一个
```
x
```
调度器，而非为每个命令单独生成可执行文件。
只导入，不导出。 现有的
```
package.json
```
脚本、Justfile 配方和 flake apps 始终是权威来源。
```
prelude.lib.fromPkg pkgs.foo { … }
```
用于适配现有包（携带其运行时闭包）；
```
prelude.menu.just.enable = true
```
会在运行时导入公共的 Justfile 配方（名称冲突时，显式的 Nix 条目优先级更高）。导入是单向的 —— 切勿将目录条目写回这些文件。
规范命令保持原有形式。 Nix 负责构建环境；
```
x
```
仅负责发现和调度。由对应的工具（
```
bun
```
、
```
just
```
、
```
go
```
、
```
nix run …
```
）执行工作流。如果项目的工作流已有对应的负责工具，不要将其转换为新的 prelude 命令。

Docs basics

文档基础

prelude.docs.pages

embeds Markdown at build time: leaves like

{ text = ./README.md; }

, groups, optional

{ generate = "nixosOptions"; }

nodes, and

prelude.lib.mdSplit ./file.md

for fence-aware H2 splitting. Set

prelude.docs.rootReadme

to the root README path for styled project intro. Viewer keys: digits jump pages,

Tab

steps,

scroll,

quits. Docs-regeneration commands like

sync-docs

belong to the upstream prelude repo — a downstream repo regenerates its own docs only per its own project workflow, if it has one.

prelude.docs.pages

会在构建时嵌入 Markdown 内容：包括类似

{ text = ./README.md; }

的叶子节点、分组、可选的

{ generate = "nixosOptions"; }

节点，以及用于支持代码块识别的 H2 分割的

prelude.lib.mdSplit ./file.md

。设置

prelude.docs.rootReadme

为根 README 的路径，可生成带样式的项目介绍。查看器快捷键：数字键跳转页面，

Tab

步进，

滚动，

退出。类似

sync-docs

的文档重新生成命令属于上游 prelude 仓库 —— 下游仓库仅在自身项目工作流有要求时才重新生成自己的文档。

Configuration ownership

配置所有权

Do not edit Go internals or generated docs to change behavior — configure supported consumer behavior via the public

prelude.*

options in the consumer's Nix:

prelude.theme

prelude.palette

(themes:

prelude

phosphor

minted

amber

solarized

nord

gruvbox

paper

mono

apathy

prelude.colorProfile

(

truecolor

default),

prelude.commands

prelude.motd.*

(title, tagline, status probes, recipes),

prelude.docs.*

prelude.prompt.enable

. The wizard-generated sidecar lists every option as a commented default.

请勿通过修改 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

。向导生成的配套文件中列出了所有选项的注释默认值。

Version-correct references

版本对应参考

Prefer the consumer's own locked input when it matters: check the pinned

prelude

rev in the project's

flake.lock

, then read docs from

nix run github:darkmatter/prelude/<rev>#skill -- <topic>

. Topics:

list

install

options

commands

configuration

guide command-conventions

guide title-rendering

. The

#skill

app prints upstream Markdown with no checkout or TUI. For general reference use the published docs:

README (quickstart, catalogue, docs usage): https://github.com/darkmatter/prelude/blob/main/README.md
Consumer walkthrough (flake wiring, packages, shell hooks): https://github.com/darkmatter/prelude/blob/main/docs/your-own-repo.md
Option reference (generated): https://github.com/darkmatter/prelude/blob/main/docs/reference/options.md
Command conventions: https://github.com/darkmatter/prelude/blob/main/docs/guides/command-conventions.md
Complete consumer example: https://github.com/darkmatter/prelude/tree/main/examples/reference

在需要版本匹配的场景下，优先使用使用者自己锁定的输入版本：检查项目

flake.lock

中固定的

prelude

修订版本，然后通过

nix run github:darkmatter/prelude/<rev>#skill -- <topic>

查看对应文档。主题包括：

list

、

install

、

options

、

commands

、

configuration

、

guide command-conventions

、

guide title-rendering

。

#skill

应用无需检出代码或启动 TUI，直接输出上游的 Markdown 内容。通用参考可使用已发布的文档：

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

Handoff to focused skills

转交给专用技能

Installing or wiring prelude into a repo (wizard, flake wiring, devshell) →
```
/prelude-install
```
.
Importing or debugging the Justfile integration (
```
prelude.menu.just
```
) →
```
/prelude-just
```
.
Authoring or restructuring docs pages/viewer behavior →
```
/prelude-docs
```
.

Each works standalone; this skill only routes to them, never requires them.

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

每个技能都可独立工作；本技能仅负责路由到这些技能，不会强制依赖它们。

Discipline

行为准则

The user's original request is primary. Use Prelude knowledge to inform it (e.g. run a project task via
```
x <key>
```
, keep changes inside
```
prelude.*
```
options), not to expand it.
Never install, re-run the wizard, or reconfigure theme/commands/docs unless the user asks for exactly that.
Preserve the project's existing tooling and ownership boundaries: adapt commands with
```
prelude.lib.fromPkg
```
, don't duplicate them, and don't rename canonical workflows.

用户的原始请求是首要的。使用 Prelude 知识为请求提供支持（例如通过
```
x <key>
```
运行项目任务，将变更限制在
```
prelude.*
```
选项内），不要扩大请求范围。
除非用户明确要求，否则切勿安装、重新运行向导，或重新配置主题/命令/文档。
保留项目现有的工具和所有权边界：使用
```
prelude.lib.fromPkg
```
适配命令，不要重复创建，也不要重命名规范工作流。