vault::cli

Notist CLI

notist 是 Notist 的统一可执行文件。它既提供面向人的命令，也提供编辑器、Agent host 和后台服务使用的协议入口：

普通命令   check / inspect / search / outline / references / query / edit / convert
站点命令   build / preview
协议入口   lsp / mcp
后台服务   daemon
Agent 资源 skill init

最常用的调用形式是：

notist check docs
notist search "workspace revision" docs
notist build docs -o dist
notist preview docs

命令总览

notist daemon [ROOT]
notist lsp
notist mcp [ROOT]
notist skill init <OUTPUT>

notist check [ROOT]
notist inspect [ROOT]
notist search <QUERY> [ROOT]
notist outline [ROOT]
notist references <MODULE> [ROOT] [--include-definition]
notist query definition <PATH> <OFFSET>

notist edit replace <PATH> <START> <END> <REPLACEMENT>
                    --idempotency-key <KEY>
notist edit rename <FROM> <TO> --idempotency-key <KEY>

notist convert <SOURCE> <OUTPUT> [--force]
notist build [ROOT] [-o <OUTPUT>] [--clean]
notist preview [ROOT] [--host <HOST>] [--port <PORT>] [--no-open]

所有命令都支持 -h / --help。顶层还支持 -V / --version、--color、--no-daemon 和 --format。

ROOT 与 Vault 发现

接受 [ROOT] 的命令默认从当前目录开始。ROOT 可以是 Vault、Vault 内的 source，或包含一个明确 Vault 的上层目录。Notist 按以下顺序确定实际 root：

1. 从给定路径向上查找最近的 Notist.toml，找到后使用 marker 所在目录。 2. 没有祖先 marker 时，检查给定目录下的显式 Vault。 3. 只发现一个显式 Vault时使用它；发现多个时要求传入更明确的路径。 4. 没有 marker 时，把给定目录作为隐式 Vault root。

例如：

repository/
├── src/
└── docs/
    ├── Notist.toml
    ├── README.not
    └── guide.not

下面两条命令选择的都是 docs/：

notist check docs
notist query definition docs/guide.not 40

完整 marker、nested Vault 和 ModulePath 规则见 vault::designs::D0007-notist-toml。

全局选项

--format <FORMAT>

有限生命周期的 CLI 命令支持两种输出格式：

text    面向人的现有文本输出，默认值
json    面向 Agent 和程序的版本化 JSON

全局参数可以写在子命令之前或之后：

notist --format json search "workspace revision" docs
notist search "workspace revision" docs --format json

成功或业务失败的有限命令在 stdout 写入一个 JSON document：

{
  "schema_version": 1,
  "command": "search",
  "ok": true,
  "result": {
    "root": "...",
    "snapshot": { "...": "..." },
    "query": "workspace revision",
    "results": []
  }
}

schema_version 描述 CLI envelope，不等于 daemon protocol version。command 使用稳定的逻辑名称，例如 check、query definition 或 edit replace。ok 表示命令的业务结果；例如 check 找到 diagnostics 或 edit plan 被拒绝时，仍能生成合法 JSON，但 ok 为 false 且进程返回非零状态。

无法形成命令结果的运行错误写入 stderr：

{
  "schema_version": 1,
  "command": "check",
  "ok": false,
  "error": { "message": "..." }
}

JSON 模式不输出 ANSI color，也不要求调用者解析人类 diagnostics 行。Path 表示为字符串；source range 表示为 { "start": N, "end": N }，仍然是 UTF-8 byte range。

各命令的 result 保留它需要的上下文：

  • check：root、snapshot、summary 和 diagnostics。

  • inspect：root、snapshot，以及 modules、references、semantic items 组成的 inspect record。

  • search：root、snapshot、原 query 和 results。

  • outline：root、snapshot 和 documents。

  • references：root、snapshot、module、include-definition 选择和 locations。

  • query definition：root、snapshot、输入 path/offset 和 nullable definition。

  • edit replace：被拒绝时返回 plan，成功时返回 applied record。

  • edit rename：返回 rename record。

  • build：root、output、page count 和 diagnostics。

  • skill init：输出目录与生成的文件列表。

preview --format json 是长期进程，因此 stdout 使用 JSON Lines：每行是一个独立 event envelope，包含 schema_version、command: "preview"、event 和 data。事件包括 initial/rebuild publication、listening URL、warning 和异步错误。前台 daemon --format json 同样先输出 started event，再持续服务。

lsp 与 mcp 的 stdout 本身就是 JSON-RPC transport，不能再包装 CLI JSON；对它们传入 --format json 会明确失败，避免污染协议流。Clap 自己产生的参数解析与 --help 输出仍是文本，因为命令尚未开始执行，调用者不应把 JSON 模式当成未知参数恢复协议。

--no-daemon

默认情况下，普通命令先根据 canonical Vault root 定位该 Vault 的本地 daemon。没有可用 daemon 时，client 会用当前 notist 可执行文件自动启动一个 detached 后台 child。

--no-daemon 跳过 daemon 连接与自动启动，改为在当前 notist 进程中创建一个 root-bound embedded NotistService：

notist --no-daemon check docs

两种模式调用同一组 core request，语言语义和结果格式应当一致。区别只在进程与状态生命周期：

默认模式
  command -> Vault daemon -> shared Engine/cache/watcher
                                可被同一 Vault 的后续 client 复用

--no-daemon
  command -> in-process service
             只活到当前 command / LSP / MCP 进程结束

因此 --no-daemon：

  • 不是关闭分析；parser、Analyzer、snapshot 和查询仍会完整运行。

  • 不会连接或启动后台 daemon，也不会复用其他进程的 warm cache。

  • 不会让普通 CLI 读取编辑器尚未保存的 overlay；CLI 仍打开 disk View。

  • 适合 CI、受限环境、排查 daemon/IPC 问题，以及需要一次性隔离状态的调用。

  • 用于 lsp 或 mcp 时，embedded service 会随对应 adapter 进程持续存在，而不只是单个 request。

--color <COLOR>

控制面向终端的诊断颜色：

auto     根据输出终端自动决定，默认值
always   总是输出颜色控制码
never    从不输出颜色控制码，适合 CI 日志

示例：

notist --color never check docs

检查与调试

check

notist check [ROOT]

检查整个 Vault 的 ModulePath、reference 和语义诊断。

notist check docs

没有诊断时输出 checked <N> modules 并返回成功；存在诊断时输出 source path、UTF-8 byte range、错误码和消息，并返回失败。它是 CI 中验证 Vault 的首选命令。

inspect

notist inspect [ROOT]

输出发现的 module、解析后的 reference 和内部语义项，用于理解 Vault 被分析成了什么：

notist inspect docs

inspect 是人类调试输出，不是稳定的机器交换格式。程序集成应使用 core protocol、LSP 或 MCP。

搜索与语义导航

这些命令默认读取已保存文件组成的 disk View。输出位置中的 range 都是 UTF-8 byte range。

search

notist search <QUERY> [ROOT]

搜索当前 snapshot 捕获的 Notist source context：

notist search "workspace revision" docs

每条结果包含 source path、byte range 和匹配上下文。当前命令是 source-context 搜索入口；未来的语义检索或向量索引仍应保持同一 Vault 和 snapshot 边界。

outline

notist outline [ROOT]

输出整个 Vault 求值后的 heading outline，并按 heading level 缩进。结果为每个 source 保留一条 document record；没有标题的文档返回空 symbols，因此可以与 inspect/source 列表稳定对应。标题 name 使用可见文本投影，保留 inline Raw、Math、图片 alt 和链接正文：

notist outline docs

references

notist references <MODULE> [ROOT] [--include-definition]

MODULE 必须是绝对逻辑 ModulePath，而不是文件路径：

notist references vault::designs::D0011 docs
notist references vault::designs::D0011 docs --include-definition

默认只返回引用位置；--include-definition 额外包含 module 自身的定义位置。

query definition

notist query definition <PATH> <OFFSET>

查询 source 的 UTF-8 byte offset 处符号所指向的定义：

notist query definition docs/designs/D0011-analyzer-and-workspace-snapshot.not 120

OFFSET 不是行号、列号或 Unicode 字符序号。编辑器通常应使用 LSP，由 adapter 完成 Position 与 byte offset 转换；该 CLI 入口适合 Agent、脚本和协议调试。

带前置条件的编辑

编辑命令直接修改磁盘 source，因此必须提供 idempotency key，并经过 snapshot/fingerprint 前置条件验证。

edit replace

notist edit replace <PATH> <START> <END> <REPLACEMENT>
                    --idempotency-key <KEY>

替换 [START, END) 表示的 UTF-8 byte range：

notist edit replace docs/page.not 10 18 "replacement" \
  --idempotency-key task-42-edit-1

命令先基于当前 snapshot 提议 edit plan，检查 plan diagnostics 和受影响 source fingerprint，再应用写入。如果文件在提议与应用之间发生变化，前置条件失败，命令不会覆盖新内容。

edit rename

notist edit rename <FROM> <TO> --idempotency-key <KEY>

在同一个 Vault 内重命名 source：

notist edit rename docs/old.not docs/new.not \
  --idempotency-key task-42-rename-1

源文件必须存在，目标不能越出 Vault，也不能覆盖已有目标。命令使用源 fingerprint 防止并发变化，并保留显式 rename 所对应的稳定 file identity。

Idempotency key

--idempotency-key 标识一次逻辑写入，而不是一次进程调用：

  • 同一次操作因连接中断等原因重试时复用原 key。

  • 不同 replace 或 rename 使用不同 key。

  • key 应由调用者生成并在自己的操作日志中保持稳定。

这样 daemon 可以识别已经完成的重试，避免一次 Agent 操作被写入两遍。

Vault 转换

convert

notist convert <SOURCE> <OUTPUT> [--force]

把 Markdown 或 Obsidian Vault 转换成新的 Notist Vault。命令先索引整个源 Vault，再转换所有 .md / .markdown 文档并把其余资源按对应相对路径复制到输出目录；输出目录会包含 Notist.toml marker。文件或目录名含有 Notist ModulePath 禁止的 [、]、# 时，输出路径会把这些字符归一化为 -，并同步重写文档和资源链接。

转换会把 Markdown 标题、inline formatting、列表、表格、代码、图片和命名链接改写为 Notist syntax。指向 Markdown 文档的相对链接与 Obsidian Wiki link 会解析成稳定的 [[vault::module#label]] reference；标题同时生成 annotation label，因此跨文档 heading link 仍可导航。图片、附件与其他普通链接保留相对位置。

默认拒绝写入非空输出目录；--force 允许合并并覆盖同名转换产物。输出目录不能是源 Vault 本身或其子目录，以免递归复制。无法解析或存在歧义的 Wiki / 文档链接会作为 warning 输出，并在生成文档中退化成可见文本或普通链接。--format json 的 result 包含转换文件数、复制资源数和 warnings。

notist convert notes notes-notist
notist convert obsidian-vault notist-vault --force --format json
notist check notist-vault

构建与预览

build

notist build [ROOT] [-o <OUTPUT>] [--clean]

把整个 Vault 构建为多页静态 HTML：

notist build docs
notist build docs -o dist
notist build docs -o dist --clean

OUTPUT 默认是 dist。普通构建不会先删除整个输出目录；--clean 才会在写入前清理选定目录。Notist 拒绝把 Vault root 作为输出目录，也拒绝清理过于宽泛的路径。

构建存在 diagnostics 时仍会报告生成结果，但以失败状态退出。

preview

notist preview [ROOT] [--host <HOST>] [--port <PORT>] [--no-open]

启动带 live reload 的本地预览：

notist preview docs
notist preview docs --port 3000 --no-open

选项：

--host <HOST>   监听地址，默认 127.0.0.1
--port <PORT>   TCP 端口，默认 0，由操作系统分配可用端口
--no-open       不自动打开默认浏览器

绑定非 loopback 地址会把文档内容暴露到相应网络接口，Notist 会输出安全警告。

官方文档与 Agent Skill

每个正常 CLI 工作流开始前都会检查当前版本内嵌的官方 docs fingerprint。用户数据目录中的 manifest 已匹配时只进行一次轻量比较；缺失或不匹配时，CLI 在跨进程锁内把完整 docs bundle 解压到 staging tree，校验后原子发布为稳定的普通 Vault。

默认位置是：

Windows   %LOCALAPPDATA%\Notist\docs
macOS     $HOME/Library/Application Support/Notist/docs
Unix      ${XDG_DATA_HOME:-$HOME/.local/share}/notist/docs

NOTIST_DATA_DIR 可以覆盖 Notist user-data root，此时官方 Vault 位于 $NOTIST_DATA_DIR/docs。这个覆盖适合测试、沙箱和可迁移安装；它改变的是整个 Notist 数据根，而不只是文档查询。

同步完成后没有 docs 专用查询命令。它使用现有普通接口：

notist search "WorkspaceSnapshot" <DOCS_ROOT>
notist outline <DOCS_ROOT>
notist references vault::designs::D0012 <DOCS_ROOT>
notist mcp <DOCS_ROOT>

初始化官方 Agent Skill：

notist skill init <OUTPUT>

OUTPUT 必须不存在，且父目录必须已经存在。成功后目录中只有 SKILL.md；命令不猜测 Agent host 的安装位置，也不覆盖或更新已有 Skill。Skill 教 Agent 使用普通 Notist 命令查询同步后的官方 Vault，并区分当前公开文档、活动设计、日期调研与历史设计。

官方 docs source 与 Skill 都来自当前 CLI 的内嵌发布资源，因此首次使用不需要 GitHub 或其他网络服务。向量模型和索引不包含在二进制中；未来启用语义检索时，它们仍是 docs Vault 自己的 daemon/cache 派生状态。

协议入口

lsp

notist lsp

编辑器配置：

command: notist
args: ["lsp"]

lsp 通过 stdin/stdout 传输 LSP JSON-RPC。stdout 必须只承载协议消息，不能写日志或包装器输出。一个编辑器 worktree 可以包含多个 Vault；adapter 按最近 Notist.toml marker 路由 source，并连接各 Vault 自己的 daemon。

编辑器未保存文本保存在该 LSP session 的 overlay View 中。它不会写入磁盘，也不会自动出现在普通 CLI、MCP 或另一个编辑器的 View 中。详细生命周期见 vault::designs::D0008-language-server。

mcp

notist mcp [ROOT]

Agent host 配置：

command: notist
args: ["mcp", "docs"]

当前 MCP server 打开所选 Vault 的 disk View，并提供：

tools       search, get_references, definition
resources   notist://<vault>/diagnostics
            notist://<vault>/outline

MCP 看不到编辑器未保存的 overlay。MCP resource 也是只读语义资源，不等于可写文件系统。

Daemon

notist daemon [ROOT]

手动以前台方式运行一个 Vault 的共享 service：

notist daemon docs

通常不需要手动启动它；普通 client 会在 endpoint 不可用时自动拉起后台 child。两种启动方式的生命周期不同：

自动后台 daemon   没有连接的五分钟 idle 检查窗口内自动退出
显式前台 daemon   持续运行，直到用户或宿主终止进程

一个 daemon 只服务启动时确定的 canonical Vault root。Endpoint 由当前用户身份和 root 共同派生；handshake 还会验证协议版本、Vault root 和 capabilities。不同 Vault 使用不同 daemon、watcher、Engine、索引和内存生命周期。完整进程模型见 vault::designs::D0012-daemon-and-client-interfaces。

输出、退出状态与帮助

一般约定：

  • 普通结果写入 stdout，diagnostics 和错误写入 stderr。

  • 成功返回 exit code 0；参数错误、服务错误或命令定义的 diagnostics failure 返回非 0。

  • source 位置使用 UTF-8 byte range，形式通常为 path:start..end。

  • 人类可读输出不应被当作稳定协议格式。

查看安装版本实际支持的命令和选项：

notist --help
notist check --help
notist edit replace --help
notist preview --help