# account-manager CLI 速查

将 `{baseDir}` 替换为技能根目录。所有命令通过 `python {baseDir}/scripts/main.py` 调用（工作目录可为技能根或 `scripts/`，与命令中的路径一致即可）。下文示例简写为 `python main.py` 表示在 `scripts/` 下执行。

## 子命令与实现（与代码一致）

### 平台管理

| CLI | 说明 |
|-----|------|
| `platform list [--domain logistics\|llm\|content]` | 列出平台注册 |
| `platform get <platform>` | 获取平台详情 |

### 账号管理

| CLI | 说明 |
|-----|------|
| `account add-web --platform <p> --login-id <id> [...]` | 创建网页/RPA 账号 |
| `account add-secret --platform <p> --credential-type <type> [...]` | 创建 API Key/Token 凭据 |
| `account get <id> [--with-credentials]` | 获取单条账号 JSON |
| `account list [--platform <p>] [--environment <env>] [--tenant-id <t>] [--role <role>]` | 列出账号 JSON 数组 |
| `account pick-web --platform <p> [--lease] [--ttl-sec 900]` | 挑选网页自动化候选 |
| `account mark-session <id> --session-status <status>` | 标记登录状态 |
| `account mark-error <id> --code <code> --message <msg>` | 标记错误 |
| `account mark-used <id>` | 标记已使用 |
| `account open <id>` | 打开持久化浏览器 profile（仅查看） |

### 凭据管理

| CLI | 说明 |
|-----|------|
| `credential pick --platform <p> [--type <type>] [--reveal]` | 挑选凭据（默认隐藏 secret） |
| `credential resolve --id <credential_id> [--reveal]` | 按 ID 解析凭据 |

### 租约管理

| CLI | 说明 |
|-----|------|
| `lease release <lease_token>` | 释放租约 |
| `lease list [--active]` | 列出租约 |
| `lease cleanup` | 清理过期租约 |

### 浏览器

| CLI | 说明 |
|-----|------|
| `account open <id>` | 打开浏览器查看（仅查看） |
| `open <id>` | 同上（兼容别名） |

### 兼容入口（旧版别名）

| CLI | 等价于 |
|-----|--------|
| `get <id>` | `account get <id>` |
| `list-json <platform\|all> [--limit N]` | JSON 数组输出 |
| `pick-web <platform>` | `account pick-web --platform <platform>` |
| `list [platform\|all]` | 人类可读列表 |
| `add <platform> <phone>` | `account add-web`（phone 作为 login_id） |
| `delete id\|platform <...>` | 删除账号 |

---

## account add-web

```bash
python main.py account add-web \
  --platform maersk \
  --login-id demo@maersk.com \
  --login-id-type email \
  --label "Maersk simulator booking" \
  --tenant-id tenant-demo \
  --environment simulator \
  --role booking \
  --provider-code maersk \
  --url http://localhost:5180/industries/logistics/maersk/login
```

- `--platform`（必填）：平台键/别名
- `--login-id`：登录标识（email/username/phone/customer_code）
- `--login-id-type`：默认 `unknown`
- `--label`：人可读名称，不填则自动拼接
- `--tenant-id`：租户/项目标识
- `--environment`：默认 `production`
- `--role`：默认 `default`
- `--provider-code`：默认取平台 provider_code
- `--url`：默认取平台 default_url
- `--extra-json`：扩展 JSON
- `--profile-dir`：高级调试用，不推荐

输出 JSON，包含 `id`、`profile_dir`、`url` 等。

## account add-secret

```bash
# env 方式
python main.py account add-secret \
  --platform deepseek \
  --credential-type api_key \
  --label "DeepSeek env key" \
  --secret-storage env \
  --secret-ref DEEPSEEK_API_KEY \
  --environment production \
  --role api

# windows_credential 方式
echo "sk-test-1234" | python main.py account add-secret \
  --platform deepseek \
  --credential-type api_key \
  --label "DeepSeek production key" \
  --secret-storage windows_credential \
  --secret-stdin \
  --environment production \
  --role api
```

- `--secret-storage`：`env` / `windows_credential` / `none`
- `--secret-stdin`：从 stdin 读取 secret（仅 windows_credential）
- `--secret-ref`：环境变量名（仅 env）
- `none` 仅允许 `credential_type=browser_profile` 或 `note`

输出 JSON，包含 `account_id`（未指定 `--account-id` 时会自动创建一条用于挂载凭据的账号记录）、`credential_id`、`secret_mask`、`secret_ref`，**不包含 secret 明文**。

## account pick-web

```bash
python main.py account pick-web \
  --platform maersk \
  --environment simulator \
  --tenant-id tenant-demo \
  --role booking \
  --lease \
  --ttl-sec 900 \
  --holder monitor-competitor-rates \
  --purpose maersk_sim_rpa
```

- 筛选 status=active 且未被 active lease 占用的账号
- 优先 session_status != expired
- 优先 last_used_at 为空的账号
- `--lease`：创建 lease，返回 `lease_token` 和 `lease_expires_at`
- `--ttl-sec`：租约时长，默认 900 秒

## credential pick

成功时输出单行 JSON：`{"success": true, ...fields }`；失败时为 [ERRORS.md](ERRORS.md) 的机器 JSON。

```bash
# 默认不返回 secret
python main.py credential pick --platform deepseek --type api_key --environment production --role api

# --reveal 才返回 secret 明文
python main.py credential pick --platform deepseek --type api_key --environment production --role api --reveal
```

## 通用说明

- **平台参数**：可为 `scripts/util/platforms.py` 中配置的**展示名、别名或英文键**（如 `sohu`、`搜狐号`、`maersk`、`马士基`）。详见 [PLATFORMS.md](PLATFORMS.md)。
- **数据与路径**：库文件、profile 目录由环境变量决定。详见 [RUNTIME.md](RUNTIME.md)。
- **机器可读命令**：成功时输出单行 JSON；失败时首行 `ERROR:`。详见 [INTEGRATION.md](INTEGRATION.md)。
- **错误码**：见 [ERRORS.md](ERRORS.md)。