Scopes and Project Discovery zh CN

作用域与项目发现

语言： English · 简体中文

Scope 决定命令可以读取或修改哪一个 Wiki。项目发现会从当前目录建立明确的文件系统授权边界，而不是提供通向任意 path 的便捷别名。本页说明日常发现、显式覆盖，以及防止跨项目访问的路径安全规则。

Scope 模型

Scope	Store	适用场景
project	最近的合法 ancestor <root>/.lwc/wiki.db	仓库知识与项目操作
global	当前用户的 ~/.lwc/wiki.db	跨项目记忆与默认配置
all	已初始化 project 与 global store 的有界合并	面向读取的 search、context、tag list 与 strong-tag load

会修改领域状态的命令只接受 project 或 global。读取类命令如果提供记录选项，启用记录前应先选择一个明确 writable scope。

合并读取后，project 与 global 结果仍保留各自 scope 字段。LWC 不会合并两份规范数据库。

日常项目发现

在项目或其子目录中直接运行 lwc：

cd /path/to/project
lwc --scope project context --limit 20

LWC 从当前目录向上查找，选择最近的真实 .lwc/wiki.db。它不会把用户 global ~/.lwc/wiki.db 误当 project Wiki，也不会搜索到 user-home boundary 之外。

lwc init 会复用最近 ancestor 中的已有 Wiki；找不到时才在当前目录初始化。

因此，日常命令既不需要 export project root，也不需要设置 absolute binary variable。

显式 LWC_PROJECT_ROOT

只有一个进程刻意指定已知项目边界，且当前目录位于该边界内时，才使用 LWC_PROJECT_ROOT：

LWC_PROJECT_ROOT=/path/to/project lwc --scope project context --limit 20

LWC 会 canonicalize root 与当前目录，要求 cwd 始终位于 root 内，并在该 boundary 停止解析。

如果当前目录与显式 root 之间存在多个 project Wiki，LWC 返回 project_scope_conflict，不会猜测本次命令应属于哪一个。

禁止把该变量写进 shell startup file 或 Agent instructions。已经位于当前项目时，它只会制造噪声，还可能让后续命令指向错误边界。

Global Home 解析

LWC 按以下顺序使用当前平台变量解析 user home：

1. HOME；
2. USERPROFILE；
3. HOMEDRIVE 加 HOMEPATH。

无法得到 home 时返回 home_not_set。Agent installation 与 global Wiki 共用同一用户边界，但各宿主路径仍由对应 AgentTarget adapter 管理。

路径安全

Store discovery 会验证 .lwc 目录、wiki.db、WAL 与 shared-memory sidecar 都是真实 path。符号链接或非普通文件会返回 typed unsafe-path error。

显式设置 LWC_PROJECT_ROOT 后，target path 的每个现有 ancestor 都会被 canonicalize，并且必须位于 root 内。Symlink 如果解析到外部，就会得到 project_root_escape。

Draft runtime、Work、graph sidecar、config、checkpoint 与 materialization 会在各自写入边界重复做 ownership check。只在入口比较一次字符串前缀并不足够。

Source 与转换路径

Source manifest 与转换 input 通常必须位于所选项目内。External Source 或转换输入需要显式 command option，之后仍会经过文件类型、大小、UTF-8 与 secret 检查。

转换 output 必须位于项目内、以 .md 结尾，并采用 create-new 语义。Adapter argument 不能暗中指定其他 output 或 positional filesystem path。

CodeGraph argument 相对 canonical project 规范化，并拒绝通过 ..、外部 absolute path 或可解析 symlink 逃逸。

MCP 项目授权

lwc serve --mcp 要求 client 在每次 explore call 中提供 absolute project path。该路径必须存在、不能是 filesystem root，并且能找到目标 Wiki/CodeGraph 状态。

服务会先验证 mode 与 path，再调用对应 backend。它不会修改当前进程 scope、初始化缺失能力，也不会把 relative path 当成 ambient authority。

Agent 安装位置

Agent 的 --location global 与 --location local 是集成位置，并非 Wiki scope：

• global 写入宿主官方 user configuration；
• local 写入当前项目的官方 host surface；
• 两者都不会自动启用 project Wiki、document graph 或 CodeGraph。

Receipt 会记录准确 path 与 post-install hash。Refresh 和 uninstall 依据 ownership 操作，不会在宿主目录下宽泛删除。

Secret 边界

禁止在以下位置保存 secret：

• Wiki 没有明确获得该数据授权时的 Source content；
• Page body 或 strong tag；
• command --reason 或被记录的 query wording；
• trans argument；
• Agent instruction、Hook output 或 MCP config。

LWC 会扫描部分 ingest 和配置 input 中的疑似 credential，但检测只是一道 guardrail，不能证明内容安全。用户仍需负责所选项目的数据分级和文件系统权限。

常见错误

• store_not_found：所选 scope 中没有 Wiki；
• project_root_invalid：显式 root 为空、不存在或不是目录；
• project_root_mismatch：当前目录位于显式 root 外；
• project_root_escape：所选 path 或 ancestor 解析到 root 外；
• project_scope_conflict：显式边界内存在多份 Wiki；
• store_path_invalid：Store 或 sidecar 不是安全普通 path；
• scope_not_supported：该命令不能使用 --scope all。

不要通过 symlink 或私有 absolute binary alias 绕过这些错误。应进入已授权项目目录，或修正显式边界。

验收

Mutation 前确认：

lwc --scope project context --limit 1
lwc --scope project config show

检查响应中的 database/config path 和 scope。刻意操作外部项目时，还要在执行 mutation 前确认 canonical root 与 cwd 的关系。

下一篇：Agent 兼容性