# 客户端抖音专家附件打通计划

Status: proposed

Date: 2026-04-10

## 1. 背景

当前客户端到 Douyin expert 的主链路，已经基本具备：

1. 专家页选择 `douyin` 项目
2. 会话绑定到 `project:douyin:*`
3. 默认命中项目 `workspace-entry`
4. 启动项目级执行链路

但这条链路目前仍然基本是“纯文本对话链路”。

对 Douyin 项目来说，这会直接卡住数字人能力，也会限制纯画面路线里的引用素材输入。

## 2. 当前代码事实

### 2.1 已打通部分

- 专家页可以命中项目级 `workspace-entry`
- Douyin 本地纯画面工作流已经有真实成功样例
- Douyin 主流程已支持：
  - `--image`
  - `--audio`
  - `--seedance-reference-image`
  - `--seedance-reference-video`
  - `--seedance-reference-audio`

### 2.2 当前明确缺口

- 客户端专家页输入框目前只有文本输入，没有图片上传入口
- `DesktopApi.chat.sendPrompt()` / `streamPrompt()` 当前只有：
  - `sessionId`
  - `prompt`
  - `skillId`
- IPC 层当前也只透传纯文本 prompt
- `project-workspace-executor` / `project-workspace-agent-runner` 当前只有文本 prompt 输入，没有附件协议
- Douyin 数字人链路当前明确要求必须有图片

### 2.3 对 Douyin 的直接影响

- 数字人路线：当前客户端无法把图片传给 expert，因此无法从客户端直接跑通数字人
- 纯画面路线：无图纯文案可以跑，但参考图 / 参考视频 / 参考音频能力当前无法从客户端输入

## 3. 目标

本次目标不是一次性做完整多模态聊天，而是先补齐最小闭环：

1. 客户端专家页支持选择并发送 1 张本地图片
2. 图片在 main 进程被复制到当前项目目录下的稳定路径
3. `workspace-entry` 能收到这张图的结构化输入
4. Douyin expert 能把这张图用于数字人主图输入
5. smoke 不再只验证 `workspace-entry launch`，至少验证“附件已进入项目执行层”

## 4. 方案范围

### 4.1 本次纳入

- 图片附件协议
- 专家页单图上传
- main 进程项目内落盘
- `workspace-entry` 附件透传
- Douyin expert 单图数字人最小闭环
- smoke 验证升级

### 4.2 本次不纳入

- 多图上传
- 音频上传
- 剪贴板图片
- URL 素材粘贴
- 通用多模态聊天体系重构
- 去修改 Douyin 项目“数字人必须传图”的业务约束

## 5. 实施方案

### 5.1 聊天协议与 IPC

扩展以下调用签名，新增可选 `attachments`：

- `DesktopApi.chat.sendPrompt`
- `DesktopApi.chat.streamPrompt`

新增最小附件结构，v1 先只支持图片：

- `kind: "image"`
- `name`
- `mimeType`
- `localPath`

要求：

- 与当前纯文本调用兼容
- 无附件时行为保持不变
- renderer -> preload -> ipc -> main 全链路统一使用同一份附件结构

### 5.2 专家页 UI

在现有 composer 上补一个最小上传入口：

- 支持选择 1 张本地图片
- 已选择图片可见
- 重选时以最后一次选择覆盖
- 发送成功后清空附件
- 发送失败时保留附件，便于重试

本阶段不引入复杂交互：

- 不做多图排序
- 不做拖拽上传
- 不做素材管理器

### 5.3 Main 进程项目内落盘

main 进程收到图片后，不直接把临时路径传给项目，而是先复制到当前项目目录：

- 目标目录：`inputs/images/main/`

要求：

- 生成稳定文件名
- 绑定当前 `projectId` / `sessionId`
- 禁止跨项目复用错误路径
- 会话未绑定项目时直接返回明确错误

### 5.4 Workspace-entry 执行层

扩展：

- `ProjectExecutionRequest`
- `ProjectWorkspaceExecutionInput`
- `project-workspace-agent-runner` 的输入结构

执行策略：

- 保留原始 `prompt`
- 同时透传 `attachments`
- 如果当前 bundled agent 暂时不能直接吃结构化图片输入，则在 runner 层集中做一次降级，把图片路径转换成稳定提示注入

约束：

- 不在 renderer 层拼接图片说明
- 不在多个中间层重复组装 prompt
- 所有附件降级策略集中在执行层单点处理

### 5.5 Douyin expert 约定

v1 统一约定：

- 客户端上传的单张图片，默认视为“数字人主图 / main image”

这样可以先解当前最刚需的场景：

- 从客户端对话 Douyin expert
- 上传人物图
- 继续生成数字人口播视频

纯画面路线后续可以复用同一套附件协议，再细分为：

- `seedance_image`
- `reference_image`
- `reference_video`
- `reference_audio`

但这些不作为本次第一阶段的强验收项。

## 6. 验收标准

### 6.1 功能验收

满足以下结果即视为本阶段完成：

1. 专家页可选择并发送 1 张图片
2. 图片能落到当前项目 `inputs/images/main/`
3. Douyin expert 在项目执行层能读取到该图片路径
4. 数字人路线不再因为“客户端无法传图”而阻断

### 6.2 回归要求

以下行为不能被破坏：

1. 无附件的纯文本专家对话行为不变
2. 当前已打通的 `workspace-entry` 路由不回退为 skill fallback
3. 现有 Douyin 纯画面文本生成链路不回归

### 6.3 smoke 验收

至少新增或升级以下验证：

1. 专家页上传图片后，附件成功透传到项目执行层
2. `douyin expert cloud-bundle smoke` 不再只接受 `workspace-entry launch`
3. 保留现有纯文本 smoke，确保兼容旧行为

如果环境允许，再补一条本地真实验证：

1. 上传人物图
2. 用文案 + TTS 走数字人
3. 输出 `video_omnihuman.json` 或等效成功产物

## 7. 实施顺序

建议按以下顺序推进，避免前后返工：

1. 先补 shared types / preload / ipc 的附件协议
2. 再补专家页单图上传 UI
3. 再补 main 进程项目内落盘
4. 再补 workspace-entry executor / runner 附件透传
5. 最后补 Douyin smoke 和真实验证

## 8. 默认假设

- v1 只支持单张图片
- v1 只支持本地文件
- v1 不支持音频上传
- v1 不改 Douyin 数字人必须传图的既有约束
- 结构化多模态能力如果当前 runtime 未直接支持，允许 runner 层先做集中降级适配
