跳到主要内容

Shoplazza AI Toolkit 排错

AI 智能体通过 Toolkit 操作 Shoplazza 时的常见问题及解决办法。

智能体说未认证​

技能通过 Shoplazza CLI 操作，CLI 需要自己登录。运行：

shell
shoplazza auth status

若显示无店铺或 token 过期，重新认证：

shell
shoplazza auth login --store-domain my-store.myshoplaza.com --domain products,orders

"缺少 scope"报错​

超出已授予 OAuth scope 的调用会被拒绝（HTTP 403），CLI 将其报为带重新登录提示的 auth 错误。若智能体遇到 scope 报错，说明你授予的范围比任务所需窄。带上所需域重新登录——见认证 → 作用域映射。新的登录会替换原有授权，所以要么列全仍需要的所有域，要么加上 --merge-scopes 保留已授予的 scope：

shell
shoplazza auth login --store-domain my-store.myshoplaza.com --domain products,orders,customers
shoplazza auth login --store-domain my-store.myshoplaza.com --domain customers --merge-scopes

技能没加载 / 路由错了域​

  • 显式带前缀：请求以 /shoplazza-<域> 开头，别只依赖触发词匹配。
  • 选对拥有该任务的域。注意边界：礼品卡 → products；按邮箱查订单 → orders；客户资料 → customers；买家退款 → orders。见 Agent Skills → 选对业务域。
  • 按快速开始 → 添加 Agent Skills里对应智能体的确认方式，检查技能是否已加载。没有就用 npx skills add Shoplazza/shoplazza-cli -g 重装。
  • shoplazza --version 和 shoplazza doctor check 会报告技能是否已装在 ~/.agents/skills/。

智能体用了不存在的 flag​

技能文件可能漂移，CLI 自身的 help 才权威。让智能体组装命令前先核对：

shell
shoplazza schema discounts            # 某域的命令与参数
shoplazza discounts +percent-code --help   # 某快捷命令的 flag
shoplazza skills read shoplazza-discounts  # 与当前 CLI 版本配套的技能

命令卡住等待输入​

缺少必填 flag 的命令会提问补全，部分 ID flag 还会弹出选择列表，但前提是 stdin 和 stderr 都是终端。在 pty 里运行命令的智能体环境可能触发这些提示，命令随即一直等一个不会到来的按键。传 --no-input，或为整个会话关掉提示：

shell
export SHOPLAZZA_CLI_NO_INTERACTIVE=1

关掉提示后，缺 flag 会直接以 required flag(s) not set 错误快速失败。

dry-run 预览和你要的对不上​

批准前仔细读被复述的命令。参数不对就修正指令、让智能体重新预览。绝不批准你看不懂 --dry-run 输出的写操作。

CLI 本身异常​

运行内置诊断：

shell
shoplazza doctor check

安装、版本与环境问题见安装 Shoplazza CLI 与 CLI 错误格式。

参见​

在此页面