minecodex 2.0.1 → 2.0.3

package/features/sites/src/adapters/codex/catalog.mjs

@@ -0,0 +1,26 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { DatabaseSync } from "node:sqlite";
+// Codex 的项目目录与数据库结构在此转换为插件目录快照。
+export class CodexCatalog {
+  constructor(codexHome) { this.codexHome=codexHome; this.status={available:false,reason:"not-read"}; }
+  diagnostics() {return {...this.status};}
+  async snapshot() {
+    let state;
+    try { state = JSON.parse(await readFile(path.join(this.codexHome, ".codex-global-state.json"), "utf8")); }
+    catch (error) { if (error.code === "ENOENT") {this.status={available:false,reason:"catalog-state-unavailable"};return { projects: [], threads: [] };} throw error; }
+    this.status={available:true,reason:null};
+    const projects = Object.entries(state["local-projects"] ?? {}).map(([id, p]) => ({ id, name: p.name || id, rootPaths: (p.rootPaths ?? []).filter(r => typeof r === "string") }));
+    const ids = new Set(state["projectless-thread-ids"] ?? []);
+    let threads = [];
+    if (ids.size) {
+      let db;
+      try {
+        db = new DatabaseSync(path.join(this.codexHome, "state_5.sqlite"), { readOnly: true });
+        threads = db.prepare("SELECT id, title, name FROM threads WHERE archived = 0 ORDER BY updated_at DESC").all().filter(t => ids.has(t.id)).map(t => ({ id: t.id, title: t.name || t.title || t.id }));
+      } catch (error) { if (!/unable to open database/i.test(error.message)) throw error; this.status={available:false,reason:"thread-database-unavailable"}; }
+      finally { db?.close(); }
+    }
+    return { projects, threads };
+  }
+}

package/features/sites/src/adapters/codex/renderer.mjs

@@ -0,0 +1,83 @@
+// 专有路由、页面锚点和原生网页打开协议不跨出此适配器。
+export function createSitesAdapter(signal,codex) {
+  let nativeButton,nativeInner,nativePlus,nativeSiteIcon,nativeMore,nativeExternal,nativeGlobe,nativeActionsClass;
+  const owned="data-mcx-sites";
+  const text=(en,zh)=>(document.documentElement.lang || navigator.language).startsWith("zh") ? zh : en;
+  const visible=e=>!!e?.isConnected && e.getBoundingClientRect().width>0 && e.getBoundingClientRect().height>0;
+  async function until(check) {
+    const end=Date.now()+10000;
+    while(!signal.aborted && Date.now()<end) {const value=check();if(value)return value;await new Promise(resolve=>setTimeout(resolve,80));}
+    throw new Error(text("The native view did not become ready.","原生视图未就绪。"));
+  }
+function nativeProps(node, predicate) {
+  let fiber = codex.currentFiber(node);
+  for (let depth = 0; fiber && depth < 220; depth++, fiber = fiber.return) { const p = fiber.memoizedProps; if (p && predicate(p)) return p; }
+  return null;
+}
+function router() {
+  const p = nativeProps(document.querySelector("[data-sidebar-destination]"), p => p.router?.navigate || p.value?.router?.navigate);
+  return p?.router || p?.value?.router;
+}
+function pageInfo() {
+  if (router()?.state?.location?.pathname !== "/space/sites") return null;
+  const input = [...document.querySelectorAll("input")].find(e => /Search sites|搜索站点|搜尋網站/.test(e.placeholder));
+  if (!input) return null;
+  let page = input.parentElement;
+  while (page && !page.classList.contains("min-h-full")) page = page.parentElement;
+  if (!page || page.children.length < 2) return null;
+  const content = page.children[1], list = page.querySelector('[data-testid="sites-table"], [data-testid="sites-grid"]');
+  const native = nativeProps(list || content.querySelector("button") || content.querySelector("p") || content.lastElementChild?.lastElementChild, p => "viewMode" in p && "shared" in p);
+  const grid = native ? native.viewMode === "grid" : !!page.querySelector('button[aria-label="Grid view"][aria-pressed="true"],button[aria-label="网格视图"][aria-pressed="true"]');
+  const shared = native ? !!native.shared : [...page.querySelectorAll("button[aria-pressed=true]")].some(b => /Shared with you|与你共享|與你共用/.test(b.textContent));
+  const create = [...page.firstElementChild.querySelectorAll("button")].find(b => /^(New|新建|新增)$/.test(b.textContent.trim()) && !b.hasAttribute(owned));
+  codex.report("sites-page",true);
+  return { page, input, content, list, grid, shared, create };
+}
+function fullViewControl(enter) {
+  const pattern = enter ? /^(Enter full view|进入完整视图|进入全屏视图|進入完整檢視|進入全螢幕檢視)$/ : /^(Exit full view|退出完整视图|退出全屏视图|退出完整檢視|退出全螢幕檢視)$/;
+  return [...document.querySelectorAll("button")].find(e => visible(e) && [e.getAttribute("aria-label"), e.getAttribute("title"), e.getAttribute("data-tooltip-content")].some(value => pattern.test(value || "")));
+}
+async function open(origin,url,cwd) {
+    const r = router(); if (!r) throw new Error(text("Native navigation is unavailable.", "原生导航暂不可用。"));
+    if (origin.kind === "thread") {
+      await r.navigate(`/local/${origin.threadId}`);
+      await until(() => codex.currentThreadId() === origin.threadId);
+    } else {
+      const nonce = Date.now();
+      // 项目网页必须进入本地执行草稿，普通聊天模式会丢弃项目上下文。
+      await r.navigate("/", { state: {
+        project: origin.kind === "project" ? { type: "local", projectId: origin.projectId } : null,
+        ...(origin.kind === "project" ? { prefillLocalExecution: true, prefillComposerMode: "local" } : {}),
+        focusComposerNonce: nonce
+      } });
+      await until(() => r.state.location.pathname === "/" && [...document.querySelectorAll('[data-codex-composer="true"]')].some(e => visible(e) && nativeProps(e, p => p.value?.kind === "new" && p.value.focusComposerNonce === nonce)));
+      // 等原生草稿的 layout/effect 完成，浏览器再绑定到当前草稿。
+      await new Promise(resolve => requestAnimationFrame(() => requestAnimationFrame(resolve)));
+    }
+    // 只在同一原聊天中复用网址相同的原生 tab，项目新草稿仍走新建路径。
+    const existing = origin.kind === "thread" && [...document.querySelectorAll('[role="tab"]')].find(e => {
+      const p = nativeProps(e, p => p.tab?.kind === "browser");
+      return p?.tab.props?.browserConversationId === origin.threadId && p.tab.durableRoute?.params?.restoreUrl === url;
+    });
+    if (existing) existing.click();
+    else window.postMessage({ type: "open-browser-tab", ...(origin.kind === "thread" ? { conversationId: origin.threadId } : {}), initialUrl: url, ...(origin.kind === "project" ? { cwd: cwd } : {}), source: "manual", initiator: "sites_library" }, location.origin);
+
+}
+function templates(page) {
+  const create = page.create;
+  if (create) {
+    const template = page.page.querySelector('button[data-size="lg"][data-color="secondary"]');
+    nativeButton = template.className; nativeInner = template.firstElementChild.className;
+    nativePlus = create.querySelector("svg")?.cloneNode(true);
+  }
+  nativeSiteIcon ||= document.querySelector('[data-sidebar-destination="builtin:sites"] svg')?.cloneNode(true);
+  const row = page.list?.querySelector("[data-appgen-row], article");
+  nativeExternal ||= row?.querySelector('button[aria-label*="new tab"]')?.cloneNode(true);
+  nativeActionsClass ||= row?.lastElementChild?.className;
+  nativeGlobe ||= [...(page.list?.querySelectorAll("[data-appgen-row]") || [])].find(r => r.children[2]?.textContent.includes("Everyone"))?.children[2]?.querySelector("svg")?.cloneNode(true);
+  nativeMore ||= row?.querySelector('button[aria-haspopup="menu"] svg')?.cloneNode(true);
+  return {nativeButton,nativeInner,nativePlus,nativeSiteIcon,nativeMore,nativeExternal,nativeGlobe,nativeActionsClass};
+}
+
+return {templates,pageInfo,fullViewControl,open,path:()=>router()?.state?.location?.pathname};
+}

package/features/sites/src/backend/discovery.mjs

@@ -0,0 +1,73 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+const run = promisify(execFile);
+
+export function parseListeners(output) {
+  let pid, command;
+  const entries = new Map();
+  for (const line of output.split("\n")) {
+    if (line[0] === "p") pid = Number(line.slice(1));
+    if (line[0] === "c") command = line.slice(1);
+    if (line[0] !== "n" || !pid) continue;
+    const port = Number(line.match(/:(\d+)$/)?.[1]);
+    if (!port) continue;
+    const address = line.slice(1, line.lastIndexOf(":"));
+    // 只访问归属于项目的本机监听地址，不探测局域网。
+    if (!["*", "0.0.0.0", "127.0.0.1", "[::]", "[::1]"].includes(address)) continue;
+    const host = address === "[::1]" ? "[::1]" : "127.0.0.1";
+    entries.set(`${pid}:${port}`, { pid, command, port, url: `http://${host}:${port}/` });
+  }
+  return [...entries.values()];
+}
+
+export async function probePage(url, { fetchImpl = fetch, timeoutMs = 1400 } = {}) {
+  const response = await fetchImpl(url, { signal: AbortSignal.timeout(timeoutMs), redirect: "manual", headers: { Accept: "text/html" } });
+  // 自动发现不跟随跳转，以免一次本机检查变成任意网络访问。
+  if (!response.ok || !/text\/html|application\/xhtml\+xml/i.test(response.headers.get("content-type") ?? "")) { await response.body?.cancel(); return null; }
+  const reader = response.body?.getReader();
+  if (!reader) return null;
+  let text = "", bytes = 0;
+  const decoder = new TextDecoder();
+  try {
+    while (bytes < 65536) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      bytes += value.byteLength;
+      text += decoder.decode(value.slice(0, Math.max(0, 65536 - (bytes - value.byteLength))), { stream: true });
+    }
+  } finally { await reader.cancel(); }
+  if (!/<(?:!doctype\s+html|html|head|body|title|div|main)\b/i.test(text)) return null;
+  const title = text.match(/<title[^>]*>([\s\S]*?)<\/title>/i)?.[1]?.replace(/\s+/g, " ").replace(/&amp;/g, "&").replace(/&lt;/g, "<").replace(/&gt;/g, ">")?.trim().slice(0, 160);
+  return { title: title || new URL(url).host };
+}
+
+export async function localListeners({ platform = process.platform, runImpl = run } = {}) {
+  if (platform === "win32") {
+    // Windows 不公开进程 cwd；仅采用命令行中可确认的项目绝对路径。
+    const script = '$p=@{}; Get-CimInstance Win32_Process | ForEach-Object {$p[[int]$_.ProcessId]=$_.CommandLine}; @(Get-NetTCPConnection -State Listen | ForEach-Object { [pscustomobject]@{pid=$_.OwningProcess;address=$_.LocalAddress;port=$_.LocalPort;command=$p[[int]$_.OwningProcess]} }) | ConvertTo-Json -Compress';
+    const { stdout } = await runImpl("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", script], { timeout: 4000, maxBuffer: 2 * 1024 * 1024 });
+    return [].concat(JSON.parse(stdout || "[]")).filter(e => ["::", "::1", "0.0.0.0", "127.0.0.1"].includes(e.address)).map(e => ({ ...e, url: `http://${e.address === "::1" ? "[::1]" : "127.0.0.1"}:${e.port}/` }));
+  }
+  let stdout;
+  try { ({ stdout } = await runImpl("lsof", ["-nP", "-iTCP", "-sTCP:LISTEN", "-Fpcn"], { timeout: 4000, maxBuffer: 2 * 1024 * 1024 })); }
+  catch (error) { if (error.code === 1 && !error.stdout) return []; throw error; }
+  const entries = parseListeners(stdout);
+  if (!entries.length) return [];
+  const pids = [...new Set(entries.map(e => e.pid))].join(",");
+  const [result, processInfo] = await Promise.all([
+    runImpl("lsof", ["-a", "-p", pids, "-d", "cwd", "-Fn"], { timeout: 4000, maxBuffer: 2 * 1024 * 1024 }),
+    runImpl("ps", ["-ww", "-p", pids, "-o", "pid=,args="], { timeout: 2000, maxBuffer: 2 * 1024 * 1024 }),
+  ].map(task => task.catch(error => {
+    // 服务可在两次枚举之间退出，保留仍存活进程的输出。
+    if (error.code === 1) return { stdout: error.stdout || "" };
+    throw error;
+  })));
+  const commands = new Map(processInfo.stdout.split("\n").flatMap(line => {
+    const match = line.trim().match(/^(\d+)\s+(.+)$/);
+    return match ? [[Number(match[1]), match[2]]] : [];
+  }));
+  let pid; const cwd = new Map();
+  for (const line of result.stdout.split("\n")) { if (line[0] === "p") pid = Number(line.slice(1)); if (line[0] === "n") cwd.set(pid, line.slice(1)); }
+  return entries.map(e => ({ ...e, command: commands.get(e.pid) || "", cwd: cwd.get(e.pid) }));
+}

package/features/sites/src/backend/project-sites.mjs

@@ -0,0 +1,34 @@
+import { readFile, readdir, realpath } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import path from "node:path";
+
+const ignored = new Set(["node_modules", "dist", "build", "out", "vendor", "target", "coverage"]);
+export const entryKey = (projectId, directory) => createHash("sha256").update(`${projectId}\0${directory}`).digest("hex");
+export async function findProjectSites(projects) {
+  const found = [], visited = new Set();
+  let remaining = 4000;
+  async function walk(directory, project, depth) {
+    if (--remaining < 0 || depth > 4) return;
+    const canonical = await realpath(directory).catch(() => null);
+    if (!canonical || visited.has(canonical)) return; visited.add(canonical);
+    let entries; try { entries = await readdir(canonical, { withFileTypes: true }); } catch { return; }
+    let pkg;
+    if (entries.some(e => e.name === "package.json")) { try { pkg = JSON.parse(await readFile(path.join(canonical, "package.json"), "utf8")); } catch {} }
+    const scripts = Object.entries(pkg?.scripts || {});
+    const selected = ["dev", "start", "serve"].flatMap(name => scripts.filter(([key]) => key === name))
+      .map(([script, command]) => ({ script, command, framework: String(command).match(/^(vite|next\s+dev|astro\s+dev)(?:\s|$)/)?.[1]?.split(" ")[0] }))
+      .find(s => s.framework && !/[;&|`$<>\n]/.test(s.command));
+    // 不把只有 dev/watch 名称的编译器、MCP 或模拟器当作网站。
+    const staticEntry = !pkg && entries.some(e => e.isFile() && e.name === "index.html");
+    if (selected || staticEntry) {
+      let title = pkg?.name || path.basename(canonical);
+      if (staticEntry) { const html = await readFile(path.join(canonical, "index.html"), "utf8").catch(() => ""); title = html.match(/<title[^>]*>([^<]*)<\/title>/i)?.[1]?.trim() || title; }
+      found.push({ entryId: entryKey(project.id, canonical), directory: canonical, projectId: project.id, projectName: project.name, title, framework: selected?.framework || "static", script: selected?.script || null, command: selected?.command || null, url: null, status: "stopped" });
+    }
+    for (const entry of entries) if (entry.isDirectory() && !entry.name.startsWith(".") && !ignored.has(entry.name)) await walk(path.join(canonical, entry.name), project, depth + 1);
+  }
+  // 深层项目先归属，避免被父项目重复收录。
+  const roots = projects.flatMap(p => p.rootPaths.map(root => ({ root, project: p }))).sort((a,b) => b.root.length - a.root.length);
+  for (const { root, project } of roots) await walk(root, project, 0);
+  return found;
+}

package/features/sites/src/backend/site-launcher.mjs

@@ -0,0 +1,54 @@
+import { spawn } from "node:child_process";
+import { createServer } from "node:http";
+import { readFile, realpath } from "node:fs/promises";
+import { createRequire } from "node:module";
+import path from "node:path";
+
+export class SiteLauncher {
+  constructor(probe) { this.probe = probe; this.running = new Map(); this.pending = new Map(); }
+  async start(entry) {
+    if (this.pending.has(entry.entryId)) return this.pending.get(entry.entryId);
+    const task = this.launch(entry).finally(() => this.pending.delete(entry.entryId)); this.pending.set(entry.entryId, task); return task;
+  }
+  async launch(entry) {
+    const existing = this.running.get(entry.entryId);
+    if (existing) { try { if (await this.probe(existing.url)) return existing.url; } catch {} existing.stop(); this.running.delete(entry.entryId); }
+    if (entry.framework === "static") {
+      const root = await realpath(entry.directory);
+      const types = { ".html":"text/html; charset=utf-8", ".js":"text/javascript", ".mjs":"text/javascript", ".css":"text/css", ".json":"application/json", ".svg":"image/svg+xml", ".png":"image/png", ".jpg":"image/jpeg", ".webp":"image/webp", ".woff2":"font/woff2" };
+      const server = createServer(async (req,res) => {
+        if (!["GET","HEAD"].includes(req.method)) { res.writeHead(405); res.end(); return; }
+        try {
+          const pathname = decodeURIComponent(new URL(req.url,"http://localhost").pathname);
+          if (pathname.split("/").some(p => p.startsWith("."))) throw Error();
+          const file = await realpath(path.join(root, pathname.endsWith("/") ? pathname + "index.html" : pathname));
+          const relative = path.relative(root,file); if (relative.startsWith("..") || path.isAbsolute(relative)) throw Error();
+          const bytes = await readFile(file); res.setHeader("Content-Type",types[path.extname(file)] || "application/octet-stream");res.end(req.method === "HEAD" ? undefined : bytes);
+        } catch { res.writeHead(404);res.end(); }
+      });
+      await new Promise((resolve,reject) => { server.once("error",reject);server.listen(0,"127.0.0.1",resolve); });
+      const url = `http://127.0.0.1:${server.address().port}/`; this.running.set(entry.entryId,{url,stop:()=>server.close()}); return url;
+    }
+    if (!["vite","next","astro"].includes(entry.framework)) throw Error("No supported start command was found for this site.");
+    // 只使用已安装的框架，不安装依赖、不运行任意 package 脚本。
+    const require = createRequire(path.join(entry.directory,"package.json"));
+    let packageFile; try { packageFile = require.resolve(`${entry.framework}/package.json`); } catch { throw Error("Project dependencies are not installed. Install them in the project first."); }
+    const pkg = JSON.parse(await readFile(packageFile,"utf8")); const relativeBin = typeof pkg.bin === "string" ? pkg.bin : pkg.bin?.[entry.framework];
+    if (!relativeBin) throw Error("Framework executable is unavailable.");
+    const reserve = createServer(); await new Promise(r=>reserve.listen(0,"127.0.0.1",r));const port=reserve.address().port;await new Promise(r=>reserve.close(r));
+    const args = entry.framework === "next" ? ["dev","--hostname","127.0.0.1","--port",String(port)] : [...(entry.framework === "astro" ? ["dev"] : []),"--host","127.0.0.1","--port",String(port),...(entry.framework === "vite" ? ["--strictPort"] : [])];
+    // 有自定义参数的配方不能静默丢弃，交由项目维护者整理后再启动。
+    if (!/^(vite|next\s+dev|astro\s+dev)(?:\s+--(?:host|hostname|port)\s+[\w.:-]+|\s+--(?:turbopack|strictPort))*\s*$/.test(entry.command || "")) throw Error("This site has a custom start command. Start it in the project first.");
+    if (/--turbopack\b/.test(entry.command)) args.push("--turbopack");
+    const child=spawn(process.execPath,[path.resolve(path.dirname(packageFile),relativeBin),...args],{cwd:entry.directory,stdio:["ignore","pipe","pipe"],env:process.env});
+    let failure; child.on("error",e=>{failure=e;}); child.stdout.resume();child.stderr.resume();
+    const url=`http://127.0.0.1:${port}/`; const record={url,stop:()=>child.kill("SIGTERM")};this.running.set(entry.entryId,record);
+    child.once("exit",()=>{if(this.running.get(entry.entryId)===record)this.running.delete(entry.entryId);});
+    try {
+      const deadline=Date.now()+25000;
+      while(Date.now()<deadline){if(failure)throw failure;if(child.exitCode!==null)throw Error("Website process exited before becoming ready.");try{if(await this.probe(url,{timeoutMs:1000}))return url;}catch{}await new Promise(r=>setTimeout(r,400));}
+      throw Error("Website did not become ready within 25 seconds.");
+    } catch(e){record.stop();this.running.delete(entry.entryId);throw e;}
+  }
+  stop(){for(const entry of this.running.values())entry.stop();this.running.clear();}
+}

package/features/sites/src/backend/sites-preview.mjs

@@ -0,0 +1,53 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { createHash } from "node:crypto";
+import { access, chmod, mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+const run = promisify(execFile);
+export async function captureSitePreview(url) {
+  const candidates = process.platform === "darwin" ? ["/Applications/Google Chrome.app/Contents/MacOS/Google Chrome", "/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge"] : process.platform === "win32" ? [process.env.PROGRAMFILES, process.env["PROGRAMFILES(X86)"], process.env.LOCALAPPDATA].filter(Boolean).flatMap(root => [path.join(root, "Google/Chrome/Application/chrome.exe"), path.join(root, "Microsoft/Edge/Application/msedge.exe")]) : ["/usr/bin/google-chrome", "/usr/bin/chromium", "/usr/bin/chromium-browser"];
+  let browser;
+  for (const candidate of candidates) { try { await access(candidate); browser = candidate; break; } catch {} }
+  if (!browser) throw new Error("A Chromium browser is required for site previews.");
+  const temporary = await mkdtemp(path.join(os.tmpdir(), "minecodex-site-preview-"));
+  const screenshot = path.join(temporary, "preview.png");
+  try {
+    // 独立无界面 profile，不使用用户浏览器的登录状态或已有窗口。
+    const { stdout } = await run(browser, ["--headless=new", "--dump-dom", "--no-first-run", "--no-default-browser-check", "--disable-background-networking", "--disable-extensions", "--hide-scrollbars", "--mute-audio", `--user-data-dir=${path.join(temporary, "profile")}`, "--window-size=960,600", "--timeout=8000", "--virtual-time-budget=1200", `--screenshot=${screenshot}`, url], { timeout: 12000, maxBuffer: 1024 * 1024 });
+    if (/chrome-error:\/\/chromewebdata|id="main-frame-error"/.test(stdout)) throw new Error("Site could not be loaded.");
+    const bytes = await readFile(screenshot);
+    if (bytes.length > 2 * 1024 * 1024 || bytes.subarray(0, 8).toString("hex") !== "89504e470d0a1a0a") throw new Error("Invalid site preview.");
+    return bytes;
+  } finally { await rm(temporary, { recursive: true, force: true, maxRetries: 3 }); }
+}
+
+export class SitePreviews {
+  constructor(directory, capture = captureSitePreview) { this.directory = directory; this.capture = capture; this.pending = new Map(); this.results = new Map(); this.queue = Promise.resolve(); }
+  async cached(url) {
+    const file = path.join(this.directory, createHash("sha256").update(url).digest("hex") + ".png");
+    try { return { image: `data:image/png;base64,${(await readFile(file)).toString("base64")}` }; } catch(e) { if(e.code === "ENOENT")return {image:null};throw e; }
+  }
+  request(url) {
+    const previous = this.results.get(url);
+    if (previous && (previous.image || Date.now() - previous.finishedAt < 60000)) return previous;
+    if (!this.pending.has(url)) {
+      this.get(url).then(result => this.results.set(url, result), () => this.results.set(url, { image: null, finishedAt: Date.now() }));
+    }
+    return { pending: true };
+  }
+  async get(url) {
+    if (this.pending.has(url)) return this.pending.get(url);
+    const file = path.join(this.directory, createHash("sha256").update(url).digest("hex") + ".png");
+    const task = (async () => {
+      try { return await readFile(file); } catch (e) { if (e.code !== "ENOENT") throw e; }
+      const capture = this.queue.catch(() => {}).then(async () => {
+        const bytes = await this.capture(url); await mkdir(this.directory, { recursive: true, mode: 0o700 });
+        await writeFile(file, bytes, { mode: 0o600 }); await chmod(file, 0o600); return bytes;
+      });
+      this.queue = capture; return capture;
+    })().then(bytes => ({ image: `data:image/png;base64,${bytes.toString("base64")}` })).finally(() => this.pending.delete(url));
+    this.pending.set(url, task); return task;
+  }
+}

package/features/sites/src/backend/sites-service.mjs

@@ -0,0 +1,162 @@
+import { normalizeSite, projectForDirectory, isLocalAddress } from "../domain/site.mjs";
+import { localListeners, probePage } from "./discovery.mjs";
+import { randomUUID } from "node:crypto";
+import { mkdir, readFile, rename, writeFile, realpath } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { CodexCatalog } from "../adapters/codex/catalog.mjs";
+
+import { findProjectSites, entryKey } from "./project-sites.mjs";
+import { SiteLauncher } from "./site-launcher.mjs";
+import { SitePreviews } from "./sites-preview.mjs";
+
+const loops = new Set(["localhost", "127.0.0.1", "[::1]"]);
+export class SitesService {
+  constructor({ dataDir, codexHome = process.env.CODEX_HOME || path.join(os.homedir(), ".codex"), listeners = localListeners, probe = probePage, catalog = new CodexCatalog(codexHome) } = {}) {
+    const support = process.platform === "win32" ? path.join(process.env.APPDATA || os.homedir(), "MineCodex") : path.join(os.homedir(), "Library", "Application Support", "MineCodex");
+    this.file = path.join(dataDir || process.env.MINECODEX_SITES_DATA_DIR || path.join(support, "sites"), "sites.json");
+    this.previews = new SitePreviews(path.join(path.dirname(this.file), "previews")); this.discoveredUrls = new Set(); this.entries = new Map(); this.discoveryQueue = Promise.resolve();
+    this.launcher = new SiteLauncher(probe); this.launchJobs = new Map();
+    this.catalogReader = catalog; this.listeners = listeners; this.probe = probe; this.queue = Promise.resolve();
+  }
+  catalog() { return this.catalogReader.snapshot(); }
+  async read() {
+    try { const data = JSON.parse(await readFile(this.file, "utf8")); if (data.schemaVersion !== 1 || !Array.isArray(data.sites)) throw new Error("Unsupported sites data."); return data.sites.map(site => site.url ? { ...site, hosting: isLocalAddress(new URL(site.url).hostname) ? "local" : "self-hosted" } : site); }
+    catch (error) { if (error.code === "ENOENT") return []; throw error; }
+  }
+  async mutate(operation) {
+    const task = this.queue.catch(() => {}).then(async () => {
+      const sites = await this.read(); const result = operation(sites);
+      await mkdir(path.dirname(this.file), { recursive: true, mode: 0o700 });
+      const temporary = `${this.file}.${randomUUID()}.tmp`;
+      await writeFile(temporary, JSON.stringify({ schemaVersion: 1, sites }, null, 2) + "\n", { mode: 0o600 });
+      await rename(temporary, this.file); return result;
+    });
+    this.queue = task; return task;
+  }
+  discover() {
+    const task = this.discoveryQueue.catch(() => {}).then(() => this.scan()); this.discoveryQueue = task; return task;
+  }
+  async scan() {
+    const { projects } = await this.catalog();
+    const canonical = await Promise.all(projects.map(async p => ({ ...p, rootPaths: await Promise.all(p.rootPaths.map(r => realpath(r).catch(() => r))) })));
+    const definitions = await findProjectSites(canonical);
+    const listeners = await this.listeners(); const deadline = Date.now() + 7500; const candidates = []; const seen = new Set();
+    const attributed = await Promise.all(listeners.map(async e => {
+      const cwd = e.cwd ? await realpath(e.cwd).catch(() => e.cwd) : null;
+      const project = projectForDirectory(canonical, cwd) || (process.platform === "win32" ? canonical.filter(p => p.rootPaths.some(r => String(e.command).toLowerCase().includes((r + path.sep).toLowerCase()))).sort((a,b) => b.rootPaths[0].length - a.rootPaths[0].length)[0] : null);
+      return { ...e, project };
+    }));
+    // 模拟器桥接首页也会执行 simctl；须在 HTTP 探测前排除，避免安装授权弹窗。
+    // 无法读取完整命令时不主动探测，仍允许用户手动添加网址。
+    const pending = attributed.filter(e => e.project && e.command && !/(?:^|[\s/\\])(?:serve-sim|swiftui-preview-browser)(?:[.\s/\\]|$)/i.test(e.command));
+    await Promise.all(Array.from({ length: Math.min(6, pending.length) }, async () => {
+      while (pending.length && Date.now() < deadline) {
+        const entry = pending.shift();
+        if ([...this.launcher.running.values()].some(r => r.url === entry.url)) continue;
+        if (seen.has(entry.url)) continue; seen.add(entry.url);
+        try { const page = await this.probe(entry.url, { timeoutMs: Math.min(1400, Math.max(1, deadline - Date.now())) }); if (page) candidates.push({ title: page.title, url: entry.url, projectId: entry.project.id, projectName: entry.project.name, directory: entry.cwd, status: "running" }); } catch { /* 未就绪或非 HTTP 服务不列为网页。 */ }
+      }
+    }));
+    const historyFile = path.join(path.dirname(this.file), "project-history.json");
+    let history = {};
+    try { history = JSON.parse(await readFile(historyFile, "utf8")); } catch (e) { if (e.code !== "ENOENT") throw e; }
+    for (const candidate of candidates) {
+      const definition = definitions.filter(d => d.projectId === candidate.projectId && candidate.directory && projectForDirectory([{ rootPaths: [d.directory] }], candidate.directory)).sort((a,b) => b.directory.length - a.directory.length)[0];
+      candidate.entryId = definition?.entryId || entryKey(candidate.projectId, candidate.directory || candidate.url);
+      if (definition) { Object.assign(candidate, { framework: definition.framework, script: definition.script, command: definition.command }); definitions.splice(definitions.indexOf(definition), 1); }
+      history[candidate.entryId] = { ...history[candidate.entryId], projectId:candidate.projectId,projectName:candidate.projectName,directory:candidate.directory, lastSeenAt: Date.now(), url: candidate.url, title: candidate.title };
+    }
+    for (const [id, previous] of Object.entries(history)) {
+      if (previous.directory && projectForDirectory(canonical.filter(p => p.id === previous.projectId), previous.directory) && !candidates.some(c => c.entryId === id) && !definitions.some(c => c.entryId === id)) definitions.push({ ...previous,entryId:id,status:"stopped" });
+    }
+    for (const definition of definitions) {
+      const running = this.launcher.running.get(definition.entryId);
+      candidates.push({ ...definition, ...history[definition.entryId], url: running?.url || history[definition.entryId]?.url || null, status: running ? "running" : "stopped" });
+    }
+    for (const candidate of candidates) Object.assign(candidate, { lastSeenAt: history[candidate.entryId]?.lastSeenAt, lastStartedAt: history[candidate.entryId]?.lastStartedAt });
+    await mkdir(path.dirname(this.file), { recursive: true, mode: 0o700 });
+    await writeFile(historyFile, JSON.stringify(history), { mode: 0o600 });
+    this.entries = new Map(candidates.map(c => [c.entryId, c])); this.scannedAt = Date.now();
+    this.discoveredUrls = new Set(candidates.filter(c => c.status === "running").map(c => c.url));
+    return { candidates: candidates.sort((a,b) => a.projectName.localeCompare(b.projectName) || (a.url || a.directory).localeCompare(b.url || b.directory)), scope: "local-projects" };
+  }
+  async action(payload = {}) {
+    if (payload.operation === "start") {
+      const site = (await this.read()).find(s => s.id === payload.id);
+      if (!site || site.origin.kind !== "project") throw new Error("Project site is unavailable.");
+      const job = this.launchJobs.get(site.id);
+      if (job) { if (job.pending) return job; this.launchJobs.delete(site.id); if (job.error) throw new Error(job.error); return job; }
+      await this.discover(); const entry = site.entryId ? this.entries.get(site.entryId) : [...this.entries.values()].find(e => e.url === site.url && e.projectId === site.origin.projectId);
+      if (!entry) throw new Error("Project website entry no longer exists.");
+      if (entry.status === "running") return { url: entry.url };
+      this.launchJobs.set(site.id, { pending: true });
+      this.launcher.start(entry).then(async url => {
+        const now = Date.now();
+        await this.mutate(sites => { const saved = sites.find(s => s.id === site.id); if (saved) Object.assign(saved, {entryId:entry.entryId,url,status:"running",lastStartedAt:now,lastSeenAt:now}); });
+        const historyFile = path.join(path.dirname(this.file), "project-history.json");
+        // 和扫描共用串行队列，避免运行记录被并发覆盖。
+        const update = this.discoveryQueue.catch(() => {}).then(async () => {
+          const history = JSON.parse(await readFile(historyFile,"utf8")); history[entry.entryId] = { ...history[entry.entryId],url,lastStartedAt:now,lastSeenAt:now,title:entry.title }; await writeFile(historyFile,JSON.stringify(history),{mode:0o600});
+        }); this.discoveryQueue = update; await update;
+        this.entries.set(entry.entryId,{...entry,url,status:"running",lastStartedAt:now,lastSeenAt:now});
+        this.launchJobs.set(site.id,{url});
+      }).catch(error => this.launchJobs.set(site.id,{error:error.message}));
+      return { pending:true };
+    }
+    if (payload.operation === "preview") {
+      const url = new URL(String(payload.url)).href;
+      if (!this.discoveredUrls.has(url) && !(payload.cachedOnly && [...this.entries.values()].some(e => e.url === url)) && !(await this.read()).some(s => s.url === url)) throw new Error("Site is not in the library or discovery results.");
+      // 手动收录也不能让截图重新触发模拟器工具链安装。
+      const parsed = new URL(url);
+      if (loops.has(parsed.hostname)) {
+        const listeners = await this.listeners();
+        if (listeners.some(e => new URL(e.url).port === parsed.port && /(?:serve-sim|swiftui-preview-browser)/i.test(e.command))) return { image: null };
+      }
+      return payload.cachedOnly ? this.previews.cached(url) : this.previews.request(url);
+    }
+    if (payload.operation === "list") {
+      if (!this.scannedAt || Date.now() - this.scannedAt > 10000) await this.discover();
+      return { sites: (await this.read()).map(site => {
+        const entry = site.entryId ? this.entries.get(site.entryId) : [...this.entries.values()].find(e => e.url && e.url === site.url && e.projectId === site.origin.projectId);
+        return entry ? { ...site,...entry } : site;
+      }), ...await this.catalog() };
+    }
+    if (payload.operation === "discover") return this.discover();
+    if (payload.operation === "save") {
+      let site;
+      if (payload.site?.entryId) {
+        const candidate = this.entries.get(payload.site.entryId);
+        if (!candidate) throw new Error("Project site is no longer available. Reopen Add site.");
+        site = { ...candidate, hosting: "local", origin: { kind: "project", projectId: candidate.projectId } };
+      } else site = normalizeSite(payload.site);
+      const catalog = await this.catalog();
+      if (site.origin.kind === "project" && !catalog.projects.some(p => p.id === site.origin.projectId)) throw new Error("Project is no longer available. Choose another source.");
+      if (site.origin.kind === "thread" && !catalog.threads.some(t => t.id === site.origin.threadId)) throw new Error("Projectless chat is no longer available. Choose another source.");
+      return this.mutate(sites => {
+        const index = payload.id ? sites.findIndex(s => s.id === payload.id) : -1;
+        if (payload.id && index < 0) throw new Error("Site no longer exists. Refresh the list.");
+        const duplicate = sites.find(s => s.id !== payload.id && (site.entryId ? s.entryId === site.entryId || (!!site.url && s.url === site.url) : s.url === site.url) && JSON.stringify(s.origin) === JSON.stringify(site.origin));
+        if (duplicate) {
+          if (payload.id) throw new Error("This URL and development source are already saved in another entry.");
+          return duplicate;
+        }
+        const record = { ...site, id: payload.id || randomUUID(), createdAt: index < 0 ? Date.now() : sites[index].createdAt, updatedAt: Date.now() };
+        if (index < 0) sites.unshift(record); else sites[index] = record;
+        return record;
+      });
+    }
+    if (payload.operation === "remove") return this.mutate(sites => { const i = sites.findIndex(s => s.id === payload.id); if (i >= 0) sites.splice(i, 1); return { removed: i >= 0 }; });
+    if (payload.operation === "resolve") {
+      let site = (await this.read()).find(s => s.id === payload.id);
+      if (!site) throw new Error("Site no longer exists.");
+      const catalog = await this.catalog();
+      if (site.origin.kind === "project" && !catalog.projects.some(p => p.id === site.origin.projectId)) return { site, missing: "project" };
+      if (site.origin.kind === "thread" && !catalog.threads.some(t => t.id === site.origin.threadId)) return { site, missing: "thread" };
+      if (site.entryId) { await this.discover(); const entry = site.entryId ? this.entries.get(site.entryId) : [...this.entries.values()].find(e => e.url === site.url && e.projectId === site.origin.projectId); if (entry) site = { ...site, ...entry }; }
+      const project = site.origin.kind === "project" ? catalog.projects.find(p => p.id === site.origin.projectId) : null;
+      return { site, ...(project ? { cwd: site.directory || project.rootPaths[0] } : {}) };
+    }
+    throw new Error("Unknown Sites operation.");
+  }
+}

package/features/sites/src/domain/site.mjs

@@ -0,0 +1,40 @@
+import path from "node:path";
+
+export function isLocalAddress(hostname) {
+  const host = hostname.toLowerCase().replace(/^\[|\]$/g, "");
+  if (host === "localhost" || host.endsWith(".localhost") || host.endsWith(".local") || host === "::1") return true;
+  const parts = host.split(".");
+  if (parts.length === 4 && parts.every(p => /^\d+$/.test(p) && Number(p) <= 255)) {
+    const [a, b] = parts.map(Number);
+    return a === 127 || a === 10 || a === 192 && b === 168 || a === 172 && b >= 16 && b <= 31 || a === 169 && b === 254;
+  }
+  // URL 已规范化 IPv6；识别私有、链路本地及 IPv4 映射地址。
+  if (/^(fc|fd)[0-9a-f]{2}:|^fe[89ab][0-9a-f]:/.test(host)) return true;
+  const mapped = host.match(/^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/);
+  if (mapped) {
+    const high = parseInt(mapped[1], 16), low = parseInt(mapped[2], 16);
+    return isLocalAddress([high >> 8, high & 255, low >> 8, low & 255].join("."));
+  }
+  return false;
+}
+export function normalizeSite(input) {
+  const url = new URL(String(input.url ?? "").trim());
+  if (!["http:", "https:"].includes(url.protocol) || url.username || url.password) throw new Error("Use an HTTP or HTTPS URL without embedded credentials.");
+  const title = String(input.title ?? "").trim().slice(0, 160) || url.hostname;
+  const origin = input.origin;
+  if (!origin || !["project", "thread", "external"].includes(origin.kind)) throw new Error("Choose the site's development source.");
+  const cleanOrigin = { kind: origin.kind };
+  if (origin.kind !== "external") {
+    const field = origin.kind === "project" ? "projectId" : "threadId";
+    if (!/^[a-zA-Z0-9_-]{1,128}$/.test(origin[field] ?? "")) throw new Error("Choose a valid development source.");
+    cleanOrigin[field] = origin[field];
+  }
+  return { title, url: url.href, hosting: isLocalAddress(url.hostname) ? "local" : "self-hosted", origin: cleanOrigin };
+}
+
+export function projectForDirectory(projects, cwd, pathApi = path) {
+  if (!cwd) return null;
+  return projects.flatMap(project => project.rootPaths.map(root => ({ project, root })))
+    .filter(({ root }) => { const relative = pathApi.relative(root, cwd); return relative === "" || (!relative.startsWith(`..${pathApi.sep}`) && relative !== ".." && !pathApi.isAbsolute(relative)); })
+    .sort((a, b) => b.root.length - a.root.length)[0]?.project ?? null;
+}