> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zeus.agentspro.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# Artifacts 结构化输出

> Zeus 结构化工具返回格式

## 概述

Artifacts 是一种结构化的工具返回格式，用于在 Trajectory 区域渲染丰富的内容（HTML、代码、Diff、图表等），而不是显示原始文本。渲染采用 **VSCode 浅色风格**，使用 Prism.js 语法高亮和行号。

## 问题背景

当前工具返回的结果存在以下问题：

1. **格式不统一**：不同工具返回格式各异
2. **前端解析困难**：依赖正则表达式检测内容类型
3. **渲染受限**：无法区分可渲染内容和普通文本
4. **扩展性差**：每新增一种类型都需要修改前端检测逻辑

## 数据结构设计

### ToolResultContent

工具返回内容的结构化表示，包含以下字段：

| 字段         | 类型          | 说明                             |
| ---------- | ----------- | ------------------------------ |
| `type`     | string      | 内容类型（见下表）                      |
| `data`     | string      | 内容数据                           |
| `language` | string (可选) | 编程语言标识                         |
| `title`    | string (可选) | 标题（也用于通过文件扩展名检测语言）             |
| `meta`     | object (可选) | 额外元数据（如 `old_content` 用于 diff） |

### ToolResult

标准工具返回格式：

| 字段          | 类型                     | 说明                  |
| ----------- | ---------------------- | ------------------- |
| `success`   | boolean                | 是否成功                |
| `message`   | string                 | 结果消息（简洁描述，供 LLM 使用） |
| `content`   | ToolResultContent (可选) | 结构化内容（供用户展示）        |
| `file_path` | string (可选)            | 关联文件路径              |
| `files`     | SandboxFile\[] (可选)    | 生成的文件列表             |

### SandboxFile

沙盒操作返回的文件元数据：

| 字段             | 类型          | 说明                                      |
| -------------- | ----------- | --------------------------------------- |
| `name`         | string      | 文件名                                     |
| `type`         | string      | 文件类型（`document`、`code`、`image`、`other`） |
| `sandbox_path` | string      | 沙盒内文件路径                                 |
| `url`          | string (可选) | 云端存储 URL（如 Supabase Storage）            |
| `content`      | string (可选) | 文件内容或 base64                            |
| `size`         | number (可选) | 文件大小（字节）                                |

## 内容类型说明

| type       | 说明       | 渲染方式                         |
| ---------- | -------- | ---------------------------- |
| `text`     | 纯文本      | `<pre>` 或 Markdown 渲染器（自动检测） |
| `html`     | HTML 内容  | `<iframe>` 沙盒渲染              |
| `markdown` | Markdown | Markdown 渲染器                 |
| `code`     | 代码       | Prism.js 语法高亮 CodeBlock，带行号  |
| `json`     | JSON 数据  | Prism.js 高亮 JSON 查看器，带行号     |
| `image`    | 图片       | `<img>`                      |
| `error`    | 错误信息     | 红色错误样式                       |

## Diff 渲染

对于 `edit` 和 `write` 工具的返回结果，当存在 `meta.old_content` 时，前端会渲染 **DiffPreview** 组件而非标准 Artifact 渲染器，提供类 Cursor 的统一 diff 视图。

### 工作原理

1. **后端**：`write` 工具在覆写前读取文件的旧内容，`edit` 工具在应用修改前捕获原始文件内容。两者都将旧内容存储在 `content.meta.old_content` 中。
2. **前端**：`WorkspaceArea` 组件检测到 `edit`/`write` 结果包含 `meta.old_content` 时，使用 `react-diff-viewer-continued` 渲染 `DiffPreview`，并基于文件扩展名进行 Prism.js 语法高亮。
3. **降级方案**：对于 `meta.old_content` 不可用的 `edit` 调用，前端降级为对比 `parameters.old_string` 和 `parameters.new_string`（片段级 diff）。

### ToolCallCard 上的 Diff 统计

工具调用完成后，`ToolCallCard` 头部会显示行内 diff 统计（`+N` / `-N`），由新旧内容计算得出。用户可一目了然地了解增删的代码量。

## 前端渲染

前端根据 `content.type` 字段选择对应的渲染组件：

* **HTML**：沙盒 iframe 预览，支持设备宽度预设（桌面/平板/手机）和部署功能
* **Markdown**：完整 Markdown 渲染器
* **Code**：VSCode 风格浅色表格布局，带行号、Prism.js 语法高亮、长文件（>20 行）可折叠
* **JSON**：与代码相同的表格布局，JSON 专属高亮
* **Image**：直接 `<img>` 显示
* **Error**：红色错误样式
* **Diff**（edit/write）：统一 diff 视图，增删行高亮

### Raw 模式

工作区支持在 **Preview** 和 **Raw** 模式间切换。Raw 模式以 Prism.js 高亮 JSON 显示参数和结果，Section 头部带复制按钮，取代了之前基于 Monaco Editor 的方案，更轻量、渲染更快。

## 向后兼容

* 前端同时支持新旧格式
* 旧格式（纯文本）会被包装为 `type: "text"` 的 content
* 渐进式迁移，不影响现有功能