@downcity/plugins 1.0.4

package/src/chat/runtime/ChatQueue.ts

@@ -0,0 +1,77 @@
+/**
+ * ChatQueue 共享门面。
+ *
+ * 关键点（中文）
+ * - 迁移阶段保留旧函数式 API，内部委托给共享 `ChatQueueStore`。
+ * - 新代码应优先通过 `ChatQueueStore` 实例或 `resolveChatQueueStore(runtime)` 使用队列。
+ */
+
+import type {
+  ChatQueueEnqueueParams,
+  ChatQueueEnqueueResult,
+  ChatQueueItem,
+} from "@/chat/types/ChatQueue.js";
+import {
+  ChatQueueStore,
+  getSharedChatQueueStore,
+  resolveChatQueueStore,
+  type ChatQueueEnqueueListener,
+  type ChatQueueStorePort,
+} from "./ChatQueueStore.js";
+
+export { ChatQueueStore, getSharedChatQueueStore, resolveChatQueueStore };
+export type { ChatQueueEnqueueListener, ChatQueueStorePort };
+
+/**
+ * 订阅共享 queue 的入队事件。
+ */
+export function onChatQueueEnqueue(listener: ChatQueueEnqueueListener): () => void {
+  return getSharedChatQueueStore().onEnqueue(listener);
+}
+
+/**
+ * 向共享 queue 入队。
+ */
+export function enqueueChatQueue(
+  params: ChatQueueEnqueueParams,
+): ChatQueueEnqueueResult {
+  return getSharedChatQueueStore().enqueue(params);
+}
+
+/**
+ * 从共享 queue 弹出一条消息。
+ */
+export function shiftChatQueueItem(laneKey: string): ChatQueueItem | null {
+  return getSharedChatQueueStore().shift(laneKey);
+}
+
+/**
+ * 从共享 queue drain 某个 lane。
+ */
+export function drainChatQueueLane(
+  laneKey: string,
+  maxItems?: number,
+): ChatQueueItem[] {
+  return getSharedChatQueueStore().drain(laneKey, maxItems);
+}
+
+/**
+ * 列出共享 queue 当前积压的 lane keys。
+ */
+export function listChatQueueLanes(): string[] {
+  return getSharedChatQueueStore().listLanes();
+}
+
+/**
+ * 查询共享 queue 某个 lane 的长度。
+ */
+export function getChatQueueLaneSize(laneKey: string): number {
+  return getSharedChatQueueStore().getLaneSize(laneKey);
+}
+
+/**
+ * 清空共享 queue 某个 lane。
+ */
+export function clearChatQueueLane(laneKey: string): void {
+  getSharedChatQueueStore().clear(laneKey);
+}

package/src/chat/runtime/ChatQueueReplyDispatch.ts

@@ -0,0 +1,191 @@
+/**
+ * ChatQueueReplyDispatch：chat queue worker 的回复分发模块。
+ *
+ * 关键点（中文）
+ * - 收敛 direct / fallback 两类 channel 回发逻辑。
+ * - ChatQueueWorker 主类只保留“何时分发”的决策，不再承载具体发消息细节。
+ */
+
+import type { Logger } from "@downcity/agent/internal/utils/logger/Logger.js";
+import type { AgentContext } from "@downcity/agent/internal/types/runtime/agent/AgentContext.js";
+import { parseDirectDispatchAssistantText } from "./DirectDispatchParser.js";
+import { sendActionByChatKey } from "./ChatkeySend.js";
+import { sendChatTextByChatKey } from "../Action.js";
+import {
+  emitChatReplyEffect,
+  prepareChatReplyText,
+  resolveChatReplyTarget,
+} from "./ReplyDispatch.js";
+
+/**
+ * 把 assistant 纯文本直接投递到 chat。
+ */
+export async function dispatchAssistantTextDirect(params: {
+  logger: Logger;
+  context: AgentContext;
+  sessionId: string;
+  assistantText: string;
+  phase?: "step" | "final" | "error";
+}): Promise<boolean> {
+  const plan = parseDirectDispatchAssistantText({
+    assistantText: params.assistantText,
+    fallbackChatKey: params.sessionId,
+  });
+  if (!plan) return false;
+  let textDispatchSucceeded = false;
+
+  if (plan.text) {
+    const target = await resolveChatReplyTarget({
+      context: params.context,
+      chatKey: plan.text.chatKey,
+    });
+    const preparedText = await prepareChatReplyText({
+      context: params.context,
+      input: {
+        chatKey: plan.text.chatKey,
+        ...(target.channel ? { channel: target.channel } : {}),
+        ...(typeof target.chatId === "string" ? { chatId: target.chatId } : {}),
+        ...(typeof plan.text.messageId === "string"
+          ? { messageId: plan.text.messageId }
+          : typeof target.messageId === "string"
+            ? { messageId: target.messageId }
+            : {}),
+        text: plan.text.text,
+        phase: params.phase || "final",
+        mode: "direct",
+      },
+    });
+    const textResult = await sendChatTextByChatKey({
+      context: params.context,
+      chatKey: plan.text.chatKey,
+      text: preparedText,
+      replyToMessage: plan.text.replyToMessage,
+      messageId: plan.text.messageId,
+      ...(typeof plan.text.delayMs === "number"
+        ? { delayMs: plan.text.delayMs }
+        : {}),
+      ...(typeof plan.text.sendAtMs === "number"
+        ? { sendAtMs: plan.text.sendAtMs }
+        : {}),
+    });
+    await emitChatReplyEffect({
+      context: params.context,
+      input: {
+        chatKey: plan.text.chatKey,
+        ...(target.channel ? { channel: target.channel } : {}),
+        ...(typeof target.chatId === "string" ? { chatId: target.chatId } : {}),
+        ...(typeof plan.text.messageId === "string"
+          ? { messageId: plan.text.messageId }
+          : typeof target.messageId === "string"
+            ? { messageId: target.messageId }
+            : {}),
+        text: preparedText,
+        phase: params.phase || "final",
+        mode: "direct",
+        success: textResult.success,
+        ...(textResult.success ? {} : { error: textResult.error || "chat send failed" }),
+      },
+    });
+    if (!textResult.success) {
+      params.logger.warn("Direct chat text dispatch failed", {
+        sessionId: params.sessionId,
+        targetChatKey: plan.text.chatKey,
+        error: textResult.error || "chat send failed",
+      });
+    } else {
+      textDispatchSucceeded = true;
+    }
+  }
+
+  for (const reaction of plan.reactions) {
+    const reactResult = await sendActionByChatKey({
+      context: params.context,
+      chatKey: reaction.chatKey,
+      action: "react",
+      messageId: reaction.messageId,
+      reactionEmoji: reaction.emoji,
+      reactionIsBig: reaction.big,
+    });
+    if (!reactResult.success) {
+      params.logger.warn("Direct chat reaction dispatch failed", {
+        sessionId: params.sessionId,
+        targetChatKey: reaction.chatKey,
+        error: reactResult.error || "chat react failed",
+      });
+    }
+  }
+
+  return textDispatchSucceeded;
+}
+
+/**
+ * 强制把文本回发到 channel。
+ */
+export async function dispatchTextToChannel(params: {
+  logger: Logger;
+  context: AgentContext;
+  sessionId: string;
+  text: string;
+  messageId?: string;
+  phase?: "step" | "final" | "error";
+}): Promise<boolean> {
+  const text = String(params.text || "").trim();
+  if (!text) return false;
+  const target = await resolveChatReplyTarget({
+    context: params.context,
+    chatKey: params.sessionId,
+  });
+  const preparedText = await prepareChatReplyText({
+    context: params.context,
+    input: {
+      chatKey: params.sessionId,
+      ...(target.channel ? { channel: target.channel } : {}),
+      ...(typeof target.chatId === "string" ? { chatId: target.chatId } : {}),
+      ...(typeof params.messageId === "string"
+        ? { messageId: params.messageId }
+        : typeof target.messageId === "string"
+          ? { messageId: target.messageId }
+          : {}),
+      text,
+      phase: params.phase || "final",
+      mode: "fallback",
+    },
+  });
+
+  const result = await sendChatTextByChatKey({
+    context: params.context,
+    chatKey: params.sessionId,
+    text: preparedText,
+    replyToMessage: true,
+    ...(typeof params.messageId === "string" && params.messageId
+      ? { messageId: params.messageId }
+      : {}),
+  });
+  await emitChatReplyEffect({
+    context: params.context,
+    input: {
+      chatKey: params.sessionId,
+      ...(target.channel ? { channel: target.channel } : {}),
+      ...(typeof target.chatId === "string" ? { chatId: target.chatId } : {}),
+      ...(typeof params.messageId === "string"
+        ? { messageId: params.messageId }
+        : typeof target.messageId === "string"
+          ? { messageId: target.messageId }
+          : {}),
+      text: preparedText,
+      phase: params.phase || "final",
+      mode: "fallback",
+      success: result.success,
+      ...(result.success ? {} : { error: result.error || "chat send failed" }),
+    },
+  });
+
+  if (!result.success) {
+    params.logger.warn("ChatQueueWorker forced channel dispatch failed", {
+      sessionId: params.sessionId,
+      error: result.error || "chat send failed",
+    });
+    return false;
+  }
+  return true;
+}

package/src/chat/runtime/ChatQueueStore.ts

@@ -0,0 +1,185 @@
+/**
+ * ChatQueueStore：chat plugin runtime 队列存储。
+ *
+ * 关键点（中文）
+ * - 这是 chat queue 的实例级状态容器。
+ * - 允许 `ChatPlugin` 持有自己的 queue store，而不是完全依赖模块级全局状态。
+ * - 旧的 `ChatQueue.ts` 会保留共享门面，逐步迁移到显式实例注入。
+ */
+
+import type { AgentContext } from "@downcity/agent/internal/types/runtime/agent/AgentContext.js";
+import type {
+  ChatQueueEnqueueParams,
+  ChatQueueEnqueueResult,
+  ChatQueueItem,
+} from "@/chat/types/ChatQueue.js";
+
+/**
+ * 入队监听器。
+ */
+export type ChatQueueEnqueueListener = (laneKey: string) => void;
+
+/**
+ * ChatPlugin queue store 的最小能力接口。
+ */
+export interface ChatQueueStorePort {
+  /**
+   * 订阅入队事件。
+   */
+  onEnqueue(listener: ChatQueueEnqueueListener): () => void;
+  /**
+   * 入队。
+   */
+  enqueue(params: ChatQueueEnqueueParams): ChatQueueEnqueueResult;
+  /**
+   * 弹出一条队列项。
+   */
+  shift(laneKey: string): ChatQueueItem | null;
+  /**
+   * drain 指定 lane。
+   */
+  drain(laneKey: string, maxItems?: number): ChatQueueItem[];
+  /**
+   * 列出当前 lane keys。
+   */
+  listLanes(): string[];
+  /**
+   * 查询某个 lane 的长度。
+   */
+  getLaneSize(laneKey: string): number;
+  /**
+   * 清空某个 lane。
+   */
+  clear(laneKey: string): void;
+}
+
+/**
+ * 共享 queue store。
+ *
+ * 关键点（中文）
+ * - 迁移阶段仍保留一份共享实例，避免一次性改动所有旧入口。
+ * - 新代码应优先通过 `AgentContext.agent` 解析显式 queue store。
+ */
+/**
+ * Chat queue 实例级存储。
+ */
+export class ChatQueueStore implements ChatQueueStorePort {
+  private readonly lanes: Map<string, ChatQueueItem[]> = new Map();
+  private readonly listeners: Set<ChatQueueEnqueueListener> = new Set();
+  private nextSeq = 1;
+
+  private generateItemId(): string {
+    const seq = this.nextSeq;
+    this.nextSeq += 1;
+    return `q:${Date.now().toString(36)}:${seq.toString(36)}`;
+  }
+
+  private getLane(key: string): ChatQueueItem[] {
+    const lane = this.lanes.get(key);
+    if (lane) return lane;
+    const created: ChatQueueItem[] = [];
+    this.lanes.set(key, created);
+    return created;
+  }
+
+  private normalizeLaneKey(raw: string): string {
+    const key = String(raw || "").trim();
+    if (!key) throw new Error("ChatQueueStore requires a non-empty lane key");
+    return key;
+  }
+
+  onEnqueue(listener: ChatQueueEnqueueListener): () => void {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+
+  enqueue(params: ChatQueueEnqueueParams): ChatQueueEnqueueResult {
+    const laneKey = this.normalizeLaneKey(params.sessionId);
+    const lane = this.getLane(laneKey);
+    const item: ChatQueueItem = {
+      ...params,
+      id: this.generateItemId(),
+      enqueuedAt: Date.now(),
+      kind: params.kind ?? "exec",
+    };
+    lane.push(item);
+    for (const listener of this.listeners) {
+      try {
+        listener(laneKey);
+      } catch {
+        // ignore listener failure
+      }
+    }
+    return {
+      lanePosition: lane.length,
+      itemId: item.id,
+    };
+  }
+
+  shift(laneKey: string): ChatQueueItem | null {
+    const key = this.normalizeLaneKey(laneKey);
+    const lane = this.lanes.get(key);
+    if (!lane || lane.length === 0) return null;
+    const item = lane.shift() || null;
+    if (lane.length === 0) this.lanes.delete(key);
+    return item;
+  }
+
+  drain(laneKey: string, maxItems?: number): ChatQueueItem[] {
+    const key = this.normalizeLaneKey(laneKey);
+    const lane = this.lanes.get(key);
+    if (!lane || lane.length === 0) return [];
+
+    if (typeof maxItems === "number" && maxItems > 0 && maxItems < lane.length) {
+      return lane.splice(0, Math.floor(maxItems));
+    }
+
+    this.lanes.delete(key);
+    return lane.splice(0, lane.length);
+  }
+
+  listLanes(): string[] {
+    return Array.from(this.lanes.keys());
+  }
+
+  getLaneSize(laneKey: string): number {
+    const key = String(laneKey || "").trim();
+    if (!key) return 0;
+    const lane = this.lanes.get(key);
+    return lane ? lane.length : 0;
+  }
+
+  clear(laneKey: string): void {
+    const key = String(laneKey || "").trim();
+    if (!key) return;
+    this.lanes.delete(key);
+  }
+}
+
+const sharedChatQueueStore = new ChatQueueStore();
+
+/**
+ * 读取共享 chat queue store。
+ */
+export function getSharedChatQueueStore(): ChatQueueStore {
+  return sharedChatQueueStore;
+}
+
+/**
+ * 从运行时解析 chat queue store。
+ *
+ * 关键点（中文）
+ * - 新路径优先读取 `runtime.agent.pluginInstances.chat.queueStore`。
+ * - 迁移阶段若拿不到，则回退到共享 queue store，保证旧入口可继续工作。
+ */
+export function resolveChatQueueStore(runtime?: AgentContext): ChatQueueStorePort {
+  const chatService = runtime?.agent?.pluginInstances?.get?.("chat") as
+    | { queueStore?: ChatQueueStorePort }
+    | undefined;
+  if (chatService?.queueStore) {
+    return chatService.queueStore;
+  }
+  return sharedChatQueueStore;
+}