@downcity/plugins 1.0.215 → 1.0.233

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

@@ -9,7 +9,7 @@
 
 import path from "path";
 import type { Logger } from "@downcity/agent";
-import type { AgentContext } from "@downcity/agent";
+import type { PluginContext } from "@downcity/agent";
 import type { JsonObject } from "@downcity/agent";
 import type {
   IncomingChatAccessParams,
@@ -24,7 +24,7 @@ import {
   augmentChatInboundInput,
   buildChatInboundText,
 } from "@/chat/runtime/InboundAugment.js";
-import { renderChatMessageFileTag } from "@downcity/agent";
+import { render_chat_message_file_tag } from "@downcity/agent";
 import { extractTelegramReplyContext } from "./ReplyContext.js";
 import {
   getActorName,
@@ -58,7 +58,7 @@ export interface TelegramMessagePlatform {
    */
   sendInboundAckReaction(params: {
     chatId: string;
-    messageId?: number;
+    message_id?: number;
     emoji: string;
   }): Promise<void>;
   /**
@@ -72,8 +72,8 @@ export interface TelegramMessagePlatform {
  */
 export type TelegramMessageAuditWriter = (params: {
   chatId: string;
-  messageId?: string;
-  userId?: string;
+  message_id?: string;
+  user_id?: string;
   text: string;
   meta?: ChannelUserMessageMeta;
 }) => Promise<void>;
@@ -86,7 +86,7 @@ export type TelegramMessageExecutor = (params: {
   instructions: string;
   from?: TelegramUser;
   chatTitle?: string;
-  messageId?: string;
+  message_id?: string;
   chatType?: NonNullable<TelegramUpdate["message"]>["chat"]["type"];
   messageThreadId?: number;
   receivedAt?: string;
@@ -110,7 +110,7 @@ export interface TelegramMessageHandlerOptions {
   /**
    * 当前 agent context。
    */
-  context: AgentContext;
+  context: PluginContext;
   /**
    * 项目根目录。
    */
@@ -149,9 +149,9 @@ export interface TelegramMessageHandlerOptions {
    */
   enqueueAuditMessage: TelegramMessageAuditWriter;
   /**
-   * 按 chatKey 串行执行。
+   * 按 chat_key 串行执行。
    */
-  runInChat(chatKey: string, fn: () => Promise<void>): Promise<void>;
+  runInChat(chat_key: string, fn: () => Promise<void>): Promise<void>;
   /**
    * 命令处理。
    */
@@ -180,7 +180,7 @@ export async function handleTelegramMessage(
         : "";
   const entities = message.entities || message.caption_entities;
   const hasIncomingAttachment = hasTelegramIncomingAttachment(message);
-  const messageId =
+  const message_id =
     typeof message.message_id === "number" ? String(message.message_id) : undefined;
   const receivedAt =
     typeof message.date === "number" && Number.isFinite(message.date)
@@ -198,13 +198,13 @@ export async function handleTelegramMessage(
   const actorName = getActorName(from);
   const chatTitle = getTelegramChatTitle(message.chat);
   const isGroup = isTelegramGroupChat(message.chat.type);
-  const chatKey = buildTelegramChatKey(chatId, messageThreadId);
+  const chat_key = buildTelegramChatKey(chatId, messageThreadId);
 
   if (!actorId) {
-    options.logger.warn("Telegram 消息缺少发送者 userId，已忽略", {
+    options.logger.warn("Telegram 消息缺少发送者 user_id，已忽略", {
       chatId,
       chatType: message.chat.type,
-      messageId,
+      message_id,
       messageThreadId,
       hasFrom: !!from,
     });
@@ -215,7 +215,7 @@ export async function handleTelegramMessage(
     chatId,
     chatType: message.chat.type,
     chatTitle,
-    userId: actorId,
+    user_id: actorId,
     username: actorName,
   });
   if (!access_result.allowed) {
@@ -237,8 +237,8 @@ export async function handleTelegramMessage(
     if (!isGroup) return;
     await options.enqueueAuditMessage({
       chatId,
-      messageId,
-      userId: actorId,
+      message_id,
+      user_id: actorId,
       text: buildTelegramAuditText({ rawText, hasIncomingAttachment, message }),
       meta: {
         chatType: message.chat.type,
@@ -258,14 +258,14 @@ export async function handleTelegramMessage(
     options.logger.debug("Ignored bot-originated message", {
       chatId,
       chatType: message.chat.type,
-      messageId,
-      fromId: from?.id,
+      message_id,
+      from_id: from?.id,
       fromUsername: from?.username,
     });
     return;
   }
 
-  await options.runInChat(chatKey, async () => {
+  await options.runInChat(chat_key, async () => {
     options.logger.debug("Telegram message received", {
       chatId,
       chatType: message.chat.type,
@@ -273,9 +273,9 @@ export async function handleTelegramMessage(
       actorId,
       actorUsername: from?.username,
       actorName,
-      messageId,
+      message_id,
       messageThreadId,
-      chatKey,
+      chat_key,
       hasIncomingAttachment,
       textPreview: rawText.length > 240 ? `${rawText.slice(0, 240)}…` : rawText,
       entityTypes: (entities || []).map((entity) => entity.type),
@@ -290,15 +290,15 @@ export async function handleTelegramMessage(
 
     await options.platform.sendInboundAckReaction({
       chatId,
-      messageId: parseTelegramMessageId(messageId),
+      message_id: parseTelegramMessageId(message_id),
       emoji: options.inboundAckEmoji,
     });
 
     if (rawText.startsWith("/")) {
       await options.enqueueAuditMessage({
         chatId,
-        messageId,
-        userId: actorId,
+        message_id,
+        user_id: actorId,
         text: buildTelegramAuditText({ rawText, hasIncomingAttachment, message }),
         meta: {
           chatType: message.chat.type,
@@ -330,8 +330,8 @@ export async function handleTelegramMessage(
       options,
       message,
       chatId,
-      messageId,
-      chatKey,
+      message_id,
+      chat_key,
     });
     const replyContext = extractTelegramReplyContext(message);
 
@@ -344,12 +344,12 @@ export async function handleTelegramMessage(
               channel: "telegram",
               chatId,
               chatType: message.chat.type,
-              chatKey,
-              messageId,
+              chat_key,
+              message_id,
               rootPath: options.rootPath,
               attachmentText:
                 attachmentLines.length > 0 ? attachmentLines.join("\n") : undefined,
-              bodyText: cleaned ? cleaned.trim() : undefined,
+              body_text: cleaned ? cleaned.trim() : undefined,
               attachments: incomingAttachments.map((attachment) => ({
                 channel: "telegram" as const,
                 kind: attachment.type,
@@ -372,7 +372,7 @@ export async function handleTelegramMessage(
       instructions,
       from,
       chatTitle,
-      messageId,
+      message_id,
       chatType: message.chat.type,
       messageThreadId,
       receivedAt,
@@ -422,8 +422,8 @@ async function collectIncomingAttachments(params: {
   options: TelegramMessageHandlerOptions;
   message: TelegramUpdate["message"];
   chatId: string;
-  messageId?: string;
-  chatKey: string;
+  message_id?: string;
+  chat_key: string;
 }): Promise<{
   attachmentLines: string[];
   incomingAttachments: Array<{
@@ -447,7 +447,7 @@ async function collectIncomingAttachments(params: {
     for (const attachment of incomingAttachments) {
       const rel = path.relative(params.options.rootPath, attachment.path);
       attachmentLines.push(
-        renderChatMessageFileTag({
+        render_chat_message_file_tag({
           type: attachment.type,
           path: rel,
           ...(attachment.desc ? { caption: attachment.desc } : {}),
@@ -458,8 +458,8 @@ async function collectIncomingAttachments(params: {
     params.options.logger.warn("Failed to save incoming Telegram attachment(s)", {
       error: String(error),
       chatId: params.chatId,
-      messageId: params.messageId,
-      chatKey: params.chatKey,
+      message_id: params.message_id,
+      chat_key: params.chat_key,
     });
   }
 

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

@@ -50,8 +50,8 @@ export interface TelegramPendingUpdatePlatform {
  */
 export type TelegramPendingAuditWriter = (params: {
   chatId: string;
-  messageId?: string;
-  userId?: string;
+  message_id?: string;
+  user_id?: string;
   text: string;
   meta?: ChannelUserMessageMeta;
 }) => Promise<void>;
@@ -120,7 +120,7 @@ async function enqueuePendingMessage(params: {
     typeof message.message_thread_id === "number"
       ? message.message_thread_id
       : undefined;
-  const chatKey = buildTelegramChatKey(chatId, messageThreadId);
+  const chat_key = buildTelegramChatKey(chatId, messageThreadId);
   const from = message.from;
   const chatTitle = getTelegramChatTitle(message.chat);
   const botId = params.platform.getBotId();
@@ -147,14 +147,14 @@ async function enqueuePendingMessage(params: {
     !!message.audio ||
     !!message.video;
 
-  const messageId =
+  const message_id =
     typeof message.message_id === "number" ? String(message.message_id) : undefined;
   const actorId = from?.id ? String(from.id) : undefined;
 
   await params.enqueueAuditMessage({
     chatId,
-    messageId,
-    userId: actorId,
+    message_id,
+    user_id: actorId,
     text: buildTelegramAuditText({ rawText, hasIncomingAttachment, message }),
     meta: {
       kind: "pending",
@@ -165,7 +165,7 @@ async function enqueuePendingMessage(params: {
       messageThreadId,
       username: from?.username,
       fromIsBot,
-      chatKey,
+      chat_key,
     },
   });
 }
@@ -190,8 +190,8 @@ async function enqueuePendingCallbackQuery(params: {
       : undefined;
   await params.enqueueAuditMessage({
     chatId,
-    messageId: undefined,
-    userId: query.from?.id ? String(query.from.id) : undefined,
+    message_id: undefined,
+    user_id: query.from?.id ? String(query.from.id) : undefined,
     text: `[callback_query] ${String(query.data || "").slice(0, 1000)}`.trim(),
     meta: {
       kind: "pending",

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

@@ -7,7 +7,7 @@
  * - `TelegramBot` 只保留入站授权、命令分发、消息入队等业务编排。
  */
 
-import type { AgentContext } from "@downcity/agent";
+import type { PluginContext } from "@downcity/agent";
 import type { ChatChannelTestResult } from "@/chat/types/ChannelStatus.js";
 import { TelegramApiClient } from "./ApiClient.js";
 import { TelegramStateStore } from "./StateStore.js";
@@ -23,7 +23,7 @@ export interface TelegramPlatformClientOptions {
   /**
    * 当前执行上下文。
    */
-  context: AgentContext;
+  context: PluginContext;
   /**
    * Telegram bot token。
    */
@@ -48,7 +48,7 @@ export interface TelegramPlatformClientOptions {
  * Telegram 平台运行时。
  */
 export class TelegramPlatformClient {
-  private readonly logger: AgentContext["logger"];
+  private readonly logger: PluginContext["logger"];
   private readonly api: TelegramApiClient;
   private readonly stateStore: TelegramStateStore;
   private readonly onMessage: TelegramPlatformClientOptions["onMessage"];
@@ -74,10 +74,10 @@ export class TelegramPlatformClient {
     this.botToken = options.botToken;
     this.api = new TelegramApiClient({
       botToken: options.botToken,
-      projectRoot: options.context.rootPath,
+      project_root: options.context.workspace_path,
       logger: options.context.logger,
     });
-    this.stateStore = new TelegramStateStore(options.context.rootPath);
+    this.stateStore = new TelegramStateStore(options.context.workspace_path);
     this.onMessage = options.onMessage;
     this.onCallbackQuery = options.onCallbackQuery;
     this.onWebhookConflictResolved = options.onWebhookConflictResolved;
@@ -298,18 +298,18 @@ export class TelegramPlatformClient {
    */
   async sendInboundAckReaction(params: {
     chatId: string;
-    messageId?: number;
+    message_id?: number;
     emoji: string;
   }): Promise<void> {
-    if (!params.messageId) return;
+    if (!params.message_id) return;
     try {
-      await this.api.setMessageReaction(params.chatId, params.messageId, {
+      await this.api.setMessageReaction(params.chatId, params.message_id, {
         emoji: params.emoji,
       });
     } catch (error) {
       this.logger.warn("Telegram 入站 ack reaction 失败，继续处理消息", {
         chatId: params.chatId,
-        messageId: params.messageId,
+        message_id: params.message_id,
         error: String(error),
       });
     }
@@ -354,10 +354,10 @@ export class TelegramPlatformClient {
    */
   async setMessageReaction(
     chatId: string,
-    messageId: number,
+    message_id: number,
     opts?: { emoji?: string; isBig?: boolean },
   ): Promise<void> {
-    await this.api.setMessageReaction(chatId, messageId, opts);
+    await this.api.setMessageReaction(chatId, message_id, opts);
   }
 
   /**

package/src/chat/config/ChatPluginConfig.ts

@@ -0,0 +1,266 @@
+/**
+ * Chat Plugin 的结构化配置协议。
+ *
+ * 关键点（中文）
+ * - Zod Schema 是内建 Chat 行为配置与 Resource 配置的唯一源码。
+ * - Plugin config 只描述 queue 行为，完整渠道配置由独立 Resource Item 承载。
+ * - `readOnly` 字段由 Resource Resolver 写入，`writeOnly` 字段由 CLI 安全采集和脱敏。
+ */
+
+import type { JsonObject } from "@downcity/agent";
+import { z } from "zod";
+import { resolveChatChannelBotInfo } from "@/chat/channels/BotInfoProvider.js";
+import type { ChatPluginResource } from "@/chat/types/ChatPluginResource.js";
+
+const resource_id_schema = z.string()
+  .trim()
+  .min(1)
+  .max(80)
+  .regex(/^[a-z0-9][a-z0-9_-]*$/u)
+  .meta({
+    title: "Resource ID",
+    description: "Stable Resource ID generated by City.",
+    readOnly: true,
+  });
+
+const resource_name_schema = z.string()
+  .trim()
+  .min(1)
+  .meta({
+    title: "Name",
+    description: "Display name written by the Resource Resolver.",
+    readOnly: true,
+  });
+
+const secret_schema = z.string()
+  .trim()
+  .min(1)
+  .meta({ writeOnly: true });
+
+/** Telegram Resource 完整配置 Schema。 */
+const telegram_resource_schema = z.object({
+  id: resource_id_schema,
+  type: z.literal("telegram").meta({ title: "Type" }),
+  name: resource_name_schema,
+  bot_token: secret_schema.meta({
+    title: "Bot Token",
+    description: "Telegram Bot API Token.",
+    writeOnly: true,
+  }),
+  username: z.string().trim().min(1).optional().meta({
+    title: "Username",
+    description: "Telegram username written by the Resource Resolver.",
+    readOnly: true,
+  }),
+  bot_user_id: z.string().trim().min(1).optional().meta({
+    title: "Bot User ID",
+    description: "Telegram Bot user ID written by the Resource Resolver.",
+    readOnly: true,
+  }),
+}).strict().meta({
+  title: "Telegram",
+  description: "Telegram Bot Resource.",
+});
+
+/** Feishu / Lark Resource 完整配置 Schema。 */
+const feishu_resource_schema = z.object({
+  id: resource_id_schema,
+  type: z.literal("feishu").meta({ title: "Type" }),
+  name: resource_name_schema,
+  app_id: z.string().trim().min(1).meta({
+    title: "App ID",
+    description: "Feishu or Lark App ID.",
+  }),
+  app_secret: secret_schema.meta({
+    title: "App Secret",
+    description: "Feishu or Lark App Secret.",
+    writeOnly: true,
+  }),
+  domain: z.url().optional().meta({
+    title: "Open API Domain",
+    description: "Optional Feishu or Lark Open API domain.",
+  }),
+  identity: z.string().trim().min(1).optional().meta({
+    title: "Identity",
+    readOnly: true,
+  }),
+  owner: z.string().trim().min(1).optional().meta({
+    title: "Owner",
+    readOnly: true,
+  }),
+  creator: z.string().trim().min(1).optional().meta({
+    title: "Creator",
+    readOnly: true,
+  }),
+  bot_user_id: z.string().trim().min(1).optional().meta({
+    title: "Bot User ID",
+    readOnly: true,
+  }),
+}).strict().meta({
+  title: "Feishu / Lark",
+  description: "Feishu or Lark Bot Resource.",
+});
+
+/** QQ Resource 完整配置 Schema。 */
+const qq_resource_schema = z.object({
+  id: resource_id_schema,
+  type: z.literal("qq").meta({ title: "Type" }),
+  name: resource_name_schema,
+  app_id: z.string().trim().min(1).meta({
+    title: "App ID",
+    description: "QQ Bot App ID.",
+  }),
+  app_secret: secret_schema.meta({
+    title: "App Secret",
+    description: "QQ Bot App Secret.",
+    writeOnly: true,
+  }),
+  sandbox: z.boolean().optional().meta({
+    title: "Sandbox",
+    description: "Whether to use the QQ sandbox environment.",
+    default: false,
+  }),
+  identity: z.string().trim().min(1).optional().meta({
+    title: "Identity",
+    readOnly: true,
+  }),
+  bot_user_id: z.string().trim().min(1).optional().meta({
+    title: "Bot User ID",
+    readOnly: true,
+  }),
+}).strict().meta({
+  title: "QQ",
+  description: "QQ Bot Resource.",
+});
+
+/** Chat Plugin 单个完整 Resource Item Schema。 */
+export const chat_plugin_resource_schema = z.discriminatedUnion("type", [
+  telegram_resource_schema,
+  feishu_resource_schema,
+  qq_resource_schema,
+]);
+
+/** Chat Plugin 完整配置 Schema。 */
+export const chat_plugin_config_schema = z.object({
+  queue: z.object({
+    max_concurrency: z.number()
+      .int()
+      .min(1)
+      .max(32)
+      .optional()
+      .meta({
+        title: "Maximum concurrency",
+        description: "Maximum number of chat lanes executed concurrently.",
+      }),
+    merge_debounce_ms: z.number()
+      .int()
+      .min(0)
+      .max(60_000)
+      .optional()
+      .meta({
+        title: "Merge debounce",
+        description: "Debounce window used to merge consecutive inbound messages.",
+      }),
+    merge_max_wait_ms: z.number()
+      .int()
+      .min(0)
+      .max(120_000)
+      .optional()
+      .meta({
+        title: "Maximum merge wait",
+        description: "Maximum time to wait before executing a merged inbound burst.",
+      }),
+  }).strict().optional().meta({
+    title: "Queue",
+    description: "Chat queue scheduling and inbound message merge behavior.",
+  }),
+}).strict().meta({
+  title: "Chat Plugin",
+  description: "Chat queue behavior. Messaging channels are Plugin Resources.",
+});
+
+/** Chat Plugin 完整结构化配置。 */
+export type ChatPluginConfig = z.infer<typeof chat_plugin_config_schema>;
+
+/** 供 City Plugin Catalog 使用的标准 JSON Schema。 */
+export const CHAT_PLUGIN_CONFIG_JSON_SCHEMA = z.toJSONSchema(
+  chat_plugin_config_schema,
+  { target: "draft-2020-12" },
+) as JsonObject;
+
+/** 供 City Plugin Catalog 使用的完整 Resource Item JSON Schema。 */
+export const CHAT_PLUGIN_RESOURCE_JSON_SCHEMA = z.toJSONSchema(
+  chat_plugin_resource_schema,
+  { target: "draft-2020-12" },
+) as JsonObject;
+
+/** 在运行时装配边界解析并收窄 Chat Plugin 配置。 */
+export function parse_chat_plugin_config(input: unknown): ChatPluginConfig {
+  return chat_plugin_config_schema.parse(input);
+}
+
+/** 解析一个完整 Chat Plugin Resource Item。 */
+export function parse_chat_plugin_resource(input: unknown): ChatPluginResource {
+  return chat_plugin_resource_schema.parse(input);
+}
+
+/** 读取一个 Chat Resource 类型分支的标准 JSON Schema。 */
+export function get_chat_plugin_resource_json_schema(
+  resource_type: ChatPluginResource["type"],
+): JsonObject {
+  const variants = Array.isArray(CHAT_PLUGIN_RESOURCE_JSON_SCHEMA.oneOf)
+    ? CHAT_PLUGIN_RESOURCE_JSON_SCHEMA.oneOf
+    : [];
+  for (const value of variants) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) continue;
+    const variant = value as JsonObject;
+    const properties = variant.properties;
+    if (!properties || typeof properties !== "object" || Array.isArray(properties)) continue;
+    const type_schema = (properties as JsonObject).type;
+    if (
+      type_schema
+      && typeof type_schema === "object"
+      && !Array.isArray(type_schema)
+      && (type_schema as JsonObject).const === resource_type
+    ) {
+      return JSON.parse(JSON.stringify(variant)) as JsonObject;
+    }
+  }
+  throw new Error(`Missing Chat Resource schema: ${resource_type}`);
+}
+
+/**
+ * 根据用户字段解析并返回 Resolver 可写的动态字段。
+ *
+ * 关键点（中文）：返回值不包含 `id`、`type` 和凭据，字段所有权由 City 按 Schema 校验。
+ */
+export async function resolve_chat_plugin_resource(
+  input: JsonObject,
+): Promise<JsonObject> {
+  const type = String(input.type || "").trim();
+  if (type !== "telegram" && type !== "feishu" && type !== "qq") {
+    throw new Error(`Unsupported Chat Resource type: ${type}`);
+  }
+  const result = await resolveChatChannelBotInfo({
+    channel: type,
+    credentials: {
+      botToken: typeof input.bot_token === "string" ? input.bot_token : undefined,
+      appId: typeof input.app_id === "string" ? input.app_id : undefined,
+      appSecret: typeof input.app_secret === "string" ? input.app_secret : undefined,
+      domain: typeof input.domain === "string" ? input.domain : undefined,
+      sandbox: input.sandbox === true,
+    },
+  });
+  const identity = String(result.identity || "").trim();
+  const bot_user_id = String(result.botUserId || "").trim();
+  const owner = String(result.owner || "").trim();
+  const creator = String(result.creator || "").trim();
+  return {
+    name: result.name,
+    ...(type === "telegram" && identity ? { username: identity } : {}),
+    ...(type !== "telegram" && identity ? { identity } : {}),
+    ...(bot_user_id ? { bot_user_id } : {}),
+    ...(type === "feishu" && owner ? { owner } : {}),
+    ...(type === "feishu" && creator ? { creator } : {}),
+  };
+}