Toolkit 是一套小型 API，为 Python 与智能体都穿上了合脚的鞋。
1. 动机
同一个函数很容易先为 Python 包装一次，再为 MCP 包装一次，最后为模型提供商包装第三次。随后这些包装器会在名称、模式、序列化器、持久化与授权上产生分歧。 HeavenBase 使用三个可组合值：Capsule拥有可执行 manifest 与恢复契约。Tool拥有一个公共工具名、模式、执行 Capsule 与序列化器。Toolkit拥有有序 Tool 集，以及持久化与导出行为。
2. 构建函数式 Tool
Tool 接受普通 callable、已有 Capsule 或装饰器选项。它为本地调用保留包装签名，同时为智能体边界暴露 JSON 兼容工具模式。
默认序列化器生成紧凑 JSTR 输出。只有当某个工具需要不同文本边界时，才设置自定义 callable 或 Capsule。
3. 组合 Toolkit
Toolkit 接受列表、(name, item) 对、映射、Capsule、Tool 或 callable。add(...)、add_many(...) 与 @toolkit.tool(...) 都会把项目规范化为同一个 Tool 契约。
run(...) 返回原始 Python 值。run_to_str(...) 把该值交给 MCP 与智能体客户端使用的 Tool 序列化器。
4. 在显式工作区中持久化
register(ws=...) 存储一条 sys-toolkit 行，以及每个 Tool 引用的主 sys-capsule 与 serializer sys-capsule 行。相同 id 内容默认使用覆盖模式；需要显式冲突策略时使用 on_conflict="raise" 或 "skip"。
省略 ws= 会使用仅加载已有项的 hb.HeavenBase.load()。它绝不会创建默认工作区或进程全局 Toolkit 存储。
5. 加载、列出、描述与删除
delete(...) 默认写入 tombstone。删除 Toolkit 行不会自动删除其他 Toolkit 可能引用的 Capsule 行。
版本是显式字符串。公共工具契约改变时使用新版本；可复现性重要时主动选择版本。
6. 导出 FastMCP 服务器
to_mcp_json(...) 打印客户端配置，使用 serve(...) 运行传输。除非另一个可信层提供认证与传输安全，否则网络服务器应留在 loopback。
Toolkit.from_fastmcp(...) 在实时服务器上创建客户端 Toolkit。运行时代理 Tool 无法持久化，因为它们闭包捕获的是服务器句柄，而不是持久函数。
7. 把工作区变成限定范围的 Toolkit
运行时工作区 Toolkit 无法持久化，因为其函数闭包捕获一个实时工作区。请改为把底层 profile 与 Toolkit-family 定义持久化为 Registry 模块记录。
8. 发布外部 Toolkit Family
外部模块可以声明：- 带持久 builder 目标与精确工具名的
toolkit_family - 带工具、实体、Skill、序列化器、依赖与可选
extends的mcp_profile - 当打包序列化器不合适时使用的
mcp_serializer
9. 保持窄智能体边界
- 优先选择支持任务的最小 profile。
- 对 Agent/MCP 使用仅关键字参数分派，并验证不可信输入。
- 让文件系统、网络、凭据与破坏性权威保持显式。
- 把
full视为可信管理。 - 把应用逻辑保留在工作区 API 中；Tool 函数应保持为薄适配器。
- 测试精确导出模式与真实 list/call 往返。
摘要
- Tool 在一个函数式契约背后规范化 callable 与 Capsule。
- 持久 Toolkit 与引用的 Capsule 属于显式应用工作区。
- Profile 与 serializer 让 Agent 权威保持狭窄且可检查。