@downcity/agent 1.1.23 → 1.1.32

package/src/plugin/builtins/chat/runtime/ChatSession.ts

@@ -0,0 +1,156 @@
+/**
+ * ChatSession：chat 专用 Executor 实现。
+ *
+ * 关键点（中文）
+ * - ChatSession 在实例化时持有自己的 context composer 实例。
+ * - chat 当前 turn 的 step 合并/step 回发状态都绑定在 Session 自身，不再新增 `runChat` 一层入口。
+ * - 外层仍只调用标准 `run(...)`；chat 语义由 ChatSession 内部收敛。
+ */
+
+import type { LanguageModel, Tool } from "ai";
+import { Executor } from "@session/Executor.js";
+import type { SessionHistoryComposer } from "@session/composer/history/SessionHistoryComposer.js";
+import type { SessionHistoryStore } from "@/session/store/history/SessionHistoryStore.js";
+import type { SessionCompactionComposer } from "@session/composer/compaction/SessionCompactionComposer.js";
+import type { SessionSystemComposer } from "@session/composer/system/SessionSystemComposer.js";
+import type { ChatSessionContextComposer } from "@/plugin/builtins/chat/runtime/ChatSessionContextComposer.js";
+import type { Logger } from "@/utils/logger/Logger.js";
+import type { SessionAssistantStepCallback } from "@/session/types/SessionRun.js";
+import type { SessionRunResult } from "@/session/types/SessionRun.js";
+import type { ChatSessionTurnState } from "@/plugin/builtins/chat/runtime/ChatSessionTypes.js";
+
+type ChatSessionOptions = {
+  /**
+   * 当前会话 ID。
+   */
+  sessionId: string;
+
+  /**
+   * 当前 session 的 history store。
+   */
+  historyStore: SessionHistoryStore;
+
+  /**
+   * 当前 session 的 history composer。
+   */
+  historyComposer: SessionHistoryComposer;
+
+  /**
+   * 读取当前 session 使用的模型实例。
+   */
+  getModel: () => LanguageModel | undefined;
+
+  /**
+   * 统一日志器。
+   */
+  logger: Logger;
+
+  /**
+   * 当前 session 对应的 compaction Composer。
+   */
+  compactionComposer: SessionCompactionComposer;
+
+  /**
+   * 当前 session 对应的 system Composer。
+   */
+  systemComposer: SessionSystemComposer;
+
+  /**
+   * 获取当前可用工具集合。
+   */
+  getTools: () => Record<string, Tool>;
+
+  /**
+   * 当前 session 绑定的 chat context composer。
+   */
+  contextComposer: ChatSessionContextComposer;
+
+  /**
+   * session 更新后的异步回调。
+   */
+  runAfterSessionUpdated?: (sessionId: string) => Promise<void>;
+};
+
+/**
+ * Chat 专用 Session。
+ */
+export class ChatSession extends Executor {
+  /**
+   * ChatSession 持有的 composer 实例。
+   */
+  readonly contextComposer: ChatSessionContextComposer;
+
+  private activeTurnState: ChatSessionTurnState | null = null;
+
+  constructor(options: ChatSessionOptions) {
+    const contextComposer = options.contextComposer;
+    super({
+      sessionId: options.sessionId,
+      historyStore: options.historyStore,
+      historyComposer: options.historyComposer,
+      getModel: options.getModel,
+      logger: options.logger,
+      compactionComposer: options.compactionComposer,
+      systemComposer: options.systemComposer,
+      getTools: options.getTools,
+      contextComposer,
+      ...(options.runAfterSessionUpdated
+        ? { runAfterSessionUpdated: options.runAfterSessionUpdated }
+        : {}),
+    });
+    this.contextComposer = contextComposer;
+  }
+
+  /**
+   * 读取当前绑定的 chat turn 状态。
+   */
+  getTurnState(): ChatSessionTurnState | null {
+    return this.activeTurnState;
+  }
+
+  /**
+   * 处理一次 assistant step 回发。
+   *
+   * 关键点（中文）
+   * - step 持久化由基类 `Session.run` 先完成。
+   * - 这里仅负责把当前 turn 绑定的外部回发钩子继续调出去。
+   */
+  private readonly forwardAssistantStep: SessionAssistantStepCallback = async (
+    step,
+  ): Promise<void> => {
+    const callback = this.activeTurnState?.onAssistantStepCallback;
+    if (typeof callback !== "function") return;
+    await callback(step);
+  };
+
+  /**
+   * 运行当前 chat session 的一次请求。
+   *
+   * 关键点（中文）
+   * - 外层继续走统一的内部执行入口。
+   * - ChatSession 只是在 run 生命周期里临时绑定 turn 状态给自己的 composer。
+   */
+  override async run(params: {
+    query: string;
+    onStepCallback?: ChatSessionTurnState["onStepCallback"];
+    onAssistantStepCallback?: ChatSessionTurnState["onAssistantStepCallback"];
+  }): Promise<SessionRunResult> {
+    this.activeTurnState = {
+      ...(typeof params.onStepCallback === "function"
+        ? { onStepCallback: params.onStepCallback }
+        : {}),
+      ...(typeof params.onAssistantStepCallback === "function"
+        ? { onAssistantStepCallback: params.onAssistantStepCallback }
+        : {}),
+    };
+    try {
+      return await super.run({
+        query: params.query,
+        onStepCallback: params.onStepCallback,
+        onAssistantStepCallback: this.forwardAssistantStep,
+      });
+    } finally {
+      this.activeTurnState = null;
+    }
+  }
+}

package/src/plugin/builtins/chat/runtime/ChatSessionContextComposer.ts

@@ -0,0 +1,106 @@
+/**
+ * ChatSessionContextComposer：chat 专用 context composer。
+ *
+ * 关键点（中文）
+ * - 由 chat 层在 Session 实例化时注入，不再依赖 run 时层层传 callback。
+ * - step 合并消息读取自 ChatSession 当前绑定的 turn context。
+ * - 其余能力（tools / fallback assistant）继续复用默认本地实现。
+ */
+
+import type { ModelMessage, Tool } from "ai";
+import { drainInjectedUserMessages } from "@session/SessionRunScope.js";
+import { LocalSessionContextComposer } from "@session/composer/context/LocalSessionContextComposer.js";
+import type { SessionMessageV1 } from "@/session/types/SessionMessages.js";
+import type { SessionSystemMessage } from "@/session/types/SessionPrompts.js";
+import type { ChatSessionTurnState } from "@/plugin/builtins/chat/runtime/ChatSessionTypes.js";
+
+type ChatSessionContextComposerOptions = {
+  /**
+   * 当前 session 标识。
+   */
+  sessionId: string;
+
+  /**
+   * 读取当前可用工具集合。
+   */
+  getTools: () => Record<string, Tool>;
+
+  /**
+   * 读取当前已绑定的 chat turn 状态。
+   */
+  getTurnState: () => ChatSessionTurnState | null;
+};
+
+/**
+ * ChatSession 专用 context composer。
+ */
+export class ChatSessionContextComposer extends LocalSessionContextComposer {
+  private readonly getTurnState: ChatSessionContextComposerOptions["getTurnState"];
+
+  constructor(options: ChatSessionContextComposerOptions) {
+    super({
+      sessionId: options.sessionId,
+      getTools: options.getTools,
+    });
+    this.getTurnState = options.getTurnState;
+  }
+
+  createPrepareStepHandler(
+    input: {
+      system: SessionSystemMessage[];
+      appendMergedUserMessages: (
+        messages: SessionMessageV1[],
+      ) => Promise<ModelMessage[]>;
+    },
+  ): (input: { messages?: ModelMessage[] }) => Promise<{
+    system: SessionSystemMessage[];
+    messages?: ModelMessage[];
+  }> {
+    return async ({
+      messages,
+    }: {
+      messages?: ModelMessage[];
+    }): Promise<{
+      system: SessionSystemMessage[];
+      messages?: ModelMessage[];
+    }> => {
+      const injectedMessages = drainInjectedUserMessages();
+      const turnState = this.getTurnState();
+      const onStepCallback = turnState?.onStepCallback;
+      if (
+        typeof onStepCallback !== "function" &&
+        injectedMessages.length === 0
+      ) {
+        return { system: input.system };
+      }
+
+      const incomingMessages: ModelMessage[] = Array.isArray(messages)
+        ? messages
+        : [];
+      let outMessages: ModelMessage[] | undefined;
+      try {
+        const mergedMessages =
+          typeof onStepCallback === "function"
+            ? await onStepCallback()
+            : [];
+        const mergedWithInjected = [
+          ...injectedMessages,
+          ...(Array.isArray(mergedMessages) ? mergedMessages : []),
+        ];
+        const mergedModelMessages = await input.appendMergedUserMessages(
+          mergedWithInjected,
+        );
+        if (mergedModelMessages.length > 0) {
+          // 关键点（中文）：保持当前 step 顺序，仅把新增 chat user 消息追加到末尾。
+          outMessages = [...incomingMessages, ...mergedModelMessages];
+        }
+      } catch {
+        // ignore merge hook failures
+      }
+      return {
+        system: input.system,
+        ...(Array.isArray(outMessages) ? { messages: outMessages } : {}),
+      };
+    };
+  }
+}

package/src/plugin/builtins/chat/runtime/ChatSessionDelete.ts

@@ -0,0 +1,95 @@
+/**
+ * ChatSessionDelete：按 sessionId 彻底删除 chat 会话数据。
+ *
+ * 关键点（中文）
+ * - 删除路由映射（`.downcity/channel/meta.json`）
+ * - 删除 chat 审计目录（`.downcity/chat/<sessionId>/`）
+ * - 删除 core session 目录（`.downcity/agents/<agentId>/sessions/<sessionId>/`）
+ * - 清理运行中 agent 与队列，避免残留任务继续执行
+ */
+
+import fs from "fs-extra";
+import path from "node:path";
+import type { AgentContext } from "@/core/AgentContextTypes.js";
+import { resolveChatQueueStore } from "@/plugin/builtins/chat/runtime/ChatQueue.js";
+import { removeChatMetaBySessionId } from "@/plugin/builtins/chat/runtime/ChatMetaStore.js";
+
+function normalizeSessionId(sessionId: string): string {
+  return String(sessionId || "").trim();
+}
+
+/**
+ * 彻底删除一个 chat session。
+ *
+ * 关键点（中文）
+ * - 幂等：目标不存在时返回 success + deleted=false，避免上层重试复杂化。
+ */
+export async function deleteChatSessionById(params: {
+  context: AgentContext;
+  sessionId: string;
+}): Promise<{
+  success: boolean;
+  sessionId: string;
+  deleted: boolean;
+  removedMeta: boolean;
+  removedChatDir: boolean;
+  removedSessionDir: boolean;
+  error?: string;
+}> {
+  const sessionId = normalizeSessionId(params.sessionId);
+  if (!sessionId) {
+    return {
+      success: false,
+      sessionId: "",
+      deleted: false,
+      removedMeta: false,
+      removedChatDir: false,
+      removedSessionDir: false,
+      error: "Missing sessionId",
+    };
+  }
+
+  try {
+    // 关键点（中文）：先停执行，再删文件，避免删除过程中仍有任务写入。
+    params.context.session.get(sessionId).clearExecutor();
+    resolveChatQueueStore(params.context).clear(sessionId);
+
+    const removedMetaResult = await removeChatMetaBySessionId({
+      context: params.context,
+      sessionId,
+    });
+
+    const chatDir = path.join(params.context.rootPath, ".downcity", "chat", sessionId);
+    const sessionDir = params.context.paths.getDowncitySessionDirPath(sessionId);
+    const hadChatDir = await fs.pathExists(chatDir);
+    const hadSessionDir = await fs.pathExists(sessionDir);
+    if (hadChatDir) {
+      await fs.remove(chatDir);
+    }
+    if (hadSessionDir) {
+      await fs.remove(sessionDir);
+    }
+
+    const deleted =
+      removedMetaResult.removed || hadChatDir || hadSessionDir;
+
+    return {
+      success: true,
+      sessionId,
+      deleted,
+      removedMeta: removedMetaResult.removed,
+      removedChatDir: hadChatDir,
+      removedSessionDir: hadSessionDir,
+    };
+  } catch (error) {
+    return {
+      success: false,
+      sessionId,
+      deleted: false,
+      removedMeta: false,
+      removedChatDir: false,
+      removedSessionDir: false,
+      error: String(error),
+    };
+  }
+}

package/src/plugin/builtins/chat/runtime/ChatkeySend.ts

@@ -0,0 +1,187 @@
+/**
+ * Send text to a target chat using chatKey.
+ *
+ * 设计动机（中文）
+ * - Task runner / scheduler 需要在“非当前对话上下文”向指定 chatKey 投递消息
+ * - 复用现有 dispatcher 与 chat meta（尤其 QQ 的被动回复依赖 messageId）
+ *
+ * 注意
+ * - 这里是运行时内部能力（不是 tool）；tool `chat_contact_send` 也会复用本实现
+ */
+
+import { getChatSender } from "./ChatSendRegistry.js";
+import type {
+  ChatDispatchAction,
+  ChatDispatchChannel,
+} from "@/plugin/builtins/chat/types/ChatDispatcher.js";
+import type { AgentContext } from "@/core/AgentContextTypes.js";
+import { readChatMetaBySessionId } from "./ChatMetaStore.js";
+
+/**
+ * 解析实际分发目标。
+ *
+ * 规则（中文）
+ * - 仅使用 service/builtins/chat 维护的 session 路由映射。
+ * - 不再支持 legacy chatKey 字符串解析回退。
+ */
+export async function resolveDispatchTargetByChatKey(params: {
+  context: AgentContext;
+  chatKey: string;
+}): Promise<{
+  channel: ChatDispatchChannel;
+  chatId: string;
+  chatType?: string;
+  messageThreadId?: number;
+  messageId?: string;
+} | null> {
+  const storedMeta = await readChatMetaBySessionId({
+    context: params.context,
+    sessionId: params.chatKey,
+  });
+  const channel = storedMeta?.channel;
+  const chatId = String(storedMeta?.chatId || "").trim();
+  if (!channel || !chatId) return null;
+
+  const chatType =
+    typeof storedMeta?.targetType === "string" && storedMeta.targetType
+      ? storedMeta.targetType
+      : undefined;
+  const messageThreadId =
+    typeof storedMeta?.threadId === "number" &&
+    Number.isFinite(storedMeta.threadId)
+      ? storedMeta.threadId
+      : undefined;
+  const messageId =
+    typeof storedMeta?.messageId === "string" && storedMeta.messageId
+      ? storedMeta.messageId
+      : undefined;
+
+  return {
+    channel: channel as ChatDispatchChannel,
+    chatId,
+    ...(typeof chatType === "string" && chatType ? { chatType } : {}),
+    ...(typeof messageThreadId === "number" ? { messageThreadId } : {}),
+    ...(typeof messageId === "string" && messageId ? { messageId } : {}),
+  };
+}
+
+/**
+ * 按 chatKey 发送文本到对应平台。
+ *
+ * 流程（中文）
+ * 1) 通过 sessionId 读取映射并定位 channel dispatcher
+ * 2) 从 chat meta 回填 chatType/threadId/messageId
+ * 3) 合并参数后调用 dispatcher 发送
+ */
+export async function sendTextByChatKey(params: {
+  context: AgentContext;
+  chatKey: string;
+  text: string;
+  replyToMessage?: boolean;
+  messageId?: string;
+}): Promise<{ success: boolean; error?: string }> {
+  const context = params.context;
+  const chatKey = String(params.chatKey || "").trim();
+  const text = String(params.text ?? "");
+  if (!chatKey) return { success: false, error: "Missing chatKey" };
+  if (!text.trim()) return { success: true };
+
+  const target = await resolveDispatchTargetByChatKey({ context, chatKey });
+  if (!target) {
+    return {
+      success: false,
+      error: `Unsupported sessionId for dispatch: ${chatKey}`,
+    };
+  }
+
+  const channel = target.channel;
+  const chatId = target.chatId;
+
+  const dispatcher = getChatSender(channel);
+  if (!dispatcher) {
+    return {
+      success: false,
+      error: `No dispatcher registered for channel: ${channel}`,
+    };
+  }
+
+  const chatType = target.chatType;
+  const messageThreadId = target.messageThreadId;
+  const explicitMessageId = String(params.messageId || "").trim();
+  const messageId = explicitMessageId || target.messageId;
+  const shouldReplyToMessage = params.replyToMessage === true;
+
+  if (channel === "qq") {
+    if (!chatType || !messageId) {
+      return {
+        success: false,
+        error:
+          "QQ requires chatType + messageId to send a reply. Ask the target user to send a message first so Downcity can record latest chat meta.",
+      };
+    }
+  }
+
+  return dispatcher.sendText({
+    chatId,
+    text,
+    ...(typeof messageThreadId === "number" ? { messageThreadId } : {}),
+    ...(typeof chatType === "string" && chatType ? { chatType } : {}),
+    ...(typeof messageId === "string" && messageId ? { messageId } : {}),
+    ...(shouldReplyToMessage ? { replyToMessage: true } : {}),
+  });
+}
+
+/**
+ * 按 chatKey 发送平台动作（typing/react）。
+ *
+ * 流程（中文）
+ * 1) 通过 sessionId 读取映射并定位 channel dispatcher
+ * 2) 合并目标元信息与显式参数（显式 messageId 优先）
+ * 3) 调用 dispatcher.sendAction
+ */
+export async function sendActionByChatKey(params: {
+  context: AgentContext;
+  chatKey: string;
+  action: ChatDispatchAction;
+  messageId?: string;
+  reactionEmoji?: string;
+  reactionIsBig?: boolean;
+}): Promise<{ success: boolean; error?: string }> {
+  const context = params.context;
+  const chatKey = String(params.chatKey || "").trim();
+  if (!chatKey) return { success: false, error: "Missing chatKey" };
+  if (!params.action) return { success: false, error: "Missing action" };
+
+  const target = await resolveDispatchTargetByChatKey({ context, chatKey });
+  if (!target) {
+    return {
+      success: false,
+      error: `Unsupported sessionId for dispatch: ${chatKey}`,
+    };
+  }
+
+  const dispatcher = getChatSender(target.channel);
+  if (!dispatcher || typeof dispatcher.sendAction !== "function") {
+    return {
+      success: false,
+      error: `No action dispatcher registered for channel: ${target.channel}`,
+    };
+  }
+
+  const messageId = String(params.messageId || "").trim() || target.messageId;
+  return dispatcher.sendAction({
+    chatId: target.chatId,
+    action: params.action,
+    ...(typeof target.messageThreadId === "number"
+      ? { messageThreadId: target.messageThreadId }
+      : {}),
+    ...(typeof target.chatType === "string" && target.chatType
+      ? { chatType: target.chatType }
+      : {}),
+    ...(typeof messageId === "string" && messageId ? { messageId } : {}),
+    ...(typeof params.reactionEmoji === "string" && params.reactionEmoji.trim()
+      ? { reactionEmoji: params.reactionEmoji.trim() }
+      : {}),
+    ...(params.reactionIsBig === true ? { reactionIsBig: true } : {}),
+  });
+}

package/src/plugin/builtins/chat/runtime/DirectDispatchParser.ts

@@ -0,0 +1,158 @@
+/**
+ * DirectDispatchParser：direct 模式 assistant 文本解析器。
+ *
+ * 关键点（中文）
+ * - 默认把 assistant 文本原样当作用户可见正文发送。
+ * - frontmatter metadata 语义与 `city chat send` 保持一致。
+ * - 额外保留 `react` 字段用于 direct 模式贴表情。
+ */
+
+import type {
+  DirectReactTagPayload,
+  ResolvedDirectDispatchPlan,
+  ResolvedDirectReactionPayload,
+  ResolvedDirectTextPayload,
+} from "@/plugin/builtins/chat/types/DirectDispatch.js";
+import {
+  buildChatMessageText,
+  parseChatMessageMarkup,
+} from "@/plugin/builtins/chat/runtime/ChatMessageMarkup.js";
+import { parseChatSendOptionsFromMetadata } from "@/plugin/builtins/chat/runtime/ChatSendMetadata.js";
+import type { ChatMessageSegment } from "@/plugin/builtins/chat/types/ChatMessageMarkup.js";
+
+function normalizeText(value: unknown): string {
+  return String(value ?? "").trim();
+}
+
+function parseBoolean(value: unknown): boolean {
+  if (typeof value === "boolean") return value;
+  const text = normalizeText(value).toLowerCase();
+  return text === "true" || text === "1" || text === "yes";
+}
+
+function parseReactionFromMetadata(value: unknown): DirectReactTagPayload | null {
+  if (typeof value === "string") {
+    const emoji = normalizeText(value);
+    return emoji ? { emoji } : null;
+  }
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return null;
+  }
+  const raw = value as Record<string, unknown>;
+  const emoji = normalizeText(raw.emoji);
+  if (!emoji) return null;
+  const big = parseBoolean(raw.big);
+  return {
+    emoji,
+    ...(big ? { big: true } : {}),
+  };
+}
+
+function parseReactionsFromMetadata(
+  metadata: Record<string, unknown>,
+): DirectReactTagPayload[] {
+  const out: DirectReactTagPayload[] = [];
+  const raw = metadata.react;
+  if (!raw) return out;
+  const list = Array.isArray(raw) ? raw : [raw];
+  for (const item of list) {
+    const parsed = parseReactionFromMetadata(item);
+    if (!parsed) continue;
+    out.push(parsed);
+  }
+  return out;
+}
+
+function resolveTextPlan(params: {
+  fallbackChatKey: string;
+  metadata: Record<string, unknown>;
+  segments: ChatMessageSegment[];
+}): ResolvedDirectTextPayload | null {
+  const sendOptions = parseChatSendOptionsFromMetadata({
+    metadata: params.metadata,
+    strict: false,
+  });
+  const chatKey = normalizeText(sendOptions.chatKey || params.fallbackChatKey);
+  const text = buildChatMessageText({
+    segments: params.segments,
+  });
+  if (!chatKey || !text) return null;
+
+  return {
+    text,
+    chatKey,
+    replyToMessage: sendOptions.replyToMessage === true,
+    ...(typeof sendOptions.messageId === "string" && sendOptions.messageId
+      ? { messageId: sendOptions.messageId }
+      : {}),
+    ...(typeof sendOptions.delayMs === "number"
+      ? { delayMs: sendOptions.delayMs }
+      : {}),
+    ...(typeof sendOptions.sendAtMs === "number"
+      ? { sendAtMs: sendOptions.sendAtMs }
+      : {}),
+  };
+}
+
+function resolveReactionPlans(params: {
+  fallbackChatKey: string;
+  metadata: Record<string, unknown>;
+  reacts: DirectReactTagPayload[];
+}): ResolvedDirectReactionPayload[] {
+  const out: ResolvedDirectReactionPayload[] = [];
+  const sendOptions = parseChatSendOptionsFromMetadata({
+    metadata: params.metadata,
+    strict: false,
+  });
+  const chatKey = normalizeText(sendOptions.chatKey || params.fallbackChatKey);
+  const messageId = normalizeText(sendOptions.messageId);
+  if (!chatKey) return out;
+
+  for (const react of params.reacts) {
+    const emoji = normalizeText(react.emoji);
+    if (!emoji) continue;
+    out.push({
+      emoji,
+      chatKey,
+      ...(messageId ? { messageId } : {}),
+      big: react.big === true,
+    });
+  }
+  return out;
+}
+
+/**
+ * 从 assistant 文本中解析 direct 出站执行计划。
+ *
+ * 协议（中文）
+ * - frontmatter metadata：与 `city chat send` 参数保持一致。
+ * - 附件统一使用 `<file type=\"document|photo|voice|audio|video\">path</file>`。
+ * - `react` 仍仅用于 direct 模式的反应动作。
+ */
+export function parseDirectDispatchAssistantText(params: {
+  assistantText: string;
+  fallbackChatKey: string;
+}): ResolvedDirectDispatchPlan | null {
+  const source = String(params.assistantText ?? "");
+  const fallbackChatKey = normalizeText(params.fallbackChatKey);
+  if (!normalizeText(source) || !fallbackChatKey) return null;
+
+  const parsed = parseChatMessageMarkup(source);
+  const reacts = parseReactionsFromMetadata(parsed.metadata);
+  const textPlan = resolveTextPlan({
+    fallbackChatKey,
+    metadata: parsed.metadata,
+    segments: parsed.segments,
+  });
+  const reactionPlans = resolveReactionPlans({
+    fallbackChatKey,
+    metadata: parsed.metadata,
+    reacts,
+  });
+
+  if (!textPlan && reactionPlans.length === 0) return null;
+  return {
+    text: textPlan,
+    reactions: reactionPlans,
+  };
+}