# ⚡️ Commerce CLI
### 用自然语言管理你的电商店铺
**专为 Claude Code 设计的对话式 CLI 工具**
[](https://www.npmjs.com/package/@optima-chat/commerce-cli)
[](https://www.npmjs.com/package/@optima-chat/commerce-cli)
[](https://opensource.org/licenses/MIT)
[](https://www.typescriptlang.org/)
[](https://nodejs.org/)
[网站](https://cli.optima.shop) • [文档](https://github.com/Optima-Chat/commerce-cli#readme) • [NPM](https://www.npmjs.com/package/@optima-chat/commerce-cli) • [问题反馈](https://github.com/Optima-Chat/commerce-cli/issues)
---
## 🎯 简介
Commerce CLI 是 [Optima Commerce](https://www.optima.shop) 生态的命令行工具，**专为 Claude Code 设计**。
无需记住命令 - 直接用中文对话，Claude 会自动调用相应的 CLI 命令来管理你的电商店铺。
```bash
# 传统方式（需要记住命令）
commerce product create --title "陶瓷杯" --price 89 --stock 20
# Commerce CLI + Claude Code（自然语言）
"创建陶瓷杯商品，89 美元，库存 20" ✨
```
## 🎬 演示
### Claude Code 自然语言交互
> 这是 Commerce CLI 最强大的功能 - 用自然语言管理电商店铺
**计划展示场景**：
- 💬 用中文对话创建商品
- 📦 自然语言查询订单
- 🚚 对话式订单发货
- 📊 智能库存管理
> 📹 演示内容录制中。参见 [DEMO_GUIDE.md](./docs/DEMO_GUIDE.md) 查看录制计划
### 安装和基本使用
### 商品管理
## ✨ 核心特性
- 🤖 **对话式操作** - 在 Claude Code 中用自然语言管理店铺，无需记住命令
- ⚡️ **即开即用** - 一行命令安装，自动配置 Claude Code 集成
- 📦 **功能完整** - 16 个模块，95+ 个命令，覆盖商品、订单、库存、物流、首页配置等全流程
- 🌍 **国际化支持** - 内置多语言翻译管理，支持商品、商户、集合、首页的国际化
- 🎨 **双输出模式** - 默认 JSON 格式（AI 友好），支持 `--pretty` 彩色表格输出
- 🤖 **AI 优先设计** - 所有命令默认 JSON 输出，可被 AI Agent 直接解析和处理
- 🔐 **安全可靠** - OAuth 2.0 Device Flow 认证，Token 自动刷新
- 🌐 **多环境隔离** - 支持 Production/Stage/Development 三环境，各自独立配置
- 🧪 **测试工具** - 内置健康检查、冒烟测试、E2E 测试脚本，可用作功能测试工具
- 🛠 **开发者友好** - TypeScript 类型安全，完善的错误处理，单元测试覆盖
## 🚀 快速开始
**要求**：Node.js >= 18
### 1. 安装
```bash
npm install -g @optima-chat/commerce-cli@latest
```
安装完成后，在项目中运行 `commerce init` 启用所需场景。支持 5 个场景化 Skills：
**可用场景**：
- 🛍️ **Product Management** - 商品管理（商品、变体、图片）
- 📦 **Order Fulfillment** - 订单履行（发货、退款）
- 📊 **Inventory Management** - 库存管理（监控、补货）
- 🏪 **Storefront Configuration** - 店铺配置（首页、集合）
- 🌍 **Internationalization** - 国际化（多语言翻译）
```bash
# 交互式选择场景
commerce init
# 或直接指定场景
commerce init --skills product,order
```
### 2. 登录你的账号
在 Claude Code 中，你可以用自然语言说：
```
"登录 Optima"
"Optima 登录"
"帮我登录到 Optima"
```
Claude 会自动打开浏览器引导你完成 OAuth 授权。
### 3. 开始用自然语言管理店铺 ✨
在 Claude Code 中，你可以这样说：
```
- "创建珍珠耳环商品，299 美元，库存 10"
- "查看今天的订单"
- "订单 order_123 发货，快递单号 DHL123456"
- "库存低于 5 的商品"
- "商品 prod_123 改价 399"
- "给商品添加中文翻译"
```
Claude 会自动调用对应的 `commerce` 命令来完成操作。
**就是这么简单！** 🎉
## 📦 功能模块
Commerce CLI 提供 **16 个功能模块**，**95+ 个命令**，覆盖电商全流程：
| 模块 | 命令数 | 说明 |
|------|--------|------|
| 🔐 **auth** | 4 | OAuth 2.0 认证（login, logout, whoami, switch）+ 多环境支持 |
| 📦 **product** | 7 | 商品 CRUD，图片管理，URL |
| 🎨 **variant** | 6 | SKU/规格管理 |
| 📋 **order** | 6 | 订单查询、发货、取消、标记送达 |
| 💰 **refund** | 2 | 退款创建和查询 |
| 📊 **inventory** | 4 | 库存预警、调整、历史、预留 |
| 🏪 **merchant** | 4 | 商户资料管理，URL |
| 🏠 **homepage** | 13 | 首页配置（CRUD、设置、重排序、翻译） |
| 📚 **collection** | 13 | 集合管理（CRUD、产品关联、翻译） |
| 🚚 **shipping** | 3 | 运费计算、物流历史、状态更新 |
| 🌍 **shipping-zone** | 5 | 运费区域和费率配置 |
| 📤 **upload** | 3 | 图片、视频、文件上传 |
| 💬 **conversation** | 7 | 客服对话管理 |
| 💳 **transfer** | 2 | 财务转账和汇总 |
| 🌐 **i18n** | 24 | 多语言翻译管理（商品/变体/集合/商户/首页） |
| 🧪 **test** | 2 | 健康检查、冒烟测试（功能测试工具） |
## 🎨 输出格式
Commerce CLI 支持两种输出格式，适用于不同场景：
### JSON 模式（默认，AI 友好）
适合 AI Agent 和程序化处理，返回结构化 JSON 数据：
```bash
commerce product list --limit 2
# 输出标准 JSON 格式
{
"success": true,
"data": {
"products": [...],
"total": 2,
"page": 1,
"has_next": false
}
}
```
**JSON 输出特性**：
- ✅ 所有 93 个命令默认输出 JSON 格式
- ✅ 统一的响应格式：`{ success, data, message?, error? }`
- ✅ 完整的数据结构，无信息丢失
- ✅ 适合 AI Agent 解析和自动化脚本
- ✅ 向后兼容：可使用 `--pretty` 切换到表格模式
### Pretty 模式（人类可读）
适合人类阅读，提供彩色终端输出和表格化数据：
```bash
commerce product list --limit 2 --pretty
# 输出彩色表格，包含商品名称、价格、库存等
```
**使用场景**：
**JSON 模式**（默认）：
- AI Agent 调用（如 Claude Code）
- 自动化脚本和 CI/CD 流程
- 需要解析数据的程序
- 数据导出和集成
**Pretty 模式**：
- 在终端手动执行命令
- 快速查看数据和调试
- 人类可读性优先
**示例对比**：
```bash
# JSON 模式（AI 友好，默认）
$ commerce merchant info
{
"success": true,
"data": {
"merchant": {
"id": "...",
"name": "徐昊的全球小店",
"slug": "xuhao-global-store",
"default_currency": "USD",
...
}
}
}
# Pretty 模式（人类友好）
$ commerce merchant info --pretty
✔ 商户信息获取成功
店铺名称: 徐昊的全球小店
店铺 Slug: xuhao-global-store
默认货币: USD
...
```
> **提示**：在 Claude Code 中，Claude 会根据需要自动选择合适的输出格式。
## 🤖 非交互模式 / CI/CD
**v0.16.0 新增**：Commerce CLI 现在支持智能环境检测，自动适配终端用户和 AI/CI/CD 环境！
### 🎯 自动环境检测
Commerce CLI 自动检测运行环境，无需手动配置：
| 环境 | 行为 | 示例 |
|------|------|------|
| **终端** | 缺少参数时显示友好交互提示 | `$ commerce product create`
📦 创建新商品
? 商品名称: _ |
| **AI / CI/CD** | 自动禁用交互，立即报错 | `$ commerce product create`
⚠️ 缺少必需参数: --title |
### 🔧 环境变量控制
**强制启用交互模式**（终端检测失败时）：
```bash
export OPTIMA_INTERACTIVE=1
```
**强制禁用交互模式**：
```bash
export NON_INTERACTIVE=1
# 或
export OPTIMA_NON_INTERACTIVE=true
```
**CI 环境自动检测**：
- GitHub Actions (`CI=true`)
- GitLab CI (`GITLAB_CI=true`)
- Jenkins (`JENKINS_URL` 存在)
- Travis CI (`TRAVIS=true`)
- 等其他 CI 平台
### 💻 CI/CD 使用示例
#### GitHub Actions
```yaml
name: Deploy Products
on: [push]
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Install Commerce CLI
run: npm install -g @optima-chat/commerce-cli
- name: Create Products
env:
OPTIMA_TOKEN: ${{ secrets.OPTIMA_TOKEN }}
run: |
# CI 环境自动禁用交互提示
commerce product create \
--title "自动化商品" \
--price 99 \
--stock 100
# 删除操作需要 --yes 确认
commerce product delete --id prod-123 --yes
```
#### GitLab CI
```yaml
stages:
- deploy
deploy_products:
stage: deploy
image: node:18
before_script:
- npm install -g @optima-chat/commerce-cli
script:
# CI 环境自动检测，无需额外配置
- commerce product list --json > products.json
- commerce product create --title "新商品" --price 49
variables:
OPTIMA_TOKEN: $OPTIMA_TOKEN
```
#### Docker
```dockerfile
FROM node:18-alpine
RUN npm install -g @optima-chat/commerce-cli
# 非交互环境，需提供所有参数
CMD ["commerce", "product", "list", "--json"]
```
```bash
# 运行容器
docker run -e OPTIMA_TOKEN=$OPTIMA_TOKEN commerce-cli
```
### ✅ 确认操作（`--yes` 标志）
删除、取消等危险操作在终端和 CI 环境都需要明确确认：
```bash
# 终端：显示确认提示
$ commerce product delete --id prod-123
⚠️ 即将删除商品: prod-123
? 确定要删除此商品吗？ (y/N)
# CI/CD：使用 --yes 跳过确认
$ commerce product delete --id prod-123 --yes
✓ 商品删除成功！
```
需要 `--yes` 的命令：
- `product delete`, `variant delete`
- `order cancel`, `order complete`
- `shipping-zone delete`
- `cleanup`
### 📋 受影响的命令（17 个）
以下命令支持自动环境检测：
| 类别 | 命令 | 非交互要求 |
|------|------|-----------|
| **核心** | `shipping calculate`, `product create`, `order ship` | 提供所有必需参数 |
| **常用** | `variant create`, `inventory update/reserve`, `shipping-zone create/add-rate` | 提供所有必需参数 |
| **确认** | `product/variant delete`, `order cancel/complete`, `cleanup` | 添加 `--yes` 标志 |
| **i18n** | `i18n product/merchant create` | 提供 `--lang` 和 `--name` |
### 📚 更多信息
完整技术文档请参阅 [`docs/NON_INTERACTIVE_MODE_DESIGN.md`](./docs/NON_INTERACTIVE_MODE_DESIGN.md)
---
## 📖 命令参考
> **提示**：推荐通过 Claude Code 用自然语言调用，以下为完整命令参考。
### 🔐 认证管理
```bash
commerce auth login # OAuth 登录到生产环境（默认）
commerce auth login --env stage # OAuth 登录到 Stage 环境
commerce auth login --env development # OAuth 登录到开发环境
commerce auth whoami # 查看当前用户和环境信息
commerce auth switch --env stage # 切换到 Stage 环境（无需重新登录）
commerce auth logout # 登出当前环境
commerce auth logout --env stage # 登出指定环境
commerce auth logout --all # 登出所有环境
```
**多环境支持**（v0.19.0+）：
Commerce CLI 支持三个独立环境，共享统一的 token 文件：
| 环境 | Auth API | Commerce API | 店铺前端域名 | token.json env |
|------|----------|--------------|------------|----------------|
| Production（默认） | auth.optima.shop | api.optima.shop | optima.shop | `prod` |
| **Stage** | **auth.stage.optima.onl** | **api.stage.optima.onl** | **store.stage.optima.onl** | `stage` |
| Development | auth.optima.chat | api.optima.chat | optima.sh | `ci` |
**Token 文件位置**：`~/.optima/token.json`（所有环境共享）
```bash
# 登录到不同环境
commerce auth login # Production（默认）
commerce auth login --env stage # Stage 预发布环境
commerce auth login --env development # Development 开发环境
# 切换环境（无需重新登录）
commerce auth switch --env stage # 切换到 Stage
commerce auth switch --env production # 切换回 Production
# 查看当前环境
commerce auth whoami # 显示环境、用户、API URLs
# 环境配置会持久化，后续命令自动使用当前环境
commerce merchant url # 根据当前环境返回正确的店铺域名
```
**环境变量认证**（适用于容器/CI/CD）：
```bash
# 设置环境变量后直接使用，无需 commerce auth login
export OPTIMA_TOKEN=
commerce product list
# Docker 容器
docker run -e OPTIMA_TOKEN= commerce-cli product list
# CI/CD 流水线
export OPTIMA_TOKEN=${{ secrets.OPTIMA_TOKEN }}
commerce product create --title "商品"
```
**认证优先级**：`OPTIMA_TOKEN` 环境变量 > 配置文件（`~/.config/commerce-cli`）
**自定义 Backend 地址**（适用于开发/测试环境）：
```bash
# 自定义 Commerce API 地址
export OPTIMA_API_URL=http://localhost:8000
commerce product list
# 自定义 Auth API 地址
export OPTIMA_AUTH_URL=http://localhost:3000
commerce auth login
# Docker 开发环境
docker run \
-e OPTIMA_TOKEN= \
-e OPTIMA_API_URL=http://host.docker.internal:8000 \
commerce-cli product list
```
**默认 Backend**：
- Commerce API: `https://api.optima.shop`
- Auth API: `https://auth.optima.shop`
### 📦 商品管理
```bash
commerce product create [--tags ] # 创建商品（支持标签）
commerce product list [--limit 20] [--tags ] # 商品列表（支持标签筛选）
commerce product get --id # 商品详情
commerce product update --id [--tags ] # 更新商品（支持标签）
commerce product delete --id [-y] # 删除商品
commerce product add-images --id --path <...> # 添加本地图片
commerce product add-images --id --url <...> # 添加图片URL
```
**示例**：
```bash
# 创建商品（带标签）
commerce product create \
--title "手工陶瓷杯" \
--price 89 \
--currency USD \
--stock 20 \
--description "精美手工制作" \
--tags "featured,new,handmade"
# 更新商品
commerce product update --id prod_123 \
--price 99 \
--stock 50 \
--tags "featured,sale"
# 按标签筛选商品
commerce product list --tags "featured,new"
# 添加本地图片
commerce product add-images --id prod_123 --path ./img1.jpg ./img2.jpg
# 添加图片 URL（避免重复上传）
commerce product add-images --id prod_123 --url https://example.com/image.jpg
# 混合使用
commerce product add-images --id prod_123 --path ./local.jpg --url https://example.com/remote.jpg
```
### 🎨 商品变体（SKU/规格）
```bash
commerce variant list --product-id # 变体列表
commerce variant create --product-id # 创建变体
commerce variant get --product-id --id # 变体详情
commerce variant update --product-id --id # 更新变体
commerce variant delete --product-id --id [-y] # 删除变体
commerce variant add-images --product-id --id --path <...> # 添加变体图片
```
**示例**：
```bash
# 创建变体
commerce variant create --product-id prod_123 \
--sku "CUP-S-WHITE" \
--price 89 \
--stock 10 \
--attributes '{"size":"S","color":"White"}'
```
### 📋 订单管理
```bash
commerce order list [--status pending] # 订单列表
commerce order get --id # 订单详情
commerce order ship --id # 订单发货
commerce order complete --id # 完成订单
commerce order cancel --id # 取消订单
commerce order mark-delivered --id # 标记已送达
```
**示例**：
```bash
# 发货
commerce order ship --id order_123 \
--tracking DHL123456 \
--carrier DHL
# 取消订单
commerce order cancel --id order_456 \
--reason "客户要求取消" \
--yes
```
### 💰 退款管理
```bash
commerce refund create --order-id # 创建退款
commerce refund get --id # 退款详情
```
**示例**：
```bash
# 创建退款
commerce refund create --order-id order_123 \
--amount 50 \
--reason requested_by_customer
```
### 📊 库存管理
```bash
commerce inventory low-stock [--threshold 5] # 低库存商品
commerce inventory update --id # 更新库存
commerce inventory history --id # 库存历史
commerce inventory reserve --id # 预留库存
```
**示例**：
```bash
# 查看低库存
commerce inventory low-stock --threshold 10
# 更新库存
commerce inventory update --id prod_123 \
--quantity 50 \
--reason "补货"
```
### 🏪 商户管理
```bash
commerce merchant info # 获取商户信息
commerce merchant update # 更新商户资料
commerce merchant setup # 初始化商户资料（首次使用）
commerce merchant url [--open] # 获取店铺链接（可在浏览器打开）
```
**初始化商户资料示例**：
```bash
# 交互式模式（适合本地使用）
commerce merchant setup
# 非交互式模式（适合容器/CI/CD，所有必填字段通过参数提供）
commerce merchant setup \
--name "我的店铺" \
--origin-country-alpha2 HK \
--origin-city Saikung \
--origin-state "New Territories" \
--origin-line-1 "G/F NO.93, TAI PO TSAI VILLAGE" \
--contact-name "XU, HAO" \
--contact-phone "53736279" \
--contact-email "merchant@example.com"
# 带可选字段
commerce merchant setup \
--name "我的店铺" \
--description "高品质商品" \
--slug "my-store" \
--default-currency USD \
--origin-country-alpha2 CN \
--origin-city "深圳" \
--origin-state "广东省" \
--origin-line-1 "南山区科技园" \
--origin-line-2 "创业大厦10楼" \
--origin-postal-code "518000" \
--contact-name "张三" \
--contact-phone "13800138000" \
--contact-email "merchant@example.com" \
--company-name "深圳某某科技有限公司"
```
**必填字段**：
- `--name`: 商户名称
- `--origin-country-alpha2`: 发货国家代码（2位，如 CN, US, HK）
- `--origin-city`: 发货城市
- `--origin-state`: 发货省/州
- `--origin-line-1`: 发货地址第一行
- `--contact-name`: 联系人姓名
- `--contact-phone`: 联系电话
- `--contact-email`: 联系邮箱
### 🏠 首页配置
```bash
# 首页模块管理
commerce homepage module list # 查看所有首页模块
commerce homepage module get --slug # 获取模块详情
commerce homepage module create # 创建首页模块
commerce homepage module update --slug # 更新模块
commerce homepage module delete --slug [-y] # 删除模块
commerce homepage module reorder # 重新排序模块
# 首页设置
commerce homepage settings get # 获取首页设置
commerce homepage settings update # 更新首页设置
# 首页统计
commerce homepage analytics # 查看首页分析数据
# 首页区块翻译
commerce i18n homepage list --section-id # 查看区块的所有翻译
commerce i18n homepage set --section-id --lang --title # 创建/更新区块翻译
commerce i18n homepage delete --section-id --lang [-y] # 删除区块翻译
```
**示例**：
```bash
# 创建轮播图模块
commerce homepage module create \
--slug hero-banner \
--type banner \
--position 1 \
--enabled true \
--config '{"images":[{"url":"https://example.com/banner.jpg","alt":"Summer Sale"}]}'
# 更新首页设置
commerce homepage settings update \
--show-search true \
--show-categories true \
--featured-limit 8
# 为首页区块添加中英文翻译
commerce i18n homepage set \
--section-id section-123 \
--lang zh-CN \
--title "精选商品" \
--description "查看我们最受欢迎的产品"
commerce i18n homepage set \
--section-id section-123 \
--lang en-US \
--title "Featured Products" \
--description "Discover our most popular items"
```
### 📚 集合管理
```bash
# 集合 CRUD
commerce collection list # 查看所有集合
commerce collection get --slug # 获取集合详情
commerce collection create # 创建集合
commerce collection update --slug # 更新集合
commerce collection delete --slug [-y] # 删除集合
# 集合产品关联
commerce collection add-products --slug # 添加产品到集合
commerce collection remove-products --slug # 从集合移除产品
# 集合翻译
commerce i18n collection list --collection-id # 查看集合翻译列表
commerce i18n collection get --collection-id --lang # 获取特定语言翻译
commerce i18n collection create --collection-id # 创建集合翻译
commerce i18n collection update --collection-id --lang # 更新集合翻译
commerce i18n collection delete --collection-id --lang [-y] # 删除集合翻译
```
**示例**：
```bash
# 创建夏季促销集合
commerce collection create \
--name "Summer Sale" \
--slug summer-sale \
--description "Hot deals for summer" \
--image-url "https://example.com/summer.jpg"
# 添加产品到集合
commerce collection add-products --slug summer-sale \
--product-ids prod_123,prod_456,prod_789
# 添加西班牙语翻译
commerce i18n collection create \
--collection-id coll_123 \
--lang es-ES \
--name "Promoción de Verano" \
--description "Ofertas calientes para el verano"
```
### 🚚 物流管理
```bash
commerce shipping calculate # 计算运费
commerce shipping history --order-id # 物流历史
commerce shipping update-status --id # 更新物流状态
```
**示例**：
```bash
# 计算运费
commerce shipping calculate \
--country US \
--postal-code 10001 \
--weight 0.5
```
### 🌍 运费区域管理
```bash
commerce shipping-zone list # 运费区域列表
commerce shipping-zone create # 创建运费区域
commerce shipping-zone delete --id [-y] # 删除运费区域
commerce shipping-zone list-rates --zone-id # 查看区域费率
commerce shipping-zone add-rate --zone-id # 添加运费费率
```
**示例**：
```bash
# 创建区域
commerce shipping-zone create \
--name "北美区域" \
--countries US,CA,MX
# 添加费率
commerce shipping-zone add-rate --zone-id zone_123 \
--price 15 \
--currency USD \
--min-weight 0 \
--free-threshold 100
```
### 📤 文件上传
```bash
commerce upload image --path # 上传图片
commerce upload video --path # 上传视频
commerce upload file --path # 上传文件
```
### 💬 对话管理
```bash
commerce conversation list # 对话列表
commerce conversation get --id # 对话详情
commerce conversation create # 创建对话
commerce conversation close --id # 关闭对话
commerce conversation messages --id # 查看消息
commerce conversation send --id # 发送消息
commerce conversation mark-read --id # 标记已读
```
### 💳 财务管理
```bash
commerce transfer list # 转账列表
commerce transfer summary # 财务汇总
```
### 🌐 国际化翻译
Commerce CLI 内置完整的多语言翻译管理系统：
```bash
# 语言管理
commerce i18n languages [--all] # 查看支持的语言
# 商品翻译
commerce i18n product list --product-id
commerce i18n product get --product-id --lang
commerce i18n product create --product-id
commerce i18n product update --product-id --lang
commerce i18n product delete --product-id --lang [-y]
# 商户翻译
commerce i18n merchant list
commerce i18n merchant get --lang
commerce i18n merchant create
commerce i18n merchant update --lang
commerce i18n merchant delete --lang [-y]
# 变体翻译
commerce i18n variant list --variant-id
commerce i18n variant get --variant-id --lang
commerce i18n variant create --variant-id
commerce i18n variant update --variant-id --lang
commerce i18n variant delete --variant-id --lang [-y]
# 集合翻译
commerce i18n collection list --collection-id
commerce i18n collection get --collection-id --lang
commerce i18n collection create --collection-id
commerce i18n collection update --collection-id --lang
commerce i18n collection delete --collection-id --lang [-y]
# 首页区块翻译
commerce i18n homepage list --section-id
commerce i18n homepage set --section-id --lang --title
commerce i18n homepage delete --section-id --lang [-y]
```
**示例**：
```bash
# 查看支持的语言
commerce i18n languages
# 为商品添加中文翻译
commerce i18n product create --product-id prod_123 \
--lang zh-CN \
--name "手工陶瓷杯" \
--description "精美的手工制作陶瓷杯" \
--meta-title "手工陶瓷杯 - 传统工艺"
# 为变体添加翻译（注意：使用 --variant-id 而非 --product-id）
commerce i18n variant create --variant-id var_456 \
--lang ja-JP \
--name "セラミックマグ" \
--variant-attributes-translations '{"size":{"key_translation":"サイズ","value_translation":{"S":"小"}},"color":{"key_translation":"色","value_translation":{"白":"白"}}}'
# 为集合添加翻译
commerce i18n collection create --collection-id coll_789 \
--lang es-ES \
--name "Promoción de Verano" \
--description "Colección especial de verano"
```
### 🧪 测试工具
Commerce CLI 内置测试工具，可用作功能测试和 API 健康检查：
```bash
# 健康检查（检查 API 连通性和响应时间）
commerce test health
# 冒烟测试（测试核心 API 端点）
commerce test smoke
# 端到端测试脚本（适用于 CI/CD）
export OPTIMA_TOKEN=your_token
export TEST_ENV=stage
./scripts/e2e-test.sh
```
**健康检查示例**：
```bash
$ commerce test health
🏥 健康检查 - stage 环境
检查 Auth API...
✓ Auth API 健康 (120ms)
检查 Commerce API...
✓ Commerce API 健康 (150ms)
认证状态:
✓ 已登录
总体状态:
✓ 所有服务正常
```
**冒烟测试示例**：
```bash
$ commerce test smoke
🧪 冒烟测试 - stage 环境
1. 测试商户信息 API...
✓ 成功 (120ms) - 商户: My Store
2. 测试商品列表 API...
✓ 成功 (150ms) - 5 个商品
3. 测试订单列表 API...
✓ 成功 (180ms) - 3 个订单
测试结果:
✓ 通过: 3
成功率: 100.0%
```
**E2E 测试脚本**：
```bash
# scripts/e2e-test.sh 执行完整业务流程测试
# 1. 健康检查
# 2. 冒烟测试
# 3. 创建测试商品
# 4. 验证商品
# 5. 清理测试数据
# 在 CI/CD 中使用
- name: Run E2E tests
env:
OPTIMA_TOKEN: ${{ secrets.OPTIMA_TOKEN_STAGE }}
TEST_ENV: stage
run: ./scripts/e2e-test.sh
```
**特点**：
- ✅ 默认 JSON 输出，易于解析
- ✅ 测试失败时退出码为 1（CI/CD 友好）
- ✅ 支持多环境测试
- ✅ 详细的错误信息和响应时间
## 💬 自然语言示例
在 Claude Code 中，你可以用非常简洁的自然语言描述需求：
**认证和环境**：
- "登录 Optima"
- "登录到 Stage 环境"
- "切换到生产环境"
- "查看我的账号信息"
- "打开我的店铺"
- "切换到开发环境"
**商品管理**：
- "创建陶瓷杯商品，89 美元，库存 20"
- "查看所有商品"
- "商品 prod_123 改价 99"
- "删除商品 prod_456"
- "给商品 prod_789 添加这张图片"
- "把产品 handle 改成英文"
- "创建白色 S 码变体，SKU 为 CUP-S-WHITE"
**订单处理**：
- "今天的订单"
- "待发货订单"
- "订单 order_123 详情"
- "订单 order_456 发货，快递单号 DHL123456"
- "取消订单 order_789"
- "标记订单 order_123 已送达"
**库存管理**：
- "库存低于 5 的商品"
- "商品 prod_123 库存改为 50"
- "查看商品 prod_456 的库存历史"
- "预留商品 prod_789 的 10 个库存"
**物流管理**：
- "计算从香港到纽约的运费，0.5 公斤"
- "查看订单 order_123 的物流历史"
- "创建北美运费区域，包含 US、CA、MX"
**国际化管理**：
- "查看支持的语言"
- "给商品 prod_123 添加中文翻译"
- "更新商品 prod_456 的日语翻译"
- "查看商户的所有翻译"
- "给变体 var_123 添加日语翻译"
- "给集合 coll_456 添加西班牙语翻译"
**首页配置**：
- "查看首页所有模块"
- "创建轮播图模块"
- "更新首页设置，启用搜索栏"
- "重新排序首页模块"
- "给首页添加中文翻译"
**集合管理**：
- "创建夏季促销集合"
- "查看所有集合"
- "给集合 coll_123 添加商品 prod_456"
- "从集合中移除商品"
- "给集合添加西班牙语翻译"
**客服管理**：
- "查看所有对话"
- "创建新的客户对话"
- "给对话 conv_123 发送消息"
**测试工具**：
- "检查 API 健康状态"
- "运行冒烟测试"
- "测试 Stage 环境的服务"
> **提示**：说话越自然越好，Claude 会理解你的意图并调用正确的命令。
## 🛠 工具命令
```bash
commerce init # 在当前项目启用 Commerce CLI（创建 Claude Skill）
commerce cleanup # 清理配置文件
commerce version # 显示版本信息
```
## 🏗 项目状态
**当前版本：v1.0.0** 🎉
✅ **已完成功能**：
- ✅ 完整的 OAuth 2.0 认证系统（Device Flow + 自动刷新）
- ✅ 16 个核心功能模块（新增 test 测试模块）
- ✅ 95+ 个完整命令
- ✅ 默认 JSON 输出（AI 优先设计）
- ✅ 双输出模式（JSON + Pretty）
- ✅ 国际化翻译管理系统（支持 5 种语言）
- ✅ 首页配置管理（模块化组件 + 多语言）
- ✅ 集合管理（CRUD + 产品关联 + 翻译）
- ✅ **三环境隔离支持**（Production/Stage/Development）
- ✅ **测试工具集成**（健康检查 + 冒烟测试 + E2E 脚本）
- ✅ Claude Code 深度集成
- ✅ 完善的错误处理和用户提示
- ✅ 单元测试覆盖（19 tests, 81% coverage）
- ✅ 交互式命令提示
- ✅ 智能环境检测（终端 vs AI/CI）
**功能覆盖率**：100%（所有核心商户运营功能 + 测试工具）
## 🔧 开发
```bash
# 克隆仓库
git clone https://github.com/Optima-Chat/commerce-cli.git
cd commerce-cli
# 安装依赖
npm install
# 开发模式运行
npm run dev
# 构建
npm run build
# 测试
npm test # 运行所有测试
npm run test:watch # 监听模式
npm run test:coverage # 生成覆盖率报告
# 发布到 NPM
npm version minor # 升级版本号
git push --follow-tags # 推送触发自动发布
```
## 📚 技术栈
- **语言**：TypeScript 5.3
- **CLI 框架**：Commander.js
- **HTTP 客户端**：Axios
- **交互提示**：Inquirer.js
- **UI 组件**：Chalk（颜色）+ cli-table3（表格）+ Ora（加载动画）
- **配置存储**：Conf（加密）
- **认证**：OAuth 2.0 Device Flow
- **测试**：Jest + ts-jest（19 tests, 81% coverage）
## 📝 许可证
[MIT License](./LICENSE)
## 🔗 相关链接
- [Optima Commerce 官网](https://www.optima.shop)
- [Agentic Chat](https://ai.optima.chat) - 卖家对话界面
- [Optima Store](https://go.optima.shop) - 买家购物前端
- [Claude Code](https://claude.com/claude-code)
- [NPM Package](https://www.npmjs.com/package/@optima-chat/commerce-cli)
- [GitHub Issues](https://github.com/Optima-Chat/commerce-cli/issues)
## 💬 支持
遇到问题？
- 提交 [Issue](https://github.com/Optima-Chat/commerce-cli/issues)
- 查看完整命令列表：`commerce --help`
- 联系团队：support@optima.chat
---
**由 [Optima Commerce Team](https://www.optima.shop) 用 ❤️ 打造**