@genduo/desk 0.0.0-stage → 0.4.0

package/cli.py

@@ -0,0 +1,632 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""genduo-desk — 店铺 Mac 采集 CLI（npm: @genduo/desk）。
+
+主 UX（门店）：
+  genduo-desk login --shop 5RT2
+    交互写入 Agent token + R-Login 两组凭据到 Keychain，
+    可选验证 RMS 登录、注册心跳、安装 LaunchAgent + caffeinate 防休眠。
+
+超管侧（先备齐凭据 / 签发 token）：
+  genduo-desk admin checklist --shop 5RT2
+  genduo-desk admin set-rms --shop 5RT2
+  genduo-desk admin write-bootstrap --shop 5RT2   # token 从 stdin，600 文件
+
+不打印 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:
+    """门店首次授权：token + R-Login → Keychain，可选心跳 / RMS 校验 / LaunchAgent。"""
+    shop = _resolve_shop(a.shop)
+    base = _resolve_base(a.base)
+    print(f"店铺 {shop}  · 中心 {base}")
+    print("凭据只写入本机 Keychain，不会打印、不会上传到中心。")
+
+    # --- Agent token ---
+    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:
+        token = os.environ.get("DATAANALYST_AGENT_TOKEN", "").strip()
+        if not token:
+            _die("DATAANALYST_AGENT_TOKEN 为空")
+    elif a.keep_token and kc.has_generic(kc.AGENT_TOKEN_SERVICE):
+        print("保留现有 Keychain Agent token")
+    else:
+        print("请粘贴超管签发的 Agent token（da_…，输入时不回显）")
+        token = _prompt_secret("Agent token")
+
+    if token:
+        try:
+            kc.set_agent_token(token)
+        except ValueError as exc:
+            _die(str(exc))
+        print(f"✓ Agent token → Keychain service={kc.AGENT_TOKEN_SERVICE}")
+        # 尽快丢掉明文引用
+        token = None
+
+    # --- R-Login 两组 ---
+    present = kc.rms_creds_present(shop)
+    if a.keep_rms and present["rlogin"] and present["ai"]:
+        print(f"保留现有 Keychain RMS 凭据 "
+              f"({kc.rms_rlogin_service(shop)}, {kc.rms_ai_service(shop)})")
+    else:
+        print("R-Login 第一组（glogin ID / 密码）")
+        rlogin_id = _prompt("R-Login ID")
+        rlogin_pw = _prompt_secret("R-Login 密码")
+        print("Rakuten 会员第二组（SSO 邮箱 / 密码）")
+        sso_user = _prompt("SSO 邮箱 / 用户名")
+        sso_pw = _prompt_secret("SSO 密码")
+        kc.set_rms_creds(shop, rlogin_id=rlogin_id, rlogin_password=rlogin_pw,
+                         sso_user=sso_user, sso_password=sso_pw)
+        # 清引用
+        rlogin_pw = sso_pw = ""  # noqa: F841
+        print(f"✓ R-Login → {kc.rms_rlogin_service(shop)}")
+        print(f"✓ SSO     → {kc.rms_ai_service(shop)}")
+
+    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   # Agent + caffeinate LaunchAgent")
+    print(f"  {sys.argv[0]} prevent-sleep     # 仅装 caffeinate；pmset 需 sudo 另做")
+
+
+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"agent_token   {'有' if present['agent_token'] else '缺'}  ({kc.AGENT_TOKEN_SERVICE})")
+    print(f"rms_rlogin    {'有' if present['rlogin'] else '缺'}  ({kc.rms_rlogin_service(shop)})")
+    print(f"rms_ai        {'有' if present['ai'] else '缺'}  ({kc.rms_ai_service(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 '未运行'}  ({CAFFEINATE_BIN} {' '.join(CAFFEINATE_ARGS)})")
+    if present["agent_token"] and not a.offline:
+        try:
+            tok = kc.get_agent_token()
+            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} 开店清单 ========
+
+    目标 UX：超管先备齐本店全部凭据；门店只拿到本 CLI，运行
+      genduo-desk login --shop {shop}
+    完成登录授权（Keychain + 心跳），不必手写 LaunchAgent。
+
+    A. 中心签发 Agent token（只显示一次明文）
+       · Web：超管 → API Token
+           name    = {name}
+           scopes  = collect:view,collect:edit
+           shops   = {shop}
+           days    = 365（建议）
+       · 或 VPS：
+           cd /opt/dataanalyst && sudo -u postgres env \\
+             DATAANALYST_DSN=dbname=dataanalyst DATAANALYST_SCHEMA=prod \\
+             venv/bin/python -m app.tokens --env prod create \\
+             --name {name} --scopes collect:view,collect:edit \\
+             --shops {shop} --days 365
+       · 明文立刻交给门店（或写入一次性 bootstrap），不要进 git / 聊天记录。
+
+    B. 备齐 RMS 两组密码（中心不存；只给人/Keychain）
+       · 第一组 R-Login ID/密码  → Keychain {kc.rms_rlogin_service(shop)}
+       · 第二组 Rakuten SSO     → Keychain {kc.rms_ai_service(shop)}
+       · 超管可在本机预先写入：
+           genduo-desk admin set-rms --shop {shop}
+         或让门店在 login 时自己输入。
+
+    C. 交给门店的材料
+       1. 本仓库 tools/collector-agent/（或 npm 包 @genduo/desk（命令 genduo-desk））
+       2. 店号 {shop}
+       3. Agent token（口头 / 密封通道 / bootstrap 文件）
+       4.（可选）R-Login 两组，若尚未写入该 Mac Keychain
+
+    D. 门店执行
+           python3 tools/collector-agent/cli.py login --shop {shop} --verify-rms --install-service
+         或：
+           genduo-desk admin write-bootstrap --shop {shop} --out /tmp/{shop}.boot.json
+           # 门店：
+           genduo-desk login --shop {shop} --bootstrap /tmp/{shop}.boot.json \\
+             --consume-bootstrap --verify-rms --install-service
+
+    E. 防休眠（install-service 默认会装 caffeinate）
+       · 用户级：LaunchAgent jp.dataanalyst.caffeinate → caffeinate -dims
+         （login --install-service / install-service / prevent-sleep）
+       · 系统级需管理员（CLI 不静默 sudo）：
+           sudo pmset -a sleep 0 disksleep 0 displaysleep 0
+           sudo systemsetup -setrestartpowerfailure on
+
+    F. 验收
+           genduo-desk status
+           # 应见 caffeinate=已装 且 caffeinate_ps=运行中
+           # 中心 /sources 或 GET /api/agent/status 可见 {shop} online
+    """).strip())
+
+
+def cmd_admin_set_rms(a: argparse.Namespace) -> None:
+    """超管在本机（或店里 Mac）写入 RMS Keychain，不涉及 Agent token。"""
+    shop = _resolve_shop(a.shop)
+    print(f"为 {shop} 写入 RMS Keychain（不打印密码）")
+    rlogin_id = _prompt("R-Login ID")
+    rlogin_pw = _prompt_secret("R-Login 密码")
+    sso_user = _prompt("SSO 邮箱 / 用户名")
+    sso_pw = _prompt_secret("SSO 密码")
+    kc.set_rms_creds(shop, rlogin_id=rlogin_id, rlogin_password=rlogin_pw,
+                     sso_user=sso_user, sso_password=sso_pw)
+    print(f"✓ {kc.rms_rlogin_service(shop)}")
+    print(f"✓ {kc.rms_ai_service(shop)}")
+    if a.verify_rms:
+        _do_verify_rms(shop, headed=a.headed)
+
+
+def cmd_admin_write_bootstrap(a: argparse.Namespace) -> None:
+    """把超管刚签发的 token 写成 600 的一次性文件；不进仓库。"""
+    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()
+    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)
+    cmd = [sys.executable, str(script), "--shop", shop, "--from-keychain",
+           "--out", str(out)]
+    if headed:
+        cmd.append("--headed")
+    print("验证 RMS 登录（Playwright；登录阶段不截密码）…")
+    r = subprocess.run(cmd)
+    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)
+    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"
+            "  </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="门店登录授权：token + R-Login → Keychain")
+    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 读 token")
+    p.add_argument("--keep-token", action="store_true",
+                   help="Keychain 已有 token 则不覆盖")
+    p.add_argument("--keep-rms", action="store_true",
+                   help="Keychain 已有 RMS 凭据则不覆盖")
+    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="查看 Keychain / LaunchAgent / caffeinate / 心跳")
+    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="打印某店开店清单（含签发 token 命令）")
+    p.set_defaults(func=cmd_admin_checklist)
+
+    p = adm_sub.add_parser("set-rms", parents=[common],
+                           help="交互写入本店 RMS Keychain")
+    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 一次性文件给门店 login 用")
+    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()