Python SDK Windows x64 runtime
Python SDK Windows x64 运行时
The Python SDK runtime distribution needs a Windows carrier without creating another application entrypoint or weakening the installed-wheel evidence used by the existing native targets. Windows executable names, Python wheel tags, ConPTY addons, ripgrep sidecars, shell composition, virtual environments, and process launch rules differ from Linux and macOS. Claiming Windows from cross-platform unit tests or from a no
English
Problem
The Python SDK runtime distribution needs a Windows carrier without creating another application entrypoint or weakening the installed-wheel evidence used by the existing native targets. Windows executable names, Python wheel tags, ConPTY addons, ripgrep sidecars, shell composition, virtual environments, and process launch rules differ from Linux and macOS. Claiming Windows from cross-platform unit tests or from a non-Windows executable would leave the artifact selected by pip unproved.
Decision
One x64 product
python/sdk-runtime/platforms.json declares one Windows target, win-x64. Its pkg target is node24-win-x64, its runtime wheel tag is py3-none-win_amd64, and its payload is deepseek-harness-sdk-runtime-win-x64.exe with deepseek-harness-sdk-runtime-win-x64-rg.exe. The packaged node-pty tree must contain both x64 ConPTY addons. Runtime lookup rejects Windows arm64 rather than selecting or relabeling the x64 wheel.
The Python process still launches the ordinary dsh --profile sdk application and requires an explicit Harness home under the Python profile-runtime decision. Windows adds no Python-specific Node application, complete-config entrypoint, implicit ~/.dsh, or system Node requirement.
Native build and publication
The executable builder accepts win as a pkg platform only with x64, requires the Windows build to run under x64 Node on a Windows host, preserves .exe names, and copies @vscode/ripgrep-win32-x64 as the conventional -rg.exe sidecar. Pnpm subprocesses use a caller-supplied JavaScript entry through process.execPath. When the caller exposes a .cmd shim, the builder resolves the installed pnpm.mjs or pnpm.cjs through PNPM_HOME; it fails if no JavaScript entry exists instead of spawning the shim or enabling a command shell.
The required GitHub matrix builds node24-win-x64 on windows-2025 beside Linux x64, Linux arm64, macOS arm64, and macOS x64. The public GitHub release and GitLab tag pipeline each publish the same five runtime wheels plus the pure SDK wheel. Windows arm64 is absent from target parsing, manifests, matrices, release contents, and documentation.
Installed-wheel behavior
The Windows lane creates a clean Windows virtual environment, installs the exact SDK and win_amd64 runtime wheels, changes to a directory outside the checkout, unsets PYTHONPATH and DSH_RUNTIME_MODE, and runs the same --scenario all --installed-wheel blackbox as every other target. Trusted pull requests also run the same two-turn sdk-live provider scenario. Fork and Dependabot heads receive no key.
The public Python client gives the initial profile handshake an independent 30-second default through initialize_timeout_seconds. The bound accommodates cold Windows x64 executable startup and profile materialization while still failing a stuck runtime; callers may configure it separately from ordinary request timeouts.
After a successful shutdown response, the Python client closes stdin and waits within the configured shutdown timeout for the dsh context to exit and flush durable session state before terminating it. A failed shutdown retains immediate bounded termination. shutdown_timeout_seconds bounds each of the shutdown request, EOF grace, and termination-confirmation phases, so a pathological close can approach three times that value before the final kill. This distinction preserves the final accepted turn on Windows, where terminate() force-kills the process rather than delivering a catchable signal.
The minimal blackbox uses persistent pwsh plus str_replace_editor on Windows and owns minimal/win-x64/model-visible.json; Linux and macOS retain persistent Bash and the shared minimal/model-visible.json. The advanced process/subagent snapshot and restart/durable-log snapshot remain shared across all targets. The shipped sdk-minimal bundle selects the same platform shell pair for the runnable Python tutorial.
Existing decisions and supersession
This decision partially supersedes the Windows non-goal in the single-file runtime distribution and extends the required target set in the installed Python wheel blackbox decision. Those notes remain authoritative for SEA packaging, the two Python distributions, provenance checks, key handling, and the common blackbox scenarios.
Alternatives considered
Add Windows before the dsh profile runtime. Rejected because tests for the retired private direct-config carrier would not prove the Windows form users receive. Windows is defined only for the sole dsh launch architecture.
Publish Windows arm64 too. Rejected because the accepted product scope is x64 only; adding a second architecture would require its own native builder, wheel tag, ConPTY and ripgrep payload checks, installed-wheel matrix leg, and release artifact.
Give Windows a smaller smoke suite. Rejected because a platform wheel cannot borrow protocol, persistence, worker, MCP, plugin, native-tool, or real-provider evidence from another executable. Platform-specific expected output is limited to the persistent shell surface; the remaining snapshots stay shared.
Run the Windows leg through Git Bash. Rejected because the repository requires native pwsh on Windows runners and MSYS path conversion would not prove native command behavior. Portable one-line steps use each runner's default shell; path, virtual-environment, and blackbox steps have explicit POSIX and PowerShell forms.
Consequences
Python installation selects a Node-free Windows x64 runtime with the same explicit-home and profile customization model as Linux and macOS. Every pull request builds the Windows executable and runtime wheel as one of five native targets, runs the full keyless blackbox, and—on trusted heads—runs the real-provider task. Release validation retains six wheels. Windows arm64 users receive an explicit unsupported-platform failure until a separate native product decision supplies and proves that carrier.
中文
Problem
Python SDK 运行时分发需要 Windows 载体，同时不能创建另一个应用入口，也不能削弱现有原生目标所使用的 installed-wheel 证据。Windows 的可执行文件名、Python wheel 标签、ConPTY addon、ripgrep sidecar、shell 组合、虚拟环境与进程启动规则均不同于 Linux 和 macOS。仅凭跨平台单元测试或非 Windows 可执行文件声称支持 Windows，会使 pip 实际选择的产物未经证明。
Decision
唯一 x64 产品
python/sdk-runtime/platforms.json 声明唯一的 Windows 目标 win-x64。其 pkg 目标是 node24-win-x64，运行时 wheel 标签是 py3-none-win_amd64，载荷包含 deepseek-harness-sdk-runtime-win-x64.exe 与 deepseek-harness-sdk-runtime-win-x64-rg.exe。打包后的 node-pty 文件树必须包含两个 x64 ConPTY addon。运行时查找会拒绝 Windows arm64，不会选择 x64 wheel 或把它重新标记为 arm64。
Python 进程仍按 Python profile 运行时决策启动普通 dsh --profile sdk 应用，并要求显式 Harness home。Windows 不会增加 Python 专用 Node 应用、完整配置入口、隐式 ~/.dsh 或系统 Node 要求。
原生构建与发布
可执行文件构建器仅允许 x64 使用 pkg 的 win 平台，并要求 Windows 构建在 Windows 宿主的 x64 Node 下运行；构建器保留 .exe 文件名，并把 @vscode/ripgrep-win32-x64 复制为常规 -rg.exe sidecar。Pnpm 子进程通过 process.execPath 执行调用方提供的 JavaScript 入口。当调用方暴露 .cmd shim 时，构建器会通过 PNPM_HOME 解析已安装的 pnpm.mjs 或 pnpm.cjs；如果不存在 JavaScript 入口，构建会失败，而不会启动 shim 或启用命令 shell。
必需 GitHub 矩阵会在 windows-2025 上构建 node24-win-x64，与 Linux x64、Linux arm64、macOS arm64 和 macOS x64 并列。公开 GitHub 发布与 GitLab 标签流水线都会发布同一组五个运行时 wheel 加纯 SDK wheel。目标解析、manifest、矩阵、发布内容与文档均不包含 Windows arm64。
Installed-wheel 行为
Windows lane 会创建干净的 Windows 虚拟环境，安装版本精确匹配的 SDK 与 win_amd64 运行时 wheel，切换到 checkout 外的目录，清除 PYTHONPATH 与 DSH_RUNTIME_MODE，再运行与其他目标相同的 --scenario all --installed-wheel 黑盒测试。可信拉取请求还会运行相同的双轮 sdk-live 真实提供方场景。Fork 与 Dependabot head 不会获得密钥。
公开 Python 客户端通过 initialize_timeout_seconds 为首次 profile 握手提供独立的 30 秒默认上限。该上限可容纳 Windows x64 可执行文件冷启动与 profile 物化，同时仍会使卡死的运行时失败；调用方可将其与普通请求超时分开配置。
成功收到 shutdown 响应后，Python 客户端会关闭 stdin，并在已配置的 shutdown 超时内等待 dsh 上下文退出及刷写持久 session 状态，然后才回退到终止进程。Shutdown 失败时仍立即执行有界终止。shutdown_timeout_seconds 会分别限制 shutdown 请求、EOF 宽限与终止确认阶段，因此异常关闭在最终 kill 前可能接近该值的三倍。该区别会保留 Windows 上最后一个已接受轮次；该平台的 terminate() 会强制结束进程，而不是发送可捕获信号。
极简黑盒测试在 Windows 上使用持久 pwsh 与 str_replace_editor，并由 minimal/win-x64/model-visible.json 固定预期；Linux 与 macOS 保留持久 Bash 和共享的 minimal/model-visible.json。高级进程／subagent 快照与重启／持久日志快照继续由所有目标共享。随附的 sdk-minimal 组合包为可运行 Python 教程选择同一组平台 shell。
Existing decisions and supersession
本决策部分取代单文件运行时分发中的 Windows 非目标声明，并扩展安装后 Python wheel 黑盒决策中的必需目标集合。上述 Note 继续负责 SEA 打包、两个 Python distribution、来源校验、密钥处理与通用黑盒场景。
Alternatives considered
在 dsh profile 运行时之前增加 Windows。 否决：针对已退役私有直启载体的测试无法证明 Windows 用户实际获得的形态。Windows 仅定义于唯一的 dsh 启动架构。
同时发布 Windows arm64。 否决：已接受的产品范围只有 x64；增加第二种架构需要独立的原生构建器、wheel 标签、ConPTY 与 ripgrep 载荷校验、installed-wheel 矩阵 lane 及发布产物。
为 Windows 提供较小的冒烟测试套件。 否决：一个平台 wheel 不能借用其他可执行文件的协议、持久化、worker、MCP、插件、原生工具或真实提供方证据。只有持久 shell surface 使用平台专属预期，其余快照继续共享。
通过 Git Bash 运行 Windows lane。 否决：仓库要求 Windows runner 使用原生 pwsh，而 MSYS 路径转换无法证明原生命令行为。可移植的单行步骤使用各 runner 的默认 shell；路径、虚拟环境与黑盒步骤分别提供显式 POSIX 和 PowerShell 形式。
Consequences
Python 安装会选择无需 Node 的 Windows x64 运行时，并与 Linux、macOS 使用同一套显式 home 与 profile 自定义模型。每个拉取请求都会把 Windows 可执行文件和运行时 wheel 作为五个原生目标之一进行构建，运行完整 keyless 黑盒测试，并在可信 head 上运行真实提供方任务。候选发行版验证会保留六个 wheel。Windows arm64 用户会收到明确的不支持平台错误，直到另一项原生产品决策提供并证明该载体。