@modesto_ma/dsh-channels 0.4.0 → 0.5.0-beta.2

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, PendingAttachmentRecord,
-  PendingAttachmentsTable, 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'
@@ -66,8 +62,10 @@ 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 { PendingAttachmentStore } from './feishu/pending-attachments.ts'
 import { AttachmentFetchToolRuntime, TopicMessagesToolRuntime } from './feishu/tools.ts'
+import { SendFileToolRuntime } from './feishu/send-file.ts'
+import { WikiConsent } from './feishu/wiki/consent.ts'
+import { WikiToolRuntime } from './feishu/wiki/tools.ts'
 import type { KnownAttachmentMessageInput, KnownAttachmentSource } from './feishu/tools.ts'
 import {
   MessageReader, TOPIC_MESSAGES_MAX_LIMIT, buildHistoryContextBlock,
@@ -78,7 +76,8 @@ 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 {
@@ -95,11 +94,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 { 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'
-import { legacyTopicWorkspaceRoot } from './workspaces.ts'
 
 /** Periodic route-GC sweep cadence (a long-running instance also accumulates
  *  dead records; TTL semantics make 6 h granularity more than sufficient). */
@@ -108,9 +108,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 {
@@ -139,29 +148,7 @@ async function openFeishuDomain(ctx: HostContext): Promise<FeishuDomainHandle> {
   const accessGroupsRaw = domain.table('access_groups')
   const accessUsersRaw = domain.table('access_users')
   const accessRequestsRaw = domain.table('access_requests')
-  // Pending attachment metadata is a table ADDED to the domain at the same
-  // version (see `pendingAttachmentRecordSchema`); hosts that cannot accept the
-  // addition leave this undefined and the registry degrades to its memory TTL
-  // fallback without taking the whole storage domain down.
-  let pendingAttachmentsRaw: ReturnType<RawDomainHandle['table']> | undefined
-  try {
-    pendingAttachmentsRaw = domain.table('pending_attachments')
-  } catch (error) {
-    ctx.logger?.warn?.('dsh-channels: pending attachment table unavailable: %s', String(error))
-  }
-  const pendingAttachments: PendingAttachmentsTable | undefined = pendingAttachmentsRaw === undefined
-    ? undefined
-    : {
-      get: key => pendingAttachmentsRaw.get(key) as PendingAttachmentRecord | undefined,
-      put: (key, value) => pendingAttachmentsRaw.put(key, value),
-      update: (key, fn) => pendingAttachmentsRaw.update(
-        key,
-        current => fn(current as PendingAttachmentRecord),
-      ),
-      delete: key => pendingAttachmentsRaw.delete(key),
-      entries: () =>
-        pendingAttachmentsRaw.entries() as IterableIterator<[string, PendingAttachmentRecord]>,
-    }
+  const accessWikiUsersRaw = domain.table('access_wiki_users')
   return {
     routes: {
       get: key => table.get(key) as RouteRecord | undefined,
@@ -205,13 +192,21 @@ async function openFeishuDomain(ctx: HostContext): Promise<FeishuDomainHandle> {
       delete: key => accessRequestsRaw.delete(key),
       entries: () => accessRequestsRaw.entries() as IterableIterator<[string, AccessRequestRecord]>,
     },
-    pendingAttachments,
+    accessWikiUsers: {
+      get: key => accessWikiUsersRaw.get(key) as AccessUserRecord | undefined,
+      put: (key, value) => accessWikiUsersRaw.put(key, value),
+      delete: key => accessWikiUsersRaw.delete(key),
+      entries: () => accessWikiUsersRaw.entries() as IterableIterator<[string, AccessUserRecord]>,
+    },
     getGlobal: () => (domain.global.get() ?? {}) as FeishuDomainGlobal,
     setGlobal: value => domain.global.set(value),
     close: () => domain.close(),
   }
 }
 
+/** `/auth wiki` usage line (input-error card). */
+const AUTH_WIKI_USAGE = '用法：/auth wiki add <@用户|user_id> 或 /auth wiki remove <@用户|user_id>。知识库白名单里的用户（以及管理员）发起的话题可以使用知识库工具。'
+
 /**
  * Resolve one credential reference through the host credentials seam.
  *
@@ -239,52 +234,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. */
@@ -313,12 +262,6 @@ export class FeishuService {
    * fallback when the host does not mount `ctx.attachments`.
    */
   private readonly inboundAttachmentStore: InboundAttachmentStore
-  /**
-   * Silently registered attachment metadata (`pending_attachments` table):
-   * admission-layer registration, prompt manifest reads, fetch authorization
-   * whitelist, and the TTL/cap sweep wired into the periodic record GC.
-   */
-  private readonly pendingAttachments: PendingAttachmentStore
   /**
    * Read-only Feishu message access (P2): the quoted-message excerpt and the
    * first-turn topic history. Constructed before the inbound router so the
@@ -336,6 +279,9 @@ export class FeishuService {
    */
   private readonly attachmentFetchTools: AttachmentFetchToolRuntime
   private readonly topicMessagesTools: TopicMessagesToolRuntime
+  private readonly sendFileTools: SendFileToolRuntime
+  private readonly wikiConsent: WikiConsent
+  private readonly wikiTools: WikiToolRuntime
   /** 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. */
@@ -369,10 +315,6 @@ export class FeishuService {
   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`). */
@@ -389,6 +331,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,
@@ -430,13 +383,16 @@ export class FeishuService {
         //
         // 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`. Both mounts start
-        // together and resolve as one promise (no serial blocking).
+        // 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))
+        mounts.push(this.wikiTools.mount(agentCtx, sessionId))
         return Promise.all(mounts).then(() => undefined)
       },
       warn: (message, ...args) => this.ctx.logger?.warn?.(message, ...args),
@@ -457,18 +413,9 @@ export class FeishuService {
       archive: this.attachments,
       warn: (message, ...args) => this.ctx.logger?.warn?.(message, ...args),
     })
-    this.pendingAttachments = new PendingAttachmentStore({
-      // Undefined storage domain/table → the registry's memory TTL fallback.
-      table: () => this.domain?.pendingAttachments,
-      enabled: () => this.config.acceptAttachments,
-      ttlMs: () => this.config.pendingAttachmentTtlMs,
-      maxPerScope: () => this.config.pendingAttachmentLimit,
-      warn: (message, ...args) => this.ctx.logger?.warn?.(message, ...args),
-    })
     this.attachmentFetchTools = new AttachmentFetchToolRuntime({
       config: () => this.config,
       channel: () => this.channel,
-      pending: () => this.pendingAttachments,
       routeOfSession: sessionId => {
         const record = this.routes.findBySession(sessionId)
         if (record === undefined) return undefined
@@ -477,7 +424,7 @@ export class FeishuService {
           kind: record.kind,
           chatId: record.chatId,
           chatType: record.chatType,
-          senderOpenId: record.senderOpenId,
+          senderUserId: record.senderUserId,
         }
       },
       warn: (message, ...args) => this.ctx.logger?.warn?.(message, ...args),
@@ -493,7 +440,7 @@ export class FeishuService {
           kind: record.kind,
           chatId: record.chatId,
           chatType: record.chatType,
-          senderOpenId: record.senderOpenId,
+          senderUserId: record.senderUserId,
         }
       },
       noteKnownMessage: (route, message, source) => {
@@ -505,6 +452,35 @@ export class FeishuService {
       fetchAvailable: () => this.effectiveAttachmentBackend() === 'native',
       warn: (message, ...args) => this.ctx.logger?.warn?.(message, ...args),
     })
+    this.wikiConsent = new WikiConsent({
+      channel: () => (this.started ? this.channel : undefined),
+      timeoutMs: () => this.config.approvalTimeoutMs,
+      onError: (sessionId, error) => {
+        this.ctx.logger?.warn?.('dsh-channels wiki consent error (session %s): %s', sessionId, String(error))
+      },
+    })
+    this.wikiTools = new WikiToolRuntime({
+      config: () => this.config,
+      channel: () => (this.started ? this.channel : undefined),
+      routeOfSession: sessionId => this.approvalRouteFor(sessionId),
+      mayUseWiki: userId => this.accessController.isAdmin(userId) || this.accessStore.hasWikiUser(userId),
+      consent: this.wikiConsent,
+      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,
@@ -516,7 +492,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),
@@ -543,7 +519,6 @@ export class FeishuService {
       attachmentMode: () => this.config.attachmentStore,
       nativeAttachments: () => this.nativeAttachmentService(),
       attachmentStore: this.inboundAttachmentStore,
-      pendingAttachments: this.pendingAttachments,
       noteKnownAttachments: (record, message, source) => {
         this.noteKnownAttachmentMessage(record, message, source ?? 'trigger')
       },
@@ -561,6 +536,7 @@ export class FeishuService {
       queue: this.routeOperations,
       streamer: () => this.streamer,
       questionAnswerer: () => this.questionAnswerer,
+      approvalAnswerer: () => this.approvalAnswerer,
       commands: { handleSlash: (msg, line) => this.handleSlashMessage(msg, line) },
     })
   }
@@ -603,8 +579,8 @@ export class FeishuService {
    * 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 messages
-   * visible in the durable pending-attachment registry. Registering is a pure
+   * 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(
@@ -617,7 +593,7 @@ export class FeishuService {
       kind: record.kind,
       chatId: record.chatId,
       chatType: record.chatType,
-      senderOpenId: record.senderOpenId,
+      senderUserId: record.senderUserId,
     }, message, source)
   }
 
@@ -633,7 +609,7 @@ export class FeishuService {
       kind: record.kind,
       chatId: record.chatId,
       chatType: record.chatType,
-      senderOpenId: record.senderOpenId,
+      senderUserId: record.senderUserId,
     }
   }
 
@@ -907,7 +883,6 @@ export class FeishuService {
    */
   applyOverlay(overlay: OverlayPatch): void {
     this.replaceConfig(mergeOverlay(this.baseConfig, overlay))
-    this.refreshRetentionTimer()
   }
 
   /**
@@ -956,15 +931,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,
@@ -973,7 +950,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,
@@ -990,7 +967,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
       }),
@@ -1001,8 +978,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({
@@ -1032,15 +1009,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,
@@ -1054,9 +1031,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() }
@@ -1069,8 +1046,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 }
@@ -1080,276 +1057,193 @@ 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)
-        this.attachmentFetchTools.forgetRoute(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,
+        wikiRead: this.config.feishuTools.wikiRead && this.config.wikiRoots.length > 0,
+        wikiWrite: this.config.feishuTools.wikiWrite && this.config.wikiRoots.length > 0,
+      })
+      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. */
@@ -1481,6 +1375,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 })
@@ -1500,7 +1397,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),
@@ -1518,10 +1415,16 @@ export class FeishuService {
       void accessRequests.onCardAction(event)
       answerer.onCardAction(event)
       questions.onCardAction(event)
+      this.wikiConsent.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.
@@ -1537,7 +1440,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))
@@ -1554,8 +1465,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',
@@ -1571,11 +1480,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，管理员已配置')
     }
@@ -1624,15 +1537,12 @@ export class FeishuService {
     this.approvalAnswerer?.dispose()
     this.approvalAnswerer = undefined
     this.questionAnswerer?.dispose()
+    this.wikiConsent.dispose()
     this.questionAnswerer = undefined
     if (this.gcTimer !== undefined) {
       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()
@@ -1645,10 +1555,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 -------------------------------------------------
@@ -1722,7 +1638,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: '无权操作此会话。',
       })
@@ -1732,7 +1648,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: '无权操作此会话。',
         })
@@ -1765,12 +1681,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>`。',
+          `**白名单**：群 ${groups.length} 个 · 用户 ${users.length} 个 · 知识库 ${this.accessStore.wikiUserRecords().length} 个 · 待处理申请 ${pending.length} 个`,
+          '群授权：`/auth allow` 或 `/auth revoke`（在目标群内发）；用户授权：`/auth user add @用户` 或 `/auth user add <user_id>`；知识库授权：`/auth wiki add @用户`。',
         ]), direct)
         return
       }
@@ -1817,35 +1733,78 @@ 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
+      }
+      if (action === 'wiki') {
+        const sub = words[1]
+        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: target.reason === 'usage' ? AUTH_WIKI_USAGE : 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.hasWikiUser(userId)) {
+            await this.delivery.commandCard(msg, {
+              kind: 'success', command: 'auth', text: `该用户已在知识库白名单中：${label}。`,
+            }, direct)
+            return
+          }
+          await this.accessStore.addWikiUser({
+            userId,
+            ...(target.name === undefined ? {} : { name: target.name }),
+            source: 'command', addedBy: msg.senderId, addedAt: now,
+          })
+          await this.delivery.commandCard(msg, {
+            kind: 'success', command: 'auth',
+            text: `✅ 已把 ${label} 加入知识库白名单：他发起的话题里可以使用知识库工具（每次读取、新建、修改仍需他在授权卡上确认）。`,
+          }, direct)
+          return
+        }
+        const removed = await this.accessStore.removeWikiUser(userId)
+        await this.delivery.commandCard(msg, {
+          kind: removed ? 'success' : 'unavailable', command: 'auth',
+          text: removed ? `已把 ${label} 移出知识库白名单，立即生效。` : `用户 ${label} 不在知识库白名单中。`,
         }, direct)
         return
       }
@@ -1858,19 +1817,25 @@ 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}\``)
+        const wikiUsers = this.accessStore.wikiUserRecords()
+        const wikiLines = wikiUsers.length === 0
+          ? ['（暂无；管理员始终可用）']
+          : wikiUsers.slice(0, 30).map(user => `- ${user.name ?? user.userId} \`${user.userId}\``)
         await this.delivery.standaloneReply(msg, standaloneInfoCard('**🔐 访问授权清单**', [
           `**已授权群（${groups.length}）**`,
           ...groupLines,
           `**已授权用户（${users.length}）**`,
           ...userLines,
+          `**知识库白名单（${wikiUsers.length}）**`,
+          ...wikiLines,
           `**待处理申请**：${pending.length} 个（可在 Web 设置面板处理）`,
         ]), direct)
         return
       }
       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>|wiki add <@用户|user_id>|wiki remove <@用户|user_id>]',
       }, direct)
     } catch (error) {
       this.ctx.logger?.warn?.('dsh-channels: /auth failed: %s', String(error))
@@ -1979,10 +1944,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 ? '已请求停止当前回合。' : '当前没有正在运行的回合。',
@@ -1995,6 +1957,73 @@ 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. The result replaces
+   * the picker card in place instead of arriving as a new card. 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.delivery.replacingCard(event.messageId, () => 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.
@@ -2015,14 +2044,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}\``}`,
@@ -2149,6 +2191,7 @@ export class FeishuService {
     }
     await this.renderCommandResult({
       spec, msg, current, live,
+      bare: parsed.rawInput.trim() === '',
       result: execution.result,
       compactBefore,
       renewAdmission,
@@ -2163,6 +2206,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
@@ -2172,6 +2217,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,
@@ -2181,7 +2237,7 @@ export class FeishuService {
       return
     }
     if (spec.name === 'health' && result.kind === 'success') {
-      await this.delivery.standaloneReply(msg, buildHealthCard(this.healthSnapshot()))
+      await this.delivery.standaloneReply(msg, buildHealthCard(this.healthSnapshot()), { createThread: false })
       return
     }
     if (spec.name === 'status' && result.kind === 'success') {
@@ -2395,18 +2451,13 @@ export class FeishuService {
 
 
   /**
-   * GC pass over the routing domain. Three independent parts:
+   * 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 —
    *    redelivery windows are minutes, so a day of retention is ample and
    *    keeps the table bounded regardless of the route TTL setting.
-   * 2. Pending attachment metadata (unconditional): rows past
-   *    `pendingAttachmentTtlMs` and rows above `pendingAttachmentLimit` per
-   *    `(chat, thread?, sender)` scope are removed. Independent of the route
-   *    TTL: the registry keeps its own 7-day default even when route retirement
-   *    is disabled.
-   * 3. Route/inflight GC (`routeTtlMs > 0`): thread routes idle past the TTL
+   * 2. Route/inflight GC (`routeTtlMs > 0`): thread routes idle past the TTL
    *    are retired into minimal persistent tombstones before their active
    *    records are deleted. A later message in that visible topic is then
    *    rejected instead of silently creating a context-free Session. Degraded
@@ -2439,18 +2490,6 @@ export class FeishuService {
     }
     this.inbound.pruneAccepted(processedCutoff)
 
-    try {
-      const pruned = await this.pendingAttachments.prune()
-      if (pruned.removedExpired > 0 || pruned.removedOverLimit > 0) {
-        this.ctx.logger?.info?.(
-          'dsh-channels: record GC removed %d expired and %d over-limit pending attachment record(s)',
-          pruned.removedExpired, pruned.removedOverLimit,
-        )
-      }
-    } catch (error) {
-      this.ctx.logger?.warn?.('dsh-channels: pending attachment GC failed: %s', String(error))
-    }
-
     const ttlMs = this.config.routeTtlMs
     if (ttlMs === 0) {
       if (removedProcessed > 0) {
@@ -2526,7 +2565,7 @@ export class FeishuService {
       chatId: record.chatId,
       cardMessageId: record.cardMessageId,
       inThread: record.kind === 'thread',
-      senderOpenId: record.senderOpenId,
+      senderUserId: record.senderUserId,
     }
   }
 
@@ -2546,22 +2585,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('、')}`
@@ -2598,6 +2625,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 []
@@ -2738,3 +2818,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}`
+}