cicy-desktop 2.1.179 → 2.1.181

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cicy-desktop",
-  "version": "2.1.179",
+  "version": "2.1.181",
   "description": "CiCy - AI-powered operating system browser",
   "main": "src/main.js",
   "bin": {

package/src/backends/sidecar-ipc.js

@@ -340,13 +340,16 @@ function register({ sidecarLogPath } = {}) {
 
   // ⋯ menu → 重建 Docker:删容器 + 用新 env(docker team 网关 key)重新 docker run(保留
   // volume 数据)。换 key 的唯一途径。渲染端已 confirm。
-  ipcMain.handle("docker:app-recreate", async () => {
+  ipcMain.handle("docker:app-recreate", async (e) => {
     try {
       await ensureDockerTeam();
-      await appDocker.recreate({ ...(await appOpts()) });
+      await appDocker.recreate({
+        ...(await appOpts()),
+        onProgress: (ev) => { try { e.sender.send("docker:app-progress", ev); } catch {} },
+      });
       await registerAppTeam();
       return { ok: true };
-    } catch (e) { return { ok: false, error: e.message }; }
+    } catch (err) { return { ok: false, error: err.message }; }
   });
 
   // ⋯ menu(仅 macOS)→ 「授权容器访问 Mac」:不挂 docker,改走 SSH。colima 自带

package/src/main.js

@@ -1377,25 +1377,38 @@ function cleanup() {
   log.info("[Cleanup] shutting down child services");
   try { cicyCodeSidecar.stop(); } catch (e) { /* best-effort */ }
 
-  // Kill cicy-code, all tmux servers, gotty/ttyd, and code-server processes
-  // that the cicy-code sidecar may have spawned. best-effort, sync, cross-platform.
+  // Reap leftover NATIVE host helpers from the pre-docker-only era (a stray
+  // cicy-code.exe / ttyd / gotty / code-server). 主人: quitting CiCy Desktop must
+  // NOT touch Docker — in docker-only these all run INSIDE the container, and the
+  // Docker engine (colima VM on mac / WSL distro+dockerd on win) is a separate
+  // background service that survives the app + the container is --restart
+  // unless-stopped. So we ONLY kill exact native host targets, never the engine.
   try {
     const { execSync } = require("child_process");
     const targets = ["cicy-code", "ttyd", "gotty", "code-server"];
 
     if (process.platform === "win32") {
-      // Windows: taskkill /F /IM <name>.exe (and base name in case extension differs)
+      // Windows: taskkill /F /IM <name>.exe — EXACT image name, no wildcards, so it
+      // can only hit a native cicy-code.exe (retired), never wsl.exe / dockerd /
+      // vmmem / the WSL distro. We never `wsl --terminate/--shutdown` on quit.
       for (const t of targets) {
         try { execSync(`taskkill /F /IM ${t}.exe`, { stdio: "ignore", windowsHide: true }); } catch {}
-        try { execSync(`taskkill /F /IM ${t}`, { stdio: "ignore", windowsHide: true }); } catch {}
       }
-      // Windows has no tmux by default; nothing to do.
     } else {
-      // macOS / Linux: pkill matches by command line.
-      for (const t of targets) {
-        try { execSync(`pkill -f ${t}`, { stdio: "ignore" }); } catch {}
+      // macOS / Linux: pkill matches by FULL command line. ⚠️ docker-only: cicy-code
+      // / ttyd / gotty / code-server all run INSIDE the container, NOT on the host —
+      // there is normally nothing here to kill. CRITICAL: never `pkill -f cicy-code`
+      // plainly — the colima profile is named `cicy-code`, so the Lima VM hostagent
+      // runs as `limactl ... colima-cicy-code` and a bare match KILLS THE VM on every
+      // quit → next launch sees Docker "down" and re-bootstraps ("重新 install" bug).
+      // Anchor cicy-code to the native --desktop sidecar form (retired) only.
+      const unixPats = ["cicy-code --desktop", "ttyd", "gotty", "code-server"];
+      for (const p of unixPats) {
+        try { execSync(`pkill -f '${p}'`, { stdio: "ignore" }); } catch {}
       }
-      try { execSync(`tmux kill-server`, { stdio: "ignore" }); } catch {}
+      // Host tmux only (native path, retired); the container's tmux is in its own
+      // namespace and unaffected. (No -f cicy-code match here either.)
+      try { execSync(`pkill -f 'tmux.*cicy'`, { stdio: "ignore" }); } catch {}
     }
   } catch (e) {
     log.warn(`[Cleanup] kill children failed: ${e.message}`);

package/src/sidecar/colima-docker.js

@@ -37,6 +37,12 @@ const IMAGE   = process.env.CICY_DOCKER_IMAGE || "cicybot/cicy-code:latest";
 const IS_ARM  = process.arch === "arm64";
 const ARCH_TAG = IS_ARM ? "arm64" : "amd64";
 const PLATFORM_FLAG = IS_ARM ? "--platform linux/amd64" : "";
+// 主人: 容器额外暴露的端口段(给容器内 agent 跑服务用),宿主 127.0.0.1 直达。
+const EXTRA_PORTS = process.env.CICY_EXTRA_PORTS || "18000-19999";
+// 主人: Colima VM 资源,4C8G 起步(可用 env 覆盖,不写死)。
+const VM_CPUS   = process.env.CICY_COLIMA_CPUS   || "4";
+const VM_MEMORY = process.env.CICY_COLIMA_MEMORY || "8";
+const VM_DISK   = process.env.CICY_COLIMA_DISK   || "30";
 
 // Colima 基础 VM 镜像:colima `start` 默认从 github.com/abiosoft/colima-core 下,
 // CN 直接 EOF 拉不下来(真机实测)。colima 0.10.3 没有 --disk-image-mirror(那是
@@ -222,7 +228,7 @@ async function startVM({ emit } = {}) {
   const vzArgs = IS_ARM
     ? `--vm-type vz --vz-rosetta --mount-type virtiofs`
     : `--vm-type vz --mount-type virtiofs`;
-  const common = `--cpus 2 --memory 4 --disk 30 ${diskArgs}`;
+  const common = `--cpus ${VM_CPUS} --memory ${VM_MEMORY} --disk ${VM_DISK} ${diskArgs}`;
   for (let attempt = 1; attempt <= 3; attempt++) {
     emit && emit({ phase: "container", status: "running", message: `启动 Colima 运行环境(首次较慢,请耐心)…${attempt > 1 ? `(重试 ${attempt})` : ""}` });
     try {
@@ -263,6 +269,28 @@ async function loadImage(tarball, { emit } = {}) {
   if (m && m[1] !== IMAGE) { try { await dk(`tag ${m[1]} ${IMAGE}`, { timeout: 15000 }); } catch {} }
 }
 
+// 主人修复「为什么没用最新的 docker」: imagePresent() 只看本地有没有 `:latest` 标签,
+// 旧镜像在就永远跳过下载 → 卡在过期镜像。这里改成校验 OSS tarball 的 ETag:本地缺镜像、
+// 或 OSS 的 ETag 跟上次 load 的不一致 → 重下重载(删旧缓存包,避免同尺寸被误跳过)。
+// 非破坏性:不删 VM、不删 volume(数据/token 不丢)。返回是否真的刷新了。
+async function ensureFreshImage({ emit } = {}) {
+  const e = (ev) => { try { emit && emit(ev); } catch {} };
+  const present = await imagePresent();
+  const remote = await docker.remoteImageEtag().catch(() => "");
+  const loaded = docker.readLoadedImageEtag();
+  // 本地有镜像、且能证明是最新(ETag 一致)→ 不动。HEAD 失败(remote 空)时不强刷,
+  // 避免离线/被墙时把能用的旧镜像也拖垮。
+  if (present && remote && loaded && remote === loaded) return false;
+  if (present && !remote) return false; // 拿不到远端指纹,保守不刷
+  if (present && remote !== loaded) { e({ phase: "image", status: "running", message: "检测到更新的镜像,正在拉取最新版…" }); docker.clearImageTarball(); }
+  let tarball;
+  try { tarball = await docker.downloadImageTarball({ emit }); }
+  catch (err) { if (present) { e({ phase: "image", status: "running", message: `最新镜像下载失败(${err.message}),沿用现有镜像` }); return false; } throw err; }
+  await loadImage(tarball, { emit });
+  if (remote) docker.writeLoadedImageEtag(remote);
+  return true;
+}
+
 // 宿主 127.0.0.1:port 健康探针 —— Lima 自动把 VM 内 127.0.0.1 端口转发到宿主。
 const probeHealth = docker.probeHealth;
 
@@ -277,44 +305,41 @@ const probeHealth = docker.probeHealth;
 //     bind-mount 会用空的宿主目录**遮住镜像里预装的 /home/cicy**(cicy-code 装在那),
 //     entrypoint 找不到就试图全局 npm 重装 → EACCES 崩溃,:8009 起不来。named volume
 //     首次挂载会**从镜像内容预填充**,容器才看得到预装的 cicy-code(和 WSL 一致)。
-// Shared folder bind: the CURRENT macOS user's ~/Desktop/Share ↔
-// /home/cicy/cicy-ai/Share in the container. Auto-created (with a readme) on every
-// container start if missing; os.homedir() makes it per-user. Colima mounts the
-// host $HOME into the VM, so the direct path works (no /mnt translation like WSL).
-const SHARE_README = `# CiCy 共享目录 / Shared Folder
+// 主人: 把宿主 ~/projects 挂进容器 /home/cicy/projects(~ 用 os.homedir() 展开,绝不写死)。
+// Colima 把宿主 $HOME 挂进 VM,所以直接路径就能用(不像 WSL 要 /mnt 转换)。
+// 源目录不存在先建出来,否则 docker 建挂载点会报错挡住容器启动。
+const PROJECTS_README = `# CiCy 持久工作区 / Persistent Workspace
 
-这个文件夹与 CiCy 容器之间双向共享 —— 你和容器里的 agent 都能读写同一份文件。
+这个文件夹与 CiCy 容器双向共享,而且是**持久的** —— 它在你电脑的真实磁盘上,
+不在容器里。容器删了、重建了、升级了,这里的文件都还在,不会丢。
 
-- 你的电脑上: ~/Desktop/Share （就是这个文件夹）
-- 容器里: /home/cicy/cicy-ai/Share
+- 你的电脑上: ~/projects （就是这个文件夹）
+- 容器里: /home/cicy/projects
 
-把文件丢进来,CiCy 里的 agent 就能访问;agent 写到容器 Share 里的东西,也会出现在这里。
+把代码仓库 / 项目放在这里,CiCy 里的 agent 就能直接读写;它们改的东西也实时
+出现在你电脑上。容器是临时的,这个目录才是你工作的家。
 
 ---
 
-This folder is shared both ways between your computer and the CiCy container.
+This folder is shared both ways with the CiCy container and is **persistent** —
+it lives on your computer's real disk, not inside the container. Delete, rebuild
+or upgrade the container and everything here survives.
 
-- On your computer: ~/Desktop/Share (this folder)
-- Inside the container: /home/cicy/cicy-ai/Share
+- On your computer: ~/projects (this folder)
+- Inside the container: /home/cicy/projects
 
-Drop files here for CiCy agents to read; files agents write to Share show up here too.
+Put your repos / projects here; CiCy agents read and write them directly, and
+their changes show up live on your machine. The container is disposable — this
+directory is where your work actually lives.
 `;
 
-function shareMountArg() {
+function projectsMountArg() {
   try {
-    // 主人: Share 真实目录放 ~/cicy-ai/Share —— 不能用 ~/Desktop:macOS TCC 挡着 colima(VM)
-    // 访问 Desktop/Documents/Downloads,docker 建挂载源时报 'mkdir …/Desktop: operation not
-    // permitted' → 容器起不来。~/cicy-ai 非 TCC、colima 能挂。再在 Desktop 放个软链(桌面可见;
-    // 失败无所谓,真实目录已可用)。
-    const share = path.join(os.homedir(), "cicy-ai", "Share");
-    fs.mkdirSync(share, { recursive: true });
-    const readme = path.join(share, "readme.md");
-    if (!fs.existsSync(readme)) { try { fs.writeFileSync(readme, SHARE_README); } catch {} }
-    try {
-      const link = path.join(os.homedir(), "Desktop", "Share");
-      if (!fs.existsSync(link)) fs.symlinkSync(share, link);
-    } catch {}
-    return `-v '${share}':/home/cicy/cicy-ai/Share`;
+    const dir = path.join(os.homedir(), "projects");
+    fs.mkdirSync(dir, { recursive: true });
+    const readme = path.join(dir, "README.md");
+    if (!fs.existsSync(readme)) { try { fs.writeFileSync(readme, PROJECTS_README); } catch {} }
+    return `-v '${dir}':/home/cicy/projects`;
   } catch { return ""; }
 }
 
@@ -329,15 +354,16 @@ async function runContainer({ port = 8009, container = "cicy-code-docker-8009",
   // 服务,不再从容器 publish 20001-32 —— colima/Lima 转发那个端口段始终到不了容器里只绑
   // 127.0.0.1 的监听(Chrome 一直 ERR_EMPTY_RESPONSE)。容器只暴露 cicy-code 的 :8009。
   const mk = (s) => `run -d --name ${container} --restart unless-stopped ${PLATFORM_FLAG} ` +
-    `-p 127.0.0.1:${port}:8008 -e CICY_PUBLIC=1 -v ${volume}:/home/cicy ${s} ${envArgs} ${IMAGE}`;
-  const share = shareMountArg();
+    `-p 127.0.0.1:${port}:8008 -p 127.0.0.1:${EXTRA_PORTS}:${EXTRA_PORTS} ` +
+    `-e CICY_PUBLIC=1 -v ${volume}:/home/cicy ${s} ${envArgs} ${IMAGE}`;
+  const mounts = projectsMountArg();
   try {
-    await dk(mk(share), { timeout: 90000 });
+    await dk(mk(mounts), { timeout: 90000 });
   } catch (e) {
-    if (!share) throw e;
-    // 兜底: 带 Share 启动失败(如 macOS TCC 挡 colima 访问挂载源)→ 去掉 Share 重试,保证容器
-    // 一定能起(Share 只是附加共享目录,不该挡住整个服务). 主人: '容器起不来' 的修复.
-    console.warn(`[colima] 带 Share 启动失败,去掉 Share 重试: ${e.message}`);
+    if (!mounts) throw e;
+    // 兜底: 带挂载启动失败(如 colima 访问挂载源出错)→ 去掉附加挂载重试,保证容器
+    // 一定能起(projects 只是附加共享目录,不该挡住整个服务). 主人: '容器起不来' 的修复.
+    console.warn(`[colima] 带挂载启动失败,去掉附加挂载重试: ${e.message}`);
     try { await dk(`rm -f ${container}`, { timeout: 20000 }); } catch {}
     await dk(mk(""), { timeout: 90000 });
   }
@@ -445,13 +471,11 @@ async function _bootstrap({ onProgress, port = 8009, container = "cicy-code-dock
     }
   }
 
-  // 4) 镜像(docker load R2 包)
-  if (!(await imagePresent())) {
-    let tarball;
-    try { tarball = await docker.downloadImageTarball({ emit }); }
-    catch (e) { emit({ phase: "image", status: "error", message: `镜像下载失败:${e.message}(点重试续传)` }); return { ok: false, reason: "image_download_failed" }; }
-    try { await loadImage(tarball, { emit }); }
-    catch (e) { emit({ phase: "image", status: "error", message: `镜像导入失败:${e.message}(点重试)` }); return { ok: false, reason: "image_load_failed" }; }
+  // 4) 镜像(docker load R2 包)—— 缺镜像就下,镜像在但 OSS 有更新版也刷新(主人:别卡旧镜像)
+  try { await ensureFreshImage({ emit }); }
+  catch (e) {
+    if (!(await imagePresent())) { emit({ phase: "image", status: "error", message: `镜像下载失败:${e.message}(点重试续传)` }); return { ok: false, reason: "image_download_failed" }; }
+    emit({ phase: "image", status: "running", message: `镜像刷新失败(${e.message}),沿用现有镜像` });
   }
 
   // 5) 容器
@@ -507,7 +531,10 @@ async function dockerRestart({ container = "cicy-code-docker-8009" } = {}) {
 
 // 重建:强删占该端口的任何容器 + 目标容器,再 docker run(用新 env,如新 docker team
 // 网关 key)。保留 bind-mount 宿主目录(数据/api_token 不丢)。破坏性 → 调用方要 confirm。
-async function recreate({ port = 8009, container = "cicy-code-docker-8009", volume = "cicy-team-8009", env = {} } = {}) {
+async function recreate({ onProgress, port = 8009, container = "cicy-code-docker-8009", volume = "cicy-team-8009", env = {} } = {}) {
+  const emit = (ev) => { try { onProgress && onProgress(ev); } catch {} };
+  // 重建 = 用最新镜像重建。OSS 有更新版先刷新(非破坏性,不删 VM/volume),再 rm + run。
+  try { await ensureFreshImage({ emit }); } catch (e) { emit({ phase: "image", status: "running", message: `镜像刷新跳过(${e.message}),用现有镜像重建` }); }
   try { await dk(`ps -aq --filter publish=${port} | xargs -r docker --context ${CTX} rm -f 2>/dev/null; docker --context ${CTX} rm -f ${container} 2>/dev/null; true`, { timeout: 30000 }); } catch {}
   const r = await runContainer({ port, container, volume, env });
   try { await ensureDesktopShortcut(volume, port); } catch {}

package/src/sidecar/docker.js

@@ -181,6 +181,38 @@ function headSize(url, hops = 5) {
   });
 }
 
+// HEAD the URL and return a freshness fingerprint (ETag, else Last-Modified).
+// Mirrors headSize (follows redirects, node http so it works without curl).
+// "" on any failure → callers treat unknown as "can't prove fresh".
+function headETag(url, hops = 5) {
+  return new Promise((resolve) => {
+    if (hops <= 0) return resolve("");
+    const lib = url.startsWith("https:") ? https : http;
+    const req = lib.request(url, { method: "HEAD", timeout: 15000, headers: { "User-Agent": DL_UA } }, (res) => {
+      if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+        res.resume();
+        return headETag(res.headers.location, hops - 1).then(resolve);
+      }
+      resolve(String(res.headers["etag"] || res.headers["last-modified"] || "").trim());
+    });
+    req.on("error", () => resolve(""));
+    req.on("timeout", () => { req.destroy(); resolve(""); });
+    req.end();
+  });
+}
+
+// Marker recording the OSS fingerprint of the image tarball we last `docker load`ed.
+// Lets recreate/bootstrap detect a refreshed OSS image (same `:latest` tag, new
+// content) and re-pull — without it, `imagePresent()` stays true forever and the
+// machine is pinned to a stale image (主人 bug: "为什么没用最新的docker").
+function imageEtagPath() { return path.join(downloadsDir(), "cicy-code-latest.etag"); }
+function readLoadedImageEtag() { try { return fs.readFileSync(imageEtagPath(), "utf8").trim(); } catch { return ""; } }
+function writeLoadedImageEtag(v) { try { fs.writeFileSync(imageEtagPath(), String(v || "")); } catch {} }
+async function remoteImageEtag() { return headETag(R2_TARBALL); }
+// Drop the cached tarball so a stale copy on disk can't be reused (downloadImageTarball
+// skips a complete file by size, which a same-size new image would wrongly satisfy).
+function clearImageTarball() { try { fs.unlinkSync(imageTarballPath()); } catch {} }
+
 // Download `url`→`dest` but: SKIP if the file is already complete, RESUME if it's
 // a partial, retry with progress, fall back to `mirror`. This is the core of the
 // user's "下载了就不重复下载 / 步骤走过的不要再走".
@@ -735,4 +767,6 @@ module.exports = {
   launchElevated, wslMissing, ensureWsl,
   // platform-agnostic download/retry primitives, reused by native.js
   ensureDownloaded, curlDownload, withRetry, waitUntil, run, headSize,
+  // image freshness (主人: 修「重建仍用旧镜像」—— 校验 OSS ETag 变了才重下重载)
+  headETag, remoteImageEtag, readLoadedImageEtag, writeLoadedImageEtag, clearImageTarball,
 };

package/src/sidecar/wsl-docker.js

@@ -21,6 +21,8 @@ const log = require("electron-log"); // persisted main.log — bootstrap timing/
 // Dedicated distro name — NEVER reuse/clobber a user's own "Ubuntu" distro.
 const DISTRO   = process.env.CICY_WSL_DISTRO || "cicy-code-wsl";
 const IMAGE    = process.env.CICY_DOCKER_IMAGE || "cicybot/cicy-code:latest";
+// 主人: 容器额外暴露的端口段(给容器内 agent 跑服务用),宿主 127.0.0.1 直达。
+const EXTRA_PORTS = process.env.CICY_EXTRA_PORTS || "18000-19999";
 // PRE-BAKED WSL rootfs (built in CI, .github/workflows/build-wsl-package.yml):
 // Ubuntu 22.04 + Docker Engine + the cicy-code image already loaded into
 // /var/lib/docker, with dockerd auto-start via /etc/wsl.conf. We just download
@@ -360,6 +362,25 @@ async function loadImage(winTarballPath, { emit } = {}) {
   if (m && m[1] !== IMAGE) { try { await wslRun(`docker tag ${m[1]} ${IMAGE}`, { timeout: 15000 }); } catch {} }
 }
 
+// 主人修复「卡在旧镜像」: imagePresent() 只看本地有没有 `:latest`,旧镜像在就永远跳过下载。
+// 改成校验 OSS tarball ETag:缺镜像、或 ETag 跟上次 load 不一致 → 重下重载(删旧缓存包)。
+// 非破坏性:不删发行版/不删 volume。返回是否真刷新了。与 colima 端逻辑一致。
+async function ensureFreshImage({ emit } = {}) {
+  const e = (ev) => { try { emit && emit(ev); } catch {} };
+  const present = await imagePresent();
+  const remote = await docker.remoteImageEtag().catch(() => "");
+  const loaded = docker.readLoadedImageEtag();
+  if (present && remote && loaded && remote === loaded) return false;
+  if (present && !remote) return false; // 拿不到远端指纹,保守不刷
+  if (present && remote !== loaded) { e({ phase: "image", status: "running", message: "检测到更新的镜像,正在拉取最新版…" }); docker.clearImageTarball(); }
+  let tarball;
+  try { tarball = await docker.downloadImageTarball({ emit }); }
+  catch (err) { if (present) { e({ phase: "image", status: "running", message: `最新镜像下载失败(${err.message}),沿用现有镜像` }); return false; } throw err; }
+  await loadImage(tarball, { emit });
+  if (remote) docker.writeLoadedImageEtag(remote);
+  return true;
+}
+
 // HTTP /health probe on 127.0.0.1:port from Windows — WSL2 forwards localhost,
 // so a container published on :port is reachable here. Reuse docker.js's probe.
 const probeHealth = docker.probeHealth;
@@ -375,40 +396,47 @@ const probeHealth = docker.probeHealth;
 //     network-exposed; the api_token gates access. WSL2's localhost relay then
 //     forwards the distro's 127.0.0.1:<port> to Windows 127.0.0.1:<port>.
 // Only :<port> is published — sshd/cron stay inside the container's own netns.
-// Shared folder bind: the CURRENT Windows user's ~/Desktop/Share ↔
-// /home/cicy/cicy-ai/Share in the container — a drop-zone both the user and the
-// agent can read/write. Auto-created (with a readme) on every container start if
-// missing; os.homedir() makes it per-user (never hard-coded to one account).
-// Returns the docker `-v` arg, or "" if setup fails (mount is best-effort).
-const SHARE_README = `# CiCy 共享目录 / Shared Folder
+// Persistent workspace bind: the CURRENT Windows user's ~/projects ↔
+// /home/cicy/projects in the container — both the user and the agent read/write
+// it, and it lives on the host disk so it survives container delete/rebuild.
+// Auto-created (with a README) on every container start if missing; os.homedir()
+// makes it per-user (never hard-coded). Returns the `-v` arg, or "" on failure.
+const PROJECTS_README = `# CiCy 持久工作区 / Persistent Workspace
 
-这个文件夹与 CiCy 容器之间双向共享 —— 你和容器里的 agent 都能读写同一份文件。
+这个文件夹与 CiCy 容器双向共享,而且是**持久的** —— 它在你电脑的真实磁盘上,
+不在容器里。容器删了、重建了、升级了,这里的文件都还在,不会丢。
 
-- 你的电脑上: ~/Desktop/Share （就是这个文件夹）
-- 容器里: /home/cicy/cicy-ai/Share
+- 你的电脑上: ~/projects （就是这个文件夹）
+- 容器里: /home/cicy/projects
 
-把文件丢进来,CiCy 里的 agent 就能访问;agent 写到容器 Share 里的东西,也会出现在这里。
+把代码仓库 / 项目放在这里,CiCy 里的 agent 就能直接读写;它们改的东西也实时
+出现在你电脑上。容器是临时的,这个目录才是你工作的家。
 
 ---
 
-This folder is shared both ways between your computer and the CiCy container.
+This folder is shared both ways with the CiCy container and is **persistent** —
+it lives on your computer's real disk, not inside the container. Delete, rebuild
+or upgrade the container and everything here survives.
 
-- On your computer: ~/Desktop/Share (this folder)
-- Inside the container: /home/cicy/cicy-ai/Share
+- On your computer: ~/projects (this folder)
+- Inside the container: /home/cicy/projects
 
-Drop files here for CiCy agents to read; files agents write to Share show up here too.
+Put your repos / projects here; CiCy agents read and write them directly, and
+their changes show up live on your machine. The container is disposable — this
+directory is where your work actually lives.
 `;
 
-function shareMountArg() {
+// 主人: 把宿主 ~/projects 挂进容器 /home/cicy/projects(~ 用 os.homedir() 展开,绝不写死)。
+// Windows 路径 C:\Users\<user>\projects → WSL 视图 /mnt/c/Users/<user>/projects。
+function projectsMountArg() {
   try {
-    const winShare = path.join(os.homedir(), "Desktop", "Share");
-    fs.mkdirSync(winShare, { recursive: true });
-    const readme = path.join(winShare, "readme.md");
-    if (!fs.existsSync(readme)) { try { fs.writeFileSync(readme, SHARE_README); } catch {} }
-    // C:\Users\<user>\Desktop\Share → /mnt/c/Users/<user>/Desktop/Share (WSL view)
-    const wslShare = winShare.replace(/^([A-Za-z]):/, (_, d) => `/mnt/${d.toLowerCase()}`).replace(/\\/g, "/");
-    return `-v '${wslShare}':/home/cicy/cicy-ai/Share`;
-  } catch (e) { log.warn(`[wsl-docker] Share mount setup failed: ${e.message}`); return ""; }
+    const winProjects = path.join(os.homedir(), "projects");
+    fs.mkdirSync(winProjects, { recursive: true });
+    const readme = path.join(winProjects, "README.md");
+    if (!fs.existsSync(readme)) { try { fs.writeFileSync(readme, PROJECTS_README); } catch {} }
+    const wslProjects = winProjects.replace(/^([A-Za-z]):/, (_, d) => `/mnt/${d.toLowerCase()}`).replace(/\\/g, "/");
+    return `-v '${wslProjects}':/home/cicy/projects`;
+  } catch (e) { log.warn(`[wsl-docker] projects mount setup failed: ${e.message}`); return ""; }
 }
 
 async function runContainer({ port = 8009, container = "cicy-code-docker", volume = "cicy-team-8009", env = {} } = {}) {
@@ -427,7 +455,7 @@ async function runContainer({ port = 8009, container = "cicy-code-docker", volum
   // 223.5.5.5 (CN-fast) first, Google 8.8.8.8 as the overseas fallback.
   // 主人方案: Chrome 的 per-profile 代理改由「宿主 mihomo」(host-mihomo.js)服务,不再从容器
   // publish 20001-32(WSL/colima 转发那段口到不了容器里只绑 127.0.0.1 的监听)。容器只暴露 :8009。
-  const cmd = `docker run -d --name ${container} --restart unless-stopped --dns 223.5.5.5 --dns 8.8.8.8 -p 127.0.0.1:${port}:8008 -e CICY_PUBLIC=1 -v ${volume}:/home/cicy ${shareMountArg()} ${envArgs} ${IMAGE}`;
+  const cmd = `docker run -d --name ${container} --restart unless-stopped --dns 223.5.5.5 --dns 8.8.8.8 -p 127.0.0.1:${port}:8008 -p 127.0.0.1:${EXTRA_PORTS}:${EXTRA_PORTS} -e CICY_PUBLIC=1 -v ${volume}:/home/cicy ${projectsMountArg()} ${envArgs} ${IMAGE}`;
   await wslRun(cmd, { timeout: 60000 });
   ensureDesktopShortcut(volume, port).catch(() => {});
   return { started: true };
@@ -616,17 +644,14 @@ async function _bootstrap({ onProgress, port = 8009, container = "cicy-code-dock
     done();
   } else done(true);
 
-  // 5) Base image — pre-baked into the package, so this normally just confirms.
-  //    The download-tarball path is a fallback for a non-pre-baked rootfs.
+  // 5) Base image — pre-baked into the package, normally just confirms; but if the
+  //    OSS tarball has a newer build (ETag changed) it refreshes (主人:别卡旧镜像)。
   begin("ensure-image");
-  if (!(await imagePresent())) {
-    let tarball;
-    try { tarball = await docker.downloadImageTarball({ emit }); }
-    catch (e) { fail("image_download_failed", e.message); emit({ phase: "image", status: "error", message: `镜像下载失败：${e.message}（点重试续传）` }); finish(false, "image_download_failed"); return { ok: false, reason: "image_download_failed" }; }
-    try { await loadImage(tarball, { emit }); }
-    catch (e) { fail("image_load_failed", e.message); emit({ phase: "image", status: "error", message: `镜像导入失败：${e.message}（点重试）` }); finish(false, "image_load_failed"); return { ok: false, reason: "image_load_failed" }; }
-    done();
-  } else done(true);
+  try { await ensureFreshImage({ emit }); done(); }
+  catch (e) {
+    if (!(await imagePresent())) { fail("image_download_failed", e.message); emit({ phase: "image", status: "error", message: `镜像下载失败：${e.message}（点重试续传）` }); finish(false, "image_download_failed"); return { ok: false, reason: "image_download_failed" }; }
+    emit({ phase: "image", status: "running", message: `镜像刷新失败（${e.message}），沿用现有镜像` }); done(true);
+  }
 
   // 6) Container (phase "container" = 启动服务)
   begin("run-container");
@@ -698,7 +723,10 @@ async function dockerRestart({ container = "cicy-code-docker-8009" } = {}) {
 // 重建容器:docker rm -f 旧容器 + docker run 新容器(用新 env,如新的 docker team 网关
 // key)。**保留 volume**(数据/api_token/deviceId 不丢),只是换掉容器本身 + env。
 // 破坏性(短暂中断 + 换 key)→ 调用方要 confirm。
-async function recreate({ port = 8009, container = "cicy-code-docker-8009", volume = "cicy-team-8009", env = {} } = {}) {
+async function recreate({ onProgress, port = 8009, container = "cicy-code-docker-8009", volume = "cicy-team-8009", env = {} } = {}) {
+  const emit = (ev) => { try { onProgress && onProgress(ev); } catch {} };
+  // 重建 = 用最新镜像重建。OSS 有更新版先刷新(非破坏性,不删发行版/volume),再 rm + run。
+  try { await ensureFreshImage({ emit }); } catch (e) { emit({ phase: "image", status: "running", message: `镜像刷新跳过(${e.message}),用现有镜像重建` }); }
   // 强删占用该端口的**任何**容器(含老名字 cicy-code-docker)+ 目标容器 —— 否则
   // runContainer 开头的 probeHealth 看到旧容器还健康会 adopt 它、不重建,key 就换不了。
   try { await wslRun(`docker ps -aq --filter publish=${port} | xargs -r docker rm -f 2>/dev/null; docker rm -f ${container} 2>/dev/null; true`, { timeout: 30000 }); } catch {}