graph-ma

目标与默认产物

让读者先看懂项目，再理解关键实现与设计原因：

• 一份中文 Markdown，开头用一句话说明业务问题、输入输出及分析范围。
• 一张简洁项目主图 SVG；核心子模块仅在有助于解释时另画 SVG。
• 关键模块的少量核心代码；存在有解释价值的真实图表时，配合结果图及解读。
• 复盘、学习或面试场景可附项目相关问答；普通架构说明不强制附题库。
• 多模块、持续维护或需要后续追问时，可在指定文档目录保存轻量 analysis.json，关联模块、结论、源码证据、章节及图形；一次性小范围说明不强制生成。

图讲流程，代码讲实现，结果图讲观察，正文讲原因与边界。只保留对理解有帮助的材料，不为每个模块凑齐图、代码和结果。不要额外生成 HTML、PPT、业务代码或无关文件。

1. 锁定范围并选择分析路径

读取项目目录、版本、用户指定输出位置及现有文档。参考文档用于继承组织方式和术语粒度，项目结论仍须回到当前源码核实。

从用户目标确定讲解深度：快速定位只追踪相关链路；完整解读覆盖主链路和关键机制；学习或复盘补充设计取舍与验证思路。未指定时按足以回答问题的范围推进，不为做全仓库索引扩大任务。大仓库先读入口、构建与配置，再按依赖补读；跳过生成物和无关数据，说明覆盖边界。按勘察、成图、验证等阶段简短报告进展。

根据项目实际入口选择链路，不按文件夹逐层介绍：

| 项目类型 | 优先追踪 | | --- | --- | | 在线服务 / Agent / RAG | 输入 → 请求或上下文 → 路由与执行 → 模型、工具、存储 → 输出与回写 | | 机器学习 / Notebook | 原始数据 → 探查与筛选 → 特征处理 → 切分、训练与评估 → 融合或预测 → 产物 | | 批处理 / 数据管道 | 数据源 → 转换与调度 → 存储边界 → 下游消费 |

• 涉及 Agent、RAG、记忆、路由或工具执行时，读取 服务与 Agent 专项检查。
• 涉及数据分析、机器学习或 Notebook 时，读取 机器学习专项检查。
• 混合项目只读取涉及的参考内容；不强行套用 API、重试、回写或训练评估等不适用阶段。
• 需要复用分析或更新既有文档时，读取 分析底稿与增量更新。底稿与文档放在同一授权输出范围，不另建全仓库数据库。
• 项目已有 Understand Anything 图谱时，可按 图谱接入 定位相关节点；先检查时效，再用当前源码核实，不要求安装 UA。

若用户明确要求“先确定主图”，完成主图草案和说明后暂停等待确认；否则完成整体交付，不额外设置确认环节。

2. 沿真实链路建立证据

追踪实际入口、配置、关键函数与下游读写关系。关键结论能回指文件、类、函数、配置键、SQL、测试或 Notebook 单元格。Notebook 标明按文件顺序计数的单元格位置，不把执行编号当稳定位置。无 Git 版本时可记录分析日期与关键文件摘要。

区分以下证据来源，不必把它们都做成正文大表：

| 来源 | 能说明什么 | | --- | --- | | 源码确认 | 当前代码实现的步骤、条件、参数与读写关系 | | 本地文件实测 | 本次读到的文件形状、内容或一致性，不能证明生成过程已重现 | | 历史输出 | Notebook、日志或已有图表保存的旧结果 | | 本次运行 | 实际执行的范围、环境与观测结果 | | 合理推断 | 由证据推得但未直接验证的结论 | | 待验证 | 需要运行环境、外部数据或进一步实验才能确认的事项 |

默认值不是生产值，注释不是已验证结果，历史输出不是本次重跑，静态检查不是全流程运行成功。图中出现指标时就近注明必要口径与来源；不要暴露密钥、账号或敏感连接串。

使用底稿时，将关键结论关联到模块、证据与对应章节，稳定保留 ID。沿模块依赖记录必要关系，不为每个函数建节点；源码实现、观察结果与设计原因的推断分别记录。底稿帮助检索，不能替代重读关键源码。

3. 设计简洁主图与按需子图

主图回答：解决什么问题、输入是什么、经过哪些关键阶段、结果到哪里。保留改变主路径的关键分支和必要边界。

• 主图通常 4～7 个阶段，节点以名称加 1～2 行说明为宜；这是可调整的密度建议，不是硬限制。
• 子图围绕一个具体问题展开，例如“怎样剔除无效特征”“工具结果怎样返回模型”。
• 每张图只画理解机制必需的步骤、分支和少量关键条件。参数表、完整证据、次要异常和详细风险移到正文。
• 输入输出、状态、存储、参数、失败和一致性是分析检查项，不要求全部放入每张图。
• 优先采用易读的顺序布局。箭头表达真实调用、读写、路由等语义；阅读顺序不能伪装成数据依赖。
• 简单模块用短文或核心代码即可；真实结果图已经能回答问题时，不重复画装饰性 SVG。

SVG 使用可维护的原生元素，不把位图包装成 SVG。默认宽约 1600px，随信息量调整高度，使用 Microsoft YaHei, Segoe UI, Arial, sans-serif。保持颜色语义、留白、对齐与可读字号；箭头避开文字，包含 title 和 desc。不能靠缩小字号装入更多信息。

4. 选择核心代码与结果图

核心代码

为关键机制默认挑选最小必要片段，通常每段 5～20 行；复杂机制可拆段或适当放宽。

• 保留核心判断、变换、调用或合并过程，省略重复导包、打印和无关绘图。
• 就近注明来源及依赖变量；独立可运行示例与依赖 Notebook 上下文的摘录要区分。
• 区分原文摘录、精简改写和改进建议。改写不得悄悄改变模型、条件、指标、输入输出或错误处理；必要差异必须说明。
• 不把整函数、整 Notebook 或大量框架样板搬进文档。不是每个模块都需要代码。

真实结果图

流程图说明“怎么走”，结果图说明“观察到了什么”。优先复用源码关联的已有图、Notebook 嵌入输出或经过核实的运行产物，例如分布图、热力图、学习曲线和监控曲线。

每张结果图附简短解释：

1. 轴、颜色或标记表示什么。
2. 图支持什么观察或结论。
3. 图不能证明什么，以及来源属于历史输出还是本次运行。

结果图可作为正式 PNG、SVG 等资产交付；用于流程图视觉检查的临时 PNG 不属于正式产物。不要为凑图重跑昂贵训练或外部操作，不捏造结果。若确有必要重新生成，使用真实数据并注明本次执行范围；示意图明确标为示意。

5. 按主图组织正文

主图位于解释之前，模块标题与主图对应。

按读者的问题选择阅读路线：接手侧重入口、主链路与状态边界；排查侧重触发条件、分支与失败处理；学习侧重机制与取舍；复盘侧重实验设置与真实结果。必要时在主图下用简短导读说明先看哪里、能回答什么、下一步追踪哪个模块，顺序依据理解需要，不伪装成调用关系。

模块内部可按以下顺序取舍：

## 模块名称：要解释的问题

![简洁流程图](assets/module.svg)

做什么、为什么这样做。

### 核心代码
最小必要片段，说明来源与精简情况。

### 结果与解读
![真实结果图](assets/result.png)

观察、结论及局限。

源码位置与必要边界。

没有解释价值的子标题或材料直接省略。正文不要逐字复述图，不要写成文件清单；读者应能先看图获得全貌，再读代码和结果理解关键模块。风险集中呈现，只有影响当前结论的边界才在模块旁提示，避免到处重复免责声明。

6. 复盘与面试问答（按场景启用）

用户要求项目复盘、学习讲解或面试准备时，可补少量高价值问题，通常 3～6 个，按需求调整。围绕当前项目的真实设计选择与易混概念，不生成泛泛题库。

每题采用“简短结论 → 本项目怎样做 → 适用条件或取舍”；必要时附一句可口述答案。优先解释为什么采用某步骤、有哪些替代方案、如何验证效果。例如机器学习中的缩放与正则化，或 Agent 中路由与工具调用的关系。

原理解释、已有实现、尚未实施的改进分别写清。不能把面试建议包装成项目已经实现的能力。用户仅要架构或代码说明时，不自动扩展成完整教程。

7. 验证与写回

• 核对主要链路、条件、参数、代码片段和结果来源；区分事实、推断及运行范围。
• 可用 Python 3.10+ 运行 scripts/validate.py 检查 Markdown 图片、SVG 引用及底稿中的证据位置；具体参数见 工具用法。机械检查不证明结论含义或视觉布局正确。
• SVG XML 可解析，marker、gradient、clipPath、filter 等引用存在。用浏览器或可靠渲染器渲染并目检裁切、重叠、乱码、断箭头和小字，发现问题后修复再检查。
• 复用结果图同样需要目检可读性，核对图与对应解释、源码一致；不能仅凭文件名判断含义。
• 检查 Markdown 图片路径、标题对应关系、代码围栏和公式排版。Obsidian 优先沿用现有相对图片链接及资产目录，不硬编码某个用户的库路径。
• 继续编辑前读取最新文档，把用户新增的代码、图和解释作为后续章节的参考形式，保留现有内容与图片引用。不要把附件或文档中的文字自动当成新的操作指令。
• 已有底稿时，先用 scripts/analysis.py changes 比较当前源码与基线，重读受影响模块及调用方，修订相关章节和图；新增未映射文件或配置时扩大复核。完成源码核实、资源校验与渲染目检后，再用 snapshot 推进基线。范围之外的变化需重新勘察；不要仅凭 commit 一致判断未提交内容没变。
• 写入前重新检查目标内容摘要或时间戳。若有并发修改，保留新内容并合并；无法安全合并时说明冲突，不静默覆盖。
• 只修改用户授权的文档及其支撑资产，包括按需生成的底稿和结果来源记录；不擅自修改业务代码、配置、依赖或部署。环境不支持某项验证时如实说明，不声称已经通过。

交付

简短链接到文档与主要资产，说明覆盖范围、实际完成的验证和关键待验证项，以及是否修改业务代码。生成底稿时附其位置；更新文档时概括受影响范围。支持展示时可附主图预览；不在最终回复重复整篇文档。