npm - @aiyiran/myclaw - Versions diffs - 1.1.162 → 1.1.165 - Mend

@aiyiran/myclaw 1.1.162 → 1.1.165

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (5) hide show

package/CLAUDE.md +9 -3
package/assets/myclaw-inject.js +12 -8
package/package.json +1 -1
package/server/debug_record.py +391 -880
package/server/sync_workspace.py +5 -3

package/server/debug_record.py CHANGED Viewed

@@ -1,27 +1,30 @@
 """
-debug_record_renderer.py
+debug_record.py
 用途：
-把前端收集到的 currentDebugRecord 渲染成一个学生愿意打开的 HTML 文件。
-核心定位：
-1. 学生看到的是“运行回放”，不是专业调试报告。
-2. 老师能看到可能有用的线索。
-3. AI 可以从 <script id="debug-data" type="application/json"> 中读取完整结构化数据。
-4. 不做完整翻译，只做“事件转写”和少量常见 JS 错误解释。
+把前端收集到的 currentDebugRecord 落盘成两个文件，供学生/老师/AI 查看。
+【架构：数据与渲染分离】
+- debug-data.js   —— 每次覆盖写。内容是 `window.__DEBUG_DATA__ = {规范化后的记录}`。
+                     这是**唯一数据源**：既喂前端渲染，也给 AI 直接读。
+- debug-record.html —— 恒定的“壳”。包含 CSS + 前端渲染器 JS，运行时动态加载
+                     debug-data.js 并渲染。内容不随数据变化，因此同步循环不会
+                     反复把它当成“更新”重传。
+为什么这么拆：
+1. HTML 壳恒定 → 哈希不变 → 不再被同步误判为更新（根除循环上传问题）。
+2. AI 读的是纯数据 debug-data.js，信噪比高，不掺样式。
+3. 渲染逻辑在前端，改样式不用动 Python、不用重启同步进程。
+服务端职责（本文件）：
+- 接收 / 校验 / normalize 记录
+- 写出 debug-data.js 和 debug-record.html
+渲染职责（前端，在 HTML 壳的内联 JS 里）：
+- 读 window.__DEBUG_DATA__，渲染小结 / 线索 / 运行回放 / 原始数据
 重要架构原则：
 - 前端只传 claw / workspace / entryFile 这类逻辑身份。
-- 服务端根据 claw / workspace 计算真正的保存目录。
-- 不允许前端直接传文件系统路径。
-- debug-record.html 是给人看的。
-- debug-record.json / debug-data 是给 AI 和后续程序读的。
-后续扩展点：
-- 想改页面视觉：主要改 render_style()
-- 想改学生看到的文案：主要改 format_replay_event()
-- 想扩展错误解释：主要改 simplify_error_message()
-- 想新增事件类型：扩展 EventType 和 format_replay_event()
+- 服务端根据 claw / workspace 计算真正的保存目录，不允许前端传文件系统路径。
 """
 from __future__ import annotations
@@ -30,18 +33,16 @@ import json
 import re
 import time
 import uuid
-from dataclasses import dataclass
-from html import escape as html_escape
 from pathlib import Path
 from typing import Any, Dict, List, Optional
-from urllib.parse import urlparse, unquote
 # =============================================================================
 # 1. 事件类型定义
 # =============================================================================
 # 这里的事件类型必须和 debug-probe.js 中发出的 type 保持一致。
-# 后续如果 probe 新增事件类型，优先在这里补充，而不是散落在代码各处。
+# 注意：渲染逻辑已搬到前端 JS（见 render_shell_html），这里的常量主要供
+# normalize / create_summary 使用。前端 JS 里有一份对应的字符串常量。
 class EventType:
@@ -63,97 +64,39 @@ ERROR_EVENT_TYPES = {
 }
-DEFAULT_TITLE = "刚才发生了什么？"
 # =============================================================================
-# 2. 对外主函数：渲染 HTML
+# 2. 保存层：写 debug-data.js + 恒定的 debug-record.html 壳
 # =============================================================================
-def render_debug_record_html(input_record: Dict[str, Any]) -> str:
-    """
-    把调试记录渲染成完整 HTML。
-    参数：
-        input_record:
-            前端提交的 currentDebugRecord。
-            通常包含：
-            - claw
-            - workspace
-            - entryFile
-            - entryUrl
-            - traceId
-            - startedAt
-            - endedAt
-            - events
-    返回：
-        完整 HTML 字符串。
-    注意：
-        这里会 normalize record，避免字段缺失导致页面崩溃。
+def save_debug_record(record: Dict[str, Any], debug_dir: Path) -> Dict[str, str]:
     """
-    record = normalize_record(input_record)
-    summary = create_summary(record)
-    clues = extract_clues(record["events"])
-    replay_items_html = render_replay_items(record["events"])
-    clues_html = render_clues(clues)
-    raw_data_html = render_raw_data_card(record)
-    debug_json = safe_json_for_script(record)
-    return f"""<!DOCTYPE html>
-<html lang="zh-CN">
-<head>
-  <meta charset="UTF-8" />
-  <title>{escape_html(DEFAULT_TITLE)}</title>
-  <meta name="viewport" content="width=device-width, initial-scale=1" />
-  {render_style()}
-</head>
-<body>
-  <main class="page">
-    {render_hero()}
-    {render_summary(summary)}
-    {render_clues_card(clues_html)}
-    {render_replay_card(replay_items_html)}
-    {raw_data_html}
-    <script id="debug-data" type="application/json">
-{debug_json}
-    </script>
-  </main>
-</body>
-</html>"""
-# =============================================================================
-# 3. 保存层：写入 debug-record.html
-# =============================================================================
+    落盘调试记录。
-def save_debug_record(record: Dict[str, Any], debug_dir: Path) -> Dict[str, str]:
+    写两个文件：
+    - debug-data.js     每次覆盖，内容 = window.__DEBUG_DATA__ = {normalized record}
+    - debug-record.html 恒定壳（内容不变），负责加载并渲染上面的数据
+    """
     debug_dir.mkdir(parents=True, exist_ok=True)
     normalized_record = normalize_record(record)
+    # 数据文件：每次覆盖
+    data_js = "window.__DEBUG_DATA__ = " + safe_json_for_js(normalized_record) + ";\n"
+    data_path = debug_dir / "debug-data.js"
+    write_text_atomic(data_path, data_js)
+    # HTML 壳：内容恒定（不含数据）。每次都写没关系——内容一致，
+    # 基于内容哈希的同步不会把它当成变更重传。
     html_path = debug_dir / "debug-record.html"
-    write_text_atomic(html_path, render_debug_record_html(normalized_record))
+    write_text_atomic(html_path, render_shell_html())
-    return {"html_path": str(html_path)}
+    return {"html_path": str(html_path), "data_path": str(data_path)}
 def write_text_atomic(file_path: Path, content: str) -> None:
     """
-    原子写文件。
-    为什么不用直接 write_text？
-    因为 debug-record.html 可能被前端同时访问。
-    原子写可以避免出现“写到一半被读取”的半截文件。
-    实现方式：
-    1. 先写临时文件
-    2. 再 rename 成目标文件
+    原子写文件：先写临时文件，再 rename，避免“写到一半被读取”的半截文件。
     """
     temp_path = file_path.with_name(
         f"{file_path.name}.tmp.{int(time.time() * 1000)}.{uuid.uuid4().hex[:8]}"
@@ -163,7 +106,7 @@ def write_text_atomic(file_path: Path, content: str) -> None:
 # =============================================================================
-# 4. 路径层：根据 claw / workspace 计算正确目录
+# 3. 路径层：根据 claw / workspace 计算正确目录
 # =============================================================================
@@ -182,15 +125,11 @@ def resolve_workspace_debug_dir(
     """
     根据逻辑身份计算 debug 目录。
-    重要：
-    - 前端只应该传 workspace（你们的真实结构是 ~/.openclaw/{workspace}/，没有 claw 目录层）。
+    - 前端只传 workspace（真实结构 ~/.openclaw/{workspace}/，没有 claw 目录层）。
     - claw 只用于身份校验，不参与路径计算。
     - 服务端自己计算真实文件路径，不允许前端传文件系统路径。
-    真实目录（本机 Mac）：
-        ~/.openclaw/{workspace}/debug/
-    真实目录（服务器）：
-        /root/.openclaw/{workspace}/debug/
+    真实目录：{openclaw_root}/{workspace}/debug/
     安全规则：
     - workspace 只能包含字母、数字、下划线、短横线。
@@ -250,7 +189,6 @@ def handle_save_request(body: Dict[str, Any], openclaw_root: str, server_claw: s
         "ok": True,
         "traceId": record["traceId"],
         "debugRecordPath": paths["html_path"],
         "debugRecordUrl": debug_record_url,
     }
@@ -258,20 +196,7 @@ def handle_save_request(body: Dict[str, Any], openclaw_root: str, server_claw: s
 def assert_safe_id(value: str, field_name: str) -> None:
     """
     校验 claw / workspace 这类逻辑 ID。
-    允许：
-    - a-z
-    - A-Z
-    - 0-9
-    - _
-    - -
-    不允许：
-    - /
-    - ..
-    - 空格
-    - 中文路径
-    - 其他特殊字符
+    允许 a-z A-Z 0-9 _ -；不允许 / .. 空格 中文 等。
     """
     if not isinstance(value, str):
         raise ValueError(f"invalid {field_name}: must be string")
@@ -281,19 +206,16 @@ def assert_safe_id(value: str, field_name: str) -> None:
 # =============================================================================
-# 5. record / event 规范化
+# 4. record / event 规范化（数据清洗留在服务端，输出进 debug-data.js）
 # =============================================================================
 def normalize_record(record: Optional[Dict[str, Any]]) -> Dict[str, Any]:
     """
     规范化调试记录。
-    目的：
     - 服务端不要完全信任前端字段。
     - 字段缺失时提供默认值。
-    - events 始终是 list。
-    - payload 保持 JSON 可序列化。
+    - events 始终是 list；payload 保持 JSON 可序列化。
     """
     if not isinstance(record, dict):
         record = {}
@@ -326,10 +248,7 @@ def normalize_record(record: Optional[Dict[str, Any]]) -> Dict[str, Any]:
 def normalize_event(event: Any, index: int) -> Dict[str, Any]:
     """
-    规范化单条事件。
-    这里不会丢弃未知事件类型。
-    未知事件也保留，方便后续调试和扩展。
+    规范化单条事件。未知事件类型也保留，方便后续调试和扩展。
     """
     if not isinstance(event, dict):
         event = {}
@@ -354,11 +273,7 @@ def normalize_event(event: Any, index: int) -> Dict[str, Any]:
 def normalize_entry_file(value: Any) -> str:
     """
     入口文件只做展示用途，不用它计算文件系统路径。
-    为了安全和稳定：
-    - 缺失时返回 index.html
-    - 出现 .. 时返回 index.html
-    - 不是 .html 时返回 index.html
+    缺失 / 含 .. / 非 .html → 返回 index.html
     """
     entry_file = to_safe_string(value).lstrip("/")
@@ -378,16 +293,9 @@ def create_trace_id() -> str:
     return f"trace_{int(time.time() * 1000)}_{uuid.uuid4().hex[:8]}"
-# =============================================================================
-# 6. 概览与线索提取
-# =============================================================================
 def create_summary(record: Dict[str, Any]) -> Dict[str, Any]:
     """
-    重新计算概览，不完全依赖前端传来的 summary。
-    这块数据主要用于页面顶部的“试玩小结”。
+    重新计算概览，不完全依赖前端传来的 summary。用于页面顶部“试玩小结”。
     """
     events = record.get("events") or []
@@ -429,442 +337,82 @@ def create_summary(record: Dict[str, Any]) -> Dict[str, Any]:
     }
-def extract_clues(events: List[Dict[str, Any]]) -> List[Dict[str, str]]:
-    """
-    提取“可能有用的线索”。
-    这不是自动诊断，不要过度智能化。
-    只提取明显线索：
-    - runtime-error
-    - unhandledrejection
-    - resource-error
-    - console.error / console.warn
-    - console 中出现 null / undefined
-    """
-    clues: List[Dict[str, str]] = []
-    for event in events:
-        event_type = event.get("type")
-        payload = event.get("payload") or {}
-        if event_type == EventType.RUNTIME_ERROR:
-            clues.append({
-                "level": "error",
-                "icon": "⚠️",
-                "text": f"程序出错：{simplify_error_message(payload.get('message'))}",
-            })
-            continue
-        if event_type == EventType.UNHANDLED_REJECTION:
-            clues.append({
-                "level": "error",
-                "icon": "⚠️",
-                "text": f"程序有一个异步错误：{simplify_error_message(payload.get('message'))}",
-            })
-            continue
-        if event_type == EventType.RESOURCE_ERROR:
-            url = to_safe_string(payload.get("url"))
-            clues.append({
-                "level": "warning",
-                "icon": "🖼️",
-                "text": f"资源没加载出来：{get_file_name(url) or url or '未知资源'}",
-            })
-            continue
-        if event_type == EventType.CONSOLE:
-            level = to_safe_string(payload.get("level")) or "log"
-            message = to_safe_string(payload.get("message"))
-            if level == "error":
-                clues.append({
-                    "level": "error",
-                    "icon": "💬",
-                    "text": f"程序提示：{message}",
-                })
-                continue
-            if level == "warn":
-                clues.append({
-                    "level": "warning",
-                    "icon": "💬",
-                    "text": f"程序提醒：{message}",
-                })
-                continue
-            if "null" in message or "undefined" in message:
-                clues.append({
-                    "level": "info",
-                    "icon": "🔎",
-                    "text": f"程序里出现了空值线索：{message}",
-                })
-    return dedupe_clues(clues)[:6]
-def dedupe_clues(clues: List[Dict[str, str]]) -> List[Dict[str, str]]:
-    seen = set()
-    result = []
-    for clue in clues:
-        key = f"{clue.get('icon')}-{clue.get('text')}"
-        if key in seen:
-            continue
-        seen.add(key)
-        result.append(clue)
-    return result
 # =============================================================================
-# 7. 事件转写：结构化事件 -> 学生能读懂的回放句子
+# 5. 工具函数
 # =============================================================================
-def format_replay_event(event: Dict[str, Any]) -> Dict[str, str]:
-    """
-    把事件转成页面上的一条“运行回放”。
-    注意：
-    - 这不是完整翻译。
-    - 变量名、文件名、console 内容尽量保留原文。
-    - 外面包一层学生能读懂的壳。
-    """
-    event_type = event.get("type")
-    payload = event.get("payload") or {}
-    if event_type == EventType.PROBE_READY:
-        version = (
-            to_safe_string(payload.get("probeVersion"))
-            or to_safe_string(event.get("probeVersion"))
-        )
-        return {
-            "icon": "🔌",
-            "title": f"调试探针已就位（版本 {version}）" if version else "调试探针已就位",
-            "detail": "",
-        }
-    if event_type == EventType.PAGE_ENTER:
-        title = (
-            event.get("pageTitle")
-            or get_file_name(event.get("pageUrl"))
-            or "一个页面"
-        )
-        return {
-            "icon": "📄",
-            "title": f"来到了【{title}】",
-            "detail": get_file_name(event.get("pageUrl")),
-        }
-    if event_type == EventType.CLICK:
-        text = (
-            payload.get("text")
-            or payload.get("selector")
-            or payload.get("tag")
-            or "某个地方"
-        )
-        return {
-            "icon": "👆",
-            "title": f"点击了【{to_safe_string(text)}】",
-            "detail": "",
-        }
-    if event_type == EventType.KEYDOWN:
-        key = payload.get("code") or payload.get("key") or "某个键"
-        return {
-            "icon": "⌨️",
-            "title": f"按下了【{to_safe_string(key)}】",
-            "detail": "",
-        }
-    if event_type == EventType.CONSOLE:
-        level = to_safe_string(payload.get("level")) or "log"
-        message = to_safe_string(payload.get("message"))
-        return {
-            "icon": "⚠️" if level == "error" else "💬",
-            "title": f"程序说：{message}",
-            "detail": "" if level == "log" else f"console.{level}",
-        }
-    if event_type == EventType.RUNTIME_ERROR:
-        message = to_safe_string(payload.get("message"))
-        return {
-            "icon": "⚠️",
-            "title": f"程序出错了：{simplify_error_message(message)}",
-            "detail": message,
-        }
-    if event_type == EventType.UNHANDLED_REJECTION:
-        message = to_safe_string(payload.get("message"))
-        return {
-            "icon": "⚠️",
-            "title": f"程序有一个异步错误：{simplify_error_message(message)}",
-            "detail": message,
-        }
+def to_safe_string(value: Any) -> str:
+    if value is None:
+        return ""
+    if isinstance(value, str):
+        return value
+    try:
+        return str(value)
+    except Exception:
+        return ""
-    if event_type == EventType.RESOURCE_ERROR:
-        url = to_safe_string(payload.get("url"))
-        return {
-            "icon": "🖼️",
-            "title": f"有一个资源没有加载出来：{get_file_name(url) or payload.get('tag') or '未知资源'}",
-            "detail": url,
-        }
-    return {
-        "icon": "•",
-        "title": to_safe_string(event_type) or "未知事件",
-        "detail": "",
-    }
+def to_int(value: Any, default: int) -> int:
+    try:
+        return int(value)
+    except Exception:
+        return default
-def simplify_error_message(message: Any) -> str:
+def to_jsonable(value: Any) -> Any:
     """
-    少量常见 JS 错误解释。
-    原则：
-    - 不做完整翻译。
-    - 能稳定解释的才解释。
-    - 解释不了就返回原始错误。
+    确保对象可被 json.dumps 序列化。probe 发来的 payload 理论上已是 JSON，
+    这里做一层保护，避免后端因奇怪字段崩掉。
     """
-    raw = to_safe_string(message).strip()
-    if not raw:
-        return "程序遇到了一个错误"
+    try:
+        json.dumps(value, ensure_ascii=False)
+        return value
+    except Exception:
+        return to_safe_string(value)
-    not_defined_match = re.search(
-        r"(?:ReferenceError:\s*)?(.+?)\s+is not defined",
-        raw,
-    )
-    if not_defined_match:
-        name = not_defined_match.group(1).strip()
-        if name:
-            return f"找不到 {name}"
-    read_null_match = re.search(
-        r"Cannot read properties of null \(reading ['\"](.+?)['\"]\)",
-        raw,
-    )
-    if read_null_match:
-        return f"程序想从一个空东西里读取 {read_null_match.group(1)}"
-    read_undefined_match = re.search(
-        r"Cannot read properties of undefined \(reading ['\"](.+?)['\"]\)",
-        raw,
+def safe_json_for_js(value: Any) -> str:
+    """
+    把数据序列化成可安全放进 .js 文件的 JSON 字面量。
+    JSON 是 JS 的子集，唯一要处理的是 U+2028 / U+2029：
+    它们在 JSON 里合法，但在 JS 源码里是非法的行终止符。
+    """
+    return (
+        json.dumps(value, ensure_ascii=False, indent=2)
+        .replace(" ", "\\u2028")
+        .replace(" ", "\\u2029")
     )
-    if read_undefined_match:
-        return f"程序想从一个还没准备好的东西里读取 {read_undefined_match.group(1)}"
-    if "Cannot read properties of null" in raw:
-        return "程序想使用一个空东西"
-    if "Cannot read properties of undefined" in raw:
-        return "程序想使用一个还没有准备好的东西"
-    if "Failed to fetch" in raw:
-        return "网络请求失败，可能是资源地址或接口有问题"
-    if "Unexpected token" in raw:
-        return "代码里可能有一个符号写错了"
-    if "Unexpected end of input" in raw:
-        return "代码可能少了一个结尾符号"
-    return raw
-# =============================================================================
-# 8. HTML 渲染子函数
 # =============================================================================
-def render_hero() -> str:
-    return """
-    <section class="hero">
-      <div class="eyebrow">给 AI 看的运行回放</div>
-      <h1>刚才发生了什么？</h1>
-      <p class="intro">
-        这是你刚刚试玩作品时留下的记录。它记下了你进入了哪些页面、点击了哪些按钮、按了哪些键，以及程序有没有留下有用的线索。
-        如果作品哪里不对，可以把这份记录交给 AI 看。
-      </p>
-    </section>
-"""
-def render_summary(summary: Dict[str, Any]) -> str:
-    return f"""
-    <section class="card">
-      <h2>试玩小结</h2>
-      <div class="summary-grid">
-        {render_summary_item(summary.get("pageCount", 0), "进入页面")}
-        {render_summary_item(summary.get("clicks", 0), "点击")}
-        {render_summary_item(summary.get("keydowns", 0), "按键")}
-        {render_summary_item(summary.get("errorCount", 0), "可能的问题")}
-      </div>
-    </section>
-"""
-def render_summary_item(number: Any, label: str) -> str:
-    return f"""
-        <div class="summary-item">
-          <div class="summary-number">{escape_html(number)}</div>
-          <div class="summary-label">{escape_html(label)}</div>
-        </div>
-"""
-def render_clues_card(clues_html: str) -> str:
-    return f"""
-    <section class="card">
-      <h2>可能有用的线索</h2>
-      <div class="clue-list">
-        {clues_html}
-      </div>
-    </section>
-"""
-def render_clues(clues: List[Dict[str, str]]) -> str:
-    if not clues:
-        return """
-        <div class="empty-clue">
-          这次没有发现明显的红字错误。作品如果不符合预期，可以继续告诉 AI：
-          我做了什么、我希望发生什么、实际发生什么。
-        </div>
-"""
-    return "".join(
-        f"""
-        <div class="clue clue-{escape_html(clue.get("level", "info"))}">
-          <span class="clue-icon">{escape_html(clue.get("icon", "•"))}</span>
-          <span>{escape_html(clue.get("text", ""))}</span>
-        </div>
-"""
-        for clue in clues
-    )
-def render_replay_card(replay_items_html: str) -> str:
-    fallback = '<li class="empty-replay">这次没有记录到运行事件。</li>'
-    return f"""
-    <section class="card">
-      <h2>运行回放</h2>
-      <ol class="replay-list">
-        {replay_items_html or fallback}
-      </ol>
-    </section>
-"""
-def render_replay_items(events: List[Dict[str, Any]]) -> str:
-    html_parts = []
-    for event in events:
-        view = format_replay_event(event)
-        class_name = get_event_class_name(event)
-        detail_html = ""
-        if view.get("detail"):
-            detail_html = f' · {escape_html(view.get("detail"))}'
-        html_parts.append(
-            f"""
-        <li class="replay-item {escape_html(class_name)}">
-          <div class="event-icon">{escape_html(view.get("icon", "•"))}</div>
-          <div class="event-body">
-            <div class="event-main">{escape_html(view.get("title", ""))}</div>
-            <div class="event-sub">
-              {escape_html(format_time(event.get("time")))}{detail_html}
-            </div>
-          </div>
-        </li>
-"""
-        )
-    return "".join(html_parts)
-def render_raw_data_card(record: Dict[str, Any]) -> str:
-    pretty_json = json.dumps(record, ensure_ascii=False, indent=2)
-    return f"""
-    <section class="card">
-      <details>
-        <summary>展开给 AI 看的原始数据</summary>
-        <div class="tech-meta">
-          <div>作品空间：{escape_html(record.get("workspace") or "未知")}</div>
-          <div>入口文件：{escape_html(record.get("entryFile") or "index.html")}</div>
-          <div>开始时间：{escape_html(record.get("startedAt") or "")}</div>
-          <div>结束时间：{escape_html(record.get("endedAt") or "")}</div>
-          <div>记录编号：{escape_html(record.get("traceId") or "")}</div>
-        </div>
-        <pre>{escape_html(pretty_json)}</pre>
-      </details>
-    </section>
-"""
-def get_event_class_name(event: Dict[str, Any]) -> str:
-    event_type = event.get("type")
-    payload = event.get("payload") or {}
-    if event_type == EventType.PAGE_ENTER:
-        return "page-enter"
-    if event_type == EventType.CLICK:
-        return "click"
-    if event_type == EventType.KEYDOWN:
-        return "keydown"
-    if event_type == EventType.CONSOLE:
-        if payload.get("level") == "error":
-            return "console console-error"
-        return "console"
-    if event_type == EventType.RUNTIME_ERROR:
-        return "runtime-error"
-    if event_type == EventType.UNHANDLED_REJECTION:
-        return "unhandledrejection"
-    if event_type == EventType.RESOURCE_ERROR:
-        return "resource-error"
-    return "unknown"
+# 6. 恒定的 HTML 壳（含前端渲染器）
 # =============================================================================
-# 9. CSS
-# =============================================================================
-# CSS 放在这里有一个好处：
-# debug-record.html 是一个完整的独立文件。
-# 即使学生作品的 CSS 出问题，这个运行回放页面也不会受影响。
-def render_style() -> str:
-    return """
+# 这个函数返回的内容**不随数据变化**，是纯静态的“壳”：
+#   - <style> 页面样式
+#   - 前端渲染器 JS（事件转写 / 错误解释 / 线索提取 / DOM 渲染）
+#   - 运行时动态加载 debug-data.js?t=<时间戳> 绕开 CDN 缓存
+# 渲染逻辑是从原 Python 函数（format_replay_event / simplify_error_message /
+# extract_clues / render_*）逐一移植过来的 JS 版本。
+#
+# 维护提示：改样式改 <style>；改文案改 formatReplayEvent；改错误解释改
+# simplifyErrorMessage；新增事件类型在 formatReplayEvent / getEventClassName 补。
+def render_shell_html() -> str:
+    return r"""<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+  <meta charset="UTF-8" />
+  <title>刚才发生了什么？</title>
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
   <style>
     :root {
-      --bg: #f7f4ef;
-      --card: #ffffff;
-      --text: #262626;
-      --muted: #777;
-      --line: #eee4d8;
-      --soft-blue: #eef6ff;
-      --soft-yellow: #fff7df;
-      --soft-red: #fff1f1;
-      --soft-green: #edf9f1;
-      --soft-purple: #f4efff;
-    }
-    * {
-      box-sizing: border-box;
+      --bg: #f7f4ef; --card: #ffffff; --text: #262626; --muted: #777;
+      --line: #eee4d8; --soft-blue: #eef6ff; --soft-yellow: #fff7df;
+      --soft-red: #fff1f1; --soft-green: #edf9f1; --soft-purple: #f4efff;
     }
+    * { box-sizing: border-box; }
     body {
       margin: 0;
       background:
@@ -872,352 +420,315 @@ def render_style() -> str:
         radial-gradient(circle at top right, #eaf4ff, transparent 26rem),
         var(--bg);
       color: var(--text);
-      font-family:
-        -apple-system,
-        BlinkMacSystemFont,
-        "Segoe UI",
-        "PingFang SC",
-        "Microsoft YaHei",
-        sans-serif;
+      font-family: -apple-system, BlinkMacSystemFont, "Segoe UI",
+        "PingFang SC", "Microsoft YaHei", sans-serif;
       line-height: 1.6;
     }
-    .page {
-      max-width: 880px;
-      margin: 0 auto;
-      padding: 28px 18px 56px;
-    }
+    .page { max-width: 880px; margin: 0 auto; padding: 28px 18px 56px; }
     .hero {
       background: rgba(255, 255, 255, 0.88);
       border: 1px solid rgba(255, 255, 255, 0.7);
-      border-radius: 24px;
-      padding: 28px;
-      box-shadow: 0 10px 32px rgba(80, 58, 30, 0.08);
-      margin-bottom: 18px;
-    }
-    .eyebrow {
-      color: #8b6f3e;
-      font-weight: 700;
-      font-size: 14px;
-      margin-bottom: 8px;
-    }
-    h1 {
-      margin: 0 0 10px;
-      font-size: 34px;
-      letter-spacing: -0.03em;
-    }
-    h2 {
-      margin: 0 0 14px;
-      font-size: 21px;
-    }
-    .intro {
-      margin: 0;
-      color: #555;
-      font-size: 16px;
-      max-width: 680px;
+      border-radius: 24px; padding: 28px;
+      box-shadow: 0 10px 32px rgba(80, 58, 30, 0.08); margin-bottom: 18px;
     }
+    .eyebrow { color: #8b6f3e; font-weight: 700; font-size: 14px; margin-bottom: 8px; }
+    h1 { margin: 0 0 10px; font-size: 34px; letter-spacing: -0.03em; }
+    h2 { margin: 0 0 14px; font-size: 21px; }
+    .intro { margin: 0; color: #555; font-size: 16px; max-width: 680px; }
     .card {
-      background: var(--card);
-      border-radius: 20px;
-      padding: 22px;
-      margin-bottom: 16px;
-      box-shadow: 0 4px 18px rgba(60, 40, 20, 0.055);
+      background: var(--card); border-radius: 20px; padding: 22px;
+      margin-bottom: 16px; box-shadow: 0 4px 18px rgba(60, 40, 20, 0.055);
       border: 1px solid rgba(0, 0, 0, 0.035);
     }
-    .summary-grid {
-      display: grid;
-      grid-template-columns: repeat(4, 1fr);
-      gap: 10px;
-    }
+    .summary-grid { display: grid; grid-template-columns: repeat(4, 1fr); gap: 10px; }
     .summary-item {
-      border-radius: 16px;
-      padding: 14px;
-      background: #faf7f2;
-      border: 1px solid #f1e8db;
-      text-align: center;
-    }
-    .summary-number {
-      font-size: 30px;
-      line-height: 1;
-      font-weight: 800;
-      margin-bottom: 6px;
-    }
-    .summary-label {
-      color: #746b60;
-      font-size: 13px;
-    }
-    .clue-list {
-      display: grid;
-      gap: 10px;
-    }
-    .clue {
-      display: flex;
-      gap: 10px;
-      align-items: flex-start;
-      border-radius: 14px;
-      padding: 12px 14px;
-    }
-    .clue-error {
-      background: var(--soft-red);
-      border: 1px solid #ffd3d3;
-    }
-    .clue-warning {
-      background: var(--soft-yellow);
-      border: 1px solid #f3e4aa;
-    }
-    .clue-info {
-      background: var(--soft-blue);
-      border: 1px solid #d8eaff;
-    }
-    .clue-icon {
-      font-size: 20px;
-      line-height: 1.4;
-    }
+      border-radius: 16px; padding: 14px; background: #faf7f2;
+      border: 1px solid #f1e8db; text-align: center;
+    }
+    .summary-number { font-size: 30px; line-height: 1; font-weight: 800; margin-bottom: 6px; }
+    .summary-label { color: #746b60; font-size: 13px; }
+    .clue-list { display: grid; gap: 10px; }
+    .clue { display: flex; gap: 10px; align-items: flex-start; border-radius: 14px; padding: 12px 14px; }
+    .clue-error { background: var(--soft-red); border: 1px solid #ffd3d3; }
+    .clue-warning { background: var(--soft-yellow); border: 1px solid #f3e4aa; }
+    .clue-info { background: var(--soft-blue); border: 1px solid #d8eaff; }
+    .clue-icon { font-size: 20px; line-height: 1.4; }
     .empty-clue {
-      background: var(--soft-green);
-      border: 1px solid #cdebd5;
-      border-radius: 14px;
-      padding: 14px;
-      color: #375d42;
-    }
-    .replay-list {
-      list-style: none;
-      padding: 0;
-      margin: 0;
-      display: grid;
-      gap: 10px;
+      background: var(--soft-green); border: 1px solid #cdebd5;
+      border-radius: 14px; padding: 14px; color: #375d42;
     }
+    .replay-list { list-style: none; padding: 0; margin: 0; display: grid; gap: 10px; }
     .replay-item {
-      display: flex;
-      gap: 12px;
-      padding: 13px 14px;
-      border-radius: 16px;
-      background: #fbfbfb;
-      border: 1px solid #eeeeee;
-    }
-    .replay-item.click {
-      background: var(--soft-blue);
-      border-color: #d8eaff;
-    }
-    .replay-item.keydown {
-      background: var(--soft-purple);
-      border-color: #e2d7ff;
-    }
-    .replay-item.console {
-      background: #f9f9f9;
-      border-color: #ececec;
+      display: flex; gap: 12px; padding: 13px 14px; border-radius: 16px;
+      background: #fbfbfb; border: 1px solid #eeeeee;
     }
+    .replay-item.click { background: var(--soft-blue); border-color: #d8eaff; }
+    .replay-item.keydown { background: var(--soft-purple); border-color: #e2d7ff; }
+    .replay-item.console { background: #f9f9f9; border-color: #ececec; }
     .replay-item.console-error,
     .replay-item.runtime-error,
     .replay-item.unhandledrejection,
-    .replay-item.resource-error {
-      background: var(--soft-red);
-      border-color: #ffd3d3;
-    }
+    .replay-item.resource-error { background: var(--soft-red); border-color: #ffd3d3; }
     .event-icon {
-      width: 30px;
-      height: 30px;
-      display: grid;
-      place-items: center;
-      font-size: 20px;
-      flex: 0 0 auto;
-    }
-    .event-main {
-      font-weight: 650;
-    }
-    .event-sub {
-      margin-top: 2px;
-      color: var(--muted);
-      font-size: 13px;
-      word-break: break-all;
-    }
-    .empty-replay {
-      color: #777;
-      background: #fafafa;
-      border-radius: 14px;
-      padding: 14px;
-    }
-    details {
-      color: #555;
-    }
-    details summary {
-      cursor: pointer;
-      font-weight: 700;
-      color: #444;
-      margin-bottom: 10px;
-    }
+      width: 30px; height: 30px; display: grid; place-items: center;
+      font-size: 20px; flex: 0 0 auto;
+    }
+    .event-main { font-weight: 650; }
+    .event-sub { margin-top: 2px; color: var(--muted); font-size: 13px; word-break: break-all; }
+    .empty-replay { color: #777; background: #fafafa; border-radius: 14px; padding: 14px; }
+    details { color: #555; }
+    details summary { cursor: pointer; font-weight: 700; color: #444; margin-bottom: 10px; }
     pre {
-      background: #141821;
-      color: #e5e7eb;
-      border-radius: 14px;
-      padding: 16px;
-      overflow: auto;
-      white-space: pre-wrap;
-      word-break: break-word;
-      max-height: 460px;
-      font-size: 12px;
-      line-height: 1.5;
+      background: #141821; color: #e5e7eb; border-radius: 14px; padding: 16px;
+      overflow: auto; white-space: pre-wrap; word-break: break-word;
+      max-height: 460px; font-size: 12px; line-height: 1.5;
     }
-    .tech-meta {
-      display: grid;
-      gap: 4px;
-      font-size: 13px;
-      color: #777;
-      margin-bottom: 12px;
+    .tech-meta { display: grid; gap: 4px; font-size: 13px; color: #777; margin-bottom: 12px; }
+    @media (max-width: 720px) {
+      .summary-grid { grid-template-columns: repeat(2, 1fr); }
+      h1 { font-size: 29px; }
+      .hero, .card { padding: 20px; border-radius: 18px; }
     }
+  </style>
+</head>
+<body>
+  <main class="page">
+    <section class="hero">
+      <div class="eyebrow">给 AI 看的运行回放</div>
+      <h1>刚才发生了什么？</h1>
+      <p class="intro">
+        这是你刚刚试玩作品时留下的记录。它记下了你进入了哪些页面、点击了哪些按钮、按了哪些键，以及程序有没有留下有用的线索。
+        如果作品哪里不对，可以把这份记录交给 AI 看。
+      </p>
+    </section>
+    <div id="dynamic">正在加载调试数据…</div>
+  </main>
-    @media (max-width: 720px) {
-      .summary-grid {
-        grid-template-columns: repeat(2, 1fr);
+  <script>
+  (function () {
+    var EventType = {
+      PROBE_READY: "probe-ready", PAGE_ENTER: "page-enter", CLICK: "click",
+      KEYDOWN: "keydown", CONSOLE: "console", RUNTIME_ERROR: "runtime-error",
+      UNHANDLED_REJECTION: "unhandledrejection", RESOURCE_ERROR: "resource-error"
+    };
+    function toSafeString(v) {
+      if (v === null || v === undefined) return "";
+      if (typeof v === "string") return v;
+      try { return String(v); } catch (e) { return ""; }
+    }
+    function escapeHtml(v) {
+      return toSafeString(v)
+        .replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;").replace(/'/g, "&#39;");
+    }
+    function formatTime(iso) {
+      var t = toSafeString(iso);
+      if (t.length >= 19 && t.indexOf("T") >= 0) return t.substring(11, 19);
+      return t;
+    }
+    function getFileName(url) {
+      var t = toSafeString(url);
+      if (!t) return "";
+      try {
+        var path = t.split("?")[0].split("#")[0];
+        var name = path.substring(path.lastIndexOf("/") + 1);
+        return decodeURIComponent(name);
+      } catch (e) { return ""; }
+    }
+    function simplifyErrorMessage(message) {
+      var raw = toSafeString(message).trim();
+      if (!raw) return "程序遇到了一个错误";
+      var m;
+      m = raw.match(/(?:ReferenceError:\s*)?(.+?)\s+is not defined/);
+      if (m && m[1].trim()) return "找不到 " + m[1].trim();
+      m = raw.match(/Cannot read properties of null \(reading ['"](.+?)['"]\)/);
+      if (m) return "程序想从一个空东西里读取 " + m[1];
+      m = raw.match(/Cannot read properties of undefined \(reading ['"](.+?)['"]\)/);
+      if (m) return "程序想从一个还没准备好的东西里读取 " + m[1];
+      if (raw.indexOf("Cannot read properties of null") >= 0) return "程序想使用一个空东西";
+      if (raw.indexOf("Cannot read properties of undefined") >= 0) return "程序想使用一个还没有准备好的东西";
+      if (raw.indexOf("Failed to fetch") >= 0) return "网络请求失败，可能是资源地址或接口有问题";
+      if (raw.indexOf("Unexpected token") >= 0) return "代码里可能有一个符号写错了";
+      if (raw.indexOf("Unexpected end of input") >= 0) return "代码可能少了一个结尾符号";
+      return raw;
+    }
+    function formatReplayEvent(event) {
+      var type = event.type;
+      var p = event.payload || {};
+      if (type === EventType.PROBE_READY) {
+        var ver = toSafeString(p.probeVersion) || toSafeString(event.probeVersion);
+        return { icon: "🔌", title: ver ? ("调试探针已就位（版本 " + ver + "）") : "调试探针已就位", detail: "" };
       }
-      h1 {
-        font-size: 29px;
+      if (type === EventType.PAGE_ENTER) {
+        var title = event.pageTitle || getFileName(event.pageUrl) || "一个页面";
+        return { icon: "📄", title: "来到了【" + title + "】", detail: getFileName(event.pageUrl) };
       }
-      .hero,
-      .card {
-        padding: 20px;
-        border-radius: 18px;
+      if (type === EventType.CLICK) {
+        var text = p.text || p.selector || p.tag || "某个地方";
+        return { icon: "👆", title: "点击了【" + toSafeString(text) + "】", detail: "" };
+      }
+      if (type === EventType.KEYDOWN) {
+        var key = p.code || p.key || "某个键";
+        return { icon: "⌨️", title: "按下了【" + toSafeString(key) + "】", detail: "" };
+      }
+      if (type === EventType.CONSOLE) {
+        var level = toSafeString(p.level) || "log";
+        var message = toSafeString(p.message);
+        return { icon: level === "error" ? "⚠️" : "💬", title: "程序说：" + message, detail: level === "log" ? "" : ("console." + level) };
+      }
+      if (type === EventType.RUNTIME_ERROR) {
+        var em = toSafeString(p.message);
+        return { icon: "⚠️", title: "程序出错了：" + simplifyErrorMessage(em), detail: em };
+      }
+      if (type === EventType.UNHANDLED_REJECTION) {
+        var am = toSafeString(p.message);
+        return { icon: "⚠️", title: "程序有一个异步错误：" + simplifyErrorMessage(am), detail: am };
+      }
+      if (type === EventType.RESOURCE_ERROR) {
+        var url = toSafeString(p.url);
+        return { icon: "🖼️", title: "有一个资源没有加载出来：" + (getFileName(url) || p.tag || "未知资源"), detail: url };
+      }
+      return { icon: "•", title: toSafeString(type) || "未知事件", detail: "" };
+    }
+    function getEventClassName(event) {
+      var type = event.type;
+      var p = event.payload || {};
+      if (type === EventType.PAGE_ENTER) return "page-enter";
+      if (type === EventType.CLICK) return "click";
+      if (type === EventType.KEYDOWN) return "keydown";
+      if (type === EventType.CONSOLE) return p.level === "error" ? "console console-error" : "console";
+      if (type === EventType.RUNTIME_ERROR) return "runtime-error";
+      if (type === EventType.UNHANDLED_REJECTION) return "unhandledrejection";
+      if (type === EventType.RESOURCE_ERROR) return "resource-error";
+      return "unknown";
+    }
+    function extractClues(events) {
+      var clues = [];
+      for (var i = 0; i < events.length; i++) {
+        var event = events[i];
+        var type = event.type;
+        var p = event.payload || {};
+        if (type === EventType.RUNTIME_ERROR) {
+          clues.push({ level: "error", icon: "⚠️", text: "程序出错：" + simplifyErrorMessage(p.message) });
+          continue;
+        }
+        if (type === EventType.UNHANDLED_REJECTION) {
+          clues.push({ level: "error", icon: "⚠️", text: "程序有一个异步错误：" + simplifyErrorMessage(p.message) });
+          continue;
+        }
+        if (type === EventType.RESOURCE_ERROR) {
+          var url = toSafeString(p.url);
+          clues.push({ level: "warning", icon: "🖼️", text: "资源没加载出来：" + (getFileName(url) || url || "未知资源") });
+          continue;
+        }
+        if (type === EventType.CONSOLE) {
+          var level = toSafeString(p.level) || "log";
+          var message = toSafeString(p.message);
+          if (level === "error") { clues.push({ level: "error", icon: "💬", text: "程序提示：" + message }); continue; }
+          if (level === "warn") { clues.push({ level: "warning", icon: "💬", text: "程序提醒：" + message }); continue; }
+          if (message.indexOf("null") >= 0 || message.indexOf("undefined") >= 0) {
+            clues.push({ level: "info", icon: "🔎", text: "程序里出现了空值线索：" + message });
+          }
+        }
+      }
+      // 去重 + 取前 6 条
+      var seen = {}, result = [];
+      for (var j = 0; j < clues.length; j++) {
+        var k = clues[j].icon + "-" + clues[j].text;
+        if (seen[k]) continue;
+        seen[k] = true;
+        result.push(clues[j]);
       }
+      return result.slice(0, 6);
     }
-  </style>
-"""
-# =============================================================================
-# 10. 工具函数
-# =============================================================================
-def format_time(iso_time: Any) -> str:
-    """
-    把 ISO 时间变成页面里显示的 HH:MM:SS。
-    注意：
-    这里只做展示，不做严肃时区换算。
-    """
-    text = to_safe_string(iso_time)
-    if len(text) >= 19 and "T" in text:
-        return text[11:19]
-    return text
-def get_file_name(url: Any) -> str:
-    """
-    从 URL 或路径中取最后一个文件名。
-    示例：
-    https://cdn.xxx.com/workspace/player.png?t=123 -> player.png
-    /workspace/game.html -> game.html
-    """
-    text = to_safe_string(url)
-    if not text:
-        return ""
-    try:
-        parsed = urlparse(text)
-        path = parsed.path or text.split("?")[0].split("#")[0]
-        name = Path(path).name
-        return unquote(name)
-    except Exception:
-        return ""
-def to_safe_string(value: Any) -> str:
-    """
-    尽量把任意值转成字符串。
-    """
-    if value is None:
-        return ""
-    if isinstance(value, str):
-        return value
-    try:
-        return str(value)
-    except Exception:
-        return ""
-def to_int(value: Any, default: int) -> int:
-    try:
-        return int(value)
-    except Exception:
-        return default
-def to_jsonable(value: Any) -> Any:
-    """
-    确保对象可以被 json.dumps 序列化。
-    debug-probe 发来的 payload 理论上已经是 JSON。
-    但这里做一层保护，避免后端因为奇怪字段崩掉。
-    """
-    try:
-        json.dumps(value, ensure_ascii=False)
-        return value
-    except Exception:
-        return to_safe_string(value)
-def escape_html(value: Any) -> str:
-    """
-    HTML 转义，防止 XSS。
-    所有进入 HTML 正文的动态内容，都应该走这个函数。
-    """
-    return html_escape(to_safe_string(value), quote=True)
-def safe_json_for_script(value: Any) -> str:
-    """
-    把 JSON 安全地放进：
-    <script type="application/json">...</script>
-    重点防止：
-    - </script> 提前闭合
-    - < > & 等字符影响 HTML
-    """
-    return (
-        json.dumps(value, ensure_ascii=False, indent=2)
-        .replace("<", "\\u003c")
-        .replace(">", "\\u003e")
-        .replace("&", "\\u0026")
-        .replace("\u2028", "\\u2028")
-        .replace("\u2029", "\\u2029")
-    )
+    function renderSummary(summary) {
+      summary = summary || {};
+      function item(n, label) {
+        return '<div class="summary-item"><div class="summary-number">' +
+          escapeHtml(n || 0) + '</div><div class="summary-label">' +
+          escapeHtml(label) + '</div></div>';
+      }
+      return '<section class="card"><h2>试玩小结</h2><div class="summary-grid">' +
+        item(summary.pageCount, "进入页面") +
+        item(summary.clicks, "点击") +
+        item(summary.keydowns, "按键") +
+        item(summary.errorCount, "可能的问题") +
+        '</div></section>';
+    }
+    function renderClues(clues) {
+      if (!clues.length) {
+        return '<section class="card"><h2>可能有用的线索</h2><div class="clue-list">' +
+          '<div class="empty-clue">这次没有发现明显的红字错误。作品如果不符合预期，可以继续告诉 AI：' +
+          '我做了什么、我希望发生什么、实际发生什么。</div></div></section>';
+      }
+      var inner = clues.map(function (c) {
+        return '<div class="clue clue-' + escapeHtml(c.level || "info") + '">' +
+          '<span class="clue-icon">' + escapeHtml(c.icon || "•") + '</span>' +
+          '<span>' + escapeHtml(c.text || "") + '</span></div>';
+      }).join("");
+      return '<section class="card"><h2>可能有用的线索</h2><div class="clue-list">' + inner + '</div></section>';
+    }
+    function renderReplay(events) {
+      var fallback = '<li class="empty-replay">这次没有记录到运行事件。</li>';
+      var items = events.map(function (event) {
+        var view = formatReplayEvent(event);
+        var cls = getEventClassName(event);
+        var detail = view.detail ? (" · " + escapeHtml(view.detail)) : "";
+        return '<li class="replay-item ' + escapeHtml(cls) + '">' +
+          '<div class="event-icon">' + escapeHtml(view.icon || "•") + '</div>' +
+          '<div class="event-body"><div class="event-main">' + escapeHtml(view.title || "") + '</div>' +
+          '<div class="event-sub">' + escapeHtml(formatTime(event.time)) + detail + '</div></div></li>';
+      }).join("");
+      return '<section class="card"><h2>运行回放</h2><ol class="replay-list">' +
+        (items || fallback) + '</ol></section>';
+    }
+    function renderRawData(record) {
+      var pretty = JSON.stringify(record, null, 2);
+      return '<section class="card"><details><summary>展开给 AI 看的原始数据</summary>' +
+        '<div class="tech-meta">' +
+        '<div>作品空间：' + escapeHtml(record.workspace || "未知") + '</div>' +
+        '<div>入口文件：' + escapeHtml(record.entryFile || "index.html") + '</div>' +
+        '<div>开始时间：' + escapeHtml(record.startedAt || "") + '</div>' +
+        '<div>结束时间：' + escapeHtml(record.endedAt || "") + '</div>' +
+        '<div>记录编号：' + escapeHtml(record.traceId || "") + '</div></div>' +
+        '<pre>' + escapeHtml(pretty) + '</pre></details></section>';
+    }
+    function render(record) {
+      record = record || {};
+      var events = record.events || [];
+      var html =
+        renderSummary(record.summary) +
+        renderClues(extractClues(events)) +
+        renderReplay(events) +
+        renderRawData(record);
+      document.getElementById("dynamic").innerHTML = html;
+    }
+    // 动态加载数据，带时间戳绕开 CDN 缓存（壳恒定，数据每次新）
+    var s = document.createElement("script");
+    s.src = "debug-data.js?t=" + Date.now();
+    s.onload = function () {
+      try { render(window.__DEBUG_DATA__); }
+      catch (e) { document.getElementById("dynamic").textContent = "渲染失败：" + (e && e.message); }
+    };
+    s.onerror = function () {
+      document.getElementById("dynamic").textContent = "调试数据加载失败（debug-data.js）";
+    };
+    document.head.appendChild(s);
+  })();
+  </script>
+</body>
+</html>"""