工作区不是数据库。它是从语义到存储的映射。
1. 最短心智模型
HeavenBase 在多个物理后端之上提供一个逻辑工作区。 你定义实体来描述数据的含义。每个实体有类型化字段，每行有一个稳定的object_id。HeavenBase 随后决定——或遵循你的显式指令——每个字段应存放何处：标量值可能进 SQL，向量进向量库，长文本进搜索，JSON 或文件进行存储。
关键是用户与 Agent 不必思考这些物理切片。他们向工作区写入、查询工作区，得到一行逻辑记录或一个 ResultFrame。HeavenBase 将物理放置、查询编译、后端执行与结果合并藏在这一表面之后。
对用户而言，模型是：
2. 核心路径
图刻意保持精简。HeavenBase 模块比这更多，但多数落在其中某条线上：定义结构、选择放置、编译操作、对接 provider，或将工作区适配到其他接口。3. 工作区即边界
HeavenBase 工作区拥有必须彼此一致的事物：
- 已注册实体
- 已配置的后端实例
- 字段级存储计划
- 操作处理器
- 用于发现与内省的系统行
hb.HeavenBase.load("shop") 背后的进程注册表让命名工作区易于复用，而工作区锁避免注册、CRUD、查询、刷新与 drop 在同一工作区对象内竞态。
4. 实体描述含义
实体是逻辑 schema。它说明「此对象有这些字段，字段有这些含义」。它本身并不规定必须存进哪个数据库。 定义hb.Entity 时，元类将类编译为 EntitySchema。字段变为 FieldSchema 记录。ShortText、LongText、Float、Date、Json、Array、HyperG、Vector 等逻辑类型拥有值契约：
validate()将用户输入转为规范 Python 值。encode()将规范值转为后端就绪的存储值。decode()将后端值转回规范值。
object_id: Identifier 主键。若未提供，HeavenBase 从配置的源字段（通常是 name）派生确定性 ID。该 object_id 是让分散的字段片段稍后重新拼合的线索。
5. 路由放置字段
路由在字段级。字段可有显式放置.store(to=..., strategy=...)，或使用其逻辑类型的默认存储配置。
默认直觉是：
- 向量优先使用带
VectorIndex的向量后端 - 长文本优先使用带
InvertedIndex的搜索后端，其次行存储 - JSON 优先使用支持 JSON 的行存储与
JsonField - 数组与
HyperG在可用时优先 SQL 侧表 - 普通标量使用内联行列
StoragePlan。计划包含有效的 StorageBinding 行：实体、字段、后端、策略与来源。后端随后收到 ensure(schema, bindings)，以便为所拥有字段准备表、索引、文件或 provider 集合。
object_id 字段特殊。HeavenBase 控制其放置，并复制到存储同一实体片段的后端，以便安全合并。
6. CRUD 扇出再合并
写入从工作区表面开始：upsert、set、delete 及其批量变体。
对 upsert，HeavenBase 先物化行：规范化 object_id、应用默认值、运行 compute Hook、通过逻辑类型校验各 present 字段，再仅编码各后端拥有的字段。写入器将这些片段分组为 RowOp 批次，并在各路由后端上调用 Backend.upsert(...)。
非系统实体写入成功后，HeavenBase 发布 Catalog 行。这使对象发现与对象 payload 分离：目录告诉 Agent 存在什么，实体行仍携带类型化数据。
读取逆转路由。get 与 get_many 向各路由后端请求 object_id，解码该后端拥有的字段，将片段合并为一行逻辑记录。若两个路由后端对同一字段不一致，HeavenBase 在正常唯一读取路径下抛出异常，而非隐藏冲突。
删除在实体行之前移除 Catalog 行，避免发现仍指向正在删除的对象。
7. 查询编译为片段
HeavenBase 接受多种查询表面，但它们汇聚于同一QuerySpec。
Python 表达式如 Product.price < 100、Mongo 风格 JSON 过滤器、向量 .near(...)、投影、排序、offset 与 limit 都规范化为该 spec。查询引擎查看 StoragePlan，对每个叶子问一个窄问题：
(logical type, operation, backend type, strategy) 注册。处理器不执行查询；它将叶子编译为 QueryFragment：SQL 的 SQLAlchemy where 子句、搜索/向量系统的 provider 查询 payload，或扫描回退的 Python 行谓词。
后端只执行片段，不解析用户查询。
当查询跨多个后端，HeavenBase 执行相关片段并按 object_id 合并 frame：AND 为交集，OR 为并集，NOT 为与实体全集的差集。向量查询遵循同一原则，near + filter 有额外规划：优先同后端组合执行、可用时重复元数据预过滤、支持时有界候选 ID 预过滤，否则后过滤合并。
最终公开值是 ResultFrame。它保留 object_id、保留后端合并的列、必要时水合缺失的逻辑字段，再应用排序、offset、limit 与投影。
8. Catalog 让工作区可观测
HeavenBase 通过system 与默认加载的 prompt 扩展发布内置元数据。每个工作区会自动启用 system。常见内置实体是：
sys-catalog（Catalog）描述具体对象：目标实体、目标object_id、name、description、tags、active 标志与工作区。sys-metaschema（MetaSchema）描述结构：工作区、后端、能力、实体、字段、存储绑定与已启用扩展。sys-prompt与sys-translation来自默认加载的prompt扩展，存储可调用提示 (Prompt) 与绑定提示 (Prompt) 的翻译。sys-capsule与sys-toolkit存储可执行 Capsule manifest 与用于 MCP 提供的工具集 (Toolkit) 引用。
Catalog 找到正确对象，检查 MetaSchema 理解实体与字段结构，再通过同一工作区运行类型化查询或 CRUD。
这是更大 HeavenBase 理念背后的小循环：结构也是数据，Agent 应能观测它。
9. 扩展接入时不改变工作区 API
HeavenBase 将扩展工作分为两层：- 实体扩展 通过
ExtensionSpec与ws.enable_extension(...)增加可选实体类型。包作者在工作区加载前用register_extension(...)注册它们。 - 开发者扩展 通过
hb.ext注册后端、处理器、存储策略、逻辑类型与查询 operation。工作区路由与 handler 播种消费这些进程全局注册表。
system 扩展是今天唯一必需的实体扩展。Capsule 与 Toolkit 属于它；Prompt 与 Translation 位于默认加载的 prompt 扩展。
自定义实体扩展发布 MetaSchema 行，并通过正常工作区路径注册实体。开发者扩展将查询叶子编译为后端执行的 QueryFragment 对象。两层都不会教后端直接解析用户查询。
10. 开发者应看哪里
若读源码，从公开路径向下：
扩展 HeavenBase 时最安全的规则，正是实现已在遵循的：通过 backend builder、存储配置与 handler 添加新物理行为。不要教后端解析
QuerySpec，也不要把新路由规则藏进 provider 代码。