DeepSeek Harness Python 开发工作流

DeepSeek Harness 是 DeepSeek AI 开源的智能体框架，命令行工具名为 dsh，主打「一切皆插件」的架构，底层由 Cordis 驱动，目前在 GitHub 上处于开发者预览阶段，以 MIT 协议开放。除了面向 npm 生态的主程序，仓库还配有一套 Python SDK：deepseek-harness-sdk 提供高层 turns API 和底层 JSON-RPC 客户端，deepseek-harness-runtime-bin 负责携带内置运行时二进制，两者通过 stdio 上按行分隔的 JSON-RPC 通信。SDK 文档解决「怎么用」之后，仓库里的 python/development.md 回答的是另一个问题：贡献者如何开发、验证并发布这套 Python 包。这份文档按目标拆出五条工作流，本文逐条整理。

按产出选路径：五条工作流

文档开门见山：先想清楚你要的产出，再选对应工作流。要运行时可执行文件，走构建流程；要确认 SDK 改动没问题，跑测试套件；要对着未构建的源码调试，选源码模式；要产出可安装的发行包，走构建发行流程；要确认一次发布万无一失，先过候选版本验证。至于各包的行为契约，则由 SDK 参考和运行时 carrier 参考两份文档负责，工作流文档只管过程。

构建运行时产物

各平台的可执行文件属于构建产物，不进 git，必须本地生成。在仓库根目录执行两步：

pnpm install
pnpm exec tsx scripts/build-exe-for-python-sdk.ts

脚本有几个实用开关：--skip-build 在所需的 lib/ 产物已存在时跳过重建；--targets 可以点名平台，例如 node24-linux-x64,node24-linux-arm64,node24-macos-arm64。构建结果落在 dist-exe/，脚本同时会把选中的 carrier 同步进 python/sdk-runtime/。在 macOS 上构建时，还会顺带同步 node-pty 依赖的 spawn helper，省去手工补文件的麻烦。

验证 SDK

验证环节有三条约定。第一，虚拟环境要放在 python/ 目录之外，官方推荐用 uv 配合自定义环境变量：

export UV_PROJECT_ENVIRONMENT="$PWD/tmp/py-sdk-venv"
uv sync --project python/sdk --group test
uv run --project python/sdk pytest

第二，python/sdk/tests/test_bundled_runtime.py 会覆盖当前可用的内置 carrier，某个 carrier 的产物没构建时，对应用例自动跳过，不会误报；仓库层面的测试政策由 docs/testing.md 统一约定。第三，交互式冒烟测试需要 DEEPSEEK_API_KEY，放在环境变量或仓库根目录的 .env 里均可：

from deepseek_harness import DeepSeekHarness

with DeepSeekHarness() as harness:
    print(harness.run("say hi").final_response)

直连 Node 源码调试

调试 Python SDK 时，仓库贡献者可以在两种开发 carrier 里选，让 Python 客户端直接对接 Node 侧：

• 设 DSH_RUNTIME_MODE=node，使用已构建的 Node carrier，要求系统 Node.js 不低于 22.19。构建脚本会刷新这个 carrier，但发行包永远不会包含它，也不会自动选中。
• 设 launch_args_override=("./node_modules/.bin/tsx", "packages/examples/jsonrpc-demo/src/bin.ts") 并把 cwd 指到仓库根，就能直接跑未经构建的 TypeScript 源码；默认配置不合适时，再补一个 cordis=...。

完整的 source-mode 调用示例在 python/sdk/tests/manual_sdk_agent_smoke.py，照抄改参数即可。

构建发行包

版本号的权威来源只有一个：仓库根目录 package.json 的 version 字段。staging 脚本会把这个版本注入两个 wheel，并把 SDK 钉到同版本的 deepseek-harness-runtime-bin，保证两者严格配套。做法是纯 SDK wheel 构建一次，runtime wheel 在每个目标原生平台上各构建一次：

version="$(node -p "require('./package.json').version")"
python scripts/build-python-release.py --package sdk --output-dir dist-python
python scripts/build-python-release.py --package runtime --platform macos-arm64 --runtime-exe dist-exe/dsh-jsonrpc-agent-pkg-macos-arm64 --output-dir dist-python
pip install --find-links dist-python deepseek-harness-sdk=="$version"

注意 runtime 发行包只有 wheel 这一种形态。发布流水线最终随纯 SDK wheel 一共发出四个文件：三个平台 runtime wheel 分别覆盖 Linux x64、Linux arm64 和 macOS 14 及以上 arm64。python-v<仓库版本> 形式的标签只有在与仓库版本一致时才会被接受；预发布版本如 0.0.1-rc.1，在 wheel 文件名和元数据里会用 PEP 440 的规范化写法 0.0.1rc1。

候选版本验证与发布门禁

确认一次发布没问题，有两条等效的干跑路径：给拉取请求打上 python-release-dry-run 标签，或者手动触发 GitHub 的 Release (Python) 工作流并把 publish 设为 false。干跑做五件事：构建全部四个 wheel；在 Python 3.10 和 3.14 上安装 Linux 发行集；逐一核对文件名与元数据；强制执行 PyPI 的单文件大小上限；保留一份带 SHA-256 哈希的聚合产物。两条干跑路径都不携带 registry 凭据，所以拉取请求触发的运行进不了任何发布 job。

正式发布运行在私有的自动化仓库里；包元数据指向单独的只读公开源码镜像，镜像不执行发布 Actions。私有仓库把变量 PYPI_PUBLISHER_REPOSITORY 设为自己的 owner/name，平时保持 PUBLIC_PYPI_RELEASE_ENABLED=false，只在有意的发布窗口打开。

发布 job 也做了拆分：runtime 与 SDK 各一个，SDK 上传失败可以续跑，不必重发不可变的 runtime 文件。publish=true 只在三个条件同时满足时生效：工作流跑在配置的发布仓库上、触发于匹配的 python-v* 标签、受保护环境 pypi-runtime 与 pypi 分别放行 runtime 与 SDK 两个 job。凭据走 PyPI Trusted Publishing，按需下发短时效 OIDC；公开 attestation 被显式关闭，因为它们会暴露私有发布者的身份。

小结

把五条工作流连起来看，是一条完整的 Python 侧工程链路：构建产物进 dist-exe/，uv 与 pytest 守住质量，源码模式打通调试，四个 wheel 组成发行面，干跑加多重门禁把住发布关。想给这个项目贡献 Python 代码，python/development.md 是必读；对更多团队而言，它展示了一个开源项目如何把「可执行文件分发、双语言包配套、受控发布」做得足够严谨，这套发布工程本身就有参考价值。