Capability Configuration zh CN

能力配置总览

语言： English · 简体中文

LWC 的能力配置用于选择可选的文档图与 Markdown 转换行为。它属于分层的 deployment-local state，不是 Wiki 知识，也不能加入 changeset。本页帮助你判断应启用什么、应在哪一层配置，以及如何验证最终生效结果。

两项能力默认都关闭。初始化只会介绍可用选项，绝不会自动启用或安装。

查看有效配置

lwc --scope project config show
lwc --scope global config show

响应包含：

• 当前 scope 与配置文件 path；
• 有效 graph setting 与 origin；
• 有效 trans setting、origin、timeout_seconds、anydoc_args 和 markitdown_args。

必须查看有效值及其来源。只读 .lwc/config.json 会漏掉 global inheritance 与内置默认值。

分层规则

解析顺序如下：

内置 disabled
      -> 非 inherit 的 global config
            -> 非 inherit 的 project config

Scope	配置路径	含义
Global	~/.lwc/config.json	当前用户的跨项目默认配置
Project	<project>/.lwc/config.json	当前 project Wiki 的覆盖配置

Graph 与 trans 各自独立解析。一个项目可以继承 global graph，同时选择自己的转换引擎。

配置文件格式版本为 3，拒绝未知字段，替换前会验证全部值，并通过原子临时文件写入。指向符号链接的配置路径会被拒绝。

文档图

支持以下设置：

值	行为
disabled	不做外部文档图投影或查询
grafeo	使用内嵌的 Grafeo file-backed engine
surrealdb	使用内嵌的 SurrealDB/SurrealKV engine
inherit	使用下一层配置

显式启用一个引擎：

lwc --scope project config set --graph grafeo
lwc --scope project work watch <work-id>
lwc --scope project graph verify

设置 grafeo 或 surrealdb 会排入一次全量投影 Work。配置成功本身不能证明图已经 ready。

关闭能力但不删除规范图事实：

lwc --scope project config set --graph disabled

恢复继承：

lwc --scope project config unset --graph

unset 只改变配置层，不返回 graph Work。如果继承让有效引擎从 disabled 变为 enabled，应检查 graph status 与 graph verify。需要全量重建时，通过显式 config set --graph <engine> 排入 projection。

前一项 graph Work 活动时不要切换引擎。应先等待并校验，再改设置，然后独立等待、校验新引擎。

文档转换

Trans 支持 disabled、markitdown 与 anydoc：

lwc --scope project config set --trans markitdown
lwc --scope project config set --trans anydoc
lwc --scope project config set --trans disabled

选择引擎不会安装它。lwc trans 会检查 executable 是否存在，不可用时返回 typed setup error。

默认 timeout 为 120 秒，可接受范围是 1 到 900：

lwc --scope project config set \
  --trans markitdown \
  --trans-timeout 300

重复 --trans-arg 会替换当前所选引擎保存的参数列表：

lwc --scope project config set \
  --trans markitdown \
  --trans-timeout 300 \
  --trans-arg --keep-data-uris

另一引擎的参数会单独保留。选择 disabled 时不能携带参数。

配置写入会拒绝明确 credential flag 与疑似 secret 的值。真正转换前还会再次检查 path-like positional argument、output override、credential flag 以及可能逃逸 LWC ownership boundary 的其他参数。

禁止在 trans argument 中保存 API key、token、password、subscription key 或客户 secret。

把 trans 层恢复为继承默认值：

lwc --scope project config unset --trans

原子组合更新

Graph 与 trans 可以在一次配置替换中同时更新：

lwc --scope project config set \
  --graph grafeo \
  --trans markitdown \
  --trans-timeout 300

如果 graph selection 是显式 enabled，响应还会包含 projection Work。即使本次主要目的是配置转换，也必须 watch 这项 Work。

Scope 规则

• project 更新 <project>/.lwc/config.json；
• global 更新 ~/.lwc/config.json；
• 拒绝 all；
• 配置是 deployment-local，因此拒绝 changeset selector；
• 默认根据当前目录发现项目，只有某条命令刻意指定其他项目时才使用 LWC_PROJECT_ROOT。

日常使用不要 export LWC_PROJECT_ROOT，也不要定义私有 LWC=/path/to/lwc 变量。应把 lwc 安装到 PATH，并在项目目录运行。

安全编辑规则

只使用 lwc config set 与 lwc config unset。Active process 期间不要手改 JSON。格式错误会以 invalid_config 阻止解析，不支持的版本返回 unsupported_config_version。

如果策略要求审核配置文件，应使用 config show 确认有效契约，再只读查看 owned file。分享诊断信息前要先脱敏 argument。

验收

每次配置变化后：

1. 运行 config show，确认 setting 与 origin；
2. watch 返回的 Work；
3. 独立验证已启用图；
4. 对 trans 执行一次不含敏感数据的真实转换，并检查 receipt 与输出；
5. 确认没有 secret 被持久化；
6. 配置变更与规范 Wiki 变更分开记录。

下一篇：作用域、项目解析与安全