Graph Projection and Performance zh CN

图投影与性能设计

语言： English · 简体中文

LWC 会把规范知识投影到文档图 sidecar，并对图、recall 与派生工作设置明确边界，而不是把全部文档、token 或 edge 一次性装入内存。该设计面向本地 Agent 工作流，使用一个规范 SQLite writer 与可重建索引。

提高 limit、新增后台任务，或打算把 LWC 当成 hosted multi-user database 之前，应先阅读本页。

目标运行模型

LWC 针对以下场景优化：

• 一个用户或 Agent process 协调本地 Wiki 写入；
• 偶尔 mutation，中间进行大量有界读取；
• project 与 global 知识分开保存；
• 昂贵投影通过显式后台 Work 执行；
• 不引入模型与网络延迟的确定性检索；
• 可以从规范状态重建索引。

它不是水平分布式知识服务。多台独立机器如果需要同时写入并提供远程租户隔离，LWC 的本地 Store 就不应承担同步层职责。

所有读取都必须有界

公开 list、search、context、graph、log、lint、Work 与 tag 命令都要求或强制 limit。Candidate generation 只会在硬上限内适量 overfetch，再确定性筛选和截断。

--scope all 最多合并 project 与 global 两个读取结果，不会扫描任意项目。MCP 还有更严格的响应预算，Agent 无法通过一次 tool call 拉取整个 Wiki。

响应出现 has_more 或 truncated 时，应翻页或缩小 query。问题范围不清晰时，第一反应不应是提高全局上限。

稀疏 Changeset

changeset begin 只保存 touched entity 与 base fingerprint，不复制 live 数据库。Draft lint 与 search 会只读 attach live 基线，再叠加 delta。

因此，纯标签或少量多 Page 更新的成本只与变更面相关。每个 draft 仍拥有隔离 Work 与 graph sidecar，不能为了节省存储牺牲隔离。

持久 Work 与合并

Schema migration、maintenance 和 document-graph projection 在发起终端之外运行。每个 Wiki 同时只允许一个 active state-changing Work，避免重任务互相争用。

Graph mutation 会把 document key 追加到去重 pending set。活动 projector 会连续消费多个 batch，因此一批 Page 写入不会为每个 Page 启一个进程。失败时，尚未处理的 key 会放回队列。

这种设计改善 throughput，同时保持 canonical read 可用，但不能省略对最终 Work 的 watch 与图 verify。

控制词图密度

Token membership 是产品中最密集的关系。因此，LWC 永远不会持久化或返回一张全局词网。

每次请求受到以下边界约束：

• 最多 8 个 query term；
• 每个样本页 25 个 candidate document；
• 30 个 selected term；
• 200 个 node、500 条 edge；
• 最多检查 4 MiB 内容；
• 每个 document 最多检查 4 个 span；
• pagination offset 上限为 10,000。

系统先通过 FTS 选择 candidate，再只对已选 metadata 和 span 分词，并同时应用 byte、node、edge 与 term budget。响应会报告 diagnostics 和 truncation reason，不会默默假装结果完整。

控制检索成本

Document 与 span search 最多接受 64 个 normalized query term。Candidate overfetch 为请求 limit 的 4× 或 8×，并限制在 1,000 以内。Filter、adjustment、graph reranking、grouping 与最终排序都只处理这组有界 candidate。

Markdown segmentation 对单个 passage、sentence 字节数和每份文档总 span 数设有上限。准确 UTF-8 range 避免为每个 span 复制第二份正文。

FTS row 与 span 会在规范 Page 或 Source transaction 内更新，普通 search 不会顺便进行全量 reindex。

控制图投影成本

文档图 mutation 以 dirty document key 做增量投影。只有启用引擎、checkpoint restore、修复或显式配置变化时才做全量 projection。

Graph query 对 depth 与 result count 有界。Viewer 还会把可视图限制为 1,000 个 node 和 5,000 条 edge。graph verify 通过 fingerprint 与 key set 判断一致性，不会把查询成功当成完整性证明。

Grafeo 与 SurrealDB 是两个可替代的派生引擎；同时启用两者只会重复成本，不会增加规范持久性。

CodeGraph 复用

固定 CodeGraph runtime 按用户、版本和 target 缓存一次。第二个项目会复用已校验 runtime，但仍构建自己的索引。

索引写入会完整提交当前 owner file，再处理下一文件，因此更新期间原图仍然可读。Viewer 直接读取已有数据库，绝不唤醒索引过程。

Runtime 复用消除了重复下载，但不会合并项目索引或放松 project path containment。

SQLite 并发

WAL mode 允许 reader 在 writer commit 期间继续读取。写路径使用 transaction 与有界 busy timeout，不会永久等待。

另一 writer 占用相关边界时，应预期出现 database_busy。根据返回的 delay 重试，禁止加入无界 loop 或绕过 revision check。Changeset commit 与 checkpoint restore 会刻意拒绝 stale observation，而不是以牺牲正确性换速度。

文件系统成本

生成 Markdown 与状态文件采用暂存替换。Maintenance compact 通过持久 Work checkpoint 并截断 WAL。Checkpoint 是完整数据库副本，因此保留成本随数据库大小和快照数量增长。

不要为每次写入调度 checkpoint。只保留与真实运维边界对应的命名恢复点，并且只按明确 retention policy 清理。

调优前先诊断

优先使用已有证据：

lwc --scope project work list
lwc --scope project graph status
lwc --scope project graph verify
lwc --scope project search "slow query terms" --limit 10 --explain
lwc --scope project lint

词图查看 diagnostics、limits 与 truncation_reasons；CodeGraph 要区分 runtime installed 与 project initialized；mutation 缓慢时，先定位 Work phase 再修改系统级边界。

扩展实践

• 项目事实放 project Wiki，可复用实践放 global scope；
• 把共享知识整合进维护 Page，避免累积重复 source summary；
• 使用稳定 title、summary 与术语，减少 lexical retrieval 所需 candidate；
• Strong tag 只用于少量确定性核心内容；
• 优先增量 graph projection，只在恢复或引擎切换时全量重建；
• 对密集 Word Graph 与 list view 分页；
• 保持 Source 精选，LWC 不是 raw log warehouse；
• 只有测得真实 ceiling 后才修改常量。

已知上限

架构上限是本地 SQLite writer 与本地派生索引。这让安装、审计、备份与恢复保持简单，也意味着高写入 multi-tenant service 需要不同的 canonical store 和协调协议，而不是更大的 --limit。

下一篇：配置参考