@genduo/desk 0.0.0-stage → 0.5.0

package/cli.py

@@ -0,0 +1,667 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""genduo-desk — 店铺 Mac 采集 CLI（npm: @genduo/desk）。
+
+主 UX（门店）：
+  genduo-desk login --shop 5RT2
+    本机 Keychain 只需已有 JDY_MCP / 服务器URL；
+    Agent token 与 R-Login 两组从简道云密码表经 MCP 读取，
+    可选验证 RMS 登录、注册心跳、安装 LaunchAgent + caffeinate 防休眠。
+
+超管侧（先备齐简道云 Title + 签发 token 写入密码表）：
+  genduo-desk admin checklist --shop 5RT2
+  genduo-desk admin verify-secrets --shop 5RT2
+
+不打印 token / 密码；不向生产库签发新 token（签发走中心 Web 或
+`python -m app.tokens`，见 admin checklist）。
+"""
+from __future__ import annotations
+
+import argparse
+import getpass
+import json
+import os
+import subprocess
+import sys
+import textwrap
+from pathlib import Path
+
+HERE = Path(__file__).resolve().parent
+# 包安装位置 = 含 cli.py 的目录（npm global 下是 node_modules/@genduo/desk）。
+# monorepo 开发时 HERE 仍是 tools/collector-agent/；ROOT 仅作 vendored 缺失时的回退。
+ROOT = HERE.parent.parent  # dataanalyst/（仅 monorepo 布局下有意义）
+sys.path.insert(0, str(HERE))
+
+import api_client  # noqa: E402
+import keychain_util as kc  # noqa: E402
+import local_config as cfg  # noqa: E402
+
+PLIST_LABEL = "jp.dataanalyst.agent"
+PLIST_PATH = Path.home() / "Library" / "LaunchAgents" / f"{PLIST_LABEL}.plist"
+CAFFEINATE_LABEL = "jp.dataanalyst.caffeinate"
+CAFFEINATE_PATH = Path.home() / "Library" / "LaunchAgents" / f"{CAFFEINATE_LABEL}.plist"
+CAFFEINATE_BIN = "/usr/bin/caffeinate"
+# -d display  -i idle  -m disk  -s system(AC)：用户级即可，重启后随登录会话拉起
+CAFFEINATE_ARGS = ["-dims"]
+
+
+def _die(msg: str, code: int = 1) -> None:
+    print(msg, file=sys.stderr)
+    raise SystemExit(code)
+
+
+def _prompt(msg: str, *, default: str = "") -> str:
+    suffix = f" [{default}]" if default else ""
+    val = input(f"{msg}{suffix}: ").strip()
+    return val or default
+
+
+def _prompt_secret(msg: str) -> str:
+    val = getpass.getpass(f"{msg}: ")
+    if not val:
+        _die(f"已取消：{msg} 不能为空")
+    return val
+
+
+def _resolve_shop(explicit: str | None) -> str:
+    if explicit:
+        shop = explicit.upper()
+    else:
+        shop = (cfg.load().get("shop") or _prompt("店铺代码", default="5RT2")).upper()
+    if shop not in cfg.SHOPS:
+        _die(f"非法店铺: {shop}（允许: {', '.join(cfg.SHOPS)}）")
+    return shop
+
+
+def _resolve_base(explicit: str | None) -> str:
+    return (explicit or cfg.load().get("base") or cfg.DEFAULT_BASE).rstrip("/")
+
+
+# ---------------------------------------------------------------------------
+# shop commands
+# ---------------------------------------------------------------------------
+
+def cmd_login(a: argparse.Namespace) -> None:
+    """门店授权：Agent token → 环境（及可选写入 LaunchAgent）；不写 dataanalyst Keychain。"""
+    shop = _resolve_shop(a.shop)
+    base = _resolve_base(a.base)
+    print(f"店铺 {shop}  · 中心 {base}")
+    print("与销量计算系统一致：Keychain 仅 JDY_MCP（本机可无）；"
+          "不写 dataanalyst-agent-token / dataanalyst/rms/*。")
+
+    token: str | None = None
+    if a.bootstrap:
+        boot = Path(a.bootstrap).expanduser()
+        if not boot.is_file():
+            _die(f"找不到 bootstrap 文件: {boot}")
+        data = json.loads(boot.read_text(encoding="utf-8"))
+        if (data.get("shop") or "").upper() != shop:
+            _die(f"bootstrap.shop={data.get('shop')} 与 --shop {shop} 不一致")
+        token = (data.get("agent_token") or "").strip()
+        if not token:
+            _die("bootstrap 缺少 agent_token")
+        print(f"已从 bootstrap 读取 token（文件: {boot}）")
+        if a.consume_bootstrap:
+            try:
+                boot.unlink()
+                print("已删除 bootstrap 文件（一次性）")
+            except OSError as exc:
+                print(f"警告: 未能删除 bootstrap: {exc}", file=sys.stderr)
+    elif a.token_env or a.keep_token:
+        token = os.environ.get("DATAANALYST_AGENT_TOKEN", "").strip() or None
+        if a.token_env and not token:
+            _die("DATAANALYST_AGENT_TOKEN 为空")
+        if token:
+            print("使用环境变量 DATAANALYST_AGENT_TOKEN")
+    if token is None and not a.keep_token:
+        print("请粘贴超管签发的 Agent token（da_…，输入时不回显）")
+        token = _prompt_secret("Agent token")
+
+    if token:
+        if not token.startswith("da_"):
+            _die("Agent token 应以 da_ 开头")
+        os.environ["DATAANALYST_AGENT_TOKEN"] = token
+        print("✓ Agent token → 本进程环境 DATAANALYST_AGENT_TOKEN（不写 Keychain）")
+        token = None
+
+    # JDY_MCP：与销量系统相同；本机没有属正常，仅提示
+    if kc.has_generic(kc.JDY_MCP_SERVICE):
+        print(f"✓ JDY_MCP 钥匙串可见（或已设 JDY_MCP_URL）")
+        if not a.skip_secret_check:
+            try:
+                _ = kc.get_api_key()
+                _ = None
+                print(f"✓ JDY API Key ← 密码表 Title={kc.JDY_API_KEY_TITLE}")
+            except RuntimeError as exc:
+                print(f"警告: 未能经 MCP 读取 API Key: {exc}", file=sys.stderr)
+    else:
+        print("（本机无 JDY_MCP / JDY_MCP_URL — 开发机可如此；店机请维护钥匙串）")
+
+    # RMS：可选交互写入环境变量供本进程 verify-rms（不写 Keychain）
+    if a.verify_rms and not a.keep_rms:
+        present = kc.rms_creds_present(shop)
+        if not (present["rlogin"] and present["ai"]):
+            print("R-Login 第一组（写入本进程环境，不写 Keychain）")
+            p = kc.rms_env_prefix(shop)
+            os.environ[p + "LOGIN_ID"] = _prompt("R-Login ID")
+            os.environ[p + "PASSWORD"] = _prompt_secret("R-Login 密码")
+            print("Rakuten 会员第二组")
+            os.environ[p + "SHOP_USER"] = _prompt("SSO 邮箱 / 用户名")
+            os.environ[p + "SHOP_PASSWORD"] = _prompt_secret("SSO 密码")
+            print(f"✓ RMS 凭据 → 环境变量 {p}*")
+
+    path = cfg.save(shop, base)
+    print(f"✓ 本机配置 → {path}（无密钥）")
+
+    if not a.skip_heartbeat:
+        _do_heartbeat(shop, base)
+
+    if a.verify_rms:
+        _do_verify_rms(shop, headed=a.headed)
+
+    if a.install_service:
+        _do_install_service(
+            shop, base,
+            skip_caffeinate=getattr(a, "skip_caffeinate", False),
+        )
+
+    print()
+    print("login 完成。常用后续：")
+    print(f"  {sys.argv[0]} status")
+    print(f"  {sys.argv[0]} heartbeat")
+    print(f"  {sys.argv[0]} install-service")
+
+
+
+def cmd_status(a: argparse.Namespace) -> None:
+    conf = cfg.load()
+    shop = _resolve_shop(a.shop or conf.get("shop"))
+    base = _resolve_base(a.base or conf.get("base"))
+    present = kc.rms_creds_present(shop)
+    print(f"shop          {shop}")
+    print(f"base          {base}")
+    print(f"version       {cfg.VERSION}")
+    print(f"jdy_mcp       {'有' if present.get('mcp_url') else '无（可预期）'}  "
+          f"({kc.JDY_MCP_SERVICE}/{kc.JDY_MCP_ACCOUNT} 或 JDY_MCP_URL)")
+    print(f"agent_token   {'有' if present['agent_token'] else '缺'}  "
+          f"(env DATAANALYST_AGENT_TOKEN)")
+    print(f"rms_env       rlogin={'有' if present['rlogin'] else '缺'}  "
+          f"ai={'有' if present['ai'] else '缺'}  ({kc.rms_env_prefix(shop)}*)")
+    print(f"launchagent   {'已装' if PLIST_PATH.is_file() else '未装'}  ({PLIST_PATH})")
+    print(f"caffeinate    {'已装' if CAFFEINATE_PATH.is_file() else '未装'}  ({CAFFEINATE_PATH})")
+    caf_alive = _caffeinate_running()
+    print(f"caffeinate_ps {'运行中' if caf_alive else '未运行'}  "
+          f"({CAFFEINATE_BIN} {' '.join(CAFFEINATE_ARGS)})")
+    if present["agent_token"] and not a.offline:
+        try:
+            tok = kc.get_agent_token(shop)
+            hb = api_client.heartbeat(base, tok, shop, cfg.VERSION)
+            agent = (hb or {}).get("agent") or {}
+            print(f"heartbeat     ok  last_seen={agent.get('last_seen_at')}")
+        except Exception as exc:  # noqa: BLE001
+            print(f"heartbeat     失败: {exc}")
+
+
+
+def cmd_heartbeat(a: argparse.Namespace) -> None:
+    conf = cfg.load()
+    shop = _resolve_shop(a.shop or conf.get("shop"))
+    base = _resolve_base(a.base or conf.get("base"))
+    _do_heartbeat(shop, base, show_jobs=not a.no_jobs)
+
+
+def cmd_install_service(a: argparse.Namespace) -> None:
+    conf = cfg.load()
+    shop = _resolve_shop(a.shop or conf.get("shop"))
+    base = _resolve_base(a.base or conf.get("base"))
+    _do_install_service(shop, base, force=a.force,
+                        skip_caffeinate=getattr(a, "skip_caffeinate", False))
+
+
+def cmd_prevent_sleep(a: argparse.Namespace) -> None:
+    """只装 caffeinate LaunchAgent，并打印需 sudo 的 pmset 说明。"""
+    _do_install_caffeinate(force=a.force)
+    _print_pmset_hint()
+
+
+def cmd_uninstall_service(_a: argparse.Namespace) -> None:
+    _launchctl_unload(PLIST_LABEL, PLIST_PATH)
+    if PLIST_PATH.is_file():
+        PLIST_PATH.unlink()
+        print(f"已移除 {PLIST_PATH}")
+    else:
+        print("Agent LaunchAgent 未安装")
+    _launchctl_unload(CAFFEINATE_LABEL, CAFFEINATE_PATH)
+    if CAFFEINATE_PATH.is_file():
+        CAFFEINATE_PATH.unlink()
+        print(f"已移除 {CAFFEINATE_PATH}")
+    else:
+        print("caffeinate LaunchAgent 未安装")
+
+
+# ---------------------------------------------------------------------------
+# admin commands
+# ---------------------------------------------------------------------------
+
+def cmd_admin_checklist(a: argparse.Namespace) -> None:
+    shop = _resolve_shop(a.shop)
+    name = f"agent-{shop}"
+    print(textwrap.dedent(f"""
+    ======== 超管 · {shop} 开店清单 ========
+
+    凭据逻辑与「销量计算系统」一致：
+      · 店机 Keychain：仅 JDY_MCP / 服务器URL（开发机可无）
+      · 或环境变量 JDY_MCP_URL
+      · JDY API Key：MCP 密码表 Title={kc.JDY_API_KEY_TITLE}
+      · 不再使用 dataanalyst-agent-token / dataanalyst/rms/* Keychain
+
+    A. 中心签发 Agent token（只显示一次明文）
+       · Web / VPS python -m app.tokens …
+           name={name}  scopes=collect:view,collect:edit  shops={shop}
+       · 门店用环境变量 DATAANALYST_AGENT_TOKEN，或 login --bootstrap
+
+    B. RMS 两组
+       · 环境变量 {kc.rms_env_prefix(shop)}LOGIN_ID / PASSWORD / SHOP_USER / SHOP_PASSWORD
+       · 或 rms_browser_login --env-file
+       · login --verify-rms 时可交互写入「本进程环境」（不写 Keychain）
+
+    C. 店机 Keychain（用户维护；与销量系统相同）
+       · service=JDY_MCP  account=服务器URL
+       · 本开发机没有该条目是正常的
+
+    D. 门店执行
+           genduo-desk login --shop {shop} --verify-rms --install-service
+
+    E. 验收
+           genduo-desk status
+    """).strip())
+
+
+def cmd_admin_verify_secrets(a: argparse.Namespace) -> None:
+    """探测 JDY_MCP → get_api_key（与销量系统相同）；不打印 Key。"""
+    shop = _resolve_shop(a.shop)
+    print(f"校验 JDY MCP / API Key（shop={shop} 仅作上下文；不打印 secret）")
+    if not kc.has_generic(kc.JDY_MCP_SERVICE):
+        print("本机无 JDY_MCP / JDY_MCP_URL（开发机可预期；店机请维护）")
+        raise SystemExit(0)
+    try:
+        _ = kc.get_api_key()
+        _ = None
+        print(f"✓ API Key 可读  Title={kc.JDY_API_KEY_TITLE}")
+    except RuntimeError as exc:
+        _die(str(exc))
+    if a.verify_rms:
+        _do_verify_rms(shop, headed=a.headed)
+
+
+def cmd_admin_set_rms(a: argparse.Namespace) -> None:
+    print("admin set-rms 已废弃：不再写入 dataanalyst/rms/* Keychain。")
+    print(f"请设置环境变量 {kc.rms_env_prefix(_resolve_shop(a.shop))}* "
+          "或使用 --env-file。")
+    raise SystemExit(2)
+
+
+def cmd_admin_write_bootstrap(a: argparse.Namespace) -> None:
+    """把 token 写成 600 一次性文件；不进仓库、不写 Keychain。"""
+    shop = _resolve_shop(a.shop)
+    out = Path(a.out).expanduser() if a.out else Path(f"/tmp/dataanalyst-{shop}-bootstrap.json")
+    print("粘贴 Agent token（不回显）；将写入仅含 shop+token 的 600 文件")
+    token = _prompt_secret("Agent token")
+    if not token.startswith("da_"):
+        _die("Agent token 应以 da_ 开头")
+    payload = {
+        "shop": shop,
+        "agent_token": token,
+        "base": _resolve_base(a.base),
+        "note": "一次性；login --consume-bootstrap 后应删除。勿提交 git。",
+    }
+    out.parent.mkdir(parents=True, exist_ok=True)
+    out.write_text(json.dumps(payload, ensure_ascii=False, indent=2) + "\n",
+                   encoding="utf-8")
+    os.chmod(out, 0o600)
+    print(f"✓ bootstrap → {out} (mode 600)")
+    print(f"门店执行: genduo-desk login --shop {shop} "
+          f"--bootstrap {out} --consume-bootstrap")
+
+
+
+# ---------------------------------------------------------------------------
+# helpers
+# ---------------------------------------------------------------------------
+
+def _do_heartbeat(shop: str, base: str, *, show_jobs: bool = True) -> None:
+    try:
+        tok = kc.get_agent_token(shop)
+    except RuntimeError as exc:
+        _die(str(exc))
+    try:
+        hb = api_client.heartbeat(base, tok, shop, cfg.VERSION)
+    except api_client.ApiError as exc:
+        _die(f"heartbeat 失败: {exc}")
+    agent = (hb or {}).get("agent") or {}
+    print(f"✓ heartbeat ok  shop={shop}  last_seen={agent.get('last_seen_at')}")
+    if show_jobs:
+        try:
+            j = api_client.jobs(base, tok, shop, limit=5)
+            n = len((j or {}).get("jobs") or j or []) if isinstance(j, dict) else 0
+            print(f"  jobs queued/leased: {n}")
+        except api_client.ApiError as exc:
+            print(f"  jobs: {exc}")
+
+
+def _do_verify_rms(shop: str, *, headed: bool = False) -> None:
+    # 优先包内 vendored 副本（npm 安装后无 monorepo）；其次 monorepo tools/。
+    candidates = [
+        HERE / "rms_browser_login.py",
+        HERE / "vendor" / "rms_browser_login.py",
+        ROOT / "tools" / "rms_browser_login.py",
+    ]
+    script = next((p for p in candidates if p.is_file()), None)
+    if script is None:
+        _die("找不到 rms_browser_login.py（包内 vendored 或 monorepo tools/）")
+    out = HERE / "state" / f"{shop}.json"
+    out.parent.mkdir(parents=True, exist_ok=True)
+    # 把本进程 RMS_* 环境写成 600 临时 env-file（不进 Keychain、用后删）
+    try:
+        creds = kc.get_rms_creds(shop)
+    except RuntimeError as exc:
+        _die(str(exc))
+    pfx = kc.rms_env_prefix(shop)
+    env_path = HERE / "state" / f".{shop}.rms.env"
+    lines = [
+        f"{pfx}LOGIN_ID={creds['rlogin_id']}",
+        f"{pfx}PASSWORD={creds['rlogin_password']}",
+        f"{pfx}SHOP_USER={creds['sso_user']}",
+        f"{pfx}SHOP_PASSWORD={creds['sso_password']}",
+        "",
+    ]
+    env_path.write_text("\n".join(lines), encoding="utf-8")
+    os.chmod(env_path, 0o600)
+    # 清内存引用
+    creds = None  # noqa: F841
+    cmd = [sys.executable, str(script), "--shop", shop,
+           "--env-file", str(env_path), "--out", str(out)]
+    if headed:
+        cmd.append("--headed")
+    print("验证 RMS 登录（Playwright；登录阶段不截密码）…")
+    try:
+        r = subprocess.run(cmd)
+    finally:
+        try:
+            env_path.unlink()
+        except OSError:
+            pass
+    if r.returncode != 0:
+        _die("RMS 登录验证失败", r.returncode)
+    try:
+        os.chmod(out, 0o600)
+    except OSError:
+        pass
+    print(f"✓ RMS 会话 → {out}")
+
+
+def _caffeinate_running() -> bool:
+    r = subprocess.run(["pgrep", "-x", "caffeinate"], capture_output=True)
+    return r.returncode == 0
+
+
+def _launchctl_unload(label: str, plist_path: Path) -> None:
+    uid = os.getuid()
+    subprocess.run(["launchctl", "bootout", f"gui/{uid}/{label}"],
+                   capture_output=True)
+    subprocess.run(["launchctl", "unload", str(plist_path)],
+                   capture_output=True)
+
+
+def _launchctl_load(label: str, plist_path: Path) -> None:
+    uid = os.getuid()
+    _launchctl_unload(label, plist_path)
+    r = subprocess.run(["launchctl", "bootstrap", f"gui/{uid}", str(plist_path)],
+                       capture_output=True, text=True)
+    if r.returncode != 0:
+        r2 = subprocess.run(["launchctl", "load", str(plist_path)],
+                            capture_output=True, text=True)
+        if r2.returncode != 0:
+            _die(f"launchctl 失败 ({label}): {(r.stderr or r2.stderr or '')[:300]}")
+    subprocess.run(["launchctl", "kickstart", "-k", f"gui/{uid}/{label}"],
+                   capture_output=True)
+
+
+def _print_pmset_hint() -> None:
+    """系统级防休眠需 sudo；CLI 只提示，不静默执行。"""
+    print()
+    print("防休眠分层：")
+    print(f"  · 用户级（已由 CLI 安装）：LaunchAgent {CAFFEINATE_LABEL}")
+    print(f"    → {CAFFEINATE_BIN} {' '.join(CAFFEINATE_ARGS)}（登录会话内 KeepAlive）")
+    print("  · 系统级（需管理员，CLI 不会自动 sudo）：")
+    print("      sudo pmset -a sleep 0 disksleep 0 displaysleep 0")
+    print("      sudo systemsetup -setrestartpowerfailure on   # 断电恢复，可选")
+    print("    执行前请确认这是店铺常开机；笔记本合盖策略另议。")
+
+
+def _do_install_caffeinate(*, force: bool = False) -> None:
+    if not Path(CAFFEINATE_BIN).is_file():
+        _die(f"找不到 {CAFFEINATE_BIN}（非 macOS？）")
+    CAFFEINATE_PATH.parent.mkdir(parents=True, exist_ok=True)
+    logs = HERE / "logs"
+    logs.mkdir(parents=True, exist_ok=True)
+    if CAFFEINATE_PATH.is_file() and not force:
+        print(f"caffeinate LaunchAgent 已存在: {CAFFEINATE_PATH}（加 --force 覆盖）")
+        _launchctl_load(CAFFEINATE_LABEL, CAFFEINATE_PATH)
+        if _caffeinate_running():
+            print("✓ caffeinate 进程已在运行")
+        else:
+            print("警告: caffeinate LaunchAgent 已装但进程未见到，请查 Console",
+                  file=sys.stderr)
+        return
+
+    arg_lines = "\n".join(
+        f"    <string>{a}</string>" for a in CAFFEINATE_ARGS
+    )
+    plist = (
+        '<?xml version="1.0" encoding="UTF-8"?>\n'
+        '<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"\n'
+        '  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">\n'
+        '<plist version="1.0">\n'
+        "<dict>\n"
+        f"  <key>Label</key><string>{CAFFEINATE_LABEL}</string>\n"
+        "  <key>ProgramArguments</key>\n"
+        "  <array>\n"
+        f"    <string>{CAFFEINATE_BIN}</string>\n"
+        f"{arg_lines}\n"
+        "  </array>\n"
+        "  <key>RunAtLoad</key><true/>\n"
+        "  <key>KeepAlive</key><true/>\n"
+        f"  <key>StandardOutPath</key><string>{logs}/caffeinate.stdout.log</string>\n"
+        f"  <key>StandardErrorPath</key><string>{logs}/caffeinate.stderr.log</string>\n"
+        "</dict>\n"
+        "</plist>\n"
+    )
+    CAFFEINATE_PATH.write_text(plist, encoding="utf-8")
+    _launchctl_load(CAFFEINATE_LABEL, CAFFEINATE_PATH)
+    print(f"✓ caffeinate LaunchAgent → {CAFFEINATE_PATH}")
+    print(f"  program: {CAFFEINATE_BIN} {' '.join(CAFFEINATE_ARGS)}")
+    if _caffeinate_running():
+        print("✓ caffeinate 进程运行中（防 idle/磁盘/显示/系统休眠）")
+    else:
+        print("警告: LaunchAgent 已 load，但尚未见到 caffeinate 进程",
+              file=sys.stderr)
+
+
+def _pick_agent_python() -> str:
+    """优先 monorepo .venv（有 playwright），否则当前解释器。"""
+    venv_py = HERE.parents[1] / ".venv" / "bin" / "python"
+    if venv_py.is_file() and os.access(venv_py, os.X_OK):
+        return str(venv_py)
+    return sys.executable
+
+
+def _do_install_service(shop: str, base: str, *, force: bool = False,
+                        skip_caffeinate: bool = False) -> None:
+    """安装 Agent LaunchAgent。
+
+    依赖长驻 `run.py`（进程内 sleep 循环）。KeepAlive=崩溃重启，
+    **不是**短任务轮询——切勿把 run.py 改回「跑完即退」否则会狂刷心跳。
+    """
+    cfg.save(shop, base)
+    def _plist_esc(s: str) -> str:
+        return (s.replace("&", "&amp;").replace("<", "&lt;")
+                 .replace(">", "&gt;").replace('"', "&quot;"))
+    tok_env = (os.environ.get("DATAANALYST_AGENT_TOKEN") or "").strip()
+    tok_xml = (
+        f"    <key>DATAANALYST_AGENT_TOKEN</key><string>{_plist_esc(tok_env)}</string>\n"
+        if tok_env else ""
+    )
+    python = _pick_agent_python()
+    run_py = HERE / "run.py"
+    logs = HERE / "logs"
+    logs.mkdir(parents=True, exist_ok=True)
+    PLIST_PATH.parent.mkdir(parents=True, exist_ok=True)
+    if PLIST_PATH.is_file() and not force:
+        print(f"Agent LaunchAgent 已存在: {PLIST_PATH}（加 --force 覆盖）")
+    else:
+        # KeepAlive + 长驻 run.py；ThrottleInterval 仅限制崩溃重启频率
+        plist = (
+            '<?xml version="1.0" encoding="UTF-8"?>\n'
+            '<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"\n'
+            '  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">\n'
+            '<plist version="1.0">\n'
+            "<dict>\n"
+            f"  <key>Label</key><string>{PLIST_LABEL}</string>\n"
+            "  <key>ProgramArguments</key>\n"
+            "  <array>\n"
+            f"    <string>{python}</string>\n"
+            f"    <string>{run_py}</string>\n"
+            "  </array>\n"
+            "  <key>EnvironmentVariables</key>\n"
+            "  <dict>\n"
+            f"    <key>DATAANALYST_SHOP</key><string>{shop}</string>\n"
+            f"    <key>DATAANALYST_BASE</key><string>{base}</string>\n"
+            f"{tok_xml}"
+            "  </dict>\n"
+            "  <key>RunAtLoad</key><true/>\n"
+            "  <key>KeepAlive</key><true/>\n"
+            "  <key>ThrottleInterval</key><integer>30</integer>\n"
+            f"  <key>WorkingDirectory</key><string>{HERE}</string>\n"
+            f"  <key>StandardOutPath</key><string>{logs}/stdout.log</string>\n"
+            f"  <key>StandardErrorPath</key><string>{logs}/stderr.log</string>\n"
+            "</dict>\n"
+            "</plist>\n"
+        )
+        PLIST_PATH.write_text(plist, encoding="utf-8")
+        _launchctl_load(PLIST_LABEL, PLIST_PATH)
+        print(f"✓ Agent LaunchAgent → {PLIST_PATH}")
+        print(f"  program: {python} {run_py}")
+        print("  说明: run.py 进程内 sleep 常驻；KeepAlive 仅崩溃重启（ThrottleInterval=30s）")
+
+    if skip_caffeinate:
+        print("已跳过 caffeinate（--skip-caffeinate）")
+    else:
+        _do_install_caffeinate(force=force)
+    _print_pmset_hint()
+
+
+def _link_hint() -> None:
+    """可选：提示如何把 cli 挂到 PATH。"""
+    pass
+
+
+# ---------------------------------------------------------------------------
+# argparse
+# ---------------------------------------------------------------------------
+
+def build_parser() -> argparse.ArgumentParser:
+    ap = argparse.ArgumentParser(
+        prog="genduo-desk",
+        description="店铺 Mac 采集 Agent CLI（login 授权 / 心跳 / LaunchAgent）",
+    )
+    common = argparse.ArgumentParser(add_help=False)
+    common.add_argument("--shop", help="店铺代码，如 5RT2")
+    common.add_argument("--base", help=f"中心 URL（默认 {cfg.DEFAULT_BASE}）")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+
+    p = sub.add_parser("login", parents=[common],
+                       help="门店登录授权：Agent token 环境 + 可选 RMS 校验")
+    p.add_argument("--bootstrap", help="紧急：一次性 JSON（含 agent_token）→ 仅本进程环境")
+    p.add_argument("--consume-bootstrap", action="store_true",
+                   help="login 成功后删除 bootstrap 文件")
+    p.add_argument("--token-env", action="store_true",
+                   help="要求已设置 DATAANALYST_AGENT_TOKEN（覆盖密码表）")
+    p.add_argument("--keep-token", action="store_true",
+                   help="沿用已有 DATAANALYST_AGENT_TOKEN，不交互粘贴")
+    p.add_argument("--keep-rms", action="store_true",
+                   help="沿用已有 RMS_<SHOP>_* 环境变量")
+    p.add_argument("--skip-secret-check", action="store_true",
+                   help="跳过密码表拉取校验（不推荐）")
+    p.add_argument("--skip-heartbeat", action="store_true")
+    p.add_argument("--verify-rms", action="store_true",
+                   help="用 Playwright 验证 R-Login 并写 state/<shop>.json")
+    p.add_argument("--headed", action="store_true", help="RMS 验证时显示浏览器")
+    p.add_argument("--install-service", action="store_true",
+                   help="login 末尾安装 Agent + caffeinate LaunchAgent")
+    p.add_argument("--skip-caffeinate", action="store_true",
+                   help="与 --install-service 合用时不装 caffeinate")
+    p.set_defaults(func=cmd_login)
+
+    p = sub.add_parser("status", parents=[common],
+                       help="查看 JDY_MCP / token 环境 / LaunchAgent / 心跳")
+    p.add_argument("--offline", action="store_true", help="不打中心心跳")
+    p.set_defaults(func=cmd_status)
+
+    p = sub.add_parser("heartbeat", parents=[common],
+                       help="向中心打一次心跳并拉任务")
+    p.add_argument("--no-jobs", action="store_true")
+    p.set_defaults(func=cmd_heartbeat)
+
+    p = sub.add_parser("install-service", parents=[common],
+                       help="安装 / 更新 Agent + caffeinate LaunchAgent")
+    p.add_argument("--force", action="store_true")
+    p.add_argument("--skip-caffeinate", action="store_true",
+                   help="只装 Agent，不装 caffeinate")
+    p.set_defaults(func=cmd_install_service)
+
+    p = sub.add_parser("prevent-sleep", parents=[common],
+                       help="安装 caffeinate LaunchAgent，并提示 pmset（需 sudo）")
+    p.add_argument("--force", action="store_true")
+    p.set_defaults(func=cmd_prevent_sleep)
+
+    p = sub.add_parser("uninstall-service", parents=[common],
+                       help="移除 Agent 与 caffeinate LaunchAgent")
+    p.set_defaults(func=cmd_uninstall_service)
+
+    adm = sub.add_parser("admin", help="超管：清单 / 校验密码表 / 紧急 bootstrap")
+    adm_sub = adm.add_subparsers(dest="admin_cmd", required=True)
+
+    p = adm_sub.add_parser("checklist", parents=[common],
+                           help="打印某店开店清单（与销量计算系统凭据说明）")
+    p.set_defaults(func=cmd_admin_checklist)
+
+    p = adm_sub.add_parser("verify-secrets", parents=[common],
+                           help="探测 JDY_MCP → API Key（与销量系统相同；不打印）")
+    p.add_argument("--verify-rms", action="store_true")
+    p.add_argument("--headed", action="store_true")
+    p.set_defaults(func=cmd_admin_verify_secrets)
+
+    p = adm_sub.add_parser("set-rms", parents=[common],
+                           help="已废弃：等同 verify-secrets")
+    p.add_argument("--verify-rms", action="store_true")
+    p.add_argument("--headed", action="store_true")
+    p.set_defaults(func=cmd_admin_set_rms)
+
+    p = adm_sub.add_parser("write-bootstrap", parents=[common],
+                           help="紧急：把 token 写成 600 文件（正式请写简道云）")
+    p.add_argument("--out", help="输出路径（默认 /tmp/dataanalyst-<SHOP>-bootstrap.json）")
+    p.set_defaults(func=cmd_admin_write_bootstrap)
+
+    return ap
+
+
+def main(argv: list[str] | None = None) -> None:
+    ap = build_parser()
+    args = ap.parse_args(argv)
+    # 顶层 --shop/--base 渗入子命令 namespace
+    args.func(args)
+
+
+if __name__ == "__main__":
+    main()