@hupan56/wlkj 2.7.12 → 3.1.2

package/bin/cli.js

@@ -1,1108 +1,1436 @@
-#!/usr/bin/env node
-// wlkj - workflow toolkit
-
-const path = require("path");
-const fs = require("fs");
-const { execSync } = require("child_process");
-
-const T = path.join(__dirname, "..", "templates");
-
-// 当前 npm 包版本（从 package.json 读，不硬编码）
-const PKG_VERSION = JSON.parse(
-  fs.readFileSync(path.join(__dirname, "..", "package.json"), "utf-8")
-).version;
-
-// 升级时受保护的用户数据文件（绝不覆盖）
-// 这些文件含团队/机器特定配置，覆盖 = 数据丢失
-const PROTECTED_FILES = new Set([
-  "config.yaml",        // 团队 git 仓库 URL、平台映射
-  "settings.json",      // 本地权限/hook 配置
-]);
-
-// 本地状态文件（升级时也绝不碰，但不算"受保护配置"，不提示合并）
-const LOCAL_STATE_FILES = new Set([
-  ".developer", ".current-task", ".engine-version",
-]);
-
-// 探测可用的 Python 命令 (python 或 python3)。
-// macOS 系统通常只有 python3, 硬编码 python 会让 Mac 全员失败。
-// 探测结果缓存到全局, 避免每次调用都 fork 进程。
-let _PY_CMD_CACHE = null;
-function detectPyCmd() {
-  if (_PY_CMD_CACHE) return _PY_CMD_CACHE;
-  for (const c of ["python", "python3"]) {
-    try {
-      execSync(`${c} --version`, { encoding: "utf-8", timeout: 5000, stdio: "pipe" });
-      _PY_CMD_CACHE = c;
-      return c;
-    } catch { /* try next */ }
-  }
-  _PY_CMD_CACHE = null;
-  return null;
-}
-
-function py(script, args = []) {
-  const p = path.join(process.cwd(), ".qoder", "scripts", script);
-  if (!fs.existsSync(p)) { console.log("请先运行: npx wlkj init"); process.exit(1); }
-  const pyCmd = detectPyCmd();
-  if (!pyCmd) { console.log("Python 未安装, 无法运行脚本。跑: npx @hupan56/wlkj install-env"); return ""; }
-  try {
-    return execSync(`${pyCmd} "${p}" ${args.map(a => `"${a}"`).join(" ")}`, { cwd: process.cwd(), encoding: "utf-8", timeout: 15000 });
-  } catch (e) { return (e.stdout || e.message); }
-}
-
-// 透传执行: 直接 spawn (不捕获输出, 实时显示, 支持长超时和交互式)
-// 用于 kg_build/eval_prd/autotest 等耗时脚本, 以及需要交互的场景
-function runScript(scriptName, args = [], timeoutMs = 600000) {
-  const p = path.join(process.cwd(), ".qoder", "scripts", scriptName);
-  if (!fs.existsSync(p)) { console.log("脚本不存在: " + scriptName + "。跑: npx wlkj init"); process.exit(1); }
-  const pyCmd = detectPyCmd();
-  if (!pyCmd) { console.log("Python 未安装。跑: npx @hupan56/wlkj install-env"); process.exit(1); }
-  const { spawnSync } = require("child_process");
-  // 强制 UTF-8 环境 (Windows cmd 默认 GBK, 会导致中文输出乱码)
-  const env = { ...process.env, PYTHONIOENCODING: "utf-8", PYTHONUTF8: "1" };
-  const r = spawnSync(pyCmd, [p, ...args], { cwd: process.cwd(), stdio: "inherit", timeout: timeoutMs, encoding: "utf-8", env });
-  process.exit(r.status || 0);
-}
-
-// 带镜像兜底的 pip 安装 —— 复用 Python 的 common/pip_install.py (单一事实源)
-// 为什么不复用 Python: 上一轮给 init_doctor 做了 common/pip_install.py (失败切清华/阿里/腾讯)。
-// cli.js 的 install-env/update 是独立 JS 路径, 之前没享受镜像兜底 → 50 人里弱网用户全崩。
-// 这里调用同一个 Python 工具, 保证两路径行为一致。
-//
-// 优先: 引擎已装 → 调 common.pip_install (有镜像兜底)
-// 回退: 引擎没装 → 裸 pip install (install-env 首次场景, 无 Python 工具可用)
-//
-// 实现注意 (修 2.7.0 的真 bug): 不能用字符串拼接构造 Python -c 代码 ——
-// Windows 路径含反斜杠, 拼进 Python 字符串后 \Y \n 等成了非法转义 + 引号丢失,
-// 导致 SyntaxError → 镜像兜底静默失败 → 回退裸 pip → 弱网用户全崩。
-// 改用环境变量传参 (WLKJ_REQ_PATH), Python 侧 os.environ 读, 彻底避开转义地狱。
-function installPipDeps(pyCmd, reqPath) {
-  const scriptsDir = path.join(process.cwd(), ".qoder", "scripts");
-  const hasTool = fs.existsSync(path.join(scriptsDir, "common", "pip_install.py"));
-  if (hasTool) {
-    // 用环境变量传 requirements 路径, Python 侧 os.environ 读 (跨平台无转义问题)
-    const prog = [
-      "import sys, os, json",
-      "sys.path.insert(0, os.environ['WLKJ_SCRIPTS_DIR'])",
-      "from common.pip_install import install_with_fallback",
-      "r = install_with_fallback(['-r', os.environ['WLKJ_REQ_PATH']])",
-      "print('WLKJ_RESULT=' + json.dumps(r, ensure_ascii=False))",
-    ].join("; ");
-    try {
-      const out = execSync(`${pyCmd} -c "${prog}"`, {
-        encoding: "utf-8", timeout: 600000,
-        env: { ...process.env, WLKJ_SCRIPTS_DIR: scriptsDir, WLKJ_REQ_PATH: reqPath },
-      });
-      // 找 WLKJ_RESULT= 那行 (避免被 pip 输出干扰)
-      const resultLine = out.split("\n").find(l => l.startsWith("WLKJ_RESULT="));
-      if (!resultLine) throw new Error("Python 工具无结果输出");
-      const result = JSON.parse(resultLine.slice("WLKJ_RESULT=".length));
-      if (result.ok) {
-        console.log(`  [OK] Python 依赖已装` + (result.source && result.source !== "default" ? ` (镜像源: ${result.source})` : ""));
-      } else {
-        console.log(`  [WARN] pip 安装失败 (尝试了所有镜像)`);
-        console.log(`  ${result.hint || ""}`.replace(/\n/g, "\n  "));
-      }
-      return result.ok;
-    } catch (e) {
-      console.log(`  [WARN] 调用镜像工具失败, 回退裸 pip: ${(e.message || "").slice(0, 80)}`);
-    }
-  }
-  // 回退: 裸 pip install (引擎未装, 或工具调用失败)
-  try {
-    execSync(`${pyCmd} -m pip install -r "${reqPath}"`, { stdio: "inherit", timeout: 300000 });
-    console.log("  [OK] Python 依赖已装");
-    return true;
-  } catch (e) {
-    console.log(`  [WARN] pip 安装失败: ${(e.message || "").slice(0, 80)}`);
-    console.log("  国内网络建议配镜像: pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple");
-    return false;
-  }
-}
-
-function cp(src, dest) {
-  const s = path.join(T, src), d = path.join(process.cwd(), dest);
-  if (!fs.existsSync(s)) return;
-  fs.mkdirSync(path.dirname(d), { recursive: true });
-  if (!fs.existsSync(d)) { fs.copyFileSync(s, d); return true; }
-  return false;
-}
-
-function gitOp(op) {
-  const cwd = process.cwd();
-  const cmds = {
-    "提交": 'git add . && git commit -m "update [ai-assisted]" && git push',
-    "推送": "git push",
-    "拉取最新": "git pull",
-    "同步": "git pull",
-    "查看状态": "git status",
-    "提交PRD": 'git add workspace/specs/prd/ && git commit -m "docs(ai): PRD update [ai-generated]" && git push',
-    "提交Spec": 'git add workspace/specs/ && git commit -m "docs(ai): Spec update [ai-generated]" && git push',
-    "提交任务": 'git add workspace/tasks/ && git commit -m "chore: task update [ai-assisted]" && git push',
-  };
-  const cmd = cmds[op];
-  if (!cmd) { console.log("可用: 提交 推送 拉取最新 同步 查看状态 提交PRD 提交Spec 提交任务"); return; }
-  try { console.log(execSync(cmd, { cwd, encoding: "utf-8", timeout: 30000, stdio: "pipe" }) || `${op} done`); }
-  catch (e) { console.log(e.stdout || e.message); }
-}
-
-// 快速环境检测 (init 前置): 缺 Python 致命退出, 缺 git 警告不阻塞
-// 目的: 杜绝"裸机没 Python 时 init 静默失败仍宣布成功"的假成功
-function checkEnvQuick() {
-  console.log("--- 环境检测 ---");
-  // Node 一定有 (npx 在跑), 输出 version 确认
-  console.log(`  Node.js: [OK] ${process.version}`);
-
-  // Python: python 或 python3 任一可用即可
-  let pyCmd = null, pyVer = null;
-  for (const c of ["python", "python3"]) {
-    try {
-      const v = execSync(`${c} --version`, { encoding: "utf-8", timeout: 5000, stdio: "pipe" }).trim();
-      pyCmd = c; pyVer = v; break;
-    } catch { /* try next */ }
-  }
-  if (!pyCmd) {
-    console.log("  Python:  [缺失] (引擎必需)");
-    console.log("\n  ⚠ 没装 Python, 无法继续。请先装环境:");
-    console.log("    npx @hupan56/wlkj install-env");
-    console.log("    (自动装 Node/Python/git + pip 依赖; 装完重开终端再 init)\n");
-    return { ok: false, pyCmd: null };
-  }
-  console.log(`  Python:  [OK] ${pyVer} (${pyCmd})`);
-
-  // git: 可选, 缺了只警告 (与 init_doctor 口径一致)
-  try {
-    const gv = execSync("git --version", { encoding: "utf-8", timeout: 5000, stdio: "pipe" }).trim();
-    console.log(`  git:     [OK] ${gv}`);
-  } catch {
-    console.log("  git:     [缺失] (可选, 团队同步/源码克隆将禁用, 本地 PRD/搜索/任务仍可用)");
-    console.log("           想启用: npx @hupan56/wlkj install-env");
-  }
-  console.log("");
-  return { ok: true, pyCmd };
-}
-
-// 交互式问角色 (50 人团队角色各异, 不能写死 pm)
-// 支持的角色 (与 config.yaml / kg.py ROLE_SECTIONS 对齐)
-const ROLES = [
-  { key: "pm", label: "产品经理 (PM) — 写需求/PRD/任务" },
-  { key: "design", label: "设计师 (UI) — 录入设计稿/出原型" },
-  { key: "dev", label: "开发 (前端/后端) — 写代码/提交/测试" },
-  { key: "test", label: "测试 (QA) — 跑测试用例/验证" },
-  { key: "admin", label: "管理员 — 管理/维护工作流" },
-];
-
-function askRole() {
-  // 非交互环境 (CI/AI 调用) 默认 pm
-  if (!process.stdin.isTTY) {
-    console.log("  (非交互环境, 默认角色: pm)");
-    return "pm";
-  }
-  console.log("\n  你的角色是? (决定命令视角和建议)");
-  ROLES.forEach((r, i) => console.log(`    ${i + 1}. ${r.label}`));
-  const readline = require("readline").createInterface({ input: process.stdin, output: process.stdout });
-  return new Promise((resolve) => {
-    readline.question("\n  选择 (1-5, 默认1): ", (ans) => {
-      readline.close();
-      const idx = parseInt(ans, 10) - 1;
-      const role = (idx >= 0 && idx < ROLES.length) ? ROLES[idx].key : "pm";
-      console.log(`  角色: ${role}\n`);
-      resolve(role);
-    });
-  });
-}
-
-// 校验角色参数合法性 (大小写无关: PM/pm/Dev/dev 都认)
-function normalizeRole(r) {
-  if (!r) return null;
-  const low = String(r).toLowerCase();
-  return ROLES.some(x => x.key === low) ? low : null;
-}
-
-async function doInit(name, roleArg) {
-  const cwd = process.cwd();
-  const hasExisting = fs.existsSync(path.join(cwd, ".qoder", "scripts", "setup.py"));
-  console.log(`\nwlkj init -> ${cwd}${hasExisting ? " (已存在, 增量更新)" : ""}\n`);
-
-  // === 0. 环境前置检测 (避免裸机无 Python 时假成功) ===
-  const env = checkEnvQuick();
-  if (!env.ok) process.exit(1);
-  const { pyCmd } = env;
-
-  // === 0.5. 确定角色 (参数 > 交互式, 不再写死 pm)
-  // 50 人团队角色各异: 产品/UI/前后端/测试/管理, 每个角色的命令视角不同。
-  // 写死 pm = 设计师和开发拿不到匹配的上下文 (见 wl-prd-full 的 --role 适配)。
-  let role = normalizeRole(roleArg);
-  if (!role) {
-    role = await askRole();
-  } else {
-    console.log(`  角色: ${role} (来自参数)\n`);
-  }
-
-  // === 1. 拷贝完整引擎 (镜像 .qoder/ 结构) ===
-  // 源: templates/qoder/*  目标: .qoder/*
-  // 注意: init 用 "update" 模式的保护逻辑更安全 —— 新装时目标文件不存在,
-  // 保护逻辑不触发; 重跑 init 时 config.yaml/settings.json 不会被覆盖。
-  const qoderSrc = path.join(T, "qoder");
-  let copied = 0;
-  if (fs.existsSync(qoderSrc)) {
-    const r = copyDirRecursive(qoderSrc, path.join(cwd, ".qoder"), "update");
-    copied = r.copied;
-    if (r.protectedN > 0) {
-      console.log(`  [保护] ${r.protectedN} 个配置文件未覆盖（新版存为 .new）`);
-    }
-  }
-  console.log(`  引擎: ${copied} 个文件 (${hasExisting ? "更新" : "新建"})`);
-
-  // === 2. 根文件 (AGENTS.md, 新手指南.md, requirements.txt) ===
-  ["root/AGENTS.md", "root/新手指南.md", "root/requirements.txt"].forEach(f => {
-    const src = path.join(T, f);
-    if (fs.existsSync(src)) {
-      const dstName = path.basename(f);
-      const dst = path.join(cwd, dstName);
-      // requirements.txt 始终覆盖(版本可能更新), 其它不存在才拷
-      if (dstName === "requirements.txt" || !fs.existsSync(dst)) {
-        fs.copyFileSync(src, dst);
-      }
-    }
-  });
-
-  // === 3. workspace 目录结构 ===
-  ["workspace/specs/prd", "workspace/tasks", "workspace/constitution",
-   "workspace/members", "data/docs/prd", "data/index", "data/code"].forEach(d => {
-    fs.mkdirSync(path.join(cwd, d), { recursive: true });
-  });
-  console.log(`  workspace 目录就绪`);
-
-  // === 4. git init (若没有) ===
-  if (!fs.existsSync(path.join(cwd, ".git"))) {
-    try { execSync("git init", { cwd, stdio: "pipe" }); console.log(`  git init done`); }
-    catch (_) { /* git 可能没装, 不阻塞 */ }
-  }
-
-  // === 5. .gitignore (若没有) ===
-  const gitignorePath = path.join(cwd, ".gitignore");
-  if (!fs.existsSync(gitignorePath)) {
-    const baseGitignore = [
-      "# Source code repos (cloned by git_sync.py)", "data/code/",
-      "", "# AI pipeline runtime", ".qoder/.developer", ".qoder/.current-task",
-      ".qoder/.engine-version", ".qoder/.runtime/", "",
-      "# Personal learning", ".qoder/learning/feedback.jsonl",
-      "", "# Machine-local", "data/index/.last-sync", "data/index/.prd-collected.json",
-      "data/index/.index-meta.json", "data/index/.sync-lock", "data/index/.file-keys.json",
-      "data/index/.inverted-cache.json", "data/index/*.corrupt",
-      "", "# Identity (secret)", "workspace/members/*/.signing_key", "",
-      "# Python", "__pycache__/", "*.pyc", "*.lock", "",
-    ].join("\n");
-    fs.writeFileSync(gitignorePath, baseGitignore, "utf-8");
-  }
-
-  // === 6. 自动跑 setup.py (名字探测/git/索引/cron/QoderWork) ===
-  console.log(`\n--- 自动初始化 ---`);
-  const setupPath = path.join(cwd, ".qoder", "scripts", "setup.py");
-  if (fs.existsSync(setupPath)) {
-    const setupArgs = [name, role, "--skip-cron", "--skip-qoderwork"].filter(Boolean);
-    try {
-      const cmd = `python "${setupPath}" ${setupArgs.map(a => `"${a}"`).join(" ")}`;
-      console.log(`  运行: setup.py ${setupArgs.join(" ")}`);
-      // 强制 UTF-8 环境 (Windows cmd 默认 GBK, 会导致中文输出乱码)
-      const env = { ...process.env, PYTHONIOENCODING: "utf-8", PYTHONUTF8: "1" };
-      execSync(cmd, { cwd, stdio: "inherit", timeout: 300000, env });
-    } catch (e) {
-      console.log(`  setup 部分失败 (不阻塞): ${(e.message || "").slice(0, 100)}`);
-      console.log(`  可重新运行: npx @hupan56/wlkj init ${name || "<你的名字>"}`);
-    }
-    } else {
-      console.log(`  setup.py 未找到, 跳过自动初始化`);
-    }
-
-  // === 6.4. 装 pip 依赖 (必须在配 MCP 之前!)
-  // 顺序关键: 先装依赖 → 再写 mcp.json → mcp.json 选到"装了依赖的Python" → MCP 秒绿
-  // 旧版 init 不装依赖直接配 mcp.json → 新机 MCP 全黄 (没装 duckdb/pymysql)
-  console.log(`\n--- Python 依赖安装 (失败自动切镜像) ---`);
-  const reqFileInit = path.join(cwd, "requirements.txt");
-  if (pyCmd && fs.existsSync(reqFileInit)) {
-    installPipDeps(pyCmd, reqFileInit);
-  } else if (!pyCmd) {
-    console.log(`  [跳过] Python 未装`);
-  } else {
-    console.log(`  [跳过] requirements.txt 不存在`);
-  }
-
-  // === 6.5. 自动配 QoderWork MCP (新机关键: 否则 mcp.json 不生成, 4 个 MCP 全连不上) ===
-  // 复刻 doUpdate 第 6 步的逻辑: 拷 launcher + install_qoderwork --mcp-only
-  // setup.py 带了 --skip-qoderwork (offer_qoderwork 是交互式+装skill, 不适合 npx),
-  // 这里用 --mcp-only (纯文件操作, 无交互) 把 mcp.json 配好
-  // 注意: 此时依赖已装好(6.4步), install_qoderwork 会选到装了依赖的 Python
-  if (pyCmd) {
-    console.log(`\n--- QoderWork MCP 自动配置 ---`);
-    const home = process.env.USERPROFILE || require("os").homedir();
-    const launcherSrc = path.join(cwd, ".qoder", "scripts", "mcp_launcher.py");
-    const launcherDst = path.join(home, ".qoderwork", "mcp_launcher.py");
-    try {
-      if (fs.existsSync(launcherSrc)) {
-        fs.mkdirSync(path.dirname(launcherDst), { recursive: true });
-        fs.copyFileSync(launcherSrc, launcherDst);
-        console.log(`  [OK] launcher 已装: ~/.qoderwork/mcp_launcher.py`);
-      }
-      const instScript = path.join(cwd, ".qoder", "scripts", "install_qoderwork.py");
-      if (fs.existsSync(instScript)) {
-        try {
-          const env = { ...process.env, PYTHONIOENCODING: "utf-8", PYTHONUTF8: "1" };
-          execSync(`${pyCmd} "${instScript}" --mcp-only`, { stdio: "inherit", timeout: 20000, env });
-          console.log(`  [OK] mcp.json 已生成 (选装了依赖的Python, MCP 不会黄)`);
-        } catch (e) {
-          console.log(`  [WARN] MCP 配置未完全成功 (不阻塞): ${(e.message || "").slice(0, 80)}`);
-          console.log(`         可手动补: ${pyCmd} .qoder/scripts/install_qoderwork.py`);
-        }
-      }
-    } catch (e) {
-      console.log(`  [WARN] MCP 配置跳过: ${(e.message || "").slice(0, 80)}`);
-    }
-  }
-
-  // === 7. 写版本戳 ===
-  writeEngineVersion(cwd);
-
-  console.log(`\n${"=".repeat(50)}`);
-  console.log(`  安装完成!  (v${PKG_VERSION})`);
-  console.log(`${"=".repeat(50)}`);
-  console.log(`\n  现在可以开始了:`);
-  console.log(`    在 Qoder 里说 "写个 XX 的需求"`);
-  console.log(`    或输 / 看命令列表 (/wl-prd /wl-search /wl-task)`);
-  console.log(`\n  ✓ QoderWork MCP 已自动配好 (kg/mysql/lanhu/playwright)`);
-  console.log(`    用 QoderWork 桌面端想装技能(软链到 ~/.qoderwork/skills/)?`);
-  console.log(`    python .qoder/scripts/install_qoderwork.py`);
-  console.log(`\n  看不到命令? 新建对话 / 重启 QoderWork`);
-  console.log(`  环境问题? python .qoder/scripts/init_doctor.py --fix\n`);
-}
-
-// 递归拷贝目录, 返回 {copied, protected, skipped}
-// mode: "init" (新装, 全拷) | "update" (升级, 保护用户数据)
-function copyDirRecursive(src, dst, mode = "init") {
-  let copied = 0, protectedN = 0, skipped = 0;
-  if (!fs.existsSync(src)) return { copied, protectedN, skipped };
-  fs.mkdirSync(dst, { recursive: true });
-  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
-    if (entry.name === "__pycache__" || entry.name.endsWith(".pyc")) continue;
-    const s = path.join(src, entry.name);
-    const d = path.join(dst, entry.name);
-    if (entry.isDirectory()) {
-      const r = copyDirRecursive(s, d, mode);
-      copied += r.copied; protectedN += r.protectedN; skipped += r.skipped;
-    } else {
-      const isEngine = entry.name.endsWith(".py") || entry.name.endsWith(".md") ||
-                       entry.name.endsWith(".yaml") || entry.name.endsWith(".yml") ||
-                       entry.name.endsWith(".toml") || entry.name.endsWith(".json") ||
-                       entry.name.endsWith(".html") || entry.name.endsWith(".txt");
-
-      if (mode === "update") {
-        // 升级模式: 受保护文件绝不覆盖
-        if (PROTECTED_FILES.has(entry.name) && fs.existsSync(d)) {
-          // 新版内容存为 .new 让用户手动合并（仅当内容不同）
-          if (!filesEqual(s, d)) {
-            fs.copyFileSync(s, d + ".new");
-            protectedN++;
-          } else {
-            skipped++;
-          }
-          continue;
-        }
-        // 引擎文件: 无条件刷新（纯引擎, 不含用户数据）
-        // 非引擎文件: 已存在跳过, 不存在才建
-        if (isEngine || !fs.existsSync(d)) {
-          fs.copyFileSync(s, d);
-          copied++;
-        } else {
-          skipped++;
-        }
-      } else {
-        // init 模式: 引擎文件全覆盖, 非引擎已存在跳过 (保留用户改动)
-        if (isEngine || !fs.existsSync(d)) {
-          fs.copyFileSync(s, d);
-        }
-        copied++;
-      }
-    }
-  }
-  return { copied, protectedN, skipped };
-}
-
-// 两文件内容是否相同（先比大小再比内容）
-function filesEqual(a, b) {
-  try {
-    const sa = fs.statSync(a), sb = fs.statSync(b);
-    if (sa.size !== sb.size) return false;
-    return fs.readFileSync(a).equals(fs.readFileSync(b));
-  } catch { return false; }
-}
-
-// 版本戳: .qoder/.engine-version 存当前引擎版本
-function writeEngineVersion(cwd) {
-  try {
-    const p = path.join(cwd, ".qoder", ".engine-version");
-    fs.mkdirSync(path.dirname(p), { recursive: true });
-    fs.writeFileSync(p, PKG_VERSION + "\n", "utf-8");
-  } catch { /* 不阻塞 */ }
-}
-
-function readEngineVersion(cwd) {
-  try {
-    const p = path.join(cwd, ".qoder", ".engine-version");
-    if (fs.existsSync(p)) return fs.readFileSync(p, "utf-8").trim();
-  } catch { /* */ }
-  return null;
-}
-
-// 跑 install_qoderwork.py（升级时强制刷新 commands）
-function runQoderWorkInstall(cwd, forceCommands) {
-  const script = path.join(cwd, ".qoder", "scripts", "install_qoderwork.py");
-  if (!fs.existsSync(script)) {
-    console.log("  [跳过] install_qoderwork.py 不存在");
-    return;
-  }
-  const args = ["python", `"${script}"`];
-  if (forceCommands) args.push("--force-commands");
-  try {
-    console.log(`\n--- 刷新 QoderWork ---`);
-    execSync(args.join(" "), { cwd, stdio: "inherit", timeout: 60000 });
-  } catch (e) {
-    console.log(`  QoderWork 刷新失败 (不阻塞): ${(e.message || "").slice(0, 80)}`);
-  }
-}
-
-function doStatus() {
-  console.log("");
-  const dev = path.join(process.cwd(), ".qoder", ".developer");
-  if (fs.existsSync(dev)) {
-    // 解析 .developer 的 name= 和 role= 行
-    const lines = fs.readFileSync(dev, "utf-8").split("\n");
-    const nameLine = lines.find(l => l.startsWith("name="));
-    const roleLine = lines.find(l => l.startsWith("role="));
-    const name = nameLine ? nameLine.split("=")[1]?.trim() : "?";
-    const role = roleLine ? roleLine.split("=")[1]?.trim() : "pm";
-    console.log(`dev: ${name} (角色: ${role})`);
-    if (!roleLine) {
-      console.log(`  ⚠ 角色未设置 (默认 pm)。重跑: npx @hupan56/wlkj init ${name} <pm|design|dev|test|admin>`);
-    }
-  } else {
-    console.log("dev: - (未初始化。跑: npx @hupan56/wlkj init <名字> <角色>)");
-    console.log("  角色: 产品(pm)/设计(design)/开发(dev)/测试(test)/管理(admin)");
-  }
-
-  process.stdout.write(py("task.py", ["current", "--source"]));
-
-  const wsSpecs = path.join(process.cwd(), "workspace", "specs", "prd");
-  if (fs.existsSync(wsSpecs)) {
-    const n = fs.readdirSync(wsSpecs).filter(f => f.endsWith(".md")).length;
-    console.log(`PRDs: ${n}`);
-  }
-  const ver = readEngineVersion(process.cwd());
-  console.log(`engine: ${ver || "未知"} (最新: v${PKG_VERSION})${ver === PKG_VERSION ? " [最新]" : ver ? " [可升级: npx @hupan56/wlkj update]" : ""}`);
-  console.log("");
-}
-
-function doUpdate() {
-  const cwd = process.cwd();
-  const oldVer = readEngineVersion(cwd);
-  const qoderSrc = path.join(T, "qoder");
-
-  // 前置检查: 必须已装过
-  if (!fs.existsSync(path.join(cwd, ".qoder", "scripts"))) {
-    console.log("\n  未检测到已安装的引擎。首次安装请用:");
-    console.log("    npx @hupan56/wlkj init [你的名字]\n");
-    return;
-  }
-
-  console.log(`\nwlkj update${oldVer ? " " + oldVer : ""} -> v${PKG_VERSION}\n`);
-
-  // P1-15: 显式声明 update 绝不触碰的路径
-  console.log("  受保护路径 (绝不覆盖):");
-  console.log("    .qoder/config.yaml          (团队 git 配置)");
-  console.log("    .qoder/settings.json         (权限/hook 配置)");
-  console.log("    .qoder/.developer            (你的身份)");
-  console.log("    .qoder/.current-task         (当前任务)");
-  console.log("    .qoder/.engine-version       (版本戳)");
-  console.log("    workspace/                   (你的全部产出)");
-  console.log("    data/                        (代码仓库+知识图谱)");
-  console.log("");
-
-  // === 1. 刷新引擎文件（保护 config.yaml / settings.json）===
-  let copied = 0, protectedN = 0, skipped = 0;
-  if (fs.existsSync(qoderSrc)) {
-    const r = copyDirRecursive(qoderSrc, path.join(cwd, ".qoder"), "update");
-    copied = r.copied; protectedN = r.protectedN; skipped = r.skipped;
-  }
-  console.log(`  引擎刷新: ${copied} 个文件${skipped ? ` / ${skipped} 无变化` : ""}`);
-
-  // 报告受保护文件
-  if (protectedN > 0) {
-    console.log(`  [保护] ${protectedN} 个配置文件已保留你的本地设置:`);
-    console.log(`         新版模板存为 .new 文件, 如需合并新结构请手动对比:`);
-    // 列出实际生成的 .new 文件
-    try {
-      for (const f of fs.readdirSync(path.join(cwd, ".qoder"))) {
-        if (f.endsWith(".new")) {
-          console.log(`           .qoder/${f}`);
-        }
-      }
-    } catch { /* */ }
-  } else {
-    console.log(`  config.yaml / settings.json: 已保护（未改动）`);
-  }
-
-  // === 2. 根文件（文档 + requirements.txt, 始终覆盖保证最新）===
-  ["root/AGENTS.md", "root/新手指南.md", "root/requirements.txt"].forEach(f => {
-    const src = path.join(T, f);
-    if (fs.existsSync(src)) {
-      fs.copyFileSync(src, path.join(cwd, path.basename(f)));
-    }
-  });
-  console.log(`  根文档 + requirements.txt: 已更新`);
-
-  // === 2.5. git pull 拉最新团队数据 (kg.duckdb/kg_db.duckdb/PRD等在git里) ===
-  // git pull 失败会导致 kg.duckdb 拿不到 → kg MCP 无数据(但仍能连)。
-  // 失败原因常见: 未配 git 身份 / 远程仓库需要认证 / 网络问题 / 分支没tracking。
-  // 这里给出清晰诊断, 不让"git pull 失败"变成无声的静默跳过。
-  // 前置: 自愈分支 tracking (老版 init 配了 remote 但没 set-upstream, pull 会报
-  //       "no tracking information"。这里检测到就补上, 老用户 update 也能自动修)
-  try {
-    const { execSync: _es } = require("child_process");
-    // 先看当前分支有没有 upstream
-    let _trackOk = false;
-    try {
-      _es("git rev-parse --abbrev-ref --symbolic-full-name @{u}", { cwd, encoding: "utf-8", timeout: 5000, stdio: "pipe" });
-      _trackOk = true;  // 有 upstream, 正常
-    } catch {
-      // 没 tracking — 尝试补设 (有 origin remote 的前提下)
-      try {
-        const _remote = _es("git remote", { cwd, encoding: "utf-8", timeout: 5000, stdio: "pipe" }).trim();
-        if (_remote.split(/\s+/).includes("origin")) {
-          _es("git fetch origin", { cwd, encoding: "utf-8", timeout: 30000, stdio: "pipe" });
-          // 确定本地分支名
-          const _branch = _es("git rev-parse --abbrev-ref HEAD", { cwd, encoding: "utf-8", timeout: 5000, stdio: "pipe" }).trim();
-          // 远程用 master 还是 main
-          let _remoteBranch = null;
-          for (const _c of ["master", "main"]) {
-            try {
-              _es(`git rev-parse --verify remotes/origin/${_c}`, { cwd, encoding: "utf-8", timeout: 5000, stdio: "pipe" });
-              _remoteBranch = _c; break;
-            } catch { /* 该分支不存在, 试下一个 */ }
-          }
-          if (_remoteBranch) {
-            _es(`git branch --set-upstream-to=origin/${_remoteBranch} ${_branch}`, { cwd, encoding: "utf-8", timeout: 5000, stdio: "pipe" });
-            console.log(`  git: 已自动设置上游 tracking (origin/${_remoteBranch})`);
-            _trackOk = true;
-          }
-        }
-      } catch { /* 补 tracking 失败, 走下面的 pull 诊断 */ }
-    }
-    const pullR = _es("git pull --no-rebase 2>&1", { cwd, encoding: "utf-8", timeout: 30000 });
-    if (pullR.includes("Already up to date") || pullR.includes("已经是最新")) {
-      console.log(`  git: 已是最新`);
-    } else if (pullR.includes("CONFLICT") || pullR.includes("conflict")) {
-      console.log(`  git: ⚠️ 有冲突, 跳过pull(不影响本地工作)`);
-    } else {
-      console.log(`  git: 已拉取最新`);
-    }
-  } catch (e) {
-    // git pull 失败诊断: 区分"没配git身份"/"远程要认证"/"网络问题"/"非git仓库"
-    // node execSync 抛异常时, git 的真实报错在 e.stderr/e.stdout, 不能只看 e.message
-    const errMsg = String(e.message || "");
-    const stdout = String((e.stdout || "") + " " + (e.stderr || ""));
-    const combined = (errMsg + " " + stdout).toLowerCase();
-    if (combined.includes("authentication failed") || combined.includes("permission denied") ||
-        combined.includes("could not read username") || combined.includes("不支持密码") ||
-        combined.includes("credentials") || combined.includes("403") || combined.includes("401")) {
-      console.log(`  git: ⚠️ 认证失败 — kg.duckdb 等团队数据拉不到`);
-      console.log(`       原因: git 身份/凭证未配。MCP 能连但无数据。`);
-      console.log(`       修复: npx @hupan56/wlkj init <你的名字> (交互式配 git 账号)`);
-    } else if (combined.includes("not a git repository") || combined.includes("not a git dir") ||
-               combined.includes("unknown revision") || combined.includes("does not have any commits")) {
-      console.log(`  git: ⚠️ 非git仓库或空仓库 — 团队数据拉不到`);
-      console.log(`       原因: 此目录不是 git clone 来的, 或没有 remote。`);
-      console.log(`       修复: npx @hupan56/wlkj init <你的名字> (会配团队远程仓库)`);
-    } else if (combined.includes("timed out") || combined.includes("timeout") ||
-               combined.includes("could not resolve host") || combined.includes("connection refused") ||
-               combined.includes("network is unreachable")) {
-      console.log(`  git: ⚠️ 网络问题 — 连不上远程仓库`);
-      console.log(`       原因: ${stdout.trim().slice(0, 80) || "网络超时/无法解析主机"}`);
-      console.log(`       (kg.duckdb 拉不到, MCP 能连但搜索无结果)`);
-    } else {
-      // 兜底: 显示 git 的真实报错, 不再笼统说 "Command failed"
-      const realErr = stdout.trim() || errMsg;
-      console.log(`  git: ⚠️ 拉取失败 — ${realErr.slice(0, 100)}`);
-      console.log(`       (kg.duckdb 拉不到, MCP 能连但搜索无结果)`);
-    }
-  }
-
-  // === 3. 补装 pip 依赖 (必须在刷 mcp.json 之前!)
-  // 顺序很关键: 先装依赖 → 再写 mcp.json → mcp.json 能选到"已装依赖的Python"
-  // 旧版顺序反了(先写mcp.json再装依赖), 导致 mcp.json 指向没装依赖的Python → MCP 黄。
-  console.log(`\n--- Python 依赖补装 (失败自动切镜像) ---`);
-  const reqFile = path.join(cwd, "requirements.txt");
-  const pyCmd = detectPyCmd();
-  if (pyCmd && fs.existsSync(reqFile)) {
-    installPipDeps(pyCmd, reqFile);
-  } else if (!pyCmd) {
-    console.log(`  [跳过] Python 未装`);
-  } else {
-    console.log(`  [跳过] requirements.txt 不存在`);
-  }
-
-  // === 4. 刷新 QoderWork commands（强制覆盖已存在的）===
-  runQoderWorkInstall(cwd, true);
-
-  // === 5. 写版本戳 ===
-  writeEngineVersion(cwd);
-
-  // === 5b. 清理旧版废弃文件 ===
-  const OBSOLETE_FILES = [
-    // 旧脚本(已替代)
-    ".qoder/workflow.md",                      // 被 rules/wl-pipeline.md 替代
-    ".qoder/scripts/code_index.py",            // 被 git_sync.py 替代
-    ".qoder/scripts/notify.py",                // 被 common/feishu.py 替代
-    ".qoder/scripts/team.py",                  // 被 task.py + team_sync.py 替代
-    "packages/wlkj/templates/cli.js",          // 旧版 CLI
-    ".qoder/templates/qoder/config.toml",      // 旧版配置
-    ".qoder/templates/qoder/scripts/code_index.py",
-    ".qoder/templates/qoder/scripts/notify.py",
-    ".qoder/templates/qoder/scripts/team.py",
-    // 旧命令(已合并进 /wl-prd 和 /wl-design)
-    ".qoder/commands/wl-prd-full.md",
-    ".qoder/commands/wl-prd-quick.md",
-    ".qoder/commands/wl-prd-review.md",
-    ".qoder/commands/wl-design-draw.md",
-    ".qoder/commands/wl-design-scan.md",
-    ".qoder/commands/wl-design-spec.md",
-    // 旧版索引JSON(已迁移到DuckDB, 残留在老用户的data/index/)
-    "data/index/keyword-index.json",
-    "data/index/api-index.json",
-    "data/index/prd-index.json",
-    "data/index/module-map.json",
-    "data/index/prd-code-map.json",
-    "data/index/callgraph.json",
-    "data/index/style-index.json",
-    "data/index/style-meta.json",
-    "data/index/vben-style-reference.json",
-    "data/index/chart-style-reference.json",
-    "data/index/icon-reference.json",
-    "data/index/wiki-index.json",
-    // 旧运行时缓存(自动重建)
-    "data/index/.file-keys.json",
-    "data/index/.inverted-cache.json",
-    "data/index/.api-table-cache.json",
-    // 旧learning空壳(未实现的功能占位)
-    ".qoder/learning/patterns/code-patterns.md",
-    ".qoder/learning/patterns/prd-patterns.md",
-    ".qoder/learning/patterns/review-fixes.md",
-    // 用户级旧命令(已合并的, 清理~/.qoderwork/commands/)
-  ];
-  let cleaned = 0;
-  for (const f of OBSOLETE_FILES) {
-    const fp = path.join(cwd, f);
-    if (fs.existsSync(fp)) {
-      try {
-        if (fs.statSync(fp).isDirectory()) {
-          fs.rmSync(fp, { recursive: true, force: true });
-        } else {
-          fs.unlinkSync(fp);
-        }
-        console.log(`  [清理] 删除废弃文件: ${f}`);
-        cleaned++;
-      } catch (e) { /* 删不掉跳过 */ }
-    }
-  }
-  // 清理 .new 临时文件 (上次升级生成的配置对比文件)
-  try {
-    for (const f of fs.readdirSync(path.join(cwd, ".qoder"))) {
-      if (f.endsWith(".new")) {
-        fs.unlinkSync(path.join(cwd, ".qoder", f));
-        cleaned++;
-      }
-    }
-  } catch { /* */ }
-
-  // 清理用户级旧命令 (已合并的, ~/.qoderwork/commands/)
-  const home = process.env.USERPROFILE || require("os").homedir();
-  const userCmdDir = path.join(home, ".qoderwork", "commands");
-  const OBSOLETE_USER_CMDS = [
-    "wl-prd-full.md", "wl-prd-quick.md", "wl-prd-review.md",
-    "wl-design-draw.md", "wl-design-scan.md", "wl-design-spec.md",
-  ];
-  for (const f of OBSOLETE_USER_CMDS) {
-    const fp = path.join(userCmdDir, f);
-    if (fs.existsSync(fp)) {
-      try { fs.unlinkSync(fp); console.log(`  [清理] 用户级旧命令: ${f}`); cleaned++; }
-      catch { /* */ }
-    }
-  }
-  // 清理 .new 临时文件 (上次升级生成的配置对比文件)
-  try {
-    for (const f of fs.readdirSync(path.join(cwd, ".qoder"))) {
-      if (f.endsWith(".new")) {
-        fs.unlinkSync(path.join(cwd, ".qoder", f));
-        console.log(`  [清理] 删除临时文件: .qoder/${f}`);
-        cleaned++;
-      }
-    }
-  } catch { /* */ }
-  // 清理缓存 (索引重建后失效的旧缓存)
-  const runtimeDir = path.join(cwd, ".qoder", ".runtime");
-  let cacheCleaned = 0;
-  try {
-    for (const f of fs.readdirSync(runtimeDir)) {
-      if (f.startsWith("search-cache-") || f.startsWith("ctx-cache-")) {
-        fs.unlinkSync(path.join(runtimeDir, f));
-        cacheCleaned++;
-      }
-    }
-  } catch { /* */ }
-  if (cleaned > 0 || cacheCleaned > 0) {
-    console.log(`  [清理] 废弃文件 ${cleaned} 个 + 过期缓存 ${cacheCleaned} 个`);
-  }
-
-  // === 6. 刷新 launcher + mcp.json (老用户的可能是旧版/写死路径) ===
-  // 注意: pip 依赖已在第3步装好, 此处 install_qoderwork 会选到"已装依赖的Python"写进 mcp.json
-  try {
-    const home = process.env.USERPROFILE || require("os").homedir();
-    const launcherSrc = path.join(cwd, ".qoder", "scripts", "mcp_launcher.py");
-    const launcherDst = path.join(home, ".qoderwork", "mcp_launcher.py");
-    if (fs.existsSync(launcherSrc)) {
-      fs.mkdirSync(path.dirname(launcherDst), { recursive: true });
-      fs.copyFileSync(launcherSrc, launcherDst);
-      console.log(`  [OK] launcher 已刷新`);
-    }
-    // 刷新 mcp.json 为 launcher 模式 (install_qoderwork.py 的 rewrite 逻辑)
-    const instScript = path.join(cwd, ".qoder", "scripts", "install_qoderwork.py");
-    if (pyCmd && fs.existsSync(instScript)) {
-      try {
-        execSync(`${pyCmd} "${instScript}" --mcp-only`, { stdio: "pipe", timeout: 15000 });
-        console.log(`  [OK] mcp.json 已刷新 (选装了依赖的Python, 避免MCP黄)`);
-      } catch (e) { /* --mcp-only 可能不支持, 静默跳过 */ }
-    }
-  } catch (e) { /* 刷新失败不阻塞升级 */ }
-
-  // === 6.5. MCP 启动实测 (发 initialize 看哪个起不来) ===
-  // 这是"根治黄色"的关键一步: 配完 mcp.json 后立即模拟 QoderWork 发 initialize,
-  // 看每个 MCP 是 OK / DISABLED(绿) / CRASHED(黄)。有问题当场报, 不让用户重启后才发现。
-  console.log(`\n--- MCP 启动实测 (模拟 QoderWork 连接) ---`);
-  const diagScript = path.join(cwd, ".qoder", "scripts", "check_mcp_launch.py");
-  if (pyCmd && fs.existsSync(diagScript)) {
-    try {
-      const env = { ...process.env, PYTHONIOENCODING: "utf-8", PYTHONUTF8: "1" };
-      execSync(`${pyCmd} "${diagScript}"`, { cwd, stdio: "inherit", timeout: 60000, env });
-    } catch (e) {
-      console.log(`  [WARN] MCP 实测脚本异常 (不阻塞): ${(e.message || "").slice(0, 80)}`);
-    }
-  }
-
-  // === 7. 自检: 关键文件到底齐不齐 ===
-  console.log(`\n--- 自检 (关键文件验证) ---`);
-  const checks = [
-    ["requirements.txt", path.join(cwd, "requirements.txt"), "依赖清单(没它pip装不了)"],
-    ["duckdb(pip)", null, "知识图谱核心依赖"],
-    ["kg.duckdb", path.join(cwd, "data", "index", "kg.duckdb"), "代码图谱(MCP需要)"],
-    ["kg_db.duckdb", path.join(cwd, "data", "index", "kg_db.duckdb"), "数据库图谱(table_impact需要)"],
-    [".qoder/commands/", path.join(cwd, ".qoder", "commands"), "斜杠命令"],
-  ];
-  let allOk = true;
-  for (const [label, p, desc] of checks) {
-    if (p === null) {
-      // duckdb 用 python 检测
-      try {
-        execSync(`${pyCmd || "python"} -c "import duckdb"`, { stdio: "pipe", timeout: 5000 });
-        console.log(`  [✓] ${label} - ${desc}`);
-      } catch {
-        console.log(`  [✗] ${label} 缺失! ${desc}`);
-        console.log(`       → 修复: pip install duckdb -i https://pypi.tuna.tsinghua.edu.cn/simple`);
-        allOk = false;
-      }
-    } else if (fs.existsSync(p)) {
-      console.log(`  [✓] ${label}`);
-    } else {
-      console.log(`  [✗] ${label} 缺失! ${desc}`);
-      if (label.includes("duckdb")) {
-        console.log(`       → 修复: npx @hupan56/wlkj run kg_build.py --rebuild`);
-      } else if (label.includes("commands")) {
-        console.log(`       → 修复: npx @hupan56/wlkj update`);
-      }
-      allOk = false;
-    }
-  }
-  if (!allOk) {
-    console.log(`\n  ⚠️ 有缺失项, 按上面的提示修复后重跑 update。`);
-  } else {
-    console.log(`  全部关键文件就绪 ✓`);
-  }
-
-  console.log(`\n${"=".repeat(50)}`);
-  console.log(`  升级完成!  (v${PKG_VERSION})`);
-  console.log(`${"=".repeat(50)}`);
-  console.log(`\n  生效方式:`);
-  console.log(`    Qoder IDE / Quest: 新建对话即可`);
-  console.log(`    QoderWork: 重启应用或新建对话`);
-
-  // 检查 git 身份是否需要配置 (只检测不引导, update 保持轻量)
-  // 老用户如果之前 init 时塞了假账号, 这里提示重跑 init 修正
-  let gitWarn = false;
-  try {
-    const devFile = path.join(cwd, ".qoder", ".developer");
-    if (fs.existsSync(devFile)) {
-      const devName = fs.readFileSync(devFile, "utf-8").trim();
-      const mj = path.join(cwd, "workspace", "members", devName, "member.json");
-      if (fs.existsSync(mj)) {
-        const m = JSON.parse(fs.readFileSync(mj, "utf-8"));
-        const ga = m.git_author || "";
-        if (!ga || ga.includes("@local") || ga.includes("@unknown")) {
-          gitWarn = true;
-        }
-      }
-    }
-  } catch { /* 检测失败不阻塞 */ }
-
-  if (gitWarn) {
-    console.log(`\n  ⚠ git 账号未配置或为假账号 (push/同步会失败)`);
-    console.log(`    重跑初始化可修复: npx @hupan56/wlkj init <你的名字>`);
-    console.log(`    (init 会交互式引导你配置团队 git 账号和团队仓库)`);
-  } else {
-    console.log(`\n  如果还没配过 git 账号或团队仓库, 重跑: npx @hupan56/wlkj init <你的名字>`);
-  }
-
-  if (protectedN > 0) {
-    console.log(`\n  ⚠ 有配置文件新版有变化, 生成 .new 文件:`);
-    console.log(`    确认无需合并后可直接删除, 或手动合并后删除`);
-  }
-  console.log("");
-}
-
-function doHelp() {
-  console.log("");
-  console.log(`wlkj - AI 产品研发工作流 (v${PKG_VERSION})`);
-  console.log("");
-  console.log("=== 5 个核心命令 (记住这 5 个就够) ===");
-  console.log("");
-  console.log("  npx @hupan56/wlkj install-env    ① 装环境 (Node/Python/git/pip依赖)");
-  console.log("  npx @hupan56/wlkj init [名字]    ② 装引擎 + 初始化身份");
-  console.log("  npx @hupan56/wlkj update         ③ 升级 (刷新引擎+补依赖+刷MCP)");
-  console.log("  npx @hupan56/wlkj doctor         ④ 体检 (环境/依赖/图谱健康度)");
-  console.log("  npx @hupan56/wlkj sync           ⑤ 推送产出 (PRD/任务/原型)");
-  console.log("");
-  console.log("=== 万能跑 (想跑任何脚本) ===");
-  console.log("  npx @hupan56/wlkj run <脚本名> [参数]");
-  console.log("  例: npx wlkj run kg_build.py --rebuild");
-  console.log("      npx wlkj run eval_prd.py xxx.md");
-  console.log("");
-  console.log("=== Qoder 里怎么用 (日常就在这里干) ===");
-  console.log("  说中文: '写个XX的需求' '查XX代码' '建任务' '测一下XX'");
-  console.log("  或斜杠: /wl-prd /wl-design /wl-task /wl-code /wl-test /wl-commit");
-  console.log("");
-  console.log("  看不到命令? 新建对话 / 重启 QoderWork");
-  console.log("");
-}
-
-function doInstallEnv(checkOnly = false, location = null) {
-  const { execSync } = require("child_process");
-  const isWin = process.platform === "win32";
-  const isMac = process.platform === "darwin";
-
-  // 解析 --location（CLI 入口已提取，这里兜底）
-  console.log("\n=== 环境检测 ===\n");
-  if (location) {
-    console.log(`  安装位置: ${location}${isWin ? "" : " (仅 Windows winget 支持指定目录)"}`);
-    // Windows: 预建目录
-    if (isWin) {
-      try { fs.mkdirSync(location, { recursive: true }); } catch { /* */ }
-    }
-  }
-
-  // 检测函数
-  function check(cmd) {
-    try { return execSync(`${cmd} --version`, { encoding: "utf-8", timeout: 5000, stdio: "pipe" }).trim().split("\n")[0]; }
-    catch { return null; }
-  }
-  function has(cmd) {
-    try { execSync(`where ${cmd}`, { encoding: "utf-8", timeout: 3000, stdio: "pipe" }); return true; }
-    catch { try { execSync(`which ${cmd}`, { encoding: "utf-8", timeout: 3000, stdio: "pipe" }); return true; } catch { return false; } }
-  }
-  // Windows: 把目录加到用户 PATH（幂等，已存在不重复加）
-  function addToPathWin(dir) {
-    if (!isWin) return false;
-    try {
-      // 用 setx 会截断超长 PATH，改用 PowerShell 读 User PATH 追加
-      const ps = `powershell -NoProfile -Command "$p=[Environment]::GetEnvironmentVariable('Path','User'); if($p -notlike '*{dir}*'){[Environment]::SetEnvironmentVariable('Path',$p.TrimEnd(';')+';{dir}','User')}"`.replace(/{dir}/g, dir.replace(/\\/g, "\\\\"));
-      execSync(ps, { stdio: "pipe", timeout: 15000 });
-      return true;
-    } catch (e) { console.log(`  [WARN] 加 PATH 失败（可手动加）: ${dir}`); return false; }
-  }
-  function install(name, wingetId, brewPkg) {
-    if (checkOnly) return false;
-    try {
-      if (isWin && has("winget")) {
-        console.log(`  用 winget 装 ${name}...`);
-        // winget --location 不一定被安装包尊重，但先传上
-        let cmd = `winget install --id ${wingetId} -e --source winget --accept-source-agreements --accept-package-agreements`;
-        if (location) cmd += ` --location "${location}"`;
-        execSync(cmd, { stdio: "inherit", timeout: 300000 });
-        return true;
-      } else if (isMac && has("brew")) {
-        console.log(`  用 brew 装 ${name}...`);
-        execSync(`brew install ${brewPkg}`, { stdio: "inherit", timeout: 300000 });
-        return true;
-      } else if (!isWin && !isMac) {
-        // Linux: 尝试 apt/dnf/yum
-        for (const [mgr, pkg] of [["apt", brewPkg], ["dnf", brewPkg]]) {
-          if (has(mgr)) {
-            console.log(`  用 ${mgr} 装 ${name}...`);
-            execSync(`sudo ${mgr} install -y ${pkg}`, { stdio: "inherit", timeout: 300000 });
-            return true;
-          }
-        }
-      }
-    } catch (e) { console.log(`  自动安装失败: ${(e.message || "").slice(0, 80)}`); }
-    return false;
-  }
-
-  const nodeVer = check("node");
-  const pyVer = check("python") || check("python3");
-  const gitVer = check("git");
-
-  console.log(`  Node.js: ${nodeVer ? "[OK] " + nodeVer : "[缺失] (npx 命令需要)"}`);
-  console.log(`  Python:  ${pyVer ? "[OK] " + pyVer : "[缺失] (引擎需要)"}`);
-  console.log(`  git:     ${gitVer ? "[OK] " + gitVer : "[缺失] (可选, 核心功能不依赖)"}`);
-
-  if (checkOnly) {
-    console.log("\n仅检测。去掉 --check 自动安装。");
-    return;
-  }
-
-  const need = [];
-  if (!nodeVer) {
-    console.log("");
-    if (nodeVer || install("Node.js", "OpenJS.NodeJS.LTS", "node")) { console.log(`  [OK] Node.js 已装`); }
-    else { need.push("Node.js (手动: https://nodejs.org)"); }
-  }
-  if (!pyVer) {
-    console.log("");
-    if (install("Python", "Python.Python.3.12", "python@3.12")) { console.log(`  [OK] Python 已装`); }
-    else { need.push("Python (手动: https://python.org, 勾 Add to PATH)"); }
-  }
-  if (!gitVer) {
-    console.log("");
-    if (install("git", "Git.Git", "git")) { console.log(`  [OK] git 已装`); }
-    else { need.push("git (手动: https://git-scm.com, 可选)"); }
-  }
-
-  // --location 模式: 提示用户验证安装位置 + 手动加 PATH
-  // （winget 的 --location 对 Node/Python 不一定生效，需用户确认）
-  if (location && isWin) {
-    console.log(`\n--- 安装位置确认 ---`);
-    console.log(`  你指定了: ${location}`);
-    console.log(`  注意: winget 的 --location 对 Node.js/Python 不一定生效`);
-    console.log(`        (取决于安装包是否支持自定义路径)`);
-    console.log(`  请检查实际装到哪了:`);
-    console.log(`    重新打开终端后跑: node --version  python --version  git --version`);
-    console.log(`  如果某软件没进 PATH, 手动把它加进去:`);
-    console.log(`    设置 → 系统 → 关于 → 高级系统设置 → 环境变量 → Path → 新建`);
-    console.log(`    或用命令: npx @hupan56/wlkj add-path "D:\\wldev\\nodejs"`);
-  }
-
-  // Python pip 依赖 (知识图谱/MCP/测试需要)
-  console.log("\n--- Python 依赖 ---");
-  const pyCmd = check("python") ? "python" : (check("python3") ? "python3" : null);
-  if (pyCmd) {
-    // 找 requirements.txt: 引擎已安装则用 .qoder/scripts/../requirements.txt
-    const reqPaths = [
-      path.join(process.cwd(), "requirements.txt"),
-      path.join(process.cwd(), ".qoder", "..", "requirements.txt"),
-    ].filter(p => fs.existsSync(p));
-    if (reqPaths.length > 0) {
-      console.log(`  安装 pip 依赖: ${path.basename(reqPaths[0])} (失败自动切国内镜像)`);
-      installPipDeps(pyCmd, reqPaths[0]);
-    } else {
-      console.log("  [跳过] 未找到 requirements.txt (先 npx @hupan56/wlkj init 安装引擎)");
-    }
-  } else {
-    console.log("  [跳过] Python 未装, 无法装 pip 依赖");
-  }
-
-  console.log("\n=== 结果 ===");
-  if (need.length === 0) {
-    console.log("  环境就绪! 下一步: npx @hupan56/wlkj init");
-    console.log("  (新装的可能需要重新打开终端)");
-  } else {
-    console.log("  以下需手动安装:");
-    need.forEach(n => console.log("    - " + n));
-  }
-}
-
-// add-path: 把目录加到 Windows 用户 PATH（幂等）
-function doAddPath(dir) {
-  if (!dir) { console.log("用法: npx @hupan56/wlkj add-path <目录>"); return; }
-  if (process.platform !== "win32") {
-    console.log("add-path 仅支持 Windows。Mac/Linux 请手动加到 ~/.zshrc 或 ~/.bashrc");
-    return;
-  }
-  const abs = path.resolve(dir);
-  if (!fs.existsSync(abs)) {
-    console.log(`[警告] 目录不存在: ${abs}（仍会加到 PATH）`);
-  }
-  try {
-    const ps = `powershell -NoProfile -Command "$p=[Environment]::GetEnvironmentVariable('Path','User'); if($p -notlike '*${abs.replace(/\\/g,"\\\\")}*'){[Environment]::SetEnvironmentVariable('Path',$p.TrimEnd(';')+';${abs.replace(/\\/g,"\\\\")}','User'); Write-Output 'ADDED'} else { Write-Output 'EXISTS' }"`;
-    const out = execSync(ps, { encoding: "utf-8", timeout: 15000 }).trim();
-    console.log(`  ${out === "ADDED" ? "已加入" : "已存在(无需重复加)"}: ${abs}`);
-    console.log(`  ⚠ 需要重新打开终端才生效`);
-  } catch (e) {
-    console.log(`  失败: ${(e.message || "").slice(0, 100)}`);
-    console.log(`  手动加: 设置 → 系统 → 关于 → 高级系统设置 → 环境变量 → Path → 新建 → ${abs}`);
-  }
-}
-
-const [,, cmd, ...rest] = process.argv;
-const mapped = rest.map(a => a === "-p" ? "--priority" : a);
-
-switch (cmd) {
-  case "init": doInit(rest[0], rest[1]); break;
-  case "update": case "upgrade": doUpdate(); break;
-  case "install-env": {
-    const checkOnly = rest.includes("--check");
-    // 提取 --location <dir> 或 --location=<dir>
-    let loc = null;
-    const li = rest.indexOf("--location");
-    if (li !== -1 && rest[li + 1]) loc = rest[li + 1];
-    const eq = rest.find(a => a.startsWith("--location="));
-    if (eq) loc = eq.slice("--location=".length);
-    doInstallEnv(checkOnly, loc);
-    break;
-  }
-  case "add-path": doAddPath(rest[0]); break;
-  case "task": process.stdout.write(py("task.py", mapped)); break;
-  case "status": doStatus(); break;
-  case "session": process.stdout.write(py("add_session.py", rest)); break;
-  case "help": case "--help": case "-h": doHelp(); break;
-
-  // ── 核心 5 个: 装/升/体检/同步/万能跑 ──
-  case "doctor": case "体检":
-    runScript("init_doctor.py", rest); break;
-  case "sync": case "push": case "commit":
-    runScript("team_sync.py", ["push", ...rest.filter(a => a !== "push")]); break;
-  case "pull":
-    runScript("team_sync.py", ["pull"]); break;
-
-  // ── 万能透传: npx wlkj run <脚本名> [参数...] ──
-  // 任何 .qoder/scripts/ 下的脚本都能跑, 不用记命令名
-  // 例: npx wlkj run kg_build.py --rebuild
-  //     npx wlkj run eval_prd.py xxx.md
-  //     npx wlkj run autotest.py quick
-  case "run": {
-    if (!rest[0]) { console.log("用法: npx wlkj run <脚本名> [参数...]\n例: npx wlkj run kg_build.py --rebuild"); break; }
-    runScript(rest[0], rest.slice(1));
-    break;
-  }
-
-  case "提交": case "拉取最新": case "同步":
-  case "查看状态": case "提交PRD": case "提交Spec": case "提交任务":
-    gitOp(cmd); break;
-  default: doHelp();
+#!/usr/bin/env node
+// wlkj - workflow toolkit
+
+const path = require("path");
+const fs = require("fs");
+const { execSync } = require("child_process");
+
+const T = path.join(__dirname, "..", "templates");
+
+// 当前 npm 包版本（从 package.json 读，不硬编码）
+const PKG_VERSION = JSON.parse(
+  fs.readFileSync(path.join(__dirname, "..", "package.json"), "utf-8")
+).version;
+
+// 升级时受保护的用户数据文件（绝不覆盖）
+// 这些文件含团队/机器特定配置，覆盖 = 数据丢失
+const PROTECTED_FILES = new Set([
+  "config.yaml",        // 团队 git 仓库 URL、平台映射
+  "settings.json",      // 本地权限/hook 配置
+]);
+
+// 本地状态文件（升级时也绝不碰，但不算"受保护配置"，不提示合并）
+const LOCAL_STATE_FILES = new Set([
+  ".developer", ".current-task", ".engine-version",
+]);
+
+// 探测可用的 Python 命令 (python 或 python3)。
+// macOS 系统通常只有 python3, 硬编码 python 会让 Mac 全员失败。
+// 探测结果缓存到全局, 避免每次调用都 fork 进程。
+let _PY_CMD_CACHE = null;
+function detectPyCmd() {
+  if (_PY_CMD_CACHE) return _PY_CMD_CACHE;
+  // ⚠ 必须校验是 Python 3.8+! 不能只看 exit 0 ——
+  //   老企业机/某些 RHEL 上 `python` 仍指向 2.7 (exit 0), 引擎要 3.8+,
+  //   误选 2.7 会被缓存 → 后续所有 py()/runScript 全用 2.7 跑 → setup.py 直接失败。
+  //   检查 --version 输出以 "Python 3." 开头, 且次版本 >=8。
+  for (const c of ["python", "python3"]) {
+    try {
+      const out = execSync(`${c} --version`, { encoding: "utf-8", timeout: 5000, stdio: "pipe" });
+      const m = /Python\s+3\.(\d+)/i.exec((out || "").trim());
+      if (m && parseInt(m[1], 10) >= 8) {
+        _PY_CMD_CACHE = c;
+        return c;
+      }
+      // 是 python 但版本不够 (2.7 或 3.0-3.7) → 跳过试下一个候选
+    } catch { /* try next */ }
+  }
+  _PY_CMD_CACHE = null;
+  return null;
+}
+
+function py(script, args = []) {
+  // v3.x: 不再直接找扁平路径 (scripts/<script>), 改为转发 wlkj.py 单一真源调度器。
+  // 根治 "引擎分层重组后 cli.js 路径全部失效" 的载体漂移。
+  const wlkj = path.join(process.cwd(), ".qoder", "scripts", "orchestration", "wlkj.py");
+  if (!fs.existsSync(wlkj)) { console.log("请先运行: npx wlkj init"); process.exit(1); }
+  const pyCmd = detectPyCmd();
+  if (!pyCmd) { console.log("Python 未安装, 无法运行脚本。跑: npx @hupan56/wlkj install-env"); return ""; }
+  // 把脚本名当命令传给 wlkj.py (DISPATCH 命中则路由, 否则 run fallback 递归找)
+  try {
+    const cmdName = script.replace(/\.py$/, "").replace(/\//g, "-");
+    return execSync(`${pyCmd} "${wlkj}" ${cmdName} ${args.map(a => `"${a}"`).join(" ")}`, { cwd: process.cwd(), encoding: "utf-8", timeout: 15000, env: { ...process.env, PYTHONIOENCODING: "utf-8", PYTHONUTF8: "1" } });
+  } catch (e) { return (e.stdout || e.message); }
+}
+
+// 透传执行: 直接 spawn (不捕获输出, 实时显示, 支持长超时和交互式)
+// 用于 kg_build/eval_prd/autotest 等耗时脚本, 以及需要交互的场景
+function runScript(scriptName, args = [], timeoutMs = 600000) {
+  // v3.x: 转发 wlkj.py 单一真源 (不再直接找扁平 scripts/<scriptName>)
+  const wlkj = path.join(process.cwd(), ".qoder", "scripts", "orchestration", "wlkj.py");
+  if (!fs.existsSync(wlkj)) { console.log("引擎未安装。跑: npx @hupan56/wlkj init"); process.exit(1); }
+  const pyCmd = detectPyCmd();
+  if (!pyCmd) { console.log("Python 未安装。跑: npx @hupan56/wlkj install-env"); process.exit(1); }
+  const { spawnSync } = require("child_process");
+  const env = { ...process.env, PYTHONIOENCODING: "utf-8", PYTHONUTF8: "1" };
+  // 脚本名作为命令传给 wlkj.py (DISPATCH 命中则路由, 否则 run fallback 递归找)
+  const cmdName = scriptName.replace(/\.py$/, "").replace(/\//g, "-");
+  const r = spawnSync(pyCmd, [wlkj, cmdName, ...args], { cwd: process.cwd(), stdio: "inherit", timeout: timeoutMs, encoding: "utf-8", env });
+  process.exit(r.status || 0);
+}
+
+// 带镜像兜底的 pip 安装 —— 复用 Python 的 common/pip_install.py (单一事实源)
+// 为什么不复用 Python: 上一轮给 init_doctor 做了 common/pip_install.py (失败切清华/阿里/腾讯)。
+// cli.js 的 install-env/update 是独立 JS 路径, 之前没享受镜像兜底 → 50 人里弱网用户全崩。
+// 这里调用同一个 Python 工具, 保证两路径行为一致。
+//
+// 优先: 引擎已装 → 调 foundation.utils.pip_install (有镜像兜底)
+// 回退: 引擎没装 → 裸 pip install (install-env 首次场景, 无 Python 工具可用)
+//
+// 实现注意 (修 2.7.0 的真 bug): 不能用字符串拼接构造 Python -c 代码 ——
+// Windows 路径含反斜杠, 拼进 Python 字符串后 \Y \n 等成了非法转义 + 引号丢失,
+// 导致 SyntaxError → 镜像兜底静默失败 → 回退裸 pip → 弱网用户全崩。
+// 改用环境变量传参 (WLKJ_REQ_PATH), Python 侧 os.environ 读, 彻底避开转义地狱。
+function installPipDeps(pyCmd, reqPath) {
+  // ⚠ v3.x 重写: 直接用 Node spawnSync 跑 pip (不嵌套 Python 子进程)。
+  // 原方案 `python -c "...install_with_fallback..."` 在 Anaconda 3.9+ Windows 下,
+  // pip 进镜像重试(长时间编译 tree-sitter/playwright)退出时会触发
+  // "PyEval_SaveThread: GIL released" 致命崩溃 → Python 死、结果丢失、回退裸 pip、
+  // 弱网新机装不上。Node 直接跑 pip 不嵌套 Python, 无此 GIL 问题。
+  // 镜像兜底逻辑在 JS 侧复刻同一策略 (默认源→清华→阿里→腾讯), 行为与 Python 版一致。
+  const { spawnSync } = require("child_process");
+  const MIRRORS = [
+    ["清华", "https://pypi.tuna.tsinghua.edu.cn/simple"],
+    ["阿里", "https://mirrors.aliyun.com/pypi/simple/"],
+    ["腾讯", "https://mirrors.cloud.tencent.com/simple"],
+  ];
+  const installEnv = { ...process.env, PYTHONIOENCODING: "utf-8", PYTHONUTF8: "1" };
+
+  function runPip(extraArgs, timeoutMs) {
+    // stdio inherit 让用户看到进度; 不捕获输出 = 不撑管道、不触发任何崩溃
+    const r = spawnSync(pyCmd, ["-m", "pip", "install", "--no-input", "--progress-bar", "off", ...extraArgs, "-r", reqPath],
+      { stdio: "inherit", timeout: timeoutMs || 300000, encoding: "utf-8", env: installEnv });
+    return r.status === 0;
+  }
+
+  function pkgsInstalled() {
+    // 轻量 import 验证: 不跑 pip 子进程, 只 python -c "import ...", 无 GIL 风险。
+    // 核心包都 import 成功就算装好 (即使某些可选包编译失败 pip 返回非0)。
+    const coreMods = ["duckdb", "pymysql", "yaml", "requests"];
+    const mod = coreMods.map(m => "__import__('%s')".replace("%s", m)).join(";");
+    try {
+      const r = spawnSync(pyCmd, ["-c", mod], { encoding: "utf-8", timeout: 15000, env: installEnv, stdio: "pipe" });
+      return r.status === 0;
+    } catch { return false; }
+  }
+
+  // 已装好就不折腾 (常见: 老机器 update, 依赖都在)
+  if (pkgsInstalled()) {
+    console.log("  [OK] Python 依赖已就绪");
+    return true;
+  }
+
+  // 1. 默认源 (国内常被拦, 短超时快速判定)
+  console.log("  试默认源(PyPI)...");
+  let ok = runPip([], 60000);
+  if (ok || pkgsInstalled()) { console.log("  [OK] Python 依赖已装"); return true; }
+
+  // 2. 默认源失败 → 逐个国内镜像
+  for (const [name, url] of MIRRORS) {
+    console.log(`  默认源失败, 切镜像(${name})...`);
+    ok = runPip(["-i", url, "--trusted-host", url.replace(/^https?:\/\//, "").split("/")[0]], 300000);
+    if (ok || pkgsInstalled()) {
+      console.log(`  [OK] Python 依赖已装 (镜像源: ${name})`);
+      return true;
+    }
+  }
+
+  // 3. 全失败
+  console.log("  [WARN] pip 安装失败 (尝试了所有镜像)");
+  console.log("  可能原因: 网络/防火墙/公司代理拦截 PyPI。");
+  console.log("  手动装 (用清华镜像): pip install -i https://pypi.tuna.tsinghua.edu.cn/simple -r requirements.txt");
+  console.log("  或配全局镜像: pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple");
+  return false;
+}
+
+function cp(src, dest) {
+  const s = path.join(T, src), d = path.join(process.cwd(), dest);
+  if (!fs.existsSync(s)) return;
+  fs.mkdirSync(path.dirname(d), { recursive: true });
+  if (!fs.existsSync(d)) { fs.copyFileSync(s, d); return true; }
+  return false;
+}
+
+function gitOp(op) {
+  const cwd = process.cwd();
+  const cmds = {
+    "提交": 'git add . && git commit -m "update [ai-assisted]" && git push',
+    "推送": "git push",
+    "拉取最新": "git pull",
+    "同步": "git pull",
+    "查看状态": "git status",
+    "提交PRD": 'git add workspace/specs/prd/ && git commit -m "docs(ai): PRD update [ai-generated]" && git push',
+    "提交Spec": 'git add workspace/specs/ && git commit -m "docs(ai): Spec update [ai-generated]" && git push',
+    "提交任务": 'git add workspace/tasks/ && git commit -m "chore: task update [ai-assisted]" && git push',
+  };
+  const cmd = cmds[op];
+  if (!cmd) { console.log("可用: 提交 推送 拉取最新 同步 查看状态 提交PRD 提交Spec 提交任务"); return; }
+  try { console.log(execSync(cmd, { cwd, encoding: "utf-8", timeout: 30000, stdio: "pipe" }) || `${op} done`); }
+  catch (e) { console.log(e.stdout || e.message); }
+}
+
+// 快速环境检测 (init 前置): 缺 Python 致命退出, 缺 git 警告不阻塞
+// 目的: 杜绝"裸机没 Python 时 init 静默失败仍宣布成功"的假成功
+function checkEnvQuick() {
+  console.log("--- 环境检测 ---");
+  // Node 一定有 (npx 在跑), 输出 version 确认
+  console.log(`  Node.js: [OK] ${process.version}`);
+
+  // Python: python 或 python3 任一可用即可
+  let pyCmd = null, pyVer = null;
+  for (const c of ["python", "python3"]) {
+    try {
+      const v = execSync(`${c} --version`, { encoding: "utf-8", timeout: 5000, stdio: "pipe" }).trim();
+      pyCmd = c; pyVer = v; break;
+    } catch { /* try next */ }
+  }
+  if (!pyCmd) {
+    console.log("  Python:  [缺失] (引擎必需)");
+    console.log("\n  ⚠ 没装 Python, 无法继续。请先装环境:");
+    console.log("    npx @hupan56/wlkj install-env");
+    console.log("    (自动装 Node/Python/git + pip 依赖; 装完重开终端再 init)\n");
+    return { ok: false, pyCmd: null };
+  }
+  console.log(`  Python:  [OK] ${pyVer} (${pyCmd})`);
+
+  // git: 可选, 缺了只警告 (与 init_doctor 口径一致)
+  try {
+    const gv = execSync("git --version", { encoding: "utf-8", timeout: 5000, stdio: "pipe" }).trim();
+    console.log(`  git:     [OK] ${gv}`);
+  } catch {
+    console.log("  git:     [缺失] (可选, 团队同步/源码克隆将禁用, 本地 PRD/搜索/任务仍可用)");
+    console.log("           想启用: npx @hupan56/wlkj install-env");
+  }
+  console.log("");
+  return { ok: true, pyCmd };
+}
+
+// 交互式问角色 (50 人团队角色各异, 不能写死 pm)
+// 支持的角色 (与 config.yaml / kg.py ROLE_SECTIONS 对齐)
+const ROLES = [
+  { key: "pm", label: "产品经理 (PM) — 写需求/PRD/任务" },
+  { key: "design", label: "设计师 (UI) — 录入设计稿/出原型" },
+  { key: "dev", label: "开发 (前端/后端) — 写代码/提交/测试" },
+  { key: "test", label: "测试 (QA) — 跑测试用例/验证" },
+  { key: "admin", label: "管理员 — 管理/维护工作流" },
+];
+
+function askRole() {
+  // 非交互环境 (CI/AI 调用) 默认 pm
+  if (!process.stdin.isTTY) {
+    console.log("  (非交互环境, 默认角色: pm)");
+    return "pm";
+  }
+  console.log("\n  你的角色是? (决定命令视角和建议)");
+  ROLES.forEach((r, i) => console.log(`    ${i + 1}. ${r.label}`));
+  const readline = require("readline").createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    readline.question("\n  选择 (1-5, 默认1): ", (ans) => {
+      readline.close();
+      const idx = parseInt(ans, 10) - 1;
+      const role = (idx >= 0 && idx < ROLES.length) ? ROLES[idx].key : "pm";
+      console.log(`  角色: ${role}\n`);
+      resolve(role);
+    });
+  });
+}
+
+// 校验角色参数合法性 (大小写无关: PM/pm/Dev/dev 都认)
+function normalizeRole(r) {
+  if (!r) return null;
+  const low = String(r).toLowerCase();
+  return ROLES.some(x => x.key === low) ? low : null;
+}
+
+// reset --hard 前备份本地改过的团队数据文件 (防丢真实密码/配置)。
+// 只备份 .qoder/config.yaml|config.toml|settings.json, 且仅当本地内容与远程不同时。
+// 返回被备份的相对路径列表。引擎文件 (gitignored) 不备份, 反正由 update 重新生成。
+function _backupLocalTeamData(cwd, remoteBranch, _es) {
+  const DATA_FILES = [".qoder/config.yaml", ".qoder/config.toml", ".qoder/settings.json"];
+  const backed = [];
+  const backupDir = path.join(cwd, ".wlkj-pre-reset");
+  try {
+    fs.mkdirSync(backupDir, { recursive: true });
+    for (const rel of DATA_FILES) {
+      const local = path.join(cwd, rel);
+      if (!fs.existsSync(local)) continue;
+      let localContent = "";
+      try { localContent = fs.readFileSync(local, "utf-8"); } catch { continue; }
+      // 拿远程版本对比
+      let remoteContent = null;
+      try {
+        remoteContent = _es(`git show origin/${remoteBranch}:${rel}`, { cwd, encoding: "utf-8", timeout: 5000, stdio: "pipe" });
+      } catch { /* 远程没这文件 */ }
+      const same = (remoteContent !== null && remoteContent.trim() === localContent.trim());
+      if (!same) {
+        const target = path.join(backupDir, rel.replace(/[\\/]/g, "__"));
+        fs.copyFileSync(local, target);
+        backed.push(rel);
+      }
+    }
+  } catch { /* 备份失败不阻塞, 但少一层保护 */ }
+  return backed;
+}
+
+async function doInit(name, roleArg) {
+  const cwd = process.cwd();
+  const hasExisting = fs.existsSync(path.join(cwd, ".qoder", "scripts", "setup.py"));
+  console.log(`\nwlkj init -> ${cwd}${hasExisting ? " (已存在, 增量更新)" : ""}\n`);
+
+  // === 0. 环境前置检测 (避免裸机无 Python 时假成功) ===
+  const env = checkEnvQuick();
+  if (!env.ok) process.exit(1);
+  const { pyCmd } = env;
+
+  // === 0.5. 确定角色 (参数 > 交互式, 不再写死 pm)
+  // 50 人团队角色各异: 产品/UI/前后端/测试/管理, 每个角色的命令视角不同。
+  // 写死 pm = 设计师和开发拿不到匹配的上下文 (见 wl-prd-full 的 --role 适配)。
+  let role = normalizeRole(roleArg);
+  if (!role) {
+    role = await askRole();
+  } else {
+    console.log(`  角色: ${role} (来自参数)\n`);
+  }
+
+  // === 1. 拷贝完整引擎 (镜像 .qoder/ 结构) ===
+  // 源: templates/qoder/*  目标: .qoder/*
+  // init 复用 update 的三路快照保护: 新装时目标不存在, 保护不触发;
+  // 重跑 init 时用户改过的引擎文件 (如自定义 skill) 不会被覆盖。
+  const qoderSrc = path.join(T, "qoder");
+  let copied = 0;
+  if (fs.existsSync(qoderSrc)) {
+    const snap = readSnapshot(cwd);
+    const newSnap = {};
+    const r = copyDirRecursive(qoderSrc, path.join(cwd, ".qoder"), "update", snap, newSnap);
+    copied = r.copied;
+    writeSnapshot(cwd, newSnap);
+    if (r.protectedN > 0) {
+      console.log(`  [保护] ${r.protectedN} 个文件保留你的改动 (新版存为 .new):`);
+      for (const f of r.protectedFiles.slice(0, 8)) console.log(`         .qoder/${f}`);
+      if (r.protectedFiles.length > 8) console.log(`         ...等 ${r.protectedFiles.length} 个`);
+    }
+  }
+  console.log(`  引擎: ${copied} 个文件 (${hasExisting ? "更新" : "新建"})`);
+
+  // === 2. 根文件 (AGENTS.md, 新手指南.md, requirements.txt) ===
+  ["root/AGENTS.md", "root/新手指南.md", "root/requirements.txt"].forEach(f => {
+    const src = path.join(T, f);
+    if (fs.existsSync(src)) {
+      const dstName = path.basename(f);
+      const dst = path.join(cwd, dstName);
+      // requirements.txt 始终覆盖(版本可能更新), 其它不存在才拷
+      if (dstName === "requirements.txt" || !fs.existsSync(dst)) {
+        fs.copyFileSync(src, dst);
+      }
+    }
+  });
+
+  // === 3. workspace 目录结构 ===
+  ["workspace/specs/prd", "workspace/tasks", "workspace/constitution",
+   "workspace/members", "data/docs/prd", "data/index", "data/code"].forEach(d => {
+    fs.mkdirSync(path.join(cwd, d), { recursive: true });
+  });
+  console.log(`  workspace 目录就绪`);
+
+  // === 4. git init (若没有) ===
+  if (!fs.existsSync(path.join(cwd, ".git"))) {
+    try { execSync("git init", { cwd, stdio: "pipe" }); console.log(`  git init done`); }
+    catch (_) { /* git 可能没装, 不阻塞 */ }
+  }
+
+  // === 5. .gitignore (若没有) ===
+  const gitignorePath = path.join(cwd, ".gitignore");
+  if (!fs.existsSync(gitignorePath)) {
+    const baseGitignore = [
+      "# 引擎代码 (由 npm 包 @hupan56/wlkj init/update 生成, 不进团队 git)",
+      ".qoder/scripts/", ".qoder/skills/", ".qoder/commands/", ".qoder/agents/",
+      ".qoder/contracts/", ".qoder/hooks/", ".qoder/templates/", ".qoder/rules/",
+      ".qoder/repowiki/", ".qoder/archive/",
+      "",
+      "# 团队数据 (保持跟踪): .qoder/config.yaml, .qoder/settings.json, data/learning/, data/index/, data/, workspace/",
+      "",
+      "# Source code repos (cloned by git_sync.py)", "data/code/",
+      "", "# AI pipeline runtime", ".qoder/.developer", ".qoder/.current-task",
+      ".qoder/.engine-version", ".qoder/.engine-snapshot.json", ".qoder/.runtime/", "",
+      "# Machine-local", "data/index/.last-sync", "data/index/.prd-collected.json",
+      "data/index/.index-meta.json", "data/index/.sync-lock", "data/index/.file-keys.json",
+      "data/index/.inverted-cache.json", "data/index/*.corrupt",
+      "", "# Identity (secret)", "workspace/members/*/.signing_key", "",
+      "# Python", "__pycache__/", "*.pyc", "*.lock", "*.tmp", "",
+    ].join("\n");
+    fs.writeFileSync(gitignorePath, baseGitignore, "utf-8");
+  }
+
+  // === 6. 自动跑 setup.py (名字探测/git/索引/cron/QoderWork) ===
+  console.log(`\n--- 自动初始化 ---`);
+  const setupPath = path.join(cwd, ".qoder", "scripts", "deployment", "setup", "setup.py");
+  if (fs.existsSync(setupPath)) {
+    const setupArgs = [name, role, "--skip-cron", "--skip-qoderwork"].filter(Boolean);
+    try {
+      const cmd = `python "${setupPath}" ${setupArgs.map(a => `"${a}"`).join(" ")}`;
+      console.log(`  运行: setup.py ${setupArgs.join(" ")}`);
+      // 强制 UTF-8 环境 (Windows cmd 默认 GBK, 会导致中文输出乱码)
+      const env = { ...process.env, PYTHONIOENCODING: "utf-8", PYTHONUTF8: "1" };
+      execSync(cmd, { cwd, stdio: "inherit", timeout: 300000, env });
+    } catch (e) {
+      console.log(`  setup 部分失败 (不阻塞): ${(e.message || "").slice(0, 100)}`);
+      console.log(`  可重新运行: npx @hupan56/wlkj init ${name || "<你的名字>"}`);
+    }
+    } else {
+      console.log(`  setup.py 未找到, 跳过自动初始化`);
+    }
+
+  // === 6.4. 装 pip 依赖 (必须在配 MCP 之前!)
+  // 顺序关键: 先装依赖 → 再写 mcp.json → mcp.json 选到"装了依赖的Python" → MCP 秒绿
+  // 旧版 init 不装依赖直接配 mcp.json → 新机 MCP 全黄 (没装 duckdb/pymysql)
+  console.log(`\n--- Python 依赖安装 (失败自动切镜像) ---`);
+  const reqFileInit = path.join(cwd, "requirements.txt");
+  if (pyCmd && fs.existsSync(reqFileInit)) {
+    installPipDeps(pyCmd, reqFileInit);
+  } else if (!pyCmd) {
+    console.log(`  [跳过] Python 未装`);
+  } else {
+    console.log(`  [跳过] requirements.txt 不存在`);
+  }
+
+  // === 6.5. 自动配 QoderWork MCP (新机关键: 否则 mcp.json 不生成, 4 个 MCP 全连不上) ===
+  // 复刻 doUpdate 第 6 步的逻辑: 拷 launcher + install_qoderwork --mcp-only
+  // setup.py 带了 --skip-qoderwork (offer_qoderwork 是交互式+装skill, 不适合 npx),
+  // 这里用 --mcp-only (纯文件操作, 无交互) 把 mcp.json 配好
+  // 注意: 此时依赖已装好(6.4步), install_qoderwork 会选到装了依赖的 Python
+  if (pyCmd) {
+    console.log(`\n--- QoderWork MCP 自动配置 ---`);
+    const home = process.env.USERPROFILE || require("os").homedir();
+    const launcherSrc = path.join(cwd, ".qoder", "scripts", "protocol", "mcp", "mcp_launcher.py");
+    const launcherDst = path.join(home, ".qoderwork", "mcp_launcher.py");
+    try {
+      if (fs.existsSync(launcherSrc)) {
+        fs.mkdirSync(path.dirname(launcherDst), { recursive: true });
+        fs.copyFileSync(launcherSrc, launcherDst);
+        console.log(`  [OK] launcher 已装: ~/.qoderwork/mcp_launcher.py`);
+      }
+      const instScript = path.join(cwd, ".qoder", "scripts", "deployment", "setup", "install_qoderwork.py");
+      if (fs.existsSync(instScript)) {
+        try {
+          const env = { ...process.env, PYTHONIOENCODING: "utf-8", PYTHONUTF8: "1" };
+          execSync(`${pyCmd} "${instScript}" --mcp-only`, { stdio: "inherit", timeout: 20000, env });
+          console.log(`  [OK] mcp.json 已生成 (选装了依赖的Python, MCP 不会黄)`);
+        } catch (e) {
+          console.log(`  [WARN] MCP 配置未完全成功 (不阻塞): ${(e.message || "").slice(0, 80)}`);
+          console.log(`         可手动补: ${pyCmd} .qoder/scripts/deployment/setup/install_qoderwork.py`);
+        }
+      }
+    } catch (e) {
+      console.log(`  [WARN] MCP 配置跳过: ${(e.message || "").slice(0, 80)}`);
+    }
+  }
+
+  // === 7. 写版本戳 ===
+  writeEngineVersion(cwd);
+
+  console.log(`\n${"=".repeat(50)}`);
+  console.log(`  安装完成!  (v${PKG_VERSION})`);
+  console.log(`${"=".repeat(50)}`);
+  console.log(`\n  现在可以开始了:`);
+  console.log(`    在 Qoder 里说 "写个 XX 的需求"`);
+  console.log(`    或输 / 看命令列表 (/wl-prd /wl-search /wl-task)`);
+  console.log(`\n  ✓ QoderWork MCP 已自动配好 (kg/mysql/lanhu/playwright)`);
+  console.log(`    用 QoderWork 桌面端想装技能(软链到 ~/.qoderwork/skills/)?`);
+  console.log(`    python .qoder/scripts/deployment/setup/install_qoderwork.py`);
+  console.log(`\n  看不到命令? 新建对话 / 重启 QoderWork`);
+  console.log(`  环境问题? python .qoder/scripts/deployment/setup/init_doctor.py --fix\n`);
+}
+
+// 递归拷贝目录, 返回 {copied, protected, skipped, protectedFiles}
+// mode: "init" (新装, 全拷) | "update" (升级, 保护用户数据)
+// update 模式下采用三路快照保护 (见 readSnapshot/writeSnapshot):
+//   用户改过的引擎文件 (与上次安装快照不同) → 保留用户的, 新版存 .new
+//   用户没动过的引擎文件 → 正常升级
+//   非引擎文件已存在 → 跳过 (留用户数据)
+function copyDirRecursive(src, dst, mode = "init", snap = {}, newSnap = {}, relBase = "") {
+  let copied = 0, protectedN = 0, skipped = 0;
+  const protectedFiles = [];
+  if (!fs.existsSync(src)) return { copied, protectedN, skipped, protectedFiles };
+  fs.mkdirSync(dst, { recursive: true });
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    if (entry.name === "__pycache__" || entry.name.endsWith(".pyc")) continue;
+    const s = path.join(src, entry.name);
+    const d = path.join(dst, entry.name);
+    const rel = relBase ? `${relBase}/${entry.name}` : entry.name;
+    if (entry.isDirectory()) {
+      const r = copyDirRecursive(s, d, mode, snap, newSnap, rel);
+      copied += r.copied; protectedN += r.protectedN; skipped += r.skipped;
+      protectedFiles.push(...r.protectedFiles);
+    } else {
+      const isEngine = entry.name.endsWith(".py") || entry.name.endsWith(".md") ||
+                       entry.name.endsWith(".yaml") || entry.name.endsWith(".yml") ||
+                       entry.name.endsWith(".toml") || entry.name.endsWith(".json") ||
+                       entry.name.endsWith(".html") || entry.name.endsWith(".txt");
+
+      if (mode === "update") {
+        // 受保护配置 (config.yaml/settings.json): 永不覆盖, 有差异存 .new
+        if (PROTECTED_FILES.has(entry.name) && fs.existsSync(d)) {
+          if (!filesEqual(s, d)) {
+            fs.copyFileSync(s, d + ".new");
+            protectedN++; protectedFiles.push(rel);
+          } else {
+            skipped++;
+          }
+          // 快照记上游 hash: 用户当前 == 上游 → 下次安全升级; 否则持续保护
+          const sh = fileHash(s); if (sh) newSnap[rel] = sh;
+          continue;
+        }
+        // 引擎文件: 三路快照保护
+        if (isEngine) {
+          const userHash = fs.existsSync(d) ? fileHash(d) : null;
+          const snapHash = snap[rel] || null;
+          // 保护判定: 用户当前文件与上游源不同, 且要么(a)与上次快照也不同(确属用户改过),
+          // 要么(b)快照缺失/损坏(无法判定来源 → 保守保护, 不覆盖, 避免静默丢用户改动)。
+          // ⚠ 旧逻辑要求 snapHash 非 null 才保护 → 快照缺失/损坏时全量覆盖, 静默吞掉用户改动。
+          const userModifiedKnownSnap = (fs.existsSync(d) && userHash && snapHash && userHash !== snapHash);
+          const userDiffersFromUpstream = (fs.existsSync(d) && !filesEqual(s, d));
+          const snapshotMissing = !snapHash;
+          const shouldProtect = userModifiedKnownSnap || (userDiffersFromUpstream && snapshotMissing);
+          if (shouldProtect) {
+            // 保留用户的, 新版存 .new (不覆盖)
+            if (!filesEqual(s, d)) {
+              fs.copyFileSync(s, d + ".new");
+              protectedN++; protectedFiles.push(rel);
+            } else {
+              skipped++;
+            }
+            // 关键: 快照记上游 hash (不是用户的 hash)。
+            // 这样下次升级: 用户文件若仍 != 上游 → 继续保护; 若用户手动改成上游 → 自动恢复正常升级。
+            const sh = fileHash(s); if (sh) newSnap[rel] = sh;
+          } else {
+            // 用户没动过 (或新文件), 正常升级, 刷新快照为新版 hash
+            fs.copyFileSync(s, d);
+            copied++;
+            const sh = fileHash(s); if (sh) newSnap[rel] = sh;
+          }
+        } else {
+          // 非引擎文件: 已存在跳过 (保护用户数据), 不存在才建
+          if (!fs.existsSync(d)) {
+            fs.copyFileSync(s, d);
+            copied++;
+          } else {
+            skipped++;
+          }
+        }
+      } else {
+        // init 模式: 引擎文件全覆盖, 非引擎已存在跳过 (保留用户改动)
+        if (isEngine || !fs.existsSync(d)) {
+          fs.copyFileSync(s, d);
+        }
+        copied++;
+        // 快照记上游 hash (基线), 供将来升级对比
+        const sh = fileHash(s); if (sh) newSnap[rel] = sh;
+      }
+    }
+  }
+  return { copied, protectedN, skipped, protectedFiles };
+}
+
+// 两文件内容是否相同（先比大小再比内容）
+function filesEqual(a, b) {
+  try {
+    const sa = fs.statSync(a), sb = fs.statSync(b);
+    if (sa.size !== sb.size) return false;
+    return fs.readFileSync(a).equals(fs.readFileSync(b));
+  } catch { return false; }
+}
+
+// 版本戳: .qoder/.engine-version 存当前引擎版本
+function writeEngineVersion(cwd) {
+  try {
+    const p = path.join(cwd, ".qoder", ".engine-version");
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.writeFileSync(p, PKG_VERSION + "\n", "utf-8");
+  } catch { /* 不阻塞 */ }
+}
+
+function readEngineVersion(cwd) {
+  try {
+    const p = path.join(cwd, ".qoder", ".engine-version");
+    if (fs.existsSync(p)) return fs.readFileSync(p, "utf-8").trim();
+  } catch { /* */ }
+  return null;
+}
+
+// ─────────────────────────────────────────────────────────────
+// 三路快照保护 (dpkg/brew conffiles 同款机制, 彻底解决"我原本的技能呢?")
+//
+// 问题: update 用 isEngine 一刀切强制刷新 .md/.py/.yaml 等,
+//       用户改过的 stock skill (如 .qoder/skills/wl-prd-full/SKILL.md)
+//       被无声覆盖 → "更新完我的技能没了"。
+//
+// 解法: 每次安装/升级后, 把所有"从 npm 包拷过来的引擎文件"的 hash 记到
+//       .qoder/.engine-snapshot.json。下次升级时, 三路对比:
+//         用户当前文件 hash == 快照 hash  → 没动过, 安全升级
+//         用户当前文件 hash != 快照 hash  → 动过! 保留用户的, 新版存 .new
+// 这就是 apt/dpkg 对 /etc 下 conffiles 的处理, 行业标准, 不瞎猜。
+// ─────────────────────────────────────────────────────────────
+const SNAPSHOT_FILE = ".engine-snapshot.json";
+
+function snapshotPath(cwd) {
+  return path.join(cwd, ".qoder", SNAPSHOT_FILE);
+}
+
+// 读快照: { "skills/wl-prd-full/SKILL.md": "<sha256前16位>", ... }
+function readSnapshot(cwd) {
+  try {
+    const p = snapshotPath(cwd);
+    if (fs.existsSync(p)) return JSON.parse(fs.readFileSync(p, "utf-8"));
+  } catch { /* 损坏的快照当空 */ }
+  return {};
+}
+
+// 写快照: 传入 {相对路径: hash} 的对象
+function writeSnapshot(cwd, snap) {
+  try {
+    const p = snapshotPath(cwd);
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.writeFileSync(p, JSON.stringify(snap, null, 2), "utf-8");
+  } catch { /* 快照写失败不阻塞升级 */ }
+}
+
+// 计算文件内容 hash (sha256 前 16 位, 足够检测"是否动过")
+function fileHash(p) {
+  try {
+    const crypto = require("crypto");
+    const h = crypto.createHash("sha256");
+    h.update(fs.readFileSync(p));
+    return h.digest("hex").slice(0, 16);
+  } catch { return null; }
+}
+
+// 跑 install_qoderwork.py（升级时强制刷新 commands）
+// v3.x: 脚本已分子目录, 路径为 scripts/deployment/setup/install_qoderwork.py
+function runQoderWorkInstall(cwd, forceCommands) {
+  const script = path.join(cwd, ".qoder", "scripts", "deployment", "setup", "install_qoderwork.py");
+  if (!fs.existsSync(script)) {
+    console.log("  [跳过] install_qoderwork.py 不存在");
+    return;
+  }
+  // ⚠ 必须用 detectPyCmd(), 不能硬编码 "python"!
+  //    macOS 默认只有 python3, 硬编码 python 会让 Mac 全员 update 时
+  //    "刷新 QoderWork" 步骤静默失败 (commands/skills 不刷新)。
+  //    用 spawnSync(list-form) 而非 args.join(" ") → 路径含空格/中文也不裂。
+  const { spawnSync } = require("child_process");
+  const pyCmd = detectPyCmd();
+  if (!pyCmd) {
+    console.log("  [跳过] Python 未安装, 无法刷新 QoderWork (npx @hupan56/wlkj install-env)");
+    return;
+  }
+  const args = [script];
+  if (forceCommands) args.push("--force-commands");
+  try {
+    console.log(`\n--- 刷新 QoderWork ---`);
+    const r = spawnSync(pyCmd, args, {
+      cwd, stdio: "inherit", timeout: 60000,
+      env: { ...process.env, PYTHONIOENCODING: "utf-8", PYTHONUTF8: "1" },
+    });
+    if (r.status !== 0 && r.status !== null) {
+      console.log(`  QoderWork 刷新返回非0 (不阻塞): exit ${r.status}`);
+    }
+  } catch (e) {
+    console.log(`  QoderWork 刷新失败 (不阻塞): ${(e.message || "").slice(0, 80)}`);
+  }
+}
+
+function doStatus() {
+  console.log("");
+  // v3.x: 转调 wlkj.py status (单一真源 domain/report/status.py)。
+  // 旧版 doStatus 自带 .developer 解析, 但 role 实际存在 member.json,
+  // 旧解析读不到 role 行就误报"角色未设置", 与 status.py 自相矛盾。
+  // 统一走 Python 入口, 消除"两套读取逻辑不一致"。
+  const wlkj = path.join(process.cwd(), ".qoder", "scripts", "orchestration", "wlkj.py");
+  if (!fs.existsSync(wlkj)) {
+    console.log("引擎未安装。跑: npx @hupan56/wlkj init");
+    return;
+  }
+  const pyCmd = detectPyCmd();
+  if (!pyCmd) {
+    console.log("Python 未安装。跑: npx @hupan56/wlkj install-env");
+    return;
+  }
+  try {
+    const env = { ...process.env, PYTHONIOENCODING: "utf-8", PYTHONUTF8: "1" };
+    const out = execSync(`${pyCmd} "${wlkj}" status`, { cwd: process.cwd(), encoding: "utf-8", timeout: 20000, env });
+    process.stdout.write(out);
+  } catch (e) {
+    process.stdout.write((e.stdout || e.message || ""));
+  }
+  // 版本戳 (status.py 不管这层, 保留在 cli 侧)
+  const ver = readEngineVersion(process.cwd());
+  console.log(`engine: ${ver || "未知"} (最新: v${PKG_VERSION})${ver === PKG_VERSION ? " [最新]" : ver ? " [可升级: npx @hupan56/wlkj update]" : ""}`);
+  console.log("");
+}
+
+function doUpdate() {
+  const cwd = process.cwd();
+  const oldVer = readEngineVersion(cwd);
+  const qoderSrc = path.join(T, "qoder");
+
+  // 前置检查: 必须已装过
+  if (!fs.existsSync(path.join(cwd, ".qoder", "scripts"))) {
+    console.log("\n  未检测到已安装的引擎。首次安装请用:");
+    console.log("    npx @hupan56/wlkj init [你的名字]\n");
+    return;
+  }
+
+  console.log(`\nwlkj update${oldVer ? " " + oldVer : ""} -> v${PKG_VERSION}\n`);
+
+  // P1-15: 显式声明 update 绝不触碰的路径
+  console.log("  受保护路径 (绝不覆盖):");
+  console.log("    .qoder/config.yaml          (团队 git 配置)");
+  console.log("    .qoder/settings.json         (权限/hook 配置)");
+  console.log("    .qoder/.developer            (你的身份)");
+  console.log("    .qoder/.current-task         (当前任务)");
+  console.log("    .qoder/.engine-version       (版本戳)");
+  console.log("    你改过的引擎文件             (三路快照: 改过的留你的, 新版存 .new)");
+  console.log("    workspace/                   (你的全部产出)");
+  console.log("    data/                        (代码仓库+知识图谱)");
+  console.log("");
+
+  // === 1. 刷新引擎文件 (三路快照保护用户改动) ===
+  let copied = 0, protectedN = 0, skipped = 0;
+  let protectedFiles = [];
+  if (fs.existsSync(qoderSrc)) {
+    const snap = readSnapshot(cwd);
+    const newSnap = {};
+    const r = copyDirRecursive(qoderSrc, path.join(cwd, ".qoder"), "update", snap, newSnap);
+    copied = r.copied; protectedN = r.protectedN; skipped = r.skipped;
+    protectedFiles = r.protectedFiles || [];
+    writeSnapshot(cwd, newSnap);  // 刷新基线 (供下次升级对比)
+  }
+  console.log(`  引擎刷新: ${copied} 个文件${skipped ? ` / ${skipped} 无变化` : ""}`);
+
+  // 报告受保护文件 (用户的改动 + 配置文件)
+  if (protectedN > 0) {
+    console.log(`  [保护] ${protectedN} 个文件已保留你的改动 (新版存为 .new):`);
+    for (const f of protectedFiles.slice(0, 10)) console.log(`         .qoder/${f}`);
+    if (protectedFiles.length > 10) console.log(`         ...等 ${protectedFiles.length} 个`);
+    console.log(`         确认无需合并后可删除 .new; 或手动对比合并后删除。`);
+  }
+
+  // === 2. 根文件（文档 + requirements.txt, 始终覆盖保证最新）===
+  ["root/AGENTS.md", "root/新手指南.md", "root/requirements.txt"].forEach(f => {
+    const src = path.join(T, f);
+    if (fs.existsSync(src)) {
+      fs.copyFileSync(src, path.join(cwd, path.basename(f)));
+    }
+  });
+  console.log(`  根文档 + requirements.txt: 已更新`);
+
+  // === 2.5. git pull 拉最新团队数据 (Trellis: 引擎已由上面 copyDirRecursive 生成, git 只存数据) ===
+  // 团队数据 = config.yaml / settings.json / data/learning/ + data/ (kg.duckdb/kg_db.duckdb/索引) + workspace/ (PRD/任务)。
+  // 引擎代码 (scripts/skills/...) 已被 gitignore, 不在 git 里, 不会与 pull 冲突。
+  // git pull 失败会导致 kg.duckdb 拿不到 → kg MCP 无数据(但仍能连)。
+  // 失败原因常见: 未配 git 身份 / 远程仓库要认证 / 网络问题 / 分支没tracking / unrelated histories。
+  // 这里给出清晰诊断, 不让"git pull 失败"变成无声的静默跳过。
+  // 前置: 自愈分支 tracking (老版 init 配了 remote 但没 set-upstream, pull 会报
+  //       "no tracking information"。这里检测到就补上, 老用户 update 也能自动修)
+  const { execSync: _es } = require("child_process");  // 提到 try 外, catch 块的自愈逻辑也要用
+  try {
+    // 先看当前分支有没有 upstream
+    let _trackOk = false;
+    try {
+      _es("git rev-parse --abbrev-ref --symbolic-full-name @{u}", { cwd, encoding: "utf-8", timeout: 5000, stdio: "pipe" });
+      _trackOk = true;  // 有 upstream, 正常
+    } catch {
+      // 没 tracking — 尝试补设 (有 origin remote 的前提下)
+      try {
+        const _remote = _es("git remote", { cwd, encoding: "utf-8", timeout: 5000, stdio: "pipe" }).trim();
+        if (_remote.split(/\s+/).includes("origin")) {
+          _es("git fetch origin", { cwd, encoding: "utf-8", timeout: 30000, stdio: "pipe" });
+          // 确定本地分支名
+          const _branch = _es("git rev-parse --abbrev-ref HEAD", { cwd, encoding: "utf-8", timeout: 5000, stdio: "pipe" }).trim();
+          // 远程用 master 还是 main
+          let _remoteBranch = null;
+          for (const _c of ["master", "main"]) {
+            try {
+              _es(`git rev-parse --verify remotes/origin/${_c}`, { cwd, encoding: "utf-8", timeout: 5000, stdio: "pipe" });
+              _remoteBranch = _c; break;
+            } catch { /* 该分支不存在, 试下一个 */ }
+          }
+          if (_remoteBranch) {
+            _es(`git branch --set-upstream-to=origin/${_remoteBranch} ${_branch}`, { cwd, encoding: "utf-8", timeout: 5000, stdio: "pipe" });
+            console.log(`  git: 已自动设置上游 tracking (origin/${_remoteBranch})`);
+            _trackOk = true;
+          }
+        }
+      } catch { /* 补 tracking 失败, 走下面的 pull 诊断 */ }
+    }
+    const pullR = _es("git pull --no-rebase 2>&1", { cwd, encoding: "utf-8", timeout: 30000 });
+    if (pullR.includes("Already up to date") || pullR.includes("已经是最新")) {
+      console.log(`  git: 已是最新`);
+    } else if (pullR.includes("CONFLICT") || pullR.includes("conflict")) {
+      console.log(`  git: ⚠️ 有冲突, 跳过pull(不影响本地工作)`);
+    } else {
+      console.log(`  git: 已拉取最新`);
+    }
+  } catch (e) {
+    // git pull 失败诊断: 区分"没配git身份"/"远程要认证"/"网络问题"/"非git仓库"
+    // node execSync 抛异常时, git 的真实报错在 e.stderr/e.stdout, 不能只看 e.message
+    const errMsg = String(e.message || "");
+    const stdout = String((e.stdout || "") + " " + (e.stderr || ""));
+    const combined = (errMsg + " " + stdout).toLowerCase();
+    if (combined.includes("authentication failed") || combined.includes("permission denied") ||
+        combined.includes("could not read username") || combined.includes("不支持密码") ||
+        combined.includes("credentials") || combined.includes("403") || combined.includes("401")) {
+      console.log(`  git: ⚠️ 认证失败 — kg.duckdb 等团队数据拉不到`);
+      console.log(`       原因: git 身份/凭证未配。MCP 能连但无数据。`);
+      console.log(`       修复: npx @hupan56/wlkj init <你的名字> (交互式配 git 账号)`);
+    } else if (combined.includes("not a git repository") || combined.includes("not a git dir") ||
+               combined.includes("unknown revision") || combined.includes("does not have any commits")) {
+      console.log(`  git: ⚠️ 非git仓库或空仓库 — 团队数据拉不到`);
+      console.log(`       原因: 此目录不是 git clone 来的, 或没有 remote。`);
+      console.log(`       修复: npx @hupan56/wlkj init <你的名字> (会配团队远程仓库)`);
+    } else if (combined.includes("timed out") || combined.includes("timeout") ||
+               combined.includes("could not resolve host") || combined.includes("connection refused") ||
+               combined.includes("network is unreachable") || combined.includes("unable to access") ||
+               combined.includes("ssl") || combined.includes("failed to connect")) {
+      console.log(`  git: ⚠️ 网络问题 — 连不上远程仓库`);
+      console.log(`       原因: ${stdout.trim().slice(0, 80) || "网络超时/无法解析主机"}`);
+      console.log(`       (kg.duckdb 拉不到, MCP 能连但搜索无结果)`);
+    } else if (combined.includes("unrelated histories") || combined.includes("refusing to merge")) {
+      // 自愈: 本地是空的 git init 历史, 与团队远程无公共祖先。
+      // 引擎代码现在由 npm 生成 (不在 git 里), 团队数据在远程 → 采用远程历史是正确的。
+      // 但 reset --hard 会覆盖工作树 → 先把本地改过的团队数据文件备份, 防丢密码/配置。
+      console.log(`  git: ⚠️ 无关历史 (本地 git init 产生的平行历史与团队远程无公共祖先)`);
+      try {
+        // 探测远程分支名
+        let _rb = null;
+        for (const _c of ["master", "main"]) {
+          try {
+            _es(`git rev-parse --verify remotes/origin/${_c}`, { cwd, encoding: "utf-8", timeout: 5000, stdio: "pipe" });
+            _rb = _c; break;
+          } catch { /* */ }
+        }
+        if (_rb) {
+          // 备份本地改过的团队数据 (config 等可能含未提交的真实密码)
+          const _backed = _backupLocalTeamData(cwd, _rb, _es);
+          _es(`git reset --hard origin/${_rb}`, { cwd, encoding: "utf-8", timeout: 30000, stdio: "pipe" });
+          console.log(`  git: ✓ 已采用远程历史 (origin/${_rb}), 团队数据已落地`);
+          console.log(`       (引擎随后由本次 update 重新生成)`);
+          if (_backed.length > 0) {
+            console.log(`  ⚠️ reset 前已备份你本地改过的数据文件 (可能含未提交的真实密码/配置):`);
+            for (const rel of _backed) console.log(`       → .wlkj-pre-reset/${rel.replace(/[\\/]/g, "__")}`);
+            console.log(`       检查这些文件, 把需要的配置/密码重新填回 .qoder/config.yaml 后删备份目录。`);
+          }
+        } else {
+          console.log(`  git: 远程无 master/main 分支, 无法自愈。请确认团队仓库地址正确。`);
+        }
+      } catch (re) {
+        console.log(`  git: 自愈失败 (${String(re.message || "").slice(0, 80)})`);
+        console.log(`       可手动: git fetch origin && git reset --hard origin/master`);
+      }
+    } else {
+      // 兜底: 显示 git 的真实报错, 不再笼统说 "Command failed"
+      const realErr = stdout.trim() || errMsg;
+      console.log(`  git: ⚠️ 拉取失败 — ${realErr.slice(0, 100)}`);
+      console.log(`       (kg.duckdb 拉不到, MCP 能连但搜索无结果)`);
+    }
+  }
+
+  // === 3. 补装 pip 依赖 (必须在刷 mcp.json 之前!)
+  // 顺序很关键: 先装依赖 → 再写 mcp.json → mcp.json 能选到"已装依赖的Python"
+  // 旧版顺序反了(先写mcp.json再装依赖), 导致 mcp.json 指向没装依赖的Python → MCP 黄。
+  console.log(`\n--- Python 依赖补装 (失败自动切镜像) ---`);
+  const reqFile = path.join(cwd, "requirements.txt");
+  const pyCmd = detectPyCmd();
+  if (pyCmd && fs.existsSync(reqFile)) {
+    installPipDeps(pyCmd, reqFile);
+  } else if (!pyCmd) {
+    console.log(`  [跳过] Python 未装`);
+  } else {
+    console.log(`  [跳过] requirements.txt 不存在`);
+  }
+
+  // === 4. 刷新 QoderWork commands（强制覆盖已存在的）===
+  // WLKJ_SKIP_QW_INSTALL=1 时跳过 (测试隔离用, 防止测试目录污染 ~/.qoderwork/.repo-root)
+  if (process.env.WLKJ_SKIP_QW_INSTALL !== "1") {
+    runQoderWorkInstall(cwd, true);
+  }
+
+  // === 5. 写版本戳 ===
+  writeEngineVersion(cwd);
+
+  // === 5b. 清理旧版废弃文件 ===
+  const OBSOLETE_FILES = [
+    // 旧脚本(已替代)
+    ".qoder/workflow.md",                      // 被 rules/wl-pipeline.md 替代
+    ".qoder/scripts/code_index.py",            // 被 git_sync.py 替代
+    ".qoder/scripts/notify.py",                // 被 common/feishu.py 替代
+    ".qoder/scripts/team.py",                  // 被 task.py + team_sync.py 替代
+    "packages/wlkj/templates/cli.js",          // 旧版 CLI
+    ".qoder/templates/qoder/config.toml",      // 旧版配置
+    ".qoder/templates/qoder/scripts/code_index.py",
+    ".qoder/templates/qoder/scripts/notify.py",
+    ".qoder/templates/qoder/scripts/team.py",
+    // 旧命令(已合并进 /wl-prd 和 /wl-design)
+    ".qoder/commands/wl-prd-full.md",
+    ".qoder/commands/wl-prd-quick.md",
+    ".qoder/commands/wl-prd-review.md",
+    ".qoder/commands/wl-design-draw.md",
+    ".qoder/commands/wl-design-scan.md",
+    ".qoder/commands/wl-design-spec.md",
+    // 旧版索引JSON(已迁移到DuckDB, 残留在老用户的data/index/)
+    "data/index/keyword-index.json",
+    "data/index/api-index.json",
+    "data/index/prd-index.json",
+    "data/index/module-map.json",
+    "data/index/prd-code-map.json",
+    "data/index/callgraph.json",
+    "data/index/style-index.json",
+    "data/index/style-meta.json",
+    "data/index/vben-style-reference.json",
+    "data/index/chart-style-reference.json",
+    "data/index/icon-reference.json",
+    "data/index/wiki-index.json",
+    // 旧运行时缓存(自动重建)
+    "data/index/.file-keys.json",
+    "data/index/.inverted-cache.json",
+    "data/index/.api-table-cache.json",
+    // 旧learning空壳(未实现的功能占位)
+    ".qoder/learning/patterns/code-patterns.md",
+    ".qoder/learning/patterns/prd-patterns.md",
+    ".qoder/learning/patterns/review-fixes.md",
+    // 用户级旧命令(已合并的, 清理~/.qoderwork/commands/)
+  ];
+  let cleaned = 0;
+  for (const f of OBSOLETE_FILES) {
+    const fp = path.join(cwd, f);
+    if (fs.existsSync(fp)) {
+      try {
+        if (fs.statSync(fp).isDirectory()) {
+          fs.rmSync(fp, { recursive: true, force: true });
+        } else {
+          fs.unlinkSync(fp);
+        }
+        console.log(`  [清理] 删除废弃文件: ${f}`);
+        cleaned++;
+      } catch (e) { /* 删不掉跳过 */ }
+    }
+  }
+  // 清理用户级旧命令 (已合并的, ~/.qoderwork/commands/)
+  const home = process.env.USERPROFILE || require("os").homedir();
+  const userCmdDir = path.join(home, ".qoderwork", "commands");
+  const OBSOLETE_USER_CMDS = [
+    "wl-prd-full.md", "wl-prd-quick.md", "wl-prd-review.md",
+    "wl-design-draw.md", "wl-design-scan.md", "wl-design-spec.md",
+  ];
+  for (const f of OBSOLETE_USER_CMDS) {
+    const fp = path.join(userCmdDir, f);
+    if (fs.existsSync(fp)) {
+      try { fs.unlinkSync(fp); console.log(`  [清理] 用户级旧命令: ${f}`); cleaned++; }
+      catch { /* */ }
+    }
+  }
+  // 注意: .new 文件不再自动删除! 它们是三路快照保护的"新版待对比"信号,
+  // 用户需要看到 .new 才知道"我的改动被保留了, 这里是新版"。用户手动合并后删。
+  // 清理缓存 (索引重建后失效的旧缓存)
+  const runtimeDir = path.join(cwd, ".qoder", ".runtime");
+  let cacheCleaned = 0;
+  try {
+    for (const f of fs.readdirSync(runtimeDir)) {
+      if (f.startsWith("search-cache-") || f.startsWith("ctx-cache-")) {
+        fs.unlinkSync(path.join(runtimeDir, f));
+        cacheCleaned++;
+      }
+    }
+  } catch { /* */ }
+  if (cleaned > 0 || cacheCleaned > 0) {
+    console.log(`  [清理] 废弃文件 ${cleaned} 个 + 过期缓存 ${cacheCleaned} 个`);
+  }
+
+  // === 5c. 清理 .qoder 嵌套残留 (致命 bug 源) ===
+  // 旧版 paths.py 的 _find_repo_root 会误把 .qoder 当 PROJECT_ROOT, 然后往
+  // "PROJECT_ROOT/.qoder/.runtime/" 写缓存 → 误建嵌套 .qoder/ 目录 →
+  // 这个残留反过来又让 _find_repo_root 再次误判 → 死循环。
+  // 表现: MCP cookie 路径全错 (workspace 跑到 .qoder/workspace), lanhu 永远 cookie 未配置。
+  // v3.0 修了 paths.py 不再误建, 但老用户机器上的残留要清掉, 否则 bug 还在。
+  // 注意: 残留可能出现在两处 —— .qoder/.qoder 和 .qoder/scripts/.qoder (后者是
+  // search 缓存写到错误 PROJECT_ROOT 时建的), 两处都要扫干净。
+  const nestedCandidates = [
+    path.join(cwd, ".qoder", ".qoder"),
+    path.join(cwd, ".qoder", "scripts", ".qoder"),
+  ];
+  for (const nestedQoder of nestedCandidates) {
+    if (fs.existsSync(nestedQoder)) {
+      try {
+        fs.rmSync(nestedQoder, { recursive: true, force: true });
+        console.log(`  [清理] 删除嵌套残留 ${path.relative(cwd, nestedQoder) || nestedQoder}/ (曾导致 MCP 路径错位)`);
+        cleaned++;
+      } catch { /* 删不掉不阻塞 (可能被占用), 下次再清 */ }
+    }
+  }
+
+  // === 6. 刷新 launcher + mcp.json (老用户的可能是旧版/写死路径) ===
+  // 注意: pip 依赖已在第3步装好, 此处 install_qoderwork 会选到"已装依赖的Python"写进 mcp.json
+  // WLKJ_SKIP_QW_INSTALL=1 时跳过 (测试隔离, 防止污染全局 ~/.qoderwork/)
+  if (process.env.WLKJ_SKIP_QW_INSTALL !== "1") {
+  try {
+    const home = process.env.USERPROFILE || require("os").homedir();
+    const launcherSrc = path.join(cwd, ".qoder", "scripts", "protocol", "mcp", "mcp_launcher.py");
+    const launcherDst = path.join(home, ".qoderwork", "mcp_launcher.py");
+    if (fs.existsSync(launcherSrc)) {
+      fs.mkdirSync(path.dirname(launcherDst), { recursive: true });
+      fs.copyFileSync(launcherSrc, launcherDst);
+      console.log(`  [OK] launcher 已刷新`);
+    }
+    // 刷新 mcp.json 为 launcher 模式 (install_qoderwork.py 的 rewrite 逻辑)
+    const instScript = path.join(cwd, ".qoder", "scripts", "deployment", "setup", "install_qoderwork.py");
+    if (pyCmd && fs.existsSync(instScript)) {
+      try {
+        execSync(`${pyCmd} "${instScript}" --mcp-only`, { stdio: "pipe", timeout: 15000 });
+        console.log(`  [OK] mcp.json 已刷新 (选装了依赖的Python, 避免MCP黄)`);
+      } catch (e) { /* --mcp-only 可能不支持, 静默跳过 */ }
+    }
+  } catch (e) { /* 刷新失败不阻塞升级 */ }
+  }  // end WLKJ_SKIP_QW_INSTALL guard
+
+  // === 6.5. MCP 启动实测 (发 initialize 看哪个起不来) ===
+  // 这是"根治黄色"的关键一步: 配完 mcp.json 后立即模拟 QoderWork 发 initialize,
+  // 看每个 MCP 是 OK / DISABLED(绿) / CRASHED(黄)。有问题当场报, 不让用户重启后才发现。
+  // v3.x: check_mcp_launch.py 已合并进 protocol/mcp/mcp_doctor.py (实际启动诊断)。
+  console.log(`\n--- MCP 启动实测 (模拟 QoderWork 连接) ---`);
+  const diagScript = path.join(cwd, ".qoder", "scripts", "protocol", "mcp", "mcp_doctor.py");
+  if (pyCmd && fs.existsSync(diagScript)) {
+    try {
+      const env = { ...process.env, PYTHONIOENCODING: "utf-8", PYTHONUTF8: "1" };
+      execSync(`${pyCmd} "${diagScript}"`, { cwd, stdio: "inherit", timeout: 60000, env });
+    } catch (e) {
+      console.log(`  [WARN] MCP 实测脚本异常 (不阻塞): ${(e.message || "").slice(0, 80)}`);
+    }
+  }
+
+  // === 7. 自检: 关键文件到底齐不齐 ===
+  console.log(`\n--- 自检 (关键文件验证) ---`);
+  const checks = [
+    ["requirements.txt", path.join(cwd, "requirements.txt"), "依赖清单(没它pip装不了)"],
+    ["duckdb(pip)", null, "知识图谱核心依赖"],
+    ["kg.duckdb", path.join(cwd, "data", "index", "kg.duckdb"), "代码图谱(MCP需要)"],
+    ["kg_db.duckdb", path.join(cwd, "data", "index", "kg_db.duckdb"), "数据库图谱(table_impact需要)"],
+    [".qoder/commands/", path.join(cwd, ".qoder", "commands"), "斜杠命令"],
+  ];
+  let allOk = true;
+  for (const [label, p, desc] of checks) {
+    if (p === null) {
+      // duckdb 用 python 检测
+      try {
+        execSync(`${pyCmd || "python"} -c "import duckdb"`, { stdio: "pipe", timeout: 5000 });
+        console.log(`  [✓] ${label} - ${desc}`);
+      } catch {
+        console.log(`  [✗] ${label} 缺失! ${desc}`);
+        console.log(`       → 修复: pip install duckdb -i https://pypi.tuna.tsinghua.edu.cn/simple`);
+        allOk = false;
+      }
+    } else if (fs.existsSync(p)) {
+      console.log(`  [✓] ${label}`);
+    } else {
+      console.log(`  [✗] ${label} 缺失! ${desc}`);
+      if (label.includes("duckdb")) {
+        // duckdb 是团队共享数据, 在 git 里 → 非管理员靠 git pull 拿; 管理员靠本地构建。
+        console.log(`       → 修复: 先 npx @hupan56/wlkj doctor (拉团队数据); `);
+        console.log(`                管理员可 npx @hupan56/wlkj run kg_build.py --rebuild`);
+      } else if (label.includes("commands")) {
+        console.log(`       → 修复: npx @hupan56/wlkj update`);
+      }
+      allOk = false;
+    }
+  }
+  if (!allOk) {
+    console.log(`\n  ⚠️ 有缺失项, 按上面的提示修复后重跑 update。`);
+  } else {
+    console.log(`  全部关键文件就绪 ✓`);
+  }
+
+  console.log(`\n${"=".repeat(50)}`);
+  console.log(`  升级完成!  (v${PKG_VERSION})`);
+  console.log(`${"=".repeat(50)}`);
+  console.log(`\n  生效方式:`);
+  console.log(`    Qoder IDE / Quest: 新建对话即可`);
+  console.log(`    QoderWork: 重启应用或新建对话`);
+
+  // 检查 git 身份是否需要配置 (只检测不引导, update 保持轻量)
+  // 老用户如果之前 init 时塞了假账号, 这里提示重跑 init 修正
+  let gitWarn = false;
+  try {
+    const devFile = path.join(cwd, ".qoder", ".developer");
+    if (fs.existsSync(devFile)) {
+      const devName = fs.readFileSync(devFile, "utf-8").trim();
+      const mj = path.join(cwd, "workspace", "members", devName, "member.json");
+      if (fs.existsSync(mj)) {
+        const m = JSON.parse(fs.readFileSync(mj, "utf-8"));
+        const ga = m.git_author || "";
+        if (!ga || ga.includes("@local") || ga.includes("@unknown")) {
+          gitWarn = true;
+        }
+      }
+    }
+  } catch { /* 检测失败不阻塞 */ }
+
+  if (gitWarn) {
+    console.log(`\n  ⚠ git 账号未配置或为假账号 (push/同步会失败)`);
+    console.log(`    重跑初始化可修复: npx @hupan56/wlkj init <你的名字>`);
+    console.log(`    (init 会交互式引导你配置团队 git 账号和团队仓库)`);
+  } else {
+    console.log(`\n  如果还没配过 git 账号或团队仓库, 重跑: npx @hupan56/wlkj init <你的名字>`);
+  }
+
+  if (protectedN > 0) {
+    console.log(`\n  ⚠ 有配置文件新版有变化, 生成 .new 文件:`);
+    console.log(`    确认无需合并后可直接删除, 或手动合并后删除`);
+  }
+  console.log("");
+}
+
+// ─────────────────────────────────────────────────────────────
+// 一次性迁移: 把引擎代码从团队 git 跟踪里摘出来 (Trellis 化)
+// 团队管理员只跑一次, 其余成员 wlkj update 后自动同步。
+// 原理: git rm -r --cached (只删 git 索引, 不删磁盘文件) + commit。
+// 之后引擎文件仍在磁盘 (由 wlkj update 重新生成), 但不再被 git 跟踪 →
+// 彻底消除"引擎更新污染团队 git"和"新机 init 产生 unrelated histories"。
+// 团队数据 (.qoder/config.yaml, settings.json, data/learning/, data/, workspace/) 保持不动。
+// ─────────────────────────────────────────────────────────────
+function doMigrate() {
+  const { execSync } = require("child_process");
+  const cwd = process.cwd();
+  const env = { ...process.env, PYTHONIOENCODING: "utf-8", PYTHONUTF8: "1" };
+  function _es(cmd, opts = {}) {
+    return execSync(cmd, { cwd, encoding: "utf-8", timeout: 30000, stdio: "pipe", env, ...opts });
+  }
+
+  console.log("");
+  console.log("=== wlkj migrate: 引擎代码改为 npm 生成 (Trellis 化) ===");
+  console.log("");
+
+  // 1. 必须在 git 仓库里
+  if (!fs.existsSync(path.join(cwd, ".git"))) {
+    console.log("  ✗ 当前目录不是 git 仓库。请在团队仓库根目录运行。");
+    console.log("");
+    return;
+  }
+
+  // 2. 要从 git 跟踪摘除的引擎目录 (团队数据 config/data/learning 等不在此列)
+  const ENGINE_DIRS = [
+    ".qoder/scripts", ".qoder/skills", ".qoder/commands", ".qoder/agents",
+    ".qoder/contracts", ".qoder/hooks", ".qoder/templates", ".qoder/rules",
+  ];
+
+  // 3. 哪些目录当前确被跟踪 (只摘这些, 避免在已迁移过的仓库上空跑)
+  const tracked = [];
+  for (const d of ENGINE_DIRS) {
+    let isTracked = false;
+    try {
+      // git ls-files 能列出被跟踪的文件; 有输出说明该目录还有文件在跟踪
+      const out = _es(`git ls-files "${d}"`, { timeout: 10000 });
+      if (out.trim()) isTracked = true;
+    } catch { /* 命令失败当未跟踪 */ }
+    if (isTracked) tracked.push(d);
+  }
+
+  if (tracked.length === 0) {
+    console.log("  ✓ 引擎目录已不在 git 跟踪中, 无需迁移。");
+    console.log("    (这通常是已经迁移过了, 或是个全新仓库)");
+    console.log("");
+    return;
+  }
+
+  console.log(`  将从 git 跟踪中移除 (磁盘文件保留, 不删):`);
+  for (const d of tracked) console.log(`    - ${d}`);
+  console.log("");
+
+  // 4. 先确保 .gitignore 已含引擎忽略规则 (防止 rm --cached 后又被加回)
+  //    逐条补缺, 不重复不乱插。
+  const giPath = path.join(cwd, ".gitignore");
+  const RULES_TO_ENSURE = [
+    "# 引擎代码 (由 npm 包 @hupan56/wlkj init/update 生成, 不进团队 git)",
+    ".qoder/scripts/", ".qoder/skills/", ".qoder/commands/", ".qoder/agents/",
+    ".qoder/contracts/", ".qoder/hooks/", ".qoder/templates/", ".qoder/rules/",
+    ".qoder/repowiki/", ".qoder/archive/",
+    ".wlkj-pre-reset/",
+  ];
+  let gi = fs.existsSync(giPath) ? fs.readFileSync(giPath, "utf-8") : "";
+  const existingLines = new Set(gi.split(/\r?\n/));
+  const missing = RULES_TO_ENSURE.filter(rule => !existingLines.has(rule));
+  if (missing.length > 0) {
+    // 缺哪条补哪条 (注释行单独补, 规则行单独补), 补在最前面
+    gi = missing.join("\n") + "\n" + (gi ? "\n" + gi : "");
+    fs.writeFileSync(giPath, gi, "utf-8");
+    console.log(`  ✓ .gitignore 已补 ${missing.length} 条忽略规则`);
+  }
+
+  // 5. git rm -r --cached (只删索引, 不删磁盘文件)
+  console.log("  从 git 索引移除 (git rm -r --cached, 磁盘文件不动)...");
+  try {
+    _es(`git rm -r --cached ${tracked.map(t => `"${t}"`).join(" ")}`, { timeout: 60000 });
+    console.log("  ✓ 已移除");
+  } catch (e) {
+    console.log(`  ✗ git rm 失败: ${(e.stderr || e.message || "").slice(0, 200)}`);
+    console.log("    可手动跑: " + tracked.map(t => `git rm -r --cached ${t}`).join(" && "));
+    return;
+  }
+
+  // 6. 自动 commit (标记这次架构变更)
+  console.log("  提交迁移...");
+  try {
+    _es(`git add -A .gitignore`, { timeout: 10000 });
+    _es(`git commit -m "chore(wlkj): 引擎代码改为 npm 生成, 不再进团队 git (Trellis 化)"`, { timeout: 30000 });
+    console.log("  ✓ 已提交");
+  } catch (e) {
+    console.log(`  ⚠ 自动提交失败 (可手动 commit): ${(e.stderr || e.message || "").slice(0, 150)}`);
+  }
+
+  console.log("");
+  console.log("=== 迁移完成 ===");
+  console.log("  接下来:");
+  console.log("    1. npx @hupan56/wlkj sync   # 推到团队远程");
+  console.log("    2. 团队其他成员各自跑: npx @hupan56/wlkj update");
+  console.log("       (本地引擎文件不会被删, 之后由 update 重新生成, 互不冲突)");
+  console.log("");
+}
+
+function doHelp() {
+  console.log("");
+  console.log(`wlkj - AI 产品研发工作流 (v${PKG_VERSION})`);
+  console.log("");
+  console.log("=== 终端只用 3 个 (从下载到日常) ===");
+  console.log("");
+  console.log("  npx @hupan56/wlkj install-env    首次: 装环境 (Node/Python/git/pip)");
+  console.log("  npx @hupan56/wlkj init [名字]    首次: 装引擎 + 初始化身份");
+  console.log("  npx @hupan56/wlkj update         日常: 升级 (刷新引擎+补依赖+刷MCP)");
+  console.log("");
+  console.log("=== 日常工作全在 Qoder 里 (不用回终端) ===");
+  console.log("  说中文: '写个XX的需求' '查XX代码' '建任务' '测一下XX'");
+  console.log("  或斜杠: /wl-prd /wl-design /wl-task /wl-code /wl-test /wl-commit");
+  console.log("  (提交/同步 /wl-task 和 /wl-commit 会自动做, 不用单独 npx sync)");
+  console.log("");
+  console.log("=== 进阶 (管理员/特殊情况才用, 不常用) ===");
+  console.log("  npx @hupan56/wlkj doctor     体检 (或在 Qoder 里 /wl-init 无参数)");
+  console.log("  npx @hupan56/wlkj migrate    老团队一次性升级到 Trellis 架构");
+  console.log("  npx @hupan56/wlkj run <脚本> 万能跑脚本 (AI 内部用, 用户很少需要)");
+  console.log("");
+  console.log("  看不到命令? 新建对话 / 重启 QoderWork");
+  console.log("  环境问题? python .qoder/scripts/setup/init_doctor.py --fix");
+  console.log("");
+}
+
+function doInstallEnv(checkOnly = false, location = null) {
+  const { execSync } = require("child_process");
+  const isWin = process.platform === "win32";
+  const isMac = process.platform === "darwin";
+
+  // 解析 --location（CLI 入口已提取，这里兜底）
+  console.log("\n=== 环境检测 ===\n");
+  if (location) {
+    console.log(`  安装位置: ${location}${isWin ? "" : " (仅 Windows winget 支持指定目录)"}`);
+    // Windows: 预建目录
+    if (isWin) {
+      try { fs.mkdirSync(location, { recursive: true }); } catch { /* */ }
+    }
+  }
+
+  // 检测函数
+  function check(cmd) {
+    try { return execSync(`${cmd} --version`, { encoding: "utf-8", timeout: 5000, stdio: "pipe" }).trim().split("\n")[0]; }
+    catch { return null; }
+  }
+  function has(cmd) {
+    try { execSync(`where ${cmd}`, { encoding: "utf-8", timeout: 3000, stdio: "pipe" }); return true; }
+    catch { try { execSync(`which ${cmd}`, { encoding: "utf-8", timeout: 3000, stdio: "pipe" }); return true; } catch { return false; } }
+  }
+  // Windows: 把目录加到用户 PATH（幂等，已存在不重复加）
+  function addToPathWin(dir) {
+    if (!isWin) return false;
+    try {
+      // 用 setx 会截断超长 PATH，改用 PowerShell 读 User PATH 追加
+      const ps = `powershell -NoProfile -Command "$p=[Environment]::GetEnvironmentVariable('Path','User'); if($p -notlike '*{dir}*'){[Environment]::SetEnvironmentVariable('Path',$p.TrimEnd(';')+';{dir}','User')}"`.replace(/{dir}/g, dir.replace(/\\/g, "\\\\"));
+      execSync(ps, { stdio: "pipe", timeout: 15000 });
+      return true;
+    } catch (e) { console.log(`  [WARN] 加 PATH 失败（可手动加）: ${dir}`); return false; }
+  }
+  function install(name, wingetId, brewPkg) {
+    if (checkOnly) return false;
+    try {
+      if (isWin && has("winget")) {
+        console.log(`  用 winget 装 ${name}...`);
+        // winget --location 不一定被安装包尊重，但先传上
+        let cmd = `winget install --id ${wingetId} -e --source winget --accept-source-agreements --accept-package-agreements`;
+        if (location) cmd += ` --location "${location}"`;
+        execSync(cmd, { stdio: "inherit", timeout: 300000 });
+        return true;
+      } else if (isMac && has("brew")) {
+        console.log(`  用 brew 装 ${name}...`);
+        execSync(`brew install ${brewPkg}`, { stdio: "inherit", timeout: 300000 });
+        return true;
+      } else if (!isWin && !isMac) {
+        // Linux: 尝试 apt/dnf/yum
+        for (const [mgr, pkg] of [["apt", brewPkg], ["dnf", brewPkg]]) {
+          if (has(mgr)) {
+            console.log(`  用 ${mgr} 装 ${name}...`);
+            execSync(`sudo ${mgr} install -y ${pkg}`, { stdio: "inherit", timeout: 300000 });
+            return true;
+          }
+        }
+      }
+    } catch (e) { console.log(`  自动安装失败: ${(e.message || "").slice(0, 80)}`); }
+    return false;
+  }
+
+  const nodeVer = check("node");
+  const pyVer = check("python") || check("python3");
+  const gitVer = check("git");
+
+  console.log(`  Node.js: ${nodeVer ? "[OK] " + nodeVer : "[缺失] (npx 命令需要)"}`);
+  console.log(`  Python:  ${pyVer ? "[OK] " + pyVer : "[缺失] (引擎需要)"}`);
+  console.log(`  git:     ${gitVer ? "[OK] " + gitVer : "[缺失] (可选, 核心功能不依赖)"}`);
+
+  if (checkOnly) {
+    console.log("\n仅检测。去掉 --check 自动安装。");
+    return;
+  }
+
+  const need = [];
+  if (!nodeVer) {
+    console.log("");
+    if (nodeVer || install("Node.js", "OpenJS.NodeJS.LTS", "node")) { console.log(`  [OK] Node.js 已装`); }
+    else { need.push("Node.js (手动: https://nodejs.org)"); }
+  }
+  if (!pyVer) {
+    console.log("");
+    if (install("Python", "Python.Python.3.12", "python@3.12")) { console.log(`  [OK] Python 已装`); }
+    else { need.push("Python (手动: https://python.org, 勾 Add to PATH)"); }
+  }
+  if (!gitVer) {
+    console.log("");
+    if (install("git", "Git.Git", "git")) { console.log(`  [OK] git 已装`); }
+    else { need.push("git (手动: https://git-scm.com, 可选)"); }
+  }
+
+  // --location 模式: 提示用户验证安装位置 + 手动加 PATH
+  // （winget 的 --location 对 Node/Python 不一定生效，需用户确认）
+  if (location && isWin) {
+    console.log(`\n--- 安装位置确认 ---`);
+    console.log(`  你指定了: ${location}`);
+    console.log(`  注意: winget 的 --location 对 Node.js/Python 不一定生效`);
+    console.log(`        (取决于安装包是否支持自定义路径)`);
+    console.log(`  请检查实际装到哪了:`);
+    console.log(`    重新打开终端后跑: node --version  python --version  git --version`);
+    console.log(`  如果某软件没进 PATH, 手动把它加进去:`);
+    console.log(`    设置 → 系统 → 关于 → 高级系统设置 → 环境变量 → Path → 新建`);
+    console.log(`    或用命令: npx @hupan56/wlkj add-path "D:\\wldev\\nodejs"`);
+  }
+
+  // Python pip 依赖 (知识图谱/MCP/测试需要)
+  console.log("\n--- Python 依赖 ---");
+  const pyCmd = check("python") ? "python" : (check("python3") ? "python3" : null);
+  if (pyCmd) {
+    // 找 requirements.txt: 引擎已安装则用 .qoder/scripts/../requirements.txt
+    const reqPaths = [
+      path.join(process.cwd(), "requirements.txt"),
+      path.join(process.cwd(), ".qoder", "..", "requirements.txt"),
+    ].filter(p => fs.existsSync(p));
+    if (reqPaths.length > 0) {
+      console.log(`  安装 pip 依赖: ${path.basename(reqPaths[0])} (失败自动切国内镜像)`);
+      installPipDeps(pyCmd, reqPaths[0]);
+    } else {
+      console.log("  [跳过] 未找到 requirements.txt (先 npx @hupan56/wlkj init 安装引擎)");
+    }
+  } else {
+    console.log("  [跳过] Python 未装, 无法装 pip 依赖");
+  }
+
+  console.log("\n=== 结果 ===");
+  if (need.length === 0) {
+    console.log("  环境就绪! 下一步: npx @hupan56/wlkj init");
+    console.log("  (新装的可能需要重新打开终端)");
+  } else {
+    console.log("  以下需手动安装:");
+    need.forEach(n => console.log("    - " + n));
+  }
+}
+
+// add-path: 把目录加到 Windows 用户 PATH（幂等）
+function doAddPath(dir) {
+  if (!dir) { console.log("用法: npx @hupan56/wlkj add-path <目录>"); return; }
+  if (process.platform !== "win32") {
+    console.log("add-path 仅支持 Windows。Mac/Linux 请手动加到 ~/.zshrc 或 ~/.bashrc");
+    return;
+  }
+  const abs = path.resolve(dir);
+  if (!fs.existsSync(abs)) {
+    console.log(`[警告] 目录不存在: ${abs}（仍会加到 PATH）`);
+  }
+  try {
+    const ps = `powershell -NoProfile -Command "$p=[Environment]::GetEnvironmentVariable('Path','User'); if($p -notlike '*${abs.replace(/\\/g,"\\\\")}*'){[Environment]::SetEnvironmentVariable('Path',$p.TrimEnd(';')+';${abs.replace(/\\/g,"\\\\")}','User'); Write-Output 'ADDED'} else { Write-Output 'EXISTS' }"`;
+    const out = execSync(ps, { encoding: "utf-8", timeout: 15000 }).trim();
+    console.log(`  ${out === "ADDED" ? "已加入" : "已存在(无需重复加)"}: ${abs}`);
+    console.log(`  ⚠ 需要重新打开终端才生效`);
+  } catch (e) {
+    console.log(`  失败: ${(e.message || "").slice(0, 100)}`);
+    console.log(`  手动加: 设置 → 系统 → 关于 → 高级系统设置 → 环境变量 → Path → 新建 → ${abs}`);
+  }
+}
+
+const [,, cmd, ...rest] = process.argv;
+const mapped = rest.map(a => a === "-p" ? "--priority" : a);
+
+switch (cmd) {
+  case "init": doInit(rest[0], rest[1]); break;
+  case "update": case "upgrade": doUpdate(); break;
+  case "migrate": doMigrate(); break;
+  case "install-env": {
+    const checkOnly = rest.includes("--check");
+    // 提取 --location <dir> 或 --location=<dir>
+    let loc = null;
+    const li = rest.indexOf("--location");
+    if (li !== -1 && rest[li + 1]) loc = rest[li + 1];
+    const eq = rest.find(a => a.startsWith("--location="));
+    if (eq) loc = eq.slice("--location=".length);
+    doInstallEnv(checkOnly, loc);
+    break;
+  }
+  case "add-path": doAddPath(rest[0]); break;
+  case "task": process.stdout.write(py("task.py", mapped)); break;
+  case "status": doStatus(); break;
+  case "session": process.stdout.write(py("add_session.py", rest)); break;
+  case "help": case "--help": case "-h": doHelp(); break;
+
+  // ── 核心 5 个: 装/升/体检/同步/万能跑 ──
+  case "doctor": case "体检":
+    runScript("init_doctor.py", rest); break;
+  case "sync": case "push": case "commit":
+    runScript("team_sync.py", ["push", ...rest.filter(a => a !== "push")]); break;
+  case "pull":
+    runScript("team_sync.py", ["pull"]); break;
+
+  // ── 万能透传: npx wlkj run <脚本名> [参数...] ──
+  // 任何 .qoder/scripts/ 下的脚本都能跑, 不用记命令名
+  // 例: npx wlkj run kg_build.py --rebuild
+  //     npx wlkj run eval_prd.py xxx.md
+  //     npx wlkj run autotest.py quick
+  case "run": {
+    // 万能跑脚本 (AI 内部用, 用户日常不直接用 — 用 /命令 或 init/update)
+    if (!rest[0]) { console.log("用法: npx wlkj run <脚本名> [参数...]\n例: npx wlkj run kg_build.py --rebuild"); break; }
+    runScript(rest[0], rest.slice(1));
+    break;
+  }
+
+  case "提交": case "拉取最新": case "同步":
+  case "查看状态": case "提交PRD": case "提交Spec": case "提交任务":
+    gitOp(cmd); break;
+  default: doHelp();
 }