Hermes 文件结构
本文描述 Hermes Agent 在 /opt/data 下的文件行为。不提供映射建议或迁移策略。
初始状态：空 volume 首次启动
Hermes 入口脚本检测到空 /opt/data 后自动写入以下默认文件。非空则跳过。
| 路径 | 写入者 | 说明 |
|---|---|---|
/opt/data/config.yaml | 入口脚本 | 全量默认配置 |
/opt/data/.env | 入口脚本 | 环境变量模板（空占位符） |
/opt/data/auth.json | 入口脚本 | OAuth 模板 |
/opt/data/SOUL.md | 入口脚本 | 人格提示词模板 |
/opt/data/sessions/ | Hermes 核心 | 对话历史目录 |
/opt/data/memories/ | Memory 模块 | 持久记忆目录（早期版本） |
/opt/data/memory_store.db | Holographic Memory | SQLite 记忆库（新版本，有 .db-shm .db-wal） |
/opt/data/skills/ | 入口脚本 | 内置 skill 副本及元数据（.bundled_manifest .curator_state .usage.json） |
/opt/data/state.db | Session 模块 | 会话索引（有 .db-shm .db-wal） |
/opt/data/response_store.db | Response 缓存 | 响应缓存（有 .db-shm .db-wal） |
/opt/data/cron/jobs.json | Cron 模块 | 定时任务定义 |
/opt/data/cron/output/ | Cron 模块 | 作业输出按 job_id/ 分目录存放 |
/opt/data/cron/.tick.lock | Cron 模块 | 调度锁 |
/opt/data/logs/ | Logging 模块 | 自动轮转日志 |
/opt/data/kanban.db | Kanban 模块 | 看板数据库 |
/opt/data/channel_directory.json | Gateway | 频道 ID 映射 |
/opt/data/gateway_state.json | Gateway | 接入层状态 |
运行时新增路径
以下路径在使用过程中自动出现，归因于具体功能被触发：
| 路径 | 触发条件 | 说明 |
|---|---|---|
/opt/data/workspace/ | Workspace 功能首次使用 | 工作区目录 |
/opt/data/plans/ | Plan 功能首次使用 | 计划文件 |
/opt/data/platforms/ | 平台配置首次生成 | 平台适配 |
/opt/data/plugins/ | 插件机制首次使用 | 插件目录 |
/opt/data/research/ | Research 功能首次使用 | 调研结果缓存 |
/opt/data/sandboxes/ | 沙盒首次使用 | 隔离执行环境 |
/opt/data/scripts/ | 用户脚本存放 | 可执行脚本 |
/opt/data/skins/ | 皮肤切换首次使用 | 界面皮肤 |
/opt/data/hooks/ | 事件钩子首次注册 | Hook 定义 |
/opt/data/processes.json | 后台进程模块使用 | 进程追踪 |
/opt/data/auth.lock | 认证流程运行时 | 认证锁 |
/opt/data/.restart_last_processed.json | 重启检测 | 上次重启处理记录 |
/opt/data/.hermes_history | CLI 使用 | 命令历史 |
/opt/data/home/ | 容器用户目录 | 用户 HOME（内含多个子目录） |
注： 上述路径中，只有 sessions/ memories/ skills/ logs/ cron/jobs.json state.db 是入口脚本在空 volume 上首次启动时创建的。其余是在对应功能触发后由 Hermes 模块自动创建。
/opt/data/home/ 内部
容器内 $HOME 指向 /opt/data/home/。以下内容由不同模块或用户操作产生：
| 路径 | 来源 |
|---|---|
/opt/data/home/www/ | 用户建立（默认无） |
/opt/data/home/scripts/ | 用户放置（默认无） |
/opt/data/home/bin/ | 用户放置（gbrain 等工具） |
/opt/data/home/.bashrc | Bash 自动生成 |
/opt/data/home/.profile | Bash 自动生成 |
/opt/data/home/.gitconfig | 用户配置 |
/opt/data/home/.config/ | 各种工具写入 |
/opt/data/home/trilium-mcp/ | 用户安装 MCP 服务器 |
/opt/data/home/gbrain/ | gbrain 安装包 |
/opt/data/home/.gbrain/ | gbrain 数据库 + 索引 |
/opt/data/home/.gbrain.backup-*/ | gbrain 自动备份 |
/opt/data/home/.pinchtab/ | PinchTab 自建状态目录 |
/opt/data/home/.bun/ | Bun 缓存 |
/opt/data/home/bun-new/ | Bun 安装包 |
/opt/data/home/.cache/ | 运行时缓存 |
/opt/data/home/.local/ | pip install 本地包 |
/opt/data/home/.npm/ | npm 缓存 |
运行时产物（容器重启重建）
| 路径 | 来源 |
|---|---|
/opt/data/cache/ | 模型目录缓存 |
/opt/data/bin/tirith | 安全扫描器 |
/opt/data/.local/ | pip 包 |
/opt/data/models_*_cache.json | 模型探勘缓存 |
/opt/data/ollama_*_cache.json | Ollama 模型缓存 |
/opt/data/gateway.lock | 进程锁 |
/opt/data/gateway.pid | 进程 PID |
/opt/data/interrupt_debug.log | 中断调试日志 |
*.db-shm / *.db-wal | SQLite WAL 日志 |
/opt/data/home/.cache/ | 用户级缓存 |
/opt/data/home/.local/ | 用户级 pip 包 |
/opt/data/home/.npm/ | npm 缓存 |
/opt/data/home/.bun/ | Bun 缓存 |
路径引用审计
仅由 Hermes 原生创建的路径
空 volume 首次启动时入口脚本创建：config.yaml .env auth.json SOUL.md sessions/ memories/ skills/ state.db
使用过程中 Hermes 模块自动创建：workspace/ plans/ platforms/ plugins/ research/ sandboxes/ scripts/ skins/ hooks/ cron/output/ cron/.tick.lock memory_store.db response_store.db processes.json gateway_state.json channel_directory.json auth.lock .hermes_history .restart_last_processed.json
不会自动产生的路径（需用户手动创建或安装工具才出现）：
/opt/data/mcp/— 无原生 MCP_HOME，用户安装 MCP 服务器时自行决定路径/opt/data/tools/— 无原生 TOOLS_HOME，用户安装工具时自行决定/opt/data/home/cron/— 无原生 cron 脚本目录，用户自行创建或由安装脚本创建/opt/data/home/www/— 用户建项目时创建/opt/data/home/trilium-mcp/— 用户安装/opt/data/home/gbrain/— 用户安装 gbrain/opt/data/home/.pinchtab/— PinchTab 首次 invoker 自建/opt/data/home/.gbrain/— gbrain 首次使用自建/opt/data/home/.gbrain.backup-*/— gbrain curator 备份
当前环境中的上下文依赖路径
| 位置 | 写法 | 问题 | 建议改为 |
|---|---|---|---|
config.yaml → pinchtab.command |
/www/kc-ai-hermes/pinchtab/... |
依赖 /www 存在，该目录属外部映射 |
/opt/data/home/.pinchtab/... 或安装到 /opt/data/home 内 |
cron/run.sh SCRIPT_DIR |
$(dirname "$0") |
解析值取决于启动 CWD 和脚本位置 | 硬编码 CRON_HOME="/opt/data/home/cron"（前提是脚本搬到此路径） |
cron jobs.json script |
hermes-cron-master.sh |
相对 ~/.hermes/scripts/ 解析；当前为 symlink 指向 /www/kc-ai-hermes/cron/run.sh |
将脚本复制到 ~/.hermes/scripts/ 内，或使用 no_agent 脚本的绝对路径（当前 cron 系统不支持） |
skills/external_dirs |
/opt/data/skills |
✅ 绝对路径，无问题 | — |
trilium-mcp.command |
/opt/data/home/trilium-mcp/dist/index.js |
✅ 绝对路径，无问题 | — |
文件来源对照
| 写入者 | 写入路径 |
|---|---|
| 入口脚本（空 volume） | config.yaml .env auth.json SOUL.md sessions/ memories/ skills/ state.db |
| Hermes 核心 | sessions/{session_id}.jsonl memories/MEMORY.md memories/USER.md state.db |
| Holographic Memory | memory_store.db (+ shm, wal) |
| Response 缓存 | response_store.db (+ shm, wal) |
| Gateway | channel_directory.json gateway_state.json gateway.lock gateway.pid |
| Cron 模块 | cron/jobs.json cron/output/{job_id}/ cron/.tick.lock |
| Kanban 模块 | kanban.db |
| Logging 模块 | logs/ (自动轮转) |
| Workspace 模块 | workspace/ |
| Plan 模块 | plans/ |
| Plugin 系统 | plugins/ |
| Research 模块 | research/ |
| Sandbox 系统 | sandboxes/ |
| Hook 系统 | hooks/ |
| 后台进程模块 | processes.json |
| 认证模块 | auth.lock |
| CLI 模块 | .hermes_history |
| 重启检测 | .restart_last_processed.json |
| Skill Curator | skills/.curator_state skills/.curator_backups/ skills/.usage.json |
| 运行时（重启重建） | cache/ bin/ .local/ models_*_cache.json ollama_*_cache.json interrupt_debug.log |
| Bash | home/.bashrc home/.profile |
| gbrain 工具 | home/gbrain/ home/bin/gbrain home/.gbrain/ |
| PinchTab 工具 | home/.pinchtab/ home/.pinchtab/config.json |
| 用户手动安装 | home/trilium-mcp/ home/www/ home/scripts/ |
| npm/Bun/pip | home/.npm/ home/.bun/ home/.cache/ home/.local/ |
— 本文档由 Hermes Agent 维护于 Trilium（审计 v3）