@downcity/plugins 1.0.56 → 1.0.59

package/src/asr/types/AsrPlugin.ts

@@ -0,0 +1,118 @@
+/**
+ * AsrPlugin 类型定义。
+ *
+ * 关键点（中文）
+ * - ASR plugin 只定义 agent 侧协议，不绑定本地模型、Python 或 City 具体实现。
+ * - 真实转写能力通过 constructor 的 `asr` 函数注入，推荐传入 `city.ai.asr`。
+ * - `auto` 只表示是否在 chat 入站时自动转写语音附件。
+ */
+
+import type { JsonObject, JsonValue } from "@downcity/agent/internal/types/common/Json.js";
+
+/**
+ * ASR 输入。
+ */
+export interface AsrPluginInput {
+  /**
+   * 本地音频文件路径。
+   *
+   * 说明（中文）
+   * - chat runtime 下载附件后会传入本地路径。
+   * - 显式 action 调用时也优先使用该字段。
+   */
+  audio_path?: string;
+  /**
+   * 远程音频 URL。
+   */
+  url?: string;
+  /**
+   * data URL 音频内容。
+   */
+  data_url?: string;
+  /**
+   * 语言提示，例如 `auto`、`zh`、`en`。
+   */
+  language?: string;
+  /**
+   * 音频 MIME 类型，例如 `audio/ogg`。
+   */
+  media_type?: string;
+  /**
+   * 原始文件名。
+   */
+  file_name?: string;
+  /**
+   * Provider 私有参数。
+   */
+  provider_options?: JsonObject;
+  /**
+   * 允许外部 asr 函数接收其他 JSON 可序列化参数。
+   */
+  [key: string]: JsonValue | undefined;
+}
+
+/**
+ * ASR 输出。
+ */
+export interface AsrPluginResult {
+  /**
+   * 转写文本。
+   */
+  text: string;
+  /**
+   * 识别到的语言（可选）。
+   */
+  language?: string;
+  /**
+   * 结果置信度（可选）。
+   */
+  confidence?: number;
+  /**
+   * Provider 原始元信息（可选）。
+   */
+  metadata?: JsonObject;
+  /**
+   * 允许外部 asr 函数返回其他 JSON 可序列化字段。
+   */
+  [key: string]: JsonValue | undefined;
+}
+
+/**
+ * AsrPlugin 构造参数。
+ */
+export interface AsrPluginOptions {
+  /**
+   * Plugin 稳定名称，默认 `asr`。
+   */
+  name?: string;
+  /**
+   * Plugin 展示标题，默认 `ASR`。
+   */
+  title?: string;
+  /**
+   * Plugin 用途说明。
+   */
+  description?: string;
+  /**
+   * 真实 ASR 能力函数。
+   *
+   * 说明（中文）
+   * - 推荐传入 `(input) => city.ai.asr(input)`。
+   * - plugin 只负责调用该函数，不关心模型、provider、鉴权或运行依赖。
+   */
+  asr: (input: AsrPluginInput) => Promise<AsrPluginResult> | AsrPluginResult;
+  /**
+   * 是否自动转写 chat 入站语音附件。
+   *
+   * 说明（中文）
+   * - `true`：遇到 voice/audio 附件时自动调用 `asr`。
+   * - `false`：仅保留显式 `transcribe` action。
+   * - 默认 `false`，避免 agent 隐式调用外部 ASR 成本。
+   */
+  auto?: boolean;
+  /**
+   * 默认语言提示。
+   */
+  language?: string;
+}
+

package/src/auth/types/AuthPlugin.ts

@@ -1,20 +1,15 @@
 /**
- * ChatAuthorizationPlugin 类型与契约定义。
+ * ChatAuthorization 类型与契约定义。
  *
  * 关键点（中文）
- * - 统一维护聊天授权 plugin 的领域类型、扩展点/action 名称、payload 契约。
- * - 业务层不应散落硬编码字符串，如 `chat.authorizeIncoming`、`set-user-role`。
- * - chat / console / plugin 执行链路都从这里共享同一份边界定义。
+ * - 统一维护 ChatPlugin 内置授权能力的领域类型、扩展点/action 名称、payload 契约。
+ * - 业务层不应散落硬编码字符串，如 `chat.authorizeIncoming`、`authorization-set-user-role`。
+ * - chat / console / plugin action 执行链路都从这里共享同一份边界定义。
  */
 
 import type { ChatDispatchChannel } from "@/chat/types/ChatDispatcher.js";
 import { CHAT_PLUGIN_POINTS } from "@/chat/runtime/PluginPoints.js";
 
-/**
- * 聊天授权 plugin 稳定名称。
- */
-export const CHAT_AUTHORIZATION_PLUGIN_NAME = "chat-authorization";
-
 /**
  * 聊天授权支持的渠道目录。
  */
@@ -28,7 +23,7 @@ export type ChatAuthorizationChannel = (typeof CHAT_AUTHORIZATION_CHANNELS)[numb
 /**
  * 聊天授权扩展点名称集合。
  */
-export const CHAT_AUTHORIZATION_PLUGIN_POINTS = {
+export const CHAT_AUTHORIZATION_POINTS = {
   observePrincipal: CHAT_PLUGIN_POINTS.observePrincipal,
   authorizeIncoming: CHAT_PLUGIN_POINTS.authorizeIncoming,
   resolveUserRole: CHAT_PLUGIN_POINTS.resolveUserRole,
@@ -38,10 +33,10 @@ export const CHAT_AUTHORIZATION_PLUGIN_POINTS = {
  * 聊天授权 action 名称集合。
  */
 export const CHAT_AUTHORIZATION_ACTIONS = {
-  snapshot: "snapshot",
-  readConfig: "read-config",
-  writeConfig: "write-config",
-  setUserRole: "set-user-role",
+  snapshot: "authorization-snapshot",
+  readConfig: "authorization-read-config",
+  writeConfig: "authorization-write-config",
+  setUserRole: "authorization-set-user-role",
 } as const;
 
 /**
@@ -463,7 +458,7 @@ export interface ChatAuthorizationStateFile {
 }
 
 /**
- * plugin effect 输入：记录观测主体。
+ * ChatPlugin effect 输入：记录观测主体。
  */
 export interface ChatAuthorizationObservePrincipalPayload {
   /**
@@ -493,7 +488,7 @@ export interface ChatAuthorizationObservePrincipalPayload {
 }
 
 /**
- * plugin effect 输出：记录观测主体结果。
+ * ChatPlugin effect 输出：记录观测主体结果。
  */
 export interface ChatAuthorizationObservePrincipalResult {
   /**
@@ -503,7 +498,7 @@ export interface ChatAuthorizationObservePrincipalResult {
 }
 
 /**
- * plugin resolve 输入：查询用户角色。
+ * ChatPlugin resolve 输入：查询用户角色。
  */
 export interface ChatAuthorizationResolveUserRolePayload {
   /**

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);