alicli

alicli 是面向 Agent 和业务人员的 Alibaba.com 电商数据 CLI。稳定命令提供可发现的能力、机器可读 JSON、明确错误码、专用浏览器会话、请求节奏控制和完整性检查。

当前稳定业务能力：从一个 Alibaba.com 商品详情链接导出该店铺的文字评价 Excel。

安装

npm install -g @petercjl/alicli
alicli --version
alicli doctor

要求 Node.js 20 或更高版本以及 Google Chrome。当前在 macOS Apple Silicon 上完成真实测试；Windows 和 Linux 的 Chrome 探测代码已提供，但尚未完成发布级实机验证。

能力发现

alicli capabilities
alicli capabilities --json
alicli capabilities --all

capabilities --json 是 Agent 的稳定发现入口。命令路由、帮助与能力信息由同一个注册表生成。

店铺评价导出

alicli reviews store \
  --url 'https://www.alibaba.com/product-detail/example_1234567890.html' \
  --out store-reviews.xlsx

机器调用：

alicli reviews store \
  --url 'https://www.alibaba.com/product-detail/example_1234567890.html' \
  --out store-reviews.xlsx \
  --json

Excel 包含：

• 概览；
• 可筛选的评价明细；
• 评分分布。

默认每页 50 条。--max-pages N 只用于小样本或明确的有限导出；未设置时，CLI 会核对可导出文字评价数和最终去重评价数，不完整则返回 PARTIAL_DATA。

浏览器与安全

CLI 使用专用、持久的电商浏览器身份：

• 默认 CDP：http://127.0.0.1:9223
• 默认 Profile：~/.dianshang-chrome-profile

业务命令会在需要时尝试启动 Chrome。首次使用或登录失效时，请在打开的浏览器中人工完成 Alibaba.com 登录后重新执行。

CLI 会在页面加载、接口拦截等待、每次 API 调用前、随机延时后以及 API 返回后检查登录和验证状态。每次 API 请求前随机等待 1000–2000ms；可以用 --min-delay-ms 和 --max-delay-ms 设置更慢范围，但最小值不能低于 1000ms。遇到未登录、登录表单、验证码、安全验证、访问限制或限流时立即停止，不再调用下一页 API，也不会自动刷新或绕过。

环境变量：

| 变量 | 用途 | | --- | --- | | ALICLI_CDP_URL | CDP 地址 | | ALICLI_REMOTE_DEBUGGING_PORT | Chrome 调试端口 | | ALICLI_CHROME_PROFILE | 持久浏览器 Profile | | ALICLI_CHROME_PATH | Chrome 可执行文件 |

JSON 契约

成功：

{
  "schemaVersion": "1.0",
  "ok": true,
  "command": "store-reviews-export",
  "data": {}
}

失败：

{
  "schemaVersion": "1.0",
  "ok": false,
  "command": "store-reviews-export",
  "error": {
    "code": "AUTH_REQUIRED",
    "message": "需要人工登录"
  }
}

stdout 只输出最终结果；进度输出到 stderr。失败返回非零退出码。

稳定错误码：

• INPUT_REQUIRED
• INVALID_INPUT
• UNKNOWN_COMMAND
• ENVIRONMENT_ERROR
• AUTH_REQUIRED
• VERIFICATION_REQUIRED
• RATE_LIMITED
• PARTIAL_DATA
• INTERNAL_ERROR

开发验证

npm install
npm test
npm pack --dry-run

新增业务能力时必须更新命令注册表，并补充参数、安全、分页、完整性、JSON、错误码、Excel 和打包测试。