跳转到主要内容
实体扩展增加 schema。开发者注册表增加物理行为。两者接入时均不改变工作区 API。

​
1. 两层扩展

HeavenBase 将扩展工作分为两层，共享 hb.ext 导入路径，但面向不同作者：
LayerAudienceWhat it addsPrimary API
Entity extension应用与包作者可选 Entity 类与 MetaSchema 行ExtensionSpec、register_extension、ws.enable_extension
Developer extension后端与编译器作者后端、处理器、策略、逻辑类型、ophb.ext.register_backend_builder、register_strategy、register_handler、…
实体扩展通过正常工作区注册发布结构。开发者扩展通过进程全局注册表发布行为，工作区规划器与 handler 播种在运行时使用它们。

​
2. 内置 System 扩展

HeavenBase 提供一个必需的内置实体扩展：system。每个 HeavenBase(...) 工作区会自动启用它。 规范实现位于 src/heavenbase/extensions/system/。heavenbase.prompt、heavenbase.capsule、heavenbase.toolkit 等公开兼容模块从该处重新导出面向用户的类。

​
2.1. 系统实体

Entity idClassPurpose
sys-catalogCatalog具体对象发现
sys-metaschemaMetaSchema结构、能力与扩展
sys-promptPrompt可调用提示 (Prompt) 行
sys-translationTranslation绑定提示 (Prompt) 的翻译
sys-capsuleCapsule可执行 Capsule 清单
sys-toolkitToolkit工具集 (Toolkit) 清单
ConfigLayer（sys-config-layer）位于同一包中，但不属于 system_entities()，也不会自动启用。

​
2.2. 0.1.1.0 中的变化

Prompt、Translation、Capsule 与 Toolkit 已并入必需的 system 扩展。调用 ws.enable_extension("prompt") 会抛出 KeyError，因为 prompt 不再是独立的扩展标识符。 ensure_prompt_entities(ws) 等惰性 helper 与 Capsule 注册表 setup 在需要系统行时会调用 ws.enable_extension("system")。

​
3. 实体扩展 API

在工作区加载之前定义并注册实体扩展： 
import heavenbase as hb
from heavenbase.ext import Extension, ExtensionSpec, register_extension


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

    event = hb.field(hb.ShortText)


register_extension(
    Extension(
        ExtensionSpec(
            identifier="audit",
            name="Audit Log",
            desc="Optional audit rows.",
            entities=(AuditLog,),
            tags=("audit",),
        )
    )
)
ExtensionSpec 字段：
FieldRole
identifier稳定扩展 id（与工作区 id 相同的命名规则）
name、desc、version发布到 MetaSchema 的可读元数据
entities扩展启用时注册的实体类
required为 True 时扩展不可跳过（目前仅 system 使用）
tags、meta发现与工具用的额外元数据
在单个工作区中启用扩展： 
ws = hb.HeavenBase("demo", preset="debug")
spec = ws.enable_extension("audit")
print(spec.identifier)
print(ws.extensions())
通过配置在每个新工作区上启用自定义扩展： 
# heavenbase.extensions.default: ["audit", "my-package"]
实体扩展不会绕过存储规划。已启用的实体仍须经过 ws.register(...) 与正常路由。

​
4. 开发者扩展注册表

开发者扩展在 hb.ext 导出的进程全局注册表中注册物理行为：
RegistryRegister functionUsed by
Backendsregister_backend_builder、register_backend_class配置加载、存储放置、handler 播种
Handlersregister_handler、HandlerRegistry.register查询 (Query) 编译
Strategiesregister_strategy存储放置与 handler 查找
Logical typesregister_logical_typeHandler 播种与存储配置
Operationsregister_opJSON 查询 (Query) 解析与 handler 播种
Storage profilesregister_storage_profile默认字段放置
Handler 将一个逻辑 operation 编译为一个 QueryFragment。它们不执行 IO；后端执行 fragment。 
import heavenbase as hb

def compile_ends_with(field_schema, value, ctx):
    def payload(row):
        return str(row.get(field_schema.name, "")).endswith(str(value))

    return hb.ext.QueryFragment(ctx.backend, "ends_with", field_schema.name, payload)


hb.ext.register_handler(
    "demo",
    hb.ShortText,
    "ends_with",
    "inmem",
    "suffix-index",
    compile_ends_with,
)
Provider 原生 handler 插件位于 heavenbase.handlers.plugins，通过 register_handler_plugin 注册。内置播种消费注册表与插件，而非硬编码 provider 列表。

​
5. 发现能力

用户与扩展 UI 应通过公开能力索引发现选项，而非读取注册表内部： 
import heavenbase as hb

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

hb.capabilities.logical_types()
hb.capabilities.strategies(hb.Vector)
hb.capabilities.backends(hb.Array, hb.SideTable, op="array_contains")
hb.capabilities.ops(hb.ShortText, hb.InlineColumn, backend="sqlite")

# Same methods on ws.capabilities(), filtered to configured backends
ws.capabilities.backends(hb.Vector, hb.VectorIndex, op="near")
每个选项暴露 to_dict()，用于构建选择器或诊断信息。

​
6. 验证清单

添加扩展面之后：
  1. 在 src/heavenbase/ 下正确的角色包中注册组件。
  2. 若为内置组件，从包 __init__.py 与顶层 heavenbase 导出。
  3. 在 tests/test_extensions.py、tests/test_backends.py 或专用测试模块中添加测试。
  4. 在 HeavenBase 仓库根目录运行 bash scripts/test.bash。
最小自定义 operation demo 见 demos/04_extension_backend_template.py。

​
Further Exploration

相关资源：