shoplazza-docs 是 shoplazza CLI 提供的开发者文档检索技能,用于在 www.shoplazza.dev 上搜索并阅读 Shoplazza 的开发者文档。文档内容包括应用与主题开发指南、各 API 版本的 API 参考、变更日志(changelog),提供英文和中文两种语言。该技能在线运行且只读,不需要登录、店铺或 profile,会忽略 --profile 参数;使用时需要能访问 www.shoplazza.dev 和文档搜索服务。
主要能力
docs search --query "<terms>" --locale <zh-CN|en>:在指定语言的文档中检索,返回最匹配的若干文档片段,每段附带所在页面的 url 和标题;默认返回 10 条,可用 --limit 在 1 到 20 之间调整;可用 --api-version 指定 API 版本(如 202601 或 2026-01)。docs get --url <url>:读取整页文档,页面内容放在返回结果的 markdown 字段中。页面较长时可能被截断(truncated: true,--max-chars 默认 20000 字符),此时可用 --output 将整页保存到系统临时目录中的新文件再读取。
使用方式与建议
- 查询应使用简短关键词,直接写 API、字段、错误码或概念名称(如 "webhook hmac verify"、"app proxy signature"、"product-create variants"),避免粘贴整句问题。
- 根据用户使用的语言传入 --locale:中文用户用 zh-CN,其他用户用 en;查询词本身的语言不受限制。
- 先用 search 的片段作答,片段不足时再对排名最前的 1 到 2 个页面执行 docs get;最多搜索 3 次,每次换一种表述(完整名称、更少词、另一种语言),仍无结果则说明文档未覆盖,并给出找到的最接近页面。
- 引用所使用页面的 url,不要凭记忆补全文档内容。
- 在比较不同 API 版本时,需要分别按每个版本各搜索一次。
- 文档站默认版本可能比 CLI 命令调用的 API 版本(202601)更新;将文档与 CLI 命令对照时,应传入 --api-version 202601。
适用场景
- 用户询问 Shoplazza 平台的工作方式或能力范围,如应用开发、OAuth 与 scope、webhook 签名、app proxy、checkout/theme/function 扩展、主题开发、Liquid。
- 在编写调用 Shoplazza API 或使用 Liquid 的代码之前查询资料。
- 调用报错或返回不认识的字段时排查原因。
- 用户升级 API 版本或询问变更内容时查阅 changelog。
使用限制
- 该技能只覆盖文档检索,不执行店铺操作。修改店铺上的 Liquid、订阅 webhook、CLI 登录与授权、读写店铺数据、查询 CLI 命令参数等,分别属于其他技能或命令(如 shoplazza-themes、shoplazza-webhook、shoplazza-common、shoplazza schema)。
- 当搜索配额用尽并提示限流时,若等待秒数不超过 60 可等待后重试一次,否则停止并告知用户,不要循环重试。
- 网络错误(退出码 4)时重试一次,随后告知用户文档不可达,不要凭记忆作答。
- docs get 返回 404 表示页面已移动或删除,可重新搜索当前页面。