@downcity/plugins 1.0.56 → 1.0.59

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,
+    };
+  }
+}

package/src/chat/runtime/ChatAuthorizationRuntime.ts

@@ -0,0 +1,229 @@
+/**
+ * ChatAuthorizationRuntime：ChatPlugin 内置授权能力。
+ *
+ * 关键点（中文）
+ * - 授权能力归属于 ChatPlugin，不再作为独立 plugin 注册。
+ * - chat runtime 仍通过通用 plugin hook / resolve 点调用，保持执行链路统一。
+ * - action 名称统一带 `authorization-` 前缀，避免和 chat 会话动作混淆。
+ */
+
+import type {
+  PluginActions,
+  PluginHooks,
+  PluginResolves,
+} from "@downcity/agent/internal/plugin/types/Plugin.js";
+import type { JsonValue } from "@downcity/agent/internal/types/common/Json.js";
+import { CHAT_PLUGIN_POINTS } from "@/chat/runtime/PluginPoints.js";
+import type { ChatDispatchChannel } from "@/chat/types/ChatDispatcher.js";
+import {
+  CHAT_AUTHORIZATION_ACTIONS,
+  CHAT_AUTHORIZATION_CATALOG,
+  type ChatAuthorizationConfig,
+  type ChatAuthorizationEvaluateInput,
+  type ChatAuthorizationObservePrincipalPayload,
+  type ChatAuthorizationSetUserRolePayload,
+  type ChatAuthorizationSnapshot,
+  type ChatAuthorizationWriteConfigPayload,
+} from "@/auth/types/AuthPlugin.js";
+import {
+  readChatAuthorizationConfig,
+  setChatAuthorizationUserRole,
+  writeChatAuthorizationConfig,
+} from "@/auth/runtime/AuthorizationConfig.js";
+import {
+  evaluateIncomingChatAuthorization,
+  resolveAuthorizedUserRole,
+} from "@/auth/runtime/AuthorizationPolicy.js";
+import {
+  readAuthorizationSnapshot,
+  recordObservedAuthorizationPrincipal,
+} from "@/auth/runtime/AuthorizationStore.js";
+
+function toChannel(value: unknown): ChatDispatchChannel | null {
+  const text = String(value || "").trim().toLowerCase();
+  if (text === "telegram" || text === "feishu" || text === "qq") return text;
+  return null;
+}
+
+function toRecord(value: unknown): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return {};
+  return value as Record<string, unknown>;
+}
+
+function toEvaluateInput(payload: Record<string, unknown>): ChatAuthorizationEvaluateInput {
+  const channel = toChannel(payload.channel);
+  if (!channel) {
+    throw new Error("chat.authorizeIncoming requires a valid channel");
+  }
+  return {
+    channel,
+    chatId: String(payload.chatId || "").trim(),
+    ...(typeof payload.chatType === "string" ? { chatType: payload.chatType.trim() } : {}),
+    ...(typeof payload.userId === "string" ? { userId: payload.userId.trim() } : {}),
+    ...(typeof payload.username === "string" ? { username: payload.username.trim() } : {}),
+    ...(typeof payload.chatTitle === "string" ? { chatTitle: payload.chatTitle.trim() } : {}),
+  };
+}
+
+function toSnapshotData(snapshot: ChatAuthorizationSnapshot): JsonValue {
+  return {
+    catalog: CHAT_AUTHORIZATION_CATALOG as unknown as JsonValue,
+    config: snapshot.config as unknown as JsonValue,
+    users: snapshot.users as unknown as JsonValue,
+    chats: snapshot.chats as unknown as JsonValue,
+  };
+}
+
+/**
+ * 创建 ChatPlugin 内置授权 hooks。
+ */
+export function createChatAuthorizationHooks(): PluginHooks {
+  return {
+    guard: {
+      [CHAT_PLUGIN_POINTS.authorizeIncoming]: [
+        async ({ context, value }) => {
+          const input =
+            value && typeof value === "object" && !Array.isArray(value)
+              ? (value as Record<string, unknown>)
+              : {};
+          const evaluateInput = toEvaluateInput(input);
+          const authorizationConfig = readChatAuthorizationConfig(context);
+          const result = evaluateIncomingChatAuthorization({
+            config: context.config,
+            channel: evaluateInput.channel,
+            input: evaluateInput,
+            authorizationConfig,
+          });
+          if (result.decision !== "allow") {
+            throw new Error(result.reason || "chat authorization blocked");
+          }
+        },
+      ],
+    },
+    effect: {
+      [CHAT_PLUGIN_POINTS.observePrincipal]: [
+        async ({ context, value }) => {
+          const input = toRecord(
+            value,
+          ) as unknown as ChatAuthorizationObservePrincipalPayload;
+          const channel = toChannel(input.channel);
+          if (!channel) {
+            throw new Error("chat.observePrincipal requires a valid channel");
+          }
+          await recordObservedAuthorizationPrincipal({
+            context,
+            channel,
+            chatId: String(input.chatId || "").trim(),
+            ...(typeof input.chatType === "string"
+              ? { chatType: input.chatType.trim() }
+              : {}),
+            ...(typeof input.chatTitle === "string"
+              ? { chatTitle: input.chatTitle.trim() }
+              : {}),
+            ...(typeof input.userId === "string"
+              ? { userId: input.userId.trim() }
+              : {}),
+            ...(typeof input.username === "string"
+              ? { username: input.username.trim() }
+              : {}),
+          });
+        },
+      ],
+    },
+  };
+}
+
+/**
+ * 创建 ChatPlugin 内置授权 resolve 点。
+ */
+export function createChatAuthorizationResolves(): PluginResolves {
+  return {
+    [CHAT_PLUGIN_POINTS.resolveUserRole]: async ({ context, value }) => {
+      const input =
+        value && typeof value === "object" && !Array.isArray(value)
+          ? (value as Record<string, unknown>)
+          : {};
+      const channel = toChannel(input.channel);
+      if (!channel) {
+        throw new Error("chat.resolveUserRole requires a valid channel");
+      }
+      const role = resolveAuthorizedUserRole({
+        channel,
+        userId: String(input.userId || "").trim(),
+        rootPath: context.rootPath,
+      });
+      return ((role || null) as unknown) as JsonValue;
+    },
+  };
+}
+
+/**
+ * 创建 ChatPlugin 内置授权 actions。
+ */
+export function createChatAuthorizationActions(): PluginActions {
+  return {
+    [CHAT_AUTHORIZATION_ACTIONS.snapshot]: {
+      execute: async ({ context }) => {
+        const snapshot = await readAuthorizationSnapshot({
+          context,
+        });
+        return {
+          success: true,
+          data: toSnapshotData(snapshot),
+        };
+      },
+    },
+    [CHAT_AUTHORIZATION_ACTIONS.readConfig]: {
+      execute: async ({ context }) => {
+        return {
+          success: true,
+          data: readChatAuthorizationConfig(context) as unknown as JsonValue,
+        };
+      },
+    },
+    [CHAT_AUTHORIZATION_ACTIONS.writeConfig]: {
+      execute: async ({ context, payload }) => {
+        const body = toRecord(
+          payload,
+        ) as unknown as ChatAuthorizationWriteConfigPayload;
+        const nextConfig =
+          body.config && typeof body.config === "object" && !Array.isArray(body.config)
+            ? (body.config as ChatAuthorizationConfig)
+            : {};
+        await writeChatAuthorizationConfig({
+          context,
+          nextConfig,
+        });
+        return {
+          success: true,
+          data: readChatAuthorizationConfig(context) as unknown as JsonValue,
+        };
+      },
+    },
+    [CHAT_AUTHORIZATION_ACTIONS.setUserRole]: {
+      execute: async ({ context, payload }) => {
+        const body = toRecord(
+          payload,
+        ) as unknown as ChatAuthorizationSetUserRolePayload;
+        const channel = toChannel(body.channel);
+        if (!channel) {
+          return {
+            success: false,
+            error: "authorization-set-user-role requires a valid channel",
+            message: "authorization-set-user-role requires a valid channel",
+          };
+        }
+        await setChatAuthorizationUserRole({
+          context,
+          channel,
+          userId: String(body.userId || "").trim(),
+          roleId: String(body.roleId || "").trim(),
+        });
+        return {
+          success: true,
+          data: readChatAuthorizationConfig(context) as unknown as JsonValue,
+        };
+      },
+    },
+  };
+}

package/src/chat/runtime/ChatChannelActions.ts

@@ -25,11 +25,11 @@ import {
   getChatChannelStatus,
   listChatChannelConfigurationDescriptions,
   normalizeChatChannelConfigPatch,
-  setChatChannelConfig,
-  setChatChannelEnabled,
 } from "./ChatChannelConfig.js";
 import {
+  type ChatRuntimeBindings,
   getChatChannelBot,
+  resolveChatPluginBindings,
   resolveTargetChannels,
 } from "./ChatChannelCore.js";
 import {
@@ -37,6 +37,18 @@ import {
   stopSingleChatChannel,
 } from "./ChatChannelLifecycle.js";
 
+type ChatRuntimeControlBindings = ChatRuntimeBindings & {
+  applyChannelRuntimePatch: NonNullable<ChatRuntimeBindings["applyChannelRuntimePatch"]>;
+};
+
+function getChatRuntimeBindings(context: AgentContext): ChatRuntimeControlBindings {
+  const plugin = resolveChatPluginBindings(context);
+  if (!plugin?.applyChannelRuntimePatch) {
+    throw new Error("ChatPlugin runtime instance is not available");
+  }
+  return plugin as ChatRuntimeControlBindings;
+}
+
 /**
  * 执行 `chat.status` action。
  */
@@ -163,9 +175,9 @@ export async function executeChatOpenAction(params: {
   payload: ChatOpenActionPayload;
 }) {
   const targets = resolveTargetChannels(params.payload.channel);
+  const plugin = getChatRuntimeBindings(params.context);
   for (const channel of targets) {
-    await setChatChannelEnabled({
-      context: params.context,
+    plugin.applyChannelRuntimePatch({
       channel,
       enabled: true,
     });
@@ -198,10 +210,10 @@ export async function executeChatCloseAction(params: {
   payload: ChatCloseActionPayload;
 }) {
   const targets = resolveTargetChannels(params.payload.channel);
+  const plugin = getChatRuntimeBindings(params.context);
   for (const channel of targets) {
     await stopSingleChatChannel(params.state, channel);
-    await setChatChannelEnabled({
-      context: params.context,
+    plugin.applyChannelRuntimePatch({
       channel,
       enabled: false,
     });
@@ -280,10 +292,13 @@ export async function executeChatConfigureAction(params: {
     }
   }
 
-  await setChatChannelConfig({
-    context: params.context,
+  const plugin = getChatRuntimeBindings(params.context);
+  plugin.applyChannelRuntimePatch({
     channel,
-    patch,
+    ...(typeof patch.enabled === "boolean" ? { enabled: patch.enabled } : {}),
+    ...(Object.prototype.hasOwnProperty.call(patch, "channelAccountId")
+      ? { channelAccountId: String(patch.channelAccountId || "").trim() || null }
+      : {}),
   });
 
   // 关键点（中文）：默认重载一次目标渠道，让新配置立刻生效。

package/src/chat/runtime/ChatChannelConfig.ts

@@ -2,13 +2,11 @@
  * ChatChannelConfig：chat 渠道配置与状态快照模块。
  *
  * 关键点（中文）
- * - 渠道配置摘要、状态快照、patch 归一化、downcity.json 落盘都收敛在这里。
- * - 所有配置写入都遵循“先改内存，再落盘”的一致性顺序。
+ * - 渠道配置摘要、状态快照、patch 归一化都收敛在这里。
+ * - chat.configure 的运行态写入由 ChatPlugin 实例承载，不再落盘到 downcity.json。
  * - 该模块不直接负责 action 流程控制，只提供可复用的底层能力。
  */
 
-import fs from "node:fs/promises";
-import path from "node:path";
 import type { JsonObject, JsonValue } from "@downcity/agent/internal/types/common/Json.js";
 import type { AgentContext } from "@downcity/agent/internal/types/runtime/agent/AgentContext.js";
 import type { StoredChannelAccount } from "@downcity/agent/internal/types/platform/Store.js";
@@ -109,47 +107,6 @@ export function getChatChannelStatus(
   };
 }
 
-/**
- * 更新内存配置与 downcity.json 中的 channel enabled 状态。
- */
-export async function setChatChannelEnabled(params: {
-  context: AgentContext;
-  channel: ChatChannelName;
-  enabled: boolean;
-}): Promise<void> {
-  const { context, channel, enabled } = params;
-
-  const configPlugins = ((context.config.plugins ??= {}) as {
-    chat?: {
-      channels?: Record<string, Record<string, unknown>>;
-    };
-  });
-  const chatConfig = (configPlugins.chat ??= {});
-  const channelConfigs = (chatConfig.channels ??= {});
-  const channelConfig = (channelConfigs[channel] ??= {});
-  channelConfig.enabled = enabled;
-
-  const shipPath = path.join(context.rootPath, "downcity.json");
-  let shipJson: Record<string, unknown> = {};
-  try {
-    const raw = await fs.readFile(shipPath, "utf-8");
-    const parsed = JSON.parse(raw) as unknown;
-    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
-      shipJson = parsed as Record<string, unknown>;
-    }
-  } catch {
-    shipJson = {};
-  }
-
-  const shipPlugins = ((shipJson.plugins ??= {}) as Record<string, unknown>);
-  const shipChat = ((shipPlugins.chat ??= {}) as Record<string, unknown>);
-  const shipChannels = ((shipChat.channels ??= {}) as Record<string, unknown>);
-  const shipChannel = ((shipChannels[channel] ??= {}) as Record<string, unknown>);
-  shipChannel.enabled = enabled;
-
-  await fs.writeFile(shipPath, `${JSON.stringify(shipJson, null, 2)}\n`, "utf-8");
-}
-
 function isJsonObject(value: JsonValue): value is JsonObject {
   return !!value && typeof value === "object" && !Array.isArray(value);
 }
@@ -253,61 +210,6 @@ export function normalizeChatChannelConfigPatch(params: {
   return patch;
 }
 
-function applyChannelPatch(
-  target: Record<string, unknown>,
-  patch: Record<string, string | number | boolean | null>,
-): void {
-  for (const [key, value] of Object.entries(patch)) {
-    if (value === null) {
-      delete target[key];
-      continue;
-    }
-    target[key] = value;
-  }
-}
-
-/**
- * 更新单个 channel 配置（内存 + downcity.json）。
- */
-export async function setChatChannelConfig(params: {
-  context: AgentContext;
-  channel: ChatChannelName;
-  patch: Record<string, string | number | boolean | null>;
-}): Promise<void> {
-  const { context, channel, patch } = params;
-  if (Object.keys(patch).length === 0) return;
-
-  const configPlugins = ((context.config.plugins ??= {}) as {
-    chat?: {
-      channels?: Record<string, Record<string, unknown>>;
-    };
-  });
-  const chatConfig = (configPlugins.chat ??= {});
-  const channelConfigs = (chatConfig.channels ??= {});
-  const channelConfig = (channelConfigs[channel] ??= {});
-  applyChannelPatch(channelConfig, patch);
-
-  const shipPath = path.join(context.rootPath, "downcity.json");
-  let shipJson: Record<string, unknown> = {};
-  try {
-    const raw = await fs.readFile(shipPath, "utf-8");
-    const parsed = JSON.parse(raw) as unknown;
-    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
-      shipJson = parsed as Record<string, unknown>;
-    }
-  } catch {
-    shipJson = {};
-  }
-
-  const shipPlugins = ((shipJson.plugins ??= {}) as Record<string, unknown>);
-  const shipChat = ((shipPlugins.chat ??= {}) as Record<string, unknown>);
-  const shipChannels = ((shipChat.channels ??= {}) as Record<string, unknown>);
-  const shipChannel = ((shipChannels[channel] ??= {}) as Record<string, unknown>);
-  applyChannelPatch(shipChannel, patch);
-
-  await fs.writeFile(shipPath, `${JSON.stringify(shipJson, null, 2)}\n`, "utf-8");
-}
-
 /**
  * 读取渠道 configuration 描述。
  */