feat(ui): introduce each teacher with an individual welcome bubble

src/pages/Chat/TeacherCompanion.tsx

@@ -1,5 +1,5 @@
 import { ArrowUpRight, Loader2, RefreshCw, X } from 'lucide-react';
-import { useState, type Ref } from 'react';
+import { useState, type CSSProperties, type Ref } from 'react';
 import { Provider as TooltipProvider } from '@radix-ui/react-tooltip';
 import { TeacherAvatar } from './TeacherAvatar';
 import { TeacherIntroduction } from './TeacherIntroduction';
@@ -14,7 +14,7 @@ export function TeacherCompanion({ companion, open, onOpen, onToggle, bubbleRef,
   bubbleRef?: Ref<HTMLDivElement>;
   introductionRef?: Ref<HTMLDivElement>;
 }) {
-  const { definition, invitation, welcome, loading, enabled, checking, error } = companion;
+  const { definition, invitation, welcome, welcomes, loading, enabled, checking, error } = companion;
   const [introductionId, setIntroductionId] = useState<string | null>(null);
   const introductionProps = (id: string) => ({
     open: introductionId === id,
@@ -25,6 +25,7 @@ export function TeacherCompanion({ companion, open, onOpen, onToggle, bubbleRef,
   const agents = companion.selectedAgent && !companion.agents.some((item) => item.teacher_id === activeId)
     ? [...companion.agents, companion.selectedAgent] : companion.agents;
   const viewConversation = () => { companion.dismiss(); onOpen(); };
+  const meetTeacher = (agentId: string) => { setIntroductionId(null); companion.dismissWelcome(agentId); onOpen(agentId); };
   const status = loading ? '正在连接智能体…'
     : checking ? '智能体在看看你最近的进展…'
     : error || (!enabled ? '智能体暂未开放，仍可查看以往讨论' : open ? '我们慢慢聊，想到什么都可以说' : '点我聊聊，想到什么都可以说');
@@ -60,6 +61,29 @@ export function TeacherCompanion({ companion, open, onOpen, onToggle, bubbleRef,
         <span>{companion.refreshing ? '刷新中' : companion.refreshStatus === 'error' ? '刷新失败' : companion.refreshStatus === 'success' ? '已更新' : '刷新'}</span>
       </button>
       <span className="sr-only" role="status" aria-live="polite">{refreshMessage}</span>
+      {!invitation && welcomes.length > 0 && <div ref={bubbleRef} className="teacher-welcome-presence" data-testid="teacher-welcomes" aria-label="认识这里的老师">
+        <div className="teacher-welcome-heading"><span>来认识一下</span>
+          <button type="button" onClick={companion.dismissWelcomes}>先自己试试</button>
+        </div>
+        <div className="teacher-welcome-list">
+          {welcomes.map((item, index) => <article key={item.agentId} className="teacher-welcome-card" data-agent-id={item.agentId}
+            data-tone={item.tone} style={{ '--welcome-delay': `${Math.min(index, 4) * 180}ms` } as CSSProperties}>
+            <button type="button" className="teacher-welcome-avatar" aria-label={`认识${item.definition.name}`} onClick={() => meetTeacher(item.agentId)}>
+              <TeacherAvatar definition={item.definition} />
+            </button>
+            <div className="teacher-welcome-bubble">
+              <button type="button" className="teacher-welcome-open" aria-label={`和${item.definition.name}聊聊`} onClick={() => meetTeacher(item.agentId)}>
+                <span className="teacher-welcome-name">{item.definition.name}</span>
+                <span className="teacher-welcome-text" title={item.text}>{item.text}</span>
+                <span className="teacher-welcome-action">和我聊聊 <ArrowUpRight aria-hidden="true" className="h-3 w-3" /></span>
+              </button>
+              <button type="button" className="teacher-welcome-dismiss" aria-label={`收起${item.definition.name}的介绍`} onClick={() => companion.dismissWelcome(item.agentId)}>
+                <X className="h-3.5 w-3.5" aria-hidden="true" />
+              </button>
+            </div>
+          </article>)}
+        </div>
+      </div>}
       {(invitation || welcome) && <div ref={bubbleRef} className="teacher-companion-presence" data-testid="teacher-presence">
         <div className="teacher-companion-bubble" data-testid="teacher-invitation" data-bubble-kind={invitation ? 'check-in' : 'welcome'}>
           <div className="teacher-companion-bubble-heading">

src/pages/Chat/classroom-workspace.css

@@ -113,5 +113,27 @@
 .teacher-companion-actions button:hover { text-decoration: underline; text-underline-offset: 4px; }
 .teacher-companion-speaker { flex-shrink: 0; width: 48px; height: 48px; margin-top: 5px; border-radius: 8px; }
 .teacher-companion-speaker img { width: 100%; height: 100%; object-fit: contain; image-rendering: pixelated; filter: drop-shadow(0 3px 1px #33485820); }
+.teacher-welcome-presence { position: absolute; top: calc(100% + 12px); right: 0; z-index: 90; width: 340px; max-width: calc(100vw - 40px); padding: 6px; border-radius: 18px; background: #fffdf8; box-shadow: 0 8px 24px #30465f12; }
+.teacher-welcome-heading { display: flex; align-items: center; justify-content: space-between; gap: 12px; padding: 0 8px 4px; color: #6a7463; font-size: 12px; }
+.teacher-welcome-heading button { min-height: 32px; padding: 0 4px; color: #4d663c; border-radius: 8px; cursor: pointer; }
+.teacher-welcome-heading button:hover { background: #eef1e8; }
+.teacher-welcome-list { display: grid; gap: 10px; max-height: min(440px, calc(100vh - 200px)); overflow-y: auto; overscroll-behavior: contain; padding: 4px 6px 8px; scrollbar-width: thin; }
+.teacher-welcome-card { --welcome-fill: #fff3ce; --welcome-edge: #efddb0; display: flex; align-items: flex-start; gap: 10px; min-width: 0; animation: teacher-welcome-arrive 220ms ease-out backwards; animation-delay: var(--welcome-delay, 0ms); }
+.teacher-welcome-card[data-tone="1"] { --welcome-fill: #edf5ff; --welcome-edge: #d7e5f5; }
+.teacher-welcome-card[data-tone="2"] { --welcome-fill: #f3edfc; --welcome-edge: #e5d9f5; }
+.teacher-welcome-avatar { flex-shrink: 0; width: 42px; height: 44px; margin-top: 8px; padding: 2px; border: 1px solid var(--welcome-edge); border-radius: 14px; background: #fff; box-shadow: 0 3px 0 var(--welcome-edge); cursor: pointer; }
+.teacher-welcome-avatar img { width: 100%; height: 100%; object-fit: cover; border-radius: 11px; }
+.teacher-welcome-bubble { position: relative; flex: 1; min-width: 0; border: 1px solid var(--welcome-edge); border-radius: 17px 17px 17px 6px; background: var(--welcome-fill); box-shadow: 0 2px 0 var(--welcome-edge); }
+.teacher-welcome-bubble::before { content: ''; position: absolute; top: 23px; left: -5px; width: 8px; height: 8px; transform: rotate(45deg); border-left: 1px solid var(--welcome-edge); border-bottom: 1px solid var(--welcome-edge); background: var(--welcome-fill); }
+.teacher-welcome-open { display: flex; flex-direction: column; gap: 6px; width: 100%; min-width: 0; padding: 12px; border-radius: inherit; color: #34465c; text-align: left; cursor: pointer; }
+.teacher-welcome-open:hover { background: #ffffff40; }
+.teacher-welcome-name { padding-right: 20px; font-size: 13px; font-weight: 600; line-height: 19px; overflow-wrap: anywhere; }
+.teacher-welcome-text { display: -webkit-box; -webkit-line-clamp: 3; -webkit-box-orient: vertical; overflow: hidden; overflow-wrap: anywhere; white-space: pre-wrap; font-size: 13px; line-height: 1.6; }
+.teacher-welcome-action { display: inline-flex; align-items: center; gap: 3px; color: #596b55; font-size: 11px; line-height: 18px; }
+.teacher-welcome-dismiss { position: absolute; top: 5px; right: 5px; display: grid; place-items: center; width: 30px; height: 30px; color: #6e776b; border-radius: 10px; cursor: pointer; }
+.teacher-welcome-dismiss:hover { background: #ffffff90; }
+@keyframes teacher-welcome-arrive { from { opacity: 0; transform: translateY(5px); } to { opacity: 1; transform: translateY(0); } }
+@media (prefers-reduced-motion: reduce) { .teacher-welcome-card { animation: none; } }
+@media (max-width: 600px) { .teacher-welcome-presence { position: fixed; top: 64px; right: 12px; max-width: calc(100vw - 24px); } }
 /* Native preview clearance is measured against the bubble, not the whole pane. */
 @media (max-height: 650px) { .teacher-companion-bubble { padding-top: 9px; } .teacher-companion-message { -webkit-line-clamp: 2; } }

src/pages/Chat/use-teacher-companion.ts

@@ -42,6 +42,11 @@ function writeLocal(key: string, value: unknown) {
   try { localStorage.setItem(key, JSON.stringify(value)); } catch { /* In-memory state remains usable. */ }
 }
 
+function readIntroducedAgents(key: string | null): string[] {
+  const value = key ? readLocal<unknown>(key, []) : [];
+  return Array.isArray(value) ? value.filter((id): id is string => typeof id === 'string') : [];
+}
+
 function unreadInvitation(state: Pick<CompanionState, 'topic' | 'seen'>) {
   if (state.topic?.conversation) return null;
   return state.topic?.requests.slice().reverse().find((request) => request.intent === 'check-in'
@@ -52,6 +57,21 @@ export function useTeacherCompanion(options: Options) {
   const account = useAuthStore((state) => state.user?.userId ?? state.user?.username ?? 'signed-out');
   const scope = account;
   const storageKey = `makelore-teacher-presence:${scope}`;
+  const introductionKey = options.projectId
+    ? `${storageKey}:project:${encodeURIComponent(options.projectId)}:introduced-agents` : null;
+  const [introductions, setIntroductions] = useState(() => ({ key: introductionKey, ids: readIntroducedAgents(introductionKey) }));
+  const introducedIds = introductions.key === introductionKey ? introductions.ids : readIntroducedAgents(introductionKey);
+  const dismissIntroductions = useCallback((ids: string[]) => {
+    if (!introductionKey || !ids.length) return;
+    setIntroductions(current => {
+      const previous = current.key === introductionKey ? current.ids : readIntroducedAgents(introductionKey);
+      const next = [...new Set([...previous, ...ids])];
+      if (current.key === introductionKey && next.length === previous.length) return current;
+      writeLocal(introductionKey, next);
+      return { key: introductionKey, ids: next };
+    });
+  }, [introductionKey]);
+  const dismissWelcome = useCallback((agentId: string) => dismissIntroductions([agentId]), [dismissIntroductions]);
   const [state, setState] = useState<CompanionState>({ agents: [], definition: null, enabled: false, loading: true, refreshing: false, refreshStatus: 'idle', topic: null, seen: [], welcomeDismissed: false, error: '' });
   const [unreadAgentIds, setUnreadAgentIds] = useState<string[]>([]);
   const selectionEpoch = useRef(0);
@@ -322,7 +342,20 @@ export function useTeacherCompanion(options: Options) {
   const selectedAgentId = visibleState.selectedAgent?.teacher_id ?? selectedDefinition?.config_id;
   const selectedAgent = visibleState.selectedAgent === null ? undefined
     : visibleState.agents.find((item) => item.teacher_id === selectedAgentId) ?? visibleState.selectedAgent;
-  const welcome = topic?.role !== 'friend' && !options.teacherOpen && !visibleState.loading && visibleState.enabled && !visibleState.welcomeDismissed
+  useEffect(() => {
+    // Opening one teacher consumes only that teacher's introduction, never their unread replies.
+    if (options.teacherOpen && selectedAgent?.teacher_id) dismissWelcome(selectedAgent.teacher_id);
+  }, [options.teacherOpen, selectedAgent?.teacher_id, dismissWelcome]);
+  const welcomes = options.projectId && !options.teacherOpen && !visibleState.loading
+    ? visibleState.agents.flatMap((agent, index) => introducedIds.includes(agent.teacher_id) ? [] : [{
+      agentId: agent.teacher_id,
+      definition: agent.definition,
+      text: agent.definition.description.trim() || agent.definition.welcome_message.trim()
+        || `我是${agent.definition.name}，一起聊聊你的想法吧。`,
+      tone: index % 3,
+    }]) : [];
+  const dismissWelcomes = () => dismissIntroductions(welcomes.map(item => item.agentId));
+  const welcome = !visibleState.agents.length && topic?.role !== 'friend' && !options.teacherOpen && !visibleState.loading && visibleState.enabled && !visibleState.welcomeDismissed
     ? selectedDefinition?.welcome_message.trim() || null : null;
   return {
     unreadAgentIds,
@@ -336,7 +369,10 @@ export function useTeacherCompanion(options: Options) {
     topic,
     invitation,
     welcome,
-    bubbleVisible: Boolean(invitation || welcome),
+    welcomes,
+    dismissWelcome,
+    dismissWelcomes,
+    bubbleVisible: Boolean(invitation || welcome || welcomes.length),
     checking: last?.intent === 'check-in' && ['preparing', 'running'].includes(last.status),
     dismiss,
     noteTopic,