FileSystem 能力用于在云电脑环境中创建目录、读取文件、写入文件、移动文件和搜索文件。

接口清单

创建目录

await session.filesystem.create_directory({
  path: 'C:/ai-user-test'
});

成功时，业务数据通常包含：

{
  "path": "C:\\ai-user-test",
  "created": true
}

读取文件

读取文本文件时，可返回文本内容：

const result = await session.filesystem.read_file({
  path: 'C:/ai-user-test/demo.txt',
  offset: 0,
  length: 1024
});

console.log(result.data.content);

返回结构示例：

{
  "path": "C:\\ai-user-test\\demo.txt",
  "offset": 0,
  "bytesRead": 1024,
  "encoding": "utf-8",
  "content": "当前片段内容"
}

参数说明：

当前读取能力面向文本文件。服务端会尝试使用 utf-8、utf-8-sig、gbk 解码。无法解码为文本的文件会返回错误。

写入文件

await session.filesystem.write_file({
  path: 'C:/ai-user-test/result.txt',
  mode: 'overwrite',
  content: 'task result'
});

mode 支持：

成功时，业务数据通常包含：

{
  "path": "C:\\ai-user-test\\result.txt",
  "mode": "overwrite",
  "charsWritten": 11
}

大内容写入

调用方通常只需要传入 content。当写入内容较大时，SDK 和服务会自动适配处理，调用方式保持不变。

建议业务侧按普通文本写入方式调用，不需要关注内部传输方式。

移动文件

await session.filesystem.move_file({
  source: 'C:/ai-user-test/result.txt',
  destination: 'C:/ai-user-test/archive/result.txt'
});

move_file 可用于移动或重命名文件、目录。目标父目录不存在时会自动创建。

搜索文件

const result = await session.filesystem.search_files({
  path: 'C:/ai-user-test',
  pattern: '*.txt',
  matchMode: 'wildcard'
});

console.log(result.data.matches);

matchMode 支持：

返回结构示例：

{
  "matches": [
    "C:\\ai-user-test\\result.txt"
  ],
  "pattern": "*.txt",
  "matchMode": "wildcard",
  "path": "C:\\ai-user-test",
  "truncated": false
}

路径安全建议

FileSystem 工具具备读写目标云电脑文件的能力。业务系统应限制可操作的目录范围，避免误读、误写系统文件或敏感目录。

建议为任务分配独立工作目录，例如：

C:/ai-use/tasks/{taskId}

使用建议

• 文本大文件建议使用 offset 和 length 分片读取。

• 写入文件前应明确 mode，避免误覆盖。

• 不建议使用 read_file 读取二进制文件。

• 对外共享文件内容或截图前应进行必要脱敏。