fix: reuse runtime processes across project sessions

Multiple projects could spawn duplicate heavyweight runtimes, while settings changes and remote reconnection could cancel or strand native conversations. Share compatible local OpenCode and DeepSeek Harness process owners and Agent-owned ACP connections, retaining workspace routing, per-session modes, model attribution, question ownership, targeted cancellation and idle cleanup. Restore remote pending questions and terminal task projections across reconnect and desktop restart, and preserve accepted ordinary requests during settings replacement while cancelling expert-team parents with their replaced scheduler. Extend regression coverage and Agent type checks. Record measured resource and real-model validation results, including failures and limitations. Also include the conversation media-generation design drafts (not an implemented feature), documentation entry links and dedicated Linux test-directory guidance. Desktop and Agent changes must be delivered together for shared process results. Validation: typecheck and lint passed; staged content and documentation links checked. Prior full regression and live-model evidence are recorded in progress notes; no new full test suite or model calls were run for this commit. Release note: 多项目会话现在复用兼容的 OpenCode 和 DeepSeek Harness 进程，减少重复启动并保持工作区、工具和取消隔离。修复远端问答在断线、重启及配置更新后的恢复与状态同步问题，Desktop 与 Agent 需配套更新。
2026-09-15 08:14:42 +08:00
parent b755951ecd
commit e5aa9ed688
65 changed files with 4116 additions and 365 deletions
@@ -0,0 +1,35 @@
+# 会话媒体生成
+
+状态：设计草案，尚未实现。日期：2026-09-15。
+
+用户添加生图或生视频模型后，可以开启“允许 AI 在会话中调用”。支持工具调用的聊天模型通过 GoodBuddy 使用这些模型，图片和视频返回当前会话。切换聊天模型或 Agent Runtime 时，生成模型配置、已提交的生成操作和历史成果各自保持明确的归属。
+
+本目录负责普通 LLM 调用媒体模型的产品行为、调用入口和生命周期。现有直连图片协议及连续修改仍由[图片生成](../image-generation/README.md)维护；本设计不表示现有功能已改变。
+
+## 首期范围
+
+首期以图片为主：在直连文本 Model Runtime 中调用已有生图协议，支持文生图及协议已有的参考图编辑。提供模型调用开关、全局默认和本次指定模型，复用图片成果展示。切换聊天模型或离开会话后，已提交生成继续执行，结果保存到原会话。
+
+视频、其他 Runtime 的自动调用、会话级生成模型选择、独立生成表单及跨重启查询恢复留到后续。首期只需 `generate_image` 核心工具，Skill 按实际使用需要补充。需求的阶段划分以[产品需求](./prd.md)为准；下文各设计保留的后续规则不作为首期实现要求。
+
+## 文档导航
+
+| 文档 | 权威职责 |
+| --- | --- |
+| [产品需求](./prd.md) | 范围、需求编号与产品验收 |
+| [用户场景](./user-stories.md) | 用户操作及场景验收 |
+| [行为规则](./logic-design.md) | 选择优先级、切换规则、状态和失败处理 |
+| [界面设计](./ui-design.md) | 配置入口、会话操作、结果卡片和反馈 |
+| [技术设计](./technical-design.md) | Skill、工具、Main 服务、存储与 Runtime 接入 |
+| [进度记录](./progress.md) | 当前代码事实、剩余工作与验证证据 |
+
+## 术语与依赖
+
+聊天模型负责理解请求、调用工具和组织回答；生成模型负责图片或视频输出；Agent Runtime 承载聊天模型及工具执行。Skill 提供能力使用说明，工具提供结构化调用入口，两者不能互相替代。
+
+“生成操作”指一次媒体生成及其结果记录，不自动创建任务中心的 Task，也不引入新的通用 Job 调度系统。领域边界遵循 [Task 与 Job 模型](../task-and-job/task-and-job-model.md)。
+
+- [模型连接](../model-connections/README.md)：连接、凭据、协议及请求定制。
+- [直连文本 Agent](../direct-model-agent/README.md)：文本工具循环与上下文。
+- [远程主机](../remote-host/README.md)：远程 Runtime 与桌面通信。
+- [统一界面规则](../../../UI-DESIGN.md)：控件、反馈和可访问性。
@@ -0,0 +1,77 @@
+# 行为规则
+
+状态：设计草案。此文是模型选择、切换与生成状态的权威定义。
+
+## 首期适用规则
+
+阶段范围以[产品需求](./prd.md)为准。以下 L-1 至 L-5 保留完整目标，首期按这些限定执行：
+
+- L-1：只在直连文本 Model Runtime 暴露图片工具；未接入的 Runtime 或无工具模型显示限制，沿用已有直连图片工作流，不新增显式生成入口。
+- L-2：新建图片按“本次明确指定 > 全局默认”选择；编辑按“本次明确指定 > 原成果模型 > 全局默认”选择。只有前一项未设置时才查下一项；选定模型失效时提示改选。
+- L-3：提交时固定生成模型、连接参数、素材和原会话。首期没有会话级生成选择；新请求在实际提交时解析默认值。切换到未接入的 Runtime 只影响后续自动调用，不取消已提交操作。
+- L-4：对图片请求复用进行中、已完成、失败和已停止等待的状态表达，保存成功后才完成，不预建视频任务状态机。取消后若仍取得成果，更新原卡片并说明取消未生效。重启后未完成记录显示结果未确认，不查询恢复或自动重提。人工重新生成创建新操作；首期不提供独立保存重试。
+- L-5：图片成果引用、无视觉模型的文字上下文及会话归属规则全部适用。
+
+## 能力与调用时点
+
+L-1（FR-1、FR-3、FR-7、FR-9；US-01、US-08、US-11）：会话自动生成需要模型连接允许调用、对应协议可执行、Runtime 能暴露工具、聊天模型支持工具调用，并且请求处于 Execute。Skill 只描述这些真实能力。无工具能力时，显式生成入口直接调用同一服务；Ask 下生成入口不能绕过只读限制。
+
+请求开始和聊天模型、Runtime、配置切换后重新计算可用能力。运行中的聊天回合保留原有工具协议，Main 在真正提交生成前检查最新可用性。这样已关闭的模型即使残留在该回合的工具列表中，也不能接受新操作。
+
+## 模型和素材选择
+
+L-2（FR-2、FR-5；US-02、US-03、US-05、US-07、US-14）：先确定生成类型和操作意图，再按下表选模型。图片与视频的默认值独立保存。
+
+| 操作 | 选择优先级，由高到低 |
+| --- | --- |
+| 新建图片或视频 | 用户本次明确指定 > 当前会话明确选择 > 全局默认 |
+| 编辑历史成果 | 用户本次明确指定 > 当前会话明确选择 > 原成果模型 > 全局默认 |
+
+只有较高优先级未设置时才查看下一项。已选目标被删除、关闭或不支持所需操作时，要求改选，不能静默跳过。没有默认值时由用户选择，可以同时设为默认；名称歧义必须解析到唯一连接后再提交。LLM 不得无依据地填写模型 ID。
+
+显式附件或明确点选的成果优先。用户使用“刚才那张”等明确指代且仅有一个匹配对象时才引用历史图；多义指代先澄清。新建不相关图片不附带旧图。图生视频复用素材引用，但按视频模型选择顺序处理，不沿用图片模型。
+
+编辑能力不足或原图缺失时保留输入并提示。新工具路径不自动将编辑降为纯文生图；用户可以明确选择按文字重新生成。已有直连路径的降级规则仍见[图片技术设计](../image-generation/technical-design.md)。
+
+## 切换规则
+
+L-3（FR-4；US-03 至 US-06、US-11）：生成服务接受提交时固定所属会话、触发消息、实际生成模型、生成参数与素材引用。用户尚未发送的草稿使用发送时配置；已发送且排队的请求保留会话选择，跟随全局默认的选项在实际提交时解析。该时点以后不再重选模型。
+
+| 变化 | 未提交操作 | 已提交操作与成果 |
+| --- | --- | --- |
+| 切换聊天模型 | 下一回合使用新模型及其可用工具 | 不改变生成模型；原回合按 Runtime 切换机制结束，操作独立继续 |
+| 切换 Runtime | 下一回合按新 Runtime 的工具接入能力执行 | 不依赖旧 Runtime 进程；不向新进程补发未配对的旧工具响应 |
+| 切换全局默认 | 跟随默认的操作解析新默认 | 继续原模型 |
+| 切换会话生成模型 | 后续操作使用新选择 | 继续原模型 |
+| 关闭或删除生成连接 | 拒绝该连接的新操作，提示改选 | 已发请求尽力完成；若后续查询所需连接已失效，显示无法继续查询 |
+| 更改地址、凭据或请求参数 | 新操作用新配置 | 当前操作不混用新端点；重启后连接已改变则提示无法继续原操作 |
+| 离开或重开会话 | 会话选择独立保留 | 只更新所属会话，不能写入当前打开的其他会话 |
+
+切换聊天模型不会自动取消媒体生成。“停止回复”只结束当前文字回合；生成卡片的“取消生成”单独处理已提交操作。切到 Ask 不撤销先前 Execute 已提交的操作，也不允许新增生成。
+
+## 操作状态
+
+L-4（FR-6、FR-8；US-04、US-09、US-10、US-13）：状态描述应用实际知道的事实。上游没有百分比时，只显示阶段及已等待时间。
+
+| 状态 | 进入条件 | 后续处理 |
+| --- | --- | --- |
+| 提交中 | 已接受操作，正在发送 | 获得上游响应后生成中或保存中；失败保留原因 |
+| 生成中 | 上游已接受、尚无最终成果 | 查询状态或等待响应，结果返回后保存中 |
+| 保存中 | 已获得成果，Main 正在校验和保存 | 本地成果及引用保存成功后才完成 |
+| 已完成 | 成果可从会话重新读取 | 终态，后续编辑或重试创建新操作 |
+| 取消中 | 用户请求取消、等待终止结果 | 上游确认停止后已取消；若已完成则展示成果并说明取消未生效 |
+| 已取消 | 本地已停止等待或上游确认取消 | 区分“已停止等待，上游可能继续生成”与“生成已取消” |
+| 失败 | 上游明确失败或成果保存失败 | 提供失败原因及适用的重试入口 |
+| 状态待确认 | 提交响应丢失、断连或应用重启，无法确认上游结果 | 有上游 ID 时查询；不能查询时提示用户，不自动重新提交 |
+
+同一操作的重复状态通知只能更新同一记录。取消后的晚到结果不恢复旧工具回合，不自动开始下一次生成。若仍能取得成果，可在原卡片标明“取消未生效，已生成”并展示。超时不等于上游取消，不承诺退款。
+
+重新生成创建独立操作，沿用旧操作的模型和输入，提交前检查可用性；用户改选模型后将新选择显示在新尝试上。保存失败且上游成果仍可读取时，“重试保存”使用原操作 ID，由失败回到保存中并更新原卡片，不再次提交生成。无法确认上游是否接受的请求，不做自动生成重试。
+
+L-5（FR-5、FR-8；US-07、US-12）：历史上下文传成果引用、提示词及实际模型信息。只有具备视觉输入能力的聊天模型才接收适用的图片内容。不能以“有成果引用”推断模型已经看过图片。删除会话沿用已有确认流程，并说明活动生成的取消及不能保证上游停止的情况，删除后晚到结果不能重建会话。
+
+## 完整性与待定项
+
+已覆盖首次配置、模型选择、历史编辑、模型与 Runtime 切换、只读模式、失败、取消、重启和成果归属。无产品规则需要在本次文档交付前补充确认。
+
+视频服务商、协议、取消与查询能力、可接受的文件限制属于实施前的技术选型。远程 Runtime 的工具往返需要原型验证；无法接入时按 L-1 提供显式入口，不把工具接入状态写成已支持。跨设备同步、应用退出后的本地执行不在本次范围。
@@ -0,0 +1,43 @@
+# 产品需求
+
+状态：设计草案。本文描述目标行为，不作为现有能力说明。
+
+## 用户问题与范围
+
+用户希望在文字会话中直接提出“画一张海报”“把背景改成蓝色”“用这张图生成视频”，由聊天助手调用已配置的专用模型。用户不应为了生成媒体而丢失当前聊天入口；切换聊天模型后，也应能继续引用已有成果。
+
+范围包括模型调用开关、默认与会话选择、文生图、支持协议下的参考图编辑、文生视频及图生视频、结果展示和生成过程管理。视频具体服务商及协议待技术选型；接通真实服务前不能宣称视频可用。
+
+不包含模型训练、自动采购服务、无工具能力 LLM 的通用文本指令执行器、批量渲染平台、应用退出后仍由桌面后台执行的承诺。直接选择图片模型的已有工作流继续保留。
+
+## 功能需求
+
+### 首期交付
+
+首期只交付图片生成，自动调用先接通直连文本 Model Runtime。支持已有图片协议下的文生图、参考图编辑、历史图片引用与成果保存，不新增图片协议。保留模型调用开关、一个全局默认生图模型及用户本次明确指定；编辑默认沿用原成果模型。首期不持久化会话级生成模型选择。
+
+切换聊天模型、生成模型或离开会话后，已提交操作仍固定原模型和原会话。切换到尚未接入工具的 Runtime 后，原操作继续，但该 Runtime 暂不能自动发起生图。不支持工具调用时说明限制，用户可使用已有直连图片工作流；首期不增加独立生成表单。
+
+运行状态、取消、错误说明及人工重新生成属于首期。应用退出后不继续本地生成；重新打开时将未完成操作标明结果未确认，不自动重新提交。跨重启查询恢复和独立“重试保存”入口后续再做。
+
+### 后续范围
+
+视频生成与播放、其他本地及远程 Runtime 自动调用、会话级模型选择、独立生成表单、查询恢复及保存重试不纳入首期验收。不为这些能力预建工具、存储字段或界面占位。
+
+以下 FR 编号保留完整目标；FR-1 至 FR-8 按上述首期范围验收，FR-9 首期只要求准确说明已接通的 Runtime 和使用限制，其余接入后分别验收。
+
+| 编号 | 要求 | 产品验收 |
+| --- | --- | --- |
+| FR-1 | 图片、视频模型分别提供会话调用开关；新增和已有连接默认关闭，由用户主动开启 | 保存后成为对应可用能力，关闭后不能再提交新操作；历史成果保留 |
+| FR-2 | 支持全局默认、当前会话选择和本次明确指定 | 按[选择规则](./logic-design.md)解析并显示实际模型；不静默改用其他服务 |
+| FR-3 | 在支持工具调用的聊天模型下，使用自然语言生成媒体 | 从聊天输入到真实服务输出、保存与会话展示完整可用，活动记录可见 |
+| FR-4 | 支持聊天模型、Runtime 及生成模型切换 | 新请求获得当前能力，已提交操作保持原模型和原会话；切换不触发重新生成 |
+| FR-5 | 支持历史成果引用与继续编辑 | 重新打开会话后可引用已保存原图；缺失素材或编辑能力不足时有明确处理入口 |
+| FR-6 | 长耗时生成可独立显示状态、取消与重试 | 离开会话不取消；状态区分上游生成、结果保存、完成及失败，不虚构进度 |
+| FR-7 | 适配工作模式及能力边界 | Ask 不提交生成；不支持工具调用时仍可用 Execute 下的显式生成入口 |
+| FR-8 | 图片、视频作为会话成果保存 | 结果可预览和导出，来源模型可追溯；聊天模型不能看图时只接收文字事实及引用 |
+| FR-9 | 本地和远程 Runtime 有可核验的支持说明 | 自动调用以真实工具往返验收为准；未接通的 Runtime 显示原因及显式生成入口 |
+
+## 交付标准
+
+以[用户场景](./user-stories.md)验收产品路径。生图、视频和各 Runtime 分别记录验证结果，不用某一个模型或 Runtime 的成功代替其他路径。配置连接检查成功不等于生成成功，真实生成成果必须在会话中可见且能重新打开。
@@ -0,0 +1,33 @@
+# 进度记录
+
+## 2026-09-15
+
+根据用户“首期以图片为主”的意见收敛设计，已同步需求、场景、规则、界面及技术文档的阶段范围。首期接通直连文本图片工具，保留模型切换、原会话归属及历史图片引用；后续范围见[产品需求](./prd.md)。
+
+本次只修改设计文档，未检查或改变应用实现，2026-09-14 的代码检查记录保留为当日证据，不表示已重新验证。图片首期仍待实施。
+
+文档验证：7 份文档的一致性审阅未发现首期范围冲突；31 个相对 Markdown 链接均可解析。`deai-writing` 扫描阻断项为 0，31 个复核候选为设计状态、能力职责及行为限制，按语境保留。`git diff --check -- docs/features/conversation-media-generation` 通过；目录当前未跟踪，该命令不覆盖未跟踪文件，内容与链接另行审阅。未运行应用测试或真实生成请求。
+
+## 2026-09-14
+
+当前阶段：设计草案已落盘，功能未实现。本次只新增设计文档与相关入口链接。
+
+代码与文档检查确认以下基础能力：
+
+| 事实 | 证据 |
+| --- | --- |
+| 已有直连图片生成、编辑及历史成果引用 | [图片技术设计](../image-generation/technical-design.md)、`src/main/agent/model-runtime.ts` |
+| 模型连接及 Main 凭据存储已存在 | `src/shared/contracts.ts`、`src/main/runtime-settings-store.ts` |
+| 已有 Skill 发现、Runtime 分配及工具分发 | `src/main/capabilities/capability-service.ts`、`src/main/agent/model-tool-provider.ts` |
+| 会话、消息 metadata 和成果已有 SQLite 存储 | `src/main/assistant/assistant-database.ts`、`src/shared/assistant-contracts.ts` |
+| 生图尚未成为普通 LLM 的内置生成工具 | 检查 `src/shared/builtin-model-tools.ts` 及工具分发路径 |
+| 本次检查未发现第一方视频生成协议实现 | 检查模型能力契约、Runtime 及现有功能文档；不据此推断外部 MCP 的能力 |
+
+剩余工作对应[技术设计实施顺序](./technical-design.md)：模型调用设置与选择、图片服务及会话入口、各 Runtime 接入、视频真实服务与成果交付均待实施。视频协议选择和远程工具桥接验证待完成。
+
+本次未修改应用代码，未运行应用测试或真实生成请求。文档验证记录如下：
+
+- 相对 Markdown 链接检查：7 份新文档及图片功能入口共 33 个链接，失效链接为 0。
+- `deai-writing` 扫描：阻断项为 0；人工复核保留设计状态、能力边界和禁止行为等必要限定，以及真实并列的验收项。
+- 独立一致性审阅发现“重新生成”与“重试保存”的操作身份表述不一致，已在 L-4 和 US-09 中统一：前者创建新操作，后者更新原操作。
+- `git diff --check` 通过。上述检查只验证文档，不构成功能验收。
@@ -0,0 +1,91 @@
+# 技术设计
+
+状态：设计草案。拟议字段和工具名用于评审，不表示已存在公开 API。实现 [FR-1 至 FR-9](./prd.md)及[行为规则 L-1 至 L-5](./logic-design.md)。
+
+## 首期实现边界
+
+首期调用路径为：直连文本 Model Runtime → `generate_image` → Main 图片生成服务 → 现有图片协议 → 原会话 artifact。提取已有图片请求和保存逻辑，Main 持有活动请求，使聊天模型或 Runtime 切换不释放已提交生成。复用现有成果视图与活动反馈。
+
+只新增图片会话调用开关和全局默认图片 profile ID；本次指定作为工具参数。生成记录优先放入现有消息 metadata，保存实际模型、输入、状态及成果引用。首期没有会话级生成选择、视频字段、上游任务恢复信息或独立任务表。
+
+工具说明随每个新回合提供可调用图片模型的脱敏 ID、名称和已支持能力，提交前重新校验配置。先以工具描述承载使用规则；只有实际调用验证表明说明不足时才补充一份共享 Skill，不把 Skill 管理作为交付依赖。首期不注册 `list_media_models`、视频、查询和取消工具，取消通过会话中的操作入口完成。
+
+工具等待遵循现有超时约束；超出回合等待或发生 Runtime 切换后，Main 仍将结果写回原会话。后续回合读取已保存的操作摘要和成果，不补发旧工具响应。应用重启后未完成记录只提示结果未确认，不建立恢复查询或自动重试机制。
+
+以下章节描述完整目标中的调用关系和扩展约束。出现视频、会话选择、额外工具、独立生成表单、其他 Runtime 接入和恢复查询时，均属后续设计，不要求首期预建抽象或占位实现。
+
+## 调用结构
+
+```mermaid
+flowchart TD
+  Chat[聊天模型与 Agent Runtime] --> Tool[媒体工具入口]
+  Skill[内置媒体 Skill 使用说明] -.-> Chat
+  UI[会话显式生成入口] --> Main[Main 媒体生成服务]
+  Tool --> Main
+  Main --> Profile[模型连接与凭据存储]
+  Main --> Adapter[图片或视频协议实现]
+  Adapter --> Provider[生成服务商]
+  Main --> Artifact[操作记录与会话成果]
+  Artifact --> Card[原会话生成卡片]
+```
+
+Main 持有生成请求、取消句柄和结果保存职责。服务生命周期独立于聊天 Runtime controller，切换或释放 controller 不释放已提交的媒体操作。Renderer 经明确 preload/IPC 方法调用；IPC 使用共享契约校验并保留现有发送方校验。凭据只在 Main 解密，不进入 Skill、工具参数或工具输出。
+
+从 `ModelAgentRuntime` 提取现有图片请求、校验和成果处理中的可复用部分，使直连图片与媒体工具共用协议实现。直连路径保持原有上下文与编辑降级策略；工具路径依据 L-2 传入明确的素材和降级选项，避免协议重用改变产品语义。
+
+## Skill 与工具
+
+提供一份内置媒体生成 Skill，说明新建、编辑、图生视频、模型选择、素材引用和结果使用。开启模型配置仅更新能力目录，不为每个连接复制 Skill。能力目录与工具从同一份有效配置生成；Skill 中不保存可过期的模型名单或凭据。
+
+拟议工具：`list_media_models` 返回脱敏的可用连接 ID、名称、已支持操作及参数约束；`generate_image`、`generate_video` 提交生成；`get_media_generation` 查询；`cancel_media_generation` 取消。按操作性质接入现有工作模式控制，不因媒体工具增加额外通用审批。
+
+生成输入包括 `prompt`、可选 `modelProfileId`、显式 `operation`、`sourceArtifactIds` 及协议支持的类型化选项。图片数量、尺寸与质量，以及视频时长、分辨率等按已接入协议校验，不能假定服务商完全兼容。`conversationId`、触发消息及请求身份由运行上下文绑定，不能由 LLM 自由指定目标会话。
+
+提交后返回操作 ID、实际模型和当前状态；完成结果返回成果 ID 与必要文字信息，不把 Base64 或视频字节塞入工具历史。等待有界，长任务通过查询及卡片更新呈现。原回合仍在执行时，可通过其合法工具响应返回最新结果；回合已结束或 Runtime 已切换时，只更新操作记录与原会话卡片，下一回合读取成果摘要，不自动唤起新 LLM 请求。
+
+## 配置与持久化
+
+| 对象 | 最小拟议数据 | 存储职责 |
+| --- | --- | --- |
+| 模型连接 | 会话调用开关、适用生成能力 | 复用 settings/profile；现有连接缺少开关时解释为关闭 |
+| 全局偏好 | 默认图片、视频 profile ID | 复用应用设置；不复制连接及凭据 |
+| 会话选择 | 图片、视频分别为跟随默认或显式 profile ID | 持久化到会话设置，独立于聊天 Runtime selection |
+| 生成操作 | ID、原会话/消息 ID、工具调用关联、状态、实际模型 ID 与名称、提示词、有效参数、素材引用、时间、错误、成果 ID | 优先扩展现有会话消息 metadata；实施时评估查询需求后决定是否需要独立表 |
+| 上游异步信息 | 必要的上游任务 ID、查询所需非敏感参数 | 仅在协议确实支持异步查询时保存；无凭据副本 |
+| 成果 | 媒体内容及类型、原操作与素材关联 | 复用 artifact 体系；不放入 Skill 或 Runtime 内存作为唯一副本 |
+
+已提交操作在内存持有当次解析的连接参数；持久记录只保留来源与恢复查询所必需的非敏感信息。应用重启后通过原连接核对是否仍可查询，不增加凭据历史、通用恢复日志或多阶段提交机制。不能确认时采用 L-4 的“状态待确认”。
+
+操作不自动成为 Task/Job，已有 `runs` 表也不等于通用后台调度已经存在。数据库变更实施前按[迁移规范](../../development/database-migrations.md)评审已发布数据兼容；本次文档不预先引入新表和迁移。
+
+Main 必须在成果持久化成功后发布完成事件，事件按操作 ID 更新而非重复追加。校验素材来自当前会话可访问的附件或成果，继承现有项目、会话隔离，不允许模型填写任意文件路径代替成果引用。
+
+## 图片与视频结果
+
+图片继续遵循[图片技术设计](../image-generation/technical-design.md)：校验有界内联图片，不下载 Provider 返回的图片 URL。现有成果内容字符串上限为 5 MiB，这不是原始二进制文件大小，实施时必须正确处理编码开销和超限提示。
+
+视频不沿用内联图片存储。优先复用 `managed_file` 成果和现有文件导出能力，补充媒体类型、播放所需信息及预览。协议选型必须明确提交、查询、取消、结果读取、认证、文件大小上限、超时和过期时间；最终方案用实际服务的证据补入本文。
+
+若视频服务只返回下载地址，需在视频协议设计中明确 Main 端的读取来源、认证、重定向及字节限制后实现，不能借用或放宽图片 URL 禁止规则。生成媒体读取不使用应用更新或模型包下载源设置；受管软件包镜像规则也不适用于动态生成的媒体结果。无法保存或播放的上游结果不能标记为交付完成。
+
+## Runtime 接入
+
+| 路径 | 设计接入点 | 验证要求 |
+| --- | --- | --- |
+| 直连文本 Model Runtime | `builtin-model-tools.ts` 的工具契约及 `model-tool-provider.ts` 分发 | 自然语言请求实际调用生成模型并返回成果 |
+| 本地 OpenCode、Continue、DeepSeek Harness | 复用各 Runtime 已有工具或 MCP 注入机制，转到同一 Main 服务 | 分别验证发现、调用、查询、取消和切换；不能以 Skill 注入成功代替 |
+| GoodBuddy Agent 远程路径 | 经现有桌面与 Agent 通信能力将工具请求绑定到原会话，Main 执行生成 | 验证真实 Host 的工具往返、断连和结果归属，凭据不下发远端 |
+| 不支持工具调用的聊天模型或尚未接入的 Runtime | Renderer 显式入口经 IPC 调用同一服务 | Execute 可完成生成，Ask 不提交，原会话可查看成果 |
+
+Runtime 进程复用时，新的聊天回合仍需刷新能力目录；不假定修改配置必然重启进程。远程桥接是否可直接复用现有工具分发是实施前的验证项，不能由本地成功推断远程支持。远程断连后桌面仍运行时，可继续管理已提交生成；远程 LLM 停止等待不等于媒体取消。
+
+## 实施顺序与验证
+
+1. 首期：实现图片调用开关、全局默认及本次指定，提取图片服务并接通直连文本 `generate_image`。完成文生图、已有协议编辑、成果保存、取消及模型切换后的结果交付。
+2. 后续按实际需求接通其余本地 Runtime 与远程工具路径，分别验证真实调用及切换。
+3. 后续评估会话级选择、独立生成入口及恢复能力，确认需要后再增加界面和数据。
+4. 视频单独选型与验收，实际接通服务后再增加视频工具、异步查询和播放能力。
+
+首期以图片真实产品路径验收，完成后标记“图片首期完成”，后续能力单独记录。针对首期适用的 L-1 至 L-5 编写选择优先级、配置失效、会话隔离、重复结果、取消及晚到结果测试。验证原直连图片行为不回归，检查进程切换不会重复提交。
+
+源代码实现后运行 `npm test`、`npm run typecheck`、`npm run lint`。首期真实生成从直连文本聊天输入进入，覆盖[用户场景](./user-stories.md)中的首期验收；记录实际请求数量、模型、Runtime 和结果。后续显式入口需独立验证。涉及 Agent 的变更按[远程主机验证要求](../remote-host/technical-design.md)在真实测试 Host 验证。当前仅写文档，不发起收费生成调用。
@@ -0,0 +1,42 @@
+# 界面设计
+
+状态：设计草案。遵循[统一界面设计](../../../UI-DESIGN.md)，实现 [FR-1 至 FR-9](./prd.md)，行为以[行为规则](./logic-design.md)为准。
+
+## 首期界面
+
+首期只在图片模型配置提供会话调用开关和“设为默认生图模型”，沿用下文共享控件规范。关闭或删除默认模型后保留失效选择并提示改选，不自动改用其他模型。
+
+会话以自然语言发起生图，本次指定模型也通过请求表达。不新增会话级模型选择器、独立生成表单或视频入口。未设默认时，助手提示用户本次指定一个可用模型，或到设置中选择默认后重新发送请求；名称有歧义时先澄清。
+
+复用图片成果展示与引用入口，显示实际模型、进行状态、结果或错误，并支持取消和人工重新生成。首期不增加视频播放和独立“重试保存”按钮。不支持工具调用或 Runtime 未接通时说明限制，提示可切换到支持的聊天路径或使用已有直连图片工作流；Ask 下说明生成需要 Execute，不自动切换模式。
+
+以下为完整目标的界面设计，按[产品需求的阶段划分](./prd.md)实施；首期不预留后续控件。
+
+## 模型配置
+
+在现有模型连接表单中，按已支持的生成能力显示持久开关：
+
+- 图片模型：“允许 AI 在会话中调用此模型生成图片”。
+- 视频模型：“允许 AI 在会话中调用此模型生成视频”。
+
+说明文字：“开启后，支持工具调用的聊天助手可使用此模型。生成结果保存在发起请求的会话中。”开关复用共享 Switch，并提供 `role="switch"`、键盘操作及可见焦点。不要求用户维护 Skill 文件或填写第二套 API 凭据。
+
+开启后提供“设为默认生图模型”或“设为默认视频模型”操作。列表在对应模型旁显示“可在会话中调用”和默认标识。关闭、删除默认连接时提示会话选择将不可用，保留原选择供改选，不自动指定其他模型。
+
+## 会话入口
+
+在现有输入区工具菜单提供“生成图片”“生成视频”，以及对应模型选择。默认项写成“跟随全局设置（模型名称）”；没有默认值则显示“选择生成模型”。选择只影响当前会话，设为全局默认必须使用独立操作。
+
+自然语言调用与显式入口共用成果卡片。显式入口提供提示词和参考素材选择，按所选模型展示适用参数，不呈现供应商请求字段。输入区显示已引用的素材缩略图或文件名，可移除。
+
+不支持工具调用时提示“当前聊天模型无法自动调用，可使用生成入口”。Ask 下提示“生成图片或视频需要 Execute 模式”，由用户切换工作模式；不能自动切换。未配置生成模型时给出“添加生成模型”入口。
+
+## 生成卡片
+
+卡片就近显示媒体类型、实际模型、当前阶段、成果或错误。参数、提示词和来源素材放在可展开详情中；不显示密钥、认证头或供应商私有下载地址。运行活动使用同一操作标识，与卡片关联。
+
+图片完成后可预览、下载和“继续修改”；存在可用图生视频能力时提供“生成视频”。视频完成后提供带原生播放控制的预览及下载，不自动播放。点击继续修改会把成果加入输入区，用户填写本次修改要求。
+
+进行中显示“取消生成”，取消结果按行为规则展示。失败显示有针对性的“重试”“重新选择模型”“重新选择素材”或“重试保存”。卡片错误不重复弹出全局错误通知；模型设置保存等非上下文反馈使用应用通知。
+
+窄窗口中操作允许换行，媒体宽度不超过消息区；模型长名称可截断并提供完整可访问名称。状态使用文字表达，不能只依靠颜色；阶段变化通过适度的 `aria-live` 提示，避免等待时间逐秒播报。弹出选择器关闭后焦点回到触发控件。
@@ -0,0 +1,39 @@
+# 用户场景
+
+状态：设计草案。表中 Given、When、Then 分别为前提、操作和预期结果。
+
+## 首期验收
+
+原 US 编号保留完整目标。首期在直连文本 Model Runtime 验收 US-01、US-03、US-04、US-07、US-12、US-14，其中切换后的自动编辑要求目标聊天模型支持工具调用。切换到其他 Runtime 时，只验证原生成继续并写回原会话，不要求新 Runtime 能发起生成。
+
+其余场景的首期预期如下，以[首期行为规则](./logic-design.md)为准：
+
+| 场景 | 首期验收 |
+| --- | --- |
+| US-02 | 未设默认时提示本次指定模型或去设置默认；重新发送后生成，不新增模型选择弹窗 |
+| US-05 | 当前操作使用 X，修改全局默认为 Y 后，新建图片使用 Y，旧操作保持 X |
+| US-06 | 默认或本次指定的 X 不可用时提示改选，历史图片保留；没有会话级选择 |
+| US-08 | 无工具能力时说明限制及已有直连图片工作流；Ask 不提交生成 |
+| US-09 | 图片生成可取消并如实显示结果，人工重新生成创建新操作；没有独立保存重试 |
+| US-13 | 应用重启后未完成图片操作显示结果未确认，不自动查询或重新提交 |
+
+US-10 视频生成、US-11 远程自动调用，以及下表中超出上述范围的预期，留到后续验收。
+
+## 完整目标场景
+
+| 编号 | 需求 | Given | When | Then |
+| --- | --- | --- | --- | --- |
+| US-01 | FR-1、FR-3 | 已添加生图模型并开启会话调用，已选默认模型 | 在支持工具的文字模型中要求画海报 | 活动中显示调用，完成后原会话出现图片及实际模型 |
+| US-02 | FR-2 | 有两个可调用生图模型，未选默认 | 请求生成图片 | 提供模型选择入口，选择后继续原请求；不会自行按列表顺序提交 |
+| US-03 | FR-4、FR-5 | 模型 A 已生成图片 | 切换聊天模型 B，要求修改该图 | B 获得成果引用和可用工具，编辑模型按规则选择 |
+| US-04 | FR-4、FR-6 | 一个生成操作已经提交 | 切换 Runtime 并打开其他会话 | 原操作继续，结果只写回原会话；新 Runtime 不重复调用 |
+| US-05 | FR-2、FR-4 | 会话跟随全局默认，当前操作使用模型 X | 将默认改成 Y，再发一个新建图片请求 | 旧操作仍用 X，新操作用 Y，卡片显示各自来源 |
+| US-06 | FR-4 | 会话明确选择 X | X 被关闭或删除后请求生成 | 显示 X 不可用并允许改选；历史图仍可打开 |
+| US-07 | FR-5、FR-8 | 已保存生成图并重新打开会话 | 显式引用原图，指定另一个支持编辑的模型 | 新模型接收原图；成果丢失时要求重新选择素材，不能假装已编辑 |
+| US-08 | FR-7 | 切换到不支持工具调用的文字模型 | 点击会话显式生图入口 | Execute 下可生成并回写；Ask 下说明需要切换 Execute，不能发出生成请求 |
+| US-09 | FR-6 | 操作正在生成或保存结果 | 点击取消，或失败后选择重试 | 如实显示取消结果；重新生成创建独立操作，重试保存更新原操作，不自动重复收费请求 |
+| US-10 | FR-3、FR-8 | 已接通支持图生视频的模型 | 从图片成果选择生成视频 | 使用所选图片，视频完成并保存后可播放、导出，重开会话仍可访问 |
+| US-11 | FR-4、FR-9 | 远程 Runtime 已接入媒体工具 | 在远程会话中生成后切换本地 Runtime | 结果与活动属于原会话，凭据留在 Main，后续请求可引用成果 |
+| US-12 | FR-5、FR-7 | 新聊天模型没有视觉能力 | 请求分析已生成图片或继续修改 | 说明无法直接查看图片；可根据用户文字调用编辑工具，不编造视觉观察 |
+| US-13 | FR-6 | 上游视频返回可查询的任务标识 | 退出并重开应用 | 查询已有任务；无法查询的中断操作明确提示，不自动重新提交 |
+| US-14 | FR-5 | 同一会话有多张成果 | 要求“修改第二张”或“新画一张无关图片” | 前者引用指定成果，后者不自动附带上一张图；指代不清时先澄清 |