deepseek-harness/python/development.zh.md

Python 贡献者工作流

English | 中文

构建、验证和分发 Python SDK 与内置运行时的参考。包行为分别见 SDK 参考和运行时载体参考。

构建运行时产物

各平台可执行文件是构建产物，不检入 git。请在仓库根目录运行构建：

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

所需 lib/ 产物已存在时使用 --skip-build；如需选择平台，请使用 --targets=node24-linux-x64,node24-linux-arm64,node24-macos-arm64。产物写入 dist-exe/，脚本会将所选载体同步到 python/sdk-runtime/。macOS 构建还会同步 node-pty 所需的配套 spawn helper。

验证 SDK

请将虚拟环境放在 python/ 之外，安装测试组，然后运行 Python 测试套件：

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 会运行可用的内置载体；某个载体的产物尚未构建时，会跳过该载体。仓库级测试政策见测试。

交互式冒烟测试需要环境变量或仓库根目录 .env 中存在 DEEPSEEK_API_KEY：

from deepseek_harness import DeepSeekHarness

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

针对 Node 源码运行

仓库贡献者可以选择以下任一开发载体：

• 设置 DSH_RUNTIME_MODE=node，在系统 Node >=22.19 上使用已构建的 Node 载体。构建脚本会刷新该载体，但分发物绝不会包含或自动选择它。
• 将仓库根目录设为 cwd，并设置 launch_args_override=("./node_modules/.bin/tsx", "packages/examples/jsonrpc-demo/src/bin.ts")，以运行未构建的 TypeScript 源码。默认配置不合适时，请提供 cordis=...。

完整的源码模式调用见 python/sdk/tests/manual_sdk_agent_smoke.py。

构建分发物

根目录 package.json 的版本是两个 Python 分发物的权威版本。暂存脚本会将该版本注入两个 wheel 包，并将 SDK 固定到同版本的 deepseek-harness-runtime-bin。

纯 SDK wheel 包只需构建一次；每个原生平台分别构建一个运行时 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=="$version"

运行时分发物仅提供 wheel 包。发布流水线会连同纯 SDK wheel 包一起发布三个平台 wheel 包：Linux x64、Linux arm64 和 macOS arm64。只有与仓库版本匹配时，才接受 python-vX.Y.Z 标签。