文档：集成图生图客户端契约

.project-docs/20-architecture/data-flow.md

@@ -16,6 +16,7 @@
 | AI 编程模型代理错误 | OpenCode provider 请求 | Main Host AI proxy → Works 模型上游 | 配额耗尽保持独立终止态；只有明确的分组上游饱和才投影为 OpenCode 终止状态，通用限速仍保留 `429` |
 | 设计会话创建/切换 | AI 绘画页面或侧栏 | Renderer API → Main → Workspace Conversation API | 新会话属于现有 Workspace；读取独立消息、Brief、Quote 和 `turnRevision` |
 | 设计消息与确认 | 当前 Conversation | Main → 持久 Agent Gateway Session → Conversation 快照 | 请求和流式结果同时绑定 Workspace + Conversation |
+| 设计单图来源选择 | 当前 Workspace 已完成图片 / 本地图片 | 现有 Asset 上传或选择 → `attachmentAssetIds` → 当前 Conversation Turn | 图片 Brief 用作图生图参考图；视频 Brief 用作首帧；只提交一个真实 Workspace Asset ID |
 | 设计任务同步 | 任一 Conversation 的事件流 / REST | Renderer Workspace 任务列表 | Task 和 Asset 按 Workspace 归并，切换 Conversation 后仍可见 |
 
 ## State Ownership
@@ -26,6 +27,7 @@
 - 本地构建临时目录、HTTP origin 和预检 WebContents/partition 只属于一次调用；预检读取与 `built_archive` 相同的内存字节，但结果不写为可信上传 receipt，也不覆盖生产 opaque-origin。
 - 旧 schema v1 `submitted` 记录迁移并保留；旧 `armed`、`waiting_for_package`、`waiting_for_login`、`uploading`、`failed` 归一为 `legacy_retired`，不再启动 watcher 或上传任务。
 - AI 绘画 Conversation 持有消息、Brief、Quote、`turnRevision` 和服务端 Session 绑定；Workspace 持有 Conversation 列表、生成任务和资产。
+- 图生图参考图与视频首帧都先归一为当前 Workspace 的 Asset；从作品选择时复用生成结果 Asset，本地选择时先走既有上传接口，再把唯一 Asset ID 随 Turn 提交。选择或上传成功后关闭选择器。
 - 本地开发适配器将旧单会话 schema v2 原子迁移为带默认 Conversation 的 schema v3；打包应用不使用该本地适配器作为云端失败回退。
 - 注销和退出会关闭本地事件流并清除本机 Conversation Session-id 缓存；服务端持久 Session 保留，下一次访问从 Conversation API 重新读取。
 - AI 编程 Store 的 `sessionMessagesBySessionId` own-key 是加载状态契约：键缺失表示历史未知，存在且值为 `[]` 表示已知为空。只有后者可使用不读取历史的快速选择；普通历史会话选择继续刷新消息。
@@ -41,4 +43,4 @@
 
 ## Last Updated
 
-2026-08-12
+2026-08-13

.project-docs/20-architecture/module-map.md

@@ -25,7 +25,7 @@
 | `electron/image-workspace/works-square-workspace.ts` | Works Square 多 Conversation 云端适配器与 Gateway 事件映射 | 使用服务端持久 Session；本地清理不 DELETE 远端 Session |
 | `electron/image-workspace/local-workspace.ts` | 未打包开发模式的本地 Workspace 适配器和 v2→v3 迁移 | 仅开发使用，不得成为打包回退 |
 | `src/stores/image-workspace.ts` | 当前 Workspace/Conversation、项目任务及流式更新状态 | 异步结果按 Workspace + Conversation generation/revision 防护 |
-| `src/pages/ImageCanvas/index.tsx` | Conversation 对话、Quote 确认、统一任务列表与新会话入口 | Enter 发送、Shift+Enter 换行、IME 保护 |
+| `src/pages/ImageCanvas/index.tsx` | Conversation 对话、Quote 确认、统一任务列表、新会话入口与单图来源选择器 | 图片 Brief 选择/上传图生图参考图；视频 Brief 绑定首帧；均提交一个 Workspace Asset ID |
 | `src/components/layout/ImageWorkspaceSidebar.tsx` | Workspace 与近期 Conversation 切换/创建 | 切换会话不清空项目级任务 |
 
 ## Dependency Direction
@@ -45,7 +45,8 @@
 - `ai-proxy.ts` 的上游饱和状态投影依赖当前固定 OpenCode 的重试语义和窄化错误文案；升级 runtime 或调整上游错误格式时必须复核，不能把所有 `429` 统一终止。
 - 多 Conversation 事件处理必须区分对话快照与 Workspace 任务更新；不得用任务时间戳推进 Conversation 流水位，也不得让旧会话的迟到流覆盖当前会话。
 - `closeEventSessions` 只负责本地流和缓存生命周期；远端 Conversation Session 是服务端持久资源。
+- 单图来源选择器当前仍由精确中文 quick reply 触发，并以 Brief medium 判断图生图或视频首帧用途；扩展更多输入用途前应先把消息协议升级为结构化 action/purpose，避免展示文案与行为继续耦合。
 
 ## Last Updated
 
-2026-08-12
+2026-08-13

.project-docs/20-architecture/system-overview.md

@@ -19,6 +19,7 @@ Makelore 是 Electron 桌面客户端。Renderer 负责项目操作与状态展
 | Built Artifact Preflight | 在上传前对最终 built snapshot 做桌面/移动 UX fail-fast | Main 使用临时 loopback origin 与 Electron WebContents/CDP；不使用 Playwright、不生成可信证明 |
 | AI Design Workspace | 保存项目身份、Conversation 列表、生成任务和资产 | 任务和资产在切换 Conversation 后继续可见 |
 | AI Design Conversation | 保存消息、Brief、Quote、`turnRevision` 与服务端 Agent Session 绑定 | 同一 Workspace 内互相隔离；Session 由服务端持久化 |
+| AI Design Image Source Picker | 当前 Workspace 已完成图片或本地上传 | 图片 Brief 绑定图生图参考图；视频 Brief 绑定首帧；提交一个真实 Asset ID |
 | AI Design Event Routing | Main 云端适配器 → Host API/SSE → Renderer store | Conversation 更新按 Workspace + Conversation 路由；任务更新按 Workspace 归并 |
 
 ## Important Boundaries
@@ -37,11 +38,13 @@ Makelore 是 Electron 桌面客户端。Renderer 负责项目操作与状态展
 - AI 绘画中，一个 Workspace 可包含多条 Conversation；消息、Brief、Quote 和 `turnRevision` 属于 Conversation，生成任务和资产属于 Workspace。新建 Conversation 不得隐式创建新 Workspace。
 - 每条 Conversation 复用服务端持久 Agent Gateway Session。客户端不得在注销或退出时 DELETE 该 Session；只关闭本地事件流并清除本机 Session-id 缓存，重新访问时从 Conversation API 刷新。
 - Renderer 的异步与流式状态必须同时校验 Workspace + Conversation 身份；项目任务事件只按 Workspace 归并，避免切换会话时丢失任务或接收迟到消息。
+- 图片与视频复用同一个单图来源选择器。图片 Brief 可从当前 Workspace 的已完成作品或本地上传中选择一张参考图继续生成；视频 Brief 使用同一入口绑定首帧。两条路径都必须通过现有 Workspace Asset 上传/选择契约提交一个真实 `attachmentAssetIds`，不得用本地路径或自然语言描述代替资产身份。
+- 当前兼容协议仍通过精确 quick reply `从作品列表选择图片` 打开选择器，并由当前 Brief medium 区分用途；仅 `medium === image` 使用图生图语义，`video`、null 或缺失 medium 保持视频首帧语义。该展示文案耦合不得扩散到更多用途，后续应升级为结构化 action/purpose。
 
 ## Related Decisions
 
-- 当前长期边界记录于 README、ADR-001、集成任务 `20260807-integrate-login-client-a4f8`、源任务 `20260810-static-release-only-a91c`、`20260812-client-built-release-makelore-7e5b` 及本次 Integration Gate；后续如改变唯一入口、凭据所有权、构建执行边界、Conversation 状态归属或重新引入客户端部署协调器，应新增 ADR。
+- 当前长期边界记录于 README、ADR-001、集成任务 `20260807-integrate-login-client-a4f8`、源任务 `20260810-static-release-only-a91c`、`20260812-client-built-release-makelore-7e5b`、`20260812-design-image-to-image-client-c91e` 及本次 Integration Gate；后续如改变唯一入口、凭据所有权、构建执行边界、Conversation 状态归属或重新引入客户端部署协调器，应新增 ADR。
 
 ## Last Updated
 
-2026-08-12
+2026-08-13