文件操作说明

Agent 文件操作接口提供对应用工作空间文件系统的完整管理能力，包括目录浏览、文件树、文件上传（普通/分片）、下载、编辑、复制、移动、删除、创建目录及搜索等操作。

Workspace 说明

注意

此处的 Workspace（文件工作空间） 与平台的工作空间（Space） 是两个不同的概念，请勿混淆。平台工作空间是租户/团队维度的资源隔离单元，用于管理应用、成员和权限；文件 Workspace 是 Agent 运行时的文件沙盒环境，以业务方用户为维度独立分配，仅用于文件存储与访问。

Workspace 与用户的关系：

Workspace 以用户为维度创建，每个业务方用户（user_id）对应一个独立的工作空间。所有文件操作接口均需传入 user_id，平台根据 user_id 定位该用户的工作空间，不同用户之间的文件数据完全隔离、互不可见。

Workspace 与 Agent 的关系：

Workspace 不与具体 Agent 应用绑定，而是归属于用户。同一用户调用不同 Agent 时，共享同一个工作空间。这意味着一个 Agent 写入的文件，另一个 Agent 可以直接读取，便于多 Agent 协作处理同一份数据。

Workspace 与后端存储的关系：

Workspace 的持久化存储基于对象存储（OBS），同时在 Agent 运行期间挂载到 sandbox 容器内作为本地文件系统使用。两者通过同步机制保持一致：

• sandbox 运行时：文件写操作先落到 sandbox 本地，再异步同步到 OBS；读操作直接从 OBS 获取。
• sandbox 未启动时：文件操作直接读写 OBS。

客户端路径（如 /data/file.csv）对应 OBS 中的存储路径为 workspaces/user_{userID}/data/file.csv，内部映射对调用方透明。

路径规则：

• 客户端路径以 / 开头（如 /data/file.csv）
• 内部 /workspace/ 目录对客户端透明，视为根目录
• 禁止包含 .. 的路径

INFO

文件操作接口仅适用于 Agent 类型应用。

请求头（公共）

参数名	必填	说明
Authorization	是	鉴权凭证，格式 Bearer sk_xxx

统一响应格式

{
  "code": 200,
  "data": {},
  "message": "",
  "trace_id": "xxx"
}

文件对象结构

各接口返回的文件对象字段如下：

字段	类型	说明
name	string	文件或目录名称
path	string	完整路径
size	number	文件大小（字节），目录为 0
is_dir	bool	是否为目录
mod_time	string	最后修改时间，ISO 8601 UTC 格式
url	string	文件访问 URL，仅文件返回，目录无此字段
is_agent_dir	bool	是否为 Agent 家目录，仅列出根目录时对目录标记
agent_app_id	string	所属 Agent 应用 ID，仅 Agent 家目录返回
agent_name	string	所属 Agent 应用名称，仅 Agent 家目录返回

TIP

is_agent_dir / agent_app_id / agent_name 仅在列出目录接口列出根目录时返回，用于标识各 Agent 的专属工作目录，其他接口及子目录列表不会返回这些字段。

注意事项

1. 客户端路径必须以 / 开头，禁止包含 .. 路径遍历字符，空路径或 / 表示根目录。
2. 上传未指定 path 时，文件上传到根目录并保持原始文件名。
3. 编辑接口中 old_string 必须在文件中存在，new_string 为空时等同于删除 old_string。
4. 复制/移动目标路径已存在时会返回错误，不会覆盖已有文件。
5. 删除目录时递归删除其下所有内容。
6. 创建目录时自动填充 .empty 隐藏文件，保证 OBS 等云存储中目录可见。
7. 搜索为递归全量扫描，仅返回文件，不含目录，关键词匹配大小写不敏感。
8. 下载文件接口直接返回文件二进制流，下载目录接口将目录打包为 zip 返回。
9. 分片上传适用于大文件场景，完整流程及各子接口说明见分片上传。
10. 查询文件记录基于文件元数据表分页查询，支持按类型筛选与排序，返回结构与对象存储实时扫描类接口（列出目录、文件树、搜索）不同，适用于管理类场景。