Notist CLI

notist 是发布与检查的统一入口。build / serve 构建或预览当前 package 的 site；check / cst / core / json / query / html 分析单个源码或渲染单页；lsp 提供 stdio 语言服务。

字段见 Notist.toml 配置，包组织见 Package 与站点组织。从源码运行时使用 cargo run -p notist-cli -- <command>。

命令总览

命令	作用	选择方式	主要输出
`build`	构建当前包或 workspace 站点	当前包、-p、--workspace	文件树与 stdout 摘要
`serve`	预览一个包的站点	当前包或 -p	HTTP 服务与终端 / 浏览器诊断
`check`	解析并报告文档或模块的诊断	单文件或目录	stderr 诊断
`cst`	打印无损 CST	单文件	stdout 树
`core`	打印降糖后的 core / IR	单文件	stdout 树
`json`	打印 JSON analysis	单文件	stdout JSON
`query`	按 id / tag / ctor / function / level 选择节点	单文件	stdout JSON
`html`	渲染单页 HTML 及使用的组件资源	单文件	目录与 stdout 路径
`lsp`	通过 stdio 运行语言服务	编辑器	JSON-RPC

notist help <command> 或 notist <command> --help 显示当前二进制的完整参数。

全局选项

选项	说明
`--config <path>`	显式指定 Notist.toml，跳过最近清单的自动发现；路径相对当前工作目录。成员清单仍使用所属 workspace 的共享输出根。单文件命令用它提供文档扩展。
`--eval`	让 `core` / `json` / `query` 查看求值后的表示；`core` / `json` 只对文档生效，`.notc` 模块分析不经过文档求值。不影响 `build` / `serve` / `check` / `cst` / `html`。
`-v, --verbose`	在 stderr 展示树状实时构建进度与各阶段耗时，包括配置、文档分析、模块加载、求值、HTML、资源和发布；可放在子命令前后。重定向、CI 或 dumb 终端使用无动画的纯文本。
`-j, --jobs <N>`	build / serve 的统一工作线程数上限，N 为正整数；默认使用可用 CPU 数。可放在子命令前后。单文件命令和语言服务不使用构建执行器。
`-h, --help`	打印帮助。
`-V, --version`	打印版本。

配置发现

build / serve 从当前目录向上寻找最近的 Notist.toml，并识别所属的祖先 workspace；成员不继承 workspace 的扩展或站点选项。单文件命令只使用最近的包配置。

路径与配置作用域见 Notist.toml 配置。

workspace 内使用 -p / --package 按包名选择成员。--config 的作用类似 Cargo 的 --manifest-path，用于显式定位清单，例如从 workspace 外调用；指定成员清单不改变共享输出根。从源码运行时，cargo run -p notist-cli -- build -p notist-site 中，-- 前的 -p 选择 Rust crate，之后的 -p 选择 Notist 包。

发布：notist build

notist build [-p <package> ... | --workspace] [--out-dir <path>] [-j <N>]

选项	说明
`--workspace`	构建当前 workspace 中所有声明 site 的包；没有 site 的模块包跳过。
`-p, --package <name>`	按包名选择成员，可重复；与 --workspace 互斥。显式选择的包必须声明 site。
`--out-dir <path>`	覆盖该包站点的输出目录，相对当前工作目录。

普通包必须声明 site 才能直接 build / serve。纯 workspace 根默认构建所有站点；有 package 的根默认只构建根包，--workspace 构建全部成员。serve 需要包的 site；在纯 workspace 根通过 -p 指定成员。

一次调用共用一个构建执行器：文档求值和最终页面模板渲染使用相同的工作线程池，不为每个阶段或 workspace 成员分别创建线程池。-j 1 保持串行求值与串行模板渲染；小批次可以串行处理，不必用满线程。分析、链接与正文 HTML 渲染、资源准备及发布仍按阶段执行，不因指定 -j 就全部并行。

并行构建保持页面输出和诊断的归并顺序，但跨页资源请求交错时，共享预算耗尽的具体报错页面可能不同；要求原串行请求与扩展调用顺序时使用 -j 1。该预算不限制外部命令扩展及其子工具自行创建的线程。

输出与发布：

默认输出为 workspace 根的 notist-output / package.name；独立包以自己的包根作为 workspace 根。site.output 和 --out-dir 指定最终目录，不追加包名。
构建检查配置、资源与输出安全，再暂存并发布；失败保留该包的旧产物。
--out-dir 要求本次只选择一个站点。workspace 按包逐个发布，某个包失败会停止后续构建，不回滚已经成功发布的其他包。
成功时打印页数与绝对输出路径，例如 22 pages → /path/notist-output/manual。

# 当前包
notist build

# 所有构建阶段共用至多 8 个工作线程
notist build -j 8

# 串行构建，便于诊断和性能对照
notist -j 1 build

# 构建整个 workspace
notist build --workspace

# 按名称选择 workspace 成员
notist build -p manual
notist build -p website

# 临时输出位置，相对调用者目录
notist build -p manual --out-dir target/preview

预览：notist serve

notist serve [-p <package>] [--host <host>] [--port <port>] [--no-clear-screen] [-j <N>]

选项	默认	说明
`-p, --package <name>`	当前包	按包名选择一个 workspace 成员。
`--host <host>`	`127.0.0.1`	HTTP 监听主机名或 IP 地址，IPv6 直接写 `::1`。
`--port <port>`	优先 `8000`	显式指定时严格使用该端口；`0` 表示由系统分配空闲端口。
`--address <addr>`	无	完整监听地址，如 `127.0.0.1:9000` 或 `[::1]:9000`；与 `--host`、`--port` 互斥。
`--no-clear-screen`	关闭	保留每一轮构建的终端输出；重定向、管道和 CI 环境也会自动关闭清屏。

serve 与 build 使用同一份 package / site 配置，不需要额外选择发布目标。初次构建与后续监听重建复用同一个执行器和 -j 设置；HTTP 服务与文件监听线程不计入构建工作线程数。

未指定端口时优先使用 8000，被占用则选择空闲端口；指定端口不可用时则报错。终端输出实际监听地址。

serve 在内存中生成与静态构建相同的产物，监听源文件、模板、样式、数据、配置和实际读取的模块资源。失败时保留上一次成功预览，并明确提示当前展示旧内容；修复后自动重建。预览始终使用根路径 /，静态构建使用 Site 的 base_url。

文件监听在注册前按 site.exclude 剪枝，路径与内容发现一致：相对 content，挂载目录使用 mounts.path 的命名空间。排除目录不递归遍历；隐藏目录、target、node_modules、发布输出和符号链接也不会被递归监听。不递归监听整个包根。修改 Notist.toml 后重新计算监听范围，新增目录和被删除后重建的目录仍可触发预览更新。

exclude 是内容发现过滤，不取消实际构建依赖：模板、静态文件、数据、声明的扩展 watch，以及实际读取的模块和文件仍保留必要监听。隐藏或排除目录中的具体文件只监听其必要父目录，不因此重新遍历整棵目录。站点命令在内容目录外使用的脚本与其他输入应声明在其 watch 中。

使用 -v 查看各阶段进度与耗时；serve -v 同时保留每轮终端输出。进度写入 stderr。

cd book && notist serve
notist serve -p website
notist serve -p website --host 127.0.0.1 --port 9000

单文件命令

单文件命令分析指定文件，使用最近 Notist.toml 的顶层文档扩展；可通过 --config 指定配置。生成页面需通过 build / serve 运行 SSG 站点扩展。

check

notist check <file|dir>

解析并物化文档，报告全部诊断。文件参数可以是 .not / .md 文档或 .notc 模块；.not 文档还会检查本地的正文链接与锚点。参数是目录时索引该目录并检查其中的文档。

诊断写到 stderr；有任何问题以非零状态退出，并用 check: N issues in <file> 或 check: N issues under <dir> 汇总。

notist check docs/README.not
notist check docs
notist check modules/grammar/src/lexer.notc

cst / core / json

三个命令把不同层次的表示打印到 stdout：

命令	输入	输出
`cst`	单文件	无损 CST，不做名称解析或求值。
`core`	单文件	降糖后的 core / IR。文档输出求值前的 Item 树；`.notc` 输出模块分析。
`json`	单文件	完整 JSON analysis：语法树、AST、core 与诊断。`.notc` 输出模块 JSON。

--eval 在这一组命令中只改变文档的 core / json：core 打印求值后的 Item，json 追加 core 与 evaluation_diagnostics。.notc 的模块分析不经过文档求值。query 的 --eval 见下一节。

notist cst docs/README.not
notist core docs/README.not
notist core docs/README.not --eval
notist json docs/README.not
notist json docs/README.not --eval

query

notist query <file> <selector>

在文档的表示树上按 selector 选择后代节点，输出 JSON。--eval 时在求值后的树上选择。

selector	匹配
`id:<value>`	`id` 属性等于 value 的节点。
`tag:<value>`	`tags` 中包含 value 的节点。
`ctor:<name>`	构造函数名；扩展函数按注册名匹配，内置构造不区分 ASCII 大小写。
`function:<module.fn>`	调用的函数身份。
`level:block` / `level:inline`	内容层级。

notist query docs/README.not 'level:block'
notist query docs/README.not 'function:notist.math'
notist query docs/README.not 'tag:diagram' --eval

html

notist html <file> [--out-dir <dir>]

渲染单个文档为 HTML，并把实际使用的组件资源写入目录；默认输出目录是 target/notist-html。命令在 stdout 打印生成的 index.html 路径。

适合检查组件和单页呈现。构建完整书籍或站点时使用 build。

notist html docs/components/README.not --out-dir target/components-demo

lsp

notist lsp

通过 stdio 运行语言服务；--config 指定编辑器会话使用的清单。lsp 是默认 feature 的一部分；构建时关闭 lsp feature 则不提供该子命令。

提供诊断、文档大纲、悬浮与定义跳转，采用全文同步。每批输入以全部未保存文件覆盖磁盘资源，创建新 Vault；查询复用同批的分析、环境、源码导航与索引，不重新运行扩展。模块编译与导入绑定缓存可跨批次复用。

文档使用与单文件 check 相同的 id 与同文档锚点检查。链接跳转共用工作区索引的目标分类；跨文件锚点在同批输入中读取直接引用的目标文档，优先使用未保存内容，不递归扫描整个工作区。

文档扩展只运行 beforecheck 与 aftercheck；不执行求值、after_evaluate 或 site.extensions。command 扩展仍是同步执行，没有超时或取消；每批输入仍会刷新全部打开文档，没有编辑防抖或按依赖选择性重分析。

诊断、输出与退出码

成功返回 0，失败返回非零（当前为 1）。
诊断与人类可读错误写到 stderr；JSON、CST、core 等机器输出写到 stdout。build 的页数摘要在 stdout；serve 的地址行在 stdout，构建状态在 stderr。
warning 不阻止 build 发布；阻止构建的错误会保留旧产物（build）或旧预览（serve）。
终端颜色与清屏按 TTY 自动判断；重定向、管道和 CI 不输出清屏控制序列。

常见工作流

# 构建并部署文档
notist build --config docs/Notist.toml

# 本地预览，指定端口
notist serve --config docs/Notist.toml --port 9000

# 检查一份文档或整个目录
notist check docs/README.not
notist check docs

# 查看 IR 与求值结果
notist core docs/README.not
notist json docs/README.not --eval

# 按标签或函数选择节点，交给 jq 等工具
notist query docs/README.not 'tag:diagram' | jq .

# 导出单页组件示例
notist html docs/components/README.not --out-dir target/components-demo