@xiaobuyu/nodesign 0.0.1

package/server/engine/runs/turn-relay.js

@@ -0,0 +1,217 @@
+/**
+ * server/engine/runs/turn-relay.js — run 记录 ↔ 用户消息的配对（2026-08-20 从
+ * active-runs.js 拆出，行数棘轮）。
+ *
+ * 管的只有一件事：turn.js 为每条用户消息建的 run 行，怎样在 streamInput 模式下跟
+ * SDK 流里的 turn 边界对上号。会话记录（currentRunId / pendingRunIds / runIdByUuid）
+ * 仍归 active-runs.js 所有（registerQuerySession 初始化、unregister 清理），这里只读写
+ * 它的这几个字段 —— 所以本模块 import active-runs，反向不 import（无环）。
+ *
+ * 下面 claimRunByUuid 上方的长注释是整套机制与探针证据，改任何一处前先读它。
+ */
+
+import { randomUUID } from 'node:crypto';
+import { getQuerySession } from './active-runs.js';
+import { markRunStarted, markRunSucceeded, mergeRunMetadata } from './store.js';
+
+/**
+ * 推一条 user message 到 session 的 input queue + 标记当前 turn runId。
+ * runSession for-await-of 那头会拉到这条 message → SDK 处理 → 出 result message
+ * → runSession 用 currentRunId 做 markRunSucceeded / emit run.done。
+ *
+ * @param {string} sessionId
+ * @param {string} runId  - 当前 turn 的 run record id（前端 UI 跟踪用）
+ * @param {object} sdkUserMessage  - { type:'user', message:{role,content}, parent_tool_use_id }
+ * @returns {boolean} true=成功 push
+ */
+export function pushUserMessage(sessionId, runId, sdkUserMessage) {
+  const rec = getQuerySession(sessionId);
+  if (!rec) return false;
+  if (rec.abortController.signal.aborted) return false;
+  // runId 关联（2026-08-20 重做，背景见文件尾「run 记账错位案」）：
+  //   - 出站消息盖 uuid 章。SDKUserMessage 的 uuid 字段是 SDK 类型里的合法可选项，
+  //     CLI 回显时原样带回，是 runId ↔ 消息唯一可靠的配对键。
+  //   - session idle 且没人排队 → 直接设 currentRunId，SDK 拉到消息即处理。
+  //   - 否则一律**排队**，不抢占 currentRunId。两种情形都排：① turn 进行中
+  //     （老逻辑立即覆盖会让 session-loop 的 turn 边界检测把还在跑的 turn1 误判成
+  //     TURN_LEAK 标 failed，turn2 又没有 run.start/run.done —— 前端表现"stop 按钮
+  //     消失但字还在冒"）；② turn 刚结束、前面还有排队的消息没被 CLI 回显
+  //     （此刻 currentRunId 是空的，但 CLI 队列是 FIFO，它下一条要处理的是前面那条
+  //     —— 这条若直接上位，回显到了就会把前面那条误判成"并进了这条"）。
+  //   - 排队的 runId **不再靠 finishTurn 计数晋升**，由它自己的回显来认领
+  //     （claimRunByUuid）。
+  if (!sdkUserMessage.uuid) sdkUserMessage.uuid = randomUUID();
+  rec.runIdByUuid.set(sdkUserMessage.uuid, runId);
+  if (!rec.currentRunId && rec.pendingRunIds.length === 0) {
+    rec.currentRunId = runId;
+  } else {
+    rec.pendingRunIds.push(runId);
+  }
+  rec.lastActivityAt = Date.now();
+  try {
+    rec.inputQueue.push(sdkUserMessage);
+    return true;
+  } catch (err) {
+    console.warn(`[active-runs] pushUserMessage failed for ${sessionId}: ${err.message}`);
+    return false;
+  }
+}
+
+/**
+ * ## run 记账错位案（2026-08-19 定案，08-20 修）
+ *
+ * 老接力：`result` 到 → finishTurn(当前) → promoteNextPendingRunId 晋升队头。
+ * 前提是「一条用户消息严格对应一个 result」。但 CLI 在 streamInput 模式下会把
+ * turn 进行中追加的消息**并进正在跑的这一轮**（默认 priority 'next'；探针
+ * `server/_probe-turn-merge.mjs` 实测：一个 result、num_turns=3、两条都答了）。
+ * 发生一次，链就永久错一格且永不自愈 —— 之后每个 result 关的都是上一条的 run，
+ * runs 表里每条 started_at/finished_at 其实是下一轮的执行窗口（"排队 7-12 分钟"
+ * 的假象）；前端等的 run.start 迟一轮才发/最后一条永不发（追加后丢状态）。
+ *
+ * 新锚：CLI 开 `--replay-user-messages` 后回显每条用户消息，**回显时刻 = 那条
+ * 消息真正被并进对话的时刻**（探针实测：push 后 2.5s，回显在 12s 后 tool_result
+ * 回来、下一次模型调用之前到；不是读到 stdin 就回）。于是：
+ *   - 回显到、此刻没有 turn 在跑 → 这条 run 的 turn 开始了（晋升）
+ *   - 回显到、turn 进行中 → 这条被并进了当前轮（就地关账，metadata 记 mergedIntoRunId）
+ * 并轮语义**保留不改**（`priority:'later'` 可让 CLI 排到下一轮不并，探针验过，
+ * 但"追加立刻被看见"是更好的体验，跟 Claude Code 自己一致）。
+ */
+
+/**
+ * 推一条**不认领 run** 的用户消息（08-21 晚，半截续接用）。
+ *
+ * 跟 pushUserMessage 的区别：不盖 uuid 章、不进 runIdByUuid、不碰 currentRunId/pendingRunIds。
+ * 因为它不是用户发的新一轮，而是**当前这一轮的延续** —— 半截被掐了，我们替 agent 说一句
+ * "接着说"。调用方（session-loop）此刻还没 finishTurn，currentRunId 仍是这一轮，
+ * 于是 CLI 回显它时 claimRunByUuid 返 null（不是我们盖章的消息，照旧忽略），
+ * turn 边界检测也不动（cid 没变）—— 整段续接算在同一个 run 里，token 照常累加。
+ *
+ * ⚠️ 别拿 pushUserMessage 干这件事：它会把 runId 塞进 pendingRunIds，而这个 runId
+ * 已经是 currentRunId，回显时走 'current' 分支不出队 —— 队列里那条永远清不掉，
+ * 前端"已排队 1 条"会一直亮着，还会误触发回显锚缺席的 FIFO 兜底。
+ *
+ * @returns {boolean} true = 推进队列了
+ */
+export function pushUnclaimedMessage(sessionId, sdkUserMessage) {
+  const rec = getQuerySession(sessionId);
+  if (!rec) return false;
+  if (rec.abortController.signal.aborted) return false;
+  rec.lastActivityAt = Date.now();
+  try {
+    rec.inputQueue.push(sdkUserMessage);
+    return true;
+  } catch (err) {
+    console.warn(`[turn-relay] pushUnclaimedMessage failed for ${sessionId}: ${err.message}`);
+    return false;
+  }
+}
+
+/**
+ * 回显到了一条带 uuid 的用户消息 → 认领它对应的 run。
+ *
+ * @param {string} sessionId
+ * @param {string} uuid  回显消息的 uuid
+ * @returns {null | { runId: string, outcome: 'current' | 'promoted' | 'merged' | 'unknown', intoRunId?: string }}
+ *   null = 不是我们盖过章的消息（首条经 initialRunId 走、或 CLI 合成的）；
+ *   current = 它本来就是当前 run（idle 直设 / FIFO 兜底已晋升）；
+ *   promoted = 从排队晋升为当前 run（调用方接着 startTurn）；
+ *   merged = 并进了正在跑的 intoRunId（调用方就地关账）；
+ *   unknown = 盖过章但已不在排队里（理论上不该发生，留给日志）。
+ */
+export function claimRunByUuid(sessionId, uuid) {
+  const rec = getQuerySession(sessionId);
+  if (!rec || !uuid) return null;
+  const runId = rec.runIdByUuid.get(uuid);
+  if (!runId) return null;
+  rec.runIdByUuid.delete(uuid);
+  if (runId === rec.currentRunId) return { runId, outcome: 'current' };
+  const idx = rec.pendingRunIds.indexOf(runId);
+  if (idx < 0) return { runId, outcome: 'unknown' };
+  rec.pendingRunIds.splice(idx, 1);
+  if (!rec.currentRunId) {
+    rec.currentRunId = runId;
+    return { runId, outcome: 'promoted' };
+  }
+  return { runId, outcome: 'merged', intoRunId: rec.currentRunId };
+}
+
+/**
+ * turn 结束：让出 currentRunId（session-loop finishTurn 调）。
+ * 排队的下一条**不在这里晋升** —— 等它自己的回显（claimRunByUuid）。
+ *
+ * @param {string} sessionId
+ */
+export function releaseCurrentTurnRunId(sessionId) {
+  const rec = getQuerySession(sessionId);
+  if (!rec) return;
+  rec.currentRunId = null;
+}
+
+/**
+ * FIFO 兜底：回显锚缺席时（CLI 没开 replay / 版本行为变了）按队头晋升，
+ * 否则排队的 run 永远没人认领、整轮事件全丢。session-loop 只在"没 turn 在跑、
+ * 有人排队、模型却已经在说话"时调它，并打 warn —— 正常运行下不该走到。
+ *
+ * @param {string} sessionId
+ * @returns {string|null} 晋升后的 currentRunId
+ */
+export function promoteNextPendingRunId(sessionId) {
+  const rec = getQuerySession(sessionId);
+  if (!rec) return null;
+  if (rec.currentRunId) return rec.currentRunId;
+  rec.currentRunId = rec.pendingRunIds.shift() || null;
+  return rec.currentRunId;
+}
+
+/**
+ * @param {string} sessionId
+ * @returns {number} 排队中（已 push、还没被 CLI 回显认领）的 run 数
+ */
+export function getPendingRunCount(sessionId) {
+  return getQuerySession(sessionId)?.pendingRunIds.length || 0;
+}
+
+/**
+ * 取 inputQueue 当前积压深度（push 但尚未被 SDK pull 的 message 数）。
+ * 给前端显示"已排队 N 条"用。
+ *
+ * 0 = agent idle 立即处理；>0 = agent 还在忙，下一条要排队
+ *
+ * @param {string} sessionId
+ * @returns {number}
+ */
+export function getQueueDepth(sessionId) {
+  // 2026-08-20 改口径：老值是 inputQueue.size，但 SDK 一有消息就拉走（它自己往 CLI
+  // stdin 写，排队发生在 CLI 进程里），这个数基本恒为 0 —— "已排队 N 条"从没亮过。
+  // 现在 N = 已 push、还没被 CLI 回显认领的 run 数，这才是用户那句"agent 还没接上
+  // 我这条"的真相。
+  return getPendingRunCount(sessionId);
+}
+
+/**
+ * 并轮关账（session-loop 的回显锚在 outcome==='merged' 时调）。
+ * 回显到了一条排队消息、而 turn 正在跑 = CLI 把它并进了当前轮。它的 run 行不能
+ * 停在 pending（那就是老病：runs 表里"排队 N 分钟"的假象），也不能等一个永远不来
+ * 的 result。就地 running→succeeded，metadata 记它并进了谁；token/费用全记在承载它
+ * 的那一轮（SDK 的 result 本来就只给一份）。run.merged 事件给前端/审计看，前端
+ * 现在不消费（追加那条从没被认领过 runId，不需要清状态）。
+ */
+export function closeMergedRun({ runId, intoRunId, sessionId, sdkSessionId, eventBus }) {
+  try { markRunStarted(runId); } catch { /* 不该已 running；兜底继续关 */ }
+  try {
+    mergeRunMetadata(runId, { mergedIntoRunId: intoRunId, sdkSessionId });
+    markRunSucceeded(runId, {});
+  } catch (err) {
+    console.warn(`[turn-relay] sid=${sessionId.slice(0, 8)} close merged run=${runId} failed: ${err.message}`);
+  }
+  console.info(`[turn-relay] sid=${sessionId.slice(0, 8)} run=${runId} merged into running turn run=${intoRunId}`);
+  eventBus.publish({ type: 'run.merged', sessionId, runId, intoRunId, ts: new Date().toISOString() });
+}
+
+/**
+ * 广播"已排队 N 条"（N = 还没被 CLI 回显认领的 run 数，见 getQueueDepth）。
+ * 认领一条广播一次让前端递减；turn 处理完也广播。
+ */
+export function publishQueueDepth(eventBus, sessionId) {
+  eventBus.publish({ type: 'run.queue.depth', sessionId, depth: getQueueDepth(sessionId), ts: new Date().toISOString() });
+}

package/server/engine/runtime/workspace.js

@@ -0,0 +1,164 @@
+/**
+ * engine/runtime/workspace.js — 每个 run 一个沙盒目录
+ *
+ * 设计要点：
+ *   - 每个 run 独占 `<WORKSPACE_DIR>/<runId>/workspace/`
+ *   - 所有 tool（read_file / write_file / list_dir）必须经 safeResolve 校验路径，
+ *     绝不能让 agent 写到 workspace 之外（包括 `..` 越界、绝对路径、symlink 跳出）
+ *   - 不放敏感数据：env、token 都不进 workspace；只放 skill 产物 + 中间文件
+ *   - WORKSPACE_DIR 默认 server/runs/，可通过 env 覆盖（部署时可能挂载到独立 volume）
+ *
+ * 不在这层做的事：
+ *   - 真正的 chroot / cgroup 沙盒：MVP 是 trust-but-verify，工具层做严格 path 校验，
+ *     但不防 Node.js 进程内的反射攻击（agent 不能直接写 JS 调 fs，工具层是唯一入口）
+ *   - 资源配额（disk quota / cpu）：等 P3 接入 playwright 后再考虑
+ */
+
+import { promises as fs } from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+/** 所有 workspace 的根目录（绝对路径）*/
+export const WORKSPACE_ROOT = path.resolve(
+  process.env.WORKSPACE_DIR || path.join(__dirname, '../../runs')
+);
+
+// ── runId 校验（防止把恶意字符当目录名）──
+
+const RUN_ID_RE = /^run_[a-z0-9_]{6,80}$/i;
+
+function validateRunId(runId) {
+  if (typeof runId !== 'string' || !RUN_ID_RE.test(runId)) {
+    throw new Error(`非法 runId: ${JSON.stringify(runId)}`);
+  }
+}
+
+// ── 路径辅助 ──
+
+/** 该 run 的 workspace 绝对路径（不保证存在）*/
+export function getWorkspaceRoot(runId) {
+  validateRunId(runId);
+  return path.join(WORKSPACE_ROOT, runId, 'workspace');
+}
+
+/** 该 run 的 run-level 目录（workspace 的父目录），未来可放 logs/ events.jsonl 等 */
+export function getRunRoot(runId) {
+  validateRunId(runId);
+  return path.join(WORKSPACE_ROOT, runId);
+}
+
+/**
+ * 创建 workspace（幂等）。返回 workspace 绝对路径。
+ */
+export async function ensureWorkspace(runId) {
+  const root = getWorkspaceRoot(runId);
+  await fs.mkdir(root, { recursive: true });
+  return root;
+}
+
+/**
+ * 把相对路径解析成 workspace 内的绝对路径，并校验越界。
+ *
+ * 规则：
+ *   - relativePath 必须是非空字符串
+ *   - 解析后必须严格落在 workspace root 下（path.relative 不能以 .. 开头 / 不能是绝对）
+ *   - 不接受空串、'.'、'/'、绝对路径作为目标（避免歧义）
+ *
+ * @returns {string} 解析后的绝对路径
+ * @throws {Error}  路径越界 / 非法
+ */
+export function safeResolve(runId, relativePath) {
+  const root = getWorkspaceRoot(runId);
+  if (typeof relativePath !== 'string' || relativePath.length === 0) {
+    throw new Error(`safeResolve: 相对路径必须为非空字符串，收到 ${JSON.stringify(relativePath)}`);
+  }
+  if (path.isAbsolute(relativePath)) {
+    throw new Error(`safeResolve: 不接受绝对路径 ${relativePath}`);
+  }
+  const target = path.resolve(root, relativePath);
+  const rel = path.relative(root, target);
+  // path.relative 在 target 等于 root 时返回 ''；MVP 也禁止（语义不明）
+  if (rel === '' || rel.startsWith('..') || path.isAbsolute(rel)) {
+    throw new Error(`safeResolve: 路径越界或指向 workspace 自身: ${relativePath}`);
+  }
+  return target;
+}
+
+// ── 文件操作（薄包装，让 tool 层不直接 import fs）──
+
+/**
+ * 读文件文本内容。
+ * @param {string} runId
+ * @param {string} relativePath
+ * @returns {Promise<string>}
+ */
+export async function readFile(runId, relativePath) {
+  const abs = safeResolve(runId, relativePath);
+  return fs.readFile(abs, 'utf8');
+}
+
+/**
+ * 写文件（覆盖）；自动 mkdir 父目录。
+ * @returns {Promise<{ bytes: number, path: string }>}
+ */
+export async function writeFile(runId, relativePath, content) {
+  const abs = safeResolve(runId, relativePath);
+  await fs.mkdir(path.dirname(abs), { recursive: true });
+  const buf = Buffer.from(content, 'utf8');
+  await fs.writeFile(abs, buf);
+  return { bytes: buf.length, path: relativePath };
+}
+
+/**
+ * 列目录（一层；不递归）。返回 [{ name, type: 'file'|'dir', size? }]
+ * 不存在则返回 []（不抛）—— 让 agent 第一次访问空 workspace 不必先 try/catch
+ */
+export async function listDir(runId, relativePath = '.') {
+  const root = getWorkspaceRoot(runId);
+  // '.' 单独处理：列 workspace 根
+  const abs = relativePath === '.' ? root : safeResolve(runId, relativePath);
+  let entries;
+  try {
+    entries = await fs.readdir(abs, { withFileTypes: true });
+  } catch (err) {
+    if (err.code === 'ENOENT') return [];
+    throw err;
+  }
+  const out = [];
+  for (const e of entries) {
+    const item = { name: e.name, type: e.isDirectory() ? 'dir' : 'file' };
+    if (e.isFile()) {
+      try {
+        const stat = await fs.stat(path.join(abs, e.name));
+        item.size = stat.size;
+      } catch { /* ignore */ }
+    }
+    out.push(item);
+  }
+  return out;
+}
+
+/**
+ * 检查文件是否存在。返回 boolean。
+ */
+export async function exists(runId, relativePath) {
+  try {
+    const abs = safeResolve(runId, relativePath);
+    await fs.access(abs);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * 清理整个 run（workspace + run root）。MVP 不主动调用，留给将来的清理任务。
+ * ⚠️ 注意：rm -rf 等价；只通过 runId 匹配防误删
+ */
+export async function removeRun(runId) {
+  validateRunId(runId);
+  const root = getRunRoot(runId);
+  await fs.rm(root, { recursive: true, force: true });
+}

package/server/index.js

@@ -0,0 +1,235 @@
+/**
+ * server/index.js — NoDesign 后端入口
+ *
+ * 职责：
+ *   - Express HTTP 服务（默认端口 4001）
+ *   - WebSocket upgrade 处理（路径 /ws/projects/:pid）
+ *   - 路由挂载（/api/* — 业务 endpoint 在 C3+ 逐步补齐）
+ *   - dev 环境 CORS 开放给 vite 5174（prod 走 vite proxy 同源不需要）
+ *
+ * 启动：
+ *   node --env-file-if-exists=.env server/index.js
+ *   （Node 22+ 内置 --env-file-if-exists，不需要 dotenv 依赖）
+ */
+
+// ⚠️ 必须是第一个 import：它在别的模块加载前决定 profile（hosted | local）并给数据目录 env 填默认值
+import './runtime/profile.js';
+import http from 'http';
+import fs from 'node:fs';
+import path from 'node:path';
+import express from 'express';
+import cors from 'cors';
+import { originAllowed } from './auth/origin-guard.js';
+
+import { setupWS } from './ws/index.js';
+import { primeOwnAddresses } from './lib/ssrf-guard.js';
+import { stopIngress } from './lib/model-ingress.js';
+import { startRembgService, stopRembgService } from './services/rembg-launcher.js';
+import projectsRouter from './api/projects.js';
+import canvasRouter from './api/canvas.js';
+import skillsRouter from './api/skills.js';
+import assetsRouter from './api/assets.js';
+import turnRouter from './api/turn.js';
+import exportsRouter from './api/exports.js';
+import sessionsRouter from './api/sessions.js';
+import instructionRouter from './api/instruction.js';
+import memoryRouter from './api/memory.js';
+import boardRouter from './api/board.js';
+import pendingChangesRouter from './api/pending-changes.js';
+import browseRouter from './api/browse.js';
+import publishRouter from './api/publish.js';
+import chataiRouter from './api/chatai.js';
+import recentRouter from './api/recent.js';
+import { userPluginsRouter, projectPluginsRouter } from './api/plugins.js';
+import { authRouter, authGuard } from './auth/middleware.js';
+import { authEnabled } from './auth/session.js';
+import { bootstrapAuth } from './auth/users-store.js';
+import { sweepOrphanRuns } from './engine/runs/store.js';
+import adminRouter from './api/admin.js';
+import meRouter from './api/me.js';
+import localRouter, { RESTART_EXIT_CODE } from './api/local.js';
+import { platform } from './runtime/platform.js';
+import { probeCapabilities, summarizeCapabilities } from './runtime/capabilities.js';
+
+// 启动时 dump 平台决策（让运维一眼看到 OS / HOME / claudeConfigDir / sandbox / preflight）
+// 跨平台坑排查的第一信号
+platform.dump();
+// 本机能力位（git / chromium / LibreOffice / 钥匙…）：启动探一遍，工具注册（mcp/capability-gate.js）与
+// GET /api/local/status 都读它。探测是异步的（playwright 要 import），在 listen 之前等它
+await probeCapabilities();
+console.log(summarizeCapabilities());
+
+const PORT = Number(process.env.PORT || 4001);
+
+const app = express();
+
+// cors：origin:true 是「反射任何来源」，配 credentials 等于把 REST 也交给同站
+// 攻击面（见 auth/origin-guard.js）。收成同一份判据。
+app.use(cors((req, cb) => cb(null, {
+  origin: originAllowed(req) ? (req.headers.origin || true) : false,
+  credentials: true,
+})));
+app.use(express.json({ limit: '4mb' }));
+
+// ── Health ──
+app.get('/api/health', (_req, res) => {
+  res.json({
+    ok: true,
+    service: 'nodesign',
+    version: '0.1.0',
+    ts: new Date().toISOString(),
+  });
+});
+
+// ── 登录墙（health 之后、业务路由之前）──
+// 多用户 bootstrap（幂等）：users 空时用 NODESIGN_AUTH_PASSWORD 建 admin +
+// 回填存量项目归属。必须在 authEnabled() 判断之前跑
+// 僵尸 run 清扫：只有 server 启动时才知道"上个进程已经死了"这个前提成立。
+// 2026-07-31 从 store.js 的模块加载副作用挪到这里 —— 挂在 import 上时，任何
+// 碰到 store 的脚本（invite.mjs / notice.mjs / 临时排查）都会把线上正在跑的
+// run 全标成 failed，实测误杀过真实用户的对话。
+sweepOrphanRuns();
+
+if (platform.isLocal) {
+  // 本地分发版：单租户，登录墙钉死关闭（auth/users-store.js authEnabled），请求者恒为 LOCAL_OWNER。
+  // 不跑 bootstrapAuth：它会按 NODESIGN_AUTH_PASSWORD 建 admin、回填项目归属 —— 那是多用户站的事。
+  console.log(`[profile] local：单租户模式，数据目录 ${platform.dataRoot}，只监听 ${platform.listenHost}`);
+} else {
+  bootstrapAuth();
+  if (!authEnabled()) {
+    console.warn('[auth] ⚠️ 无用户且未设 NODESIGN_AUTH_PASSWORD — 登录墙关闭，切勿公网暴露！');
+  }
+}
+app.use('/api/auth', authRouter);
+app.use('/api', authGuard);
+// admin 管理接口 + 当前用户自视图（都在 authGuard 之后，req.user 已挂）
+app.use('/api/admin', adminRouter);
+app.use('/api/me', meRouter);
+// 本地分发版专用（配置文件 / 状态 / 重启）。hosted 下不挂：这组接口假设请求者就是机器的主人
+if (platform.isLocal) app.use('/api/local', localRouter);
+
+// ── 业务路由 ──
+// projects router 挂在 /api/projects（CRUD）
+app.use('/api/projects', projectsRouter);
+// canvas / assets / turn 共用 /api/projects/:pid/* 命名空间，挂同前缀
+app.use('/api/projects', canvasRouter);
+app.use('/api/projects', assetsRouter);
+app.use('/api/projects', turnRouter);
+app.use('/api/projects', exportsRouter);
+app.use('/api/projects', sessionsRouter);
+app.use('/api/projects', instructionRouter);
+app.use('/api/projects', memoryRouter);
+app.use('/api/projects', boardRouter);
+app.use('/api/projects', pendingChangesRouter);  // C4: 用户直接编辑 + 评论 buffer
+app.use('/api/projects', browseRouter);          // 刷新后拿回浏览器窗/求助状态
+app.use('/api/projects', publishRouter);         // 站点一键上线 Cloudflare Pages
+app.use('/api/projects', chataiRouter);          // 演出端点：页面 → chatai 通路（编排/闸门见 api/chatai.js）
+app.use('/api/projects', projectPluginsRouter);  // 2026-05-18: project 级 plugin 上传/卸载/列表
+// 跨项目聚合：/api/sessions/recent
+app.use('/api', recentRouter);
+// skills 全局
+app.use('/api/skills', skillsRouter);
+// 用户级 plugin（跨 project 全局）
+app.use('/api/plugins', userPluginsRouter);
+
+// ── 前端静态托管（本地分发版；hosted 由 nginx 发 dist，这里默认关）──
+if (platform.serveWeb) {
+  const indexHtml = path.join(platform.webDistDir, 'index.html');
+  if (!fs.existsSync(indexHtml)) {
+    // 不抛：API 照常可用（开发者可能正用 vite dev 连着）。但要说出来，别让人对着 404 猜
+    console.warn(`[server] ⚠️ 前端构建产物不存在：${indexHtml}（先 cd web && npm run build）`);
+  }
+  // 入口 HTML 不缓存（和线上 nginx 同口径：发新版后开着的页面刷新就能拿到新分片）；哈希分片随便缓存
+  app.use(express.static(platform.webDistDir, {
+    index: false,
+    setHeaders(res, file) { if (file.endsWith('.html')) res.setHeader('Cache-Control', 'no-cache'); },
+  }));
+  app.use((req, res, next) => {
+    // SPA 回退：非 API / WS 的 GET 一律回 index.html（/projects/:id 这类前端路由刷新不 404）
+    if (req.method !== 'GET' || req.path.startsWith('/api/') || req.path.startsWith('/ws/')) return next();
+    if (!fs.existsSync(indexHtml)) return next();
+    res.setHeader('Cache-Control', 'no-cache');
+    res.sendFile(indexHtml);
+  });
+}
+
+// ── 错误兜底 ──
+app.use((err, _req, res, _next) => {
+  console.error('[server] error:', err);
+  res.status(err.status || 500).json({
+    error: err.message || 'internal error',
+    code: err.code,
+  });
+});
+
+// ── 启动 ──
+const httpServer = http.createServer(app);
+setupWS(httpServer);
+
+// listenHost：local = 127.0.0.1（没有登录墙，绝不能开到全地址）；hosted = undefined（Node 默认全地址，nginx 在前）
+httpServer.on('error', (err) => {
+  // 不走 uncaughtException（那个 handler 故意不退出）：没监听成功的进程是僵尸，supervisor 会以为它还活着
+  if (err?.code === 'EADDRINUSE') {
+    console.error(`[server] 端口 ${PORT} 已被占用（${platform.listenHost || '*'}:${PORT}）。换一个：nodesign --port 4002，或 PORT=4002；查占用：`
+      + (process.platform === 'win32' ? `netstat -ano | findstr :${PORT}` : `lsof -i :${PORT}`));
+  } else {
+    console.error('[server] listen failed:', err?.message || err);
+  }
+  process.exit(1);
+});
+httpServer.listen(PORT, platform.listenHost, () => {
+  // 出网闸要知道本机的公网 IP —— 云上 1:1 NAT 下它不在任何网卡上（见 ssrf-guard）
+  primeOwnAddresses().catch(() => {});
+  console.log(`[server] listening on ${platform.listenHost || ''}:${PORT}`);
+  console.log(`[server] health: http://localhost:${PORT}/api/health`);
+  if (platform.serveWeb) console.log(`[server] app: http://${platform.listenHost || 'localhost'}:${PORT}/`);
+});
+
+// 起 rembg-service 常驻 python 进程：onnxruntime session 在内存里 warm 缓存，
+// 让 mcp__nodesign__remove_background 调用走 Unix socket（warm ~5-15s/张），
+// 比 per-call cold spawn（~30-180s/张）快 10×。venv 不存在 / spawn 失败时
+// noop 不阻塞 server，remove_background 走 fallback spawn-bridge 兼容路径。
+// 详见 server/services/rembg-launcher.js + rembg-service.py。
+startRembgService().catch((err) => {
+  console.warn('[server] rembg-service start error (non-fatal):', err.message);
+});
+
+// 守护进程级兜底：SDK binary 子进程偶发 stdio 异常（write EPIPE 之类）会
+// emit unhandled 'error' on Socket，nodejs 默认把整个 process 拉下水（之前
+// 实测 "Session ID already in use" 错让 server crash 用户连不上）。
+//
+// 这里只 log + 不退出 —— 单次 SDK call 的 socket 错不该影响其他正在跑的
+// session 或新 HTTP 请求。真严重的错（OOM / 不可恢复 state）会 log 后由
+// 上层 watch / supervisord 重启。
+process.on('uncaughtException', (err) => {
+  console.error('[server] uncaughtException:', err?.message || err);
+  if (err?.stack) console.error(err.stack);
+});
+process.on('unhandledRejection', (reason) => {
+  console.error('[server] unhandledRejection:', reason?.message || reason);
+  if (reason?.stack) console.error(reason.stack);
+});
+
+// graceful shutdown
+let shuttingDown = false;
+function shutdown(signal, exitCode = 0) {
+  if (shuttingDown) return;
+  shuttingDown = true;
+  console.log(`[server] ${signal} received, shutting down...`);
+  // 关闭 model-ingress（API 通路会话会启的本地通用入口）。
+  // 不阻塞 httpServer close —— close fail 也不影响主流程。
+  stopIngress().catch((err) => console.error('[server] ingress close error:', err.message));
+  // 关闭 rembg-service 常驻 python 进程（SIGTERM；兜底 3s 后 SIGKILL）。
+  stopRembgService();
+  httpServer.close((err) => {
+    if (err) console.error('[server] close error:', err);
+    process.exit(err ? 1 : exitCode);
+  });
+  // 兜底强制退出（重启请求也按约定码退，bin 的 supervisor 才会拉起新进程）
+  setTimeout(() => process.exit(exitCode || 1), 5000).unref();
+}
+process.on('SIGINT', () => shutdown('SIGINT'));
+process.on('SIGTERM', () => shutdown('SIGTERM'));
+// 本地分发版「保存配置后重启」：api/local.js 发这个事件，进程以 RESTART_EXIT_CODE 退出，bin/nodesign.js 的
+// supervisor 见到这个码就重新拉起（模型表是加载时冻结的，热改不如重起干净）
+process.on('nodesign:restart', () => shutdown('restart', RESTART_EXIT_CODE));