FranklinWH-Toolbox/service/cmd/mcp/.kiro/steering/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：

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

返回结果：

{
  "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_to_local（任意文件）

• 适用于：图片、PDF、压缩包、Excel 等任意类型文件
• 将文件从 MinIO 下载到本地临时路径 /tmp/fwh-toolbox-agent/downloads/
• 返回本地文件路径，可用于后续处理：
  • 图片文件：通过本地路径读取后用于 AI 视觉分析
  • Excel/PDF：通过工具解析后提取文本
  • 任意文件：中转、转发、或作为其他工具的输入

判断标准

• 用户要求分析文本文件 → storage_file_read
• 用户要求处理非文本文件（图片、PDF、Excel 等） → storage_file_read_to_local
• 不确定文件类型时 → 先用 storage_file_list 查看文件信息，再选择合适的读取方式

写文件策略

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

需要给用户下载的文件

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

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

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

• 使用 storage_file_upload 工具上传（最大 100MB）
• 传入本地文件的绝对路径（localPath 参数），服务端直接读取文件
• 无需 base64 编码，不占用 token
• 尽量传入 userId 和 sessionId
• 上传成功后同样输出 $$FILE_DOWNLOAD:...$$ 标记

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

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

判断标准

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