1688-distribution-shop-bind-newton

# 1688 分销绑店 - 牛顿 牛顿客户端绑店 Skill，通过自然对话引导用户完成店铺绑定全流程。 ## 前置条件 执行本 Skill 前必须满足以下条件，**按顺序检查**： 1. **AK 已配置**：环境变量 `ALI_1688_AK` 已设置，或 OpenClaw 配置文件中包含有效 AK（否则所有 API 调用将返回认证失败） 2. **requests 已安装**：Python 环境中已安装 `requests` 库（`pip install requests`） 3. **牛顿客户端环境**：运行在牛顿 Electron 客户端中，支持 `browser_action` 指令（非牛顿环境下浏览器操作将降级为 Playwright fallback） ## 环境变量 | 变量名 | 必填 | 默认值 | 说明 | |--------|------|--------|------| | `ALI_1688_AK` | 是 | — | 1688 API 认证密钥（Base64 编码的 AccessKeySecret + AccessKeyID） | | `DISTRIBUTE_BASE_URL` | 否 | `https://skills-gateway.1688.com` | 1688 网关地址，用于测试或切换环境 | | `OPENCLAW_CONFIG_DIR` | 否 | `~/.openclaw` | OpenClaw 配置文件目录，AK fallback 读取路径 | | `NEWTON_CLIENT` | 否 | — | 设为 `true` 表示运行在牛顿客户端中 | | `NEWTON_BROWSER_RESULT` | 否 | — | 牛顿客户端回传的浏览器操作结果（JSON） | ## Workflow 以下步骤**必须按顺序执行**，每步依赖上一步的输出： ### Step 1：查询 ISV 工具列表 获取用户可用的 ISV 工具和已绑定店铺，确定绑店的目标平台。 ```bash python3 cli.py shop_info ``` 解析返回 JSON 中 `data.options` 列表，展示给用户选择目标平台和工具。 ### Step 2：启动绑店流程 用户选择平台后，初始化绑店流程。需要传入 Step 1 中用户选择的 `channel` 和 `appKey`。 ```bash python3 cli.py bind_shop --action start --channel <channel> --app-key <appKey> ``` 如果用户尚未选择平台，也可以传入用户输入让 Skill 自动匹配： ```bash python3 cli.py bind_shop --action start --user-input "抖音" ``` ### Step 3：处理浏览器操作 如果返回 JSON 中包含 `browser_action` 字段，说明当前步骤需要浏览器操作（如打开授权链接）。将 `browser_action` 和 `browser_params` 交给牛顿客户端执行。 等待用户在浏览器中完成授权/登录后，继续流程： ```bash python3 cli.py bind_shop --action continue --channel <channel> --app-key <appKey> ``` ### Step 4：轮询与推进 重复 Step 3 直到返回 JSON 中 `flow_completed` 为 `true`。每次 `continue` 会自动查询流程状态并返回下一步引导。 如需主动查询当前进度： ```bash python3 cli.py bind_shop --action query --channel <channel> --app-key <appKey> ``` ### Step 5：流程完成或关闭 当 `flow_completed` 为 `true` 时，绑店流程全部完成。 如需中途关闭流程： ```bash python3 cli.py bind_shop --action close --channel <channel> --app-key <appKey> ``` ## 输出约定 所有命令通过 stdout 输出 JSON，通过 exit code 表达执行状态。详见 [references/output_schema.md](references/output_schema.md)。 **Exit Code**：0=成功，1=参数错误，2=认证失败，3=业务异常，4=网络异常。 **埋点日志**通过 stderr 输出 JSON（含 `_tracker: true`），不影响 stdout 解析。 ## References - [references/commands.md](references/commands.md) — 完整命令用法参考 - [references/output_schema.md](references/output_schema.md) — 输出格式和字段说明 - [references/api_reference.md](references/api_reference.md) — 1688 网关接口和认证说明 ## 依赖 - **Python**: 3.8+ - **requests**: HTTP 客户端（`pip install requests`，Skill 脚本中 `_http.py` 依赖此包） - **牛顿客户端**: Electron 内嵌浏览器（用于响应 `browser_action` 指令） ## 文件结构 ``` . ├── cli.py # CLI 统一入口 ├── SKILL.md # 本文件 ├── references/ │ ├── commands.md # 命令用法参考 │ ├── output_schema.md # 输出格式规范 │ └── api_reference.md # API 接口参考 ├── scripts/ │ ├── _auth.py # CSK 签名认证 │ ├── _http.py # 1688 网关 HTTP 客户端 │ ├── _errors.py # 异常定义 │ ├── _const.py # 常量配置 │ ├── _tracker.py # 埋点打点 │ └── capabilities/ │ ├── shop_bind_process/ # 绑店流程 │ ├── shop_info/ # 店铺信息查询 │ └── browser/ # 浏览器操作 ```