@hupan56/wlkj 2.7.12 → 3.1.2

package/templates/qoder/scripts/{setup_lanhu.py → deployment/setup/setup_lanhu.py}

@@ -1,963 +1,979 @@
-#!/usr/bin/env python3
-# -*- coding: utf-8 -*-
-"""
-setup_lanhu.py - 蓝湖 MCP 引导器 (幂等)
-
-把第三方 dsphper/lanhu-mcp 引导成本机可用: clone + venv 依赖 + playwright + cookie + mcp.json 注册。
-
-蓝湖 MCP 与我们自己的 kg_mcp_server.py 不同:
-  - 它是 HTTP server (http://localhost:8000/mcp), 需要独立常驻启动
-    (不像 kg_mcp_server.py 被 QoderWork 通过 command/args 自动拉起)
-  - cookie (LANHU_COOKIE) 在它的 .env 里, 必须用户登录 lanhuapp.com 后
-    从浏览器 DevTools 复制 (AI 拿不到)
-  - QoderWork 的 mcp.json 用 url 字段注册 (Streamable HTTP), 不是 command/args
-
-被谁调用:
-  - setup.py Step 4.5: 主初始化流程
-  - install_qoderwork.py: 技能安装时同步注册 mcp.json
-  - 用户手动: python .qoder/scripts/setup_lanhu.py [--check|--uninstall]
-
-用法:
-  python .qoder/scripts/setup_lanhu.py             # 引导 + 注册 (幂等)
-  python .qoder/scripts/setup_lanhu.py --check     # 只体检不改动
-  python .qoder/scripts/setup_lanhu.py --uninstall # 删 external/lanhu-mcp/ + mcp.json 条目
-  python .qoder/scripts/setup_lanhu.py --skip-install  # 只注册 mcp.json, 不 clone/装依赖
-
-幂等: 已 clone 跳过 clone; venv+依赖装过跳过; cookie 有效跳过; mcp.json 有 lanhu 跳过。
-"""
-
-import argparse
-import json
-import os
-import shutil
-import socket
-import subprocess
-import sys
-from pathlib import Path
-
-try:
-    sys.stdout.reconfigure(encoding='utf-8', errors='replace')
-    sys.stderr.reconfigure(encoding='utf-8', errors='replace')
-except (AttributeError, TypeError, OSError):
-    pass
-
-THIS_DIR = Path(__file__).resolve().parent
-BASE = THIS_DIR.parent.parent  # repo root
-
-LANHU_REPO = 'https://github.com/dsphper/lanhu-mcp.git'
-EXTERNAL_DIR = BASE / 'external'
-LANHU_DIR = EXTERNAL_DIR / 'lanhu-mcp'
-LANHU_VENV = LANHU_DIR / '.venv'
-LANHU_SERVER_SCRIPT = LANHU_DIR / 'lanhu_mcp_server.py'
-COOKIE_PLACEHOLDER = 'PUT_YOUR_COOKIE_HERE'
-LANHU_PORT = 8000
-LANHU_MCP_PATH = '/mcp'
-
-# QoderWork mcp.json 位置
-if sys.platform == 'win32':
-    _HOME = Path(os.environ.get('USERPROFILE', str(Path.home())))
-else:
-    _HOME = Path.home()
-QODERWORK_MCP_FILE = _HOME / '.qoderwork' / 'mcp.json'
-
-
-def _current_developer():
-    """读 .qoder/.developer 确定当前用户。没有返回 None。"""
-    try:
-        sys.path.insert(0, str(THIS_DIR))
-        from common.paths import get_developer
-        return get_developer(BASE)
-    except Exception:
-        return None
-
-
-def lanhu_secrets_dir(developer=None):
-    """当前用户的私密信息目录: workspace/members/{dev}/.secrets/
-
-    按 .developer 隔离: 一台机器多人切换时, 各自的 cookie 互不覆盖。
-    跟 .signing_key / autotest-data.yaml 同一套隔离机制。
-    """
-    dev = developer or _current_developer() or 'default'
-    return BASE / 'workspace' / 'members' / dev / '.secrets'
-
-
-def lanhu_env_file(developer=None):
-    """当前用户的蓝湖 cookie 文件: workspace/members/{dev}/.secrets/lanhu.env"""
-    return lanhu_secrets_dir(developer) / 'lanhu.env'
-
-
-# ============================================================
-# 工具函数
-# ============================================================
-
-def ok(msg):
-    print(f'  [\u2713] {msg}')  # ✓
-
-
-def warn(msg):
-    print(f'  [!] {msg}')
-
-
-def fail(msg):
-    print(f'  [\u2717] {msg}', file=sys.stderr)
-
-
-def ask(prompt, default='y'):
-    """交互式 yes/no, 默认 default。非交互环境返回 default。"""
-    if not sys.stdin.isatty():
-        return default.lower() in ('y', 'yes')
-    try:
-        ans = input(f'{prompt} [{default}] ').strip().lower() or default
-        return ans in ('y', 'yes')
-    except (EOFError, KeyboardInterrupt):
-        return default.lower() in ('y', 'yes')
-
-
-def run(cmd, **kwargs):
-    """跑子进程, 返回 CompletedProcess。encoding 容错。"""
-    kwargs.setdefault('capture_output', True)
-    kwargs.setdefault('text', True)
-    kwargs.setdefault('encoding', 'utf-8')
-    kwargs.setdefault('errors', 'replace')
-    return subprocess.run(cmd, **kwargs)
-
-
-def _venv_python(venv: Path) -> Path:
-    """venv 内的 python 可执行路径 (跨平台)。"""
-    if sys.platform == 'win32':
-        return venv / 'Scripts' / 'python.exe'
-    return venv / 'bin' / 'python'
-
-
-def _venv_pip(venv: Path) -> list:
-    """venv 内的 pip 调用命令 (用 python -m pip, 更稳)。"""
-    return [str(_venv_python(venv)), '-m', 'pip']
-
-
-# lanhu-mcp 的 fastmcp 依赖需要 Python >= 3.10。
-# 不能盲用 sys.executable (本机可能是 3.9), 得找一个 3.10+ 的解释器建 venv。
-LANHU_MIN_PYTHON = (3, 10)
-
-
-def _python_version(exe):
-    """返回解释器的 (major, minor) 元组, 探测失败返回 None。"""
-    try:
-        r = run([exe, '-c', 'import sys; print(sys.version_info[:2])'])
-        if r.returncode == 0:
-            import ast
-            ver = ast.literal_eval(r.stdout.strip())
-            if isinstance(ver, tuple) and len(ver) >= 2:
-                return (ver[0], ver[1])
-    except Exception:
-        pass
-    return None
-
-
-def find_python_310():
-    """找一个 Python >= 3.10 的解释器路径, 优先级:
-      1. sys.executable (如果本身就 >= 3.10, 直接用, 最省事)
-      2. Windows py launcher: py -3.10 / -3.11 / -3.12 / -3.13
-      3. 常见命令: python3.10/3.11/3.12, python3
-      4. 兜底返回 sys.executable (让 pip 报错给用户看真原因)
-    """
-    # 1. 当前解释器够新
-    if sys.version_info[:2] >= LANHU_MIN_PYTHON:
-        return sys.executable
-
-    # 2. Windows py launcher
-    if sys.platform == 'win32':
-        for v in ('3.13', '3.12', '3.11', '3.10'):
-            launcher = 'py' if shutil.which('py') else ('py.exe' if shutil.which('py.exe') else None)
-            if not launcher:
-                break
-            r = run([launcher, f'-{v}', '-c', 'import sys; print(sys.executable)'])
-            if r.returncode == 0 and r.stdout.strip():
-                exe = r.stdout.strip().strip('"')
-                ver = _python_version(exe)
-                if ver and ver >= LANHU_MIN_PYTHON:
-                    return exe
-
-    # 3. 常见命令名 (跨平台)
-    for cand in ('python3.13', 'python3.12', 'python3.11', 'python3.10',
-                 'python3', 'python'):
-        path = shutil.which(cand)
-        if path:
-            ver = _python_version(path)
-            if ver and ver >= LANHU_MIN_PYTHON:
-                return path
-
-    # 4. 兜底
-    return sys.executable
-
-
-# ============================================================
-# Step 1: clone / update lanhu-mcp
-# ============================================================
-
-def ensure_clone(dry=False, interactive=True):
-    """clone lanhu-mcp 到 external/lanhu-mcp/, 已存在则 git pull 更新。
-
-    返回 (status, path): status in ('cloned', 'updated', 'ok', 'failed', 'would', 'absent')
-    """
-    print('\n--- 1. 蓝湖 MCP 源码 ---')
-    if not shutil.which('git'):
-        warn('git 未安装, 无法 clone lanhu-mcp (装 git 后重跑)')
-        return ('failed', None)
-
-    if not LANHU_DIR.is_dir():
-        if dry:
-            print(f'  [MISS] 未 clone: {LANHU_DIR}')
-            return ('would', None)
-        EXTERNAL_DIR.mkdir(parents=True, exist_ok=True)
-        print(f'  git clone {LANHU_REPO} -> {LANHU_DIR}')
-        r = run(['git', 'clone', '--depth', '1', LANHU_REPO, str(LANHU_DIR)])
-        if r.returncode != 0:
-            fail('clone 失败: ' + (r.stderr or '').strip()[:200])
-            return ('failed', None)
-        ok(f'已 clone: {LANHU_DIR}')
-        return ('cloned', LANHU_DIR)
-
-    # 已存在: 检查是否是有效 repo
-    if not (LANHU_DIR / '.git').is_dir():
-        warn(f'{LANHU_DIR} 存在但不是 git 仓库, 跳过更新 (手动处理)')
-        return ('ok', LANHU_DIR)
-
-    if dry:
-        ok(f'已存在: {LANHU_DIR}')
-        return ('ok', LANHU_DIR)
-
-    # git pull 更新 (best-effort, 失败不阻塞)
-    r = run(['git', '-C', str(LANHU_DIR), 'pull', '--ff-only'])
-    if r.returncode == 0:
-        ok(f'已更新: {LANHU_DIR}')
-        return ('updated', LANHU_DIR)
-    warn('git pull 失败 (本地可能有改动), 用现有版本继续: '
-         + (r.stderr or '').strip()[:120])
-    return ('ok', LANHU_DIR)
-
-
-# ============================================================
-# Step 2: venv + 依赖 + playwright chromium
-# ============================================================
-
-def ensure_deps(dry=False, _rebuilt=False):
-    """建隔离 venv, 装 requirements.txt + playwright chromium。
-
-    幂等: venv+依赖装过则跳过 (靠一个 marker 文件判断)。
-    _rebuilt: 内部防无限递归 (删旧 venv 重建只允许一次)。
-    """
-    print('\n--- 2. 蓝湖 MCP 依赖 ---')
-    if not LANHU_DIR.is_dir():
-        warn('lanhu-mcp 未 clone, 跳过依赖安装')
-        return 'absent'
-
-    marker = LANHU_DIR / '.deps-installed'
-    req_file = LANHU_DIR / 'requirements.txt'
-
-    # 已装过 (marker 在 + requirements 没变) → 跳过
-    if marker.is_file() and req_file.is_file():
-        try:
-            marker_mtime = marker.stat().st_mtime
-            req_mtime = req_file.stat().st_mtime
-            if marker_mtime > req_mtime:
-                ok(f'依赖已装 (venv: {LANHU_VENV})')
-                return 'ok'
-        except OSError:
-            pass
-
-    if dry:
-        print(f'  [MISS] 依赖未装: {LANHU_VENV}')
-        return 'would'
-
-    # 建 venv (用 3.10+ Python, fastmcp 要求)
-    base_python = find_python_310()
-    base_ver = _python_version(base_python)
-    if not LANHU_VENV.is_dir():
-        if base_ver and base_ver >= LANHU_MIN_PYTHON:
-            print(f'  建 venv (Python {base_ver[0]}.{base_ver[1]}): '
-                  f'"{base_python}" -m venv {LANHU_VENV}')
-        else:
-            # 找不到 3.10+, 仍尝试建 (pip 会报错, 但给用户明确指引)
-            warn(f'未找到 Python >= 3.10 (fastmcp 要求)。当前最佳: '
-                 f'{base_python} ({base_ver})')
-            print(f'  建 venv: "{base_python}" -m venv {LANHU_VENV}')
-            print('  ⚠ 预计 pip install 会失败 — 装 Python 3.10+ 后重跑')
-        r = run([base_python, '-m', 'venv', str(LANHU_VENV)])
-        if r.returncode != 0:
-            fail('venv 创建失败: ' + (r.stderr or '').strip()[:200])
-            return 'failed'
-    elif base_ver and base_ver < LANHU_MIN_PYTHON and not _rebuilt:
-        # venv 已存在但可能是旧 3.9 建的 (之前版本的 bug), 删了重建。
-        # _rebuilt 防无限递归: 若本机没有 3.10+, 删了重建还是 3.9, 不再删第二次。
-        venv_ver = _python_version(_venv_python(LANHU_VENV))
-        if venv_ver and venv_ver < LANHU_MIN_PYTHON:
-            warn(f'现有 venv 是 Python {venv_ver[0]}.{venv_ver[1]} (fastmcp 需 3.10+), '
-                 f'删了重建')
-            try:
-                shutil.rmtree(LANHU_VENV)
-            except OSError:
-                pass
-            return ensure_deps(dry=dry, _rebuilt=True)
-
-    py = _venv_python(LANHU_VENV)
-    if not py.is_file():
-        fail(f'venv python 不存在: {py}')
-        return 'failed'
-
-    # 升级 pip
-    print('  升级 pip...')
-    run(_venv_pip(LANHU_VENV) + ['install', '--upgrade', 'pip'])
-
-    # 装 requirements.txt
-    if req_file.is_file():
-        print(f'  pip install -r requirements.txt')
-        r = run(_venv_pip(LANHU_VENV) + ['install', '-r', str(req_file)])
-        if r.returncode != 0:
-            fail('pip install requirements 失败: ' + (r.stderr or '').strip()[:200])
-            return 'failed'
-        ok('依赖已装')
-    else:
-        warn('requirements.txt 不存在, 跳过 (lanhu-mcp 目录结构可能变了)')
-
-    # playwright install chromium (150-300MB, 一次性)
-    print('  playwright install chromium (一次性, 约 150-300MB)...')
-    r = run([str(py), '-m', 'playwright', 'install', 'chromium'])
-    if r.returncode == 0:
-        ok('chromium 已装')
-    else:
-        warn('playwright install chromium 失败 (可稍后手动跑: '
-             f'{py} -m playwright install chromium)')
-        warn('  原因: ' + (r.stderr or '').strip()[:120])
-        # 不阻塞: cookie/服务启动后 playwright 缺失会在用时才报错
-
-    # 写 marker
-    try:
-        marker.write_text('deps installed\n', encoding='utf-8')
-    except OSError:
-        pass
-    return 'ok'
-
-
-# ============================================================
-# Step 3: cookie (按开发者隔离, workspace/members/{dev}/.secrets/lanhu.env)
-# ============================================================
-# 为什么不放 external/lanhu-mcp/.env:
-#   1. cookie 是个人登录凭证, 不该进仓库代码区 (即使 gitignore)
-#   2. 同一台机器多人切换 .developer 时, 单一 .env 会互相覆盖
-#   3. 跟 .signing_key / autotest-data.yaml 同一套隔离机制, 一致
-# 蓝湖服务端怎么读到这个 cookie:
-#   lanhu_mcp_server.py 用 load_dotenv(override=False), 已有环境变量优先。
-#   所以启动时把 LANHU_COOKIE 作为环境变量注入即可 (见 start_lanhu_server)。
-
-def _read_env_cookie(developer=None):
-    """读当前用户 lanhu.env 里的 LANHU_COOKIE, 没有返回 None。"""
-    env_file = lanhu_env_file(developer)
-    if not env_file.is_file():
-        return None
-    try:
-        for line in env_file.read_text(encoding='utf-8', errors='replace').splitlines():
-            line = line.strip()
-            if line.startswith('LANHU_COOKIE') and '=' in line:
-                val = line.split('=', 1)[1].strip().strip('"').strip("'")
-                return val
-    except OSError:
-        pass
-    return None
-
-
-def _write_env_cookie(cookie, developer=None):
-    """把 LANHU_COOKIE 写进当前用户的 lanhu.env (保留其他行)。
-
-    文件: workspace/members/{dev}/.secrets/lanhu.env (已 gitignore)
-    """
-    env_file = lanhu_env_file(developer)
-    try:
-        env_file.parent.mkdir(parents=True, exist_ok=True)
-        lines = []
-        found = False
-        if env_file.is_file():
-            for line in env_file.read_text(encoding='utf-8', errors='replace').splitlines():
-                if line.strip().startswith('LANHU_COOKIE') and '=' in line:
-                    lines.append(f'LANHU_COOKIE="{cookie}"')
-                    found = True
-                else:
-                    lines.append(line)
-        if not found:
-            lines.append(f'LANHU_COOKIE="{cookie}"')
-        env_file.write_text('\n'.join(lines) + '\n', encoding='utf-8')
-        return True
-    except OSError as e:
-        fail(f'写 {env_file} 失败: {e}')
-        return False
-
-
-def ensure_cookie(dry=False):
-    """收 cookie 写 .env。已有真 cookie 跳过; 没有则交互式引导。
-
-    返回 status: 'ok' (有真 cookie) / 'placeholder' (占位) / 'would' / 'absent'
-    """
-    dev = _current_developer()
-    env_file = lanhu_env_file(dev)
-    print('\n--- 3. 蓝湖 Cookie ---')
-    if dev:
-        print(f'  当前开发者: {dev}')
-        print(f'  cookie 文件: {env_file} (按人隔离, 不进 git)')
-    cookie = _read_env_cookie(dev)
-    if cookie and cookie != COOKIE_PLACEHOLDER:
-        ok(f'蓝湖 cookie 已配置 ({env_file.name})')
-        return 'ok'
-
-    if dry:
-        if cookie == COOKIE_PLACEHOLDER:
-            print(f'  [WARN] {env_file.name} 里是占位 cookie, 需要换成真的')
-        else:
-            print(f'  [MISS] 没有 LANHU_COOKIE ({env_file})')
-        return 'would'
-
-    # 交互式引导
-    if sys.stdin.isatty():
-        print()
-        print('  蓝湖 cookie 获取步骤:')
-        print('    1. 浏览器打开 https://lanhuapp.com 并登录')
-        print('    2. 按 F12 打开开发者工具, 切到 Network 标签')
-        print('    3. 刷新页面 (F5), 点任意一个请求')
-        print('    4. Request Headers 里找 Cookie: 这一行, 复制【整行】')
-        print('       (或 Application → Cookies → lanhuapp.com, 把所有项拼成')
-        print('        name1=value1; name2=value2 格式)')
-        print('    ⚠ 必须【整行】, 不能只复制 user_token 一个!')
-        print('       实测: 只给 user_token 蓝湖 API 返回 418 (鉴权失败),')
-        print('       需要 user_token + session + 其他项的组合才认。')
-        print()
-        try:
-            cookie = input('  粘贴蓝湖 cookie (留空跳过, 之后编辑 lanhu.env): ').strip()
-        except (EOFError, KeyboardInterrupt):
-            cookie = ''
-        if cookie and len(cookie) > 20:
-            if _write_env_cookie(cookie, dev):
-                ok(f'蓝湖 cookie 已写入 {env_file}')
-                return 'ok'
-            return 'placeholder'
-        warn(f'未输入 cookie, 写入占位 (之后编辑 {env_file} 换成真的)')
-    else:
-        # 非交互环境 (AI 调用): 写占位
-        warn('非交互环境, 无法收 cookie, 写入占位')
-
-    if _write_env_cookie(COOKIE_PLACEHOLDER, dev):
-        print(f'       占位已写入: {env_file}')
-        print(f'       编辑该文件, 把 {COOKIE_PLACEHOLDER} 换成真 cookie')
-    return 'placeholder'
-
-
-# ============================================================
-# Step 4: mcp.json 注册 (url 模式)
-# ============================================================
-
-def lanhu_mcp_url(developer_name='Developer'):
-    """生成蓝湖 MCP 的 url (HTTP Streamable, role/name 作为 query)。"""
-    import urllib.parse
-    name = urllib.parse.quote(developer_name or 'Developer')
-    return f'http://localhost:{LANHU_PORT}{LANHU_MCP_PATH}?role=Developer&name={name}'
-
-
-def _detect_python_command():
-    """探测本机可用的 python 命令 (跨平台)。win: py -3 > python; mac: python3。
-    复用 install_qoderwork 的逻辑, 但本文件独立实现避免循环依赖。"""
-    for cand in (('py', ['-3']), ('python3', []), ('python', [])):
-        name, extra = cand
-        if not shutil.which(name):
-            continue
-        cmd = [name] + extra + ['--version']
-        try:
-            r = run(cmd)
-            if r.returncode == 0:
-                return ' '.join([name] + extra)
-        except (OSError, subprocess.SubprocessError):
-            continue
-    return 'python'
-
-
-def _lanhu_stdio_entry():
-    """构造 STDIO 模式的 mcp.json lanhu 条目 (launcher 模式, 不写死路径)。
-
-    用统一启动器 mcp_launcher.py: command=python命令名, args=[launcher, "lanhu"]。
-    launcher 运行时自定位仓库根 + 找 venv python + 读角色 cookie。
-    这样 mcp.json 不含任何写死的仓库路径/venv路径, 跨机器通用。
-    """
-    py_cmd = _detect_python_command()
-    # launcher 在 ~/.qoderwork/mcp_launcher.py (install 时拷)
-    launcher = str(_HOME / '.qoderwork' / 'mcp_launcher.py')
-    return {
-        'command': py_cmd,
-        'args': [launcher, 'lanhu'],
-    }
-
-
-def _is_stdio_entry(entry):
-    """判断 mcp.json 里 lanhu 条目是不是 launcher STDIO 格式 (args 含 mcp_launcher)。"""
-    if not isinstance(entry, dict):
-        return False
-    args = entry.get('args', [])
-    return 'command' in entry and any('mcp_launcher.py' in str(a) for a in args)
-
-
-def register_lanhu_mcp(developer_name='Developer', dry=False):
-    """在 ~/.qoderwork/mcp.json 注册蓝湖 MCP (STDIO 模式, QoderWork 自动开关)。
-
-    STDIO 模式: command 指向 wrapper, QoderWork 开自动拉起、关自动杀。
-    cookie 由 wrapper 运行时按角色读 .secrets, 不进 mcp.json (角色隔离)。
-
-    迁移: 旧的 url 格式 (HTTP) → 升级成 STDIO。
-    幂等: 已是 STDIO 格式 → 跳过。
-    返回: 'ok-existing' / 'added' / 'upgraded' / 'would-add'
-    """
-    if not QODERWORK_MCP_FILE.is_file():
-        if dry:
-            return 'would-add'
-        QODERWORK_MCP_FILE.parent.mkdir(parents=True, exist_ok=True)
-
-    existing = {}
-    if QODERWORK_MCP_FILE.is_file():
-        try:
-            existing = json.loads(QODERWORK_MCP_FILE.read_text(encoding='utf-8'))
-            if not isinstance(existing, dict):
-                existing = {}
-        except (json.JSONDecodeError, OSError):
-            existing = {}
-
-    servers = existing.get('mcpServers', {})
-    if not isinstance(servers, dict):
-        servers = {}
-
-    cur = servers.get('lanhu')
-    stdio_entry = _lanhu_stdio_entry()
-
-    if cur and _is_stdio_entry(cur):
-        # 已是 STDIO, 但 command/args 可能因换机器变了 (venv 路径), 校准
-        if cur.get('command') == stdio_entry['command'] and cur.get('args') == stdio_entry['args']:
-            return 'ok-existing'
-        # 路径漂移, 更新
-        if dry:
-            return 'would-add'
-        servers['lanhu'] = stdio_entry
-        existing['mcpServers'] = servers
-        QODERWORK_MCP_FILE.write_text(
-            json.dumps(existing, indent=2, ensure_ascii=False) + '\n',
-            encoding='utf-8')
-        return 'upgraded'
-
-    if dry:
-        return 'would-add'
-
-    # 新增或从 url(HTTP) 升级到 STDIO
-    was_http = bool(cur and 'url' in cur)
-    servers['lanhu'] = stdio_entry
-    existing['mcpServers'] = servers
-    QODERWORK_MCP_FILE.write_text(
-        json.dumps(existing, indent=2, ensure_ascii=False) + '\n',
-        encoding='utf-8')
-    return 'upgraded' if was_http else 'added'
-
-
-def unregister_lanhu_mcp():
-    """从 mcp.json 删 lanhu 条目 (best-effort)。"""
-    if not QODERWORK_MCP_FILE.is_file():
-        return False
-    try:
-        existing = json.loads(QODERWORK_MCP_FILE.read_text(encoding='utf-8'))
-        servers = existing.get('mcpServers', {})
-        if 'lanhu' in servers:
-            del servers['lanhu']
-            existing['mcpServers'] = servers
-            QODERWORK_MCP_FILE.write_text(
-                json.dumps(existing, indent=2, ensure_ascii=False) + '\n',
-                encoding='utf-8',
-            )
-            return True
-    except (json.JSONDecodeError, OSError):
-        pass
-    return False
-
-
-# ============================================================
-# 健康探测: 蓝湖 HTTP 服务是否在跑
-# ============================================================
-
-def is_lanhu_running():
-    """探测 localhost:8000 是否在监听 (蓝湖服务是否启动)。"""
-    try:
-        with socket.create_connection(('127.0.0.1', LANHU_PORT), timeout=1):
-            return True
-    except (OSError, socket.timeout):
-        return False
-
-
-# ============================================================
-# 打印启动指引
-# ============================================================
-
-def print_start_hint():
-    """STDIO 模式下, 蓝湖由 QoderWork 自动管, 这个 hint 主要提示怎么验证。"""
-    print('\n  蓝湖 MCP (STDIO 模式, QoderWork 自动开关):')
-    print('    开 QoderWork 自动起, 关自动停 — 无需手动 start')
-    print('  验证: 在 QoderWork 里 /wl-design-spec 录入 <蓝湖链接>, 能调通即正常')
-    print('  换角色: 改 .developer + 配新角色 cookie → 重启 QoderWork')
-    print('  调试/多客户端共享 (强制 HTTP): python .qoder/scripts/setup_lanhu.py start --http')
-
-
-# ============================================================
-# 启动蓝湖服务端 (读当前用户 cookie, 以环境变量注入)
-# ============================================================
-
-def start_lanhu_server(force_http=False):
-    """启动蓝湖 MCP 服务。
-
-    默认 (STDIO 模式): 不需要手动 start, QoderWork 自动管。本函数只提示。
-    force_http=True: 走旧 HTTP 模式 (前台常驻, 用于调试或多客户端共享)。
-    """
-    if not force_http:
-        print('=' * 56)
-        print('  蓝湖 MCP 服务启动')
-        print('=' * 56)
-        # 检测当前 mcp.json 是不是 STDIO
-        entry = None
-        if QODERWORK_MCP_FILE.is_file():
-            try:
-                entry = json.loads(QODERWORK_MCP_FILE.read_text(encoding='utf-8')).get('mcpServers', {}).get('lanhu')
-            except Exception:
-                pass
-        if _is_stdio_entry(entry) if entry else False:
-            ok('已是 STDIO 模式 — QoderWork 自动开关, 无需手动 start')
-            print('  开 QoderWork 自动拉起蓝湖 (wrapper 读当前角色 cookie), 关自动停')
-            print('  换角色: 改 .developer + 配新角色 cookie → 重启 QoderWork')
-            print('')
-            print('  要强制用 HTTP 模式 (调试/多客户端共享):')
-            print(f'    python .qoder/scripts/setup_lanhu.py start --http')
-            return 0
-        # 非 STDIO (旧 HTTP 或没注册), 提示升级
-        warn('当前不是 STDIO 模式, 手动 start 只支持 HTTP')
-        print('  建议升级 STDIO (QoderWork 自动开关): python .qoder/scripts/setup_lanhu.py')
-        print('  或强制 HTTP: python .qoder/scripts/setup_lanhu.py start --http')
-        return 1
-
-    # === HTTP 模式 (force_http=True, 降级/调试用) ===
-    print('=' * 56)
-    print('  启动蓝湖 MCP 服务端 (HTTP 模式, 降级/调试)')
-    print('=' * 56)
-
-    # 1. 源码 + venv 是否就绪
-    if not LANHU_SERVER_SCRIPT.is_file():
-        fail(f'蓝湖服务脚本不存在: {LANHU_SERVER_SCRIPT}')
-        print('  先跑: python .qoder/scripts/setup_lanhu.py')
-        return 1
-    py = _venv_python(LANHU_VENV)
-    if not py.is_file():
-        fail(f'venv python 不存在: {py}')
-        print('  先跑: python .qoder/scripts/setup_lanhu.py')
-        return 1
-
-    # 2. 当前用户 + cookie
-    dev = _current_developer()
-    env_file = lanhu_env_file(dev)
-    env_cookie = os.environ.get('LANHU_COOKIE', '').strip()
-    cookie_source = 'env' if env_cookie else 'file'
-    cookie = env_cookie or _read_env_cookie(dev)
-
-    print(f'  当前开发者: {dev or "(未初始化, 用 default)"}')
-    if cookie_source == 'env':
-        print(f'  cookie 来源: 环境变量 LANHU_COOKIE (临时, 不落盘)')
-    else:
-        print(f'  cookie 来源: {env_file} (主线, 落盘)')
-
-    if not cookie or cookie == COOKIE_PLACEHOLDER:
-        fail('cookie 未配置')
-        if cookie_source == 'env':
-            print('  环境变量 LANHU_COOKIE 是空的或占位')
-        else:
-            print(f'  编辑 {env_file}, 把 {COOKIE_PLACEHOLDER} 换成真 cookie')
-        print('  获取: lanhuapp.com 登录 → F12 → Network → Cookie 头复制')
-        return 1
-    print(f'  cookie: 已配置 (长度 {len(cookie)})')
-
-    # 3. 已在跑就别重复启
-    if is_lanhu_running():
-        warn(f'蓝湖服务已在跑 (localhost:{LANHU_PORT}), 不重复启动')
-        return 0
-
-    # 4. 以环境变量注入 cookie 启动 (前台常驻, Ctrl+C 退出)
-    print(f'\n  启动: {py} {LANHU_SERVER_SCRIPT}')
-    print(f'  HTTP: http://localhost:{LANHU_PORT}{LANHU_MCP_PATH}')
-    print('  (常驻前台, 用完 Ctrl+C 关闭。别关这个终端。)\n')
-    env = os.environ.copy()
-    env['LANHU_COOKIE'] = cookie
-    # 不捕获输出 —— 服务端日志直接打到当前终端, 用户能看到请求/报错
-    try:
-        return subprocess.call([str(py), str(LANHU_SERVER_SCRIPT)], env=env)
-    except OSError as e:
-        fail(f'启动失败: {e}')
-        return 1
-
-
-# ============================================================
-# 主流程
-# ============================================================
-
-def configure_lanhu(developer_name='Developer', dry=False, skip_install=False):
-    """完整引导: clone → 依赖 → cookie → mcp.json 注册。
-
-    返回 dict 报告各步状态。
-    """
-    report = {'clone': 'skipped', 'deps': 'skipped',
-              'cookie': 'skipped', 'mcp': 'skipped'}
-
-    if skip_install:
-        print('\n--- 蓝湖 MCP (--skip-install, 只注册 mcp.json) ---')
-    else:
-        print('\n' + '=' * 56)
-        print('  蓝湖 MCP 引导')
-        print('=' * 56)
-
-        # 1. clone
-        status, _ = ensure_clone(dry=dry)
-        report['clone'] = status
-        if status == 'failed':
-            print('\n蓝湖源码获取失败, 后续步骤跳过。')
-            return report
-
-        # 2. 依赖
-        report['deps'] = ensure_deps(dry=dry)
-
-    # 3. cookie (即使 skip_install 也引导, 因为 mcp.json 注册后需要 cookie 才能用)
-    if not skip_install:
-        report['cookie'] = ensure_cookie(dry=dry)
-
-    # 4. mcp.json 注册 (STDIO 模式, QoderWork 自动开关)
-    print('\n--- 4. 注册到 QoderWork mcp.json (STDIO 自动开关) ---')
-    status = register_lanhu_mcp(developer_name, dry=dry)
-    report['mcp'] = status
-    if status == 'ok-existing':
-        ok(f'蓝湖 MCP 已注册 (STDIO): {QODERWORK_MCP_FILE}')
-        print('       开 QoderWork 自动起, 关自动停, 无需手动 start')
-    elif status in ('added', 'upgraded'):
-        tag = '已写入' if status == 'added' else '已升级(HTTP→STDIO)'
-        ok(f'{tag} 蓝湖 MCP: {QODERWORK_MCP_FILE}')
-        print('       STDIO 模式: 开 QoderWork 自动起, 关自动停')
-        print(f'       command → wrapper → 读 {developer_name} 的 cookie 拉起 lanhu')
-    elif status == 'would-add':
-        print(f'  [MISS] 未注册, 安装时会写入 {QODERWORK_MCP_FILE}')
-
-    return report
-
-
-def print_check_report():
-    """--check 模式: 体检报告 (不改动)。"""
-    print('=' * 56)
-    print('  蓝湖 MCP 体检')
-    print('=' * 56)
-
-    # clone
-    print('\n--- 1. 源码 ---')
-    if LANHU_DIR.is_dir() and (LANHU_DIR / '.git').is_dir():
-        ok(f'已 clone: {LANHU_DIR}')
-        # 检查关键文件
-        server_file = LANHU_DIR / 'lanhu_mcp_server.py'
-        if server_file.is_file():
-            ok(f'入口文件在: {server_file}')
-        else:
-            warn(f'入口文件缺失: {server_file} (lanhu-mcp 版本结构可能变了)')
-    else:
-        print(f'  [MISS] 未 clone (跑 setup.py 或本脚本安装)')
-
-    # 依赖
-    print('\n--- 2. 依赖 ---')
-    if LANHU_VENV.is_dir() and _venv_python(LANHU_VENV).is_file():
-        marker = LANHU_DIR / '.deps-installed'
-        # 实测验证: 尝试导入 fastmcp (lanhu-mcp 的核心依赖, 缺它一定跑不起来)
-        # marker 只是快速跳过标记, 真相以能否导入为准
-        py = _venv_python(LANHU_VENV)
-        r = run([str(py), '-c', 'import fastmcp; print(fastmcp.__version__)'])
-        deps_importable = r.returncode == 0 and r.stdout.strip()
-        if deps_importable:
-            extra = f' (fastmcp {r.stdout.strip()})'
-            if marker.is_file():
-                ok(f'venv + 依赖已装: {LANHU_VENV}{extra}')
-            else:
-                ok(f'venv + 依赖已装 (marker 缺失但实测可导入): {LANHU_VENV}{extra}')
-                print(f'       (补写 marker 以便后续快速跳过)')
-                try:
-                    marker.write_text('deps verified by import\n', encoding='utf-8')
-                except OSError:
-                    pass
-        elif marker.is_file():
-            warn(f'marker 在但 fastmcp 导入失败, 依赖可能损坏: {LANHU_VENV}')
-            print(f'       重装: python .qoder/scripts/setup_lanhu.py')
-        else:
-            warn(f'venv 存在但依赖未装完 (fastmcp 不可导入): {LANHU_VENV}')
-            print(f'       重装: python .qoder/scripts/setup_lanhu.py')
-    else:
-        print(f'  [MISS] venv 未建 (跑 setup.py 或本脚本安装)')
-
-    # cookie (按开发者隔离)
-    print('\n--- 3. Cookie ---')
-    dev = _current_developer()
-    env_file = lanhu_env_file(dev)
-    if dev:
-        print(f'  当前开发者: {dev}')
-    cookie = _read_env_cookie(dev)
-    if cookie and cookie != COOKIE_PLACEHOLDER:
-        ok(f'蓝湖 cookie 已配置 ({env_file})')
-    elif cookie == COOKIE_PLACEHOLDER:
-        warn(f'占位 cookie ({COOKIE_PLACEHOLDER}), 需要换成真的')
-        print(f'       编辑: {env_file}')
-    else:
-        print(f'  [MISS] 没有 LANHU_COOKIE ({env_file})')
-
-    # mcp.json (STDIO 模式检测)
-    print('\n--- 4. QoderWork 注册 ---')
-    if QODERWORK_MCP_FILE.is_file():
-        try:
-            cfg = json.loads(QODERWORK_MCP_FILE.read_text(encoding='utf-8'))
-            servers = cfg.get('mcpServers', {})
-            entry = servers.get('lanhu')
-            if not entry:
-                print(f'  [MISS] mcp.json 没有 lanhu 条目')
-            elif _is_stdio_entry(entry):
-                launcher_ok = (_HOME / '.qoderwork' / 'mcp_launcher.py').is_file()
-                ok(f'已注册 (STDIO launcher, 自动开关): command={entry.get("command","?")}')
-                ok(f'  launcher 存在: {"✓" if launcher_ok else "✗ 缺 ~/.qoderwork/mcp_launcher.py (重跑 install_qoderwork)"}')
-                print('  开 QoderWork 自动起, 关自动停 (无需手动 start)')
-            elif 'command' in entry:
-                # 旧 STDIO (写死 venv 路径) 或其他 command 格式
-                warn(f'旧 STDIO 格式 (command 写死路径), 建议升级 launcher 模式')
-                print('  升级: python .qoder/scripts/install_qoderwork.py')
-            else:
-                warn(f'旧 HTTP 模式 (url={entry.get("url","?")[:50]}...), 需手动 start')
-                print('  升级 STDIO: python .qoder/scripts/setup_lanhu.py')
-        except (json.JSONDecodeError, OSError):
-            warn(f'mcp.json 解析失败: {QODERWORK_MCP_FILE}')
-    else:
-        print(f'  [MISS] mcp.json 不存在: {QODERWORK_MCP_FILE}')
-
-    # 服务状态 (STDIO 模式由 QoderWork 管, 不常驻端口; 这里只提示)
-    print('\n--- 5. 服务状态 ---')
-    entry = None
-    if QODERWORK_MCP_FILE.is_file():
-        try:
-            entry = json.loads(QODERWORK_MCP_FILE.read_text(encoding='utf-8')).get('mcpServers', {}).get('lanhu')
-        except Exception:
-            pass
-    if _is_stdio_entry(entry) if entry else False:
-        ok('STDIO 模式: QoderWork 启动时自动拉起 (不占常驻端口)')
-        print('  (要验证: 开 QoderWork 后 /wl-design-spec 录入 <蓝湖链接> 能调通即正常)')
-    elif is_lanhu_running():
-        ok(f'蓝湖服务在跑 (HTTP, localhost:{LANHU_PORT}) — 旧模式, 建议升级 STDIO')
-    else:
-        print('  STDIO 模式下服务由 QoderWork 按需拉起, 这里不显示常驻状态')
-
-
-def do_uninstall():
-    """删 external/lanhu-mcp/ + mcp.json lanhu 条目。"""
-    print('=' * 56)
-    print('  蓝湖 MCP 卸载')
-    print('=' * 56)
-
-    # 1. mcp.json 条目
-    print('\n--- 1. 移除 mcp.json 条目 ---')
-    if unregister_lanhu_mcp():
-        ok(f'已从 mcp.json 删除 lanhu 条目')
-    else:
-        print('  mcp.json 无 lanhu 条目 (无需删除)')
-
-    # 2. external/lanhu-mcp/
-    print('\n--- 2. 删除源码 ---')
-    if LANHU_DIR.is_dir():
-        if ask(f'删除 {LANHU_DIR}? (含 venv + chromium 缓存, 不可恢复)', 'n'):
-            try:
-                shutil.rmtree(LANHU_DIR)
-                ok(f'已删除: {LANHU_DIR}')
-            except OSError as e:
-                fail(f'删除失败: {e}')
-        else:
-            print('  跳过 (保留源码)')
-    else:
-        print(f'  源码目录不存在: {LANHU_DIR}')
-
-    # 3. 清理空的 external/
-    if EXTERNAL_DIR.is_dir():
-        try:
-            remaining = list(EXTERNAL_DIR.iterdir())
-            if not remaining:
-                EXTERNAL_DIR.rmdir()
-                ok(f'已删除空目录: {EXTERNAL_DIR}')
-        except OSError:
-            pass
-
-    print('\n✓ 蓝湖 MCP 卸载完成。')
-
-
-def main():
-    parser = argparse.ArgumentParser(
-        description='蓝湖 MCP 引导器: clone + 依赖 + cookie + mcp.json 注册',
-        formatter_class=argparse.RawDescriptionHelpFormatter,
-        epilog='''示例:
-  python .qoder/scripts/setup_lanhu.py             # 引导 + 注册 STDIO (幂等, 自动开关)
-  python .qoder/scripts/setup_lanhu.py --check     # 只体检
-  python .qoder/scripts/setup_lanhu.py start       # 提示 STDIO 状态 (默认无需手动)
-  python .qoder/scripts/setup_lanhu.py start --http # 强制 HTTP 模式 (调试/多客户端)
-  python .qoder/scripts/setup_lanhu.py --skip-install  # 只注册 mcp.json
-  python .qoder/scripts/setup_lanhu.py --uninstall # 卸载
-''')
-    parser.add_argument('command', nargs='?', default=None,
-                        help='子命令: start = 提示服务状态 (STDIO 自动, 加 --http 强制 HTTP)')
-    parser.add_argument('--check', action='store_true', help='只体检不改动')
-    parser.add_argument('--uninstall', action='store_true', help='卸载 (删源码 + mcp.json 条目)')
-    parser.add_argument('--skip-install', action='store_true',
-                        help='只注册 mcp.json, 不 clone/装依赖')
-    parser.add_argument('--http', action='store_true',
-                        help='start 时强制走 HTTP 模式 (调试/多客户端共享; 默认 STDIO 自动开关)')
-    parser.add_argument('--name', default='Developer', help='开发者名 (用于蓝湖 url 的 name 参数)')
-    args = parser.parse_args()
-
-    # 子命令: start (提示服务状态 / 强制 HTTP)
-    if args.command == 'start':
-        return start_lanhu_server(force_http=args.http)
-    if args.command and args.command not in (None,):
-        fail(f'未知子命令: {args.command}')
-        print('  可用: start [--http]')
-        return 1
-
-    if args.check:
-        print_check_report()
-        return 0
-
-    if args.uninstall:
-        do_uninstall()
-        return 0
-
-    report = configure_lanhu(
-        developer_name=args.name,
-        dry=False,
-        skip_install=args.skip_install,
-    )
-
-    # 汇总
-    print('\n' + '=' * 56)
-    print('  蓝湖 MCP 引导完成')
-    print('=' * 56)
-    print(f'  源码:   {report["clone"]}')
-    print(f'  依赖:   {report["deps"]}')
-    print(f'  Cookie: {report["cookie"]}')
-    print(f'  注册:   {report["mcp"]}')
-
-    if report['cookie'] == 'placeholder':
-        print(f'\n  ⚠ 下一步: 编辑 {lanhu_env_file()}, 把 {COOKIE_PLACEHOLDER} 换成真 cookie')
-
-    if report['mcp'] in ('added', 'ok-existing') and not is_lanhu_running():
-        print_start_hint()
-
-    print('\n  QoderWork 里用命令触发蓝湖 (非侵入式, 必须走命令):')
-    print('    /wl-design-spec 录入 <蓝湖链接>  → design-import 调 mcp__lanhu__* (命令内授权)')
-    return 0
-
-
-if __name__ == '__main__':
-    sys.exit(main())
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+# v3.0 路径自举: 引导到 common/bootstrap, 统一 sys.path 逻辑
+import os as _o, sys as _s
+_f = _o.path.abspath(__file__)
+for _ in range(10):
+    _f = _o.path.dirname(_f)
+    _cp = _o.path.join(_f, 'foundation')
+    if _o.path.isfile(_o.path.join(_cp, 'bootstrap.py')):
+        break
+if _cp not in _s.path: _s.path.insert(0, _cp)
+from bootstrap import setup; setup()
+from foundation.core.paths import get_repo_root
+
+"""
+setup_lanhu.py - 蓝湖 MCP 引导器 (幂等)
+
+把第三方 dsphper/lanhu-mcp 引导成本机可用: clone + venv 依赖 + playwright + cookie + mcp.json 注册。
+
+蓝湖 MCP 与我们自己的 kg_mcp_server.py 不同:
+  - 它是 HTTP server (http://localhost:8000/mcp), 需要独立常驻启动
+    (不像 kg_mcp_server.py 被 QoderWork 通过 command/args 自动拉起)
+  - cookie (LANHU_COOKIE) 在它的 .env 里, 必须用户登录 lanhuapp.com 后
+    从浏览器 DevTools 复制 (AI 拿不到)
+  - QoderWork 的 mcp.json 用 url 字段注册 (Streamable HTTP), 不是 command/args
+
+被谁调用:
+  - setup.py Step 4.5: 主初始化流程
+  - install_qoderwork.py: 技能安装时同步注册 mcp.json
+  - 用户手动: python .qoder/scripts/setup_lanhu.py [--check|--uninstall]
+
+用法:
+  python .qoder/scripts/setup_lanhu.py             # 引导 + 注册 (幂等)
+  python .qoder/scripts/setup_lanhu.py --check     # 只体检不改动
+  python .qoder/scripts/setup_lanhu.py --uninstall # 删 external/lanhu-mcp/ + mcp.json 条目
+  python .qoder/scripts/setup_lanhu.py --skip-install  # 只注册 mcp.json, 不 clone/装依赖
+
+幂等: 已 clone 跳过 clone; venv+依赖装过跳过; cookie 有效跳过; mcp.json 有 lanhu 跳过。
+"""
+
+import argparse
+import json
+import os
+import shutil
+import socket
+import subprocess
+import sys
+from pathlib import Path
+
+try:
+    sys.stdout.reconfigure(encoding='utf-8', errors='replace')
+    sys.stderr.reconfigure(encoding='utf-8', errors='replace')
+except (AttributeError, TypeError, OSError):
+    pass
+
+THIS_DIR = Path(__file__).resolve().parent
+BASE = get_repo_root()
+
+LANHU_REPO = 'https://github.com/dsphper/lanhu-mcp.git'
+EXTERNAL_DIR = BASE / 'external'
+LANHU_DIR = EXTERNAL_DIR / 'lanhu-mcp'
+LANHU_VENV = LANHU_DIR / '.venv'
+LANHU_SERVER_SCRIPT = LANHU_DIR / 'lanhu_mcp_server.py'
+COOKIE_PLACEHOLDER = 'PUT_YOUR_COOKIE_HERE'
+LANHU_PORT = 8000
+LANHU_MCP_PATH = '/mcp'
+
+# QoderWork mcp.json 位置
+if sys.platform == 'win32':
+    _HOME = Path(os.environ.get('USERPROFILE', str(Path.home())))
+else:
+    _HOME = Path.home()
+QODERWORK_MCP_FILE = _HOME / '.qoderwork' / 'mcp.json'
+
+
+def _current_developer():
+    """读 .qoder/.developer 确定当前用户。没有返回 None。"""
+    try:
+        sys.path.insert(0, str(THIS_DIR))
+        from foundation.core.paths import get_developer
+        return get_developer(BASE)
+    except Exception:
+        return None
+
+
+def lanhu_secrets_dir(developer=None):
+    """当前用户的私密信息目录 (v3.0: 收进 .private/secrets/, 向后兼容老 .secrets/)。
+
+    按 .developer 隔离: 一台机器多人切换时, 各自的 cookie 互不覆盖。
+    """
+    dev = developer or _current_developer() or 'default'
+    try:
+        sys.path.insert(0, str(BASE / '.qoder' / 'scripts'))
+        from foundation.core.paths import get_secrets_dir
+        return Path(get_secrets_dir(dev))
+    except Exception:
+        return BASE / 'workspace' / 'members' / dev / '.secrets'
+
+
+def lanhu_env_file(developer=None):
+    """当前用户的蓝湖 cookie 文件: workspace/members/{dev}/.private/secrets/lanhu.env"""
+    return lanhu_secrets_dir(developer) / 'lanhu.env'
+
+
+# ============================================================
+# 工具函数
+# ============================================================
+
+def ok(msg):
+    print(f'  [\u2713] {msg}')  # ✓
+
+
+def warn(msg):
+    print(f'  [!] {msg}')
+
+
+def fail(msg):
+    print(f'  [\u2717] {msg}', file=sys.stderr)
+
+
+def ask(prompt, default='y'):
+    """交互式 yes/no, 默认 default。非交互环境返回 default。"""
+    if not sys.stdin.isatty():
+        return default.lower() in ('y', 'yes')
+    try:
+        ans = input(f'{prompt} [{default}] ').strip().lower() or default
+        return ans in ('y', 'yes')
+    except (EOFError, KeyboardInterrupt):
+        return default.lower() in ('y', 'yes')
+
+
+def run(cmd, **kwargs):
+    """跑子进程, 返回 CompletedProcess。encoding 容错。"""
+    kwargs.setdefault('capture_output', True)
+    kwargs.setdefault('text', True)
+    kwargs.setdefault('encoding', 'utf-8')
+    kwargs.setdefault('errors', 'replace')
+    return subprocess.run(cmd, **kwargs)
+
+
+def _venv_python(venv: Path) -> Path:
+    """venv 内的 python 可执行路径 (跨平台)。"""
+    if sys.platform == 'win32':
+        return venv / 'Scripts' / 'python.exe'
+    return venv / 'bin' / 'python'
+
+
+def _venv_pip(venv: Path) -> list:
+    """venv 内的 pip 调用命令 (用 python -m pip, 更稳)。"""
+    return [str(_venv_python(venv)), '-m', 'pip']
+
+
+# lanhu-mcp 的 fastmcp 依赖需要 Python >= 3.10。
+# 不能盲用 sys.executable (本机可能是 3.9), 得找一个 3.10+ 的解释器建 venv。
+LANHU_MIN_PYTHON = (3, 10)
+
+
+def _python_version(exe):
+    """返回解释器的 (major, minor) 元组, 探测失败返回 None。"""
+    try:
+        r = run([exe, '-c', 'import sys; print(sys.version_info[:2])'])
+        if r.returncode == 0:
+            import ast
+            ver = ast.literal_eval(r.stdout.strip())
+            if isinstance(ver, tuple) and len(ver) >= 2:
+                return (ver[0], ver[1])
+    except Exception:
+        pass
+    return None
+
+
+def find_python_310():
+    """找一个 Python >= 3.10 的解释器路径, 优先级:
+      1. sys.executable (如果本身就 >= 3.10, 直接用, 最省事)
+      2. Windows py launcher: py -3.10 / -3.11 / -3.12 / -3.13
+      3. 常见命令: python3.10/3.11/3.12, python3
+      4. 兜底返回 sys.executable (让 pip 报错给用户看真原因)
+    """
+    # 1. 当前解释器够新
+    if sys.version_info[:2] >= LANHU_MIN_PYTHON:
+        return sys.executable
+
+    # 2. Windows py launcher
+    if sys.platform == 'win32':
+        for v in ('3.13', '3.12', '3.11', '3.10'):
+            launcher = 'py' if shutil.which('py') else ('py.exe' if shutil.which('py.exe') else None)
+            if not launcher:
+                break
+            r = run([launcher, f'-{v}', '-c', 'import sys; print(sys.executable)'])
+            if r.returncode == 0 and r.stdout.strip():
+                exe = r.stdout.strip().strip('"')
+                ver = _python_version(exe)
+                if ver and ver >= LANHU_MIN_PYTHON:
+                    return exe
+
+    # 3. 常见命令名 (跨平台)
+    for cand in ('python3.13', 'python3.12', 'python3.11', 'python3.10',
+                 'python3', 'python'):
+        path = shutil.which(cand)
+        if path:
+            ver = _python_version(path)
+            if ver and ver >= LANHU_MIN_PYTHON:
+                return path
+
+    # 4. 兜底
+    return sys.executable
+
+
+# ============================================================
+# Step 1: clone / update lanhu-mcp
+# ============================================================
+
+def ensure_clone(dry=False, interactive=True):
+    """clone lanhu-mcp 到 external/lanhu-mcp/, 已存在则 git pull 更新。
+
+    返回 (status, path): status in ('cloned', 'updated', 'ok', 'failed', 'would', 'absent')
+    """
+    print('\n--- 1. 蓝湖 MCP 源码 ---')
+    if not shutil.which('git'):
+        warn('git 未安装, 无法 clone lanhu-mcp (装 git 后重跑)')
+        return ('failed', None)
+
+    if not LANHU_DIR.is_dir():
+        if dry:
+            print(f'  [MISS] 未 clone: {LANHU_DIR}')
+            return ('would', None)
+        EXTERNAL_DIR.mkdir(parents=True, exist_ok=True)
+        print(f'  git clone {LANHU_REPO} -> {LANHU_DIR}')
+        r = run(['git', 'clone', '--depth', '1', LANHU_REPO, str(LANHU_DIR)])
+        if r.returncode != 0:
+            fail('clone 失败: ' + (r.stderr or '').strip()[:200])
+            return ('failed', None)
+        ok(f'已 clone: {LANHU_DIR}')
+        return ('cloned', LANHU_DIR)
+
+    # 已存在: 检查是否是有效 repo
+    if not (LANHU_DIR / '.git').is_dir():
+        warn(f'{LANHU_DIR} 存在但不是 git 仓库, 跳过更新 (手动处理)')
+        return ('ok', LANHU_DIR)
+
+    if dry:
+        ok(f'已存在: {LANHU_DIR}')
+        return ('ok', LANHU_DIR)
+
+    # git pull 更新 (best-effort, 失败不阻塞)
+    r = run(['git', '-C', str(LANHU_DIR), 'pull', '--ff-only'])
+    if r.returncode == 0:
+        ok(f'已更新: {LANHU_DIR}')
+        return ('updated', LANHU_DIR)
+    warn('git pull 失败 (本地可能有改动), 用现有版本继续: '
+         + (r.stderr or '').strip()[:120])
+    return ('ok', LANHU_DIR)
+
+
+# ============================================================
+# Step 2: venv + 依赖 + playwright chromium
+# ============================================================
+
+def ensure_deps(dry=False, _rebuilt=False):
+    """建隔离 venv, 装 requirements.txt + playwright chromium。
+
+    幂等: venv+依赖装过则跳过 (靠一个 marker 文件判断)。
+    _rebuilt: 内部防无限递归 (删旧 venv 重建只允许一次)。
+    """
+    print('\n--- 2. 蓝湖 MCP 依赖 ---')
+    if not LANHU_DIR.is_dir():
+        warn('lanhu-mcp 未 clone, 跳过依赖安装')
+        return 'absent'
+
+    marker = LANHU_DIR / '.deps-installed'
+    req_file = LANHU_DIR / 'requirements.txt'
+
+    # 已装过 (marker 在 + requirements 没变) → 跳过
+    if marker.is_file() and req_file.is_file():
+        try:
+            marker_mtime = marker.stat().st_mtime
+            req_mtime = req_file.stat().st_mtime
+            if marker_mtime > req_mtime:
+                ok(f'依赖已装 (venv: {LANHU_VENV})')
+                return 'ok'
+        except OSError:
+            pass
+
+    if dry:
+        print(f'  [MISS] 依赖未装: {LANHU_VENV}')
+        return 'would'
+
+    # 建 venv (用 3.10+ Python, fastmcp 要求)
+    base_python = find_python_310()
+    base_ver = _python_version(base_python)
+    if not LANHU_VENV.is_dir():
+        if base_ver and base_ver >= LANHU_MIN_PYTHON:
+            print(f'  建 venv (Python {base_ver[0]}.{base_ver[1]}): '
+                  f'"{base_python}" -m venv {LANHU_VENV}')
+        else:
+            # 找不到 3.10+, 仍尝试建 (pip 会报错, 但给用户明确指引)
+            warn(f'未找到 Python >= 3.10 (fastmcp 要求)。当前最佳: '
+                 f'{base_python} ({base_ver})')
+            print(f'  建 venv: "{base_python}" -m venv {LANHU_VENV}')
+            print('  ⚠ 预计 pip install 会失败 — 装 Python 3.10+ 后重跑')
+        r = run([base_python, '-m', 'venv', str(LANHU_VENV)])
+        if r.returncode != 0:
+            fail('venv 创建失败: ' + (r.stderr or '').strip()[:200])
+            return 'failed'
+    elif base_ver and base_ver < LANHU_MIN_PYTHON and not _rebuilt:
+        # venv 已存在但可能是旧 3.9 建的 (之前版本的 bug), 删了重建。
+        # _rebuilt 防无限递归: 若本机没有 3.10+, 删了重建还是 3.9, 不再删第二次。
+        venv_ver = _python_version(_venv_python(LANHU_VENV))
+        if venv_ver and venv_ver < LANHU_MIN_PYTHON:
+            warn(f'现有 venv 是 Python {venv_ver[0]}.{venv_ver[1]} (fastmcp 需 3.10+), '
+                 f'删了重建')
+            try:
+                shutil.rmtree(LANHU_VENV)
+            except OSError:
+                pass
+            return ensure_deps(dry=dry, _rebuilt=True)
+
+    py = _venv_python(LANHU_VENV)
+    if not py.is_file():
+        fail(f'venv python 不存在: {py}')
+        return 'failed'
+
+    # 升级 pip
+    print('  升级 pip...')
+    run(_venv_pip(LANHU_VENV) + ['install', '--upgrade', 'pip'])
+
+    # 装 requirements.txt
+    if req_file.is_file():
+        print(f'  pip install -r requirements.txt')
+        r = run(_venv_pip(LANHU_VENV) + ['install', '-r', str(req_file)])
+        if r.returncode != 0:
+            fail('pip install requirements 失败: ' + (r.stderr or '').strip()[:200])
+            return 'failed'
+        ok('依赖已装')
+    else:
+        warn('requirements.txt 不存在, 跳过 (lanhu-mcp 目录结构可能变了)')
+
+    # playwright install chromium (150-300MB, 一次性)
+    print('  playwright install chromium (一次性, 约 150-300MB)...')
+    r = run([str(py), '-m', 'playwright', 'install', 'chromium'])
+    if r.returncode == 0:
+        ok('chromium 已装')
+    else:
+        warn('playwright install chromium 失败 (可稍后手动跑: '
+             f'{py} -m playwright install chromium)')
+        warn('  原因: ' + (r.stderr or '').strip()[:120])
+        # 不阻塞: cookie/服务启动后 playwright 缺失会在用时才报错
+
+    # 写 marker
+    try:
+        marker.write_text('deps installed\n', encoding='utf-8')
+    except OSError:
+        pass
+    return 'ok'
+
+
+# ============================================================
+# Step 3: cookie (按开发者隔离, workspace/members/{dev}/.private/secrets/lanhu.env)
+# ============================================================
+# 为什么不放 external/lanhu-mcp/.env:
+#   1. cookie 是个人登录凭证, 不该进仓库代码区 (即使 gitignore)
+#   2. 同一台机器多人切换 .developer 时, 单一 .env 会互相覆盖
+#   3. 跟 .signing_key / autotest-data.yaml 同一套隔离机制, 一致
+# 蓝湖服务端怎么读到这个 cookie:
+#   lanhu_mcp_server.py 用 load_dotenv(override=False), 已有环境变量优先。
+#   所以启动时把 LANHU_COOKIE 作为环境变量注入即可 (见 start_lanhu_server)。
+
+def _read_env_cookie(developer=None):
+    """读当前用户 lanhu.env 里的 LANHU_COOKIE, 没有返回 None。"""
+    env_file = lanhu_env_file(developer)
+    if not env_file.is_file():
+        return None
+    try:
+        for line in env_file.read_text(encoding='utf-8', errors='replace').splitlines():
+            line = line.strip()
+            if line.startswith('LANHU_COOKIE') and '=' in line:
+                val = line.split('=', 1)[1].strip().strip('"').strip("'")
+                return val
+    except OSError:
+        pass
+    return None
+
+
+def _write_env_cookie(cookie, developer=None):
+    """把 LANHU_COOKIE 写进当前用户的 lanhu.env (保留其他行)。
+
+    文件: workspace/members/{dev}/.private/secrets/lanhu.env (已 gitignore)
+    """
+    env_file = lanhu_env_file(developer)
+    try:
+        env_file.parent.mkdir(parents=True, exist_ok=True)
+        lines = []
+        found = False
+        if env_file.is_file():
+            for line in env_file.read_text(encoding='utf-8', errors='replace').splitlines():
+                if line.strip().startswith('LANHU_COOKIE') and '=' in line:
+                    lines.append(f'LANHU_COOKIE="{cookie}"')
+                    found = True
+                else:
+                    lines.append(line)
+        if not found:
+            lines.append(f'LANHU_COOKIE="{cookie}"')
+        env_file.write_text('\n'.join(lines) + '\n', encoding='utf-8')
+        return True
+    except OSError as e:
+        fail(f'写 {env_file} 失败: {e}')
+        return False
+
+
+def ensure_cookie(dry=False):
+    """收 cookie 写 .env。已有真 cookie 跳过; 没有则交互式引导。
+
+    返回 status: 'ok' (有真 cookie) / 'placeholder' (占位) / 'would' / 'absent'
+    """
+    dev = _current_developer()
+    env_file = lanhu_env_file(dev)
+    print('\n--- 3. 蓝湖 Cookie ---')
+    if dev:
+        print(f'  当前开发者: {dev}')
+        print(f'  cookie 文件: {env_file} (按人隔离, 不进 git)')
+    cookie = _read_env_cookie(dev)
+    if cookie and cookie != COOKIE_PLACEHOLDER:
+        ok(f'蓝湖 cookie 已配置 ({env_file.name})')
+        return 'ok'
+
+    if dry:
+        if cookie == COOKIE_PLACEHOLDER:
+            print(f'  [WARN] {env_file.name} 里是占位 cookie, 需要换成真的')
+        else:
+            print(f'  [MISS] 没有 LANHU_COOKIE ({env_file})')
+        return 'would'
+
+    # 交互式引导
+    if sys.stdin.isatty():
+        print()
+        print('  蓝湖 cookie 获取步骤:')
+        print('    1. 浏览器打开 https://lanhuapp.com 并登录')
+        print('    2. 按 F12 打开开发者工具, 切到 Network 标签')
+        print('    3. 刷新页面 (F5), 点任意一个请求')
+        print('    4. Request Headers 里找 Cookie: 这一行, 复制【整行】')
+        print('       (或 Application → Cookies → lanhuapp.com, 把所有项拼成')
+        print('        name1=value1; name2=value2 格式)')
+        print('    ⚠ 必须【整行】, 不能只复制 user_token 一个!')
+        print('       实测: 只给 user_token 蓝湖 API 返回 418 (鉴权失败),')
+        print('       需要 user_token + session + 其他项的组合才认。')
+        print()
+        try:
+            cookie = input('  粘贴蓝湖 cookie (留空跳过, 之后编辑 lanhu.env): ').strip()
+        except (EOFError, KeyboardInterrupt):
+            cookie = ''
+        if cookie and len(cookie) > 20:
+            if _write_env_cookie(cookie, dev):
+                ok(f'蓝湖 cookie 已写入 {env_file}')
+                return 'ok'
+            return 'placeholder'
+        warn(f'未输入 cookie, 写入占位 (之后编辑 {env_file} 换成真的)')
+    else:
+        # 非交互环境 (AI 调用): 写占位
+        warn('非交互环境, 无法收 cookie, 写入占位')
+
+    if _write_env_cookie(COOKIE_PLACEHOLDER, dev):
+        print(f'       占位已写入: {env_file}')
+        print(f'       编辑该文件, 把 {COOKIE_PLACEHOLDER} 换成真 cookie')
+    return 'placeholder'
+
+
+# ============================================================
+# Step 4: mcp.json 注册 (url 模式)
+# ============================================================
+
+def lanhu_mcp_url(developer_name='Developer'):
+    """生成蓝湖 MCP 的 url (HTTP Streamable, role/name 作为 query)。"""
+    import urllib.parse
+    name = urllib.parse.quote(developer_name or 'Developer')
+    return f'http://localhost:{LANHU_PORT}{LANHU_MCP_PATH}?role=Developer&name={name}'
+
+
+def _detect_python_command():
+    """探测本机可用的 python 命令 (跨平台)。win: py -3 > python; mac: python3。
+    复用 install_qoderwork 的逻辑, 但本文件独立实现避免循环依赖。"""
+    for cand in (('py', ['-3']), ('python3', []), ('python', [])):
+        name, extra = cand
+        if not shutil.which(name):
+            continue
+        cmd = [name] + extra + ['--version']
+        try:
+            r = run(cmd)
+            if r.returncode == 0:
+                return ' '.join([name] + extra)
+        except (OSError, subprocess.SubprocessError):
+            continue
+    return 'python'
+
+
+def _lanhu_stdio_entry():
+    """构造 STDIO 模式的 mcp.json lanhu 条目 (launcher 模式, 不写死路径)。
+
+    用统一启动器 mcp_launcher.py: command=python命令名, args=[launcher, "lanhu"]。
+    launcher 运行时自定位仓库根 + 找 venv python + 读角色 cookie。
+    这样 mcp.json 不含任何写死的仓库路径/venv路径, 跨机器通用。
+    """
+    py_cmd = _detect_python_command()
+    # launcher 在 ~/.qoderwork/mcp_launcher.py (install 时拷)
+    launcher = str(_HOME / '.qoderwork' / 'mcp_launcher.py')
+    return {
+        'command': py_cmd,
+        'args': [launcher, 'lanhu'],
+    }
+
+
+def _is_stdio_entry(entry):
+    """判断 mcp.json 里 lanhu 条目是不是 launcher STDIO 格式 (args 含 mcp_launcher)。"""
+    if not isinstance(entry, dict):
+        return False
+    args = entry.get('args', [])
+    return 'command' in entry and any('mcp_launcher.py' in str(a) for a in args)
+
+
+def register_lanhu_mcp(developer_name='Developer', dry=False):
+    """在 ~/.qoderwork/mcp.json 注册蓝湖 MCP (STDIO 模式, QoderWork 自动开关)。
+
+    STDIO 模式: command 指向 wrapper, QoderWork 开自动拉起、关自动杀。
+    cookie 由 wrapper 运行时按角色读 .secrets, 不进 mcp.json (角色隔离)。
+
+    迁移: 旧的 url 格式 (HTTP) → 升级成 STDIO。
+    幂等: 已是 STDIO 格式 → 跳过。
+    返回: 'ok-existing' / 'added' / 'upgraded' / 'would-add'
+    """
+    if not QODERWORK_MCP_FILE.is_file():
+        if dry:
+            return 'would-add'
+        QODERWORK_MCP_FILE.parent.mkdir(parents=True, exist_ok=True)
+
+    existing = {}
+    if QODERWORK_MCP_FILE.is_file():
+        try:
+            existing = json.loads(QODERWORK_MCP_FILE.read_text(encoding='utf-8'))
+            if not isinstance(existing, dict):
+                existing = {}
+        except (json.JSONDecodeError, OSError):
+            existing = {}
+
+    servers = existing.get('mcpServers', {})
+    if not isinstance(servers, dict):
+        servers = {}
+
+    cur = servers.get('lanhu')
+    stdio_entry = _lanhu_stdio_entry()
+
+    if cur and _is_stdio_entry(cur):
+        # 已是 STDIO, 但 command/args 可能因换机器变了 (venv 路径), 校准
+        if cur.get('command') == stdio_entry['command'] and cur.get('args') == stdio_entry['args']:
+            return 'ok-existing'
+        # 路径漂移, 更新
+        if dry:
+            return 'would-add'
+        servers['lanhu'] = stdio_entry
+        existing['mcpServers'] = servers
+        QODERWORK_MCP_FILE.write_text(
+            json.dumps(existing, indent=2, ensure_ascii=False) + '\n',
+            encoding='utf-8')
+        return 'upgraded'
+
+    if dry:
+        return 'would-add'
+
+    # 新增或从 url(HTTP) 升级到 STDIO
+    was_http = bool(cur and 'url' in cur)
+    servers['lanhu'] = stdio_entry
+    existing['mcpServers'] = servers
+    QODERWORK_MCP_FILE.write_text(
+        json.dumps(existing, indent=2, ensure_ascii=False) + '\n',
+        encoding='utf-8')
+    return 'upgraded' if was_http else 'added'
+
+
+def unregister_lanhu_mcp():
+    """从 mcp.json 删 lanhu 条目 (best-effort)。"""
+    if not QODERWORK_MCP_FILE.is_file():
+        return False
+    try:
+        existing = json.loads(QODERWORK_MCP_FILE.read_text(encoding='utf-8'))
+        servers = existing.get('mcpServers', {})
+        if 'lanhu' in servers:
+            del servers['lanhu']
+            existing['mcpServers'] = servers
+            QODERWORK_MCP_FILE.write_text(
+                json.dumps(existing, indent=2, ensure_ascii=False) + '\n',
+                encoding='utf-8',
+            )
+            return True
+    except (json.JSONDecodeError, OSError):
+        pass
+    return False
+
+
+# ============================================================
+# 健康探测: 蓝湖 HTTP 服务是否在跑
+# ============================================================
+
+def is_lanhu_running():
+    """探测 localhost:8000 是否在监听 (蓝湖服务是否启动)。"""
+    try:
+        with socket.create_connection(('127.0.0.1', LANHU_PORT), timeout=1):
+            return True
+    except (OSError, socket.timeout):
+        return False
+
+
+# ============================================================
+# 打印启动指引
+# ============================================================
+
+def print_start_hint():
+    """STDIO 模式下, 蓝湖由 QoderWork 自动管, 这个 hint 主要提示怎么验证。"""
+    print('\n  蓝湖 MCP (STDIO 模式, QoderWork 自动开关):')
+    print('    开 QoderWork 自动起, 关自动停 — 无需手动 start')
+    print('  验证: 在 QoderWork 里 /wl-design 预览 <蓝湖链接>, 能调通即正常')
+    print('  换角色: 改 .developer + 配新角色 cookie → 重启 QoderWork')
+    print('  调试/多客户端共享 (强制 HTTP): python .qoder/scripts/setup_lanhu.py start --http')
+
+
+# ============================================================
+# 启动蓝湖服务端 (读当前用户 cookie, 以环境变量注入)
+# ============================================================
+
+def start_lanhu_server(force_http=False):
+    """启动蓝湖 MCP 服务。
+
+    默认 (STDIO 模式): 不需要手动 start, QoderWork 自动管。本函数只提示。
+    force_http=True: 走旧 HTTP 模式 (前台常驻, 用于调试或多客户端共享)。
+    """
+    if not force_http:
+        print('=' * 56)
+        print('  蓝湖 MCP 服务启动')
+        print('=' * 56)
+        # 检测当前 mcp.json 是不是 STDIO
+        entry = None
+        if QODERWORK_MCP_FILE.is_file():
+            try:
+                entry = json.loads(QODERWORK_MCP_FILE.read_text(encoding='utf-8')).get('mcpServers', {}).get('lanhu')
+            except Exception:
+                pass
+        if _is_stdio_entry(entry) if entry else False:
+            ok('已是 STDIO 模式 — QoderWork 自动开关, 无需手动 start')
+            print('  开 QoderWork 自动拉起蓝湖 (wrapper 读当前角色 cookie), 关自动停')
+            print('  换角色: 改 .developer + 配新角色 cookie → 重启 QoderWork')
+            print('')
+            print('  要强制用 HTTP 模式 (调试/多客户端共享):')
+            print(f'    python .qoder/scripts/setup_lanhu.py start --http')
+            return 0
+        # 非 STDIO (旧 HTTP 或没注册), 提示升级
+        warn('当前不是 STDIO 模式, 手动 start 只支持 HTTP')
+        print('  建议升级 STDIO (QoderWork 自动开关): python .qoder/scripts/setup_lanhu.py')
+        print('  或强制 HTTP: python .qoder/scripts/setup_lanhu.py start --http')
+        return 1
+
+    # === HTTP 模式 (force_http=True, 降级/调试用) ===
+    print('=' * 56)
+    print('  启动蓝湖 MCP 服务端 (HTTP 模式, 降级/调试)')
+    print('=' * 56)
+
+    # 1. 源码 + venv 是否就绪
+    if not LANHU_SERVER_SCRIPT.is_file():
+        fail(f'蓝湖服务脚本不存在: {LANHU_SERVER_SCRIPT}')
+        print('  先跑: python .qoder/scripts/setup_lanhu.py')
+        return 1
+    py = _venv_python(LANHU_VENV)
+    if not py.is_file():
+        fail(f'venv python 不存在: {py}')
+        print('  先跑: python .qoder/scripts/setup_lanhu.py')
+        return 1
+
+    # 2. 当前用户 + cookie
+    dev = _current_developer()
+    env_file = lanhu_env_file(dev)
+    env_cookie = os.environ.get('LANHU_COOKIE', '').strip()
+    cookie_source = 'env' if env_cookie else 'file'
+    cookie = env_cookie or _read_env_cookie(dev)
+
+    print(f'  当前开发者: {dev or "(未初始化, 用 default)"}')
+    if cookie_source == 'env':
+        print(f'  cookie 来源: 环境变量 LANHU_COOKIE (临时, 不落盘)')
+    else:
+        print(f'  cookie 来源: {env_file} (主线, 落盘)')
+
+    if not cookie or cookie == COOKIE_PLACEHOLDER:
+        fail('cookie 未配置')
+        if cookie_source == 'env':
+            print('  环境变量 LANHU_COOKIE 是空的或占位')
+        else:
+            print(f'  编辑 {env_file}, 把 {COOKIE_PLACEHOLDER} 换成真 cookie')
+        print('  获取: lanhuapp.com 登录 → F12 → Network → Cookie 头复制')
+        return 1
+    print(f'  cookie: 已配置 (长度 {len(cookie)})')
+
+    # 3. 已在跑就别重复启
+    if is_lanhu_running():
+        warn(f'蓝湖服务已在跑 (localhost:{LANHU_PORT}), 不重复启动')
+        return 0
+
+    # 4. 以环境变量注入 cookie 启动 (前台常驻, Ctrl+C 退出)
+    print(f'\n  启动: {py} {LANHU_SERVER_SCRIPT}')
+    print(f'  HTTP: http://localhost:{LANHU_PORT}{LANHU_MCP_PATH}')
+    print('  (常驻前台, 用完 Ctrl+C 关闭。别关这个终端。)\n')
+    env = os.environ.copy()
+    env['LANHU_COOKIE'] = cookie
+    # 不捕获输出 —— 服务端日志直接打到当前终端, 用户能看到请求/报错
+    try:
+        return subprocess.call([str(py), str(LANHU_SERVER_SCRIPT)], env=env)
+    except OSError as e:
+        fail(f'启动失败: {e}')
+        return 1
+
+
+# ============================================================
+# 主流程
+# ============================================================
+
+def configure_lanhu(developer_name='Developer', dry=False, skip_install=False):
+    """完整引导: clone → 依赖 → cookie → mcp.json 注册。
+
+    返回 dict 报告各步状态。
+    """
+    report = {'clone': 'skipped', 'deps': 'skipped',
+              'cookie': 'skipped', 'mcp': 'skipped'}
+
+    if skip_install:
+        print('\n--- 蓝湖 MCP (--skip-install, 只注册 mcp.json) ---')
+    else:
+        print('\n' + '=' * 56)
+        print('  蓝湖 MCP 引导')
+        print('=' * 56)
+
+        # 1. clone
+        status, _ = ensure_clone(dry=dry)
+        report['clone'] = status
+        if status == 'failed':
+            print('\n蓝湖源码获取失败, 后续步骤跳过。')
+            return report
+
+        # 2. 依赖
+        report['deps'] = ensure_deps(dry=dry)
+
+    # 3. cookie (即使 skip_install 也引导, 因为 mcp.json 注册后需要 cookie 才能用)
+    if not skip_install:
+        report['cookie'] = ensure_cookie(dry=dry)
+
+    # 4. mcp.json 注册 (STDIO 模式, QoderWork 自动开关)
+    print('\n--- 4. 注册到 QoderWork mcp.json (STDIO 自动开关) ---')
+    status = register_lanhu_mcp(developer_name, dry=dry)
+    report['mcp'] = status
+    if status == 'ok-existing':
+        ok(f'蓝湖 MCP 已注册 (STDIO): {QODERWORK_MCP_FILE}')
+        print('       开 QoderWork 自动起, 关自动停, 无需手动 start')
+    elif status in ('added', 'upgraded'):
+        tag = '已写入' if status == 'added' else '已升级(HTTP→STDIO)'
+        ok(f'{tag} 蓝湖 MCP: {QODERWORK_MCP_FILE}')
+        print('       STDIO 模式: 开 QoderWork 自动起, 关自动停')
+        print(f'       command → wrapper → 读 {developer_name} 的 cookie 拉起 lanhu')
+    elif status == 'would-add':
+        print(f'  [MISS] 未注册, 安装时会写入 {QODERWORK_MCP_FILE}')
+
+    return report
+
+
+def print_check_report():
+    """--check 模式: 体检报告 (不改动)。"""
+    print('=' * 56)
+    print('  蓝湖 MCP 体检')
+    print('=' * 56)
+
+    # clone
+    print('\n--- 1. 源码 ---')
+    if LANHU_DIR.is_dir() and (LANHU_DIR / '.git').is_dir():
+        ok(f'已 clone: {LANHU_DIR}')
+        # 检查关键文件
+        server_file = LANHU_DIR / 'lanhu_mcp_server.py'
+        if server_file.is_file():
+            ok(f'入口文件在: {server_file}')
+        else:
+            warn(f'入口文件缺失: {server_file} (lanhu-mcp 版本结构可能变了)')
+    else:
+        print(f'  [MISS] 未 clone (跑 setup.py 或本脚本安装)')
+
+    # 依赖
+    print('\n--- 2. 依赖 ---')
+    if LANHU_VENV.is_dir() and _venv_python(LANHU_VENV).is_file():
+        marker = LANHU_DIR / '.deps-installed'
+        # 实测验证: 尝试导入 fastmcp (lanhu-mcp 的核心依赖, 缺它一定跑不起来)
+        # marker 只是快速跳过标记, 真相以能否导入为准
+        py = _venv_python(LANHU_VENV)
+        r = run([str(py), '-c', 'import fastmcp; print(fastmcp.__version__)'])
+        deps_importable = r.returncode == 0 and r.stdout.strip()
+        if deps_importable:
+            extra = f' (fastmcp {r.stdout.strip()})'
+            if marker.is_file():
+                ok(f'venv + 依赖已装: {LANHU_VENV}{extra}')
+            else:
+                ok(f'venv + 依赖已装 (marker 缺失但实测可导入): {LANHU_VENV}{extra}')
+                print(f'       (补写 marker 以便后续快速跳过)')
+                try:
+                    marker.write_text('deps verified by import\n', encoding='utf-8')
+                except OSError:
+                    pass
+        elif marker.is_file():
+            warn(f'marker 在但 fastmcp 导入失败, 依赖可能损坏: {LANHU_VENV}')
+            print(f'       重装: python .qoder/scripts/setup_lanhu.py')
+        else:
+            warn(f'venv 存在但依赖未装完 (fastmcp 不可导入): {LANHU_VENV}')
+            print(f'       重装: python .qoder/scripts/setup_lanhu.py')
+    else:
+        print(f'  [MISS] venv 未建 (跑 setup.py 或本脚本安装)')
+
+    # cookie (按开发者隔离)
+    print('\n--- 3. Cookie ---')
+    dev = _current_developer()
+    env_file = lanhu_env_file(dev)
+    if dev:
+        print(f'  当前开发者: {dev}')
+    cookie = _read_env_cookie(dev)
+    if cookie and cookie != COOKIE_PLACEHOLDER:
+        ok(f'蓝湖 cookie 已配置 ({env_file})')
+    elif cookie == COOKIE_PLACEHOLDER:
+        warn(f'占位 cookie ({COOKIE_PLACEHOLDER}), 需要换成真的')
+        print(f'       编辑: {env_file}')
+    else:
+        print(f'  [MISS] 没有 LANHU_COOKIE ({env_file})')
+
+    # mcp.json (STDIO 模式检测)
+    print('\n--- 4. QoderWork 注册 ---')
+    if QODERWORK_MCP_FILE.is_file():
+        try:
+            cfg = json.loads(QODERWORK_MCP_FILE.read_text(encoding='utf-8'))
+            servers = cfg.get('mcpServers', {})
+            entry = servers.get('lanhu')
+            if not entry:
+                print(f'  [MISS] mcp.json 没有 lanhu 条目')
+            elif _is_stdio_entry(entry):
+                launcher_ok = (_HOME / '.qoderwork' / 'mcp_launcher.py').is_file()
+                ok(f'已注册 (STDIO launcher, 自动开关): command={entry.get("command","?")}')
+                ok(f'  launcher 存在: {"✓" if launcher_ok else "✗ 缺 ~/.qoderwork/mcp_launcher.py (重跑 install_qoderwork)"}')
+                print('  开 QoderWork 自动起, 关自动停 (无需手动 start)')
+            elif 'command' in entry:
+                # 旧 STDIO (写死 venv 路径) 或其他 command 格式
+                warn(f'旧 STDIO 格式 (command 写死路径), 建议升级 launcher 模式')
+                print('  升级: python .qoder/scripts/install_qoderwork.py')
+            else:
+                warn(f'旧 HTTP 模式 (url={entry.get("url","?")[:50]}...), 需手动 start')
+                print('  升级 STDIO: python .qoder/scripts/setup_lanhu.py')
+        except (json.JSONDecodeError, OSError):
+            warn(f'mcp.json 解析失败: {QODERWORK_MCP_FILE}')
+    else:
+        print(f'  [MISS] mcp.json 不存在: {QODERWORK_MCP_FILE}')
+
+    # 服务状态 (STDIO 模式由 QoderWork 管, 不常驻端口; 这里只提示)
+    print('\n--- 5. 服务状态 ---')
+    entry = None
+    if QODERWORK_MCP_FILE.is_file():
+        try:
+            entry = json.loads(QODERWORK_MCP_FILE.read_text(encoding='utf-8')).get('mcpServers', {}).get('lanhu')
+        except Exception:
+            pass
+    if _is_stdio_entry(entry) if entry else False:
+        ok('STDIO 模式: QoderWork 启动时自动拉起 (不占常驻端口)')
+        print('  (要验证: 开 QoderWork 后 /wl-design 预览 <蓝湖链接> 能调通即正常)')
+    elif is_lanhu_running():
+        ok(f'蓝湖服务在跑 (HTTP, localhost:{LANHU_PORT}) — 旧模式, 建议升级 STDIO')
+    else:
+        print('  STDIO 模式下服务由 QoderWork 按需拉起, 这里不显示常驻状态')
+
+
+def do_uninstall():
+    """删 external/lanhu-mcp/ + mcp.json lanhu 条目。"""
+    print('=' * 56)
+    print('  蓝湖 MCP 卸载')
+    print('=' * 56)
+
+    # 1. mcp.json 条目
+    print('\n--- 1. 移除 mcp.json 条目 ---')
+    if unregister_lanhu_mcp():
+        ok(f'已从 mcp.json 删除 lanhu 条目')
+    else:
+        print('  mcp.json 无 lanhu 条目 (无需删除)')
+
+    # 2. external/lanhu-mcp/
+    print('\n--- 2. 删除源码 ---')
+    if LANHU_DIR.is_dir():
+        if ask(f'删除 {LANHU_DIR}? (含 venv + chromium 缓存, 不可恢复)', 'n'):
+            try:
+                shutil.rmtree(LANHU_DIR)
+                ok(f'已删除: {LANHU_DIR}')
+            except OSError as e:
+                fail(f'删除失败: {e}')
+        else:
+            print('  跳过 (保留源码)')
+    else:
+        print(f'  源码目录不存在: {LANHU_DIR}')
+
+    # 3. 清理空的 external/
+    if EXTERNAL_DIR.is_dir():
+        try:
+            remaining = list(EXTERNAL_DIR.iterdir())
+            if not remaining:
+                EXTERNAL_DIR.rmdir()
+                ok(f'已删除空目录: {EXTERNAL_DIR}')
+        except OSError:
+            pass
+
+    print('\n✓ 蓝湖 MCP 卸载完成。')
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description='蓝湖 MCP 引导器: clone + 依赖 + cookie + mcp.json 注册',
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog='''示例:
+  python .qoder/scripts/setup_lanhu.py             # 引导 + 注册 STDIO (幂等, 自动开关)
+  python .qoder/scripts/setup_lanhu.py --check     # 只体检
+  python .qoder/scripts/setup_lanhu.py start       # 提示 STDIO 状态 (默认无需手动)
+  python .qoder/scripts/setup_lanhu.py start --http # 强制 HTTP 模式 (调试/多客户端)
+  python .qoder/scripts/setup_lanhu.py --skip-install  # 只注册 mcp.json
+  python .qoder/scripts/setup_lanhu.py --uninstall # 卸载
+''')
+    parser.add_argument('command', nargs='?', default=None,
+                        help='子命令: start = 提示服务状态 (STDIO 自动, 加 --http 强制 HTTP)')
+    parser.add_argument('--check', action='store_true', help='只体检不改动')
+    parser.add_argument('--uninstall', action='store_true', help='卸载 (删源码 + mcp.json 条目)')
+    parser.add_argument('--skip-install', action='store_true',
+                        help='只注册 mcp.json, 不 clone/装依赖')
+    parser.add_argument('--http', action='store_true',
+                        help='start 时强制走 HTTP 模式 (调试/多客户端共享; 默认 STDIO 自动开关)')
+    parser.add_argument('--name', default='Developer', help='开发者名 (用于蓝湖 url 的 name 参数)')
+    args = parser.parse_args()
+
+    # 子命令: start (提示服务状态 / 强制 HTTP)
+    if args.command == 'start':
+        return start_lanhu_server(force_http=args.http)
+    if args.command and args.command not in (None,):
+        fail(f'未知子命令: {args.command}')
+        print('  可用: start [--http]')
+        return 1
+
+    if args.check:
+        print_check_report()
+        return 0
+
+    if args.uninstall:
+        do_uninstall()
+        return 0
+
+    report = configure_lanhu(
+        developer_name=args.name,
+        dry=False,
+        skip_install=args.skip_install,
+    )
+
+    # 汇总
+    print('\n' + '=' * 56)
+    print('  蓝湖 MCP 引导完成')
+    print('=' * 56)
+    print(f'  源码:   {report["clone"]}')
+    print(f'  依赖:   {report["deps"]}')
+    print(f'  Cookie: {report["cookie"]}')
+    print(f'  注册:   {report["mcp"]}')
+
+    if report['cookie'] == 'placeholder':
+        print(f'\n  ⚠ 下一步: 编辑 {lanhu_env_file()}, 把 {COOKIE_PLACEHOLDER} 换成真 cookie')
+
+    if report['mcp'] in ('added', 'ok-existing') and not is_lanhu_running():
+        print_start_hint()
+
+    print('\n  QoderWork 里用命令触发蓝湖 (非侵入式, 必须走命令):')
+    print('    /wl-design 预览 <蓝湖链接>  → design-import 调 mcp__lanhu__* (命令内授权)')
+    return 0
+
+
+if __name__ == '__main__':
+    sys.exit(main())