# PodPSD CLI 使用文档

`podpsd` 是 PodPSD 平台的官方命令行工具，覆盖**模板管理、批量套图生成、账号与 API Key、用量计费、平台管理**等能力。所有命令都支持 `--json` 输出，天然适合脚本与 AI Agent（如 codex）自动化调用。

- 服务基址（默认）：`https://psd.elmdesk.com`
- 在线接口文档：`https://psd.elmdesk.com/api-docs`
- 在线 CLI 文档：`https://psd.elmdesk.com/cli-docs`

---

## 1. 安装

CLI 是一个独立的 Python 包（`podpsd-cli`），位于仓库 `backend/` 目录。

```bash
# 进入后端目录，安装（建议使用虚拟环境）
cd backend
pip install -e .

# 验证
podpsd --version      # podpsd, version 1.0.0
podpsd --help
```

依赖：`click`、`httpx`、`tabulate`（`pip install -e .` 会自动装好）。

也可以不安装、直接用模块方式运行：

```bash
python -m podpsd_cli --help
```

---

## 2. 三类凭证与鉴权模型

CLI 的接口分两大类，用不同的凭证：

| 接口类别 | 命令 | 使用的凭证 | HTTP 头 |
|---|---|---|---|
| 合成/模板类 | `template` / `generate` / `image` / `ping` | **API Key** 或 内部 `POD_TOKEN` | `X-Api-Key` 或 `Authorization: Basic` |
| 平台类 | `whoami` / `key` / `usage` / `admin` | **会话 JWT**（登录获得） | `Authorization: Bearer` |

- **API Key**：租户维度的密钥，用于程序化生成图片、管理自己的模板。通过 `podpsd key create` 生成。
- **会话 JWT**：`podpsd login` / `register` 后自动保存，用于控制台与管理后台接口。
- **POD_TOKEN**：内部管理员直连合成接口的令牌（内网/管理员用），可选。

---

## 3. 凭证优先级与配置

凭证与基址的取值优先级（高 → 低）：

1. 命令行参数：`--base-url` / `--api-key` / `--token` / `--pod-token`
2. 环境变量：`PODPSD_BASE_URL` / `PODPSD_API_KEY` / `PODPSD_TOKEN` / `PODPSD_POD_TOKEN`
3. 配置文件：`~/.podpsd/config.json`
4. 默认值（基址默认 `https://psd.elmdesk.com`）

其它环境变量：

- `PODPSD_JSON=1`：全局强制 JSON 输出（等价每次都带 `--json`，推荐 Agent 使用）。
- `PODPSD_CONFIG_DIR`：自定义配置目录（默认 `~/.podpsd`）。多账号并行时很有用。

### 写入配置

```bash
podpsd configure --base-url https://psd.elmdesk.com --api-key pod_live_xxx
# 交互式：仅执行 podpsd configure 会提示输入
```

### 查看当前生效配置（敏感值自动打码）

```bash
podpsd config-show
```

---

## 4. 输出模式

- **默认**：人类可读表格（`tabulate`）。
- **`--json`**：机器可读 JSON，**注意 `--json` 是全局选项，必须放在子命令之前**：

```bash
podpsd --json template list          # ✅ 正确
podpsd template list --json          # ❌ 错误（会报 No such option）
```

或用环境变量（对所有命令生效）：

```bash
export PODPSD_JSON=1
podpsd template list
```

---

## 5. 命令速查

```
podpsd
├── configure                写入本地配置
├── config-show              查看生效配置
├── ping                     健康检查
├── register                 注册租户（保存会话）
├── login                    登录（保存会话）
├── whoami                   当前用户与用量
├── template
│   ├── upload PATH          上传本地 PSD 为模板
│   ├── add-url URL          用链接添加模板
│   ├── list                 模板列表
│   ├── get SKU              模板详情（含 slots 槽位）
│   └── delete SKU           删除模板
├── generate                 生成套图（核心命令）
├── image
│   ├── get SKU              图片详情
│   └── list                 图片列表
├── key                      （需登录）
│   ├── list                 列出 API Key
│   ├── create --name        创建 API Key（明文仅出示一次）
│   └── revoke ID            撤销 API Key
├── usage                    （需登录）
│   ├── summary              用量概览
│   └── logs                 用量流水
└── admin                    （需 platform_admin）
    ├── stats                平台仪表盘
    ├── tenants              租户列表
    ├── plans                套餐列表
    └── usage                全平台用量流水
```

---

## 6. 典型工作流

### 6.1 用 API Key 跑批（推荐给自动化/codex）

```bash
export PODPSD_BASE_URL=https://psd.elmdesk.com
export PODPSD_API_KEY=pod_live_xxxxxxxx
export PODPSD_JSON=1

# 1) 上传模板
podpsd template upload ./cover.psd --title "封面模板A"
# → {"sku": "1782...", "width": 2480, "height": 3508, "slots": ["sucai","logo"]}

# 2) 查看模板槽位
podpsd template get 1782...        # slots 字段即可替换的图层名

# 3) 生成（本地素材自动上传 + 远程链接混用），并下载结果
podpsd generate --psd 1782... \
  --material sucai=./product.jpg \
  --set logo=https://cdn.example.com/logo.png \
  --mode auto \
  --out ./result.jpg
# → {"success":1,"sku":"...","oss":"https://.../xxx.jpg","billing":{"units":1.5,"cost":0.0}}
```

### 6.2 账号 / 控制台

```bash
# 注册（自动登录并保存会话到 ~/.podpsd/config.json）
podpsd register --email you@corp.com --password 'yourpass' --company '你的公司'

# 或已有账号登录
podpsd login --email you@corp.com --password 'yourpass'

# 查看自己
podpsd whoami

# 创建 API Key（明文仅此一次返回，请立即保存）
podpsd --json key create --name "ci-key"
podpsd key list
podpsd key revoke 3

# 用量
podpsd usage summary
podpsd usage logs --page 1 --rows 50
```

### 6.3 平台管理（管理员）

```bash
podpsd login --email admin@podpsd.com --password '******'
podpsd admin stats
podpsd admin tenants --page 1 --rows 20
podpsd admin plans
podpsd admin usage --tenant-id 6
```

---

## 7. `generate` 命令详解

```
podpsd generate --psd SKU [选项]
```

| 选项 | 说明 |
|---|---|
| `--psd SKU` | **必填**，模板 sku |
| `--set name=URL` | 按槽位名指定素材图片**链接**，可重复 |
| `--material name=PATH` | 按槽位名指定**本地素材文件**（自动先上传再替换），可重复 |
| `--mode` | 填充模式：`auto`（默认满铺）/`cover`/`contain`/`fill` |
| `--sub SKU` | 订阅/业务类型 sku（可选） |
| `--callback URL` | 异步回调地址（配合 `--async`） |
| `--async` | 异步生成，立即返回图片 sku，稍后回调 |
| `--out FILE` | 同步模式下把生成结果下载到本地文件 |

- `name` 为模板里的可替换图层名（用 `template get` 查 `slots`）。
- `--set` 与 `--material` 可同时使用、可各自多次。
- 计费：每张成功生成计一次用量；套餐内不额外扣费，超额按「基础单价 × 像素分档系数」计价（≤2MP=1×、≤8MP=1.5×、≤30MP=2.2×、>30MP=3×）。返回体中的 `billing` 字段给出本次 `units` 和 `cost`。

---

## 8. 退出码与错误处理

- 成功退出码 `0`；失败为非 0。
- 错误信息打到 **stderr**，格式：`错误: <消息>`。
- 业务错误（合成接口 `code != 10000`）与 HTTP 4xx/5xx 都会被捕获并给出可读消息。

Agent 建议：设置 `PODPSD_JSON=1`，用退出码判断成败，用 stdout 的 JSON 取字段（如 `oss`、`sku`、`billing.cost`）。

---

## 9. 在 CI / 脚本中使用示例

```bash
#!/usr/bin/env bash
set -euo pipefail
export PODPSD_BASE_URL=https://psd.elmdesk.com
export PODPSD_API_KEY="$POD_API_KEY"   # 从 CI Secret 注入
export PODPSD_JSON=1

sku=$(podpsd template upload ./tpl.psd --title auto | jq -r .sku)
oss=$(podpsd generate --psd "$sku" --material sucai=./m.jpg | jq -r .oss)
echo "generated: $oss"
```

---

## 10. 常见问题

- **`No such option: --json`**：`--json` 要放在子命令前，或改用 `PODPSD_JSON=1`。
- **`未登录：请先 podpsd login`**：`key`/`usage`/`admin` 需要会话 JWT，先 `login`。
- **`需要平台管理员权限`**：`admin` 命令需要 `platform_admin` 角色的账号。
- **多账号并行**：用 `PODPSD_CONFIG_DIR` 指向不同目录隔离会话。