{ "canonical_name": "langchain-ai/langchainjs", "compilation_id": "pack_bebaec13f7f646f7b64fa3c57c722c38", "created_at": "2026-05-16T05:46:08.633914+00:00", "created_by": "project-pack-compiler", "feedback": { "carrier_selection_notes": [ "viable_asset_types=skill, recipe, host_instruction, eval, preflight", "recommended_asset_types=skill, recipe, host_instruction, eval, preflight" ], "evidence_delta": { "confirmed_claims": [ "identity_anchor_present", "capability_and_host_targets_present", "install_path_declared_or_better" ], "missing_required_fields": [], "must_verify_forwarded": [ "Run or inspect `npm install -S langchain` in an isolated environment.", "Confirm the project exposes the claimed capability to at least one target host." ], "quickstart_execution_scope": "allowlisted_sandbox_smoke", "sandbox_command": "npm install -S langchain", "sandbox_container_image": "node:22-slim", "sandbox_execution_backend": "docker", "sandbox_planner_decision": "deterministic_isolated_install", "sandbox_validation_id": "sbx_12e0143db7ae48dea96afb97fc1cfc85" }, "feedback_event_type": "project_pack_compilation_feedback", "learning_candidate_reasons": [], "template_gaps": [] }, "identity": { "canonical_id": "project_6160c3635a7917b10fa436d58b5e216c", "canonical_name": "langchain-ai/langchainjs", "homepage_url": null, "license": "unknown", "repo_url": "https://github.com/langchain-ai/langchainjs", "slug": "langchainjs", "source_packet_id": "phit_c673851771da42b0b5c4fca4701e4fed", "source_validation_id": "dval_d18ecddff9bf424e9e8c59d6cb1811bd" }, "merchandising": { "best_for": "需要软件开发与交付能力，并使用 local_cli的用户", "github_forks": 3167, "github_stars": 17672, "one_liner_en": "The agent engineering platform", "one_liner_zh": "The agent engineering platform", "primary_category": { "category_id": "software-development", "confidence": "medium", "name_en": "Software Development", "name_zh": "软件开发与交付", "reason": "matched_keywords:git, cli" }, "target_user": "使用 local_cli 等宿主 AI 的用户", "title_en": "langchainjs", "title_zh": "langchainjs 能力包", "visible_tags": [ { "label_en": "Browser Agents", "label_zh": "浏览器 Agent", "source": "repo_evidence_project_characteristics", "tag_id": "product_domain-browser-agents", "type": "product_domain" }, { "label_en": "Web Task Automation", "label_zh": "网页任务自动化", "source": "repo_evidence_project_characteristics", "tag_id": "user_job-web-task-automation", "type": "user_job" }, { "label_en": "Browser Automation", "label_zh": "浏览器自动化", "source": "repo_evidence_project_characteristics", "tag_id": "core_capability-browser-automation", "type": "core_capability" }, { "label_en": "Multi-role Workflow", "label_zh": "多角色协作流程", "source": "repo_evidence_project_characteristics", "tag_id": "workflow_pattern-multi-role-workflow", "type": "workflow_pattern" }, { "label_en": "Evaluation Suite", "label_zh": "评测体系", "source": "repo_evidence_project_characteristics", "tag_id": "selection_signal-evaluation-suite", "type": "selection_signal" } ] }, "packet_id": "phit_c673851771da42b0b5c4fca4701e4fed", "page_model": { "artifacts": { "artifact_slug": "langchainjs", "files": [ "PROJECT_PACK.json", "QUICK_START.md", "PROMPT_PREVIEW.md", "HUMAN_MANUAL.md", "AI_CONTEXT_PACK.md", "BOUNDARY_RISK_CARD.md", "PITFALL_LOG.md", "REPO_INSPECTION.json", "REPO_INSPECTION.md", "CAPABILITY_CONTRACT.json", "EVIDENCE_INDEX.json", "CLAIM_GRAPH.json" ], "required_files": [ "PROJECT_PACK.json", "QUICK_START.md", "PROMPT_PREVIEW.md", "HUMAN_MANUAL.md", "AI_CONTEXT_PACK.md", "BOUNDARY_RISK_CARD.md", "PITFALL_LOG.md", "REPO_INSPECTION.json" ] }, "detail": { "capability_source": "Project Hit Packet + DownstreamValidationResult", "commands": [ { "command": "npm install -S langchain", "label": "Node.js / npm · 官方安装入口", "source": "https://github.com/langchain-ai/langchainjs#readme", "verified": true } ], "display_tags": [ "浏览器 Agent", "网页任务自动化", "浏览器自动化", "多角色协作流程", "评测体系" ], "eyebrow": "软件开发与交付", "glance": [ { "body": "判断自己是不是目标用户。", "label": "最适合谁", "value": "需要软件开发与交付能力，并使用 local_cli的用户" }, { "body": "先理解能力边界，再决定是否继续。", "label": "核心价值", "value": "The agent engineering platform" }, { "body": "未完成验证前保持审慎。", "label": "继续前", "value": "publish to Doramagic.ai project surfaces" } ], "guardrail_source": "Boundary & Risk Card", "guardrails": [ { "body": "Prompt Preview 只展示流程，不证明项目已安装或运行。", "label": "Check 1", "value": "不要把试用当真实运行" }, { "body": "local_cli", "label": "Check 2", "value": "确认宿主兼容" }, { "body": "publish to Doramagic.ai project surfaces", "label": "Check 3", "value": "先隔离验证" } ], "mode": "skill, recipe, host_instruction, eval, preflight", "pitfall_log": { "items": [ { "body": "GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[Feature request] React Native support", "category": "配置坑", "evidence": [ "community_evidence:github | cevd_39933028ef894033b30ff784e81f185f | https://github.com/langchain-ai/langchainjs/issues/4239 | 来源类型 github_issue 暴露的待验证使用条件。" ], "severity": "high", "suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。", "title": "来源证据：[Feature request] React Native support", "user_impact": "可能增加新用户试用和生产接入成本。" }, { "body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：@langchain/core@1.1.46", "category": "安装坑", "evidence": [ "community_evidence:github | cevd_36a7a58d5cd84bda8dde7918402a6f8a | https://github.com/langchain-ai/langchainjs/releases/tag/%40langchain/core%401.1.46 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。" ], "severity": "medium", "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。", "title": "来源证据：@langchain/core@1.1.46", "user_impact": "可能增加新用户试用和生产接入成本。" }, { "body": "GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Must pass in at least 1 record to upsert.", "category": "配置坑", "evidence": [ "community_evidence:github | cevd_26c3acaad9e14ed3953206f25870c0b0 | https://github.com/langchain-ai/langchainjs/issues/10890 | 来源讨论提到 node 相关条件，需在安装/试用前复核。" ], "severity": "medium", "suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。", "title": "来源证据：Must pass in at least 1 record to upsert.", "user_impact": "可能增加新用户试用和生产接入成本。" }, { "body": "README/documentation is current enough for a first validation pass.", "category": "能力坑", "evidence": [ "capability.assumptions | github_repo:598342280 | https://github.com/langchain-ai/langchainjs | README/documentation is current enough for a first validation pass." ], "severity": "medium", "suggested_check": "将假设转成下游验证清单。", "title": "能力判断依赖假设", "user_impact": "假设不成立时，用户拿不到承诺的能力。" }, { "body": "未记录 last_activity_observed。", "category": "维护坑", "evidence": [ "evidence.maintainer_signals | github_repo:598342280 | https://github.com/langchain-ai/langchainjs | last_activity_observed missing" ], "severity": "medium", "suggested_check": "补 GitHub 最近 commit、release、issue/PR 响应信号。", "title": "维护活跃度未知", "user_impact": "新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。" }, { "body": "no_demo", "category": "安全/权限坑", "evidence": [ "downstream_validation.risk_items | github_repo:598342280 | https://github.com/langchain-ai/langchainjs | no_demo; severity=medium" ], "severity": "medium", "suggested_check": "进入安全/权限治理复核队列。", "title": "下游验证发现风险项", "user_impact": "下游已经要求复核，不能在页面中弱化。" }, { "body": "no_demo", "category": "安全/权限坑", "evidence": [ "risks.scoring_risks | github_repo:598342280 | https://github.com/langchain-ai/langchainjs | no_demo; severity=medium" ], "severity": "medium", "suggested_check": "把风险写入边界卡，并确认是否需要人工复核。", "title": "存在评分风险", "user_impact": "风险会影响是否适合普通用户安装。" }, { "body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：bug(@langchain/openai): Bare JSON.parse in Responses API converter crashes on structured output with trailing characters", "category": "安全/权限坑", "evidence": [ "community_evidence:github | cevd_4d2a6bed33284a3cbd2f3319321d9e4c | https://github.com/langchain-ai/langchainjs/issues/10894 | 来源讨论提到 node 相关条件，需在安装/试用前复核。" ], "severity": "medium", "suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。", "title": "来源证据：bug(@langchain/openai): Bare JSON.parse in Responses API converter crashes on structured output with trailing characters", "user_impact": "可能阻塞安装或首次运行。" }, { "body": "issue_or_pr_quality=unknown。", "category": "维护坑", "evidence": [ "evidence.maintainer_signals | github_repo:598342280 | https://github.com/langchain-ai/langchainjs | issue_or_pr_quality=unknown" ], "severity": "low", "suggested_check": "抽样最近 issue/PR，判断是否长期无人处理。", "title": "issue/PR 响应质量未知", "user_impact": "用户无法判断遇到问题后是否有人维护。" }, { "body": "release_recency=unknown。", "category": "维护坑", "evidence": [ "evidence.maintainer_signals | github_repo:598342280 | https://github.com/langchain-ai/langchainjs | release_recency=unknown" ], "severity": "low", "suggested_check": "确认最近 release/tag 和 README 安装命令是否一致。", "title": "发布节奏不明确", "user_impact": "安装命令和文档可能落后于代码，用户踩坑概率升高。" } ], "source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals", "summary": "发现 10 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：配置坑 - 来源证据：[Feature request] React Native support。", "title": "踩坑日志" }, "snapshot": { "contributors": 1079, "forks": 3167, "license": "unknown", "note": "站点快照，非实时质量证明；用于开工前背景判断。", "stars": 17672 }, "source_url": "https://github.com/langchain-ai/langchainjs", "steps": [ { "body": "不安装项目，先体验能力节奏。", "code": "preview", "title": "先试 Prompt" }, { "body": "理解输入、输出、失败模式和边界。", "code": "manual", "title": "读说明书" }, { "body": "把上下文交给宿主 AI 继续工作。", "code": "context", "title": "带给 AI" }, { "body": "进入主力环境前先完成安装入口与风险边界验证。", "code": "verify", "title": "沙箱验证" } ], "subtitle": "The agent engineering platform", "title": "langchainjs 能力包", "trial_prompt": "# langchainjs - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 langchainjs 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的软件开发与交付任务。\n我常用的宿主 AI：Local CLI\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 示例引导, 判断线索。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- 安装前能力预览: The agent engineering platform 输入：用户任务, 当前 AI 对话上下文；输出：示例引导, 判断线索。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. page-1：项目概述与生态系统。围绕“项目概述与生态系统”模拟一次用户任务，不展示安装或运行结果。\n2. page-2：系统架构与核心抽象。围绕“系统架构与核心抽象”模拟一次用户任务，不展示安装或运行结果。\n3. page-3：Agent 与 Chains 实现。围绕“Agent 与 Chains 实现”模拟一次用户任务，不展示安装或运行结果。\n4. page-4：向量存储与检索系统。围绕“向量存储与检索系统”模拟一次用户任务，不展示安装或运行结果。\n5. page-5：主要模型提供商集成。围绕“主要模型提供商集成”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. page-1\n输入：用户提供的“项目概述与生态系统”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. page-2\n输入：用户提供的“系统架构与核心抽象”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. page-3\n输入：用户提供的“Agent 与 Chains 实现”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. page-4\n输入：用户提供的“向量存储与检索系统”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. page-5\n输入：用户提供的“主要模型提供商集成”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / page-1：Step 1 必须围绕“项目概述与生态系统”形成一个小中间产物，并等待用户确认。\n- Step 2 / page-2：Step 2 必须围绕“系统架构与核心抽象”形成一个小中间产物，并等待用户确认。\n- Step 3 / page-3：Step 3 必须围绕“Agent 与 Chains 实现”形成一个小中间产物，并等待用户确认。\n- Step 4 / page-4：Step 4 必须围绕“向量存储与检索系统”形成一个小中间产物，并等待用户确认。\n- Step 5 / page-5：Step 5 必须围绕“主要模型提供商集成”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/langchain-ai/langchainjs\n- https://github.com/langchain-ai/langchainjs#readme\n- README.md\n- libs/langchain-core/README.md\n- libs/langchain/README.md\n- libs/langchain-classic/README.md\n- libs/langchain-core/src/runnables/base.ts\n- libs/langchain-core/src/callbacks/base.ts\n- libs/langchain-core/src/memory.ts\n- libs/langchain-core/src/tools/index.ts\n- libs/langchain-core/src/language_models/chat_models.ts\n- libs/langchain-core/src/vectorstores.ts\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 langchainjs 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n", "voices": [ { "body": "来源平台：github。github/github_issue: [Feature request] React Native support（https://github.com/langchain-ai/langchainjs/issues/4239）；github/github_issue: bug(@langchain/openai): Bare JSON.parse in Responses API converter crash（https://github.com/langchain-ai/langchainjs/issues/10894）；github/github_issue: Must pass in at least 1 record to upsert.（https://github.com/langchain-ai/langchainjs/issues/10890）；github/github_release: @langchain/core@1.1.46（https://github.com/langchain-ai/langchainjs/releases/tag/%40langchain/core%401.1.46）；github/github_release: @langchain/core@1.1.41（https://github.com/langchain-ai/langchainjs/releases/tag/%40langchain/core%401.1.41）；github/github_release: @langchain/anthropic@1.3.27（https://github.com/langchain-ai/langchainjs/releases/tag/%40langchain/anthropic%401.3.27）。这些是项目级外部声音，不作为单独质量证明。", "items": [ { "kind": "github_issue", "source": "github", "title": "[Feature request] React Native support", "url": "https://github.com/langchain-ai/langchainjs/issues/4239" }, { "kind": "github_issue", "source": "github", "title": "bug(@langchain/openai): Bare JSON.parse in Responses API converter crash", "url": "https://github.com/langchain-ai/langchainjs/issues/10894" }, { "kind": "github_issue", "source": "github", "title": "Must pass in at least 1 record to upsert.", "url": "https://github.com/langchain-ai/langchainjs/issues/10890" }, { "kind": "github_release", "source": "github", "title": "@langchain/core@1.1.46", "url": "https://github.com/langchain-ai/langchainjs/releases/tag/%40langchain/core%401.1.46" }, { "kind": "github_release", "source": "github", "title": "@langchain/core@1.1.41", "url": "https://github.com/langchain-ai/langchainjs/releases/tag/%40langchain/core%401.1.41" }, { "kind": "github_release", "source": "github", "title": "@langchain/anthropic@1.3.27", "url": "https://github.com/langchain-ai/langchainjs/releases/tag/%40langchain/anthropic%401.3.27" } ], "status": "已收录 6 条来源", "title": "社区讨论" } ] }, "homepage_card": { "category": "软件开发与交付", "desc": "The agent engineering platform", "effort": "安装已验证", "forks": 3167, "icon": "code", "name": "langchainjs 能力包", "risk": "可发布", "slug": "langchainjs", "stars": 17672, "tags": [ "浏览器 Agent", "网页任务自动化", "浏览器自动化", "多角色协作流程", "评测体系" ], "thumb": "gray", "type": "Skill Pack" }, "manual": { "markdown": "# https://github.com/langchain-ai/langchainjs 项目说明书\n\n生成时间：2026-05-16 04:29:18 UTC\n\n## 目录\n\n- [项目概述与生态系统](#page-1)\n- [系统架构与核心抽象](#page-2)\n- [Agent 与 Chains 实现](#page-3)\n- [向量存储与检索系统](#page-4)\n- [主要模型提供商集成](#page-5)\n- [扩展提供商与工具集成](#page-6)\n- [多环境部署支持](#page-7)\n- [依赖管理与测试策略](#page-8)\n- [扩展开发指南](#page-9)\n- [示例代码与最佳实践](#page-10)\n\n\n\n## 项目概述与生态系统\n\n### 相关页面\n\n相关主题：[系统架构与核心抽象](#page-2), [主要模型提供商集成](#page-5)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/langchain-ai/langchainjs/blob/main/README.md)\n- [libs/langchain-core/README.md](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-core/README.md)\n- [libs/langchain/README.md](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain/README.md)\n- [libs/langchain-classic/README.md](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-classic/README.md)\n- [libs/langchain-textsplitters/README.md](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-textsplitters/README.md)\n- [libs/create-langchain-integration/template/README.md](https://github.com/langchain-ai/langchainjs/blob/main/libs/create-langchain-integration/template/README.md)\n
\n\n# 项目概述与生态系统\n\nLangChain.js 是一个用于构建 LLM 驱动应用的框架，旨在通过可组合性简化 AI 应用开发过程。它帮助开发者将可互操作的组件和第三方集成链在一起，同时为底层技术演进提供未来保障。\n\n## 核心定位与价值主张\n\nLangChain.js 的核心价值在于提供一个灵活的框架，使开发者能够：\n\n- **链式组合**：将多个组件组合成复杂的工作流\n- **第三方集成**：轻松接入各种 LLM 提供商和工具\n- **模块化设计**：各组件独立可替换，便于维护和升级\n- **开发效率**：提供开箱即用的抽象，加速应用开发\n\n## 生态系统架构\n\nLangChain.js 采用多包架构，将不同功能模块分离到独立的包中，以提高可维护性和灵活度。\n\n```mermaid\ngraph TD\n A[用户应用] --> B[langchain 主包]\n A --> C[@langchain/classic 经典包]\n B --> D[@langchain/core 核心包]\n C --> D\n B --> E[@langchain/textsplitters 文本分割]\n D --> F[Provider 包]\n F --> G[langchain-openai]\n F --> H[langchain-anthropic]\n F --> I[langchain-google-common]\n```\n\n## 核心包结构\n\n### @langchain/core 核心包\n\n`@langchain/core` 是整个生态系统的基础库，定义了 LangChain 的核心抽象和接口。它包含：\n\n- **消息系统**：定义各种消息类型和消息处理逻辑\n- **语言模型接口**：统一的 LLM 调用抽象\n- **工具系统**：定义工具的创建和调用方式\n- **输出解析器**：将 LLM 输出解析为结构化数据\n- **事件系统**：支持流式事件和状态更新\n\n资料来源：[libs/langchain-core/README.md]()\n\n### langchain 主包\n\n`langchain` 是面向现代 Agent 开发的主包，提供了构建 AI Agent 的高级 API。\n\n#### 主要特性\n\n| 特性 | 描述 |\n|------|------|\n| createAgent | 创建 Agent 的主要入口 |\n| 中间件支持 | 支持 HITL 等中间件功能 |\n| 工具集成 | 内置工具调用和工具管理 |\n\n#### Agent 架构\n\n```mermaid\ngraph LR\n A[用户输入] --> B[Agent 核心]\n B --> C[工具调用]\n C --> D[外部服务]\n D --> B\n B --> E[响应输出]\n```\n\n`langchain` 包支持通过中间件扩展功能，例如人机交互中间件（Human-in-the-Loop），允许在 Agent 执行过程中进行干预和控制。\n\n资料来源：[libs/langchain/README.md](), [libs/langchain/src/agents/middleware/hitl.ts:1-100]()\n\n### @langchain/classic 经典包\n\n`@langchain/classic` 是为了向后兼容而保留的包，包含从 LangChain v0.x 移出的功能。\n\n#### 何时使用\n\n建议使用 `@langchain/classic` 的场景：\n\n| 场景 | 说明 |\n|------|------|\n| 遗留链 | 使用 `LLMChain`、`ConversationalRetrievalQAChain` 等 |\n| 索引 API | 使用文档索引和向量存储功能 |\n| 社区集成 | 依赖之前从 `langchain` 重新导出的社区功能 |\n| 应用迁移 | 维护现有应用，尚未准备好迁移到新 API |\n\n#### 何时不使用\n\n**对于新项目，应使用 langchain v1.0**，新 API 提供：\n\n- 更清晰的 `createAgent` 构建方式\n- 更好的性能优化\n- 更聚焦的 API 表面\n- 活跃的开发支持\n\n#### 迁移路径\n\n```typescript\n// 旧导入（已弃用）\nimport { LLMChain } from \"langchain\";\n\n// 新导入\nimport { LLMChain } from \"@langchain/classic\";\n```\n\n资料来源：[libs/langchain-classic/README.md](), [libs/langchain-classic/src/util/entrypoint_deprecation.ts:1-50]()\n\n### @langchain/textsplitters 文本分割包\n\n`@langchain/textsplitters` 提供各种文本分割器实现，是 RAG（检索增强生成）管道的常用组件。\n\n#### 支持的分割模式\n\n| 语言 | 说明 |\n|------|------|\n| html | HTML 特定的分块策略 |\n| javascript | JavaScript 代码分割 |\n| typescript | TypeScript 代码分割 |\n| markdown | Markdown 文档分割 |\n| python | Python 代码分割 |\n| json | JSON 数据分割 |\n\n#### 基本使用\n\n```typescript\nimport { RecursiveCharacterTextSplitter } from \"@langchain/textsplitters\";\n\nconst splitter = RecursiveCharacterTextSplitter.fromLanguage(\"html\", {\n chunkSize: 175,\n chunkOverlap: 20,\n});\n\nconst output = await splitter.createDocuments([htmlText]);\n```\n\n资料来源：[libs/langchain-textsplitters/README.md](), [examples/src/langchain-classic/indexes/html_text_splitter.ts:1-50]()\n\n## Provider 包生态\n\nProvider 包提供了与各个 LLM 服务商的集成。\n\n### 主要 Provider\n\n| Provider | 包名 | 功能 |\n|----------|------|------|\n| OpenAI | langchain-openai | GPT 系列模型集成 |\n| Anthropic | langchain-anthropic | Claude 模型集成 |\n| Google | langchain-google-common | Google AI 集成 |\n\n### Provider 架构\n\n```mermaid\ngraph TD\n A[统一接口] --> B[langchain-core]\n B --> C[OpenAI 适配器]\n B --> D[Anthropic 适配器]\n B --> E[Google 适配器]\n C --> F[OpenAI API]\n D --> G[Anthropic API]\n E --> H[Google API]\n```\n\n每个 Provider 包都实现了统一的接口规范，确保应用可以在不同 LLM 之间切换而不需要大量代码改动。\n\n资料来源：[libs/providers/langchain-openai/src/chat_models/index.ts](), [libs/providers/langchain-anthropic/src/chat_models.ts](), [libs/providers/langchain-google-common/src/utils/anthropic.ts]()\n\n### 工具调用支持\n\nProvider 包普遍支持：\n\n- **函数调用**：通过 `withStructuredOutput()` 实现结构化输出\n- **工具使用**：内置工具调用和工具管理\n- **流式处理**：支持流式响应和增量输出\n\n```typescript\nimport { tool } from \"@langchain/core/tools\";\nimport { z } from \"zod\";\n\nconst getWeather = tool(\n async (input) => `Weather in ${input.location}`,\n {\n name: \"get_weather\",\n description: \"Get weather for a location\",\n schema: z.object({ location: z.string() }),\n }\n);\n```\n\n## 开发工具与模板\n\n### 创建新集成\n\n`create-langchain-integration` 提供了创建新 Provider 包的标准模板：\n\n```bash\nnpm install @langchain/\n```\n\n新包需要配置与 `@langchain/core` 的版本对齐：\n\n```json\n{\n \"dependencies\": {\n \"@langchain/\": \"^0.0.0\",\n \"@langchain/core\": \"^0.3.0\"\n },\n \"resolutions\": {\n \"@langchain/core\": \"^0.3.0\"\n }\n}\n```\n\n资料来源：[libs/create-langchain-integration/template/README.md]()\n\n## 核心抽象与接口\n\n### 消息系统\n\nLangChain.js 定义了完整的消息类型体系：\n\n| 类型 | 说明 |\n|------|------|\n| HumanMessage | 用户消息 |\n| AIMessage | AI 响应消息 |\n| SystemMessage | 系统级指令 |\n| ToolMessage | 工具执行结果 |\n\n```typescript\nimport { AIMessageChunk } from '@langchain/core/messages';\nimport { concat } from '@langchain/core/utils';\n```\n\n资料来源：[libs/langchain-core/src/messages/block_translators/openai.ts](), [libs/langchain-core/src/testing/matchers.ts:1-100]()\n\n### 事件系统\n\n核心库提供了完整的事件系统，支持流式处理和状态追踪：\n\n| 事件类型 | 说明 |\n|----------|------|\n| content-block-delta | 内容块增量更新 |\n| content-block-finish | 内容块完成 |\n| usage | 使用量更新 |\n| provider | 原始 Provider 事件 |\n\n```typescript\ninterface ContentBlockDeltaEvent {\n event: \"content-block-delta\";\n index: number;\n delta: ContentBlockDelta;\n}\n```\n\n资料来源：[libs/langchain-core/src/language_models/event.ts]()\n\n### 索引系统\n\nLangChain.js 提供了文档索引的基础设施，用于 RAG 场景：\n\n```mermaid\ngraph LR\n A[文档] --> B[DocumentLoader]\n B --> C[TextSplitter]\n C --> D[Document 数组]\n D --> E[RecordManager]\n D --> F[VectorStore]\n```\n\n索引功能使用 RecordManager 追踪文档状态，支持增量更新和删除管理。\n\n资料来源：[libs/langchain-core/src/indexing/base.ts]()\n\n## 版本演进与兼容性\n\n### v1.0 架构变化\n\nLangChain v1.0 进行了重要的架构调整：\n\n1. **核心功能下沉**：`@langchain/core` 成为基础抽象层\n2. **功能分离**：`@langchain/classic` 承接遗留功能\n3. **现代 API**：`langchain` 主包专注于 Agent 构建\n4. **Provider 解耦**：各 Provider 独立维护\n\n### 弃用警告\n\n导入路径迁移会产生弃用警告：\n\n```typescript\n// 旧路径\nimport { SomeClass } from \"langchain\";\n\n// 新路径\nimport { SomeClass } from \"@langchain/classic\";\n```\n\n可通过环境变量抑制警告：\n\n```bash\nLANGCHAIN_SUPPRESS_MIGRATION_WARNINGS=true\n```\n\n资料来源：[libs/langchain-classic/src/util/entrypoint_deprecation.ts]()\n\n## 安装与依赖管理\n\n### 推荐的依赖配置\n\n为确保各包之间的 `@langchain/core` 版本一致，建议在项目中添加版本锁定：\n\n```json\n{\n \"resolutions\": {\n \"@langchain/core\": \"^0.3.0\"\n },\n \"overrides\": {\n \"@langchain/core\": \"^0.3.0\"\n },\n \"pnpm\": {\n \"overrides\": {\n \"@langchain/core\": \"^0.3.0\"\n }\n }\n}\n```\n\n### 开发依赖\n\n克隆仓库后的标准开发流程：\n\n```bash\npnpm install\npnpm build\npnpm test\npnpm lint && pnpm format\n```\n\n资料来源：[libs/langchain-textsplitters/README.md](), [libs/create-langchain-integration/template/README.md]()\n\n## 总结\n\nLangChain.js 生态系统通过模块化设计提供了灵活的 LLM 应用构建能力：\n\n- **核心层**：`@langchain/core` 提供统一抽象\n- **主包**：`langchain` 专注现代 Agent 开发\n- **兼容层**：`@langchain/classic` 支持平滑迁移\n- **集成层**：多种 Provider 包连接各 LLM 服务商\n- **工具层**：文本分割等实用工具支持 RAG 场景\n\n这种架构既保证了新项目的开发效率，也照顾了现有代码的向后兼容性，使 LangChain.js 成为构建 LLM 应用的可靠选择。\n\n---\n\n\n\n## 系统架构与核心抽象\n\n### 相关页面\n\n相关主题：[项目概述与生态系统](#page-1), [Agent 与 Chains 实现](#page-3)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [libs/langchain-core/src/runnables/base.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-core/src/runnables/base.ts)\n- [libs/langchain-core/src/callbacks/base.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-core/src/callbacks/base.ts)\n- [libs/langchain-core/src/memory.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-core/src/memory.ts)\n- [libs/langchain-core/src/tools/index.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-core/src/tools/index.ts)\n- [libs/langchain-core/src/language_models/chat_models.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-core/src/language_models/chat_models.ts)\n- [libs/langchain-core/src/vectorstores.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-core/src/vectorstores.ts)\n
\n\n# 系统架构与核心抽象\n\n## 概述\n\nLangChain.js 的系统架构采用模块化设计，核心抽象层位于 `@langchain/core` 包中，为上层应用提供统一的接口和组件。架构设计遵循以下原则：可组合性、可扩展性和类型安全。整个系统以 **Runnable** 抽象为核心，构建了一套完整的大语言模型应用开发框架。\n\nLangChain.js 的核心抽象主要包括：Runnable 执行单元、Callbacks 事件系统、Memory 记忆管理、Tools 工具系统、Chat Models 聊天模型接口，以及 Vector Stores 向量存储接口。这些抽象共同构成了构建复杂 LLM 应用的基石。\n\n## 核心架构图\n\n```mermaid\ngraph TB\n subgraph \"核心抽象层 @langchain/core\"\n Runnable[Runnable 执行单元]\n Callbacks[Callbacks 事件系统]\n Memory[Memory 记忆管理]\n Tools[Tools 工具系统]\n ChatModels[Chat Models 接口]\n VectorStores[Vector Stores 接口]\n end\n \n subgraph \"应用层\"\n Agents[Agent 代理]\n Chains[Chain 链]\n VectorRetrieval[向量检索]\n end\n \n subgraph \"集成层\"\n Providers[第三方集成]\n end\n \n Runnable --> Callbacks\n Runnable --> Memory\n Runnable --> Tools\n Runnable --> ChatModels\n Runnable --> VectorStores\n \n Agents --> Runnable\n Chains --> Runnable\n VectorRetrieval --> VectorStores\n \n Providers --> ChatModels\n Providers --> Tools\n Providers --> VectorStores\n```\n\n## Runnable 执行单元\n\n### 设计理念\n\n**Runnable** 是 LangChain.js 最核心的抽象，它代表了任何可以被执行的组件。所有的 Chain、Agent、Tool、Memory 等都实现或扩展了 Runnable 接口。这种设计使得系统中的任意组件都可以被统一地组合、管道化和执行。\n\nRunnable 接口定义了一套标准的执行方法，包括同步调用、批量处理、流式输出等。这确保了无论组件的具体实现如何，调用者都可以用统一的方式与它们交互。\n\n### 核心接口方法\n\n| 方法名 | 说明 | 返回类型 |\n|--------|------|----------|\n| `invoke(input)` | 同步执行单个输入 | `Output` |\n| `batch(inputs)` | 批量处理多个输入 | `Output[]` |\n| `stream(input)` | 流式输出 | `AsyncGenerator` |\n| `pipe(destination)` | 管道连接到另一个 Runnable | `Runnable` |\n| `bind(config)` | 绑定运行时配置 | `Runnable` |\n\n### 可组合性\n\n```mermaid\ngraph LR\n A[输入] --> B[Prompt]\n B --> C[LLM]\n C --> D[Output Parser]\n D --> E[最终结果]\n \n style B fill:#e1f5fe\n style C fill:#fff3e0\n style D fill:#e8f5e8\n```\n\nRunnable 支持两种组合方式：顺序组合和并行组合。顺序组合通过 `pipe()` 方法实现，将前一个 Runnable 的输出作为下一个 Runnable 的输入。并行组合则可以将多个 Runnable 同时应用于同一输入，然后合并结果。\n\n## Callbacks 事件系统\n\n### 架构设计\n\nCallbacks 系统提供了一套完整的事件通知机制，允许在 Runnable 执行过程中的各个阶段插入自定义逻辑。这种设计实现了关注点分离：核心逻辑与监控、调试、日志记录等辅助功能解耦。\n\n事件系统采用发布-订阅模式，定义了清晰的事件生命周期钩子。开发者可以通过实现 `CallbackHandler` 接口来订阅感兴趣的事件，并在事件触发时执行相应操作。\n\n### 主要事件类型\n\n| 事件名称 | 触发时机 | 典型用途 |\n|----------|----------|----------|\n| `handleStart` | Runnable 开始执行 | 记录开始时间 |\n| `handleEnd` | Runnable 完成执行 | 记录结束时间、收集结果 |\n| `handleError` | 执行过程中发生错误 | 错误日志、告警通知 |\n| `handleText` | 输出文本片段 | 实时显示、流式输出 |\n| `handleChainStart` | Chain 开始执行 | 追踪调用链 |\n| `handleChainEnd` | Chain 完成执行 | 性能监控 |\n\n### 使用场景\n\nCallbacks 系统常用于以下场景：\n\n1. **性能监控**：测量各个 Runnable 的执行时间\n2. **日志记录**：记录完整的调用链和中间结果\n3. **流式输出**：实时处理模型生成的内容片段\n4. **调试开发**：在执行过程中输出中间状态\n5. **成本追踪**：统计 token 使用量和 API 调用次数\n\n## Memory 记忆管理\n\n### 抽象接口\n\nMemory 接口定义了与对话历史交互的标准方式。它允许 Chain 和 Agent 在多次调用之间保持状态，实现真正的多轮对话能力。Memory 的设计独立于具体的存储后端，支持内存、数据库、文件系统等多种实现。\n\n```mermaid\nsequenceDiagram\n participant User as 用户\n participant Chain as Chain\n participant Memory as Memory\n \n User->>Chain: 第一轮输入\n Chain->>Memory: 读取历史\n Memory-->>Chain: 历史消息\n Chain->>LLM: 组合输入\n LLM-->>Chain: 响应\n Chain->>Memory: 保存对话\n Chain-->>User: 返回结果\n \n User->>Chain: 第二轮输入\n Chain->>Memory: 读取历史\n Memory-->>Chain: 历史消息\n Chain->>LLM: 组合输入\n LLM-->>Chain: 响应\n Chain->>Memory: 保存对话\n Chain-->>User: 返回结果\n```\n\n### 核心方法\n\n| 方法名 | 说明 |\n|--------|------|\n| `loadMemoryVariables()` | 加载当前记忆变量 |\n| `saveContext(inputs, outputs)` | 保存输入输出对到记忆 |\n| `clear()` | 清除所有记忆内容 |\n\nMemory 系统支持多种实现方式，包括基础缓冲记忆、会话窗口记忆、摘要记忆等。开发者可以根据应用需求选择合适的记忆策略，或实现自定义的 Memory 类。\n\n## Tools 工具系统\n\n### 工具定义接口\n\nTools 系统允许 LLM 调用外部函数和 API，扩展了模型的能力边界。每个 Tool 都是一个独立的 Runnable，具有明确定义的输入模式（通过 Zod schema 定义）和返回值格式。\n\n```mermaid\ngraph TD\n LLM[LLM] -->|决定调用| ToolCall[Tool Call]\n ToolCall --> Tool[Tool 执行]\n Tool --> Result[结果]\n Result --> LLM\n \n subgraph \"Tool 定义\"\n Name[名称]\n Desc[描述]\n Schema[输入模式]\n Func[执行函数]\n end\n \n Tool --> Name\n Tool --> Desc\n Tool --> Schema\n Tool --> Func\n```\n\n### 工具属性\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| name | string | 工具的唯一标识名 |\n| description | string | 工具功能描述，用于 LLM 理解何时调用 |\n| argsSchema | ZodSchema | 输入参数的模式定义 |\n\n### 工具调用流程\n\n1. **描述注册**：工具注册时提供名称和描述\n2. **意图识别**：LLM 根据用户问题和工具描述判断是否需要调用\n3. **参数生成**：LLM 根据工具的 schema 生成调用参数\n4. **安全执行**：系统验证参数并执行工具\n5. **结果返回**：工具执行结果返回给 LLM 继续处理\n\nTools 系统还支持动态工具调用配置，允许在运行时修改工具行为和可见性。\n\n## Chat Models 聊天模型接口\n\n### 接口设计\n\nChat Models 接口抽象了所有聊天语言模型的通用能力，提供了一套标准化的 API。通过这个接口，LangChain.js 可以统一地与不同的 LLM 提供商（如 OpenAI、Anthropic、Cohere 等）交互。\n\n接口设计遵循流式优先的原则，所有模型都支持流式输出，允许实时处理生成的内容。这对于需要即时反馈的应用场景至关重要。\n\n### 核心能力\n\n| 能力 | 说明 | 重要性 |\n|------|------|--------|\n| 同步调用 | 等待完整响应返回 | 高 |\n| 流式输出 | 实时获取生成的文本片段 | 高 |\n| 批量处理 | 一次处理多个请求 | 中 |\n| 结构化输出 | 生成符合 schema 的 JSON | 高 |\n| 工具调用 | 支持 function calling | 高 |\n| 多模态 | 支持图像、音频等输入 | 中 |\n\n### 消息类型\n\n接口定义了标准化的消息类型系统，包括：\n\n- **HumanMessage**：用户发送的消息\n- **AIMessage**：AI 生成的响应\n- **SystemMessage**：系统级指令\n- **ToolMessage**：工具执行结果\n- **AIMessageChunk**：流式输出的消息片段\n\n## Vector Stores 向量存储接口\n\n### 检索增强生成支持\n\nVector Stores 接口为检索增强生成（RAG）提供了向量存储和相似性检索的基础设施。接口设计兼容多种向量数据库，包括本地内存存储和云服务（如 Pinecone、Weaviate、Chroma 等）。\n\n```mermaid\ngraph LR\n A[文档] --> B[文档加载器]\n B --> C[文本分割器]\n C --> D[嵌入模型]\n D --> E[向量存储]\n \n F[用户查询] --> G[嵌入模型]\n G --> H[相似性搜索]\n H --> E\n E --> I[相关文档]\n I --> J[LLM 生成]\n```\n\n### 核心方法\n\n| 方法名 | 说明 |\n|--------|------|\n| `addDocuments()` | 添加文档到向量存储 |\n| `similaritySearch()` | 基于向量相似性搜索 |\n| `similaritySearchWithScore()` | 返回相似性得分 |\n| `delete()` | 删除指定文档 |\n| `getCapabilities()` | 获取存储能力信息 |\n\n### 索引管理\n\n向量存储支持灵活的索引管理，允许：\n\n- 增量更新文档而无需重建整个索引\n- 基于元数据过滤搜索结果\n- 配置不同的相似性度量方法（余弦相似度、欧氏距离等）\n\n## 模块协作示例\n\n以下流程图展示了一个典型 RAG 应用中各模块的协作方式：\n\n```mermaid\nsequenceDiagram\n participant User as 用户\n participant Chain as Chain\n participant Memory as Memory\n participant Retriever as Retriever\n participant VS as Vector Store\n participant LLM as LLM\n \n User->>Chain: 用户查询\n Chain->>Memory: 获取对话上下文\n Memory-->>Chain: 历史消息\n Chain->>Retriever: 检索请求\n Retriever->>VS: 向量相似性搜索\n VS-->>Retriever: 相关文档\n Retriever-->>Chain: 上下文文档\n Chain->>LLM: 组合查询+上下文\n LLM-->>Chain: 生成回答\n Chain->>Memory: 保存对话\n Chain-->>User: 返回结果\n```\n\n## 类型系统与验证\n\n### Zod Schema 集成\n\nLangChain.js 深度集成了 Zod 进行类型验证和模式定义。这种集成提供了：\n\n1. **编译时类型检查**：TypeScript 编译器可以验证类型安全\n2. **运行时验证**：确保输入输出符合预期格式\n3. **自动类型推断**：减少手写类型定义的工作量\n4. **LLM 输出验证**：验证模型生成的响应是否符合 schema\n\n### 层级化类型定义\n\n| 层级 | 用途 | 示例 |\n|------|------|------|\n| `input` | API 输入参数 | 用户提供的原始数据 |\n| `z.input` | 输入模式 | 验证后的输入类型 |\n| `z.output` | 输出模式 | 模型生成的响应类型 |\n| `z.infer` | 推断类型 | TypeScript 类型推导 |\n\n## 最佳实践建议\n\n### 组件设计原则\n\n1. **优先使用接口**：通过抽象接口编程，提高代码的可测试性和可替换性\n2. **利用类型系统**：充分利用 TypeScript 和 Zod 的类型检查能力\n3. **模块化组合**：将复杂逻辑拆分为可复用的 Runnable 组件\n\n### 性能优化\n\n1. **流式处理**：对实时性要求高的场景使用流式 API\n2. **批量操作**：批量处理多个独立请求以提高吞吐量\n3. **缓存策略**：对不频繁变化的计算结果进行缓存\n\n### 错误处理\n\n1. **使用 Callbacks**：通过事件系统监控执行过程中的错误\n2. **类型验证**：在处理外部输入前进行严格的类型验证\n3. **优雅降级**：为可能的失败场景准备降级方案\n\n---\n\n本页面基于 LangChain.js 源码分析了其核心架构和抽象设计。各核心模块相互协作，共同支撑起构建复杂 LLM 应用的基础能力。开发者可以根据这些抽象接口进行扩展和定制，构建满足特定需求的 LangChain 应用。\n\n---\n\n\n\n## Agent 与 Chains 实现\n\n### 相关页面\n\n相关主题：[系统架构与核心抽象](#page-2), [向量存储与检索系统](#page-4)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [libs/langchain-core/src/agents/types.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-core/src/agents/types.ts)\n- [libs/langchain-core/src/messages/ai.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-core/src/messages/ai.ts)\n- [libs/langchain/src/agents/middleware/hitl.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain/src/agents/middleware/hitl.ts)\n- [libs/langchain-classic/src/agents/format_scratchpad/xml.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-classic/src/agents/format_scratchpad/xml.ts)\n- [libs/langchain-classic/src/chains/question_answering/load.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-classic/src/chains/question_answering/load.ts)\n- [libs/langchain-classic/src/chains/llm_chain.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-classic/src/chains/llm_chain.ts)\n
\n\n# Agent 与 Chains 实现\n\n## 概述\n\nLangChain.js 中的 Agent 与 Chains 模块构成了构建 LLM 驱动应用的核心架构。Agent 负责动态决策和工具调用，而 Chains 则提供了将多个组件组合成连贯工作流的机制。这两者共同支持了从简单的问答系统到复杂的自主代理应用。\n\n## 核心架构\n\n### Agent 类型系统\n\nLangChain.js 定义了完善的类型系统来支持不同类型的 Agent 实现：\n\n```typescript\n// 资料来源：libs/langchain-core/src/agents/types.ts\nexport type N = typeof START | \"model_request\" | \"tools\";\n```\n\n类型推断助手允许开发者从 Agent 配置中提取特定类型：\n\n| 工具函数 | 用途 |\n|---------|------|\n| `InferAgentType` | 提取上下文类型 |\n| `InferAgentMiddleware` | 提取中间件类型 |\n| `InferAgentTools` | 提取工具类型 |\n| `InferAgentStreamTransformers` | 提取流转换器类型 |\n\n```typescript\n// 资料来源：libs/langchain-core/src/agents/types.ts\n/**\n * Shorthand helper to extract the Tools type from an AgentTypeConfig or ReactAgent.\n */\nexport type InferAgentTools = InferAgentType;\n```\n\n### 中断机制\n\nAgent 系统支持中断功能，用于实现 Human-in-the-Loop (HITL) 模式：\n\n```typescript\n// 资料来源：libs/langchain/src/agents/middleware/hitl.ts\nexport interface Interrupt {\n // 表示中断状态的接口\n}\n```\n\nInterrupt 配置支持动态描述生成：\n\n```typescript\n// 资料来源：libs/langchain/src/agents/middleware/hitl.ts\nconst formatToolDescription: DescriptionFactory = (\n toolCall: ToolCall,\n state: AgentBuiltInState,\n runtime: Runtime\n) => {\n return `Tool: ${toolCall.name}\\nArguments:\\n${JSON.stringify(toolCall.args, null, 2)}`;\n};\n```\n\n## Agent 实现类型\n\n### ReAct Agent\n\nReAct (Reasoning + Acting) Agent 结合了推理和行动能力，通过中间步骤处理复杂任务。\n\n### OpenAI Functions Agent\n\n针对 OpenAI 函数调用能力优化的 Agent，利用结构化输出进行工具选择。\n\n### Structured Chat Agent\n\n支持结构化聊天交互的 Agent，适合需要复杂参数的工具调用场景。\n\n## Chains 实现\n\n### LLMChain\n\nLLMChain 是最基本的链实现，用于将提示模板与 LLM 结合：\n\n```typescript\n// 资料来源：libs/langchain-classic/src/chains/llm_chain.ts\nconst llmChain = new LLMChain({ prompt, llm, verbose });\n```\n\n### 问答链加载\n\nLangChain 提供了灵活的问答链加载机制：\n\n```typescript\n// 资料来源：libs/langchain-classic/src/chains/question_answering/load.ts\nexport function loadQAStuffChain(\n llm: BaseLanguageModelInterface,\n params: StuffQAChainParams = {}\n) {\n const { prompt = QA_PROMPT_SELECTOR.getPrompt(llm), verbose } = params;\n const llmChain = new LLMChain({ prompt, llm, verbose });\n const chain = new StuffDocumentsChain({ llmChain, verbose });\n return chain;\n}\n```\n\n支持三种主要的问答链类型：\n\n| 链类型 | 描述 | 使用场景 |\n|-------|------|---------|\n| `stuff` | 将所有文档塞入单个提示 | 文档较少时 |\n| `map_reduce` | 分别处理每个文档后汇总 | 文档较多时 |\n| `refine` | 迭代式精炼答案 | 需要渐进式推理 |\n\n### 参数配置\n\n```typescript\n// 资料来源：libs/langchain-classic/src/chains/question_answering/load.ts\nexport interface StuffQAChainParams {\n prompt?: BasePromptTemplate;\n verbose?: boolean;\n}\n\nexport interface MapReduceQAChainParams {\n returnIntermediateSteps?: MapReduceDocumentsChainInput[\"returnIntermediateSteps\"];\n combineMapPrompt?: BasePromptTemplate;\n combinePrompt?: BasePromptTemplate;\n combineLLM?: BaseLanguageModelInterface;\n verbose?: boolean;\n}\n```\n\n## 工具调用系统\n\n### AIMessage 与 Tool Calls\n\nAIMessage 类集成了工具调用支持，处理消息内容块转换：\n\n```typescript\n// 资料来源：libs/langchain-core/src/messages/ai.ts\nif (this.tool_calls) {\n const missingToolCalls = this.tool_calls.filter(\n (block) =>\n !blocks.some((b) => b.id === block.id && b.name === block.name)\n );\n blocks.push(\n ...(missingToolCalls.map((block) => ({\n type: \"tool_call\" as const,\n id: block.id,\n name: block.name,\n args: block.args,\n })) as ContentBlock.Tools.ToolCall[])\n );\n}\n```\n\n### Action 接口\n\n```typescript\n// 资料来源：libs/langchain/src/agents/middleware/hitl.ts\nexport interface Action {\n /**\n * 动作类型或名称（如 \"add_numbers\"）\n */\n name: string;\n /**\n * 动作所需参数的键值对（如 {\"a\": 1, \"b\": 2}）\n */\n args: Record;\n}\n```\n\n## Scratchpad 格式化\n\nAgent 使用 scratchpad 记录中间推理步骤，支持 XML 格式：\n\n```typescript\n// 资料来源：libs/langchain-classic/src/agents/format_scratchpad/xml.ts\nexport function formatXml(intermediateSteps: AgentStep[]) {\n let log = \"\";\n for (const step of intermediateSteps) {\n const { action, observation } = step;\n log += `${action.tool}${action.toolInput}\\n${observation}`;\n }\n return log;\n}\n```\n\n## 架构流程图\n\n```mermaid\ngraph TD\n A[用户输入] --> B[Agent 决策]\n B --> C{选择工具?}\n C -->|是| D[执行工具]\n D --> E[获取观察结果]\n E --> B\n C -->|否| F[生成最终响应]\n B --> G{需要人工确认?}\n G -->|是| H[中断并等待]\n H --> I[人类决策]\n I --> B\n G -->|否| F\n```\n\n## 消息传递流程\n\n```mermaid\nsequenceDiagram\n participant U as 用户\n participant A as Agent\n participant M as AIMessage\n participant T as 工具\n\n U->>A: 输入请求\n A->>M: 生成消息\n M->>M: 处理 tool_calls\n M->>M: 转换 contentBlocks\n A->>T: 调用工具\n T->>A: 返回结果\n A->>U: 最终响应\n```\n\n## 配置与中间件\n\n### InterruptOnConfig 配置\n\n```typescript\n// 资料来源：libs/langchain/src/agents/middleware/hitl.ts\nconst config: InterruptOnConfig = {\n allowedDecisions: [\"approve\", \"edit\"],\n description: formatToolDescription,\n argsSchema: z.record(z.any()).optional(),\n};\n```\n\n### 配置参数说明\n\n| 参数 | 类型 | 必填 | 描述 |\n|------|------|------|------|\n| `allowedDecisions` | `string[]` | 否 | 允许的决策列表 |\n| `description` | `string \\| DescriptionFunction` | 否 | 决策描述 |\n| `argsSchema` | `Record` | 否 | 参数的 JSON Schema |\n\n## 测试匹配器\n\nLangChain 提供了专门的测试匹配器用于验证 Agent 行为：\n\n```typescript\n// 资料来源：libs/langchain-core/src/testing/matchers.ts\nexport const langchainMatchers = {\n toBeHumanMessage,\n toBeAIMessage,\n toBeSystemMessage,\n toBeToolMessage,\n toHaveToolCalls,\n toHaveToolCallCount,\n toContainToolCall,\n toHaveToolMessages,\n toHaveBeenInterrupted,\n toHaveStructuredResponse,\n};\n```\n\n## 最佳实践\n\n### 工具选择策略\n\n1. **评估任务复杂度**：简单任务使用单一工具，复杂任务考虑多工具协作\n2. **定义清晰的工具描述**：确保 Agent 能准确理解工具用途\n3. **处理工具调用失败**：实现降级策略和错误恢复机制\n\n### Chain 组合建议\n\n1. **从 LLMChain 开始**：验证基础功能后再组合复杂链\n2. **使用输入输出映射**：确保数据在链之间正确传递\n3. **添加错误处理**：为每个链组件添加适当的异常处理\n\n## 版本迁移\n\n`@langchain/classic` 包保留了 v0.x 版本的链实现，用于向后兼容：\n\n```typescript\n// 资料来源：libs/langchain-classic/README.md\n- `LLMChain` - Basic chain for calling an LLM with a prompt template\n- `ConversationalRetrievalQAChain` - Chain for conversational question-answering\n- `RetrievalQAChain` - Chain for question-answering over documents\n```\n\n新项目推荐使用 `createAgent` API 获取更好的性能和更清晰的接口。\n\n---\n\n\n\n## 向量存储与检索系统\n\n### 相关页面\n\n相关主题：[Agent 与 Chains 实现](#page-3), [扩展提供商与工具集成](#page-6)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [libs/langchain-classic/src/vectorstores/memory.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-classic/src/vectorstores/memory.ts)\n- [libs/providers/langchain-pinecone/README.md](https://github.com/langchain-ai/langchainjs/blob/main/libs/providers/langchain-pinecone/README.md)\n- [libs/providers/langchain-qdrant/README.md](https://github.com/langchain-ai/langchainjs/blob/main/libs/providers/langchain-qdrant/README.md)\n- [libs/langchain-classic/src/retrievers/parent_document.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-classic/src/retrievers/parent_document.ts)\n- [libs/langchain-classic/src/retrievers/multi_query.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-classic/src/retrievers/multi_query.ts)\n- [examples/src/langchain-classic/indexes/html_text_splitter.ts](https://github.com/langchain-ai/langchainjs/blob/main/examples/src/langchain-classic/indexes/html_text_splitter.ts)\n- [libs/langchain-textsplitters/README.md](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-textsplitters/README.md)\n
\n\n# 向量存储与检索系统\n\n## 概述\n\nLangChain.js 的向量存储与检索系统是构建检索增强生成（RAG）应用的核心基础设施。该系统提供了一套完整的接口和实现，用于将文档转换为向量表示、存储在各种向量数据库中，并通过语义相似性进行高效检索。\n\n系统设计遵循模块化原则，提供了统一的 `VectorStore` 接口规范，使得不同的向量存储后端可以无缝切换。开发者可以根据数据规模、查询性能和部署需求选择合适的存储方案，同时保持上层应用代码的一致性。\n\nLangChain.js 支持多种主流向量数据库集成，包括内存存储（用于开发测试）、Pinecone、Qdrant、MongoDB Atlas Search、PostgreSQL PGVector 等，为企业级应用提供了丰富的选择。\n\n## 核心架构\n\n### 系统组件关系\n\nLangChain.js 的向量存储与检索系统由多个核心组件构成，这些组件协同工作以实现完整的文档处理和检索流程。\n\n```mermaid\ngraph TD\n A[文档输入] --> B[文本分割器 Text Splitters]\n B --> C[向量化 Embeddings]\n C --> D[向量存储 VectorStore]\n D --> E[检索器 Retrievers]\n E --> F[应用层]\n \n G[Embedding Models] --> C\n \n H[Pinecone] --> D\n I[Qdrant] --> D\n J[MongoDB] --> D\n K[PGVector] --> D\n L[Memory] --> D\n```\n\n### 数据处理流程\n\n文档从原始格式到可检索向量的转换过程涉及多个阶段，每个阶段都有明确的职责边界。\n\n```mermaid\ngraph LR\n A[原始文档] --> B[文本分割]\n B --> C[小文档块]\n C --> D[调用 Embeddings API]\n D --> E[向量 + 元数据]\n E --> F[存储到 VectorStore]\n \n G[用户查询] --> H[查询向量化]\n H --> I[相似度搜索]\n I --> J[返回相关文档]\n```\n\n## 向量存储接口\n\n### VectorStore 基类\n\n`VectorStore` 是所有向量存储实现的基础抽象接口，定义了向量存储的核心操作方法。所有具体的向量存储实现都继承自这个接口，确保了 API 的一致性和可替换性。\n\n接口主要包含以下几个核心方法：\n\n```typescript\nclass VectorStore {\n // 添加文档到向量存储\n async addDocuments(documents: Document[]): Promise\n \n // 通过相似度搜索查找相关文档\n async similaritySearch(\n query: string, \n k?: number\n ): Promise\n \n // 带相似度分数的搜索\n async similaritySearchWithScore(\n query: string,\n k?: number\n ): Promise<[Document, number][]>\n \n // 删除文档\n async delete(ids?: string[]): Promise\n \n // 跨链支持\n asRetriever(config?: SimilarityRetrieverConfig): BaseRetriever\n}\n```\n\n### 内存向量存储\n\n`MemoryVectorStore` 是最简单的向量存储实现，将所有向量存储在内存中。这种实现适用于开发测试、小规模数据集，或作为原型验证阶段的首选方案。由于数据存储在内存中，应用重启后数据会丢失，不适合生产环境使用。\n\n```typescript\nimport { MemoryVectorStore } from 'langchain/vectorstores/memory'\nimport { OpenAIEmbeddings } from '@langchain/openai'\n\nconst embeddings = new OpenAIEmbeddings({\n model: \"text-embedding-3-small\",\n})\n\nconst vectorStore = new MemoryVectorStore(embeddings)\n\nconst documents = [\n { pageContent: \"文档内容示例\", metadata: { source: \"doc1\" } },\n { pageContent: \"另一篇文档内容\", metadata: { source: \"doc2\" } }\n]\n\nawait vectorStore.addDocuments(documents)\n\nconst results = await vectorStore.similaritySearch(\"查询文本\", 2)\n```\n\n## 第三方向量存储集成\n\n### Pinecone 集成\n\nPinecone 是一个托管的向量数据库服务，提供高性能的向量存储和检索能力。LangChain.js 通过 `@langchain/pinecone` 包提供了完整的集成支持。\n\n#### 安装配置\n\n```bash\nnpm install @langchain/pinecone @langchain/core @pinecone-database/pinecone\n```\n\n#### 使用示例\n\n```typescript\nimport { PineconeStore } from '@langchain/pinecone'\nimport { Pinecone } from '@pinecone-database/pinecone'\nimport { OpenAIEmbeddings } from '@langchain/openai'\n\nconst pinecone = new Pinecone()\nconst index = pinecone.Index('your-index-name')\n\nconst vectorStore = await PineconeStore.fromExistingIndex(\n new OpenAIEmbeddings(),\n { pineconeIndex: index }\n)\n```\n\n### Qdrant 集成\n\nQdrant 是一个开源的向量相似度搜索引擎，支持混合搜索和过滤。`@langchain/qdrant` 包提供了与 Qdrant 的完整集成。\n\n#### 安装配置\n\n```bash\nnpm install @langchain/qdrant\n```\n\n#### 核心特性\n\n| 特性 | 说明 |\n|------|------|\n| 混合搜索 | 支持向量搜索与关键词搜索结合 |\n| 过滤条件 | 支持元数据过滤 |\n| 集合管理 | 提供集合创建和管理接口 |\n| 距离度量 | 支持 Cosine、Euclidean、Dot 产品 |\n\n### MongoDB Atlas Search\n\nMongoDB Atlas Search 提供了基于 Lucene 的全文搜索能力，结合 MongoDB 的文档模型，可以存储和检索带有多维向量的文档。`@langchain/mongodb` 包提供了这一集成。\n\n### PGVector 集成\n\n对于已在使用 PostgreSQL 的团队，PGVector 提供了在关系数据库中存储和检索向量的能力。`@langchain/pgvector` 包支持这一集成，使得可以利用现有的 PostgreSQL 基础设施。\n\n#### 配置参数\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| connectionString | string | PostgreSQL 连接字符串 |\n| tableName | string | 存储向量的表名（默认：langchain_vectorstore） |\n| columns | object | 向量和元数据列的配置 |\n| distanceStrategy | string | 距离计算策略 |\n\n## 检索器系统\n\n检索器（Retriever）是连接向量存储和应用逻辑的关键组件。LangChain.js 提供了多种检索器实现，以适应不同的检索场景和需求。\n\n### 父文档检索器\n\n`ParentDocumentRetriever` 解决了小文本块丢失上下文信息的问题。该检索器首先检索与查询相关的小文本块，然后返回这些小块所属的完整父文档。\n\n```mermaid\ngraph TD\n A[用户查询] --> B[检索小块]\n B --> C[获取父文档ID]\n C --> D[加载完整父文档]\n D --> E[返回带上下文的结果]\n \n F[小块1] --> G[父文档A]\n H[小块2] --> G\n I[小块3] --> J[父文档B]\n```\n\n这种策略在保持检索精确性的同时，确保返回的内容具有完整的上下文信息，特别适用于需要返回较长连续文本的场景。\n\n### 多查询检索器\n\n`MultiQueryRetriever` 通过使用语言模型生成多个不同角度的查询，然后对所有查询的结果进行去重合并，从而提高检索的召回率。\n\n```typescript\nimport { MultiQueryRetriever } from 'langchain/retrievers/multi_query'\n\nconst retriever = MultiQueryRetriever.fromLLM({\n llm: chatModel,\n retriever: baseRetriever,\n includeOriginal: true,\n verbose: true,\n})\n```\n\n| 参数 | 说明 |\n|------|------|\n| llm | 用于生成多查询的语言模型 |\n| retriever | 基础检索器 |\n| includeOriginal | 是否包含原始查询的结果 |\n| verbose | 是否输出详细日志 |\n\n### 检索器配置\n\n所有检索器都支持通过配置对象进行定制化设置，主要配置选项包括：\n\n| 配置项 | 说明 | 默认值 |\n|--------|------|--------|\n| k | 返回的文档数量 | 4 |\n| filter | 元数据过滤条件 | undefined |\n| namespace | 命名空间（部分向量存储支持） | undefined |\n\n## 文本分割器\n\n文本分割器是将长文档拆分为适合嵌入和检索的小块的关键组件。`@langchain/textsplitters` 包提供了多种分割策略。\n\n### 递归字符分割器\n\n`RecursiveCharacterTextSplitter` 是最常用的分割器，它按照预定义的字符优先级递归地分割文本，确保语义完整性。\n\n```typescript\nimport { RecursiveCharacterTextSplitter } from \"@langchain/textsplitters\"\n\nconst splitter = RecursiveCharacterTextSplitter.fromLanguage(\"html\", {\n chunkSize: 175,\n chunkOverlap: 20,\n})\n\nconst output = await splitter.createDocuments([text])\n```\n\n### 分割参数说明\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| chunkSize | number | 每个块的最大字符数 |\n| chunkOverlap | number | 相邻块之间的重叠字符数 |\n| separators | string[] | 分割符列表（按优先级排序） |\n\n### 语言特定分割\n\n分割器支持针对不同内容类型进行优化配置：\n\n```typescript\n// Markdown 文档\nconst mdSplitter = RecursiveCharacterTextSplitter.fromLanguage(\"markdown\", {\n chunkSize: 1000,\n chunkOverlap: 100,\n})\n\n// 代码文件\nconst codeSplitter = RecursiveCharacterTextSplitter.fromLanguage(\"js\", {\n chunkSize: 500,\n chunkOverlap: 50,\n})\n\n// HTML 文档\nconst htmlSplitter = RecursiveCharacterTextSplitter.fromLanguage(\"html\", {\n chunkSize: 175,\n chunkOverlap: 20,\n})\n```\n\n## Embeddings 集成\n\nEmbeddings 是将文本转换为向量表示的模型。LangChain.js 通过标准化的接口支持多种 Embeddings 提供商。\n\n### 接口定义\n\n```typescript\ninterface Embeddings {\n embedQuery(text: string): Promise\n embedDocuments(texts: string[]): Promise\n}\n```\n\n### 支持的提供商\n\n| 提供商 | 包名 | 说明 |\n|--------|------|------|\n| OpenAI | @langchain/openai | text-embedding-3-small/large |\n| Google | @langchain/google-vertexai | Palm/Embedding-Gecko |\n| Anthropic | @langchain/anthropic | Claude 内置支持 |\n| Cohere | @langchain/cohere | Embed v3/v4 |\n| HuggingFace | @langchain/huggingface | 数千种开源模型 |\n\n## 最佳实践\n\n### 数据处理流程\n\n构建高效的向量检索系统需要遵循系统化的数据处理流程。在数据准备阶段，应根据内容类型选择合适的分割策略：结构化文档使用语义分割，代码文件按函数或类分割，网页内容按 HTML 标签语义分割。\n\n```mermaid\ngraph TD\n A[数据收集] --> B[数据清洗]\n B --> C[内容分类]\n C --> D[选择分割策略]\n D --> E[文本分割]\n E --> F[向量化]\n F --> G[质量检查]\n G --> H{是否合格}\n H -->|否| E\n H -->|是| I[存储向量]\n I --> J[索引优化]\n```\n\n### 查询优化\n\n在进行相似性搜索时，应充分利用向量数据库的过滤功能，在向量相似度计算前先进行元数据过滤，以减少搜索范围并提高准确性。对于复杂的查询场景，考虑使用混合搜索策略，结合向量相似度和关键词匹配。\n\n### 生产环境考虑\n\n生产环境中应重点关注向量存储的索引配置、查询延迟监控、以及 Embeddings 模型的选择。对于大规模数据集，Pinecone 或 Qdrant 等专用向量数据库通常比通用数据库提供更好的性能。同时应建立 Embeddings 缓存机制，避免对相同文本重复进行向量化计算。\n\n## 相关资源\n\n- [官方文档](https://docs.langchain.com/oss/javascript/langchain)\n- [@langchain/textsplitters 文档](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-textsplitters/README.md)\n- [@langchain/pinecone 文档](https://github.com/langchain-ai/langchainjs/blob/main/libs/providers/langchain-pinecone/README.md)\n- [@langchain/qdrant 文档](https://github.com/langchain-ai/langchainjs/blob/main/libs/providers/langchain-qdrant/README.md)\n\n---\n\n\n\n## 主要模型提供商集成\n\n### 相关页面\n\n相关主题：[系统架构与核心抽象](#page-2), [扩展提供商与工具集成](#page-6)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [libs/providers/langchain-anthropic/src/chat_models.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/providers/langchain-anthropic/src/chat_models.ts)\n- [libs/providers/langchain-openai/src/chat_models/index.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/providers/langchain-openai/src/chat_models/index.ts)\n- [libs/langchain-classic/src/vectorstores/memory.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-classic/src/vectorstores/memory.ts)\n- [libs/langchain-core/src/messages/message.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-core/src/messages/message.ts)\n- [libs/langchain-core/src/language_models/utils.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-core/src/language_models/utils.ts)\n
\n\n# 主要模型提供商集成\n\n## 概述\n\nLangChain.js 的主要模型提供商集成模块为开发者提供了统一的接口，用于对接多个主流 AI 服务提供商的 chat models。这些集成通过标准化的抽象层，使得应用程序能够在不同提供商之间无缝切换，同时保持代码的兼容性和可维护性。\n\n集成模块位于 `libs/providers/` 目录下，支持的提供商包括 OpenAI、Anthropic、Google Vertex AI、Google GenAI、Mistral AI 等主流 LLM 服务商。每个提供商都实现了统一的 chat model 接口规范，确保了调用方式的一致性。\n\n## 架构设计\n\n### 核心抽象层\n\nLangChain.js 采用分层架构设计，模型提供商集成位于基础设施层之上，为上层应用提供统一的 AI 能力访问接口。\n\n```mermaid\ngraph TD\n A[应用层 Application] --> B[链与代理层 Chains & Agents]\n B --> C[模型抽象层 Model Abstraction]\n C --> D[提供商集成层 Provider Integrations]\n D --> E[OpenAI]\n D --> F[Anthropic]\n D --> G[Google Vertex]\n D --> H[Mistral AI]\n E --> I[外部 API 服务]\n F --> I\n G --> I\n H --> I\n```\n\n### 消息标准化\n\n每个模型集成都实现了消息格式的标准化转换，确保不同提供商的消息结构能够被正确处理。核心的消息类型定义位于 `libs/langchain-core/src/messages/message.ts`，包括工具定义（`MessageToolDefinition`）、工具集（`MessageToolSet`）等关键数据结构。\n\n```mermaid\ngraph LR\n A[用户消息] --> B[标准化消息格式]\n B --> C[Provider-specific 转换]\n C --> D[API 请求格式]\n D --> E[模型提供商]\n```\n\n## 核心功能特性\n\n### 统一调用接口\n\n所有 chat model 实现都遵循统一的调用模式，支持 `invoke` 方法进行同步调用和 `stream` 方法进行流式响应处理。这种设计使得开发者可以在不修改应用代码的情况下更换底层模型提供商。\n\n```typescript\n// 统一的调用方式\nconst result = await llm.invoke(input);\nfor await (const chunk of await llm.stream(input)) {\n console.log(chunk);\n}\n```\n\n资料来源：[libs/providers/langchain-anthropic/src/chat_models.ts]()\n\n### 结构化输出\n\n模型集成支持通过 `withStructuredOutput()` 方法实现结构化输出，该功能使用提供商的原生工具调用能力来约束输出格式到特定的 JSON schema。\n\n| 功能 | 描述 | 实现方式 |\n|------|------|----------|\n| 函数调用 | 使用工具调用约束输出 | `withStructuredOutput()` |\n| JSON Schema | 使用原生 JSON schema 支持 | Provider 原生功能 |\n| 类型安全 | 提供完整的 TypeScript 类型推导 | Zod schema 定义 |\n\n资料来源：[libs/providers/langchain-anthropic/src/chat_models.ts]()\n\n### 工具调用支持\n\n集成模块提供了完整的工具调用（Tool Calling）支持，允许模型调用外部工具和函数。这一功能通过 `tool()` 辅助函数实现，支持 Zod schema 定义工具参数。\n\n```typescript\nimport { tool } from \"@langchain/core/tools\";\nimport { z } from \"zod\";\n\nconst getWeather = tool(\n async (input) => `Weather in ${input.location}`,\n {\n name: \"get_weather\",\n description: \"Get weather for a location\",\n schema: z.object({ location: z.string() }),\n }\n);\n```\n\n资料来源：[libs/providers/langchain-anthropic/src/chat_models.ts]()\n\n## OpenAI 集成\n\n### 基本配置\n\nOpenAI 集成提供了对 GPT 系列模型的访问支持，核心实现在 `libs/providers/langchain-openai/src/chat_models/index.ts`。\n\n```typescript\nimport { ChatOpenAI } from \"@langchain/openai\";\n\nconst llm = new ChatOpenAI({\n model: \"gpt-4o\",\n temperature: 0.7,\n // 其他配置参数...\n});\n```\n\n### 流式响应处理\n\nOpenAI 集成支持流式输出，响应包含内容块、元数据和 token 使用统计信息。\n\n```txt\nAIMessageChunk {\n \"id\": \"chatcmpl-9u4NWB7yUeHCKdLr6jP3HpaOYHTqs\",\n \"content\": \"\"\n}\nAIMessageChunk {\n \"content\": \"J\"\n}\nAIMessageChunk {\n \"content\": \"'adore\"\n}\n```\n\n资料来源：[libs/providers/langchain-openai/src/chat_models/index.ts]()\n\n## Anthropic 集成\n\n### 特性概述\n\nAnthropic 集成专门针对 Claude 系列模型进行了优化，提供了额外的特性支持，包括高级工具使用和搜索功能。\n\n| 特性 | 描述 | 适用版本 |\n|------|------|----------|\n| 标准工具调用 | 基础函数调用功能 | 所有版本 |\n| 工具搜索 | 使用 regex 或 bm25 搜索工具 | 需 `advanced-tool-use-2025-11-20` beta |\n| 延迟加载工具 | 按需加载不常用工具 | 支持 `defer_loading: true` |\n\n资料来源：[libs/providers/langchain-anthropic/src/chat_models.ts]()\n\n### 消息块翻译\n\nAnthropic 集成实现了消息块翻译器（BlockTranslator）接口，用于在标准格式和提供商特定格式之间进行转换：\n\n```typescript\nBlockTranslator = {\n translateContent: (message) => {\n if (typeof message.content === \"string\") {\n return convertToV1FromChatCompletions(message);\n }\n return convertToV1FromResponses(message);\n },\n translateContentChunk: (message) => { /* ... */ },\n};\n```\n\n资料来源：[libs/langchain-core/src/messages/block_translators/openai.ts]()\n\n## 向量存储与嵌入集成\n\n### 内存向量存储\n\nLangChain.js 提供了 `MemoryVectorStore` 实现，用于在内存中存储和检索文档向量。该存储与嵌入模型配合使用，支持添加文档和相似性搜索功能。\n\n```typescript\nimport { MemoryVectorStore } from 'langchain/vectorstores/memory';\nimport { OpenAIEmbeddings } from '@langchain/openai';\n\nconst embeddings = new OpenAIEmbeddings({\n model: \"text-embedding-3-small\",\n});\n\nconst vectorStore = new MemoryVectorStore(embeddings);\n\n// 添加文档\nawait vectorStore.addDocuments(documents);\n\n// 相似性搜索\nconst results = await vectorStore.similaritySearch(\"thud\", 1);\n```\n\n资料来源：[libs/langchain-classic/src/vectorstores/memory.ts]()\n\n### 嵌入模型配置\n\n嵌入模型是 RAG（检索增强生成）管道的核心组件，用于将文本转换为向量表示。每个模型提供商都提供了相应的嵌入实现。\n\n## 消息与工具系统\n\n### 消息结构\n\nLangChain.js 定义了标准化的消息结构体系，包括基础消息类型、工具定义和工具调用块等核心组件。\n\n```mermaid\nclassDiagram\n class MessageToolDefinition {\n +TInput input\n +TOutput output\n }\n \n class MessageToolSet {\n +[key: string]: MessageToolDefinition\n }\n \n class MessageToolCallBlock {\n +string type\n +string name\n +Record args\n +string? id\n }\n \n MessageToolSet --> MessageToolDefinition : contains\n```\n\n资料来源：[libs/langchain-core/src/messages/message.ts]()\n\n### 工具调用块类型\n\n工具调用块是消息系统中表示工具调用的关键数据结构，其类型定义如下：\n\n```typescript\ntype $MessageToolCallBlock = {\n type: \"tool_call\";\n name: string;\n args: TStructure[\"tools\"][keyof TStructure[\"tools\"]][\"input\"];\n id?: string;\n};\n```\n\n资料来源：[libs/langchain-core/src/messages/message.ts]()\n\n## 标准消息内容转换\n\n### 内容转换工具\n\n`castStandardMessageContent` 函数是 LangChain.js 消息处理的核心工具，用于标准化消息内容格式：\n\n```typescript\nfunction castStandardMessageContent(message: T) {\n const Cls = message.constructor as Constructor;\n return new Cls({\n ...message,\n content: message.contentBlocks,\n response_metadata: {\n ...message.response_metadata,\n output_version: \"v1\",\n },\n });\n}\n```\n\n该函数将消息的内容块转换为标准内容格式，并附加 v1 输出版本元数据，确保了不同提供商之间的兼容性。\n\n资料来源：[libs/langchain-core/src/language_models/utils.ts]()\n\n## 安装与配置\n\n### 依赖管理\n\n每个模型提供商包都依赖 `@langchain/core` 作为 peer dependency。建议在项目 `package.json` 中统一管理依赖版本以避免冲突：\n\n```json\n{\n \"dependencies\": {\n \"@langchain/anthropic\": \"^0.0.9\",\n \"@langchain/openai\": \"^0.0.9\",\n \"@langchain/core\": \"^0.3.0\"\n },\n \"overrides\": {\n \"@langchain/core\": \"^0.3.0\"\n }\n}\n```\n\n资料来源：[libs/providers/langchain-anthropic/README.md]()\n\n### 环境变量配置\n\n不同的提供商需要设置相应的 API 密钥：\n\n```bash\n# OpenAI\nexport OPENAI_API_KEY=\"sk-...\"\n\n# Anthropic\nexport ANTHROPIC_API_KEY=\"sk-ant-...\"\n\n# Google Cloud\nexport GOOGLEAPPLICATIONCREDENTIALS=\"/path/to/credentials.json\"\n```\n\n## 最佳实践\n\n### 提供商选择指南\n\n| 使用场景 | 推荐提供商 | 理由 |\n|----------|------------|------|\n| 通用对话 | OpenAI GPT-4o | 性能与成本平衡 |\n| 长上下文 | Anthropic Claude | 支持 200K token 上下文 |\n| 代码生成 | OpenAI / Anthropic | 两者都有优秀的代码能力 |\n| 本地部署 | Ollama / Llama.cpp | 无需 API 费用 |\n\n### 错误处理策略\n\n实现模型调用时应考虑网络错误、速率限制和配额耗尽等异常情况。建议使用指数退避重试机制，并实现适当的降级策略。\n\n### 性能优化建议\n\n1. **批量处理**：将多个请求合并为批量调用（如果提供商支持）\n2. **流式响应**：对于长文本输出，使用流式响应减少等待时间\n3. **缓存**：对重复查询实现结果缓存\n4. **连接复用**：保持 HTTP 连接活跃以减少建立开销\n\n## 相关资源\n\n- 官方文档：[LangChain.js 文档](https://js.langchain.com/)\n- API 参考：[Provider 包文档](https://github.com/langchain-ai/langchainjs/tree/main/libs/providers)\n- 示例代码：[examples 目录](https://github.com/langchain-ai/langchainjs/tree/main/examples)\n\n---\n\n\n\n## 扩展提供商与工具集成\n\n### 相关页面\n\n相关主题：[主要模型提供商集成](#page-5), [扩展开发指南](#page-9)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [libs/providers/langchain-anthropic/src/chat_models.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/providers/langchain-anthropic/src/chat_models.ts)\n- [libs/providers/langchain-openai/src/chat_models/index.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/providers/langchain-openai/src/chat_models/index.ts)\n- [libs/providers/langchain-openai/src/utils/tools.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/providers/langchain-openai/src/utils/tools.ts)\n- [libs/langchain-core/src/messages/block_translators/openai.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-core/src/messages/block_translators/openai.ts)\n- [libs/langchain-core/src/messages/ai.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-core/src/messages/ai.ts)\n- [libs/langchain-core/src/messages/message.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-core/src/messages/message.ts)\n- [libs/langchain-core/src/language_models/utils.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-core/src/language_models/utils.ts)\n- [libs/langchain/src/agents/types.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain/src/agents/types.ts)\n- [libs/langchain/src/agents/middleware/hitl.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain/src/agents/middleware/hitl.ts)\n- [libs/langchain-core/src/testing/matchers.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-core/src/testing/matchers.ts)\n
\n\n# 扩展提供商与工具集成\n\n## 概述\n\nLangChain.js 的扩展提供商系统是一个模块化架构，允许通过不同的提供商 SDK 集成各种大语言模型（LLM）服务。每个提供商都实现了统一的接口规范，同时保留了各自平台特有的功能特性。工具集成是这些提供商的核心能力之一，它使得 AI 模型能够调用外部函数来执行特定任务，如计算、搜索、数据处理等。\n\n在 LangChain.js 的架构中，工具集成涉及三个主要层面的抽象：工具定义层、消息传输层和提供商适配层。工具定义使用统一的 TypeScript 类型系统描述工具的输入输出结构，消息传输层负责在不同格式之间进行转换，而提供商适配层则处理与各个 AI 服务提供商的特定集成细节。\n\n## 工具定义系统\n\n### 核心类型定义\n\nLangChain.js 在 `libs/langchain-core/src/messages/message.ts` 中定义了工具系统的核心类型结构。这些类型构成了整个工具集成的基础架构，提供了类型安全的工具定义和调用机制。\n\n```typescript\nexport interface MessageToolDefinition {\n input: TInput;\n output: TOutput;\n}\n\nexport interface MessageToolSet {\n [key: string]: MessageToolDefinition;\n}\n```\n\n资料来源：[libs/langchain-core/src/messages/message.ts:1-15]()\n\n`MessageToolDefinition` 接口使用泛型参数定义工具的输入和输出类型，允许开发者为每个工具指定精确的数据结构。`MessageToolSet` 接口则是一个映射类型，将工具名称与对应的工具定义关联起来。\n\n### 工具调用块结构\n\n工具调用块（Tool Call Block）是消息中表示工具调用的数据结构，包含工具名称、参数和可选的调用标识符。这个结构在 `MessageStructure` 的工具扩展部分定义：\n\n```typescript\ntype CalcToolCall = $MessageToolCallBlock;\n// Resolves to:\n// {\n// type: \"tool_call\";\n// name: \"calculator\";\n// args: { operation: string, numbers: number[] };\n// id?: string;\n// }\n```\n\n资料来源：[libs/langchain-core/src/messages/message.ts:50-70]()\n\n这种结构设计确保了工具调用的自包含性，每个调用都包含足够的上下文信息来执行对应的工具函数。`id` 字段是可选的，允许在不需要追踪单个调用的情况下省略。\n\n## 消息格式转换层\n\n### OpenAI 格式翻译器\n\nLangChain.js 的 `block_translators` 模块提供了不同消息格式之间的转换能力。在 `libs/langchain-core/src/messages/block_translators/openai.ts` 中实现的 `BlockTranslator` 是核心的转换逻辑：\n\n```typescript\nBlockTranslator = {\n translateContent: (message) => {\n if (typeof message.content === \"string\") {\n return convertToV1FromChatCompletions(message);\n }\n return convertToV1FromResponses(message);\n },\n translateContentChunk: (message) => {\n if (typeof message.content === \"string\") {\n return convertToV1FromChatCompletionsChunk(message);\n }\n return convertToV1FromResponsesChunk(message);\n },\n};\n```\n\n资料来源：[libs/langchain-core/src/messages/block_translators/openai.ts:1-15]()\n\n翻译器根据消息内容类型选择不同的转换路径。对于字符串内容，它使用 Chat Completions 格式的转换器；对于数组格式的内容，则使用 Responses API 格式的转换器。这种设计允许系统同时支持 OpenAI 的两种主要 API 风格。\n\n### 标准消息内容转换\n\n`libs/langchain-core/src/language_models/utils.ts` 中的 `castStandardMessageContent` 函数提供了标准消息内容的转换能力，确保消息格式在不同版本之间保持兼容性：\n\n```typescript\nfunction castStandardMessageContent(message: T) {\n const Cls = message.constructor as Constructor;\n return new Cls({\n ...message,\n content: message.contentBlocks,\n response_metadata: {\n ...message.response_metadata,\n output_version: \"v1\",\n },\n });\n}\n```\n\n资料来源：[libs/langchain-core/src/language_models/utils.ts:8-20]()\n\n该函数通过重建消息实例来确保内容块被正确格式化，同时在响应元数据中添加版本标识，便于后续处理和调试。\n\n## AIMessage 工具集成\n\n### 内容块生成逻辑\n\n`AIMessage` 类在 `libs/langchain-core/src/messages/ai.ts` 中实现了复杂的工具调用整合逻辑。其 `contentBlocks` getter 方法负责合并基础内容与工具调用信息：\n\n```typescript\noverride get contentBlocks(): ContentBlock[] {\n if (\n \"model_provider\" in this.response_metadata &&\n typeof this.response_metadata.model_provider === \"string\"\n ) {\n const translator = getTranslator(this.response_metadata.model_provider);\n if (translator) {\n return translator.translateContent(this as AIMessage);\n }\n }\n\n const blocks = super.contentBlocks;\n\n if (this.tool_calls) {\n const missingToolCalls = this.tool_calls.filter(\n (block) =>\n !blocks.some((b) => b.id === block.id && b.name === block.name)\n );\n blocks.push(\n ...(missingToolCalls.map((block) => ({\n type: \"tool_call\" as const,\n id: block.id,\n name: block.name,\n args: block.args,\n })) as ContentBlock.Tools.ToolCall[])\n );\n }\n\n return blocks;\n}\n```\n\n资料来源：[libs/langchain-core/src/messages/ai.ts:1-35]()\n\n该逻辑首先检查响应元数据中是否包含模型提供商信息，如果有则使用对应的翻译器进行格式转换。如果不存在翻译器，则采用默认逻辑，将 `tool_calls` 数组中的工具调用转换为内容块。过滤逻辑确保不会重复添加已存在于基础内容中的工具调用。\n\n### 类型守卫机制\n\nAIMessage 类提供了静态类型守卫方法来安全地识别消息类型：\n\n```typescript\nstatic isInstance(\n obj: BaseMessage\n): obj is BaseMessage & AIMessage;\nstatic isInstance(obj: unknown): obj is AIMessage;\n```\n\n资料来源：[libs/langchain-core/src/messages/ai.ts:60-68]()\n\n这两个重载分别处理泛型和非泛型场景，允许在类型安全的情况下进行类型收窄和断言。\n\n## 提供商工具格式处理\n\n### OpenAI 工具格式\n\n`libs/providers/langchain-openai/src/utils/tools.ts` 中定义了 OpenAI 特定的工具格式转换逻辑：\n\n```typescript\nIClient.Chat.ChatCompletionCustomTool = {\n getFormat: () => {\n if (!tool.format) {\n return undefined;\n }\n if (tool.format.type === \"grammar\") {\n return {\n type: \"grammar\" as const,\n grammar: {\n definition: tool.format.definition,\n syntax: tool.format.syntax,\n },\n };\n }\n if (tool.format.type === \"text\") {\n return {\n type: \"text\" as const,\n };\n }\n return undefined;\n },\n return {\n type: \"custom\",\n custom: {\n name: tool.name,\n description: tool.description,\n format: getFormat(),\n },\n };\n};\n```\n\n资料来源：[libs/providers/langchain-openai/src/utils/tools.ts:1-35]()\n\nOpenAI 支持多种工具格式类型，包括 `grammar` 格式（包含语法定义和语法规则）和 `text` 格式。这种灵活性允许开发者为不同的用例选择最合适的格式定义方式。`custom` 类型包装了所有自定义工具，确保符合 OpenAI API 的工具规范。\n\n### Anthropic 流式响应\n\nAnthropic 提供商在 `libs/providers/langchain-anthropic/src/chat_models.ts` 中处理流式响应，其输出格式与 OpenAI 不同，使用 `additional_kwargs` 传递工具元数据：\n\n```txt\nAIMessageChunk {\n \"id\": \"msg_01N8MwoYxiKo9w4chE4gXUs4\",\n \"content\": \"\",\n \"additional_kwargs\": {\n \"id\": \"msg_01N8MwoYxiKo9w4chE4gXUs4\",\n \"type\": \"message\",\n \"role\": \"assistant\",\n \"model\": \"claude-sonnet-4-5-20250929\"\n },\n \"usage_metadata\": {\n \"input_tokens\": 25,\n \"output_tokens\": 1,\n \"total_tokens\": 26\n }\n}\n```\n\n资料来源：[libs/providers/langchain-anthropic/src/chat_models.ts:50-75]()\n\nAnthropic 的流式响应以增量方式返回内容块，每个 `AIMessageChunk` 包含部分内容。这种设计优化了响应延迟，使得用户可以尽快看到初始输出。\n\n## Agent 工具集成\n\n### Agent 类型定义\n\n`libs/langchain/src/agents/types.ts` 中定义了 Agent 的类型系统，包括工具配置选项：\n\n```typescript\ninterface AgentConfig {\n model: string | AgentLanguageModelLike;\n \n tools?: (ServerTool | ClientTool)[];\n \n systemMessage?: string | SystemMessage;\n}\n```\n\n资料来源：[libs/langchain/src/agents/types.ts:1-20]()\n\nAgent 配置中的 `tools` 字段接受 `ServerTool` 或 `ClientTool` 类型的数组，允许 Agent 访问可用的工具集合。系统消息可以是简单的字符串或包含数组内容的 `SystemMessage`，后者支持更复杂的结构化内容。\n\n### 工具调用中间件\n\n`libs/langchain/src/agents/middleware/hitl.ts` 实现了人机协作的中间件系统，允许在工具执行前进行干预：\n\n```typescript\nexport interface Action {\n name: string;\n args: Record;\n}\n\nexport interface InterruptOnConfig {\n description?: z.union([z.string(), DescriptionFunctionSchema]).optional();\n argsSchema?: z.record(z.any()).optional();\n}\n```\n\n资料来源：[libs/langchain/src/agents/middleware/hitl.ts:1-30]()\n\n`Action` 接口定义了工具调用的基本结构，包含动作名称和参数记录。`InterruptOnConfig` 提供了描述工具的选项，可以是静态字符串或动态函数，允许在执行前格式化工具调用的展示信息。\n\n## 测试与验证\n\n### 工具相关匹配器\n\nLangChain.js 提供了专门的测试匹配器来验证工具调用行为，在 `libs/langchain-core/src/testing/matchers.ts` 中实现：\n\n```typescript\nexport const langchainMatchers = {\n toBeHumanMessage,\n toBeAIMessage,\n toBeSystemMessage,\n toBeToolMessage,\n toHaveToolCalls,\n toHaveToolCallCount,\n toContainToolCall,\n toHaveToolMessages,\n toHaveBeenInterrupted,\n toHaveStructuredResponse,\n};\n```\n\n资料来源：[libs/langchain-core/src/testing/matchers.ts:1-15]()\n\n这些匹配器提供了丰富的工具调用验证能力：\n\n| 匹配器 | 用途 |\n|--------|------|\n| `toHaveToolCalls` | 验证消息包含指定数量的工具调用 |\n| `toHaveToolCallCount` | 验证工具调用的精确数量 |\n| `toContainToolCall` | 验证包含特定名称或参数的工具调用 |\n| `toHaveToolMessages` | 验证工具执行后的响应消息 |\n\n工具调用匹配器的使用示例：\n\n```typescript\nexpect(message).toHaveToolCalls([\n { name: \"calculator\", args: { operation: \"add\", a: 1, b: 2 } },\n { name: \"translator\", args: { text: \"hello\", targetLanguage: \"french\" } }\n]);\n```\n\n资料来源：[libs/langchain-core/src/testing/matchers.ts:25-40]()\n\n## 架构流程图\n\n```mermaid\ngraph TD\n A[用户定义工具] --> B[MessageToolDefinition]\n B --> C[工具注册到模型]\n C --> D[模型生成工具调用]\n D --> E[工具调用块创建]\n E --> F{提供商类型}\n F -->|OpenAI| G[Chat Completions / Responses API]\n F -->|Anthropic| H[additional_kwargs]\n F -->|其他| I[提供商特定格式]\n G --> J[BlockTranslator转换]\n H --> J\n I --> J\n J --> K[标准v1格式]\n K --> L[Agent执行工具]\n L --> M[工具响应消息]\n M --> N[继续对话循环]\n```\n\n## 不同提供商的工具调用差异\n\n| 特性 | OpenAI | Anthropic | 其他提供商 |\n|------|--------|-----------|------------|\n| 工具定义格式 | `custom` 类型 + `format` | 集成到消息结构 | 各不相同 |\n| 流式响应 | `AIMessageChunk` 增量 | `AIMessageChunk` 增量 | 差异较大 |\n| 元数据传递 | `tool_calls` 数组 | `additional_kwargs` | 需适配 |\n| 格式翻译器 | `BlockTranslator` | 需扩展 | 需扩展 |\n\n## 最佳实践\n\n### 工具定义规范\n\n在 LangChain.js 中定义工具时，应遵循以下规范以确保最佳的跨提供商兼容性：\n\n1. **使用精确的 TypeScript 类型**：为工具的输入和输出定义完整的类型，避免使用 `any` 类型\n2. **提供清晰的描述**：工具描述应准确反映功能，便于模型理解何时调用\n3. **使用 Zod Schema**：通过 Zod 定义参数验证架构，确保传入参数的有效性\n\n### 消息处理建议\n\n处理包含工具调用的消息时，建议采用以下策略：\n\n1. **始终检查翻译器**：在处理提供商特定格式时，先检查是否存在对应的翻译器\n2. **合并重复工具调用**：使用 `AIMessage` 中的过滤逻辑避免重复添加\n3. **处理缺失字段**：工具调用块中的 `id` 是可选的，应有合理的降级处理\n\n### 扩展新提供商\n\n为新的 AI 服务提供商添加工具集成支持时，需要实现以下组件：\n\n1. 创建提供商特定的工具格式转换器\n2. 实现 `BlockTranslator` 接口的转换方法\n3. 在 `getTranslator` 注册新的翻译器\n4. 编写集成测试验证功能正确性\n\n## 总结\n\nLangChain.js 的扩展提供商与工具集成系统通过分层架构实现了灵活而强大的工具调用能力。核心类型系统提供了统一的工具定义规范，消息格式转换层确保了不同提供商之间的互操作性，而 Provider 适配层则处理了各个平台的特定实现细节。\n\n这套系统的主要优势包括：类型安全的消息处理、统一的工具定义接口、灵活的消息格式转换，以及完善的测试支持。开发者可以通过实现对应的翻译器和适配器，将新的 AI 提供商集成到 LangChain.js 生态系统中，同时保持与其他提供商的一致性体验。\n\n---\n\n\n\n## 多环境部署支持\n\n### 相关页面\n\n相关主题：[依赖管理与测试策略](#page-8), [示例代码与最佳实践](#page-10)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [environment_tests/README.md](https://github.com/langchain-ai/langchainjs/blob/main/environment_tests/README.md)\n- [environment_tests/docker-compose.yml](https://github.com/langchain-ai/langchainjs/blob/main/environment_tests/docker-compose.yml)\n- [environment_tests/test-exports-bun/src/entrypoints.js](https://github.com/langchain-ai/langchainjs/blob/main/environment_tests/test-exports-bun/src/entrypoints.js)\n- [environment_tests/test-exports-cf/src/entrypoints.js](https://github.com/langchain-ai/langchainjs/blob/main/environment_tests/test-exports-cf/src/entrypoints.js)\n- [environment_tests/test-exports-vite/src/entrypoints.js](https://github.com/langchain-ai/langchainjs/blob/main/environment_tests/test-exports-vercel/src/entrypoints.js)\n- [libs/langchain-core/src/utils/signal.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-core/src/utils/signal.ts)\n
\n\n# 多环境部署支持\n\nLangChain.js 通过一套完整的多环境部署测试框架，确保核心库能够在不同的 JavaScript 运行时环境和构建工具中正确运行。该系统覆盖了从服务器端 Node.js 到边缘计算平台的多样化部署场景。\n\n## 概述与设计目标\n\nLangChain.js 的多环境部署支持旨在验证包的导出结构（exports）与目标运行时环境的兼容性。不同的部署环境对模块格式、异步处理和文件系统访问有着截然不同的要求，LangChain.js 通过自动化测试确保这些差异不会导致运行时错误。\n\n核心设计原则包括：\n\n- **环境无关性**：核心抽象层独立于特定运行时环境\n- **导出兼容性**：通过 `package.json` 的 `exports` 字段精细控制不同环境的入口点\n- **异步标准化**：统一 `AsyncLocalStorage` 和 `AbortSignal` 等跨环境 API 的行为\n\n资料来源：[libs/langchain-core/src/utils/signal.ts:1-50]()\n\n## 支持的部署环境\n\nLangChain.js 维护了一套针对主流运行时和构建工具的兼容性测试：\n\n| 环境类型 | 包名 | 用途说明 |\n|---------|------|---------|\n| Node.js | `@langchain/core` | 服务端默认环境，支持完整 Node.js API |\n| Bun | `test-exports-bun` | Bun 运行时兼容性测试 |\n| Cloudflare Workers | `test-exports-cf` | 边缘计算环境测试 |\n| Vercel Edge Functions | `test-exports-vercel` | Vercel 边缘函数环境测试 |\n| Vite | `test-exports-vite` | 前端构建工具兼容性测试 |\n\n资料来源：[environment_tests/README.md]()\n资料来源：[environment_tests/test-exports-bun/src/entrypoints.js]()\n资料来源：[environment_tests/test-exports-cf/src/entrypoints.js]()\n\n## 测试框架架构\n\n### 目录结构\n\n```\nenvironment_tests/\n├── README.md # 测试框架说明文档\n├── docker-compose.yml # Docker 编排配置\n├── test-exports-bun/ # Bun 运行时测试\n│ └── src/\n│ └── entrypoints.js # 入口点导出验证\n├── test-exports-cf/ # Cloudflare Workers 测试\n│ └── src/\n│ └── entrypoints.js\n├── test-exports-vercel/ # Vercel Edge Functions 测试\n│ └── src/\n│ └── entrypoints.js\n└── test-exports-vite/ # Vite 构建工具测试\n └── src/\n └── entrypoints.js\n```\n\n资料来源：[environment_tests/docker-compose.yml]()\n\n### 测试流程\n\n```mermaid\ngraph TD\n A[开始测试] --> B[加载 Docker Compose 配置]\n B --> C{选择测试环境}\n C -->|Bun| D[运行 test-exports-bun]\n C -->|Cloudflare| E[运行 test-exports-cf]\n C -->|Vercel| F[运行 test-exports-vercel]\n C -->|Vite| G[运行 test-exports-vite]\n D --> H[验证入口点导出]\n E --> H\n F --> H\n G --> H\n H --> I{所有测试通过?}\n I -->|是| J[测试成功]\n I -->|否| K[报告环境兼容性问题]\n```\n\n## Docker 容器化测试环境\n\nLangChain.js 使用 Docker Compose 管理多环境测试容器，确保测试环境的一致性和可重复性。\n\n### 服务配置\n\n测试框架定义了多个服务容器，每个容器运行特定的运行时环境：\n\n- **基础镜像选择**：针对不同运行环境选择合适的基础镜像\n- **依赖安装**：在容器启动时安装项目依赖\n- **测试执行**：运行入口点验证脚本\n\n资料来源：[environment_tests/docker-compose.yml]()\n\n## 核心导出机制\n\n### package.json exports 字段\n\nLangChain.js 通过 `package.json` 的 `exports` 字段实现条件导出，为不同环境提供定制化的模块入口：\n\n```javascript\n// 条件导出的典型配置\n{\n \"exports\": {\n \".\": {\n \"types\": \"./dist/index.d.ts\",\n \"import\": \"./dist/index.js\",\n \"require\": \"./dist/index.cjs\",\n \"default\": \"./dist/index.js\"\n },\n \"./utils\": {\n \"types\": \"./dist/utils.d.ts\",\n \"import\": \"./dist/utils.js\"\n }\n }\n}\n```\n\n资料来源：[libs/langchain-core/package.json:1-30]()\n\n### 入口点验证\n\n每个环境测试包包含一个 `entrypoints.js` 文件，用于验证关键导出是否正确可用：\n\n```javascript\n// test-exports-bun/src/entrypoints.js 示例\nexport * from \"@langchain/core\";\n// 验证核心导出在 Bun 环境中可访问\n```\n\n资料来源：[environment_tests/test-exports-bun/src/entrypoints.js]()\n\n## 异步与信号处理\n\nLangChain.js 的核心模块实现了跨环境兼容的异步处理机制，这对于在边缘计算环境中运行至关重要。\n\n### AbortSignal 支持\n\n核心模块支持标准的 `AbortSignal` 接口，允许调用者取消异步操作：\n\n```typescript\n// libs/langchain-core/src/utils/signal.ts\nexport interface AbortSignalLike {\n readonly aborted: boolean;\n addEventListener: (type: \"abort\", listener: () => void) => void;\n removeEventListener: (type: \"abort\", listener: () => void) => void;\n}\n```\n\n资料来源：[libs/langchain-core/src/utils/signal.ts:1-30]()\n\n### AsyncLocalStorage 适配\n\n在不支持 `AsyncLocalStorage` 的环境中（如某些边缘运行时），LangChain.js 提供了优雅的降级处理机制，确保核心功能不受影响。\n\n## 边缘计算环境特殊考虑\n\n### Cloudflare Workers\n\nCloudflare Workers 环境对代码有以下限制：\n\n| 限制类型 | 说明 | 处理方式 |\n|---------|------|---------|\n| 文件系统 | 仅支持 KV 和 R2 存储 | 使用抽象层访问存储 |\n| 运行时 | V8 isolates，无 Node.js API | 使用 web 标准 API |\n| 启动时间 | 需极快初始化 | 懒加载非关键模块 |\n\n资料来源：[environment_tests/test-exports-cf/src/entrypoints.js]()\n\n### Vercel Edge Functions\n\nVercel Edge Functions 运行在 V8 isolates 上，与 Cloudflare Workers 类似需要避免使用 Node.js 特定 API。\n\n## 开发工作流\n\n### 本地测试\n\n开发者可以使用以下命令在本地运行多环境测试：\n\n```bash\n# 启动所有测试环境容器\ndocker-compose up\n\n# 运行特定环境测试\npnpm --filter test-exports-bun test\npnpm --filter test-exports-cf test\n```\n\n### CI/CD 集成\n\n多环境测试通常集成到持续集成流程中，确保每次代码变更不会破坏特定环境的兼容性：\n\n1. 检出代码\n2. 安装依赖\n3. 构建核心包\n4. 运行各环境测试\n5. 收集并报告结果\n\n## 最佳实践\n\n### 包开发者指南\n\n1. **避免 Node.js 特定 API**：使用 web 标准 API 或条件导入\n2. **使用条件导出**：在 `package.json` 中正确配置 `exports` 字段\n3. **测试所有目标环境**：在开发周期早期发现问题\n4. **处理缺失的全局对象**：如 `AsyncLocalStorage` 不可用时的降级方案\n\n### 环境检测模式\n\n```typescript\n// 检测当前环境类型\nconst isEdge = typeof EdgeRuntime !== \"undefined\";\nconst isNode = typeof process !== \"undefined\" && process.versions?.node;\nconst isBrowser = typeof window !== \"undefined\";\n```\n\n## 相关资源\n\n- [LangChain.js 主仓库](https://github.com/langchain-ai/langchainjs)\n- [@langchain/core 核心包](https://github.com/langchain-ai/langchainjs/tree/main/libs/langchain-core)\n- [环境测试框架](https://github.com/langchain-ai/langchainjs/tree/main/environment_tests)\n\n---\n\n\n\n## 依赖管理与测试策略\n\n### 相关页面\n\n相关主题：[多环境部署支持](#page-7), [扩展开发指南](#page-9)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [package.json](https://github.com/langchain-ai/langchainjs/blob/main/package.json)\n- [pnpm-workspace.yaml](https://github.com/langchain-ai/langchainjs/blob/main/pnpm-workspace.yaml)\n- [internal/standard-tests/src/index.ts](https://github.com/langchain-ai/langchainjs/blob/main/internal/standard-tests/src/index.ts)\n- [dependency_range_tests/docker-compose.yml](https://github.com/langchain-ai/langchainjs/blob/main/dependency_range_tests/docker-compose.yml)\n- [dependency_range_tests/scripts/langchain/node/update_resolutions_latest.js](https://github.com/langchain-ai/langchainjs/blob/main/dependency_range_tests/scripts/langchain/node/update_resolutions_latest.js)\n
\n\n# 依赖管理与测试策略\n\n## 概述\n\nLangChain.js 是一个采用 monorepo 架构的 TypeScript 项目，使用 pnpm workspaces 进行依赖管理，并通过多层次的测试策略确保代码质量。依赖管理策略涵盖了版本控制、依赖范围测试和标准化测试，而测试策略则包括单元测试、集成测试、标准单元测试和标准集成测试等多种测试模式。\n\n该项目的依赖管理核心目标是确保所有 `@langchain/*` 包共享相同版本的 `@langchain/core`，避免因核心库版本不一致导致的兼容性问题。资料来源：[libs/langchain-core/package.json](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-core/package.json)()\n\n## Monorepo 架构\n\n### 工作区结构\n\nLangChain.js 使用 pnpm workspaces 管理多包工作区，所有包位于 `libs/` 目录下。资料来源：[pnpm-workspace.yaml](https://github.com/langchain-ai/langchainjs/blob/main/pnpm-workspace.yaml)()\n\n```mermaid\ngraph TD\n A[langchainjs Root] --> B[pnpm-workspace.yaml]\n A --> C[package.json]\n A --> D[libs/]\n \n D --> E[langchain-core]\n D --> F[langchain-classic]\n D --> G[langchain-textsplitters]\n D --> H[providers/]\n D --> I[community/]\n \n H --> H1[langchain-anthropic]\n H --> H2[langchain-aws]\n H --> H3[langchain-cohere]\n H --> H4[langchain-xai]\n H --> H5[langchain-mistralai]\n H --> H6[langchain-tavily]\n```\n\n### 包类型分类\n\n| 目录 | 包类型 | 说明 |\n|------|--------|------|\n| `libs/langchain-core` | 核心包 | 包含 LangChain.js 的核心抽象和模式定义 |\n| `libs/langchain-classic` | 兼容性包 | 包含从 v0.x 迁移的遗留链和功能 |\n| `libs/langchain-textsplitters` | 工具包 | 文本分割器实现 |\n| `libs/providers/*` | 集成包 | 各第三方服务提供商集成 |\n| `libs/community/*` | 社区包 | 社区维护的集成 |\n| `internal/standard-tests` | 内部工具 | 标准化测试框架 |\n\n## 依赖管理策略\n\n### 核心依赖一致性\n\nLangChain.js 要求所有包共享同一个 `@langchain/core` 实例。核心库采用 tilde 依赖版本策略，确保向后兼容性。资料来源：[libs/langchain-core/README.md](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-core/README.md)()\n\n```json\n{\n \"peerDependencies\": {\n \"@langchain/core\": \"~0.3.0\"\n },\n \"devDependencies\": {\n \"@langchain/core\": \"~0.3.0\"\n }\n}\n```\n\n### 依赖覆盖机制\n\n项目推荐在用户项目的 `package.json` 中添加依赖覆盖配置，以强制所有包使用相同版本的核心库：\n\n```mermaid\ngraph LR\n A[用户项目] --> B[dependencies]\n A --> C[resolutions]\n A --> D[overrides]\n A --> E[pnpm.overrides]\n \n B --> F[@langchain/core]\n B --> G[@langchain/anthropic]\n B --> H[@langchain/cohere]\n \n C --> F\n D --> F\n E --> F\n```\n\n支持的包管理器及其覆盖字段：\n\n| 包管理器 | 配置字段 | 示例 |\n|----------|----------|------|\n| npm/yarn | `resolutions` | `\"@langchain/core\": \"^0.3.0\"` |\n| npm/yarn | `overrides` | `\"@langchain/core\": \"^0.3.0\"` |\n| pnpm | `pnpm.overrides` | `\"@langchain/core\": \"^0.3.0\"` |\n\n资料来源：[libs/providers/langchain-anthropic/README.md](https://github.com/langchain-ai/langchainjs/blob/main/libs/providers/langchain-anthropic/README.md)()\n\n### 依赖范围测试\n\n项目通过 Docker 环境测试不同依赖版本组合的兼容性，确保包在依赖版本变化时仍能正常工作。\n\n#### Docker 测试环境配置\n\n依赖范围测试使用 Docker Compose 定义测试环境：\n\n```yaml\nservices:\n test:\n build:\n context: .\n dockerfile: Dockerfile\n volumes:\n - .:/app\n environment:\n - NODE_ENV=test\n command: pnpm test:ranges\n```\n\n资料来源：[dependency_range_tests/docker-compose.yml](https://github.com/langchain-ai/langchainjs/blob/main/dependency_range_tests/docker-compose.yml)()\n\n#### 自动更新依赖脚本\n\n项目提供脚本自动更新依赖到最新版本：\n\n```javascript\n// update_resolutions_latest.js\nasync function updateResolutions() {\n // 获取 @langchain/core 最新版本\n const latestCore = await getLatestVersion(\"@langchain/core\");\n \n // 更新所有包的 resolutions\n await updateWorkspaceResolutions(latestCore);\n}\n```\n\n该脚本遍历工作区中的所有包，将 `@langchain/core` 依赖更新到最新版本，验证兼容性后提交更改。资料来源：[dependency_range_tests/scripts/langchain/node/update_resolutions_latest.js](https://github.com/langchain-ai/langchainjs/blob/main/dependency_range_tests/scripts/langchain/node/update_resolutions_latest.js)()\n\n## 测试策略\n\n### 测试类型概览\n\nLangChain.js 采用多层次的测试策略，确保代码质量和向后兼容性：\n\n```mermaid\ngraph TD\n A[测试策略] --> B[单元测试]\n A --> C[集成测试]\n A --> D[标准测试]\n A --> E[导出测试]\n A --> F[依赖范围测试]\n \n B --> B1[vitest run]\n C --> C1[vitest run --mode int]\n D --> D1[standard-unit]\n D --> D2[standard-int]\n E --> E1[test:exports:docker]\n F --> F1[test:ranges:docker]\n```\n\n资料来源：[package.json](https://github.com/langchain-ai/langchainjs/blob/main/package.json)()\n\n### 单元测试\n\n单元测试使用 Vitest 框架运行，每个包在 `src/` 目录下包含 `tests/` 文件夹：\n\n| 测试类型 | 文件后缀 | 运行命令 |\n|----------|----------|----------|\n| 单元测试 | `.test.ts` | `vitest run` |\n| 集成测试 | `.int.test.ts` | `vitest run --mode int` |\n| 监视模式 | - | `vitest` 或 `vitest --watch` |\n\n```bash\n# 运行单元测试\npnpm test\n\n# 运行集成测试\npnpm test:int\n\n# 监视模式运行\npnpm test:watch\n```\n\n资料来源：[libs/langchain-core/package.json](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-core/package.json)()\n\n### 标准测试框架\n\n`@langchain/standard-tests` 是项目内部的标准化测试框架，为所有 LangChain 包提供一致的测试接口。资料来源：[internal/standard-tests/src/index.ts](https://github.com/langchain-ai/langchainjs/blob/main/internal/standard-tests/src/index.ts)()\n\n#### 标准测试模块结构\n\n```mermaid\nclassDiagram\n class StandardTests {\n +runUnitTests()\n +runIntegrationTests()\n +runChatModelTests()\n +runEmbeddingsTests()\n +runVectorStoreTests()\n }\n \n class UnitTestRunner {\n +run()\n +validateOutput()\n }\n \n class IntegrationTestRunner {\n +run()\n +setupFixtures()\n +teardown()\n }\n \n StandardTests --> UnitTestRunner\n StandardTests --> IntegrationTestRunner\n```\n\n#### 测试模式\n\n| 模式 | 命令 | 说明 |\n|------|------|------|\n| 标准单元测试 | `test:standard:unit` | 使用标准测试框架的单元测试 |\n| 标准集成测试 | `test:standard:int` | 使用标准测试框架的集成测试 |\n| 完整标准测试 | `test:standard` | 运行所有标准测试 |\n\n```bash\n# 运行标准测试\npnpm test:standard:unit\npnpm test:standard:int\npnpm test:standard\n```\n\n资料来源：[package.json](https://github.com/langchain-ai/langchainjs/blob/main/package.json)()\n\n### 导出兼容性测试\n\n导出测试验证包的导出接口在不同环境（ESM/CJS）下的兼容性：\n\n```mermaid\ngraph LR\n A[导出测试] --> B[ESM环境]\n A --> C[CJS环境]\n A --> D[Docker容器]\n \n B --> E[import测试]\n C --> F[require测试]\n D --> G[跨环境验证]\n```\n\n使用 Docker 环境进行导出测试：\n\n```bash\npnpm test:exports:docker\n```\n\n资料来源：[package.json](https://github.com/langchain-ai/langchainjs/blob/main/package.json)()\n\n### 依赖范围测试\n\n依赖范围测试验证包在不同核心库版本下的行为：\n\n```mermaid\ngraph TD\n A[依赖范围测试] --> B[Docker环境]\n A --> C[版本矩阵]\n A --> D[兼容性验证]\n \n C --> C1[@langchain/core ^0.2.0]\n C --> C2[@langchain/core ^0.3.0]\n C --> C3[@langchain/core latest]\n \n D --> D1[API兼容性]\n D --> D2[类型检查]\n D --> D3[运行时测试]\n```\n\n运行依赖范围测试：\n\n```bash\npnpm test:ranges:docker\n```\n\n资料来源：[package.json](https://github.com/langchain-ai/langchainjs/blob/main/package.json)()\n\n## CI/CD 集成\n\n### Turbo 构建系统\n\n项目使用 Turbo 进行构建和测试编排：\n\n```json\n{\n \"scripts\": {\n \"test:unit:ci\": \"turbo test\",\n \"build\": \"turbo build\"\n }\n}\n```\n\nTurbo 的优势：\n\n| 特性 | 说明 |\n|------|------|\n| 增量构建 | 仅重新构建变更的包 |\n| 并行执行 | 充分利用多核 CPU |\n| 远程缓存 | 共享 CI 缓存 |\n| 任务管道 | 自动解析任务依赖 |\n\n资料来源：[package.json](https://github.com/langchain-ai/langchainjs/blob/main/package.json)()\n\n### 过滤规则\n\nCI 配置使用过滤器排除不需要测试的包：\n\n```bash\n# 排除导出测试、示例和创建集成模板\npnpm test:unit:ci --filter=\"!test-exports-*\" --filter=\"!examples\" --filter=\"!create-langchain-integration\"\n```\n\n## 包开发指南\n\n### 创建新集成包\n\n项目提供了集成包模板 `create-langchain-integration`，开发者可以使用该模板快速创建新的提供商集成。资料来源：[libs/create-langchain-integration/template/README.md](https://github.com/langchain-ai/langchainjs/blob/main/libs/create-langchain-integration/template/README.md)()\n\n新包开发流程：\n\n1. 使用模板创建包结构\n2. 添加 `@langchain/core` 为 peer dependency 和 dev dependency\n3. 实现集成代码\n4. 添加单元测试和集成测试\n5. 运行标准测试验证\n6. 提交更改\n\n### 包配置示例\n\n```json\n{\n \"name\": \"@langchain/example-provider\",\n \"version\": \"0.0.1\",\n \"type\": \"module\",\n \"dependencies\": {\n \"@example/sdk\": \"^1.0.0\"\n },\n \"peerDependencies\": {\n \"@langchain/core\": \"~0.3.0\"\n },\n \"devDependencies\": {\n \"@langchain/core\": \"~0.3.0\"\n }\n}\n```\n\n## 最佳实践\n\n### 依赖管理\n\n| 实践 | 说明 |\n|------|------|\n| 使用 peerDependencies | 声明运行时依赖，让消费者提供核心库 |\n| 使用 devDependencies | 仅开发时需要的依赖 |\n| 避免直接依赖 | 集成包不应直接依赖其他 `@langchain/*` 包 |\n| 版本一致性 | 确保所有包使用相同版本的 `@langchain/core` |\n\n### 测试覆盖\n\n| 测试类型 | 覆盖率目标 | 运行频率 |\n|----------|------------|----------|\n| 单元测试 | 80%+ | 每次提交 |\n| 集成测试 | 核心功能全覆盖 | 每次 PR |\n| 标准测试 | 所有包必须通过 | 发布前 |\n| 导出测试 | ESM/CJS 双环境 | 发布前 |\n| 依赖范围测试 | 主流版本组合 | 每周 |\n\n### 构建验证\n\n在发布包之前，确保完成以下验证步骤：\n\n```mermaid\ngraph LR\n A[代码编写] --> B[单元测试]\n B --> C[集成测试]\n C --> D[标准测试]\n D --> E[导出测试]\n E --> F[依赖范围测试]\n F --> G[发布]\n\n---\n\n\n\n## 扩展开发指南\n\n### 相关页面\n\n相关主题：[扩展提供商与工具集成](#page-6), [示例代码与最佳实践](#page-10)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [libs/create-langchain-integration/create-app.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/create-langchain-integration/create-app.ts)\n- [libs/create-langchain-integration/template/package.json](https://github.com/langchain-ai/langchainjs/blob/main/libs/create-langchain-integration/template/package.json)\n- [CONTRIBUTING.md](https://github.com/langchain-ai/langchainjs/blob/main/CONTRIBUTING.md)\n- [libs/langchain-mcp-adapters/src/client.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-mcp-adapters/src/client.ts)\n- [libs/langchain-mcp-adapters/src/tools.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-mcp-adapters/src/tools.ts)\n- [libs/langchain-core/README.md](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-core/README.md)\n- [libs/providers/langchain-anthropic/README.md](https://github.com/langchain-ai/langchainjs/blob/main/libs/providers/langchain-anthropic/README.md)\n- [libs/langchain-textsplitters/README.md](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-textsplitters/README.md)\n
\n\n# 扩展开发指南\n\nLangChain.js 采用模块化架构设计，支持开发者通过扩展机制集成第三方服务和功能。本指南涵盖创建新的集成包、扩展现有功能以及贡献代码的完整流程。\n\n## 概述\n\nLangChain.js 的扩展开发体系包含以下核心组件：\n\n| 组件类型 | 说明 | 位置 |\n|---------|------|------|\n| 集成包 | 特定服务商的 SDK 封装（如 Anthropic、AWS、Cohere） | `libs/providers/` |\n| 核心扩展 | 文本分割器、工具适配器等核心功能 | `libs/langchain-*` |\n| MCP 适配器 | Model Context Protocol 工具集成 | `libs/langchain-mcp-adapters/` |\n| 社区扩展 | 社区贡献的集成 | `libs/community/` |\n\n## 项目结构\n\nLangChain.js 使用 pnpm monorepo 管理所有包，每个扩展包遵循统一的目录结构：\n\n```\nlibs/\n├── create-langchain-integration/ # 集成创建脚手架\n│ ├── create-app.ts # CLI 入口\n│ └── template/ # 包模板目录\n│ └── package.json # 模板 package.json\n├── providers/ # 官方提供商集成\n│ ├── langchain-anthropic/\n│ ├── langchain-aws/\n│ └── langchain-cohere/\n├── langchain-core/ # 核心抽象层\n├── langchain-textsplitters/ # 文本分割实现\n└── langchain-mcp-adapters/ # MCP 协议适配器\n```\n\n## 创建新集成包\n\n### 使用脚手架工具\n\nLangChain.js 提供了自动化工具来生成新的集成包骨架：\n\n```bash\npnpm create @langchain/integration \n```\n\n该命令调用 `create-app.ts` 中的逻辑，生成符合规范的包结构。脚手架会自动配置：\n\n- TypeScript 编译配置\n- 包名命名规范（`@langchain/`）\n- 依赖版本锁定策略\n\n### 包模板结构\n\n生成的模板包含以下关键文件：\n\n| 文件路径 | 用途 |\n|---------|------|\n| `package.json` | 包元数据、脚本、依赖声明 |\n| `README.md` | 安装和使用文档 |\n| `src/index.ts` | 包导出入口 |\n| `src/.ts` | 主要功能实现 |\n\n### package.json 配置要求\n\n集成包的 `package.json` 必须遵循以下配置规范：\n\n```json\n{\n \"name\": \"@langchain/\",\n \"version\": \"0.0.1\",\n \"type\": \"module\",\n \"dependencies\": {\n \"\": \"^\"\n },\n \"peerDependencies\": {\n \"@langchain/core\": \"^1.0.0\"\n },\n \"devDependencies\": {\n \"@langchain/core\": \"workspace:^\"\n }\n}\n```\n\n**关键配置说明：**\n\n| 字段 | 要求 | 说明 |\n|-----|------|------|\n| `type` | 必须为 `\"module\"` | ESM 模块支持 |\n| `peerDependencies` | 必须包含 `@langchain/core` | 运行时依赖核心包 |\n| `devDependencies` | 建议使用 `workspace:^` | 开发时引用本地 core |\n\n资料来源：[libs/create-langchain-integration/template/package.json](https://github.com/langchain-ai/langchainjs/blob/main/libs/create-langchain-integration/template/package.json)\n\n## 依赖管理策略\n\n### @langchain/core 版本锁定\n\n为确保所有 LangChain 包使用相同版本的 `@langchain/core`，需要在项目根目录的 `package.json` 中添加版本覆盖配置：\n\n```json\n{\n \"resolutions\": {\n \"@langchain/core\": \"^0.3.0\"\n },\n \"overrides\": {\n \"@langchain/core\": \"^0.3.0\"\n },\n \"pnpm\": {\n \"overrides\": {\n \"@langchain/core\": \"^0.3.0\"\n }\n }\n}\n```\n\n资料来源：[libs/providers/langchain-anthropic/README.md](https://github.com/langchain-ai/langchainjs/blob/main/libs/providers/langchain-anthropic/README.md)\n\n## MCP 适配器开发\n\nModel Context Protocol (MCP) 适配器允许 LangChain 与外部 MCP 服务器通信，访问其提供的工具。\n\n### 客户端架构\n\n```mermaid\ngraph TD\n A[LangChain Agent] --> B[MCPClient]\n B --> C[MCP Server]\n C --> D[Remote Tools]\n B --> E[MCPTools]\n E --> A\n```\n\n### 核心组件\n\n**MCPTools 类** 提供 MCP 工具到 LangChain 工具的转换：\n\n```typescript\n// 将 MCP 工具适配为 LangChain 可用格式\nexport class MCPTools {\n constructor(\n private client: MCPClient,\n private toolNames?: string[]\n ) {}\n\n getTools(): Tool[] {\n // 返回适配后的工具列表\n }\n}\n```\n\n资料来源：[libs/langchain-mcp-adapters/src/tools.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-mcp-adapters/src/tools.ts)\n\n### 客户端初始化\n\n```typescript\nimport { MCPClient } from \"./client\";\n\nconst client = new MCPClient({\n name: \"my-mcp-client\",\n version: \"1.0.0\",\n command: \"npx\",\n args: [\"-y\", \"@modelcontextprotocol/server-filesystem\", \"./data\"]\n});\n```\n\n资料来源：[libs/langchain-mcp-adapters/src/client.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-mcp-adapters/src/client.ts)\n\n## 构建和测试\n\n### 构建脚本\n\n集成包应包含标准的构建和测试脚本：\n\n| 脚本 | 用途 |\n|-----|------|\n| `pnpm build` | 编译 TypeScript 生成 dist 目录 |\n| `pnpm test` | 运行单元测试 |\n| `pnpm test:int` | 运行集成测试 |\n| `pnpm lint` | 代码风格检查 |\n| `pnpm format` | 代码格式化 |\n\n### 构建流程\n\nLangChain.js 使用 `turbo` 作为构建编排工具：\n\n```bash\npnpm build --filter @langchain/\n```\n\n单包构建命令：\n\n```bash\ncd libs/providers/langchain-anthropic\npnpm build\n```\n\n### 测试规范\n\n- 单元测试文件命名：`.test.ts`\n- 集成测试文件命名：`.int.test.ts`\n- 测试文件位置：`src/tests/` 或根目录 `tests/`\n\n资料来源：[libs/langchain-textsplitters/README.md](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-textsplitters/README.md)\n\n## 贡献代码\n\n### 贡献流程\n\n```mermaid\ngraph LR\n A[Fork 仓库] --> B[创建功能分支]\n B --> C[开发实现]\n C --> D[编写测试]\n D --> E[提交 Pull Request]\n E --> F[Code Review]\n F --> G[合并到主分支]\n```\n\n### 代码规范\n\n- 遵循 TypeScript 最佳实践\n- 使用 ESLint 进行代码检查\n- 使用 Prettier 进行代码格式化\n- 确保所有新功能包含测试覆盖\n\n### 提交规范\n\n```bash\npnpm lint && pnpm format\n```\n\n运行提交前的检查：\n\n```bash\npnpm lint:eslint && pnpm lint:dpdm\n```\n\n`dpdm` 工具检查动态导入的循环依赖问题。\n\n资料来源：[CONTRIBUTING.md](https://github.com/langchain-ai/langchainjs/blob/main/CONTRIBUTING.md)\n\n## 包导出配置\n\n### package.json exports 字段\n\n新包应配置 `exports` 字段以支持按需导入：\n\n```json\n{\n \"exports\": {\n \".\": {\n \"import\": \"./dist/index.js\",\n \"types\": \"./dist/index.d.ts\"\n },\n \"./\": {\n \"import\": \"./dist/.js\",\n \"types\": \"./dist/.d.ts\"\n }\n }\n}\n```\n\n添加新导出后，需要执行 `pnpm build` 重新生成入口文件。\n\n资料来源：[libs/langchain-textsplitters/README.md](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-textsplitters/README.md)\n\n## 最佳实践\n\n### 1. 版本兼容性\n\n- 使用 `~` 而非 `^` 来锁定 `@langchain/core` 依赖\n- 允许补丁版本更新，限制次版本兼容性\n\n```json\n\"peerDependencies\": {\n \"@langchain/core\": \"~0.3.0\"\n}\n```\n\n### 2. ESM 和 CJS 兼容\n\n构建步骤应生成兼容两种模块系统的代码。使用 `tsdown` 进行编译：\n\n```bash\ntsdown src/index.ts --dts\n```\n\n### 3. 文档编写\n\n每个集成包应包含 README.md，包含：\n\n- 安装说明\n- 环境变量配置\n- 基本使用示例\n- API 参考链接\n\n### 4. 类型安全\n\n- 导出完整的 TypeScript 类型定义\n- 使用 Zod 进行运行时验证\n- 避免使用 `any` 类型\n\n## 扩展包注册表\n\n| 包类型 | 命名空间 | 示例 |\n|-------|---------|------|\n| 官方提供商 | `@langchain/` | `@langchain/anthropic`, `@langchain/cohere` |\n| 核心功能 | `@langchain/` | `@langchain/textsplitters`, `@langchain/core` |\n| 社区包 | `@langchain/community` | 社区维护的集成 |\n| MCP 适配器 | `@langchain/mcp-adapters` | MCP 协议支持 |\n\n## 常见问题\n\n**Q: 如何为现有包添加新功能？**\n\n在 `src/` 目录创建新文件，然后在 `src/index.ts` 中导出。修改后运行 `pnpm build` 更新构建产物。\n\n**Q: 如何测试包之间的依赖关系？**\n\n使用 `pnpm why ` 检查依赖树，确保没有意外的版本冲突。\n\n**Q: MCP 适配器支持哪些 MCP 服务器？**\n\n理论上支持所有符合 MCP 协议规范的服务器，包括文件操作、数据库访问、API 调用等类型。\n\n---\n\n\n\n## 示例代码与最佳实践\n\n### 相关页面\n\n相关主题：[Agent 与 Chains 实现](#page-3), [扩展开发指南](#page-9)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [libs/langchain-textsplitters/README.md](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-textsplitters/README.md)\n- [libs/langchain/src/agents/middleware/hitl.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain/src/agents/middleware/hitl.ts)\n- [libs/langchain/src/agents/utils.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain/src/agents/utils.ts)\n- [libs/providers/langchain-anthropic/src/chat_models.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/providers/langchain-anthropic/src/chat_models.ts)\n- [libs/providers/langchain-openai/src/chat_models/index.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/providers/langchain-openai/src/chat_models/index.ts)\n- [libs/langchain-core/src/language_models/event.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-core/src/language_models/event.ts)\n
\n\n# 示例代码与最佳实践\n\n本页面汇集了 LangChain.js 框架的核心示例代码和最佳实践指南，涵盖文本分割、代理中间件、聊天模型集成、事件处理等关键功能模块。通过这些示例，开发者可以快速掌握如何在实际项目中应用 LangChain.js 构建 LLM 驱动的应用程序。\n\n## 核心功能概览\n\nLangChain.js 提供了丰富的功能模块，帮助开发者构建模块化、可组合的 LLM 应用程序。以下表格总结了主要功能模块及其用途：\n\n| 功能模块 | 包名 | 主要用途 |\n|---------|------|---------|\n| 文本分割 | `@langchain/textsplitters` | 将长文档分割成适合处理的块 |\n| 代理中间件 | `langchain/agents` | 为代理添加人机交互、监控等能力 |\n| 聊天模型 | `@langchain/anthropic`, `@langchain/openai` | 与各种 LLM 提供商集成 |\n| 事件系统 | `@langchain/core` | 处理流式输出和状态更新 |\n| 工具系统 | `@langchain/core/tools` | 定义和执行 LLM 工具调用 |\n\n## 文本分割器使用指南\n\n文本分割是 RAG（检索增强生成）流水线中的关键步骤。LangChain.js 提供了多种文本分割器实现，最常用的是 `RecursiveCharacterTextSplitter`。\n\n### HTML 文档分割示例\n\n以下示例展示了如何分割 HTML 文档：\n\n```typescript\nimport { RecursiveCharacterTextSplitter } from \"@langchain/textsplitters\";\n\nconst text = `\n\n \n 🦜️🔗 LangChain\n \n \n \n
\n

🦜️🔗 LangChain

\n

⚡ Building applications with LLMs through composability ⚡

\n
\n \n`;\n\nconst splitter = RecursiveCharacterTextSplitter.fromLanguage(\"html\", {\n chunkSize: 175,\n chunkOverlap: 20,\n});\nconst output = await splitter.createDocuments([text]);\n```\n\n资料来源：[examples/src/langchain-classic/indexes/html_text_splitter.ts:1-28]()\n\n### 分割器配置参数\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `chunkSize` | number | 每个文本块的最大字符数 |\n| `chunkOverlap` | number | 相邻块之间的重叠字符数 |\n| `separators` | string[] | 分割符列表，按优先级排序 |\n\n### 开发与测试\n\n`@langchain/textsplitters` 包的开发流程如下：\n\n```bash\n# 安装依赖\npnpm install\n\n# 构建包\npnpm build\n# 或从仓库根目录\npnpm build --filter @langchain/textsplitters\n\n# 运行测试\npnpm test # 单元测试\npnpm test:int # 集成测试\n```\n\n资料来源：[libs/langchain-textsplitters/README.md](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-textsplitters/README.md)\n\n## 代理中间件系统\n\nLangChain.js 的代理系统支持中间件扩展，允许开发者在代理执行过程中插入自定义逻辑。\n\n### 中间件状态解析\n\n代理中间件使用状态模式管理状态架构，支持两种主要类型：\n\n```typescript\nfunction parseMiddlewareState(\n stateSchema: unknown,\n state: Record\n): Record {\n // 处理 LangGraph StateSchema（具有 fields 属性）\n if (StateSchema.isInstance(stateSchema)) {\n const result: Record = {};\n for (const key of Object.keys(stateSchema.fields)) {\n if (key in state) {\n result[key] = state[key];\n }\n }\n return result;\n }\n\n // 使用 interopParse 处理 Zod schemas\n if (isInteropZodSchema(stateSchema)) {\n return interopParse(stateSchema as InteropZodObject, state);\n }\n\n throw new Error(`Invalid state schema type: ${typeof stateSchema}`);\n}\n```\n\n资料来源：[libs/langchain/src/agents/utils.ts:1-40]()\n\n### HITL 中断配置\n\n人机交互（HITL）中间件提供了精细的中断控制能力：\n\n```typescript\nexport interface InterruptOnConfig {\n /**\n * 允许的决策列表\n */\n allowedDecisions?: string[];\n /**\n * 动态可调用描述\n */\n description?: z.union([z.string(), DescriptionFunctionSchema]).optional();\n /**\n * 如果允许编辑，则关联参数的 JSON schema\n */\n argsSchema?: z.record(z.any()).optional();\n}\n```\n\n资料来源：[libs/langchain/src/agents/middleware/hitl.ts:1-50]()\n\n### 中间件架构流程\n\n```mermaid\ngraph TD\n A[用户输入] --> B[代理处理器]\n B --> C{检查中间件}\n C -->|存在 HITL| D[显示工具调用信息]\n C -->|其他中间件| E[执行中间件逻辑]\n D --> F[等待用户批准/编辑]\n E --> G[继续执行]\n F --> G\n G --> H[返回结果]\n```\n\n### 动态工具描述示例\n\n```typescript\nimport type {\n AgentBuiltInState,\n Runtime,\n DescriptionFactory,\n ToolCall,\n InterruptOnConfig\n} from \"langchain\";\n\nconst formatToolDescription: DescriptionFactory = (\n toolCall: ToolCall,\n state: AgentBuiltInState,\n runtime: Runtime\n) => {\n return `Tool: ${toolCall.name}\\nArguments:\\n${JSON.stringify(toolCall.args, null, 2)}`;\n};\n\nconst config: InterruptOnConfig = {\n allowedDecisions: [\"approve\", \"edit\"],\n description: formatToolDescription\n};\n```\n\n## 聊天模型集成\n\nLangChain.js 提供了统一的接口来集成多种聊天模型提供商。\n\n### Anthropic 模型\n\n`ChatAnthropicMessages` 类扩展了基础聊天模型，支持完整的 Anthropic API 功能：\n\n```typescript\nexport class ChatAnthropicMessages<\n CallOptions extends ChatAnthropicCallOptions = ChatAnthropicCallOptions,\n>\n extends BaseChatModel\n implements AnthropicInput\n{\n static lc_name() {\n return \"ChatAnthropic\";\n }\n\n get lc_secrets(): { [key: string]: string } | undefined {\n return {\n anthropicApiKey: \"ANTHROPIC_API_KEY\",\n apiKey: \"ANTHROPIC_API_KEY\",\n };\n }\n}\n```\n\n资料来源：[libs/providers/langchain-anthropic/src/chat_models.ts:1-30]()\n\n### OpenAI 模型\n\nOpenAI 聊天模型同样提供了流式输出和完整响应支持：\n\n```typescript\nfor await (const chunk of await llm.stream(input)) {\n console.log(chunk);\n}\n```\n\n输出示例：\n\n```txt\nAIMessageChunk {\n \"id\": \"chatcmpl-9u4NWB7yUeHCKdLr6jP3HpaOYHTqs\",\n \"content\": \"\"\n}\nAIMessageChunk {\n \"content\": \"J\"\n}\nAIMessageChunk {\n \"content\": \"'adore\"\n}\n```\n\n资料来源：[libs/providers/langchain-openai/src/chat_models/index.ts:1-50]()\n\n### 工具调用与结构化输出\n\n聊天模型支持两种结构化输出方式：\n\n| 方式 | 说明 | 使用场景 |\n|------|------|---------|\n| `withStructuredOutput()` | 使用函数调用 | 需要严格约束输出格式 |\n| JSON Schema Mode | 使用原生 JSON schema | 直接结构化输出 |\n\n```typescript\nimport { tool } from \"@langchain/core/tools\";\nimport { z } from \"zod\";\n\nconst getWeather = tool(\n async (input) => `Weather in ${input.location}`,\n {\n name: \"get_weather\",\n description: \"Get weather for a location\",\n schema: z.object({ location: z.string() }),\n extras: { defer_loading: true },\n }\n);\n```\n\n## 事件系统\n\nLangChain.js 的事件系统用于追踪和响应语言模型运行时的状态变化。\n\n### 内容块事件\n\n```typescript\n/**\n * 内容块增量更新时触发\n */\nexport interface ContentBlockDeltaEvent {\n event: \"content-block-delta\";\n /** 正在更新的块的位置索引 */\n index: number;\n /** 增量内容块 */\n delta: ContentBlockDelta;\n}\n\n/**\n * 内容块完成时触发\n */\nexport interface ContentBlockFinishEvent {\n event: \"content-block-finish\";\n /** 完成的块的位置索引 */\n index: number;\n /** 最终内容块 */\n content: ContentBlock;\n}\n```\n\n资料来源：[libs/langchain-core/src/language_models/event.ts:1-30]()\n\n### 使用量事件\n\n```typescript\n/**\n * 提供商报告使用量更新时触发\n * 每个事件携带运行快照（非增量）\n */\nexport interface UsageUpdateEvent {\n event: \"usage\";\n /** 当前使用量快照 */\n usage: Partial;\n}\n```\n\n### 提供商事件\n\n```typescript\n/**\n * 用于原生提供商事件的透传\n */\nexport interface ProviderEvent {\n event: \"provider\";\n /** 提供商标识符 */\n provider: string;\n /** 来自提供商 SDK 的原始事件类型名 */\n name: string;\n /** 来自提供商 SDK 的原始事件载荷 */\n payload: unknown;\n}\n```\n\n### 事件处理流程\n\n```mermaid\ngraph LR\n A[流式调用] --> B[接收 AIMessageChunk]\n B --> C{检查事件类型}\n C -->|content-block-delta| D[更新文本内容]\n C -->|content-block-finish| E[标记块完成]\n C -->|usage| F[更新 token 统计]\n C -->|provider| G[透传原始事件]\n D --> H[累积完整响应]\n E --> H\n F --> H\n G --> H\n```\n\n### 聚合流式块\n\n```typescript\nimport { AIMessageChunk } from '@langchain/core/messages';\nimport { concat } from '@langchain/core/utils';\n\nlet fullForMetadata: AIMessageChunk | undefined;\nfor await (const chunk of await llm.stream(input)) {\n fullForMetadata = fullForMetadata\n ? concat(fullForMetadata, chunk)\n : chunk;\n}\nconsole.log(fullForMetadata?.usage_metadata);\n// 输出: { input_tokens: 25, output_tokens: 20, total_tokens: 45 }\n```\n\n## 包依赖管理最佳实践\n\n当在项目中使用多个 LangChain 包时，建议统一 `@langchain/core` 版本以避免兼容性问题：\n\n```json\n{\n \"name\": \"your-project\",\n \"version\": \"0.0.0\",\n \"dependencies\": {\n \"@langchain/anthropic\": \"^0.3.0\",\n \"@langchain/core\": \"^0.3.0\"\n },\n \"resolutions\": {\n \"@langchain/core\": \"^0.3.0\"\n },\n \"overrides\": {\n \"@langchain/core\": \"^0.3.0\"\n },\n \"pnpm\": {\n \"overrides\": {\n \"@langchain/core\": \"^0.3.0\"\n }\n }\n}\n```\n\n资料来源：[libs/create-langchain-integration/template/README.md](https://github.com/langchain-ai/langchainjs/blob/main/libs/create-langchain-integration/template/README.md)\n\n## 迁移与弃用处理\n\nLangChain.js 在演进过程中会迁移某些功能，开发者应注意弃用警告：\n\n```typescript\nif (\n getEnvironmentVariable(\"LANGCHAIN_SUPPRESS_MIGRATION_WARNINGS\") !== \"true\"\n) {\n console.warn(warningText);\n}\n```\n\n通过设置环境变量 `LANGCHAIN_SUPPRESS_MIGRATION_WARNINGS=true` 可以抑制迁移警告。\n\n资料来源：[libs/langchain-classic/src/util/entrypoint_deprecation.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-classic/src/util/entrypoint_deprecation.ts)\n\n## 常见模式总结\n\n| 模式 | 描述 | 适用场景 |\n|------|------|---------|\n| 链式调用 | 使用 `Runnable` 接口组合多个组件 | 数据处理流水线 |\n| 工具调用 | LLM 调用外部函数 | 需要获取外部数据 |\n| 流式处理 | 实时获取 LLM 输出 | 对话式应用 |\n| 中间件拦截 | 在代理执行中插入逻辑 | 监控、HITL |\n| 状态管理 | 使用 Zod 或 StateSchema | 结构化代理状态 |\n\n这些示例代码和最佳实践为开发者提供了构建生产级 LLM 应用的坚实基础。建议从简单的示例开始，逐步探索更高级的功能。\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：langchain-ai/langchainjs\n\n摘要：发现 10 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：配置坑 - 来源证据：[Feature request] React Native support。\n\n## 1. 配置坑 · 来源证据：[Feature request] React Native support\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[Feature request] React Native support\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_39933028ef894033b30ff784e81f185f | https://github.com/langchain-ai/langchainjs/issues/4239 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 2. 安装坑 · 来源证据：@langchain/core@1.1.46\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：@langchain/core@1.1.46\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_36a7a58d5cd84bda8dde7918402a6f8a | https://github.com/langchain-ai/langchainjs/releases/tag/%40langchain/core%401.1.46 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 3. 配置坑 · 来源证据：Must pass in at least 1 record to upsert.\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Must pass in at least 1 record to upsert.\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_26c3acaad9e14ed3953206f25870c0b0 | https://github.com/langchain-ai/langchainjs/issues/10890 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 4. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:598342280 | https://github.com/langchain-ai/langchainjs | README/documentation is current enough for a first validation pass.\n\n## 5. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:598342280 | https://github.com/langchain-ai/langchainjs | last_activity_observed missing\n\n## 6. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:598342280 | https://github.com/langchain-ai/langchainjs | no_demo; severity=medium\n\n## 7. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:598342280 | https://github.com/langchain-ai/langchainjs | no_demo; severity=medium\n\n## 8. 安全/权限坑 · 来源证据：bug(@langchain/openai): Bare JSON.parse in Responses API converter crashes on structured output with trailing characters\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：bug(@langchain/openai): Bare JSON.parse in Responses API converter crashes on structured output with trailing characters\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_4d2a6bed33284a3cbd2f3319321d9e4c | https://github.com/langchain-ai/langchainjs/issues/10894 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 9. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:598342280 | https://github.com/langchain-ai/langchainjs | issue_or_pr_quality=unknown\n\n## 10. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:598342280 | https://github.com/langchain-ai/langchainjs | release_recency=unknown\n\n\n", "markdown_key": "langchainjs", "pages": "draft", "source_refs": [ { "evidence_id": "github_repo:598342280", "kind": "repo", "supports_claim_ids": [ "claim_identity", "claim_distribution", "claim_capability" ], "url": "https://github.com/langchain-ai/langchainjs" }, { "evidence_id": "art_73d783e5de2540acb8b7d277070227b6", "kind": "docs", "supports_claim_ids": [ "claim_identity", "claim_distribution", "claim_capability" ], "url": "https://github.com/langchain-ai/langchainjs#readme" } ], "summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。", "title": "langchainjs 说明书", "toc": [ "https://github.com/langchain-ai/langchainjs 项目说明书", "目录", "项目概述与生态系统", "核心定位与价值主张", "生态系统架构", "核心包结构", "Provider 包生态", "开发工具与模板", "Doramagic 踩坑日志" ] } }, "quality_gate": { "blocking_gaps": [], "category_confidence": "medium", "compile_status": "ready_for_review", "five_assets_present": true, "install_sandbox_verified": true, "missing_evidence": [], "next_action": "publish to Doramagic.ai project surfaces", "prompt_preview_boundary_ok": true, "publish_status": "publishable", "quick_start_verified": true, "repo_clone_verified": true, "repo_commit": "76df9d0968150e2f8901e5bfea2fce5d1445627c", "repo_inspection_error": null, "repo_inspection_files": [ "pnpm-lock.yaml", "package.json", "README.md", "docs/core_docs/README.md", "examples/package.json", "examples/openai_openapi.yaml", "examples/tsconfig.json", "examples/src/index.ts", "examples/src/README.md", "examples/src/extraction/openai_tool_calling_extraction.ts", "examples/src/multi-agent/handoffs.ts", "examples/src/multi-agent/skills-sql-assistant.ts", "examples/src/multi-agent/subagents-personal-assistant.ts", "examples/src/multi-agent/router-knowledge-base.ts", "examples/src/multi-agent/handoffs-customer-support.ts", "examples/src/cache/cloudflare_kv.ts", "examples/src/llms/googlevertexai.ts", "examples/src/llms/openai.ts", "examples/src/llms/azure_openai-chat.ts", "examples/src/llms/googlevertexai-streaming.ts", "examples/src/llms/azure_openai.ts", "examples/src/createAgent/customSystemPrompts.ts", "examples/src/createAgent/updateThreadLevelInTools.ts", "examples/src/createAgent/accessExternalContext.ts", "examples/src/createAgent/accessLongTermMemory.ts", "examples/src/createAgent/accessExternalContextInTools.ts", "examples/src/createAgent/tools.ts", "examples/src/createAgent/structuredOutput.ts", "examples/src/createAgent/updateModelBeforeCall.ts", "examples/src/createAgent/streaming.ts", "examples/src/createAgent/supervisor.ts", "examples/src/createAgent/updateThreadLevel.ts", "examples/src/createAgent/updateToolsBeforeModelCall.ts", "examples/src/createAgent/accessThreadLevelState.ts", "examples/src/createAgent/updateLongTermMemoryInTools.ts", "examples/src/createAgent/accessThreadLevelStateInTools.ts", "examples/src/createAgent/controlOverMessagePreparation.ts", "examples/src/createAgent/accessLongTermMemoryInTools.ts", "examples/src/provider/anthropic/memory.ts", "examples/src/langchain-classic/chains/api_chain.ts" ], "repo_inspection_verified": true, "review_reasons": [], "tag_count_ok": true, "unsupported_claims": [] }, "schema_version": "0.1", "user_assets": { "ai_context_pack": { "asset_id": "ai_context_pack", "filename": "AI_CONTEXT_PACK.md", "markdown": "# langchainjs - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 langchainjs 编译的 AI Context Pack。请把它当作开工前上下文：帮助用户理解适合谁、能做什么、如何开始、哪些必须安装后验证、风险在哪里。不要声称你已经安装、运行或执行了目标项目。\n\n## Claim 消费规则\n\n- **事实来源**：Repo Evidence + Claim/Evidence Graph；Human Wiki 只提供显著性、术语和叙事结构。\n- **事实最低状态**：`supported`\n- `supported`：可以作为项目事实使用，但回答中必须引用 claim_id 和证据路径。\n- `weak`：只能作为低置信度线索，必须要求用户继续核实。\n- `inferred`：只能用于风险提示或待确认问题，不能包装成项目事实。\n- `unverified`：不得作为事实使用，应明确说证据不足。\n- `contradicted`：必须展示冲突来源，不得替用户强行选择一个版本。\n\n## 它最适合谁\n\n- **想在安装前理解开源项目价值和边界的用户**：当前证据主要来自项目文档。 证据：`README.md` Claim：`clm_0002` supported 0.86\n\n## 它能做什么\n\n- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`AGENTS.md` Claim：`clm_0001` supported 0.86\n\n## 怎么开始\n\n- `npx create-langchain-integration` 证据：`AGENTS.md` Claim：`clm_0003` supported 0.86\n\n## 继续前判断卡\n\n- **当前建议**：先做角色匹配试用\n- **为什么**：这个项目更像角色库，核心风险是选错角色或把角色文案当执行能力；先用 Prompt Preview 试角色匹配，再决定是否沙盒导入。\n\n### 30 秒判断\n\n- **现在怎么做**：先做角色匹配试用\n- **最小安全下一步**：先用 Prompt Preview 试角色匹配；满意后再隔离导入\n- **先别相信**：角色质量和任务匹配不能直接相信。\n- **继续会触碰**：角色选择偏差、命令执行、宿主 AI 配置\n\n### 现在可以相信\n\n- **适合人群线索：想在安装前理解开源项目价值和边界的用户**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0002` supported 0.86\n- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`AGENTS.md` Claim：`clm_0001` supported 0.86\n- **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`AGENTS.md` Claim：`clm_0003` supported 0.86\n\n### 现在还不能相信\n\n- **角色质量和任务匹配不能直接相信。**（unverified）：角色库证明有很多角色，不证明每个角色都适合你的具体任务，也不证明角色能产生高质量结果。\n- **不能把角色文案当成真实执行能力。**（unverified）：安装前只能判断角色描述和任务画像是否匹配，不能证明它能在宿主 AI 里完成任务。\n- **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。\n- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。\n- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。 证据：`AGENTS.md`\n- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。\n- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。\n- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。\n\n### 继续会触碰什么\n\n- **角色选择偏差**：用户对任务应该由哪个专家角色处理的判断。 原因：选错角色会让 AI 从错误专业视角回答，浪费时间或误导决策。\n- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`AGENTS.md`\n- **宿主 AI 配置**：Claude/Codex/Cursor/Gemini/OpenCode 等宿主的 plugin、Skill 或规则加载配置。 原因：宿主配置会改变 AI 后续工作方式，可能和用户已有规则冲突。 证据：`AGENTS.md`\n- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`AGENTS.md`\n- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。\n\n### 最小安全下一步\n\n- **先跑 Prompt Preview**：先用交互式试用验证任务画像和角色匹配，不要先导入整套角色库。（适用：任何项目都适用，尤其是输出质量未知时。）\n- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）\n- **先备份宿主 AI 配置**：Skill、plugin、规则文件可能改变 Claude/Cursor/Codex 的默认行为。（适用：存在插件 manifest、Skill 或宿主规则入口时。）\n- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）\n\n### 退出方式\n\n- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。\n- **准备移除宿主 plugin / Skill / 规则入口**：如果试装后行为异常，可以把宿主 AI 恢复到试装前状态。\n- **保留原始角色选择记录**：如果输出偏题，可以回到任务画像阶段重新选择角色，而不是继续沿着错误角色推进。\n- **记录安装命令和写入路径**：没有明确卸载说明时，至少要知道哪些目录或配置需要手动清理。\n- **如果没有回滚路径，不进入主力环境**：不可回滚是继续前阻断项，不应靠信任或运气继续。\n\n## 哪些只能预览\n\n- 解释项目适合谁和能做什么\n- 基于项目文档演示典型对话流程\n- 帮助用户判断是否值得安装或继续研究\n\n## 哪些必须安装后验证\n\n- 真实安装 Skill、插件或 CLI\n- 执行脚本、修改本地文件或访问外部服务\n- 验证真实输出质量、性能和兼容性\n\n## 边界与风险判断卡\n\n- **把安装前预览误认为真实运行**：用户可能高估项目已经完成的配置、权限和兼容性验证。 处理方式：明确区分 prompt_preview_can_do 与 runtime_required。 Claim：`clm_0004` inferred 0.45\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`AGENTS.md` Claim：`clm_0005` supported 0.86\n- **待确认**：真实安装后是否与用户当前宿主 AI 版本兼容？。原因：兼容性只能通过实际宿主环境验证。\n- **待确认**：项目输出质量是否满足用户具体任务？。原因：安装前预览只能展示流程和边界，不能替代真实评测。\n- **待确认**：安装命令是否需要网络、权限或全局写入？。原因：这影响企业环境和个人环境的安装风险。\n\n## 开工前工作上下文\n\n### 加载顺序\n\n- 先读取 how_to_use.host_ai_instruction，建立安装前判断资产的边界。\n- 读取 claim_graph_summary，确认事实来自 Claim/Evidence Graph，而不是 Human Wiki 叙事。\n- 再读取 intended_users、capabilities 和 quick_start_candidates，判断用户是否匹配。\n- 需要执行具体任务时，优先查 role_skill_index，再查 evidence_index。\n- 遇到真实安装、文件修改、网络访问、性能或兼容性问题时，转入 risk_card 和 boundaries.runtime_required。\n\n### 任务路由\n\n- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`AGENTS.md` Claim：`clm_0001` supported 0.86\n\n### 上下文规模\n\n- 文件总数：2517\n- 重要文件覆盖：40/2517\n- 证据索引条目：80\n- 角色 / Skill 条目：50\n\n### 证据不足时的处理\n\n- **missing_evidence**：说明证据不足，要求用户提供目标文件、README 段落或安装后验证记录；不要补全事实。\n- **out_of_scope_request**：说明该任务超出当前 AI Context Pack 证据范围，并建议用户先查看 Human Manual 或真实安装后验证。\n- **runtime_request**：给出安装前检查清单和命令来源，但不要替用户执行命令或声称已执行。\n- **source_conflict**：同时展示冲突来源，标记为待核实，不要强行选择一个版本。\n\n## Prompt Recipes\n\n### 适配判断\n\n- 目标：判断这个项目是否适合用户当前任务。\n- 预期输出：适配结论、关键理由、证据引用、安装前可预览内容、必须安装后验证内容、下一步建议。\n\n```text\n请基于 langchainjs 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 langchainjs 当作安装前体验资产，而不是已安装工具或真实运行环境。\n\n请严格输出四段：\n1. 先问我 3 个必要问题。\n2. 给出一段“体验剧本”：用 [安装前可预览]、[必须安装后验证]、[证据不足] 三种标签展示它可能如何引导工作流。\n3. 给出安装后验证清单：列出哪些能力只有真实安装、真实宿主加载、真实项目运行后才能确认。\n4. 给出谨慎建议：只能说“值得继续研究/试装”“先补充信息后再判断”或“不建议继续”，不得替项目背书。\n\n硬性边界：\n- 不要声称已经安装、运行、执行测试、修改文件或产生真实结果。\n- 不要写“自动适配”“确保通过”“完美适配”“强烈建议安装”等承诺性表达。\n- 如果描述安装后的工作方式，必须使用“如果安装成功且宿主正确加载 Skill，它可能会……”这种条件句。\n- 体验剧本只能写成“示例台词/假设流程”：使用“可能会询问/可能会建议/可能会展示”，不要写“已写入、已生成、已通过、正在运行、正在生成”。\n- Prompt Preview 不负责给安装命令；如用户准备试装，只能提示先阅读 Quick Start 和 Risk Card，并在隔离环境验证。\n- 所有项目事实必须来自 supported claim、evidence_refs 或 source_paths；inferred/unverified 只能作风险或待确认项。\n\n```\n\n### 角色 / Skill 选择\n\n- 目标：从项目里的角色或 Skill 中挑选最匹配的资产。\n- 预期输出：候选角色或 Skill 列表，每项包含适用场景、证据路径、风险边界和是否需要安装后验证。\n\n```text\n请读取 role_skill_index，根据我的目标任务推荐 3-5 个最相关的角色或 Skill。每个推荐都要说明适用场景、可能输出、风险边界和 evidence_refs。\n```\n\n### 风险预检\n\n- 目标：安装或引入前识别环境、权限、规则冲突和质量风险。\n- 预期输出：环境、权限、依赖、许可、宿主冲突、质量风险和未知项的检查清单。\n\n```text\n请基于 risk_card、boundaries 和 quick_start_candidates，给我一份安装前风险预检清单。不要替我执行命令，只说明我应该检查什么、为什么检查、失败会有什么影响。\n```\n\n### 宿主 AI 开工指令\n\n- 目标：把项目上下文转成一次对话开始前的宿主 AI 指令。\n- 预期输出：一段边界明确、证据引用明确、适合复制给宿主 AI 的开工前指令。\n\n```text\n请基于 langchainjs 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 50 个角色 / Skill / 项目文档条目。\n\n- **Readme**（project_doc）：These docs have moved! See https://docs.langchain.com/oss/javascript/ Repo https://github.com/langchain-ai/docs 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/core_docs/README.md`\n- **Changesets**（project_doc）：Hello and welcome! This folder has been automatically generated by @changesets/cli , a build tool that works with multi-package repos, or single-package repos to help you version and publish your code. You can find the full documentation for it in our repository https://github.com/changesets/changesets 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.changeset/README.md`\n- **Dev container**（project_doc）：This project includes a dev container https://containers.dev/ , which lets you use a container as a full-featured dev environment. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.devcontainer/README.md`\n- **AGENTS.md - AI Agent Guidelines for LangChain.js**（project_doc）：AGENTS.md - AI Agent Guidelines for LangChain.js 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`AGENTS.md`\n- **⚡️ Quick Install**（project_doc）：! npm https://img.shields.io/npm/dm/langchain ! License: MIT https://img.shields.io/badge/License-MIT-yellow.svg https://opensource.org/licenses/MIT ! Twitter https://img.shields.io/twitter/url/https/twitter.com/langchain js.svg?style=social&label=Follow%20%40LangChain https://x.com/langchain js 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`README.md`\n- **Environment Tests**（project_doc）：This directory contains tests that verify LangChain packages work correctly in different JavaScript/TypeScript environments. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`environment_tests/README.md`\n- **langchain-examples**（project_doc）：This folder contains examples of how to use LangChain. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`examples/src/README.md`\n- **@langchain/build**（project_doc）：Pre-configured build system for LangChain packages using tsdown https://tsdown.dev/ . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`internal/build/README.md`\n- **Model Profiles Generator**（project_doc）：A CLI tool for automatically generating TypeScript model profile files from the models.dev https://models.dev API. This tool fetches model capabilities and constraints, applies provider-level and model-specific overrides, and generates type-safe TypeScript files using the TypeScript AST API. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`internal/model-profiles/README.md`\n- **LangChain.js Standard Tests**（project_doc）：This package contains the base standard tests for LangChain.js. It includes unit, and integration test classes. This package is not intended to be used outside of the LangChain.js project, and thus it is not published to npm. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`internal/standard-tests/README.md`\n- **@langchain/**（project_doc）：This package contains the LangChain.js integrations for through their SDK. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`libs/create-langchain-integration/template/README.md`\n- **@langchain/classic**（project_doc）：This package contains functionality from LangChain v0.x that has been moved out of the main langchain package as part of the v1.0 release. It exists to provide backward compatibility for existing applications while the core langchain package focuses on the essential building blocks for modern agent development. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`libs/langchain-classic/README.md`\n- **🦜🍎️ @langchain/core**（project_doc）：! npm https://img.shields.io/npm/dm/@langchain/core ! License: MIT https://img.shields.io/badge/License-MIT-yellow.svg https://opensource.org/licenses/MIT ! Twitter https://img.shields.io/twitter/url/https/twitter.com/langchain js.svg?style=social&label=Follow%20%40LangChain https://x.com/langchain js 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`libs/langchain-core/README.md`\n- **LangChain.js MCP Adapters**（project_doc）：! npm version https://img.shields.io/npm/v/@langchain/mcp-adapters.svg https://www.npmjs.com/package/@langchain/mcp-adapters ! License: MIT https://img.shields.io/badge/License-MIT-yellow.svg https://opensource.org/licenses/MIT 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`libs/langchain-mcp-adapters/README.md`\n- **LangChainJS-MCP-Adapters Examples**（project_doc）：This directory contains examples demonstrating how to use the @langchain/mcp-adapters library with various MCP servers 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`libs/langchain-mcp-adapters/examples/README.md`\n- **🦜✂️ @langchain/textsplitters**（project_doc）：This package contains various implementations of LangChain.js text splitters, most commonly used as part of retrieval-augmented generation RAG pipelines. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`libs/langchain-textsplitters/README.md`\n- **🦜️🔗 LangChain.js**（project_doc）：! npm https://img.shields.io/npm/dm/langchain ! License: MIT https://img.shields.io/badge/License-MIT-yellow.svg https://opensource.org/licenses/MIT ! Twitter https://img.shields.io/twitter/url/https/twitter.com/langchain js.svg?style=social&label=Follow%20%40LangChain https://x.com/langchain js 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`libs/langchain/README.md`\n- **@langchain/anthropic**（project_doc）：This package contains the LangChain.js integrations for Anthropic through their SDK. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`libs/providers/langchain-anthropic/README.md`\n- **@langchain/aws**（project_doc）：This package contains the LangChain.js integrations for AWS through their SDK. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`libs/providers/langchain-aws/README.md`\n- **@langchain/cloudflare**（project_doc）：This package contains the LangChain.js integrations for Cloudflare through their SDK. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`libs/providers/langchain-cloudflare/README.md`\n- **@langchain/cohere**（project_doc）：This package contains the LangChain.js integrations for Cohere through their SDK. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`libs/providers/langchain-cohere/README.md`\n- **@langchain/deepseek**（project_doc）：This package contains the LangChain.js integrations for DeepSeek. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`libs/providers/langchain-deepseek/README.md`\n- **@langchain/exa**（project_doc）：This package contains the LangChain.js integrations for exa through their SDK. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`libs/providers/langchain-exa/README.md`\n- **@langchain/fireworks**（project_doc）：This package contains the LangChain.js integrations for Fireworks AI. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`libs/providers/langchain-fireworks/README.md`\n- **@langchain/google-cloud-sql-pg**（project_doc）：The LangChain package for CloudSQL for Postgres provides a way to connect to Cloud SQL instances from the LangChain ecosystem. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`libs/providers/langchain-google-cloud-sql-pg/README.md`\n- **LangChain google-common**（project_doc）：This package contains common resources to access Google AI/ML models and other Google services in an auth-independent way. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`libs/providers/langchain-google-common/README.md`\n- **LangChain google-gauth**（project_doc）：This package contains resources to access Google AI/ML models and other Google services. Authorization to these services use either an API Key or service account credentials that are either stored on the local file system or are provided through the Google Cloud Platform environment it is running on. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`libs/providers/langchain-google-gauth/README.md`\n- **@langchain/google-genai**（project_doc）：This package contains the LangChain.js integrations for Gemini through their generative-ai SDK. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`libs/providers/langchain-google-genai/README.md`\n- **LangChain google-vertexai-web**（project_doc）：This package contains resources to access Google AI/ML models and other Google services via Vertex AI. Authorization to these services use either an API Key or service account credentials that are included in an environment variable. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`libs/providers/langchain-google-vertexai-web/README.md`\n- **LangChain google-vertexai**（project_doc）：This package contains resources to access Google AI/ML models and other Google services via Vertex AI. Authorization to these services use service account credentials stored on the local file system or provided through the Google Cloud Platform environment it is running on. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`libs/providers/langchain-google-vertexai/README.md`\n- **LangChain google-webauth**（project_doc）：This package contains resources to access Google AI/ML models and other Google services. Authorization to these services use either an API Key or service account credentials that are included in an environment variable. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`libs/providers/langchain-google-webauth/README.md`\n- **@langchain/google**（project_doc）：This package supports access to a variety of Google's models, including the Gemini family of models and their Nano Banana image generation model. You can access these models through either Google's Google AI https://ai.google.dev/ API sometimes also called the Generative AI API or the AI Studio API or through the Google Cloud Platform Vertex AI https://cloud.google.com/vertex-ai service. It does not rely on the \"gen… 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`libs/providers/langchain-google/README.md`\n- **@langchain/groq**（project_doc）：This package contains the LangChain.js integrations for Groq via the groq/sdk package. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`libs/providers/langchain-groq/README.md`\n- **@langchain/ibm**（project_doc）：This package contains the LangChain.js integrations for IBM watsonx.ai https://www.ibm.com/watsonx via the @ibm-cloud/watsonx-ai SDK. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`libs/providers/langchain-ibm/README.md`\n- **@langchain/mistralai**（project_doc）：This package contains the LangChain.js integrations for Mistral through their SDK. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`libs/providers/langchain-mistralai/README.md`\n- **@langchain/mongodb**（project_doc）：This package contains the LangChain.js integrations for MongoDB through their SDK. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`libs/providers/langchain-mongodb/README.md`\n- **@langchain/neo4j**（project_doc）：This package contains the LangChain.js https://github.com/langchain-ai/langchainjs integrations for Neo4j https://neo4j.com/ graph database, including support for Memgraph https://memgraph.com/ which uses the Bolt protocol . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`libs/providers/langchain-neo4j/README.md`\n- **@langchain/ollama**（project_doc）：This package contains the LangChain.js integrations for Ollama via the ollama TypeScript SDK. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`libs/providers/langchain-ollama/README.md`\n- **@langchain/openai**（project_doc）：This package contains the LangChain.js integrations for OpenAI through their SDK. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`libs/providers/langchain-openai/README.md`\n- **@langchain/openrouter**（project_doc）：This package contains the LangChain.js integrations for OpenRouter https://openrouter.ai/ . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`libs/providers/langchain-openrouter/README.md`\n- **@langchain/perplexity**（project_doc）：This package provides a LangChain.js https://github.com/langchain-ai/langchainjs integration for Perplexity AI https://www.perplexity.ai/ , including chat models, the Perplexity Search retriever, and the Perplexity Search tool. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`libs/providers/langchain-perplexity/README.md`\n- **@langchain/pgvector**（project_doc）：This package contains the LangChain.js https://github.com/langchain-ai/langchainjs integration for pgvector https://github.com/pgvector/pgvector , the open-source vector similarity search extension for PostgreSQL. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`libs/providers/langchain-pgvector/README.md`\n- **@langchain/pinecone**（project_doc）：This package contains the LangChain.js integrations for Pinecone through their SDK. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`libs/providers/langchain-pinecone/README.md`\n- **@langchain/qdrant**（project_doc）：This package contains the LangChain.js integration for the Qdrant https://qdrant.tech/ vector database. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`libs/providers/langchain-qdrant/README.md`\n- **@langchain/redis**（project_doc）：This package contains the LangChain.js integrations for Redis through their SDK. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`libs/providers/langchain-redis/README.md`\n- **@langchain/tavily**（project_doc）：! NPM - Version https://img.shields.io/npm/v/@langchain/tavily?style=flat-square&label=%20 https://www.npmjs.com/package/@langchain/tavily 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`libs/providers/langchain-tavily/README.md`\n- **@langchain/together-ai**（project_doc）：This package contains the LangChain.js integrations for Together AI https://www.together.ai/ . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`libs/providers/langchain-together-ai/README.md`\n- **@langchain/weaviate**（project_doc）：This package contains the LangChain.js integrations for Weaviate with the weaviate-client SDK. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`libs/providers/langchain-weaviate/README.md`\n- **@langchain/xai**（project_doc）：This package contains the LangChain.js integrations for xAI. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`libs/providers/langchain-xai/README.md`\n- **Contributing to LangChain**（project_doc）：👋 Welcome! Thank you for your interest in contributing. LangChain has helped form the largest developer community in generative AI, and we're always open to new contributors. Whether you're fixing bugs, adding features, improving documentation, or sharing feedback, your involvement helps make LangChain and LangGraph better for everyone 🦜❤️ 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`CONTRIBUTING.md`\n\n## 证据索引\n\n- 共索引 80 条证据。\n\n- **Readme**（documentation）：These docs have moved! See https://docs.langchain.com/oss/javascript/ Repo https://github.com/langchain-ai/docs 证据：`docs/core_docs/README.md`\n- **Changesets**（documentation）：Hello and welcome! This folder has been automatically generated by @changesets/cli , a build tool that works with multi-package repos, or single-package repos to help you version and publish your code. You can find the full documentation for it in our repository https://github.com/changesets/changesets 证据：`.changeset/README.md`\n- **Dev container**（documentation）：This project includes a dev container https://containers.dev/ , which lets you use a container as a full-featured dev environment. 证据：`.devcontainer/README.md`\n- **AGENTS.md - AI Agent Guidelines for LangChain.js**（documentation）：AGENTS.md - AI Agent Guidelines for LangChain.js 证据：`AGENTS.md`\n- **⚡️ Quick Install**（documentation）：! npm https://img.shields.io/npm/dm/langchain ! License: MIT https://img.shields.io/badge/License-MIT-yellow.svg https://opensource.org/licenses/MIT ! Twitter https://img.shields.io/twitter/url/https/twitter.com/langchain js.svg?style=social&label=Follow%20%40LangChain https://x.com/langchain js 证据：`README.md`\n- **Environment Tests**（documentation）：This directory contains tests that verify LangChain packages work correctly in different JavaScript/TypeScript environments. 证据：`environment_tests/README.md`\n- **langchain-examples**（documentation）：This folder contains examples of how to use LangChain. 证据：`examples/src/README.md`\n- **@langchain/build**（documentation）：Pre-configured build system for LangChain packages using tsdown https://tsdown.dev/ . 证据：`internal/build/README.md`\n- **Model Profiles Generator**（documentation）：A CLI tool for automatically generating TypeScript model profile files from the models.dev https://models.dev API. This tool fetches model capabilities and constraints, applies provider-level and model-specific overrides, and generates type-safe TypeScript files using the TypeScript AST API. 证据：`internal/model-profiles/README.md`\n- **LangChain.js Standard Tests**（documentation）：This package contains the base standard tests for LangChain.js. It includes unit, and integration test classes. This package is not intended to be used outside of the LangChain.js project, and thus it is not published to npm. 证据：`internal/standard-tests/README.md`\n- **@langchain/**（documentation）：This package contains the LangChain.js integrations for through their SDK. 证据：`libs/create-langchain-integration/template/README.md`\n- **@langchain/classic**（documentation）：This package contains functionality from LangChain v0.x that has been moved out of the main langchain package as part of the v1.0 release. It exists to provide backward compatibility for existing applications while the core langchain package focuses on the essential building blocks for modern agent development. 证据：`libs/langchain-classic/README.md`\n- **🦜🍎️ @langchain/core**（documentation）：! npm https://img.shields.io/npm/dm/@langchain/core ! License: MIT https://img.shields.io/badge/License-MIT-yellow.svg https://opensource.org/licenses/MIT ! Twitter https://img.shields.io/twitter/url/https/twitter.com/langchain js.svg?style=social&label=Follow%20%40LangChain https://x.com/langchain js 证据：`libs/langchain-core/README.md`\n- **LangChain.js MCP Adapters**（documentation）：! npm version https://img.shields.io/npm/v/@langchain/mcp-adapters.svg https://www.npmjs.com/package/@langchain/mcp-adapters ! License: MIT https://img.shields.io/badge/License-MIT-yellow.svg https://opensource.org/licenses/MIT 证据：`libs/langchain-mcp-adapters/README.md`\n- **LangChainJS-MCP-Adapters Examples**（documentation）：This directory contains examples demonstrating how to use the @langchain/mcp-adapters library with various MCP servers 证据：`libs/langchain-mcp-adapters/examples/README.md`\n- **🦜✂️ @langchain/textsplitters**（documentation）：This package contains various implementations of LangChain.js text splitters, most commonly used as part of retrieval-augmented generation RAG pipelines. 证据：`libs/langchain-textsplitters/README.md`\n- **🦜️🔗 LangChain.js**（documentation）：! npm https://img.shields.io/npm/dm/langchain ! License: MIT https://img.shields.io/badge/License-MIT-yellow.svg https://opensource.org/licenses/MIT ! Twitter https://img.shields.io/twitter/url/https/twitter.com/langchain js.svg?style=social&label=Follow%20%40LangChain https://x.com/langchain js 证据：`libs/langchain/README.md`\n- **@langchain/anthropic**（documentation）：This package contains the LangChain.js integrations for Anthropic through their SDK. 证据：`libs/providers/langchain-anthropic/README.md`\n- **@langchain/aws**（documentation）：This package contains the LangChain.js integrations for AWS through their SDK. 证据：`libs/providers/langchain-aws/README.md`\n- **@langchain/cloudflare**（documentation）：This package contains the LangChain.js integrations for Cloudflare through their SDK. 证据：`libs/providers/langchain-cloudflare/README.md`\n- **@langchain/cohere**（documentation）：This package contains the LangChain.js integrations for Cohere through their SDK. 证据：`libs/providers/langchain-cohere/README.md`\n- **@langchain/deepseek**（documentation）：This package contains the LangChain.js integrations for DeepSeek. 证据：`libs/providers/langchain-deepseek/README.md`\n- **@langchain/exa**（documentation）：This package contains the LangChain.js integrations for exa through their SDK. 证据：`libs/providers/langchain-exa/README.md`\n- **@langchain/fireworks**（documentation）：This package contains the LangChain.js integrations for Fireworks AI. 证据：`libs/providers/langchain-fireworks/README.md`\n- **@langchain/google-cloud-sql-pg**（documentation）：The LangChain package for CloudSQL for Postgres provides a way to connect to Cloud SQL instances from the LangChain ecosystem. 证据：`libs/providers/langchain-google-cloud-sql-pg/README.md`\n- **LangChain google-common**（documentation）：This package contains common resources to access Google AI/ML models and other Google services in an auth-independent way. 证据：`libs/providers/langchain-google-common/README.md`\n- **LangChain google-gauth**（documentation）：This package contains resources to access Google AI/ML models and other Google services. Authorization to these services use either an API Key or service account credentials that are either stored on the local file system or are provided through the Google Cloud Platform environment it is running on. 证据：`libs/providers/langchain-google-gauth/README.md`\n- **@langchain/google-genai**（documentation）：This package contains the LangChain.js integrations for Gemini through their generative-ai SDK. 证据：`libs/providers/langchain-google-genai/README.md`\n- **LangChain google-vertexai-web**（documentation）：This package contains resources to access Google AI/ML models and other Google services via Vertex AI. Authorization to these services use either an API Key or service account credentials that are included in an environment variable. 证据：`libs/providers/langchain-google-vertexai-web/README.md`\n- **LangChain google-vertexai**（documentation）：This package contains resources to access Google AI/ML models and other Google services via Vertex AI. Authorization to these services use service account credentials stored on the local file system or provided through the Google Cloud Platform environment it is running on. 证据：`libs/providers/langchain-google-vertexai/README.md`\n- **LangChain google-webauth**（documentation）：This package contains resources to access Google AI/ML models and other Google services. Authorization to these services use either an API Key or service account credentials that are included in an environment variable. 证据：`libs/providers/langchain-google-webauth/README.md`\n- **@langchain/google**（documentation）：This package supports access to a variety of Google's models, including the Gemini family of models and their Nano Banana image generation model. You can access these models through either Google's Google AI https://ai.google.dev/ API sometimes also called the Generative AI API or the AI Studio API or through the Google Cloud Platform Vertex AI https://cloud.google.com/vertex-ai service. It does not rely on the \"genai\" library from Google, but rather uses direct REST calls. 证据：`libs/providers/langchain-google/README.md`\n- **@langchain/groq**（documentation）：This package contains the LangChain.js integrations for Groq via the groq/sdk package. 证据：`libs/providers/langchain-groq/README.md`\n- **@langchain/ibm**（documentation）：This package contains the LangChain.js integrations for IBM watsonx.ai https://www.ibm.com/watsonx via the @ibm-cloud/watsonx-ai SDK. 证据：`libs/providers/langchain-ibm/README.md`\n- **@langchain/mistralai**（documentation）：This package contains the LangChain.js integrations for Mistral through their SDK. 证据：`libs/providers/langchain-mistralai/README.md`\n- **@langchain/mongodb**（documentation）：This package contains the LangChain.js integrations for MongoDB through their SDK. 证据：`libs/providers/langchain-mongodb/README.md`\n- **@langchain/neo4j**（documentation）：This package contains the LangChain.js https://github.com/langchain-ai/langchainjs integrations for Neo4j https://neo4j.com/ graph database, including support for Memgraph https://memgraph.com/ which uses the Bolt protocol . 证据：`libs/providers/langchain-neo4j/README.md`\n- **@langchain/ollama**（documentation）：This package contains the LangChain.js integrations for Ollama via the ollama TypeScript SDK. 证据：`libs/providers/langchain-ollama/README.md`\n- **@langchain/openai**（documentation）：This package contains the LangChain.js integrations for OpenAI through their SDK. 证据：`libs/providers/langchain-openai/README.md`\n- **@langchain/openrouter**（documentation）：This package contains the LangChain.js integrations for OpenRouter https://openrouter.ai/ . 证据：`libs/providers/langchain-openrouter/README.md`\n- **@langchain/perplexity**（documentation）：This package provides a LangChain.js https://github.com/langchain-ai/langchainjs integration for Perplexity AI https://www.perplexity.ai/ , including chat models, the Perplexity Search retriever, and the Perplexity Search tool. 证据：`libs/providers/langchain-perplexity/README.md`\n- **@langchain/pgvector**（documentation）：This package contains the LangChain.js https://github.com/langchain-ai/langchainjs integration for pgvector https://github.com/pgvector/pgvector , the open-source vector similarity search extension for PostgreSQL. 证据：`libs/providers/langchain-pgvector/README.md`\n- **@langchain/pinecone**（documentation）：This package contains the LangChain.js integrations for Pinecone through their SDK. 证据：`libs/providers/langchain-pinecone/README.md`\n- **@langchain/qdrant**（documentation）：This package contains the LangChain.js integration for the Qdrant https://qdrant.tech/ vector database. 证据：`libs/providers/langchain-qdrant/README.md`\n- **@langchain/redis**（documentation）：This package contains the LangChain.js integrations for Redis through their SDK. 证据：`libs/providers/langchain-redis/README.md`\n- **@langchain/tavily**（documentation）：! NPM - Version https://img.shields.io/npm/v/@langchain/tavily?style=flat-square&label=%20 https://www.npmjs.com/package/@langchain/tavily 证据：`libs/providers/langchain-tavily/README.md`\n- **@langchain/together-ai**（documentation）：This package contains the LangChain.js integrations for Together AI https://www.together.ai/ . 证据：`libs/providers/langchain-together-ai/README.md`\n- **@langchain/weaviate**（documentation）：This package contains the LangChain.js integrations for Weaviate with the weaviate-client SDK. 证据：`libs/providers/langchain-weaviate/README.md`\n- **@langchain/xai**（documentation）：This package contains the LangChain.js integrations for xAI. 证据：`libs/providers/langchain-xai/README.md`\n- **Package**（package_manifest）：{ \"name\": \"examples\", \"version\": \"0.0.0\", \"private\": true, \"description\": \"Langchain examples\", \"main\": \"./dist/index.js\", \"type\": \"module\", \"files\": \"dist/\" , \"scripts\": { \"build\": \"tsc --declaration --outDir dist/\", \"clean\": \"rm -rf .turbo dist/\", \"start\": \"tsx --experimental-wasm-modules -r dotenv/config src/index.ts\", \"start:dist\": \"pnpm build && node -r dotenv/config dist/index.js\", \"precommit\": \"lint-staged\" }, \"author\": \"LangChain\", \"license\": \"MIT\", \"dependencies\": { \"@aws-sdk/dsql-signer\": \"^3.1022.0\", \"@azure/identity\": \"^4.13.1\", \"@browserbasehq/stagehand\": \"^3.2.0\", \"@clickhouse/client\": \"^1.18.2\", \"@cloudflare/workers-types\": \"^4.20260508.1\", \"@elastic/elasticsearch\": \"^9.3.4\",… 证据：`examples/package.json`\n- **Package**（package_manifest）：{ \"name\": \"langchainjs\", \"author\": \"LangChain\", \"license\": \"MIT\", \"private\": true, \"homepage\": \"https://github.com/langchain-ai/langchainjs/tree/main/\", \"repository\": { \"type\": \"git\", \"url\": \"https://github.com/langchain-ai/langchainjs.git\" }, \"packageManager\": \"pnpm@10.14.0\", \"scripts\": { \"build\": \"turbo build:compile\", \"watch\": \"turbo watch build:compile\", \"clean\": \"turbo clean\", \"dev\": \"pnpm --filter @langchain/build watch\", \"format\": \"oxfmt .\", \"format:check\": \"oxfmt --check .\", \"lint\": \"oxlint .\", \"lint:fix\": \"oxlint . --fix\", \"precommit\": \"turbo precommit\", \"prerelease\": \"BUILD MODE=prerelease pnpm build\", \"release\": \"changeset publish\", \"test\": \"pnpm test:unit && pnpm test:exports:do… 证据：`package.json`\n- **Contributing to LangChain**（documentation）：👋 Welcome! Thank you for your interest in contributing. LangChain has helped form the largest developer community in generative AI, and we're always open to new contributors. Whether you're fixing bugs, adding features, improving documentation, or sharing feedback, your involvement helps make LangChain and LangGraph better for everyone 🦜❤️ 证据：`CONTRIBUTING.md`\n- **Package**（package_manifest）：{ \"name\": \"dependency-range-tests\", \"version\": \"0.0.0\", \"private\": true, \"description\": \"Tests dependency ranges for LangChain.\", \"dependencies\": { \"semver\": \"^7.5.4\" } } 证据：`dependency_range_tests/scripts/langchain/node/package.json`\n- **Package**（package_manifest）：{ \"name\": \"dependency-range-tests\", \"version\": \"0.0.0\", \"private\": true, \"description\": \"Tests dependency ranges for LangChain.\", \"dependencies\": { \"semver\": \"^7.5.4\" }, \"packageManager\": \"pnpm@10.14.0+sha512.ad27a79641b49c3e481a16a805baa71817a04bbe06a38d17e60e2eaee83f6a146c6a688125f5792e48dd5ba30e7da52a5cda4c3992b9ccf333f9ce223af84748\" } 证据：`dependency_range_tests/scripts/with_standard_tests/anthropic/node/package.json`\n- **Package**（package_manifest）：{ \"name\": \"dependency-range-tests\", \"version\": \"0.0.0\", \"private\": true, \"description\": \"Tests dependency ranges for LangChain.\", \"dependencies\": { \"semver\": \"^7.5.4\" }, \"packageManager\": \"pnpm@10.14.0+sha512.ad27a79641b49c3e481a16a805baa71817a04bbe06a38d17e60e2eaee83f6a146c6a688125f5792e48dd5ba30e7da52a5cda4c3992b9ccf333f9ce223af84748\" } 证据：`dependency_range_tests/scripts/with_standard_tests/cohere/node/package.json`\n- **Package**（package_manifest）：{ \"name\": \"dependency-range-tests\", \"version\": \"0.0.0\", \"private\": true, \"description\": \"Tests dependency ranges for LangChain.\", \"dependencies\": { \"semver\": \"^7.5.4\" }, \"packageManager\": \"pnpm@10.14.0\" } 证据：`dependency_range_tests/scripts/with_standard_tests/google-vertexai/node/package.json`\n- **Package**（package_manifest）：{ \"name\": \"dependency-range-tests\", \"version\": \"0.0.0\", \"private\": true, \"description\": \"Tests dependency ranges for LangChain.\", \"dependencies\": {} } 证据：`dependency_range_tests/scripts/with_standard_tests/node/package.json`\n- **Package**（package_manifest）：{ \"name\": \"dependency-range-tests\", \"version\": \"0.0.0\", \"private\": true, \"description\": \"Tests dependency ranges for LangChain.\", \"dependencies\": { \"semver\": \"^7.5.4\" }, \"packageManager\": \"pnpm@10.14.0+sha512.ad27a79641b49c3e481a16a805baa71817a04bbe06a38d17e60e2eaee83f6a146c6a688125f5792e48dd5ba30e7da52a5cda4c3992b9ccf333f9ce223af84748\" } 证据：`dependency_range_tests/scripts/with_standard_tests/openai/node/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@langchain/build\", \"private\": true, \"version\": \"0.1.1\", \"type\": \"module\", \"main\": \"./src/index.ts\", \"types\": \"./src/index.ts\", \"scripts\": { \"build\": \"exit 0\" }, \"dependencies\": { \"@arethetypeswrong/core\": \"^0.18.2\", \"@typescript/native-preview\": \"^7.0.0-dev.20260401.1\", \"publint\": \"^0.3.19\", \"rolldown\": \"^1.0.0-rc.4\", \"tsdown\": \"^0.21.7\", \"type-fest\": \"^5.3.0\", \"typescript\": \"^6.0.3\", \"unplugin-unused\": \"^0.5.6\" }, \"devDependencies\": { \"@langchain/tsconfig\": \"workspace: \", \"@tsconfig/recommended\": \"^1.0.10\" }, \"optionalDependencies\": { \"@esbuild/win32-x64\": \" \", \"@rolldown/binding-darwin-arm64\": \" \", \"@rolldown/binding-darwin-x64\": \" \", \"@rolldown/binding-linux-arm64-gnu\": \" \", \"… 证据：`internal/build/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@langchain/model-profiles\", \"version\": \"0.0.10\", \"private\": true, \"type\": \"module\", \"scripts\": { \"make\": \"tsx src/cli.ts\", \"test\": \"vitest run\", \"test:watch\": \"vitest\" }, \"dependencies\": { \"@iarna/toml\": \"^2.2.5\", \"@langchain/core\": \"workspace:^\", \"commander\": \"^14.0.3\", \"typescript\": \"^6.0.3\", \"zod\": \"^4.3.6\" }, \"devDependencies\": { \"@types/iarna toml\": \"^2.0.5\", \"@types/node\": \"^25.5.0\", \"tsx\": \"^4.21.0\", \"vitest\": \"^4.1.5\" } } 证据：`internal/model-profiles/package.json`\n- 其余 20 条证据见 `AI_CONTEXT_PACK.json` 或 `EVIDENCE_INDEX.json`。\n\n## 宿主 AI 必须遵守的规则\n\n- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`docs/core_docs/README.md`, `.changeset/README.md`, `.devcontainer/README.md`\n- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`docs/core_docs/README.md`, `.changeset/README.md`, `.devcontainer/README.md`\n\n## 用户开工前应该回答的问题\n\n- 你准备在哪个宿主 AI 或本地环境中使用它？\n- 你只是想先体验工作流，还是准备真实安装？\n- 你最在意的是安装成本、输出质量、还是和现有规则的冲突？\n\n## 验收标准\n\n- 所有能力声明都能回指到 evidence_refs 中的文件路径。\n- AI_CONTEXT_PACK.md 没有把预览包装成真实运行。\n- 用户能在 3 分钟内看懂适合谁、能做什么、如何开始和风险边界。\n\n---\n\n## Doramagic Context Augmentation\n\n下面内容用于强化 Repomix/AI Context Pack 主体。Human Manual 只提供阅读骨架；踩坑日志会被转成宿主 AI 必须遵守的工作约束。\n\n## Human Manual 骨架\n\n使用规则：这里只是项目阅读路线和显著性信号，不是事实权威。具体事实仍必须回到 repo evidence / Claim Graph。\n\n宿主 AI 硬性规则：\n- 不得把页标题、章节顺序、摘要或 importance 当作项目事实证据。\n- 解释 Human Manual 骨架时，必须明确说它只是阅读路线/显著性信号。\n- 能力、安装、兼容性、运行状态和风险判断必须引用 repo evidence、source path 或 Claim Graph。\n\n- **项目概述与生态系统**：importance `high`\n - source_paths: README.md, libs/langchain-core/README.md, libs/langchain/README.md, libs/langchain-classic/README.md\n- **系统架构与核心抽象**：importance `high`\n - source_paths: libs/langchain-core/src/runnables/base.ts, libs/langchain-core/src/callbacks/base.ts, libs/langchain-core/src/memory.ts, libs/langchain-core/src/tools/index.ts, libs/langchain-core/src/language_models/chat_models.ts\n- **Agent 与 Chains 实现**：importance `high`\n - source_paths: libs/langchain-classic/src/agents/react/index.ts, libs/langchain-classic/src/agents/openai_functions/index.ts, libs/langchain-classic/src/agents/structured_chat/index.ts, libs/langchain-classic/src/chains/llm_chain.ts, libs/langchain-classic/src/chains/sql_db/sql_db_chain.ts\n- **向量存储与检索系统**：importance `high`\n - source_paths: libs/langchain-core/src/vectorstores.ts, libs/providers/langchain-pinecone/src/vectorstores.ts, libs/providers/langchain-qdrant/src/vectorstores.ts, libs/providers/langchain-mongodb/src/vectorstores.ts, libs/providers/langchain-pgvector/src/vectorstores.ts\n- **主要模型提供商集成**：importance `high`\n - source_paths: libs/providers/langchain-openai/src/chat_models/base.ts, libs/providers/langchain-anthropic/src/chat_models.ts, libs/providers/langchain-google-vertexai/src/chat_models.ts, libs/providers/langchain-google-genai/src/chat_models.ts, libs/providers/langchain-mistralai/src/chat_models.ts\n- **扩展提供商与工具集成**：importance `medium`\n - source_paths: libs/providers/langchain-cohere/src/chat_models.ts, libs/providers/langchain-ollama/src/chat_models.ts, libs/providers/langchain-aws/src/chat_models.ts, libs/providers/langchain-aws/src/retrievers/bedrock.ts, libs/providers/langchain-groq/src/chat_models.ts\n- **多环境部署支持**：importance `high`\n - source_paths: environment_tests/README.md, environment_tests/docker-compose.yml, environment_tests/test-exports-bun/src/entrypoints.js, environment_tests/test-exports-cf/src/entrypoints.js, environment_tests/test-exports-vercel/src/entrypoints.js\n- **依赖管理与测试策略**：importance `medium`\n - source_paths: dependency_range_tests/docker-compose.yml, dependency_range_tests/scripts/langchain/node/update_resolutions_latest.js, internal/standard-tests/src/index.ts, pnpm-workspace.yaml, package.json\n\n## Repo Inspection Evidence / 源码检查证据\n\n- repo_clone_verified: true\n- repo_inspection_verified: true\n- repo_commit: `76df9d0968150e2f8901e5bfea2fce5d1445627c`\n- inspected_files: `pnpm-lock.yaml`, `package.json`, `README.md`, `docs/core_docs/README.md`, `examples/package.json`, `examples/openai_openapi.yaml`, `examples/tsconfig.json`, `examples/src/index.ts`, `examples/src/README.md`, `examples/src/extraction/openai_tool_calling_extraction.ts`, `examples/src/multi-agent/handoffs.ts`, `examples/src/multi-agent/skills-sql-assistant.ts`, `examples/src/multi-agent/subagents-personal-assistant.ts`, `examples/src/multi-agent/router-knowledge-base.ts`, `examples/src/multi-agent/handoffs-customer-support.ts`, `examples/src/cache/cloudflare_kv.ts`, `examples/src/llms/googlevertexai.ts`, `examples/src/llms/openai.ts`, `examples/src/llms/azure_openai-chat.ts`, `examples/src/llms/googlevertexai-streaming.ts`\n\n宿主 AI 硬性规则：\n- 没有 repo_clone_verified=true 时，不得声称已经读过源码。\n- 没有 repo_inspection_verified=true 时，不得把 README/docs/package 文件判断写成事实。\n- 没有 quick_start_verified=true 时，不得声称 Quick Start 已跑通。\n\n## Doramagic Pitfall Constraints / 踩坑约束\n\n这些规则来自 Doramagic 发现、验证或编译过程中的项目专属坑点。宿主 AI 必须把它们当作工作约束，而不是普通说明文字。\n\n### Constraint 1: 来源证据：[Feature request] React Native support\n\n- Trigger: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[Feature request] React Native support\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_39933028ef894033b30ff784e81f185f | https://github.com/langchain-ai/langchainjs/issues/4239 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 2: 来源证据：@langchain/core@1.1.46\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：@langchain/core@1.1.46\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_36a7a58d5cd84bda8dde7918402a6f8a | https://github.com/langchain-ai/langchainjs/releases/tag/%40langchain/core%401.1.46 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 3: 来源证据：Must pass in at least 1 record to upsert.\n\n- Trigger: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Must pass in at least 1 record to upsert.\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_26c3acaad9e14ed3953206f25870c0b0 | https://github.com/langchain-ai/langchainjs/issues/10890 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 4: 能力判断依赖假设\n\n- Trigger: README/documentation is current enough for a first validation pass.\n- Host AI rule: 将假设转成下游验证清单。\n- Why it matters: 假设不成立时，用户拿不到承诺的能力。\n- Evidence: capability.assumptions | github_repo:598342280 | https://github.com/langchain-ai/langchainjs | README/documentation is current enough for a first validation pass.\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 5: 维护活跃度未知\n\n- Trigger: 未记录 last_activity_observed。\n- Host AI rule: 补 GitHub 最近 commit、release、issue/PR 响应信号。\n- Why it matters: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- Evidence: evidence.maintainer_signals | github_repo:598342280 | https://github.com/langchain-ai/langchainjs | last_activity_observed missing\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 6: 下游验证发现风险项\n\n- Trigger: no_demo\n- Host AI rule: 进入安全/权限治理复核队列。\n- Why it matters: 下游已经要求复核，不能在页面中弱化。\n- Evidence: downstream_validation.risk_items | github_repo:598342280 | https://github.com/langchain-ai/langchainjs | no_demo; severity=medium\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 7: 存在评分风险\n\n- Trigger: no_demo\n- Host AI rule: 把风险写入边界卡，并确认是否需要人工复核。\n- Why it matters: 风险会影响是否适合普通用户安装。\n- Evidence: risks.scoring_risks | github_repo:598342280 | https://github.com/langchain-ai/langchainjs | no_demo; severity=medium\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 8: 来源证据：bug(@langchain/openai): Bare JSON.parse in Responses API converter crashes on structured output with trailing characters\n\n- Trigger: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：bug(@langchain/openai): Bare JSON.parse in Responses API converter crashes on structured output with trailing characters\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能阻塞安装或首次运行。\n- Evidence: community_evidence:github | cevd_4d2a6bed33284a3cbd2f3319321d9e4c | https://github.com/langchain-ai/langchainjs/issues/10894 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 9: issue/PR 响应质量未知\n\n- Trigger: issue_or_pr_quality=unknown。\n- Host AI rule: 抽样最近 issue/PR，判断是否长期无人处理。\n- Why it matters: 用户无法判断遇到问题后是否有人维护。\n- Evidence: evidence.maintainer_signals | github_repo:598342280 | https://github.com/langchain-ai/langchainjs | issue_or_pr_quality=unknown\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 10: 发布节奏不明确\n\n- Trigger: release_recency=unknown。\n- Host AI rule: 确认最近 release/tag 和 README 安装命令是否一致。\n- Why it matters: 安装命令和文档可能落后于代码，用户踩坑概率升高。\n- Evidence: evidence.maintainer_signals | github_repo:598342280 | https://github.com/langchain-ai/langchainjs | release_recency=unknown\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n", "summary": "给宿主 AI 的上下文和工作边界。", "title": "AI Context Pack / 带给我的 AI" }, "boundary_risk_card": { "asset_id": "boundary_risk_card", "filename": "BOUNDARY_RISK_CARD.md", "markdown": "# Boundary & Risk Card / 安装前决策卡\n\n项目：langchain-ai/langchainjs\n\n## Doramagic 试用结论\n\n当前结论：可以进入发布前推荐检查；首次使用仍应从最小权限、临时目录和可回滚配置开始。\n\n## 用户现在可以做\n\n- 可以先阅读 Human Manual，理解项目目的和主要工作流。\n- 可以复制 Prompt Preview 做安装前体验；这只验证交互感，不代表真实运行。\n- 可以把官方 Quick Start 命令放到隔离环境中验证，不要直接进主力环境。\n\n## 现在不要做\n\n- 不要把 Prompt Preview 当成项目实际运行结果。\n- 不要把 metadata-only validation 当成沙箱安装验证。\n- 不要把未验证能力写成“已支持、已跑通、可放心安装”。\n- 不要在首次试用时交出生产数据、私人文件、真实密钥或主力配置目录。\n\n## 安装前检查\n\n- 宿主 AI 是否匹配：local_cli\n- 官方安装入口状态：已发现官方入口\n- 是否在临时目录、临时宿主或容器中验证：必须是\n- 是否能回滚配置改动：必须能\n- 是否需要 API Key、网络访问、读写文件或修改宿主配置：未确认前按高风险处理\n- 是否记录了安装命令、实际输出和失败日志：必须记录\n\n## 当前阻塞项\n\n- 无阻塞项。\n\n## 项目专属踩坑\n\n- 来源证据：[Feature request] React Native support（high）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：@langchain/core@1.1.46（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 来源证据：Must pass in at least 1 record to upsert.（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 能力判断依赖假设（medium）：假设不成立时，用户拿不到承诺的能力。 建议检查：将假设转成下游验证清单。\n- 维护活跃度未知（medium）：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n\n## 风险与权限提示\n\n- no_demo: medium\n\n## 证据缺口\n\n- 暂未发现结构化证据缺口。\n", "summary": "安装、权限、验证和推荐前风险。", "title": "Boundary & Risk Card / 边界与风险卡" }, "human_manual": { "asset_id": "human_manual", "filename": "HUMAN_MANUAL.md", "markdown": "# https://github.com/langchain-ai/langchainjs 项目说明书\n\n生成时间：2026-05-16 04:29:18 UTC\n\n## 目录\n\n- [项目概述与生态系统](#page-1)\n- [系统架构与核心抽象](#page-2)\n- [Agent 与 Chains 实现](#page-3)\n- [向量存储与检索系统](#page-4)\n- [主要模型提供商集成](#page-5)\n- [扩展提供商与工具集成](#page-6)\n- [多环境部署支持](#page-7)\n- [依赖管理与测试策略](#page-8)\n- [扩展开发指南](#page-9)\n- [示例代码与最佳实践](#page-10)\n\n\n\n## 项目概述与生态系统\n\n### 相关页面\n\n相关主题：[系统架构与核心抽象](#page-2), [主要模型提供商集成](#page-5)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/langchain-ai/langchainjs/blob/main/README.md)\n- [libs/langchain-core/README.md](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-core/README.md)\n- [libs/langchain/README.md](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain/README.md)\n- [libs/langchain-classic/README.md](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-classic/README.md)\n- [libs/langchain-textsplitters/README.md](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-textsplitters/README.md)\n- [libs/create-langchain-integration/template/README.md](https://github.com/langchain-ai/langchainjs/blob/main/libs/create-langchain-integration/template/README.md)\n
\n\n# 项目概述与生态系统\n\nLangChain.js 是一个用于构建 LLM 驱动应用的框架，旨在通过可组合性简化 AI 应用开发过程。它帮助开发者将可互操作的组件和第三方集成链在一起，同时为底层技术演进提供未来保障。\n\n## 核心定位与价值主张\n\nLangChain.js 的核心价值在于提供一个灵活的框架，使开发者能够：\n\n- **链式组合**：将多个组件组合成复杂的工作流\n- **第三方集成**：轻松接入各种 LLM 提供商和工具\n- **模块化设计**：各组件独立可替换，便于维护和升级\n- **开发效率**：提供开箱即用的抽象，加速应用开发\n\n## 生态系统架构\n\nLangChain.js 采用多包架构，将不同功能模块分离到独立的包中，以提高可维护性和灵活度。\n\n```mermaid\ngraph TD\n A[用户应用] --> B[langchain 主包]\n A --> C[@langchain/classic 经典包]\n B --> D[@langchain/core 核心包]\n C --> D\n B --> E[@langchain/textsplitters 文本分割]\n D --> F[Provider 包]\n F --> G[langchain-openai]\n F --> H[langchain-anthropic]\n F --> I[langchain-google-common]\n```\n\n## 核心包结构\n\n### @langchain/core 核心包\n\n`@langchain/core` 是整个生态系统的基础库，定义了 LangChain 的核心抽象和接口。它包含：\n\n- **消息系统**：定义各种消息类型和消息处理逻辑\n- **语言模型接口**：统一的 LLM 调用抽象\n- **工具系统**：定义工具的创建和调用方式\n- **输出解析器**：将 LLM 输出解析为结构化数据\n- **事件系统**：支持流式事件和状态更新\n\n资料来源：[libs/langchain-core/README.md]()\n\n### langchain 主包\n\n`langchain` 是面向现代 Agent 开发的主包，提供了构建 AI Agent 的高级 API。\n\n#### 主要特性\n\n| 特性 | 描述 |\n|------|------|\n| createAgent | 创建 Agent 的主要入口 |\n| 中间件支持 | 支持 HITL 等中间件功能 |\n| 工具集成 | 内置工具调用和工具管理 |\n\n#### Agent 架构\n\n```mermaid\ngraph LR\n A[用户输入] --> B[Agent 核心]\n B --> C[工具调用]\n C --> D[外部服务]\n D --> B\n B --> E[响应输出]\n```\n\n`langchain` 包支持通过中间件扩展功能，例如人机交互中间件（Human-in-the-Loop），允许在 Agent 执行过程中进行干预和控制。\n\n资料来源：[libs/langchain/README.md](), [libs/langchain/src/agents/middleware/hitl.ts:1-100]()\n\n### @langchain/classic 经典包\n\n`@langchain/classic` 是为了向后兼容而保留的包，包含从 LangChain v0.x 移出的功能。\n\n#### 何时使用\n\n建议使用 `@langchain/classic` 的场景：\n\n| 场景 | 说明 |\n|------|------|\n| 遗留链 | 使用 `LLMChain`、`ConversationalRetrievalQAChain` 等 |\n| 索引 API | 使用文档索引和向量存储功能 |\n| 社区集成 | 依赖之前从 `langchain` 重新导出的社区功能 |\n| 应用迁移 | 维护现有应用，尚未准备好迁移到新 API |\n\n#### 何时不使用\n\n**对于新项目，应使用 langchain v1.0**，新 API 提供：\n\n- 更清晰的 `createAgent` 构建方式\n- 更好的性能优化\n- 更聚焦的 API 表面\n- 活跃的开发支持\n\n#### 迁移路径\n\n```typescript\n// 旧导入（已弃用）\nimport { LLMChain } from \"langchain\";\n\n// 新导入\nimport { LLMChain } from \"@langchain/classic\";\n```\n\n资料来源：[libs/langchain-classic/README.md](), [libs/langchain-classic/src/util/entrypoint_deprecation.ts:1-50]()\n\n### @langchain/textsplitters 文本分割包\n\n`@langchain/textsplitters` 提供各种文本分割器实现，是 RAG（检索增强生成）管道的常用组件。\n\n#### 支持的分割模式\n\n| 语言 | 说明 |\n|------|------|\n| html | HTML 特定的分块策略 |\n| javascript | JavaScript 代码分割 |\n| typescript | TypeScript 代码分割 |\n| markdown | Markdown 文档分割 |\n| python | Python 代码分割 |\n| json | JSON 数据分割 |\n\n#### 基本使用\n\n```typescript\nimport { RecursiveCharacterTextSplitter } from \"@langchain/textsplitters\";\n\nconst splitter = RecursiveCharacterTextSplitter.fromLanguage(\"html\", {\n chunkSize: 175,\n chunkOverlap: 20,\n});\n\nconst output = await splitter.createDocuments([htmlText]);\n```\n\n资料来源：[libs/langchain-textsplitters/README.md](), [examples/src/langchain-classic/indexes/html_text_splitter.ts:1-50]()\n\n## Provider 包生态\n\nProvider 包提供了与各个 LLM 服务商的集成。\n\n### 主要 Provider\n\n| Provider | 包名 | 功能 |\n|----------|------|------|\n| OpenAI | langchain-openai | GPT 系列模型集成 |\n| Anthropic | langchain-anthropic | Claude 模型集成 |\n| Google | langchain-google-common | Google AI 集成 |\n\n### Provider 架构\n\n```mermaid\ngraph TD\n A[统一接口] --> B[langchain-core]\n B --> C[OpenAI 适配器]\n B --> D[Anthropic 适配器]\n B --> E[Google 适配器]\n C --> F[OpenAI API]\n D --> G[Anthropic API]\n E --> H[Google API]\n```\n\n每个 Provider 包都实现了统一的接口规范，确保应用可以在不同 LLM 之间切换而不需要大量代码改动。\n\n资料来源：[libs/providers/langchain-openai/src/chat_models/index.ts](), [libs/providers/langchain-anthropic/src/chat_models.ts](), [libs/providers/langchain-google-common/src/utils/anthropic.ts]()\n\n### 工具调用支持\n\nProvider 包普遍支持：\n\n- **函数调用**：通过 `withStructuredOutput()` 实现结构化输出\n- **工具使用**：内置工具调用和工具管理\n- **流式处理**：支持流式响应和增量输出\n\n```typescript\nimport { tool } from \"@langchain/core/tools\";\nimport { z } from \"zod\";\n\nconst getWeather = tool(\n async (input) => `Weather in ${input.location}`,\n {\n name: \"get_weather\",\n description: \"Get weather for a location\",\n schema: z.object({ location: z.string() }),\n }\n);\n```\n\n## 开发工具与模板\n\n### 创建新集成\n\n`create-langchain-integration` 提供了创建新 Provider 包的标准模板：\n\n```bash\nnpm install @langchain/\n```\n\n新包需要配置与 `@langchain/core` 的版本对齐：\n\n```json\n{\n \"dependencies\": {\n \"@langchain/\": \"^0.0.0\",\n \"@langchain/core\": \"^0.3.0\"\n },\n \"resolutions\": {\n \"@langchain/core\": \"^0.3.0\"\n }\n}\n```\n\n资料来源：[libs/create-langchain-integration/template/README.md]()\n\n## 核心抽象与接口\n\n### 消息系统\n\nLangChain.js 定义了完整的消息类型体系：\n\n| 类型 | 说明 |\n|------|------|\n| HumanMessage | 用户消息 |\n| AIMessage | AI 响应消息 |\n| SystemMessage | 系统级指令 |\n| ToolMessage | 工具执行结果 |\n\n```typescript\nimport { AIMessageChunk } from '@langchain/core/messages';\nimport { concat } from '@langchain/core/utils';\n```\n\n资料来源：[libs/langchain-core/src/messages/block_translators/openai.ts](), [libs/langchain-core/src/testing/matchers.ts:1-100]()\n\n### 事件系统\n\n核心库提供了完整的事件系统，支持流式处理和状态追踪：\n\n| 事件类型 | 说明 |\n|----------|------|\n| content-block-delta | 内容块增量更新 |\n| content-block-finish | 内容块完成 |\n| usage | 使用量更新 |\n| provider | 原始 Provider 事件 |\n\n```typescript\ninterface ContentBlockDeltaEvent {\n event: \"content-block-delta\";\n index: number;\n delta: ContentBlockDelta;\n}\n```\n\n资料来源：[libs/langchain-core/src/language_models/event.ts]()\n\n### 索引系统\n\nLangChain.js 提供了文档索引的基础设施，用于 RAG 场景：\n\n```mermaid\ngraph LR\n A[文档] --> B[DocumentLoader]\n B --> C[TextSplitter]\n C --> D[Document 数组]\n D --> E[RecordManager]\n D --> F[VectorStore]\n```\n\n索引功能使用 RecordManager 追踪文档状态，支持增量更新和删除管理。\n\n资料来源：[libs/langchain-core/src/indexing/base.ts]()\n\n## 版本演进与兼容性\n\n### v1.0 架构变化\n\nLangChain v1.0 进行了重要的架构调整：\n\n1. **核心功能下沉**：`@langchain/core` 成为基础抽象层\n2. **功能分离**：`@langchain/classic` 承接遗留功能\n3. **现代 API**：`langchain` 主包专注于 Agent 构建\n4. **Provider 解耦**：各 Provider 独立维护\n\n### 弃用警告\n\n导入路径迁移会产生弃用警告：\n\n```typescript\n// 旧路径\nimport { SomeClass } from \"langchain\";\n\n// 新路径\nimport { SomeClass } from \"@langchain/classic\";\n```\n\n可通过环境变量抑制警告：\n\n```bash\nLANGCHAIN_SUPPRESS_MIGRATION_WARNINGS=true\n```\n\n资料来源：[libs/langchain-classic/src/util/entrypoint_deprecation.ts]()\n\n## 安装与依赖管理\n\n### 推荐的依赖配置\n\n为确保各包之间的 `@langchain/core` 版本一致，建议在项目中添加版本锁定：\n\n```json\n{\n \"resolutions\": {\n \"@langchain/core\": \"^0.3.0\"\n },\n \"overrides\": {\n \"@langchain/core\": \"^0.3.0\"\n },\n \"pnpm\": {\n \"overrides\": {\n \"@langchain/core\": \"^0.3.0\"\n }\n }\n}\n```\n\n### 开发依赖\n\n克隆仓库后的标准开发流程：\n\n```bash\npnpm install\npnpm build\npnpm test\npnpm lint && pnpm format\n```\n\n资料来源：[libs/langchain-textsplitters/README.md](), [libs/create-langchain-integration/template/README.md]()\n\n## 总结\n\nLangChain.js 生态系统通过模块化设计提供了灵活的 LLM 应用构建能力：\n\n- **核心层**：`@langchain/core` 提供统一抽象\n- **主包**：`langchain` 专注现代 Agent 开发\n- **兼容层**：`@langchain/classic` 支持平滑迁移\n- **集成层**：多种 Provider 包连接各 LLM 服务商\n- **工具层**：文本分割等实用工具支持 RAG 场景\n\n这种架构既保证了新项目的开发效率，也照顾了现有代码的向后兼容性，使 LangChain.js 成为构建 LLM 应用的可靠选择。\n\n---\n\n\n\n## 系统架构与核心抽象\n\n### 相关页面\n\n相关主题：[项目概述与生态系统](#page-1), [Agent 与 Chains 实现](#page-3)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [libs/langchain-core/src/runnables/base.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-core/src/runnables/base.ts)\n- [libs/langchain-core/src/callbacks/base.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-core/src/callbacks/base.ts)\n- [libs/langchain-core/src/memory.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-core/src/memory.ts)\n- [libs/langchain-core/src/tools/index.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-core/src/tools/index.ts)\n- [libs/langchain-core/src/language_models/chat_models.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-core/src/language_models/chat_models.ts)\n- [libs/langchain-core/src/vectorstores.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-core/src/vectorstores.ts)\n
\n\n# 系统架构与核心抽象\n\n## 概述\n\nLangChain.js 的系统架构采用模块化设计，核心抽象层位于 `@langchain/core` 包中，为上层应用提供统一的接口和组件。架构设计遵循以下原则：可组合性、可扩展性和类型安全。整个系统以 **Runnable** 抽象为核心，构建了一套完整的大语言模型应用开发框架。\n\nLangChain.js 的核心抽象主要包括：Runnable 执行单元、Callbacks 事件系统、Memory 记忆管理、Tools 工具系统、Chat Models 聊天模型接口，以及 Vector Stores 向量存储接口。这些抽象共同构成了构建复杂 LLM 应用的基石。\n\n## 核心架构图\n\n```mermaid\ngraph TB\n subgraph \"核心抽象层 @langchain/core\"\n Runnable[Runnable 执行单元]\n Callbacks[Callbacks 事件系统]\n Memory[Memory 记忆管理]\n Tools[Tools 工具系统]\n ChatModels[Chat Models 接口]\n VectorStores[Vector Stores 接口]\n end\n \n subgraph \"应用层\"\n Agents[Agent 代理]\n Chains[Chain 链]\n VectorRetrieval[向量检索]\n end\n \n subgraph \"集成层\"\n Providers[第三方集成]\n end\n \n Runnable --> Callbacks\n Runnable --> Memory\n Runnable --> Tools\n Runnable --> ChatModels\n Runnable --> VectorStores\n \n Agents --> Runnable\n Chains --> Runnable\n VectorRetrieval --> VectorStores\n \n Providers --> ChatModels\n Providers --> Tools\n Providers --> VectorStores\n```\n\n## Runnable 执行单元\n\n### 设计理念\n\n**Runnable** 是 LangChain.js 最核心的抽象，它代表了任何可以被执行的组件。所有的 Chain、Agent、Tool、Memory 等都实现或扩展了 Runnable 接口。这种设计使得系统中的任意组件都可以被统一地组合、管道化和执行。\n\nRunnable 接口定义了一套标准的执行方法，包括同步调用、批量处理、流式输出等。这确保了无论组件的具体实现如何，调用者都可以用统一的方式与它们交互。\n\n### 核心接口方法\n\n| 方法名 | 说明 | 返回类型 |\n|--------|------|----------|\n| `invoke(input)` | 同步执行单个输入 | `Output` |\n| `batch(inputs)` | 批量处理多个输入 | `Output[]` |\n| `stream(input)` | 流式输出 | `AsyncGenerator` |\n| `pipe(destination)` | 管道连接到另一个 Runnable | `Runnable` |\n| `bind(config)` | 绑定运行时配置 | `Runnable` |\n\n### 可组合性\n\n```mermaid\ngraph LR\n A[输入] --> B[Prompt]\n B --> C[LLM]\n C --> D[Output Parser]\n D --> E[最终结果]\n \n style B fill:#e1f5fe\n style C fill:#fff3e0\n style D fill:#e8f5e8\n```\n\nRunnable 支持两种组合方式：顺序组合和并行组合。顺序组合通过 `pipe()` 方法实现，将前一个 Runnable 的输出作为下一个 Runnable 的输入。并行组合则可以将多个 Runnable 同时应用于同一输入，然后合并结果。\n\n## Callbacks 事件系统\n\n### 架构设计\n\nCallbacks 系统提供了一套完整的事件通知机制，允许在 Runnable 执行过程中的各个阶段插入自定义逻辑。这种设计实现了关注点分离：核心逻辑与监控、调试、日志记录等辅助功能解耦。\n\n事件系统采用发布-订阅模式，定义了清晰的事件生命周期钩子。开发者可以通过实现 `CallbackHandler` 接口来订阅感兴趣的事件，并在事件触发时执行相应操作。\n\n### 主要事件类型\n\n| 事件名称 | 触发时机 | 典型用途 |\n|----------|----------|----------|\n| `handleStart` | Runnable 开始执行 | 记录开始时间 |\n| `handleEnd` | Runnable 完成执行 | 记录结束时间、收集结果 |\n| `handleError` | 执行过程中发生错误 | 错误日志、告警通知 |\n| `handleText` | 输出文本片段 | 实时显示、流式输出 |\n| `handleChainStart` | Chain 开始执行 | 追踪调用链 |\n| `handleChainEnd` | Chain 完成执行 | 性能监控 |\n\n### 使用场景\n\nCallbacks 系统常用于以下场景：\n\n1. **性能监控**：测量各个 Runnable 的执行时间\n2. **日志记录**：记录完整的调用链和中间结果\n3. **流式输出**：实时处理模型生成的内容片段\n4. **调试开发**：在执行过程中输出中间状态\n5. **成本追踪**：统计 token 使用量和 API 调用次数\n\n## Memory 记忆管理\n\n### 抽象接口\n\nMemory 接口定义了与对话历史交互的标准方式。它允许 Chain 和 Agent 在多次调用之间保持状态，实现真正的多轮对话能力。Memory 的设计独立于具体的存储后端，支持内存、数据库、文件系统等多种实现。\n\n```mermaid\nsequenceDiagram\n participant User as 用户\n participant Chain as Chain\n participant Memory as Memory\n \n User->>Chain: 第一轮输入\n Chain->>Memory: 读取历史\n Memory-->>Chain: 历史消息\n Chain->>LLM: 组合输入\n LLM-->>Chain: 响应\n Chain->>Memory: 保存对话\n Chain-->>User: 返回结果\n \n User->>Chain: 第二轮输入\n Chain->>Memory: 读取历史\n Memory-->>Chain: 历史消息\n Chain->>LLM: 组合输入\n LLM-->>Chain: 响应\n Chain->>Memory: 保存对话\n Chain-->>User: 返回结果\n```\n\n### 核心方法\n\n| 方法名 | 说明 |\n|--------|------|\n| `loadMemoryVariables()` | 加载当前记忆变量 |\n| `saveContext(inputs, outputs)` | 保存输入输出对到记忆 |\n| `clear()` | 清除所有记忆内容 |\n\nMemory 系统支持多种实现方式，包括基础缓冲记忆、会话窗口记忆、摘要记忆等。开发者可以根据应用需求选择合适的记忆策略，或实现自定义的 Memory 类。\n\n## Tools 工具系统\n\n### 工具定义接口\n\nTools 系统允许 LLM 调用外部函数和 API，扩展了模型的能力边界。每个 Tool 都是一个独立的 Runnable，具有明确定义的输入模式（通过 Zod schema 定义）和返回值格式。\n\n```mermaid\ngraph TD\n LLM[LLM] -->|决定调用| ToolCall[Tool Call]\n ToolCall --> Tool[Tool 执行]\n Tool --> Result[结果]\n Result --> LLM\n \n subgraph \"Tool 定义\"\n Name[名称]\n Desc[描述]\n Schema[输入模式]\n Func[执行函数]\n end\n \n Tool --> Name\n Tool --> Desc\n Tool --> Schema\n Tool --> Func\n```\n\n### 工具属性\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| name | string | 工具的唯一标识名 |\n| description | string | 工具功能描述，用于 LLM 理解何时调用 |\n| argsSchema | ZodSchema | 输入参数的模式定义 |\n\n### 工具调用流程\n\n1. **描述注册**：工具注册时提供名称和描述\n2. **意图识别**：LLM 根据用户问题和工具描述判断是否需要调用\n3. **参数生成**：LLM 根据工具的 schema 生成调用参数\n4. **安全执行**：系统验证参数并执行工具\n5. **结果返回**：工具执行结果返回给 LLM 继续处理\n\nTools 系统还支持动态工具调用配置，允许在运行时修改工具行为和可见性。\n\n## Chat Models 聊天模型接口\n\n### 接口设计\n\nChat Models 接口抽象了所有聊天语言模型的通用能力，提供了一套标准化的 API。通过这个接口，LangChain.js 可以统一地与不同的 LLM 提供商（如 OpenAI、Anthropic、Cohere 等）交互。\n\n接口设计遵循流式优先的原则，所有模型都支持流式输出，允许实时处理生成的内容。这对于需要即时反馈的应用场景至关重要。\n\n### 核心能力\n\n| 能力 | 说明 | 重要性 |\n|------|------|--------|\n| 同步调用 | 等待完整响应返回 | 高 |\n| 流式输出 | 实时获取生成的文本片段 | 高 |\n| 批量处理 | 一次处理多个请求 | 中 |\n| 结构化输出 | 生成符合 schema 的 JSON | 高 |\n| 工具调用 | 支持 function calling | 高 |\n| 多模态 | 支持图像、音频等输入 | 中 |\n\n### 消息类型\n\n接口定义了标准化的消息类型系统，包括：\n\n- **HumanMessage**：用户发送的消息\n- **AIMessage**：AI 生成的响应\n- **SystemMessage**：系统级指令\n- **ToolMessage**：工具执行结果\n- **AIMessageChunk**：流式输出的消息片段\n\n## Vector Stores 向量存储接口\n\n### 检索增强生成支持\n\nVector Stores 接口为检索增强生成（RAG）提供了向量存储和相似性检索的基础设施。接口设计兼容多种向量数据库，包括本地内存存储和云服务（如 Pinecone、Weaviate、Chroma 等）。\n\n```mermaid\ngraph LR\n A[文档] --> B[文档加载器]\n B --> C[文本分割器]\n C --> D[嵌入模型]\n D --> E[向量存储]\n \n F[用户查询] --> G[嵌入模型]\n G --> H[相似性搜索]\n H --> E\n E --> I[相关文档]\n I --> J[LLM 生成]\n```\n\n### 核心方法\n\n| 方法名 | 说明 |\n|--------|------|\n| `addDocuments()` | 添加文档到向量存储 |\n| `similaritySearch()` | 基于向量相似性搜索 |\n| `similaritySearchWithScore()` | 返回相似性得分 |\n| `delete()` | 删除指定文档 |\n| `getCapabilities()` | 获取存储能力信息 |\n\n### 索引管理\n\n向量存储支持灵活的索引管理，允许：\n\n- 增量更新文档而无需重建整个索引\n- 基于元数据过滤搜索结果\n- 配置不同的相似性度量方法（余弦相似度、欧氏距离等）\n\n## 模块协作示例\n\n以下流程图展示了一个典型 RAG 应用中各模块的协作方式：\n\n```mermaid\nsequenceDiagram\n participant User as 用户\n participant Chain as Chain\n participant Memory as Memory\n participant Retriever as Retriever\n participant VS as Vector Store\n participant LLM as LLM\n \n User->>Chain: 用户查询\n Chain->>Memory: 获取对话上下文\n Memory-->>Chain: 历史消息\n Chain->>Retriever: 检索请求\n Retriever->>VS: 向量相似性搜索\n VS-->>Retriever: 相关文档\n Retriever-->>Chain: 上下文文档\n Chain->>LLM: 组合查询+上下文\n LLM-->>Chain: 生成回答\n Chain->>Memory: 保存对话\n Chain-->>User: 返回结果\n```\n\n## 类型系统与验证\n\n### Zod Schema 集成\n\nLangChain.js 深度集成了 Zod 进行类型验证和模式定义。这种集成提供了：\n\n1. **编译时类型检查**：TypeScript 编译器可以验证类型安全\n2. **运行时验证**：确保输入输出符合预期格式\n3. **自动类型推断**：减少手写类型定义的工作量\n4. **LLM 输出验证**：验证模型生成的响应是否符合 schema\n\n### 层级化类型定义\n\n| 层级 | 用途 | 示例 |\n|------|------|------|\n| `input` | API 输入参数 | 用户提供的原始数据 |\n| `z.input` | 输入模式 | 验证后的输入类型 |\n| `z.output` | 输出模式 | 模型生成的响应类型 |\n| `z.infer` | 推断类型 | TypeScript 类型推导 |\n\n## 最佳实践建议\n\n### 组件设计原则\n\n1. **优先使用接口**：通过抽象接口编程，提高代码的可测试性和可替换性\n2. **利用类型系统**：充分利用 TypeScript 和 Zod 的类型检查能力\n3. **模块化组合**：将复杂逻辑拆分为可复用的 Runnable 组件\n\n### 性能优化\n\n1. **流式处理**：对实时性要求高的场景使用流式 API\n2. **批量操作**：批量处理多个独立请求以提高吞吐量\n3. **缓存策略**：对不频繁变化的计算结果进行缓存\n\n### 错误处理\n\n1. **使用 Callbacks**：通过事件系统监控执行过程中的错误\n2. **类型验证**：在处理外部输入前进行严格的类型验证\n3. **优雅降级**：为可能的失败场景准备降级方案\n\n---\n\n本页面基于 LangChain.js 源码分析了其核心架构和抽象设计。各核心模块相互协作，共同支撑起构建复杂 LLM 应用的基础能力。开发者可以根据这些抽象接口进行扩展和定制，构建满足特定需求的 LangChain 应用。\n\n---\n\n\n\n## Agent 与 Chains 实现\n\n### 相关页面\n\n相关主题：[系统架构与核心抽象](#page-2), [向量存储与检索系统](#page-4)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [libs/langchain-core/src/agents/types.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-core/src/agents/types.ts)\n- [libs/langchain-core/src/messages/ai.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-core/src/messages/ai.ts)\n- [libs/langchain/src/agents/middleware/hitl.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain/src/agents/middleware/hitl.ts)\n- [libs/langchain-classic/src/agents/format_scratchpad/xml.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-classic/src/agents/format_scratchpad/xml.ts)\n- [libs/langchain-classic/src/chains/question_answering/load.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-classic/src/chains/question_answering/load.ts)\n- [libs/langchain-classic/src/chains/llm_chain.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-classic/src/chains/llm_chain.ts)\n
\n\n# Agent 与 Chains 实现\n\n## 概述\n\nLangChain.js 中的 Agent 与 Chains 模块构成了构建 LLM 驱动应用的核心架构。Agent 负责动态决策和工具调用，而 Chains 则提供了将多个组件组合成连贯工作流的机制。这两者共同支持了从简单的问答系统到复杂的自主代理应用。\n\n## 核心架构\n\n### Agent 类型系统\n\nLangChain.js 定义了完善的类型系统来支持不同类型的 Agent 实现：\n\n```typescript\n// 资料来源：libs/langchain-core/src/agents/types.ts\nexport type N = typeof START | \"model_request\" | \"tools\";\n```\n\n类型推断助手允许开发者从 Agent 配置中提取特定类型：\n\n| 工具函数 | 用途 |\n|---------|------|\n| `InferAgentType` | 提取上下文类型 |\n| `InferAgentMiddleware` | 提取中间件类型 |\n| `InferAgentTools` | 提取工具类型 |\n| `InferAgentStreamTransformers` | 提取流转换器类型 |\n\n```typescript\n// 资料来源：libs/langchain-core/src/agents/types.ts\n/**\n * Shorthand helper to extract the Tools type from an AgentTypeConfig or ReactAgent.\n */\nexport type InferAgentTools = InferAgentType;\n```\n\n### 中断机制\n\nAgent 系统支持中断功能，用于实现 Human-in-the-Loop (HITL) 模式：\n\n```typescript\n// 资料来源：libs/langchain/src/agents/middleware/hitl.ts\nexport interface Interrupt {\n // 表示中断状态的接口\n}\n```\n\nInterrupt 配置支持动态描述生成：\n\n```typescript\n// 资料来源：libs/langchain/src/agents/middleware/hitl.ts\nconst formatToolDescription: DescriptionFactory = (\n toolCall: ToolCall,\n state: AgentBuiltInState,\n runtime: Runtime\n) => {\n return `Tool: ${toolCall.name}\\nArguments:\\n${JSON.stringify(toolCall.args, null, 2)}`;\n};\n```\n\n## Agent 实现类型\n\n### ReAct Agent\n\nReAct (Reasoning + Acting) Agent 结合了推理和行动能力，通过中间步骤处理复杂任务。\n\n### OpenAI Functions Agent\n\n针对 OpenAI 函数调用能力优化的 Agent，利用结构化输出进行工具选择。\n\n### Structured Chat Agent\n\n支持结构化聊天交互的 Agent，适合需要复杂参数的工具调用场景。\n\n## Chains 实现\n\n### LLMChain\n\nLLMChain 是最基本的链实现，用于将提示模板与 LLM 结合：\n\n```typescript\n// 资料来源：libs/langchain-classic/src/chains/llm_chain.ts\nconst llmChain = new LLMChain({ prompt, llm, verbose });\n```\n\n### 问答链加载\n\nLangChain 提供了灵活的问答链加载机制：\n\n```typescript\n// 资料来源：libs/langchain-classic/src/chains/question_answering/load.ts\nexport function loadQAStuffChain(\n llm: BaseLanguageModelInterface,\n params: StuffQAChainParams = {}\n) {\n const { prompt = QA_PROMPT_SELECTOR.getPrompt(llm), verbose } = params;\n const llmChain = new LLMChain({ prompt, llm, verbose });\n const chain = new StuffDocumentsChain({ llmChain, verbose });\n return chain;\n}\n```\n\n支持三种主要的问答链类型：\n\n| 链类型 | 描述 | 使用场景 |\n|-------|------|---------|\n| `stuff` | 将所有文档塞入单个提示 | 文档较少时 |\n| `map_reduce` | 分别处理每个文档后汇总 | 文档较多时 |\n| `refine` | 迭代式精炼答案 | 需要渐进式推理 |\n\n### 参数配置\n\n```typescript\n// 资料来源：libs/langchain-classic/src/chains/question_answering/load.ts\nexport interface StuffQAChainParams {\n prompt?: BasePromptTemplate;\n verbose?: boolean;\n}\n\nexport interface MapReduceQAChainParams {\n returnIntermediateSteps?: MapReduceDocumentsChainInput[\"returnIntermediateSteps\"];\n combineMapPrompt?: BasePromptTemplate;\n combinePrompt?: BasePromptTemplate;\n combineLLM?: BaseLanguageModelInterface;\n verbose?: boolean;\n}\n```\n\n## 工具调用系统\n\n### AIMessage 与 Tool Calls\n\nAIMessage 类集成了工具调用支持，处理消息内容块转换：\n\n```typescript\n// 资料来源：libs/langchain-core/src/messages/ai.ts\nif (this.tool_calls) {\n const missingToolCalls = this.tool_calls.filter(\n (block) =>\n !blocks.some((b) => b.id === block.id && b.name === block.name)\n );\n blocks.push(\n ...(missingToolCalls.map((block) => ({\n type: \"tool_call\" as const,\n id: block.id,\n name: block.name,\n args: block.args,\n })) as ContentBlock.Tools.ToolCall[])\n );\n}\n```\n\n### Action 接口\n\n```typescript\n// 资料来源：libs/langchain/src/agents/middleware/hitl.ts\nexport interface Action {\n /**\n * 动作类型或名称（如 \"add_numbers\"）\n */\n name: string;\n /**\n * 动作所需参数的键值对（如 {\"a\": 1, \"b\": 2}）\n */\n args: Record;\n}\n```\n\n## Scratchpad 格式化\n\nAgent 使用 scratchpad 记录中间推理步骤，支持 XML 格式：\n\n```typescript\n// 资料来源：libs/langchain-classic/src/agents/format_scratchpad/xml.ts\nexport function formatXml(intermediateSteps: AgentStep[]) {\n let log = \"\";\n for (const step of intermediateSteps) {\n const { action, observation } = step;\n log += `${action.tool}${action.toolInput}\\n${observation}`;\n }\n return log;\n}\n```\n\n## 架构流程图\n\n```mermaid\ngraph TD\n A[用户输入] --> B[Agent 决策]\n B --> C{选择工具?}\n C -->|是| D[执行工具]\n D --> E[获取观察结果]\n E --> B\n C -->|否| F[生成最终响应]\n B --> G{需要人工确认?}\n G -->|是| H[中断并等待]\n H --> I[人类决策]\n I --> B\n G -->|否| F\n```\n\n## 消息传递流程\n\n```mermaid\nsequenceDiagram\n participant U as 用户\n participant A as Agent\n participant M as AIMessage\n participant T as 工具\n\n U->>A: 输入请求\n A->>M: 生成消息\n M->>M: 处理 tool_calls\n M->>M: 转换 contentBlocks\n A->>T: 调用工具\n T->>A: 返回结果\n A->>U: 最终响应\n```\n\n## 配置与中间件\n\n### InterruptOnConfig 配置\n\n```typescript\n// 资料来源：libs/langchain/src/agents/middleware/hitl.ts\nconst config: InterruptOnConfig = {\n allowedDecisions: [\"approve\", \"edit\"],\n description: formatToolDescription,\n argsSchema: z.record(z.any()).optional(),\n};\n```\n\n### 配置参数说明\n\n| 参数 | 类型 | 必填 | 描述 |\n|------|------|------|------|\n| `allowedDecisions` | `string[]` | 否 | 允许的决策列表 |\n| `description` | `string \\| DescriptionFunction` | 否 | 决策描述 |\n| `argsSchema` | `Record` | 否 | 参数的 JSON Schema |\n\n## 测试匹配器\n\nLangChain 提供了专门的测试匹配器用于验证 Agent 行为：\n\n```typescript\n// 资料来源：libs/langchain-core/src/testing/matchers.ts\nexport const langchainMatchers = {\n toBeHumanMessage,\n toBeAIMessage,\n toBeSystemMessage,\n toBeToolMessage,\n toHaveToolCalls,\n toHaveToolCallCount,\n toContainToolCall,\n toHaveToolMessages,\n toHaveBeenInterrupted,\n toHaveStructuredResponse,\n};\n```\n\n## 最佳实践\n\n### 工具选择策略\n\n1. **评估任务复杂度**：简单任务使用单一工具，复杂任务考虑多工具协作\n2. **定义清晰的工具描述**：确保 Agent 能准确理解工具用途\n3. **处理工具调用失败**：实现降级策略和错误恢复机制\n\n### Chain 组合建议\n\n1. **从 LLMChain 开始**：验证基础功能后再组合复杂链\n2. **使用输入输出映射**：确保数据在链之间正确传递\n3. **添加错误处理**：为每个链组件添加适当的异常处理\n\n## 版本迁移\n\n`@langchain/classic` 包保留了 v0.x 版本的链实现，用于向后兼容：\n\n```typescript\n// 资料来源：libs/langchain-classic/README.md\n- `LLMChain` - Basic chain for calling an LLM with a prompt template\n- `ConversationalRetrievalQAChain` - Chain for conversational question-answering\n- `RetrievalQAChain` - Chain for question-answering over documents\n```\n\n新项目推荐使用 `createAgent` API 获取更好的性能和更清晰的接口。\n\n---\n\n\n\n## 向量存储与检索系统\n\n### 相关页面\n\n相关主题：[Agent 与 Chains 实现](#page-3), [扩展提供商与工具集成](#page-6)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [libs/langchain-classic/src/vectorstores/memory.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-classic/src/vectorstores/memory.ts)\n- [libs/providers/langchain-pinecone/README.md](https://github.com/langchain-ai/langchainjs/blob/main/libs/providers/langchain-pinecone/README.md)\n- [libs/providers/langchain-qdrant/README.md](https://github.com/langchain-ai/langchainjs/blob/main/libs/providers/langchain-qdrant/README.md)\n- [libs/langchain-classic/src/retrievers/parent_document.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-classic/src/retrievers/parent_document.ts)\n- [libs/langchain-classic/src/retrievers/multi_query.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-classic/src/retrievers/multi_query.ts)\n- [examples/src/langchain-classic/indexes/html_text_splitter.ts](https://github.com/langchain-ai/langchainjs/blob/main/examples/src/langchain-classic/indexes/html_text_splitter.ts)\n- [libs/langchain-textsplitters/README.md](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-textsplitters/README.md)\n
\n\n# 向量存储与检索系统\n\n## 概述\n\nLangChain.js 的向量存储与检索系统是构建检索增强生成（RAG）应用的核心基础设施。该系统提供了一套完整的接口和实现，用于将文档转换为向量表示、存储在各种向量数据库中，并通过语义相似性进行高效检索。\n\n系统设计遵循模块化原则，提供了统一的 `VectorStore` 接口规范，使得不同的向量存储后端可以无缝切换。开发者可以根据数据规模、查询性能和部署需求选择合适的存储方案，同时保持上层应用代码的一致性。\n\nLangChain.js 支持多种主流向量数据库集成，包括内存存储（用于开发测试）、Pinecone、Qdrant、MongoDB Atlas Search、PostgreSQL PGVector 等，为企业级应用提供了丰富的选择。\n\n## 核心架构\n\n### 系统组件关系\n\nLangChain.js 的向量存储与检索系统由多个核心组件构成，这些组件协同工作以实现完整的文档处理和检索流程。\n\n```mermaid\ngraph TD\n A[文档输入] --> B[文本分割器 Text Splitters]\n B --> C[向量化 Embeddings]\n C --> D[向量存储 VectorStore]\n D --> E[检索器 Retrievers]\n E --> F[应用层]\n \n G[Embedding Models] --> C\n \n H[Pinecone] --> D\n I[Qdrant] --> D\n J[MongoDB] --> D\n K[PGVector] --> D\n L[Memory] --> D\n```\n\n### 数据处理流程\n\n文档从原始格式到可检索向量的转换过程涉及多个阶段，每个阶段都有明确的职责边界。\n\n```mermaid\ngraph LR\n A[原始文档] --> B[文本分割]\n B --> C[小文档块]\n C --> D[调用 Embeddings API]\n D --> E[向量 + 元数据]\n E --> F[存储到 VectorStore]\n \n G[用户查询] --> H[查询向量化]\n H --> I[相似度搜索]\n I --> J[返回相关文档]\n```\n\n## 向量存储接口\n\n### VectorStore 基类\n\n`VectorStore` 是所有向量存储实现的基础抽象接口，定义了向量存储的核心操作方法。所有具体的向量存储实现都继承自这个接口，确保了 API 的一致性和可替换性。\n\n接口主要包含以下几个核心方法：\n\n```typescript\nclass VectorStore {\n // 添加文档到向量存储\n async addDocuments(documents: Document[]): Promise\n \n // 通过相似度搜索查找相关文档\n async similaritySearch(\n query: string, \n k?: number\n ): Promise\n \n // 带相似度分数的搜索\n async similaritySearchWithScore(\n query: string,\n k?: number\n ): Promise<[Document, number][]>\n \n // 删除文档\n async delete(ids?: string[]): Promise\n \n // 跨链支持\n asRetriever(config?: SimilarityRetrieverConfig): BaseRetriever\n}\n```\n\n### 内存向量存储\n\n`MemoryVectorStore` 是最简单的向量存储实现，将所有向量存储在内存中。这种实现适用于开发测试、小规模数据集，或作为原型验证阶段的首选方案。由于数据存储在内存中，应用重启后数据会丢失，不适合生产环境使用。\n\n```typescript\nimport { MemoryVectorStore } from 'langchain/vectorstores/memory'\nimport { OpenAIEmbeddings } from '@langchain/openai'\n\nconst embeddings = new OpenAIEmbeddings({\n model: \"text-embedding-3-small\",\n})\n\nconst vectorStore = new MemoryVectorStore(embeddings)\n\nconst documents = [\n { pageContent: \"文档内容示例\", metadata: { source: \"doc1\" } },\n { pageContent: \"另一篇文档内容\", metadata: { source: \"doc2\" } }\n]\n\nawait vectorStore.addDocuments(documents)\n\nconst results = await vectorStore.similaritySearch(\"查询文本\", 2)\n```\n\n## 第三方向量存储集成\n\n### Pinecone 集成\n\nPinecone 是一个托管的向量数据库服务，提供高性能的向量存储和检索能力。LangChain.js 通过 `@langchain/pinecone` 包提供了完整的集成支持。\n\n#### 安装配置\n\n```bash\nnpm install @langchain/pinecone @langchain/core @pinecone-database/pinecone\n```\n\n#### 使用示例\n\n```typescript\nimport { PineconeStore } from '@langchain/pinecone'\nimport { Pinecone } from '@pinecone-database/pinecone'\nimport { OpenAIEmbeddings } from '@langchain/openai'\n\nconst pinecone = new Pinecone()\nconst index = pinecone.Index('your-index-name')\n\nconst vectorStore = await PineconeStore.fromExistingIndex(\n new OpenAIEmbeddings(),\n { pineconeIndex: index }\n)\n```\n\n### Qdrant 集成\n\nQdrant 是一个开源的向量相似度搜索引擎，支持混合搜索和过滤。`@langchain/qdrant` 包提供了与 Qdrant 的完整集成。\n\n#### 安装配置\n\n```bash\nnpm install @langchain/qdrant\n```\n\n#### 核心特性\n\n| 特性 | 说明 |\n|------|------|\n| 混合搜索 | 支持向量搜索与关键词搜索结合 |\n| 过滤条件 | 支持元数据过滤 |\n| 集合管理 | 提供集合创建和管理接口 |\n| 距离度量 | 支持 Cosine、Euclidean、Dot 产品 |\n\n### MongoDB Atlas Search\n\nMongoDB Atlas Search 提供了基于 Lucene 的全文搜索能力，结合 MongoDB 的文档模型，可以存储和检索带有多维向量的文档。`@langchain/mongodb` 包提供了这一集成。\n\n### PGVector 集成\n\n对于已在使用 PostgreSQL 的团队，PGVector 提供了在关系数据库中存储和检索向量的能力。`@langchain/pgvector` 包支持这一集成，使得可以利用现有的 PostgreSQL 基础设施。\n\n#### 配置参数\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| connectionString | string | PostgreSQL 连接字符串 |\n| tableName | string | 存储向量的表名（默认：langchain_vectorstore） |\n| columns | object | 向量和元数据列的配置 |\n| distanceStrategy | string | 距离计算策略 |\n\n## 检索器系统\n\n检索器（Retriever）是连接向量存储和应用逻辑的关键组件。LangChain.js 提供了多种检索器实现，以适应不同的检索场景和需求。\n\n### 父文档检索器\n\n`ParentDocumentRetriever` 解决了小文本块丢失上下文信息的问题。该检索器首先检索与查询相关的小文本块，然后返回这些小块所属的完整父文档。\n\n```mermaid\ngraph TD\n A[用户查询] --> B[检索小块]\n B --> C[获取父文档ID]\n C --> D[加载完整父文档]\n D --> E[返回带上下文的结果]\n \n F[小块1] --> G[父文档A]\n H[小块2] --> G\n I[小块3] --> J[父文档B]\n```\n\n这种策略在保持检索精确性的同时，确保返回的内容具有完整的上下文信息，特别适用于需要返回较长连续文本的场景。\n\n### 多查询检索器\n\n`MultiQueryRetriever` 通过使用语言模型生成多个不同角度的查询，然后对所有查询的结果进行去重合并，从而提高检索的召回率。\n\n```typescript\nimport { MultiQueryRetriever } from 'langchain/retrievers/multi_query'\n\nconst retriever = MultiQueryRetriever.fromLLM({\n llm: chatModel,\n retriever: baseRetriever,\n includeOriginal: true,\n verbose: true,\n})\n```\n\n| 参数 | 说明 |\n|------|------|\n| llm | 用于生成多查询的语言模型 |\n| retriever | 基础检索器 |\n| includeOriginal | 是否包含原始查询的结果 |\n| verbose | 是否输出详细日志 |\n\n### 检索器配置\n\n所有检索器都支持通过配置对象进行定制化设置，主要配置选项包括：\n\n| 配置项 | 说明 | 默认值 |\n|--------|------|--------|\n| k | 返回的文档数量 | 4 |\n| filter | 元数据过滤条件 | undefined |\n| namespace | 命名空间（部分向量存储支持） | undefined |\n\n## 文本分割器\n\n文本分割器是将长文档拆分为适合嵌入和检索的小块的关键组件。`@langchain/textsplitters` 包提供了多种分割策略。\n\n### 递归字符分割器\n\n`RecursiveCharacterTextSplitter` 是最常用的分割器，它按照预定义的字符优先级递归地分割文本，确保语义完整性。\n\n```typescript\nimport { RecursiveCharacterTextSplitter } from \"@langchain/textsplitters\"\n\nconst splitter = RecursiveCharacterTextSplitter.fromLanguage(\"html\", {\n chunkSize: 175,\n chunkOverlap: 20,\n})\n\nconst output = await splitter.createDocuments([text])\n```\n\n### 分割参数说明\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| chunkSize | number | 每个块的最大字符数 |\n| chunkOverlap | number | 相邻块之间的重叠字符数 |\n| separators | string[] | 分割符列表（按优先级排序） |\n\n### 语言特定分割\n\n分割器支持针对不同内容类型进行优化配置：\n\n```typescript\n// Markdown 文档\nconst mdSplitter = RecursiveCharacterTextSplitter.fromLanguage(\"markdown\", {\n chunkSize: 1000,\n chunkOverlap: 100,\n})\n\n// 代码文件\nconst codeSplitter = RecursiveCharacterTextSplitter.fromLanguage(\"js\", {\n chunkSize: 500,\n chunkOverlap: 50,\n})\n\n// HTML 文档\nconst htmlSplitter = RecursiveCharacterTextSplitter.fromLanguage(\"html\", {\n chunkSize: 175,\n chunkOverlap: 20,\n})\n```\n\n## Embeddings 集成\n\nEmbeddings 是将文本转换为向量表示的模型。LangChain.js 通过标准化的接口支持多种 Embeddings 提供商。\n\n### 接口定义\n\n```typescript\ninterface Embeddings {\n embedQuery(text: string): Promise\n embedDocuments(texts: string[]): Promise\n}\n```\n\n### 支持的提供商\n\n| 提供商 | 包名 | 说明 |\n|--------|------|------|\n| OpenAI | @langchain/openai | text-embedding-3-small/large |\n| Google | @langchain/google-vertexai | Palm/Embedding-Gecko |\n| Anthropic | @langchain/anthropic | Claude 内置支持 |\n| Cohere | @langchain/cohere | Embed v3/v4 |\n| HuggingFace | @langchain/huggingface | 数千种开源模型 |\n\n## 最佳实践\n\n### 数据处理流程\n\n构建高效的向量检索系统需要遵循系统化的数据处理流程。在数据准备阶段，应根据内容类型选择合适的分割策略：结构化文档使用语义分割，代码文件按函数或类分割，网页内容按 HTML 标签语义分割。\n\n```mermaid\ngraph TD\n A[数据收集] --> B[数据清洗]\n B --> C[内容分类]\n C --> D[选择分割策略]\n D --> E[文本分割]\n E --> F[向量化]\n F --> G[质量检查]\n G --> H{是否合格}\n H -->|否| E\n H -->|是| I[存储向量]\n I --> J[索引优化]\n```\n\n### 查询优化\n\n在进行相似性搜索时，应充分利用向量数据库的过滤功能，在向量相似度计算前先进行元数据过滤，以减少搜索范围并提高准确性。对于复杂的查询场景，考虑使用混合搜索策略，结合向量相似度和关键词匹配。\n\n### 生产环境考虑\n\n生产环境中应重点关注向量存储的索引配置、查询延迟监控、以及 Embeddings 模型的选择。对于大规模数据集，Pinecone 或 Qdrant 等专用向量数据库通常比通用数据库提供更好的性能。同时应建立 Embeddings 缓存机制，避免对相同文本重复进行向量化计算。\n\n## 相关资源\n\n- [官方文档](https://docs.langchain.com/oss/javascript/langchain)\n- [@langchain/textsplitters 文档](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-textsplitters/README.md)\n- [@langchain/pinecone 文档](https://github.com/langchain-ai/langchainjs/blob/main/libs/providers/langchain-pinecone/README.md)\n- [@langchain/qdrant 文档](https://github.com/langchain-ai/langchainjs/blob/main/libs/providers/langchain-qdrant/README.md)\n\n---\n\n\n\n## 主要模型提供商集成\n\n### 相关页面\n\n相关主题：[系统架构与核心抽象](#page-2), [扩展提供商与工具集成](#page-6)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [libs/providers/langchain-anthropic/src/chat_models.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/providers/langchain-anthropic/src/chat_models.ts)\n- [libs/providers/langchain-openai/src/chat_models/index.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/providers/langchain-openai/src/chat_models/index.ts)\n- [libs/langchain-classic/src/vectorstores/memory.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-classic/src/vectorstores/memory.ts)\n- [libs/langchain-core/src/messages/message.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-core/src/messages/message.ts)\n- [libs/langchain-core/src/language_models/utils.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-core/src/language_models/utils.ts)\n
\n\n# 主要模型提供商集成\n\n## 概述\n\nLangChain.js 的主要模型提供商集成模块为开发者提供了统一的接口，用于对接多个主流 AI 服务提供商的 chat models。这些集成通过标准化的抽象层，使得应用程序能够在不同提供商之间无缝切换，同时保持代码的兼容性和可维护性。\n\n集成模块位于 `libs/providers/` 目录下，支持的提供商包括 OpenAI、Anthropic、Google Vertex AI、Google GenAI、Mistral AI 等主流 LLM 服务商。每个提供商都实现了统一的 chat model 接口规范，确保了调用方式的一致性。\n\n## 架构设计\n\n### 核心抽象层\n\nLangChain.js 采用分层架构设计，模型提供商集成位于基础设施层之上，为上层应用提供统一的 AI 能力访问接口。\n\n```mermaid\ngraph TD\n A[应用层 Application] --> B[链与代理层 Chains & Agents]\n B --> C[模型抽象层 Model Abstraction]\n C --> D[提供商集成层 Provider Integrations]\n D --> E[OpenAI]\n D --> F[Anthropic]\n D --> G[Google Vertex]\n D --> H[Mistral AI]\n E --> I[外部 API 服务]\n F --> I\n G --> I\n H --> I\n```\n\n### 消息标准化\n\n每个模型集成都实现了消息格式的标准化转换，确保不同提供商的消息结构能够被正确处理。核心的消息类型定义位于 `libs/langchain-core/src/messages/message.ts`，包括工具定义（`MessageToolDefinition`）、工具集（`MessageToolSet`）等关键数据结构。\n\n```mermaid\ngraph LR\n A[用户消息] --> B[标准化消息格式]\n B --> C[Provider-specific 转换]\n C --> D[API 请求格式]\n D --> E[模型提供商]\n```\n\n## 核心功能特性\n\n### 统一调用接口\n\n所有 chat model 实现都遵循统一的调用模式，支持 `invoke` 方法进行同步调用和 `stream` 方法进行流式响应处理。这种设计使得开发者可以在不修改应用代码的情况下更换底层模型提供商。\n\n```typescript\n// 统一的调用方式\nconst result = await llm.invoke(input);\nfor await (const chunk of await llm.stream(input)) {\n console.log(chunk);\n}\n```\n\n资料来源：[libs/providers/langchain-anthropic/src/chat_models.ts]()\n\n### 结构化输出\n\n模型集成支持通过 `withStructuredOutput()` 方法实现结构化输出，该功能使用提供商的原生工具调用能力来约束输出格式到特定的 JSON schema。\n\n| 功能 | 描述 | 实现方式 |\n|------|------|----------|\n| 函数调用 | 使用工具调用约束输出 | `withStructuredOutput()` |\n| JSON Schema | 使用原生 JSON schema 支持 | Provider 原生功能 |\n| 类型安全 | 提供完整的 TypeScript 类型推导 | Zod schema 定义 |\n\n资料来源：[libs/providers/langchain-anthropic/src/chat_models.ts]()\n\n### 工具调用支持\n\n集成模块提供了完整的工具调用（Tool Calling）支持，允许模型调用外部工具和函数。这一功能通过 `tool()` 辅助函数实现，支持 Zod schema 定义工具参数。\n\n```typescript\nimport { tool } from \"@langchain/core/tools\";\nimport { z } from \"zod\";\n\nconst getWeather = tool(\n async (input) => `Weather in ${input.location}`,\n {\n name: \"get_weather\",\n description: \"Get weather for a location\",\n schema: z.object({ location: z.string() }),\n }\n);\n```\n\n资料来源：[libs/providers/langchain-anthropic/src/chat_models.ts]()\n\n## OpenAI 集成\n\n### 基本配置\n\nOpenAI 集成提供了对 GPT 系列模型的访问支持，核心实现在 `libs/providers/langchain-openai/src/chat_models/index.ts`。\n\n```typescript\nimport { ChatOpenAI } from \"@langchain/openai\";\n\nconst llm = new ChatOpenAI({\n model: \"gpt-4o\",\n temperature: 0.7,\n // 其他配置参数...\n});\n```\n\n### 流式响应处理\n\nOpenAI 集成支持流式输出，响应包含内容块、元数据和 token 使用统计信息。\n\n```txt\nAIMessageChunk {\n \"id\": \"chatcmpl-9u4NWB7yUeHCKdLr6jP3HpaOYHTqs\",\n \"content\": \"\"\n}\nAIMessageChunk {\n \"content\": \"J\"\n}\nAIMessageChunk {\n \"content\": \"'adore\"\n}\n```\n\n资料来源：[libs/providers/langchain-openai/src/chat_models/index.ts]()\n\n## Anthropic 集成\n\n### 特性概述\n\nAnthropic 集成专门针对 Claude 系列模型进行了优化，提供了额外的特性支持，包括高级工具使用和搜索功能。\n\n| 特性 | 描述 | 适用版本 |\n|------|------|----------|\n| 标准工具调用 | 基础函数调用功能 | 所有版本 |\n| 工具搜索 | 使用 regex 或 bm25 搜索工具 | 需 `advanced-tool-use-2025-11-20` beta |\n| 延迟加载工具 | 按需加载不常用工具 | 支持 `defer_loading: true` |\n\n资料来源：[libs/providers/langchain-anthropic/src/chat_models.ts]()\n\n### 消息块翻译\n\nAnthropic 集成实现了消息块翻译器（BlockTranslator）接口，用于在标准格式和提供商特定格式之间进行转换：\n\n```typescript\nBlockTranslator = {\n translateContent: (message) => {\n if (typeof message.content === \"string\") {\n return convertToV1FromChatCompletions(message);\n }\n return convertToV1FromResponses(message);\n },\n translateContentChunk: (message) => { /* ... */ },\n};\n```\n\n资料来源：[libs/langchain-core/src/messages/block_translators/openai.ts]()\n\n## 向量存储与嵌入集成\n\n### 内存向量存储\n\nLangChain.js 提供了 `MemoryVectorStore` 实现，用于在内存中存储和检索文档向量。该存储与嵌入模型配合使用，支持添加文档和相似性搜索功能。\n\n```typescript\nimport { MemoryVectorStore } from 'langchain/vectorstores/memory';\nimport { OpenAIEmbeddings } from '@langchain/openai';\n\nconst embeddings = new OpenAIEmbeddings({\n model: \"text-embedding-3-small\",\n});\n\nconst vectorStore = new MemoryVectorStore(embeddings);\n\n// 添加文档\nawait vectorStore.addDocuments(documents);\n\n// 相似性搜索\nconst results = await vectorStore.similaritySearch(\"thud\", 1);\n```\n\n资料来源：[libs/langchain-classic/src/vectorstores/memory.ts]()\n\n### 嵌入模型配置\n\n嵌入模型是 RAG（检索增强生成）管道的核心组件，用于将文本转换为向量表示。每个模型提供商都提供了相应的嵌入实现。\n\n## 消息与工具系统\n\n### 消息结构\n\nLangChain.js 定义了标准化的消息结构体系，包括基础消息类型、工具定义和工具调用块等核心组件。\n\n```mermaid\nclassDiagram\n class MessageToolDefinition {\n +TInput input\n +TOutput output\n }\n \n class MessageToolSet {\n +[key: string]: MessageToolDefinition\n }\n \n class MessageToolCallBlock {\n +string type\n +string name\n +Record args\n +string? id\n }\n \n MessageToolSet --> MessageToolDefinition : contains\n```\n\n资料来源：[libs/langchain-core/src/messages/message.ts]()\n\n### 工具调用块类型\n\n工具调用块是消息系统中表示工具调用的关键数据结构，其类型定义如下：\n\n```typescript\ntype $MessageToolCallBlock = {\n type: \"tool_call\";\n name: string;\n args: TStructure[\"tools\"][keyof TStructure[\"tools\"]][\"input\"];\n id?: string;\n};\n```\n\n资料来源：[libs/langchain-core/src/messages/message.ts]()\n\n## 标准消息内容转换\n\n### 内容转换工具\n\n`castStandardMessageContent` 函数是 LangChain.js 消息处理的核心工具，用于标准化消息内容格式：\n\n```typescript\nfunction castStandardMessageContent(message: T) {\n const Cls = message.constructor as Constructor;\n return new Cls({\n ...message,\n content: message.contentBlocks,\n response_metadata: {\n ...message.response_metadata,\n output_version: \"v1\",\n },\n });\n}\n```\n\n该函数将消息的内容块转换为标准内容格式，并附加 v1 输出版本元数据，确保了不同提供商之间的兼容性。\n\n资料来源：[libs/langchain-core/src/language_models/utils.ts]()\n\n## 安装与配置\n\n### 依赖管理\n\n每个模型提供商包都依赖 `@langchain/core` 作为 peer dependency。建议在项目 `package.json` 中统一管理依赖版本以避免冲突：\n\n```json\n{\n \"dependencies\": {\n \"@langchain/anthropic\": \"^0.0.9\",\n \"@langchain/openai\": \"^0.0.9\",\n \"@langchain/core\": \"^0.3.0\"\n },\n \"overrides\": {\n \"@langchain/core\": \"^0.3.0\"\n }\n}\n```\n\n资料来源：[libs/providers/langchain-anthropic/README.md]()\n\n### 环境变量配置\n\n不同的提供商需要设置相应的 API 密钥：\n\n```bash\n# OpenAI\nexport OPENAI_API_KEY=\"sk-...\"\n\n# Anthropic\nexport ANTHROPIC_API_KEY=\"sk-ant-...\"\n\n# Google Cloud\nexport GOOGLEAPPLICATIONCREDENTIALS=\"/path/to/credentials.json\"\n```\n\n## 最佳实践\n\n### 提供商选择指南\n\n| 使用场景 | 推荐提供商 | 理由 |\n|----------|------------|------|\n| 通用对话 | OpenAI GPT-4o | 性能与成本平衡 |\n| 长上下文 | Anthropic Claude | 支持 200K token 上下文 |\n| 代码生成 | OpenAI / Anthropic | 两者都有优秀的代码能力 |\n| 本地部署 | Ollama / Llama.cpp | 无需 API 费用 |\n\n### 错误处理策略\n\n实现模型调用时应考虑网络错误、速率限制和配额耗尽等异常情况。建议使用指数退避重试机制，并实现适当的降级策略。\n\n### 性能优化建议\n\n1. **批量处理**：将多个请求合并为批量调用（如果提供商支持）\n2. **流式响应**：对于长文本输出，使用流式响应减少等待时间\n3. **缓存**：对重复查询实现结果缓存\n4. **连接复用**：保持 HTTP 连接活跃以减少建立开销\n\n## 相关资源\n\n- 官方文档：[LangChain.js 文档](https://js.langchain.com/)\n- API 参考：[Provider 包文档](https://github.com/langchain-ai/langchainjs/tree/main/libs/providers)\n- 示例代码：[examples 目录](https://github.com/langchain-ai/langchainjs/tree/main/examples)\n\n---\n\n\n\n## 扩展提供商与工具集成\n\n### 相关页面\n\n相关主题：[主要模型提供商集成](#page-5), [扩展开发指南](#page-9)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [libs/providers/langchain-anthropic/src/chat_models.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/providers/langchain-anthropic/src/chat_models.ts)\n- [libs/providers/langchain-openai/src/chat_models/index.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/providers/langchain-openai/src/chat_models/index.ts)\n- [libs/providers/langchain-openai/src/utils/tools.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/providers/langchain-openai/src/utils/tools.ts)\n- [libs/langchain-core/src/messages/block_translators/openai.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-core/src/messages/block_translators/openai.ts)\n- [libs/langchain-core/src/messages/ai.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-core/src/messages/ai.ts)\n- [libs/langchain-core/src/messages/message.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-core/src/messages/message.ts)\n- [libs/langchain-core/src/language_models/utils.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-core/src/language_models/utils.ts)\n- [libs/langchain/src/agents/types.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain/src/agents/types.ts)\n- [libs/langchain/src/agents/middleware/hitl.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain/src/agents/middleware/hitl.ts)\n- [libs/langchain-core/src/testing/matchers.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-core/src/testing/matchers.ts)\n
\n\n# 扩展提供商与工具集成\n\n## 概述\n\nLangChain.js 的扩展提供商系统是一个模块化架构，允许通过不同的提供商 SDK 集成各种大语言模型（LLM）服务。每个提供商都实现了统一的接口规范，同时保留了各自平台特有的功能特性。工具集成是这些提供商的核心能力之一，它使得 AI 模型能够调用外部函数来执行特定任务，如计算、搜索、数据处理等。\n\n在 LangChain.js 的架构中，工具集成涉及三个主要层面的抽象：工具定义层、消息传输层和提供商适配层。工具定义使用统一的 TypeScript 类型系统描述工具的输入输出结构，消息传输层负责在不同格式之间进行转换，而提供商适配层则处理与各个 AI 服务提供商的特定集成细节。\n\n## 工具定义系统\n\n### 核心类型定义\n\nLangChain.js 在 `libs/langchain-core/src/messages/message.ts` 中定义了工具系统的核心类型结构。这些类型构成了整个工具集成的基础架构，提供了类型安全的工具定义和调用机制。\n\n```typescript\nexport interface MessageToolDefinition {\n input: TInput;\n output: TOutput;\n}\n\nexport interface MessageToolSet {\n [key: string]: MessageToolDefinition;\n}\n```\n\n资料来源：[libs/langchain-core/src/messages/message.ts:1-15]()\n\n`MessageToolDefinition` 接口使用泛型参数定义工具的输入和输出类型，允许开发者为每个工具指定精确的数据结构。`MessageToolSet` 接口则是一个映射类型，将工具名称与对应的工具定义关联起来。\n\n### 工具调用块结构\n\n工具调用块（Tool Call Block）是消息中表示工具调用的数据结构，包含工具名称、参数和可选的调用标识符。这个结构在 `MessageStructure` 的工具扩展部分定义：\n\n```typescript\ntype CalcToolCall = $MessageToolCallBlock;\n// Resolves to:\n// {\n// type: \"tool_call\";\n// name: \"calculator\";\n// args: { operation: string, numbers: number[] };\n// id?: string;\n// }\n```\n\n资料来源：[libs/langchain-core/src/messages/message.ts:50-70]()\n\n这种结构设计确保了工具调用的自包含性，每个调用都包含足够的上下文信息来执行对应的工具函数。`id` 字段是可选的，允许在不需要追踪单个调用的情况下省略。\n\n## 消息格式转换层\n\n### OpenAI 格式翻译器\n\nLangChain.js 的 `block_translators` 模块提供了不同消息格式之间的转换能力。在 `libs/langchain-core/src/messages/block_translators/openai.ts` 中实现的 `BlockTranslator` 是核心的转换逻辑：\n\n```typescript\nBlockTranslator = {\n translateContent: (message) => {\n if (typeof message.content === \"string\") {\n return convertToV1FromChatCompletions(message);\n }\n return convertToV1FromResponses(message);\n },\n translateContentChunk: (message) => {\n if (typeof message.content === \"string\") {\n return convertToV1FromChatCompletionsChunk(message);\n }\n return convertToV1FromResponsesChunk(message);\n },\n};\n```\n\n资料来源：[libs/langchain-core/src/messages/block_translators/openai.ts:1-15]()\n\n翻译器根据消息内容类型选择不同的转换路径。对于字符串内容，它使用 Chat Completions 格式的转换器；对于数组格式的内容，则使用 Responses API 格式的转换器。这种设计允许系统同时支持 OpenAI 的两种主要 API 风格。\n\n### 标准消息内容转换\n\n`libs/langchain-core/src/language_models/utils.ts` 中的 `castStandardMessageContent` 函数提供了标准消息内容的转换能力，确保消息格式在不同版本之间保持兼容性：\n\n```typescript\nfunction castStandardMessageContent(message: T) {\n const Cls = message.constructor as Constructor;\n return new Cls({\n ...message,\n content: message.contentBlocks,\n response_metadata: {\n ...message.response_metadata,\n output_version: \"v1\",\n },\n });\n}\n```\n\n资料来源：[libs/langchain-core/src/language_models/utils.ts:8-20]()\n\n该函数通过重建消息实例来确保内容块被正确格式化，同时在响应元数据中添加版本标识，便于后续处理和调试。\n\n## AIMessage 工具集成\n\n### 内容块生成逻辑\n\n`AIMessage` 类在 `libs/langchain-core/src/messages/ai.ts` 中实现了复杂的工具调用整合逻辑。其 `contentBlocks` getter 方法负责合并基础内容与工具调用信息：\n\n```typescript\noverride get contentBlocks(): ContentBlock[] {\n if (\n \"model_provider\" in this.response_metadata &&\n typeof this.response_metadata.model_provider === \"string\"\n ) {\n const translator = getTranslator(this.response_metadata.model_provider);\n if (translator) {\n return translator.translateContent(this as AIMessage);\n }\n }\n\n const blocks = super.contentBlocks;\n\n if (this.tool_calls) {\n const missingToolCalls = this.tool_calls.filter(\n (block) =>\n !blocks.some((b) => b.id === block.id && b.name === block.name)\n );\n blocks.push(\n ...(missingToolCalls.map((block) => ({\n type: \"tool_call\" as const,\n id: block.id,\n name: block.name,\n args: block.args,\n })) as ContentBlock.Tools.ToolCall[])\n );\n }\n\n return blocks;\n}\n```\n\n资料来源：[libs/langchain-core/src/messages/ai.ts:1-35]()\n\n该逻辑首先检查响应元数据中是否包含模型提供商信息，如果有则使用对应的翻译器进行格式转换。如果不存在翻译器，则采用默认逻辑，将 `tool_calls` 数组中的工具调用转换为内容块。过滤逻辑确保不会重复添加已存在于基础内容中的工具调用。\n\n### 类型守卫机制\n\nAIMessage 类提供了静态类型守卫方法来安全地识别消息类型：\n\n```typescript\nstatic isInstance(\n obj: BaseMessage\n): obj is BaseMessage & AIMessage;\nstatic isInstance(obj: unknown): obj is AIMessage;\n```\n\n资料来源：[libs/langchain-core/src/messages/ai.ts:60-68]()\n\n这两个重载分别处理泛型和非泛型场景，允许在类型安全的情况下进行类型收窄和断言。\n\n## 提供商工具格式处理\n\n### OpenAI 工具格式\n\n`libs/providers/langchain-openai/src/utils/tools.ts` 中定义了 OpenAI 特定的工具格式转换逻辑：\n\n```typescript\nIClient.Chat.ChatCompletionCustomTool = {\n getFormat: () => {\n if (!tool.format) {\n return undefined;\n }\n if (tool.format.type === \"grammar\") {\n return {\n type: \"grammar\" as const,\n grammar: {\n definition: tool.format.definition,\n syntax: tool.format.syntax,\n },\n };\n }\n if (tool.format.type === \"text\") {\n return {\n type: \"text\" as const,\n };\n }\n return undefined;\n },\n return {\n type: \"custom\",\n custom: {\n name: tool.name,\n description: tool.description,\n format: getFormat(),\n },\n };\n};\n```\n\n资料来源：[libs/providers/langchain-openai/src/utils/tools.ts:1-35]()\n\nOpenAI 支持多种工具格式类型，包括 `grammar` 格式（包含语法定义和语法规则）和 `text` 格式。这种灵活性允许开发者为不同的用例选择最合适的格式定义方式。`custom` 类型包装了所有自定义工具，确保符合 OpenAI API 的工具规范。\n\n### Anthropic 流式响应\n\nAnthropic 提供商在 `libs/providers/langchain-anthropic/src/chat_models.ts` 中处理流式响应，其输出格式与 OpenAI 不同，使用 `additional_kwargs` 传递工具元数据：\n\n```txt\nAIMessageChunk {\n \"id\": \"msg_01N8MwoYxiKo9w4chE4gXUs4\",\n \"content\": \"\",\n \"additional_kwargs\": {\n \"id\": \"msg_01N8MwoYxiKo9w4chE4gXUs4\",\n \"type\": \"message\",\n \"role\": \"assistant\",\n \"model\": \"claude-sonnet-4-5-20250929\"\n },\n \"usage_metadata\": {\n \"input_tokens\": 25,\n \"output_tokens\": 1,\n \"total_tokens\": 26\n }\n}\n```\n\n资料来源：[libs/providers/langchain-anthropic/src/chat_models.ts:50-75]()\n\nAnthropic 的流式响应以增量方式返回内容块，每个 `AIMessageChunk` 包含部分内容。这种设计优化了响应延迟，使得用户可以尽快看到初始输出。\n\n## Agent 工具集成\n\n### Agent 类型定义\n\n`libs/langchain/src/agents/types.ts` 中定义了 Agent 的类型系统，包括工具配置选项：\n\n```typescript\ninterface AgentConfig {\n model: string | AgentLanguageModelLike;\n \n tools?: (ServerTool | ClientTool)[];\n \n systemMessage?: string | SystemMessage;\n}\n```\n\n资料来源：[libs/langchain/src/agents/types.ts:1-20]()\n\nAgent 配置中的 `tools` 字段接受 `ServerTool` 或 `ClientTool` 类型的数组，允许 Agent 访问可用的工具集合。系统消息可以是简单的字符串或包含数组内容的 `SystemMessage`，后者支持更复杂的结构化内容。\n\n### 工具调用中间件\n\n`libs/langchain/src/agents/middleware/hitl.ts` 实现了人机协作的中间件系统，允许在工具执行前进行干预：\n\n```typescript\nexport interface Action {\n name: string;\n args: Record;\n}\n\nexport interface InterruptOnConfig {\n description?: z.union([z.string(), DescriptionFunctionSchema]).optional();\n argsSchema?: z.record(z.any()).optional();\n}\n```\n\n资料来源：[libs/langchain/src/agents/middleware/hitl.ts:1-30]()\n\n`Action` 接口定义了工具调用的基本结构，包含动作名称和参数记录。`InterruptOnConfig` 提供了描述工具的选项，可以是静态字符串或动态函数，允许在执行前格式化工具调用的展示信息。\n\n## 测试与验证\n\n### 工具相关匹配器\n\nLangChain.js 提供了专门的测试匹配器来验证工具调用行为，在 `libs/langchain-core/src/testing/matchers.ts` 中实现：\n\n```typescript\nexport const langchainMatchers = {\n toBeHumanMessage,\n toBeAIMessage,\n toBeSystemMessage,\n toBeToolMessage,\n toHaveToolCalls,\n toHaveToolCallCount,\n toContainToolCall,\n toHaveToolMessages,\n toHaveBeenInterrupted,\n toHaveStructuredResponse,\n};\n```\n\n资料来源：[libs/langchain-core/src/testing/matchers.ts:1-15]()\n\n这些匹配器提供了丰富的工具调用验证能力：\n\n| 匹配器 | 用途 |\n|--------|------|\n| `toHaveToolCalls` | 验证消息包含指定数量的工具调用 |\n| `toHaveToolCallCount` | 验证工具调用的精确数量 |\n| `toContainToolCall` | 验证包含特定名称或参数的工具调用 |\n| `toHaveToolMessages` | 验证工具执行后的响应消息 |\n\n工具调用匹配器的使用示例：\n\n```typescript\nexpect(message).toHaveToolCalls([\n { name: \"calculator\", args: { operation: \"add\", a: 1, b: 2 } },\n { name: \"translator\", args: { text: \"hello\", targetLanguage: \"french\" } }\n]);\n```\n\n资料来源：[libs/langchain-core/src/testing/matchers.ts:25-40]()\n\n## 架构流程图\n\n```mermaid\ngraph TD\n A[用户定义工具] --> B[MessageToolDefinition]\n B --> C[工具注册到模型]\n C --> D[模型生成工具调用]\n D --> E[工具调用块创建]\n E --> F{提供商类型}\n F -->|OpenAI| G[Chat Completions / Responses API]\n F -->|Anthropic| H[additional_kwargs]\n F -->|其他| I[提供商特定格式]\n G --> J[BlockTranslator转换]\n H --> J\n I --> J\n J --> K[标准v1格式]\n K --> L[Agent执行工具]\n L --> M[工具响应消息]\n M --> N[继续对话循环]\n```\n\n## 不同提供商的工具调用差异\n\n| 特性 | OpenAI | Anthropic | 其他提供商 |\n|------|--------|-----------|------------|\n| 工具定义格式 | `custom` 类型 + `format` | 集成到消息结构 | 各不相同 |\n| 流式响应 | `AIMessageChunk` 增量 | `AIMessageChunk` 增量 | 差异较大 |\n| 元数据传递 | `tool_calls` 数组 | `additional_kwargs` | 需适配 |\n| 格式翻译器 | `BlockTranslator` | 需扩展 | 需扩展 |\n\n## 最佳实践\n\n### 工具定义规范\n\n在 LangChain.js 中定义工具时，应遵循以下规范以确保最佳的跨提供商兼容性：\n\n1. **使用精确的 TypeScript 类型**：为工具的输入和输出定义完整的类型，避免使用 `any` 类型\n2. **提供清晰的描述**：工具描述应准确反映功能，便于模型理解何时调用\n3. **使用 Zod Schema**：通过 Zod 定义参数验证架构，确保传入参数的有效性\n\n### 消息处理建议\n\n处理包含工具调用的消息时，建议采用以下策略：\n\n1. **始终检查翻译器**：在处理提供商特定格式时，先检查是否存在对应的翻译器\n2. **合并重复工具调用**：使用 `AIMessage` 中的过滤逻辑避免重复添加\n3. **处理缺失字段**：工具调用块中的 `id` 是可选的，应有合理的降级处理\n\n### 扩展新提供商\n\n为新的 AI 服务提供商添加工具集成支持时，需要实现以下组件：\n\n1. 创建提供商特定的工具格式转换器\n2. 实现 `BlockTranslator` 接口的转换方法\n3. 在 `getTranslator` 注册新的翻译器\n4. 编写集成测试验证功能正确性\n\n## 总结\n\nLangChain.js 的扩展提供商与工具集成系统通过分层架构实现了灵活而强大的工具调用能力。核心类型系统提供了统一的工具定义规范，消息格式转换层确保了不同提供商之间的互操作性，而 Provider 适配层则处理了各个平台的特定实现细节。\n\n这套系统的主要优势包括：类型安全的消息处理、统一的工具定义接口、灵活的消息格式转换，以及完善的测试支持。开发者可以通过实现对应的翻译器和适配器，将新的 AI 提供商集成到 LangChain.js 生态系统中，同时保持与其他提供商的一致性体验。\n\n---\n\n\n\n## 多环境部署支持\n\n### 相关页面\n\n相关主题：[依赖管理与测试策略](#page-8), [示例代码与最佳实践](#page-10)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [environment_tests/README.md](https://github.com/langchain-ai/langchainjs/blob/main/environment_tests/README.md)\n- [environment_tests/docker-compose.yml](https://github.com/langchain-ai/langchainjs/blob/main/environment_tests/docker-compose.yml)\n- [environment_tests/test-exports-bun/src/entrypoints.js](https://github.com/langchain-ai/langchainjs/blob/main/environment_tests/test-exports-bun/src/entrypoints.js)\n- [environment_tests/test-exports-cf/src/entrypoints.js](https://github.com/langchain-ai/langchainjs/blob/main/environment_tests/test-exports-cf/src/entrypoints.js)\n- [environment_tests/test-exports-vite/src/entrypoints.js](https://github.com/langchain-ai/langchainjs/blob/main/environment_tests/test-exports-vercel/src/entrypoints.js)\n- [libs/langchain-core/src/utils/signal.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-core/src/utils/signal.ts)\n
\n\n# 多环境部署支持\n\nLangChain.js 通过一套完整的多环境部署测试框架，确保核心库能够在不同的 JavaScript 运行时环境和构建工具中正确运行。该系统覆盖了从服务器端 Node.js 到边缘计算平台的多样化部署场景。\n\n## 概述与设计目标\n\nLangChain.js 的多环境部署支持旨在验证包的导出结构（exports）与目标运行时环境的兼容性。不同的部署环境对模块格式、异步处理和文件系统访问有着截然不同的要求，LangChain.js 通过自动化测试确保这些差异不会导致运行时错误。\n\n核心设计原则包括：\n\n- **环境无关性**：核心抽象层独立于特定运行时环境\n- **导出兼容性**：通过 `package.json` 的 `exports` 字段精细控制不同环境的入口点\n- **异步标准化**：统一 `AsyncLocalStorage` 和 `AbortSignal` 等跨环境 API 的行为\n\n资料来源：[libs/langchain-core/src/utils/signal.ts:1-50]()\n\n## 支持的部署环境\n\nLangChain.js 维护了一套针对主流运行时和构建工具的兼容性测试：\n\n| 环境类型 | 包名 | 用途说明 |\n|---------|------|---------|\n| Node.js | `@langchain/core` | 服务端默认环境，支持完整 Node.js API |\n| Bun | `test-exports-bun` | Bun 运行时兼容性测试 |\n| Cloudflare Workers | `test-exports-cf` | 边缘计算环境测试 |\n| Vercel Edge Functions | `test-exports-vercel` | Vercel 边缘函数环境测试 |\n| Vite | `test-exports-vite` | 前端构建工具兼容性测试 |\n\n资料来源：[environment_tests/README.md]()\n资料来源：[environment_tests/test-exports-bun/src/entrypoints.js]()\n资料来源：[environment_tests/test-exports-cf/src/entrypoints.js]()\n\n## 测试框架架构\n\n### 目录结构\n\n```\nenvironment_tests/\n├── README.md # 测试框架说明文档\n├── docker-compose.yml # Docker 编排配置\n├── test-exports-bun/ # Bun 运行时测试\n│ └── src/\n│ └── entrypoints.js # 入口点导出验证\n├── test-exports-cf/ # Cloudflare Workers 测试\n│ └── src/\n│ └── entrypoints.js\n├── test-exports-vercel/ # Vercel Edge Functions 测试\n│ └── src/\n│ └── entrypoints.js\n└── test-exports-vite/ # Vite 构建工具测试\n └── src/\n └── entrypoints.js\n```\n\n资料来源：[environment_tests/docker-compose.yml]()\n\n### 测试流程\n\n```mermaid\ngraph TD\n A[开始测试] --> B[加载 Docker Compose 配置]\n B --> C{选择测试环境}\n C -->|Bun| D[运行 test-exports-bun]\n C -->|Cloudflare| E[运行 test-exports-cf]\n C -->|Vercel| F[运行 test-exports-vercel]\n C -->|Vite| G[运行 test-exports-vite]\n D --> H[验证入口点导出]\n E --> H\n F --> H\n G --> H\n H --> I{所有测试通过?}\n I -->|是| J[测试成功]\n I -->|否| K[报告环境兼容性问题]\n```\n\n## Docker 容器化测试环境\n\nLangChain.js 使用 Docker Compose 管理多环境测试容器，确保测试环境的一致性和可重复性。\n\n### 服务配置\n\n测试框架定义了多个服务容器，每个容器运行特定的运行时环境：\n\n- **基础镜像选择**：针对不同运行环境选择合适的基础镜像\n- **依赖安装**：在容器启动时安装项目依赖\n- **测试执行**：运行入口点验证脚本\n\n资料来源：[environment_tests/docker-compose.yml]()\n\n## 核心导出机制\n\n### package.json exports 字段\n\nLangChain.js 通过 `package.json` 的 `exports` 字段实现条件导出，为不同环境提供定制化的模块入口：\n\n```javascript\n// 条件导出的典型配置\n{\n \"exports\": {\n \".\": {\n \"types\": \"./dist/index.d.ts\",\n \"import\": \"./dist/index.js\",\n \"require\": \"./dist/index.cjs\",\n \"default\": \"./dist/index.js\"\n },\n \"./utils\": {\n \"types\": \"./dist/utils.d.ts\",\n \"import\": \"./dist/utils.js\"\n }\n }\n}\n```\n\n资料来源：[libs/langchain-core/package.json:1-30]()\n\n### 入口点验证\n\n每个环境测试包包含一个 `entrypoints.js` 文件，用于验证关键导出是否正确可用：\n\n```javascript\n// test-exports-bun/src/entrypoints.js 示例\nexport * from \"@langchain/core\";\n// 验证核心导出在 Bun 环境中可访问\n```\n\n资料来源：[environment_tests/test-exports-bun/src/entrypoints.js]()\n\n## 异步与信号处理\n\nLangChain.js 的核心模块实现了跨环境兼容的异步处理机制，这对于在边缘计算环境中运行至关重要。\n\n### AbortSignal 支持\n\n核心模块支持标准的 `AbortSignal` 接口，允许调用者取消异步操作：\n\n```typescript\n// libs/langchain-core/src/utils/signal.ts\nexport interface AbortSignalLike {\n readonly aborted: boolean;\n addEventListener: (type: \"abort\", listener: () => void) => void;\n removeEventListener: (type: \"abort\", listener: () => void) => void;\n}\n```\n\n资料来源：[libs/langchain-core/src/utils/signal.ts:1-30]()\n\n### AsyncLocalStorage 适配\n\n在不支持 `AsyncLocalStorage` 的环境中（如某些边缘运行时），LangChain.js 提供了优雅的降级处理机制，确保核心功能不受影响。\n\n## 边缘计算环境特殊考虑\n\n### Cloudflare Workers\n\nCloudflare Workers 环境对代码有以下限制：\n\n| 限制类型 | 说明 | 处理方式 |\n|---------|------|---------|\n| 文件系统 | 仅支持 KV 和 R2 存储 | 使用抽象层访问存储 |\n| 运行时 | V8 isolates，无 Node.js API | 使用 web 标准 API |\n| 启动时间 | 需极快初始化 | 懒加载非关键模块 |\n\n资料来源：[environment_tests/test-exports-cf/src/entrypoints.js]()\n\n### Vercel Edge Functions\n\nVercel Edge Functions 运行在 V8 isolates 上，与 Cloudflare Workers 类似需要避免使用 Node.js 特定 API。\n\n## 开发工作流\n\n### 本地测试\n\n开发者可以使用以下命令在本地运行多环境测试：\n\n```bash\n# 启动所有测试环境容器\ndocker-compose up\n\n# 运行特定环境测试\npnpm --filter test-exports-bun test\npnpm --filter test-exports-cf test\n```\n\n### CI/CD 集成\n\n多环境测试通常集成到持续集成流程中，确保每次代码变更不会破坏特定环境的兼容性：\n\n1. 检出代码\n2. 安装依赖\n3. 构建核心包\n4. 运行各环境测试\n5. 收集并报告结果\n\n## 最佳实践\n\n### 包开发者指南\n\n1. **避免 Node.js 特定 API**：使用 web 标准 API 或条件导入\n2. **使用条件导出**：在 `package.json` 中正确配置 `exports` 字段\n3. **测试所有目标环境**：在开发周期早期发现问题\n4. **处理缺失的全局对象**：如 `AsyncLocalStorage` 不可用时的降级方案\n\n### 环境检测模式\n\n```typescript\n// 检测当前环境类型\nconst isEdge = typeof EdgeRuntime !== \"undefined\";\nconst isNode = typeof process !== \"undefined\" && process.versions?.node;\nconst isBrowser = typeof window !== \"undefined\";\n```\n\n## 相关资源\n\n- [LangChain.js 主仓库](https://github.com/langchain-ai/langchainjs)\n- [@langchain/core 核心包](https://github.com/langchain-ai/langchainjs/tree/main/libs/langchain-core)\n- [环境测试框架](https://github.com/langchain-ai/langchainjs/tree/main/environment_tests)\n\n---\n\n\n\n## 依赖管理与测试策略\n\n### 相关页面\n\n相关主题：[多环境部署支持](#page-7), [扩展开发指南](#page-9)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [package.json](https://github.com/langchain-ai/langchainjs/blob/main/package.json)\n- [pnpm-workspace.yaml](https://github.com/langchain-ai/langchainjs/blob/main/pnpm-workspace.yaml)\n- [internal/standard-tests/src/index.ts](https://github.com/langchain-ai/langchainjs/blob/main/internal/standard-tests/src/index.ts)\n- [dependency_range_tests/docker-compose.yml](https://github.com/langchain-ai/langchainjs/blob/main/dependency_range_tests/docker-compose.yml)\n- [dependency_range_tests/scripts/langchain/node/update_resolutions_latest.js](https://github.com/langchain-ai/langchainjs/blob/main/dependency_range_tests/scripts/langchain/node/update_resolutions_latest.js)\n
\n\n# 依赖管理与测试策略\n\n## 概述\n\nLangChain.js 是一个采用 monorepo 架构的 TypeScript 项目，使用 pnpm workspaces 进行依赖管理，并通过多层次的测试策略确保代码质量。依赖管理策略涵盖了版本控制、依赖范围测试和标准化测试，而测试策略则包括单元测试、集成测试、标准单元测试和标准集成测试等多种测试模式。\n\n该项目的依赖管理核心目标是确保所有 `@langchain/*` 包共享相同版本的 `@langchain/core`，避免因核心库版本不一致导致的兼容性问题。资料来源：[libs/langchain-core/package.json](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-core/package.json)()\n\n## Monorepo 架构\n\n### 工作区结构\n\nLangChain.js 使用 pnpm workspaces 管理多包工作区，所有包位于 `libs/` 目录下。资料来源：[pnpm-workspace.yaml](https://github.com/langchain-ai/langchainjs/blob/main/pnpm-workspace.yaml)()\n\n```mermaid\ngraph TD\n A[langchainjs Root] --> B[pnpm-workspace.yaml]\n A --> C[package.json]\n A --> D[libs/]\n \n D --> E[langchain-core]\n D --> F[langchain-classic]\n D --> G[langchain-textsplitters]\n D --> H[providers/]\n D --> I[community/]\n \n H --> H1[langchain-anthropic]\n H --> H2[langchain-aws]\n H --> H3[langchain-cohere]\n H --> H4[langchain-xai]\n H --> H5[langchain-mistralai]\n H --> H6[langchain-tavily]\n```\n\n### 包类型分类\n\n| 目录 | 包类型 | 说明 |\n|------|--------|------|\n| `libs/langchain-core` | 核心包 | 包含 LangChain.js 的核心抽象和模式定义 |\n| `libs/langchain-classic` | 兼容性包 | 包含从 v0.x 迁移的遗留链和功能 |\n| `libs/langchain-textsplitters` | 工具包 | 文本分割器实现 |\n| `libs/providers/*` | 集成包 | 各第三方服务提供商集成 |\n| `libs/community/*` | 社区包 | 社区维护的集成 |\n| `internal/standard-tests` | 内部工具 | 标准化测试框架 |\n\n## 依赖管理策略\n\n### 核心依赖一致性\n\nLangChain.js 要求所有包共享同一个 `@langchain/core` 实例。核心库采用 tilde 依赖版本策略，确保向后兼容性。资料来源：[libs/langchain-core/README.md](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-core/README.md)()\n\n```json\n{\n \"peerDependencies\": {\n \"@langchain/core\": \"~0.3.0\"\n },\n \"devDependencies\": {\n \"@langchain/core\": \"~0.3.0\"\n }\n}\n```\n\n### 依赖覆盖机制\n\n项目推荐在用户项目的 `package.json` 中添加依赖覆盖配置，以强制所有包使用相同版本的核心库：\n\n```mermaid\ngraph LR\n A[用户项目] --> B[dependencies]\n A --> C[resolutions]\n A --> D[overrides]\n A --> E[pnpm.overrides]\n \n B --> F[@langchain/core]\n B --> G[@langchain/anthropic]\n B --> H[@langchain/cohere]\n \n C --> F\n D --> F\n E --> F\n```\n\n支持的包管理器及其覆盖字段：\n\n| 包管理器 | 配置字段 | 示例 |\n|----------|----------|------|\n| npm/yarn | `resolutions` | `\"@langchain/core\": \"^0.3.0\"` |\n| npm/yarn | `overrides` | `\"@langchain/core\": \"^0.3.0\"` |\n| pnpm | `pnpm.overrides` | `\"@langchain/core\": \"^0.3.0\"` |\n\n资料来源：[libs/providers/langchain-anthropic/README.md](https://github.com/langchain-ai/langchainjs/blob/main/libs/providers/langchain-anthropic/README.md)()\n\n### 依赖范围测试\n\n项目通过 Docker 环境测试不同依赖版本组合的兼容性，确保包在依赖版本变化时仍能正常工作。\n\n#### Docker 测试环境配置\n\n依赖范围测试使用 Docker Compose 定义测试环境：\n\n```yaml\nservices:\n test:\n build:\n context: .\n dockerfile: Dockerfile\n volumes:\n - .:/app\n environment:\n - NODE_ENV=test\n command: pnpm test:ranges\n```\n\n资料来源：[dependency_range_tests/docker-compose.yml](https://github.com/langchain-ai/langchainjs/blob/main/dependency_range_tests/docker-compose.yml)()\n\n#### 自动更新依赖脚本\n\n项目提供脚本自动更新依赖到最新版本：\n\n```javascript\n// update_resolutions_latest.js\nasync function updateResolutions() {\n // 获取 @langchain/core 最新版本\n const latestCore = await getLatestVersion(\"@langchain/core\");\n \n // 更新所有包的 resolutions\n await updateWorkspaceResolutions(latestCore);\n}\n```\n\n该脚本遍历工作区中的所有包，将 `@langchain/core` 依赖更新到最新版本，验证兼容性后提交更改。资料来源：[dependency_range_tests/scripts/langchain/node/update_resolutions_latest.js](https://github.com/langchain-ai/langchainjs/blob/main/dependency_range_tests/scripts/langchain/node/update_resolutions_latest.js)()\n\n## 测试策略\n\n### 测试类型概览\n\nLangChain.js 采用多层次的测试策略，确保代码质量和向后兼容性：\n\n```mermaid\ngraph TD\n A[测试策略] --> B[单元测试]\n A --> C[集成测试]\n A --> D[标准测试]\n A --> E[导出测试]\n A --> F[依赖范围测试]\n \n B --> B1[vitest run]\n C --> C1[vitest run --mode int]\n D --> D1[standard-unit]\n D --> D2[standard-int]\n E --> E1[test:exports:docker]\n F --> F1[test:ranges:docker]\n```\n\n资料来源：[package.json](https://github.com/langchain-ai/langchainjs/blob/main/package.json)()\n\n### 单元测试\n\n单元测试使用 Vitest 框架运行，每个包在 `src/` 目录下包含 `tests/` 文件夹：\n\n| 测试类型 | 文件后缀 | 运行命令 |\n|----------|----------|----------|\n| 单元测试 | `.test.ts` | `vitest run` |\n| 集成测试 | `.int.test.ts` | `vitest run --mode int` |\n| 监视模式 | - | `vitest` 或 `vitest --watch` |\n\n```bash\n# 运行单元测试\npnpm test\n\n# 运行集成测试\npnpm test:int\n\n# 监视模式运行\npnpm test:watch\n```\n\n资料来源：[libs/langchain-core/package.json](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-core/package.json)()\n\n### 标准测试框架\n\n`@langchain/standard-tests` 是项目内部的标准化测试框架，为所有 LangChain 包提供一致的测试接口。资料来源：[internal/standard-tests/src/index.ts](https://github.com/langchain-ai/langchainjs/blob/main/internal/standard-tests/src/index.ts)()\n\n#### 标准测试模块结构\n\n```mermaid\nclassDiagram\n class StandardTests {\n +runUnitTests()\n +runIntegrationTests()\n +runChatModelTests()\n +runEmbeddingsTests()\n +runVectorStoreTests()\n }\n \n class UnitTestRunner {\n +run()\n +validateOutput()\n }\n \n class IntegrationTestRunner {\n +run()\n +setupFixtures()\n +teardown()\n }\n \n StandardTests --> UnitTestRunner\n StandardTests --> IntegrationTestRunner\n```\n\n#### 测试模式\n\n| 模式 | 命令 | 说明 |\n|------|------|------|\n| 标准单元测试 | `test:standard:unit` | 使用标准测试框架的单元测试 |\n| 标准集成测试 | `test:standard:int` | 使用标准测试框架的集成测试 |\n| 完整标准测试 | `test:standard` | 运行所有标准测试 |\n\n```bash\n# 运行标准测试\npnpm test:standard:unit\npnpm test:standard:int\npnpm test:standard\n```\n\n资料来源：[package.json](https://github.com/langchain-ai/langchainjs/blob/main/package.json)()\n\n### 导出兼容性测试\n\n导出测试验证包的导出接口在不同环境（ESM/CJS）下的兼容性：\n\n```mermaid\ngraph LR\n A[导出测试] --> B[ESM环境]\n A --> C[CJS环境]\n A --> D[Docker容器]\n \n B --> E[import测试]\n C --> F[require测试]\n D --> G[跨环境验证]\n```\n\n使用 Docker 环境进行导出测试：\n\n```bash\npnpm test:exports:docker\n```\n\n资料来源：[package.json](https://github.com/langchain-ai/langchainjs/blob/main/package.json)()\n\n### 依赖范围测试\n\n依赖范围测试验证包在不同核心库版本下的行为：\n\n```mermaid\ngraph TD\n A[依赖范围测试] --> B[Docker环境]\n A --> C[版本矩阵]\n A --> D[兼容性验证]\n \n C --> C1[@langchain/core ^0.2.0]\n C --> C2[@langchain/core ^0.3.0]\n C --> C3[@langchain/core latest]\n \n D --> D1[API兼容性]\n D --> D2[类型检查]\n D --> D3[运行时测试]\n```\n\n运行依赖范围测试：\n\n```bash\npnpm test:ranges:docker\n```\n\n资料来源：[package.json](https://github.com/langchain-ai/langchainjs/blob/main/package.json)()\n\n## CI/CD 集成\n\n### Turbo 构建系统\n\n项目使用 Turbo 进行构建和测试编排：\n\n```json\n{\n \"scripts\": {\n \"test:unit:ci\": \"turbo test\",\n \"build\": \"turbo build\"\n }\n}\n```\n\nTurbo 的优势：\n\n| 特性 | 说明 |\n|------|------|\n| 增量构建 | 仅重新构建变更的包 |\n| 并行执行 | 充分利用多核 CPU |\n| 远程缓存 | 共享 CI 缓存 |\n| 任务管道 | 自动解析任务依赖 |\n\n资料来源：[package.json](https://github.com/langchain-ai/langchainjs/blob/main/package.json)()\n\n### 过滤规则\n\nCI 配置使用过滤器排除不需要测试的包：\n\n```bash\n# 排除导出测试、示例和创建集成模板\npnpm test:unit:ci --filter=\"!test-exports-*\" --filter=\"!examples\" --filter=\"!create-langchain-integration\"\n```\n\n## 包开发指南\n\n### 创建新集成包\n\n项目提供了集成包模板 `create-langchain-integration`，开发者可以使用该模板快速创建新的提供商集成。资料来源：[libs/create-langchain-integration/template/README.md](https://github.com/langchain-ai/langchainjs/blob/main/libs/create-langchain-integration/template/README.md)()\n\n新包开发流程：\n\n1. 使用模板创建包结构\n2. 添加 `@langchain/core` 为 peer dependency 和 dev dependency\n3. 实现集成代码\n4. 添加单元测试和集成测试\n5. 运行标准测试验证\n6. 提交更改\n\n### 包配置示例\n\n```json\n{\n \"name\": \"@langchain/example-provider\",\n \"version\": \"0.0.1\",\n \"type\": \"module\",\n \"dependencies\": {\n \"@example/sdk\": \"^1.0.0\"\n },\n \"peerDependencies\": {\n \"@langchain/core\": \"~0.3.0\"\n },\n \"devDependencies\": {\n \"@langchain/core\": \"~0.3.0\"\n }\n}\n```\n\n## 最佳实践\n\n### 依赖管理\n\n| 实践 | 说明 |\n|------|------|\n| 使用 peerDependencies | 声明运行时依赖，让消费者提供核心库 |\n| 使用 devDependencies | 仅开发时需要的依赖 |\n| 避免直接依赖 | 集成包不应直接依赖其他 `@langchain/*` 包 |\n| 版本一致性 | 确保所有包使用相同版本的 `@langchain/core` |\n\n### 测试覆盖\n\n| 测试类型 | 覆盖率目标 | 运行频率 |\n|----------|------------|----------|\n| 单元测试 | 80%+ | 每次提交 |\n| 集成测试 | 核心功能全覆盖 | 每次 PR |\n| 标准测试 | 所有包必须通过 | 发布前 |\n| 导出测试 | ESM/CJS 双环境 | 发布前 |\n| 依赖范围测试 | 主流版本组合 | 每周 |\n\n### 构建验证\n\n在发布包之前，确保完成以下验证步骤：\n\n```mermaid\ngraph LR\n A[代码编写] --> B[单元测试]\n B --> C[集成测试]\n C --> D[标准测试]\n D --> E[导出测试]\n E --> F[依赖范围测试]\n F --> G[发布]\n\n---\n\n\n\n## 扩展开发指南\n\n### 相关页面\n\n相关主题：[扩展提供商与工具集成](#page-6), [示例代码与最佳实践](#page-10)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [libs/create-langchain-integration/create-app.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/create-langchain-integration/create-app.ts)\n- [libs/create-langchain-integration/template/package.json](https://github.com/langchain-ai/langchainjs/blob/main/libs/create-langchain-integration/template/package.json)\n- [CONTRIBUTING.md](https://github.com/langchain-ai/langchainjs/blob/main/CONTRIBUTING.md)\n- [libs/langchain-mcp-adapters/src/client.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-mcp-adapters/src/client.ts)\n- [libs/langchain-mcp-adapters/src/tools.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-mcp-adapters/src/tools.ts)\n- [libs/langchain-core/README.md](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-core/README.md)\n- [libs/providers/langchain-anthropic/README.md](https://github.com/langchain-ai/langchainjs/blob/main/libs/providers/langchain-anthropic/README.md)\n- [libs/langchain-textsplitters/README.md](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-textsplitters/README.md)\n
\n\n# 扩展开发指南\n\nLangChain.js 采用模块化架构设计，支持开发者通过扩展机制集成第三方服务和功能。本指南涵盖创建新的集成包、扩展现有功能以及贡献代码的完整流程。\n\n## 概述\n\nLangChain.js 的扩展开发体系包含以下核心组件：\n\n| 组件类型 | 说明 | 位置 |\n|---------|------|------|\n| 集成包 | 特定服务商的 SDK 封装（如 Anthropic、AWS、Cohere） | `libs/providers/` |\n| 核心扩展 | 文本分割器、工具适配器等核心功能 | `libs/langchain-*` |\n| MCP 适配器 | Model Context Protocol 工具集成 | `libs/langchain-mcp-adapters/` |\n| 社区扩展 | 社区贡献的集成 | `libs/community/` |\n\n## 项目结构\n\nLangChain.js 使用 pnpm monorepo 管理所有包，每个扩展包遵循统一的目录结构：\n\n```\nlibs/\n├── create-langchain-integration/ # 集成创建脚手架\n│ ├── create-app.ts # CLI 入口\n│ └── template/ # 包模板目录\n│ └── package.json # 模板 package.json\n├── providers/ # 官方提供商集成\n│ ├── langchain-anthropic/\n│ ├── langchain-aws/\n│ └── langchain-cohere/\n├── langchain-core/ # 核心抽象层\n├── langchain-textsplitters/ # 文本分割实现\n└── langchain-mcp-adapters/ # MCP 协议适配器\n```\n\n## 创建新集成包\n\n### 使用脚手架工具\n\nLangChain.js 提供了自动化工具来生成新的集成包骨架：\n\n```bash\npnpm create @langchain/integration \n```\n\n该命令调用 `create-app.ts` 中的逻辑，生成符合规范的包结构。脚手架会自动配置：\n\n- TypeScript 编译配置\n- 包名命名规范（`@langchain/`）\n- 依赖版本锁定策略\n\n### 包模板结构\n\n生成的模板包含以下关键文件：\n\n| 文件路径 | 用途 |\n|---------|------|\n| `package.json` | 包元数据、脚本、依赖声明 |\n| `README.md` | 安装和使用文档 |\n| `src/index.ts` | 包导出入口 |\n| `src/.ts` | 主要功能实现 |\n\n### package.json 配置要求\n\n集成包的 `package.json` 必须遵循以下配置规范：\n\n```json\n{\n \"name\": \"@langchain/\",\n \"version\": \"0.0.1\",\n \"type\": \"module\",\n \"dependencies\": {\n \"\": \"^\"\n },\n \"peerDependencies\": {\n \"@langchain/core\": \"^1.0.0\"\n },\n \"devDependencies\": {\n \"@langchain/core\": \"workspace:^\"\n }\n}\n```\n\n**关键配置说明：**\n\n| 字段 | 要求 | 说明 |\n|-----|------|------|\n| `type` | 必须为 `\"module\"` | ESM 模块支持 |\n| `peerDependencies` | 必须包含 `@langchain/core` | 运行时依赖核心包 |\n| `devDependencies` | 建议使用 `workspace:^` | 开发时引用本地 core |\n\n资料来源：[libs/create-langchain-integration/template/package.json](https://github.com/langchain-ai/langchainjs/blob/main/libs/create-langchain-integration/template/package.json)\n\n## 依赖管理策略\n\n### @langchain/core 版本锁定\n\n为确保所有 LangChain 包使用相同版本的 `@langchain/core`，需要在项目根目录的 `package.json` 中添加版本覆盖配置：\n\n```json\n{\n \"resolutions\": {\n \"@langchain/core\": \"^0.3.0\"\n },\n \"overrides\": {\n \"@langchain/core\": \"^0.3.0\"\n },\n \"pnpm\": {\n \"overrides\": {\n \"@langchain/core\": \"^0.3.0\"\n }\n }\n}\n```\n\n资料来源：[libs/providers/langchain-anthropic/README.md](https://github.com/langchain-ai/langchainjs/blob/main/libs/providers/langchain-anthropic/README.md)\n\n## MCP 适配器开发\n\nModel Context Protocol (MCP) 适配器允许 LangChain 与外部 MCP 服务器通信，访问其提供的工具。\n\n### 客户端架构\n\n```mermaid\ngraph TD\n A[LangChain Agent] --> B[MCPClient]\n B --> C[MCP Server]\n C --> D[Remote Tools]\n B --> E[MCPTools]\n E --> A\n```\n\n### 核心组件\n\n**MCPTools 类** 提供 MCP 工具到 LangChain 工具的转换：\n\n```typescript\n// 将 MCP 工具适配为 LangChain 可用格式\nexport class MCPTools {\n constructor(\n private client: MCPClient,\n private toolNames?: string[]\n ) {}\n\n getTools(): Tool[] {\n // 返回适配后的工具列表\n }\n}\n```\n\n资料来源：[libs/langchain-mcp-adapters/src/tools.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-mcp-adapters/src/tools.ts)\n\n### 客户端初始化\n\n```typescript\nimport { MCPClient } from \"./client\";\n\nconst client = new MCPClient({\n name: \"my-mcp-client\",\n version: \"1.0.0\",\n command: \"npx\",\n args: [\"-y\", \"@modelcontextprotocol/server-filesystem\", \"./data\"]\n});\n```\n\n资料来源：[libs/langchain-mcp-adapters/src/client.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-mcp-adapters/src/client.ts)\n\n## 构建和测试\n\n### 构建脚本\n\n集成包应包含标准的构建和测试脚本：\n\n| 脚本 | 用途 |\n|-----|------|\n| `pnpm build` | 编译 TypeScript 生成 dist 目录 |\n| `pnpm test` | 运行单元测试 |\n| `pnpm test:int` | 运行集成测试 |\n| `pnpm lint` | 代码风格检查 |\n| `pnpm format` | 代码格式化 |\n\n### 构建流程\n\nLangChain.js 使用 `turbo` 作为构建编排工具：\n\n```bash\npnpm build --filter @langchain/\n```\n\n单包构建命令：\n\n```bash\ncd libs/providers/langchain-anthropic\npnpm build\n```\n\n### 测试规范\n\n- 单元测试文件命名：`.test.ts`\n- 集成测试文件命名：`.int.test.ts`\n- 测试文件位置：`src/tests/` 或根目录 `tests/`\n\n资料来源：[libs/langchain-textsplitters/README.md](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-textsplitters/README.md)\n\n## 贡献代码\n\n### 贡献流程\n\n```mermaid\ngraph LR\n A[Fork 仓库] --> B[创建功能分支]\n B --> C[开发实现]\n C --> D[编写测试]\n D --> E[提交 Pull Request]\n E --> F[Code Review]\n F --> G[合并到主分支]\n```\n\n### 代码规范\n\n- 遵循 TypeScript 最佳实践\n- 使用 ESLint 进行代码检查\n- 使用 Prettier 进行代码格式化\n- 确保所有新功能包含测试覆盖\n\n### 提交规范\n\n```bash\npnpm lint && pnpm format\n```\n\n运行提交前的检查：\n\n```bash\npnpm lint:eslint && pnpm lint:dpdm\n```\n\n`dpdm` 工具检查动态导入的循环依赖问题。\n\n资料来源：[CONTRIBUTING.md](https://github.com/langchain-ai/langchainjs/blob/main/CONTRIBUTING.md)\n\n## 包导出配置\n\n### package.json exports 字段\n\n新包应配置 `exports` 字段以支持按需导入：\n\n```json\n{\n \"exports\": {\n \".\": {\n \"import\": \"./dist/index.js\",\n \"types\": \"./dist/index.d.ts\"\n },\n \"./\": {\n \"import\": \"./dist/.js\",\n \"types\": \"./dist/.d.ts\"\n }\n }\n}\n```\n\n添加新导出后，需要执行 `pnpm build` 重新生成入口文件。\n\n资料来源：[libs/langchain-textsplitters/README.md](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-textsplitters/README.md)\n\n## 最佳实践\n\n### 1. 版本兼容性\n\n- 使用 `~` 而非 `^` 来锁定 `@langchain/core` 依赖\n- 允许补丁版本更新，限制次版本兼容性\n\n```json\n\"peerDependencies\": {\n \"@langchain/core\": \"~0.3.0\"\n}\n```\n\n### 2. ESM 和 CJS 兼容\n\n构建步骤应生成兼容两种模块系统的代码。使用 `tsdown` 进行编译：\n\n```bash\ntsdown src/index.ts --dts\n```\n\n### 3. 文档编写\n\n每个集成包应包含 README.md，包含：\n\n- 安装说明\n- 环境变量配置\n- 基本使用示例\n- API 参考链接\n\n### 4. 类型安全\n\n- 导出完整的 TypeScript 类型定义\n- 使用 Zod 进行运行时验证\n- 避免使用 `any` 类型\n\n## 扩展包注册表\n\n| 包类型 | 命名空间 | 示例 |\n|-------|---------|------|\n| 官方提供商 | `@langchain/` | `@langchain/anthropic`, `@langchain/cohere` |\n| 核心功能 | `@langchain/` | `@langchain/textsplitters`, `@langchain/core` |\n| 社区包 | `@langchain/community` | 社区维护的集成 |\n| MCP 适配器 | `@langchain/mcp-adapters` | MCP 协议支持 |\n\n## 常见问题\n\n**Q: 如何为现有包添加新功能？**\n\n在 `src/` 目录创建新文件，然后在 `src/index.ts` 中导出。修改后运行 `pnpm build` 更新构建产物。\n\n**Q: 如何测试包之间的依赖关系？**\n\n使用 `pnpm why ` 检查依赖树，确保没有意外的版本冲突。\n\n**Q: MCP 适配器支持哪些 MCP 服务器？**\n\n理论上支持所有符合 MCP 协议规范的服务器，包括文件操作、数据库访问、API 调用等类型。\n\n---\n\n\n\n## 示例代码与最佳实践\n\n### 相关页面\n\n相关主题：[Agent 与 Chains 实现](#page-3), [扩展开发指南](#page-9)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [libs/langchain-textsplitters/README.md](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-textsplitters/README.md)\n- [libs/langchain/src/agents/middleware/hitl.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain/src/agents/middleware/hitl.ts)\n- [libs/langchain/src/agents/utils.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain/src/agents/utils.ts)\n- [libs/providers/langchain-anthropic/src/chat_models.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/providers/langchain-anthropic/src/chat_models.ts)\n- [libs/providers/langchain-openai/src/chat_models/index.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/providers/langchain-openai/src/chat_models/index.ts)\n- [libs/langchain-core/src/language_models/event.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-core/src/language_models/event.ts)\n
\n\n# 示例代码与最佳实践\n\n本页面汇集了 LangChain.js 框架的核心示例代码和最佳实践指南，涵盖文本分割、代理中间件、聊天模型集成、事件处理等关键功能模块。通过这些示例，开发者可以快速掌握如何在实际项目中应用 LangChain.js 构建 LLM 驱动的应用程序。\n\n## 核心功能概览\n\nLangChain.js 提供了丰富的功能模块，帮助开发者构建模块化、可组合的 LLM 应用程序。以下表格总结了主要功能模块及其用途：\n\n| 功能模块 | 包名 | 主要用途 |\n|---------|------|---------|\n| 文本分割 | `@langchain/textsplitters` | 将长文档分割成适合处理的块 |\n| 代理中间件 | `langchain/agents` | 为代理添加人机交互、监控等能力 |\n| 聊天模型 | `@langchain/anthropic`, `@langchain/openai` | 与各种 LLM 提供商集成 |\n| 事件系统 | `@langchain/core` | 处理流式输出和状态更新 |\n| 工具系统 | `@langchain/core/tools` | 定义和执行 LLM 工具调用 |\n\n## 文本分割器使用指南\n\n文本分割是 RAG（检索增强生成）流水线中的关键步骤。LangChain.js 提供了多种文本分割器实现，最常用的是 `RecursiveCharacterTextSplitter`。\n\n### HTML 文档分割示例\n\n以下示例展示了如何分割 HTML 文档：\n\n```typescript\nimport { RecursiveCharacterTextSplitter } from \"@langchain/textsplitters\";\n\nconst text = `\n\n \n 🦜️🔗 LangChain\n \n \n \n
\n

🦜️🔗 LangChain

\n

⚡ Building applications with LLMs through composability ⚡

\n
\n \n`;\n\nconst splitter = RecursiveCharacterTextSplitter.fromLanguage(\"html\", {\n chunkSize: 175,\n chunkOverlap: 20,\n});\nconst output = await splitter.createDocuments([text]);\n```\n\n资料来源：[examples/src/langchain-classic/indexes/html_text_splitter.ts:1-28]()\n\n### 分割器配置参数\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `chunkSize` | number | 每个文本块的最大字符数 |\n| `chunkOverlap` | number | 相邻块之间的重叠字符数 |\n| `separators` | string[] | 分割符列表，按优先级排序 |\n\n### 开发与测试\n\n`@langchain/textsplitters` 包的开发流程如下：\n\n```bash\n# 安装依赖\npnpm install\n\n# 构建包\npnpm build\n# 或从仓库根目录\npnpm build --filter @langchain/textsplitters\n\n# 运行测试\npnpm test # 单元测试\npnpm test:int # 集成测试\n```\n\n资料来源：[libs/langchain-textsplitters/README.md](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-textsplitters/README.md)\n\n## 代理中间件系统\n\nLangChain.js 的代理系统支持中间件扩展，允许开发者在代理执行过程中插入自定义逻辑。\n\n### 中间件状态解析\n\n代理中间件使用状态模式管理状态架构，支持两种主要类型：\n\n```typescript\nfunction parseMiddlewareState(\n stateSchema: unknown,\n state: Record\n): Record {\n // 处理 LangGraph StateSchema（具有 fields 属性）\n if (StateSchema.isInstance(stateSchema)) {\n const result: Record = {};\n for (const key of Object.keys(stateSchema.fields)) {\n if (key in state) {\n result[key] = state[key];\n }\n }\n return result;\n }\n\n // 使用 interopParse 处理 Zod schemas\n if (isInteropZodSchema(stateSchema)) {\n return interopParse(stateSchema as InteropZodObject, state);\n }\n\n throw new Error(`Invalid state schema type: ${typeof stateSchema}`);\n}\n```\n\n资料来源：[libs/langchain/src/agents/utils.ts:1-40]()\n\n### HITL 中断配置\n\n人机交互（HITL）中间件提供了精细的中断控制能力：\n\n```typescript\nexport interface InterruptOnConfig {\n /**\n * 允许的决策列表\n */\n allowedDecisions?: string[];\n /**\n * 动态可调用描述\n */\n description?: z.union([z.string(), DescriptionFunctionSchema]).optional();\n /**\n * 如果允许编辑，则关联参数的 JSON schema\n */\n argsSchema?: z.record(z.any()).optional();\n}\n```\n\n资料来源：[libs/langchain/src/agents/middleware/hitl.ts:1-50]()\n\n### 中间件架构流程\n\n```mermaid\ngraph TD\n A[用户输入] --> B[代理处理器]\n B --> C{检查中间件}\n C -->|存在 HITL| D[显示工具调用信息]\n C -->|其他中间件| E[执行中间件逻辑]\n D --> F[等待用户批准/编辑]\n E --> G[继续执行]\n F --> G\n G --> H[返回结果]\n```\n\n### 动态工具描述示例\n\n```typescript\nimport type {\n AgentBuiltInState,\n Runtime,\n DescriptionFactory,\n ToolCall,\n InterruptOnConfig\n} from \"langchain\";\n\nconst formatToolDescription: DescriptionFactory = (\n toolCall: ToolCall,\n state: AgentBuiltInState,\n runtime: Runtime\n) => {\n return `Tool: ${toolCall.name}\\nArguments:\\n${JSON.stringify(toolCall.args, null, 2)}`;\n};\n\nconst config: InterruptOnConfig = {\n allowedDecisions: [\"approve\", \"edit\"],\n description: formatToolDescription\n};\n```\n\n## 聊天模型集成\n\nLangChain.js 提供了统一的接口来集成多种聊天模型提供商。\n\n### Anthropic 模型\n\n`ChatAnthropicMessages` 类扩展了基础聊天模型，支持完整的 Anthropic API 功能：\n\n```typescript\nexport class ChatAnthropicMessages<\n CallOptions extends ChatAnthropicCallOptions = ChatAnthropicCallOptions,\n>\n extends BaseChatModel\n implements AnthropicInput\n{\n static lc_name() {\n return \"ChatAnthropic\";\n }\n\n get lc_secrets(): { [key: string]: string } | undefined {\n return {\n anthropicApiKey: \"ANTHROPIC_API_KEY\",\n apiKey: \"ANTHROPIC_API_KEY\",\n };\n }\n}\n```\n\n资料来源：[libs/providers/langchain-anthropic/src/chat_models.ts:1-30]()\n\n### OpenAI 模型\n\nOpenAI 聊天模型同样提供了流式输出和完整响应支持：\n\n```typescript\nfor await (const chunk of await llm.stream(input)) {\n console.log(chunk);\n}\n```\n\n输出示例：\n\n```txt\nAIMessageChunk {\n \"id\": \"chatcmpl-9u4NWB7yUeHCKdLr6jP3HpaOYHTqs\",\n \"content\": \"\"\n}\nAIMessageChunk {\n \"content\": \"J\"\n}\nAIMessageChunk {\n \"content\": \"'adore\"\n}\n```\n\n资料来源：[libs/providers/langchain-openai/src/chat_models/index.ts:1-50]()\n\n### 工具调用与结构化输出\n\n聊天模型支持两种结构化输出方式：\n\n| 方式 | 说明 | 使用场景 |\n|------|------|---------|\n| `withStructuredOutput()` | 使用函数调用 | 需要严格约束输出格式 |\n| JSON Schema Mode | 使用原生 JSON schema | 直接结构化输出 |\n\n```typescript\nimport { tool } from \"@langchain/core/tools\";\nimport { z } from \"zod\";\n\nconst getWeather = tool(\n async (input) => `Weather in ${input.location}`,\n {\n name: \"get_weather\",\n description: \"Get weather for a location\",\n schema: z.object({ location: z.string() }),\n extras: { defer_loading: true },\n }\n);\n```\n\n## 事件系统\n\nLangChain.js 的事件系统用于追踪和响应语言模型运行时的状态变化。\n\n### 内容块事件\n\n```typescript\n/**\n * 内容块增量更新时触发\n */\nexport interface ContentBlockDeltaEvent {\n event: \"content-block-delta\";\n /** 正在更新的块的位置索引 */\n index: number;\n /** 增量内容块 */\n delta: ContentBlockDelta;\n}\n\n/**\n * 内容块完成时触发\n */\nexport interface ContentBlockFinishEvent {\n event: \"content-block-finish\";\n /** 完成的块的位置索引 */\n index: number;\n /** 最终内容块 */\n content: ContentBlock;\n}\n```\n\n资料来源：[libs/langchain-core/src/language_models/event.ts:1-30]()\n\n### 使用量事件\n\n```typescript\n/**\n * 提供商报告使用量更新时触发\n * 每个事件携带运行快照（非增量）\n */\nexport interface UsageUpdateEvent {\n event: \"usage\";\n /** 当前使用量快照 */\n usage: Partial;\n}\n```\n\n### 提供商事件\n\n```typescript\n/**\n * 用于原生提供商事件的透传\n */\nexport interface ProviderEvent {\n event: \"provider\";\n /** 提供商标识符 */\n provider: string;\n /** 来自提供商 SDK 的原始事件类型名 */\n name: string;\n /** 来自提供商 SDK 的原始事件载荷 */\n payload: unknown;\n}\n```\n\n### 事件处理流程\n\n```mermaid\ngraph LR\n A[流式调用] --> B[接收 AIMessageChunk]\n B --> C{检查事件类型}\n C -->|content-block-delta| D[更新文本内容]\n C -->|content-block-finish| E[标记块完成]\n C -->|usage| F[更新 token 统计]\n C -->|provider| G[透传原始事件]\n D --> H[累积完整响应]\n E --> H\n F --> H\n G --> H\n```\n\n### 聚合流式块\n\n```typescript\nimport { AIMessageChunk } from '@langchain/core/messages';\nimport { concat } from '@langchain/core/utils';\n\nlet fullForMetadata: AIMessageChunk | undefined;\nfor await (const chunk of await llm.stream(input)) {\n fullForMetadata = fullForMetadata\n ? concat(fullForMetadata, chunk)\n : chunk;\n}\nconsole.log(fullForMetadata?.usage_metadata);\n// 输出: { input_tokens: 25, output_tokens: 20, total_tokens: 45 }\n```\n\n## 包依赖管理最佳实践\n\n当在项目中使用多个 LangChain 包时，建议统一 `@langchain/core` 版本以避免兼容性问题：\n\n```json\n{\n \"name\": \"your-project\",\n \"version\": \"0.0.0\",\n \"dependencies\": {\n \"@langchain/anthropic\": \"^0.3.0\",\n \"@langchain/core\": \"^0.3.0\"\n },\n \"resolutions\": {\n \"@langchain/core\": \"^0.3.0\"\n },\n \"overrides\": {\n \"@langchain/core\": \"^0.3.0\"\n },\n \"pnpm\": {\n \"overrides\": {\n \"@langchain/core\": \"^0.3.0\"\n }\n }\n}\n```\n\n资料来源：[libs/create-langchain-integration/template/README.md](https://github.com/langchain-ai/langchainjs/blob/main/libs/create-langchain-integration/template/README.md)\n\n## 迁移与弃用处理\n\nLangChain.js 在演进过程中会迁移某些功能，开发者应注意弃用警告：\n\n```typescript\nif (\n getEnvironmentVariable(\"LANGCHAIN_SUPPRESS_MIGRATION_WARNINGS\") !== \"true\"\n) {\n console.warn(warningText);\n}\n```\n\n通过设置环境变量 `LANGCHAIN_SUPPRESS_MIGRATION_WARNINGS=true` 可以抑制迁移警告。\n\n资料来源：[libs/langchain-classic/src/util/entrypoint_deprecation.ts](https://github.com/langchain-ai/langchainjs/blob/main/libs/langchain-classic/src/util/entrypoint_deprecation.ts)\n\n## 常见模式总结\n\n| 模式 | 描述 | 适用场景 |\n|------|------|---------|\n| 链式调用 | 使用 `Runnable` 接口组合多个组件 | 数据处理流水线 |\n| 工具调用 | LLM 调用外部函数 | 需要获取外部数据 |\n| 流式处理 | 实时获取 LLM 输出 | 对话式应用 |\n| 中间件拦截 | 在代理执行中插入逻辑 | 监控、HITL |\n| 状态管理 | 使用 Zod 或 StateSchema | 结构化代理状态 |\n\n这些示例代码和最佳实践为开发者提供了构建生产级 LLM 应用的坚实基础。建议从简单的示例开始，逐步探索更高级的功能。\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：langchain-ai/langchainjs\n\n摘要：发现 10 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：配置坑 - 来源证据：[Feature request] React Native support。\n\n## 1. 配置坑 · 来源证据：[Feature request] React Native support\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[Feature request] React Native support\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_39933028ef894033b30ff784e81f185f | https://github.com/langchain-ai/langchainjs/issues/4239 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 2. 安装坑 · 来源证据：@langchain/core@1.1.46\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：@langchain/core@1.1.46\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_36a7a58d5cd84bda8dde7918402a6f8a | https://github.com/langchain-ai/langchainjs/releases/tag/%40langchain/core%401.1.46 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 3. 配置坑 · 来源证据：Must pass in at least 1 record to upsert.\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Must pass in at least 1 record to upsert.\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_26c3acaad9e14ed3953206f25870c0b0 | https://github.com/langchain-ai/langchainjs/issues/10890 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 4. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:598342280 | https://github.com/langchain-ai/langchainjs | README/documentation is current enough for a first validation pass.\n\n## 5. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:598342280 | https://github.com/langchain-ai/langchainjs | last_activity_observed missing\n\n## 6. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:598342280 | https://github.com/langchain-ai/langchainjs | no_demo; severity=medium\n\n## 7. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:598342280 | https://github.com/langchain-ai/langchainjs | no_demo; severity=medium\n\n## 8. 安全/权限坑 · 来源证据：bug(@langchain/openai): Bare JSON.parse in Responses API converter crashes on structured output with trailing characters\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：bug(@langchain/openai): Bare JSON.parse in Responses API converter crashes on structured output with trailing characters\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_4d2a6bed33284a3cbd2f3319321d9e4c | https://github.com/langchain-ai/langchainjs/issues/10894 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 9. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:598342280 | https://github.com/langchain-ai/langchainjs | issue_or_pr_quality=unknown\n\n## 10. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:598342280 | https://github.com/langchain-ai/langchainjs | release_recency=unknown\n\n\n", "summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。", "title": "Human Manual / 人类版说明书" }, "pitfall_log": { "asset_id": "pitfall_log", "filename": "PITFALL_LOG.md", "markdown": "# Pitfall Log / 踩坑日志\n\n项目：langchain-ai/langchainjs\n\n摘要：发现 10 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：配置坑 - 来源证据：[Feature request] React Native support。\n\n## 1. 配置坑 · 来源证据：[Feature request] React Native support\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[Feature request] React Native support\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_39933028ef894033b30ff784e81f185f | https://github.com/langchain-ai/langchainjs/issues/4239 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 2. 安装坑 · 来源证据：@langchain/core@1.1.46\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：@langchain/core@1.1.46\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_36a7a58d5cd84bda8dde7918402a6f8a | https://github.com/langchain-ai/langchainjs/releases/tag/%40langchain/core%401.1.46 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 3. 配置坑 · 来源证据：Must pass in at least 1 record to upsert.\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Must pass in at least 1 record to upsert.\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_26c3acaad9e14ed3953206f25870c0b0 | https://github.com/langchain-ai/langchainjs/issues/10890 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 4. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:598342280 | https://github.com/langchain-ai/langchainjs | README/documentation is current enough for a first validation pass.\n\n## 5. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:598342280 | https://github.com/langchain-ai/langchainjs | last_activity_observed missing\n\n## 6. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:598342280 | https://github.com/langchain-ai/langchainjs | no_demo; severity=medium\n\n## 7. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:598342280 | https://github.com/langchain-ai/langchainjs | no_demo; severity=medium\n\n## 8. 安全/权限坑 · 来源证据：bug(@langchain/openai): Bare JSON.parse in Responses API converter crashes on structured output with trailing characters\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：bug(@langchain/openai): Bare JSON.parse in Responses API converter crashes on structured output with trailing characters\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_4d2a6bed33284a3cbd2f3319321d9e4c | https://github.com/langchain-ai/langchainjs/issues/10894 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 9. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:598342280 | https://github.com/langchain-ai/langchainjs | issue_or_pr_quality=unknown\n\n## 10. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:598342280 | https://github.com/langchain-ai/langchainjs | release_recency=unknown\n", "summary": "用户实践前最可能遇到的身份、安装、配置、运行和安全坑。", "title": "Pitfall Log / 踩坑日志" }, "prompt_preview": { "asset_id": "prompt_preview", "filename": "PROMPT_PREVIEW.md", "markdown": "# langchainjs - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 langchainjs 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的软件开发与交付任务。\n我常用的宿主 AI：Local CLI\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 示例引导, 判断线索。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- 安装前能力预览: The agent engineering platform 输入：用户任务, 当前 AI 对话上下文；输出：示例引导, 判断线索。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. page-1：项目概述与生态系统。围绕“项目概述与生态系统”模拟一次用户任务，不展示安装或运行结果。\n2. page-2：系统架构与核心抽象。围绕“系统架构与核心抽象”模拟一次用户任务，不展示安装或运行结果。\n3. page-3：Agent 与 Chains 实现。围绕“Agent 与 Chains 实现”模拟一次用户任务，不展示安装或运行结果。\n4. page-4：向量存储与检索系统。围绕“向量存储与检索系统”模拟一次用户任务，不展示安装或运行结果。\n5. page-5：主要模型提供商集成。围绕“主要模型提供商集成”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. page-1\n输入：用户提供的“项目概述与生态系统”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. page-2\n输入：用户提供的“系统架构与核心抽象”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. page-3\n输入：用户提供的“Agent 与 Chains 实现”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. page-4\n输入：用户提供的“向量存储与检索系统”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. page-5\n输入：用户提供的“主要模型提供商集成”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / page-1：Step 1 必须围绕“项目概述与生态系统”形成一个小中间产物，并等待用户确认。\n- Step 2 / page-2：Step 2 必须围绕“系统架构与核心抽象”形成一个小中间产物，并等待用户确认。\n- Step 3 / page-3：Step 3 必须围绕“Agent 与 Chains 实现”形成一个小中间产物，并等待用户确认。\n- Step 4 / page-4：Step 4 必须围绕“向量存储与检索系统”形成一个小中间产物，并等待用户确认。\n- Step 5 / page-5：Step 5 必须围绕“主要模型提供商集成”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/langchain-ai/langchainjs\n- https://github.com/langchain-ai/langchainjs#readme\n- README.md\n- libs/langchain-core/README.md\n- libs/langchain/README.md\n- libs/langchain-classic/README.md\n- libs/langchain-core/src/runnables/base.ts\n- libs/langchain-core/src/callbacks/base.ts\n- libs/langchain-core/src/memory.ts\n- libs/langchain-core/src/tools/index.ts\n- libs/langchain-core/src/language_models/chat_models.ts\n- libs/langchain-core/src/vectorstores.ts\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 langchainjs 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n", "summary": "不安装项目也能感受能力节奏的安全试用 Prompt。", "title": "Prompt Preview / 安装前试用 Prompt" }, "quick_start": { "asset_id": "quick_start", "filename": "QUICK_START.md", "markdown": "# Quick Start / 官方入口\n\n项目：langchain-ai/langchainjs\n\n## 官方安装入口\n\n### Node.js / npm · 官方安装入口\n\n```bash\nnpm install -S langchain\n```\n\n来源：https://github.com/langchain-ai/langchainjs#readme\n\n## 来源\n\n- repo: https://github.com/langchain-ai/langchainjs\n- docs: https://github.com/langchain-ai/langchainjs#readme\n", "summary": "从项目官方 README 或安装文档提取的开工入口。", "title": "Quick Start / 官方入口" } }, "validation_id": "dval_d18ecddff9bf424e9e8c59d6cb1811bd" }