11. 目录结构与磁盘文件
数据分两处存：全局目录（与用户绑定，跨工作区共享）和工作区目录（与启动 omicos 的目录绑定）。弄清布局，排查、备份、迁移都更容易。
11.1 全局目录 ~/.omicos/
与账户 / 机器绑定，所有工作区共享。位置可用 OMICOS_LOCAL_HOME 改写。
ls ~/.omicos
预期输出：
a2a.json auth.json cloud-models memory
a2a_keys.json cloud-agents cloud_login.json oauth
active_domain cloud-skills env plan_token.jwt
| 条目 | 作用 |
|---|---|
cloud_login.json |
登录凭证的全局副本 / 回退（omicos login 默认写这里；守护进程优先读工作区本地版），权限 0600 |
auth.json |
API key 的文件回退存储（见第 12 章） |
plan_token.jwt |
订阅令牌，权限 0600，后台自动续期 |
a2a.json / a2a_keys.json |
Agent2Agent 端点配置与已签发的 API key（只存哈希）。0.3.29 之后的版本；没用过 A2A 就不会有 |
active_domain |
当前内容域，决定拉哪一套智能体 / 技能目录 |
.kernel_choice |
持久化的 kernel 解释器选择（隐藏文件，ls -a 才看得到） |
env/ |
omicos 管理的共享 Python 环境（里面是 .venv） |
memory/ |
跨对话长期记忆（.md 文件），记忆本体就在这里，不是缓存 |
cloud-agents/ cloud-skills/ cloud-models/ |
从云端同步下来的智能体 / 技能 / 模型目录缓存 |
oauth/ |
第三方 OAuth 凭证（codex.json / gemini_cli.json） |
11.2 工作区目录 <workspace>/.omicos/
与启动 omicos 的目录绑定，存放该工作区的会话、轨迹和锁。serve 默认用 .omicos，cli 自起守护进程时默认用 .omicos/cli（由 --data-dir 控制）。
ls ~/my-analysis/.omicos
预期输出（一个已登录、用过一段时间的工作区）：
account.json conversations serve.pid trajectories
cloud_login.json conversations.json settings usage
conversation_sync.state.json timeline tool_outputs
workspace_id
| 条目 | 作用 |
|---|---|
workspace_id |
持久的 32 位十六进制 id，决定云端 process_id |
serve.pid |
守护进程锁，两行：第 1 行 pid，第 2 行端口 |
cloud_login.json |
工作区本地登录凭证（守护进程优先读这里），权限 0600 |
account.json |
本地登录状态记录 |
settings/ |
本工作区的模型 / provider 配置 |
conversations/ |
会话内容，每个会话一个目录（含 meta.json、history.jsonl、outputs/、uploads/） |
conversations.json |
会话索引 |
conversation_sync.state.json |
会话同步进度记录 |
trajectories/ |
每轮分析的审计日志，见下 |
usage/ |
按 LLM 调用计的用量记录（<session>.jsonl） |
tool_outputs/ |
工具结果的溢出存储（可能有很多条） |
timeline/ |
时间线（可能为空） |
updater/ |
自动更新暂存的新版二进制（下载过才有） |
agents/ skills/ |
lab+ 订阅的本地覆盖，只在你自己创建后才存在 |
trajectories/ 内部按登录账户隔离：
ls ~/my-analysis/.omicos/trajectories
预期输出：
3e81b60c-7d24-42af-9a15-c0f5e8d31b77 anonymous
<owner_id>/—— 按登录账户 id 分目录（2026-05 起），多账户共用一个工作区文件夹也不会串。里面是一个会话一个<session_id>.jsonl，追加写入，自动同步到云端。anonymous/—— 登录之前产生的记录落在这里。登录后不会自动迁移过去：同一个目录可能被多个账户用过，无法事后判断归属。- 更早期版本留下的、直接放在
trajectories/下的散装.jsonl文件，因为没有可证明的归属，会被排除在账户范围的读取之外（可用omicos recover-conversations认领，见第 9 章）。
上面很多目录只在被用到时才出现，干净的工作区里不一定齐全。
11.3 serve 与 cli 的数据目录
| 模式 | 默认 data_dir |
|---|---|
omicos serve |
<workspace>/.omicos |
omicos cli（自己起守护进程时） |
<workspace>/.omicos/cli |
二者的会话、轨迹完全隔离、互不可见。所以网页端进程选择器里，带 (cli) 后缀的和不带后缀的是两个独立命名空间。
注意：工作区里已经有
omicos serve在跑时，omicos cli会直接连上它，此时用的是 serve 的数据目录，两边看到的是同一份历史。
11.4 几个关键文件的细节
| 文件 | 说明 |
|---|---|
workspace_id |
32 位十六进制、无连字符（不是带横线的标准 UUID 写法）。它决定云端 process_id（local-<workspace_id>），所以把工作区目录改名或搬位置，进程身份仍然稳定。切换账户遇到身份冲突时会被旋转成新值。 |
serve.pid |
两行：pid + 端口。进程正常退出会自动删除；被强杀留下的陈旧锁，下次启动时会检测到持有者已不在并自动回收。 |
cloud_login.json |
守护进程优先读工作区本地这份，全局那份作回退。删掉它等于该工作区登出。权限 0600，切勿外泄。 |
.kernel_choice |
记录你选定的 kernel 解释器，优先级高于 OMICOS_KERNEL_PYTHON。设了环境变量却没生效时先查它（见第 4 章）。 |
11.5 用变量改写位置
| 变量 / 参数 | 改写什么 |
|---|---|
OMICOS_LOCAL_HOME |
全局目录（凭证、env/、缓存等）的根位置 |
OMICOS_USER_HOME |
「每用户一份」的全局根，给多工作区启动器用；不设时跟随上面那个 |
OMICOS_WORKSPACE_ROOT |
工作区根（会话 / 轨迹的存放位置） |
--data-dir |
工作区数据目录（默认 <workspace>/.omicos） |
11.6 备份与迁移建议
- 要备份的：
~/.omicos/memory/（长期记忆）、各工作区的conversations/和trajectories/。 - 不必备份的：
cloud-agents/cloud-skills/cloud-models/（会从云端重新同步）、env/（可用omicos env setup重建）、updater/、tool_outputs/。 - 绝不外泄的：
cloud_login.json、auth.json、plan_token.jwt、a2a_keys.json、oauth/。