本地文件与 Relay

让 Agent 创建工作区

workspace_create 使用 source: {"kind":"relay","rootAlias":"project"} 和唯一 idempotencyKey。工作区先进入 AWAITING_INPUT，此时尚未启动容器。

在服务仓库中安装固定工具后，本机运行：

zig build relay -- connect --workspace <workspaceId> --root /path/to/project --read-only

凭据从本机环境变量 MOGICK_SANDBOX_API_KEY 读取。命令展示真实目录和持久化说明， 确认后才连接；无交互使用需要显式 --yes。--origin 可指定同一服务的其他 HTTPS 地址。 也可在安装此仓库工作区依赖后运行 libs/ts/relay/bin.mjs relay connect。

连接器只向外连接 Cloudflare，不需要本地开放公网端口。支持 macOS/Linux 和 Python 3。 禁止导出整个家目录或根目录；默认排除 .git、.env*、凭据目录及私钥。 文件名排除不能识别业务文件内部的所有敏感信息，批准前应检查目录内容。

读取与导入

Agent 使用 relay_status 获取 sessionId 和 manifest revision，然后调用 relay_list、relay_stat、relay_read。列表每页100个文件；文件内容按Base64分块返回。 relay_materialize 指定 sessionId、manifestRevision、可选 paths 和幂等键，返回 operationId。 等待 operation 成功后，在普通 Linux 路径中执行任务。

首次导入位于 /workspace/project。后续导入进入其下新的 imports/<operationId>， operation结果返回相对目标目录。已有云端改动不会被覆盖。本地源文件不会被云端修改。 本地变化后重新运行连接器，批准新版本；不支持实时同步或自动回写。

单文件最多20 MiB，全部工作文件最多200 MiB、2000个文件，manifest最多2 MiB。 单个读取块最多256 KiB，物化时只能有一个工作区写操作；取消使用 operation_cancel。

缓存、离线与撤销

live 是默认模式，要求连接器在线；读取会验证源文件版本，变化返回 STALE_INPUT。 完整校验后的文件在私有R2中按内容哈希复用，默认缓存24小时。 显式 mode: "snapshot" 及 manifestRevision 可在本机离线后读取或导入完整缓存， 缓存不完整返回 CACHE_MISS。未缓存的实时输入离线时返回 RELAY_OFFLINE。

断线后可重新运行连接命令，重新批准目录。每次连接使用一次性凭据，旧连接响应不会进入新请求。 授权最长8小时且不超过来源Token；撤销Token、禁用用户或 relay_revoke 均阻断后续读取。 Dashboard工作区详情也能撤销本地读取授权。撤销不会删除已经传入的工作区、保存点或产物。

已导入并保存的副本可以在本地离线时恢复。恢复不复活旧连接授权；需要继续读取本机时重新连接。 Cloudflare终止WSS并处理输入内容，方案不提供对云厂商不可见的端到端加密。