> ## 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 Manifests)

> 重放工作区外壳，同时不假装它的行数据能塞进行李箱。

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

<br />

## 1. 动机

工作区设置往往需要在笔记本电脑、CI 与生产环境之间迁移。
清单捕获这个可重建外壳：一份 Backend 构造契约、请求的可选扩展，以及带放置规则的用户 Entity schema。

它刻意排除已存储的行与物理 Backend 数据。
这条边界让配置便于审查，也避免每次导出都意外变成数据库备份。

<br />

## 2. 导出与重放

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

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

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

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
scratch = hb.HeavenBase.from_manifest(manifest, detached=True)
```

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

<br />

## 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 身份，而不是连接配置。
重放绝不会根据标识符臆造端点、凭据、路径或客户端。

<br />

## 4. 清单形状

```yaml theme={"theme":{"light":"github-light","dark":"github-dark"}}
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。

<br />

## 5. 保存与加载文件

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
manifest = hb.WorkspaceManifest.from_dict(ws.to_manifest())
manifest.save("workspace.yaml")

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

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

<br />

## 6. 替换环境

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

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
production = hb.HeavenBase.from_manifest(
    manifest,
    backends={"main": {"type": "postgres", "database": "shop"}},
)
```

替换是整份信封替换，绝非递归合并。
工作区 id、请求的扩展与 Entity schema 仍由清单拥有。

当显式 Backend 映射含凭据时，应将其视为敏感信息。
若密钥不应随清单移动，请优先使用环境自有的替换配置。

<br />

## 7. CLI 工作流

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
hb ws manifest shop > workspace.yaml
hb ws import workspace.yaml
hb ws activate shop
```

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

<br />

## 8. 范围与恢复

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

重放后，请通过数据所属的 API 重新连接或摄取领域数据。
例如，需要外部 Catalog 元数据时，请加载 `database` 扩展并调用 `ws.database.ingest(...)`。

版本 1 清单仍可在输入边界读取，并会被规范化为版本 2。
新的导出始终产生版本 2。

<br />

## 总结

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

<br />

## 进一步探索

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

  * [工作区 (Workspace)](/zh/features/workspace) — 生命周期、Context 所有权与持久身份
  * [后端 (Backends)](/zh/features/backends) — 构造、标签与路由真相
  * [扩展 (Extensions)](/zh/features/extensions) — 请求的根与激活依赖
</Tip>

<br />