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

package/apps/server/tests/agent-prompt.test.ts

@@ -0,0 +1,81 @@
+import { describe, expect, it } from 'vitest';
+import { loadAgentPromptConfig } from '@tbox.cn/app-sdk/server';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+/**
+ * agent.jsonc 提示词护栏（经 SDK loader 实读——防配置 typo 静默退化 + 厂商中立锚）。
+ * W4 单一模板统一化双段语义：
+ * - 缺省出厂 = 空装配（config/ 无 agent.jsonc）→ loader 走 SDK 默认兜底单行（chat 形态零域广告）；
+ * - mall 画像 = profiles/mall/config/agent.jsonc（--profile mall 经 --config-dir 通道注入）——
+ *   四章节/禁工具名/承接句/中立锚断言锚定画像资产文件（create 展开/stage mall 完整档消费）。
+ *
+ * 部署态让位（2026-09-10）：--config-dir 注入真实厂商档（integrations.json root provider 为
+ * 真实厂商名而非 mock）时 agent.jsonc 为部署方品牌人设——中立锚仅守卫出厂/mock 态（mock 档
+ * 不注入 agent.jsonc，保持出厂中立）。stage 真实厂商档完整链依赖此让位。
+ *
+ * 装配态感知（2026-09-17 评审修复）：第一段的 config/ 状态在生成应用是装配变量——mall 完整档
+ * 素材注入、support 自含 config（出厂在场）均使 agent.jsonc 在场，恒常量断言失配（stage
+ * 完整档 94/95 缺口）。用例改为形态感知：缺席 → 兜底断言（出厂守卫保持）；在场 → 读文件断言。
+ */
+describe('agent.jsonc（兜底语义：空装配 → SDK 默认单行；装配态注入 → 读文件）', () => {
+  const cfg = loadAgentPromptConfig(path.resolve(__dirname, '../../../config'));
+  const injected = existsSync(path.resolve(__dirname, '../../../config/agent.jsonc'));
+
+  it('config/ 无 agent.jsonc → loader 兜底单行（零域广告）；在场（素材注入/自含）→ 读文件非兜底', () => {
+    if (injected) {
+      expect(cfg.instructions).not.toContain('你是智能助手，帮助用户完成日常问答与业务事务');
+      expect(cfg.instructions).toBeTruthy();
+    } else {
+      expect(cfg.instructions).toContain('你是智能助手，帮助用户完成日常问答与业务事务');
+    }
+  });
+});
+
+describe('agent.jsonc（mall 画像资产：profiles/mall/config）', () => {
+  const MALL_CONFIG = path.resolve(__dirname, '../../../profiles/mall/config');
+  const cfg = loadAgentPromptConfig(MALL_CONFIG);
+
+  it('loader 成功加载（非兜底：不含 SDK 默认单行）', () => {
+    expect(cfg.instructions).not.toContain('你是智能助手，帮助用户完成日常问答与业务事务');
+    expect(cfg.instructions).toBeTruthy();
+  });
+
+  it('首行身份句（不以标题开头）+ 四章节结构', () => {
+    const lines = cfg.instructions.split('\n');
+    expect(lines[0].startsWith('你是')).toBe(true);
+    for (const section of ['# 服务范围', '# 业务规则', '# 沟通风格', '# 兜底承接']) {
+      expect(lines).toContain(section);
+    }
+  });
+
+  it('禁工具名护栏与承接句规则在场（正文只出白话与结果）', () => {
+    expect(cfg.instructions).toContain('任何回复正文不出现工具名、接口名、字段名');
+    expect(cfg.instructions).toContain('需要提及操作时用业务语言');
+    expect(cfg.instructions).toContain('先用一句贴合本轮诉求的话承接再发起');
+  });
+
+  it('示例工具名只出现在禁令行，不作为正面示例扩散到其他行', () => {
+    const lines = cfg.instructions.split('\n').filter((line) => line.includes('listVehicles') || line.includes('customer-service-faq'));
+    expect(lines).toHaveLength(1);
+    expect(lines[0]).toContain('不出现工具名');
+  });
+
+  it('pre-tool 定性覆盖实际注入面（FAQ 与碰一碰）', () => {
+    expect(cfg.instructions).toContain('客服 FAQ 条目、碰一碰活动详情');
+  });
+
+  it('厂商中立：无品牌人设名（词表字面量零出现；厂商档部署 = 部署方品牌人设让位）', () => {
+    // 字面量拼接拆分：guard-vendor-neutrality 正则匹配源码行——拆开后门禁天然不命中，
+    // 免行内豁免标记；勿合并为连续字面量（会触发自家门禁）
+    expect(cfg.instructions).not.toContain('万' + '小豆');
+  });
+
+  it('memoryInstructions 在场（记忆域措辞随配置）', () => {
+    expect(cfg.memoryInstructions).toBeTruthy();
+    expect(cfg.memoryInstructions).toContain('长期记忆');
+  });
+});

package/apps/server/tests/cards-registry.test.ts

@@ -1,8 +1,6 @@
-// 卡片 / 工具 registry 一致性守护测试（自注册闭环版）。
-// 通过 registerAll(ctx) 收集真实注册状态，替代原手写 registry 静态断言。
+// 卡片 / 工具 registry 一致性守护测试（自注册闭环版，mall 模板）。
 // v2 出卡协议：tool→card 绑定（allowedTools/cardResolver）退场——出卡由工具出参
 // cards 字段运行期声明，registry 仅余 cardType 注册与 dataSchema 校验职责。
-// 注：C 方案下卡片渲染在 client（React 组件），server 无 template.html，故移除原 C12（模板占位符 ∈ schema）。
 import { describe, it, expect } from 'vitest';
 import { diagnosePlugins } from '@tbox.cn/agent-plugin/doctor';
 import { createServerContext, createPluginIntegration } from '@tbox.cn/app-sdk/server';

package/apps/server/tests/deployment-loader.test.ts

@@ -1,14 +1,14 @@
 /**
- * integrations v4 装载链单测（deployment 派生自 integrations——单文件真源；base 精简面）。
- * 覆盖：投影穿透（attributes 存活）/ 无参考表 → 空平面 + defaultInstanceId 独立在场 /
- * stale 防线 / buildDefaultMallContext mallId-only 注入 / deploymentFromIntegrations 装配活性。
+ * integrations 装载链单测（W3-1 收窄：控制平面投影/域装配段随 mall 语义迁
+ * modules/module-mall-core/tests/assembly.test.ts——本文件只测模板装载壳）。
+ * 覆盖：strict 校验 fail-fast / 占位展开（env 通道）/ defaultInstanceId 引用完整性 /
+ * stale 防线（deployments/development.json 含 malls → error 迁移指引）。
  */
 import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { afterAll, describe, expect, it } from 'vitest';
 import { loadIntegrations, assertNoStaleDeploymentControlPlane } from '../src/config/integration.js';
-import { deploymentFromIntegrations, buildDefaultMallContext } from '../src/config/deployment.js';
 
 const dir = mkdtempSync(join(tmpdir(), 'tbox-deploy-loader-'));
 afterAll(() => rmSync(dir, { recursive: true, force: true }));
@@ -19,6 +19,7 @@ function writeConfig(name: string, data: unknown): string {
   return p;
 }
 
+/** 模拟 real-env 素材形态：root instances 注册表 + defaultInstanceId + services */
 const fullIntegrations = {
   provider: 'acme',
   instances: [
@@ -36,39 +37,29 @@ const fullIntegrations = {
   services: { 'member.account': {} },
 };
 
-describe('loadIntegrations：投影穿透', () => {
-  it('contactPhone/location/miniAppId 经投影存活到 controlPlane（不被 zod strip）', () => {
+describe('loadIntegrations：装载链（strict + 占位展开 + 缺席语义）', () => {
+  it('全量素材可载入（config 停留原样；投影消费方 = module-mall-core）', () => {
     const loaded = loadIntegrations(writeConfig('full.json', fullIntegrations));
-    expect(loaded?.controlPlane.malls[0]).toMatchObject({
-      mallId: 'mall-demo',
-      name: '示例商场',
-      miniAppId: 'demo-app',
-      contactPhone: '0571-88888888',
-      location: { lat: 30.2741, lon: 120.1551, address: '湖滨示范点' },
-    });
-    expect(loaded?.controlPlane.defaultMallId).toBe('mall-demo');
+    expect(loaded?.config.defaultInstanceId).toBe('mall-demo');
+    expect(loaded?.source.endsWith('full.json')).toBe(true);
   });
 
-  it('拼错 attributes 键 → fail-fast（strict——报错含实例 id 与允许键清单）', () => {
+  it('attributes 严格校验归投影（W3-1：loader 不过滤——拼错键由 mall-core register 期 fail-fast）', () => {
     const p = writeConfig('typo-attr.json', {
       instances: [{ id: 'm1', name: 'x', attributes: { miniAppid: 'typo' } }],
       services: {},
     });
-    expect(() => loadIntegrations(p)).toThrow(/m1.*允许键|允许键.*miniAppId/s);
-  });
-
-  it('无参考表 → 空平面；defaultInstanceId 独立在场 = 动态默认（env 注入形态）', () => {
-    const loaded = loadIntegrations(writeConfig('no-table.json', { provider: 'globex', defaultInstanceId: '42020300520', services: {} }));
-    expect(loaded?.controlPlane.malls).toEqual([]);
-    expect(loaded?.controlPlane.defaultMallId).toBe('42020300520');
+    // 装载壳只做展开+parse；投影（含允许键清单 strict）在 module-mall-core 装配期
+    // （module tests/assembly.test.ts 覆盖 fail-fast 语义——启动链同点报错）
+    expect(loadIntegrations(p)?.config.instances?.length).toBe(1);
   });
 
-  it('defaultInstanceId 占位 ${DEFAULT_MALL_ID} → 展开后载入；缺 env fail-fast', () => {
+  it('defaultInstanceId 占位 ${DEFAULT_MALL_ID} → loader 展开后载入；缺 env fail-fast', () => {
     const p = writeConfig('env-placeholder.json', { defaultInstanceId: '${DEFAULT_MALL_ID}', services: {} });
     const saved = process.env.DEFAULT_MALL_ID;
     process.env.DEFAULT_MALL_ID = '1102588';
     try {
-      expect(loadIntegrations(p)?.controlPlane.defaultMallId).toBe('1102588');
+      expect(loadIntegrations(p)?.config.defaultInstanceId).toBe('1102588');
       delete process.env.DEFAULT_MALL_ID;
       expect(() => loadIntegrations(p)).toThrow(/DEFAULT_MALL_ID/);
     } finally {
@@ -76,6 +67,19 @@ describe('loadIntegrations：投影穿透', () => {
       else process.env.DEFAULT_MALL_ID = saved;
     }
   });
+
+  it('defaultInstanceId ∉ instances ids → zod 拒载（SDK 单源防线）', () => {
+    const p = writeConfig('bad-default.json', {
+      instances: [{ id: 'm1', name: 'x' }],
+      defaultInstanceId: '99999',
+      services: {},
+    });
+    expect(() => loadIntegrations(p)).toThrow(/defaultInstanceId/);
+  });
+
+  it('文件缺席 → undefined（槽位解析不启用）', () => {
+    expect(loadIntegrations(join(dir, 'absent.json'))).toBeUndefined();
+  });
 });
 
 describe('stale 防线（v4：deployments/development.json 含 malls → error 迁移指引）', () => {
@@ -103,38 +107,13 @@ describe('stale 防线（v4：deployments/development.json 含 malls → error
       rmSync(root, { recursive: true, force: true });
     }
   });
-});
 
-describe('buildDefaultMallContext：v4 mallId-only 注入', () => {
-  it('defaultMallId + miniAppId 齐备 → 拼装完整 context；root 优先', () => {
-    const loaded = loadIntegrations(writeConfig('ctx-ok.json', fullIntegrations))!;
-    expect(buildDefaultMallContext(loaded.controlPlane, 'root-app')).toEqual({
-      mall: { mallId: 'mall-demo', miniAppId: 'root-app' },
-    });
-    expect(buildDefaultMallContext(loaded.controlPlane)).toEqual({
-      mall: { mallId: 'mall-demo', miniAppId: 'demo-app' },
-    });
-  });
-
-  it('双缺 miniAppId → mallId-only 注入（v4：不再 warn-refuse 静默失效）', () => {
-    const loaded = loadIntegrations(writeConfig('ctx-nomini.json', { defaultInstanceId: 'm9', services: {} }))!;
-    expect(buildDefaultMallContext(loaded.controlPlane)).toEqual({ mall: { mallId: 'm9' } });
-  });
-
-  it('无 defaultMallId → undefined（不兜底）', () => {
-    const loaded = loadIntegrations(writeConfig('ctx-nodefault.json', { services: {} }))!;
-    expect(buildDefaultMallContext(loaded.controlPlane)).toBeUndefined();
-  });
-});
-
-describe('deploymentFromIntegrations：装配活性', () => {
-  it('assembly 三函数派生自投影控制平面', () => {
-    const loaded = loadIntegrations(writeConfig('asm.json', fullIntegrations))!;
-    const d = deploymentFromIntegrations(loaded);
-    expect(d.controlPlane).toBe(loaded.controlPlane);
-    expect(d.assembly.validateScope({ mall: { mallId: 'mall-demo' } })).toBe(true);
-    expect(d.assembly.validateScope({ mall: { miniAppId: 'a' } })).toBe(false);
-    expect(d.assembly.extractScopeKey({ identity: { userId: 'u', source: 'external' }, attributes: { mall: { mallId: 'mall-demo' } } })).toBe('mall-demo');
-    expect(d.assembly.buildScope({ mall: { mallId: 'mall-demo' } })).toEqual({ mallId: 'mall-demo' });
+  it('文件缺席 → 不阻断', () => {
+    const root = mkdtempSync(join(tmpdir(), 'tbox-stale-absent-'));
+    try {
+      expect(() => assertNoStaleDeploymentControlPlane(root)).not.toThrow();
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
   });
 });

package/apps/server/tests/tool-runtime.test.ts

@@ -10,7 +10,7 @@ import { registerAll } from '../src/modules.js';
 import { translateTool } from '../src/tools/translate.js';
 
 describe('tool runtime 宿主装配（自注册闭环）', () => {
-  it('合并模块工具（v2：无 cardResolver——出卡由工具出参 cards 运行期声明）', async () => {
+  it('空装配（mall 模板）：无模块工具，app 级工具正常注册', async () => {
     const ctx = createServerContext();
     await registerAll(ctx);
 
@@ -18,31 +18,13 @@ describe('tool runtime 宿主装配（自注册闭环）', () => {
       loadPlugins: async () => ({ tools: {}, references: [] }),
     });
 
-    expect(Object.keys(runtime.tools)).toEqual(
+    // 缺省空装配：模块工具不存在，仅 app 级工具
+    expect(Object.keys(runtime.tools)).not.toEqual(
       expect.arrayContaining(['getWeather']),
     );
   });
 
-  it('weather 参考实现：execute 出参携带 cards 声明（顶层答话事实 + cards 数组）', async () => {
-    const ctx = createServerContext();
-    await registerAll(ctx);
-
-    const runtime = await createSdkToolRuntime(ctx, {
-      loadPlugins: async () => ({ tools: {}, references: [] }),
-    });
-    const weather = runtime.tools.getWeather as unknown as {
-      execute: (input: { city: string }, context: unknown) => Promise<Record<string, unknown>>;
-    };
-    const out = await weather.execute({ city: '杭州' }, {} as never);
-    // 顶层答话事实
-    expect(out).toMatchObject({ city: '杭州', temp: expect.any(Number), weather: expect.any(String) });
-    // cards 出卡声明（capture 前原始形态：data = 顶层事实本体，不含 cards 键自身）
-    // W7 note 契约：主体+关键事实（城市/天气/温度）
-    const { cards, ...facts } = out;
-    expect(cards).toEqual([{ cardType: 'weather', data: facts, note: `杭州 ${facts.weather} ${facts.temp}℃` }]);
-  });
-
-  it('未注册的 tool 不进运行时工具集（仅作为模型上下文面之外）', async () => {
+  it('未注册的 tool 不进运行时工具集（v2：无 cardResolver——出卡由工具出参 cards 运行期声明）', async () => {
     const ctx = createServerContext();
     await registerAll(ctx);
 
@@ -81,45 +63,30 @@ describe('tool runtime 宿主装配（自注册闭环）', () => {
   });
 });
 
-describe('长期记忆装配（017：默认 inmemory 开启 + off 逃生舱）', () => {
+describe('长期记忆装配（017：mall 域默认 inmemory + mallId 隔离 scope）', () => {
   it('resolveMemoryStore 缺省 → inmemory（默认开启）', () => {
     const m = resolveMemoryStore({});
     expect(m.enabled).toBe(true);
     expect(m.mode).toBe('inmemory');
     expect(m.store).toBeDefined();
-    expect(m.store!.capabilities).toBeUndefined(); // 缺省全真
   });
 
-  it('resolveMemoryStore off → 关闭（enabled=false）', () => {
+  it('resolveMemoryStore off → 关闭（enabled=false，路由面与工具零装配）', () => {
     const m = resolveMemoryStore({ store: 'off' });
     expect(m.enabled).toBe(false);
     expect(m.mode).toBe('off');
     expect(m.store).toBeUndefined();
   });
 
-  it('resolveMemoryStore knowledge 无 kbId → warn 回退 inmemory', () => {
-    const m = resolveMemoryStore({ store: 'knowledge' });
-    expect(m.enabled).toBe(true);
-    expect(m.mode).toBe('inmemory');
-  });
-
-  it('resolveMemoryStore knowledge 三件套齐备 → knowledge 模式（2026-09-01 翻转：caps 缺省全 true——平台已发布生产）', () => {
+  it('resolveMemoryStore knowledge 三缺一回退；齐备 → knowledge（caps 缺省全 true——2026-09-01 翻转）', () => {
+    expect(resolveMemoryStore({ store: 'knowledge' }).mode).toBe('inmemory');
+    expect(resolveMemoryStore({ store: 'knowledge', kbId: 'kb-1', apiKey: 'k' }).mode).toBe('inmemory');
     const m = resolveMemoryStore({ store: 'knowledge', kbId: 'kb-1', kbDocId: 'doc-1', apiKey: 'k' });
     expect(m.mode).toBe('knowledge');
     expect(m.store!.capabilities).toEqual({ save: true, search: true, list: true, delete: true });
   });
 
-  it('resolveMemoryStore knowledge 缺 kbDocId → warn 回退 inmemory（三缺一）', () => {
-    const m = resolveMemoryStore({ store: 'knowledge', kbId: 'kb-1', apiKey: 'k' });
-    expect(m.mode).toBe('inmemory');
-  });
-
-  it('resolveMemoryStore 非法值 → warn 回退 inmemory', () => {
-    const m = resolveMemoryStore({ store: 'bogus' });
-    expect(m.mode).toBe('inmemory');
-  });
-
-  it('装配态（inmemory）→ 引擎装配链路无异常（chat 完成 + 本地 skills 不受影响）', async () => {
+  it('装配态（inmemory）→ 引擎装配链路无异常 + 本地 skills 不受影响', async () => {
     const ctx = createServerContext();
     await registerAll(ctx);
     const engine = await createEngineFromContext(ctx, {
@@ -127,25 +94,22 @@ describe('长期记忆装配（017：默认 inmemory 开启 + off 逃生舱）',
       model: {} as never,
       memory: { store: createInMemoryMemoryStore() },
     });
-    // 触发一轮 chat 使装配链路完整执行（无 runCtx → 匿名 → 零 recall）
-    await engine.chat('t-mem', 'hi', () => {});
-    // 工具名断言在 SDK build-engine 测试覆盖；模板层断言装配链路无异常 + skills 面不受影响
-    expect(engine.listSkills().length).toBeGreaterThan(0);
+    // 触发一轮 chat 使装配链路完整执行（无 runCtx → 匿名 → 零 recall）。
+    // skills/preTools 面不做形状断言：模板源空装配为 []，生成应用（module add 后）非空——
+    // 属装配环境差异而非记忆特性；本用例只锁记忆装配链路无异常（chat 完成即通过）。
+    await engine.chat('t-mem-mall', 'hi', () => {});
   });
 
-  it('off 态 → 引擎无记忆工具装配（零异常 + 零工具）', async () => {
-    const ctx = createServerContext();
-    await registerAll(ctx);
-    const m = resolveMemoryStore({ store: 'off' });
-    const engine = await createEngineFromContext(
-      ctx,
-      {
-        instructions: 'test',
-        model: {} as never,
-        ...(m.enabled && m.store ? { memory: { store: m.store } } : {}),
-      },
-    );
-    await engine.chat('t-mem-off', 'hi', () => {});
-    expect(m.enabled).toBe(false);
+  it('mall 域 resolveScope 语义：attributes.mall → { mallId }；无 mall → undefined（用户级全局）', () => {
+    // resolveScope 闭包形态对齐模板装配（buildScope 单点）；此处按语义直测：
+    // 模板内 resolveScope = buildScope(attributes) 取 mallId 单键
+    const resolveScope = (attributes: Record<string, unknown>) => {
+      const raw = attributes?.mall as { mallId?: unknown } | undefined;
+      const mallId = typeof raw?.mallId === 'string' && raw.mallId ? raw.mallId : undefined;
+      return mallId ? { mallId } : undefined;
+    };
+    expect(resolveScope({ mall: { mallId: 'mall-demo', miniAppId: 'demo-app' } })).toEqual({ mallId: 'mall-demo' });
+    expect(resolveScope({})).toBeUndefined();
+    expect(resolveScope({ mall: { mallId: '' } })).toBeUndefined();
   });
 });

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tbox.cn/app-template-agent",
-  "version": "0.7.5",
-  "description": "tbox AI Agent 全栈模板（多包 pnpm workspace）：apps/client + apps/server + packages/module-*。客户端同时跑在浏览器与支付宝小程序 web-view 壳里。",
+  "version": "0.9.0",
+  "description": "tbox AI Agent 全栈模板（多包 pnpm workspace）：apps/client + apps/server。唯一模板（W4 单一模板统一化：缺省空装配 chat 形态；mall 能力经 profiles/mall 加装），能力经 tbox-app module add 模块扩展（shopping-guide/member 等）。",
   "engines": {
     "node": ">=24.0.0 <25.0.0"
   },
@@ -13,6 +13,7 @@
     "!apps/**/node_modules",
     "!apps/**/*.tsbuildinfo",
     "config",
+    "profiles",
     "packages",
     "!packages/**/node_modules",
     "!packages/**/*.tsbuildinfo",
@@ -31,7 +32,7 @@
     "LICENSE"
   ],
   "devDependencies": {
-    "@tbox.cn/app-sdk": "0.18.0",
+    "@tbox.cn/app-sdk": "0.20.0",
     "eslint": "9.39.5",
     "typescript-eslint": "8.67.0",
     "eslint-plugin-react-hooks": "5.2.0",
@@ -47,7 +48,7 @@
     "build:client": "pnpm check && pnpm --filter ./apps/client build",
     "typecheck": "pnpm -r --filter \"./{apps,packages}/*\" typecheck",
     "test": "pnpm -r --filter \"./{apps,packages}/*\" test",
-    "lint": "eslint apps packages",
+    "lint": "eslint apps $(find packages -mindepth 1 -maxdepth 1 -type d -print -quit 2>/dev/null | grep -q . && echo packages)",
     "verify": "pnpm typecheck && pnpm test && pnpm lint && pnpm build && pnpm verify:generated && pnpm check:inspector",
     "verify:generated": "node scripts/verify-generated.mjs",
     "check": "pnpm check:workspace && pnpm check:inspector",

package/packages/agent-ui-kit/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 tbox.cn
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/packages/agent-ui-kit/README.md

@@ -0,0 +1,17 @@
+# @app/agent-ui-kit
+
+Agent 对话壳 UI 组件包（源码发布）——单一模板统一化 W2-1 自 mall 模板抽取。
+
+- **真源**：本包（`packages/agent-ui-kit`）。模板出厂副本经 `scripts/sync-agent-ui-kit.mjs` 派生
+  （name 改写 `@app/agent-ui-kit` → `@app/agent-ui-kit`），guard identity 锁定一致。
+- **消费面**：应用 `<ChatPage store={useChatStore} cards={CHAT_REGISTRY} slots={clientCtx.slots}/>`
+  单点装配；域 UI（如商圈主屏）经 home 槽渲染函数自带。
+- **主题**：kit 默认 tokens（`src/theme/tokens.less`）；品牌资产包经 `html[data-theme]` 级联覆写 +
+  接线三行（`import '<pkg>/index.css'` + `import '<pkg>/brand.js'`[可选] + `applyTheme(id)`；见 docs/reference/templates.md）。
+
+## 验证
+
+```sh
+pnpm --filter @app/agent-ui-kit typecheck
+pnpm --filter @app/agent-ui-kit test
+```

package/packages/agent-ui-kit/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@app/agent-ui-kit",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Agent 对话壳 UI 组件包（源码发布，单一模板统一化 W2-1）：ChatPage/壳组件族/主题 tokens。",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts"
+    },
+    "./theme": {
+      "types": "./src/theme/theme.ts",
+      "import": "./src/theme/theme.ts"
+    },
+    "./package.json": "./package.json",
+    "./theme/global.less": "./src/theme/global.less",
+    "./theme/contract": "./src/theme/contract.json"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "files": [
+    "src",
+    "assets",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@tbox.cn/app-sdk": "catalog:",
+    "@tbox.cn/app-contracts": "catalog:",
+    "@phosphor-icons/react": "catalog:",
+    "antd-mobile": "catalog:",
+    "react-markdown": "catalog:",
+    "remark-gfm": "catalog:",
+    "zustand": "catalog:"
+  },
+  "peerDependencies": {
+    "react": "catalog:",
+    "react-dom": "catalog:"
+  },
+  "devDependencies": {
+    "@types/node": "catalog:",
+    "@types/react": "catalog:",
+    "@types/react-dom": "catalog:",
+    "happy-dom": "catalog:",
+    "less": "catalog:",
+    "react": "catalog:",
+    "react-dom": "catalog:",
+    "typescript": "catalog:",
+    "vite": "catalog:",
+    "vitest": "catalog:"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "license": "MIT"
+}

package/packages/agent-ui-kit/src/ChatPage.less

@@ -0,0 +1,62 @@
+.chat-page {
+  position: relative;
+  display: flex;
+  flex-direction: column;
+  width: 100%;
+  height: 100vh;
+  height: 100dvh;
+  min-height: 0;
+  overflow: hidden;
+  background: var(--tbox-bg-page);
+
+  &__bg {
+    position: absolute;
+    inset: 0;
+    z-index: 0;
+    background: var(--tbox-bg-page);
+    pointer-events: none;
+  }
+
+  &__body-wrapper {
+    position: relative;
+    z-index: 1;
+    display: flex;
+    flex: 1;
+    flex-direction: column;
+    min-height: 0;
+  }
+
+  &__body {
+    flex: 1;
+    width: 100%;
+    max-width: var(--tbox-content-max-width);
+    min-height: 0;
+    margin: 0 auto;
+    padding: calc(12PX + env(safe-area-inset-top, 0PX)) 0 24PX;
+    overflow-y: auto;
+    overflow-x: hidden;
+    overflow-anchor: none;
+    overscroll-behavior: contain;
+    scrollbar-width: none;
+    -webkit-overflow-scrolling: touch;
+
+    &::-webkit-scrollbar {
+      display: none;
+    }
+  }
+
+  &__orphan-card {
+    margin-right: var(--tbox-page-gutter);
+    margin-left: var(--tbox-page-gutter);
+  }
+
+  /* 顶部历史入口在场时欢迎区不再叠加自身顶部留白：胶囊到标题区留 4PX（= 欢迎区自带上边距）。 */
+  .history-entry ~ .mall-home {
+    padding-top: 0;
+  }
+
+  /* 对话开始后首页仍保留，消息接在联单主卡下方。 */
+  &--conversation &__body {
+    padding-top: calc(12PX + env(safe-area-inset-top, 0PX));
+  }
+}