dlinkclaw-openclaw 1.0.0

package/ext_capabilities/workrelay-speak-qwen/manifest.json

@@ -0,0 +1,63 @@
+{
+  "name": "workrelay-speak-qwen",
+  "displayName": "语音合成（千问 Qwen3-TTS）",
+  "description": "Agent 语音回复：Docker 部署 Voicebox（Qwen3-TTS CustomVoice 引擎），9 种预设音色，中英日韩多语种，音质自然、断句好，适合视频配音。独立容器（端口 17602）；与 Kokoro / LuxTTS 互斥，启用本能力会自动停止其它 TTS。首次安装需下载模型约 4.6GB",
+  "requirements": [
+    {
+      "id": "os",
+      "label": "操作系统",
+      "expect": "Linux",
+      "check": "uname -s | grep -qi linux",
+      "hint": "TTS 依赖 Docker，仅支持 Linux（Windows 请用 WSL2）"
+    },
+    {
+      "id": "docker",
+      "label": "Docker 已安装",
+      "expect": "已安装 docker",
+      "check": "command -v docker >/dev/null 2>&1",
+      "hint": "未找到 Docker，请先安装：sudo apt install docker.io docker-compose-v2"
+    },
+    {
+      "id": "docker_access",
+      "label": "Docker 可访问（权限）",
+      "expect": "docker info 可正常执行",
+      "check": "docker info >/dev/null 2>&1 || (id -nG | grep -qw docker && sg docker -c 'docker info' >/dev/null 2>&1) || sudo -n docker info >/dev/null 2>&1",
+      "hint": "Docker 无权限。一次性解决（需 sudo 密码一次）：① sudo systemctl start docker ② sudo usermod -aG docker $USER ③ openclaw gateway restart 后重试"
+    },
+    {
+      "id": "memory",
+      "label": "内存 ≥ 6GB（建议 8GB+）",
+      "expect": "≥ 6GB 可用",
+      "check": "[ $(LANG=C free -m | awk '/^Mem:/{print $2}') -ge 6144 ]",
+      "hint": "当前内存不足，Qwen3-TTS 1.7B 至少需要 6GB 内存，建议 8GB 以上"
+    },
+    {
+      "id": "disk",
+      "label": "磁盘 ≥ 8GB",
+      "expect": "≥ 8GB 可用（模型 4.6GB + 运行缓存）",
+      "check": "[ $(df -BM \"$HOME\" | tail -1 | awk '{print $4}' | sed 's/M//') -ge 8192 ]",
+      "hint": "可用空间不足，Qwen3-TTS 模型约需 4.6GB，建议预留 8GB"
+    },
+    {
+      "id": "registry",
+      "label": "镜像仓库可达（ghcr.io / 国内公共仓库，自动回退）",
+      "expect": "能访问阿里云镜像仓库",
+      "check": "timeout 4 docker manifest inspect ghcr.io/rockychen2016/dlinkclaw-tts:qwen-20260914 >/dev/null 2>&1 || timeout 4 docker manifest inspect registry.cn-hangzhou.aliyuncs.com/shiduo/dlinkclaw-tts:qwen-20260914 >/dev/null 2>&1",
+      "hint": "镜像源不可达。国际源: ghcr.io（GitHub Container Registry，公开免登录）；国内源: registry.cn-hangzhou.aliyuncs.com（待发布）。安装时自动按区域优先并回退"
+    },
+    {
+      "id": "model_source",
+      "label": "模型源可达（HF 国内镜像）",
+      "expect": "能访问 hf-mirror.com",
+      "check": "timeout 4 curl -sI https://hf-mirror.com >/dev/null 2>&1 || timeout 4 curl -sI https://huggingface.co >/dev/null 2>&1",
+      "hint": "无法访问模型源（国内 hf-mirror.com / 国际 huggingface.co），Qwen 模型（4.6GB）将无法下载，请检查网络"
+    },
+    {
+      "id": "gpu",
+      "label": "GPU 加速（可选）",
+      "expect": "检测到 NVIDIA GPU 时合成更快",
+      "check": "if command -v nvidia-smi >/dev/null 2>&1; then nvidia-smi -L >/dev/null 2>&1 && exit 0; fi; exit 0",
+      "hint": "未检测到 NVIDIA 独显，将使用 CPU 合成（Qwen 1.7B 约 10~60 秒/句，慢但可用）；有 NVIDIA GPU 时自动启用 CUDA 加速"
+    }
+  ]
+}

package/ext_capabilities/workrelay-speak-qwen/status.sh

@@ -0,0 +1,106 @@
+#!/bin/bash
+# WorkRelay 语音合成（千问 Qwen3-TTS）状态检查
+# 返回值: 0=已启用, 1=未安装, 2=部分安装, 3=容器存在但API未就绪
+# 2026-09-14 新增能力：独立容器 voicebox-qwen + 端口 17602 + provider tts-local-cli-qwen
+# 2026-09-14 互斥：TTS 三选一——读 openclaw.json 的 tts.provider，不是本引擎则视为"未启用"
+set -e
+
+STATUS_OK=0
+STATUS_NOT_INSTALLED=1
+STATUS_PARTIAL=2
+STATUS_DOCKER_DOWN=3
+
+VB_HOST="${WR_VOICEBOX_HOST:-127.0.0.1}"
+VB_PORT="${WR_VOICEBOX_QWEN_PORT:-17602}"
+
+export PATH="$PATH:/snap/bin:/usr/local/bin"
+if ! docker info &>/dev/null 2>&1; then
+  if sg docker -c "docker info" &>/dev/null 2>&1; then
+    docker() { sg docker -c "docker $(printf '%q ' "$@")"; }
+  elif sudo -n docker info &>/dev/null 2>&1; then
+    docker() { sudo docker "$@"; }
+  fi
+fi
+
+# 检查1: Docker
+check_docker=0
+docker info &>/dev/null 2>&1 && check_docker=1 || true
+
+# 检查2: voicebox-qwen 容器
+check_container=0
+docker ps --format '{{.Names}}' 2>/dev/null | grep -q "voicebox-qwen" && check_container=1 || true
+
+# 检查3: API
+check_api=0
+curl -s --max-time 3 "http://${VB_HOST}:${VB_PORT}/mcp" >/dev/null 2>&1 && check_api=1 || true
+
+# 检查4: TTS 桥接脚本
+check_tts_script=0
+[ -f "$HOME/.workrelay/speak-qwen/workrelay-tts.sh" ] && check_tts_script=1 || true
+
+# 检查5: 千问预设音色 profile
+check_profile=0
+[ -f "$HOME/.workrelay/speak-qwen/profile_id" ] && check_profile=1 || true
+
+# 检查6: OpenClaw TTS 配置（2026-09-14 新版顶层路径 tts.providers.*，不再读旧 messages.tts.*）
+# 2026-09-14 互斥判定：仅当 tts.provider == tts-local-cli-qwen 时才算"已启用"
+check_config=0
+check_provider=0
+OC_JSON="${OPENCLAW_HOME:-$HOME/.openclaw}/openclaw.json"
+if [ -f "$OC_JSON" ]; then
+  grep -q '"tts-local-cli-qwen"' "$OC_JSON" && check_config=1 || true
+  # 当前生效的 TTS provider（互斥判定）：取 "provider": "xxx" 中第一个（tts 段内）
+  CUR_PROVIDER=$(python3 -c '
+import json,sys
+try:
+    c=json.load(open(sys.argv[1]))
+    print((c.get("tts") or {}).get("provider",""))
+except Exception:
+    print("")
+' "$OC_JSON" 2>/dev/null)
+  [ "$CUR_PROVIDER" = "tts-local-cli-qwen" ] && check_provider=1 || true
+fi
+
+# ── 汇总状态 ──
+total=$((check_docker + check_container + check_api + check_tts_script + check_profile + check_config))
+
+case $total in
+  6)
+    # 已安装齐全：再按互斥判定是否"启用"（provider 指向本引擎）
+    if [ "$check_provider" -eq 1 ]; then
+      status="enabled";   desc="语音合成（千问 Qwen3-TTS）已启用"; exit_code=$STATUS_OK
+    else
+      status="disabled";  desc="已安装但未启用（当前语音合成为其它引擎，TTS 只能启用一个）"; exit_code=$STATUS_NOT_INSTALLED
+    fi
+    ;;
+  0) status="disabled";  desc="未安装";          exit_code=$STATUS_NOT_INSTALLED ;;
+  *)
+    if [ "$check_container" -eq 0 ] && [ "$check_docker" -eq 1 ]; then
+      status="disabled"; desc="Docker 运行中但 voicebox-qwen 未安装"; exit_code=$STATUS_NOT_INSTALLED
+    elif [ "$check_container" -eq 1 ] && [ "$check_api" -eq 0 ]; then
+      status="partial"; desc="voicebox-qwen 容器存在但 API 未就绪（可能在加载模型）"; exit_code=$STATUS_DOCKER_DOWN
+    else
+      status="partial"; desc="部分安装"; exit_code=$STATUS_PARTIAL
+    fi
+    ;;
+esac
+
+# ── 输出 JSON ──
+cat <<JSONEOF
+{
+  "status": "$status",
+  "description": "$desc",
+  "endpoint": "http://${VB_HOST}:${VB_PORT}",
+  "checks": {
+    "docker": $( [ $check_docker -eq 1 ] && echo true || echo false ),
+    "container": $( [ $check_container -eq 1 ] && echo true || echo false ),
+    "api": $( [ $check_api -eq 1 ] && echo true || echo false ),
+    "tts_script": $( [ $check_tts_script -eq 1 ] && echo true || echo false ),
+    "profile": $( [ $check_profile -eq 1 ] && echo true || echo false ),
+    "openclaw_config": $( [ $check_config -eq 1 ] && echo true || echo false ),
+    "provider_active": $( [ $check_provider -eq 1 ] && echo true || echo false )
+  }
+}
+JSONEOF
+
+exit $exit_code

package/ext_capabilities/workrelay-speak-qwen/workrelay-tts.sh

@@ -0,0 +1,98 @@
+#!/bin/bash
+# WorkRelay TTS 桥接脚本（千问 Qwen3-TTS 引擎）
+# 调用本地 Voicebox (voicebox-qwen, 端口 17602) REST API
+# 环境变量：
+#   WR_VOICEBOX_QWEN_PORT  - 千问实例端口（默认 17602，独立于 Kokoro 17493/17600、LuxTTS 17601）
+#   WR_VOICEBOX_PROFILE_ID - 声音 profile ID（可选，缺省读取 ~/.workrelay/speak-qwen/profile_id）
+#   WR_VOICEBOX_LANG       - 语言（默认 zh）
+# 2026-09-14 新增：千问 Qwen3-TTS 能力，固定引擎 qwen_custom_voice（预设音色）
+set -e
+
+TEXT="$1"
+OUT="$2"
+
+if [ -z "$TEXT" ] || [ -z "$OUT" ]; then
+  echo "usage: $0 <text> <output_path>" >&2
+  exit 1
+fi
+
+VB_HOST="${WR_VOICEBOX_HOST:-127.0.0.1}"
+VB_PORT="${WR_VOICEBOX_QWEN_PORT:-17602}"
+PROFILE_ID="${WR_VOICEBOX_PROFILE_ID:-}"
+# 固定引擎：千问预设音色引擎
+ENGINE="qwen_custom_voice"
+LANG="${WR_VOICEBOX_LANG:-zh}"
+
+BASE_URL="http://${VB_HOST}:${VB_PORT}"
+if ! curl -s --max-time 2 "${BASE_URL}/mcp" >/dev/null 2>&1; then
+  echo "ERROR: Voicebox (千问) API 不可达 ($VB_HOST:$VB_PORT)" >&2
+  exit 1
+fi
+
+# ── profile 自动解析（install.sh 写入千问预设音色 profile id）──
+if [ -z "$PROFILE_ID" ] && [ -f "$HOME/.workrelay/speak-qwen/profile_id" ]; then
+  PROFILE_ID=$(cat "$HOME/.workrelay/speak-qwen/profile_id" 2>/dev/null | tr -d ' \n')
+fi
+if [ -z "$PROFILE_ID" ]; then
+  # 兜底：从 /profiles 找千问预设 profile（优先中文女声 Vivian）
+  PROFILE_ID=$(curl --noproxy '*' -s --max-time 5 "$BASE_URL/profiles" 2>/dev/null \
+    | python3 -c '
+import json,sys
+out=""
+try:
+    d=json.load(sys.stdin)
+    for p in d:
+        if p.get("preset_engine")=="qwen_custom_voice" and p.get("language")=="zh":
+            out=p.get("id",""); break
+    if not out:
+        for p in d:
+            if p.get("preset_engine")=="qwen_custom_voice":
+                out=p.get("id",""); break
+    print(out)
+except Exception:
+    print("")
+' 2>/dev/null)
+fi
+if [ -z "$PROFILE_ID" ]; then
+  echo "ERROR: 未找到可用的千问预设音色 profile（Voicebox /profiles 为空）" >&2
+  exit 1
+fi
+
+# JSON-escape text
+TEXT_JSON=$(python3 -c 'import json,sys; print(json.dumps(sys.argv[1]))' "$TEXT")
+
+# 提交生成请求（固定 engine=qwen_custom_voice）
+RESP=$(curl --noproxy '*' -s --max-time 15 -X POST "$BASE_URL/generate" \
+  -H "Content-Type: application/json" \
+  -H "X-Voicebox-Client-Id: workrelay-tts-qwen" \
+  -d "{\"text\": $TEXT_JSON, \"profile_id\": \"$PROFILE_ID\", \"language\": \"$LANG\", \"engine\": \"$ENGINE\"}")
+
+GEN_ID=$(echo "$RESP" | python3 -c 'import json,sys; print(json.load(sys.stdin).get("id",""))' 2>/dev/null)
+if [ -z "$GEN_ID" ]; then
+  echo "ERROR: Voicebox (千问) 生成提交失败: $RESP" >&2
+  exit 1
+fi
+
+# 轮询等待完成（千问 1.7B CPU 推理约 10~180 秒，GPU 更快）
+MAX_POLLS=300
+for i in $(seq 1 $MAX_POLLS); do
+  sleep 1
+  ST=$(curl --noproxy '*' -s --max-time 10 "$BASE_URL/history/$GEN_ID" 2>/dev/null \
+    | python3 -c 'import json,sys; d=json.load(sys.stdin); print(d.get("status",""))' 2>/dev/null)
+  if [ "$ST" = "completed" ]; then
+    break
+  fi
+  if [ "$ST" = "error" ] || [ "$ST" = "failed" ]; then
+    echo "ERROR: Voicebox (千问) 生成失败 (id=$GEN_ID, status=$ST)" >&2
+    exit 1
+  fi
+done
+
+# 下载音频
+curl --noproxy '*' -s --max-time 60 -o "$OUT" "$BASE_URL/audio/$GEN_ID"
+if [ -s "$OUT" ]; then
+  exit 0
+else
+  echo "ERROR: Voicebox (千问) 音频下载失败 (id=$GEN_ID)" >&2
+  exit 1
+fi

package/ext_capabilities/workrelay-transcribe/README.md

@@ -0,0 +1,76 @@
+# WorkRelay 语音转录模块
+
+## 文件说明
+
+| 文件 | 作用 |
+|------|------|
+| `transcribe.py` | faster-whisper 转录引擎（纯 Python，CPU 推理） |
+| `transcribe_server.py` | **常驻转写服务**（2026-08-12 新增）：模型加载一次常驻内存，免每次重新加载 |
+| `voicebox-transcribe.sh` | 转录桥接：优先常驻服务 → 直接本地 → 可选远程 fallback |
+| `install.sh` | 一键安装（依赖→模型→启动常驻服务→OpenClaw 配置） |
+| `status.sh` | 状态查询，输出 JSON，客户端判断"已启用/未启用" |
+
+## 客户端集成方案
+
+### 设置页面
+
+```
+┌─────────────────────────────────────┐
+│  ⚙️ 语音转录                        │
+│                                     │
+│  状态: ● 已启用 / ○ 未启用          │
+│                                     │
+│  模型: faster-whisper-small         │
+│  存储: ~460MB（常驻内存）           │
+│                                     │
+│  [ 启用语音转录 ]  ← 仅未启用时显示  │
+└─────────────────────────────────────┘
+```
+
+### 交互流程
+
+```
+客户端设置页 → 点击[启用] → 发送指令给 Agent
+                           → Agent 执行 install.sh
+                           → 返回进度/结果
+                           → 客户端刷新状态
+
+客户端设置页 → 加载时 → 调用 status.sh
+                     → 解析 JSON
+                     → 显示状态
+```
+
+### status.sh 返回格式
+
+```json
+{
+  "status": "enabled",    // enabled | disabled | partial
+  "description": "语音转录已启用",
+  "checks": {
+    "faster_whisper": true,
+    "model": true,
+    "scripts": true,
+    "openclaw_config": true
+  }
+}
+```
+
+status 为 `enabled` 时四项全部为 true。
+
+## 环境变量（可选）
+
+| 变量 | 默认值 | 说明 |
+|------|--------|------|
+| `WR_WHISPER_MODEL` | `small` | 模型大小（small 默认，广东话/普通话均可用） |
+| `WR_WHISPER_CACHE` | `~/.cache/faster-whisper` | 模型缓存目录 |
+| `WR_WHISPER_PORT` | `17890` | 常驻服务端口 |
+| `WR_INSTALL_DIR` | `~/.workrelay/transcribe` | 脚本安装目录 |
+| `WR_FALLBACK_URL` | 无 | 远程转录服务 URL（不设则仅本地） |
+
+## 限制
+
+- 仅支持 **Linux / macOS**（Windows 用户需 WSL2）
+- 需要 **1GB+** 可用磁盘空间
+- 需要可访问 HuggingFace（下载模型，small ~460MB）
+- 常驻服务首次启动加载模型约 5-10 秒，之后转写即时（3-5 秒）
+- OpenClaw 内置 `MIN_AUDIO_FILE_BYTES=1024`，小于 1KB 的语音不会触发转录

package/ext_capabilities/workrelay-transcribe/install.sh

@@ -0,0 +1,227 @@
+#!/bin/bash
+# WorkRelay 语音转录一键安装脚本
+# 自动完成：依赖安装 → 模型下载 → OpenClaw 配置
+set -e
+
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m'
+
+INSTALL_DIR="$HOME/.workrelay/transcribe"
+MODEL_CACHE="$HOME/.cache/faster-whisper"
+WR_DIR="$(dirname "$(readlink -f "$0")")"
+
+echo "============================================"
+echo "  WorkRelay 语音转录 - 一键安装"
+echo "============================================"
+echo ""
+
+# ── 系统检查 ──
+echo -n "[1/5] 检查系统环境... "
+
+OS="$(uname -s)"
+case "$OS" in
+  Linux)  ;;
+  Darwin) ;;
+  *)
+    echo -e "${RED}失败${NC}"
+    echo "错误：当前仅支持 Linux/macOS，不支持 $OS"
+    echo "提示：Windows 用户请通过 WSL2 运行本脚本"
+    exit 1
+    ;;
+esac
+
+if ! command -v python3 &>/dev/null; then
+  echo -e "${RED}失败${NC}"
+  echo "错误：未找到 python3，请先安装 Python 3.8+"
+  exit 1
+fi
+
+PYVER=$(python3 -c "import sys; print(f'{sys.version_info.major}.{sys.version_info.minor}')")
+echo -e "${GREEN}OK${NC} (Python $PYVER, $(uname -o))"
+
+# ── 磁盘空间检查 ──
+echo -n "[2/5] 检查磁盘空间... "
+AVAIL=$(df -BM "$HOME" | tail -1 | awk '{print $4}' | sed 's/M//')
+if [ "$AVAIL" -lt 2500 ]; then
+  echo -e "${RED}不足${NC}"
+  echo "错误：可用空间 ${AVAIL}MB，至少需要 1GB（模型 ~460MB）"
+  exit 1
+fi
+echo -e "${GREEN}OK${NC} (可用 ${AVAIL}MB)"
+
+# ── 安装 Python 依赖 ──
+echo -n "[3/5] 安装 Python 依赖... "
+
+# 2026-08-18 修复：彻底移除 sudo 依赖，改用户级安装（pip --user / ensurepip --user）。
+# 纯 Linux 上 sudo 通常需要密码，spawn 非交互环境无法输入 → 原 sudo apt-get 方案必失败。
+# 用户级安装无需任何提权，任何机器可用；--break-system-packages 兼容 PEP668 系统。
+export PATH="$PATH:$HOME/.local/bin:/usr/local/bin:/snap/bin"
+
+# 统一 pip 调用入口（pip3 优先，否则 python3 -m pip）
+pip_install() {
+  if command -v pip3 >/dev/null 2>&1; then
+    pip3 "$@"
+  else
+    python3 -m pip "$@"
+  fi
+}
+
+# 确保 pip 可用：python3 -m pip / pip3 都没有时，用 ensurepip --user 自举（Python 自带，无需 sudo）
+if ! python3 -m pip --version &>/dev/null 2>&1 && ! command -v pip3 &>/dev/null; then
+  echo ""
+  echo "  未检测到 pip，使用 python3 -m ensurepip --user 自举安装 ..."
+  if ! python3 -m ensurepip --user >/tmp/wr-pip-err.log 2>&1; then
+    echo -e "${RED}失败${NC}"
+    echo "错误：pip 自举失败，请手动执行："
+    echo "  python3 -m ensurepip --user"
+    echo "  或安装系统 pip（需 root）：sudo apt install python3-pip"
+    cat /tmp/wr-pip-err.log
+    exit 1
+  fi
+  export PATH="$PATH:$HOME/.local/bin"
+fi
+
+# 安装 faster-whisper（用户级 --user，不写系统目录，无需 sudo）
+echo "  pip 可用，安装 faster-whisper（用户级安装）..."
+if ! pip_install install --user --quiet --break-system-packages faster-whisper 2>/tmp/wr-pip-err.log; then
+  # fallback：老系统无 PEP668，无需 --break-system-packages
+  if ! pip_install install --user --quiet faster-whisper 2>>/tmp/wr-pip-err.log; then
+    echo -e "${RED}失败${NC}"
+    echo "错误：faster-whisper 安装失败，请手动执行："
+    echo "  pip3 install --user --break-system-packages faster-whisper"
+    cat /tmp/wr-pip-err.log
+    exit 1
+  fi
+fi
+echo -e "${GREEN}OK${NC}"
+
+# ── 下载模型 ──
+echo -n "[4/5] 下载 Whisper 模型 (~460MB)... "
+echo ""
+# 2026-08-18 修复：systemd 透传的 all_proxy 可能是 socks5://（如 clash），
+# 而 httpx 初始化 SOCKS 代理需要 socksio 包（默认未装）→ ImportError 导致下载失败。
+# clash 混合端口（7890）同时支持 HTTP，这里将 socks5:// 降级为 http://，无需额外装包。
+if [[ "${all_proxy:-}${ALL_PROXY:-}" == *"socks5://"* ]]; then
+  echo "  ℹ 检测到 socks5 代理，降级为 http 代理（clash 混合端口兼容），避免 socksio 依赖"
+  export all_proxy="${all_proxy//socks5:/http:}"
+  export ALL_PROXY="${ALL_PROXY//socks5:/http:}"
+fi
+# 2026-08-18 修复：国内机器直连 HuggingFace 经常 Network unreachable，
+# 增加 hf-mirror.com 镜像自动 fallback（HF_ENDPOINT 环境变量由 huggingface_hub 原生支持）。
+# 直连失败 → 镜像重试 → 仍失败给出手动指引。
+dl_model() {
+  python3 -c "
+import os
+from huggingface_hub import snapshot_download
+endpoint = os.environ.get('HF_ENDPOINT', 'https://huggingface.co')
+print(f'  正在从 {endpoint} 下载 faster-whisper-small ...')
+snapshot_download('Systran/faster-whisper-small',
+                  cache_dir='$MODEL_CACHE')
+print('  模型下载完成')
+" 2>&1
+}
+# 2026-09-14 优化（石头哥）：按区域决定下载顺序
+#   国内（WR_IMAGE_REGION=cn，客户端中文界面传入）→ 镜像优先，省掉直连超时等待
+#   国际/未指定 → 直连优先；两种顺序都保留"失败自动回退另一种"+ 手动指引
+HF_MIRROR_URL="${WR_HF_ENDPOINT:-https://hf-mirror.com}"
+dl_fail_msg() {
+  echo -e "${RED}模型下载失败${NC}"
+  echo "提示：检查网络连接，或手动设置 WR_WHISPER_CACHE 到已有模型目录"
+  echo "  也可手动下载：HF_ENDPOINT=${HF_MIRROR_URL} python3 -c \"from huggingface_hub import snapshot_download; snapshot_download('Systran/faster-whisper-small', cache_dir='$MODEL_CACHE')\""
+}
+if [ "${WR_IMAGE_REGION:-auto}" = "cn" ] && [ -z "${WR_HF_ENDPOINT:-}" ]; then
+  # 国内：镜像优先（避免先直连超时白等）
+  if HF_ENDPOINT="$HF_MIRROR_URL" dl_model; then
+    echo "  ✅ 已通过国内镜像 hf-mirror.com 下载（国内优先，跳过直连等待）"
+  elif dl_model; then
+    echo "  ℹ 国内镜像不可用，已直连 HuggingFace 下载成功"
+  else
+    dl_fail_msg
+    exit 1
+  fi
+else
+  # 国际/自动：直连优先，失败回退镜像
+  if dl_model; then
+    :
+  elif HF_ENDPOINT="$HF_MIRROR_URL" dl_model; then
+    echo "  ℹ 直连 HuggingFace 失败，已通过国内镜像 hf-mirror.com 下载成功"
+  else
+    dl_fail_msg
+    exit 1
+  fi
+fi
+echo -e "  ${GREEN}OK${NC}"
+
+# ── 安装脚本 & 配置 OpenClaw ──
+echo -n "[5/5] 部署脚本 & 配置 OpenClaw... "
+mkdir -p "$INSTALL_DIR"
+cp "$WR_DIR/transcribe.py" "$INSTALL_DIR/"
+cp "$WR_DIR/transcribe_server.py" "$INSTALL_DIR/"
+cp "$WR_DIR/voicebox-transcribe.sh" "$INSTALL_DIR/"
+chmod +x "$INSTALL_DIR/voicebox-transcribe.sh" "$INSTALL_DIR/transcribe.py" "$INSTALL_DIR/transcribe_server.py"
+
+# 2026-08-12：启动常驻转写服务（模型常驻内存，免每次重新加载）。
+# 已在跑则跳过；未跑则后台 detached 启动，日志写入 ~/.openclaw/logs/wr-transcribe-server.log。
+WR_SERVER_PORT="${WR_WHISPER_PORT:-17890}"
+if curl -s --connect-timeout 2 "http://127.0.0.1:${WR_SERVER_PORT}/health" >/dev/null 2>&1; then
+  echo -n " (常驻服务已运行) "
+else
+  mkdir -p "$(dirname "$HOME/.openclaw/logs/wr-transcribe-server.log" 2>/dev/null)" 2>/dev/null || true
+  nohup python3 "$INSTALL_DIR/transcribe_server.py" "$WR_SERVER_PORT" \
+    >>"$HOME/.openclaw/logs/wr-transcribe-server.log" 2>&1 &
+  echo -n " (常驻服务已启动) "
+fi
+
+# 写入 OpenClaw 配置
+if command -v openclaw &>/dev/null; then
+  openclaw config set audio.transcription.command \
+    "[\"$INSTALL_DIR/voicebox-transcribe.sh\", \"{{MediaPath}}\"]" 2>/dev/null || {
+    echo -e "${YELLOW}⚠ OpenClaw 配置写入失败，请手动执行：${NC}"
+    echo "  openclaw config set audio.transcription.command '[\"$INSTALL_DIR/voicebox-transcribe.sh\", \"{{MediaPath}}\"]'"
+  }
+
+  # 2026-08-12：入站语音转写切到本地 faster-whisper（tools.media.audio → cli 模式）。
+  # 默认 OpenClaw 入站音频转写走 tools.media.audio 的云端 provider（如商汤 SenseAudio），
+  # 安装本扩展后应切到本地命令，避免联网/费用；用户无需手动改配置。
+  openclaw config set tools.media.audio.models \
+    '[{"type":"cli","command":"'"$INSTALL_DIR"'/voicebox-transcribe.sh","args":["{{MediaPath}}"]}]' 2>/dev/null || {
+    echo -e "${YELLOW}⚠ tools.media.audio 切本地失败，请手动配置${NC}"
+  }
+  openclaw gateway restart 2>/dev/null || true
+else
+  echo -e "${YELLOW}⚠ 未检测到 openclaw CLI，跳过自动配置${NC}"
+fi
+
+echo -e "${GREEN}OK${NC}"
+echo ""
+
+# ── 验证 ──
+echo "============================================"
+echo "  安装验证"
+echo "============================================"
+
+echo -n "  faster-whisper: "
+python3 -c "import faster_whisper; print(faster_whisper.__version__)" 2>/dev/null \
+  && echo "" \
+  || echo -e "${RED}未安装${NC}"
+
+echo -n "  模型: "
+if [ -d "$MODEL_CACHE" ] && [ "$(du -sm "$MODEL_CACHE" | cut -f1)" -gt 500 ]; then
+  echo -e "${GREEN}$(du -sh "$MODEL_CACHE" | cut -f1)${NC}"
+else
+  echo -e "${RED}未下载或异常${NC}"
+fi
+
+echo -n "  转录脚本: "
+if [ -f "$INSTALL_DIR/transcribe.py" ] && [ -f "$INSTALL_DIR/voicebox-transcribe.sh" ]; then
+  echo -e "${GREEN}已部署${NC}  ($INSTALL_DIR)"
+else
+  echo -e "${RED}缺失${NC}"
+fi
+
+echo ""
+echo -e "${GREEN}✅ 安装完成！${NC}"
+echo "  语音转录将在下次 OpenClaw 重启后生效。"
+echo ""

package/ext_capabilities/workrelay-transcribe/manifest.json

@@ -0,0 +1,42 @@
+{
+  "name": "workrelay-transcribe",
+  "displayName": "语音转录（STT）",
+  "description": "语音消息转文字：本地 faster-whisper 转录，无需联网",
+  "requirements": [
+    {
+      "id": "os",
+      "label": "操作系统",
+      "expect": "Linux / macOS",
+      "check": "uname -s | grep -qiE 'linux|darwin'",
+      "hint": "仅支持 Linux/macOS（Windows 请用 WSL2）"
+    },
+    {
+      "id": "python",
+      "label": "Python 3.8+",
+      "expect": "已安装 python3",
+      "check": "command -v python3 >/dev/null 2>&1 && python3 -c 'import sys; sys.exit(0 if sys.version_info >= (3, 8) else 1)'",
+      "hint": "未找到 Python 3.8+，请先安装 Python"
+    },
+    {
+      "id": "pip",
+      "label": "pip 可用",
+      "expect": "pip3 或 python3 -m pip",
+      "check": "command -v pip3 >/dev/null 2>&1 || python3 -m pip --version >/dev/null 2>&1",
+      "hint": "未找到 pip 时，安装脚本会自动用 python3 -m ensurepip --user 用户级自举，无需手动安装"
+    },
+    {
+      "id": "disk",
+      "label": "磁盘 ≥ 2.5GB",
+      "expect": "≥ 2.5GB 可用",
+      "check": "[ $(df -BM \"$HOME\" | tail -1 | awk '{print $4}' | sed 's/M//') -ge 2560 ]",
+      "hint": "可用空间不足，模型约需 460MB，建议预留 1GB"
+    },
+    {
+      "id": "network",
+      "label": "外网可达（HuggingFace 或镜像）",
+      "expect": "能访问 huggingface.co 或 hf-mirror.com",
+      "check": "curl -sI --max-time 5 https://huggingface.co >/dev/null 2>&1 || curl -sI --max-time 5 https://hf-mirror.com >/dev/null 2>&1",
+      "hint": "无法访问 HuggingFace 及国内镜像，将无法下载 Whisper 模型"
+    }
+  ]
+}