47 步噩梦

UCP 电商流程中涉及许多隐藏步骤。在传统店面中，用户点击按钮，浏览器会显示发生了什么。在 UCP 世界中，购物者的意图由 AI 助手解释，并通过商务网关路由到目录、结账和支付系统——通常没有任何 UI 来"显示真相"当出现问题时。这就是为什么团队依赖交互建模（序列图）来使 API 驱动的行为在实施之前变得可理解和可审查。

代理商务在演示中感觉"简单"，但在生产中它变成了一个难以推理、更难调试的隐形多系统对话。解决方案是将通用商务协议（UCP）视为分布式系统，并在编码之前端到端地映射握手流程。

了解 UCP 已经提供了什么

UCP 围绕代理和商家之间的发现 + 协商设计，而不是每个开发者发明一次性集成。它定义了"核心能力"（如 Checkout、Discovery、Fulfillment），使商务可以分层组合，而不是成为脆弱的单体。

UCP 还将结账建模为状态机。协议明确处理 incomplete、requires_escalation 和 ready_for_complete 等状态。当代理无法自主进行时（例如，缺少配送信息），商家服务器会响应结构化的 continue_url。这允许代理将用户转交到安全的 Web 视图以完成任务，然后通过嵌入式协议通道（JSON-RPC 2.0）恢复对话。

简单来说：UCP 为您提供原语（协商、状态、逃生舱口）。您的工作是编排、用户体验和可靠性。

开发者实际构建什么（"胶水代码"）

当 UCP 处理后端时，您仍然需要构建代理的大脑。您的代码拥有决策（形成查询、排序结果）、状态处理（对 incomplete 信号做出反应）和信任层（收集明确的支付确认）。

在我们的架构分析中，最大的风险恰好出现在流程暂停或分支的地方：

"幻觉"差距： 如果目录返回零结果怎么办？
"缺失数据"循环： 如果用户没有提供邮政编码怎么办？
"静默授权"风险： 用户真的说了"现在付款"吗？

这些不是 Shopify 问题；它们是编排问题。这就是为什么可视化地图至关重要。

47 个交互：谁拥有什么？

我们分解了标准的 47 步购买流程，以准确显示您的责任从哪里开始、在哪里结束。

阶段	步骤	主要由 UCP / 商家处理	主要由开发者处理（代理端）
意图 → 结构化搜索	1–6	无。这是上游用户意图捕获。	将模糊意图转换为稳定的 `Catalog Query`。记录假设。避免幻觉约束。
目录查询 → 产品	7–11	网关响应匹配的产品（或空集）。	选择查询策略。优雅地处理零结果状态（"澄清并重试"循环）。
选择 → 结账会话	12–20	UCP 创建会话 ID 并定义结账状态机。	持久化 `session_id`。准备处理状态变化（不仅仅是"成功/失败"）。
必填字段循环	21–30	UCP 发出 `incomplete` 或 `requires_escalation` 信号。	提示用户填写缺失字段。幂等地提交更新。重新请求总计。
支付确认	31–38	支付收集委托给处理程序（Shop Pay 或其他）。	强制执行明确的确认门。没有用户信号不要捕获资金。
订单状态 → 通知	39–47	商店对状态和履行更新具有权威性。	将状态代码映射到您的 UI。实现关联 ID 以进行支持追踪。

为什么 FlowZap 是正确的格式

文档会腐烂。静态图表会被忽略。

FlowZap 通过序列图模式解决了这个问题。您在代码中定义一次逻辑——映射代理和 UCP 网关之间的精确交接——我们自动渲染两个视图：

架构师视图（序列）： 精确的 API 调用、参与者的严格类型（Shopper、Assistant、Gateway）以及循环和等待状态的可视化。
利益相关者视图（流程）： 简化的旅程图，解释正在发生什么，没有协议噪音。

这确保您的 PM、首席开发人员和 QA 团队都在查看同一个真相来源。

不要从零开始。使用模板。

我们知道您不想花费整个冲刺来映射 47 个交互步骤。所以我们为您完成了繁重的工作。

我们已将 Shopify UCP 蓝图作为免费模板发布在 FlowZap 库中。它预加载了：

完整逻辑： 标准购买流程的所有 47 个步骤，以可编辑的 FlowZap 代码编写。
注释所有权： 我们将步骤标记为 // UCP Managed 与 // Dev Required，以便您可以立即看到您的实施范围。
关键状态： 为 missing_info 和 payment_confirmation 预构建的循环，准备好用于您的特定逻辑。

下载 .fz UCP 模板

三个"死亡区"（集成通常失败的地方）

图表很长，但失败模式聚集在可预测的地方：翻译、数据收集和支付信任。以下是值得过度记录（和过度测试）的三个区域，因为它们会产生最昂贵的错误。

死亡区 1："幻觉差距"（步骤 4-10）

AI 助手必须将模糊请求转换为结构化查询，然后网关查询商店目录并返回匹配的产品。如果目录返回"没有相关内容"，最糟糕的行为是助手自信地"编造"一个选项；正确的行为是分支到澄清（"颜色？"、"预算？"、"品牌？"）并使用更严格的约束重试。

FlowZap 在这里有帮助，因为您可以将重试建模为一流循环，而不是将其埋在临时提示逻辑中。FlowZap Code 甚至支持循环片段语法，旨在紧凑地表达重试逻辑，这正是"澄清并重试"的含义。

死亡区 2："缺失数据循环"（步骤 21-30）

结账初始化后，商店返回必填字段（送货地址、送货选项、电子邮件等），助手必须暂停协议以向购物者询问缺失数据。这是许多代理流程在生产中死亡的地方：缺失字段响应不是"错误"，而是需要用户提示和等待状态的状态转换。

图表明确显示"向购物者询问缺失信息"、"等待"，然后"提交买家详细信息"，接着是"重新计算总计"和"返回订单摘要"。这不是填充——这些步骤是您实现幂等性和防止用户在结账过程中改变主意时重复提交的蓝图。

死亡区 3："静默支付"风险（步骤 31-38）

图表使支付确认成为明确的握手：显示订单摘要、请求确认、等待，然后发送支付意图并继续授权/捕获。这种分离是安全护栏：它在"推荐/对话"和"资金移动"之间强制建立清晰的边界。

对于开发者来说，这是序列图发挥作用的地方：哪个参与者负责每个操作以及支付处理器何时被调用变得显而易见。在哪里附加审计日志（摘要中显示了什么、确认了什么以及何时创建了意图）也变得显而易见。

底线

代理商务不仅仅是将 LLM 连接到 API；它是关于管理用户、机器人和严格银行协议之间复杂的异步对话。"演示"和"产品"之间的区别在于您的系统如何优雅地处理混乱的中间部分——重试、缺失的地址和支付确认。

停止猜测状态机。Fork 我们的蓝图，映射您的特定边缘情况，并为您的团队提供他们需要的可见性以自信地交付。

Shopify UCP 开发者指南