Wolt CLI

工具仓库地址：https://github.com/mekedron/wolt-cli

请打开该仓库查阅安装与构建说明，然后使用本地的 wolt 二进制文件：

wolt   [flags]

会话启动流程

1. 每次会话中仅需检查一次命令树：

wolt --help

2. 面向 Agent 工作时，优先使用机器可读输出格式：

... --format json

3. 从响应信封（envelope）中解析 .data 字段，并将 .warnings 和 .error 字段显式呈现给用户。

安全规则

• 默认以只读模式启动。
• 对可能产生变更的命令，必须请求用户显式确认：
  • cart add、cart remove、cart clear
  • profile favorites add、profile favorites remove
  • profile addresses add、profile addresses update、profile addresses remove、profile addresses use
  • configure（向本地配置写入用户凭证）
• 切勿将 checkout preview 描述为“下单”操作。CLI 不执行最终订单提交。

认证工作流

使用明确的 profile 名称，避免歧义：

wolt configure --profile-name default --wtoken "" --wrtoken "" --overwrite
wolt profile status --profile default --format json --verbose

已认证命令的凭证回退策略如下：

1. 显式传入的参数（--wtoken、--wrtoken、--cookie）
2. 当前选中的 profile 中配置的认证字段
3. 默认 profile 中配置的认证字段

当刷新凭证（refresh credentials）可用时，过期或返回 401 的访问令牌（access token）将被自动刷新，并将新令牌持久化写入本地配置。

位置规则

请严格遵守以下规则：

• 仅可使用以下两种方式之一指定位置：
   • --address ""
   • 同时提供 --lat 与 --lon
• 禁止同时使用 --address 与 --lat/--lon。
• 若未显式传入位置覆盖参数，则使用 profile 中保存的位置信息。
• search venues/items 和 venue show/hours 支持 --address 或 profile 位置，不接受直接的 --lat/--lon 参数。
• discover、cart、checkout preview 及 profile favorites 支持 --lat/--lon。

命令选择指南

• 探索周边选项：discover feed、discover categories、search venues、search items
• 深度查看单个商户：venue show、venue categories、venue search、venue menu、venue hours
• 定位单个商品及其可选项（用于购物车操作）：item show、item options
• 购物车与价格计算：cart count/show/add/remove/clear，随后执行 checkout preview
• 账户与历史记录：profile show/status/orders/payments/addresses/favorites

对于大型综合型商户（marketplace venue），推荐使用以下高效方式，而非遍历完整菜单：

• venue search --query ""
• venue menu --category

输出与诊断

• --format json|yaml 返回标准信封（envelope）结构字段：meta、data、warnings，以及可选的 error。
• 当上游服务调用失败时，请添加 --verbose 参数重试，以捕获完整的请求链路与详细诊断信息。

参考文档

• 完整命令与参数对照表：references/command-reference.md
• 可复用、高置信度的工作流示例：references/workflows.md
• 信封（envelope）/错误解析及自动化注意事项：references/output-and-errors.md