Cell 管理

Cell 是 wesclaw 中数据隔离和 AI 运行的基本单元。本文介绍 Cell 的概念、温度管理、导出导入和多 Cell 场景。

Cell 概念说明

什么是 Cell

Cell 是一个完整、独立、可移植的 AI Agent 运行时。可以把它理解为一个"AI 工作空间"，包含了 AI 运行所需的全部数据和配置：

Cell 与用户的关系

部署形态Cell 数量说明
桌面版（默认）1 个（main）个人使用，所有数据在一个 Cell 中
桌面版（多 Profile）多个工作/私人分离，每个 Profile 一个 Cell
SaaS 云端版每用户 1 个由平台自动管理

单 Cell 模式（默认）

对于大多数个人用户，wesclaw 默认创建一个名为 main 的 Cell。你不需要了解 Cell 的细节，一切开箱即用：

Cell 的物理结构

每个 Cell 在数据目录下有独立的文件夹：

$DATA_DIR/cells/main/
├── meta.db        # Cell 元数据
├── sessions.db    # 对话和消息
├── state.db       # 运行状态和追踪
├── skills/        # 已安装的技能包
├── knowledge/     # 知识库文件
├── workspace/     # AI 产出的文件
├── .scratch/      # 临时计算（Run 结束后自动清理）
└── .plans/        # Plan 产物

温度管理

什么是温度

Cell 有四种温度状态，表示其资源占用和激活程度：

温度状态资源占用激活成本
🔴 Hot有活跃 Run 正在执行高（CPU + 内存 + DB 连接）0
🟡 Warm无活跃 Run，但 goroutine 和 DB 连接保持中（内存 + DB 连接）0
🔵 Cool磁盘保留，无 goroutine低（仅磁盘）100-500ms
⚫ Cold已停止无1-3s

温度转换

Hot → Warm：Run 结束后
Warm → Cool：空闲 15 分钟后自动降温
Cool → Cold：空闲数天后（可配置）

温度对用户的影响

温度发送消息的体验
Hot/Warm立即响应
Cool有约 100-500ms 的短暂预热延迟
Cold首次请求返回"正在启动"，约 1-3 秒后自动就绪

为什么需要降温

对于单 Cell 的个人用户，温度管理是自动的，你通常不需要关注。多 Cell 场景下温度管理更有意义。

Cell 导出 / 导入

导出 Cell

Cell 导出会将整个 Cell 打包为一个 .tar.gz 文件，包含所有数据：

操作步骤：

  1. 打开 设置 → 数据管理
  2. 点击 导出数据
  3. 选择保存位置
  4. 等待导出完成

导出包含的内容：

数据包含
对话历史✅
记忆✅
Agent 配置✅
技能包✅
知识库✅
运行追踪✅
AI 产出的文件（workspace）✅（默认包含，可排除）
临时文件（.scratch）❌（永不包含）

导出特点：

导入 Cell

从备份文件恢复 Cell 数据：

操作步骤：

  1. 打开 设置 → 数据管理
  2. 点击 导入数据
  3. 选择之前导出的 .tar.gz 文件
  4. 确认导入（现有数据会被替换）
  5. 等待导入完成

注意事项：

命令行操作（高级）

通过 API 也可以执行 Cell 导出/导入：

# 导出
GET /admin/cells/main/export
# 返回 tar.gz 流

# 导入
POST /admin/cells/import
Content-Type: application/gzip
# 请求体：tar.gz 文件内容

多 Cell 场景

Profile 模式（计划功能）

wesclaw 支持创建多个 Profile，每个 Profile 对应一个独立的 Cell：

ProfileCellID用途
默认main日常使用
工作profile-work工作相关的对话和记忆
私人profile-personal个人事务

Profile 的隔离性

不同 Profile 之间完全隔离：

数据是否共享
对话历史❌ 独立
记忆❌ 独立
Agent❌ 独立
技能❌ 独立
知识库❌ 独立
Provider 配置❌ 独立
登录凭证✅ 共享

切换 Profile

切换 Profile 时：

切换 Profile 不需要重启应用。

创建新 Profile

设置 → Profile 管理 → 新建 Profile

新 Profile 从空白开始，你也可以：

多 Cell 的数据目录结构

多 Cell 场景下，数据目录结构如下：

$DATA_DIR/
├── hypervisor.db          # Hypervisor 管理所有 Cell 的注册信息
├── secrets/
│   └── spec.key           # Cell 配置加密密钥
├── cells/
│   ├── main/              # 默认 Cell
│   │   ├── meta.db
│   │   ├── sessions.db
│   │   ├── state.db
│   │   └── ...
│   ├── profile-work/      # 工作 Profile
│   │   ├── meta.db
│   │   ├── sessions.db
│   │   └── ...
│   └── profile-personal/  # 私人 Profile
│       ├── meta.db
│       ├── sessions.db
│       └── ...
├── db/
│   └── wesclaw.db         # 应用层数据（跨 Cell 共享）
└── logs/
    └── wesclaw.log

Cell 状态查看

通过 UI 查看

通过 API 查看

# 查看 Cell 状态
GET /cells/main/state

# 返回示例
{
  "id": "main",
  "temperature": "warm",
  "active_runs": 0,
  "memory_count": 156,
  "session_count": 42
}

Cell 管理注意事项

数据安全

资源管理

迁移

Cell 可以在不同设备间迁移：

  1. 在源设备导出 Cell
  2. 将 .tar.gz 文件传输到目标设备
  3. 在目标设备导入 Cell
  4. 重新配置 Provider（API Key 需要重新输入）

SaaS 版差异

SaaS 云端版本：

下一步