企业官网建设流程全解析

• 人工智能
• 大模型
• AI Agent
• Agent 框架
• RAG

导读

LangChain 是一个 Agent 工程平台，为构建 LLM 驱动的应用提供可组合的抽象（Runnable、BaseChatModel、工具、提示词、消息）、多厂商模型集成与编排原语。本指南基于仓库内 openwiki/quickstart.md 整理而成，面向首次接触该仓库的工程师：你将掌握libs/三层 monorepo 的组织方式与各层职责边界，用uv完成依赖安装与 pre-commit 钩子配置，熟练运行单元测试、集成测试、格式检查与 lint 命令，并走完从"选任务 → 改代码 → 本地校验 → 提交 PR"的完整开发流程。读完本文，你可以独立定位要修改的包、跑通本地校验并提交合规的 Pull Request。

Monorepo 总览：三层架构与各层职责

LangChain 仓库在/libs/目录下采用三层架构组织代码：

/libs/ ├── core/ # langchain-core：基础抽象（Runnable、BaseChatModel、tools、prompts、messages） ├── langchain_v1/ # langchain：Agent 编排、工厂、中间件 ├── partners/ # 厂商集成（OpenAI、Anthropic、Ollama 等） ├── standard-tests/ # 面向组件的共享一致性测试套件 ├── text-splitters/ # 文本切分工具 ├── model-profiles/ # LLM 元数据与能力画像 └── Makefile # monorepo 级构建目标

三层之间依赖方向清晰：core 定义接口、langchain_v1 做编排、partners 提供实现。从源码看，libs/core/langchain_core/init.py 明确写道："langchain-core定义 LangChain 生态的基础抽象……这里不定义任何第三方集成，依赖被刻意保持非常轻量"，这印证了 core 层的纯净定位。而 libs/langchain_v1/langchain/init.py 是主包入口，当前版本为1.4.2。

何时编辑哪一层

以langchain_v1层为例，libs/langchain_v1/langchain/agents/factory.py 中create_agent的签名（见 factory.py#L823-L840）暴露了该层编排能力的核心参数面：model（字符串或BaseChatModel）、tools、system_prompt、middleware、response_format、state_schema、context_schema、checkpointer、store、interrupt_before/after、debug等，返回一个编译好的CompiledStateGraph——这正是"Agent 编排层"的落点。

安装与设置

克隆仓库

git clone https://gitcode.com/GitHub_Trending/la/langchain.git cd langchain

用uv安装依赖

整个 monorepo 使用uv做快速、确定性的依赖解析。先安装uv：

# macOS / Linux curl -LsSf https://astral.sh/uv/install.sh | sh # Windows powershell -c "irm https://astral.sh/uv/install.ps1 | iex" # 或者通过 Homebrew brew install uv

然后在任意libs/子目录中同步依赖（各包依赖分组以对应 pyproject.toml 为准）：

# 从任意 libs/ 子目录安装全部分组（test、lint、type、typing、dev） uv sync --all-groups # 或者只装你需要的分组 uv sync --group test # 运行测试 uv sync --group test_integration # 运行带 VCR cassettes 的集成测试 uv sync --group lint # ruff 格式化 uv sync --group typing # mypy 类型检查 uv sync --group dev # 开发工具（Jupyter、setuptools 等）

需要说明的是，各包的make test目标实际以uv run --group test方式执行，且通过.EXPORT_ALL_VARIABLES导出了UV_FROZEN = true（见 libs/core/Makefile），即在锁定文件约束下运行，保证依赖版本可复现。

配置 Pre-Commit 钩子

pre-commit install # 手动运行全部钩子 pre-commit run --all-files # 运行指定钩子 pre-commit run ruff --all-files

钩子定义在仓库根目录 .pre-commit-config.yaml 中，主要执行：

• YAML/TOML 语法校验（check-yaml --unsafe、check-toml）
• 文本规范化与尾随空格修复（end-of-file-fixer、trailing-whitespace、fix-smartquotes、fix-spaces）
• 逐包格式化与 lint（ruff、mypy）：每个包（core、langchain、standard-tests、text-splitters 及全部 partners）都有独立的 local hook，例如make -C libs/core format lint只针对^libs/core/路径下的改动触发
• 版本一致性检查：check_version钩子对每个包的pyproject.toml与版本文件（如libs/core/version.py、libs/langchain_v1/langchain/__init__.py）做同步校验，防止包版本号漂移

此外钩子还包含no-commit-to-branch，禁止直接向master提交。

常见开发任务

运行单元测试

# 在任意包目录（libs/core、libs/langchain_v1 等） make test # 运行指定测试文件 make test TEST_FILE=tests/unit_tests/agents/test_factory.py # 监视模式（文件变更自动重跑） make test_watch # 运行扩展测试（标记 @pytest.mark.requires） make extended_tests

从 libs/core/Makefile 可以确认这些关键细节：

• 测试默认带socket 限制（--disable-socket --allow-unix-socket），防止意外网络调用；单元测试因此是完全离线的
• 测试通过pytest-xdist 并行运行（-n auto）
• 运行前会unset 掉 LangSmith 相关环境变量（LANGCHAIN_TRACING_V2、LANGCHAIN_API_KEY、LANGSMITH_API_KEY、LANGSMITH_TRACING、LANGCHAIN_PROJECT），保证测试隔离
• 测试路径镜像源码路径：langchain_core/runnables/base.py→tests/unit_tests/runnables/test_base.py

注意：libs/langchain_v1的make test需要先通过make start_services拉起 Docker 服务（Postgres、Redis，定义见tests/unit_tests/agents/compose-*.yml），跑完make stop_services清理；make test_fast则通过LANGGRAPH_TEST_FAST=1跳过这些外部服务依赖（见 libs/langchain_v1/Makefile）。

格式化与 Lint

# 格式化所有 Python 文件（ruff） make format # 检查 lint 问题（ruff、mypy） make lint # 仅做类型检查（mypy） make type # 只格式化改动过的文件（与 main 的 git diff） make format_diff

工具链：

• ruff：高性能 Python linter 与 formatter，统一取代 black、isort、flake8；通过uv run --group lint运行。make format内部执行ruff format后再ruff check --fix（见 libs/core/Makefile）
• mypy：静态类型检查器；通过uv run --group typing运行，使用独立缓存目录（.mypy_cache）
• 两者同时集成进 pre-commit 钩子与 make 目标

此外各包还提供lint_package（只查包体）与lint_tests（只查测试）等细分目标，并统一先执行scripts/lint_imports.sh校验导入规范。

运行集成测试

集成测试会调用真实模型 API，并将响应录制为 VCR cassettes：

# 在任意包目录 make integration_tests # 运行指定集成测试 make integration_tests TEST_FILE=tests/integration_tests/test_specific.py # 录制新的 cassettes（需要 .env 中的 API 凭证） make integration_tests RECORD=true

详细的 cassette 管理方式参见 Integration Testing 指南。cassettes 通常存放在各包的tests/cassettes/（如 libs/langchain_v1/tests/cassettes）。

提交前完整本地校验

# 在包目录内 make format && make lint && make test

或者一步到位：

cd libs/core && make format lint test

集成测试也一起跑：

cd libs/langchain_v1 && make format lint test integration_tests

快速导航：按任务路由到深度文档

下表覆盖了常见的开发任务，可直接路由到对应的 wiki 深度文档：

导航背后的源码支撑

快速导航表中提到的核心概念都能在源码中找到落点：

• Runnable / LCEL：Runnable协议与 LangChain Expression Language 定义在 libs/core/langchain_core/runnables/init.py，其模块 docstring 说明 LCEL 构建的程序天然支持同步/异步、批量与流式四种调用形态，异步支持让服务端在更高并发下弹性扩展
• BaseChatModel：定义于 libs/core/langchain_core/language_models/chat_models.py，是厂商ChatModel实现必须继承的抽象基类，同时聚合了消息归一化、输出解析、回调与模型画像等基础设施
• init_chat_model：位于 libs/langchain_v1/langchain/chat_models/base.py，其_BUILTIN_PROVIDERS注册表（见 base.py#L56-L97）把provider名称映射到(模块路径, 类名, 创建函数)三元组——例如openai → langchain_openai.ChatOpenAI、anthropic → langchain_anthropic.ChatAnthropic，并采用lru_cache缓存创建函数以避免重复导入；注册表未覆盖的厂商只要安装了对应集成包，也可通过显式model_provider参数使用

仓库结构速览

根目录

/ ├── .github/ # GitHub Actions 工作流（CI/CD） ├── .pre-commit-config.yaml # pre-commit 钩子定义 ├── .vscode/ # VS Code 设置 ├── libs/ # monorepo 主工作区 ├── AGENTS.md # 贡献指南（提 PR 前必读） └── README.md # 顶层项目概览

/libs/内部

core/— 基础抽象（langchain-core 包）

core/ ├── langchain_core/ │ ├── language_models/ # BaseChatModel 与语言模型契约 │ ├── messages/ # 消息类型与 content blocks │ ├── runnables/ # Runnable 协议与运算符 │ ├── tools/ # BaseTool 与工具工具函数 │ ├── prompts/ # 提示词模板与 few-shot │ ├── callbacks/ # Callback manager 与 handlers │ └── output_parsers/ # 输出解析与校验 ├── tests/unit_tests/ # 单元测试（无网络） ├── tests/integration_tests/ # 集成测试（真实 API） ├── Makefile # 构建目标（test、lint、format） └── pyproject.toml # 包依赖与元数据

langchain_v1/— Agent 编排（langchain 包）

langchain_v1/ ├── langchain/ │ ├── agents/ │ │ ├── factory.py # create_agent 函数 │ │ ├── middleware/ # 可插拔中间件钩子 │ │ └── structured_output.py # 响应 schema │ ├── chat_models/ │ │ └── base.py # init_chat_model 工厂 │ ├── mcp/ # Model Context Protocol │ └── ... ├── tests/unit_tests/ ├── tests/integration_tests/ ├── tests/cassettes/ # 用于 HTTP mock 的 VCR cassettes ├── Makefile └── pyproject.toml

partners/— 厂商集成

partners/ ├── openai/ # ChatOpenAI（Chat Completions 与 Responses API）、embeddings ├── anthropic/ # ChatAnthropic（Claude） ├── ollama/ # ChatOllama（本地模型） ├── groq/ # ChatGroq ├── mistralai/ # ChatMistralAI ├── huggingface/ # HuggingFace 模型/embeddings ├── deepseek/ # ChatDeepSeek └── ...（20+ 个厂商）

每个 partner 采用相同的内部结构：

provider/ ├── langchain_{provider}/ │ ├── __init__.py # 导出 ChatModel 类 │ ├── chat_models/ │ │ └── base.py # ChatModel 实现 │ └── data/ # 模型画像 ├── tests/ │ ├── unit_tests/ # 标准测试 + 自定义测试 │ └── integration_tests/ ├── pyproject.toml ├── Makefile └── uv.lock

部分厂商（如 OpenAI）支持高级 API 模式——Responses API 与结构化输出流式等细节参见 OpenAI Integration。

你的第一个 PR：完整工作流

第 1 步：挑选任务

参考上面的快速导航表决定要做什么。首次贡献者参考难度分级：

• 简单：补一个测试、修一个类型错误、改进文档
• 中等：新增一个中间件钩子、扩展工具接口
• 困难：新增一个厂商集成（遵循 Adding a Chat Model Provider）

第 2 步：阅读贡献指南

动手写代码之前，先读：

• AGENTS.md— 约定、风格与 PR 期望
• 相关的 wiki 页面— 你所在领域的深度上下文（见上方导航表）

第 3 步：设置你的包环境

cd libs/{core|langchain_v1|partners/provider} uv sync --all-groups pre-commit install

第 4 步：做出修改

遵循代码库中已有的风格与模式，使用类型注解，并与代码同步编写测试。注意 langchain_v1 包的make test需要 Docker 服务（make start_services拉起 Postgres/Redis），而 core 包测试完全离线。

第 5 步：运行本地检查

make format lint test

推送前所有检查必须通过。

第 6 步：提交与推送

遵循带 scope 的 Conventional Commits 格式（必填）：

git add . # 格式：type(scope): description # 示例：feat(core): add streaming support to BaseChatModel # 示例：fix(openai): handle timeout errors gracefully git commit -m "type(scope): description" git push origin your-branch

分支命名遵循<username>/<scope>/<description>约定（详见 AGENTS.md）。pre-commit 钩子会自动运行；若失败，修复后重新提交。

第 7 步：打开 Pull Request

将 PR 关联到相关 issue，并在描述中引用你读过的 wiki 页面。LangChain 团队会 review 并给出反馈。

必须了解的关键文件

其中libs/Makefile的lock目标会遍历 core、text-splitters、langchain、langchain_v1、model-profiles 五个包逐个执行uv lock，check-lock则逐个执行uv lock --check校验锁定文件是否过期（见 libs/Makefile）。

故障排查

测试报 Socket 错误

测试默认启用 socket 限制。若确实需要网络访问：

• 将用例写入tests/integration_tests/（见 Integration Testing）
• 或者本地临时关闭 socket 限制：uv run --group test pytest --disable-socket=false ...

导入错误或版本不一致

重新生成 lockfile：

cd libs make lock

或仅针对单个包：

cd libs/core uv lock

版本一致性由 pre-commit 的check_version钩子守护，若钩子拦截说明pyproject.toml与版本文件不同步，用上述命令重新锁定即可。

类型检查失败

运行 mypy 查看详细错误：

make type

参考 Chat Models 或 Runnables 页面了解类型签名模式。

Pre-Commit 钩子阻止提交

pre-commit 会自动修复格式与部分问题，重新暂存并提交：

git add . git commit -m "..." # 再试一次

若 lint 仍失败，运行make lint查看细节并手动修复。

快速命令参考

# 设置 uv sync --all-groups # 安装全部依赖 pre-commit install # 配置 git 钩子 # 测试 make test # 运行单元测试 make test TEST_FILE=path/ # 运行指定测试文件 make test_watch # 监视模式（自动重跑） make integration_tests # 运行集成测试 # 代码质量 make format # 格式化代码（ruff） make lint # 检查 lint（ruff、mypy） make type # 仅类型检查（mypy） # Lockfile 管理 cd libs && make lock # 重新生成全部 lockfile cd libs && make check-lock # 校验 lockfile 是否最新 # 提 PR 前全部检查 make format && make lint && make test

下一步

1. 阅读AGENTS.md了解贡献约定
2. 从快速导航表中挑选与你任务匹配的 wiki 页面
3. 克隆仓库、完成环境设置，做出第一个改动
4. 本地运行make format lint test校验
5. 打开 PR 并与团队交流

欢迎加入 LangChain 开发！

• 人工智能
• 大模型
• AI Agent
• Agent 框架
• RAG