工作区不是数据库；它是坚决不把自己变成飞机的空中交通管制员。
1. 动机
数据应用经常长出一个提供商全局注册表、另一个插件注册表，再加第三套悄悄决定有哪些内置项的导入。这样一来，检查会导入代码，外部包成为二等公民，两个工作区也可能意外共享机器状态。 HeavenBase 0.1.2.1 使用一个标准库注册表 (Registry) 内核、一个上下文 (Context) 所有者与一套模块文件夹协议。内置和外部记录遵循同一套安装、检查、解析、验证与生命周期路径。工作区只协调属于该应用边界的模式、后端、路由、数据行与工具。 这很重要，因为扩展来源应回答「这条记录来自哪里？」，而不是「哪条特权分支会执行它？」2. 保持精简的公共心智模型
多数应用只需要一次导入、一个工作区，以及从查询结果显式退出：HeavenBase(...) 会创建缺失的持久工作区，或以兼容方式重新打开它。register() 建立模式；普通行 CRUD 不会把创建模式作为副作用。查询变换返回新的不可变值，execute() 重新计算，rows() 则显式跨过 ResultFrame 传输边界。
3. 看清三个所有权边界
- 上下文 (Context) 拥有机器配置、Registry 存储、模块解析与活跃工作区身份。
- ModuleService 拥有声明式记录、精确
meta.yaml发现、已验证本地制品、检查、解析与生命周期。 - 工作区 (Workspace) 拥有应用模式、后端实例、放置、查询路由、数据行、固定元数据实体、已启用扩展与智能体工具。
hb.DEFAULT_CONTEXT 是未绑定调用的便利入口。显式构造的 Context 仍然是其工作区内每一次嵌套查找的权威。
4. 理解工作区基础
Catalog 与 MetaSchema 是固定的工作区基础实体。它们不是可替换的扩展内容。Catalog 描述具体对象；MetaSchema 投影安全的模式、放置、扩展与 Registry 支持元数据以供检查。
Capsule 是必需扩展根，因为 Toolkit 通过 Capsule 行持久化可调用引用。Toolkit 与 Prompt 是打包默认根。Agent、Memory 与 Database 是可选根。工作区会快照请求的可选根，并在重新打开时重新计算精确的 Extension.requires 依赖。
5. 跟随数据从含义走向存储
Entity 类会编译成隔离的 EntitySchema。注册把每个字段编写的存储规则与已安装放置 profile、工作区命名后端一起解析。结果是一份规范存储计划。
写入会物化并验证逻辑行，按后端分组物理片段，再执行行操作。读取沿相反路线进行，并按稳定 object_id 合并片段。成功的非基础写入会在数据变更后发布 Catalog 行。
查询遵循相同的所有权方向：
Query.explain() 会报告所选的原生、适配器、扫描、回退或不支持路线。
6. 在代码之前把模块视为数据
每个内置或外部内聚模块文件夹都使用一个精确的meta.yaml。其中的项目可以声明实体、扩展、后端类型、处理器、操作、归约器、策略、逻辑类型、Toolkit family、MCP profile、序列化器、标签或其他注册角色。
meta.tags 中；可选标签定义会添加诊断，却不会封闭词汇。
本地 source: path 模块在安装时会被捕获为不可变的内容寻址制品。远程获取、签名与生态系统信任仍是未来工作。
7. 把查询与结果保持为值
这里没有可变的QueryBuilder。每个查询方法都返回新的 hb.Query，因此分支只是普通赋值：
execute() 都返回新分离的 hb.ResultFrame。使用 rows()、scalar()、to_pandas()、to_pyarrow()、to_numpy()、to_pydantic() 或 to_daft() 显式选择消费边界。
一个工作区可以把查询路由到多个后端，但独立提供商不会因此成为分布式事务。当提供商无法证明等价的原生语义时，便携扫描或归约执行是有意选择。
8. 找到当前源码所有者
已退役的
heavenbase.registry、heavenbase.storage、heavenbase.handlers、heavenbase.frame 与 heavenbase.discovery 包不是兼容界面。
9. 保持架构不变量
- 通过 Registry 记录与共享模块协议添加开放扩展，不要添加中央提供商分支。
- 需要隔离时保持 Context 所有权显式；不要在已绑定工作区内部回退到环境默认值。
- 在 CRUD 前注册模式，并让行操作远离隐藏的模式生命周期。
- 把标签视为描述性元数据，把
explain()视为具体执行证据。 - 让 CLI、仪表盘、MCP 与其他界面保持为所有者 API 之上的薄层。
- 把已安装可执行模块、Capsule、pickle 数据与本地制品视为可信代码或可信本地数据。
摘要
- Context、工作区与模块所有权保持显式。
- Registry 记录先是数据，之后才导入实现。
- Query 值、执行计划与 detached frame 让边界可检查。