ylib-syim 0.0.1

package/scripts/build-bridge.mjs

@@ -0,0 +1,36 @@
+/**
+ * 钉钉桥接 esbuild 打包：
+ * - 默认：重型依赖外置 + minify，cjs 约 200KB+（未压缩源码约 400KB+）。
+ * - --all：全部打入单文件（~13MB → minify 后明显变小）。
+ * - --no-minify：便于对照报错行号（体积变大）。
+ */
+import * as esbuild from "esbuild";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const root = path.join(__dirname, "..");
+
+/** 与 dingtalk-openclaw-connector 中重型依赖对齐；运行时必须存在于 node_modules */
+const RUNTIME_EXTERNALS = [
+  "dingtalk-stream",
+  "pdf-parse",
+  "mammoth",
+  "fluent-ffmpeg",
+  "@ffmpeg-installer/ffmpeg",
+  "axios",
+];
+
+const all = process.argv.includes("--all");
+const noMinify = process.argv.includes("--no-minify");
+
+await esbuild.build({
+  entryPoints: [path.join(root, "scripts/dingtalk-stdio-bridge.ts")],
+  bundle: true,
+  platform: "node",
+  format: "cjs",
+  outfile: path.join(root, "dist/dingtalk-stdio-bridge.cjs"),
+  external: all ? [] : RUNTIME_EXTERNALS,
+  minify: !noMinify,
+  logLevel: "info",
+});

package/scripts/dev-server.ts

@@ -0,0 +1,53 @@
+/**
+ * 本地测试用开发服务器：接收 HTTP POST 的 InboundMessage，经 Hub 处理后由钉钉适配器回发到钉钉。
+ * 使用可复用的 createInboundServer；可选文件 Session 持久化（PERSIST_SESSIONS=1 或 SESSION_DIR）。
+ *
+ * 使用方式：
+ *   DINGTALK_CLIENT_ID=xxx DINGTALK_CLIENT_SECRET=yyy pnpm run dev
+ *   PERSIST_SESSIONS=1 或 SESSION_DIR=/path/to/sessions 启用会话落盘
+ */
+
+import {
+  createHub,
+  createDingTalkAdapter,
+  createRuleBasedRouter,
+  createInMemorySessionStore,
+  createFileSessionStore,
+  createLangChainLikeAgent,
+  startInboundServer,
+} from "../src/index.js";
+
+const PORT = Number(process.env.PORT) || 3100;
+
+const clientId = process.env.DINGTALK_CLIENT_ID;
+const clientSecret = process.env.DINGTALK_CLIENT_SECRET;
+
+if (!clientId || !clientSecret) {
+  console.error("请设置环境变量: DINGTALK_CLIENT_ID, DINGTALK_CLIENT_SECRET");
+  process.exit(1);
+}
+
+const sessions =
+  process.env.PERSIST_SESSIONS === "1" || process.env.SESSION_DIR
+    ? createFileSessionStore(process.env.SESSION_DIR ? { dir: process.env.SESSION_DIR } : {})
+    : createInMemorySessionStore();
+
+const echoAgent = createLangChainLikeAgent({
+  id: "main",
+  systemPrompt: "你是助手。回复简洁。",
+  historyLimit: 20,
+  runnable: async ({ messages }) => {
+    const last = messages[messages.length - 1];
+    return { content: `收到：${last?.content ?? ""}` };
+  },
+});
+
+const hub = createHub({
+  router: createRuleBasedRouter({ defaultAgentId: "main" }),
+  agents: [echoAgent],
+  adapters: [createDingTalkAdapter({ config: { clientId, clientSecret } })],
+  sessions,
+});
+
+startInboundServer({ hub, port: PORT });
+console.log("peer.id 填钉钉 userId 或群 openConversationId；PERSIST_SESSIONS=1 可持久化会话");

package/scripts/dingtalk-stdio-bridge.ts

@@ -0,0 +1,309 @@
+/**
+ * 钉钉 Stdio 桥接：与 start:connector 行为一致，复用同一套 @dingtalk-real-ai/dingtalk-connector 插件。
+ * 不维护独立的消息/流式逻辑，插件新功能（如 asyncMode、AI Card、bindings）自动生效。
+ * 桥接层不改写 /v1/chat/completions 请求体，是否传 ext 由插件决定（当前通用契约为不传 ext，仅传 user）。
+ *
+ * 与 connector-host 的差异：不启动本地 HTTP Gateway，而是通过 cfg.channels.dingtalk-connector.gatewayBaseUrl
+ * 让插件直接请求远程 Gateway（如 yuce-gpt）。配置来源与 connector-host 相同：syim.json 或环境变量。
+ *
+ * 使用：在项目目录下配置 syim.json 的 channels.dingtalk-connector，或设置环境变量；
+ * 必须提供远程 Gateway 的 base URL：环境变量 DINGTALK_AGENT_URL / GATEWAY_URL，或 syim.json 中
+ * channels.dingtalk-connector 的 dingtalkAgentUrl / gatewayBaseUrl，或任一子账号 accounts.*.gatewayBaseUrl。
+ */
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+const CHANNEL_KEY = "dingtalk-connector";
+
+/**
+ * 项目根（syim.json 所在目录）。
+ * 用 process.argv[1]：兼容 `tsx scripts/...ts`、`node dist/...cjs`，且 CJS 打包产物内无需 import.meta / __filename。
+ */
+function getProjectRoot(): string {
+  const main = process.argv[1];
+  if (main) {
+    const resolved = path.resolve(main);
+    const base = path.basename(resolved);
+    if (
+      base === "dingtalk-stdio-bridge.ts" ||
+      base === "dingtalk-stdio-bridge.cjs" ||
+      base === "dingtalk-stdio-bridge.mjs"
+    ) {
+      return path.join(path.dirname(resolved), "..");
+    }
+  }
+  return process.cwd();
+}
+
+/** 在 `accounts` 记录中查找第一个非空字符串字段（用于 hub 式配置：Gateway 仅写在子账号下） */
+function firstStringInAccounts(
+  accounts: Record<string, unknown> | undefined,
+  field: string,
+): string {
+  if (!accounts || typeof accounts !== "object") return "";
+  for (const acc of Object.values(accounts)) {
+    if (!acc || typeof acc !== "object") continue;
+    const v = (acc as Record<string, unknown>)[field];
+    if (typeof v === "string" && v.trim()) return v.trim();
+  }
+  return "";
+}
+
+function channelsForLog(channels: Record<string, unknown> | undefined): Record<string, unknown> | undefined {
+  if (!channels || typeof channels !== "object") return channels;
+  const out: Record<string, unknown> = {};
+  const sensitive = new Set(["clientSecret", "dingtalkAgentAccessToken", "token", "gatewayToken", "gatewayPassword"]);
+  for (const [k, v] of Object.entries(channels)) {
+    if (v && typeof v === "object") {
+      const c = { ...(v as Record<string, unknown>) };
+      for (const key of Object.keys(c)) if (sensitive.has(key)) (c as Record<string, unknown>)[key] = "<redacted>";
+      if (c.accounts && typeof c.accounts === "object") (c as Record<string, unknown>).accounts = Object.keys(c.accounts as object);
+      out[k] = c;
+    } else out[k] = v;
+  }
+  return out;
+}
+
+/** 加载 syim.json，与 connector-host 一致 */
+function loadOpenClawConfig(): Record<string, unknown> | null {
+  const configPaths = [path.join(getProjectRoot(), "syim.json"), path.join(os.homedir(), ".syim", "syim.json")];
+  for (const configPath of configPaths) {
+    if (!fs.existsSync(configPath)) continue;
+    try {
+      const content = fs.readFileSync(configPath, "utf-8");
+      const config = JSON.parse(content) as Record<string, unknown>;
+      console.error("[dingtalk-stdio-bridge] 配置与 connector 匹配: 从 syim.json 加载配置，路径:", configPath);
+      console.error("[dingtalk-stdio-bridge] 配置文件 channels:", JSON.stringify(channelsForLog(config.channels as Record<string, unknown>), null, 2));
+      return config;
+    } catch (err) {
+      console.warn("[dingtalk-stdio-bridge] 读取配置失败:", configPath, (err as Error).message);
+    }
+  }
+  console.error("[dingtalk-stdio-bridge] 配置与 connector 匹配: 未找到 syim.json，将使用环境变量");
+  return null;
+}
+
+/** 构建 cfg，与 connector-host buildDingTalkCfg 一致；并注入 gatewayBaseUrl 使插件直连远程 Gateway */
+function buildCfg(): Record<string, unknown> {
+  const raw = loadOpenClawConfig();
+  const channelConfig = (raw?.channels as Record<string, unknown>)?.[CHANNEL_KEY] as Record<string, unknown> | undefined;
+
+  const envBase = (process.env.DINGTALK_AGENT_URL || process.env.GATEWAY_URL || "").trim();
+  const accountsMap = channelConfig?.accounts as Record<string, unknown> | undefined;
+  const fileBase =
+    (channelConfig?.dingtalkAgentUrl as string)?.trim() ||
+    (channelConfig?.gatewayBaseUrl as string)?.trim() ||
+    firstStringInAccounts(accountsMap, "gatewayBaseUrl") ||
+    "";
+  const baseUrlRaw = envBase || fileBase;
+  const gatewayBaseUrl = baseUrlRaw
+    ? baseUrlRaw.replace(/\/dingtalk\/chat\/?$/i, "").replace(/\/v1\/chat\/completions\/?$/i, "").replace(/\/+$/, "")
+    : "";
+  const gatewayToken = (
+    process.env.GATEWAY_TOKEN ||
+    process.env.OPENCLAW_GATEWAY_TOKEN ||
+    process.env.OPENCLAW_GATEWAY_API_KEY ||
+    (channelConfig?.gatewayToken as string)?.trim() ||
+    firstStringInAccounts(accountsMap, "gatewayToken") ||
+    ""
+  ).trim();
+  console.log("[dingtalk-stdio-bridge] gatewayToken =", gatewayToken);
+  console.log("[dingtalk-stdio-bridge] gatewayBaseUrl =", gatewayBaseUrl);
+
+  if (!gatewayBaseUrl) {
+    console.error(JSON.stringify({ error: "DINGTALK_AGENT_URL or GATEWAY_URL (or syim.json dingtalkAgentUrl) required" }));
+    process.exit(1);
+  }
+
+  let cfg: Record<string, unknown>;
+
+  if (channelConfig) {
+    const base = { ...channelConfig } as Record<string, unknown>;
+    const accounts = base.accounts as Record<string, Record<string, unknown>> | undefined;
+    delete base.accounts;
+    base.gatewayBaseUrl = gatewayBaseUrl;
+    if (gatewayToken) base.gatewayToken = gatewayToken;
+    if (accounts && typeof accounts === "object") {
+      const merged: Record<string, Record<string, unknown>> = {};
+      for (const [id, acc] of Object.entries(accounts)) {
+        if (acc && typeof acc === "object") merged[id] = { ...base, ...acc };
+      }
+      cfg = { channels: { [CHANNEL_KEY]: { ...base, accounts: merged } } };
+    } else {
+      cfg = { channels: { [CHANNEL_KEY]: base } };
+    }
+    console.error("[dingtalk-stdio-bridge] 配置与 connector 匹配: channel 键 \"" + CHANNEL_KEY + "\" 在 cfg.channels 中找到");
+  } else {
+    const clientId = process.env.DINGTALK_CLIENT_ID;
+    const clientSecret = process.env.DINGTALK_CLIENT_SECRET;
+    if (!clientId || !clientSecret) {
+      console.error(JSON.stringify({ error: "DINGTALK_CLIENT_ID and DINGTALK_CLIENT_SECRET required (set in syim.json channels.dingtalk-connector or env)" }));
+      process.exit(1);
+    }
+    console.error("[dingtalk-stdio-bridge] 配置与 connector 匹配: 无配置文件或未匹配 channel，使用环境变量");
+    cfg = {
+      channels: {
+        [CHANNEL_KEY]: {
+          clientId,
+          clientSecret,
+          gatewayBaseUrl,
+          gatewayToken: gatewayToken || undefined,
+          separateSessionByConversation: true,
+          groupSessionScope: "group",
+          debug: process.env.DEBUG === "1",
+        },
+      },
+    };
+  }
+
+  console.error("[dingtalk-stdio-bridge] 配置与 connector 匹配: gatewayBaseUrl =", gatewayBaseUrl, "(插件将直连此 base + /v1/chat/completions)");
+  console.error("[dingtalk-stdio-bridge] 配置与 connector 匹配: 桥接就绪，加载插件 @dingtalk-real-ai/dingtalk-connector 与 start:connector 行为一致");
+  return { cfg, gatewayBaseUrl, gatewayToken };
+}
+
+/**
+ * 方案 A：在导入插件前设置临时 HOME，使插件内读取 ~/.syim/syim.json 时实际读到当前项目 syim.json（用于 bindings 等）。
+ * 不劫持 fs，仅改环境变量 + 临时目录内放一份配置（拷贝），进程内 os.homedir() 指向该临时目录。
+ */
+function setupOpenClawConfigForPlugin(): void {
+  const projectRoot = getProjectRoot();
+  const projectConfigPath = path.join(projectRoot, "syim.json");
+  if (!fs.existsSync(projectConfigPath)) return;
+
+  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "openclaw-bridge-"));
+  const openclawDir = path.join(tempDir, ".syim");
+  fs.mkdirSync(openclawDir, { recursive: true });
+  const targetPath = path.join(openclawDir, "syim.json");
+  try {
+    fs.copyFileSync(projectConfigPath, targetPath);
+  } catch (err) {
+    console.warn("[dingtalk-stdio-bridge] 拷贝 syim.json 到临时目录失败，插件将使用系统 ~/.syim:", (err as Error).message);
+    try {
+      fs.rmSync(tempDir, { recursive: true, force: true });
+    } catch (_) {}
+    return;
+  }
+  process.env.HOME = tempDir;
+  if (process.platform === "win32") process.env.USERPROFILE = tempDir;
+  console.error("[dingtalk-stdio-bridge] 已设置 HOME 为临时目录，插件将读取当前项目 syim.json（bindings 等）:", projectConfigPath);
+}
+
+async function main(): Promise<void> {
+  setupOpenClawConfigForPlugin();
+
+  const { cfg, gatewayBaseUrl, gatewayToken } = buildCfg();
+
+  // 确保插件 getConfig(cfg) 拿到的对象上就有 gatewayBaseUrl：直接写入 cfg.channels[CHANNEL_KEY]
+  const ch = (cfg as Record<string, unknown>).channels as Record<string, unknown> | undefined;
+  const channelEntry = ch?.[CHANNEL_KEY];
+  if (channelEntry && typeof channelEntry === "object") {
+    (channelEntry as Record<string, unknown>).gatewayBaseUrl = gatewayBaseUrl;
+    if (gatewayToken) (channelEntry as Record<string, unknown>).gatewayToken = gatewayToken;
+  }
+
+  const runtime = {
+    gateway: { port: 0 },
+    channel: { activity: { record: (_ch: string, _acc: string, _ev: string) => {} } },
+  };
+
+  console.error("[dingtalk-stdio-bridge] 插件与 connector 匹配: 开始加载插件包 ylib-dingtalk-connector");
+  const connectorModule = await import("ylib-dingtalk-connector");
+  const plugin = connectorModule.default as { register: (api: unknown) => void };
+  const dingtalkPlugin = connectorModule.dingtalkPlugin as {
+    config?: { listAccountIds?: (cfg: unknown) => string[]; resolveAccount?: (cfg: unknown, id?: string) => unknown; isConfigured?: (a: unknown) => boolean };
+    gateway?: { startAccount?: (ctx: unknown) => Promise<unknown> };
+  } | undefined;
+
+  if (typeof plugin?.register !== "function") {
+    console.error(JSON.stringify({ error: "connector 未导出 default.register" }));
+    process.exit(1);
+  }
+  plugin.register({
+    runtime,
+    registerChannel: () => {},
+    registerGatewayMethod: () => {},
+  });
+  console.error("[dingtalk-stdio-bridge] 插件与 connector 匹配: 已调用 plugin.register(api)");
+
+  const listAccountIds = dingtalkPlugin?.config?.listAccountIds;
+  const resolveAccount = dingtalkPlugin?.config?.resolveAccount;
+  const isConfigured = dingtalkPlugin?.config?.isConfigured;
+  const startAccount = dingtalkPlugin?.gateway?.startAccount;
+
+  if (!startAccount) {
+    console.error(JSON.stringify({ error: "connector 未注册 gateway.startAccount（请确认 @dingtalk-real-ai/dingtalk-connector 导出 dingtalkPlugin）" }));
+    process.exit(1);
+  }
+
+  const accountIds = listAccountIds ? listAccountIds(cfg) : ["__default__"];
+  console.error("[dingtalk-stdio-bridge] 插件与 connector 匹配: listAccountIds(cfg) =>", accountIds);
+  if (accountIds.length === 0) {
+    console.error(JSON.stringify({ error: "无可用钉钉账号，请检查 syim.json channels.dingtalk-connector 或环境变量" }));
+    process.exit(1);
+  }
+
+  const log = {
+    info: (msg: string) => console.error("[DingTalk]", msg),
+    warn: (msg: string) => console.warn("[DingTalk]", msg),
+    error: (msg: string) => console.error("[DingTalk]", msg),
+  };
+
+  type ResolvedAccount = { accountId: string; config: Record<string, unknown>; enabled: boolean };
+  const cfgChannels = (cfg as Record<string, unknown>).channels as Record<string, unknown> | undefined;
+  const defaultAccount: ResolvedAccount = {
+    accountId: "__default__",
+    config: (cfgChannels?.[CHANNEL_KEY] as Record<string, unknown>) ?? {},
+    enabled: true,
+  };
+
+  let startedCount = 0;
+  for (const accountId of accountIds) {
+    const account: ResolvedAccount = (resolveAccount ? resolveAccount(cfg, accountId) : defaultAccount) as ResolvedAccount;
+    console.error("[dingtalk-stdio-bridge] 插件与 connector 匹配: resolveAccount(cfg,", accountId, ") =>", { accountId: account?.accountId, enabled: account?.enabled, configured: account ? isConfigured?.(account) : false });
+    if (!account?.enabled) {
+      log.info(`[${accountId}] 账号已禁用，跳过`);
+      continue;
+    }
+    if (isConfigured && !isConfigured(account)) {
+      log.warn(`[${accountId}] 账号未配置 clientId/clientSecret，跳过`);
+      continue;
+    }
+    // 插件 resolveAccount 返回的 config 即 cfg.channels[CHANNEL_KEY] 的引用（或合并后的对象），上面已写入 gatewayBaseUrl；
+    // 再在 account.config 上就地写入一次，确保插件 startAccount 内 const config = account.config 能拿到
+    const accConfig = (account as { config?: Record<string, unknown> }).config;
+    if (accConfig && typeof accConfig === "object") {
+      (accConfig as Record<string, unknown>).gatewayBaseUrl = gatewayBaseUrl;
+      if (gatewayToken) (accConfig as Record<string, unknown>).gatewayToken = gatewayToken;
+    }
+    console.error(
+      "[dingtalk-stdio-bridge] 调用 startAccount 前校验:",
+      "accountId=",
+      account.accountId,
+      "gatewayBaseUrl=",
+      (account.config as any)?.gatewayBaseUrl,
+      "gatewayToken=",
+      (account.config as any)?.gatewayToken ? "<present>" : "<absent>"
+    );
+    console.error("[dingtalk-stdio-bridge] 插件与 connector 匹配: 调用 gateway.startAccount 启动 accountId =", account.accountId);
+    const abort = new AbortController();
+    startAccount({
+      cfg,
+      accountId: account.accountId,
+      account,
+      abortSignal: abort.signal,
+      log,
+    }).catch((err: Error) => {
+      log.error(`[${account.accountId}] 启动失败: ${err.message}`);
+    });
+    startedCount++;
+  }
+
+  console.error("[dingtalk-stdio-bridge] 钉钉 connector 已启动（与 start:connector 同一插件），账号数:", startedCount, "，Gateway 直连 gatewayBaseUrl");
+}
+
+main().catch((err) => {
+  console.error("[dingtalk-stdio-bridge]", err);
+  process.exit(1);
+});

package/scripts/dingtalk-stream-server.ts

@@ -0,0 +1,173 @@
+/**
+ * 钉钉 Stream 收消息 + im-agent-hub 处理 + 钉钉 OpenAPI 回发（完整收发流程）
+ *
+ * 与官方 dingtalk-openclaw-connector 相同的收消息方式（dingtalk-stream），
+ * 收到后转成 InboundMessage 交给 hub.handleInbound，回复由 createDingTalkAdapter 发出。
+ *
+ * 使用方式：
+ *   # 必填：钉钉应用
+ *   DINGTALK_CLIENT_ID=xxx DINGTALK_CLIENT_SECRET=yyy pnpm run start:dingtalk
+ *
+ *   # 若设置 IFLOW_API_KEY，单聊/群聊回复将使用 iflow 接口；不设则使用内置 echo 回复
+ *   IFLOW_API_KEY=sk-xxx DINGTALK_CLIENT_ID=xxx DINGTALK_CLIENT_SECRET=yyy pnpm run start:dingtalk
+ *
+ * 环境变量：
+ *   DINGTALK_CLIENT_ID    钉钉应用 AppKey（必填）
+ *   DINGTALK_CLIENT_SECRET 钉钉应用 AppSecret（必填）
+ *   IFLOW_API_KEY         可选，设置后使用 iflow 接口回答（可直接在钉钉里和机器人对话）
+ *   IFLOW_BASE_URL        可选，iflow 接口地址，默认 http://92.113.117.22:10068/proxy/iflow
+ *   DEBUG                 设为 1 可开启 dingtalk-stream 调试
+ */
+
+import { DWClient, TOPIC_ROBOT } from "dingtalk-stream";
+import {
+  createHub,
+  createDingTalkAdapter,
+  createRuleBasedRouter,
+  createInMemorySessionStore,
+  createLangChainLikeAgent,
+  createIflowAgent,
+  type InboundMessage,
+} from "../src/index.js";
+
+const clientId = process.env.DINGTALK_CLIENT_ID;
+const clientSecret = process.env.DINGTALK_CLIENT_SECRET;
+
+if (!clientId || !clientSecret) {
+  console.error("请设置环境变量: DINGTALK_CLIENT_ID, DINGTALK_CLIENT_SECRET");
+  process.exit(1);
+}
+
+const config = { clientId, clientSecret };
+
+// 从钉钉 Stream 回调 data 中提取文本（与 connector extractMessageContent 对齐）
+function extractText(data: Record<string, unknown>): string {
+  const msgtype = (data.msgtype as string) || "text";
+  switch (msgtype) {
+    case "text":
+      return ((data.text as Record<string, unknown>)?.content as string)?.trim() ?? "";
+    case "richText": {
+      const parts = (data.content as Record<string, unknown>)?.richText as Array<{ text?: string }> | undefined;
+      if (!Array.isArray(parts)) return "[富文本]";
+      return parts.map((p) => p?.text ?? "").join("") || "[富文本]";
+    }
+    case "picture":
+      return "[图片]";
+    case "audio":
+      return ((data.content as Record<string, unknown>)?.recognition as string) ?? "[语音]";
+    case "file": {
+      const fileName = (data.content as Record<string, unknown>)?.fileName as string;
+      return `[文件: ${fileName ?? "文件"}]`;
+    }
+    default:
+      return ((data.text as Record<string, unknown>)?.content as string)?.trim() ?? `[${msgtype}]`;
+  }
+}
+
+// 去重：避免同一消息重复处理
+const processedIds = new Set<string>();
+const TTL = 5 * 60 * 1000;
+const cleanup = () => {
+  if (processedIds.size < 100) return;
+  const now = Date.now();
+  for (const id of processedIds) {
+    processedIds.delete(id);
+    break;
+  }
+};
+
+// 设置 IFLOW_API_KEY 时使用 iflow 接口回答，否则使用内置 echo
+const useIflow = Boolean(process.env.IFLOW_API_KEY);
+const mainAgent = useIflow
+  ? createIflowAgent({
+      id: "main",
+      systemPrompt: "你是助手。回复简洁友好。",
+      historyLimit: 20,
+      stream: true, // 流式返回，钉钉 adapter 使用 AI Card 打字机效果
+    })
+  : createLangChainLikeAgent({
+      id: "main",
+      systemPrompt: "你是助手。回复简洁。",
+      historyLimit: 20,
+      runnable: async ({ messages }) => {
+        const last = messages[messages.length - 1];
+        return { content: `收到：${last?.content ?? ""}` };
+      },
+    });
+
+const hub = createHub({
+  router: createRuleBasedRouter({ defaultAgentId: "main" }),
+  agents: [mainAgent],
+  adapters: [createDingTalkAdapter({ config })],
+  sessions: createInMemorySessionStore(),
+});
+
+const client = new DWClient({
+  clientId: config.clientId,
+  clientSecret: config.clientSecret,
+  debug: process.env.DEBUG === "1",
+  autoReconnect: true,
+  keepAlive: true,
+// dingtalk-stream 的 DWClient 构造函数参数类型可能与声明不完全一致，用 any 避免 TS 报错
+} as any);
+
+client.registerCallbackListener(TOPIC_ROBOT, async (res: { headers?: { messageId?: string }; data?: string }) => {
+  const messageId = res.headers?.messageId;
+  if (messageId) {
+    client.socketCallBackResponse(messageId, { success: true });
+    if (processedIds.has(messageId)) {
+      console.warn("[DingTalk] 重复消息已跳过:", messageId);
+      return;
+    }
+    processedIds.add(messageId);
+    cleanup();
+  }
+
+  let data: Record<string, unknown>;
+  try {
+    data = JSON.parse(res.data ?? "{}") as Record<string, unknown>;
+  } catch {
+    console.error("[DingTalk] 解析 data 失败");
+    return;
+  }
+
+  const text = extractText(data);
+  const conversationType = data.conversationType as string | undefined;
+  const isDirect = conversationType === "1";
+  const senderId = (data.senderStaffId ?? data.senderId) as string | undefined;
+  const senderNick = (data.senderNick as string) ?? "Unknown";
+  const conversationId = data.conversationId as string | undefined;
+
+  if (!senderId) {
+    console.warn("[DingTalk] 缺少 senderStaffId/senderId");
+    return;
+  }
+
+  const input: InboundMessage = {
+    provider: "dingtalk",
+    accountId: "__default__",
+    peer: isDirect
+      ? { kind: "direct", id: senderId }
+      : { kind: "group", id: conversationId ?? senderId },
+    sender: { id: senderId, name: senderNick },
+    messageId: messageId ?? `stream-${Date.now()}`,
+    timestamp: Date.now(),
+    text,
+  };
+
+  console.log("[DingTalk] 收到:", isDirect ? "单聊" : "群聊", senderNick, text.slice(0, 80));
+  try {
+    await hub.handleInbound(input);
+  } catch (err) {
+    console.error("[DingTalk] handleInbound 错误:", err);
+  }
+});
+
+client.connect().then(() => {
+  console.log("钉钉 Stream 已连接，等待消息…");
+  if (useIflow) {
+    console.log("当前使用 iflow 接口回复（已设置 IFLOW_API_KEY），可直接在钉钉单聊/群聊中与机器人对话。");
+  } else {
+    console.log("未设置 IFLOW_API_KEY，使用内置 echo 回复。若要用 iflow，请设置 IFLOW_API_KEY 后重启。");
+  }
+});

package/scripts/example-feishu-webhook.ts

@@ -0,0 +1,71 @@
+/**
+ * 飞书 webhook 示例：HTTP 服务开启飞书回调路由，收消息后经 Hub 由飞书适配器回发
+ *
+ * 使用方式：
+ *   1. 在飞书开放平台创建应用，开通「接收消息」等权限，并订阅 im.message.receive_v1
+ *   2. 配置「请求地址」为：https://你的域名/webhook/feishu（需公网可访问）
+ *   3. 本地或服务器启动本脚本（若本地需用 ngrok 等暴露 /webhook/feishu）
+ *
+ * 环境变量：
+ *   PORT                 HTTP 端口，默认 3100
+ *   FEISHU_APP_ID       飞书应用 App ID（发消息用）
+ *   FEISHU_APP_SECRET   飞书应用 App Secret（发消息用）
+ *
+ * 请求地址校验：使用 parseFeishuWebhookBodyWithVerification 作为 parseBody，
+ * 飞书配置 URL 时发的 type=url_verification 会原样返回 challenge 通过校验。
+ */
+
+import {
+  createHub,
+  createFeishuAdapter,
+  createRuleBasedRouter,
+  createInMemorySessionStore,
+  createLangChainLikeAgent,
+  parseFeishuWebhookBodyWithVerification,
+  startInboundServer,
+} from "../src/index.js";
+
+const PORT = Number(process.env.PORT) || 3100;
+const feishuAppId = process.env.FEISHU_APP_ID;
+const feishuAppSecret = process.env.FEISHU_APP_SECRET;
+
+if (!feishuAppId || !feishuAppSecret) {
+  console.error("请设置环境变量: FEISHU_APP_ID, FEISHU_APP_SECRET（用于回发消息）");
+  process.exit(1);
+}
+
+const feishuCfg = { app_id: feishuAppId, app_secret: feishuAppSecret };
+
+const echoAgent = createLangChainLikeAgent({
+  id: "main",
+  systemPrompt: "你是助手。回复简洁。",
+  historyLimit: 20,
+  runnable: async ({ messages }) => {
+    const last = messages[messages.length - 1];
+    return { content: `收到：${last?.content ?? ""}` };
+  },
+});
+
+const hub = createHub({
+  router: createRuleBasedRouter({ defaultAgentId: "main" }),
+  agents: [echoAgent],
+  adapters: [createFeishuAdapter({ cfg: feishuCfg })],
+  sessions: createInMemorySessionStore(),
+});
+
+startInboundServer({
+  hub,
+  port: PORT,
+  webhookRoutes: [
+    {
+      path: "/webhook/feishu",
+      parseBody: parseFeishuWebhookBodyWithVerification,
+    },
+  ],
+});
+
+console.log(`[im-agent-hub] 已启动 http://localhost:${PORT}`);
+console.log("  GET  /health          -> 健康检查");
+console.log("  POST /inbound         -> 通用 InboundMessage JSON");
+console.log("  POST /webhook/feishu   -> 飞书事件回调（含 URL 校验）");
+console.log("请将飞书「请求地址」配置为: https://你的域名/webhook/feishu");