DeepSeek/deepseek-harness
1
0
Fork 0
mirror of https://github.com/deepseek-ai/deepseek-harness synced 2026-08-15 21:04:50 +00:00
Code Issues Packages Projects Releases Wiki Activity

fix(python): rename SDK distribution

Browse Source
This commit is contained in:
Yichen Jiang
2026-08-10 19:45:54 +08:00
parent dc524c2c93
commit 299cafad01
27 changed files with 151 additions and 50 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.i18n.yaml
View File

@@ -2,5 +2,5 @@
# side as of the last confirmed-consistent state. Both languages carry equal authority; # side as of the last confirmed-consistent state. Both languages carry equal authority;
# after editing either side, bring the other along and re-record with: # after editing either side, bring the other along and re-record with:
# pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md # pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md
2026-07-10-single-file-executable-sdk-runtime-distribution.md: a45678c9bb5fcae340ff7134687890879f56c630 2026-07-10-single-file-executable-sdk-runtime-distribution.md: fd232e8893b7beebe2e279cb5532daf8ef73a8a3
2026-07-10-single-file-executable-sdk-runtime-distribution.zh.md: f1fccc508471356dd6434da0e126ed38f15ed3ba 2026-07-10-single-file-executable-sdk-runtime-distribution.zh.md: bb0b6f8f660a42495da651a581236a7ce2a50773

4
.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md
View File

@@ -48,13 +48,13 @@ CI: [`.github/workflows/build-exe-for-python-sdk.yml`](../../../../.github/workf
The Python SDK lives at [`python/`](../../../../python/README.md): `python/sdk` (the client) + `python/sdk-runtime` (the runtime carrier package). The runtime package's data directory holds the checked-in default `runtime/cordis.yml`, the build-injected platform exe and optional helper, and the build-injected `runtime/node/` closure tree. `resolve_bundled_launch_args()` automatic resolution **finds the exe only**; the node carrier is enabled only by an explicit `DSH_RUNTIME_MODE=node` (running `runtime/node/node_modules/@deepseek-ai/dsh-jsonrpc-demo/lib/bin.js`, requiring a system node ≥22.19), positioned as the development-verification channel for members of this repo, and does not enter wheel distributions. The Python SDK lives at [`python/`](../../../../python/README.md): `python/sdk` (the client) + `python/sdk-runtime` (the runtime carrier package). The runtime package's data directory holds the checked-in default `runtime/cordis.yml`, the build-injected platform exe and optional helper, and the build-injected `runtime/node/` closure tree. `resolve_bundled_launch_args()` automatic resolution **finds the exe only**; the node carrier is enabled only by an explicit `DSH_RUNTIME_MODE=node` (running `runtime/node/node_modules/@deepseek-ai/dsh-jsonrpc-demo/lib/bin.js`, requiring a system node ≥22.19), positioned as the development-verification channel for members of this repo, and does not enter wheel distributions.
[`scripts/build-python-release.py`](../../../../scripts/build-python-release.py) reads the authoritative stable `X.Y.Z` from the repository root `package.json` and stages both packages at that version, with the SDK depending exactly on `deepseek-harness-runtime-bin==X.Y.Z`. An optional `python-vX.Y.Z` release tag is a consistency assertion and is rejected when it differs from the repository version; the source `pyproject.toml` development sentinel never determines a release version. The SDK is a `py3-none-any` wheel; each wheel-only runtime package contains one exe, and the macOS wheel also contains its architecture-matched helper. Runtime wheels use one of `py3-none-manylinux_2_28_x86_64`, `py3-none-manylinux_2_28_aarch64`, or `py3-none-macosx_11_0_arm64`; the Hatch hook rejects sdists, universal tags, mixed-platform payloads, missing or extra helpers, and unsupported platforms. [`scripts/build-python-release.py`](../../../../scripts/build-python-release.py) reads the authoritative stable `X.Y.Z` from the repository root `package.json` and stages both packages at that version, with `deepseek-harness-sdk` depending exactly on `deepseek-harness-runtime-bin==X.Y.Z`. An optional `python-vX.Y.Z` release tag is a consistency assertion and is rejected when it differs from the repository version; the source `pyproject.toml` development sentinel never determines a release version. The SDK is a `py3-none-any` wheel; each wheel-only runtime package contains one exe, and the macOS wheel also contains its architecture-matched helper. Runtime wheels use one of `py3-none-manylinux_2_28_x86_64`, `py3-none-manylinux_2_28_aarch64`, or `py3-none-macosx_11_0_arm64`; the Hatch hook rejects sdists, universal tags, mixed-platform payloads, missing or extra helpers, and unsupported platforms.
The exe's "must be explicitly configured" hard semantic is unchanged; the zero-config experience is restored by the wrapper: when the caller gave no `cordis`, named no explicit runtime, and the environment has no `DSH_CORDIS_CONFIG`, the client explicitly injects the checked-in default `cordis.yml` (agent-core + preloaded llm-deepseek + JSONL persistence + bash-local + the `dsh-jsonrpc` serving entry, with `!!js` environment-variable fallbacks) via `DSH_CORDIS_CONFIG`. The exe's "must be explicitly configured" hard semantic is unchanged; the zero-config experience is restored by the wrapper: when the caller gave no `cordis`, named no explicit runtime, and the environment has no `DSH_CORDIS_CONFIG`, the client explicitly injects the checked-in default `cordis.yml` (agent-core + preloaded llm-deepseek + JSONL persistence + bash-local + the `dsh-jsonrpc` serving entry, with `!!js` environment-variable fallbacks) via `DSH_CORDIS_CONFIG`.
### Naming lineage ### Naming lineage
`@deepseek-ai/dsh-jsonrpc-demo` (the package) → `dsh-jsonrpc-agent` (the bin) → `dsh-jsonrpc-agent-pkg` (the closure manifest; no scope prefix, deliberately sidestepping the constraints' package-shape rules for `@deepseek-ai/dsh-*`) → `dsh-jsonrpc-agent-pkg-<platform>-<arch>` (the exe artifacts). The wire `serverInfo.name` stays `deepseek-harness-sdk-runtime` (a protocol-stable value); the Python dist names are `deepseek-harness` / `deepseek-harness-runtime-bin`. `@deepseek-ai/dsh-jsonrpc-demo` (the package) → `dsh-jsonrpc-agent` (the bin) → `dsh-jsonrpc-agent-pkg` (the closure manifest; no scope prefix, deliberately sidestepping the constraints' package-shape rules for `@deepseek-ai/dsh-*`) → `dsh-jsonrpc-agent-pkg-<platform>-<arch>` (the exe artifacts). The wire `serverInfo.name` stays `deepseek-harness-sdk-runtime` (a protocol-stable value); the Python distribution names are `deepseek-harness-sdk` / `deepseek-harness-runtime-bin`, while the import modules remain `deepseek_harness` / `deepseek_harness_runtime`.
## Disposition of worker-style plugins ## Disposition of worker-style plugins

4
.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.zh.md
View File

@@ -48,13 +48,13 @@ CI 使用 [`.github/workflows/build-exe-for-python-sdk.yml`](../../../../.github
Python SDK 位于 [`python/`](../../../../python/README.md)：`python/sdk` 是客户端，`python/sdk-runtime` 是运行时载体包。运行时包的数据目录包含检入的默认 `runtime/cordis.yml`、构建注入的平台 exe 与可选 helper，以及构建注入的 `runtime/node/` 闭包树。`resolve_bundled_launch_args()` 的自动解析**只查找 exe**；`node` 载体仅在显式设置 `DSH_RUNTIME_MODE=node` 时启用（运行 `runtime/node/node_modules/@deepseek-ai/dsh-jsonrpc-demo/lib/bin.js`，需要系统 Node ≥22.19），定位为本仓库成员的开发验证通道，不随 wheel 包分发。 Python SDK 位于 [`python/`](../../../../python/README.md)：`python/sdk` 是客户端，`python/sdk-runtime` 是运行时载体包。运行时包的数据目录包含检入的默认 `runtime/cordis.yml`、构建注入的平台 exe 与可选 helper，以及构建注入的 `runtime/node/` 闭包树。`resolve_bundled_launch_args()` 的自动解析**只查找 exe**；`node` 载体仅在显式设置 `DSH_RUNTIME_MODE=node` 时启用（运行 `runtime/node/node_modules/@deepseek-ai/dsh-jsonrpc-demo/lib/bin.js`，需要系统 Node ≥22.19），定位为本仓库成员的开发验证通道，不随 wheel 包分发。
[`scripts/build-python-release.py`](../../../../scripts/build-python-release.py) 从仓库根目录的 `package.json` 读取权威的稳定版本 `X.Y.Z`，以该版本暂存两个包，并让 SDK 精确依赖 `deepseek-harness-runtime-bin==X.Y.Z`。可选的 `python-vX.Y.Z` 发布标签只是一项一致性断言，与仓库版本不同时会被拒绝；源码 `pyproject.toml` 中的开发占位版本从不决定发布版本。SDK 是 `py3-none-any` wheel 包；每个只提供 wheel 包的运行时包都包含一个 exe，macOS wheel 包还包含与其架构匹配的 helper。运行时 wheel 包使用 `py3-none-manylinux_2_28_x86_64`、`py3-none-manylinux_2_28_aarch64` 或 `py3-none-macosx_11_0_arm64` 三种标签之一；Hatch 钩子拒绝 sdist、通用标签、混合平台载荷、helper 缺失或多余，以及不支持的平台。 [`scripts/build-python-release.py`](../../../../scripts/build-python-release.py) 从仓库根目录的 `package.json` 读取权威的稳定版本 `X.Y.Z`，以该版本暂存两个包，并让 `deepseek-harness-sdk` 精确依赖 `deepseek-harness-runtime-bin==X.Y.Z`。可选的 `python-vX.Y.Z` 发布标签只是一项一致性断言，与仓库版本不同时会被拒绝；源码 `pyproject.toml` 中的开发占位版本从不决定发布版本。SDK 是 `py3-none-any` wheel 包；每个只提供 wheel 包的运行时包都包含一个 exe，macOS wheel 包还包含与其架构匹配的 helper。运行时 wheel 包使用 `py3-none-manylinux_2_28_x86_64`、`py3-none-manylinux_2_28_aarch64` 或 `py3-none-macosx_11_0_arm64` 三种标签之一；Hatch 钩子拒绝 sdist、通用标签、混合平台载荷、helper 缺失或多余，以及不支持的平台。
exe「必须显式配置」的硬语义不变；零配置体验由包装层恢复：调用方没有提供 `cordis`、没有显式指定运行时，且环境中没有 `DSH_CORDIS_CONFIG` 时，客户端将检入的默认 `cordis.yml`（`agent-core` + 预载的 `llm-deepseek` + JSONL 持久化 + `bash-local` + `dsh-jsonrpc` 对外服务条目，并通过 `!!js` 使用环境变量兜底）显式注入 `DSH_CORDIS_CONFIG`。 exe「必须显式配置」的硬语义不变；零配置体验由包装层恢复：调用方没有提供 `cordis`、没有显式指定运行时，且环境中没有 `DSH_CORDIS_CONFIG` 时，客户端将检入的默认 `cordis.yml`（`agent-core` + 预载的 `llm-deepseek` + JSONL 持久化 + `bash-local` + `dsh-jsonrpc` 对外服务条目，并通过 `!!js` 使用环境变量兜底）显式注入 `DSH_CORDIS_CONFIG`。
### 命名血统 ### 命名血统
`@deepseek-ai/dsh-jsonrpc-demo`（包）→ `dsh-jsonrpc-agent`（`bin`）→ `dsh-jsonrpc-agent-pkg`（闭包 manifest；没有作用域前缀，刻意避开 `constraints` 对 `@deepseek-ai/dsh-*` 的包形状规则）→ `dsh-jsonrpc-agent-pkg-<platform>-<arch>`（exe 产物）。协议字段 `serverInfo.name` 保持为 `deepseek-harness-sdk-runtime`（协议稳定值）；Python 分发名为 `deepseek-harness` / `deepseek-harness-runtime-bin`。 `@deepseek-ai/dsh-jsonrpc-demo`（包）→ `dsh-jsonrpc-agent`（`bin`）→ `dsh-jsonrpc-agent-pkg`（闭包 manifest；没有作用域前缀，刻意避开 `constraints` 对 `@deepseek-ai/dsh-*` 的包形状规则）→ `dsh-jsonrpc-agent-pkg-<platform>-<arch>`（exe 产物）。协议字段 `serverInfo.name` 保持为 `deepseek-harness-sdk-runtime`（协议稳定值）；Python 分发包名为 `deepseek-harness-sdk` / `deepseek-harness-runtime-bin`，导入模块名仍为 `deepseek_harness` / `deepseek_harness_runtime`。
## 工作线程插件 ## 工作线程插件

12
.github/workflows/build-exe-for-python-sdk.yml vendored
View File

@@ -92,7 +92,7 @@ jobs:
sdk-wheel: sdk-wheel:
needs: plan needs: plan
name: deepseek_harness-${{ needs.plan.outputs.version }}-py3-none-any.whl name: deepseek_harness_sdk-${{ needs.plan.outputs.version }}-py3-none-any.whl
runs-on: ubuntu-latest runs-on: ubuntu-latest
timeout-minutes: 5 timeout-minutes: 5
steps: steps:
@@ -113,8 +113,8 @@ jobs:
- uses: actions/upload-artifact@v7 - uses: actions/upload-artifact@v7
with: with:
name: deepseek_harness-${{ needs.plan.outputs.version }}-py3-none-any.whl name: deepseek_harness_sdk-${{ needs.plan.outputs.version }}-py3-none-any.whl
path: dist-python/deepseek_harness-${{ needs.plan.outputs.version }}-py3-none-any.whl path: dist-python/deepseek_harness_sdk-${{ needs.plan.outputs.version }}-py3-none-any.whl
if-no-files-found: error if-no-files-found: error
build: build:
@@ -197,7 +197,7 @@ jobs:
- uses: actions/download-artifact@v8 - uses: actions/download-artifact@v8
with: with:
name: deepseek_harness-${{ needs.plan.outputs.version }}-py3-none-any.whl name: deepseek_harness_sdk-${{ needs.plan.outputs.version }}-py3-none-any.whl
path: dist-python path: dist-python
- name: Install only the SDK into a clean venv and run zero-config - name: Install only the SDK into a clean venv and run zero-config
@@ -208,7 +208,7 @@ jobs:
python -m venv "$RUNNER_TEMP/dsh-sdk-smoke" python -m venv "$RUNNER_TEMP/dsh-sdk-smoke"
"$RUNNER_TEMP/dsh-sdk-smoke/bin/python" -m pip install \ "$RUNNER_TEMP/dsh-sdk-smoke/bin/python" -m pip install \
--find-links dist-python \ --find-links dist-python \
deepseek-harness=="$VERSION" deepseek-harness-sdk=="$VERSION"
"$RUNNER_TEMP/dsh-sdk-smoke/bin/python" scripts/smoke-python-runtime.py \ "$RUNNER_TEMP/dsh-sdk-smoke/bin/python" scripts/smoke-python-runtime.py \
--scenario sdk-default --scenario sdk-default
@@ -238,7 +238,7 @@ jobs:
esac esac
docker run --rm -e VERSION -v "$PWD:/work" -w /work "$image" bash -euxo pipefail -c ' docker run --rm -e VERSION -v "$PWD:/work" -w /work "$image" bash -euxo pipefail -c '
/opt/python/cp310-cp310/bin/python -m venv /tmp/dsh-sdk /opt/python/cp310-cp310/bin/python -m venv /tmp/dsh-sdk
/tmp/dsh-sdk/bin/python -m pip install --find-links /work/dist-python deepseek-harness=="$VERSION" /tmp/dsh-sdk/bin/python -m pip install --find-links /work/dist-python deepseek-harness-sdk=="$VERSION"
/tmp/dsh-sdk/bin/python /work/scripts/smoke-python-runtime.py --scenario sdk-default /tmp/dsh-sdk/bin/python /work/scripts/smoke-python-runtime.py --scenario sdk-default
' '

6
.gitlab-ci.yml
View File

@@ -42,7 +42,7 @@ sdk-wheel:
- uv run --python 3.10 --group test --project python/sdk python scripts/smoke-python-runtime.py --scenario all --exe "$EXE" - uv run --python 3.10 --group test --project python/sdk python scripts/smoke-python-runtime.py --scenario all --exe "$EXE"
- python scripts/build-python-release.py --package runtime --tag "$CI_COMMIT_TAG" --platform "$PLATFORM" --runtime-exe "$EXE" --output-dir "release/$PLATFORM" - python scripts/build-python-release.py --package runtime --tag "$CI_COMMIT_TAG" --platform "$PLATFORM" --runtime-exe "$EXE" --output-dir "release/$PLATFORM"
- python -m venv .wheel-smoke - python -m venv .wheel-smoke
- .wheel-smoke/bin/python -m pip install --find-links "release/$PLATFORM" --find-links release/sdk deepseek-harness=="$DSH_VERSION" - .wheel-smoke/bin/python -m pip install --find-links "release/$PLATFORM" --find-links release/sdk deepseek-harness-sdk=="$DSH_VERSION"
- .wheel-smoke/bin/python scripts/smoke-python-runtime.py --scenario sdk-default - .wheel-smoke/bin/python scripts/smoke-python-runtime.py --scenario sdk-default
- | - |
if [ "${PLATFORM#linux-}" != "$PLATFORM" ]; then if [ "${PLATFORM#linux-}" != "$PLATFORM" ]; then
@@ -55,7 +55,7 @@ sdk-wheel:
linux-arm64) image=quay.io/pypa/manylinux_2_28_aarch64 ;; linux-arm64) image=quay.io/pypa/manylinux_2_28_aarch64 ;;
*) echo "Unsupported Linux platform $PLATFORM"; exit 1 ;; *) echo "Unsupported Linux platform $PLATFORM"; exit 1 ;;
esac esac
docker run --rm -v "$PWD:/work" -w /work "$image" bash -euxo pipefail -c "/opt/python/cp310-cp310/bin/python -m venv /tmp/dsh-sdk && /tmp/dsh-sdk/bin/python -m pip install --find-links /work/release/$PLATFORM --find-links /work/release/sdk deepseek-harness==$DSH_VERSION && /tmp/dsh-sdk/bin/python /work/scripts/smoke-python-runtime.py --scenario sdk-default" docker run --rm -v "$PWD:/work" -w /work "$image" bash -euxo pipefail -c "/opt/python/cp310-cp310/bin/python -m venv /tmp/dsh-sdk && /tmp/dsh-sdk/bin/python -m pip install --find-links /work/release/$PLATFORM --find-links /work/release/sdk deepseek-harness-sdk==$DSH_VERSION && /tmp/dsh-sdk/bin/python /work/scripts/smoke-python-runtime.py --scenario sdk-default"
fi fi
artifacts: artifacts:
paths: [release/$PLATFORM/*.whl] paths: [release/$PLATFORM/*.whl]
@@ -112,7 +112,7 @@ publish-python:
- python -m pip install twine==6.2.0 - python -m pip install twine==6.2.0
script: script:
- test "$(find release -name '*.whl' | wc -l | tr -d ' ')" = 4 - test "$(find release -name '*.whl' | wc -l | tr -d ' ')" = 4
- test -f "release/sdk/deepseek_harness-${DSH_VERSION}-py3-none-any.whl" - test -f "release/sdk/deepseek_harness_sdk-${DSH_VERSION}-py3-none-any.whl"
- test -f "release/linux-x64/deepseek_harness_runtime_bin-${DSH_VERSION}-py3-none-manylinux_2_28_x86_64.whl" - test -f "release/linux-x64/deepseek_harness_runtime_bin-${DSH_VERSION}-py3-none-manylinux_2_28_x86_64.whl"
- test -f "release/linux-arm64/deepseek_harness_runtime_bin-${DSH_VERSION}-py3-none-manylinux_2_28_aarch64.whl" - test -f "release/linux-arm64/deepseek_harness_runtime_bin-${DSH_VERSION}-py3-none-manylinux_2_28_aarch64.whl"
- test -f "release/macos-arm64/deepseek_harness_runtime_bin-${DSH_VERSION}-py3-none-macosx_11_0_arm64.whl" - test -f "release/macos-arm64/deepseek_harness_runtime_bin-${DSH_VERSION}-py3-none-macosx_11_0_arm64.whl"

2
THIRD_PARTY_NOTICES.md
View File

@@ -181,7 +181,7 @@ Direct dependencies of the `pyproject.toml` manifests, plus `uv` as the developm
| Package | License | Role | | Package | License | Role |
| --- | --- | --- | | --- | --- | --- |
| [`hatchling`](https://github.com/pypa/hatch) | MIT | build backend | | [`hatchling`](https://github.com/pypa/hatch) | MIT | build backend |
| [`pydantic`](https://github.com/pydantic/pydantic) | MIT | runtime dependency of `deepseek-harness` | | [`pydantic`](https://github.com/pydantic/pydantic) | MIT | runtime dependency of `deepseek-harness-sdk` |
| [`pytest`](https://github.com/pytest-dev/pytest) | MIT | test-only | | [`pytest`](https://github.com/pytest-dev/pytest) | MIT | test-only |
| [`uv`](https://github.com/astral-sh/uv) | MIT / Apache-2.0 | development workflow tool | | [`uv`](https://github.com/astral-sh/uv) | MIT / Apache-2.0 | development workflow tool |

4
docs/user/guide/python-sdk-minimal.i18n.yaml
View File

@@ -2,5 +2,5 @@
# side as of the last confirmed-consistent state. Both languages carry equal authority; # side as of the last confirmed-consistent state. Both languages carry equal authority;
# after editing either side, bring the other along and re-record with: # after editing either side, bring the other along and re-record with:
# pnpm run verify-translation-pairing --write docs/user/guide/python-sdk-minimal.md # pnpm run verify-translation-pairing --write docs/user/guide/python-sdk-minimal.md
python-sdk-minimal.md: 9d46278aeec625afdf30678806bc90104be00b66 python-sdk-minimal.md: e658fadae9575fd8bbc2aab2c622df7079c7addf
python-sdk-minimal.zh.md: ec06a205c680c1d7a83be5f949c7ff4d719defe4 python-sdk-minimal.zh.md: ef37e1e801512bf60f212e69b61eb423ce4ab1d1

39
docs/user/guide/python-sdk-minimal.md
View File

@@ -11,15 +11,50 @@ This tutorial runs the minimal agent without the Web UI. The checked-in Cordis c
- A DeepSeek-compatible API endpoint and credential - A DeepSeek-compatible API endpoint and credential
- An isolated workspace that the agent may modify - An isolated workspace that the agent may modify
## Install the SDK
Choose either the public package or a source build. Both install the `deepseek-harness-sdk` distribution and expose the `deepseek_harness` Python module.
### Install from PyPI
Create a virtual environment and install the SDK with its same-version bundled runtime: Create a virtual environment and install the SDK with its same-version bundled runtime:
```sh ```sh
python -m venv .venv python -m venv .venv
. .venv/bin/activate . .venv/bin/activate
python -m pip install deepseek-harness python -m pip install deepseek-harness-sdk
``` ```
The runtime wheel contains the JSON-RPC executable and every plugin used by the complete [`minimal.cordis.yml`](../../../examples/jsonrpc-agent/minimal.cordis.yml), so an installed SDK does not need Node.js. ### Build from source
A source build additionally requires Git, Node.js ^22.19 or >= 24, Corepack-enabled pnpm 11, and `uv`. The following commands build the runtime for the current supported host platform, build both wheels, and install them into the active virtual environment:
```sh
git clone https://github.com/deepseek-ai/deepseek-harness-sdk.git
cd deepseek-harness
python -m pip install uv==0.11.23
corepack enable
pnpm install
case "$(uname -s):$(uname -m)" in
Linux:x86_64) runtime_platform=linux-x64 ;;
Linux:aarch64|Linux:arm64) runtime_platform=linux-arm64 ;;
Darwin:arm64) runtime_platform=macos-arm64 ;;
*) echo "unsupported platform" >&2; exit 1 ;;
esac
pnpm exec tsx scripts/build-exe-for-python-sdk.ts --targets="node24-$runtime_platform"
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 "$runtime_platform" \
--runtime-exe "dist-exe/dsh-jsonrpc-agent-pkg-$runtime_platform" \
--output-dir dist-python
python -m pip install --find-links dist-python "deepseek-harness-sdk==$version"
```
The runtime wheel contains the JSON-RPC executable and every plugin used by the complete [`minimal.cordis.yml`](../../../examples/jsonrpc-agent/minimal.cordis.yml), so neither installation path needs Node.js after installation.
## Run the checked-in example ## Run the checked-in example

39
docs/user/guide/python-sdk-minimal.zh.md
View File

@@ -11,15 +11,50 @@
- DeepSeek 兼容的 API 端点与凭据 - DeepSeek 兼容的 API 端点与凭据
- agent 可以修改的隔离 workspace - agent 可以修改的隔离 workspace
## 安装 SDK
可以选择安装公开包或从源码构建。两种方式都会安装 `deepseek-harness-sdk` 分发包，并提供 `deepseek_harness` Python 模块。
### 从 PyPI 安装
请创建虚拟环境，并安装 SDK 及其同版本内置运行时： 请创建虚拟环境，并安装 SDK 及其同版本内置运行时：
```sh ```sh
python -m venv .venv python -m venv .venv
. .venv/bin/activate . .venv/bin/activate
python -m pip install deepseek-harness python -m pip install deepseek-harness-sdk
``` ```
运行时 wheel 包含 JSON-RPC 可执行文件，以及完整 [`minimal.cordis.yml`](../../../examples/jsonrpc-agent/minimal.cordis.yml) 使用的每个插件，因此安装后的 SDK 不需要 Node.js。 ### 从源码构建
从源码构建还需要 Git、Node.js ^22.19 或 >= 24、通过 Corepack 启用的 pnpm 11，以及 `uv`。以下命令为当前受支持的宿主平台构建运行时和两个 wheel 包，并将它们安装进当前虚拟环境：
```sh
git clone https://github.com/deepseek-ai/deepseek-harness-sdk.git
cd deepseek-harness
python -m pip install uv==0.11.23
corepack enable
pnpm install
case "$(uname -s):$(uname -m)" in
Linux:x86_64) runtime_platform=linux-x64 ;;
Linux:aarch64|Linux:arm64) runtime_platform=linux-arm64 ;;
Darwin:arm64) runtime_platform=macos-arm64 ;;
*) echo "unsupported platform" >&2; exit 1 ;;
esac
pnpm exec tsx scripts/build-exe-for-python-sdk.ts --targets="node24-$runtime_platform"
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 "$runtime_platform" \
--runtime-exe "dist-exe/dsh-jsonrpc-agent-pkg-$runtime_platform" \
--output-dir dist-python
python -m pip install --find-links dist-python "deepseek-harness-sdk==$version"
```
运行时 wheel 包含 JSON-RPC 可执行文件，以及完整 [`minimal.cordis.yml`](../../../examples/jsonrpc-agent/minimal.cordis.yml) 使用的每个插件，因此两种安装方式完成后都不再需要 Node.js。
## 运行仓库内置示例 ## 运行仓库内置示例

4
python/README.i18n.yaml
View File

@@ -2,5 +2,5 @@
# side as of the last confirmed-consistent state. Both languages carry equal authority; # side as of the last confirmed-consistent state. Both languages carry equal authority;
# after editing either side, bring the other along and re-record with: # after editing either side, bring the other along and re-record with:
# pnpm run verify-translation-pairing --write python/README.md # pnpm run verify-translation-pairing --write python/README.md
README.md: 6ab9de681471c4be3bff72ddbf6ce8f118224d4d README.md: 75276a915eb4b63f84e0876de46e6d8d63540b59
README.zh.md: 82fca597791f19caa21a7a433e533a4d47c64ccb README.zh.md: 7791231f9899bd1cca0d62ad35e388db608294c2

2
python/README.md
View File

@@ -8,7 +8,7 @@ Python packages for driving DeepSeek Harness as a subprocess. The client SDK com
| Directory | Dist / module | Role | | Directory | Dist / module | Role |
|---|---|---| |---|---|---|
| [sdk](sdk/README.md) | `deepseek-harness` / `deepseek_harness` | High-level turns API and lower-level JSON-RPC client | | [sdk](sdk/README.md) | `deepseek-harness-sdk` / `deepseek_harness` | High-level turns API and lower-level JSON-RPC client |
| [sdk-runtime](sdk-runtime/README.md) | `deepseek-harness-runtime-bin` / `deepseek_harness_runtime` | Bundled runtime binaries and default agent configuration | | [sdk-runtime](sdk-runtime/README.md) | `deepseek-harness-runtime-bin` / `deepseek_harness_runtime` | Bundled runtime binaries and default agent configuration |
## Behavior ## Behavior

2
python/README.zh.md
View File

@@ -8,7 +8,7 @@
| 目录 | 分发名 / 模块 | 职责 | | 目录 | 分发名 / 模块 | 职责 |
|---|---|---| |---|---|---|
| [sdk](sdk/README.md) | `deepseek-harness` / `deepseek_harness` | 高层轮次 API 与低层 JSON-RPC 客户端 | | [sdk](sdk/README.md) | `deepseek-harness-sdk` / `deepseek_harness` | 高层轮次 API 与低层 JSON-RPC 客户端 |
| [sdk-runtime](sdk-runtime/README.md) | `deepseek-harness-runtime-bin` / `deepseek_harness_runtime` | 内置运行时二进制与默认 agent（智能体）配置 | | [sdk-runtime](sdk-runtime/README.md) | `deepseek-harness-runtime-bin` / `deepseek_harness_runtime` | 内置运行时二进制与默认 agent（智能体）配置 |
## 行为 ## 行为

4
python/development.i18n.yaml
View File

@@ -2,5 +2,5 @@
# side as of the last confirmed-consistent state. Both languages carry equal authority; # side as of the last confirmed-consistent state. Both languages carry equal authority;
# after editing either side, bring the other along and re-record with: # after editing either side, bring the other along and re-record with:
# pnpm run verify-translation-pairing --write python/development.md # pnpm run verify-translation-pairing --write python/development.md
development.md: b0d4875f0d5b7c8fd2b4b480ac67793741640710 development.md: 9614c06436ab6863a5e1b2ff83fbe605552dc13b
development.zh.md: 053cd1d022ef5fc7d8cff98b9fc3234df6ff4cd1 development.zh.md: 1c646ca39735b85a5d380768fe215c92532be7e7

2
python/development.md
View File

@@ -55,7 +55,7 @@ Build the pure SDK wheel once and one runtime wheel on each native platform:
version="$(node -p "require('./package.json').version")" 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 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 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" pip install --find-links dist-python deepseek-harness-sdk=="$version"
``` ```
The runtime distribution is wheel-only. The release pipeline publishes three platform wheels with the pure SDK wheel: Linux x64, Linux arm64, and macOS arm64. A `python-vX.Y.Z` tag is accepted only when it matches the repository version. The runtime distribution is wheel-only. The release pipeline publishes three platform wheels with the pure SDK wheel: Linux x64, Linux arm64, and macOS arm64. A `python-vX.Y.Z` tag is accepted only when it matches the repository version.

2
python/development.zh.md
View File

@@ -55,7 +55,7 @@ with DeepSeekHarness() as harness:
version="$(node -p "require('./package.json').version")" 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 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 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" pip install --find-links dist-python deepseek-harness-sdk=="$version"
``` ```
运行时分发包仅提供 wheel 包。发布流水线会连同纯 SDK wheel 包一起发布三个平台 wheel 包：Linux x64、Linux arm64 和 macOS arm64。只有与仓库版本匹配时，才接受 `python-vX.Y.Z` 标签。 运行时分发包仅提供 wheel 包。发布流水线会连同纯 SDK wheel 包一起发布三个平台 wheel 包：Linux x64、Linux arm64 和 macOS arm64。只有与仓库版本匹配时，才接受 `python-vX.Y.Z` 标签。

4
python/sdk-runtime/README.i18n.yaml
View File

@@ -2,5 +2,5 @@
# side as of the last confirmed-consistent state. Both languages carry equal authority; # side as of the last confirmed-consistent state. Both languages carry equal authority;
# after editing either side, bring the other along and re-record with: # after editing either side, bring the other along and re-record with:
# pnpm run verify-translation-pairing --write python/sdk-runtime/README.md # pnpm run verify-translation-pairing --write python/sdk-runtime/README.md
README.md: 07bb3c574b3cd49f1dc74f0e9d9bd1bb7ca9b216 README.md: 5c7c6f66083a1b56cc6b4aed9565e8b1be014ccc
README.zh.md: 0613b6faf68ea3bdb6c9b673677fc483b79dab72 README.zh.md: cef1478710d20d7faa612e50d0c2f8ec19e8716a

2
python/sdk-runtime/README.md
View File

@@ -2,7 +2,7 @@
English | [中文](README.zh.md) English | [中文](README.zh.md)
Runtime carrier package for the Python SDK (dist `deepseek-harness-runtime-bin`, module `deepseek_harness_runtime`): it locates the bundled runtime binaries the `deepseek-harness` client spawns, and ships the default configuration behind zero-config runs. Runtime carrier package for the Python SDK (dist `deepseek-harness-runtime-bin`, module `deepseek_harness_runtime`): it locates the bundled runtime binaries the `deepseek-harness-sdk` client spawns, and ships the default configuration behind zero-config runs.
## Runtime carriers ## Runtime carriers

2
python/sdk-runtime/README.zh.md
View File

@@ -2,7 +2,7 @@
[English](README.md) | 中文 [English](README.md) | 中文
Python SDK 的运行时载体包（分发名 `deepseek-harness-runtime-bin`，模块名 `deepseek_harness_runtime`）：它定位 `deepseek-harness` 客户端要 spawn 的内置运行时二进制，并附带支撑零配置运行的默认配置。 Python SDK 的运行时载体包（分发名 `deepseek-harness-runtime-bin`，模块名 `deepseek_harness_runtime`）：它定位 `deepseek-harness-sdk` 客户端要 spawn 的内置运行时二进制，并附带支撑零配置运行的默认配置。
## 运行时载体 ## 运行时载体

4
python/sdk/README.i18n.yaml
View File

@@ -2,5 +2,5 @@
# side as of the last confirmed-consistent state. Both languages carry equal authority; # side as of the last confirmed-consistent state. Both languages carry equal authority;
# after editing either side, bring the other along and re-record with: # after editing either side, bring the other along and re-record with:
# pnpm run verify-translation-pairing --write python/sdk/README.md # pnpm run verify-translation-pairing --write python/sdk/README.md
README.md: f2cd6b9f1a978fe5519df3965fbe6679a72d56f5 README.md: 2350fbfd5dd0094bfd7a11f81d8226e960879923
README.zh.md: dfa25d1d09d6edf24ebf1df3faa925493aeef7de README.zh.md: 5120a8c5f65360485d450614186d5cb2702fda17

8
python/sdk/README.md
View File

@@ -7,7 +7,13 @@ runtime inherits normal DeepSeek Harness environment variables such as
`DEEPSEEK_BASE_URL` and `DEEPSEEK_API_KEY`, so callers can use real model `DEEPSEEK_BASE_URL` and `DEEPSEEK_API_KEY`, so callers can use real model
endpoints directly or point those variables at a local proxy. endpoints directly or point those variables at a local proxy.
Installing `deepseek-harness` installs the exact same-version `deepseek-harness-runtime-bin` platform wheel. The normal entry point therefore needs no executable argument: Install the `deepseek-harness-sdk` distribution from PyPI; the import module remains `deepseek_harness`:
```sh
python -m pip install deepseek-harness-sdk
```
Installing `deepseek-harness-sdk` installs the exact same-version `deepseek-harness-runtime-bin` platform wheel. The normal entry point therefore needs no executable argument:
```py ```py
from deepseek_harness import DeepSeekHarness from deepseek_harness import DeepSeekHarness

8
python/sdk/README.zh.md
View File

@@ -4,7 +4,13 @@
通过 JSON-RPC stdio 驱动 DeepSeek Harness 的 Python 子进程 SDK。运行时继承常规的 DeepSeek Harness 环境变量（如 `DEEPSEEK_BASE_URL` 与 `DEEPSEEK_API_KEY`），调用方可以直接使用真实模型端点，也可以把这些变量指向本地代理。 通过 JSON-RPC stdio 驱动 DeepSeek Harness 的 Python 子进程 SDK。运行时继承常规的 DeepSeek Harness 环境变量（如 `DEEPSEEK_BASE_URL` 与 `DEEPSEEK_API_KEY`），调用方可以直接使用真实模型端点，也可以把这些变量指向本地代理。
安装 `deepseek-harness` 会同时安装版本完全相同的 `deepseek-harness-runtime-bin` 平台 wheel 包。因此常规入口不需要传可执行文件参数： 请从 PyPI 安装 `deepseek-harness-sdk` 分发包；导入模块仍为 `deepseek_harness`：
```sh
python -m pip install deepseek-harness-sdk
```
安装 `deepseek-harness-sdk` 会同时安装版本完全相同的 `deepseek-harness-runtime-bin` 平台 wheel 包。因此常规入口不需要传可执行文件参数：
```py ```py
from deepseek_harness import DeepSeekHarness from deepseek_harness import DeepSeekHarness

2
python/sdk/pyproject.toml
View File

@@ -3,7 +3,7 @@ requires = ["hatchling>=1.30.1"]
build-backend = "hatchling.build" build-backend = "hatchling.build"
[project] [project]
name = "deepseek-harness" name = "deepseek-harness-sdk"
version = "0.0.0.dev0" version = "0.0.0.dev0"
description = "Python SDK for DeepSeek Harness" description = "Python SDK for DeepSeek Harness"
readme = "README.md" readme = "README.md"

12
python/sdk/tests/test_release_version.py
View File

@@ -39,6 +39,18 @@ def test_repository_version_rejects_non_stable_versions(tmp_path: Path) -> None:
build_python_release.repository_version(tmp_path) build_python_release.repository_version(tmp_path)
def test_stage_sdk_keeps_distribution_module_and_runtime_pin_distinct(tmp_path: Path) -> None:
destination = tmp_path / "staging"
build_python_release.stage_sdk(destination, "1.2.3")
pyproject = (destination / "pyproject.toml").read_text()
assert 'name = "deepseek-harness-sdk"' in pyproject
assert 'version = "1.2.3"' in pyproject
assert '"deepseek-harness-runtime-bin==1.2.3"' in pyproject
assert (destination / "src" / "deepseek_harness" / "__init__.py").is_file()
@pytest.mark.parametrize(("target", "with_helper"), [("linux-x64", False), ("macos-arm64", True)]) @pytest.mark.parametrize(("target", "with_helper"), [("linux-x64", False), ("macos-arm64", True)])
def test_stage_runtime_copies_platform_payload( def test_stage_runtime_copies_platform_payload(
tmp_path: Path, target: str, with_helper: bool tmp_path: Path, target: str, with_helper: bool

14
python/sdk/uv.lock generated
View File

@@ -21,7 +21,12 @@ wheels = [
] ]
[[package]] [[package]]
name = "deepseek-harness" name = "deepseek-harness-runtime-bin"
version = "0.0.0.dev0"
source = { editable = "../sdk-runtime" }
[[package]]
name = "deepseek-harness-sdk"
version = "0.0.0.dev0" version = "0.0.0.dev0"
source = { editable = "." } source = { editable = "." }
dependencies = [ dependencies = [
@@ -43,17 +48,12 @@ requires-dist = [
[package.metadata.requires-dev] [package.metadata.requires-dev]
test = [{ name = "pytest", specifier = ">=8.0" }] test = [{ name = "pytest", specifier = ">=8.0" }]
[[package]]
name = "deepseek-harness-runtime-bin"
version = "0.0.0.dev0"
source = { editable = "../sdk-runtime" }
[[package]] [[package]]
name = "exceptiongroup" name = "exceptiongroup"
version = "1.3.1" version = "1.3.1"
source = { registry = "https://pypi.org/simple" } source = { registry = "https://pypi.org/simple" }
dependencies = [ dependencies = [
{ name = "typing-extensions" }, { name = "typing-extensions", marker = "python_full_version < '3.13'" },
] ]
sdist = { url = "https://files.pythonhosted.org/packages/50/79/66800aadf48771f6b62f7eb014e352e5d06856655206165d775e675a02c9/exceptiongroup-1.3.1.tar.gz", hash = "sha256:8b412432c6055b0b7d14c310000ae93352ed6754f70fa8f7c34141f91c4e3219", size = 30371, upload-time = "2025-11-21T23:01:54.787Z" } sdist = { url = "https://files.pythonhosted.org/packages/50/79/66800aadf48771f6b62f7eb014e352e5d06856655206165d775e675a02c9/exceptiongroup-1.3.1.tar.gz", hash = "sha256:8b412432c6055b0b7d14c310000ae93352ed6754f70fa8f7c34141f91c4e3219", size = 30371, upload-time = "2025-11-21T23:01:54.787Z" }
wheels = [ wheels = [

11
scripts/build-python-release.py
View File

@@ -17,6 +17,8 @@ from pathlib import Path
ROOT = Path(__file__).resolve().parents[1] ROOT = Path(__file__).resolve().parents[1]
SDK_DISTRIBUTION = "deepseek-harness-sdk"
RUNTIME_DISTRIBUTION = "deepseek-harness-runtime-bin"
PLATFORMS = { PLATFORMS = {
"linux-x64": ("manylinux_2_28_x86_64", "dsh-jsonrpc-agent-pkg-linux-x64"), "linux-x64": ("manylinux_2_28_x86_64", "dsh-jsonrpc-agent-pkg-linux-x64"),
"linux-arm64": ("manylinux_2_28_aarch64", "dsh-jsonrpc-agent-pkg-linux-arm64"), "linux-arm64": ("manylinux_2_28_aarch64", "dsh-jsonrpc-agent-pkg-linux-arm64"),
@@ -53,7 +55,7 @@ def main() -> None:
if args.package == "sdk": if args.package == "sdk":
stage_sdk(staging, version) stage_sdk(staging, version)
environment = None environment = None
expected = output_dir / f"deepseek_harness-{version}-py3-none-any.whl" expected = output_dir / f"deepseek_harness_sdk-{version}-py3-none-any.whl"
else: else:
platform_tag, executable_name = PLATFORMS[args.platform] platform_tag, executable_name = PLATFORMS[args.platform]
stage_runtime(staging, version, args.runtime_exe.resolve(), executable_name) stage_runtime(staging, version, args.runtime_exe.resolve(), executable_name)
@@ -160,6 +162,11 @@ def verify_wheel(
raise RuntimeError(f"{wheel} has wrong WHEEL tags: {wheel_metadata.get_all('Tag')}") raise RuntimeError(f"{wheel} has wrong WHEEL tags: {wheel_metadata.get_all('Tag')}")
if metadata.get("Version") != version: if metadata.get("Version") != version:
raise RuntimeError(f"{wheel} has version {metadata.get('Version')}, expected {version}") raise RuntimeError(f"{wheel} has version {metadata.get('Version')}, expected {version}")
expected_distribution = SDK_DISTRIBUTION if package == "sdk" else RUNTIME_DISTRIBUTION
if metadata.get("Name") != expected_distribution:
raise RuntimeError(
f"{wheel} has distribution name {metadata.get('Name')}, expected {expected_distribution}"
)
runtime_files = [ runtime_files = [
name for name in archive.namelist() if "/runtime/dsh-jsonrpc-agent-pkg-" in name name for name in archive.namelist() if "/runtime/dsh-jsonrpc-agent-pkg-" in name
] ]
@@ -177,7 +184,7 @@ def verify_wheel(
raise RuntimeError(f"SDK wheel unexpectedly contains runtime executables: {runtime_files}") raise RuntimeError(f"SDK wheel unexpectedly contains runtime executables: {runtime_files}")
if package == "sdk": if package == "sdk":
requirements = metadata.get_all("Requires-Dist") or [] requirements = metadata.get_all("Requires-Dist") or []
expected_requirement = f"deepseek-harness-runtime-bin=={version}" expected_requirement = f"{RUNTIME_DISTRIBUTION}=={version}"
if expected_requirement not in requirements: if expected_requirement not in requirements:
raise RuntimeError(f"{wheel} does not pin {expected_requirement}; found {requirements}") raise RuntimeError(f"{wheel} does not pin {expected_requirement}; found {requirements}")

2
scripts/gen-third-party-notices.spec.ts
View File

@@ -227,7 +227,7 @@ describe('collectPythonDependencies', () => {
it('excludes normalized local project names without exempting a third-party prefix', () => { it('excludes normalized local project names without exempting a third-party prefix', () => {
const pyprojects = [ const pyprojects = [
'[project]\nname = "deepseek-harness-runtime-bin"\ndependencies = ["pydantic"]\n', '[project]\nname = "deepseek-harness-runtime-bin"\ndependencies = ["pydantic"]\n',
'[project]\nname = "deepseek-harness"\ndependencies = ["DeepSeek.Harness_Runtime-Bin", "deepseek-unrelated"]\n', '[project]\nname = "deepseek-harness-sdk"\ndependencies = ["DeepSeek.Harness_Runtime-Bin", "deepseek-unrelated"]\n',
] ]
expect(() => collectPythonDependencies(pyprojects)).toThrow( expect(() => collectPythonDependencies(pyprojects)).toThrow(
'python dependency deepseek-unrelated is missing from PYTHON_METADATA', 'python dependency deepseek-unrelated is missing from PYTHON_METADATA',

2
scripts/gen-third-party-notices.ts
View File

@@ -83,7 +83,7 @@ const OVERRIDES: Record<string, { license?: string; repo?: string }> = {
* the generator fails when a manifest names a package this map misses. * the generator fails when a manifest names a package this map misses.
*/ */
const PYTHON_METADATA: Record<string, { license: string; repo: string; role: string }> = { const PYTHON_METADATA: Record<string, { license: string; repo: string; role: string }> = {
pydantic: { license: 'MIT', repo: 'https://github.com/pydantic/pydantic', role: 'runtime dependency of `deepseek-harness`' }, pydantic: { license: 'MIT', repo: 'https://github.com/pydantic/pydantic', role: 'runtime dependency of `deepseek-harness-sdk`' },
hatchling: { license: 'MIT', repo: 'https://github.com/pypa/hatch', role: 'build backend' }, hatchling: { license: 'MIT', repo: 'https://github.com/pypa/hatch', role: 'build backend' },
pytest: { license: 'MIT', repo: 'https://github.com/pytest-dev/pytest', role: 'test-only' }, pytest: { license: 'MIT', repo: 'https://github.com/pytest-dev/pytest', role: 'test-only' },
} }