人工智能大模型AI AgentAgent 框架RAG【免费下载链接】langchainThe agent engineering platform.项目地址https://gitcode.com/GitHub_Trending/la/langchain点击查看免费下载本文基于 LangChain Python 单仓库monorepo根目录的 AGENTS.md 全局开发指南编写系统梳理该仓库的包结构分层、基于uv的开发命令与依赖管理、代码质量与测试规范、模型 profile 维护流程以及从 PR 提交到包发布的完整 CI/CD 链路。读完本文你将掌握在该仓库中定位各包职责、配置本地开发环境、按规范提交与审查代码、运行单元测试与集成测试以及发布 partner 包的标准操作流程。一、仓库定位与整体架构LangChain 是一个 Agent 工程平台The agent engineering platform其 Python 侧以单仓库形式管理多个独立版本号的包包与包之间的依赖通过可编辑安装editable install关联。整个仓库的顶层结构如下langchain/ ├── libs/ │ ├── core/ # langchain-core primitives and base abstractions │ ├── langchain/ # langchain-classic (legacy, no new features) │ ├── langchain_v1/ # Actively maintained langchain package │ ├── partners/ # Third-party integrations │ │ ├── openai/ # OpenAI models and embeddings │ │ ├── anthropic/ # Anthropic (Claude) integration │ │ ├── ollama/ # Local model support │ │ └── ... (other integrations maintained by the LangChain team) │ ├── text-splitters/ # Document chunking utilities │ ├── standard-tests/ # Shared test suite for integrations │ ├── model-profiles/ # Model configuration profiles ├── .github/ # CI/CD workflows and templates ├── .vscode/ # VSCode IDE standard settings and recommended extensions └── README.md # Information about LangChain从源码目录可以看出该仓库实际实现了这一结构libs/ 下包含core、langchain、langchain_v1、partners、text-splitters、standard-tests、model-profiles七个一级目录.github/workflows/下存放 CI 工作流文件.vscode/目录对应 IDE 标准配置。四层职责划分指南明确将整个仓库划分为四层每一层解决不同粒度的问题核心层langchain-core位于 libs/core/langchain_core/提供基础抽象、接口与协议如runnables、messages、tools、output_parsers等。它面向开发者透明用户通常无需直接感知这一层。实现层langchain即 libs/langchain_v1/提供具体实现与高层公共工具是当前活跃维护的langchain包而同目录下的 libs/langchain/langchain-classic属于遗留包不再新增功能。集成层partners/libs/partners/ 存放由 LangChain 团队维护的第三方服务集成例如openai、anthropic、ollama等。需要说明的是该单仓库并未穷尽所有 LangChain 集成部分集成如langchain-google、langchain-aws维护在独立仓库中通常被克隆在与本仓库同级的目录开发时可通过../langchain-google/直接引用其代码。测试层standard-testslibs/standard-tests/langchain_tests/ 为各 partner 集成提供标准化的共享测试套件保证不同集成实现行为的一致性。技术栈与工具链仓库的开发工具链在 AGENTS.md 中列出并可在各包 pyproject.toml 的依赖分组中逐一印证工具用途仓库证据uv快速 Python 包安装与解析器替代 pip/poetry每个包均有独立的pyproject.toml与uv.lock如 libs/core/pyproject.tomlmake常见开发命令的任务执行器各层 Makefile如 libs/Makefile、libs/core/Makefileruff快速 Python lint 与格式化lint分组声明ruff0.15.0见 libs/core/pyproject.tomlmypy静态类型检查typing分组声明mypy2.1.0见 libs/core/pyproject.tomlpytest测试框架test分组声明pytest9.0.3见 libs/core/pyproject.toml二、开发环境与依赖管理全面拥抱 uvAGENTS.md 明确要求本单仓库内所有环境与依赖操作一律使用uv不要直接调用pip、poetry或conda。原因在于uv以锁文件保证构建可复现并能自动管理解释器与虚拟环境无需手动source .venv/bin/activate。环境搭建命令在仓库根目录或对应包目录执行# 安装所有依赖分组推荐首次使用 uv sync --all-groups # 或仅安装某个分组 uv sync --group test依赖分组的定义位于各包的 pyproject.toml常见的分组包括lint、typing、dev、test、test_integration等--all-groups会一次性同步全部。使用约束让uv管理解释器与虚拟环境uv sync/uv run会自动处理不要在包目录之外另建临时虚拟环境。不固定全局 Python 版本每个包通过自己的pyproject.toml声明支持的 Python 范围。例如langchain-core声明requires-python 3.10.0,4.0.0libs/core/pyproject.toml并明确列出 Python 3.103.14 的分类器libs/core/pyproject.toml。需要解释器时以包的requires-python为准不要假设系统 Python。依赖必须通过uv sync可选--group name/--all-groups显式安装不允许隐式安装。同一会话内不要混用环境除非确有需要以近期 release/commit 及采纳情况说明理由否则不新增依赖。锁文件与跨包任务libs/Makefile 提供了跨包锁文件维护任务# 重新生成 core、text-splitters、langchain、langchain_v1、model-profiles 的锁文件 make lock # 校验所有锁文件是否最新过期则失败退出 make check-lock其中check-lock内部执行uv lock --check任一包校验失败即退出码 1。三、测试、Lint 与格式化命令运行单元测试离线# 运行全部单元测试不联网 make test # 运行指定测试文件 uv run --group test pytest tests/unit_tests/test_specific.pymake test的具体实现见 libs/core/Makefile它以env -u依次清除LANGCHAIN_TRACING_V2、LANGCHAIN_API_KEY、LANGSMITH_API_KEY、LANGSMITH_TRACING、LANGCHAIN_PROJECT五个追踪相关环境变量再通过uv run --group test pytest -n auto --benchmark-disable --disable-socket --allow-unix-socket并行执行其中--disable-socket保证单元测试不允许发起网络请求这正是「单元测试无网络调用」这一硬性约束的执行机制。此外libs/core/tests/unit_tests/runnables/conftest.py 中有一个 session 级 autouse fixture_disable_local_langsmith_tracing它会移除开发者本地的 LangSmith 环境变量并将LANGSMITH_TRACING置为false确保 runnable 单元测试不依赖开发者的追踪配置测试结束后再恢复原环境——与 AGENTS.md 中「单元测试必须与开发者本地 LangSmith 环境变量隔离」的描述完全吻合。Lint、格式化与类型检查# 代码检查import 排序 ruff mypy make lint # 代码格式化ruff format ruff check --fix make format # 仅类型检查 uv run --group lint mypy .从 libs/core/Makefile 可见make lint依次执行scripts/lint_imports.sh校验 import 规则、ruff check、ruff format --diff与mypy带.mypy_cache缓存make format则执行ruff format与ruff check --fix。若只想检查本次改动还有面向 diff 的lint_diff/format_diff目标。测试组织约定AGENTS.md 规定测试文件结构应与源码结构一一对应单元测试tests/unit_tests/禁止网络调用如 libs/core/tests/unit_tests/集成测试tests/integration_tests/允许网络调用如 libs/core/tests/integration_tests/、libs/partners/openai/tests/integration_tests/。每个新功能或 bug 修复必须有单元测试覆盖且遵循如下清单逻辑被破坏时测试必须失败覆盖 happy path覆盖边界条件与错误分支外部依赖使用 fixture/mock测试确定性高不允许 flaky整套测试在你改动被破坏时能报错。四、代码质量与公共接口稳定性维护稳定的公共接口最高优先级AGENTS.md 将其标记为 CRITICAL任何对导出/公共方法的函数签名、参数位置与名称的改动都应尽力避免不允许引入破坏性变更。即使看起来不具破坏性的签名变化也应对开发者发出警告。在改动公共 API 之前必须自查检查该函数/类是否已在__init__.py中导出例如 libs/core/langchain_core/init.py检索测试与示例中已有的使用模式新增参数必须使用 keyword-only*, new_param: str default实验性功能需在 docstring 中用 MkDocs Material 风格的 admonition如!!! warning明确标注。判断标准一句话概括这个改动会不会让上周还在用它的用户代码崩掉Would this change break someones code if they used it last week?代码风格要求所有 Python 代码必须包含类型注解与返回类型。AGENTS.md 给出的规范示例def filter_unknown_users(users: list[str], known_users: set[str]) - list[str]: Single line description of the function. Any additional context about the function can go here. Args: users: List of user identifiers to filter. known_users: Set of known/valid user identifiers. Returns: List of users that are not in the known_users set. 此外还要求使用描述性变量名遵循正在修改的代码既有模式超过约 20 行的复杂函数应拆分为更小、更聚焦的函数删除不可达/注释掉的代码正确释放文件句柄、连接等资源避免资源泄漏与竞态条件。安全与风险评估禁止对用户可控输入执行eval()、exec()或pickle异常处理要规范不允许裸except:错误消息统一放在msg变量中。文档规范Google-style docstring公共函数一律使用带Args段的 Google 风格 docstring并遵循以下细则def send_email(to: str, msg: str, *, priority: str normal) - bool: Send an email to a recipient with specified priority. Any additional context about the function can go here. Args: to: The email address of the recipient. msg: The message body to send. priority: Email priority level. Returns: True if email was sent successfully, False otherwise. Raises: InvalidEmailError: If the email address format is invalid. SMTPConnectionError: If unable to connect to email server. 类型放在函数签名中不写进 docstring已有默认值时不重复列出除非存在后处理或条件设置描述聚焦「为什么」而非「是什么」覆盖全部参数、返回值与异常统一使用美式拼写如behavior而非behaviour行内代码引用使用单反引号code不要用 Sphinx 风格的双反引号code。文档与示例中的模型引用引用 LLM 时始终使用最新的 GAGenerally Available模型避免 preview/beta 标识除非没有 GA 等价物。写文档或示例前应核对 provider 官方文档中的当前模型 ID不要依赖记忆中的旧模型名。特别要注意修改代码中已上线的默认参数值如类构造函数里的model默认值可能构成破坏性变更须遵守上述公共接口稳定原则文档与示例中的模型引用则不受此限制。模型 profile 数据能力标志、上下文窗口等统一通过下文介绍的langchain-profilesCLI 维护。五、模型 Profiles 维护langchain-profiles CLI模型 profile能力标志、上下文窗口等元数据通过 libs/model-profiles 中的langchain-profilesCLI 生成与刷新CLI 入口实现见 libs/model-profiles/langchain_model_profiles/cli.py。其refresh子命令会从 models.dev 拉取数据、应用profile_augmentations.toml中的覆盖项overrides分为 provider 级与 model 级两层并写入目标 data 目录。关键约束--data-dir必须指向包含profile_augmentations.toml的目录而非包的顶层目录。# 在 libs/model-profiles 下执行 cd libs/model-profiles # 刷新本仓库内 partner 的 profiles uv run langchain-profiles refresh --provider openai --data-dir ../partners/openai/langchain_openai/data # 刷新外部仓库 partner 的 profiles需 echo y 确认 echo y | uv run langchain-profiles refresh --provider google --data-dir /path/to/langchain-google/libs/genai/langchain_google_genai/data本仓库内带 profile 数据的 partner 示例libs/partners/openai/langchain_openai/data/provideropenai其中已包含 profile_augmentations.tomllibs/partners/anthropic/langchain_anthropic/data/provideranthropiclibs/partners/perplexity/langchain_perplexity/data/providerperplexity。echo y |管道仅在--data-dir位于libs/model-profiles工作目录之外时必需。这一点与 cli.py 中的安全确认逻辑对应当目标目录不在当前工作目录内时CLI 会提示Continue? (y/N)等待用户输入y才继续写入。六、CI/CD 基础设施发布流程每个 partner 包独立发布完整发布链路为version bump PR → 合并到 master → 触发 release 工作流 → 自动发布。第 1 步Version bump PR。创建一个 PR逐行修改三个文件langchain_partner/_version.py中的__version__pyproject.toml中的versionuv.lock在包目录执行uv lock重新生成。若 diff 中包含无关改动如不同本地 Python 版本产生的环境相关 marker 行应还原只保留被发布包的version ...一行。标题遵循 Conventional Commitsrelease(partner): version如release(openrouter): 0.2.6分支名为release/partner-version。patch 还是 minor 的取舍遵循仓库先例在0.x系列内修复与纯增量功能走 patch例如新增session_id字段 → 0.2.1→0.2.2新增parallel_tool_calls→ 0.2.3→0.2.4。第 2 步合并 PR 到master。第 3 步触发发布工作流。对_release.yml文件 ID63880841执行gh workflow rungh workflow run 63880841 --repo langchain-ai/langchain \ -f working-directorypartner -f release-versionversion其中working-directory使用工作流下拉菜单中的短 partner 名如openrouter而非libs/partners/openrouter。第 4 步其余全部自动完成。不要手动创建 GitHub Release 或 tag。mark-release任务使用ncipollo/release-action会在 PyPI 发布成功后自动创建 GitHub Release、tag 与 release notesrelease notes 正文由上一个 tag 至 HEAD 的提交历史自动生成。监控命令gh run view run-id --repo langchain-ai/langchain完整任务链为build → release-notes → pre-release-checks → TestPyPI publish → PyPI publish → tag GitHub release。PR 标题 lint 与自动打标标题 lint由 .github/workflows/pr_lint.yml 执行强制 Conventional Commits 格式。该文件明确列出了允许的 typefeat、fix、docs、style、refactor、perf、test、build、ci、chore、revert、release、hotfix与允许的 scopecore、langchain、langchain-classic、model-profiles、standard-tests、text-splitters、docs、各 partner 名、infra、deps、partners等。所有标题都必须带 scope即使是主langchain包也不例外。自动打标工作流均可在 .github/workflows/ 中看到pr_labeler.yml统一的 PR 标签器按 size、file、title、internal/external、contributor tier 打标pr_labeler_backfill.yml对已打开 PR 手动回填标签auto-label-by-package.yml按包为 issue 打标tag-external-issues.ymlissue 的 internal/external 分类。集成测试的 LangSmith 追踪定时或手动触发的集成测试integration_tests.yml会把每次运行都 trace 到 LangSmith使失败能回溯到对应的 GitHub Actions 运行。CI 设置的环境变量包括环境变量含义LANGSMITH_API_KEY认证 LangSmith仓库 secret限定在integration_tests.yml的 Scheduled testing 环境中LANGSMITH_TRACINGtrue开启测试进程的追踪LANGSMITH_PROJECTtrace 所属项目默认scheduled-testing-py通过仓库变量覆盖${{ vars.LANGSMITH_PROJECT \|\| scheduled-testing-py }}要改项目应在 GitHub 设置中改仓库变量不要硬编码进工作流LANGSMITH_TAGS逗号分隔的 run 标识github-actions、矩阵工作目录如libs/partners/openai、Python 版本、commit SHALANGSMITH_METADATA由 Build LangSmith Metadata 步骤构建的 JSON 对象包含github_sha、github_run_id、github_run_attempt、github_run_url、github_workflow、github_event、github_ref、working_directory、python_version追踪桥接插件LangSmith SDK 原生不读取LANGSMITH_TAGS/LANGSMITH_METADATA环境变量因此需要 libs/standard-tests/langchain_tests/_langsmith_plugin.py 这个 pytest 插件来弥补。该插件在测试会话期间进入langsmith.run_helpers.tracing_context且仅在GITHUB_ACTIONStrue时激活见该文件_is_github_actions()实现libs/standard-tests/langchain_tests/_langsmith_plugin.py因此不影响本地开发它通过pytest11entry point 被所有依赖langchain-tests的包自动发现声明见 libs/standard-tests/pyproject.toml。单元测试隔离单元测试绝不允许网络调用或发送 trace。make test通过env -u清除追踪变量见 libs/core/Makefilelibs/core/tests/unit_tests/runnables/conftest.py 则以 session 级 autouse fixture 显式禁用 runnable 单元测试的追踪并随后恢复环境。新增 partner 包时需要更新的文件在 .github/ 下依次更新.github/ISSUE_TEMPLATE/*.yml加入 package 下拉选项.github/dependabot.yml新增依赖更新条目.github/scripts/pr-labeler-config.json新增文件规则与 scope→label 映射.github/workflows/_release.yml按需补充 API key secrets.github/workflows/auto-label-by-package.yml新增包标签.github/workflows/check_diffs.yml加入变更检测.github/workflows/integration_tests.yml新增集成测试配置.github/workflows/pr_lint.yml加入允许的 scope。GitHub Actions 安全约束仓库要求所有 action固定到完整长度的 commit SHA使用 tag 会失败。需要时用ghCLI 查询并确认 tag 不是 annotated tag 对象否则需要解引用。七、Git 提交规范与 PR 描述写作Conventional Commits 标题所有提交标题遵循 Conventional Commits且必须包含 scope无例外见 .github/workflows/pr_lint.yml 的完整 type/scope 列表。细则type(scope):之后以小写字母开头除非首词是专有名词如Azure、GitHub、OpenAI或具名实体类、函数、方法、参数、变量名具名实体用反引号包裹专有名词不加修饰标题保持简短、有描述性细节放进正文。示例feat(langchain): add new chat completion feature fix(core): resolve type hinting issue in vector store chore(anthropic): update infrastructure dependencies feat(langchain): ls_agent_type tag on create_agent calls fix(openai): infer Azure chat profiles from model name分支命名分支统一采用github-username/scope/short-description三段式github-username作者 GitHub 登录名如mdrxyscope与提交标题中的 scope 一致core、langchain、partner 名、infra、docs等short-descriptionkebab-case、简短、末尾不带斜杠。示例mdrxy/anthropic/normalize-tool-call-ids mdrxy/core/vector-store-type-hints mdrxy/infra/agents-md-branchPR 描述规范PR 描述本身就是摘要不要加# Summary标题若 PR 关闭某个 issue第一行单独放 closing 关键字后接分隔线与正文Closes #123 --- rest of description只有Closes、Fixes、Resolves会在合并时自动关闭关联 issueRelated:等仅作信息提示不会关闭任何 issue。解释「为什么」谁受益、他们遇到了什么问题、该改动如何解决。优先用简短用户故事而非长摘要面向可能不熟悉该代码库的读者写作避免内部行话便于公开读者理解不要引用行号文件一变即失效极少包含完整文件路径或文件名改为引用受影响的符号、类或子系统名类、函数、方法、参数、变量名用反引号包裹全新功能或行为变更型修复需在描述中加入## Release note小节以 release-note-ready 的语言陈述用户可见变化大多数情况省略独立的 Test plan / Testing 小节仅在覆盖不明显、有风险或值得注意时提及测试指出需要仔细 review 的改动区域若贡献涉及 AI 参与添加简短声明。八、可用的额外资源文档官方 Python 文档位于docs.langchain.com源码维护在独立的langchain-ai/docs仓库本仓库外可用../docs/访问。指南建议优先使用本地安装配合文件搜索工具获得最佳效果。贡献指南见docs.langchain.com/oss/python/contributing/overview。此外本仓库根目录还包含一个自动生成的openwiki/证据索引如 openwiki/index.md它是可选的即时上下文并非启动必读源码与测试才是权威依据定期的 OpenWiki GitHub Actions 工作流openwiki-update.yml会刷新该 wiki除明确要求外不要手工编辑生成的 OpenWiki 页面应优先更新源码/文档后让其自动重新生成。结语AGENTS.md 是 LangChain 单仓库的「开发宪法」从 monorepo 的四层架构与uv驱动的依赖管理到公共 API 稳定性红线、Google-style docstring 与单元测试全覆盖要求再到模型 profile 刷新、partner 包发布链路与 LangSmith 追踪隔离每一条规范都能在仓库的 Makefile、pyproject.toml 与.github/workflows/中找到对应实现。无论是作为贡献者参与开发还是作为读者理解该平台的工程实践本文梳理的流程与命令都能帮助你快速进入状态。赞分享人工智能大模型AI AgentAgent 框架RAG【免费下载链接】langchainThe agent engineering platform.项目地址https://gitcode.com/GitHub_Trending/la/langchain点击查看免费下载相关推荐Video2X免费视频超分与补帧全攻略360P提到4KVideo2X免费视频超分与补帧全攻略360P提到4K 你把 40GB 的老视频拖进放大工具进度条走到一半才发现硬盘早已被拆出来的帧图吞掉。Video2X音视频视频处理图像处理深度学习react-datepicker 仓库开发指南CLAUDE.md 工程规范、构建架构与贡献工作流全解react datepicker 仓库开发指南CLAUDE.md 工程规范、构建架构与贡献工作流全解 本文以仓库根目录 CLAUDE.md https://l前端UI组件SkyPilot 开发者指南从仓库结构、工程规范到架构模式与提交流程SkyPilot 开发者指南从仓库结构、工程规范到架构模式与提交流程 本指南以 SkyPilot 代码库中的 CLAUDE.md 开发文档为骨架面向在 Sk后端任务调度MLOps集群管理创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考