map-the-landscape

梳理全貌

建立有用的心智模型，而不是穷尽所有内容的目录。揭示让细节变得易于理解的结构：边界内包含什么、边界外有哪些事物、哪些关系至关重要、价值或数据如何流动、全貌为何如此，以及哪些地方仍存在不确定性。

设定观察范围

根据请求和现有上下文推断以下内容：

• **主题：**要梳理的主题、领域、生态系统或代码仓库。
• 模式：topic、repository；当必须将代码仓库置于更广泛的生态系统中时，使用 hybrid。
• **受众：**用户目前的知识水平和预期用途。
• **决策：**这份全貌梳理应帮助用户理解什么或接下来做什么。
• 深度：snapshot、standard 或 deep。
• **时间范围：**默认聚焦当前状态；如果历史有助于解释现状，则补充历史。

仅当主题或预期观察范围确实模糊时，最多提出一个澄清问题。否则，说明所选边界并继续。除非用户要求快速概览或深入研究，否则采用 standard 深度。

证据规范

让全貌梳理便于核查，同时避免写成研究论文。

• 将重要陈述标记为 Observed（直接从代码仓库文件中读取）、Sourced（有外部来源支持）、Inferred（根据证据推断）或 Unknown（证据不足）。
• 对于有关当前状态或易变主题的说法，浏览并引用权威来源。优先采用一手文档、规范、论文、代码仓库、发行说明和官方材料。
• 对于代码仓库相关的说法，先检查代码和本地文档，再依赖摘要。使用 rg --files、清单文件、入口点、配置、测试和近期历史，了解系统自身的术语。
• 不要把目录名称、依赖列表、搜索摘要、星标数或人气当作解释。应将证据转化为关系及其影响。
• 区分已实现的系统与其声明的意图。README 描述的是承诺；代码路径和测试展示的是实际约束。

工作流程

1. 确定全貌梳理的范围

用两到三行概述方向：

1. 用一句话建立心智模型：“X 是一种……，通过……将……连接起来。”
2. 说明边界：哪些内容在范围内、哪些与主题相邻，以及哪些明确不在范围内。
3. 说明组织问题或决策。

列出五到九个这份全貌梳理必须回答的关键问题。根据主题调整问题，而不是套用固定分类法。

2. 收集最低限度的证据

对于 topic：

• 确定规范术语、主要子领域、重要参与者和机构、核心产物或标准，以及主要资源或价值流。
• 了解足够的历史，以解释当前的分歧和默认做法。
• 查找不同学派、替代方案、互补因素、瓶颈、激励机制和正在发生的变化。
• 当新增来源只补充示例，而不再带来新的重要节点、关系或分歧点时，停止收集。

对于 repository：

• 阅读代码仓库指南、根目录 README、清单文件、顶层目录树、主要入口点、配置和有代表性的测试。
• 确定运行时单元、所有权边界、持久化状态、外部系统、公共接口以及构建和部署路径。
• 端到端追踪一个有代表性的用户流程或数据流。优先选择真实的纵向路径，而不是逐一阅读所有目录。
• 仅在近期历史有助于解释架构、迁移或尚未完成的变更时，才检查近期历史。
• 确保每个关键组件都有明确职责、关系，并至少有一个证据依据。

对于 hybrid，先梳理代码仓库，再围绕它呈现重要的外部依赖、标准、竞争者和用户。

使用 references/map-lenses.md 查找针对不同模式的观察角度、证据目标和输出模板。只选用能揭示该主题结构的观察角度。

3. 从中心向外构建

按以下顺序构建地图：

1. **中心：**核心工作、问题或不变量。
2. **内部系统：**直接执行该工作的各个部分。
3. **支撑层：**基础设施、工具、治理机制和提供支持的机构。
4. **外部生态：**用户、生产者、竞争者、互补方、监管者和外部系统。
5. **作用力：**推动系统发展的激励、约束、瓶颈、反馈回路和趋势。

对于每个主要节点，说明：

• 它的角色；
• 它连接到什么；
• 什么内容会通过该连接传递；
• 该连接为何重要。

合并角色相同的节点。省略孤立事实。重要关系清晰时，地图就完整了，不必涵盖每个名词。

4. 追踪流动与时间

至少说明一条端到端的流动：

• 主题模式：价值、资金、信息、权力、供应或注意力。
• 仓库模式：请求、事件、数据、控制、构建或部署。

然后简要说明其演变：

• 之前是什么样的？
• 什么改变了其结构？
• 哪些历史遗留约束仍然存在？
• 现在有什么正在变化？

只有在历史能够解释当今的边界、惯例、权衡或冲突时，才纳入相关历史。

5. 对全貌进行压力测试

综合之前，先审视草稿：

• 缺少了哪个重要视角？
• 是否描述了某个组件，却没有说明它的输入和输出关系？
• 是否把既定目标误当成了已实现的行为？
• 不同的源名称是否掩盖了底层相同的角色？
• 是否把一个流行示例误当成了整个类别？
• 如果哪项主张不成立，最可能彻底改变这张地图？
• 所选边界让什么变得不可见？

遇到分歧和未知之处时，应明确标出，而非刻意消除差异。如果证据支持多种合理的地图，就展示这些方案，并说明如何区分它们。

6. 解释全貌

先介绍最简单且有用的模型，再逐层展开细节。默认采用以下结构：

1. 一分钟看懂全貌
2. 边界与术语
3. 全貌地图：对于非简单系统，使用 Mermaid 图表
4. 各部分如何协同
5. 最重要的流动
6. 它如何发展至今，以及正在发生什么变化
7. 分歧点、权衡与盲区
8. 接下来要检查或了解的内容
9. 证据与未知之处

以文字说明为主，图表作为辅助。使用“发布”“调用”“资助”“存储”“治理”或“与……竞争”等直白的关系标签。不要制作比主题本身更难理解的复杂图表。

最后给出优先级明确的入门路径：

• 首先要检查的三个概念、文件或来源；
• 一条值得追踪的代表性流动；
• 一个应避免的常见误解；
• 一个值得调查的未决问题。

除非用户要求保存为文件，否则在聊天中返回地图。保存时，使用用户指定的路径；如果用户未指定，则使用 docs/landscape/<subject>.md。

深度控制

• **概览：**一分钟全貌、5–8 个节点、一条流动、三个后续步骤。
• **标准：**分层地图、8–15 个节点、历史、分歧点、证据和学习路径。
• **深入：**多张地图或多个缩放层级、相互竞争的模型、更多来源核实；必要时保存为文件。

如果用户需要投资级调研、详尽的比较，或需要广泛交叉验证来源后才能做出决策，应转入专门的深度研究工作流。本技能应专注于建立全貌和综合分析。

故障处理

• 如果代码库过大，先梳理一个垂直流程及其周边边界，再确定下一个缩放层级。
• 如果无法访问代码，应明确区分文档地图和实现地图，并列出尚未验证的内容。
• 如果无法访问当前网页来源，应使用可用的一手证据，标明时效性缺口，并避免声称内容完整。
• 如果主题过于宽泛，应选择并说明一个有用的范围，而不是给出浅显的百科全书式介绍。
• 如果用户提到的陌生术语可能指代多个主题，应在调研前询问具体指哪个主题。