sophhub 0.4.29 → 0.4.31

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sophhub",
-  "version": "0.4.29",
+  "version": "0.4.31",
   "description": "SophHub CLI - Manage and download AI Agent skills and agents",
   "type": "module",
   "bin": {

package/skills/agent-install/skill.json

@@ -1,12 +1,19 @@
 {
   "name": "agent-install",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "types": [
     "store"
   ],
   "displayName": "Agent安装",
   "description": "安装或升级 Sophclaw Agent（含占位替换、备份、post_install 脚本与自动安装 skill）。",
   "changelog": [
+    {
+      "changes": [
+        "新增 _ensure_main_agent_in_list：单 Agent 模式下安装 Agent 时自动迁移 main Agent 至 agents.list，防止 session 丢失"
+      ],
+      "date": "2026-05-27",
+      "version": "0.1.8"
+    },
     {
       "changes": [
         "新增 run_post_install.py：安装时执行 .config.json 中 post_install 脚本",
@@ -47,5 +54,5 @@
     }
   ],
   "createdAt": "2026-04-21",
-  "updatedAt": "2026-05-20"
+  "updatedAt": "2026-05-27"
 }

package/skills/agent-install/src/scripts/update_openclaw.py

@@ -6,6 +6,8 @@ import json
 import sys
 from pathlib import Path
 
+from copy import deepcopy
+
 from common import (
     build_agent_entry,
     build_bot_api_account,
@@ -33,6 +35,64 @@ def normalized_override(value: str | None) -> str | None:
     return None
 
 
+def _ensure_main_agent_in_list(config: dict, config_path: Path) -> dict | None:
+    """如果 openclaw.json 处于单 Agent 模式（agents.list 为空但默认 workspace 存在），
+    将 main Agent 迁移至 list 中，防止 install 后 session 丢失。
+
+    返回迁移信息 dict（含 migrated/agent_id/workspace），无需迁移时返回 None。
+    """
+    agents = config.setdefault("agents", {})
+    agents_list = agents.setdefault("list", [])
+
+    # 已有 Agent 列表条目 → 已是多 Agent 模式，无需迁移
+    if agents_list:
+        return None
+
+    root_dir = config_path.parent
+    # 默认 workspace 路径为 openclaw.json 同级目录下的 workspace
+    default_workspace = root_dir / "workspace"
+    if not default_workspace.is_dir():
+        return None
+
+    main_id = config.get("id", "main")
+    if not isinstance(main_id, str) or not main_id.strip():
+        main_id = "main"
+    main_id = main_id.strip()
+
+    # workspace：优先顶层 config.workspace，否则用默认路径
+    top_workspace = config.get("workspace")
+    workspace = str(top_workspace) if isinstance(top_workspace, str) and top_workspace.strip() else str(default_workspace)
+    entry: dict = {"id": main_id, "workspace": workspace}
+
+    # model：顶层 config.model 优先于 defaults.model（单 Agent 模式顶层可能含 fallbacks 等）
+    defaults = agents.get("defaults", {})
+    top_model = config.get("model")
+    if isinstance(top_model, dict):
+        entry["model"] = deepcopy(top_model)
+    elif isinstance(defaults.get("model"), dict):
+        entry["model"] = deepcopy(defaults["model"])
+    if isinstance(defaults.get("heartbeat"), dict):
+        entry["heartbeat"] = deepcopy(defaults["heartbeat"])
+
+    # identity：优先从顶层 config 取，否则用 main_id 构造默认值
+    if isinstance(config.get("identity"), dict):
+        entry["identity"] = deepcopy(config["identity"])
+    else:
+        entry["identity"] = {"name": main_id, "theme": main_id, "emoji": "🤖"}
+
+    if isinstance(config.get("name"), str) and config["name"].strip():
+        entry["name"] = config["name"].strip()
+    if isinstance(config.get("agentDir"), str) and config["agentDir"].strip():
+        entry["agentDir"] = config["agentDir"].strip()
+    if isinstance(config.get("tools"), dict):
+        entry["tools"] = deepcopy(config["tools"])
+    if isinstance(config.get("skills"), list):
+        entry["skills"] = deepcopy(config["skills"])
+
+    agents_list.insert(0, entry)
+    return {"migrated": True, "agent_id": main_id, "workspace": workspace}
+
+
 def upsert_agent(config: dict, entry: dict) -> str:
     config.setdefault("agents", {})
     agents = config["agents"].setdefault("list", [])
@@ -103,6 +163,7 @@ def update_openclaw(
     resolved_name = normalized_override(name_override)
     agent_def = load_agent_definition(agent_id, source_path)
     config = load_openclaw_config(config_path)
+    main_migration = _ensure_main_agent_in_list(config, config_path)
     desired_workspace = resolved_workspace or agent_def.get("install", {}).get("workspace") or agent_def.get("workspace")
     previous = resolve_existing_agent_entry(config_path, config, agent_id, desired_workspace)
     if previous is None and resolved_openclaw_id:
@@ -164,6 +225,7 @@ def update_openclaw(
         "auto_generate_image_description": auto_img_desc,
         "heartbeat_configured": heartbeat_cfg is not None,
         "heartbeat": heartbeat_cfg,
+        "main_migration": main_migration,
     }
 
 

package/skills/online-bug-report/skill.json

@@ -1,12 +1,36 @@
 {
   "name": "online-bug-report",
-  "version": "1.0.5",
+  "version": "1.0.7",
   "types": [
     "store"
   ],
   "displayName": "在线提Bug",
-  "description": "用户说「在线提交bug」时收集 Bug 并经由虾友 DM 发送工单（含 session 附件）",
+  "description": "当用户说「在线提交bug」时，收集问题描述并通过虾友 DM 提交工单。",
   "changelog": [
+    {
+      "changes": [
+        "新增 ensure-friend 子命令，add_friend.py 删除逻辑内置",
+        "新增 --agent-id 参数，sessions 路径改为 /agents/{agentId}/sessions/",
+        "消息格式重构为 flat ▎结构",
+        "支持 JWT 自动解析 sender（userId/name）",
+        "错误消息改为显示实际失败原因",
+        "pyproject.toml 对齐 sophnet-image-ocr（aliyun mirror、依赖声明）",
+        "SKILL.md 精简至 55 行",
+        "清理死代码、提取 resolve_api_base 去重"
+      ],
+      "date": "2026-05-28",
+      "version": "1.0.7"
+    },
+    {
+      "changes": [
+        "移除对 sophnet-oss skill 的引用，上传脚本自包含",
+        "路径改为运行时格式（{baseDir}/scripts/），去除 src/ 和 workspace",
+        "新增模板变量说明节，定义 sender_id、sender_name 等变量",
+        "Python 版本要求从 3.10+ 降为 3.8+"
+      ],
+      "date": "2026-05-27",
+      "version": "1.0.6"
+    },
     {
       "changes": [
         "凭证移至 src/secrets/bug-report.json，与 npm 打包仅含 src/ 对齐"
@@ -51,5 +75,5 @@
     }
   ],
   "createdAt": "2026-05-18",
-  "updatedAt": "2026-05-19"
+  "updatedAt": "2026-05-28"
 }

package/skills/online-bug-report/src/SKILL.md

@@ -1,131 +1,55 @@
 ---
 name: online-bug-report
-description: |
-  仅当用户说「在线提交bug」（大小写不敏感）时触发。收集 Bug 描述、上传 session .jsonl 到 OSS，
-  通过虾友 DM 发送工单。勿因「提 Bug」「报障」「系统坏了」等其它说法触发。
+description: 当用户说「在线提交bug」时，收集问题描述并通过虾友 DM 提交工单。
 ---
 
 # 在线提 Bug
 
-用户说「**在线提交 Bug**」后，收集 Bug 描述并提交工单。
+用户说「**在线提交 Bug**」（`bug` 不区分大小写，允许中间空格）后执行。
 
-## Processing Mode
+## Step 1：校验好友
 
-**STRICT SERIAL PROCESSING ONLY** — 单次顺序执行。
-
-## Prerequisites
-
-- Python 3.10+、`uv`
-- 有效 JWT：`/home/node/.openclaw/jwt.json`（字段 `web_jwt`）
-- `exec` 工具可用
-
-## 凭证文件
-
-**内置凭证（随 skill 下发）：** `{baseDir}/secrets/bug-report.json`，下载后可直接使用。修改收件人请直接编辑该文件，或使用 `--cred-file` 指定其它路径。
-
-## 触发词
-
-**唯一触发词**：「在线提交bug」（`bug` 不区分大小写；允许 `在线提交 bug` 中间有空格）
-
-| 用户说的话 | 是否触发 |
-|-----------|----------|
-| 「在线提交bug」/「在线提交 Bug」 | ✅ 触发 |
-| 「提 Bug」 | ❌ 不触发，正常回答 |
-| 「报 Bug」 | ❌ 不触发，正常回答 |
-| 「系统坏了」 | ❌ 不触发，正常回答 |
-| 「有个 Bug」 | ❌ 不触发，正常回答 |
-
-## Agent 角色定位
-
-**Agent 是 Bug 信息收集者，不是问题解决者。**
-
-| Agent 行为 | 正确/错误 |
-|-----------|----------|
-| 收集用户描述 → 提交工单 | ✅ 正确 |
-| 尝试自己分析/修复 Bug | ❌ 错误 |
-| 询问技术细节、API、配置 | ❌ 错误 |
-| 让用户补充现象描述 | ✅ 正确 |
+```bash
+uv run {baseDir}/scripts/report_bug.py ensure-friend --json
+```
 
-## 执行流程
+| 退出码 | Agent 行为 |
+|--------|-----------|
+| 0 | 进入 Step 2 |
+| 2 | 回复「研发值班还不是您的好友，已自动发送申请。通过后请重新提交 Bug」→ 结束 |
+| 其他 | 回复「提交 Bug 失败，失败原因为：{stderr}」→ 结束 |
 
-### Step 1：用户说「在线提交 Bug」
+## Step 2：收集描述
 
-Agent **立即停止任何尝试解决问题的行为**，回复：
+回复以下内容让用户补充：
 
 ```
 好的，我来帮您提交 Bug 工单。
 
-请补充一下问题描述：
-- 具体是什么问题/现象？
-- 大概什么时候发生的？
-- 有复现步骤吗？（可选）
-
-补充完之后告诉我，我会提交处理。
-```
-
-**关键点**：
-- **不尝试**：不分析原因、不尝试修复、不给解决方案
-- **只收集**：等待用户补充描述
-- **不询问技术细节**
-
-### Step 2：等待用户补充描述
-
-用户补充描述后，记录用户原话作为 Bug 描述。
-
-若描述不足，追问：「请问具体现象是什么？」
-不追问技术细节。
-
-### Step 3：获取完整 session 文件
-
-```bash
-SESSION_KEY="{当前sessionKey}"
-SESSION_ID=$(cat {agentDir}/sessions/sessions.json | jq -r '."${SESSION_KEY}".sessionId')
-SESSION_FILE="{agentDir}/sessions/${SESSION_ID}.jsonl"
+请补充一下您的具体问题/现象，如果能提供复现步骤，那更好。
 ```
 
-**上传完整的 `.jsonl` 文件**（包含整个对话历史）。
+记录用户原话。若描述不足追问「请问具体现象是什么？」
 
-### Step 4：上传到 OSS
+## Step 3：提交工单
 
-```bash
-cd {workspace}/skills/sophnet-oss
-uv run --with sophnet-tools python scripts/upload_file.py \
-  --file "${SESSION_FILE}" --timeout 60
-```
-
-### Step 5：发送工单
+获取当前 session 的 sessionKey 和 agentId（sessionKey 形如 `agent:<AgentID>:...`，取第二段即为 agentId），然后执行：
 
 ```bash
-cd {workspace}/skills/online-bug-report/src
-uv run scripts/report_bug.py send \
-  --sender-id "{sender_id}" \
-  --sender-name "{sender_name}" \
+uv run {baseDir}/scripts/report_bug.py send \
   --description "{用户完整描述}" \
-  --session-key "${SESSION_KEY}" \
-  --oss-url "${OSS_URL}" \
+  --session-key "{sessionKey}" \
+  --agent-id "{agentId}" \
   --json
 ```
 
-### Step 6：回复用户
-
-- 成功：「已提交 Bug 工单，会跟进处理。」
-- 失败：「已记录问题，稍后将补发工单。」
-
-## 与「知识库反馈」分流
-
-| 用户意图 | 处理 |
-|---------|------|
-| 「文档错了」「知识库内容有误」 | `memory/feedback-*.md` 流程 |
-| 「在线提交 Bug」 | **本 Skill** → 收集并提交 |
-
-## 安全约束
+## Step 4：回复用户
 
-- **不暴露**：JWT、凭证路径、friendId、API 地址
-- **不询问**：技术细节、配置参数
-- **不尝试**：分析或修复 Bug
+- 退出码 0 → 「已提交 Bug 工单，会跟进处理。」
+- 退出码非 0 → 「提交 Bug 失败，失败原因为：{stderr}」
 
 ## Forbidden
 
-- 不要尝试解决用户的问题
-- 不要向用户暴露 JWT、凭证
-- 不要询问技术细节
+- 不要分析/修复 Bug，只收集信息
+- 不要询问技术细节、API、配置
+- 不要暴露 JWT、凭证、friendId、API 地址

package/skills/online-bug-report/src/pyproject.toml

@@ -1,5 +1,13 @@
 [project]
 name = "online-bug-report"
-version = "1.0.5"
+version = "1.0.7"
 description = "Send VIP online bug reports to a Sophclaw friend via IM"
-requires-python = ">=3.10"
+requires-python = ">=3.8"
+dependencies = [
+    "requests>=2.28.0",
+    "sophnet-tools>=0.0.1",
+]
+
+[[tool.uv.index]]
+url = "https://mirrors.aliyun.com/pypi/simple/"
+default = true

package/skills/online-bug-report/src/references/config.example.json

@@ -1,11 +1,8 @@
 {
   "_comment": "字段说明参考；实际凭证见 secrets/bug-report.json（与 SKILL.md 同级的 src/secrets/）",
   "dev_friend_id": 0,
-  "dev_friend_name": "收件人名称",
-  "terminal_label": "虾友 DM",
   "terminal_url": "",
   "session_url_template": "{base_url}/chat?session={session_key}",
   "api_base_url": "https://yagent.sophnet.com/api",
-  "openclaw_base_url": "",
-  "default_model": "Qwen3.5-122B-A10B"
+  "openclaw_base_url": ""
 }

package/skills/online-bug-report/src/scripts/report_bug.py

@@ -15,19 +15,16 @@ from dataclasses import dataclass, field
 from datetime import datetime
 from pathlib import Path
 from typing import Any, Optional
-
+import sophnet_tools
 
 DEFAULT_TIMEOUT = 30
 DEFAULT_API_BASE_URL = "https://yagent.sophnet.com/api"
 DEFAULT_JWT_PATH = Path("/home/node/.openclaw/jwt.json")
 DEFAULT_OPENCLAW_BASE_PATH = Path("/home/node/.openclaw/.base.json")
-DEFAULT_SOURCE_LABEL = "虾友 DM"
+OSS_UPLOAD_TIMEOUT = 60
 
 CONFIG_ALIASES: dict[str, tuple[str, ...]] = {
     "dev_friend_id": ("dev_friend_id", "DEV_FRIEND_ID", "friend_id"),
-    "dev_friend_name": ("dev_friend_name", "DEV_FRIEND_NAME", "friend_name"),
-    "terminal_label": ("terminal_label", "TERMINAL_LABEL"),
-    "terminal_url": ("terminal_url", "TERMINAL_URL"),
     "session_url_template": (
         "session_url_template",
         "SESSION_URL_TEMPLATE",
@@ -39,10 +36,16 @@ CONFIG_ALIASES: dict[str, tuple[str, ...]] = {
         "OPENCLAW_BASE_URL",
         "sophclaw_base_url",
     ),
-    "default_model": ("default_model", "DEFAULT_MODEL", "llm", "model"),
 }
 
 
+def get_sessions_dir(agent_id: str) -> Path:
+    """根据 agentId 构造 sessions 目录路径。"""
+    if not agent_id.strip():
+        raise AppError("agent-id 不能为空")
+    return Path("/home/node/.openclaw/agents") / agent_id.strip() / "sessions"
+
+
 class AppError(RuntimeError):
     pass
 
@@ -161,12 +164,12 @@ class BugReport:
     sender_name: str
     user_description: str
     openclaw_base_url: Optional[str] = None
-    terminal_label: str = DEFAULT_SOURCE_LABEL
-    terminal_url: Optional[str] = None
     session_key: Optional[str] = None
     session_url: Optional[str] = None
-    context: Optional[str] = None
     model: Optional[str] = None
+    model_provider: Optional[str] = None
+    context_tokens: Optional[int] = None
+    total_tokens: Optional[int] = None
     oss_urls: list[str] = field(default_factory=list)
     reported_at: Optional[str] = None
 
@@ -185,44 +188,29 @@ def format_bug_message(report: BugReport) -> str:
     ts = report.reported_at or datetime.now().strftime("%Y-%m-%d %H:%M:%S")
     lines = [
         f"【在线 Bug】{ts}",
-        "",
-        "▎发件人",
-        f"- 用户: {report.sender_name.strip()} ({report.sender_id.strip()})",
-        f"- 来源: {report.terminal_label.strip() or DEFAULT_SOURCE_LABEL}",
-        "",
-        "▎用户描述",
-        report.user_description.strip(),
-        "",
-        "▎环境",
+        f"▎发件人：{report.sender_name.strip()}",
+        f"▎ID: {report.sender_id.strip()}",
+        f"▎会话：{report.session_key.strip() if report.session_key else '（无）'}",
     ]
     if report.openclaw_base_url:
-        lines.append(f"- OpenClaw Base URL: {report.openclaw_base_url}")
-    else:
-        lines.append("- OpenClaw Base URL: （未配置）")
-    terminal_line = f"- 终端: {report.terminal_label.strip() or DEFAULT_SOURCE_LABEL}"
-    if report.terminal_url and report.terminal_url.strip():
-        terminal_line += f" ({report.terminal_url.strip()})"
-    lines.append(terminal_line)
+        lines.append(f"▎Base URL: {report.openclaw_base_url}")
     if report.model and report.model.strip():
-        lines.append(f"- 模型: {report.model.strip()}")
-    else:
-        lines.append("- 模型: （未知）")
-
-    lines.extend(["", "▎会话"])
-    if report.session_key and report.session_key.strip():
-        lines.append(f"- sessionKey: {report.session_key.strip()}")
-    else:
-        lines.append("- sessionKey: （无）")
-    if report.session_url and report.session_url.strip():
-        lines.append(f"- Session 链接: {report.session_url.strip()}")
-    if report.context and report.context.strip():
-        lines.extend(["- 近期上下文:", report.context.strip()])
+        model_line = report.model.strip()
+        if report.model_provider and report.model_provider.strip():
+            model_line = f"{report.model_provider.strip()}/{report.model.strip()}"
+        lines.append(f"▎模型: {model_line}")
+    if report.context_tokens is not None:
+        lines.append(f"▎上下文大小: {report.context_tokens}")
+    if report.total_tokens is not None:
+        lines.append(f"▎当前上下文占用: {report.total_tokens}")
 
-    lines.extend(["", "▎附件"])
     if report.oss_urls:
-        lines.extend(report.oss_urls)
-    else:
-        lines.append("（无）")
+        lines.append(f"▎附件：{report.oss_urls[0]}")
+        for u in report.oss_urls[1:]:
+            lines.append(f"    {u}")
+
+    lines.append(f"▎用户描述：")
+    lines.append(f"    {report.user_description.strip()}")
 
     return "\n".join(lines).rstrip() + "\n"
 
@@ -349,7 +337,7 @@ def load_friends(api_base: str, token: str, timeout: int) -> list[dict[str, Any]
     return out
 
 
-def find_nearest_agent_config(start_dir: Path | None = None) -> Path | None:
+def find_nearest_agent_config(start_dir: Optional[Path] = None) -> Optional[Path]:
     current = (start_dir or Path.cwd()).resolve()
     for candidate in [current, *current.parents]:
         config_path = candidate / ".config.json"
@@ -358,7 +346,7 @@ def find_nearest_agent_config(start_dir: Path | None = None) -> Path | None:
     return None
 
 
-def read_model_from_agent_config(config_path: Path | None = None) -> Optional[str]:
+def read_model_from_agent_config(config_path: Optional[Path] = None) -> Optional[str]:
     path = config_path or find_nearest_agent_config()
     if path is None:
         return None
@@ -375,39 +363,105 @@ def read_model_from_agent_config(config_path: Path | None = None) -> Optional[st
     return None
 
 
-def read_context_file(path: Optional[str]) -> Optional[str]:
-    if not path:
-        return None
-    file_path = Path(path).expanduser()
+def resolve_sender_from_jwt(jwt_path: Path = DEFAULT_JWT_PATH) -> tuple[str, str]:
+    """从 JWT payload 中解析 userId 和 name 作为 sender_id / sender_name。"""
+    data = load_json_file(jwt_path)
+    token = data.get("web_jwt")
+    if not isinstance(token, str) or not token.strip():
+        raise AppError(f"JWT 文件缺少有效 web_jwt: {jwt_path}")
+    token = token.strip()
+    if token.lower().startswith("bearer "):
+        token = token[7:].strip()
+    parts = token.split(".")
+    if len(parts) != 3:
+        raise AppError("web_jwt 不是有效的 JWT 格式")
+    payload_b64 = parts[1]
+    remainder = len(payload_b64) % 4
+    if remainder:
+        payload_b64 += "=" * (4 - remainder)
     try:
-        text = file_path.read_text(encoding="utf-8")
-    except OSError as exc:
-        raise AppError(f"无法读取 context 文件 {file_path}: {exc}") from exc
-    text = text.strip()
-    return text or None
+        raw = base64.urlsafe_b64decode(payload_b64.encode("ascii"))
+        payload = json.loads(raw)
+    except (ValueError, UnicodeDecodeError, json.JSONDecodeError) as exc:
+        raise AppError(f"JWT payload 解码失败: {exc}") from exc
+    user_id = payload.get("userId")
+    if user_id is None:
+        raise AppError("JWT payload 中未找到 userId 字段")
+    sender_id = str(int(user_id))
+    sender_name = str(payload.get("name") or "")
+    if not sender_name.strip():
+        sender_name = sender_id
+    return sender_id, sender_name
+
+
+def resolve_session_file(session_key: str, agent_id: str) -> tuple[Path, dict[str, Any]]:
+    """根据 sessionKey 查找 .jsonl 会话文件，同时返回 session 元信息。"""
+    if not session_key.strip():
+        raise AppError("session-key 不能为空")
+    if not agent_id.strip():
+        raise AppError("agent-id 不能为空")
+    sessions_dir = get_sessions_dir(agent_id)
+    sessions_json = sessions_dir / "sessions.json"
+    if not sessions_json.is_file():
+        raise AppError(f"sessions.json 不存在: {sessions_json}")
+    data = load_json_file(sessions_json)
+    session_entry = data.get(session_key.strip())
+    if not isinstance(session_entry, dict):
+        raise AppError(f"sessions.json 中未找到 sessionKey={session_key} 的记录")
+    session_file = Path(session_entry.get("sessionFile") or "")
+    if not session_file.is_file():
+        raise AppError(f"session 文件不存在: {session_file}")
+    meta = {
+        "modelProvider": session_entry.get("modelProvider"),
+        "model": session_entry.get("model"),
+        "contextTokens": session_entry.get("contextTokens"),
+        "totalTokens": session_entry.get("totalTokens"),
+    }
+    return session_file, meta
+
+
+def upload_session_to_oss(session_file: Path, timeout: int = OSS_UPLOAD_TIMEOUT) -> str:
+    """上传 session 文件到 OSS，返回签名下载 URL。"""
+    signed_url = sophnet_tools.upload_oss(str(session_file), timeout=timeout)
+    if not signed_url:
+        raise AppError("OSS 上传失败：未返回下载 URL")
+    return signed_url
 
 
 def build_report_from_args(args: argparse.Namespace) -> BugReport:
     cred = load_cred_file(args.cred_file)
 
+    # sender: 显式传入优先，否则从 JWT 自动解析
+    sender_id = (args.sender_id or "").strip()
+    sender_name = (args.sender_name or "").strip()
+    if not sender_id or not sender_name:
+        jwt_id, jwt_name = resolve_sender_from_jwt()
+        if not sender_id:
+            sender_id = jwt_id
+        if not sender_name:
+            sender_name = jwt_name
+
     openclaw_base = (
         (args.openclaw_base_url or "").strip()
         or cfg_pick(cred, "openclaw_base_url", "OPENCLAW_BASE_URL")
         or read_openclaw_base_url(Path(args.openclaw_base_path).expanduser())
     )
 
-    terminal_label = (
-        (args.terminal_label or "").strip()
-        or cfg_pick(cred, "terminal_label", "BUG_TERMINAL_LABEL")
-        or DEFAULT_SOURCE_LABEL
-    )
-    terminal_url = (
-        (args.terminal_url or "").strip()
-        or cfg_pick(cred, "terminal_url", "BUG_TERMINAL_URL")
-        or None
-    )
-
     session_key = (args.session_key or "").strip() or None
+    agent_id = (args.agent_id or "").strip() or None
+
+    # OSS URL: 显式传入优先，否则根据 session_key 自动上传
+    explicit_oss_urls = [normalize_http_url(u, field_name="oss-url") for u in (args.oss_url or [])]
+    session_meta: dict[str, Any] = {}
+    if explicit_oss_urls:
+        oss_urls = explicit_oss_urls
+    elif session_key and agent_id:
+        session_file, session_meta = resolve_session_file(session_key, agent_id)
+        oss_url = upload_session_to_oss(session_file)
+        oss_urls = [oss_url]
+    else:
+        oss_urls = []
+
     template = (args.session_url_template or "").strip() or cfg_pick(
         cred, "session_url_template", "BUG_SESSION_URL_TEMPLATE"
     )
@@ -419,33 +473,38 @@ def build_report_from_args(args: argparse.Namespace) -> BugReport:
         openclaw_base,
     )
 
-    context = (args.context or "").strip() or read_context_file(args.context_file)
-
-    oss_urls = [normalize_http_url(u, field_name="oss-url") for u in (args.oss_url or [])]
-
     model = (
         (args.model or "").strip()
+        or session_meta.get("model")
         or cfg_pick(cred, "default_model", "BUG_MODEL")
         or read_model_from_agent_config()
     ) or None
+    model_provider = (
+        session_meta.get("modelProvider")
+        or cfg_pick(cred, "model_provider")
+    ) or None
+
+    def _session_int(key: str) -> Optional[int]:
+        v = session_meta.get(key)
+        return int(v) if isinstance(v, (int, float)) else None
 
     return BugReport(
-        sender_id=args.sender_id,
-        sender_name=args.sender_name,
+        sender_id=sender_id,
+        sender_name=sender_name,
         user_description=args.description,
         openclaw_base_url=openclaw_base,
-        terminal_label=terminal_label,
-        terminal_url=terminal_url,
         session_key=session_key,
         session_url=session_url,
-        context=context,
         model=model,
+        model_provider=model_provider,
+        context_tokens=_session_int("contextTokens"),
+        total_tokens=_session_int("totalTokens"),
         oss_urls=oss_urls,
         reported_at=(args.reported_at or "").strip() or None,
     )
 
 
-def resolve_dev_friend(args: argparse.Namespace, cred: dict[str, Any]) -> tuple[int, str]:
+def resolve_dev_friend(args: argparse.Namespace, cred: dict[str, Any]) -> int:
     if args.friend_id is not None and args.friend_id > 0:
         friend_id = int(args.friend_id)
     else:
@@ -458,12 +517,52 @@ def resolve_dev_friend(args: argparse.Namespace, cred: dict[str, Any]) -> tuple[
             raise AppError(f"dev_friend_id 不是有效整数: {raw}") from exc
     if friend_id <= 0:
         raise AppError("friend-id 必须为正整数")
-    friend_name = (
-        (args.friend_name or "").strip()
-        or cfg_pick(cred, "dev_friend_name", "BUG_DEV_FRIEND_NAME")
-        or "研发值班"
+    return friend_id
+
+
+def request_friend(api_base: str, token: str, friend_id: int, timeout: int) -> dict[str, Any]:
+    """发起好友请求。"""
+    url = f"{api_base}/sys/openclaw/friend/request"
+    return request_json("POST", url, token, timeout, payload={"friendId": friend_id})
+
+
+def resolve_api_base(
+    args: argparse.Namespace,
+    cred: dict[str, Any],
+) -> str:
+    """从参数和凭证中解析 api_base_url，三处调用共用。"""
+    return normalize_http_url(
+        (args.api_base_url or "").strip()
+        or cfg_pick(cred, "api_base_url", "BUG_API_BASE_URL")
+        or DEFAULT_API_BASE_URL,
+        field_name="api-base-url",
     )
-    return friend_id, friend_name
+
+
+def cmd_ensure_friend(args: argparse.Namespace) -> int:
+    """ensure-friend 子命令：检查 dev_friend_id 是否已是好友，否则发起好友请求。
+
+    退出码: 0=已是好友, 2=刚发起好友请求, 1=异常
+    """
+    cred = load_cred_file(getattr(args, "cred_file", None), required=True)
+    friend_id = resolve_dev_friend(args, cred)
+    api_base = resolve_api_base(args, cred)
+    jwt_path = Path(args.jwt_path).expanduser()
+    token = read_bearer_token(jwt_path)
+    ensure_jwt_valid(token, jwt_path, args.allow_expired_jwt)
+
+    friends = load_friends(api_base, token, args.timeout)
+    friend_ids = {f.get("friendId") for f in friends}
+
+    if friend_id in friend_ids:
+        result = {"status": "already_friend", "friendId": friend_id}
+        print_json(result)
+        return 0
+
+    request_friend(api_base, token, friend_id, args.timeout)
+    result = {"status": "request_sent", "friendId": friend_id}
+    print_json(result)
+    return 2
 
 
 def add_report_args(parser: argparse.ArgumentParser) -> None:
@@ -472,10 +571,11 @@ def add_report_args(parser: argparse.ArgumentParser) -> None:
         "-c",
         help="凭证 JSON 路径（默认 src/secrets/bug-report.json）",
     )
-    parser.add_argument("--sender-id", required=True, help="发件人 ID（虾友/Bot senderId）")
-    parser.add_argument("--sender-name", required=True, help="发件人展示名")
+    parser.add_argument("--sender-id", default="", help="发件人 ID（默认从 JWT 自动解析）")
+    parser.add_argument("--sender-name", default="", help="发件人展示名（默认从 JWT 自动解析）")
     parser.add_argument("--description", required=True, help="用户 Bug 描述")
     parser.add_argument("--session-key", default="", help="当前会话 sessionKey")
+    parser.add_argument("--agent-id", default="", help="当前 Agent ID（用于定位 sessions 目录）")
     parser.add_argument(
         "--session-url",
         default="",
@@ -496,15 +596,10 @@ def add_report_args(parser: argparse.ArgumentParser) -> None:
         default=str(DEFAULT_OPENCLAW_BASE_PATH),
         help="base_url JSON 路径",
     )
-    parser.add_argument("--terminal-label", default="", help="终端名称，默认「虾友 DM」")
-    parser.add_argument("--terminal-url", default="", help="终端入口 URL（可选）")
-    parser.add_argument(
-        "--model",
+    parser.add_argument("--model",
         default="",
         help="用户/客服会话使用的模型（默认读凭证 default_model 或就近 .config.json 的 llm）",
     )
-    parser.add_argument("--context", default="", help="近期对话上下文（多行文本）")
-    parser.add_argument("--context-file", help="从文件读取近期上下文")
     parser.add_argument(
         "--oss-url",
         action="append",
@@ -524,7 +619,6 @@ def add_http_args(parser: argparse.ArgumentParser) -> None:
     parser.add_argument("--timeout", type=int, default=DEFAULT_TIMEOUT)
     parser.add_argument("--allow-expired-jwt", action="store_true")
     parser.add_argument("--friend-id", type=int, help="研发值班虾友 friendId")
-    parser.add_argument("--friend-name", default="", help="研发虾友展示名（日志用）")
 
 
 def build_parser() -> argparse.ArgumentParser:
@@ -540,6 +634,15 @@ def build_parser() -> argparse.ArgumentParser:
     add_http_args(p_send)
     p_send.add_argument("--json", action="store_true", help="JSON 输出")
 
+    p_ensure = sub.add_parser("ensure-friend", help="校验研发虾友是否为好友，否则发起好友请求")
+    p_ensure.add_argument(
+        "--cred-file",
+        "-c",
+        help="凭证 JSON 路径（默认 src/secrets/bug-report.json）",
+    )
+    add_http_args(p_ensure)
+    p_ensure.add_argument("--json", action="store_true", help="JSON 输出")
+
     p_friends = sub.add_parser("list-friends", help="列出虾友（配置 dev_friend_id 时用）")
     p_friends.add_argument(
         "--cred-file",
@@ -558,14 +661,12 @@ def main(argv: Optional[list[str]] = None) -> int:
         if getattr(args, "timeout", DEFAULT_TIMEOUT) <= 0:
             raise AppError("timeout 必须为正整数")
 
+        if args.command == "ensure-friend":
+            return cmd_ensure_friend(args)
+
         if args.command == "list-friends":
             cred = load_cred_file(getattr(args, "cred_file", None))
-            api_base = normalize_http_url(
-                (args.api_base_url or "").strip()
-                or cfg_pick(cred, "api_base_url", "BUG_API_BASE_URL")
-                or DEFAULT_API_BASE_URL,
-                field_name="api-base-url",
-            )
+            api_base = resolve_api_base(args, cred)
             token = read_bearer_token(Path(args.jwt_path).expanduser())
             ensure_jwt_valid(token, Path(args.jwt_path).expanduser(), args.allow_expired_jwt)
             friends = load_friends(api_base, token, args.timeout)
@@ -583,6 +684,9 @@ def main(argv: Optional[list[str]] = None) -> int:
                     "senderId": report.sender_id,
                     "senderName": report.sender_name,
                     "model": report.model,
+                    "modelProvider": report.model_provider,
+                    "contextTokens": report.context_tokens,
+                    "totalTokens": report.total_tokens,
                     "sessionKey": report.session_key,
                     "sessionUrl": report.session_url,
                     "ossUrls": report.oss_urls,
@@ -595,13 +699,8 @@ def main(argv: Optional[list[str]] = None) -> int:
             return 0
 
         cred = load_cred_file(args.cred_file, required=True)
-        friend_id, friend_name = resolve_dev_friend(args, cred)
-        api_base = normalize_http_url(
-            (args.api_base_url or "").strip()
-            or cfg_pick(cred, "api_base_url", "BUG_API_BASE_URL")
-            or DEFAULT_API_BASE_URL,
-            field_name="api-base-url",
-        )
+        friend_id = resolve_dev_friend(args, cred)
+        api_base = resolve_api_base(args, cred)
         jwt_path = Path(args.jwt_path).expanduser()
         token = read_bearer_token(jwt_path)
         ensure_jwt_valid(token, jwt_path, args.allow_expired_jwt)
@@ -609,7 +708,7 @@ def main(argv: Optional[list[str]] = None) -> int:
         sent = send_im_message(api_base, token, rid, message, args.timeout)
         result = {
             "success": True,
-            "friend": {"friendId": friend_id, "displayName": friend_name},
+            "friend": {"friendId": friend_id},
             "rid": rid,
             "messageId": sent.get("_id"),
             "message": message,
@@ -618,7 +717,7 @@ def main(argv: Optional[list[str]] = None) -> int:
             print_json(result)
         else:
             print("✅ Bug 工单已发送给研发虾友。")
-            print(f"收件人: {friend_name} (friendId={friend_id})")
+            print(f"收件人 friendId={friend_id}")
             if sent.get("_id"):
                 print(f"messageId: {sent.get('_id')}")
         return 0

package/skills/online-bug-report/src/secrets/bug-report.json

@@ -1,6 +1,3 @@
 {
-  "dev_friend_id": 55039,
-  "dev_friend_name": "用户2199",
-  "terminal_label": "虾友 DM",
-  "default_model": "Qwen3.5-122B-A10B"
+  "dev_friend_id": 23858
 }

package/skills/restore-state/skill.json

@@ -0,0 +1,16 @@
+{
+  "name": "restore-state",
+  "version": "1.0.0",
+  "types": ["store"],
+  "displayName": "状态恢复",
+  "description": "从 ZIP 备份文件恢复 SophClaw 完整状态。当用户要求恢复数据、还原备份、恢复账号或上传了备份 ZIP 文件时触发。支持恢复 agent 配置、会话历史、workspace 文件、语义记忆等全部状态。",
+  "changelog": [
+    {
+      "version": "1.0.0",
+      "date": "2026-05-27",
+      "changes": ["从 moltbot 迁移：ZIP 备份解析、openclaw.json 合并、会话恢复、workspace 恢复"]
+    }
+  ],
+  "createdAt": "2026-05-27",
+  "updatedAt": "2026-05-27"
+}

package/skills/restore-state/src/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: restore-state
+description: 从 ZIP 备份文件恢复 SophClaw 完整状态。当用户说要"恢复数据"、"还原备份"、"恢复我的账号"、"restore"并上传了 ZIP 文件时触发。支持恢复 agent 配置、会话历史、workspace 文件、语义记忆等全部状态。
+---
+
+# Restore State
+
+从用户上传的 ZIP 备份文件恢复 SophClaw 完整状态到当前空白容器。
+
+## 前置检查
+
+在开始恢复之前，先确认以下几点：
+
+1. 用户已通过聊天上传了一个 `.zip` 文件（从 SophClaw 前端下载的备份包）
+2. 当前容器是空白状态（新创建的容器，不包含用户之前的数据）
+3. 如果当前容器已有重要数据，警告用户会被部分覆盖
+
+向用户简短确认：
+
+- "我将用你上传的备份文件恢复你的 SophClaw 状态，包括 agent 配置、会话历史和 workspace 文件。当前容器的某些数据会被覆盖。确认继续吗？"
+
+用户确认后继续。
+
+## 定位上传的 ZIP 文件
+
+用户通过 SophClaw Web UI 上传的文件会被保存在 `~/.openclaw/media/inbound/` 目录下，文件名格式为 `<原始名称>---<uuid>.zip`。
+
+**第一步：查找最新上传的 ZIP 文件**
+
+```bash
+ls -lt ~/.openclaw/media/inbound/*.zip 2>/dev/null | head -5
+```
+
+如果用户刚上传了一个恢复用的 ZIP，最新的文件就是它（文件名包含恢复相关的关键词如 `restore`、`backup`、`openclaw` 等）。
+
+如果找到明确的文件，直接使用它的完整路径。如果有多个 ZIP，选择最新的那个。
+
+**第二步：如果 media/inbound 目录没有 ZIP**
+
+可能用户是通过其他方式提供的文件路径。请用户确认文件位置，然后用 `ls` 验证。
+
+## 执行恢复
+
+找到 ZIP 文件路径后，运行：
+
+```bash
+python3 skills/restore-state/src/scripts/restore.py "<找到的zip文件完整路径>"
+```
+
+也可以不加参数直接运行，脚本会自动搜索 `~/.openclaw/media/inbound/` 中最新的 ZIP：
+
+```bash
+python3 skills/restore-state/src/scripts/restore.py
+```
+
+## 解释恢复结果
+
+脚本会输出恢复摘要，包括：
+- 恢复了哪些 agent（main、assistant、beauty、vip-qa 等）
+- 恢复了多少条会话记录
+- 恢复了哪些 workspace
+- 是否有跳过的文件及原因
+
+向用户报告摘要。
+
+## 下一步提示
+
+提醒用户：
+
+- "由于更新了配置，SophClaw 会自动重新加载。等待约 10 秒后刷新前端页面即可看到恢复的会话和 agent。"
+
+## 异常处理
+
+| 场景 | 处理方式 |
+|------|----------|
+| ZIP 文件路径不存在 | 用 `ls ~/.openclaw/media/inbound/` 查看可用文件，选最新的 ZIP |
+| ZIP 文件格式损坏 | 请用户重新下载备份文件后再试 |
+| 未找到任何 ZIP 文件 | 请用户重新上传备份文件到聊天中 |
+| Python 或依赖缺失 | 运行 `which python3` 确认解释器存在 |
+| 权限被拒绝写入 ~/.openclaw | 检查当前用户和目录权限 |
+| openclaw.json 解析失败 | 检查备份文件是否完整，尝试用 `python3 -m json.tool` 验证 JSON |
+| Gateway 重载失败 | 手动运行 `openclaw daemon restart` |

package/skills/restore-state/src/scripts/restore.py

@@ -0,0 +1,396 @@
+#!/usr/bin/env python3
+"""SophClaw state restore tool.
+
+Extracts a SophClaw backup ZIP and merges its contents into the current
+state directory (~/.openclaw by default).
+
+Usage:
+    python3 restore.py [backup.zip]
+
+If no path is given, auto-discovers the latest ZIP in ~/.openclaw/media/inbound/.
+"""
+
+import json
+import os
+import shutil
+import sys
+import tempfile
+import zipfile
+from pathlib import Path
+
+
+def resolve_state_dir() -> Path:
+    """Resolve the SophClaw state directory, same logic as SophClaw's resolveStateDir."""
+    env_override = os.environ.get("OPENCLAW_STATE_DIR")
+    if env_override:
+        return Path(env_override).expanduser().resolve()
+
+    home = Path.home()
+    candidates = [
+        home / ".openclaw",
+        home / ".clawdbot",
+        home / ".moltbot",
+    ]
+    for candidate in candidates:
+        if candidate.exists():
+            return candidate
+
+    return home / ".openclaw"
+
+
+def auto_discover_zip(state_dir: Path) -> Path | None:
+    """Find the most recent ZIP file in the media/inbound directory."""
+    inbound = state_dir / "media" / "inbound"
+    if not inbound.is_dir():
+        return None
+
+    zip_files = sorted(
+        inbound.glob("*.zip"),
+        key=lambda p: p.stat().st_mtime,
+        reverse=True,
+    )
+    if not zip_files:
+        return None
+    return zip_files[0]
+
+
+# Config keys to RESTORE from the backup (user-created content and preferences).
+RESTORE_BACKUP_KEYS = {
+    "agents",
+    "models",
+    "skills",
+    "tools",
+    "commands",
+    "messages",
+    "session",
+    "identity",
+    "cron",
+}
+
+
+def deep_merge(base: dict, overlay: dict) -> dict:
+    """Recursively merge overlay into base. overlay values win on conflict."""
+    result = dict(base)
+    for key, value in overlay.items():
+        if key in result and isinstance(result[key], dict) and isinstance(value, dict):
+            result[key] = deep_merge(result[key], value)
+        else:
+            result[key] = value
+    return result
+
+
+def merge_openclaw_json(backup_path: Path, state_dir: Path) -> dict:
+    """Merge backup openclaw.json with the current one.
+
+    Backup values take precedence for user-config keys (agents, models, etc.).
+    Container runtime keys (gateway, channels, plugins) are kept from current.
+    """
+    current_path = state_dir / "openclaw.json"
+    if not current_path.exists():
+        with open(backup_path, "r", encoding="utf-8") as f:
+            return json.load(f)
+
+    with open(current_path, "r", encoding="utf-8") as f:
+        current = json.load(f)
+    with open(backup_path, "r", encoding="utf-8") as f:
+        backup = json.load(f)
+
+    merged = dict(current)
+
+    for key in RESTORE_BACKUP_KEYS:
+        if key in backup:
+            if key in merged and isinstance(merged[key], dict) and isinstance(backup[key], dict):
+                merged[key] = deep_merge(merged[key], backup[key])
+            else:
+                merged[key] = backup[key]
+
+    return merged
+
+
+def merge_sessions_json(backup_path: Path, current_path: Path) -> tuple[int, int]:
+    """Merge backup sessions.json into the current one.
+
+    Backup entries win on session ID conflict.
+    Returns (backup_session_count, merged_total_count).
+    """
+    current_sessions: dict = {}
+    if current_path.exists():
+        with open(current_path, "r", encoding="utf-8") as f:
+            current_sessions = json.load(f)
+
+    with open(backup_path, "r", encoding="utf-8") as f:
+        backup_sessions = json.load(f)
+
+    merged = dict(current_sessions)
+    for session_id, entry in backup_sessions.items():
+        merged[session_id] = entry
+
+    current_path.parent.mkdir(parents=True, exist_ok=True)
+    with open(current_path, "w", encoding="utf-8") as f:
+        json.dump(merged, f, ensure_ascii=False, indent=2)
+        f.write("\n")
+
+    return len(backup_sessions), len(merged)
+
+
+def copy_file(src: Path, dst: Path) -> bool:
+    """Copy a file from src to dst, creating parent dirs as needed."""
+    try:
+        dst.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copy2(src, dst)
+        return True
+    except OSError as e:
+        print(f"  [WARN] Failed to copy {src} -> {dst}: {e}", file=sys.stderr)
+        return False
+
+
+def copy_directory(src: Path, dst: Path) -> tuple[int, int]:
+    """Recursively copy directory contents from src to dst."""
+    copied = 0
+    skipped = 0
+    dst.mkdir(parents=True, exist_ok=True)
+    for item in src.rglob("*"):
+        rel = item.relative_to(src)
+        target = dst / rel
+        if item.is_dir():
+            target.mkdir(parents=True, exist_ok=True)
+            continue
+        if copy_file(item, target):
+            copied += 1
+        else:
+            skipped += 1
+    return copied, skipped
+
+
+def resolve_backup_path(args: list[str], state_dir: Path) -> tuple[Path, str]:
+    """Resolve the backup ZIP path from CLI args or auto-discovery.
+
+    Returns (path, source_description).
+    """
+    if len(args) >= 2:
+        user_path = Path(args[1]).resolve()
+        if not user_path.exists():
+            print(f"Error: backup file not found: {user_path}", file=sys.stderr)
+            sys.exit(1)
+        if not zipfile.is_zipfile(user_path):
+            print(f"Error: not a valid ZIP file: {user_path}", file=sys.stderr)
+            sys.exit(1)
+        return user_path, "user-specified"
+
+    # Auto-discover from media/inbound
+    discovered = auto_discover_zip(state_dir)
+    if discovered is None:
+        print(
+            "Error: no backup ZIP path provided and no ZIP files found in "
+            f"{state_dir / 'media' / 'inbound'}",
+            file=sys.stderr,
+        )
+        print(
+            "Usage: python3 restore.py <backup.zip>\n"
+            "       or upload a ZIP via SophClaw chat and run without arguments.",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    return discovered, "auto-discovered"
+
+
+def main():
+    state_dir = resolve_state_dir()
+    state_dir.mkdir(parents=True, exist_ok=True)
+
+    zip_path, source = resolve_backup_path(sys.argv, state_dir)
+
+    print(f"State directory: {state_dir}")
+    print(f"Backup ZIP ({source}): {zip_path}")
+    print(f"  Size: {zip_path.stat().st_size / 1024:.1f} KB")
+    print()
+
+    summary = {
+        "agents_restored": [],
+        "sessions_total": 0,
+        "sessions_merged": 0,
+        "files_copied": 0,
+        "files_skipped": 0,
+        "workspaces_restored": [],
+    }
+
+    with tempfile.TemporaryDirectory(prefix="sophclaw-restore-") as tmpdir:
+        tmp = Path(tmpdir)
+        print("Extracting ZIP...")
+        with zipfile.ZipFile(zip_path, "r") as zf:
+            zf.extractall(tmp)
+
+        top_items = list(tmp.iterdir())
+        print(f"  Extracted {len(top_items)} top-level items")
+
+        # === 1. openclaw.json ===
+        backup_config = tmp / "openclaw.json"
+        if backup_config.exists():
+            print("\n--- Config ---")
+            print("  Merging openclaw.json...")
+            merged = merge_openclaw_json(backup_config, state_dir)
+
+            config_target = state_dir / "openclaw.json"
+            with open(config_target, "w", encoding="utf-8") as f:
+                json.dump(merged, f, ensure_ascii=False, indent=2)
+                f.write("\n")
+            print(f"  Written: {config_target}")
+
+            agents_list = merged.get("agents", {}).get("list", [])
+            for agent in agents_list:
+                summary["agents_restored"].append(agent.get("id", "unknown"))
+            print(f"  Agents restored: {', '.join(summary['agents_restored']) or 'none'}")
+        else:
+            print("  [WARN] No openclaw.json found in backup")
+
+        # === 2. Agents (sessions, models, runtime-stats) ===
+        backup_agents = tmp / "agents"
+        if backup_agents.is_dir():
+            print("\n--- Agents ---")
+            current_agents = state_dir / "agents"
+
+            for agent_dir in sorted(backup_agents.iterdir()):
+                if not agent_dir.is_dir():
+                    continue
+                agent_name = agent_dir.name
+
+                # Merge sessions.json
+                backup_sessions_json = agent_dir / "sessions" / "sessions.json"
+                current_sessions_json = current_agents / agent_name / "sessions" / "sessions.json"
+                if backup_sessions_json.exists():
+                    backup_count, merged_count = merge_sessions_json(
+                        backup_sessions_json, current_sessions_json
+                    )
+                    summary["sessions_merged"] += backup_count
+                    summary["sessions_total"] += merged_count
+                    print(
+                        f"  [{agent_name}] sessions: {backup_count} from backup, "
+                        f"{merged_count} total after merge"
+                    )
+
+                # Copy session transcript .jsonl files
+                backup_sessions_dir = agent_dir / "sessions"
+                if backup_sessions_dir.is_dir():
+                    jsonl_count = 0
+                    for session_file in backup_sessions_dir.iterdir():
+                        if session_file.suffix == ".jsonl" and session_file.name != "sessions.json":
+                            target = current_agents / agent_name / "sessions" / session_file.name
+                            if copy_file(session_file, target):
+                                jsonl_count += 1
+                    if jsonl_count > 0:
+                        print(f"  [{agent_name}] transcripts: {jsonl_count} files copied")
+
+                # Copy non-session agent files (models.json, runtime-stats, etc.)
+                for item in agent_dir.rglob("*"):
+                    if item.is_dir():
+                        continue
+                    rel = item.relative_to(agent_dir)
+                    if rel.parts[0] == "sessions":
+                        continue
+                    target = current_agents / agent_name / rel
+                    if copy_file(item, target):
+                        summary["files_copied"] += 1
+        else:
+            print("\n  [INFO] No agents directory in backup")
+
+        # === 3. Workspace directories ===
+        print("\n--- Workspaces ---")
+        for item in sorted(tmp.iterdir()):
+            if not item.is_dir():
+                continue
+            if item.name.startswith("workspace"):
+                ws_name = item.name
+                current_ws = state_dir / ws_name
+                copied, skipped = copy_directory(item, current_ws)
+                summary["files_copied"] += copied
+                summary["files_skipped"] += skipped
+                summary["workspaces_restored"].append(ws_name)
+                print(f"  [{ws_name}] {copied} files, {skipped} skipped")
+
+        # === 4. Memory SQLite files ===
+        backup_memory = tmp / "memory"
+        if backup_memory.is_dir():
+            print("\n--- Memory ---")
+            current_memory = state_dir / "memory"
+            for db_file in sorted(backup_memory.iterdir()):
+                if db_file.suffix == ".sqlite":
+                    target = current_memory / db_file.name
+                    if copy_file(db_file, target):
+                        summary["files_copied"] += 1
+                        print(f"  [{db_file.name}] restored")
+
+        # === 5. Loose files (identity, canvas, logs, media, config backups, etc.) ===
+        LOOSE_PATTERNS = [
+            "identity",
+            "canvas",
+            "logs",
+            "media",
+            "openclaw.json.bak",
+            "openclaw.json.bak.1",
+            "openclaw.json.bak.2",
+            "openclaw.json.bak.3",
+            "openclaw.json.bak.4",
+            "openclaw.json.last-good",
+            "jwt.json",
+            "update-check.json",
+        ]
+
+        print("\n--- Other Files ---")
+        for pattern in LOOSE_PATTERNS:
+            src = tmp / pattern
+            if src.exists():
+                dst = state_dir / pattern
+                if src.is_dir():
+                    copied, skipped = copy_directory(src, dst)
+                    summary["files_copied"] += copied
+                    summary["files_skipped"] += skipped
+                    print(f"  [{pattern}/] {copied} files")
+                else:
+                    if copy_file(src, dst):
+                        summary["files_copied"] += 1
+                        print(f"  [{pattern}] copied")
+
+        # Handle any remaining items not explicitly covered
+        handled = set(LOOSE_PATTERNS) | {"agents", "memory", "openclaw.json"}
+        for ws_name in summary["workspaces_restored"]:
+            handled.add(ws_name)
+
+        for item in sorted(tmp.iterdir()):
+            if item.name in handled:
+                continue
+            dst = state_dir / item.name
+            if item.is_dir():
+                copied, skipped = copy_directory(item, dst)
+                summary["files_copied"] += copied
+                summary["files_skipped"] += skipped
+                if copied > 0:
+                    print(f"  [{item.name}/] {copied} files")
+            else:
+                if copy_file(item, dst):
+                    summary["files_copied"] += 1
+                    print(f"  [{item.name}] copied")
+
+    # === Summary ===
+    print()
+    print("=" * 50)
+    print("Restore Complete")
+    print("=" * 50)
+    print(f"  Agents:      {', '.join(summary['agents_restored']) or 'none'}")
+    print(f"  Sessions:    {summary['sessions_merged']} from backup ({summary['sessions_total']} total)")
+    print(f"  Workspaces:  {', '.join(summary['workspaces_restored']) or 'none'}")
+    print(f"  Files:       {summary['files_copied']} copied, {summary['files_skipped']} skipped")
+    print()
+
+    # Touch config to trigger chokidar-based hot reload
+    config_target = state_dir / "openclaw.json"
+    if config_target.exists():
+        os.utime(config_target, None)
+        print("Config updated. SophClaw will auto-reload within a few seconds.")
+        print("Refresh your browser page to see the restored state.")
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())