# 2026-04-17 客户端模型配置打通进度

## 目标

让客户在桌面客户端自行配置项目所使用的模型信息，不依赖项目包内固定写死；项目从云端配置接口拉取 zip 并解压后，实际执行时由客户端把模型配置注入到项目运行时。

## 已完成

### 1. 客户端配置结构已支持 `modelId`

- 已扩展共享类型，`expertModelConfig.image/copywriting/video` 均支持 `modelId`
- 已扩展桌面端配置持久化与归一化逻辑，保存后不会丢失 `modelId`
- 已扩展 IPC 返回值，前端加载配置时可以拿到 `modelId`

涉及文件：

- [packages/shared-types/src/index.ts](D:/qjclaw/packages/shared-types/src/index.ts)
- [apps/desktop/src/main/services/app-config.ts](D:/qjclaw/apps/desktop/src/main/services/app-config.ts)
- [apps/desktop/src/main/ipc.ts](D:/qjclaw/apps/desktop/src/main/ipc.ts)

### 2. 客户端设置页已可配置项目模型

- 已在设置页增加图片模型 `model_id` 输入
- 已在设置页增加文案模型 `model_id` 输入
- 保存设置后，冒烟态和配置回显会校验 `modelId`

涉及文件：

- [apps/ui/src/App.tsx](D:/qjclaw/apps/ui/src/App.tsx)

### 3. 项目运行前注入逻辑已打通

- 新增项目运行时模型注入服务
- 在执行 `workspace_entry.py` 前，根据当前项目 ID 和客户端已保存配置生成 `memory/project.env`
- 同时把生成后的环境变量注入子进程，确保项目执行链路可直接读取

当前已支持：

- `xhs`
  - `QWEN_BASE_URL`
  - `QWEN_API_KEY`
  - `QWEN_MODEL`
  - `QWEN_VISION_MODEL`
  - `XHS_IMAGE_PROVIDER=env:xhsImage`
  - `XHS_IMAGE_BASE_URL`
  - `XHS_IMAGE_API_KEY`
  - `XHS_IMAGE_MODEL`
- `douyin`
  - `DOUYIN_WRITER_LLM_BASE_URL`
  - `DASHSCOPE_API_KEY`
  - `QWEN_API_KEY`
  - `DOUYIN_WRITER_LLM_MODEL`
  - `SEEDREAM_ARK_BASE_URL`
  - `SEEDREAM_ARK_API_KEY`
  - `SEEDREAM_MODEL`

涉及文件：

- [apps/desktop/src/main/services/project-model-runtime.ts](D:/qjclaw/apps/desktop/src/main/services/project-model-runtime.ts)
- [apps/desktop/src/main/services/project-workspace-executor.ts](D:/qjclaw/apps/desktop/src/main/services/project-workspace-executor.ts)
- [apps/desktop/src/main/ipc.ts](D:/qjclaw/apps/desktop/src/main/ipc.ts)

### 4. 打包链路和端到端冒烟已验证通过

- `corepack pnpm typecheck` 通过
- `corepack pnpm package` 通过
- 安装器冒烟通过
- `xhs` 云端 zip -> 解压 -> 激活项目 -> workspace-entry -> `project.env` 注入 冒烟通过
- `douyin` 云端 zip -> 解压 -> 激活项目 -> workspace-entry -> `project.env` 注入 冒烟通过

结果文件：

- [installer-smoke-result.json](D:/qjclaw/.tmp/installer-smoke/20260416-221908/installer-smoke-result.json)
- [xhs result.json](D:/qjclaw/.tmp/xhs-expert-cloud-bundle-smoke/result.json)
- [douyin result.json](D:/qjclaw/.tmp/douyin-expert-cloud-bundle-smoke/result.json)

对应冒烟脚本：

- [build/scripts/installer-smoke.ps1](D:/qjclaw/build/scripts/installer-smoke.ps1)
- [build/scripts/xhs-expert-cloud-bundle-smoke.ps1](D:/qjclaw/build/scripts/xhs-expert-cloud-bundle-smoke.ps1)
- [build/scripts/douyin-expert-cloud-bundle-smoke.ps1](D:/qjclaw/build/scripts/douyin-expert-cloud-bundle-smoke.ps1)
- [apps/desktop/src/main/index.ts](D:/qjclaw/apps/desktop/src/main/index.ts)

## 当前未完成

### 1. 视频模型链路暂未纳入本次范围

- 当前只重点打通了图片模型和文案模型
- `video.modelId` 类型和配置持久化已预留
- 但视频模型的运行时注入、前端独立配置项联动、项目实际消费逻辑，本次未继续展开

### 2. 目前是“客户端本地配置生效”，不是“云端统一下发模型配置”

- 现在已经支持客户在本机客户端配置模型并立即作用于项目执行
- 但还没有把这份模型配置并入远端配置中心做统一下发
- 如果后续要做多端一致、换机继承、后台代运营配置，需要再单独设计云端配置存储和同步

### 3. 还没有单独补业务说明文档

- 当前代码和烟测已齐
- 但还没有补一份给实施/运维/客户的“字段含义、支持项目、配置示例、常见错误”操作文档

## 结论

当前“客户在客户端配置模型 -> 项目从云端拉 zip -> 客户端解压并执行 -> 执行前注入模型环境变量”主链路已经打通，并已通过打包后的端到端冒烟验证。

如果下一步继续推进，优先级建议是：

1. 补一份面向实施和客户的配置说明文档
2. 决定是否要把模型配置接入云端配置中心
3. 视业务需要再补视频模型链路
