# 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-logged-in`、`pick-web`、`set-login-status` 的成功/失败约定见 [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-logged-in` — 该平台**已登录**的一条账号（单行 JSON）

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

- 筛选：`login_status = 1`，按 `last_login_at` 优先。
- 失败：首行以 `ERROR:` 开头（**勿当 JSON 解析**）。

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

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

- 优先同 `pick-logged-in`；若无已登录，则取该平台 `updated_at` 最新一条。
- 失败：首行 `ERROR:`。

### `set-login-status` — 回写登录态（跨技能）

```bash
python main.py set-login-status <id> <0|1>
```

- 成功：`stdout` 首行 `OK:SET_LOGIN_STATUS` 或 `OK:CLEARED_LOGIN_STATUS`，退出码 `0`。
- 失败：`stdout` 首行 `ERROR:...`，退出码 `1`。

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

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

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

### `login` — 打开浏览器并**自动检测登录**，写回 `login_status`

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

- 依赖 Playwright；超时与轮询间隔等见 [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`。