@steerable/agent-shell-web 0.6.26 → 0.6.27

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@steerable/agent-shell-web",
-  "version": "0.6.26",
+  "version": "0.6.27",
   "type": "module",
   "description": "Steerable framework — product-neutral renderer SPA source for @steerable/agent-shell (React + Vite). Consumed by product web entry points via the `@/` alias (anchored at this package's src/) and the createProductViteConfig factory. Published as a source package (src/), plus the compiled vite.base config factory (vite.base.js + .d.ts) for Node-side config loading.",
   "license": "Apache-2.0",
@@ -46,8 +46,8 @@
     "react-router-dom": "^6.30.0",
     "rehype-raw": "^7.0.0",
     "remark-gfm": "^4.0.1",
-    "@steerable/agent-ui": "0.6.26",
-    "@steerable/agent-protocol": "0.6.26"
+    "@steerable/agent-protocol": "0.6.27",
+    "@steerable/agent-ui": "0.6.27"
   },
   "devDependencies": {
     "@tailwindcss/vite": "^4.3.0",
@@ -60,7 +60,7 @@
     "typescript": "^5.8.3",
     "vite": "^5.4.21",
     "vitest": "^3.2.4",
-    "@steerable/pack-sdk": "0.6.26"
+    "@steerable/pack-sdk": "0.6.27"
   },
   "scripts": {
     "gen": "echo agent-shell-web",

package/src/components/chat/MessageList.tsx

@@ -173,8 +173,8 @@ export function MessageList({
   onSelectSuggestion,
 }: MessageListProps) {
   const containerRef = useRef<HTMLDivElement>(null);
-  const endRef = useRef<HTMLDivElement>(null);
   const [isAtBottom, setIsAtBottom] = useState(true);
+  const isAtBottomRef = useRef(true);
 
   const visibleMessages = messages.filter(
     (m) => m.role === 'user' || m.role === 'assistant',
@@ -192,13 +192,18 @@ export function MessageList({
     if (!el) return;
     const atBottom =
       el.scrollHeight - el.scrollTop - el.clientHeight < NEAR_BOTTOM_THRESHOLD_PX;
+    isAtBottomRef.current = atBottom;
     setIsAtBottom(atBottom);
   }, []);
 
-  const scrollToBottom = useCallback((behavior: ScrollBehavior = 'smooth') => {
-    const el = endRef.current;
+  const scrollToBottom = useCallback((behavior: ScrollBehavior = 'auto') => {
+    const el = containerRef.current;
     if (!el) return;
-    el.scrollIntoView({ behavior, block: 'end' });
+    if (behavior === 'smooth') {
+      el.scrollTo({ top: el.scrollHeight, behavior: 'smooth' });
+      return;
+    }
+    el.scrollTop = el.scrollHeight;
   }, []);
 
   useEffect(() => {
@@ -213,28 +218,30 @@ export function MessageList({
   // Snap to bottom on first paint, regardless of whether the user "was" at
   // the bottom — there's no "before" on mount.
   useLayoutEffect(() => {
-    scrollToBottom('instant' as ScrollBehavior);
+    isAtBottomRef.current = true;
+    scrollToBottom('auto');
     setIsAtBottom(true);
   }, [scrollToBottom]);
 
-  // Subsequent auto-scroll only when the user is already near the bottom,
-  // so reading old messages doesn't get yanked.
+  // Stick to the bottom *before paint* while the user is still anchored.
+  // Smooth `scrollIntoView` on every reasoning token paints a frame mid-list
+  // then animates down — on Windows the classic scrollbar visibly jumps.
   const lastMessageId = visibleMessages[visibleMessages.length - 1]?.id;
   const lastContentLen = visibleMessages[visibleMessages.length - 1]?.content?.length ?? 0;
   const lastTimelineSig = currentTurnTimeline
     ?.map((block) => (block.type === 'tools' ? `t${block.actions.length}` : `c${block.content.length}`))
     .join('|') ?? '';
   const suggestedSig = suggestedReplies?.join('\0') ?? '';
-  useEffect(() => {
-    if (!isAtBottom) return;
-    scrollToBottom('smooth');
-  }, [lastMessageId, lastContentLen, lastTimelineSig, suggestedSig, isAtBottom, scrollToBottom]);
+  useLayoutEffect(() => {
+    if (!isAtBottomRef.current) return;
+    scrollToBottom('auto');
+  }, [lastMessageId, lastContentLen, lastTimelineSig, suggestedSig, scrollToBottom]);
 
   return (
     <div className="relative flex-1 overflow-hidden">
       <div
         ref={containerRef}
-        className="h-full overflow-y-auto px-3 py-3"
+        className="h-full overflow-y-auto overflow-anchor-none px-3 py-3"
       >
         {visibleMessages.length === 0 ? (
           emptyState ?? null
@@ -359,13 +366,16 @@ export function MessageList({
             ) : null}
           </div>
         )}
-        <div ref={endRef} />
       </div>
 
       {!isAtBottom && visibleMessages.length > 0 && (
         <button
           type="button"
-          onClick={() => scrollToBottom('smooth')}
+          onClick={() => {
+            isAtBottomRef.current = true;
+            setIsAtBottom(true);
+            scrollToBottom('smooth');
+          }}
           className="absolute bottom-3 right-3 flex h-8 w-8 items-center justify-center rounded-full border border-agent-border bg-agent-canvas text-agent-foreground shadow-md transition-colors hover:bg-agent-foreground/5"
           title="回到底部"
           aria-label="回到底部"

package/src/components/chat/TaskProcessPanel.tsx

@@ -35,16 +35,18 @@ export function TaskProcessPanel({
   const [error, setError] = useState<string | null>(null);
   const containerRef = useRef<HTMLDivElement>(null);
   const [isAtBottom, setIsAtBottom] = useState(true);
+  const isAtBottomRef = useRef(true);
 
   const checkAtBottom = useCallback(() => {
     const el = containerRef.current;
     if (!el) return;
     const atBottom =
       el.scrollHeight - el.scrollTop - el.clientHeight < NEAR_BOTTOM_THRESHOLD_PX;
+    isAtBottomRef.current = atBottom;
     setIsAtBottom(atBottom);
   }, []);
 
-  const scrollToBottom = useCallback((behavior: ScrollBehavior = 'smooth') => {
+  const scrollToBottom = useCallback((behavior: ScrollBehavior = 'auto') => {
     const el = containerRef.current;
     if (!el) return;
     if (behavior === 'smooth') {
@@ -65,20 +67,22 @@ export function TaskProcessPanel({
 
   // 换任务 / 首屏：没有「之前在不在底部」可言，直接钉到底。
   useLayoutEffect(() => {
-    scrollToBottom('instant' as ScrollBehavior);
+    isAtBottomRef.current = true;
+    scrollToBottom('auto');
     setIsAtBottom(true);
   }, [inspected.id, scrollToBottom]);
 
-  // live 增量只在用户还贴着底部时跟滚——往上翻看前面的工具调用时不要拽走。
+  // live 增量在 paint 前钉住底部。smooth scroll 会先露出一帧半截内容再往下
+  // 滑，Windows 经典滚动条就会上下跳。
   const timelineSig = blocks
     .map((block) =>
       block.type === 'tools' ? `t${block.actions.length}` : `c${block.content.length}`,
     )
     .join('|');
-  useEffect(() => {
-    if (!isAtBottom) return;
-    scrollToBottom('smooth');
-  }, [timelineSig, live, isAtBottom, scrollToBottom]);
+  useLayoutEffect(() => {
+    if (!isAtBottomRef.current) return;
+    scrollToBottom('auto');
+  }, [timelineSig, live, scrollToBottom]);
 
   useEffect(() => {
     let cancelled = false;
@@ -153,7 +157,7 @@ export function TaskProcessPanel({
       <div className="relative min-h-0 flex-1 overflow-hidden">
         <div
           ref={containerRef}
-          className="h-full overflow-y-auto p-3"
+          className="h-full overflow-y-auto overflow-anchor-none p-3"
           data-testid="task-process-scroll"
         >
           {loading ? (
@@ -191,6 +195,7 @@ export function TaskProcessPanel({
           <button
             type="button"
             onClick={() => {
+              isAtBottomRef.current = true;
               setIsAtBottom(true);
               scrollToBottom('smooth');
             }}

package/src/components/chat/TurnProcessGroup.tsx

@@ -1,7 +1,10 @@
 import { Fragment, useEffect, useLayoutEffect, useRef, useState, type ReactNode } from 'react';
 import { LuChevronDown, LuChevronRight } from 'react-icons/lu';
 import type { LocalChat, LocalChatAgent } from '@/lib/local-api';
-import { useShowThinkingContent } from '@/lib/show-thinking-content';
+import {
+  useThinkingDisplay,
+  type ThinkingDisplayMode,
+} from '@/lib/show-thinking-content';
 import { Markdown } from './Markdown';
 import { ToolsFlow } from './ExecutedActionsCard';
 import { processStatusLabel } from './process-status';
@@ -9,27 +12,56 @@ import { processHasReasoning, splitTurnProcess, type TurnBlock } from './turn-ti
 
 /**
  * Codex / DeepSeek-style turn process: think + tool rows stay in one
- * disclosure. Default is collapsed (settings 「显示思考内容」 off). While
- * streaming, a fixed 7-line peek shows the latest reasoning; it folds when
- * the turn ends. The status line still shows 思考中 / 工具名 / tok/s /
+ * disclosure. Settings 「显示思考内容」 has three modes: hidden / 5-line
+ * peek / full. The status line still shows 思考中 / 工具名 / tok/s /
  * elapsed. The summary itself stays outside the fold.
  */
 
-export const THINKING_PEEK_LINES = 7;
+export const THINKING_PEEK_LINES = 5;
+/**
+ * 5 行 `text-xs` + `leading-relaxed` 的稳定高度。
+ * 不用 CSS `lh`：Windows Electron 在中文字体尚未就绪时 `lh` 会算成 0，
+ * 思考 peek 整块消失，字体加载后又把主列表高度撑跳。
+ */
+export const THINKING_PEEK_HEIGHT = `${THINKING_PEEK_LINES * 1.625}em`;
+
+function ReasoningBody({
+  content,
+  showCursor,
+}: {
+  content: string;
+  showCursor?: boolean;
+}) {
+  return (
+    <>
+      <div className="whitespace-pre-wrap break-words">{content}</div>
+      {showCursor ? (
+        <span className="ml-0.5 inline-block h-3 w-[2px] animate-agent-cursor-blink bg-agent-muted-foreground/60 align-text-bottom" />
+      ) : null}
+    </>
+  );
+}
+
+function resolveThinkingDisplay(
+  preference: ThinkingDisplayMode,
+  thinkingDisplay?: ThinkingDisplayMode,
+  showThinkingContent?: boolean,
+): ThinkingDisplayMode {
+  if (thinkingDisplay) return thinkingDisplay;
+  if (showThinkingContent === true) return 'full';
+  if (showThinkingContent === false) return 'peek';
+  return preference;
+}
 
-function useLiveElapsedMs(
-  startedAtMs: number | undefined,
-  enabled: boolean,
-): number | undefined {
+function useLiveNow(enabled: boolean): number {
   const [now, setNow] = useState(() => Date.now());
   useEffect(() => {
-    if (!enabled || startedAtMs == null) return;
+    if (!enabled) return;
     setNow(Date.now());
     const id = window.setInterval(() => setNow(Date.now()), 1000);
     return () => window.clearInterval(id);
-  }, [enabled, startedAtMs]);
-  if (startedAtMs == null) return undefined;
-  return Math.max(0, now - startedAtMs);
+  }, [enabled]);
+  return now;
 }
 
 function ProcessBlocks({
@@ -56,10 +88,7 @@ function ProcessBlocks({
               key={`reasoning-${index}`}
               className="text-xs leading-relaxed text-agent-muted-foreground"
             >
-              <Markdown agents={agents} chats={chats} chatId={chatId}>{block.content}</Markdown>
-              {isStreaming && isLast && (
-                <span className="ml-0.5 inline-block h-3 w-[2px] animate-agent-cursor-blink bg-agent-muted-foreground/60 align-text-bottom" />
-              )}
+              <ReasoningBody content={block.content} showCursor={isStreaming && isLast} />
             </div>
           );
         }
@@ -82,15 +111,9 @@ function ProcessBlocks({
 function ThinkingPeek({
   blocks,
   isStreaming,
-  agents,
-  chats,
-  chatId,
 }: {
   blocks: TurnBlock[];
   isStreaming: boolean;
-  agents: LocalChatAgent[];
-  chats: LocalChat[];
-  chatId?: string | null;
 }) {
   const scrollerRef = useRef<HTMLDivElement>(null);
   const reasoning = blocks.filter(
@@ -107,17 +130,15 @@ function ThinkingPeek({
   return (
     <div
       ref={scrollerRef}
-      className="h-[7lh] overflow-hidden border-l border-agent-border/70 pl-3 text-xs leading-relaxed text-agent-muted-foreground"
+      className="overflow-y-auto overflow-anchor-none [scrollbar-width:none] [-ms-overflow-style:none] [&::-webkit-scrollbar]:hidden border-l border-agent-border/70 pl-3 text-xs leading-relaxed text-agent-muted-foreground"
+      style={{ height: THINKING_PEEK_HEIGHT }}
       data-thinking-peek=""
       data-testid="thinking-peek"
       data-peek-lines={THINKING_PEEK_LINES}
     >
       {reasoning.map((block, index) => (
         <div key={`peek-reasoning-${index}`}>
-          <Markdown agents={agents} chats={chats} chatId={chatId}>{block.content}</Markdown>
-          {isStreaming && index === lastIndex && (
-            <span className="ml-0.5 inline-block h-3 w-[2px] animate-agent-cursor-blink bg-agent-muted-foreground/60 align-text-bottom" />
-          )}
+          <ReasoningBody content={block.content} showCursor={isStreaming && index === lastIndex} />
         </div>
       ))}
     </div>
@@ -134,6 +155,7 @@ export function TurnProcessGroup({
   streamingHint,
   startedAtMs,
   durationMs,
+  thinkingDisplay: thinkingDisplayProp,
   showThinkingContent: showThinkingContentProp,
   renderAnswer,
 }: {
@@ -149,25 +171,42 @@ export function TurnProcessGroup({
   startedAtMs?: number;
   /** Frozen wall-clock of a finished turn (metadata or just-ended stream). */
   durationMs?: number;
+  /** Override the settings preference (hidden / peek / full). */
+  thinkingDisplay?: ThinkingDisplayMode;
   /**
-   * Override the settings preference. Omitted = read 「显示思考内容」.
+   * Legacy override. `true` = full, `false` = peek.
    * Task process panel passes true so the inspector stays expanded.
    */
   showThinkingContent?: boolean;
   renderAnswer: (block: Extract<TurnBlock, { type: 'text' }>, isLast: boolean) => ReactNode;
 }) {
-  const preference = useShowThinkingContent();
-  const showThinkingContent = showThinkingContentProp ?? preference;
+  const preference = useThinkingDisplay();
+  const thinkingDisplay = resolveThinkingDisplay(
+    preference,
+    thinkingDisplayProp,
+    showThinkingContentProp,
+  );
+  const showFullThinking = thinkingDisplay === 'full';
+  const showThinkingPeekAllowed = thinkingDisplay === 'peek';
   const { process, answer } = splitTurnProcess(blocks);
   const [open, setOpen] = useState(
-    () => showThinkingContent && (isStreaming || answer.length === 0),
+    () => showFullThinking && (isStreaming || answer.length === 0),
   );
   const wasStreamingRef = useRef(isStreaming);
   const isStreamingRef = useRef(isStreaming);
   const answerLenRef = useRef(answer.length);
   isStreamingRef.current = isStreaming;
   answerLenRef.current = answer.length;
-  const liveElapsedMs = useLiveElapsedMs(startedAtMs, isStreaming);
+  const now = useLiveNow(isStreaming);
+  const streamClockRef = useRef<number | undefined>(undefined);
+  if (isStreaming) {
+    streamClockRef.current ??= startedAtMs ?? now;
+  } else {
+    streamClockRef.current = undefined;
+  }
+  const liveElapsedMs = isStreaming
+    ? Math.max(0, now - (startedAtMs ?? streamClockRef.current ?? now))
+    : undefined;
   const lastLiveElapsedRef = useRef<number | undefined>(undefined);
   if (isStreaming && liveElapsedMs != null) {
     lastLiveElapsedRef.current = liveElapsedMs;
@@ -181,23 +220,23 @@ export function TurnProcessGroup({
   if (isStreaming && lastProcess?.type === 'reasoning') {
     const index = process.length - 1;
     if (reasoningClockRef.current?.index !== index) {
-      reasoningClockRef.current = { index, startedAt: Date.now() };
+      reasoningClockRef.current = { index, startedAt: now };
     }
   } else if (!isStreaming) {
     reasoningClockRef.current = null;
   }
   const reasoningElapsedMs =
     isStreaming && lastProcess?.type === 'reasoning' && reasoningClockRef.current
-      ? Math.max(0, Date.now() - reasoningClockRef.current.startedAt)
+      ? Math.max(0, now - reasoningClockRef.current.startedAt)
       : undefined;
 
   useEffect(() => {
-    if (!showThinkingContent) {
+    if (!showFullThinking) {
       setOpen(false);
       return;
     }
     if (isStreamingRef.current || answerLenRef.current === 0) setOpen(true);
-  }, [showThinkingContent]);
+  }, [showFullThinking]);
 
   useEffect(() => {
     const wasStreaming = wasStreamingRef.current;
@@ -205,17 +244,21 @@ export function TurnProcessGroup({
       setOpen(false);
     }
     if (!wasStreaming && isStreaming) {
-      setOpen(showThinkingContent);
+      setOpen(showFullThinking);
     }
     wasStreamingRef.current = isStreaming;
-  }, [isStreaming, answer.length, showThinkingContent]);
+  }, [isStreaming, answer.length, showFullThinking]);
 
   if (blocks.length === 0) return <>{emptyFallback}</>;
 
   const showToggle = process.length > 0;
   const showProcess = !showToggle || open;
   const showThinkingPeek =
-    isStreaming && !open && showToggle && processHasReasoning(process);
+    showThinkingPeekAllowed &&
+    isStreaming &&
+    !open &&
+    showToggle &&
+    processHasReasoning(process);
   const showStreamingHint =
     Boolean(streamingHint) && isStreaming && answer.length === 0 && !showToggle;
 
@@ -255,13 +298,7 @@ export function TurnProcessGroup({
         />
       )}
       {showThinkingPeek && (
-        <ThinkingPeek
-          blocks={process}
-          isStreaming={answer.length === 0}
-          agents={agents}
-          chats={chats}
-          chatId={chatId}
-        />
+        <ThinkingPeek blocks={process} isStreaming={answer.length === 0} />
       )}
       {showStreamingHint ? streamingHint : null}
       {answer.map((block, index) => (

package/src/components/chat/process-status.ts

@@ -35,6 +35,22 @@ export function formatTokenSpeed(tokens: number, elapsedMs: number): string | nu
   return `${shown} tok/s`;
 }
 
+export function estimateProcessReasoningTokens(process: TurnBlock[]): number {
+  let tokens = 0;
+  for (const block of process) {
+    if (block.type === 'reasoning') tokens += estimateTextTokens(block.content);
+  }
+  return tokens;
+}
+
+function speedElapsedMs(
+  reasoningElapsedMs: number | undefined,
+  elapsedMs: number | undefined,
+): number {
+  if (reasoningElapsedMs != null && reasoningElapsedMs >= 400) return reasoningElapsedMs;
+  return elapsedMs ?? reasoningElapsedMs ?? 0;
+}
+
 export function lastToolsAreRunning(process: TurnBlock[]): boolean {
   const last = process[process.length - 1];
   if (last?.type !== 'tools' || last.actions.length === 0) return false;
@@ -79,13 +95,18 @@ export function processStatusLabel(input: {
       if (names.length > 0) parts.push(names.join('、'));
     } else {
       parts.push('思考中');
-      if (last?.type === 'reasoning') {
-        const speed = formatTokenSpeed(
-          estimateTextTokens(last.content),
-          reasoningElapsedMs ?? elapsedMs ?? 0,
-        );
-        if (speed) parts.push(speed);
-      }
+      const tokens =
+        last?.type === 'reasoning'
+          ? estimateTextTokens(last.content)
+          : estimateProcessReasoningTokens(process);
+      const speed = formatTokenSpeed(
+        tokens,
+        speedElapsedMs(
+          last?.type === 'reasoning' ? reasoningElapsedMs : undefined,
+          elapsedMs,
+        ),
+      );
+      if (speed) parts.push(speed);
     }
     if (elapsed) parts.push(elapsed);
     return parts.join(' · ');

package/src/components/settings/AppearanceSettingsPanel.tsx

@@ -1,43 +1,56 @@
-import { persistShowThinkingContent, useShowThinkingContent } from '@/lib/show-thinking-content';
+import {
+  THINKING_DISPLAY_OPTIONS,
+  persistThinkingDisplay,
+  useThinkingDisplay,
+} from '@/lib/show-thinking-content';
 
 /**
- * 界面偏好：思考过程正文默认折叠，状态行仍显示思考中 / 工具名 / 速度 / 时间。
+ * 界面偏好：思考过程正文按「隐藏 / 显示5行 / 完整显示」三档。
  * 立即写入 localStorage，不走设置页顶部的模型保存按钮。
  */
 export function AppearanceSettingsPanel() {
-  const showThinkingContent = useShowThinkingContent();
+  const mode = useThinkingDisplay();
+  const current = THINKING_DISPLAY_OPTIONS.find((item) => item.mode === mode);
 
   return (
     <div
       className="space-y-3 rounded-agent-md border border-agent-border bg-agent-card p-4"
       data-testid="appearance-settings-panel"
     >
-      <div className="flex items-start justify-between gap-4">
-        <div className="min-w-0">
-          <p className="text-sm font-medium text-agent-foreground">显示思考内容</p>
-          <p className="mt-1 text-xs leading-relaxed text-agent-muted-foreground">
-            关闭后流式中只露出 7 行思考，结束后自动折叠。状态行仍显示思考中、工具名、速度和用时。
-          </p>
-        </div>
-        <button
-          type="button"
-          role="switch"
-          aria-checked={showThinkingContent}
-          aria-label="显示思考内容"
-          data-testid="show-thinking-content-toggle"
-          onClick={() => persistShowThinkingContent(!showThinkingContent)}
-          className={[
-            'relative mt-0.5 inline-flex h-5 w-9 shrink-0 items-center rounded-full px-0.5 transition-colors',
-            showThinkingContent ? 'bg-agent-foreground' : 'bg-agent-foreground/25',
-          ].join(' ')}
-        >
-          <span
-            className={[
-              'h-4 w-4 rounded-full bg-agent-canvas shadow-sm transition-transform',
-              showThinkingContent ? 'translate-x-4' : 'translate-x-0',
-            ].join(' ')}
-          />
-        </button>
+      <div>
+        <p className="text-sm font-medium text-agent-foreground">显示思考内容</p>
+        <p className="mt-1 text-xs leading-relaxed text-agent-muted-foreground">
+          {current?.hint} 状态行仍显示思考中、工具名、速度和用时。
+        </p>
+      </div>
+      <div
+        className="flex w-full rounded-full border border-agent-border bg-agent-canvas p-0.5"
+        role="radiogroup"
+        aria-label="显示思考内容"
+        data-testid="thinking-display-toggle"
+      >
+        {THINKING_DISPLAY_OPTIONS.map((item) => {
+          const selected = mode === item.mode;
+          return (
+            <button
+              key={item.mode}
+              type="button"
+              role="radio"
+              aria-checked={selected}
+              aria-label={item.label}
+              data-testid={`thinking-display-${item.mode}`}
+              onClick={() => persistThinkingDisplay(item.mode)}
+              className={[
+                'h-7 flex-1 rounded-full px-2 text-xs transition-colors',
+                selected
+                  ? 'bg-agent-foreground/10 text-agent-foreground'
+                  : 'text-agent-muted-foreground hover:text-agent-foreground',
+              ].join(' ')}
+            >
+              {item.label}
+            </button>
+          );
+        })}
       </div>
     </div>
   );

package/src/lib/show-thinking-content.ts

@@ -1,8 +1,8 @@
 /**
- * 聊天里「显示思考内容」的本机偏好。
+ * 聊天里「显示思考内容」的本机偏好：隐藏 / 显示 5 行 / 完整显示。
  *
- * 默认关闭：思考 / 工具过程折叠，只留状态行。打开后流式中自动展开。
- * 存在 localStorage，设置页开关立即生效，不走后端。
+ * 默认「显示 5 行」：流式中露出固定行数，结束后折叠，只留状态行。
+ * 存在 localStorage，设置页切换立即生效，不走后端。
  */
 
 import { useEffect, useState } from 'react';
@@ -10,32 +10,57 @@ import { useEffect, useState } from 'react';
 export const SHOW_THINKING_CONTENT_STORAGE_KEY = 'agent-show-thinking-content';
 export const SHOW_THINKING_CONTENT_EVENT = 'agent-show-thinking-content-changed';
 
-export function readShowThinkingContent(): boolean {
-  if (typeof localStorage === 'undefined') return false;
-  return localStorage.getItem(SHOW_THINKING_CONTENT_STORAGE_KEY) === '1';
+export const THINKING_DISPLAY_MODES = ['hidden', 'peek', 'full'] as const;
+export type ThinkingDisplayMode = (typeof THINKING_DISPLAY_MODES)[number];
+export const DEFAULT_THINKING_DISPLAY: ThinkingDisplayMode = 'peek';
+
+export const THINKING_DISPLAY_OPTIONS: ReadonlyArray<{
+  mode: ThinkingDisplayMode;
+  label: string;
+  hint: string;
+}> = [
+  { mode: 'hidden', label: '隐藏', hint: '只保留状态行，不展示思考正文。' },
+  { mode: 'peek', label: '显示5行', hint: '流式中露出 5 行思考，结束后自动折叠。' },
+  { mode: 'full', label: '完整显示', hint: '流式中展开全部思考与工具过程，结束后可手动折叠。' },
+];
+
+export function isThinkingDisplayMode(value: unknown): value is ThinkingDisplayMode {
+  return value === 'hidden' || value === 'peek' || value === 'full';
+}
+
+/** 兼容旧开关：'1' → 完整显示，'0' / 缺失 → 显示 5 行。 */
+export function parseThinkingDisplay(raw: string | null | undefined): ThinkingDisplayMode {
+  if (isThinkingDisplayMode(raw)) return raw;
+  if (raw === '1') return 'full';
+  return DEFAULT_THINKING_DISPLAY;
+}
+
+export function readThinkingDisplay(): ThinkingDisplayMode {
+  if (typeof localStorage === 'undefined') return DEFAULT_THINKING_DISPLAY;
+  return parseThinkingDisplay(localStorage.getItem(SHOW_THINKING_CONTENT_STORAGE_KEY));
 }
 
-export function persistShowThinkingContent(show: boolean): void {
+export function persistThinkingDisplay(mode: ThinkingDisplayMode): void {
   if (typeof localStorage !== 'undefined') {
-    localStorage.setItem(SHOW_THINKING_CONTENT_STORAGE_KEY, show ? '1' : '0');
+    localStorage.setItem(SHOW_THINKING_CONTENT_STORAGE_KEY, mode);
   }
   if (typeof window === 'undefined') return;
   window.dispatchEvent(
-    new CustomEvent<boolean>(SHOW_THINKING_CONTENT_EVENT, { detail: show }),
+    new CustomEvent<ThinkingDisplayMode>(SHOW_THINKING_CONTENT_EVENT, { detail: mode }),
   );
 }
 
 /** 当前页与跨标签的偏好变更都会刷新。 */
-export function useShowThinkingContent(): boolean {
-  const [show, setShow] = useState(readShowThinkingContent);
+export function useThinkingDisplay(): ThinkingDisplayMode {
+  const [mode, setMode] = useState(readThinkingDisplay);
   useEffect(() => {
     const onCustom = (event: Event) => {
-      const detail = (event as CustomEvent<boolean>).detail;
-      setShow(typeof detail === 'boolean' ? detail : readShowThinkingContent());
+      const detail = (event as CustomEvent<ThinkingDisplayMode>).detail;
+      setMode(isThinkingDisplayMode(detail) ? detail : readThinkingDisplay());
     };
     const onStorage = (event: StorageEvent) => {
       if (event.key === SHOW_THINKING_CONTENT_STORAGE_KEY) {
-        setShow(event.newValue === '1');
+        setMode(parseThinkingDisplay(event.newValue));
       }
     };
     window.addEventListener(SHOW_THINKING_CONTENT_EVENT, onCustom);
@@ -45,5 +70,5 @@ export function useShowThinkingContent(): boolean {
       window.removeEventListener('storage', onStorage);
     };
   }, []);
-  return show;
+  return mode;
 }

package/src/pages/ChatPanelPreviewPage.tsx

@@ -1,4 +1,4 @@
-import { useMemo, useState } from 'react';
+import { useEffect, useMemo, useState } from 'react';
 import type { ChatMessage } from '@steerable/agent-protocol';
 import { LocalChatPanel } from '@/components/chat/LocalChatPanel';
 import { ChatHeader } from '@/components/ChatHeader';
@@ -123,17 +123,53 @@ const MOCK_TIMELINE: TurnBlock[] = [
  *     StreamingStatus's "正在思考..." baseline.
  *   • `tools-run`  — in-flight bubble, round 2, 2 tools just ran; verifies
  *     StreamingStatus's "已调用 N 个工具" + "Round N" badge interaction.
+ *   • `reasoning-stream` — reasoning tokens arrive over time; verifies the
+ *     5-line peek stays visible and the list scrollbar sticks to the bottom.
  */
-type PreviewScene = 'static' | 'thinking' | 'tools-run';
+type PreviewScene = 'static' | 'thinking' | 'tools-run' | 'reasoning-stream';
+
+const STREAMING_REASONING = [
+  '先检查服务是否还能连上。',
+  '如果端口通了，再跑本目录的测试套件。',
+  '失败的话只读失败文件，不要整仓扫一遍。',
+  '断言颜色对不上时优先看 AssistantMessage 的默认色。',
+  '改完再复跑一次，确认没有带出新的失败。',
+  '工具调用保持最少：连通性检查、跑测试、必要时读文件。',
+  '最后用一两句说清楚结果和下一步。',
+  '如果还在思考，后面的句子会被 5 行窗口裁掉。',
+  '比较 a < b 时不要被 Markdown 当成 HTML 标签吃掉。',
+  '滚动条应一直钉在最下面，不要随着 token 上下跳。',
+].join('\n');
 
 const SCENES: { id: PreviewScene; label: string }[] = [
   { id: 'static', label: '静态历史' },
   { id: 'thinking', label: '流式 · 空内容' },
   { id: 'tools-run', label: '流式 · 工具已跑 · round 2' },
+  { id: 'reasoning-stream', label: '流式 · 推理打字' },
 ];
 
 export function ChatPanelPreviewPage() {
   const [scene, setScene] = useState<PreviewScene>('static');
+  const [streamedReasoning, setStreamedReasoning] = useState('');
+
+  useEffect(() => {
+    if (scene !== 'reasoning-stream') {
+      setStreamedReasoning('');
+      return;
+    }
+    setStreamedReasoning('');
+    let index = 0;
+    const id = window.setInterval(() => {
+      index += 2;
+      if (index >= STREAMING_REASONING.length) {
+        setStreamedReasoning(STREAMING_REASONING);
+        window.clearInterval(id);
+        return;
+      }
+      setStreamedReasoning(STREAMING_REASONING.slice(0, index));
+    }, 40);
+    return () => window.clearInterval(id);
+  }, [scene]);
 
   // Explicit struct type so TS doesn't try to narrow `actionsByMsgId` to the
   // union of {} | { m2: ... } — both shapes are valid `Record<string, ...>`
@@ -198,7 +234,7 @@ export function ChatPanelPreviewPage() {
                 '改完再复跑一次，确认没有带出新的失败。',
                 '工具调用保持最少：连通性检查、跑测试、必要时读文件。',
                 '最后用一两句说清楚结果和下一步。',
-                '如果还在思考，后面的句子会被 7 行窗口裁掉。',
+                '如果还在思考，后面的句子会被 5 行窗口裁掉。',
               ].join('\n'),
             },
             {
@@ -209,6 +245,28 @@ export function ChatPanelPreviewPage() {
           currentTurnStartedAtMs: Date.now() - 12_000,
           currentRound: 2,
         };
+      case 'reasoning-stream':
+        return {
+          messages: [
+            MOCK_MESSAGES[0],
+            {
+              id: 'm-streaming',
+              role: 'assistant',
+              agentId: MOCK_AGENT.id,
+              content: '',
+              createdAt: new Date().toISOString(),
+            },
+          ],
+          isStreaming: true,
+          actionsByMsgId: {} as Record<string, ExecutedAction[]>,
+          currentTurnActions: [],
+          timelineByMsgId: {} as Record<string, TurnBlock[]>,
+          currentTurnTimeline: streamedReasoning
+            ? [{ type: 'reasoning', content: streamedReasoning }]
+            : [],
+          currentTurnStartedAtMs: Date.now() - 1_000,
+          currentRound: 1,
+        };
       case 'static':
       default:
         return {
@@ -222,7 +280,7 @@ export function ChatPanelPreviewPage() {
           suggestedReplies: ['修一下失败的断言颜色', '把测试再跑一遍', '解释这次失败的原因'],
         };
     }
-  }, [scene]);
+  }, [scene, streamedReasoning]);
 
   return (
     <div className="flex h-full w-full flex-col bg-agent-muted/30">