| name | dimina-kit-worktree-build |
| description | 在 git worktree 或干净沙箱里构建 / 跑 e2e（含 dimina submodule）时的前置步骤与误诊清单。当你要在非主工作目录构建、跑 playwright e2e，或遇到 build:container 报 submodule 未初始化、native-host e2e 字段 undefined、devkit/compiler 测试因 dist 缺失而失败、pawl:check 退出码 2 时使用。 |
dimina-kit worktree / 沙箱构建 runbook
本仓库把上游 dimina/ 作为 submodule，且 dimina/fe 是一个独立的 pnpm workspace（不在根 packages/* 里）。全量 pnpm build（= turbo run build）里 @dimina-kit/devtools 的第一步就是 build:container（node build-container.js），它从 dimina/fe/packages/container 构建。新 worktree 不会自动带上这些，漏一步的典型表现是看起来无关的另一个假故障——所以先照下面做，再把红当真回归查。
一、标准搭建顺序（新 worktree 必做）
worktree 新建后 dimina/ 是空的，dimina/fe/node_modules 也没有：
git submodule update --init dimina
pnpm -C dimina/fe install
pnpm install
二、构建：两条路径，按“版本匹配”取舍
- 在 worktree 内真构建（改了 submodule 内容、或需要与本 worktree 的 submodule commit 版本一致的容器时）：
pnpm -C packages/devtools run build:main
pnpm -C packages/devtools run build:preload
pnpm -C packages/devtools run build:renderer
pnpm -C packages/devtools run build:simulator
pnpm -C packages/devtools run build:native-host
pnpm -C packages/devtools run build:workbench
DIMINA_FORCE_BUILD=1 node packages/devtools/build-container.js
- 复用已构建产物（只改了 kit 代码、submodule commit 与某个已构建 checkout 一致时，最快）：从那个 checkout rsync 已构建的 dist，再逐个
build:main/preload/renderer/simulator/native-host（跳过 build:container）：
packages/devtools/dist
packages/devkit/fe/dimina-fe-container
dimina/fe/packages/{service,common,render,container,compiler,components}/dist
⚠️ 版本必须匹配：rsync 来的容器/服务产物版本要与本 worktree 的 submodule commit 一致，否则 native-host e2e 会整片返回 undefined 字段——这是环境性假失败，不是代码回归。唯一根治法是在 worktree 内构建版本匹配的容器。
dimina/fe 已 init 但未装依赖时 build:container 会因缺 vite/依赖而构建失败。@dimina-kit/compiler 的 dist 依赖 submodule 源码；纯改 kit 时可直接拷主仓库 compiler dist。
三、误诊清单（出现下列现象，先回查上面漏没漏步骤，再当真回归）
build:container 报 dimina submodule is not initialized 或异常退出 → submodule 没 --init（空 dimina/fe）。- devkit / compiler 集成测试报
dist/pool.node.js 缺失、MODULE_NOT_FOUND、TS2307 → 对应包没 build（compiler 依赖 submodule 源码）。
- native-host e2e 字段全是
undefined → 容器产物与本 worktree submodule commit 版本不匹配。
pawl:check 退出码 2 → 只跑了部分包、缺工件，是 fail-loud 不是回归（pawl 缺工件绝不当“测得零”）。- playwright 报 “two different versions” → 根的
.bin/playwright 与 worktree 自己 node_modules/.pnpm/playwright 混用了；统一用 worktree 自己的 .bin/playwright。
- 多分支合并后 lint 报 eslint 未声明 devDep /
MODULE_NOT_FOUND → git checkout origin/main -- pnpm-lock.yaml 重置后重装。
四、判成败别被管道骗
gate 类命令（build / e2e / pawl / test）禁止用 | tail / | head 判通过与否——管道丢真实退出码，命令链 / wrapper 也可能把非零码吞成 0，还有静默 skip（如未设 HOT_RELOAD_STRESS=1 时 stress spec 直接跳过却看似通过）。判成败读完整输出末尾或结构化 reporter：playwright stats.unexpected / test-report*.json、vitest test-report.json、pawl 退出码本身。多步命令用 pnpm -C / git -C / 绝对路径（自包含，别依赖 cwd 继承）。详见 CLAUDE.md「提交前必跑 lint」段。
