sophhub 0.4.37 → 0.4.38

package/package.json

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

package/skills/claw-friend-message-capture/skill.json

@@ -0,0 +1,41 @@
+{
+  "name": "claw-friend-message-capture",
+  "version": "1.2.0",
+  "types": ["store"],
+  "displayName": "抓取虾友消息",
+  "description": "自动拉取虾友发送的 IM 消息（含文字、文件、截图），支持按好友或时间筛选，下载附件到本地。触发词：抓取虾友消息、查看虾友消息、获取好友消息、拉取未读消息、下载虾友附件。",
+  "changelog": [
+    {
+      "version": "1.2.0",
+      "date": "2026-05-29",
+      "changes": [
+        "添加 setup 子命令：支持手动配置 refresh token（从浏览器 DevTools 获取）",
+        "refresh token 多来源支持：jwt.json、环境变量 SOPHCLAW_REFRESH_TOKEN、文件 ~/.openclaw/refresh_token",
+        "添加首次设置说明文档"
+      ]
+    },
+    {
+      "version": "1.1.0",
+      "date": "2026-05-29",
+      "changes": [
+        "JWT 自动刷新：集成 sophclaw_auth 共享模块，access token 过期时自动用 refresh token 续期，有效期从 2h 延长到 30 天"
+      ]
+    },
+    {
+      "version": "1.0.1",
+      "date": "2026-05-29",
+      "changes": [
+        "修复容器 DNS ndots:5 导致 Python urllib3 解析超时：脚本启动时设 RES_OPTIONS=ndots:1"
+      ]
+    },
+    {
+      "version": "1.0.0",
+      "date": "2026-05-29",
+      "changes": [
+        "初次提交：查看频道列表、拉取好友消息历史、下载附件（图片/文件）、按时间增量抓取"
+      ]
+    }
+  ],
+  "createdAt": "2026-05-29",
+  "updatedAt": "2026-05-29T12:00:00Z"
+}

package/skills/claw-friend-message-capture/src/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: claw-friend-message-capture
+description: 自动抓取虾友发送的 IM 消息，包括文字、截图和文件附件。场景：抓取虾友消息、查看虾友消息、获取好友消息、拉取未读消息、下载虾友附件。
+---
+
+# 抓取虾友消息
+
+通过 Sophnet IM API 拉取虾友（好友）发送的消息，支持文字、图片截图和文件附件。脚本 `{baseDir}/scripts/capture_messages.py` 提供四个子命令。
+
+## 子命令速查
+
+| 子命令 | 用途 | 示例场景 |
+|--------|------|---------|
+| `friends` | 查看所有虾友及 DM 频道 | "列出我的虾友" |
+| `list` | 拉取指定好友的消息历史 | "查看小明的最近消息" |
+| `unread` | 拉取所有未读/最近消息 | "抓取虾友消息" / "查看未读消息" |
+| `download` | 下载消息附件（图片/文件） | "下载虾友发的截图" |
+
+## 用法
+
+### 1. 列出虾友 + DM 频道
+
+```bash
+uv run {baseDir}/scripts/capture_messages.py friends --json
+```
+
+输出每项含 `friendId`、`nickname`、`dmChannelId`（rid）。
+
+### 2. 拉取指定好友消息
+
+```bash
+# 通过 friendId 自动查找 DM 频道
+uv run {baseDir}/scripts/capture_messages.py list --friend-id 123 --count 30
+
+# 直接用 rid（DM 频道 ID）
+uv run {baseDir}/scripts/capture_messages.py list --rid "<rid>" --count 30
+
+# 指定时间范围（latest 为毫秒时间戳，拉取此时间之前的消息）
+uv run {baseDir}/scripts/capture_messages.py list --rid "<rid>" --latest 1700000000000 --count 20
+```
+
+### 3. 抓取所有未读/最近消息
+
+```bash
+# 拉取所有 DM 频道最新消息
+uv run {baseDir}/scripts/capture_messages.py unread
+
+# 仅拉取有未读的频道，每个频道 20 条
+uv run {baseDir}/scripts/capture_messages.py unread --count 20 --min-unread 1
+```
+
+### 4. 下载消息附件
+
+```bash
+# 下载指定消息中的图片和文件
+uv run {baseDir}/scripts/capture_messages.py download \
+  --rid "<rid>" \
+  --msg-id "<消息ID>" \
+  --out-dir ./downloads
+```
+
+附件保存到 `{out-dir}/images/`（截图）和 `{out-dir}/files/`（文件）。
+
+## 执行建议
+
+- 用户说「抓取虾友消息」→ 先执行 `friends --json`，然后对每个 DM 频道执行 `list` 或批量执行 `unread`
+- 用户说「下载虾友发的图片」→ 从消息 JSON 中找到 `imageAttachments`，对目标消息执行 `download`
+- 用户提供昵称 → 从 `friends` 输出中匹配 `nickname`，拿到 `dmChannelId` 再拉消息
+
+## 首次设置（获取 refresh token）
+
+首次使用前需配置 refresh token，之后 JWT 过期会自动续期。
+
+### 获取 refresh token
+
+1. 浏览器打开 Sophnet 并登录
+2. 按 F12 → **应用**（Application）→ **本地存储**（Local Storage）→ `user-info`
+3. 复制其中 `refreshToken` 字段的值
+
+也可以打开浏览器控制台（Console），执行以下命令直接复制：
+
+```js
+copy(JSON.parse(localStorage['user-info']).refreshToken)
+```
+
+### 配置 refresh token（三选一）
+
+**方式 A — setup 子命令（推荐）**：
+
+```bash
+uv run {baseDir}/scripts/capture_messages.py setup --refresh-token "<你的refreshToken>"
+```
+
+**方式 B — 环境变量**（重启后失效）：
+
+```bash
+export SOPHCLAW_REFRESH_TOKEN="<你的refreshToken>"
+```
+
+**方式 C — 文件持久化**：
+
+```bash
+echo "<你的refreshToken>" > ~/.openclaw/refresh_token
+```
+
+配置完成后即可正常使用，JWT 过期时自动续期。
+
+## 注意事项
+
+- 从 `/home/node/.openclaw/jwt.json` 的 `web_jwt` 字段读取 JWT，通过 `sophclaw_auth` 模块自动检测过期并续期（refresh token 有效期最长 30 天）
+- refresh token 读取优先级：jwt.json → 环境变量 `SOPHCLAW_REFRESH_TOKEN` → 文件 `~/.openclaw/refresh_token`
+- 默认 API 地址：`https://yagent.sophnet.com/api`，可通过 `--api-base-url` 或环境变量 `SOPHCLAW_API_BASE_URL` 覆盖
+- 附件 URL 默认按 `https://www.sophnet.com` 拼接 Origin，可通过 `--origin` 或 `SOPHCLAW_ORIGIN` 覆盖
+- 凭证文件和 JWT 切勿提交 Git
+- 本 skill 仅提供单次拉取，如需定时自动抓取，请在 Agent 侧配置 Cron Job

package/skills/claw-friend-message-capture/src/pyproject.toml

@@ -0,0 +1,12 @@
+[project]
+name = "claw-friend-message-capture"
+version = "1.2.0"
+description = "Capture Sophclaw friend IM messages including files and screenshots"
+requires-python = ">=3.8"
+dependencies = [
+    "requests>=2.28.0",
+]
+
+# [[tool.uv.index]]
+# url = "https://mirrors.aliyun.com/pypi/simple/"
+# default = true

package/skills/claw-friend-message-capture/src/scripts/capture_messages.py

@@ -0,0 +1,573 @@
+#!/usr/bin/env python3
+"""抓取虾友 IM 消息：好友列表、消息拉取、附件下载。"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import os
+import sys
+import time
+import urllib.parse
+from pathlib import Path
+from typing import Any, Optional
+
+import requests
+
+from sophclaw_auth import SophclawAuth
+
+# 修复容器 DNS ndots:5 问题：避免 Python urllib3 在 search domain 上耗尽重试
+os.environ.setdefault("RES_OPTIONS", "ndots:1")
+os.environ.setdefault("SOCKET_THREAD_POOL_SIZE", "0")
+
+DEFAULT_TIMEOUT = 30
+DEFAULT_API_BASE_URL = "https://yagent.sophnet.com/api"
+DEFAULT_JWT_PATH = Path("/home/node/.openclaw/jwt.json")
+MAX_RETRIES = 3
+RETRY_DELAY = 2
+DEFAULT_PAGE_SIZE = 50
+
+
+class AppError(RuntimeError):
+    pass
+
+
+def configure_stdio() -> None:
+    for name in ("stdout", "stderr"):
+        stream = getattr(sys, name, None)
+        if stream is not None and hasattr(stream, "reconfigure"):
+            stream.reconfigure(encoding="utf-8", errors="replace")
+
+
+def print_json(payload: Any) -> None:
+    print(json.dumps(payload, ensure_ascii=False, indent=2))
+
+
+def request_json(
+    method: str,
+    url: str,
+    token: str,
+    timeout: int,
+    payload: Optional[dict[str, Any]] = None,
+    raw_response: bool = False,
+) -> Any:
+    headers = {
+        "Authorization": "Bearer {}".format(token),
+        "Accept": "application/json",
+    }
+    if payload is not None:
+        headers["Content-Type"] = "application/json"
+
+    last_error = None
+    for attempt in range(1, MAX_RETRIES + 1):
+        try:
+            resp = requests.request(
+                method=method,
+                url=url,
+                headers=headers,
+                json=payload,
+                timeout=timeout,
+            )
+            if raw_response:
+                return resp
+            if not resp.ok:
+                raise AppError(
+                    "HTTP {} {}: {}".format(resp.status_code, url, resp.text[:500])
+                )
+            data = resp.json()
+            if isinstance(data, dict) and data.get("status") not in (None, 0):
+                raise AppError(
+                    "接口错误: status={} message={!r}".format(
+                        data.get("status"), data.get("message")
+                    )
+                )
+            return data if isinstance(data, dict) else {"result": data}
+        except requests.exceptions.ConnectionError as exc:
+            last_error = exc
+            if attempt < MAX_RETRIES:
+                time.sleep(RETRY_DELAY * attempt)
+        except requests.exceptions.Timeout as exc:
+            last_error = exc
+            if attempt < MAX_RETRIES:
+                time.sleep(RETRY_DELAY * attempt)
+        except AppError:
+            raise
+        except Exception as exc:
+            last_error = exc
+            if attempt < MAX_RETRIES:
+                time.sleep(RETRY_DELAY * attempt)
+
+    raise AppError("请求失败 {} (重试 {} 次后仍失败): {}".format(url, MAX_RETRIES, last_error))
+
+
+def unwrap_result(data: dict[str, Any]) -> Any:
+    return data.get("result") if "result" in data else data
+
+
+def resolve_api_base(args: argparse.Namespace) -> str:
+    if args.api_base_url and args.api_base_url.strip():
+        return args.api_base_url.strip().rstrip("/")
+    env_base = os.environ.get("SOPHCLAW_API_BASE_URL", "").strip()
+    if env_base:
+        return env_base.rstrip("/")
+    return DEFAULT_API_BASE_URL
+
+
+def resolve_origin(args: argparse.Namespace) -> str:
+    if args.origin and args.origin.strip():
+        return args.origin.strip().rstrip("/")
+    env_origin = os.environ.get("SOPHCLAW_ORIGIN", "").strip()
+    if env_origin:
+        return env_origin.rstrip("/")
+    return "https://www.sophnet.com"
+
+
+def expand_path(path_str: str) -> Path:
+    return Path(path_str).expanduser().resolve()
+
+
+def looks_like_image(url: str, name: Optional[str] = None) -> bool:
+    lower = (name or "") + (url or "")
+    return bool(
+        __import__("re").search(r"\.(jpg|jpeg|png|gif|webp|bmp|heic)(\?|$)", lower, __import__("re").IGNORECASE)
+    )
+
+
+def cmd_setup(args: argparse.Namespace) -> int:
+    """将 refresh token 写入 jwt.json。"""
+    try:
+        path = SophclawAuth.setup_refresh_token(
+            refresh_token=args.refresh_token,
+            jwt_path=expand_path(args.jwt_path),
+        )
+        print("refresh token 已写入 {}".format(path))
+        print("现在可以正常使用技能了，JWT 过期时将会自动续期。")
+        return 0
+    except Exception as exc:
+        print("设置失败: {}".format(exc), file=sys.stderr)
+        return 1
+
+
+def normalize_message(m: dict[str, Any], origin: str) -> dict[str, Any]:
+    """标准化消息对象，分离图片和文件附件。"""
+    msg = {
+        "id": str(m.get("_id", m.get("id", ""))),
+        "rid": str(m.get("rid", "")),
+        "msg": str(m.get("msg", "")),
+        "ts": m.get("ts"),
+        "updatedAt": m.get("_updatedAt", m.get("updatedAt")),
+        "u": None,
+        "imageAttachments": [],
+        "fileAttachments": [],
+    }
+
+    if isinstance(m.get("u"), dict):
+        u = m["u"]
+        msg["u"] = {
+            "id": str(u.get("_id", u.get("id", ""))),
+            "username": str(u.get("username", "")),
+            "name": u.get("name"),
+        }
+
+    all_attachments = []
+    if isinstance(m.get("attachments"), list):
+        all_attachments.extend(m["attachments"])
+    if isinstance(m.get("file"), dict):
+        all_attachments.append(m["file"])
+    if isinstance(m.get("files"), list):
+        all_attachments.extend(m["files"])
+
+    for att in all_attachments:
+        if not isinstance(att, dict):
+            continue
+        url = att.get("image_url") or att.get("imageUrl") or att.get("url", "")
+        name = att.get("name") or att.get("title")
+        if url and (str(att.get("type", "")).startswith("image/") or looks_like_image(url, name)):
+            full_url = _resolve_url(url, origin)
+            msg["imageAttachments"].append({"url": full_url, "title": name})
+        elif url:
+            full_url = _resolve_url(url, origin)
+            msg["fileAttachments"].append({
+                "url": full_url,
+                "name": name,
+                "type": att.get("type"),
+                "size": att.get("size"),
+            })
+
+    return msg
+
+
+def _resolve_url(raw: str, origin: str) -> str:
+    if not raw:
+        return raw
+    if raw.startswith("http://") or raw.startswith("https://"):
+        return raw
+    if raw.startswith("/"):
+        return origin.rstrip("/") + raw
+    return raw
+
+
+def download_file(url: str, dest: Path, token: str, timeout: int) -> Path:
+    """下载文件到 dest，dest 为父目录，自动处理文件名。"""
+    dest = dest.expanduser().resolve()
+    dest.mkdir(parents=True, exist_ok=True)
+
+    resp = request_json("GET", url, token, timeout, raw_response=True)
+    content_type = resp.headers.get("Content-Type", "")
+    content_disp = resp.headers.get("Content-Disposition", "")
+
+    filename = None
+    if "filename=" in content_disp:
+        import re
+        m = re.search(r'filename[^=]*="?([^";\s]+)"?', content_disp)
+        if m:
+            filename = m.group(1)
+
+    if not filename:
+        parsed = urllib.parse.urlparse(url)
+        path_part = parsed.path
+        if path_part and "/" in path_part:
+            filename = path_part.rsplit("/", 1)[-1]
+        if not filename or "." not in filename:
+            ext = ".jpg" if "image" in content_type else ".bin"
+            h = hashlib.md5(url.encode()).hexdigest()[:8]
+            filename = "{}{}".format(h, ext)
+
+    filepath = dest / filename
+    with filepath.open("wb") as fp:
+        for chunk in resp.iter_content(chunk_size=8192):
+            fp.write(chunk)
+
+    return filepath
+
+
+# ---------------------------------------------------------------------------
+# 子命令
+# ---------------------------------------------------------------------------
+
+
+def cmd_friends(args: argparse.Namespace) -> int:
+    """列出所有虾友及其 DM 频道。"""
+    api_base = resolve_api_base(args)
+    auth = SophclawAuth(jwt_path=expand_path(args.jwt_path), api_base_url=api_base)
+    token = auth.get_valid_token()
+
+    # 获取好友列表
+    data = request_json("GET", "{}/sys/openclaw/friend/list".format(api_base), token, args.timeout)
+    result = unwrap_result(data)
+    friends = result.get("friends", []) if isinstance(result, dict) else []
+
+    output = []
+    for f in friends:
+        friend_id = f.get("friendId")
+        nickname = f.get("nickname", "未知")
+        dm_channel = None
+
+        # 获取/创建 DM 频道
+        if friend_id:
+            try:
+                dm_data = request_json(
+                    "POST",
+                    "{}/sys/openclaw/friend/dm".format(api_base),
+                    token,
+                    args.timeout,
+                    payload={"friendId": friend_id},
+                )
+                dm_result = unwrap_result(dm_data)
+                dm_channel = (
+                    dm_result.get("channel") if isinstance(dm_result, dict) else dm_result
+                )
+            except AppError:
+                pass
+
+        output.append({
+            "friendId": friend_id,
+            "nickname": nickname,
+            "avatarUrl": f.get("avatarUrl"),
+            "dmChannelId": str(dm_channel.get("_id", "")) if dm_channel else None,
+            "dmChannelName": dm_channel.get("fname") or dm_channel.get("name") if dm_channel else None,
+        })
+
+    if args.json:
+        print_json({"total": len(output), "friends": output})
+    else:
+        for item in output:
+            ch_id = item["dmChannelId"] or "无"
+            print("  {} (friendId={}, dm={})".format(item["nickname"], item["friendId"], ch_id))
+
+    return 0
+
+
+def cmd_list(args: argparse.Namespace) -> int:
+    """拉取指定好友/频道的历史消息。"""
+    api_base = resolve_api_base(args)
+    origin = resolve_origin(args)
+    auth = SophclawAuth(jwt_path=expand_path(args.jwt_path), api_base_url=api_base)
+    token = auth.get_valid_token()
+
+    rid = args.rid
+    if not rid and args.friend_id is not None:
+        # 通过 friendId 查找 DM 频道
+        dm_data = request_json(
+            "POST",
+            "{}/sys/openclaw/friend/dm".format(api_base),
+            token,
+            args.timeout,
+            payload={"friendId": args.friend_id},
+        )
+        dm_result = unwrap_result(dm_data)
+        dm_channel = dm_result.get("channel") if isinstance(dm_result, dict) else dm_result
+        if dm_channel:
+            rid = str(dm_channel.get("_id", ""))
+
+    if not rid:
+        raise AppError("请指定 --rid 或 --friend-id")
+
+    count = args.count if args.count and args.count > 0 else DEFAULT_PAGE_SIZE
+    params = {"rid": rid, "count": min(count, 100)}
+    if args.latest is not None:
+        params["latest"] = args.latest
+    if args.oldest is not None:
+        params["oldest"] = args.oldest
+    if args.offset is not None:
+        params["offset"] = args.offset
+
+    query = "&".join("{}={}".format(k, v) for k, v in params.items())
+    url = "{}/sys/openclaw/im/channels.history?{}".format(api_base, query)
+    data = request_json("GET", url, token, args.timeout)
+    result = unwrap_result(data)
+
+    raw_messages = []
+    if isinstance(result, dict):
+        raw_messages = result.get("messages", [])
+    elif isinstance(result, list):
+        raw_messages = result
+
+    messages = [normalize_message(m, origin) for m in raw_messages if isinstance(m, dict)]
+
+    output = {
+        "rid": rid,
+        "count": len(messages),
+        "messages": messages,
+    }
+    print_json(output)
+    return 0
+
+
+def cmd_unread(args: argparse.Namespace) -> int:
+    """拉取所有 DM 频道的最近消息（模拟未读消息）。"""
+    api_base = resolve_api_base(args)
+    origin = resolve_origin(args)
+    auth = SophclawAuth(jwt_path=expand_path(args.jwt_path), api_base_url=api_base)
+    token = auth.get_valid_token()
+
+    # 拉取频道列表（含未读数）
+    data = request_json("GET", "{}/sys/openclaw/im/channels.list".format(api_base), token, args.timeout)
+    result = unwrap_result(data)
+    channels = result.get("channels", []) if isinstance(result, dict) else []
+    if isinstance(channels, list):
+        pass
+    else:
+        channels = []
+
+    # 过滤出 DM 频道 (t == "d")
+    dm_channels = [ch for ch in channels if isinstance(ch, dict) and ch.get("t") == "d"]
+
+    min_unread = args.min_unread if args.min_unread is not None else 0
+    if min_unread > 0:
+        dm_channels = [ch for ch in dm_channels if ch.get("unread", 0) >= min_unread]
+
+    count = args.count if args.count and args.count > 0 else 20
+    output_channels = []
+
+    for ch in dm_channels:
+        rid = str(ch.get("_id", ch.get("rid", "")))
+        # 拉取最近消息
+        try:
+            h_url = "{}/sys/openclaw/im/channels.history?rid={}&count={}".format(
+                api_base, rid, min(count, 100)
+            )
+            h_data = request_json("GET", h_url, token, args.timeout)
+            h_result = unwrap_result(h_data)
+            raw_msgs = (
+                h_result.get("messages", [])
+                if isinstance(h_result, dict)
+                else (h_result if isinstance(h_result, list) else [])
+            )
+            messages = [
+                normalize_message(m, origin) for m in raw_msgs if isinstance(m, dict)
+            ]
+        except AppError:
+            messages = []
+
+        output_channels.append({
+            "rid": rid,
+            "name": ch.get("fname") or ch.get("name", ""),
+            "unread": ch.get("unread", 0),
+            "lm": ch.get("lm"),
+            "lastMessage": ch.get("lastMessage"),
+            "messages": messages,
+            "messageCount": len(messages),
+        })
+
+    output = {
+        "channels": output_channels,
+        "total": len(output_channels),
+    }
+    print_json(output)
+    return 0
+
+
+def cmd_download(args: argparse.Namespace) -> int:
+    """下载指定消息的附件。"""
+    api_base = resolve_api_base(args)
+    origin = resolve_origin(args)
+    auth = SophclawAuth(jwt_path=expand_path(args.jwt_path), api_base_url=api_base)
+    token = auth.get_valid_token()
+    out_dir = expand_path(args.out_dir or "./shrimp_attachments")
+
+    rid = args.rid
+    msg_id = args.msg_id
+
+    if not rid or not msg_id:
+        raise AppError("请同时指定 --rid 和 --msg-id")
+
+    # 查历史消息找到目标消息
+    url = "{}/sys/openclaw/im/channels.history?rid={}&count=100".format(api_base, rid)
+    data = request_json("GET", url, token, args.timeout)
+    result = unwrap_result(data)
+    raw_msgs = (
+        result.get("messages", []) if isinstance(result, dict) else (result if isinstance(result, list) else [])
+    )
+
+    target_msg = None
+    for m in raw_msgs:
+        m_id = str(m.get("_id", m.get("id", "")))
+        if m_id == msg_id or msg_id in m_id:
+            target_msg = m
+            break
+
+    if target_msg is None:
+        raise AppError("未找到消息: msgId={}".format(msg_id))
+
+    normalized = normalize_message(target_msg, origin)
+    image_dir = out_dir / "images"
+    file_dir = out_dir / "files"
+    downloaded = []
+
+    # 下载图片
+    for idx, img in enumerate(normalized.get("imageAttachments", [])):
+        img_url = img.get("url")
+        if img_url:
+            try:
+                dest = download_file(img_url, image_dir, token, args.timeout)
+                downloaded.append({"type": "image", "url": img_url, "path": str(dest)})
+            except AppError as exc:
+                downloaded.append({"type": "image", "url": img_url, "error": str(exc)})
+
+    # 下载文件
+    for idx, file_att in enumerate(normalized.get("fileAttachments", [])):
+        file_url = file_att.get("url")
+        if file_url:
+            try:
+                dest = download_file(file_url, file_dir, token, args.timeout)
+                downloaded.append({"type": "file", "url": file_url, "path": str(dest)})
+            except AppError as exc:
+                downloaded.append({"type": "file", "url": file_url, "error": str(exc)})
+
+    output = {
+        "msgId": normalized["id"],
+        "downloaded": downloaded,
+        "total": len(downloaded),
+    }
+    print_json(output)
+    return 0
+
+
+# ---------------------------------------------------------------------------
+# 命令行入口
+# ---------------------------------------------------------------------------
+
+
+def add_http_args(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument(
+        "--api-base-url",
+        default="",
+        help="虾友 API 根地址（默认 {}）".format(DEFAULT_API_BASE_URL),
+    )
+    parser.add_argument("--jwt-path", default=str(DEFAULT_JWT_PATH), help="JWT 文件路径")
+    parser.add_argument("--timeout", type=int, default=DEFAULT_TIMEOUT, help="HTTP 超时秒数")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="抓取虾友 IM 消息")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    # friends
+    p_friends = sub.add_parser("friends", help="列出所有虾友及 DM 频道")
+    add_http_args(p_friends)
+    p_friends.add_argument("--json", action="store_true", help="JSON 输出")
+
+    # list
+    p_list = sub.add_parser("list", help="拉取指定好友/频道的历史消息")
+    add_http_args(p_list)
+    p_list.add_argument("--origin", default="", help="附件 URL 拼接前缀（默认 https://www.sophnet.com）")
+    p_list.add_argument("--rid", default="", help="DM 频道 ID")
+    p_list.add_argument("--friend-id", type=int, default=None, help="好友 ID（自动查找 DM 频道）")
+    p_list.add_argument("--count", type=int, default=DEFAULT_PAGE_SIZE, help="拉取条数（默认 {}，上限 100）".format(DEFAULT_PAGE_SIZE))
+    p_list.add_argument("--latest", type=int, default=None, help="拉取此时间戳之前的消息（毫秒）")
+    p_list.add_argument("--oldest", type=int, default=None, help="拉取此时间戳之后的消息（毫秒）")
+    p_list.add_argument("--offset", type=int, default=None, help="偏移量")
+
+    # unread
+    p_unread = sub.add_parser("unread", help="拉取所有 DM 频道的最近/未读消息")
+    add_http_args(p_unread)
+    p_unread.add_argument("--origin", default="", help="附件 URL 拼接前缀（默认 https://www.sophnet.com）")
+    p_unread.add_argument("--count", type=int, default=20, help="每个频道拉取条数（默认 20）")
+    p_unread.add_argument("--min-unread", type=int, default=0, help="最小未读数过滤（默认 0 表示全部）")
+
+    # download
+    p_download = sub.add_parser("download", help="下载指定消息的附件")
+    add_http_args(p_download)
+    p_download.add_argument("--origin", default="", help="附件 URL 拼接前缀")
+    p_download.add_argument("--rid", required=True, help="频道 ID")
+    p_download.add_argument("--msg-id", required=True, help="消息 ID")
+    p_download.add_argument("--out-dir", default="./shrimp_attachments", help="输出目录")
+
+    # setup — 设置 refresh token
+    p_setup = sub.add_parser("setup", help="设置 refresh token 到 jwt.json")
+    p_setup.add_argument(
+        "--refresh-token", required=True, help="从浏览器 localStorage user-info 中复制的 refreshToken"
+    )
+    p_setup.add_argument("--jwt-path", default=str(DEFAULT_JWT_PATH), help="JWT 文件路径")
+
+    return parser
+
+
+def main(argv: Optional[list[str]] = None) -> int:
+    configure_stdio()
+    args = build_parser().parse_args(argv)
+    try:
+        if args.timeout <= 0:
+            raise AppError("timeout 必须为正整数")
+
+        if args.command == "friends":
+            return cmd_friends(args)
+        if args.command == "list":
+            return cmd_list(args)
+        if args.command == "unread":
+            return cmd_unread(args)
+        if args.command == "download":
+            return cmd_download(args)
+        if args.command == "setup":
+            return cmd_setup(args)
+
+        raise AppError("未知命令: {}".format(args.command))
+    except AppError as exc:
+        print("ERROR: {}".format(exc), file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/skills/claw-friend-message-capture/src/scripts/sophclaw_auth.py

@@ -0,0 +1,395 @@
+#!/usr/bin/env python3
+"""Sophclaw Skill 共享认证模块：JWT 自动刷新。
+
+用法：
+    from sophclaw_auth import SophclawAuth
+
+    auth = SophclawAuth(api_base_url="https://yagent.sophnet.com/api")
+    token = auth.get_valid_token()  # 自动检测过期并刷新
+
+refresh token 读取优先级（从高到低）：
+    1. jwt.json 中的 web_refresh_token 字段（Web 端同步，v1.1.0+）
+    2. 环境变量 SOPHCLAW_REFRESH_TOKEN
+    3. 文件 ~/.openclaw/refresh_token
+    4. 若都没有且 access token 过期，抛出 AuthError 提示用户 setup
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+from pathlib import Path
+from typing import Any, Optional
+import sys
+import time
+
+# DNS fix: container ndots:5 breaks Python thread pool DNS
+import os as _os
+import time
+_os.environ.setdefault('RES_OPTIONS', 'ndots:1')
+_os.environ.setdefault('SOCKET_THREAD_POOL_SIZE', '0')
+del _os
+
+import requests
+
+DEFAULT_JWT_PATH = Path("/home/node/.openclaw/jwt.json")
+DEFAULT_REFRESH_TOKEN_FILE = Path("/home/node/.openclaw/refresh_token")
+# 提前 5 分钟刷新，避免边界情况
+REFRESH_MARGIN_SECONDS = 300
+MAX_RETRIES = 3
+RETRY_DELAY = 2
+REQUEST_TIMEOUT = 30
+
+SETUP_INSTRUCTIONS = """
+========================================
+未找到 refresh token，无法自动续期 JWT。
+
+获取 refresh token 的方法：
+  1. 浏览器打开 Sophnet，按 F12 → Application → Local Storage → user-info
+     复制其中 refreshToken 字段的值
+  2. 执行以下命令完成设置（二选一）：
+
+     方式 A — 写入环境变量（推荐，重启后失效需重设）：
+       export SOPHCLAW_REFRESH_TOKEN="<你的refreshToken>"
+
+     方式 B — 写入文件（持久化）：
+       echo "<你的refreshToken>" > ~/.openclaw/refresh_token
+
+     方式 C — 用脚本 setup 子命令（写入 jwt.json，持久化）：
+       uv run {baseDir}/scripts/auto_accept.py setup --refresh-token "<你的refreshToken>"
+
+  3. 设置完成后重新执行原有命令即可。
+========================================
+"""
+
+
+class AuthError(RuntimeError):
+    """认证相关错误。"""
+    pass
+
+
+def _resolve_api_base(api_base_url: Optional[str] = None) -> str:
+    if api_base_url and api_base_url.strip():
+        return api_base_url.strip().rstrip("/")
+    env_base = os.environ.get("SOPHCLAW_API_BASE_URL", "").strip()
+    if env_base:
+        return env_base.rstrip("/")
+    return "https://yagent.sophnet.com/api"
+
+
+def _load_json_file(path: Path) -> dict[str, Any]:
+    try:
+        with path.open("r", encoding="utf-8") as fp:
+            data = json.load(fp)
+    except OSError as exc:
+        raise AuthError("无法读取文件 {}: {}".format(path, exc)) from exc
+    except json.JSONDecodeError as exc:
+        raise AuthError("文件不是有效 JSON: {}: {}".format(path, exc)) from exc
+    if not isinstance(data, dict):
+        raise AuthError("JSON 根对象必须是对象: {}".format(path))
+    return data
+
+
+def _save_json_file(path: Path, data: dict[str, Any]) -> None:
+    try:
+        parent = path.parent
+        if not parent.exists():
+            parent.mkdir(parents=True, exist_ok=True)
+        tmp_path = path.with_suffix(path.suffix + ".tmp")
+        with tmp_path.open("w", encoding="utf-8") as fp:
+            json.dump(data, fp, ensure_ascii=False, indent=2)
+        tmp_path.replace(path)
+    except OSError as exc:
+        raise AuthError("无法写入文件 {}: {}".format(path, exc)) from exc
+
+
+def _read_refresh_token_file(path: Path) -> Optional[str]:
+    """读取纯文本 refresh token 文件。"""
+    try:
+        with path.open("r", encoding="utf-8") as fp:
+            token = fp.read().strip()
+            return token if token else None
+    except OSError:
+        return None
+
+
+def _save_refresh_token_file(token: str, path: Optional[Path] = None) -> None:
+    """将 refresh token 写入独立纯文本文件（不被 Web 同步覆盖）。"""
+    if path is None:
+        path = DEFAULT_REFRESH_TOKEN_FILE
+    try:
+        parent = path.parent
+        if not parent.exists():
+            parent.mkdir(parents=True, exist_ok=True)
+        with path.open("w", encoding="utf-8") as fp:
+            fp.write(token.strip() + "\n")
+    except OSError as exc:
+        raise AuthError("无法写入 refresh token 文件 {}: {}".format(path, exc)) from exc
+
+
+def _resolve_refresh_token(
+    jwt_data: dict[str, Any],
+    jwt_path: Path,
+) -> str:
+    """查找 refresh token，优先级：独立文件 → jwt.json → 环境变量。
+
+    - 独立文件 ~/.openclaw/refresh_token 不会被 Web 前端覆盖
+    - jwt.json 的 web_refresh_token 会在界面刷新时丢失
+    - 环境变量重启后失效
+
+    返回 refresh token 字符串，找不到则抛出 AuthError。
+    """
+    # 1. 独立文件 ~/.openclaw/refresh_token（最稳定，不被 Web 覆盖）
+    rt = _read_refresh_token_file(DEFAULT_REFRESH_TOKEN_FILE)
+    if rt:
+        _sophlog("从 {} 读取 refresh token".format(DEFAULT_REFRESH_TOKEN_FILE))
+        return rt
+
+    # 2. jwt.json 中的 web_refresh_token（会被 Web 刷新重置）
+    rt = jwt_data.get("web_refresh_token")
+    if isinstance(rt, str) and rt.strip():
+        # 顺便备份到独立文件，防止 Web 刷新后丢失
+        try:
+            _save_refresh_token_file(rt)
+        except AuthError:
+            pass
+        return rt.strip()
+
+    # 3. 环境变量
+    rt = os.environ.get("SOPHCLAW_REFRESH_TOKEN", "").strip()
+    if rt:
+        _sophlog("从环境变量 SOPHCLAW_REFRESH_TOKEN 读取 refresh token")
+        try:
+            _save_refresh_token_file(rt)
+            jwt_data["web_refresh_token"] = rt
+            _save_json_file(jwt_path, jwt_data)
+        except AuthError:
+            pass
+        return rt
+
+    raise AuthError(SETUP_INSTRUCTIONS)
+
+
+def _http_request(
+    method: str,
+    url: str,
+    token: str,
+    timeout: int = REQUEST_TIMEOUT,
+    payload: Optional[dict[str, Any]] = None,
+    expect_json: bool = True,
+) -> Any:
+    headers = {
+        "Authorization": "Bearer {}".format(token),
+        "Accept": "application/json",
+    }
+    if payload is not None:
+        headers["Content-Type"] = "application/json"
+
+    last_error = None
+    for attempt in range(1, MAX_RETRIES + 1):
+        try:
+            resp = requests.request(
+                method=method,
+                url=url,
+                headers=headers,
+                json=payload,
+                timeout=timeout,
+            )
+            if not expect_json:
+                return resp
+            if not resp.ok:
+                raise AuthError(
+                    "HTTP {} {}: {}".format(resp.status_code, url, resp.text[:500])
+                )
+            data = resp.json()
+            if isinstance(data, dict) and data.get("status") not in (None, 0):
+                raise AuthError(
+                    "接口错误: status={} message={!r}".format(
+                        data.get("status"), data.get("message")
+                    )
+                )
+            return data if isinstance(data, dict) else {"result": data}
+        except requests.exceptions.ConnectionError as exc:
+            last_error = exc
+            if attempt < MAX_RETRIES:
+                time.sleep(RETRY_DELAY * attempt)
+        except requests.exceptions.Timeout as exc:
+            last_error = exc
+            if attempt < MAX_RETRIES:
+                time.sleep(RETRY_DELAY * attempt)
+        except AuthError:
+            raise
+        except Exception as exc:
+            last_error = exc
+            if attempt < MAX_RETRIES:
+                time.sleep(RETRY_DELAY * attempt)
+
+    raise AuthError("请求失败 {} (重试 {} 次后仍失败): {}".format(url, MAX_RETRIES, last_error))
+
+
+def _sophlog(msg: str) -> None:
+    """模块级日志函数，供 _resolve_refresh_token 等模块函数调用。"""
+    print("[sophclaw-auth] {}".format(msg), file=sys.stderr)
+
+
+class SophclawAuth:
+    """Sophclaw 认证管理器：自动检测 JWT 过期并刷新。"""
+
+    def __init__(
+        self,
+        jwt_path: Optional[Path] = None,
+        api_base_url: Optional[str] = None,
+    ):
+        self._jwt_path = Path(jwt_path or DEFAULT_JWT_PATH).expanduser().resolve()
+        self._api_base = _resolve_api_base(api_base_url)
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def get_valid_token(self) -> str:
+        """获取有效的 JWT access token，过期时自动刷新。"""
+        data = _load_json_file(self._jwt_path)
+
+        # 提取 access token
+        raw = data.get("web_jwt")
+        if not isinstance(raw, str) or not raw.strip():
+            raise AuthError("jwt.json 缺少有效 web_jwt: {}".format(self._jwt_path))
+        raw = raw.strip()
+        if raw.lower().startswith("bearer "):
+            raw = raw[7:].strip()
+
+        if not self._is_expired(raw):
+            return raw
+
+        # 尝试用 refresh token 续期（多来源查找）
+        refresh = _resolve_refresh_token(data, self._jwt_path)
+
+        self._log("JWT 已过期，尝试用 refreshToken 续期...")
+        new_token, new_refresh = self._do_refresh(refresh)
+
+        # 写回 jwt.json + 独立文件（双重保险）
+        data["web_jwt"] = "Bearer {}".format(new_token)
+        data["web_refresh_token"] = new_refresh
+        data["savedAt"] = time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
+        _save_json_file(self._jwt_path, data)
+        _save_refresh_token_file(new_refresh)
+
+        self._log("JWT 续期成功。")
+        return new_token
+
+    def get_api_base(self) -> str:
+        return self._api_base
+
+    @staticmethod
+    def setup_refresh_token(
+        refresh_token: str,
+        jwt_path: Optional[Path] = None,
+    ) -> Path:
+        """将 refresh token 写入 jwt.json。
+
+        如果 jwt.json 不存在则创建，如果已存在则保留原有字段并更新 web_refresh_token。
+        返回 jwt.json 的路径。
+        """
+        path = Path(jwt_path or DEFAULT_JWT_PATH).expanduser().resolve()
+
+        try:
+            data = _load_json_file(path)
+        except AuthError:
+            # 文件不存在或无效，创建新的
+            data = {}
+
+        data["web_refresh_token"] = refresh_token.strip()
+        if "savedAt" not in data:
+            data["savedAt"] = time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
+
+        _save_json_file(path, data)
+        _save_refresh_token_file(refresh_token.strip())
+        _log("refresh token 已写入 {} + {}".format(path, DEFAULT_REFRESH_TOKEN_FILE))
+        return path
+
+    # ------------------------------------------------------------------
+    # Internal
+    # ------------------------------------------------------------------
+
+    def _is_expired(self, token: str) -> bool:
+        """检查 token 是否已过期（含 5 分钟提前量）。"""
+        exp = self._jwt_exp_unix(token)
+        if exp is None:
+            return False  # 无法解析则不拦截
+        return time.time() >= exp - REFRESH_MARGIN_SECONDS
+
+    @staticmethod
+    def _jwt_exp_unix(token: str) -> Optional[int]:
+        try:
+            parts = token.split(".")
+            if len(parts) != 3:
+                return None
+            payload = parts[1] + "=" * (-len(parts[1]) % 4)
+            raw = base64.urlsafe_b64decode(payload.encode("ascii"))
+            data = json.loads(raw)
+            exp = data.get("exp")
+            return int(exp) if isinstance(exp, (int, float)) else None
+        except Exception:
+            return None
+
+    def _do_refresh(self, refresh_token: str) -> tuple[str, str]:
+        """调用 refresh 接口换取新 token。
+
+        返回: (new_access_token, new_refresh_token)
+        """
+        # refresh 接口只认 sophnet.com，不认 yagent.sophnet.com
+        url = "https://sophnet.com/api/sys/login/refresh"
+        try:
+            # refresh 接口不需要 Authorization header，
+            # 请求体传 refreshToken 即可
+            resp = requests.post(
+                url,
+                json={"refreshToken": refresh_token},
+                headers={
+                    "Content-Type": "application/json",
+                    "Accept": "application/json",
+                },
+                timeout=REQUEST_TIMEOUT,
+            )
+            if resp.status_code == 401:
+                raise AuthError("Refresh token 已失效，请重新登录获取新的 refresh token。")
+            if not resp.ok:
+                raise AuthError(
+                    "Refresh 接口返回 HTTP {}: {}".format(
+                        resp.status_code, resp.text[:500]
+                    )
+                )
+            data = resp.json()
+
+            # 兼容两种响应格式：
+            #   { status: 0, result: { token, refreshToken, ... } }
+            #   { token, refreshToken, ... }
+            if isinstance(data, dict) and data.get("status") not in (None, 0):
+                raise AuthError(
+                    "Refresh 接口错误: status={} message={!r}".format(
+                        data.get("status"), data.get("message")
+                    )
+                )
+            result = data.get("result") if isinstance(data, dict) else data
+            if isinstance(result, dict):
+                token_data = result
+            else:
+                token_data = data
+
+            new_token = token_data.get("token") or token_data.get("accessToken")
+            new_refresh = token_data.get("refreshToken")
+
+            if not new_token:
+                raise AuthError("Refresh 接口未返回 token: {}".format(data))
+            if not new_refresh:
+                # 某些实现可能不返回新 refreshToken，沿用旧的
+                new_refresh = refresh_token
+
+            return str(new_token), str(new_refresh)
+        except requests.exceptions.RequestException as exc:
+            raise AuthError("Refresh 请求失败: {}".format(exc)) from exc
+
+    @staticmethod
+    def _log(msg: str) -> None:
+        _sophlog(msg)