@downcity/agent 1.1.1 → 1.1.5

package/src/services/chat/runtime/ChatkeySend.ts

@@ -1,187 +0,0 @@
-/**
- * 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 "@services/chat/types/ChatDispatcher.js";
-import type { AgentContext } from "@/types/agent/AgentContext.js";
-import { readChatMetaBySessionId } from "./ChatMetaStore.js";
-
-/**
- * 解析实际分发目标。
- *
- * 规则（中文）
- * - 仅使用 services/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/services/chat/runtime/DirectDispatchParser.ts

@@ -1,158 +0,0 @@
-/**
- * DirectDispatchParser：direct 模式 assistant 文本解析器。
- *
- * 关键点（中文）
- * - 默认把 assistant 文本原样当作用户可见正文发送。
- * - frontmatter metadata 语义与 `city chat send` 保持一致。
- * - 额外保留 `react` 字段用于 direct 模式贴表情。
- */
-
-import type {
-  DirectReactTagPayload,
-  ResolvedDirectDispatchPlan,
-  ResolvedDirectReactionPayload,
-  ResolvedDirectTextPayload,
-} from "@services/chat/types/DirectDispatch.js";
-import {
-  buildChatMessageText,
-  parseChatMessageMarkup,
-} from "@services/chat/runtime/ChatMessageMarkup.js";
-import { parseChatSendOptionsFromMetadata } from "@services/chat/runtime/ChatSendMetadata.js";
-import type { ChatMessageSegment } from "@services/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,
-  };
-}

package/src/services/chat/runtime/EnqueueDispatch.ts

@@ -1,49 +0,0 @@
-/**
- * Chat enqueue dispatch helper。
- *
- * 关键点（中文）
- * - 统一封装入队前/后的扩展点调用。
- * - service 通过这里暴露 queue 生命周期，不直接散落调用细节。
- */
-
-import type { AgentContext } from "@/types/agent/AgentContext.js";
-import type {
-  ChatEnqueueEffectInput,
-  ChatEnqueuePipelineInput,
-} from "@/shared/types/ChatPlugin.js";
-import type { JsonValue } from "@/shared/types/Json.js";
-import { CHAT_PLUGIN_POINTS } from "@services/chat/runtime/PluginPoints.js";
-
-function normalizeText(value: string): string {
-  return String(value || "").trim();
-}
-
-/**
- * 入队前增强。
- */
-export async function prepareChatEnqueue(params: {
-  context: AgentContext;
-  input: ChatEnqueuePipelineInput;
-}): Promise<ChatEnqueuePipelineInput> {
-  const normalized: ChatEnqueuePipelineInput = {
-    ...params.input,
-    text: normalizeText(params.input.text),
-  };
-  return (params.context.plugins.pipeline<JsonValue>(
-    CHAT_PLUGIN_POINTS.beforeEnqueue,
-    normalized as unknown as JsonValue,
-  ) as unknown) as Promise<ChatEnqueuePipelineInput>;
-}
-
-/**
- * 入队后通知。
- */
-export async function emitChatEnqueueEffect(params: {
-  context: AgentContext;
-  input: ChatEnqueueEffectInput;
-}): Promise<void> {
-  await params.context.plugins.effect(
-    CHAT_PLUGIN_POINTS.afterEnqueue,
-    params.input as unknown as JsonValue,
-  );
-}

package/src/services/chat/runtime/InboundAugment.ts

@@ -1,63 +0,0 @@
-/**
- * Chat inbound augment helper。
- *
- * 关键点（中文）
- * - chat service 先构造基础输入，再交给 plugin pipeline 做增强。
- * - 最终拼装顺序固定为：attachmentText -> pluginSections -> bodyText。
- */
-
-import type { AgentContext } from "@/types/agent/AgentContext.js";
-import type { ChatInboundAugmentInput } from "@/shared/types/ChatPlugin.js";
-import type { JsonValue } from "@/shared/types/Json.js";
-import { CHAT_PLUGIN_POINTS } from "@services/chat/runtime/PluginPoints.js";
-
-function normalizeText(value: string | undefined): string | undefined {
-  const text = String(value || "").trim();
-  return text || undefined;
-}
-
-/**
- * 执行 chat 入站增强 pipeline。
- */
-export async function augmentChatInboundInput(params: {
-  context: AgentContext;
-  input: ChatInboundAugmentInput;
-}): Promise<ChatInboundAugmentInput> {
-  const normalized: ChatInboundAugmentInput = {
-    ...params.input,
-    ...(params.input.chatType ? { chatType: params.input.chatType } : {}),
-    ...(params.input.chatKey ? { chatKey: params.input.chatKey } : {}),
-    ...(params.input.messageId ? { messageId: params.input.messageId } : {}),
-    ...(normalizeText(params.input.attachmentText)
-      ? { attachmentText: normalizeText(params.input.attachmentText) }
-      : {}),
-    ...(normalizeText(params.input.bodyText)
-      ? { bodyText: normalizeText(params.input.bodyText) }
-      : {}),
-    pluginSections: Array.isArray(params.input.pluginSections)
-      ? params.input.pluginSections.map((item) => String(item || "").trim()).filter(Boolean)
-      : [],
-    attachments: Array.isArray(params.input.attachments) ? params.input.attachments : [],
-  };
-
-  return (params.context.plugins.pipeline<JsonValue>(
-    CHAT_PLUGIN_POINTS.augmentInbound,
-    normalized as unknown as JsonValue,
-  ) as unknown) as Promise<ChatInboundAugmentInput>;
-}
-
-/**
- * 把增强后的 chat 入站输入拼成最终正文。
- */
-export function buildChatInboundText(input: ChatInboundAugmentInput): string {
-  return [
-    normalizeText(input.attachmentText),
-    ...(Array.isArray(input.pluginSections)
-      ? input.pluginSections.map((item) => normalizeText(item)).filter(Boolean)
-      : []),
-    normalizeText(input.bodyText),
-  ]
-    .filter(Boolean)
-    .join("\n\n")
-    .trim();
-}

package/src/services/chat/runtime/PluginDispatch.ts

@@ -1,89 +0,0 @@
-/**
- * PluginDispatch：chat 领域的 plugin 调用辅助。
- *
- * 关键点（中文）
- * - chat service 只依赖这里，不直接依赖某个具体 plugin 模块路径。
- * - 这里封装 chat 领域的 plugin 点调用语义，保持 service 边界稳定。
- */
-
-import type { AgentContext } from "@/types/agent/AgentContext.js";
-import type { JsonObject } from "@/shared/types/Json.js";
-import type {
-  AuthObservePrincipalPayload,
-  ChatAuthorizationEvaluateInput,
-  ChatAuthorizationRole,
-} from "@/shared/types/AuthPlugin.js";
-import type { ChatDispatchChannel } from "@services/chat/types/ChatDispatcher.js";
-import { CHAT_PLUGIN_POINTS } from "@services/chat/runtime/PluginPoints.js";
-
-function toRecord(value: unknown): Record<string, unknown> {
-  if (!value || typeof value !== "object" || Array.isArray(value)) return {};
-  return value as Record<string, unknown>;
-}
-
-/**
- * 观测入站主体。
- */
-export async function observeIncomingChatPrincipal(params: {
-  context: AgentContext;
-  channel: ChatDispatchChannel;
-  chatId: string;
-  chatType?: string;
-  chatTitle?: string;
-  userId?: string;
-  username?: string;
-}): Promise<void> {
-  await params.context.plugins.effect(CHAT_PLUGIN_POINTS.observePrincipal, {
-    channel: params.channel,
-    chatId: params.chatId,
-    ...(params.chatType ? { chatType: params.chatType } : {}),
-    ...(params.chatTitle ? { chatTitle: params.chatTitle } : {}),
-    ...(params.userId ? { userId: params.userId } : {}),
-    ...(params.username ? { username: params.username } : {}),
-  } as AuthObservePrincipalPayload as unknown as JsonObject);
-}
-
-/**
- * 校验入站消息是否允许执行。
- *
- * 关键点（中文）
- * - 这是 guard 语义：允许则静默返回，拒绝则直接抛错。
- * - 这样 chat service 可以像处理中间件一样串联 guard 点。
- */
-export async function guardIncomingChat(params: {
-  context: AgentContext;
-  channel: ChatDispatchChannel;
-  input: ChatAuthorizationEvaluateInput;
-}): Promise<void> {
-  await params.context.plugins.guard(
-    CHAT_PLUGIN_POINTS.authorizeIncoming,
-    {
-      channel: params.channel,
-      chatId: params.input.chatId,
-      ...(params.input.chatType ? { chatType: params.input.chatType } : {}),
-      ...(params.input.userId ? { userId: params.input.userId } : {}),
-      ...(params.input.username ? { username: params.input.username } : {}),
-      ...(params.input.chatTitle ? { chatTitle: params.input.chatTitle } : {}),
-    } as JsonObject,
-  );
-}
-
-/**
- * 解析用户角色。
- */
-export async function resolveIncomingChatUserRole(params: {
-  context: AgentContext;
-  channel: ChatDispatchChannel;
-  userId?: string;
-}): Promise<ChatAuthorizationRole | undefined> {
-  const result = await params.context.plugins.resolve<JsonObject, unknown>(
-    CHAT_PLUGIN_POINTS.resolveUserRole,
-    {
-      channel: params.channel,
-      ...(params.userId ? { userId: params.userId } : {}),
-    },
-  );
-  const role = toRecord(result);
-  if (!role.roleId) return undefined;
-  return role as unknown as ChatAuthorizationRole;
-}

package/src/services/chat/runtime/ReplyContextFormatter.ts

@@ -1,85 +0,0 @@
-/**
- * ReplyContextFormatter：reply 引用上下文格式化工具。
- *
- * 关键点（中文）
- * - 把平台 reply 信息稳定地拼进模型输入正文。
- * - 同时提供额外 metadata，便于 history / 调试链路查看。
- */
-
-import type { JsonObject } from "@/shared/types/Json.js";
-import type { InboundReplyContext } from "@services/chat/types/ReplyContext.js";
-
-function normalizeReplyValue(value: string | undefined): string | undefined {
-  const text = String(value || "").trim();
-  return text ? text : undefined;
-}
-
-/**
- * 将 reply 上下文转换为执行输入正文。
- *
- * 说明（中文）
- * - 当前消息正文为空时，也会保留 reply block，避免“只看见 reply、看不见被引用内容”。
- * - quote 与完整正文相同则自动去重，避免重复噪声。
- */
-export function buildReplyContextInstruction(params: {
-  text: string;
-  replyContext?: InboundReplyContext;
-}): string {
-  const body = String(params.text ?? "").trim();
-  const replyContext = params.replyContext;
-  if (!replyContext) return body;
-
-  const messageId = normalizeReplyValue(replyContext.messageId);
-  const actorName = normalizeReplyValue(replyContext.actorName);
-  const quoteText = normalizeReplyValue(replyContext.quoteText);
-  const replyText = normalizeReplyValue(replyContext.text);
-  const normalizedQuote =
-    quoteText && quoteText !== replyText ? quoteText : undefined;
-
-  if (!messageId && !actorName && !normalizedQuote && !replyText) {
-    return body;
-  }
-
-  const lines: string[] = ["<reply_context>"];
-  if (messageId) lines.push(`reply_message_id: ${messageId}`);
-  if (actorName) lines.push(`reply_actor_name: ${actorName}`);
-  if (normalizedQuote) {
-    lines.push("reply_quote:");
-    lines.push(normalizedQuote);
-  }
-  if (replyText) {
-    lines.push("reply_message:");
-    lines.push(replyText);
-  }
-  lines.push("</reply_context>");
-
-  if (!body) return lines.join("\n");
-  return `${lines.join("\n")}\n\n${body}`;
-}
-
-/**
- * 将 reply 上下文转换为 ingress extra。
- *
- * 说明（中文）
- * - 仅保留稳定、短小的字段。
- * - 方便在 Console / history 中直接看到引用信息。
- */
-export function buildReplyContextExtra(
-  replyContext?: InboundReplyContext,
-): JsonObject | undefined {
-  if (!replyContext) return undefined;
-
-  const messageId = normalizeReplyValue(replyContext.messageId);
-  const actorName = normalizeReplyValue(replyContext.actorName);
-  const text = normalizeReplyValue(replyContext.text);
-  const quoteText = normalizeReplyValue(replyContext.quoteText);
-  if (!messageId && !actorName && !text && !quoteText) return undefined;
-
-  return {
-    hasReplyContext: true,
-    ...(messageId ? { replyMessageId: messageId } : {}),
-    ...(actorName ? { replyActorName: actorName } : {}),
-    ...(text ? { replyText: text } : {}),
-    ...(quoteText ? { replyQuoteText: quoteText } : {}),
-  };
-}