数据与存储

Usora 数据是本地文件。插件缓存可以删除或升级，Hub 数据应当被当作个人能力资产处理。

默认目录

当前不支持 USORA_HOME 环境变量。

目录结构

Hub schema v2 会创建这些目录：

<hub>/
├── activities/
├── candidates/
├── skills/
├── usage/
├── archive/
├── events/
├── sessions/
├── indexes/
└── backups/

<anchor>/config.json

config.json 总在固定 anchor 目录，便于先找到配置，再解析用户通过 hub_config.path 移动后的 Hub。

配置

默认配置：

{
  "maintainer": "codex",
  "automation_policy": "manual_approval",
  "hub_schema_version": 2,
  "intelligence": {
    "candidate_min_occurrences": 2
  }
}

hub_config 可修改 Maintainer、自动化策略，或传入 path 移动 Hub 数据。移动会复制既有记录、清理旧记录目录，并把新位置写入 hub_path。

查询模型

默认使用紧凑查询，减少上下文占用：

• activity_query 默认返回 digest，activity_get 才读完整 Activity。
• candidate_query 返回 Candidate 记录，可用 candidate_get 读取单条。
• skill_query 读取 metadata，skill_get 才读取 SKILL.md。
• skill_index 和 pattern_index 维护本地索引。

v2 迁移

Usora Foundry 2.0 使用 Hub schema v2。v1 Hub 不会被静默迁移。hub_status、hub_init、hub_doctor 检测到旧 schema 时会返回 migration_required，写入工具会拒绝创建新 v2 记录。

先 dry run：

hub_migrate

确认后迁移：

hub_migrate(confirm: true)

迁移会在 <hub>/backups/ 下备份，再更新 Activities、Candidates、Skills 和 config。失败时会尝试恢复备份并写入事件。

生命周期提示

hub_status.next_action 可能是 capture_activity、create_candidate、create_skill 或 review_or_cleanup。它只是下一步建议，不会自动执行。