> ## Documentation Index
> Fetch the complete documentation index at: https://ahvn.top/llms.txt
> Use this file to discover all available pages before exploring further.

# 架构

> HeavenBase 心智模型：工作区、实体、路由、后端、处理器与结果。

<Note>
  *工作区不是数据库。它是从语义到存储的映射。*
</Note>

<br />

## 1. 最短心智模型

HeavenBase 在多个物理后端之上提供一个逻辑工作区。

你定义**实体**来描述数据的含义。每个实体有类型化字段，每行有一个稳定的 `object_id`。HeavenBase 随后决定——或遵循你的显式指令——每个字段应存放何处：标量值可能进 SQL，向量进向量库，长文本进搜索，JSON 或文件进行存储。

关键是用户与 Agent 不必思考这些物理切片。他们向工作区写入、查询工作区，得到一行逻辑记录或一个 `ResultFrame`。HeavenBase 将物理放置、查询编译、后端执行与结果合并藏在这一表面之后。

对用户而言，模型是：

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
Workspace -> Entity -> Field placement -> Backend execution -> Logical result
```

对开发者而言，实现遵循同一形状：

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
workspace -> entity/schema/types -> storage/strategies -> handlers/backends -> frame
```

<br />

## 2. 核心路径

```mermaid placement="top-right" actions={true} theme={"theme":{"light":"github-light","dark":"github-dark"}}
flowchart TB
    Surface["Python, JSON, MCP, or CLI"] --> Workspace["HeavenBase workspace"]
    Workspace --> Entity["Entity + logical types"]
    Workspace --> System["Catalog + MetaSchema"]
    Entity --> Plan["StoragePlan: field -> backend + strategy"]
    Plan --> Write["CRUD writer"]
    Plan --> Query["Workspace router"]
    Write --> RowOps["RowOp batches"]
    Query --> Handlers["HandlerRegistry"]
    Handlers --> Fragments["QueryFragments"]
    RowOps --> Backends["Backends"]
    Fragments --> Backends
    Backends --> Frame["ResultFrame"]
    Frame --> Surface
```

图刻意保持精简。HeavenBase 模块比这更多，但多数落在其中某条线上：定义结构、选择放置、编译操作、对接 provider，或将工作区适配到其他接口。

<br />

## 3. 工作区即边界

`HeavenBase` 工作区拥有必须彼此一致的事物：

* 已注册实体
* 已配置的后端实例
* 字段级存储计划
* 操作处理器
* 用于发现与内省的系统行

因此多数公开工作从这里开始：

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import heavenbase as hb

ws = hb.HeavenBase("shop", preset="debug")
```

工作区也是隔离单元。同一 Python 进程中，两个工作区可使用不同后端、不同注册实体与不同存储计划。`hb.HeavenBase.load("shop")` 背后的进程注册表让命名工作区易于复用，而工作区锁避免注册、CRUD、查询、刷新与 drop 在同一工作区对象内竞态。

<br />

## 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` 是让分散的字段片段稍后重新拼合的线索。

<br />

## 5. 路由放置字段

路由在字段级。字段可有显式放置 `.store(to=..., strategy=...)`，或使用其逻辑类型的默认存储配置。

默认直觉是：

* 向量优先使用带 `VectorIndex` 的向量后端
* 长文本优先使用带 `InvertedIndex` 的搜索后端，其次行存储
* JSON 优先使用支持 JSON 的行存储与 `JsonField`
* 数组与 `HyperG` 在可用时优先 SQL 侧表
* 普通标量使用内联行列

注册时将这些规则一次性解析为 `StoragePlan`。计划包含有效的 `StorageBinding` 行：实体、字段、后端、策略与来源。后端随后收到 `ensure(schema, bindings)`，以便为所拥有字段准备表、索引、文件或 provider 集合。

`object_id` 字段特殊。HeavenBase 控制其放置，并复制到存储同一实体片段的后端，以便安全合并。

<br />

## 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` 行，避免发现仍指向正在删除的对象。

<br />

## 7. 查询编译为片段

HeavenBase 接受多种查询表面，但它们汇聚于同一 `QuerySpec`。

Python 表达式如 `Product.price < 100`、Mongo 风格 JSON 过滤器、向量 `.near(...)`、投影、排序、offset 与 limit 都规范化为该 spec。查询引擎查看 `StoragePlan`，对每个叶子问一个窄问题：

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
Which backend owns this field, and which handler compiles this operation there?
```

处理器按 `(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 与投影。

<br />

## 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) 引用。

它们是普通可查询实体。这很重要，因为 Agent 可在行动前发现版图。Agent 可搜索 `Catalog` 找到正确对象，检查 `MetaSchema` 理解实体与字段结构，再通过同一工作区运行类型化查询或 CRUD。

这是更大 HeavenBase 理念背后的小循环：结构也是数据，Agent 应能观测它。

<br />

## 9. 扩展接入时不改变工作区 API

HeavenBase 将扩展工作分为两层：

* **实体扩展** 通过 `ExtensionSpec` 与 `ws.enable_extension(...)` 增加可选实体类型。包作者在工作区加载前用 `register_extension(...)` 注册它们。
* **开发者扩展** 通过 `hb.ext` 注册后端、处理器、存储策略、逻辑类型与查询 operation。工作区路由与 handler 播种消费这些进程全局注册表。

内置 `system` 扩展是今天唯一必需的实体扩展。Capsule 与 Toolkit 属于它；Prompt 与 Translation 位于默认加载的 `prompt` 扩展。

自定义实体扩展发布 MetaSchema 行，并通过正常工作区路径注册实体。开发者扩展将查询叶子编译为后端执行的 `QueryFragment` 对象。两层都不会教后端直接解析用户查询。

<br />

## 10. 开发者应看哪里

若读源码，从公开路径向下：

| Area                   | Source path                                                                                                                                       | What to look for                                                                          |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| Workspace facade       | `src/heavenbase/workspace/`                                                                                                                       | Public CRUD/query methods, workspace registry, writer, query engine, system-row publisher |
| Logical model          | `src/heavenbase/entity/`, `src/heavenbase/schema/`, `src/heavenbase/types/`                                                                       | Entity metaclass, field DSL, schema IR, logical type validation and encoding              |
| Placement              | `src/heavenbase/storage/`, `src/heavenbase/strategies/`                                                                                           | Storage rules, default profiles, effective bindings, strategy identifiers                 |
| Execution              | `src/heavenbase/handlers/`, `src/heavenbase/backends/`                                                                                            | Handler lookup, native compilers, scan fallbacks, provider adapters                       |
| Results                | `src/heavenbase/query/`, `src/heavenbase/frame/`                                                                                                  | Query AST, JSON query parser, `QueryBuilder`, `ResultFrame` merge/export behavior         |
| Extensions             | `src/heavenbase/extensions/`, `src/heavenbase/ext.py`                                                                                             | Built-in `system` extension, entity extension registry, developer registry exports        |
| Discovery and adapters | `src/heavenbase/discovery/`, `src/heavenbase/extensions/system/toolkit/`, `src/heavenbase/mcp/`, `src/heavenbase/cli/`, `src/heavenbase/interop/` | Capability browsing, MCP tools, CLI commands, import/export bridges                       |

扩展 HeavenBase 时最安全的规则，正是实现已在遵循的：通过 backend builder、存储配置与 handler 添加新物理行为。不要教后端解析 `QuerySpec`，也不要把新路由规则藏进 provider 代码。

<br />

## 进一步探索

<Tip>
  **相关资源：**

  * [概览](/zh/introduction/overview) - HeavenBase 的用途
  * [设计哲学](/zh/introduction/philosophy) - 结构与搜索为何重要
  * [工作区](/zh/features/workspace) - 工作区边界
  * [实体](/zh/features/entities) - 逻辑 schema 与类型
  * [路由](/zh/features/routing) - 字段级放置
  * [查询](/zh/features/query) - QueryBuilder、explain 与 ResultFrame
  * [目录](/zh/features/catalog) - Catalog 与 MetaSchema
  * [扩展](/zh/features/extensions) - 实体与开发者扩展模型
  * [扩展系统](/zh/quickstart/extension-system) - 启用与检查扩展
</Tip>

<br />