shoplazza-common 是 shoplazza CLI 所有领域技能（如 discounts、products 等）的共享基础层，集中承载跨领域的通用机制，领域技能不再重复这些内容，且在开头要求先阅读本文件。命令与参数的权威来源是 shoplazza <svc> <cmd> --help 与 shoplazza schema；本技能讲机制，不记忆具体标志。
回复语言：技能正文为英文，但回复应镜像用户语言（中文提问用中文回答），包括反问、写操作确认复述与错误解释；CLI 命令、标志与字段名保持原样不翻译。
访问层级：按能表达需求的最上层级优先，命中即停。第一层为快捷命令 shoplazza <svc> +<verb> [命名标志]，具命名标志、智能默认与结构化错误；第二层为规范叶子 shoplazza <svc> <cmd> --params '{…}' [--data '{…}']，用于无快捷方式的端点；第三层为 api rest 原始兜底，仅在上述两层无法表达时使用。在 <svc> --help 中带 + 前缀者为快捷方式，其余为规范叶子。
输出结构：成功时 stdout 返回 {"ok":true,"data":<body>}，失败时 stderr 返回 {"ok":false,"error":{...}} 且非零退出。响应体嵌套在 .data 下，所以 jq 路径都从 .data 开始（如 .data.products[].id），漏掉前缀是最常见的提取错误。例外：本地命令（auth status、auth scopes、profile list）无该包装，字段在顶层直接读取。
常用标志：--dry-run 打印将发送的请求而不发送，破坏性/批量/涉及资金的写操作应先执行；-q/--jq 用 jq 表达式过滤输出，默认输出原始标量，不要再加 -r；--fields 仅少数搜索快捷方式支持（如 products +search --fields id,title），使用前需查 --help；--page-limit 列表页大小 1–250，API 默认 10；--format json|pretty|table 为全局标志；--profile 为单次调用指定 Profile。
读取过滤列表：返回 ok:true 不代表筛选与分页符合预期，有两种静默失败模式——截断（默认 10 条，--page-limit 最大 250，has_more/cursor 标记剩余，has_more 可能为 null，非 true 即结束；依赖完整性的回答应设 --page-limit 250 并跟随 cursor，纯计数优先用 +count）与静默丢弃筛选（API 忽略不认识的查询参数而不报 400，返回 200 与未筛选集合）。因此在过滤读取成为答案或写入依据前，应先用 --dry-run 确认真实参数、用 +count 对比未筛选与筛选总数，筛选结果等于未筛选总数即为可疑信号，并用 --jq 抽检返回记录确实满足筛选。若筛选被丢弃，可用 schema <svc>.<cmd> --view request 查看端点真正接受的参数，改走规范叶子或 api rest。
精度阶梯：同一过滤条件有多个方式时取最窄——专用精确匹配参数（常为数组，如 customer_emails、skus、order_tags）优于通用关键词搜索，优于对整页 --jq 手工过滤。用户措辞可判断意图：「是/为/等于/=」「编号/号码/值 is X」或自识别完整字符串（完整邮箱、完整 SKU、完整电话）表示整值，用精确匹配数组参数；「包含/含/像/类似/以…开头/前缀/片段」表示片段，用关键词搜索。回答时应说明所应用的筛选与完整性依据（如「3 条中的 3 条，未筛选总数 18」）。
先定位再操作：写操作以 id 定位记录，但用户通常用订单号、编码、邮箱、标题等命名。应先读解析目标，再按匹配数分支：0 条则停止并告知，不得扩大写入或编造 id；恰好 1 条则继续（破坏性/资金操作仍需 --dry-run 并复述）；2 条及以上则列出候选并询问。数字不等于 id（如订单号与内部 order_id），需通过读取解析，不可假设。
Schema 自省：调用规范叶子或 api rest 前，用 shoplazza schema 查看模块、命令、参数/请求体/响应结构，不要猜字段；可用 --view all|request|response 只看请求侧。
api rest 兜底：仅在前两层无法表达时使用，写入解析后的真实 URL（非模板），支持 --params/--data（含 - 标准输入、@file 文件）、--dry-run、-q/--jq。大整数 id 在 JSON 中应加引号作为字符串传递（如 {"id":"669923000979557666"}），裸大整数会被浮点转换导致请求被拒，适用于超过约 15 位的 id。
安装：若 shoplazza 未找到或 --version 失败则未安装；安装会改动用户机器，应先说明方式并等待确认。npm（推荐，需 Node.js ≥ 16）：npm install -g shoplazza-cli；Homebrew：brew install Shoplazza/tap/shoplazza-cli；安装脚本：curl -fsSL https://raw.githubusercontent.com/Shoplazza/shoplazza-cli/main/install.sh | bash（无 Node 的 macOS/Linux，装到 /usr/local/bin，可用 INSTALL_DIR 修改）；发布二进制从 GitHub releases 下载并放入 PATH。安装后用 shoplazza --version 确认。只保留一个安装器，避免 PATH 上出现两个不同版本；更新应使用对应安装器（shoplazza update 总是通过 npm 重装，Homebrew 或脚本安装应改用 brew upgrade 或重跑脚本）。
首次设置：运行版本检查，执行 shoplazza auth login -s my-store.myshoplazza.com --domain products,orders 登录并绑定店铺，再用 auth status 确认。登录应在后台运行并把授权 URL 交给用户，询问店铺与所需模块，不要猜测店铺域名。
认证：会话内首次店铺操作前先运行 auth status（本地即时、无包装），需同时满足 logged_in: true 与 profiles 非空；否则引导登录。授权分账号级与店铺级两层。--domain <模块,…> 按顶层命令名授权并展开为 OAuth 作用域（可选 app、billing、checkout、customers、discounts、orders、products、shop、themes、webhook、all）；--scope 为细粒度作用域。重新登录会替换已有授权，补权限需加 --merge-scopes（旧版无此标志则先 auth scopes 再请求并集）。Agent 驱动登录：后台运行 auth login（默认轮询 2s、超时 300s），从输出中提取授权 URL 交给用户；仅当 stdin 与 stderr 都是真实终端且未设 SHOPLAZZA_CLI_NO_INTERACTIVE 或 CI 时才交互提问，使用 pty 的 harness 应设置 SHOPLAZZA_CLI_NO_INTERACTIVE=1。非交互快速路径：shoplazza auth login --uat <UAT> 或设置 SHOPLAZZA_UAT 环境变量。店铺切换：auth status 查看当前店铺，profile list/use 切换已有 Profile，auth store use -s <域名> 为无 Profile 的店铺创建并设为当前，单次命令可用 --profile 覆盖。权限不足时按错误提示补充对应模块或作用域后重试。
Profiles（多租户）：一个 Profile 即一个店铺执行上下文（店铺令牌与作用域），支持 add、list、use（--previous 切回上个）、info、rename、remove、update；--profile 标志优先于 SHOPLAZZA_CLI_PROFILE 环境变量与当前 Profile。
更新提醒：检测到新版本时会在 stderr 打印一行提示（不出现在 stdout 的 JSON 中），应在完成当前请求后告知用户当前/最新版本并提供更新选项；shoplazza update 通过 npm 更新，--check 仅报告版本；Homebrew 或脚本安装应改用对应方式。