数据、安全与恢复
Scientific Agent 默认把研究数据保存在本机。数据、缓存和应用配置分开存放，便于备份重要结果，同时安全地清理可再生成内容。
默认位置
研究数据默认都在 ~/Documents/ScientificAgent。缓存和配置按平台放置：
| 平台 | 缓存 | 配置 |
|---|---|---|
| Linux | $XDG_CACHE_HOME/scientific-agent，未设置时为 ~/.cache/scientific-agent |
$XDG_CONFIG_HOME/scientific-agent，未设置时为 ~/.config/scientific-agent |
| macOS | ~/Library/Caches/ScientificAgent |
~/Library/Application Support/ScientificAgent |
| Windows | %LOCALAPPDATA%\ScientificAgent\Cache |
%APPDATA%\ScientificAgent |
CLI 可显式覆盖：
scientific-agent \
--data-dir /data/my-study \
--cache-dir /scratch/scientific-agent-cache \
--config-dir /data/my-settings \
status RUN_ID
三个全局选项必须出现在子命令之前。
数据目录中有什么
主要目录包括：
| 目录 | 内容 |
|---|---|
runs/ |
每次运行的合同、事件、状态、工作区、日志和交互记录 |
artifacts/ |
跨运行或应用级产物存储 |
models/ |
最终模型和模型相关交付物 |
reports/ |
报告数据 |
exports/ |
科学导出和 Runtime 备份 |
单个运行目录通常包含 events/、artifacts/、workspace/、logs/、interactions/ 和 state/。这些是内部布局；请通过桌面端、CLI 或 Control API 读取，不要手工编辑。
为什么事件和产物都要保存
- 事件记录“发生了什么”：运行状态、动作、预算、人工介入和完成决定。
- 产物记录“依据是什么”：输入、数据、代码、预测、评估、分析和报告。
- 投影视图把两者组合成控制室、时间线和谱系。
启动、恢复或查看旧运行时，Runtime 会从事件重放研究状态。产物带有 SHA-256 摘要；读取时会校验内容，避免文件被替换后仍被当作原始证据。
因此，手工修改 events.jsonl、state 文件或产物内容会破坏可恢复性和审计链。要修正研究，应创建新运行或通过支持的介入命令留下新记录。
移动数据目录
桌面端 Settings → Storage 会显示当前目录、大小和可用空间，并支持选择新位置。迁移前：
- 暂停或结束所有运行。
- 创建 Runtime 备份。
- 选择有足够空间且能持续挂载的位置。
- 完成移动/复制后，让应用自行验证新目录。
不要在运行中用文件管理器移动目录。网络盘或同步盘可能改变原子写入和锁行为；若必须使用，先在小型 toy run 上验证暂停、恢复和产物哈希。
Runtime 备份
桌面端点击 Create backup，或使用：
curl -sS -X POST http://127.0.0.1:8000/api/v1/storage/backups | jq
备份 ZIP 位于 <data-dir>/exports/backups/，包含 runs、artifacts、models、reports 以及带每个文件摘要的 backup.json。缓存和普通配置不在备份中，因为它们不是研究事实。
备份文件仍在数据目录内部。真正的灾难恢复还需要把 ZIP 复制到另一块磁盘或受控的备份系统，并定期测试解压和摘要。
科学导出
成功运行可以生成面向审阅者的科学导出。它会选择最终报告、模型/推理文件和必要元数据，保存在 exports/ 下。
导出适合论文附件、同事复核和部署交接；它不是所有历史运行的镜像。需要完整恢复时使用 Runtime 备份。
中断与恢复
应用或机器异常退出后，运行通常显示 INTERRUPTED。恢复会：
- 校验事件序列和已有产物；
- 定位安全恢复点；
- 标记未完成作业，而不是假设它已成功；
- 从保存的合同和剩余预算继续。
在控制室点击 Recover，或执行：
scientific-agent resume RUN_ID
若状态不是可恢复中断，命令会拒绝操作。先用 status RUN_ID --events 查看最后一个失败或生命周期事件。
凭据
桌面端把 provider 凭据交给操作系统凭据存储，并且不会把密钥写入研究合同、事件或模型档案。CLI 使用环境变量：
export LAB_MODEL_API_KEY="..."
scientific-agent run study.yaml
配置文件只写环境变量名，例如 auth_env: LAB_MODEL_API_KEY。不要把 .env、终端历史、带密钥的日志或配置提交到版本库。
codex-cli provider 使用本机 Codex 登录状态。它与 API key provider 是两条不同的认证路径。
Control API 与桌面安全
- Desktop 的本地 API 使用应用生成的临时令牌，并限制可接受的本地来源。
scientific-agent serve是方便开发和自动化的无认证模式；默认绑定127.0.0.1，不要改成公网地址直接暴露。- 需要远程或多用户服务时，在前面增加 TLS、认证、访问控制和请求大小限制，并使用独立系统账户运行。
- API 返回的是受控读模型，不应通过静态文件服务器直接公开数据目录。
插件与本地执行
启用的 Python 插件与应用进程拥有相同权限。ZIP 安装会阻止常见压缩包路径攻击，但不会证明插件业务代码安全。只启用可信代码。
Local Executor 限制工作区和声明的输入/输出，却不是针对恶意程序的安全沙箱。对不可信代码，应在容器、虚拟机或隔离账户中运行整个 Scientific Agent。
评估私有数据
带 evaluator_private 可见性的产物只交给受信任评估器。它们不会进入：
- Scientific Reasoner 上下文；
- 普通研究插件输入；
- 面向研究者的产物列表和 Research Flow；
- 科学导出的公开部分。
这能防止普通训练循环直接读取答案，但仍应使用文件权限和隔离账户保护底层磁盘。
删除与保留
当前界面重点提供打开、移动、备份和导出，不提供把历史事实当作普通缓存清理的工作流。需要释放空间时：
- 先生成并异地保存备份；
- 确认相关论文、报告和模型已导出；
- 关闭应用和 API 服务；
- 按明确的完整运行目录做归档或删除，不要只删其中的 events 或 artifacts。
缓存可以重新生成，研究数据通常不能。两者不要放进同一条清理命令。