feat: preview Agent HTML in conversations and unblock long replies

Agent replies that produced HTML could only be read as source, so users had to copy the markup into an external file to see the result. Completed Agent and Subagent output now renders complete HTML documents, single-root HTML replies, and `html` / `htm` code blocks as an isolated static preview in place. Each preview keeps a persistent notice that scripts and network are disabled and offers the same icon actions as Mermaid diagrams: a source toggle and a full-screen preview. The new "render HTML in conversations" switch under Platform Features / General is on by default, applies to the open conversation immediately, and falls back to HTML source when disabled. Previews cannot run scripts, reach the network, submit forms, open windows, or load remote media; author stylesheets and inline styles are preserved so the intended layout survives, and remote resource loading is refused by the preview CSP instead. Direct-model replies no longer fail once they grow large. The byte caps on streaming responses, single stream blocks, non-streaming replies, model tool arguments, tool request context, aggregate tool results, and accumulated answer text are removed, so users stop seeing "模型接口流式响应超过安全限制" on long answers. Response length is now governed by the request timeout, cancellation, and context compression. Image generation responses keep their decodable-image validation. A message sent after a failed or interrupted run stayed in the pending queue instead of running. The conversation is now released whenever a run reaches any terminal state, not only when the renderer reports readiness again, and a dispatched queue item whose run never starts releases its reservation and returns to pending. Later messages dispatch without extra user action. Release note: Agent 回复中的 HTML 现在可直接在会话内预览，支持查看源码和全屏预览，默认开启并可在“平台功能 / 通用设置”关闭；直连模型的长回复不再因大小限制中断；上一次运行失败或被中断后，新发送的消息会立即执行而不再排队等待。
2026-09-05 09:10:44 +08:00
parent 9588c4b901
commit a4b64a1641
35 changed files with 1669 additions and 195 deletions
@@ -0,0 +1,29 @@
+# 会话 HTML 渲染
+
+会话 HTML 渲染让用户直接查看 Agent 回复中的网页结果，而不必先复制代码到外部文件。
+该能力默认开启，也可以在“设置 > 平台功能 > 通用设置”中关闭。
+
+## 功能边界
+
+- 只渲染已完成的 Agent 正文和已完成的子 Agent 输出。
+- 支持完整 HTML 文档、单一 HTML 根元素，以及 Markdown 中的 `html` / `htm` 代码块。
+- 使用无脚本、无网络、无表单提交和无窗口操作权限的静态隔离预览。
+- 每个预览提供源码切换和全屏预览两个图标操作；全屏预览沿用同一清理和隔离边界。
+- 用户消息、推理过程和流式中的回复不执行 HTML；关闭功能后继续显示 HTML 源码。
+- 本功能不把普通聊天回复复制为成果，也不替代助手工作栏中独立成果的预览流程。
+
+## 文档
+
+- [产品需求](./prd.md)：功能范围、状态规则和验收标准。
+- [技术设计](./technical-design.md)：设置持久化、渲染边界与静态隔离方案。
+- [实现进度](./progress.md)：已验证实现和验证记录。
+
+## 术语
+
+- **HTML 源码**：Agent 回复中原始、可复制的 HTML 文本。
+- **静态预览**：在隔离 `iframe` 中显示的 HTML；脚本、联网和外部操作均被禁用。
+- **全屏预览**：在应用级 Modal 中显示同一份静态预览文档，用于查看完整页面布局。
+
+全局聊天和设置界面规则由根目录的
+[统一界面设计系统](../../../UI-DESIGN.md)定义。独立成果预览仍由
+[助手工作栏](../assistant-workbar/README.md)负责。
@@ -0,0 +1,69 @@
+# 会话 HTML 渲染产品需求
+
+## 用户问题
+
+Agent 可以生成网页、报告和交互原型的 HTML，但此前会话只能显示源码或忽略原始标签。
+用户必须把内容复制到外部文件后才能查看结果，打断了会话内的阅读和迭代流程。
+
+## 目标
+
+- 让 Agent 生成的 HTML 在回复完成后直接显示为网页预览。
+- 保留一键查看原始 HTML 的能力。
+- 允许用户通过平台功能开关恢复为只看源码。
+- 预览不取得 GoodBuddy Renderer 或外部网络能力。
+
+## 非目标
+
+- 不执行 Agent 提供的 JavaScript。
+- 不提供联网网页、表单、弹窗或 Electron `webview`。
+- 不在流式输出中反复加载不完整页面。
+- 不自动把普通会话回复保存为成果。
+
+## 功能需求
+
+### FR-1 默认设置
+
+“会话 HTML 渲染”是应用级持久设置，默认开启。用户可在“设置 > 平台功能 >
+通用设置”中立即关闭或重新开启；保存失败时保留最后确认的状态并显示错误。
+
+### FR-2 可识别输出
+
+开启后，已完成 Agent 回复中的以下内容显示为静态预览：
+
+1. 完整 HTML 文档。
+2. 由单一 HTML 根元素构成的完整回复。
+3. Markdown 中标记为 `html` 或 `htm` 的代码块。
+
+普通 Markdown 继续按原有规则显示。一个回复中的多个 HTML 代码块各自保持原有位置。
+
+### FR-3 回复状态和角色
+
+- 已完成的主 Agent 正文和已完成的子 Agent 输出可以预览 HTML。
+- 用户消息和 Agent 推理只显示文本或源码。
+- 流式 Agent 正文在完成前显示源码，完成后原位切换为预览。
+
+### FR-4 源码、全屏与关闭行为
+
+每个预览持续显示“静态安全预览，脚本和网络已禁用”，并在标题右侧提供两个图标操作：
+
+1. 源码按钮，就地展开或收起原始 HTML。
+2. 全屏按钮，在应用级 Modal 中查看同一份预览文档。
+
+嵌入预览使用固定高度并在框内滚动，需要更大画面时使用全屏预览。全屏预览可通过关闭
+按钮、Escape 或点击遮罩退出，退出后焦点回到全屏按钮。关闭平台功能后，完整 HTML 回复
+和 HTML 代码块继续显示源码，不能变成空白。
+
+### FR-5 静态隔离
+
+预览必须禁用脚本、网络请求、表单提交、嵌套页面、插件对象和窗口操作。远程链接和远程
+媒体不得从预览加载；内联样式和有界的内联位图可用于还原静态视觉。
+
+## 产品验收
+
+- 新安装和从旧设置升级后，开关均为开启。
+- 完整 HTML 和 fenced HTML 在已完成的 Agent 回复中显示预览。
+- 关闭开关后，当前会话立即恢复显示源码，重启后选择仍保留。
+- 流式回复、推理和用户消息从不执行 HTML。
+- 预览可通过键盘访问源码和全屏按钮，并具有明确的 iframe 标题。
+- 全屏预览隔离背景、初始聚焦关闭按钮，Escape 退出后焦点回到全屏按钮。
+- 恶意脚本、事件属性、远程资源、表单和嵌套 frame 不进入可执行预览。
@@ -0,0 +1,39 @@
+# 会话 HTML 渲染实现进度
+
+## 已实现
+
+- [x] 应用级持久开关，默认开启，并提供旧设置迁移。
+- [x] 平台功能通用设置中的共享 Switch。
+- [x] 已完成 Agent 回复和子 Agent 输出中的完整 HTML 与 fenced HTML 识别。
+- [x] 隔离静态预览、持续安全说明和源码切换。
+- [x] 预览保留作者 `<style>` 与 `style` 属性，样式不再被整块丢弃。
+- [x] 与 Mermaid 一致的图标按钮组：源码切换与全屏预览 Modal。
+- [x] 嵌入预览固定 480px 高度，源码面板同值上限。
+- [x] 用户消息、推理、流式回复和关闭状态的源码边界。
+- [x] 设置变更后当前会话立即重新渲染。
+
+## 验证记录
+
+2026-09-05：
+
+- `npm run typecheck`：通过。
+- 聚焦测试（应用设置、Markdown、会话时间线、设置中心、App 集成）：306 项通过。
+- 全量 `npm test`：`3493 passed, 55 skipped`。
+- `npm run lint`：通过。
+- `npm run build`：Main、Preload、Renderer 与控制面安装器均成功构建。
+
+修复样式丢失后复验：
+
+- 原实现只要 `<style>` 或 `style` 属性中出现 `@import` / `url()` 就整块删除，带渐变或
+  背景图的回复因此完全失去样式；现改为保留作者样式，外部资源加载仍由 iframe CSP 拒绝。
+- `npx vitest run src/renderer/src/MarkdownRenderer.test.tsx`：`19 passed`。
+- 聚焦测试（会话时间线、App 集成、设置中心）：`260 passed`。
+- `npm run typecheck`、`npm run lint`：通过。
+
+新增全屏预览与图标化源码按钮后复验：
+
+- 源码按钮改为代码图标并暴露 `aria-expanded`；新增放大图标打开全屏 Modal。
+- 嵌入预览高度由 `min-height: 320px` 改为固定 `height: 480px`，源码面板上限同步为 480px。
+- 新增回归测试覆盖全屏 Modal 的初始焦点、背景 inert、Sandbox/CSP 与 Escape 焦点恢复。
+- 聚焦测试（Markdown、会话时间线、App 集成、设置中心）：`280 passed`。
+- `npm run typecheck`、`npm run lint`：通过。
@@ -0,0 +1,68 @@
+# 会话 HTML 渲染技术设计
+
+## 进程和设置边界
+
+`conversationHtmlRenderingEnabled` 属于现有 `ApplicationSettings`。Main 继续通过
+版本化 JSON 文件持久化应用设置，IPC 继续复用已验证的
+`settings:application:get/update` 通道，Preload 只暴露类型化设置方法。
+
+应用设置格式升级到版本 11。版本 10 及更早设置在读取时补入默认值 `true`，无需保留第二份
+状态或独立迁移文件。
+
+## Renderer 数据流
+
+1. `App` 启动时读取应用设置，并把当前值传给每个保活的会话视图。
+2. 平台功能 Switch 保存成功后立即更新 `App` 状态。
+3. `ChatTimeline` 只为 `role === "assistant"` 且 `state === "complete"` 的正文传入
+   HTML 渲染权限；推理始终不传入该权限。
+4. `MarkdownRenderer` 识别完整 HTML 回复以及 `html` / `htm` fenced code。
+5. 关闭权限或回复仍在流式阶段时，HTML 保持代码文本。
+
+## 静态预览
+
+`StaticHtmlPreview` 不使用 `dangerouslySetInnerHTML`。它先用 DOMPurify 清理文档，再通过
+`DOMParser` 移除事件属性、非锚点 `href` 和非内联图片的 `src` / `poster`，最后把结果写入
+`<iframe sandbox="" srcDoc>`。
+
+作者样式必须保留：`<style>` 元素和 `style` 属性原样传入预览，不按 `@import` 或 `url()`
+关键字整块删除，否则任何带渐变或背景图的回复都会退化成无样式文档。外部样式表和远程
+字体、图片的实际加载由 iframe 文档的 CSP 拒绝，不需要在清理阶段重复拦截。
+
+iframe 文档注入严格 CSP：
+
+- `default-src 'none'`
+- `script-src 'none'`
+- `connect-src 'none'`
+- `frame-src 'none'`
+- `object-src 'none'`
+- `form-action 'none'`
+- 只允许内联样式以及 `data:` 字体和受支持的内联位图
+
+同时设置 `referrerPolicy="no-referrer"`。Sandbox 不授予 scripts、forms、popups、
+same-origin 或 navigation 权限。预览只在回复完成后创建，并使用 lazy loading。
+
+## UI 与无障碍
+
+预览沿用聊天阅读宽度、语义颜色和共享 `icon-button`。`figure` / `figcaption` 表达预览及其
+说明，iframe 具有本地化标题。标题右侧是一个 `role="group"` 图标按钮组，与 Mermaid 图表
+操作保持一致：源码按钮暴露 `aria-expanded` 与 `aria-controls`，全屏按钮打开 Modal。
+
+嵌入预览高度固定为 480px，超出部分在框内滚动；查看源码面板使用同一数值作为最大高度。
+iframe 无法按内容自适应高度，因为 `sandbox=""` 不含 `allow-same-origin` 或 `allow-scripts`，
+主文档既读不到内部文档尺寸，也不能接收上报；全屏预览覆盖需要更多空间的场景。
+
+全屏预览复用 `dialog-focus` 的 `activateModalFocus` 与 `trapTabFocus`，遵循统一 Modal 的
+背景 inert、初始焦点落在关闭按钮、Tab 循环、Escape 关闭和关闭后焦点恢复。它渲染的是与
+嵌入预览完全相同的清理后文档，不额外放宽 Sandbox 或 CSP。切换回复时，源码面板与全屏
+预览按当前 source 派生开合状态，不使用会引发级联渲染的重置 effect。
+
+## 验证范围
+
+- 应用设置默认值、关闭持久化和版本 10 迁移。
+- fenced HTML、完整 HTML、关闭后的源码回退。
+- 作者 `<style>` 与 `style` 属性在预览中保留。
+- 脚本、远程资源、表单和事件属性清理，以及 iframe Sandbox/CSP。
+- 源码按钮的 `aria-expanded` 切换，以及全屏预览的初始焦点、背景 inert、Escape 关闭和
+  焦点恢复。
+- 主 Agent、子 Agent、用户、推理和流式状态边界。
+- 从设置 Switch 到当前会话重新渲染的应用级集成路径。
@@ -6,8 +6,8 @@
 | --- | --- |
 | 文档类型 | 功能进度 |
 | 状态 | 已实施，本机验收完成 |
-| 版本 | 0.3 |
-| 日期 | 2026-09-03 |
+| 版本 | 0.4 |
+| 日期 | 2026-09-05 |
 | 关联入口 | [直连模型 Agent 能力](./README.md) |

 ## 当前结论
@@ -126,6 +126,18 @@
 - `npm run build`：Main、Preload、Renderer 和控制面安装器均成功构建。2026-09-02 按产品
  决策移除未对应实际性能问题的 Renderer bundle 基线门禁后复验通过。

+## 2026-09-05 移除直连模型响应字节上限
+
+- 直连模型不再对流式响应总量、单个流式块、非流式回复、模型工具参数、工具请求上下文、
+  聚合工具结果和累计回答长度设置字节上限；长回复和大工具结果由请求超时、取消和上下文
+  压缩控制。用户不再看到“模型接口流式响应超过安全限制”。
+- 图像生成响应仍按可解码图片大小校验，Provider 错误响应仍读取有界文本。
+- 回归测试改为验证超过旧上限的长流式回复可以完整返回，以及超过 1 MB 的图片工具结果会
+  进入下一轮模型请求。
+- `npx vitest run src/main/agent/model-runtime.test.ts`：`74 passed, 1 skipped`。
+- 全量 `npm test`：`3493 passed, 55 skipped`。
+- `npm run typecheck`、`npm run lint` 和 `npm run build`：通过。
+
 ## 进度维护要求

 - 只有真实生产路径完成并验证后才能勾选实施项。
@@ -327,11 +327,15 @@ type SubagentActor =

 不要用宽泛 catch 抹掉取消、超时、Provider HTTP 状态或进程退出上下文。

-模型请求重试由 `ModelAgentRuntime` 的统一流式请求边界处理，覆盖普通问答、工具轮次和复用
+模型请求重试由 `ModelAgentRuntime` 的统一流式请求处理，覆盖普通问答、工具轮次和复用
 同一 Runtime 的上下文摘要。重试分类检查错误及有界 `cause` 链中的 Node/Undici 网络错误
 码；每次尝试创建独立超时信号。退避等待监听父请求取消。只有完整模型轮次返回后才执行
 工具，因此未产生可见文本或推理内容的重试不会重复执行工具。

+模型回复本身不设固定字节上限：流式响应、非流式回复、模型工具参数、请求上下文和工具
+结果总量都由请求超时、取消和上下文压缩控制，长回复和大工具结果不会被中断。图像生成
+响应仍按可解码图片大小校验。
+
 ## 11. 性能

 - Shell 探测按执行服务实例缓存，不在每轮模型调用重复探测。
@@ -231,8 +231,10 @@ type TimeTrigger =

 同一 Conversation 的普通消息和 Scheduled Task occurrence 使用同一 FIFO 队列。Agent
 正在回复时，到期 occurrence 只显示为待执行，不中断当前输出；当前执行结束后才认领下一项。
-用户显式选择“立即中断并插入”时，系统取消当前 Conversation 的活动请求，并让所选项成为
-下一项。删除待执行 occurrence 只取消该次运行，不删除稳定 Task、Conversation 或历史结果。
+执行以失败、取消或中断结束时同样立即释放该 Conversation，下一项无需用户再次操作即会
+执行。用户显式选择“立即中断并插入”时，系统取消当前 Conversation 的活动请求，并让所选项
+成为下一项。删除待执行 occurrence 只取消该次运行，不删除稳定 Task、Conversation 或历史
+结果。

 ## 8. 一次触发的对象关系

@@ -365,6 +367,8 @@ Task Center 显示 Scheduled Task 的范围、关联 Conversation、状态、模
 - [x] 当前回复期间可以继续发送普通消息，并在 Composer 上沿查看、删除或提升待发送项。
 - [x] 应用重启恢复尚未执行的队列项和有界附件上下文；已写入 Conversation 的用户输入
  通过队列项身份完成恢复对账，不会再次进入待发送队列。
+- [x] 执行失败、取消或中断后立即释放会话，下一项和随后发送的新消息无需用户额外操作
+  即会执行。
 - [x] 文本结果只写入 Conversation，独立交付物才进入成果。
 - [ ] Task Center 和桌面通知可以打开正确 Conversation 并定位 Task。
 - [ ] 应用重启不自动重放结果未知的副作用。