@tencent-weixin/openclaw-weixin-cli 1.0.3 → 2.0.1

package/README.md

@@ -0,0 +1,119 @@
+# openclaw-weixin-installer
+
+OpenClaw 微信消息通道插件的统一安装器。自动检测宿主 OpenClaw 版本，安装兼容的插件版本。
+
+## 快速开始
+
+```bash
+npx -y @tencent-weixin/openclaw-weixin-cli install
+```
+
+安装器会自动完成以下步骤：
+1. 检测本地 `openclaw --version`
+2. 根据兼容矩阵选择合适的插件版本（dist-tag）
+3. 调用 `openclaw plugins install` 安装对应版本
+4. 引导扫码连接微信
+5. 重启 OpenClaw Gateway
+
+**无需手动指定版本号。**
+
+## 兼容矩阵
+
+| openclaw-weixin | 支持的 OpenClaw     | dist-tag | 说明       |
+|-----------------|---------------------|----------|------------|
+| 1.0.x           | >=2026.3.0 <2026.3.22 | `legacy` | 旧宿主维护线 |
+| 2.0.x           | >=2026.3.22            | `latest` | 新宿主线     |
+
+> 从 2.0.0 开始，插件采用独立 semver 版本号，不再对齐宿主 OpenClaw 版本号。
+
+## 手动安装
+
+如果需要手动指定版本，可以直接使用 openclaw 命令：
+
+```bash
+# 查看当前 OpenClaw 版本
+openclaw --version
+
+# 新宿主 (>=2026.3.22)：安装 latest 线
+openclaw plugins install @tencent/openclaw-weixin@latest
+
+# 旧宿主 (<2026.3.22)：安装 legacy 线
+openclaw plugins install @tencent/openclaw-weixin@legacy
+```
+
+## 运行时版本校验
+
+插件在启动时会自动检查宿主版本兼容性。如果版本不匹配，将立即抛出错误：
+
+```
+[openclaw-weixin] 宿主版本不兼容!
+  当前 OpenClaw 版本: 2026.3.10
+  当前插件支持范围:   >=2026.3.22
+  请安装 openclaw-weixin@legacy (1.0.x (旧宿主线))
+  或运行: npx @tencent-weixin/openclaw-weixin-cli install (自动选择兼容版本)
+```
+
+## 故障排查
+
+### 宿主版本不兼容
+
+**症状**：插件启动时报 `宿主版本不兼容` 错误。
+
+**解决**：
+```bash
+# 1. 确认 OpenClaw 版本
+openclaw --version
+
+# 2. 用统一安装器重新安装（自动匹配版本）
+npx -y @tencent-weixin/openclaw-weixin-cli install
+```
+
+### 如何安装 legacy 线
+
+```bash
+# 方式一：统一安装器（自动判断）
+npx -y @tencent-weixin/openclaw-weixin-cli install
+
+# 方式二：手动指定 dist-tag
+openclaw plugins install @tencent/openclaw-weixin@legacy
+```
+
+### 如何查看当前 openclaw 版本
+
+```bash
+openclaw --version
+```
+
+## 发布策略
+
+### dist-tag 说明
+
+| dist-tag | 对应版本线 | 说明 |
+|----------|-----------|------|
+| `latest` | 2.x       | 新宿主线，`npm install` / `openclaw plugins install` 默认安装 |
+| `legacy` | 1.x       | 旧宿主维护线，需显式指定 `@legacy` |
+
+### 发布命令
+
+```bash
+# 发布新宿主线 (2.x)
+npm run publish:external:latest -- patch
+npm run publish:internal:latest -- patch
+
+# 发布旧宿主维护线 (1.x)
+npm run publish:external:legacy -- patch
+npm run publish:internal:legacy -- patch
+
+# dry run 预检
+npm run publish:external:latest -- patch --dry-run
+```
+
+## 开发
+
+```bash
+# 安装开发依赖
+npm install
+
+# 本地测试 install 命令
+node cli.mjs install
+```

package/cli.mjs

@@ -1,6 +1,14 @@
 #!/usr/bin/env node
 
 import { execSync, spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import {
+  COMPAT_MATRIX,
+  findCompatEntry,
+  formatRange,
+} from "./lib/compat.mjs";
 
 const PLUGIN_SPEC = "@tencent-weixin/openclaw-weixin";
 const CHANNEL_ID = "openclaw-weixin";
@@ -35,6 +43,107 @@ function which(bin) {
   }
 }
 
+// ── version detection ───────────────────────────────────────────────────────
+
+function getOpenclawVersion() {
+  try {
+    const raw = run("openclaw --version");
+    const match = raw.match(/(\d+\.\d+\.\d+)/);
+    return match ? match[1] : null;
+  } catch {
+    return null;
+  }
+}
+
+function selectPluginTag(openclawVersion) {
+  const entry = findCompatEntry(openclawVersion);
+  if (entry) return entry;
+
+  error(`当前 OpenClaw 版本 ${openclawVersion} 不在任何已知兼容范围内`);
+  console.log("\n  已知兼容矩阵:");
+  for (const e of COMPAT_MATRIX) {
+    console.log(`    ${e.label}  →  OpenClaw ${formatRange(e.openclawRange)}`);
+  }
+  console.log();
+  return null;
+}
+
+// ── symlink ──────────────────────────────────────────────────────────────────
+
+/**
+ * Resolve the host openclaw package root from the `openclaw` binary.
+ * e.g. /Users/x/.nvm/versions/node/v22/lib/node_modules/openclaw
+ */
+function resolveHostOpenclawRoot() {
+  const bin = which("openclaw");
+  if (!bin) return null;
+  try {
+    // Follow symlinks to the real binary, then go up to the package root.
+    const real = fs.realpathSync(bin);
+    // binary is at <root>/openclaw.mjs or <root>/dist/index.js etc.
+    // Walk up until we find a package.json with name "openclaw".
+    let dir = path.dirname(real);
+    for (let i = 0; i < 6; i++) {
+      try {
+        const pkg = JSON.parse(fs.readFileSync(path.join(dir, "package.json"), "utf-8"));
+        if (pkg.name === "openclaw") return dir;
+      } catch {}
+      const parent = path.dirname(dir);
+      if (parent === dir) break;
+      dir = parent;
+    }
+  } catch {}
+  return null;
+}
+
+/**
+ * Resolve the plugin extensions directory.
+ * Default: ~/.openclaw/extensions/openclaw-weixin
+ */
+function resolvePluginExtDir() {
+  const stateDir = process.env.OPENCLAW_STATE_DIR || path.join(os.homedir(), ".openclaw");
+  return path.join(stateDir, "extensions", "openclaw-weixin");
+}
+
+/**
+ * Create a symlink from the plugin's node_modules/openclaw to the host
+ * openclaw package root. This lets jiti resolve openclaw/plugin-sdk/*
+ * without openclaw being a runtime dependency.
+ */
+function ensureOpenclawSymlink() {
+  const hostRoot = resolveHostOpenclawRoot();
+  if (!hostRoot) {
+    error("无法定位宿主 openclaw 包根目录，跳过 symlink 创建");
+    return;
+  }
+
+  const pluginDir = resolvePluginExtDir();
+  if (!fs.existsSync(pluginDir)) {
+    // Plugin not in extensions dir (might be a -l link install); skip.
+    return;
+  }
+
+  const nmDir = path.join(pluginDir, "node_modules");
+  const linkPath = path.join(nmDir, "openclaw");
+
+  // Check if already correct
+  try {
+    const existing = fs.readlinkSync(linkPath);
+    if (fs.realpathSync(existing) === fs.realpathSync(hostRoot)) {
+      log("openclaw symlink 已存在且正确");
+      return;
+    }
+    // Wrong target — remove and recreate
+    fs.unlinkSync(linkPath);
+  } catch {
+    // Not a symlink or doesn't exist — fine
+  }
+
+  fs.mkdirSync(nmDir, { recursive: true });
+  fs.symlinkSync(hostRoot, linkPath);
+  log(`已创建 symlink: node_modules/openclaw → ${hostRoot}`);
+}
+
 // ── commands ─────────────────────────────────────────────────────────────────
 
 function install() {
@@ -47,10 +156,26 @@ function install() {
   }
   log("已找到本地安装的 openclaw");
 
-  // 2. Install plugin via openclaw
-  log("正在安装插件...");
+  // 2. Detect host version and select compatible plugin
+  const hostVersion = getOpenclawVersion();
+  if (!hostVersion) {
+    error("无法获取 openclaw 版本号，请确认 `openclaw --version` 正常工作");
+    process.exit(1);
+  }
+  log(`检测到 OpenClaw 版本: ${hostVersion}`);
+
+  const compat = selectPluginTag(hostVersion);
+  if (!compat) {
+    process.exit(1);
+  }
+
+  const pluginInstallSpec = `${PLUGIN_SPEC}@${compat.distTag}`;
+  log(`匹配兼容版本: ${compat.label} (dist-tag: ${compat.distTag})`);
+
+  // 3. Install plugin via openclaw
+  log(`正在安装插件 ${pluginInstallSpec}...`);
   try {
-    const installOut = run(`openclaw plugins install "${PLUGIN_SPEC}"`);
+    const installOut = run(`openclaw plugins install "${pluginInstallSpec}"`);
     if (installOut) log(installOut);
   } catch (installErr) {
     if (installErr.stderr && installErr.stderr.includes("already exists")) {
@@ -67,12 +192,16 @@ function install() {
     } else {
       error("插件安装失败，请手动执行：");
       if (installErr.stderr) console.error(installErr.stderr);
-      console.log(`  openclaw plugins install "${PLUGIN_SPEC}"`);
+      console.log(`  openclaw plugins install "${pluginInstallSpec}"`);
       process.exit(1);
     }
   }
 
-  // 3. Login (interactive QR scan)
+  // 4. Symlink host openclaw into plugin's node_modules
+  //    so jiti can resolve openclaw/plugin-sdk/* without a runtime dependency.
+  ensureOpenclawSymlink();
+
+  // 5. Login (interactive QR scan)
   log("插件就绪，开始首次连接...");
   try {
     run(`openclaw channels login --channel ${CHANNEL_ID}`, { silent: false });
@@ -82,7 +211,7 @@ function install() {
     console.log(`  openclaw channels login --channel ${CHANNEL_ID}`);
   }
 
-  // 4. Restart gateway so it picks up the new account
+  // 6. Restart gateway so it picks up the new account
   log("正在重启 OpenClaw Gateway...");
   try {
     run(`openclaw gateway restart`, { silent: false });
@@ -90,7 +219,6 @@ function install() {
     error("重启失败，可手动执行：");
     console.log(`  openclaw gateway restart`);
   }
-
 }
 
 function help() {
@@ -98,9 +226,14 @@ function help() {
   用法: npx -y @tencent-weixin/openclaw-weixin-cli <命令>
 
   命令:
-    install   安装微信插件并扫码连接
+    install   自动检测 OpenClaw 版本，安装兼容的微信插件并扫码连接
     help      显示帮助信息
-`);
+
+  兼容矩阵:`);
+  for (const e of COMPAT_MATRIX) {
+    console.log(`    ${e.label.padEnd(28)} OpenClaw ${formatRange(e.openclawRange)}`);
+  }
+  console.log();
 }
 
 // ── main ─────────────────────────────────────────────────────────────────────

package/lib/compat.mjs

@@ -0,0 +1,61 @@
+// lib/compat.mjs
+// Centralized compatibility matrix for openclaw-weixin plugin versions.
+
+/**
+ * Each entry maps a plugin major version to the supported OpenClaw host range.
+ * Used by both the installer CLI (auto-select) and the plugin runtime (fail-fast).
+ */
+export const COMPAT_MATRIX = [
+  {
+    pluginMajor: 1,
+    distTag: 'legacy',
+    openclawRange: { gte: '2026.3.0', lt: '2026.3.22' },
+    label: '1.0.x (旧宿主线)',
+  },
+  {
+    pluginMajor: 2,
+    distTag: 'latest',
+    openclawRange: { gte: '2026.3.22' },
+    label: '2.0.x (新宿主线)',
+  },
+];
+
+/** Parse a version string like "2026.3.22" into [major, minor, patch]. */
+export function parseVersion(v) {
+  const m = String(v).match(/(\d+)\.(\d+)\.(\d+)/);
+  if (!m) return null;
+  return [Number(m[1]), Number(m[2]), Number(m[3])];
+}
+
+/** Compare two version strings. Returns <0, 0, or >0. */
+export function compareVersions(a, b) {
+  const va = parseVersion(a);
+  const vb = parseVersion(b);
+  if (!va || !vb) return NaN;
+  for (let i = 0; i < 3; i++) {
+    if (va[i] !== vb[i]) return va[i] - vb[i];
+  }
+  return 0;
+}
+
+/** Check if `version` satisfies { gte, lt } range. */
+export function satisfiesRange(version, range) {
+  if (range.gte && compareVersions(version, range.gte) < 0) return false;
+  if (range.lt && compareVersions(version, range.lt) >= 0) return false;
+  return true;
+}
+
+/** Find the matching matrix entry for a given OpenClaw host version. */
+export function findCompatEntry(openclawVersion) {
+  return COMPAT_MATRIX.find(entry =>
+    satisfiesRange(openclawVersion, entry.openclawRange)
+  ) || null;
+}
+
+/** Format a range for display, e.g. ">=2026.3.22 <2026.4.0". */
+export function formatRange(range) {
+  const parts = [];
+  if (range.gte) parts.push(`>=${range.gte}`);
+  if (range.lt) parts.push(`<${range.lt}`);
+  return parts.join(' ');
+}

package/lib/version-check.mjs

@@ -0,0 +1,86 @@
+// lib/version-check.mjs
+// Runtime fail-fast version check — call at plugin initialization.
+//
+// Usage (in plugin entry point):
+//   import { assertHostCompat } from '@tencent/openclaw-weixin/lib/version-check.mjs';
+//   assertHostCompat();
+
+import { readFileSync } from 'node:fs';
+import { resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import {
+  COMPAT_MATRIX,
+  findCompatEntry,
+  parseVersion,
+  formatRange,
+} from './compat.mjs';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+/**
+ * Resolve the current OpenClaw host version.
+ * Checks (in order):
+ *   1. OPENCLAW_VERSION env var (set by host since 2026.3.x)
+ *   2. globalThis.__openclaw_version__ (injected by host runtime)
+ */
+export function getHostVersion() {
+  if (process.env.OPENCLAW_VERSION) return process.env.OPENCLAW_VERSION;
+  if (globalThis.__openclaw_version__) return String(globalThis.__openclaw_version__);
+  return null;
+}
+
+/**
+ * Read the plugin's own major version from its package.json.
+ */
+function getPluginMajor() {
+  try {
+    const pkg = JSON.parse(
+      readFileSync(resolve(__dirname, '..', 'package.json'), 'utf-8'),
+    );
+    return parseVersion(pkg.version)?.[0] ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Assert that the current host is compatible with this plugin version.
+ * Throws a clear error if incompatible; silently returns on success.
+ */
+export function assertHostCompat() {
+  const hostVersion = getHostVersion();
+  if (!hostVersion) {
+    console.warn(
+      '[openclaw-weixin] 无法检测 OpenClaw 宿主版本，跳过兼容性检查',
+    );
+    return;
+  }
+
+  const pluginMajor = getPluginMajor();
+  const entry = COMPAT_MATRIX.find(e => e.pluginMajor === pluginMajor);
+  if (!entry) {
+    console.warn(
+      `[openclaw-weixin] 未知插件主版本 ${pluginMajor}，跳过兼容性检查`,
+    );
+    return;
+  }
+
+  const compat = findCompatEntry(hostVersion);
+  if (compat && compat.pluginMajor === pluginMajor) {
+    // Compatible — nothing to do.
+    return;
+  }
+
+  const supported = formatRange(entry.openclawRange);
+  const suggestion = compat
+    ? `请安装 openclaw-weixin@${compat.distTag} (${compat.label})`
+    : '请升级或降级 OpenClaw 宿主到受支持的版本';
+
+  throw new Error(
+    `[openclaw-weixin] 宿主版本不兼容!\n` +
+    `  当前 OpenClaw 版本: ${hostVersion}\n` +
+    `  当前插件支持范围:   ${supported}\n` +
+    `  ${suggestion}\n` +
+    `  或运行: npx @tencent-weixin/openclaw-weixin-cli install (自动选择兼容版本)`,
+  );
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tencent-weixin/openclaw-weixin-cli",
-  "version": "1.0.3",
+  "version": "2.0.1",
   "description": "Lightweight installer for the OpenClaw Weixin channel plugin",
   "license": "MIT",
   "author": "Tencent",
@@ -9,9 +9,21 @@
     "weixin-installer": "./cli.mjs"
   },
   "files": [
-    "cli.mjs"
+    "cli.mjs",
+    "lib/"
   ],
   "scripts": {},
+  "peerDependencies": {
+    "openclaw": ">=2026.3.0"
+  },
+  "peerDependenciesMeta": {
+    "openclaw": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "openclaw": "2026.3.22"
+  },
   "engines": {
     "node": ">=22"
   }