工作区清单 (Workspace Manifests)

清单记得如何搭舞台；演员仍得自己安排旅程。

1. 动机

工作区设置往往需要在笔记本电脑、CI 与生产环境之间迁移。清单捕获这个可重建外壳：一份 Backend 构造契约、请求的可选扩展，以及带放置规则的用户 Entity schema。它刻意排除已存储的行与物理 Backend 数据。这条边界让配置便于审查，也避免每次导出都意外变成数据库备份。

2. 导出与重放

import heavenbase as hb

ws = hb.HeavenBase("shop", preset="debug")
manifest = ws.to_manifest()
clone = hb.HeavenBase.from_manifest(manifest)

持久重放会创建不存在的工作区，或打开一个兼容的已注册工作区。它不会激活工作区。若需要一个不进入 Context 工作区目录、由调用方拥有的 facade，请使用 detached=True：

scratch = hb.HeavenBase.from_manifest(manifest, detached=True)

Detached 并不表示临时存储、自动清理或放宽 Backend 身份检查。

3. 版本 2 构造

版本 2 只有一个顶层 construction 信封，不再有平行的顶层 config。

类型	信封	重放行为
Ambient	`{"kind": "ambient"}`	解析普通工作区默认值
Preset	`{"kind": "preset", "preset": "debug"}`	解析命名 Preset
Backends	`{"kind": "backends", "config": {...}}`	重建完整 Backend 映射
Runtime	`{"kind": "runtime", "identifiers": {...}}`	重新连接匹配的实时 Backend 实例

运行时标识符证明 Backend 身份，而不是连接配置。重放绝不会根据标识符臆造端点、凭据、路径或客户端。

4. 清单形状

kind: heavenbase.workspace.manifest
version: 2
id: shop
construction:
  kind: backends
  config:
    main:
      type: sqlite
      database: shop.db
extensions:
  - database
entities:
  - entity_id: product
    fields:
      object_id: {type: identifier, pk: true}
      name: {type: short-text}

extensions 保存请求的可选根。重放时会重新计算必需依赖与传递依赖，而扩展拥有的 Entity schema 会由其所有者重建。 backend_summary 可能作为检查元数据出现。它绝不会配置或重新连接 Backend。

5. 保存与加载文件

manifest = hb.WorkspaceManifest.from_dict(ws.to_manifest())
manifest.save("workspace.yaml")

loaded = hb.WorkspaceManifest.load("workspace.yaml")
restored = loaded.open()

以 .json 结尾的路径使用 JSON；其他路径使用 YAML。清单对象会深拷贝嵌套构造值与序列化映射，因此编辑导出的字典不会改变源对象。

6. 替换环境

Preset 与已配置 Backend 的清单可在重放时替换完整构造信封：

production = hb.HeavenBase.from_manifest(
    manifest,
    backends={"main": {"type": "postgres", "database": "shop"}},
)

替换是整份信封替换，绝非递归合并。工作区 id、请求的扩展与 Entity schema 仍由清单拥有。当显式 Backend 映射含凭据时，应将其视为敏感信息。若密钥不应随清单移动，请优先使用环境自有的替换配置。

7. CLI 工作流

hb ws manifest shop > workspace.yaml
hb ws import workspace.yaml
hb ws activate shop

导入会注册重建的工作区，并保持当前激活选择不变。创建与导入刻意不提供 --active 选项；激活是另一项独立决定。

8. 范围与恢复

包含	不包含
工作区 id	已存储的 Entity 行
完整 Backend 构造信封	Backend 文件与数据库
请求的可选扩展根	配置中不存在的 Provider 凭据
用户 Entity schema 与放置规则	实时客户端与进程状态
可选 Backend 摘要	跨环境数据迁移

重放后，请通过数据所属的 API 重新连接或摄取领域数据。例如，需要外部 Catalog 元数据时，请加载 database 扩展并调用 ws.database.ingest(...)。版本 1 清单仍可在输入边界读取，并会被规范化为版本 2。新的导出始终产生版本 2。

总结

清单重建工作区外壳，而不是其中的行。
construction 是唯一的 Backend 重放权威。
导入与激活始终是两项独立操作。
必需依赖会根据请求的可选根重新计算。

进一步探索

相关资源：

工作区 (Workspace) — 生命周期、Context 所有权与持久身份
后端 (Backends) — 构造、标签与路由真相
扩展 (Extensions) — 请求的根与激活依赖

介绍

快速开始

核心概念

开发者

工具箱

LLM

智能体运行时

社区

工作区清单 (Workspace Manifests)

1. 动机

2. 导出与重放

3. 版本 2 构造

4. 清单形状

5. 保存与加载文件

6. 替换环境

7. CLI 工作流

8. 范围与恢复

总结

进一步探索

​1. 动机

​2. 导出与重放

​3. 版本 2 构造

​4. 清单形状

​5. 保存与加载文件

​6. 替换环境

​7. CLI 工作流

​8. 范围与恢复

​总结

​进一步探索

1. 动机

2. 导出与重放

3. 版本 2 构造

4. 清单形状

5. 保存与加载文件

6. 替换环境

7. CLI 工作流

8. 范围与恢复

总结

进一步探索