LangGraph Monorepo 工程指南AGENTS.md 协作规范、核心库职责与 make 命令体系深度解析【免费下载链接】langgraphBuild resilient agents.项目地址: https://gitcode.com/GitHub_Trending/la/langgraph本文以 LangGraph 仓库根目录的 AGENTS.md 为主线完整解读这份面向开发者与 AI 编码代理的仓库协作规范monorepo 目录组织、8 个核心库的职责边界、反向依赖影响图以及提交 PR 前必须执行的make format/make lint/make test工作流。读完后你可以直接在正确的库目录中定位代码、用TEST变量精准运行指定测试文件并根据依赖图评估一次改动可能波及的下游库。AGENTS.md 是什么给“写代码的 Agent”的操作手册LangGraph 是一个构建有状态、多角色stateful, multi-actor应用的框架仓库本身采用 monorepo 组织——每个库library都位于libs/下的一个独立子目录中。AGENTS.md 正是为这一结构编写的操作手册它规定了修改任何库代码后、创建 Pull Request 前必须执行的验证命令它给出了仓库内各库的高层职责划分和依赖关系图用于在做破坏性改动前评估影响面它包含条件性安全分析指引Corridor 工具和文档字符串的格式约定。仓库根目录同时存在一份内容基本一致的 CLAUDE.md供 Claude 系编码工具读取两者差异很小例如 Corridor 一节中analyzePlan工具的触发时机措辞略有不同。可以把AGENTS.md理解为“无论人或 AI 代理动代码前都应遵守的最小工程契约”。Monorepo 布局8 个核心库的职责划分AGENTS.md对仓库中的 Python 与 JavaScript/TypeScript 库给出了如下高层概览库目录职责libs/checkpointLangGraph Checkpointer 的基础接口状态持久化抽象层libs/checkpoint-postgresCheckpoint Saver 的 Postgres 实现libs/checkpoint-sqliteCheckpoint Saver 的 SQLite 实现libs/cliLangGraph 官方命令行工具libs/langgraph核心框架构建有状态、多角色 Agentlibs/prebuilt创建与运行 Agent 和工具的高层 APIlibs/sdk-js与 LangGraph REST API 交互的 JS/TS SDKlibs/sdk-pyLangGraph Server API 的 Python SDK从各库pyproject.toml的实际声明可以进一步印证这种分层关系以当前仓库版本为准libs/langgraph/pyproject.toml 中langgraph当前版本 1.2.11的生产依赖包含langgraph-checkpoint4.1.0,5.0.0、langgraph-sdk0.4.2,0.5.0、langgraph-prebuilt1.1.0,1.2.0即核心框架向下依赖 checkpoint 基础库、SDK 和 prebuiltlibs/checkpoint-postgres/pyproject.toml 中langgraph-checkpoint-postgres3.1.2声明依赖langgraph-checkpoint4.1.0,5.0.0、orjson、psycopg、psycopg-pool且通过[tool.uv.sources]同文件 L51-L53将langgraph-checkpoint指向本地相对路径../checkpoint的 editable 安装——这是 monorepo 内跨库联调的典型做法libs/prebuilt/pyproject.toml 中langgraph-prebuilt1.1.0生产依赖为langgraph-checkpoint与langchain-core。此外libs/下还存在 libs/checkpoint-conformance一套针对 checkpointer 实现的一致性conformance测试套件。它不属于AGENTS.md列出的核心库清单但会被 checkpoint 家族库以测试依赖的方式引入例如 checkpoint-postgres 的 test 依赖组中声明了langgraph-checkpoint-conformance并以 editable 方式指向本地../checkpoint-conformance用于保证 Postgres、SQLite 等实现满足同一份接口规范。依赖关系图改动前先看谁会受影响AGENTS.md的核心资产是一张反向依赖图dependency map。该图依据各库pyproject.toml或package.json中声明的生产依赖整理列出每个库的下游依赖方——即图中每个分组的根节点是“被依赖的上游库”其下分支是“直接依赖它的下游库”checkpoint ├── checkpoint-postgres ├── checkpoint-sqlite ├── prebuilt └── langgraph prebuilt └── langgraph sdk-py ├── langgraph └── cli sdk-js (standalone)读图要点与仓库验证checkpoint 是整座仓库的地基。checkpoint-postgres、checkpoint-sqlite、prebuilt、langgraph 四个库都直接依赖它。抽查源码可以印证checkpoint-postgres 声明langgraph-checkpoint4.1.0,5.0.0libs/checkpoint-postgres/pyproject.tomllanggraph 声明langgraph-checkpoint4.1.0,5.0.0libs/langgraph/pyproject.toml。因此修改libs/checkpoint的公共接口如 libs/checkpoint/langgraph/checkpoint/base 中的抽象类时必须同时回归四个下游库的测试。prebuilt → langgraph表示 langgraph 核心包在运行时依赖langgraph-prebuilt见 libs/langgraph/pyproject.toml 中的langgraph-prebuilt1.1.0,1.2.0。prebuilt 的公开行为变化会直接传导到核心框架。sdk-py → langgraph、cli表示 Python SDKlanggraph-sdk是核心框架与 CLI 的公共依赖langgraph 一侧已在 libs/langgraph/pyproject.toml 中得到验证。SDK 的 API 变更如流式传输协议、SSE 解码行为需要同时关注 CLI 侧。sdk-js 是独立的standalone不与 Python 侧的库形成生产依赖JS/TS SDK 的改动影响面相对隔离。AGENTS.md对此给出的行动准则很直接“Changes to a library may impact all of its dependents shown above”——对某个库的修改可能影响图中列出的所有下游依赖方。做接口级变更前应先沿这张图圈出需要跑测试的目录。提交 PR 前的标准工作流make format / make lint / make testAGENTS.md规定修改任意库的代码后在创建 PR 前要在该库自己的目录中运行以下三条命令make format # 运行代码格式化器 make lint # 运行 linter make test # 执行测试套件这三个目标在各库 Makefile 中的实际实现高度统一以 libs/langgraph/Makefile 为例可以看清每一步到底做了什么make format 与 make lint 的源码级行为libs/langgraph/Makefile 中format目标执行uv run ruff format $(PYTHON_FILES)与uv run ruff check --fix $(PYTHON_FILES)即用 ruff 完成格式化加可自动修复项的修正lint目标执行uv run ruff check .、uv run ruff format --diff只检查不落地、uv run ruff check --select Iimport 排序检查以及uv run ty check langgraph类型检查通过PYTHON_FILES变量控制作用域lint/format作用于整个目录.而lint_package/lint_tests可以只检查langgraph或tests子目录lint_diff则只对git diff中与main分支相比变更过的.py/.ipynb文件生效适合增量审查。libs/checkpoint/Makefile 与 libs/prebuilt/Makefile 采用同一套模式ruff ty只是类型检查的目标包名不同。依赖全部通过 uv 管理各库pyproject.toml的[dependency-groups]中lint组声明了ruff、ty等工具因此命令不需要预装全局工具链。make test 的内部机制自动探测 Docker 服务make test并不是简单的pytest .。以核心库为例libs/langgraph/Makefile 的test目标逻辑是用command -v docker探测本机是否安装 DockerNO_DOCKER变量有 Docker时先make start-services启动 Postgres 与 Rediscompose 文件为 libs/langgraph/tests/compose-postgres.yml 与 libs/langgraph/tests/compose-redis.yml再make start-dev-server以 libs/langgraph/tests/example_app/langgraph.json 为配置启动langgraph dev开发服务器然后执行uv run pytest $(TEST)结束后自动停掉服务并透传测试退出码无 Docker时退化为NO_DOCKERtrue uv run pytest $(TEST)只运行不依赖外部服务的用例。libs/prebuilt/Makefile 则固定要求先make start-services再测试因为它的测试普遍涉及 Postgres并额外提供test-fast目标LANGGRAPH_TEST_FAST1只用内存版 checkpointer 跑快速测试。而 libs/checkpoint/Makefile 的测试最轻量uv run pytest $(TEST)无外部服务依赖——这与它作为纯接口/内存实现库的定位一致。Makefile 还提供了test_watch基于ptw的 watch 模式、coveragepytest --cov、type单独跑ty、spell_check/spell_fixcodespell等辅助目标开发者可以在对应库目录用make help查看完整清单。用 TEST 变量运行指定测试AGENTS.md给出的一条高频操作是通过TEST变量运行特定测试文件或向 pytest 追加参数TESTpath/to/test.py make test对照 Makefile 源码如 libs/langgraph/Makefile 中的TEST ? .可以明确两点机制TEST ? .表示该变量默认为当前目录.即不传参时pytest .跑整个库的测试TEST的值会被原样拼接进uv run pytest $(TEST)命令行因此TEST内可以携带任何 pytest 合法参数例如追加选项、选择器或标记过滤。这也解释了为什么文档强调“Other pytest arguments can also be supplied inside theTESTvariable”。一个典型场景修改了 libs/checkpoint-sqlite/langgraph/checkpoint/sqlite 的增量通道逻辑后在libs/checkpoint-sqlite目录运行TESTtests/test_get_delta_channel_history.py make test即可只回归对应的历史取数用例。根目录 Makefile对全部库的一键批处理除了“进入单个库目录操作”仓库根目录的 Makefile 提供了跨库批处理能力。它用LIBS_DIRS : $(wildcard libs/*)枚举libs/下所有子目录然后逐个进入执行all: lint format lock test # 默认目标全仓库 lint format lock testmake install创建 uv 虚拟环境后对每个含pyproject.toml的库执行uv pip install -e dir一次性以 editable 方式安装所有 Python 库sdk-js 无 pyproject.toml 会被自动跳过make lint/make format/make test遍历每个含Makefile的库目录执行对应目标make lock/make lock-upgrade在各库内执行uv lock或--upgrade维护各库独立的uv.lock。从源码结构看这套批处理与AGENTS.md的“在该库目录运行命令”并不矛盾单库命令用于日常开发与 PR 前验证根目录命令更适合全量回归与依赖锁定检查。两个容易忽略的附加规范Corridor 安全分析条件性要求AGENTS.md用corridor标签包裹了一段条件性指令当 Corridor 的analyzePlan工具可用时应在生成或修改代码之前先制定计划并调用该工具做安全分析再按其给出的安全指引写代码。这是一段典型的“写给工具看”的指令块——没有该工具时自动不生效人类开发者可忽略。Docstring 格式约定文档最后一条规则禁止使用 Sphinx 风格的双反引号code行内代码写法要求 docstring 和注释中一律使用单反引号code。这条约定保证文档字符串在各种渲染器下的一致性是在本仓库写注释时需要记住的一个小细节。开发者自检清单综合 AGENTS.md 的规范与仓库中 Makefile、pyproject.toml的实际实现改动代码后的检查清单可以收敛为定位改动所在库目录libs/library确认其职责边界见本文库职责表对照依赖图圈出下游依赖方评估接口变更的影响面在该库目录依次执行make format、make lint、make test注意 langgraph/prebuilt 库的测试会自动拉起 Docker 服务无 Docker 环境会自动降级或按各库 Makefile 的行为执行需要缩小测试范围时用TESTpath或pytest参数 make test写注释与 docstring 时使用单反引号行内代码避免 Sphinx 双反引号写法若工作流中接入了 Corridor 的analyzePlan工具先过安全分析再动手改代码。这套“目录即边界、Makefile 即流程、依赖图即影响面”的约定本质上把 monorepo 的协作复杂度收敛成了三张表库职责表、依赖图、Makefile 目标表——无论人类开发者还是自动化编码代理都可以据此独立、完整地定位并验证自己的改动。【免费下载链接】langgraphBuild resilient agents.项目地址: https://gitcode.com/GitHub_Trending/la/langgraph创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考