From 1a7b4639c364005ffeacb99e3d3c8ca914a2925c Mon Sep 17 00:00:00 2001 From: Leo Date: Mon, 6 Jul 2026 04:51:39 +0000 Subject: [PATCH] =?UTF-8?q?docs(code):=20DESIGN.md=20=E6=9B=B4=E6=96=B0?= =?UTF-8?q?=E7=82=BA=E3=80=8C=E8=A3=81=E5=AE=9A=20A=E3=80=81Workers=20?= =?UTF-8?q?=E5=B0=B1=E7=B7=92=E3=80=8D=E7=9A=84=E6=9C=80=E7=B5=82=E7=8B=80?= =?UTF-8?q?=E6=85=8B?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_01HJiLCRUU2o3aSpPEzVCt2o --- registry/components/code/DESIGN.md | 17 +++++++++++++---- 1 file changed, 13 insertions(+), 4 deletions(-) diff --git a/registry/components/code/DESIGN.md b/registry/components/code/DESIGN.md index af884fb..15a7297 100644 --- a/registry/components/code/DESIGN.md +++ b/registry/components/code/DESIGN.md @@ -1,6 +1,6 @@ # `code` 零件 —— 沙箱設計小結（Arcrun#10） -> 狀態：設計 + PoC（Node/vitest 綠燈），**未部署 leo21c**。live 前需總管與 leo 過寫入/部署閘。 +> 狀態：**Workers 就緒（裁定 A，可部署）**，Node/vitest 12/12 綠燈，**未部署 leo21c**。live 前需總管與 leo 過寫入/部署閘。封裝＝A（quickjs-emscripten singlefile variant）；B（自建 QuickJS+wasi-sdk）列後續技術債。 ## 0. arcrun 零件 runtime 真相（先摸清再設計） @@ -28,10 +28,19 @@ Cloudflare Worker isolate（V8） - **input 穿越邊界**：以 JSON 字串 marshal，沙箱內 `JSON.parse` —— host 與 guest **不共享物件圖**，杜絕 prototype/引用逃逸。 - **user code 形狀**：當「函式體」跑（可含 `const`/`function` 宣告、以 `return` 回值），綁定唯一入參 `input`。回值 `JSON.stringify` 後交回 host。 -## 2. 生產路徑（PoC → live 的差異） +## 2. 生產路徑（裁定 A，已就緒） -- **PoC**（本目錄 `sandbox.mjs` + `test/`）：用 `quickjs-emscripten`（預編 QuickJS wasm）在 **Node/vitest** 跑，證明沙箱**語義**。`sha256` 以 Node `node:crypto` 實作。**12 測試全綠**，含 card→envelope 全等。 -- **live（Worker）**：`quickjs-emscripten` 有 Cloudflare Workers 相容 variant，可直接在零件 Worker 內用。**唯一要改**：`sha256` 不用 host function（Worker 的 Web Crypto `crypto.subtle.digest` 是 async，跟 QuickJS 同步 host-call 不合），改成**把純 JS SHA-256 當 prelude 字串注入沙箱**（無 host call、Node/Worker 皆決定性）。這也讓「curated builtin = 純演算法字串」成為往後加 builtin 的標準做法。 +`sandbox.mjs` 為 **runtime-agnostic 核心**，Node 測試與 CF Worker **共用同一份**： + +- **封裝**：`@jitl/quickjs-singlefile-mjs-release-sync` variant（wasm 內嵌 base64、同步載入） + —— CF Workers 相容 loading 路徑（不靠 fetch/fs 取 .wasm），bundler 友善、無需 `[[wasm_modules]]`。 +- **`sha256` curated builtin**：以**純 JS SHA-256 字串 prelude** 注入沙箱（不呼叫 host、不用 async + Web Crypto、不需 `nodejs_compat`），Node/Worker 皆決定性；與 Node crypto sha256 逐字等價 + （測試 ⑤ 對 card 全文比對 content_hash 相同）。「curated builtin = 純演算法字串」定為往後標準。 +- **Worker host**：`index.ts`（Hono，POST /→`runCode`），自足 Worker，不走 TinyGo 模板流程。 +- **測試**：`sandbox.mjs` + `test/` 在 **Node/vitest 12/12 全綠**（含 card→envelope 全等）。 +- **與 B 的差**：B（自建 QuickJS+wasi-sdk→preview1 wasm，跑現有 WASI host shim）最同構，但需 + wasi-sdk 工具鏈（本環境無 sysroot）＋維護 C harness，列後續技術債。 ## 3. 資源限制（防跑飛）