Common Workflows and Recipes zh CN

常用工作流与实战配方

语言： English · 简体中文

本页把 LWC 的单项命令组合成可重复执行的 Agent 工作流。应选择与任务匹配的最小配方，始终明确 scope，并以实际证据收尾，不能因为任务已经排队就假定完成。

在合适的时机使用 LWC

当本次工作产生了需要跨会话保留的知识时使用 LWC，例如：已经验证的架构结论、运维规则、有来源支撑的解释、会反复出现的调查，或者后续任务依赖的关系。

临时命令输出、未经验证的猜测、原始思维链、秘密，以及一次廉价查询就能重新得到的结果，不应写入持久记忆。

配方：建立项目记忆

项目还没有 Wiki 时执行一次：

lwc --scope project init
lwc --scope project purpose show
lwc --scope project schema show
lwc --scope project lint

从项目根或其子目录执行。初始化不会启用文档图、安装 CodeGraph，也不会选择转换引擎。只有项目确实受益时，再分别向用户介绍这些可选能力。

验收标准：lint 正常完成，scope 指向目标项目，Git 中没有意外加入无关仓库文件。

配方：把一份文档整合成可维护知识

lwc --scope project source add docs/design.md --title "Design source"
lwc --scope project ingest claim <source-id> --source-max-chars 100000
lwc --scope project ingest analyze <source-id> --file analysis.md
lwc --scope project page put source-<source-id> \
  --title "Design source summary" --kind source \
  --file source-summary.md --source <source-id>
lwc --scope project page put project-design \
  --title "Project design" --kind concept \
  --file project-design.md --source <source-id>
lwc --scope project ingest complete <source-id>
lwc --scope project lint

写结论之前必须读完全部 Source window。来源摘要 Page 回答“这份证据说了什么”，共享 Page 回答“项目当前知道什么”。同一主题已有共享 Page 时应更新它，不要按文档数量机械拆页。

验收标准：ingest job 为 completed，共享 Page 引用了该 Source，lint 干净，并且两条固定的自然语言检索都能把目标 Page 排在前列。

配方：调查前先召回已有结论

lwc --scope project context --limit 25
lwc --scope project search "how does release recovery work" --limit 5 --explain
lwc --scope project page show release-recovery

先搜索，再打开完成决策所需的准确 Page 和引用 Source。只有可复用的全局知识确实相关时才用 --scope all，不要把整个 Wiki 一次性塞进上下文。

如果发现已有知识过期，应在核实现状后修正它，而不是绕过旧结论另答一遍。

配方：保留已经验证的答案

某项调查很可能再次出现，且答案还不适合并入稳定 concept Page 时，可以写成 query Page：

lwc --scope project page put why-release-retries-are-safe \
  --title "Why release retries are safe" --kind query \
  --summary "Verified retry and idempotence boundaries" \
  --file verified-answer.md --source <source-id>
lwc --scope project lint

应保存结论、证据、成立条件和已知不确定性，而不是保存调查过程的聊天记录。

配方：不依赖搜索，强载入必须规则

lwc --scope project tag set rules release-policy \
  --priority 100 --reason "Mandatory release boundary"
lwc --scope project tag autoload rules --enable \
  --priority 100 --limit 10 --max-chars 50000 \
  --reason "Load reviewed project rules at lifecycle boundaries"
lwc --scope project load tag rules --limit 10

强标签只适合少量、高度相关的核心 Page。标签成员关系不能代替搜索分类，autoload 也不适合装入整本手册。

验收标准：返回的是完整 Page，按成员 priority 排序，没有超过字符预算，并且每一页都适合进入所有目标会话。

配方：调查文档关系

lwc --scope project graph status
lwc --scope project graph verify
lwc --scope project graph neighbors page:project-design --limit 50
lwc --scope project graph path page:project-design source:<source-id> --max-depth 4
lwc --scope project graph impact page:project-design --max-depth 4 --limit 100

只有用户同意后才能启用文档图，依赖遍历结果之前必须先验证。只有 citation 和 Wiki link 无法表达、且已经人工核实的含义，才应写成显式 semantic relation。

配方：调查代码结构

lwc --scope project cg status
lwc --scope project cg init
lwc --scope project cg status

随后由 Agent 通过 lwc_explore 的 code mode 查询符号、调用方、被调用方、依赖关系或影响范围。CodeGraph runtime 会在用户级复用，索引则属于具体项目。只有 status 表明索引缺失或失效时才重新初始化，不要每次查询都执行 init。

配方：转换一份已审核的外部文档

lwc --scope project config show
lwc --scope project config set --trans markitdown
lwc --scope project trans docs/report.docx --output converted/report.md

转换只会创建 Markdown 文件，不会自动摄取。先审核输出；只有内容经过授权、确有价值且不含秘密时，再把它加入 Source。已有输出绝不会被覆盖。

配方：原子发布一组知识更新

lwc --scope project changeset begin operations-update
lwc --scope project --changeset operations-update page put operations-policy \
  --title "Operations policy" --kind policy \
  --file operations-policy.md --source <source-id>
lwc --scope project --changeset operations-update lint
lwc --scope project changeset show operations-update
lwc --scope project changeset commit operations-update
lwc --scope project graph verify

多条命令必须同时可见时使用 changeset。稀疏草稿通过 overlay 读取未改动的 live 知识。发生冲突时从最新 live 基线重新处理，不能用跳过 lint 的方式掩盖 overlay 缺陷。

配方：恢复派生投影

lwc --scope project lint --limit 100
lwc --scope project work list
lwc --scope project maintenance materialize
lwc --scope project work watch <work-id>
lwc --scope project lint

搜索索引漂移时选择 maintenance reindex；图漂移时重新应用已经选定的 graph 配置。只有规范 Wiki 状态本身需要回到旧时间点时，才使用 checkpoint restore。

通用完成模式

每个配方最后都要回答四个问题：

1. 命令是否作用于正确 scope 或 draft？
2. 返回的 Work 是否都到达 succeeded？
3. Canonical readback 是否与预期一致？
4. 适用时，lint、固定检索和 graph verify 是否全部通过？

命令细节参见 CLI 与配置参考，发生故障时使用故障排查与常见问题。