# 文件输出规则

## storage_file_write 调用规范

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

## 文件下载事件

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

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

### 规则

1. 标记必须独占一行
2. 使用 `storage_file_write` 返回的 `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_write` 工具写入
- 尽量传入 `userId` 和 `sessionId`
- 写入成功后输出 `$$FILE_DOWNLOAD:...$$` 标记
- 适用场景：导出数据、生成报告、分析结果文件

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

### 判断标准
- 用户说"下载"、"导出"、"生成报告"、"保存为文件" → 使用 storage_file_write + 输出标记
- 中间计算结果、日志 → 写入 /temp
- 不确定时 → 询问用户