Capsule 是带着行李、指纹与一位严格边检员的函数。
1. 动机
对函数做 pickle 可以保存字节，却不一定保留可检查的公共身份、输入模式、docstring、恢复策略或信任决定。导入模块路径很可读，但当消费者没有同一份源码检出时就会失败。Capsule 记录 callable 身份、签名、模式、docstring、依赖、恢复层、能力、信任标志与完整性指纹。它现在可以像原函数一样工作，稍后则按显式策略恢复。
恢复 Capsule 会执行 Python 代码。元数据让这个边界可审核；它不会让不可信代码变安全。
2. 捕获并调用函数
Capsule 直接接受 callable，并保留类似函数的元数据。Capsule.from_func(...) 是等价的显式构造器。
它也能用作装饰器：
3. 理解恢复层
默认捕获会考虑 source 与 import-path 层。可信本地cloudpickle 层是可选项，默认关闭。
4. 运行前检查并验证
verify() 在不执行 callable 的前提下，用同一 manifest 中的指纹检查已存 source 与二进制载荷。这是记录完整性检查，不是与今天实时源码的比较，也不是代码安全证明。
to_str("json")、to_str("yaml")、to_str("source") 与 to_str("docstring") 暴露可审核形式。Capsule.from_str(...) 恢复 JSON 或 YAML manifest。
5. 让应用工作区拥有 Toolkit Capsule
具体 Toolkit 持久化会把sys-toolkit 行与每条引用的 sys-capsule 行存入一个显式应用工作区：
Capsule.register() 与 Capsule.load() 仍是配置 Capsule 注册表之上的高级 Context 私有管理。只有当 Capsule 真正独立于应用 Toolkit 时才使用它们；需要隔离时请传递匹配的 resolver/config 权威。
6. 加载并运行独立 Capsule
register() 默认为 overwrite=False。load() 验证已存 checksum 并惰性恢复。Capsule.list(...) 检查已存数据行；Capsule.delete(...) 默认写入 tombstone。
对于普通 Toolkit 代码，请优先使用 toolkit.register(ws=...)，让 Capsule 与 Toolkit 行共享显式应用工作区。
7. 在 Tool 后面使用 Capsule
Tool 是一个执行 Capsule 加可选 serializer Capsule 的函数式视图。Toolkit.add(...) 接受 Tool、Capsule 或普通 callable，并把三者规范化为同一契约。
即使本地 Tool 与 Capsule 能像其包装函数一样工作，Agent 与 MCP 调用仍保持关键字参数形式。
8. 保持显式信任边界
- 把已安装模块制品与 Capsule 行视为源码仓库。
- 除非已审核本地 callable 确实需要，否则保持
include_cloudpickle=False。 - 把 Tool 暴露给智能体前审核输入模式。
- 把 MCP profile 限定到所需的最少工具与实体。
- 使用显式工作区与 Context，避免可执行状态漂移进环境权威。
- 对有意生命周期变更使用 tombstone 或新版本；不可变修订历史并不是通用应用迁移系统。
摘要
- Capsule 通过可检查的恢复层与指纹捕获 callable 行为。
- 应用工作区拥有持久 Toolkit 引用的 Capsule。
- 完整性不等于安全；可执行负载仍是受信代码。