84 lines
11 KiB
Markdown
84 lines
11 KiB
Markdown
# RFC: 单文件可执行的 SDK 运行时分发（single-exe）
|
||
|
||
Status: implemented
|
||
|
||
[English](2026-07-10-single-file-executable-sdk-runtime-distribution.md) | 中文
|
||
|
||
## 问题
|
||
|
||
DeepSeek Harness 需要为 Python 库专门提供一个免安装 Node、可直接在目标平台运行的 SDK 分发形态：一个单文件可执行程序（下称 exe），对外提供 stdio JSON-RPC 服务面（`HarnessSdkServer`，Python SDK 的对端），且实际启动的插件与配置完全由 exe 外部输入的 `cordis.yml` 决定。
|
||
|
||
- 与 Python SDK 通信的 JSONRPC 协议已经过验证
|
||
- 需要提供标准化的 cordis.yml 加载所有插件（ESModule）的能力
|
||
- 分发物要自带 Node 运行时，并支持本地源码链接的调试模式
|
||
|
||
## 决策
|
||
|
||
### 打包路线：@yao-pkg/pkg 的 `--sea` 模式
|
||
|
||
exe 用 [@yao-pkg/pkg](https://github.com/yao-pkg/pkg)（vercel/pkg 归档后的活跃维护 fork）的 **`--sea`（enhanced SEA）模式**打包。相比 Node 原生 SEA，pkg 在其上加装 `/snapshot` VFS 与运行时模块钩子，ESM 入口原样交给 Node 默认 ESM loader，不依赖任何 ESM→CJS 转译。
|
||
> 实测（macos-arm64、node24 target、pkg 6.21.0）：VFS 内裸包名 ESM 动态 import（含顶层 await）、CJS 互操作、`node:sqlite`、集合外包名 fail loud、VFS 外磁盘 ESM import 全部通过，`import.meta.url` 原样为 `file:///snapshot/...`。
|
||
|
||
`--sea` 要求 target ≥ node22，exe 统一以 node24 为 target；单次 pkg 调用只打一个 target，多平台各调一次。
|
||
|
||
术语提醒：pkg 的 `/snapshot` VFS 与本仓库测试体系的「snapshot」（ACP replay goldens、`$DSH_SNAPSHOT`）无关，本文用「VFS」指前者。
|
||
|
||
### serving 面是插件：ui/jsonrpc + ui/jsonrpc-agent 两包
|
||
|
||
确定性协议实现（`server.ts` / `transport.ts`）按 `ui/acp` + `ui/acp-agent` 的既有模式落为两包——serving 面本身也是插件：
|
||
|
||
- [`packages/ui/jsonrpc`](../../../../packages/ui/jsonrpc/README.md)（`@deepseek-ai/dsh-jsonrpc`）：纯协议插件，apply 时在进程 stdio 上挂 `HarnessSdkServer` + 行式 JSON-RPC transport，disposal 走 `ctx.effect()`。是否服务由 `cordis.yml` 决定；一份 yml 没挂它就是一个不 serve 的合法进程。协议级退出归插件（`shutdown` 请求应答后 dispose 自身 fiber 再 `exit(0)`；HMR 式卸载只停服务不退进程）。
|
||
- [`packages/ui/jsonrpc-agent`](../../../../packages/ui/jsonrpc-agent/README.md)（`@deepseek-ai/dsh-jsonrpc-agent`）：薄 app bin——`installFailLoud` + `loadEnv` + 配置发现 + [`dsh-app-boot`](../../../../packages/ui/app-boot/src/index.ts) 的 `boot()`，boot 完即毕，server 由 yml 里的 `dsh-jsonrpc` 条目带起。依赖只有 app-boot。进程级退出归 bin（stdin EOF/SIGTERM → dispose 后 0，SIGINT → 130）。
|
||
|
||
配置发现两通道，缺失即报错：`DSH_CORDIS_CONFIG` 环境变量优先（SDK 客户端约定），argv 位置参数次之；无任何默认路径或内置回退——「实际启动的插件由外部 cordis.yml 决定」是硬语义。
|
||
|
||
### 插件解析：VFS 装真实包树，闭包清单即 deploy root
|
||
|
||
exe 的 VFS 内是**构建产物形态的真实包树**（各包 `lib/` + 真实 `node_modules`），Loader 解析插件名走标准动态 `import()`：裸包名从 VFS 内 Loader 位置沿 `node_modules` 向上解析，天然落在 VFS 内。封闭集不需要白名单代码——集合就是 VFS 里装了什么，引用集合外的名字 import 失败。
|
||
|
||
deploy root 是 [`python/sdk-runtime/package.json`](../../../../python/sdk-runtime/package.json)（`dsh-jsonrpc-agent-pkg`，pnpm workspace 成员、零代码纯依赖清单）——「exe 装什么插件」与「Python runtime 分发什么」的合一事实源。往 exe 加插件 = 清单加一行依赖再重打包。两条实测得来的闭包完整性规则：闭包成员以 peerDependency 引用的仓库内纯库（`dsh-brand`、`dsh-timeout`、`dsh-invariants`、`@cordisjs/plugin-timer`）必须显式列进清单 `dependencies`；deploy 按各包 `files` 打包，tsdown 拆出的共享 chunk 必须被 `files` 覆盖。
|
||
|
||
### 构建管线与产物
|
||
|
||
[`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-<platform>-<arch>` 落 `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 是非目标。
|
||
|
||
### Python SDK 分发：双载体，exe 为生产、node 为开发
|
||
|
||
Python SDK 位于 [`python/`](../../../../python/README.md)：`python/sdk`（客户端）+ `python/sdk-runtime`（运行时载体包）。runtime 包数据目录三类内容：检入的默认 `runtime/cordis.yml`、构建注入的平台 exe、构建注入的 `runtime/node/` 闭包树。`resolve_bundled_launch_args()` 自动解析**只找 exe**；node 载体仅显式 `DSH_RUNTIME_MODE=node` 启用（跑 `runtime/node/node_modules/@deepseek-ai/dsh-jsonrpc-agent/lib/bin.js`，需系统 node ≥22.19），定位是本仓库成员的开发验证通道，不进 wheel/sdist 分发物。
|
||
|
||
exe「必须显式配置」的硬语义不变；零配置体验由 wrapper 恢复：调用方没给 `cordis`、没显式指定 runtime、环境无 `DSH_CORDIS_CONFIG` 时，客户端把检入的默认 `cordis.yml`（agent-core + 预载 llm-deepseek + JSONL 持久化 + bash-local + `dsh-jsonrpc` serving 条目，`!!js` 环境变量兜底）显式注入 `DSH_CORDIS_CONFIG`。
|
||
|
||
### 命名血统
|
||
|
||
`@deepseek-ai/dsh-jsonrpc-agent`（包）→ `dsh-jsonrpc-agent`（bin）→ `dsh-jsonrpc-agent-pkg`（闭包清单；无 scope 前缀，刻意避开 constraints 对 `@deepseek-ai/dsh-*` 的包形状规则）→ `dsh-jsonrpc-agent-pkg-<platform>-<arch>`（exe 产物）。wire `serverInfo.name` 保持 `deepseek-harness-sdk-runtime`（协议稳定值）；Python dist 名为 `deepseek-harness` / `deepseek-harness-runtime-bin`。
|
||
|
||
## worker 类插件的处置
|
||
|
||
`dsh-workflow-workerthread` 与 `dsh-code-runtime-worker` 以 `new Worker(new URL('./worker.js', import.meta.url))` 依赖磁盘兄弟文件。PoC 实测：pkg 的 Worker 补丁只拦截**字符串路径**，URL 对象形态在 VFS 内找不到文件——修法已明确（`fileURLToPath()` 转字符串），但本期评审决策是**不验证、不承诺、不处理**：它们随全量集合编译进 exe，外部 `cordis.yml` 引用时行为未定义。
|
||
|
||
## 测试
|
||
|
||
验证面分三层。机制层：`--sea` 链路的实测结论内嵌在「决策」各节（VFS 内 ESM 动态 import、cordis 单实例、fail-loud 配置链路、`node:sqlite`、macOS ad-hoc 签名可运行）。SDK 层：`python/sdk/tests` 的 28 例 pytest 覆盖客户端协议（18 例，keyless、假运行时对端）、双载体启动（6 例，产物缺失时独立 skip）与载体解析规则（4 例）。端到端层：验收物料（keyless 五项：env 通道启动、缺配置 fail-loud、坏插件名 fail-loud、配置通道、mock 端点完整回合 + JSONL 落盘；带 key 两项：真实回合、bash 工具写 marker 文件的世界校验 + 干净退出）由真实 Python SDK 客户端驱动 exe。当前欠账：上述套件对当前产物的运行与 built-exe e2e。JSON-RPC 协议不在 ACP snapshot 体系内，无 snapshot 层（点名后的明确空缺，非遗漏）。
|
||
|
||
手工驱动注意：bin 视 stdin EOF 为「客户端已走」并立即 dispose，短命管道会中止在飞回合——管道驱动必须保持 stdin 打开到回合结束。
|
||
|
||
## 曾考虑的替代方案
|
||
|
||
**Node 原生 SEA 裸用。** 注入主脚本必须是 CJS 单文件、blob 内无文件系统与模块解析，动态 import 裸包名无从解析，只能把插件静态编译进主脚本并手工注册——绕过标准模块解析、插件集合被硬编码，与「配置决定一切」相悖。最终路线实为「官方 SEA 地基 + pkg 的 VFS/模块钩子层」，否掉的是裸用而非 SEA 本身。
|
||
|
||
**pkg standard 模式。** PoC 判死，非取舍：它把 ESM 经 esbuild 转 CJS + V8 字节码，运行时 vm 编译未接动态 import 回调，任何 `import()` 一律抛 `ERR_VM_DYNAMIC_IMPORT_CALLBACK_MISSING`，`--options experimental-require-module` 无效；且依赖社区补丁 Node 二进制（macos-arm64 无预编译，现场源码编译约 10 分钟）。对本仓库架构零可行性。
|
||
|
||
**每包 ESM→CJS 预打包进 VFS。** 保持真实解析语义、只降级模块格式的折中；`--sea` 直接通过实测，这层构建复杂度无需引入。
|
||
|
||
**jsonrpc-agent 背全量闭包依赖。** app bin 声明 53+ 个它不 import 的依赖，「打包清单」冒充真实依赖关系，且迫使 constraints 为其开 cordis-in-dependencies 与 files-通配两个例外。闭包清单落在 python 侧的清单包上，constraints 无需任何例外，bin 保持与 acp-agent 同构的正常包形状。
|
||
|
||
**开放插件集（磁盘加载用户插件）。** 本期封闭集；PoC 顺带证实 VFS 外磁盘 ESM import 可行（经 `ctx.baseUrl` 相对路径通道），列为后续演进，需另解外部插件与 exe 内 cordis 实例的共享问题。
|
||
|
||
## 后果
|
||
|
||
**买到的**：目标平台零依赖单文件分发；插件语义与源码运行严格一致（同一棵真实包树，无转译无注册表）；serving 面、插件集、配置三者全部收敛到 `cordis.yml` + 一份依赖清单两个事实源；exe 与 node 双载体同树同语义，开发验证不必等打包；官方 Node 二进制消除了补丁二进制供应链顾虑。
|
||
|
||
**付出的**：产物 174MB 级且源码原样进 blob（无字节码混淆，闭源分发诉求需另行评估）；pkg 的 VFS/模块钩子层仍是社区维护（构建脚本钉死 `@yao-pkg/pkg@6.21.0`，升级走显式改动）；`--sea` 单 target 单次调用（与 CI 每平台一腿匹配，本地多平台构建串行）；worker 类插件在 exe 内行为未定义；验收与覆盖率存在补跑欠账（见「测试」）。
|