diff --git a/.github/workflows/build-exe-for-python-sdk.yml b/.github/workflows/build-exe-for-python-sdk.yml index 46eab512bd..8e94476476 100644 --- a/.github/workflows/build-exe-for-python-sdk.yml +++ b/.github/workflows/build-exe-for-python-sdk.yml @@ -2,10 +2,11 @@ name: Build single-exe # Single-file executable (single-exe) builds of the DeepSeek Harness SDK # runtime. The build pipeline and target platforms are specified in -# docs/rfc/implemented/architecture/2026-07-10-single-exe-sdk-runtime.md: each target is -# built natively on a runner of its own platform (no cross-compilation) by -# scripts/build-exe-for-python-sdk.ts, which deploys the dsh-jsonrpc-agent-pkg closure manifest -# closure with @yao-pkg/pkg into dist-exe/. +# docs/rfc/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md: +# each target is built natively on a runner of its own platform (no +# cross-compilation) by scripts/build-exe-for-python-sdk.ts, which deploys +# the dsh-jsonrpc-agent-pkg closure manifest with @yao-pkg/pkg into +# dist-exe/. # # Each build leg uploads two artifacts: # - dsh-jsonrpc-agent-pkg- — the bare single-file exe, for @@ -16,13 +17,15 @@ name: Build single-exe # as-is, the checked-in default runtime/cordis.yml is editable in # place, and the embedded exe also runs directly. # -# workflow_dispatch ONLY — deliberately not triggered by push/pull_request: -# the exe is a release-style deliverable, and the build (full pnpm build + -# pnpm deploy + pkg across a 3-platform matrix, ~100MB per artifact) is far -# too expensive to run as a per-commit CI signal. Dispatch it from the -# Actions tab when artifacts are needed. There is no `ref` input on purpose: -# actions/checkout already checks out the branch/tag the run was dispatched -# on. +# Two explicit triggers, deliberately no per-commit CI: the exe is a +# release-style deliverable, and the build (full pnpm build + pnpm deploy + +# pkg across a 3-platform matrix, ~100MB per artifact) is far too expensive +# to run on every push. Either dispatch it from the Actions tab, or put the +# `build-exe` label on a pull request to build that PR's merge result +# (remove and re-apply the label to rerun); any other label leaves the jobs +# skipped. There is no `ref` input on purpose: actions/checkout already +# checks out the ref the run was triggered on — the dispatched branch/tag, +# or the PR merge ref. on: workflow_dispatch: inputs: @@ -30,11 +33,15 @@ on: description: >- Comma-separated pkg targets to build. Any subset of: node24-linux-x64, node24-linux-arm64, node24-macos-arm64. + Empty builds all three. type: string required: false - default: node24-linux-x64,node24-linux-arm64,node24-macos-arm64 + default: '' + pull_request: + types: [labeled] -# Manual runs on the same ref supersede each other. +# Runs on the same ref supersede each other (per branch/tag for dispatch, +# per PR merge ref for label runs). concurrency: group: ${{ github.workflow }}-${{ github.ref }} cancel-in-progress: true @@ -49,9 +56,11 @@ jobs: # not available in a job-level `if:` (jobs..if only sees # github/needs/vars/inputs), so target selection happens here instead of # skipping matrix legs; an unknown target name fails the whole run loudly - # instead of being silently ignored. + # instead of being silently ignored. The label gate lives here too: `build` + # needs this job, so skipping it skips the whole run. plan: name: plan targets + if: github.event_name == 'workflow_dispatch' || github.event.label.name == 'build-exe' runs-on: ubuntu-latest timeout-minutes: 5 outputs: @@ -60,7 +69,9 @@ jobs: - name: Compute matrix from targets input id: plan env: - TARGETS: ${{ inputs.targets }} + # Empty on label runs and on dispatch with the input left blank — + # both mean "all three targets". + TARGETS: ${{ inputs.targets || 'node24-linux-x64,node24-linux-arm64,node24-macos-arm64' }} run: | set -euo pipefail matrix='[]' diff --git a/docs/rfc/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.i18n.yaml b/docs/rfc/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.i18n.yaml index bf09a201d4..2d879af81f 100644 --- a/docs/rfc/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.i18n.yaml +++ b/docs/rfc/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.i18n.yaml @@ -2,5 +2,5 @@ # 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: # pnpm run verify-translation-pairing --write -2026-07-10-single-file-executable-sdk-runtime-distribution.md: eab441e9b73d49d783a85f457ee84b7f479d86b4 -2026-07-10-single-file-executable-sdk-runtime-distribution.zh.md: 4244d9e4e3af6cb04618c24cfa72ef77cd17335c +2026-07-10-single-file-executable-sdk-runtime-distribution.md: 4fab5f89542753f2dd5977d4262e1310097f4545 +2026-07-10-single-file-executable-sdk-runtime-distribution.zh.md: 56a93f2392bff655d32ec4947c357b33d9e6da5e diff --git a/docs/rfc/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md b/docs/rfc/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md index eab441e9b7..4fab5f8954 100644 --- a/docs/rfc/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md +++ b/docs/rfc/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md @@ -42,7 +42,7 @@ The deploy root is [`python/sdk-runtime/package.json`](../../../../python/sdk-ru [`scripts/build-exe-for-python-sdk.ts`](../../../../scripts/build-exe-for-python-sdk.ts): `pnpm run build` → (after clearing) `pnpm --filter dsh-jsonrpc-agent-pkg deploy --legacy --prod --config.node-linker=hoisted --config.auto-install-peers=false --config.link-workspace-packages=true` **directly into** `python/sdk-runtime/src/deepseek_harness_runtime/runtime/node/` → inject the pkg configuration (`bin` points at `node_modules/@deepseek-ai/dsh-jsonrpc-agent/lib/bin.js` inside the closure, `assets` is a full glob — dynamic import is invisible to pkg's static analysis, so everything must be packed in explicitly) → one `pkg --sea` per target → the artifacts `dsh-jsonrpc-agent-pkg--` land in `dist-exe/` (the CI artifact) and are copied back into the runtime directory. All four deploy flags are grounded in measurement: `--legacy` is the mandatory path with inject-workspace-packages off; hoisted yields a zero-symlink file tree (most stable for the pkg VFS, physically guaranteeing a single cordis instance); disabling automatic peer installation keeps unpublished package names from triggering registry resolution; link-workspace-packages points the closure at workspace/vendor sources. -CI: [`.github/workflows/build-exe-for-python-sdk.yml`](../../../../.github/workflows/build-exe-for-python-sdk.yml), manually triggered via `workflow_dispatch` only; native builds on the three platforms linux-x64 / linux-arm64 (`ubuntu-24.04-arm`) / macos-arm64, with `~/.pkg-cache` cached and artifacts uploaded per platform; macOS ad-hoc signing is handled by pkg. Windows is a non-goal. +CI: [`.github/workflows/build-exe-for-python-sdk.yml`](../../../../.github/workflows/build-exe-for-python-sdk.yml), triggered explicitly only — `workflow_dispatch`, or the `build-exe` label on a pull request; native builds on the three platforms linux-x64 / linux-arm64 (`ubuntu-24.04-arm`) / macos-arm64, with `~/.pkg-cache` cached and artifacts uploaded per platform; macOS ad-hoc signing is handled by pkg. Windows is a non-goal. ### Python SDK distribution: two carriers, exe for production, node for development diff --git a/docs/rfc/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.zh.md b/docs/rfc/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.zh.md index 4244d9e4e3..56a93f2392 100644 --- a/docs/rfc/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.zh.md +++ b/docs/rfc/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.zh.md @@ -42,7 +42,7 @@ deploy root 是 [`python/sdk-runtime/package.json`](../../../../python/sdk-runti [`scripts/build-exe-for-python-sdk.ts`](../../../../scripts/build-exe-for-python-sdk.ts)：`pnpm run build` →（清空后）`pnpm --filter dsh-jsonrpc-agent-pkg deploy --legacy --prod --config.node-linker=hoisted --config.auto-install-peers=false --config.link-workspace-packages=true` **直落** `python/sdk-runtime/src/deepseek_harness_runtime/runtime/node/`→ 注入 pkg 配置（`bin` 指闭包内 `node_modules/@deepseek-ai/dsh-jsonrpc-agent/lib/bin.js`，`assets` 全量 glob——动态 import 对 pkg 静态分析不可见，必须显式全量打入）→ 每 target 一次 `pkg --sea` → 产物 `dsh-jsonrpc-agent-pkg--` 落 `dist-exe/`（CI artifact）并拷回 runtime 目录。deploy 四 flag 均有实测依据：`--legacy` 是未开 inject-workspace-packages 时的必选路径；hoisted 产出零符号链接文件树（pkg VFS 最稳、物理保证 cordis 单实例）；关 peer 自动安装避免未发布包名触发 registry 解析；link-workspace-packages 让闭包指向 workspace/vendor 源。 -CI：[`.github/workflows/build-exe-for-python-sdk.yml`](../../../../.github/workflows/build-exe-for-python-sdk.yml)，仅 `workflow_dispatch` 手动触发，linux-x64 / linux-arm64（`ubuntu-24.04-arm`）/ macos-arm64 三平台原生构建，`~/.pkg-cache` 缓存，artifact 按平台上传；macOS ad-hoc 签名由 pkg 处理。Windows 是非目标。 +CI：[`.github/workflows/build-exe-for-python-sdk.yml`](../../../../.github/workflows/build-exe-for-python-sdk.yml)，仅显式触发——`workflow_dispatch` 手动派发，或给 PR 打 `build-exe` 标签；linux-x64 / linux-arm64（`ubuntu-24.04-arm`）/ macos-arm64 三平台原生构建，`~/.pkg-cache` 缓存，artifact 按平台上传；macOS ad-hoc 签名由 pkg 处理。Windows 是非目标。 ### Python SDK 分发：双载体，exe 为生产、node 为开发 diff --git a/python/README.i18n.yaml b/python/README.i18n.yaml index 29c3b03096..b337d2c288 100644 --- a/python/README.i18n.yaml +++ b/python/README.i18n.yaml @@ -2,5 +2,5 @@ # 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: # pnpm run verify-translation-pairing --write -README.md: 56199c1daaac4d55a29dae8852277f0ba77238b2 -README.zh.md: e34f3afd455926bd6b09d3451509594cee78ad88 +README.md: 294cbd1eb0690de17fa70f3049bb4677e1fd135a +README.zh.md: f89d1612f6ac454b3a57515b5a1a0f3c59c579d1 diff --git a/python/README.md b/python/README.md index 56199c1daa..294cbd1eb0 100644 --- a/python/README.md +++ b/python/README.md @@ -22,7 +22,7 @@ pnpm exec tsx scripts/build-exe-for-python-sdk.ts --skip-build # lib/ artifac pnpm exec tsx scripts/build-exe-for-python-sdk.ts --targets=node24-linux-x64,node24-linux-arm64,node24-macos-arm64 ``` -Products land in `dist-exe/` (CI artifact shape) and are synced into this package at `sdk-runtime/src/deepseek_harness_runtime/runtime/dsh-jsonrpc-agent-pkg--` (platform: `linux`/`macos`; arch: `x64`/`arm64`) — after a build the SDK finds the executable with no further setup. Alternatively, download the platform artifact from the `build-exe-for-python-sdk` CI workflow (manual dispatch) and place it at that same path. Which plugins the exe bundles and how the carriers are organized: [sdk-runtime README](sdk-runtime/README.md); the build also refreshes the dev-only node carrier (see "against the Node source" below). +Products land in `dist-exe/` (CI artifact shape) and are synced into this package at `sdk-runtime/src/deepseek_harness_runtime/runtime/dsh-jsonrpc-agent-pkg--` (platform: `linux`/`macos`; arch: `x64`/`arm64`) — after a build the SDK finds the executable with no further setup. Alternatively, download the platform artifact from the `build-exe-for-python-sdk` CI workflow (manual dispatch, or the `build-exe` PR label) and place it at that same path. Which plugins the exe bundles and how the carriers are organized: [sdk-runtime README](sdk-runtime/README.md); the build also refreshes the dev-only node carrier (see "against the Node source" below). ## Validating the SDK against the executable diff --git a/python/README.zh.md b/python/README.zh.md index e34f3afd45..f89d1612f6 100644 --- a/python/README.zh.md +++ b/python/README.zh.md @@ -22,7 +22,7 @@ pnpm exec tsx scripts/build-exe-for-python-sdk.ts --skip-build # lib/ artifac pnpm exec tsx scripts/build-exe-for-python-sdk.ts --targets=node24-linux-x64,node24-linux-arm64,node24-macos-arm64 ``` -产物落入 `dist-exe/`（CI 产物形态），并同步进本包的 `sdk-runtime/src/deepseek_harness_runtime/runtime/dsh-jsonrpc-agent-pkg--`（platform：`linux`/`macos`；arch：`x64`/`arm64`），构建完成后 SDK 不需要额外设置就能找到可执行文件。也可以从 `build-exe-for-python-sdk` CI workflow（手动触发）下载对应平台的产物放到同一路径。exe 内置哪些插件、载体如何组织，见 [sdk-runtime README](sdk-runtime/README.md)；构建还会顺带刷新仅供开发用的 node 载体（见下文「对着 Node 源码运行」）。 +产物落入 `dist-exe/`（CI 产物形态），并同步进本包的 `sdk-runtime/src/deepseek_harness_runtime/runtime/dsh-jsonrpc-agent-pkg--`（platform：`linux`/`macos`；arch：`x64`/`arm64`），构建完成后 SDK 不需要额外设置就能找到可执行文件。也可以从 `build-exe-for-python-sdk` CI workflow（手动触发，或给 PR 打 `build-exe` 标签）下载对应平台的产物放到同一路径。exe 内置哪些插件、载体如何组织，见 [sdk-runtime README](sdk-runtime/README.md)；构建还会顺带刷新仅供开发用的 node 载体（见下文「对着 Node 源码运行」）。 ## 用可执行文件验证 SDK