FranklinWH-Toolbox/deploy/kiro/skills/fwh-toolbox-rules/references/file-output-rules.md

文件输出规则（完整）

调用规范

调用 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：

{
  "fileName": "report.csv",
  "content": "id,name,value\n1,test,100",
  "userId": "jerry",
  "sessionId": "sess_abc123"
}

返回结果：

{
  "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
• 不确定时 → 询问用户