@downcity/plugins 1.0.57 → 1.0.60

package/src/chat/ChatPlugin.ts

@@ -9,29 +9,47 @@
  */
 
 import { BasePlugin } from "@downcity/agent/internal/plugin/core/BasePlugin.js";
-import type { PluginActions } from "@downcity/agent/internal/plugin/types/Plugin.js";
+import type {
+  PluginActions,
+  PluginHooks,
+  PluginResolves,
+} from "@downcity/agent/internal/plugin/types/Plugin.js";
 import type { AgentContext } from "@downcity/agent/internal/types/runtime/agent/AgentContext.js";
 import type { ChatChannelState } from "@/chat/types/ChatRuntime.js";
-import type { StoredChannelAccount } from "@downcity/agent/internal/types/platform/Store.js";
 import type { ChatQueueWorkerConfig } from "@/chat/types/ChatQueueWorker.js";
 import type {
-  ChatPluginFeishuOptions,
+  ChatChannel,
   ChatPluginOptions,
-  ChatPluginQqOptions,
-  ChatPluginTelegramOptions,
-} from "@/chat/ChatPluginTypes.js";
+} from "@/chat/types/ChatPluginOptions.js";
 import type { ChatChannelName } from "@/chat/types/ChannelStatus.js";
+import {
+  FeishuChannel,
+  QqChannel,
+  TelegramChannel,
+} from "@/chat/channels/RuntimeChannel.js";
 import {
   createChatChannelState,
   startChatChannels,
   stopChatChannels,
 } from "./runtime/ChatChannelFacade.js";
-import { getStoredChannelAccountSync } from "./accounts/Store.js";
 import { createChatPluginActions } from "./runtime/ChatPluginActions.js";
+import {
+  createChatAuthorizationActions,
+  createChatAuthorizationHooks,
+  createChatAuthorizationResolves,
+} from "./runtime/ChatAuthorizationRuntime.js";
 import { ChatQueueWorker } from "./runtime/ChatQueueWorker.js";
 import { buildChatPluginSystem } from "./runtime/ChatPluginSystem.js";
 import { ChatQueueStore } from "./runtime/ChatQueueStore.js";
 
+function createDefaultChannels(): ChatChannel[] {
+  return [
+    new TelegramChannel({ enabled: false }),
+    new FeishuChannel({ enabled: false }),
+    new QqChannel({ enabled: false }),
+  ];
+}
+
 /**
  * Chat plugin 类实现。
  */
@@ -69,6 +87,11 @@ export class ChatPlugin extends BasePlugin {
    */
   public readonly options: ChatPluginOptions;
 
+  /**
+   * 当前实例持有的 chat channels。
+   */
+  public readonly channels: ChatChannel[];
+
   /**
    * 当前 plugin 的 system 文本构建器。
    */
@@ -81,6 +104,16 @@ export class ChatPlugin extends BasePlugin {
    */
   readonly actions: PluginActions;
 
+  /**
+   * 当前 plugin 的 hook 定义表。
+   */
+  readonly hooks: PluginHooks;
+
+  /**
+   * 当前 plugin 的 resolve 定义表。
+   */
+  readonly resolves: PluginResolves;
+
   /**
    * 启动当前实例的 queue worker。
    */
@@ -109,9 +142,17 @@ export class ChatPlugin extends BasePlugin {
   constructor(options?: ChatPluginOptions) {
     super();
     this.options = options || {};
-    this.actions = createChatPluginActions({
-      channelState: this.channelState,
-    });
+    this.channels = Array.isArray(this.options.channels)
+      ? [...this.options.channels]
+      : createDefaultChannels();
+    this.actions = {
+      ...createChatPluginActions({
+        channelState: this.channelState,
+      }),
+      ...createChatAuthorizationActions(),
+    };
+    this.hooks = createChatAuthorizationHooks();
+    this.resolves = createChatAuthorizationResolves();
     this.lifecycle = {
       start: async (context) => {
         this.startQueueWorker(context);
@@ -130,18 +171,15 @@ export class ChatPlugin extends BasePlugin {
   getQueueWorkerConfig(
     context: AgentContext,
   ): Partial<ChatQueueWorkerConfig> | undefined {
-    return this.options.queue || context.config.plugins?.chat?.queue;
+    void context;
+    return this.options.queue;
   }
 
   /**
    * 判断指定渠道是否启用。
    */
   isChannelEnabled(context: AgentContext, channel: ChatChannelName): boolean {
-    const explicit = this.getExplicitChannelOptions(channel);
-    if (explicit) {
-      return explicit.enabled !== false;
-    }
-    return context.config.plugins?.chat?.channels?.[channel]?.enabled === true;
+    return this.getChannel(channel)?.isEnabled(context) === true;
   }
 
   /**
@@ -151,13 +189,40 @@ export class ChatPlugin extends BasePlugin {
     context: AgentContext,
     channel: ChatChannelName,
   ): string {
-    const explicit = this.getExplicitChannelOptions(channel);
-    const explicitAccountId = String(explicit?.channelAccountId || "").trim();
-    if (explicitAccountId) return explicitAccountId;
-    const config = context.config.plugins?.chat?.channels?.[channel] as
-      | { channelAccountId?: unknown }
-      | undefined;
-    return String(config?.channelAccountId || "").trim();
+    return String(this.getChannel(channel)?.getChannelAccountId(context) || "").trim();
+  }
+
+  /**
+   * 更新当前实例的渠道运行态配置。
+   *
+   * 关键点（中文）
+   * - chat.open/close/configure 只修改当前 plugin 实例，不写 downcity.json。
+   * - 当前运行态只允许更新 `enabled` 与 `channelAccountId`，密钥仍来自 constructor 或账号池。
+   */
+  applyChannelRuntimePatch(params: {
+    /**
+     * 目标渠道。
+     */
+    channel: ChatChannelName;
+    /**
+     * 是否启用该渠道。
+     */
+    enabled?: boolean;
+    /**
+     * 绑定的账号池记录 ID；传入 null 表示清空绑定。
+     */
+    channelAccountId?: string | null;
+  }): void {
+    const channel = this.getChannel(params.channel);
+    if (!channel) {
+      throw new Error(`Chat channel is not registered: ${params.channel}`);
+    }
+    channel.applyRuntimePatch({
+      ...(typeof params.enabled === "boolean" ? { enabled: params.enabled } : {}),
+      ...(Object.prototype.hasOwnProperty.call(params, "channelAccountId")
+        ? { channelAccountId: params.channelAccountId ?? null }
+        : {}),
+    });
   }
 
   /**
@@ -166,73 +231,11 @@ export class ChatPlugin extends BasePlugin {
   resolveChannelAccount(
     context: AgentContext,
     channel: ChatChannelName,
-  ): StoredChannelAccount | null {
-    const explicit = this.buildExplicitChannelAccount(channel);
-    if (explicit) return explicit;
-    const channelAccountId = this.getChannelAccountId(context, channel);
-    if (!channelAccountId) return null;
-    return getStoredChannelAccountSync(channelAccountId);
+  ) {
+    return this.getChannel(channel)?.getAccount(context) || null;
   }
 
-  private getExplicitChannelOptions(
-    channel: ChatChannelName,
-  ): ChatPluginTelegramOptions | ChatPluginFeishuOptions | ChatPluginQqOptions | undefined {
-    if (channel === "telegram") return this.options.telegram;
-    if (channel === "feishu") return this.options.feishu;
-    return this.options.qq;
-  }
-
-  private buildExplicitChannelAccount(
-    channel: ChatChannelName,
-  ): StoredChannelAccount | null {
-    const now = new Date().toISOString();
-
-    if (channel === "telegram") {
-      const config = this.options.telegram;
-      const botToken = String(config?.botToken || "").trim();
-      if (!botToken) return null;
-      return {
-        id: String(config?.channelAccountId || `chat-sdk-${channel}`).trim(),
-        channel,
-        name: String(config?.name || "telegram").trim() || "telegram",
-        botToken,
-        createdAt: now,
-        updatedAt: now,
-      };
-    }
-
-    if (channel === "feishu") {
-      const config = this.options.feishu;
-      const appId = String(config?.appId || "").trim();
-      const appSecret = String(config?.appSecret || "").trim();
-      if (!appId || !appSecret) return null;
-      return {
-        id: String(config?.channelAccountId || `chat-sdk-${channel}`).trim(),
-        channel,
-        name: String(config?.name || "feishu").trim() || "feishu",
-        appId,
-        appSecret,
-        ...(String(config?.domain || "").trim()
-          ? { domain: String(config?.domain || "").trim() }
-          : {}),
-        createdAt: now,
-        updatedAt: now,
-      };
-    }
-
-    const config = this.options.qq;
-    const appId = String(config?.appId || "").trim();
-    const appSecret = String(config?.appSecret || "").trim();
-    if (!appId || !appSecret) return null;
-    return {
-      id: String(config?.channelAccountId || `chat-sdk-${channel}`).trim(),
-      channel,
-      name: String(config?.name || "qq").trim() || "qq",
-      appId,
-      appSecret,
-      ...(config?.sandbox === true ? { sandbox: true } : {}),
-      createdAt: now,
-      updatedAt: now,
-    };
+  private getChannel(channel: ChatChannelName): ChatChannel | null {
+    return this.channels.find((item) => item.name === channel) || null;
   }
 }

package/src/chat/Index.ts

@@ -2,7 +2,24 @@
  * Chat Plugin 导出入口。
  *
  * 关键点（中文）
- * - Index 只负责导出类实现。
+ * - Index 只负责导出类实现与 channel SDK 对象。
  * - 真正的类实现位于 `ChatPlugin.ts`。
  */
 export { ChatPlugin } from "./ChatPlugin.js";
+export {
+  FeishuChannel,
+  QqChannel,
+  TelegramChannel,
+} from "./channels/RuntimeChannel.js";
+export type {
+  BaseChatChannelOptions,
+  ChatChannelEnv,
+  FeishuChannelOptions,
+  QqChannelOptions,
+  TelegramChannelOptions,
+} from "./channels/RuntimeChannel.js";
+export type {
+  ChatChannel,
+  ChatChannelRuntimePatch,
+  ChatPluginOptions,
+} from "./types/ChatPluginOptions.js";

package/src/chat/channels/Configuration.ts

@@ -27,7 +27,7 @@ export abstract class ChatChannelConfiguration {
   abstract describe(): ChatChannelConfigurationDescriptor;
 
   /**
-   * 返回可通过 `chat.configure` 写入的 downcity.json 字段定义。
+   * 返回可通过 `chat.configure` 更新的运行态字段定义。
    */
   getWritableShipFields(): ChatChannelConfigurationField[] {
     return this.describe().fields.ship.filter((field) => field.writable);

package/src/chat/channels/RuntimeChannel.ts

@@ -0,0 +1,264 @@
+/**
+ * Chat channel SDK 基类与内置 channel 实现。
+ *
+ * 关键点（中文）
+ * - channel 对象是 ChatPlugin 的运行态配置单元。
+ * - env 由 channel 自己读取，ChatPlugin 不理解平台字段。
+ * - channelAccountId 仅作为账号池绑定能力保留，不再是 ChatPlugin 顶层配置。
+ */
+
+import type { AgentContext } from "@downcity/agent/internal/types/runtime/agent/AgentContext.js";
+import type { StoredChannelAccount } from "@downcity/agent/internal/types/platform/Store.js";
+import type { ChatChannelName } from "@/chat/types/ChannelStatus.js";
+import type {
+  ChatChannel,
+  ChatChannelRuntimePatch,
+} from "@/chat/types/ChatPluginOptions.js";
+import { getStoredChannelAccountSync } from "@/chat/accounts/Store.js";
+
+/**
+ * env 字典。
+ */
+export type ChatChannelEnv = Record<string, string | undefined>;
+
+/**
+ * Chat channel 基础配置。
+ */
+export interface BaseChatChannelOptions {
+  /**
+   * 是否启用该 channel。
+   *
+   * 说明（中文）
+   * - 默认值为 `true`，因为传入 channel 对象通常表示希望启用它。
+   * - 可通过 chat.open / chat.close 在运行态修改。
+   */
+  enabled?: boolean;
+  /**
+   * channel 专属 env。
+   *
+   * 说明（中文）
+   * - 这里面放面向人类可读的环境变量名，例如 `TELEGRAM_BOT_TOKEN`。
+   * - channel 会自行读取所需字段。
+   */
+  env?: ChatChannelEnv;
+  /**
+   * 可选账号池绑定 ID。
+   *
+   * 说明（中文）
+   * - 仅在需要复用全局账号池时使用。
+   * - SDK 主路径推荐直接通过 `env` 传入凭据。
+   */
+  channelAccountId?: string;
+  /**
+   * 运行态展示名称。
+   */
+  name?: string;
+}
+
+abstract class BaseRuntimeChatChannel implements ChatChannel {
+  /**
+   * channel 名称。
+   */
+  abstract readonly name: ChatChannelName;
+
+  protected enabled: boolean;
+  protected env: ChatChannelEnv;
+  protected channelAccountId: string;
+  protected displayName: string;
+
+  protected constructor(options: BaseChatChannelOptions = {}) {
+    this.enabled = options.enabled !== false;
+    this.env = options.env || {};
+    this.channelAccountId = String(options.channelAccountId || "").trim();
+    this.displayName = String(options.name || "").trim();
+  }
+
+  isEnabled(_context: AgentContext): boolean {
+    return this.enabled;
+  }
+
+  getChannelAccountId(_context: AgentContext): string {
+    return this.channelAccountId;
+  }
+
+  applyRuntimePatch(patch: ChatChannelRuntimePatch): void {
+    if (typeof patch.enabled === "boolean") {
+      this.enabled = patch.enabled;
+    }
+    if (Object.prototype.hasOwnProperty.call(patch, "channelAccountId")) {
+      this.channelAccountId = String(patch.channelAccountId || "").trim();
+    }
+  }
+
+  protected getStoredAccount(): StoredChannelAccount | null {
+    if (!this.channelAccountId) return null;
+    const account = getStoredChannelAccountSync(this.channelAccountId);
+    if (!account || account.channel !== this.name) return null;
+    return account;
+  }
+
+  protected nowIso(): string {
+    return new Date().toISOString();
+  }
+
+  abstract getAccount(context: AgentContext): StoredChannelAccount | null;
+}
+
+/**
+ * Telegram channel 配置。
+ */
+export interface TelegramChannelOptions extends BaseChatChannelOptions {
+  /**
+   * Telegram bot token。
+   *
+   * 说明（中文）
+   * - 优先级高于 `env.TELEGRAM_BOT_TOKEN`。
+   */
+  botToken?: string;
+}
+
+/**
+ * Telegram channel。
+ */
+export class TelegramChannel extends BaseRuntimeChatChannel {
+  readonly name = "telegram" as const;
+  private readonly botToken?: string;
+
+  constructor(options: TelegramChannelOptions = {}) {
+    super(options);
+    this.botToken = String(options.botToken || "").trim() || undefined;
+  }
+
+  getAccount(_context: AgentContext): StoredChannelAccount | null {
+    const storedAccount = this.getStoredAccount();
+    if (storedAccount) return storedAccount;
+
+    const token = String(this.botToken || this.env.TELEGRAM_BOT_TOKEN || "").trim();
+    if (!token) return null;
+    const now = this.nowIso();
+    return {
+      id: this.channelAccountId || "chat-sdk-telegram",
+      channel: "telegram",
+      name: this.displayName || "telegram",
+      botToken: token,
+      createdAt: now,
+      updatedAt: now,
+    };
+  }
+}
+
+/**
+ * Feishu channel 配置。
+ */
+export interface FeishuChannelOptions extends BaseChatChannelOptions {
+  /**
+   * Feishu / Lark App ID。
+   */
+  appId?: string;
+  /**
+   * Feishu / Lark App Secret。
+   */
+  appSecret?: string;
+  /**
+   * Feishu / Lark Open API 域名。
+   */
+  domain?: string;
+}
+
+/**
+ * Feishu channel。
+ */
+export class FeishuChannel extends BaseRuntimeChatChannel {
+  readonly name = "feishu" as const;
+  private readonly appId?: string;
+  private readonly appSecret?: string;
+  private readonly domain?: string;
+
+  constructor(options: FeishuChannelOptions = {}) {
+    super(options);
+    this.appId = String(options.appId || "").trim() || undefined;
+    this.appSecret = String(options.appSecret || "").trim() || undefined;
+    this.domain = String(options.domain || "").trim() || undefined;
+  }
+
+  getAccount(_context: AgentContext): StoredChannelAccount | null {
+    const storedAccount = this.getStoredAccount();
+    if (storedAccount) return storedAccount;
+
+    const appId = String(this.appId || this.env.FEISHU_APP_ID || "").trim();
+    const appSecret = String(
+      this.appSecret || this.env.FEISHU_APP_SECRET || "",
+    ).trim();
+    const domain = String(this.domain || this.env.FEISHU_DOMAIN || "").trim();
+    if (!appId || !appSecret) return null;
+    const now = this.nowIso();
+    return {
+      id: this.channelAccountId || "chat-sdk-feishu",
+      channel: "feishu",
+      name: this.displayName || "feishu",
+      appId,
+      appSecret,
+      ...(domain ? { domain } : {}),
+      createdAt: now,
+      updatedAt: now,
+    };
+  }
+}
+
+/**
+ * QQ channel 配置。
+ */
+export interface QqChannelOptions extends BaseChatChannelOptions {
+  /**
+   * QQ Bot App ID。
+   */
+  appId?: string;
+  /**
+   * QQ Bot App Secret。
+   */
+  appSecret?: string;
+  /**
+   * 是否使用 QQ 沙箱模式。
+   */
+  sandbox?: boolean;
+}
+
+/**
+ * QQ channel。
+ */
+export class QqChannel extends BaseRuntimeChatChannel {
+  readonly name = "qq" as const;
+  private readonly appId?: string;
+  private readonly appSecret?: string;
+  private readonly sandbox?: boolean;
+
+  constructor(options: QqChannelOptions = {}) {
+    super(options);
+    this.appId = String(options.appId || "").trim() || undefined;
+    this.appSecret = String(options.appSecret || "").trim() || undefined;
+    this.sandbox = options.sandbox === true;
+  }
+
+  getAccount(_context: AgentContext): StoredChannelAccount | null {
+    const storedAccount = this.getStoredAccount();
+    if (storedAccount) return storedAccount;
+
+    const appId = String(this.appId || this.env.QQ_APP_ID || "").trim();
+    const appSecret = String(this.appSecret || this.env.QQ_APP_SECRET || "").trim();
+    const sandbox =
+      this.sandbox === true ||
+      String(this.env.QQ_SANDBOX || "").trim().toLowerCase() === "true";
+    if (!appId || !appSecret) return null;
+    const now = this.nowIso();
+    return {
+      id: this.channelAccountId || "chat-sdk-qq",
+      channel: "qq",
+      name: this.displayName || "qq",
+      appId,
+      appSecret,
+      ...(sandbox ? { sandbox: true } : {}),
+      createdAt: now,
+      updatedAt: now,
+    };
+  }
+}