工具集 (Toolkit) - HeavenBase

Tool 是 Capsule 的即时视图。Capsule 是持久的可执行载荷。

1. 工具集 (Toolkit) 是什么

工具集 (Toolkit) 在工具名下分组 Capsule 与服务元数据。当你希望一组函数像本地 API、MCP 服务器或模型工具调用导出目标时，使用它。持久模型有意保持精简：

Capsule：存储可执行函数 manifest
Tool：命名一个 Capsule（加可选 serializer Capsule），并暴露 run(...) 与 run_to_str(...)
Toolkit：排序工具、保存引用并导出服务器
sys-toolkit：存储工具集 (Toolkit) manifest 与 Capsule 引用的持久实体行

每个持久化工具保留两个 Capsule 引用：主执行 Capsule 与 serializer Capsule。默认情况下 HeavenBase 使用共享 jstr_serializer Capsule，对 dict 与 list 结果应用紧凑 JSON 序列化。

2. 构建并注册工具集 (Toolkit)

import heavenbase as hb

def add(left: int, right: int) -> int:
    return left + right

def fibonacci(number: int) -> int:
    previous = 0
    current = 1
    for _ in range(number):
        previous, current = current, previous + current
    return previous

toolkit = hb.Toolkit("math-tools", namespace="demo", version="1")

@toolkit.tool(name="add")
def add_tool(left: int, right: int) -> int:
    return add(left, right)

toolkit.add(fibonacci, name="fibonacci", namespace="demo", version="1")

toolkit_id = toolkit.register()

toolkit.register(...) 保存每个工具的主 Capsule 与 serializer Capsule，再将工具集 (Toolkit) manifest 存为有序 Capsule 引用。加载工具集 (Toolkit) 会惰性恢复引用的 Capsule。 Toolkit.register(...) 默认为 overwrite=True。需要显式冲突处理时使用 on_conflict="raise" 或 on_conflict="skip"。紧凑构造可传入 list、pair 或 mapping：

toolkit = hb.Toolkit("math-tools", {"add": add, "fibonacci": fibonacci}, namespace="demo")

3. 从其他路径加载并运行

loaded = hb.Toolkit.load(name="math-tools", namespace="demo", version="1")
assert loaded.run("add", left=2, right=3) == 5
assert loaded.run("fibonacci", number=10) == 55

消费者无需导入创建工具集 (Toolkit) 的文件。它从注册表加载工具集 (Toolkit) manifest，再从各自 manifest 恢复每个 Capsule。需要 MCP 与 Agent 客户端期望的序列化字符串边界时使用 run_to_str(...)：

assert loaded.run_to_str("add", left=2, right=3) == "5"

测试与应用可传入 registry_config=... 隔离注册表存储，同时保持相同公开 API。

4. 架构数据流

工具集 (Toolkit) 执行是 Capsule 上的薄层：

Toolkit.add(callable) 将 callable 捕获为主 Capsule，并解析 serializer Capsule（默认 jstr_serializer）。
toolkit.register() 持久化每个工具的两个 Capsule，再存储含有序 Capsule 引用的 sys-toolkit 行。
Toolkit.load(...) 解析 manifest 并将每个引用的 Capsule 恢复为 Tool。
Toolkit.run(name, **kwargs) 本地调用所选主 Capsule，返回原始 Python 值。
Toolkit.run_to_str(name, **kwargs) 运行工具并通过 serializer Capsule 传递结果。
Toolkit.to_fastmcp() 用签名兼容的 FastMCP 函数包装每个 Tool，返回序列化字符串。
Toolkit.to_anthropic_tools(...) 导出带 allowed_callers 的独立 Anthropic programmatic tool schema。

5. 通过 MCP 提供

from fastmcp import Client

server = loaded.to_fastmcp()

async with Client(server) as client:
    tools = await client.list_tools()
    result = await client.call_tool("add", {"left": 2, "right": 3})
    assert result.content[0].text == "5"

也可打印客户端配置：

print(loaded.to_mcp_json(transport="http", host="127.0.0.1", port=7011))

用 toolkit.serve(...) 阻塞或后台提供。默认位于 CM_HVNB 的 heavenbase.mcp（transport、host、port、wait）。

6. 导入 MCP 服务器

client_toolkit = hb.Toolkit.from_fastmcp(server, name="math-client")
assert client_toolkit.run_to_str("add", left=2, right=3) == "5"

FastMCP 客户端代理仅用于即时执行。它们无法用 register() 持久化，因为闭包持有 live 服务器句柄。

7. 工作区工具集 (Toolkit)

每个工作区仍可成为工具集 (Toolkit)：

workspace = hb.HeavenBase("notes", backends={"main": {"type": "inmem"}})
toolkit = workspace.to_mcp(name="notes")

print(toolkit.list_tools())

工作区工具集 (Toolkit) 组装已注册的工具集 family：核心工作区 family 暴露实体定义、目录 (Catalog) 发现、CRUD、count、查询 (Query) 与 explain 工具。 Family spec 与别名会作为 toolkit_family 行镜像到 sys-metaschema；即时工作区工具集 (Toolkit) 仍无法注册，因为闭包持有 live 工作区对象。

8. Demo

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

demo 创建持久数学工具集 (Toolkit)，通过 Toolkit.load(...) 加载回来，展示 Capsule docstring 与格式转换，并检查 FastMCP 能否列出与调用工具。

进一步探索

相关资源：

Capsule - 每个 Tool 背后的持久可执行 manifest
扩展 - sys-toolkit 属于 system 扩展
HeavenBase MCP - MCP 传输与客户端配置
首个 MCP - 持久化 Capsule 工具集 (Toolkit) MCP 提供
MCP 工具集 (Toolkit) 参考 - 完整 API 表与 CLI 命令

​1. 工具集 (Toolkit) 是什么

​2. 构建并注册工具集 (Toolkit)

​3. 从其他路径加载并运行

​4. 架构数据流

​5. 通过 MCP 提供

​6. 导入 MCP 服务器

​7. 工作区工具集 (Toolkit)

​8. Demo

​进一步探索

1. 工具集 (Toolkit) 是什么

2. 构建并注册工具集 (Toolkit)

3. 从其他路径加载并运行

4. 架构数据流

5. 通过 MCP 提供

6. 导入 MCP 服务器

7. 工作区工具集 (Toolkit)

8. Demo

进一步探索