@downcity/agent 1.1.23 → 1.1.32

package/src/plugin/builtins/chat/runtime/ChatPluginActionRegistry.ts

@@ -0,0 +1,367 @@
+/**
+ * ChatPluginActions：chat service 的 action 注册表模块。
+ *
+ * 关键点（中文）
+ * - 这里专门负责把 chat 的 CLI/execute 定义装配成 `PluginActions`。
+ * - ChatService 本体只保留实例状态与 lifecycle，不再承载大段 action 声明。
+ * - action 执行仍然复用各 runtime 模块，确保行为与现有实现保持一致。
+ */
+
+import type { Command } from "commander";
+import type { PluginActions } from "@/plugin/types/Plugin.js";
+import type {
+  ChatCloseActionPayload,
+  ChatConfigurationActionPayload,
+  ChatConfigureActionPayload,
+  ChatDeleteActionPayload,
+  ChatHistoryActionPayload,
+  ChatInfoActionPayload,
+  ChatListActionPayload,
+  ChatOpenActionPayload,
+  ChatReactActionPayload,
+  ChatReconnectActionPayload,
+  ChatSendActionPayload,
+  ChatSessionActionPayload,
+  ChatStatusActionPayload,
+  ChatTestActionPayload,
+} from "@/plugin/builtins/chat/types/ChatPluginActionPayload.js";
+import type { ChatChannelState } from "@/plugin/builtins/chat/types/ChatRuntime.js";
+import {
+  mapChatChannelCommandInput,
+  mapChatConfigureCommandInput,
+  mapChatDeleteCommandInput,
+  mapChatHistoryCommandInput,
+  mapChatInfoCommandInput,
+  mapChatListCommandInput,
+  mapChatReactCommandInput,
+  mapChatSendCommandInput,
+} from "./ChatActionInput.js";
+import {
+  executeChatContextAction,
+  executeChatDeleteAction,
+  executeChatHistoryAction,
+  executeChatInfoAction,
+  executeChatListAction,
+  executeChatReactAction,
+  executeChatSendAction,
+} from "./ChatActionExecution.js";
+import {
+  executeChatCloseAction,
+  executeChatConfigurationAction,
+  executeChatConfigureAction,
+  executeChatOpenAction,
+  executeChatReconnectAction,
+  executeChatStatusAction,
+  executeChatTestAction,
+} from "./ChatChannelFacade.js";
+
+const CHAT_SEND_HELP_TEXT = [
+  "",
+  "消息协议：",
+  "  frontmatter metadata 字段语义与 `city chat send` 参数一致。",
+  "  附件使用 `<file type=\"...\">path</file>`，支持 `document/photo/voice/audio/video`。",
+  "  正文与 `<file>` 可以交错出现，运行时会按原顺序发送。",
+  "",
+  "常用示例：",
+  "  city chat send --text 'done'",
+  "  city chat send --chat-key <chatKey> --text 'done'",
+  "  cat <<'EOF' | city chat send --stdin --chat-key <chatKey>",
+  "  第一行",
+  "  第二行",
+  "  EOF",
+  "  city chat send --text-file ./result.md --chat-key <chatKey>",
+  "",
+  "说明：",
+  "  当前会话可省略 `--chat-key`；跨 chat 发送时必须显式传 `--chat-key`。",
+  "  `--delay` 与 `--time` 互斥；ISO 时间必须带时区。",
+].join("\n");
+
+const CHAT_REACT_HELP_TEXT = [
+  "",
+  "常用示例：",
+  "  city chat react --emoji '👍'",
+  "  city chat react --emoji '✅' --message-id <messageId>",
+  "  city chat react --chat-key <chatKey> --message-id <messageId> --emoji '🔥'",
+  "",
+  "说明：",
+  "  当前会话可省略 `--chat-key`；跨 chat 操作时显式传 `--chat-key`。",
+  "  `react` 需要目标消息，优先使用显式 `--message-id`。",
+].join("\n");
+
+function attachCommandHelpText(command: Command, text: string): void {
+  command.on("--help", () => {
+    console.log(text);
+  });
+}
+
+/**
+ * 创建 chat service 的 action 定义表。
+ */
+export function createChatPluginActions(params: {
+  channelState: ChatChannelState;
+}): PluginActions {
+  return {
+    status: {
+      command: {
+        description: "查看 chat 渠道连接状态",
+        configure(command: Command) {
+          command.option("--channel <name>", "指定渠道（telegram|feishu|qq）");
+        },
+        mapInput: mapChatChannelCommandInput,
+      },
+      execute: async (actionParams) => {
+        return executeChatStatusAction({
+          state: params.channelState,
+          context: actionParams.context,
+          payload: actionParams.payload as ChatStatusActionPayload,
+        });
+      },
+    },
+    test: {
+      command: {
+        description: "测试 chat 渠道连通性",
+        configure(command: Command) {
+          command.option("--channel <name>", "指定渠道（telegram|feishu|qq）");
+        },
+        mapInput: mapChatChannelCommandInput,
+      },
+      execute: async (actionParams) => {
+        return executeChatTestAction({
+          state: params.channelState,
+          context: actionParams.context,
+          payload: actionParams.payload as ChatTestActionPayload,
+        });
+      },
+    },
+    reconnect: {
+      command: {
+        description: "重连 chat 渠道（默认全部）",
+        configure(command: Command) {
+          command.option("--channel <name>", "指定渠道（telegram|feishu|qq）");
+        },
+        mapInput: mapChatChannelCommandInput,
+      },
+      execute: async (actionParams) => {
+        return executeChatReconnectAction({
+          state: params.channelState,
+          context: actionParams.context,
+          payload: actionParams.payload as ChatReconnectActionPayload,
+        });
+      },
+    },
+    open: {
+      command: {
+        description: "打开 chat 渠道（enabled=true，已配置则尝试启动）",
+        configure(command: Command) {
+          command.option("--channel <name>", "指定渠道（telegram|feishu|qq）");
+        },
+        mapInput: mapChatChannelCommandInput,
+      },
+      execute: async (actionParams) => {
+        return executeChatOpenAction({
+          state: params.channelState,
+          context: actionParams.context,
+          payload: actionParams.payload as ChatOpenActionPayload,
+        });
+      },
+    },
+    close: {
+      command: {
+        description: "关闭 chat 渠道（enabled=false，并停止运行）",
+        configure(command: Command) {
+          command.option("--channel <name>", "指定渠道（telegram|feishu|qq）");
+        },
+        mapInput: mapChatChannelCommandInput,
+      },
+      execute: async (actionParams) => {
+        return executeChatCloseAction({
+          state: params.channelState,
+          context: actionParams.context,
+          payload: actionParams.payload as ChatCloseActionPayload,
+        });
+      },
+    },
+    configuration: {
+      command: {
+        description: "查看 chat 渠道配置元信息（字段、类型、说明）",
+        configure(command: Command) {
+          command.option("--channel <name>", "指定渠道（telegram|feishu|qq）");
+        },
+        mapInput: mapChatChannelCommandInput,
+      },
+      execute: async (actionParams) => {
+        return executeChatConfigurationAction({
+          context: actionParams.context,
+          payload: actionParams.payload as ChatConfigurationActionPayload,
+        });
+      },
+    },
+    configure: {
+      command: {
+        description: "更新 chat 渠道参数（写入 downcity.json，可选立即重载）",
+        configure(command: Command) {
+          command
+            .requiredOption("--channel <name>", "指定渠道（telegram|feishu|qq）")
+            .requiredOption(
+              "--config-json <json>",
+              "配置 patch JSON（例如 '{\"channelAccountId\":\"qq-main\",\"enabled\":true}'）",
+            )
+            .option("--restart", "配置后立即重载渠道", false);
+        },
+        mapInput: mapChatConfigureCommandInput,
+      },
+      execute: async (actionParams) => {
+        return executeChatConfigureAction({
+          state: params.channelState,
+          context: actionParams.context,
+          payload: actionParams.payload as ChatConfigureActionPayload,
+        });
+      },
+    },
+    list: {
+      command: {
+        description: "列出当前 agent 已记录的 chat 会话（chatTitle/chatKey）",
+        configure(command: Command) {
+          command
+            .option("--channel <name>", "渠道过滤（telegram|feishu|qq）")
+            .option("--limit <n>", "返回最近 N 条（默认 50）")
+            .option("--q <text>", "关键词过滤（title/chatId/sessionId/actor）");
+        },
+        mapInput: mapChatListCommandInput,
+      },
+      execute: async (actionParams) => {
+        return executeChatListAction({
+          context: actionParams.context,
+          payload: actionParams.payload as ChatListActionPayload,
+        });
+      },
+    },
+    info: {
+      command: {
+        description: "查看指定 chat 会话信息（路由/本地路径/上下文快照）",
+        configure(command: Command) {
+          command
+            .option("--chat-key <chatKey>", "目标 chatKey（不传则尝试读取 DC_CTX_CHAT_KEY）")
+            .option("--session-id <sessionId>", "显式指定 sessionId（优先级更高）");
+        },
+        mapInput: mapChatInfoCommandInput,
+      },
+      execute: async (actionParams) => {
+        return executeChatInfoAction({
+          context: actionParams.context,
+          payload: actionParams.payload as ChatInfoActionPayload,
+        });
+      },
+    },
+    send: {
+      command: {
+        description: "发送消息到目标 chatKey",
+        configure(command: Command) {
+          command
+            .option("--text <text>", "消息正文")
+            .option("--stdin", "从标准输入读取消息正文", false)
+            .option("--text-file <file>", "从文件读取消息正文（相对当前目录）")
+            .option("--reply", "显式使用 reply_to_message 回复目标消息", false)
+            .option("--message-id <id>", "显式指定 reply 目标消息 ID")
+            .option(
+              "--chat-key <chatKey>",
+              "目标 chatKey（不传则尝试读取 DC_CTX_CHAT_KEY）",
+            );
+          attachCommandHelpText(command, CHAT_SEND_HELP_TEXT);
+        },
+        mapInput: mapChatSendCommandInput,
+      },
+      execute: async (actionParams) => {
+        return executeChatSendAction({
+          context: actionParams.context,
+          payload: actionParams.payload as ChatSendActionPayload,
+        });
+      },
+    },
+    react: {
+      command: {
+        description: "给目标消息贴表情（当前仅 Telegram 支持）",
+        configure(command: Command) {
+          command
+            .option("--emoji <emoji>", "表情字符（默认 👍）")
+            .option("--big", "使用大表情效果（Telegram is_big）", false)
+            .option("--message-id <id>", "目标消息 ID（默认尝试从 chat meta 回填）")
+            .option(
+              "--chat-key <chatKey>",
+              "目标 chatKey（不传则尝试读取 DC_CTX_CHAT_KEY）",
+            );
+          attachCommandHelpText(command, CHAT_REACT_HELP_TEXT);
+        },
+        mapInput: mapChatReactCommandInput,
+      },
+      execute: async (actionParams) => {
+        return executeChatReactAction({
+          context: actionParams.context,
+          payload: actionParams.payload as ChatReactActionPayload,
+        });
+      },
+    },
+    context: {
+      command: {
+        description: "查看当前会话上下文快照",
+        configure(command: Command) {
+          command.option("--chat-key <chatKey>", "显式覆盖 chatKey");
+        },
+        mapInput(input) {
+          const chatKey =
+            typeof input.opts.chatKey === "string" ? String(input.opts.chatKey).trim() : "";
+          return {
+            ...(chatKey ? { chatKey } : {}),
+          };
+        },
+      },
+      execute: async (actionParams) => {
+        return executeChatContextAction({
+          context: actionParams.context,
+          payload: actionParams.payload as ChatSessionActionPayload,
+        });
+      },
+    },
+    delete: {
+      command: {
+        description: "彻底删除指定 chat 会话（映射+历史+context）",
+        configure(command: Command) {
+          command
+            .option("--chat-key <chatKey>", "显式指定 chatKey")
+            .option("--session-id <sessionId>", "显式指定 sessionId");
+        },
+        mapInput: mapChatDeleteCommandInput,
+      },
+      execute: async (actionParams) => {
+        return executeChatDeleteAction({
+          context: actionParams.context,
+          payload: actionParams.payload as ChatDeleteActionPayload,
+        });
+      },
+    },
+    history: {
+      command: {
+        description: "读取 chat 历史消息（默认最近 30 条）",
+        configure(command: Command) {
+          command
+            .option("--chat-key <chatKey>", "显式覆盖 chatKey")
+            .option("--session-id <sessionId>", "显式覆盖 sessionId")
+            .option("--limit <n>", "返回最近 N 条（默认 30）")
+            .option(
+              "--direction <direction>",
+              "方向过滤（all|inbound|outbound）",
+            )
+            .option("--before-ts <ts>", "仅返回 ts 小于该值的记录（毫秒）")
+            .option("--after-ts <ts>", "仅返回 ts 大于该值的记录（毫秒）");
+        },
+        mapInput: mapChatHistoryCommandInput,
+      },
+      execute: async (actionParams) => {
+        return executeChatHistoryAction({
+          context: actionParams.context,
+          payload: actionParams.payload as ChatHistoryActionPayload,
+        });
+      },
+    },
+  };
+}

package/src/plugin/builtins/chat/runtime/ChatPluginActions.ts

@@ -0,0 +1,5 @@
+/**
+ * ChatPluginActions 导出门面。
+ */
+
+export { createChatPluginActions } from "./ChatPluginActionRegistry.js";

package/src/plugin/builtins/chat/runtime/ChatPluginSystem.ts

@@ -0,0 +1,70 @@
+/**
+ * ChatPluginSystem：chat plugin 的 system prompt 组装模块。
+ *
+ * 关键点（中文）
+ * - chat plugin prompt 与 channel prompt 都属于静态资产。
+ * - 当前请求只注入当前 channel 的 prompt，避免平台规则串味。
+ * - 该模块只负责 prompt 解析与拼装，不承担运行态控制职责。
+ */
+import type { AgentContext } from "@/core/AgentContextTypes.js";
+import {
+  buildCurrentChatEnvironmentPrompt,
+  resolveCurrentChatEnvironmentPromptInput,
+} from "@/plugin/builtins/chat/runtime/SystemPrompt.js";
+import {
+  CHAT_SERVICE_PROMPT,
+  FEISHU_CHAT_CHANNEL_PROMPT,
+  QQ_CHAT_CHANNEL_PROMPT,
+  TELEGRAM_CHAT_CHANNEL_PROMPT,
+} from "@/plugin/builtins/chat/runtime/ChatPromptAssets.js";
+
+const CHAT_CHANNEL_PROMPTS: Record<"telegram" | "feishu" | "qq", string> = {
+  telegram: TELEGRAM_CHAT_CHANNEL_PROMPT,
+  feishu: FEISHU_CHAT_CHANNEL_PROMPT,
+  qq: QQ_CHAT_CHANNEL_PROMPT,
+};
+
+function resolveCurrentChatPromptChannel(
+  channel: string,
+): "telegram" | "feishu" | "qq" | null {
+  if (channel === "telegram" || channel === "feishu" || channel === "qq") {
+    return channel;
+  }
+  return null;
+}
+
+/**
+ * 构建当前请求所属 channel 的提示词片段。
+ *
+ * 关键点（中文）
+ * - 仅注入当前 context 对应的 channel prompt，避免把其他平台规则混入本轮会话。
+ * - 若当前 context 不是 chat channel（如 consoleui）或尚无路由元信息，则不注入 channel prompt。
+ */
+export async function buildCurrentChannelPrompts(
+  context: AgentContext,
+): Promise<string[]> {
+  const chatEnvironment = await resolveCurrentChatEnvironmentPromptInput(context);
+  if (!chatEnvironment) return [];
+  const channel = resolveCurrentChatPromptChannel(
+    String(chatEnvironment.channel || "")
+      .trim()
+      .toLowerCase(),
+  );
+  if (!channel) return [];
+  return [CHAT_CHANNEL_PROMPTS[channel]].filter(Boolean);
+}
+
+/**
+ * 构建 chat plugin 注入到 session 的 system 文本。
+ */
+export async function buildChatPluginSystem(
+  context: AgentContext,
+): Promise<string> {
+  return [
+    CHAT_SERVICE_PROMPT,
+    await buildCurrentChatEnvironmentPrompt(context),
+    ...(await buildCurrentChannelPrompts(context)),
+  ]
+    .filter(Boolean)
+    .join("\n\n");
+}

package/src/plugin/builtins/chat/runtime/ChatPromptAssets.ts

@@ -0,0 +1,32 @@
+/**
+ * ChatPromptAssets：chat service 静态提示词资产。
+ *
+ * 关键点（中文）
+ * - prompt 文本真实来源是 `*.ts.txt` 文本文件。
+ * - 这里统一做 `trim()`，避免多渠道 prompt 行为不一致。
+ */
+
+import chatServicePromptText from "@/plugin/builtins/chat/PROMPT.direct.js";
+import feishuChatPromptText from "@/plugin/builtins/chat/channels/feishu/PROMPT.direct.js";
+import qqChatPromptText from "@/plugin/builtins/chat/channels/qq/PROMPT.direct.js";
+import telegramChatPromptText from "@/plugin/builtins/chat/channels/telegram/PROMPT.direct.js";
+
+/**
+ * chat service 基础 prompt。
+ */
+export const CHAT_SERVICE_PROMPT = chatServicePromptText.trim();
+
+/**
+ * 飞书 channel prompt。
+ */
+export const FEISHU_CHAT_CHANNEL_PROMPT = feishuChatPromptText.trim();
+
+/**
+ * QQ channel prompt。
+ */
+export const QQ_CHAT_CHANNEL_PROMPT = qqChatPromptText.trim();
+
+/**
+ * Telegram channel prompt。
+ */
+export const TELEGRAM_CHAT_CHANNEL_PROMPT = telegramChatPromptText.trim();

package/src/plugin/builtins/chat/runtime/ChatQueue.ts

@@ -0,0 +1,77 @@
+/**
+ * ChatQueue 共享门面。
+ *
+ * 关键点（中文）
+ * - 迁移阶段保留旧函数式 API，内部委托给共享 `ChatQueueStore`。
+ * - 新代码应优先通过 `ChatQueueStore` 实例或 `resolveChatQueueStore(runtime)` 使用队列。
+ */
+
+import type {
+  ChatQueueEnqueueParams,
+  ChatQueueEnqueueResult,
+  ChatQueueItem,
+} from "@/plugin/builtins/chat/types/ChatQueue.js";
+import {
+  ChatQueueStore,
+  getSharedChatQueueStore,
+  resolveChatQueueStore,
+  type ChatQueueEnqueueListener,
+  type ChatQueueStorePort,
+} from "./ChatQueueStore.js";
+
+export { ChatQueueStore, getSharedChatQueueStore, resolveChatQueueStore };
+export type { ChatQueueEnqueueListener, ChatQueueStorePort };
+
+/**
+ * 订阅共享 queue 的入队事件。
+ */
+export function onChatQueueEnqueue(listener: ChatQueueEnqueueListener): () => void {
+  return getSharedChatQueueStore().onEnqueue(listener);
+}
+
+/**
+ * 向共享 queue 入队。
+ */
+export function enqueueChatQueue(
+  params: ChatQueueEnqueueParams,
+): ChatQueueEnqueueResult {
+  return getSharedChatQueueStore().enqueue(params);
+}
+
+/**
+ * 从共享 queue 弹出一条消息。
+ */
+export function shiftChatQueueItem(laneKey: string): ChatQueueItem | null {
+  return getSharedChatQueueStore().shift(laneKey);
+}
+
+/**
+ * 从共享 queue drain 某个 lane。
+ */
+export function drainChatQueueLane(
+  laneKey: string,
+  maxItems?: number,
+): ChatQueueItem[] {
+  return getSharedChatQueueStore().drain(laneKey, maxItems);
+}
+
+/**
+ * 列出共享 queue 当前积压的 lane keys。
+ */
+export function listChatQueueLanes(): string[] {
+  return getSharedChatQueueStore().listLanes();
+}
+
+/**
+ * 查询共享 queue 某个 lane 的长度。
+ */
+export function getChatQueueLaneSize(laneKey: string): number {
+  return getSharedChatQueueStore().getLaneSize(laneKey);
+}
+
+/**
+ * 清空共享 queue 某个 lane。
+ */
+export function clearChatQueueLane(laneKey: string): void {
+  getSharedChatQueueStore().clear(laneKey);
+}