# Amazon 结算报表自动下载 CLI

将 `{baseDir}` 替换为技能根目录。入口：`python {baseDir}/scripts/main.py`

## 最小命令

```bash
python {baseDir}/scripts/main.py health
python {baseDir}/scripts/main.py config-path
python {baseDir}/scripts/main.py version
```

## run — 下载结算报表

```bash
python {baseDir}/scripts/main.py run \
  --date-from 2025-12-01 \
  --date-to 2025-12-31 \
  [--seller-code AMA1OF6T]
```

| 参数 | 必填 | 默认 | 说明 |
|------|------|------|------|
| `--date-from` | 否 | `2025-12-01` | 起始日期 YYYY-MM-DD |
| `--date-to` | 否 | `2025-12-31` | 结束日期 YYYY-MM-DD |
| `--seller-code` | 否 | （页面首个 seller） | Amazon 店铺代码 |

### 成功 stdout（JSON，最后一行）

```json
{
  "ok": true,
  "job_id": "abc123",
  "file_path": "{DATA_ROOT}/{USER_ID}/download-settlement-report-amazon/downloads/settlement_....xlsx",
  "filename": "settlement_....xlsx",
  "date_from": "2025-12-01",
  "date_to": "2025-12-31"
}
```

### 失败

- 退出码 `1`
- `ERROR:INVALID_ARGS` / `ERROR:ENTITLEMENT` 等前缀，或 JSON 中 `"ok": false`

## logs / log-get

```bash
python {baseDir}/scripts/main.py logs [--limit 10] [--task-type download_settlement] [--status success]
python {baseDir}/scripts/main.py log-get <log_id>
```

## 运行档位

| OPENCLAW_TEST_TARGET | 行为 |
|----------------------|------|
| `mock`（默认） | 离线 mock，不写真实浏览器 |
| `simulator_rpa` | Playwright 操作线上 sandbox Reports 页 |
| `real_rpa` | 未实现，回退 mock |

## config-path 示例

```json
{
  "skill": "download-settlement-report-amazon",
  "env_path": "{DATA_ROOT}/{USER_ID}/download-settlement-report-amazon/.env",
  "example_path": "{skill_root}/.env.example"
}
```

## health 标准输出（runtime diagnostics）

`health` 委托 `jiangchang_skill_core.collect_runtime_diagnostics`，典型字段：

- `python_executable` — 当前 Python 解释器路径
- `platform_kit_version` / `platform_kit_min_version` / `platform_kit_version_ok`
- `jiangchang_skill_core_file` — 公共库加载来源
- `env_path` / `env_exists` / `example_path`

## 手工排查（共享 python-runtime）

**建议使用宿主共享 python-runtime**，避免技能目录内临时 venv 加载不到公共库：

```text
Windows:
  {JIANGCHANG_DATA_ROOT}\python-runtime\.venv\Scripts\python.exe {baseDir}\scripts\main.py health

通用:
  <shared-python> {baseDir}/scripts/main.py health
```

`<shared-python>` 通常位于 `{JIANGCHANG_DATA_ROOT}/python-runtime/.venv`。

**不建议**在生产/测试机使用技能目录内 `uv run python`，以免加载不到共享 runtime 中的 `jiangchang-platform-kit` / `playwright`。