llmdoc / docs / cli

CLI 参考

以 npx -y @tokenroll/llmdoc <command> 调用外部 CLI。工作流需要可复现时，在包名中固定版本。

发现与读取

tree

根文档与 topic 的动态地图。

index [--topic …] [--kind …]

用于发现文档的 front matter 投影。

search <query>

在跟踪知识中执行词法搜索；中文查询自动分词，零 lexical 召回时明确标注 CJK bigram 降级。

context --files <src…>

逐个把源码路径映射到 owner 文档与依赖前置，并明确报告未映射输入。

show <path…>

读取选中的文档正文。

serve

在 127.0.0.1 启动本地 Viewer，查看文档结构、关系与状态。

检查有效性

status

有效性、baseline、dirty 与增长信号。

delta

从代码变化计算受影响文档闭包。

validate

校验 schema、结构、关系、链接、代码路径（含零命中 glob）、ledger 一致性与可选启动配置。

安全改写

new <path> --kind <kind>

创建 V3 文档骨架；最近 Git 根尚无 llmdoc/ 时会自动建立目录。

adopt <path…>

登记已有合法文档，不重写正文。

mv <from> <to>

移动文档，并事务性重写内部引用、ledger identity 与匹配的 startup preload 项。

init-state

在真实 Git HEAD 上建立首次 ledger；unborn 仓库须先创建初始 commit。

commit [--verified <path…> | --all]

校验、提交正文，并刷新变化或验证未变文档的 revision。

fingerprint --update <path…> | --all

刷新 ledger 中经过验证的 revision。

显式操作与 hooks

prune --report

只读的知识收敛信号，并列出手工合并或删除必须维护的 startup preload 引用。

upgrade

显式 V2 迁移诊断。

hook session-start | stop | compact

只读、fail-open 的宿主信号。

启动上下文配置

llmdoc workspace 根目录可增加可选的 llmdoc.config.json；在 Git 仓库中，它就是拥有 llmdoc/ 的最近 Git 根。该配置可让 SessionStart 主动提示 Agent 使用 llmdoc skill，并在冷启动直接载入精确文档：

{
  "$schema": "https://llmdoc.tokenroll.ai/schemas/config.schema.json",
  "schema": "llmdoc.config/v1",
  "startup": {
    "remindSkill": true,
    "preload": ["architecture.mdx", "api-client/contracts.mdx"]
  }
}

已发布的 schema 可供编辑器校验。操作守则默认启用；将 remindSkill 设为 false 可关闭。冷启动预载保持声明顺序，且不设置 llmdoc 字符或 token 预算；结尾完成标记用于暴露可能的宿主截断。compact 重入只列文档 ID，不重复注入正文。

validate 会拒绝非法或不存在的路径，并在去重规范化别名时产生 warning。hook 保持 fail-open：JSON/schema 无法读取时使用默认提醒；仅 preload 出错时保留合法的 remindSkill 选择并跳过 preload。

CLI 自身的固定界面文案全部使用英文；中文查询与仓库文档内容仍完整支持并保持原文返回。