@glittering0717/ai-browser 1.2.2 → 1.3.0

package/scripts/marketing/data_snapshot.sh

@@ -0,0 +1,69 @@
+#!/bin/bash
+# data_snapshot.sh — ai-browser 推广数据每日快照
+# 用法：bash scripts/marketing/data_snapshot.sh [备注]
+# 输出：追加一行到 docs/marketing/DATA_LOG.md
+set -u
+REPO="/Users/Zhuanz/Documents/trae_projects/ai-browser"
+LOG="$REPO/docs/marketing/DATA_LOG.md"
+DATE=$(date +%Y-%m-%d)
+TIME=$(date +%H:%M)
+NOTE="${1:-}"
+
+jqf() { # jqf <gh-api-path> <jq-filter> <default>
+  local out
+  out=$(gh api "$1" --jq "$2" 2>/dev/null) || out=""
+  [ -z "$out" ] && out="$3"
+  echo "$out"
+}
+
+# --- GitHub ---
+STARS=$(jqf "repos/Glittering/ai-browser" '.stargazers_count' '?')
+FORKS=$(jqf "repos/Glittering/ai-browser" '.forks_count' '?')
+ISSUES=$(jqf "repos/Glittering/ai-browser" '.open_issues_count' '?')
+VIEWS14=$(jqf "repos/Glittering/ai-browser/traffic/views" '.count' '?')
+UNIQ14=$(jqf "repos/Glittering/ai-browser/traffic/views" '.uniques' '?')
+CLONES14=$(jqf "repos/Glittering/ai-browser/traffic/clones" '.count' '?')
+CLONEU14=$(jqf "repos/Glittering/ai-browser/traffic/clones" '.uniques' '?')
+
+# --- npm ---
+NPM_VER=$(curl -s --max-time 15 "https://registry.npmjs.org/@glittering0717%2Fai-browser" 2>/dev/null | python3 -c "import json,sys; print(json.load(sys.stdin)['dist-tags']['latest'])" 2>/dev/null || echo '?')
+NPM_DL=$(curl -s --max-time 15 "https://api.npmjs.org/downloads/point/last-week/@glittering0717/ai-browser" 2>/dev/null | python3 -c "import json,sys; d=json.load(sys.stdin); print(d.get('downloads','N/A'))" 2>/dev/null || echo 'N/A')
+
+# --- MCP Registry（取 isLatest 条目；API 偶发超时，带重试）---
+mcp_fetch() {
+  for i in 1 2 3; do
+    local out
+    out=$(curl -s --max-time 20 "https://registry.modelcontextprotocol.io/v0/servers?search=ai-browser" 2>/dev/null)
+    if [ -n "$out" ] && echo "$out" | python3 -c "import json,sys; json.load(sys.stdin)" 2>/dev/null; then
+      echo "$out"
+      return 0
+    fi
+    sleep 2
+  done
+  echo ""
+}
+MCP_INFO=$(mcp_fetch | python3 -c "
+import json,sys
+try:
+    d=json.load(sys.stdin)
+    for item in d.get('servers',[]):
+        s=item.get('server',{})
+        if s.get('name')=='io.github.Glittering/ai-browser':
+            m=item.get('_meta',{}).get('io.modelcontextprotocol.registry/official',{})
+            if m.get('isLatest'):
+                print(s.get('version','?'), m.get('status','?'))
+                break
+except Exception:
+    pass
+" 2>/dev/null)
+MCP_VER=$(echo "$MCP_INFO" | awk '{print $1}')
+MCP_STATUS=$(echo "$MCP_INFO" | awk '{print $2}')
+[ -z "$MCP_VER" ] && MCP_VER='?'
+[ -z "$MCP_STATUS" ] && MCP_STATUS='?'
+
+# --- 文章渠道状态（经 ai-browser 巡查时更新；此处留空由人工/agent 回填）---
+printf '| %s %s | %s | %s | %s | %s | %s | %s | %s | %s | %s | %s | %s |\n' \
+  "$DATE" "$TIME" "$STARS" "$FORKS" "$ISSUES" "$VIEWS14" "$UNIQ14" "$CLONES14/$CLONEU14" "$NPM_VER" "$NPM_DL" "$MCP_VER" "$MCP_STATUS" "${NOTE:-}" >> "$LOG"
+
+echo "快照已写入 $LOG"
+tail -1 "$LOG"

package/scripts/render_icon.cjs

@@ -0,0 +1,118 @@
+#!/usr/bin/env node
+// scripts/render_icon.cjs — 从 build/icon.svg 一键重建整条图标链：
+//   SVG → 2048×2048 PNG（icon@2x.png）→ 1024 PNG（icon.png）
+//       → icon.iconset/（10 个尺寸）→ icon.icns（packager 的输入）
+//
+// # 为什么不用 qlmanage / rsvg-convert / ImageMagick
+//   qlmanage 在受限沙箱里直接 "sandbox initialization failed: Operation not permitted"；
+//   rsvg-convert / convert / inkscape 本机都没装。为一个图标引入一串系统依赖不划算。
+//   而本项目**本来就自带一个完整的 Chromium**（electron 依赖），拿它渲染 SVG 是天经地义的事，
+//   零新增依赖，且渲染结果和图标最终运行的引擎完全一致。
+//
+// # 为什么 icns 要提交、中间 png 不提交
+//   build_dmg.cjs 的 icon 选项只读 build/icon.icns；icon.svg 是母版；
+//   其余 png/iconset 都是本脚本的再生产物，改了 SVG 重跑本脚本即可。
+//
+// # 用法（必须在 Electron 下运行，不是 node；本沙箱还要 --no-sandbox --disable-gpu）
+//   env -u ELECTRON_RUN_AS_NODE \
+//     node_modules/electron/dist/Electron.app/Contents/MacOS/Electron \
+//     --no-sandbox --disable-gpu scripts/render_icon.cjs
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+
+const ROOT = path.resolve(__dirname, '..');
+const SVG = path.join(ROOT, 'build', 'icon.svg');
+const PNG_2X = path.join(ROOT, 'build', 'icon@2x.png'); // 2048×2048，母版位图
+const PNG = path.join(ROOT, 'build', 'icon.png'); //    1024×1024，预览用
+const ICONSET = path.join(ROOT, 'build', 'icon.iconset');
+const ICNS = path.join(ROOT, 'build', 'icon.icns');
+
+// icns 要求的全部尺寸（源图是 2048²，一律从它缩）
+const SIZES = [
+  [16, 'icon_16x16.png'],
+  [32, 'icon_16x16@2x.png'],
+  [32, 'icon_32x32.png'],
+  [64, 'icon_32x32@2x.png'],
+  [128, 'icon_128x128.png'],
+  [256, 'icon_128x128@2x.png'],
+  [256, 'icon_256x256.png'],
+  [512, 'icon_256x256@2x.png'],
+  [512, 'icon_512x512.png'],
+  [1024, 'icon_512x512@2x.png'],
+];
+
+// 在普通 node 下 require('electron') 拿到的是二进制路径字符串，提前拦掉给出提示
+let electron;
+try {
+  electron = require('electron');
+} catch (_) {
+  electron = null;
+}
+if (!electron || typeof electron.app === 'undefined') {
+  console.error('[icon] 本脚本必须在 Electron 下运行（见文件头用法），node 直接跑不了。');
+  process.exit(2);
+}
+
+const { app, BrowserWindow } = electron;
+
+app.commandLine.appendSwitch('disable-gpu'); // 无头环境没有 GL，别让 GPU 进程拖后腿
+
+function run(cmd, args) {
+  const r = spawnSync(cmd, args, { cwd: ROOT });
+  if (r.status !== 0) {
+    throw new Error(`${cmd} ${args.join(' ')} exited with code ${r.status}`);
+  }
+}
+
+app.whenReady().then(async () => {
+  // 窗口 1024，capturePage 在 Retina 下返回 2x（2048×2048）——这就是母版位图
+  const SIZE = 1024;
+  const win = new BrowserWindow({
+    width: SIZE,
+    height: SIZE,
+    show: false,
+    transparent: true,
+    backgroundColor: '#00000000',
+    useContentSize: true,
+    webPreferences: { offscreen: false },
+  });
+
+  try {
+    await win.loadFile(SVG);
+    // 等一帧，确保 SVG 已经完成布局与绘制（loadFile 只保证 DOM ready）
+    await new Promise((r) => setTimeout(r, 300));
+
+    const img = await win.webContents.capturePage();
+    if (img.isEmpty()) throw new Error('capturePage returned an empty image');
+
+    const png = img.toPNG();
+    fs.writeFileSync(PNG_2X, png);
+    const w = img.getSize().width;
+    const h = img.getSize().height;
+    console.log(`[icon] ${path.relative(ROOT, SVG)} -> ${path.relative(ROOT, PNG_2X)} (${w}x${h}, ${png.length} bytes)`);
+
+    // ---- 以下三步是 macOS 自带工具，不联网、不加依赖 ----
+    // 1) 1024 预览图
+    run('sips', ['-Z', '1024', PNG_2X, '-o', PNG]);
+    // 2) 10 个 icns 尺寸
+    fs.rmSync(ICONSET, { recursive: true, force: true });
+    fs.mkdirSync(ICONSET, { recursive: true });
+    for (const [size, name] of SIZES) {
+      run('sips', ['-Z', String(size), PNG_2X, '-o', path.join(ICONSET, name)]);
+    }
+    // 3) 打 icns
+    fs.rmSync(ICNS, { force: true });
+    run('iconutil', ['-c', 'icns', ICONSET, '-o', ICNS]);
+
+    const icnsSize = fs.statSync(ICNS).size;
+    console.log(`[icon] iconset: ${SIZES.length} sizes -> ${path.relative(ROOT, ICNS)} (${icnsSize} bytes)`);
+    console.log('[icon] done. build_dmg.cjs 会读取 build/icon.icns');
+    app.exit(0);
+  } catch (e) {
+    console.error(`[icon] FAILED: ${e.message}`);
+    app.exit(1);
+  }
+});

package/src/main/axExtractor.js

@@ -72,8 +72,23 @@ function statesFor(node) {
     if (!v || v.type !== 'boolean' || v.value !== true) continue;
     if (p.name === 'read-only') { states.push('readonly'); continue; }
     if (p.name === 'hidden') continue;
+    // required 在下面单独处理（要给出与 DOM 路径同一份语义）。这里跳过，
+    // 否则 states 里会出现两个 "required"。
+    if (p.name === 'required') continue;
+    if (p.name === 'invalid') continue; // 字符串属性，下面单独处理
     states.push(p.name); // focusable/disabled/focused/checked/selected/settable/multiline/visible...
   }
+  // 必填 / 无效（P2-2）。AX 把 aria-required 和原生 required 都折成 `required`，
+  // 把 aria-invalid 折成 `invalid`（字符串：false | true | grammar | spelling）。
+  // 这两个信号此前完全不在 states 里，于是"掘金红*必填"和"字段已判错"都只能靠
+  // 截图猜 —— 而红色星号在无样式/色盲场景下本来就不是可靠信号。
+  const req = prop(nodeStore, node.nodeId, 'required');
+  if (req && req.value === true) states.push('required');
+  const invalid = prop(nodeStore, node.nodeId, 'invalid');
+  if (invalid && typeof invalid.value === 'string' && invalid.value !== 'false') {
+    states.push('invalid');
+    if (invalid.value !== 'true') states.push('invalid=' + invalid.value); // grammar / spelling
+  }
   // raw `editable` stays available to callers that need the primitive signal
   const editable = nodeStore ? valueOf(prop(nodeStore, node.nodeId, 'editable')) : null;
   if (editable) states.push('editable=' + editable);
@@ -81,6 +96,27 @@ function statesFor(node) {
 }
 
 let nodeStore = null; // current normalize pass's node map (see normalizeAxTree)
+// Nodes already emitted in this pass. Needed because we walk *through* ignored
+// wrappers (§buildThroughIgnored); an AX node that a wrapper re-parents must not
+// be emitted twice.
+let seenNodes = null;
+
+// Descendants of an AX node that is `ignored: true`. AX marks presentational
+// wrappers (a `span` in a flex row, `<b>` inside a paragraph) as ignored, but
+// the text under them is real content — dropping the wrapper must not drop the
+// subtree. This is the P2-1 cause: a list row's title lives in such a span, so
+// the row came back as `[button] 编辑` and nothing else.
+function buildThroughIgnored(node, idFor) {
+  const out = [];
+  for (const cid of node.childIds || []) {
+    const c = nodeStore.get(cid);
+    if (!c || seenNodes.has(c.nodeId)) continue;
+    if (c.ignored) { out.push(...buildThroughIgnored(c, idFor)); continue; }
+    seenNodes.add(c.nodeId);
+    out.push(build(c, idFor));
+  }
+  return out;
+}
 
 function build(node, idFor) {
   const rawRole = (node.role && node.role.value) || 'generic';
@@ -130,7 +166,12 @@ function build(node, idFor) {
   const kids = [];
   for (const cid of node.childIds || []) {
     const c = nodeStore.get(cid);
-    if (c && !c.ignored) kids.push(build(c, idFor));
+    if (!c || seenNodes.has(c.nodeId)) continue;
+    // 被 AX 标为 ignored 的只是包裹层（见 buildThroughIgnored）；它的子节点
+    // 才是内容，必须被提升上来而不是连同子树一起丢掉。
+    if (c.ignored) { kids.push(...buildThroughIgnored(c, idFor)); continue; }
+    seenNodes.add(c.nodeId);
+    kids.push(build(c, idFor));
   }
   if (kids.length) tn.children = kids;
   return tn;
@@ -141,21 +182,41 @@ let readValue = null; // opts.readValue — per-node DOM read hook for textbox v
 // Public pure API.
 // opts: { idFor: (node)=>string, readValue: (node)=>string }
 export function normalizeAxTree(rawNodes, opts = {}) {
-  const live = (rawNodes || []).filter((n) => n && !n.ignored);
-  nodeStore = new Map(live.map((n) => [n.nodeId, n]));
+  // nodeStore keeps ignored nodes too: we never *emit* them, but we must walk
+  // through them (see buildThroughIgnored). Indexing only the live ones was the
+  // second half of the P2-1 bug — the wrapper was in the map lookup's blind spot
+  // and its children became unreachable.
+  const all = (rawNodes || []).filter(Boolean);
+  const live = all.filter((n) => !n.ignored);
+  nodeStore = new Map(all.map((n) => [n.nodeId, n]));
+  seenNodes = new Set();
   readValue = opts.readValue || null;
   const idFor = opts.idFor || ((n) => 'ax-' + n.nodeId);
 
-  const childIds = new Set();
-  for (const n of live) for (const c of n.childIds || []) if (c != null) childIds.add(c);
-  const roots = live.filter((n) => !childIds.has(n.nodeId));
+  // Parent map over ALL nodes, so "is this a root?" accounts for ignored
+  // ancestors: a live node under an ignored wrapper is not a root.
+  const parentOf = new Map();
+  for (const n of all) for (const c of n.childIds || []) if (c != null && !parentOf.has(c)) parentOf.set(c, n.nodeId);
+  const hasLiveAncestor = (n) => {
+    let p = parentOf.get(n.nodeId); let guard = 0;
+    while (p != null && guard++ < 64) {
+      const pn = nodeStore.get(p);
+      if (!pn) return false;
+      if (!pn.ignored) return true;
+      p = parentOf.get(p);
+    }
+    return false;
+  };
+  const roots = live.filter((n) => !hasLiveAncestor(n));
 
+  for (const r of roots) seenNodes.add(r.nodeId);
   const built = roots.map((n) => build(n, idFor));
   const tree = built.length === 1
     ? built[0]
     : { id: 'root', role: 'generic', label: '', states: ['visible'], actions: [], bounds: { x: 0, y: 0, width: 0, height: 0 }, children: built };
   tree._debug = { layer: 'ax', version: VERSION_TAG };
   nodeStore = null;
+  seenNodes = null;
   readValue = null;
   return tree;
 }
@@ -215,8 +276,11 @@ export function mergeFrameTrees(mainTree, frames = []) {
 // AX role=dialog|alertdialog that is visible, plus its descendant buttons — the
 // AX-native replacement for the class-keyword modal table (extractor's modalSelectors).
 export function modalsFromAx(rawNodes) {
-  const live = (rawNodes || []).filter((n) => n && !n.ignored);
-  nodeStore = new Map(live.map((n) => [n.nodeId, n]));
+  const all = (rawNodes || []).filter(Boolean);
+  const live = all.filter((n) => !n.ignored);
+  // 与 normalizeAxTree 同一条规则：ignored 只是包裹层，遍历要穿过去（否则
+  // ignored span 里的按钮永远数不到）。
+  nodeStore = new Map(all.map((n) => [n.nodeId, n]));
   const dialogs = live.filter((n) => {
     const r = n.role && n.role.value;
     if (r !== 'dialog' && r !== 'alertdialog') return false;
@@ -228,7 +292,8 @@ export function modalsFromAx(rawNodes) {
     const buttons = [];
     const walk = (id) => {
       const n = nodeStore.get(id);
-      if (!n || n.ignored) return;
+      if (!n) return;
+      if (n.ignored) { for (const cid of n.childIds || []) walk(cid); return; }
       const r = n.role && n.role.value;
       if (r === 'button') {
         const btn = {
@@ -279,13 +344,6 @@ async function axRaw(dbg) {
   return raw;
 }
 
-export function interactiveIdSet(raw) {
-  const byId = new Map(raw.filter((n) => !n.ignored).map((n) => [n.nodeId, n]));
-  const s = new Set();
-  for (const n of raw) if (!n.ignored && isInteractiveNode(n, byId)) s.add(n.nodeId);
-  return s;
-}
-
 // C: PURE READ. Same {tree, context} shape as the default getTree, but derived
 // from AX alone. No DOM mutation, ids = ax-{backendDOMNodeId} (stable).
 export async function axRead(dbg) {
@@ -330,24 +388,10 @@ export async function ensureHandles(dbg) {
   return out;
 }
 
-// A: PURE diff of two AX snapshots (pre/post a reveal) by nodeId. Returns only
-// interactive nodes that newly appeared (revealed) or disappeared (hidden).
-export function diffAx(beforeRaw, afterRaw) {
-  const bm = new Map((beforeRaw || []).map((n) => [n.nodeId, n]));
-  const am = new Map((afterRaw || []).map((n) => [n.nodeId, n]));
-  const bi = interactiveIdSet(beforeRaw || []);
-  const ai = interactiveIdSet(afterRaw || []);
-  const toLite = (n) => ({
-    id: axId(n),
-    role: (n.role && n.role.value) || 'generic',
-    label: (n.name && n.name.value) || '',
-    backendDOMNodeId: n.backendDOMNodeId != null ? n.backendDOMNodeId : undefined,
-  });
-  const revealed = [], hidden = [];
-  for (const id of ai) if (!bi.has(id)) { const n = am.get(id); if (n && !n.ignored) revealed.push(toLite(n)); }
-  for (const id of bi) if (!ai.has(id)) { const n = bm.get(id); if (n && !n.ignored) hidden.push(toLite(n)); }
-  return { revealed, hidden };
-}
+// 注意：这里原本有基于 AX 的 diffAx（ui.peek 用的差异比较）。它已删除，原因是
+// 自绘菜单在 AX 里是"无名的 generic"、进不了 isInteractiveNode 的判据，peek 因此
+// 对这类菜单一律报空；且它返回的 ax-* id 动作层解析不了，探到了也点不了。
+// ui.peek 现在改用 DOM 语义树做差异，实现在 src/shared/tree_diff.cjs。
 
 // C: read-only href resolution for actionable nodes. The AX read layer only knows
 // "this is clickable", not "where it goes" (AX has no href). We lazily decorate
@@ -386,6 +430,24 @@ export async function attachHrefs(dbg, tree) {
 // descendants); drops layout-only branches. Pure and generic (role/actions
 // based, no site heuristics) — the read-lowering mode for long feeds.
 function isInteractive(tree) { return !!tree.editor_type || (tree.actions && tree.actions.length > 0) || !!tree.url; }
+
+// 行容器（列表项 / 表格行 / 树项）在 prune 后常常只剩一个操作按钮：
+// 标题是被剪掉的纯文本，而**纯文本正是"这是哪一行"的唯一线索**。B站稿件
+// 管理列表因此每行只剩 `[button] 编辑`，无法定位目标条目（P2-1）。
+// 对这类角色，若剪完 label 为空，就把首个文本后代的文字提升成行 label。
+const ROW_ROLES = { listitem: 1, row: 1, treeitem: 1, cell: 1, gridcell: 1, article: 1 };
+const MAX_ROW_LABEL = 120;
+function firstTextOf(node) {
+  if (!node) return '';
+  const role = node.role || '';
+  if (role === 'StaticText' || role === 'InlineTextBox') return String(node.label || '').trim();
+  for (const c of node.children || []) {
+    const t = firstTextOf(c);
+    if (t) return t;
+  }
+  return '';
+}
+
 export function filterInteractive(tree) {
   if (!tree) return tree;
   const keep = (t) => {
@@ -393,7 +455,12 @@ export function filterInteractive(tree) {
     const kids = (t.children || []).map(keep).filter(Boolean);
     if (kids.length || isInteractive(t)) {
       if (!kids.length) return t;
-      return { ...t, children: kids };
+      const node = { ...t, children: kids };
+      if (ROW_ROLES[t.role] && !node.label) {
+        const txt = firstTextOf(t);
+        if (txt) node.label = txt.slice(0, MAX_ROW_LABEL);
+      }
+      return node;
     }
     return null;
   };
@@ -433,4 +500,4 @@ export function diffLite(prevLite, newLite) {
   return { revealed, hidden };
 }
 
-export default { normalizeAxTree, mergeFrameTrees, modalsFromAx, extractFromDebugger, axRead, axRaw, ensureHandles, diffAx, interactiveIdSet, attachHrefs, filterInteractive, liteSnapshot, diffLite, VERSION_TAG };
+export default { normalizeAxTree, mergeFrameTrees, modalsFromAx, extractFromDebugger, axRead, axRaw, ensureHandles, attachHrefs, filterInteractive, liteSnapshot, diffLite, VERSION_TAG };

package/src/main/error_log.js

@@ -0,0 +1,245 @@
+// src/main/error_log.js — 主进程错误日志（JSONL，滚动，可回读）。
+//
+// 存在理由（2026-10-17 实测）：主进程此前**一处错误处理都没有**。任何未捕获
+// 异常都走 Electron 的默认路径 —— 弹一个原生对话框（标题就是 "A JavaScript
+// error occurred in the main process"），栈只在框里、点掉就没了，进程随即退出。
+// 用户看到"弹了个框说 js 崩溃"，而事后**没有任何地方能查到它崩在哪** ——
+// 连"刚才是不是真崩过"都证不了。这不是"日志不够详细"，是根本没有。
+//
+// 三条设计约束：
+//   1. **日志本身绝不能再抛异常**。所有磁盘操作 try/catch 吞掉：为了记录崩溃
+//      而制造新崩溃，是最难查的那种 bug。
+//   2. **同步写**（appendFileSync）。异步写等到 flush 时进程可能已经没了 ——
+//      崩溃现场最需要的恰恰是最后一刻那几行。
+//   3. **异常条目自带最近的调用上下文**。只有栈是不够的：栈会告诉你崩在
+//      `selectorAncestors`，但不会告诉你"是哪个 ui.act 在什么 target 上触发的"。
+//      所以维护一个 WS 调用环形缓冲，落盘时把它一并附上。
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+// 单文件上限与保留份数。2MB ×(1+4) 对纯文本日志是几个月量级的事件量；
+// 再大就说明是循环报错，那种情况靠滚动还不如早点被看见。
+// 允许 init 时覆盖：磁盘紧张的环境可以调小，测试也靠它把滚动路径跑起来。
+const DEFAULT_MAX_BYTES = 2 * 1024 * 1024;
+const DEFAULT_KEEP = 4;
+let maxBytes = DEFAULT_MAX_BYTES;
+let keepFiles = DEFAULT_KEEP;
+// 内存里留最近多少条，供 ui.errors 直接读（不碰磁盘，快）
+const RING_MAX = 200;
+// 最近多少次 WS 调用参与"崩溃上下文"
+const CALL_RING_MAX = 40;
+// 单条日志里字符串字段的截断长度
+const FIELD_MAX = 4000;
+
+let logFile = null;
+let logDir = null;
+let wroteBytes = 0;
+let dropped = 0;
+
+const ring = [];
+const callRing = [];
+
+/** 把任意值压成"可安全 JSON.stringify 的一行摘要"。 */
+function summarize(v, depth = 0) {
+  if (v === null || v === undefined) return v;
+  const t = typeof v;
+  if (t === 'string') return v.length > FIELD_MAX ? v.slice(0, FIELD_MAX) + '…(' + v.length + ' chars)' : v;
+  if (t === 'number' || t === 'boolean') return v;
+  if (t === 'bigint') return String(v);
+  if (t === 'function') return '[function ' + (v.name || 'anonymous') + ']';
+  if (t === 'symbol') return String(v);
+  if (v instanceof Error) {
+    return { name: v.name, message: v.message, stack: String(v.stack || '').slice(0, 8000) };
+  }
+  if (depth >= 3) return Array.isArray(v) ? '[array ' + v.length + ']' : '[object]';
+  if (Array.isArray(v)) {
+    const head = v.slice(0, 12).map((x) => summarize(x, depth + 1));
+    return v.length > 12 ? head.concat(['…+' + (v.length - 12)]) : head;
+  }
+  const out = {};
+  let n = 0;
+  for (const k of Object.keys(v)) {
+    if (n++ >= 20) { out['…'] = 'more keys omitted'; break; }
+    out[k] = summarize(v[k], depth + 1);
+  }
+  return out;
+}
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+function rotateIfNeeded(nextLen) {
+  try {
+    if (!logFile) return;
+    let size = wroteBytes;
+    if (!size) {
+      try { size = fs.statSync(logFile).size; } catch { size = 0; }
+    }
+    if (size + nextLen <= maxBytes) return;
+    // error.jsonl → error.jsonl.1 → error.jsonl.2 …
+    for (let i = keepFiles - 1; i >= 1; i--) {
+      const from = i === 1 ? logFile : logFile + '.' + (i - 1);
+      const to = logFile + '.' + i;
+      try { if (fs.existsSync(from)) fs.renameSync(from, to); } catch {}
+    }
+    // 轮转后旧内容已经在 .1，当前文件从零开始
+    try { if (fs.existsSync(logFile)) fs.unlinkSync(logFile); } catch {}
+    wroteBytes = 0;
+  } catch {}
+}
+
+function appendLine(obj) {
+  const line = JSON.stringify(obj) + '\n';
+  rotateIfNeeded(Buffer.byteLength(line));
+  try {
+    fs.appendFileSync(logFile, line);
+    wroteBytes += Buffer.byteLength(line);
+  } catch (e) {
+    // 写不下去就记账，靠 ui.errors 的 dropped 字段让调用方知道"这里缺了东西"
+    dropped += 1;
+  }
+}
+
+/**
+ * 初始化日志目录。**必须在 app ready 之前调用**，否则早期崩溃（最常见的那类）
+ * 落不了盘。
+ * @param {{dir: string, meta?: object}} opts dir 为日志目录；meta 附在启动行里
+ *        （版本、端口、userData…），方便事后分辨"这份日志是哪个实例的"。
+ */
+export function initErrorLog(opts) {
+  const dir = (opts && opts.dir) || null;
+  if (!dir) return null;
+  logDir = dir;
+  if (opts && Number(opts.maxBytes) > 0) maxBytes = Number(opts.maxBytes);
+  if (opts && Number(opts.keep) > 0) keepFiles = Math.max(1, Number(opts.keep));
+  logFile = path.join(dir, 'error.jsonl');
+  try {
+    fs.mkdirSync(dir, { recursive: true });
+    try { wroteBytes = fs.statSync(logFile).size; } catch { wroteBytes = 0; }
+    // 进程边界的标记行：读日志时能一眼看出"这是哪一次启动"，以及上一次
+    // 是不是异常结束（没有 shutdown 行就说明是硬退）
+    appendLine({
+      ts: nowIso(),
+      kind: 'boot',
+      pid: process.pid,
+      node: process.versions && process.versions.node,
+      electron: process.versions && process.versions.electron,
+      platform: process.platform + ' ' + process.arch,
+      ...summarize((opts && opts.meta) || {}),
+    });
+  } catch {
+    logFile = null;
+  }
+  return logFile;
+}
+
+export function getLogPath() {
+  return logFile;
+}
+
+export function getLogDir() {
+  return logDir;
+}
+
+/**
+ * 记一条错误。永不抛。
+ * @param {string} kind 事件类别：uncaught_exception / unhandled_rejection /
+ *        render_process_gone / child_process_gone / nav_fail / ws_error / …
+ * @param {object} info 任意附加字段（message/stack/url/tab/…）
+ */
+export function recordError(kind, info) {
+  const entry = {
+    ts: nowIso(),
+    kind: String(kind || 'unknown'),
+    pid: process.pid,
+    uptime_ms: Math.round(process.uptime() * 1000),
+    ...summarize(info || {}),
+  };
+  // 崩溃上下文：最近若干次 WS 调用。放在条目里而不是另起一行，读的时候
+  // 不用自己按时间拼。
+  if (callRing.length) entry.recent_calls = callRing.slice(-20);
+  ring.push(entry);
+  while (ring.length > RING_MAX) ring.shift();
+  appendLine(entry);
+  return entry;
+}
+
+/**
+ * 记一次 WS 调用（进环形缓冲，不落盘 —— 只作为崩溃时的上下文）。
+ * @param {string} method 方法名
+ * @param {object} params 原始参数（内部会摘要化，大字段自动截断）
+ * @param {number} ms 耗时
+ * @param {boolean|string} outcome true/false 或错误摘要
+ */
+export function noteCall(method, params, ms, outcome) {
+  try {
+    const brief = summarize(params || {});
+    // 只留能定位的信息：text/html 这类大字段压成"长度"
+    const slim = {};
+    if (brief && typeof brief === 'object') {
+      for (const k of Object.keys(brief)) {
+        if (k === 'text' || k === 'html') {
+          // 正文类字段只留长度：几十 KB 的稿子灌进日志，一条就把文件写满
+          const v = (params || {})[k];
+          slim[k] = typeof v === 'string' ? '<' + v.length + ' chars>' : brief[k];
+        } else if (k === 'js') {
+          // 脚本保留开头：它是定位"崩在哪段注入代码"的关键，只留长度等于没留。
+          // 但也不能整段进日志（内联 base64 图片会让一条日志到 MB 级）。
+          const v = (params || {})[k];
+          slim[k] = typeof v === 'string'
+            ? (v.length > 200 ? v.slice(0, 200) + '…<' + v.length + ' chars>' : v)
+            : brief[k];
+        } else {
+          slim[k] = brief[k];
+        }
+      }
+    }
+    callRing.push({
+      ts: nowIso(),
+      method: String(method || ''),
+      params: slim,
+      ms: typeof ms === 'number' ? ms : null,
+      outcome: outcome === undefined ? null : summarize(outcome),
+    });
+    while (callRing.length > CALL_RING_MAX) callRing.shift();
+  } catch {
+    /* 记调用上下文失败绝不影响调用本身 */
+  }
+}
+
+/**
+ * 读最近错误（内存里的本次进程记录）。文件才是权威历史 —— 进程一崩，这里
+ * 就没了，所以回执里带 path 让调用方自己去翻。
+ */
+export function recentErrors(limit = 50, kind = null) {
+  const n = Math.max(1, Math.min(RING_MAX, Number(limit) || 50));
+  // boot / shutdown 是进程边界标记，不是"错误"。只有明确按 kind 查时才返回它们。
+  const MARKERS = new Set(['boot', 'shutdown']);
+  let items = kind ? ring.filter((e) => e.kind === kind) : ring.filter((e) => !MARKERS.has(e.kind));
+  return {
+    path: logFile,
+    dir: logDir,
+    count_in_memory: items.length,
+    dropped_writes: dropped,
+    items: items.slice(-n),
+  };
+}
+
+/** 正常退出时补一行收尾 —— 日志里没有 shutdown 行 = 上次是硬退。 */
+export function markShutdown(reason) {
+  recordError('shutdown', { reason: reason || 'normal' });
+}
+
+// 仅供测试：重置模块内状态，避免用例之间互相污染。
+export function __resetForTests() {
+  logFile = null;
+  logDir = null;
+  wroteBytes = 0;
+  dropped = 0;
+  maxBytes = DEFAULT_MAX_BYTES;
+  keepFiles = DEFAULT_KEEP;
+  ring.length = 0;
+  callRing.length = 0;
+}