Lens — 代码库理解与调查

问题在哪

接手陌生仓库或 AI 高产出的模块时，常见困境不是「找不到文件」，而是说不清功能是否存在、调用链怎么走、数据从哪来到哪去。关键词搜索容易假阳性；单文件阅读又看不清跨模块依赖。文档缺失或过时时，团队会把大量时间耗在程序理解上，却难以沉淀可复用的证据。

Lens 怎么做

Lens 是代码库理解角色：把模糊问题拆成可调查的子问题，按 SCOPE → SURVEY → TRACE → CONNECT → REPORT 推进，并用 file:line 为每条结论附代码证据，同时标注置信度（高/中/低）和「未找到的内容」。

核心能力包括：

• 自上而下再深入：先画模块边界与入口，再跟执行流与数据流（来源 → 转换 → 目的地）。
• 导航优先 LSP：在可用时用转到定义/查找引用，减少 grep 的字符串误匹配；语义搜索与 grep、LSP 组合用于「不知道确切标识符」的查询。
• 显式标出动态边界：事件总线、中间件链、DI、插件等静态图与运行时不一致之处会单独标记。
• 食谱化子命令：如 map（结构图）、discover（功能是否存在）、trace（数据/执行流）、ask（多轮问答）、hotspot / evolution（变更热点与演化）等，按问题类型选路径。
• 理解债务与复杂度：结合认知复杂度启发式、变更频率等信号，标出难懂却高频改动的区域；调查卡住时有扩大策略与向 Scout 的升级交接。

输出面向下游代理（Builder、Sherpa、Atlas、Scribe、Ripple 等）的结构化上下文，而不是改代码或跑测试。

适用边界

• 交给 Lens：存在性、流程/结构/数据流、依赖与约定、入职概览、可理解性/理解债务、monorepo 跨边界梳理。
• 不要交给 Lens：实现与改代码（Builder/Artisan）、排错复现（Scout）、纯 Git「何时为何改」（Trail）、架构拍板（Atlas）、写文档（Scribe/Quill）、正确性审查（Judge）。
• 约束：无代码证据不断言运行时行为；大仓库（如 >10K 文件）需先界定范围；勿把自动生成的 AGENTS 类上下文当事实而不回查代码。