@downcity/agent 1.1.1

package/src/services/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 "@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

@@ -0,0 +1,49 @@
+/**
+ * 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

@@ -0,0 +1,63 @@
+/**
+ * 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

@@ -0,0 +1,89 @@
+/**
+ * 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/PluginPoints.ts

@@ -0,0 +1,78 @@
+/**
+ * Chat service plugin 点定义。
+ *
+ * 关键点（中文）
+ * - plugin 点由 chat service 定义，不由具体 plugin 定义。
+ * - service 只依赖这些稳定点名，具体 plugin 负责实现其中某些点。
+ * - 后续新增 chat 生命周期 plugin 点，也应统一收敛到这里。
+ */
+
+/**
+ * Chat service 对外暴露的 plugin 点目录。
+ */
+export const CHAT_PLUGIN_POINTS = {
+  /**
+   * 增强入站消息正文。
+   *
+   * 说明（中文）
+   * - service 先构造基础 attachment/body 文本。
+   * - plugin 通过 pipeline 往 `pluginSections` 中追加中间块。
+   */
+  augmentInbound: "chat.augmentInbound",
+  /**
+   * 回复前文本增强。
+   *
+   * 说明（中文）
+   * - service 在真正回发到 channel 前调用。
+   * - plugin 可在这里做收尾改写、格式整理、签名注入等。
+   */
+  beforeReply: "chat.beforeReply",
+  /**
+   * 回复后事件通知。
+   *
+   * 说明（中文）
+   * - service 在一次回复发送完成后触发。
+   * - plugin 可在这里做审计、统计、回执同步等副作用。
+   */
+  afterReply: "chat.afterReply",
+  /**
+   * 入队前数据增强。
+   *
+   * 说明（中文）
+   * - service 在 append ingress / enqueue 之前调用。
+   * - plugin 可在这里改写入队文本或补充 extra metadata。
+   */
+  beforeEnqueue: "chat.beforeEnqueue",
+  /**
+   * 入队后事件通知。
+   *
+   * 说明（中文）
+   * - service 在消息真正入队完成后调用。
+   * - plugin 可在这里做统计、观测、调试落点。
+   */
+  afterEnqueue: "chat.afterEnqueue",
+  /**
+   * 观测入站主体信息。
+   *
+   * 说明（中文）
+   * - 仅做副作用记录，不返回值。
+   * - 典型实现方是 auth plugin。
+   */
+  observePrincipal: "chat.observePrincipal",
+  /**
+   * 判定当前入站消息是否允许执行。
+   *
+   * 说明（中文）
+   * - 由 service 在 ingress 阶段显式调用。
+   * - 典型实现方是 auth plugin。
+   */
+  authorizeIncoming: "chat.authorizeIncoming",
+  /**
+   * 解析当前用户角色。
+   *
+   * 说明（中文）
+   * - 主要用于在 history / queue metadata 中补齐授权上下文。
+   * - 典型实现方是 auth plugin。
+   */
+  resolveUserRole: "chat.resolveUserRole",
+} as const;

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

@@ -0,0 +1,43 @@
+/**
+ * QueuedUserMessage：构造入队执行消息文本。
+ *
+ * 关键点（中文）
+ * - 统一生成 `<info>...</info>` 头部，供模型读取用户与本次请求元信息。
+ * - chat 路由环境不再放入 `<info>`，改由 system prompt 注入。
+ * - 供 chat 入站执行与其他复用入口共用，避免重复实现。
+ */
+
+import type { QueuedUserInfoInput } from "@/shared/types/ChatPromptContext.js";
+
+function normalizeInfoValue(value: unknown): string {
+  const text = String(value ?? "").replace(/\r?\n/g, " ").trim();
+  if (!text) return "";
+  return text.replace(/</g, "&#60;").replace(/>/g, "&#62;");
+}
+
+/**
+ * 构造“入队 user message”文本。
+ *
+ * 说明（中文）
+ * - 顶部 `<info>` 为内部语义块，仅记录 user/request 元信息。
+ * - 正文为用户原始输入（可为空）。
+ */
+export function buildQueuedUserMessageWithInfo(params: {
+  text: string;
+} & QueuedUserInfoInput): string {
+  const infoLines = [
+    `message_id: ${normalizeInfoValue(params.messageId || "unknown")}`,
+    `user_id: ${normalizeInfoValue(params.userId || "unknown")}`,
+    `username: ${normalizeInfoValue(params.username || "unknown")}`,
+    `role_id: ${normalizeInfoValue(params.roleId || "unknown")}`,
+    `permissions: ${normalizeInfoValue((params.permissions || []).join(",") || "none")}`,
+    `received_at: ${normalizeInfoValue(params.receivedAt || new Date().toISOString())}`,
+  ];
+  if (normalizeInfoValue(params.userTimezone)) {
+    infoLines.push(`user_timezone: ${normalizeInfoValue(params.userTimezone)}`);
+  }
+  const infoBlock = `<info>\n${infoLines.join("\n")}\n</info>`;
+  const body = String(params.text ?? "").trim();
+  if (!body) return infoBlock;
+  return `${infoBlock}\n\n${body}`;
+}

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

@@ -0,0 +1,85 @@
+/**
+ * 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 } : {}),
+  };
+}

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

@@ -0,0 +1,78 @@
+/**
+ * Chat reply dispatch helper。
+ *
+ * 关键点（中文）
+ * - 把 chat 回复前/回复后的扩展点统一收敛到这里。
+ * - 仅服务 agent 执行生命周期，不覆盖手动 `chat send`。
+ */
+
+import type { AgentContext } from "@/types/agent/AgentContext.js";
+import type { ChatReplyDispatchInput, ChatReplyEffectInput } from "@/shared/types/ChatPlugin.js";
+import type { JsonValue } from "@/shared/types/Json.js";
+import type { ChatDispatchChannel } from "@services/chat/types/ChatDispatcher.js";
+import { CHAT_PLUGIN_POINTS } from "@services/chat/runtime/PluginPoints.js";
+import { resolveDispatchTargetByChatKey } from "@services/chat/runtime/ChatkeySend.js";
+
+function normalizeText(value: string | undefined): string {
+  return String(value || "").trim();
+}
+
+/**
+ * 回复前文本增强。
+ */
+export async function prepareChatReplyText(params: {
+  context: AgentContext;
+  input: ChatReplyDispatchInput;
+}): Promise<string> {
+  const input = {
+    ...params.input,
+    text: normalizeText(params.input.text),
+  };
+  if (!input.text) return "";
+
+  const next = await params.context.plugins.pipeline<JsonValue>(
+    CHAT_PLUGIN_POINTS.beforeReply,
+    input as unknown as JsonValue,
+  );
+  const record =
+    next && typeof next === "object" && !Array.isArray(next)
+      ? (next as Record<string, unknown>)
+      : {};
+  return normalizeText(typeof record.text === "string" ? record.text : input.text);
+}
+
+/**
+ * 回复后事件分发。
+ */
+export async function emitChatReplyEffect(params: {
+  context: AgentContext;
+  input: ChatReplyEffectInput;
+}): Promise<void> {
+  await params.context.plugins.effect(
+    CHAT_PLUGIN_POINTS.afterReply,
+    params.input as unknown as JsonValue,
+  );
+}
+
+/**
+ * 基于 chatKey 补齐回复目标上下文。
+ */
+export async function resolveChatReplyTarget(params: {
+  context: AgentContext;
+  chatKey: string;
+}): Promise<{
+  channel?: ChatDispatchChannel;
+  chatId?: string;
+  messageId?: string;
+}> {
+  const target = await resolveDispatchTargetByChatKey({
+    context: params.context,
+    chatKey: params.chatKey,
+  });
+  if (!target) return {};
+  return {
+    channel: target.channel,
+    chatId: target.chatId,
+    ...(target.messageId ? { messageId: target.messageId } : {}),
+  };
+}