code-understand

Code Understand — 按需架构焦点图

你即将开始处理一个尚不熟悉的代码库。与其四处搜索或随意阅读文件，不如让本地提取器生成一份焦点图：列出架构所依赖的核心符号并按重要性排序，每项都附有 file:line 引用和证据类型。只阅读它指向的内容——这是一张地图，不能代替阅读它引用的实际代码。

适用场景

• 修改不熟悉的模块之前——先了解哪些代码会调用它，以及它会调用哪些代码，再调整其结构。
• 用户询问代码库“X 是如何工作的”“更改 Y 会有什么影响”或“还有谁在使用这个函数”，而不是询问 Wiki。
• 即将进行大型重构，想要一份按重要性排序的关键文件列表，而不是阅读整个目录树。
• 已经有差异或一组已更改的文件，想在完成修改前了解其影响范围。

不适用于：为 Wiki 总结项目的功能（这属于 wiki-update 第 3b 步，它会在更大的同步流程中调用同一命令）——只有在你当前的工作需要焦点图，而不是要保存知识时，才直接使用此技能。

运行

obsidian-wiki code-understand --project <dir> [--backend auto|builtin|codegraph] \
    [--changed <file>...] [--since <sha>] [--max-symbols N] [--pretty]

• --project — 默认为当前目录。
• 不指定 --changed/--since — 将所有受 Git 跟踪的文件作为种子（扫描整个项目）。
• --changed <file>（可重复）— 将你已知相关的特定文件作为种子（例如，即将修改的差异中的文件）。
• --since <sha> — 将自某个 Git 引用以来所有更改的内容作为种子（例如 --since HEAD~5 或某个基础分支）。
• --backend — auto（默认）会在安装了 CodeGraph 时使用它，否则回退到内置提取器；指定 builtin 可强制使用不依赖外部依赖的路径，指定 codegraph 则要求使用增强后端（若未安装会明确报错，而不是静默降级）。
• --max-symbols — 限制焦点图大小（默认 50）；快速了解概况时设小一些，深入分析时调大。

**注意：**如果命令不可用或报错，请跳过它并回到常规探索方式（搜索/阅读）——它只是加速工具，不是依赖项。不要因此阻塞工作。

阅读输出

1. **证据类型很重要。**当 backend: codegraph 时，焦点图条目是结构性事实（真实的调用图边）——可直接引用。当 backend: builtin 时，defines/imports/changed-file 条目是事实，但 rg-reference 条目仅是文本匹配证据——将其视为真实关系之前，请打开文件进行确认。
2. **先打开引用所指的内容，不要先看其他内容。**焦点图会告诉你在哪里阅读；它不包含源代码正文。对架构形成看法之前，请先阅读这些 file:line 位置。
3. **在自己的输出中注明引用。**如果你要向用户解释架构，或将其写入 PR 描述/提交信息，请保留焦点图或所打开源代码中的 (file:lines) 引用——不要在没有出处的情况下断言代码结构。
4. **它是缓存，不是交付物。**绝不要将原始 JSON 或 .codegraph/ 写入 Wiki 库、PR 描述或已提交的文档——它是项目仓库中的临时附属数据（已被 Git 忽略）。下次需要时重新运行，不要把旧输出当作持久资料。

如果未安装 CodeGraph

auto/builtin 无需任何设置即可运行（使用正则 AST 提取器和 rg）。如果你需要增强的跨文件调用图证据，且用户同意安装：

npm install -g @colbymchenry/codegraph

或者将 CODE_UNDERSTANDING_CODEGRAPH_BIN 指向现有二进制文件。未经用户同意，绝不要安装——先询问，再重新运行命令。

查看 obsidian-wiki doctor --project <dir> 输出中的 code-understanding.* 能力项（builtin、rg、codegraph、codegraph-index、codegraph-fresh、codegraph-gitignore），了解可用功能，再决定显式请求哪个后端。