--- version: 1.0 last-updated: 2026-03-04 status: stable --- # Quick Init — 快捷初始化 > 通过预置 `~/.qimingclaw/qimingclaw.json` 或环境变量，跳过手动向导完成客户端初始化。 --- ## 概述 客户端初始化向导需要用户手动填写配置（端口、工作区）和登录（动态认证码）。Quick Init 支持通过预置配置文件或环境变量快速完成初始化——文件中包含 `savedKey`（已完成过登录的设备密钥），直接调 reg 接口（password 传空字符串），跳过动态码流程。 **关键约束**：即使有快捷配置，依赖安装步骤不能跳过，必须先完成依赖检测/安装。qiming-file-server、qiming-mcp-stdio-proxy、qimingcode、claude-code-acp-ts 四包均不随包集成，通过 SETUP_REQUIRED_DEPENDENCIES 的 installVersion 在 ~/.qimingclaw 初始化安装，并参与升级后的 syncInitDependencies。 --- ## 配置来源与优先级 ``` qimingclaw.json (quickInit scope) → 环境变量 → 无配置（走正常向导） ``` Per-field 合并：每个字段独立按 JSON > 环境变量 > 默认值 取值。 ### qimingclaw.json 文件路径：`~/.qimingclaw/qimingclaw.json` 使用 `quickInit` scope，便于将来在同一文件中增加其他配置。 ```json { "quickInit": { "enabled": true, "serverHost": "https://agent.qiming.com", "savedKey": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "username": "user@example.com", "agentPort": 60001, "fileServerPort": 60000, "workspaceDir": "/home/user/workspace" } } ``` 最简写法（只需必填字段，其余走默认值）： ```json { "quickInit": { "serverHost": "https://agent.qiming.com", "savedKey": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" } } ``` 设为 `"enabled": false` 可禁用快捷初始化（同时阻断环境变量回退）。 ### 环境变量 | 环境变量 | 对应字段 | 必填 | |---|---|---| | `QIMING_SERVER_HOST` | serverHost | 是 | | `QIMING_SAVED_KEY` | savedKey | 是 | | `QIMING_USER_NAME` | username | 否 | | `QIMING_AGENT_PORT` | agentPort | 否 | | `QIMING_FILE_SERVER_PORT` | fileServerPort | 否 | | `QIMING_WORKSPACE_DIR` | workspaceDir | 否 | ### 字段说明 | 字段 | 类型 | 必填 | 默认值 | 说明 | |---|---|---|---|---| | `serverHost` | string | **是** | - | 服务域名 | | `savedKey` | string | **是** | - | 设备密钥（已注册） | | `username` | string | 否 | `''` | 登录用户名 | | `agentPort` | number | 否 | `60001` | Agent 端口 | | `fileServerPort` | number | 否 | `60000` | 文件服务端口 | | `workspaceDir` | string | 否 | `~/.qimingclaw/workspace` | 工作区目录 | | `enabled` | boolean | 否 | `true` | 是否启用（仅 JSON） | --- ## 架构 ``` ┌─────────────────────────────────────────────────────────────┐ │ Main Process │ │ │ │ bootstrap/quickInit.ts │ │ ┌────────────────────────────────────────────────────┐ │ │ │ readQuickInitConfig() │ │ │ │ 1. 读取 ~/.qimingclaw/qimingclaw.json → quickInit │ │ │ │ 2. 读取 QIMING_* 环境变量 │ │ │ │ 3. Per-field 合并: JSON > env > default │ │ │ │ 4. 校验 serverHost + savedKey 必填 │ │ │ │ 5. 缓存结果（每次启动只读一次） │ │ │ └────────────────────────────────────────────────────┘ │ │ │ │ │ IPC: quickInit:getConfig │ │ │ │ ├─────────────────────────┼───────────────────────────────────┤ │ ▼ │ │ Renderer Process │ │ │ │ App.tsx (每次启动) │ │ ┌────────────────────────────────────────────────────┐ │ │ │ checkSetup: │ │ │ │ setup 已完成? │ │ │ │ ├─ 是 → quickInit.getConfig() │ │ │ │ │ ├─ 有配置 → applyQuickInitToDb() │ │ │ │ │ │ (覆盖 step1 + savedKey + 静默注册) │ │ │ │ │ └─ 无配置 → 使用 DB 已有值 │ │ │ │ │ → 进入主界面 │ │ │ │ └─ 否 → 渲染 SetupWizard │ │ │ └────────────────────────────────────────────────────┘ │ │ │ │ SetupWizard.tsx (仅首次 setup) │ │ ┌────────────────────────────────────────────────────┐ │ │ │ 启动 → 依赖检测 │ │ │ │ │ │ │ │ │ ├─ 依赖就绪 + setup 未完成 │ │ │ │ │ └─ quickInit.getConfig() │ │ │ │ │ ├─ 有配置 → performQuickInit() │ │ │ │ │ └─ 无配置 → 正常向导 │ │ │ │ │ │ │ │ │ └─ 依赖缺失 → 安装流程 │ │ │ │ └─ handleDepsComplete │ │ │ │ └─ quickInit.getConfig() │ │ │ │ ├─ 有配置 → performQuickInit() │ │ │ │ └─ 无配置 → 正常向导 │ │ │ └────────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────┘ ``` │ │ └─ 无配置 → 正常向导 │ │ │ └────────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────┘ ``` --- ## 启动时序 ``` App 启动 │ ├─ Main: 注册 quickInit:getConfig IPC handler │ └─ Renderer: App.tsx checkSetup │ └─ setupService.isSetupCompleted() │ ├─ true (setup 已完成) │ └─ ✅ quickInit.getConfig() │ ├─ 有配置 → applyQuickInitToDb() │ │ 覆盖 step1 config + savedKey + 静默 loginAndRegister │ └─ 无配置 → 使用 DB 已有值 │ → 进入主界面 → autoReconnect → 启动服务 │ └─ false (setup 未完成) → 渲染 SetupWizard │ └─ useEffect init() │ ├─ 依赖全部就绪 │ └─ ✅ quickInit.getConfig() │ ├─ 有配置 → performQuickInit() → 自动完成 │ └─ 无配置 → 正常向导 step 1/2 │ └─ 依赖缺失 → 安装流程 └─ 安装完成 handleDepsComplete └─ ✅ quickInit.getConfig() ``` **每次启动都读取配置**：无论 setup 是否已完成，都优先读取 `qimingclaw.json` / 环境变量。有配置 → 覆盖 DB；无配置 → 使用 DB 已有值。 --- ## applyQuickInitToDb 流程（setup 已完成时） App.tsx 中 setup 已完成时静默更新 DB，确保后续 autoReconnect / 服务启动使用最新值。 ``` applyQuickInitToDb(config) │ ├─ 1. 覆盖 Step1 配置（serverHost, agentPort, fileServerPort, workspaceDir） │ ├─ 2. 覆盖 savedKey（全局 + 域名级） │ └─ 3. 静默 loginAndRegister(username, '', { domain }) └─ 失败不阻塞启动（console.warn，已有 auth 信息仍可用） ``` ## performQuickInit 流程（setup 未完成时） ``` performQuickInit(config) │ ├─ 1. 保存 Step1 配置（serverHost, agentPort, fileServerPort, workspaceDir） │ ├─ 2. 预存 savedKey 到 SQLite │ ├─ AUTH_KEYS.SAVED_KEY → 全局 savedKey │ └─ AUTH_KEYS.SAVED_KEYS_PREFIX + domain_username → 域名级 savedKey │ ├─ 3. loginAndRegister(username, '', { domain }) │ └─ password 传空字符串，函数内部从 DB 取 savedKey 附加到 reg 请求 │ ├─ 4. completeStep2() + completeSetup() │ └─ 5. onComplete() → 进入主界面 │ └─ [失败] catch → console.error → 回退到手动向导（step1 可能已保存） ``` 失败兜底：quick init 任何步骤失败 → 回退到正常向导流程。UI 显示 `` + "正在自动配置..."。 --- ## 文件清单 ### 新建 | 文件 | 说明 | |---|---| | `src/shared/types/quickInit.ts` | `QuickInitConfig` 接口 + `hasRequiredQuickInitFields()` 校验 | | `src/main/bootstrap/quickInit.ts` | Main 进程读取 JSON / 环境变量，per-field 合并，缓存 | | `src/shared/types/quickInit.test.ts` | 类型校验测试（10 cases） | | `src/main/bootstrap/quickInit.test.ts` | 读取逻辑测试（19 cases） | ### 修改 | 文件 | 改动 | |---|---| | `src/main/ipc/settingsHandlers.ts` | 添加 `quickInit:getConfig` IPC handler | | `src/preload/index.ts` | 暴露 `quickInit.getConfig()` 给 Renderer | | `src/shared/types/electron.d.ts` | 添加 `QuickInitAPI` 接口 + `ElectronAPI.quickInit` | | `src/renderer/App.tsx` | setup 已完成时读取配置 → `applyQuickInitToDb()` 覆盖 DB | | `src/renderer/components/setup/SetupWizard.tsx` | setup 未完成时检测配置 → `performQuickInit()` 自动完成流程 | --- ## 复用的现有函数 | 函数 | 文件 | 用途 | |---|---|---| | `loginAndRegister()` | `renderer/services/core/auth.ts` | 调用 reg API，savedKey 由函数内部从 DB 读取 | | `normalizeServerHost()` | `renderer/services/core/auth.ts` | 域名标准化（加 https 前缀、去尾 /） | | `setupService.saveStep1Config()` | `renderer/services/core/setup.ts` | 保存 step1 配置并更新 state | | `setupService.completeStep2()` | `renderer/services/core/setup.ts` | 标记 step2 完成 | | `setupService.completeSetup()` | `renderer/services/core/setup.ts` | 标记整体完成 | | `APP_DATA_DIR_NAME` | `shared/constants.ts` | `.qimingclaw` 目录名 | | `DEFAULT_AGENT_RUNNER_PORT` | `shared/constants.ts` | `60001` | | `DEFAULT_FILE_SERVER_PORT` | `shared/constants.ts` | `60000` | --- ## 测试 29 个测试用例，覆盖以下场景： ### hasRequiredQuickInitFields（10 cases） - 必填字段齐全 / 全字段齐全 - 缺 serverHost / 缺 savedKey / 空字符串 - null / undefined / 非 object / 字段类型错误 ### readQuickInitConfig（19 cases） | 分类 | 场景 | |---|---| | 无配置 | 无 JSON + 无 env → null | | JSON | 全字段 / 仅必填（填默认值） / enabled:false / enabled:true / 无 quickInit scope / 缺必填 / 格式错误 | | 环境变量 | 全字段 / 仅必填 / 缺一个必填 → null / 无效端口回退默认 | | 优先级 | JSON > env / env 补充 JSON 缺失字段 / 都缺省走 default | | enabled:false | 阻断环境变量回退 | | 缓存 | 二次调用同引用 / null 也缓存 | 运行： ```bash npx vitest run src/shared/types/quickInit.test.ts src/main/bootstrap/quickInit.test.ts ``` --- ## 验证清单 | # | 场景 | 预期 | |---|---|---| | 1 | 无 JSON + 无 env | 正常向导流程不受影响 | | 2 | JSON 缺必填字段 | 控制台 warn 日志，走正常向导 | | 3 | JSON `enabled: false` | 跳过 quick init，不回退 env | | 4 | 有效 JSON + 无效 savedKey | 依赖安装正常 → quick init 调 reg 失败 → 回退手动向导（step1 已预填） | | 5 | 有效 JSON + 有效 savedKey | 依赖安装 → 自动配置 spinner → 直接进入主界面 | | 6 | 仅 env QIMING_SERVER_HOST + QIMING_SAVED_KEY | 同 #5，其余走默认值 | | 7 | JSON serverHost + env QIMING_AGENT_PORT | JSON 字段优先，env 补充缺失字段 | | 8 | `npm run electron:dev` 开发模式 | 正常运行 | --- *Last updated: 2026-03-04*