@modesto_ma/dsh-channels 0.3.0 → 0.5.0-beta.1

package/src/service.ts

@@ -18,11 +18,10 @@
  * @module dsh-channels/service
  */
 
-import { lstat, readdir, realpath, rm } from 'node:fs/promises'
-import path from 'node:path'
 import { AccessController } from './access/controller.ts'
 import { AccessRequests } from './access/requests.ts'
 import { AccessStore } from './access/store.ts'
+import { AUTH_USER_TARGET_ERRORS, resolveAuthUserTarget } from './access/targets.ts'
 import { ApprovalAnswerer } from './approvals.ts'
 import type { ApprovalRoute } from './approvals.ts'
 import { QuestionAnswerer } from './questions.ts'
@@ -33,14 +32,15 @@ import type {
   CredentialProvider,
   CordisFiber,
   HostContext,
+  LlmModelInfo,
   LlmService,
   Session,
   SessionId,
   SessionProjections,
   TokenMeter,
-  Workspace,
 } from './dsh-types.ts'
-import { standaloneInfoCard } from './cards.ts'
+import { buildPickerCard, parsePickAction, standaloneInfoCard, STOP_ACTION } from './cards.ts'
+import type { PickerOption } from './cards.ts'
 import {
   armEffortCommand, armModelCommand, armRenewCommand, registerModelCommand, commandResultCardKind, parseSlashCommand,
   registerEffortCommand, registerRenewCommand, RouteOperationQueue, supportedCommandHelp, supportedCommandList,
@@ -49,15 +49,11 @@ import type { EffortCommandAction, ParsedSlashCommand } from './commands.ts'
 import { commandSpec } from './commands/registry.ts'
 import type { ChannelCommandSpec } from './commands/registry.ts'
 import type { PermissionPresets, SessionQuery } from './dsh-types.ts'
-import { feishuDomain, sessionDirOf } from './domain.ts'
-import {
-  applyWorkspaceCleanup, isPathInside, planWorkspaceCleanup, retentionMs,
-} from './cleanup.ts'
-import type { CleanupDeps, CleanupRoute, CleanupTombstone, ScannedSessionDir, WorkspaceStats } from './cleanup.ts'
+import { FEISHU_USER_ID_PATTERN, feishuDomain, sessionDirOf } from './domain.ts'
 import type {
   AccessGroupRecord, AccessRequestRecord, AccessUserRecord,
-  ExpiredRouteRecord, FeishuDomainGlobal, FeishuDomainHandle, InflightSnapshot, ProcessedRecord, RawDomainHandle,
-  RouteRecord,
+  ExpiredRouteRecord, FeishuDomainGlobal, FeishuDomainHandle, InflightSnapshot,
+  ProcessedRecord, RawDomainHandle, RouteRecord,
 } from './domain.ts'
 import { RouteStore } from './session/routes.ts'
 import { InflightRepair } from './session/repair.ts'
@@ -65,9 +61,21 @@ import { SessionManager } from './session/manager.ts'
 import type { LiveAgent, RenewCommit } from './session/manager.ts'
 import { CardDelivery } from './feishu/delivery.ts'
 import { AttachmentIntake } from './feishu/inbound-attachments.ts'
+import { InboundAttachmentStore, effectiveAttachmentMode, resolveAttachmentService } from './feishu/native-attachments.ts'
+import { AttachmentFetchToolRuntime, TopicMessagesToolRuntime } from './feishu/tools.ts'
+import { SendFileToolRuntime } from './feishu/send-file.ts'
+import type { KnownAttachmentMessageInput, KnownAttachmentSource } from './feishu/tools.ts'
+import {
+  MessageReader, TOPIC_MESSAGES_MAX_LIMIT, buildHistoryContextBlock,
+  buildQuoteContextBlock, clampInt, knownMessageOfItems, knownMessagesOfHistory, quoteItemsOf,
+  readQuoteItems,
+} from './feishu/message-read.ts'
+import type { MessageReadRoute, RawMessageItem } from './feishu/message-read.ts'
+import type { AttachmentStore } from './host/attachments.ts'
 import { InboundRouter } from './routing/inbound.ts'
 import type { RequestPolicyController } from './session/request-policy.ts'
-import type { ChannelFactory, FeishuChannel, NormalizedMessage } from './feishu-channel.ts'
+import type { CardActionEvent, ChannelFactory, FeishuChannel, NormalizedMessage } from './feishu-channel.ts'
+import { AppOwnerLookupError, FeishuApiError } from './feishu-channel.ts'
 import { buildHealthCard, foldHealthSnapshot, HEALTH_DEPENDENCY_NAMES } from './health.ts'
 import type { HealthDependencyName, HealthSnapshot } from './health.ts'
 import {
@@ -84,10 +92,12 @@ import { ACTIVITY_BUILD_MARKER, TurnStreamer } from './streamer.ts'
 import type { ProjectedStats, StreamerHooks } from './streamer.ts'
 import type { FeishuConfig } from './config.ts'
 import type {
-  AccessMutationResponse, AccessRequestWire, AccessWire,
+  AccessMutationResponse, AccessRequestWire, AccessWire, ScopeCheckWire, SlashCommandSyncWire,
 } from './settings/contract.ts'
-import type { OverlayStore } from './settings/overlay.ts'
-import { legacyTopicWorkspaceRoot } from './workspaces.ts'
+import { checkScopes } from './feishu/scopes.ts'
+import { desiredSlashCommands, syncSlashCommands } from './feishu/slash-commands.ts'
+import { mergeOverlay } from './settings/overlay.ts'
+import type { OverlayPatch, OverlayStore } from './settings/overlay.ts'
 
 /** Periodic route-GC sweep cadence (a long-running instance also accumulates
  *  dead records; TTL semantics make 6 h granularity more than sufficient). */
@@ -96,9 +106,18 @@ const GC_SWEEP_INTERVAL_MS = 6 * 60 * 60 * 1000
 /** Dedup-record retention: Feishu redelivery windows are minutes-scale, so a
  *  day is 100×+ headroom while keeping the table bounded. */
 const PROCESSED_RETENTION_MS = 24 * 60 * 60 * 1000
+/** Upper bound on the boot-time app-owner lookup before the connection opens. */
+const APP_OWNER_LOOKUP_TIMEOUT_MS = 10_000
+/** Upper bound on the post-connect scope grant query. */
+const SCOPE_CHECK_TIMEOUT_MS = 10_000
+/** Upper bound on the whole post-connect slash-command panel sync (one list plus per-command writes). */
+const SLASH_COMMAND_SYNC_TIMEOUT_MS = 30_000
 
-/** Workspace-retention sweep cadence when automatic cleanup is enabled. */
-const RETENTION_SWEEP_INTERVAL_MS = 24 * 60 * 60 * 1000
+/** Outcome of the app-owner lookup for the current connection. */
+type AppOwnerState =
+  | { readonly userId: string }
+  /** `apiRejected`: Feishu answered with an error code (typically a missing app-info scope). */
+  | { readonly error: string; readonly apiRejected: boolean }
 
 
 interface RenewAdmission {
@@ -203,52 +222,6 @@ function messageOf(error: unknown): string {
   return error instanceof Error ? error.message : String(error)
 }
 
-/**
- * Measure one workspace directory for the cleanup preview: total regular-file
- * bytes and file count. Symlinks are never followed; unreadable entries are
- * skipped so a permission problem cannot fail the whole pass.
- */
-async function measureWorkspace(dir: string): Promise<WorkspaceStats | undefined> {
-  let info
-  try {
-    info = await lstat(dir)
-  } catch {
-    return undefined
-  }
-  if (!info.isDirectory()) return undefined
-  let bytes = 0
-  let files = 0
-  const pending = [dir]
-  while (pending.length > 0) {
-    const current = pending.pop()!
-    let entries
-    try {
-      entries = await readdir(current, { withFileTypes: true })
-    } catch {
-      continue
-    }
-    for (const entry of entries) {
-      const child = path.join(current, entry.name)
-      if (entry.isSymbolicLink()) continue
-      if (entry.isDirectory()) {
-        pending.push(child)
-        continue
-      }
-      if (!entry.isFile()) continue
-      try {
-        const stat = await lstat(child)
-        if (stat.isFile()) {
-          bytes += stat.size
-          files += 1
-        }
-      } catch {
-        // The directory changed while walking it; the byte total is advisory.
-      }
-    }
-  }
-  return { mtimeMs: info.mtimeMs, bytes, files }
-}
-
 export class FeishuService {
   private readonly ctx: HostContext
   /** Live config object. Mutated in place — collaborators captured this reference. */
@@ -270,10 +243,31 @@ export class FeishuService {
   private readonly delivery: CardDelivery
   /** Inbound attachment archival (Feishu resources → workspace files). */
   private readonly attachments: AttachmentIntake
+  /**
+   * Backend-selecting inbound storage facade. The native path stays lazy in
+   * admission (prefetch images + manifest); this facade owns the legacy
+   * workspace download used by `attachmentStore: 'archive'` and by the
+   * fallback when the host does not mount `ctx.attachments`.
+   */
+  private readonly inboundAttachmentStore: InboundAttachmentStore
+  /**
+   * Read-only Feishu message access (P2): the quoted-message excerpt and the
+   * first-turn topic history. Constructed before the inbound router so the
+   * turn assembly can reach it; it resolves the live channel lazily.
+   */
+  private readonly messageReader = new MessageReader({ channel: () => this.channel })
   /** Inbound routing: dedup, admission, decision tree, session establishment. */
   private readonly inbound: InboundRouter
   /** Agent/session lifecycle: live registry, resume, presets, renew. */
   private readonly sessions: SessionManager
+  /**
+   * Model-facing Feishu tools. `feishu_attachment_fetch` plus the shared
+   * per-route known-message whitelist the admission, quote and history layers
+   * populate; `feishu_topic_messages` reads the current topic on demand.
+   */
+  private readonly attachmentFetchTools: AttachmentFetchToolRuntime
+  private readonly topicMessagesTools: TopicMessagesToolRuntime
+  private readonly sendFileTools: SendFileToolRuntime
   /** FIFO admission for ordinary turns and commands targeting one route. */
   private readonly routeOperations = new RouteOperationQueue()
   /** Active Host command executions, aborted before shutdown tears peers down. */
@@ -298,15 +292,15 @@ export class FeishuService {
   private runningConfig: FeishuConfig | undefined
   /** Guards overlapping panel-triggered reconnects. */
   private restarting = false
+  /** One-shot warning for a native deployment without the host attachment library. */
+  private warnedNativeAttachmentsUnmounted = false
+  /** One-shot warning for silently degraded quote/history reads (missing scope). */
+  private warnedPromptReadDegraded = false
   private unlisten: (() => void) | undefined
   /** Disposers for host-scoped listeners registered by `start()`. */
   private readonly unlistenHost: Array<() => boolean> = []
   /** Periodic route-GC timer (unref'd; only armed when `routeTtlMs > 0`). */
   private gcTimer: ReturnType<typeof setInterval> | undefined
-  /** Periodic workspace-retention timer (only armed when auto cleanup is on). */
-  private retentionTimer: ReturnType<typeof setInterval> | undefined
-  /** Guards overlapping cleanup passes (panel button / daily timer). */
-  private cleanupRunning = false
   /** HITL approval answerer (created in `start()`). */
   private approvalAnswerer: ApprovalAnswerer | undefined
   /** HITL structured-question answerer (`ask_user_question`). */
@@ -323,6 +317,17 @@ export class FeishuService {
   /** Administrator DM authorization cards + bot-added group info cards. */
   private accessRequests: AccessRequests | undefined
   private unlistenBotAdded: (() => void) | undefined
+  /**
+   * App owner resolved at `start()`; the administrator whenever `adminUserId`
+   * is unset. Cleared on shutdown so a reconnect looks it up again.
+   */
+  private appOwner: AppOwnerState | undefined
+  /** Post-connect scope self-check; cleared on shutdown. */
+  private scopeCheckState: ScopeCheckWire | undefined
+  /** Post-connect slash-command panel sync; cleared on shutdown. */
+  private slashCommandSyncState: SlashCommandSyncWire | undefined
+  /** Aborts the running panel sync's remaining writes (timeout, shutdown, reconnect). */
+  private slashCommandSyncAbort: AbortController | undefined
 
   constructor(
     ctx: HostContext,
@@ -355,6 +360,26 @@ export class FeishuService {
       persistRoute: (key, record) => this.routes.put(key, record),
       started: () => this.started,
       detachStream: sessionId => this.streamer?.detach(sessionId),
+      mountTools: (agentCtx, sessionId) => {
+        // The fetch tool only makes sense for the lazy native backend: in
+        // archive deployments (explicit, missing host library, or fetch tool
+        // disabled) every attachment is downloaded before the turn and the
+        // Agent reads the workspace copy, so mounting the tool would only
+        // advertise an operation that can never be authorized.
+        //
+        // The topic-messages tool is backend-independent: quoted excerpts and
+        // topic history are read-only, so it is mounted for both backends and
+        // self-gates on `feishuTools.topicMessages`; `feishu_send_file`
+        // self-gates on `feishuTools.sendFile`. The mounts start together and
+        // resolve as one promise (no serial blocking).
+        const mounts: Array<Promise<void>> = []
+        if (this.effectiveAttachmentBackend() === 'native') {
+          mounts.push(this.attachmentFetchTools.mount(agentCtx, sessionId))
+        }
+        mounts.push(this.topicMessagesTools.mount(agentCtx, sessionId))
+        mounts.push(this.sendFileTools.mount(agentCtx, sessionId))
+        return Promise.all(mounts).then(() => undefined)
+      },
       warn: (message, ...args) => this.ctx.logger?.warn?.(message, ...args),
     })
     this.attachments = new AttachmentIntake({
@@ -362,6 +387,70 @@ export class FeishuService {
       channel: () => this.channel,
       warn: (message, ...args) => this.ctx.logger?.warn?.(message, ...args),
     })
+    this.inboundAttachmentStore = new InboundAttachmentStore({
+      enabled: () => this.config.acceptAttachments,
+      // Effective backend, not the raw config: `store()` is only called after
+      // admission already decided `archive`, so a native-configured deployment
+      // with the fetch tool disabled must download to the workspace here too.
+      mode: () => this.effectiveAttachmentBackend(),
+      service: () => this.nativeAttachmentService(),
+      channel: () => this.channel,
+      archive: this.attachments,
+      warn: (message, ...args) => this.ctx.logger?.warn?.(message, ...args),
+    })
+    this.attachmentFetchTools = new AttachmentFetchToolRuntime({
+      config: () => this.config,
+      channel: () => this.channel,
+      routeOfSession: sessionId => {
+        const record = this.routes.findBySession(sessionId)
+        if (record === undefined) return undefined
+        return {
+          key: record.key,
+          kind: record.kind,
+          chatId: record.chatId,
+          chatType: record.chatType,
+          senderUserId: record.senderUserId,
+        }
+      },
+      warn: (message, ...args) => this.ctx.logger?.warn?.(message, ...args),
+    })
+    this.topicMessagesTools = new TopicMessagesToolRuntime({
+      config: () => this.config,
+      channel: () => this.channel,
+      routeOfSession: sessionId => {
+        const record = this.routes.findBySession(sessionId)
+        if (record === undefined) return undefined
+        return {
+          key: record.key,
+          kind: record.kind,
+          chatId: record.chatId,
+          chatType: record.chatType,
+          senderUserId: record.senderUserId,
+        }
+      },
+      noteKnownMessage: (route, message, source) => {
+        this.attachmentFetchTools.noteKnownMessage(route, message, source)
+      },
+      isKnownMessage: (route, messageId) => this.attachmentFetchTools.isKnownMessage(route, messageId),
+      // The tool description must not promise a fetch tool that archive
+      // deployments do not mount; the runtime appends a degradation note.
+      fetchAvailable: () => this.effectiveAttachmentBackend() === 'native',
+      warn: (message, ...args) => this.ctx.logger?.warn?.(message, ...args),
+    })
+    this.sendFileTools = new SendFileToolRuntime({
+      config: () => this.config,
+      channel: () => (this.started ? this.channel : undefined),
+      targetOfSession: sessionId => {
+        const record = this.routes.findBySession(sessionId)
+        if (record === undefined) return undefined
+        return {
+          replyTo: record.cardMessageId,
+          inThread: record.kind === 'thread',
+          rootDir: sessionDirOf(record),
+        }
+      },
+      warn: (message, ...args) => this.ctx.logger?.warn?.(message, ...args),
+    })
     this.delivery = new CardDelivery({
       channel: () => this.channel,
       started: () => this.started,
@@ -373,7 +462,7 @@ export class FeishuService {
       warn: (message, ...args) => this.ctx.logger?.warn?.(message, ...args),
     })
     this.accessController = new AccessController({
-      config: () => this.config,
+      config: () => this.accessConfig(),
       store: this.accessStore,
       channel: () => this.channel,
       warn: (message, ...args) => this.ctx.logger?.warn?.(message, ...args),
@@ -397,15 +486,247 @@ export class FeishuService {
       repair: this.repair,
       delivery: this.delivery,
       sessions: this.sessions,
-      attachments: this.attachments,
+      attachmentMode: () => this.config.attachmentStore,
+      nativeAttachments: () => this.nativeAttachmentService(),
+      attachmentStore: this.inboundAttachmentStore,
+      noteKnownAttachments: (record, message, source) => {
+        this.noteKnownAttachmentMessage(record, message, source ?? 'trigger')
+      },
+      messageRead: {
+        quote: input => this.readQuoteContext(input),
+        history: input => this.readHistoryContext(input),
+      },
+      prefetchImages: () => ({
+        enabled: this.config.prefetchImages,
+        maxImageBytes: this.config.prefetchImageMaxBytes,
+        maxTotalBytes: this.config.prefetchTotalMaxBytes,
+        timeoutMs: this.config.prefetchTimeoutMs,
+      }),
       access: this.accessController,
       queue: this.routeOperations,
       streamer: () => this.streamer,
       questionAnswerer: () => this.questionAnswerer,
+      approvalAnswerer: () => this.approvalAnswerer,
       commands: { handleSlash: (msg, line) => this.handleSlashMessage(msg, line) },
     })
   }
 
+  /** Effective inbound attachment backend (matches the inbound router). */
+  private effectiveAttachmentBackend(): 'native' | 'archive' {
+    return effectiveAttachmentMode(
+      this.config.attachmentStore,
+      this.nativeAttachmentService(),
+      this.config.feishuTools.attachmentFetch,
+      this.config.acceptAttachments,
+    )
+  }
+
+  /**
+   * Resolve the host's native attachment library from the plugin scope.
+   *
+   * The service is registered host-wide (`@deepseek-ai/dsh-attachment-local`),
+   * so the safe `ctx.get` lookup resolves it even though this plugin does not
+   * declare `attachments` in its cordis `inject` list (the per-Agent scopes
+   * still inject it for the fetch tool). A missing service reads as
+   * `undefined` and switches admission to the legacy archive backend.
+   */
+  private nativeAttachmentService(): AttachmentStore | undefined {
+    const service = resolveAttachmentService(this.ctx)
+    if (service === undefined && this.config.attachmentStore === 'native'
+      && !this.warnedNativeAttachmentsUnmounted) {
+      // The facade now receives the effective backend, so its own downgrade
+      // warning cannot fire: report the missing library once from the resolver.
+      this.warnedNativeAttachmentsUnmounted = true
+      this.ctx.logger?.warn?.(
+        'dsh-channels: attachmentStore=native 但宿主未挂载 ctx.attachments，'
+        + '入站附件回退话题 attachments/ 工作区落盘',
+      )
+    }
+    return service
+  }
+
+  /**
+   * Pre-authorize one admitted Feishu message for `feishu_attachment_fetch`.
+   *
+   * The admission and quote layers call this after their access gates for the
+   * triggering / quoted message; the tool otherwise only authorizes the route
+   * owner's own messages it reads back from Feishu. Registering is a pure
+   * in-memory operation (one LRU entry per route) and never fails the caller.
+   */
+  noteKnownAttachmentMessage(
+    record: RouteRecord,
+    message: KnownAttachmentMessageInput,
+    source: KnownAttachmentSource = 'trigger',
+  ): void {
+    this.attachmentFetchTools.noteKnownMessage({
+      key: record.key,
+      kind: record.kind,
+      chatId: record.chatId,
+      chatType: record.chatType,
+      senderUserId: record.senderUserId,
+    }, message, source)
+  }
+
+  // ---- read-only message context (quoted excerpt / topic history) -------
+
+  /**
+   * Channel-plane identity of one route for message reads (structurally the
+   * same as the attachment-tool route: key/kind/chat/sender).
+   */
+  private messageReadRouteOf(record: RouteRecord): MessageReadRoute {
+    return {
+      key: record.key,
+      kind: record.kind,
+      chatId: record.chatId,
+      chatType: record.chatType,
+      senderUserId: record.senderUserId,
+    }
+  }
+
+  /**
+   * Resolve one quoted message into the bounded `<feishu_quote>` block and the
+   * whitelist registration of the quoted message (merged-forward containers
+   * keep their container id, per the P0 download rule).
+   *
+   * The quoted message must belong to this route's visible container: another
+   * chat is always rejected; on a thread route a quoted message of a
+   * *different* topic is rejected as well (a main-timeline message carries no
+   * thread id and stays allowed — quotes happen before the bot owns a topic);
+   * on a degraded chat route any topic message is rejected (a chat route must
+   * not read another topic of the same group).
+   *
+   * The read budget is the short prompt-enrichment budget, never the model
+   * tool timeout. Read failures (missing scope, deleted message, channel down)
+   * degrade to `undefined`: the turn runs without an excerpt (AC6).
+   */
+  private async readQuoteContext(input: {
+    messageId: string
+    record: RouteRecord
+  }): Promise<{ block: string; message?: KnownAttachmentMessageInput } | undefined> {
+    try {
+      const result = await readQuoteItems(this.messageReader, input.messageId, {
+        timeoutMs: this.config.promptContextTimeoutMs,
+      })
+      if (!result.ok) {
+        this.reportDegradedRead('quoted message', input.messageId, result.reason)
+        return undefined
+      }
+      const container: RawMessageItem | undefined = quoteItemsOf(result.value)
+      if (container === undefined) return undefined
+      if (!this.quotedMessageBelongsToRoute(input.record, container)) {
+        this.ctx.logger?.debug?.(
+          'dsh-channels: dropping quoted message %s from another chat/topic', input.messageId,
+        )
+        return undefined
+      }
+      const block = buildQuoteContextBlock(result.value, {
+        attachmentFetchAvailable: this.attachmentFetchMounted(),
+      })
+      if (block === '') return undefined
+      const message = knownMessageOfItems(result.value)
+      return { block, ...(message === undefined ? {} : { message }) }
+    } catch (error) {
+      // Defensive: the reader reports structured failures; a raw throw is still
+      // only ever a missing excerpt, never a failed turn.
+      this.ctx.logger?.debug?.(
+        'dsh-channels: reading quoted message %s failed: %s', input.messageId, String(error),
+      )
+      return undefined
+    }
+  }
+
+  /** Whether one quoted message may be shown/authorized for one route. */
+  private quotedMessageBelongsToRoute(record: RouteRecord, container: RawMessageItem): boolean {
+    // Fail closed on a missing/foreign chat id: every real Feishu item carries
+    // one, so an absent id is a malformed response, never a legitimate quote.
+    if (container.chatId === undefined || container.chatId !== record.chatId) return false
+    // A main-timeline message has no thread id; a message of another topic must
+    // never leak into this route's excerpt or whitelist. A degraded chat route
+    // (no topic) must reject topic messages entirely, even in the same chat.
+    if (record.kind === 'thread') {
+      return container.threadId === undefined || container.threadId === record.key
+    }
+    return container.threadId === undefined
+  }
+
+  /**
+   * Resolve the bounded first-turn `<feishu_history>` block plus the whitelist
+   * registrations of the history messages (chronological order).
+   *
+   * `limit` is `historyBootstrapLimit` (0/negative → no read at all). The page
+   * is requested newest-first so a long topic yields the most recent messages;
+   * excluded ids (the trigger and the streaming card), deleted messages, and
+   * messages outside the route container are filtered before the newest
+   * `limit` rows are reversed into chronological order for rendering. The read
+   * uses the short prompt-enrichment budget and degrades to `undefined` (AC6).
+   */
+  private async readHistoryContext(input: {
+    record: RouteRecord
+    limit: number
+    excludeMessageIds: readonly string[]
+  }): Promise<{ block: string; messages: readonly KnownAttachmentMessageInput[] } | undefined> {
+    if (!Number.isFinite(input.limit) || input.limit <= 0) return undefined
+    try {
+      const route = this.messageReadRouteOf(input.record)
+      const pageSize = clampInt(
+        input.limit + input.excludeMessageIds.length,
+        1,
+        TOPIC_MESSAGES_MAX_LIMIT,
+      )
+      const result = await this.messageReader.listRoute(route, {
+        pageSize,
+        order: 'newest-first',
+        timeoutMs: this.config.promptContextTimeoutMs,
+      })
+      if (!result.ok) {
+        this.reportDegradedRead('topic history', input.record.key, result.reason)
+        return undefined
+      }
+      const excluded = new Set(input.excludeMessageIds)
+      const recent = result.value.items
+        .filter(item => !item.deleted && !excluded.has(item.messageId))
+        .slice(0, input.limit)
+        .reverse()
+      const block = buildHistoryContextBlock(recent, {
+        maxMessages: input.limit,
+        attachmentFetchAvailable: this.attachmentFetchMounted(),
+      })
+      if (block === '') return undefined
+      return { block, messages: knownMessagesOfHistory(recent) }
+    } catch (error) {
+      this.ctx.logger?.debug?.(
+        'dsh-channels: reading topic history of %s failed: %s', input.record.key, String(error),
+      )
+      return undefined
+    }
+  }
+
+  /** Whether this deployment mounts the lazy attachment fetch tool. */
+  private attachmentFetchMounted(): boolean {
+    return this.effectiveAttachmentBackend() === 'native'
+  }
+
+  /**
+   * Report one silently degraded prompt read: debug per occurrence (expected
+   * when a deployment misses a scope) plus ONE warn per service lifetime so an
+   * operator can find the cause without log spam.
+   */
+  private reportDegradedRead(kind: string, target: string, reason: string): void {
+    if (this.warnedPromptReadDegraded) {
+      this.ctx.logger?.debug?.(
+        'dsh-channels: %s read of %s failed (degraded): %s', kind, target, reason,
+      )
+      return
+    }
+    this.warnedPromptReadDegraded = true
+    this.ctx.logger?.warn?.(
+      'dsh-channels: %s（%s）读取失败，已静默降级（不带引用/历史上下文继续回合）：%s。'
+      + '如持续出现请检查飞书应用的消息读取权限（如 im:message:readonly / im:message.group_msg），'
+      + '或确认该消息未被撤回、网络正常',
+      kind, target, reason,
+    )
+  }
+
   // ---- lifecycle / Web settings panel ----------------------------------
 
   /**
@@ -511,7 +832,7 @@ export class FeishuService {
   /** Re-read the Web overlay over the profile config (no channel touch). */
   private async loadOverlay(): Promise<void> {
     const overlay = this.overlay === undefined ? {} : await this.overlay.load()
-    this.replaceConfig({ ...this.baseConfig, ...overlay })
+    this.replaceConfig(mergeOverlay(this.baseConfig, overlay))
   }
 
   /**
@@ -530,9 +851,8 @@ export class FeishuService {
    * Apply an already-validated overlay over the profile config. Fields read
    * per event/turn take effect immediately; `RESTART_KEYS` need `restart()`.
    */
-  applyOverlay(overlay: Partial<FeishuConfig>): void {
-    this.replaceConfig({ ...this.baseConfig, ...overlay })
-    this.refreshRetentionTimer()
+  applyOverlay(overlay: OverlayPatch): void {
+    this.replaceConfig(mergeOverlay(this.baseConfig, overlay))
   }
 
   /**
@@ -581,15 +901,17 @@ export class FeishuService {
 
   /** Whitelists + pending authorization requests (read-only Web projection). */
   accessSnapshot(): AccessWire {
-    const admin = this.config.adminOpenId
+    const admin = this.effectiveAdminUserId()
+    const owner = this.appOwner
     return {
       mode: this.config.accessMode,
       // Whitelists live in the storage domain, which is only open while the
       // channel runs; an unconnected panel must not present them as empty.
       loaded: this.domain !== undefined,
       admin: {
-        ...(admin === undefined ? {} : { openId: admin }),
+        ...(admin === undefined ? {} : { userId: admin, source: this.configuredAdminUserId() === undefined ? 'owner' : 'config' }),
         configured: admin !== undefined,
+        ...(owner !== undefined && 'error' in owner ? { ownerLookupError: owner.error } : {}),
       },
       groups: this.accessStore.groupRecords().map(record => ({
         chatId: record.chatId,
@@ -598,7 +920,7 @@ export class FeishuService {
         addedAt: record.addedAt,
       })),
       users: this.accessStore.userRecords().map(record => ({
-        openId: record.openId,
+        userId: record.userId,
         ...(record.name === undefined ? {} : { name: record.name }),
         source: record.source,
         addedAt: record.addedAt,
@@ -615,7 +937,7 @@ export class FeishuService {
         if (name !== undefined) wire.name = name
         if (record.chatId !== undefined) wire.chatId = record.chatId
         if (record.groupName !== undefined) wire.groupName = record.groupName
-        const requester = record.requesterName ?? record.requesterOpenId
+        const requester = record.requesterName ?? record.requesterUserId
         if (requester !== undefined) wire.requester = requester
         return wire
       }),
@@ -626,8 +948,8 @@ export class FeishuService {
   async addAccessGroup(chatId: string, name?: string): Promise<AccessMutationResponse> {
     const id = this.cleanAccessTargetId(chatId)
     if (id === undefined) return { ok: false, error: 'chat_id 不合法（应为 oc_ 开头的群 ID）' }
-    const admin = this.config.adminOpenId
-    if (admin === undefined) return { ok: false, error: '请先在「访问授权」标签页设置管理员 open_id' }
+    const admin = this.effectiveAdminUserId()
+    if (admin === undefined) return { ok: false, error: '请先在「访问授权」标签页设置管理员 user_id' }
     try {
       if (!this.accessStore.hasGroup(id)) {
         await this.accessStore.addGroup({
@@ -657,15 +979,15 @@ export class FeishuService {
   }
 
   /** Panel: authorize one user (global across authorized groups). */
-  async addAccessUser(openId: string, name?: string): Promise<AccessMutationResponse> {
-    const id = this.cleanAccessUserId(openId)
-    if (id === undefined) return { ok: false, error: 'open_id 不合法（应以 ou_ 开头）' }
-    const admin = this.config.adminOpenId
-    if (admin === undefined) return { ok: false, error: '请先在「访问授权」标签页设置管理员 open_id' }
+  async addAccessUser(userId: string, name?: string): Promise<AccessMutationResponse> {
+    const id = this.cleanAccessUserId(userId)
+    if (id === undefined) return { ok: false, error: 'user_id 不合法（只能包含字母、数字、_ 和 -，不是 ou_ 开头的 open_id）' }
+    const admin = this.effectiveAdminUserId()
+    if (admin === undefined) return { ok: false, error: '请先在「访问授权」标签页设置管理员 user_id' }
     try {
       if (!this.accessStore.hasUser(id)) {
         await this.accessStore.addUser({
-          openId: id,
+          userId: id,
           ...(name === undefined || name.trim() === '' ? {} : { name: name.trim() }),
           source: 'panel',
           addedBy: admin,
@@ -679,9 +1001,9 @@ export class FeishuService {
   }
 
   /** Panel: revoke one user. */
-  async removeAccessUser(openId: string): Promise<AccessMutationResponse> {
-    const id = this.cleanAccessUserId(openId)
-    if (id === undefined) return { ok: false, error: 'open_id 不合法' }
+  async removeAccessUser(userId: string): Promise<AccessMutationResponse> {
+    const id = this.cleanAccessUserId(userId)
+    if (id === undefined) return { ok: false, error: 'user_id 不合法' }
     try {
       await this.accessStore.removeUser(id)
       return { ok: true, access: this.accessSnapshot() }
@@ -694,8 +1016,8 @@ export class FeishuService {
   async resolveAccessRequest(token: string, decision: 'allow' | 'deny'): Promise<AccessMutationResponse> {
     const requests = this.accessRequests
     if (requests === undefined) return { ok: false, error: '授权服务尚未启动' }
-    const actor = this.config.adminOpenId
-    if (actor === undefined) return { ok: false, error: '请先在「访问授权」标签页配置管理员 open_id' }
+    const actor = this.effectiveAdminUserId()
+    if (actor === undefined) return { ok: false, error: '请先在「访问授权」标签页配置管理员 user_id' }
     try {
       const result = await requests.resolve(token, decision, actor)
       if (!result.ok) return { ok: false, error: result.error }
@@ -705,275 +1027,191 @@ export class FeishuService {
     }
   }
 
-  /** Trim + bound one panel-supplied identifier; rejects control characters. */
-  private cleanAccessTargetId(raw: string): string | undefined {
-    const value = raw.trim()
-    if (value === '' || value.length > 128) return undefined
-    // eslint-disable-next-line no-control-regex
-    if (/[\u0000-\u001f\u007f]/u.test(value)) return undefined
-    return value
+  /** `/auth status` administrator line: id plus where it came from. */
+  private adminStatusLine(): string {
+    const admin = this.effectiveAdminUserId()
+    if (admin === undefined) return '未配置'
+    return this.configuredAdminUserId() === undefined ? `\`${admin}\`（应用所有者，自动）` : `\`${admin}\``
   }
 
-  /** Same normalization for user open_ids, which must look like ou_xxx. */
-  private cleanAccessUserId(raw: string): string | undefined {
-    const value = this.cleanAccessTargetId(raw)
-    if (value === undefined || !/^ou_[A-Za-z0-9_-]+$/u.test(value)) return undefined
-    return value
+  /** The explicitly configured administrator, trimmed; empty counts as unset. */
+  private configuredAdminUserId(): string | undefined {
+    const admin = this.config.adminUserId?.trim()
+    return admin === undefined || admin === '' ? undefined : admin
   }
 
-  // ---- retention cleanup ------------------------------------------------
+  /** Configured administrator, else the app owner looked up at `start()`. */
+  private effectiveAdminUserId(): string | undefined {
+    const configured = this.configuredAdminUserId()
+    if (configured !== undefined) return configured
+    const owner = this.appOwner
+    return owner !== undefined && 'userId' in owner ? owner.userId : undefined
+  }
 
-  /**
-   * Retention preview for the Web panel: how many plugin workspaces exist,
-   * how many directories are past the configured window, and their measured
-   * footprint. Never deletes anything.
-   */
-  async cleanupPreview(): Promise<{
-    retention: string
-    thresholdMs?: number
-    auto: boolean
-    workspaces: number
-    candidates: number
-    candidateBytes: number
-    error?: string
-  }> {
-    const retention = this.config.workspaceRetention
-    const window = retentionMs(retention)
-    const base = {
-      retention,
-      ...(window === undefined ? {} : { thresholdMs: window }),
-      auto: this.config.workspaceRetentionAuto,
-    }
-    if (this.domain === undefined) {
-      // No connection: routes live in the closed storage domain, so a preview
-      // would mistake every directory for a candidate. Report why instead.
-      return {
-        ...base,
-        workspaces: 0,
-        candidates: 0,
-        candidateBytes: 0,
-        error: '飞书连接建立后即可预览和清理工作区',
-      }
-    }
-    try {
-      const workspaces = this.ctx.workspaceRegistry.list().filter(workspace => this.isPluginWorkspace(workspace))
-      const plan = await planWorkspaceCleanup(this.cleanupDeps())
-      return {
-        ...base,
-        workspaces: workspaces.length,
-        candidates: plan?.candidates.length ?? 0,
-        candidateBytes: plan?.candidates.reduce((total, candidate) => total + candidate.bytes, 0) ?? 0,
-      }
-    } catch (error) {
-      return { ...base, workspaces: 0, candidates: 0, candidateBytes: 0, error: messageOf(error) }
-    }
+  /** Live config with `adminUserId` replaced by the effective administrator. */
+  private accessConfig(): FeishuConfig {
+    return { ...this.config, adminUserId: this.effectiveAdminUserId() }
   }
 
   /**
-   * Delete every stale plugin directory the configured retention allows: the
-   * per-topic working directories of current conversations and the legacy
-   * one-workspace-per-topic directories of older versions. User workspaces are
-   * never deleted.
-   *
-   * Active routes bound to a removed directory are retired first (thread
-   * routes leave a tombstone), so an old topic fails with the explicit expired
-   * card instead of resuming into a missing directory. DSH Session logs are not
-   * touched.
+   * Look up the app owner for the administrator fallback. Never throws: a
+   * failure is recorded for the panel and only warned about when no
+   * administrator is configured (the fallback is then what admission needs).
    */
-  async runWorkspaceCleanup(): Promise<{
-    ok: boolean
-    deletedWorkspaces: number
-    deletedSessionDirs: number
-    retiredRoutes: number
-    freedBytes: number
-    failures: string[]
-    error?: string
-  }> {
-    const empty = {
-      ok: false,
-      deletedWorkspaces: 0,
-      deletedSessionDirs: 0,
-      retiredRoutes: 0,
-      freedBytes: 0,
-      failures: [] as string[],
-    }
-    if (this.domain === undefined) {
-      // Without the storage domain the route table is unreadable, so a cleanup
-      // could mistake live directories for candidates and fail to retire their
-      // routes. Refuse rather than rely on the panel disabling the button.
-      return { ...empty, error: '飞书连接建立后才能清理工作区' }
-    }
-    if (retentionMs(this.config.workspaceRetention) === undefined) {
-      return { ...empty, error: '未启用目录清理阈值（workspaceRetention 为 off）' }
-    }
-    if (this.cleanupRunning) return { ...empty, error: '目录清理正在进行中，请稍候' }
-    this.cleanupRunning = true
+  private async resolveAppOwner(channel: FeishuChannel): Promise<void> {
+    this.appOwner = undefined
+    if (channel.appOwnerUserId === undefined) return
+    let timer: ReturnType<typeof setTimeout> | undefined
+    let state: AppOwnerState
     try {
-      const deps = this.cleanupDeps()
-      const plan = await planWorkspaceCleanup(deps)
-      if (plan === undefined) return { ...empty, error: '目录清理不可用：baseDir 配置无效' }
-      const outcome = await applyWorkspaceCleanup(deps, plan)
-      this.ctx.logger?.info?.(
-        'dsh-channels: retention cleanup removed %d legacy workspace(s) and %d topic dir(s), retired %d route(s), freed %d bytes',
-        outcome.deletedWorkspaces, outcome.deletedSessionDirs, outcome.retiredRoutes, outcome.freedBytes,
-      )
-      return {
-        ok: true,
-        deletedWorkspaces: outcome.deletedWorkspaces,
-        deletedSessionDirs: outcome.deletedSessionDirs,
-        retiredRoutes: outcome.retiredRoutes,
-        freedBytes: outcome.freedBytes,
-        failures: outcome.failures.map(failure => `${failure.path}: ${failure.message}`),
-      }
+      const userId = await Promise.race([
+        channel.appOwnerUserId(),
+        new Promise<never>((_, reject) => {
+          timer = setTimeout(() => reject(new Error(`超时（${APP_OWNER_LOOKUP_TIMEOUT_MS} ms）`)), APP_OWNER_LOOKUP_TIMEOUT_MS)
+        }),
+      ])
+      state = userId !== undefined && FEISHU_USER_ID_PATTERN.test(userId)
+        ? { userId }
+        : { error: '应用所有者不是企业内成员，或接口未返回其 user_id', apiRejected: false }
     } catch (error) {
-      return { ...empty, error: messageOf(error) }
+      const detail = error instanceof AppOwnerLookupError ? error.detail : messageOf(error)
+      state = {
+        error: `获取应用信息失败：${detail}。请在「访问授权」手动填写管理员 user_id（私聊机器人发 /userid 获取，私聊模式关闭时可在飞书管理后台的成员详情里查看用户 ID）；或为应用开通「获取应用信息」权限并发布版本后重新连接`,
+        apiRejected: error instanceof AppOwnerLookupError && error.code !== undefined,
+      }
     } finally {
-      this.cleanupRunning = false
+      if (timer !== undefined) clearTimeout(timer)
+    }
+    // A background lookup can outlive its connection (shutdown/reconnect).
+    if (this.channel !== channel) return
+    this.appOwner = state
+    if ('error' in state && this.configuredAdminUserId() === undefined) {
+      this.ctx.logger?.warn?.('dsh-channels: app owner fallback unavailable: %s', state.error)
     }
   }
 
-  /** Whether one registry workspace was created by this plugin inside `baseDir`. */
-  private isPluginWorkspace(workspace: Workspace): boolean {
-    const pluginTitle = workspace.title.startsWith('飞书私聊 ·') || workspace.title.startsWith('飞书群聊 ·')
-    return pluginTitle && isPathInside(path.resolve(this.config.baseDir), workspace.path)
+  /** Latest post-connect scope self-check, when one finished for this connection. */
+  scopeCheck(): ScopeCheckWire | undefined {
+    return this.scopeCheckState
   }
 
-  /** Effect seams for the cleanup policy module (all I/O stays here). */
-  private cleanupDeps(): CleanupDeps {
-    const baseDir = path.resolve(this.config.baseDir)
-    return {
-      baseDir,
-      retention: this.config.workspaceRetention,
-      listWorkspaces: () => this.ctx.workspaceRegistry.list(),
-      listSessionDirs: () => this.listCleanableSessionDirs(baseDir),
-      activeRoutes: () => [...(this.domain?.routes.entries() ?? [])].map(([key, record]): CleanupRoute => ({
-        key,
-        kind: record.kind,
-        workspacePath: record.workspacePath,
-        ...(record.sessionDir === undefined ? {} : { sessionDir: record.sessionDir }),
-        sessionId: record.sessionId,
-        lastActivityAt: record.lastActivityAt,
-      })),
-      tombstones: () => [...(this.domain?.expiredRoutes.entries() ?? [])].map(([key, record]): CleanupTombstone => ({
-        key,
-        ...(record.workspacePath === undefined ? {} : { workspacePath: record.workspacePath }),
-        ...(record.sessionDir === undefined ? {} : { sessionDir: record.sessionDir }),
-        expiredAt: record.expiredAt,
-        ...(record.lastActivityAt === undefined ? {} : { lastActivityAt: record.lastActivityAt }),
-      })),
-      isLive: sessionId => this.sessions.get(sessionId) !== undefined
-        || this.ctx.agents.get(sessionId as SessionId) !== undefined,
-      statWorkspace: directory => measureWorkspace(directory),
-      removeWorkspace: async workspace => {
-        await this.deleteDirectoryInsideBase(baseDir, workspace.path)
-        try {
-          await this.ctx.workspaceRegistry.delete(workspace.id)
-        } catch (error) {
-          this.ctx.logger?.warn?.(
-            'dsh-channels: unregistering cleaned workspace %s failed: %s', workspace.path, String(error),
-          )
-        }
-      },
-      removeSessionDir: async directory => {
-        await this.deleteDirectoryInsideBase(baseDir, directory)
-      },
-      retireRoute: async route => {
-        if (route.kind === 'thread') await this.routes.retire(route.key)
-        else await this.routes.remove(route.key)
-      },
-      warn: message => this.ctx.logger?.warn?.(message),
-    }
+  /** Latest native slash-command panel sync, when one finished for this connection. */
+  slashCommandSync(): SlashCommandSyncWire | undefined {
+    return this.slashCommandSyncState
   }
 
   /**
-   * Scan the live user workspaces for per-topic working directories that no
-   * route record points at anymore (for example the old route of a degraded
-   * chat conversation was deleted by TTL retirement). Route/tombstone evidence
-   * wins for age; the scan mtime only covers true orphans.
+   * Reconcile Feishu's native `/` panel with the command registry and log the
+   * outcome. Never throws; a failure only loses the panel listing, typed
+   * commands keep working.
    */
-  private async listCleanableSessionDirs(baseDir: string): Promise<ScannedSessionDir[]> {
-    const legacyRoot = legacyTopicWorkspaceRoot(baseDir)
-    const roots: string[] = []
-    for (const workspace of this.ctx.workspaceRegistry.list()) {
-      if (!this.isPluginWorkspace(workspace)) continue
-      const resolved = path.resolve(workspace.path)
-      // Legacy per-topic workspaces are cleaned as workspaces, not scanned here.
-      if (isPathInside(legacyRoot, resolved)) continue
-      roots.push(resolved)
-    }
-    const scanned: ScannedSessionDir[] = []
-    for (const root of roots) {
-      for (const relative of ['topics', path.join('.agents', 'worktrees')]) {
-        const directory = path.join(root, relative)
-        let entries
-        try {
-          entries = await readdir(directory, { withFileTypes: true })
-        } catch {
-          continue
-        }
-        for (const entry of entries) {
-          if (!entry.isDirectory()) continue
-          const candidate = path.join(directory, entry.name)
-          try {
-            const info = await lstat(candidate)
-            if (info.isDirectory()) scanned.push({ path: candidate, mtimeMs: info.mtimeMs })
-          } catch {
-            // Removed or unreadable between readdir and lstat; skip it.
-          }
-        }
-      }
+  private async runSlashCommandSync(channel: FeishuChannel): Promise<void> {
+    this.slashCommandSyncState = undefined
+    this.slashCommandSyncAbort?.abort()
+    this.slashCommandSyncAbort = undefined
+    const api = channel.slashCommands
+    if (api === undefined) return
+    const abort = new AbortController()
+    this.slashCommandSyncAbort = abort
+    let timer: ReturnType<typeof setTimeout> | undefined
+    let state: SlashCommandSyncWire
+    try {
+      const result = await Promise.race([
+        syncSlashCommands(api, desiredSlashCommands(), abort.signal),
+        new Promise<never>((_, reject) => {
+          timer = setTimeout(() => reject(new Error(`超时（${SLASH_COMMAND_SYNC_TIMEOUT_MS} ms）`)), SLASH_COMMAND_SYNC_TIMEOUT_MS)
+        }),
+      ])
+      state = { state: 'ok', checkedAt: Date.now(), ...result }
+    } catch (error) {
+      const detail = error instanceof FeishuApiError ? error.detail : messageOf(error)
+      state = { state: 'error', checkedAt: Date.now(), error: detail }
+    } finally {
+      if (timer !== undefined) clearTimeout(timer)
+      // A timed-out sync must not keep writing behind a reported failure.
+      abort.abort()
+      if (this.slashCommandSyncAbort === abort) this.slashCommandSyncAbort = undefined
+    }
+    // A background sync can outlive its connection (shutdown/reconnect).
+    if (this.channel !== channel) return
+    this.slashCommandSyncState = state
+    if (state.state === 'ok') {
+      this.ctx.logger?.info?.('dsh-channels: slash command panel synced (%d commands, %d created, %d updated, %d removed)', state.total, state.created, state.updated, state.removed)
+    } else {
+      this.ctx.logger?.warn?.('dsh-channels: 飞书原生斜杠指令面板同步失败（直接输入命令不受影响）：%s', state.error)
     }
-    return scanned
   }
 
   /**
-   * Recursively delete one plugin directory below `baseDir`.
-   *
-   * The lexical check refuses paths outside `baseDir`; the realpath check then
-   * refuses a symlinked ancestor that would let the recursive delete escape
-   * the plugin root. A missing directory is already effectively removed.
+   * Compare the app's granted scopes with what the plugin uses and log the
+   * missing ones. Never throws; waits for the owner lookup so the app-info
+   * need reflects its outcome.
    */
-  private async deleteDirectoryInsideBase(baseDir: string, target: string): Promise<void> {
-    const resolved = path.resolve(target)
-    if (!isPathInside(baseDir, resolved)) {
-      throw new Error(`refusing to delete a path outside baseDir (${resolved})`)
-    }
+  private async runScopeCheck(channel: FeishuChannel, appId: string, ownerLookup: Promise<void>): Promise<void> {
+    this.scopeCheckState = undefined
+    if (channel.grantedScopes === undefined) return
+    await ownerLookup
+    let timer: ReturnType<typeof setTimeout> | undefined
+    let state: ScopeCheckWire
     try {
-      const [physicalBase, physicalTarget] = await Promise.all([realpath(baseDir), realpath(resolved)])
-      if (!isPathInside(physicalBase, physicalTarget)) {
-        throw new Error(`refusing to delete a symlink escape outside baseDir (${physicalTarget})`)
-      }
+      const grants = await Promise.race([
+        channel.grantedScopes(),
+        new Promise<never>((_, reject) => {
+          timer = setTimeout(() => reject(new Error(`超时（${SCOPE_CHECK_TIMEOUT_MS} ms）`)), SCOPE_CHECK_TIMEOUT_MS)
+        }),
+      ])
+      const result = checkScopes(grants, appId, {
+        dmEnabled: this.config.dmMode === 'open',
+        requireMention: this.config.requireMention,
+        ownerLookupFailed: this.config.accessMode === 'guarded'
+          && this.configuredAdminUserId() === undefined
+          && this.appOwner !== undefined && 'error' in this.appOwner && this.appOwner.apiRejected,
+        slashCommandPanel: this.config.slashCommandPanel,
+        sendFile: this.config.feishuTools.sendFile,
+      })
+      state = result.consoleUrl === undefined
+        ? { state: 'ok', checkedAt: Date.now() }
+        : {
+            state: 'missing',
+            checkedAt: Date.now(),
+            missing: result.missing.map(item => ({
+              scopes: [...item.anyOf], level: item.level, purpose: item.purpose, consoleUrl: item.consoleUrl,
+            })),
+            consoleUrl: result.consoleUrl,
+          }
     } catch (error) {
-      if (error instanceof Error && error.message.startsWith('refusing to delete a symlink escape')) throw error
-      // A missing directory is already effectively removed (rm is idempotent).
+      const detail = error instanceof FeishuApiError ? error.detail : messageOf(error)
+      state = { state: 'error', checkedAt: Date.now(), error: detail }
+    } finally {
+      if (timer !== undefined) clearTimeout(timer)
+    }
+    // A background check can outlive its connection (shutdown/reconnect).
+    if (this.channel !== channel) return
+    this.scopeCheckState = state
+    if (state.state === 'ok') {
+      this.ctx.logger?.info?.('dsh-channels: scope self-check passed')
+    } else if (state.state === 'missing') {
+      const lines = state.missing.map(item => `${item.level === 'required' ? '必需' : '可选'} ${item.scopes.join(' 或 ')}：${item.purpose}`)
+      this.ctx.logger?.warn?.('dsh-channels: 飞书权限缺失 %d 项，开通后需发布新版本（%s）：\n  %s', state.missing.length, state.consoleUrl, lines.join('\n  '))
+    } else {
+      this.ctx.logger?.warn?.('dsh-channels: 飞书权限自检失败：%s', state.error)
     }
-    await rm(resolved, { recursive: true, force: true })
   }
 
-  /**
-   * (Re)arm the daily retention timer to match the live config. `runNow`
-   * performs one pass immediately; it is only used at startup so saving any
-   * unrelated setting can never trigger a surprise deletion pass.
-   */
-  private refreshRetentionTimer(runNow = false): void {
-    if (this.retentionTimer !== undefined) {
-      clearInterval(this.retentionTimer)
-      this.retentionTimer = undefined
-    }
-    if (!this.started
-      || !this.config.workspaceRetentionAuto
-      || retentionMs(this.config.workspaceRetention) === undefined) return
-    const sweep = (): void => {
-      void this.runWorkspaceCleanup().then(result => {
-        if (!result.ok && result.error !== '目录清理正在进行中，请稍候') {
-          this.ctx.logger?.warn?.('dsh-channels: automatic workspace cleanup failed: %s', result.error)
-        }
-      })
-    }
-    if (runNow) sweep()
-    const timer = setInterval(sweep, RETENTION_SWEEP_INTERVAL_MS)
-    timer.unref?.()
-    this.retentionTimer = timer
+  /** Trim + bound one panel-supplied identifier; rejects control characters. */
+  private cleanAccessTargetId(raw: string): string | undefined {
+    const value = raw.trim()
+    if (value === '' || value.length > 128) return undefined
+    // eslint-disable-next-line no-control-regex
+    if (/[\u0000-\u001f\u007f]/u.test(value)) return undefined
+    return value
+  }
+
+  /** Same normalization for user ids, which must be Feishu `user_id`s. */
+  private cleanAccessUserId(raw: string): string | undefined {
+    const value = this.cleanAccessTargetId(raw)
+    if (value === undefined || !FEISHU_USER_ID_PATTERN.test(value)) return undefined
+    return value
   }
 
   /** Aggregate health used by `/health` and the Web settings panel. */
@@ -1105,6 +1343,9 @@ export class FeishuService {
       onError: (sessionId, error) => {
         this.ctx.logger?.warn?.('dsh-channels approval error (session %s): %s', sessionId, String(error))
       },
+      onWaitingChange: (sessionId, toolNames) => {
+        this.streamer?.setAwaitingApproval(sessionId, toolNames)
+      },
     }, this.config.approvalTimeoutMs)
     this.approvalAnswerer = answerer
     this.unlistenApproval = this.ctx.on('approval/request', (req, next) => answerer.onRequest(req, next), { prepend: true })
@@ -1124,7 +1365,7 @@ export class FeishuService {
       { prepend: true },
     )
     const accessRequests = new AccessRequests({
-      config: () => this.config,
+      config: () => this.accessConfig(),
       store: this.accessStore,
       channel: () => this.channel,
       warn: (message, ...args) => this.ctx.logger?.warn?.(message, ...args),
@@ -1142,10 +1383,15 @@ export class FeishuService {
       void accessRequests.onCardAction(event)
       answerer.onCardAction(event)
       questions.onCardAction(event)
+      this.onStopAction(event)
+      void this.onPickAction(event).catch((error: unknown) => {
+        this.ctx.logger?.warn?.('dsh-channels: picker card action failed: %s', String(error))
+      })
     })
 
     this.unlistenHost.push(this.ctx.on('session/event', (session, event) => {
       this.streamer?.onSessionEvent(session, event)
+      this.approvalAnswerer?.onSessionEvent(session.id, event)
     }))
     // DSH removed the durable `assistant/chunk` event (format v2 embeds the
     // stream in the settlement); the live deltas arrive here instead.
@@ -1161,7 +1407,15 @@ export class FeishuService {
           .catch(() => {})
       })
     })
+    // Without a configured administrator, resolve the owner before the
+    // handshake so the first inbound message already sees the fallback; with
+    // one, the lookup only backs a later runtime clear and must not delay boot.
+    const ownerLookup = this.resolveAppOwner(channel)
+    if (this.configuredAdminUserId() === undefined) await ownerLookup
     await channel.connect()
+    // Background: the results only feed the panel and the log.
+    void this.runScopeCheck(channel, appId, ownerLookup)
+    if (this.config.slashCommandPanel) void this.runSlashCommandSync(channel)
     // Repair cards a previous instance left mid-flight (best-effort, background).
     void this.repair.repairAll().catch((error: unknown) => {
       this.ctx.logger?.warn?.('dsh-channels: inflight repair failed: %s', String(error))
@@ -1178,8 +1432,6 @@ export class FeishuService {
     }, GC_SWEEP_INTERVAL_MS)
     timer.unref?.()
     this.gcTimer = timer
-    // Workspace retention: opt-in automatic cleanup (default off).
-    this.refreshRetentionTimer(true)
     this.ctx.logger?.info?.(
       'dsh-channels: feishu long connection established (bot open_id %s, %d route(s) loaded)',
       channel.botOpenId() ?? 'unknown',
@@ -1195,11 +1447,15 @@ export class FeishuService {
     })
     if (this.config.accessMode === 'open') {
       console.warn('[dsh-channels] 准入=open：任何应用可用范围内的用户都可以对话（不安全，仅调试）')
-    } else if (this.config.adminOpenId === undefined) {
+    } else if (this.effectiveAdminUserId() === undefined) {
+      const ownerError = this.appOwner !== undefined && 'error' in this.appOwner ? this.appOwner.error : undefined
       console.warn(
-        '[dsh-channels] 准入=guarded 但未配置管理员 open_id：所有对话都会被拒绝；'
-        + '私聊机器人发送 /userid 取得 open_id 后填入 Web 设置面板',
+        '[dsh-channels] 准入=guarded 但未配置管理员 user_id，也无法使用应用所有者兜底：所有对话都会被拒绝；'
+        + '私聊机器人发送 /userid 取得 user_id 后填入 Web 设置面板'
+        + (ownerError === undefined ? '' : `（${ownerError}）`),
       )
+    } else if (this.configuredAdminUserId() === undefined) {
+      console.info('[dsh-channels] 准入=guarded，未配置管理员，使用应用所有者', this.effectiveAdminUserId())
     } else {
       console.info('[dsh-channels] 准入=guarded，管理员已配置')
     }
@@ -1253,11 +1509,8 @@ export class FeishuService {
       clearInterval(this.gcTimer)
       this.gcTimer = undefined
     }
-    if (this.retentionTimer !== undefined) {
-      clearInterval(this.retentionTimer)
-      this.retentionTimer = undefined
-    }
     await this.sessions.disposeAll()
+    this.attachmentFetchTools.clear()
     this.routeOperations.clear()
     this.inbound.clear()
     this.routes.clear()
@@ -1268,10 +1521,16 @@ export class FeishuService {
       // Already disconnected is fine.
     }
     this.channel = undefined
+    this.streamer?.detachAll()
     this.streamer = undefined
     await this.domain?.close()
     this.domain = undefined
     this.runningConfig = undefined
+    this.appOwner = undefined
+    this.scopeCheckState = undefined
+    this.slashCommandSyncState = undefined
+    this.slashCommandSyncAbort?.abort()
+    this.slashCommandSyncAbort = undefined
   }
 
   // ---- inbound routing -------------------------------------------------
@@ -1345,7 +1604,7 @@ export class FeishuService {
       return
     }
 
-    if (msg.senderId !== route.senderOpenId) {
+    if (msg.senderId !== route.senderUserId) {
       await this.delivery.commandCard(msg, {
         kind: 'forbidden', command: parsed.name, text: '无权操作此会话。',
       })
@@ -1355,7 +1614,7 @@ export class FeishuService {
     const operation = this.routeOperations.run(route.key, async () => {
       if (!this.started) return
       const current = this.routes.get(route.key) ?? route
-      if (msg.senderId !== current.senderOpenId) {
+      if (msg.senderId !== current.senderUserId) {
         await this.delivery.commandCard(msg, {
           kind: 'forbidden', command: parsed.name, text: '无权操作此会话。',
         })
@@ -1388,12 +1647,12 @@ export class FeishuService {
         const pending = this.accessStore.pendingRequests()
         await this.delivery.standaloneReply(msg, standaloneInfoCard('**🔐 访问授权状态**', [
           `**准入模式**：\`${this.config.accessMode}\``,
-          `**管理员**：${this.config.adminOpenId === undefined ? '未配置' : `\`${this.config.adminOpenId}\``}`,
+          `**管理员**：${this.adminStatusLine()}`,
           ...(msg.chatType === 'group'
             ? [`**本群**：${this.accessStore.hasGroup(msg.chatId) ? '已授权' : '未授权'}（\`${msg.chatId}\`）`]
             : []),
           `**白名单**：群 ${groups.length} 个 · 用户 ${users.length} 个 · 待处理申请 ${pending.length} 个`,
-          '群授权：`/auth allow` 或 `/auth revoke`（在目标群内发）；用户授权：`/auth user add <open_id>`。',
+          '群授权：`/auth allow` 或 `/auth revoke`（在目标群内发）；用户授权：`/auth user add @用户` 或 `/auth user add <user_id>`。',
         ]), direct)
         return
       }
@@ -1440,35 +1699,39 @@ export class FeishuService {
       }
       if (action === 'user') {
         const sub = words[1]
-        const openId = words[2]
-        if ((sub !== 'add' && sub !== 'remove') || openId === undefined
-          || !/^ou_[A-Za-z0-9_-]+$/u.test(openId)) {
+        const target = sub === 'add' || sub === 'remove'
+          ? resolveAuthUserTarget(words.slice(2).join(' '), msg.mentions, this.channel?.botOpenId())
+          : { ok: false as const, reason: 'usage' as const }
+        if (!target.ok) {
           await this.delivery.commandCard(msg, {
-            kind: 'input-error', command: 'auth',
-            text: '用法：/auth user add <open_id> 或 /auth user remove <open_id>（open_id 以 ou_ 开头，可用 /userid 查看）。',
+            kind: 'input-error', command: 'auth', text: AUTH_USER_TARGET_ERRORS[target.reason],
           }, direct)
           return
         }
+        const { userId } = target
+        const label = target.name === undefined ? `\`${userId}\`` : `${target.name}（\`${userId}\`）`
         if (sub === 'add') {
-          if (this.accessStore.hasUser(openId)) {
+          if (this.accessStore.hasUser(userId)) {
             await this.delivery.commandCard(msg, {
-              kind: 'success', command: 'auth', text: `该用户已在白名单中（\`${openId}\`）。`,
+              kind: 'success', command: 'auth', text: `该用户已在白名单中：${label}。`,
             }, direct)
             return
           }
           await this.accessStore.addUser({
-            openId, source: 'command', addedBy: msg.senderId, addedAt: now,
+            userId,
+            ...(target.name === undefined ? {} : { name: target.name }),
+            source: 'command', addedBy: msg.senderId, addedAt: now,
           })
           await this.delivery.commandCard(msg, {
             kind: 'success', command: 'auth',
-            text: `✅ 已授权用户 \`${openId}\`（在所有已授权群里生效）。`,
+            text: `✅ 已授权用户 ${label}（在所有已授权群里生效）。`,
           }, direct)
           return
         }
-        const removed = await this.accessStore.removeUser(openId)
+        const removed = await this.accessStore.removeUser(userId)
         await this.delivery.commandCard(msg, {
           kind: removed ? 'success' : 'unavailable', command: 'auth',
-          text: removed ? `已移除用户 \`${openId}\`，立即生效。` : `用户 \`${openId}\` 不在白名单中。`,
+          text: removed ? `已移除用户 ${label}，立即生效。` : `用户 ${label} 不在白名单中。`,
         }, direct)
         return
       }
@@ -1481,7 +1744,7 @@ export class FeishuService {
           : groups.slice(0, 30).map(group => `- ${group.name ?? group.chatId} \`${group.chatId}\``)
         const userLines = users.length === 0
           ? ['（暂无）']
-          : users.slice(0, 30).map(user => `- ${user.name ?? user.openId} \`${user.openId}\``)
+          : users.slice(0, 30).map(user => `- ${user.name ?? user.userId} \`${user.userId}\``)
         await this.delivery.standaloneReply(msg, standaloneInfoCard('**🔐 访问授权清单**', [
           `**已授权群（${groups.length}）**`,
           ...groupLines,
@@ -1493,7 +1756,7 @@ export class FeishuService {
       }
       await this.delivery.commandCard(msg, {
         kind: 'input-error', command: 'auth',
-        text: '用法：/auth [status|allow|revoke|list|user add <open_id>|user remove <open_id>]',
+        text: '用法：/auth [status|allow|revoke|list|user add <@用户|user_id>|user remove <@用户|user_id>]',
       }, direct)
     } catch (error) {
       this.ctx.logger?.warn?.('dsh-channels: /auth failed: %s', String(error))
@@ -1602,10 +1865,7 @@ export class FeishuService {
       return
     }
     if (spec.name === 'stop') {
-      const agent = this.sessions.get(current.sessionId)?.agent
-        ?? this.ctx.agents.get(current.sessionId as SessionId)
-      const running = agent?.status === 'running'
-      agent?.cancel?.({ kind: 'user' })
+      const running = this.cancelTurn(current.sessionId)
       await this.delivery.commandCard(msg, {
         kind: 'success', command: 'stop', sessionId: current.sessionId,
         text: running ? '已请求停止当前回合。' : '当前没有正在运行的回合。',
@@ -1618,6 +1878,72 @@ export class FeishuService {
     })
   }
 
+  /**
+   * Cancel one Session's live turn without resuming anything. Queued
+   * messages stay in the inbox: each already has its own streaming card and
+   * runs next.
+   * @param sessionId The Session to cancel.
+   * @returns Whether a turn was running.
+   */
+  private cancelTurn(sessionId: string): boolean {
+    const agent = this.sessions.get(sessionId)?.agent
+      ?? this.ctx.agents.get(sessionId as SessionId)
+    const running = agent?.status === 'running'
+    agent?.cancel?.({ kind: 'user' }, { keepInbox: true })
+    if (running) this.streamer?.markStopping(sessionId)
+    return running
+  }
+
+  /**
+   * Streaming-card stop button. Only the session owner, clicking inside the
+   * session's own chat, cancels the turn; another operator gets the
+   * owner-only notice on the card instead.
+   */
+  private onStopAction(event: CardActionEvent): void {
+    if (!this.started) return
+    if ((event.action.value as { decision?: unknown } | undefined)?.decision !== STOP_ACTION) return
+    const sessionId = this.streamer?.stopTargetOf(event.messageId)
+    if (sessionId === undefined) return
+    const route = this.routes.findBySession(sessionId)
+    if (route === undefined) return
+    if (event.operator.userId !== route.senderUserId || event.chatId !== route.chatId) {
+      this.streamer?.markStopDenied(sessionId)
+      return
+    }
+    this.cancelTurn(sessionId)
+  }
+
+  /**
+   * Picker-card click: run the chosen `/<command> <arg>` exactly as if the
+   * operator had typed it under the picker card, so access admission, route
+   * ownership and validation are the typed command's. Stale pickers (the
+   * topic was rebound, or the card was forwarded elsewhere) and non-owner
+   * clicks are ignored.
+   */
+  private async onPickAction(event: CardActionEvent): Promise<void> {
+    if (!this.started) return
+    const action = parsePickAction(event.action.value)
+    if (action === undefined) return
+    const route = this.routes.findBySession(action.sessionId)
+    const userId = event.operator.userId
+    if (route === undefined || route.chatId !== event.chatId || userId !== route.senderUserId) return
+    const line = `/${action.command} ${action.arg}`
+    await this.handleSlashMessage({
+      messageId: event.messageId,
+      chatId: route.chatId,
+      chatType: route.chatType,
+      senderId: userId,
+      content: line,
+      rawContentType: 'text',
+      resources: [],
+      mentions: [],
+      mentionAll: false,
+      mentionedBot: true,
+      ...(route.kind === 'thread' ? { threadId: route.key } : {}),
+      createTime: Date.now(),
+    }, line)
+  }
+
   /**
    * `/permissions`: show this Session's effective sandbox+approval preset and
    * the selectable catalog; switch only when the deployment opted in.
@@ -1638,14 +1964,27 @@ export class FeishuService {
     const live = await this.sessions.ensureLive(current)
     let active: string | undefined
     let catalogLine = ''
+    let choices: PickerOption[] = []
     try {
       active = presets.current(live.agent.session)
       const catalog = presets.catalog()
       catalogLine = catalog.options.map(option => `\`${option.value}\``).join('、')
+      choices = catalog.options.map(option => ({ label: option.name || option.value, arg: option.value }))
     } catch {
       active = undefined
     }
     const requested = parsed.rawInput.trim()
+    if (requested === '' && this.config.allowPermissionSwitch && choices.length > 0) {
+      await this.delivery.standaloneReply(msg, buildPickerCard({
+        title: '🔐 权限预设',
+        command: 'permissions',
+        text: `**当前权限预设**：${active === undefined ? '暂无数据' : `\`${active}\``}\n切换会同时调整沙箱与审批策略。`,
+        sessionId: current.sessionId,
+        options: choices,
+        ...(active === undefined ? {} : { current: active }),
+      }))
+      return
+    }
     if (requested === '') {
       const lines = [
         `**当前权限预设**：${active === undefined ? '暂无数据' : `\`${active}\``}`,
@@ -1772,6 +2111,7 @@ export class FeishuService {
     }
     await this.renderCommandResult({
       spec, msg, current, live,
+      bare: parsed.rawInput.trim() === '',
       result: execution.result,
       compactBefore,
       renewAdmission,
@@ -1786,6 +2126,8 @@ export class FeishuService {
     msg: NormalizedMessage
     current: RouteRecord
     live: LiveAgent
+    /** The command was typed without arguments. */
+    bare: boolean
     result: CommandResult
     compactBefore: ContextMeasurement | undefined
     renewAdmission: RenewAdmission | undefined
@@ -1795,6 +2137,17 @@ export class FeishuService {
     const { spec, msg, current, live, result, compactBefore, renewAdmission, effortAdmission, modelAdmission } = input
     if (spec.name === 'effort') effortAdmission?.controller.sync(live.agent.session.snapshotEvents())
     if (spec.name === 'model') modelAdmission?.controller.sync(live.agent.session.snapshotEvents())
+    if (input.bare && result.kind === 'success') {
+      const picker = spec.name === 'model' && modelAdmission !== undefined
+        ? await this.modelPicker(current, live, modelAdmission)
+        : spec.name === 'effort' && effortAdmission !== undefined
+          ? await this.effortPicker(current, live, effortAdmission, result.text ?? '')
+          : undefined
+      if (picker !== undefined) {
+        await this.delivery.standaloneReply(msg, picker)
+        return
+      }
+    }
     if (spec.name === 'renew' && result.kind === 'success' && renewAdmission?.commit !== undefined) {
       await this.delivery.standaloneReply(msg, buildRenewCard({
         previousSessionId: renewAdmission.commit.previous.sessionId,
@@ -2018,7 +2371,7 @@ export class FeishuService {
 
 
   /**
-   * GC pass over the routing domain. Two independent halves:
+   * GC pass over the routing domain. Two independent parts:
    *
    * 1. Dedup records (unconditional): `processed` records and in-process
    *    guard entries older than `PROCESSED_RETENTION_MS` are dropped —
@@ -2077,6 +2430,7 @@ export class FeishuService {
           } else {
             await this.routes.remove(key)
           }
+          this.attachmentFetchTools.forgetRoute(key)
           removedRoutes++
         } catch (error) {
           this.ctx.logger?.warn?.('dsh-channels: GC of route %s failed: %s', key, String(error))
@@ -2084,6 +2438,19 @@ export class FeishuService {
       }
     }
 
+    // Reconcile the attachment-fetch whitelist with the active route set: the
+    // inbound TTL path retires a thread route directly (tombstone), so its
+    // in-memory whitelist bucket would otherwise live until process exit.
+    const droppedToolRoutes = this.attachmentFetchTools.pruneRoutes(
+      routeKey => this.routes.get(routeKey) !== undefined,
+    )
+    if (droppedToolRoutes > 0) {
+      this.ctx.logger?.info?.(
+        'dsh-channels: record GC dropped %d stale attachment-tool route bucket(s)',
+        droppedToolRoutes,
+      )
+    }
+
     const inflight = this.domain?.inflight
     if (inflight !== undefined) {
       for (const [key, snapshot] of [...inflight.entries()]) {
@@ -2118,7 +2485,7 @@ export class FeishuService {
       chatId: record.chatId,
       cardMessageId: record.cardMessageId,
       inThread: record.kind === 'thread',
-      senderOpenId: record.senderOpenId,
+      senderUserId: record.senderUserId,
     }
   }
 
@@ -2138,22 +2505,10 @@ export class FeishuService {
     if (admission.live.agent !== invocation.agent) {
       return { kind: 'error', text: '/model 只能通过已授权的飞书话题执行。' }
     }
-    const session = invocation.agent.session
-    const state = admission.controller.state
-    const header = session.requestHeader?.()?.config
-    const currentProvider = state.effectiveModel?.provider
-      ?? (typeof header?.provider === 'string' && header.provider !== '' ? header.provider : undefined)
-    const currentModel = state.effectiveModel?.model
-      ?? (typeof header?.model === 'string' && header.model !== '' ? header.model : undefined)
-    const source = state.modelSource === 'session'
-      ? 'Session 覆盖'
-      : state.modelSource === 'config' ? '配置默认' : '部署默认'
+    const { provider: currentProvider, model: currentModel } = currentModelRoute(admission.live, admission.controller)
 
     if (rawInput === '') {
-      const lines = [
-        `**当前模型**：${currentModel === undefined ? '尚无模型请求记录' : `\`${currentModel}\``}`
-          + `${currentProvider === undefined ? '' : `（provider \`${currentProvider}\`）`} · ${source}`,
-      ]
+      const lines = [currentModelLine(admission.live, admission.controller)]
       const models = await this.listModels(currentProvider)
       if (models.length > 0) {
         lines.push(`**可选模型（${models.length}）**：${models.slice(0, 20).map(id => `\`${id}\``).join('、')}`
@@ -2190,6 +2545,59 @@ export class FeishuService {
     return { kind: 'success', text: `当前 Session 模型已切换为 \`${label}\`（下一条消息生效）。` }
   }
 
+  /** `/model` picker: the provider's advertised models, or undefined when none are listed. */
+  private async modelPicker(
+    current: RouteRecord,
+    live: LiveAgent,
+    admission: ModelAdmission,
+  ): Promise<object | undefined> {
+    const route = currentModelRoute(live, admission.controller)
+    const models = await this.listModels(route.provider)
+    if (models.length === 0) return undefined
+    return buildPickerCard({
+      title: '🧠 模型',
+      command: 'model',
+      text: `${currentModelLine(live, admission.controller)}\n切换在下一条消息生效。`,
+      sessionId: current.sessionId,
+      options: models.map(id => ({ label: id, arg: id })),
+      ...(route.model === undefined ? {} : { current: route.model }),
+      reset: true,
+    })
+  }
+
+  /**
+   * `/effort` picker: the efforts the current model route advertises, or
+   * undefined when the route is unknown or advertises none.
+   */
+  private async effortPicker(
+    current: RouteRecord,
+    live: LiveAgent,
+    admission: EffortAdmission,
+    text: string,
+  ): Promise<object | undefined> {
+    const route = currentModelRoute(live, admission.controller)
+    if (route.provider === undefined || route.model === undefined) return undefined
+    let reasoning: LlmModelInfo['reasoning']
+    try {
+      const llm = this.ctx.get?.('llm') as LlmService | undefined
+      reasoning = (await llm?.resolveModelInfo(route.provider, route.model))?.reasoning
+    } catch (error) {
+      this.ctx.logger?.warn?.('dsh-channels: effort catalog lookup failed: %s', String(error))
+      return undefined
+    }
+    if (reasoning === undefined || reasoning.efforts.length === 0) return undefined
+    const active = admission.controller.state.effectiveEffort ?? reasoning.defaultEffort
+    return buildPickerCard({
+      title: '💭 推理强度',
+      command: 'effort',
+      text,
+      sessionId: current.sessionId,
+      options: reasoning.efforts.map(effort => ({ label: effort.name || effort.id, arg: effort.id })),
+      ...(active === undefined ? {} : { current: active }),
+      reset: true,
+    })
+  }
+
   /** Model ids advertised for one provider route (empty when unavailable). */
   private async listModels(provider: string | undefined): Promise<string[]> {
     if (provider === undefined) return []
@@ -2330,3 +2738,28 @@ export class FeishuService {
     }
   }
 }
+
+/** The model route the next request of a Session uses, as far as it is known. */
+function currentModelRoute(
+  live: LiveAgent,
+  controller: RequestPolicyController,
+): { provider: string | undefined; model: string | undefined } {
+  const state = controller.state
+  const header = live.agent.session.requestHeader?.()?.config
+  return {
+    provider: state.effectiveModel?.provider
+      ?? (typeof header?.provider === 'string' && header.provider !== '' ? header.provider : undefined),
+    model: state.effectiveModel?.model
+      ?? (typeof header?.model === 'string' && header.model !== '' ? header.model : undefined),
+  }
+}
+
+/** `**当前模型**：…` line shared by the `/model` text answer and its picker. */
+function currentModelLine(live: LiveAgent, controller: RequestPolicyController): string {
+  const { provider, model } = currentModelRoute(live, controller)
+  const source = controller.state.modelSource === 'session'
+    ? 'Session 覆盖'
+    : controller.state.modelSource === 'config' ? '配置默认' : '部署默认'
+  return `**当前模型**：${model === undefined ? '尚无模型请求记录' : `\`${model}\``}`
+    + `${provider === undefined ? '' : `（provider \`${provider}\`）`} · ${source}`
+}