扩展 - HeavenBase

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

1. 动机

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

if provider == "sqlite":
    return build_sqlite(config)
if provider == "my_provider":
    return build_my_provider(config)

现在每个新包都需要修改宿主源码并等待发布。检查可能导入实现，打包提供商也会得到外部提供商无法复现的特权。 HeavenBase 改用一套 Registry 支持的模块协议。内聚文件夹在 meta.yaml 中声明记录；Context 安装并检查这些记录；类型化入口在需要时解析行为。内置与外部项目共享相同描述符、Registry、解析器、验证、生命周期与契约形态。

2. 区分扩展概念

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

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

3. 理解内置基础与根

Catalog 与 MetaSchema 是固定的工作区基础实体。任何 Extension 都不能替换它们。 Capsule 是必需 Extension 根。Toolkit 与 Prompt 是打包默认根。Agent、Memory 与 Database 是应用主动启用的可选根。每个 Extension 声明精确的 requires 标识符；重新打开工作区会从请求根重新计算硬依赖闭包。

import heavenbase as hb

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

print(ws.extensions())

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

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

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

acme_notes/
├── __init__.py
├── entities.py
└── meta.yaml

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

import heavenbase as hb

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

    name = hb.field(hb.ShortText)

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

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。

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

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)。卸载模块不会删除应用工作区数据。

6. 挂载工作区绑定 API

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

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，让检查、安装回执、兼容性与制品保持显式。

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

高级作者通过 hb.ext 与所属包使用后端类型、处理器、策略、逻辑类型、查询操作、Toolkit family、profile、序列化器及相关 Registry 支持角色。每个开放 family 都遵循同一规则：

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

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

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

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() 判断执行路线。

9. 使用扩展检查清单

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

摘要

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

进一步探索

相关资源：

扩展系统 - 构建并运行上面的最小模块
架构 - 查看 Context 与 Registry 所有权
工作区 - 理解扩展根与生命周期
后端 - 检查已注册提供商选择
MCP Toolkit - 定义 Toolkit family 与 profile

介绍

快速开始

核心概念

开发者

工具箱

LLM

智能体运行时

社区

扩展

1. 动机

2. 区分扩展概念

3. 理解内置基础与根

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

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

6. 挂载工作区绑定 API

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

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

9. 使用扩展检查清单

摘要

进一步探索

​1. 动机

​2. 区分扩展概念

​3. 理解内置基础与根

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

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

​6. 挂载工作区绑定 API

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

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

​9. 使用扩展检查清单

​摘要

​进一步探索

1. 动机

2. 区分扩展概念

3. 理解内置基础与根

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

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

6. 挂载工作区绑定 API

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

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

9. 使用扩展检查清单

摘要

进一步探索