源码快照 @ 2026-09-01 (source-only, 剔除非源码素材)

docs/conventions/troubleshooting/windows-e2e-dev-start.md

@@ -0,0 +1,79 @@
+# Windows E2E Dev 启动约定
+
+## 一条命令启动
+
+在仓库根目录执行：
+
+```powershell
+& .\tools\scripts\start-windows-e2e-dev.ps1 `
+  -RepoRoot C:\Work\tutti-os\tutti-windows-e2e-acceptance-20260804 `
+  -ResetState
+```
+
+在当前仓库根目录，也可以使用固定版本的 pnpm 命令：
+
+```powershell
+corepack pnpm@10.11.0 dev:windows:e2e:clean  # 首次启动或需要清理旧状态
+corepack pnpm@10.11.0 dev:windows:e2e        # 后续复用已有状态
+```
+
+不要给 pnpm script 追加 `-- -ResetState`；需要自定义 `RepoRoot` 或 `StateDir` 时，直接调用上面的 PowerShell 脚本。
+
+这个入口默认不重新 build。它会完成以下前置检查并按固定顺序启动：
+
+1. 校验 Node 主版本和 `corepack pnpm` 版本；
+2. 校验已经构建的 `tuttid.exe`、Electron 入口和 Windows 内置
+   `managed-posix-shell/runtime.json`；
+3. 从 runtime metadata 解析并注入
+   `TUTTI_MANAGED_POSIX_SHELL`；
+4. 强制设置 `TUTTI_ANALYTICS_DISABLED=1`，避免验收操作进入业务埋点；
+5. 启动或复用 `http://127.0.0.1:5173` 的 renderer dev server；
+6. 从 `apps/desktop` 目录启动 Electron，并让桌面进程自己生成临时
+   `TUTTID_ACCESS_TOKEN`；
+7. 等待 `tutti-desktop.log` 出现 `desktop app ready` 后才返回成功。
+
+默认 state 在仓库 `.tmp\tutti-windows-e2e-dev` 下。需要完全干净的验收时使用
+`-ResetState`；脚本只允许清理仓库 `.tmp` 下的 state，并且会先关闭同一
+worktree/state 的开发进程，避免 app server 锁住旧的 `.exe`。
+
+## 为什么之前会反复遇到“应用安装不上”
+
+日志显示“下载安装”和“启动失败”曾被混在一起看：
+
+- `tuttid.log` 的 `18:07:29` 开始下载 `ai-slide`，`18:07:40` 下载完成，
+  `18:07:45` 记录 `workspace_app_install_job_succeeded`；
+- `18:19:03` 开始下载 `ai-media-canvas`，`18:19:41` 下载完成，
+  `18:20:10` 记录 `workspace_app_install_job_succeeded`，随后
+  `18:20:14` 记录 `workspace_app_runtime_running`；
+- 真正的失败日志是 `workspace_app_runtime_start_failed`，原因明确为：
+  `managed POSIX shell is unavailable on Windows: TUTTI_MANAGED_POSIX_SHELL is not configured`；
+- 同一 state 反复启动时还出现 `workspace.app.package.replace_deferred`，
+  错误为 `tutti-onboarding-server.exe: Access is denied`。这是旧 app server
+  仍在运行导致的文件锁，不是远端包下载失败。
+
+因此，Windows 开发验收不能只运行裸的 `tuttid.exe`，也不能只设置
+`TUTTID_ACCESS_TOKEN`：裸 daemon 缺少桌面注入的临时 token，且不会自动知道
+仓库内置的 managed shell；也不能复用仍有 app server 子进程的旧 state。
+
+## 常见错误与处理
+
+| 现象                                    | 原因                                            | 处理                                         |
+| --------------------------------------- | ----------------------------------------------- | -------------------------------------------- |
+| `TUTTID_ACCESS_TOKEN is required`       | 直接启动 daemon，绕过 Electron 的桌面托管       | 使用本脚本，不要手工运行 `tuttid.exe`        |
+| `managed POSIX shell is unavailable...` | 未注入仓库内置 Bash                             | 检查脚本输出的 `shell` 路径和 `runtime.json` |
+| `Access is denied` 替换 app server      | 旧 state 的 app runtime 仍被进程占用            | 脚本会清理同一 state；必要时加 `-ResetState` |
+| `Cannot find module <repo-root>`        | Electron 的 cwd 是仓库根，而不是 `apps/desktop` | 由脚本固定在 `apps/desktop` 启动             |
+| `ERR_PNPM_UNSUPPORTED_ENGINE`           | 系统 pnpm 不是仓库要求版本                      | 脚本固定使用 `corepack pnpm`                 |
+
+## 验收前检查日志
+
+启动成功后重点看：
+
+```powershell
+$state = 'C:\Work\tutti-os\tutti-windows-e2e-acceptance-20260804\.tmp\tutti-windows-e2e-dev'
+Select-String -Path "$state\logs\tutti-desktop.log" -Pattern 'desktop app ready|managed_posix_shell'
+Select-String -Path "$state\logs\tuttid.log" -Pattern 'workspace_app_install_job_succeeded|workspace_app_runtime_running|workspace_app_runtime_start_failed'
+```
+
+期望看到 `desktop app ready`、安装成功和 `workspace_app_runtime_running`；
+若再次出现 `managed_posix_shell` 未配置，应先停止验收，不要继续重复点击“安装”。