# Desktop Startup Handoff (2026-04-07)

## Goal

排查并优化 Windows 安装包首启卡在“正在同步员工配置”的问题，重点处理两件事：

1. 修正启动状态汇总，避免把真实错误或后续阶段统一显示成“正在同步员工配置”
2. 增加首启结构化日志和更完整的 diagnostics 信息，便于现场机器定位卡点

## Current Status

当前不是完成态，但主体改动已经做了大半。

已完成：

- 主进程接入 startup logger 基础能力
- diagnostics 导出内容增强
- workspace summary 逻辑已改，新增 `syncing-projects` 阶段，避免“无项目”覆盖真实错误
- UI 已做最小配套修改：
  - 支持 `syncing-projects`
  - 导出 diagnostics 后显示 `startupLogPath`
  - 启动错误遮罩上增加“导出诊断”按钮

未完成：

- 当前还没跑通整仓 typecheck
- 还没跑桌面端/安装包首启验证
- 日志点已接入到部分关键服务，但还没有做完整的 installer 现场回归

## Current Blocker

最新一次整仓类型检查：

```powershell
$env:COREPACK_HOME='D:\qjclaw\.corepack'; corepack pnpm typecheck
```

结果：

- `packages/shared-types` 通过
- `packages/gateway-client` 通过
- `apps/ui` 失败

当前唯一已确认报错：

- `apps/ui/src/App.tsx:969`
- `nextWorkspace` is possibly `null`

对应代码附近逻辑是启动轮询里的：

```ts
const nextWorkspace = await refresh(false);
const nextShouldPoll = Boolean(nextWorkspace) && (
  nextWorkspace.chatLaunchState === "starting"
  || (!nextWorkspace.shellReady && nextWorkspace.bindingRequired)
);
```

这里需要把 `nextWorkspace` 收窄后再访问字段。

## Files Changed For This Task

确认与本任务直接相关的文件：

- `apps/desktop/src/main/index.ts`
- `apps/desktop/src/main/ipc.ts`
- `apps/desktop/src/main/services/cloud-api.ts`
- `apps/desktop/src/main/services/diagnostics.ts`
- `apps/desktop/src/main/services/project-bundle.ts`
- `apps/desktop/src/main/services/startup-logger.ts`
- `packages/shared-types/src/index.ts`
- `apps/ui/src/App.tsx`

## Important Functional Changes

### 1. New startup logger

新增：

- `apps/desktop/src/main/services/startup-logger.ts`

作用：

- 向 `<logsPath>/startup/` 写 JSONL 风格首启日志
- 生成会话日志和 latest 日志
- 对 token / api key / password / URL 做基本脱敏

### 2. Shared types updated

`packages/shared-types/src/index.ts` 已添加：

- `WorkspaceStartupPhase` 新值：`syncing-projects`
- `DiagnosticsExportResult.startupLogPath?: string`

### 3. Diagnostics export enhanced

`apps/desktop/src/main/services/diagnostics.ts` 当前已支持导出更多现场信息：

- `workspaceSummary`
- `bundleSyncStatus`
- `startupLogPath`
- `reason`

并通过 `startupLogger` 写 diagnostics 导出记录。

### 4. Workspace summary fix

`apps/desktop/src/main/ipc.ts` 是本次最关键的修复点。

当前逻辑已经改成：

- `error` 不再被“无项目”覆盖
- 当 runtime cloud ready 但还没有项目时，进入 `syncing-projects`
- 如果 bundle sync 失败，返回明确错误 summary
- summary 变化会写 startup logger
- diagnostics export 时会附带 startup log path / workspace summary / bundle sync status

这部分是本次修复“首页闪一下又被‘正在同步员工配置’盖回去”的核心。

### 5. Index / service wiring

`apps/desktop/src/main/index.ts` 已做的事情：

- 创建 `startupLogger`
- 注入 `DiagnosticsService`
- 注入 `OpenClawConfigClient`
- 注入 `ProjectBundleService`
- 注入 `registerDesktopIpc`

`cloud-api.ts` / `project-bundle.ts` 已开始接入 logger，但后续仍建议在类型检查通过后再补一次日志点覆盖率检查。

### 6. UI minimal support

`apps/ui/src/App.tsx` 当前的目标性修改只有这些：

- `startupCurtainCopy.syncingProjects`
- `getStartupProgress()` 支持 `syncing-projects`
- `getStartupCurtainStatus()` 支持 `syncing-projects`
- diagnostics 成功提示里包含 `startupLogPath`
- 启动错误遮罩新增 diagnostics 导出按钮

## Other Dirty Files In Worktree

当前 `git diff --name-only` 里还有这些未提交改动：

- `apps/desktop/src/main/services/project-store.ts`
- `apps/desktop/src/preload/index.ts`
- `apps/ui/src/styles.css`
- `build/scripts/electron-smoke.ps1`

这些不在我本次“启动日志/状态机”主线修改的核心列表里，可能是已有改动或其他任务改动。

如果另一个 AI 要继续本任务，不要默认回退这些文件。

## Whether This Affects Another Task

会不会影响，取决于另一个任务改哪些文件。

影响较小的情况：

- 另一个任务不改下列文件：
  - `apps/desktop/src/main/index.ts`
  - `apps/desktop/src/main/ipc.ts`
  - `apps/desktop/src/main/services/cloud-api.ts`
  - `apps/desktop/src/main/services/diagnostics.ts`
  - `apps/desktop/src/main/services/project-bundle.ts`
  - `apps/ui/src/App.tsx`
  - `packages/shared-types/src/index.ts`

容易冲突的情况：

- 另一个任务要改 `App.tsx`
- 另一个任务要改 desktop main 启动链路
- 另一个任务要改 diagnostics / preload / shared-types IPC 类型

所以如果你只是临时切去改完全无关模块，通常问题不大；如果另一个任务也碰启动、UI 主壳、共享类型或 preload，冲突概率就高。

## Recommended Pause Strategy

如果要先切走做别的任务，建议：

1. 不要继续在当前改动基础上随手混改启动相关文件
2. 让另一个任务尽量避开本任务相关文件
3. 如果另一个 AI 要继续本任务，先读本文件，再跑一次 typecheck，从 UI 的 nullability 报错开始收尾

## Recommended Next Steps For The Next AI

1. 修复 `apps/ui/src/App.tsx:969` 的空值收窄问题
2. 重新运行：

```powershell
$env:COREPACK_HOME='D:\qjclaw\.corepack'; corepack pnpm typecheck
```

3. 如果 typecheck 继续报主进程相关错误，再逐个修：
   - `index.ts`
   - `cloud-api.ts`
   - `project-bundle.ts`
   - `ipc.ts`

4. typecheck 通过后，验证桌面端：
   - 启动阶段文案是否出现 `syncing-projects`
   - diagnostics 导出是否返回 `startupLogPath`
   - 启动错误遮罩是否能导出日志

5. 再做安装包/首启验证，重点看是否能区分：
   - 员工配置请求失败
   - 项目 bundle 同步失败
   - runtime 启动失败
   - gateway 连接失败
   - summary 被覆盖

## Useful Commands

查看工作区变更：

```powershell
git -c safe.directory=D:/qjclaw diff --name-only
```

重新看 UI 变更：

```powershell
git -c safe.directory=D:/qjclaw diff -- apps/ui/src/App.tsx
```

重新跑类型检查：

```powershell
$env:COREPACK_HOME='D:\qjclaw\.corepack'; corepack pnpm typecheck
```

## Notes

- 这个仓库当前在 Windows 环境下，且 `D:\qjclaw` 需要按 safe.directory 方式使用 git
- 我这轮没有做 destructive revert
- 当前最重要的是先保持工作区稳定，不要在 `App.tsx` 上再叠加大改