@hupan56/wlkj 2.7.12 → 3.0.0

package/templates/qoder/scripts/{check_mcp.py → mcp/mcp_doctor.py}

@@ -1,298 +1,515 @@
-#!/usr/bin/env python3
-# -*- coding: utf-8 -*-
-"""
-check_mcp.py - MCP 启动健康检查 (验证 init/download 后全系列可用)
-
-为什么需要它:
-  install_qoderwork.py --mcp-only 会写 mcp.json + launcher, 但"写了配置"不等于
-  "MCP 能起来"。50 人里有人 pip 没装齐、有人 .repo-root 写错、有人 lanhu venv 没建,
-  这些都要等用的时候才发现 MCP 挂了。本脚本主动验证每个 MCP 能否真正启动。
-
-  对应需求: "确保 MCP 等 init/download 后, 所有人 qoder 全系列正常运行"。
-
-检查什么 (不真启动 server, 只验证启动条件):
-  1. mcp.json 存在 + 各 server 注册了 launcher 模式
-  2. launcher 能定位仓库根 (.repo-root 锚点 / 环境变量 / 向上找)
-  3. 各 MCP 的依赖就绪:
-     - kg:    装了 duckdb 的 Python + kg_mcp_server.py 存在
-     - mysql: 装了 pymysql 的 Python + config.yaml 有 mysql 段
-     - lanhu: venv 建了 + 当前角色 cookie 配了
-     - playwright: node 在 + cli.js / npx 可用
-
-Usage:
-    python .qoder/scripts/check_mcp.py            # 全量检查
-    python .qoder/scripts/check_mcp.py --fix      # 检查 + 尝试修复 (.repo-root 等)
-Exit: 0 = 全部就绪, 1 = 有 MCP 未就绪
-"""
-import json
-import os
-import subprocess
-import sys
-from pathlib import Path
-
-if sys.platform == 'win32':
-    try:
-        sys.stdout.reconfigure(encoding='utf-8')
-    except (AttributeError, IOError):
-        pass
-
-sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
-from common.paths import get_repo_root
-
-BASE = get_repo_root()
-HOME = Path(os.environ.get('USERPROFILE') or os.path.expanduser('~'))
-QODERWORK_DIR = HOME / '.qoderwork'
-MCP_FILE = QODERWORK_DIR / 'mcp.json'
-REPO_ROOT_ANCHOR = QODERWORK_DIR / '.repo-root'
-
-OK_TAG = '[OK]  '
-WARN_TAG = '[WARN]'
-MISS_TAG = '[MISS]'
-BAD_TAG = '[BAD] '
-
-issues = []
-
-
-def say(tag, msg):
-    print('{} {}'.format(tag, msg))
-
-
-def problem(msg, hint=None):
-    issues.append(msg)
-    say(BAD_TAG, msg)
-    if hint:
-        print('       -> ' + hint)
-
-
-def _run(cmd, timeout=10):
-    """跑命令, 返回 (returncode, output)。"""
-    try:
-        r = subprocess.run(cmd, capture_output=True, text=True,
-                           encoding='utf-8', errors='replace', timeout=timeout)
-        return r.returncode, (r.stdout or '') + (r.stderr or '')
-    except (subprocess.TimeoutExpired, FileNotFoundError, OSError):
-        return 1, ''
-
-
-def _find_python_with(mod):
-    """找一个装了指定模块的 Python。返回路径或 None。"""
-    # 当前 Python
-    try:
-        __import__(mod)
-        return sys.executable
-    except ImportError:
-        pass
-    # 其他 Python
-    import shutil
-    for name in ('python', 'python3', 'py'):
-        p = shutil.which(name)
-        if p and p != sys.executable:
-            rc, _ = _run([p, '-c', 'import %s' % mod], timeout=8)
-            if rc == 0:
-                return p
-    return None
-
-
-# ============================================================
-# 检查项
-# ============================================================
-
-def check_mcp_json(fix=False):
-    """1. mcp.json 存在 + launcher 模式。"""
-    print('\n--- 1. mcp.json 配置 ---')
-    if not MCP_FILE.is_file():
-        problem('mcp.json 不存在 (%s)' % MCP_FILE,
-                '跑: python .qoder/scripts/install_qoderwork.py --mcp-only')
-        return False
-    try:
-        cfg = json.loads(MCP_FILE.read_text(encoding='utf-8'))
-    except (ValueError, OSError):
-        problem('mcp.json 解析失败', '文件损坏, 重跑 install_qoderwork.py --mcp-only')
-        return False
-    servers = cfg.get('mcpServers', {})
-    if not servers:
-        problem('mcp.json 无 mcpServers', '重跑 install_qoderwork.py --mcp-only')
-        return False
-    say(OK_TAG, 'mcp.json 存在, 注册了 %d 个 server: %s' % (
-        len(servers), ', '.join(servers.keys())))
-    # 检查是否 launcher 模式 (command 用 mcp_launcher.py)
-    launcher_count = 0
-    for name, entry in servers.items():
-        args = entry.get('args', []) if isinstance(entry, dict) else []
-        if any('mcp_launcher.py' in str(a) for a in args):
-            launcher_count += 1
-    if launcher_count > 0:
-        say(OK_TAG, '%d 个 server 用 launcher 模式 (跨机器通用)' % launcher_count)
-    else:
-        say(WARN_TAG, '无 launcher 模式 server (可能写死路径), 升级: install_qoderwork.py --mcp-only')
-    return True
-
-
-def check_repo_root(fix=False):
-    """2. launcher 能定位仓库根 (.repo-root 锚点)。"""
-    print('\n--- 2. 仓库根定位 ---')
-    if REPO_ROOT_ANCHOR.is_file():
-        try:
-            root_val = REPO_ROOT_ANCHOR.read_text(encoding='utf-8').strip()
-            if (Path(root_val) / '.qoder' / 'scripts').is_dir():
-                say(OK_TAG, '.repo-root 锚点正确: %s' % root_val)
-                return True
-            else:
-                problem('.repo-root 指向的目录不是仓库根: %s' % root_val,
-                        '重跑 install_qoderwork.py --mcp-only 会用 PROJECT_ROOT 修正')
-        except OSError:
-            pass
-    # 锚点缺失或错误
-    if fix:
-        try:
-            REPO_ROOT_ANCHOR.parent.mkdir(parents=True, exist_ok=True)
-            REPO_ROOT_ANCHOR.write_text(str(BASE), encoding='utf-8')
-            say(OK_TAG, '.repo-root 锚点已修复: %s -> %s' % (REPO_ROOT_ANCHOR, BASE))
-            return True
-        except OSError as e:
-            problem('修复 .repo-root 失败: %s' % e)
-    else:
-        problem('.repo-root 锚点缺失或错误',
-                '加 --fix 自动修复, 或重跑 install_qoderwork.py --mcp-only')
-    return False
-
-
-def check_launcher_file(fix=False):
-    """3. launcher 脚本存在于 ~/.qoderwork/。"""
-    print('\n--- 3. MCP launcher ---')
-    launcher = QODERWORK_DIR / 'mcp_launcher.py'
-    if launcher.is_file():
-        say(OK_TAG, 'launcher 存在: %s' % launcher)
-        return True
-    problem('launcher 不存在: %s' % launcher,
-            '重跑 install_qoderwork.py --mcp-only (会复制 launcher)')
-    return False
-
-
-def check_kg():
-    """4. kg MCP: duckdb + kg_mcp_server.py。"""
-    print('\n--- 4. 知识图谱 MCP (kg) ---')
-    server = BASE / '.qoder' / 'scripts' / 'kg_mcp_server.py'
-    if not server.is_file():
-        problem('kg_mcp_server.py 不存在', '引擎不完整, 重跑 npx wlkj update')
-        return
-    py = _find_python_with('duckdb')
-    if py:
-        say(OK_TAG, 'kg 就绪 (python=%s, 装了 duckdb)' % py)
-    else:
-        problem('找不到装了 duckdb 的 Python',
-                'pip install duckdb 或 npx @hupan56/wlkj install-env')
-
-
-def check_mysql():
-    """5. mysql MCP: pymysql + config.yaml mysql 段。"""
-    print('\n--- 5. MySQL MCP ---')
-    server = BASE / '.qoder' / 'scripts' / 'mysql_mcp_server.py'
-    if not server.is_file():
-        problem('mysql_mcp_server.py 不存在')
-        return
-    py = _find_python_with('pymysql')
-    if not py:
-        problem('找不到装了 pymysql 的 Python', 'pip install pymysql')
-        return
-    # config.yaml mysql 段
-    cfg_path = BASE / '.qoder' / 'config.yaml'
-    has_mysql = False
-    if cfg_path.is_file():
-        try:
-            import yaml
-            d = yaml.safe_load(cfg_path.read_text(encoding='utf-8')) or {}
-            has_mysql = bool(d.get('mysql', {}).get('host'))
-        except Exception:
-            pass
-    if has_mysql:
-        say(OK_TAG, 'mysql 就绪 (config.yaml 已配连接信息)')
-    else:
-        say(WARN_TAG, 'mysql 依赖就绪, 但 config.yaml 无 mysql 段 (按需配)')
-
-
-def check_lanhu():
-    """6. lanhu MCP: venv + cookie。三态 (就绪/未装/未配)。"""
-    print('\n--- 6. 蓝湖 MCP (lanhu, 可选) ---')
-    venv = BASE / 'external' / 'lanhu-mcp' / '.venv'
-    server = BASE / 'external' / 'lanhu-mcp' / 'lanhu_mcp_server.py'
-    if not venv.is_dir() or not server.is_file():
-        say(WARN_TAG, 'lanhu 未安装 (团队不用蓝湖可忽略; 用的话: setup_lanhu.py)')
-        return
-    # venv python
-    venv_py = venv / ('Scripts' if sys.platform == 'win32' else 'bin') / ('python.exe' if sys.platform == 'win32' else 'python')
-    if not venv_py.is_file():
-        problem('lanhu venv python 不存在', '重装: setup_lanhu.py')
-        return
-    # 当前角色 cookie
-    try:
-        from common.paths import get_developer
-        dev = get_developer(BASE)
-    except Exception:
-        dev = None
-    if not dev:
-        say(WARN_TAG, 'lanhu venv 就绪, 但未初始化开发者 (跑 /wl-init)')
-        return
-    cookie_file = BASE / 'workspace' / 'members' / dev / '.secrets' / 'lanhu.env'
-    if cookie_file.is_file():
-        say(OK_TAG, 'lanhu 就绪 (角色=%s, cookie 已配)' % dev)
-    else:
-        say(WARN_TAG, 'lanhu venv 就绪, 但角色 %s 的 cookie 未配 (%s)' % (dev, cookie_file))
-
-
-def check_playwright():
-    """7. playwright MCP: node + cli.js/npx。"""
-    print('\n--- 7. Playwright MCP (浏览器测试) ---')
-    import shutil
-    node = shutil.which('node')
-    if not node:
-        problem('node 未安装 (playwright MCP 需要)', '装 Node.js: npx wlkj install-env')
-        return
-    # 优先 cli.js (快), 回退 npx (慢)
-    try:
-        out = subprocess.run('npm root -g', shell=True, capture_output=True,
-                             text=True, timeout=10)
-        root = out.stdout.strip()
-        cli = os.path.join(root, '@playwright', 'mcp', 'cli.js')
-        if os.path.isfile(cli):
-            say(OK_TAG, 'playwright 就绪 (node + cli.js, 快启动)')
-            return
-    except Exception:
-        pass
-    if shutil.which('npx'):
-        say(WARN_TAG, 'playwright 可用但走 npx (冷启动慢, 可能被 QoderWork 超时杀)')
-        say(WARN_TAG, '  建议全局装: npm i -g @playwright/mcp')
-    else:
-        problem('npx 不可用', '装 Node.js')
-
-
-def main():
-    fix = '--fix' in sys.argv
-    print('=' * 56)
-    print('MCP 健康检查 (验证 init/download 后全系列可用)')
-    print('=' * 56)
-
-    check_mcp_json(fix)
-    check_repo_root(fix)
-    check_launcher_file(fix)
-    check_kg()
-    check_mysql()
-    check_lanhu()
-    check_playwright()
-
-    print('\n' + '=' * 56)
-    if issues:
-        print('未就绪 (%d):' % len(issues))
-        for i in issues:
-            print('  - ' + i)
-        print('=' * 56)
-        print('一键修复: python .qoder/scripts/check_mcp.py --fix')
-        print('重配 MCP: python .qoder/scripts/install_qoderwork.py --mcp-only')
-        return 1
-    print('所有 MCP 就绪, Qoder 全系列可正常调用。')
-    print('=' * 56)
-    return 0
-
-
-if __name__ == '__main__':
-    sys.exit(main())
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""mcp_doctor.py - MCP 诊断 (Facade 外观模式)
+
+v3.0 合并自: check_mcp(启动条件) + check_mcp_launch(实际启动)。
+两者都是"MCP诊断"一个职责的两个阶段, 对外应是1个命令的子操作。
+
+用法:
+    python mcp_doctor.py conditions [--fix]   启动条件检查 (依赖/配置/mcp.json)
+    python mcp_doctor.py launch               实际启动诊断 (逐个发initialize看谁黄)
+"""
+# v3.0 路径自举: 引导到 common/bootstrap, 统一 sys.path 逻辑
+import os as _o, sys as _s
+_cp = _o.path.join(_o.path.dirname(_o.path.dirname(_o.path.abspath(__file__))), 'common')
+if _cp not in _s.path: _s.path.insert(0, _cp)
+from bootstrap import setup; setup()
+
+
+
+# ==================== 来自 check_mcp.py (启动条件检查) ====================
+"""
+check_mcp.py - MCP 启动健康检查 (验证 init/download 后全系列可用)
+
+为什么需要它:
+  install_qoderwork.py --mcp-only 会写 mcp.json + launcher, 但"写了配置"不等于
+  "MCP 能起来"。50 人里有人 pip 没装齐、有人 .repo-root 写错、有人 lanhu venv 没建,
+  这些都要等用的时候才发现 MCP 挂了。本脚本主动验证每个 MCP 能否真正启动。
+
+  对应需求: "确保 MCP 等 init/download 后, 所有人 qoder 全系列正常运行"。
+
+检查什么 (不真启动 server, 只验证启动条件):
+  1. mcp.json 存在 + 各 server 注册了 launcher 模式
+  2. launcher 能定位仓库根 (.repo-root 锚点 / 环境变量 / 向上找)
+  3. 各 MCP 的依赖就绪:
+     - kg:    装了 duckdb 的 Python + kg_mcp_server.py 存在
+     - mysql: 装了 pymysql 的 Python + config.yaml 有 mysql 段
+     - lanhu: venv 建了 + 当前角色 cookie 配了
+     - playwright: node 在 + cli.js / npx 可用
+
+Usage:
+    python .qoder/scripts/check_mcp.py            # 全量检查
+    python .qoder/scripts/check_mcp.py --fix      # 检查 + 尝试修复 (.repo-root 等)
+Exit: 0 = 全部就绪, 1 = 有 MCP 未就绪
+"""
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+if sys.platform == 'win32':
+    try:
+        sys.stdout.reconfigure(encoding='utf-8')
+    except (AttributeError, IOError):
+        pass
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+from common.paths import get_repo_root
+
+BASE = get_repo_root()
+HOME = Path(os.environ.get('USERPROFILE') or os.path.expanduser('~'))
+QODERWORK_DIR = HOME / '.qoderwork'
+MCP_FILE = QODERWORK_DIR / 'mcp.json'
+REPO_ROOT_ANCHOR = QODERWORK_DIR / '.repo-root'
+
+OK_TAG = '[OK]  '
+WARN_TAG = '[WARN]'
+MISS_TAG = '[MISS]'
+BAD_TAG = '[BAD] '
+
+issues = []
+
+
+def say(tag, msg):
+    print('{} {}'.format(tag, msg))
+
+
+def problem(msg, hint=None):
+    issues.append(msg)
+    say(BAD_TAG, msg)
+    if hint:
+        print('       -> ' + hint)
+
+
+def _run(cmd, timeout=10):
+    """跑命令, 返回 (returncode, output)。"""
+    try:
+        r = subprocess.run(cmd, capture_output=True, text=True,
+                           encoding='utf-8', errors='replace', timeout=timeout)
+        return r.returncode, (r.stdout or '') + (r.stderr or '')
+    except (subprocess.TimeoutExpired, FileNotFoundError, OSError):
+        return 1, ''
+
+
+def _find_python_with(mod):
+    """找一个装了指定模块的 Python。返回路径或 None。"""
+    # 当前 Python
+    try:
+        __import__(mod)
+        return sys.executable
+    except ImportError:
+        pass
+    # 其他 Python
+    import shutil
+    for name in ('python', 'python3', 'py'):
+        p = shutil.which(name)
+        if p and p != sys.executable:
+            rc, _ = _run([p, '-c', 'import %s' % mod], timeout=8)
+            if rc == 0:
+                return p
+    return None
+
+
+# ============================================================
+# 检查项
+# ============================================================
+
+def check_mcp_json(fix=False):
+    """1. mcp.json 存在 + launcher 模式。"""
+    print('\n--- 1. mcp.json 配置 ---')
+    if not MCP_FILE.is_file():
+        problem('mcp.json 不存在 (%s)' % MCP_FILE,
+                '跑: python .qoder/scripts/install_qoderwork.py --mcp-only')
+        return False
+    try:
+        cfg = json.loads(MCP_FILE.read_text(encoding='utf-8'))
+    except (ValueError, OSError):
+        problem('mcp.json 解析失败', '文件损坏, 重跑 install_qoderwork.py --mcp-only')
+        return False
+    servers = cfg.get('mcpServers', {})
+    if not servers:
+        problem('mcp.json 无 mcpServers', '重跑 install_qoderwork.py --mcp-only')
+        return False
+    say(OK_TAG, 'mcp.json 存在, 注册了 %d 个 server: %s' % (
+        len(servers), ', '.join(servers.keys())))
+    # 检查是否 launcher 模式 (command 用 mcp_launcher.py)
+    launcher_count = 0
+    for name, entry in servers.items():
+        args = entry.get('args', []) if isinstance(entry, dict) else []
+        if any('mcp_launcher.py' in str(a) for a in args):
+            launcher_count += 1
+    if launcher_count > 0:
+        say(OK_TAG, '%d 个 server 用 launcher 模式 (跨机器通用)' % launcher_count)
+    else:
+        say(WARN_TAG, '无 launcher 模式 server (可能写死路径), 升级: install_qoderwork.py --mcp-only')
+    return True
+
+
+def check_repo_root(fix=False):
+    """2. launcher 能定位仓库根 (.repo-root 锚点)。"""
+    print('\n--- 2. 仓库根定位 ---')
+    if REPO_ROOT_ANCHOR.is_file():
+        try:
+            root_val = REPO_ROOT_ANCHOR.read_text(encoding='utf-8').strip()
+            if (Path(root_val) / '.qoder' / 'scripts').is_dir():
+                say(OK_TAG, '.repo-root 锚点正确: %s' % root_val)
+                return True
+            else:
+                problem('.repo-root 指向的目录不是仓库根: %s' % root_val,
+                        '重跑 install_qoderwork.py --mcp-only 会用 PROJECT_ROOT 修正')
+        except OSError:
+            pass
+    # 锚点缺失或错误
+    if fix:
+        try:
+            REPO_ROOT_ANCHOR.parent.mkdir(parents=True, exist_ok=True)
+            REPO_ROOT_ANCHOR.write_text(str(BASE), encoding='utf-8')
+            say(OK_TAG, '.repo-root 锚点已修复: %s -> %s' % (REPO_ROOT_ANCHOR, BASE))
+            return True
+        except OSError as e:
+            problem('修复 .repo-root 失败: %s' % e)
+    else:
+        problem('.repo-root 锚点缺失或错误',
+                '加 --fix 自动修复, 或重跑 install_qoderwork.py --mcp-only')
+    return False
+
+
+def check_launcher_file(fix=False):
+    """3. launcher 脚本存在于 ~/.qoderwork/。"""
+    print('\n--- 3. MCP launcher ---')
+    launcher = QODERWORK_DIR / 'mcp_launcher.py'
+    if launcher.is_file():
+        say(OK_TAG, 'launcher 存在: %s' % launcher)
+        return True
+    problem('launcher 不存在: %s' % launcher,
+            '重跑 install_qoderwork.py --mcp-only (会复制 launcher)')
+    return False
+
+
+def check_kg():
+    """4. kg MCP: duckdb + kg_mcp_server.py。"""
+    print('\n--- 4. 知识图谱 MCP (kg) ---')
+    server = BASE / '.qoder' / 'scripts' / 'kg_mcp_server.py'
+    if not server.is_file():
+        problem('kg_mcp_server.py 不存在', '引擎不完整, 重跑 npx wlkj update')
+        return
+    py = _find_python_with('duckdb')
+    if py:
+        say(OK_TAG, 'kg 就绪 (python=%s, 装了 duckdb)' % py)
+    else:
+        problem('找不到装了 duckdb 的 Python',
+                'pip install duckdb 或 npx @hupan56/wlkj install-env')
+
+
+def check_mysql():
+    """5. mysql MCP: pymysql + config.yaml mysql 段。"""
+    print('\n--- 5. MySQL MCP ---')
+    server = BASE / '.qoder' / 'scripts' / 'mysql_mcp_server.py'
+    if not server.is_file():
+        problem('mysql_mcp_server.py 不存在')
+        return
+    py = _find_python_with('pymysql')
+    if not py:
+        problem('找不到装了 pymysql 的 Python', 'pip install pymysql')
+        return
+    # config.yaml mysql 段
+    cfg_path = BASE / '.qoder' / 'config.yaml'
+    has_mysql = False
+    if cfg_path.is_file():
+        try:
+            import yaml
+            d = yaml.safe_load(cfg_path.read_text(encoding='utf-8')) or {}
+            has_mysql = bool(d.get('mysql', {}).get('host'))
+        except Exception:
+            pass
+    if has_mysql:
+        say(OK_TAG, 'mysql 就绪 (config.yaml 已配连接信息)')
+    else:
+        say(WARN_TAG, 'mysql 依赖就绪, 但 config.yaml 无 mysql 段 (按需配)')
+
+
+def check_lanhu():
+    """6. lanhu MCP: venv + cookie。三态 (就绪/未装/未配)。"""
+    print('\n--- 6. 蓝湖 MCP (lanhu, 可选) ---')
+    venv = BASE / 'external' / 'lanhu-mcp' / '.venv'
+    server = BASE / 'external' / 'lanhu-mcp' / 'lanhu_mcp_server.py'
+    if not venv.is_dir() or not server.is_file():
+        say(WARN_TAG, 'lanhu 未安装 (团队不用蓝湖可忽略; 用的话: setup_lanhu.py)')
+        return
+    # venv python
+    venv_py = venv / ('Scripts' if sys.platform == 'win32' else 'bin') / ('python.exe' if sys.platform == 'win32' else 'python')
+    if not venv_py.is_file():
+        problem('lanhu venv python 不存在', '重装: setup_lanhu.py')
+        return
+    # 当前角色 cookie
+    try:
+        from common.paths import get_developer
+        dev = get_developer(BASE)
+    except Exception:
+        dev = None
+    if not dev:
+        say(WARN_TAG, 'lanhu venv 就绪, 但未初始化开发者 (跑 /wl-init)')
+        return
+    cookie_file = BASE / 'workspace' / 'members' / dev / '.secrets' / 'lanhu.env'
+    if cookie_file.is_file():
+        say(OK_TAG, 'lanhu 就绪 (角色=%s, cookie 已配)' % dev)
+    else:
+        say(WARN_TAG, 'lanhu venv 就绪, 但角色 %s 的 cookie 未配 (%s)' % (dev, cookie_file))
+
+
+def check_playwright():
+    """7. playwright MCP: node + cli.js/npx。"""
+    print('\n--- 7. Playwright MCP (浏览器测试) ---')
+    import shutil
+    node = shutil.which('node')
+    if not node:
+        problem('node 未安装 (playwright MCP 需要)', '装 Node.js: npx wlkj install-env')
+        return
+    # 优先 cli.js (快), 回退 npx (慢)
+    try:
+        out = subprocess.run('npm root -g', shell=True, capture_output=True,
+                             text=True, timeout=10)
+        root = out.stdout.strip()
+        cli = os.path.join(root, '@playwright', 'mcp', 'cli.js')
+        if os.path.isfile(cli):
+            say(OK_TAG, 'playwright 就绪 (node + cli.js, 快启动)')
+            return
+    except Exception:
+        pass
+    if shutil.which('npx'):
+        say(WARN_TAG, 'playwright 可用但走 npx (冷启动慢, 可能被 QoderWork 超时杀)')
+        say(WARN_TAG, '  建议全局装: npm i -g @playwright/mcp')
+    else:
+        problem('npx 不可用', '装 Node.js')
+
+
+def main_conditions():
+    fix = '--fix' in sys.argv
+    print('=' * 56)
+    print('MCP 健康检查 (验证 init/download 后全系列可用)')
+    print('=' * 56)
+
+    check_mcp_json(fix)
+    check_repo_root(fix)
+    check_launcher_file(fix)
+    check_kg()
+    check_mysql()
+    check_lanhu()
+    check_playwright()
+
+    print('\n' + '=' * 56)
+    if issues:
+        print('未就绪 (%d):' % len(issues))
+        for i in issues:
+            print('  - ' + i)
+        print('=' * 56)
+        print('一键修复: python .qoder/scripts/check_mcp.py --fix')
+        print('重配 MCP: python .qoder/scripts/install_qoderwork.py --mcp-only')
+        return 1
+    print('所有 MCP 就绪, Qoder 全系列可正常调用。')
+    print('=' * 56)
+    return 0
+
+
+
+
+# ==================== 来自 check_mcp_launch.py (实际启动诊断) ====================
+"""
+check_mcp_launch.py - 诊断 MCP 为什么黄色
+
+逐个模拟 mcp_launcher.py 启动每个 MCP, 发送 initialize 请求,
+看哪个 MCP 启动失败/崩溃/不响应。输出明确的诊断结论。
+
+用法: python .qoder/scripts/check_mcp_launch.py
+"""
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+SCRIPTS_DIR = Path(__file__).resolve().parent
+BASE = SCRIPTS_DIR.parent.parent  # repo root
+
+MCP_NAMES = ['kg', 'mysql', 'zentao', 'lanhu']
+
+
+def find_python_with(mod):
+    """找一个能 import mod 的 python."""
+    for py in [sys.executable, 'python', 'python3']:
+        try:
+            r = subprocess.run([py, '-c', f'import {mod}'],
+                               capture_output=True, timeout=8)
+            if r.returncode == 0:
+                return py
+        except Exception:
+            continue
+    return None
+
+
+def test_mcp(name):
+    """测试一个 MCP 能否正常响应 initialize."""
+    launcher = SCRIPTS_DIR / 'mcp_launcher.py'
+    if not launcher.is_file():
+        return {'name': name, 'status': 'ERROR',
+                'detail': f'launcher 不存在: {launcher}'}
+
+    init_req = json.dumps({
+        'jsonrpc': '2.0', 'id': 1, 'method': 'initialize',
+        'params': {'capabilities': {}, 'protocolVersion': '2024-11-05',
+                   'clientInfo': {'name': 'diag', 'version': '1.0'}}
+    }) + '\n'
+
+    try:
+        r = subprocess.run(
+            [sys.executable, str(launcher), name],
+            input=init_req,
+            capture_output=True, text=True, timeout=10,
+            cwd=str(BASE), encoding='utf-8', errors='replace'
+        )
+    except subprocess.TimeoutExpired:
+        return {'name': name, 'status': 'TIMEOUT',
+                'detail': '启动后 10s 无响应 (可能卡在等 stdin)'}
+    except Exception as e:
+        return {'name': name, 'status': 'ERROR',
+                'detail': f'启动异常: {e}'}
+
+    stdout = r.stdout or ''
+    stderr = r.stderr or ''
+
+    # 解析 stdout 找 initialize 响应
+    init_ok = False
+    disabled = False
+    reason = ''
+    for line in stdout.split('\n'):
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            resp = json.loads(line)
+            if resp.get('id') == 1 and 'result' in resp:
+                init_ok = True
+                si = resp['result'].get('serverInfo', {})
+                ver = si.get('version', '')
+                if 'disabled' in ver:
+                    disabled = True
+                    reason = si.get('reason', '')
+                break
+        except json.JSONDecodeError:
+            continue
+
+    if init_ok and not disabled:
+        return {'name': name, 'status': 'OK',
+                'detail': '正常启动, 工具可用'}
+    elif init_ok and disabled:
+        return {'name': name, 'status': 'DISABLED',
+                'detail': f'以"未启用"模式启动 (绿但0工具): {reason}'}
+    elif r.returncode != 0:
+        # 进程崩溃了
+        return {'name': name, 'status': 'CRASHED',
+                'detail': f'进程退出(rc={r.returncode})。stderr:\n{stderr[-500:]}'}
+    else:
+        return {'name': name, 'status': 'NO_RESPONSE',
+                'detail': f'没崩溃但没响应 initialize。stdout:\n{stdout[-300:]}\nstderr:\n{stderr[-300:]}'}
+
+
+def main_launch():
+    print('=' * 56)
+    print('MCP 启动诊断')
+    print(f'仓库: {BASE}')
+    print(f'Python: {sys.executable} ({sys.version.split()[0]})')
+    print('=' * 56)
+
+    # 基础检查
+    print('\n--- 环境检查 ---')
+    for mod, label in [('duckdb', 'kg 依赖'), ('pymysql', 'mysql 依赖'),
+                       ('requests', 'zentao 依赖'), ('yaml', '配置解析')]:
+        try:
+            __import__(mod)
+            print(f'  [OK]   {mod} ({label})')
+        except ImportError:
+            py = find_python_with(mod)
+            if py:
+                print(f'  [WARN] {mod} 在当前Python没有, 但 {py} 有')
+            else:
+                print(f'  [MISS] {mod} ({label}) — pip install {mod}')
+
+    kg_path = BASE / 'data' / 'index' / 'kg.duckdb'
+    print(f'\n  kg.duckdb: {"存在" if kg_path.is_file() else "缺失 (git pull 失败? 非管理员跑 team_sync pull)"}')
+
+    # mcp.json 检查
+    home = Path(os.environ.get('USERPROFILE') or os.path.expanduser('~'))
+    mcp_file = home / '.qoderwork' / 'mcp.json'
+    print(f'\n  mcp.json: {mcp_file}')
+    if mcp_file.is_file():
+        try:
+            cfg = json.loads(mcp_file.read_text(encoding='utf-8'))
+            servers = cfg.get('mcpServers', {})
+            for srv in ['qoder-knowledge-graph', 'qoder-mysql', 'qoder-zentao', 'lanhu']:
+                entry = servers.get(srv)
+                if entry:
+                    cmd = entry.get('command', '?')
+                    args = entry.get('args', [])
+                    has_launcher = any('mcp_launcher.py' in str(a) for a in args)
+                    print(f'    {srv}: command={cmd!r} launcher={"是" if has_launcher else "否(旧模式)"}')
+                else:
+                    print(f'    {srv}: 未注册')
+        except Exception as e:
+            print(f'  [ERR] mcp.json 解析失败: {e}')
+    else:
+        print(f'  [MISS] mcp.json 不存在 (跑 npx @hupan56/wlkj update)')
+
+    # 逐个测试 MCP
+    print('\n--- MCP 启动测试 (模拟 QoderWork 发 initialize) ---')
+    results = []
+    for name in MCP_NAMES:
+        print(f'\n  测试 {name}...')
+        r = test_mcp(name)
+        results.append(r)
+        icon = {'OK': '🟢', 'DISABLED': '🟢(无工具)', 'CRASHED': '🔴',
+                'TIMEOUT': '🟡', 'NO_RESPONSE': '🟡', 'ERROR': '🔴'}
+        print(f'    {icon.get(r["status"], "?")} {r["status"]}: {r["name"]}')
+        if r['status'] not in ('OK', 'DISABLED'):
+            print(f'    详情: {r["detail"]}')
+
+    # 总结
+    print('\n' + '=' * 56)
+    print('诊断结论:')
+    ok = sum(1 for r in results if r['status'] in ('OK', 'DISABLED'))
+    bad = sum(1 for r in results if r['status'] not in ('OK', 'DISABLED'))
+    if bad == 0:
+        print(f'  全部 MCP 启动正常 ({ok}/{len(results)})。')
+        print('  如果 QoderWork 仍显示黄色: 重启 QoderWork 或新建对话。')
+        print('  (mcp.json 改动需要重启才生效)')
+    else:
+        print(f'  {bad} 个 MCP 启动有问题:')
+        for r in results:
+            if r['status'] not in ('OK', 'DISABLED'):
+                print(f'    - {r["name"]}: {r["status"]}')
+        print('\n  常见原因:')
+        print('    CRASHED: Python 版本不兼容(如3.14) 或 脚本语法错误 → 看详情里的 stderr')
+        print('    TIMEOUT: 脚本卡住了 → 查 DuckDB 文件锁 或 网络等待')
+        print('    NO_RESPONSE: stdout 被 print 污染 → 看 stdout 里的非 JSON 内容')
+    print('=' * 56)
+
+
+
+
+# ============================================================
+# Facade: 统一入口分发
+# ============================================================
+def main():
+    cmd = sys.argv[1] if len(sys.argv) > 1 else 'conditions'
+    sys.argv = [sys.argv[0]] + sys.argv[2:]  # 去掉子命令, 让各main的argparse正确解析
+    if cmd in ('conditions', 'check'):
+        sys.exit(main_conditions())
+    elif cmd == 'launch':
+        sys.exit(main_launch())
+    else:
+        print('用法: mcp_doctor.py [conditions|launch]')
+        print('  conditions [--fix]  启动条件检查')
+        print('  launch              实际启动诊断')
+
+if __name__ == '__main__':
+    main()