@steerable/agent-shell-web 0.6.21 → 0.6.24

package/README.md

@@ -17,4 +17,10 @@ bundle; there is no prebuilt `dist/` here. See
 [`docs/spec/architecture.md`](https://github.com/pathlyapp/steerable-framework/blob/develop/docs/spec/architecture.md)
 for the tier model.
 
+Products that require authentication can register an `AppShellGate` from
+`@steerable/agent-shell-web/auth/gate` before calling `bootstrap()`. An
+enabled gate renders before the application router and calls
+`onAuthenticated` to continue normal bootstrap. With no gate, or a disabled
+gate, startup is unchanged.
+
 License: Apache-2.0.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@steerable/agent-shell-web",
-  "version": "0.6.21",
+  "version": "0.6.24",
   "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",
@@ -14,6 +14,7 @@
     "url": "https://github.com/pathlyapp/steerable-framework/issues"
   },
   "exports": {
+    "./auth/gate": "./src/auth/gate.ts",
     "./vite.base": {
       "types": "./vite.base.d.ts",
       "default": "./vite.base.js"
@@ -45,8 +46,8 @@
     "react-router-dom": "^6.30.0",
     "rehype-raw": "^7.0.0",
     "remark-gfm": "^4.0.1",
-    "@steerable/agent-ui": "0.6.21",
-    "@steerable/agent-protocol": "0.6.21"
+    "@steerable/agent-ui": "0.6.24",
+    "@steerable/agent-protocol": "0.6.24"
   },
   "devDependencies": {
     "@tailwindcss/vite": "^4.3.0",
@@ -59,7 +60,7 @@
     "typescript": "^5.8.3",
     "vite": "^5.4.21",
     "vitest": "^3.2.4",
-    "@steerable/pack-sdk": "0.6.21"
+    "@steerable/pack-sdk": "0.6.24"
   },
   "scripts": {
     "gen": "echo agent-shell-web",

package/src/auth/gate.ts

@@ -0,0 +1,26 @@
+import type { ComponentType } from 'react';
+
+/**
+ * Optional product-provided gate rendered before the application router.
+ */
+export interface AppShellGate {
+  /** Allows one product entry to disable its gate for unsupported runtimes. */
+  enabled(): boolean;
+  /** Renders authentication UI and resumes bootstrap through the callback. */
+  Component: ComponentType<{ onAuthenticated: () => void }>;
+}
+
+let registeredGate: AppShellGate | null = null;
+
+/** Registers the app-shell gate before calling `bootstrap()`. */
+export function registerAppShellGate(gate: AppShellGate): void {
+  if (registeredGate) {
+    throw new Error('[app-shell-gate] a gate is already registered');
+  }
+  registeredGate = gate;
+}
+
+/** Returns the product-provided gate, if one was registered. */
+export function getAppShellGate(): AppShellGate | null {
+  return registeredGate;
+}

package/src/components/ChatHeader.tsx

@@ -1,7 +1,7 @@
 import { useEffect, useLayoutEffect, useMemo, useRef, useState } from 'react';
 import { createPortal } from 'react-dom';
 import { LuCheck, LuGitBranch, LuListTodo, LuListTree, LuLoaderCircle } from 'react-icons/lu';
-import type { LocalChat, LocalChatAgent, LocalTask } from '@/lib/local-api';
+import type { LocalChat, LocalTask } from '@/lib/local-api';
 import {
   activateChatBranch,
   getChatBranches,
@@ -13,7 +13,6 @@ import { actionableTasks, summarizeTasks, type ChatTaskSummary } from './chat/us
 
 interface ChatHeaderProps {
   chat: LocalChat | null;
-  agent: LocalChatAgent | null;
   /**
    * W1.2.1: called after the active branch switches — the page re-hydrates
    * the message list from the re-projected store. When provided (and the
@@ -29,8 +28,6 @@ interface ChatHeaderProps {
 /**
  * ChatHeader — slim title bar above ChatPanel. Shows:
  *   - chat title (完整显示，长标题换行不截断)
- *   - bound agent name + icon (read-only here; switching is done from the
- *     sidebar's expert team list)
  *   - shortened chat id (for support / debugging)
  *
  * Terminal / 场景包调试窗 / 本地模型设置 USED to live here, but per the
@@ -40,7 +37,6 @@ interface ChatHeaderProps {
  */
 export function ChatHeader({
   chat,
-  agent,
   onBranchSwitched,
   onInspectTask,
   tasks = [],
@@ -186,18 +182,6 @@ export function ChatHeader({
         >
           {chat?.title ?? '未选择对话'}
         </span>
-        <span className="shrink-0 text-xs text-agent-muted-foreground">
-          {agent ? (
-            <>
-              <span className="mr-0.5">{agent.icon || '🤖'}</span>
-              {agent.name}
-            </>
-          ) : chat?.agentId ? (
-            <span className="font-mono">{chat.agentId}</span>
-          ) : (
-            <span className="italic">no agent</span>
-          )}
-        </span>
         {chat && (
           <span className="hidden shrink-0 font-mono text-[10px] text-agent-muted-foreground/70 md:inline">
             {shortenId(chat.id)}

package/src/components/chat/TaskProcessPanel.tsx

@@ -167,6 +167,7 @@ export function TaskProcessPanel({
             <TurnProcessGroup
               blocks={blocks}
               isStreaming={live}
+              showThinkingContent
               agents={[]}
               chats={[]}
               emptyFallback={

package/src/components/chat/TurnProcessGroup.tsx

@@ -1,24 +1,22 @@
-import { Fragment, useEffect, useRef, useState, type ReactNode } from 'react';
+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 { Markdown } from './Markdown';
 import { ToolsFlow } from './ExecutedActionsCard';
-import { formatElapsedCompact } from './elapsed';
-import {
-  countProcessTools,
-  processHasReasoning,
-  splitTurnProcess,
-  type TurnBlock,
-} from './turn-timeline';
+import { processStatusLabel } from './process-status';
+import { processHasReasoning, splitTurnProcess, type TurnBlock } from './turn-timeline';
 
 /**
  * Codex / DeepSeek-style turn process: think + tool rows stay in one
- * disclosure. Expanded while the turn streams; collapsed once the trailing
- * summary is on screen. The summary itself stays outside the fold.
- * Elapsed time ticks while streaming (Codex status line) and freezes as
- * 「工作了 …」 after the turn ends.
+ * 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 /
+ * elapsed. The summary itself stays outside the fold.
  */
 
+export const THINKING_PEEK_LINES = 7;
+
 function useLiveElapsedMs(
   startedAtMs: number | undefined,
   enabled: boolean,
@@ -34,27 +32,6 @@ function useLiveElapsedMs(
   return Math.max(0, now - startedAtMs);
 }
 
-function processLabel(
-  process: TurnBlock[],
-  isStreaming: boolean,
-  elapsedMs: number | undefined,
-): string {
-  const elapsed =
-    elapsedMs != null && (isStreaming || elapsedMs >= 1000)
-      ? formatElapsedCompact(elapsedMs)
-      : null;
-  if (isStreaming) {
-    return elapsed ? `正在执行… ${elapsed}` : '正在执行…';
-  }
-  const parts: string[] = [];
-  const tools = countProcessTools(process);
-  if (tools > 0) parts.push(`${tools} 次工具调用`);
-  if (processHasReasoning(process)) parts.push('已思考');
-  if (elapsed) parts.push(`工作了 ${elapsed}`);
-  if (parts.length === 0) return '执行过程';
-  return parts.join(' · ');
-}
-
 function ProcessBlocks({
   blocks,
   isStreaming,
@@ -102,6 +79,51 @@ 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(
+    (block): block is Extract<TurnBlock, { type: 'reasoning' }> =>
+      block.type === 'reasoning' && block.content.trim().length > 0,
+  );
+  const sig = reasoning.map((block) => block.content.length).join(',');
+  useLayoutEffect(() => {
+    const el = scrollerRef.current;
+    if (!el) return;
+    el.scrollTop = el.scrollHeight;
+  }, [sig]);
+  const lastIndex = reasoning.length - 1;
+  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"
+      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" />
+          )}
+        </div>
+      ))}
+    </div>
+  );
+}
+
 export function TurnProcessGroup({
   blocks,
   isStreaming,
@@ -112,6 +134,7 @@ export function TurnProcessGroup({
   streamingHint,
   startedAtMs,
   durationMs,
+  showThinkingContent: showThinkingContentProp,
   renderAnswer,
 }: {
   blocks: TurnBlock[];
@@ -126,11 +149,24 @@ export function TurnProcessGroup({
   startedAtMs?: number;
   /** Frozen wall-clock of a finished turn (metadata or just-ended stream). */
   durationMs?: number;
+  /**
+   * Override the settings preference. Omitted = read 「显示思考内容」.
+   * 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 { process, answer } = splitTurnProcess(blocks);
-  const [open, setOpen] = useState(() => isStreaming || answer.length === 0);
+  const [open, setOpen] = useState(
+    () => showThinkingContent && (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 lastLiveElapsedRef = useRef<number | undefined>(undefined);
   if (isStreaming && liveElapsedMs != null) {
@@ -140,24 +176,48 @@ export function TurnProcessGroup({
     ? liveElapsedMs
     : durationMs ?? lastLiveElapsedRef.current;
 
+  const lastProcess = process[process.length - 1];
+  const reasoningClockRef = useRef<{ index: number; startedAt: number } | null>(null);
+  if (isStreaming && lastProcess?.type === 'reasoning') {
+    const index = process.length - 1;
+    if (reasoningClockRef.current?.index !== index) {
+      reasoningClockRef.current = { index, startedAt: Date.now() };
+    }
+  } else if (!isStreaming) {
+    reasoningClockRef.current = null;
+  }
+  const reasoningElapsedMs =
+    isStreaming && lastProcess?.type === 'reasoning' && reasoningClockRef.current
+      ? Math.max(0, Date.now() - reasoningClockRef.current.startedAt)
+      : undefined;
+
+  useEffect(() => {
+    if (!showThinkingContent) {
+      setOpen(false);
+      return;
+    }
+    if (isStreamingRef.current || answerLenRef.current === 0) setOpen(true);
+  }, [showThinkingContent]);
+
   useEffect(() => {
     const wasStreaming = wasStreamingRef.current;
     if (wasStreaming && !isStreaming && answer.length > 0) {
       setOpen(false);
     }
     if (!wasStreaming && isStreaming) {
-      setOpen(true);
+      setOpen(showThinkingContent);
     }
     wasStreamingRef.current = isStreaming;
-  }, [isStreaming, answer.length]);
+  }, [isStreaming, answer.length, showThinkingContent]);
 
   if (blocks.length === 0) return <>{emptyFallback}</>;
 
   const showToggle = process.length > 0;
   const showProcess = !showToggle || open;
-  const lastProcess = process[process.length - 1];
+  const showThinkingPeek =
+    isStreaming && !open && showToggle && processHasReasoning(process);
   const showStreamingHint =
-    Boolean(streamingHint) && isStreaming && answer.length === 0 && lastProcess?.type === 'tools';
+    Boolean(streamingHint) && isStreaming && answer.length === 0 && !showToggle;
 
   return (
     <div className="space-y-1.5" data-turn-timeline>
@@ -175,7 +235,14 @@ export function TurnProcessGroup({
           ) : (
             <LuChevronRight className="h-3.5 w-3.5 shrink-0" />
           )}
-          <span className="truncate">{processLabel(process, isStreaming, elapsedMs)}</span>
+          <span className="truncate">
+            {processStatusLabel({
+              process,
+              isStreaming,
+              elapsedMs,
+              reasoningElapsedMs,
+            })}
+          </span>
         </button>
       )}
       {showProcess && (
@@ -187,6 +254,15 @@ export function TurnProcessGroup({
           chatId={chatId}
         />
       )}
+      {showThinkingPeek && (
+        <ThinkingPeek
+          blocks={process}
+          isStreaming={answer.length === 0}
+          agents={agents}
+          chats={chats}
+          chatId={chatId}
+        />
+      )}
       {showStreamingHint ? streamingHint : null}
       {answer.map((block, index) => (
         <Fragment key={`answer-${index}`}>

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

@@ -0,0 +1,101 @@
+/**
+ * Turn-process status line: live 「思考中 / 调用工具中」 plus finished
+ * 「N 次工具调用 · 已思考 · 工作了 …」. Token speed is a coarse estimate
+ * from reasoning text (same CJK/other weights as the desktop compactor).
+ */
+
+import { formatElapsedCompact } from './elapsed';
+import {
+  countProcessTools,
+  processHasReasoning,
+  type TurnBlock,
+} from './turn-timeline';
+
+export function estimateTextTokens(text: string): number {
+  if (!text) return 0;
+  let cjk = 0;
+  for (let i = 0; i < text.length; i++) {
+    const code = text.charCodeAt(i);
+    if (
+      (code >= 0x4e00 && code <= 0x9fff) ||
+      (code >= 0x3000 && code <= 0x303f) ||
+      (code >= 0xff00 && code <= 0xffef)
+    ) {
+      cjk++;
+    }
+  }
+  return Math.ceil(cjk * 0.6 + (text.length - cjk) * 0.25);
+}
+
+export function formatTokenSpeed(tokens: number, elapsedMs: number): string | null {
+  if (tokens < 1 || elapsedMs < 400) return null;
+  const perSec = tokens / (elapsedMs / 1000);
+  if (perSec < 0.5) return null;
+  const shown = perSec >= 10 ? Math.round(perSec) : Math.round(perSec * 10) / 10;
+  return `${shown} tok/s`;
+}
+
+export function lastToolsAreRunning(process: TurnBlock[]): boolean {
+  const last = process[process.length - 1];
+  if (last?.type !== 'tools' || last.actions.length === 0) return false;
+  return last.actions.some((action) => action.result == null);
+}
+
+export function activeToolNames(process: TurnBlock[]): string[] {
+  for (let i = process.length - 1; i >= 0; i -= 1) {
+    const block = process[i];
+    if (block.type !== 'tools' || block.actions.length === 0) continue;
+    const running = block.actions.filter((action) => action.result == null);
+    const source = running.length > 0 ? running : block.actions;
+    return source.slice(-2).map((action) => action.tool);
+  }
+  return [];
+}
+
+function formatElapsedPart(
+  isStreaming: boolean,
+  elapsedMs: number | undefined,
+): string | null {
+  if (elapsedMs == null) return null;
+  if (!isStreaming && elapsedMs < 1000) return null;
+  return formatElapsedCompact(elapsedMs);
+}
+
+export function processStatusLabel(input: {
+  process: TurnBlock[];
+  isStreaming: boolean;
+  elapsedMs?: number;
+  reasoningElapsedMs?: number;
+}): string {
+  const { process, isStreaming, elapsedMs, reasoningElapsedMs } = input;
+  const elapsed = formatElapsedPart(isStreaming, elapsedMs);
+
+  if (isStreaming) {
+    const parts: string[] = [];
+    const last = process[process.length - 1];
+    if (lastToolsAreRunning(process)) {
+      parts.push('调用工具中');
+      const names = activeToolNames(process);
+      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);
+      }
+    }
+    if (elapsed) parts.push(elapsed);
+    return parts.join(' · ');
+  }
+
+  const parts: string[] = [];
+  const tools = countProcessTools(process);
+  if (tools > 0) parts.push(`${tools} 次工具调用`);
+  if (processHasReasoning(process)) parts.push('已思考');
+  if (elapsed) parts.push(`工作了 ${elapsed}`);
+  if (parts.length === 0) return '执行过程';
+  return parts.join(' · ');
+}

package/src/components/settings/AppearanceSettingsPanel.tsx

@@ -0,0 +1,44 @@
+import { persistShowThinkingContent, useShowThinkingContent } from '@/lib/show-thinking-content';
+
+/**
+ * 界面偏好：思考过程正文默认折叠，状态行仍显示思考中 / 工具名 / 速度 / 时间。
+ * 立即写入 localStorage，不走设置页顶部的模型保存按钮。
+ */
+export function AppearanceSettingsPanel() {
+  const showThinkingContent = useShowThinkingContent();
+
+  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>
+    </div>
+  );
+}

package/src/fixtures/browser-dev-data.json

@@ -10,7 +10,7 @@
       "icon": "Cpu",
       "color": "#4f46e5",
       "description": "默认本地助手，可调用 shell、文件与 MCP 工具。",
-      "rolePrompt": "你是本地离线助手，回答时清晰、可执行。",
+      "rolePrompt": "你是 **电脑操作员**，本地离线助手，回答时清晰、可执行。",
       "forbiddenPrompt": null,
       "skillIds": [],
       "toolPolicy": {

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

@@ -0,0 +1,49 @@
+/**
+ * 聊天里「显示思考内容」的本机偏好。
+ *
+ * 默认关闭：思考 / 工具过程折叠，只留状态行。打开后流式中自动展开。
+ * 存在 localStorage，设置页开关立即生效，不走后端。
+ */
+
+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 function persistShowThinkingContent(show: boolean): void {
+  if (typeof localStorage !== 'undefined') {
+    localStorage.setItem(SHOW_THINKING_CONTENT_STORAGE_KEY, show ? '1' : '0');
+  }
+  if (typeof window === 'undefined') return;
+  window.dispatchEvent(
+    new CustomEvent<boolean>(SHOW_THINKING_CONTENT_EVENT, { detail: show }),
+  );
+}
+
+/** 当前页与跨标签的偏好变更都会刷新。 */
+export function useShowThinkingContent(): boolean {
+  const [show, setShow] = useState(readShowThinkingContent);
+  useEffect(() => {
+    const onCustom = (event: Event) => {
+      const detail = (event as CustomEvent<boolean>).detail;
+      setShow(typeof detail === 'boolean' ? detail : readShowThinkingContent());
+    };
+    const onStorage = (event: StorageEvent) => {
+      if (event.key === SHOW_THINKING_CONTENT_STORAGE_KEY) {
+        setShow(event.newValue === '1');
+      }
+    };
+    window.addEventListener(SHOW_THINKING_CONTENT_EVENT, onCustom);
+    window.addEventListener('storage', onStorage);
+    return () => {
+      window.removeEventListener(SHOW_THINKING_CONTENT_EVENT, onCustom);
+      window.removeEventListener('storage', onStorage);
+    };
+  }, []);
+  return show;
+}

package/src/main.tsx

@@ -1,5 +1,5 @@
 import { StrictMode, lazy, Suspense, type ReactNode } from 'react';
-import { createRoot } from 'react-dom/client';
+import { createRoot, type Root } from 'react-dom/client';
 import { createHashRouter, RouterProvider } from 'react-router-dom';
 import { AppShell } from './AppShell';
 import { AgentLayout } from './layouts/AgentLayout';
@@ -7,6 +7,7 @@ import { AgentPage } from './pages/AgentPage';
 import { SettingsPage } from './pages/SettingsPage';
 import { getPackRoutes } from './packs/registry';
 import { getBrandLogoUrl, BRAND_NAME } from './brand';
+import { getAppShellGate } from './auth/gate';
 import './styles/index.css';
 
 // 浏览器 dev mock 的安装在 bootstrap() 开头（动态 import + DEV 门）。
@@ -40,19 +41,7 @@ const ChatPanelPreviewPage = import.meta.env.DEV
  * （products/<id>/web/main.tsx）先静态调用包的 register*Renderer()，
  * 再调本函数——路由注册发生在路由表创建之前。
  */
-export async function bootstrap(): Promise<void> {
-  if (import.meta.env.DEV) {
-    // 动态 import：prod 构建里 Rollup 把 DEV 分支连同 mock（含其 fixtures）
-    // 整体树摇掉，浏览器 dev mock 数据不进产物。
-    const { installBrowserDevElectronMock } = await import('./lib/browser-dev-electron-mock');
-    installBrowserDevElectronMock();
-  }
-
-  // 标题与 favicon 在 bootstrap 时设置——此刻产品入口已完成包注册
-  // （品牌 logo 由包经 setBrandLogoUrl 注入，见 brand.ts）。
-  document.title = BRAND_NAME;
-  document.querySelector<HTMLLinkElement>('link[rel="icon"]')?.setAttribute('href', getBrandLogoUrl());
-
+function renderApplication(root: Root): void {
   const router = createHashRouter([
     {
       path: '/',
@@ -90,14 +79,47 @@ export async function bootstrap(): Promise<void> {
     },
   ]);
 
+  root.render(
+    <StrictMode>
+      <RouterProvider router={router} />
+    </StrictMode>,
+  );
+}
+
+export async function bootstrap(): Promise<void> {
+  if (import.meta.env.DEV) {
+    // 动态 import：prod 构建里 Rollup 把 DEV 分支连同 mock（含其 fixtures）
+    // 整体树摇掉，浏览器 dev mock 数据不进产物。
+    const { installBrowserDevElectronMock } = await import('./lib/browser-dev-electron-mock');
+    installBrowserDevElectronMock();
+  }
+
+  // 标题与 favicon 在 bootstrap 时设置——此刻产品入口已完成包注册
+  // （品牌 logo 由包经 setBrandLogoUrl 注入，见 brand.ts）。
+  document.title = BRAND_NAME;
+  document.querySelector<HTMLLinkElement>('link[rel="icon"]')?.setAttribute('href', getBrandLogoUrl());
+
   const rootEl = document.getElementById('root');
   if (!rootEl) {
     throw new Error('Missing #root element in index.html');
   }
+  const root = createRoot(rootEl);
+  const gate = getAppShellGate();
+  if (gate?.enabled()) {
+    let authenticated = false;
+    const onAuthenticated = () => {
+      if (authenticated) return;
+      authenticated = true;
+      renderApplication(root);
+    };
+    const Gate = gate.Component;
+    root.render(
+      <StrictMode>
+        <Gate onAuthenticated={onAuthenticated} />
+      </StrictMode>,
+    );
+    return;
+  }
 
-  createRoot(rootEl).render(
-    <StrictMode>
-      <RouterProvider router={router} />
-    </StrictMode>,
-  );
+  renderApplication(root);
 }

package/src/pages/AgentPage.tsx

@@ -1008,7 +1008,6 @@ function AgentChatView({
         header={
           <ChatHeader
             chat={chat}
-            agent={agent}
             onBranchSwitched={isElectron() ? onBranchTick : undefined}
             onInspectTask={ctx.inspectTask}
             tasks={tasks}

package/src/pages/ChatPanelPreviewPage.tsx

@@ -188,8 +188,23 @@ export function ChatPanelPreviewPage() {
           currentTurnActions: MOCK_ACTIONS.slice(0, 2),
           timelineByMsgId: {} as Record<string, TurnBlock[]>,
           currentTurnTimeline: [
-            { type: 'reasoning', content: '先检查连通性，再跑测试。' },
-            { type: 'tools', actions: MOCK_ACTIONS.slice(0, 2) },
+            {
+              type: 'reasoning',
+              content: [
+                '先检查服务是否还能连上。',
+                '如果端口通了，再跑本目录的测试套件。',
+                '失败的话只读失败文件，不要整仓扫一遍。',
+                '断言颜色对不上时优先看 AssistantMessage 的默认色。',
+                '改完再复跑一次，确认没有带出新的失败。',
+                '工具调用保持最少：连通性检查、跑测试、必要时读文件。',
+                '最后用一两句说清楚结果和下一步。',
+                '如果还在思考，后面的句子会被 7 行窗口裁掉。',
+              ].join('\n'),
+            },
+            {
+              type: 'tools',
+              actions: [MOCK_ACTIONS[0], { ...MOCK_ACTIONS[1], result: undefined }],
+            },
           ],
           currentTurnStartedAtMs: Date.now() - 12_000,
           currentRound: 2,
@@ -242,7 +257,7 @@ export function ChatPanelPreviewPage() {
           onCancel={() => {}}
           className="flex-1"
           header={
-            <ChatHeader chat={MOCK_CHAT} agent={MOCK_AGENT} />
+            <ChatHeader chat={MOCK_CHAT} />
           }
           inputPlaceholder="预览模式 — 输入不会真的发送…"
           agents={[MOCK_AGENT]}

package/src/pages/SettingsPage.tsx

@@ -1,8 +1,9 @@
 import { useRef, useState } from 'react';
-import { LuActivity, LuBlocks, LuBot, LuChartBar, LuNetwork, LuPlug, LuSearch, LuSettings, LuShieldCheck } from 'react-icons/lu';
+import { LuActivity, LuBlocks, LuBot, LuChartBar, LuMonitor, LuNetwork, LuPlug, LuSearch, LuSettings, LuShieldCheck } from 'react-icons/lu';
 import { useOutletContext, useSearchParams } from 'react-router-dom';
 import { isElectron } from '@/lib/electron-bridge';
 import { AgentsSettingsPanel } from '@/components/settings/AgentsSettingsPanel';
+import { AppearanceSettingsPanel } from '@/components/settings/AppearanceSettingsPanel';
 import { DiagnoseSettingsPanel } from '@/components/settings/DiagnoseSettingsPanel';
 import { InsightsSettingsPanel } from '@/components/settings/InsightsSettingsPanel';
 import {
@@ -32,7 +33,7 @@ function resolveSection(raw: string | null): SettingsSection {
  *   - `skills`  侧栏「Skill 设置」
  *   - `mcp`     侧栏「MCP 设置」
  *   - `agents`  侧栏「智能体管理」
- *   - 缺省/`general`  侧栏底「设置」（模型 / 搜索 / 用量 / 安全 / 洞察 / 遥测）
+ *   - 缺省/`general`  侧栏底「设置」（界面 / 模型 / 搜索 / 用量 / 安全 / 洞察 / 遥测）
  *
  * Panel 数据自管理（挂载即拉取），页面本身不持有后端状态。
  */
@@ -111,6 +112,14 @@ export function SettingsPage() {
 
           {section === 'general' && (
             <>
+              <section className="space-y-3" data-testid="settings-section-appearance">
+                <h2 className="flex items-center gap-1.5 text-sm font-semibold text-agent-foreground">
+                  <LuMonitor className="h-4 w-4 text-agent-muted-foreground" />
+                  界面
+                </h2>
+                <AppearanceSettingsPanel />
+              </section>
+
               <section className="space-y-3" data-testid="settings-section-llm">
                 <h2 className="flex items-center gap-1.5 text-sm font-semibold text-agent-foreground">
                   <LuSettings className="h-4 w-4 text-agent-muted-foreground" />