sophhub 0.4.22 → 0.4.24

package/agents/parent-toddler/.config.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.1.0",
+  "version": "1.1.1",
   "agent_id": "parent-toddler",
   "agent_label": "幼儿家长助手",
   "description": "面向幼儿家长的成长陪伴助手：亲子互动、图片与多媒体创作、日常记录与轻量咨询",
@@ -21,6 +21,12 @@
       "read"
     ]
   },
+  "heartbeat": {
+    "every": "2h",
+    "target": "none",
+    "lightContext": true,
+    "isolatedSession": true
+  },
   "skills": [
     { "name": "image-classify", "builtin": false, "auto_install": true },
     { "name": "image-identify-world", "builtin": false, "auto_install": true },

package/agents/parent-toddler/HEARTBEAT.md

@@ -1,5 +1,5 @@
-# HEARTBEAT.md
+# Heartbeat checklist
 
-# Keep this file empty (or with only comments) to skip heartbeat API calls.
-
-# Add tasks below when you want the agent to check something periodically.
+- 解析当前 Agent ID：从 SessionKey（形如 `agent:<AgentID>:...`）取第二段；隔离 Heartbeat 会话示例 `agent:<AgentID>:main:heartbeat`，`<AgentID>` 即所需 id。亦可与用户问「获取当前 Agent ID」时给出的 id 交叉确认，二者须一致。
+- 静默执行：`python3 scripts/compact_sessions_over_threshold.py --agent-id <AgentID> --json`（不向用户展示命令、路径、日志或脚本输出；脚本局部失败亦不影响 Heartbeat，仍只回复 `HEARTBEAT_OK`）
+- 完成后只回复 `HEARTBEAT_OK`，不要输出其它内容

package/agents/parent-toddler/TOOLS.md

@@ -10,6 +10,15 @@
 
 ---
 
+## 运维备忘
+
+- Session store：`/home/node/.openclaw/agents/<AgentID>/sessions/sessions.json`（`<AgentID>` 为 openclaw 运行时 id，由 Heartbeat 通过脚本参数 `--agent-id` 传入）
+- 定时压缩：见 `HEARTBEAT.md`；间隔见 `openclaw.json` 中本 agent 的 `heartbeat.every`；通过 gateway `chat.send` 向各 session 发送 `/compact` 命令
+- 须启用 `heartbeat.isolatedSession`（见 `.config.json`），否则 Heartbeat 执行期间主会话为 running，无法被选中压缩
+- **勿**在 `tools.deny` 中禁用 `exec`（Heartbeat 依赖 exec 运行压缩脚本）
+
+---
+
 ## 可选备忘
 
 以下为占位，按需填写：

package/agents/parent-toddler/scripts/compact_sessions_over_threshold.py

@@ -0,0 +1,368 @@
+#!/usr/bin/env python3
+"""
+轮询指定 agent 的 sessions.json，对「超阈值且非 running」的会话执行 /compact。
+通过 openclaw gateway call chat.send 向目标 session 发送 /compact 控制命令。
+
+Heartbeat 须在独立会话中运行（heartbeat.isolatedSession=true），否则执行脚本的
+会话在 store 里为 running，主会话无法被选中。脚本会跳过键名以 :heartbeat 结尾的
+会话，以及环境变量标明的当前执行会话。
+
+局部 compact 失败仅写入 JSON 汇总，进程仍以 exit 0 结束，便于 Heartbeat 稳定回复 HEARTBEAT_OK。
+
+默认状态目录: /home/node/.openclaw
+--agent-id 必填（由调用方传入当前 openclaw Agent ID）
+可选环境变量 OPENCLAW_STATE_DIR 覆盖状态目录
+
+用法:
+  python3 compact_sessions_over_threshold.py --agent-id parent-toddler --json
+  python3 compact_sessions_over_threshold.py --agent-id parent-toddler --dry-run
+  python3 compact_sessions_over_threshold.py --agent-id parent-toddler --threshold 100000
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import subprocess
+import sys
+import uuid
+from pathlib import Path
+from typing import Any, Iterable, Optional
+
+DEFAULT_STATE_DIR = Path("/home/node/.openclaw")
+DEFAULT_TOKEN_THRESHOLD = 80_000
+COMPACT_MESSAGE = "/compact"
+DEFAULT_AGENT_TIMEOUT_SEC = 600
+
+
+def _as_int_or_none(v: Any) -> Optional[int]:
+    if v is None or isinstance(v, bool):
+        return None
+    if isinstance(v, int):
+        return v
+    if isinstance(v, float) and v.is_integer():
+        return int(v)
+    return None
+
+
+def iter_session_rows(store: dict[str, Any]) -> Iterable[dict[str, Any]]:
+    for key, entry in store.items():
+        if not isinstance(entry, dict):
+            continue
+        st = entry.get("status")
+        yield {
+            "key": key,
+            "sessionId": entry.get("sessionId"),
+            "totalTokens": _as_int_or_none(entry.get("totalTokens")),
+            "statusRunning": st == "running",
+        }
+
+
+def list_sessions_from_store(path: Path) -> list[dict[str, Any]]:
+    raw = path.read_text(encoding="utf-8")
+    data = json.loads(raw)
+    if not isinstance(data, dict):
+        raise ValueError("根节点必须是 JSON 对象（键为 session key）")
+    return list(iter_session_rows(data))
+
+
+def filter_sessions_by_agent(rows: list[dict[str, Any]], agent_id: str) -> list[dict[str, Any]]:
+    aid = agent_id.strip()
+    if not aid:
+        raise ValueError("agent_id 不能为空")
+    prefix = f"agent:{aid}:"
+    return [row for row in rows if str(row.get("key", "")).startswith(prefix)]
+
+
+def filter_sessions_over_threshold(
+    rows: list[dict[str, Any]],
+    threshold: int,
+) -> list[dict[str, Any]]:
+    if threshold < 0:
+        raise ValueError("threshold 不能为负数")
+    out: list[dict[str, Any]] = []
+    for row in rows:
+        total = row.get("totalTokens")
+        if total is None:
+            continue
+        if total > threshold:
+            out.append(row)
+    return out
+
+
+def filter_sessions_idle(rows: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    return [row for row in rows if row.get("statusRunning") is not True]
+
+
+def _resolve_executor_session_key() -> Optional[str]:
+    for name in ("OPENCLAW_TASK_SESSION_KEY", "OPENCLAW_SESSION_KEY"):
+        value = os.environ.get(name, "").strip()
+        if value:
+            return value
+    return None
+
+
+def _resolve_executor_session_id() -> Optional[str]:
+    value = os.environ.get("OPENCLAW_TASK_SESSION_ID", "").strip()
+    return value or None
+
+
+def filter_sessions_excluded_from_compact(
+    rows: list[dict[str, Any]],
+    *,
+    executor_session_key: Optional[str] = None,
+    executor_session_id: Optional[str] = None,
+) -> list[dict[str, Any]]:
+    """跳过 Heartbeat 隔离会话及当前正在执行本脚本的会话。"""
+    key = (executor_session_key or "").strip()
+    sid = (executor_session_id or "").strip()
+    out: list[dict[str, Any]] = []
+    for row in rows:
+        row_key = str(row.get("key", ""))
+        if row_key.endswith(":heartbeat"):
+            continue
+        if key and row_key == key:
+            continue
+        row_sid = row.get("sessionId")
+        if sid and row_sid is not None and str(row_sid) == sid:
+            continue
+        out.append(row)
+    return out
+
+
+def filter_sessions_compactable(
+    rows: list[dict[str, Any]],
+    *,
+    executor_session_key: Optional[str] = None,
+    executor_session_id: Optional[str] = None,
+) -> list[dict[str, Any]]:
+    rows = filter_sessions_excluded_from_compact(
+        rows,
+        executor_session_key=executor_session_key,
+        executor_session_id=executor_session_id,
+    )
+    return filter_sessions_idle(rows)
+
+
+def resolve_state_dir() -> Path:
+    override = os.environ.get("OPENCLAW_STATE_DIR", "").strip()
+    if override:
+        return Path(override).expanduser()
+    return DEFAULT_STATE_DIR
+
+
+def resolve_sessions_store_path(agent_id: str, explicit: Optional[Path]) -> Path:
+    if explicit is not None:
+        return explicit.expanduser().resolve()
+    return resolve_state_dir() / "agents" / agent_id / "sessions" / "sessions.json"
+
+
+def find_compact_targets(
+    store_path: Path,
+    agent_id: str,
+    threshold: int,
+    *,
+    executor_session_key: Optional[str] = None,
+    executor_session_id: Optional[str] = None,
+) -> list[dict[str, Any]]:
+    rows = list_sessions_from_store(store_path)
+    rows = filter_sessions_by_agent(rows, agent_id)
+    rows = filter_sessions_over_threshold(rows, threshold)
+    return filter_sessions_compactable(
+        rows,
+        executor_session_key=executor_session_key or _resolve_executor_session_key(),
+        executor_session_id=executor_session_id or _resolve_executor_session_id(),
+    )
+
+
+def run_compact_for_session(
+    session_key: str,
+    *,
+    timeout_sec: int,
+    dry_run: bool,
+) -> tuple[bool, str]:
+    key = session_key.strip()
+    if not key:
+        return False, "missing sessionKey"
+    if dry_run:
+        return True, "dry-run"
+
+    params = {
+        "sessionKey": key,
+        "message": COMPACT_MESSAGE,
+        "idempotencyKey": str(uuid.uuid4()),
+        "timeoutMs": timeout_sec * 1000,
+    }
+    # CLI --timeout 为毫秒，略大于 params.timeoutMs 以等待 gateway 收尾。
+    cli_timeout_ms = (timeout_sec + 15) * 1000
+    cmd = [
+        "openclaw",
+        "gateway",
+        "call",
+        "chat.send",
+        "--params",
+        json.dumps(params, ensure_ascii=False),
+        "--expect-final",
+        "--timeout",
+        str(cli_timeout_ms),
+    ]
+    try:
+        result = subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+            timeout=(timeout_sec + 30),
+            check=False,
+        )
+    except FileNotFoundError:
+        return False, "openclaw 命令未找到"
+    except subprocess.TimeoutExpired:
+        return False, f"超时（>{timeout_sec}s）"
+
+    if result.returncode != 0:
+        detail = (result.stderr or result.stdout or "").strip()
+        return False, detail or f"exit {result.returncode}"
+    return True, "ok"
+
+
+def poll_and_compact(
+    *,
+    store_path: Path,
+    agent_id: str,
+    threshold: int,
+    dry_run: bool,
+    timeout_sec: int,
+) -> dict[str, Any]:
+    targets = find_compact_targets(store_path, agent_id, threshold)
+    results: list[dict[str, Any]] = []
+    ok_count = 0
+    fail_count = 0
+
+    for row in targets:
+        key = row.get("key")
+        session_id = row.get("sessionId")
+        total = row.get("totalTokens")
+
+        success, detail = run_compact_for_session(
+            str(key) if key else "",
+            timeout_sec=timeout_sec,
+            dry_run=dry_run,
+        )
+        if success:
+            ok_count += 1
+            status = "dry-run" if dry_run else "compacted"
+        else:
+            fail_count += 1
+            status = "failed"
+        results.append(
+            {
+                "key": key,
+                "sessionId": session_id,
+                "totalTokens": total,
+                "statusRunning": False,
+                "status": status,
+                "detail": detail,
+            }
+        )
+
+    return {
+        "agentId": agent_id,
+        "storePath": str(store_path),
+        "threshold": threshold,
+        "dryRun": dry_run,
+        "targetCount": len(targets),
+        "okCount": ok_count,
+        "failCount": fail_count,
+        "results": results,
+    }
+
+
+def main() -> None:
+    p = argparse.ArgumentParser(
+        description=(
+            "对 totalTokens 超过阈值、非 running、且非 Heartbeat/执行器会话的条目执行 /compact"
+        )
+    )
+    p.add_argument(
+        "--store",
+        type=Path,
+        default=None,
+        help="sessions.json 路径（默认 /home/node/.openclaw/agents/<agent>/sessions/sessions.json）",
+    )
+    p.add_argument(
+        "--agent-id",
+        type=str,
+        required=True,
+        help="当前 openclaw Agent ID（必填，由 Heartbeat 等调用方传入）",
+    )
+    p.add_argument(
+        "--threshold",
+        type=int,
+        default=DEFAULT_TOKEN_THRESHOLD,
+        help=f"totalTokens 阈值，严格大于该值才处理（默认 {DEFAULT_TOKEN_THRESHOLD}）",
+    )
+    p.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="只列出将压缩的会话（已排除 running），不调用 gateway chat.send",
+    )
+    p.add_argument(
+        "--timeout",
+        type=int,
+        default=DEFAULT_AGENT_TIMEOUT_SEC,
+        help=f"单次 chat.send /compact 超时秒数（默认 {DEFAULT_AGENT_TIMEOUT_SEC}）",
+    )
+    p.add_argument(
+        "--json",
+        action="store_true",
+        help="以 JSON 输出汇总（便于日志/监控）",
+    )
+    args = p.parse_args()
+
+    agent_id = args.agent_id.strip()
+    if not agent_id:
+        print("错误：--agent-id 不能为空", file=sys.stderr)
+        sys.exit(1)
+    store_path = resolve_sessions_store_path(agent_id, args.store)
+
+    if not store_path.is_file():
+        print(f"错误：找不到 session store: {store_path}", file=sys.stderr)
+        sys.exit(1)
+
+    try:
+        summary = poll_and_compact(
+            store_path=store_path,
+            agent_id=agent_id,
+            threshold=args.threshold,
+            dry_run=args.dry_run,
+            timeout_sec=max(30, args.timeout),
+        )
+    except json.JSONDecodeError as e:
+        print(f"错误：JSON 解析失败: {e}", file=sys.stderr)
+        sys.exit(1)
+    except ValueError as e:
+        print(f"错误：{e}", file=sys.stderr)
+        sys.exit(1)
+
+    if args.json:
+        print(json.dumps(summary, ensure_ascii=False, indent=2))
+    else:
+        print(
+            f"agent={summary['agentId']} store={summary['storePath']} "
+            f"threshold>{summary['threshold']} targets={summary['targetCount']} "
+            f"ok={summary['okCount']} failed={summary['failCount']}"
+        )
+        for item in summary["results"]:
+            print(
+                f"  [{item['status']}] {item.get('key')} "
+                f"tokens={item.get('totalTokens')} "
+                f"sessionId={item.get('sessionId')} "
+                f"{item.get('detail', '')}"
+            )
+
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/package.json

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

package/skills/agent-install/src/SKILL.md

@@ -167,6 +167,8 @@ uv run {baseDir}/scripts/update_openclaw.py \
 
 **自动生成图片描述**：Agent 包 `.config.json` 顶层可选 **`auto_generate_image_description`**（布尔）；不写或与 `true` 为开启，`false` 为关闭。与 **`update_openclaw.py`** 一并生效；具体写入 **`openclaw.json`** 的规则以实现为准，脚本标准输出中含 **`auto_generate_image_description`** 字段便于核对。
 
+**Heartbeat（可选，默认不配置）**：`.config.json` **可以不写** `heartbeat`。此时 `update_openclaw.py` **不会**向 `openclaw.json` 写入或合并 `heartbeat` 字段（沿用该 agent 在 openclaw 中的已有配置，新装则无 heartbeat）。仅当显式提供带有效 **`every`** 的 `heartbeat` 对象时才会合并，例如 `every: "2h"`、`target: "none"`、`lightContext: true`。脚本输出含 `heartbeat_configured` / `heartbeat` 便于核对。
+
 `NOT_INSTALLED` 无备份，直接 2）。`UPDATABLE` / `SAME_VERSION_REINSTALL` 须已完成 1）。
 
 **输入模版（仅要备份时）**

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

@@ -222,6 +222,22 @@ def normalize_llm_primary(llm: Any) -> str | None:
     return f"sophnet/{stripped}"
 
 
+def normalize_heartbeat_for_openclaw(agent_def: dict[str, Any]) -> dict[str, Any] | None:
+    """
+    仅当 .config.json 显式配置 heartbeat 且包含有效 every 时返回配置块。
+    未配置、空对象、或缺少 every 时返回 None（install 不写入 openclaw.json 的 heartbeat）。
+    """
+    raw = agent_def.get("heartbeat")
+    if raw is None:
+        return None
+    if not isinstance(raw, dict) or not raw:
+        return None
+    every = raw.get("every")
+    if not isinstance(every, str) or not every.strip():
+        return None
+    return raw
+
+
 def build_agent_entry(
     agent_def: dict[str, Any],
     *,
@@ -281,6 +297,10 @@ def build_agent_entry(
     if install.get("subagents"):
         entry["subagents"] = install["subagents"]
 
+    heartbeat = normalize_heartbeat_for_openclaw(agent_def)
+    if heartbeat is not None:
+        entry["heartbeat"] = heartbeat
+
     return entry
 
 

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

@@ -16,6 +16,7 @@ from common import (
     find_bot_api_accounts_by_agent_id,
     find_agent_by_workspace,
     is_auto_generate_image_description_enabled,
+    normalize_heartbeat_for_openclaw,
     load_agent_definition,
     load_openclaw_config,
     resolve_existing_agent_entry,
@@ -147,6 +148,8 @@ def update_openclaw(
         },
     )
 
+    heartbeat_cfg = normalize_heartbeat_for_openclaw(agent_def)
+
     return {
         "agent_id": agent_id,
         "openclaw_id": target_agent_id,
@@ -159,6 +162,8 @@ def update_openclaw(
         "version": agent_def["version"],
         "install_state": str(state_path),
         "auto_generate_image_description": auto_img_desc,
+        "heartbeat_configured": heartbeat_cfg is not None,
+        "heartbeat": heartbeat_cfg,
     }
 
 

package/skills/image-classify/skill.json

@@ -1,6 +1,6 @@
 {
   "name": "image-classify",
-  "version": "1.0.3",
+  "version": "1.0.4",
   "types": [
     "store"
   ],
@@ -8,12 +8,19 @@
   "description": "通过人脸识别对照片进行分类、搜索和管理",
   "changelog": [
     {
-      "version": "1.0.3",
-      "date": "2026-04-15",
+      "version": "1.0.4",
+      "date": "2026-05-18",
       "changes": [
-        "照片分类器添加对自动发送虾友的支持"
+        "人脸检测的阈值从0.7降低到0.5"
       ]
     },
+    {
+      "changes": [
+        "照片分类器添加对自动发送虾友的支持"
+      ],
+      "date": "2026-04-15",
+      "version": "1.0.3"
+    },
     {
       "changes": [
         "配置文件读写统一使用 UTF-8 编码（open 显式指定 encoding）"
@@ -38,5 +45,5 @@
     }
   ],
   "createdAt": "2026-04-10",
-  "updatedAt": "2026-04-15"
+  "updatedAt": "2026-05-18"
 }

package/skills/image-classify/src/SKILL.md

@@ -363,6 +363,6 @@ uv run {baseDir}/scripts/face_search.py -c {baseDir}/references/config.json uplo
 - `pack` 与 `copy` 均依赖 `config.json` 中保存的搜索结果（`search_result` 或 `quick_search_result` 等），须先执行 `search`、`classify` 或 `quick-search`。默认流程只需 **`pack`**；`copy` 为可选，由用户另行提出时再执行。
 - **`classify`** 会向 `friendId` 发**分类结果摘要**；**`pack`** 会向 `friendId` 发**打包下载链接**（两次私信、用途不同）；若只需其一，可后续再改脚本或配置（当前实现为两者都发）。
 - `pack` 的压缩文件存放在系统临时目录中，上传完成后可忽略清理。上传超时默认 120 秒，文件特别大时可通过 `--timeout` 增大。
-- `config.json` 中的 `query_threshold`（默认 0.7）控制人脸检测置信度阈值，`search_similarity_threshold`（默认 0.3）控制搜索匹配的最低相似度。
+- `config.json` 中的 `query_threshold`（默认 0.5）控制人脸检测置信度阈值，`search_similarity_threshold`（默认 0.3）控制搜索匹配的最低相似度。
 - `{baseDir}` 指本 skill 根目录（如 `skills/image-classify`），调用时替换为实际绝对路径。
 - `friendId`（虾友号）与可选 `friendLabel` 写在用户条目下；**注册时**通过 `add ... --friend-id` / `--friend-label` 写入。后续若需修改可编辑 `config.json`（本 skill 未单独提供改绑子命令）。旧键名仍兼容读取。

package/skills/image-classify/src/references/config.json

@@ -1,4 +1,4 @@
 {
-    "query_threshold": 0.7,
+    "query_threshold": 0.5,
     "search_similarity_threshold": 0.3
 }

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

@@ -0,0 +1,55 @@
+{
+  "name": "online-bug-report",
+  "version": "1.0.5",
+  "types": [
+    "store"
+  ],
+  "displayName": "在线提Bug",
+  "description": "用户说「在线提交bug」时收集 Bug 并经由虾友 DM 发送工单（含 session 附件）",
+  "changelog": [
+    {
+      "changes": [
+        "凭证移至 src/secrets/bug-report.json，与 npm 打包仅含 src/ 对齐"
+      ],
+      "date": "2026-05-19",
+      "version": "1.0.5"
+    },
+    {
+      "changes": [
+        "凭证仅使用 secrets/bug-report.json，移除 .secrets 候选路径"
+      ],
+      "date": "2026-05-19",
+      "version": "1.0.4"
+    },
+    {
+      "changes": [
+        "内置 secrets/bug-report.json 随 skill 下发，下载即用"
+      ],
+      "date": "2026-05-19",
+      "version": "1.0.3"
+    },
+    {
+      "changes": [
+        "凭证改为 .secrets/bug-report.json；明确唯一触发词；移除仓库内嵌凭证"
+      ],
+      "date": "2026-05-19",
+      "version": "1.0.2"
+    },
+    {
+      "changes": [
+        "工单环境区增加「模型」字段；支持 --model 与 default_model 配置"
+      ],
+      "date": "2026-05-18",
+      "version": "1.0.1"
+    },
+    {
+      "changes": [
+        "初次提交：精简工单模板、preview/send、虾友 DM 外推"
+      ],
+      "date": "2026-05-18",
+      "version": "1.0.0"
+    }
+  ],
+  "createdAt": "2026-05-18",
+  "updatedAt": "2026-05-19"
+}