@hupan56/wlkj 3.4.9 → 3.5.1

package/templates/qoder/scripts/deployment/setup/install_qoderwork.py

@@ -1,835 +1,835 @@
-# -*- 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
-
-"""
-install_qoderwork.py - 把 .qoder/skills/ 安装到 QoderWork 桌面端可识别的位置
-
-QoderWork 从 %USERPROFILE%\\.qoderwork\\skills\\ 加载技能（每个子目录一个 skill），
-从 %USERPROFILE%\\.qoderwork\\commands\\ 加载斜杠命令。
-本项目源在 <repo>/.qoder/skills/ 和 <repo>/.qoder/commands/，QoderWork 不会读项目
-目录，必须软链/拷过去。
-（注: 旧版本误用 ~/.qoderworkcn/，已废弃，官方路径为 ~/.qoderwork/）
-
-为什么用 junction（mklink /J）而不是 symlink（mklink /D）：
-  - junction 不需要管理员权限，普通用户可建
-  - 本地评估默认启用，跨进程透明
-  - symlink 在未开开发者模式的 Windows 上需要 SeCreateSymbolicLink 特权
-
-用法:
-    python .qoder/scripts/install_qoderwork.py            # 安装/同步（幂等）
-    python .qoder/scripts/install_qoderwork.py --uninstall # 删除所有 junction（不删源）
-    python .qoder/scripts/install_qoderwork.py --check     # 仅检查，不改动
-    python .qoder/scripts/install_qoderwork.py --copy      # 改用拷贝（非 Windows 或不想软链）
-
-幂等：已存在的 junction 会跳过；已存在的非 junction 目录会报错让人工处理。
-"""
-
-import argparse
-import json
-import os
-import shutil
-import subprocess
-import sys
-from pathlib import Path
-
-# 确保 UTF-8 输出（Windows 控制台默认 GBK）
-if sys.platform == "win32":
-    try:
-        sys.stdout.reconfigure(encoding="utf-8")
-        sys.stderr.reconfigure(encoding="utf-8")
-    except (AttributeError, IOError):
-        pass
-
-# 路径自检：项目根 = 本文件上四级 (v3.0: setup/ -> scripts/ -> .qoder/ -> repo)
-SCRIPT_DIR = Path(__file__).resolve().parent
-PROJECT_ROOT = get_repo_root()
-SOURCE_SKILLS_DIR = PROJECT_ROOT / ".qoder" / "skills"
-SOURCE_COMMANDS_DIR = PROJECT_ROOT / ".qoder" / "commands"
-
-# QoderWork 目标目录 (官方: ~/.qoderwork/skills/ 和 ~/.qoderwork/commands/)
-# 注意: 之前误用了 ~/.qoderworkcn/ (国内版旧路径), 官方文档明确是 ~/.qoderwork/
-# https://docs.qoder.com/zh/qoderwork/skills
-if sys.platform == "win32":
-    _HOME = Path(os.environ.get("USERPROFILE", str(Path.home())))
-else:
-    _HOME = Path.home()
-QODERWORK_SKILLS_DIR = _HOME / ".qoderwork" / "skills"
-QODERWORK_COMMANDS_DIR = _HOME / ".qoderwork" / "commands"
-QODERWORK_MCP_FILE = _HOME / ".qoderwork" / "mcp.json"
-
-# Playwright MCP 配置 (让 QoderWork 的 AI 能用 Playwright 工具驱动浏览器, 快且稳)
-# 可选增强: 不装 playwright 也不影响 QoderWork 自带连接器
-# ⚠️ 实测: npx @playwright/mcp@latest 冷启动 11.7s, QoderWork 会超时杀掉 → 工具注册失败
-#    → AI 瞎猜工具名(BrowserNavigate) → 全失败。
-#    解法: 优先用"全局已装的 cli.js + node 直启"(0.57s), 探测不到才回退 npx。
-def _find_playwright_mcp_cli():
-    """探测全局已装的 @playwright/mcp/cli.js 路径, 返回 (node, cli.js) 或 None。
-    Windows 下 npm 是 .cmd, 必须 shell=True 才能调到。"""
-    import shutil, subprocess
-    node = shutil.which("node")
-    if not node:
-        return None
-    # npm root -g 拿全局 node_modules 路径 (最准, 跨自定义prefix)
-    try:
-        out = subprocess.run("npm root -g", capture_output=True, text=True,
-                             shell=True, timeout=10)
-        root = out.stdout.strip()
-        if root:
-            cli = os.path.join(root, "@playwright", "mcp", "cli.js")
-            if os.path.isfile(cli):
-                return node, cli
-    except Exception:
-        pass
-    # 回退: 试常见全局路径
-    for cand in [os.path.join(os.path.expanduser("~"), "AppData", "Roaming", "npm",
-                              "node_modules", "@playwright", "mcp", "cli.js")]:
-        if os.path.isfile(cand):
-            return node, cand
-    return None
-
-
-def _playwright_mcp_entry():
-    """生成 playwright MCP 配置: 优先 node+cli.js(快), 回退 npx(慢但通用)。"""
-    found = _find_playwright_mcp_cli()
-    if found:
-        node, cli = found
-        return {"playwright": {"command": node, "args": [cli]}}
-    # 回退: npx (冷启动慢, 可能被 QoderWork 超时杀, 但通用)
-    return {"playwright": {"command": "npx", "args": ["@playwright/mcp@latest"]}}
-
-
-PLAYWRIGHT_MCP_ENTRY = _playwright_mcp_entry()
-
-# 旧的错误路径 (迁移清理用)
-LEGACY_WRONG_DIR = _HOME / ".qoderworkcn" / "skills"
-
-
-def is_junction(path: Path) -> bool:
-    """判断目录是否是 junction/symlink（reparse point）。"""
-    if not path.exists():
-        return False
-    # Windows: 用 dir 命令检测 <JUNCTION> 标记最可靠（无需 ctypes）
-    if sys.platform == "win32":
-        try:
-            # os.lstat: reparse point 的 FILE_ATTRIBUTE_REPARSE_POINT (0x400) 会体现在 st_file_attributes
-            import stat as _stat
-            st = path.lstat()
-            # FILE_ATTRIBUTE_REPARSE_POINT = 0x400
-            return bool(getattr(st, "st_file_attributes", 0) & 0x400)
-        except (OSError, AttributeError):
-            return False
-    else:
-        return path.is_symlink()
-
-
-def find_source_skills() -> list:
-    """扫描 .qoder/skills/*/SKILL.md，返回 [(name, src_dir), ...]。"""
-    if not SOURCE_SKILLS_DIR.is_dir():
-        return []
-    result = []
-    for child in sorted(SOURCE_SKILLS_DIR.iterdir()):
-        if not child.is_dir():
-            continue
-        if (child / "SKILL.md").is_file():
-            result.append((child.name, child))
-    return result
-
-
-def file_equal(a: Path, b: Path) -> bool:
-    """快速判断两文件内容是否相同（先比大小再比内容，避免无谓全读）。"""
-    try:
-        if a.stat().st_size != b.stat().st_size:
-            return False
-        return a.read_bytes() == b.read_bytes()
-    except OSError:
-        return False
-
-
-def create_junction(link: Path, target: Path) -> bool:
-    """用 mklink /J 创建 junction。返回是否成功。"""
-    # 用 errors="replace" 防止 Windows GBK 输出（如"为...创建的联接"）触发 UnicodeDecodeError
-    cmd = ["cmd", "/c", "mklink", "/J", str(link), str(target)]
-    try:
-        r = subprocess.run(
-            cmd,
-            stdout=subprocess.PIPE,
-            stderr=subprocess.PIPE,
-            # 不用 text=True，自己 decode 防编码异常
-        )
-        return r.returncode == 0
-    except (OSError, subprocess.SubprocessError):
-        return False
-
-
-def install_one(name: str, src: Path, mode: str, dry: bool = False) -> str:
-    """
-    安装一个 skill 到 QoderWork 目录。
-    返回状态字符串：'created' / 'ok-existing' / 'copied' / 'error: ...' / 'skip: ...'
-    """
-    link = QODERWORK_SKILLS_DIR / name
-    if link.exists() or link.is_symlink():
-        if is_junction(link):
-            # 悬空 junction 检测: junction 存在但目标已移走/删除
-            # (常见于团队重命名 skill 后, 旧 junction 变成死链)
-            # link.exists() 对悬空 junction 返回 False, 但 link.is_symlink() 可能 True
-            # 用 os.path.exists 解析目标判断
-            try:
-                target_alive = os.path.exists(str(link))
-            except OSError:
-                target_alive = False
-            if target_alive:
-                return "ok-existing"
-            else:
-                # 悬空 junction, 删除后重建
-                if dry:
-                    return "would-recreate (dangling)"
-                try:
-                    if sys.platform == "win32":
-                        subprocess.run(["cmd", "/c", "rmdir", str(link)],
-                                       stdout=subprocess.PIPE, stderr=subprocess.PIPE, check=True)
-                    else:
-                        os.unlink(str(link))
-                except (OSError, subprocess.SubprocessError) as e:
-                    return "error: 悬空 junction 无法删除 (手动 rmdir {}): {}".format(link, e)
-                # 落到下面 recreate 逻辑
-        else:
-            # 非 junction 的真实目录/文件 -> 不覆盖
-            return f"skip: {name} 已存在且不是软链（避免覆盖，请人工确认 {link}）"
-
-    if dry:
-        return "would-create"
-
-    QODERWORK_SKILLS_DIR.mkdir(parents=True, exist_ok=True)
-
-    if mode == "copy":
-        try:
-            shutil.copytree(src, link)
-            return "copied"
-        except (OSError, shutil.Error) as e:
-            return f"error: copy 失败 {e}"
-    else:
-        # junction 模式（默认）
-        if sys.platform != "win32":
-            # 非 Windows 退化为 symlink，失败再退化为 copy
-            try:
-                os.symlink(src, link, target_is_directory=True)
-                return "created(symlink)"
-            except (OSError, NotImplementedError):
-                try:
-                    shutil.copytree(src, link)
-                    return "copied(fallback)"
-                except (OSError, shutil.Error) as e:
-                    return f"error: {e}"
-        if create_junction(link, src):
-            return "created"
-        return "error: mklink /J 失败（可能需要检查路径或权限）"
-
-
-def uninstall_one(name: str) -> str:
-    """删除一个 junction（只删 link，不删源）。"""
-    link = QODERWORK_SKILLS_DIR / name
-    if not link.exists() and not link.is_symlink():
-        return "absent"
-    if not is_junction(link):
-        return f"skip: {name} 不是软链（不动真实目录，请人工删除 {link}）"
-    try:
-        # 删 junction 用 rmdir（不递归到源）
-        if sys.platform == "win32":
-            subprocess.run(["cmd", "/c", "rmdir", str(link)],
-                           stdout=subprocess.PIPE, stderr=subprocess.PIPE, check=True)
-        else:
-            os.unlink(str(link))
-        return "removed"
-    except (OSError, subprocess.SubprocessError) as e:
-        return f"error: {e}"
-
-
-def setup_playwright_mcp(dry=False):
-    """把 Playwright MCP 写进 ~/.qoderwork/mcp.json (可选增强, 不影响自带连接器)。
-
-    让 QoderWork 的 AI 能用 Playwright 工具(browser_navigate/click/type/screenshot)
-    驱动浏览器 —— 快(10s级 vs 自带连接器 5-8分钟)、稳(不折腾 tab)、不依赖扩展。
-    已有 playwright 配置则跳过(幂等); 没有则追加。
-    """
-    import json
-    mcp_path = QODERWORK_MCP_FILE
-    # 读现有配置
-    existing = {}
-    if mcp_path.is_file():
-        try:
-            existing = json.loads(mcp_path.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 = {}
-    if "playwright" in servers:
-        # 已有配置: 若是旧的 npx@latest(慢, 易超时失败), 升级成 node+cli.js(快)
-        cur = servers["playwright"]
-        if cur.get("command") == "npx":
-            new_entry = PLAYWRIGHT_MCP_ENTRY["playwright"]
-            if new_entry.get("command") != "npx":  # 探测到了 cli.js
-                if dry:
-                    return "would-upgrade"
-                servers["playwright"] = new_entry
-                existing["mcpServers"] = servers
-                mcp_path.write_text(json.dumps(existing, indent=2, ensure_ascii=False), encoding="utf-8")
-                return "upgraded"
-        return "ok-existing"
-    if dry:
-        return "would-add"
-    # 追加 playwright
-    servers["playwright"] = PLAYWRIGHT_MCP_ENTRY["playwright"]
-    existing["mcpServers"] = servers
-    mcp_path.parent.mkdir(parents=True, exist_ok=True)
-    mcp_path.write_text(
-        json.dumps(existing, indent=2, ensure_ascii=False) + "\n",
-        encoding="utf-8",
-    )
-    return "added"
-
-
-def setup_lanhu_mcp(dry=False):
-    """注册蓝湖 MCP 到 ~/.qoderwork/mcp.json (可选增强, 设计稿直读)。
-
-    蓝湖 MCP (dsphper/lanhu-mcp) 是第三方 HTTP server, 让设计师发蓝湖链接,
-    AI 直读设计稿(颜色/尺寸/字体/切图)。注册成 url 模式 (Streamable HTTP),
-    跟 playwright/kg/mysql 这些 stdio server 并列。
-
-    注意: 蓝湖是 HTTP server, 需要用户手动启动
-      python .qoder/scripts/setup_lanhu.py start
-    (启动脚本自动读当前开发者的 cookie 注入, 不用手动配 .env)
-    本函数只注册 url (幂等), 不负责 clone/装依赖/启动 —— 那些由 setup_lanhu.py
-    在 setup.py Step 4.5 完成。这里只做 mcp.json 条目同步, 保证团队所有人
-    跑 install_qoderwork 后都能看到蓝湖 server。
-
-    返回: 'ok-existing' / 'added' / 'would-add'
-    """
-    # 复用 setup_lanhu.py 的注册逻辑 (单一事实源)
-    try:
-        sys.path.insert(0, str(SCRIPT_DIR))
-        from setup_lanhu import register_lanhu_mcp
-    except ImportError:
-        return 'would-add'
-    return register_lanhu_mcp(developer_name='Developer', dry=dry)
-
-
-def detect_python_command():
-    """探测本机可用的 python 命令名 (跨平台), 用于写进 mcp.json 的 command 字段。
-
-    ⚠️ 关键约束: 返回值必须是单个可执行文件名/路径, 不能含空格或参数。
-    旧版返回 'py -3' (带参数), MCP 客户端 spawn('py -3', args) 会把
-    'py -3' 当字面文件名 → 找不到可执行文件 → MCP 显示黄色(连接失败)。
-
-    优先级 (Windows): python > py > python3
-      - 故意把 python 放 py 前面: 'python' 是单文件名, 最稳;
-        'py' 需要配合 -3 参数, 但我们返回纯 'py' (不带 -3) 也通常能用
-        (py 启动器会选默认版本)。
-    优先级 (mac/linux): python3 > python
-
-    返回: 命令名字符串 (如 'python' / 'py' / 'python3'), 失败返回 None。
-    """
-    if sys.platform == 'win32':
-        candidates = ('python', 'py', 'python3')
-    else:
-        candidates = ('python3', 'python')
-    for name in candidates:
-        if not shutil.which(name):
-            continue
-        try:
-            r = subprocess.run([name, '--version'], capture_output=True, text=True,
-                               encoding='utf-8', errors='replace')
-            if r.returncode == 0:
-                return name  # 纯命令名, 不带参数
-        except (OSError, subprocess.SubprocessProcessError):
-            continue
-    return None
-
-
-def find_python_with_core_deps():
-    """找一个装了核心依赖 (duckdb/pymysql/yaml/requests) 的 Python 可执行文件。
-
-    用于写 mcp.json: 如果某个 Python 已经装了核心依赖, 直接用它当 command,
-    launcher 启动后 _find_python_with_deps 会秒命中 sys.executable, 不用再遍历。
-    解决"多 Python 共存, 装到了 A 但 mcp.json 指向 B"的常见问题。
-
-    返回: python 可执行文件路径(str) 或 None(没找到装了依赖的)。
-    """
-    # 先测当前 Python (install_qoderwork 正在跑的这个)
-    for mod in ('duckdb', 'pymysql', 'yaml', 'requests'):
-        try:
-            __import__(mod)
-        except ImportError:
-            break
-    else:
-        # 当前 Python 四个核心依赖都有 → 用它
-        return sys.executable
-
-    # 当前 Python 没装全, 找其它 Python
-    for name in ('python', 'python3', 'py'):
-        p = shutil.which(name)
-        if not p or p == sys.executable:
-            continue
-        try:
-            r = subprocess.run(
-                [p, '-c', 'import duckdb, pymysql, yaml, requests'],
-                capture_output=True, timeout=8)
-            if r.returncode == 0:
-                return p
-        except (OSError, subprocess.SubprocessProcessError):
-            continue
-    return None
-
-
-def rewrite_mcp_json_for_launcher():
-    """把 mcp.json 里所有 python MCP (kg/mysql/lanhu) 改成 launcher 模式。
-
-    ★ kg 走云平台 SSE url（共识），不走 launcher——在 for srv 循环已配 SSE，
-      这里跳过 kg（不改 launcher），保住 SSE 配置。
-
-    旧 (写死路径): {"command": "E:\\...\\python.exe", "args": ["E:\\...\\server.py"]}
-    新 (launcher): {"command": "<py cmd>", "args": ["<home>/.qoderwork/mcp_launcher.py", "<name>"]}
-
-    幂等: 已是 launcher 模式 (args 含 mcp_launcher.py) 则跳过。
-    全新机器: mcp.json 不存在时创建空骨架 + 写入 kg/mysql/lanhu 条目。
-    mysql env 抽到 ~/.qoderwork/.mcp-mysql-env.json (launcher 读)。
-    """
-    # 全新机器: mcp.json 不存在 → 创建空骨架 (playwright 后续会追加)
-    if not QODERWORK_MCP_FILE.is_file():
-        QODERWORK_MCP_FILE.parent.mkdir(parents=True, exist_ok=True)
-        QODERWORK_MCP_FILE.write_text(
-            '{"mcpServers": {}}\n', encoding="utf-8")
-    try:
-        cfg = json.loads(QODERWORK_MCP_FILE.read_text(encoding="utf-8"))
-    except (json.JSONDecodeError, OSError):
-        return
-    servers = cfg.get("mcpServers", {})
-    if not isinstance(servers, dict):
-        return
-
-    # 选 Python 写进 mcp.json:
-    # v3.0 修复: 用装了核心依赖的 Python 绝对路径 (不用命令名)!
-    # 原因: QoderWork 桌面应用不继承 shell PATH, 命令名(python/py -3)找不到 → 黄灯。
-    # 绝对路径每次 install 时探测, 换机器重跑 update 自动刷新。
-    # 依赖查找: 先找装了 duckdb 的 python (find_python_with_core_deps),
-    # 找不到回退 detect_python_command。
-    # ⚠ find_python_with_core_deps 返回 None (不抛异常) 时, 旧代码因 try/except
-    #   捕不到 → py_cmd 留 None → mcp.json 写 "command": null → QoderWork 起 MCP
-    #   失败变黄。这里显式 None 判断 + 多级回退, 绝不写 null。
-    py_cmd = find_python_with_core_deps()
-    if not py_cmd:
-        py_cmd = detect_python_command() or sys.executable or "python"
-    launcher = str(_HOME / ".qoderwork" / "mcp_launcher.py")
-    # MCP 名 → launcher 子命令
-    name_map = {
-        "qoder-knowledge-graph": "kg",
-        "qoder-mysql": "mysql",
-        "qoder-zentao": "zentao",
-        "lanhu": "lanhu",
-    }
-    changed = False
-    for srv, sub in name_map.items():
-        # 共识：kg 走云平台（默认 http://10.89.7.120:10010/mcp，config platform_mcp.url 可覆盖）
-        if srv == "qoder-knowledge-graph":
-            _pm = "http://10.89.7.120:10010/mcp"
-            try:
-                import yaml as _y
-                _cfg_p = get_repo_root() / ".qoder" / "config.yaml"
-                if _cfg_p.is_file():
-                    _cfg = _y.safe_load(_cfg_p.read_text(encoding="utf-8")) or {}
-                    _pm = (_cfg.get("platform_mcp") or {}).get("url", "") or _pm
-            except Exception:
-                pass
-            servers[srv] = {"url": _pm, "type": "sse", "enabled": True}
-            changed = True
-            continue
-        entry = servers.get(srv)
-        # 全新机器: kg/mysql/lanhu 条目可能不存在 → 创建它 (launcher 模式)
-        if not entry:
-            servers[srv] = {"command": py_cmd, "args": [launcher, sub], "enabled": True}
-            changed = True
-            continue
-        # 已是 launcher 模式? 检查 command 是否需要更新 (Python 路径可能变了)
-        args = entry.get("args", []) if isinstance(entry, dict) else []
-        if args and any("mcp_launcher.py" in str(a) for a in args):
-            # launcher 模式, 但 command 可能指向旧的/错的 Python → 更新
-            old_cmd = entry.get("command", "") if isinstance(entry, dict) else ""
-            if old_cmd != py_cmd:
-                servers[srv] = {"command": py_cmd, "args": [launcher, sub], "enabled": True}
-                changed = True
-            # 补 enabled (旧版可能没写, 导致黄灯)
-            if isinstance(entry, dict) and not entry.get("enabled"):
-                entry["enabled"] = True
-                changed = True
-            continue
-        # mysql env 抽离到独立文件
-        if srv == "qoder-mysql" and isinstance(entry, dict) and entry.get("env"):
-            env_file = _HOME / ".qoderwork" / ".mcp-mysql-env.json"
-            try:
-                env_file.write_text(json.dumps(entry["env"], indent=2, ensure_ascii=False) + "\n",
-                                    encoding="utf-8")
-            except OSError:
-                pass
-        # 改成 launcher 模式
-        servers[srv] = {"command": py_cmd, "args": [launcher, sub], "enabled": True}
-        changed = True
-
-    if changed:
-        cfg["mcpServers"] = servers
-        try:
-            QODERWORK_MCP_FILE.write_text(
-                json.dumps(cfg, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
-            print(f"\n--- mcp.json 重写为 launcher 模式 ---")
-            print(f"  [UPD]  kg/mysql/zentao/lanhu → command={py_cmd} (命令名, 跨机器通用)")
-            print(f"         args=[mcp_launcher.py, <名>] (launcher 内部找装依赖的 Python)")
-            print(f"         不再写死绝对路径, 换机器/重装Python不会失效")
-        except OSError as e:
-            print(f"  [ERR]  mcp.json 重写失败: {e}")
-
-
-def main():
-    parser = argparse.ArgumentParser(
-        description="把 .qoder/skills/ 安装到 QoderWork 桌面端目录"
-    )
-    parser.add_argument("--uninstall", action="store_true",
-                        help="删除所有 junction（不删源）")
-    parser.add_argument("--check", action="store_true",
-                        help="仅检查状态，不改动")
-    parser.add_argument("--copy", action="store_true",
-                        help="用拷贝代替 junction（非 Windows 或不想软链时用）")
-    parser.add_argument("--force-commands", action="store_true",
-                        help="强制覆盖已存在的 command 文件（升级时用；默认已存在则跳过）")
-    parser.add_argument("--mcp-only", action="store_true",
-                        help="只刷新 launcher + mcp.json，不装 skill（update 时调）")
-    args = parser.parse_args()
-
-    # --mcp-only: 轻量模式, 只刷 launcher + mcp.json, 不装 skill
-    if args.mcp_only:
-        print("=" * 56)
-        print("MCP 配置刷新 (--mcp-only)")
-        print("=" * 56)
-        # 1. 复制 launcher
-        launcher_src = SOURCE_COMMANDS_DIR.parent / "scripts" / "protocol" / "mcp" / "mcp_launcher.py"  # v3.0: protocol/mcp子包
-        launcher_dst = _HOME / ".qoderwork" / "mcp_launcher.py"
-        try:
-            launcher_dst.parent.mkdir(parents=True, exist_ok=True)
-            if launcher_src.is_file():
-                import shutil as _sh
-                _sh.copy2(str(launcher_src), str(launcher_dst))
-                print(f"  [OK]   launcher 已刷新: {launcher_dst}")
-            else:
-                print(f"  [ERR]  源不存在: {launcher_src}")
-        except OSError as e:
-            print(f"  [ERR]  复制失败: {e}")
-        # 2. 重写 mcp.json 为 launcher 模式 (创建 kg/mysql/lanhu)
-        rewrite_mcp_json_for_launcher()
-        # 3. 补 playwright (rewrite 不含它)
-        try:
-            setup_playwright_mcp(dry=False)
-        except Exception:
-            pass
-        # 4. 写 .repo-root 锚点 (launcher 定位仓库根用)
-        # 防御: 二次验证 PROJECT_ROOT 是"真仓库" (有 workspace/data/.git),
-        #       防止测试在临时目录跑 install 污染全局 .repo-root。
-        is_real_repo = any((PROJECT_ROOT / m).exists() for m in ('workspace', 'data', '.git'))
-        anchor = _HOME / ".qoderwork" / ".repo-root"
-        try:
-            anchor.parent.mkdir(parents=True, exist_ok=True)
-            if is_real_repo:
-                anchor.write_text(str(PROJECT_ROOT), encoding="utf-8")
-                print(f"  [OK]   .repo-root 锚点: {anchor} -> {PROJECT_ROOT}")
-            else:
-                print(f"  [SKIP] .repo-root 未更新 ({PROJECT_ROOT} 非真仓库, 缺 workspace/data/.git)")
-        except OSError:
-            pass
-        # 5. 复制 wlkj 薄壳 (QoderWork 桌面端任意 cwd 直跑 wlkj, 不用每次先算 R)
-        # 治"相对路径在会话临时 cwd 失效"踩坑 (真实: 连续 2 条命令报错浪费一轮)
-        shim_src = SOURCE_COMMANDS_DIR.parent / "scripts" / "deployment" / "setup" / "wlkj_shim.py"
-        shim_dst = _HOME / ".qoderwork" / "wlkj.py"
-        try:
-            if shim_src.is_file():
-                import shutil as _sh2
-                _sh2.copy2(str(shim_src), str(shim_dst))
-                print(f"  [OK]   wlkj 薄壳: {shim_dst} (任意 cwd 可跑: python ~/.qoderwork/wlkj.py ...)")
-        except OSError as e:
-            print(f"  [ERR]  wlkj 薄壳复制失败: {e}")
-        return
-
-    print("=" * 56)
-    print("QoderWork 技能安装器")
-    print(f"  源:   {SOURCE_SKILLS_DIR}")
-    print(f"  目标: {QODERWORK_SKILLS_DIR}")
-    print("=" * 56)
-
-    # 迁移清理: 旧版本错装到了 ~/.qoderworkcn/, 清理掉避免混淆
-    if not args.check and LEGACY_WRONG_DIR.exists():
-        legacy_junctions = []
-        try:
-            for child in LEGACY_WRONG_DIR.iterdir():
-                if is_junction(child):
-                    legacy_junctions.append(child.name)
-        except OSError:
-            pass
-        if legacy_junctions:
-            print(f"\n[迁移] 发现旧版本错装在 {LEGACY_WRONG_DIR} ({len(legacy_junctions)} 个)")
-            print(f"       QoderWork 实际读的是 ~/.qoderwork/, 正在清理旧 junction...")
-            for name in legacy_junctions:
-                try:
-                    subprocess.run(["cmd", "/c", "rmdir", str(LEGACY_WRONG_DIR / name)],
-                                   stdout=subprocess.PIPE, stderr=subprocess.PIPE, check=True)
-                except (OSError, subprocess.SubprocessError):
-                    pass
-            print(f"       已清理 {len(legacy_junctions)} 个旧 junction")
-            # 若旧目录空了, 删掉
-            try:
-                remaining = list(LEGACY_WRONG_DIR.iterdir())
-                if not remaining and LEGACY_WRONG_DIR.parent.exists():
-                    LEGACY_WRONG_DIR.rmdir()
-                    print(f"       已删除空目录 {LEGACY_WRONG_DIR.parent}")
-            except OSError:
-                pass
-
-    sources = find_source_skills()
-    if not sources:
-        print(f"[ERR] 源目录无 skill：{SOURCE_SKILLS_DIR}")
-        print("      检查 .qoder/skills/*/SKILL.md 是否存在")
-        return 1
-
-    mode = "copy" if args.copy else "junction"
-    action = "check" if args.check else ("uninstall" if args.uninstall else "install")
-    print(f"\n模式: {action} / link={mode}，发现 {len(sources)} 个源 skill\n")
-
-    results = {}
-    for name, src in sources:
-        if action == "uninstall":
-            results[name] = uninstall_one(name)
-        elif action == "check":
-            link = QODERWORK_SKILLS_DIR / name
-            if link.exists() or link.is_symlink():
-                results[name] = "ok(junction)" if is_junction(link) else "WARN(非软链)"
-            else:
-                results[name] = "missing"
-        else:  # install
-            results[name] = install_one(name, src, mode, dry=False)
-
-    # 打印结果
-    print("-" * 56)
-    counts = {"ok": 0, "create": 0, "copy": 0, "warn": 0, "err": 0, "missing": 0}
-    for name, status in sorted(results.items()):
-        tag = ""
-        if status.startswith("ok") or status == "copied" or status.startswith("created"):
-            if status.startswith("created") or status == "copied":
-                counts["create"] += 1
-                tag = "[NEW]"
-            else:
-                counts["ok"] += 1
-                tag = "[OK]"
-        elif status.startswith("skip"):
-            counts["warn"] += 1
-            tag = "[WARN]"
-        elif status.startswith("error"):
-            counts["err"] += 1
-            tag = "[ERR]"
-        elif status == "missing":
-            counts["missing"] += 1
-            tag = "[MISS]"
-        elif status == "removed":
-            counts["ok"] += 1
-            tag = "[DEL]"
-        elif status.startswith("WARN"):
-            counts["warn"] += 1
-            tag = "[WARN]"
-        else:
-            counts["ok"] += 1
-            tag = "[OK]"
-        print(f"  {tag:6} {name:22} {status}")
-
-    print("-" * 56)
-    print(f"\n小结: 新建 {counts['create']} / 已存在 {counts['ok']} / "
-          f"缺失 {counts['missing']} / 警告 {counts['warn']} / 错误 {counts['err']}")
-
-    # 同时安装 commands (让 QoderWork 用户级也能看到 /wl-* 命令)
-    if action in ("install", "check") and SOURCE_COMMANDS_DIR.is_dir():
-        print("\n--- Commands (/wl-* 斜杠命令) ---")
-        cmd_count = {"ok": 0, "new": 0, "upd": 0}
-        for cmd_file in sorted(SOURCE_COMMANDS_DIR.rglob("*.md")):
-            name = cmd_file.name  # e.g. wl-prd.md (子目录归类的也平铺到目标)
-            target = QODERWORK_COMMANDS_DIR / name
-            if action == "check":
-                if target.exists():
-                    cmd_count["ok"] += 1
-                else:
-                    print(f"  [MISS] {name}")
-            else:  # install
-                need_copy = False
-                is_update = False
-                if not target.exists():
-                    need_copy = True
-                else:
-                    # 始终按内容同步(幂等): 不同就刷新。
-                    # command 是纯文本小文件, 内容不同说明源已升级, 必须覆盖,
-                    # 否则 QoderWork 用旧 command → 走错流程(如旧 wl-test 搜代码)。
-                    if not file_equal(cmd_file, target):
-                        need_copy = True
-                        is_update = True
-                if need_copy:
-                    try:
-                        QODERWORK_COMMANDS_DIR.mkdir(parents=True, exist_ok=True)
-                        shutil.copy2(str(cmd_file), str(target))
-                        if is_update:
-                            cmd_count["upd"] += 1
-                        else:
-                            cmd_count["new"] += 1
-                    except OSError as e:
-                        print(f"  [ERR] {name}: {e}")
-                else:
-                    cmd_count["ok"] += 1
-        msg = f"  commands: {cmd_count['new']} 新建 / {cmd_count['ok']} 已存在"
-        if cmd_count["upd"]:
-            msg += f" / {cmd_count['upd']} 刷新"
-        print(msg)
-
-    # === 2.5. repo_root.py (QoderWork 桌面端仓库根定位器) ===
-    # QoderWork 桌面端工作目录是临时会话目录, 不是仓库根, 相对路径失效。
-    # repo_root.py 从 mcp.json 反推仓库根, 命令文件靠它定位脚本/模板。
-    if action in ("install", "check"):
-        repo_root_src = SOURCE_COMMANDS_DIR.parent / "scripts" / "deployment" / "setup" / "repo_root.py"  # v3.0: deployment/setup子包
-        repo_root_dst = _HOME / ".qoderwork" / "repo_root.py"
-        if repo_root_src.is_file():
-            if action == "check":
-                if repo_root_dst.exists():
-                    print(f"\n--- repo_root.py (仓库根定位器) ---")
-                    print(f"  [OK]   {repo_root_dst}")
-                else:
-                    print(f"\n--- repo_root.py (仓库根定位器) ---")
-                    print(f"  [MISS] 未安装到 {repo_root_dst}")
-            else:
-                try:
-                    repo_root_dst.parent.mkdir(parents=True, exist_ok=True)
-                    shutil.copy2(str(repo_root_src), str(repo_root_dst))
-                    print(f"\n--- repo_root.py (仓库根定位器) ---")
-                    print(f"  [OK]   已安装: {repo_root_dst}")
-                except OSError as e:
-                    print(f"\n--- repo_root.py (仓库根定位器) ---")
-                    print(f"  [ERR]  {e}")
-
-    # === 2.6. mcp_launcher.py + .repo-root (统一 MCP 启动器, 消除写死路径) ===
-    # mcp_launcher.py 让 mcp.json 不再写死仓库路径/venv路径, 跨 Win/Mac 通用。
-    # .repo-root 锚点文件让 launcher 能定位仓库根 (不依赖 mcp.json 里的路径)。
-    if action in ("install", "check"):
-        print(f"\n--- mcp_launcher.py (统一 MCP 启动器) ---")
-        launcher_src = SOURCE_COMMANDS_DIR.parent / "scripts" / "protocol" / "mcp" / "mcp_launcher.py"  # v3.0: protocol/mcp子包
-        launcher_dst = _HOME / ".qoderwork" / "mcp_launcher.py"
-        anchor_dst = _HOME / ".qoderwork" / ".repo-root"
-        if action == "check":
-            if launcher_dst.exists():
-                print(f"  [OK]   launcher 已装: {launcher_dst}")
-            else:
-                print(f"  [MISS] launcher 未装")
-            if anchor_dst.exists():
-                print(f"  [OK]   .repo-root 锚点在: {anchor_dst}")
-            else:
-                print(f"  [MISS] .repo-root 锚点缺失 (launcher 会回退向上找)")
-        else:
-            try:
-                launcher_dst.parent.mkdir(parents=True, exist_ok=True)
-                if launcher_src.is_file():
-                    shutil.copy2(str(launcher_src), str(launcher_dst))
-                    print(f"  [OK]   launcher 已装: {launcher_dst}")
-                else:
-                    print(f"  [ERR]  源不存在: {launcher_src}")
-                # 写 .repo-root 锚点 (记录当前仓库根, launcher 读它定位)
-                anchor_dst.write_text(str(PROJECT_ROOT) + "\n", encoding="utf-8")
-                print(f"  [OK]   .repo-root 锚点已写: {PROJECT_ROOT}")
-            except OSError as e:
-                print(f"  [ERR]  {e}")
-
-    # === 2.7. 重写 mcp.json: 所有 python MCP 改 launcher 模式 (消除写死路径) ===
-    if action == "install":
-        rewrite_mcp_json_for_launcher()
-
-    # === 3. Playwright MCP (可选增强: 让 QoderWork 能用 Playwright 驱动浏览器) ===
-    if action in ("install", "check"):
-        print("\n--- Playwright MCP (浏览器自动化增强, 可选) ---")
-        pw_status = setup_playwright_mcp(dry=(action == "check"))
-        if pw_status == "ok-existing":
-            print(f"  [OK]   playwright MCP 已配置: {QODERWORK_MCP_FILE}")
-        elif pw_status == "added":
-            print(f"  [NEW]  已写入 playwright MCP: {QODERWORK_MCP_FILE}")
-            print("         QoderWork 重启后, AI 可用 Playwright 工具驱动浏览器(快、稳)")
-        elif pw_status == "upgraded":
-            print(f"  [FIX]  playwright MCP 已升级: npx(慢,易超时) → node+cli.js(0.5s启动)")
-            print("         ⚠️ 必须 重启 QoderWork 生效。旧 npx 配置会被 QoderWork 超时杀掉导致工具注册失败")
-        elif pw_status == "would-upgrade":
-            print(f"  [FIX]  检测到旧 npx 配置(慢), 安装时会升级为 node+cli.js")
-        elif pw_status == "would-add":
-            print(f"  [MISS] 未配置 playwright MCP, 安装时会写入 {QODERWORK_MCP_FILE}")
-        # 检查 playwright mcp 是否已装(优先看 cli.js, 决定能否走快路径)
-        pw_cli = _find_playwright_mcp_cli()
-        if pw_cli:
-            print(f"  启动方式: node + cli.js (0.5s, 快) ← {pw_cli[1]}")
-        else:
-            npx_ok = shutil.which("npx") is not None
-            print(f"  启动方式: {'npx (11s冷启动, 可能被QoderWork超时杀)' if npx_ok else '✗ 未装 Node.js'}")
-            if npx_ok:
-                print("  提示: 装 @playwright/mcp 全局后重跑本脚本, 会自动切换到快的 node 启动: npm i -g @playwright/mcp")
-
-    # === 4. 蓝湖 MCP (可选增强: 设计师发蓝湖链接, AI 直读设计稿) ===
-    if action in ("install", "check"):
-        print("\n--- 蓝湖 MCP (设计稿直读增强, 可选) ---")
-        lh_status = setup_lanhu_mcp(dry=(action == "check"))
-        if lh_status == "ok-existing":
-            print(f"  [OK]   蓝湖 MCP 已注册: {QODERWORK_MCP_FILE}")
-        elif lh_status == "added":
-            print(f"  [NEW]  已写入蓝湖 MCP (STDIO): {QODERWORK_MCP_FILE}")
-            print("         QoderWork 开自动起、关自动停; 命令内授权调 mcp__lanhu__*")
-        elif lh_status == "upgraded":
-            print(f"  [UPD]  蓝湖 MCP 升级 HTTP→STDIO: {QODERWORK_MCP_FILE}")
-            print("         重启 QoderWork 后自动开关, 无需手动 start")
-        elif lh_status == "would-add":
-            print(f"  [MISS] 未注册蓝湖 MCP, 安装时会写入 {QODERWORK_MCP_FILE}")
-        # STDIO 模式由 QoderWork 自动管, 不查端口; 只确认 wrapper + 源码就绪
-        wrapper = PROJECT_ROOT / ".qoder" / "scripts" / "protocol" / "mcp" / "lanhu_stdio_wrapper.py"
-        lanhu_dir = PROJECT_ROOT / "external" / "lanhu-mcp"
-        if wrapper.is_file():
-            print(f"  wrapper 就绪: {wrapper.name} (按角色读 cookie)")
-        else:
-            print(f"  [MISS] wrapper 缺失: {wrapper}")
-        if not lanhu_dir.is_dir():
-            print("  蓝湖源码: 未 clone (跑 setup.py 或 setup_lanhu.py 安装)")
-
-    if action == "install" and counts["err"] == 0:
-        print("\n✓ 安装完成。重启 QoderWork（或新建对话）后技能生效。")
-        print("  在 QoderWork 里直接用自然语言即可，例如：")
-        print('    "写个保险异常筛选的 PRD"  -> /wl-prd（正经需求, 完整档）')
-        print('    "列表加个导出按钮"       -> /wl-prd（小改动, 自动走快速档）')
-        print('    "查一下考勤代码在哪"      -> /wl-search')
-    elif action == "install" and counts["err"] > 0:
-        print(f"\n⚠ 有 {counts['err']} 个安装失败，见上方 [ERR] 行。")
-        print("  常见原因: 目标路径被占用为非软链。手动删除该目录后重跑本脚本。")
-        return 1
-    elif action == "uninstall":
-        print("\n✓ 卸载完成（源文件未动）。")
-    elif action == "check":
-        if counts["missing"] > 0 or counts["warn"] > 0:
-            print("\n⚠ 检测到缺失/异常，建议跑: python .qoder/scripts/install_qoderwork.py")
-            return 1
-        else:
-            print("\n✓ 全部 skill 已正确安装到 QoderWork 目录。")
-    return 0
-
-
-if __name__ == "__main__":
-    sys.exit(main())
+# -*- 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
+
+"""
+install_qoderwork.py - 把 .qoder/skills/ 安装到 QoderWork 桌面端可识别的位置
+
+QoderWork 从 %USERPROFILE%\\.qoderwork\\skills\\ 加载技能（每个子目录一个 skill），
+从 %USERPROFILE%\\.qoderwork\\commands\\ 加载斜杠命令。
+本项目源在 <repo>/.qoder/skills/ 和 <repo>/.qoder/commands/，QoderWork 不会读项目
+目录，必须软链/拷过去。
+（注: 旧版本误用 ~/.qoderworkcn/，已废弃，官方路径为 ~/.qoderwork/）
+
+为什么用 junction（mklink /J）而不是 symlink（mklink /D）：
+  - junction 不需要管理员权限，普通用户可建
+  - 本地评估默认启用，跨进程透明
+  - symlink 在未开开发者模式的 Windows 上需要 SeCreateSymbolicLink 特权
+
+用法:
+    python .qoder/scripts/install_qoderwork.py            # 安装/同步（幂等）
+    python .qoder/scripts/install_qoderwork.py --uninstall # 删除所有 junction（不删源）
+    python .qoder/scripts/install_qoderwork.py --check     # 仅检查，不改动
+    python .qoder/scripts/install_qoderwork.py --copy      # 改用拷贝（非 Windows 或不想软链）
+
+幂等：已存在的 junction 会跳过；已存在的非 junction 目录会报错让人工处理。
+"""
+
+import argparse
+import json
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+# 确保 UTF-8 输出（Windows 控制台默认 GBK）
+if sys.platform == "win32":
+    try:
+        sys.stdout.reconfigure(encoding="utf-8")
+        sys.stderr.reconfigure(encoding="utf-8")
+    except (AttributeError, IOError):
+        pass
+
+# 路径自检：项目根 = 本文件上四级 (v3.0: setup/ -> scripts/ -> .qoder/ -> repo)
+SCRIPT_DIR = Path(__file__).resolve().parent
+PROJECT_ROOT = get_repo_root()
+SOURCE_SKILLS_DIR = PROJECT_ROOT / ".qoder" / "skills"
+SOURCE_COMMANDS_DIR = PROJECT_ROOT / ".qoder" / "commands"
+
+# QoderWork 目标目录 (官方: ~/.qoderwork/skills/ 和 ~/.qoderwork/commands/)
+# 注意: 之前误用了 ~/.qoderworkcn/ (国内版旧路径), 官方文档明确是 ~/.qoderwork/
+# https://docs.qoder.com/zh/qoderwork/skills
+if sys.platform == "win32":
+    _HOME = Path(os.environ.get("USERPROFILE", str(Path.home())))
+else:
+    _HOME = Path.home()
+QODERWORK_SKILLS_DIR = _HOME / ".qoderwork" / "skills"
+QODERWORK_COMMANDS_DIR = _HOME / ".qoderwork" / "commands"
+QODERWORK_MCP_FILE = _HOME / ".qoderwork" / "mcp.json"
+
+# Playwright MCP 配置 (让 QoderWork 的 AI 能用 Playwright 工具驱动浏览器, 快且稳)
+# 可选增强: 不装 playwright 也不影响 QoderWork 自带连接器
+# ⚠️ 实测: npx @playwright/mcp@latest 冷启动 11.7s, QoderWork 会超时杀掉 → 工具注册失败
+#    → AI 瞎猜工具名(BrowserNavigate) → 全失败。
+#    解法: 优先用"全局已装的 cli.js + node 直启"(0.57s), 探测不到才回退 npx。
+def _find_playwright_mcp_cli():
+    """探测全局已装的 @playwright/mcp/cli.js 路径, 返回 (node, cli.js) 或 None。
+    Windows 下 npm 是 .cmd, 必须 shell=True 才能调到。"""
+    import shutil, subprocess
+    node = shutil.which("node")
+    if not node:
+        return None
+    # npm root -g 拿全局 node_modules 路径 (最准, 跨自定义prefix)
+    try:
+        out = subprocess.run("npm root -g", capture_output=True, text=True,
+                             shell=True, timeout=10)
+        root = out.stdout.strip()
+        if root:
+            cli = os.path.join(root, "@playwright", "mcp", "cli.js")
+            if os.path.isfile(cli):
+                return node, cli
+    except Exception:
+        pass
+    # 回退: 试常见全局路径
+    for cand in [os.path.join(os.path.expanduser("~"), "AppData", "Roaming", "npm",
+                              "node_modules", "@playwright", "mcp", "cli.js")]:
+        if os.path.isfile(cand):
+            return node, cand
+    return None
+
+
+def _playwright_mcp_entry():
+    """生成 playwright MCP 配置: 优先 node+cli.js(快), 回退 npx(慢但通用)。"""
+    found = _find_playwright_mcp_cli()
+    if found:
+        node, cli = found
+        return {"playwright": {"command": node, "args": [cli]}}
+    # 回退: npx (冷启动慢, 可能被 QoderWork 超时杀, 但通用)
+    return {"playwright": {"command": "npx", "args": ["@playwright/mcp@latest"]}}
+
+
+PLAYWRIGHT_MCP_ENTRY = _playwright_mcp_entry()
+
+# 旧的错误路径 (迁移清理用)
+LEGACY_WRONG_DIR = _HOME / ".qoderworkcn" / "skills"
+
+
+def is_junction(path: Path) -> bool:
+    """判断目录是否是 junction/symlink（reparse point）。"""
+    if not path.exists():
+        return False
+    # Windows: 用 dir 命令检测 <JUNCTION> 标记最可靠（无需 ctypes）
+    if sys.platform == "win32":
+        try:
+            # os.lstat: reparse point 的 FILE_ATTRIBUTE_REPARSE_POINT (0x400) 会体现在 st_file_attributes
+            import stat as _stat
+            st = path.lstat()
+            # FILE_ATTRIBUTE_REPARSE_POINT = 0x400
+            return bool(getattr(st, "st_file_attributes", 0) & 0x400)
+        except (OSError, AttributeError):
+            return False
+    else:
+        return path.is_symlink()
+
+
+def find_source_skills() -> list:
+    """扫描 .qoder/skills/*/SKILL.md，返回 [(name, src_dir), ...]。"""
+    if not SOURCE_SKILLS_DIR.is_dir():
+        return []
+    result = []
+    for child in sorted(SOURCE_SKILLS_DIR.iterdir()):
+        if not child.is_dir():
+            continue
+        if (child / "SKILL.md").is_file():
+            result.append((child.name, child))
+    return result
+
+
+def file_equal(a: Path, b: Path) -> bool:
+    """快速判断两文件内容是否相同（先比大小再比内容，避免无谓全读）。"""
+    try:
+        if a.stat().st_size != b.stat().st_size:
+            return False
+        return a.read_bytes() == b.read_bytes()
+    except OSError:
+        return False
+
+
+def create_junction(link: Path, target: Path) -> bool:
+    """用 mklink /J 创建 junction。返回是否成功。"""
+    # 用 errors="replace" 防止 Windows GBK 输出（如"为...创建的联接"）触发 UnicodeDecodeError
+    cmd = ["cmd", "/c", "mklink", "/J", str(link), str(target)]
+    try:
+        r = subprocess.run(
+            cmd,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            # 不用 text=True，自己 decode 防编码异常
+        )
+        return r.returncode == 0
+    except (OSError, subprocess.SubprocessError):
+        return False
+
+
+def install_one(name: str, src: Path, mode: str, dry: bool = False) -> str:
+    """
+    安装一个 skill 到 QoderWork 目录。
+    返回状态字符串：'created' / 'ok-existing' / 'copied' / 'error: ...' / 'skip: ...'
+    """
+    link = QODERWORK_SKILLS_DIR / name
+    if link.exists() or link.is_symlink():
+        if is_junction(link):
+            # 悬空 junction 检测: junction 存在但目标已移走/删除
+            # (常见于团队重命名 skill 后, 旧 junction 变成死链)
+            # link.exists() 对悬空 junction 返回 False, 但 link.is_symlink() 可能 True
+            # 用 os.path.exists 解析目标判断
+            try:
+                target_alive = os.path.exists(str(link))
+            except OSError:
+                target_alive = False
+            if target_alive:
+                return "ok-existing"
+            else:
+                # 悬空 junction, 删除后重建
+                if dry:
+                    return "would-recreate (dangling)"
+                try:
+                    if sys.platform == "win32":
+                        subprocess.run(["cmd", "/c", "rmdir", str(link)],
+                                       stdout=subprocess.PIPE, stderr=subprocess.PIPE, check=True)
+                    else:
+                        os.unlink(str(link))
+                except (OSError, subprocess.SubprocessError) as e:
+                    return "error: 悬空 junction 无法删除 (手动 rmdir {}): {}".format(link, e)
+                # 落到下面 recreate 逻辑
+        else:
+            # 非 junction 的真实目录/文件 -> 不覆盖
+            return f"skip: {name} 已存在且不是软链（避免覆盖，请人工确认 {link}）"
+
+    if dry:
+        return "would-create"
+
+    QODERWORK_SKILLS_DIR.mkdir(parents=True, exist_ok=True)
+
+    if mode == "copy":
+        try:
+            shutil.copytree(src, link)
+            return "copied"
+        except (OSError, shutil.Error) as e:
+            return f"error: copy 失败 {e}"
+    else:
+        # junction 模式（默认）
+        if sys.platform != "win32":
+            # 非 Windows 退化为 symlink，失败再退化为 copy
+            try:
+                os.symlink(src, link, target_is_directory=True)
+                return "created(symlink)"
+            except (OSError, NotImplementedError):
+                try:
+                    shutil.copytree(src, link)
+                    return "copied(fallback)"
+                except (OSError, shutil.Error) as e:
+                    return f"error: {e}"
+        if create_junction(link, src):
+            return "created"
+        return "error: mklink /J 失败（可能需要检查路径或权限）"
+
+
+def uninstall_one(name: str) -> str:
+    """删除一个 junction（只删 link，不删源）。"""
+    link = QODERWORK_SKILLS_DIR / name
+    if not link.exists() and not link.is_symlink():
+        return "absent"
+    if not is_junction(link):
+        return f"skip: {name} 不是软链（不动真实目录，请人工删除 {link}）"
+    try:
+        # 删 junction 用 rmdir（不递归到源）
+        if sys.platform == "win32":
+            subprocess.run(["cmd", "/c", "rmdir", str(link)],
+                           stdout=subprocess.PIPE, stderr=subprocess.PIPE, check=True)
+        else:
+            os.unlink(str(link))
+        return "removed"
+    except (OSError, subprocess.SubprocessError) as e:
+        return f"error: {e}"
+
+
+def setup_playwright_mcp(dry=False):
+    """把 Playwright MCP 写进 ~/.qoderwork/mcp.json (可选增强, 不影响自带连接器)。
+
+    让 QoderWork 的 AI 能用 Playwright 工具(browser_navigate/click/type/screenshot)
+    驱动浏览器 —— 快(10s级 vs 自带连接器 5-8分钟)、稳(不折腾 tab)、不依赖扩展。
+    已有 playwright 配置则跳过(幂等); 没有则追加。
+    """
+    import json
+    mcp_path = QODERWORK_MCP_FILE
+    # 读现有配置
+    existing = {}
+    if mcp_path.is_file():
+        try:
+            existing = json.loads(mcp_path.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 = {}
+    if "playwright" in servers:
+        # 已有配置: 若是旧的 npx@latest(慢, 易超时失败), 升级成 node+cli.js(快)
+        cur = servers["playwright"]
+        if cur.get("command") == "npx":
+            new_entry = PLAYWRIGHT_MCP_ENTRY["playwright"]
+            if new_entry.get("command") != "npx":  # 探测到了 cli.js
+                if dry:
+                    return "would-upgrade"
+                servers["playwright"] = new_entry
+                existing["mcpServers"] = servers
+                mcp_path.write_text(json.dumps(existing, indent=2, ensure_ascii=False), encoding="utf-8")
+                return "upgraded"
+        return "ok-existing"
+    if dry:
+        return "would-add"
+    # 追加 playwright
+    servers["playwright"] = PLAYWRIGHT_MCP_ENTRY["playwright"]
+    existing["mcpServers"] = servers
+    mcp_path.parent.mkdir(parents=True, exist_ok=True)
+    mcp_path.write_text(
+        json.dumps(existing, indent=2, ensure_ascii=False) + "\n",
+        encoding="utf-8",
+    )
+    return "added"
+
+
+def setup_lanhu_mcp(dry=False):
+    """注册蓝湖 MCP 到 ~/.qoderwork/mcp.json (可选增强, 设计稿直读)。
+
+    蓝湖 MCP (dsphper/lanhu-mcp) 是第三方 HTTP server, 让设计师发蓝湖链接,
+    AI 直读设计稿(颜色/尺寸/字体/切图)。注册成 url 模式 (Streamable HTTP),
+    跟 playwright/kg/mysql 这些 stdio server 并列。
+
+    注意: 蓝湖是 HTTP server, 需要用户手动启动
+      python .qoder/scripts/setup_lanhu.py start
+    (启动脚本自动读当前开发者的 cookie 注入, 不用手动配 .env)
+    本函数只注册 url (幂等), 不负责 clone/装依赖/启动 —— 那些由 setup_lanhu.py
+    在 setup.py Step 4.5 完成。这里只做 mcp.json 条目同步, 保证团队所有人
+    跑 install_qoderwork 后都能看到蓝湖 server。
+
+    返回: 'ok-existing' / 'added' / 'would-add'
+    """
+    # 复用 setup_lanhu.py 的注册逻辑 (单一事实源)
+    try:
+        sys.path.insert(0, str(SCRIPT_DIR))
+        from setup_lanhu import register_lanhu_mcp
+    except ImportError:
+        return 'would-add'
+    return register_lanhu_mcp(developer_name='Developer', dry=dry)
+
+
+def detect_python_command():
+    """探测本机可用的 python 命令名 (跨平台), 用于写进 mcp.json 的 command 字段。
+
+    ⚠️ 关键约束: 返回值必须是单个可执行文件名/路径, 不能含空格或参数。
+    旧版返回 'py -3' (带参数), MCP 客户端 spawn('py -3', args) 会把
+    'py -3' 当字面文件名 → 找不到可执行文件 → MCP 显示黄色(连接失败)。
+
+    优先级 (Windows): python > py > python3
+      - 故意把 python 放 py 前面: 'python' 是单文件名, 最稳;
+        'py' 需要配合 -3 参数, 但我们返回纯 'py' (不带 -3) 也通常能用
+        (py 启动器会选默认版本)。
+    优先级 (mac/linux): python3 > python
+
+    返回: 命令名字符串 (如 'python' / 'py' / 'python3'), 失败返回 None。
+    """
+    if sys.platform == 'win32':
+        candidates = ('python', 'py', 'python3')
+    else:
+        candidates = ('python3', 'python')
+    for name in candidates:
+        if not shutil.which(name):
+            continue
+        try:
+            r = subprocess.run([name, '--version'], capture_output=True, text=True,
+                               encoding='utf-8', errors='replace')
+            if r.returncode == 0:
+                return name  # 纯命令名, 不带参数
+        except (OSError, subprocess.SubprocessProcessError):
+            continue
+    return None
+
+
+def find_python_with_core_deps():
+    """找一个装了核心依赖 (duckdb/pymysql/yaml/requests) 的 Python 可执行文件。
+
+    用于写 mcp.json: 如果某个 Python 已经装了核心依赖, 直接用它当 command,
+    launcher 启动后 _find_python_with_deps 会秒命中 sys.executable, 不用再遍历。
+    解决"多 Python 共存, 装到了 A 但 mcp.json 指向 B"的常见问题。
+
+    返回: python 可执行文件路径(str) 或 None(没找到装了依赖的)。
+    """
+    # 先测当前 Python (install_qoderwork 正在跑的这个)
+    for mod in ('duckdb', 'pymysql', 'yaml', 'requests'):
+        try:
+            __import__(mod)
+        except ImportError:
+            break
+    else:
+        # 当前 Python 四个核心依赖都有 → 用它
+        return sys.executable
+
+    # 当前 Python 没装全, 找其它 Python
+    for name in ('python', 'python3', 'py'):
+        p = shutil.which(name)
+        if not p or p == sys.executable:
+            continue
+        try:
+            r = subprocess.run(
+                [p, '-c', 'import duckdb, pymysql, yaml, requests'],
+                capture_output=True, timeout=8)
+            if r.returncode == 0:
+                return p
+        except (OSError, subprocess.SubprocessProcessError):
+            continue
+    return None
+
+
+def rewrite_mcp_json_for_launcher():
+    """把 mcp.json 里所有 python MCP (kg/mysql/lanhu) 改成 launcher 模式。
+
+    ★ kg 走云平台 SSE url（共识），不走 launcher——在 for srv 循环已配 SSE，
+      这里跳过 kg（不改 launcher），保住 SSE 配置。
+
+    旧 (写死路径): {"command": "E:\\...\\python.exe", "args": ["E:\\...\\server.py"]}
+    新 (launcher): {"command": "<py cmd>", "args": ["<home>/.qoderwork/mcp_launcher.py", "<name>"]}
+
+    幂等: 已是 launcher 模式 (args 含 mcp_launcher.py) 则跳过。
+    全新机器: mcp.json 不存在时创建空骨架 + 写入 kg/mysql/lanhu 条目。
+    mysql env 抽到 ~/.qoderwork/.mcp-mysql-env.json (launcher 读)。
+    """
+    # 全新机器: mcp.json 不存在 → 创建空骨架 (playwright 后续会追加)
+    if not QODERWORK_MCP_FILE.is_file():
+        QODERWORK_MCP_FILE.parent.mkdir(parents=True, exist_ok=True)
+        QODERWORK_MCP_FILE.write_text(
+            '{"mcpServers": {}}\n', encoding="utf-8")
+    try:
+        cfg = json.loads(QODERWORK_MCP_FILE.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError):
+        return
+    servers = cfg.get("mcpServers", {})
+    if not isinstance(servers, dict):
+        return
+
+    # 选 Python 写进 mcp.json:
+    # v3.0 修复: 用装了核心依赖的 Python 绝对路径 (不用命令名)!
+    # 原因: QoderWork 桌面应用不继承 shell PATH, 命令名(python/py -3)找不到 → 黄灯。
+    # 绝对路径每次 install 时探测, 换机器重跑 update 自动刷新。
+    # 依赖查找: 先找装了 duckdb 的 python (find_python_with_core_deps),
+    # 找不到回退 detect_python_command。
+    # ⚠ find_python_with_core_deps 返回 None (不抛异常) 时, 旧代码因 try/except
+    #   捕不到 → py_cmd 留 None → mcp.json 写 "command": null → QoderWork 起 MCP
+    #   失败变黄。这里显式 None 判断 + 多级回退, 绝不写 null。
+    py_cmd = find_python_with_core_deps()
+    if not py_cmd:
+        py_cmd = detect_python_command() or sys.executable or "python"
+    launcher = str(_HOME / ".qoderwork" / "mcp_launcher.py")
+    # MCP 名 → launcher 子命令
+    name_map = {
+        "qoder-knowledge-graph": "kg",
+        "qoder-mysql": "mysql",
+        "qoder-zentao": "zentao",
+        "lanhu": "lanhu",
+    }
+    changed = False
+    for srv, sub in name_map.items():
+        # 共识：kg 走云平台（默认 http://10.87.106.252/mcp，config platform_mcp.url 可覆盖）
+        if srv == "qoder-knowledge-graph":
+            _pm = "http://10.87.106.252/mcp"
+            try:
+                import yaml as _y
+                _cfg_p = get_repo_root() / ".qoder" / "config.yaml"
+                if _cfg_p.is_file():
+                    _cfg = _y.safe_load(_cfg_p.read_text(encoding="utf-8")) or {}
+                    _pm = (_cfg.get("platform_mcp") or {}).get("url", "") or _pm
+            except Exception:
+                pass
+            servers[srv] = {"url": _pm, "type": "sse", "enabled": True}
+            changed = True
+            continue
+        entry = servers.get(srv)
+        # 全新机器: kg/mysql/lanhu 条目可能不存在 → 创建它 (launcher 模式)
+        if not entry:
+            servers[srv] = {"command": py_cmd, "args": [launcher, sub], "enabled": True}
+            changed = True
+            continue
+        # 已是 launcher 模式? 检查 command 是否需要更新 (Python 路径可能变了)
+        args = entry.get("args", []) if isinstance(entry, dict) else []
+        if args and any("mcp_launcher.py" in str(a) for a in args):
+            # launcher 模式, 但 command 可能指向旧的/错的 Python → 更新
+            old_cmd = entry.get("command", "") if isinstance(entry, dict) else ""
+            if old_cmd != py_cmd:
+                servers[srv] = {"command": py_cmd, "args": [launcher, sub], "enabled": True}
+                changed = True
+            # 补 enabled (旧版可能没写, 导致黄灯)
+            if isinstance(entry, dict) and not entry.get("enabled"):
+                entry["enabled"] = True
+                changed = True
+            continue
+        # mysql env 抽离到独立文件
+        if srv == "qoder-mysql" and isinstance(entry, dict) and entry.get("env"):
+            env_file = _HOME / ".qoderwork" / ".mcp-mysql-env.json"
+            try:
+                env_file.write_text(json.dumps(entry["env"], indent=2, ensure_ascii=False) + "\n",
+                                    encoding="utf-8")
+            except OSError:
+                pass
+        # 改成 launcher 模式
+        servers[srv] = {"command": py_cmd, "args": [launcher, sub], "enabled": True}
+        changed = True
+
+    if changed:
+        cfg["mcpServers"] = servers
+        try:
+            QODERWORK_MCP_FILE.write_text(
+                json.dumps(cfg, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+            print(f"\n--- mcp.json 重写为 launcher 模式 ---")
+            print(f"  [UPD]  kg/mysql/zentao/lanhu → command={py_cmd} (命令名, 跨机器通用)")
+            print(f"         args=[mcp_launcher.py, <名>] (launcher 内部找装依赖的 Python)")
+            print(f"         不再写死绝对路径, 换机器/重装Python不会失效")
+        except OSError as e:
+            print(f"  [ERR]  mcp.json 重写失败: {e}")
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="把 .qoder/skills/ 安装到 QoderWork 桌面端目录"
+    )
+    parser.add_argument("--uninstall", action="store_true",
+                        help="删除所有 junction（不删源）")
+    parser.add_argument("--check", action="store_true",
+                        help="仅检查状态，不改动")
+    parser.add_argument("--copy", action="store_true",
+                        help="用拷贝代替 junction（非 Windows 或不想软链时用）")
+    parser.add_argument("--force-commands", action="store_true",
+                        help="强制覆盖已存在的 command 文件（升级时用；默认已存在则跳过）")
+    parser.add_argument("--mcp-only", action="store_true",
+                        help="只刷新 launcher + mcp.json，不装 skill（update 时调）")
+    args = parser.parse_args()
+
+    # --mcp-only: 轻量模式, 只刷 launcher + mcp.json, 不装 skill
+    if args.mcp_only:
+        print("=" * 56)
+        print("MCP 配置刷新 (--mcp-only)")
+        print("=" * 56)
+        # 1. 复制 launcher
+        launcher_src = SOURCE_COMMANDS_DIR.parent / "scripts" / "protocol" / "mcp" / "mcp_launcher.py"  # v3.0: protocol/mcp子包
+        launcher_dst = _HOME / ".qoderwork" / "mcp_launcher.py"
+        try:
+            launcher_dst.parent.mkdir(parents=True, exist_ok=True)
+            if launcher_src.is_file():
+                import shutil as _sh
+                _sh.copy2(str(launcher_src), str(launcher_dst))
+                print(f"  [OK]   launcher 已刷新: {launcher_dst}")
+            else:
+                print(f"  [ERR]  源不存在: {launcher_src}")
+        except OSError as e:
+            print(f"  [ERR]  复制失败: {e}")
+        # 2. 重写 mcp.json 为 launcher 模式 (创建 kg/mysql/lanhu)
+        rewrite_mcp_json_for_launcher()
+        # 3. 补 playwright (rewrite 不含它)
+        try:
+            setup_playwright_mcp(dry=False)
+        except Exception:
+            pass
+        # 4. 写 .repo-root 锚点 (launcher 定位仓库根用)
+        # 防御: 二次验证 PROJECT_ROOT 是"真仓库" (有 workspace/data/.git),
+        #       防止测试在临时目录跑 install 污染全局 .repo-root。
+        is_real_repo = any((PROJECT_ROOT / m).exists() for m in ('workspace', 'data', '.git'))
+        anchor = _HOME / ".qoderwork" / ".repo-root"
+        try:
+            anchor.parent.mkdir(parents=True, exist_ok=True)
+            if is_real_repo:
+                anchor.write_text(str(PROJECT_ROOT), encoding="utf-8")
+                print(f"  [OK]   .repo-root 锚点: {anchor} -> {PROJECT_ROOT}")
+            else:
+                print(f"  [SKIP] .repo-root 未更新 ({PROJECT_ROOT} 非真仓库, 缺 workspace/data/.git)")
+        except OSError:
+            pass
+        # 5. 复制 wlkj 薄壳 (QoderWork 桌面端任意 cwd 直跑 wlkj, 不用每次先算 R)
+        # 治"相对路径在会话临时 cwd 失效"踩坑 (真实: 连续 2 条命令报错浪费一轮)
+        shim_src = SOURCE_COMMANDS_DIR.parent / "scripts" / "deployment" / "setup" / "wlkj_shim.py"
+        shim_dst = _HOME / ".qoderwork" / "wlkj.py"
+        try:
+            if shim_src.is_file():
+                import shutil as _sh2
+                _sh2.copy2(str(shim_src), str(shim_dst))
+                print(f"  [OK]   wlkj 薄壳: {shim_dst} (任意 cwd 可跑: python ~/.qoderwork/wlkj.py ...)")
+        except OSError as e:
+            print(f"  [ERR]  wlkj 薄壳复制失败: {e}")
+        return
+
+    print("=" * 56)
+    print("QoderWork 技能安装器")
+    print(f"  源:   {SOURCE_SKILLS_DIR}")
+    print(f"  目标: {QODERWORK_SKILLS_DIR}")
+    print("=" * 56)
+
+    # 迁移清理: 旧版本错装到了 ~/.qoderworkcn/, 清理掉避免混淆
+    if not args.check and LEGACY_WRONG_DIR.exists():
+        legacy_junctions = []
+        try:
+            for child in LEGACY_WRONG_DIR.iterdir():
+                if is_junction(child):
+                    legacy_junctions.append(child.name)
+        except OSError:
+            pass
+        if legacy_junctions:
+            print(f"\n[迁移] 发现旧版本错装在 {LEGACY_WRONG_DIR} ({len(legacy_junctions)} 个)")
+            print(f"       QoderWork 实际读的是 ~/.qoderwork/, 正在清理旧 junction...")
+            for name in legacy_junctions:
+                try:
+                    subprocess.run(["cmd", "/c", "rmdir", str(LEGACY_WRONG_DIR / name)],
+                                   stdout=subprocess.PIPE, stderr=subprocess.PIPE, check=True)
+                except (OSError, subprocess.SubprocessError):
+                    pass
+            print(f"       已清理 {len(legacy_junctions)} 个旧 junction")
+            # 若旧目录空了, 删掉
+            try:
+                remaining = list(LEGACY_WRONG_DIR.iterdir())
+                if not remaining and LEGACY_WRONG_DIR.parent.exists():
+                    LEGACY_WRONG_DIR.rmdir()
+                    print(f"       已删除空目录 {LEGACY_WRONG_DIR.parent}")
+            except OSError:
+                pass
+
+    sources = find_source_skills()
+    if not sources:
+        print(f"[ERR] 源目录无 skill：{SOURCE_SKILLS_DIR}")
+        print("      检查 .qoder/skills/*/SKILL.md 是否存在")
+        return 1
+
+    mode = "copy" if args.copy else "junction"
+    action = "check" if args.check else ("uninstall" if args.uninstall else "install")
+    print(f"\n模式: {action} / link={mode}，发现 {len(sources)} 个源 skill\n")
+
+    results = {}
+    for name, src in sources:
+        if action == "uninstall":
+            results[name] = uninstall_one(name)
+        elif action == "check":
+            link = QODERWORK_SKILLS_DIR / name
+            if link.exists() or link.is_symlink():
+                results[name] = "ok(junction)" if is_junction(link) else "WARN(非软链)"
+            else:
+                results[name] = "missing"
+        else:  # install
+            results[name] = install_one(name, src, mode, dry=False)
+
+    # 打印结果
+    print("-" * 56)
+    counts = {"ok": 0, "create": 0, "copy": 0, "warn": 0, "err": 0, "missing": 0}
+    for name, status in sorted(results.items()):
+        tag = ""
+        if status.startswith("ok") or status == "copied" or status.startswith("created"):
+            if status.startswith("created") or status == "copied":
+                counts["create"] += 1
+                tag = "[NEW]"
+            else:
+                counts["ok"] += 1
+                tag = "[OK]"
+        elif status.startswith("skip"):
+            counts["warn"] += 1
+            tag = "[WARN]"
+        elif status.startswith("error"):
+            counts["err"] += 1
+            tag = "[ERR]"
+        elif status == "missing":
+            counts["missing"] += 1
+            tag = "[MISS]"
+        elif status == "removed":
+            counts["ok"] += 1
+            tag = "[DEL]"
+        elif status.startswith("WARN"):
+            counts["warn"] += 1
+            tag = "[WARN]"
+        else:
+            counts["ok"] += 1
+            tag = "[OK]"
+        print(f"  {tag:6} {name:22} {status}")
+
+    print("-" * 56)
+    print(f"\n小结: 新建 {counts['create']} / 已存在 {counts['ok']} / "
+          f"缺失 {counts['missing']} / 警告 {counts['warn']} / 错误 {counts['err']}")
+
+    # 同时安装 commands (让 QoderWork 用户级也能看到 /wl-* 命令)
+    if action in ("install", "check") and SOURCE_COMMANDS_DIR.is_dir():
+        print("\n--- Commands (/wl-* 斜杠命令) ---")
+        cmd_count = {"ok": 0, "new": 0, "upd": 0}
+        for cmd_file in sorted(SOURCE_COMMANDS_DIR.rglob("*.md")):
+            name = cmd_file.name  # e.g. wl-prd.md (子目录归类的也平铺到目标)
+            target = QODERWORK_COMMANDS_DIR / name
+            if action == "check":
+                if target.exists():
+                    cmd_count["ok"] += 1
+                else:
+                    print(f"  [MISS] {name}")
+            else:  # install
+                need_copy = False
+                is_update = False
+                if not target.exists():
+                    need_copy = True
+                else:
+                    # 始终按内容同步(幂等): 不同就刷新。
+                    # command 是纯文本小文件, 内容不同说明源已升级, 必须覆盖,
+                    # 否则 QoderWork 用旧 command → 走错流程(如旧 wl-test 搜代码)。
+                    if not file_equal(cmd_file, target):
+                        need_copy = True
+                        is_update = True
+                if need_copy:
+                    try:
+                        QODERWORK_COMMANDS_DIR.mkdir(parents=True, exist_ok=True)
+                        shutil.copy2(str(cmd_file), str(target))
+                        if is_update:
+                            cmd_count["upd"] += 1
+                        else:
+                            cmd_count["new"] += 1
+                    except OSError as e:
+                        print(f"  [ERR] {name}: {e}")
+                else:
+                    cmd_count["ok"] += 1
+        msg = f"  commands: {cmd_count['new']} 新建 / {cmd_count['ok']} 已存在"
+        if cmd_count["upd"]:
+            msg += f" / {cmd_count['upd']} 刷新"
+        print(msg)
+
+    # === 2.5. repo_root.py (QoderWork 桌面端仓库根定位器) ===
+    # QoderWork 桌面端工作目录是临时会话目录, 不是仓库根, 相对路径失效。
+    # repo_root.py 从 mcp.json 反推仓库根, 命令文件靠它定位脚本/模板。
+    if action in ("install", "check"):
+        repo_root_src = SOURCE_COMMANDS_DIR.parent / "scripts" / "deployment" / "setup" / "repo_root.py"  # v3.0: deployment/setup子包
+        repo_root_dst = _HOME / ".qoderwork" / "repo_root.py"
+        if repo_root_src.is_file():
+            if action == "check":
+                if repo_root_dst.exists():
+                    print(f"\n--- repo_root.py (仓库根定位器) ---")
+                    print(f"  [OK]   {repo_root_dst}")
+                else:
+                    print(f"\n--- repo_root.py (仓库根定位器) ---")
+                    print(f"  [MISS] 未安装到 {repo_root_dst}")
+            else:
+                try:
+                    repo_root_dst.parent.mkdir(parents=True, exist_ok=True)
+                    shutil.copy2(str(repo_root_src), str(repo_root_dst))
+                    print(f"\n--- repo_root.py (仓库根定位器) ---")
+                    print(f"  [OK]   已安装: {repo_root_dst}")
+                except OSError as e:
+                    print(f"\n--- repo_root.py (仓库根定位器) ---")
+                    print(f"  [ERR]  {e}")
+
+    # === 2.6. mcp_launcher.py + .repo-root (统一 MCP 启动器, 消除写死路径) ===
+    # mcp_launcher.py 让 mcp.json 不再写死仓库路径/venv路径, 跨 Win/Mac 通用。
+    # .repo-root 锚点文件让 launcher 能定位仓库根 (不依赖 mcp.json 里的路径)。
+    if action in ("install", "check"):
+        print(f"\n--- mcp_launcher.py (统一 MCP 启动器) ---")
+        launcher_src = SOURCE_COMMANDS_DIR.parent / "scripts" / "protocol" / "mcp" / "mcp_launcher.py"  # v3.0: protocol/mcp子包
+        launcher_dst = _HOME / ".qoderwork" / "mcp_launcher.py"
+        anchor_dst = _HOME / ".qoderwork" / ".repo-root"
+        if action == "check":
+            if launcher_dst.exists():
+                print(f"  [OK]   launcher 已装: {launcher_dst}")
+            else:
+                print(f"  [MISS] launcher 未装")
+            if anchor_dst.exists():
+                print(f"  [OK]   .repo-root 锚点在: {anchor_dst}")
+            else:
+                print(f"  [MISS] .repo-root 锚点缺失 (launcher 会回退向上找)")
+        else:
+            try:
+                launcher_dst.parent.mkdir(parents=True, exist_ok=True)
+                if launcher_src.is_file():
+                    shutil.copy2(str(launcher_src), str(launcher_dst))
+                    print(f"  [OK]   launcher 已装: {launcher_dst}")
+                else:
+                    print(f"  [ERR]  源不存在: {launcher_src}")
+                # 写 .repo-root 锚点 (记录当前仓库根, launcher 读它定位)
+                anchor_dst.write_text(str(PROJECT_ROOT) + "\n", encoding="utf-8")
+                print(f"  [OK]   .repo-root 锚点已写: {PROJECT_ROOT}")
+            except OSError as e:
+                print(f"  [ERR]  {e}")
+
+    # === 2.7. 重写 mcp.json: 所有 python MCP 改 launcher 模式 (消除写死路径) ===
+    if action == "install":
+        rewrite_mcp_json_for_launcher()
+
+    # === 3. Playwright MCP (可选增强: 让 QoderWork 能用 Playwright 驱动浏览器) ===
+    if action in ("install", "check"):
+        print("\n--- Playwright MCP (浏览器自动化增强, 可选) ---")
+        pw_status = setup_playwright_mcp(dry=(action == "check"))
+        if pw_status == "ok-existing":
+            print(f"  [OK]   playwright MCP 已配置: {QODERWORK_MCP_FILE}")
+        elif pw_status == "added":
+            print(f"  [NEW]  已写入 playwright MCP: {QODERWORK_MCP_FILE}")
+            print("         QoderWork 重启后, AI 可用 Playwright 工具驱动浏览器(快、稳)")
+        elif pw_status == "upgraded":
+            print(f"  [FIX]  playwright MCP 已升级: npx(慢,易超时) → node+cli.js(0.5s启动)")
+            print("         ⚠️ 必须 重启 QoderWork 生效。旧 npx 配置会被 QoderWork 超时杀掉导致工具注册失败")
+        elif pw_status == "would-upgrade":
+            print(f"  [FIX]  检测到旧 npx 配置(慢), 安装时会升级为 node+cli.js")
+        elif pw_status == "would-add":
+            print(f"  [MISS] 未配置 playwright MCP, 安装时会写入 {QODERWORK_MCP_FILE}")
+        # 检查 playwright mcp 是否已装(优先看 cli.js, 决定能否走快路径)
+        pw_cli = _find_playwright_mcp_cli()
+        if pw_cli:
+            print(f"  启动方式: node + cli.js (0.5s, 快) ← {pw_cli[1]}")
+        else:
+            npx_ok = shutil.which("npx") is not None
+            print(f"  启动方式: {'npx (11s冷启动, 可能被QoderWork超时杀)' if npx_ok else '✗ 未装 Node.js'}")
+            if npx_ok:
+                print("  提示: 装 @playwright/mcp 全局后重跑本脚本, 会自动切换到快的 node 启动: npm i -g @playwright/mcp")
+
+    # === 4. 蓝湖 MCP (可选增强: 设计师发蓝湖链接, AI 直读设计稿) ===
+    if action in ("install", "check"):
+        print("\n--- 蓝湖 MCP (设计稿直读增强, 可选) ---")
+        lh_status = setup_lanhu_mcp(dry=(action == "check"))
+        if lh_status == "ok-existing":
+            print(f"  [OK]   蓝湖 MCP 已注册: {QODERWORK_MCP_FILE}")
+        elif lh_status == "added":
+            print(f"  [NEW]  已写入蓝湖 MCP (STDIO): {QODERWORK_MCP_FILE}")
+            print("         QoderWork 开自动起、关自动停; 命令内授权调 mcp__lanhu__*")
+        elif lh_status == "upgraded":
+            print(f"  [UPD]  蓝湖 MCP 升级 HTTP→STDIO: {QODERWORK_MCP_FILE}")
+            print("         重启 QoderWork 后自动开关, 无需手动 start")
+        elif lh_status == "would-add":
+            print(f"  [MISS] 未注册蓝湖 MCP, 安装时会写入 {QODERWORK_MCP_FILE}")
+        # STDIO 模式由 QoderWork 自动管, 不查端口; 只确认 wrapper + 源码就绪
+        wrapper = PROJECT_ROOT / ".qoder" / "scripts" / "protocol" / "mcp" / "lanhu_stdio_wrapper.py"
+        lanhu_dir = PROJECT_ROOT / "external" / "lanhu-mcp"
+        if wrapper.is_file():
+            print(f"  wrapper 就绪: {wrapper.name} (按角色读 cookie)")
+        else:
+            print(f"  [MISS] wrapper 缺失: {wrapper}")
+        if not lanhu_dir.is_dir():
+            print("  蓝湖源码: 未 clone (跑 setup.py 或 setup_lanhu.py 安装)")
+
+    if action == "install" and counts["err"] == 0:
+        print("\n✓ 安装完成。重启 QoderWork（或新建对话）后技能生效。")
+        print("  在 QoderWork 里直接用自然语言即可，例如：")
+        print('    "写个保险异常筛选的 PRD"  -> /wl-prd（正经需求, 完整档）')
+        print('    "列表加个导出按钮"       -> /wl-prd（小改动, 自动走快速档）')
+        print('    "查一下考勤代码在哪"      -> /wl-search')
+    elif action == "install" and counts["err"] > 0:
+        print(f"\n⚠ 有 {counts['err']} 个安装失败，见上方 [ERR] 行。")
+        print("  常见原因: 目标路径被占用为非软链。手动删除该目录后重跑本脚本。")
+        return 1
+    elif action == "uninstall":
+        print("\n✓ 卸载完成（源文件未动）。")
+    elif action == "check":
+        if counts["missing"] > 0 or counts["warn"] > 0:
+            print("\n⚠ 检测到缺失/异常，建议跑: python .qoder/scripts/install_qoderwork.py")
+            return 1
+        else:
+            print("\n✓ 全部 skill 已正确安装到 QoderWork 目录。")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())