@downcity/plugins 1.0.4

package/src/chat/runtime/PluginDispatch.ts

@@ -0,0 +1,89 @@
+/**
+ * PluginDispatch：chat 领域的 plugin 调用辅助。
+ *
+ * 关键点（中文）
+ * - chat plugin runtime 只依赖这里，不直接依赖某个具体 plugin 模块路径。
+ * - 这里封装 chat 领域的 plugin 点调用语义，保持 service 边界稳定。
+ */
+
+import type { AgentContext } from "@downcity/agent/internal/types/runtime/agent/AgentContext.js";
+import type { JsonObject } from "@downcity/agent/internal/types/common/Json.js";
+import type {
+  AuthObservePrincipalPayload,
+  ChatAuthorizationEvaluateInput,
+  ChatAuthorizationRole,
+} from "@/auth/types/AuthPlugin.js";
+import type { ChatDispatchChannel } from "@/chat/types/ChatDispatcher.js";
+import { CHAT_PLUGIN_POINTS } from "@/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 plugin runtime 可以像处理中间件一样串联 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/chat/runtime/PluginPoints.ts

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

package/src/chat/runtime/QueuedUserMessage.ts

@@ -0,0 +1,43 @@
+/**
+ * QueuedUserMessage：构造入队执行消息文本。
+ *
+ * 关键点（中文）
+ * - 统一生成 `<info>...</info>` 头部，供模型读取用户与本次请求元信息。
+ * - chat 路由环境不再放入 `<info>`，改由 system prompt 注入。
+ * - 供 chat 入站执行与其他复用入口共用，避免重复实现。
+ */
+
+import type { QueuedUserInfoInput } from "@/chat/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/chat/runtime/ReplyContextFormatter.ts

@@ -0,0 +1,85 @@
+/**
+ * ReplyContextFormatter：reply 引用上下文格式化工具。
+ *
+ * 关键点（中文）
+ * - 把平台 reply 信息稳定地拼进模型输入正文。
+ * - 同时提供额外 metadata，便于 history / 调试链路查看。
+ */
+
+import type { JsonObject } from "@downcity/agent/internal/types/common/Json.js";
+import type { InboundReplyContext } from "@/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/chat/runtime/ReplyDispatch.ts

@@ -0,0 +1,78 @@
+/**
+ * Chat reply dispatch helper。
+ *
+ * 关键点（中文）
+ * - 把 chat 回复前/回复后的扩展点统一收敛到这里。
+ * - 仅服务 agent 执行生命周期，不覆盖手动 `chat send`。
+ */
+
+import type { AgentContext } from "@downcity/agent/internal/types/runtime/agent/AgentContext.js";
+import type { ChatReplyDispatchInput, ChatReplyEffectInput } from "@/chat/types/ChatPlugin.js";
+import type { JsonValue } from "@downcity/agent/internal/types/common/Json.js";
+import type { ChatDispatchChannel } from "@/chat/types/ChatDispatcher.js";
+import { CHAT_PLUGIN_POINTS } from "@/chat/runtime/PluginPoints.js";
+import { resolveDispatchTargetByChatKey } from "@/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 } : {}),
+  };
+}

package/src/chat/runtime/SystemPrompt.ts

@@ -0,0 +1,84 @@
+/**
+ * Chat SystemPrompt：chat 运行时 system prompt 辅助。
+ *
+ * 关键点（中文）
+ * - 把当前 chat 路由环境从入站 `<info>` 中剥离，改由 system prompt 注入。
+ * - 仅描述当前会话环境，不承载用户身份字段。
+ * - 统一从 request context + ChatMetaStore 读取当前 chat 元信息。
+ */
+
+import { getSessionRunScope } from "@downcity/agent/internal/executor/SessionRunScope.js";
+import type { AgentContext } from "@downcity/agent/internal/types/runtime/agent/AgentContext.js";
+import type { ChatEnvironmentPromptInput } from "@/chat/types/ChatPromptContext.js";
+import { readChatMetaBySessionId } from "@/chat/runtime/ChatMetaStore.js";
+
+function normalizePromptValue(value: unknown, fallback: string): string {
+  const text = String(value ?? "").trim();
+  return text || fallback;
+}
+
+/**
+ * 解析当前请求的 chat 环境输入。
+ *
+ * 说明（中文）
+ * - 非 chat session 或尚未建立 chat route 时返回 `null`。
+ */
+export async function resolveCurrentChatEnvironmentPromptInput(
+  context: AgentContext,
+): Promise<ChatEnvironmentPromptInput | null> {
+  const sessionId = String(getSessionRunScope()?.sessionId || "").trim();
+  if (!sessionId) return null;
+
+  const meta = await readChatMetaBySessionId({
+    context,
+    sessionId,
+  }).catch(() => null);
+  if (!meta?.channel || !meta.chatId) return null;
+
+  return {
+    sessionId: meta.sessionId,
+    chatKey: meta.sessionId,
+    channel: meta.channel,
+    chatId: meta.chatId,
+    ...(meta.targetType ? { chatType: meta.targetType } : {}),
+    ...(typeof meta.threadId === "number" ? { threadId: meta.threadId } : {}),
+    ...(meta.chatTitle ? { chatTitle: meta.chatTitle } : {}),
+  };
+}
+
+/**
+ * 构造当前 chat 环境说明文本。
+ */
+export function buildChatEnvironmentPrompt(input: ChatEnvironmentPromptInput): string {
+  const lines = [
+    "# Current Chat Environment",
+    "以下字段只描述当前 chat 会话环境与路由，不是用户身份信息：",
+    `- channel: ${normalizePromptValue(input.channel, "unknown")}`,
+    `- session_id: ${normalizePromptValue(input.sessionId, "unknown")}`,
+    `- chat_key: ${normalizePromptValue(input.chatKey, "unknown")}`,
+    `- chat_id: ${normalizePromptValue(input.chatId, "unknown")}`,
+    `- chat_type: ${normalizePromptValue(input.chatType, "unknown")}`,
+    `- thread_id: ${normalizePromptValue(
+      typeof input.threadId === "number" ? String(input.threadId) : "",
+      "none",
+    )}`,
+  ];
+
+  const chatTitle = normalizePromptValue(input.chatTitle, "");
+  if (chatTitle) {
+    lines.push(`- chat_title: ${chatTitle}`);
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * 读取并渲染当前请求的 chat 环境 prompt。
+ */
+export async function buildCurrentChatEnvironmentPrompt(
+  context: AgentContext,
+): Promise<string> {
+  const input = await resolveCurrentChatEnvironmentPromptInput(context);
+  if (!input) return "";
+  return buildChatEnvironmentPrompt(input);
+}

package/src/chat/types/BotInfo.ts

@@ -0,0 +1,101 @@
+/**
+ * Chat Bot 信息探测类型定义。
+ *
+ * 关键点（中文）
+ * - 将“凭据 -> bot 基础信息”的探测输入输出结构标准化。
+ * - Console、Channel Account 存储、后续自动化流程都复用该结构。
+ */
+
+import type { ChatChannelName } from "@/chat/types/ChannelStatus.js";
+
+/**
+ * Bot 信息探测凭据。
+ */
+export interface ChatBotInfoCredentialInput {
+  /**
+   * Telegram 机器人 token（仅 Telegram 渠道使用）。
+   */
+  botToken?: string;
+  /**
+   * 应用 ID（Feishu/QQ 使用）。
+   */
+  appId?: string;
+  /**
+   * 应用密钥（Feishu/QQ 使用）。
+   */
+  appSecret?: string;
+  /**
+   * 平台域名（可选，主要用于 Feishu 私有部署或特殊网关）。
+   */
+  domain?: string;
+  /**
+   * 是否使用沙箱环境（QQ 使用）。
+   */
+  sandbox?: boolean;
+}
+
+/**
+ * Bot 信息探测请求。
+ */
+export interface ChatBotInfoResolveInput {
+  /**
+   * 目标渠道名称。
+   */
+  channel: ChatChannelName;
+  /**
+   * 渠道对应的认证凭据。
+   */
+  credentials: ChatBotInfoCredentialInput;
+}
+
+/**
+ * Bot 信息探测结果。
+ */
+export interface ChatBotInfoResult {
+  /**
+   * 渠道名称。
+   */
+  channel: ChatChannelName;
+  /**
+   * Bot 展示名称（用于 Console 列表展示和默认命名）。
+   */
+  name: string;
+  /**
+   * Bot 身份标识（通常是用户名/open_id/appId 等）。
+   */
+  identity?: string;
+  /**
+   * Bot 所有者信息（可选；平台可获取时返回）。
+   */
+  owner?: string;
+  /**
+   * Bot 创建者信息（可选；平台可获取时返回）。
+   */
+  creator?: string;
+  /**
+   * 平台返回的 bot 用户唯一 ID（若可获取）。
+   */
+  botUserId?: string;
+  /**
+   * 建议用于生成 channel account id 的稳定种子。
+   */
+  idSeed?: string;
+  /**
+   * 探测结果描述。
+   */
+  message: string;
+}
+
+/**
+ * 渠道级 Bot 信息探测器接口。
+ */
+export interface ChatChannelBotInfoProvider {
+  /**
+   * 当前探测器对应渠道。
+   */
+  readonly channel: ChatChannelName;
+  /**
+   * 使用凭据探测并返回标准化 bot 信息。
+   */
+  resolve(credentials: ChatBotInfoCredentialInput): Promise<ChatBotInfoResult>;
+}