account-manager/references/CLI.md

# account-manager CLI 速查

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

> **说明**：内置 `_USAGE`（无参数启动 CLI）已列出加密三类子命令；更完整的 JSON 约定仍以本文与源码为准。


## stdout / JSON 约定（集成必读）

- 若干命令输出 **单层 JSON 对象**（例如 `account pick-web`、`account get`、`account get-credential` 成功时），**没有**统一的 `{"success":true}` 外层包裹。
- `account add-web`、`account add-secret`（等多数字命令）成功时为 **`{"success": true, "data": {...}}`**。
- `credential pick` / `credential resolve` 成功时为 **`{"success": true, ...字段}`**。
- `platform list` / `platform get` 成功时为 **`{"success": true, "data": ...}`**。
- 失败行多为 **`{"success": false, "error": {"code": "...", "message": "..."}}`**（个别老旧路径仍可能打印 `ERROR:` 前缀文本，首行解析逻辑见 [INTEGRATION.md](INTEGRATION.md)）。

---

## 子命令速查（按业务流程）

### 0. 运行时初始化（宿主标准）

| CLI | 说明 |
|---|---|
| `init-db` | 幂等初始化本地 SQLite、schema 迁移与数据管理中文元数据（`_jiangchang_*`）。成功输出 JSON：`{"ok":true,"skill":"account-manager","db_path":"..."}`。**匠厂安装/升级技能时会调用本命令**；业务命令内部也会触发同等 `init_db()`。 |

### A. 平台管理

| CLI | 说明 |
|---|---|
| `platform list [--domain logistics\|llm\|content]` | 列出平台注册（`--domain` 仅接受这三种；`dev`/`sim` 等平台请省略 `--domain` 查全量或在 JSON 里筛选） |
| `platform get <platform>` | 获取数据库中的平台详情 |

### B. 加密初始化（v2）

| CLI | 说明 |
|---|---|
| `account init-master-key` | 生成 master.key（写入 `{数据根}/{用户}/account-manager/master.key`） |
| `account init-master-key --print` | 生成密钥并 **单行 JSON** 打印完整 key（备份用，不落盘） |
| `account init-master-key --from-env` | 从 `ACCOUNT_MANAGER_MASTER_KEY` 读取合法 Fernet key 并写入文件 |
| `account init-master-key --rotate` | 覆盖现有 master.key（stderr 会先打印警告；应先有 export 备份） |

### C. 账号管理（v2 扩展）

| CLI | 说明 |
|---|---|
| `account add-web --platform <p> [--login-id <id>] [--login-id-type <type>] [...]` | 创建网页/RPA 账号；可选 `--auth-strategy` / `--session-persistent 0\|1` / `--device-fingerprint <fp>` |
| `account add-secret --platform <p> --credential-type <t> --secret-storage env\|windows_credential\|none\|local_encrypted` | 创建凭据；`local_encrypted` **必须** `--secret-stdin` |
| `account get <id> [--with-credentials]` | 输出账号 JSON（若带 `--with-credentials` 则附加关联凭据摘要） |
| `account resolve [--id <id>] [--platform <p>] [--login-id <手机号/用户名>] [--label <备注>] [--query <…>]` | **用人话定位一条账号**（成功输出同 `get`）；多条匹配返回 `ERROR:AMBIGUOUS_ACCOUNT` |
| `account get-credential <account_id> [--reveal --lease-token <token>]` | v2：**按账号 id** 取活跃凭据；`--reveal` 必须配合合法 lease |
| `account list [--platform <p>] [...] [--login-id <id>] [--label <label>] [--limit N]` | 输出账号 JSON **数组**；可按登录标识/备注筛选 |
| `account pick-web --platform <p> [...] [--login-id <…>] [--label <…>] [--lease] [...] [--ensure]` | 挑选网页自动化候选；可按手机号/用户名/备注精确筛选；`--ensure` 等同 `ensure-web` |
| `account ensure-web --platform <p> [--login-id <…>] [--label <…>] [...] [--lease]` | **有则 pick、无则 add-web 再 pick**；指定 `--login-id`/`--label` 时按该标识筛选/创建；均被租约占用时**不新建**，返回 `ERROR:LEASE_CONFLICT` |
| `account mark-session <id> --session-status <status>` | 标记会话状态 |
| `account mark-error <id> --code <code> --message <msg>` | 标记错误 |
| `account mark-used <id>` | 标记已使用 |
| `account open <id>` | 打开持久化浏览器 profile（仅查看） |
| `account reveal-profile <id>` | 在系统文件管理器中打开该账号 `profile_dir` |

### D. 加密备份与迁移（v2）

| CLI | 说明 |
|---|---|
| `account export-credentials --plaintext` | 将所有凭据行导出为 JSON **数组** 打到 stdout（stderr 有人类可读警告）；**必须**显式 `--plaintext` |
| `account import-credentials [--replace-all]` | 从 stdin 读 JSON 数组，仅对带 `plaintext` 的行调用加密插入；结果摘要打到 **stderr** |

### E. 凭据 / 租约 / 浏览器（v1 兼容入口保留）

以下命令仍推荐使用，行为与 v1 时期一致，适合「只拿 API Key」或脚本兼容：

| CLI | 说明 |
|---|---|
| `credential pick --platform <p> [--type <type>] [--environment <env>] [--role <role>] [--reveal]` | v1 兼容：挑选凭据 |
| `credential resolve --id <credential_id> [--reveal]` | v1 兼容：按凭据 id 解析 |
| `lease release <lease_token>` | 释放租约 |
| `lease list [--active]` | 列出租约 |
| `lease cleanup` | 清理过期租约 |
| `account open <id>` / `open <id>` | 浏览器查看 |
| `account reveal-profile <id>` | 打开 Profile 目录 |

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

| CLI | 等价 / 说明 |
|---|---|
| `get <id>` | `account get <id>` |
| `list-json <platform\|all> [--limit N]` | JSON 数组输出 |
| `pick-web <platform>` | `account pick-web --platform <platform>`（无 lease 参数） |
| `list [platform\|all]` | 人类可读列表 |
| `add <platform> <phone>` | 映射到 `account add-web`（`login_id_type=phone`），不传 v2 扩展参数 |
| `delete id\|platform <...>` | 删除账号 |

---

## account add-web（扩参示例）

```bash
# 扫码登录的抖音账号
python main.py account add-web \
  --platform douyin \
  --label "douyin-creator-1" \
  --auth-strategy qr_code_manual \
  --session-persistent 1
```

- `--auth-strategy`：`password_auto` / `password_with_captcha` / `password_plus_2fa` / `qr_code_manual` / `per_session_manual` / `device_bound` / `client_certificate` / `api_token` / `sso_redirect`；省略时按平台默认（`seed_platforms` + `platforms.default_auth_strategy`，回填规则见 `db/platform_defaults.py`）；非法值返回 **`ERR_AUTH_STRATEGY_NOT_SUPPORTED`**。
- `--session-persistent`：`0` 或 `1`；省略时由代码推导：`qr_code_manual`、`password_plus_2fa`、`device_bound`、`sso_redirect` → `1`；`per_session_manual`、`client_certificate` → `0`；其余默认 `1`。
- `--device-fingerprint`：**仅当** `--auth-strategy=device_bound` 时允许设置；否则 **`ERR_DEVICE_FINGERPRINT_NOT_APPLICABLE`**。
- 成功 stdout：`{"success": true, "data": { ... }}`，`data` 内含 `id`、`platform_key`、`profile_dir`、`auth_strategy`、`session_persistent`、`device_fingerprint` 等。

---

## account add-secret（`local_encrypted` 示例）

```bash
echo "my-icbc-password" | python main.py account add-secret \
  --platform icbc_sim \
  --credential-type password \
  --secret-storage local_encrypted \
  --secret-stdin \
  --label "工行仿真主账号"
```

- `local_encrypted` **必须** `--secret-stdin`（否则 **`ERR_LOCAL_ENCRYPTED_REQUIRES_STDIN`**）。
- 允许的 `credential_type`：`password`、`api_key`、`api_token`、`bearer_token`、`refresh_token`、`oauth_client`（`browser_profile` / `note` 会被 **`ERR_LOCAL_ENCRYPTED_TYPE_NOT_ALLOWED`** 拒绝）。
- stdin 为空：**`ERR_LOCAL_ENCRYPTED_EMPTY_STDIN`**。
- master key 未就绪：**`ERR_MASTER_KEY_MISSING`**。
- 成功：`{"success": true, "data": {"credential_id", "account_id", "platform_key", "credential_type", "secret_storage", "secret_mask"}}`。

---

## account get-credential（示例）

```bash
# 不 reveal：仅返回 metadata + mask
python main.py account get-credential 42

# reveal：必须带合法 lease-token（通常来自 pick-web --lease）
LEASE=$(python main.py account pick-web --platform icbc_sim --lease --holder my-rpa | jq -r .lease_token)
python main.py account get-credential 42 --reveal --lease-token "$LEASE"
```

- 无 `--reveal`：单行 JSON，`success`/`account_id`/`credential_id`/`secret_storage`/`secret_mask` 等。
- `--reveal`：`secret_storage=local_encrypted` 等在 lease 校验通过后追加 **`plaintext`**；若底层存储为 `none`，返回 **`plaintext: null`** 及说明字段（并非抛错）。
- 常见错误：`ERR_LEASE_INVALID`、`ERR_CREDENTIAL_MISSING`、`ERR_MASTER_KEY_MISSING`、`ERR_CREDENTIAL_DECRYPT_FAILED`（见 [ERRORS.md](ERRORS.md)）。

---

## account export-credentials / import-credentials（示例）

```bash
# 备份（stdout 为 JSON 数组，含解密后的 plaintext；务必妥善销毁）
python main.py account export-credentials --plaintext > backup-2026-05-11.json

# 在新机器恢复（需先 init-master-key，使 master key 可用）
python main.py account import-credentials --replace-all < backup-2026-05-11.json
```

- 未带 `--plaintext`：**`ERR_EXPORT_REQUIRES_PLAINTEXT_FLAG`**（单行 JSON）。
- `import-credentials` 成功时 **stdout 通常为空**，进度与计数在 **stderr**。

---

## account init-master-key（示例）

```bash
# 首次初始化（写入 master.key）
python main.py account init-master-key

# 打印 key 备份到密码管理器（不落盘）
python main.py account init-master-key --print

# 从环境变量恢复写入文件
ACCOUNT_MANAGER_MASTER_KEY="<base64-44-chars>" python main.py account init-master-key --from-env
```

- 文件已存在且未 `--rotate`：**`ERR_MASTER_KEY_EXISTS`**（JSON）。
- `--from-env` 字符串非法：**`ERR_MASTER_KEY_INVALID`**。

---

## account pick-web（字段）

成功时为 **单行 JSON 对象**（非 `_ok_json` 包裹）。核心字段：

- `id`, `platform_key`, `account_label`, `login_id`, `profile_dir`, `url`, `tenant_id`, `environment`, `role`, `provider_code`, `session_status`
- **v2**：`auth_strategy`, `session_persistent`, `device_fingerprint`
- 带 `--lease`：`lease_token`, `lease_expires_at`（ISO8601 **本地时间**字符串，由内部 Unix 秒字段转换而来）

---

## 9 种 `auth_strategy` 简表（参考）

| 策略键 | 适用场景 | 是否要 plaintext（典型） | 是否要人介入 |
|---|---|---|---|
| `password_auto` | 标准账密表单 | 是 | 否 |
| `password_with_captcha` | 带图形验证码 | 是 | 是（填码阶段） |
| `password_plus_2fa` | 短信/邮件/OTP 2FA | 是 | 是（OTP 阶段） |
| `qr_code_manual` | 扫码登录 | 否 | 是（扫码阶段） |
| `per_session_manual` | 银行/政务等每次手动 | 否 | 是 |
| `device_bound` | 绑机器 / U-Key 等 | 可选（有密码则自动填） | 视情况 |
| `client_certificate` | 客户端证书 + PIN | — | 不可自动化（rpa_helpers 抛错） |
| `api_token` | 无浏览器登录 | 否 | 否 |
| `sso_redirect` | OAuth / SSO 跳转 | 否 | 是（SSO 页阶段） |

业务 skill 同进程调用详见 [RPA_HELPERS.md](RPA_HELPERS.md)。

---

## 通用说明

- **平台参数**：可为 `scripts/util/platforms.py` 中的英文键、`display_name`、任一 alias（不区分大小写）。详见 [PLATFORMS.md](PLATFORMS.md)。
- **数据与路径**：库文件、profile、`master.key` 布局见 [RUNTIME.md](RUNTIME.md)。
- **机器可读集成**：见 [INTEGRATION.md](INTEGRATION.md)。
- **错误码**：见 [ERRORS.md](ERRORS.md)。

## 内置 `_USAGE`（阶段 F）

无参数运行 CLI（例如 `python scripts/main.py` / `python -m cli.app`，cwd=`scripts/`）打印的内置 `_USAGE` 已与 `main()` 路由对齐，包含 **`account init-master-key` / `account export-credentials` / `account import-credentials`**。面向外部仓库的契约摘要见 [V1_COMPATIBILITY.md](V1_COMPATIBILITY.md)。