# 文件输出规则（完整）

## 调用规范

调用 `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
{
  "fileName": "report.csv",
  "content": "id,name,value\n1,test,100",
  "userId": "jerry",
  "sessionId": "sess_abc123"
}
```

返回结果：

```json
{
  "message": "文件写入成功",
  "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` / `storage_file_read_to_local` 通过 `key` 参数定位文件；`key` 来自 `storage_file_write` / `storage_file_upload` 的返回值，或 `storage_file_list` 列出的文件项。`storage_file_list` 可传入 `userId` / `sessionId` 限定范围（取值方式同上，来自消息开头的 `[context]` 行）。

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

### storage_file_read（文本文件）

- 适用于：CSV、JSON、TXT、Markdown、代码文件等文本类型
- 入参：`key`（对象 key）
- 返回纯文本内容，可直接用于分析

### storage_file_read_to_local（任意文件）

- 适用于：图片、PDF、压缩包、Excel 等二进制文件
- 入参：`key`（对象 key）
- 将文件下载到本地临时路径（`/tmp/fwh-toolbox-agent/downloads/`），返回本地文件路径 `localPath`
- **图片文件**（png/jpg/gif/webp）下载后可通过本地路径进行 AI 视觉分析
- 其他二进制文件下载后主要用于中转（如重新上传、返回给前端下载）

### 判断标准

- 用户要求分析文本文件 → `storage_file_read`
- 用户要求分析图片/二进制内容 → `storage_file_read_to_local`
- 需要获取文件原始数据（中转、转发） → `storage_file_read_to_local`
- 不确定文件类型或不知道 key 时 → 先用 `storage_file_list` 查看文件信息（含 key），再选择合适的读取方式

## 写文件策略

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

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

#### 文本文件（CSV、JSON、Markdown、代码等）

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

#### 任意类型文件（二进制文件、图片、PDF、压缩包、Excel 等）

- 使用 `storage_file_upload` 工具上传（最大 100MB）
- 直接传入本地文件的绝对路径 `localPath` 参数（无需 base64 编码）
- 可选传入 `fileName` 参数指定上传后的文件名（不传则使用本地文件名）
- 尽量传入 `userId` 和 `sessionId`
- 上传成功后同样输出 `$$FILE_DOWNLOAD:...$$` 标记

### 临时文件（中间处理、缓存等）

- 写入 `/tmp/fwh-toolbox-agent/` 目录
- 处理完成后无需输出下载标记

### 判断标准

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