Anthropic Commerce Agents：一次批准怎样真正变成一次商店修改

商家批准一笔调价后，最难的往往才刚开始：后台是否真的写入，等待期间的商品事实是否变化，一组操作只成功一半又该怎么办？Anthropic 的 Commerce Agents 把建议、预览、批准和写入分开，提供了可检查的控制骨架；它与 Shopify 的适配代码也暴露出一个关键边界：“台账已应用”与“业务状态已兑现”必须分别证明。

这里分析的是两个固定版本的公开参考实现，不是真实商家的经营成效。Anthropic 仓库里的 ACME 商店和交易是演示材料；Shopify 适配器采用同一套核心，因此两者不是独立效果实验。项目范围｜Shopify 适配范围

让模型建议修改，让应用掌握身份与批准

商家助手的后台接口 MerchantBackend 将读取、暂存与执行明确分开。模型传入商品标识和新价格；后台从当前商品取得原价、币种等事实，从会话取得经营主体和操作人，生成包含前后值的 StagedChange。凭据由承载助手的应用持有，不进入模型。带规格的商品要落实到变体；不能把一个商品系列的标识当成具体规格价格。后台契约

这份暂存记录是预览和执行的共同对象。核心规则检查单次项目数、价格或折扣幅度、受保护字段等；同一对象同一字段的重复修改也要处理，避免分成多行绕过限制。规则值属于部署配置，不能把演示配置当成真实商店政策。变更规则

执行器还检查记录来源与会话关系，并在执行时重新检查当前规则。要求宿主批准的部署中，应用批准的是指定 change_id，临时批准标记由宿主加入，调用完成后清除。模型复述“已获同意”不能制造这个标记；批准本身也不会提前把台账从 staged 改为 applied。门禁｜执行器

三种运行方式不能混成一种安全保证。直接 Messages API 运行时自己驱动工具循环；Agent SDK 将工具接到进程内；Managed Agents 把循环交给平台，并依赖平台对写入与记忆工具的审批策略。是否由核心门禁检查宿主批准，需连同运行方式一起核对，不能只看到一个配置字段就断言所有部署都有人审。Managed 配置说明

同一个 applied，在两个后台里含义不同

可横向查看，点击打开原尺寸 ↗

固定版本 Anthropic fd4d592、Shopify d68c7fa：图分开展示两种实现；故障窗口是源码与离线探针支持的观察，不是客户事故。

后台契约要求：先写业务系统，成功后再标记 applied；写入失败应抛错，使记录保持 staged。Anthropic 的内存零售示例却先调用 ledger.apply，再调用 _apply_to_live_state。顺序差异可以直接从原函数看见。契约｜零售实现

既有研究对这个固定版本做过离线故障注入：在台账推进后、实际状态写入前使写入函数抛错。观察到业务值未变、台账已 applied，而重试因记录已进入终态被拒。这是参考代码的局部故障观察，没有调用真实商店，也不是客户事故。它说明迁移时不能只复用 happy path：若写入和记账不在同一事务，必须设计“执行结果未知”如何查回和修复。

Shopify 适配器采用相反顺序：writer 先向 Admin API 发送变更，成功后后台才推进台账。writer 按目标分组逐个写入，异常携带 completed，告诉上层此前哪些目标已写入。这保留了部分成功信息，但不是整个批次的原子提交。Shopify 后台｜writer

促销和营销活动又有不同语义：此适配器只在台账记录决定，并在结果中明确说明，没有创建实际折扣对象或渠道营销活动。它们不能与已写入价格、库存的 applied 混为“已经上线”。暂停商品也映射为 Shopify 的 DRAFT，会移出所有销售渠道，而非只隐藏某个网页。动作映射与限制

重试安全取决于修改的是“目标值”还是“增量”

库存 writer 计算的是暂存前后值之差，再读取当前库存，把这个增量发送给 API。changeFromQuantity 使用的是执行前刚读到的 available，不是预览时的库存。因此这次比较能防止“刚读完又被别人改”的竞争，却不会自动拒绝“等待批准期间已经变化”的预览。

既有离线探针使用原 writer 和本地替身 API：预览库存 25→35，外部先增加 5，执行后得到 40。结果符合“再增加 10”的代码语义，却不等于“把库存设为 35”。同一个批准界面若没有说清这两种意图，人和系统会以为自己批准了不同的操作。库存写入

第二个探针让一批两个目标中的后一个失败；整份记录仍 staged，重批后第一个目标的增量又执行一次。源码每次调用都会生成新的 idempotencyKey，即帮助接口识别重复请求的标识；它没有把同一业务变更的重试固定为同一键。这个观察不能推出 Shopify API 没有幂等能力，只说明此适配器的批次恢复还需要接入方补齐。接入时应按已完成目标恢复，或用持久化的业务操作标识和后台读回，不能整批盲重跑。

模型看见的上下文也有工程边界

Skill 是按任务加载的操作说明。注册器先暴露名称与简介，load_skill 才读取正文；部署未加载技能目录时，不会凭空拥有这些方法。稳定的系统指令和工具定义构成请求前缀，购物车、页面、当前时间、商家事实与记忆等动态内容放在后续系统块。时间取整到小时，减少无意义变化对缓存的影响；缓存标记只加在本次请求副本，避免污染保存的会话。技能注册｜请求装配

这解释了“缓存”与“记忆”的区别：缓存减少重复计算；记忆存储需要另外配置，决定哪些偏好或约束跨会话保留。商家记忆按 merchant_id 组织，可能服务同一商家的多位操作人，不能自动当作个人隔离。动态块、技能全文、历史工具结果都有预算；把所有资料塞进提示词既不是完整性保证，也会改变成本和可用上下文。记忆实现

分析任务还可以委派给只读查询路径，但只读必须由后台执行环境落实。零售示例使用 SQLite authorizer 限制读操作、进度处理器限制运行，并返回截断标记；接口契约同样要求真实集成提供主体范围、行数/字节限制与超时。模型提示词里的“只运行 SELECT”不能代替这些控制。分析契约｜演示只读查询实现

验收要同时看最终业务状态与该拒绝的操作

官方评测说明没有附送完整运行器，而是规定如何构造本商店的数据与评分：确定性的门禁用代码测试，模型是否选对技能、对象和工具另做行为评测。它要求每个正例配反例；一味拒绝的助手也必须失败。判断以最终工具参数、购物车、变更台账或记忆存储为依据，不能只看回复是否像成功。评测方法

人工或模型裁判只承担难以写成确定条件的判断；裁判模型和规则应固定并记录，解析失败与助手失败分开。离线回放能比较同一工具结果下的行为，却不能替代真实后台的写入验证。

准备接入时，选一类已有读回接口的写操作，把一次批准追到业务系统：预览记录、批准的变更标识、后台响应、最终值与失败后的可恢复状态必须对得上。随后专门检查等待期间数据变化、第二项失败、响应丢失后的重试。若这些状态还分不清，先开放建议与预览，把写入留给现有业务流程。