@tbox.cn/app-template-agent 0.7.5 → 0.9.0

package/apps/client/src/business/README.md

@@ -1,8 +1,8 @@
 # Business application entry
 
-`App.tsx` 是业务应用的唯一入口。模板基线默认挂载文旅 landing，用于展示完整的对话首页能力。
+`App.tsx` 是业务应用的唯一入口。缺省出厂 = 空装配 chat 形态（`AgentChatApp` 直出对话流，无 landing 注入——014 已退役）。商圈形态经 `tbox-app create --profile mall` 加装：mall-home 模块经 home 槽供给联单式主屏（欢迎区 + 单一联单活动主卡 + 会员/停车双快览 + 四域开发测试入口），消息追加在首页内容下方，底部保留三枚快捷指令与输入区。四域开发测试入口可见性由后端开关控制（`MALL_HOME_DEV_SERVICES` env → `GET /api/m/mall-home/config`，fail-closed 缺省隐藏；详见模板 ENV.md）。会员快览严格区分登录与入会状态，仅对已入会用户展示服务端返回的真实积分。
 
-无论生成普通页面还是对话智能体，都必须替换默认 `TourismLanding`，最终应用只能呈现用户要求的业务。`@/examples/**` 仅供模板维护者参考，除模板基线的 `App.tsx` 外禁止导入。生成完成后运行 `pnpm verify:generated`；示例引用或标记仍存在时验收会失败。
+业务能力经 `tbox-app module add` 扩展（shopping-guide/member/parking/promotion/alipay-activity），安装后自动装配进双端 `modules.ts`；联单节点是支付宝活动回执的支付笔数投影（mall-home 域），不从会话业务卡或本地默认值派生。生成完成后运行 `pnpm verify:generated`。
 
 ## 本地交互应用
 
@@ -32,7 +32,7 @@ business/
 
 图标用于辅助识别，不应压过标题、数据和主要内容。生成或修改业务页面时遵守以下约束：
 
-- 优先使用 `@phosphor-icons/react`，同一区域统一图标系列、`weight`、底板形状和用色方式。浅色底板上的普通入口默认使用 `weight="regular"`；不要为了缩小图标而统一改成 `bold`，否则线条会显得拥挤、厚重。`bold` 只用于确实需要强调的单个操作，`fill` 只用于选中态或少量主操作，不要整页铺满粗线或实心图标。
+- 优先使用 `@phosphor-icons/react`（模板缺省未内置，按需 `pnpm add @phosphor-icons/react` 引入；pnpm 严格 node_modules 下不随 kit 传递解析），同一区域统一图标系列、`weight`、底板形状和用色方式。浅色底板上的普通入口默认使用 `weight="regular"`；不要为了缩小图标而统一改成 `bold`，否则线条会显得拥挤、厚重。`bold` 只用于确实需要强调的单个操作，`fill` 只用于选中态或少量主操作，不要整页铺满粗线或实心图标。
 - **Phosphor 的 `size` 属性是最终屏幕 CSS 像素，不会经过 PostCSS 的 750 稿换算。** 不要按设计稿尺寸写 `size={36}`、`size={48}`。普通导航/按钮使用 `18~24`，网格入口使用 `20~24`，列表或卡片前导图标使用 `24~28`；只有真正的空状态或主视觉才能更大。
 - 图标底板写 Less 的 750 稿尺寸：四宫格/八宫格入口建议 `72~80px`，列表前导图标建议 `80~96px`。内部图形的视觉宽高不超过底板的 `55%~60%`。
 - 点击热区和图标视觉尺寸分开处理。按钮可以保持足够大的可点击区域，但不要靠放大图标填满热区。
@@ -71,12 +71,6 @@ business/
 
 ## 对话智能体应用
 
-需要保留平台对话能力时继续使用 `AgentChatApp`。业务首屏通过 `landing` 从 `business/App.tsx` 注入，并始终位于当前会话的卡片和消息之前；发送消息后 landing 不会消失。生成欢迎卡的智能体可以不注入 landing，直接让服务端卡片成为首屏内容。
+保留平台对话能力时继续使用 `AgentChatApp`。缺省无 landing 注入：空态首屏 = 平台对话，服务端欢迎卡经 `engine.emitCard` 旁路呈现（012 出卡协议）；mall 形态（`--profile mall`）下首屏由 home 槽供给（`MallHome`，来源 = `modules/module-mall-home`）。生成欢迎卡的智能体可直接由服务端出卡，无需改 `App.tsx`。
 
-```tsx
-export default function BusinessApp() {
-  return <AgentChatApp landing={YourLanding} />;
-}
-```
-
-修改对话组件、卡片或服务端工具时再读取对应目录的 `AGENTS.md`。不要修改通用 `pages/index` 来写死具体行业内容，也不要把 `src/examples/` 中的参考案例复制回运行时。
+修改对话组件、卡片或服务端工具时再读取对应目录的 `AGENTS.md`。不要修改通用首页入口来写死具体行业内容。

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, []);
@@ -17,15 +17,16 @@ export default function AgentChatApp({ landing }: { landing?: ChatLandingCompone
   useEffect(() => {
     authClient
       .ensureAuth()
-      .then((auth) => platformApi.getTboxSession(auth.identity.userId))
+      // 会话 β 收口：身份恒取 token（服务端 401/403），userId 不再上行
+      .then(() => platformApi.getTboxSession())
       .then(setSession)
       .catch((err) => appLogger.error('tbox session init failed:', err));
   }, []);
 
   const refreshSession = useCallback(async (): Promise<AdapterContextValue> => {
     platformApi.clearTboxSession();
-    const auth = await authClient.refreshAuth();
-    const data = await platformApi.getTboxSession(auth.identity.userId, true);
+    await authClient.refreshAuth();
+    const data = await platformApi.getTboxSession(true);
     setSession(data);
     return { tts, ...createPlatformAdapters(data, { tts }), refreshSession };
   }, [tts]);
@@ -37,7 +38,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();