@downcity/plugins 1.0.153 → 1.0.157

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

@@ -72,6 +72,29 @@ export class TelegramBot extends BaseChatChannel {
     return buildTelegramChatKey(params.chatId, params.messageThreadId);
   }
 
+  /** SDK 直连时使用 Telegram Bot ID 作为 issuer。 */
+  protected getAccessIssuerFallback(): string {
+    return String(this.platform.getBotId() || "").trim();
+  }
+
+  /**
+   * 使用 Telegram 行内代码展示授权值。
+   *
+   * 说明（中文）
+   * - Telegram 的 Markdown 会把普通文本中的成对下划线解析为强调标记。
+   * - 行内代码可以原样保留 request ID 和 Agent ID，便于管理员直接复制执行。
+   */
+  protected format_access_code(value: string): string {
+    const escaped_value = value.replace(/([\\`])/g, "\\$1");
+    return `\`${escaped_value}\``;
+  }
+
+  /** 使用带语言标记的代码块展示可直接执行的管理命令。 */
+  protected format_access_command(command: string): string {
+    const escaped_command = command.replace(/([\\`])/g, "\\$1");
+    return `\`\`\`bash\n${escaped_command}\n\`\`\``;
+  }
+
   protected async sendTextToPlatform(
     params: ChannelSendTextParams,
   ): Promise<void> {
@@ -207,16 +230,13 @@ export class TelegramBot extends BaseChatChannel {
         logger: this.logger,
         inboundAckEmoji: TelegramBot.INBOUND_ACK_EMOJI,
         platform: this.platform,
-        observeIncomingAuthorization: async (params) => {
-          await this.observeIncomingAuthorization(params);
-        },
-        evaluateIncomingAuthorization: async (params) =>
-          await this.evaluateIncomingAuthorization(params),
-        sendAuthorizationText: async (params) => {
-          await this.sendAuthorizationText(params);
+        evaluateIncomingAccess: async (params) =>
+          await this.evaluateIncomingAccess(params),
+        sendAccessText: async (params) => {
+          await this.sendAccessText(params);
         },
-        buildUnauthorizedBlockedText: (params) =>
-          this.buildUnauthorizedBlockedText(params),
+        buildAccessBlockedText: (params) =>
+          this.buildAccessBlockedText(params),
         enqueueAuditMessage: async (params) => {
           await this.enqueueAuditMessage(params);
         },

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

@@ -28,14 +28,14 @@ export class TelegramChannelConfiguration extends ChatChannelConfiguration {
         canConfigure: true,
       },
       fields: {
-        ship: [
+        agent_config: [
           {
             key: "enabled",
             label: "Enabled",
             description:
               "Whether telegram channel should be started by runtime.",
             type: "boolean",
-            source: "ship_json",
+            source: "agent_config",
             required: false,
             nullable: false,
             writable: true,
@@ -47,9 +47,9 @@ export class TelegramChannelConfiguration extends ChatChannelConfiguration {
             key: "channelAccountId",
             label: "Chat Account ID",
             description:
-              "Bind this chat platform to a chat account row in ~/.downcity/downcity.db channel_accounts.",
+              "Bind this chat platform to a channel_accounts row in the global downcity.db.",
             type: "string",
-            source: "ship_json",
+            source: "agent_config",
             required: false,
             nullable: true,
             writable: true,

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

@@ -2,7 +2,7 @@
  * Telegram 普通消息处理器。
  *
  * 关键点（中文）
- * - 负责单条 message 的授权、审计、附件保存、入队指令构造。
+ * - 负责单条 message 的 Chat Access、审计、附件保存、入队指令构造。
  * - 不持有 channel 实例；所有副作用通过显式依赖注入。
  * - `TelegramBot` 只保留平台生命周期与命令/callback 分发入口。
  */
@@ -12,8 +12,8 @@ import type { Logger } from "@downcity/agent";
 import type { AgentContext } from "@downcity/agent";
 import type { JsonObject } from "@downcity/agent";
 import type {
-  IncomingAuthorizationParams,
-  IncomingAuthorizationResult,
+  IncomingChatAccessParams,
+  IncomingChatAccessResult,
 } from "@/chat/channels/BaseChatChannel.js";
 import type { ChannelUserMessageMeta } from "@/chat/channels/BaseChatChannelSupport.js";
 import {
@@ -127,35 +127,23 @@ export interface TelegramMessageHandlerOptions {
    * Telegram 平台能力。
    */
   platform: TelegramMessagePlatform;
+  /** 入站 Chat Access 判定。 */
+  evaluateIncomingAccess(
+    params: IncomingChatAccessParams,
+  ): Promise<IncomingChatAccessResult>;
   /**
-   * 入站主体观测。
+   * 发送 Chat Access 失败提示。
    */
-  observeIncomingAuthorization(
-    params: IncomingAuthorizationParams,
-  ): Promise<void>;
-  /**
-   * 入站授权判定。
-   */
-  evaluateIncomingAuthorization(
-    params: IncomingAuthorizationParams,
-  ): Promise<IncomingAuthorizationResult>;
-  /**
-   * 发送授权失败提示。
-   */
-  sendAuthorizationText(params: {
+  sendAccessText(params: {
     chatId: string;
     text: string;
     chatType?: string;
     messageThreadId?: number;
   }): Promise<void>;
   /**
-   * 构建授权失败提示文案。
+   * 构建 Chat Access 失败提示文案。
    */
-  buildUnauthorizedBlockedText(params?: {
-    userId?: string;
-    chatId?: string;
-    chatType?: string;
-  }): string;
+  buildAccessBlockedText(params: { result: IncomingChatAccessResult }): string;
   /**
    * Audit 队列写入。
    */
@@ -223,32 +211,20 @@ export async function handleTelegramMessage(
     return;
   }
 
-  await options.observeIncomingAuthorization({
-    chatId,
-    chatType: message.chat.type,
-    chatTitle,
-    userId: actorId,
-    username: actorName,
-  });
-
-  const authResult = await options.evaluateIncomingAuthorization({
+  const access_result = await options.evaluateIncomingAccess({
     chatId,
     chatType: message.chat.type,
     chatTitle,
     userId: actorId,
     username: actorName,
   });
-  if (authResult.decision !== "allow") {
+  if (!access_result.allowed) {
     if (!isGroup) {
-      await options.sendAuthorizationText({
+      await options.sendAccessText({
         chatId,
         chatType: message.chat.type,
         messageThreadId,
-        text: options.buildUnauthorizedBlockedText({
-          chatId,
-          chatType: message.chat.type,
-          userId: actorId,
-        }),
+        text: options.buildAccessBlockedText({ result: access_result }),
       });
     }
     return;

package/src/chat/runtime/ChatChannelActions.ts

@@ -7,7 +7,11 @@
  * - 对外只暴露 action 级入口，供 ChatPluginActions 装配使用。
  */
 
-import type { AgentContext } from "@downcity/agent";
+import type {
+  AgentContext,
+  DowncityChatChannelConfig,
+  DowncityConfig,
+} from "@downcity/agent";
 import type { ChatChannelState } from "@/chat/types/ChatRuntime.js";
 import { getStoredChannelAccountSync } from "@/chat/accounts/Store.js";
 import type {
@@ -20,6 +24,7 @@ import type {
   ChatTestActionPayload,
 } from "@/chat/types/ChatPluginActionPayload.js";
 import type { ChatChannelTestResult } from "@/chat/types/ChannelStatus.js";
+import type { ChatChannelName } from "@/chat/types/ChannelStatus.js";
 import {
   describeChatChannelConfiguration,
   getChatChannelStatus,
@@ -49,6 +54,54 @@ function getChatRuntimeBindings(context: AgentContext): ChatRuntimeControlBindin
   return plugin as ChatRuntimeControlBindings;
 }
 
+/**
+ * 将 channel patch 合并进完整 plugins 配置并交给宿主持久化。
+ *
+ * 关键点（中文）
+ * - 始终写回完整 plugins 对象，避免覆盖其他 plugin 配置。
+ * - 宿主持久化成功后才更新当前 context 快照，保证运行态与存储态一致。
+ */
+async function persist_chat_channel_patches(params: {
+  context: AgentContext;
+  patches: Array<{
+    channel: ChatChannelName;
+    enabled?: boolean;
+    channel_account_id?: string | null;
+  }>;
+}): Promise<DowncityConfig["plugins"]> {
+  const current_plugins = params.context.config.plugins || {};
+  const current_chat = current_plugins.chat || {};
+  const next_channels = { ...(current_chat.channels || {}) };
+
+  for (const patch of params.patches) {
+    const current_channel = next_channels[patch.channel] || {};
+    const next_channel: DowncityChatChannelConfig = { ...current_channel };
+    if (typeof patch.enabled === "boolean") {
+      next_channel.enabled = patch.enabled;
+    }
+    if (Object.prototype.hasOwnProperty.call(patch, "channel_account_id")) {
+      const channel_account_id = String(patch.channel_account_id || "").trim();
+      if (channel_account_id) {
+        next_channel.channelAccountId = channel_account_id;
+      } else {
+        delete next_channel.channelAccountId;
+      }
+    }
+    next_channels[patch.channel] = next_channel;
+  }
+
+  const next_plugins: DowncityConfig["plugins"] = {
+    ...current_plugins,
+    chat: {
+      ...current_chat,
+      channels: next_channels,
+    },
+  };
+  await params.context.pluginConfig.persistProjectPlugins(next_plugins);
+  params.context.config.plugins = next_plugins;
+  return next_plugins;
+}
+
 /**
  * 执行 `chat.status` action。
  */
@@ -176,6 +229,10 @@ export async function executeChatOpenAction(params: {
 }) {
   const targets = resolveTargetChannels(params.payload.channel);
   const plugin = getChatRuntimeBindings(params.context);
+  await persist_chat_channel_patches({
+    context: params.context,
+    patches: targets.map((channel) => ({ channel, enabled: true })),
+  });
   for (const channel of targets) {
     plugin.applyChannelRuntimePatch({
       channel,
@@ -211,6 +268,10 @@ export async function executeChatCloseAction(params: {
 }) {
   const targets = resolveTargetChannels(params.payload.channel);
   const plugin = getChatRuntimeBindings(params.context);
+  await persist_chat_channel_patches({
+    context: params.context,
+    patches: targets.map((channel) => ({ channel, enabled: false })),
+  });
   for (const channel of targets) {
     await stopSingleChatChannel(params.state, channel);
     plugin.applyChannelRuntimePatch({
@@ -293,6 +354,16 @@ export async function executeChatConfigureAction(params: {
   }
 
   const plugin = getChatRuntimeBindings(params.context);
+  await persist_chat_channel_patches({
+    context: params.context,
+    patches: [{
+      channel,
+      ...(typeof patch.enabled === "boolean" ? { enabled: patch.enabled } : {}),
+      ...(Object.prototype.hasOwnProperty.call(patch, "channelAccountId")
+        ? { channel_account_id: String(patch.channelAccountId || "").trim() || null }
+        : {}),
+    }],
+  });
   plugin.applyChannelRuntimePatch({
     channel,
     ...(typeof patch.enabled === "boolean" ? { enabled: patch.enabled } : {}),

package/src/chat/runtime/ChatChannelConfig.ts

@@ -3,7 +3,7 @@
  *
  * 关键点（中文）
  * - 渠道配置摘要、状态快照、patch 归一化都收敛在这里。
- * - chat.configure 的运行态写入由 ChatPlugin 实例承载，不再落盘到 downcity.json。
+ * - chat.configure 的配置持久化由宿主能力承载，运行态更新由 ChatPlugin 实例承载。
  * - 该模块不直接负责 action 流程控制，只提供可复用的底层能力。
  */
 
@@ -37,7 +37,7 @@ function toJsonObject(input: unknown): JsonObject {
  *
  * 关键点（中文）
  * - 不返回明文密钥，只返回布尔“是否已配置”。
- * - 字段命名尽量贴近 `downcity.json`，便于前端直接映射编辑。
+ * - 字段命名与 Agent 全局配置保持一致，便于前端直接映射编辑。
  */
 export function buildChatChannelConfigSummary(
   context: AgentContext,
@@ -194,7 +194,7 @@ export function normalizeChatChannelConfigPatch(params: {
   config: Record<string, JsonValue>;
 }): Record<string, string | number | boolean | null> {
   const configDefinition = getChatChannelConfiguration(params.channel);
-  const writableFields = configDefinition.getWritableShipFields();
+  const writableFields = configDefinition.get_writable_agent_config_fields();
   const patch: Record<string, string | number | boolean | null> = {};
 
   for (const field of writableFields) {

package/src/chat/runtime/ChatChannelCore.ts

@@ -101,7 +101,7 @@ export function resolveChannelAccountId(
  * 关键点（中文）
  * - 优先使用 ChatPlugin 实例上的显式解析逻辑。
  * - 若实例只提供 channelAccountId，再从默认全局账号池读取对应账号。
- * - 不再从 downcity.json 隐式推断运行时账号。
+ * - 不从项目文件隐式推断运行时账号。
  */
 export function resolveChannelAccount(
   context: AgentContext,

package/src/chat/runtime/ChatChannelLifecycle.ts

@@ -4,7 +4,7 @@
  * 关键点（中文）
  * - 渠道 bot 的创建、启动、停止逻辑统一收敛在这里。
  * - 渠道 bot 状态归属于 chat plugin runtime 实例持有的 `ChatChannelState`。
- * - 本模块不处理 downcity.json 写入，也不负责 action 输入输出包装。
+ * - 本模块不处理配置持久化，也不负责 action 输入输出包装。
  */
 
 import type { AgentContext } from "@downcity/agent";

package/src/chat/runtime/PluginPoints.ts

@@ -51,28 +51,4 @@ export const CHAT_PLUGIN_POINTS = {
    * - plugin 可在这里做统计、观测、调试落点。
    */
   afterEnqueue: "chat.afterEnqueue",
-  /**
-   * 观测入站主体信息。
-   *
-   * 说明（中文）
-   * - 仅做副作用记录，不返回值。
-   * - ChatPlugin 内置授权能力会使用该点记录主体快照。
-   */
-  observePrincipal: "chat.observePrincipal",
-  /**
-   * 判定当前入站消息是否允许执行。
-   *
-   * 说明（中文）
-   * - 由 chat plugin runtime 在 ingress 阶段显式调用。
-   * - ChatPlugin 内置授权能力会使用该点执行角色与权限判定。
-   */
-  authorizeIncoming: "chat.authorizeIncoming",
-  /**
-   * 解析当前用户角色。
-   *
-   * 说明（中文）
-   * - 主要用于在 history / queue metadata 中补齐授权上下文。
-   * - ChatPlugin 内置授权能力会使用该点补齐用户角色。
-   */
-  resolveUserRole: "chat.resolveUserRole",
 } as const;

package/src/chat/runtime/QueuedUserMessage.ts

@@ -43,8 +43,6 @@ export function buildQueuedUserMessageWithInfo(params: {
     `message_id: ${normalizeInfoValue(params.messageId || "unknown")}`,
     `user_id: ${normalizeInfoValue(params.userId || "unknown")}`,
     `username: ${normalizeInfoValue(params.username || "unknown")}`,
-    `role_id: ${normalizeInfoValue(params.roleId || "unknown")}`,
-    `permissions: ${normalizeInfoValue((params.permissions || []).join(",") || "none")}`,
     `received_at: ${normalizeInfoValue(receivedAtIso)}`,
     `received_at_local: ${normalizeInfoValue(formatDateTimeInTimezone(receivedAtDate, runtimeTimezone))}`,
     `runtime_timezone: ${normalizeInfoValue(runtimeTimezone)}`,

package/src/chat/types/ChannelConfiguration.ts

@@ -27,7 +27,7 @@ export type ChatChannelConfigurationFieldType =
  * 配置字段来源枚举。
  */
 export type ChatChannelConfigurationFieldSource =
-  | "ship_json"
+  | "agent_config"
   | "bot_account"
   | "env_fallback";
 
@@ -70,7 +70,7 @@ export interface ChatChannelConfigurationField {
    */
   type: ChatChannelConfigurationFieldType;
   /**
-   * 字段值来源（downcity.json / chat account / env fallback）。
+   * 字段值来源（Agent config / chat account / env fallback）。
    */
   source: ChatChannelConfigurationFieldSource;
   /**
@@ -145,9 +145,9 @@ export interface ChatChannelConfigurationDescriptor {
    */
   fields: {
     /**
-     * `downcity.json` 可声明字段。
+     * Agent 全局配置可声明字段。
      */
-    ship: ChatChannelConfigurationField[];
+    agent_config: ChatChannelConfigurationField[];
     /**
      * `channel_accounts` 字段。
      */