Release v1.0.56: Credential & Browser Profile Manager

2026-05-05 18:51:00 +08:00
parent 6b6d2969c3
commit 91057fa3b7
29 changed files with 4582 additions and 900 deletions
--- a/references/CLI.md
+++ b/references/CLI.md
@@ -4,102 +4,157 @@

 ## 子命令与实现（与代码一致）

-| CLI（`main.py` 第一参或等价路由） | 实现（`scripts/service/`） |
-|----------------------------------|---------------------------|
-| `add` | `account_service.cmd_add` |
-| `list`；或首参为平台且 `list`/单参 | `account_service.cmd_list`（路由见 `cli/app.py`） |
-| `get` | `account_service.cmd_get` |
-| `list-json` | `account_service.cmd_list_json` |
-| `pick-web` | `account_service.cmd_pick_web` |
-| `open` | `browser_service.cmd_open` |
-| `delete` | `account_service.cmd_delete_by_id` / `cmd_delete_by_platform` / `cmd_delete_by_platform_phone` |
+### 平台管理

-入口：`scripts/main.py` → `cli/app.py` → 上表。
+| CLI | 说明 |
+|-----|------|
+| `platform list [--domain logistics\|llm\|content]` | 列出平台注册 |
+| `platform get <platform>` | 获取平台详情 |
+
+### 账号管理
+
+| 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 mark-error <id> --code <code> --message <msg>` | 标记错误 |
+| `account mark-used <id>` | 标记已使用 |
+| `account open <id>` | 打开持久化浏览器 profile（仅查看） |
+
+### 凭据管理
+
+| CLI | 说明 |
+|-----|------|
+| `credential pick --platform <p> [--type <type>] [--reveal]` | 挑选凭据（默认隐藏 secret） |
+| `credential resolve --id <credential_id> [--reveal]` | 按 ID 解析凭据 |
+
+### 租约管理
+
+| CLI | 说明 |
+|-----|------|
+| `lease release <lease_token>` | 释放租约 |
+| `lease list [--active]` | 列出租约 |
+| `lease cleanup` | 清理过期租约 |
+
+### 浏览器
+
+| CLI | 说明 |
+|-----|------|
+| `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>` |
+| `list [platform\|all]` | 人类可读列表 |
+| `add <platform> <phone>` | `account add-web`（phone 作为 login_id） |
+| `delete id\|platform <...>` | 删除账号 |
+
+---
+
+## 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`（必填）：平台键/别名
+- `--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`：高级调试用，不推荐
+
+输出 JSON，包含 `id`、`profile_dir`、`url` 等。
+
+## account add-secret
+
+```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 \
+  --secret-stdin \
+  --environment production \
+  --role api
+```
+
+- `--secret-storage`：`env` / `windows_credential` / `none`
+- `--secret-stdin`：从 stdin 读取 secret（仅 windows_credential）
+- `--secret-ref`：环境变量名（仅 env）
+- `none` 仅允许 `credential_type=browser_profile` 或 `note`
+
+输出 JSON，包含 `account_id`（未指定 `--account-id` 时会自动创建一条用于挂载凭据的账号记录）、`credential_id`、`secret_mask`、`secret_ref`，**不包含 secret 明文**。
+
+## account pick-web
+
+```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
+```
+
+- 筛选 status=active 且未被 active lease 占用的账号
+- 优先 session_status != expired
+- 优先 last_used_at 为空的账号
+- `--lease`：创建 lease，返回 `lease_token` 和 `lease_expires_at`
+- `--ttl-sec`：租约时长，默认 900 秒
+
+## credential pick
+
+成功时输出单行 JSON：`{"success": true, ...fields }`；失败时为 [ERRORS.md](ERRORS.md) 的机器 JSON。
+
+```bash
+# 默认不返回 secret
+python main.py credential pick --platform deepseek --type api_key --environment production --role api
+
+# --reveal 才返回 secret 明文
+python main.py credential pick --platform deepseek --type api_key --environment production --role api --reveal
+```

 ## 通用说明

- **平台参数**：可为 `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；详见运行环境说明。
- 仅供人工核对页面；登录与否由业务侧（如 llm-manager 网页引擎）在使用账号时自行处理。
-
-### `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`。
+- **平台参数**：可为 `scripts/util/platforms.py` 中配置的**展示名、别名或英文键**（如 `sohu`、`搜狐号`、`maersk`、`马士基`）。详见 [PLATFORMS.md](PLATFORMS.md)。
+- **数据与路径**：库文件、profile 目录由环境变量决定。详见 [RUNTIME.md](RUNTIME.md)。
+- **机器可读命令**：成功时输出单行 JSON；失败时首行 `ERROR:`。详见 [INTEGRATION.md](INTEGRATION.md)。
+- **错误码**：见 [ERRORS.md](ERRORS.md)。