@hupan56/wlkj 2.7.11 → 3.0.0

package/bin/cli.js

@@ -220,6 +220,36 @@ function normalizeRole(r) {
   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"));
@@ -242,15 +272,20 @@ async function doInit(name, roleArg) {
 
   // === 1. 拷贝完整引擎 (镜像 .qoder/ 结构) ===
   // 源: templates/qoder/*  目标: .qoder/*
-  // 注意: init 用 "update" 模式的保护逻辑更安全 —— 新装时目标文件不存在,
-  // 保护逻辑不触发; 重跑 init 时 config.yaml/settings.json 不会被覆盖。
+  // init 复用 update 的三路快照保护: 新装时目标不存在, 保护不触发;
+  // 重跑 init 时用户改过的引擎文件 (如自定义 skill) 不会被覆盖。
   const qoderSrc = path.join(T, "qoder");
   let copied = 0;
   if (fs.existsSync(qoderSrc)) {
-    const r = copyDirRecursive(qoderSrc, path.join(cwd, ".qoder"), "update");
+    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）`);
+      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 ? "更新" : "新建"})`);
@@ -285,15 +320,21 @@ async function doInit(name, roleArg) {
   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, .qoder/learning/, data/, workspace/",
+      "",
       "# 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",
+      ".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", "",
+      "# Python", "__pycache__/", "*.pyc", "*.lock", "*.tmp", "",
     ].join("\n");
     fs.writeFileSync(gitignorePath, baseGitignore, "utf-8");
   }
@@ -354,7 +395,7 @@ async function doInit(name, roleArg) {
           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`);
+          console.log(`         可手动补: ${pyCmd} .qoder/scripts/setup/install_qoderwork.py`);
         }
       }
     } catch (e) {
@@ -373,24 +414,31 @@ async function doInit(name, roleArg) {
   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(`    python .qoder/scripts/setup/install_qoderwork.py`);
   console.log(`\n  看不到命令? 新建对话 / 重启 QoderWork`);
-  console.log(`  环境问题? python .qoder/scripts/init_doctor.py --fix\n`);
+  console.log(`  环境问题? python .qoder/scripts/setup/init_doctor.py --fix\n`);
 }
 
-// 递归拷贝目录, 返回 {copied, protected, skipped}
+// 递归拷贝目录, 返回 {copied, protected, skipped, protectedFiles}
 // mode: "init" (新装, 全拷) | "update" (升级, 保护用户数据)
-function copyDirRecursive(src, dst, mode = "init") {
+// update 模式下采用三路快照保护 (见 readSnapshot/writeSnapshot):
+//   用户改过的引擎文件 (与上次安装快照不同) → 保留用户的, 新版存 .new
+//   用户没动过的引擎文件 → 正常升级
+//   非引擎文件已存在 → 跳过 (留用户数据)
+function copyDirRecursive(src, dst, mode = "init", snap = {}, newSnap = {}, relBase = "") {
   let copied = 0, protectedN = 0, skipped = 0;
-  if (!fs.existsSync(src)) return { copied, protectedN, skipped };
+  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);
+      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") ||
@@ -398,24 +446,47 @@ function copyDirRecursive(src, dst, mode = "init") {
                        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)) {
-          // 新版内容存为 .new 让用户手动合并（仅当内容不同）
           if (!filesEqual(s, d)) {
             fs.copyFileSync(s, d + ".new");
-            protectedN++;
+            protectedN++; protectedFiles.push(rel);
           } else {
             skipped++;
           }
+          // 快照记上游 hash: 用户当前 == 上游 → 下次安全升级; 否则持续保护
+          const sh = fileHash(s); if (sh) newSnap[rel] = sh;
           continue;
         }
-        // 引擎文件: 无条件刷新（纯引擎, 不含用户数据）
-        // 非引擎文件: 已存在跳过, 不存在才建
-        if (isEngine || !fs.existsSync(d)) {
-          fs.copyFileSync(s, d);
-          copied++;
+        // 引擎文件: 三路快照保护
+        if (isEngine) {
+          const userHash = fs.existsSync(d) ? fileHash(d) : null;
+          const snapHash = snap[rel] || null;
+          if (fs.existsSync(d) && userHash && snapHash && userHash !== snapHash) {
+            // 用户改过这个文件! 保留用户的, 新版存 .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 {
-          skipped++;
+          // 非引擎文件: 已存在跳过 (保护用户数据), 不存在才建
+          if (!fs.existsSync(d)) {
+            fs.copyFileSync(s, d);
+            copied++;
+          } else {
+            skipped++;
+          }
         }
       } else {
         // init 模式: 引擎文件全覆盖, 非引擎已存在跳过 (保留用户改动)
@@ -423,10 +494,12 @@ function copyDirRecursive(src, dst, mode = "init") {
           fs.copyFileSync(s, d);
         }
         copied++;
+        // 快照记上游 hash (基线), 供将来升级对比
+        const sh = fileHash(s); if (sh) newSnap[rel] = sh;
       }
     }
   }
-  return { copied, protectedN, skipped };
+  return { copied, protectedN, skipped, protectedFiles };
 }
 
 // 两文件内容是否相同（先比大小再比内容）
@@ -455,6 +528,53 @@ function readEngineVersion(cwd) {
   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）
 function runQoderWorkInstall(cwd, forceCommands) {
   const script = path.join(cwd, ".qoder", "scripts", "install_qoderwork.py");
@@ -524,32 +644,30 @@ function doUpdate() {
   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. 刷新引擎文件（保护 config.yaml / settings.json）===
+  // === 1. 刷新引擎文件 (三路快照保护用户改动) ===
   let copied = 0, protectedN = 0, skipped = 0;
+  let protectedFiles = [];
   if (fs.existsSync(qoderSrc)) {
-    const r = copyDirRecursive(qoderSrc, path.join(cwd, ".qoder"), "update");
+    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} 个配置文件已保留你的本地设置:`);
-    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: 已保护（未改动）`);
+    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, 始终覆盖保证最新）===
@@ -561,12 +679,45 @@ function doUpdate() {
   });
   console.log(`  根文档 + requirements.txt: 已更新`);
 
-  // === 2.5. git pull 拉最新团队数据 (kg.duckdb/kg_db.duckdb/PRD等在git里) ===
+  // === 2.5. git pull 拉最新团队数据 (Trellis: 引擎已由上面 copyDirRecursive 生成, git 只存数据) ===
+  // 团队数据 = config.yaml / settings.json / learning/ + data/ (kg.duckdb/kg_db.duckdb/索引) + workspace/ (PRD/任务)。
+  // 引擎代码 (scripts/skills/...) 已被 gitignore, 不在 git 里, 不会与 pull 冲突。
   // git pull 失败会导致 kg.duckdb 拿不到 → kg MCP 无数据(但仍能连)。
-  // 失败原因常见: 未配 git 身份 / 远程仓库需要认证 / 网络问题。
+  // 失败原因常见: 未配 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 {
-    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: 已是最新`);
@@ -594,10 +745,43 @@ function doUpdate() {
       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("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;
@@ -621,7 +805,10 @@ function doUpdate() {
   }
 
   // === 4. 刷新 QoderWork commands（强制覆盖已存在的）===
-  runQoderWorkInstall(cwd, true);
+  // WLKJ_SKIP_QW_INSTALL=1 时跳过 (测试隔离用, 防止测试目录污染 ~/.qoderwork/.repo-root)
+  if (process.env.WLKJ_SKIP_QW_INSTALL !== "1") {
+    runQoderWorkInstall(cwd, true);
+  }
 
   // === 5. 写版本戳 ===
   writeEngineVersion(cwd);
@@ -683,16 +870,6 @@ function doUpdate() {
       } 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");
@@ -707,16 +884,8 @@ function doUpdate() {
       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 { /* */ }
+  // 注意: .new 文件不再自动删除! 它们是三路快照保护的"新版待对比"信号,
+  // 用户需要看到 .new 才知道"我的改动被保留了, 这里是新版"。用户手动合并后删。
   // 清理缓存 (索引重建后失效的旧缓存)
   const runtimeDir = path.join(cwd, ".qoder", ".runtime");
   let cacheCleaned = 0;
@@ -732,8 +901,25 @@ function doUpdate() {
     console.log(`  [清理] 废弃文件 ${cleaned} 个 + 过期缓存 ${cacheCleaned} 个`);
   }
 
+  // === 5c. 清理 .qoder/.qoder 嵌套残留 (致命 bug 源) ===
+  // 旧版 paths.py 的 _find_repo_root 会误把 .qoder 当 PROJECT_ROOT, 然后往
+  // "PROJECT_ROOT/.qoder/.runtime/" 写缓存 → 误建 .qoder/.qoder/ 目录 →
+  // 这个残留反过来又让 _find_repo_root 再次误判 → 死循环。
+  // 表现: MCP cookie 路径全错 (workspace 跑到 .qoder/workspace), lanhu 永远 cookie 未配置。
+  // v3.0 修了 paths.py 不再误建, 但老用户机器上的残留要清掉, 否则 bug 还在。
+  const nestedQoder = path.join(cwd, ".qoder", ".qoder");
+  if (fs.existsSync(nestedQoder)) {
+    try {
+      fs.rmSync(nestedQoder, { recursive: true, force: true });
+      console.log(`  [清理] 删除嵌套残留 .qoder/.qoder/ (曾导致 MCP cookie 路径错位)`);
+      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", "mcp_launcher.py");
@@ -752,6 +938,7 @@ function doUpdate() {
       } catch (e) { /* --mcp-only 可能不支持, 静默跳过 */ }
     }
   } catch (e) { /* 刷新失败不阻塞升级 */ }
+  }  // end WLKJ_SKIP_QW_INSTALL guard
 
   // === 6.5. MCP 启动实测 (发 initialize 看哪个起不来) ===
   // 这是"根治黄色"的关键一步: 配完 mcp.json 后立即模拟 QoderWork 发 initialize,
@@ -793,7 +980,9 @@ function doUpdate() {
     } else {
       console.log(`  [✗] ${label} 缺失! ${desc}`);
       if (label.includes("duckdb")) {
-        console.log(`       → 修复: npx @hupan56/wlkj run kg_build.py --rebuild`);
+        // 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`);
       }
@@ -846,28 +1035,134 @@ function doUpdate() {
   console.log("");
 }
 
+// ─────────────────────────────────────────────────────────────
+// 一次性迁移: 把引擎代码从团队 git 跟踪里摘出来 (Trellis 化)
+// 团队管理员只跑一次, 其余成员 wlkj update 后自动同步。
+// 原理: git rm -r --cached (只删 git 索引, 不删磁盘文件) + commit。
+// 之后引擎文件仍在磁盘 (由 wlkj update 重新生成), 但不再被 git 跟踪 →
+// 彻底消除"引擎更新污染团队 git"和"新机 init 产生 unrelated histories"。
+// 团队数据 (.qoder/config.yaml, settings.json, 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/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("=== 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("=== 终端只用 3 个 (从下载到日常) ===");
   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("  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("=== 日常工作全在 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("");
 }
 
@@ -1034,6 +1329,7 @@ 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>
@@ -1065,6 +1361,7 @@ switch (cmd) {
   //     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;