@modesto_ma/dsh-channels 0.5.0-beta.5 → 0.5.0-beta.7

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

@@ -10,12 +10,16 @@
  */
 
 import { fillCopy, PANEL_COPY, TAB_FIELD_GROUPS } from '../../settings/contract.ts'
-import { FieldSections, NoticeBar } from './shared.tsx'
+import type { AccessWire } from '../../settings/contract.ts'
+import { Avatar } from '../avatar.tsx'
+import type { ProfileView } from './profiles.ts'
+import { FieldSections, NoticeBar, Row } from './shared.tsx'
 import type { FormView } from './shared.tsx'
 import { RequestList, Whitelist } from './whitelist.tsx'
 
 export interface AccessTabProps {
   form: FormView
+  profiles: ProfileView
   accessNotice: string | null
   accessError: string | null
   onAddGroup: (chatId: string, name: string) => Promise<boolean>
@@ -26,17 +30,10 @@ export interface AccessTabProps {
 }
 
 export function AccessTab(props: AccessTabProps): JSX.Element {
-  const { form, accessNotice, accessError, onAddGroup, onRemoveGroup, onAddUser, onRemoveUser, onResolveRequest } = props
+  const { form, profiles, accessNotice, accessError, onAddGroup, onRemoveGroup, onAddUser, onRemoveUser, onResolveRequest } = props
   const { access } = form.panel
   const working = form.busy === 'access'
   const disabled = form.busy !== null || form.locked || !access.loaded
-  // The administrator row says who is in charge right now when the owner fallback applies.
-  const ownerAdmin = access.mode === 'guarded' && access.admin.source === 'owner' ? access.admin.userId : undefined
-  const fields = ownerAdmin === undefined
-    ? form.fields
-    : form.fields.map(field => field.key === 'adminUserId'
-      ? { ...field, summary: fillCopy(PANEL_COPY.accessAdminOwnerSummary, { id: ownerAdmin }) }
-      : field)
   return (
     <div className="dsh-channels-cfg__tabBody">
       {accessNotice === null ? null : <NoticeBar kind="ok" text={accessNotice} />}
@@ -51,13 +48,23 @@ export function AccessTab(props: AccessTabProps): JSX.Element {
             />
           )
         : null}
+      {profiles.warning === undefined ? null : <p className="dsh-channels-cfg__secFoot">{fillCopy(PANEL_COPY.profilesWarning, { reason: profiles.warning })}</p>}
       {access.loaded && access.requests.length > 0
-        ? <RequestList requests={access.requests} disabled={disabled} working={working} onResolve={onResolveRequest} />
+        ? <RequestList requests={access.requests} profiles={profiles} disabled={disabled} working={working} onResolve={onResolveRequest} />
         : null}
-      <FieldSections form={{ ...form, fields }} groups={TAB_FIELD_GROUPS.access} />
+      <FieldSections
+        form={form}
+        groups={TAB_FIELD_GROUPS.access}
+        extra={{ access: <AdminRow admin={access.admin} profiles={profiles} /> }}
+      />
       <Whitelist
         title={PANEL_COPY.accessGroupsTitle}
-        entries={access.groups.map(group => ({ id: group.chatId, name: group.name, source: group.source }))}
+        entries={access.groups.map(group => ({
+          id: group.chatId,
+          name: profiles.chat(group.chatId)?.name ?? group.name,
+          avatarUrl: profiles.chat(group.chatId)?.avatarUrl,
+          source: group.source,
+        }))}
         avatar="群"
         empty={PANEL_COPY.accessGroupsEmpty}
         loaded={access.loaded}
@@ -71,7 +78,12 @@ export function AccessTab(props: AccessTabProps): JSX.Element {
       />
       <Whitelist
         title={PANEL_COPY.accessUsersTitle}
-        entries={access.users.map(user => ({ id: user.userId, name: user.name, source: user.source }))}
+        entries={access.users.map(user => ({
+          id: user.userId,
+          name: profiles.user(user.userId)?.name ?? user.name,
+          avatarUrl: profiles.user(user.userId)?.avatarUrl,
+          source: user.source,
+        }))}
         empty={PANEL_COPY.accessUsersEmpty}
         loaded={access.loaded}
         addLabel={PANEL_COPY.accessAddUser}
@@ -85,3 +97,19 @@ export function AccessTab(props: AccessTabProps): JSX.Element {
     </div>
   )
 }
+
+/** The effective administrator with their Feishu name and avatar; nothing while there is none. */
+function AdminRow(props: { admin: AccessWire['admin']; profiles: ProfileView }): JSX.Element | null {
+  const { admin, profiles } = props
+  if (admin.userId === undefined) return null
+  const profile = profiles.user(admin.userId)
+  const name = profile?.name ?? admin.userId
+  const source = admin.source === 'owner' ? PANEL_COPY.accessAdminSourceOwner : PANEL_COPY.accessAdminSourceConfig
+  return (
+    <Row
+      leading={<Avatar text={name} url={profile?.avatarUrl} />}
+      label={name}
+      summary={<>{PANEL_COPY.accessAdminCurrent} · <span className="dsh-channels-cfg__mono">{admin.userId}</span> · {source}</>}
+    />
+  )
+}

package/src/client/panel/index.tsx

@@ -1,11 +1,10 @@
 /**
- * 设置 →「飞书渠道」页面：数据加载、5 秒状态轮询、全局 draft、顶部状态头 /
+ * 左侧栏「飞书渠道」主区页面：数据加载、5 秒状态轮询、全局 draft、顶部状态头 /
  * tab 导航与底部保存条的外壳。
  *
  * 所有 Host 交互（panel / status / catalog / config / credentials / access /
  * pick-directory）都集中在这里；tab 组件只接收渲染所需的数据与
- * 回调。页面不 import 任何 DSH 客户端包，只依赖 react 与 `settings.section`
- * 槽位。
+ * 回调。页面不 import 任何 DSH 客户端包，只依赖 react 与 `main` 槽位。
  *
  * @module dsh-channels/client/panel
  */
@@ -49,6 +48,7 @@ import { AccessTab } from './access-tab.tsx'
 import { AdvancedTab } from './advanced-tab.tsx'
 import { ConnectionTab } from './connection-tab.tsx'
 import { FieldsTab } from './fields-tab.tsx'
+import { useFeishuProfiles } from './profiles.ts'
 import {
   fieldLabel,
   formatUptime,
@@ -69,13 +69,23 @@ import type {
 } from './shared.tsx'
 import { WikiTab } from './wiki-tab.tsx'
 
-/** Owner props handed to a `settings.section` contribution (unused beyond parity). */
-export interface FeishuChannelsSectionProps {
-  close?: () => void
+/**
+ * Main-column page for the `main` slot: a full-height scroll region with the
+ * centered panel column. The slot passes no owner props.
+ * @returns the page.
+ */
+export function FeishuChannelsPage(): JSX.Element {
+  return (
+    <section className="dsh-channels-page" aria-label={PANEL_COPY.title}>
+      <div className="dsh-channels-page__content">
+        <FeishuChannelsPanel />
+      </div>
+    </section>
+  )
 }
 
-/** Page shell: one panel payload, one status poll, one global config draft. */
-export function FeishuChannelsSection(_props: FeishuChannelsSectionProps): JSX.Element | null {
+/** Panel shell: one panel payload, one status poll, one global config draft. */
+function FeishuChannelsPanel(): JSX.Element | null {
   const [load, setLoad] = useState<LoadState>({ phase: 'loading' })
   const [activeTab, setActiveTab] = useState<PanelTabId>('connection')
   const [draft, setDraft] = useState<EditableValues>({})
@@ -652,6 +662,8 @@ export function FeishuChannelsSection(_props: FeishuChannelsSectionProps): JSX.E
     }
   }, [busy, draft, hostBusy, issues, onPickDirectory, panel, renderedFields, updateDraft])
 
+  const profiles = useFeishuProfiles(panel?.access ?? null)
+
   const credentials = useMemo<CredentialsView>(() => ({
     appId: appIdInput,
     appSecret: appSecretInput,
@@ -741,6 +753,7 @@ export function FeishuChannelsSection(_props: FeishuChannelsSectionProps): JSX.E
           ? (
               <AccessTab
                 form={form}
+                profiles={profiles}
                 accessNotice={accessNotice}
                 accessError={accessError}
                 onAddGroup={onAddAccessGroup}
@@ -755,6 +768,7 @@ export function FeishuChannelsSection(_props: FeishuChannelsSectionProps): JSX.E
           ? (
               <WikiTab
                 form={form}
+                profiles={profiles}
                 accessNotice={accessNotice}
                 accessError={accessError}
                 onAddUser={(userId, name) => addUser(addWikiUser, userId, name, PANEL_COPY.wikiUserAdded)}
@@ -791,7 +805,7 @@ function PanelHeader(props: {
   return (
     <header className="dsh-channels-cfg__panelHead">
       <div className="dsh-channels-cfg__headRow">
-        <h2 className="dsh-channels-cfg__title">{PANEL_COPY.title}</h2>
+        <h1 className="dsh-channels-cfg__title">{PANEL_COPY.title}</h1>
         <Pill tone={badge.tone} dot>{badge.text}</Pill>
         <span className="dsh-channels-cfg__meta dsh-channels-cfg__mono">v{status.version}</span>
         {status.uptimeMs === undefined

package/src/client/panel/profiles.ts

@@ -0,0 +1,73 @@
+/**
+ * Live Feishu names and avatars for every user and chat the access and wiki
+ * tabs show. The page asks the Host once on entry and again whenever the set
+ * of shown ids changes; a failed request keeps the previous answer.
+ *
+ * @module dsh-channels/client/panel/profiles
+ */
+
+import { useEffect, useMemo, useState } from 'react'
+import type { AccessWire, FeishuProfilesWire, FeishuProfileWire } from '../../settings/contract.ts'
+import { fetchFeishuProfiles } from '../api.ts'
+
+/** Resolved profiles plus the reason some could not be read. */
+export interface ProfileView {
+  user: (userId: string) => FeishuProfileWire | undefined
+  chat: (chatId: string) => FeishuProfileWire | undefined
+  /** Feishu or request failure reason, when one lookup failed. */
+  warning?: string
+}
+
+/**
+ * The `user_id`s and `chat_id`s one access snapshot shows.
+ * @param access - the panel's access snapshot.
+ * @returns sorted, distinct ids per kind.
+ */
+export function profileIds(access: AccessWire): { users: string[]; chats: string[] } {
+  const users = new Set<string>()
+  const chats = new Set<string>()
+  if (access.admin.userId !== undefined) users.add(access.admin.userId)
+  for (const user of access.users) users.add(user.userId)
+  for (const user of access.wikiUsers) users.add(user.userId)
+  for (const group of access.groups) chats.add(group.chatId)
+  for (const request of access.requests) {
+    if (request.kind === 'user') users.add(request.targetId)
+    else chats.add(request.targetId)
+    if (request.chatId !== undefined) chats.add(request.chatId)
+  }
+  return { users: [...users].sort(), chats: [...chats].sort() }
+}
+
+/**
+ * Profiles for one access snapshot; empty until the panel has loaded.
+ * @param access - the panel's access snapshot, null while loading.
+ * @returns lookups by id and the latest failure reason.
+ */
+export function useFeishuProfiles(access: AccessWire | null): ProfileView {
+  const ids = useMemo(() => (access === null ? { users: [], chats: [] } : profileIds(access)), [access])
+  const key = `${ids.users.join(',')}|${ids.chats.join(',')}`
+  const [answer, setAnswer] = useState<FeishuProfilesWire>({ users: {}, chats: {} })
+  const [requestError, setRequestError] = useState<string | undefined>(undefined)
+  useEffect(() => {
+    if (ids.users.length === 0 && ids.chats.length === 0) return
+    let current = true
+    fetchFeishuProfiles(ids.users, ids.chats).then(
+      (next) => {
+        if (!current) return
+        setAnswer(next)
+        setRequestError(undefined)
+      },
+      (error: unknown) => { if (current) setRequestError(error instanceof Error ? error.message : String(error)) },
+    )
+    return () => { current = false }
+    // `key` carries `ids`: a new snapshot with the same ids does not re-ask.
+  }, [key])
+  return useMemo(() => {
+    const warning = requestError ?? answer.warning
+    return {
+      user: (userId: string) => answer.users[userId],
+      chat: (chatId: string) => answer.chats[chatId],
+      ...(warning === undefined ? {} : { warning }),
+    }
+  }, [answer, requestError])
+}

package/src/client/panel/whitelist.tsx

@@ -8,6 +8,8 @@
 import { useState } from 'react'
 import { fillCopy, PANEL_COPY } from '../../settings/contract.ts'
 import type { AccessGroupWire, AccessRequestWire } from '../../settings/contract.ts'
+import { Avatar } from '../avatar.tsx'
+import type { ProfileView } from './profiles.ts'
 import { EmptyRow, Row, Section } from './shared.tsx'
 
 /** Local `MM-DD HH:mm` rendering for authorization timestamps. */
@@ -27,15 +29,13 @@ function sourceLabel(source: AccessGroupWire['source']): string {
   }
 }
 
-/** Round initial badge in front of a whitelist entry. */
-function Avatar(props: { text: string }): JSX.Element {
-  return <span className="dsh-channels-cfg__avatar" aria-hidden="true">{Array.from(props.text)[0] ?? '?'}</span>
-}
-
 /** One whitelist entry: a group `chat_id` or a user `user_id`. */
 export interface WhitelistEntry {
   id: string
+  /** Live Feishu name, else the name captured at authorization time. */
   name?: string
+  /** Live Feishu avatar. */
+  avatarUrl?: string
   source: AccessGroupWire['source']
 }
 
@@ -48,6 +48,7 @@ export function Whitelist(props: {
   /** Shown after the title once loaded; defaults to the entry count. */
   countLabel?: string
   entries: readonly WhitelistEntry[]
+  /** Fallback avatar text for entries without an image; defaults to the entry name. */
   avatar?: string
   empty: string
   loaded: boolean
@@ -81,7 +82,7 @@ export function Whitelist(props: {
       {entries.map(entry => (
         <Row
           key={entry.id}
-          leading={<Avatar text={avatar ?? entry.name ?? entry.id} />}
+          leading={<Avatar text={avatar ?? entry.name ?? entry.id} url={entry.avatarUrl} />}
           label={entry.name ?? entry.id}
           summary={<><span className="dsh-channels-cfg__mono">{entry.id}</span> · {sourceLabel(entry.source)}</>}
           control={(
@@ -146,22 +147,27 @@ export function Whitelist(props: {
 /** Pending authorization requests, settled with the same resolver as the DM card. */
 export function RequestList(props: {
   requests: readonly AccessRequestWire[]
+  profiles: ProfileView
   disabled: boolean
   working: boolean
   onResolve: (token: string, decision: 'allow' | 'deny') => void
 }): JSX.Element {
-  const { requests, disabled, working, onResolve } = props
+  const { requests, profiles, disabled, working, onResolve } = props
   return (
     <Section title={`${PANEL_COPY.accessRequestsTitle} · ${requests.length}`} tone="warn">
       {requests.map((request) => {
-        const target = request.name ?? request.targetId
-        const where = request.kind === 'user' && (request.groupName ?? request.chatId) !== undefined
-          ? fillCopy(PANEL_COPY.accessRequestIn, { group: request.groupName ?? request.chatId ?? '' })
+        const profile = request.kind === 'user' ? profiles.user(request.targetId) : profiles.chat(request.targetId)
+        const target = profile?.name ?? request.name ?? request.targetId
+        const group = request.chatId === undefined
+          ? request.groupName
+          : profiles.chat(request.chatId)?.name ?? request.groupName ?? request.chatId
+        const where = request.kind === 'user' && group !== undefined
+          ? fillCopy(PANEL_COPY.accessRequestIn, { group })
           : ''
         return (
           <Row
             key={request.token}
-            leading={<Avatar text={target} />}
+            leading={<Avatar text={target} url={profile?.avatarUrl} />}
             label={`${target} ${where}${request.kind === 'group' ? PANEL_COPY.accessRequestGroup : PANEL_COPY.accessRequestUser}`}
             summary={(
               <>

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

@@ -7,12 +7,14 @@
  */
 
 import { fillCopy, PANEL_COPY, TAB_FIELD_GROUPS } from '../../settings/contract.ts'
+import type { ProfileView } from './profiles.ts'
 import { FieldSections, NoticeBar } from './shared.tsx'
 import type { FormView } from './shared.tsx'
 import { Whitelist } from './whitelist.tsx'
 
 export interface WikiTabProps {
   form: FormView
+  profiles: ProfileView
   accessNotice: string | null
   accessError: string | null
   onAddUser: (userId: string, name: string) => Promise<boolean>
@@ -20,18 +22,24 @@ export interface WikiTabProps {
 }
 
 export function WikiTab(props: WikiTabProps): JSX.Element {
-  const { form, accessNotice, accessError, onAddUser, onRemoveUser } = props
+  const { form, profiles, accessNotice, accessError, onAddUser, onRemoveUser } = props
   const { access } = form.panel
   const disabled = form.busy !== null || form.locked || !access.loaded
   return (
     <div className="dsh-channels-cfg__tabBody">
       {accessNotice === null ? null : <NoticeBar kind="ok" text={accessNotice} />}
       {accessError === null ? null : <NoticeBar kind="error" text={accessError} />}
+      {profiles.warning === undefined ? null : <p className="dsh-channels-cfg__secFoot">{fillCopy(PANEL_COPY.profilesWarning, { reason: profiles.warning })}</p>}
       <FieldSections form={form} groups={TAB_FIELD_GROUPS.wiki} />
       <Whitelist
         title={PANEL_COPY.wikiUsersTitle}
         countLabel={fillCopy(PANEL_COPY.wikiUsersAdminPlus, { n: access.wikiUsers.length })}
-        entries={access.wikiUsers.map(user => ({ id: user.userId, name: user.name, source: user.source }))}
+        entries={access.wikiUsers.map(user => ({
+          id: user.userId,
+          name: profiles.user(user.userId)?.name ?? user.name,
+          avatarUrl: profiles.user(user.userId)?.avatarUrl,
+          source: user.source,
+        }))}
         empty={PANEL_COPY.wikiUsersEmpty}
         loaded={access.loaded}
         addLabel={PANEL_COPY.accessAddUser}

package/src/client/styles.ts

@@ -1,5 +1,5 @@
 /**
- * Settings panel styling. DSH semantic tokens (`--dsw-alias-*`) with neutral
+ * Feishu channel page styling. DSH semantic tokens (`--dsw-alias-*`) with neutral
  * fallbacks, aliased once to local `--dc-*` variables, so the page follows
  * the active theme.
  *
@@ -9,10 +9,13 @@
 const STYLE_ATTRIBUTE = 'data-dsh-channels-css'
 
 const CSS = `
+.dsh-channels-page{width:100%;height:100%;min-width:0;min-height:0;overflow:auto;scrollbar-gutter:stable;background:var(--dsw-alias-bg-base,#fff)}
+.dsh-channels-page__content{box-sizing:border-box;max-width:816px;margin:0 auto;padding:18px clamp(24px,4vw,48px) 48px}
+[data-platform='darwin'] .dsh-channels-page__content{padding-top:calc(18px + var(--dsh-frame-top-clearance,0px))}
 .dsh-channels-cfg{--dc-fg:var(--dsw-alias-label-primary,#1f2328);--dc-fg2:var(--dsw-alias-label-secondary,#5c6169);--dc-fg3:var(--dsw-alias-label-tertiary,#8a8f98);--dc-dim:var(--dsw-alias-label-dimmed,#b0b4ba);--dc-bg:var(--dsw-alias-bg-base,#fff);--dc-line:var(--dsw-alias-border-l2,rgba(0,0,0,.12));--dc-hover:var(--dsw-alias-interactive-bg-hover,rgba(0,0,0,.05));--dc-accent:var(--dsw-alias-state-business-primary,#0a67d3);--dc-ok:var(--dsw-alias-state-success-primary,#0a7d33);--dc-warn:var(--dsw-alias-state-warn-primary,#a15c00);--dc-bad:var(--dsw-alias-state-error-primary,#c62828);--dc-mono:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace;container-type:inline-size;display:flex;flex-direction:column;gap:14px;width:100%;max-width:720px;color:var(--dc-fg);font-size:13px;line-height:20px}
 .dsh-channels-cfg__panelHead{position:sticky;top:0;z-index:2;display:flex;flex-direction:column;gap:4px;padding:10px 0 6px;background:var(--dc-bg)}
 .dsh-channels-cfg__headRow{display:flex;align-items:center;gap:8px;flex-wrap:wrap}
-.dsh-channels-cfg__title{margin:0 2px 0 0;font-size:17px;font-weight:600;line-height:26px}
+.dsh-channels-cfg__title{margin:0 2px 0 0;font-size:20px;font-weight:500;line-height:28px}
 .dsh-channels-cfg__meta{color:var(--dc-fg3);font-size:12px}
 .dsh-channels-cfg__spacer{flex:1}
 .dsh-channels-cfg__mono{font-family:var(--dc-mono);font-size:12px}
@@ -103,7 +106,7 @@ const CSS = `
 .dsh-channels-cfg__scopeList li{display:flex;align-items:baseline;gap:8px;flex-wrap:wrap}
 .dsh-channels-cfg__scopeList .dsh-channels-cfg__link{font-size:12px}
 .dsh-channels-cfg__list>.dsh-channels-cfg__scopeList{border-top-width:0}
-.dsh-channels-cfg__avatar{display:grid;place-items:center;flex:none;width:26px;height:26px;border-radius:50%;background:var(--dc-hover);color:var(--dc-fg2);font-size:12px}
+.dsh-channels-avatar{box-sizing:border-box;display:grid;place-items:center;flex:none;border-radius:50%;object-fit:cover;background:var(--dsw-alias-interactive-bg-hover,rgba(0,0,0,.05));color:var(--dsw-alias-label-secondary,#5c6169);line-height:1}
 .dsh-channels-cfg__addRow{display:flex;align-items:center;gap:8px;flex-wrap:wrap;padding:10px 14px}
 .dsh-channels-cfg__addRow .dsh-channels-cfg__input{flex:1 1 160px;width:auto}
 .dsh-channels-cfg__emptyRow{padding:11px 14px;color:var(--dc-fg3);font-size:12px}
@@ -116,6 +119,26 @@ const CSS = `
 .dsh-channels-cfg__stepTitle{font-weight:500}
 .dsh-channels-cfg__error{padding:10px 12px;border:1px solid var(--dc-bad);border-radius:10px;color:var(--dc-bad);font-size:12px;line-height:18px;display:flex;flex-direction:column;gap:8px}
 .dsh-channels-cfg__loading{padding:16px 0;color:var(--dc-fg3);font-size:12px}
+.dsh-channels-origin-chip{display:inline-flex;align-items:center;gap:4px;max-width:180px;height:24px;padding:0 8px;border:0;border-radius:6px;background:transparent;color:var(--dsw-alias-label-secondary,#5c6169);font:inherit;font-size:12px;line-height:24px;cursor:pointer;white-space:nowrap}
+.dsh-channels-origin-chip:hover{background:var(--dsw-alias-interactive-bg-hover,rgba(0,0,0,.05));color:var(--dsw-alias-label-primary,#1f2328)}
+.dsh-channels-origin-chip>svg{flex:none}
+.dsh-channels-origin__who{display:inline-flex;align-items:center;gap:6px;vertical-align:middle}
+.dsh-channels-origin-chip__text{overflow:hidden;text-overflow:ellipsis}
+.dsh-channels-origin{box-sizing:border-box;height:100%;overflow:auto;padding:16px;color:var(--dsw-alias-label-primary,#1f2328);font-size:13px;line-height:20px}
+.dsh-channels-origin__head{display:flex;align-items:center;gap:8px;margin-bottom:12px}
+.dsh-channels-origin__title{font-size:15px;font-weight:600;line-height:22px;overflow-wrap:anywhere}
+.dsh-channels-origin__list{display:flex;flex-direction:column;margin:0;border:1px solid var(--dsw-alias-border-l2,rgba(0,0,0,.12));border-radius:10px}
+.dsh-channels-origin__row{display:flex;gap:12px;padding:9px 12px}
+.dsh-channels-origin__row+.dsh-channels-origin__row{border-top:1px solid var(--dsw-alias-border-l2,rgba(0,0,0,.12))}
+.dsh-channels-origin__row dt{flex:none;width:64px;color:var(--dsw-alias-label-tertiary,#8a8f98)}
+.dsh-channels-origin__row dd{flex:1;min-width:0;margin:0;overflow-wrap:anywhere}
+.dsh-channels-origin__mono{font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace;font-size:12px}
+.dsh-channels-origin__muted{color:var(--dsw-alias-label-tertiary,#8a8f98)}
+.dsh-channels-origin__error{display:flex;flex-direction:column;gap:6px;color:var(--dsw-alias-state-error-primary,#c62828);font-size:12px}
+.dsh-channels-origin__actions{display:flex;align-items:center;gap:14px;margin-top:14px}
+.dsh-channels-origin__button{display:inline-flex;align-items:center;height:28px;padding:0 12px;border:1px solid var(--dsw-alias-border-l2,rgba(0,0,0,.12));border-radius:7px;color:inherit;font-size:13px;text-decoration:none}
+.dsh-channels-origin__button:hover{background:var(--dsw-alias-interactive-bg-hover,rgba(0,0,0,.05))}
+.dsh-channels-origin__link{padding:0;border:0;background:none;color:var(--dsw-alias-state-business-primary,#0a67d3);font:inherit;font-size:13px;cursor:pointer}
 @media (prefers-reduced-motion:reduce){.dsh-channels-cfg__switch,.dsh-channels-cfg__switch::after{transition:none}}
 @container (max-width:560px){
 .dsh-channels-cfg__row:not(.dsh-channels-cfg__row--wide){flex-wrap:wrap}

package/src/config.ts

@@ -384,13 +384,20 @@ export const configSchema = z.object({
    * Admission policy for inbound Feishu traffic.
    *
    * - `guarded` (default): only the configured administrator can talk in
-   *   private chats, and a group conversation additionally requires the group
-   *   to be authorized and the sender to be the administrator or an explicitly
+   *   private chats (plus whitelisted users when `dmAllowWhitelist` is on),
+   *   and a group conversation additionally requires the group to be
+   *   authorized and the sender to be the administrator or an explicitly
    *   authorized user.
    * - `open`: legacy behavior — any user inside the app's availability scope
    *   can start a conversation. Debug/compatibility only; unsafe.
    */
   accessMode: z.enum(['open', 'guarded']).default('guarded'),
+  /**
+   * In `guarded` mode, also admit users on the global user whitelist
+   * (`/auth user`) in private chats. Off by default: private chats stay
+   * administrator-only. Each private-chat user already has an own workspace.
+   */
+  dmAllowWhitelist: z.boolean().default(false),
   /**
    * 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

package/src/domain.ts

@@ -217,8 +217,8 @@ export type AccessGroupRecord = z.infer<typeof accessGroupRecordSchema>
 
 /**
  * One authorized user (`user_id`), global across every authorized group.
- * Private chats are administrator-only, so this grant only affects group
- * conversations.
+ * Private chats are administrator-only unless `dmAllowWhitelist` is on, so
+ * by default this grant only affects group conversations.
  */
 export const accessUserRecordSchema = z.object({
   /** Feishu `user_id` — also the table key. */
@@ -321,6 +321,34 @@ export const analyzeRequestRecordSchema = z.object({
 
 export type AnalyzeRequestRecord = z.infer<typeof analyzeRequestRecordSchema>
 
+/**
+ * Where one Feishu-routed Session came from, keyed by its DSH session id.
+ * Written the first time a route record names the Session (new topic,
+ * `/renew`, analyze API) and kept after the route retires, so the Web
+ * client can still show the origin of an old Session. Names are resolved
+ * live when read, never stored.
+ */
+export const sessionOriginRecordSchema = z.object({
+  /** DSH session id (also the table key). */
+  key: z.string().min(1),
+  /** Route key the Session was bound under (thread_id or chat:<chatId>). */
+  routeKey: z.string().min(1),
+  /** Topic-scoped (`thread`) or chat-scoped (`chat`) route. */
+  kind: z.enum(['thread', 'chat']),
+  /** Feishu chat the Session was started from. */
+  chatId: z.string().min(1),
+  /** `p2p` or `group`. */
+  chatType: z.enum(['p2p', 'group']),
+  /** `user_id` of the user who started the Session (the requester for analyze topics). */
+  senderUserId: z.string().min(1),
+  /** Epoch ms when the Session was bound to the route. */
+  createdAt: z.number().int().nonnegative(),
+  /** Group-shared route (log-platform analysis topic). */
+  shared: z.literal(true).optional(),
+})
+
+export type SessionOriginRecord = z.infer<typeof sessionOriginRecordSchema>
+
 export interface FeishuDomainSpecShape {
   name: 'channels_routes_v2'
   version: 1
@@ -365,6 +393,10 @@ export interface FeishuDomainSpecShape {
       valueSchema: typeof analyzeRequestRecordSchema
       __key?: string
     }
+    session_origins: {
+      valueSchema: typeof sessionOriginRecordSchema
+      __key?: string
+    }
   }
 }
 
@@ -407,6 +439,8 @@ export const feishuDomain: FeishuDomainSpecShape = {
     access_wiki_users: { valueSchema: accessUserRecordSchema },
     // Analyze API idempotency records; a missing table loads empty.
     analyze_requests: { valueSchema: analyzeRequestRecordSchema },
+    // Session id → Feishu origin; a missing table loads empty.
+    session_origins: { valueSchema: sessionOriginRecordSchema },
   },
 }
 
@@ -480,6 +514,12 @@ export interface AnalyzeRequestsTable {
   entries(): IterableIterator<[string, AnalyzeRequestRecord]>
 }
 
+/** Normalized table handle for the session-origin table (key = DSH session id). */
+export interface SessionOriginsTable {
+  get(key: string): SessionOriginRecord | undefined
+  put(key: string, value: SessionOriginRecord): Promise<unknown> | void
+}
+
 /** Normalized domain handle. */
 export interface FeishuDomainHandle {
   routes: RoutesTable
@@ -493,6 +533,8 @@ export interface FeishuDomainHandle {
   accessWikiUsers: AccessUsersTable
   /** Analyze API idempotency records. */
   analyzeRequests: AnalyzeRequestsTable
+  /** Feishu origin of every Session a route ever named. */
+  sessionOrigins: SessionOriginsTable
   getGlobal(): FeishuDomainGlobal
   setGlobal(value: FeishuDomainGlobal): Promise<unknown> | void
   close(): Promise<void>

package/src/feishu/scopes.ts

@@ -77,7 +77,8 @@ const BASE_REQUIREMENTS: readonly ScopeRequirement[] = [
   { anyOf: ['im:message:update', 'im:message'], level: 'required', purpose: '流式更新回复卡片' },
   { anyOf: ['im:message.reactions:write_only', 'im:message'], level: 'optional', purpose: '给消息添加/移除处理中表情' },
   { anyOf: ['im:message:readonly', 'im:message'], level: 'optional', purpose: '读取引用消息、话题历史与 feishu_topic_messages' },
-  { anyOf: ['im:chat:readonly', 'im:chat'], level: 'optional', purpose: '机器人入群后读取群信息、发送群信息卡' },
+  { anyOf: ['im:chat:readonly', 'im:chat'], level: 'optional', purpose: '机器人入群后读取群信息、发送群信息卡；Web 页面显示群名和群头像' },
+  { anyOf: ['contact:user.base:readonly'], level: 'optional', purpose: 'Web 页面显示用户真实姓名和头像' },
 ]
 
 /** Panel sync needs, applicable while `slashCommandPanel` is on. */

package/src/feishu-channel.ts

@@ -71,6 +71,27 @@ export interface FeishuChannel {
   onBotAdded(handler: (event: BotAddedEvent) => void | Promise<void>): () => void
   /** Chat name/owner/member count (needs chat-info read permission). */
   getChatInfo(chatId: string): Promise<ChatInfo>
+  /**
+   * Contact profiles (name and avatar) of tenant users by `user_id`
+   * (`contact.v3.user.batch`, `contact:user.base:readonly`). Users outside the
+   * app's contact range are absent from the map. Rejects with a
+   * {@link FeishuApiError} when the lookup fails as a whole. Optional so stubs
+   * can omit it.
+   */
+  userProfiles?(userIds: readonly string[]): Promise<ReadonlyMap<string, FeishuProfile>>
+  /**
+   * Name and avatar of one chat (`im.v1.chat.get`, `im:chat:readonly`); a bot
+   * outside the chat still gets both. Rejects with a {@link FeishuApiError}
+   * when the call fails. Optional so stubs can omit it.
+   */
+  chatProfile?(chatId: string): Promise<FeishuProfile>
+  /**
+   * Display name of one user from the member list of `chatId`
+   * (`im:chat:readonly`), for users the contact profile cannot name. Resolves
+   * `undefined` when the list does not name the user; never rejects. Optional
+   * so stubs can omit it.
+   */
+  memberName?(userId: string, chatId: string): Promise<string | undefined>
   /** Bot open_id, available after `connect()` resolves. */
   botOpenId(): string | undefined
   /**
@@ -278,6 +299,29 @@ function assertFeishuOk(response: { code?: number; msg?: string }): void {
   }
 }
 
+/** Member-list pages `memberName()` scans before giving up (100 members each). */
+const MEMBER_NAME_PAGES = 5
+
+/** `user_ids` per `contact.v3.user.batch` call (the API maximum). */
+const USER_BATCH_SIZE = 50
+
+/** Display name and avatar of one Feishu user or chat, as far as Feishu reports them. */
+export interface FeishuProfile {
+  name?: string
+  /** `https:` image URL on the Feishu CDN. */
+  avatarUrl?: string
+}
+
+/** Keep a non-blank name and an `https:` avatar URL from one Feishu response. */
+function feishuProfile(name: string | undefined, avatar: string | undefined): FeishuProfile {
+  const trimmed = name?.trim()
+  const avatarUrl = avatar !== undefined && /^https:\/\/[^\s"'<>]+$/u.test(avatar) ? avatar : undefined
+  return {
+    ...(trimmed === undefined || trimmed === '' ? {} : { name: trimmed }),
+    ...(avatarUrl === undefined ? {} : { avatarUrl }),
+  }
+}
+
 /** Run one raw request, mapping thrown and non-zero-code failures to {@link FeishuApiError}. */
 async function feishuCall<T extends { code?: number; msg?: string }>(call: () => Promise<T>): Promise<T> {
   let response: T
@@ -450,6 +494,49 @@ class LarkChannelAdapter implements FeishuChannel {
     return this.channel.getChatInfo(chatId)
   }
 
+  async userProfiles(userIds: readonly string[]): Promise<ReadonlyMap<string, FeishuProfile>> {
+    const client = this.channel.rawClient
+    const profiles = new Map<string, FeishuProfile>()
+    for (let offset = 0; offset < userIds.length; offset += USER_BATCH_SIZE) {
+      const response = await feishuCall(() => client.contact.v3.user.batch({
+        params: { user_ids: userIds.slice(offset, offset + USER_BATCH_SIZE), user_id_type: 'user_id' },
+      }))
+      for (const item of response.data?.items ?? []) {
+        if (item.user_id === undefined) continue
+        profiles.set(item.user_id, feishuProfile(item.name, item.avatar?.avatar_72))
+      }
+    }
+    return profiles
+  }
+
+  async chatProfile(chatId: string): Promise<FeishuProfile> {
+    const client = this.channel.rawClient
+    const response = await feishuCall(() => client.im.v1.chat.get({ path: { chat_id: chatId } }))
+    return feishuProfile(response.data?.name, response.data?.avatar)
+  }
+
+  async memberName(userId: string, chatId: string): Promise<string | undefined> {
+    const client = this.channel.rawClient
+    let pageToken: string | undefined
+    for (let page = 0; page < MEMBER_NAME_PAGES; page += 1) {
+      let response
+      try {
+        response = await feishuCall(() => client.im.v1.chatMembers.get({
+          path: { chat_id: chatId },
+          params: { member_id_type: 'user_id', page_size: 100, ...(pageToken === undefined ? {} : { page_token: pageToken }) },
+        }))
+      } catch (_membersUnavailable) {
+        // No chat-read scope, or a chat the bot left: the caller shows the id.
+        return undefined
+      }
+      const hit = response.data?.items?.find(item => item.member_id === userId)?.name?.trim()
+      if (hit !== undefined && hit !== '') return hit
+      pageToken = response.data?.page_token
+      if (response.data?.has_more !== true || pageToken === undefined) return undefined
+    }
+    return undefined
+  }
+
   botOpenId(): string | undefined {
     return this.channel.botIdentity?.openId
   }