Marico's space

最近在设计一套同时面向人类用户和 AI Agent（人工智能代理）的商务系统，踩了几个状态同步的坑，这篇把核心问题说清楚。

很多产品加了 Agent 接口之后，很容易把它当成第二个应用来对待：网页界面给人用，API 工具给 AI 用。UI 层这么分没问题，但一旦延伸到交易模型，问题就来了。

如果人机两套接口用的订单状态、权限规则、完成定义都不一样，系统实际上就有两套"商业现实"。人看到的是"待处理"，Agent 报告的是"已完成"。网页里需要人工确认的步骤，到了 Agent API 可能变成无人审核的捷径。出问题时，两边根本说不清楚同一件事。

更稳妥的设计是：一个协议，两个接口。

不同所长，共享状态

PWA（渐进式网页应用）和 MCP（模型上下文协议）服务器不该长得一模一样，它们的操作者是不同的。

人机界面擅长展示条款、收集明确授权、管理身份、帮用户排查异常。Agent 接口擅长结构化查询、对比分析、重复准备工作、遵循明确的机器可读契约。

两套接口可以分工，但真相只能有一份：

Human PWA Agent MCP
--------- ---------
inspect terms read structured facts
manage identity search and compare
review a proposed action prepare a request
perform Passkey approval receive the resulting state
inspect exceptions continue from explicit outcomes \ / one state machine

重要的不是视觉一致性，而是行为一致性。两套接口必须对以下内容达成共识：被操作的实体是什么、当前状态是什么、允许的转移是什么、该转移产生了什么凭证。

权限应该描述动作

持有凭证不应该默认可执行所有写操作。

WebAZ 发布了一份能力矩阵，认证的 Agent 写操作映射到具名的动作作用域。未声明的写操作默认拒绝。这让授权成为集成契约的一部分，而不是藏在客户端代码里的假设。

概念上，Agent 声明可以这样写：

{ "allowed_actions": [ "search", "place_order" ]
}

具体集合没那么重要，原则才重要：权限应该命名动作及其边界。搜索能力不等于下单权限。准备订单的权限不等于审批不可逆步骤的权限。

准备不等于同意

按可逆性拆分动作，Agent 工作流更容易推理：

1. 读取：查看公开的或已授权的状态。
2. 准备：搜索、对比、询价或组装请求。
3. 提交：创建商业义务或变更需担责的状态。
4. 结算：转移价值或敲定不可逆结果。

Agent 在前两个层级可以非常有用。从准备到提交，应该有明确的规则约束，而不是"买最好的那个"这种模糊指令。

在 WebAZ 中，风险操作会返回一个审批 URL。人类在浏览器界面完成 Passkey（通行密钥）认证流程。Agent 可以准备动作，在协议报告结果后继续执行，但在审批环节不会冒用身份。

有些操作有铁律：没有任何声明的作用域可以覆盖"必须有人类在场"的要求。这是协议属性，不是留给各个 Agent 客户端自己决定的偏好。

仅探索的接口也有价值

不是每个 MCP 端点都需要通往结算的路径。

WebAZ 经过审查的 shopping-v1 接口有意设计为仅探索用途。它暴露一个搜索工具用于检索已审核的上架商品，无法创建订单或转移资金。这个更小的接口让买家和开发者可以在引入重大操作之前，先评估 Agent 能否诚实呈现商品信息和未知项。

这是一种有用的部署模式：

• 从窄口的只读接口起步；
• 把输出和人类可见的记录做对比；
• 加入带明确状态的准备动作；
• 仅当身份、权限、恢复机制都定义清楚后才加入提交能力；
• 把"必须有人类在场"的要求放在 Agent 无法绕过的位置。

集成检查清单

在给商务系统加 Agent 接口之前，先问自己：

1. 网页端和 Agent 读取的商品 ID、订单 ID 是否相同？
2. 两套接口能否命名同一个当前状态？
3. 每个 Agent 写操作是否映射到明确的作用域？
4. 未声明的写操作是否被拒绝？
5. 准备和提交是否分为独立的转移？
6. 人类审批是否发生在用户可以检查的界面上？
7. Agent 能否从确认结果恢复，而不是靠猜动作是否成功？
8. 操作失败时，两套接口能否产生同一条审计记录？

如果答案因接口而异，问题不只是 API 设计，而是交易模型分裂了。

一个协议就是产品本身

面向 Agent 的商务不等于在真实系统旁边维护一个 AI 快捷方式。它应该意味着：通过另一个接口暴露真实系统，同时保持让结果可理解的规则。

WebAZ 把当前的集成契约、能力矩阵、负空间规则发布为机器可读文档：

• webaz-integration.json
• webaz-capabilities.json
• webaz-negative-space.json

PWA 和 MCP 做的是不同的活。但协议只有一个。