@evandu/super-pi 0.1.137 → 0.1.139

package/scripts/diagnose.mjs

@@ -1,31 +1,154 @@
-// `super_pi diagnose` — where the time goes when a message is slow.
-//
-// WHY THIS EXISTS AND WHY IT IS A COMMAND. The complaint that produced it was "it is slow, take this
-// many seconds, here are three of them" — and answering it from the developer's machine was wrong
-// twice, because the developer machine is fast and a wall clock does not transfer. So the measurement
-// has to run where the problem is, which means it has to ship with the product.
-//
-// WHAT IT PRINTS, AND WHY THAT SHAPE. Three spans, because they belong to DIFFERENT OWNERS and
-// conflating them is how two wrong root causes got written down:
-//
-//   1. picker data      -> Super Pi   (the catalog read)
-//   2. send -> waiting  -> Super Pi   (session build + first prompt)
-//   3. waiting -> text  -> the MODEL  (not ours, and it grows with the conversation)
-//
-// And under each, the STRUCTURE — how many Pi processes were started, how many sessions were built,
-// how many were reused. Structure is the part that survives the difference between a fast machine and a
-// slow one; seconds are not. If the process count is zero and a span is still long, the time is not in
-// Super Pi, and this says so rather than leaving it to be guessed at.
+// `super_pi diagnose`: local runtime probe, or --url read-only network probe from THIS machine.
+// Each report names what was observed. A loopback span cannot exonerate a remote transport, a
+// process count cannot assign latency, and stored JSON is not compressed wire traffic.
 import { spawn } from "node:child_process";
 import { mkdtempSync, rmSync, existsSync, statSync, readFileSync } from "node:fs";
 import { homedir, tmpdir } from "node:os";
 import { join } from "node:path";
 import { pathToFileURL } from "node:url";
 import { createRequire } from "node:module";
+import { request as httpRequest } from "node:http";
+import { request as httpsRequest } from "node:https";
+import { hostname } from "node:os";
+import { gunzipSync, inflateSync, brotliDecompressSync } from "node:zlib";
 
-/** The Node version Pi requires. Below it, module loading and jiti transpiling are measurably slower. */
+/** Compatibility requirement, not evidence of the cause of any measured delay. */
 const PI_NODE_REQUIREMENT = "22.19.0";
 
+export function parseDiagnoseArgs(args) {
+  const result = {};
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (/^\d+$/.test(arg) && result.turns === undefined) { result.turns = Number(arg); continue; }
+    const [name, ...inline] = arg.split("=");
+    const key = { "--url": "url", "--workspace": "workspaceId", "--conversation": "conversationId" }[name];
+    if (!key) throw new Error(`Unknown diagnose option: ${name}`);
+    const value = inline.length ? inline.join("=") : args[++i];
+    if (!value || value.startsWith("--")) throw new Error(`Missing value for ${name}`);
+    result[key] = value;
+  }
+  if (!result.url && (result.workspaceId || result.conversationId)) throw new Error("--workspace/--conversation require --url");
+  return result;
+}
+
+/** Raw encoded HTTP body bytes: fetch() transparently decompresses and cannot measure this. */
+function measureHttp(url, headers, timeoutMs) {
+  return new Promise((resolve, reject) => {
+    const start = performance.now();
+    const req = (url.protocol === "https:" ? httpsRequest : httpRequest)(url, { headers, agent: false }, response => {
+      const headersMs = performance.now() - start;
+      const chunks = [];
+      let encodedBodyBytes = 0;
+      response.on("data", chunk => {
+        encodedBodyBytes += chunk.length;
+        if (encodedBodyBytes > 64 * 1024 * 1024) req.destroy(new Error("HTTP sample exceeds 64 MiB"));
+        else chunks.push(chunk);
+      });
+      response.on("error", reject);
+      response.on("end", () => {
+        try {
+          const completeMs = performance.now() - start;
+          const encoded = Buffer.concat(chunks);
+          const encoding = response.headers["content-encoding"] ?? "identity";
+          const opts = { maxOutputLength: 64 * 1024 * 1024 };
+          const body = encoding === "gzip" ? gunzipSync(encoded, opts) : encoding === "deflate" ? inflateSync(encoded, opts)
+            : encoding === "br" ? brotliDecompressSync(encoded, opts) : encoded;
+          if (response.statusCode !== 200) throw new Error(`HTTP ${response.statusCode}; redirects are not followed`);
+          resolve({ headersMs, bodyMs: completeMs - headersMs, completeMs, encodedBodyBytes, decodedBodyBytes: body.length, encoding, body: JSON.parse(body.toString()) });
+        } catch (error) { reject(error); }
+      });
+    });
+    const timer = setTimeout(() => req.destroy(new Error("HTTP probe deadline exceeded")), timeoutMs);
+    req.on("close", () => clearTimeout(timer));
+    req.on("error", reject);
+    req.end();
+  });
+}
+
+/** Read-only probe from THIS computer to an existing server. Never sends application commands. */
+export async function diagnoseRemote({ url, workspaceId, conversationId, token = process.env.SUPER_PI_ACCESS_TOKEN, timeoutMs = 15000 } = {}) {
+  const target = new URL(url);
+  if (!["http:", "https:"].includes(target.protocol) || target.username || target.password || target.search || target.hash || target.pathname !== "/") {
+    throw new Error("--url must be an http(s) origin without credentials, path, query or fragment");
+  }
+  const loopback = ["localhost", "127.0.0.1", "[::1]"].includes(target.hostname);
+  const result = { mode: "remote", origin: `${hostname()} (${process.platform})`, target: target.origin, loopback };
+  const headers = { "accept-encoding": "gzip", ...(token ? { authorization: `Bearer ${token}` } : {}) };
+  try {
+    const { body: health, ...measurement } = await measureHttp(new URL("/api/health", target), headers, timeoutMs);
+    if (health.service !== "super-pi") throw new Error("Target is not a Super Pi health endpoint");
+    result.health = measurement;
+    const { WebSocket } = await import("ws");
+    const endpoint = new URL("/ws", target);
+    endpoint.protocol = target.protocol === "https:" ? "wss:" : "ws:";
+    endpoint.searchParams.set("state", "focused");
+    if (conversationId) endpoint.searchParams.set("conversationId", conversationId);
+    result.websocket = await new Promise((resolve, reject) => {
+      const started = performance.now();
+      const socket = new WebSocket(endpoint, { headers, handshakeTimeout: timeoutMs, maxPayload: 64 * 1024 * 1024 });
+      const sample = { decodedMessageBytes: 0, messages: 0, pingRttMs: [] };
+      let first = false, pingStart;
+      const timer = setTimeout(() => fail(new Error("WebSocket probe deadline exceeded")), timeoutMs);
+      function fail(error) { clearTimeout(timer); socket.terminate(); reject(error); }
+      socket.on("error", fail);
+      socket.once("close", () => { if (sample.pingRttMs.length !== 3) fail(new Error("WebSocket closed before probe completed")); });
+      socket.on("open", () => { sample.upgradeMs = performance.now() - started; sample.compression = socket.extensions || "none"; });
+      socket.on("message", raw => {
+        sample.messages++;
+        sample.decodedMessageBytes += raw.length;
+        try {
+          const event = JSON.parse(raw.toString());
+          if (!first && event.type === "state") {
+            first = true;
+            sample.firstStateMs = performance.now() - started;
+            sample.stateJsonBytes = raw.length;
+            pingStart = performance.now(); socket.ping("diagnose-0");
+          }
+        } catch (error) { fail(error); }
+      });
+      socket.on("pong", raw => {
+        if (raw.toString() !== `diagnose-${sample.pingRttMs.length}`) return;
+        sample.pingRttMs.push(performance.now() - pingStart);
+        if (sample.pingRttMs.length < 3) { pingStart = performance.now(); socket.ping(`diagnose-${sample.pingRttMs.length}`); return; }
+        // Includes HTTP upgrade, WS headers, catalogues and pongs, before closing. This is NOT an
+        // individual state frame size, nor Ethernet/TCP/TLS overhead. Label the counter honestly.
+        sample.socketInputBytes = socket._socket.bytesRead;
+        sample.sampleMs = performance.now() - started;
+        clearTimeout(timer); socket.terminate(); resolve(sample);
+      });
+    });
+    if (workspaceId) {
+      const indexUrl = new URL("/api/files/index", target);
+      indexUrl.searchParams.set("workspaceId", workspaceId);
+      const { body: _index, ...index } = await measureHttp(indexUrl, headers, timeoutMs);
+      result.fileIndex = index;
+    }
+  } catch (error) { result.error = error instanceof Error ? error.message : String(error); }
+  return result;
+}
+
+function renderRemoteReport(result) {
+  const lines = ["Super Pi 远程链路诊断（只读）", `  探针位置：${result.origin}`, `  目标：${result.target}`,
+    `  路径：${result.loopback ? "回环地址，未覆盖其他电脑的访问路径" : "此电脑到目标；请在发生问题的客户端电脑执行"}`];
+  const http = (name, sample) => {
+    if (!sample) return;
+    lines.push(`  ${name}: 收到响应头 ${sample.headersMs.toFixed(1)}ms，响应体传输 ${sample.bodyMs.toFixed(1)}ms，总计 ${sample.completeMs.toFixed(1)}ms`);
+    lines.push(`    编码后响应体 ${sample.encodedBodyBytes} B，解码后 ${sample.decodedBodyBytes} B，编码 ${sample.encoding}`);
+  };
+  http("health", result.health);
+  if (result.websocket) {
+    const ws = result.websocket;
+    lines.push(`  WS: upgrade ${ws.upgradeMs.toFixed(1)}ms，首个 focused state ${ws.firstStateMs.toFixed(1)}ms，state JSON ${ws.stateJsonBytes} B`);
+    lines.push(`    socket 输入 ${ws.socketInputBytes} B，解码后消息合计 ${ws.decodedMessageBytes} B，压缩 ${ws.compression}`);
+    lines.push(`    Ping RTT: ${ws.pingRttMs.map(n => n.toFixed(1) + "ms").join(", ")}`);
+  }
+  http("文件索引（显式指定 workspace）", result.fileIndex);
+  if (result.error) lines.push(`  失败：${result.error}`);
+  lines.push("  范围：响应头等待包含网络与服务端处理，不能当作纯服务端耗时。socket 输入含 upgrade/WS 帧，未计 IP/TCP/TLS 开销。");
+  lines.push("  未测：浏览器点击/解析/绘制、创建/停止/撤回、模型调用；未创建会话或发送业务命令。小样本不能推算链路带宽。");
+  return lines.join("\n");
+}
+
 /**
  * Compares two dotted versions.
  *
@@ -43,22 +166,9 @@ function atLeast(actual, required) {
 }
 
 /**
- * How big the REAL state is, and what a full write of it costs.
- *
- * WHY THIS IS HERE AND NOT IN THE MEASUREMENT ABOVE. The measurement above runs against a THROWAWAY
- * data directory, so its state is empty and its writes are instant - which is exactly why it could
- * not see the thing it was looking for. A real server holds every conversation a person has ever had,
- * and a message used to cost a full write of all of it before the browser was told the turn had
- * started. The size of that state is invisible from a fresh install and decisive on a real one, so it
- * is reported from the REAL data directory, read-only, and the write is measured on a COPY.
- *
- * THE NUMBER THAT MATTERS IS THE STATE, NOT THE FILE. An earlier version of this report called the
- * SQLite FILE size "the state", and that is a different number: the file holds the base snapshot AND
- * the incremental overlay tables, and the overlay is never pruned, so the file grows with every write
- * while the state the BROWSER RECEIVES does not grow the same way. The number that costs time is the
- * one that is cloned (`store.snapshot()`), serialised (`JSON.stringify`) and parsed (`JSON.parse` in
- * the browser) on every state broadcast - so that is what is measured here, by rebuilding the state
- * out of the database and measuring its JSON.
+ * Read-only storage context. A fresh throwaway server cannot reveal real history size. Rebuild
+ * logical state via the repository layout, but never label that JSON as actual browser traffic:
+ * focused projection, per-message compression and transport overhead produce different sizes.
  */
 function measureRealState(dataDir) {
   const result = { path: "", bytes: 0, fileBytes: 0, conversations: 0, messages: 0, fullWriteMs: undefined };
@@ -72,20 +182,18 @@ function measureRealState(dataDir) {
         const parsed = JSON.parse(readFileSync(path, "utf8"));
         result.conversations = parsed.conversations?.length ?? 0;
         result.messages = (parsed.conversations ?? []).reduce((sum, c) => sum + (c.messages?.length ?? 0), 0);
-        // THE SIZE THAT IS ACTUALLY SENT. The browser gets this JSON, not the file.
-        result.bytes = Buffer.byteLength(readFileSync(path, "utf8"), "utf8");
+        // Logical storage state, not a focused projection or compressed network measurement.
+        result.bytes = Buffer.byteLength(JSON.stringify(parsed), "utf8");
       } else {
         // THE SQLITE STATE, REBUILT AND MEASURED. The repository's own loader is the authority on what
         // the state IS, so the report does not guess at it: the database is opened READ-ONLY, the
         // overlays are folded onto the base snapshot the way `load()` folds them, and the result is
-        // measured as JSON - the same bytes a state broadcast carries.
+        // measured as JSON. The browser's scoped projection and compression are separate measurements.
         const measured = measureSqliteState(path);
         if (measured.bytes > 0) {
           result.bytes = measured.bytes;
           result.conversations = measured.conversations;
           result.messages = measured.messages;
-        } else {
-          result.bytes = result.fileBytes;
         }
       }
     } catch { /* unreadable is not a fact worth reporting */ }
@@ -400,10 +508,13 @@ export async function diagnose({ repositoryRoot, turns = 2, onProgress = () => {
 
 /** Renders a diagnosis as the report a person reads. */
 export function renderReport(result) {
+  if (result.mode === "remote") return renderRemoteReport(result);
   const lines = [];
   const ms = (value) => (typeof value === "number" ? `${String(value).padStart(6)}ms` : "     ?");
 
   lines.push(`Super Pi 延迟诊断 — ${new Date().toISOString()}`);
+  lines.push("  测量范围：本机临时 server + 回环连接；未测用户电脑到云服务器的网络，也未测浏览器点击/绘制。");
+  lines.push("  远程访问请在客户端电脑运行：super_pi diagnose --url http://SERVER:3080");
   lines.push("");
   lines.push(`  Node ${result.node}   (Pi 要求 >= ${result.required}：${result.nodeOk ? "满足" : "过低"})`);
   lines.push(`  server 就绪耗时 ${ms(result.bootMs)}`);
@@ -426,7 +537,7 @@ export function renderReport(result) {
   }
   for (const turn of result.turns ?? []) {
     lines.push(`     第${turn.turn}轮 发送 -> 等待中     ${ms(turn.toWaitingMs)}   Super Pi   （建会话 + 首个 prompt）`);
-    lines.push(`     第${turn.turn}轮 等待中 -> 出字     ${ms(turn.modelMs)}   模型       （不是 Super Pi）`);
+    lines.push(`     第${turn.turn}轮 等待中 -> 出字     ${ms(turn.modelMs)}   首字等待   （包含 runtime、供应商及传输，未单独归因）`);
   }
   if (result.interrupt) {
     if (Array.isArray(result.interruptTrace) && result.interruptTrace.length) {
@@ -438,7 +549,7 @@ export function renderReport(result) {
     lines.push("  打断（点「打断并回答」之后）：");
     lines.push(`     点击 -> 新一轮报等待中     ${ms(result.interrupt.toWaitingMs)}   Super Pi   （等旧轮退完 + 等槽位）`);
     lines.push(`     点击 -> 出字             ${ms(result.interrupt.toTextMs)}   整条链`);
-    lines.push(`     其中模型                 ${ms(result.interrupt.modelMs)}   模型       （不是 Super Pi）`);
+    lines.push(`     其中首字等待             ${ms(result.interrupt.modelMs)}   runtime/供应商/传输，未单独归因`);
     lines.push(`     打断后启动的 Pi 进程数： ${result.interrupt.spawned}`);
   } else {
     lines.push("");
@@ -459,8 +570,7 @@ export function renderReport(result) {
   if (result.systemPromptBytes) {
     lines.push("");
     lines.push(`  发给模型的系统提示：${(result.systemPromptBytes / 1024).toFixed(1)}KB`);
-    lines.push("  这是每一轮都要先传过去的东西。模型的 provider 得先收下它才能回答，");
-    lines.push("  所以在慢链路上，它直接就是首字之前的那几秒。");
+    lines.push("  这是逻辑提示体积；供应商协议、压缩、缓存和网络吞吐未在此测量，不能据此换算首字延迟。");
   }
 
   const real = result.realState;
@@ -468,33 +578,26 @@ export function renderReport(result) {
     lines.push("");
     lines.push("  你真实的 state（上面那些数字是在一个全新的空目录上量的，看不到它）：");
     lines.push(`    ${real.path}`);
-    const megabytes = (real.bytes / 1024 / 1024).toFixed(2);
+    const megabytes = real.bytes ? (real.bytes / 1024 / 1024).toFixed(2) : "未测";
     const shape = real.conversations ? `，${real.conversations} 个会话，${real.messages} 条消息` : "";
-    lines.push(`    浏览器每次收到的那份 state：${megabytes}MB${shape}`);
+    lines.push(`    存储状态重建后的 JSON：${real.bytes ? megabytes + "MB" : megabytes}${shape}（不是浏览器传输量）`);
     if (real.fileBytes && real.fileBytes !== real.bytes) {
       lines.push(`    数据库文件本身：${(real.fileBytes / 1024 / 1024).toFixed(2)}MB`);
-      lines.push("    （文件比 state 大是因为它还存着增量写的那几层，那些层从不被清理；");
-      lines.push("      真正花时间的是上面那个数字——每次广播都要克隆它、序列化它、");
-      lines.push("      再在浏览器里解析一遍。）");
+      lines.push("    （数据库含基础快照和增量表；磁盘体积、重建 JSON、focused JSON 与压缩传输量必须分开。）");
     }
     if (real.bytes > 1024 * 1024) {
-      lines.push("    这个体积的 state 每变一次就要整份克隆 + 整份序列化 + 浏览器整份解析，");
-      lines.push("    在慢机器上每一次广播都是秒级，而一轮里会广播好几次。");
+      lines.push("    全量状态很大时，应检查克隆/持久化成本；现代 focused 客户端只收摘要与选中详情，不能据全库大小断言远程耗时。");
     }
   }
 
 
   lines.push("");
   if (!result.nodeOk) {
-    lines.push(`  Node 版本低于 Pi 的要求（>= ${result.required}）。这一条本身就可能解释了前面几段的`);
-    lines.push("  大部分时间：模块加载和 jiti 转译都会更慢。请先升级 Node 再跑一次——否则这份报告");
-    lines.push("  描述的是一台 Pi 本来就不该在上面运行的机器。");
+    lines.push(`  Node 版本低于 Pi 的要求（>= ${result.required}）。请升级 Node 以满足兼容要求；版本不匹配本身不能证明延迟根因。`);
     lines.push("");
   }
   lines.push("  怎么看这份报告：");
-  lines.push("    - 「启动的 Pi 进程数」是最关键的那个数。它是 0，说明 Super Pi 正在用 Pi 的 SDK，");
-  lines.push("      会话被复用了；如果每一轮都很大，说明会话层根本没生效。");
-  lines.push("    - 第 1、2 段是 Super Pi 自己的。如果这两段是秒级，这份报告就是该发出来的东西。");
-  lines.push("    - 第 3 段是模型，会随对话变长。Super Pi 改不了它。");
+  lines.push("    - 进程数与会话构建/复用数说明执行结构，零进程不代表零开销或已经复用。");
+  lines.push("    - 各阶段是本机探针观察值；未结合跨机器传输和浏览器 trace 时，不能排除 Super Pi 或网络。");
   return lines.join("\n");
 }