@konglx/rotom 2.21.0

package/bin/mesh-master.sh

@@ -0,0 +1,439 @@
+#!/usr/bin/env bash
+#
+# Digital Employee Mesh — Master 管理脚本
+#
+# 用法: mesh-master <command> [options]
+# 命令: start | stop | restart | status | install-service | uninstall-service
+# 选项: --port/-p <port>  --host <addr>  --data/-d <dir>  --daemon
+#
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+SERVER_JS="$SCRIPT_DIR/dist/master/server.js"
+OPENCLAW_DIR="$HOME/.openclaw"
+PID_FILE="$OPENCLAW_DIR/mesh-master.pid"
+SVC="com.openclaw.mesh-master"
+
+PORT="${MESH_MASTER_PORT:-28800}"
+HOST="${MESH_MASTER_HOST:-0.0.0.0}"
+DATA="${MESH_MASTER_DATA:-$HOME/.rotom}"
+DAEMON=false
+DEV=false
+
+# ── 工具函数 ──────────────────────────────────────────────────────────────────
+
+detect_os() { [[ "$OSTYPE" == darwin* ]] && echo macos || echo linux; }
+
+# 查找占用端口的 PID（lsof 在 macOS SIP 下可能看不到 launchd 子进程）
+find_port_pid() {
+  if command -v lsof &>/dev/null; then
+    lsof -ti :"$PORT" -sTCP:LISTEN 2>/dev/null || true
+  elif command -v ss &>/dev/null; then
+    ss -tlnp "sport = :$PORT" 2>/dev/null | grep -oP 'pid=\K[0-9]+' | head -1 || true
+  elif command -v fuser &>/dev/null; then
+    fuser "$PORT/tcp" 2>/dev/null | tr -d ' ' || true
+  else
+    echo ""
+  fi
+}
+
+# 通过 launchctl 获取服务 PID（macOS）
+find_service_pid() {
+  if [ "$(detect_os)" = "macos" ]; then
+    launchctl list "$SVC" 2>/dev/null | awk '{print $1}' | grep -E '^[0-9]+$' || true
+  fi
+}
+
+# 检测端口是否被占用：lsof → TCP 探测 → curl health
+is_port_in_use() {
+  # 1. lsof（快，但 macOS SIP 下可能看不到 launchd 子进程）
+  [ -n "$(find_port_pid)" ] && return 0
+  # 2. TCP 连接探测（不受 SIP 限制）
+  python3 -c "
+import socket, sys
+s = socket.socket()
+s.settimeout(1)
+try:
+    s.connect(('127.0.0.1', $PORT))
+    s.close()
+except:
+    sys.exit(1)
+" 2>/dev/null && return 0
+  # 3. curl health 端点
+  curl -sf --connect-timeout 2 "http://127.0.0.1:$PORT/health" >/dev/null 2>&1 && return 0
+  return 1
+}
+
+# 轮询等待端口就绪（默认最多 10 秒）
+wait_for_port() {
+  local max_wait=${1:-10} i=0
+  while [ $i -lt $max_wait ]; do
+    is_port_in_use && return 0
+    sleep 1
+    i=$((i+1))
+  done
+  return 1
+}
+
+# 轮询等待端口释放（默认最多 5 秒）
+wait_for_port_free() {
+  local max_wait=${1:-5} i=0
+  while [ $i -lt $max_wait ]; do
+    is_port_in_use || return 0
+    sleep 1
+    i=$((i+1))
+  done
+  return 1
+}
+
+# 检查系统服务是否已安装（plist/service 文件存在）
+is_service_installed() {
+  if [ "$(detect_os)" = "macos" ]; then
+    [ -f "$HOME/Library/LaunchAgents/$SVC.plist" ]
+  else
+    [ -f "$HOME/.config/systemd/user/mesh-master.service" ]
+  fi
+}
+
+# 停止系统服务（不删除 plist 文件）
+# macOS: bootout 替代废弃的 stop+unload，彻底停止并阻止 KeepAlive 重启
+stop_service() {
+  if [ "$(detect_os)" = "macos" ]; then
+    local domain="gui/$(id -u)"
+    launchctl bootout "$domain/$SVC" 2>/dev/null || true
+  else
+    systemctl --user stop mesh-master 2>/dev/null || true
+  fi
+}
+
+# 启动系统服务
+# macOS: bootstrap + kickstart 替代废弃的 load，确保进程实际启动
+start_service() {
+  if [ "$(detect_os)" = "macos" ]; then
+    local domain="gui/$(id -u)"
+    local plist="$HOME/Library/LaunchAgents/$SVC.plist"
+    # bootstrap 注册服务（如果已注册则忽略错误）
+    launchctl bootstrap "$domain" "$plist" 2>/dev/null || true
+    # kickstart -k 强制（重新）启动，解决 bootstrap 不触发 RunAtLoad 的已知问题
+    launchctl kickstart -k "$domain/$SVC" 2>/dev/null || true
+  else
+    systemctl --user start mesh-master 2>/dev/null || true
+  fi
+}
+
+fix_path() {
+  [ -d "/opt/homebrew/bin" ] && export PATH="/opt/homebrew/bin:$PATH"
+  [ -d "/usr/local/bin" ] && export PATH="/usr/local/bin:$PATH"
+  [ -d "$HOME/.nodejs/bin" ] && export PATH="$HOME/.nodejs/bin:$PATH"
+  [ -s "$HOME/.nvm/nvm.sh" ] && { export NVM_DIR="$HOME/.nvm"; . "$NVM_DIR/nvm.sh"; }
+  [ -d "$HOME/.fnm" ] && { export PATH="$HOME/.fnm:$PATH"; eval "$(fnm env 2>/dev/null)" || true; }
+  [ -d "$HOME/.volta" ] && export PATH="$HOME/.volta/bin:$PATH"
+}
+
+detect_pkg() {
+  command -v pnpm &>/dev/null && echo pnpm && return
+  command -v npm &>/dev/null && echo npm && return
+  command -v yarn &>/dev/null && echo yarn && return
+  echo ""
+}
+
+ensure_built() {
+  local need=false
+  [ ! -f "$SERVER_JS" ] && need=true
+  # 选择哪些源文件参与“是否需要重建”的判断
+  # dev: 只看 src/ 下的后端 .ts；prod: 同时看 packages/ 下的前端
+  local watch_dirs="$SCRIPT_DIR/src"
+  [ "$DEV" = false ] && watch_dirs="$watch_dirs $SCRIPT_DIR/packages"
+  [ "$need" = false ] && {
+    local newer
+    # shellcheck disable=SC2086
+    newer=$(find $watch_dirs \( -name '*.ts' -o -name '*.tsx' -o -name '*.html' -o -name '*.css' \) -newer "$SERVER_JS" -print -quit 2>/dev/null)
+    [ -n "$newer" ] && need=true
+  }
+  if [ "$need" = true ]; then
+    local target="build:master"
+    [ "$DEV" = true ] && target="build"
+    echo "[mesh-master] 构建中 ($target)..."
+    local pkg; pkg=$(detect_pkg)
+    case "$pkg" in
+      pnpm) (cd "$SCRIPT_DIR" && pnpm "$target") ;;
+      npm)  (cd "$SCRIPT_DIR" && npm run "$target") ;;
+      yarn) (cd "$SCRIPT_DIR" && yarn "$target") ;;
+      *)    echo "[mesh-master] 未找到包管理器"; return 1 ;;
+    esac
+  fi
+}
+
+# 杀掉进程（PID 文件 → launchctl 查询 → 端口查找）
+kill_process() {
+  local pid
+  # 1. PID 文件
+  pid=$(cat "$PID_FILE" 2>/dev/null || true)
+  # 2. launchctl list（macOS，SIP 下 lsof 看不到 launchd 子进程）
+  if [ -z "$pid" ] || ! kill -0 "$pid" 2>/dev/null; then
+    pid=$(find_service_pid)
+  fi
+  # 3. 端口查找
+  if [ -z "$pid" ] || ! kill -0 "$pid" 2>/dev/null; then
+    pid=$(find_port_pid)
+  fi
+  if [ -z "$pid" ]; then
+    return 1
+  fi
+  echo "[mesh-master] 停止中 (PID $pid)..."
+  kill "$pid" 2>/dev/null || true
+  local i=0; while kill -0 "$pid" 2>/dev/null && [ $i -lt 50 ]; do sleep 0.1; i=$((i+1)); done
+  kill -0 "$pid" 2>/dev/null && kill -9 "$pid" 2>/dev/null || true
+  rm -f "$PID_FILE"
+  return 0
+}
+
+# ── 命令 ──────────────────────────────────────────────────────────────────────
+
+do_run() {
+  fix_path || true
+  ensure_built || true
+  mkdir -p "$OPENCLAW_DIR" "$DATA"
+  exec node "$SERVER_JS" --port "$PORT" --host "$HOST" --data "$DATA"
+}
+
+do_start() {
+  if is_port_in_use; then
+    echo "[mesh-master] 端口 $PORT 已被占用"; return 1
+  fi
+  ensure_built
+  mkdir -p "$OPENCLAW_DIR" "$DATA"
+  if [ "$DAEMON" = true ]; then
+    nohup node "$SERVER_JS" --port "$PORT" --host "$HOST" --data "$DATA" >/dev/null 2>&1 &
+    echo "$!" > "$PID_FILE"
+    sleep 1
+    if kill -0 "$!" 2>/dev/null; then
+      echo "[mesh-master] 启动成功 (PID $!, port $PORT)"
+    else
+      rm -f "$PID_FILE"; echo "[mesh-master] 启动失败，查看 ~/.rotom/logs/ 下的日志文件"; return 1
+    fi
+  else
+    echo "$$" > "$PID_FILE"
+    trap 'rm -f "$PID_FILE"' EXIT INT TERM
+    exec node "$SERVER_JS" --port "$PORT" --host "$HOST" --data "$DATA"
+  fi
+}
+
+do_stop() {
+  local was_running=false
+
+  # 如果有系统服务，先 bootout（彻底停止 + 阻止 KeepAlive 重启）
+  if is_service_installed; then
+    echo "[mesh-master] 检测到系统服务，停止服务..."
+    stop_service
+    was_running=true
+    sleep 1
+  fi
+
+  # 再杀残留进程（手动启动的、或 bootout 未杀干净的）
+  if kill_process 2>/dev/null; then
+    was_running=true
+  fi
+
+  if [ "$was_running" = true ]; then
+    wait_for_port_free 5 || true
+    echo "[mesh-master] 已停止"
+  elif is_port_in_use; then
+    echo "[mesh-master] 警告: 端口 $PORT 被未知进程占用"
+    return 1
+  else
+    echo "[mesh-master] 未在运行"
+  fi
+}
+
+do_restart() {
+  do_stop
+  sleep 1
+  # 如果有系统服务，用系统服务启动
+  if is_service_installed; then
+    echo "[mesh-master] 通过系统服务启动..."
+    start_service
+    if wait_for_port 10; then
+      echo "[mesh-master] 重启成功"
+    else
+      echo "[mesh-master] 重启失败，查看 ~/.rotom/logs/ 下的日志文件"; return 1
+    fi
+  else
+    do_start
+  fi
+}
+
+do_status() {
+  if is_port_in_use; then
+    echo "[mesh-master] 运行中 (port $PORT)"
+    is_service_installed && echo "  模式: 系统服务" || echo "  模式: 手动"
+    curl -sf "http://127.0.0.1:$PORT/health" 2>/dev/null | python3 -m json.tool 2>/dev/null || true
+  else
+    echo "[mesh-master] 未运行"; return 1
+  fi
+}
+
+# ── 系统服务 ──────────────────────────────────────────────────────────────────
+
+do_install_service() {
+  # 先停掉现有进程和旧服务
+  if is_service_installed || is_port_in_use; then
+    echo "[mesh-master] 停止现有服务/进程..."
+    do_stop
+    sleep 1
+  fi
+
+  ensure_built
+  mkdir -p "$OPENCLAW_DIR" "$DATA"
+  local self="$SCRIPT_DIR/bin/mesh-master.sh"
+
+  if [ "$(detect_os)" = "macos" ]; then
+    local plist="$HOME/Library/LaunchAgents/$SVC.plist"
+    local domain="gui/$(id -u)"
+    mkdir -p "$HOME/Library/LaunchAgents"
+
+    local data_args=""
+    if [ -n "$DATA" ]; then
+      data_args="        <string>--data</string><string>${DATA}</string>"
+    fi
+
+    cat > "$plist" << PLIST
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key><string>${SVC}</string>
+    <key>ProgramArguments</key>
+    <array>
+        <string>${self}</string><string>_run</string>
+        <string>--port</string><string>${PORT}</string>
+        <string>--host</string><string>${HOST}</string>
+${data_args}
+    </array>
+    <key>EnvironmentVariables</key>
+    <dict>
+        <key>PATH</key><string>${PATH}</string>
+        <key>HOME</key><string>${HOME}</string>
+        <key>LANG</key><string>${LANG:-en_US.UTF-8}</string>
+    </dict>
+    <key>RunAtLoad</key><true/>
+    <key>KeepAlive</key><true/>
+    <key>StandardOutPath</key><string>/dev/null</string>
+    <key>StandardErrorPath</key><string>/dev/null</string>
+    <key>WorkingDirectory</key><string>${SCRIPT_DIR}</string>
+</dict>
+</plist>
+PLIST
+    # 现代 API: bootstrap 注册 + kickstart 强制启动
+    if ! launchctl bootstrap "$domain" "$plist" 2>&1; then
+      echo "[mesh-master] bootstrap 失败"; return 1
+    fi
+    launchctl kickstart -k "$domain/$SVC" 2>/dev/null || true
+  else
+    local svc_file="$HOME/.config/systemd/user/mesh-master.service"
+    mkdir -p "$(dirname "$svc_file")"
+
+    local data_flag=""
+    [ -n "$DATA" ] && data_flag=" --data ${DATA}"
+
+    cat > "$svc_file" << SERVICE
+[Unit]
+Description=Digital Employee Mesh Master
+After=network.target
+[Service]
+Type=simple
+ExecStart=${self} _run --port ${PORT} --host ${HOST}${data_flag}
+Restart=always
+RestartSec=5
+Environment=PATH=${PATH}
+Environment=HOME=${HOME}
+Environment=LANG=${LANG:-en_US.UTF-8}
+StandardOutput=null
+StandardError=null
+WorkingDirectory=${SCRIPT_DIR}
+[Install]
+WantedBy=default.target
+SERVICE
+    systemctl --user daemon-reload
+    systemctl --user enable mesh-master
+    systemctl --user start mesh-master
+  fi
+
+  if wait_for_port 10; then
+    echo "[mesh-master] 系统服务已安装并启动 ✅"
+    echo "  升级: git pull → $0 restart"
+    echo "  卸载: $0 uninstall-service"
+    echo "  日志:   JS logger → ~/.rotom/logs/mesh-master-YYYY-MM-DD.log"
+  else
+    echo "[mesh-master] 启动失败，查看 ~/.rotom/logs/ 下的日志文件"; return 1
+  fi
+}
+
+do_uninstall_service() {
+  if [ "$(detect_os)" = "macos" ]; then
+    local domain="gui/$(id -u)"
+    # bootout 停止并注销服务
+    launchctl bootout "$domain/$SVC" 2>/dev/null || true
+    rm -f "$HOME/Library/LaunchAgents/$SVC.plist"
+  else
+    systemctl --user stop mesh-master 2>/dev/null || true
+    systemctl --user disable mesh-master 2>/dev/null || true
+    rm -f "$HOME/.config/systemd/user/mesh-master.service"
+    systemctl --user daemon-reload
+  fi
+  echo "[mesh-master] 系统服务已卸载 ✅"
+}
+
+# ── 帮助 ──────────────────────────────────────────────────────────────────────
+
+do_help() {
+  cat <<EOF
+Digital Employee Mesh — Master 管理脚本
+
+用法: mesh-master <command> [options]
+
+命令:
+  start              启动 (默认前台, --daemon 后台)
+  stop               停止（自动识别手动/系统服务）
+  restart            重启（自动识别手动/系统服务）
+  status             查看状态
+  install-service    安装系统服务（开机自启 + 守护进程 + 升级自动编译）
+  uninstall-service  卸载系统服务
+
+选项:
+  --port, -p <port>    端口 (默认: ${PORT})
+  --host <addr>        地址 (默认: ${HOST})
+  --data, -d <dir>     数据目录 (默认: ~/Library/Application Support/a2a-gateway/mesh-data)
+  --daemon             后台运行
+  --dev                开发模式：只编译后端，跳过 vite 前端构建
+                       前端用 \`pnpm dashboard:dev\` 单独跑（vite dev :3000）
+
+示例:
+  mesh-master start --daemon                 # 后台启动
+  mesh-master start --dev                    # 开发模式（不 build vite）
+  mesh-master install-service                # 安装为系统服务
+  mesh-master restart                        # 重启（升级后用）
+  mesh-master status                         # 查看状态
+EOF
+}
+
+# ── 入口 ──────────────────────────────────────────────────────────────────────
+
+CMD="${1:-help}"; shift 2>/dev/null || true
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --port|-p) PORT="$2"; shift 2 ;; --host) HOST="$2"; shift 2 ;;
+    --data|-d) DATA="$2"; shift 2 ;; --daemon) DAEMON=true; shift ;;
+    --dev) DEV=true; shift ;;
+    --help) do_help; exit 0 ;; *) echo "未知选项: $1"; do_help; exit 1 ;;
+  esac
+done
+
+case "$CMD" in
+  start)   do_start ;; stop) do_stop ;; restart) do_restart ;;
+  status)  do_status ;; _run) do_run ;;
+  install-service) do_install_service ;; uninstall-service) do_uninstall_service ;;
+  help|-h|--help) do_help ;; *) echo "未知命令: $CMD"; do_help; exit 1 ;;
+esac

package/bin/rotom

@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+# rotom CLI launcher.
+# Prefers the compiled JS; falls back to running the TS source through tsx
+# (so contributors don't need to rebuild on every change).
+set -e
+
+# Resolve the real path of this script, following symlinks (so global installs
+# via `ln -s ... /usr/local/bin/rotom` still locate the repo).
+SOURCE="${BASH_SOURCE[0]}"
+while [ -L "$SOURCE" ]; do
+  TARGET="$(readlink "$SOURCE")"
+  case "$TARGET" in
+    /*) SOURCE="$TARGET" ;;
+    *)  SOURCE="$(cd "$(dirname "$SOURCE")" && pwd)/$TARGET" ;;
+  esac
+done
+HERE="$(cd "$(dirname "$SOURCE")" && pwd)"
+ROOT="$(cd "$HERE/.." && pwd)"
+DIST="$ROOT/dist/cli/rotom.js"
+SRC="$ROOT/src/cli/rotom.ts"
+
+if [ -f "$DIST" ]; then
+  exec node "$DIST" "$@"
+elif [ -f "$SRC" ]; then
+  exec node --import tsx "$SRC" "$@"
+else
+  echo "rotom: cannot find dist/cli/rotom.js or src/cli/rotom.ts (looked in $ROOT)" >&2
+  exit 1
+fi

package/bin/rotom-link.sh

@@ -0,0 +1,136 @@
+#!/usr/bin/env bash
+#
+# rotom-link —— 轻量 federation link daemon 启停脚本。
+#
+# 用法: rotom-link <command> [options]
+# 命令: start | stop | restart | status | logs
+# 选项: --port/-p <port>   默认 28900
+#
+# 运行时目录: ~/.rotom/{run,logs}
+#
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+LINK_JS="$SCRIPT_DIR/dist/link/server.js"
+
+ROTOM_HOME="${ROTOM_HOME:-$HOME/.rotom}"
+RUN_DIR="$ROTOM_HOME/run"
+LOG_DIR="$ROTOM_HOME/logs"
+LINK_PID="$RUN_DIR/link.pid"
+LINK_LOG="$LOG_DIR/link.log"
+LINK_CONFIG="$ROTOM_HOME/link.json"
+
+PORT="${ROTOM_LINK_PORT:-28900}"
+
+mkdir -p "$RUN_DIR" "$LOG_DIR"
+
+is_pid_alive() {
+  local pid_file="$1"
+  [ -f "$pid_file" ] || return 1
+  local pid; pid=$(cat "$pid_file" 2>/dev/null || true)
+  [ -z "$pid" ] && return 1
+  kill -0 "$pid" 2>/dev/null
+}
+
+stop_pid_file() {
+  local pid_file="$1" label="$2"
+  if ! is_pid_alive "$pid_file"; then
+    rm -f "$pid_file"
+    return 1
+  fi
+  local pid; pid=$(cat "$pid_file")
+  echo "[rotom-link] 停止 $label (PID $pid)..."
+  kill "$pid" 2>/dev/null || true
+  local i=0
+  while kill -0 "$pid" 2>/dev/null && [ $i -lt 50 ]; do
+    sleep 0.1; i=$((i+1))
+  done
+  kill -0 "$pid" 2>/dev/null && kill -9 "$pid" 2>/dev/null || true
+  rm -f "$pid_file"
+  return 0
+}
+
+wait_link_ready() {
+  local max_wait=${1:-10} i=0
+  while [ $i -lt $max_wait ]; do
+    if curl -sf --connect-timeout 1 "http://127.0.0.1:$PORT/health" >/dev/null 2>&1; then
+      return 0
+    fi
+    sleep 1; i=$((i+1))
+  done
+  return 1
+}
+
+do_start() {
+  if is_pid_alive "$LINK_PID"; then
+    echo "[rotom-link] 已在运行 (PID $(cat "$LINK_PID"))"
+    return 0
+  fi
+  if [ ! -f "$LINK_JS" ]; then
+    echo "[rotom-link] ❌ $LINK_JS 不存在,请先 \`pnpm build\`"
+    return 1
+  fi
+  if [ ! -f "$LINK_CONFIG" ]; then
+    echo "[rotom-link] ❌ $LINK_CONFIG 不存在,请先 \`rotom link join <coordEndpoint> --hostname <name>\`"
+    return 1
+  fi
+  # 端口预检
+  if command -v lsof >/dev/null 2>&1; then
+    local occupier
+    occupier=$(lsof -nP -iTCP:"$PORT" -sTCP:LISTEN -t 2>/dev/null | head -n1 || true)
+    if [ -n "$occupier" ]; then
+      local occupier_cmd
+      occupier_cmd=$(ps -p "$occupier" -o command= 2>/dev/null | head -c 120 || echo "(unknown)")
+      echo "[rotom-link] ❌ 端口 $PORT 已被占用 (PID $occupier: $occupier_cmd)"
+      return 1
+    fi
+  fi
+  echo "[rotom-link] 启动 link daemon (port=$PORT)..."
+  nohup node "$LINK_JS" --port "$PORT" >> "$LINK_LOG" 2>&1 &
+  echo "$!" > "$LINK_PID"
+  if ! wait_link_ready 10; then
+    echo "[rotom-link] ❌ 启动失败,查看 $LINK_LOG"
+    stop_pid_file "$LINK_PID" link || true
+    return 1
+  fi
+  echo "[rotom-link] ✅ 就绪 (PID $(cat "$LINK_PID"), http://127.0.0.1:$PORT)"
+}
+
+do_stop() {
+  stop_pid_file "$LINK_PID" link || echo "[rotom-link] 未在运行"
+}
+
+do_status() {
+  if is_pid_alive "$LINK_PID"; then
+    local pid; pid=$(cat "$LINK_PID")
+    echo "[rotom-link] running (PID $pid, port=$PORT)"
+    if curl -sf --connect-timeout 1 "http://127.0.0.1:$PORT/health" >/dev/null 2>&1; then
+      curl -s "http://127.0.0.1:$PORT/health"
+      echo
+    fi
+  else
+    echo "[rotom-link] stopped"
+  fi
+}
+
+do_logs() {
+  if [ -f "$LINK_LOG" ]; then
+    tail -n 200 "$LINK_LOG"
+  else
+    echo "[rotom-link] no log at $LINK_LOG"
+  fi
+}
+
+cmd="${1:-}"; shift || true
+case "$cmd" in
+  start)   do_start ;;
+  stop)    do_stop ;;
+  restart) do_stop; do_start ;;
+  status)  do_status ;;
+  logs)    do_logs ;;
+  *)
+    echo "usage: rotom-link <start|stop|restart|status|logs> [--port N]"
+    exit 1
+    ;;
+esac

package/bin/rotom-send-with-status

@@ -0,0 +1,57 @@
+#!/bin/bash
+# rotom-send-with-status - 发送消息并解释投递状态
+#
+# 用法：rotom-send-with-status <groupId> <target> <message>
+# 示例：rotom-send-with-status cda34ffc-c8e9-428b-b9da-2bec7c6039d1 小寿 "@小寿 帮我看看这个问题"
+
+GROUP_ID=$1
+TARGET=$2
+MESSAGE=$3
+
+if [ -z "$GROUP_ID" ] || [ -z "$TARGET" ] || [ -z "$MESSAGE" ]; then
+  echo "用法: rotom-send-with-status <groupId> <target> <message>" >&2
+  exit 1
+fi
+
+# 调用 rotom 并捕获输出
+RESULT=$(rotom group send "$GROUP_ID" "$TARGET" "$MESSAGE" 2>&1)
+EXIT_CODE=$?
+
+if [ $EXIT_CODE -ne 0 ]; then
+  echo "❌ 命令执行失败: $RESULT" >&2
+  exit $EXIT_CODE
+fi
+
+# 检查是否有 jq 命令
+if ! command -v jq >/dev/null 2>&1; then
+  # 没有 jq，直接返回原始 JSON
+  echo "$RESULT"
+  exit 0
+fi
+
+# 解析 JSON
+DELIVERED=$(echo "$RESULT" | jq -r '.delivered')
+QUEUED=$(echo "$RESULT" | jq -r '.queued')
+ERROR=$(echo "$RESULT" | jq -r '.error // empty')
+REQUEST_ID=$(echo "$RESULT" | jq -r '.requestId // empty')
+
+# 生成人类可读的输出
+echo "$RESULT"  # 原始 JSON（供程序处理）
+echo ""  # 空行分隔
+
+# 解释性输出（供人类阅读）
+echo "📤 → $TARGET: $MESSAGE"
+
+if [ "$DELIVERED" = "true" ]; then
+  echo "✅ 消息已实时送达（对方在线，会立即处理）"
+elif [ "$QUEUED" = "true" ]; then
+  echo "⏳ $TARGET 当前离线，消息已缓存，上线后会收到"
+else
+  if [ -n "$ERROR" ]; then
+    echo "❌ 消息投递失败：$ERROR"
+  else
+    echo "❓ 未知投递状态（请联系管理员检查）"
+  fi
+fi
+
+exit 0