Deep Agents 伙伴包Partner Package开发指南从独立版本化到 CI/发布全链路接线【免费下载链接】deepagentsThe batteries-included agent harness.项目地址: https://gitcode.com/GitHub_Trending/de/deepagents导读本文围绕 Deep Agents 仓库中libs/partners/AGENTS.md展开系统讲解伙伴包partner package的定位、开发约束以及把一个全新伙伴包接入仓库全部工程表面issue 模板、标签、CI、发布、安全凭证清单的完整操作清单。读完本文你将掌握伙伴包「独立版本化 自包含环境」的核心原则、Warnings are errors 的警告治理约定、18 个必须接线的仓库表面以及首次发布为何必须把 release-please manifest 基线设为0.0.0的底层原因并能在 Deep Agents monorepo 中独立完成一个新伙伴包的接入与首次发版。一、伙伴包是什么结构与职责边界Deep Agents monorepo 在libs/partners/下维护一组与第三方基础设施集成的伙伴包目前包含五个包目录发布名用途依据各包README.md与pyproject.tomllibs/partners/daytonalangchain-daytonaDaytona 沙箱后端集成DaytonaSandboxlibs/partners/modallangchain-modalModal 沙箱后端集成libs/partners/runlooplangchain-runloopRunloop 沙箱后端集成libs/partners/vercellangchain-vercel-sandboxVercel Sandbox 后端集成libs/partners/quickjslangchain-quickjs基于 QuickJS 的 JavaScript REPL 中间件CodeInterpreterMiddleware伙伴包遵循一个核心边界每个伙伴包都是独立版本化的一等公民拥有自己的环境、pyproject.toml、Makefile和测试互不共享依赖环境。这意味着对任何一个伙伴包的修改都不会牵连其他包也意味着新增包时必须把它完整接入仓库的工程体系而不是只建一个目录。二、两条全局铁律2.1 遵循仓库级规则特别是 Warnings are errors所有伙伴包必须遵循根目录AGENTS.md中定义的仓库级规则。其中被每个伙伴包pyproject.toml的注释按名引用的关键规则是Warnings are errors所有包都把未被接受的 pytest 警告视为错误。从libs/partners/daytona/pyproject.toml可以看到这条规则的落地形态[tool.pytest.ini_options] filterwarnings [ # Unexpected warnings fail the run; see Warnings are errors in AGENTS.md. error, # langchain_core imports pydantic.v1 during collection on Python 3.14. ignore:Core Pydantic V1 functionality isnt compatible:UserWarning, # ... ]规则细节见根AGENTS.md先error兜底把未预期的警告整体升级为失败对可预期的第三方警告才在包级filterwarnings中逐条ignore/default且必须写明理由注释对单条可预期警告优先用pytest.mark.filterwarnings作用到具体测试而不是放宽到包级警告过滤器中的 message 字段是未转义正则需转义字面元字符优先用default::而非ignore::让PytestUnhandledThreadExceptionWarning这类警告仍然可见。2.2 独立环境与独立版本每个伙伴包拥有自己的uv.lock例如libs/partners/daytona/uv.lock、pyproject.toml、Makefile、CHANGELOG.md与tests/。以 daytona 包为例其pyproject.toml声明requires-python 3.11,4.0 dependencies [ deepagents0.7.0,0.8.0, daytona, ] [tool.uv.sources] deepagents { path ../../deepagents, editable true }注意[tool.uv.sources]用本地可编辑路径指向 SDK../../deepagents本地开发直接吃仓库内最新 SDK而发布到 PyPI 时发布的是deepagents0.7.0,0.8.0的公开版本约束。这一本地路径 / 发布约束双轨制是伙伴包依赖管理的标准模式。三、新增伙伴包把新包接入所有相关仓库表面libs/partners/AGENTS.md的核心是一条接线清单wiring checklist新增伙伴包时必须把新包接入以下全部仓库表面。按职责可分为四组。3.1 议题与标签表面Issue LabelingIssue 模板的 Area 选项在.github/ISSUE_TEMPLATE/bug-report.yml、.github/ISSUE_TEMPLATE/feature-request.yml、.github/ISSUE_TEMPLATE/privileged.yml的 Area 下拉选项中加入新包使用户提交 issue 时能正确归类Scope 到 Label 的映射与路径规则在.github/scripts/labeling/pr-labeler-config.json含 pr-labeler 配置中加入新包的 scope-to-label 与 path 规则Issue 标签在.github/workflows/auto-label-by-package.yml中为新包注册自动打标规则。3.2 依赖更新表面Dependabot在.github/dependabot.yml的uvecosystem 的directories列表中注册新包目录。当前伙伴包的注册形态为- package-ecosystem: uv directories: - /libs/partners/daytona - /libs/partners/modal - /libs/partners/quickjs - /libs/partners/runloop - /libs/partners/vercel同时注意dependabot.yml的ignore列表中显式忽略所有仓库自有包deepagents、langchain-daytona等因为它们由发布流程自身管理版本避免 Dependabot 与 release-please 打架。3.3 CI 表面Change detection / Lint / Scope 同步变更检测与 CI 任务在.github/workflows/ci.yml中加入新包的变更检测path filter与对应的 lint/test 任务允许的 PR scope在.github/workflows/pr_lint.yml的scopes列表中加入新包 scope当前伙伴包对应langchain-daytona、langchain-modal、langchain-quickjs、langchain-runloop、langchain-vercel-sandbox等三处 scope 列表字节级同步上面的允许 scope 还必须字节一致地镜像到.githooks/pre-push和.github/workflows/branch_name_check.yml的SCOPES_RE列表中。仓库内的branch-scopes-syncpre-commit hook 会校验三处一致三处不一致则提交失败。相关同步检查脚本见.github/scripts/checks/check_branch_scopes_sync.py。提示PR scope 是 Conventional Commits 的type(scope):一部分pr_lint.yml中requireScope: true且release被disallowScopes排除release是类型而非 scope。伙伴包改动必须以形如feat(langchain-daytona): ...的标题提交。3.4 Sandbox 与集成测试表面沙箱选项与凭证检查若新伙伴包是sandbox-backed即提供沙箱后端如 daytona/modal/runloop/vercel必须在.github/workflows/harbor.yml中加入沙箱选项与凭证检查矩阵条目与按包密钥门控在.github/workflows/integration_tests.yml中为新包加入测试矩阵条目并按包做 secret 门控没有对应凭据的 PR 不跑该包的集成测试。3.5 发布表面Release-please 全链路这是接线最密集的一组涉及八个文件包设置与 inputs在.github/workflows/release.yml中加入新包的 package 设置与 workflow inputs发布检测在.github/workflows/release-please.yml中加入新包的发布检测release-please 配置在release-please-config.json的packages中加入新包条目。以 daytona 包为例标准条目形如libs/partners/daytona: { release-type: python, package-name: langchain-daytona, component: langchain-daytona, bump-minor-pre-major: true, bump-patch-for-minor-pre-major: true, extra-files: [ pyproject.toml, langchain_daytona/_version.py ], changelog-path: CHANGELOG.md, exclude-paths: [libs/partners/daytona/tests] }注意extra-files同时声明pyproject.toml与模块内_version.py发布时两处版本号会一起更新 4.manifest 基线在.release-please-manifest.json中加入新包条目见下节首次发布详解 5.受管包表在.github/RELEASING.md的 managed-packages 表格中加入新包一行包名、路径、component、PyPI 链接 6.发布说明的分发映射在.github/scripts/release/build_release_notes.py的 distribution-to-path 映射中加入新包 7.最低版本检查列表在.github/workflows/raise_langchain_minimums.yml的包列表中加入新包 8.凭证清单在.github/SECRETS.md的凭证清单中登记新包所需的 CI 密钥。四、首次发布为什么 manifest 基线必须设为 0.0.0libs/partners/AGENTS.md特别强调首次发布时把.release-please-manifest.json中的新包基线设为0.0.0原因与校验规则详见.github/RELEASING.md#adding-a-release-please-managed-package。核心机制是manifest 里记录的是最近一次已发布版本基线而不是包源码的当前版本。具体场景新包源码在pyproject.toml与_version.py中从0.0.1起步首次 PR 标题是 release-worthy 的如feat(langchain-daytona): ...如果 manifest 基线直接写0.0.1release-please 会认为0.0.1已经在外部发布过于是第一次 release PR 就直接开成0.0.2—— 包从未发布就先跳版本正确做法manifest 写0.0.0表示还从未发布pyproject.toml与_version.py保持0.0.1release-please 的首次 release PR 就会是0.0.1。仓库用Release-please initial baseline checkworkflow 拦截错误基线任何以0.0.1作为新受管包基线合入的 PR 都会被阻断。除非0.0.1确实已经在 release-please 体系之外发布过否则不要给新包写0.0.1基线。五、从源码看伙伴包的标准工程配置5.1 构建与依赖以langchain-daytona为例libs/partners/daytona/pyproject.toml展示了一个标准伙伴包配置构建后端hatchlingwheel 打包目录为langchain_daytonaPython 版本requires-python 3.11,4.0classifiers 覆盖 3.11~3.14测试依赖组pytest、pytest-cov、pytest-socket、pytest-xdist、pytest-timeout、pytest-asyncio、ruff、ty、langchain-tests等类型检查[tool.ty.environment]固定 python-version 3.11 并extra-paths指向本地 SDKRuff 全量规则select [ALL]仅对与格式化/动态类型相关的少数规则COM812、ISC001、ANN401做豁免Google 风格 docstringpytest 严格模式--strict-markers --strict-config --durations5asyncio_mode auto无需pytest.mark.asynciofilterwarnings以error开头落实 Warnings are errors。5.2 测试目标以langchain-daytona为例libs/partners/daytona/Makefile定义了伙伴包的标准 make 目标test: ## 单元测试禁用网络 socket仅放行 unix socket uv run --group test pytest -vvv $(PYTEST_EXTRA) --disable-socket --allow-unix-socket $(TEST_FILE) integration_test: ## 集成测试允许网络带 30s 超时 uv run --group test pytest -vvv --timeout 30 $(TEST_FILE) lint: ## ruff check format --diff ty check [ $(PYTHON_FILES) ] || uv run --all-groups ruff check $(PYTHON_FILES) [ $(PYTHON_FILES) ] || uv run --all-groups ruff format $(PYTHON_FILES) --diff $(MAKE) type type: ## ty 类型检查 uv run --all-groups ty check langchain_daytona测试布局约定见根AGENTS.md无网络测试放tests/unit_tests/需要网络/真实服务的测试放tests/integration_tests/。伙伴包测试目录结构与此一致例如 daytona 包的tests/unit_tests/test_import.py与tests/integration_tests/test_integration.py。5.3 功能差异quickjs 包的特例并非所有伙伴包都是沙箱后端。langchain-quickjs是一个中间件包通过CodeInterpreterMiddleware给 Deep Agents 注入一个持久的、沙箱化的 JavaScript REPL 工具见libs/partners/quickjs/README.md。其pyproject.tomllibs/partners/quickjs/pyproject.toml依赖quickjs-rs、langchain、langgraph、bsdiff4等测试组还带pytest-benchmark、pytest-codspeed与testcontainers[postgres]并定义了benchmark标记。这印证了伙伴包职责自由、工程统一的原则功能可以千差万别但独立版本化、独立环境、统一 CI/发布接线是硬性要求。六、发布周期与版本语义速览伙伴包与 SDK 一起由 release-please 统一管理见.github/RELEASING.md的 managed-packages 表。与伙伴包直接相关的要点发版触发合入feat/fix/perf/revert等 release-worthy 的 Conventional Commits 到main后release-please 按改动文件路径把提交归属到对应包为每个包开独立的草稿 release PRPre-1.0 版本语义所有包当前均未到 1.0因此feat只触发 Patch0.0.xfeat!/BREAKING CHANGE才触发 Minor0.x.0合并即发布release PR 合并后release.yml会按「构建 → 预发布检查 → Test PyPI → PyPI → GitHub Release → 标签切换」流水线自动发布伙伴包无需人工干预SKD 版本约束伙伴包以deepagents0.7.0,0.8.0这类上下限锁定 SDK发布前应确认在 PyPI 公开依赖图上可解析仓库用 Check Release Dependenciesworkflow 校验。七、接入自检清单Checklist新增伙伴包 PR 合入前对照libs/partners/AGENTS.md清单逐项确认pyproject.toml、Makefile、uv.lock、CHANGELOG.md、LICENSE、tests/一应俱全且可独立uv run --group test pytestfilterwarnings以error开头Warnings are errors 落实Issue 模板bug-report / feature-request / privileged加入 Area 选项.github/dependabot.yml注册新包目录pr-labeler 配置、auto-label-by-package.yml注册新包标签ci.yml增加变更检测与任务pr_lint.yml/.githooks/pre-push/branch_name_check.yml三处 scope 字节一致sandbox-backed 包harbor.yml沙箱选项与凭证检查integration_tests.yml矩阵与 secret 门控release.yml、release-please.yml、release-please-config.json、.release-please-manifest.json基线0.0.0、.github/RELEASING.md表、build_release_notes.py映射、raise_langchain_minimums.yml列表、.github/SECRETS.md凭证全部更新。结语libs/partners/AGENTS.md用一份精炼的清单定义了 Deep Agents 伙伴包的全部工程契约独立版本化与自包含环境保证每个包可独立演进Warnings are errors 保证测试信号的干净可信覆盖 issue、标签、CI、发布、凭证的 18 个接线点保证新包从诞生第一天就完整纳入仓库治理0.0.0基线规则则保证首次发布版本号不被 release-please 误跳。对想要为 Deep Agents 贡献新后端集成的开发者而言这份指南就是接入的路线图对照源码逐一落实即可让新伙伴包与既有五个包一样获得全自动的 CI 与发布能力。【免费下载链接】deepagentsThe batteries-included agent harness.项目地址: https://gitcode.com/GitHub_Trending/de/deepagents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考