client-commons/account-manager
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: update SKILL.md / README.md / CLI.md / INTEGRATION.md for v2

Browse Source 
Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
chendelian
2026-05-11 18:34:42 +08:00
parent dbf5604090
commit 1792ba2a0d
4 changed files with 335 additions and 155 deletions
Download Patch File Download Diff File Expand all files Collapse all files

245
references/CLI.md
View File

@@ -1,160 +1,203 @@
# account-manager CLI 速查
将 `{baseDir}` 替换为技能根目录。所有命令通过 `python {baseDir}/scripts/main.py` 调用（工作目录可为技能根或 `scripts/`，与命令中的路径一致即可）。下文示例简写为 `python main.py` 表示在 `scripts/` 下执行。
将 `{baseDir}` 替换为技能根目录。所有命令通过 `python {baseDir}/scripts/main.py` 调用（工作目录可为技能根或 `scripts/`，与命令中的路径一致即可）。下文示例简写为 `python main.py`，表示在 `{baseDir}/scripts/` 下执行。
## 子命令与实现（与代码一致）
> **说明**：`scripts/cli/app.py` 内置的帮助字符串 `_USAGE` 主要覆盖 platform / account / credential / lease / open；实际路由还支持 **`account init-master-key` / `account export-credentials` / `account import-credentials`**（本文档以代码为准）。
### 平台管理
## 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)）。
---
## 子命令速查（按业务流程）
### A. 平台管理
| CLI | 说明 |
|-----|------|
| `platform list [--domain logistics\|llm\|content]` | 列出平台注册 |
| `platform get <platform>` | 获取平台详情 |
|---|---|
| `platform list [--domain logistics\|llm\|content]` | 列出平台注册（`--domain` 仅接受这三种；`dev`/`sim` 等平台请省略 `--domain` 查全量或在 JSON 里筛选） |
| `platform get <platform>` | 获取数据库中的平台详情 |
### 账号管理
### B. 加密初始化（v2）
| 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 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 | 说明 |
|-----|------|
| `credential pick --platform <p> [--type <type>] [--reveal]` | 挑选凭据（默认隐藏 secret） |
| `credential resolve --id <credential_id> [--reveal]` | 按 ID 解析凭据 |
|---|---|
| `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` | 清理过期租约 |
### 浏览器
| CLI | 说明 |
|-----|------|
| `account open <id>` | 打开浏览器查看（仅查看） |
| `open <id>` | 同上（兼容别名） |
| `account open <id>` / `open <id>` | 浏览器查看 |
### 兼容入口（旧版别名）
| CLI | 等价于 |
|-----|--------|
| CLI | 等价 / 说明 |
|---|---|
| `get <id>` | `account get <id>` |
| `list-json <platform\|all> [--limit N]` | JSON 数组输出 |
| `pick-web <platform>` | `account pick-web --platform <platform>` |
| `pick-web <platform>` | `account pick-web --platform <platform>`（无 lease 参数） |
| `list [platform\|all]` | 人类可读列表 |
| `add <platform> <phone>` | `account add-web`（phone 作为 login_id） |
| `add <platform> <phone>` | 映射到 `account add-web`（`login_id_type=phone`），不传 v2 扩展参数 |
| `delete id\|platform <...>` | 删除账号 |
---
## account add-web
## 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 douyin \
--label "douyin-creator-1" \
--auth-strategy qr_code_manual \
--session-persistent 1
```
- `--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`：高级调试用，不推荐
- `--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` 等。
输出 JSON，包含 `id`、`profile_dir`、`url` 等。
---
## account add-secret
## account add-secret（`local_encrypted` 示例）
```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 \
echo "my-icbc-password" | python main.py account add-secret \
--platform icbc_sim \
--credential-type password \
--secret-storage local_encrypted \
--secret-stdin \
--environment production \
--role api
--label "工行仿真主账号"
```
- `--secret-storage`：`env` / `windows_credential` / `none`
- `--secret-stdin`：从 stdin 读取 secret（仅 windows_credential）
- `--secret-ref`：环境变量名（仅 env）
- `none` 仅允许 `credential_type=browser_profile` 或 `note`
- `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"}}`。
输出 JSON，包含 `account_id`（未指定 `--account-id` 时会自动创建一条用于挂载凭据的账号记录）、`credential_id`、`secret_mask`、`secret_ref`，**不包含 secret 明文**。
---
## account pick-web
## account get-credential（示例）
```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
# 不 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"
```
- 筛选 status=active 且未被 active lease 占用的账号
- 优先 session_status != expired
- 优先 last_used_at 为空的账号
- `--lease`：创建 lease，返回 `lease_token` 和 `lease_expires_at`
- `--ttl-sec`：租约时长，默认 900 秒
- 无 `--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)）。
## credential pick
---
成功时输出单行 JSON：`{"success": true, ...fields }`；失败时为 [ERRORS.md](ERRORS.md) 的机器 JSON。
## account export-credentials / import-credentials（示例）
```bash
# 默认不返回 secret
python main.py credential pick --platform deepseek --type api_key --environment production --role api
# 备份（stdout 为 JSON 数组，含解密后的 plaintext；务必妥善销毁）
python main.py account export-credentials --plaintext > backup-2026-05-11.json
# --reveal 才返回 secret 明文
python main.py credential pick --platform deepseek --type api_key --environment production --role api --reveal
# 在新机器恢复（需先 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` 中配置的**展示名、别名或英文键**（如 `sohu`、`搜狐号`、`maersk`、`马士基`）。详见 [PLATFORMS.md](PLATFORMS.md)。
- **数据与路径**：库文件、profile 目录由环境变量决定。详见 [RUNTIME.md](RUNTIME.md)。
- **机器可读命令**：成功时输出单行 JSON；失败时首行 `ERROR:`。详见 [INTEGRATION.md](INTEGRATION.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)。