@tbox.cn/app-template-agent 0.7.4 → 0.8.0

package/apps/client/src/cards/registry.ts

@@ -1,22 +1,37 @@
 /**
- * 卡片注册表：模块加载期快照（registerAll → ctx.cards.getAll()）。
+ * 卡片注册表 + 客户端组装上下文（模块加载期快照：registerAll → ctx 注册表）。
  *
  * 卡片注册发生在各模块 clientModule.register(ctx) 内（模块内自注册闭环），
  * 本文件仅消费组装端上下文；CardType 由 apps/client/src/modules.ts 从装配数组自动推导。
- * 组合层覆盖（CardOverrides）类型安全：模块删除 → CardType 收缩 → 编译报错。
+ *
+ * W3-2（薄装配）：三通道全经 ctx 读取——
+ * - CHAT_REGISTRY = 原始注册 + 覆盖通道（聊天视图；覆盖优先）；
+ * - CARD_REGISTRY = 原始注册（RawCardRenderer 详情弹层消费）；
+ * - INLINE_CARD_FILTER = 内联流过滤复合（ChatPage filterInlineCards 注入值）；
+ * - CLIENT_SLOTS = 槽注册表（home 槽由模块注册）。
  */
-import type { CardComponent } from '@tbox.cn/app-contracts';
+import type { CardComponent, TboxCardPayload } from '@tbox.cn/app-contracts';
 import { createClientContext } from '@tbox.cn/app-sdk/client';
 import { registerAll, type CardType } from '../modules';
 
-/** 组装端单例：注册全部模块客户端能力（模块加载期执行一次；registerMap 幂等） */
+/** 组装端单例：注册全部模块客户端能力（模块加载期执行一次；注册幂等告警） */
 const ctx = createClientContext();
 registerAll(ctx);
 
-/** 运行时卡片注册表（由各模块 clientModule.register 填充） */
+/** 运行时卡片注册表（原始形态；由各模块 clientModule.register 填充） */
 export const CARD_REGISTRY = ctx.cards.getAll() as Record<CardType, CardComponent>;
 
-export type { CardType } from '../modules';
+/** 聊天入口 registry：模块注册 + 覆盖通道（同 cardType 覆盖优先） */
+export const CHAT_REGISTRY: Record<string, CardComponent> = {
+  ...CARD_REGISTRY,
+  ...ctx.cards.getOverrides(),
+};
+
+/** 内联流过滤（域注册复合；无注册 = 恒等） */
+export const INLINE_CARD_FILTER = (cards: readonly TboxCardPayload[]): TboxCardPayload[] =>
+  ctx.cards.applyInlineFilters(cards);
 
-/** 组合层覆盖：类型安全的部分覆盖（002 §7.2），模块删除时键收缩 → 编译报错 */
-export type CardOverrides = Partial<Record<CardType, CardComponent>>;
+/** 客户端槽注册表（home 槽由模块 register 注册——W3-2 收口完成） */
+export const CLIENT_SLOTS = ctx.slots;
+
+export type { CardType } from '../modules';

package/apps/client/src/main.tsx

@@ -1,8 +1,39 @@
 import { StrictMode } from 'react';
 import { createRoot } from 'react-dom/client';
-import { configureRuntime, installGlobalErrorReporting } from '@tbox.cn/app-sdk/client';
+import { configureRuntime, createLogger, installGlobalErrorReporting } from '@tbox.cn/app-sdk/client';
 import App from './app';
-import './styles/global.less';
+import { configureChatConfigDefaults } from '@app/agent-ui-kit';
+import '@app/agent-ui-kit/theme/global.less';
+// 品牌主题（出厂接线——theme-tbox 平台品牌资产包：素材/标题经本包承载，模块零品牌资产）。
+// 换主题 = 替换三行（index.css + brand.js + applyTheme；叠加会致旧主题残留死重）；
+// 部署者轨迹见 cookbook·build-app-image「主题接线」。CLI 自由区，module sync 永不触碰。
+import '@tbox.cn/app-theme-tbox/index.css';
+import '@tbox.cn/app-theme-tbox/brand.js';
+import { applyTheme } from '@app/agent-ui-kit/theme';
+applyTheme('tbox');
+// chat.json 构建期快照 → kit 静态配置 store（createRoot 前注入，首帧即快照值；
+// HELLO_ACK settings 达后经 ChatPage 内水合覆盖）
+import chatConfigJson from '../../../config/chat.json';
+
+const bootLogger = createLogger('BOOT');
+
+// 壳→H5 接入契约观测：落页即打印 URL 参数（search + hash 双读源，全量加载仅一次）。
+// 壳侧若把参数移进 hash，mall-scope-url 的 search-only 读源会静默失效——这里第一时间暴露。
+// code/token 类值部分脱敏（前缀 + 长度，对齐 provider log-redact 惯例）。
+const SENSITIVE_PARAM = /^(code|token|auth_code|visitortoken|session)$/i;
+const collectParams = (source: string): Record<string, string> => {
+  const out: Record<string, string> = {};
+  new URLSearchParams(source).forEach((value, key) => {
+    out[key] = SENSITIVE_PARAM.test(key) ? `${value.slice(0, 6)}…(len=${value.length})` : value;
+  });
+  return out;
+};
+const hashQuery = window.location.hash.includes('?')
+  ? window.location.hash.slice(window.location.hash.indexOf('?') + 1)
+  : '';
+bootLogger.info(
+  `url params: ${JSON.stringify({ search: collectParams(window.location.search), hash: collectParams(hashQuery) })}`,
+);
 
 // H1：环境值注入点（SDK 零 Vite 依赖）——VITE_API_URL 空串 = 同源相对路径
 configureRuntime({ apiBaseUrl: import.meta.env.VITE_API_URL as string | undefined });
@@ -10,7 +41,10 @@ configureRuntime({ apiBaseUrl: import.meta.env.VITE_API_URL as string | undefine
 // 全局错误兜底：未捕获异常/rejection → 统一日志行（本地落地；上报扩展点见 SDK client logger）
 installGlobalErrorReporting();
 
+configureChatConfigDefaults(chatConfigJson as Record<string, unknown>);
+
 const el = document.getElementById('root');
+
 if (el) {
   createRoot(el).render(
     <StrictMode>

package/apps/client/src/modules.ts

@@ -8,20 +8,23 @@
 import type { ClientContext, InferModuleCards } from '@tbox.cn/app-sdk/client';
 
 // @tbox:imports-begin
-import { clientModule as moduleWeather } from '@app/module-weather/client';
+// 其余能力经 `tbox-app module add` 扩展（shopping-guide/member 等商圈模块；mall-home 经 profiles/mall）
 // @tbox:imports-end
 
 // @tbox:register-begin
+// W4 单一模板统一化：缺省出厂 = 空装配（chat 流；home 槽缺席 → chat 形态派生）——
+// mall-home（home 槽/覆盖卡/内联过滤）经 profiles/mall 加装（W5 接线）。
+// 形态约定：数组恒多行（register 锚区行式插入依赖换行结构；单行 [] 会让 add 只插 import 不插注册行）
 const modules = [
-  moduleWeather,
-];
+] as const;
 // @tbox:register-end
 
 // 自由区：可做装配级定制——条件注册、顺序调整
 
 /** 注册所有已安装模块（客户端装配——勿与 apps/server/src/modules.ts 混淆） */
 export function registerAll(ctx: ClientContext): void {
-  for (const m of modules) {
+  // 空装配下 (typeof modules)[number] = never：经最小注册面断言遍历（add 模块后自动收缩为具体类型）
+  for (const m of modules as readonly { register(ctx: ClientContext): void }[]) {
     m.register(ctx);
   }
 }

package/apps/client/src/pages/index/index.tsx

@@ -1,167 +1,23 @@
-import { useCallback, useEffect, useRef, useState, type ComponentType } from 'react';
+/**
+ * 首页（薄页，单一模板统一化 W2-5/W3-2）：kit ChatPage 单点装配——零域 import。
+ *
+ * - store = 应用薄壳 store（会话泳道 deps 注入 SDK 默认实现）；
+ * - cards/rawCards = 覆盖通道组装 / 原始形态（registry.ts 经 ctx 读取）；
+ * - slots = 客户端槽注册表（home 槽由 module-mall-home register 注册）；
+ * - filterInlineCards = 内联流过滤复合（域模块注册；无注册恒等）。
+ */
+import { ChatPage } from '@app/agent-ui-kit';
 import { useChatStore } from '@/store/chat';
-import { useChatConfigStore } from '@/store/chat-config';
-import { useTTSAutoPlay } from '@/hooks/useTTSAutoPlay';
-import { MessageBubble } from '@/components/MessageBubble';
-import { ChatInput } from '@/components/ChatInput';
-import { QuickCommands } from '@/components/QuickCommands';
-import ChatHeader from '@/components/ChatHeader';
-import ScrollToBottomButton from '@/components/ScrollToBottomButton';
-import PullDownIndicator from '@/components/PullDownIndicator';
-import { usePullDownHistory, consumeAutoSendQuery, runAutoSend } from '@tbox.cn/app-sdk/client';
-import { CardRenderer } from '@/cards/CardRenderer';
-import type { ChatInputMessage } from '@/types/chat';
-import './index.less';
-
-export interface ChatLandingProps {
-  onSend: (input: string | ChatInputMessage) => void;
-}
-
-export type ChatLandingComponent = ComponentType<ChatLandingProps>;
-
-interface IndexPageProps {
-  landing?: ChatLandingComponent;
-}
-
-export default function IndexPage({ landing: Landing }: IndexPageProps) {
-  const messages = useChatStore((s) => s.messages);
-  const historyMessages = useChatStore((s) => s.historyMessages);
-  const historyHasMore = useChatStore((s) => s.historyHasMore);
-  const isLoadingHistory = useChatStore((s) => s.isLoadingHistory);
-  const loadMoreHistory = useChatStore((s) => s.loadMoreHistory);
-  const isGenerating = useChatStore((s) => s.isGenerating);
-  const orphanCards = useChatStore((s) => s.orphanCards);
-  const cardsByMessageId = useChatStore((s) => s.cardsByMessageId);
-  const initConversation = useChatStore((s) => s.initConversation);
-  const destroy = useChatStore((s) => s.destroy);
-  const sendMessage = useChatStore((s) => s.sendMessage);
-  const cancelGeneration = useChatStore((s) => s.cancelGeneration);
-  const newConversation = useChatStore((s) => s.newConversation);
-  const authBlocked = useChatStore((s) => s.authBlocked);
-  const retryBootstrap = useChatStore((s) => s.retryBootstrap);
-  // chat settings 水合：HELLO_ACK 服务端真源 → 静态 store（ack 未达/键缺席保留构建期快照；
-  // 重连/新会话产生新 helloAck 再水合——applyServerSettings 幂等）
-  const serverSettings = useChatStore((s) => s.helloAck?.chatConfig?.settings);
-  const applyServerSettings = useChatConfigStore((s) => s.applyServerSettings);
-  useEffect(() => {
-    applyServerSettings(serverSettings);
-  }, [serverSettings, applyServerSettings]);
-
-  const [ttsAutoPlay, setTtsAutoPlay] = useState(false);
-  const [showScrollToBottom, setShowScrollToBottom] = useState(false);
-  const bodyRef = useRef<HTMLDivElement>(null);
-  // 初始 true：全新会话（未滚动）也可直接下拉加载历史（onScroll 才是真源更新）
-  const isAtTopRef = useRef(true);
-  const isNearBottomRef = useRef(true);
-
-  // TTS 自动播放：开启后边生成边流式朗读（服务端关态经水合强制停——防按钮隐藏仍朗读的僵尸路径）
-  const enableTTS = useChatConfigStore((s) => s.enableTTS);
-  useTTSAutoPlay(ttsAutoPlay && enableTTS);
-
-  const send = useCallback((input: string | ChatInputMessage) => sendMessage(input), [sendMessage]);
-
-  // 连接终态阻断（登录失败/scope 拒绝）：禁用输入 + 提示条 + 重试（authBlocked 非空 ⇒ socket 已关 ⇒ 发送必失败）
-  const blocked = authBlocked
-    ? { message: authBlocked, onRetry: () => void retryBootstrap() }
-    : undefined;
-
-  const scrollToBottom = useCallback(() => {
-    const el = bodyRef.current;
-    if (el) el.scrollTop = el.scrollHeight;
-    isNearBottomRef.current = true;
-    setShowScrollToBottom(false);
-  }, []);
-
-  const NEAR_BOTTOM = 150;
-  const onScroll = useCallback(() => {
-    const el = bodyRef.current;
-    if (!el) return;
-    isAtTopRef.current = el.scrollTop <= 5;
-    const distanceToBottom = el.scrollHeight - el.scrollTop - el.clientHeight;
-    isNearBottomRef.current = distanceToBottom < NEAR_BOTTOM;
-    setShowScrollToBottom(!isNearBottomRef.current);
-  }, []);
-
-  // 下拉加载历史：加载时保持滚动位置（记录加载前高度，加载后补偿）
-  const onLoadHistory = useCallback(async () => {
-    const el = bodyRef.current;
-    const prevHeight = el?.scrollHeight ?? 0;
-    await loadMoreHistory();
-    requestAnimationFrame(() => {
-      const cur = bodyRef.current;
-      if (cur) cur.scrollTop += cur.scrollHeight - prevHeight;
-    });
-  }, [loadMoreHistory]);
-
-  const pull = usePullDownHistory({
-    isAtTopRef,
-    isLoadingHistory,
-    hasMore: historyHasMore,
-    onLoad: onLoadHistory,
-    // touchmove 走容器上的非 passive 原生监听（web-view 内合成事件 passive，阻止不了原生滚动）
-    scrollRef: bodyRef,
-  });
-
-  useEffect(() => {
-    // 深链自动发送：同步消费（StrictMode 双挂载/刷新安全），引导完成后等连接就绪发送
-    const autoQuery = consumeAutoSendQuery();
-    void initConversation().then(async () => {
-      if (autoQuery) await runAutoSend(autoQuery, sendMessage);
-    });
-    return () => destroy();
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, []);
-
-  // 仅在贴近底部时自动滚动，避免打断用户上翻查看历史
-  // 依赖含 cardsByMessageId：012 主卡在文字完成后挂载、消息行增高，需补滚避免卡片截出视口
-  useEffect(() => {
-    if (isNearBottomRef.current) {
-      const el = bodyRef.current;
-      if (el) el.scrollTop = el.scrollHeight;
-    }
-  }, [messages, orphanCards, cardsByMessageId]);
+import { CARD_REGISTRY, CHAT_REGISTRY, CLIENT_SLOTS, INLINE_CARD_FILTER } from '@/cards/registry';
 
+export default function IndexPage() {
   return (
-    <div className="chat-page">
-      <div className="chat-page__bg" />
-      <ChatHeader
-        ttsAutoPlay={ttsAutoPlay}
-        onToggleTTS={() => setTtsAutoPlay((v) => !v)}
-        onClearChat={newConversation}
-      />
-
-      <div className="chat-page__body-wrapper">
-        <div
-          className="chat-page__body"
-          ref={bodyRef}
-          onScroll={onScroll}
-        >
-          {/* 下拉加载历史指示器 */}
-          <PullDownIndicator status={pull.pullStatus} distance={pull.pullDistance} />
-
-          {/* 历史消息（下拉加载） */}
-          {historyMessages.map((msg) => (
-            <MessageBubble key={msg.id} message={msg} />
-          ))}
-
-          {Landing ? <Landing onSend={send} /> : null}
-
-          {/* 业务旁路 emit 的卡片（如欢迎卡） */}
-          {orphanCards.map((card) => (
-            <CardRenderer key={card.id} card={card} />
-          ))}
-
-          {/* 消息（每条消息下的卡片由 MessageBubble 内部渲染） */}
-          {messages.map((msg) => (
-            <MessageBubble key={msg.id} message={msg} />
-          ))}
-        </div>
-
-        <ScrollToBottomButton visible={showScrollToBottom && isGenerating} onClick={scrollToBottom} />
-      </div>
-
-      {!blocked && <QuickCommands onCommand={send} />}
-      <ChatInput generating={isGenerating} blocked={blocked} onSend={send} onCancel={cancelGeneration} onNewChat={newConversation} />
-    </div>
+    <ChatPage
+      store={useChatStore}
+      cards={CHAT_REGISTRY}
+      rawCards={CARD_REGISTRY}
+      slots={CLIENT_SLOTS}
+      filterInlineCards={INLINE_CARD_FILTER}
+    />
   );
 }

package/apps/client/src/platform/AgentChatApp.tsx

@@ -5,11 +5,11 @@ const appLogger = createLogger('AgentChatApp');
 import { useCallback, useEffect, useMemo, useState } from 'react';
 import { AdapterProvider, createPlatformAdapters, type AdapterContextValue } from '@tbox.cn/app-sdk/client';
 import type { TboxSessionData } from '@tbox.cn/app-contracts';
-import IndexPage, { type ChatLandingComponent } from '@/pages/index/index';
+import IndexPage from '@/pages/index/index';
 import { authClient, platformApi } from './agent-runtime';
 
 /** 平台默认的全栈对话运行时。普通本地应用无需读取或修改。 */
-export default function AgentChatApp({ landing }: { landing?: ChatLandingComponent }) {
+export default function AgentChatApp() {
   const [session, setSession] = useState<TboxSessionData | null>(null);
   // TTS 不依赖 session，恒可用且保持同一实例（播放状态不因会话刷新丢失）
   const tts = useMemo(() => createPlatformAdapters().tts, []);
@@ -37,7 +37,7 @@ export default function AgentChatApp({ landing }: { landing?: ChatLandingCompone
 
   return (
     <AdapterProvider value={adapters}>
-      <IndexPage landing={landing} />
+      <IndexPage />
     </AdapterProvider>
   );
 }

package/apps/client/src/platform/agent-runtime.ts

@@ -4,12 +4,17 @@
  * 环境值（VITE_API_URL / VITE_AUTH_PROVIDER）由 main.tsx 经 configureRuntime / 选项注入（H1）。
  */
 import { createAuthClient, createPlatformApi } from '@tbox.cn/app-sdk/client';
+// 读源归位 TIER1（W1-①）：mall-scope-url 契约助手（search-only 语义；壳 URL 改写层契约见包注释）
+import { readMallIdFromUrl } from '@app/contracts-mall';
 
 /** VITE_AUTH_PROVIDER=external 时壳内换码登录转发外部（服务端需同步配置 AUTH_EXTERNAL_*） */
 const AUTH_PROVIDER = import.meta.env.VITE_AUTH_PROVIDER as string | undefined;
 
 export const authClient = createAuthClient({
   ...(AUTH_PROVIDER === 'external' ? { loginPlatform: 'external' } : {}),
+  // SPEZ-017：token 缓存域键——URL mallId 变更即失效旧 token 重登（跨 mall 防串域）。
+  // 读源与 chat.ts configureHelloContext 逐字符同源（mall-scope-url.ts 唯一真源，search-only）
+  scopeKey: () => readMallIdFromUrl() ?? '',
 });
 
 export const platformApi = createPlatformApi();

package/apps/client/src/store/chat.ts

@@ -1,202 +1,64 @@
 /**
- * 对话状态（Zustand）。
- * 使用 createCoreChatState 在同一个 create() 中合并核心状态与业务方法，
- * 共用同一份 set/get，避免双 store 断裂。
+ * 对话状态（Zustand）薄壳（单一模板统一化 W2-5）：
+ * 会话泳道/历史分页/凭证升级调度全部下沉 SDK createCoreChatState——
+ * 本壳只做域参数注入（HELLO context 采集）+ 排水订阅装配（应用侧一行）。
  */
 import { create } from 'zustand';
-import { createLogger } from '@tbox.cn/app-sdk/client';
-
-const conversationLogger = createLogger('CONVERSATION');
-const historyLogger = createLogger('HISTORY');
-const feedbackLogger = createLogger('FEEDBACK');
-import { createCoreChatState, getWsUrl, configureHelloContext } from '@tbox.cn/app-sdk/client';
+import {
+  createCoreChatState,
+  getWsUrl,
+  getLocation,
+  configureHelloContext,
+  subscribeSessionUpgradeDrain,
+} from '@tbox.cn/app-sdk/client';
 import type { CoreChatState } from '@tbox.cn/app-sdk/client';
-import { convertHistoryMessages } from '@tbox.cn/app-sdk/client';
-import type { PlatformHistoryMessage } from '@tbox.cn/app-sdk/client';
-import type { ChatMessage } from '@/types/chat';
-import type { IFeedbackAdapter } from '@tbox.cn/app-sdk/client';
-import type { AdapterContextValue } from '@tbox.cn/app-sdk/client';
-import { isSessionExpiredError } from '@/utils/session-error';
-import { toast } from '@/utils/toast';
+import { toast } from '@app/agent-ui-kit';
+import { readMallIdFromUrl, readMiniAppIdFromUrl } from '@app/contracts-mall';
 import { authClient, platformApi } from '@/platform/agent-runtime';
 
-// ── 历史加载代际标志（模块级）：newConversation 递增作废在途 loadMoreHistory（stale 响应整段丢弃）──
-let historyEpoch = 0;
-// ── 新建会话 in-flight 标志（模块级）：双击「新对话」防双建会话 ──
-let newConversationInFlight = false;
-// ── 终态阻断重试 in-flight 标志（模块级）：防并发重试 ──
-let retryBootstrapInFlight: Promise<void> | null = null;
-
-interface ChatState extends CoreChatState {
-  historyMessages: ChatMessage[];
-  historyHasMore: boolean;
-  isLoadingHistory: boolean;
-  initConversation: () => Promise<void>;
-  /** 新建会话：清会话态（连接复用）+ 重置历史态 + create 新会话 */
-  newConversation: () => Promise<void>;
-  loadMoreHistory: () => Promise<void>;
-  /** 终态阻断后重试：清匿名降级缓存 → 拆除连接 → 重走 initConversation（重复点击防抖） */
-  retryBootstrap: () => Promise<void>;
-  submitFeedback: (
-    messageId: string,
-    type: 'like' | 'dislike' | 'cancel',
-    adapter: IFeedbackAdapter,
-    refreshSession?: () => Promise<AdapterContextValue>,
-  ) => Promise<void>;
-}
-
-export const useChatStore = create<ChatState>((set, get) => ({
-  // 核心状态：所有 set/get 闭包绑定到此 store（006：不再创建客户端 sessionId）
+export const useChatStore = create<CoreChatState>()((set, get) => ({
+  // 核心状态：所有 set/get 闭包绑定到此 store（006：不再创建客户端 sessionId）；
+  // 会话泳道 deps（platformApi/authClient）注入 SDK 默认实现
   ...createCoreChatState(
-    { getWsUrl: () => getWsUrl(), toast },
+    {
+      getWsUrl: () => getWsUrl(),
+      toast,
+      platformApi,
+      authClient,
+      // session.credentials-refreshed effect → 升级调度（清缓存冷登 + 幂等重连；守卫在 scheduleSessionUpgrade 内）
+      onSessionCredentialsRefreshed: () => void get().scheduleSessionUpgrade(),
+    },
     set as (partial: any) => void,
     get as () => any,
-  ),  // 业务扩展状态
-  historyMessages: [],
-  historyHasMore: true,
-  isLoadingHistory: false,
-
-  initConversation: async () => {
-    const userId = await authClient.resolveUserId();
-    set({ userId });
-    try {
-      let conversationId: string | null = null;
-      // 006：create 的 userId 只来自 token 身份（body 废弃）；匿名（无 token）不可建会话 → 直接走 no-conv 分支
-      if (!authClient.getAuthState()?.token) {
-        conversationLogger.warn('anonymous: skip create conversation (no-conv)');
-      } else {
-        for (let i = 0; i < 2 && !conversationId; i++) {
-          try {
-            const { status, data } = await platformApi.createConversation();
-            if (status === 200 && data?.conversationId) conversationId = data.conversationId;
-          } catch (e) {
-            conversationLogger.warn(`createConversation 失败（重试 ${i + 1}/2）：err=${(e as Error).message}`);
-          }
-        }
-      }
-      if (conversationId) set({ conversationId });
-      get().init();
-    } catch (err) {
-      conversationLogger.error('init error:', err);
-      get().init();
-    }
-  },
-
-  // 终态阻断（登录失败/scope 拒绝）后重试：清匿名降级缓存（不清则必复败）→ 拆连接 → 重走完整引导
-  retryBootstrap: () => {
-    if (retryBootstrapInFlight) return retryBootstrapInFlight; // 并发重试防抖
-    const task = (async () => {
-      authClient.clearAuth(); // 匿名降级结果被缓存，不清则重试必然复败
-      get().destroy();
-      await get().initConversation();
-    })();
-    const tracked = task.finally(() => {
-      if (retryBootstrapInFlight === tracked) retryBootstrapInFlight = null;
-    });
-    retryBootstrapInFlight = tracked;
-    return tracked;
-  },
-
-  // 新建会话：连接复用（clearChat 不断连——连接/身份是身份域），create 拿新会话键
-  newConversation: async () => {
-    if (newConversationInFlight) return; // 双击防双建会话
-    newConversationInFlight = true;
-    try {
-      historyEpoch++; // 作废在途历史加载（stale 响应整段丢弃，含 isLoadingHistory 复位）
-      get().clearChat(); // SDK：内聚取消运行中 run + 清会话态
-      set({ historyMessages: [], historyHasMore: true, isLoadingHistory: false });
-      await get().initConversation(); // create 新会话；init 对 OPEN 连接幂等早返
-    } finally {
-      newConversationInFlight = false;
-    }
-  },
-
-  loadMoreHistory: async () => {
-    const { isLoadingHistory, historyHasMore, historyMessages } = get();
-    if (isLoadingHistory || !historyHasMore) return;
-    const epoch = historyEpoch; // 快照：newConversation 递增后本响应作废
-    set({ isLoadingHistory: true });
-
-    const pageSize = 5;
-    const earliestRequestId =
-      historyMessages.length > 0
-        ? historyMessages[0].requestId
-        : get().messages.find((m) => m.requestId)?.requestId;
-
-    // 006：有 token 身份时服务端按 token 取归属；无 token（匿名/兼容）保留 query userId
-    try {
-      const { status, data } = await platformApi.listMessages({
-        pageSize,
-        ...(authClient.getAuthState()?.token
-          ? {}
-          : { userId: get().userId }),
-        ...(earliestRequestId ? { beforeId: earliestRequestId } : {}),
-      });
-      // stale 响应（newConversation 已重置态）：整段丢弃——含 isLoadingHistory 复位也不落
-      if (epoch !== historyEpoch) return;
-      if (status === 200 && data) {
-        const rawList: PlatformHistoryMessage[] = (data.data as PlatformHistoryMessage[]) || [];
-        const currentRequestIds = new Set(get().messages.map((m) => m.requestId).filter(Boolean));
-        const filtered = rawList.filter(
-          (item) => !item.outerBusinessId || !currentRequestIds.has(item.outerBusinessId),
-        );
-        // SDK 单真源：消息对 + 历史卡片桶同 key 派生（平台 id 字段归一；isHistory 已由服务端标记）
-        const { messages: newMessages, cardsByMessageId } = convertHistoryMessages(filtered.reverse());
-        set((s) => ({
-          historyMessages: [...newMessages, ...s.historyMessages],
-          historyHasMore: rawList.length >= pageSize,
-          isLoadingHistory: false,
-          cardsByMessageId: { ...s.cardsByMessageId, ...cardsByMessageId },
-        }));
-      } else {
-        set({ isLoadingHistory: false });
-      }
-    } catch (err) {
-      historyLogger.error('load more error:', err);
-      if (epoch !== historyEpoch) return; // stale：newConversation 已重置 isLoadingHistory
-      set({ isLoadingHistory: false });
-    }
-  },
-
-  submitFeedback: async (messageId, type, adapter, refreshSession) => {
-    const oldMsg = get().messages.find((m) => m.id === messageId);
-    const oldFeedbackState = oldMsg?.feedbackState ?? 'none';
-    const feedbackRequestId = oldMsg?.requestId;
-    if (!feedbackRequestId) {
-      feedbackLogger.warn('no requestId for message', messageId);
-      return;
-    }
-    const newFeedbackState = type === 'cancel' ? 'none' : type;
-    get().updateMessage(messageId, { feedbackState: newFeedbackState as 'none' | 'like' | 'dislike' });
-
-    const feedbackMap = { like: 'LIKE' as const, dislike: 'DISLIKE' as const, cancel: 'CANCEL' as const };
-    try {
-      const result = await adapter.addTag(feedbackRequestId, feedbackMap[type]);
-      if (!result.success) get().updateMessage(messageId, { feedbackState: oldFeedbackState });
-    } catch (err) {
-      if (isSessionExpiredError(err) && refreshSession) {
-        try {
-          const newAdapters = await refreshSession();
-          if (newAdapters.feedback) {
-            const retry = await newAdapters.feedback.addTag(feedbackRequestId, feedbackMap[type]);
-            if (!retry.success) get().updateMessage(messageId, { feedbackState: oldFeedbackState });
-            return;
-          }
-        } catch (retryErr) {
-          feedbackLogger.error('retry failed:', retryErr);
-        }
-      }
-      get().updateMessage(messageId, { feedbackState: oldFeedbackState });
-    }
-  },
+  ),
 }));
 
 // 011 L4：HELLO context 采集——mallId 经 URL query 采集（mall 部署；无 mallId 时不携带 context）
+// 停车缴费按用户就近车场查（服务端 #ensureParkingId 用 lbs 反查 cityId→最近车场），
+// 故伴采集实时 lbs（best-effort：H5/无定位权限时静默丢弃，服务端自行降级 plaza）。
+// getter 同步签名，不能现 await getLocation() → 装配期先发起，缓存供 getter 同步读取。
+let cachedLbs: { latitude: string; longitude: string } | undefined;
+void getLocation()
+  .then((loc) => {
+    if (Number.isFinite(loc.latitude) && Number.isFinite(loc.longitude)) {
+      cachedLbs = { latitude: String(loc.latitude), longitude: String(loc.longitude) };
+    }
+  })
+  .catch(() => {
+    // 定位不可用（H5 沙箱/未授权）→ 不带 location，服务端走 plaza 降级
+  });
 configureHelloContext(() => {
-  const mallId = new URLSearchParams(window.location.search).get('mallId');
-  const miniAppId = new URLSearchParams(window.location.search).get('miniAppId');
+  // 读源收敛（CS-8）：mallId ?? plazaId 单一 helper（contracts-mall runtime 唯一真源）
+  const mallId = readMallIdFromUrl();
+  const miniAppId = readMiniAppIdFromUrl();
   if (!mallId) return undefined;
-  return { mall: { mallId, ...(miniAppId ? { miniAppId } : {}) } };
+  return {
+    mall: { mallId, ...(miniAppId ? { miniAppId } : {}) },
+    ...(cachedLbs ? { location: cachedLbs } : {}),
+  };
 });
 
 // 4002 scope 拒绝 / 4001 鉴权耗尽的终态提示与禁用由 SDK 统一出站（chat-store configureWsFatalCloseHandler）
+
+// 凭证升级排水（W2-2 SDK 装配位）：生成中排队的升级在 isGenerating true→false 跃迁时执行
+subscribeSessionUpgradeDrain(useChatStore);

package/apps/client/src/test/setup.ts

@@ -0,0 +1,7 @@
+/**
+ * vitest 全局 setup：React act() 环境声明单一真源。
+ * 此前散落各用例内联声明、多数漏声明（act 告警刷屏 CI 日志）；
+ * 统一收敛后新用例自动继承，无需逐文件记忆。node 环境纯逻辑用例设此全局无副作用。
+ */
+(globalThis as typeof globalThis & { IS_REACT_ACT_ENVIRONMENT?: boolean })
+  .IS_REACT_ACT_ENVIRONMENT = true;

package/apps/client/vite.config.ts

@@ -1,3 +1,4 @@
+/// <reference types="vitest" />
 import { defineConfig, type Plugin } from 'vite';
 import react from '@vitejs/plugin-react';
 import pxToRem from 'postcss-pxtorem';
@@ -31,7 +32,9 @@ export default defineConfig(async ({ command }) => {
   // __dirname 基准 = apps/client：构件区在模板根（上一级×2）
   const devOverridePath = resolve(__dirname, '../../.tbox-dev.local/vite-override.mjs');
   const devPlugins: Plugin[] = [];
-  if (existsSync(devOverridePath)) {
+  // 作用域门：override 仅 dev-serve 生效——build/vitest 不受 dev 会话残留影响
+  // （G2 防线；门与探针标记同文件，guard 另断言门条件在场）
+  if (command === 'serve' && !process.env.VITEST && existsSync(devOverridePath)) {
     const { default: tboxDevOverride } = await import(pathToFileURL(devOverridePath).href);
     devPlugins.push(tboxDevOverride());
   }
@@ -48,6 +51,18 @@ export default defineConfig(async ({ command }) => {
         fs: resolve(__dirname, 'src/shims/node-stub.ts'),
         path: resolve(__dirname, 'src/shims/node-stub.ts'),
       },
+      // dev 域 React 单实例（G1/G2 防线）：双 dev 入口经本文件合并生效（middleware
+      // dev 加载本文件且 command==='serve'）；build 恒不继承——产物位稳定性。
+      ...(command === 'serve' ? { dedupe: ['react', 'react-dom'] } : {}),
+    },
+    // vitest 并入同一 config（vitest 无专属 config 文件时本就加载本文件）：
+    // act() 环境声明统一入口——此前散落各用例内联、多数漏声明 → act 告警刷屏 CI 日志。
+    // environment 保持每文件 @vitest-environment pragma（纯逻辑用例不付 DOM 开销）。
+    test: {
+      setupFiles: ['src/test/setup.ts'],
+      // W3-2：client 测试随域迁 module-mall-home（页级集成测试 = 模块 tests/index.test.tsx）；
+      // 模板仅留薄页装配，零测试文件合法（新增客户端测试时移除本旗标）
+      passWithNoTests: true,
     },
     css: {
       postcss: { plugins: [pxToRemPlugin] },

package/apps/server/package.json

@@ -11,7 +11,6 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@app/module-weather": "workspace:*",
     "@tbox.cn/agent-plugin": "catalog:",
     "@tbox.cn/app-sdk": "catalog:",
     "@tbox.cn/app-contracts": "catalog:",