@downcity/agent 1.1.10 → 1.1.11

package/src/service/builtins/README.md

@@ -2,20 +2,20 @@
 
 ## 模块定位
 
-`services/` 是 Downcity 的主动业务层。  
+`service/builtins/` 是 Downcity 的内建主动业务层。  
 每个 service 对外暴露统一的 `Service` 契约，但在运行时已经逐步迁移为 `BaseService` 子类，由 agent 在启动时创建 `per-agent service instance`。
 
 ## 当前整体模型
 
-1. `main/service/Services.ts`
+1. `service/core/Services.ts`
    - 维护 service 的静态注册清单。
-2. `main/registries/ServiceClassRegistry.ts`
+2. `service/core/ServiceClassRegistry.ts`
    - 负责把静态 service 定义实例化为 `BaseService` 子类。
-3. `agent/AgentRuntime.ts`
+3. `runtime/AgentRuntime.ts`
    - agent 持有当前运行中的 service 实例集合。
-4. `main/service/Manager.ts`
+4. `service/core/Manager.ts`
    - 统一做 service lifecycle、action 调度、CLI/API 桥接。
-5. `src/types/Service.ts`
+5. `service/types/Service.ts`
    - 作为 service 共享契约的单一事实源。
 
 ## 当前内建 service
@@ -31,7 +31,9 @@
    - `runtime/ChatChannelConfig.ts` 负责状态快照与配置落盘。
    - `runtime/ChatChannelActions.ts` 负责渠道类 action 执行。
    - `runtime/ChatChannelFacade.ts` 只保留门面导出。
-   - `runtime/ChatActionInput.ts` 负责 CLI/API 输入映射。
+   - `runtime/ChatActionInput.ts` 负责非 send 类 CLI/API 输入映射与统一导出。
+   - `runtime/ChatSendActionInput.ts` 负责 `chat send` 正文协议、stdin/file 与定时发送输入映射。
+   - `runtime/ChatActionInputSupport.ts` 负责 chat action 输入映射共享解析辅助。
    - `runtime/ChatActionExecution.ts` 负责消息类 action 执行。
    - `runtime/ChatQueueSessionBridge.ts` 负责 queue 与 session 的桥接写入协议。
    - `runtime/ChatQueueWorkerSupport.ts` 负责 worker 辅助能力。
@@ -41,17 +43,24 @@
    - `channels/BaseChatChannelSupport.ts` 负责 session 映射、history 与 chat meta 辅助。
    - `channels/BaseChatChannelQueue.ts` 负责 audit/exec 入队编排。
    - `channels/telegram/Bot.ts` 现在只保留 Telegram 渠道门面与编排。
+   - `channels/telegram/TelegramMessageHandler.ts` 负责 Telegram 普通消息授权、附件与执行入队。
+   - `channels/telegram/TelegramPendingUpdates.ts` 负责 Telegram 积压 updates 的 audit 补录。
    - `channels/telegram/TelegramPlatformClient.ts` 负责 Telegram polling/API/发送主逻辑。
    - `channels/telegram/TelegramInbound.ts` 负责 Telegram 入站归一化辅助。
    - `channels/feishu/Feishu.ts` 现在只保留 Feishu 渠道门面与编排。
+   - `channels/feishu/FeishuMessageHandler.ts` 负责 Feishu 入站去重、授权、附件与执行入队。
    - `channels/feishu/FeishuPlatformClient.ts` 负责 Feishu runtime 宿主与 token/cache 状态。
    - `channels/feishu/FeishuPlatformLookup.ts` 负责 Feishu 用户/群聊/reply 查询与入站附件下载。
    - `channels/feishu/FeishuPlatformMessaging.ts` 负责 Feishu 消息发送与附件上传。
    - `channels/feishu/FeishuInbound.ts` 负责 Feishu 入站归一化辅助。
    - `channels/qq/QQ.ts` 现在只保留 QQ 渠道门面与编排。
+   - `channels/qq/QQMessageHandler.ts` 负责 QQ group/c2c/channel 入站主流程。
    - `channels/qq/QQSupport.ts` 负责 QQ READY 身份解析、命令映射与入站增强组装。
-  - `channels/qq/QQGatewayClient.ts` 负责 QQ Gateway runtime 宿主、WS 编排与重连调度。
-  - `channels/qq/QQGatewaySupport.ts` 负责 QQ Gateway 状态快照、心跳判断与 payload 解析。
+   - `channels/qq/QQGatewayClient.ts` 负责 QQ Gateway runtime 宿主、WS 编排与重连调度。
+   - `channels/qq/QQGatewayConnection.ts` 负责 QQ Gateway WebSocket 创建与事件绑定。
+   - `channels/qq/QQGatewayProtocol.ts` 负责 QQ Gateway op code 协议路由与 Identify。
+   - `channels/qq/QQGatewayHeartbeat.ts` 负责 QQ Gateway heartbeat payload 发送。
+   - `channels/qq/QQGatewaySupport.ts` 负责 QQ Gateway 状态快照、心跳判断与 payload 解析。
    - `channels/qq/QQGatewayAuth.ts` 负责 QQ 鉴权、Gateway URL 与 HTTP 连通性测试。
    - `channels/qq/QQGatewaySend.ts` 负责 QQ 回发请求构造、超时与自动重试。
    - `channels/qq/QQInbound.ts` 负责 QQ 入站归一化辅助。
@@ -65,6 +74,7 @@
    - `runtime/TaskRunnerProgress.ts` 负责 progress 快照与文本辅助。
    - `runtime/TaskRunnerSession.ts` 负责 task 专用 session runtime。
    - `runtime/TaskRunnerRound.ts` 负责单轮执行与模拟用户判定。
+   - `runtime/TaskRunnerScript.ts` 负责 script 类型任务的 one-shot 执行与校验分支。
    - `runtime/TaskRunArtifacts.ts` 负责 run 产物写入与 markdown/json 摘要格式。
    - `runtime/Runner.ts` 负责主编排并协调 run 产物写入。
 3. `memory/`
@@ -75,9 +85,20 @@
    - `ShellService.ts` 持有实例级 shell session 状态。
    - `runtime/ShellActionRuntime.ts` 负责公开 action 编排。
    - `runtime/ShellActionRuntimeSupport.ts` 负责持久化、waiter 与 session 查找等共享运行时细节。
+   - `runtime/ShellRuntimeEnvironment.ts` 负责 shell cwd、env 与 owner context 解析。
+   - `runtime/ShellActionResponse.ts` 负责输出游标裁剪与标准 action response 构造。
+   - `runtime/ShellProcessEvents.ts` 负责 shell 子进程输出、错误与 close 事件绑定。
    - `session/tools/shell/ShellToolDefinition.ts` 作为 session tool facade，只做协议适配。
    - `session/tools/shell/ShellToolSchemas.ts` 负责 shell tool schema。
    - `session/tools/shell/ShellToolBridge.ts` 负责 runtime bridge 与响应整理。
+5. `contact/`
+   - 负责 agent 点对点关系、长期 contact chat、内容分享与 inbox 接收。
+   - `ContactService.ts` 是实例入口，只保留 service 骨架与 contact 业务动作。
+   - `Action.ts` 负责 CLI/API action 注册表与输入映射。
+   - `runtime/ContactPayload.ts` 负责远端 HTTP payload 与 contact token 读取。
+   - `runtime/ContactStore.ts`、`LinkStore.ts`、`InboxStore.ts` 负责 contact/link/inbox 落盘。
+   - `runtime/LinkApproval.ts`、`ApproveCallback.ts` 负责建联与双向回连确认。
+   - `runtime/ShareBundle.ts` 负责分享内容打包与接收。
 
 ## 统一服务模式
 
@@ -86,11 +107,11 @@
 2. `<Domain>Service.ts`
    - 作为真正的 class service 实现。
 3. `Action.ts`
-   - 保留该领域的核心业务 helper，供 service/runtime 复用。
+   - 负责 action 注册表、CLI/API 输入映射与 handler 注入。
 4. `runtime/`
    - 承载具体运行时实现、状态管理与输入映射。
 5. `types/`
-   - 存放领域内部协议；跨层共享契约统一提升到 `src/types/`。
+   - 存放领域内部协议；跨层共享契约统一提升到 `service/types/` 或包级 `types/`。
 
 ## 边界约束
 

package/src/service/builtins/chat/Action.ts

@@ -6,7 +6,7 @@
  * - 通过 SessionRunScope（ALS）读取当前请求上下文
  */
 
-import type { AgentContext } from "@/agent/AgentContextTypes.js";
+import type { AgentContext } from "@/runtime/AgentContextTypes.js";
 import { getSessionRunScope } from "@session/SessionRunScope.js";
 import {
   sendActionByChatKey,

package/src/service/builtins/chat/ChatService.ts

@@ -8,12 +8,12 @@
  * - action 注册表已经拆到独立模块，当前文件只保留实例骨架。
  */
 
-import type { AgentRuntime } from "@/agent/AgentRuntimeTypes.js";
+import type { AgentRuntime } from "@/runtime/AgentRuntimeTypes.js";
 import { BaseService } from "@/service/builtins/BaseService.js";
 import type { ServiceActions } from "@/service/types/Service.js";
-import type { AgentContext } from "@/agent/AgentContextTypes.js";
+import type { AgentContext } from "@/runtime/AgentContextTypes.js";
 import type { ChatChannelState } from "@/service/builtins/chat/types/ChatRuntime.js";
-import type { StoredChannelAccount } from "@/host/types/Store.js";
+import type { StoredChannelAccount } from "@/types/host/Store.js";
 import type { ChatQueueWorkerConfig } from "@/service/builtins/chat/types/ChatQueueWorker.js";
 import type {
   ChatServiceFeishuOptions,

package/src/service/builtins/chat/ChatServiceTypes.ts

@@ -7,9 +7,9 @@
  * - 若未显式注入，则 ChatService 仍可回退到现有 `downcity.json + PlatformStore` 读取路径。
  */
 
-import type { AgentContext } from "@/agent/AgentContextTypes.js";
+import type { AgentContext } from "@/runtime/AgentContextTypes.js";
 import type { ChatQueueWorkerConfig } from "@/service/builtins/chat/types/ChatQueueWorker.js";
-import type { StoredChannelAccount } from "@/host/types/Store.js";
+import type { StoredChannelAccount } from "@/types/host/Store.js";
 import type { ChatChannelName } from "@/service/builtins/chat/types/ChannelStatus.js";
 
 /**

package/src/service/builtins/chat/accounts/ChannelAccountService.ts

@@ -8,8 +8,8 @@
  */
 
 import crypto from "node:crypto";
-import type { AgentPlatformRuntime } from "@/host/types/AgentHost.js";
-import type { StoredChannelAccountChannel } from "@/host/types/Store.js";
+import type { AgentPlatformRuntime } from "@/types/host/AgentHost.js";
+import type { StoredChannelAccountChannel } from "@/types/host/Store.js";
 import { resolveChatChannelBotInfo } from "@/service/builtins/chat/channels/BotInfoProvider.js";
 import type {
   ChatChannelAccountCreateInput,

package/src/service/builtins/chat/channels/BaseChatChannel.ts

@@ -15,7 +15,7 @@ import type {
   ChatDispatcher,
 } from "@/service/builtins/chat/types/ChatDispatcher.js";
 import type { Logger } from "@/utils/logger/Logger.js";
-import type { AgentContext } from "@/agent/AgentContextTypes.js";
+import type { AgentContext } from "@/runtime/AgentContextTypes.js";
 import { resolveChatQueueStore } from "@/service/builtins/chat/runtime/ChatQueue.js";
 import { deleteChatSessionById } from "@/service/builtins/chat/runtime/ChatSessionDelete.js";
 import {

package/src/service/builtins/chat/channels/BaseChatChannelQueue.ts

@@ -15,8 +15,8 @@ import {
   prepareChatEnqueue,
 } from "@/service/builtins/chat/runtime/EnqueueDispatch.js";
 import type { ChatDispatchChannel } from "@/service/builtins/chat/types/ChatDispatcher.js";
-import type { AgentContext } from "@/agent/AgentContextTypes.js";
-import type { JsonObject } from "@/utils/types/Json.js";
+import type { AgentContext } from "@/runtime/AgentContextTypes.js";
+import type { JsonObject } from "@/types/common/Json.js";
 import type { IncomingChatMessage } from "./BaseChatChannel.js";
 import {
   appendInboundChannelHistory,

package/src/service/builtins/chat/channels/BaseChatChannelSupport.ts

@@ -8,8 +8,8 @@
 
 import type { ChatDispatchChannel } from "@/service/builtins/chat/types/ChatDispatcher.js";
 import type { Logger } from "@/utils/logger/Logger.js";
-import type { AgentContext } from "@/agent/AgentContextTypes.js";
-import type { JsonObject, JsonValue } from "@/utils/types/Json.js";
+import type { AgentContext } from "@/runtime/AgentContextTypes.js";
+import type { JsonObject, JsonValue } from "@/types/common/Json.js";
 import {
   resolveSessionIdByChatTarget,
   resolveOrCreateSessionIdByChatTarget,

package/src/service/builtins/chat/channels/feishu/Feishu.ts

@@ -14,33 +14,18 @@ import type {
   ChannelChatKeyParams,
   ChannelSendTextParams,
 } from "@/service/builtins/chat/channels/BaseChatChannel.js";
-import type { AgentContext } from "@/agent/AgentContextTypes.js";
-import type { JsonObject } from "@/utils/types/Json.js";
+import type { AgentContext } from "@/runtime/AgentContextTypes.js";
+import type { JsonObject } from "@/types/common/Json.js";
 import type { ChatChannelTestResult } from "@/service/builtins/chat/types/ChannelStatus.js";
 import type { ParsedFeishuAttachmentCommand } from "@/service/builtins/chat/types/FeishuAttachment.js";
-import type { InboundReplyContext } from "@/service/builtins/chat/types/ReplyContext.js";
 import type {
   FeishuConfig,
   FeishuMessageEvent,
   FeishuMessagePayloadType,
 } from "@/service/builtins/chat/channels/feishu/types/FeishuChannel.js";
 import { parseFeishuAttachments } from "./Shared.js";
-import { parseFeishuInboundMessage } from "./InboundAttachment.js";
-import {
-  buildReplyContextExtra,
-  buildReplyContextInstruction,
-} from "@/service/builtins/chat/runtime/ReplyContextFormatter.js";
-import {
-  augmentChatInboundInput,
-  buildChatInboundText,
-} from "@/service/builtins/chat/runtime/InboundAugment.js";
-import { renderChatMessageFileTag } from "@/service/builtins/chat/runtime/ChatMessageMarkup.js";
-import {
-  extractFeishuSenderIdentity,
-  isFeishuGroupChat,
-  stripFeishuAtMentions,
-} from "./FeishuInbound.js";
 import { FeishuPlatformClient } from "./FeishuPlatformClient.js";
+import { handleFeishuMessage } from "./FeishuMessageHandler.js";
 
 /**
  * 飞书入站确认 reaction 类型。
@@ -198,222 +183,70 @@ export class FeishuBot extends BaseChatChannel {
    * 处理入站消息。
    */
   private async handleMessage(data: FeishuMessageEvent): Promise<void> {
-    try {
-      if (!data?.message) return;
-      const {
-        message: {
-          chat_id,
-          content,
-          message_type,
-          chat_type,
-          message_id,
-          parent_id,
-        },
-      } = data;
-
-      const threadId = this.buildChatKey(chat_id);
-      const senderIdentity = extractFeishuSenderIdentity(data);
-      const actorId = senderIdentity.senderId;
-      const normalizedMessageId = String(message_id || "").trim();
-      if (!normalizedMessageId) return;
-      if (!actorId) {
-        this.logger.warn("飞书消息缺少发送者 userId/open_id，已忽略", {
-          chatId: chat_id,
-          chatType: chat_type,
-          messageId: normalizedMessageId,
-        });
-        return;
-      }
-
-      if (this.processedMessages.has(normalizedMessageId)) {
-        this.logger.debug(`Message already processed, skipping: ${normalizedMessageId}`);
-        return;
-      }
-
-      const persisted = await this.loadDedupeSet(threadId);
-      if (persisted.has(normalizedMessageId)) {
-        this.logger.debug(
-          `Message already processed (persisted), skipping: ${normalizedMessageId}`,
+    await handleFeishuMessage({
+      context: this.context,
+      rootPath: this.rootPath,
+      logger: this.logger,
+      buildChatKey: (chatId) => this.buildChatKey(chatId),
+      processedMessages: this.processedMessages,
+      processingMessages: this.processingMessages,
+      loadDedupeSet: async (threadId) => await this.loadDedupeSet(threadId),
+      persistDedupeSet: async (threadId, set) =>
+        await this.persistDedupeSet(threadId, set),
+      downloadIncomingAttachments: async (params) =>
+        await this.platform.downloadIncomingAttachments(params),
+      resolveReplyContext: async (params) =>
+        await this.platform.resolveReplyContext(params),
+      resolveSenderName: async (params) =>
+        await this.platform.resolveSenderName(params),
+      resolveChatTitle: async (chatId) => await this.platform.resolveChatTitle(chatId),
+      sendInboundAckReaction: async (params) =>
+        await this.platform.sendInboundAckReaction(params),
+      rememberChat: (threadId, value) => {
+        this.knownChats.set(threadId, value);
+      },
+      observeIncomingAuthorization: async (params) => {
+        await this.observeIncomingAuthorization(params);
+      },
+      evaluateIncomingAuthorization: async (params) =>
+        await this.evaluateIncomingAuthorization(params),
+      sendAuthorizationText: async (params) => {
+        await this.sendAuthorizationText(params);
+      },
+      buildUnauthorizedBlockedText: (params) =>
+        this.buildUnauthorizedBlockedText(params),
+      runInChat: async (chatKey, fn) => {
+        await this.runInChat(chatKey, fn);
+      },
+      handleCommand: async (params) => {
+        await this.handleCommand(
+          params.chatId,
+          params.chatType,
+          params.messageId,
+          params.command,
         );
-        return;
-      }
-
-      if (this.processingMessages.has(normalizedMessageId)) {
-        this.logger.debug(
-          `Message is already being processed, skipping duplicate delivery: ${normalizedMessageId}`,
+      },
+      executeAndReply: async (params) => {
+        await this.executeAndReply(
+          params.chatId,
+          params.chatType,
+          params.messageId,
+          params.instructions,
+          params.actorId,
+          params.actorName,
+          params.chatTitle,
+          params.extra,
         );
-        return;
-      }
-      this.processingMessages.add(normalizedMessageId);
-
-      let handled = false;
-      try {
-        let userMessage = "";
-        let incomingAttachments = [] as Awaited<
-          ReturnType<FeishuPlatformClient["downloadIncomingAttachments"]>
-        >;
-        let replyContext: InboundReplyContext | undefined;
-        try {
-          const parsed = parseFeishuInboundMessage({
-            messageType: message_type,
-            content,
-          });
-          if (parsed.unsupportedType) {
-            await this.sendErrorMessage(
-              chat_id,
-              chat_type,
-              message_id,
-              `Unsupported Feishu message type: ${parsed.unsupportedType}`,
-            );
-            handled = true;
-            return;
-          }
-
-          userMessage = parsed.text;
-          incomingAttachments = await this.platform.downloadIncomingAttachments({
-            messageId: message_id,
-            attachments: parsed.attachments,
-          });
-          replyContext = await this.platform.resolveReplyContext({
-            parentMessageId: parent_id,
-          });
-        } catch (error) {
-          await this.sendErrorMessage(
-            chat_id,
-            chat_type,
-            message_id,
-            `Failed to parse message: ${String(error)}`,
-          );
-          handled = true;
-          return;
-        }
-
-        this.logger.info(`Received Feishu message: ${userMessage || "[attachment]"}`);
-        const actorName =
-          (await this.platform.resolveSenderName({
-            ...senderIdentity,
-            chatId: chat_id,
-          })) || undefined;
-        const resolvedChatTitle = await this.platform.resolveChatTitle(chat_id);
-        const chatTitle = resolvedChatTitle || (chat_type === "p2p" ? actorName : undefined);
-
-        await this.observeIncomingAuthorization({
-          chatId: chat_id,
-          chatType: chat_type,
-          chatTitle,
-          userId: actorId,
-          username: actorName,
-        });
-
-        const authResult = await this.evaluateIncomingAuthorization({
-          chatId: chat_id,
-          chatType: chat_type,
-          chatTitle,
-          userId: actorId,
-          username: actorName,
-        });
-        if (authResult.decision !== "allow") {
-          if (chat_type === "p2p") {
-            await this.sendAuthorizationText({
-              chatId: chat_id,
-              chatType: chat_type,
-              text: this.buildUnauthorizedBlockedText({
-                chatId: chat_id,
-                chatType: chat_type,
-                userId: actorId,
-              }),
-            });
-          }
-          handled = true;
-          return;
-        }
-
-        this.knownChats.set(threadId, {
-          chatId: chat_id,
-          chatType: chat_type,
-          ...(chatTitle ? { chatTitle } : {}),
-        });
-
-        await this.platform.sendInboundAckReaction({
-          messageId: message_id,
-        });
-
-        await this.runInChat(threadId, async () => {
-          if (userMessage.startsWith("/") && incomingAttachments.length === 0) {
-            await this.handleCommand(chat_id, chat_type, message_id, userMessage);
-            return;
-          }
-
-          const attachmentLines = incomingAttachments.map((attachment) => {
-            const rel = path.relative(this.rootPath, attachment.path);
-            return renderChatMessageFileTag({
-              type: attachment.type,
-              path: rel,
-              ...(attachment.desc ? { caption: attachment.desc } : {}),
-            });
-          });
-
-          if (isFeishuGroupChat(chat_type)) {
-            userMessage = stripFeishuAtMentions(userMessage);
-          }
-
-          const instructions = buildReplyContextInstruction({
-            text:
-              buildChatInboundText(
-                await augmentChatInboundInput({
-                  context: this.context,
-                  input: {
-                    channel: "feishu",
-                    chatId: chat_id,
-                    chatType: chat_type,
-                    chatKey: threadId,
-                    messageId: message_id,
-                    rootPath: this.rootPath,
-                    attachmentText:
-                      attachmentLines.length > 0 ? attachmentLines.join("\n") : undefined,
-                    bodyText: userMessage ? userMessage.trim() : undefined,
-                    attachments: incomingAttachments.map((attachment) => ({
-                      channel: "feishu" as const,
-                      kind: attachment.type,
-                      path: attachment.path,
-                      desc: attachment.desc,
-                    })),
-                  },
-                }),
-              ) ||
-              (attachmentLines.length > 0
-                ? `${attachmentLines.join("\n")}\n\n请查看以上附件。`
-                : ""),
-            replyContext,
-          });
-
-          if (!instructions) return;
-
-          await this.executeAndReply(
-            chat_id,
-            chat_type,
-            message_id,
-            instructions,
-            actorId,
-            actorName,
-            chatTitle,
-            buildReplyContextExtra(replyContext),
-          );
-        });
-        handled = true;
-      } finally {
-        this.processingMessages.delete(normalizedMessageId);
-        if (handled) {
-          this.processedMessages.add(normalizedMessageId);
-          persisted.add(normalizedMessageId);
-          await this.persistDedupeSet(threadId, persisted);
-        }
-      }
-    } catch (error) {
-      this.logger.error("Failed to process Feishu message", {
-        error: String(error),
-      });
-    }
+      },
+      sendErrorMessage: async (params) => {
+        await this.sendErrorMessage(
+          params.chatId,
+          params.chatType,
+          params.messageId,
+          params.errorText,
+        );
+      },
+    }, data);
   }
 
   /**