@downcity/plugins 1.0.4

package/src/chat/accounts/ChannelAccountManager.ts

@@ -0,0 +1,314 @@
+/**
+ * Chat channel account 管理器。
+ *
+ * 关键点（中文）
+ * - 统一封装 agent 运行时下 chat channel account 的 CRUD 与探测。
+ * - 账号凭据只在写入路径接收明文；列表与读取路径返回脱敏结果。
+ * - city / vibecape 等上层产品都应直接复用这个实现，而不是各自维护副本。
+ */
+
+import crypto from "node:crypto";
+import type { StoredChannelAccountChannel } from "@downcity/agent/internal/types/runtime/host/Store.js";
+import { resolveChatChannelBotInfo } from "@/chat/channels/BotInfoProvider.js";
+import {
+  getStoredChannelAccountSync,
+  listStoredChannelAccountsSync,
+  normalizeChannelAccountChannel,
+  removeStoredChannelAccount,
+  upsertStoredChannelAccount,
+} from "./Store.js";
+import type {
+  ChatChannelAccountCreateInput,
+  ChatChannelAccountListItem,
+  ChatChannelAccountListResult,
+  ChatChannelAccountProbeResult,
+  ChatChannelAccountUpsertInput,
+} from "@/chat/types/ChannelAccount.js";
+import type { StoredChannelAccount } from "@downcity/agent/internal/types/runtime/host/Store.js";
+
+const SUPPORTED_CHANNELS: readonly StoredChannelAccountChannel[] = [
+  "telegram",
+  "feishu",
+  "qq",
+];
+
+function maskSecret(value: string | undefined): string {
+  const raw = String(value || "").trim();
+  if (!raw) return "";
+  if (raw.length <= 8) return "***";
+  return `${raw.slice(0, 4)}***${raw.slice(-4)}`;
+}
+
+function assertChannel(input: string): StoredChannelAccountChannel {
+  const channel = String(input || "").trim().toLowerCase() as StoredChannelAccountChannel;
+  if (!SUPPORTED_CHANNELS.includes(channel)) {
+    throw new Error(
+      `Unsupported channel: ${input}. Supported: ${SUPPORTED_CHANNELS.join(", ")}`,
+    );
+  }
+  return channel;
+}
+
+function normalizeOptionalText(value: unknown): string | undefined {
+  const text = String(value || "").trim();
+  return text || undefined;
+}
+
+function normalizeChannelAccountIdToken(value: string): string {
+  const token = String(value || "")
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9_-]+/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^-+/, "")
+    .replace(/-+$/, "");
+  return token || "bot";
+}
+
+function pickFirstNonEmpty(inputs: unknown[]): string {
+  for (const input of inputs) {
+    const text = String(input || "").trim();
+    if (text) return text;
+  }
+  return "";
+}
+
+/**
+ * ChatChannelAccountManager。
+ */
+export class ChatChannelAccountManager {
+  constructor() {}
+
+  /**
+   * 生成唯一 channel account id。
+   *
+   * 关键点（中文）
+   * - 账号 id 统一由系统生成，避免用户手填导致冲突或命名不一致。
+   * - 若碰撞则自动追加随机后缀重试。
+   */
+  private async generateUniqueAccountId(params: {
+    channel: StoredChannelAccountChannel;
+    seed?: string;
+  }): Promise<string> {
+    const seed = normalizeChannelAccountIdToken(params.seed || "");
+    const prefix = `${params.channel}-${seed}`.slice(0, 36);
+    for (let index = 0; index < 8; index += 1) {
+      const suffix = crypto.randomBytes(3).toString("hex");
+      const candidate = `${prefix}-${suffix}`.slice(0, 64);
+      const existing = getStoredChannelAccountSync(candidate);
+      if (!existing) return candidate;
+    }
+    return `${params.channel}-${Date.now().toString(36)}`;
+  }
+
+  /**
+   * 探测 bot 凭据并返回自动填充信息。
+   */
+  async probe(input: {
+    channel: string;
+    botToken?: string;
+    appId?: string;
+    appSecret?: string;
+    domain?: string;
+    sandbox?: boolean;
+  }): Promise<ChatChannelAccountProbeResult> {
+    const channel = assertChannel(input.channel);
+    const botInfo = await resolveChatChannelBotInfo({
+      channel,
+      credentials: {
+        botToken: normalizeOptionalText(input.botToken),
+        appId: normalizeOptionalText(input.appId),
+        appSecret: normalizeOptionalText(input.appSecret),
+        domain: normalizeOptionalText(input.domain),
+        sandbox: input.sandbox === true,
+      },
+    });
+    const accountId = await this.generateUniqueAccountId({
+      channel,
+      seed: pickFirstNonEmpty([
+        botInfo.idSeed,
+        botInfo.botUserId,
+        botInfo.identity,
+        botInfo.name,
+        "bot",
+      ]),
+    });
+
+    return {
+      channel,
+      accountId,
+      name: botInfo.name,
+      identity: botInfo.identity,
+      owner: botInfo.owner,
+      creator: botInfo.creator,
+      botUserId: botInfo.botUserId,
+      message: botInfo.message,
+    };
+  }
+
+  /**
+   * 使用凭据创建账号。
+   *
+   * 关键点（中文）
+   * - 默认先尝试探测 bot 信息，成功时自动填充名称与身份。
+   * - 探测失败但用户提供了名称时，仍允许先保存，便于后续排障。
+   */
+  async create(input: ChatChannelAccountCreateInput): Promise<{
+    id: string;
+    probed: boolean;
+    message?: string;
+  }> {
+    const channel = assertChannel(input.channel);
+    let probeResult: ChatChannelAccountProbeResult | null = null;
+    if (input.probe !== false) {
+      try {
+        probeResult = await this.probe({
+          channel,
+          botToken: input.botToken,
+          appId: input.appId,
+          appSecret: input.appSecret,
+          domain: input.domain,
+          sandbox: input.sandbox,
+        });
+      } catch (error) {
+        if (!normalizeOptionalText(input.name)) {
+          throw error;
+        }
+      }
+    }
+
+    const id =
+      probeResult?.accountId ||
+      (await this.generateUniqueAccountId({
+        channel,
+        seed: pickFirstNonEmpty([input.name, input.appId, "bot"]),
+      }));
+    const name = normalizeOptionalText(input.name) || probeResult?.name || `${channel} bot`;
+
+    await this.upsert({
+      id,
+      channel,
+      name,
+      identity: probeResult?.identity,
+      owner: probeResult?.owner,
+      creator: probeResult?.creator,
+      botToken: input.botToken,
+      appId: input.appId,
+      appSecret: input.appSecret,
+      domain: input.domain,
+      sandbox: input.sandbox,
+    });
+
+    return {
+      id,
+      probed: Boolean(probeResult),
+      message: probeResult?.message,
+    };
+  }
+
+  /**
+   * 列出账户池（脱敏）。
+   */
+  async list(): Promise<ChatChannelAccountListResult> {
+    return {
+      items: listStoredChannelAccountsSync().map((account) =>
+        toChannelAccountListItem(account),
+      ),
+    };
+  }
+
+  /**
+   * 新增或更新账号。
+   */
+  async upsert(input: ChatChannelAccountUpsertInput): Promise<{ id: string }> {
+    const id = String(input.id || "").trim();
+    if (!id) throw new Error("channel account id cannot be empty");
+    const name = String(input.name || "").trim();
+    if (!name) throw new Error("channel account name cannot be empty");
+
+    const channel = normalizeChannelAccountChannel(input.channel);
+
+    if (input.botToken !== undefined && input.clearBotToken === true) {
+      throw new Error("botToken and clearBotToken cannot be used together");
+    }
+    if (input.appId !== undefined && input.clearAppId === true) {
+      throw new Error("appId and clearAppId cannot be used together");
+    }
+    if (input.appSecret !== undefined && input.clearAppSecret === true) {
+      throw new Error("appSecret and clearAppSecret cannot be used together");
+    }
+
+    const current = getStoredChannelAccountSync(id);
+    const nextBotToken = input.clearBotToken
+      ? undefined
+      : input.botToken !== undefined
+        ? normalizeOptionalText(input.botToken)
+        : current?.botToken;
+    const nextAppId = input.clearAppId
+      ? undefined
+      : input.appId !== undefined
+        ? normalizeOptionalText(input.appId)
+        : current?.appId;
+    const nextAppSecret = input.clearAppSecret
+      ? undefined
+      : input.appSecret !== undefined
+        ? normalizeOptionalText(input.appSecret)
+        : current?.appSecret;
+    const nextIdentity = Object.prototype.hasOwnProperty.call(input, "identity")
+      ? normalizeOptionalText(input.identity)
+      : current?.identity;
+    const nextOwner = Object.prototype.hasOwnProperty.call(input, "owner")
+      ? normalizeOptionalText(input.owner)
+      : current?.owner;
+    const nextCreator = Object.prototype.hasOwnProperty.call(input, "creator")
+      ? normalizeOptionalText(input.creator)
+      : current?.creator;
+
+    await upsertStoredChannelAccount({
+      id,
+      channel,
+      name,
+      identity: nextIdentity,
+      owner: nextOwner,
+      creator: nextCreator,
+      botToken: nextBotToken,
+      appId: nextAppId,
+      appSecret: nextAppSecret,
+      domain: normalizeOptionalText(input.domain),
+      sandbox: input.sandbox === true,
+    });
+    return { id };
+  }
+
+  /**
+   * 删除账号。
+   */
+  async remove(idInput: string): Promise<void> {
+    const id = String(idInput || "").trim();
+    if (!id) throw new Error("channel account id cannot be empty");
+    await removeStoredChannelAccount(id);
+  }
+}
+
+function toChannelAccountListItem(
+  account: StoredChannelAccount,
+): ChatChannelAccountListItem {
+  return {
+    id: account.id,
+    channel: account.channel,
+    name: account.name,
+    identity: account.identity,
+    owner: account.owner,
+    creator: account.creator,
+    domain: account.domain,
+    sandbox: account.sandbox === true,
+    hasBotToken: !!String(account.botToken || "").trim(),
+    hasAppId: !!String(account.appId || "").trim(),
+    hasAppSecret: !!String(account.appSecret || "").trim(),
+    botTokenMasked: maskSecret(account.botToken),
+    appIdMasked: maskSecret(account.appId),
+    appSecretMasked: maskSecret(account.appSecret),
+    createdAt: account.createdAt,
+    updatedAt: account.updatedAt,
+  };
+}

package/src/chat/accounts/Crypto.ts

@@ -0,0 +1,83 @@
+/**
+ * Channel account 默认存储加密工具。
+ *
+ * 职责说明（中文）
+ * - 负责默认 channel account 存储中的敏感字段加解密。
+ * - 默认复用平台级 `model-db.key`，保证和现有 `~/.downcity/downcity.db` 数据兼容。
+ *
+ * 边界说明（中文）
+ * - 这里只处理“字符串 <-> 密文”的转换，不负责数据库读写。
+ * - 加密算法与密钥文件路径属于默认实现细节，上层不直接感知。
+ */
+
+import crypto from "node:crypto";
+import fs from "fs-extra";
+import path from "node:path";
+import { getPlatformStoreKeyPath } from "@downcity/agent/internal/config/PlatformPaths.js";
+
+const ENCRYPTION_ALGO = "aes-256-gcm";
+
+let cachedKey: Buffer | null = null;
+
+function resolveKeyFilePathSync(): string {
+  const keyPath = getPlatformStoreKeyPath();
+  fs.ensureDirSync(path.dirname(keyPath));
+  return keyPath;
+}
+
+function loadOrCreateKeySync(): Buffer {
+  if (cachedKey) return cachedKey;
+
+  const envKey = String(process.env.DC_MODEL_DB_KEY || "").trim();
+  if (envKey) {
+    cachedKey = crypto.createHash("sha256").update(envKey, "utf8").digest();
+    return cachedKey;
+  }
+
+  const keyPath = resolveKeyFilePathSync();
+  if (fs.existsSync(keyPath)) {
+    const raw = String(fs.readFileSync(keyPath, "utf8")).trim();
+    if (raw) {
+      const parsed = Buffer.from(raw, "base64");
+      if (parsed.length === 32) {
+        cachedKey = parsed;
+        return cachedKey;
+      }
+    }
+  }
+
+  const next = crypto.randomBytes(32);
+  fs.writeFileSync(keyPath, next.toString("base64"), { mode: 0o600 });
+  cachedKey = next;
+  return cachedKey;
+}
+
+/**
+ * 同步加密字符串。
+ */
+export function encryptTextSync(plainText: string): string {
+  const key = loadOrCreateKeySync();
+  const iv = crypto.randomBytes(12);
+  const cipher = crypto.createCipheriv(ENCRYPTION_ALGO, key, iv);
+  const encrypted = Buffer.concat([cipher.update(plainText, "utf8"), cipher.final()]);
+  const tag = cipher.getAuthTag();
+  return Buffer.concat([iv, tag, encrypted]).toString("base64");
+}
+
+/**
+ * 同步解密字符串。
+ */
+export function decryptTextSync(cipherText: string): string {
+  const key = loadOrCreateKeySync();
+  const packed = Buffer.from(cipherText, "base64");
+  if (packed.length < 28) {
+    throw new Error("Invalid encrypted payload");
+  }
+  const iv = packed.subarray(0, 12);
+  const tag = packed.subarray(12, 28);
+  const body = packed.subarray(28);
+  const decipher = crypto.createDecipheriv(ENCRYPTION_ALGO, key, iv);
+  decipher.setAuthTag(tag);
+  const plain = Buffer.concat([decipher.update(body), decipher.final()]);
+  return plain.toString("utf8");
+}

package/src/chat/accounts/Store.ts

@@ -0,0 +1,287 @@
+/**
+ * Channel account 默认存储实现。
+ *
+ * 职责说明（中文）
+ * - 提供 `chat` plugin 默认使用的全局 channel account 读写能力。
+ * - 默认直接操作 `~/.downcity/downcity.db` 里的 `channel_accounts` 表。
+ * - 对 `city` 而言，这里也是统一的默认账号池实现来源。
+ *
+ * 边界说明（中文）
+ * - 这里只负责 channel account 这一个表，不扩展成通用平台数据库门面。
+ * - 模型池、env、其他平台级配置仍由各自模块独立管理。
+ */
+
+import Database from "better-sqlite3";
+import fs from "fs-extra";
+import path from "node:path";
+import { getPlatformStoreDbPath } from "@downcity/agent/internal/config/PlatformPaths.js";
+import { decryptTextSync, encryptTextSync } from "./Crypto.js";
+import type {
+  StoredChannelAccount,
+  StoredChannelAccountChannel,
+  UpsertChannelAccountInput,
+} from "@downcity/agent/internal/types/runtime/host/Store.js";
+
+function nowIso(): string {
+  return new Date().toISOString();
+}
+
+function normalizeNonEmptyText(value: string, fieldName: string): string {
+  const normalized = String(value || "").trim();
+  if (!normalized) {
+    throw new Error(`${fieldName} cannot be empty`);
+  }
+  return normalized;
+}
+
+function optionalTrimmedText(value: string | undefined): string | undefined {
+  const normalized = String(value || "").trim();
+  return normalized || undefined;
+}
+
+/**
+ * 规范化 channel 类型。
+ */
+export function normalizeChannelAccountChannel(
+  input: string,
+): StoredChannelAccountChannel {
+  const channel = String(input || "").trim().toLowerCase();
+  if (channel === "telegram" || channel === "feishu" || channel === "qq") {
+    return channel;
+  }
+  throw new Error(`Unsupported channel account type: ${input}`);
+}
+
+function ensureChannelAccountSchema(database: Database.Database): void {
+  database.exec(`
+    CREATE TABLE IF NOT EXISTS channel_accounts (
+      id TEXT PRIMARY KEY NOT NULL,
+      channel TEXT NOT NULL,
+      name TEXT NOT NULL,
+      identity TEXT,
+      owner TEXT,
+      creator TEXT,
+      bot_token_encrypted TEXT,
+      app_id_encrypted TEXT,
+      app_secret_encrypted TEXT,
+      domain TEXT,
+      sandbox INTEGER,
+      created_at TEXT NOT NULL,
+      updated_at TEXT NOT NULL
+    );
+  `);
+  database.exec(`
+    CREATE INDEX IF NOT EXISTS channel_accounts_channel_idx
+    ON channel_accounts(channel);
+  `);
+
+  const rows = database
+    .prepare("PRAGMA table_info(channel_accounts)")
+    .all() as Array<{ name?: unknown }>;
+  const columns = new Set(
+    rows.map((row) => String(row.name || "").trim()).filter(Boolean),
+  );
+  if (!columns.has("owner")) {
+    database.exec("ALTER TABLE channel_accounts ADD COLUMN owner TEXT;");
+  }
+  if (!columns.has("creator")) {
+    database.exec("ALTER TABLE channel_accounts ADD COLUMN creator TEXT;");
+  }
+}
+
+function withChannelAccountDb<T>(callback: (database: Database.Database) => T): T {
+  const dbPath = getPlatformStoreDbPath();
+  fs.ensureDirSync(path.dirname(dbPath));
+  const database = new Database(dbPath);
+  try {
+    database.pragma("journal_mode = WAL");
+    ensureChannelAccountSchema(database);
+    return callback(database);
+  } finally {
+    database.close();
+  }
+}
+
+function buildChannelAccountFromRow(
+  row: Record<string, unknown>,
+): StoredChannelAccount | null {
+  const id = String(row.id || "").trim();
+  if (!id) return null;
+  const botTokenEncrypted =
+    typeof row.bot_token_encrypted === "string" ? row.bot_token_encrypted : "";
+  const appIdEncrypted =
+    typeof row.app_id_encrypted === "string" ? row.app_id_encrypted : "";
+  const appSecretEncrypted =
+    typeof row.app_secret_encrypted === "string" ? row.app_secret_encrypted : "";
+
+  return {
+    id,
+    channel: normalizeChannelAccountChannel(String(row.channel || "")),
+    name: String(row.name || "").trim() || id,
+    identity: optionalTrimmedText(String(row.identity || "")),
+    owner: optionalTrimmedText(String(row.owner || "")),
+    creator: optionalTrimmedText(String(row.creator || "")),
+    botToken: optionalTrimmedText(
+      botTokenEncrypted ? decryptTextSync(botTokenEncrypted) : undefined,
+    ),
+    appId: optionalTrimmedText(
+      appIdEncrypted ? decryptTextSync(appIdEncrypted) : undefined,
+    ),
+    appSecret: optionalTrimmedText(
+      appSecretEncrypted ? decryptTextSync(appSecretEncrypted) : undefined,
+    ),
+    domain: optionalTrimmedText(String(row.domain || "")),
+    sandbox: Number(row.sandbox || 0) === 1,
+    createdAt: String(row.created_at || ""),
+    updatedAt: String(row.updated_at || ""),
+  };
+}
+
+/**
+ * 同步列出全部 channel account。
+ */
+export function listStoredChannelAccountsSync(
+  channelInput?: string,
+): StoredChannelAccount[] {
+  return withChannelAccountDb((database) => {
+    const maybeChannel = optionalTrimmedText(channelInput);
+    const rows = maybeChannel
+      ? database.prepare(
+          `
+          SELECT
+            id, channel, name, identity, owner, creator,
+            bot_token_encrypted, app_id_encrypted, app_secret_encrypted,
+            domain, sandbox, created_at, updated_at
+          FROM channel_accounts
+          WHERE channel = ?
+          ORDER BY name ASC, id ASC;
+          `,
+        ).all(maybeChannel)
+      : database.prepare(
+          `
+          SELECT
+            id, channel, name, identity, owner, creator,
+            bot_token_encrypted, app_id_encrypted, app_secret_encrypted,
+            domain, sandbox, created_at, updated_at
+          FROM channel_accounts
+          ORDER BY channel ASC, name ASC, id ASC;
+          `,
+        ).all();
+
+    const out: StoredChannelAccount[] = [];
+    for (const row of rows as Array<Record<string, unknown>>) {
+      const item = buildChannelAccountFromRow(row);
+      if (item) out.push(item);
+    }
+    return out;
+  });
+}
+
+/**
+ * 同步按 ID 读取单个 channel account。
+ */
+export function getStoredChannelAccountSync(
+  accountIdInput: string,
+): StoredChannelAccount | null {
+  const accountId = normalizeNonEmptyText(accountIdInput, "channel account id");
+  return withChannelAccountDb((database) => {
+    const row = database.prepare(
+      `
+      SELECT
+        id, channel, name, identity, owner, creator,
+        bot_token_encrypted, app_id_encrypted, app_secret_encrypted,
+        domain, sandbox, created_at, updated_at
+      FROM channel_accounts
+      WHERE id = ?
+      LIMIT 1;
+      `,
+    ).get(accountId) as Record<string, unknown> | undefined;
+    return row ? buildChannelAccountFromRow(row) : null;
+  });
+}
+
+/**
+ * 新增或更新 channel account。
+ *
+ * 关键点（中文）
+ * - 这里保留和现有平台库一致的落盘结构，避免默认实现切换后出现数据断层。
+ * - 未显式传入的敏感字段会保留旧值，便于 CLI 局部更新。
+ */
+export async function upsertStoredChannelAccount(
+  input: UpsertChannelAccountInput,
+): Promise<void> {
+  const id = normalizeNonEmptyText(input.id, "channel account id");
+  const channel = normalizeChannelAccountChannel(input.channel);
+  const name = normalizeNonEmptyText(input.name, "channel account name");
+  const existing = getStoredChannelAccountSync(id);
+  const createdAt = existing?.createdAt || nowIso();
+  const updatedAt = nowIso();
+
+  const nextBotToken =
+    Object.prototype.hasOwnProperty.call(input, "botToken")
+      ? optionalTrimmedText(input.botToken)
+      : existing?.botToken;
+  const nextAppId =
+    Object.prototype.hasOwnProperty.call(input, "appId")
+      ? optionalTrimmedText(input.appId)
+      : existing?.appId;
+  const nextAppSecret =
+    Object.prototype.hasOwnProperty.call(input, "appSecret")
+      ? optionalTrimmedText(input.appSecret)
+      : existing?.appSecret;
+
+  const botTokenEncrypted = nextBotToken ? encryptTextSync(nextBotToken) : null;
+  const appIdEncrypted = nextAppId ? encryptTextSync(nextAppId) : null;
+  const appSecretEncrypted = nextAppSecret ? encryptTextSync(nextAppSecret) : null;
+
+  withChannelAccountDb((database) => {
+    database.prepare(
+      `
+      INSERT INTO channel_accounts (
+        id, channel, name, identity, owner, creator,
+        bot_token_encrypted, app_id_encrypted, app_secret_encrypted,
+        domain, sandbox, created_at, updated_at
+      )
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT(id) DO UPDATE SET
+        channel = excluded.channel,
+        name = excluded.name,
+        identity = excluded.identity,
+        owner = excluded.owner,
+        creator = excluded.creator,
+        bot_token_encrypted = excluded.bot_token_encrypted,
+        app_id_encrypted = excluded.app_id_encrypted,
+        app_secret_encrypted = excluded.app_secret_encrypted,
+        domain = excluded.domain,
+        sandbox = excluded.sandbox,
+        updated_at = excluded.updated_at;
+      `,
+    ).run(
+      id,
+      channel,
+      name,
+      optionalTrimmedText(input.identity) || null,
+      optionalTrimmedText(input.owner) || null,
+      optionalTrimmedText(input.creator) || null,
+      botTokenEncrypted,
+      appIdEncrypted,
+      appSecretEncrypted,
+      optionalTrimmedText(input.domain) || null,
+      input.sandbox === true ? 1 : 0,
+      createdAt,
+      updatedAt,
+    );
+  });
+}
+
+/**
+ * 删除单个 channel account。
+ */
+export async function removeStoredChannelAccount(
+  accountIdInput: string,
+): Promise<void> {
+  const accountId = normalizeNonEmptyText(accountIdInput, "channel account id");
+  withChannelAccountDb((database) => {
+    database.prepare("DELETE FROM channel_accounts WHERE id = ?;").run(accountId);
+  });
+}