refactor(chat): 收敛线程会话路由状态

frontend/src/app/workspace/agents/[agent_name]/chats/[thread_id]/page.tsx

@@ -39,20 +39,20 @@ export default function AgentChatPage() {
 
   const { agent } = useAgent(agent_name);
 
-  const { threadId, isNewThread, setIsNewThread } = useThreadChat();
+  const { threadId, routeKind } = useThreadChat();
+  const isNewRoute = routeKind === "new";
   const [settings, setSettings] = useLocalSettings();
 
   const { showNotification } = useNotification();
   const [thread, sendMessage] = useThreadStream({
-    threadId: isNewThread ? undefined : threadId,
+    threadId: isNewRoute ? undefined : threadId,
     context: { ...settings.context, agent_name: agent_name },
-    onStart: () => {
+    onStart: (currentThreadId) => {
-      setIsNewThread(false);
       // ! Important: Never use next.js router for navigation in this case, otherwise it will cause the thread to re-mount and lose all states. Use native history API instead.
       history.replaceState(
         null,
         "",
-        `/workspace/agents/${agent_name}/chats/${threadId}`,
+        `/workspace/agents/${agent_name}/chats/${currentThreadId}`,
       );
     },
     onFinish: (state) => {
@@ -89,13 +89,13 @@ export default function AgentChatPage() {
     MESSAGE_LIST_FOLLOWUPS_EXTRA_PADDING_BOTTOM;
 
   return (
-    <ThreadContext.Provider value={{ thread, threadId }}>
+    <ThreadContext.Provider value={{ thread, threadId: threadId ?? "" }}>
       <ChatBox threadId={threadId}>
         <div className="relative flex size-full min-h-0 justify-between">
           <header
             className={cn(
               "absolute top-0 right-0 left-0 z-30 flex h-12 shrink-0 items-center gap-2 px-4",
-              isNewThread
+              isNewRoute
                 ? "bg-background/0 backdrop-blur-none"
                 : "bg-background/80 shadow-xs backdrop-blur",
             )}
@@ -109,7 +109,7 @@ export default function AgentChatPage() {
             </div>
 
             <div className="flex w-full items-center text-sm font-medium">
-              <ThreadTitle threadId={threadId} thread={thread} />
+              <ThreadTitle threadId={threadId ?? ""} thread={thread} />
             </div>
             <div className="mr-4 flex items-center">
               <Tooltip content={t.agents.newChat}>
@@ -124,7 +124,7 @@ export default function AgentChatPage() {
                 </Button>
               </Tooltip>
               <TokenUsageIndicator messages={thread.messages} />
-              <ExportTrigger threadId={threadId} />
+              <ExportTrigger threadId={threadId ?? ""} />
               <ArtifactTrigger />
             </div>
           </header>
@@ -132,8 +132,8 @@ export default function AgentChatPage() {
           <main className="flex min-h-0 max-w-full grow flex-col">
             <div className="flex size-full justify-center">
               <MessageList
-                className={cn("size-full", !isNewThread && "pt-10")}
+                className={cn("size-full", !isNewRoute && "pt-10")}
-                threadId={threadId}
+                threadId={threadId ?? ""}
                 thread={thread}
                 paddingBottom={messageListPaddingBottom}
               />
@@ -143,8 +143,8 @@ export default function AgentChatPage() {
               <div
                 className={cn(
                   "relative w-full",
-                  isNewThread && "-translate-y-[calc(50vh-96px)]",
+                  isNewRoute && "-translate-y-[calc(50vh-96px)]",
-                  isNewThread
+                  isNewRoute
                     ? "max-w-(--container-width-sm)"
                     : "max-w-(--container-width-md)",
                 )}
@@ -163,10 +163,10 @@ export default function AgentChatPage() {
 
                 <InputBox
                   className={cn("bg-background/5 w-full -translate-y-4")}
-                  threadId={threadId}
+                  threadId={threadId ?? ""}
-                  autoFocus={isNewThread}
+                  autoFocus={isNewRoute}
-                  showWelcomeStyle={isNewThread}
+                  isWelcomeView={isNewRoute}
-                  hasSubmitted={!isNewThread}
+                  hasSubmitted={!isNewRoute}
                   status={
                     thread.error
                       ? "error"
@@ -176,7 +176,7 @@ export default function AgentChatPage() {
                   }
                   context={settings.context}
                   extraHeader={
-                    isNewThread && (
+                    isNewRoute && (
                       <AgentWelcome agent={agent} agentName={agent_name} />
                     )
                   }

frontend/src/app/workspace/chats/[thread_id]/page.tsx

@@ -1,7 +1,7 @@
 "use client";
 
 import { Ticker } from "@tombcato/smart-ticker";
-import { FilesIcon, ListTodoIcon, XIcon } from "lucide-react";
+import { FilesIcon, XIcon } from "lucide-react";
 import { useRouter } from "next/navigation";
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { toast } from "sonner";
@@ -23,11 +23,9 @@ import {
 } from "@/components/workspace/artifacts";
 import { useThreadChat } from "@/components/workspace/chats";
 // import { DevTodoList } from "@/components/workspace/dev-todo-list";
-import { IframeTestPanel } from "@/components/workspace/iframe-test-panel";
 import { InputBox } from "@/components/workspace/input-box";
 import { MessageList } from "@/components/workspace/messages";
 import { ThreadContext } from "@/components/workspace/messages/context";
-import { ThreadTitle } from "@/components/workspace/thread-title";
 import { Tooltip } from "@/components/workspace/tooltip";
 import { useSpecificChatMode } from "@/components/workspace/use-chat-mode";
 import { Welcome } from "@/components/workspace/welcome";
@@ -60,42 +58,25 @@ export default function ChatPage() {
     setArtifacts,
     select: selectArtifact,
     selectedArtifact,
-    deselect: deselectArtifact,
-    setFullscreen: setArtifactsFullscreen,
     fullscreen,
   } = useArtifacts();
-  const { threadId, isNewThread, setIsNewThread, isMock, showWelcomeStyle } =
+  const { threadId, routeKind, viewMode, lifecycleMode, isMock } =
     useThreadChat();
-
+  const isWelcomeView = viewMode === "welcome";
-  // 新逻辑：历史渲染和新会话仅由路由 /chats/new 控制，不再读取 isnew/is_chatting 参数。
+  const isNewRoute = routeKind === "new";
-  const shouldRenderHistory = !showWelcomeStyle;
+  const shouldRenderHistory = viewMode === "chat";
-  const safeThreadId = useMemo(() => {
-    if (!threadId || threadId === "new") {
-      return undefined;
-    }
-    return threadId;
-  }, [threadId]);
-  // `/new` + `thread_id` now reuses the pre-created thread, instead of creating
-  // a new session on first submit.
-  const createNewSession = useMemo(
-    () => isNewThread && !safeThreadId,
-    [isNewThread, safeThreadId],
-  );
   const [isThreadInitReady, setIsThreadInitReady] = useState(false);
 
   const streamThreadId = useMemo(() => {
-    if (!safeThreadId) {
+    if (!threadId) {
       return undefined;
     }
-    // In /new flow, defer history loading until thread init is finished:
+    if (lifecycleMode === "reset_on_entry" && !isThreadInitReady) {
-    // delete -> create -> history.
-    if (isNewThread && !isThreadInitReady) {
       return undefined;
     }
-    return safeThreadId;
+    return threadId;
-  }, [isNewThread, isThreadInitReady, safeThreadId]);
+  }, [isThreadInitReady, lifecycleMode, threadId]);
   const apiClient = useMemo(() => getAPIClient(isMock), [isMock]);
-  const warnedMissingThreadIdRef = useRef(false);
   const initializedThreadRef = useRef<string | null>(null);
   const threadInitPromiseRef = useRef<Promise<void> | null>(null);
 
@@ -135,30 +116,30 @@ export default function ChatPage() {
   }, []);
 
   useEffect(() => {
-    if (!isNewThread) {
+    if (lifecycleMode === "preserve") {
-      warnedMissingThreadIdRef.current = false;
+      initializedThreadRef.current = null;
+      threadInitPromiseRef.current = null;
       setIsThreadInitReady(true);
       return;
     }
-    if (!safeThreadId) {
+
-      if (!warnedMissingThreadIdRef.current) {
+    if (lifecycleMode !== "reset_on_entry" || !threadId) {
-        warnedMissingThreadIdRef.current = true;
+      initializedThreadRef.current = null;
-        toast.error(t.chatPage.missingThreadIdForCreate);
+      threadInitPromiseRef.current = null;
-      }
       setIsThreadInitReady(false);
       return;
     }
-    warnedMissingThreadIdRef.current = false;
+
-    if (initializedThreadRef.current === safeThreadId) return;
+    if (initializedThreadRef.current === threadId) return;
-    initializedThreadRef.current = safeThreadId;
+    initializedThreadRef.current = threadId;
     setIsThreadInitReady(false);
 
     const initPromise = apiClient.threads
-      .delete(safeThreadId)
+      .delete(threadId)
       .catch(() => undefined)
       .then(() =>
         apiClient.threads.create({
-          threadId: safeThreadId,
+          threadId,
           ifExists: "do_nothing",
         }),
       )
@@ -179,10 +160,9 @@ export default function ChatPage() {
     });
   }, [
     apiClient,
-    isNewThread,
+    lifecycleMode,
-    safeThreadId,
+    threadId,
     t.chatPage.createSessionFailed,
-    t.chatPage.missingThreadIdForCreate,
   ]);
 
   // 监听宿主页 selectedSkill 消息
@@ -190,21 +170,16 @@ export default function ChatPage() {
     skillError: selectedSkillError,
     clearSkillError: clearSelectedSkillError,
     isBootstrapping: isSelectedSkillBootstrapping,
-  } = useSelectedSkillListener({ threadId: safeThreadId ?? null });
+  } = useSelectedSkillListener({ threadId: threadId ?? null });
   // 对话行为控制器
   const [thread, sendMessage, isUploading] = useThreadStream({
     threadId: streamThreadId,
     context: settings.context,
-    createNewSession,
     isMock,
-    // 发送消息后跳转的逻辑
     onStart: (currentThreadId) => {
-      setIsNewThread(false);
+      if (isNewRoute || viewMode === "welcome") {
-      // if (!shouldStayOnNewRoute) {
+        router.replace(`/workspace/chats/${currentThreadId}?is_chatting=true`);
-      // Keep /new in history so router.back() can return to it.
+      }
-      router.replace(`/workspace/chats/${currentThreadId}?is_chatting=true`);
-      // }
-      // history.pushState(null, "", pathOfThread(currentThreadId));
     },
     onFinish: (state) => {
       if (document.hidden || !document.hasFocus()) {
@@ -258,7 +233,7 @@ export default function ChatPage() {
   ]);
 
   useEffect(() => {
-    const pageTitle = isNewThread
+    const pageTitle = isNewRoute
       ? t.pages.newChat
       : thread.values?.title && thread.values.title !== "Untitled"
         ? thread.values.title
@@ -269,7 +244,7 @@ export default function ChatPage() {
       document.title = `${pageTitle} - ${t.pages.appName}`;
     }
   }, [
-    isNewThread,
+    isNewRoute,
     t.common.loading,
     t.pages.newChat,
     t.pages.untitled,
@@ -312,30 +287,30 @@ export default function ChatPage() {
       if (isSelectedSkillBootstrapping) {
         return;
       }
-      if (isNewThread && !safeThreadId) {
+      if (lifecycleMode === "missing_thread_id") {
         toast.error(t.chatPage.missingThreadIdForSend);
         return;
       }
-      if (isNewThread && safeThreadId) {
+      if (lifecycleMode === "reset_on_entry") {
         await threadInitPromiseRef.current;
       }
-      if (isNewThread && safeThreadId && !isThreadInitReady) {
+      if (lifecycleMode === "reset_on_entry" && !isThreadInitReady) {
         return;
       }
       setHasSubmitted(true);
-      if (safeThreadId && (isNewThread || showWelcomeStyle)) {
+      if (threadId && viewMode === "welcome") {
-        router.replace(`/workspace/chats/${safeThreadId}?is_chatting=true`);
+        router.replace(`/workspace/chats/${threadId}?is_chatting=true`);
       }
-      void sendMessage(safeThreadId, message);
+      void sendMessage(threadId, message);
     },
     [
-      isNewThread,
       isThreadInitReady,
       isSelectedSkillBootstrapping,
+      lifecycleMode,
       router,
-      safeThreadId,
       sendMessage,
-      showWelcomeStyle,
+      threadId,
+      viewMode,
       t.chatPage.missingThreadIdForSend,
     ],
   );
@@ -343,24 +318,8 @@ export default function ChatPage() {
     await thread.stop();
   }, [thread]);
 
-  const resetNewSessionState = useCallback(() => {
-    setIsNewThread(true);
-    setHasSubmitted(false);
-    setHistoryCutoff(null);
-    setArtifacts([]);
-    deselectArtifact();
-    setArtifactsOpen(false);
-    setArtifactsFullscreen(false);
-  }, [
-    deselectArtifact,
-    setArtifacts,
-    setArtifactsFullscreen,
-    setArtifactsOpen,
-    setIsNewThread,
-  ]);
-
   return (
-    <ThreadContext.Provider value={{ threadId, thread }}>
+    <ThreadContext.Provider value={{ threadId: threadId ?? "", thread }}>
       <div
         className={cn(
           "m-auto flex h-screen min-h-svh overflow-hidden rounded-t-[20px] transition-[width] duration-300 ease-in-out",
@@ -379,7 +338,7 @@ export default function ChatPage() {
               <header
                 className={cn(
                   "bg-background absolute top-0 right-0 left-0 z-30 mx-4 grid h-[58px] shrink-0 grid-cols-3 items-center border-b transition-all duration-300 ease-in-out",
-                  showWelcomeStyle && !hasSubmitted ? "hidden" : "",
+                  isWelcomeView && !hasSubmitted ? "hidden" : "",
                 )}
               >
                 <div className="flex items-center justify-start overflow-hidden text-sm font-medium">
@@ -466,7 +425,7 @@ export default function ChatPage() {
               <main
                 className={cn(
                   "flex min-h-0 max-w-full grow flex-col",
-                  showWelcomeStyle && !hasSubmitted
+                  isWelcomeView && !hasSubmitted
                     ? "bg-ws-surface-base"
                     : "bg-background",
                 )}
@@ -475,9 +434,9 @@ export default function ChatPage() {
                   <MessageList
                     className={cn(
                       "size-full",
-                      (!showWelcomeStyle || hasSubmitted) && "pt-[58px]",
+                      (!isWelcomeView || hasSubmitted) && "pt-[58px]",
                     )}
-                    threadId={threadId}
+                    threadId={threadId ?? ""}
                     thread={thread}
                     messagesOverride={
                       shouldRenderHistory
@@ -487,7 +446,7 @@ export default function ChatPage() {
                           : thread.messages.slice(historyCutoff)
                     }
                     paddingBottom={todoListCollapsed ? 160 : 280}
-                    showScrollToBottomButton={!showWelcomeStyle}
+                    showScrollToBottomButton={!isWelcomeView}
                     scrollButtonClassName="bottom-[112px]"
                   />
                 </div>
@@ -508,7 +467,7 @@ export default function ChatPage() {
             <div
               className={cn(
                 "h-full w-full transition-transform duration-300 ease-in-out",
-                showWelcomeStyle && !hasSubmitted ? "translate-x-0" : "",
+                isWelcomeView && !hasSubmitted ? "translate-x-0" : "",
                 artifactPanelOpen ? "translate-x-0" : "translate-x-full",
               )}
             >
@@ -516,7 +475,7 @@ export default function ChatPage() {
                 <ArtifactFileDetail
                   className="size-full"
                   filepath={selectedArtifact}
-                  threadId={threadId}
+                  threadId={threadId ?? ""}
                 />
               ) : (
                 <div className="relative flex size-full justify-center px-[20px]">
@@ -548,7 +507,7 @@ export default function ChatPage() {
                         <ArtifactFileList
                           className="mb-[207px] max-w-(--container-width-sm) pt-[20px]"
                           files={sanitizedArtifacts}
-                          threadId={threadId}
+                          threadId={threadId ?? ""}
                         />
                       </main>
                     </div>
@@ -570,19 +529,19 @@ export default function ChatPage() {
           <div
             className={cn(
               "pointer-events-auto relative w-full max-w-[720px]",
-              showWelcomeStyle &&
+              isWelcomeView &&
                 !hasSubmitted &&
                 "-translate-y-[calc(50vh-96px)]",
             )}
           >
-            {!(showWelcomeStyle && thread.isThreadLoading) ? (
+            {!(isWelcomeView && thread.isThreadLoading) ? (
               <>
                 <InputBox
                   className={cn("w-full rounded-[20px] bg-ws-surface-elevated")}
-                  threadId={threadId}
+                  threadId={threadId ?? ""}
-                  showWelcomeStyle={showWelcomeStyle}
+                  isWelcomeView={isWelcomeView}
                   hasSubmitted={hasSubmitted}
-                  autoFocus={showWelcomeStyle}
+                  autoFocus={isWelcomeView}
                   status={
                     thread.error
                       ? "error"
@@ -593,7 +552,7 @@ export default function ChatPage() {
                   context={settings.context}
                   extraHeader={
                     <div className="flex flex-col gap-4">
-                      {showWelcomeStyle && !hasSubmitted && (
+                      {isWelcomeView && !hasSubmitted && (
                         <Welcome mode={settings.context.mode} />
                       )}
                     </div>
@@ -602,7 +561,7 @@ export default function ChatPage() {
                     env.NEXT_PUBLIC_STATIC_WEBSITE_ONLY === "true" ||
                     isSelectedSkillBootstrapping ||
                     isUploading ||
-                    (isNewThread && !safeThreadId)
+                    lifecycleMode === "missing_thread_id"
                   }
                   onContextChange={(context) => setSettings("context", context)}
                   onSubmit={handleSubmit}
@@ -657,14 +616,13 @@ export default function ChatPage() {
                     type: POST_MESSAGE_TYPES.IS_CHATTING,
                     isChatting: false,
                   });
-                  // 始终复用 query 中的 thread_id。
+                  // NOTE: `/workspace/chats/new?thread_id=...` is the
-                  const nextQuery = new URLSearchParams();
+                  // historical "reset welcome" route. Keep it until the chat
-                  if (threadId && threadId !== "new") {
+                  // URL contract is redesigned.
-                    nextQuery.set("thread_id", threadId);
-                  }
-                  // /workspace/chats/${threadId}?is_chatting=false
                   router.replace(
-                    `/workspace/chats/new?thread_id=${threadId}`,
+                    threadId
+                      ? `/workspace/chats/new?thread_id=${threadId}`
+                      : "/workspace/chats/new",
                   );
                 }}
               >

frontend/src/components/workspace/chats/chat-box.tsx

@@ -5,12 +5,12 @@ import type { GroupImperativeHandle } from "react-resizable-panels";
 
 import { ConversationEmptyState } from "@/components/ai-elements/conversation";
 import { Button } from "@/components/ui/button";
-import { sanitizeArtifactPaths } from "@/core/artifacts/utils";
 import {
   ResizableHandle,
   ResizablePanel,
   ResizablePanelGroup,
 } from "@/components/ui/resizable";
+import { sanitizeArtifactPaths } from "@/core/artifacts/utils";
 import { useI18n } from "@/core/i18n/hooks";
 import { env } from "@/env";
 import { cn } from "@/lib/utils";

frontend/src/components/workspace/chats/thread-chat-route.test.ts

@@ -0,0 +1,94 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+const { normalizeThreadId, resolveThreadChatRouteState } = await import(
+  new URL("./thread-chat-route.ts", import.meta.url).href
+);
+
+void test("resolveThreadChatRouteState treats /chats/new as invalid new", () => {
+  const result = resolveThreadChatRouteState({
+    pathname: "/workspace/chats/new",
+    paramsThreadId: "new",
+    queryThreadId: null,
+    isChatting: null,
+  });
+
+  assert.deepEqual(result, {
+    threadId: undefined,
+    routeKind: "new",
+    viewMode: "welcome",
+    lifecycleMode: "missing_thread_id",
+  });
+});
+
+void test("resolveThreadChatRouteState treats /chats/new?thread_id=T1 as reset welcome", () => {
+  const result = resolveThreadChatRouteState({
+    pathname: "/workspace/chats/new",
+    paramsThreadId: "new",
+    queryThreadId: "T1",
+    isChatting: null,
+  });
+
+  assert.deepEqual(result, {
+    threadId: "T1",
+    routeKind: "new",
+    viewMode: "welcome",
+    lifecycleMode: "reset_on_entry",
+  });
+});
+
+void test("resolveThreadChatRouteState treats /chats/:id without is_chatting as preserve welcome", () => {
+  const result = resolveThreadChatRouteState({
+    pathname: "/workspace/chats/T1",
+    paramsThreadId: "T1",
+    queryThreadId: null,
+    isChatting: null,
+  });
+
+  assert.deepEqual(result, {
+    threadId: "T1",
+    routeKind: "thread",
+    viewMode: "welcome",
+    lifecycleMode: "preserve",
+  });
+});
+
+void test("resolveThreadChatRouteState treats /chats/:id?is_chatting=false as preserve welcome", () => {
+  const result = resolveThreadChatRouteState({
+    pathname: "/workspace/chats/T1",
+    paramsThreadId: "T1",
+    queryThreadId: null,
+    isChatting: "false",
+  });
+
+  assert.deepEqual(result, {
+    threadId: "T1",
+    routeKind: "thread",
+    viewMode: "welcome",
+    lifecycleMode: "preserve",
+  });
+});
+
+void test("resolveThreadChatRouteState treats /chats/:id?is_chatting=true as chat view", () => {
+  const result = resolveThreadChatRouteState({
+    pathname: "/workspace/chats/T1",
+    paramsThreadId: "T1",
+    queryThreadId: null,
+    isChatting: "true",
+  });
+
+  assert.deepEqual(result, {
+    threadId: "T1",
+    routeKind: "thread",
+    viewMode: "chat",
+    lifecycleMode: "preserve",
+  });
+});
+
+void test("normalizeThreadId drops reserved and empty values", () => {
+  assert.equal(normalizeThreadId(""), undefined);
+  assert.equal(normalizeThreadId("new"), undefined);
+  assert.equal(normalizeThreadId(" undefined "), undefined);
+  assert.equal(normalizeThreadId(" null "), undefined);
+  assert.equal(normalizeThreadId(" T1 "), "T1");
+});

frontend/src/components/workspace/chats/thread-chat-route.ts

@@ -0,0 +1,77 @@
+export type RouteKind = "new" | "thread";
+export type ViewMode = "welcome" | "chat";
+export type LifecycleMode =
+  | "missing_thread_id"
+  | "reset_on_entry"
+  | "preserve";
+
+export type ThreadChatRouteState = {
+  threadId?: string;
+  routeKind: RouteKind;
+  viewMode: ViewMode;
+  lifecycleMode: LifecycleMode;
+};
+
+export type ResolveThreadChatRouteStateInput = {
+  pathname: string;
+  paramsThreadId?: string | null;
+  queryThreadId?: string | null;
+  isChatting?: string | null;
+};
+
+export function resolveThreadChatRouteState({
+  pathname,
+  paramsThreadId,
+  queryThreadId,
+  isChatting,
+}: ResolveThreadChatRouteStateInput): ThreadChatRouteState {
+  const pathThreadId =
+    paramsThreadId?.trim() ?? extractThreadIdFromPathname(pathname);
+  const routeKind: RouteKind = pathThreadId === "new" ? "new" : "thread";
+  const threadId =
+    routeKind === "new"
+      ? normalizeThreadId(queryThreadId)
+      : normalizeThreadId(pathThreadId);
+  const viewMode: ViewMode =
+    routeKind === "new" ? "welcome" : isChatting === "true" ? "chat" : "welcome";
+  const lifecycleMode: LifecycleMode =
+    routeKind === "new"
+      ? threadId
+        ? "reset_on_entry"
+        : "missing_thread_id"
+      : "preserve";
+
+  return {
+    threadId,
+    routeKind,
+    viewMode,
+    lifecycleMode,
+  };
+}
+
+export function normalizeThreadId(value?: string | null): string | undefined {
+  if (!value) {
+    return undefined;
+  }
+  const normalized = value.trim().toLowerCase();
+  if (
+    normalized.length === 0 ||
+    normalized === "new" ||
+    normalized === "undefined" ||
+    normalized === "null"
+  ) {
+    return undefined;
+  }
+  return value.trim();
+}
+
+export function extractThreadIdFromPathname(
+  pathname: string,
+): string | undefined {
+  const parts = pathname.split("?")[0]?.split("/") ?? [];
+  const idx = parts.lastIndexOf("chats");
+  if (idx >= 0 && parts.length > idx + 1) {
+    return parts[idx + 1];
+  }
+  return undefined;
+}

frontend/src/components/workspace/chats/use-thread-chat.ts

@@ -1,88 +1,33 @@
 "use client";
 
 import { useParams, usePathname, useSearchParams } from "next/navigation";
-import { useEffect, useState } from "react";
+
+import { resolveThreadChatRouteState } from "./thread-chat-route";
+
+export type {
+  LifecycleMode,
+  RouteKind,
+  ThreadChatRouteState,
+  ViewMode,
+} from "./thread-chat-route";
 
 export function useThreadChat() {
   const pathname = usePathname();
   const params = useParams<{ thread_id: string }>();
   const searchParams = useSearchParams();
-  const threadIdFromSearchParams = searchParams.get("thread_id")?.trim();
+  // NOTE: The current chat URLs are a historical compatibility layer.
-  // showWelcomeStyle的子判断
+  // `/workspace/chats/new?thread_id=...` and `?is_chatting=` should eventually
-  const isChattingFromQuery = (() => {
+  // be redesigned, but this hook remains the single source of truth for the
-    const isChatting = searchParams.get("is_chatting");
+  // current contract until that URL cleanup happens.
-    return isChatting === "true";
+  const routeState = resolveThreadChatRouteState({
-  })();
-  // 兜底：当 params 还未就绪时，从 pathname 解析 thread_id。
-  const threadIdFromPathname = (() => {
-    const parts = pathname.split("?")[0]?.split("/") ?? [];
-    const idx = parts.lastIndexOf("chats");
-    if (idx >= 0 && parts.length > idx + 1) {
-      return parts[idx + 1];
-    }
-    return undefined;
-  })();
-  const rawPathThreadId = params?.thread_id ?? threadIdFromPathname;
-
-  const isNewRoute = rawPathThreadId === "new";
-  const threadIdFromPathOrParams = isNewRoute
-    ? normalizeThreadId(threadIdFromSearchParams)
-    : normalizeThreadId(rawPathThreadId);
-  // console.log("[useThreadChat] pathname", pathname);
-  // console.log("[useThreadChat] params.thread_id", params?.thread_id);
-  // console.log("[useThreadChat] threadIdFromPathname", threadIdFromPathname);
-  // console.log("[useThreadChat] threadIdFromPath", threadIdFromPath);
-  // New session is only controlled by `/workspace/chats/new`.
-  const [isNewThread, setIsNewThread] = useState(() => isNewRoute);
-
-  const [showWelcomeStyle, setShowWelcomeStyle] = useState(() => {
-    return isNewRoute || !isChattingFromQuery;
-  });
-  // console.log("[useThreadChat] effectiveThreadIdFromPath", effectiveThreadIdFromPath);
-
-  const [threadId, setThreadId] = useState<string>(() => {
-    return threadIdFromPathOrParams ?? "";
-  });
-
-  useEffect(() => {
-    // 记住最近一次有效的 thread_id，供下次加载兜底使用。
-    if (threadId && threadId !== "new" && typeof window !== "undefined") {
-      window.sessionStorage.setItem("workspace.thread_id", threadId);
-    }
-    setIsNewThread(isNewRoute);
-    // Prefer path thread id, fall back to query thread_id when path is /new.
-    setThreadId(threadIdFromPathOrParams ?? "");
-    setShowWelcomeStyle(isNewRoute || !isChattingFromQuery);
-  }, [
-    isNewRoute,
     pathname,
-    searchParams,
+    paramsThreadId: params?.thread_id,
-    isChattingFromQuery,
+    queryThreadId: searchParams.get("thread_id"),
-    threadId,
+    isChatting: searchParams.get("is_chatting"),
-    threadIdFromPathOrParams,
+  });
-  ]);
+
-  const isMock = searchParams.get("mock") === "true";
   return {
-    threadId,
+    ...routeState,
-    isNewThread,
+    isMock: searchParams.get("mock") === "true",
-    setIsNewThread,
-    isMock,
-    showWelcomeStyle,
   };
 }
-
-function normalizeThreadId(value?: string | null): string | undefined {
-  if (!value) return undefined;
-  return isValidThreadId(value) ? value.trim() : undefined;
-}
-
-function isValidThreadId(value?: string | null): value is string {
-  if (!value) return false;
-  const normalized = value.trim().toLowerCase();
-  return (
-    normalized.length > 0 &&
-    normalized !== "new" &&
-    normalized !== "undefined" &&
-    normalized !== "null"
-  );
-}

frontend/src/components/workspace/input-box.tsx

@@ -218,7 +218,7 @@ export function InputBox({
   status,
   context,
   extraHeader,
-  showWelcomeStyle,
+  isWelcomeView,
   hasSubmitted,
   initialValue,
   onContextChange,
@@ -237,7 +237,7 @@ export function InputBox({
     mode: "flash" | "thinking" | "pro" | "ultra" | undefined;
   };
   extraHeader?: React.ReactNode;
-  showWelcomeStyle: boolean;
+  isWelcomeView: boolean;
   hasSubmitted?: boolean;
   initialValue?: string;
   onContextChange?: (
@@ -294,14 +294,14 @@ export function InputBox({
   const [isInputToolsTourReady, setIsInputToolsTourReady] = useState(false);
   const { data: referenceFilesData } = useReferenceFiles(threadIdFromProps);
 
-  // isNewThread 时禁用收缩，始终保持展开（除非已提交消息）
+  // Welcome view 时禁用收缩，始终保持展开（除非已提交消息）
   const effectiveIsFocused =
-    ((showWelcomeStyle ?? false) && !hasSubmitted) || isFocused;
+    ((isWelcomeView ?? false) && !hasSubmitted) || isFocused;
   const shouldShowSuggestionList =
-    showWelcomeStyle && !hasSubmitted && searchParams.get("mode") !== "skill";
+    isWelcomeView && !hasSubmitted && searchParams.get("mode") !== "skill";
 
   useEffect(() => {
-    if (!showWelcomeStyle || hasSubmitted) {
+    if (!isWelcomeView || hasSubmitted) {
       setIsInputToolsTourReady(false);
       return;
     }
@@ -317,7 +317,7 @@ export function InputBox({
     });
     return () => window.cancelAnimationFrame(frameId);
   }, [
-    showWelcomeStyle,
+    isWelcomeView,
     hasSubmitted,
     shouldShowSuggestionList,
     iframeSkill.isBootstrapping,
@@ -325,7 +325,7 @@ export function InputBox({
   ]);
 
   useEffect(() => {
-    if (!showWelcomeStyle || hasSubmitted || !isInputToolsTourReady) {
+    if (!isWelcomeView || hasSubmitted || !isInputToolsTourReady) {
       setIsInputToolsTourOpen(false);
       return;
     }
@@ -337,7 +337,7 @@ export function InputBox({
     if (!hasSeenTourForCurrentThread) {
       setIsInputToolsTourOpen(true);
     }
-  }, [showWelcomeStyle, hasSubmitted, isInputToolsTourReady, threadId]);
+  }, [isWelcomeView, hasSubmitted, isInputToolsTourReady, threadId]);
 
   const finishInputToolsTour = useCallback(() => {
     const seenState = parseInputToolsTourSeenState(
@@ -515,7 +515,7 @@ export function InputBox({
         return;
       }
       setIsFocused(false);
-      if (showWelcomeStyle) {
+      if (isWelcomeView) {
         sendToParent({
           type: POST_MESSAGE_TYPES.IS_CHATTING,
           isChatting: true,
@@ -529,7 +529,7 @@ export function InputBox({
       setReferences([]);
     },
     [
-      showWelcomeStyle,
+      isWelcomeView,
       onSubmit,
       onStop,
       references,
@@ -760,7 +760,7 @@ export function InputBox({
 
     return () => controller.abort();
     */
-  }, [disabled, showWelcomeStyle, threadId]);
+  }, [disabled, isWelcomeView, threadId]);
 
   return (
     <div
@@ -816,7 +816,7 @@ export function InputBox({
         inputGroupClassName={cn(
           "border-0 rounded-[20px] backdrop-blur-sm",
           "transition-[height] duration-300 ease-out shadow-none ",
-          !showWelcomeStyle && "h-[200px] shadow-[0_0_20px_0_rgba(0,0,0,0.10)]",
+          !isWelcomeView && "h-[200px] shadow-[0_0_20px_0_rgba(0,0,0,0.10)]",
           hasSubmitted && "shadow-[0_0_20px_0_rgba(0,0,0,0.10)]!",
           effectiveIsFocused ? "h-[200px]" : "h-[80px]",
         )}
@@ -839,7 +839,7 @@ export function InputBox({
             )}
             disabled={isInputDisabled}
             placeholder={
-              showWelcomeStyle
+              isWelcomeView
                 ? t.inputBox.welcomePlaceholder
                 : t.inputBox.chatPlaceholder
             }
@@ -962,7 +962,7 @@ export function InputBox({
               />
             </PromptInputActionMenuContent>
           </PromptInputActionMenu> */}
-            {showWelcomeStyle && (
+            {isWelcomeView && (
               <div ref={historyButtonTourRef} className="shrink-0 h-full">
                 <HistoryButton
                   router={router}
@@ -970,7 +970,7 @@ export function InputBox({
                 />
               </div>
             )}
-            {!showWelcomeStyle && (
+            {!isWelcomeView && (
               <div className="shrink-0 h-full">
                 <ExitChattingButton
                   router={router}
@@ -1047,7 +1047,7 @@ export function InputBox({
         )}
 
       {!disabled &&
-        !showWelcomeStyle &&
+        !isWelcomeView &&
         !followupsHidden &&
         (followupsLoading || followups.length > 0) && (
           <div className="absolute -top-20 right-0 left-0 z-20 flex items-center justify-center">

frontend/src/components/workspace/thread-title.tsx

@@ -18,7 +18,8 @@ export function ThreadTitle({
   threadTitle?: string;
 }) {
   const { t } = useI18n();
-  const { isNewThread } = useThreadChat();
+  const { routeKind } = useThreadChat();
+  const isNewRoute = routeKind === "new";
   useEffect(() => {
     if (!thread) {
       return;
@@ -27,7 +28,7 @@ export function ThreadTitle({
 
     if (thread.values?.title) {
       _title = thread.values.title;
-    } else if (isNewThread) {
+    } else if (isNewRoute) {
       _title = t.pages.newChat;
     }
     if (thread.isThreadLoading) {
@@ -36,7 +37,7 @@ export function ThreadTitle({
       document.title = `${_title} - ${t.pages.appName}`;
     }
   }, [
-    isNewThread,
+    isNewRoute,
     t.pages.newChat,
     t.pages.untitled,
     t.pages.appName,

frontend/src/core/threads/utils.ts

@@ -2,33 +2,10 @@ import type { Message } from "@langchain/langgraph-sdk";
 
 import type { AgentThread } from "./types";
 
-export interface ThreadQueryIntentInput {
-  pathThreadId?: string | null;
-  queryThreadId?: string | null;
-  isNewRoute?: boolean;
-}
-
-export interface ThreadQueryIntent {
-  threadId: string | undefined;
-  isNewThread: boolean;
-  showWelcomeStyle: boolean;
-}
-
 export function pathOfThread(threadId: string) {
   return `/workspace/chats/${threadId}`;
 }
 
-function normalizeThreadId(value?: string | null): string | undefined {
-  if (!value) {
-    return undefined;
-  }
-  const trimmed = value.trim();
-  if (!trimmed || trimmed === "new") {
-    return undefined;
-  }
-  return trimmed;
-}
-
 export function textOfMessage(message: Message) {
   if (typeof message.content === "string") {
     return message.content;