@downcity/plugins 1.0.254 → 1.0.280

package/src/chat/channels/RuntimeChannel.ts

@@ -4,7 +4,7 @@
  * 关键点（中文）
  * - channel 对象是 ChatPlugin 的运行态配置单元。
  * - env 由 channel 自己读取，ChatPlugin 不理解平台字段。
- * - Resource 已由宿主解析为构造参数，channel 不访问账号池或其他外部 Store。
+ * - 配置已由宿主解析为构造参数，channel 不访问其他外部 Store。
  */
 
 import type { PluginContext } from "@downcity/agent";
@@ -38,7 +38,7 @@ export interface BaseChatChannelOptions {
    */
   env?: ChatChannelEnv;
   /**
-   * Resource 或 SDK 调用方提供的稳定 ID。
+   * Plugin profile 或 SDK 调用方提供的稳定 ID。
    */
   id?: string;
   /**
@@ -55,13 +55,13 @@ abstract class BaseRuntimeChatChannel implements ChatChannel {
 
   protected enabled: boolean;
   protected env: ChatChannelEnv;
-  protected resource_id: string;
+  protected channel_id: string;
   protected display_name: string;
 
   protected constructor(options: BaseChatChannelOptions = {}) {
     this.enabled = options.enabled !== false;
     this.env = options.env || {};
-    this.resource_id = String(options.id || "").trim();
+    this.channel_id = String(options.id || "").trim();
     this.display_name = String(options.name || "").trim();
   }
 
@@ -69,8 +69,8 @@ abstract class BaseRuntimeChatChannel implements ChatChannel {
     return this.enabled;
   }
 
-  getResourceId(_context: PluginContext): string {
-    return this.resource_id;
+  get_channel_id(_context: PluginContext): string {
+    return this.channel_id;
   }
 
   protected nowIso(): string {
@@ -110,7 +110,7 @@ export class TelegramChannel extends BaseRuntimeChatChannel {
     if (!token) return null;
     const now = this.nowIso();
     return {
-      id: this.resource_id || "chat-sdk-telegram",
+      id: this.channel_id || "chat-sdk-telegram",
       channel: "telegram",
       name: this.display_name || "telegram",
       bot_token: token,
@@ -163,7 +163,7 @@ export class FeishuChannel extends BaseRuntimeChatChannel {
     if (!appId || !appSecret) return null;
     const now = this.nowIso();
     return {
-      id: this.resource_id || "chat-sdk-feishu",
+      id: this.channel_id || "chat-sdk-feishu",
       channel: "feishu",
       name: this.display_name || "feishu",
       app_id: appId,
@@ -218,7 +218,7 @@ export class QqChannel extends BaseRuntimeChatChannel {
     if (!appId || !appSecret) return null;
     const now = this.nowIso();
     return {
-      id: this.resource_id || "chat-sdk-qq",
+      id: this.channel_id || "chat-sdk-qq",
       channel: "qq",
       name: this.display_name || "qq",
       app_id: appId,

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

@@ -64,7 +64,7 @@ export class FeishuBot extends BaseChatChannel {
     this.appId = appId;
     this.appSecret = appSecret;
     this.domain = domain;
-    this.dedupeDir = get_feishu_dedupe_dir_path(context.workspace_path);
+    this.dedupeDir = get_feishu_dedupe_dir_path(context.data_path);
     this.platform = new FeishuPlatformClient({
       context,
       config: {

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

@@ -60,6 +60,7 @@ export interface FeishuPlatformClientOptions {
 export class FeishuPlatformClient {
   private readonly context: PluginContext;
   private readonly rootPath: string;
+  private readonly dataPath: string;
   private readonly logger: PluginContext["logger"];
   private readonly appId: string;
   private readonly appSecret: string;
@@ -79,6 +80,7 @@ export class FeishuPlatformClient {
   constructor(options: FeishuPlatformClientOptions) {
     this.context = options.context;
     this.rootPath = options.context.workspace_path;
+    this.dataPath = options.context.data_path;
     this.logger = options.context.logger;
     this.appId = options.config.appId;
     this.appSecret = options.config.appSecret;
@@ -394,6 +396,7 @@ export class FeishuPlatformClient {
   private getLookupDeps() {
     return {
       rootPath: this.rootPath,
+      dataPath: this.dataPath,
       logger: this.logger,
       client: this.client,
       getAppAccessToken: () => this.getAppAccessToken(),

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

@@ -26,6 +26,8 @@ export interface FeishuLookupDeps {
    * 项目根目录。
    */
   rootPath: string;
+  /** Agent private runtime directory 内部数据根目录。 */
+  dataPath: string;
   /**
    * 日志器。
    */
@@ -481,7 +483,7 @@ export async function downloadFeishuIncomingAttachments(
 ): Promise<FeishuDownloadedAttachment[]> {
   if (!deps.client || params.attachments.length === 0) return [];
 
-  const dir = path.join(deps.rootPath, ".downcity", ".cache", "feishu");
+  const dir = path.join(deps.dataPath, ".cache", "feishu");
   await fs.ensureDir(dir);
 
   const out: FeishuDownloadedAttachment[] = [];

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

@@ -58,7 +58,7 @@ export class QQBot extends BaseChatChannel {
     this.appSecret = appSecret;
     this.useSandbox = useSandbox;
     this.inboundDedupeStore = new QqInboundDedupeStore({
-      rootPath: this.rootPath,
+      dataPath: this.dataPath,
       logger: this.logger,
     });
     this.gateway = new QQGatewayClient({
@@ -67,7 +67,7 @@ export class QQBot extends BaseChatChannel {
       appId: this.appId,
       appSecret: this.appSecret,
       useSandbox: this.useSandbox,
-      captureConfig: getQqEventCaptureConfig(this.rootPath),
+      captureConfig: getQqEventCaptureConfig(this.dataPath),
       onDispatch: async (params) => {
         await this.handleDispatch(params.eventType, params.data);
       },
@@ -268,6 +268,7 @@ export class QQBot extends BaseChatChannel {
     return {
       context: this.context,
       rootPath: this.rootPath,
+      dataPath: this.dataPath,
       logger: this.logger,
       getBotUserId: () => this.botUserId,
       getChatKey: (params) => this.getChatKey(params),

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

@@ -14,7 +14,7 @@ import type { QQEventCaptureConfig, QQEventCaptureMode, QQGatewayPayload } from
 /**
  * 读取 QQ 原始事件捕获配置。
  */
-export function getQqEventCaptureConfig(project_root: string): QQEventCaptureConfig {
+export function getQqEventCaptureConfig(data_path: string): QQEventCaptureConfig {
   const raw = String(process.env.SHIP_QQ_CAPTURE_EVENTS ?? "")
     .trim()
     .toLowerCase();
@@ -22,7 +22,7 @@ export function getQqEventCaptureConfig(project_root: string): QQEventCaptureCon
     return {
       enabled: false,
       mode: "dispatch",
-      dir: join(project_root, ".downcity", ".debug", "qq-events"),
+      dir: join(data_path, ".debug", "qq-events"),
     };
   }
 
@@ -32,7 +32,7 @@ export function getQqEventCaptureConfig(project_root: string): QQEventCaptureCon
     typeof process.env.SHIP_QQ_CAPTURE_DIR === "string" &&
     process.env.SHIP_QQ_CAPTURE_DIR.trim()
       ? process.env.SHIP_QQ_CAPTURE_DIR.trim()
-      : join(project_root, ".downcity", ".debug", "qq-events");
+      : join(data_path, ".debug", "qq-events");
 
   return {
     enabled: true,

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

@@ -23,7 +23,7 @@ export class QqInboundDedupeStore {
   private loaded: boolean = false;
 
   constructor(params: {
-    rootPath: string;
+    dataPath: string;
     logger: Logger;
     maxEntries?: number;
   }) {
@@ -35,8 +35,7 @@ export class QqInboundDedupeStore {
         ? Math.floor(params.maxEntries)
         : 2000;
     this.filePath = path.join(
-      params.rootPath,
-      ".downcity",
+      params.dataPath,
       ".cache",
       "qq",
       "inbound-dedupe.json",

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

@@ -57,6 +57,10 @@ export interface QQMessageHandlerOptions {
    * 项目根目录。
    */
   rootPath: string;
+  /**
+   * 当前 Agent private runtime directory 的私有数据目录。
+   */
+  dataPath: string;
   /**
    * 日志器。
    */
@@ -256,6 +260,7 @@ export async function handleQqChannelMessage(
   const instructions = await buildQqInboundInstructions({
     context: options.context,
     rootPath: options.rootPath,
+    dataPath: options.dataPath,
     chatId: channelId,
     chat_key: options.getChatKey({ chatId: channelId, chatType }),
     message_id,
@@ -410,6 +415,7 @@ async function handleQqInboundMessage(
   const instructions = await buildQqInboundInstructions({
     context: options.context,
     rootPath: options.rootPath,
+    dataPath: options.dataPath,
     chatId,
     chat_key,
     message_id,

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

@@ -57,6 +57,10 @@ export interface BuildQqInboundInstructionsParams {
    * 项目根目录。
    */
   rootPath: string;
+  /**
+   * 当前 Agent private runtime directory 的私有数据目录。
+   */
+  dataPath: string;
   /**
    * 平台 chatId。
    */
@@ -233,6 +237,7 @@ export async function buildQqInboundInstructions(
       try {
         const localPath = await resolveQqAttachmentLocalPath({
           rootPath: params.rootPath,
+          dataPath: params.dataPath,
           attachment,
           authToken,
         });

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

@@ -298,6 +298,7 @@ function defaultExtByKind(kind: QqInboundAttachmentKind): string {
 }
 
 async function downloadRemoteAttachment(params: {
+  dataPath: string;
   rootPath: string;
   attachment: QqIncomingAttachment;
   authToken?: string;
@@ -346,7 +347,7 @@ async function downloadRemoteAttachment(params: {
     extFromContentType(responseType) ||
     defaultExtByKind(params.attachment.kind);
 
-  const dir = path.join(params.rootPath, ".downcity", ".cache", "qq");
+  const dir = path.join(params.dataPath, ".cache", "qq");
   await mkdir(dir, { recursive: true });
 
   const stem = safeBase.replace(/\.[^.]+$/, "");
@@ -364,6 +365,9 @@ async function downloadRemoteAttachment(params: {
  * - 远程 URL 会按需下载到 cache，再返回绝对路径。
  */
 export async function resolveQqAttachmentLocalPath(params: {
+  /** 当前 Agent private runtime directory 的私有数据目录，用于保存下载缓存。 */
+  dataPath: string;
+  /** 项目根目录，用于解析消息中已有的项目相对路径。 */
   rootPath: string;
   attachment: QqIncomingAttachment;
   authToken?: string;

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

@@ -38,11 +38,18 @@ function sleep(ms: number): Promise<void> {
 export class TelegramApiClient {
   private readonly botToken: string;
   private readonly rootPath: string;
+  private readonly dataPath: string;
   private readonly logger: Logger;
 
-  constructor(opts: { botToken: string; project_root: string; logger: Logger }) {
+  constructor(opts: {
+    botToken: string;
+    project_root: string;
+    data_path: string;
+    logger: Logger;
+  }) {
     this.botToken = opts.botToken;
     this.rootPath = opts.project_root;
+    this.dataPath = opts.data_path;
     this.logger = opts.logger;
   }
 
@@ -166,7 +173,7 @@ export class TelegramApiClient {
   }
 
   /**
-   * 下载 Telegram 文件并保存到 `.downcity/.cache/telegram`。
+   * 下载 Telegram 文件并保存到当前 Agent private runtime directory 数据目录的 `.cache/telegram`。
    *
    * 说明（中文）
    * - 文件名会做安全化处理，避免路径注入
@@ -200,7 +207,7 @@ export class TelegramApiClient {
       base.replace(/[^\w.\-()@\u4e00-\u9fff]+/g, "_").slice(0, 160) ||
       `tg-${fileId}`;
 
-    const dir = path.join(this.rootPath, ".downcity", ".cache", "telegram");
+    const dir = path.join(this.dataPath, ".cache", "telegram");
     await fs.ensureDir(dir);
     const uniq = `${Date.now()}-${fileId.slice(0, 8)}`;
     const outPath = path.join(dir, `${uniq}-${safeBase}`);

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

@@ -19,8 +19,8 @@ import type { JsonObject } from "@downcity/agent";
 export class TelegramStateStore {
   private readonly lastUpdateIdFile: string;
 
-  constructor(project_root: string) {
-    const dir = path.join(project_root, ".downcity", ".cache", "telegram");
+  constructor(data_path: string) {
+    const dir = path.join(data_path, ".cache", "telegram");
     this.lastUpdateIdFile = path.join(dir, "lastUpdateId.json");
   }
 

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

@@ -75,9 +75,10 @@ export class TelegramPlatformClient {
     this.api = new TelegramApiClient({
       botToken: options.botToken,
       project_root: options.context.workspace_path,
+      data_path: options.context.data_path,
       logger: options.context.logger,
     });
-    this.stateStore = new TelegramStateStore(options.context.workspace_path);
+    this.stateStore = new TelegramStateStore(options.context.data_path);
     this.onMessage = options.onMessage;
     this.onCallbackQuery = options.onCallbackQuery;
     this.onWebhookConflictResolved = options.onWebhookConflictResolved;

package/src/chat/main/ChatPluginMain.ts

@@ -0,0 +1,163 @@
+/** Chat Plugin Profile 的 main actions 与凭据边界。 */
+
+import {
+  define_plugin_main,
+  type PluginJsonObject,
+  type PluginJsonValue,
+} from "@downcity/plugin";
+import type { ChatPluginChannelConfig } from "@/chat/types/ChatPluginChannelConfig.js";
+import type { ChatPluginConfig } from "@/chat/types/ChatPluginConfig.js";
+import type {
+  ChatPluginPublicChannelConfig,
+  ChatPluginPublicProfile,
+  ChatPluginPublicQueueConfig,
+} from "@/chat/types/ChatPluginProfile.js";
+
+/** Chat Plugin 的宿主管理入口。 */
+export const CHAT_PLUGIN_MAIN = define_plugin_main({
+  activate({ plugin }) {
+    plugin.action({
+      id: "profile.read",
+      run: async (_input, context) => to_public_profile(
+        await context.config.get() as unknown as ChatPluginConfig,
+      ) as unknown as PluginJsonValue,
+    });
+    plugin.action({
+      id: "profile.save",
+      run: async (input, context) => {
+        const current = await context.config.get() as unknown as ChatPluginConfig;
+        const config = normalize_profile(input, current);
+        await context.config.set(config as unknown as PluginJsonObject);
+        return to_public_profile(config) as unknown as PluginJsonValue;
+      },
+    });
+  },
+});
+
+/** 把完整配置转换为不包含凭据原文的 Mainview 投影。 */
+function to_public_profile(config: ChatPluginConfig): ChatPluginPublicProfile {
+  return {
+    queue: { ...(config.queue ?? {}) },
+    channels: (config.channels ?? []).map((channel) => ({
+      id: channel.id,
+      type: channel.type,
+      name: channel.name,
+      ...(channel.type !== "telegram" ? { app_id: channel.app_id } : {}),
+      ...(channel.type === "feishu" && channel.domain ? { domain: channel.domain } : {}),
+      ...(channel.type === "qq" ? { sandbox: channel.sandbox === true } : {}),
+      secret_configured: channel.type === "telegram"
+        ? Boolean(channel.bot_token)
+        : Boolean(channel.app_secret),
+    })),
+  };
+}
+
+/** 校验 Mainview 草稿并补回未重新填写的已有凭据。 */
+function normalize_profile(
+  input: PluginJsonValue | undefined,
+  current: ChatPluginConfig,
+): ChatPluginConfig {
+  const profile = as_record(input, "Chat Profile");
+  const queue = normalize_queue(profile.queue);
+  const channel_values = profile.channels;
+  if (!Array.isArray(channel_values)) throw new Error("Chat channels must be an array");
+  const channel_types = new Set<string>();
+  const channel_ids = new Set<string>();
+  const channels = channel_values.map((value) => {
+    const channel = normalize_channel(value, current.channels ?? []);
+    if (channel_types.has(channel.type)) {
+      throw new Error(`Chat Channel type is duplicated: ${channel.type}`);
+    }
+    if (channel_ids.has(channel.id)) {
+      throw new Error(`Chat Channel ID is duplicated: ${channel.id}`);
+    }
+    channel_types.add(channel.type);
+    channel_ids.add(channel.id);
+    return channel;
+  });
+  return {
+    ...(Object.keys(queue).length > 0 ? { queue } : {}),
+    channels,
+  };
+}
+
+/** 校验 Chat 队列配置。 */
+function normalize_queue(value: PluginJsonValue | undefined): ChatPluginPublicQueueConfig {
+  if (value === undefined) return {};
+  const queue = as_record(value, "Chat queue");
+  return {
+    ...read_integer(queue, "max_concurrency", 1, 32),
+    ...read_integer(queue, "merge_debounce_ms", 0, 60000),
+    ...read_integer(queue, "merge_max_wait_ms", 0, 120000),
+  };
+}
+
+/** 校验并规范化一个 Chat Channel。 */
+function normalize_channel(
+  value: PluginJsonValue,
+  current_channels: ChatPluginChannelConfig[],
+): ChatPluginChannelConfig {
+  const channel = as_record(value, "Chat Channel");
+  const id = read_required_string(channel, "id");
+  const name = read_required_string(channel, "name");
+  const type = read_required_string(channel, "type");
+  const current = current_channels.find((item) => item.id === id && item.type === type);
+  if (type === "telegram") {
+    const bot_token = read_optional_string(channel, "bot_token")
+      || (current?.type === "telegram" ? current.bot_token : "");
+    if (!bot_token) throw new Error(`Telegram Bot Token is required: ${id}`);
+    return { id, type, name, bot_token };
+  }
+  if (type === "feishu") {
+    const app_id = read_required_string(channel, "app_id");
+    const app_secret = read_optional_string(channel, "app_secret")
+      || (current?.type === "feishu" ? current.app_secret : "");
+    if (!app_secret) throw new Error(`Feishu App Secret is required: ${id}`);
+    const domain = read_optional_string(channel, "domain");
+    return { id, type, name, app_id, app_secret, ...(domain ? { domain } : {}) };
+  }
+  if (type === "qq") {
+    const app_id = read_required_string(channel, "app_id");
+    const app_secret = read_optional_string(channel, "app_secret")
+      || (current?.type === "qq" ? current.app_secret : "");
+    if (!app_secret) throw new Error(`QQ App Secret is required: ${id}`);
+    return { id, type, name, app_id, app_secret, sandbox: channel.sandbox === true };
+  }
+  throw new Error(`Unsupported Chat Channel type: ${type}`);
+}
+
+/** 读取一个受范围约束的可选整数字段。 */
+function read_integer(
+  source: PluginJsonObject,
+  key: string,
+  minimum: number,
+  maximum: number,
+): Partial<Record<string, number>> {
+  const value = source[key];
+  if (value === undefined || value === null || value === "") return {};
+  if (typeof value !== "number" || !Number.isInteger(value) || value < minimum || value > maximum) {
+    throw new Error(`Invalid Chat Profile field: ${key}`);
+  }
+  return { [key]: value };
+}
+
+/** 要求一个值是 JSON object。 */
+function as_record(value: PluginJsonValue | undefined, label: string): PluginJsonObject {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`${label} must be an object`);
+  }
+  return value;
+}
+
+/** 读取并规范化必填字符串。 */
+function read_required_string(source: PluginJsonObject, key: string): string {
+  const value = read_optional_string(source, key);
+  if (!value) throw new Error(`Chat Profile field is required: ${key}`);
+  return value;
+}
+
+/** 读取并规范化可选字符串。 */
+function read_optional_string(source: PluginJsonObject, key: string): string {
+  const value = source[key];
+  return typeof value === "string" ? value.trim() : "";
+}

package/src/chat/renderer/ChatPluginRenderer.tsx

@@ -0,0 +1,149 @@
+/** Chat Plugin 使用宿主 UI Components 的唯一 React Mainview。 */
+
+import { useCallback, useEffect, useState } from "react";
+import type { PluginJsonValue } from "@downcity/plugin";
+import { define_plugin_renderer } from "@downcity/plugin/react";
+import type {
+  ChatPluginPublicChannelConfig,
+  ChatPluginPublicProfile,
+  ChatPluginPublicQueueConfig,
+} from "@/chat/types/ChatPluginProfile.js";
+import type { ChatPluginChannelEditorProps } from "@/chat/types/ChatPluginRenderer.js";
+
+const channel_types: readonly ChatPluginPublicChannelConfig["type"][] = ["telegram", "feishu", "qq"];
+
+/** Chat Plugin 唯一 Mainview 组件。 */
+export const CHAT_PLUGIN_RENDERER = define_plugin_renderer(function ChatPluginRenderer({ plugin, ui }) {
+  const { Button, Callout, EmptyState, Group, Input, LoadingState, Page, Row, Section, Select, Stack, Switch, Toolbar } = ui.components;
+  const [profile, set_profile] = useState<ChatPluginPublicProfile>();
+  const [loading, set_loading] = useState(true);
+  const [saving, set_saving] = useState(false);
+  const [error, set_error] = useState("");
+
+  const load = useCallback(async () => {
+    set_loading(true);
+    set_error("");
+    try {
+      set_profile(await plugin.invoke("profile.read") as unknown as ChatPluginPublicProfile);
+    } catch (reason) {
+      set_error(to_error_message(reason));
+    } finally {
+      set_loading(false);
+    }
+  }, [plugin]);
+
+  useEffect(() => { void load(); }, [load]);
+
+  const save = async () => {
+    if (!profile) return;
+    set_saving(true);
+    set_error("");
+    try {
+      const saved = await plugin.invoke("profile.save", profile as unknown as PluginJsonValue);
+      set_profile(saved as unknown as ChatPluginPublicProfile);
+      ui.toast({ type: "success", message: "Chat Profile 已保存" });
+    } catch (reason) {
+      const message = to_error_message(reason);
+      set_error(message);
+      ui.toast({ type: "error", message });
+    } finally {
+      set_saving(false);
+    }
+  };
+
+  const update_queue = (key: keyof ChatPluginPublicQueueConfig, value: string) => {
+    set_profile((current) => current ? {
+      ...current,
+      queue: {
+        ...current.queue,
+        [key]: value === "" ? undefined : Number(value),
+      },
+    } : current);
+  };
+
+  const add_channel = () => {
+    if (!profile) return;
+    const used_types = new Set(profile.channels.map((channel) => channel.type));
+    const type = channel_types.find((item) => !used_types.has(item));
+    if (!type) {
+      ui.toast({ type: "info", message: "每种 Channel 类型只能配置一次" });
+      return;
+    }
+    set_profile((current) => current ? {
+      ...current,
+      channels: [...current.channels, { id: "", name: "", type, secret_configured: false }],
+    } : current);
+  };
+
+  if (loading && !profile) return <LoadingState label="正在读取 Chat Profile…" />;
+
+  return <Page>
+    <Toolbar
+      actions={<Button variant="primary" disabled={!profile || saving} on_click={() => void save()}>{saving ? "保存中…" : "保存"}</Button>}
+    />
+    {error ? <Callout tone="danger">{error}</Callout> : null}
+    <Section title="Queue" description="控制入站消息的并发与合并等待。" surface={false}>
+      <Group>
+        <Row label="Maximum concurrency" trailing={<Input type="number" value={number_value(profile?.queue.max_concurrency)} minimum={1} maximum={32} placeholder="4" on_value_change={(value) => update_queue("max_concurrency", value)} />} />
+        <Row label="Merge debounce" description="连续消息停止到达后等待的毫秒数。" trailing={<Input type="number" value={number_value(profile?.queue.merge_debounce_ms)} minimum={0} maximum={60000} on_value_change={(value) => update_queue("merge_debounce_ms", value)} />} />
+        <Row label="Maximum merge wait" description="一组消息允许等待合并的最大毫秒数。" trailing={<Input type="number" value={number_value(profile?.queue.merge_max_wait_ms)} minimum={0} maximum={120000} on_value_change={(value) => update_queue("merge_max_wait_ms", value)} />} />
+      </Group>
+    </Section>
+    <Section title="Channels" description="同一种 Channel 类型在一个 Profile 中只能出现一次。" action={<Button on_click={add_channel}>添加 Channel</Button>} surface={false}>
+      {!profile?.channels.length ? <EmptyState title="还没有消息渠道" description="添加 Telegram、Feishu 或 QQ Channel。" action={<Button variant="primary" on_click={add_channel}>添加 Channel</Button>} size="compact" />
+        : <Stack>{profile.channels.map((channel, index) => <ChannelEditor
+          key={`${channel.type}:${index}`}
+          channel={channel}
+          used_types={new Set(profile.channels.filter((_item, item_index) => item_index !== index).map((item) => item.type))}
+          components={{ Button, Group, Input, Row, Select, Switch }}
+          update={(next) => set_profile((current) => current ? { ...current, channels: current.channels.map((item, item_index) => item_index === index ? next : item) } : current)}
+          remove={() => set_profile((current) => current ? { ...current, channels: current.channels.filter((_item, item_index) => item_index !== index) } : current)}
+        />)}</Stack>}
+    </Section>
+  </Page>;
+});
+
+/** 编辑一个具体 Channel，凭据输入只保存在当前草稿。 */
+function ChannelEditor({ channel, used_types, components, update, remove }: ChatPluginChannelEditorProps) {
+  const { Button, Group, Input, Row, Select, Switch } = components;
+  const set_string = (key: "id" | "name" | "bot_token" | "app_id" | "app_secret" | "domain", value: string) => update({ ...channel, [key]: value });
+  const type_options = channel_types.map((type) => ({ value: type, label: channel_type_label(type), disabled: used_types.has(type) }));
+  return <Group label={channel.name || channel.id || channel_type_label(channel.type)} action={<Button variant="destructive" on_click={remove}>删除</Button>}>
+    <Row label="Type" trailing={<Select value={channel.type} options={type_options} on_value_change={(value) => update({ id: channel.id, name: channel.name, type: value as ChatPluginPublicChannelConfig["type"], secret_configured: false })} />} />
+    <Row label="Channel ID" trailing={<Input value={channel.id} on_value_change={(value) => set_string("id", value)} />} />
+    <Row label="Name" trailing={<Input value={channel.name} on_value_change={(value) => set_string("name", value)} />} />
+    {channel.type === "telegram" ? <Row label="Bot Token" description={secret_description(channel)} trailing={<Input type="password" value={channel.bot_token ?? ""} placeholder={secret_placeholder(channel)} on_value_change={(value) => set_string("bot_token", value)} />} /> : <>
+      <Row label="App ID" trailing={<Input value={channel.app_id ?? ""} on_value_change={(value) => set_string("app_id", value)} />} />
+      <Row label="App Secret" description={secret_description(channel)} trailing={<Input type="password" value={channel.app_secret ?? ""} placeholder={secret_placeholder(channel)} on_value_change={(value) => set_string("app_secret", value)} />} />
+      {channel.type === "feishu" ? <Row label="API Domain" trailing={<Input value={channel.domain ?? ""} placeholder="https://open.feishu.cn" on_value_change={(value) => set_string("domain", value)} />} /> : null}
+      {channel.type === "qq" ? <Row label="Sandbox" trailing={<Switch checked={channel.sandbox === true} on_checked_change={(sandbox) => update({ ...channel, sandbox })} aria_label="QQ Sandbox" />} /> : null}
+    </>}
+  </Group>;
+}
+
+/** 返回 Channel 类型的用户可见名称。 */
+function channel_type_label(type: ChatPluginPublicChannelConfig["type"]): string {
+  if (type === "telegram") return "Telegram";
+  if (type === "feishu") return "Feishu / Lark";
+  return "QQ";
+}
+
+/** 把可选数字转换为受控 Input 字符串。 */
+function number_value(value: number | undefined): string {
+  return value === undefined ? "" : String(value);
+}
+
+/** 已配置凭据的安全说明。 */
+function secret_description(channel: ChatPluginPublicChannelConfig): string | undefined {
+  return channel.secret_configured ? "已有凭据不会显示；留空会保留当前值。" : undefined;
+}
+
+/** 已配置凭据的安全占位符。 */
+function secret_placeholder(channel: ChatPluginPublicChannelConfig): string | undefined {
+  return channel.secret_configured ? "已配置；留空保持" : undefined;
+}
+
+/** 把未知失败转换为用户可见消息。 */
+function to_error_message(reason: unknown): string {
+  return reason instanceof Error ? reason.message : String(reason);
+}