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

# 扩展

> Registry 支持的模块文件夹、工作区扩展、后端/提供商贡献，以及内置与外部共享生命周期。

<Note>
  *健康的插件系统里，「内置」是来源，不是秘密握手。*
</Note>

<br />

## 1. 动机

中央分支让第一个提供商很容易，却让第五十个提供商变成政治问题：

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
if provider == "sqlite":
    return build_sqlite(config)
if provider == "my_provider":
    return build_my_provider(config)
```

现在每个新包都需要修改宿主源码并等待发布。检查可能导入实现，打包提供商也会得到外部提供商无法复现的特权。

HeavenBase 改用一套 Registry 支持的模块协议。内聚文件夹在 `meta.yaml` 中声明记录；Context 安装并检查这些记录；类型化入口在需要时解析行为。内置与外部项目共享相同描述符、Registry、解析器、验证、生命周期与契约形态。

<br />

## 2. 区分扩展概念

| 概念             | 它拥有什么                          | 典型作者    |
| -------------- | ------------------------------ | ------- |
| 模块文件夹          | 一个内聚 `meta.yaml` 加可选实现文件       | 包或提供商作者 |
| Registry 记录    | 一个声明式身份，例如实体、后端类型、处理器或 profile | 模块安装器   |
| 扩展             | 工作区实体包、依赖与可选挂载 API             | 应用/领域作者 |
| Toolkit family | 一组工作区限定的可调用工具                  | 智能体集成作者 |
| MCP profile    | 工具、实体、Skill 与序列化器范围            | 界面/策略作者 |
| 标签定义或声明        | 用于检查与候选选择的开放语义元数据              | 任意模块作者  |

Extension 是一种 Registry 记录；它不是 Registry 本身。后端、处理器、逻辑类型、策略、查询操作、序列化器与 profile 都是同级记录类型，而不是巨型 Extension 对象上的字段。

<br />

## 3. 理解内置基础与根

`Catalog` 与 `MetaSchema` 是固定的工作区基础实体。任何 Extension 都不能替换它们。

Capsule 是必需 Extension 根。Toolkit 与 Prompt 是打包默认根。Agent、Memory 与 Database 是应用主动启用的可选根。每个 Extension 声明精确的 `requires` 标识符；重新打开工作区会从请求根重新计算硬依赖闭包。

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

ws = hb.HeavenBase("extension-demo", preset="debug")
ws.enable_extension("memory")

print(ws.extensions())
```

启用是单调的。这里没有通用禁用/卸载操作，因为只有所属领域才能解释如何安全移除自己的数据行、物理数据、索引、配置与派生效果。

<br />

## 4. 声明可分发模块文件夹

最小外部实体 Extension 可以使用以下布局：

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
acme_notes/
├── __init__.py
├── entities.py
└── meta.yaml
```

实体仍是普通的公共 HeavenBase 代码：

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


class AcmeNote(hb.Entity):
    identifier = "acme-note"

    name = hb.field(hb.ShortText)
```

描述符发布实体，以及激活该实体的 Extension：

```yaml theme={"theme":{"light":"github-light","dark":"github-dark"}}
manifest_version: 2
coordinate: acme/notes
version: 1.0.0
bundle: acme-notes
items:
  - kind: entity
    identifier: acme-note
    source: path
    target: {module: entities, qualname: AcmeNote}
  - kind: extension
    identifier: acme-notes
    source: inline
    target: definition
    meta:
      dependencies: [entity:acme-note]
      definition:
        identifier: acme-notes
        entities: [acme-note]
        required: false
        requires: []
        setup: null
        api: null
        api_name: null
```

`source: path` 目标相对于模块文件夹。请把导入保留在捕获根内，或使用稳定的绝对公共 API。

<br />

## 5. 安装、检查、解析与启用

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
from pathlib import Path

import heavenbase as hb


context = hb.Context.load()
modules = context.modules()
receipt = modules.install(Path("acme_notes"))

record = modules.inspect("extension", "acme-notes")[0]
ws = hb.HeavenBase("notes", preset="debug", context=context)
ws.enable_extension("acme-notes")

Note = ws.entities["acme-note"]
note_id = ws.upsert(Note, {"name": "Registry parity"})
print(ws.get(note_id, entity=Note)["name"])
```

`install()` 把本地可执行文件捕获为经过验证的内容寻址制品，并返回精确回执。`inspect()` 读取惰性记录数据。`enable_extension()` 通过工作区的 Context 解析 Extension 及其声明的 Entity 记录，再注册规范类。

只有在你有意移除该安装代时才使用 `modules.uninstall(receipt)`。卸载模块不会删除应用工作区数据。

<br />

## 6. 挂载工作区绑定 API

Extension 可以通过 `api` 与 `api_name` 挂载一个领域服务。工厂接收工作区，因此服务会继承正确的 Context、规范 Entity 类与生命周期。

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
class NotesAPI:
    def __init__(self, workspace):
        self.workspace = workspace

    def list(self):
        Note = self.workspace.entities["acme-note"]
        return self.workspace.query(Note).execute().rows()
```

在可分发模块中，把工厂作为 Extension 定义里的持久 `heavenbase.executable` 目标发布。启用后，应用代码使用挂载 API，例如 `ws.notes.list()`，CLI 与 MCP 界面则保持为薄适配器。

程序化 `Extension(...).register(resolver=...)` 对本地或生成定义仍然有用。发布包应优先使用一个 `meta.yaml`，让检查、安装回执、兼容性与制品保持显式。

<br />

## 7. 通过注册角色扩展物理行为

高级作者通过 `hb.ext` 与所属包使用后端类型、处理器、策略、逻辑类型、查询操作、Toolkit family、profile、序列化器及相关 Registry 支持角色。

每个开放 family 都遵循同一规则：

1. 通过目标 Context 的解析器发布一条规范记录。
2. 把实现加载保留在类型化入口后面。
3. 声明精确依赖与兼容性。
4. 通过安装、检查、解析、使用与卸载测试内置/外部一致性。

不要添加固定提供商扫描、特权导入列表或中央规划器分支。不要把标签声明当作可执行证明。

<br />

## 8. 检查声明而不过度承诺

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
modules = ws.context.modules()

claim = modules.tag("backend_type", "inmem", "vector")
print(claim.value)

plan = ws.query(Note).where(Note.name == "Registry parity").explain()
print(plan["steps"])
```

模块标签是描述性声明与候选提示。精确处理器记录、编译器输出与实时资源检查决定具体查询是原生执行、通过适配器、进行便携扫描，还是完全不支持。请使用 `explain()` 判断执行路线。

<br />

## 9. 使用扩展检查清单

* 给模块、每条记录与每个 Extension 稳定标识符。
* 在内聚模块根保留一个精确 `meta.yaml`。
* 声明依赖，不要依赖导入顺序。
* 把路径目标保留在捕获的模块根内。
* 当身份或生命周期真实存在时，通过一个工作区 API 挂载领域行为。
* 给 MCP 工具加命名空间，并把 profile 限定到所需的精确工具、实体、Skill 与序列化器。
* 测试全新 Context 恢复、惰性检查、激活、普通使用与精确回执卸载。
* 把已安装可执行源码视为可信代码。

<br />

## 摘要

* 内置模块与外部模块使用同一套 `meta.yaml` 文件夹协议。
* Registry 记录会在导入实现前接受检查。
* 工作区 Extension 通过显式根与依赖附加领域行为。

<br />

## 进一步探索

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

  * [扩展系统](/zh/quickstart/extension-system) - 构建并运行上面的最小模块
  * [架构](/zh/introduction/architecture) - 查看 Context 与 Registry 所有权
  * [工作区](/zh/features/workspace) - 理解扩展根与生命周期
  * [后端](/zh/features/backends) - 检查已注册提供商选择
  * [MCP Toolkit](/zh/reference/mcp-toolkit/overview) - 定义 Toolkit family 与 profile
</Tip>

<br />