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

package/src/client/panel/connection-tab.tsx

@@ -6,12 +6,13 @@
  * - error：连接信息卡 + 最近一次连接失败 + 「重试」
  * - connected：连接信息卡 + 「重启飞书连接」+ 凭据卡
  * - connecting：禁用按钮显示「连接中…」
+ * - 已连接且权限自检完成：权限自检卡（缺失权限红字 + 开发者后台深链）
  *
  * @module dsh-channels/client/panel/connection-tab
  */
 
 import { PANEL_COPY } from '../../settings/contract.ts'
-import type { ChannelStatusWire, PanelWire } from '../../settings/contract.ts'
+import type { ChannelStatusWire, PanelWire, ScopeCheckWire, SlashCommandSyncWire } from '../../settings/contract.ts'
 import { CredentialsCard } from './credentials-card.tsx'
 import { connectionStateLabel, fieldLabel, formatUptime, phaseBadge, TabHelp } from './shared.tsx'
 import type { BusyAction, CredentialsView } from './shared.tsx'
@@ -35,6 +36,8 @@ export function ConnectionTab(props: ConnectionTabProps): JSX.Element {
       {status.phase === 'unconfigured'
         ? <OnboardingCard status={status} />
         : <ConnectionInfoCard status={status} busy={busy} onReconnect={onReconnect} />}
+      {status.scopeCheck === undefined ? null : <ScopeCheckCard check={status.scopeCheck} />}
+      {status.slashCommandSync === undefined ? null : <SlashCommandSyncCard sync={status.slashCommandSync} />}
       <CredentialsCard panel={panel} credentials={credentials} />
     </div>
   )
@@ -186,6 +189,72 @@ function ConnectionInfoCard(props: {
   )
 }
 
+/** Post-connect scope self-check: missing scopes in red, each with a console deep link. */
+function ScopeCheckCard(props: { check: ScopeCheckWire }): JSX.Element {
+  const { check } = props
+  return (
+    <section className="dsh-channels-cfg__card">
+      <div className="dsh-channels-cfg__cardHead">
+        <span className="dsh-channels-cfg__cardTitle">{PANEL_COPY.scopeCheckTitle}</span>
+      </div>
+      {check.state === 'ok'
+        ? <div className="dsh-channels-cfg__notice dsh-channels-cfg__notice--ok">{PANEL_COPY.scopeCheckOk}</div>
+        : null}
+      {check.state === 'error'
+        ? (
+            <div className="dsh-channels-cfg__notice dsh-channels-cfg__notice--error">
+              <strong>{PANEL_COPY.scopeCheckError}</strong>
+              <span className="dsh-channels-cfg__mono">{check.error}</span>
+            </div>
+          )
+        : null}
+      {check.state === 'missing'
+        ? (
+            <div className="dsh-channels-cfg__notice dsh-channels-cfg__notice--error">
+              <strong>{PANEL_COPY.scopeCheckMissing}</strong>
+              <ul className="dsh-channels-cfg__scopeList">
+                {check.missing.map(item => (
+                  <li key={item.scopes.join(',')}>
+                    <span>[{item.level === 'required' ? PANEL_COPY.scopeCheckRequired : PANEL_COPY.scopeCheckOptional}] </span>
+                    <span className="dsh-channels-cfg__mono">{item.scopes.join(' / ')}</span>
+                    <span>：{item.purpose} </span>
+                    <a href={item.consoleUrl} target="_blank" rel="noreferrer noopener">{PANEL_COPY.scopeCheckOpenOne}</a>
+                  </li>
+                ))}
+              </ul>
+              <a href={check.consoleUrl} target="_blank" rel="noreferrer noopener">{PANEL_COPY.scopeCheckOpenAll}</a>
+            </div>
+          )
+        : null}
+    </section>
+  )
+}
+
+/** Post-connect native slash-command panel sync: counts on success, the Feishu reason on failure. */
+function SlashCommandSyncCard(props: { sync: SlashCommandSyncWire }): JSX.Element {
+  const { sync } = props
+  return (
+    <section className="dsh-channels-cfg__card">
+      <div className="dsh-channels-cfg__cardHead">
+        <span className="dsh-channels-cfg__cardTitle">{PANEL_COPY.slashCommandSyncTitle}</span>
+      </div>
+      {sync.state === 'ok'
+        ? (
+            <div className="dsh-channels-cfg__notice dsh-channels-cfg__notice--ok">
+              <span>{PANEL_COPY.slashCommandSyncOk} </span>
+              <span>{PANEL_COPY.slashCommandSyncTotal} {sync.total} · {PANEL_COPY.slashCommandSyncCreated} {sync.created} · {PANEL_COPY.slashCommandSyncUpdated} {sync.updated} · {PANEL_COPY.slashCommandSyncRemoved} {sync.removed}</span>
+            </div>
+          )
+        : (
+            <div className="dsh-channels-cfg__notice dsh-channels-cfg__notice--error">
+              <strong>{PANEL_COPY.slashCommandSyncError}</strong>
+              <span className="dsh-channels-cfg__mono">{sync.error}</span>
+            </div>
+          )}
+    </section>
+  )
+}
+
 /** Config saved but only applied on the next connect: offer the one-click restart. */
 function RestartBanner(props: {
   panel: PanelWire

package/src/client/panel/index.tsx

@@ -2,8 +2,8 @@
  * 设置 →「飞书渠道」页面：数据加载、5 秒状态轮询、全局 draft 与顶部状态头 /
  * tab 导航的外壳。
  *
- * 所有 Host 交互（panel / status / catalog / config / credentials / cleanup /
- * access / pick-directory）都集中在这里；tab 组件只接收渲染所需的数据与
+ * 所有 Host 交互（panel / status / catalog / config / credentials / access /
+ * pick-directory）都集中在这里；tab 组件只接收渲染所需的数据与
  * 回调。页面不 import 任何 DSH 客户端包，只依赖 react 与 `settings.section`
  * 槽位。
  *
@@ -17,7 +17,6 @@ import type {
   AccessWire,
   CatalogWire,
   ChannelStatusWire,
-  CleanupRunWire,
   ConfigValue,
   CredentialField,
   EditableKey,
@@ -39,7 +38,6 @@ import {
   removeAccessGroup,
   removeAccessUser,
   resolveAccessRequest,
-  runCleanup,
   saveConfig,
   saveCredentials,
 } from '../api.ts'
@@ -51,7 +49,6 @@ import { ModelTab } from './model-tab.tsx'
 import { SessionsTab } from './sessions-tab.tsx'
 import {
   fieldLabel,
-  formatBytes,
   messageOf,
   NoticeBar,
   phaseBadge,
@@ -85,8 +82,6 @@ export function FeishuChannelsSection(_props: FeishuChannelsSectionProps): JSX.E
   const [appSecretInput, setAppSecretInput] = useState('')
   const [catalog, setCatalog] = useState<CatalogWire | null>(null)
   const [catalogBusy, setCatalogBusy] = useState(false)
-  const [cleanupResult, setCleanupResult] = useState<CleanupRunWire | null>(null)
-  const [cleanupError, setCleanupError] = useState<string | null>(null)
   const [accessNotice, setAccessNotice] = useState<string | null>(null)
   const [accessError, setAccessError] = useState<string | null>(null)
   const catalogTicket = useRef(0)
@@ -102,8 +97,6 @@ export function FeishuChannelsSection(_props: FeishuChannelsSectionProps): JSX.E
   const loadPanel = useCallback(async (): Promise<void> => {
     setLoad({ phase: 'loading' })
     setNotice(null)
-    setCleanupResult(null)
-    setCleanupError(null)
     setAccessNotice(null)
     setAccessError(null)
     try {
@@ -145,7 +138,7 @@ export function FeishuChannelsSection(_props: FeishuChannelsSectionProps): JSX.E
         setPollError(null)
         // A phase transition changes what the panel payload can offer: the
         // storage domain opens/closes with the connection, so the access
-        // whitelists and the cleanup preview go stale. Re-read the panel but
+        // whitelists go stale. Re-read the panel but
         // never touch the dirty draft.
         if (previousPhase !== undefined && previousPhase !== next.phase) {
           try {
@@ -260,8 +253,8 @@ export function FeishuChannelsSection(_props: FeishuChannelsSectionProps): JSX.E
   }, [])
 
   /**
-   * Manual refresh: reload the whole panel payload so access lists, the cleanup
-   * preview and `restartPendingKeys` catch up with the Host. The dirty draft is
+   * Manual refresh: reload the whole panel payload so access lists and
+   * `restartPendingKeys` catch up with the Host. The dirty draft is
    * deliberately preserved — refreshing never discards user input.
    */
   const onRefresh = useCallback(async (): Promise<void> => {
@@ -301,8 +294,6 @@ export function FeishuChannelsSection(_props: FeishuChannelsSectionProps): JSX.E
       }
       setLoad({ phase: 'ready', panel: result.panel })
       setStatus(result.panel.status)
-      setCleanupResult(null)
-      setCleanupError(null)
       // Clear only the submitted keys: edits typed while the request was in
       // flight stay in the draft instead of being silently discarded.
       setDraft(previous => {
@@ -372,8 +363,6 @@ export function FeishuChannelsSection(_props: FeishuChannelsSectionProps): JSX.E
       setLoad({ phase: 'ready', panel: result.panel })
       setStatus(result.panel.status)
       setDraft({})
-      setCleanupResult(null)
-      setCleanupError(null)
       setNotice({ kind: 'ok', text: PANEL_COPY.cleared })
     } catch (error) {
       setNotice({ kind: 'error', text: messageOf(error) })
@@ -417,40 +406,6 @@ export function FeishuChannelsSection(_props: FeishuChannelsSectionProps): JSX.E
     }
   }, [refreshStatus, running])
 
-  /**
-   * Delete stale workspaces after an explicit confirmation. The Host refreshes
-   * the panel in the same response, so the preview counts update immediately;
-   * partial failures stay visible in the card instead of being swallowed.
-   */
-  const onRunCleanup = useCallback(async (): Promise<void> => {
-    if (panel === null) return
-    const { cleanup } = panel
-    const confirmed = typeof window.confirm === 'function'
-      ? window.confirm(
-        `${PANEL_COPY.cleanupConfirm}\n${PANEL_COPY.cleanupCandidates}：${cleanup.candidates} · ${PANEL_COPY.cleanupCandidateBytes}：${formatBytes(cleanup.candidateBytes)}`,
-      )
-      : true
-    if (!confirmed) return
-    setBusy('cleanup')
-    setNotice(null)
-    setCleanupResult(null)
-    setCleanupError(null)
-    try {
-      const response = await runCleanup()
-      if (!response.ok) {
-        setCleanupError(response.error)
-        return
-      }
-      setLoad({ phase: 'ready', panel: response.panel })
-      setStatus(response.panel.status)
-      setCleanupResult(response.result)
-    } catch (error) {
-      setCleanupError(messageOf(error))
-    } finally {
-      setBusy(null)
-    }
-  }, [panel])
-
   /** Replace the embedded access snapshot after a whitelist mutation. */
   const applyAccess = useCallback((access: AccessWire): void => {
     setLoad(previous => previous.phase === 'ready'
@@ -498,12 +453,12 @@ export function FeishuChannelsSection(_props: FeishuChannelsSectionProps): JSX.E
     }
   }, [applyAccess])
 
-  const onAddAccessUser = useCallback(async (openId: string, name: string): Promise<boolean> => {
+  const onAddAccessUser = useCallback(async (userId: string, name: string): Promise<boolean> => {
     setBusy('access')
     setAccessError(null)
     setAccessNotice(null)
     try {
-      const result = await addAccessUser(openId, name)
+      const result = await addAccessUser(userId, name)
       if (!result.ok) {
         setAccessError(result.error)
         return false
@@ -519,12 +474,12 @@ export function FeishuChannelsSection(_props: FeishuChannelsSectionProps): JSX.E
     }
   }, [applyAccess])
 
-  const onRemoveAccessUser = useCallback(async (openId: string): Promise<void> => {
+  const onRemoveAccessUser = useCallback(async (userId: string): Promise<void> => {
     setBusy('access')
     setAccessError(null)
     setAccessNotice(null)
     try {
-      const result = await removeAccessUser(openId)
+      const result = await removeAccessUser(userId)
       if (!result.ok) {
         setAccessError(result.error)
         return
@@ -729,13 +684,7 @@ export function FeishuChannelsSection(_props: FeishuChannelsSectionProps): JSX.E
         {activeTab === 'model' ? <ModelTab form={form} catalogBusy={catalogBusy} /> : null}
         {activeTab === 'workspace'
           ? (
-              <WorkspaceTab
-                form={form}
-                cleanup={form.panel.cleanup}
-                cleanupResult={cleanupResult}
-                cleanupError={cleanupError}
-                onRunCleanup={() => { void onRunCleanup() }}
-              />
+              <WorkspaceTab form={form} />
             )
           : null}
         {activeTab === 'access'
@@ -747,7 +696,7 @@ export function FeishuChannelsSection(_props: FeishuChannelsSectionProps): JSX.E
                 onAddGroup={onAddAccessGroup}
                 onRemoveGroup={chatId => { void onRemoveAccessGroup(chatId) }}
                 onAddUser={onAddAccessUser}
-                onRemoveUser={openId => { void onRemoveAccessUser(openId) }}
+                onRemoveUser={userId => { void onRemoveAccessUser(userId) }}
                 onResolveRequest={(token, decision) => { void onResolveAccessRequest(token, decision) }}
               />
             )

package/src/client/panel/shared.tsx

@@ -13,7 +13,6 @@ import { FIELD_GROUP_LABELS, PANEL_COPY, TAB_FIELD_GROUPS } from '../../settings
 import type {
   AccessWire,
   ChannelPhaseWire,
-  CleanupPreviewWire,
   ConfigValue,
   CredentialField,
   EditableFieldWire,
@@ -46,7 +45,6 @@ export type BusyAction =
   | 'reconnect'
   | 'credentials'
   | 'credentials-clear'
-  | 'cleanup'
   | 'access'
 
 /** Tone of a small badge; maps onto `dsh-channels-cfg__badge--*` classes. */
@@ -56,20 +54,6 @@ export function messageOf(error: unknown): string {
   return error instanceof Error ? error.message : String(error)
 }
 
-/** Human-readable byte size for the cleanup preview/result (base-2 units). */
-export function formatBytes(bytes: number): string {
-  if (!Number.isFinite(bytes) || bytes <= 0) return '0 B'
-  const units = ['B', 'KB', 'MB', 'GB', 'TB']
-  let value = bytes
-  let unit = 0
-  while (value >= 1024 && unit < units.length - 1) {
-    value /= 1024
-    unit += 1
-  }
-  const digits = unit === 0 || value >= 10 ? 0 : 1
-  return `${value.toFixed(digits)} ${units[unit] ?? 'B'}`
-}
-
 /** Compact duration for the connection card. */
 export function formatUptime(ms: number | undefined): string {
   if (ms === undefined || !Number.isFinite(ms)) return PANEL_COPY.unknownValue
@@ -479,10 +463,3 @@ export function connectionStateLabel(state: string | undefined): { text: string;
     default: return { text: state ?? PANEL_COPY.unknownValue, tone: 'muted' }
   }
 }
-
-/** Retention label, reusing the Host field options so the copy stays on the Host. */
-export function retentionLabel(panel: PanelWire, cleanup: CleanupPreviewWire): string {
-  const field = panel.config.fields.find(item => item.key === 'workspaceRetention')
-  return field?.options?.find(option => option.value === cleanup.retention)?.label
-    ?? (cleanup.retention === 'off' ? PANEL_COPY.cleanupRetentionOff : cleanup.retention)
-}

package/src/client/panel/workspace-tab.tsx

@@ -1,40 +1,24 @@
 /**
- * 「工作区」tab：工作区根目录 / 过期保留策略 / 自动清理字段 + 目录清理卡。
- * 表单保存栏在字段卡正下方，清理卡（独立动作，不走 draft）在其后。
+ * 「工作区」tab：工作区根目录字段与保存栏。
  *
  * @module dsh-channels/client/panel/workspace-tab
  */
 
 import { PANEL_COPY, TAB_FIELD_GROUPS } from '../../settings/contract.ts'
-import type { CleanupPreviewWire, CleanupRunWire } from '../../settings/contract.ts'
-import { CleanupCard } from './cleanup-card.tsx'
 import { FieldsCard, SaveBar, TabHelp } from './shared.tsx'
 import type { FormView } from './shared.tsx'
 
 export interface WorkspaceTabProps {
   form: FormView
-  cleanup: CleanupPreviewWire
-  cleanupResult: CleanupRunWire | null
-  cleanupError: string | null
-  onRunCleanup: () => void
 }
 
 export function WorkspaceTab(props: WorkspaceTabProps): JSX.Element {
-  const { form, cleanup, cleanupResult, cleanupError, onRunCleanup } = props
+  const { form } = props
   return (
     <div className="dsh-channels-cfg__tabBody">
       <TabHelp text={PANEL_COPY.workspaceTabHelp} />
       <FieldsCard form={form} groups={TAB_FIELD_GROUPS.workspace} />
       <SaveBar form={form} tab="workspace" />
-      <CleanupCard
-        panel={form.panel}
-        cleanup={cleanup}
-        busy={form.busy}
-        locked={form.locked}
-        result={cleanupResult}
-        error={cleanupError}
-        onRun={onRunCleanup}
-      />
     </div>
   )
 }

package/src/client/styles.ts

@@ -68,6 +68,8 @@ select.dsh-channels-cfg__input{appearance:auto;cursor:pointer}
 .dsh-channels-cfg__notice{display:flex;flex-direction:column;gap:2px;padding:8px 10px;border-radius:8px;font-size:12px;line-height:18px;overflow-wrap:anywhere}
 .dsh-channels-cfg__notice--ok{color:var(--dsw-alias-state-business-primary,#0a7d33);background:color-mix(in srgb,currentColor 8%,transparent)}
 .dsh-channels-cfg__notice--error{color:var(--dsw-alias-state-danger-primary,#c62828);background:color-mix(in srgb,currentColor 8%,transparent)}
+.dsh-channels-cfg__notice a{color:inherit;text-decoration:underline}
+.dsh-channels-cfg__scopeList{margin:2px 0;padding-left:18px;display:flex;flex-direction:column;gap:2px}
 .dsh-channels-cfg__banner{display:flex;align-items:center;gap:8px;flex-wrap:wrap;padding:8px 10px;border-radius:8px;border:1px dashed var(--dsw-alias-state-warning-primary,#a15c00);color:var(--dsw-alias-state-warning-primary,#a15c00);font-size:12px;line-height:18px}
 .dsh-channels-cfg__footer{display:flex;align-items:center;gap:8px;flex-wrap:wrap;padding-top:2px}
 .dsh-channels-cfg__spacer{flex:1}

package/src/commands/registry.ts

@@ -72,8 +72,8 @@ export const CHANNEL_COMMANDS = [
     usage: '[name]', channelPlane: true, agentScoped: false,
   },
   {
-    name: 'auth', group: '会话', description: '查看/管理访问授权（仅管理员）',
-    usage: '[status|allow|revoke|list|user add <open_id>|user remove <open_id>]',
+    name: 'auth', group: '会话', description: '查看/管理访问授权，可 @ 成员授权（仅管理员）',
+    usage: '[status|allow|revoke|list|user add <@用户|user_id>|user remove <@用户|user_id>]',
     routeFree: true, channelPlane: true, agentScoped: false,
   },
   {

package/src/config.ts

@@ -13,7 +13,7 @@
  */
 
 import { z } from 'zod'
-import { WORKSPACE_RETENTION_VALUES } from './cleanup.ts'
+import { FEISHU_USER_ID_PATTERN } from './domain.ts'
 
 export const FEISHU_LOGGER_LEVELS = ['debug', 'info', 'warn', 'error'] as const
 export type FeishuLoggerLevel = (typeof FEISHU_LOGGER_LEVELS)[number]
@@ -34,6 +34,48 @@ export const DEFAULT_APPROVAL_TIMEOUT_MS = 5 * 60 * 1000
 /** Default structured-question window: 5 minutes per `ask_user_question` call. */
 export const DEFAULT_QUESTION_TIMEOUT_MS = 5 * 60 * 1000
 
+/** Backends for inbound attachment storage, selected by `attachmentStore`. */
+export const ATTACHMENT_STORE_MODES = ['native', 'archive'] as const
+export type AttachmentStoreMode = (typeof ATTACHMENT_STORE_MODES)[number]
+
+/** Default per-call attachment count of `feishu_attachment_fetch`. */
+export const DEFAULT_ATTACHMENT_FETCH_MAX_RESOURCES = 10
+
+/** Default per-call total download budget of `feishu_attachment_fetch` (100 MiB). */
+export const DEFAULT_ATTACHMENT_FETCH_MAX_BYTES = 100 * 1024 * 1024
+
+/** Default whole-call timeout of `feishu_attachment_fetch` (120 s). */
+export const DEFAULT_ATTACHMENT_FETCH_TIMEOUT_MS = 120_000
+
+/** Default per-image byte cap for trigger-message prefetch (20 MiB). */
+export const DEFAULT_PREFETCH_IMAGE_MAX_BYTES = 20 * 1024 * 1024
+
+/** Default total byte budget for one trigger-message image prefetch (50 MiB). */
+export const DEFAULT_PREFETCH_TOTAL_MAX_BYTES = 50 * 1024 * 1024
+
+/** Default short timeout for one trigger-message image prefetch (10 s). */
+export const DEFAULT_PREFETCH_TIMEOUT_MS = 10_000
+
+/**
+ * Default number of recent topic messages attached to a new Session's first
+ * turn (0 disables the history bootstrap). Mirrors
+ * `HISTORY_BOOTSTRAP_DEFAULT` in `feishu/message-read.ts`.
+ */
+export const DEFAULT_HISTORY_BOOTSTRAP_LIMIT = 10
+
+/** Hard cap of the first-turn history bootstrap. */
+export const MAX_HISTORY_BOOTSTRAP_LIMIT = 20
+
+/** Default whole-call timeout of `feishu_topic_messages` (20 s). */
+export const DEFAULT_TOPIC_MESSAGES_TIMEOUT_MS = 20_000
+
+/**
+ * Default budget of one passive prompt-enrichment message read (quoted excerpt
+ * / first-turn topic history). Kept short: the turn must not wait long for an
+ * optional context block.
+ */
+export const DEFAULT_PROMPT_CONTEXT_TIMEOUT_MS = 3_000
+
 /** A credential reference: `FEISHU_APP_ID`-style name resolved through ctx.credentials. */
 const credentialRefSchema = z.string().regex(
   CREDENTIAL_REF_PATTERN,
@@ -55,13 +97,6 @@ export const configSchema = z.object({
    * against the host process cwd.
    */
   baseDir: z.string().min(1).default('./channels-data'),
-  /**
-   * Optional path of the Web settings overlay (default
-   * `$DSH_HOME/dsh-channels/settings.json`). The Web panel writes only
-   * editable fields there; this path is for embedded hosts, tests, or users
-   * who want multiple instances with different overlays.
-   */
-  settingsFile: z.string().min(1).optional(),
   /** LLM provider route for sessions this plugin creates (optional → deployment default). */
   provider: z.string().optional(),
   /** Model id for sessions this plugin creates (optional → deployment default). */
@@ -138,34 +173,155 @@ export const configSchema = z.object({
    */
   approvalTimeoutMs: z.number().int().min(10_000).max(3_600_000).default(DEFAULT_APPROVAL_TIMEOUT_MS),
   /**
-   * Accept inbound Feishu images, files, and merged-forward chat records and
-   * save them below `<workspace>/attachments/`. Nothing is forwarded to the
-   * model automatically: the Agent reads whichever attachment the
-   * conversation needs with its ordinary filesystem tools. Disabled keeps
-   * attachment messages inert (no save, no turn).
+   * Accept inbound Feishu images, files, and merged-forward chat records.
+   *
+   * With the native backend (default) images of the triggering message are
+   * prefetched into the DSH native attachment library and files stay lazy
+   * behind a prompt manifest; with the archive backend the resources are saved
+   * below `<workspace>/attachments/` before the turn, exactly like the legacy
+   * pipeline. Disabled keeps attachment messages inert (no save, no turn, no
+   * manifest rows).
    */
   acceptAttachments: z.boolean().default(true),
   /**
-   * Delete the topic directories of stale conversations, plus legacy
-   * one-workspace-per-topic directories written by older plugin versions.
-   * `off` (default) never deletes; `7d`/`30d`/`90d`/`180d` remove those
-   * directories when their last activity is older than the threshold. User
-   * workspaces themselves are never deleted. The managed Web panel exposes
-   * this as a select, previews the candidates, and can run one cleanup
-   * manually. DSH Session logs are never deleted.
+   * Backend for inbound Feishu images and files.
+   *
+   * - `native` (default): store into the DSH native attachment library
+   *   (`ctx.attachments`) as durable `ImageBlock`/`FileBlock` references; if
+   *   the host does not mount that service, the storage layer falls back to
+   *   `archive` for that deployment.
+   * - `archive`: legacy behavior — write the resources into the topic
+   *   workspace `attachments/` directory through the existing intake.
+   *
+   * Admission consumes this switch through the backend-selecting inbound
+   * store: an explicit `archive` always uses the legacy download path, and a
+   * `native` deployment without the mounted host service degrades to the same
+   * legacy path (see `effectiveAttachmentMode`).
+   */
+  attachmentStore: z.enum(ATTACHMENT_STORE_MODES).default('native'),
+  /**
+   * Prefetch images attached to the triggering message into the first model
+   * turn (native attachment backend only). The session, topic, and streaming
+   * card are already visible before the prefetch starts; the turn only waits
+   * for the (short, bounded) image download, never for file bytes. Failed,
+   * oversized, or timed-out images degrade to a manifest row that the model
+   * can fetch with `feishu_attachment_fetch`. Set `false` to keep every
+   * attachment lazy (images then need the tool as well).
+   */
+  prefetchImages: z.boolean().default(true),
+  /**
+   * Largest single image the trigger-message prefetch buffers in memory before
+   * refusing it (default 20 MiB). A refused image stays in the manifest and
+   * is fetched on demand.
+   */
+  prefetchImageMaxBytes: z.number().int().min(1).max(200 * 1024 * 1024)
+    .default(DEFAULT_PREFETCH_IMAGE_MAX_BYTES),
+  /**
+   * Total byte budget of one trigger-message image prefetch (default 50 MiB).
+   * Once exhausted, the remaining images degrade to the manifest.
+   */
+  prefetchTotalMaxBytes: z.number().int().min(1).max(1024 * 1024 * 1024)
+    .default(DEFAULT_PREFETCH_TOTAL_MAX_BYTES),
+  /**
+   * Short whole-prefetch timeout (default 10 s). On expiry the already-loaded
+   * images stay in the prompt and the rest degrade to the manifest, so a slow
+   * image download never blocks the turn for long.
+   */
+  prefetchTimeoutMs: z.number().int().min(100).max(120_000).default(DEFAULT_PREFETCH_TIMEOUT_MS),
+  /**
+   * Number of recent messages of the current topic automatically attached to
+   * the FIRST turn of a new Session (decision D1: the model should see the
+   * discussion before @ without asking). The `<feishu_history>` block is
+   * bounded and truncated with an explicit marker and each line carries the
+   * message_id needed to fetch a named attachment; older messages remain
+   * reachable through the `feishu_topic_messages` tool. `0` disables the
+   * bootstrap entirely. Reads use a short (~3 s) prompt-enrichment budget and a
+   * failure (missing scope, p2p history unavailable, channel down) degrades
+   * silently: the turn still runs.
    */
-  workspaceRetention: z.enum(WORKSPACE_RETENTION_VALUES).default('off'),
+  historyBootstrapLimit: z.number().int().min(0).max(MAX_HISTORY_BOOTSTRAP_LIMIT)
+    .default(DEFAULT_HISTORY_BOOTSTRAP_LIMIT),
   /**
-   * Run the retention cleanup at startup and once per day. Off by default:
-   * deletion is irreversible, so it stays an explicit opt-in even when a
-   * retention threshold is configured.
+   * Whole-read budget (milliseconds) of the passive prompt enrichment: the
+   * quoted-message excerpt and the first-turn topic history. Deliberately short
+   * (default 3 s) and independent from `feishuTools.topicMessagesTimeoutMs`:
+   * on expiry the block is omitted and the turn runs. Model-initiated reads
+   * through `feishu_topic_messages` use the tool timeout instead.
    */
-  workspaceRetentionAuto: z.boolean().default(false),
+  promptContextTimeoutMs: z.number().int().min(100).max(10_000)
+    .default(DEFAULT_PROMPT_CONTEXT_TIMEOUT_MS),
+  /**
+   * Model-facing Feishu tools.
+   *
+   * - `attachmentFetch` (default on): register `feishu_attachment_fetch` in
+   *   channel sessions so the model can fetch images/files of a known message
+   *   on demand. Registration is skipped (with one warning) on deployments
+   *   without the host `tools` / `attachments` services. Turning it off also
+   *   keeps inbound attachments on the archive backend: lazy native files
+   *   would be unreachable without the tool, so admission downloads them to
+   *   the workspace instead (see `effectiveAttachmentMode`).
+   * - `attachmentFetchMaxResources`: maximum attachments one tool call may
+   *   fetch (1–50). A message with more attachments is refused with a readable
+   *   reason so the model can retry per `file_key`.
+   * - `attachmentFetchMaxBytes`: total download budget of one tool call
+   *   (default 100 MiB). Files stream to the native attachment library, so the
+   *   limit is enforced while streaming rather than buffered first.
+   * - `attachmentFetchTimeoutMs`: whole-call timeout (default 120 s). On expiry
+   *   the in-flight download is cancelled and reported per attachment.
+   * - `topicMessages` (default on): register `feishu_topic_messages` in
+   *   channel sessions so the model can read the quoted message / earlier
+   *   topic messages on demand and authorize their attachments for fetch.
+   *   Reads require the Feishu message-read scopes; a missing scope degrades to
+   *   a readable tool failure and never fails the turn. This switch only
+   *   controls the model-facing tool: the passive `<feishu_quote>` /
+   *   `<feishu_history>` prompt excerpts stay enabled (they are bounded and
+   *   degrade silently) and are configured by `historyBootstrapLimit`. On the
+   *   archive backend the tool is still mounted for history text, while its
+   *   description states that `feishu_attachment_fetch` is unavailable.
+   * - `topicMessagesTimeoutMs`: whole-call timeout of one model-initiated
+   *   topic read (default 20 s). Passive prompt excerpts use a separate short
+   *   (~3 s) budget and never wait this long.
+   * - `sendFile` (default on): register `feishu_send_file` in channel sessions
+   *   so the model can send an image or file from the topic's working
+   *   directory back to the current conversation. Needs the Feishu
+   *   `im:resource` (or `im:resource:upload`) scope; without it a call returns
+   *   a readable failure and the turn continues.
+   *
+   * The Web panel/metrics ship with `panel_docs_release`.
+   */
+  feishuTools: z.object({
+    attachmentFetch: z.boolean().default(true),
+    attachmentFetchMaxResources: z.number().int().min(1).max(50)
+      .default(DEFAULT_ATTACHMENT_FETCH_MAX_RESOURCES),
+    attachmentFetchMaxBytes: z.number().int().min(1).max(1024 * 1024 * 1024)
+      .default(DEFAULT_ATTACHMENT_FETCH_MAX_BYTES),
+    attachmentFetchTimeoutMs: z.number().int().min(1_000).max(600_000)
+      .default(DEFAULT_ATTACHMENT_FETCH_TIMEOUT_MS),
+    topicMessages: z.boolean().default(true),
+    topicMessagesTimeoutMs: z.number().int().min(1_000).max(120_000)
+      .default(DEFAULT_TOPIC_MESSAGES_TIMEOUT_MS),
+    sendFile: z.boolean().default(true),
+  }).default({
+    attachmentFetch: true,
+    attachmentFetchMaxResources: DEFAULT_ATTACHMENT_FETCH_MAX_RESOURCES,
+    attachmentFetchMaxBytes: DEFAULT_ATTACHMENT_FETCH_MAX_BYTES,
+    attachmentFetchTimeoutMs: DEFAULT_ATTACHMENT_FETCH_TIMEOUT_MS,
+    topicMessages: true,
+    topicMessagesTimeoutMs: DEFAULT_TOPIC_MESSAGES_TIMEOUT_MS,
+    sendFile: true,
+  }),
   /**
    * Send a one-time onboarding card on the first private message of a chat
    * (facts + command cheat sheet). Persisted per chat; never repeats.
    */
   welcomeOnboarding: z.boolean().default(true),
+  /**
+   * Sync the command registry to Feishu's native `/` panel on every connect
+   * (needs the `application:app_slash_command:read`/`write` scopes). Off by
+   * default: some tenants forbid apps from adding slash commands. When off,
+   * the plugin neither reads nor writes the panel.
+   */
+  slashCommandPanel: z.boolean().default(false),
   /**
    * Allow `/permissions <name>` to switch this Session's sandbox + approval
    * preset from Feishu. Read-only `/permissions` always works; switching is
@@ -184,15 +340,17 @@ export const configSchema = z.object({
    */
   accessMode: z.enum(['open', 'guarded']).default('guarded'),
   /**
-   * The unique administrator's Feishu open_id (`ou_...`). Set it in the Web
+   * The unique administrator's Feishu `user_id`. Set it in the Web
    * settings panel (or the profile config). Get it by sending `/userid` to the
-   * bot in a private chat. While `accessMode` is `guarded` and this is unset,
-   * every conversation is refused (fail closed); `/userid` and a fixed notice
-   * stay available so the deployment can be bootstrapped.
+   * bot in a private chat. When unset, the Feishu app owner (looked up via
+   * `application.v6.application.get` at connect; needs an app-info read scope)
+   * is the administrator. While `accessMode` is `guarded` and neither is
+   * available, every conversation is refused (fail closed); `/userid` and a
+   * fixed notice stay available so the deployment can be bootstrapped.
    */
-  adminOpenId: z.string().regex(
-    /^ou_[A-Za-z0-9_-]+$/,
-    'must be a Feishu open_id such as ou_xxx (send /userid to the bot in a private chat to see it)',
+  adminUserId: z.string().regex(
+    FEISHU_USER_ID_PATTERN,
+    'must be a Feishu user_id, not an open_id (send /userid to the bot in a private chat to see it)',
   ).optional(),
   /**
    * Lifetime of one pending authorization request and of the DM card that asks