CLI and Configuration Reference zh CN

CLI 与配置参考

语言： English · 简体中文

LWC 是一个以 JSON 为首要接口的命令行工具。命令成功时向标准输出写入 JSON；失败时向标准错误写入结构化错误，并以非零状态退出。本页说明各命令族的职责。具体参数与示例应以当前安装版本的 --help 为准。

调用模型

lwc [--scope project|global|all] [--changeset <name>] <command>

• project 是默认作用域，会向上查找最近的 .lwc/wiki.db；
• global 使用 ~/.lwc/wiki.db 中的用户级 Wiki；
• all 只读，且仅适用于 search 和 context；
• --changeset 将受支持的操作路由到指定隔离草稿。

应让 lwc 位于 PATH 中并直接调用。不要在日常命令前反复导出 LWC_PROJECT_ROOT，也不要用变量保存二进制绝对路径。只有在需要人为限定某个项目的发现边界时，才设置 LWC_PROJECT_ROOT。

配置模型

配置是 deployment-local JSON，按内置默认值、全局设置、项目覆盖的顺序分层解析。它不是 Wiki 知识，也不参与 changeset。

lwc --scope project config show
lwc --scope project config set --graph grafeo
lwc --scope project config set --trans markitdown --trans-timeout 120
lwc --scope project config unset --graph --trans

图设置支持 disabled、grafeo 和 surrealdb，转换设置支持 disabled、markitdown 和 anydoc。项目字段 unset 后会继承全局值；显式 disabled 则阻止继承。应读取响应中的 effective 配置与 origin，不要只看某一个文件就推断最终行为。

关于适配器参数、原子组合更新、安全规则与验收方式，参见能力配置总览。

命令族

命令	职责	主要说明
init	初始化所选 Wiki，并生成受管文件	快速开始
source	收集、查看、比较、引用和移除不可变证据	来源与摄取
ingest	驱动 Source 完成持久化分析流程	来源与摄取
page	创建、查看、关联和移除编译后的知识	Wiki 页面与溯源
schema、purpose	定义 Wiki 的内容契约和目标	持久记忆
search、span、context	检索文档或获取有界上下文	搜索与上下文
tag、load	策展并强载入核心 Page 集合	标签与强上下文
weight	设置显式排序权重或检索反馈	搜索排序与索引
graph	查询和维护物理文档图	文档知识图
cg	安装、初始化和检查 CodeGraph	代码图
trans	把外部文档转换成新的 Markdown 文件	文档转换
changeset	暂存并发布一组原子变更	变更集
work	查看、等待、取消和恢复持久 Work	Work 系统
checkpoint	创建或恢复完整 Store 快照	检查点与回滚
maintenance	重建投影、搜索索引或压缩存储	恢复与维护
lint、log	校验结构并查看持久操作历史	故障排查
view	打开仅回环可访问的只读 Viewer	只读 Viewer
serve --mcp	提供标准的 Agent MCP 传输	MCP 服务与 lwc_explore

Source 工作流

lwc --scope project source add docs/design.md --title "Design specification"
lwc --scope project ingest next --source-max-chars 100000
lwc --scope project ingest analyze <source-id> --file analysis.md
lwc --scope project page put source-<source-id> \
  --title "Design specification" --kind source \
  --file summary.md --source <source-id>
lwc --scope project page put architecture \
  --title "Architecture" --kind concept \
  --file architecture.md --source <source-id>
lwc --scope project ingest complete <source-id>
lwc --scope project lint

source add 只是收集证据，并不等于知识已经完成整合。必须走完摄取状态机，并写出带引用的 Page。

Source 的常用子命令包括 add、add-dir、add-manifest、list、status、diff、show、refs 和 remove。只有在确实获准读取项目外路径时，才使用 --allow-external-source。

检索工作流

lwc --scope project search "rollback graph projection" --limit 10 --explain
lwc --scope project search "exact sentence" --granularity sentence
lwc --scope all context --limit 25
lwc --scope project span get <span-id>
lwc --scope project span expand <span-id> --children 10

搜索默认优先返回编译后的 Page，并在必要时回退到 Source。可通过 --type、--kind、--granularity 和 --group-by 收窄结果模型。只有显式传入 --record 才会持久化查询操作。

Page 与 Tag 工作流

lwc --scope project page put operations-policy \
  --title "Operations policy" --kind policy \
  --file operations-policy.md --source <source-id>
lwc --scope project tag set rules operations-policy \
  --priority 100 --reason "Mandatory operating boundary"
lwc --scope project tag autoload rules --enable \
  --priority 100 --limit 10 --max-chars 50000 \
  --reason "Load at Agent lifecycle boundaries"
lwc --scope project load tag rules --limit 10

标签成员关系与自动载入策略是两类独立记录。load tag 会按确定性的优先级顺序返回完整 Page；它不是搜索命令。

图工作流

lwc --scope project config set --graph grafeo
lwc --scope project work watch <work-id>
lwc --scope project graph verify
lwc --scope project graph related page:architecture --limit 20
lwc --scope project graph path page:architecture source:<source-id> --max-depth 4
lwc --scope project cg init
lwc --scope project cg status

文档图与 CodeGraph 相互独立。命令返回已排队的 Work，不代表能力已经就绪；需要等待终态成功，再校验文档图或检查 CodeGraph 状态。

原子更新工作流

lwc --scope project changeset begin release-policy
lwc --scope project --changeset release-policy page put release-policy \
  --title "Release policy" --kind policy \
  --file release-policy.md --source <source-id>
lwc --scope project --changeset release-policy lint
lwc --scope project changeset show release-policy
lwc --scope project changeset commit release-policy

提交前可用 discard 丢弃草稿。提交后只能针对准确的 changeset-id 使用 rollback，并等待返回的图 Work。不要用 --allow-lint-issues 掩盖误报或未完成内容。

持久 Work

lwc --scope project work list
lwc --scope project work status <work-id>
lwc --scope project work watch <work-id>
lwc --scope project work cancel <work-id>
lwc --scope project work resume <work-id>

会改变状态的维护和图投影会返回 Work 元数据。watch 是正常的完成边界。取消采用协作式语义；只有观察到 cancelled 终态后，才能认为执行已经停止。

Viewer、Hook 与 MCP 传输

lwc --scope project view --no-open --port 0
lwc agent hook --agent codex --event SessionStart
lwc serve --mcp --path /absolute/project/path

Viewer 的启动与停止属于前台进程生命周期。Hook 模式从标准输入读取宿主事件信封。MCP 在标准输入输出上传输逐行 JSON-RPC；不要向该数据流混入面向人的日志。

机器可读的错误处理

if ! output=$(lwc --scope project lint 2>error.json); then
  jq -r '.error.code' error.json
  jq '.error.details' error.json
fi

自动化应根据 error.code 分支，检查 error.details，并保留进程退出状态。不要解析本地化文案，也不要认定报错就意味着完全没有变更：恢复类错误可能明确报告 canonical 部分成功。

另见JSON 输出与错误契约和作用域与项目发现。