Catalog 负责找书;MetaSchema 负责解释为什么有一层书架在嗡嗡作响。
1. 动机
Agent 需要两种不同的发现能力。 它们既要在不了解每个 Entity 类时找到具体对象,也要检查让这些对象可查询的结构。 HeavenBase 将这两个问题分开:Catalog为具体工作区对象建立索引。MetaSchema投影安全的工作区与模块结构。hb.capabilities报告可选择的引擎选项。
2. 发现具体对象
普通用户 Entity 成功写入后,HeavenBase 会维护相应的 Catalog 行。Catalog.object_id 标识 Catalog 行。
target_entity + target_id 这一对值标识被索引的对象。
3. 还原类型化行
Catalog 是发现索引,而不是类型化 Entity 访问的替代品。 请通过工作区还原选中的结果:4. 遵守可用性
普通发现应使用.available(),避免把未激活、隐藏、过期与陈旧行泄露给 Agent。
stale=True 会包含陈旧行,而 invisible=True 会包含隐藏行。
硬过期行与未激活行仍然会被排除。
对应的 JSON 形式是 {"available": {"stale": true}}。
5. 检查工作区结构
MetaSchema 描述 Entity、字段、存储放置、Backend、扩展与安全的 Registry 投影。
MetaSchema 了解可以查询什么。
用 Catalog 找到实际对象。
6. 检查可选择能力
hb.capabilities 回答有哪些逻辑类型、存储策略、Backend 类型与操作可用。
ws.capabilities。
直接检查模块标签时,请使用 ws.context.modules().tag(...)。
7. 审计派生行
Catalog 行派生自 Entity 行。 手动恢复 Backend 或发生部分失败后,请先审计再开放工作区:dry_run=True 会报告修复计划,而不写入或删除 Catalog 行。
总结
- Catalog 发现具体对象。
- MetaSchema 描述安全的工作区结构。
- Capabilities 报告可选择的引擎选项。
- 类型化工作区访问仍是底层行的权威。

