Tianyi Cui
3c1c6a89b1
* test(python): exercise installed wheels as black boxes Add an installed-wheel mode that refuses source/editable imports, repository working directories, mismatched SDK/runtime versions, unpinned runtime dependencies, and executables outside the installed runtime distribution. The mode resolves the wheel-owned executable itself, so callers cannot accidentally prove an explicit checkout artifact. Add a real-API scenario that drives two tool-using turns through the public synchronous SDK, verifies the file bytes outside the agent, checks completed turn/tool events and persistence, and projects provider failures without retaining credential-bearing error text. The existing deterministic scenario set remains the keyless behavior oracle. Refs #2952. * ci(python): require installed-wheel checks on every release target Move the complete deterministic runtime scenarios behind construction and clean installation of the SDK and matching runtime wheels. Each native leg runs outside the checkout with source-resolution environment variables removed; Linux manylinux smokes assert the same installed provenance. Expand the required pull-request call from Linux x64 to Linux x64, Linux arm64, and macOS arm64. Trusted heads receive only DEEPSEEK_API_KEY_EXTERNAL for a fail-loud live two-turn smoke on each carrier, while fork and Dependabot heads retain the full keyless path without exposing secrets. Pin the reusable secret declaration, matrix call, aggregate dependency, untrusted-head condition, and live/keyless commands in the workflow contract test. Refs #2952. * docs(testing): make installed wheels the Python CI authority Record the clean-wheel provenance boundary, complete keyless scenario set, trusted real-API contract, secret handling, and three-target required topology in a new implemented testing decision. Update the SEA distribution and portable-CI authorities plus the Python contributor reference to describe the same current state. Archive the fully superseded Linux-x64-only decision after consolidating its rationale and alternatives into the new owner. Preserve its bilingual triplet as a sealed historical snapshot and redirect every active current-state reference. Refs #2952.
6.4 KiB
Python 贡献者工作流
English | 中文
根据所需的贡献者成果选择工作流：构建运行时产物、验证 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 辅助程序。
验证 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 会运行可用的内置载体；某个载体的产物尚未构建时，会跳过该载体。仓库级测试政策见 测试。
该套件面向的是伪造的运行时对端。scripts/smoke-python-runtime.py 面向打包运行时。必需的 python-runtime CI 任务会构建每个已发布原生目标，把匹配的 SDK wheel 包与运行时 wheel 包安装进新的 Python 3.10 虚拟环境，在 checkout 外清除 PYTHONPATH 与 DSH_RUNTIME_MODE 后运行，证明两个模块及可执行文件都来自这些 distribution，然后运行全部 keyless 场景。聚焦的本地源码 SDK 运行可以选择一个已构建可执行文件与场景：
uv run --project python/sdk python scripts/smoke-python-runtime.py \
--scenario sdk-minimal --exe dist-exe/dsh-jsonrpc-agent-pkg-macos-arm64
其中三个场景会比对 scripts/snapshots/python-sdk-single-exe/ 下已提交的期望输出。minimal/model-visible.json 固定了签入的极简组合所组装的系统提示词、对外公布的工具 schema 以及模型可见消息，因此插件一旦贡献出计划外的系统分段或 user 消息，该任务即失败；它会丢弃动态运行时上下文快照——同一组合在 macOS 上会发出它，在 Linux 上不会（#2488）。advanced/ 固定一个复杂进程的 SDK 结果及父／子会话日志。restart/ 针对同一持久化根目录启动两个完整 SDK 运行时进程，并固定其彼此隔离的模型历史、高层结果与独立持久日志。重新运行对应场景时加上 --update-snapshots，并在提交前审阅该差异。
可信拉取请求还会在每个原生目标上运行 --scenario sdk-live --installed-wheel。该场景面向 https://api.deepseek.com 执行两个使用工具的轮次，从外部验证已创建文件，并在仓库密钥缺失时失败而不是自行 skip。Fork 与 Dependabot 拉取请求会运行完整的 keyless 安装后 wheel 路径，但不会获得密钥。
交互式冒烟测试需要环境变量或仓库根目录 .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/sdk/python-runtime/src/packaged-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="$(python - <<'PY'
import runpy
release = runpy.run_path("scripts/build-python-release.py")
print(release["pep440_version"](release["repository_version"]()))
PY
)"
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 \
"dist-python/deepseek_harness_sdk-$version-py3-none-any.whl" \
"dist-python/deepseek_harness_runtime_bin-$version-py3-none-macosx_14_0_arm64.whl"
运行时分发包仅提供 wheel 包。发布流水线会连同纯 SDK wheel 包一起发布三个平台 wheel 包：Linux x64、Linux arm64 和 macOS 14 或更高版本的 arm64。只有与仓库版本匹配时，才接受 python-v<repository-version> 标签；0.0.1-rc.1 之类的仓库预发布版本在 wheel 包文件名和元数据中使用规范化的 PEP 440 写法，例如 0.0.1rc1。
验证候选发行版
手动运行 GitHub 的 Release (Python) 工作流并设置 publish=false，即可构建全部四个 wheel 包，在 Python 3.10 和 3.14 上安装 Linux 发行集合，检查精确文件名和元数据，执行 PyPI 默认单文件大小限制，并保留一份带 SHA-256 哈希的汇总产物。该运行没有注册表凭据，dry-run 运行无法进入任何发布作业。
公开发布从私有自动化仓库运行；包元数据指向独立的只读公开源码镜像，该镜像不运行发布 Actions。私有仓库把仓库变量 PYPI_PUBLISHER_REPOSITORY 定义为自身的 owner/name，并且只在有意发布期间把 PUBLIC_PYPI_RELEASE_ENABLED 从 false 改为 true。
独立的运行时与 SDK 作业使 SDK 上传失败后可以继续执行，而无需重新发送不可变的运行时文件。只有工作流从配置的发布仓库、匹配的 python-v* 标签运行，且受保护的 pypi-runtime 和 pypi 环境分别批准运行时与 SDK 作业时，才接受 publish=true。PyPI Trusted Publishing 仍会提供短期 OIDC 凭据，但公开 attestation 会披露私有发布仓库身份，因此将其禁用。