Architecture Overview zh CN

总体架构

语言： English · 简体中文

LWC 是本地优先的 Rust CLI，整体架构遵循一条核心原则：SQLite 持有规范知识，其他表示要么是派生状态，要么是部署本地状态。因此，Agent 可以使用更丰富的检索和图能力，而不必把某个可选服务变成事实来源。

当一项变更同时涉及存储、索引、图、Agent 集成或恢复边界时，应先阅读本页。

系统全景

Agent / 人类 / 脚本
        |
        v
Clap CLI 分发器 -------- stdio MCP 服务 -------- AgentTarget 安装器
        |                      |                         |
        +---------- 有界命令与结构化 JSON -------------+
                               |
                               v
                        规范 Store（SQLite）
                        Sources · Pages · links
                        ingest · tags · retrieval
                        operations · changesets
                               |
             +-----------------+-----------------+
             v                 v                 v
        生成 Markdown       文档图投影          检索投影
        供人类阅读          Grafeo/SurrealDB    FTS5 + spans
                               |
                               v
                          持久化 Work

项目源码文件 -------------------------------> CodeGraph 索引
                                             独立、项目本地

命令路径

二进制入口分为三层：

1. cli::definitions 使用 Clap 声明公开命令语法；
2. cli::dispatch 解析 scope、执行 live/draft 边界检查、选择 Store 打开模式并分发命令；
3. store、work、external_graph、codegraph、agent、mcp、trans 与 view 承担各自领域行为。

命令在标准输出返回结构化 JSON，在标准错误返回结构化错误。面向人的说明放在字段中，不会替换机器契约。

隐藏 worker 只是内部传输机制。用户只通过 work list、status、watch、cancel 与 resume 管理任务。

规范数据平面

每个 Wiki 只有一个 wiki.db。规范写入通过 SQLite transaction，把不可分割的记录一起更新：

• Source 快照与 pending ingest job；
• Page 正文、引用、provenance、链接、检索文档、spans 与操作记录；
• tag 策略与成员关系；
• 检索权重或基于 query fingerprint 的反馈；
• changeset 状态与 inverse 元数据。

Source 内容不可变并按内容寻址，Page 则是可维护、可更新的知识。二者通过 page_sources 明确关联，任何一方都不会暗中替代另一方。

Store identity 包含稳定 store ID 与持续变化的 revision fingerprint。Changeset、checkpoint、span 以及并发 restore 都依赖这些身份信息发现 stale 或错配状态。

派生数据平面

检索

Contentless SQLite FTS5 表保存规范化后的 Page、Source、passage 和 sentence terms。精确 span 记录保存 UTF-8 byte range 与内容指纹。Reindex 可以根据规范文档重建这些数据。

Markdown

.lwc/wiki/ 是为人类和 Markdown 工具生成的目录，不是另一条写入入口。物化时会先暂存文件再替换，因此失败可以恢复，也不会重新定义规范状态。

文档图

Grafeo 与 SurrealDB sidecar 接收规范 Page、Source、link、citation 与 semantic relation 的投影。Mutation 会把脏文档键追加到持久化 Work；graph verify 则比较当前 sidecar 与规范投影键和指纹。

CodeGraph

CodeGraph 索引的是检出项目文件，而不是 Wiki 记录。LWC 会在用户全局缓存中固定并校验一个 runtime 版本，同时把各项目数据库保存在 .lwc/codegraph。即使 MCP 通过同一个 lwc_explore 暴露两者，代码结构仍然是独立证据平面。

部署本地平面

以下状态控制当前安装，而不是 Wiki 知识：

• .lwc/config.json 与全局 ~/.lwc/config.json；
• Work 请求和进度文件；
• 文档图 sidecar；
• CodeGraph runtime 与项目索引；
• AgentTarget receipt 和宿主配置；
• 编译进二进制的 Viewer 资源。

因此，checkpoint restore 会替换 wiki.db，然后按照当前部署配置重建或重新排入派生投影。

Live 与草稿 Store

Changeset 是与某个 live store 和 base revision 绑定的稀疏 SQLite overlay：

.lwc/wiki.db                         live 规范 Store
.lwc/changesets/<name>.db           稀疏草稿记录
.lwc/changesets/draft-<name>/        隔离 Work 与图运行目录

草稿读取会组合 live 基线和 touched draft entities。Commit 不会替换整个 live 数据库，而是在 live write lock 下校验指纹并合并一个准确 patch。这样既能保留无关 live 写入，也能生成 touched-entity inverse。

读写边界

读取命令会以只读方式打开当前格式 Store。旧 Store 如果需要受支持迁移，会先通过可写迁移路径更新，再执行原请求。

Mutation 拒绝 --scope all。Deployment-local 配置、Viewer、checkpoint、CodeGraph 生命周期和文档转换如果无法加入草稿原子契约，也会拒绝 changeset selector。

MCP 被刻意限定为只读。缺少索引时只返回 readiness guidance 或 typed unavailable state；任何 MCP 请求都不会下载 runtime、启用图或修改记忆。

故障模型

LWC 把结果区分为三类：

1. 未发生规范写入： validation、conflict 或获取锁失败；
2. 规范成功： transaction 已提交，所有必要投影均已完成或成功排队；
3. 规范部分成功： 知识已提交，但图排队、清理或物化失败。

第三类会明确返回 canonical_committed 或 checkpoint_restored 等字段，并给出准确恢复命令。只有文档明确说明高层操作具备幂等恢复能力时，才可以重试它。

派生失败不能通过假装规范知识从未提交来回滚正确数据。反过来，Work 成功也不能代替最终图一致性校验。

安全边界

架构层防护包括：

• 对 Store、草稿、Work、配置与 sidecar 做规范路径校验并拒绝符号链接；
• 显式项目选择与 CodeGraph path 必须落在 project root 内；
• owned file 使用 create-new 或原子替换；
• Source ingest、转换参数和部分集成写入前执行 secret scan；
• Viewer 只监听 loopback，且只开放 GET/HEAD；
• MCP 只有一个只读工具，并验证显式项目路径；
• Agent host 通过 ownership receipt 与 marker-bounded block 精确更新。

这些措施不能把不可信本地账号变安全。LWC 假定当前进程已经获得用户授权，可以读取所选项目和用户级集成文件。

组件职责

组件	负责	不负责
Store	规范知识与 transaction invariant	外部图是否可用
Work	长任务的持久执行状态	规范业务判断
外部图适配器	投影、查询与校验	Source truth
CodeGraph 适配器	Runtime 固定与项目代码索引边界	Wiki 记忆
MCP	有界只读探索	初始化或 mutation
AgentTarget 适配器	官方宿主文件和 LWC-owned fragment	UI-only 设置或宽泛 trust approval
Viewer	本地查看	编辑、迁移或构建索引
Trans 适配器	安全子进程转换	自动 Source ingest

设计检查

新增能力前，应回答：

1. 哪一条规范记录能够证明该事实？
2. 新状态属于 canonical、derived 还是 deployment-local？
3. 哪个 transaction 能保证不可分割写入原子完成？
4. 派生状态如何重建和验证？
5. 规范提交之后、投影完成之前发生故障会怎样？
6. 哪个 scope 和 project boundary 授权这项操作？
7. 现有 Store、Work 或 AgentTarget 路径是否已经可以满足需求？

如果这些答案仍不清楚，这项变更就不应跨越架构边界。

下一篇：存储与数据模型