AI编程技术图谱：Agent闭环协作实战指南

2026-05-29阅读 0热度 0

# 技术图谱与Agent读图：实战协作方案 2026-05-28 · 系列《AI编程闭环协作》第二卷 --- ## 为什么需要先搞懂“怎么读图”？建议先读卷一《怎样才算做完》，那里详细说明了“图谱+协作流程”的叠放关系——意图、成果、验收标准。卷一强调了**技术图谱**的核心作用：帮助Agent回答“改哪里、会影响谁”。本卷聚焦图谱轨道。我们将梳理仓库中的图谱文件——流程图、表结构说明、入口清单、机器总图；探讨首张图谱的来源、流程图的.md/.ai.md/.json三种形态、Agent的默认读图方式（查询子图+清单便签，而非整仓Mermaid），以及图谱CI门禁在合并流程中的作用。协作流程和合并签收留到卷三。仅有地图而无签收，合并仍不可靠。 --- ## 8. 技术图谱到底是什么 ### 8.0 衔接卷一卷一§2.1的“主图+子图”是本卷基础。若未阅读，建议先查看多模块API主链路示意图，再继续下文。 ![多模块API.png](https://developer.qcloudimg.com/http-sa ve/yehe-12403993/6773b3d1009fb6562ba56330d78f8247.png) ### 8.1 仓库里的技术图谱：先认识这些文件不必陷入抽象方法论。技术图谱在工程上无非是：**仓库中一个专用文件夹**（如 `docs/_tech_graph/`，名称可自定义），存放“帮助Agent改代码的地图和清单”——并非产品PRD全文，也不替代README。图谱文件夹通常包含以下类型： **主流程图（人读）**：鸟瞰全貌，展示用户请求入口、业务分支走向。用于人眼审查和团队讨论。 **分册流程图（人读）**：主图上某一节点（如“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要么整仓灌图，要么完全不看。在读图决策图中：**菱形**是判断（是/否）；**矩形**是动作（去读什么、去做什么）；从左到右沿箭头阅读。 ![读图决策.png](https://developer.qcloudimg.com/http-sa ve/yehe-12403993/0504b0f8ac7d2e490de57801d8dd611f.png) **各分支的含义**： - **回顾支路**（第一个菱形选“是”）：打开经验或复盘类文档（若有），用于理解背景，但**不能代替**改代码时的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读图姿势需靠团队约定与任务单——二者互补。

AI编程技术图谱：Agent闭环协作实战指南

相关阅读

最新教程

最新资讯