zclaw_openfang/docs/references/artifact-system-reference.md

产物系统参考文档

调研 DeerFlow 和 Hermes Agent 的产物/输出面板实现，为 ZCLAW 产物系统重构提供参考。 分析日期：2026-04-24

---

一、DeerFlow 产物系统

DeerFlow 有完整的全栈产物管道，是主要参考对象。

1.1 端到端数据流

Agent tool call (write_file / str_replace / present_files)
    ↓
Backend: ThreadState.artifacts (LangGraph annotated list, merge_artifacts reducer 去重)
    ↓ 文件写入: {base_dir}/threads/{thread_id}/user-data/outputs/
    ↓ 虚拟路径: /mnt/user-data/outputs/filename.ext
    ↓
Backend API: GET /api/threads/{thread_id}/artifacts/{virtual_path}
    ↓ MIME 检测 / .skill ZIP 解压 / download vs inline
    ↓
Frontend: thread.values.artifacts (string[]) → ArtifactsProvider context
    ↓
ChatBox (ResizablePanelGroup) → chat(60%) | artifact panel(40%)
    ↓
ArtifactFileDetail → CodeMirror(代码) / Streamdown(Markdown) / iframe(HTML)

1.2 关键文件

前端核心

文件	职责
frontend/src/core/artifacts/utils.ts	URL 构建、产物列表提取、路径解析
frontend/src/core/artifacts/loader.ts	从后端 API 获取产物文本；从 tool call args 直接提取内容
frontend/src/core/artifacts/hooks.ts	TanStack React Query hook，5 分钟缓存
frontend/src/components/workspace/artifacts/context.tsx	ArtifactsProvider + useArtifacts() — 管理列表、选中、开关、自动选中
frontend/src/components/workspace/artifacts/artifact-file-detail.tsx	产物详情视图：头部(文件选择器+code/preview切换) + CodeEditor/Preview
frontend/src/components/workspace/artifacts/artifact-file-list.tsx	卡片式列表视图，每个卡片含图标/名称/扩展名/下载/安装按钮
frontend/src/components/workspace/artifacts/artifact-trigger.tsx	头部触发按钮，仅在产物存在时显示

前端渲染

文件	职责
frontend/src/components/workspace/code-editor.tsx	CodeMirror 只读编辑器，支持 CSS/HTML/JS/JSON/MD/Python 语法高亮
frontend/src/components/ai-elements/code-block.tsx	Shiki 语法高亮代码块，双主题(light/dark)
frontend/src/components/ai-elements/web-preview.tsx	iframe 网页预览，含地址栏和导航按钮
frontend/src/components/workspace/messages/markdown-content.tsx	Streamdown 渲染 Markdown (GFM + Math + Raw HTML + KaTeX)
frontend/src/core/utils/files.tsx	140+ 扩展名→语言映射，文件图标/类型判断

后端

文件	职责
backend/.../thread_state.py	ThreadState.artifacts 列表 + merge_artifacts 去重 reducer
backend/.../present_file_tool.py	present_files 工具 — 标准化路径，返回 Command(update)
backend/.../paths.py	路径管理：threads/{id}/user-data/{workspace,uploads,outputs}
backend/app/gateway/routers/artifacts.py	FastAPI 路由：GET 产物文件，MIME 检测，安全处理

1.3 支持的内容类型

类型	渲染方式
代码文件 (140+ 扩展名)	CodeMirror 只读 + 语法高亮
Markdown (.md)	Streamdown (GFM + Math + KaTeX + Raw HTML)
HTML (.html/.htm)	沙箱 <iframe> (srcDoc)
图片 (.png/.jpg/.svg/.webp)	<img> 标签，非代码文件用 iframe
.skill 压缩包	ZIP 解压，SKILL.md 渲染为 Markdown
二进制文件 (PDF 等)	后端 inline Content-Disposition
文本文件 (.txt/.csv/.log)	CodeMirror 纯文本模式

1.4 持久化架构

磁盘存储：

{DEER_FLOW_HOME}/threads/{thread_id}/user-data/outputs/

状态持久化： artifacts 列表是 LangGraph ThreadState 的一部分，由 checkpoint 系统自动持久化。

前端缓存： TanStack React Query，5 分钟 stale time。

1.5 UI/UX 设计模式

分栏布局 (chat-box.tsx)

• react-resizable-panels 水平分栏
• 关闭态：chat=100%, artifacts=0%
• 打开态：chat=60%, artifacts=40%
• 300ms CSS 过渡动画

自动打开 + 自动选中

• 检测到 write_file / str_replace tool call 时自动打开面板并选中文件
• autoOpen / autoSelect 标志防止用户手动关闭后重复打开

代码/预览切换

• HTML/Markdown 默认 Preview，其他默认 Code
• Preview 用 Streamdown(MD) 或 iframe(HTML)

头部操作栏

• 文件选择器下拉菜单（不用返回列表即可切换）
• 复制 / 下载 / 新窗口打开 / 关闭

聊天内嵌展示

• present_files tool call → 聊天流内渲染卡片网格
• 点击卡片 → 侧栏打开该文件

双路径方案

1. 真实文件路径 — 从后端 API 获取，React Query 缓存
2. write-file: 虚拟路径 — 直接从 tool call args 提取内容，无需后端请求，支持流式显示

1.6 Provider 层级

ArtifactsProvider → 提供useArtifacts() context
  ChatBox → ResizablePanelGroup
    Panel(chat) → MessageList → ToolCall 自动打开产物面板
    Panel(artifacts) → ArtifactFileDetail → useArtifactContent() hook

---

二、Hermes Agent 产物机制

结论：Hermes Agent 无产物面板、无 Web 前端、无分栏布局。 它是终端 CLI 工具，所有输出在终端内联渲染。但有值得借鉴的大输出处理机制。

2.1 项目定位

Hermes Agent 是 Python CLI/TUI Agent（类似 Claude Code），通过 prompt_toolkit TUI 运行，同时支持 Telegram/Discord/Slack/WhatsApp 等 IM 平台网关。

无 React/Next.js/Web UI。 暴露 OpenAI 兼容 API 供 Open WebUI/LobeChat 等第三方 UI 接入。

2.2 大输出处理（3 层防御）

这是唯一接近"产物管理"的机制，值得借鉴。

文件：tools/tool_result_storage.py

层级	机制	说明
Layer 1	工具自身截断	每个工具限制自己的输出长度
Layer 2	maybe_persist_tool_result	单个结果超阈值 → 写入沙箱临时文件，上下文中替换为 <persisted-output> 预览块
Layer 3	enforce_turn_budget	整轮超过 200K 字符 → 最大的几个溢出到磁盘

核心逻辑：

# 超阈值时：完整内容写入文件，上下文替换为预览
remote_path = f"{storage_dir}/{tool_use_id}.txt"
_write_to_sandbox(content, remote_path, env)
return _build_persisted_message(preview, has_more, len(content), remote_path)
# 后续 agent 可用 read_file + offset/limit 读取完整内容

2.3 预算配置

文件：tools/budget_config.py

参数	默认值
DEFAULT_RESULT_SIZE_CHARS	100,000（单工具阈值）
DEFAULT_TURN_BUDGET_CHARS	200,000（整轮上限）
DEFAULT_PREVIEW_SIZE_CHARS	1,500（内联预览长度）

2.4 CLI 渲染方式

文件：agent/display.py

• 工具进度：KawaiiSpinner 动画 + 一行摘要
• 文件编辑：内联 colored unified diff（write_file / patch 工具）
• 最终响应：Rich Panel 边框包裹，主题色可换（7 套 skin）

2.5 会话持久化

文件：hermes_state.py

SQLite (~/.hermes/state.db) + FTS5 全文搜索：

• sessions 表：元数据、模型配置、token 计数、费用、标题
• messages 表：role、content、tool_call_id、reasoning、时间戳

2.6 值得借鉴的点

点	借鉴价值
大输出溢出到磁盘 + 内联预览	解决 context window 溢出问题
3 层递进防御	对 ZCLAW 中间件链有参考价值
预算配置化	阈值可调，不同场景不同策略

---

三、对比分析：ZCLAW 现状 vs 参考方案

3.1 现状差距

维度	DeerFlow	ZCLAW 现状	差距
数据源	3 个工具(present_files/write_file/str_replace)主动注册	仅 streamStore 解析 tool output 的 filePath	极窄，几乎不触发
持久化	磁盘文件 + LangGraph checkpoint	纯内存 Zustand	刷新即丢失
渲染-代码	CodeMirror 只读 + 语法高亮 (140+ 语言)	纯 <pre> 标签，无高亮	无高亮
渲染-Markdown	Streamdown (GFM+Math+KaTeX+RawHTML)	手写 30 行正则渲染器	仅标题/粗体/列表
渲染-HTML	沙箱 iframe	不支持	无
渲染-图片	<img> + iframe	类型声明了无实现	无
渲染-表格	GFM 表格	纯文本 <pre>	无
面板布局	react-resizable-panels 60/40	react-resizable-panels 65/35	已有，可复用
自动打开	write_file/str_replace 触发	addArtifact 时打开	已有
文件选择	下拉菜单不离开详情视图	必须返回列表再选	体验差
聊天内嵌	present_files → 卡片网格	无	缺失
缓存	React Query 5min	无	缺失
双路径	真实路径 + write-file: 虚拟路径	仅运行时内存	缺失
右面板重叠	单一面板	ArtifactPanel + RightPanel"文件"tab 职责交叉	架构问题

3.2 核心差距总结

按优先级排列：

1. P0 数据源断裂 — 产物几乎没有来源，是最根本的问题
2. P0 无持久化 — 产物刷新即丢
3. P1 Markdown 渲染残缺 — 30 行正则 vs 完整 GFM 渲染器
4. P1 代码无语法高亮 — 纯 <pre> vs CodeMirror/Shiki
5. P2 双面板职责交叉 — ArtifactPanel vs RightPanel"文件"tab
6. P2 缺少详情内文件切换 — 需返回列表才能切换文件
7. P3 聊天内嵌产物卡片缺失
8. P3 HTML/图片/表格渲染缺失

3.3 推荐方案

方案 A：最小可行（基于现有架构补全）

在现有 ArtifactPanel + artifactStore 上修补：

• 数据源：扩展 streamStore 中的 tool output 解析，覆盖更多工具类型
• 持久化：artifactStore 追加 IndexedDB 写入（复用 messageStore 模式）
• Markdown：引入 react-markdown + remark-gfm 替换手写渲染器
• 代码高亮：引入 shiki 或 highlight.js
• 合并面板：RightPanel "文件"tab 功能合并到 ArtifactPanel，删除 RightPanel 的 files tab

工作量：~2-3 天

方案 B：参照 DeerFlow 重构（推荐）

借鉴 DeerFlow 架构但适配 ZCLAW Tauri 本地架构：

DeerFlow 组件	ZCLAW 适配
FastAPI 产物路由	Tauri 命令 artifact_list / artifact_read / artifact_serve
磁盘 outputs/ 目录	{workspace}/artifacts/{session_key}/
LangGraph checkpoint	SQLite (已有 zclaw-memory)
React Query 缓存	TanStack Query 或 Zustand + stale cache
CodeMirror 只读	引入 @uiw/react-codemirror
Streamdown MD	react-markdown + remark-gfm + rehype-katex
iframe HTML 预览	Tauri webview window (安全隔离)

核心改动清单：

1. Rust 侧（zclaw-kernel）：

   • 新增 artifact_create / artifact_list / artifact_read Tauri 命令
   • 产物写入 {workspace}/artifacts/{session_key}/
   • 中间件链中 ToolEnd 事件触发产物注册

2. 前端 Store：

   • artifactStore 增加 IndexedDB 持久化
   • 从 streamStore 解耦产物创建逻辑到独立 hook

3. 前端组件：

   • 替换 MarkdownPreview → react-markdown + GFM
   • 引入 CodeMirror/shiki 代码高亮
   • 详情视图增加文件下拉切换
   • RightPanel "文件" tab 合并或移除

工作量：~5-7 天

方案 C：借鉴 Hermes 防御机制（附加）

无论选 A 还是 B，都可叠加 Hermes 的大输出防御：

• 中间件链 ToolOutputGuard 层增加溢出检测
• 超阈值产物自动持久化到磁盘，上下文替换为 <persisted-output> 预览
• agent 可通过 read_file 回读完整内容

---

四、关键依赖库参考

库	用途	DeerFlow 使用	推荐
react-markdown	Markdown 渲染	✅ (Streamdown)	✅
remark-gfm	GFM 表格/删除线/任务列表	✅	✅
rehype-katex	数学公式渲染	✅	按需
@uiw/react-codemirror	代码编辑器/高亮	✅	✅
shiki	静态代码高亮	✅ (chat 内代码块)	✅
react-resizable-panels	分栏布局	✅	已有
@tanstack/react-query	数据缓存	✅	可选

---

五、文件索引

参考项目	关键路径
DeerFlow 前端	G:/deerflow/frontend/src/components/workspace/artifacts/
DeerFlow 前端工具	G:/deerflow/frontend/src/core/artifacts/
DeerFlow 布局	G:/deerflow/frontend/src/components/workspace/chats/chat-box.tsx
DeerFlow 代码编辑	G:/deerflow/frontend/src/components/workspace/code-editor.tsx
DeerFlow 后端路由	G:/deerflow/backend/app/gateway/routers/artifacts.py
DeerFlow 后端工具	G:/deerflow/backend/packages/harness/deerflow/tools/builtins/present_file_tool.py
Hermes 输出管理	G:/hermes-agent-main/tools/tool_result_storage.py
Hermes 预算配置	G:/hermes-agent-main/tools/budget_config.py