本章是 AITM 两种图视图的可视化指南：Contract Explorer（项目中所有 Behavioral Contracts 的地图）和 App Flow（某个特定应用元素与其他所有内容之间关系的地图）。内容包括：每张图展示什么、如何阅读节点、颜色和连线、图例的含义，以及这两种视图究竟有什么用途。
Contract Explorer & App Flow
如果尚不了解什么是 Contract 或知识图谱，请先阅读“Contracts、知识图谱与 Hints”。本章以此为基础，专注于如何浏览这两种可视化视图。
Contract Explorer — 项目的 Contract 地图
用途：Contract Explorer 是项目中所有 Behavioral Contracts 的交互式图 — 即关于代码各部分行为方式的已存储事实。在一个屏幕上即可看到 AITM 对项目掌握了多少知识、测试覆盖得如何、哪些模块最大，以及 Contracts 如何与文件、变量和文档相连。想回答“AITM 对我的项目了解多少？”以及薄弱环节在哪里（未测试或失败的 Contracts），这是最快的方式。
入口：在项目面板中点击 Contracts 子标签页（项目的子标签页包括 Develop、Testing、Archive、Setting、Optimize、Contracts、Graph 和 Multi Graph）。相邻的 Graph 子标签页绘制项目的代码图，Multi Graph 则将该标签页下所有项目一起绘制（仅当标签页中有多个项目时才会显示）。
屏幕上有什么
屏幕分为四个主要区域：
- 顶部栏 — 数据集标签页、汇总统计和操作按钮。
- 左侧边栏 — 搜索、模块筛选和 Contract 列表。
- 主图区域 — 交互式图（鼠标滚轮缩放，拖动平移，节点可以拖动）。
- 图例（图左下角的浮层面板） — 说明节点颜色和线型。
顶部栏：标签页与统计
| 元素 | 含义 |
|---|---|
| Contracts (数量) | 从代码派生的 Contracts — 图中显示的主要数据集。 |
| Doc Contracts (数量) | 从文档（Task 结果）中提取的 Contracts。此标签页显示列表而非图。 |
| Doc Pointers (数量) | 文档文件指向 Contracts 的引用 — 即“文档中哪里写到了这个”。 |
| Needs Review (数量) | 等待审核的 Contracts（例如置信度低，或在发生冲突的变更之后）。 |
| Total / Passing / Failing / Unknown | 健康度汇总：Contracts 总数、测试通过的数量、失败的数量、状态未知的数量。 |
| Coverage | 被测试覆盖的 Contracts 百分比。 |
| Fix Contracts | 启动对不一致 Contracts 的修复。 |
| Reimport | 从项目源码重新读取 Contracts（完全重新同步）。 |
显示层级：Module View 与 All Contracts
图的上方有一个详细程度切换器：
- Module View （大型项目的默认视图，Contracts 超过 500 个时） — 每个节点是一个完整的模块（例如“AI Chat”、“Backup Service”）。气泡大小反映模块中 Contracts 的数量；模块之间的连线表示它们共享源文件。这是“鸟瞰视图” — 理想的起点。
- 点击模块会下钻到 Module Detail — 图中显示所选模块的各个 Contracts。
- All Contracts — 一次性显示所有 Contracts 的完整图。在大型项目中，为了性能，节点数上限为 500（徽章会显示数量，并带有“Show all”链接，可有意绕过该上限）。
图的右上角还有一个渲染器切换器：SVG、Sigma （默认 — WebGL，可处理大型图）、3D、Cosmo 和 deck.gl。它不会改变功能，只改变图的绘制方式 — 如果大型项目中图出现卡顿，请选择 Sigma。
读图：节点
每个节点（圆圈）代表一个实体。颜色表示类型 — 对于 Contracts，颜色同时也表示测试状态：
| 节点颜色 | 类型 / 状态 | 含义 |
|---|---|---|
 绿色 | Contract — Tested (passing) | 该 Contract 有测试，且全部通过。 |
 红色 | Contract — Failing | 该 Contract 有失败的测试 — 请优先查看这里。 |
 琥珀色 | Contract — Untested | 完全没有测试的 Contract — 行为已有描述，但没有保护。 |
 蓝色 | Module | 模块（一组 Contracts） — Module View 中的主要气泡。 |
 灰色 | File | 被多个 Contracts 共享的源文件。 |
 橙色 | Doc (Doc Pointer) | 引用 Contracts 的文档文件。 |
 紫色 | Doc Contract / variable | 由文档派生的 Contract，或通信语言变量。 |
 青色 | Behavior Doc | 生成的行为描述文档。 |
节点越大 = 实体越重要（Contracts 更多的模块、危险区域 Contract 等）。
读图：连线（关系）
节点之间的连线表示“这两者相关”。关系类型通过线型来编码：
| 线型 | 关系 | 含义 |
|---|---|---|
| 实线 | Module → Contract | 该 Contract 属于该模块。在 Module View 中，线的粗细反映模块之间共享文件的数量。 |
| 细实线 | Contract → File / Variable / Doc | 该 Contract 涉及某个文件、管辖某个变量，或由某份文档描述。 |
| 紫色虚线 | DocContract → Contract | 文档 Contract 确认/扩展了代码 Contract。 |
| 橙色虚线 | Contract → Doc Pointer | 某个文档文件引用了该 Contract。 |
| 浅紫色虚线 | DocContract ↔ Doc Pointer | 文档 Contract 与 Doc Pointer 共享同一个 Contract — 即文档链。 |
实际读法：实线 = 代码中的关系，虚线 = 通过文档形成的关系。从某个 Contract 引出的虚线表示它有书面文档 — 点击橙色节点即可在应用内直接打开。
图例
图例（图左下角的面板）准确概括了上文所述内容 — 节点颜色和连接类型。对于 Contract 的三种状态，它还会显示实时数量和百分比（例如 Tested (passing) 4/2403 (0%)）：即当前显示集合中处于各状态的 Contracts 数量。这些数字会随当前筛选条件重新计算 — 在 Module View 中指屏幕上的模块，下钻到某个模块的 Contracts 后则指该模块的 Contracts。
左侧边栏
- Search — 在 Contract ID、行为描述、文件和变量中进行全文搜索。
- Filters / Groups — 在模块筛选（带模块名称的按钮；
All清除筛选）与分组树之间切换。 - Contract 列表（底部） — 显示所选模块的 Contracts。每一行都有一个彩色圆点，含义与图中节点相同（绿/红/琥珀），此外，处于危险区域（历史上小改动曾造成严重破坏的地方）的 Contracts 还带有
图标。
Contract 详情
点击某个 Contract（在图中或列表中）会打开 Contract 详情窗口：
| 部分 | 提供的信息 |
|---|---|
| 标题 + 徽章 | Contract ID（例如 DPL-001）、模块、状态（code-only = 从代码派生、无测试；tested = 有测试）以及健康徽章（unverified、passing、failing）。 |
| Behavior | Contract 本身 — 用一两句话精确描述行为（“这一部分做什么，以及在……时返回什么”）。 |
| Tests | 保护该行为的测试（文件 + 测试名称）。 |
| Files | 该 Contract 涉及的源文件 — 点击可筛选图。 |
| Variables | 该 Contract 管辖的通信语言变量（BL.*、UI.* ……）。 |
| Reliability Score | 该 Contract 的可靠性分数（综合了年龄、测试、变更历史）。分数低 = 对该信息应持保留态度。 |
| Related Tasks | 创建或修改过该 Contract 的 Tasks。 |
| Screenshot | 对于 UI Contracts，显示元素的预览（在 Pipeline 的 E2E 步骤中截取）。 |
| Change History | 该 Contract 何时、由哪个 Task 修改。 |
| Related Contracts / Documentation | 同级 Contracts（共享文件）以及引用该 Contract 的文档。 |
详情顶部有两个重要按钮：
Assembled doc — 打开该 Contract 的完整汇编文档。
Flow — 直接跳转到以该 Contract 的第一个变量为中心的 App Flow 视图（见下文）。这是两种可视化之间的桥梁：从“什么成立”（Contract）到“它如何融入应用”（流程）。
App Flow — 单个元素的关系地图
用途：Contract Explorer 从上方俯瞰整个项目，而 App Flow 回答的是“这一个特定元素与应用的其余部分有什么关系？”。你可以看到与该元素相邻的每一个通信语言变量 — 通过命名空间、共享的 Contracts、共享的文件以及 UI 导航产生关联。它是评估变更影响（“如果我改动这里，还会影响什么？”）和撰写精确 Task 提示词的理想工具。
入口：
- 从 Dev Panel — 在运行中的应用里点击某个元素；其详情窗口会打开，包含标签页 Graph | Guide & Flow | App Flow。
- 从 Contract Explorer — 通过 Contract 详情中的 Flow 按钮（见上文）。
屏幕上有什么
- 左栏 — 被检查元素的数据：名称、描述、层级，最重要的是管辖它的 Contracts 列表（含 ID、测试状态、健康度、文件和分数）。信息与 Contract Explorer 中相同，只是从单个元素的角度来看。
- 中间 — 图 — 交互式图，被检查的元素位于中心，相关变量环绕在周围。
- 右侧面板 — 关系类型筛选（复选框）和相关变量列表，以可读列表的形式对应图中内容。
读图：节点
| 节点外观 | 含义 |
|---|---|
| 带标签的矩形 | 变量 — 标签是点号表示法的最后一段（例如 BL.CODEMAP 显示为 CODEMAP）。 |
| 蓝色边框节点 | 被检查的元素 — 图的中心，即你点击的对象。 |
| 虚线边框 | Ghost node（幽灵节点） — 一个在屏幕上没有自身元素的业务逻辑变量（例如纯后端的 BL.* 变量）。点击幽灵节点会将其载入左栏，同样可以固定到提示词中。 |
读图：边的颜色（关系类型）
每条线的颜色取决于变量为何相关：
| 边的颜色 | 关系 | 如何产生 |
|---|---|---|
| 灰色 | namespace | 命名空间同级 — 共享点号前缀（例如 UI.PANEL.CHAT 和 UI.PANEL.BRAINSTORM）。表示“我们属于同一家族”。 |
| 琥珀色 | contract | 列在同一批 Contracts 上的变量 — 它们的行为受相同规则约束。这是进行影响分析时最有价值的关系。 |
 深灰色 | file | 其他 Contracts 中涉及相同源文件的变量 — 通过代码形成的关系。 |
| 蓝色 | navigation | 真实 UI 中的关系：点击此元素会显示/导航到目标元素（由已映射的 DOM 效果得出）。 |
右侧面板：筛选与列表
顶部有四个复选框 — Namespace、Contract、File、Navigation — 同时筛选图和列表。默认勾选 Namespace + Contract（最有用、噪声最少的关系）；需要通过代码或 UI 流程追踪关联时，再启用 File 和 Navigation。
列表的每一行显示变量代码、名称和关系类型徽章。
（插入提示词）按钮会将变量代码直接固定到你正在撰写的 Task 提示词中 — 因此典型工作流是：在应用中找到元素 → 查看其 App Flow → 固定相关变量 → 描述变更。这样 AI Agent 就能收到与变更相关位置的精确地址，无需自行搜索。
图例与帮助
图的左下角是图例，概括了节点样式和边的颜色（与上文所述完全一致）。右上角是 (?) 按钮，会打开帮助弹出框，说明 App Flow 显示什么，以及每种关系类型是如何得出的：
Guide & Flow — 业务逻辑流程
在 App Flow 旁边，元素详情还有一个 Guide & Flow 标签页。它以通俗的步骤自上而下地解释所选元素 — 先是 UI 元素本身，然后是描述其行为的业务 Contracts（每个都附有其涉及的变量） — 而 Copy as Markdown 按钮会将整段说明复制到剪贴板，便于直接粘贴到 Task 提示词中。
AITM Dev Panel
它是什么：一个小型浮动工具栏，AITM 可以将其注入到所管理项目的 Web 应用中。当你在浏览器中使用应用时，该面板就是 AITM 在应用内部的“眼睛”：它会记录所看到的带标记的 UI 元素（构建项目的屏幕、按钮和对话框地图，Contract Explorer 和 App Flow 即以此为基础绘图），并捕获浏览器控制台中的 JavaScript 错误并发送给 AITM，这些错误会显示在该项目中，并可转化为 Bug Tasks。
如何加载：该面板是由 AITM 服务器提供的一个脚本，在开发模式下被包含到应用页面中。New Project Wizard 会自动将其添加到它创建的 Web 项目中；AITM 自己的 Dashboard 也带有该面板。
界面内容：四个标签页 —
- Elements — 你点击或固定的元素，每个都带有其变量代码、背后的 Contracts 和文件，以及来自危险区域 Contracts 的警告。Overlay 高亮页面上所有带标记的元素；Pin / One Pin 为提示词收集元素；每行的图标可复制代码、打开该元素的详情（Graph、Guide & Flow、App Flow）以及移除固定。Clear Pins 清空列表。
- Records — 面板从页面记录下来的 UI 元素。
- Errors — 在此浏览器中捕获的 JavaScript 和控制台错误，标签名中带有数量。
- Settings — 面板自身的选项。
该面板仅在开发模式下出现，面向开发者和 AI Agents，而非应用的最终用户。其完整文档可从标题栏菜单打开：Help → AITM Dev Panel。面板的字体大小可在 Settings → Font & Style 中调整。
实用工作流
找出模块的薄弱环节：Contracts → Module View → 点击某个模块 → 在图中查找 琥珀色（未测试）和 红色（失败）节点。图例可让你一眼看到百分比。
在提交 Task 之前评估变更影响：通过 Dev Panel 在应用中找到该元素（或在 Contract Explorer 中找到某个 Contract 并点击 Flow 按钮） → App Flow → 启用 contract 和 file 关系 → 所有相连的内容都可能受到变更影响。
撰写精确的提示词：在 App Flow 中，将相关变量固定 到提示词中 — 这样 Task 使用的就是你与 Pipeline 的 AI Agents 双方都能理解的语言（通信语言）。
检查行为是否已有文档：在 Contract Explorer 中，沿着某个 Contract 的虚线查看 — 它们通向文档（橙色节点），点击即可在应用内直接打开。