206 lines
9.0 KiB
Markdown
206 lines
9.0 KiB
Markdown
# Ygent 富内容渲染设计（HTML 制品 / 流程图 / 公式）
|
||
|
||
> 状态：设计提案，待确认
|
||
> 背景：`docs/reference/workbuddy/chat-tool-fold.md` 已摸清 WorkBuddy 的实现与安全边界
|
||
> 本文只讨论「对话区要支持哪些内容类型、怎么安全地渲染、分几步做」
|
||
|
||
---
|
||
|
||
## 1. 现状盘点
|
||
|
||
| 内容类型 | WorkBuddy | Ygent 现状 | 差距 |
|
||
|---|---|---|---|
|
||
| 段落 / 列表 / 引用 | ✓ | ✓（remark-gfm） | — |
|
||
| 表格 | ✓ | ✓ | — |
|
||
| 代码块高亮 | ✓ Prism | ✓ highlight.js | 可接受 |
|
||
| 代码 diff（改文件时） | ✓ `tool-diff` | ✗ | 见 §7 |
|
||
| 图片 | ✓ | ✓（react-markdown 默认） | — |
|
||
| **流程图 / 图表** | ✓ mermaid | **✗** | 需新增 |
|
||
| **数学公式** | ✓ KaTeX | **✗** | 需新增 |
|
||
| **HTML 制品** | ✓ sandbox iframe | **✗** | 需新增 |
|
||
| 内联 SVG（消毒） | ✓ DOMPurify | ✗ | 低优先 |
|
||
|
||
Ygent 当前渲染管线：`remarkGfm` + `rehypeHighlight`，**无 `rehype-raw`**（即不渲染 Markdown 里的裸 HTML）——这一点与 WorkBuddy 一致，是安全基线，**不要为了省事打开它**。
|
||
|
||
---
|
||
|
||
## 2. 两条进入路径（关键决策）
|
||
|
||
富内容有两种进入对话的方式，**建议两条都做，但优先级不同**：
|
||
|
||
### 路径 A：Markdown 内联（模型天然会用）
|
||
|
||
模型输出 ```mermaid 代码块或 `$$…$$` 公式，由渲染管线识别。
|
||
|
||
- 优点：**零工具改动**。模型不需要被教会调用新工具，它在别处已经习惯了这套写法。
|
||
- 证据：WorkBuddy 的 mermaid 就是这条路径——存在 i18n 键 `markdown.mermaid.rendering`（渲染中占位文案），说明是代码块触发而非工具产出。
|
||
- 适用：mermaid、KaTeX
|
||
|
||
### 路径 B：工具产出制品
|
||
|
||
专用工具（如 `show_html`）返回一段 HTML，以「制品块」形式呈现，带独立查看器 UI。
|
||
|
||
- 优点：有明确的类型边界，可以配查看器（切代码 / 复制 / 下载 / 导出图片）与独立的安全边界。
|
||
- 证据：WorkBuddy 的 `show_widget` 工具 + `SYn = {show_widget, visualize:show_widget, visualizer:show_widget}`，走 `<iframe sandbox="allow-scripts">`。
|
||
- 适用：HTML 制品（交互式页面、可视化）
|
||
|
||
---
|
||
|
||
## 3. 各类型的渲染方案与安全边界
|
||
|
||
### 3.1 mermaid 流程图（路径 A）
|
||
|
||
```
|
||
```mermaid
|
||
flowchart LR
|
||
A[用户] --> B[内核] --> C[结果]
|
||
```
|
||
```
|
||
|
||
渲染：` ```mermaid ` 代码块 → 动态加载 mermaid → `mermaid.render()` → 得到 SVG → **消毒** → 注入。
|
||
|
||
**消毒是必须的**，直接照抄 WorkBuddy 已验证的配置：
|
||
|
||
```js
|
||
DOMPurify.sanitize(svg, {
|
||
USE_PROFILES: { svg: true, svgFilters: true },
|
||
FORBID_TAGS: ["script", "foreignObject"],
|
||
FORBID_ATTR: ["srcdoc", "formaction"],
|
||
});
|
||
```
|
||
|
||
要点：
|
||
- **只开 SVG profile**（不含 HTML profile）——消毒结果只能表达图形，带不了 `<a>`/`<form>`
|
||
- **禁 `foreignObject`**：它能把 HTML 塞进 SVG 里绕过 SVG profile
|
||
- 渲染中显示占位（对应 `markdown.mermaid.rendering` 那种文案），失败时**回退显示原始代码**而不是空白
|
||
|
||
### 3.2 数学公式（路径 A）
|
||
|
||
`$inline$` 与 `$$block$$` → remark-math + rehype-katex → KaTeX 产出 HTML。
|
||
|
||
KaTeX 的输入是公式文本、输出是受控 HTML，**不需要额外消毒**（与 WorkBuddy 一致）。
|
||
|
||
### 3.3 HTML 制品（路径 B）
|
||
|
||
```jsx
|
||
<iframe sandbox="allow-scripts" srcDoc={html} title="交互制品" />
|
||
```
|
||
|
||
**不带 `allow-same-origin` 是整个方案的核心**：制品里的 JS 能跑（图表要动），但因为源是 opaque origin ——
|
||
读不到 `localStorage`、拿不到父窗口 DOM、发不出带 cookie 的请求。
|
||
|
||
已确认的前提：Ygent 的 `tauri.conf.json` 里 `"csp": null`，**不会拦 iframe srcdoc**。
|
||
若将来收紧 CSP，需为 iframe 放行（或在制品 HTML 内自带 `<meta http-equiv="Content-Security-Policy">`）。
|
||
|
||
查看器能力（参考 WorkBuddy 的 `widget.*` 文案）：
|
||
显示 UI ⇄ 查看代码、复制代码、下载到本地、导出为图片、加载中态、错误面板。
|
||
|
||
---
|
||
|
||
## 4. 数据模型
|
||
|
||
**不需要新增 `MsgKind`。** 制品就是工具产出，复用现有 `tool` kind：
|
||
|
||
```ts
|
||
export type MsgKind = "user" | "agent" | "tool" | "perm"; // 不变
|
||
|
||
export interface ChatMessage {
|
||
// …现有字段
|
||
/** 制品：HTML 内容或落盘路径（见 §4.1） */
|
||
artifact?: { kind: "html"; path: string; title?: string };
|
||
/** 制品必须 keepVisible —— 折叠时不能被收走（否则制品整个消失） */
|
||
keepVisible?: boolean;
|
||
}
|
||
```
|
||
|
||
`toolState` 已在本轮补上，制品卡直接复用「运行中 / 完成」两态。
|
||
|
||
### 4.1 制品内容存哪（待决策）
|
||
|
||
| 方案 | 优点 | 缺点 |
|
||
|---|---|---|
|
||
| 存 `messages.result`（TEXT） | 零改动 | 大 HTML 撑大 SQLite；`list_messages` 变重 |
|
||
| **落项目工作目录 + DB 只存路径（建议）** | 符合「目录即项目」哲学；可被工具读回；DB 轻 | 需要文件生命周期管理 |
|
||
|
||
建议第二种：`.agent/artifacts/<message-id>.html`，DB 的 `result` 只存相对路径。
|
||
删除会话时一并清理（或按「永不删除项目目录」的铁律只解除登记）。
|
||
|
||
---
|
||
|
||
## 5. 与「回合分组 / 折叠」的关系（容易踩坑）
|
||
|
||
这是 WorkBuddy 用 `isShowWidget` + `keepVisible` + `presentationGroupId` 解决的问题，Ygent 必须一起考虑：
|
||
|
||
1. **制品不能被折叠掉。** 回合结束时会把连续工具块收成一行摘要——制品必须 `keepVisible`，
|
||
否则用户点了折叠，图表就没了。
|
||
2. **制品要和它的解释文字绑在一起。** WorkBuddy 的做法是制品块向前找最近的正文块，
|
||
共享 `presentationGroupId`。Ygent 目前用「回合」粒度分组（见 `ChatView.tsx` 的 `groupTurns`），
|
||
如果制品总是出现在回合末尾，回合粒度暂时够用；一旦出现「文字→制品→文字」的结构，
|
||
就需要下沉到块粒度。
|
||
3. **制品高度不定**，不能像工具卡那样单行省略。需要 iframe 通过 `postMessage` 上报高度自适应，
|
||
或给一个可拖拽/固定高度 + 内部滚动。
|
||
|
||
---
|
||
|
||
## 6. 体积代价（必须先决策）
|
||
|
||
| 依赖 | 体积 | 现状 |
|
||
|---|---|---|
|
||
| mermaid | **~2.8 MB**（WorkBuddy 的 `vendor-mermaid` chunk） | Ygent 前端 bundle 现在共 563 KB |
|
||
| katex | ~300 KB（含字体） | — |
|
||
| dompurify | ~45 KB | — |
|
||
|
||
**结论：一律动态 `import()`，按需加载，首次出现该内容类型时才拉。**
|
||
|
||
否则只为了偶尔一张流程图，就把首屏 bundle 撑到 3 MB+，冷启动明显变慢——这跟前面查到的「OMP 内核启动 1.31s」是同一类问题。
|
||
|
||
---
|
||
|
||
## 7. 顺带：代码 diff 视图（与富内容同级）
|
||
|
||
工具改文件时显示行级 diff，WorkBuddy 的 `tool-diff` 是现成参考：
|
||
|
||
- 输入 `oldCode` / `newCode` / `fileName`
|
||
- 按扩展名推断语言（`ts/tsx/js/py/rs/go/java/kt/swift/c/cpp/cs/php/css/html/vue/sh/yml/sql/scala`）
|
||
- Prism 懒加载该语言 + LRU 缓存，**语言不支持时回退 HTML 转义纯文本**（不要渲染空白）
|
||
- 行渲染 `+/−` 号
|
||
|
||
Ygent 的 `edit` / `write` 卡目前只显示「项目/新增文档.md +15」徽标。
|
||
要做 diff 的话，**必须用转义兜底**——文件内容绝不能当 HTML 注入。
|
||
|
||
---
|
||
|
||
## 8. 建议的分阶段落地
|
||
|
||
| 阶段 | 内容 | 成本 | 收益 |
|
||
|---|---|---|---|
|
||
| **P1** | mermaid 代码块（动态 import + DOMPurify SVG 消毒 + 失败回退原始代码） | 低 | 直观，模型零适配 |
|
||
| **P2** | KaTeX 公式（remark-math + rehype-katex，动态 import） | 低 | 技术对话可读性明显提升 |
|
||
| **P3** | 代码 diff 视图（`edit`/`write` 卡） | 中 | 直接改善现有工具卡 |
|
||
| **P4** | HTML 制品（工具 + iframe 查看器 + 存储策略） | 高 | 能力上限最高，但需要先定 §4.1 和 §5 |
|
||
|
||
P1 + P2 可以在一个改动里做完（都是 Markdown 管线扩展 + 动态加载），建议作为第一步。
|
||
|
||
---
|
||
|
||
## 9. 待决策清单
|
||
|
||
1. **制品 HTML 存 DB 还是落项目目录？**（建议落目录，见 §4.1）
|
||
2. **是否允许制品访问外网（CDN 脚本/字体）？** 现在 `csp: null` 允许；要不要收紧到白名单？
|
||
3. **制品高度**：`postMessage` 自适应，还是固定高度 + 内部滚动？
|
||
4. **mermaid 之外是否还要别的图表库**（如 ECharts）？WorkBuddy 的 `show_widget` 走的是「生成 HTML」而不是绑定图表库，这条路更通用但要制品能力先就位。
|
||
5. **是否给制品加「导出为图片」**？WorkBuddy 有（`widget.downloadImage`），但需要额外依赖做 HTML→图片。
|
||
|
||
---
|
||
|
||
## 附：与 WorkBuddy 的差异（有意为之）
|
||
|
||
| 项 | WorkBuddy | Ygent 建议 |
|
||
|---|---|---|
|
||
| 高亮库 | Prism | 保持 highlight.js（已用，换库无收益） |
|
||
| Markdown 裸 HTML | 未开启 | **同样不开启** |
|
||
| 制品渲染 | iframe sandbox | 同 |
|
||
| 内联 SVG 消毒 | DOMPurify SVG profile | 同（做 mermaid 时一并引入） |
|
||
| 虚拟列表 | 有 | **不做**（Ygent 无此瓶颈） |
|
||
| widget 分组 | 有（`presentationGroupId`） | **暂不做**，先用回合粒度；出现「文字→制品→文字」再下沉 |
|