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

# 工作区 (Workspace)

> HeavenBase 工作区边界：承载 schema、后端、路由、系统行与数据。

<Note>
  *一个工作区，多种存储引擎，一个统一提问入口。*
</Note>

<br />

## 1. 工作区拥有什么

`HeavenBase` 工作区是数据应用的应用边界。它拥有：

* 你注册的实体 schema
* 你连接的后端实例
* 字段级存储放置
* 必需 `system` 扩展中 `Catalog`、`MetaSchema` 等实体的系统行
* 对工作区内数据的 CRUD、查询、审计、修复，以及面向 MCP 的访问

通常为一个应用、Agent 记忆、demo 或租户边界创建一个工作区。在该边界内，即使字段分布在不同物理后端，HeavenBase 仍保持统一的逻辑 API。

<Info>
  把工作区理解为「数据的含义」与「数据的存放位置」交汇之处。
</Info>

<br />

## 2. 从 preset 开始

首次本地执行时，使用 `debug` preset。它无需 Docker 服务，提供 SQLite 行存储以及内存向量与搜索后端。

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

ws = hb.HeavenBase("core-workspace", preset="debug")
print(ws.id)
```

从 CLI 查看解析后的 preset：

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
hb ws presets show debug
```

| Preset      | Backends                                               | When to use      |
| ----------- | ------------------------------------------------------ | ---------------- |
| `debug`     | SQLite `main`, in-memory `vec`, in-memory `search`     | 首次 demo、测试与示例。   |
| `local-lts` | Postgres `main`, LanceDB `vec`, Elasticsearch `search` | 使用仓库服务栈的持久化本地开发。 |
| `web-lts`   | Managed Postgres, pgvector, hosted search              | 共享或托管部署。         |

<Tip>
  在需要持久化或外部服务之前，先用 `preset="debug"`。相同的实体与查询代码之后可迁移到更大的 preset。
</Tip>

<br />

## 3. 放置关系明确时使用显式后端

Preset 是最短路径，但当你需要自定义测试布局或记录部署形态时，显式后端映射更有用。

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
ws = hb.HeavenBase(
    "core-explicit-workspace",
    backends={
        "main": {"type": "inmem"},
        "vec": {"type": "inmem"},
    },
)

print(ws.backends.names())
```

后端键是工作区本地名称。后端 `type` 选择 provider 族，例如 `sqlite`、`postgres`、`inmem`、`lance`、`elasticsearch`、`json` 或 `pickle`。

<br />

## 4. 注册、写入与读取

注册是显式的：定义实体，在工作区注册，再通过工作区 API 写入行。

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
class Note(hb.Entity):
    title = hb.field(hb.ShortText)
    body = hb.field(hb.LongText)


ws.register(Note)

note_id = ws.upsert(
    Note,
    {
        "name": "Routing note",
        "title": "Routing note",
        "body": "One logical row can move across backends.",
    },
)

row = ws.get(note_id, entity=Note)
print(row["title"])
```

每行只有一个 `object_id`。当你省略它且行有 `name` 时，HeavenBase 会根据实体 schema 与该 name 派生稳定 ID。

<br />

## 5. 检查与修复

工作区始终注册 `Catalog` 与 `MetaSchema` 系统实体。当 Agent 或开发者需要了解工作区内容时，查询它们。

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
entity_rows = (
    ws.query(hb.MetaSchema)
    .where(hb.MetaSchema.kind == "entity")
    .select("subject_id", "name")
    .execute()
    .rows()
)

print([row["subject_id"] for row in entity_rows])
print(ws.audit()["catalog"]["ok"])
```

用 `ws.audit()` 检查 Catalog 一致性。仅当你有意让 HeavenBase 根据权威实体行重建缺失或过时的 Catalog 行时，才使用 `ws.repair()`。

<br />

## Further Exploration

<Tip>
  **Related resources:**

  * [工作区清单 (Workspace Manifests)](/features/workspace-manifest) - 导出并重放工作区构造配置
  * [实体 (Entities)](/features/entities) - 定义逻辑 schema
  * [路由 (Routing)](/features/routing) - 将字段放置到后端
  * [后端 (Backends)](/features/backends) - 选择存储 provider
  * [目录 (Catalog)](/features/catalog) - 浏览对象与工作区结构
  * [扩展 (Extensions)](/features/extensions) - system 扩展与自定义实体扩展
</Tip>

<br />