@hupan56/wlkj 2.7.12 → 3.1.2

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

@@ -0,0 +1,148 @@
+import os
+import sys
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+SCRIPTS = None
+cur = HERE
+for _ in range(8):
+    if os.path.isdir(os.path.join(cur, "foundation")) and os.path.isdir(os.path.join(cur, "domain")):
+        SCRIPTS = cur
+        break
+    cur = os.path.dirname(cur)
+if SCRIPTS is None:
+    SCRIPTS = os.path.dirname(os.path.dirname(HERE))
+if SCRIPTS not in sys.path:
+    sys.path.insert(0, SCRIPTS)
+    sys.path.insert(0, os.path.join(SCRIPTS, "foundation"))
+try:
+    from bootstrap import setup
+    setup()
+except Exception as e:
+    print("bootstrap setup failed: %s" % e)
+
+from foundation.core.paths import get_repo_root
+ROOT = get_repo_root()
+
+COMMANDS = os.path.join(str(ROOT), ".qoder", "commands")
+SKILLS = os.path.join(str(ROOT), ".qoder", "skills")
+AGENTS = os.path.join(str(ROOT), "AGENTS.md")
+
+CMD_PREFIX = "wl-"
+
+def names_cmds():
+    s = set()
+    if os.path.isdir(COMMANDS):
+        for r, d, fs in os.walk(COMMANDS):
+            for f in fs:
+                if f.endswith(".md") and f.startswith(CMD_PREFIX):
+                    s.add(os.path.splitext(f)[0])
+    return s
+
+def names_skills():
+    s = set()
+    if os.path.isdir(SKILLS):
+        for d in os.listdir(SKILLS):
+            p = os.path.join(SKILLS, d, "SKILL.md")
+            if os.path.isfile(p) and d.startswith(CMD_PREFIX):
+                s.add(d)
+    return s
+
+def agents_table_cmds():
+    s = set()
+    if not os.path.isfile(AGENTS):
+        return s, False
+    txt = open(AGENTS, encoding="utf-8", errors="ignore").read()
+    in_table = False
+    for line in txt.splitlines():
+        if "7 Core" in line or "核心命令" in line:
+            in_table = True
+        if not in_table:
+            continue
+        # match /wl-xxx only when followed by a table cell boundary
+        i = 0
+        while True:
+            a = line.find("/wl-", i)
+            if a < 0:
+                break
+            b = a + 4
+            while b < len(line) and (line[b].isalpha() or line[b] == "-"):
+                b += 1
+            # name must be at least /wl- + 1 char, and next char must be a boundary
+            ok = b >= a + 5
+            nxt = line[b] if b < len(line) else ""
+            if ok and nxt in ("`", " ", "|", "", "\t"):
+                s.add(line[a + 1:b])
+            i = b
+    return s, True
+
+def main():
+    errs = 0
+    warns = 0
+    print("=" * 60)
+    print("carriers verify: 4-carrier name-set + table integrity")
+    print("ROOT = %s" % ROOT)
+    print("=" * 60)
+
+    cs = names_cmds()
+    ss = names_skills()
+    ts, has_agents = agents_table_cmds()
+
+    only_cmd = sorted(cs - ss)
+    only_skill = sorted(ss - cs)
+
+    print("\n[1] command<->skill name set diff (wl-* prefixed only)")
+    print("    commands: %d, skills: %d" % (len(cs), len(ss)))
+    if only_cmd:
+        warns += 1
+        print("    [warn] commands without matching skill dir:")
+        for n in only_cmd:
+            print("       -%s" % n)
+    # 白名单: wl-prd-full/quick/review 是 wl-prd 路由器命令的模式子 skill (设计如此, 非漂移)
+    PRD_ROUTER_SKILLS = {"wl-prd-full", "wl-prd-quick", "wl-prd-review"}
+    real_orphans = [n for n in only_skill if n not in PRD_ROUTER_SKILLS]
+    prd_router = [n for n in only_skill if n in PRD_ROUTER_SKILLS]
+    if real_orphans:
+        errs += 1
+        print("    [FAIL] skills without matching command file (orphan):")
+        for n in real_orphans:
+            print("       -%s" % n)
+    if prd_router:
+        print("    [info] %d prd-router sub-skills (wl-prd-full/quick/review, by-design)" % len(prd_router))
+    if not only_cmd and not only_skill:
+        print("    [ok] wl-* command<->skill name sets aligned")
+
+    print("\n[2] AGENTS.md core-command table vs files")
+    if not has_agents:
+        errs += 1
+        print("    [FAIL] AGENTS.md missing")
+    else:
+        missing = sorted(ts - cs - ss)
+        if missing:
+            errs += 1
+            print("    [FAIL] table lists commands that have no file:")
+            for n in missing:
+                print("       /%s" % n)
+        else:
+            print("    [ok] all %d table entries have a file" % len(ts))
+
+    print("\n[3] delegate content check to existing carriers.py check")
+    chk = os.path.join(str(ROOT), ".qoder", "scripts", "deployment", "setup", "carriers.py")
+    if os.path.isfile(chk):
+        import subprocess
+        r = subprocess.run([sys.executable, chk, "check"], capture_output=True, text=True, encoding="utf-8", errors="replace")
+        if r.returncode == 0:
+            print("    [ok] carriers check passed")
+        else:
+            errs += 1
+            print("    [FAIL] carriers check reported drift (rc=%d)" % r.returncode)
+            for ln in (r.stdout or "").splitlines():
+                if ln.strip():
+                    print("       %s" % ln[:90])
+
+    print("-" * 60)
+    print("RESULT: %d FAIL / %d warn" % (errs, warns))
+    print("FAIL=must-fix drift; warn=advisory. exit 0 only if FAIL==0.")
+    return 1 if errs else 0
+
+if __name__ == "__main__":
+    sys.exit(main())

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

@@ -1,5 +1,16 @@
 #!/usr/bin/env python3
 # -*- coding: utf-8 -*-
+# v3.0 路径自举: 引导到 common/bootstrap, 统一 sys.path 逻辑
+import os as _o, sys as _s
+_f = _o.path.abspath(__file__)
+for _ in range(10):
+    _f = _o.path.dirname(_f)
+    _cp = _o.path.join(_f, 'foundation')
+    if _o.path.isfile(_o.path.join(_cp, 'bootstrap.py')):
+        break
+if _cp not in _s.path: _s.path.insert(0, _cp)
+from bootstrap import setup; setup()
+
 """
 QODER Init Doctor - 幂等的一站式环境体检 + 按需修复
 
@@ -44,12 +55,12 @@ except (AttributeError, TypeError, OSError, IOError):
     except Exception:
         pass
 
-SCRIPTS_DIR = os.path.dirname(os.path.abspath(__file__))
-sys.path.insert(0, SCRIPTS_DIR)
+from foundation.core.paths import get_repo_root, get_developer, get_developer_info
 
-from common.paths import get_repo_root, get_developer, get_developer_info
+SCRIPTS_DIR = str(get_repo_root())
+sys.path.insert(0, SCRIPTS_DIR)
 
-BASE = str(get_repo_root())
+BASE = SCRIPTS_DIR
 CODE_DIR = os.path.join(BASE, 'data', 'code')
 INDEX_DIR = os.path.join(BASE, 'data', 'index')
 TPL_DIR = os.path.join(BASE, '.qoder', 'templates')
@@ -76,22 +87,37 @@ def problem(msg, hint=None):
 
 
 def run_script(script, *args, timeout=1800):
-    """跑同目录下的另一个脚本, 实时透传输出"""
-    cmd = [sys.executable, os.path.join(SCRIPTS_DIR, script)] + list(args)
+    """跑另一个脚本, 实时透传输出。
+    v3.0: 支持子目录化 — 先在 scripts/根找, 找不到扫各子包。"""
+    # 先试 scripts/根
+    cand = os.path.join(SCRIPTS_DIR, script)
+    if not os.path.isfile(cand):
+        # 扫各子包
+        for sub in ('io', 'setup', 'kg', 'build', 'test'):
+            c2 = os.path.join(SCRIPTS_DIR, sub, script)
+            if os.path.isfile(c2):
+                cand = c2
+                break
+    cmd = [sys.executable, cand] + list(args)
     r = subprocess.run(cmd, cwd=BASE, timeout=timeout)
     return r.returncode == 0
 
 
 def load_config():
-    cfg = os.path.join(BASE, '.qoder', 'config.yaml')
-    if not os.path.isfile(cfg):
-        return {}
+    """v3.0: 转发到 Config 单例 (带 mtime 缓存)。"""
     try:
-        import yaml
-        with open(cfg, encoding='utf-8') as f:
-            return yaml.safe_load(f) or {}
+        from foundation.core.config import Config
+        return Config.load().raw
     except Exception:
-        return {}
+        cfg = os.path.join(BASE, '.qoder', 'config.yaml')
+        if not os.path.isfile(cfg):
+            return {}
+        try:
+            import yaml
+            with open(cfg, encoding='utf-8') as f:
+                return yaml.safe_load(f) or {}
+        except Exception:
+            return {}
 
 
 # ============================================================
@@ -100,7 +126,18 @@ def load_config():
 
 def check_basics():
     print('\n--- 1. 基础环境 ---')
-    say(OK, 'Python {}.{} ({})'.format(sys.version_info[0], sys.version_info[1], sys.platform))
+    # Python 版本下限检查 (v3.0+ 新增, 治"3.7 用户装 duckdb 难定位"隐患)
+    # duckdb>=1.1.0 / playwright>=1.40 / tree-sitter>=0.21 都要求 Python >=3.8
+    py_major, py_minor = sys.version_info[0], sys.version_info[1]
+    say(OK, 'Python {}.{} ({})'.format(py_major, py_minor, sys.platform))
+    if (py_major, py_minor) < (3, 8):
+        problem(
+            'Python {}.{} 低于最低要求 3.8 (duckdb/playwright/tree-sitter 需要)'.format(py_major, py_minor),
+            hint='升级 Python: 装 3.10+ (Windows python.org / Mac brew install python@3.10)'
+        )
+    elif (py_major, py_minor) < (3, 9):
+        say(WARN, 'Python {}.{} 可用但建议升级到 3.10+ (部分依赖未来可能提高要求)'.format(py_major, py_minor))
+
     # git 可选 (无 git 时核心功能仍可用, 仅团队同步禁用)
     try:
         r = subprocess.run(['git', '--version'], capture_output=True, text=True,
@@ -153,11 +190,29 @@ def check_dependencies(fix=False):
         req = os.path.join(BASE, 'requirements.txt')
         if os.path.isfile(req):
             # 用镜像兜底安装: 默认源失败 → 自动切清华/阿里/腾讯
-            from common.pip_install import install_with_fallback
+            # 注意: install_with_fallback 在 Anaconda 3.9+ Windows 上, pip 长时间编译
+            # 退出时偶发 GIL 崩溃 (Python 进程死)。这里 try 兜住: 崩了就用 os.system
+            # 跑裸 pip (独立进程, 无 GIL 问题) 兜底, 绝不让 doctor --fix 卡死。
             print('  → 安装: pip install -r requirements.txt (失败自动切国内镜像)')
-            result = install_with_fallback(['-r', req])
+            result = None
+            try:
+                from foundation.utils.pip_install import install_with_fallback
+                result = install_with_fallback(['-r', req])
+            except Exception as _e:
+                print('  [WARN] 镜像安装工具异常 (%s), 改用直装' % str(_e)[:60])
+            # 工具崩了或返回失败 → 用 os.system 直装 (清华镜像, 独立进程无 GIL 风险)
+            if not result or not result.get('ok'):
+                print('  → 直装: pip install -r requirements.txt (清华镜像)')
+                import subprocess as _sp
+                _rc = _sp.call([sys.executable, '-m', 'pip', 'install', '--no-input',
+                                '--progress-bar', 'off', '-i',
+                                'https://pypi.tuna.tsinghua.edu.cn/simple',
+                                '--trusted-host', 'pypi.tuna.tsinghua.edu.cn',
+                                '-r', req])
+                result = {'ok': _rc == 0, 'source': '清华' if _rc == 0 else None,
+                          'missing': [], 'hint': None}
             if result['ok']:
-                src = result['source']
+                src = result.get('source')
                 say(FIX, '依赖安装成功' + ('' if src == 'default' else ' (镜像源: %s)' % src))
                 # 装完后重新验证 (旧版装完不复查, 会把装失败误报为已装)
                 missing_core = []
@@ -168,7 +223,8 @@ def check_dependencies(fix=False):
                         except ImportError:
                             missing_core.append(pkg)
             else:
-                print('  [MISS] ' + result['hint'])
+                print('  [MISS] 依赖仍未装齐, 手动: pip install -r requirements.txt '
+                      '-i https://pypi.tuna.tsinghua.edu.cn/simple')
                 # 重新验证, 看哪些真的还缺
                 missing_core = []
                 for mod, pkg, usage, is_core in PIP_DEPS:
@@ -214,7 +270,7 @@ def check_developer(fix, name=None, role=None):
         return None
     if name and (not current or current != name):
         if fix:
-            from common.developer import init_developer
+            from foundation.identity.developer import init_developer
             if init_developer(name, role):
                 actions.append('注册/切换开发者: ' + name)
                 return name
@@ -225,9 +281,9 @@ def check_developer(fix, name=None, role=None):
     if current:
         info = get_developer_info() or {}
         say(OK, '开发者: {} ({})'.format(current, info.get('role', '?')))
-        # 个人空间目录
+        # 个人空间目录 (v3.0 M3: drafts/outputs/journal/.private, 不再有inbox)
         member = os.path.join(BASE, 'workspace', 'members', current)
-        missing = [s for s in ('drafts', 'inbox', 'journal')
+        missing = [s for s in ('drafts', 'outputs', 'journal')
                    if not os.path.isdir(os.path.join(member, s))]
         if missing:
             if fix:
@@ -377,17 +433,6 @@ def index_age_days():
         return None
     import time as _time
     return int((_time.time() - os.path.getmtime(kg_path)) / 86400)
-    if os.path.isfile(meta_path):
-        try:
-            import json
-            with open(meta_path, encoding='utf-8') as f:
-                meta = json.load(f)
-            ts = datetime.strptime(meta.get('last_sync', ''), '%Y-%m-%d %H:%M')
-        except Exception:
-            ts = None
-    if ts is None:
-        ts = datetime.fromtimestamp(os.path.getmtime(ki_path))
-    return (datetime.now() - ts).total_seconds() / 86400
 
 
 def _has_source_code():
@@ -409,11 +454,11 @@ def print_degraded_status():
     print('=' * 56)
     print('  以下功能需要源码, 当前不可用:')
     print('    /wl-search      搜代码 (无源码 = 搜不到)')
-    print('    /wl-prd-full    完整 PRD 的字段/API 锚定 (会跳过, 原型可用)')
+    print('    /wl-prd         完整 PRD 的字段/API 锚定 (会跳过, 原型可用)')
     print('    知识图谱 MCP     search_code/api 等工具 (启动但返回空)')
     print()
     print('  以下功能不依赖源码, 当前可用:')
-    print('    /wl-prd-quick   零星需求 (纯文案/小改动)')
+    print('    /wl-prd         零星需求模式 (纯文案/小改动)')
     print('    /wl-task        任务管理')
     print('    /wl-report      日报周报')
     print('    /wl-commit      代码提交 (提交的是工作流本身的改动)')
@@ -544,11 +589,12 @@ def check_prd_templates():
             problem('PRD 模板缺失: ' + md, '需要 AI 从团队章程 docx 重新蒸馏')
 
     # Qoder 全系列载体: rules 在 IDE/Quest 生效, AGENTS.md 在 CLI 生效
+    # (Trellis 化: rules 是引擎的一部分, 由 wlkj init/update 生成, 不在团队 git 里)
     rules_file = os.path.join(BASE, '.qoder', 'rules', 'wl-pipeline.md')
     if os.path.isfile(rules_file):
-        say(OK, '.qoder/rules/wl-pipeline.md (Qoder IDE/Quest 规则载体)')
+        say(OK, '.qoder/rules/wl-pipeline.md (Qoder IDE/Quest 规则载体, wlkj 生成)')
     else:
-        problem('.qoder/rules/wl-pipeline.md 缺失', 'Quest 模式将不知道工作流规则, 从 git 同步取回')
+        problem('.qoder/rules/wl-pipeline.md 缺失', 'Quest 模式将不知道工作流规则, 跑 npx @hupan56/wlkj update 重新生成')
     if os.path.isfile(os.path.join(BASE, 'AGENTS.md')):
         say(OK, 'AGENTS.md (Qoder CLI / 其他 Agent 工具载体)')
     else:
@@ -590,6 +636,21 @@ def check_weekly(fix):
 def check_qoderwork():
     """检查 QoderWork 桌面端是否已安装本项目的技能（junction 到 ~/.qoderwork/skills/）。"""
     print('\n--- 9. QoderWork 桌面端技能 (可选) ---')
+
+    # ★ v3.0 新增: launcher 文件就位检查 (全局, 缺失则所有 stdio MCP 黄灯)
+    # 场景: 换机器后没跑 install_qoderwork, mcp.json 引用的 launcher 不存在
+    home = os.environ.get('USERPROFILE') or os.environ.get('HOME') or os.path.expanduser('~')
+    launcher = os.path.join(home, '.qoderwork', 'mcp_launcher.py')
+    mcp_json = os.path.join(home, '.qoderwork', 'mcp.json')
+    if os.path.isfile(mcp_json):
+        # 装了 QoderWork 才检查 launcher (没装 mcp.json 的不算缺失)
+        if not os.path.isfile(launcher):
+            say(BAD, 'mcp_launcher.py 缺失: {} (所有 STDIO MCP 会黄灯)'.format(launcher))
+            print('       -> 跑: python .qoder/scripts/install_qoderwork.py')
+            issues.append('mcp_launcher.py 缺失')
+        else:
+            say(OK, 'mcp_launcher.py 就位 (STDIO MCP 启动器)')
+
     src_skills = os.path.join(BASE, '.qoder', 'skills')
     if not os.path.isdir(src_skills):
         say(WARN, '.qoder/skills/ 不存在, 跳过 QoderWork 检查')
@@ -693,7 +754,7 @@ def check_lanhu():
     mcp_file = os.path.join(home, '.qoderwork', 'mcp.json')
     if not os.path.isfile(mcp_file):
         say(WARN, '未配置蓝湖 MCP (团队不用蓝湖可忽略)')
-        print('       用的话跑: python .qoder/scripts/setup.py  或  setup_lanhu.py')
+        print('       用的话跑: python .qoder/scripts/deployment/setup/setup_lanhu.py')
         return
 
     try:
@@ -705,7 +766,7 @@ def check_lanhu():
 
     if 'lanhu' not in servers:
         say(WARN, '未配置蓝湖 MCP (团队不用蓝湖可忽略)')
-        print('       用的话跑: python .qoder/scripts/setup.py  或  setup_lanhu.py')
+        print('       用的话跑: python .qoder/scripts/deployment/setup/setup_lanhu.py')
         return
 
     entry = servers['lanhu']
@@ -781,7 +842,7 @@ def main():
         print('=' * 56)
         return 1
     if _has_source_code():
-        print('环境健康, 可以开始工作: /wl-prd-full <需求描述>')
+        print('环境健康, 可以开始工作: /wl-prd <需求描述>')
     else:
         print('工作流核心已就绪 (见上方降级说明补源码)。')
     print('=' * 56)

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

@@ -1,4 +1,16 @@
 # -*- 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 桌面端可识别的位置
 
@@ -38,9 +50,9 @@ if sys.platform == "win32":
     except (AttributeError, IOError):
         pass
 
-# 路径自检：项目根 = 本文件上三级（scripts/ -> .qoder/ -> repo）
+# 路径自检：项目根 = 本文件上四级 (v3.0: setup/ -> scripts/ -> .qoder/ -> repo)
 SCRIPT_DIR = Path(__file__).resolve().parent
-PROJECT_ROOT = SCRIPT_DIR.parent.parent
+PROJECT_ROOT = get_repo_root()
 SOURCE_SKILLS_DIR = PROJECT_ROOT / ".qoder" / "skills"
 SOURCE_COMMANDS_DIR = PROJECT_ROOT / ".qoder" / "commands"
 
@@ -405,14 +417,17 @@ def rewrite_mcp_json_for_launcher():
         return
 
     # 选 Python 写进 mcp.json:
-    # 优先级 1: 找一个已经装了核心依赖(duckdb/pymysql/yaml/requests)的 Python
-    #   → 这样 launcher 启动后秒命中, MCP 秒绿
-    # 优先级 2: 任意可用 python 命令名 (launcher 内部会再找)
-    py_with_deps = find_python_with_core_deps()
-    if py_with_deps:
-        py_cmd = py_with_deps  # 完整路径, 最可靠
-    else:
-        py_cmd = detect_python_command() or "python"
+    # 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 = {
@@ -426,7 +441,7 @@ def rewrite_mcp_json_for_launcher():
         entry = servers.get(srv)
         # 全新机器: kg/mysql/lanhu 条目可能不存在 → 创建它 (launcher 模式)
         if not entry:
-            servers[srv] = {"command": py_cmd, "args": [launcher, sub]}
+            servers[srv] = {"command": py_cmd, "args": [launcher, sub], "enabled": True}
             changed = True
             continue
         # 已是 launcher 模式? 检查 command 是否需要更新 (Python 路径可能变了)
@@ -435,7 +450,11 @@ def rewrite_mcp_json_for_launcher():
             # 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]}
+                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 抽离到独立文件
@@ -447,7 +466,7 @@ def rewrite_mcp_json_for_launcher():
             except OSError:
                 pass
         # 改成 launcher 模式
-        servers[srv] = {"command": py_cmd, "args": [launcher, sub]}
+        servers[srv] = {"command": py_cmd, "args": [launcher, sub], "enabled": True}
         changed = True
 
     if changed:
@@ -456,12 +475,9 @@ def rewrite_mcp_json_for_launcher():
             QODERWORK_MCP_FILE.write_text(
                 json.dumps(cfg, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
             print(f"\n--- mcp.json 重写为 launcher 模式 ---")
-            if py_with_deps:
-                print(f"  [UPD]  kg/mysql/zentao/lanhu → command={py_cmd} (装了依赖的Python)")
-            else:
-                print(f"  [UPD]  kg/mysql/zentao/lanhu → command={py_cmd}")
+            print(f"  [UPD]  kg/mysql/zentao/lanhu → command={py_cmd} (命令名, 跨机器通用)")
             print(f"         args=[mcp_launcher.py, <名>] (launcher 内部找装依赖的 Python)")
-            print(f"         不再写死仓库路径/venv路径, 跨机器通用")
+            print(f"         不再写死绝对路径, 换机器/重装Python不会失效")
         except OSError as e:
             print(f"  [ERR]  mcp.json 重写失败: {e}")
 
@@ -488,7 +504,7 @@ def main():
         print("MCP 配置刷新 (--mcp-only)")
         print("=" * 56)
         # 1. 复制 launcher
-        launcher_src = SOURCE_COMMANDS_DIR.parent / "scripts" / "mcp_launcher.py"
+        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)
@@ -508,15 +524,17 @@ def main():
         except Exception:
             pass
         # 4. 写 .repo-root 锚点 (launcher 定位仓库根用)
-        # 用 PROJECT_ROOT (脚本自身定位的仓库根) 而非 cwd —— 修"安装目录不一致"bug:
-        # 用户可能从任意目录跑 install_qoderwork (home/其他项目), cwd ≠ 仓库根,
-        # 写 cwd 会让 .repo-root 指向错误目录 → MCP 全找不到仓库。
-        # PROJECT_ROOT 由本文件位置推出 (scripts/ -> .qoder/ -> repo), 与 cwd 无关。
+        # 防御: 二次验证 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)
-            anchor.write_text(str(PROJECT_ROOT), encoding="utf-8")
-            print(f"  [OK]   .repo-root 锚点: {anchor} -> {PROJECT_ROOT}")
+            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
         return
@@ -659,7 +677,7 @@ def main():
     # QoderWork 桌面端工作目录是临时会话目录, 不是仓库根, 相对路径失效。
     # repo_root.py 从 mcp.json 反推仓库根, 命令文件靠它定位脚本/模板。
     if action in ("install", "check"):
-        repo_root_src = SOURCE_COMMANDS_DIR.parent / "scripts" / "repo_root.py"
+        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":
@@ -684,7 +702,7 @@ def main():
     # .repo-root 锚点文件让 launcher 能定位仓库根 (不依赖 mcp.json 里的路径)。
     if action in ("install", "check"):
         print(f"\n--- mcp_launcher.py (统一 MCP 启动器) ---")
-        launcher_src = SOURCE_COMMANDS_DIR.parent / "scripts" / "mcp_launcher.py"
+        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":
@@ -755,7 +773,7 @@ def main():
         elif lh_status == "would-add":
             print(f"  [MISS] 未注册蓝湖 MCP, 安装时会写入 {QODERWORK_MCP_FILE}")
         # STDIO 模式由 QoderWork 自动管, 不查端口; 只确认 wrapper + 源码就绪
-        wrapper = PROJECT_ROOT / ".qoder" / "scripts" / "lanhu_stdio_wrapper.py"
+        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)")
@@ -767,8 +785,8 @@ def main():
     if action == "install" and counts["err"] == 0:
         print("\n✓ 安装完成。重启 QoderWork（或新建对话）后技能生效。")
         print("  在 QoderWork 里直接用自然语言即可，例如：")
-        print('    "写个保险异常筛选的 PRD"  -> /wl-prd-full（正经需求）')
-        print('    "列表加个导出按钮"       -> /wl-prd-quick（小改动）')
+        print('    "写个保险异常筛选的 PRD"  -> /wl-prd（正经需求, 完整档）')
+        print('    "列表加个导出按钮"       -> /wl-prd（小改动, 自动走快速档）')
         print('    "查一下考勤代码在哪"      -> /wl-search')
     elif action == "install" and counts["err"] > 0:
         print(f"\n⚠ 有 {counts['err']} 个安装失败，见上方 [ERR] 行。")