@downcity/plugins 1.0.153 → 1.0.157

package/src/chat/channels/BaseChatChannel.ts

@@ -4,7 +4,7 @@
  * 关键点（中文）
  * - 通过 context 显式注入 runtime 依赖。
  * - 统一注册 dispatcher，暴露 sendText/sendAction 能力。
- * - 基类只保留授权、工具发送与入站编排；存储/队列细节已下沉到辅助模块。
+ * - 基类只保留 Chat Access、工具发送与入站编排；存储/队列细节已下沉到辅助模块。
  */
 
 import { registerChatSender } from "@/chat/runtime/ChatSendRegistry.js";
@@ -19,9 +19,10 @@ import type { AgentContext } from "@downcity/agent";
 import { resolveChatQueueStore } from "@/chat/runtime/ChatQueue.js";
 import { deleteChatSessionById } from "@/chat/runtime/ChatSessionDelete.js";
 import {
-  guardIncomingChat,
-  observeIncomingChatPrincipal,
-} from "@/chat/runtime/PluginDispatch.js";
+  create_chat_access_service,
+  resolve_chat_access_issuer,
+} from "@/chat/access/ChatAccessRuntime.js";
+import type { ChatAccessDecision } from "@/chat/types/ChatAccess.js";
 import {
   appendToolOutboundChannelHistory,
   resolveChannelSessionId,
@@ -108,9 +109,9 @@ export type IncomingChatMessage = {
 };
 
 /**
- * 入站授权判定输入。
+ * 入站 Chat Access 判定输入。
  */
-export type IncomingAuthorizationParams = {
+export type IncomingChatAccessParams = {
   chatId: string;
   chatType?: string;
   userId?: string;
@@ -119,12 +120,9 @@ export type IncomingAuthorizationParams = {
 };
 
 /**
- * 入站授权判定结果。
+ * 入站 Chat Access 判定结果。
  */
-export type IncomingAuthorizationResult = {
-  decision: "allow" | "block";
-  reason: string;
-};
+export type IncomingChatAccessResult = ChatAccessDecision;
 
 /**
  * Chat channel 基类。
@@ -134,6 +132,7 @@ export abstract class BaseChatChannel {
   protected readonly context: AgentContext;
   protected readonly rootPath: string;
   protected readonly logger: Logger;
+  private readonly access_notice_sent_at = new Map<string, number>();
 
   protected constructor(params: {
     channel: ChatDispatchChannel;
@@ -159,22 +158,57 @@ export abstract class BaseChatChannel {
     params: ChannelSendTextParams,
   ): Promise<void>;
 
+  /**
+   * SDK 未绑定 City Chat Account 时的平台稳定 issuer 回退值。
+   */
+  protected getAccessIssuerFallback(): string {
+    return "";
+  }
+
+  /**
+   * 格式化 Chat Access 中需要原样展示的值。
+   *
+   * 说明（中文）
+   * - 默认返回纯文本，避免通用层绑定具体平台的富文本语法。
+   * - 支持富文本的平台可覆写此方法，确保标识符和命令可被准确展示、复制。
+   */
+  protected format_access_code(value: string): string {
+    return value;
+  }
+
+  /**
+   * 格式化 Chat Access 管理命令。
+   *
+   * 说明（中文）
+   * - 默认复用平台的原样值格式，避免通用层引入具体富文本语法。
+   * - 平台可单独覆写为块级代码，改善长命令的阅读和复制体验。
+   */
+  protected format_access_command(command: string): string {
+    return this.format_access_code(command);
+  }
+
   protected sendActionToPlatform?(
     params: ChannelSendActionParams,
   ): Promise<void>;
 
   /**
-   * 发送授权提示文本。
+   * 发送 Chat Access 提示文本。
    *
    * 关键点（中文）
    * - 一律按普通消息发送，不挂 reply，避免把“权限提示”误挂到某条消息下面。
    */
-  protected async sendAuthorizationText(params: {
+  protected async sendAccessText(params: {
     chatId: string;
     text: string;
     chatType?: string;
     messageThreadId?: number;
   }): Promise<void> {
+    const notice_key = `${params.chatId}:${params.text}`;
+    const current_time = Date.now();
+    const last_sent_at = this.access_notice_sent_at.get(notice_key) || 0;
+    if (current_time - last_sent_at < 60_000) return;
+    if (this.access_notice_sent_at.size >= 1_000) this.access_notice_sent_at.clear();
+    this.access_notice_sent_at.set(notice_key, current_time);
     await this.sendTextToPlatform({
       chatId: params.chatId,
       text: params.text,
@@ -186,83 +220,55 @@ export abstract class BaseChatChannel {
   }
 
   /**
-   * 记录入站观测主体。
+   * 执行入站 Chat Access 判定。
    */
-  protected async observeIncomingAuthorization(
-    params: IncomingAuthorizationParams,
-  ): Promise<void> {
-    await observeIncomingChatPrincipal({
-      context: this.context,
+  protected async evaluateIncomingAccess(
+    params: IncomingChatAccessParams,
+  ): Promise<IncomingChatAccessResult> {
+    const issuer =
+      resolve_chat_access_issuer(this.context, this.channel) ||
+      String(this.getAccessIssuerFallback() || "").trim();
+    return create_chat_access_service(this.context).evaluate({
       channel: this.channel,
-      chatId: params.chatId,
-      chatType: params.chatType,
-      chatTitle: params.chatTitle,
-      userId: params.userId,
-      username: params.username,
+      issuer,
+      subject_id: String(params.userId || "").trim(),
+      display_name: String(params.username || "").trim() || undefined,
+      chat_id: String(params.chatId || "").trim(),
+      chat_type: String(params.chatType || "").trim() || undefined,
+      chat_title: String(params.chatTitle || "").trim() || undefined,
     });
   }
 
   /**
-   * 执行入站授权判定。
+   * 生成 Chat Access 拒绝提示文案。
    */
-  protected async evaluateIncomingAuthorization(
-    params: IncomingAuthorizationParams,
-  ): Promise<IncomingAuthorizationResult> {
-    try {
-      await guardIncomingChat({
-        context: this.context,
-        channel: this.channel,
-        input: {
-          channel: this.channel,
-          chatId: params.chatId,
-          chatType: params.chatType,
-          userId: params.userId,
-          username: params.username,
-          chatTitle: params.chatTitle,
-        },
-      });
-      return {
-        decision: "allow",
-        reason: "allow",
-      };
-    } catch (error) {
-      return {
-        decision: "block",
-        reason: String(error || "blocked"),
-      };
-    }
-  }
-
-  /**
-   * 生成未授权提示文案。
-   */
-  protected buildUnauthorizedBlockedText(params?: {
-    userId?: string;
-    chatId?: string;
-    chatType?: string;
+  protected buildAccessBlockedText(params: {
+    result: IncomingChatAccessResult;
   }): string {
-    const userId = String(params?.userId || "").trim();
-    const chatId = String(params?.chatId || "").trim();
-    const chatType = String(params?.chatType || "").trim();
-    const lines = [
-      "当前会话权限不足，已拒绝处理。请联系管理员调整你的角色。",
-    ];
-
-    if (userId) {
-      lines.push(
-        "",
-        "请把下面命令发给管理员：",
-        `downcity chat auth set ${this.channel}:${userId}`,
-      );
+    const agent_id = String(this.context.config.id || "agent").trim() || "agent";
+    const displayed_agent_id = this.format_access_code(agent_id);
+    if (params.result.reason === "identity_missing") {
+      return "当前平台身份无法识别，请联系管理员检查 Chat 账号配置。";
     }
-
-    if (chatId || chatType) {
-      lines.push("", "来源信息：");
-      if (chatId) lines.push(`chatId: ${chatId}`);
-      if (chatType) lines.push(`chatType: ${chatType}`);
+    if (params.result.reason === "grant_denied") {
+      return `当前账号未获准访问 Agent "${displayed_agent_id}"。`;
     }
-
-    return lines.join("\n");
+    const request_id = String(params.result.request_id || "").trim();
+    if (!request_id) {
+      return `当前账号尚未获准访问 Agent "${displayed_agent_id}"。`;
+    }
+    const displayed_request_id = this.format_access_code(request_id);
+    const approval_command = this.format_access_command(
+      `downcity chat access approve ${request_id} --agent ${agent_id}`,
+    );
+    return [
+      `当前账号尚未获准访问 Agent "${displayed_agent_id}"。`,
+      "",
+      `访问请求：${displayed_request_id}`,
+      "",
+      "请将下面命令发送给管理员：",
+      approval_command,
+    ].join("\n");
   }
 
   /**

package/src/chat/channels/BaseChatChannelQueue.ts

@@ -3,13 +3,12 @@
  *
  * 关键点（中文）
  * - audit / exec 入队都需要走同一套 prepare + emit 流程。
- * - 这些逻辑抽离后，`BaseChatChannel` 只负责渠道层输入整理与授权判断。
+ * - 这些逻辑抽离后，`BaseChatChannel` 只负责渠道层输入整理与 Chat Access 判断。
  */
 
 import { resolveChatQueueStore } from "@/chat/runtime/ChatQueue.js";
 import { buildQueuedUserMessageWithInfo } from "@/chat/runtime/QueuedUserMessage.js";
 import { appendExecIngress } from "@/chat/runtime/ChatIngressStore.js";
-import { resolveIncomingChatUserRole } from "@/chat/runtime/PluginDispatch.js";
 import {
   emitChatEnqueueEffect,
   prepareChatEnqueue,
@@ -190,18 +189,9 @@ export async function enqueueExecChannelMessage(
   params: EnqueueExecChannelMessageParams,
 ): Promise<{ chatKey: string; position: number }> {
   const msg = params.message;
-  const userRole = await resolveIncomingChatUserRole({
-    context: params.context,
-    channel: params.channel,
-    userId: msg.userId,
-  });
   const inboundExtra =
     msg.extra && typeof msg.extra === "object" ? stripUndefinedMeta(msg.extra) : {};
-  const mergedExtra: JsonObject = {
-    ...inboundExtra,
-    roleId: userRole?.roleId || "unknown",
-    permissions: userRole?.permissions || [],
-  };
+  const mergedExtra: JsonObject = { ...inboundExtra };
 
   const chatKey = await resolveOrCreateChannelSessionId({
     context: params.context,
@@ -218,8 +208,6 @@ export async function enqueueExecChannelMessage(
     messageId: msg.messageId,
     userId: msg.userId,
     username: msg.username,
-    roleId: userRole?.roleId,
-    permissions: userRole?.permissions,
     receivedAt: msg.receivedAt,
     userTimezone: msg.userTimezone,
     text: msg.text,

package/src/chat/channels/Configuration.ts

@@ -3,7 +3,7 @@
  *
  * 关键点（中文）
  * - 每个 channel 继承该基类，集中声明自己的配置字段。
- * - 统一提供“可写 ship 字段”提取逻辑，避免在 service 中重复硬编码。
+ * - 统一提供“可写 Agent 配置字段”提取逻辑，避免在 service 中重复硬编码。
  */
 
 import type {
@@ -29,7 +29,7 @@ export abstract class ChatChannelConfiguration {
   /**
    * 返回可通过 `chat.configure` 更新的运行态字段定义。
    */
-  getWritableShipFields(): ChatChannelConfigurationField[] {
-    return this.describe().fields.ship.filter((field) => field.writable);
+  get_writable_agent_config_fields(): ChatChannelConfigurationField[] {
+    return this.describe().fields.agent_config.filter((field) => field.writable);
   }
 }

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

@@ -28,14 +28,14 @@ export class FeishuChannelConfiguration extends ChatChannelConfiguration {
         canConfigure: true,
       },
       fields: {
-        ship: [
+        agent_config: [
           {
             key: "enabled",
             label: "Enabled",
             description:
               "Whether feishu 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 FeishuChannelConfiguration 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/feishu/Feishu.ts

@@ -81,6 +81,11 @@ export class FeishuBot extends BaseChatChannel {
     return this.buildChatKey(params.chatId);
   }
 
+  /** SDK 直连时使用飞书 App ID 作为 issuer。 */
+  protected getAccessIssuerFallback(): string {
+    return String(this.appId || "").trim();
+  }
+
   protected async sendTextToPlatform(
     params: ChannelSendTextParams,
   ): Promise<void> {
@@ -209,16 +214,13 @@ export class FeishuBot extends BaseChatChannel {
       rememberChat: (threadId, value) => {
         this.knownChats.set(threadId, value);
       },
-      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),
       runInChat: async (chatKey, fn) => {
         await this.runInChat(chatKey, fn);
       },

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

@@ -2,7 +2,7 @@
  * Feishu 入站消息处理器。
  *
  * 关键点（中文）
- * - 负责单条飞书消息的去重、解析、授权、附件保存与执行入队。
+ * - 负责单条飞书消息的去重、解析、Chat Access、附件保存与执行入队。
  * - 不持有 `FeishuBot` 实例；所有副作用通过显式依赖注入。
  * - 解析失败/执行失败通过渠道门面提供的发送函数回写错误消息。
  */
@@ -11,8 +11,8 @@ import path from "path";
 import type { Logger } from "@downcity/agent";
 import type { AgentContext } from "@downcity/agent";
 import type {
-  IncomingAuthorizationParams,
-  IncomingAuthorizationResult,
+  IncomingChatAccessParams,
+  IncomingChatAccessResult,
 } from "@/chat/channels/BaseChatChannel.js";
 import type { JsonObject } from "@downcity/agent";
 import type { InboundReplyContext } from "@/chat/types/ReplyContext.js";
@@ -109,34 +109,22 @@ export interface FeishuMessageHandlerOptions {
     threadId: string,
     value: { chatId: string; chatType: string; chatTitle?: string },
   ): void;
+  /** 入站 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;
   }): Promise<void>;
   /**
-   * 构建授权失败提示文案。
+   * 构建 Chat Access 失败提示文案。
    */
-  buildUnauthorizedBlockedText(params?: {
-    userId?: string;
-    chatId?: string;
-    chatType?: string;
-  }): string;
+  buildAccessBlockedText(params: { result: IncomingChatAccessResult }): string;
   /**
    * 按 chatKey 串行执行。
    */
@@ -337,7 +325,7 @@ async function parseIncomingMessage(params: {
 }
 
 /**
- * 授权后处理消息内容。
+ * Chat Access 通过后处理消息内容。
  */
 async function handleAuthorizedMessage(params: {
   options: FeishuMessageHandlerOptions;
@@ -374,31 +362,19 @@ async function handleAuthorizedMessage(params: {
   const resolvedChatTitle = await options.resolveChatTitle(chatId);
   const chatTitle = resolvedChatTitle || (chatType === "p2p" ? actorName : undefined);
 
-  await options.observeIncomingAuthorization({
-    chatId,
-    chatType,
-    chatTitle,
-    userId: actorId,
-    username: actorName,
-  });
-
-  const authResult = await options.evaluateIncomingAuthorization({
+  const access_result = await options.evaluateIncomingAccess({
     chatId,
     chatType,
     chatTitle,
     userId: actorId,
     username: actorName,
   });
-  if (authResult.decision !== "allow") {
+  if (!access_result.allowed) {
     if (chatType === "p2p") {
-      await options.sendAuthorizationText({
+      await options.sendAccessText({
         chatId,
         chatType,
-        text: options.buildUnauthorizedBlockedText({
-          chatId,
-          chatType,
-          userId: actorId,
-        }),
+        text: options.buildAccessBlockedText({ result: access_result }),
       });
     }
     return true;

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

@@ -28,13 +28,13 @@ export class QqChannelConfiguration extends ChatChannelConfiguration {
         canConfigure: true,
       },
       fields: {
-        ship: [
+        agent_config: [
           {
             key: "enabled",
             label: "Enabled",
             description: "Whether qq channel should be started by runtime.",
             type: "boolean",
-            source: "ship_json",
+            source: "agent_config",
             required: false,
             nullable: false,
             writable: true,
@@ -46,9 +46,9 @@ export class QqChannelConfiguration 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/qq/QQ.ts

@@ -82,6 +82,11 @@ export class QQBot extends BaseChatChannel {
     return `qq-${chatType}-${params.chatId}`;
   }
 
+  /** SDK 直连时使用 QQ App ID 作为 issuer。 */
+  protected getAccessIssuerFallback(): string {
+    return String(this.appId || "").trim();
+  }
+
   protected async sendTextToPlatform(
     params: ChannelSendTextParams,
   ): Promise<void> {
@@ -266,16 +271,13 @@ export class QQBot extends BaseChatChannel {
       logger: this.logger,
       getBotUserId: () => this.botUserId,
       getChatKey: (params) => this.getChatKey(params),
-      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),
       shouldSkipDuplicatedInboundMessage: async (eventType, messageId) =>
         await this.shouldSkipDuplicatedInboundMessage(eventType, messageId),
       enqueueAuditMessage: async (params) => {

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

@@ -2,7 +2,7 @@
  * QQ 入站消息处理器。
  *
  * 关键点（中文）
- * - 负责 group / c2c / channel 三类入站消息的授权、去重、审计与执行入队。
+ * - 负责 group / c2c / channel 三类入站消息的 Chat Access、去重、审计与执行入队。
  * - 不直接持有 `QQBot` 实例；所有副作用通过显式函数注入。
  * - `QQBot` 因此只保留渠道生命周期、dispatch 分流、发送与命令处理。
  */
@@ -11,8 +11,8 @@ import type { Logger } from "@downcity/agent";
 import type { AgentContext } from "@downcity/agent";
 import type {
   ChannelChatKeyParams,
-  IncomingAuthorizationParams,
-  IncomingAuthorizationResult,
+  IncomingChatAccessParams,
+  IncomingChatAccessResult,
 } from "@/chat/channels/BaseChatChannel.js";
 import type { ChannelUserMessageMeta } from "@/chat/channels/BaseChatChannelSupport.js";
 import {
@@ -69,34 +69,22 @@ export interface QQMessageHandlerOptions {
    * 计算 channel chatKey。
    */
   getChatKey(params: ChannelChatKeyParams): string;
+  /** 入站 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;
   }): Promise<void>;
   /**
-   * 构建授权失败提示文案。
+   * 构建 Chat Access 失败提示文案。
    */
-  buildUnauthorizedBlockedText(params?: {
-    userId?: string;
-    chatId?: string;
-    chatType?: string;
-  }): string;
+  buildAccessBlockedText(params: { result: IncomingChatAccessResult }): string;
   /**
    * 入站去重判断。
    */
@@ -234,22 +222,14 @@ export async function handleQqChannelMessage(
     actorName: actor.username,
   });
 
-  await options.observeIncomingAuthorization({
-    chatId: channelId,
-    chatType,
-    chatTitle,
-    userId: actor.userId,
-    username: actor.username,
-  });
-
-  const authResult = await options.evaluateIncomingAuthorization({
+  const access_result = await options.evaluateIncomingAccess({
     chatId: channelId,
     chatType,
     chatTitle,
     userId: actor.userId,
     username: actor.username,
   });
-  if (authResult.decision !== "allow") return;
+  if (!access_result.allowed) return;
 
   const botUserId = options.getBotUserId();
   if (actor.userId && botUserId && actor.userId === botUserId) {
@@ -347,31 +327,19 @@ async function handleQqInboundMessage(
     ? stripQqBotMention(rawContent, botUserId)
     : extractQqTextContent(rawContent);
 
-  await options.observeIncomingAuthorization({
-    chatId,
-    chatType,
-    chatTitle,
-    userId: actor.userId,
-    username: actor.username,
-  });
-
-  const authResult = await options.evaluateIncomingAuthorization({
+  const access_result = await options.evaluateIncomingAccess({
     chatId,
     chatType,
     chatTitle,
     userId: actor.userId,
     username: actor.username,
   });
-  if (authResult.decision !== "allow") {
+  if (!access_result.allowed) {
     if (!isGroup) {
-      await options.sendAuthorizationText({
+      await options.sendAccessText({
         chatId,
         chatType,
-        text: options.buildUnauthorizedBlockedText({
-          chatId,
-          chatType,
-          userId: actor.userId,
-        }),
+        text: options.buildAccessBlockedText({ result: access_result }),
       });
     }
     return;