工作区

工作区让数据库们加入同一场对话，却不会请它们共用一把牙刷。

1. 动机

没有一个所有者时，模式设置发生在迁移脚本中，提供商客户端住在全局变量里，CLI 选择另一套配置，MCP 服务器又悄悄打开第二份副本。每个部件单独工作，应用却失去了统一身份。 HeavenBase 工作区把一个稳定 id 绑定到规范 Entity 类、命名 Backend 实例、字段放置、行与查询服务、固定元数据实体、请求的 Extension 根和智能体工具。所属上下文 (Context) 提供机器配置、模块解析与持久工作区注册。这很重要，因为一个逻辑行可以跨越 SQL、向量、搜索、图或文件提供商，应用代码却仍需要一个地方来注册、写入、查询、检查和解释它。

2. 创建或以兼容方式重新打开持久工作区

import heavenbase as hb

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

print(ws.id)
print(same.id)

HeavenBase("shop", ...) 在持久身份层面是幂等的。它会创建并注册缺失工作区，或打开已有的兼容定义。它绝不会隐式激活工作区。显式 preset= 或 backends= 是构造断言。与已存构造冲突时会抛出 FileExistsError。两者都省略时，已有 id 会复用持久构造，而不是重新解释今天的默认值。希望缺失成为错误时使用 load()：

same = hb.HeavenBase.load("shop")
same.activate()
active = hb.HeavenBase.load()

HeavenBase.load("shop") 要求工作区已经注册，缺失时抛出 KeyError。无名称 load() 先检查活跃选择，再检查配置默认值；它绝不会把创建工作区作为副作用。

3. 把隔离绑定到 Context

context = hb.Context.load(home_path="bootstrap.yaml")
ws = hb.HeavenBase("shop", preset="debug", context=context)

print(ws.context is context)
print(context.modules().inspect("backend_type", "sqlite")[0]["identifier"])

工作区内部每次 Registry 支持的查找都会继承这个 Context 及其模块解析器。两个 Context 可以拥有 id 相同、实时实例不同的工作区。hb.DEFAULT_CONTEXT 只是未绑定调用的便利所有者。稳定工作区 id 也会派生其配置层：shop 把 heavenbase.shop 覆盖在基础 heavenbase 配置上。发生实质配置变更后，如果已构建资源必须看到新快照，请重新打开工作区。

4. 从预设或显式后端开始

debug 预设不需要外部服务：

ws = hb.HeavenBase("local-demo", preset="debug")
print(ws.backends.names())

当部署放置很重要时使用显式映射：

ws = hb.HeavenBase(
    "explicit-demo",
    backends={
        "main": {"type": "sqlite", "database": "demo.db"},
        "vec": {"type": "inmem"},
    },
)

main 与 vec 等 Backend 键是工作区局部名称。每个 type 都通过 Context 解析一条规范 backend_type 记录。就绪 Backend 实例使用相同身份契约；进程重启后，重建需要兼容的实时实例或显式替换配置。

5. 在行 CRUD 前注册模式

class Product(hb.Entity):
    name = hb.field(hb.ShortText)
    price = hb.field(hb.Float)


ws.register(Product)
product_id = ws.upsert(Product, {"name": "Oak desk", "price": 129.0})
product = ws.get(product_id, entity=Product)

print(product["price"])

register() 建立规范 Entity 类、解析放置、确保物理模式，并发布 MetaSchema 行。普通 upsert、set、delete、get、exists、count、ids 与 rows 只能操作已经存在的规范类。它们绝不会把创建模式变成隐藏副作用。每一行都有稳定 object_id。如果数据行省略它却提供 name，HeavenBase 会从 Entity 模式与该名称派生确定性标识符。

6. 通过一个逻辑界面查询

query = (
    ws.query(Product)
    .where(Product.price < 150)
    .select("name", "price")
)

plan = query.explain()
rows = query.execute().rows()

print(plan["steps"])
print(rows)

查询变换返回新的不可变 hb.Query 值。execute() 重新计算并返回分离的 ResultFrame；请使用 rows()、scalar() 或类型化 dataframe 导出等显式出口。工作区解析放置、已注册操作、处理器与提供商执行。explain() 报告真实的原生、适配器、扫描、回退或不支持路线，而不会把模块标签当作证明。

7. 检查基础实体与扩展

Catalog 与 MetaSchema 是固定且不可替换的工作区基础实体。Catalog 描述具体对象；MetaSchema 描述规范模式、字段、放置、活跃 Extension 与安全的 Registry 支持元数据。

entities = (
    ws.query(hb.MetaSchema)
    .where(hb.MetaSchema.kind == "entity")
    .select("subject_id", "name")
    .execute()
    .rows()
)

print([row["subject_id"] for row in entities])
print(ws.extensions())

Capsule 是必需 Extension 根。Toolkit 与 Prompt 是打包默认根；Agent、Memory 与 Database 是可选根。工作区存储请求的可选根，并在重新打开时重新计算精确依赖。

8. 导出可重建外壳，而不是数据

工作区清单版本 2 存储一个 construction 封装、请求的可选 Extension 根与用户 Entity 模式：

manifest = ws.to_manifest()
restored = hb.HeavenBase.from_manifest(manifest)

配置 Backend 存储其完整可重放映射。实时 Backend 对象只存储完整的名称到规范标识符签名；标识符绝不会捏造凭据、端点、文件或客户端。清单不会导出已存数据行或物理 Backend 数据。重放可以用完整 preset= 或 backends= 值替换可重放构造，但不会递归合并部分 Backend 设置。

9. 主动选择分离生命周期

scratch = hb.HeavenBase(
    "scratch",
    detached=True,
    backends={"main": {"type": "inmem"}},
)

分离工作区由调用方拥有：它不会注册，不能激活，也不能被 load() 找到。分离是一种生命周期策略，不是存储承诺。它不代表临时或隔离数据，清理也不会自动发生。 release() 从所属 Context 的实时查找中移除持久工作区外观，同时保留 Backend 数据。drop() 是破坏性物理数据操作。请保留正确外观，并显式调用这些方法。

10. 了解协调边界

一个实时工作区会串行化其公共模式、CRUD、查询、刷新、修复、释放与删除操作。独立路由 Backend 仍不会形成分布式事务或跨进程序列化边界。失败的多后端写入可能需要显式审计与收敛。使用 ws.audit() 检查 Catalog 一致性，并在有意修复前使用 ws.repair(dry_run=True)。承诺提供商原生行为前先使用 Query.explain()。

摘要

工作区拥有 schema、放置、行、路由与附属领域 API。
持久构造、加载、激活与 detached 生命周期是独立决定。
清单重建外壳；Backend 与应用拥有物理数据保证。

进一步探索

相关资源：

工作区清单 - 检查版本 2 重建
实体 - 定义规范模式
路由 - 解析字段放置
后端 - 选择并检查提供商
目录 - 浏览对象与结构
扩展 - 添加 Registry 支持的领域行为

介绍

快速开始

核心概念

开发者

工具箱

LLM

智能体运行时

社区

1. 动机

2. 创建或以兼容方式重新打开持久工作区

3. 把隔离绑定到 Context

4. 从预设或显式后端开始

5. 在行 CRUD 前注册模式

6. 通过一个逻辑界面查询

7. 检查基础实体与扩展

8. 导出可重建外壳，而不是数据

9. 主动选择分离生命周期

10. 了解协调边界

摘要

进一步探索

​1. 动机

​2. 创建或以兼容方式重新打开持久工作区

​3. 把隔离绑定到 Context

​4. 从预设或显式后端开始

​5. 在行 CRUD 前注册模式

​6. 通过一个逻辑界面查询

​7. 检查基础实体与扩展

​8. 导出可重建外壳，而不是数据

​9. 主动选择分离生命周期

​10. 了解协调边界

​摘要

​进一步探索

1. 动机

2. 创建或以兼容方式重新打开持久工作区

3. 把隔离绑定到 Context

4. 从预设或显式后端开始

5. 在行 CRUD 前注册模式

6. 通过一个逻辑界面查询

7. 检查基础实体与扩展

8. 导出可重建外壳，而不是数据

9. 主动选择分离生命周期

10. 了解协调边界

摘要

进一步探索