@tencent-connect/openclaw-qqbot 1.7.2 → 2.0.0

package/src/adapter/contract.ts

@@ -0,0 +1,69 @@
+/**
+ * Runtime Contract Check — 启动时校验必需 API 可用性。
+ *
+ * 在 plugin.register() 中立刻调用，console 直接输出（register 阶段
+ * runtime.logging 的 getChildLogger 存在但输出管道未接通）。
+ */
+
+import type { PluginRuntime } from 'openclaw/plugin-sdk';
+import { createPluginLogger } from '../utils/plugin-logger.js';
+
+const log = createPluginLogger({ prefix: '[contract]', forceConsole: false });
+
+interface ApiProbe {
+  name: string;
+  probe: (rt: PluginRuntime) => boolean;
+}
+
+const REQUIRED: ApiProbe[] = [
+  {
+    name: 'channel.reply.dispatchReplyWithBufferedBlockDispatcher',
+    probe: (rt) => typeof (rt as any).channel?.reply?.dispatchReplyWithBufferedBlockDispatcher === 'function',
+  },
+];
+
+const OPTIONAL: ApiProbe[] = [
+  { name: 'channel.inbound.run (degraded)', probe: (rt) => {
+    const c = (rt as any).channel;
+    return typeof c?.inbound?.run === 'function' || typeof c?.turn?.run === 'function';
+  }},
+  { name: 'channel.inbound.buildContext', probe: (rt) => typeof (rt as any).channel?.inbound?.buildContext === 'function' },
+  { name: 'channel.reply.formatAgentEnvelope', probe: (rt) => typeof (rt as any).channel?.reply?.formatAgentEnvelope === 'function' },
+  { name: 'channel.text.chunkMarkdownText', probe: (rt) => typeof (rt as any).channel?.text?.chunkMarkdownText === 'function' },
+  { name: 'channel.routing.resolveAgentRoute', probe: (rt) => typeof (rt as any).channel?.routing?.resolveAgentRoute === 'function' },
+  { name: 'channel.session.resolveStorePath (deprecated)', probe: (rt) => typeof (rt as any).channel?.session?.resolveStorePath === 'function' },
+  { name: 'channel.session.recordInboundSession (deprecated)', probe: (rt) => typeof (rt as any).channel?.session?.recordInboundSession === 'function' },
+  { name: 'channel.reply.finalizeInboundContext (deprecated)', probe: (rt) => typeof (rt as any).channel?.reply?.finalizeInboundContext === 'function' },
+  { name: 'channel.reply.formatInboundEnvelope (deprecated)', probe: (rt) => typeof (rt as any).channel?.reply?.formatInboundEnvelope === 'function' },
+  { name: 'config.current', probe: (rt) => typeof (rt as any).config?.current === 'function' },
+];
+
+export interface ContractResult {
+  ok: boolean;
+  version: string;
+  missing: string[];
+  degraded: string[];
+}
+
+export function verifyRuntimeContract(rt: PluginRuntime): ContractResult {
+  const version = (rt as any).version ?? 'unknown';
+  const missing: string[] = [];
+  const degraded: string[] = [];
+
+  for (const r of REQUIRED) {
+    if (!r.probe(rt)) missing.push(r.name);
+  }
+  for (const r of OPTIONAL) {
+    if (!r.probe(rt)) degraded.push(r.name);
+  }
+
+  log.debug(`openclaw=${version} required=${REQUIRED.length - missing.length}/${REQUIRED.length} degraded=${degraded.length}/${OPTIONAL.length}`);
+  if (missing.length) {
+    log.error(`BROKEN — missing: ${missing.join(', ')}`);
+  }
+  if (degraded.length) {
+    log.debug(`degraded: ${degraded.join(', ')}`);
+  }
+
+  return { ok: missing.length === 0, version, missing, degraded };
+}

package/src/adapter/gateway.ts

@@ -0,0 +1,61 @@
+/**
+ * Gateway Runtime 动态加载（兼容旧版框架）
+ *
+ * openclaw < 3.22 上 gateway-runtime.js 不存在，此函数返回 null。
+ * 审批功能降级为不可用，不影响消息收发等核心能力。
+ */
+import { createRequire } from 'node:module';
+import path from 'node:path';
+
+export interface ApprovalGatewayClient {
+  start: () => void | Promise<void>;
+  stop: () => void | Promise<void>;
+  request: (method: string, params: unknown) => Promise<unknown>;
+}
+
+/** 动态加载 gateway-runtime 模块，旧版框架不可用时返回 null */
+export function loadApprovalGatewayRuntime(): {
+  createOperatorApprovalsGatewayClient: (...args: any[]) => Promise<ApprovalGatewayClient>;
+} | null {
+  const req = createRequire(__filename);
+  const pluginRoot = path.resolve(path.dirname(__filename), '..', '..');
+  const fs = req('node:fs') as typeof import('node:fs');
+
+  const tryLoadFromRoot = (root: string) => {
+    for (const rel of ['dist/plugin-sdk/gateway-runtime.js', 'plugin-sdk/gateway-runtime.js']) {
+      const p = path.join(root, rel);
+      try {
+        if (fs.existsSync(p)) return req(p);
+      } catch { /* try next */ }
+    }
+    return null;
+  };
+
+  try {
+    const { findOpenclawRoot } = req(path.join(pluginRoot, 'scripts', 'link-sdk-core.cjs')) as {
+      findOpenclawRoot: (root: string) => string | null;
+    };
+    const root = findOpenclawRoot(pluginRoot);
+    if (root) {
+      const mod = tryLoadFromRoot(root);
+      if (mod) return mod;
+    }
+  } catch { /* fallback */ }
+
+  try {
+    const entry = process.argv[1];
+    if (entry) {
+      const realEntry = fs.realpathSync(entry);
+      let dir = path.dirname(realEntry);
+      for (let i = 0; i < 6; i++) {
+        const mod = tryLoadFromRoot(dir);
+        if (mod) return mod;
+        const parent = path.dirname(dir);
+        if (parent === dir) break;
+        dir = parent;
+      }
+    }
+  } catch { /* fallback */ }
+
+  return null;
+}

package/src/adapter/index.ts

@@ -0,0 +1,15 @@
+/**
+ * Runtime Adapter — 隔离 OpenClaw 框架 API 变更对插件核心逻辑的冲击。
+ *
+ * 所有 `runtime.channel.*` / `runtime.config.*` 访问 **必须** 经由本模块导出的函数。
+ * 禁止在 adapter/ 外直接使用 `(runtime as any).channel.*`。
+ *
+ * 设计原则：
+ *   1. Capability Probe — 按候选 API 路径探测，兼容多版本框架
+ *   2. Contract Check — 启动时校验必需 API 可用性，fail-fast 暴露问题
+ *   3. 单一 resolve 入口 — 一次 resolve，全程复用缓存
+ */
+
+export { verifyRuntimeContract, type ContractResult } from './contract.js';
+export { resolveRuntimeAdapters, getAdapters, type RuntimeAdapters } from './resolve.js';
+export { loadApprovalGatewayRuntime, type ApprovalGatewayClient } from './gateway.js';

package/src/adapter/lint.ts

@@ -0,0 +1,144 @@
+/**
+ * Lint: 检测 adapter/ 外部直接访问 runtime.channel.* 的代码
+ *
+ * 运行方式：
+ *   npx tsx src/adapter/lint-runtime-access.ts
+ *
+ * 退出码：
+ *   0 = 无违规
+ *   1 = 存在未加白的直接 runtime 访问
+ *
+ * 加白方式（行内注释）：
+ *   // @adapter-bypass: <理由>
+ *
+ * 示例：
+ *   const tts = (runtime as any)?.tts; // @adapter-bypass: TTS 非 channel API，无需经过适配层
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+// ── 配置 ──
+
+const SRC_ROOT = path.resolve(import.meta.dirname, '..');
+const ADAPTER_DIR = path.resolve(SRC_ROOT, 'adapter');
+
+/** 匹配直接使用 runtime.channel / runtime.config / (runtime as any) 的模式 */
+const VIOLATION_PATTERNS: RegExp[] = [
+  /runtime\.channel\b/,
+  /runtime\.config\b/,
+  /\(runtime\s+as\s+any\)/,
+  /channel\??\.(inbound|turn|reply|session|routing|text|media|runtimeContexts)\b/,
+  /config\s+as\s*\{.*writeConfigFile/,
+];
+
+/** 加白注释标记 */
+const BYPASS_MARKER = '@adapter-bypass';
+
+/** 排除的目录/文件 */
+const EXCLUDE_DIRS = ['adapter', 'node_modules', 'dist', 'tests'];
+const EXCLUDE_FILES = ['types.ts', 'types-augment.d.ts', 'openclaw-plugin-sdk.d.ts'];
+
+// ── 扫描逻辑 ──
+
+interface Violation {
+  file: string;
+  line: number;
+  content: string;
+  pattern: string;
+}
+
+function shouldExclude(filePath: string): boolean {
+  const relative = path.relative(SRC_ROOT, filePath);
+  // 排除 adapter 自身
+  if (filePath.startsWith(ADAPTER_DIR)) return true;
+  // 排除配置的目录
+  for (const dir of EXCLUDE_DIRS) {
+    if (relative.startsWith(dir + '/') || relative === dir) return true;
+  }
+  // 排除特定文件
+  const fileName = path.basename(filePath);
+  if (EXCLUDE_FILES.includes(fileName)) return true;
+  return false;
+}
+
+function scanFile(filePath: string): Violation[] {
+  const violations: Violation[] = [];
+  const content = fs.readFileSync(filePath, 'utf8');
+  const lines = content.split('\n');
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const lineNum = i + 1;
+
+    // 跳过注释行（单行注释、JSDoc 行、多行注释体）
+    const trimmed = line.trimStart();
+    if (trimmed.startsWith('//') || trimmed.startsWith('*') || trimmed.startsWith('/**') || trimmed.startsWith('*/')) continue;
+
+    // 检查加白标记
+    if (line.includes(BYPASS_MARKER)) continue;
+
+    // 检查违规模式
+    for (const pattern of VIOLATION_PATTERNS) {
+      if (pattern.test(line)) {
+        violations.push({
+          file: path.relative(SRC_ROOT, filePath),
+          line: lineNum,
+          content: line.trim(),
+          pattern: pattern.source,
+        });
+        break; // 同一行只报一次
+      }
+    }
+  }
+
+  return violations;
+}
+
+function walkDir(dir: string): string[] {
+  const results: string[] = [];
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (!EXCLUDE_DIRS.includes(entry.name)) {
+        results.push(...walkDir(fullPath));
+      }
+    } else if (entry.isFile() && entry.name.endsWith('.ts') && !entry.name.endsWith('.d.ts')) {
+      results.push(fullPath);
+    }
+  }
+  return results;
+}
+
+// ── 主流程 ──
+
+function main(): void {
+  const files = walkDir(SRC_ROOT).filter((f) => !shouldExclude(f));
+  const allViolations: Violation[] = [];
+
+  for (const file of files) {
+    const violations = scanFile(file);
+    allViolations.push(...violations);
+  }
+
+  if (allViolations.length === 0) {
+    console.log('✅ No direct runtime access found outside adapter/');
+    process.exit(0);
+  }
+
+  console.error(`❌ Found ${allViolations.length} direct runtime access violation(s):\n`);
+  for (const v of allViolations) {
+    console.error(`  ${v.file}:${v.line}`);
+    console.error(`    ${v.content}`);
+    console.error(`    → matched: ${v.pattern}`);
+    console.error(`    → fix: use adapter or add "// @adapter-bypass: <reason>"\n`);
+  }
+  console.error(
+    `\nTo bypass a specific line, add an inline comment:\n` +
+    `  // @adapter-bypass: <reason why this cannot go through the adapter>\n`,
+  );
+  process.exit(1);
+}
+
+main();

package/src/adapter/media.ts

@@ -0,0 +1,112 @@
+/**
+ * 远程媒体下载（动态加载 plugin-sdk/media-runtime，降级到 fetch）
+ *
+ * 新版本 openclaw 有 openclaw/plugin-sdk/media-runtime（含 SSRF 防护/重试/大小限制），
+ * 旧版本不可用时降级到原生 fetch 直连。
+ */
+import { createRequire } from 'node:module';
+import * as dns from 'node:dns';
+import * as path from 'node:path';
+import * as fs from 'node:fs';
+import * as crypto from 'node:crypto';
+import { getQQBotMediaDir } from '../utils/platform.js';
+
+const req = createRequire(__filename);
+
+type SaveRemoteMedia = (opts: {
+  url: string;
+  subdir?: string;
+  originalFilename?: string;
+  maxBytes?: number;
+  timeoutMs?: number;
+}) => Promise<{ path: string }>;
+
+let _save: SaveRemoteMedia | null | undefined;
+
+export function downloadRemoteMedia(opts: {
+  url: string;
+  subdir?: string;
+  originalFilename?: string;
+  maxBytes?: number;
+  timeoutMs?: number;
+}): Promise<{ path: string }> {
+  if (_save === undefined) {
+    try {
+      const mod = req('openclaw/plugin-sdk/media-runtime') as { saveRemoteMedia: SaveRemoteMedia };
+      _save = mod.saveRemoteMedia;
+    } catch {
+      _save = null;
+    }
+  }
+  return _save ? _save(opts) : downloadViaFetch(opts);
+}
+
+// ── SSRF 防护 ──
+
+const PRIVATE_RANGES: Array<[netmask: bigint, prefix: number]> = [
+  [0x0A000000n, 8],      // 10.0.0.0/8
+  [0xAC100000n, 12],     // 172.16.0.0/12
+  [0xC0A80000n, 16],     // 192.168.0.0/16
+  [0x7F000000n, 8],      // 127.0.0.0/8
+  [0xA9FE0000n, 16],     // 169.254.0.0/16
+  [0xE0000000n, 4],      // 224.0.0.0/4 (multicast)
+];
+
+function ipToBigInt(ip: string): bigint {
+  return ip.split('.').reduce((acc, octet) => (acc << 8n) | BigInt(Number(octet)), 0n);
+}
+
+function isPrivateIP(ip: string): boolean {
+  const val = ipToBigInt(ip);
+  return PRIVATE_RANGES.some(([mask, prefix]) => (val >> (32n - BigInt(prefix))) === (mask >> (32n - BigInt(prefix))));
+}
+
+async function assertSafeHostname(hostname: string): Promise<void> {
+  const addresses = await dns.promises.resolve4(hostname).catch(() => []);
+  if (addresses.length === 0) throw new Error(`DNS resolution failed: ${hostname}`);
+  for (const addr of addresses) {
+    if (isPrivateIP(addr)) {
+      throw new Error(`SSRF blocked: ${hostname} resolves to private IP ${addr}`);
+    }
+  }
+}
+
+// ── 降级 fetch ──
+
+/** 降级：原生 fetch 直连（含 SSRF 防护、大小限制） */
+async function downloadViaFetch(opts: {
+  url: string;
+  subdir?: string;
+  originalFilename?: string;
+  maxBytes?: number;
+  timeoutMs?: number;
+}): Promise<{ path: string }> {
+  const parsed = new URL(opts.url);
+  if (parsed.protocol !== 'https:') {
+    throw new Error(`Only HTTPS allowed: ${parsed.protocol}`);
+  }
+  await assertSafeHostname(parsed.hostname);
+
+  const dir = getQQBotMediaDir(opts.subdir ?? 'downloads');
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+
+  const resp = await fetch(opts.url, {
+    signal: AbortSignal.timeout(opts.timeoutMs ?? 120_000),
+  });
+  if (!resp.ok) throw new Error(`Download HTTP ${resp.status}`);
+
+  const maxBytes = opts.maxBytes ?? 500 * 1024 * 1024;
+  const buf = Buffer.from(await resp.arrayBuffer());
+  if (buf.length > maxBytes) throw new Error(`Download exceeds ${(maxBytes / 1024 / 1024).toFixed(0)}MB`);
+
+  const ext = opts.originalFilename
+    ? path.extname(opts.originalFilename) || '.bin'
+    : '.bin';
+  const name = opts.originalFilename
+    ? path.basename(opts.originalFilename, path.extname(opts.originalFilename))
+    : 'download';
+  const rand = crypto.randomBytes(4).toString('hex');
+  const filePath = path.join(dir, `${name}_${Date.now()}_${rand}${ext}`);
+  fs.writeFileSync(filePath, buf);
+  return { path: filePath };
+}

package/src/adapter/pairing.ts

@@ -0,0 +1,99 @@
+/**
+ * Pairing Runtime 动态加载（兼容旧版框架）
+ *
+ * 从 OpenClaw 安装目录动态加载 conversation-runtime 模块中的配对函数。
+ * 不支持时返回 null，配对功能降级为不可用。
+ */
+import { createRequire } from 'node:module';
+import path from 'node:path';
+
+export interface PairingApi {
+  readAllowFromStore: (params: { channel: string; accountId: string }) => Promise<string[]>;
+  issueChallenge: (params: { channel: string; id: string; accountId: string }) => Promise<{ code: string }>;
+  buildReply: (params: { code: string; channel: string }) => string;
+  approveCode: (params: { channel: string; code: string; accountId?: string }) => Promise<{ id: string } | null>;
+}
+
+let _api: PairingApi | null | undefined;
+
+/** 获取 Pairing API，首次调用触发加载并缓存 */
+export function getPairingApi(): PairingApi | null {
+  if (_api !== undefined) return _api;
+  _api = loadPairingApi();
+  return _api;
+}
+
+function loadPairingApi(): PairingApi | null {
+  const currentFile = __filename;
+  const req = createRequire(currentFile);
+  const pluginRoot = path.resolve(path.dirname(currentFile), '..', '..');
+  const fs = req('node:fs') as typeof import('node:fs');
+
+  const tryLoad = (root: string) => {
+    for (const rel of ['dist/plugin-sdk/conversation-runtime.js', 'plugin-sdk/conversation-runtime.js']) {
+      const p = path.join(root, rel);
+      try {
+        if (fs.existsSync(p)) return req(p);
+      } catch { /* try next */ }
+    }
+    return null;
+  };
+
+  let mod: any = null;
+  try {
+    const { findOpenclawRoot } = req(path.join(pluginRoot, 'scripts', 'link-sdk-core.cjs')) as {
+      findOpenclawRoot: (root: string) => string | null;
+    };
+    const root = findOpenclawRoot(pluginRoot);
+    if (root) mod = tryLoad(root);
+  } catch { /* fallback */ }
+
+  if (!mod) {
+    try {
+      const entry = process.argv[1];
+      if (entry) {
+        const realEntry = fs.realpathSync(entry);
+        let dir = path.dirname(realEntry);
+        for (let i = 0; i < 6; i++) {
+          mod = tryLoad(dir);
+          if (mod) break;
+          const parent = path.dirname(dir);
+          if (parent === dir) break;
+          dir = parent;
+        }
+      }
+    } catch { /* fallback */ }
+  }
+
+  if (!mod?.readChannelAllowFromStore) return null;
+
+  return {
+    // readChannelAllowFromStore(channel, env?, accountId?) — 位置参数
+    readAllowFromStore: (params) =>
+      mod.readChannelAllowFromStore(params.channel, undefined, params.accountId),
+
+    // upsertChannelPairingRequest({ channel, id, accountId }) — 对象参数
+    issueChallenge: (params) =>
+      mod.upsertChannelPairingRequest({
+        channel: params.channel,
+        id: params.id,
+        accountId: params.accountId,
+      }).then((r: any) => ({ code: r.code as string })),
+
+    // buildPairingReply({ channel, idLine, code }) — 对象参数
+    buildReply: (params) =>
+      mod.buildPairingReply({
+        channel: params.channel,
+        idLine: '', // qqbot 无额外 ID 信息，留空即可
+        code: params.code,
+      }),
+
+    // approveChannelPairingCode({ channel, code, accountId? }) — 对象参数
+    approveCode: (params) =>
+      mod.approveChannelPairingCode({
+        channel: params.channel,
+        code: params.code,
+        accountId: params.accountId,
+      }),
+  };
+}