feat: account ensure-web (pick-or-create for first-run UX)

Co-authored-by: Cursor <cursoragent@cursor.com>

SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: 账号与凭据管理
 description: "通用账号 & 凭据 & 登录流程管理器。管理网页/RPA 账号、API Key/Token；支持 9 种登录策略（账密自动、扫码、2FA、SSO 等）；提供加密本地存储（Fernet）；提供 rpa_helpers 库供业务 skill 同进程调用 ensure_logged_in 完成多平台自动登录。涵盖物流、LLM、内容、开发、API 五类平台。"
-version: 2.0.0
+version: 2.0.8
 author: 深圳匠厂科技有限公司
 metadata:
   openclaw:
@@ -30,7 +30,7 @@ allowed-tools:
 1. **登记网页/RPA 账号**：`account add-web` — 平台 + 登录标识 + 自动生成 profile_dir；可选 `--auth-strategy` / `--session-persistent` / `--device-fingerprint`。
 2. **登记凭据（API Key / Token / 加密密码）**：`account add-secret` — `none` / `env` / `windows_credential` / `local_encrypted`。
 3. **查看/列出账号**：`account get/list` — JSON 输出。
-4. **为 RPA 挑选账号**：`account pick-web` — 按环境/租户/角色筛选，可带 lease。
+4. **为 RPA 挑选账号**：`account pick-web` — 按环境/租户/角色筛选，可带 lease；业务首启推荐 `account ensure-web`（或 `pick-web --ensure`）：无账号则按调用方参数自动 `add-web` 再返回。
 5. **获取 API Key（凭据表）**：`credential pick` — 默认隐藏 secret，`--reveal` 时才返回。
 6. **浏览器打开查看**：`account open <id>`（或兼容别名 `open <id>`）— 仅查看，不做站点侧登录判定。
 7. **管理 lease**：`lease release/list/cleanup` — 防止 RPA 并发。
@@ -38,6 +38,7 @@ allowed-tools:
 9. **加密备份与迁移**：`account export-credentials --plaintext` / `account import-credentials` — 导出明文 JSON、在新环境重新加密写入。
 10. **按 lease 取明文密码**：`account get-credential <id> --reveal --lease-token <token>` — 结合 pick-web 返回的 lease 解密 `local_encrypted` 等路径。
 11. **业务 skill 同进程登录**：`from service.rpa_helpers import ensure_logged_in` — 详见 [`references/RPA_HELPERS.md`](references/RPA_HELPERS.md)。
+12. **有则用、无则建（网页账号）**：`account ensure-web --platform <p>` — 登记账号 ≠ 已登录；登录仍由业务技能 / `ensure_logged_in` 处理。
 
 ## CLI 调用
 

references/CLI.md

@@ -42,7 +42,8 @@
 | `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 pick-web --platform <p> [...] [--lease] [...] [--ensure]` | 挑选网页自动化候选；`--ensure` 等同 `ensure-web`（零账号时自动登记） |
+| `account ensure-web --platform <p> [--login-id <id>] [--label <label>] [...] [--lease]` | **有则 pick、无则 add-web 再 pick**；有账号但均被租约占用时**不新建**，返回 `ERROR:LEASE_CONFLICT`；成功时结构同 `pick-web`，若本次新建则带 `account_ensured: true` |
 | `account mark-session <id> --session-status <status>` | 标记会话状态 |
 | `account mark-error <id> --code <code> --message <msg>` | 标记错误 |
 | `account mark-used <id>` | 标记已使用 |

references/ERRORS.md

@@ -51,6 +51,7 @@
 | `ERROR:ACCOUNT_NOT_FOUND` | 指定 id 不存在 |
 | `ERROR:ACCOUNT_DISABLED` | 账号状态为 disabled |
 | `ERROR:NO_ACCOUNT` | `pick-web` 无符合条件的可用账号（含均被 active 未过期 lease 占用） |
+| `ERROR:LEASE_CONFLICT` | `ensure-web` / `pick-web --ensure`：已有账号但均被租约占用（**不会**自动再建）；或同账号重复 acquire lease |
 
 ---
 

references/INTEGRATION.md

@@ -11,7 +11,9 @@
 | **A. CLI subprocess（v1 起）** | 任意业务 skill；一次性取账号 JSON / 凭据 / lease | `subprocess.run([sys.executable, f"{skill_root}/scripts/main.py", "account", "pick-web", ...])` |
 | **B. rpa_helpers 同进程 import（v2）** | 需要 Playwright 上下文内完成登录与页面操作 | `sys.path.insert(0, f"{account_manager_root}/scripts"); from service.rpa_helpers import ensure_logged_in` |
 
-常见组合：**CLI** 负责 pick / lease / `get-credential --reveal`；**rpa_helpers** 负责 `launch_browser_with_profile` + `ensure_logged_in`。详见 [`RPA_HELPERS.md`](RPA_HELPERS.md)。
+常见组合：**CLI** 负责 `ensure-web`（或 `pick-web --ensure`）/ lease / `get-credential --reveal`；**rpa_helpers** 负责 `launch_browser_with_profile` + `ensure_logged_in`。详见 [`RPA_HELPERS.md`](RPA_HELPERS.md)。
+
+业务技能首启推荐：`account ensure-web --platform <p> [--label ...] [--lease --holder <skill>]`，避免因库中尚无账号而 `NO_ACCOUNT`。登记账号 ≠ 站点已登录。
 
 ## 推荐调用方式
 
@@ -26,6 +28,7 @@
 | 取单条账号 JSON | `account get <id>` | **单行 JSON 对象**（无固定 `success` 字段） |
 | 批量账号 JSON | `account list ...` | **单行 JSON 数组** |
 | 网页自动化候选 | `account pick-web ...` | **单行 JSON 对象** |
+| 有则用无则建 | `account ensure-web ...` / `pick-web --ensure` | **同 pick-web**；本次新建时多 `account_ensured: true` |
 | 取加密凭据明文 | `account get-credential <id> --reveal --lease-token <t>` | **单行 JSON**，含 `plaintext`（若可解密） |
 | 备份加密凭据 | `account export-credentials --plaintext` | **JSON 数组**（stderr 有警告行） |
 | 导入加密凭据 | `account import-credentials [--replace-all]` | **通常为空**（计数在 stderr） |

requirements.txt

@@ -0,0 +1,3 @@
+# 公共依赖由宿主共享 runtime 提供；这里只声明技能特有 Python 依赖。
+# Fernet 加密（local_encrypted 凭据、master key、CLI 启动 import）依赖此包。
+cryptography>=42.0.0,<45

scripts/cli/app.py

@@ -4,7 +4,7 @@ CLI entry point: argv dispatch for account-manager v2.
 
 Subcommand tree:
   platform  list/get/ensure
-  account   add-web|add-secret|get|get-credential|list|pick-web|mark-session|mark-error|mark-used|open
+  account   add-web|ensure-web|add-secret|get|get-credential|list|pick-web|mark-session|mark-error|mark-used|open
             init-master-key|export-credentials|import-credentials
   credential pick|resolve
   lease     release|list|cleanup
@@ -23,6 +23,7 @@ from service.account_crypto_commands import (
 from service.account_service import (
     cmd_account_add_secret,
     cmd_account_add_web,
+    cmd_account_ensure_web,
     cmd_account_get,
     cmd_account_get_credential,
     cmd_account_list,
@@ -82,6 +83,12 @@ _USAGE = """account-manager v2 — Credential & Browser Profile Manager
   account pick-web --platform <p> [--environment <env>] [--tenant-id <t>]
                    [--role <role>] [--lease] [--ttl-sec 900]
                    [--holder <holder>] [--purpose <purpose>]
+                   [--ensure]   # 同 ensure-web：无账号时自动登记再 pick
+  account ensure-web --platform <p> [--login-id <id>] [--label <label>]
+                     [--environment <env>] [--tenant-id <t>] [--role <role>]
+                     [--lease] [--ttl-sec 900] [--holder <h>] [--purpose <p>]
+                     # 有账号则 pick；零账号则按参数 add-web 后再 pick
+                     # 有账号但均被租约占用时不新建，返回 LEASE_CONFLICT
   account mark-session <id> --session-status <status>
   account mark-error <id> --code <code> --message <msg>
   account mark-used <id>
@@ -246,12 +253,14 @@ def main() -> None:
     # ---- account subcommand ----
     elif cmd == "account":
         if len(av) < 3:
-            print("ERROR:CLI_BAD_ARGS account 需要子命令（add-web / get / …）。")
+            print("ERROR:CLI_BAD_ARGS account 需要子命令（add-web / ensure-web / get / …）。")
             print(_USAGE)
             sys.exit(1)
         sub = av[2]
         if sub == "add-web":
             _cmd_add_web(av)
+        elif sub == "ensure-web":
+            _cmd_ensure_web(av)
         elif sub == "add-secret":
             _cmd_add_secret(av)
         elif sub == "get-credential":
@@ -543,11 +552,15 @@ def _cmd_pick_web_new(argv: list[str]) -> None:
     ttl = _get_int_opt(argv, "--ttl-sec", 900)
     holder = _get_opt(argv, "--holder")
     purpose = _get_opt(argv, "--purpose")
+    do_ensure = _has_flag(argv, "--ensure")
 
     if not plat:
         print("ERROR:CLI_BAD_ARGS account pick-web 需要 --platform <platform>。")
         return
     platform_meta = _parse_platform_caller_meta(argv)
+    if do_ensure:
+        _cmd_ensure_web(argv)
+        return
     cmd_account_pick_web(
         platform_input=plat,
         environment=env,
@@ -561,6 +574,61 @@ def _cmd_pick_web_new(argv: list[str]) -> None:
     )
 
 
+def _cmd_ensure_web(argv: list[str]) -> None:
+    plat = _get_opt(argv, "--platform", "")
+    login_id = _get_opt(argv, "--login-id")
+    login_id_type = _get_opt(argv, "--login-id-type", "unknown")
+    label = _get_opt(argv, "--label")
+    tenant_id = _get_opt(argv, "--tenant-id")
+    environment = _get_opt(argv, "--environment")
+    role = _get_opt(argv, "--role")
+    provider_code = _get_opt(argv, "--provider-code")
+    url = _get_opt(argv, "--url")
+    extra_json_str = _get_opt(argv, "--extra-json")
+    profile_dir_override = _get_opt(argv, "--profile-dir")
+    auth_strategy = _get_opt(argv, "--auth-strategy")
+    session_persistent_raw = _get_opt(argv, "--session-persistent")
+    device_fingerprint = _get_opt(argv, "--device-fingerprint")
+    do_lease = _has_flag(argv, "--lease")
+    ttl = _get_int_opt(argv, "--ttl-sec", 900)
+    holder = _get_opt(argv, "--holder")
+    purpose = _get_opt(argv, "--purpose")
+
+    session_persistent: Optional[int] = None
+    if session_persistent_raw is not None:
+        try:
+            session_persistent = int(session_persistent_raw)
+        except ValueError:
+            print("ERROR:CLI_BAD_ARGS --session-persistent 必须是整数（0 或 1）。")
+            return
+
+    if not plat:
+        print("ERROR:CLI_BAD_ARGS account ensure-web 需要 --platform <platform>。")
+        return
+    platform_meta = _parse_platform_caller_meta(argv)
+    cmd_account_ensure_web(
+        platform_input=plat,
+        login_id=login_id,
+        login_id_type=login_id_type or "unknown",
+        label=label,
+        tenant_id=tenant_id,
+        environment=environment,
+        role=role,
+        provider_code=provider_code,
+        url=url,
+        extra_json_str=extra_json_str,
+        profile_dir_override=profile_dir_override,
+        auth_strategy=auth_strategy,
+        session_persistent=session_persistent,
+        device_fingerprint=device_fingerprint,
+        do_lease=do_lease,
+        ttl_sec=ttl,
+        holder=holder,
+        purpose=purpose,
+        platform_meta=platform_meta,
+    )
+
+
 def _cmd_cred_pick(argv: list[str]) -> None:
     plat = _get_opt(argv, "--platform", "")
     ctype = _get_opt(argv, "--type")

scripts/db/accounts_repo.py

@@ -284,6 +284,36 @@ def find_accounts(
         conn.close()
 
 
+def count_active_accounts(
+    platform_key: str,
+    environment: Optional[str] = None,
+    tenant_id: Optional[str] = None,
+    role: Optional[str] = None,
+) -> int:
+    """Count active accounts matching filters (ignores lease occupancy)."""
+    conn = get_conn()
+    try:
+        conn.row_factory = None
+        cur = conn.cursor()
+        conditions = ["status = 'active'", "platform_key = ?"]
+        params: list = [platform_key]
+        if environment:
+            conditions.append("environment = ?")
+            params.append(environment)
+        if tenant_id:
+            conditions.append("tenant_id = ?")
+            params.append(tenant_id)
+        if role:
+            conditions.append("role = ?")
+            params.append(role)
+        where = " AND ".join(conditions)
+        cur.execute(f"SELECT COUNT(*) FROM accounts WHERE {where}", params)
+        row = cur.fetchone()
+        return int(row[0] or 0) if row else 0
+    finally:
+        conn.close()
+
+
 def find_account_ids(
     platform_key: str,
     environment: Optional[str] = None,

scripts/service/_svc_common.py

@@ -0,0 +1,255 @@
+# -*- coding: utf-8 -*-
+"""Shared helpers for account service command modules."""
+import json
+import os
+import shutil
+import sys
+from dataclasses import dataclass, field
+from typing import Optional
+
+from db.accounts_repo import (
+    insert_account,
+    resolve_auth_strategy_for_platform,
+    ensure_platform_from_caller_meta,
+)
+from db.auth_strategy import (
+    ALL_AUTH_STRATEGIES,
+    AUTH_STRATEGY_CLIENT_CERTIFICATE,
+    AUTH_STRATEGY_DEVICE_BOUND,
+    AUTH_STRATEGY_PASSWORD_PLUS_2FA,
+    AUTH_STRATEGY_PER_SESSION_MANUAL,
+    AUTH_STRATEGY_QR_CODE_MANUAL,
+    AUTH_STRATEGY_SSO_REDIRECT,
+)
+from db.connection import get_conn, init_db
+from util.logging_config import get_skill_logger
+from util.platforms import (
+    DEFAULT_CAPABILITIES_JSON,
+    PlatformResolveResult,
+    _platform_list_cn_for_help,
+    is_valid_platform_key_format,
+    resolve_platform_key_dynamic,
+    seed_platforms,
+)
+
+
+def _map_secret_read_error(exc: BaseException) -> tuple[str, str]:
+    """Map secret read/write exceptions to ERROR:* codes (no secret text in code)."""
+    msg = str(exc)
+    if "SECRET_ENV_MISSING" in msg:
+        return "ERROR:SECRET_ENV_MISSING", msg
+    if "WINDOWS_CREDENTIAL_UNAVAILABLE" in msg:
+        return "ERROR:WINDOWS_CREDENTIAL_UNAVAILABLE", msg
+    return "ERROR:SECRET_READ_FAILED", msg
+
+
+def _credential_ok_line(payload: dict) -> str:
+    """Single-line JSON for credential commands (machine integration)."""
+    return json.dumps({"success": True, **payload}, ensure_ascii=False)
+
+
+def _derive_session_persistent(auth_strategy: str) -> int:
+    """Derive default session_persistent from auth_strategy when CLI omits it."""
+    if auth_strategy in (
+        AUTH_STRATEGY_QR_CODE_MANUAL,
+        AUTH_STRATEGY_PASSWORD_PLUS_2FA,
+        AUTH_STRATEGY_DEVICE_BOUND,
+        AUTH_STRATEGY_SSO_REDIRECT,
+    ):
+        return 1
+    if auth_strategy in (AUTH_STRATEGY_PER_SESSION_MANUAL, AUTH_STRATEGY_CLIENT_CERTIFICATE):
+        return 0
+    return 1
+
+
+def _insert_secret_holder_account(
+    conn,
+    *,
+    platform_key: str,
+    account_label: str,
+    environment: str,
+    role: str,
+    provider_code: str,
+    url: Optional[str],
+    now: int,
+) -> int:
+    """Create a minimal accounts row so credentials can join on environment/role."""
+    return insert_account(
+        conn=conn,
+        platform_key=platform_key,
+        account_label=account_label,
+        login_id=None,
+        login_id_type="api_account",
+        tenant_id=None,
+        environment=environment,
+        role=role,
+        provider_code=provider_code,
+        profile_dir=None,
+        url=url,
+        extra_json="{}",
+        now=now,
+        auth_strategy=resolve_auth_strategy_for_platform(conn, platform_key),
+    )
+
+
+def _err_json(code: str, message: str) -> str:
+    """Return a JSON error line."""
+    return json.dumps(
+        {"success": False, "error": {"code": code, "message": message}},
+        ensure_ascii=False,
+    )
+
+
+def _ok_json(data) -> str:
+    """Return a JSON success line."""
+    return json.dumps(
+        {"success": True, "data": data},
+        ensure_ascii=False,
+    )
+
+
+def _say(msg: str) -> None:
+    """Print to stdout."""
+    print(msg)
+
+
+def _say_err(msg: str) -> None:
+    """Print to stderr."""
+    print(msg, file=sys.stderr)
+
+
+def _fail_human(code: str, hint_lines: list[str]) -> None:
+    """Print human-readable error block."""
+    _say(f"ERROR:{code}")
+    for line in hint_lines:
+        _say(line)
+
+
+def _remove_profile_dir(path: str) -> None:
+    p = (path or "").strip()
+    if not p or not os.path.isdir(p):
+        return
+    try:
+        shutil.rmtree(p)
+    except OSError as e:
+        _say_err(f"WARNING: 未能删除用户数据目录（可手工删）：{p}\n   {e}")
+
+
+@dataclass
+class PlatformCallerMeta:
+    """调用方为未注册自定义平台提供的自动注册元数据（pick-web / add-web）。"""
+
+    display_name: Optional[str] = None
+    url: Optional[str] = None
+    domain: Optional[str] = None
+    auth_strategy: Optional[str] = None
+    aliases: list[str] = field(default_factory=list)
+
+    def is_sufficient_for_auto_register(self) -> bool:
+        return bool((self.display_name or "").strip() and (self.url or "").strip())
+
+
+def _emit_platform_resolve_error(result: PlatformResolveResult, hint: str = "") -> None:
+    code = result.error_code or "INVALID_PLATFORM"
+    if not code.startswith("ERROR:"):
+        code = f"ERROR:{code}"
+    _say(_err_json(code, result.message or "无法识别平台。"))
+    if hint:
+        _say(hint)
+
+
+def _resolve_or_auto_register(
+    platform_input: str,
+    meta: Optional[PlatformCallerMeta] = None,
+    *,
+    hint: str = "",
+) -> Optional[str]:
+    """解析平台；未注册时可在元数据充足时自动 ensure（幂等、仅填空字段）。"""
+    init_db()
+    conn = get_conn()
+    try:
+        result = resolve_platform_key_dynamic(platform_input, conn=conn)
+        if result.ok:
+            return result.platform_key
+
+        if result.error_code in ("PLATFORM_DISABLED", "INVALID_PLATFORM_KEY", "INVALID_PLATFORM"):
+            _emit_platform_resolve_error(result, hint=hint)
+            return None
+
+        if result.error_code != "PLATFORM_NOT_REGISTERED":
+            _emit_platform_resolve_error(result, hint=hint)
+            if result.error_code not in (
+                "PLATFORM_NOT_REGISTERED",
+                "INVALID_PLATFORM_KEY",
+                "PLATFORM_DISABLED",
+            ):
+                _say("支持：" + _platform_list_cn_for_help())
+            return None
+
+        raw_key = (platform_input or "").strip().lower()
+        if not is_valid_platform_key_format(raw_key):
+            _emit_platform_resolve_error(
+                PlatformResolveResult(
+                    error_code="INVALID_PLATFORM_KEY",
+                    message=result.message or f"平台 key 格式非法：「{platform_input}」。",
+                ),
+                hint=hint,
+            )
+            return None
+
+        if not meta or not meta.is_sufficient_for_auto_register():
+            _emit_platform_resolve_error(
+                PlatformResolveResult(
+                    error_code="PLATFORM_NOT_REGISTERED",
+                    message=(
+                        f"平台 {raw_key} 尚未注册。"
+                        "请传入 --platform-display-name 与 --platform-url，"
+                        "或先执行 account platform ensure。"
+                    ),
+                ),
+                hint=hint,
+            )
+            return None
+
+        if meta.auth_strategy and meta.auth_strategy not in ALL_AUTH_STRATEGIES:
+            _say(_err_json(
+                "ERR_AUTH_STRATEGY_NOT_SUPPORTED",
+                f"不支持的 --platform-auth-strategy：{meta.auth_strategy}",
+            ))
+            return None
+
+        seed_platforms(conn)
+        action = ensure_platform_from_caller_meta(
+            conn,
+            raw_key,
+            display_name=(meta.display_name or "").strip(),
+            domain=(meta.domain or "generic").strip() or "generic",
+            default_url=(meta.url or "").strip(),
+            aliases=meta.aliases,
+            default_auth_strategy=meta.auth_strategy,
+            capabilities_json=DEFAULT_CAPABILITIES_JSON,
+        )
+        get_skill_logger().info(
+            "platform_auto_registered key=%s action=%s", raw_key, action
+        )
+        return raw_key
+    finally:
+        conn.close()
+
+
+def _resolve_or_fail(input_name: str, hint: str = "") -> Optional[str]:
+    """Resolve platform key or emit structured JSON error and return None."""
+    init_db()
+    conn = get_conn()
+    try:
+        result = resolve_platform_key_dynamic(input_name, conn=conn)
+    finally:
+        conn.close()
+
+    if result.ok:
+        return result.platform_key
+
+    _emit_platform_resolve_error(result, hint=hint)
+    if result.error_code not in ("PLATFORM_NOT_REGISTERED", "INVALID_PLATFORM_KEY", "PLATFORM_DISABLED"):
+        _say("支持：" + _platform_list_cn_for_help())
+    return None

scripts/service/account_add_commands.py

@@ -0,0 +1,586 @@
+# -*- coding: utf-8 -*-
+"""Account creation CLI commands (add-web, add-secret)."""
+import json
+import os
+import sys
+import time
+from typing import Optional
+
+from db.accounts_repo import (
+    get_account_by_id,
+    insert_account,
+    insert_credential,
+    resolve_auth_strategy_for_platform,
+)
+from db.auth_strategy import (
+    ALL_AUTH_STRATEGIES,
+    AUTH_STRATEGY_DEVICE_BOUND,
+)
+from db.connection import get_conn, init_db
+from db.credentials_repo import insert_credential_encrypted
+from service._svc_common import (
+    PlatformCallerMeta,
+    _derive_session_persistent,
+    _err_json,
+    _insert_secret_holder_account,
+    _ok_json,
+    _resolve_or_auto_register,
+    _resolve_or_fail,
+    _say,
+    _say_err,
+)
+from service.crypto import CredentialDecryptError
+from service.master_key import MasterKeyMissingError, is_master_key_available
+from service.secret_store import (
+    mask_secret,
+    make_windows_credential_target,
+    write_secret,
+)
+from util.logging_config import get_skill_logger
+from util.platforms import get_platform_spec, seed_platforms
+from util.profile_shortcut import create_profile_browser_shortcut
+from util.runtime_paths import get_default_profile_dir_for_web
+
+
+def create_web_account_record(
+    platform_input: str,
+    login_id: Optional[str],
+    login_id_type: str,
+    label: Optional[str],
+    tenant_id: Optional[str],
+    environment: str,
+    role: str,
+    provider_code: Optional[str],
+    url: Optional[str],
+    extra_json_str: Optional[str],
+    profile_dir_override: Optional[str],
+    *,
+    auth_strategy: Optional[str] = None,
+    session_persistent: Optional[int] = None,
+    device_fingerprint: Optional[str] = None,
+    platform_meta: Optional[PlatformCallerMeta] = None,
+    platform_key: Optional[str] = None,
+) -> Optional[dict]:
+    """Create a web/RPA account. On error prints JSON and returns None; on success returns payload (no stdout)."""
+    log = get_skill_logger()
+    log.info("account_add_web_attempt platform=%s login_id_type=%s env=%s role=%s",
+             platform_input, login_id_type, environment, role)
+
+    key = platform_key or _resolve_or_auto_register(platform_input, platform_meta)
+    if not key:
+        return None
+
+    init_db()
+    now = int(time.time())
+    conn = get_conn()
+    try:
+        seed_platforms(conn)
+        platform_spec = get_platform_spec(key, conn=conn)
+    finally:
+        conn.close()
+
+    safe_label = (label or "").strip() or f"{platform_spec.get('display_name', key)} {environment} {role}"
+    extra = {}
+    if extra_json_str:
+        try:
+            extra = json.loads(extra_json_str)
+        except json.JSONDecodeError:
+            _say(_err_json("ERROR:CLI_BAD_ARGS", "extra_json 不是合法的 JSON 字符串。"))
+            return None
+
+    if profile_dir_override:
+        resolved_profile_dir = os.path.abspath(profile_dir_override)
+    else:
+        resolved_profile_dir = get_default_profile_dir_for_web(
+            platform_key=key,
+            label=safe_label,
+            login_id=login_id,
+            domain=platform_spec.get("domain", "generic"),
+        )
+    os.makedirs(resolved_profile_dir, exist_ok=True)
+
+    resolved_url = (url or "").strip() or platform_spec.get("default_url", "")
+    resolved_provider = provider_code or platform_spec.get("provider_code") or key
+    resolved_extra = json.dumps(extra, ensure_ascii=False)
+
+    conn = get_conn()
+    try:
+        seed_platforms(conn)
+        if auth_strategy is None:
+            resolved_auth = resolve_auth_strategy_for_platform(conn, key)
+        else:
+            if auth_strategy not in ALL_AUTH_STRATEGIES:
+                _say(_err_json(
+                    "ERR_AUTH_STRATEGY_NOT_SUPPORTED",
+                    f"不支持的 auth_strategy：{auth_strategy}",
+                ))
+                return None
+            resolved_auth = auth_strategy
+
+        if session_persistent is None:
+            sp = _derive_session_persistent(resolved_auth)
+        else:
+            if session_persistent not in (0, 1):
+                _say(_err_json(
+                    "ERR_INVALID_SESSION_PERSISTENT",
+                    "session_persistent 必须是 0 或 1。",
+                ))
+                return None
+            sp = session_persistent
+
+        if device_fingerprint is not None and resolved_auth != AUTH_STRATEGY_DEVICE_BOUND:
+            _say(_err_json(
+                "ERR_DEVICE_FINGERPRINT_NOT_APPLICABLE",
+                "device_fingerprint 仅在 auth_strategy=device_bound 时可设置。",
+            ))
+            return None
+
+        new_id = insert_account(
+            conn=conn,
+            platform_key=key,
+            account_label=safe_label,
+            login_id=login_id or None,
+            login_id_type=login_id_type,
+            tenant_id=tenant_id or None,
+            environment=environment,
+            role=role,
+            provider_code=resolved_provider,
+            profile_dir=resolved_profile_dir,
+            url=resolved_url,
+            extra_json=resolved_extra,
+            now=now,
+            auth_strategy=resolved_auth,
+            session_persistent=sp,
+            device_fingerprint=device_fingerprint,
+        )
+        conn.commit()
+    except Exception:
+        conn.rollback()
+        log.exception("account_add_web_failure")
+        _say(_err_json("ERROR:DB_ERROR", "Database insert failed."))
+        return None
+    finally:
+        conn.close()
+
+    shortcut_path = create_profile_browser_shortcut(resolved_profile_dir, safe_label, log)
+
+    log.info("account_add_web_success id=%s platform=%s profile_dir=%s", new_id, key, resolved_profile_dir)
+    ok_payload = {
+        "id": new_id,
+        "platform_key": key,
+        "account_label": safe_label,
+        "profile_dir": resolved_profile_dir,
+        "url": resolved_url,
+        "environment": environment,
+        "role": role,
+        "tenant_id": tenant_id or "",
+        "provider_code": resolved_provider,
+        "status": "active",
+        "session_status": "unknown",
+        "auth_strategy": resolved_auth,
+        "session_persistent": sp,
+        "device_fingerprint": device_fingerprint,
+    }
+    if shortcut_path:
+        ok_payload["profile_shortcut"] = shortcut_path
+    return ok_payload
+
+
+def cmd_account_add_web(
+    platform_input: str,
+    login_id: Optional[str],
+    login_id_type: str,
+    label: Optional[str],
+    tenant_id: Optional[str],
+    environment: str,
+    role: str,
+    provider_code: Optional[str],
+    url: Optional[str],
+    extra_json_str: Optional[str],
+    profile_dir_override: Optional[str],
+    *,
+    auth_strategy: Optional[str] = None,
+    session_persistent: Optional[int] = None,
+    device_fingerprint: Optional[str] = None,
+    platform_meta: Optional[PlatformCallerMeta] = None,
+) -> None:
+    """account add-web — create a web/RPA account record."""
+    ok_payload = create_web_account_record(
+        platform_input,
+        login_id,
+        login_id_type,
+        label,
+        tenant_id,
+        environment,
+        role,
+        provider_code,
+        url,
+        extra_json_str,
+        profile_dir_override,
+        auth_strategy=auth_strategy,
+        session_persistent=session_persistent,
+        device_fingerprint=device_fingerprint,
+        platform_meta=platform_meta,
+    )
+    if ok_payload:
+        _say(_ok_json(ok_payload))
+
+
+def cmd_account_add_secret(
+    platform_input: str,
+    credential_type: str,
+    label: Optional[str],
+    secret_storage: str,
+    secret_stdin: bool,
+    secret_ref: Optional[str],
+    account_id: Optional[int],
+    environment: Optional[str],
+    role: Optional[str],
+    extra_json_str: Optional[str],
+) -> None:
+    """account add-secret — create a credential record with masked secret."""
+    log = get_skill_logger()
+    log.info("account_add_secret_attempt platform=%s type=%s storage=%s",
+             platform_input, credential_type, secret_storage)
+
+    key = _resolve_or_fail(platform_input)
+    if not key:
+        return
+
+    storage_n = secret_storage.strip().lower()
+    if storage_n not in ("none", "env", "windows_credential", "local_encrypted"):
+        _say(_err_json("ERROR:SECRET_STORAGE_UNSUPPORTED",
+                       f"不支持的存储方式：{secret_storage}。支持：none / env / windows_credential / local_encrypted"))
+        return
+
+    if storage_n == "none" and credential_type not in ("browser_profile", "note"):
+        _say(_err_json("ERROR:SECRET_STORAGE_UNSUPPORTED",
+                       "storage=none 仅允许 credential_type=browser_profile 或 note。"))
+        return
+    if storage_n == "env" and not secret_ref:
+        _say(_err_json("ERROR:SECRET_REF_MISSING",
+                       "env 存储时必须提供 --secret-ref 环境变量名。"))
+        return
+
+    init_db()
+    conn = get_conn()
+    try:
+        seed_platforms(conn)
+        platform_spec = get_platform_spec(key, conn=conn)
+    finally:
+        conn.close()
+    now = int(time.time())
+    safe_label = (label or "").strip() or f"{platform_spec.get('display_name', key)} {credential_type}"
+
+    if storage_n == "local_encrypted":
+        if not is_master_key_available():
+            _say(_err_json(
+                "ERR_MASTER_KEY_MISSING",
+                "master key 未初始化。先跑 `account init-master-key`。",
+            ))
+            return
+        if not secret_stdin:
+            _say(_err_json(
+                "ERR_LOCAL_ENCRYPTED_REQUIRES_STDIN",
+                "local_encrypted 后端必须 --secret-stdin 输入密文，避免命令历史泄漏。",
+            ))
+            return
+        if credential_type not in (
+            "password",
+            "api_key",
+            "api_token",
+            "bearer_token",
+            "refresh_token",
+            "oauth_client",
+        ):
+            _say(_err_json(
+                "ERR_LOCAL_ENCRYPTED_TYPE_NOT_ALLOWED",
+                f"local_encrypted 不接受 credential_type={credential_type}（仅 secret 类）。",
+            ))
+            return
+        if secret_ref:
+            _say_err("[add-secret] WARNING: secret_ref ignored for local_encrypted (secret comes from stdin).")
+
+        extra: dict = {}
+        if extra_json_str:
+            try:
+                extra = json.loads(extra_json_str)
+            except json.JSONDecodeError:
+                extra = {}
+        resolved_env = environment or "production"
+        resolved_role = role or "api"
+        extra["environment"] = resolved_env
+        extra["role"] = resolved_role
+        resolved_extra = json.dumps(extra, ensure_ascii=False)
+        resolved_url = (platform_spec.get("default_url") or "").strip() or None
+        resolved_provider = platform_spec.get("provider_code") or key
+
+        plaintext = sys.stdin.readline().rstrip("\r\n")
+        if not plaintext:
+            _say(_err_json("ERR_LOCAL_ENCRYPTED_EMPTY_STDIN", "stdin 没读到密码内容。"))
+            return
+        secret_mask_out = mask_secret(plaintext)
+
+        conn = get_conn()
+        cred_id: Optional[int] = None
+        holder_id: Optional[int] = None
+        try:
+            seed_platforms(conn)
+            holder_id = account_id
+            if holder_id is not None:
+                acc = get_account_by_id(holder_id)
+                if not acc:
+                    _say(_err_json(
+                        "ERROR:ACCOUNT_NOT_FOUND",
+                        f"account_id={holder_id} 不存在。",
+                    ))
+                    return
+            if holder_id is None:
+                holder_id = _insert_secret_holder_account(
+                    conn,
+                    platform_key=key,
+                    account_label=safe_label,
+                    environment=resolved_env,
+                    role=resolved_role,
+                    provider_code=resolved_provider,
+                    url=resolved_url,
+                    now=now,
+                )
+            cred_id = insert_credential_encrypted(
+                conn,
+                account_id=holder_id,
+                platform_key=key,
+                credential_label=safe_label,
+                credential_type=credential_type,
+                plaintext=plaintext,
+                expires_at=None,
+                extra_json=resolved_extra,
+                now=now,
+            )
+            conn.commit()
+        except MasterKeyMissingError as e:
+            conn.rollback()
+            _say(_err_json("ERR_MASTER_KEY_MISSING", str(e)))
+            return
+        except CredentialDecryptError as e:
+            conn.rollback()
+            _say(_err_json("ERR_CREDENTIAL_DECRYPT_FAILED", str(e)))
+            return
+        except Exception:
+            conn.rollback()
+            log.exception("account_add_secret_failure")
+            _say(_err_json("ERROR:DB_ERROR", "Database insert failed."))
+            return
+        finally:
+            conn.close()
+
+        log.info(
+            "account_add_secret_encrypted_success cred_id=%s account_id=%s",
+            cred_id,
+            holder_id,
+        )
+        _say(_ok_json({
+            "credential_id": cred_id,
+            "account_id": holder_id,
+            "platform_key": key,
+            "credential_type": credential_type,
+            "secret_storage": "local_encrypted",
+            "secret_mask": secret_mask_out,
+        }))
+        return
+
+    if storage_n == "env":
+        secret_ref_value = secret_ref.strip()
+        secret_mask_value = mask_secret(f"env:{secret_ref_value}")
+        extra = {}
+        if extra_json_str:
+            try:
+                extra = json.loads(extra_json_str)
+            except json.JSONDecodeError:
+                extra = {}
+        resolved_env = environment or "production"
+        resolved_role = role or "api"
+        extra["environment"] = resolved_env
+        extra["role"] = resolved_role
+        extra_json_final = json.dumps(extra, ensure_ascii=False)
+
+        resolved_url = (platform_spec.get("default_url") or "").strip() or None
+        resolved_provider = platform_spec.get("provider_code") or key
+
+        conn = get_conn()
+        try:
+            seed_platforms(conn)
+            holder_id = account_id
+            if holder_id is None:
+                holder_id = _insert_secret_holder_account(
+                    conn,
+                    platform_key=key,
+                    account_label=safe_label,
+                    environment=resolved_env,
+                    role=resolved_role,
+                    provider_code=resolved_provider,
+                    url=resolved_url,
+                    now=now,
+                )
+            cred_id = insert_credential(
+                conn=conn,
+                account_id=holder_id,
+                platform_key=key,
+                credential_label=safe_label,
+                credential_type=credential_type,
+                secret_storage=storage_n,
+                secret_ref=secret_ref_value,
+                secret_mask=secret_mask_value,
+                expires_at=None,
+                extra_json=extra_json_final,
+                now=now,
+            )
+            conn.commit()
+        except Exception:
+            conn.rollback()
+            log.exception("account_add_secret_failure")
+            _say(_err_json("ERROR:DB_ERROR", "Database insert failed."))
+            return
+        finally:
+            conn.close()
+
+        log.info("account_add_secret_success id=%s platform=%s storage=env ref=%s",
+                 cred_id, key, secret_ref_value)
+        _say(_ok_json({
+            "account_id": holder_id,
+            "credential_id": cred_id,
+            "platform_key": key,
+            "credential_label": safe_label,
+            "credential_type": credential_type,
+            "secret_storage": storage_n,
+            "secret_ref": secret_ref_value,
+            "secret_mask": secret_mask_value,
+            "warning": "env 存储方式：请确保环境变量在运行时可用。",
+        }))
+        return
+
+    if storage_n == "windows_credential":
+        if not secret_stdin:
+            _say(_err_json("ERROR:CLI_BAD_ARGS",
+                           "windows_credential 需要 --secret-stdin 从 stdin 读取 secret。"))
+            return
+        secret_value = sys.stdin.readline().strip()
+        if not secret_value:
+            _say(_err_json("ERROR:CLI_BAD_ARGS", "stdin 中未读到 secret 值。"))
+            return
+
+        secret_mask_value = mask_secret(secret_value)
+        cred_label_for_target = safe_label
+        target = make_windows_credential_target(key, credential_type, cred_label_for_target)
+
+        try:
+            write_secret("windows_credential", target, secret_value)
+        except (OSError, ValueError) as e:
+            log.error("secret_write_failed storage=windows_credential error=%s", str(e))
+            _say(_err_json("ERROR:SECRET_WRITE_FAILED", f"写 Windows Credential Manager 失败：{e}"))
+            return
+
+        extra = {}
+        if extra_json_str:
+            try:
+                extra = json.loads(extra_json_str)
+            except json.JSONDecodeError:
+                extra = {}
+        resolved_env = environment or "production"
+        resolved_role = role or "api"
+        extra["environment"] = resolved_env
+        extra["role"] = resolved_role
+        extra_json_final = json.dumps(extra, ensure_ascii=False)
+
+        resolved_url = (platform_spec.get("default_url") or "").strip() or None
+        resolved_provider = platform_spec.get("provider_code") or key
+
+        conn = get_conn()
+        try:
+            seed_platforms(conn)
+            holder_id = account_id
+            if holder_id is None:
+                holder_id = _insert_secret_holder_account(
+                    conn,
+                    platform_key=key,
+                    account_label=safe_label,
+                    environment=resolved_env,
+                    role=resolved_role,
+                    provider_code=resolved_provider,
+                    url=resolved_url,
+                    now=now,
+                )
+            cred_id = insert_credential(
+                conn=conn,
+                account_id=holder_id,
+                platform_key=key,
+                credential_label=safe_label,
+                credential_type=credential_type,
+                secret_storage=storage_n,
+                secret_ref=target,
+                secret_mask=secret_mask_value,
+                expires_at=None,
+                extra_json=extra_json_final,
+                now=now,
+            )
+            conn.commit()
+        except Exception:
+            conn.rollback()
+            log.exception("account_add_secret_failure")
+            _say(_err_json("ERROR:DB_ERROR", "Database insert failed."))
+            return
+        finally:
+            conn.close()
+
+        log.info("account_add_secret_success id=%s platform=%s storage=windows_credential",
+                 cred_id, key)
+        secret_value = ""
+
+        _say(_ok_json({
+            "account_id": holder_id,
+            "credential_id": cred_id,
+            "platform_key": key,
+            "credential_label": safe_label,
+            "credential_type": credential_type,
+            "secret_storage": storage_n,
+            "secret_ref": target,
+            "secret_mask": secret_mask_value,
+        }))
+        return
+
+    conn = get_conn()
+    try:
+        seed_platforms(conn)
+        cred_id = insert_credential(
+            conn=conn,
+            account_id=account_id,
+            platform_key=key,
+            credential_label=safe_label,
+            credential_type=credential_type,
+            secret_storage=storage_n,
+            secret_ref=None,
+            secret_mask="",
+            expires_at=None,
+            extra_json=extra_json_str or "{}",
+            now=now,
+        )
+        conn.commit()
+    except Exception:
+        conn.rollback()
+        log.exception("account_add_secret_failure")
+        _say(_err_json("ERROR:DB_ERROR", "Database insert failed."))
+        return
+    finally:
+        conn.close()
+
+    log.info("account_add_secret_success id=%s platform=%s storage=none", cred_id, key)
+    _say(_ok_json({
+        "account_id": account_id,
+        "credential_id": cred_id,
+        "platform_key": key,
+        "credential_label": safe_label,
+        "credential_type": credential_type,
+        "secret_storage": storage_n,
+        "secret_ref": "",
+        "secret_mask": "",
+    }))

scripts/service/account_ensure_commands.py

@@ -0,0 +1,161 @@
+# -*- coding: utf-8 -*-
+"""account ensure-web — pick if present, otherwise add-web then pick."""
+from typing import Optional
+
+from db.accounts_repo import count_active_accounts
+from db.connection import get_conn, init_db
+from service._svc_common import PlatformCallerMeta, _err_json, _resolve_or_auto_register, _say
+from service.account_add_commands import create_web_account_record
+from service.account_query_commands import cmd_account_pick_web
+from util.logging_config import get_skill_logger
+from util.platforms import seed_platforms
+
+
+def cmd_account_ensure_web(
+    platform_input: str,
+    *,
+    login_id: Optional[str] = None,
+    login_id_type: str = "unknown",
+    label: Optional[str] = None,
+    tenant_id: Optional[str] = None,
+    environment: Optional[str] = None,
+    role: Optional[str] = None,
+    provider_code: Optional[str] = None,
+    url: Optional[str] = None,
+    extra_json_str: Optional[str] = None,
+    profile_dir_override: Optional[str] = None,
+    auth_strategy: Optional[str] = None,
+    session_persistent: Optional[int] = None,
+    device_fingerprint: Optional[str] = None,
+    do_lease: bool = False,
+    ttl_sec: int = 900,
+    holder: Optional[str] = None,
+    purpose: Optional[str] = None,
+    platform_meta: Optional[PlatformCallerMeta] = None,
+) -> None:
+    """Pick a web account; if none exist for filters, create one then pick.
+
+    Does NOT create a new account when matching accounts exist but are all leased.
+    Success stdout matches ``account pick-web`` (plus ``account_ensured`` when created).
+    """
+    log = get_skill_logger()
+    log.info(
+        "account_ensure_web_attempt platform=%s env=%s tenant=%s role=%s lease=%s",
+        platform_input,
+        environment,
+        tenant_id,
+        role,
+        do_lease,
+    )
+
+    key = _resolve_or_auto_register(platform_input, platform_meta)
+    if not key:
+        return
+
+    init_db()
+    conn = get_conn()
+    try:
+        seed_platforms(conn)
+    finally:
+        conn.close()
+
+    existing_count = count_active_accounts(
+        platform_key=key,
+        environment=environment,
+        tenant_id=tenant_id,
+        role=role,
+    )
+    created = False
+    if existing_count == 0:
+        create_env = (environment or "").strip() or "production"
+        create_role = (role or "").strip() or "default"
+        create_label = (label or "").strip() or None
+        if not create_label:
+            create_label = f"{key} 默认"
+
+        created_payload = create_web_account_record(
+            platform_input,
+            login_id,
+            login_id_type,
+            create_label,
+            tenant_id,
+            create_env,
+            create_role,
+            provider_code,
+            url,
+            extra_json_str,
+            profile_dir_override,
+            auth_strategy=auth_strategy,
+            session_persistent=session_persistent,
+            device_fingerprint=device_fingerprint,
+            platform_meta=platform_meta,
+            platform_key=key,
+        )
+        if not created_payload:
+            return
+        created = True
+        log.info(
+            "account_ensure_web_created id=%s platform=%s profile_dir=%s",
+            created_payload.get("id"),
+            key,
+            created_payload.get("profile_dir"),
+        )
+    else:
+        log.info(
+            "account_ensure_web_reuse platform=%s existing_active=%s",
+            key,
+            existing_count,
+        )
+
+    # Capture pick output so we can annotate / remap lease-busy errors.
+    import io
+    import json
+    import sys
+
+    buf = io.StringIO()
+    old_out = sys.stdout
+    sys.stdout = buf
+    try:
+        cmd_account_pick_web(
+            platform_input,
+            environment=environment,
+            tenant_id=tenant_id,
+            role=role,
+            do_lease=do_lease,
+            ttl_sec=ttl_sec,
+            holder=holder,
+            purpose=purpose,
+            platform_meta=platform_meta,
+        )
+    finally:
+        sys.stdout = old_out
+
+    raw = buf.getvalue().strip()
+    if not raw:
+        _say(_err_json("ERROR:NO_ACCOUNT", "ensure 后未能挑选到账号。"))
+        return
+
+    try:
+        payload = json.loads(raw)
+    except json.JSONDecodeError:
+        _say(raw)
+        return
+
+    if isinstance(payload, dict) and payload.get("success") is False:
+        err = (payload.get("error") or {}) if isinstance(payload.get("error"), dict) else {}
+        code = str(err.get("code") or "")
+        if code == "ERROR:NO_ACCOUNT" and existing_count > 0 and not created:
+            _say(_err_json(
+                "ERROR:LEASE_CONFLICT",
+                "该平台下已有账号，但均被其他任务占用。请稍后重试或释放租约；不会自动新建账号。",
+            ))
+            return
+        _say(raw)
+        return
+
+    if isinstance(payload, dict) and created:
+        payload["account_ensured"] = True
+        _say(json.dumps(payload, ensure_ascii=False))
+        return
+
+    _say(raw)

scripts/service/account_mark_commands.py

@@ -0,0 +1,51 @@
+# -*- coding: utf-8 -*-
+"""Account status mark CLI commands."""
+from db.accounts_repo import (
+    get_account_by_id,
+    update_account_error,
+    update_account_last_used,
+    update_account_session_status,
+)
+from service._svc_common import _err_json, _ok_json, _say
+from util.logging_config import get_skill_logger
+
+
+def cmd_account_mark_session(account_id: int, session_status: str) -> None:
+    """account mark-session <id> --session-status <status>"""
+    log = get_skill_logger()
+    log.info("account_mark_session id=%s status=%s", account_id, session_status)
+    valid_statuses = ("unknown", "likely_valid", "needs_login", "expired")
+    if session_status not in valid_statuses:
+        _say(_err_json("ERROR:CLI_BAD_ARGS",
+                       f"session_status 必须为 {valid_statuses} 之一。"))
+        return
+    acc = get_account_by_id(account_id)
+    if not acc:
+        _say(_err_json("ERROR:ACCOUNT_NOT_FOUND", f"账号 id={account_id} 不存在。"))
+        return
+    update_account_session_status(account_id, session_status)
+    _say(_ok_json({"id": account_id, "session_status": session_status}))
+
+
+def cmd_account_mark_error(account_id: int, error_code: str, error_message: str) -> None:
+    """account mark-error <id> --code <code> --message <message>"""
+    log = get_skill_logger()
+    log.info("account_mark_error id=%s code=%s", account_id, error_code)
+    acc = get_account_by_id(account_id)
+    if not acc:
+        _say(_err_json("ERROR:ACCOUNT_NOT_FOUND", f"账号 id={account_id} 不存在。"))
+        return
+    update_account_error(account_id, error_code, error_message)
+    _say(_ok_json({"id": account_id, "error_code": error_code}))
+
+
+def cmd_account_mark_used(account_id: int) -> None:
+    """account mark-used <id>"""
+    log = get_skill_logger()
+    log.info("account_mark_used id=%s", account_id)
+    acc = get_account_by_id(account_id)
+    if not acc:
+        _say(_err_json("ERROR:ACCOUNT_NOT_FOUND", f"账号 id={account_id} 不存在。"))
+        return
+    update_account_last_used(account_id)
+    _say(_ok_json({"id": account_id, "marked": "used"}))

scripts/service/account_query_commands.py

@@ -0,0 +1,325 @@
+# -*- coding: utf-8 -*-
+"""Account query and pick CLI commands."""
+import json
+import uuid
+from typing import Optional
+
+from db.accounts_repo import (
+    acquire_lease,
+    find_account_ids,
+    find_accounts,
+    find_credentials,
+    get_account_by_id,
+    get_active_lease_by_token,
+    update_account_last_used,
+)
+from db.connection import get_conn, init_db
+from db.credentials_repo import (
+    CredentialNotEncryptedError,
+    list_credentials_by_account,
+    read_credential_plaintext,
+)
+from service._svc_common import (
+    PlatformCallerMeta,
+    _err_json,
+    _resolve_or_auto_register,
+    _resolve_or_fail,
+    _say,
+    _say_err,
+)
+from service.crypto import CredentialDecryptError
+from service.master_key import MasterKeyMissingError
+from util.logging_config import get_skill_logger
+from util.platforms import seed_platforms
+from util.runtime_paths import _runtime_paths_debug_text
+
+
+def cmd_account_get(account_id, include_credentials: bool = False) -> None:
+    """Get a single account by id. Returns JSON."""
+    log = get_skill_logger()
+    log.info("cli_start subcommand=account_get id=%r", account_id)
+    init_db()
+    acc = get_account_by_id(account_id)
+    if not acc:
+        log.warning("account_get_not_found id=%r", account_id)
+        _say(f"ERROR:ACCOUNT_NOT_FOUND 账号 id={account_id} 不存在。")
+        _say_err(_runtime_paths_debug_text())
+        return
+    if include_credentials:
+        creds = find_credentials(
+            platform_key=acc["platform_key"],
+            limit=20,
+        )
+        linked_creds = [c for c in creds if c["account_id"] == acc["id"]]
+        if not linked_creds:
+            linked_creds = [c for c in creds if c["account_id"] is None]
+        acc["credentials"] = [
+            {
+                "id": c["id"],
+                "credential_label": c["credential_label"],
+                "credential_type": c["credential_type"],
+                "secret_storage": c["secret_storage"],
+                "secret_ref": c["secret_ref"],
+                "secret_mask": c["secret_mask"],
+                "status": c["status"],
+            }
+            for c in linked_creds
+        ]
+    _say(json.dumps(acc, ensure_ascii=False))
+
+
+def cmd_account_get_credential(
+    account_id: int,
+    *,
+    reveal: bool = False,
+    lease_token: Optional[str] = None,
+) -> None:
+    """account get-credential — metadata or plaintext when lease proves access."""
+    log = get_skill_logger()
+    log.info("cli_start subcommand=account_get_credential id=%s reveal=%s", account_id, reveal)
+
+    init_db()
+    acc = get_account_by_id(account_id)
+    if not acc:
+        log.warning("account_get_credential_not_found id=%s", account_id)
+        _say(_err_json("ERROR:ACCOUNT_NOT_FOUND", f"账号 id={account_id} 不存在。"))
+        return
+
+    conn = get_conn()
+    try:
+        creds_all = list_credentials_by_account(conn, account_id)
+        creds = [c for c in creds_all if (c.get("status") or "").strip().lower() == "active"]
+        if not creds:
+            _say(_err_json(
+                "ERR_CREDENTIAL_MISSING",
+                f"账号 id={account_id} 没有活跃凭据。",
+            ))
+            return
+        cred = creds[0]
+
+        base_out = {
+            "success": True,
+            "account_id": account_id,
+            "credential_id": cred["id"],
+            "credential_type": cred["credential_type"],
+            "secret_storage": cred["secret_storage"],
+            "secret_mask": cred["secret_mask"],
+        }
+
+        if not reveal:
+            _say(json.dumps(base_out, ensure_ascii=False))
+            return
+
+        tok = (lease_token or "").strip()
+        if not tok:
+            log.warning("account_get_credential_reveal_missing_token id=%s", account_id)
+            _say(_err_json(
+                "ERR_LEASE_INVALID",
+                "reveal 必须带 --lease-token。",
+            ))
+            return
+
+        lease = get_active_lease_by_token(conn, tok)
+        lease_prefix = tok[:8]
+        if lease is None:
+            log.warning(
+                "account_get_credential_reveal_bad_lease id=%s lease_prefix=%s",
+                account_id,
+                lease_prefix,
+            )
+            _say(_err_json(
+                "ERR_LEASE_INVALID",
+                "lease token 无效或已过期",
+            ))
+            return
+
+        if int(lease["account_id"]) != int(account_id):
+            log.warning(
+                "account_get_credential_reveal_lease_mismatch id=%s lease_account=%s lease_prefix=%s",
+                account_id,
+                lease["account_id"],
+                lease_prefix,
+            )
+            _say(_err_json(
+                "ERR_LEASE_INVALID",
+                "lease token 不属于该 account",
+            ))
+            return
+
+        try:
+            pt = read_credential_plaintext(conn, int(cred["id"]))
+        except MasterKeyMissingError as e:
+            log.warning("account_get_credential_master_missing id=%s", account_id)
+            _say(_err_json("ERR_MASTER_KEY_MISSING", str(e)))
+            return
+        except CredentialDecryptError as e:
+            log.warning(
+                "account_get_credential_decrypt_failed id=%s cred_id=%s lease_prefix=%s",
+                account_id,
+                cred["id"],
+                lease_prefix,
+            )
+            _say(_err_json("ERR_CREDENTIAL_DECRYPT_FAILED", str(e)))
+            return
+        except CredentialNotEncryptedError:
+            out = {**base_out, "plaintext": None, "note": "credential storage=none, no plaintext to reveal"}
+            log.info(
+                "account_get_credential_reveal_note_plain id=%s cred_id=%s lease_prefix=%s",
+                account_id,
+                cred["id"],
+                lease_prefix,
+            )
+            _say(json.dumps(out, ensure_ascii=False))
+            return
+
+        log.info(
+            "account_get_credential_reveal_success account_id=%s cred_id=%s lease_prefix=%s",
+            account_id,
+            cred["id"],
+            lease_prefix,
+        )
+        _say(json.dumps({**base_out, "plaintext": pt}, ensure_ascii=False))
+    finally:
+        conn.close()
+
+
+def cmd_get(account_id) -> None:
+    """Legacy: get <id> — same as account get <id>."""
+    cmd_account_get(account_id, include_credentials=False)
+
+
+def cmd_account_list(
+    platform_input: Optional[str] = None,
+    environment: Optional[str] = None,
+    tenant_id: Optional[str] = None,
+    role: Optional[str] = None,
+    limit: int = 200,
+) -> None:
+    """account list — output JSON array of accounts matching filters."""
+    log = get_skill_logger()
+    log.info("cli_start subcommand=account_list platform=%s env=%s tenant=%s role=%s",
+             platform_input, environment, tenant_id, role)
+    init_db()
+    key = None
+    if platform_input and platform_input not in ("all", "全部", ""):
+        key = _resolve_or_fail(platform_input)
+        if not key:
+            return
+
+    accounts = find_accounts(
+        platform_key=key,
+        environment=environment,
+        tenant_id=tenant_id,
+        role=role,
+        limit=limit,
+    )
+    _say(json.dumps(accounts, ensure_ascii=False))
+
+
+def cmd_list_json(platform_input: str, limit: int = 200) -> None:
+    """Legacy: list-json <platform|all> [--limit N]"""
+    log = get_skill_logger()
+    log.info("cli_start subcommand=list_json filter=%r limit=%s", platform_input, limit)
+    init_db()
+    raw = (platform_input or "all").strip()
+    if not raw or raw.lower() == "all" or raw == "全部":
+        key = None
+    else:
+        key = _resolve_or_fail(raw)
+        if not key:
+            return
+    lim = max(1, min(int(limit), 500))
+    accounts = find_accounts(platform_key=key, limit=lim)
+    _say(json.dumps(accounts, ensure_ascii=False))
+
+
+def cmd_account_pick_web(
+    platform_input: str,
+    environment: Optional[str] = None,
+    tenant_id: Optional[str] = None,
+    role: Optional[str] = None,
+    do_lease: bool = False,
+    ttl_sec: int = 900,
+    holder: Optional[str] = None,
+    purpose: Optional[str] = None,
+    platform_meta: Optional[PlatformCallerMeta] = None,
+) -> None:
+    """Pick a web/RPA account for use. Optionally acquire a lease."""
+    log = get_skill_logger()
+    log.info("account_pick_web_attempt platform=%s env=%s tenant=%s role=%s lease=%s",
+             platform_input, environment, tenant_id, role, do_lease)
+
+    key = _resolve_or_auto_register(platform_input, platform_meta)
+    if not key:
+        return
+
+    init_db()
+    conn = get_conn()
+    try:
+        seed_platforms(conn)
+    finally:
+        conn.close()
+
+    candidate_ids = find_account_ids(
+        platform_key=key,
+        environment=environment,
+        tenant_id=tenant_id,
+        role=role,
+    )
+    if not candidate_ids:
+        _say(_err_json("ERROR:NO_ACCOUNT",
+                       "没有符合条件的可用账号（status=active 且未被其他 lease 占用）。"))
+        return
+
+    picked_id = candidate_ids[0]
+    acc = get_account_by_id(picked_id)
+    if not acc:
+        _say(_err_json("ERROR:ACCOUNT_NOT_FOUND", "选中的账号突然不存在了。"))
+        return
+
+    update_account_last_used(picked_id)
+
+    result = {
+        "id": acc["id"],
+        "platform_key": acc["platform_key"],
+        "account_label": acc["account_label"],
+        "login_id": acc["login_id"],
+        "profile_dir": acc["profile_dir"],
+        "url": acc["url"],
+        "tenant_id": acc["tenant_id"],
+        "environment": acc["environment"],
+        "role": acc["role"],
+        "provider_code": acc["provider_code"],
+        "session_status": acc["session_status"],
+        "auth_strategy": acc["auth_strategy"],
+        "session_persistent": acc["session_persistent"],
+        "device_fingerprint": acc.get("device_fingerprint"),
+    }
+
+    lease_info = None
+    if do_lease:
+        lease_token = uuid.uuid4().hex[:32]
+        resolved_holder = holder or "unknown"
+        try:
+            lease_info = acquire_lease(
+                account_id=picked_id,
+                lease_token=lease_token,
+                holder=resolved_holder,
+                purpose=purpose,
+                ttl_sec=ttl_sec,
+            )
+            result["lease_token"] = lease_info["lease_token"]
+            result["lease_expires_at"] = lease_info["expires_at"]
+        except ValueError as e:
+            log.warning("account_pick_web_lease_conflict id=%s", picked_id)
+            _say(_err_json("ERROR:LEASE_CONFLICT", str(e)))
+            return
+
+    log.info("account_pick_web_success id=%s token_prefix=%s",
+             picked_id, lease_info["lease_token"][:8] if lease_info else "none")
+    _say(json.dumps(result, ensure_ascii=False))
+
+
+def cmd_pick_web(platform_input: str) -> None:
+    """Legacy: pick-web <platform> — same as account pick-web without lease."""
+    cmd_account_pick_web(platform_input, do_lease=False)

scripts/service/browser_service.py

@@ -33,13 +33,12 @@ def _win_find_exe(candidates):
     return None
 
 
-def resolve_chromium_channel():
+def resolve_chromium_executable():
     """
-    Playwright channel: 'chrome' | 'msedge' | None
-    Windows 优先 Chrome，其次 Edge；其它系统默认 chrome（由 Playwright 解析 PATH）。
+    Windows 上返回 chrome.exe 或 msedge.exe 的绝对路径；未找到或非 Windows 返回 None。
     """
     if sys.platform != "win32":
-        return "chrome"
+        return None
 
     pf = os.environ.get("ProgramFiles", r"C:\Program Files")
     pfx86 = os.environ.get("ProgramFiles(x86)", r"C:\Program Files (x86)")
@@ -53,7 +52,7 @@ def resolve_chromium_channel():
         ]
     )
     if chrome:
-        return "chrome"
+        return chrome
 
     edge = _win_find_exe(
         [
@@ -63,11 +62,27 @@ def resolve_chromium_channel():
         ]
     )
     if edge:
-        return "msedge"
+        return edge
 
     return None
 
 
+def resolve_chromium_channel():
+    """
+    Playwright channel: 'chrome' | 'msedge' | None
+    Windows 优先 Chrome，其次 Edge；其它系统默认 chrome（由 Playwright 解析 PATH）。
+    """
+    if sys.platform != "win32":
+        return "chrome"
+
+    exe = resolve_chromium_executable()
+    if not exe:
+        return None
+    if os.path.basename(exe).lower() == "msedge.exe":
+        return "msedge"
+    return "chrome"
+
+
 def _print_browser_install_hint():
     print("❌ 未检测到 Google Chrome 或 Microsoft Edge，请先安装：")
     print("   • Chrome: https://www.google.com/chrome/")

scripts/service/credential_commands.py

@@ -0,0 +1,121 @@
+# -*- coding: utf-8 -*-
+"""Credential pick and resolve CLI commands."""
+from typing import Optional
+
+from db.accounts_repo import find_credentials, get_credential_by_id, update_credential_last_used
+from db.connection import init_db
+from service._svc_common import (
+    _credential_ok_line,
+    _err_json,
+    _map_secret_read_error,
+    _resolve_or_fail,
+    _say,
+)
+from service.secret_store import read_secret
+from util.logging_config import get_skill_logger
+
+
+def cmd_credential_pick(
+    platform_input: str,
+    credential_type: Optional[str] = None,
+    environment: Optional[str] = None,
+    role: Optional[str] = None,
+    reveal: bool = False,
+) -> None:
+    """Pick a credential for a platform, optionally with reveal."""
+    log = get_skill_logger()
+    log.info("cli_start subcommand=credential_pick platform=%s type=%s env=%s role=%s reveal=%s",
+             platform_input, credential_type, environment, role, reveal)
+
+    key = _resolve_or_fail(platform_input)
+    if not key:
+        return
+
+    init_db()
+    creds = find_credentials(
+        platform_key=key,
+        credential_type=credential_type,
+        environment=environment,
+        role=role,
+        status="active",
+        limit=1,
+    )
+    if not creds:
+        _say(_err_json("ERROR:CREDENTIAL_NOT_FOUND",
+                       "没有符合条件的可用凭据。"))
+        return
+
+    cred = creds[0]
+    update_credential_last_used(cred["id"])
+
+    result = {
+        "id": cred["id"],
+        "platform_key": cred["platform_key"],
+        "credential_label": cred["credential_label"],
+        "credential_type": cred["credential_type"],
+        "secret_storage": cred["secret_storage"],
+        "secret_ref": cred["secret_ref"],
+        "secret_mask": cred["secret_mask"],
+        "status": cred["status"],
+    }
+
+    if reveal:
+        try:
+            secret_value = read_secret(cred["secret_storage"], cred["secret_ref"])
+            result["secret"] = secret_value
+            log.info(
+                "credential_pick_reveal_success id=%s storage=%s",
+                cred["id"],
+                cred["secret_storage"],
+            )
+        except (ValueError, OSError) as e:
+            code, msg = _map_secret_read_error(e)
+            log.error("credential_pick_reveal_failure id=%s error=%s", cred["id"], msg)
+            _say(_err_json(code, msg))
+            return
+    else:
+        log.info("credential_pick_success id=%s (masked)", cred["id"])
+
+    _say(_credential_ok_line(result))
+
+
+def cmd_credential_resolve(credential_id: int, reveal: bool = False) -> None:
+    """Resolve a credential by id."""
+    log = get_skill_logger()
+    log.info("cli_start subcommand=credential_resolve id=%s reveal=%s", credential_id, reveal)
+
+    init_db()
+    cred = get_credential_by_id(credential_id)
+    if not cred:
+        _say(_err_json("ERROR:CREDENTIAL_NOT_FOUND", f"凭据 id={credential_id} 不存在。"))
+        return
+    if cred["status"] != "active":
+        _say(_err_json("ERROR:CREDENTIAL_DISABLED", f"凭据 id={credential_id} 状态为 {cred['status']}，不可用。"))
+        return
+
+    result = {
+        "id": cred["id"],
+        "account_id": cred["account_id"],
+        "platform_key": cred["platform_key"],
+        "credential_label": cred["credential_label"],
+        "credential_type": cred["credential_type"],
+        "secret_storage": cred["secret_storage"],
+        "secret_ref": cred["secret_ref"],
+        "secret_mask": cred["secret_mask"],
+        "status": cred["status"],
+    }
+
+    if reveal:
+        try:
+            secret_value = read_secret(cred["secret_storage"], cred["secret_ref"])
+            result["secret"] = secret_value
+            log.info("credential_resolve_reveal_success id=%s", credential_id)
+        except (ValueError, OSError) as e:
+            code, msg = _map_secret_read_error(e)
+            log.error("credential_resolve_reveal_failure id=%s error=%s", credential_id, msg)
+            _say(_err_json(code, msg))
+            return
+    else:
+        log.info("credential_resolve_success id=%s (masked)", credential_id)
+
+    _say(_credential_ok_line(result))

scripts/service/lease_commands.py

@@ -0,0 +1,34 @@
+# -*- coding: utf-8 -*-
+"""Lease management CLI commands."""
+from db.accounts_repo import cleanup_expired_leases, list_active_leases, release_lease
+from service._svc_common import _err_json, _ok_json, _say
+from util.logging_config import get_skill_logger
+
+
+def cmd_lease_release(lease_token: str) -> None:
+    """lease release <token>"""
+    log = get_skill_logger()
+    log.info("cli_start subcommand=lease_release token_prefix=%s", lease_token[:8])
+    ok = release_lease(lease_token)
+    if ok:
+        _say(_ok_json({"lease_token": lease_token, "status": "released"}))
+    else:
+        _say(_err_json("ERROR:LEASE_NOT_FOUND", "未找到活跃的租约，或租约已释放/过期。"))
+
+
+def cmd_lease_list(active_only: bool = False) -> None:
+    """lease list [--active]"""
+    log = get_skill_logger()
+    log.info("cli_start subcommand=lease_list active_only=%s", active_only)
+    leases = list_active_leases()
+    if active_only:
+        pass
+    _say(_ok_json({"leases": leases}))
+
+
+def cmd_lease_cleanup() -> None:
+    """lease cleanup — mark expired leases as expired."""
+    log = get_skill_logger()
+    log.info("cli_start subcommand=lease_cleanup")
+    count = cleanup_expired_leases()
+    _say(_ok_json({"cleaned": count}))

scripts/service/legacy_commands.py

@@ -0,0 +1,128 @@
+# -*- coding: utf-8 -*-
+"""Legacy delete and human-readable list CLI commands."""
+from db.accounts_repo import get_account_by_id, find_accounts
+from db.connection import get_conn, init_db
+from service._svc_common import (
+    _remove_profile_dir,
+    _resolve_or_fail,
+    _say,
+    _say_err,
+)
+from util.logging_config import get_skill_logger
+from util.platforms import get_platform_spec
+from util.runtime_paths import _runtime_paths_debug_text
+
+
+def cmd_delete_by_id(account_id) -> None:
+    """delete id <id> — legacy"""
+    log = get_skill_logger()
+    log.info("delete_by_id id=%r", account_id)
+    acc = get_account_by_id(account_id)
+    if not acc:
+        _say(f"ERROR:ACCOUNT_NOT_FOUND 账号 id={account_id} 不存在。")
+        _say_err(_runtime_paths_debug_text())
+        return
+    profile_dir = acc.get("profile_dir", "")
+    conn = get_conn()
+    try:
+        cur = conn.cursor()
+        cur.execute("DELETE FROM accounts WHERE id = ?", (int(account_id),))
+        cur.execute("DELETE FROM credentials WHERE account_id = ?", (int(account_id),))
+        conn.commit()
+    finally:
+        conn.close()
+    _remove_profile_dir(profile_dir)
+    log.info("delete_by_id_done id=%s", account_id)
+    _say(f"✅ 已删除账号 ID {account_id}。")
+
+
+def cmd_delete_by_platform(platform_input: str) -> None:
+    """delete platform <platform> — legacy"""
+    log = get_skill_logger()
+    log.info("delete_by_platform platform=%r", platform_input)
+    key = _resolve_or_fail(platform_input)
+    if not key:
+        return
+    conn = get_conn()
+    try:
+        cur = conn.cursor()
+        cur.execute("SELECT id, profile_dir FROM accounts WHERE platform_key = ?", (key,))
+        rows = cur.fetchall()
+        if not rows:
+            _say("ERROR:NO_ACCOUNTS_FOUND 该平台下没有账号记录。")
+            return
+        for rid, pdir in rows:
+            _remove_profile_dir(pdir)
+        cur.execute("DELETE FROM accounts WHERE platform_key = ?", (key,))
+        cur.execute(
+            "DELETE FROM credentials WHERE platform_key = ? AND account_id IS NOT NULL",
+            (key,),
+        )
+        conn.commit()
+        log.info("delete_by_platform_done platform=%s count=%s", key, len(rows))
+        display = get_platform_spec(key, conn=conn).get("display_name", key)
+        _say(f"✅ 已删除 {display} 下共 {len(rows)} 条账号。")
+    finally:
+        conn.close()
+
+
+def cmd_delete_by_platform_phone(platform_input: str, phone: str) -> None:
+    """Legacy: delete by platform+phone — now uses login_id matching"""
+    log = get_skill_logger()
+    log.info("delete_by_platform_phone platform=%r", platform_input)
+    key = _resolve_or_fail(platform_input)
+    if not key:
+        return
+    phone_norm = "".join(c for c in phone if c.isdigit())
+    conn = get_conn()
+    try:
+        cur = conn.cursor()
+        cur.execute(
+            "SELECT id, profile_dir FROM accounts WHERE platform_key = ? AND login_id = ?",
+            (key, phone_norm),
+        )
+        row = cur.fetchone()
+        if not row:
+            _say("ERROR:ACCOUNT_NOT_FOUND 该平台下无此手机号。")
+            return
+        rid, pdir = row
+        _remove_profile_dir(pdir)
+        cur.execute("DELETE FROM accounts WHERE id = ?", (rid,))
+        cur.execute("DELETE FROM credentials WHERE account_id = ?", (rid,))
+        conn.commit()
+        log.info("delete_by_platform_phone_done id=%s", rid)
+        _say(f"✅ 已删除账号 ID {rid}。")
+    finally:
+        conn.close()
+
+
+def cmd_list(platform="all", limit: int = 10) -> None:
+    """Legacy: human-readable list output."""
+    log = get_skill_logger()
+    log.info("list filter=%r", platform)
+    init_db()
+    accounts = find_accounts(
+        platform_key=None if (not platform or platform in ("all", "全部")) else platform,
+        limit=limit,
+    )
+    if not accounts:
+        _say("ERROR:NO_ACCOUNTS_FOUND")
+        _say_err(_runtime_paths_debug_text())
+        return
+    log.info("list_ok rows=%s", len(accounts))
+    for i, acc in enumerate(accounts):
+        _say(f"id：{acc['id']}")
+        _say(f"label：{acc['account_label']}")
+        _say(f"platform：{acc['platform_key']}")
+        _say(f"login_id：{acc['login_id']}")
+        _say(f"env：{acc['environment']}  role：{acc['role']}")
+        _say(f"status：{acc['status']}  session：{acc['session_status']}")
+        _say(f"profile_dir：{acc['profile_dir']}")
+        _say(f"url：{acc['url']}")
+        _say(f"created_at：{acc['created_at']}")
+        _say(f"updated_at：{acc['updated_at']}")
+        if acc.get("last_error_code"):
+            _say(f"last_error：{acc['last_error_code']} {acc.get('last_error_message', '')}")
+        if i < len(accounts) - 1:
+            _say("_______________________________________")
+            _say("")

scripts/service/platform_commands.py

@@ -0,0 +1,101 @@
+# -*- coding: utf-8 -*-
+"""Platform management CLI commands."""
+import json
+from typing import Optional
+
+from db.accounts_repo import get_platform_from_db, list_platforms_from_db, upsert_platform
+from db.connection import get_conn, init_db
+from service._svc_common import _err_json, _ok_json, _resolve_or_fail, _say
+from util.logging_config import get_skill_logger
+from util.platforms import DEFAULT_CAPABILITIES_JSON, is_valid_platform_key_format, seed_platforms
+
+
+def cmd_platform_list(domain: Optional[str] = None) -> None:
+    """platform list [--domain logistics|llm|content]"""
+    log = get_skill_logger()
+    log.info("cli_start subcommand=platform_list domain=%s", domain)
+    init_db()
+    conn = get_conn()
+    try:
+        seed_platforms(conn)
+        platforms = list_platforms_from_db(conn, domain=domain)
+    finally:
+        conn.close()
+    _say(_ok_json({"platforms": platforms}))
+
+
+def cmd_platform_get(input_key: str) -> None:
+    """platform get <platform>"""
+    log = get_skill_logger()
+    log.info("cli_start subcommand=platform_get key=%s", input_key)
+    key = _resolve_or_fail(input_key)
+    if not key:
+        return
+    init_db()
+    conn = get_conn()
+    try:
+        plat = get_platform_from_db(conn, key)
+    finally:
+        conn.close()
+    if plat:
+        _say(_ok_json(plat))
+    else:
+        _say(_err_json(
+            "ERROR:PLATFORM_NOT_REGISTERED",
+            f"Platform '{key}' not found in DB.",
+        ))
+
+
+def cmd_platform_ensure(
+    key: str,
+    display_name: str,
+    domain: str = "generic",
+    url: str = "",
+    auth_strategy: Optional[str] = None,
+    aliases: Optional[str] = None,
+    capabilities: Optional[str] = None,
+) -> int:
+    """
+    幂等地注册或更新平台到 DB。
+    输出单行 JSON：{"ok": true, "platform_key": "xxx", "action": "created|updated"}
+    """
+    log = get_skill_logger()
+    key = (key or "").strip()
+    display_name = (display_name or key).strip()
+    if not key:
+        _say('ERROR:INVALID_ARGS platform ensure 需要 --key 参数')
+        return 1
+    if not is_valid_platform_key_format(key):
+        _say(_err_json(
+            "ERROR:INVALID_PLATFORM_KEY",
+            f"平台 key 格式非法：「{key}」。建议使用小写字母、数字、下划线或连字符。",
+        ))
+        return 1
+
+    aliases_json = aliases if aliases else json.dumps([key, display_name], ensure_ascii=False)
+    capabilities_json = capabilities if capabilities else DEFAULT_CAPABILITIES_JSON
+
+    init_db()
+    conn = get_conn()
+    try:
+        existed = bool(
+            conn.execute(
+                "SELECT 1 FROM platforms WHERE platform_key = ?", (key,)
+            ).fetchone()
+        )
+        upsert_platform(
+            conn,
+            key=key,
+            display_name=display_name,
+            domain=domain,
+            default_url=url,
+            aliases_json=aliases_json,
+            capabilities_json=capabilities_json,
+            default_auth_strategy=auth_strategy,
+        )
+    finally:
+        conn.close()
+    action = "updated" if existed else "created"
+    log.info("platform_ensure key=%s action=%s", key, action)
+    _say(json.dumps({"ok": True, "platform_key": key, "action": action}, ensure_ascii=False))
+    return 0

scripts/util/profile_shortcut.py

@@ -0,0 +1,84 @@
+# -*- coding: utf-8 -*-
+"""在 Profile 目录内创建浏览器快捷方式（Windows .lnk）。"""
+from __future__ import annotations
+
+import logging
+import os
+import re
+import subprocess
+import sys
+from typing import Optional
+
+from service.browser_service import resolve_chromium_executable
+
+_WIN_LNK_FORBIDDEN = re.compile(r'[<>:"/\\|?*\x00-\x1f]')
+
+
+def _lnk_safe_filename(name: str, fallback: str = "browser") -> str:
+    t = _WIN_LNK_FORBIDDEN.sub("_", (name or "").strip())
+    t = t.rstrip(" .")
+    return t or fallback
+
+
+def _ps_single_quote(value: str) -> str:
+    return "'" + value.replace("'", "''") + "'"
+
+
+def create_profile_browser_shortcut(
+    profile_dir: str,
+    account_label: str,
+    log: Optional[logging.Logger] = None,
+) -> Optional[str]:
+    """
+    在 profile_dir 内创建 {account_label}.lnk，目标为系统 Chrome/Edge + --user-data-dir。
+
+    非 Windows 或未安装 Chrome/Edge 时静默跳过，返回 None。
+    成功返回 .lnk 绝对路径。
+    """
+    if log is None:
+        log = logging.getLogger(__name__)
+
+    if sys.platform != "win32":
+        log.debug("profile_shortcut_skip platform=%s", sys.platform)
+        return None
+
+    browser_exe = resolve_chromium_executable()
+    if not browser_exe:
+        log.warning("profile_shortcut_skip reason=no_chromium")
+        return None
+
+    profile_abs = os.path.abspath(profile_dir)
+    os.makedirs(profile_abs, exist_ok=True)
+
+    lnk_name = f"{_lnk_safe_filename(account_label)}.lnk"
+    lnk_path = os.path.join(profile_abs, lnk_name)
+    arguments = f'--user-data-dir="{profile_abs}"'
+    working_dir = os.path.dirname(browser_exe)
+
+    ps = (
+        "$WshShell = New-Object -ComObject WScript.Shell; "
+        f"$s = $WshShell.CreateShortcut({_ps_single_quote(lnk_path)}); "
+        f"$s.TargetPath = {_ps_single_quote(browser_exe)}; "
+        f"$s.Arguments = {_ps_single_quote(arguments)}; "
+        f"$s.IconLocation = {_ps_single_quote(browser_exe + ',0')}; "
+        f"$s.WorkingDirectory = {_ps_single_quote(working_dir)}; "
+        "$s.Save()"
+    )
+
+    try:
+        subprocess.run(
+            ["powershell", "-NoProfile", "-NonInteractive", "-Command", ps],
+            check=True,
+            capture_output=True,
+            text=True,
+        )
+    except (OSError, subprocess.CalledProcessError) as exc:
+        log.warning("profile_shortcut_failed profile_dir=%s error=%s", profile_abs, exc)
+        return None
+
+    if not os.path.isfile(lnk_path):
+        log.warning("profile_shortcut_missing_after_create path=%s", lnk_path)
+        return None
+
+    log.info("profile_shortcut_created path=%s browser=%s", lnk_path, browser_exe)
+    return lnk_path

tests/test_ensure_web.py

@@ -0,0 +1,143 @@
+# -*- coding: utf-8 -*-
+"""Tests for account ensure-web (pick-or-create)."""
+from __future__ import annotations
+
+import io
+import json
+import sys
+
+import pytest
+
+
+def _capture(fn, *args, **kwargs):
+    buf = io.StringIO()
+    old = sys.stdout
+    sys.stdout = buf
+    try:
+        fn(*args, **kwargs)
+    finally:
+        sys.stdout = old
+    return buf.getvalue()
+
+
+class TestEnsureWeb:
+    def test_ensure_creates_when_empty(self, clean_db):
+        from service.account_service import cmd_account_ensure_web
+
+        raw = _capture(
+            cmd_account_ensure_web,
+            "maersk",
+            label="马士基默认",
+        )
+        result = json.loads(raw)
+        assert result.get("success") is not False
+        assert result["platform_key"] == "maersk"
+        assert result.get("profile_dir")
+        assert result.get("account_ensured") is True
+        assert result.get("id")
+
+    def test_ensure_reuses_existing_no_duplicate(self, clean_db):
+        from service.account_service import cmd_account_add_web, cmd_account_ensure_web
+        from db.accounts_repo import find_accounts
+
+        _capture(
+            cmd_account_add_web,
+            "maersk",
+            "a@test.com",
+            "email",
+            "已有",
+            None,
+            "production",
+            "default",
+            None,
+            None,
+            None,
+            None,
+        )
+        before = find_accounts(platform_key="maersk", status="active", limit=50)
+        assert len(before) == 1
+
+        raw = _capture(cmd_account_ensure_web, "maersk")
+        result = json.loads(raw)
+        assert result.get("account_ensured") is not True
+        assert result["id"] == before[0]["id"]
+
+        after = find_accounts(platform_key="maersk", status="active", limit=50)
+        assert len(after) == 1
+
+    def test_ensure_lease_busy_does_not_create(self, clean_db):
+        from db.accounts_repo import acquire_lease, find_account_ids, find_accounts
+        from service.account_service import cmd_account_add_web, cmd_account_ensure_web
+
+        _capture(
+            cmd_account_add_web,
+            "cma_cgm",
+            "b@cma.com",
+            "email",
+            "CMA",
+            None,
+            "production",
+            "default",
+            None,
+            None,
+            None,
+            None,
+        )
+        ids = find_account_ids("cma_cgm")
+        assert len(ids) == 1
+        acquire_lease(
+            account_id=ids[0],
+            lease_token="a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
+            holder="other",
+            purpose="busy",
+            ttl_sec=900,
+        )
+        assert find_account_ids("cma_cgm") == []
+
+        raw = _capture(cmd_account_ensure_web, "cma_cgm", do_lease=True, holder="me")
+        err = json.loads(raw)
+        assert err["success"] is False
+        assert err["error"]["code"] == "ERROR:LEASE_CONFLICT"
+
+        still = find_accounts(platform_key="cma_cgm", status="active", limit=50)
+        assert len(still) == 1
+
+    def test_pick_web_ensure_flag_cli(self, clean_db, fake_env):
+        """CLI account pick-web --ensure creates when empty."""
+        import os
+        import subprocess
+
+        scripts = os.path.join(
+            os.path.dirname(os.path.dirname(os.path.abspath(__file__))), "scripts"
+        )
+        env = {
+            **os.environ,
+            "PYTHONPATH": scripts,
+            "JIANGCHANG_DATA_ROOT": fake_env["data_root"],
+            "JIANGCHANG_USER_ID": fake_env["user_id"],
+        }
+        r = subprocess.run(
+            [
+                sys.executable,
+                "-m",
+                "cli.app",
+                "account",
+                "pick-web",
+                "--platform",
+                "maersk",
+                "--ensure",
+                "--label",
+                "cli-default",
+            ],
+            capture_output=True,
+            text=True,
+            env=env,
+            cwd=scripts,
+        )
+        assert r.returncode == 0, r.stderr + r.stdout
+        # last non-empty JSON line
+        lines = [ln for ln in r.stdout.splitlines() if ln.strip()]
+        result = json.loads(lines[-1])
+        assert result.get("platform_key") == "maersk"
+        assert result.get("account_ensured") is True
+        assert result.get("profile_dir")

tests/test_profile_shortcut.py

@@ -0,0 +1,75 @@
+# -*- coding: utf-8 -*-
+"""Profile 目录浏览器快捷方式测试。"""
+import os
+import sys
+
+import pytest
+
+from util.profile_shortcut import _lnk_safe_filename, create_profile_browser_shortcut
+
+
+class TestLnkSafeFilename:
+    def test_strips_forbidden_chars(self) -> None:
+        assert _lnk_safe_filename('小红书/测试:账号') == "小红书_测试_账号"
+
+    def test_empty_uses_fallback(self) -> None:
+        assert _lnk_safe_filename("   ") == "browser"
+
+
+class TestCreateProfileBrowserShortcut:
+    def test_skips_non_windows(self, tmp_path, monkeypatch) -> None:
+        monkeypatch.setattr("util.profile_shortcut.sys.platform", "linux")
+        out = create_profile_browser_shortcut(str(tmp_path), "demo")
+        assert out is None
+
+    def test_skips_when_no_browser(self, tmp_path, monkeypatch) -> None:
+        monkeypatch.setattr("util.profile_shortcut.sys.platform", "win32")
+        monkeypatch.setattr(
+            "util.profile_shortcut.resolve_chromium_executable",
+            lambda: None,
+        )
+        out = create_profile_browser_shortcut(str(tmp_path), "demo")
+        assert out is None
+
+    @pytest.mark.skipif(sys.platform != "win32", reason="Windows .lnk only")
+    def test_creates_lnk_on_windows(self, tmp_path, monkeypatch) -> None:
+        from service.browser_service import resolve_chromium_executable
+
+        browser_exe = resolve_chromium_executable()
+        if not browser_exe:
+            pytest.skip("no Chrome/Edge installed")
+
+        label = "ShortcutTest"
+        out = create_profile_browser_shortcut(str(tmp_path), label)
+        assert out is not None
+        assert os.path.isfile(out)
+        assert out.endswith(f"{label}.lnk")
+
+    @pytest.mark.skipif(sys.platform != "win32", reason="Windows .lnk only")
+    def test_add_web_creates_shortcut(self, clean_db, fake_env, monkeypatch) -> None:
+        from service.browser_service import resolve_chromium_executable
+        from service.account_service import cmd_account_add_web
+        from db.accounts_repo import find_accounts
+
+        if not resolve_chromium_executable():
+            pytest.skip("no Chrome/Edge installed")
+
+        label = "Maersk shortcut test"
+        cmd_account_add_web(
+            platform_input="maersk",
+            login_id="shortcut@test.com",
+            login_id_type="email",
+            label=label,
+            tenant_id="tenant-test",
+            environment="production",
+            role="booking",
+            provider_code=None,
+            url=None,
+            extra_json_str=None,
+            profile_dir_override=None,
+        )
+        accs = find_accounts(platform_key="maersk")
+        assert len(accs) == 1
+        profile_dir = accs[0]["profile_dir"]
+        lnk_path = os.path.join(profile_dir, f"{label}.lnk")
+        assert os.path.isfile(lnk_path), f"expected shortcut at {lnk_path}"

tests/test_usage.py

@@ -27,7 +27,9 @@ def test_usage_includes_all_account_subcommands():
         "export-credentials",
         "import-credentials",
         "add-web",
+        "ensure-web",
         "get-credential",
         "pick-web",
     ):
         assert cmd in usage, f"USAGE 缺少 {cmd}"
+    assert "--ensure" in usage