已有业务 API
↑ 少量适配，不导入 Agent SDK
Capability Provider
↑ 同一输入、输出、错误契约
Registry + 显式 Binding + Invoker
↑
Web / CLI / 可选 Agent / 未来其他消费者
Caploom 不要求企业把业务流程改成 Agent 流程，也不声称能自动兼容所有旧系统。 真正需要的是一个明确、可测试的适配边界。
普通 Python 接入现在优先使用 快速接入 SDK，可运行入口是
examples/sdk_quickstart.py。下面的分层仍然适用；SDK 只是代为创建 Plugin、
注册 Effect 和装配调用入口，不要求迁移到 Agent 框架。
演示中的 src/caploom/demo/domain.py 模拟一个已有同步业务 API。
它只使用 Python 标准库，负责客户、订单、退款规则、事务及幂等台账。
Agent 不能批准不符合规则的退款。Web 不能通过省略“检查规则”调用绕过写入时的校验。 两个支付适配器共享应用所有的业务状态，而不是各自维护互相冲突的退款账本。
接入实际系统时，应把已有数据库事务、幂等实现和权限校验保留在原业务系统中。 Demo 的内存锁和台账不是生产实现的替代品。
demo/contracts.py 定义七个业务契约，使用版本化 Capability ID。
例如 payment.refund@1 的输入是订单编号、原因和幂等键；输出是退款凭据。
Schema 校验复用 Pydantic，而不是自己实现 JSON Schema 验证器。
业务契约可以先用于人工系统。后续生成 Agent Tool Schema 时直接引用同一输入 Schema， 不会复制一份“Agent 特供退款规则”。
demo/providers.py 中的适配器负责三件事：把已验证输入转换成原方法参数、调用原 API、
将原结果与预期业务错误转换为契约结果。没有模型、提示词或 Agent 循环。
Provider 通过 PluginContext Effect 拥有自己的能力注册。移除时关闭新调用， 等待已有调用，再移除自己的注册，不能误删替代实例。
现在这些重复注册由 Provider.expose() 和 build() 完成。旧业务对象可以通过
service= 借用；Demo 用 ServiceRef 保留原应用所有权。需要插件自建资源时用
resource= factory，详见 SDK 的线程与资源规则，不要默认关闭借来的对象。
同步阻塞的生产 API 不能直接阻塞事件循环；应按其官方驱动/SDK选择异步调用或明确的 线程执行适配。演示域方法仅执行短小的本地内存操作，不能据此推断真实 I/O 可直接照搬。
Web/CLI 调用 Consumer.call()，Agent Tool 也转到同一个 Invoker。
Invoker 集中处理输入/输出校验、显式绑定、确认、超时、在途计数与诊断。
业务提供方被替换时，消费者只知道同一个 Capability ID，不缓存具体 Provider 对象。 本演示在切换 v1/v2 时断言 Web、CLI、客户和订单的 Fiber ID 不变。
demo/agent.py 是可选插件。只有启用它时才导入 Pydantic AI/OpenAI SDK。
七项能力通过明确 allowlist 暴露，未来增加能力不会自动暴露给模型。
Agent 使用成熟 SDK 执行循环；Caploom 只提供工具投影和宿主授予的调用上下文。 退款批准限定到提示中的一个明确订单，幂等键由调用上下文生成，模型不能自行替换。 卸载时先等待运行结束，再移除 Tool 注册和 Agent Service。
从人工 Demo 到 Agent 接入的工作中，domain.py、providers.py、contracts.py
无需新增 Agent 逻辑。零改动是针对这组已实现适配边界的验证，不是对所有旧代码的承诺。
实际部署需要按企业环境补充身份、权限、审批、持久化审计、Secret 管理、速率限制、 长期任务和远程故障语义。MCP/HTTP 等协议应作为适配层，优先复用官方 SDK， 不应取代核心业务契约。任意第三方插件的隔离、签名和市场不是当前 Phase 1 的范围。