Capsule - HeavenBase

Capsule 是受信任本地的可执行清单。仅存储你拥有或已审查的代码。

1. Capsule 是什么

Capsule 是 Python callable 的持久形态。它存储足够元数据以便日后恢复并运行函数，包括：

身份：namespace、name 与显式 version
签名：参数、返回注解与 JSON schema
恢复层：source、import path 与可选 cloudpickle 载荷
依赖：Python 版本与 source 中发现的 imports
能力：是否可本地使用、导出到 MCP，或导出为 Anthropic programmatic tools
信任与指纹：仅本地执行标志与供审查的 hash

默认恢复顺序为 source 优先、import path 其次、在显式捕获二进制载荷时 binary payload 最后。source 优先恢复使 Capsule 可在不同文件夹加载，而无需导入最初定义该函数的文件。 Capsule 是必需 system 扩展（sys-capsule）拥有的系统实体。规范实现位于 src/heavenbase/extensions/system/capsule/；请通过 import heavenbase as hb 使用 hb.Capsule。

2. 存储函数

import heavenbase as hb

def add(left: int, right: int) -> int:
    """Add two integers.

    Args:
        left: First integer.
        right: Second integer.

    Returns:
        Sum of both integers.
    """
    return left + right

capsule = hb.Capsule.from_func(
    add,
    name="add",
    namespace="demo",
    version="1",
    include_cloudpickle=False,
)

capsule_id = capsule.register()

version 是身份的一部分。HeavenBase 不会从内容 hash 自动递增 version；当你需要新的公开可执行合约时发布新版本。 Capsule.register(...) 默认为 overwrite=False。在测试或 demo 中传入 registry_config=... 以隔离注册表存储。

3. 在其他位置加载并运行

loaded = hb.Capsule.load(name="add", namespace="demo", version="1")
assert loaded.run(left=2, right=3) == 5

消费者只需 HeavenBase 与注册表后端访问权。当 source 恢复层可用时，无需导入原始构建者模块。对隔离测试或应用专用注册表，传入 config 映射而无需在用户代码中构造注册表对象：

loaded = hb.Capsule.load(
    name="add",
    namespace="demo",
    version="1",
    registry_config={
        "workspace": "math-capsule-test",
        "backend": {
            "main": {"type": "sqlite", "name": "main", "database": "file:/path/registry.db"},
        },
    },
)

4. Docstring 与格式

Capsule 在捕获时解析 callable docstring，并可从存储的签名元数据合成 callable docstring。

doc = loaded.manifest.source["doc"]
assert doc["summary"] == "Add two integers."
assert doc["params"]["left"] == "First integer."

print(loaded.to_str("docstring"))
print(loaded.to_str("source"))
print(loaded.to_str("json"))
print(loaded.to_str("yaml"))

Capsule.from_str(...) 将 JSON 与 YAML 清单字符串恢复为 Capsule。

5. 架构数据流

Capsule 流程显式且分层：

Python callable → 内部序列化策略检查 source、import path、docstring、签名、依赖与可选二进制回退。
策略 → CapsuleManifest 记录身份、schema、恢复层、能力、信任标志与指纹。
capsule.register() → 隐藏注册表工作区存储活跃 sys-capsule 行。
Capsule.load(...) → 按 id 或 namespace/name/version 读取清单；加载时验证 checksum。
Capsule.to_func() → 恢复策略依次尝试 source、import path、受信任本地 binary payload。
Tool 与 Toolkit 包装 Capsule，用于本地调用、MCP 提供与 programmatic tool 导出。

JSON 序列化器也将 callable 路由到相同内部 capsule 序列化策略。当 callable 无法捕获为 Capsule 时，回退为轻量 module.qualname 引用，而非使通用 JSON 序列化失败。

6. 注册表记录

Capsule 作为隐藏注册表工作区中的普通 HeavenBase 实体存储：

sys-capsule：活跃清单行，含身份、manifest 载荷、能力、指纹，以及覆盖时的 last_reason

不可变修订历史尚未实现。覆盖会更新活跃行并在 last_reason 中记录原因。默认注册表配置位于 CM_HVNB 的 heavenbase.capsule.registry。当 demo、测试或应用应将可执行数据保留在专用文件时，可传入 registry_config=...。多数应用代码应优先 capsule.register(...) 与 Capsule.load(...)。CapsuleRegistry 仍可通过 hb.capsule_registry(config) 用于高级注册表管理与检查。

7. 信任模型

恢复 Capsule 会执行 Python 代码。将 Capsule 注册表视为源代码仓库，而非惰性数据文件。

Capsule 不会针对原始 Python 函数的当前内容自行验证。注册表 checksum 仅验证加载的 Capsule 载荷仍与同一 manifest 存储的 hash 匹配。这是记录完整性检查，而非代码安全证明。 HeavenBase 在线程安全内存 LRU 缓存（heavenbase.capsule.registry.trust.verify_cache_size）中缓存成功的 checksum 检查，因此进程对每个缓存键验证一次 Capsule 载荷，而非每次加载或恢复都重算 hash。默认使用仅 source 的 Capsule。include_cloudpickle 默认为 False；仅对无法由 source 或 import path 表示、且已审查的本地代码启用二进制载荷。若仅 source 恢复失败，HeavenBase 报告未存储受信任本地二进制回退。

8. Demo

从 HeavenBase 源码检出运行数学 demo：

rtk uv run python demos/developer/05_capsules_toolkits_mcp.py

demo 将 add、mul、sub、div、mod 与 fibonacci 存为 Capsule，存储工具集 (Toolkit)，通过公开 API 加载，并用 FastMCP 客户端验证 MCP 服务器。

进一步探索

相关资源：

工具集 (Toolkit) - 将 Capsule 分组为 MCP 工具集合
扩展 - sys-capsule 属于 system 扩展
首个 MCP - 通过 MCP 提供工具集 (Toolkit)
MCP 工具集 (Toolkit) 参考 - 完整 Capsule 与 Toolkit API 表

​1. Capsule 是什么

​2. 存储函数

​3. 在其他位置加载并运行

​4. Docstring 与格式

​5. 架构数据流

​6. 注册表记录

​7. 信任模型

​8. Demo

​进一步探索

1. Capsule 是什么

2. 存储函数

3. 在其他位置加载并运行

4. Docstring 与格式

5. 架构数据流

6. 注册表记录

7. 信任模型

8. Demo

进一步探索