Sidekick AI App Extension 的难点不是把一个“会聊天”的入口接进来，而是把它约束成一个可解释、可确认、可回退的工具边界。本文把“开发”理解为：为 Sidekick 的应用扩展面设计工具声明，明确每项数据需要什么权限，规定什么时候必须让商家确认，并准备权限不足、数据不一致和写操作失败时的错误处理。
本文只讨论 Sidekick App Extension 的工具、数据/权限、用户确认、错误处理和测试回退。这里的 extension 不是 Storefront MCP 教程，也不是普通的 Magic 使用说明，更不是把商家直接使用 Sidekick 的经验包装成应用扩展能力。官方文档给出的硬边界是：扩展能做什么取决于已声明的 extension surface、权限和当前可用性；不能假设每个 Sidekick 安装都拥有相同工具。
1. 先把唯一意图限定清楚
1.1 这篇文章要交付的工程结果
交付物应当是一份“工具契约 + 权限矩阵 + 确认矩阵 + 错误与回退方案 + 测试规格”。它不是“让 AI 自由调用店铺 API”的授权书，也不是对商家承诺自动正确。每一项能力都要能回答五个问题：工具为何存在、它读什么、它能否写入、用户何时确认、失败后回到哪里。
1.2 明确排除的三类内容
第一，不在本文设计 Storefront MCP、headless storefront 或通用 endpoint。第二，不把商家在 Sidekick 或 Magic 中的普通操作当成应用扩展的实现证据。第三，不推断某个计划、地区、账号或安装一定具备某个工具；这类时效性事实均以 2026-08-30 核验 记录，接入前必须复测。
2. Extension summary：把扩展看成一条有闸门的路径
2.1 用户从请求到结果的最小路径
推荐的最小路径是“理解请求—选择已声明工具—检查数据和权限—展示预览—请求确认—执行或生成草稿—呈现结果—保留回退入口”。其中，生成一段建议文字也属于 AI 输出，需要商家或编辑审阅；只要涉及真实商品、订单、库存、支付、退货、客户数据或店铺政策，就不能让模型输出凌驾于当前店铺数据和政策之上。
2.2 每个闸门应该留下什么证据
下表是本文的 extension summary。它是实施方案，不声称 Shopify 已经为每一行提供同名 API 或固定 UI。
| 路径阶段 | 扩展应声明或展示的内容 | 商家/编辑的控制点 | 失败时的停止证据 |
|---|---|---|---|
| 请求理解 | 用户意图、目标对象、是否需要敏感数据 | 可改写目标、取消请求 | 目标不明确，不调用工具 |
| 工具选择 | 工具标识、用途、读/写模式 | 查看将被调用的工具 | 没有已声明工具，转为人工核验 |
| 数据检查 | 数据来源、时间/版本提示、缺失字段 | 确认是否补充数据 | 数据缺失或过期，不能猜测 |
| 预览 | 将读取/写入的对象、拟产生的结果 | 确认或拒绝 | 预览不完整，不执行写操作 |
| 执行或生成草稿 | 实际结果、警告、错误码/原因 | 审阅、重试、回退 | 无法证明成功，按未完成处理 |
| 交接 | 人工入口、原始请求、工具结果摘要 | 在后台核对真实状态 | 找不到真实状态，停止自动化 |
2.3 能力边界的公开写法
在产品说明、帮助文案和内部验收单中，建议写“本扩展仅暴露已声明且当前可用的工具；实际能力依赖扩展面、权限与当前可用性”。不要写“Sidekick 安装后即可管理所有订单”或“每个店铺都能使用相同工具”。这既是准确性要求，也是回退设计的前提。
3. 工具声明：先写契约，再写调用逻辑
3.1 一项工具声明至少包含九个字段
每个工具应有稳定的内部标识和人类可读的显示名，并声明用途、输入、输出、数据类别、读写模式、权限依据、确认级别、失败行为。再加一项“不得做什么”，防止模型把相邻任务塞进同一个宽泛工具。
例如，工具的输入不能只有一句自然语言；至少要有目标对象、范围、可选筛选条件和缺失字段处理方式。输出不能只有一段生成文本；应包含来源摘要、是否完整、是否需要人工确认以及可供人工核对的对象标识。具体字段格式由当前 extension surface 和应用实现决定，不能凭本文臆造固定平台 schema。
3.2 按副作用分级，而不是按工具数量炫技
下面的工具名是拟定设计名，不是 Shopify 内置工具名。它们用于说明如何治理边界。
| 设计级别 | 拟定工具名 | 允许的动作 | 默认确认 | 明确禁止 |
|---|---|---|---|---|
| L0 上下文 | context.inspect | 读取用户已经提供或扩展明确可见的非敏感上下文 | 无副作用时可不另弹确认，但仍要显示来源 | 猜测未提供的商品、政策或订单事实 |
| L1 只读核验 | record.lookup | 按用户指定范围读取可被当前应用和店铺授权的数据 | 涉及订单、客户、支付、退货等敏感数据前必须确认 | 借“查询”暗中修改记录 |
| L2 草稿生成 | response.draft | 根据已核验上下文生成回复、清单或操作计划 | 交给商家/编辑审阅；不得当成已执行 | 把草稿写成已完成事实 |
| L3 写操作 | change.apply | 仅在当前能力、权限和业务允许时执行明确变更 | 每次明确预览并确认 | 默认开启、批量扩大范围、静默重试 |
3.3 一个安全的声明示例
以下 YAML 只是应用内部的治理模板。permission_ref、实际 surface、输入输出字段和调用方式都必须在实施时映射到当前官方文档与已批准配置；它们不是平台权限键的断言。
``yaml tool_id: record.lookup display_name: 读取指定记录摘要 purpose: 只为回答当前请求，读取用户明确指定范围内的记录 mode: read_only data_scope: merchant-approved-context-only permission_ref: map-to-current-approved-permission confirmation: required-before-sensitive-read side_effects: none on_missing_or_stale: stop-and-ask-merchant-to-verify on_error: show-reason-and-provide-admin-handoff ``
这个示例有意把“权限引用”写成映射动作，而不是虚构一个固定 scope。实现者应在代码评审中补上真实配置、来源、最小范围和撤销方法；若当前 extension surface 不支持该读取，工具应保持禁用，而不是换成更宽的权限。
4. 权限与数据：按敏感度切层
4.1 真实数据的优先级规则
AI 只能基于已获得且可核验的上下文作答。真实商品、订单、库存、支付、退货、客户数据和店铺政策优先于模型记忆、模板示例或推测。没有数据时，正确结果是“无法核验，请到后台确认”，而不是补一个看似完整的答案。
4.2 权限矩阵应该写到对象级别
下表是接入前要填实的权限矩阵。权限列用“批准的最小权限”表示，避免在未核对官方当前配置前创造不存在的标识。
| 数据/动作 | 默认处理 | 最小权限原则 | 用户确认 | 回退 |
|---|---|---|---|---|
| 用户已提供的普通上下文 | 仅使用当前请求 | 不新增读取 | 通常不需要副作用确认 | 缺字段则追问 |
| 商品信息 | 只读、限定用户指定商品/范围 | 只允许当前任务需要的读取 | 依当前数据敏感度和扩展能力决定 | 链接后台或请编辑核对 |
| 库存、订单、退货、支付 | 默认不猜、不越权 | 逐项申请已批准的最小读取能力 | 读取前说明对象和目的 | 停止自动回答，人工核验 |
| 客户数据 | 高敏感，默认不带入草稿 | 限定对象、字段和保存周期 | 明确确认，尽量脱敏展示 | 不读取或转人工 |
| 店铺政策 | 以当前店铺政策版本为准 | 只读当前有效来源 | 变更前必须预览并确认 | 展示版本冲突，不执行 |
| 写入或触发外部动作 | 默认关闭 | 只开放单一、可审计的动作 | 每次、每范围显式确认 | 当作未执行，核对真实状态 |
4.3 权限变化要当成发布事件
增加数据类别、扩大查询范围、把草稿变成写操作，都会改变风险边界，不能只当成一个小配置改动。变更记录至少要说明新增目的、最小范围、用户可见提示、确认文案、失败回退和测试用例。若权限申请不能被解释为“为当前工具完成当前任务所必需”，就不应合并。
5. 用户确认矩阵：把“同意”设计成可理解的动作
5.1 三种确认级别
可以使用三档治理语言：无副作用的上下文读取、敏感数据读取、写入或外部动作。第一档可以在界面直接显示来源；第二档在读取前说明对象、字段目的和缺失时的处理；第三档必须展示拟执行内容、范围、结果预期和失败时的状态判断。
5.2 确认矩阵与可复用文案
| 场景 | 用户在确认前应看到 | 推荐按钮语义 | 拒绝后的行为 |
|---|---|---|---|
| 读取普通上下文 | 使用哪些已提供内容 | 查看建议 | 继续基于已有内容生成草稿 |
| 读取订单/客户等敏感对象 | 对象、字段、目的、是否保存 | 允许本次读取 | 不调用工具，给出人工核验路径 |
| 生成草稿 | 草稿性质、依据、未知项 | 生成待审草稿 | 解释缺少信息，不伪装完成 |
| 写入单个对象 | 变更前后、对象、范围、不可逆风险 | 确认并执行 | 保持原状态 |
| 批量或外部动作 | 数量、筛选条件、总影响、失败策略 | 审阅后执行 | 缩小范围或转人工，不默认批量 |
5.3 确认不是免责声明
“AI 可能出错，请自行负责”不能替代确认设计。好的确认应让用户知道扩展将读取什么、会不会改变状态、依据是否完整、拒绝后能做什么。即使用户点击确认，扩展也不能声称实时、安全或成功保证；执行结果仍需以店铺真实状态和政策核对为准。
6. 安全策略：先防止错误被放大
6.1 AI 输出必须经过商家或编辑审阅
所有回复、分类、操作计划和字段填充都可能出错。对外展示时区分“已核验事实”“模型建议”“缺失或冲突信息”。当扩展无法确认政策版本、订单状态、库存数量或支付/退货条件时，应明确标为未知并转向后台核验。不要通过更长提示词掩盖缺数据。
6.2 日志只证明发生了什么
建议记录请求标识、工具标识、读写模式、数据范围摘要、用户确认结果、返回状态、错误类别和人工交接时间。日志不应为了方便而保存完整客户内容、支付信息或不必要的订单字段。展示层可用脱敏摘要，只有已批准的人员和流程才能查阅需要核对的真实记录。
6.3 防止工具被“提示词带宽”扩大
工具说明应拒绝跨对象、跨店铺和跨目的的隐含扩展。用户要求“顺便把所有客户都处理掉”时，扩展应拆成新的、需要重新授权和确认的任务；不能把这句话拼进原有单项工具的筛选条件。工具返回的数据也不能自动成为下一次写操作的授权。
7. 错误处理：错误要可见、可解释、可回退
7.1 四类必须单独处理的错误
| 错误类 | 面向用户的说明 | 扩展动作 | 人工回退 |
|---|---|---|---|
| 能力不可用 | 当前安装或 extension surface 未提供此工具 | 不尝试替代越权工具 | 请在可用后台路径完成 |
| 权限不足/用户拒绝 | 未获得本次所需授权 | 不读取、不写入 | 缩小范围或转人工 |
| 数据缺失/过期/冲突 | 结果不能代表当前店铺真实状态 | 标记未知，禁止猜测 | 到后台核对商品、订单或政策 |
| 执行状态不明/写入失败 | 无法证明动作是否完成 | 停止重试，保持“未确认” | 用对象标识核验，再决定补偿 |
7.2 一个安全的只读示例
商家问：“这个订单能否按店铺退货政策处理？”安全路径不是直接回答“可以”。扩展先识别请求需要订单与当前政策两个来源；若当前权限或数据不可用，就显示“无法核验订单/政策，请在后台确认”，并提供待人工核对的对象信息。若两者都可读，结果也应把订单事实、政策版本、未知项和建议动作分开，最后生成待审草稿，而不是自动承诺退款或退货。
7.3 不做静默重试和静默降级
权限错误不能自动改用更宽权限，写入失败不能连续重放，数据冲突不能用旧缓存掩盖。每次重试都要回答：是否仍是同一个对象、是否仍在原确认范围、是否可能产生重复副作用。如果回答不了，就停止并交给人工。时效性事实的验证时间统一记录为 2026-08-30 核验，接入前仍需复测。
8. 具体失败与回退演练
8.1 演练 A：权限不足后回到人工核验
场景：商家要求扩展读取一个订单并判断退货处理，但当前配置未批准订单读取能力。预期流程如下：
- 工具路由识别为敏感只读请求，先停在权限检查，不发送订单内容。
- 界面说明“本次未获得读取该订单所需的已批准权限”，不显示猜测出的订单状态。
- 扩展提供两个安全选项：由商家在后台核对后粘贴必要事实，或直接转人工流程。
- 若商家拒绝授权或没有可用路径，记录
not_run，而不是success或failed-after-write。 - 测试人员核对：没有订单数据泄露、没有退款/退货动作、没有为了继续回答而扩大权限。
回退边界是“回到人工核验”，不是“自动申请更高权限”。任何后续重新读取都必须新建一次明确请求，并重新呈现确认。
8.2 演练 B：订单事实与政策版本冲突
场景：只读结果显示订单状态，但政策来源版本与当前店铺展示的政策不一致。扩展必须把冲突视为未决事项：冻结自动动作，显示两类来源和冲突字段，生成一份仅供编辑修改的核对清单。编辑确认最新店铺政策和订单事实后，才能决定是否继续；扩展不应自行选择“看起来更新”的一份，也不应把建议改写成政策结论。
验收证据包括：冲突字段可见、政策版本可追溯、未执行写入、交接信息完整。若无法获得人工确认，最终状态保持 needs_review。
8.3 演练 C：写操作返回不明确
场景：用户已确认单个变更，但执行后网络或扩展返回状态不明确。此时不能立即再次调用 change.apply。先保存本次确认范围和对象标识，向用户显示“执行状态待核验”，再要求人工在真实店铺状态中确认。若真实状态未变化，才由用户重新审阅并发起新的操作；若已变化，结束当前流程并记录实际结果。
“回退”在这里不是凭空把数据改回旧值。对于不能证明可逆的动作，rollback boundary 是停止自动化、核对真实状态、由有权限人员决定补偿步骤。测试规格只能是方案，不能写成已执行的恢复结果。
9. 开发测试与接入前复测
9.1 测试环境边界
测试应在隔离的开发店或等价的非生产环境完成，使用专门的测试记录和虚构客户内容；不能用真实客户数据证明安全。测试重点是声明面、权限拦截、确认顺序、错误显示、草稿标记和回退入口。测试环境可验证流程，不等于生产可用性；当前可用工具、extension surface、计划或账号条件仍需接入前重新确认。
9.2 测试矩阵只是验收方案
| 编号 | 前置条件 | 操作 | 预期结果 | 失败即回退 |
|---|---|---|---|---|
| T01 | 普通上下文完整 | 请求生成建议 | 显示依据和草稿标记，不写入 | 停在草稿 |
| T02 | 敏感读取未批准 | 请求订单或客户信息 | 权限错误，不读取 | 转人工 |
| T03 | 用户拒绝确认 | 在敏感读取前拒绝 | 工具不调用，原状态不变 | 结束当前流程 |
| T04 | 数据缺字段 | 请求带政策判断的回答 | 标记未知，要求核对 | needs_review |
| T05 | 两来源冲突 | 提供订单和政策版本 | 展示冲突，不自动决定 | 冻结写操作 |
| T06 | 写操作已确认但返回不明 | 模拟超时/错误 | 不重放，提示核对真实状态 | 人工核验 |
| T07 | 批量范围过宽 | 提交跨对象请求 | 拆分并重新确认，不默认执行 | 缩小范围 |
9.3 测试记录的最低内容
每个测试记录版本、环境、工具声明、使用的权限配置、确认截图或文本、输入数据类别、预期状态、实际状态和回退结果。结果应区分 pass、fail、blocked、not executed。没有执行过的测试不能写成通过；
10. 发布、监控与回滚边界
10.1 发布闸门
合并前至少检查：工具是否一项一项声明、敏感数据是否有最小权限、写操作是否默认关闭、确认文案是否说明范围、错误是否能转人工、草稿是否明确待审、真实数据和政策是否优先、官方来源是否按时效复测。任何一项缺失，都只能保持开发或测试状态。
10.2 回滚边界表
| 变化 | 可自动回退的范围 | 必须人工判断的范围 | 立即动作 |
|---|---|---|---|
| 文案或显示名错误 | 停用该工具入口、修正文案 | 已展示内容是否需通知 | 标记版本并暂停入口 |
| 只读工具误读范围 | 关闭工具、撤销未必要的读取配置 | 已读数据的处置和通知 | 停止调用，保留审计摘要 |
| 草稿被误当成完成 | 撤回草稿展示 | 是否已被外部采用 | 标注未执行并交编辑 |
| 写操作状态不明 | 停止重试 | 真实状态、补偿或逆向动作 | 人工核对对象 |
| 权限/extension surface 改变 | 关闭受影响工具 | 是否重新申请和复测 | 版本降级或停用 |
回滚不是承诺“所有动作都能恢复”。没有明确的反向动作、对象范围和真实状态证据时，自动化只能停在安全状态。生产数据、订单、支付、退货和客户政策的最终判断交给有权限的商家或编辑。
10.3 复测与时效性事实记录
接入前重新核对 Sidekick App Extension 官方文档、AI 工具说明、最佳实践和 Sidekick 帮助页，确认当前 extension surface、权限要求、确认行为和可用性。相关官方资料中的时效性事实目前统一写 2026-08-30 核验；复测前不要把它们改写成长期保证。
11. 实施清单：让代码评审可以逐项核对
11.1 开始编码前
写出唯一意图和排除项；列出每个工具的读写模式、数据类别、输入输出、拒绝条件和人工交接；确认实际 extension surface 的当前文档；把权限键、版本和环境作为待填配置，而不是散落在提示词中。
11.2 提交评审前
至少走一遍普通上下文、敏感读取拒绝、政策/订单冲突、草稿误解和写入状态不明的路径。评审者要能在日志中看出工具是否调用、用户是否确认、范围是什么、最终是成功、未执行还是待核验。对无法证明的结果，界面必须保持不确定，而不是提高语气确定性。
11.3 接入前
在隔离环境完成测试规格中的必要用例，复测官方来源和当前可用性，准备停用受影响工具的开关和人工回退文案。发布说明中应说明这是有边界的应用扩展，不承诺所有 Sidekick 安装拥有同样工具，也不承诺 AI 输出、实时状态或安全结果自动正确。
常见问题
12.1 这是不是一个 Storefront MCP 教程？
不是。本文的对象是 Sidekick App Extension 的工具声明、权限、确认、错误和测试回退。Storefront MCP、headless storefront 和其他入口不属于本文 的实现范围，不能用它们的能力替代扩展面验证。
12.2 能不能默认让 Sidekick 读取所有订单和客户？
不能。订单和客户数据应按当前任务逐项限定，使用已批准的最小权限，并在敏感读取前说明对象和目的。若当前扩展面或权限不支持，就停止读取并转人工核验；不能因为模型“可能知道”而补全事实。
12.3 生成草稿是否等于已经完成操作？
不等于。草稿、建议和操作计划都必须标为待商家或编辑审阅。只有经过明确确认、实际执行返回可核验结果，并与真实店铺状态核对后，才能描述为已完成；状态不明时保持待核验。
12.4 写操作失败时应该自动重试吗？
默认不应静默重试。先判断是否已经产生副作用、对象是否仍在原确认范围、是否存在明确的反向动作。无法证明时停止，要求人工核对真实状态；新的尝试必须重新预览和确认。
12.5 如何证明这个扩展在每个 Sidekick 安装都可用？
不能这样证明，也不应这样承诺。能力取决于声明的 extension surface、权限和当前可用性，不同安装不必然相同。接入前应在目标环境复测并记录版本、权限、工具可见性和回退结果，同时保留人工路径。
13. 官方来源与时效说明
13.1 官方来源
以下官方资料用于界定当前能力与安全边界：Sidekick app extensions、Shopify AI-powered tools、AI best practices 和 Sidekick。所有时效性事实标记为 2026-08-30 核验，接入前必须复测并由开发店签字。
14. 系列内链与相邻主题边界
14.1 只链接相关治理主题
如果需要继续阅读，可查看 AI 跨境电商实施边界 的相关系列内容、Shopify Magic 与 Sidekick 工作流 的相邻治理内容和 Shopify B2B AI 销售助手 的相关主题。它们不应被当成本文 的工具声明、权限或错误处理证据；本文 的唯一意图仍是 Sidekick App Extension 的边界治理。