磁盘与目录布局
本文列出 xopc 在磁盘上的主要读写位置。实际路径以 配置文件（默认 ~/.xopc/xopc.json）及环境变量（如 XOPC_CONFIG、XOPC_WORKSPACE）为准。
初始化步骤、模板说明与环境变量详见 状态目录与工作空间布局。
设计分工
| 区域 | 作用 |
|---|---|
| 状态目录 | 全局配置、凭据、日志、cron、全局 skills/extensions、托管工具链等。 |
智能体主目录 <stateDir>/agents/<agentId>/ | 按 agentId 隔离的运行时数据：会话 transcript、托管记忆、profile/ 下的 profile Markdown（SOUL.md 等）、入站/TTS 落盘、会话级配置等。 |
智能体状态目录 …/agents/<agentId>/agent/ | 进程状态：agent.json、各智能体凭据、IPC 收件箱、pid/socket、小型机器状态、扩展安装、出站崩溃恢复队列。 |
| Markdown 工作空间 | 用户项目树：工具 cwd、每日 memory/*.md、media/generated、用户 skills/、任意用户文件。 |
下文默认状态根为 ~/.xopc/；可用 XOPC_STATE_DIR、XOPC_PROFILE、XOPC_HOME 覆盖（见 workspace.md 环境变量）。
状态目录（全局）
默认：~/.xopc/
| 路径 | 用途 |
|---|---|
xopc.json | 主配置（若未用 XOPC_CONFIG / XOPC_CONFIG_PATH 指向他处）。 |
credentials/ | 全局密钥：auth-profiles.json、oauth/<provider>.json。 |
extensions/ | 已安装扩展、extensions-lock.json。 |
skills/ | 全局托管技能包（<id>/SKILL.md）。 |
cron/ | jobs.json、logs/、runs/。 |
logs/ | 应用日志（可用 XOPC_LOG_DIR 覆盖）。 |
bin/、tools/ | CLI 包装与工具运行时。 |
models.json | 可选的自定义模型注册数据。 |
智能体主目录：agents/<agentId>/
由 resolveAgentHomeDir(config, agentId) 解析。常见结构：
| 路径 | 用途 |
|---|---|
profile/ | 系统提示用 profile Markdown：SOUL.md、IDENTITY.md、USER.md、TOOLS.md、AGENTS.md、HEARTBEAT.md、MEMORY.md（与托管 memories/ 不同）、BOOTSTRAP.md（默认不注入），以及网关可选 agent-avatar.*。 |
sessions/ | 会话 transcript（分片、index.json、archive/）、sessions/config/ 下按会话配置。 |
memories/ | 托管结构化存储（MEMORY.md、USER.md，条目以固定分隔符分段 — BuiltinMemoryStore）。 |
inbound/ | 入站附件（非图片二进制）落盘；transcript 中相对路径为相对 agent home 的 inbound/...。 |
tts/ | 按会话缓存的出站 TTS 音频。 |
agent/ | 见下节 智能体状态目录。 |
种子：xopc init / xopc agents add 将缺失的 profile Markdown 模板复制到 agents/<agentId>/profile/（参见 工作区模板）。
智能体状态目录：agents/<agentId>/agent/
由 resolveAgentDir(config, agentId) 解析。
| 路径 | 用途 |
|---|---|
agent.json | 智能体运行时元数据。 |
credentials/ | 各智能体 API 配置（如使用）。 |
inbox/pending/、inbox/processed/ | 基于文件的 IPC 收件箱。 |
pid、status.json、agent.sock | 进程协调。 |
state/ | 机器状态（如 workspace 元数据、skills 扫描缓存）——不是 Markdown 工作区下的 .state/。 |
extensions/ | 各智能体扩展安装根目录。 |
outbound-pending.json | 出站消息崩溃恢复队列。 |
Markdown 工作空间
由 resolveAgentWorkspaceDir(config, agentId) 解析：未设置 agents.defaults.workspace 时常为 <stateDir>/workspace/<agentId>；设置时为 join(<agents.defaults.workspace>, <agentId>)；或由列表项 workspace 显式指定。
预期内容（用户可见 / 工具面向）：
| 路径 | 用途 |
|---|---|
memory/ | 按日或主题笔记（YYYY-MM-DD.md）；memory_search 等与工具 cwd。 |
media/generated/ | 生图等输出。 |
skills/ | 用户自建技能。 |
| 任意文件 | read / write / edit 等工具操作对象。 |
新安装不会把内部状态写回 Markdown 工作区。本版本只支持文首表格中的 单一目录树：人设 Markdown 与机器状态按上表分布；不会从「全部堆在 Markdown 工作区里」的旧布局自动迁移；完整状态树用 xopc init，或 xopc setup / xopc onboard 做配置与 profile Markdown 种子，从其它 fork 升级时需自行搬迁数据。
会话里引用的入站附件 / TTS 路径仅支持相对 inbound/、tts/（相对 agent home 解析）。
运维辅助 API
listAgentWorkspaceDirs(config)— 列出配置中各智能体的 Markdown 工作区根路径（CLI / 进阶用法）。listAgentProfileMarkdownDirs(config)— 与listAgentWorkspaceDirs相同根路径（profile Markdown 在工作区根；便于备份或外部编辑器挂载）。
另见
- 状态目录与工作空间布局 — 初始化、环境变量、模板文件说明。
- 架构设计 — 各组件如何使用上述路径。
- 会话管理 — 会话存储布局。