@downcity/plugins 1.0.152 → 1.0.156

package/src/chat/channels/BaseChatChannelQueue.ts

@@ -3,13 +3,12 @@
  *
  * 关键点（中文）
  * - audit / exec 入队都需要走同一套 prepare + emit 流程。
- * - 这些逻辑抽离后，`BaseChatChannel` 只负责渠道层输入整理与授权判断。
+ * - 这些逻辑抽离后，`BaseChatChannel` 只负责渠道层输入整理与 Chat Access 判断。
  */
 
 import { resolveChatQueueStore } from "@/chat/runtime/ChatQueue.js";
 import { buildQueuedUserMessageWithInfo } from "@/chat/runtime/QueuedUserMessage.js";
 import { appendExecIngress } from "@/chat/runtime/ChatIngressStore.js";
-import { resolveIncomingChatUserRole } from "@/chat/runtime/PluginDispatch.js";
 import {
   emitChatEnqueueEffect,
   prepareChatEnqueue,
@@ -190,18 +189,9 @@ export async function enqueueExecChannelMessage(
   params: EnqueueExecChannelMessageParams,
 ): Promise<{ chatKey: string; position: number }> {
   const msg = params.message;
-  const userRole = await resolveIncomingChatUserRole({
-    context: params.context,
-    channel: params.channel,
-    userId: msg.userId,
-  });
   const inboundExtra =
     msg.extra && typeof msg.extra === "object" ? stripUndefinedMeta(msg.extra) : {};
-  const mergedExtra: JsonObject = {
-    ...inboundExtra,
-    roleId: userRole?.roleId || "unknown",
-    permissions: userRole?.permissions || [],
-  };
+  const mergedExtra: JsonObject = { ...inboundExtra };
 
   const chatKey = await resolveOrCreateChannelSessionId({
     context: params.context,
@@ -218,8 +208,6 @@ export async function enqueueExecChannelMessage(
     messageId: msg.messageId,
     userId: msg.userId,
     username: msg.username,
-    roleId: userRole?.roleId,
-    permissions: userRole?.permissions,
     receivedAt: msg.receivedAt,
     userTimezone: msg.userTimezone,
     text: msg.text,

package/src/chat/channels/Configuration.ts

@@ -3,7 +3,7 @@
  *
  * 关键点（中文）
  * - 每个 channel 继承该基类，集中声明自己的配置字段。
- * - 统一提供“可写 ship 字段”提取逻辑，避免在 service 中重复硬编码。
+ * - 统一提供“可写 Agent 配置字段”提取逻辑，避免在 service 中重复硬编码。
  */
 
 import type {
@@ -29,7 +29,7 @@ export abstract class ChatChannelConfiguration {
   /**
    * 返回可通过 `chat.configure` 更新的运行态字段定义。
    */
-  getWritableShipFields(): ChatChannelConfigurationField[] {
-    return this.describe().fields.ship.filter((field) => field.writable);
+  get_writable_agent_config_fields(): ChatChannelConfigurationField[] {
+    return this.describe().fields.agent_config.filter((field) => field.writable);
   }
 }

package/src/chat/channels/feishu/Configuration.ts

@@ -28,14 +28,14 @@ export class FeishuChannelConfiguration extends ChatChannelConfiguration {
         canConfigure: true,
       },
       fields: {
-        ship: [
+        agent_config: [
           {
             key: "enabled",
             label: "Enabled",
             description:
               "Whether feishu channel should be started by runtime.",
             type: "boolean",
-            source: "ship_json",
+            source: "agent_config",
             required: false,
             nullable: false,
             writable: true,
@@ -47,9 +47,9 @@ export class FeishuChannelConfiguration extends ChatChannelConfiguration {
             key: "channelAccountId",
             label: "Chat Account ID",
             description:
-              "Bind this chat platform to a chat account row in ~/.downcity/downcity.db channel_accounts.",
+              "Bind this chat platform to a channel_accounts row in the global downcity.db.",
             type: "string",
-            source: "ship_json",
+            source: "agent_config",
             required: false,
             nullable: true,
             writable: true,

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

@@ -81,6 +81,11 @@ export class FeishuBot extends BaseChatChannel {
     return this.buildChatKey(params.chatId);
   }
 
+  /** SDK 直连时使用飞书 App ID 作为 issuer。 */
+  protected getAccessIssuerFallback(): string {
+    return String(this.appId || "").trim();
+  }
+
   protected async sendTextToPlatform(
     params: ChannelSendTextParams,
   ): Promise<void> {
@@ -209,16 +214,13 @@ export class FeishuBot extends BaseChatChannel {
       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);
+      evaluateIncomingAccess: async (params) =>
+        await this.evaluateIncomingAccess(params),
+      sendAccessText: async (params) => {
+        await this.sendAccessText(params);
       },
-      buildUnauthorizedBlockedText: (params) =>
-        this.buildUnauthorizedBlockedText(params),
+      buildAccessBlockedText: (params) =>
+        this.buildAccessBlockedText(params),
       runInChat: async (chatKey, fn) => {
         await this.runInChat(chatKey, fn);
       },

package/src/chat/channels/feishu/FeishuMessageHandler.ts

@@ -2,7 +2,7 @@
  * Feishu 入站消息处理器。
  *
  * 关键点（中文）
- * - 负责单条飞书消息的去重、解析、授权、附件保存与执行入队。
+ * - 负责单条飞书消息的去重、解析、Chat Access、附件保存与执行入队。
  * - 不持有 `FeishuBot` 实例；所有副作用通过显式依赖注入。
  * - 解析失败/执行失败通过渠道门面提供的发送函数回写错误消息。
  */
@@ -11,8 +11,8 @@ import path from "path";
 import type { Logger } from "@downcity/agent";
 import type { AgentContext } from "@downcity/agent";
 import type {
-  IncomingAuthorizationParams,
-  IncomingAuthorizationResult,
+  IncomingChatAccessParams,
+  IncomingChatAccessResult,
 } from "@/chat/channels/BaseChatChannel.js";
 import type { JsonObject } from "@downcity/agent";
 import type { InboundReplyContext } from "@/chat/types/ReplyContext.js";
@@ -109,34 +109,22 @@ export interface FeishuMessageHandlerOptions {
     threadId: string,
     value: { chatId: string; chatType: string; chatTitle?: string },
   ): void;
+  /** 入站 Chat Access 判定。 */
+  evaluateIncomingAccess(
+    params: IncomingChatAccessParams,
+  ): Promise<IncomingChatAccessResult>;
   /**
-   * 入站主体观测。
+   * 发送 Chat Access 失败提示。
    */
-  observeIncomingAuthorization(
-    params: IncomingAuthorizationParams,
-  ): Promise<void>;
-  /**
-   * 入站授权判定。
-   */
-  evaluateIncomingAuthorization(
-    params: IncomingAuthorizationParams,
-  ): Promise<IncomingAuthorizationResult>;
-  /**
-   * 发送授权失败提示。
-   */
-  sendAuthorizationText(params: {
+  sendAccessText(params: {
     chatId: string;
     text: string;
     chatType?: string;
   }): Promise<void>;
   /**
-   * 构建授权失败提示文案。
+   * 构建 Chat Access 失败提示文案。
    */
-  buildUnauthorizedBlockedText(params?: {
-    userId?: string;
-    chatId?: string;
-    chatType?: string;
-  }): string;
+  buildAccessBlockedText(params: { result: IncomingChatAccessResult }): string;
   /**
    * 按 chatKey 串行执行。
    */
@@ -337,7 +325,7 @@ async function parseIncomingMessage(params: {
 }
 
 /**
- * 授权后处理消息内容。
+ * Chat Access 通过后处理消息内容。
  */
 async function handleAuthorizedMessage(params: {
   options: FeishuMessageHandlerOptions;
@@ -374,31 +362,19 @@ async function handleAuthorizedMessage(params: {
   const resolvedChatTitle = await options.resolveChatTitle(chatId);
   const chatTitle = resolvedChatTitle || (chatType === "p2p" ? actorName : undefined);
 
-  await options.observeIncomingAuthorization({
-    chatId,
-    chatType,
-    chatTitle,
-    userId: actorId,
-    username: actorName,
-  });
-
-  const authResult = await options.evaluateIncomingAuthorization({
+  const access_result = await options.evaluateIncomingAccess({
     chatId,
     chatType,
     chatTitle,
     userId: actorId,
     username: actorName,
   });
-  if (authResult.decision !== "allow") {
+  if (!access_result.allowed) {
     if (chatType === "p2p") {
-      await options.sendAuthorizationText({
+      await options.sendAccessText({
         chatId,
         chatType,
-        text: options.buildUnauthorizedBlockedText({
-          chatId,
-          chatType,
-          userId: actorId,
-        }),
+        text: options.buildAccessBlockedText({ result: access_result }),
       });
     }
     return true;

package/src/chat/channels/qq/Configuration.ts

@@ -28,13 +28,13 @@ export class QqChannelConfiguration extends ChatChannelConfiguration {
         canConfigure: true,
       },
       fields: {
-        ship: [
+        agent_config: [
           {
             key: "enabled",
             label: "Enabled",
             description: "Whether qq channel should be started by runtime.",
             type: "boolean",
-            source: "ship_json",
+            source: "agent_config",
             required: false,
             nullable: false,
             writable: true,
@@ -46,9 +46,9 @@ export class QqChannelConfiguration extends ChatChannelConfiguration {
             key: "channelAccountId",
             label: "Chat Account ID",
             description:
-              "Bind this chat platform to a chat account row in ~/.downcity/downcity.db channel_accounts.",
+              "Bind this chat platform to a channel_accounts row in the global downcity.db.",
             type: "string",
-            source: "ship_json",
+            source: "agent_config",
             required: false,
             nullable: true,
             writable: true,

package/src/chat/channels/qq/QQ.ts

@@ -82,6 +82,11 @@ export class QQBot extends BaseChatChannel {
     return `qq-${chatType}-${params.chatId}`;
   }
 
+  /** SDK 直连时使用 QQ App ID 作为 issuer。 */
+  protected getAccessIssuerFallback(): string {
+    return String(this.appId || "").trim();
+  }
+
   protected async sendTextToPlatform(
     params: ChannelSendTextParams,
   ): Promise<void> {
@@ -266,16 +271,13 @@ export class QQBot extends BaseChatChannel {
       logger: this.logger,
       getBotUserId: () => this.botUserId,
       getChatKey: (params) => this.getChatKey(params),
-      observeIncomingAuthorization: async (params) => {
-        await this.observeIncomingAuthorization(params);
-      },
-      evaluateIncomingAuthorization: async (params) =>
-        await this.evaluateIncomingAuthorization(params),
-      sendAuthorizationText: async (params) => {
-        await this.sendAuthorizationText(params);
+      evaluateIncomingAccess: async (params) =>
+        await this.evaluateIncomingAccess(params),
+      sendAccessText: async (params) => {
+        await this.sendAccessText(params);
       },
-      buildUnauthorizedBlockedText: (params) =>
-        this.buildUnauthorizedBlockedText(params),
+      buildAccessBlockedText: (params) =>
+        this.buildAccessBlockedText(params),
       shouldSkipDuplicatedInboundMessage: async (eventType, messageId) =>
         await this.shouldSkipDuplicatedInboundMessage(eventType, messageId),
       enqueueAuditMessage: async (params) => {

package/src/chat/channels/qq/QQMessageHandler.ts

@@ -2,7 +2,7 @@
  * QQ 入站消息处理器。
  *
  * 关键点（中文）
- * - 负责 group / c2c / channel 三类入站消息的授权、去重、审计与执行入队。
+ * - 负责 group / c2c / channel 三类入站消息的 Chat Access、去重、审计与执行入队。
  * - 不直接持有 `QQBot` 实例；所有副作用通过显式函数注入。
  * - `QQBot` 因此只保留渠道生命周期、dispatch 分流、发送与命令处理。
  */
@@ -11,8 +11,8 @@ import type { Logger } from "@downcity/agent";
 import type { AgentContext } from "@downcity/agent";
 import type {
   ChannelChatKeyParams,
-  IncomingAuthorizationParams,
-  IncomingAuthorizationResult,
+  IncomingChatAccessParams,
+  IncomingChatAccessResult,
 } from "@/chat/channels/BaseChatChannel.js";
 import type { ChannelUserMessageMeta } from "@/chat/channels/BaseChatChannelSupport.js";
 import {
@@ -69,34 +69,22 @@ export interface QQMessageHandlerOptions {
    * 计算 channel chatKey。
    */
   getChatKey(params: ChannelChatKeyParams): string;
+  /** 入站 Chat Access 判定。 */
+  evaluateIncomingAccess(
+    params: IncomingChatAccessParams,
+  ): Promise<IncomingChatAccessResult>;
   /**
-   * 入站主体观测。
+   * 发送 Chat Access 失败提示。
    */
-  observeIncomingAuthorization(
-    params: IncomingAuthorizationParams,
-  ): Promise<void>;
-  /**
-   * 入站授权判定。
-   */
-  evaluateIncomingAuthorization(
-    params: IncomingAuthorizationParams,
-  ): Promise<IncomingAuthorizationResult>;
-  /**
-   * 发送授权失败提示。
-   */
-  sendAuthorizationText(params: {
+  sendAccessText(params: {
     chatId: string;
     text: string;
     chatType?: string;
   }): Promise<void>;
   /**
-   * 构建授权失败提示文案。
+   * 构建 Chat Access 失败提示文案。
    */
-  buildUnauthorizedBlockedText(params?: {
-    userId?: string;
-    chatId?: string;
-    chatType?: string;
-  }): string;
+  buildAccessBlockedText(params: { result: IncomingChatAccessResult }): string;
   /**
    * 入站去重判断。
    */
@@ -234,22 +222,14 @@ export async function handleQqChannelMessage(
     actorName: actor.username,
   });
 
-  await options.observeIncomingAuthorization({
-    chatId: channelId,
-    chatType,
-    chatTitle,
-    userId: actor.userId,
-    username: actor.username,
-  });
-
-  const authResult = await options.evaluateIncomingAuthorization({
+  const access_result = await options.evaluateIncomingAccess({
     chatId: channelId,
     chatType,
     chatTitle,
     userId: actor.userId,
     username: actor.username,
   });
-  if (authResult.decision !== "allow") return;
+  if (!access_result.allowed) return;
 
   const botUserId = options.getBotUserId();
   if (actor.userId && botUserId && actor.userId === botUserId) {
@@ -347,31 +327,19 @@ async function handleQqInboundMessage(
     ? stripQqBotMention(rawContent, botUserId)
     : extractQqTextContent(rawContent);
 
-  await options.observeIncomingAuthorization({
-    chatId,
-    chatType,
-    chatTitle,
-    userId: actor.userId,
-    username: actor.username,
-  });
-
-  const authResult = await options.evaluateIncomingAuthorization({
+  const access_result = await options.evaluateIncomingAccess({
     chatId,
     chatType,
     chatTitle,
     userId: actor.userId,
     username: actor.username,
   });
-  if (authResult.decision !== "allow") {
+  if (!access_result.allowed) {
     if (!isGroup) {
-      await options.sendAuthorizationText({
+      await options.sendAccessText({
         chatId,
         chatType,
-        text: options.buildUnauthorizedBlockedText({
-          chatId,
-          chatType,
-          userId: actor.userId,
-        }),
+        text: options.buildAccessBlockedText({ result: access_result }),
       });
     }
     return;

package/src/chat/channels/telegram/Bot.ts

@@ -72,6 +72,11 @@ export class TelegramBot extends BaseChatChannel {
     return buildTelegramChatKey(params.chatId, params.messageThreadId);
   }
 
+  /** SDK 直连时使用 Telegram Bot ID 作为 issuer。 */
+  protected getAccessIssuerFallback(): string {
+    return String(this.platform.getBotId() || "").trim();
+  }
+
   protected async sendTextToPlatform(
     params: ChannelSendTextParams,
   ): Promise<void> {
@@ -207,16 +212,13 @@ export class TelegramBot extends BaseChatChannel {
         logger: this.logger,
         inboundAckEmoji: TelegramBot.INBOUND_ACK_EMOJI,
         platform: this.platform,
-        observeIncomingAuthorization: async (params) => {
-          await this.observeIncomingAuthorization(params);
-        },
-        evaluateIncomingAuthorization: async (params) =>
-          await this.evaluateIncomingAuthorization(params),
-        sendAuthorizationText: async (params) => {
-          await this.sendAuthorizationText(params);
+        evaluateIncomingAccess: async (params) =>
+          await this.evaluateIncomingAccess(params),
+        sendAccessText: async (params) => {
+          await this.sendAccessText(params);
         },
-        buildUnauthorizedBlockedText: (params) =>
-          this.buildUnauthorizedBlockedText(params),
+        buildAccessBlockedText: (params) =>
+          this.buildAccessBlockedText(params),
         enqueueAuditMessage: async (params) => {
           await this.enqueueAuditMessage(params);
         },

package/src/chat/channels/telegram/Configuration.ts

@@ -28,14 +28,14 @@ export class TelegramChannelConfiguration extends ChatChannelConfiguration {
         canConfigure: true,
       },
       fields: {
-        ship: [
+        agent_config: [
           {
             key: "enabled",
             label: "Enabled",
             description:
               "Whether telegram channel should be started by runtime.",
             type: "boolean",
-            source: "ship_json",
+            source: "agent_config",
             required: false,
             nullable: false,
             writable: true,
@@ -47,9 +47,9 @@ export class TelegramChannelConfiguration extends ChatChannelConfiguration {
             key: "channelAccountId",
             label: "Chat Account ID",
             description:
-              "Bind this chat platform to a chat account row in ~/.downcity/downcity.db channel_accounts.",
+              "Bind this chat platform to a channel_accounts row in the global downcity.db.",
             type: "string",
-            source: "ship_json",
+            source: "agent_config",
             required: false,
             nullable: true,
             writable: true,

package/src/chat/channels/telegram/TelegramMessageHandler.ts

@@ -2,7 +2,7 @@
  * Telegram 普通消息处理器。
  *
  * 关键点（中文）
- * - 负责单条 message 的授权、审计、附件保存、入队指令构造。
+ * - 负责单条 message 的 Chat Access、审计、附件保存、入队指令构造。
  * - 不持有 channel 实例；所有副作用通过显式依赖注入。
  * - `TelegramBot` 只保留平台生命周期与命令/callback 分发入口。
  */
@@ -12,8 +12,8 @@ import type { Logger } from "@downcity/agent";
 import type { AgentContext } from "@downcity/agent";
 import type { JsonObject } from "@downcity/agent";
 import type {
-  IncomingAuthorizationParams,
-  IncomingAuthorizationResult,
+  IncomingChatAccessParams,
+  IncomingChatAccessResult,
 } from "@/chat/channels/BaseChatChannel.js";
 import type { ChannelUserMessageMeta } from "@/chat/channels/BaseChatChannelSupport.js";
 import {
@@ -127,35 +127,23 @@ export interface TelegramMessageHandlerOptions {
    * Telegram 平台能力。
    */
   platform: TelegramMessagePlatform;
+  /** 入站 Chat Access 判定。 */
+  evaluateIncomingAccess(
+    params: IncomingChatAccessParams,
+  ): Promise<IncomingChatAccessResult>;
   /**
-   * 入站主体观测。
+   * 发送 Chat Access 失败提示。
    */
-  observeIncomingAuthorization(
-    params: IncomingAuthorizationParams,
-  ): Promise<void>;
-  /**
-   * 入站授权判定。
-   */
-  evaluateIncomingAuthorization(
-    params: IncomingAuthorizationParams,
-  ): Promise<IncomingAuthorizationResult>;
-  /**
-   * 发送授权失败提示。
-   */
-  sendAuthorizationText(params: {
+  sendAccessText(params: {
     chatId: string;
     text: string;
     chatType?: string;
     messageThreadId?: number;
   }): Promise<void>;
   /**
-   * 构建授权失败提示文案。
+   * 构建 Chat Access 失败提示文案。
    */
-  buildUnauthorizedBlockedText(params?: {
-    userId?: string;
-    chatId?: string;
-    chatType?: string;
-  }): string;
+  buildAccessBlockedText(params: { result: IncomingChatAccessResult }): string;
   /**
    * Audit 队列写入。
    */
@@ -223,32 +211,20 @@ export async function handleTelegramMessage(
     return;
   }
 
-  await options.observeIncomingAuthorization({
-    chatId,
-    chatType: message.chat.type,
-    chatTitle,
-    userId: actorId,
-    username: actorName,
-  });
-
-  const authResult = await options.evaluateIncomingAuthorization({
+  const access_result = await options.evaluateIncomingAccess({
     chatId,
     chatType: message.chat.type,
     chatTitle,
     userId: actorId,
     username: actorName,
   });
-  if (authResult.decision !== "allow") {
+  if (!access_result.allowed) {
     if (!isGroup) {
-      await options.sendAuthorizationText({
+      await options.sendAccessText({
         chatId,
         chatType: message.chat.type,
         messageThreadId,
-        text: options.buildUnauthorizedBlockedText({
-          chatId,
-          chatType: message.chat.type,
-          userId: actorId,
-        }),
+        text: options.buildAccessBlockedText({ result: access_result }),
       });
     }
     return;