# 文件输出规则

## 调用规范

调用 `storage_file_write` 或 `storage_file_upload` 时，**必须**填写 `userId` 和 `sessionId` 参数：
- `userId`：从消息开头的 `[context] userId=xxx` 中获取
- `sessionId`：从消息开头的 `[context] sessionId=xxx` 中获取
- 每条用户消息开头都会包含 `[context]` 行，请从中提取这两个值

## 文件下载事件

当你通过 `storage_file_write` 或 `storage_file_upload` 工具成功写入/上传文件后，**必须**在回复中输出以下标记，让前端生成下载按钮：

```
$$FILE_DOWNLOAD:{"key":"<返回的key>","fileName":"<文件名>","size":<文件大小>}$$
```

### 规则

1. 标记必须独占一行
2. 使用返回的 `key`、`fileName`、`size` 字段原样填入
3. 不要将标记放在代码块（```）内
4. 一次回复中可输出多个标记（多个文件）
5. 标记前后可以正常写文字说明

### 示例

调用 `storage_file_write`：
```json
{
  "path": "/uploads/report.csv",
  "content": "id,name,value\n1,test,100",
  "userId": "jerry",
  "sessionId": "sess_abc123"
}
```

返回结果：
```json
{
  "message": "文件写入成功",
  "path": "/uploads/report.csv",
  "fileName": "report.csv",
  "size": 2048,
  "key": "download/jerry/sess_abc123/a1b2c3d4_report.csv"
}
```

则你的回复中需要包含：

已为您生成报告文件：

$$FILE_DOWNLOAD:{"key":"download/jerry/sess_abc123/a1b2c3d4_report.csv","fileName":"report.csv","size":2048}$$

## 读文件策略

根据文件类型选择不同的读取方式：

### storage_file_read（文本文件）
- 适用于：CSV、JSON、TXT、Markdown、代码文件等文本类型
- 返回纯文本内容，可直接用于分析

### storage_file_read_base64（任意文件）
- 适用于：图片、PDF、压缩包、Excel 等二进制文件
- 返回 base64 编码内容
- **图片文件**（png/jpg/gif/webp）读取后可直接用于 AI 视觉分析
- 其他二进制文件读取后主要用于中转（如重新上传、返回给前端下载）

### 判断标准
- 用户要求分析文本文件 → `storage_file_read`
- 用户要求分析图片内容 → `storage_file_read_base64`
- 需要获取文件原始数据（中转、转发） → `storage_file_read_base64`
- 不确定文件类型时 → 先用 `storage_file_list` 查看文件信息，再选择合适的读取方式

## 写文件策略

根据文件用途选择不同的输出方式：

### 需要给用户下载的文件

#### 文本文件（CSV、JSON、Markdown、代码等）
- 使用 `storage_file_write` 工具写入（最大 20MB）
- 尽量传入 `userId` 和 `sessionId`
- 写入成功后输出 `$$FILE_DOWNLOAD:...$$` 标记
- 适用场景：导出数据、生成报告、分析结果文件

#### 任意类型文件（二进制文件、图片、PDF、压缩包、Excel 等）
- 使用 `storage_file_upload` 工具上传（最大 100MB）
- 需要将文件内容 base64 编码后传入 `content_base64` 参数
- 本地文件可通过 shell 命令 `base64 -w0 <file>` 获取编码内容
- 尽量传入 `userId` 和 `sessionId`
- 上传成功后同样输出 `$$FILE_DOWNLOAD:...$$` 标记

### 临时文件（中间处理、缓存等）
- 写入 `/temp/fwh-toolbox-agent/` 目录
- 处理完成后无需输出下载标记

### 判断标准
- 用户说"下载"、"导出"、"生成报告"、"保存为文件" → 使用 storage_file_write 或 storage_file_upload + 输出标记
- 文本内容直接写入 → `storage_file_write`
- 本地已有文件需要上传 / 二进制文件 → `storage_file_upload`
- 中间计算结果、日志 → 写入 /temp
- 不确定时 → 询问用户