Skip to main content
Catalog 负责找书;MetaSchema 负责解释为什么有一层书架在嗡嗡作响。

1. 动机

Agent 需要两种不同的发现能力。 它们既要在不了解每个 Entity 类时找到具体对象,也要检查让这些对象可查询的结构。 HeavenBase 将这两个问题分开:
  • Catalog 为具体工作区对象建立索引。
  • MetaSchema 投影安全的工作区与模块结构。
  • hb.capabilities 报告可选择的引擎选项。

2. 发现具体对象

普通用户 Entity 成功写入后,HeavenBase 会维护相应的 Catalog 行。
当类型、名称、描述或标签等宽泛属性已经足够时,请查询 Catalog:
Catalog.object_id 标识 Catalog 行。 target_entity + target_id 这一对值标识被索引的对象。

3. 还原类型化行

Catalog 是发现索引,而不是类型化 Entity 访问的替代品。 请通过工作区还原选中的结果:
当 object id 可能在不同 Entity 类型中重复时,始终保留 Entity 标识符。

4. 遵守可用性

普通发现应使用 .available(),避免把未激活、隐藏、过期与陈旧行泄露给 Agent。
stale=True 会包含陈旧行,而 invisible=True 会包含隐藏行。 硬过期行与未激活行仍然会被排除。 对应的 JSON 形式是 {"available": {"stale": true}}

5. 检查工作区结构

MetaSchema 描述 Entity、字段、存储放置、Backend、扩展与安全的 Registry 投影。
MetaSchema 用于描述,而不是安装控制平面。 它会隐藏编写的语义标签、本地路径与可执行实现细节。 MetaSchema 了解可以查询什么。 用 Catalog 找到实际对象。

6. 检查可选择能力

hb.capabilities 回答有哪些逻辑类型、存储策略、Backend 类型与操作可用。
当答案必须只反映某个工作区中的实时 Backend 实例时,请使用 ws.capabilities。 直接检查模块标签时,请使用 ws.context.modules().tag(...)

7. 审计派生行

Catalog 行派生自 Entity 行。 手动恢复 Backend 或发生部分失败后,请先审计再开放工作区:
dry_run=True 会报告修复计划,而不写入或删除 Catalog 行。

总结

  • Catalog 发现具体对象。
  • MetaSchema 描述安全的工作区结构。
  • Capabilities 报告可选择的引擎选项。
  • 类型化工作区访问仍是底层行的权威。

进一步探索

相关资源: