lightclawbot 1.0.3 → 1.0.4

package/README.md

@@ -1 +1,241 @@
-## 对接 openclaw 的 channel 插件
+# LightClaw — OpenClaw Channel 插件
+
+对接 OpenClaw 框架的 LightClaw Bot channel 插件，支持多 apiKey（多账户）模式。
+
+---
+
+## 目录
+
+- [配置](#配置)
+- [多账户 apiKey 体系](#多账户-apikey-体系)
+  - [整体架构](#整体架构)
+  - [数据流全景](#数据流全景)
+  - [两级映射设计](#两级映射设计)
+  - [resolveEffectiveApiKey 统一入口](#resolveeffectiveapikey-统一入口)
+  - [为什么不能只用一级映射](#为什么不能只用一级映射)
+- [关键模块说明](#关键模块说明)
+- [调试指南](#调试指南)
+- [已知约束与注意事项](#已知约束与注意事项)
+
+---
+
+## 配置
+
+`~/.openclaw/openclaw.json` 中 `channels.lightclawbot` 段：
+
+```json
+{
+  "channels": {
+    "lightclawbot": {
+      "apiKeys": ["key-1", "key-2", "key-3"],
+      "enabled": true,
+      "dmScope": "per-channel-peer"
+    }
+  }
+}
+```
+
+| 字段 | 说明 |
+|------|------|
+| `apiKeys` | apiKey 数组，每个 key 对应一个 uin（用户身份）。`apiKeys[0]` 为主 key，同时作为默认 fallback |
+| `dmScope` | 会话隔离粒度，推荐 `"per-channel-peer"`（每用户独立 session） |
+
+> **注意**：配置中只有 `apiKeys`（复数数组），没有 `apiKey`（单数字段）。运行时 `account.apiKey` 的值取自 `apiKeys[0]`。
+
+---
+
+## 多账户 apiKey 体系
+
+### 整体架构
+
+多 apiKey 模式下，一个 Bot 可以持有多个 apiKey，每个 apiKey 关联到不同的 uin（用户身份）。插件需要在处理消息和执行工具时，正确选取当前用户对应的 apiKey。
+
+核心挑战：**消息处理（inbound）** 和 **工具执行（tool）** 拿到的上下文信息不同：
+
+| 阶段 | 可用标识 | 不可用标识 |
+|------|---------|-----------|
+| inbound 消息到达 | `msg.senderId`（uin） | sessionKey（需路由解析后才知道） |
+| tool 执行 | `ctx.sessionKey` | uin（框架不传递） |
+
+因此需要 **两级映射** 来桥接两个阶段。
+
+### 数据流全景
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                     Gateway 启动（一次性）                        │
+│                                                                 │
+│  1. 读取配置中的 apiKeys 数组                                     │
+│  2. 对每个 apiKey 调用 /user/current 获取其 uin                   │
+│  3. 构建 uin→apiKey 映射表（apiKeyMap）                           │
+│  4. setApiKeyMap(apiKeyMap, apiKeys[0])                          │
+│     ├─ globalApiKeyMap  = { uin_A→key_1, uin_B→key_2, ... }     │
+│     └─ globalDefaultApiKey = apiKeys[0]  (fallback 兜底)         │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                   Inbound 消息处理（每条消息）                     │
+│                                                                 │
+│  1. 收到消息，msg.senderId = uin_A                                │
+│  2. resolveEffectiveApiKey({ senderId: uin_A })                  │
+│     → 命中 globalApiKeyMap → 返回 key_1                          │
+│  3. resolveAgentRoute(...) → 得到 route.sessionKey               │
+│  4. setSessionApiKey(route.sessionKey, key_1)                    │
+│     └─ sessionKeyToApiKey = { "agent:main:lc:direct:uin_A"→key_1 } │
+│  5. 处理消息、下载/上传附件（均使用 key_1）                         │
+│  6. 分发给 AI 引擎                                               │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                   Tool 执行（AI 调用工具时）                       │
+│                                                                 │
+│  1. 框架传入 ctx.sessionKey = "agent:main:lc:direct:uin_A"       │
+│  2. resolveEffectiveApiKey({ sessionKey })                       │
+│     → 命中 sessionKeyToApiKey → 返回 key_1                       │
+│  3. 使用 key_1 上传/下载文件到 COS                                │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### 两级映射设计
+
+```
+config.ts 中维护的全局状态：
+
+  ┌─────────────────────────────────────────────────────────┐
+  │  第1级：globalApiKeyMap  (uin → apiKey)                  │
+  │  写入时机：gateway 启动时（setApiKeyMap，一次性）          │
+  │  读取时机：inbound 处理消息时                             │
+  │  数据规模：= apiKeys 数量（固定，不随消息增长）            │
+  └─────────────────────────────────────────────────────────┘
+
+  ┌─────────────────────────────────────────────────────────┐
+  │  第2级：sessionKeyToApiKey  (sessionKey → apiKey)        │
+  │  写入时机：每条消息 inbound 处理时（setSessionApiKey）     │
+  │  读取时机：tool 执行时                                    │
+  │  数据规模：= 活跃用户数（动态增长，但不会很大）             │
+  └─────────────────────────────────────────────────────────┘
+
+  ┌─────────────────────────────────────────────────────────┐
+  │  兜底：globalDefaultApiKey                               │
+  │  值 = apiKeys[0]，当以上两级都未命中时使用                 │
+  └─────────────────────────────────────────────────────────┘
+```
+
+### resolveEffectiveApiKey 统一入口
+
+所有需要获取 apiKey 的地方（inbound / upload-tool / download-tool）统一调用此函数：
+
+```typescript
+resolveEffectiveApiKey(params: {
+  sessionKey?: string;  // tool 执行时传入
+  senderId?: string;    // inbound 处理时传入
+}): string
+```
+
+**查找优先级**：
+
+| 优先级 | 数据源 | 场景 |
+|:------:|--------|------|
+| 1 | `sessionKeyToApiKey[sessionKey]` | tool 执行时的主路径 |
+| 2 | `globalApiKeyMap[senderId]` | inbound 处理时的主路径 |
+| 3 | `globalApiKeyMap[extractUinFromSessionKey(sessionKey)]` | 兜底：从 sessionKey 解析 uin |
+| 4 | `globalDefaultApiKey` | 最终 fallback |
+
+### 为什么不能只用一级映射
+
+**方案：只保留 sessionKeyToApiKey，去掉 globalApiKeyMap？**
+
+不可行，原因是 **时序依赖**：
+
+```
+用户首条消息到达 inbound：
+  │
+  ├─ 此时需要 apiKey（用于下载附件等）
+  │  → 但 sessionKey 尚未算出（要先调 resolveAgentRoute）
+  │  → 即使 sessionKey 已知，sessionKeyToApiKey 中没有记录（首条消息，从未写入过）
+  │  → ❌ 无法获取 apiKey
+  │
+  └─ 而 uin（msg.senderId）立即可用
+     → globalApiKeyMap 在 gateway 启动时就已构建好
+     → ✅ 可直接查到 apiKey
+```
+
+**`globalApiKeyMap` 是冷启动数据源（gateway 启动时预建），`sessionKeyToApiKey` 是运行时缓存（消息处理时按需写入）。** 两者解决不同阶段的问题，缺一不可。
+
+---
+
+## 关键模块说明
+
+| 文件 | 职责 | 与 apiKey 体系的关系 |
+|------|------|---------------------|
+| `src/config.ts` | 配置解析 + apiKey 映射管理 | 定义 `setApiKeyMap`、`setSessionApiKey`、`resolveEffectiveApiKey` |
+| `src/gateway.ts` | Socket.IO 连接生命周期管理 | 启动时调用 `resolveApiKeyIdentities` + `setApiKeyMap` 构建第1级映射 |
+| `src/inbound.ts` | 入站消息处理 | 调用 `resolveEffectiveApiKey({ senderId })` 获取 apiKey，再调用 `setSessionApiKey` 写入第2级映射 |
+| `src/upload-tool.ts` | 文件上传工具 | 调用 `resolveEffectiveApiKey({ sessionKey })` 获取 apiKey，传给 COS 上传 |
+| `src/download-tool.ts` | 文件下载/转发工具 | 同上 |
+| `src/file-storage.ts` | COS 文件存储封装 | 接收 `{ apiKey }` 参数，执行实际的 HTTP 上传/下载 |
+
+### gateway.ts 中的 resolveApiKeyIdentities
+
+```
+对每个 apiKey 调用 /user/current，一次遍历完成：
+- 提取每个 key 对应的 uin，构建 uin→apiKey 映射
+- 从第一个成功的 key 中提取 botClientId（所有 key 共享同一个 bot）
+- 容错：第一个 key 必须成功（否则无 botId，直接抛异常），后续 key 失败可降级跳过
+- 总计 N 次 HTTP 请求，无重复调用
+```
+
+### inbound.ts 中的 mainSessionKey 安全约束
+
+```typescript
+// ⚠️ 只写入 per-channel-peer 的 sessionKey，不写入 mainSessionKey
+// mainSessionKey（= "agent:main:main"）是全局共享的，所有用户消息都会覆盖它，
+// 导致最后一个用户的 apiKey 覆盖前一个用户，产生并发安全问题。
+if (route?.sessionKey) {
+  setSessionApiKey(route.sessionKey, effectiveApiKey);
+}
+```
+
+---
+
+## 调试指南
+
+### 查看 apiKey 选取日志
+
+upload-tool 和 download-tool 中保留了 `log.warn` 级别的调试日志：
+
+```
+[lightclaw_upload_file] sessionKey="agent:main:lightclawbot:direct:12345", accountId="default"
+[lightclaw_upload_file] resolved apiKey="key1abcd..."
+```
+
+这些日志在终端始终可见（warn 级别不会被框架过滤）。
+
+### 框架日志级别说明
+
+| 级别 | 终端可见性 | 适用场景 |
+|------|-----------|---------|
+| `log.debug` | 通常不可见 | 详细流程追踪 |
+| `log.info` | 取决于配置 | 常规信息 |
+| `log.warn` | **始终可见** | 调试关键路径、apiKey 选取 |
+| `log.error` | **始终可见** | 错误 |
+
+### apiKey 日志脱敏
+
+所有日志中 apiKey 只打印前 8 位（如 `key1abcd...`），避免泄露完整密钥。
+
+---
+
+## 已知约束与注意事项
+
+1. **dmScope 必须为 `per-channel-peer`**：确保每个用户有独立的 sessionKey，避免 `sessionKeyToApiKey` 并发覆盖。如果使用 `main`（默认值），所有用户共享同一个 sessionKey，多 key 模式会出问题。
+
+2. **sessionKeyToApiKey 只增不减**：当前实现中没有过期清理机制。在活跃用户数有限的场景下不是问题。如果未来用户量极大，需考虑 LRU 或 TTL 淘汰策略。
+
+3. **gateway 重启会重建 globalApiKeyMap**：`setApiKeyMap` 在每次 `startGateway` 时调用，会覆盖之前的映射。但 `sessionKeyToApiKey` 是累积的，重启后会被清空（模块级变量）。
+
+4. **单 key 模式兼容**：当 `apiKeys` 只有一个元素时，`globalApiKeyMap` 只有一条记录，`resolveEffectiveApiKey` 最终都会 fallback 到 `globalDefaultApiKey`，行为与之前一致。
+
+5. **环境变量兜底**：如果配置文件中没有 `apiKeys`，会尝试从 `LIGHTCLAW_API_KEY` 环境变量读取。

package/dist/public/data/scripts/check-update.9c4e848e.sh

@@ -0,0 +1,138 @@
+#!/bin/bash
+
+# ========== lightclawbot 插件升级检查脚本 ==========
+# 用途：检查 lightclawbot 插件是否需要升级（只检查，不执行安装）
+# 输出：最后一行固定为 RESULT:{...} JSON，供前端解析
+#
+# 状态说明：
+#   - 已是最新：    RESULT:{"status":"up_to_date","local":"x.y.z","remote":"x.y.z"}
+#   - 需要升级：    RESULT:{"status":"update_available","local":"x.y.z","remote":"x.y.z"}
+#   - 未安装：      RESULT:{"status":"not_installed","remote":"x.y.z"}
+#   - 无法检查：    RESULT:{"status":"error","error":"...","detail":"..."}
+#
+# 使用方式：
+#   本地执行：  bash scripts/check-update.sh
+#   CDN 执行：  bash <(curl -fsSL https://your-cdn.com/check-update.sh)
+#
+# 环境变量：
+#   NPM_REGISTRY  — npm 源地址（默认腾讯镜像）
+#   TIMEOUT        — npm view 超时秒数（默认 10）
+
+set -euo pipefail
+
+# ========== 配置 ==========
+
+NPM_REGISTRY="${NPM_REGISTRY:-https://mirrors.tencent.com/npm/}"
+TIMEOUT="${TIMEOUT:-10}"
+
+id="lightclawbot"
+spec="lightclawbot"
+plugin_dir="$HOME/.openclaw/extensions/${id}"
+
+# ========== 环境加载 ==========
+
+load_env() {
+  export NVM_DIR="$HOME/.nvm"
+  [ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
+
+  if [ -z "${PNPM_HOME:-}" ] && [ -d "$HOME/.local/share/pnpm" ]; then
+    export PNPM_HOME="$HOME/.local/share/pnpm"
+    export PATH="$PNPM_HOME:$PATH"
+  fi
+}
+
+load_env
+
+# ========== 工具函数 ==========
+
+# semver 比较：left < right 返回 0，否则返回 1，解析失败返回 2
+version_lt() {
+  local left="$1"
+  local right="$2"
+  VERSION_LEFT="$left" VERSION_RIGHT="$right" node - <<'NODE'
+function parseSemver(value) {
+  const match = String(value || "").trim().match(/^(\d+)\.(\d+)\.(\d+)(?:[-+].*)?$/);
+  if (!match) return null;
+  return [Number(match[1]), Number(match[2]), Number(match[3])];
+}
+const left = parseSemver(process.env.VERSION_LEFT);
+const right = parseSemver(process.env.VERSION_RIGHT);
+if (!left || !right) process.exit(2);
+for (let i = 0; i < 3; i++) {
+  if (left[i] < right[i]) process.exit(0);
+  if (left[i] > right[i]) process.exit(1);
+}
+process.exit(1);
+NODE
+}
+
+# ========== 1. 检查前置依赖 ==========
+
+if ! command -v npm &>/dev/null; then
+  echo "RESULT:{\"status\":\"error\",\"error\":\"missing_dependency\",\"detail\":\"npm not found\"}"
+  exit 1
+fi
+
+# ========== 2. 获取本地版本 ==========
+
+local_version=""
+if [ -d "$plugin_dir" ] && [ -f "$plugin_dir/package.json" ]; then
+  if command -v jq &>/dev/null; then
+    local_version=$(jq -r '.version // ""' "$plugin_dir/package.json" 2>/dev/null || true)
+  elif command -v node &>/dev/null; then
+    local_version=$(node -e "
+      try {
+        const p = require('$plugin_dir/package.json');
+        process.stdout.write(p.version || '');
+      } catch {}
+    " 2>/dev/null || true)
+  fi
+fi
+
+# ========== 3. 查询远程最新版本 ==========
+
+remote_version=""
+
+# 尝试腾讯镜像源
+remote_version=$(timeout "$TIMEOUT" npm view "$spec" version --registry "$NPM_REGISTRY" 2>/dev/null || true)
+
+# 回退到官方源
+if [ -z "$remote_version" ]; then
+  remote_version=$(timeout "$TIMEOUT" npm view "$spec" version --registry https://registry.npmjs.org 2>/dev/null || true)
+fi
+
+if [ -z "$remote_version" ]; then
+  echo "RESULT:{\"status\":\"error\",\"error\":\"fetch_failed\",\"detail\":\"could not fetch remote version from any registry\"}"
+  exit 1
+fi
+
+# ========== 4. 比较版本 ==========
+
+# 未安装
+if [ -z "$local_version" ]; then
+  echo "RESULT:{\"status\":\"not_installed\",\"remote\":\"${remote_version}\"}"
+  exit 0
+fi
+
+# 版本相同
+if [ "$local_version" = "$remote_version" ]; then
+  echo "RESULT:{\"status\":\"up_to_date\",\"local\":\"${local_version}\",\"remote\":\"${remote_version}\"}"
+  exit 0
+fi
+
+# semver 比较（需要 node）
+if command -v node &>/dev/null; then
+  if version_lt "$local_version" "$remote_version"; then
+    # local < remote → 需要升级
+    echo "RESULT:{\"status\":\"update_available\",\"local\":\"${local_version}\",\"remote\":\"${remote_version}\"}"
+    exit 0
+  else
+    # local >= remote（可能是开发版本或降级场景）
+    echo "RESULT:{\"status\":\"up_to_date\",\"local\":\"${local_version}\",\"remote\":\"${remote_version}\"}"
+    exit 0
+  fi
+fi
+
+# 没有 node，只能做字符串不等判断
+echo "RESULT:{\"status\":\"update_available\",\"local\":\"${local_version}\",\"remote\":\"${remote_version}\"}"
+exit 0

package/dist/public/data/scripts/check-update.sh

@@ -0,0 +1,138 @@
+#!/bin/bash
+
+# ========== lightclawbot 插件升级检查脚本 ==========
+# 用途：检查 lightclawbot 插件是否需要升级（只检查，不执行安装）
+# 输出：最后一行固定为 RESULT:{...} JSON，供前端解析
+#
+# 状态说明：
+#   - 已是最新：    RESULT:{"status":"up_to_date","local":"x.y.z","remote":"x.y.z"}
+#   - 需要升级：    RESULT:{"status":"update_available","local":"x.y.z","remote":"x.y.z"}
+#   - 未安装：      RESULT:{"status":"not_installed","remote":"x.y.z"}
+#   - 无法检查：    RESULT:{"status":"error","error":"...","detail":"..."}
+#
+# 使用方式：
+#   本地执行：  bash scripts/check-update.sh
+#   CDN 执行：  bash <(curl -fsSL https://your-cdn.com/check-update.sh)
+#
+# 环境变量：
+#   NPM_REGISTRY  — npm 源地址（默认腾讯镜像）
+#   TIMEOUT        — npm view 超时秒数（默认 10）
+
+set -euo pipefail
+
+# ========== 配置 ==========
+
+NPM_REGISTRY="${NPM_REGISTRY:-https://mirrors.tencent.com/npm/}"
+TIMEOUT="${TIMEOUT:-10}"
+
+id="lightclawbot"
+spec="lightclawbot"
+plugin_dir="$HOME/.openclaw/extensions/${id}"
+
+# ========== 环境加载 ==========
+
+load_env() {
+  export NVM_DIR="$HOME/.nvm"
+  [ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
+
+  if [ -z "${PNPM_HOME:-}" ] && [ -d "$HOME/.local/share/pnpm" ]; then
+    export PNPM_HOME="$HOME/.local/share/pnpm"
+    export PATH="$PNPM_HOME:$PATH"
+  fi
+}
+
+load_env
+
+# ========== 工具函数 ==========
+
+# semver 比较：left < right 返回 0，否则返回 1，解析失败返回 2
+version_lt() {
+  local left="$1"
+  local right="$2"
+  VERSION_LEFT="$left" VERSION_RIGHT="$right" node - <<'NODE'
+function parseSemver(value) {
+  const match = String(value || "").trim().match(/^(\d+)\.(\d+)\.(\d+)(?:[-+].*)?$/);
+  if (!match) return null;
+  return [Number(match[1]), Number(match[2]), Number(match[3])];
+}
+const left = parseSemver(process.env.VERSION_LEFT);
+const right = parseSemver(process.env.VERSION_RIGHT);
+if (!left || !right) process.exit(2);
+for (let i = 0; i < 3; i++) {
+  if (left[i] < right[i]) process.exit(0);
+  if (left[i] > right[i]) process.exit(1);
+}
+process.exit(1);
+NODE
+}
+
+# ========== 1. 检查前置依赖 ==========
+
+if ! command -v npm &>/dev/null; then
+  echo "RESULT:{\"status\":\"error\",\"error\":\"missing_dependency\",\"detail\":\"npm not found\"}"
+  exit 1
+fi
+
+# ========== 2. 获取本地版本 ==========
+
+local_version=""
+if [ -d "$plugin_dir" ] && [ -f "$plugin_dir/package.json" ]; then
+  if command -v jq &>/dev/null; then
+    local_version=$(jq -r '.version // ""' "$plugin_dir/package.json" 2>/dev/null || true)
+  elif command -v node &>/dev/null; then
+    local_version=$(node -e "
+      try {
+        const p = require('$plugin_dir/package.json');
+        process.stdout.write(p.version || '');
+      } catch {}
+    " 2>/dev/null || true)
+  fi
+fi
+
+# ========== 3. 查询远程最新版本 ==========
+
+remote_version=""
+
+# 尝试腾讯镜像源
+remote_version=$(timeout "$TIMEOUT" npm view "$spec" version --registry "$NPM_REGISTRY" 2>/dev/null || true)
+
+# 回退到官方源
+if [ -z "$remote_version" ]; then
+  remote_version=$(timeout "$TIMEOUT" npm view "$spec" version --registry https://registry.npmjs.org 2>/dev/null || true)
+fi
+
+if [ -z "$remote_version" ]; then
+  echo "RESULT:{\"status\":\"error\",\"error\":\"fetch_failed\",\"detail\":\"could not fetch remote version from any registry\"}"
+  exit 1
+fi
+
+# ========== 4. 比较版本 ==========
+
+# 未安装
+if [ -z "$local_version" ]; then
+  echo "RESULT:{\"status\":\"not_installed\",\"remote\":\"${remote_version}\"}"
+  exit 0
+fi
+
+# 版本相同
+if [ "$local_version" = "$remote_version" ]; then
+  echo "RESULT:{\"status\":\"up_to_date\",\"local\":\"${local_version}\",\"remote\":\"${remote_version}\"}"
+  exit 0
+fi
+
+# semver 比较（需要 node）
+if command -v node &>/dev/null; then
+  if version_lt "$local_version" "$remote_version"; then
+    # local < remote → 需要升级
+    echo "RESULT:{\"status\":\"update_available\",\"local\":\"${local_version}\",\"remote\":\"${remote_version}\"}"
+    exit 0
+  else
+    # local >= remote（可能是开发版本或降级场景）
+    echo "RESULT:{\"status\":\"up_to_date\",\"local\":\"${local_version}\",\"remote\":\"${remote_version}\"}"
+    exit 0
+  fi
+fi
+
+# 没有 node，只能做字符串不等判断
+echo "RESULT:{\"status\":\"update_available\",\"local\":\"${local_version}\",\"remote\":\"${remote_version}\"}"
+exit 0

package/dist/public/data/scripts/manifest.json

@@ -0,0 +1,21 @@
+{
+  "generatedAt": "2026-03-16T03:41:55.361Z",
+  "cdnBase": "https://cloudcache.tencent-cloud.com/qcloud/tea/app/data/scripts",
+  "files": {
+    "preflight.sh": {
+      "hashed": "preflight.7c5a27cd.sh",
+      "hash": "7c5a27cd",
+      "size": 3105
+    },
+    "check-update.sh": {
+      "hashed": "check-update.9c4e848e.sh",
+      "hash": "9c4e848e",
+      "size": 4422
+    },
+    "upgrade.sh": {
+      "hashed": "upgrade.bd220b70.sh",
+      "hash": "bd220b70",
+      "size": 8398
+    }
+  }
+}

package/dist/public/data/scripts/preflight.7c5a27cd.sh

@@ -0,0 +1,86 @@
+#!/bin/bash
+
+# ========== lightclawbot 插件前置检查脚本 ==========
+# 用途：快速判断 lightclawbot 插件是否可用
+# 输出：最后一行固定为 RESULT:{...} JSON，供前端解析
+#   - 可用：           RESULT:{"status":"ok","version":"x.y.z"}
+#   - 缺 openclaw：    RESULT:{"status":"need_openclaw","reason":"..."}
+#   - 缺 lightclawbot：RESULT:{"status":"need_install","reason":"..."}
+#
+# 使用方式：
+#   本地执行：  bash scripts/preflight.sh
+#   CDN 执行：  bash <(curl -fsSL https://your-cdn.com/preflight.sh)
+
+id="lightclawbot"
+cfg="$HOME/.openclaw/openclaw.json"
+plugin_dir="$HOME/.openclaw/extensions/${id}"
+
+# ---------- 1. 检查 openclaw 是否可用 ----------
+
+# 加载 nvm 环境（openclaw 可能依赖 nvm 管理的 node）
+export NVM_DIR="$HOME/.nvm"
+[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
+
+if ! command -v openclaw &>/dev/null; then
+  echo "RESULT:{\"status\":\"need_openclaw\",\"reason\":\"openclaw_not_found\"}"
+  exit 1
+fi
+
+# 验证 openclaw 可执行
+# 已知输出格式：
+#   - OpenClaw 2026.3.8 (3caab92)   （新版本，带前缀 + commit hash）
+#   - OpenClaw 2026.3.2             （带前缀，无 commit hash）
+#   - 2026.3.2                      （旧版本，直接输出版本号，无前缀）
+openclaw_output=$(openclaw -v 2>/dev/null || true)
+if ! echo "$openclaw_output" | grep -qiE '(^OpenClaw[/ ])?[0-9]+\.[0-9]+'; then
+  echo "RESULT:{\"status\":\"need_openclaw\",\"reason\":\"openclaw_not_working\"}"
+  exit 1
+fi
+
+# ---------- 2. 检查配置文件是否存在 ----------
+
+if [ ! -f "$cfg" ]; then
+  echo "RESULT:{\"status\":\"need_install\",\"reason\":\"config_not_found\"}"
+  exit 1
+fi
+
+# ---------- 3. 检查插件是否已安装（目录 + package.json） ----------
+
+if [ ! -d "$plugin_dir" ] || [ ! -f "$plugin_dir/package.json" ]; then
+  echo "RESULT:{\"status\":\"need_install\",\"reason\":\"plugin_not_installed\"}"
+  exit 1
+fi
+
+# ---------- 4. 检查配置文件中插件注册是否完整 ----------
+
+# 需要 jq 来解析 JSON
+if ! command -v jq &>/dev/null; then
+  echo "RESULT:{\"status\":\"need_install\",\"reason\":\"jq_not_found\"}"
+  exit 1
+fi
+
+# 4a. plugins.entries 中是否存在且 enabled
+plugin_enabled=$(jq -r ".plugins.entries.\"${id}\".enabled // false" "$cfg" 2>/dev/null)
+if [ "$plugin_enabled" != "true" ]; then
+  echo "RESULT:{\"status\":\"need_install\",\"reason\":\"plugin_not_enabled\"}"
+  exit 1
+fi
+
+# 4b. plugins.installs 中是否有安装记录
+if ! jq -e ".plugins.installs.\"${id}\"" "$cfg" > /dev/null 2>&1; then
+  echo "RESULT:{\"status\":\"need_install\",\"reason\":\"plugin_install_record_missing\"}"
+  exit 1
+fi
+
+# 4c. channels 中是否配置且 enabled
+channel_enabled=$(jq -r ".channels.\"${id}\".enabled // false" "$cfg" 2>/dev/null)
+if [ "$channel_enabled" != "true" ]; then
+  echo "RESULT:{\"status\":\"need_install\",\"reason\":\"channel_not_enabled\"}"
+  exit 1
+fi
+
+# ---------- 5. 全部通过，插件可用 ----------
+
+version=$(jq -r '.version // "unknown"' "$plugin_dir/package.json")
+echo "RESULT:{\"status\":\"ok\",\"version\":\"${version}\"}"
+exit 0