@aiyiran/myclaw 1.1.169 → 1.1.170

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiyiran/myclaw",
-  "version": "1.1.169",
+  "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/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()