@aiyiran/myclaw 1.1.168 → 1.1.170

package/assets/myclaw-inject.js

@@ -327,22 +327,32 @@
 
   function buildTestDonePrompt() {
     var rec = window.myclawLastDebugRecord;
-    var lines = [
-      "我刚才已经完成了测试。",
-      "请你检查我的测试数据 debug/debug-record.html，重点查看里面的 JS 日志。",
-    ];
-
-    if (rec && rec.debugRecordPath) {
-      lines.push("如果你能读取本地路径，也可以查看：" + rec.debugRecordPath);
+    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("");
     lines.push("请帮我判断：我们之前的问题是否已经修复。");
-    lines.push("如果已经修复，请简单说明你从日志里看到了什么证据。");
-    lines.push("如果还没有修复，请指出日志里最关键的问题，并建议下一步最小修改。");
+    lines.push("如果已经修复，请简单说明你从 events 里看到了什么证据。");
+    lines.push("如果还没有修复，请指出 events 里最关键的问题，并建议下一步最小修改。");
 
     return lines.join("\n");
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiyiran/myclaw",
-  "version": "1.1.168",
+  "version": "1.1.170",
   "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/skills/chat-history-extractor/SKILL.md

@@ -27,38 +27,39 @@ python3 scripts/extract_chat.py '["url1","url2","url3"]' <output-dir>
 
 ## 输出文件
 
+**只产出两个文件**，不再为每个会话单独落 js（所有会话的完整数据都汇入 `index.js`）：
+
 | 文件 | 说明 |
 |---|---|
-| `01-<session-name>.js` | 第 1 个会话的数据 |
-| `02-<session-name>.js` | 第 2 个会话的数据 |
-| `...` | |
-| `index.js` | 所有会话的索引列表（仅批量模式生成） |
-| `chat_history.js` | 向后兼容，指向第一个会话 |
-
-每个 JS 文件结构：
-
-```javascript
-const chatData = {
-  "session": "session-name",
-  "session_id": "agent:xxx:yyy",
-  "total_pairs": N,
-  "initiator": "...",
-  "conversations": [
-    { "user": "...", "user_time": "...", "ai": "...", "ai_time": "..." },
-    ...
-  ]
-};
-```
+| `index.js` | 唯一数据产物：`chatIndex`（会话元数据列表）+ `chatAll`（每个会话的完整对话） |
+| `index.html` | 查看器，复制自 `assets/chat-history-template.html`，只加载 `index.js` |
 
 `index.js` 结构：
 
 ```javascript
+// chatIndex：用于会话切换下拉框的元数据
 const chatIndex = [
-  { "index": 1, "session": "...", "js_file": "01-xxx.js", "total_pairs": 10 },
-  { "index": 2, "session": "...", "js_file": "02-yyy.js", "total_pairs": 8 },
+  { "session_id": "agent:xxx:main", "workspace_name": "xxx", "session_name": "main",
+    "total_pairs": 10, "first_time": "...", "last_time": "...", "work_url": "" },
+  ...
 ];
+
+// chatAll：按 session_id 索引的完整会话数据（HTML 渲染的真正数据源）
+const chatAll = {
+  "agent:xxx:main": {
+    "workspace_name": "xxx", "session_name": "main", "session_id": "agent:xxx:main",
+    "total_pairs": 10, "first_time": "...", "last_time": "...", "work_url": "",
+    "conversations": [
+      { "user": "...", "user_time": "...", "ai": "...", "ai_time": "..." },
+      ...
+    ]
+  },
+  ...
+};
 ```
 
+> 单会话和批量模式产物一致，区别只是 `chatIndex` / `chatAll` 里的会话数量。
+
 ## 工作流
 
 ### Step 1: 解析输入
@@ -85,14 +86,14 @@ URL 示例：`https://claw1.kekouen.cn/chat?session=agent%3Ac108-v1-1811%3Amain`
 3. 多条 AI 回复合并为一条
 4. 跳过 `toolResult` 事件和空文本消息
 
-### Step 4: 生成 JS 文件
+### Step 4: 生成 index.js
 
-批量模式下，每个会话生成独立的 `NN-<name>.js`，并额外生成 `index.js` 索引。
+所有会话的数据在内存中汇总，一次性写入唯一的 `index.js`（`chatIndex` + `chatAll`），不为单个会话单独落文件。
 
 ### Step 5: 渲染
 
-将模板 `assets/chat-history-template.html` 复制到输出目录。
-模板会加载 `chat_history.js`（单会话）或可通过 `index.js` 切换（多会话）。
+将模板 `assets/chat-history-template.html` 复制到输出目录为 `index.html`。
+模板只加载 `index.js`，通过 `chatIndex` 渲染会话切换下拉框、从 `chatAll` 取完整对话。
 
 模板展示三种时间指标：
 - **课程流逝** — 距首条消息的时间
@@ -116,8 +117,8 @@ python3 scripts/extract_chat.py "https://claw1.kekouen.cn/chat?session=agent%3Ac
 ```
 
 输出：
-- `01-main.js`
-- `chat_history.js`（= 01-main.js 的副本）
+- `index.js`（含 1 个会话）
+- `index.html`
 
 ### 批量处理
 
@@ -131,9 +132,5 @@ python3 scripts/extract_chat.py '[
 ```
 
 输出：
-- `01-main.js`
-- `02-main.js`
-- `03-每天一个小习惯·宠物养成_1813.js`
-- `04-我的金币任务板_1810.js`
-- `index.js`
-- `chat_history.js`（= 01-main.js 的副本）
+- `index.js`（含 4 个会话，全部数据在 `chatAll` 里）
+- `index.html`

package/skills/chat-history-extractor/scripts/extract_chat.py

@@ -23,10 +23,11 @@ Usage:
   python3 extract_chat.py --scan [--html]
 
 输出（默认到当前 workspace /root/.openclaw/workspace-teacher）：
-  - 每个会话生成独立的 <agentId>_<sessionName>_<date>_<time>.js
-  - 生成 index.js，包含所有会话的元信息列表（含 work_url 字段）
-  - 生成 chat_history.js（向后兼容，指向第一个会话）
-  - --html 时额外生成 summary.html（含可点击链接）
+  - index.js：唯一数据产物，含 chatIndex（会话元信息列表，含 work_url 字段）
+    + chatAll（每个会话的完整对话，按 session_id 索引）
+  - index.html：查看器，复制自 assets/chat-history-template.html，只加载 index.js
+  - 不再为每个会话单独落 js 文件
+  - --scan 模式额外生成 作品扫描_<时间>.html（含可点击链接）
 
 Host 检测：
   - 自动从 /root/.openclaw/myclaw/server/config.json 读取
@@ -34,7 +35,7 @@ Host 检测：
 
 work_url 字段:
   - 默认为空字符串
-  - AI 可后续手动编辑 JS 文件填入学生作品链接
+  - AI 可后续编辑 index.js 中对应会话的 work_url 填入学生作品链接
 """
 
 import json
@@ -166,7 +167,8 @@ def count_conversations(jsonl_path):
                 messages.append({
                     'role': role,
                     'text': text.strip(),
-                    'has_text': bool(text.strip())
+                    'has_text': bool(text.strip()),
+                    'timestamp': timestamp
                 })
 
     # Count conversation pairs (user messages with at least one AI reply)
@@ -183,9 +185,13 @@ def count_conversations(jsonl_path):
                     ai_messages.append(messages[j])
                 j += 1
             ai_text = '\n\n'.join([m['text'] for m in ai_messages if m['has_text']])
+            user_time = msg.get('timestamp', '')
+            ai_time = ai_messages[0].get('timestamp', '') if ai_messages else ''
             conversations.append({
                 'user': user_text,
                 'ai': ai_text,
+                'user_time': user_time,
+                'ai_time': ai_time,
             })
             i += 1
         else:
@@ -210,17 +216,26 @@ def build_filename(session_key):
     parts = session_key.split(':')
     agent_id = parts[1] if len(parts) > 1 else 'unknown'
     session_name = parts[2] if len(parts) > 2 else 'main'
+    # Use last part (UUID or 'main') as unique suffix to avoid collisions
+    unique_id = parts[-1] if len(parts) > 3 else session_name
     agent_safe = sanitize_filename(agent_id)
     name_safe = sanitize_filename(session_name)
-    return f"{agent_safe}_{name_safe}.js"
+    unique_safe = sanitize_filename(unique_id)
+    if unique_safe == name_safe:
+        return f"{agent_safe}_{name_safe}.js"
+    return f"{agent_safe}_{name_safe}_{unique_safe}.js"
 
 
-def generate_js(conversations, session_key, first_ts, last_ts, output_path):
+def build_chat_data(conversations, session_key, first_ts, last_ts):
+    """构建单个会话的完整数据对象（仅内存，不写盘）。
+
+    数据最终全部汇入 index.js 的 chatAll，不再为每个会话单独落 js 文件。
+    """
     parts = session_key.split(':')
     workspace_name = parts[1] if len(parts) > 1 else 'unknown'
     session_name = parts[2] if len(parts) > 2 else 'main'
 
-    output_data = {
+    return {
         'workspace_name': workspace_name,
         'session_name': session_name,
         'session_id': session_key,
@@ -230,15 +245,6 @@ def generate_js(conversations, session_key, first_ts, last_ts, output_path):
         'work_url': '',
         'conversations': conversations
     }
-    js_content = f'''// Chat History - {session_name}
-// Session Key: {session_key}
-// Generated by chat-history-extractor skill
-
-const chatData = {json.dumps(output_data, ensure_ascii=False, indent=2)};
-'''
-    with open(output_path, 'w', encoding='utf-8') as f:
-        f.write(js_content)
-    return len(conversations), session_name
 
 
 def session_key_to_url(session_key, host=None):
@@ -387,57 +393,43 @@ def process_one(url_or_key, output_dir, index):
     conversations, first_ts, last_ts = parse_jsonl_to_conversations(jsonl_path)
     print(f"[{index}] {len(conversations)} pairs")
 
-    js_filename = build_filename(session_key)
-    js_path = os.path.join(output_dir, js_filename)
-    count, _ = generate_js(conversations, session_key, first_ts, last_ts, js_path)
-    print(f"[{index}] Generated: {js_filename}")
+    data = build_chat_data(conversations, session_key, first_ts, last_ts)
 
     return {
         'index': index,
         'session_key': session_key,
         'session_name': session_name,
         'agent_id': agent_id,
-        'js_file': js_filename,
-        'total_pairs': count,
-        'first_time': parse_time(first_ts) if first_ts else '',
-        'last_time': parse_time(last_ts) if last_ts else '',
+        'total_pairs': data['total_pairs'],
+        'first_time': data['first_time'],
+        'last_time': data['last_time'],
         'work_url': '',
+        'data': data,  # 完整会话数据，汇入 index.js 的 chatAll
     }
 
 
-def generate_index_js(output_dir):
-    """Scan output_dir for all .js files, merge into index.js with full data."""
+def generate_index_js(results, output_dir):
+    """直接用内存中的 results 拼出唯一产物 index.js（chatIndex + chatAll）。
+
+    不再为每个会话单独落 js 文件——每个会话的完整对话都进 chatAll，
+    HTML 只加载 index.js 即可渲染全部会话。
+    """
     all_entries = []
     all_data = {}
 
-    for fname in sorted(os.listdir(output_dir)):
-        if not fname.endswith('.js') or fname in ('index.js', 'chat_history.js'):
-            continue
-        fpath = os.path.join(output_dir, fname)
-        mtime = int(os.path.getmtime(fpath))
-        try:
-            with open(fpath, 'r', encoding='utf-8') as f:
-                fcontent = f.read()
-            m = re.search(r'const chatData = (\{.*\});?\s*$', fcontent, re.DOTALL)
-            if not m:
-                continue
-            data = json.loads(m.group(1))
-            sid = data.get('session_id', fname.replace('.js', ''))
-            all_data[sid] = data
-            all_entries.append({
-                'workspace_name': data.get('workspace_name', ''),
-                'session_name': data.get('session_name', ''),
-                'session_id': sid,
-                'js_file': fname,
-                'total_pairs': data.get('total_pairs', 0),
-                'first_time': data.get('first_time', ''),
-                'last_time': data.get('last_time', ''),
-                'work_url': data.get('work_url', ''),
-                'mtime': mtime,
-            })
-        except Exception as ex:
-            print('  [WARN] Skip %s: %s' % (fname, ex))
-            continue
+    for r in results:
+        data = r['data']
+        sid = data['session_id']
+        all_data[sid] = data
+        all_entries.append({
+            'workspace_name': data.get('workspace_name', ''),
+            'session_name': data.get('session_name', ''),
+            'session_id': sid,
+            'total_pairs': data.get('total_pairs', 0),
+            'first_time': data.get('first_time', ''),
+            'last_time': data.get('last_time', ''),
+            'work_url': data.get('work_url', ''),
+        })
 
     now_ts = int(time.time())
     idx = '// Chat History Index - %d session(s)\n' % len(all_entries)
@@ -546,7 +538,7 @@ def main():
 
     os.makedirs(output_dir, exist_ok=True)
 
-    # Clean old JS + index.html before fresh extraction
+    # 清理旧产物（含历史遗留的单会话 js）后再重新生成
     for old_f in os.listdir(output_dir):
         if old_f.endswith('.js') or old_f == 'index.html':
             try:
@@ -564,8 +556,8 @@ def main():
         print("\nERROR: No sessions processed successfully.")
         sys.exit(1)
 
-    # Always regenerate index.js by scanning directory
-    generate_index_js(output_dir)
+    # 唯一数据产物：index.js（chatIndex + chatAll）
+    generate_index_js(results, output_dir)
 
     # Copy chat-history-template.html as index.html
     import shutil

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()