会话文件

智能体在会话里运行时，产物（报告、代码、压缩包等）都落在该会话的工作目录（<agent-dir>/.raagent/workdir-<会话ID>，由主机 CLI 管理的真实文件系统）。会话文件接口提供只读通道：列文件树、下载单个文件。

• 鉴权：raa- API Key 或 Web JWT 均可（与市场/会话接口一致）。
• 只能访问当前账号自己的会话，他人会话返回 404。
• 文件路径相对会话工作目录（如 out/report.zip）；fileId = 路径的 encodeURIComponent 结果。
• 路径穿越与符号链接逃逸在主机 CLI 侧拦截：指向工作目录外的路径一律拒绝。
• 下载单文件 ≤ 50M。
• 需要主机在线（文件在主机本地磁盘上，离线时无法读取）。

接口

方法与路径	说明
GET /api/v1/sessions/{id}/files/tree	返回会话工作目录的文件树。
GET /api/v1/sessions/{id}/files/{fileId}/download	下载单个文件（二进制流）。

文件树

GET /api/v1/sessions/s-1/files/tree HTTP/1.1
Host: raagent.me
Authorization: Bearer raa-REPLACE_WITH_YOUR_KEY

{
  "code": "0",
  "message": "ok",
  "data": {
    "workdir": {
      "id": "root-workdir",
      "name": "workdir",
      "type": "directory",
      "path": "",
      "children": [
        {
          "id": "out%2Freport.zip",
          "name": "report.zip",
          "type": "file",
          "size": 20480,
          "mtime": 1788000000000,
          "path": "out/report.zip"
        }
      ]
    }
  }
}

节点字段：

字段	类型	说明
id	string	相对路径的 encodeURIComponent（下载时用作 fileId）
name	string	文件/目录名
type	string	file / directory
size	number?	字节数（目录无此字段）
mtime	number?	修改时间（Unix 毫秒）
path	string	相对会话工作目录的路径

说明：隐藏文件（. 开头）、node_modules、.git 与符号链接不出现在树中；节点总量超过 5000 时截断（响应标记 truncated: true）。

下载文件

fileId 取文件树节点的 id（或自行对相对路径做 encodeURIComponent）：

GET /api/v1/sessions/s-1/files/out%2Freport.zip/download HTTP/1.1
Host: raagent.me
Authorization: Bearer raa-REPLACE_WITH_YOUR_KEY

成功返回 200，Content-Type: application/octet-stream，Content-Disposition 携带 UTF-8 文件名，body 为文件原始字节。文件不存在、路径越界或超过 50M 时返回错误 envelope。

典型用法：回收成果报告

调度系统跑完任务后，先列树找到产物路径，再下载：

# 1. 列出文件（或直接 GET files/tree）
raagent session files s-1

# 2. 下载产物
raagent session download s-1 out/report.zip --out ./report.zip

等价的裸 HTTP 调用见上两节。相关 CLI 命令详见文档中心「CLI 命令手册」的 session 一节。