10. 文件与工作区

每个智能体都有自己独立的工作区 —— 一个沙箱内的文件系统,智能体可以在里面读、写、执行命令。你附加的文件去这里,智能体生成的产物存这里,你叫它克隆 repo 也会落到这里。理解工作区里有什么、怎么把东西搬进搬出 —— 大致就够你日常用了。

10.1 工作区是什么

工作区就是智能体的”电脑”。它是一个沙箱内部的目录(Docker 容器、E2B 云沙箱,或 Daytona 工作区,取决于实例怎么搭的 —— 这是运维侧的选择)。从你的座位看:

  • 按智能体划分:每个智能体有自己的。同一实例下两个智能体不共享工作区文件。
  • 跨会话共享:你在会话 A 中上传的文件,智能体在会话 B 中也能看见。
  • 持久化:文件不会因为重启、网关升级、智能体停用/启用而丢。
  • 隔离:智能体跑的代码逃不出沙箱。

智能体访问工作区用的工具是 file read、write、search 和 shell exec —— 跟任何合格工程师期望的差不多。

10.2 智能体能看到什么

在工作区里,智能体有自由的读权限。这里没有按会话隔离文件 —— 你在私聊会话里上传的文件,仍在工作区里,智能体在和别人聊天时也可能看见(取决于对方的角色和策略)。

如果你有不希望任何会话提到的敏感文件 —— 别上传,或者把它放到一个被策略明确排除的路径下。见 第 15 章 · 策略与审批。

10.3 把文件搬进来

Web UI。 把文件拖进聊天窗口。adapter 会写到工作区一个已知路径,并通知智能体。智能体回复时会按文件名引用。

Telegram / Discord / Slack。 在聊天中作为附件发。通道 adapter 做同样的事 —— 复制到工作区,告诉智能体。

CLI。 hermit chat 没有内置的上传命令。要么把文件直接放进工作区路径(运维知道这个位置),要么就这一次先用 Web UI,然后回到 CLI。

让智能体自己拉。 通常最省事:贴一个 URL,说”下载这份 PDF 然后分析它”。智能体用它的 fetch 工具(或某个 MCP 服务),文件就落到了工作区。

10.4 把文件搬出去

问智能体。 “把 report.md 的内容给我看看”,或”把 chart.png 编成 base64 贴出来” —— 小文件这样就行。

Web UI。 Web UI 通常会内联渲染产物(markdown、代码、图片)。右键保存。

通道 adapter。 让智能体把文件作为附件回发;Telegram 和 Slack adapter 支持。

直接访问沙箱。 大批量操作时,运维可以配置直接从沙箱下载;默认不是用户侧的功能。

10.5 智能体用到的工具

如果你展开一条回复的 tool calls 视图,会看到:

  • File read —— 把一份文件的内容载入上下文。
  • File write —— 创建或覆盖一份文件。
  • File search / list —— grep、glob、ls 的对应物。
  • Exec —— 在沙箱里跑一条 shell 命令。

Exec 最强大、也最受策略约束。默认 owner 和 user 有,guest 没有。敏感命令可以通过策略黑名单(见 第 15 章)。

10.6 角色差异

OwnerUserGuest
读文件✓✓—
写文件✓✓—
跑 shell 命令✓✓—
通过通道上传✓✓(取决于策略)
下载✓✓(取决于策略)

Guest 默认是”无文件工具”的体验。这样一来,面向公众的智能体(从任意 Telegram 或 Web 访客那里自动创建 guest)就不会有陌生人把文件丢到共享工作区里。

10.7 How-to 配方

10.7.1 上传一份 CSV,让智能体分析

场景 —— 你有一份销售导出,想看走势。

步骤

  1. 打开 Web UI,选智能体,把 sales-q1.csv 拖进聊天。
  2. 问:“分析一下 —— 最重要的三个走势是什么?”

智能体读文件,做分析(通常通过 exec 跑 Python),然后回复。

验证 —— 回复里能点出文件里具体的数值。

10.7.2 让智能体生成一份文件再下载

场景 —— 你想把一段长对话整理成 markdown 摘要。

步骤

把这段对话整理成 markdown 摘要,存到工作区的 summary.md。

智能体写完文件。然后两个选项:

  • 让智能体把它再读出来(“把 summary.md 给我看看”),从回复里复制。
  • 在 Web UI,打开工作区浏览器(Manage → Files,如果你的实例提供),直接下载。

10.7.3 清理工作区

场景 —— 用了几个月之后,工作区堆了一堆不再需要的文件。

步骤

问智能体:

列出工作区里超过 90 天的文件;每个简单说说用途,然后问我留还是删。

交互式过一遍。或者批量来:

删掉所有匹配 tmp_* 或 .log 的文件。

验证 —— 通过智能体或运维提供的查看器 ls 工作区。

常见问题 —— 如果智能体一直在跑某些写特定路径的脚本,删它们的工作文件可能会让脚本崩。下手前先看清楚。

10.7.4 不让 guest 访问某个路径

场景 —— 一个公开智能体的 private/ 下有点私密笔记,你不想让 guest 把它们说出来。

步骤

加一条策略:guest 角色对 private/ 下的文件操作 deny。见 第 15 章 · 策略与审批。

验证 —— 以 guest 身份登录(或换一个全新的公开身份),问智能体 private/ 下的某个文件;file read 应该被拒。

10.8 FAQ

我上传的文件落到工作区的哪里? 一般是一个已知的 uploads 路径;具体布局取决于沙箱后端。智能体知道路径,会在回复里引用。

智能体能在它的沙箱里装软件吗? 在沙箱里可以 —— apt/pip/npm 之类都好使。变更会留在那个智能体的工作区。

沙箱挂了,我的文件会丢吗? 不会。工作区背靠持久化存储;重启沙箱不会清掉它。

同实例上的两个智能体能看到彼此的文件吗? 不能。按智能体隔离。

一个智能体上的多个用户,能看到彼此的上传吗? 能。工作区按智能体划分,不按用户划分。如果你需要按用户隔离,一人一智能体。

10.9 指引