@downcity/plugins 1.0.4

package/src/chat/runtime/ChannelContextStore.ts

@@ -0,0 +1,395 @@
+/**
+ * ChannelContextStore：渠道目标与 sessionId 映射存储。
+ *
+ * 关键点（中文）
+ * - 映射文件位于 `.downcity/channel/meta.json`。
+ * - sessionId 由服务端随机生成并持久化，不依赖字符串拼接规则。
+ * - 统一提供“按目标找 sessionId / 按 sessionId 找目标”能力。
+ */
+
+import fs from "fs-extra";
+import { generateId } from "@downcity/agent/internal/utils/Id.js";
+import type { AgentContext } from "@downcity/agent/internal/types/runtime/agent/AgentContext.js";
+import type {
+  ChannelContextMetaFileV1,
+  ChannelContextRouteV1,
+  ChannelContextTarget,
+} from "@/chat/types/ChannelContext.js";
+
+function toOptionalTrimmedString(input: unknown): string | undefined {
+  const value = String(input || "").trim();
+  return value ? value : undefined;
+}
+
+function toOptionalThreadId(input: unknown): number | undefined {
+  if (typeof input !== "number" || !Number.isFinite(input)) return undefined;
+  const out = Math.trunc(input);
+  if (out <= 0) return undefined;
+  return out;
+}
+
+function normalizeTarget(target: ChannelContextTarget): ChannelContextTarget | null {
+  const channel = toOptionalTrimmedString(target.channel);
+  const chatId = toOptionalTrimmedString(target.chatId);
+  if (!channel || !chatId) return null;
+  return {
+    channel: channel as ChannelContextTarget["channel"],
+    chatId,
+    ...(toOptionalTrimmedString(target.targetType)
+      ? { targetType: toOptionalTrimmedString(target.targetType) }
+      : {}),
+    ...(toOptionalThreadId(target.threadId)
+      ? { threadId: toOptionalThreadId(target.threadId) }
+      : {}),
+  };
+}
+
+function normalizeRoute(
+  input: Partial<ChannelContextRouteV1> | null | undefined,
+): ChannelContextRouteV1 | null {
+  if (!input || typeof input !== "object") return null;
+  const sessionId = toOptionalTrimmedString(input.sessionId);
+  const channel = toOptionalTrimmedString(input.channel);
+  const chatId = toOptionalTrimmedString(input.chatId);
+  if (!sessionId || !channel || !chatId) return null;
+  return {
+    v: 1,
+    sessionId,
+    channel: channel as ChannelContextRouteV1["channel"],
+    chatId,
+    ...(toOptionalTrimmedString(input.targetType)
+      ? { targetType: toOptionalTrimmedString(input.targetType) }
+      : {}),
+    ...(toOptionalThreadId(input.threadId)
+      ? { threadId: toOptionalThreadId(input.threadId) }
+      : {}),
+    ...(toOptionalTrimmedString(input.messageId)
+      ? { messageId: toOptionalTrimmedString(input.messageId) }
+      : {}),
+    ...(toOptionalTrimmedString(input.actorId)
+      ? { actorId: toOptionalTrimmedString(input.actorId) }
+      : {}),
+    ...(toOptionalTrimmedString(input.actorName)
+      ? { actorName: toOptionalTrimmedString(input.actorName) }
+      : {}),
+    ...(toOptionalTrimmedString(input.chatTitle)
+      ? { chatTitle: toOptionalTrimmedString(input.chatTitle) }
+      : {}),
+    updatedAt:
+      typeof input.updatedAt === "number" && Number.isFinite(input.updatedAt)
+        ? input.updatedAt
+        : Date.now(),
+  };
+}
+
+function normalizeMetaFile(
+  input: Partial<ChannelContextMetaFileV1> | null | undefined,
+): ChannelContextMetaFileV1 {
+  const routesBySessionId: Record<string, ChannelContextRouteV1> = {};
+  const sessionIdByTargetKey: Record<string, string> = {};
+  const rawRoutes =
+    input && typeof input === "object" && input.routesBySessionId
+      ? input.routesBySessionId
+      : {};
+  if (rawRoutes && typeof rawRoutes === "object") {
+    for (const [sessionId, rawRoute] of Object.entries(rawRoutes)) {
+      const route = normalizeRoute(rawRoute as Partial<ChannelContextRouteV1>);
+      if (!route) continue;
+      routesBySessionId[sessionId] = route;
+    }
+  }
+
+  const rawTargetMap =
+    input && typeof input === "object" && input.sessionIdByTargetKey
+      ? input.sessionIdByTargetKey
+      : {};
+  if (rawTargetMap && typeof rawTargetMap === "object") {
+    for (const [targetKey, sessionIdRaw] of Object.entries(rawTargetMap)) {
+      const sessionId = toOptionalTrimmedString(sessionIdRaw);
+      if (!targetKey || !sessionId) continue;
+      if (!routesBySessionId[sessionId]) continue;
+      sessionIdByTargetKey[targetKey] = sessionId;
+    }
+  }
+
+  return {
+    v: 1,
+    updatedAt:
+      typeof input?.updatedAt === "number" && Number.isFinite(input.updatedAt)
+        ? input.updatedAt
+        : Date.now(),
+    sessionIdByTargetKey,
+    routesBySessionId,
+  };
+}
+
+/**
+ * 构造目标键。
+ *
+ * 关键点（中文）
+ * - 目标键是纯内部索引，不对外暴露。
+ */
+export function buildChannelTargetKey(target: ChannelContextTarget): string {
+  const normalized = normalizeTarget(target);
+  if (!normalized) return "";
+  return [
+    normalized.channel,
+    normalized.chatId,
+    normalized.targetType || "",
+    typeof normalized.threadId === "number" ? String(normalized.threadId) : "",
+  ].join("|");
+}
+
+async function readMetaFile(params: {
+  filePath: string;
+}): Promise<ChannelContextMetaFileV1> {
+  const raw = (await fs.readJson(params.filePath).catch(() => null)) as
+    | Partial<ChannelContextMetaFileV1>
+    | null;
+  return normalizeMetaFile(raw);
+}
+
+async function writeMetaFile(params: {
+  dirPath: string;
+  filePath: string;
+  file: ChannelContextMetaFileV1;
+}): Promise<void> {
+  await fs.ensureDir(params.dirPath);
+  await fs.writeJson(params.filePath, params.file, { spaces: 2 });
+}
+
+/**
+ * 通过 sessionId 读取路由信息。
+ */
+export async function readChannelSessionRouteBySessionId(params: {
+  context: AgentContext;
+  sessionId: string;
+}): Promise<ChannelContextRouteV1 | null> {
+  const rootPath = String(params.context.rootPath || "").trim();
+  const sessionId = toOptionalTrimmedString(params.sessionId);
+  if (!rootPath || !sessionId) return null;
+  const file = await readMetaFile({
+    filePath: params.context.paths.getDowncityChannelMetaPath(),
+  });
+  return normalizeRoute(file.routesBySessionId[sessionId]);
+}
+
+/**
+ * 列出当前 agent 已记录的所有渠道路由条目。
+ *
+ * 关键点（中文）
+ * - 数据源为 `.downcity/channel/meta.json` 的 `routesBySessionId`。
+ * - 默认按 `updatedAt` 倒序返回，便于展示“最近活跃”会话。
+ */
+export async function listChannelSessionRoutes(params: {
+  context: AgentContext;
+}): Promise<{
+  updatedAt: number;
+  routes: ChannelContextRouteV1[];
+}> {
+  const rootPath = String(params.context.rootPath || "").trim();
+  if (!rootPath) {
+    return {
+      updatedAt: Date.now(),
+      routes: [],
+    };
+  }
+  const file = await readMetaFile({
+    filePath: params.context.paths.getDowncityChannelMetaPath(),
+  });
+  const routes = Object.values(file.routesBySessionId)
+    .map((route) => normalizeRoute(route))
+    .filter((route): route is ChannelContextRouteV1 => Boolean(route))
+    .sort((a, b) => b.updatedAt - a.updatedAt);
+  return {
+    updatedAt: file.updatedAt,
+    routes,
+  };
+}
+
+/**
+ * 根据渠道目标查找已有 sessionId（不自动创建）。
+ */
+export async function resolveChannelSessionIdByTarget(params: {
+  context: AgentContext;
+  target: ChannelContextTarget;
+}): Promise<string | null> {
+  const rootPath = String(params.context.rootPath || "").trim();
+  if (!rootPath) return null;
+  const targetKey = buildChannelTargetKey(params.target);
+  if (!targetKey) return null;
+  const file = await readMetaFile({
+    filePath: params.context.paths.getDowncityChannelMetaPath(),
+  });
+  const sessionId = toOptionalTrimmedString(file.sessionIdByTargetKey[targetKey]);
+  if (!sessionId) return null;
+  return file.routesBySessionId[sessionId] ? sessionId : null;
+}
+
+/**
+ * 根据渠道目标解析或创建 sessionId。
+ */
+export async function resolveOrCreateChannelSessionIdByTarget(params: {
+  context: AgentContext;
+  target: ChannelContextTarget;
+}): Promise<string | null> {
+  const rootPath = String(params.context.rootPath || "").trim();
+  if (!rootPath) return null;
+  const normalizedTarget = normalizeTarget(params.target);
+  if (!normalizedTarget) return null;
+  const targetKey = buildChannelTargetKey(normalizedTarget);
+  if (!targetKey) return null;
+
+  const file = await readMetaFile({
+    filePath: params.context.paths.getDowncityChannelMetaPath(),
+  });
+  const existingSessionId = toOptionalTrimmedString(file.sessionIdByTargetKey[targetKey]);
+  if (
+    existingSessionId &&
+    file.routesBySessionId[existingSessionId] &&
+    normalizeRoute(file.routesBySessionId[existingSessionId])
+  ) {
+    return existingSessionId;
+  }
+
+  const nextSessionId = `ctx_${generateId()}`;
+  file.sessionIdByTargetKey[targetKey] = nextSessionId;
+  file.routesBySessionId[nextSessionId] = {
+    v: 1,
+    sessionId: nextSessionId,
+    channel: normalizedTarget.channel,
+    chatId: normalizedTarget.chatId,
+    ...(normalizedTarget.targetType ? { targetType: normalizedTarget.targetType } : {}),
+    ...(typeof normalizedTarget.threadId === "number"
+      ? { threadId: normalizedTarget.threadId }
+      : {}),
+    updatedAt: Date.now(),
+  };
+  file.updatedAt = Date.now();
+  await writeMetaFile({
+    dirPath: params.context.paths.getDowncityChannelDirPath(),
+    filePath: params.context.paths.getDowncityChannelMetaPath(),
+    file,
+  });
+  return nextSessionId;
+}
+
+/**
+ * 更新指定 sessionId 的渠道路由信息。
+ */
+export async function upsertChannelSessionRouteBySessionId(params: {
+  context: AgentContext;
+  sessionId: string;
+  target: ChannelContextTarget;
+  messageId?: string;
+  actorId?: string;
+  actorName?: string;
+  chatTitle?: string;
+}): Promise<void> {
+  const rootPath = String(params.context.rootPath || "").trim();
+  const sessionId = toOptionalTrimmedString(params.sessionId);
+  const normalizedTarget = normalizeTarget(params.target);
+  if (!rootPath || !sessionId || !normalizedTarget) return;
+  const targetKey = buildChannelTargetKey(normalizedTarget);
+  if (!targetKey) return;
+
+  const file = await readMetaFile({
+    filePath: params.context.paths.getDowncityChannelMetaPath(),
+  });
+  const prev = normalizeRoute(file.routesBySessionId[sessionId]);
+  const nextRoute: ChannelContextRouteV1 = {
+    v: 1,
+    sessionId,
+    channel: normalizedTarget.channel,
+    chatId: normalizedTarget.chatId,
+    ...(normalizedTarget.targetType ? { targetType: normalizedTarget.targetType } : {}),
+    ...(typeof normalizedTarget.threadId === "number"
+      ? { threadId: normalizedTarget.threadId }
+      : {}),
+    ...(toOptionalTrimmedString(params.messageId)
+      ? { messageId: toOptionalTrimmedString(params.messageId) }
+      : prev?.messageId
+        ? { messageId: prev.messageId }
+        : {}),
+    ...(toOptionalTrimmedString(params.actorId)
+      ? { actorId: toOptionalTrimmedString(params.actorId) }
+      : prev?.actorId
+        ? { actorId: prev.actorId }
+        : {}),
+    ...(toOptionalTrimmedString(params.actorName)
+      ? { actorName: toOptionalTrimmedString(params.actorName) }
+      : prev?.actorName
+        ? { actorName: prev.actorName }
+        : {}),
+    ...(toOptionalTrimmedString(params.chatTitle)
+      ? { chatTitle: toOptionalTrimmedString(params.chatTitle) }
+      : prev?.chatTitle
+        ? { chatTitle: prev.chatTitle }
+        : {}),
+    updatedAt: Date.now(),
+  };
+
+  file.routesBySessionId[sessionId] = nextRoute;
+  file.sessionIdByTargetKey[targetKey] = sessionId;
+  file.updatedAt = Date.now();
+  await writeMetaFile({
+    dirPath: params.context.paths.getDowncityChannelDirPath(),
+    filePath: params.context.paths.getDowncityChannelMetaPath(),
+    file,
+  });
+}
+
+/**
+ * 删除指定 sessionId 的渠道路由映射。
+ *
+ * 关键点（中文）
+ * - 会同步清理 `routesBySessionId` 与 `sessionIdByTargetKey` 双索引。
+ * - 仅影响 chat 路由，不触碰 context / chat 历史文件。
+ */
+export async function removeChannelSessionRouteBySessionId(params: {
+  context: AgentContext;
+  sessionId: string;
+}): Promise<{
+  removed: boolean;
+  route: ChannelContextRouteV1 | null;
+}> {
+  const rootPath = String(params.context.rootPath || "").trim();
+  const sessionId = toOptionalTrimmedString(params.sessionId);
+  if (!rootPath || !sessionId) {
+    return {
+      removed: false,
+      route: null,
+    };
+  }
+
+  const file = await readMetaFile({
+    filePath: params.context.paths.getDowncityChannelMetaPath(),
+  });
+  const route = normalizeRoute(file.routesBySessionId[sessionId]);
+  if (!route) {
+    return {
+      removed: false,
+      route: null,
+    };
+  }
+
+  delete file.routesBySessionId[sessionId];
+  for (const [targetKey, mappedSessionId] of Object.entries(
+    file.sessionIdByTargetKey,
+  )) {
+    if (mappedSessionId === sessionId) {
+      delete file.sessionIdByTargetKey[targetKey];
+    }
+  }
+
+  file.updatedAt = Date.now();
+  await writeMetaFile({
+    dirPath: params.context.paths.getDowncityChannelDirPath(),
+    filePath: params.context.paths.getDowncityChannelMetaPath(),
+    file,
+  });
+  return {
+    removed: true,
+    route,
+  };
+}