EmperorClaw 存储与 Google Drive 镜像

两层结构，同一个文件

每个被跟踪的文件，其内容存放在所配置的存储后端中，持久的元数据则存放在 PostgreSQL 中：标题、文件名、内容类型、归属、客户或项目范围、可见性、校验和以及生命周期信息。数据库负责回答“谁能看到这个文件、它属于什么”；存储目录树则让普通工具也能直接使用这些文件。

数据库始终是权威来源

把文件复制到存储卷里，并不会悄悄地授予访问权限或生成业务元数据。发现和导入都必须显式进行。

真实的文件系统目录

从 0.8.0 版本起，逻辑目录会镜像到文件系统的目录结构中。已有的 artifact ID 和 API 路由保持不变。增量迁移会记录镜像状态，而对齐（reconciliation）命令会把旧的扁平存储对象安全地移动到对应的逻辑路径。

# Preview changes first
docker compose exec app npm run storage:reconcile

# Apply after reviewing the report
docker compose exec app npm run storage:reconcile -- --apply

请在数据库迁移之后、启用 Drive 镜像之前运行对齐命令。它是幂等的：重复运行只会校验已完成的工作，而不会复制出重复文件。

在 EmperorClaw 中创建和编辑文件

存储模块可以创建空白的 DOCX、XLSX、CSV、Markdown、JSON 和文本文件。DOCX 和 XLSX 编辑器只在需要时才加载，并通过同一套 artifact 替换流程保存，从而保留元数据并更新校验和。CSV、Markdown、JSON 和文本文件则使用轻量编辑器。

请通过 EmperorClaw 重命名、移动和删除文件，这样数据库、本地路径和 Drive 镜像会一起变更。由 Emperor 发起的删除会被持久地排队，并发送到 Google Drive 回收站。直接在 Drive 中删除某个文件，绝不会删除 EmperorClaw 中的权威副本。

可选的 Google Drive 镜像

官方支持的自托管方案使用可选的 drive Compose profile。一个 rclone 边车容器（sidecar）挂载与应用相同的存储卷，并频繁地与一个专用的 Drive 文件夹同步。EmperorClaw 内部不运行任何 Google OAuth 代码。

# Configure the dedicated Drive remote once
docker compose --profile drive-setup run --rm drive-config

# Start the application and mirror
docker compose --profile drive up -d

请使用专用的 Google OAuth 客户端和专用的远程文件夹。不要把镜像指向整个个人 Drive。具体的环境变量和 OAuth 流程记录在仓库的自托管指南中。

直接添加到 Drive 中的文件

编辑过的已跟踪文件会同步回来，并在 EmperorClaw 中显示为已更新。直接上传到 Drive 的全新文件会显示为未跟踪候选文件：它会在存储页面中带问号显示，但尚未被索引，也不会通过 artifact API 暴露。

选择 Add metadata（添加元数据），确认其名称、目录、客户或项目、可见性以及其他元数据，然后导入。在完成这一显式步骤之前，智能体不应把该文件视为可信的公司上下文。如果它是旧版边车遗留下来的过期副本，请选择 Remove from storage and Drive（从存储和 Drive 中移除）；如果该路径中包含仍在使用的已跟踪数据，EmperorClaw 会拒绝执行此操作。

冲突不等于版本控制

文件系统镜像便于编辑，也多了一份副本，但它并不是完整的备份策略。同时编辑可能产生冲突，大文件的传输也需要时间。EmperorClaw 发起的删除会进入 Drive 回收站，在清空回收站之前都可以恢复。请把数据库和存储一起备份，并演练恢复。

同一时间只在一个地方编辑已跟踪的文件。
同步间隔尽量短，但要留出时间让传输完成。
导入之前先审查未跟踪候选文件。
把 PostgreSQL 和存储卷作为一个整体进行备份和恢复。
进行大规模存储维护时暂停镜像。