@tencent-connect/openclaw-qqbot 1.7.2 → 2.0.0

package/src/adapter/resolve.ts

@@ -0,0 +1,333 @@
+/**
+ * Runtime Adapters — 一次 resolve，全程复用。
+ *
+ * Capability Probe 模式：按候选 API 路径探测，选出第一个可用函数。
+ * 对每个 runtime API 维护一个"候选列表"（最新在前），未来 API 改名时只需 +1 行。
+ *
+ * 调用方通过 `resolveRuntimeAdapters(runtime)` 获取适配层对象，
+ * 后续所有 dispatch / channel 代码只使用 adapters 上的方法。
+ */
+
+import type { PluginRuntime } from 'openclaw/plugin-sdk';
+import type { PluginLogger } from '../utils/plugin-logger.js';
+
+// ── 类型 ──
+
+export interface RuntimeAdapters {
+  /** 入站事件处理（自动适配 inbound.run / turn.run） */
+  inboundRun: ((params: any) => Promise<any>) | null;
+  /** 回复分发（带 block buffer） */
+  dispatchReply: ((params: any) => Promise<any>) | null;
+  /** Agent 路由解析 */
+  resolveAgentRoute: ((params: any) => any) | null;
+  /** 构建入站上下文（自动适配 inbound.buildContext / reply.finalizeInboundContext） */
+  buildInboundContext: ((params: any) => any) | null;
+  /** Session store path 解析 */
+  resolveStorePath: ((storeConfig: any, opts: any) => string) | null;
+  /** Session 记录 */
+  recordInboundSession: ((params: any) => Promise<void>) | null;
+  /** 格式化 envelope（自动适配 formatAgentEnvelope / formatInboundEnvelope） */
+  formatEnvelope: ((params: any) => string) | null;
+  /** 解析 envelope format options */
+  resolveEnvelopeFormatOptions: ((cfg: any) => any) | null;
+  /** Markdown 文本分块 */
+  chunkMarkdownText: ((text: string, limit: number) => string[]) | null;
+  /** 远程媒体保存（图片/语音下载） */
+  saveRemoteMedia: ((opts: { url: string; subdir?: string; originalFilename?: string }) => Promise<{ path: string } | null>) | null;
+  /** 获取当前配置快照 */
+  getConfig: (() => any) | null;
+  /**
+   * 持久化配置变更（高低版本兼容）。
+   *
+   * 内部优先级：
+   *   1. mutateConfigFile（新版 API，原子操作，支持 afterWrite 策略）
+   *   2. writeConfigFile（旧版 API，整体覆盖）
+   *
+   * 调用方只需传入完整 config 对象，不必关心框架版本差异。
+   */
+  /**
+   * 持久化配置变更（高低版本兼容）。
+   *
+   * 接受一个 mutator 回调，接收当前 config 对象（可变），
+   * 可直接修改或返回新对象。适配器负责确保写入和热重载。
+   */
+  persistConfig: ((mutator: (cfg: any) => any) => Promise<void>) | null;
+  /** openclaw 版本 */
+  version: string;
+}
+
+// ── Probe 辅助 ──
+
+type ProbePath = string[];
+
+/**
+ * 从 runtime 对象沿路径探测函数。返回 bound function 或 null。
+ */
+function probeFunction(rt: any, paths: ProbePath[]): ((...args: any[]) => any) | null {
+  for (const path of paths) {
+    let target = rt;
+    let parent = rt;
+    for (let i = 0; i < path.length; i++) {
+      parent = target;
+      target = target?.[path[i]];
+      if (target === undefined || target === null) break;
+    }
+    if (typeof target === 'function') {
+      // bind 到 parent（倒数第二层），确保 this 上下文正确
+      return target.bind(parent);
+    }
+  }
+  return null;
+}
+
+/**
+ * 从 runtime 对象沿路径探测值（非函数也可）。返回值或 null。
+ */
+function probeValue(rt: any, paths: ProbePath[]): any {
+  for (const path of paths) {
+    let target = rt;
+    for (const key of path) {
+      target = target?.[key];
+      if (target === undefined || target === null) break;
+    }
+    if (target !== undefined && target !== null) return target;
+  }
+  return null;
+}
+
+// ── 主入口 ──
+
+/**
+ * 一次性 resolve 所有 runtime adapter。
+ *
+ * 通常在 gateway ready 后（首条消息到来前）调用一次，结果缓存复用。
+ * 返回 null 的字段表示该能力不可用，调用方按需降级或走 fallback。
+ */
+export function resolveRuntimeAdapters(
+  rt: PluginRuntime,
+  log?: PluginLogger,
+): RuntimeAdapters {
+  const version = (rt as any).version ?? 'unknown';
+
+  const inboundRun = probeFunction(rt, [
+    ['channel', 'inbound', 'run'],      // current (2026-05+)
+    ['channel', 'turn', 'run'],          // legacy (removed 2026-05-27)
+  ]);
+
+  const dispatchReply = probeFunction(rt, [
+    ['channel', 'reply', 'dispatchReplyWithBufferedBlockDispatcher'],
+  ]);
+
+  const resolveAgentRoute = probeFunction(rt, [
+    ['channel', 'routing', 'resolveAgentRoute'],
+  ]);
+
+  // 构建入站上下文：新 API 优先，低版本 fallback 到 deprecated finalizeInboundContext
+  // 两个 API 签名不同，通过 wrapper 统一为 buildInboundContext(params) 接口
+  const rawBuildContext = probeFunction(rt, [
+    ['channel', 'inbound', 'buildContext'],
+  ]);
+  const rawFinalizeContext = !rawBuildContext
+    ? probeFunction(rt, [['channel', 'reply', 'finalizeInboundContext']])
+    : null;
+
+  const buildInboundContext: RuntimeAdapters['buildInboundContext'] = rawBuildContext
+    ? (params) => rawBuildContext(params)
+    : rawFinalizeContext
+      ? (params) => {
+          // 将统一参数转换为旧 API 的 rawCtxPayload 格式
+          const isCommand = params.access?.commands?.authorized ?? false;
+          const rawCtx = {
+            Body: params.message.body,
+            BodyForAgent: params.message.bodyForAgent,
+            RawBody: params.message.rawBody,
+            CommandBody: params.message.commandBody ?? params.message.rawBody,
+            CommandSource: isCommand ? 'text' : undefined,
+            CommandTurn: params.command ?? undefined,
+            CommandAuthorized: isCommand,
+            From: params.from,
+            To: params.reply.to,
+            SessionKey: params.route.routeSessionKey,
+            AccountId: params.route.accountId ?? params.accountId,
+            ChatType: params.conversation.kind,
+            GroupSystemPrompt: params.conversation.label,
+            SenderId: params.sender.id,
+            SenderName: params.sender.name,
+            Provider: params.provider ?? params.channel,
+            Surface: params.surface ?? params.channel,
+            MessageSid: params.messageId,
+            Timestamp: params.timestamp ?? Date.now(),
+            OriginatingChannel: params.channel,
+            OriginatingTo: params.reply.originatingTo ?? params.reply.to,
+            ...params.extra,
+          };
+          return rawFinalizeContext(rawCtx);
+        }
+      : null;
+
+  const resolveStorePath = probeFunction(rt, [
+    ['channel', 'session', 'resolveStorePath'],
+  ]);
+
+  const recordInboundSession = probeFunction(rt, [
+    ['channel', 'session', 'recordInboundSession'],
+  ]);
+
+  // 格式化 envelope：新 API 优先，低版本 fallback 到 deprecated formatInboundEnvelope
+  const formatEnvelope = probeFunction(rt, [
+    ['channel', 'reply', 'formatAgentEnvelope'],    // current (2026-06+)
+    ['channel', 'reply', 'formatInboundEnvelope'],  // deprecated，低版本兼容
+  ]);
+
+  const resolveEnvelopeFormatOptions = probeFunction(rt, [
+    ['channel', 'reply', 'resolveEnvelopeFormatOptions'],
+  ]);
+
+  const chunkMarkdownText = probeFunction(rt, [
+    ['channel', 'text', 'chunkMarkdownText'],
+  ]);
+
+  const saveRemoteMedia = probeFunction(rt, [
+    ['channel', 'media', 'saveRemoteMedia'],
+  ]);
+
+  const getConfig = probeFunction(rt, [
+    ['config', 'current'],
+  ]) ?? probeFunction(rt, [
+    ['getConfig'],
+  ]) ?? probeFunction(rt, [
+    ['config', 'loadConfig'],
+  ]);
+
+  // config 持久化：优先 mutateConfigFile（新版，原子操作），fallback writeConfigFile（旧版）
+  const rawMutateConfig = probeFunction(rt, [['config', 'mutateConfigFile']]);
+  const rawWriteConfig = probeFunction(rt, [['config', 'writeConfigFile']]);
+
+  const persistConfig: RuntimeAdapters['persistConfig'] = rawMutateConfig
+    ? async (mutator: (cfg: any) => any) => {
+        // 新版 API：mutate 回调接收当前 config，可直接修改或返回新对象
+        await rawMutateConfig({
+          afterWrite: 'hot-reload',
+          mutate: mutator,
+        });
+      }
+    : rawWriteConfig && getConfig
+      ? async (mutator: (cfg: any) => any) => {
+          // 旧版 API：先读取当前 config → 应用 mutator → 整体写入
+          const current = JSON.parse(JSON.stringify(getConfig()));
+          mutator(current);
+          await rawWriteConfig(current);
+        }
+      : null;
+
+  // 日志汇总
+  const resolved = [
+    inboundRun && 'inboundRun',
+    dispatchReply && 'dispatchReply',
+    resolveAgentRoute && 'resolveAgentRoute',
+    buildInboundContext && 'buildInboundContext',
+    resolveStorePath && 'resolveStorePath',
+    recordInboundSession && 'recordInboundSession',
+    formatEnvelope && 'formatEnvelope',
+    chunkMarkdownText && 'chunkMarkdownText',
+    saveRemoteMedia && 'saveRemoteMedia',
+    getConfig && 'getConfig',
+    persistConfig && `persistConfig(${rawMutateConfig ? 'mutate' : 'write'})`,
+  ].filter(Boolean);
+
+  log?.info(
+    `[qqbot:adapter] openclaw=${version} resolved ${resolved.length} adapters: ${resolved.join(', ')}`,
+  );
+
+  return {
+    inboundRun,
+    dispatchReply,
+    resolveAgentRoute,
+    buildInboundContext,
+    resolveStorePath,
+    recordInboundSession,
+    formatEnvelope,
+    resolveEnvelopeFormatOptions,
+    chunkMarkdownText,
+    saveRemoteMedia,
+    getConfig,
+    persistConfig,
+    version,
+  };
+}
+
+// ── 全局缓存（所有消费者共享同一份 adapters） ──
+
+let _cachedAdapters: RuntimeAdapters | null = null;
+let _cachedRuntimeRef: WeakRef<PluginRuntime> | null = null;
+
+/**
+ * 获取 RuntimeAdapters 的全局缓存版本。
+ *
+ * - 自动基于 runtime 实例的 WeakRef 判断是否需要重新 resolve
+ * - 如果 runtime 被替换（框架热更新、二次 register），自动刷新
+ * - 所有消费者（dispatch / channel / middleware）共用一份，避免重复 probe
+ *
+ * @param rt 当前 PluginRuntime 实例
+ * @param log 可选日志（仅在首次 resolve 或 runtime 变更时输出）
+ */
+export function getAdapters(
+  rt: PluginRuntime,
+  log?: PluginLogger,
+): RuntimeAdapters {
+  const cached = _cachedRuntimeRef?.deref();
+  if (cached === rt && _cachedAdapters) {
+    return _cachedAdapters;
+  }
+  // runtime 引用变化（首次 / 热更新）→ 重新 resolve
+  _cachedAdapters = resolveRuntimeAdapters(rt, log);
+  _cachedRuntimeRef = new WeakRef(rt);
+  return _cachedAdapters;
+}
+
+/**
+ * 持久化配置（auth.login 场景，兼容高低版本）。
+ *
+ * 探测顺序：
+ *   1. config.mutateConfigFile  — 新版原子操作
+ *   2. config.writeConfigFile   — 旧版整体覆盖
+ *   3. writeConfigFile          — 更旧的顶层 API
+ */
+export async function persistAuthConfig(
+  runtime: Record<string, unknown>,
+  cfg: Record<string, unknown>,
+  afterWrite = 'restart',
+): Promise<void> {
+  const config: Record<string, unknown> | undefined = runtime.config as any;
+
+  if (typeof config?.mutateConfigFile === 'function') {
+    await (config.mutateConfigFile as Function)({
+      mutate: () => cfg,
+      afterWrite,
+    });
+    return;
+  }
+  if (typeof config?.writeConfigFile === 'function') {
+    await (config.writeConfigFile as Function)(cfg);
+    return;
+  }
+  if (typeof runtime.writeConfigFile === 'function') {
+    await (runtime.writeConfigFile as Function)(cfg);
+    return;
+  }
+
+  // 最后兜底：裸写文件
+  const { homedir } = await import('node:os');
+  const { join } = await import('node:path');
+  const { writeFileSync } = await import('node:fs');
+  writeFileSync(join(homedir(), '.openclaw', 'openclaw.json'), JSON.stringify(cfg, null, 2) + '\n', 'utf-8');
+}
+
+/**
+ * 强制清除 adapter 缓存（仅测试用）
+ */
+export function _resetAdaptersCache(): void {
+  _cachedAdapters = null;
+  _cachedRuntimeRef = null;
+}
+

package/src/adapter/setup.ts

@@ -0,0 +1,55 @@
+/**
+ * Setup 工具动态加载（plugin-sdk/setup + plugin-sdk/setup-tools）
+ *
+ * 新版本 openclaw 有这些导出，旧版本可能缺失。
+ * 不可用时提供最小降级实现。
+ */
+import { createRequire } from 'node:module';
+
+const req = createRequire(__filename);
+
+let _setup: typeof import('openclaw/plugin-sdk/setup') | null | undefined;
+let _tools: typeof import('openclaw/plugin-sdk/setup-tools') | null | undefined;
+
+function loadSetup() {
+  if (_setup !== undefined) return _setup;
+  try { _setup = req('openclaw/plugin-sdk/setup'); } catch { _setup = null; }
+  return _setup;
+}
+
+function loadTools() {
+  if (_tools !== undefined) return _tools;
+  try { _tools = req('openclaw/plugin-sdk/setup-tools'); } catch { _tools = null; }
+  return _tools;
+}
+
+export type { ChannelSetupWizard } from 'openclaw/plugin-sdk/setup';
+
+export const DEFAULT_ACCOUNT_ID = 'default';
+
+export function createStandardChannelSetupStatus(
+  ...args: Parameters<NonNullable<typeof _setup>['createStandardChannelSetupStatus']>
+): ReturnType<NonNullable<typeof _setup>['createStandardChannelSetupStatus']> {
+  const mod = loadSetup();
+  if (mod) return mod.createStandardChannelSetupStatus(...args);
+  return {
+    channelLabel: args[0]?.channelLabel ?? 'QQ Bot',
+    configuredLabel: 'Configured',
+    unconfiguredLabel: 'Not configured',
+    resolveConfigured: () => false,
+  } as unknown as ReturnType<NonNullable<typeof _setup>['createStandardChannelSetupStatus']>;
+}
+
+export function setSetupChannelEnabled(
+  ...args: Parameters<NonNullable<typeof _setup>['setSetupChannelEnabled']>
+): void {
+  loadSetup()?.setSetupChannelEnabled?.(...args);
+}
+
+export function formatDocsLink(
+  ...args: Parameters<NonNullable<typeof _tools>['formatDocsLink']>
+): ReturnType<NonNullable<typeof _tools>['formatDocsLink']> {
+  const mod = loadTools();
+  if (mod) return mod.formatDocsLink(...args);
+  return (args[1] ? `${args[1]}: ${args[0]}` : args[0]) as ReturnType<NonNullable<typeof _tools>['formatDocsLink']>;
+}

package/src/adapter/webhook.ts

@@ -0,0 +1,248 @@
+/**
+ * PluginWebhookAdapter — 将 OpenClaw Gateway HTTP 路由适配为 SDK WebhookServerAdapter。
+ *
+ * 复用 openclaw/plugin-sdk/webhook-ingress 的 target registry、rate limiting 和
+ * resolveWebhookTargetWithAuthOrRejectSync 签名匹配，对齐旧版本插件行为。
+ *
+ * 多账号同路径：通过 resolveWebhookTargetWithAuthOrRejectSync 遍历 targets 做
+ * Ed25519 签名匹配，找到正确的 target 后调用其 SDK handler 处理事件。
+ */
+import type { ResolvedQQBotAccount } from '../types.js';
+import type { PluginLogger } from '../utils/plugin-logger.js';
+import type { WebhookServerAdapter, WebhookRequestHandler } from '@tencent-connect/qqbot-nodejs';
+import { verifyWebhookSignature } from '@tencent-connect/qqbot-nodejs/protocol';
+
+// ── 模块级共享状态 ──
+interface WebhookTarget {
+  path: string;
+  accountId: string;
+  appId: string;
+  clientSecret: string;
+  handler: WebhookRequestHandler;
+}
+const sharedTargets = new Map<string, WebhookTarget[]>();
+const _routeUnregisters = new Map<string, () => void>();
+
+export function createPluginWebhookAdapter(params: {
+  account: ResolvedQQBotAccount;
+  log: PluginLogger;
+}): WebhookServerAdapter {
+  let unregistered = false;
+  let storedPath = '';
+  const accountId = params.account.accountId;
+
+  return {
+    async listen(_port: number, path: string, handler: WebhookRequestHandler): Promise<void> {
+      const ingress = await import('openclaw/plugin-sdk/webhook-ingress').catch(() => null);
+      if (!ingress?.registerWebhookTargetWithPluginRoute) {
+        params.log.error('Webhook ingress not available');
+        return;
+      }
+
+      const webhookPath = storedPath = path && path !== '/' ? path : (params.account.config.webhook?.path ?? '/qqbot/webhook');
+
+      // 去重：reload 时避免同一 accountId 重复注册
+      const existing = sharedTargets.get(webhookPath);
+      if (existing) {
+        const dupIdx = existing.findIndex((t) => t.accountId === accountId);
+        if (dupIdx >= 0) {
+          existing[dupIdx] = { path: webhookPath, accountId, appId: params.account.appId, clientSecret: params.account.clientSecret, handler };
+          params.log.info(`Webhook target refreshed for ${accountId} on ${webhookPath}`);
+          return;
+        }
+      }
+
+      // 注册 target（框架管理 targetsByPath + 首次触发路由注册）
+      const target: WebhookTarget = {
+        path: webhookPath,
+        accountId,
+        appId: params.account.appId,
+        clientSecret: params.account.clientSecret,
+        handler,
+      };
+
+      const result = ingress.registerWebhookTargetWithPluginRoute({
+        targetsByPath: sharedTargets as any,
+        target,
+        route: {
+          auth: 'plugin',
+          match: 'exact',
+          pluginId: 'openclaw-qqbot',
+          source: 'qqbot-webhook',
+          accountId,
+          replaceExisting: true,
+          log: (msg: string) => params.log.info(msg),
+          handler: createSharedHandler(webhookPath, params.log),
+        },
+        onLastPathTargetRemoved: () => {
+          params.log.info(`Last webhook target removed from ${webhookPath}`);
+        },
+      });
+      _routeUnregisters.set(webhookPath, result.unregister);
+
+      params.log.info(`Webhook target added on ${webhookPath} (${sharedTargets.get(webhookPath)!.length} account(s))`);
+    },
+
+    close(): void {
+      if (unregistered) return;
+      unregistered = true;
+      if (storedPath) {
+        _routeUnregisters.get(storedPath)?.();
+        _routeUnregisters.delete(storedPath);
+      }
+    },
+  };
+}
+
+function createSharedHandler(path: string, log: PluginLogger) {
+  return async (req: any, res: any) => {
+    try {
+      const ingress = await import('openclaw/plugin-sdk/webhook-ingress').catch(() => null);
+
+      if (!ingress?.withResolvedWebhookRequestPipeline) {
+        await handleSimple(req, res, path, log);
+        return;
+      }
+
+      await ingress.withResolvedWebhookRequestPipeline({
+        req,
+        res,
+        targetsByPath: sharedTargets,
+        rateLimiter: ingress.createFixedWindowRateLimiter?.({
+          windowMs: 60_000, maxRequests: 600, maxTrackedKeys: 4096,
+        }),
+        inFlightLimiter: ingress.createWebhookInFlightLimiter?.({
+          maxInFlightPerKey: 8, maxTrackedKeys: 4096,
+        }),
+        requireJsonContentType: true,
+        handle: async ({ targets }) => {
+          const bodyResult = await ingress.readWebhookBodyOrReject({
+            req, res, maxBytes: 1_048_576, timeoutMs: 30_000,
+          });
+          if (!bodyResult.ok) {
+            log.warn?.(`[webhook] body rejected`);
+            return;
+          }
+
+          const rawBody = Buffer.from(bodyResult.value, 'utf-8');
+
+          let payload: any;
+          try { payload = JSON.parse(bodyResult.value); } catch (err) {
+            log.warn?.(`[webhook] invalid json: ${(err as Error).message}`);
+            res.statusCode = 400; res.end(JSON.stringify({ error: 'invalid json' })); return;
+          }
+
+          // op:13 → 用第一个 target 的 SDK handler（无需签名）
+          if (payload.op === 13) {
+            const t = targets[0];
+            if (!t) {
+              log.warn?.(`[webhook] op:13 no target on ${path}`);
+              res.statusCode = 500; res.end(JSON.stringify({ error: 'no target' })); return;
+            }
+            const h = resolveTargetHandler(path, t.accountId);
+            if (!h) {
+              log.warn?.(`[webhook] op:13 no handler for ${t.accountId}`);
+              res.statusCode = 500; res.end(JSON.stringify({ error: 'no handler' })); return;
+            }
+            await delegateToHandler(h, req, res, rawBody);
+            return;
+          }
+
+          // op:0 → 签名匹配 target → SDK handler 处理事件
+          const timestamp = getHeader(req, 'x-signature-timestamp') ?? '';
+          const signature = getHeader(req, 'x-signature-ed25519') ?? '';
+          if (!timestamp || !signature) {
+            log.warn?.(`[webhook] missing signature headers on ${req.url}`);
+            res.statusCode = 401; res.end(JSON.stringify({ error: 'missing signature' })); return;
+          }
+
+          const matched = ingress.resolveWebhookTargetWithAuthOrRejectSync({
+            targets, res,
+            isMatch: (t: any) => verifyWebhookSignature({
+              body: rawBody, timestamp, signature, botSecret: t.clientSecret as string,
+            }),
+            unauthorizedStatusCode: 401,
+            unauthorizedMessage: JSON.stringify({ error: 'invalid signature' }),
+          });
+          if (!matched) {
+            log.warn?.(`[webhook] signature mismatch on ${path} (${targets.length} target(s))`);
+            return;
+          }
+
+          const h = resolveTargetHandler(path, matched.accountId);
+          if (!h) {
+            log.error?.(`[webhook] no handler for matched target ${matched.accountId}`);
+            res.statusCode = 500; res.end(JSON.stringify({ error: 'no handler' })); return;
+          }
+          await delegateToHandler(h, req, res, rawBody);
+        },
+      });
+    } catch (err) {
+      log.error(`Webhook handler error: ${(err as Error).message}`);
+      if (!res.headersSent) {
+        res.statusCode = 500;
+        res.setHeader('Content-Type', 'application/json');
+        res.end(JSON.stringify({ error: 'internal error' }));
+      }
+    }
+  };
+}
+
+function resolveTargetHandler(path: string, accountId: string): WebhookRequestHandler | undefined {
+  return sharedTargets.get(path)?.find((t) => t.accountId === accountId)?.handler;
+}
+
+async function delegateToHandler(handler: WebhookRequestHandler, req: any, res: any, rawBody: Buffer) {
+  const headers: Record<string, string | string[]> = {};
+  for (const [k, v] of Object.entries(req.headers)) {
+    headers[k.toLowerCase()] = v as string | string[];
+  }
+  const resp = await handler({ body: rawBody, headers });
+  res.statusCode = resp.status;
+  if (resp.headers) {
+    for (const [k, v] of Object.entries(resp.headers)) res.setHeader(k, v as string);
+  }
+  res.end(resp.body);
+}
+
+async function handleSimple(req: any, res: any, path: string, log: PluginLogger) {
+  try {
+    const ct = String(req.headers['content-type'] ?? '');
+    if (!ct.includes('application/json')) { res.statusCode = 400; res.end(JSON.stringify({ error: 'unsupported content type' })); return; }
+
+    const chunks: Buffer[] = [];
+    let total = 0;
+    for await (const chunk of req) {
+      const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+      total += buf.length;
+      if (total > 1_048_576) { res.statusCode = 413; res.end(JSON.stringify({ error: 'too large' })); return; }
+      chunks.push(buf);
+    }
+    const rawBody = Buffer.concat(chunks);
+    const entries = sharedTargets.get(path) ?? [];
+    for (const entry of entries) {
+      const resp = await entry.handler({ body: rawBody, headers: mapHeaders(req) });
+      if (resp.status < 400) {
+        res.statusCode = resp.status;
+        if (resp.headers) for (const [k, v] of Object.entries(resp.headers)) res.setHeader(k, v as string);
+        res.end(resp.body);
+        return;
+      }
+    }
+    res.statusCode = 401; res.end(JSON.stringify({ error: 'invalid signature' }));
+  } catch (err) {
+    log.error(`Webhook simple handler error: ${(err as Error).message}`);
+    if (!res.headersSent) { res.statusCode = 500; res.end(JSON.stringify({ error: 'internal error' })); }
+  }
+}
+
+function mapHeaders(req: any): Record<string, string | string[]> {
+  const h: Record<string, string | string[]> = {};
+  for (const [k, v] of Object.entries(req.headers ?? {})) h[k.toLowerCase()] = v as string | string[];
+  return h;
+}
+
+function getHeader(req: any, key: string): string | undefined {
+  const val = req.headers[key];
+  return Array.isArray(val) ? val[0] : val;
+}

package/src/adapter/workspace.ts

@@ -0,0 +1,29 @@
+/**
+ * Agent workspace 目录解析（动态加载 plugin-sdk/health）
+ *
+ * 新版本 openclaw 有 openclaw/plugin-sdk/health 导出，
+ * 旧版本不可用时 fallback 到 QQ Bot media 目录。
+ */
+import { createRequire } from 'node:module';
+import { getQQBotMediaDir } from '../utils/platform.js';
+
+const req = createRequire(__filename);
+
+let health: {
+  resolveAgentWorkspaceDir: (cfg: any, agentId: string) => string;
+  resolveDefaultAgentId: (cfg: any) => string;
+} | null = null;
+
+export function resolveAgentWorkspace(cfg: any, agentId?: string): string {
+  if (!health) {
+    try {
+      health = req('openclaw/plugin-sdk/health') as typeof health;
+    } catch {
+      health = null;
+    }
+  }
+  if (health) {
+    return health.resolveAgentWorkspaceDir(cfg, agentId ?? health.resolveDefaultAgentId(cfg));
+  }
+  return getQQBotMediaDir();
+}