chore(desktop): 打包时裁剪桌面运行时的多余产物

打包出的 macOS arm64 未压缩应用约 518MB，其中 staging 的 Node 运行时仍带着
调试元数据、完整的 Phosphor 图标包，以及 PDF.js 的两套构建。Phosphor 图标
已经内联进 Studio 的浏览器资源，Node 侧的 PDF 适配器只 import legacy 入口，
因此这些体积对运行时没有价值。

新增 scripts/prune-desktop-runtime.mjs 作为保留/丢弃规则的唯一归属，在
stage.mjs 完成 --omit=dev 安装后调用：删除 *.map、*.d.ts/.d.mts/.d.cts 和
包内 README，移除 @phosphor-icons，PDF.js 只保留 legacy/build/pdf.mjs、
pdf.worker.mjs 与 cmaps/wasm/standard_fonts/iccs/image_decoders 支持树。
路径遍历统一走 node:path，不按 '/' 切分原生路径。

验证：npm test -w @qoder-ai/better-harness-desktop 10 项通过，其中三项在
fixture 树上断言保留与丢弃行为；harness-studio 的 pdf-artifact-adapter
测试 4 项通过，确认 legacy 入口仍可加载；实际 stage 裁掉 5394 个文件，
staged node_modules 从 285MB 降到 141MB。

Co-authored-by: Qoder (Grok 4.6) <qoder_ai@qoder.com>

Author: phodal

docs/specs/2026-09-10-desktop-runtime-prune.md

@@ -0,0 +1,67 @@
+# Desktop runtime prune for debug metadata, Phosphor, and PDF.js
+
+## Traceability
+
+- Spec ID: `2026-09-10-desktop-runtime-prune`
+- Status: Implemented
+- Request: shrink the packaged Harness Studio `.app` by dropping pack-time debug metadata, unused Phosphor files, and unused PDF.js trees
+- AI involvement: implementation and local validation by Grok 4.6
+
+## Intent
+
+The unpacked macOS arm64 app is about 518MB. Chromium is most of that, but the
+staged Node runtime still ships debug metadata, the full Phosphor icon package,
+and both PDF.js builds. Phosphor icons are already bundled into Studio's
+browser assets, and the Node PDF adapter imports only the legacy PDF.js entry.
+Staging should keep the runtime those two facts require and drop the rest
+before electron-builder packs `dist/app`.
+
+## Acceptance Scenarios
+
+- **AC-1** Given a staged desktop `node_modules` tree, when staging finishes,
+  then `*.map`, `*.d.ts` / `*.d.mts` / `*.d.cts`, and package README files are
+  gone, while runtime JavaScript, LICENSE files, native addons, and WASM remain.
+- **AC-2** Given `@phosphor-icons/react` in the production closure, when staging
+  finishes, then no `@phosphor-icons` package remains under staged
+  `node_modules`. The Studio browser bundle already inlines the icons it uses.
+- **AC-3** Given `pdfjs-dist` in the production closure, when staging finishes,
+  then the modern `build/` tree, viewer `web/` trees, types, webpack helper,
+  minified copies, and source maps are gone, while `legacy/build/pdf.mjs`,
+  `legacy/build/pdf.worker.mjs`, and the runtime support trees (`cmaps`,
+  `wasm`, `standard_fonts`, `iccs`, `image_decoders`) remain. The Node adapter
+  can still load `pdfjs-dist/legacy/build/pdf.mjs`.
+- **AC-4** Given the prune owner, when its tests run, then they assert keep and
+  drop behaviour on a fixture tree rather than grepping packaged markup.
+
+## Non-goals
+
+- Shrinking Electron Framework / Chromium.
+- Shiki language subsetting or dropping `esbuild-wasm`.
+- Changing Studio's PDF adapter to the modern `pdfjs-dist/build` entry. That
+  build loads in Node but warns to use `legacy`; this change keeps the working
+  Node path.
+- Moving Phosphor to `devDependencies` in the npm package. Desktop staging is
+  the pack-time owner; the Studio CLI package layout stays unchanged.
+- Signing, notarization, or a smaller published npm tarball.
+
+## Plan and Tasks
+
+1. Add `packages/better-harness-desktop/scripts/prune-desktop-runtime.mjs` as
+   the keep/drop owner. Walk with `node:path` / `readdir`; do not split native
+   paths on `/`.
+2. Call it from `scripts/stage.mjs` after the production `npm install`.
+3. Cover AC-1..AC-4 with `node:test` fixtures next to the existing desktop
+   protocol tests.
+4. Restage and confirm Phosphor is absent, PDF.js legacy entry still imports,
+   and staged `node_modules` is smaller.
+
+## Test and Review Evidence
+
+- `npm test -w @qoder-ai/better-harness-desktop`: 10 passed, including the three
+  prune keep/drop tests (AC-1, AC-2, AC-3, AC-4).
+- `npm exec -w @qoder-ai/harness-studio -- vitest run test/pdf-artifact-adapter.test.ts`:
+  4 passed against the workspace PDF.js install.
+- `npm run stage -w @qoder-ai/better-harness-desktop` pruned 5394 files. Staged
+  `node_modules` went from 285MB to 141MB. `@phosphor-icons` is absent.
+  `pdfjs-dist` is 7.8MB and still exports `getDocument` from
+  `legacy/build/pdf.mjs`. Zero leftover `*.map`, `*.d.ts`, or README files.

packages/better-harness-desktop/README.md

@@ -11,7 +11,10 @@ npm run better-harness-desktop:dev
 ```
 
 `npm run better-harness-desktop:pack` builds an unpacked application under
-`packages/better-harness-desktop/dist/installers`. Run it on the target OS/architecture
+`packages/better-harness-desktop/dist/installers`. Staging drops source maps,
+TypeScript declarations, package READMEs, the unused `@phosphor-icons` package
+(icons are already bundled into Studio's browser assets), and PDF.js trees the
+Node adapter does not import. Run the pack command on the target OS/architecture
 so Cargo produces the matching Rust executable. `npm run dist -w
 @qoder-ai/better-harness-desktop` creates the configured ZIP (macOS), NSIS (Windows),
 or AppImage (Linux). These are development packaging targets; signing,

packages/better-harness-desktop/scripts/prune-desktop-runtime.mjs

@@ -0,0 +1,162 @@
+import { readdir, rm } from "node:fs/promises";
+import { basename, dirname, join, relative } from "node:path";
+
+const PHOSPHOR_SCOPE = "@phosphor-icons";
+const PDFJS_PACKAGE = "pdfjs-dist";
+const PDFJS_SUPPORT_TREES = new Set(["cmaps", "wasm", "standard_fonts", "iccs", "image_decoders"]);
+const PDFJS_LEGACY_RUNTIME = new Set(["pdf.mjs", "pdf.worker.mjs"]);
+const README_NAMES = new Set(["readme", "readme.md", "readme.txt", "readme.markdown", "readme.rst"]);
+
+/** Debug metadata is never required to start the packaged Studio runtime. */
+export function isDebugMetadataFile(name) {
+  const lower = name.toLowerCase();
+  if (lower.endsWith(".map")) return true;
+  if (lower.endsWith(".d.ts") || lower.endsWith(".d.mts") || lower.endsWith(".d.cts")) return true;
+  return README_NAMES.has(lower);
+}
+
+function relativeSegments(from, to) {
+  const rel = relative(from, to);
+  if (rel === "") return [];
+  const segments = [];
+  let current = rel;
+  while (current && current !== ".") {
+    segments.unshift(basename(current));
+    const parent = dirname(current);
+    if (parent === current) break;
+    current = parent;
+  }
+  return segments;
+}
+
+/** Keep only the Node PDF.js entry Studio imports, plus its support trees. */
+export function isKeptPdfjsPath(packageRoot, filePath) {
+  const segments = relativeSegments(packageRoot, filePath);
+  if (segments.length === 1 && (segments[0] === "package.json" || segments[0] === "LICENSE")) return true;
+  if (segments[0] === "legacy" && segments[1] === "build" && segments.length === 3) {
+    return PDFJS_LEGACY_RUNTIME.has(segments[2]);
+  }
+  if (PDFJS_SUPPORT_TREES.has(segments[0])) return true;
+  if (segments[0] === "legacy" && segments[1] === "image_decoders") return true;
+  return false;
+}
+
+async function removeEmptyDirectories(root) {
+  let entries;
+  try {
+    entries = await readdir(root, { withFileTypes: true });
+  } catch (error) {
+    if (error && error.code === "ENOENT") return;
+    throw error;
+  }
+  for (const entry of entries) {
+    if (!entry.isDirectory() || entry.isSymbolicLink()) continue;
+    const full = join(root, entry.name);
+    await removeEmptyDirectories(full);
+    const leftover = await readdir(full);
+    if (leftover.length === 0) await rm(full, { recursive: true, force: true });
+  }
+}
+
+async function pruneDebugMetadata(root, stats) {
+  let entries;
+  try {
+    entries = await readdir(root, { withFileTypes: true });
+  } catch (error) {
+    if (error && error.code === "ENOENT") return;
+    throw error;
+  }
+  for (const entry of entries) {
+    const full = join(root, entry.name);
+    if (entry.isSymbolicLink()) {
+      if (isDebugMetadataFile(entry.name)) {
+        await rm(full, { force: true });
+        stats.removed += 1;
+      }
+      continue;
+    }
+    if (entry.isDirectory()) {
+      await pruneDebugMetadata(full, stats);
+      continue;
+    }
+    if (entry.isFile() && isDebugMetadataFile(entry.name)) {
+      await rm(full, { force: true });
+      stats.removed += 1;
+    }
+  }
+}
+
+function isKeptPdfjsPrefix(packageRoot, directoryPath) {
+  const segments = relativeSegments(packageRoot, directoryPath);
+  if (segments.length === 0) return true;
+  if (PDFJS_SUPPORT_TREES.has(segments[0])) return true;
+  if (segments[0] !== "legacy") return false;
+  if (segments.length === 1) return true;
+  if (segments[1] === "build" && segments.length === 2) return true;
+  return segments[1] === "image_decoders";
+}
+
+async function prunePdfjsPackage(packageRoot, current, stats) {
+  let entries;
+  try {
+    entries = await readdir(current, { withFileTypes: true });
+  } catch (error) {
+    if (error && error.code === "ENOENT") return;
+    throw error;
+  }
+  for (const entry of entries) {
+    const full = join(current, entry.name);
+    if (entry.isDirectory() && !entry.isSymbolicLink()) {
+      if (!isKeptPdfjsPrefix(packageRoot, full)) {
+        await rm(full, { recursive: true, force: true });
+        stats.removed += 1;
+        continue;
+      }
+      await prunePdfjsPackage(packageRoot, full, stats);
+      continue;
+    }
+    if (!isKeptPdfjsPath(packageRoot, full)) {
+      await rm(full, { force: true });
+      stats.removed += 1;
+    }
+  }
+}
+
+async function visitNodeModules(dir, stats) {
+  let entries;
+  try {
+    entries = await readdir(dir, { withFileTypes: true });
+  } catch (error) {
+    if (error && error.code === "ENOENT") return;
+    throw error;
+  }
+  for (const entry of entries) {
+    if (!entry.isDirectory() || entry.isSymbolicLink()) continue;
+    const full = join(dir, entry.name);
+    if (entry.name === PHOSPHOR_SCOPE) {
+      await rm(full, { recursive: true, force: true });
+      stats.removed += 1;
+      stats.removedPhosphor = true;
+      continue;
+    }
+    if (entry.name === PDFJS_PACKAGE) {
+      await prunePdfjsPackage(full, full, stats);
+      continue;
+    }
+    if (entry.name === "node_modules" || entry.name.startsWith("@")) {
+      await visitNodeModules(full, stats);
+      continue;
+    }
+    await visitNodeModules(join(full, "node_modules"), stats);
+  }
+}
+
+/** Drop pack-only weight from a staged Electron app root. */
+export async function pruneDesktopRuntime(appRoot) {
+  const nodeModules = join(appRoot, "node_modules");
+  const stats = { removed: 0, removedPhosphor: false };
+  await visitNodeModules(nodeModules, stats);
+  await pruneDebugMetadata(nodeModules, stats);
+  await removeEmptyDirectories(nodeModules);
+  return stats;
+}

packages/better-harness-desktop/scripts/stage.mjs

@@ -2,6 +2,7 @@ import { cp, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
 import { execFileSync } from 'node:child_process';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { pruneDesktopRuntime } from './prune-desktop-runtime.mjs';
 
 const root = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 const repository = resolve(root, '../..');
@@ -31,4 +32,6 @@ await cp(join(root, 'src'), join(staging, 'src'), { recursive: true });
 // Install only the two local public artifacts and their production closure.
 // This avoids copying repository dev dependencies into the desktop distribution.
 process.stdout.write(run(['install', '--omit=dev', '--ignore-scripts', '--no-audit', '--no-fund', ...archives], staging));
+const pruned = await pruneDesktopRuntime(staging);
 console.log(`Staged desktop runtime: ${staging}`);
+console.log(`Pruned ${pruned.removed} desktop runtime files`);

packages/better-harness-desktop/test/prune-desktop-runtime.test.mjs

@@ -0,0 +1,130 @@
+import { mkdir, mkdtemp, readFile, rm, stat, writeFile } from "node:fs/promises";
+import assert from "node:assert/strict";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { test } from "node:test";
+import {
+  isDebugMetadataFile,
+  isKeptPdfjsPath,
+  pruneDesktopRuntime,
+} from "../scripts/prune-desktop-runtime.mjs";
+
+async function writeTree(root, files) {
+  for (const [relativePath, content] of Object.entries(files)) {
+    const full = join(root, relativePath);
+    await mkdir(dirname(full), { recursive: true });
+    await writeFile(full, content);
+  }
+}
+
+async function exists(path) {
+  try {
+    await stat(path);
+    return true;
+  } catch (error) {
+    if (error && error.code === "ENOENT") return false;
+    throw error;
+  }
+}
+
+test("debug metadata is README, source maps, and declaration files only", () => {
+  for (const name of ["README.md", "readme", "index.js.map", "index.d.ts", "pdf.d.mts", "view.d.cts"]) {
+    assert.equal(isDebugMetadataFile(name), true, name);
+  }
+  for (const name of ["index.js", "LICENSE", "package.json", "skia.darwin-arm64.node", "esbuild.wasm", "readme.js"]) {
+    assert.equal(isDebugMetadataFile(name), false, name);
+  }
+});
+
+test("PDF.js keep list is the legacy Node entry plus support trees", () => {
+  const root = join("app", "node_modules", "pdfjs-dist");
+  assert.equal(isKeptPdfjsPath(root, join(root, "package.json")), true);
+  assert.equal(isKeptPdfjsPath(root, join(root, "LICENSE")), true);
+  assert.equal(isKeptPdfjsPath(root, join(root, "legacy", "build", "pdf.mjs")), true);
+  assert.equal(isKeptPdfjsPath(root, join(root, "legacy", "build", "pdf.worker.mjs")), true);
+  assert.equal(isKeptPdfjsPath(root, join(root, "cmaps", "A.bcmap")), true);
+  assert.equal(isKeptPdfjsPath(root, join(root, "wasm", "jbig2.wasm")), true);
+  assert.equal(isKeptPdfjsPath(root, join(root, "legacy", "build", "pdf.min.mjs")), false);
+  assert.equal(isKeptPdfjsPath(root, join(root, "legacy", "build", "pdf.sandbox.mjs")), false);
+  assert.equal(isKeptPdfjsPath(root, join(root, "build", "pdf.mjs")), false);
+  assert.equal(isKeptPdfjsPath(root, join(root, "web", "viewer.mjs")), false);
+  assert.equal(isKeptPdfjsPath(root, join(root, "types", "src", "pdf.d.ts")), false);
+});
+
+test("staging prune drops debug metadata, Phosphor, and unused PDF.js trees", async () => {
+  const appRoot = await mkdtemp(join(tmpdir(), "desktop-runtime-prune-"));
+  try {
+    await writeTree(appRoot, {
+      "src/main.mjs": "export {}\n",
+      "node_modules/keep-pkg/index.js": "export const ok = true;\n",
+      "node_modules/keep-pkg/LICENSE": "MIT\n",
+      "node_modules/keep-pkg/README.md": "docs\n",
+      "node_modules/keep-pkg/index.d.ts": "export const ok: boolean;\n",
+      "node_modules/keep-pkg/index.js.map": "{\"version\":3}\n",
+      "node_modules/@phosphor-icons/react/dist/csr/X.js": "export const X = () => null;\n",
+      "node_modules/@phosphor-icons/react/README.md": "icons\n",
+      "node_modules/pdfjs-dist/package.json": "{\"name\":\"pdfjs-dist\"}\n",
+      "node_modules/pdfjs-dist/LICENSE": "Apache-2.0\n",
+      "node_modules/pdfjs-dist/README.md": "pdfjs\n",
+      "node_modules/pdfjs-dist/webpack.mjs": "export {}\n",
+      "node_modules/pdfjs-dist/build/pdf.mjs": "export function getDocument() {}\n",
+      "node_modules/pdfjs-dist/build/pdf.mjs.map": "{\"version\":3}\n",
+      "node_modules/pdfjs-dist/web/viewer.mjs": "export {}\n",
+      "node_modules/pdfjs-dist/types/src/pdf.d.ts": "export {}\n",
+      "node_modules/pdfjs-dist/legacy/build/pdf.mjs": "export function getDocument() { return true; }\n",
+      "node_modules/pdfjs-dist/legacy/build/pdf.mjs.map": "{\"version\":3}\n",
+      "node_modules/pdfjs-dist/legacy/build/pdf.worker.mjs": "export {}\n",
+      "node_modules/pdfjs-dist/legacy/build/pdf.min.mjs": "export {}\n",
+      "node_modules/pdfjs-dist/legacy/build/pdf.sandbox.mjs": "export {}\n",
+      "node_modules/pdfjs-dist/legacy/web/viewer.mjs": "export {}\n",
+      "node_modules/pdfjs-dist/cmaps/A.bcmap": "cmap\n",
+      "node_modules/pdfjs-dist/wasm/jbig2.wasm": "wasm\n",
+      "node_modules/pdfjs-dist/standard_fonts/Fox.pfb": "font\n",
+      "node_modules/pdfjs-dist/iccs/x.icc": "icc\n",
+      "node_modules/pdfjs-dist/image_decoders/pdf.image_decoders.mjs": "export {}\n",
+      "node_modules/pdfjs-dist/image_decoders/pdf.image_decoders.mjs.map": "{\"version\":3}\n",
+      "node_modules/@qoder-ai/harness-studio/dist/app/assets/app.js": "console.log(1);\n",
+      "node_modules/@qoder-ai/harness-studio/dist/app/assets/app.js.map": "{\"version\":3}\n",
+    });
+
+    const stats = await pruneDesktopRuntime(appRoot);
+    assert.equal(stats.removedPhosphor, true);
+    assert.equal(stats.removed > 0, true);
+
+    assert.equal(await exists(join(appRoot, "src", "main.mjs")), true);
+    assert.equal(await exists(join(appRoot, "node_modules", "keep-pkg", "index.js")), true);
+    assert.equal(await exists(join(appRoot, "node_modules", "keep-pkg", "LICENSE")), true);
+    assert.equal(await exists(join(appRoot, "node_modules", "keep-pkg", "README.md")), false);
+    assert.equal(await exists(join(appRoot, "node_modules", "keep-pkg", "index.d.ts")), false);
+    assert.equal(await exists(join(appRoot, "node_modules", "keep-pkg", "index.js.map")), false);
+    assert.equal(await exists(join(appRoot, "node_modules", "@phosphor-icons")), false);
+
+    const pdfjs = join(appRoot, "node_modules", "pdfjs-dist");
+    assert.equal(await exists(join(pdfjs, "package.json")), true);
+    assert.equal(await exists(join(pdfjs, "LICENSE")), true);
+    assert.equal(await exists(join(pdfjs, "legacy", "build", "pdf.mjs")), true);
+    assert.equal(await exists(join(pdfjs, "legacy", "build", "pdf.worker.mjs")), true);
+    assert.equal(await exists(join(pdfjs, "cmaps", "A.bcmap")), true);
+    assert.equal(await exists(join(pdfjs, "wasm", "jbig2.wasm")), true);
+    assert.equal(await exists(join(pdfjs, "standard_fonts", "Fox.pfb")), true);
+    assert.equal(await exists(join(pdfjs, "iccs", "x.icc")), true);
+    assert.equal(await exists(join(pdfjs, "image_decoders", "pdf.image_decoders.mjs")), true);
+    assert.equal(await exists(join(pdfjs, "README.md")), false);
+    assert.equal(await exists(join(pdfjs, "webpack.mjs")), false);
+    assert.equal(await exists(join(pdfjs, "build")), false);
+    assert.equal(await exists(join(pdfjs, "web")), false);
+    assert.equal(await exists(join(pdfjs, "types")), false);
+    assert.equal(await exists(join(pdfjs, "legacy", "build", "pdf.mjs.map")), false);
+    assert.equal(await exists(join(pdfjs, "legacy", "build", "pdf.min.mjs")), false);
+    assert.equal(await exists(join(pdfjs, "legacy", "web")), false);
+    assert.equal(await exists(join(pdfjs, "image_decoders", "pdf.image_decoders.mjs.map")), false);
+
+    assert.equal(await exists(join(appRoot, "node_modules", "@qoder-ai", "harness-studio", "dist", "app", "assets", "app.js")), true);
+    assert.equal(await exists(join(appRoot, "node_modules", "@qoder-ai", "harness-studio", "dist", "app", "assets", "app.js.map")), false);
+
+    const runtime = await readFile(join(pdfjs, "legacy", "build", "pdf.mjs"), "utf8");
+    assert.match(runtime, /export function getDocument/);
+  } finally {
+    await rm(appRoot, { recursive: true, force: true });
+  }
+});