本技能用于在 Adobe Commerce 应用前搭设或更新 API Mesh 配置（mesh.json），把 Commerce 自带的 GraphQL API 与本应用的运行时操作组合成单一 mesh schema。它聚焦两件事：把一个运行时操作（runtime action）暴露为 mesh source，以及为已有的 Commerce 类型扩展一个字段，并委托该 source 解析该字段。
技能假设使用者已具备 API Mesh 通用知识，包括 mesh.json 结构、handler 类型、transforms、hooks、secrets、CORS，以及通用声明式/编程式 resolver。若这些不熟悉，应先从 Adobe 官方材料学习，而非猜测语法。官方材料未覆盖的内容，正是本技能要讲的：通过 additionalResolvers（targetTypeName/sourceTypeName/requiredSelectionSet/sourceSelectionSet）扩展已有 Commerce 类型，以及把 aio-commerce-sdk 运行时操作包装为 mesh source。
前置条件 需已安装 @adobe/aio-cli-plugin-api-mesh（aio plugins install @adobe/aio-cli-plugin-api-mesh）。若要把运行时操作暴露为 source，该操作须已构建并部署，具有真实、可访问的 HTTPS 端点——指向未部署操作的 source 会以不透明方式失败。用 aio api-mesh:get 检查当前工作区是否已有 mesh：返回 “No mesh found” 说明要新建，否则是在编辑已有 mesh.json 并执行更新。
第一步：通过 introspection 确认 schema 形状 在编写 additionalTypeDefs 或 additionalResolvers 之前，先对要扩展的 Commerce（或其他）GraphQL source 做 introspection。不要凭记忆或相似命名约定假设类型/字段名——名称接近但错误会导致 mesh 构建成功，但 resolver 从不触发。
第二步：搭设 sources GraphQL source 示例中包含 name 与 handler.graphql（endpoint 与 operationHeaders）。凡 schema 含客户、购物车或会话作用域字段的 source，默认都要带 operationHeaders——API Mesh 不会自动转发调用方的 Authorization 头。省略它会使所有鉴权查询以后端自带的通用 “not authorized” 错误失败，与无效 token 难以区分。
包装运行时操作时，编写一份只描述其端点的小型静态 OpenAPI 文档，并用相对路径引用它，例如 name 与 handler.openapi.source（./mesh/<source>.json）。该 OpenAPI 文档需具备足够形状，让 mesh 能由它生成一个 Query 字段，而不只是上面的指针。最小示例包含 openapi 版本、info、servers（运行时操作基础 URL）、paths（get 方法下的 operationId、parameters、responses 的 200 内容 schema）。operationId 会成为 Query 字段名——它必须与第三步 resolver 中的 sourceFieldName 完全一致，否则 resolver 构建成功但从不触发。声明的响应 schema 必须与操作实际返回一致——mesh 按你声明的内容解析，不会重塑数据。
第三步：扩展类型并接好 resolver 用 additionalTypeDefs 扩展目标类型并添加新字段，在 additionalResolvers 中配置 targetTypeName、targetFieldName、sourceName、sourceTypeName、sourceFieldName、requiredSelectionSet、sourceArgs、sourceSelectionSet、result。从返回对象的 source 字段中提取标量时，务必把 sourceSelectionSet 与 result 配对使用，不要只用 result。只用 result 的路径会手工构建选择集而非经由 GraphQL 解析器，并在目标字段在列表内解析（如父级的 items[].<newField>）时以 “No type was found for field node ... __typename” 报错。对同一 source 字段的直接根查询即使存在该 bug 也能成功，所以仅凭该测试不足以证明 resolver 正常。
第四步：部署与验证 若已知道浏览器端应用会调用该 mesh，应在首次部署前就确定 responseConfig.CORS。会话中第一次 aio api-mesh:* 调用会打开交互式浏览器登录（Waiting for browser login...）。无浏览器访问能力的 agent 无法自行完成，需把打印出的登录 URI 交给人工并等待。首次创建用 aio api-mesh:create mesh.json -c，后续编辑用 aio api-mesh:update mesh.json -c。-c/--autoConfirmAction 会跳过交互确认提示；该提示是变更他人或系统可能依赖的 mesh 前的唯一检查点——仅对你自己刚创建的工作区级 mesh（如 CI 或一次性开发工作区）保留 -c。更新已有、共享或已部署的 mesh 时，应省略 -c 由人工确认，或至少先获得对待变更差异的明确人工批准，把这视为对在线基础设施的变更而非日常 CLI 调用。配给是异步的，需轮询确认完成（until aio api-mesh:status 2>&1 | grep -qi success; do sleep 20; done）。验证分两层：先直接验证 source 的根字段，再验证其真实嵌套/鉴权形态下的字段（带真实调用方凭据的列表嵌套查询，而非扁平根字段调用）。第一层通过不能证明第二层可用——上述 bug 在第一层不可见。若消费方应用会从浏览器直接调用该 mesh（而非仅服务端到服务端），加第三层：从该应用真实来源发起真实请求。前两层只证明服务端可达性——缺少该来源 responseConfig.CORS 条目的 mesh 能通过前两层，却仍会让来自该来源的每个浏览器调用失败，且不只影响新字段。
常见问题 鉴权查询报 “not authorized”（即使 token 有效）：source 的 graphql handler 缺少 operationHeaders，应检查 mesh.json 而非 token。嵌套/列表字段报 “No type was found for field node ... __typename” 但根查询正常：resolver 用了 result 而没有 sourceSelectionSet，需补上。
质量标准 aio api-mesh:status 报告成功，且新字段在其真实嵌套/鉴权形态下正确解析，而不仅是 source 根字段。若浏览器端应用会调用该 mesh，该应用能对其完成真实请求，而不仅是 aio api-mesh:status 与 curl。
衔接 若该 source 作为运行时操作尚不存在，先调用 commerce-app-storage、commerce-app-webhooks 或 commerce-app-eventing 搭设并部署它。
参考 API Mesh 提示指南——Adobe 关于提示 agent 编写 mesh 配置的官方指南（通用工作流与预期）。api-mesh-starter-kit llm.txt——参考知识库，涵盖 mesh.json 结构、三种 handler 类型、transforms、hooks、secrets、context 状态、CORS 及 CLI 命令集。