@downcity/plugins 1.0.4

package/src/chat/runtime/ChatActionExecution.ts

@@ -0,0 +1,362 @@
+/**
+ * ChatActionExecution：chat plugin runtime 的业务 action 执行模块。
+ *
+ * 关键点（中文）
+ * - 这里只放与会话/消息相关的执行逻辑。
+ * - 渠道生命周期与配置控制已拆到 `ChatChannelFacade`，避免单文件混合过多职责。
+ * - 输出结构保持原有格式，确保 CLI/API 行为不变。
+ */
+
+import path from "node:path";
+import type { JsonObject } from "@downcity/agent/internal/types/common/Json.js";
+import type { AgentContext } from "@downcity/agent/internal/types/runtime/agent/AgentContext.js";
+import type {
+  ChatDeleteActionPayload,
+  ChatHistoryActionPayload,
+  ChatInfoActionPayload,
+  ChatListActionPayload,
+  ChatReactActionPayload,
+  ChatSendActionPayload,
+  ChatSessionActionPayload,
+} from "@/chat/types/ChatPluginActionPayload.js";
+import type { ChatHistoryEventV1 } from "@/chat/types/ChatHistory.js";
+import type { ChatListItemV1 } from "@/chat/types/ChatCommand.js";
+import {
+  deleteChatByChatKey,
+  resolveChatKey,
+  resolveChatSessionSnapshot,
+  sendChatActionByChatKey,
+  sendChatTextByChatKey,
+} from "@/chat/Action.js";
+import { listChannelSessionRoutes } from "@/chat/runtime/ChannelContextStore.js";
+import { readChatHistory } from "@/chat/runtime/ChatHistoryStore.js";
+import { readChatMetaBySessionId } from "@/chat/runtime/ChatMetaStore.js";
+import { resolveChatChannelNameOrThrow } from "@/chat/runtime/ChatChannelFacade.js";
+
+function toChatHistoryView(events: ChatHistoryEventV1[]): JsonObject[] {
+  return events.map((event) => ({
+    ...event,
+    isoTime: new Date(event.ts).toISOString(),
+  })) as JsonObject[];
+}
+
+/**
+ * 执行 `chat.context` action。
+ */
+export async function executeChatContextAction(params: {
+  context: AgentContext;
+  payload: ChatSessionActionPayload;
+}) {
+  const snapshot = resolveChatSessionSnapshot({
+    context: params.context,
+    ...(params.payload.chatKey ? { chatKey: params.payload.chatKey } : {}),
+    ...(params.payload.sessionId ? { sessionId: params.payload.sessionId } : {}),
+  });
+  return {
+    success: true,
+    data: {
+      context: snapshot,
+    },
+  };
+}
+
+/**
+ * 执行 `chat.list` action。
+ */
+export async function executeChatListAction(params: {
+  context: AgentContext;
+  payload: ChatListActionPayload;
+}) {
+  const rawChannel = String(params.payload.channel || "").trim();
+  const channel = rawChannel ? resolveChatChannelNameOrThrow(rawChannel) : undefined;
+  const rawLimit =
+    typeof params.payload.limit === "number" && Number.isFinite(params.payload.limit)
+      ? Math.trunc(params.payload.limit)
+      : undefined;
+  const limit = rawLimit && rawLimit > 0 ? Math.min(rawLimit, 500) : 50;
+  const q = String(params.payload.q || "").trim();
+  const qLower = q ? q.toLowerCase() : "";
+
+  const meta = await listChannelSessionRoutes({ context: params.context });
+
+  const matches = (value?: string): boolean => {
+    if (!qLower) return true;
+    const text = String(value || "").trim().toLowerCase();
+    return text ? text.includes(qLower) : false;
+  };
+
+  const filtered = meta.routes
+    .filter((route) => (channel ? route.channel === channel : true))
+    .filter((route) => {
+      if (!qLower) return true;
+      return (
+        matches(route.sessionId) ||
+        matches(route.chatId) ||
+        matches(route.chatTitle) ||
+        matches(route.actorName) ||
+        matches(route.actorId) ||
+        matches(route.targetType)
+      );
+    });
+
+  const total = filtered.length;
+  const chats: ChatListItemV1[] = filtered.slice(0, limit).map((route) => ({
+    chatKey: route.sessionId,
+    sessionId: route.sessionId,
+    channel: route.channel,
+    chatId: route.chatId,
+    ...(route.targetType ? { targetType: route.targetType } : {}),
+    ...(typeof route.threadId === "number" ? { threadId: route.threadId } : {}),
+    ...(route.chatTitle ? { chatTitle: route.chatTitle } : {}),
+    ...(route.actorName ? { actorName: route.actorName } : {}),
+    ...(route.actorId ? { actorId: route.actorId } : {}),
+    updatedAt: route.updatedAt,
+    isoUpdatedAt: new Date(route.updatedAt).toISOString(),
+  }));
+
+  return {
+    success: true,
+    data: {
+      metaUpdatedAt: meta.updatedAt,
+      metaIsoUpdatedAt: new Date(meta.updatedAt).toISOString(),
+      total,
+      count: chats.length,
+      chats,
+    },
+  };
+}
+
+/**
+ * 执行 `chat.info` action。
+ */
+export async function executeChatInfoAction(params: {
+  context: AgentContext;
+  payload: ChatInfoActionPayload;
+}) {
+  const explicitSessionId = String(params.payload.sessionId || "").trim();
+  const explicitChatKey = String(params.payload.chatKey || "").trim();
+  const snapshot = resolveChatSessionSnapshot({
+    context: params.context,
+    ...(explicitSessionId ? { sessionId: explicitSessionId } : {}),
+    ...(explicitChatKey ? { chatKey: explicitChatKey } : {}),
+  });
+
+  const sessionId = String(explicitSessionId || snapshot.sessionId || "").trim();
+  const chatKey = String(explicitChatKey || snapshot.chatKey || sessionId || "").trim();
+  if (!sessionId) {
+    return {
+      success: false,
+      error:
+        "Missing sessionId. Provide --session-id/--chat-key or ensure DC_SESSION_ID/DC_CTX_CHAT_KEY is injected.",
+    };
+  }
+
+  const route = await readChatMetaBySessionId({
+    context: params.context,
+    sessionId,
+  });
+
+  const toPosixRelativePath = (absPath: string): string =>
+    path.relative(params.context.rootPath, absPath).split(path.sep).join("/");
+
+  const channelMetaPath = toPosixRelativePath(
+    params.context.paths.getDowncityChannelMetaPath(),
+  );
+  const chatDirPath = toPosixRelativePath(
+    path.join(params.context.rootPath, ".downcity", "chat", sessionId),
+  );
+  const historyPath = toPosixRelativePath(
+    params.context.paths.getDowncityChatHistoryPath(sessionId),
+  );
+
+  return {
+    success: true,
+    data: {
+      sessionId,
+      chatKey,
+      context: snapshot,
+      route,
+      ...(route ? { routeIsoUpdatedAt: new Date(route.updatedAt).toISOString() } : {}),
+      paths: {
+        channelMetaPath,
+        chatDirPath,
+        historyPath,
+      },
+    },
+  };
+}
+
+/**
+ * 执行 `chat.history` action。
+ */
+export async function executeChatHistoryAction(params: {
+  context: AgentContext;
+  payload: ChatHistoryActionPayload;
+}) {
+  const payload = params.payload;
+  const snapshot = resolveChatSessionSnapshot({
+    context: params.context,
+    ...(payload.chatKey ? { chatKey: payload.chatKey } : {}),
+    ...(payload.sessionId ? { sessionId: payload.sessionId } : {}),
+  });
+  const explicitSessionId = String(payload.sessionId || "").trim();
+  const explicitChatKey = String(payload.chatKey || "").trim();
+  const sessionId = String(
+    explicitSessionId || explicitChatKey || snapshot.sessionId || "",
+  ).trim();
+  if (!sessionId) {
+    return {
+      success: false,
+      error:
+        "Missing sessionId. Provide --session-id/--chat-key or ensure DC_SESSION_ID is injected.",
+    };
+  }
+
+  const historyResult = await readChatHistory({
+    context: params.context,
+    sessionId,
+    limit: payload.limit,
+    direction: payload.direction || "all",
+    beforeTs: payload.beforeTs,
+    afterTs: payload.afterTs,
+  });
+  const historyPath = historyResult.historyPath
+    .replace(`${params.context.rootPath}/`, "")
+    .split("\\")
+    .join("/");
+
+  return {
+    success: true,
+    data: {
+      context: snapshot,
+      historyPath,
+      count: historyResult.events.length,
+      events: toChatHistoryView(historyResult.events),
+    },
+  };
+}
+
+/**
+ * 执行 `chat.send` action。
+ */
+export async function executeChatSendAction(params: {
+  context: AgentContext;
+  payload: ChatSendActionPayload;
+}) {
+  const chatKey = resolveChatKey({
+    chatKey: params.payload.chatKey,
+    context: params.context,
+  });
+  if (!chatKey) {
+    return {
+      success: false,
+      error: "Missing chatKey",
+    };
+  }
+
+  const shouldScheduleInBackground =
+    typeof params.payload.delayMs === "number" ||
+    typeof params.payload.sendAtMs === "number";
+  const result = await sendChatTextByChatKey({
+    context: params.context,
+    chatKey,
+    text: String(params.payload.text || ""),
+    delayMs: params.payload.delayMs,
+    sendAtMs: params.payload.sendAtMs,
+    // 关键点（中文）：plugin runtime action 面向 CLI/API，定时或延迟发送应立即返回，
+    // 由 runtime 在后台内存中继续等待并到点投递，避免 HTTP 请求长时间挂起。
+    ...(shouldScheduleInBackground ? { nonBlockingDelay: true } : {}),
+    replyToMessage: params.payload.replyToMessage === true,
+    ...(typeof params.payload.messageId === "string" && params.payload.messageId.trim()
+      ? { messageId: params.payload.messageId.trim() }
+      : {}),
+  });
+  if (!result.success) {
+    return {
+      success: false,
+      error: result.error || "chat send failed",
+    };
+  }
+  return {
+    success: true,
+    data: {
+      chatKey: result.chatKey || chatKey,
+    },
+  };
+}
+
+/**
+ * 执行 `chat.react` action。
+ */
+export async function executeChatReactAction(params: {
+  context: AgentContext;
+  payload: ChatReactActionPayload;
+}) {
+  const chatKey = resolveChatKey({
+    chatKey: params.payload.chatKey,
+    context: params.context,
+  });
+  if (!chatKey) {
+    return {
+      success: false,
+      error: "Missing chatKey",
+    };
+  }
+
+  const messageId = String(params.payload.messageId || "").trim() || undefined;
+  const result = await sendChatActionByChatKey({
+    context: params.context,
+    chatKey,
+    action: "react",
+    messageId,
+    reactionEmoji: params.payload.emoji,
+    reactionIsBig: params.payload.big === true,
+  });
+  if (!result.success) {
+    return {
+      success: false,
+      error: result.error || "chat react failed",
+    };
+  }
+  return {
+    success: true,
+    data: {
+      chatKey: result.chatKey || chatKey,
+      ...(messageId ? { messageId } : {}),
+      ...(typeof params.payload.emoji === "string" && params.payload.emoji.trim()
+        ? { emoji: params.payload.emoji.trim() }
+        : {}),
+      ...(params.payload.big === true ? { big: true } : {}),
+    },
+  };
+}
+
+/**
+ * 执行 `chat.delete` action。
+ */
+export async function executeChatDeleteAction(params: {
+  context: AgentContext;
+  payload: ChatDeleteActionPayload;
+}) {
+  const result = await deleteChatByChatKey({
+    context: params.context,
+    ...(params.payload.chatKey ? { chatKey: params.payload.chatKey } : {}),
+    ...(params.payload.sessionId ? { sessionId: params.payload.sessionId } : {}),
+  });
+  if (!result.success) {
+    return {
+      success: false,
+      error: result.error || "chat delete failed",
+    };
+  }
+  return {
+    success: true,
+    data: {
+      sessionId: result.sessionId || null,
+      deleted: result.deleted === true,
+      removedMeta: result.removedMeta === true,
+      removedChatDir: result.removedChatDir === true,
+      removedSessionDir: result.removedSessionDir === true,
+    },
+  };
+}

package/src/chat/runtime/ChatActionInput.ts

@@ -0,0 +1,167 @@
+/**
+ * ChatActionInput：chat plugin runtime 的 CLI 输入映射模块。
+ *
+ * 关键点（中文）
+ * - 这里统一处理命令行到 action payload 的转换。
+ * - 所有校验错误都尽量在输入层 fail-fast，避免进入执行层后才发现参数非法。
+ * - `chat send` 的 frontmatter / <file> 协议也在这里完成标准化解析。
+ */
+
+import type { JsonObject, JsonValue } from "@downcity/agent/internal/types/common/Json.js";
+import type { PluginActionCommandInput } from "@downcity/agent/internal/plugin/types/Plugin.js";
+import type {
+  ChatConfigureActionPayload,
+  ChatDeleteActionPayload,
+  ChatHistoryActionPayload,
+  ChatInfoActionPayload,
+  ChatListActionPayload,
+  ChatReactActionPayload,
+} from "@/chat/types/ChatPluginActionPayload.js";
+import { resolveChatKey } from "@/chat/Action.js";
+import { resolveChatChannelNameOrThrow } from "@/chat/runtime/ChatChannelFacade.js";
+import {
+  getBooleanOpt,
+  getStringOpt,
+  isJsonObject,
+  parseOptionalTimestampOrThrow,
+  parsePositiveIntOptionOrThrow,
+  readHistoryDirectionOrThrow,
+} from "./ChatActionInputSupport.js";
+export {
+  mapChatSendCommandInput,
+} from "./ChatSendActionInput.js";
+
+export function mapChatChannelCommandInput(
+  input: PluginActionCommandInput,
+): { channel?: ReturnType<typeof resolveChatChannelNameOrThrow> } {
+  const channelRaw = getStringOpt(input.opts, "channel");
+  if (!channelRaw) return {};
+  return {
+    channel: resolveChatChannelNameOrThrow(channelRaw),
+  };
+}
+
+export function mapChatListCommandInput(
+  input: PluginActionCommandInput,
+): ChatListActionPayload {
+  const channelRaw = getStringOpt(input.opts, "channel");
+  const limitRaw = getStringOpt(input.opts, "limit");
+  const q = getStringOpt(input.opts, "q");
+  const channel = channelRaw ? resolveChatChannelNameOrThrow(channelRaw) : undefined;
+  const limit = limitRaw ? parsePositiveIntOptionOrThrow(limitRaw, "limit") : undefined;
+  return {
+    ...(channel ? { channel } : {}),
+    ...(typeof limit === "number" ? { limit } : {}),
+    ...(q ? { q } : {}),
+  };
+}
+
+export function mapChatInfoCommandInput(
+  input: PluginActionCommandInput,
+): ChatInfoActionPayload {
+  const chatKey = getStringOpt(input.opts, "chatKey");
+  const sessionId = getStringOpt(input.opts, "sessionId");
+  return {
+    ...(chatKey ? { chatKey } : {}),
+    ...(sessionId ? { sessionId } : {}),
+  };
+}
+
+export function mapChatConfigureCommandInput(
+  input: PluginActionCommandInput,
+): ChatConfigureActionPayload {
+  const channelRaw = getStringOpt(input.opts, "channel");
+  if (!channelRaw) {
+    throw new Error("Missing --channel. Use telegram|feishu|qq.");
+  }
+  const channel = resolveChatChannelNameOrThrow(channelRaw);
+  const rawConfigJson = getStringOpt(input.opts, "configJson");
+  if (!rawConfigJson) {
+    throw new Error("Missing --config-json.");
+  }
+  let parsed: JsonValue = {};
+  try {
+    parsed = JSON.parse(rawConfigJson) as JsonValue;
+  } catch (error) {
+    throw new Error(`Invalid --config-json: ${String(error)}`);
+  }
+  if (!isJsonObject(parsed)) {
+    throw new Error("--config-json must be a JSON object");
+  }
+  return {
+    channel,
+    config: parsed as Record<string, JsonValue>,
+    restart: getBooleanOpt(input.opts, "restart"),
+  };
+}
+
+export function mapChatHistoryCommandInput(
+  input: PluginActionCommandInput,
+): ChatHistoryActionPayload {
+  const chatKey = getStringOpt(input.opts, "chatKey");
+  const sessionId = getStringOpt(input.opts, "sessionId");
+  const direction = readHistoryDirectionOrThrow(
+    getStringOpt(input.opts, "direction"),
+  );
+  const limitRaw = getStringOpt(input.opts, "limit");
+  const beforeTs = parseOptionalTimestampOrThrow(
+    getStringOpt(input.opts, "beforeTs"),
+    "beforeTs",
+  );
+  const afterTs = parseOptionalTimestampOrThrow(
+    getStringOpt(input.opts, "afterTs"),
+    "afterTs",
+  );
+  const limit = limitRaw ? parsePositiveIntOptionOrThrow(limitRaw, "limit") : undefined;
+
+  if (
+    typeof beforeTs === "number" &&
+    typeof afterTs === "number" &&
+    afterTs >= beforeTs
+  ) {
+    throw new Error("Invalid range: afterTs must be less than beforeTs.");
+  }
+
+  return {
+    ...(chatKey ? { chatKey } : {}),
+    ...(sessionId ? { sessionId } : {}),
+    ...(typeof limit === "number" ? { limit } : {}),
+    ...(direction ? { direction } : {}),
+    ...(typeof beforeTs === "number" ? { beforeTs } : {}),
+    ...(typeof afterTs === "number" ? { afterTs } : {}),
+  };
+}
+
+export function mapChatReactCommandInput(
+  input: PluginActionCommandInput,
+): ChatReactActionPayload {
+  const chatKey = resolveChatKey({
+    chatKey: getStringOpt(input.opts, "chatKey"),
+  });
+  if (!chatKey) {
+    throw new Error(
+      "Missing chatKey. Provide --chat-key or ensure DC_CTX_CHAT_KEY is injected in current shell context.",
+    );
+  }
+
+  const emoji = getStringOpt(input.opts, "emoji");
+  const messageId = getStringOpt(input.opts, "messageId");
+  const big = getBooleanOpt(input.opts, "big");
+  return {
+    chatKey,
+    ...(emoji ? { emoji } : {}),
+    ...(messageId ? { messageId } : {}),
+    ...(big ? { big: true } : {}),
+  };
+}
+
+export function mapChatDeleteCommandInput(
+  input: PluginActionCommandInput,
+): ChatDeleteActionPayload {
+  const chatKey = getStringOpt(input.opts, "chatKey");
+  const sessionId = getStringOpt(input.opts, "sessionId");
+  return {
+    ...(chatKey ? { chatKey } : {}),
+    ...(sessionId ? { sessionId } : {}),
+  };
+}

package/src/chat/runtime/ChatActionInputSupport.ts

@@ -0,0 +1,85 @@
+/**
+ * Chat action 输入映射共享辅助。
+ *
+ * 关键点（中文）
+ * - 只放 CLI/API 输入映射复用的轻量解析函数。
+ * - 具体 action 的 payload 组装留在各 action input 模块中。
+ */
+
+import type { JsonObject, JsonValue } from "@downcity/agent/internal/types/common/Json.js";
+
+/**
+ * 判断 JsonValue 是否为对象。
+ */
+export function isJsonObject(value: JsonValue): value is JsonObject {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+/**
+ * 读取字符串 option。
+ */
+export function getStringOpt(
+  opts: Record<string, JsonValue>,
+  key: string,
+): string {
+  return typeof opts[key] === "string" ? String(opts[key]).trim() : "";
+}
+
+/**
+ * 读取布尔 option。
+ */
+export function getBooleanOpt(
+  opts: Record<string, JsonValue>,
+  key: string,
+): boolean {
+  return opts[key] === true;
+}
+
+/**
+ * 解析正整数 option。
+ */
+export function parsePositiveIntOptionOrThrow(
+  value: string,
+  fieldName: string,
+): number {
+  const text = String(value || "").trim();
+  if (!text) {
+    throw new Error(`${fieldName} is required`);
+  }
+  if (!/^\d+$/.test(text)) {
+    throw new Error(`Invalid ${fieldName}: ${value}`);
+  }
+  const parsed = Number.parseInt(text, 10);
+  if (!Number.isFinite(parsed) || Number.isNaN(parsed) || parsed <= 0) {
+    throw new Error(`Invalid ${fieldName}: ${value}`);
+  }
+  return parsed;
+}
+
+/**
+ * 解析可选时间戳。
+ */
+export function parseOptionalTimestampOrThrow(
+  value: string,
+  fieldName: string,
+): number | undefined {
+  const text = String(value || "").trim();
+  if (!text) return undefined;
+  return parsePositiveIntOptionOrThrow(text, fieldName);
+}
+
+/**
+ * 读取 history direction。
+ */
+export function readHistoryDirectionOrThrow(
+  value: string,
+): "all" | "inbound" | "outbound" | undefined {
+  const text = String(value || "")
+    .trim()
+    .toLowerCase();
+  if (!text) return undefined;
+  if (text === "all" || text === "inbound" || text === "outbound") {
+    return text;
+  }
+  throw new Error(`Invalid direction: ${value}. Use all|inbound|outbound.`);
+}