@keyou007/agent-bot 0.1.0

package/src/feishu/LocalImageMarkdown.ts

@@ -0,0 +1,92 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const MARKDOWN_LINK = /(!?)\[([^\]]*)\]\(([^)\r\n]+)\)/g;
+const IMAGE_EXTENSIONS = new Set([".png", ".jpg", ".jpeg", ".gif", ".webp", ".tiff", ".bmp", ".ico"]);
+
+export async function renderMarkdownWithLocalImages(
+  markdown: string,
+  uploadImage: (filePath: string) => Promise<string>,
+  onUploadError: (error: unknown, filePath: string) => void,
+): Promise<Array<Record<string, unknown>>> {
+  const elements: Array<Record<string, unknown>> = [];
+  const uploads = new Map<string, Promise<string>>();
+  let cursor = 0;
+
+  for (const match of markdown.matchAll(MARKDOWN_LINK)) {
+    const matchIndex = match.index;
+    const target = match[3];
+    if (matchIndex === undefined || target === undefined) continue;
+    const filePath = localImagePath(target);
+    const imageSyntax = match[1] === "!";
+    const label = match[2]?.trim() || path.basename(unwrapTarget(target.trim()));
+    if (!filePath) {
+      if (!imageSyntax) continue;
+      appendMarkdown(elements, markdown.slice(cursor, matchIndex));
+      appendMarkdown(elements, unsupportedImageFallback(label, target));
+      cursor = matchIndex + match[0].length;
+      continue;
+    }
+
+    appendMarkdown(elements, markdown.slice(cursor, matchIndex));
+    try {
+      let upload = uploads.get(filePath);
+      if (!upload) {
+        upload = uploadImage(filePath);
+        uploads.set(filePath, upload);
+      }
+      const imageKey = await upload;
+      elements.push({
+        tag: "img",
+        img_key: imageKey,
+        alt: { tag: "plain_text", content: label },
+        title: { tag: "plain_text", content: label },
+        mode: "fit_horizontal",
+        preview: true,
+      });
+    } catch (error) {
+      onUploadError(error, filePath);
+      appendMarkdown(elements, `图片上传失败：${label}`);
+    }
+    cursor = matchIndex + match[0].length;
+  }
+
+  appendMarkdown(elements, markdown.slice(cursor));
+  return elements;
+}
+
+function localImagePath(rawTarget: string): string | undefined {
+  const target = unwrapTarget(rawTarget.trim());
+  let candidate: string;
+  try {
+    candidate = target.startsWith("file://") ? fileURLToPath(target) : decodeURIComponent(target);
+  } catch {
+    return undefined;
+  }
+  if (/^\/[a-z]:[\\/]/i.test(candidate)) candidate = candidate.slice(1);
+  if (!path.isAbsolute(candidate) && !path.win32.isAbsolute(candidate)) return undefined;
+  const resolved = path.resolve(candidate);
+  if (!IMAGE_EXTENSIONS.has(path.extname(resolved).toLowerCase())) return undefined;
+  try {
+    return fs.statSync(resolved).isFile() ? resolved : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function unwrapTarget(target: string): string {
+  return target.startsWith("<") && target.endsWith(">") ? target.slice(1, -1) : target;
+}
+
+function unsupportedImageFallback(label: string, rawTarget: string): string {
+  const target = unwrapTarget(rawTarget.trim());
+  return /^https?:\/\//i.test(target)
+    ? `[${label || "图片"}](${target})`
+    : `图片不可用：${label || "本地图片"}`;
+}
+
+function appendMarkdown(elements: Array<Record<string, unknown>>, content: string): void {
+  if (!content) return;
+  elements.push({ tag: "markdown", content });
+}

package/src/feishu/contextKey.ts

@@ -0,0 +1,14 @@
+const THREAD_CONTEXT_MARKER = ":thread_id:";
+
+export function threadContextKey(chatId: string, threadId: string): string {
+  return `chat_id:${chatId}${THREAD_CONTEXT_MARKER}${threadId}`;
+}
+
+export function isThreadContextKey(contextKey: string): boolean {
+  return contextKey.startsWith("chat_id:") && contextKey.includes(THREAD_CONTEXT_MARKER);
+}
+
+export function baseChatContextKey(contextKey: string): string {
+  const markerIndex = contextKey.indexOf(THREAD_CONTEXT_MARKER);
+  return markerIndex < 0 ? contextKey : contextKey.slice(0, markerIndex);
+}

package/src/feishu/transport.ts

@@ -0,0 +1,24 @@
+import type { AppConfig } from "../config/schema.js";
+
+export type FeishuTransportMode = "sdk" | "console";
+
+type FeishuTransportConfig = Pick<
+  AppConfig["feishu"],
+  "transport" | "appId" | "appSecret" | "useConsoleWhenMissingCredentials"
+>;
+
+export function resolveFeishuTransport(config: FeishuTransportConfig): FeishuTransportMode {
+  if (config.transport === "console") {
+    return "console";
+  }
+
+  const hasCredentials = Boolean(config.appId && config.appSecret);
+  if (config.transport === "sdk" || !config.useConsoleWhenMissingCredentials) {
+    if (!hasCredentials) {
+      throw new Error("Feishu appId/appSecret are required.");
+    }
+    return "sdk";
+  }
+
+  return hasCredentials ? "sdk" : "console";
+}

package/src/feishu/types.ts

@@ -0,0 +1,83 @@
+export interface IncomingMessage {
+  messageId: string;
+  contextKey: string;
+  chatId?: string;
+  chatType?: "p2p" | "group";
+  userId?: string;
+  replyInThread?: boolean;
+  threadContext?: true;
+  threadId?: string;
+  rootMessageId?: string;
+  parentMessageId?: string;
+  text: string;
+  images?: IncomingImageReference[];
+}
+
+export interface IncomingImageReference {
+  imageKey: string;
+}
+
+export interface MessageReplyTarget {
+  messageId: string;
+  replyInThread: true;
+}
+
+export interface CreateGroupInput {
+  name: string;
+  userOpenId: string;
+  avatarPng?: Uint8Array;
+}
+
+export interface CreatedGroup {
+  chatId: string;
+  name: string;
+}
+
+export interface CardAction {
+  actionId: string;
+  contextKey: string;
+  userId?: string;
+  messageId?: string;
+  value: Record<string, unknown>;
+}
+
+export interface ChatUpdatedEvent {
+  chatId: string;
+  beforeName?: string;
+  afterName: string;
+}
+
+export interface FeishuOutbound {
+  createGroup?(input: CreateGroupInput): Promise<CreatedGroup>;
+  addReaction?(messageId: string, emojiType: string): Promise<string | undefined>;
+  deleteReaction?(messageId: string, reactionId: string): Promise<void>;
+  downloadImage?(messageId: string, imageKey: string): Promise<string>;
+  sendText(contextKey: string, text: string): Promise<string | undefined>;
+  sendMarkdown(contextKey: string, markdown: string, idempotencyKey?: string): Promise<string | undefined>;
+  sendInteractiveCard(contextKey: string, card: Record<string, unknown>): Promise<string | undefined>;
+  replyText?(
+    contextKey: string,
+    target: MessageReplyTarget,
+    text: string,
+    idempotencyKey?: string,
+  ): Promise<string | undefined>;
+  replyMarkdown?(
+    contextKey: string,
+    target: MessageReplyTarget,
+    markdown: string,
+    idempotencyKey?: string,
+  ): Promise<string | undefined>;
+  replyInteractiveCard?(
+    contextKey: string,
+    target: MessageReplyTarget,
+    card: Record<string, unknown>,
+    idempotencyKey?: string,
+  ): Promise<string | undefined>;
+  updateInteractiveCard(messageId: string, card: Record<string, unknown>): Promise<void>;
+}
+
+export interface FeishuEventHandler {
+  onMessage(message: IncomingMessage): Promise<void>;
+  onCardAction(action: CardAction): Promise<void>;
+  onChatUpdated?(event: ChatUpdatedEvent): Promise<void>;
+}

package/src/index.ts

@@ -0,0 +1,228 @@
+import path from "node:path";
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { AcpProcessManager } from "./acp/AcpProcessManager.js";
+import { AcpSessionManager } from "./acp/AcpSessionManager.js";
+import { CodexProcessManager } from "./codex/CodexProcessManager.js";
+import { CodexRuntime } from "./codex/CodexRuntime.js";
+import { LocalControlServer } from "./cli/LocalControlServer.js";
+import { controlEndpoint, type ControlRequest, type ControlResponse } from "./cli/controlProtocol.js";
+import { loadConfig } from "./config/loadConfig.js";
+import { ConsoleConnector } from "./console/ConsoleConnector.js";
+import { ConsoleTurnPresenter } from "./console/ConsoleTurnPresenter.js";
+import { CardRenderer } from "./feishu/CardRenderer.js";
+import { ConsoleFeishuClient } from "./feishu/ConsoleFeishuClient.js";
+import { FeishuConnector } from "./feishu/FeishuConnector.js";
+import { FeishuMessageClient } from "./feishu/FeishuMessageClient.js";
+import { FeishuTurnPresenter } from "./feishu/FeishuTurnPresenter.js";
+import { resolveFeishuTransport } from "./feishu/transport.js";
+import { createLogger } from "./logging/logger.js";
+import { OutboundRouter, type OutboundRoute } from "./presentation/OutboundRouter.js";
+import { ProxySessionController } from "./proxy/ProxySessionController.js";
+import { AcpRuntimeAdapter } from "./runtime/AcpRuntimeAdapter.js";
+import { AgentRuntimeRegistry } from "./runtime/AgentRuntimeRegistry.js";
+import { StateStore } from "./state/StateStore.js";
+import { StartupNotifier } from "./startup/StartupNotifier.js";
+import { SessionMetadataHydrator } from "./startup/SessionMetadataHydrator.js";
+import { startFeishu } from "./startup/startFeishu.js";
+import { STOP_EXIT_CODE } from "./supervision/restartPolicy.js";
+import { replacementSupervisorEnvironment } from "./supervision/replacementSupervisor.js";
+import { SafeRestartScheduler } from "./supervision/SafeRestartScheduler.js";
+import { SafeRestartNotifier } from "./supervision/SafeRestartNotifier.js";
+
+const processStartedAt = new Date();
+const supervised = process.env.AGENT_BOT_SUPERVISED === "1";
+const startupReason = process.env.AGENT_BOT_RESTART_REASON?.trim()
+  || (supervised ? "Supervisor 启动" : "直接启动");
+const consoleOnly = process.env.AGENT_BOT_CONSOLE_ONLY === "1";
+const config = loadConfig();
+const logger = createLogger(config);
+const store = new StateStore(config.storage.sqlitePath);
+
+const acpProcessManager = new AcpProcessManager(logger);
+const acpSessionManager = new AcpSessionManager(config, acpProcessManager, logger);
+const acpRuntime = new AcpRuntimeAdapter(acpSessionManager);
+const codexAgent = Object.values(config.agents).find((agent) => agent.kind === "codex");
+const codexProcessManager = new CodexProcessManager(
+  codexAgent?.command ?? "codex",
+  codexAgent?.args ?? ["app-server", "--listen", "stdio://"],
+  codexAgent?.env ?? {},
+  logger,
+);
+const codexRuntime = new CodexRuntime(codexProcessManager, logger);
+const runtimes = new AgentRuntimeRegistry({ acp: acpRuntime, codex: codexRuntime });
+
+const transport = consoleOnly ? "console" : resolveFeishuTransport(config.feishu);
+const routes: OutboundRoute[] = [];
+let feishuConnector: FeishuConnector | undefined;
+let consoleConnector: ConsoleConnector | undefined;
+let startupNotifier: StartupNotifier | undefined;
+let safeRestartNotifier: SafeRestartNotifier | undefined;
+let controlServer: LocalControlServer | undefined;
+
+const feishuOutbound = transport === "sdk" ? new FeishuMessageClient(config, logger) : undefined;
+if (feishuOutbound) {
+  const renderer = new CardRenderer();
+  const presenter = new FeishuTurnPresenter(feishuOutbound, store, renderer, {
+    normalIntervalMs: 2_000,
+    criticalGapMs: 500,
+    onError: (error) => logger.warn({ error }, "Failed to update Codex progress card."),
+  });
+  routes.push({ matches: (contextKey) => !contextKey.startsWith("console:"), outbound: feishuOutbound, presenter });
+  const defaultAgentName = config.defaults.agent!;
+  const defaultAgent = config.agents[defaultAgentName];
+  const metadataHydrator = new SessionMetadataHydrator(store, runtimes);
+  startupNotifier = new StartupNotifier(store, feishuOutbound, renderer, logger, {
+    defaultAgentName,
+    defaultAgentTitle: defaultAgent?.title ?? defaultAgentName,
+    cwd: path.resolve(config.defaults.cwd),
+    workspaceKind: defaultAgent?.kind === "codex" ? "projectless" : "project",
+  }, metadataHydrator);
+  safeRestartNotifier = new SafeRestartNotifier(store, feishuOutbound, renderer, logger);
+}
+
+const consoleEnabled = consoleOnly || config.console.enabled || transport === "console";
+const consoleOutbound = consoleEnabled ? new ConsoleFeishuClient() : undefined;
+if (consoleOutbound) {
+  routes.push({
+    matches: (contextKey) => contextKey.startsWith("console:"),
+    outbound: consoleOutbound,
+    presenter: new ConsoleTurnPresenter(consoleOutbound),
+  });
+}
+
+if (routes.length === 0) throw new Error("Neither Feishu nor console input is enabled.");
+const outbound = new OutboundRouter(routes);
+let shuttingDown = false;
+let restartRequested = false;
+const controller = new ProxySessionController(config, store, runtimes, outbound, logger, {
+  supervised,
+  restart: requestRestart,
+});
+const safeRestart = new SafeRestartScheduler({
+  readActivity: () => store.getServerActivityState(),
+  onReady: (reason) => initiateRestart(reason),
+  onStatus: (status) => safeRestartNotifier?.update(status),
+  onStatusError: (error) => logger.warn({ error }, "Failed to publish safe restart status."),
+});
+
+if (feishuOutbound) feishuConnector = new FeishuConnector(config, controller, logger);
+if (consoleEnabled) consoleConnector = new ConsoleConnector(controller, logger);
+
+process.on("SIGINT", () => void shutdown(0));
+process.on("SIGTERM", () => void shutdown(0));
+
+const startControlServer = async (): Promise<void> => {
+  if (consoleOnly || controlServer) return;
+  controlServer = new LocalControlServer(
+    controlEndpoint(config.storage.sqlitePath),
+    handleControlRequest,
+  );
+  await controlServer.start();
+  logger.info({ endpoint: controlEndpoint(config.storage.sqlitePath) }, "Local Agent Bot control endpoint started.");
+};
+
+if (feishuConnector && startupNotifier) {
+  await startFeishu(feishuConnector, startupNotifier, processStartedAt, startupReason, startControlServer);
+} else {
+  await startControlServer();
+  await feishuConnector?.start();
+}
+consoleConnector?.start();
+
+async function requestRestart(contextKey: string): Promise<void> {
+  await initiateRestart("用户执行 /restart 命令", contextKey);
+}
+
+async function initiateRestart(reason: string, contextKey?: string): Promise<void> {
+  if (restartRequested) {
+    if (contextKey) await outbound.sendText(contextKey, "Agent Bot 已在重启中，请稍候。").catch(() => undefined);
+    return;
+  }
+  restartRequested = true;
+  safeRestart.cancel();
+  await safeRestartNotifier?.flush();
+  if (contextKey) {
+    await outbound.sendText(contextKey, "Agent Bot 正在重启，恢复在线后会发送启动状态通知。").catch((error: unknown) => {
+      logger.warn({ error, contextKey }, "Failed to send restart acknowledgement.");
+    });
+  }
+  setTimeout(() => void shutdown(supervised ? STOP_EXIT_CODE : 0, reason), 100);
+}
+
+async function handleControlRequest(request: ControlRequest): Promise<ControlResponse> {
+  switch (request.action) {
+    case "health":
+      return {
+        ok: true,
+        data: {
+          pid: process.pid,
+          startedAt: processStartedAt.toISOString(),
+          supervised,
+          safeRestartScheduled: safeRestart.scheduled,
+          safeRestartReason: safeRestart.pendingReason,
+          activity: store.getServerActivityState(),
+        },
+      };
+    case "server_restart":
+      if (request.mode === "safe") {
+        const newlyScheduled = safeRestart.schedule(request.reason);
+        return {
+          ok: true,
+          message: newlyScheduled
+            ? "已安排安全重启；将在全部任务完成并持续空闲 15 秒后执行。"
+            : "安全重启已在等待中，已更新重启原因。",
+        };
+      }
+      setTimeout(() => void initiateRestart(request.reason), 25);
+      return { ok: true, message: "已请求立即重启。" };
+    case "server_stop":
+      safeRestart.cancel();
+      setTimeout(() => void shutdown(STOP_EXIT_CODE), 25);
+      return { ok: true, message: "已请求停止 Agent Bot server。" };
+    case "task_status":
+      return { ok: true, data: await controller.controlGetTaskStatus(request.localSessionId) };
+    case "task_stop":
+      return { ok: true, message: await controller.controlStopTask(request.localSessionId) };
+    case "task_title":
+      return { ok: true, message: await controller.controlSetTaskTitle(request.localSessionId, request.title) };
+    case "task_prompt":
+      return { ok: true, message: await controller.controlSendTaskPrompt(request.localSessionId, request.text) };
+  }
+}
+
+async function shutdown(exitCode: number, restartReason?: string): Promise<void> {
+  if (shuttingDown) return;
+  shuttingDown = true;
+  logger.info({ exitCode }, "Shutting down Agent Bot.");
+  safeRestart.cancel();
+  feishuConnector?.stop();
+  consoleConnector?.stop();
+  controller.close();
+  await Promise.race([
+    outbound.flushAll().catch((error: unknown) => logger.warn({ error }, "Failed to flush presenters.")),
+    delay(5_000),
+  ]);
+  runtimes.close();
+  acpProcessManager.stopAll();
+  await controlServer?.close().catch((error: unknown) => logger.warn({ error }, "Failed to close local control endpoint."));
+  store.close();
+  if (restartReason) startReplacementSupervisor(restartReason);
+  process.exit(exitCode);
+}
+
+function startReplacementSupervisor(restartReason: string): void {
+  const supervisorEntry = fileURLToPath(new URL("./supervisor.js", import.meta.url));
+  const supervisor = spawn(process.execPath, [supervisorEntry], {
+    cwd: process.cwd(),
+    detached: true,
+    windowsHide: true,
+    stdio: "ignore",
+    env: replacementSupervisorEnvironment(restartReason),
+  });
+  supervisor.unref();
+}
+
+function delay(milliseconds: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, milliseconds));
+}

package/src/logging/logger.ts

@@ -0,0 +1,28 @@
+import fs from "node:fs";
+import path from "node:path";
+import pino, { type Logger } from "pino";
+import type { AppConfig } from "../config/schema.js";
+
+export function createLogger(config: AppConfig): Logger {
+  const streams: pino.StreamEntry[] = [
+    {
+      stream: process.stdout,
+    },
+  ];
+
+  if (config.logging.path) {
+    fs.mkdirSync(path.dirname(config.logging.path), { recursive: true });
+    streams.push({
+      stream: fs.createWriteStream(config.logging.path, { flags: "a" }),
+    });
+  }
+
+  return pino(
+    {
+      level: config.logging.level,
+      base: undefined,
+      timestamp: pino.stdTimeFunctions.isoTime,
+    },
+    pino.multistream(streams),
+  );
+}

package/src/presentation/OutboundRouter.ts

@@ -0,0 +1,205 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import type { AgentEvent } from "../runtime/types.js";
+import type {
+  CreatedGroup,
+  CreateGroupInput,
+  FeishuOutbound,
+  MessageReplyTarget,
+} from "../feishu/types.js";
+
+export interface TurnPresenter {
+  registerSession(sessionId: string, contextKey: string, taskTitle?: string, projectCwd?: string): void;
+  updateSessionTitle(sessionId: string, taskTitle: string): void;
+  unregisterSession(sessionId: string): void;
+  startPendingTurn(
+    sessionId: string,
+    contextKey: string,
+    taskTitle?: string,
+    replyTarget?: MessageReplyTarget,
+    prompt?: string,
+  ): Promise<void>;
+  failPendingTurn(sessionId: string, message: string): Promise<void>;
+  appendSteerMessage(sessionId: string, turnId: string, text: string, messageId?: string): Promise<void>;
+  onEvent(event: AgentEvent): Promise<void>;
+  showDetails(contextKey: string, turnId: string): Promise<void>;
+  showActivityPage(
+    contextKey: string,
+    turnId: string,
+    page: number | "latest",
+    messageId?: string,
+  ): Promise<void>;
+  resumeDelivery(sessionId: string, contextKey: string, turnId: string): Promise<void>;
+  flushAll(): Promise<void>;
+}
+
+export interface OutboundRoute {
+  matches(contextKey: string): boolean;
+  outbound: FeishuOutbound;
+  presenter: TurnPresenter;
+}
+
+export class OutboundRouter {
+  private readonly sessionRoutes = new Map<string, OutboundRoute>();
+  private readonly sessionContextKeys = new Map<string, string>();
+  private readonly sessionReplyTargets = new Map<string, MessageReplyTarget>();
+  private readonly replyTargets = new AsyncLocalStorage<{ contextKey: string; target: MessageReplyTarget }>();
+
+  constructor(private readonly routes: OutboundRoute[]) {
+    if (routes.length === 0) throw new Error("At least one outbound route is required.");
+  }
+
+  registerSession(sessionId: string, contextKey: string, taskTitle?: string, projectCwd?: string): void {
+    const route = this.route(contextKey);
+    this.sessionRoutes.set(sessionId, route);
+    this.sessionContextKeys.set(sessionId, contextKey);
+    route.presenter.registerSession(sessionId, contextKey, taskTitle, projectCwd);
+  }
+
+  getSessionContextKey(sessionId: string): string | undefined {
+    return this.sessionContextKeys.get(sessionId);
+  }
+
+  getSessionReplyTarget(sessionId: string): MessageReplyTarget | undefined {
+    return this.sessionReplyTargets.get(sessionId);
+  }
+
+  updateSessionTitle(sessionId: string, taskTitle: string): void {
+    this.sessionRoutes.get(sessionId)?.presenter.updateSessionTitle(sessionId, taskTitle);
+  }
+
+  unregisterSession(sessionId: string): void {
+    const route = this.sessionRoutes.get(sessionId);
+    route?.presenter.unregisterSession(sessionId);
+    this.sessionRoutes.delete(sessionId);
+    this.sessionContextKeys.delete(sessionId);
+    this.sessionReplyTargets.delete(sessionId);
+  }
+
+  async startPendingTurn(
+    sessionId: string,
+    contextKey: string,
+    taskTitle?: string,
+    replyTarget?: MessageReplyTarget,
+    prompt?: string,
+  ): Promise<void> {
+    const route = this.route(contextKey);
+    this.sessionRoutes.set(sessionId, route);
+    this.sessionContextKeys.set(sessionId, contextKey);
+    if (replyTarget) this.sessionReplyTargets.set(sessionId, replyTarget);
+    else this.sessionReplyTargets.delete(sessionId);
+    await route.presenter.startPendingTurn(sessionId, contextKey, taskTitle, replyTarget, prompt);
+  }
+
+  async failPendingTurn(sessionId: string, message: string): Promise<void> {
+    await this.sessionRoutes.get(sessionId)?.presenter.failPendingTurn(sessionId, message);
+  }
+
+  async appendSteerMessage(
+    sessionId: string,
+    turnId: string,
+    text: string,
+    messageId?: string,
+  ): Promise<void> {
+    await this.sessionRoutes.get(sessionId)?.presenter.appendSteerMessage(sessionId, turnId, text, messageId);
+  }
+
+  async onEvent(event: AgentEvent): Promise<void> {
+    await this.sessionRoutes.get(event.sessionId)?.presenter.onEvent(event);
+  }
+
+  async showDetails(contextKey: string, turnId: string): Promise<void> {
+    await this.route(contextKey).presenter.showDetails(contextKey, turnId);
+  }
+
+  async showActivityPage(
+    contextKey: string,
+    turnId: string,
+    page: number | "latest",
+    messageId?: string,
+  ): Promise<void> {
+    await this.route(contextKey).presenter.showActivityPage(contextKey, turnId, page, messageId);
+  }
+
+  async resumeDelivery(sessionId: string, contextKey: string, turnId: string): Promise<void> {
+    await this.route(contextKey).presenter.resumeDelivery(sessionId, contextKey, turnId);
+  }
+
+  async addReaction(contextKey: string, messageId: string, emojiType: string): Promise<string | undefined> {
+    return this.route(contextKey).outbound.addReaction?.(messageId, emojiType);
+  }
+
+  async deleteReaction(contextKey: string, messageId: string, reactionId: string): Promise<void> {
+    await this.route(contextKey).outbound.deleteReaction?.(messageId, reactionId);
+  }
+
+  async downloadImage(contextKey: string, messageId: string, imageKey: string): Promise<string> {
+    const outbound = this.route(contextKey).outbound;
+    const download = outbound.downloadImage;
+    if (!download) throw new Error("当前消息通道不支持下载图片。");
+    return download.call(outbound, messageId, imageKey);
+  }
+
+  async createGroup(contextKey: string, input: CreateGroupInput): Promise<CreatedGroup> {
+    const outbound = this.route(contextKey).outbound;
+    const createGroup = outbound.createGroup;
+    if (!createGroup) throw new Error("当前消息通道不支持创建飞书群。");
+    return createGroup.call(outbound, input);
+  }
+
+  withReplyTarget<T>(
+    contextKey: string,
+    target: MessageReplyTarget | undefined,
+    operation: () => Promise<T>,
+  ): Promise<T> {
+    if (!target) return operation();
+    return this.replyTargets.run({ contextKey, target }, operation);
+  }
+
+  sendText(contextKey: string, text: string): Promise<string | undefined> {
+    const outbound = this.route(contextKey).outbound;
+    const target = this.currentReplyTarget(contextKey);
+    return target && outbound.replyText
+      ? outbound.replyText(contextKey, target, text)
+      : outbound.sendText(contextKey, text);
+  }
+
+  sendMarkdown(contextKey: string, markdown: string): Promise<string | undefined> {
+    const outbound = this.route(contextKey).outbound;
+    const target = this.currentReplyTarget(contextKey);
+    return target && outbound.replyMarkdown
+      ? outbound.replyMarkdown(contextKey, target, markdown)
+      : outbound.sendMarkdown(contextKey, markdown);
+  }
+
+  sendInteractiveCard(contextKey: string, card: Record<string, unknown>): Promise<string | undefined> {
+    const outbound = this.route(contextKey).outbound;
+    const target = this.currentReplyTarget(contextKey);
+    return target && outbound.replyInteractiveCard
+      ? outbound.replyInteractiveCard(contextKey, target, card)
+      : outbound.sendInteractiveCard(contextKey, card);
+  }
+
+  async updateInteractiveCard(
+    contextKey: string,
+    messageId: string,
+    card: Record<string, unknown>,
+  ): Promise<void> {
+    await this.route(contextKey).outbound.updateInteractiveCard(messageId, card);
+  }
+
+  async flushAll(): Promise<void> {
+    const presenters = [...new Set(this.routes.map((route) => route.presenter))];
+    await Promise.all(presenters.map((presenter) => presenter.flushAll()));
+  }
+
+  private route(contextKey: string): OutboundRoute {
+    const route = this.routes.find((candidate) => candidate.matches(contextKey));
+    if (!route) throw new Error(`No outbound route for context: ${contextKey}`);
+    return route;
+  }
+
+  private currentReplyTarget(contextKey: string): MessageReplyTarget | undefined {
+    const current = this.replyTargets.getStore();
+    return current?.contextKey === contextKey ? current.target : undefined;
+  }
+}