@aiyiran/myclaw 1.1.169 → 1.1.171

package/CLAUDE.md

@@ -132,8 +132,8 @@ voice-output.js → voice-input.js → myclaw-tts.js
   ▼        ▼
 服务端（sync_workspace.py，本机 18800 / 远程经 nginx /sync）
   ├─ 按 workspace 自行算目录，写两个文件：
-  │     debug-data.js   ← 每次覆盖，window.__DEBUG_DATA__ = {规范化记录}（数据，喂渲染也给 AI 读）
-  │     debug-record.html ← 恒定壳，含 CSS + 前端渲染器，运行时加载 debug-data.js 渲染
+  │     __debug-data__.js   ← 每次覆盖，window.__DEBUG_DATA__ = {规范化记录}（数据，喂渲染也给 AI 读）
+  │     调试日志.html ← 恒定壳，含 CSS + 前端渲染器，运行时加载 __debug-data__.js 渲染
   ▼
 同步循环 → 上传 CDN → 可展示给学生
 ```
@@ -144,7 +144,7 @@ voice-output.js → voice-input.js → myclaw-tts.js
 |------|------|------|--------|
 | **probe**（采集侧） | `assets/debug-probe.js` | 在 iframe 内采集现场，`postMessage` 上报 | traceId、workspace、上传、判因 |
 | **collector**（接收侧） | `assets/debug-collector.js` | 父页面收事件、攒记录、关闭时提交 | probe 注入、AI 修复、HTML 模板 |
-| **server**（落库侧） | `server/debug_record.py` | 算目录、校验、normalize、写 debug-data.js + 恒定 HTML 壳 | 采集、CDN 上传（交给同步循环） |
+| **server**（落库侧） | `server/debug_record.py` | 算目录、校验、normalize、写 __debug-data__.js + 恒定 HTML 壳 | 采集、CDN 上传（交给同步循环） |
 | **renderer**（渲染侧） | HTML 壳内联 JS（`render_shell_html()` 里） | 读 `window.__DEBUG_DATA__`，渲染小结/线索/回放 | 数据清洗（服务端做） |
 
 ### 关键设计约束（改之前先读）
@@ -161,9 +161,9 @@ voice-output.js → voice-input.js → myclaw-tts.js
 5. **前端不传文件路径**。前端只传逻辑字段（claw / workspace / entryFile），**服务端自己算目录**。`claw` 不是路径层级，只用于跟本机 `CLAW_NAME` 校验防串写；真实路径是 `{openclaw_root}/{workspace}/debug/`。
 
 6. **数据/渲染分离，落盘两个文件**（固定文件名，每次覆盖）：
-   - `debug-data.js`：`window.__DEBUG_DATA__ = {...}`，唯一数据源（喂前端渲染 + 给 AI 直接读）。
-   - `debug-record.html`：**恒定壳**，内容不随数据变（哈希不变 → 同步不会反复当成更新）。壳内联 CSS + 渲染器 JS，运行时用 `debug-data.js?t=<时间戳>` 动态加载绕 CDN 缓存。
-   - ⚠️ 渲染逻辑（事件转写 / 错误解释 / 线索提取）现在在**前端 JS**（`render_shell_html()` 里），不在 Python。改文案/样式改这里，且因为壳恒定，AI 修 bug 应读 `debug-data.js` 而非 HTML。
+   - `__debug-data__.js`：`window.__DEBUG_DATA__ = {...}`，唯一数据源（喂前端渲染 + 给 AI 直接读）。
+   - `调试日志.html`：**恒定壳**，内容不随数据变（哈希不变 → 同步不会反复当成更新）。壳内联 CSS + 渲染器 JS，运行时用 `__debug-data__.js?t=<时间戳>` 动态加载绕 CDN 缓存。
+   - ⚠️ 渲染逻辑（事件转写 / 错误解释 / 线索提取）现在在**前端 JS**（`render_shell_html()` 里），不在 Python。改文案/样式改这里，且因为壳恒定，AI 修 bug 应读 `__debug-data__.js` 而非 HTML。
 
 ### 接口
 
@@ -192,4 +192,4 @@ voice-output.js → voice-input.js → myclaw-tts.js
 ### 已知待办
 
 - 整链路端到端实测（单测已过，未在真实 gateway + 同步进程跑通）。
-- `{workspace}/debug/debug-record.html` 会进 `__MY_ARTIFACTS__.json` 作品列表，是否需要从列表过滤、改走专门入口，待定。
+- `{workspace}/debug/调试日志.html` 会进 `__MY_ARTIFACTS__.json` 作品列表，是否需要从列表过滤、改走专门入口，待定。

package/assets/myclaw-artifacts.js

@@ -424,6 +424,7 @@
       '__teacher__.json',
       '__teacher-view__.html',
       '__任务__.html',
+      '__debug-data__.js',
       'USER.md',
       'TOOLS.md',
       'SOUL.md',

package/assets/myclaw-inject.js

@@ -325,34 +325,20 @@
 
   // ═══ 3. Debug 按钮 ═══
 
-  function buildTestDonePrompt() {
-    var rec = window.myclawLastDebugRecord;
+  function buildTestDonePrompt(keepLogs) {
     var lines = ["我刚才已经完成了测试。"];
 
-    // 调试数据落在 debug-data.js（window.__DEBUG_DATA__ = {...}），AI 直接读这个
-    // 数据文件即可，不要读同目录的 debug-record.html（那只是给人看的渲染壳）。
-    var dataFile = null;
-    if (rec) {
-      if (rec.debugRecordPath) {
-        dataFile = rec.debugRecordPath.replace(/debug-record\.html$/, "debug-data.js");
-      } else if (rec.workspace) {
-        dataFile = rec.workspace + "/debug/debug-data.js";
-      }
-    }
-    if (dataFile) {
-      lines.push("请你读取调试数据文件：" + dataFile);
-    } else {
-      lines.push("请你读取本次测试的调试数据文件 debug/debug-data.js。");
-    }
-    lines.push("它是一行 `window.__DEBUG_DATA__ = {...}` 的赋值，里面的 events 数组就是完整运行现场；不要去读同目录的 debug-record.html。");
-    if (rec && rec.entryFile) {
-      lines.push("我刚才测试的文件是：" + rec.entryFile);
-    }
+    lines.push("请你读取调试数据文件 debug/__debug-data__.js，它是一行 `window.__DEBUG_DATA__ = {...}` 的赋值，里面的 events 数组就是完整运行现场。");
 
     lines.push("");
     lines.push("请帮我判断：我们之前的问题是否已经修复。");
     lines.push("如果已经修复，请简单说明你从 events 里看到了什么证据。");
     lines.push("如果还没有修复，请指出 events 里最关键的问题，并建议下一步最小修改。");
+    if (keepLogs) {
+      lines.push("请保留现有调试日志，不要删除或精简这些 console.log，后面还要继续观察。");
+    } else {
+      lines.push("如果你确认问题已经修复，请把为了调试临时添加的 console.log / 运行提示清理掉；如果还没修复，请先保留必要日志。");
+    }
 
     return lines.join("\n");
   }
@@ -387,9 +373,7 @@
 
     menu.appendChild(makeItem("查报错", showDebugModal));
     menu.appendChild(makeItem("加日志", showLogModal));
-    menu.appendChild(makeItem("看结果", function () {
-      sendGeneratedPrompt(buildTestDonePrompt());
-    }));
+    menu.appendChild(makeItem("看结果", showTestDoneModal));
 
     wrap.appendChild(btn);
     wrap.appendChild(menu);
@@ -417,6 +401,11 @@
     if (modal) modal.remove();
   }
 
+  function closeTestDoneModal() {
+    var modal = document.getElementById("myclaw-test-done-modal");
+    if (modal) modal.remove();
+  }
+
   function makeDebugLabel(text) {
     var label = document.createElement("div");
     label.textContent = text;
@@ -571,30 +560,16 @@
     var state = { description: "" };
 
     function buildDebugPrompt() {
-      var rec = window.myclawLastDebugRecord;
       var lines = [];
 
-      // 调试数据现在落在 debug-data.js（window.__DEBUG_DATA__ = {...}），
-      // 与 debug-record.html 同目录。AI 直接读这个数据文件即可，不用读 HTML。
-      var dataFile = null;
-      if (rec) {
-        if (rec.debugRecordPath) {
-          dataFile = rec.debugRecordPath.replace(/debug-record\.html$/, "debug-data.js");
-        } else if (rec.workspace) {
-          dataFile = rec.workspace + "/debug/debug-data.js";
-        }
-      }
-      if (dataFile) {
-        lines.push("调试数据文件：" + dataFile);
-        lines.push("");
-      }
-
+      lines.push("调试数据文件：debug/__debug-data__.js");
+      lines.push("");
       lines.push("学生描述：" + (state.description || "（未填写）"));
       lines.push("");
       lines.push("请从学生描述里提取：我做了什么、发生了什么、我的预期是什么。");
       lines.push("");
       lines.push("如何阅读调试数据（按下面抓重点，别东翻西找）：");
-      lines.push("1. 读上面的调试数据文件 debug-data.js，它是一行 `window.__DEBUG_DATA__ = {...}` 的赋值，里面的 events 数组就是完整运行现场。（不要去读同目录的 debug-record.html，那只是给人看的渲染壳。）");
+      lines.push("1. 读调试数据文件 debug/__debug-data__.js，它是一行 `window.__DEBUG_DATA__ = {...}` 的赋值，里面的 events 数组就是完整运行现场。");
       lines.push("2. 先在 events 里找 runtime-error / unhandledrejection / 以及 payload.level 为 error 的 console 事件，它们是问题的起点。");
       lines.push("3. 抓住报错事件的 message、stack、filename、lineno——直接定位到源码里出错的那个函数/那几行，只看相关代码段，不要通读整个作品文件。");
       lines.push("4. 再倒着看报错之前的 page-enter / click / keydown / console，还原“做了什么 → 触发了什么”的因果链，确认重现路径。");
@@ -691,15 +666,13 @@
 
     function buildLogPrompt() {
       var lines = [];
-      lines.push("我需要你帮我添加一些调试信息，我希望调试信息非常清晰、全面。");
-      lines.push("我正在解决的问题是关于：" + state.problem);
+      lines.push("目前的信息如下：debug/__debug-data__.js");
+      lines.push("我要解决一个问题：" + state.problem);
       lines.push("");
-      lines.push("这些调试信息后续会给到你，用来帮我继续解决问题。");
-      lines.push("");
-      lines.push("请只添加调试信息，不要顺手修改功能逻辑。");
       lines.push("请优先添加 console.log，文字要清楚，适合小学生看懂。");
       lines.push("请在关键步骤都加上信息，比如：有没有点到、进入了哪一步、重要变量现在是多少、为什么没有继续。");
-      lines.push("改完后告诉我：你在哪些地方加了提示、每条提示能帮我看出什么。");
+      lines.push("");
+      lines.push("另外，你帮我看一下，如果你能直接找到原因就先尝试修复一下。如果不容易找到，就仅仅加日志。但是，日志一定要加。");
       return lines.join("\n");
     }
 
@@ -787,6 +760,61 @@
     problemField.focus();
   }
 
+  function showTestDoneModal() {
+    if (document.getElementById("myclaw-test-done-modal")) return;
+
+    var overlay = document.createElement("div");
+    overlay.id = "myclaw-test-done-modal";
+
+    var box = document.createElement("div");
+    box.className = "myclaw-debug-box myclaw-test-done-box";
+
+    var header = document.createElement("div");
+    header.className = "myclaw-debug-header myclaw-test-done-header";
+    header.innerHTML = "<span>✅ 看测试结果</span>";
+    var closeX = document.createElement("span");
+    closeX.textContent = "✕";
+    closeX.className = "myclaw-debug-close";
+    closeX.onclick = function () { closeTestDoneModal(); };
+    header.appendChild(closeX);
+
+    var body = document.createElement("div");
+    body.className = "myclaw-test-done-body";
+    body.textContent = "让 AI 看刚才的测试日志，并判断问题有没有修好。";
+
+    var footer = document.createElement("div");
+    footer.className = "myclaw-test-done-actions";
+
+    function makeAction(text, className, keepLogs) {
+      var btn = document.createElement("button");
+      btn.type = "button";
+      btn.className = className;
+      btn.textContent = text;
+      btn.addEventListener("click", function () {
+        closeTestDoneModal();
+        sendGeneratedPrompt(buildTestDonePrompt(keepLogs));
+      });
+      return btn;
+    }
+
+    var keepBtn = makeAction("检查并保留日志", "myclaw-test-done-keep", true);
+    var cleanBtn = makeAction("检查并去掉日志", "myclaw-test-done-clean", false);
+    var cancelBtn = document.createElement("button");
+    cancelBtn.type = "button";
+    cancelBtn.className = "myclaw-test-done-cancel";
+    cancelBtn.textContent = "取消";
+    cancelBtn.addEventListener("click", function () { closeTestDoneModal(); });
+
+    footer.appendChild(keepBtn);
+    footer.appendChild(cleanBtn);
+    footer.appendChild(cancelBtn);
+    box.appendChild(header);
+    box.appendChild(body);
+    box.appendChild(footer);
+    overlay.appendChild(box);
+    document.body.appendChild(overlay);
+  }
+
   // ═══ 3.1 Prompt 小助手按钮（实现见 myclaw-iteration.js） ═══
 
   function createPromptButton() {
@@ -1109,7 +1137,7 @@ btn.addEventListener("click", function () {
       "  to { opacity: 1; }",
       "}",
       /* Debug 提交弹框 */
-      "#myclaw-debug-modal, #myclaw-log-modal {",
+      "#myclaw-debug-modal, #myclaw-log-modal, #myclaw-test-done-modal {",
       "  position: fixed; inset: 0; z-index: 99999;",
       "  background: rgba(0,0,0,0.45);",
       "  display: flex; align-items: center; justify-content: center;",
@@ -1131,6 +1159,9 @@ btn.addEventListener("click", function () {
       ".myclaw-log-header {",
       "  background: linear-gradient(135deg,#0ea5e9,#6366f1);",
       "}",
+      ".myclaw-test-done-header {",
+      "  background: linear-gradient(135deg,#10b981,#14b8a6);",
+      "}",
       ".myclaw-debug-close {",
       "  cursor: pointer; padding: 2px 8px; border-radius: 4px; font-size: 15px;",
       "}",
@@ -1173,6 +1204,26 @@ btn.addEventListener("click", function () {
       ".myclaw-debug-submit:disabled {",
       "  cursor: not-allowed;",
       "}",
+      ".myclaw-test-done-box { width: 460px; }",
+      ".myclaw-test-done-body {",
+      "  padding: 20px; color: #cdd6f4; font-size: 14px;",
+      "  line-height: 1.7; font-family: -apple-system,sans-serif;",
+      "}",
+      ".myclaw-test-done-actions {",
+      "  display: flex; flex-direction: column; gap: 10px;",
+      "  padding: 0 20px 20px;",
+      "}",
+      ".myclaw-test-done-actions button {",
+      "  padding: 11px 12px; border: none; border-radius: 8px;",
+      "  color: #fff; font-size: 14px; font-weight: bold;",
+      "  font-family: -apple-system,sans-serif; cursor: pointer;",
+      "}",
+      ".myclaw-test-done-keep { background: #10b981; }",
+      ".myclaw-test-done-clean { background: #6366f1; }",
+      ".myclaw-test-done-cancel { background: #3d3d5c; color: #cdd6f4 !important; }",
+      ".myclaw-test-done-keep:hover { background: #059669; }",
+      ".myclaw-test-done-clean:hover { background: #4f46e5; }",
+      ".myclaw-test-done-cancel:hover { background: #4b4b6a; }",
     ].join("\n");
     document.head.appendChild(style);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiyiran/myclaw",
-  "version": "1.1.169",
+  "version": "1.1.171",
   "description": "",
   "main": "index.js",
   "bin": {

package/patches/patch-manifest.json

@@ -29,6 +29,11 @@
       "name": "chat-history-extractor",
       "strategy": "on",
       "description": "从 OpenClaw session URL 提取并渲染聊天记录"
+    },
+    {
+      "name": "yiran-skill-session-rollback",
+      "strategy": "on",
+      "description": "把会话还原到上一版 transcript（从 *.jsonl.reset 归档回滚）"
     }
   ],
   "_doc_agents": "Step 3: 将 agent-list/ 下的智能体分发到 ~/.openclaw/ 并注册到 openclaw.json",

package/server/debug_record.py

@@ -5,20 +5,20 @@ debug_record.py
 把前端收集到的 currentDebugRecord 落盘成两个文件，供学生/老师/AI 查看。
 
 【架构：数据与渲染分离】
-- debug-data.js   —— 每次覆盖写。内容是 `window.__DEBUG_DATA__ = {规范化后的记录}`。
+- __debug-data__.js   —— 每次覆盖写。内容是 `window.__DEBUG_DATA__ = {规范化后的记录}`。
                      这是**唯一数据源**：既喂前端渲染，也给 AI 直接读。
-- debug-record.html —— 恒定的“壳”。包含 CSS + 前端渲染器 JS，运行时动态加载
-                     debug-data.js 并渲染。内容不随数据变化，因此同步循环不会
+- 调试日志.html —— 恒定的“壳”。包含 CSS + 前端渲染器 JS，运行时动态加载
+                     __debug-data__.js 并渲染。内容不随数据变化，因此同步循环不会
                      反复把它当成“更新”重传。
 
 为什么这么拆：
 1. HTML 壳恒定 → 哈希不变 → 不再被同步误判为更新（根除循环上传问题）。
-2. AI 读的是纯数据 debug-data.js，信噪比高，不掺样式。
+2. AI 读的是纯数据 __debug-data__.js，信噪比高，不掺样式。
 3. 渲染逻辑在前端，改样式不用动 Python、不用重启同步进程。
 
 服务端职责（本文件）：
 - 接收 / 校验 / normalize 记录
-- 写出 debug-data.js 和 debug-record.html
+- 写出 __debug-data__.js 和 调试日志.html
 渲染职责（前端，在 HTML 壳的内联 JS 里）：
 - 读 window.__DEBUG_DATA__，渲染小结 / 线索 / 运行回放 / 原始数据
 
@@ -65,7 +65,7 @@ ERROR_EVENT_TYPES = {
 
 
 # =============================================================================
-# 2. 保存层：写 debug-data.js + 恒定的 debug-record.html 壳
+# 2. 保存层：写 __debug-data__.js + 恒定的 调试日志.html 壳
 # =============================================================================
 
 
@@ -74,8 +74,8 @@ 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-data__.js     每次覆盖，内容 = window.__DEBUG_DATA__ = {normalized record}
+    - 调试日志.html 恒定壳（内容不变），负责加载并渲染上面的数据
     """
     debug_dir.mkdir(parents=True, exist_ok=True)
 
@@ -83,12 +83,12 @@ def save_debug_record(record: Dict[str, Any], debug_dir: Path) -> Dict[str, str]
 
     # 数据文件：每次覆盖
     data_js = "window.__DEBUG_DATA__ = " + safe_json_for_js(normalized_record) + ";\n"
-    data_path = debug_dir / "debug-data.js"
+    data_path = debug_dir / "__debug-data__.js"
     write_text_atomic(data_path, data_js)
 
     # HTML 壳：内容恒定（不含数据）。每次都写没关系——内容一致，
     # 基于内容哈希的同步不会把它当成变更重传。
-    html_path = debug_dir / "debug-record.html"
+    html_path = debug_dir / "调试日志.html"
     write_text_atomic(html_path, render_shell_html())
 
     return {"html_path": str(html_path), "data_path": str(data_path)}
@@ -181,7 +181,7 @@ def handle_save_request(body: Dict[str, Any], openclaw_root: str, server_claw: s
     paths = save_debug_record(body, debug_dir)
 
     cdn_base = f"https://cdn.yiranlaoshi.com/{claw}"
-    debug_record_url = f"{cdn_base}/{workspace}/debug/debug-record.html"
+    debug_record_url = f"{cdn_base}/{workspace}/debug/调试日志.html"
 
     record = normalize_record(body)
 
@@ -206,7 +206,7 @@ def assert_safe_id(value: str, field_name: str) -> None:
 
 
 # =============================================================================
-# 4. record / event 规范化（数据清洗留在服务端，输出进 debug-data.js）
+# 4. record / event 规范化（数据清洗留在服务端，输出进 __debug-data__.js）
 # =============================================================================
 
 
@@ -391,7 +391,7 @@ def safe_json_for_js(value: Any) -> str:
 # 这个函数返回的内容**不随数据变化**，是纯静态的“壳”：
 #   - <style> 页面样式
 #   - 前端渲染器 JS（事件转写 / 错误解释 / 线索提取 / DOM 渲染）
-#   - 运行时动态加载 debug-data.js?t=<时间戳> 绕开 CDN 缓存
+#   - 运行时动态加载 __debug-data__.js?t=<时间戳> 绕开 CDN 缓存
 # 渲染逻辑是从原 Python 函数（format_replay_event / simplify_error_message /
 # extract_clues / render_*）逐一移植过来的 JS 版本。
 #
@@ -719,13 +719,13 @@ def render_shell_html() -> str:
 
     // 动态加载数据，带时间戳绕开 CDN 缓存（壳恒定，数据每次新）
     var s = document.createElement("script");
-    s.src = "debug-data.js?t=" + Date.now();
+    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.getElementById("dynamic").textContent = "调试数据加载失败（__debug-data__.js）";
     };
     document.head.appendChild(s);
   })();

package/server/sync_workspace.py

@@ -477,8 +477,8 @@ def _put_file_to_qiniu(token, key, abs_path):
     """统一上传入口。HTML 文件注入 probe 后以字节上传；其余走原始文件上传。"""
     ext = os.path.splitext(abs_path)[1].lower()
     if ext in (".html", ".htm"):
-        # debug-record.html 是展示壳，不是学生作品，跳过 probe 注入
-        if os.path.basename(abs_path) != "debug-record.html":
+        # 调试日志.html 是展示壳，不是学生作品，跳过 probe 注入
+        if os.path.basename(abs_path) != "调试日志.html":
             with open(abs_path, "rb") as f:
                 data = inject_probe_into_html(f.read())
             return put_data(token, key, data, mime_type="text/html")

package/skills/yiran-skill-session-rollback/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: yiran-skill-session-rollback
+description: Restore an OpenClaw conversation/session to its previous transcript version by locating the right session key, current sessionId, and archived `*.jsonl.reset.<timestamp>` transcript, then repointing the key back to the chosen prior version. Use when the user asks to recover a chat, roll back a conversation, restore the previous version of a session, or revert a session after reset. Trigger even if the user provides only a session id fragment, a TUI id, an agent name, or conversation text and you need to search for the matching session first.
+---
+
+Restore the target conversation to an earlier transcript version.
+
+Read `references/usage-and-design.md` when you need the full design rationale, safety model, or the division of labor between skill, script, and agent judgment.
+
+## Previous version definition
+
+**Previous version / 上一版** means:
+
+> For a given session key, the most recent valid transcript version that directly preceded the current live version.
+
+Use these rules:
+
+1. Treat the `sessionId` currently referenced by `sessions.json` as the **current version**.
+2. Look for the most recent prior transcript that can be tied to the same session key with high confidence.
+3. If there is exactly one clear prior candidate, that candidate is the **previous version**.
+4. If multiple reasonable prior candidates exist, treat "previous version" as **ambiguous** and ask the user before switching.
+
+Important clarifications:
+
+- "Previous version" is **not** the oldest version.
+- "Previous version" is **not** just the newest `*.jsonl.reset.*` file anywhere in the agent directory.
+- "Previous version" means the **direct predecessor** of the current live version for that specific session key.
+- In simple one-main-session agents, a single reset archive is often sufficient to define the previous version.
+- In complex agents with multiple historical branches, never guess.
+
+## Workflow
+
+1. Identify the target session.
+   - Accept any of these as clues:
+     - full session key, like `agent:daidai:main`
+     - agent name, like `daidai`
+     - TUI id, like `tui-...`
+     - partial session id
+     - distinctive text from the conversation
+   - Prefer the bundled discovery script first:
+     - `scripts/find_session_candidates.py <query> [--agent <agentId>] [--limit N]`
+   - Search `~/.openclaw/agents/*/sessions/sessions.json` and the sibling transcript files until one session is clearly identified.
+   - If multiple candidates remain, stop and ask the user to disambiguate.
+   - Treat short aliases like `ming` as likely human shorthand for the agent (`mingzi`) if the match is unique; otherwise ask.
+
+2. Inspect the session store before editing.
+   - Read the target agent's `sessions.json`.
+   - Record:
+     - current `sessionId`
+     - current `sessionFile`
+     - matching reset archives in the same `sessions/` directory
+   - Prefer the **most recent previous version** unless the user explicitly asks for an older one.
+
+3. Verify that the rollback target is real.
+   - Prefer a reset archive that can be tied to the target session key by explicit text evidence inside the transcript.
+   - If explicit evidence is unavailable, use stronger heuristics only when the mapping is unambiguous.
+   - A single reset archive in that agent's session directory is usually acceptable as the "previous version" candidate for a simple `agent:<id>:main` test restore.
+   - If the mapping is ambiguous, do not guess.
+
+4. Restore both index and transcript file.
+   - Prefer the bundled script for the final switch step:
+     - `scripts/rollback_session.py --agent <agentId> --key <sessionKey> --target-session-id <oldSessionId> [--archive <path>]`
+   - The script updates `sessions.json`, restores `<sessionId>.jsonl` from an archive when needed, and leaves safety backups behind.
+   - Keep archive files in place unless the user explicitly asks to delete them.
+
+5. Prevent immediate re-breakage.
+   - If the environment still uses aggressive reset rules and the user is likely to test immediately, warn that the next message may mint a fresh session again.
+   - If the user asked to make rollback stick, suggest changing `session.reset` to a longer `idle` policy before testing.
+
+6. Reload runtime state when needed.
+   - Restart the gateway if the session store is cached in memory or if the user asks for a full refresh.
+
+7. Report exactly what changed.
+   - Include:
+     - resolved session key
+     - old sessionId
+     - restored sessionId
+     - whether transcript file had to be recreated from `.reset`
+     - where the previous live version was backed up
+     - whether a gateway restart was performed
+
+## Safety rules
+
+- Back up `sessions.json` before editing it.
+- Preserve the current live transcript before switching.
+  - The bundled script copies the current `.jsonl` to a timestamped `.manual-switch-backup.*` file so a mistaken switch can be undone without loss.
+- Do not batch-edit unrelated sessions unless the user explicitly asked for that.
+- Do not claim success based only on `sessions.json`; confirm the target `.jsonl` file exists.
+- Do not guess across multiple ambiguous candidates.
+
+## Fast search hints
+
+Use these patterns when searching:
+
+- key search:
+  - `agent:<agentId>:main`
+  - `agent:<agentId>:tui-...`
+- transcript archives:
+  - `*.jsonl.reset.*`
+- clue text:
+  - grep distinctive conversation text across `~/.openclaw/agents/*/sessions/*`
+
+## Typical recovery logic
+
+1. Find session key.
+2. Find current `sessionId` in `sessions.json`.
+3. Find the previous archived transcript for that same session.
+4. Run `scripts/rollback_session.py` to:
+   - back up `sessions.json`
+   - back up the current live transcript
+   - restore the target transcript file if needed
+   - rewrite `sessions.json` to point back to the target session
+5. Restart gateway if required.
+
+## When to stop and ask
+
+Stop and ask if:
+- more than one session matches the user's clue
+- the reset archive cannot be tied to the target session confidently
+- the user asks for "the earliest version" and there are multiple historical candidates with no clear chain

package/skills/yiran-skill-session-rollback/references/usage-and-design.md

@@ -0,0 +1,291 @@
+# Session Rollback Skill - Usage and Design
+
+这份说明面向两类读者：
+
+- **人类维护者**：想知道这个 skill 到底怎么工作、边界在哪里
+- **AI/agent**：想知道什么时候该用 skill，什么时候该停下来问用户
+
+---
+
+## 1. 能力边界
+
+这个 skill 解决的是：
+
+> 把某个 OpenClaw 会话 key 重新指回某个更早的 transcript 版本。
+
+它不是“修复所有历史问题”的万能工具，而是一个**安全切换器**。
+
+它做的事情包括：
+
+1. 定位目标会话
+2. 找到要恢复的旧 transcript 版本
+3. 保留当前 live 版本备份
+4. 把 session key 改指到旧版本
+5. 必要时恢复 `<sessionId>.jsonl`
+6. 必要时提醒重启 gateway
+
+---
+
+## 2. 实际工作分层
+
+这套能力分三层：
+
+### A. Skill（流程层）
+`SKILL.md` 负责：
+
+- 定义什么时候触发这个能力
+- 规定恢复流程
+- 规定什么时候可以自动做
+- 规定什么时候必须停下来问用户
+
+### B. Script（执行层）
+`scripts/rollback_session.py` 负责：
+
+- 备份 `sessions.json`
+- 备份当前 live transcript
+- 恢复目标 transcript 文件
+- 改写 `sessions.json`
+
+### C. Agent 判断（决策层）
+模型负责：
+
+- 从用户线索里定位目标 session
+- 判断“上一版”是不是唯一明确
+- 判断是否有歧义
+- 决定是否需要重启 gateway
+
+一句话：
+
+> **skill 定流程，脚本做切换，agent 负责判断。**
+
+---
+
+## 3. 为什么不能只靠脚本
+
+脚本适合做“已知目标”的安全切换。
+
+但用户经常不会直接给：
+
+- 完整 session key
+- 完整旧 session id
+- 完整 archive 路径
+
+用户更可能只给：
+
+- agent 名字
+- 一段对话文本
+- 一个 TUI id
+- “切回上一版”
+
+这些都需要 agent 先做定位和判断。
+
+所以：
+
+- **纯脚本不够用**
+- **纯 prompt 也不稳定**
+- 最合理的是：**skill + script + agent 判断**
+
+---
+
+## 4. 为什么切换时必须保留当前版本
+
+恢复动作本身也可能出错，比如：
+
+- 目标选错了
+- “上一版”理解错了
+- 用户其实想回到更早版本
+- 同一个 agent 下有多个历史候选
+
+所以切换时必须默认保留当前 live 版本。
+
+当前脚本已经这样做：
+
+- 备份 `sessions.json`
+- 备份当前 `.jsonl`
+
+这样即使切错，也能无损切回来。
+
+这是这个 skill 的核心安全原则之一。
+
+---
+
+## 5. “上一版” 的正式定义
+
+**上一版 / previous version** 指的是：
+
+> 对某个 session key 来说，当前 live 版本之前最近一次有效绑定的 transcript 版本。
+
+判断规则：
+
+1. 先把 `sessions.json` 当前指向的 `sessionId` 视为**当前版**。
+2. 再寻找与该 session key 高置信关联的最近前身 transcript。
+3. 如果只有一个明确候选，它就是**上一版**。
+4. 如果存在多个合理候选，则“上一版”视为**有歧义**，必须先向用户确认。
+
+特别说明：
+
+- 上一版**不是**最老版本
+- 上一版**不是**目录里最新的任意 `*.jsonl.reset.*`
+- 上一版是**当前版本的直接前身**
+- 对简单单主会话 agent，唯一 reset 档案通常足以定义上一版
+- 对复杂多分支 agent，不能靠猜
+
+## 6. 什么情况下可以自动切
+
+可以自动切的典型情况：
+
+### 情况 A：用户给了明确目标
+例如：
+
+- `session key = agent:main:main`
+- `session id = 50b65539-...`
+
+这种情况可以直接执行。
+
+### 情况 B：只有一个明确的上一版候选
+例如：
+
+- 某个 agent 的 `main` 当前只有一份 `*.jsonl.reset.*`
+- 没有多份歧义历史
+
+这种情况下，“切到上一版”可以直接做。
+
+---
+
+## 6. 什么情况下必须停下来问
+
+必须停下来问的典型情况：
+
+### 情况 A：存在多个历史候选
+例如：
+
+- `agent:main:main` 这种会有多份 reset 档案
+- “上一版”可能有多种理解
+
+### 情况 B：找不到能明确绑定到这个 key 的 archive
+例如：
+
+- reset 文件存在
+- 但无法判断它是否真属于当前目标 session
+
+### 情况 C：用户给的线索太模糊
+例如：
+
+- 只说“帮我恢复 main”
+- 但有多个 main-like 对话
+
+这时不要猜。
+
+---
+
+## 7. 当前脚本的职责
+
+`scripts/rollback_session.py` 当前已经支持：
+
+- 指定 agent
+- 指定 session key
+- 指定目标 session id
+- 可选指定 archive 路径
+- 自动备份当前 live transcript
+- 自动备份 `sessions.json`
+- 自动恢复目标 `.jsonl`
+
+它当前**不负责**：
+
+- 从模糊文本自动搜索候选 session
+- 自动决定哪个才是“上一版”
+- 自动批量处理多个歧义 session
+
+这些仍然属于 agent 决策层。
+
+---
+
+## 8. 推荐使用方式
+
+### 场景 1：明确恢复到指定版本
+直接调用脚本：
+
+```bash
+python3 skills/yiran-skill-session-rollback/scripts/rollback_session.py \
+  --agent main \
+  --key agent:main:main \
+  --target-session-id 50b65539-0224-4f97-ae29-10e3fda589fc \
+  --archive /Users/.../50b65539-0224-4f97-ae29-10e3fda589fc.jsonl.reset....
+```
+
+### 场景 2：恢复到“上一版”
+先由 agent：
+
+1. 定位目标 session
+2. 判断唯一上一版候选
+3. 再调用脚本
+
+---
+
+## 9. 当前成熟度
+
+目前这个 skill 的成熟度可以定义为：
+
+> **半自动、可安全执行的 session rollback 工具**
+
+这意味着：
+
+- 单次恢复已经比较稳
+- 有回滚保护
+- 适合人工确认后执行
+- 还不适合无监督批量自动恢复复杂多分支历史
+
+---
+
+## 10. 当前脚本清单
+
+### `scripts/find_session_candidates.py`
+作用：
+- 输入 agent 名 / 文本 / TUI id / session id 片段
+- 输出候选 session 列表
+- 只做查找，不做修改
+
+示例：
+
+```bash
+python3 skills/yiran-skill-session-rollback/scripts/find_session_candidates.py ming --limit 5
+python3 skills/yiran-skill-session-rollback/scripts/find_session_candidates.py tui-65d670f7 --limit 5
+python3 skills/yiran-skill-session-rollback/scripts/find_session_candidates.py "假设现场出现 5 种常见对话" --agent sun --limit 5
+```
+
+注意：
+- 它会给出排序和命中原因
+- 如果有多个接近候选，仍然应该先问用户，不要直接切
+
+### `scripts/rollback_session.py`
+作用：
+- 在目标已明确时，安全切换到旧版本
+- 自动保留当前 live 版本备份
+
+---
+
+## 11. 后续可扩展方向
+
+如果以后还要增强，可以优先做：
+
+1. `find_previous_version.py`
+   - 自动给出“上一版”的候选与置信度
+
+2. 批量模式
+   - 只处理“唯一明确上一版”的 session
+   - 歧义项自动跳过并报告
+
+3. 更强的内容匹配
+   - 减少因为 transcript 文本偶然命中带来的噪音候选
+
+---
+
+## 11. 一句话总结
+
+这个 skill 的正确心智模型不是：
+
+> “一个神奇脚本，自动把一切恢复好”
+
+而是：
+
+> **一个安全恢复工作流：先判断，再切换，并且默认保留当前版本作为回滚点。**

package/skills/yiran-skill-session-rollback/scripts/find_session_candidates.py

@@ -0,0 +1,139 @@
+#!/usr/bin/env python3
+"""Find likely OpenClaw session candidates from vague user clues.
+
+This script is the discovery companion to `rollback_session.py`.
+It does not modify anything.
+
+Use it when the user provides incomplete input such as:
+- an agent name or shorthand
+- a TUI id fragment
+- a partial session id
+- a distinctive piece of conversation text
+- a partial session key
+
+The script searches `~/.openclaw/agents/*/sessions/` and returns ranked candidates.
+"""
+
+import argparse
+import json
+from pathlib import Path
+from typing import Dict, List, Tuple
+
+
+def load_json(path: Path):
+    with path.open('r', encoding='utf-8') as f:
+        return json.load(f)
+
+
+def safe_read_prefix(path: Path, max_chars: int = 12000) -> str:
+    try:
+        with path.open('r', encoding='utf-8', errors='ignore') as f:
+            return f.read(max_chars)
+    except Exception:
+        return ''
+
+
+def score_candidate(query: str, agent_id: str, key: str, item: dict, transcript_prefix: str) -> Tuple[int, List[str]]:
+    q = query.strip().lower()
+    score = 0
+    reasons: List[str] = []
+
+    hay_agent = agent_id.lower()
+    hay_key = key.lower()
+    hay_sid = str(item.get('sessionId', '')).lower()
+    hay_file = str(item.get('sessionFile', '')).lower()
+    hay_text = transcript_prefix.lower()
+
+    if q == hay_agent or q == agent_id:
+        score += 100
+        reasons.append('exact agent match')
+    elif q in hay_agent:
+        score += 40
+        reasons.append('agent substring match')
+
+    if q == hay_key:
+        score += 120
+        reasons.append('exact session key match')
+    elif q in hay_key:
+        score += 60
+        reasons.append('session key substring match')
+
+    if q and q in hay_sid:
+        score += 70
+        reasons.append('session id substring match')
+
+    if q and q in hay_file:
+        score += 20
+        reasons.append('session file path match')
+
+    if q and q in hay_text:
+        score += 50
+        reasons.append('transcript text match')
+
+    # helpful shorthand heuristics
+    if q == 'ming' and agent_id == 'mingzi':
+        score += 30
+        reasons.append('known shorthand: ming -> mingzi')
+
+    return score, reasons
+
+
+def main():
+    p = argparse.ArgumentParser(description='Find likely OpenClaw session candidates from vague clues.')
+    p.add_argument('query', help='Agent name, session key fragment, session id fragment, tui id, or distinctive text')
+    p.add_argument('--limit', type=int, default=10, help='Maximum candidates to print')
+    p.add_argument('--agent', help='Restrict search to one agent id')
+    p.add_argument('--include-transcript-prefix', action='store_true', help='Include a short transcript preview in output')
+    args = p.parse_args()
+
+    root = Path.home() / '.openclaw' / 'agents'
+    if not root.exists():
+        raise SystemExit('Agents directory not found')
+
+    candidates = []
+    for agent_dir in sorted(root.iterdir()):
+        if not agent_dir.is_dir():
+            continue
+        agent_id = agent_dir.name
+        if args.agent and agent_id != args.agent:
+            continue
+        sessions_dir = agent_dir / 'sessions'
+        sessions_json = sessions_dir / 'sessions.json'
+        if not sessions_json.exists():
+            continue
+        try:
+            data = load_json(sessions_json)
+        except Exception:
+            continue
+        for key, item in data.items():
+            if not isinstance(item, dict):
+                continue
+            session_file = Path(item.get('sessionFile', '')) if item.get('sessionFile') else None
+            prefix = safe_read_prefix(session_file) if session_file and session_file.exists() else ''
+            score, reasons = score_candidate(args.query, agent_id, key, item, prefix)
+            if score <= 0:
+                continue
+            candidates.append({
+                'score': score,
+                'reasons': reasons,
+                'agent': agent_id,
+                'key': key,
+                'sessionId': item.get('sessionId'),
+                'sessionFile': item.get('sessionFile'),
+                'updatedAt': item.get('updatedAt'),
+                'hasSessionFile': bool(session_file and session_file.exists()),
+                'transcriptPreview': prefix[:300] if args.include_transcript_prefix and prefix else None,
+            })
+
+    candidates.sort(key=lambda x: (-x['score'], str(x.get('updatedAt') or 0), x['key']))
+    result = {
+        'query': args.query,
+        'count': len(candidates),
+        'candidates': candidates[: args.limit],
+        'note': 'Use the top candidate only when the match is unambiguous. If several close candidates remain, ask the user to confirm.'
+    }
+    print(json.dumps(result, ensure_ascii=False, indent=2))
+
+
+if __name__ == '__main__':
+    main()

package/skills/yiran-skill-session-rollback/scripts/rollback_session.py

@@ -0,0 +1,149 @@
+#!/usr/bin/env python3
+"""Safely repoint an OpenClaw session key to an earlier transcript version.
+
+Design goals:
+- Make the final switch deterministic once a target sessionId is known.
+- Preserve the current live version before switching so mistakes are reversible.
+- Restore the target plain `.jsonl` file from an archive when needed.
+
+What this script does not do:
+- It does not discover the correct target from vague user language.
+- It does not decide which historical candidate is "the right one" when multiple
+  archives are plausible.
+
+Expected operating model:
+- An agent or human identifies the target session key and target session id first.
+- This script performs the safe on-disk switch.
+"""
+
+import argparse
+import json
+import shutil
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Optional, Tuple
+
+
+def now_tag() -> str:
+    return datetime.now(timezone.utc).strftime('%Y-%m-%dT%H-%M-%S.%fZ')
+
+
+def fail(msg: str, code: int = 1):
+    print(msg, file=sys.stderr)
+    raise SystemExit(code)
+
+
+def load_json(path: Path):
+    with path.open('r', encoding='utf-8') as f:
+        return json.load(f)
+
+
+def save_json(path: Path, data):
+    with path.open('w', encoding='utf-8') as f:
+        json.dump(data, f, ensure_ascii=False, indent=2)
+        f.write('\n')
+
+
+def backup_file(path: Path, suffix: str) -> Path:
+    """Create a timestamped backup next to the original file.
+
+    This is the core safety feature that makes mistaken switches reversible.
+    """
+    tag = now_tag()
+    backup = path.with_name(f"{path.name}.{suffix}.{tag}")
+    shutil.copy2(path, backup)
+    return backup
+
+
+def ensure_target_plain_file(sessions_dir: Path, target_session_id: str, archive_path: Optional[Path]) -> Tuple[Path, Optional[Path]]:
+    """Ensure the target `<sessionId>.jsonl` exists.
+
+    OpenClaw often leaves historical transcripts as `*.jsonl.reset.<timestamp>`.
+    A rollback is not complete until the plain `.jsonl` file exists again.
+    """
+    plain = sessions_dir / f'{target_session_id}.jsonl'
+    restored_from = None
+    if plain.exists():
+        return plain, restored_from
+
+    if archive_path and archive_path.exists():
+        shutil.copy2(archive_path, plain)
+        restored_from = archive_path
+        return plain, restored_from
+
+    # Fallback: auto-find matching archive for target sid
+    matches = sorted(sessions_dir.glob(f'{target_session_id}.jsonl.reset.*'))
+    if len(matches) == 1:
+        shutil.copy2(matches[0], plain)
+        restored_from = matches[0]
+        return plain, restored_from
+    if len(matches) > 1:
+        fail(f'Ambiguous target archive for {target_session_id}; pass --archive explicitly.')
+
+    fail(f'Target transcript missing: neither {plain.name} nor a usable archive was found.')
+
+
+def main():
+    p = argparse.ArgumentParser(description='Repoint an OpenClaw session key to a previous transcript version safely.')
+    p.add_argument('--agent', required=True, help='Agent id, e.g. daidai')
+    p.add_argument('--key', required=True, help='Full session key, e.g. agent:daidai:main')
+    p.add_argument('--target-session-id', required=True, help='Session id to restore to')
+    p.add_argument('--archive', help='Optional explicit archive path to restore from')
+    p.add_argument('--allow-missing-current-file', action='store_true', help='Do not fail if current sessionFile is missing')
+    args = p.parse_args()
+
+    sessions_dir = Path.home() / '.openclaw' / 'agents' / args.agent / 'sessions'
+    sessions_json = sessions_dir / 'sessions.json'
+    if not sessions_json.exists():
+        fail(f'sessions.json not found: {sessions_json}')
+
+    data = load_json(sessions_json)
+    if args.key not in data or not isinstance(data[args.key], dict):
+        fail(f'Session key not found: {args.key}')
+
+    item = data[args.key]
+    current_session_id = item.get('sessionId')
+    current_session_file = Path(item.get('sessionFile', '')) if item.get('sessionFile') else None
+    if not current_session_id:
+        fail(f'Current sessionId missing for {args.key}')
+    if not current_session_file:
+        fail(f'Current sessionFile missing for {args.key}')
+    if not current_session_file.exists() and not args.allow_missing_current_file:
+        fail(f'Current sessionFile does not exist: {current_session_file}')
+
+    archive_path = Path(args.archive).expanduser() if args.archive else None
+    if archive_path and not archive_path.exists():
+        fail(f'Archive path does not exist: {archive_path}')
+
+    # Safety backups: always preserve the current state before switching.
+    sessions_json_backup = backup_file(sessions_json, 'bak.manual-switch')
+    current_file_backup = None
+    if current_session_file.exists():
+        current_file_backup = backup_file(current_session_file, 'manual-switch-backup')
+
+    target_plain, restored_from = ensure_target_plain_file(sessions_dir, args.target_session_id, archive_path)
+
+    item['sessionId'] = args.target_session_id
+    item['sessionFile'] = str(target_plain)
+    item['updatedAt'] = int(target_plain.stat().st_mtime * 1000)
+    save_json(sessions_json, data)
+
+    result = {
+        'ok': True,
+        'agent': args.agent,
+        'key': args.key,
+        'fromSessionId': current_session_id,
+        'fromSessionFile': str(current_session_file),
+        'fromSessionFileBackup': str(current_file_backup) if current_file_backup else None,
+        'sessionsJsonBackup': str(sessions_json_backup),
+        'toSessionId': args.target_session_id,
+        'toSessionFile': str(target_plain),
+        'restoredTargetFromArchive': str(restored_from) if restored_from else None,
+        'note': 'Gateway restart may still be needed if runtime has cached session state.'
+    }
+    print(json.dumps(result, ensure_ascii=False, indent=2))
+
+
+if __name__ == '__main__':
+    main()