Skip to content

demo.md

Latest commit

 

History

History
155 lines (108 loc) · 7.75 KB

demo.md

File metadata and controls

155 lines (108 loc) · 7.75 KB
Raw

企业业务 Demo 演示手册

1. 演示目标与准备

本演示证明的是：业务能力只适配一次，人工页面、CLI 和 Agent 都能使用。Agent 不是业务核心，支付实现也不是消费者的固定依赖。

默认全离线：不需要模型凭据，没有真实支付。所有状态保存在一个进程中。 每轮完整演示前请重启 Demo 进程，以恢复未退款的种子订单。

cd /Users/pythonrust/Desktop/projects/caploom
uv sync --all-extras --frozen
uv run --all-extras caploom-demo serve --port 18765 --profile support-human

打开 http://127.0.0.1:18765。默认不启用 Agent，页面显示人工客服配置。 服务仅监听 127.0.0.1，不要为了分享而直接改成公开网络服务。 本次验证发现 8765 已有其他服务，因此使用 18765，并保留原服务不动。

2. 建议演示顺序（约 5–10 分钟）

第一幕：没有 Agent，业务已经完整运行

在“客户支持”搜索“张三”。选择 O-2001，点击“检查规则”。订单金额为 128.00 元， 存在虚构的重复扣款证据。先展示确认弹窗可以取消，再确认执行本地模拟退款。 页面出现退款编号、实际提供方和状态查询结果。

再检查 O-2002：它没有重复扣款证据，业务规则拒绝退款。该限制在后端执行， 不是前端隐藏按钮，也不是让模型自己决定。

第二幕：CLI 是另一个消费者，不是另一个系统

uv run --all-extras caploom-demo call payment.status.get@1 \
  --input '{"order_id":"O-2001"}' --url http://127.0.0.1:18765

CLI 能读到刚才 Web 创建的退款凭据。“调用记录”能区分 web 和 cli， 但它们都经过相同 Capability Invoker 和同一业务台账。

第三幕：后装 Agent，不改客户、订单和支付代码

进入“可选 Agent”，点击“启用 Agent 插件”。页面标注：

离线脚本模型 / 非真实 LLM

输入“检查订单 O-2003 的重复扣款，满足规则时退款并查询结果”，勾选明确批准该订单， 运行 Agent。页面显示逐项工具调用：订单、客户、搜索、订单列表、政策、退款、状态。 执行循环由 Pydantic AI 负责，工具来自现有 Capability Schema。

不要把离线脚本描述成模型理解或推理。 它用于可重复展示框架接入和生命周期。 未勾选批准时，即使模型请求退款，统一入口也会拒绝。批准仅限提示中一个明确订单； 模型不能把 O-2003 的批准用于 O-2004，也不能自行决定幂等键。

点击“卸载 Agent 插件”。回到客户支持或 CLI，业务继续正常运行。 运行时的 Web、CLI、客户、订单及支付 Fiber 不因 Agent 卸载而重建。

第四幕：替换支付实现，消费者代码不变

进入“能力与绑定”。点击“停用支付”，退款和状态能力显示不可用。 Web、CLI 不消失，调用收到 PROVIDER_UNAVAILABLE。

点击“切换到 Payment v2”。两个支付能力被显式绑定到 v2。 回到客户支持搜索“李四”，对 O-2004 执行模拟退款，凭据实际提供方显示 v2。

v1 与 v2 共用应用所有的旧业务台账。用同一幂等键重放以前的退款请求时， 得到的是原凭据及原执行提供方，而不是把历史伪装成 v2 执行，更不会重复退款。

第五幕：出问题时能解释，而不是只输出“失败”

在“插件运行时”依次点击：

  • “演示依赖等待”：出现 PENDING 和缺少的 Service。
  • “演示加载失败”：setup 失败，已登记监听器回滚，Fiber 保留错误。
  • “演示清理失败”：一个 disposer 故意失败，其余 Effect 仍继续清理。

展开 Fiber 历史，查看 Effect、依赖和错误。“调用记录”显示不同消费者和实际提供方。 这是故意的诊断演练；出现两个 409 响应是预期结果，不代表验收脚本失败。

3. 三个配置

配置 用途
empty 只运行能力基础设施与 Inspector，展示空系统
support-human 旧业务适配、Payment v1、Web 和 CLI；无 Agent
support-agent 人工配置再加 Agent 消费者

配置由打包的 TOML 文件定义，只接受已知插件名与显式绑定。不安装远程代码。 切换配置不重置退款台账；重启进程才重置。

“启用/停用/卸载”在当前版本指预注册插件的运行时 mount/unmount，不是 pip 安装或删除包。

4. 可选真实模型模式

真实模型模式是额外选项，不是本地 Demo 的必要条件。它可能发送提示、Schema 和 本地模拟业务结果到你指定的模型服务，也可能产生服务费用。仅使用批准的测试环境。

在启动前设置以下环境变量，不要把凭据提交到仓库、Profile 或演示录像：

CAPLOOM_AGENT_MODE=live
CAPLOOM_MODEL=<该服务实际支持的模型名>
CAPLOOM_MODEL_BASE_URL=<兼容 Chat Completions 的接口基础地址>
CAPLOOM_MODEL_API_KEY=<测试凭据>

远程地址要求 HTTPS；HTTP 仅限回环地址。禁用 URL 用户名、密码、查询参数和片段。 没有配置则明确报 AGENT_CONFIG_INVALID。网络、模型或 SDK 错误返回 AGENT_FAILED， 不会静默退回脚本，也不会声称退款成功。模型摘要不是支付凭据，应查看 calls 和 verified_writes。

真实模式连接代码已通过本机模拟兼容端点验证：实际 SDK 发送请求、包含七个 Tool Schema。 未使用真实外部模型凭据，不承诺某个具体第三方模型的推理效果或全部兼容性。

5. 重复验收与录像

推荐运行自包含联合验收。它选择空闲回环端口，启动自己的全新服务，完成后关闭； 不会重置或关闭已经运行的演示进程，也不会使用开发者的真实模型凭据：

uv run --all-extras playwright install chromium
uv run --all-extras python examples/verify_enterprise_demo.py

默认输出目录是 artifacts/phase1-demo/，可通过 CAPLOOM_EVIDENCE_DIR 更改。 除了真实页面操作，还会启动 CLI 子进程检查同一台账、原幂等键重放、Agent 的七个 工具 Effect 全部销毁，以及提供方切换前后消费者 Fiber ID 不变。 verification.json 包含实际依赖版本、源码 SHA-256、时间和预期故障记录； 重复执行失败时不会保留旧的成功报告。

另一个较轻量的浏览器冒烟脚本用于已经启动、数据全新的人工客服服务：

uv run --all-extras python scripts/browser_demo.py \
  --with-agent --base-url http://127.0.0.1:18765 --artifacts artifacts/demo

输出包括人工流程、Agent、提供方不可用/替换、Inspector、调用记录、手机宽度截图， 以及浏览器视频和 verification.json。最后一次合并验收产物位于 artifacts/phase1-accepted/； 较早的浏览器冒烟证据保留在 artifacts/phase1-final/。 这些是生成证据，不提交 Git；脚本和测试源代码已纳入版本控制。

6. 限制与故障排查

这是可信本地单进程 Demo，不是生产支付、持久化审计、身份认证、权限系统或沙箱。 调用记录仅保留最近 200 条元数据，Fiber 历史为进程内记录。

端口被占用时选择另一个端口，并给 CLI 加相同 --url，不要关闭不属于本项目的进程。 AGENT_DEPENDENCY_MISSING 表示只安装了人工 Demo 依赖，可运行 uv sync --all-extras --frozen 安装已锁定的 Agent extra。 REFUND_DENIED 可能是该订单已在上一轮退款；重启 Demo 或换一个未退款且符合规则的订单。 RUNTIME_BUSY 表示正在排空和切换，待操作完成后再发起新调用。

测试目前存在一条第三方 Starlette/AnyIO 弃用警告，已保留可见，没有屏蔽或降低质量门槛。