SmolFS 实战：给 AI Agent 装上持久化工作区，让代码在不同运行轮次间无缝衔接
用过 Claude Code、Codex 或 OpenCode 的开发者都知道一个痛点：Agent 每次运行都是一个全新的沙箱环境。生成的代码、下载的依赖、中间文件——Agent 退出后全都不见了。下次再跑，又得重新下载、重新编译、重新配置。
SmolFS 正是为了解决这个问题而生。它是一个开源的持久化工作区层，让 AI Agent 的工作目录能够在进程重启后仍然可用。本文带你从安装到实战，完整掌握 SmolFS。
什么是 SmolFS？
SmolFS（Small File System）是由 Celesto AI 团队开发的一个 CLI + SDK 工具，它为 AI Agent 提供持久化工作区文件夹。核心特性包括：
- CLI 生命周期管理：
doctor→init→mount→flush→unmount一条命令链完成全流程 - 本地开发模式：基于 SQLite 元数据 + 本地对象文件，零依赖启动
- 云端模式：Redis 元数据 + S3 对象存储，跨机器共享工作区
- Python SDK 和 TypeScript SDK：直接在 Agent 代码中调用，无需 shell 命令
- Apache 2.0 开源许可
快速安装
SmolFS 的安装非常简单，一行命令即可：
curl -fsSL https://raw.githubusercontent.com/CelestoAI/smolfs/main/scripts/install.sh | sh
安装完成后，运行 doctor 检查环境是否就绪：
smolfs doctor
如果环境缺少必要的挂载支持，可以用 --install 参数自动安装：
smolfs doctor --install
doctor 命令会检查两项内容：SmolFS 托管存储后端是否已安装、当前机器是否支持目录挂载。两条都通过后，就可以开始使用了。
CLI 实战：本地持久化工作区
1. 创建本地卷
卷（Volume）是 SmolFS 的核心概念——一个命名的持久化工作区。使用 --dev 创建本地卷：
smolfs init demo --dev
这个命令会在 ~/.smolfs/ 下创建一个 SQLite 数据库管理文件和元数据，以及本地对象文件存储目录。
2. 挂载工作区
smolfs mount demo ./workspace
现在 ./workspace 就是一个普通的目录了。你可以向里面写入任何内容：
echo "Hello from SmolFS" > ./workspace/hello.txt git clone https://github.com/example/project ./workspace/my-project pip install -r ./workspace/my-project/requirements.txt
3. 主动刷盘
SmolFS 使用缓冲写入机制，建议在关键操作后主动调用 flush：
smolfs flush demo
4. 卸载卷
Agent 任务完成后，卸载卷：
smolfs unmount demo
5. 重新挂载——关键验证
退出当前进程，新开一个终端，再次挂载同一个卷：
smolfs mount demo ./workspace cat ./workspace/hello.txt
数据完好无损！这就是持久化工作区的核心价值——Agent 进程退出后，工作目录的内容不会丢失。
云端模式：跨机器共享工作区
当同一个工作区需要在不同机器上使用时，使用云端模式。需要配置 Redis 作为元数据存储，S3 作为对象存储：
smolfs init agent-workspace \ --metadata redis://user:password@redis-host:6379/1 \ --storage s3 \ --bucket https://my-bucket.s3.us-east-2.amazonaws.com
之后 mount 和 unmount 的操作与本地模式一致，但数据会同步到远端存储，可以从另一台机器上挂载同一个卷。
Python SDK：从 Agent 代码中调用
如果你的 Agent 框架支持 Python 工具调用，使用 Python SDK 更加方便：
from pathlib import Path
from smolfs import SmolFS, doctor
report = doctor()
if not report["storage_backend"]["found"] or not report["mount_support"]["found"]:
raise RuntimeError(f"SmolFS not ready: {report}")
fs = SmolFS.from_env()
volume = fs.ensure_volume("demo", dev=True)
mount = fs.mount(volume.name, "./workspace")
workspace = Path(mount.mountpoint)
(workspace / "output.json").write_text('{"status": "done", "result": "success"}')
fs.flush(volume.name)
fs.unmount(volume.name)
TypeScript SDK
TypeScript SDK 可以在 Node.js Agent 运行时中使用：
import { SmolFS, doctor } from "@celestoai/smolfs";
import { writeFile } from "node:fs/promises";
import { join } from "node:path";
const report = doctor();
if (!report.storageBackend.found || !report.mountSupport.found) {
throw new Error(`SmolFS is not ready: ${JSON.stringify(report)}`);
}
const fs = SmolFS.fromEnv();
const volume = fs.ensureVolume({ name: "demo", dev: true });
const mount = fs.mount({ name: volume.name, path: "./workspace" });
try {
await writeFile(join(mount.mountpoint, "hello.txt"), "hello from SmolFS\n");
fs.flush(volume.name);
} finally {
fs.unmount(volume.name);
}
实战场景：AI Agent 代码生成工作流
下面是一个完整的实战场景——让 Claude Code 通过 SmolFS 实现跨轮次代码生成：
第一轮：Agent 生成代码并保存到 SmolFS 工作区
smolfs init project-alpha --dev smolfs mount project-alpha ./workspace cd ./workspace npm create vite@latest my-app -- --template react-ts cd my-app npm install npm run build cd .. smolfs flush project-alpha smolfs unmount project-alpha
第二轮：使用同一个工作区继续开发（可能几小时后）
smolfs mount project-alpha ./workspace cd ./workspace/my-app code src/App.tsx cd ../.. smolfs flush project-alpha smolfs unmount project-alpha
第三轮：部署构建产物
smolfs mount project-alpha ./workspace cd ./workspace/my-app npm run build smolfs flush project-alpha smolfs unmount project-alpha
这个工作流的优势在于：每一轮 Agent 都能看到上一轮的完整上下文，不需要重新加载依赖、重新配置项目。对于需要多次迭代的复杂项目，这可以节省大量时间。
最佳实践
- 频繁 flush：关键操作（git commit、build、部署）后及时调用
smolfs flush，防止数据丢失 - 合理命名卷：将卷名与项目名一一对应，避免跨项目数据混乱
- 本地开发用
--dev：不需要云端存储时始终使用本地模式，简单可靠延迟低 - 生产环境用显式配置：云端卷的 Redis 和 S3 配置使用环境变量或配置文件，不要硬编码凭据
- 搭配 CI/CD 使用：在 CI 流水线中挂载云端卷，让流水线可以复用上次的构建缓存
总结
SmolFS 解决了 AI Agent 生态系统中的一个基础痛点——工作区的持久性。通过简单的 CLI 命令和使用 Python/TypeScript SDK，开发者可以让 Agent 的工作目录跨越进程边界，实现真正的持久化开发体验。无论是本地原型验证，还是云端生产部署，SmolFS 都能显著提升 Agent 开发工作流的效率和连贯性。
相关链接