# account-manager CLI 参考

入口：`{skillRoot}/scripts/main.py`（宿主可将 `{baseDir}` 或技能根目录代入）。下文用 `python main.py` 表示在 `scripts/` 目录执行，或写成 `python {skillRoot}/scripts/main.py`。

## 通用说明

- **平台参数**：可为 `scripts/util/platforms.py` 中配置的**中文展示名、别名或英文键**（如 `sohu`、`搜狐号`）。详见 [PLATFORMS.md](PLATFORMS.md)。
- **数据与路径**：库文件、profile 目录由环境变量决定，网关与本地终端不一致时会「看不到同一份数据」。详见 [RUNTIME.md](RUNTIME.md)。
- **机器可读子命令**：`get`、`list-json`、`pick-web` 的成功/失败约定见 [INTEGRATION.md](INTEGRATION.md)。
- **错误码前缀**：见 [ERRORS.md](ERRORS.md)。

> 说明：当前版本 **未实现** `health` / `version` 子命令；与工作区其它技能的统一约定可对齐后另补。

---

## 子命令一览

### `add` — 添加账号

```bash
python main.py add <平台> <手机号>
```

- 手机号为**中国大陆 11 位**（`1` 开头，第二位 `3–9`），可含空格/分隔符，入库前会归一成数字。
- 同一 `platform` 下同一手机号不可重复。

### `list` — 列出账号（人类可读多行块）

```bash
python main.py list [平台|all|全部]
```

- 省略第二参数时等价于 `all`。
- 默认最多 **10** 条（按创建时间倒序）；内部实现见 `service/account_service.cmd_list`。

### 简写：`python main.py <平台>` / `python main.py <平台> list`

- 若第一个参数能解析为平台，则等价于 `list <平台>`。

### `get` — 按 id 输出**单行 JSON**

```bash
python main.py get <id>
```

- 成功：`stdout` **仅一行** JSON 对象（UTF-8）。
- 失败：首行 `ERROR:ACCOUNT_NOT_FOUND`，路径提示在 stderr。

### `list-json` — 列表的**单行 JSON 数组**（跨技能）

```bash
python main.py list-json <平台|all|全部> [--limit N]
```

- 成功：`stdout` **仅一行** JSON 数组；元素结构与 `get` 单条一致。
- 默认 `limit=200`，实际 clamp 为 `1..500`。
- 排序：按 `updated_at` 倒序。

### `pick-web` — 网页自动化候选账号（单行 JSON）

```bash
python main.py pick-web <平台>
```

- 按该平台 `updated_at`、`created_at` 倒序选一条；**不**表示当前浏览器已登录。
- 失败：首行 `ERROR:`。

### `open` — 仅打开浏览器（**不写库**）

```bash
python main.py open <id>
```

- 需本机 Chrome/Edge + Playwright；详见运行环境说明。

### `login` — 打开浏览器并**自动检测登录**（成功则刷新 `updated_at`）

```bash
python main.py login <id>
```

- 依赖 Playwright；超时与轮询间隔等见 [RUNTIME.md](RUNTIME.md)。
- **不**在库中持久化「是否已登录」；仅刷新 `updated_at` 供 `pick-web` 等排序参考。

### `wait-login` — 跨技能：**始终以本次 DOM 检测为准**

```bash
python main.py wait-login <id>
```

- 由**账号管理**打开浏览器并完成 DOM 检测；调用方只需 `subprocess` 等待本进程结束，成功时 stdout 含 `OK:WAIT_LOGIN`。
- 会先打印若干行说明（含 `INFO:WAIT_LOGIN_BEGIN`），再进入检测；超时、关窗、启动失败等见 [ERRORS.md](ERRORS.md)。
- 时间窗由 `JIANGCHANG_WAIT_LOGIN_TIMEOUT_SECONDS` 控制，见 [RUNTIME.md](RUNTIME.md)。

### `delete` — 删除库记录并尽量删除 profile 目录

```bash
python main.py delete id <id>
python main.py delete platform <平台>
python main.py delete platform <平台> <手机号>
```

- 第二段必须为 `id` 或 `platform`（小写不敏感）。

---

## 无参数 / 未知子命令

- 无参数或无法解析：打印用法概览；未知子命令时首行 `ERROR:CLI_UNKNOWN_OR_BAD_ARGS`，退出码 `1`。