Basic Concepts zh CN

基本概念

语言： English · 简体中文

本页解释 LWC 文档中的常用术语。只要分清规范知识、派生索引和 Agent 工作流，大多数操作误区都能提前避免。

Wiki

一套 LWC Wiki 由一个 SQLite 数据库及其可重建的本地投影组成。数据库保存不可变来源、Agent 维护的页面、引用、来源证明、链接、ingest 状态、检索状态和操作历史。

数据库是规范数据源。不要手工编辑 wiki.db、WAL 文件、生成的 Markdown、Work 记录、changeset 数据库或图存储侧车文件。

作用域

作用域决定知识应当存放在哪里。

作用域	含义	典型内容
project	从当前目录向上发现的最近一套项目 Wiki	仓库架构、本地决策、运维手册和项目来源
global	当前用户跨项目使用的 Wiki	稳定偏好和可复用实践
all	项目与全局记忆的合并只读视图	有界搜索、上下文、标签列表与强标签载入

all 不是规范写入目标。读取命令如果要启用可选记录模式，应先明确选择 project 或 global。日常项目工作应当直接在项目目录执行 lwc。只有某条命令需要明确指定项目边界时才设置 LWC_PROJECT_ROOT；不要把它导出成日常环境变量。

Purpose 与 Schema

每套 Wiki 都有两份持久治理文档：

• Purpose 说明 Wiki 的目标、关键问题和范围。
• Schema 定义页面类型、来源证明规则、链接约定和维护要求。

Agent 在有界召回和来源整合时会收到这两份文档。它们用于约束知识维护，但不能覆盖系统、用户、仓库或宿主的安全指令。

Source（来源）

Source 是经过筛选的不可变 UTF-8 证据快照。LWC 使用 SHA-256 识别相同内容，同时独立记录每一次观察到的路径版本。

加入来源不等于完成知识整合。该操作只会创建一个 pending ingest 任务。Agent 仍需读完来源、完成分析、更新 Wiki，最后结束这项任务。

Page（页面）

Page 是由 Agent 持续维护的知识，包含：

• 稳定 slug；
• 标题和单行摘要；
• source、concept、entity、query、comparison 或 synthesis 等类型；
• Markdown 正文；
• 对 Source 的引用；
• 不来自不可变 Source 时使用的显式来源证明；
• 指向其他 Wiki 页面的链接。

kind=source 页面负责概括单个来源，便于导航和追溯。共享知识应进入非 source 页面，这样后续证据可以修订同一概念，而不是继续堆积孤立摘要。

来源证明与引用

来源证明说明页面中的声明为什么可信。

值	含义
source-grounded	页面引用一个或多个 Source ID 后由系统自动推导
user-provided	持久事实或决策由用户明确提出
agent-observed	Agent 根据当前已授权证据完成核验
hypothesis	有调查价值但尚未验证的可能性，必须明确标注

不要伪造 Source 引用，也不要把密钥、隐藏推理或无依据猜测保存为事实。

Ingest 任务

Ingest 任务是一套持久状态机，负责把单个来源转化为可维护知识：

pending -> analyzing -> generating -> completed
                      \-> failed -> pending（重试）

正常完成时，既要有引用该来源的 source 摘要页，也要有引用该来源的非 source 页面。如果来源确实没有带来新的共享知识，应记录具体、可审计的原因，而不是制造无意义页面。

Search、Context 与 Span

• context 在固定上限内返回 Purpose、Schema、页面索引和最近操作。
• search 使用确定性的词法检索，默认优先返回已维护页面，再回退到原始来源。
• span 用于解析精确的句子或段落定位，并扩展附近上下文。

Span 定位包含文档指纹。页面发生变化后，旧定位会返回 stale_span；LWC 不会静默映射到看起来相似的新文本。

链接与文档知识图

Wiki 链接表达页面之间经过维护的关系，引用负责连接 Page 与 Source。LWC 可以把这些事实和显式语义关系投影到可选的文档图中。

图是派生索引。只有在需要遍历、路径、邻居、影响分析或可视化探索时才值得启用。graph verify 用来比较图投影与 SQLite 规范状态是否一致。

CodeGraph

CodeGraph 是独立的项目级当前代码索引，用来回答文件、符号、定义、调用方、被调用方、依赖和影响范围等问题。它不是文档图，也不会作为第二个 Agent MCP 单独注册。

运行时按用户和版本全局下载一次；每个项目在 .lwc/codegraph 下保留自己的索引。

词图网

词图网通过共享分词连接文档。由于词项关系极其稠密，LWC 不允许单次请求加载完整词网。查询必须限制词项数量和文档数量，并使用分页与服务端上限。查询结果是用于探索的有界样本，不应被理解为完整语义图。

强标签

强标签是少量核心页面的显式成员列表。lwc load tag 先按优先级和数量上限选出成员，再完整返回每一篇选中的页面。

它适合必须稳定载入的规则和手册，不是搜索关键词，也不会根据词频自动推断。

Changeset

Changeset 是一套隔离的稀疏草稿，用于暂存涉及多项写入的同一逻辑变更。Agent 可以先检查、搜索并 lint 草稿，再进行原子发布。

提交时会记录受保护的逆向补丁并返回 changeset ID。只有相关 live 实体尚未再次变化时，才能立即回滚；不存在强制回滚选项。

Work

Work 是用于图投影和维护任务的持久后台工作记录。命令返回 Work ID 只说明任务已经排队，进程退出不代表任务完成。

应使用 work status 或 work watch，并确认 state=succeeded。失败或取消的 Work 会被保留以供检查，部分任务可以显式恢复。

Checkpoint

Checkpoint 是经过验证的完整 SQLite 备份。恢复操作会先把当前 Wiki 保存为安全 checkpoint，再执行恢复并重建派生材料。无法放入 changeset 的大型直接维护操作，应先创建 checkpoint。

Agent 集成

LWC 的 Agent 集成主要包含四类能力：

• MCP： 通过一个只读 lwc_explore 工具有界探索记忆、代码或两者的组合；
• Skill： 教 Agent 判断何时以及如何使用 LWC；
• Hook： 在宿主支持的生命周期事件中提供有界 readiness 与强标签上下文；
• Instructions： 在宿主官方的全局或项目指令文件中写入带边界标记的指导段。

AgentTarget 适配器只安装各宿主官方支持的能力；由 UI 管理、处于预览状态或不支持的部分都会被明确报告。

下一篇：应用场景