@downcity/plugins 1.0.35 → 1.0.39

package/src/chat/accounts/Store.ts

@@ -1,13 +1,13 @@
 /**
- * Channel account 默认存储实现。
+ * Chat account 默认存储实现。
  *
  * 职责说明（中文）
- * - 提供 `chat` plugin 默认使用的全局 channel account 读写能力。
+ * - 提供 `chat` plugin 默认使用的全局 chat account 读写能力。
  * - 默认直接操作 `~/.downcity/downcity.db` 里的 `channel_accounts` 表。
  * - 对 `city` 而言，这里也是统一的默认账号池实现来源。
  *
  * 边界说明（中文）
- * - 这里只负责 channel account 这一个表，不扩展成通用平台数据库门面。
+ * - 这里只负责 chat account 这一个表，不扩展成通用平台数据库门面。
  * - 模型池、env、其他平台级配置仍由各自模块独立管理。
  */
 
@@ -40,7 +40,7 @@ function optionalTrimmedText(value: string | undefined): string | undefined {
 }
 
 /**
- * 规范化 channel 类型。
+ * 规范化 chat platform 类型。
  */
 export function normalizeChannelAccountChannel(
   input: string,
@@ -49,7 +49,7 @@ export function normalizeChannelAccountChannel(
   if (channel === "telegram" || channel === "feishu" || channel === "qq") {
     return channel;
   }
-  throw new Error(`Unsupported channel account type: ${input}`);
+  throw new Error(`Unsupported chat account platform: ${input}`);
 }
 
 function ensureChannelAccountSchema(database: Database.Database): void {
@@ -138,7 +138,7 @@ function buildChannelAccountFromRow(
 }
 
 /**
- * 同步列出全部 channel account。
+ * 同步列出全部 chat account。
  */
 export function listStoredChannelAccountsSync(
   channelInput?: string,
@@ -178,12 +178,12 @@ export function listStoredChannelAccountsSync(
 }
 
 /**
- * 同步按 ID 读取单个 channel account。
+ * 同步按 ID 读取单个 chat account。
  */
 export function getStoredChannelAccountSync(
   accountIdInput: string,
 ): StoredChannelAccount | null {
-  const accountId = normalizeNonEmptyText(accountIdInput, "channel account id");
+  const accountId = normalizeNonEmptyText(accountIdInput, "chat account id");
   return withChannelAccountDb((database) => {
     const row = database.prepare(
       `
@@ -201,7 +201,7 @@ export function getStoredChannelAccountSync(
 }
 
 /**
- * 新增或更新 channel account。
+ * 新增或更新 chat account。
  *
  * 关键点（中文）
  * - 这里保留和现有平台库一致的落盘结构，避免默认实现切换后出现数据断层。
@@ -210,9 +210,9 @@ export function getStoredChannelAccountSync(
 export async function upsertStoredChannelAccount(
   input: UpsertChannelAccountInput,
 ): Promise<void> {
-  const id = normalizeNonEmptyText(input.id, "channel account id");
+  const id = normalizeNonEmptyText(input.id, "chat account id");
   const channel = normalizeChannelAccountChannel(input.channel);
-  const name = normalizeNonEmptyText(input.name, "channel account name");
+  const name = normalizeNonEmptyText(input.name, "chat account name");
   const existing = getStoredChannelAccountSync(id);
   const createdAt = existing?.createdAt || nowIso();
   const updatedAt = nowIso();
@@ -275,12 +275,12 @@ export async function upsertStoredChannelAccount(
 }
 
 /**
- * 删除单个 channel account。
+ * 删除单个 chat account。
  */
 export async function removeStoredChannelAccount(
   accountIdInput: string,
 ): Promise<void> {
-  const accountId = normalizeNonEmptyText(accountIdInput, "channel account id");
+  const accountId = normalizeNonEmptyText(accountIdInput, "chat account id");
   withChannelAccountDb((database) => {
     database.prepare("DELETE FROM channel_accounts WHERE id = ?;").run(accountId);
   });

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

@@ -3,7 +3,7 @@
  *
  * 关键点（中文）
  * - ship 层只保留绑定字段。
- * - appId/appSecret/domain 由 channel account 维护。
+ * - appId/appSecret/domain 由 chat account 维护。
  */
 
 import { ChatChannelConfiguration } from "@/chat/channels/Configuration.js";
@@ -18,9 +18,9 @@ export class FeishuChannelConfiguration extends ChatChannelConfiguration {
   describe(): ChatChannelConfigurationDescriptor {
     return {
       channel: this.channel,
-      title: "Feishu Channel Configuration",
+      title: "Feishu Chat Platform Configuration",
       description:
-        "Bind a Feishu/Lark channel account and control runtime enable/disable state.",
+        "Bind a Feishu/Lark chat account and control runtime enable/disable state.",
       version: "1.0.0",
       capabilities: {
         canToggleEnabled: true,
@@ -45,9 +45,9 @@ export class FeishuChannelConfiguration extends ChatChannelConfiguration {
           },
           {
             key: "channelAccountId",
-            label: "Channel Account ID",
+            label: "Chat Account ID",
             description:
-              "Bind channel to a channel account row in ~/.downcity/downcity.db channel_accounts.",
+              "Bind this chat platform to a chat account row in ~/.downcity/downcity.db channel_accounts.",
             type: "string",
             source: "ship_json",
             required: false,

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

@@ -3,7 +3,7 @@
  *
  * 关键点（中文）
  * - ship 层只保留 `enabled` 与 `channelAccountId`。
- * - QQ 专属参数（sandbox 等）在 channel account 中维护。
+ * - QQ 专属参数（sandbox 等）在 chat account 中维护。
  */
 
 import { ChatChannelConfiguration } from "@/chat/channels/Configuration.js";
@@ -18,9 +18,9 @@ export class QqChannelConfiguration extends ChatChannelConfiguration {
   describe(): ChatChannelConfigurationDescriptor {
     return {
       channel: this.channel,
-      title: "QQ Channel Configuration",
+      title: "QQ Chat Platform Configuration",
       description:
-        "Bind a QQ channel account and control runtime enable/disable state.",
+        "Bind a QQ chat account and control runtime enable/disable state.",
       version: "1.0.0",
       capabilities: {
         canToggleEnabled: true,
@@ -44,9 +44,9 @@ export class QqChannelConfiguration extends ChatChannelConfiguration {
           },
           {
             key: "channelAccountId",
-            label: "Channel Account ID",
+            label: "Chat Account ID",
             description:
-              "Bind channel to a channel account row in ~/.downcity/downcity.db channel_accounts.",
+              "Bind this chat platform to a chat account row in ~/.downcity/downcity.db channel_accounts.",
             type: "string",
             source: "ship_json",
             required: false,

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

@@ -10,6 +10,12 @@ import {
   type TelegramAttachmentType,
 } from "./Shared.js";
 
+const TELEGRAM_SEND_MAX_ATTEMPTS = 3;
+const TELEGRAM_SEND_RETRY_DELAYS_MS = [1_000, 3_000];
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
 
 /**
  * Telegram API 客户端。
@@ -104,6 +110,61 @@ export class TelegramApiClient {
     return payload.result as T;
   }
 
+  /**
+   * 发送类 JSON 请求的短重试。
+   *
+   * 关键点（中文）
+   * - 只重试网络抖动 / Telegram 5xx 这类瞬时失败。
+   * - 不重试 Telegram 4xx，避免 Markdown 参数错误、权限错误等被重复打扰。
+   */
+  private async requestSendJson<T>(
+    method: string,
+    data: Record<string, unknown>,
+  ): Promise<T> {
+    let lastError: unknown;
+    for (let attempt = 0; attempt < TELEGRAM_SEND_MAX_ATTEMPTS; attempt += 1) {
+      try {
+        return await this.requestJson<T>(method, data);
+      } catch (error) {
+        lastError = error;
+        if (
+          attempt >= TELEGRAM_SEND_MAX_ATTEMPTS - 1 ||
+          !this.isRetryableSendError(error)
+        ) {
+          throw error;
+        }
+
+        const delayMs =
+          TELEGRAM_SEND_RETRY_DELAYS_MS[attempt] ||
+          TELEGRAM_SEND_RETRY_DELAYS_MS[
+            TELEGRAM_SEND_RETRY_DELAYS_MS.length - 1
+          ];
+        this.logger.warn("Telegram send failed, retrying", {
+          method,
+          attempt: attempt + 1,
+          retryInMs: delayMs,
+          error: String(error),
+        });
+        await sleep(delayMs);
+      }
+    }
+
+    throw lastError;
+  }
+
+  /**
+   * 判断发送失败是否适合短重试。
+   */
+  private isRetryableSendError(error: unknown): boolean {
+    const text = String(error || "");
+    if (/Telegram API (HTTP|error)\s+4\d\d/i.test(text)) {
+      return false;
+    }
+    return /fetch failed|network|TLS|ECONN|ETIMEDOUT|EAI_AGAIN|UND_ERR|HTTP\s+5\d\d/i.test(
+      text,
+    );
+  }
+
   /**
    * 下载 Telegram 文件并保存到 `.downcity/.cache/telegram`。
    *
@@ -174,7 +235,7 @@ export class TelegramApiClient {
         for (const chunk of chunks) {
           if (!chunk) continue;
           try {
-            await this.requestJson("sendMessage", {
+            await this.requestSendJson("sendMessage", {
               chat_id: chatId,
               text: chunk,
               parse_mode: "Markdown",
@@ -184,7 +245,7 @@ export class TelegramApiClient {
           } catch {
             // Fallback to plain text (Markdown is strict and often fails)
             try {
-              await this.requestJson("sendMessage", {
+              await this.requestSendJson("sendMessage", {
                 chat_id: chatId,
                 text: chunk,
                 ...(message_thread_id ? { message_thread_id } : {}),
@@ -192,6 +253,8 @@ export class TelegramApiClient {
               });
             } catch (error2) {
               this.logger.error(`Failed to send message: ${String(error2)}`);
+              // 关键点（中文）：平台发送失败必须向上冒泡，避免 history 误记为已发送。
+              throw error2;
             }
           }
         }
@@ -205,7 +268,7 @@ export class TelegramApiClient {
         });
       } catch (e) {
         try {
-          await this.requestJson("sendMessage", {
+          await this.requestSendJson("sendMessage", {
             chat_id: chatId,
             text: `❌ Failed to send ${segment.attachment.type}: ${String(e)}`,
             ...(message_thread_id ? { message_thread_id } : {}),
@@ -215,6 +278,8 @@ export class TelegramApiClient {
           this.logger.error(
             `Failed to send attachment error message: ${String(e2)}`,
           );
+          // 关键点（中文）：附件和错误提示都发送失败时，上层必须感知失败。
+          throw e2;
         }
       }
     }
@@ -231,7 +296,7 @@ export class TelegramApiClient {
         ? opts.messageThreadId
         : undefined;
     try {
-      await this.requestJson("sendMessage", {
+      await this.requestSendJson("sendMessage", {
         chat_id: chatId,
         text,
         ...(message_thread_id ? { message_thread_id } : {}),
@@ -243,6 +308,8 @@ export class TelegramApiClient {
       });
     } catch (error) {
       this.logger.error(`Failed to send message: ${String(error)}`);
+      // 关键点（中文）：inline keyboard 发送失败也要返回失败状态给调用方。
+      throw error;
     }
   }
 

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

@@ -3,7 +3,7 @@
  *
  * 关键点（中文）
  * - 基于 `getMe` 接口验证 token 有效性。
- * - 返回统一结构，供 channel account 创建流程复用。
+ * - 返回统一结构，供 chat account 创建流程复用。
  */
 
 import type {

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

@@ -3,7 +3,7 @@
  *
  * 关键点（中文）
  * - ship 层只绑定 `enabled` 与 `channelAccountId`。
- * - 真实密钥由 channel account 统一托管。
+ * - 真实密钥由 chat account 统一托管。
  */
 
 import { ChatChannelConfiguration } from "@/chat/channels/Configuration.js";
@@ -18,9 +18,9 @@ export class TelegramChannelConfiguration extends ChatChannelConfiguration {
   describe(): ChatChannelConfigurationDescriptor {
     return {
       channel: this.channel,
-      title: "Telegram Channel Configuration",
+      title: "Telegram Chat Platform Configuration",
       description:
-        "Bind a Telegram channel account and control runtime enable/disable state.",
+        "Bind a Telegram chat account and control runtime enable/disable state.",
       version: "1.0.0",
       capabilities: {
         canToggleEnabled: true,
@@ -45,9 +45,9 @@ export class TelegramChannelConfiguration extends ChatChannelConfiguration {
           },
           {
             key: "channelAccountId",
-            label: "Channel Account ID",
+            label: "Chat Account ID",
             description:
-              "Bind channel to a channel account row in ~/.downcity/downcity.db channel_accounts.",
+              "Bind this chat platform to a chat account row in ~/.downcity/downcity.db channel_accounts.",
             type: "string",
             source: "ship_json",
             required: false,

package/src/chat/runtime/ChatChannelCore.ts

@@ -4,7 +4,7 @@
  * 关键点（中文）
  * - 这里只放最基础的渠道状态/名称/account 解析能力。
  * - 生命周期、配置写入、action 执行分别放到更细的模块中。
- * - 目标是让 chat channel 子模块共享同一套最小公共基元。
+ * - 目标是让 chat platform 子模块共享同一套最小公共基元。
  */
 
 import type { AgentContext } from "@downcity/agent/internal/types/runtime/agent/AgentContext.js";

package/src/chat/runtime/ChatChannelLifecycle.ts

@@ -69,7 +69,7 @@ async function startQQChannel(
   context: AgentContext,
 ): Promise<void> {
   if (!isChatChannelEnabled(context, "qq")) return;
-  context.logger.info("QQ channel enabled");
+  context.logger.info("QQ chat platform enabled");
   const account = resolveChannelAccount(context, "qq");
   const appId = String(account?.appId || "").trim();
   const appSecret = String(account?.appSecret || "").trim();

package/src/chat/runtime/ChatPluginSystem.ts

@@ -3,7 +3,7 @@
  *
  * 关键点（中文）
  * - chat plugin prompt 与 channel prompt 都属于静态资产。
- * - 当前请求只注入当前 channel 的 prompt，避免平台规则串味。
+ * - 当前请求只注入当前 chat platform 的 prompt，避免平台规则串味。
  * - 该模块只负责 prompt 解析与拼装，不承担运行态控制职责。
  */
 import type { AgentContext } from "@downcity/agent/internal/types/runtime/agent/AgentContext.js";
@@ -38,7 +38,7 @@ function resolveCurrentChatPromptChannel(
  *
  * 关键点（中文）
  * - 仅注入当前 context 对应的 channel prompt，避免把其他平台规则混入本轮会话。
- * - 若当前 context 不是 chat channel（如 consoleui）或尚无路由元信息，则不注入 channel prompt。
+ * - 若当前 context 不是 chat platform（如 Console UI）或尚无路由元信息，则不注入 platform prompt。
  */
 export async function buildCurrentChannelPrompts(
   context: AgentContext,

package/src/chat/runtime/ChatPromptAssets.ts

@@ -22,7 +22,7 @@ export const CHAT_PLUGIN_PROMPT = chatPluginPromptText.trim();
 export const FEISHU_CHAT_CHANNEL_PROMPT = feishuChatPromptText.trim();
 
 /**
- * QQ channel prompt。
+ * QQ chat platform prompt。
  */
 export const QQ_CHAT_CHANNEL_PROMPT = qqChatPromptText.trim();
 

package/src/chat/runtime/ChatQueueWorker.ts

@@ -44,7 +44,6 @@ type TurnObservation = {
   turnId: string;
   sessionId: string;
   messageId?: string;
-  assistantStepDispatched: boolean;
   typing: { stop: () => void };
 };
 
@@ -342,13 +341,18 @@ export class ChatQueueWorker {
     if (event.visibility === "internal") return;
     const stepText = String(event.text || "").trim();
     if (!stepText) return;
-    const dispatched = await this.dispatchAssistantStepMessage({
-      sessionId: observation.sessionId,
-      text: stepText,
-      messageId: observation.messageId,
-    });
-    if (dispatched) {
-      observation.assistantStepDispatched = true;
+
+    try {
+      await this.dispatchAssistantStepMessage({
+        sessionId: observation.sessionId,
+        text: stepText,
+        messageId: observation.messageId,
+      });
+    } catch (error) {
+      this.logger.warn("ChatQueueWorker assistant step dispatch failed", {
+        sessionId: observation.sessionId,
+        error: String(error),
+      });
     }
   }
 
@@ -369,7 +373,6 @@ export class ChatQueueWorker {
         turnId: turn.id,
         sessionId: item.sessionId,
         messageId: item.messageId,
-        assistantStepDispatched: false,
         typing: this.startTypingHeartbeat(item),
       };
       params.lane.turnObservers.set(turn.id, observation);
@@ -437,36 +440,6 @@ export class ChatQueueWorker {
       });
       return;
     }
-
-    if (observation.assistantStepDispatched) {
-      return;
-    }
-
-    const finalAssistantText =
-      pickLastSuccessfulChatSendText(result.assistantMessage) || result.text;
-    if (!finalAssistantText) {
-      return;
-    }
-
-    const dispatchedDirectly = await dispatchAssistantTextDirect({
-      logger: this.logger,
-      context: this.context,
-      sessionId: observation.sessionId,
-      assistantText: finalAssistantText,
-      phase: "final",
-    });
-    if (dispatchedDirectly) {
-      return;
-    }
-
-    await dispatchTextToChannel({
-      logger: this.logger,
-      context: this.context,
-      sessionId: observation.sessionId,
-      text: finalAssistantText,
-      messageId: observation.messageId,
-      phase: "final",
-    });
   }
 
   /**

package/src/chat/types/BotInfo.ts

@@ -3,7 +3,7 @@
  *
  * 关键点（中文）
  * - 将“凭据 -> bot 基础信息”的探测输入输出结构标准化。
- * - Console、Channel Account 存储、后续自动化流程都复用该结构。
+ * - Console、Chat Account 存储、后续自动化流程都复用该结构。
  */
 
 import type { ChatChannelName } from "@/chat/types/ChannelStatus.js";
@@ -77,7 +77,7 @@ export interface ChatBotInfoResult {
    */
   botUserId?: string;
   /**
-   * 建议用于生成 channel account id 的稳定种子。
+   * 建议用于生成 chat account id 的稳定种子。
    */
   idSeed?: string;
   /**

package/src/chat/types/ChannelAccount.ts

@@ -1,24 +1,24 @@
 /**
- * Chat channel account 管理类型。
+ * Chat account 管理类型。
  *
  * 关键点（中文）
- * - 这些类型描述 agent 运行时内部的 chat channel account 管理输入输出。
+ * - 这些类型描述 agent 运行时内部的 chat account 管理输入输出。
  * - 凭据明文只允许出现在写入输入中，读取结果必须是脱敏后的安全视图。
  */
 
 import type { StoredChannelAccountChannel } from "@downcity/agent/internal/types/platform/Store.js";
 
 /**
- * 支持的 chat channel account 类型。
+ * 支持的 chat account 平台类型。
  */
 export type ChatChannelAccountChannel = StoredChannelAccountChannel;
 
 /**
- * Channel account 探测结果。
+ * Chat account 探测结果。
  */
 export interface ChatChannelAccountProbeResult {
   /**
-   * 账号所属 chat channel。
+   * 账号所属 chat platform。
    */
   channel: ChatChannelAccountChannel;
   /**
@@ -52,7 +52,7 @@ export interface ChatChannelAccountProbeResult {
 }
 
 /**
- * Channel account 列表中的安全视图。
+ * Chat account 列表中的安全视图。
  */
 export interface ChatChannelAccountListItem {
   /**
@@ -60,7 +60,7 @@ export interface ChatChannelAccountListItem {
    */
   id: string;
   /**
-   * 账号所属 chat channel。
+   * 账号所属 chat platform。
    */
   channel: ChatChannelAccountChannel;
   /**
@@ -122,7 +122,7 @@ export interface ChatChannelAccountListItem {
 }
 
 /**
- * Channel account 列表结果。
+ * Chat account 列表结果。
  */
 export interface ChatChannelAccountListResult {
   /**
@@ -132,7 +132,7 @@ export interface ChatChannelAccountListResult {
 }
 
 /**
- * Channel account 写入输入。
+ * Chat account 写入输入。
  */
 export interface ChatChannelAccountUpsertInput {
   /**
@@ -140,7 +140,7 @@ export interface ChatChannelAccountUpsertInput {
    */
   id: string;
   /**
-   * 账号所属 chat channel。
+   * 账号所属 chat platform。
    */
   channel: string;
   /**
@@ -194,11 +194,11 @@ export interface ChatChannelAccountUpsertInput {
 }
 
 /**
- * Channel account 凭据创建输入。
+ * Chat account 凭据创建输入。
  */
 export interface ChatChannelAccountCreateInput {
   /**
-   * 账号所属 chat channel。
+   * 账号所属 chat platform。
    */
   channel: string;
   /**

package/src/chat/types/ChannelConfiguration.ts

@@ -70,7 +70,7 @@ export interface ChatChannelConfigurationField {
    */
   type: ChatChannelConfigurationFieldType;
   /**
-   * 字段值来源（downcity.json / channel account / env fallback）。
+   * 字段值来源（downcity.json / chat account / env fallback）。
    */
   source: ChatChannelConfigurationFieldSource;
   /**
@@ -132,7 +132,7 @@ export interface ChatChannelConfigurationDescriptor {
      */
     canToggleEnabled: boolean;
     /**
-     * 是否支持 channel account 绑定。
+     * 是否支持 chat account 绑定。
      */
     canBindChannelAccount: boolean;
     /**
@@ -158,4 +158,3 @@ export interface ChatChannelConfigurationDescriptor {
     envFallback: ChatChannelConfigurationField[];
   };
 }
-

package/src/chat/types/FeishuPost.ts

@@ -3,7 +3,7 @@
  *
  * 关键点（中文）
  * - 统一描述飞书 `msg_type=post` 的核心结构，供入站解析与出站构建复用。
- * - 这里只保留当前 chat channel 真正会消费的字段，避免把平台超大 schema 整体引入运行时。
+ * - 这里只保留当前 chat platform 真正会消费的字段，避免把平台超大 schema 整体引入运行时。
  */
 
 /**