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）。

---

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

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 get-credential <account_id> [--reveal --lease-token <token>]	v2：按账号 id 取活跃凭据；--reveal 必须配合合法 lease
account list [--platform <p>] [--environment <env>] [--tenant-id <t>] [--role <role>] [--limit N]	输出账号 JSON 数组
account pick-web --platform <p> [--environment <env>] [--tenant-id <t>] [--role <role>] [--lease] [--ttl-sec 900] [--holder <h>] [--purpose <purpose>]	挑选网页自动化候选；返回 JSON 含 auth_strategy / session_persistent / device_fingerprint
account mark-session <id> --session-status <status>	标记会话状态
account mark-error <id> --code <code> --message <msg>	标记错误
account mark-used <id>	标记已使用
account open <id>	打开持久化浏览器 profile（仅查看）

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>	浏览器查看

兼容入口（旧版别名）

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（扩参示例）

# 扫码登录的抖音账号
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 示例）

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（示例）

# 不 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）。

---

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

# 备份（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（示例）

# 首次初始化（写入 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。

---

通用说明

• 平台参数：可为 scripts/util/platforms.py 中的英文键、display_name、任一 alias（不区分大小写）。详见 PLATFORMS.md。
• 数据与路径：库文件、profile、master.key 布局见 RUNTIME.md。
• 机器可读集成：见 INTEGRATION.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。