zoom-out

zoom-out

在深入实现或详细说明之前，先为陌生的代码区域绘制一张有依据的地图。

决策树

用户想要什么？

• “拉远视角”“上升一个层级”“梳理相关模块和调用方”“谁调用了这个”，或类似的方向梳理请求 使用此技能。先绘制代码上下文地图，再提出建议。

• 指定了某个符号、文件、路由、任务、表、命令、事件或组件 追踪直接调用方、直接被调用方、入口点和边界跨越。如果候选地图能补充已有证据，则使用清单辅助工具。

• 指定了某个功能或子系统，但没有明显的具体入口点 先查找可能的入口点：路由、命令、任务、公共导出、UI 屏幕、处理程序、测试、迁移和包清单。

• 用户问“这是如何工作的？”，想要的是讲解而不只是方向梳理 如果对该区域不熟悉，先绘制地图，然后使用 {{ skill:eli12 }} 给出讲解式的最终说明。

• 用户要求修复 bug 或实现功能，但编辑目标不明确 先快速拉远视角梳理，再在相关代码范围明确后切回常规编码模式。

• 用户只需要文本搜索、字面匹配次数统计或文件名查找 直接使用 {{ skill:ripgrep }}，不要绘制架构地图。

• 用户要求记录持久的仓库意图或产品用途 此技能不适合。它梳理代码拓扑，而非人的意图。

快速参考

需求	操作
围绕符号或路径生成可选候选清单	python3 scripts/zoom_out_inventory.py --repo <repo> --target "<symbol-or-path>" --json
生成人类可读的清单	python3 scripts/zoom_out_inventory.py --repo <repo> --target "<symbol-or-path>"
完整发现方法	阅读 references/discovery.md
调用方和被调用方追踪规则	阅读 references/caller-mapping.md
最终答复格式	阅读 references/output-contract.md 或复制 templates/zoom-out-map.md
隐藏边界情况	阅读 references/gotchas.md
验证技能包	在技能目录中运行：python3 scripts/validate.py .
运行本地打包和探测测试	在技能目录中运行：python3 scripts/test_skill.py .

默认工作流

1. 将目标重述为具体对象：符号、路径、路由、功能、任务、包或子系统。
2. 确定仓库根目录以及用户提供的范围边界。如果缺少目标且无法从上下文推断，则提出一个简短问题。
3. 如果候选发现能提供有用证据，则使用 scripts/zoom_out_inventory.py。已知路径或有针对性的搜索可能就足够；辅助工具的输出只是线索，并非证明。
4. 根据已有证据选择搜索方式：精确标识符、文件名片段、路由片段、测试名称、配置键、表名、队列名、事件名或 API 路径。若直接查看已知目标是最有用的下一步，就直接阅读。
5. 找出核心文件：解释谁定义、编排或暴露该行为所需的文件，不限文件数量。
6. 向上和向下各追踪一层：
   • 上游：调用方、路由、命令、任务、事件订阅者、测试、UI 屏幕、公共导出。
   • 下游：服务、数据访问层、适配器、外部 API、队列、存储、功能开关、配置。
7. 按职责对文件分组，而不只是按目录分组。
8. 区分观察结果和推断。如果调用路径仅基于文本匹配，在验证执行连线之前应明确说明。
9. 返回简洁的地图。不要列出找到的所有文件。
10. 如果用户计划修改代码，最后列出最精简且有用的后续阅读清单或实现目标。

输出约定

在有帮助时使用以下章节。省略会增加冗余的章节。

• 目标 - 正在映射的符号、文件、路由、功能或子系统。
• 单层映射 - 按职责分组的相关模块映射。
• 调用方路径 - 执行如何从用户操作、作业、命令、测试或公共 API 到达目标。
• 被调用方与依赖项 - 目标调用、持久化到、发布到、导入或委托给的对象。
• 边界 - 跨越的所有权、软件包、进程、网络、持久化或框架边界。
• 证据 - 使用的文件路径、符号、搜索查询和命令。
• 未知项 - 动态分派、生成代码、框架注册或缺失的运行时证据。
• 后续阅读 - 接下来要检查的最短有序文件列表。

阅读指南

情况	阅读
需要在追踪前找到正确的入口点	references/discovery.md
需要判断什么算作调用方、被调用方或边界	references/caller-mapping.md
需要带证据和不确定性标签的一致最终映射	references/output-contract.md
结果嘈杂、缺失、动态生成或由框架驱动	references/gotchas.md

注意事项

1. 目录树不是架构映射。应展示职责和执行路径，而不只是文件夹。
2. 文本匹配只是线索，并非已验证的调用方。将路径作为真实路径呈现之前，应确认导入、注册、路由、测试或运行时连线。
3. 动态系统会将调用路径隐藏在配置、装饰器、依赖注入容器、生成代码、队列、约定和框架注册中。
4. 有用的范围通常是向上一层、向下一层。扩展到包含所有依赖项会降低映射的实用性。
5. 不要掩盖不确定性。明确指出“可能是调用方，但未经验证”，胜过给出自信却缺乏依据的图示。

辅助脚本

• scripts/zoom_out_inventory.py 会生成初步清单，其中包括候选中心文件、候选调用方、导入边、目录簇、清单文件和建议阅读内容。
• scripts/validate.py 会检查结构、frontmatter、交叉引用、必需目录、evals 和 Python 语法。
• scripts/test_skill.py 会运行验证、eval 覆盖率检查、交叉引用检查，并使用临时仓库探测清单脚本。

验证说明

维护此软件包时，请使用 --help 验证命令语法，并运行 scripts/test_skill.py。该脚本会构建临时代码库，并确认清单辅助脚本能返回目标匹配项、候选调用方、导入边和建议阅读内容。这些是软件包维护检查，并非每次缩小映射范围时的前置条件。

指南不再适用时

如果辅助工具或内置的追踪假设遗漏了真实连线，请遵循仓库注册方式以及已安装框架的官方文档或主要源码。如果无法获得运行时证据，请明确标注未经证实的边。提出规范的技能修正时，应提供遗漏路径、来源/版本和一个简短的反例；不要悄悄修改已安装副本，也不要用泛泛的框架说法取代观察到的应用行为。