@downcity/plugins 1.0.153 → 1.0.156

package/src/chat/access/ChatAccessStore.ts

@@ -0,0 +1,462 @@
+/**
+ * Chat Access SQLite Store。
+ *
+ * 关键点（中文）
+ * - 该 Store 是当前 Agent Chat Access 的唯一持久化入口。
+ * - 所有字段先归一化再写入，避免平台适配器差异污染查询键。
+ * - Service 负责业务编排，Store 只负责结构化读写和事务。
+ */
+
+import Database from "better-sqlite3";
+import fs from "fs-extra";
+import path from "node:path";
+import { generateId } from "@downcity/agent";
+import { ensure_chat_access_schema } from "@/chat/access/ChatAccessSchema.js";
+import type {
+  ChatAccessEffect,
+  ChatAccessGrant,
+  ChatAccessPrincipal,
+  ChatAccessPrincipalView,
+  ChatAccessRequest,
+  ChatAccessRequestStatus,
+  ChatAccessRequestView,
+  ChatAccessScope,
+  CreateChatAccessRequestInput,
+  CreateChatAccessRequestResult,
+  InsertChatAccessAuditEventInput,
+  ResolveChatAccessRequestStoreInput,
+  ResolvePendingChatAccessRequestsInput,
+  UpsertChatAccessGrantInput,
+  UpsertChatAccessPrincipalInput,
+} from "@/chat/types/ChatAccess.js";
+import type { ChatDispatchChannel } from "@/chat/types/ChatDispatcher.js";
+
+type SqlRow = Record<string, unknown>;
+
+/**
+ * 返回项目级 Chat Access 数据库路径。
+ */
+export function get_chat_access_db_path(project_root: string): string {
+  return path.join(path.resolve(project_root), ".downcity", "chat", "access.db");
+}
+
+function normalize_text(value: unknown): string {
+  return String(value || "").trim();
+}
+
+function optional_text(value: unknown): string | undefined {
+  const text = normalize_text(value);
+  return text || undefined;
+}
+
+function now_iso(): string {
+  return new Date().toISOString();
+}
+
+function to_principal(row: SqlRow | undefined): ChatAccessPrincipal | null {
+  if (!row) return null;
+  const principal_id = normalize_text(row.principal_id);
+  const channel = normalize_text(row.channel) as ChatDispatchChannel;
+  const issuer = normalize_text(row.issuer);
+  const subject_id = normalize_text(row.subject_id);
+  if (!principal_id || !channel || !issuer || !subject_id) return null;
+  return {
+    principal_id,
+    channel,
+    issuer,
+    subject_id,
+    ...(optional_text(row.display_name)
+      ? { display_name: optional_text(row.display_name) }
+      : {}),
+    first_seen_at: normalize_text(row.first_seen_at),
+    last_seen_at: normalize_text(row.last_seen_at),
+    ...(optional_text(row.last_chat_id)
+      ? { last_chat_id: optional_text(row.last_chat_id) }
+      : {}),
+    ...(optional_text(row.last_chat_type)
+      ? { last_chat_type: optional_text(row.last_chat_type) }
+      : {}),
+  };
+}
+
+function to_grant(row: SqlRow | undefined): ChatAccessGrant | null {
+  if (!row) return null;
+  const grant_id = normalize_text(row.grant_id);
+  const principal_id = normalize_text(row.principal_id);
+  const scope = normalize_text(row.scope) as ChatAccessScope;
+  const effect = normalize_text(row.effect) as ChatAccessEffect;
+  if (!grant_id || !principal_id || !scope || !effect) return null;
+  return {
+    grant_id,
+    principal_id,
+    scope,
+    effect,
+    created_by: normalize_text(row.created_by),
+    created_at: normalize_text(row.created_at),
+    updated_at: normalize_text(row.updated_at),
+  };
+}
+
+function to_request(row: SqlRow | undefined): ChatAccessRequest | null {
+  if (!row) return null;
+  const request_id = normalize_text(row.request_id);
+  const principal_id = normalize_text(row.principal_id);
+  const scope = normalize_text(row.scope) as ChatAccessScope;
+  const status = normalize_text(row.status) as ChatAccessRequestStatus;
+  if (!request_id || !principal_id || !scope || !status) return null;
+  return {
+    request_id,
+    principal_id,
+    scope,
+    chat_id: normalize_text(row.chat_id),
+    chat_type: normalize_text(row.chat_type),
+    status,
+    ...(optional_text(row.resolved_by)
+      ? { resolved_by: optional_text(row.resolved_by) }
+      : {}),
+    created_at: normalize_text(row.created_at),
+    last_requested_at: normalize_text(row.last_requested_at),
+    ...(optional_text(row.resolved_at)
+      ? { resolved_at: optional_text(row.resolved_at) }
+      : {}),
+  };
+}
+
+/**
+ * 当前 Agent 的 Chat Access SQLite Store。
+ */
+export class ChatAccessStore {
+  private readonly database: Database.Database;
+
+  /**
+   * 打开当前项目 Chat Access 数据库。
+   */
+  constructor(project_root: string) {
+    const database_path = get_chat_access_db_path(project_root);
+    fs.ensureDirSync(path.dirname(database_path), { mode: 0o700 });
+    this.database = new Database(database_path);
+    ensure_chat_access_schema(this.database);
+    try {
+      fs.chmodSync(database_path, 0o600);
+    } catch {
+      // 某些平台不支持 POSIX 权限，SQLite 仍可正常工作。
+    }
+  }
+
+  /** 关闭数据库连接。 */
+  close(): void {
+    this.database.close();
+  }
+
+  /** 在单个 SQLite 事务中执行操作。 */
+  transaction<T>(operation: () => T): T {
+    return this.database.transaction(operation)();
+  }
+
+  /** 读取 Store 元信息。 */
+  get_meta(key: string): string | null {
+    const row = this.database
+      .prepare("SELECT value FROM chat_access_meta WHERE key = ? LIMIT 1")
+      .get(normalize_text(key)) as SqlRow | undefined;
+    return row ? normalize_text(row.value) : null;
+  }
+
+  /** 写入 Store 元信息。 */
+  set_meta(key: string, value: string): void {
+    const current_time = now_iso();
+    this.database.prepare(`
+      INSERT INTO chat_access_meta (key, value, updated_at)
+      VALUES (?, ?, ?)
+      ON CONFLICT(key) DO UPDATE SET
+        value = excluded.value,
+        updated_at = excluded.updated_at
+    `).run(normalize_text(key), normalize_text(value), current_time);
+  }
+
+  /** 判断是否已经存在业务数据。 */
+  has_access_data(): boolean {
+    const row = this.database.prepare(`
+      SELECT
+        (SELECT COUNT(*) FROM chat_access_principals) +
+        (SELECT COUNT(*) FROM chat_access_grants) +
+        (SELECT COUNT(*) FROM chat_access_requests) AS total
+    `).get() as { total?: unknown } | undefined;
+    return Number(row?.total || 0) > 0;
+  }
+
+  /** 读取指定平台身份对应主体。 */
+  get_principal_by_identity(input: {
+    channel: ChatDispatchChannel;
+    issuer: string;
+    subject_id: string;
+  }): ChatAccessPrincipal | null {
+    const row = this.database.prepare(`
+      SELECT * FROM chat_access_principals
+      WHERE channel = ? AND issuer = ? AND subject_id = ?
+      LIMIT 1
+    `).get(
+      input.channel,
+      normalize_text(input.issuer),
+      normalize_text(input.subject_id),
+    ) as SqlRow | undefined;
+    return to_principal(row);
+  }
+
+  /** 按 Principal ID 读取主体。 */
+  get_principal(principal_id: string): ChatAccessPrincipal | null {
+    const row = this.database.prepare(`
+      SELECT * FROM chat_access_principals
+      WHERE principal_id = ?
+      LIMIT 1
+    `).get(normalize_text(principal_id)) as SqlRow | undefined;
+    return to_principal(row);
+  }
+
+  /** 新增或更新观测主体。 */
+  upsert_principal(input: UpsertChatAccessPrincipalInput): ChatAccessPrincipal {
+    const existing = this.get_principal_by_identity(input);
+    const current_time = now_iso();
+    const principal_id = existing?.principal_id || `principal_${generateId()}`;
+    const first_seen_at = normalize_text(input.first_seen_at) || existing?.first_seen_at || current_time;
+    const last_seen_at = normalize_text(input.last_seen_at) || current_time;
+    this.database.prepare(`
+      INSERT INTO chat_access_principals (
+        principal_id, channel, issuer, subject_id, display_name,
+        first_seen_at, last_seen_at, last_chat_id, last_chat_type
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT(channel, issuer, subject_id) DO UPDATE SET
+        display_name = COALESCE(excluded.display_name, chat_access_principals.display_name),
+        last_seen_at = excluded.last_seen_at,
+        last_chat_id = COALESCE(excluded.last_chat_id, chat_access_principals.last_chat_id),
+        last_chat_type = COALESCE(excluded.last_chat_type, chat_access_principals.last_chat_type)
+    `).run(
+      principal_id,
+      input.channel,
+      normalize_text(input.issuer),
+      normalize_text(input.subject_id),
+      optional_text(input.display_name) || null,
+      first_seen_at,
+      last_seen_at,
+      optional_text(input.chat_id) || null,
+      optional_text(input.chat_type) || null,
+    );
+    const principal = this.get_principal_by_identity(input);
+    if (!principal) throw new Error("Failed to persist Chat Access principal");
+    return principal;
+  }
+
+  /** 读取指定主体和范围的 Grant。 */
+  get_grant(principal_id: string, scope: ChatAccessScope): ChatAccessGrant | null {
+    const row = this.database.prepare(`
+      SELECT * FROM chat_access_grants
+      WHERE principal_id = ? AND scope = ?
+      LIMIT 1
+    `).get(normalize_text(principal_id), scope) as SqlRow | undefined;
+    return to_grant(row);
+  }
+
+  /** 新增或更新 Grant。 */
+  upsert_grant(input: UpsertChatAccessGrantInput): ChatAccessGrant {
+    const existing = this.get_grant(input.principal_id, input.scope);
+    const current_time = now_iso();
+    const grant_id = existing?.grant_id || `grant_${generateId()}`;
+    this.database.prepare(`
+      INSERT INTO chat_access_grants (
+        grant_id, principal_id, scope, effect, created_by, created_at, updated_at
+      ) VALUES (?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT(principal_id, scope) DO UPDATE SET
+        effect = excluded.effect,
+        created_by = excluded.created_by,
+        updated_at = excluded.updated_at
+    `).run(
+      grant_id,
+      normalize_text(input.principal_id),
+      input.scope,
+      input.effect,
+      normalize_text(input.operator) || "unknown",
+      existing?.created_at || current_time,
+      current_time,
+    );
+    const grant = this.get_grant(input.principal_id, input.scope);
+    if (!grant) throw new Error("Failed to persist Chat Access grant");
+    return grant;
+  }
+
+  /** 删除指定主体和范围的 Grant。 */
+  delete_grant(principal_id: string, scope: ChatAccessScope): boolean {
+    const result = this.database.prepare(`
+      DELETE FROM chat_access_grants
+      WHERE principal_id = ? AND scope = ?
+    `).run(normalize_text(principal_id), scope);
+    return result.changes > 0;
+  }
+
+  /** 读取指定主体全部 Grant。 */
+  list_grants(principal_id: string): ChatAccessGrant[] {
+    const rows = this.database.prepare(`
+      SELECT * FROM chat_access_grants
+      WHERE principal_id = ?
+      ORDER BY scope ASC
+    `).all(normalize_text(principal_id)) as SqlRow[];
+    return rows.map((row) => to_grant(row)).filter((item): item is ChatAccessGrant => !!item);
+  }
+
+  /** 读取 Request。 */
+  get_request(request_id: string): ChatAccessRequest | null {
+    const row = this.database.prepare(`
+      SELECT * FROM chat_access_requests
+      WHERE request_id = ?
+      LIMIT 1
+    `).get(normalize_text(request_id)) as SqlRow | undefined;
+    return to_request(row);
+  }
+
+  /** 创建或复用 pending Request。 */
+  create_or_touch_request(input: CreateChatAccessRequestInput): CreateChatAccessRequestResult {
+    const pending_row = this.database.prepare(`
+      SELECT * FROM chat_access_requests
+      WHERE principal_id = ? AND scope = ? AND status = 'pending'
+      LIMIT 1
+    `).get(normalize_text(input.principal_id), input.scope) as SqlRow | undefined;
+    const pending = to_request(pending_row);
+    const current_time = now_iso();
+    if (pending) {
+      this.database.prepare(`
+        UPDATE chat_access_requests
+        SET chat_id = ?, chat_type = ?, last_requested_at = ?
+        WHERE request_id = ?
+      `).run(
+        normalize_text(input.chat_id),
+        normalize_text(input.chat_type),
+        current_time,
+        pending.request_id,
+      );
+      const updated = this.get_request(pending.request_id);
+      if (!updated) throw new Error("Failed to update Chat Access request");
+      return { request: updated, created: false };
+    }
+
+    const request_id = `req_${generateId()}`;
+    this.database.prepare(`
+      INSERT INTO chat_access_requests (
+        request_id, principal_id, scope, chat_id, chat_type, status,
+        created_at, last_requested_at
+      ) VALUES (?, ?, ?, ?, ?, 'pending', ?, ?)
+    `).run(
+      request_id,
+      normalize_text(input.principal_id),
+      input.scope,
+      normalize_text(input.chat_id),
+      normalize_text(input.chat_type),
+      current_time,
+      current_time,
+    );
+    const request = this.get_request(request_id);
+    if (!request) throw new Error("Failed to create Chat Access request");
+    return { request, created: true };
+  }
+
+  /** 解决指定 Request。 */
+  resolve_request(input: ResolveChatAccessRequestStoreInput): ChatAccessRequest {
+    const current_time = now_iso();
+    const result = this.database.prepare(`
+      UPDATE chat_access_requests
+      SET status = ?, resolved_by = ?, resolved_at = ?, last_requested_at = ?
+      WHERE request_id = ? AND status = 'pending'
+    `).run(
+      input.status,
+      normalize_text(input.operator) || "unknown",
+      current_time,
+      current_time,
+      normalize_text(input.request_id),
+    );
+    if (result.changes === 0) {
+      throw new Error(`Pending Chat Access request not found: ${input.request_id}`);
+    }
+    const request = this.get_request(input.request_id);
+    if (!request) throw new Error(`Chat Access request not found: ${input.request_id}`);
+    return request;
+  }
+
+  /** 解决指定主体和范围内的全部 pending Request。 */
+  resolve_pending_requests(input: ResolvePendingChatAccessRequestsInput): void {
+    if (input.scopes.length === 0) return;
+    const current_time = now_iso();
+    const placeholders = input.scopes.map(() => "?").join(", ");
+    this.database.prepare(`
+      UPDATE chat_access_requests
+      SET status = ?, resolved_by = ?, resolved_at = ?, last_requested_at = ?
+      WHERE principal_id = ?
+        AND status = 'pending'
+        AND scope IN (${placeholders})
+    `).run(
+      input.status,
+      normalize_text(input.operator) || "unknown",
+      current_time,
+      current_time,
+      normalize_text(input.principal_id),
+      ...input.scopes,
+    );
+  }
+
+  /** 列出 Request 及主体详情。 */
+  list_requests(status?: ChatAccessRequestStatus): ChatAccessRequestView[] {
+    const rows = status
+      ? this.database.prepare(`
+          SELECT * FROM chat_access_requests
+          WHERE status = ?
+          ORDER BY last_requested_at DESC
+        `).all(status) as SqlRow[]
+      : this.database.prepare(`
+          SELECT * FROM chat_access_requests
+          ORDER BY last_requested_at DESC
+        `).all() as SqlRow[];
+    const views: ChatAccessRequestView[] = [];
+    for (const row of rows) {
+      const request = to_request(row);
+      if (!request) continue;
+      const principal = this.get_principal(request.principal_id);
+      if (!principal) continue;
+      views.push({ ...request, principal });
+    }
+    return views;
+  }
+
+  /** 列出所有主体和 Grant。 */
+  list_principals(): ChatAccessPrincipalView[] {
+    const rows = this.database.prepare(`
+      SELECT * FROM chat_access_principals
+      ORDER BY last_seen_at DESC
+    `).all() as SqlRow[];
+    const views: ChatAccessPrincipalView[] = [];
+    for (const row of rows) {
+      const principal = to_principal(row);
+      if (!principal) continue;
+      views.push({
+        principal,
+        grants: this.list_grants(principal.principal_id),
+      });
+    }
+    return views;
+  }
+
+  /** 写入审计事件。 */
+  insert_audit_event(input: InsertChatAccessAuditEventInput): void {
+    this.database.prepare(`
+      INSERT INTO chat_access_audit_events (
+        event_id, principal_id, request_id, action, scope,
+        decision, operator, detail_json, created_at
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `).run(
+      `audit_${generateId()}`,
+      optional_text(input.principal_id) || null,
+      optional_text(input.request_id) || null,
+      normalize_text(input.action),
+      input.scope || null,
+      optional_text(input.decision) || null,
+      optional_text(input.operator) || null,
+      input.detail ? JSON.stringify(input.detail) : null,
+      now_iso(),
+    );
+  }
+}

package/src/chat/accounts/Crypto.ts

@@ -3,7 +3,7 @@
  *
  * 职责说明（中文）
  * - 负责默认 chat account 存储中的敏感字段加解密。
- * - 默认复用平台级 `model-db.key`，保证和现有 `~/.downcity/downcity.db` 数据兼容。
+ * - 复用 `DC_PLATFORM_ROOT` 下的平台级 `model-db.key`。
  *
  * 边界说明（中文）
  * - 这里只处理“字符串 <-> 密文”的转换，不负责数据库读写。

package/src/chat/accounts/Store.ts

@@ -3,7 +3,7 @@
  *
  * 职责说明（中文）
  * - 提供 `chat` plugin 默认使用的全局 chat account 读写能力。
- * - 默认直接操作 `~/.downcity/downcity.db` 里的 `channel_accounts` 表。
+ * - 直接操作 `DC_PLATFORM_ROOT` 下 `downcity.db` 的 `channel_accounts` 表。
  * - 对 `city` 而言，这里也是统一的默认账号池实现来源。
  *
  * 边界说明（中文）

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,35 @@ export abstract class BaseChatChannel {
     params: ChannelSendTextParams,
   ): Promise<void>;
 
+  /**
+   * SDK 未绑定 City Chat Account 时的平台稳定 issuer 回退值。
+   */
+  protected getAccessIssuerFallback(): string {
+    return "";
+  }
+
   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 +198,50 @@ 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";
+    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 "${agent_id}"。`;
     }
-
-    return lines.join("\n");
+    const request_id = String(params.result.request_id || "").trim();
+    if (!request_id) {
+      return `当前账号尚未获准访问 Agent "${agent_id}"。`;
+    }
+    return [
+      `当前账号尚未获准访问 Agent "${agent_id}"。`,
+      "",
+      `访问请求：${request_id}`,
+      "",
+      "请将下面命令发送给管理员：",
+      `downcity chat access approve ${request_id} --agent ${agent_id}`,
+    ].join("\n");
   }
 
   /**