langgraph-architecture-review

让 Python LangGraph 架构变得可理解、可核验、可改进，不凭想象补出源码里不存在的节点。

什么时候用它

梳理工作流程

我需要一张以源码为依据的 Mermaid 图，并想弄清状态、节点、路由、工具和输出怎样完成具体业务任务。

检查运行安全

我想在改图之前检查状态合并、持久化、人工确认、重试、循环、副作用、终止路径或敏感状态输出。

规划架构改动

我有明确功能或架构问题，希望每条建议都带文件位置、预期效果、风险和可执行的验证方法。

不接

从零选择通用 AI 架构、与 LangGraph 无关的普通代码审查、只有 TypeScript 的图，或未经架构检查就直接新建图，都应交给其他流程。

它会产出什么

源码和编译后的图才是证据，看起来合理的示意图不是。

• 架构报告：返回 LANGGRAPH_ARCHITECTURE_PACKET，包含 Mermaid 图、业务说明、职责边界、发现和分级建议。
• 静态清单：运行内置扫描与校验脚本，用临时 Markdown 和 JSON 报告把图元素追溯到源码。
• 运行时检查：只有确认导入项目不会触发危险副作用时，才使用公开接口读取编译图。
• 当前规范：涉及最新接口或迁移建议时核对官方来源；无法联网核验时明确标记为仅依据本地版本。
• 默认副作用：只读审查模式不改项目代码，不安装或升级 LangGraph，也不强制使用 LangSmith。
• 绝不会做：不泄露密钥或私有状态，不伪造测试结果，也不把检查点数据当成正式业务事实。

前置条件与边界

前置条件

需要一个可读、已使用 LangGraph 的 Python 项目。必须能够检查已安装版本、图构建器、状态定义、节点函数、路由、持久化配置和对外接口。

验证边界

• 扫描器漏掉动态构图时会人工检查，无法确认的连线继续标为 unverified。
• 导入有副作用时只做静态检查；缺少测试、凭据、渲染器或官方资料时标为 not_run 或未完成。
• 必须提供 Mermaid 源码，但不强制渲染成图片。

相邻流程分工

需要做的事	交给
从零选择 AI 架构	架构选型流程
审查无关的 Python 代码	普通代码审查
落实已批准的改动	明确的后续实施任务

微妙边界

默认只审查和汇报。只有用户在审查后明确要求实施，才会修改项目文件。