构建外部扩展

如果扩展还需要修改宿主，它就只是戴了假胡子的功能请求。

1. 动机

导入外部类只能证明 Python 找得到它。真正的 HeavenBase Extension 还必须通过声明式发现、惰性检查、Context 局部解析、工作区激活、普通 CRUD、全新进程与精确卸载定位。本快速开始构建最小但有用的一致性测试。你将通过 HeavenBase 内置模块使用的同一模块协议，贡献一个 Entity 与一个 Extension。

2. 创建模块文件夹

在 heavenbase 包外创建以下结构：

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

让 __init__.py 保持为空。把一个公共 Entity 放入 entities.py：

import heavenbase as hb

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

    name = hb.field(hb.ShortText)

实现导入公共入口，不依赖宿主的私有路径。

3. 声明 Entity 与 Extension

把以下内容保存为 acme_notes/meta.yaml：

manifest_version: 2
coordinate: acme/notes
version: 1.0.0
compatibility: {}
bundle: acme-notes
items:
  - kind: entity
    identifier: acme-note
    name: AcmeNote
    desc: Example external note.
    source: path
    target: {module: entities, qualname: AcmeNote}
    active: true
    meta: {schema_version: 1}
  - kind: extension
    identifier: acme-notes
    name: Acme Notes
    desc: Example external Extension.
    source: inline
    target: definition
    active: true
    meta:
      schema_version: 1
      dependencies: [entity:acme-note]
      definition:
        identifier: acme-notes
        name: Acme Notes
        version: 1.0.0
        desc: Example external Extension.
        required: false
        requires: []
        tags: {external: true}
        entities: [acme-note]
        meta: {}
        setup: null
        api: null
        api_name: null

Entity 记录指向模块文件夹内的代码。Extension 定义依赖该记录，并通过标识符激活它。

4. 安装并检查，但不导入

在包含 acme_notes 的目录中运行：

from pathlib import Path

import heavenbase as hb


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

records = modules.inspect("extension", "acme-notes")
print(records[0]["record"]["source"])

install() 验证描述符，把基于路径的代码捕获为内容寻址制品，通过 Context Registry 发布记录，并返回精确回执。inspect() 读取已存元数据而不物化 AcmeNote。

5. 启用并运行 Extension

使用分离的内存工作区，让这个冒烟测试不会创建持久工作区身份：

ws = hb.HeavenBase(
    "acme-extension-smoke",
    detached=True,
    backends={"main": {"type": "inmem"}},
    context=context,
)

ws.enable_extension("acme-notes")
Note = ws.entities["acme-note"]

note_id = ws.upsert(Note, {"name": "Installed outside HeavenBase"})
row = ws.get(note_id, entity=Note)

print(row["name"])

这个类通过工作区 Context 来自已安装制品。CRUD 使用激活在此工作区注册的规范类。

脚本在检查时打印 inline，在 CRUD 后打印 Installed outside HeavenBase。

6. 主动清理

ws.drop()
modules.uninstall(receipt)
context.close()

drop() 是破坏性的工作区数据清理。uninstall(receipt) 移除精确的已安装模块代。模块卸载不会删除其他已启用该 Extension 的工作区中的数据行。真实应用应保留安装，并正常打开持久工作区。编辑基于路径的源码后请重新安装，因为已安装制品是不可变快照。

7. 把冒烟测试变成包门禁

发布外部模块前：

在干净 Context 中运行安装与惰性检查。
在新工作区中解析并启用 Extension。
运行其 Entity、挂载 API、Toolkit family 或后端行为。
关闭 Context，并证明全新 Context 可以恢复已安装记录。
按精确回执卸载，并确认目标代已经消失。
测试 compatibility 声明的最旧与最新 HeavenBase 版本。

只有在所属工作区 API 稳定后再添加 Toolkit family 与 MCP profile。让 CLI、MCP 与其他界面保持为该 API 之上的适配器。

摘要

一个模块文件夹声明数据、实现目标与 Extension 行为。
安装与检查保持无导入，直到确实需要解析。
生命周期测试应覆盖激活、恢复与精确回执清理。

进一步探索

相关资源：

扩展 - 理解每种 Registry 支持的扩展角色
架构 - 查看 Context 与模块所有权
工作区 - 选择持久或分离生命周期
MCP Toolkit - 添加工具与限定 profile
构建 GlossWise - 在完整外部产品中查看协议

介绍

快速开始

核心概念

开发者

工具箱

LLM

智能体运行时

社区

1. 动机

2. 创建模块文件夹

3. 声明 Entity 与 Extension

4. 安装并检查，但不导入

5. 启用并运行 Extension

6. 主动清理

7. 把冒烟测试变成包门禁

摘要

进一步探索

​1. 动机

​2. 创建模块文件夹

​3. 声明 Entity 与 Extension

​4. 安装并检查，但不导入

​5. 启用并运行 Extension

​6. 主动清理

​7. 把冒烟测试变成包门禁

​摘要

​进一步探索

1. 动机

2. 创建模块文件夹

3. 声明 Entity 与 Extension

4. 安装并检查，但不导入

5. 启用并运行 Extension

6. 主动清理

7. 把冒烟测试变成包门禁

摘要

进一步探索