# 技术图谱与 Agent 读图：一套可落地的协作方案 2026-05-28 · 系列《AI 编程可闭环协作》卷二 --- ## 为什么需要先搞懂“怎么读图”？ 如果你还没读过卷一的《怎样才算做完》，不妨先花十分钟翻一翻。那里已经把“图谱 + 协作流程”的叠放关系讲清楚了——意图是什么、成果长什么样、验收怎么算一轮交付。卷一还提到了一个关键点：**技术图谱** 存在的意义，就是替 Agent 回答“改哪里、会影响谁”这两个问题。 所以这一卷只展开图谱这一条轨道。我们会先搞清楚仓库里到底有哪些图谱文件——流程图、表结构说明、入口清单、机器总图，然后看第一份图从哪来，为什么流程图会有 .md / .ai.md / .json 三种形态，Agent 默认是怎么读图的（查询子图 + 清单便签，而不是整仓灌 Mermaid），以及图谱相关的 CI 门禁在合并流程里扮演什么角色。 至于协作流程和合并签收，那是卷三的事。有地图没有签收，照样不敢合并。 --- ## 8. 技术图谱到底是什么 ### 8.0 与卷一的衔接 卷一 §2.1 的“主图 + 子图”是本卷的锚点。如果还没看过，建议先去扫一眼那段多模块 API 主链路的示意图，再回来看下面的内容。  ### 8.1 仓库里的技术图谱：先认识这些文件 先别想太多抽象方法论。技术图谱在工程上其实就是：**仓库里的一个专用文件夹**（比如 `docs/_tech_graph/`，名字可以自己定），里面放的是“帮 Agent 改代码用的地图和清单”——不是产品 PRD 全文，也不用来替代 README。 图谱夹里常见的东西有这么几类： **主流程图（人读）**：这就是鸟瞰图。用户请求从哪进来、分几条业务大路，一目了然。主要给人看，Review 和讨论的时候用。 **分册流程图（人读）**：主图上某一格（比如“RAG 召回”）展开成详细步骤。同样给人看。 **流程图（导出用原稿）**：和上面同一套流程，但边、分支、对应代码位置写得更规整，供脚本读取。人是维护者，脚本是消费者。 **机器总图**：把多篇导出用原稿编译成一份总图，包含节点、连线、代码锚点。**不要手改这个文件**，它是给 Agent 查询用的。 **表结构说明**：数据库的表、字段、关系，通常用类图表示。改表、改向量维度的时候必须翻。 **入口清单**：可从外部触发的功能入口索引。API 项目常列路径和 handler；CLI 或库则列命令、公开函数、模块入口与代码锚点。改路由、改入口、对照“从哪进代码”时用。 **契约清单（可选）**：跨服务约定，比如流式返回字段、错误码形状。改 BFF 或前后端契约时用。 **实现规约**：环境变量、禁止编造、与代码一致的约束。改配置、改关键路径前必看。 **两个容易搞混的概念**： `graph.json`（机器总图）不是让人逐字阅读的文档，而是“印刷好的大地图集”。它由 `*.ai.md` 通过脚本导出得到。Agent 默认不会把整份 JSON 塞进对话（太大了），而是按入口查一小段——比如从 RAG 这一节点往下看两步，这在 §8.4 里叫查询子图。改图的时候，改 `*.ai.md` 即可，再重新导出；**千万不要直接改 `graph.json`**。 `01_struct`（表结构说明）就是“数据库地图”。它和 `graph.json` 不是一回事，不能因为有了总图就删掉它。 入口清单和契约清单与机器总图也不一样。机器总图描述流程与调用关系，入口清单描述有哪些对外的“门”。可以这样理解：GPS 路网是总图，公交站牌表是入口清单，路口规则是契约清单。 表结构、契约、机器总图可以第二步再补。入门时先凑齐最小图谱夹就能开工。 #### 最小图谱夹长什么样 假设你有一条核心链路（比如登录、入库），最小图谱夹只需要三个文件： - `00_main.md`：主流程图（人读），一页鸟瞰 - `10_flow_xxx.md`：分册流程图（人读），主图上某一格展开 - `_manifest.json` 或表格：入口清单 有导出脚本之后，再补 `*.ai.md` 和 `graph.json`。 #### 三类逻辑信息 把文件名称忘掉也没关系，记住三类逻辑信息就行： **流程**：先走哪、再走哪、有哪些分支。落在 `*.md`、`*.ai.md` 上；Agent 查询 `graph.json`。 **结构与依赖**：改 A 会不会牵动表 B、模块 C。落在 `01_struct.md` 这类文件上。 **契约与验收**：对外形状长什么样、测什么算过。落在入口清单、契约清单、测试用例上。 一句话总结：**机器总图主要管流程怎么走；入口清单和表结构说明需要单独维护。** #### 同一套流程图，为什么有 .md、.ai.md 和 graph.json 三种？ 这其实是一条三轨并行的工作流，理解起来并不复杂： - **人读轨**：`*.md` 里的 Mermaid 图，相当于给人看的纸质地图。 - **维护/导出源**：`*.ai.md`，相当于给印刷机（导出脚本）的制版稿。 - **机器查询轨**：`graph.json`，印好的可检索地图。Agent 默认查检索版的一页，不会去复印制版稿全文。 工作流是这样的：人改图（常从 `.md` 入手）→ 同步 `.ai.md` → 脚本导出 `graph.json` → Agent 按任务查其中一截。 **不是有 json 就可以删 md 或 ai.md**。恰恰相反：机器总图来自 `.ai.md`；如果没有人读 md，至少也要有人维护 ai.md，否则总图迟早会过期。 ### 8.2 第一份图谱从哪来？ 很多人都会问：“我还没有图，第一张怎么画？”答案是分新老项目，不能一刀切。 **新项目**的推荐做法很简单： 1. 先在产品或技术方案里画一页 Mermaid 图或者白板草图：一条核心链路，从用户到 API 再到关键模块再到回包。 2. 工程落盘：主图加一个分册，都是人读的 `.md` 文件。 3. 补充入口清单和表结构说明。 4. 有脚本后，把 `.md` 定稿，同步成 `.ai.md`，再导出机器总图，并在 PR 上跑检查。 新仓库先有小地图，再写代码，不必等“全系统架构完美”。 **老项目/存量仓库**的情况稍微复杂一些： - 如果有一点文档（Wiki、旧架构图、接口表），就用文档定形状，再用代码入口与调用链核对。文档当辅助，不当唯一依据。 - 如果几乎没文档，就选一条能独立闭环的链路，从代码反推画主图和一篇子图。 - **切忌**第一周就想铺全仓、把所有历史模块一次画全。 什么样的链路适合当“第一张”？有几个标准：有清晰的 HTTP/BFF 入口；改完后能用现有或刚补的少量单测验证；依赖面可控，大约 3～7 个节点。**先别选**全局配置、横切中间件、多仓胶水这些。 反推怎么画？从对外路由或 handler 开始，跟 2～3 层调用和表，主图 5～9 个方块加一篇子图就够了。第一版 70 分就够，在真实 PR 里顺手改图迭代，不必追求一次画准。 ### 8.3 怎么选第一条核心链路 适合当试点的链路应该是：高频、有真实调用；有基本单测或能补最小测试；依赖面可控；PR 时愿意顺手改图。 尽量先别选：一年改一次的边角模块；完全无测试、一改就让人害怕的模块；十条链路同时开图；“图归架构组、业务从不维护”的情况。 具体操作步骤就五步： 1. 写下链路名。 2. 画一页主图，左进右出，分叉写清。 3. 选一个最常改的分支，拆一篇分册子图。 4. 任务单写图谱入口：主图 + 子图路径。 5. 合并前跑通卷一 §6 的合并前命令。 ### 8.4 “子图”这个词，两层意思 “子图”在协作里其实有两层含义，都对，但别混用。 **分册子图（写作）**：主图上一格展开的详细流程图文件，比如 `10_flow_rag.md`。 **查询子图（Agent 默认）**：从 `graph.json` 用“从某入口往下/往上几跳”裁出来的一小块 JSON。不是把整份 `10_flow_rag.ai.md` 贴进 Prompt。 卷一里说“打开 RAG 子图”多指分册；但推荐 Agent 默认用的是查询子图，这样更省上下文。 **不要整仓灌给 Agent**——整目录、整文件、整图 JSON，既贵又噪声大，还可能漏关联。 ### 8.5 与架构图、C4、ADR 的分工 技术图谱和其他资产的分工其实挺清晰的： - **架构分层图/部署图（C4）**：给人讲边界、运维。图谱引用即可，不重复画一遍。 - **ADR / 架构决策记录**：记录“为什么这样设计”。任务单链 ADR；Agent 读图谱，必要时读 ADR 摘要。 - **Wiki / 需求文档**：产品语义。图谱不写 PRD 全文，只写工程入口与依赖。 技术图谱（本篇主题）是给 Agent 改代码时的导航与影响面——入口、流程、入口清单、表结构。它与 Wiki、ADR **并存**：产品语义在 Wiki，设计理由在 ADR，**动实现时优先更新图谱**。 ### 8.6 存量仓库：不求全仓 存量仓库的渐进落地分几个阶段： - **阶段 0**：一张主图 + 一条分册子图 + 一张接口/表清单（表格即可）。 - **阶段 1**：PR 触及该链路时顺手改图。 - **阶段 2**：加上入口清单、导出脚本、CI，防止地图过期、防止手改总图。 - **阶段 3**：对照验证读图方式。 不要追求第一周就搞全仓数字孪生。 --- ## 9. Agent 默认怎么读图 ### 9.1 为什么要谈读图方式 画了图不等于 Agent 真会用。团队需要约定：**默认给模型看什么**。否则有人整仓贴 Mermaid，有人只给目录树，结果不可比，也难验收。 ### 9.2 三种读法 把仓库里的总地图想象成一本厚地图册（导出后的 `graph.json`，**不默认背整本**）。三种读法各有特点： **整包 Mermaid**：就像把整本图册复印进 Prompt，token 极大，已经不推荐了。 **精选 Markdown 原文**：复印与本题相关的两三章说明书。实验里作为对照臂，人读友好，但作为 Agent 主载荷往往更贵。 **查询子图 + 便签（推荐默认）**：就像 GPS 导航加上站牌和警示便签。只裁与入口相关的一截路网加上清单和影响提示，效率最高。 笔者曾在后端 API 示例项目上做过读法对照实验（不是功能测试全集）。用 3 道固定任务比较不同“喂给模型的地图材料”，在有限题集上观察到：查询子图轨的静态上下文明显小于精选 Markdown 原文；部分题的影响面列得更全。所以笔者项目中约定：Agent 改图时默认查询子图，而不是默认灌整段双轨 Markdown。你的团队应该自建题集并重测后再固化规则。 **示例题集（仅作说明）**： - 改 RAG 嵌入与运行环境相关配置：关注入口与环境变量、召回链路影响面。 - 改统一问答的流式返回：关注契约与跨端字段、接口链路子图。 - 改入库/管理类写入链路：关注流程子图、表/元数据是否列全。 题集的目的不是证明三道题做完就等于全仓合格。正式团队应该从真实 PR 抽出 5～10 道作为自己的题集。 维护仍靠人：`.md` / `.ai.md` 照旧更新 → 导出 → 再查询。升级的是读法，不是取消图源。 ### 9.3 GPS 与便签：谁是谁 用比喻来理解： - **GPS 导航**：从总图按入口查询裁出的子图 JSON，包含节点、边、代码锚点。 - **站牌便签**：入口清单里与本题相关的几条，比如 URL/handler，或命令、函数锚点。 - **施工警示便签**：影响面提示，这类改动通常还动哪些文件——进阶实验里会加强。 - **路口规则便签（可选）**：契约切片，流式 API、字段约束等。 - **整章说明书**：精选 `*.ai.md` + `*.md` 全文，留给对照或人读，不作默认主载荷。 - **表结构 + 规约手册**：表结构说明、实现规约——改表、改 env 时另外打开。 ### 9.4 收到任务：该不该读图谱？ 很多人会问：图谱夹文件不少，每次对话都要通读吗？**不必。** 团队应该约定读图决策，避免 Agent 要么整仓灌图，要么完全不看。 在读图决策图中：**菱形**是判断（是/否）；**矩形**是动作（去读什么、去做什么）；从左到右沿箭头阅读。  **各分支的含义**： - **回顾支路**（第一个菱形选“是”）：打开经验或复盘类文档（若有），用于理解背景，但**不能代替**改代码时的 GPS 便签。 - **不必开图谱**（第二个菱形选“否”）：源码 + 任务单往往够用，不必为了“有图谱”而开图谱夹。 - **改代码主链**（向右延伸）：默认 GPS（查询子图）→ 站牌/路口便签；动表或元数据再开表结构说明与实现规约；流程细节仍不够才看分册流程图片段；最后落到锚点代码——图是导航，不是替代实现。 **推荐读序**（改代码时）： GPS 查询子图 → 站牌/路口规则便签 → 按需打开表结构和规约 → 不足时看分册流程图片段 → 锚点代码 **两种常见误解**： 1. “不改业务代码就用不到图谱”——对 Agent 是否开图大体成立；但提 PR 合并时，CI 仍会校验图谱是否与代码一致，与 Agent 当轮读没读无关。 2. “任务很小也要通读图谱夹”——如果任务单已写明“改某表的某字段”，即使改动行数少，也应打开表结构说明和实现规约对照，而不是跳过图谱。 ### 9.5 图谱与 CI：门禁在流程里干什么 卷一 §6 讲过合并前必绿：单测、lint、构建等。技术图谱再补一层——**文档与代码别悄悄分叉**。它和“Agent 这一轮 Prompt 里带了什么”是两条线。 整个流程是这样的：人/Agent 改代码 → 顺手改图（.md / .ai.md）→ 导出机器总图（若已有脚本）→ 提 PR → CI 自动跑图谱相关检查 + 常规测试 → 全绿 → Review → 合并。 **CI 在这里的角色**：不是替 Agent 读图，而是**在合并前拦住“图已过期”**。相当于地图出版社的校对车间。 常见的检查项包括：入口清单与实现是否一致；导出总图与流程原稿是否同步（禁止只改总图、不改原稿）；代码里出现的表名、关键环境变量，图谱文档里是否有覆盖；图门票禁不替代 pytest、eslint 等其他检查，它们一起构成“敢合并”的条件。 因此：**即使某次对话 Agent 没打开图谱夹，只要改动了入口/流程/表，PR 仍可能因图谱 CI 变红**——这是在保护全团队的下一位读者（人或 Agent），不是惩罚“没读图”。 入门团队的做法是：任务单写清入口，合并前跑通卷一 §6 的命令；有精力再逐步加上图门票禁。 ### 9.6（进阶）按题打包 日常开发用“现场 GPS + 便签”即可。本节只给要做读法对照、或要冻结复现的团队。 先分清两步，别和“导出总图”混了： - **导出**：产出仓库里的 `graph.json`（机器总图）。把多篇流程原稿编译成一本总图册。 - **按题打包**：产出某一任务专用的一袋 Prompt 材料。比如“改 RAG 召回”这道题，预先装入查询子图、入口清单切片，便于同一袋反复对比两种读法。 按题打包不等于再 export 一份总图。它是“这道题出发时的行李”。没有基准题集、不做 A/B 读法实验时，可以不做。 无对照实验时，任务单 + CI + 人工 Review 已经够闭环。按题打包仅在做读法 A/B 或冻结复现时需要，日常改需求不必做。 ### 9.7 诚实边界 读法对照指标只代表已建模仓库和声明题集，比的是读法，不是业务全覆盖。换仓库、换模型应该重测。 验收的是“读图策略是否值得坚持”，不是“有图谱就零 bug”。 CI 保证的是文档与实现不漂移；Agent 读图姿势要靠团队约定与任务单——二者互补。