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

# Capsule

> 将 Python callable 序列化、存储并作为 HeavenBase 实体恢复。

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

<br />

## 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`。

<br />

## 2. 存储函数

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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=...` 以隔离注册表存储。

<br />

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

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
loaded = hb.Capsule.load(name="add", namespace="demo", version="1")
assert loaded.run(left=2, right=3) == 5
```

消费者只需 HeavenBase 与注册表后端访问权。当 source 恢复层可用时，无需导入原始构建者模块。

对隔离测试或应用专用注册表，传入 config 映射而无需在用户代码中构造注册表对象：

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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"},
        },
    },
)
```

<br />

## 4. Docstring 与格式

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

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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`。

<br />

## 5. 架构数据流

Capsule 流程显式且分层：

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

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

<br />

## 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)` 用于高级注册表管理与检查。

<br />

## 7. 信任模型

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

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 报告未存储受信任本地二进制回退。

<br />

## 8. Demo

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

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
rtk uv run python demos/developer/05_capsules_toolkits_mcp.py
```

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

<br />

## 进一步探索

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

  * [工具集 (Toolkit)](/zh/features/toolkits) - 将 Capsule 分组为 MCP 工具集合
  * [扩展](/zh/features/extensions) - `sys-capsule` 属于 `system` 扩展
  * [首个 MCP](/zh/quickstart/first-mcp) - 通过 MCP 提供工具集 (Toolkit)
  * [MCP 工具集 (Toolkit) 参考](/zh/reference/mcp-toolkit/overview) - 完整 Capsule 与 Toolkit API 表
</Tip>

<br />