agent-radar
2ed3415fb7
Publish Claude Code Binaries / Stage and publish binaries (push) Canceled after 0s
Publish Tutti App Runtime / Build darwin-arm64 (push) Canceled after 0s
Publish Tutti App Runtime / Build darwin-amd64 (push) Canceled after 0s
Publish Tutti App Runtime / Build linux-amd64 (push) Canceled after 0s
Publish Tutti App Runtime / Build windows-amd64 (push) Canceled after 0s
Sync Tutti Agent Skills / sync (push) Canceled after 0s
Windows Agent Adapters / Test Windows agent adapters (push) Canceled after 0s
Windows Daemon Adapters / Test Windows daemon adapters (push) Canceled after 0s
Publish Tutti App Runtime / Publish runtime catalog (push) Canceled after 0s
80 lines
4.4 KiB
Markdown
80 lines
4.4 KiB
Markdown
# 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` 未配置，应先停止验收，不要继续重复点击“安装”。
|