modelstage 0.0.0-stage → 0.5.28

package/src/server/http/diag-upload.mjs

@@ -0,0 +1,264 @@
+// http/diag-upload.mjs —— 「上传调试日志」的落盘与两条接口
+//
+// 为什么要有：页面里的调试日志只在内存（刷新即丢），出问题时用户描述不清、AI 又读不到浏览器。
+//   这里提供一个"用户点一下、日志落到服务端"的出口，之后 AI 靠 GET /api/diag/uploads 就能
+//   自己查到"文件在哪、多大、几条"，不必再问用户。
+//
+// 两条接口（路由在 serve.mjs 里挂，这里只做数据与校验）：
+//   POST /api/diag/upload   收 { logs, meta } → 落盘 data/logs/diag-<yyyyMMdd-HHmmss>.json
+//   GET  /api/diag/uploads  按时间倒序列出已上传文件 [{ file, at, bytes, count, truncated }]
+//
+// 四条硬约束：
+//   1. **文件名一律服务端生成**：客户端即使传了 file/path 也直接忽略（防路径穿越）；
+//      落盘路径只用 path.join(LOGS_DIR, basename)，并校验最终路径确实在 LOGS_DIR 之内
+//   2. **边读边计数**：请求体超过上限立刻中断并返回 413，不允许"先全读进内存再判"
+//   3. **条数/体积上限走配置**（config/diag-upload.json），不写死；超条数时截断并在文件里标 truncated
+//   4. **索引 index.json 走 tmp+rename 原子写 + 串行队列**，并发上传不会互相覆盖
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { parseJsonc } from '../../../tool/parse-jsonc.mjs';
+
+/** 默认上限（配置文件缺失时用它）：条数与请求体积分开限，前者防日志爆炸、后者防内存 */
+const DEFAULTS = {
+  maxCount: 5000,              // 单次上传最多保留多少条（超出即截断，文件里标 truncated）
+  maxBytes: 5 * 1024 * 1024,   // 单次请求体上限 5MB（约 5000 条中等日志的 3~5 倍余量）
+};
+
+/** 索引文件名（放 data/logs/ 里，与日志文件同目录，便于一起带走） */
+const INDEX_FILE = 'index.json';
+
+/** 时间戳：文件名里的 yyyyMMdd-HHmmss（本地时区，给人看的） */
+function stampFile(d = new Date()) {
+  const p = (n) => String(n).padStart(2, '0');
+  return `${d.getFullYear()}${p(d.getMonth() + 1)}${p(d.getDate())}-${p(d.getHours())}${p(d.getMinutes())}${p(d.getSeconds())}`;
+}
+
+/**
+ * 读上传上限配置（JSONC，与 config/resources.json 同一套解析）。
+ * 文件不存在/损坏就用 DEFAULTS —— 配置只是"允许调"，不是"必须存在"。
+ * @param {string} configFile
+ * @returns {{maxCount: number, maxBytes: number}}
+ */
+function readLimits(configFile) {
+  try {
+    const raw = fs.readFileSync(configFile, 'utf8');
+    const cfg = parseJsonc(raw, 'config/diag-upload.json');
+    const maxCount = Number(cfg.maxCount);
+    const maxBytes = Number(cfg.maxBytes);
+    return {
+      maxCount: Number.isFinite(maxCount) && maxCount > 0 ? Math.floor(maxCount) : DEFAULTS.maxCount,
+      maxBytes: Number.isFinite(maxBytes) && maxBytes > 0 ? Math.floor(maxBytes) : DEFAULTS.maxBytes,
+    };
+  } catch {
+    return { ...DEFAULTS };
+  }
+}
+
+/** 吐 JSON（与 serve.mjs 的 sendJson 同口径；这里自带一份避免跨模块耦合） */
+function sendJson(res, status, body) {
+  const text = JSON.stringify(body);
+  res.writeHead(status, {
+    'Content-Type': 'application/json; charset=utf-8',
+    'Content-Length': Buffer.byteLength(text),
+    'Cache-Control': 'no-store',
+  });
+  res.end(text);
+}
+
+/**
+ * 限制体积地读完整请求体。
+ * 超限时**立刻**回 413 并停止累计（不清空缓冲区也会被 GC 回收，不会 OOM）。
+ * @param {import('node:http').IncomingMessage} req
+ * @param {import('node:http').ServerResponse} res
+ * @param {number} maxBytes
+ * @returns {Promise<Buffer|null>} 超限/出错返回 null（调用方已收到响应）
+ */
+function readBodyLimited(req, res, maxBytes) {
+  return new Promise((resolve) => {
+    const chunks = [];
+    let total = 0;
+    let done = false;
+    const finish = (value) => { if (!done) { done = true; resolve(value); } };
+    req.on('data', (chunk) => {
+      if (done) return;
+      total += chunk.length;
+      if (total > maxBytes) {
+        sendJson(res, 413, { ok: false, error: `请求体超过上限（${maxBytes} 字节）`, maxBytes });
+        // 多余数据丢弃：继续 drain 会白占内存，destroy 前给响应一点时间发出去
+        setTimeout(() => { try { req.destroy(); } catch { /* 已断开 */ } }, 300);
+        finish(null);
+        return;
+      }
+      chunks.push(chunk);
+    });
+    req.on('end', () => finish(Buffer.concat(chunks)));
+    req.on('error', () => {
+      sendJson(res, 400, { ok: false, error: '读取请求体失败' });
+      finish(null);
+    });
+  });
+}
+
+/**
+ * 同步判定这两条路由是否命中。
+ *
+ * 为什么必须有同步的 matches：真正的处理要异步读请求体（handle 是 async），而 serve.mjs 里
+ *   写的是 `if (xxx.handle(...)) return;` —— 直接判 async 函数会**恒真**（返回 Promise），
+ *   把后面所有路由都截断掉（实测：挂上后整站 404）。所以拆成"同步匹配 + 异步执行"两步。
+ * @param {string} method
+ * @param {string} p 路径
+ * @returns {boolean} 是否命中
+ */
+export function matches(method, p) {
+  if (p === '/api/diag/upload') return method === 'POST';
+  if (p === '/api/diag/uploads') return method === 'GET';
+  return false;
+}
+
+/**
+ * 建"落盘仓库"：只管文件的读写与索引，不关心 HTTP。
+ * @param {{logsDir: string}} opts
+ * @returns {{logsDir: string, save: Function, list: Function, makeFileName: Function}}
+ */
+function createStore({ logsDir }) {
+  const indexPath = path.join(logsDir, INDEX_FILE);
+  // 串行队列：索引是"读-改-写"，并发写会丢条目（背景图那边同样的坑）
+  let queue = Promise.resolve();
+  fs.mkdirSync(logsDir, { recursive: true });
+
+  /** 读索引（缺失/损坏都当空表） */
+  function readIndex() {
+    try {
+      const arr = JSON.parse(fs.readFileSync(indexPath, 'utf8'));
+      return Array.isArray(arr) ? arr : [];
+    } catch {
+      return [];
+    }
+  }
+
+  /** 原子写索引（tmp + rename），并串行化，避免并发上传互相覆盖 */
+  function appendIndex(entry) {
+    queue = queue.then(() => {
+      const list = readIndex();
+      list.push(entry);
+      const tmp = `${indexPath}.tmp`;
+      fs.writeFileSync(tmp, JSON.stringify(list, null, 1));
+      fs.renameSync(tmp, indexPath);
+    }, () => { /* 上一次失败不影响这一次 */ });
+    return queue;
+  }
+
+  /**
+   * 生成不冲突的文件名（同一秒内多次上传时追加序号）。
+   * 名字**完全由服务端决定**，客户端给什么都不参与。
+   * @returns {string} 形如 diag-20261024-143000.json
+   */
+  function makeFileName() {
+    const base = `diag-${stampFile()}`;
+    let candidate = `${base}.json`;
+    let n = 1;
+    while (fs.existsSync(path.join(logsDir, candidate))) {
+      n += 1;
+      candidate = `${base}-${n}.json`;
+    }
+    return candidate;
+  }
+
+  /**
+   * 落盘一次上传（条数超限只保留最新的 N 条并标记截断）。
+   * @param {object} payload 客户端请求体 { logs, meta }
+   * @param {{maxCount:number,maxBytes:number}} limits
+   * @returns {{ok:true, file:string, path:string, count:number, bytes:number, truncated:boolean}}
+   */
+  function save(payload, limits) {
+    const all = Array.isArray(payload && payload.logs) ? payload.logs : null;
+    if (!all) {
+      const err = new Error('logs 必须是数组');
+      err.status = 400;
+      throw err;
+    }
+    // 条数上限：只保留**最新的** N 条（日志尾部才有现场价值），并显式标记截断
+    const truncated = all.length > limits.maxCount;
+    const logs = truncated ? all.slice(-limits.maxCount) : all;
+    const file = makeFileName();
+    // 二次防线：即便文件名生成逻辑被改坏，也不允许落到 logsDir 之外
+    const fullPath = path.join(logsDir, path.basename(file));
+    if (path.dirname(fullPath) !== logsDir) throw new Error('落盘路径越界');
+
+    const doc = {
+      meta: (payload && payload.meta && typeof payload.meta === 'object') ? payload.meta : {},
+      count: logs.length,
+      truncated,
+      received: all.length,
+      uploadedAt: new Date().toISOString(),
+      logs,
+    };
+    const text = JSON.stringify(doc, null, 1);
+    const tmp = `${fullPath}.tmp`;
+    fs.writeFileSync(tmp, text);
+    fs.renameSync(tmp, fullPath);          // 原子可见：不会读到写了一半的文件
+
+    const bytes = Buffer.byteLength(text);
+    appendIndex({ file, at: Date.now(), bytes, count: logs.length, truncated });
+    return { ok: true, file, path: fullPath, count: logs.length, bytes, truncated };
+  }
+
+  /** 列表：按时间倒序（最新的在前），带绝对路径供工具直接读 */
+  function list() {
+    return readIndex()
+      .filter((e) => e && typeof e.file === 'string')
+      .sort((a, b) => (b.at || 0) - (a.at || 0))
+      .map((e) => ({
+        file: e.file,
+        at: e.at,
+        bytes: e.bytes,
+        count: e.count,
+        truncated: e.truncated === true,
+        path: path.join(logsDir, path.basename(e.file)),
+      }));
+  }
+
+  return { logsDir, save, list, makeFileName };
+}
+
+/**
+ * 创建"上传调试日志"模块（路由在 serve.mjs 里挂）。
+ * @param {{dataDir: string, configDir?: string}} paths 服务端数据目录与配置目录
+ * @returns {{matches: Function, handle: Function, listUploads: Function, logsDir: string, configFile: string}}
+ */
+export function createDiagUpload(paths) {
+  const logsDir = path.join(paths.dataDir, 'logs');
+  const configFile = path.join(paths.configDir || path.join(path.dirname(paths.dataDir), 'config'), 'diag-upload.json');
+  const store = createStore({ logsDir });
+
+  /**
+   * 异步执行（只在 matches 命中后调用；调用方不要 await，让它自己写完响应）。
+   * @returns {Promise<void>}
+   */
+  async function handle(req, res, p) {
+    if (p === '/api/diag/uploads') {
+      sendJson(res, 200, { ok: true, uploads: store.list() });
+      return;
+    }
+    const limits = readLimits(configFile);
+    const raw = await readBodyLimited(req, res, limits.maxBytes);
+    if (raw === null) return;                        // 已回 413/400
+    let payload = null;
+    try {
+      payload = JSON.parse(raw.toString('utf8') || '{}');
+    } catch {
+      sendJson(res, 400, { ok: false, error: '请求体不是合法 JSON' });
+      return;
+    }
+    try {
+      sendJson(res, 200, store.save(payload, limits));
+    } catch (e) {
+      sendJson(res, e.status || 500, { ok: false, error: e.message || '上传失败' });
+    }
+  }
+
+  return { matches, handle, listUploads: store.list, logsDir, configFile };
+}
+
+export { DEFAULTS as DIAG_UPLOAD_DEFAULTS, stampFile };

package/src/server/http/diag.mjs

@@ -0,0 +1,173 @@
+// diag.mjs —— 前端诊断落盘（POST /api/diag 的数据层）
+//
+// 与旧服务同一套规则（行数/体积/轮转一致），只写 data/ 目录，不触碰用户配置：
+//   · 一行一条 JSON，追加写；
+//   · 单请求最多 500 条、单条最长 8000 字（防止一次把磁盘写满）；
+//   · 文件超过 8MB 时把当前文件改名 diag.jsonl.1（只保留一代）再继续写；
+//   · 任何异常都只回 {ok:false}，绝不抛到路由外（否则会打挂进程）。
+import fs from 'node:fs';
+import path from 'node:path';
+import { createLogger } from '../core/log.mjs';
+
+const MAX_BYTES = 8 * 1024 * 1024;
+const MAX_ENTRIES_PER_REQ = 500;
+const MAX_LINE_CHARS = 8000;
+// 每个缓冲只留最近几个会话（防长期运行内存增长）。
+// 必须放在模块级：getSession() 是模块级函数，放在 createDiag() 的闭包里它看不见，
+//   走到淘汰分支就抛 ReferenceError，被上层 catch 成「落盘失败（降级为仅内存）」——
+//   表现为诊断日志从第 5 个会话起悄悄不再写文件，而页面一切正常。
+const SESSION_MAX = 4;
+
+/**
+ * @param {{dataDir: string, diagFile: string}} paths
+ */
+/** 服务端日志（统一形状） */
+const log = createLogger('diag');
+
+export function createDiag(paths) {
+  // 服务端侧的环形缓冲（GET /api/diag 读它，与面板内容同源）。
+  // 按会话 id 分组：页面重载会换 sid，旧条目不会混进"当前这一轮"的统计。
+  const sessions = new Map();   // sid -> { recent, counts, lastAt }
+
+  /**
+   * 追加一批诊断条目。
+   * @param {string} body 原始请求体
+   * @returns {{ok: boolean, written?: number, dropped?: number, error?: string}}
+   */
+  function appendDiag(body) {
+    let payload;
+    try {
+      payload = JSON.parse(body || '{}');
+    } catch {
+      return { ok: false, error: '请求体不是合法 JSON' };
+    }
+    const entries = payload && Array.isArray(payload.entries) ? payload.entries : null;
+    if (!entries) return { ok: false, error: '缺少 entries 数组' };
+
+    const take = entries.slice(0, MAX_ENTRIES_PER_REQ);
+    try {
+      if (!fs.existsSync(paths.dataDir)) fs.mkdirSync(paths.dataDir, { recursive: true });
+      rotateIfNeeded(paths.diagFile);
+      const sid = String((payload && payload.sid) || 'anonymous');
+      remember(getSession(sessions, sid), take);
+      const lines = take.map(serialize).filter(Boolean);
+      if (lines.length) fs.appendFileSync(paths.diagFile, lines.join('\n') + '\n', 'utf8');
+      return { ok: true, written: lines.length, dropped: entries.length - take.length };
+    } catch (e) {
+      log.warn('落盘失败（前端会降级为仅内存）', { err: e.message });
+      return { ok: false, error: e.message };
+    }
+  }
+
+  /**
+   * 读取最近的诊断条目（只读：不接受调用方指定文件/路径）。
+   * 返回结构与面板一致：{ t, level, src, event, data }，外加 total 与级别分布。
+   * @param {{limit?: number, sid?: string}} [options] sid 为页面实例 id（前端每次加载都换）
+   * @returns {{ok: true, sid: string|null, sidRequested: string|null, sidSource: 'query'|'latest'|'none', total: number, counts: object, entries: object[]}}
+   */
+  function readDiag(options = {}) {
+    const limit = Math.min(Math.max(Number(options.limit) || CAPACITY, 1), CAPACITY);
+    const wanted = options.sid ? String(options.sid) : '';
+    // 选会话并**标明来源**：
+    //   query  = 按调用方给的 sid 精确命中（前端读"当前这一轮"走这条）
+    //   latest = 没给 sid 或给的 sid 尚未产生条目 ⇒ 兜底最近活跃会话（不传就永远空最难查）
+    //   none   = 一条会话都没有（页面还没上报过）
+    // 注意：兜底时**绝不能回显请求里的 sid** —— 那会让调用方以为"这个 sid 有数据但内容为空"。
+    let picked = wanted ? sessions.get(wanted) || null : null;
+    let sidSource = picked ? 'query' : null;
+    if (!picked) {
+      picked = pickSession(sessions, null);
+      sidSource = picked ? 'latest' : 'none';
+    }
+    const base = { ok: true, sidRequested: wanted || null, sidSource };
+    if (!picked) {
+      return { ...base, sid: null, total: 0, counts: { info: 0, warn: 0, error: 0, debug: 0 }, entries: [] };
+    }
+    return {
+      ...base,
+      sid: picked.sid,
+      total: picked.recent.length,
+      counts: { ...picked.counts },
+      entries: picked.recent.slice(-limit).map(shapeEntry),
+    };
+  }
+
+  return { appendDiag, readDiag };
+}
+
+/** 服务端环形缓冲容量（与前端 diag 默认容量一致） */
+const CAPACITY = 500;
+
+/** 取（或建）一个会话的缓冲；超过上限时淘汰最久未活动的会话 */
+function getSession(sessions, sid) {
+  let s = sessions.get(sid);
+  if (!s) {
+    s = { sid, recent: [], counts: { info: 0, warn: 0, error: 0, debug: 0 }, lastAt: Date.now() };
+    sessions.set(sid, s);
+    if (sessions.size > SESSION_MAX) {
+      let oldestKey = null;
+      let oldestAt = Infinity;
+      for (const [key, val] of sessions) if (val.lastAt < oldestAt) { oldestAt = val.lastAt; oldestKey = key; }
+      if (oldestKey) sessions.delete(oldestKey);
+    }
+  }
+  s.lastAt = Date.now();
+  return s;
+}
+
+/** 选会话：指定 sid 优先；没指定就取最近活跃的那个 */
+function pickSession(sessions, sid) {
+  if (sid) return sessions.get(String(sid)) || null;
+  let best = null;
+  for (const val of sessions.values()) if (!best || val.lastAt > best.lastAt) best = val;
+  return best;
+}
+
+/** 入环形缓冲 + 累计级别分布（容量满丢最旧；分布只统计当前缓冲内的条目） */
+function remember(session, entries) {
+  const { recent, counts } = session;
+  for (const raw of entries) {
+    const level = raw && typeof raw.level === 'string' ? raw.level : 'info';
+    recent.push({ level, src: raw && raw.src, event: raw && raw.event, data: raw && raw.data, t: raw && raw.t });
+    if (counts[level] === undefined) counts[level] = 0;
+    counts[level] += 1;
+    if (recent.length > CAPACITY) {
+      const dropped = recent.shift();
+      const key = dropped && dropped.level;
+      if (key && counts[key] !== undefined) counts[key] = Math.max(0, counts[key] - 1);
+    }
+  }
+}
+
+/** 单条对外形状（稳定字段：t/level/src/event/data） */
+function shapeEntry(e) {
+  return {
+    t: e && e.t ? String(e.t) : null,
+    level: (e && e.level) || 'info',
+    src: (e && e.src) || null,
+    event: (e && e.event) || null,
+    data: e && e.data !== undefined ? e.data : null,
+  };
+}
+
+/** 超过上限就把当前文件挪成 .1（只保留一代）；轮转失败不阻断本次写入 */
+function rotateIfNeeded(diagFile) {
+  try {
+    if (fs.existsSync(diagFile) && fs.statSync(diagFile).size > MAX_BYTES) {
+      fs.renameSync(diagFile, `${diagFile}.1`);
+    }
+  } catch {
+    /* 忽略 */
+  }
+}
+
+/** 单条序列化 + 截断；失败返回 null（跳过该条，不影响整批） */
+function serialize(entry) {
+  try {
+    const s = JSON.stringify(entry);
+    if (typeof s !== 'string') return null;
+    return s.length > MAX_LINE_CHARS ? s.slice(0, MAX_LINE_CHARS) : s;
+  } catch {
+    return null;
+  }
+}

package/src/server/http/ready.mjs

@@ -0,0 +1,167 @@
+// http/ready.mjs —— 就绪信号通道（服务端状态机 + SSE）
+//
+// 契约：docs/契约/交互与实现约束.md（实现以它为准）。要点：
+//   · 与 diag 完全分离：这里存**状态机**（每阶段只保留最新值），不是流水，也不进调试面板；
+//   · 每阶段只前进不后退（failed 可覆盖任何状态，且必须带 reason）；
+//   · rev 单调递增：测试据此判断快照是否过期；
+//   · GET /api/ready 幂等（任何时刻都返回完整快照，不依赖是否连过流）；
+//   · GET /api/ready/stream 连上时**先推全量 snapshot，再推增量 update**
+//     —— 只推增量会让"页面早就绪之后才连上"的测试永远等不到（死锁），这是契约 §5.3 的重点。
+//
+// 结构：状态放在一个普通 store 里，读写都是模块级函数（不塞进工厂闭包）——
+//   每个函数都能单独读、单独测，也不会被"单函数 100+ 行"的门禁拦下。
+
+/** 阶段清单（契约 §三：新增阶段必须先登记，不允许随手加字符串） */
+export const STAGES = [
+  'shell', 'topbar', 'sidebarLeft', 'sidebarRight', 'panel',
+  'bottombar', 'debugPanel', 'renderer', 'model',
+];
+
+// 合法状态（契约 §四）：
+//   pending = 尚未上报（等级最低，任何真实状态都能覆盖它；不用 unknown，契约里没有这个值）
+//   painted = 模型专属中间级（§2.2）——漏进白名单会让它被静默丢弃（实测踩过）
+export const STATES = ['pending', 'mounted', 'painted', 'settled', 'interactive', 'failed'];
+
+/** 前进顺序：同一阶段不得退回低等级（failed 例外）；painted 与 settled 同档 */
+const RANK = { pending: 0, mounted: 1, painted: 2, settled: 2, interactive: 3 };
+
+/** SSE 心跳间隔：反代/浏览器会掐掉长时间静默的连接 */
+const HEARTBEAT_MS = 15000;
+
+/** 校验阶段名与状态；非法输入返回 { ignore: 原因 } */
+function validateUpdate(u) {
+  const name = String((u && u.stage) || '');
+  const state = String((u && u.state) || '');
+  if (!STAGES.includes(name)) return { ignore: `${name || '(空)'}: 未登记的阶段` };
+  if (!STATES.includes(state)) return { ignore: `${name}: 非法状态 ${state}` };
+  return { name, state };
+}
+
+/** 由一条上报构造记录（detail 可选；failed 必带 reason） */
+function buildRecord(u, state) {
+  const rec = { state, at: Number(u.at) || Date.now() };
+  if (u.detail && typeof u.detail === 'object') rec.detail = u.detail;
+  if (state === 'failed') rec.reason = String(u.reason || '未提供原因');
+  return rec;
+}
+
+/** 把一条上报解析成记录；非法输入返回 { ignore: 原因 } */
+function toRecord(u) {
+  const v = validateUpdate(u);
+  if (v.ignore) return v;
+  return { name: v.name, state: v.state, rec: buildRecord(u, v.state), reset: u.reset === true };
+}
+
+/** 该不该接受这次变更：只前进不后退，failed 可覆盖任何状态，reset 后从零起算 */
+function shouldAdvance(state, prev) {
+  if (state === 'failed' || !prev || prev.state === 'failed') return true;
+  return (RANK[state] || 0) > (RANK[prev.state] || 1);
+}
+
+/** 推增量给所有在线的 SSE 客户端 */
+function broadcast(store, items) {
+  for (const res of store.clients) {
+    for (const it of items) {
+      try {
+        res.write(`event: update\ndata: ${JSON.stringify(it)}\n\n`);
+      } catch {
+        store.clients.delete(res);
+      }
+    }
+  }
+}
+
+/** 应用一条上报；返回 { change } 或 { ignored } */
+function applyOne(store, u) {
+  const parsed = toRecord(u);
+  if (parsed.ignore) return { ignored: parsed.ignore };
+  if (parsed.reset) store.stages.delete(parsed.name);
+  const prev = store.stages.get(parsed.name);
+  if (!shouldAdvance(parsed.rec.state, prev)) return {};
+  store.stages.set(parsed.name, parsed.rec);
+  store.rev += 1;
+  return { change: { stage: parsed.name, ...parsed.rec, rev: store.rev } };
+}
+
+/** clear：页面重载/新实例接入时清空上一轮阶段（rev 继续递增，不回退版本号） */
+function clearAll(store) {
+  store.stages = new Map();
+  store.rev += 1;
+  broadcast(store, [{ stage: '*', state: 'cleared', at: Date.now(), rev: store.rev }]);
+  return { ok: true, rev: store.rev, changed: 1, ignored: [] };
+}
+
+/** 应用一批更新（页面侧上报入口） */
+function applyUpdates(store, body) {
+  if (body && body.clear === true) return clearAll(store);
+  const list = Array.isArray(body && body.updates) ? body.updates : [];
+  const changed = [];
+  const ignored = [];
+  for (const u of list) {
+    const r = applyOne(store, u);
+    if (r.ignored) ignored.push(r.ignored);
+    if (r.change) changed.push(r.change);
+  }
+  if (changed.length) broadcast(store, changed);
+  return { ok: true, rev: store.rev, changed: changed.length, ignored };
+}
+
+/** 取快照（幂等）。单阶段：未登记 → ok:false（路由给 400）；已登记未上报 → pending */
+function snapshotOf(store, stage) {
+  const at = Date.now();
+  if (!stage) {
+    const out = {};
+    for (const [name, rec] of store.stages) out[name] = rec;
+    return { at, rev: store.rev, stages: out };
+  }
+  const name = String(stage);
+  if (!STAGES.includes(name)) return { ok: false, error: `未登记的阶段：${name}`, known: STAGES.slice() };
+  const rec = store.stages.get(name);
+  return rec ? { at, rev: store.rev, stage: name, ...rec } : { at, rev: store.rev, stage: name, state: 'pending' };
+}
+
+/** 订阅 SSE：先推全量快照，再推增量（契约 §5.3） */
+function subscribeSse(store, req, res) {
+  res.writeHead(200, {
+    'Content-Type': 'text/event-stream; charset=utf-8',
+    'Cache-Control': 'no-cache, no-transform',
+    Connection: 'keep-alive',
+    // 反代（nginx）默认缓冲响应，SSE 会看起来"一直没数据"
+    'X-Accel-Buffering': 'no',
+  });
+  try {
+    res.write('retry: 1000\n\n');
+    res.write(`event: snapshot\ndata: ${JSON.stringify(snapshotOf(store))}\n\n`);
+  } catch {
+    try { res.end(); } catch { /* 忽略 */ }
+    return;
+  }
+  store.clients.add(res);
+  const hb = setInterval(() => {
+    try { res.write(': ping\n\n'); } catch { /* 由 close 清理 */ }
+  }, HEARTBEAT_MS);
+  const bye = () => {
+    clearInterval(hb);
+    store.clients.delete(res);
+    try { res.end(); } catch { /* 已断开 */ }
+  };
+  if (req && typeof req.on === 'function') {
+    req.on('close', bye);
+    req.on('error', bye);
+  }
+}
+
+/**
+ * 创建就绪信号状态机。
+ * @returns {{apply: Function, snapshot: Function, subscribe: Function, reset: Function}}
+ */
+export function createReady() {
+  const store = { stages: new Map(), rev: 0, clients: new Set() };
+  return {
+    apply: (body) => applyUpdates(store, body),
+    snapshot: (stage) => snapshotOf(store, stage),
+    subscribe: (req, res) => subscribeSse(store, req, res),
+    /** 清空（测试用；rev 复位） */
+    reset: () => { store.stages = new Map(); store.rev = 0; },
+  };
+}