---
type: study
created: 2026-08-11
updated: 2026-08-11
sensitivity: private
status: active
tags:
  - study
  - langchain
  - integrations
  - publishing
  - testing
topic: LangChain Python 集成的实现、标准测试、独立发布与合作
sources:
  - https://docs.langchain.com/oss/python/contributing/integrations-langchain
  - https://docs.langchain.com/oss/python/contributing/implement-langchain
  - https://docs.langchain.com/oss/python/contributing/standard-tests-langchain
  - https://docs.langchain.com/oss/python/contributing/publish-langchain
  - https://docs.langchain.com/oss/python/contributing/comarketing
last_verified: 2026-08-11
---
# 集成实现、标准测试、发布与合作

## 结论

新的 LangChain 集成必须作为贡献者自己维护的独立 PyPI 包发布，例如 `langchain-yourprovider`；LangChain 与 Deep Agents 核心仓库不接受新的集成实现 PR。官方仓库中的后续 PR 只负责可发现性：默认添加外部文档 YAML，达到门槛后才可能托管完整指南。

## 选择可维护的组件

优先集成具有稳定接口且生态仍在发展的组件：chat model、tool/toolkit、retriever、embedding、vector store、middleware、checkpointer、sandbox。传统 text-completion LLM 已被 chat model 取代；document loader、store、transformer、cache、graph、chat history、callback 等类型一般不鼓励新增，除非与维护者提前确认清晰价值和长期责任。

实现应继承 `langchain-core` 的公开抽象：

| 组件 | 主要契约 | 实现重点 |
|---|---|---|
| Chat model | `BaseChatModel` | 消息转换、生成、流式、工具调用、结构化输出能力声明 |
| Embeddings | `Embeddings` | 同步/异步批处理、维度、重试与限流 |
| Tool | `BaseTool` | 稳定输入 schema、可解释错误、最小权限 |
| Middleware | `AgentMiddleware` | hook 顺序、状态更新、provider 特性与跨 provider 行为 |
| Checkpointer | LangGraph persistence contract | 原子写入、线程隔离、恢复与并发一致性 |
| Sandbox | `SandboxBackendProtocol`，通常继承 `BaseSandbox` | 隔离执行、路径校验、超时、上传下载、资源回收 |

对于 sandbox，若环境能运行 shell 且有 `python3`，通常继承 `BaseSandbox`，重点实现 `execute`、`upload_files`、`download_files`、`id` 及异步对应方法。只把模型能够修复或重试的错误规范化返回；权限、越界和基础设施故障不应伪装成普通文件错误。

## 标准测试不是可选装饰

`langchain-tests` 提供 `langchain_tests.unit_tests` 与 `langchain_tests.integration_tests` 两组 pytest 类式套件。集成通过继承对应测试类获得统一行为验证：

- 单元测试隔离运行，不接触外部服务；
- 集成测试连接真实 provider，验证接口与能力；
- 大多数能力默认 opt-in，只有实现确实支持时才覆盖 capability property；不支持的能力应 skip，不能让错误实现“假通过”；
- `langchain-tests` 新版本可能新增断言，应固定已验证版本，计划升级后再更新 CI；
- 测试目录使用 `tests/unit_tests` 与 `tests/integration_tests`；sandbox 使用 `SandboxIntegrationTests`，fixture 必须在结束时清理远程资源。

常用入口：

```bash
make test
make integration_test
uv run --group test pytest tests/unit_tests/
uv run --group test --group test_integration pytest -n auto tests/integration_tests/
```

## 发布与可发现性

1. 在自己的 GitHub 组织或账号维护独立仓库。
2. 使用 PyPI token；账户启用 2FA，token 由 CI secret 注入，不写入配置和日志。
3. 构建、测试、签名/校验产物后发布包。
4. 默认在 docs 仓库的 `scripts/data/integration_external_docs.yaml` 添加名称、PyPI/npm 包名和 `docs_url`；使用方优先跳到合作方文档，其次 GitHub，再次包注册页。
5. 只有月下载量达到 **50,000+** 或被 maintainer 标记 featured，才可从模板创建托管集成指南。`featured: true` 只能由维护者决定。
6. 若从 YAML 列表升级为托管指南，应在同一 PR 删除旧 YAML 项，避免重复展示。

包实现始终留在独立仓库；即使拥有托管指南，向官方 docs 提交的仍只是文档。CI、frontmatter、本地化、可运行示例和写作质量不合格都可能导致拒绝。

## Co-marketing 的价值判断

官方更愿意推广可迁移的教育内容，而不是单纯“如何调用某集成”的广告。高价值候选包括复杂端到端 agent 应用、长期记忆、HITL、多代理架构，以及基于 LangChain/LangGraph 的新研究。先证明内容对开发者有通用学习价值，再讨论社交渠道传播。

## 生产责任

独立发布意味着维护者承担版本兼容、供应链安全、凭证处理、限流重试、弃用策略、真实集成测试和用户支持。通过标准测试只证明 LangChain 接口契约；provider 的 SLA、数据驻留、计费、配额和灾难恢复仍需单独验证。