root/goodbuddy
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: generate and edit conversation images across runtimes

Browse Source 
Add model-controlled image invocation and read-only runtime assignments. Route image tools through Main so accepted operations retain their originating conversation when chat runtimes change, with saved references, cancellation, and manual recovery.

Keep Node hashing outside browser-shared contracts to restore production builds. Validation includes the production build, typecheck, lint, focused regressions, real Host transport checks, and two successful real image requests. Full UI-driven runtime switching acceptance remains documented as pending.

Release note: 开启图片模型的会话调用后，聊天助手可调用图片生成与编辑工具，Runtime 分配自动管理。图片成果保存在原会话，可继续修改，并独立显示生成状态和取消入口。
This commit is contained in:
mesalogo
2026-09-15 15:51:52 +08:00
parent e5aa9ed688
commit f8d07419d2
78 changed files with 2948 additions and 330 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/features/conversation-media-generation/README.md
+10 -8
View File
@@ -1,16 +1,18 @@
# 会话媒体生成
状态：设计草案，尚未实现。日期：2026-09-15。
状态：设计要求已明确，工作区已有未提交实现，产品验收未完成。日期：2026-09-15。验证范围见[进度记录](./progress.md)。
用户添加生图或生视频模型后，可以开启“允许 AI 在会话中调用”。支持工具调用的聊天模型通过 GoodBuddy 使用这些模型，图片和视频返回当前会话。切换聊天模型或 Agent Runtime 时，生成模型配置、已提交的生成操作和历史成果各自保持明确的归属。
用户添加图片模型后，可以开启“允许 AI 在会话中调用”。支持工具调用的聊天模型通过 GoodBuddy 生成图片、编辑上传图片和历史成果。切换聊天模型或 Agent Runtime 后仍可发起生成和编辑；已提交操作固定生成模型，结果保存到原会话。
本目录负责普通 LLM 调用媒体模型的产品行为、调用入口和生命周期。现有直连图片协议及连续修改仍由[图片生成](../image-generation/README.md)维护；本设计不表示现有功能已改变。
## 首期范围
## 范围
首期以图片为主：在直连文本 Model Runtime 中调用已有生图协议，支持文生图及协议已有的参考图编辑。提供模型调用开关、全局默认和本次指定模型，复用图片成果展示。切换聊天模型或离开会话后，已提交生成继续执行，结果保存到原会话。
图片生成与编辑覆盖直连文本 Model Runtime、本地 OpenCode、Continue、DeepSeek Harness，以及 GoodBuddy Agent 远程路径上的适用 Runtime。复用已有图片协议和各 Runtime 的内部工具或 MCP 注入，由 GoodBuddy 自动管理；用户无需创建 Skill、搭建 MCP server 或重复配置凭据。
视频、其他 Runtime 的自动调用、会话级生成模型选择、独立生成表单及跨重启查询恢复留到后续。首期只需 `generate_image` 核心工具，Skill 按实际使用需要补充。需求的阶段划分以[产品需求](./prd.md)为准；下文各设计保留的后续规则不作为首期实现要求。
使用稳定工具 `generate_image` 完成生成与编辑。全局默认和本次指定模型足够，不新增会话级选择器或独立生成表单。无工具能力的聊天模型明确提示限制，可使用已有直连图片工作流。视频不在本设计范围；完整需求以[产品需求](./prd.md)为准。
图片能力在现有内置 MCP 列表持续可见，Runtime 分配以只读复选框展示，由图片模型的会话调用设置自动管理；没有开启的模型时全部取消勾选，仍保留该行和模型设置入口。分配规则见[行为规则](./logic-design.md)，展示与说明见[界面设计](./ui-design.md)。
## 文档导航
@@ -20,14 +22,14 @@
| [用户场景](./user-stories.md) | 用户操作及场景验收 |
| [行为规则](./logic-design.md) | 选择优先级、切换规则、状态和失败处理 |
| [界面设计](./ui-design.md) | 配置入口、会话操作、结果卡片和反馈 |
| [技术设计](./technical-design.md) | Skill、工具、Main 服务、存储与 Runtime 接入 |
| [技术设计](./technical-design.md) | 工具注入、Main 服务、存储与 Runtime 接入 |
| [进度记录](./progress.md) | 当前代码事实、剩余工作与验证证据 |
## 术语与依赖
聊天模型负责理解请求、调用工具和组织回答；生成模型负责图片或视频输出；Agent Runtime 承载聊天模型及工具执行。Skill 提供能力使用说明，工具提供结构化调用入口，两者不能互相替代。
聊天模型负责理解请求、调用工具和组织回答；生成模型负责图片生成与编辑；Agent Runtime 承载聊天模型及工具执行。工具提供结构化调用入口，使用说明随工具提供，不要求用户管理 Skill。
“生成操作”指一次媒体生成及其结果记录，不自动创建任务中心的 Task，也不引入新的通用 Job 调度系统。领域边界遵循 [Task 与 Job 模型](../task-and-job/task-and-job-model.md)。
“生成操作”指一次图片生成或编辑及其结果记录，不自动创建任务中心的 Task，也不引入新的通用 Job 调度系统。领域边界遵循 [Task 与 Job 模型](../task-and-job/task-and-job-model.md)。
- [模型连接](../model-connections/README.md)：连接、凭据、协议及请求定制。
- [直连文本 Agent](../direct-model-agent/README.md)：文本工具循环与上下文。
docs/features/conversation-media-generation/logic-design.md
+47 -46
View File
@@ -1,77 +1,78 @@
# 行为规则
状态：设计草案。此文是模型选择、切换与生成状态的权威定义。
## 首期适用规则
阶段范围以[产品需求](./prd.md)为准。以下 L-1 至 L-5 保留完整目标，首期按这些限定执行：
- L-1：只在直连文本 Model Runtime 暴露图片工具；未接入的 Runtime 或无工具模型显示限制，沿用已有直连图片工作流，不新增显式生成入口。
- L-2：新建图片按“本次明确指定 > 全局默认”选择；编辑按“本次明确指定 > 原成果模型 > 全局默认”选择。只有前一项未设置时才查下一项；选定模型失效时提示改选。
- L-3：提交时固定生成模型、连接参数、素材和原会话。首期没有会话级生成选择；新请求在实际提交时解析默认值。切换到未接入的 Runtime 只影响后续自动调用，不取消已提交操作。
- L-4：对图片请求复用进行中、已完成、失败和已停止等待的状态表达，保存成功后才完成，不预建视频任务状态机。取消后若仍取得成果，更新原卡片并说明取消未生效。重启后未完成记录显示结果未确认，不查询恢复或自动重提。人工重新生成创建新操作；首期不提供独立保存重试。
- L-5：图片成果引用、无视觉模型的文字上下文及会话归属规则全部适用。
状态：设计草案。此文是模型选择、切换与生成状态的权威定义，范围见[产品需求](./prd.md)。L-1 至 L-5 编号保留，以下规则替代原视频、会话级选择及通用查询恢复规则。
## 能力与调用时点
L-1（FR-1、FR-3、FR-7、FR-9；US-01、US-08、US-11）：会话自动生成需要模型连接允许调用、对应协议可执行、Runtime 能暴露工具、聊天模型支持工具调用，并且请求处于 Execute。Skill 只描述这些真实能力。无工具能力时，显式生成入口直接调用同一服务；Ask 下生成入口不能绕过只读限制。
L-1（FR-1、FR-3、FR-7、FR-9；US-01、US-08、US-11、US-15 至 US-19）：自动生成与编辑要求图片连接允许会话调用、协议支持所需操作、聊天模型支持工具调用且当前请求处于 Execute。直连文本 Model Runtime、本地 OpenCode、Continue、DeepSeek Harness 及 GoodBuddy Agent 远程适用 Runtime 均须接入同一图片能力，内部工具或 MCP 注入由 GoodBuddy 管理。
请求开始和聊天模型、Runtime、配置切换后重新计算可用能力。运行中的聊天回合保留原有工具协议，Main 在真正提交生成前检查最新可用性。这样已关闭的模型即使残留在该回合的工具列表中，也不能接受新操作。
允许调用的模型目录取自已保存且“允许 AI 在会话中调用”开启的图片模型配置。目录非空时，图片生成与编辑能力的全部支持 Runtime 分配自动勾选；目录为空时全部取消勾选。模型配置是唯一事实来源，不保存独立可变的能力启用或分配设置，用户不能操作分配复选框。
| 配置或运行变化 | 分配与目录结果 |
| --- | --- |
| 首次开启或重新开启一个图片模型 | 自动勾选全部支持 Runtime，目录包含该模型 |
| 关闭或删除一个模型，仍有其他开启模型 | 分配保持勾选，从目录移除该模型 |
| 最后一个开启模型被关闭或删除，或从未开启任何模型 | 全部分配取消勾选，目录为空；能力行、说明和模型设置入口仍可见 |
| Runtime 离线、聊天模型无工具能力、Ask、配置或执行错误 | 保持按模型开关推导的勾选和目录，另行显示调用限制或错误 |
配置保存成功后同步刷新分配展示和允许模型目录；保存失败时保留最后已保存配置推导的状态。分配不表示运行就绪，也不保证每个图片模型支持编辑；协议及实际提交校验仍适用。
请求开始和聊天模型、Runtime、配置切换后刷新可用能力；进程复用也须刷新。运行中的聊天回合保留原工具协议，Main 在实际提交前检查最新配置及工作模式，已关闭的连接不能接受新操作。无工具模型说明限制并提示已有直连图片工作流；Ask 不提交生成或编辑，不自动切换模式。Runtime 接入尚未完成属于实施缺口，不能作为减少支持范围的规则。
## 模型和素材选择
L-2（FR-2、FR-5；US-02、US-03、US-05、US-07、US-14）：先确定生成类型和操作意图，再按下表选模型。图片与视频的默认值独立保存。
L-2（FR-2、FR-5；US-02、US-03、US-05、US-07、US-14、US-15）：先确定新建或编辑，再选择图片模型。
| 操作 | 选择优先级，由高到低 |
| --- | --- |
| 新建图片或视频 | 用户本次明确指定 > 当前会话明确选择 > 全局默认 |
| 编辑历史成果 | 用户本次明确指定 > 当前会话明确选择 > 原成果模型 > 全局默认 |
| 新建图片 | 用户本次明确指定 > 全局默认 |
| 编辑历史成果 | 用户本次明确指定 > 原成果模型 > 全局默认 |
| 编辑上传图片（无来源模型） | 用户本次明确指定 > 全局默认 |
只有较高优先级未设置时才查看下一项。已选目标被删除、关闭或不支持所需操作时，要求改选，不能静默跳过。没有默认值时由用户选择，可以同时设为默认；名称歧义必须解析到唯一连接后再提交。LLM 不得无依据地填写模型 ID。
只有较高优先级未设置时才查看下一项。选定模型被删除、关闭或不支持编辑时提示改选，不静默跳过。未设默认时提示本次指定或去设置默认后重新发送；名称歧义先澄清，LLM 不得编造模型 ID。不持久化会话级生成模型选择。
显式附件或明确点选的成果优先。用户使用“刚才那张”等明确指代且仅有一个匹配对象时才引用历史图；多义指代先澄清。新建不相关图片不附带旧图。图生视频复用素材引用，但按视频模型选择顺序处理，不沿用图片模型。
编辑能力不足或原图缺失时保留输入并提示。新工具路径不自动将编辑降为纯文生图；用户可以明确选择按文字重新生成。已有直连路径的降级规则仍见[图片技术设计](../image-generation/technical-design.md)。
显式附件或点选成果优先。“刚才那张”等指代仅在对象唯一时解析；多义指代先澄清。新建不相关图片不附带旧图。编辑能力不足或原图缺失时保留输入并提示，不把编辑自动降为文生图；用户可以明确要求按文字重新生成。已有直连图片路径的行为仍由[图片技术设计](../image-generation/technical-design.md)定义。
## 切换规则
L-3（FR-4；US-03 至 US-06、US-11）：生成服务接受提交时固定所属会话、触发消息、实际生成模型、生成参数与素材引用。用户尚未发送的草稿使用发送时配置；已发送且排队的请求保留会话选择，跟随全局默认的选项在实际提交时解析。该时点以后不再重选模型。
L-3（FR-4；US-03 至 US-07、US-11、US-15）：Main 接受提交时固定原会话、触发消息、实际图片模型、当次连接参数、生成参数及素材引用。未提交请求在实际提交时解析默认值并校验显式选择；提交后不重选模型。图片请求由 Main 持有，独立于聊天 Runtime 生命周期。
| 变化 | 未提交操作 | 已提交操作与成果 |
| --- | --- | --- |
| 切换聊天模型 | 下一回合使用新模型及其可用工具 | 不改变生成模型；原回合按 Runtime 切换机制结束，操作独立继续 |
| 切换 Runtime | 下一回合按新 Runtime 的工具接入能力执行 | 不依赖旧 Runtime 进程；不向新进程补发未配对的旧工具响应 |
| 切换全局默认 | 跟随默认的操作解析新默认 | 继续原模型 |
| 切换会话生成模型 | 后续操作使用新选择 | 继续原模型 |
| 关闭或删除生成连接 | 拒绝该连接的新操作，提示改选 | 已发请求尽力完成；若后续查询所需连接已失效，显示无法继续查询 |
| 更改地址、凭据或请求参数 | 新操作用新配置 | 当前操作不混用新端点；重启后连接已改变则提示无法继续原操作 |
| 离开或重开会话 | 会话选择独立保留 | 只更新所属会话，不能写入当前打开的其他会话 |
| 切换聊天模型 | 新回合使用新模型及可用工具，无工具能力时说明限制 | 图片模型不变，操作独立继续 |
| 切换本地或远程 Runtime | 新回合注入图片工具，可发起生成和编辑 | 不依赖旧进程，不向新进程补发旧工具响应，不重放生成 |
| 更改全局默认或本次指定 | 新操作按 L-2 解析 | 保持提交时模型 |
| 关闭或删除连接 | 拒绝新操作并提示改选 | 已发请求使用当次配置尽力完成 |
| 更改地址、凭据或参数 | 新操作使用新配置 | 当前操作不混用新端点或凭据 |
| 离开或重开会话 | 使用当前请求及全局配置 | 只更新原会话，历史成果仍可引用 |
| 远程断连 | 未被 Main 接收的请求不能声称已提交 | 桌面仍运行时由 Main 继续管理已接收操作 |
切换聊天模型不会自动取消媒体生成。“停止回复”只结束当前文字回合；生成卡片的“取消生成”单独处理已提交操作。切到 Ask 不撤销先前 Execute 已提交的操作，也不允许新增生成。
“停止回复”只结束文字回合；“取消生成”单独处理图片操作。切到 Ask 不撤销先前 Execute 已提交的操作，也不允许新增生成。运行时切换不自动唤起新的 LLM 请求。
## 操作状态
L-4（FR-6、FR-8；US-04、US-09、US-10、US-13）：状态描述应用实际知道的事实。上游没有百分比时，只显示阶段及已等待时间。
L-4（FR-6、FR-8；US-04、US-09、US-13）：复用现有操作与成果反馈，状态只表达实际知道的事实。没有上游百分比时显示状态及等待时间，不虚构进度。
| 状态 | 进入条件 | 后续处理 |
| --- | --- | --- |
| 提交中 | 已接受操作，正在发送 | 获得上游响应后生成中或保存中；失败保留原因 |
| 生成中 | 上游已接受、尚无最终成果 | 查询状态或等待响应，结果返回后保存中 |
| 保存中 | 已获得成果，Main 正在校验和保存 | 本地成果及引用保存成功后才完成 |
| 已完成 | 成果可从会话重新读取 | 终态，后续编辑或重试创建新操作 |
| 取消中 | 用户请求取消、等待终止结果 | 上游确认停止后已取消；若已完成则展示成果并说明取消未生效 |
| 已取消 | 本地已停止等待或上游确认取消 | 区分“已停止等待，上游可能继续生成”与“生成已取消” |
| 失败 | 上游明确失败或成果保存失败 | 提供失败原因及适用的重试入口 |
| 状态待确认 | 提交响应丢失、断连或应用重启，无法确认上游结果 | 有上游 ID 时查询；不能查询时提示用户，不自动重新提交 |
| 状态表达 | 条件与处理 |
| --- | --- |
| 进行中 | 正在发送或等待响应；仅有上游确认时才说明已接受生成 |
| 保存中 | 已取得图片，Main 正在校验并保存 |
| 已完成 | 图片及会话引用已保存，可重新读取 |
| 取消中 | 已请求终止，尚无明确结果 |
| 已停止等待／已取消 | 本地中断只说明“已停止等待，上游可能继续生成”；上游确认停止才说明“生成已取消” |
| 失败 | 有明确的请求或保存失败原因，保留输入和错误上下文 |
| 结果未确认 | 响应丢失、超时或重启后无法确认结果，不当作上游失败或取消 |
同一操作的重复状态通知只能更新同一记录。取消后的晚到结果不恢复旧工具回合，不自动开始下一次生成。若仍能取得成果，可在原卡片标明“取消未生效，已生成”并展示。超时不等于上游取消，不承诺退款。
同一操作的通知更新同一记录。取消后仍取得图片时，在原卡片保存并说明“取消未生效，已生成”，不恢复旧工具回合。超时不等于上游取消，不承诺退款。
重新生成创建独立操作，沿用旧操作的模型和输入，提交前检查可用性；用户改选模型后将新选择显示在新尝试上。保存失败且上游成果仍可读取时，“重试保存”使用原操作 ID，由失败回到保存中并更新原卡片，不再次提交生成。无法确认上游是否接受的请求，不做自动生成重试。
人工重新生成创建新操作，沿用原模型与输入并重新校验；改选模型时在新卡片显示实际选择。失败、结果未确认及保存失败均不自动重发收费请求，不设置独立保存重试入口。应用退出后不承诺继续本地执行，重启时未完成记录显示结果未确认，不建立跨重启查询恢复或通用恢复框架。
L-5（FR-5、FR-8；US-07、US-12）：历史上下文传成果引用、提示词及实际模型信息。只有具备视觉输入能力的聊天模型才接收适用的图片内容。不能以“有成果引用”推断模型已经看过图片。删除会话沿用已有确认流程，并说明活动生成的取消及不能保证上游停止的情况，删除后晚到结果不能重建会话。
## 历史成果
## 完整性与待定项
L-5（FR-5、FR-8；US-07、US-12、US-14、US-15）：历史上下文提供成果引用、提示词及实际图片模型信息。只有具备视觉输入能力的聊天模型才接收适用的图片内容；无视觉模型可根据用户文字将原图引用交给编辑工具，但不能声称看过图片。上传图片和历史成果均使用已有可持久化素材引用。
已覆盖首次配置、模型选择、历史编辑、模型与 Runtime 切换、只读模式、失败、取消、重启和成果归属。无产品规则需要在本次文档交付前补充确认。
删除会话沿用已有确认流程，说明活动生成的取消及无法保证上游停止的情况；删除后的晚到结果不能重建会话。
视频服务商、协议、取消与查询能力、可接受的文件限制属于实施前的技术选型。远程 Runtime 的工具往返需要原型验证；无法接入时按 L-1 提供显式入口，不把工具接入状态写成已支持。跨设备同步、应用退出后的本地执行不在本次范围。
## 完整性与实施验证
规则覆盖配置、新建、上传图与历史图编辑、模型与 Runtime 切换、Ask、无工具或无视觉模型、取消、失败、重启和会话归属。没有待定产品范围；各 Runtime 工具注入、远程往返及取消传播的具体接法需在实施时核验，按[技术设计](./technical-design.md)完成真实路径验收。视频、跨设备同步和应用退出后的本地执行不在范围内。
docs/features/conversation-media-generation/prd.md
+21 -27
View File
@@ -4,40 +4,34 @@
## 用户问题与范围
用户希望在文字会话中直接提出“画一张海报”“把背景改成蓝色”“用这张图生成视频”，由聊天助手调用已配置的专用模型。用户不应为了生成媒体而丢失当前聊天入口；切换聊天模型后，也应能继续引用已有成果。
用户希望在文字会话中直接提出“画一张海报”“把上传图片的背景改成蓝色”“继续修改刚才的图片”，由聊天助手调用已配置的图片模型。切换聊天模型或 Runtime 后，应能继续生成、引用和编辑图片。
范围包括模型调用开关、默认与会话选择、文生图、支持协议下的参考图编辑、文生视频及图生视频、结果展示和生成过程管理。视频具体服务商及协议待技术选型；接通真实服务前不能宣称视频可用。
范围包括图片模型调用开关、全局默认与本次指定、文生图、已有协议支持的上传图片和历史图片编辑、成果保存、取消及状态反馈。支持直连文本 Model Runtime、本地 OpenCode、Continue、DeepSeek Harness，以及 GoodBuddy Agent 远程路径上的适用 Runtime；各路径的生成、编辑和切换均属于验收范围。
不包含模型训练、自动采购服务、无工具能力 LLM 的通用文本指令执行器、批量渲染平台、应用退出后仍由桌面后台执行的承诺。直接选择图片模型的已有工作流继续保留。
GoodBuddy 自动管理内部工具或 MCP 注入，复用模型连接与凭据。用户无需创建 Skill、搭建 MCP server 或填写第二套凭据。自动调用要求聊天模型支持工具调用；无工具能力时明确说明限制，用户可使用已有直连图片工作流。
不包含视频生成、模型训练、自动采购服务、通用文本指令执行器、批量渲染平台或应用退出后继续本地执行的承诺。不新增图片协议、会话级生成模型选择器、独立生成表单或通用恢复框架，也不安排视频交付计划。
## 功能需求
### 首期交付
首期只交付图片生成，自动调用先接通直连文本 Model Runtime。支持已有图片协议下的文生图、参考图编辑、历史图片引用与成果保存，不新增图片协议。保留模型调用开关、一个全局默认生图模型及用户本次明确指定；编辑默认沿用原成果模型。首期不持久化会话级生成模型选择。
切换聊天模型、生成模型或离开会话后，已提交操作仍固定原模型和原会话。切换到尚未接入工具的 Runtime 后，原操作继续，但该 Runtime 暂不能自动发起生图。不支持工具调用时说明限制，用户可使用已有直连图片工作流；首期不增加独立生成表单。
运行状态、取消、错误说明及人工重新生成属于首期。应用退出后不继续本地生成；重新打开时将未完成操作标明结果未确认，不自动重新提交。跨重启查询恢复和独立“重试保存”入口后续再做。
### 后续范围
视频生成与播放、其他本地及远程 Runtime 自动调用、会话级模型选择、独立生成表单、查询恢复及保存重试不纳入首期验收。不为这些能力预建工具、存储字段或界面占位。
以下 FR 编号保留完整目标；FR-1 至 FR-8 按上述首期范围验收，FR-9 首期只要求准确说明已接通的 Runtime 和使用限制，其余接入后分别验收。
保留 FR-1 至 FR-9 编号。原需求中的视频部分移出范围，FR-2 的会话级选择由全局默认和本次指定替代，FR-7 的新增显式入口由已有直连图片工作流替代；下表为当前定义。
| 编号 | 要求 | 产品验收 |
| --- | --- | --- |
| 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 显示原因及显式生成入口 |
| FR-1 | 图片模型提供“允许 AI 在会话中调用”开关；新增和已有连接默认关闭，由用户主动开启；模型配置是图片能力启用与 Runtime 分配的唯一事实来源 | 至少一个模型开启时自动勾选全部支持 Runtime；全部关闭或删除时全部取消勾选；关闭或删除其中一个后若仍有开启模型，保持勾选并更新允许调用的模型目录；被关闭模型拒绝新操作，历史成果保留 |
| FR-2 | 支持全局默认和本次明确指定；编辑可沿用原成果模型 | 按[选择规则](./logic-design.md)解析并显示实际模型；失效或有歧义时提示，不静默换服务 |
| FR-3 | 在支持工具调用的聊天模型下，以自然语言生成和编辑图片 | 上传图片、历史图片及文生图均可经真实服务处理，保存后在原会话展示，活动记录可见 |
| FR-4 | 支持聊天模型、Runtime 及生成模型切换 | 切换后可发起新的生成和编辑；已提交操作固定原模型和原会话，不重复提交 |
| FR-5 | 支持上传素材、历史成果引用与连续编辑 | 重开会话及切换 Runtime 后可引用已保存原图；缺失素材或能力不足时保留输入并提示处理方式 |
| FR-6 | 生成操作独立显示状态，支持取消及人工重新生成 | 离开会话不取消；保存成功才完成；不虚构进度，不自动重试收费请求；重启后未完成操作显示结果未确认 |
| FR-7 | 遵循工作模式及模型能力边界 | Ask 不提交生成或编辑；无工具模型说明限制，可使用已有直连图片工作流，无需新增表单 |
| FR-8 | 图片作为会话成果保存 | 可预览、导出和重新打开，来源模型可追溯；无视觉聊天模型只接收文字事实及引用，不编造观察 |
| FR-9 | 本地及 GoodBuddy Agent 远程适用 Runtime 均支持图片工具；GoodBuddy 管理的图片生成与编辑能力及 Runtime 分配持续可见 | 分别完成真实生成、编辑、切换验收；分配复选框只读，不可手动切换；无开启模型时仍显示该行、未勾选状态、自动管理说明及模型设置入口；无独立能力启停、分配、移除或凭据编辑设置，用户无需维护 Skill 或 MCP server |
## 交付标准
分配表示模型配置允许的调用范围。聊天模型不支持工具、Ask、Runtime 离线、配置错误或执行失败均单独说明，不取消配置分配的勾选；不保存可独立修改的能力启用或 Runtime 分配状态。具体推导与刷新规则由 L-1 定义。
以[用户场景](./user-stories.md)验收产品路径。生图、视频和各 Runtime 分别记录验证结果，不用某一个模型或 Runtime 的成功代替其他路径。配置连接检查成功不等于生成成功，真实生成成果必须在会话中可见且能重新打开。
## 产品验收
以[用户场景](./user-stories.md)验收。各 Runtime 分别记录真实工具往返、生成、上传图编辑、历史图编辑及切换结果，不能用单一路径成功代替其他路径。配置检查或工具注入成功不等于生成成功，成果必须可在会话中重新打开。
Runtime 接入细节和真实 Host 验证属于实施工作，未验证时如实记录未完成，不据此缩减 FR-9 的支持范围。
docs/features/conversation-media-generation/progress.md
+54 -4
View File
@@ -2,13 +2,63 @@
## 2026-09-15
根据用户“首期以图片为主”的意见收敛设计，已同步需求、场景、规则、界面及技术文档的阶段范围。首期接通直连文本图片工具，保留模型切换、原会话归属及历史图片引用；后续范围见[产品需求](./prd.md)。
### 真实图片请求与构建修复
本次只修改设计文档，未检查或改变应用实现，2026-09-14 的代码检查记录保留为当日证据，不表示已重新验证。图片首期仍待实施。
已使用现有 `gpt-image2` 连接（模型 `sub-gpt-image-2`）经生产 `ImageGenerationService` 发起两次真实图片请求：生成白底蓝色圆形，再上传该成果将圆形改成红色。两次均 HTTP 200，保存并重新解码成功，导出图片目视检查符合要求。请求数为 2，自动重试为 0，用户保存的配置未修改。请求尺寸为 1024×1024，供应商实际返回两张 1254×1254 PNG；未对结果重采样。证据保存在本机临时目录 `image-bounded-oiOPRi/`。此项验证 Main 图片服务与真实供应商，尚不替代真实聊天模型经各 Runtime 自行调用工具及完整界面切换验收。
文档验证：7 份文档的一致性审阅未发现首期范围冲突；31 个相对 Markdown 链接均可解析。`deai-writing` 扫描阻断项为 0，31 个复核候选为设计状态、能力职责及行为限制，按语境保留。`git diff --check -- docs/features/conversation-media-generation` 通过；目录当前未跟踪，该命令不覆盖未跟踪文件，内容与链接另行审阅。未运行应用测试或真实生成请求。
用户报告 Renderer 生产构建失败，定位到 `remote-image-tool-contracts.ts` 的 `node:crypto` 被共享契约间接引入浏览器。已将 MCP 名称哈希移至仅 Main 与 Agent 引用的 `remote-image-tool-node.ts`，共享消息编解码使用标准 `TextEncoder`/`TextDecoder`，无新增依赖或 polyfill。修复后 `npm run build`（含类型检查、Main、Preload、Renderer 构建）、`npm run lint` 通过，4 个相关测试文件共 89 项通过。此前仅运行类型检查和测试未发现这一构建问题，不能作为生产构建通过证据。
## 2026-09-14
### 实施与集成复验
工作区已有模型会话调用开关、默认图片模型、配置派生的四种 Runtime 只读分配、Main 图片服务、上传与历史成果引用、操作状态及取消/重新生成 IPC。本地 Model、OpenCode、Continue、DeepSeek Harness 和受管远程 OpenCode 均已接入同一服务。操作复用消息 metadata 和成果存储，未新增任务表或独立分配设置。
本轮修复远程保留会话在图片目录清空后未刷新 MCP，以及 Continue 准备自定义 MCP 失败时未释放本次图片工具令牌的问题。图片卡片更新保持原顺序；取消提示区分请求取消、停止等待和取消未生效后的结果保存。失败卡片提供模型设置与素材重选入口，无工具能力及 Ask 有相应提示。长名称和提示词自动换行，窄窗口及 200% 缩放下恢复按钮可换行。
验证证据如下；此前小节中的超时和未验证记录仅代表各次检查时点：
| 验证 | 结果与边界 |
| --- | --- |
| `npm test` | 364 个文件通过、9 个跳过；4,267 项通过、67 项跳过。后续恢复入口及样式修改另有 269 项定向测试通过，未再运行全量测试 |
| `npm run typecheck`、`npm run lint` | 最后一次 Renderer 修改后通过 |
| 真实 Linux Host | 最终 Agent 构建通过固定主机身份连接，使用实际远程 OpenCode；Ask、Execute 各 1 次真实文本请求均 HTTP 200 并完成，真实图片请求 0 次 |
| Host 图片工具往返 | 最终运行含 7 次受控图片请求、15 次受控文本请求；生成、上传和历史图编辑、目录刷新、Ask 隐藏、并发会话归属、停止回复和断连后 Main 继续保存均通过。图片服务返回固定内联 PNG，不构成真实生图证明 |
| Electron 界面 | 当前生产组件、样式、字体及双语文案，使用隔离 fixture API；初轮 94 项检查，恢复入口完成后 40 项检查通过。覆盖明暗主题、四种窗口尺寸、键盘导航及 200% 缩放；没有修改用户配置 |
最终 Host 运行退出码为 0，残留自有进程为 0，隔离目录和上传文件已清理。此前受控复验另有 7 次图片请求和 15 次文本请求，因此本轮合计真实文本请求 2 次、真实图片请求 0 次、受控图片请求 14 次、受控文本请求 30 次。此前历史测试记录不计入此合计。
本机临时证据位于 `C:/Users/jiang/AppData/Local/Temp/opencode/`：`image-review-full-tests-20260915.stdout.log`、`image-host-final-real-20260915.stdout.log`、`image-host-review-20260915.stdout.log` 及 `image-visual-0915/`。这些是开发检查产物，不随产品发布。
当时尚未完成真实图片供应商生成与编辑；后续验证见上方记录。完整 Electron Main/Preload 路径中的自然语言触发及本地/远程双向切换验收仍待完成，FR-3、FR-9 尚未完成全部产品验收。
隔离的真实图片验证脚本离线校验通过后，已按用户要求执行上述两次真实请求。该连接的会话调用仅在验证内存中启用，不修改保存配置。此前 `deai-writing` 文档扫描阻断项为 0，25 个候选经语境复核保留产品边界、状态限制和历史证据；`git diff --check` 通过。
### Renderer 与设置复查
本轮在已有未提交实现上修复图片操作卡片：状态事件原位更新，保留同一消息中多次生成的卡片顺序；取消提示区分正在请求取消、已停止等待和取消未生效但图片已保存。按钮通过 `aria-describedby` 关联就地操作错误，中英文提示同步更新。补充组件回归，并在现有 App 测试中检查离开原会话、结果晚到、返回及切换 Runtime 后继续修改时的卡片顺序。
已检查模型设置、RuntimeSettingsStore、CapabilityService 和共享设置契约。现有实现从已保存模型开关派生四种 Runtime 的只读分配，不持久化独立分配；关闭或删除默认图片模型后保留失效默认。相关测试本轮通过，未改动这些生产契约。共享工具目录测试原先仅排除浏览器工具，现补充图片受管能力例外，确认 `generate_image` 保持写操作且不重复进入直连模型设置分组。
验证记录：
- `npx vitest run src/renderer/src/ImageOperationStatus.test.tsx src/renderer/src/App.test.tsx src/renderer/src/SettingsPanel.test.tsx src/main/runtime-settings-store.test.ts src/main/capabilities/capability-service.test.ts`：5 个文件、451 项通过。
- 修正目录测试后，`npx vitest run src/shared/builtin-model-tools.test.ts src/renderer/src/ImageOperationStatus.test.tsx`：2 个文件、5 项通过。
- `npm run typecheck`、`npm run lint` 通过。
- `npm test` 在 120 秒上限被终止；期间报告的共享工具目录测试失败已单独修正并复验，未取得全量测试通过结论。
- 未调用真实文本或图片服务，请求数均为 0；未执行 Electron 视觉验收或真实 Host 验证。本轮没有修改 `src/main/agent` 或 `src/agent-daemon`。各 Runtime 的真实生成、编辑、取消及切换验收仍待完成。
### 此前文档修订记录
本日补充：已按最新明确接受的要求修订 FR-1、FR-9、L-1、界面与技术设计，并新增 US-16 至 US-19。只读分配及模型配置派生规则见[行为规则](./logic-design.md)，受管行、说明与无障碍要求见[界面设计](./ui-design.md)。已读取根目录与 features 的 AGENTS、根 UI-DESIGN.md 及本目录七份现有文档，保留此前未提交修订；本次未修改目录外文件或应用代码，相关行为仍待实现与产品验收。
本日更正：此前将其他 Runtime 自动调用排除在交付范围之外的记录不符合用户要求，现由本条替代。七份文档已统一为图片生成和编辑，支持范围及验收以[产品需求](./prd.md)和[用户场景](./user-stories.md)为准，不再保留分期规则。视频移出范围，US-10 保留编号并明确标注；其他被替代要求已记录编号变更。
本次只修改本目录设计文档，未检查或改变应用实现。2026-09-14 记录仅为当日历史证据，不表示已重新验证。图片工具、Main 请求生命周期、各本地及 GoodBuddy Agent 远程适用 Runtime 的生成、编辑和切换均仍需实施与实际验证；具体注入及桥接核验属于实施工作，不缩减支持范围。
本次文档验证：7 份文档的 38 个相对 Markdown 链接均可解析；一致性审阅覆盖模型配置唯一来源、只读分配、空目录保留行、运行状态独立及完整 Runtime 范围，未发现分期或缩减支持范围的现行规则。`deai-writing` 扫描阻断项为 0，25 个复核候选涉及设计状态、职责与必要行为限制，逐条按语境保留，并通读检查结构及前后规则。`git diff --check -- docs/features/conversation-media-generation` 通过；本次七份文件均已被 Git 跟踪，检查覆盖其工作区差异。该命令不覆盖未跟踪文件，不能沿用此前“目录未跟踪”的结论。未运行应用测试或真实生成请求，未声称功能完成或重新验证此前代码。
## 2026-09-14（历史记录）
以下保留当日检查与原设计记录，其中视频、保存重试等旧范围已被 2026-09-15 更正取代，不作为当前实施要求。
当前阶段：设计草案已落盘，功能未实现。本次只新增设计文档与相关入口链接。
docs/features/conversation-media-generation/technical-design.md
+49 -59
View File
@@ -1,91 +1,81 @@
# 技术设计
状态：设计草案。拟议字段和工具名用于评审，不表示已存在公开 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 接入和恢复查询时，均属后续设计，不要求首期预建抽象或占位实现。
状态：工作区实现已接通，真实图片服务与完整产品验收未完成，证据见[进度记录](./progress.md)。内部契约实现 [FR-1 至 FR-9](./prd.md)及[行为规则 L-1 至 L-5](./logic-design.md)，不作为外部公开 API。
## 调用结构
```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[原会话生成卡片]
Direct[直连文本 Model Runtime] --> Tool[generate_image]
Local[本地 OpenCode / Continue / DeepSeek Harness] --> Injection[GoodBuddy 管理的内部 MCP 注入]
Remote[GoodBuddy Agent 远程适用 Runtime] --> Bridge[现有 Agent 通信与工具桥接]
Bridge --> Injection
Injection --> Tool
Tool --> Main[Main 图片服务]
Main --> Profile[现有模型连接与凭据]
Main --> Adapter[现有图片生成与编辑协议]
Main --> Artifact[原会话操作记录与图片成果]
```
Main 持有生成请求、取消句柄和结果保存职责。服务生命周期独立于聊天 Runtime controller，切换或释放 controller 不释放已提交的媒体操作。Renderer 经明确 preload/IPC 方法调用；IPC 使用共享契约校验并保留现有发送方校验。凭据只在 Main 解密，不进入 Skill、工具参数或工具输出。
Main 持有图片请求、取消句柄及结果保存职责，生命周期独立于聊天 Runtime controller。切换或释放聊天进程不释放已提交图片操作。Renderer 的取消等操作经明确 preload/IPC 方法进入 Main，沿用共享契约和发送方校验。凭据只在 Main 解密，不写入工具说明、参数、输出或远程 Runtime 配置。
从 `ModelAgentRuntime` 提取现有图片请求、校验和成果处理中的可复用部分，使直连图片与媒体工具共用协议实现。直连路径保持原有上下文与编辑降级策略；工具路径依据 L-2 传入明确的素材和降级选项，避免协议重用改变产品语义。
`ImageGenerationService` 复用 `ModelAgentRuntime.generateImage` 的图片请求和校验，在 Main 保存操作及成果。工具路径按 L-2 明确区分新建和编辑，不自动将缺少素材或不支持的编辑降为文生图；已有直连图片路径保持原上下文规则。
## Skill 与工具
## 工具与注入
提供一份内置媒体生成 Skill，说明新建、编辑、图生视频、模型选择、素材引用和结果使用。开启模型配置仅更新能力目录，不为每个连接复制 Skill。能力目录与工具从同一份有效配置生成；Skill 中不保存可过期的模型名单或凭据。
稳定图片工具 `generate_image` 同时负责生成和编辑。当前输入为 `prompt`、可选 `modelProfileId`、`intent`（`create` 或 `edit`）、`sourceArtifactIds` 和可选 `quality`；类型及编辑素材约束由 `src/shared/image-generation-contracts.ts` 校验。每次请求沿用已有协议的单图生成和尺寸行为，没有新增数量或尺寸参数。原会话、触发消息和工具调用关联由运行上下文绑定，LLM 不能自由指定结果写入位置或任意文件路径。
拟议工具：`list_media_models` 返回脱敏的可用连接 ID、名称、已支持操作及参数约束；`generate_image`、`generate_video` 提交生成；`get_media_generation` 查询；`cancel_media_generation` 取消。按操作性质接入现有工作模式控制，不因媒体工具增加额外通用审批。
每个新回合提供可调用图片模型的脱敏 ID、名称及生成、编辑能力，模型切换、配置变化或进程复用时刷新。Main 提交前重新校验工作模式、连接开关、所需能力及素材。优先由工具描述承载模型选择、图片引用和结果使用说明，不把 Skill 管理作为依赖。
生成输入包括 `prompt`、可选 `modelProfileId`、显式 `operation`、`sourceArtifactIds` 及协议支持的类型化选项。图片数量、尺寸与质量，以及视频时长、分辨率等按已接入协议校验，不能假定服务商完全兼容。`conversationId`、触发消息及请求身份由运行上下文绑定，不能由 LLM 自由指定目标会话。
直连文本 Model Runtime 使用内置工具契约及分发；外部 Runtime 复用内部 MCP 注入，由 GoodBuddy 自动注册、配置和管理生命周期，远程路径经现有 Agent 工具桥接调用同一服务。内置 MCP 列表中的图片行只展示这项受管能力，不代表直连 Model 也通过 MCP 调用。无需用户创建 Skill、另建 MCP server 或复制凭据，不按模型连接复制工具或 Skill。
提交后返回操作 ID、实际模型和当前状态；完成结果返回成果 ID 与必要文字信息，不把 Base64 或视频字节塞入工具历史。等待有界，长任务通过查询及卡片更新呈现。原回合仍在执行时，可通过其合法工具响应返回最新结果；回合已结束或 Runtime 已切换时，只更新操作记录与原会话卡片，下一回合读取成果摘要，不自动唤起新 LLM 请求。
Main 从已保存图片 profile 的会话调用开关推导允许模型目录，并以目录是否非空推导全部支持 Runtime 的分配。Renderer 只读取派生分配；该受管行不接入通用 MCP 的启停、分配、删除或凭据编辑写入接口。模型配置保存后刷新展示及注入目录，进程复用和下一回合重新读取；运行中的回合及已提交操作继续遵循 L-1、L-3。配置错误、Runtime 在线状态、聊天模型工具能力与执行结果独立于派生分配，不因这些状态移除允许目录中的模型或取消勾选。
不预建能力发现、查询或取消工具目录。只有实际 Runtime 协议要求独立发现、查询或取消交互，且现有工具描述、响应及 UI 操作不能满足时，才增加所需的最小适配，并记录协议依据；这些适配仍调用同一 Main 图片服务，不形成新的媒体平台。取消默认从会话卡片进入 Main。
工具等待遵循现有超时约束，返回操作 ID、实际模型、真实状态及完成后的成果 ID，不把 Base64 塞入工具历史。原回合仍有效时通过合法工具响应返回结果；回合结束或 Runtime 切换后，Main 继续写原会话，下一回合读取操作摘要及成果引用，不补发旧响应、不自动唤起 LLM 或重发图片请求。
## 配置与持久化
| 对象 | 最小拟议数据 | 存储职责 |
| --- | --- | --- |
| 模型连接 | 会话调用开关、适用生成能力 | 复用 settings/profile；现有连接缺少开关时解释为关闭 |
| 全局偏好 | 默认图片、视频 profile ID | 复用应用设置；不复制连接及凭据 |
| 会话选择 | 图片、视频分别为跟随默认或显式 profile ID | 持久化到会话设置，独立于聊天 Runtime selection |
| 生成操作 | ID、原会话/消息 ID、工具调用关联、状态、实际模型 ID 与名称、提示词、有效参数、素材引用、时间、错误、成果 ID | 优先扩展现有会话消息 metadata；实施时评估查询需求后决定是否需要独立表 |
| 上游异步信息 | 必要的上游任务 ID、查询所需非敏感参数 | 仅在协议确实支持异步查询时保存；无凭据副本 |
| 成果 | 媒体内容及类型、原操作与素材关联 | 复用 artifact 体系；不放入 Skill 或 Runtime 内存作为唯一副本 |
| 对象 | 最小数据与职责 |
| --- | --- |
| 图片模型连接 | 复用 settings/profile，增加会话调用开关；现有连接缺少开关时解释为关闭 |
| 图片能力与 Runtime 分配 | 从图片模型配置派生，只读展示；不新增独立可变的 capability enabled、assignment 设置或持久化副本 |
| 全局偏好 | 默认图片 profile ID，复用应用设置；本次指定只属于请求，不新增会话级选择 |
| 生成操作 | 优先使用现有消息 metadata，保存操作 ID、原会话/消息、工具关联、状态、实际模型 ID 与名称、提示词、有效参数、素材引用、时间、错误及成果 ID |
| 素材与成果 | 复用附件和 artifact 持久化，保存上传图片、生成图片及编辑来源关系，不能只存于 Runtime 内存 |
已提交操作在内存持有当次解析的连接参数；持久记录只保留来源与恢复查询所必需的非敏感信息。应用重启后通过原连接核对是否仍可查询，不增加凭据历史、通用恢复日志或多阶段提交机制。不能确认时采用 L-4 的“状态待确认”。
活动请求在 Main 内存持有提交时连接参数，持久记录不复制凭据。应用重启后未完成操作显示结果未确认，不建立跨重启查询恢复、凭据历史、通用恢复日志或自动重试。取消和晚到结果按 L-4 更新同一记录；人工重新生成使用新操作 ID。
操作不自动成为 Task/Job，已有 `runs` 表也不等于通用后台调度已经存在。数据库变更实施前按[迁移规范](../../development/database-migrations.md)评审已发布数据兼容；本次文档不预先引入新表和迁移。
不新增独立任务表、视频字段或通用调度器，操作不自动成为 Task/Job。若实施涉及已发布数据，按[迁移规范](../../development/database-migrations.md)处理实际兼容需求，不预建迁移或恢复机制。
Main 必须在成果持久化成功后发布完成事件，事件按操作 ID 更新而非重复追加。校验素材来自当前会话可访问的附件或成果，继承现有项目、会话隔离，不允许模型填写任意文件路径代替成果引用。
Main 仅在图片和会话引用持久化成功后发布完成事件。素材必须是当前会话可访问的附件或成果，沿用已有项目和会话边界；删除会话后的晚到结果不重建会话。
## 图片与视频结果
## 图片协议
图片继续遵循[图片技术设计](../image-generation/technical-design.md)：校验有界内联图片，不下载 Provider 返回的图片 URL。现有成果内容字符串上限为 5 MiB，这不是原始二进制文件大小，实施时必须正确处理编码开销和超限提示。
视频不沿用内联图片存储。优先复用 `managed_file` 成果和现有文件导出能力，补充媒体类型、播放所需信息及预览。协议选型必须明确提交、查询、取消、结果读取、认证、文件大小上限、超时和过期时间；最终方案用实际服务的证据补入本文。
若视频服务只返回下载地址，需在视频协议设计中明确 Main 端的读取来源、认证、重定向及字节限制后实现，不能借用或放宽图片 URL 禁止规则。生成媒体读取不使用应用更新或模型包下载源设置；受管软件包镜像规则也不适用于动态生成的媒体结果。无法保存或播放的上游结果不能标记为交付完成。
沿用[图片技术设计](../image-generation/technical-design.md)的已有生成、编辑协议及素材限制。接收并校验有界内联图片，不下载 Provider 返回的图片 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 不提交，原会话可查看成果 |
| 直连文本 Model Runtime | 现有内置工具契约及工具分发转入 Main 图片服务 | 自然语言生成、上传图编辑、历史图编辑及切换 |
| 本地 OpenCode | 现有内部 MCP 注入转入同一服务 | 实际工具往返、能力刷新、生成编辑及切换 |
| 本地 Continue | 现有内部 MCP 注入转入同一服务 | 实际工具往返、能力刷新、生成编辑及切换 |
| 本地 DeepSeek Harness | 现有内部 MCP 注入转入同一服务 | 实际工具往返、能力刷新、生成编辑及切换 |
| GoodBuddy Agent 远程适用 Runtime | 复用桌面与 Agent 通信及工具桥接，将请求绑定原会话，由 Main 调用图片模型 | 逐一验证实际支持的远程 Runtime，覆盖真实 Host 工具往返、生成编辑、本地与远程双向切换、断连及成果归属 |
| 无工具能力的聊天模型 | 说明自动调用限制，可使用已有直连图片工作流 | 不解析普通文字伪装工具调用，不新增表单；Ask 不提交 |
Runtime 进程复用时，新的聊天回合仍需刷新能力目录；不假定修改配置必然重启进程。远程桥接是否可直接复用现有工具分发是实施前的验证项，不能由本地成功推断远程支持。远程断连后桌面仍运行时，可继续管理已提交生成；远程 LLM 停止等待不等于媒体取消。
本地 OpenCode、Continue 和 DeepSeek Harness 经内部 MCP gateway 注入；直连 Model 使用内置工具分发。远程通过 `main-image-tool-session.ts`、Agent 协议和 `image-tool-mcp.ts` 回到同一 Main 服务。现有 GoodBuddy Agent 的受管远程 Runtime 为 OpenCode，项目校验和 Runtime 创建均沿用此范围；共享契约包含其他 Runtime 不表示存在其远程执行路径。保留会话在目录清空时也刷新 MCP，Continue 准备失败时释放本次分配的令牌。工具发现成功或 Skill 注入成功不能代替真实生成与编辑。
## 实施顺序与验证
Main 已接收的请求在桌面仍运行时独立于远程连接继续；未确认是否接收的请求不自动重放。聊天回合停止等待与用户取消图片是不同动作，须验证现有取消传播不会误杀 Main 图片请求。
1. 首期：实现图片调用开关、全局默认及本次指定，提取图片服务并接通直连文本 `generate_image`。完成文生图、已有协议编辑、成果保存、取消及模型切换后的结果交付。
2. 后续按实际需求接通其余本地 Runtime 与远程工具路径，分别验证真实调用及切换。
3. 后续评估会话级选择、独立生成入口及恢复能力，确认需要后再增加界面和数据。
4. 视频单独选型与验收，实际接通服务后再增加视频工具、异步查询和播放能力。
## 实施与验证
首期以图片真实产品路径验收，完成后标记“图片首期完成”，后续能力单独记录。针对首期适用的 L-1 至 L-5 编写选择优先级、配置失效、会话隔离、重复结果、取消及晚到结果测试。验证原直连图片行为不回归，检查进程切换不会重复提交。
实施工作包括配置与选择、Main 图片服务提取、各本地及远程 Runtime 工具适配、成果与状态 UI。它们共同完成本图片功能，不按 Runtime 划分交付范围。
源代码实现后运行 `npm test`、`npm run typecheck`、`npm run lint`。首期真实生成从直连文本聊天输入进入，覆盖[用户场景](./user-stories.md)中的首期验收；记录实际请求数量、模型、Runtime 和结果。后续显式入口需独立验证。涉及 Agent 的变更按[远程主机验证要求](../remote-host/technical-design.md)在真实测试 Host 验证。当前仅写文档，不发起收费生成调用。
针对 L-1 至 L-5 验证选择优先级、失效配置、上传与历史素材、无视觉模型、Ask、会话归属、重复通知、取消及晚到结果。检查切换聊天模型、图片默认模型、本地与远程 Runtime 后的新生成和编辑，以及旧操作不重复提交。回归已有直连图片工作流。
按 US-16 至 US-19 验证从零到一个开启模型、多个中关闭或删除一个、最后一个关闭或删除、重新开启，以及配置错误和 Runtime 离线时的派生分配、目录刷新、行可见性与只读交互。重开设置和应用后均从模型配置推导，不恢复独立分配值；辅助技术可读取标签、勾选状态和说明，键盘可到达模型设置导航。
源代码实现后运行 `npm test`、`npm run typecheck`、`npm run lint`，并逐路径执行[用户场景](./user-stories.md)的真实产品验收，记录模型、Runtime、请求数量和结果。涉及 Agent 的实现按[远程主机验证要求](../remote-host/technical-design.md)在真实测试 Host 验证。实施和集成验证状态由[进度记录](./progress.md)维护。
docs/features/conversation-media-generation/ui-design.md
+23 -24
View File
@@ -1,42 +1,41 @@
# 界面设计
状态：设计草案。遵循[统一界面设计](../../../UI-DESIGN.md)，实现 [FR-1 至 FR-9](./prd.md)，行为以[行为规则](./logic-design.md)为准。
## 首期界面
首期只在图片模型配置提供会话调用开关和“设为默认生图模型”，沿用下文共享控件规范。关闭或删除默认模型后保留失效选择并提示改选，不自动改用其他模型。
会话以自然语言发起生图，本次指定模型也通过请求表达。不新增会话级模型选择器、独立生成表单或视频入口。未设默认时，助手提示用户本次指定一个可用模型，或到设置中选择默认后重新发送请求；名称有歧义时先澄清。
复用图片成果展示与引用入口，显示实际模型、进行状态、结果或错误，并支持取消和人工重新生成。首期不增加视频播放和独立“重试保存”按钮。不支持工具调用或 Runtime 未接通时说明限制，提示可切换到支持的聊天路径或使用已有直连图片工作流；Ask 下说明生成需要 Execute，不自动切换模式。
以下为完整目标的界面设计，按[产品需求的阶段划分](./prd.md)实施；首期不预留后续控件。
状态：工作区已有实现及 Electron 组件验收，完整应用验收见[进度记录](./progress.md)。遵循[统一界面设计](../../../UI-DESIGN.md)，实现 [FR-1 至 FR-9](./prd.md)，行为以[行为规则](./logic-design.md)为准。
## 模型配置
在现有模型连接表单中，按已支持的生成能力显示持久开关：
在现有图片模型连接表单提供“允许 AI 在会话中调用”。说明文字：“开启后，支持工具调用的聊天助手可使用此模型生成和编辑图片，编辑能力取决于图片协议。结果保存在发起请求的会话中。”复用共享 Switch，提供 `role="switch"`、键盘操作及可见焦点。
- 图片模型：“允许 AI 在会话中调用此模型生成图片”。
- 视频模型：“允许 AI 在会话中调用此模型生成视频”。
开启后提供“设为默认生图模型”，列表显示可调用和默认标识。关闭或删除默认连接时提示默认选择不可用，保留失效选择供改选，不自动指定其他模型。用户无需创建 Skill、搭建 MCP server 或重复填写 API 凭据；内部注入由 GoodBuddy 管理，不作为配置步骤展示。
说明文字：“开启后，支持工具调用的聊天助手可使用此模型。生成结果保存在发起请求的会话中。”开关复用共享 Switch，并提供 `role="switch"`、键盘操作及可见焦点。不要求用户维护 Skill 文件或填写第二套 API 凭据。
## 能力与 Runtime 分配
开启后提供“设为默认生图模型”或“设为默认视频模型”操作。列表在对应模型旁显示“可在会话中调用”和默认标识。关闭、删除默认连接时提示会话选择将不可用，保留原选择供改选，不自动指定其他模型。
复用设置中心“MCP / 内置 MCP”的列表与分配布局，增加“图片生成与编辑”行，标记“内置 · 自动管理”。这是 GoodBuddy 管理能力的展示入口，直连 Model 通过内部工具调用，外部 Runtime 通过内部 MCP 接入；不显示为用户另行添加的 MCP 或 Skill，也不混入 Runtime 原生能力清单。
该行按 L-1 展示直连文本 Model Runtime、本地 OpenCode、Continue、DeepSeek Harness 及 GoodBuddy Agent 远程适用 Runtime 的只读分配复选框。此图片能力采用用户已接受的自动管理规则，不沿用其他内置 MCP 的手动启停、可调分配或 DeepSeek Harness“暂不支持”状态。没有开启模型时仍保留整行及全部未勾选项，不能因目录为空隐藏。
持续显示说明“由图片模型的「允许 AI 在会话中调用」设置自动管理。”，并提供“前往图片模型设置”导航。该行不提供独立启用开关、保存分配、移除、编辑连接或凭据入口。运行就绪、无工具能力、配置或调用错误单独显示，不改变分配勾选。
分配复用共享 Checkbox 的方形视觉和原生语义，以 `checked` 表示派生值并使用 `disabled` 禁止鼠标、标签点击或键盘切换；仅在共享控件已有受支持的只读实现时采用该实现，不给原生 Checkbox 添加无效的 `readonly` 或自行添加 `aria-readonly`。每项保留 Runtime 标签和可访问名称，以 `aria-describedby` 关联自动管理说明。说明放在禁用控件之外，保持可读及辅助技术可访问；导航保持正常 Tab 顺序和可见焦点。窄窗口下分配项换行，保留标签、勾选状态、说明和导航。
## 会话入口
在现有输入区工具菜单提供“生成图片”“生成视频”，以及对应模型选择。默认项写成“跟随全局设置（模型名称）”；没有默认值则显示“选择生成模型”。选择只影响当前会话，设为全局默认必须使用独立操作。
在现有聊天输入区以自然语言发起图片生成或编辑，本次指定模型也通过请求表达。复用上传附件和历史成果引用入口，输入区显示素材缩略图或文件名并允许移除。不新增会话级图片模型选择器、独立生成表单或视频入口。
自然语言调用与显式入口共用成果卡片。显式入口提供提示词和参考素材选择，按所选模型展示适用参数，不呈现供应商请求字段。输入区显示已引用的素材缩略图或文件名，可移除。
未设默认时，助手提示本次指定可用模型，或到设置选择默认后重新发送；名称歧义先澄清。没有图片连接时提供现有模型设置入口。模型不支持编辑或素材缺失时保留输入，提示更换模型或重新选择素材。
不支持工具调用时提示“当前聊天模型无法自动调用，可使用生成入口”。Ask 下提示“生成图片或视频需要 Execute 模式”，由用户切换工作模式；不能自动切换。未配置生成模型时给出“添加生成模型”入口。
直连文本、本地各 Runtime 和 GoodBuddy Agent 远程适用 Runtime 使用一致的图片操作与成果反馈。切换后可继续生成及编辑历史图；工具调用异常时显示具体原因，不宣称已提交。接入未完成的开发状态记录在进度文档，不能作为产品支持范围。
## 生成卡片
不支持工具调用时提示“当前聊天模型无法自动调用图片工具，可使用已有直连图片工作流”。Ask 下提示“生成或编辑图片需要 Execute 模式”，由用户切换，不自动切换。无视觉能力时说明无法直接查看图片，不妨碍按用户文字调用编辑工具。
卡片就近显示媒体类型、实际模型、当前阶段、成果或错误。参数、提示词和来源素材放在可展开详情中；不显示密钥、认证头或供应商私有下载地址。运行活动使用同一操作标识，与卡片关联。
## 图片卡片
图片完成后可预览、下载和“继续修改”；存在可用图生视频能力时提供“生成视频”。视频完成后提供带原生播放控制的预览及下载，不自动播放。点击继续修改会把成果加入输入区，用户填写本次修改要求。
复用现有图片成果展示，卡片就近显示实际模型、操作状态、成果或错误。提示词、适用参数和来源素材放在详情中；不显示密钥、认证头或供应商私有地址。活动记录与卡片使用同一操作标识。
进行中显示“取消生成”，取消结果按行为规则展示。失败显示有针对性的“重试”“重新选择模型”“重新选择素材”或“重试保存”。卡片错误不重复弹出全局错误通知；模型设置保存等非上下文反馈使用应用通知。
完成后可预览、下载和“继续修改”。继续修改将成果加入输入区，用户填写修改要求；切换 Runtime 或重开会话后仍可使用。离开会话不取消操作，结果只出现在原会话。
窄窗口中操作允许换行，媒体宽度不超过消息区；模型长名称可截断并提供完整可访问名称。状态使用文字表达，不能只依靠颜色；阶段变化通过适度的 `aria-live` 提示，避免等待时间逐秒播报。弹出选择器关闭后焦点回到触发控件。
进行中提供“取消生成”，与“停止回复”分开。取消、晚到结果和结果未确认的文案遵循 L-4。失败提供适用的“重新生成”“重新选择模型”或“重新选择素材”；重新生成由用户明确触发，并说明会发起新的模型请求。没有独立“重试保存”按钮。
“重新选择模型”进入已有模型连接设置；改变模型后，用户在新请求中明确指定。“重新选择素材”聚焦输入区并打开已有附件选择器，保留草稿和已有附件；空草稿填入原提示词及模型名称。历史成果仍使用“继续修改”加入引用并聚焦输入区。上述操作不自动发送请求，“重新生成”继续使用原操作的模型和输入。
卡片错误不重复弹全局通知；模型设置保存等非上下文反馈使用应用通知。状态使用文字，不能只靠颜色；状态变化通过适度的 `aria-live` 提示，避免逐秒播报等待时间。窄窗口操作可换行，图片不超过消息区宽度，模型长名称截断时保留完整可访问名称。复用的菜单关闭后焦点回到触发控件。
docs/features/conversation-media-generation/user-stories.md
+27 -32
View File
@@ -1,39 +1,34 @@
# 用户场景
状态：设计草案。表中 Given、When、Then 分别为前提、操作和预期结果。
状态：设计草案。Given、When、Then 分别为前提、操作和预期结果。范围以[产品需求](./prd.md)为准，行为以[行为规则](./logic-design.md)为准。
## 首期验收
## 场景验收
原 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 远程自动调用，以及下表中超出上述范围的预期，留到后续验收。
## 完整目标场景
适用的自动调用场景须在直连文本 Model Runtime、本地 OpenCode、Continue、DeepSeek Harness 和 GoodBuddy Agent 远程适用 Runtime 分别验证，前提为 Execute 且聊天模型支持工具调用。切换验收同时检查原操作归属和目标 Runtime 的新生成、编辑能力。
| 编号 | 需求 | 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 | 同一会话有多张成果 | 要求“修改第二张”或“新画一张无关图片” | 前者引用指定成果，后者不自动附带上一张图；指代不清时先澄清 |
| US-01 | FR-1、FR-3、FR-9 | 已添加图片模型、开启会话调用并设为默认 | 在文字会话中要求画海报 | 自动调用并显示活动，原会话出现图片及实际模型；无需创建 Skill、MCP server 或重复凭据 |
| US-02 | FR-2 | 有两个可调用图片模型，未选默认 | 请求生成图片 | 提示本次指定模型或到设置选择默认后重新发送；名称歧义先澄清，不按列表顺序提交 |
| US-03 | FR-4、FR-5 | 聊天模型 A 已调用图片模型生成图片 | 切换聊天模型 B，要求修改该图 | B 获得成果引用和可用工具，编辑模型按规则选择 |
| US-04 | FR-4、FR-6、FR-9 | 生成操作已提交 | 切换 Runtime 并打开其他会话，再请求生成或编辑 | 原操作继续且只写回原会话；目标 Runtime 可提交新操作，不重放旧调用 |
| US-05 | FR-2、FR-4 | 当前操作使用图片模型 X | 将全局默认改为 Y，再请求新建图片 | 旧操作仍用 X，新操作用 Y；本次明确指定可覆盖默认 |
| US-06 | FR-1、FR-2、FR-4 | 默认或本次指定模型为 X | X 被关闭或删除后请求生成 | 显示 X 不可用并提示改选，历史图仍可打开，不静默换模型 |
| US-07 | FR-5、FR-8 | 已保存图片并重新打开会话或切换 Runtime | 引用原图，指定另一个支持编辑的模型 | 新模型接收原图；素材缺失时要求重新选择，不能假装已编辑 |
| US-08 | FR-7 | 当前聊天模型不支持工具调用，或处于 Ask | 请求生成或编辑 | 无工具能力时说明可使用已有直连图片工作流；Ask 下不提交并提示需要 Execute，不自动切换模式 |
| US-09 | FR-6 | 操作正在生成或保存，或已经失败 | 取消，或明确要求重新生成 | 如实显示取消结果；人工重新生成创建新操作，不自动重复收费请求，不提供独立保存重试入口 |
| US-11 | FR-4、FR-9 | 使用 GoodBuddy Agent 远程适用 Runtime | 生成及编辑图片，切换本地后继续编辑，再切回远程生成 | 工具往返可用，成果可继续引用；活动归原会话，凭据留在 Main；远程断连不取消 Main 已接收的操作 |
| US-12 | FR-5、FR-7、FR-8 | 聊天模型无视觉能力但支持工具 | 请求分析图片或根据文字修改图片 | 说明无法直接查看图片；可传原图给编辑工具，不编造视觉观察 |
| US-13 | FR-6 | 图片操作尚未取得可保存结果 | 退出并重开应用 | 未完成记录显示结果未确认，不承诺后台继续，不自动查询恢复或重新提交 |
| US-14 | FR-5 | 会话有多张图片 | 要求“修改第二张”或“新画一张无关图片” | 前者引用指定成果，后者不附带旧图；指代不清先澄清 |
| US-15 | FR-3、FR-5、FR-9 | 上传图片并选择支持编辑的图片模型 | 要求修改背景，再切换 Runtime 继续修改成果 | 上传原图及后续成果被正确引用，编辑结果保存在各自发起会话；不降为纯文生图 |
| US-16 | FR-1、FR-9 | 尚无开启会话调用的图片模型 | 查看内置 MCP 列表，再开启一个图片模型并保存 | 图片生成与编辑行一直可见且标记“内置 · 自动管理”；全部支持 Runtime 从未勾选变为勾选，目录包含该模型；重开设置或应用仍按模型配置显示 |
| US-17 | FR-1、FR-9 | 至少两个图片模型开启会话调用 | 关闭或删除其中一个并保存 | 全部支持 Runtime 保持勾选，允许目录移除该模型、保留其他开启模型；新操作不能调用已关闭或删除模型 |
| US-18 | FR-1、FR-9 | 仅剩一个开启会话调用的图片模型 | 关闭或删除该模型，再重新开启或添加并开启一个模型 | 目录为空时全部取消勾选，整行和说明、模型设置导航仍可见；再次开启后自动恢复全部勾选，无需另行分配 |
| US-19 | FR-1、FR-7、FR-9 | 至少一个图片模型开启会话调用 | 尝试用鼠标或键盘切换分配，或切换到无工具聊天模型、Ask、离线 Runtime，或遇到配置或执行错误 | 分配不可手动修改，运行限制与错误不取消勾选；无独立启用、分配保存、移除或凭据编辑操作；自动管理说明持续可读，辅助技术可识别勾选和禁用状态，键盘可通过“前往图片模型设置”导航修改源配置 |
## 编号变更
US-10（图生视频）移出本图片设计范围，编号保留，不安排实施。US-02、US-05、US-06 的会话选择预期由全局默认和本次指定替代；US-08 使用已有直连图片工作流；US-09 取消独立保存重试要求；US-13 的视频查询恢复由图片中断状态说明替代。其余编号保持，US-15 补充上传图片编辑的显式验收。
US-16 至 US-19 补充自动管理分配验收，设置展示不依赖 Execute 或当前聊天模型支持工具；自动生成与编辑仍遵循本节的调用前提。