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

# 扩展系统

> 启用内置 system/prompt 扩展，注册自定义实体扩展，并扩展后端、处理器与存储策略。

<Note>
  *扩展在不改变工作区 API 的前提下，增加实体类型与存储行为。*
</Note>

<br />

## 1. 扩展做什么

HeavenBase 扩展向工作区注册额外的实体类型或开发者 Hook。工作区 API 不变：你仍调用 `register`、`upsert`、`query` 与 `get`。

0.1.1.5 中有两层：

* **实体扩展** 通过 `ExtensionSpec` 与 `ws.enable_extension(...)` 增加可选实体类型。
* **开发者扩展** 通过 `hb.ext` 注册后端、处理器、存储策略与查询 op。

<br />

## 2. 内置 System 与 Prompt 扩展

每个工作区在构造期间会自动启用必需的 `system` 扩展。应用代码中无需调用 `enable_extension("system")`。

`system` 与默认加载的 `prompt` 扩展注册内置持久实体：

| Entity id         | Role                          |
| ----------------- | ----------------------------- |
| `sys-catalog`     | 具体对象发现                        |
| `sys-metaschema`  | 工作区结构、能力与已启用扩展                |
| `sys-prompt`      | 来自 `prompt` 的可调用提示 (Prompt) 行 |
| `sys-translation` | 来自 `prompt` 的绑定提示 (Prompt) 翻译 |
| `sys-capsule`     | 可执行 Capsule 清单                |
| `sys-toolkit`     | 工具集 (Toolkit) 清单与 Capsule 引用  |

Capsule 与 Toolkit 属于 `system`；Prompt 与 Translation 属于默认加载的 `prompt` 扩展。

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

ws = hb.HeavenBase("ext-demo", preset="debug")

print("system" in ws.extensions())
print("prompt" in ws.extensions())
print("sys-capsule" in ws.entities)
```

在工作区中注册提示 (Prompt) 时，HeavenBase 会确保 `prompt` 扩展已启用。通过根包 API 使用 `hb.Prompt(...).register(ws=ws)`。

<br />

## 3. 查看已启用的扩展

用 `ws.extensions()` 获取已启用扩展元数据，或查询 `MetaSchema` 中已发布的 extension 行：

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
print(list(ws.extensions()))

ext_rows = (
    ws.query(hb.MetaSchema)
    .where(hb.MetaSchema.kind == "extension")
    .select("subject_id", "name", "desc")
    .execute()
    .rows()
)

print([row["subject_id"] for row in ext_rows])
```

`system` 与 `prompt` 行的 `meta.entities` 包含各自的内置实体 id。

<br />

## 4. 注册自定义实体扩展

包作者在加载工作区之前，将实体扩展注册到进程注册表：

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import heavenbase as hb
from heavenbase.ext import Extension, ExtensionSpec, register_extension


class AuditLog(hb.Entity):
    identifier = "audit-log"

    event = hb.field(hb.ShortText)
    payload = hb.field(hb.Json).default({})


register_extension(
    Extension(
        ExtensionSpec(
            identifier="audit",
            name="Audit Log",
            desc="Optional audit rows for demo extensions.",
            entities=(AuditLog,),
            tags=("audit",),
        )
    )
)

ws = hb.HeavenBase("ext-custom", preset="debug")
ws.enable_extension("audit")
ws.register(AuditLog)
ws.upsert(
    AuditLog,
    {"object_id": "a1", "name": "startup", "event": "startup", "payload": {"ok": True}},
)
```

若要在每个新工作区上启用自定义扩展，在配置中将 `heavenbase.extensions.default` 设为逗号分隔列表或扩展 id 数组。

<br />

## 5. 扩展后端与处理器

底层扩展作者使用 `heavenbase.ext`（亦可用 `hb.ext`）注册后端、处理器插件、逻辑类型、存储策略与查询操作。工作区路由通过注册表接入它们，而非修改中心代码。

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
from heavenbase.ext import registered_backend_identifiers, registered_ops

print("sqlite" in registered_backend_identifiers())
print("eq" in registered_ops())
```

通过公开能力索引发现支持的组合：

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

hb.capabilities.logical_types()
hb.capabilities.backends(hb.Vector, hb.VectorIndex, op="near")
```

发布新存储 provider 或编译器时使用该接口；日常应用代码不必依赖它。自定义 operation 示例见 `demos/04_extension_backend_template.py`。

<br />

## 进一步探索

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

  * [扩展](/zh/features/extensions) - 实体与开发者扩展参考
  * [架构](/zh/introduction/architecture) - 扩展在核心路径中的位置
  * [目录](/zh/features/catalog) - `system` 扩展提供的系统实体
  * [提示 (Prompt)](/zh/features/utilities/prompt) - 由 `sys-prompt` 支撑的可调用提示 (Prompt)
  * [Capsule](/zh/features/capsules) - `sys-capsule` 下的可执行清单
  * [后端](/zh/features/backends) - 扩展可注册的后端家族
</Tip>

<br />