@aiyiran/myclaw 1.1.139 → 1.1.140

package/CLAUDE.md

@@ -0,0 +1,164 @@
+# MyClaw 架构说明
+
+> 本文件由 Claude Code 每次会话自动加载，也是给人类协作者的架构索引。
+> 项目变复杂后，**新增跨文件、跨前后端的系统时，请在这里补一节**，让后来的 AI 和人都能快速建立全局认识。
+
+---
+
+## 项目是什么
+
+MyClaw 是 OpenClaw 教学环境的一站式工具包，做两件事：
+
+1. **CLI**（`index.js`）：给老师/管理员用，`myclaw patch`、`myclaw update`、`myclaw new` 等命令。
+2. **运行时注入**：把一批 JS 文件注入进 OpenClaw 的 control-ui 页面，扩展其功能（作品列表、调试记录、TTS、语音输入…）。
+
+两件事共用同一个仓库，发布为 npm 包（`@aiyiran/myclaw`）。
+
+---
+
+## 目录结构速览
+
+```
+myclaw/
+├── assets/              # 浏览器运行时注入脚本（被 patch.js 拷进 control-ui）
+│   ├── debug-probe.js       # 注入到学生 HTML iframe 的采集探针
+│   ├── debug-collector.js   # 父页面调试记录收集器
+│   ├── myclaw-artifacts.js  # 作品列表 + 预览弹框
+│   ├── myclaw-inject.js     # 核心注入（token、workspace 等）
+│   ├── myclaw-iteration.js  # 迭代面板
+│   └── myclaw-tts.js        # TTS 注入
+├── patches/
+│   └── patch.js         # 把 assets/ 里的脚本拷进 control-ui 并注入 index.html
+├── server/
+│   ├── sync_workspace.py    # 核心服务端：同步循环 + HTTP API（18800 端口）
+│   ├── debug_record.py      # 调试记录的校验、路径计算、渲染、写盘
+│   └── artifacts_schema.py  # __MY_ARTIFACTS__.json 的 schema 和工具函数
+├── injects/             # 注入到 OpenClaw 内部行为的脚本（非 control-ui 页面）
+├── index.js             # CLI 入口
+└── gateway.js           # Gateway 生命周期管理
+```
+
+---
+
+## 两个环境（本地 vs 远程）
+
+很多逻辑都在这里分叉，改代码前先确认你在哪个环境：
+
+| | 本地（Mac 开发） | 远程（服务器） |
+|---|---|---|
+| control-ui 地址 | `http://127.0.0.1:18789` | `https://{claw}.yiranlaoshi.com` |
+| API 服务端口 | `18800` | `8080`（经 nginx `/sync` 反代） |
+| `.openclaw` 根目录 | `~/.openclaw/` | `/root/.openclaw/` |
+| clawName 来源 | `/api/config` 接口动态获取 | hostname 解析 |
+| 学生 HTML 预览 | CDN（`cdn.yiranlaoshi.com`） | CDN（同） |
+
+`detectEnvironment()` 和 `MYCLAW_API_BASE` 封装了这个分叉，前端代码通过它们取路径，**不要在各处硬写 URL**。
+
+---
+
+## 注入脚本的生命周期
+
+```
+assets/*.js 源码
+    ↓  myclaw patch（即 patches/patch.js）
+control-ui 目录（.js 文件拷贝进去 + index.html 注入 <script> 标签）
+    ↓  浏览器加载 control-ui
+父页面运行时
+```
+
+**script 加载顺序**（有依赖关系，顺序不能乱）：
+```
+voice-output.js → voice-input.js → myclaw-tts.js
+→ debug-collector.js   ← 必须在 artifacts 之前（artifacts 调它暴露的全局函数）
+→ myclaw-artifacts.js → myclaw-iteration.js → myclaw-inject.js
+```
+
+⚠️ **改了 `assets/` 的文件，必须重新跑 `myclaw patch` 才生效。**
+
+---
+
+## sync_workspace.py 是什么
+
+它不只是同步脚本，是一个完整的 Python HTTP 服务（`MyclawAPIHandler`），同时做两件事：
+
+- **同步循环**：定期扫 `.openclaw/workspace*/`，把变化的文件上传七牛 CDN。
+- **HTTP API**：监听 18800（服务器上 8080），提供 `/api/artifacts`、`/api/file`、`/api/debug-record/save` 等接口。
+
+⚠️ **改了 `server/` 下的 Python 文件，必须重启同步进程才生效**（不会热重载）。
+
+---
+
+## 调试记录系统（Debug Record）
+
+让老师/学生在预览 HTML 作品时，自动采集运行现场（点击、报错、console…），关闭预览时落盘成一份调试报告，供 AI 修 bug 或展示给学生。
+
+### 数据流（一条事件的一生）
+
+```
+学生 HTML 作品（CDN，跨域 iframe）
+  │  内含注入的 probe
+  ├─ probe 采集 console/click/keydown/错误/资源失败
+  │        │ postMessage(source=OPENCLAW_DEBUG_PROBE)
+  ▼        ▼
+父页面（control-ui，OpenClaw 控制台）
+  ├─ artifacts 预览弹框：创建并拥有 iframe
+  ├─ collector：挂靠该 iframe，收事件、攒成 currentDebugRecord
+  │        │ 关闭预览时 POST {claw, workspace, entryFile, events...}
+  ▼        ▼
+服务端（sync_workspace.py，本机 18800 / 远程经 nginx /sync）
+  ├─ 按 workspace 自行算目录，写 {workspace}/debug/debug-record.{json,html}
+  ▼
+同步循环 → 上传 CDN → 可展示给学生
+```
+
+### 三个角色（务必分清职责）
+
+| 角色 | 文件 | 职责 | 不负责 |
+|------|------|------|--------|
+| **probe**（采集侧） | `assets/debug-probe.js` | 在 iframe 内采集现场，`postMessage` 上报 | traceId、workspace、上传、判因 |
+| **collector**（接收侧） | `assets/debug-collector.js` | 父页面收事件、攒记录、关闭时提交 | probe 注入、AI 修复、HTML 模板 |
+| **server**（落库侧） | `server/debug_record.py` | 算目录、校验、渲染 HTML、原子写盘 | 采集、CDN 上传（交给同步循环） |
+
+### 关键设计约束（改之前先读）
+
+1. **跨域是前提**。学生 HTML 从 CDN 加载，父页面**读不到也注入不进** iframe。所以 probe 必须预先在 HTML 里，靠 `postMessage` 通信。别试图用父页面 DOM 操作 iframe 内部。
+
+2. **probe 由服务端在上传时注入**，不是前端注入。见 `sync_workspace.py` 的 `_put_file_to_qiniu` / `inject_probe_into_html`：HTML 上传到七牛前注入，**不改磁盘原文件**（改了会触发同步循环 + 污染学生源码）。
+
+3. **probe 版本号单一来源**：`assets/debug-probe.js` 里的 `PROBE_VERSION` 常量。服务端**运行时正则解析**它，不在 Python 里硬写。注入用 `<script data-openclaw-probe="版本号">` 做幂等：已是当前版本跳过，旧版本替换，缺失则注入。
+   - ⚠️ **probe 是惰性加载并缓存的**。改了 `debug-probe.js` 必须**重启同步进程**才生效（符合 publish 即重启的流程，但本地手调要记得）。
+
+4. **只有一个 iframe**。collector 当初设计成自建 iframe，已改为"挂靠 artifacts 已建好的 iframe"（`startDebugRecord(iframeEl, entryUrl, context)`）。两个模块共用一个 iframe，artifacts 管生命周期，collector 只录制。
+
+5. **前端不传文件路径**。前端只传逻辑字段（claw / workspace / entryFile），**服务端自己算目录**。`claw` 不是路径层级，只用于跟本机 `CLAW_NAME` 校验防串写；真实路径是 `{openclaw_root}/{workspace}/debug/`。
+
+6. **落盘只留最新一份**：固定文件名 `debug-record.{json,html}`，每次覆盖。
+
+### 接口
+
+`POST /api/debug-record/save`（`sync_workspace.py` 的 `do_POST`）
+
+```jsonc
+// 请求
+{ "claw","workspace","entryFile","entryUrl","traceId",
+  "startedAt","endedAt","summary":{}, "events":[] }
+// 响应
+{ "ok":true, "traceId", "debugRecordPath", "debugRecordJsonPath", "debugRecordUrl" }
+```
+
+### 涉及文件一览
+
+| 文件 | 角色 |
+|------|------|
+| `assets/debug-probe.js` | probe 源码（含版本号，单一来源） |
+| `assets/debug-collector.js` | 父页面收集器 |
+| `assets/myclaw-artifacts.js` | 预览弹框，HTML 分支挂载 collector |
+| `server/sync_workspace.py` | probe 注入（上传时）+ 保存接口路由 |
+| `server/debug_record.py` | 保存逻辑 + HTML 渲染 |
+| `patches/patch.js` | 把 collector 注入 control-ui 页面 |
+| `server/参考/*.ref` | AI 给的 Node 版参考实现（已移植为 Python，仅留存） |
+
+### 已知待办
+
+- 整链路端到端实测（单测已过，未在真实 gateway + 同步进程跑通）。
+- `{workspace}/debug/debug-record.html` 会进 `__MY_ARTIFACTS__.json` 作品列表，是否需要从列表过滤、改走专门入口，待定。

package/assets/debug-collector.js

@@ -0,0 +1,384 @@
+/**
+ * OpenClaw Parent Debug Collector V1
+ *
+ * 职责：
+ * 1. 点击查看网页时创建 currentDebugRecord
+ * 2. 接收 iframe 内 probe 发来的 DEBUG_EVENT
+ * 3. 关闭 iframe 时提交服务端
+ *
+ * 不负责：
+ * 1. probe 注入
+ * 2. AI 修复
+ * 3. 服务端生成 HTML 的具体模板
+ */
+
+let currentDebugRecord = null;
+let previewIframe = null;
+let latestDebugRecordResult = null;
+
+// 当前预览所属的作品空间上下文（由调用方在打开预览时传入）。
+// collector 只把它原样转交服务端，服务端据此自行计算落盘目录。
+let currentWorkspaceContext = null;
+
+const MAX_EVENTS = 300;
+
+/**
+ * 创建本地 traceId。
+ * 这个 traceId 不传给 iframe，只用于整理记录。
+ */
+function createTraceId() {
+    const time = new Date()
+        .toISOString()
+        .replace(/[-:.TZ]/g, "")
+        .slice(0, 14);
+
+    const random = Math.random().toString(36).slice(2, 8);
+
+    return `trace_${time}_${random}`;
+}
+
+/**
+ * 打开网页预览时调用，挂靠到一个已存在的 iframe 上开始录制。
+ * iframe 的创建、显示、关闭都由调用方（artifacts 预览弹框）负责，
+ * collector 只负责记录，不拥有 iframe。
+ *
+ * @param {HTMLIFrameElement} iframeEl 预览用的 iframe（src 已设置）
+ * @param {string} entryUrl           iframe 实际加载的 URL（通常已含缓存戳）
+ * @param {Object}  context           作品空间上下文 { claw, workspace, entryFile, apiBase }
+ */
+function startDebugRecord(iframeEl, entryUrl, context) {
+    closeExistingPreviewWithoutSaving();
+
+    currentWorkspaceContext = context || null;
+
+    currentDebugRecord = {
+        traceId: createTraceId(),
+        entryUrl: entryUrl || (iframeEl && iframeEl.src) || "",
+        startedAt: new Date().toISOString(),
+        endedAt: null,
+        events: []
+    };
+
+    previewIframe = iframeEl || null;
+
+    setPreviewState("recording");
+
+    console.log("[debug] 调试记录开始:", currentDebugRecord.traceId);
+}
+
+/**
+ * 接收 probe 发来的 postMessage。
+ */
+function handleProbeMessage(messageEvent) {
+    const data = messageEvent.data;
+
+    if (!data || data.source !== "OPENCLAW_DEBUG_PROBE") {
+        return;
+    }
+
+    if (data.type !== "DEBUG_EVENT") {
+        return;
+    }
+
+    if (!currentDebugRecord) {
+        return;
+    }
+
+    // 第一版只允许一个 iframe，尽量过滤掉非当前 iframe 的消息。
+    if (
+        previewIframe &&
+        previewIframe.contentWindow &&
+        messageEvent.source !== previewIframe.contentWindow
+    ) {
+        return;
+    }
+
+    const probeEvent = data.event;
+
+    if (!probeEvent || !probeEvent.type) {
+        return;
+    }
+
+    appendDebugEvent(probeEvent);
+}
+
+/**
+ * 把事件追加进当前调试记录。
+ */
+function appendDebugEvent(probeEvent) {
+    const event = {
+        seq: currentDebugRecord.events.length + 1,
+        receivedAt: new Date().toISOString(),
+        ...probeEvent
+    };
+
+    currentDebugRecord.events.push(event);
+
+    trimDebugEvents(currentDebugRecord.events);
+
+    renderDebugRecordPreview(currentDebugRecord);
+}
+
+/**
+ * 控制日志长度，避免无限膨胀。
+ */
+function trimDebugEvents(events) {
+    if (events.length <= MAX_EVENTS) {
+        return;
+    }
+
+    const importantTypes = new Set([
+        "runtime-error",
+        "unhandledrejection",
+        "resource-error"
+    ]);
+
+    const importantEvents = events.filter((event) =>
+        importantTypes.has(event.type)
+    );
+
+    const latestEvents = events.slice(-MAX_EVENTS);
+
+    const merged = [...importantEvents, ...latestEvents];
+
+    const seen = new Set();
+    const deduped = [];
+
+    for (const event of merged) {
+        const key = event.seq || `${event.type}-${event.time}-${event.pageUrl}`;
+        if (seen.has(key)) continue;
+        seen.add(key);
+        deduped.push(event);
+    }
+
+    events.length = 0;
+    events.push(...deduped.slice(-MAX_EVENTS));
+}
+
+/**
+ * 点击【关闭网页】时调用。
+ */
+async function closePreviewAndSaveDebugRecord() {
+    if (!currentDebugRecord) {
+        closeIframeOnly();
+        return null;
+    }
+
+    currentDebugRecord.endedAt = new Date().toISOString();
+
+    const recordToSave = {
+        ...currentDebugRecord,
+        summary: createLocalDebugSummary(currentDebugRecord)
+    };
+
+    closeIframeOnly();
+
+    setPreviewState("saving-debug-record");
+
+    try {
+        const result = await saveDebugRecordToServer(recordToSave);
+
+        latestDebugRecordResult = result;
+
+        setPreviewState("debug-record-ready");
+
+        console.log("[debug] debug record saved:", result);
+
+        return result;
+    } catch (error) {
+        setPreviewState("debug-record-save-failed");
+
+        console.error("[debug] failed to save debug record:", error);
+
+        throw error;
+    } finally {
+        currentDebugRecord = null;
+    }
+}
+
+/**
+ * 只关闭 iframe，不保存。
+ * 用于打开新预览前清理旧 iframe。
+ */
+function closeExistingPreviewWithoutSaving() {
+    if (previewIframe) {
+        closeIframeOnly();
+    }
+
+    currentDebugRecord = null;
+}
+
+/**
+ * 解除对 iframe 的引用。
+ * iframe 的 DOM 移除由调用方（预览弹框）负责，collector 不拥有 iframe。
+ */
+function closeIframeOnly() {
+    previewIframe = null;
+}
+
+/**
+ * 提交给服务端。
+ * 合入作品空间逻辑字段（claw / workspace / entryFile），服务端据此自行算目录。
+ * 不传文件路径——路径由服务端决定，更安全。
+ */
+async function saveDebugRecordToServer(record) {
+    const context = currentWorkspaceContext || {};
+
+    const payload = {
+        claw: context.claw,
+        workspace: context.workspace,
+        entryFile: context.entryFile,
+        ...record
+    };
+
+    // API 基址由调用方传入（远程走 /sync 反代，本地走 18800 端口）；
+    // 缺省回落到同源相对路径。
+    const base = context.apiBase || "";
+    const response = await fetch(base + "/api/debug-record/save", {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json"
+        },
+        body: JSON.stringify(payload)
+    });
+
+    if (!response.ok) {
+        throw new Error(`保存调试记录失败：${response.status}`);
+    }
+
+    return await response.json();
+}
+
+/**
+ * 生成一个本地摘要，方便服务端直接展示。
+ */
+function createLocalDebugSummary(record) {
+    const events = record.events || [];
+
+    const errorCount = events.filter((event) =>
+        ["runtime-error", "unhandledrejection", "resource-error"].includes(event.type)
+    ).length;
+
+    const consoleErrorCount = events.filter(
+        (event) =>
+            event.type === "console" &&
+            event.payload &&
+            event.payload.level === "error"
+    ).length;
+
+    const pages = Array.from(
+        new Set(
+            events
+                .map((event) => event.pagePath || event.pageUrl)
+                .filter(Boolean)
+        )
+    );
+
+    const clicks = events.filter((event) => event.type === "click").length;
+    const keydowns = events.filter((event) => event.type === "keydown").length;
+
+    return {
+        eventCount: events.length,
+        errorCount,
+        consoleErrorCount,
+        pages,
+        clicks,
+        keydowns
+    };
+}
+
+/**
+ * 简单渲染当前记录，可选。
+ * V1 可以只在调试面板里显示最近几条。
+ */
+function renderDebugRecordPreview(record) {
+    const panel = document.getElementById("debugRecordPreview");
+    if (!panel) return;
+
+    const latestEvents = record.events.slice(-10);
+
+    panel.innerHTML = latestEvents
+        .map((event) => {
+            return `<div class="debug-event">
+        <span>${escapeHtml(formatEventForStudent(event))}</span>
+      </div>`;
+        })
+        .join("");
+}
+
+/**
+ * 把事件翻译成学生能看懂的话。
+ */
+function formatEventForStudent(event) {
+    const time = event.time ? event.time.slice(11, 19) : "";
+
+    if (event.type === "page-enter") {
+        return `${time} 进入页面：${event.pageTitle || event.pagePath || event.pageUrl}`;
+    }
+
+    if (event.type === "click") {
+        const text = event.payload && event.payload.text;
+        const selector = event.payload && event.payload.selector;
+        return `${time} 点击：${text || selector || "某个元素"}`;
+    }
+
+    if (event.type === "keydown") {
+        const code = event.payload && event.payload.code;
+        return `${time} 按键：${code || "未知按键"}`;
+    }
+
+    if (event.type === "console") {
+        const level = event.payload && event.payload.level;
+        const message = event.payload && event.payload.message;
+        return `${time} 程序输出(${level})：${message || ""}`;
+    }
+
+    if (event.type === "runtime-error") {
+        const message = event.payload && event.payload.message;
+        return `${time} 程序报错：${message || "未知错误"}`;
+    }
+
+    if (event.type === "unhandledrejection") {
+        const message = event.payload && event.payload.message;
+        return `${time} 异步错误：${message || "未知错误"}`;
+    }
+
+    if (event.type === "resource-error") {
+        const url = event.payload && event.payload.url;
+        return `${time} 资源加载失败：${url || "未知资源"}`;
+    }
+
+    return `${time} ${event.type}`;
+}
+
+function escapeHtml(text) {
+    return String(text)
+        .replaceAll("&", "&amp;")
+        .replaceAll("<", "&lt;")
+        .replaceAll(">", "&gt;")
+        .replaceAll('"', "&quot;")
+        .replaceAll("'", "&#039;");
+}
+
+/**
+ * UI 状态钩子。
+ */
+function setPreviewState(state) {
+    document.body.dataset.previewState = state;
+
+    const submitBugButton = document.getElementById("submitBugButton");
+
+    if (submitBugButton) {
+        // iframe 关闭并成功生成调试记录后，才允许提交 bug。
+        submitBugButton.disabled = state !== "debug-record-ready";
+    }
+}
+
+/**
+ * 启动监听。
+ */
+window.addEventListener("message", handleProbeMessage);
+
+// 暴露给预览弹框（artifacts）调用：开始录制 / 关闭并保存。
+window.startDebugRecord = startDebugRecord;
+window.closePreviewAndSaveDebugRecord = closePreviewAndSaveDebugRecord;