@tbox.cn/app-template-agent 0.1.0 → 0.2.0

package/ENV.md

@@ -60,6 +60,8 @@
 | `ALIPAY_APP_ID` / `ALIPAY_APP_PRIVATE_KEY` | 支付宝小程序 Auth(login code 换 openId;按需)。私钥为支付宝应用私钥 RSA2 PEM |
 | `WX_APP_ID` / `WX_APP_SECRET` | weapp 换码登录(本地 provider,按需) |
 | `TTS_AUTH_URL` / `TTS_APPKEY` | TTS 鉴权必需:AUTH_URL 为鉴权网关端点(POST `{appkey}` → `timestamp+digest`);APPKEY 为 TTS 应用密钥。**缺失时 TTS 播放直接 CONFIGURATION_ERROR(无「走平台」回退)**,前端报 `[TTS] server error` |
+| `TBOX_SKILL_MODE` | 本地 Skill 模式(009):`accelerated`(默认,本地路由命中 → SOP 注入当前轮 user 消息,零额外 LLM 轮次)/ `progressive`(全量注册 InlineSkill,模型渐进 skill_read)。非法值回退默认 |
+| `TBOX_PRE_TOOL_TIMEOUT_MS` | 前置工具(010)单工具总预算 ms(decide+execute 共享):默认 `2000`;`0` = 整体禁用(预执行全关,行为与未启用逐字节一致)。非法值回退默认 |
 | `HOST` | 服务监听地址(默认 `0.0.0.0`) |
 | `PORT` | 服务监听端口(默认 `8000`) |
 

package/README.md

@@ -32,6 +32,7 @@ tbox-agent-app/
   apps/
     client/                    React/Vite 装配端（业务页面/组件/hooks/样式；平台能力经 @tbox.cn/app-sdk/client）
     server/                    Express + WS 装配端（~120 行装配：auth 中间件 + 模块挂载 + 平台路由面/TTS/WS）
+    server/skills/             本地 Skill（SKILL.md 目录格式，随模板复制/pack）
   packages/
     module-weather/            示例业务模块（双端单包）
   config/                      chat/model/plugin 配置
@@ -39,6 +40,115 @@ tbox-agent-app/
   pnpm-workspace.template.yaml 应用 workspace 模板（create 生成应用 pnpm-workspace.yaml 的来源）
 ```
 
+## 本地 Skill（009）
+
+应用与模块可为 Agent 提供受控技能（SOP + 参考资料），支持双模式（全局配置，运行期恒定）：
+
+| 模式 | 环境变量 | 行为 | 适用 |
+|---|---|---|---|
+| **accelerated（默认）** | `TBOX_SKILL_MODE=accelerated` | 本地打分路由（零 LLM）命中 → `<system-reminder skill="...">SOP+references</system-reminder>` 注入**当前轮 user 消息前部**；同 skill 会话内最多一次；system prompt 与工具列表恒定 → 前缀缓存稳定、零 skill 轮次 | 大多数业务场景 |
+| **progressive** | `TBOX_SKILL_MODE=progressive` | Agent 全量注册 InlineSkill，模型按需 skill_read 渐进读取（mastra 原生） | 需要模型自主挑选技能的复杂场景 |
+
+### 应用级 Skill（目录格式）
+
+```text
+apps/server/skills/<skill-name>/
+├── SKILL.md              # frontmatter（name/description/metadata.routingTerms）+ SOP 正文
+└── references/           # 可选，递归 *.md（随 SKILL.md 内存化加载，运行期零文件系统暴露）
+    ├── a.md
+    └── sub/b.md
+```
+
+模板已内置 `shopping-guide` 示例（含子目录 references）。新增步骤：建目录 → 写 SKILL.md（`name` 须匹配 `^[a-z0-9-]{1,64}$`）→ references 可选 → 启动加载（无需改代码）。
+
+### 模块级 Skill（文件加载，推荐示例）
+
+模块包内放 `skills/` 目录（与 `src/` 平级），顶层 await 加载后填回 `serverModule.skills` 声明式通道（装配端 `registerAll` 自动注册，register 内零代码）：
+
+```text
+packages/module-weather/
+├── skills/weather-guide/
+│   ├── SKILL.md              # frontmatter（name/description/metadata.routingTerms）+ SOP
+│   └── references/dressing-tips.md
+├── src/server/index.ts
+└── package.json              # exports 须含 "./package.json": "./package.json"
+```
+
+```ts
+// packages/module-weather/src/server/index.ts
+import { loadModuleSkills } from '@tbox.cn/app-sdk/server';
+
+const skills = Object.fromEntries(
+  (await loadModuleSkills('@app/module-weather', import.meta.url)).map((s) => [s.name, s]),
+) satisfies Record<string, LocalSkill>;
+
+export const serverModule = { cards, skills, register(ctx) { /* ... */ } } satisfies ServerModule;
+```
+
+底层能力（SDK `loadModuleSkills(packageName, import.meta.url)`）**单策略**（createRequire 包名解析）定位模块包根，**dev / build dist / 发布态路径恒等**：以调用文件为基准解析 `${packageName}/package.json`（workspace link / 模块 dist / 应用 tsup bundle dist / node_modules 全形态命中）。前置：模块 exports 须含 `"./package.json"`。加载失败降级 `[]` + 可行动 warn（提示 exports 键/安装问题，不阻断启动）。生成应用内（codegen 展开）源码调用名由 CLI 自动改写为本地装配包名（`@app/<id>`），模块源码按字面量包名写法即可。
+
+inline 声明（`serverModule.skills` 直接内联 instructions/references）仍是发布态模块的轻量选择（无文件系统依赖），两种形态可并存。
+
+### 冒烟
+
+```sh
+# 启动日志会打印装配结果：mode + skill 名列表（不含内容）
+[SKILL] mode=accelerated skills=weather-guide,shopping-guide
+# 提问触发词（accelerated）："今天天气怎么样"（weather-guide → getWeather 工具+卡片）/ "3楼有什么"（shopping-guide → SOP）
+# 切换模式：TBOX_SKILL_MODE=progressive
+```
+
+## 前置 Tool 加速执行（010）
+
+对「参数可工程化获取、不依赖模型抽参」的**只读工具**，模型请求前先执行、结果注入上下文——正式回答首字从「模型①生成 tool-call → 工具执行 → 模型②作答」缩短为「工具执行 → 模型①直接作答」，**每个预执行工具省一整轮 loop**。
+
+### 三步声明法
+
+```ts
+// 模块：serverModule.preTools（key = tool.id；装配端自动注册，register 内零代码）
+// 应用：BuildEngineOptions.preTools（apps/server/src/pre-tools.ts）
+// 统一经 definePreTool(tool, spec) 构造——tool 实例引用 = 单一真源（id/description 派生）
+import { definePreTool } from '@tbox.cn/app-sdk/server';
+definePreTool(weatherTool, {
+  routing: { mode: 'keywords', terms: ['天气', '气温'] }, // ② 结构化路由：词表打分 / { mode:'always' } 必选
+  decide: ({ text, identity }) => {                       // ③ 决策即构造：run(args) = 预执行 / skip = 不生效
+    const city = CITIES.find((c) => text.includes(c));
+    return city ? { decision: 'run', args: { city } } : { decision: 'skip' };
+  },
+});
+```
+
+铁律：仅只读/幂等工具（`requireApproval`/交互式工具不参与）；decide 不得抛（SDK 兜底 warn + skip）；args 必须 JSON 可序列化（坏形状/非法参数 → warn + skip）；身份经入参 `identity` 获取（per-run 并发安全，**不用 `ctx.auth`**）；`always` 路由每轮进入 decide（慎用，防每轮噪音）；框架层**无跨轮去重**（同参可重入，执行策略完全由 decide 工程化自控）。
+
+### 行为
+
+- **注入**：每预执行工具一个 `<system-reminder pre-tool="...">` 数据块（`<input>`/`<output>` 内嵌 JSON，user 消息前部；**无合成工具消息**——模型不会把结果误判为「已调用过该工具」，可跨轮正常再调用）；server-only（不进事件/落库/历史恢复）。
+- **前端**：thinking 气泡内实时显示「自动查询 xx」徽标（执行前即出现 spinner）→「已自动获取 xx」+ 可展开结果详情；刷新后历史消息同样可见。
+- **失败降级**：decide skip / 执行失败 / 超时 → 该工具按普通 LLM 工具路径走，不影响本轮回答；意图路由命中 → 零预执行。
+- **预算**：单工具 decide+execute 共享 `TBOX_PRE_TOOL_TIMEOUT_MS`（默认 2000ms；`0` = 整体禁用）；单轮最多 3 个工具并行预执行。
+
+### 模板演示
+
+| 示例 | 位置 | 形态 |
+|---|---|---|
+| `getWeather` | `packages/module-weather/src/server/pre-tools.ts` | 文本抽取（城市词表，抽不到 skip）——与 weather-guide skill SOP 共存，单轮完成 |
+| `getCurrentTime` | `apps/server/src/pre-tools.ts` + `tools/clock.ts` | 零参工程化（词表命中即执行） |
+| `queryPoints` | `modules/module-member`（`tbox-app module add` 后） | `always` 必选 + 身份门控（identity 取 userId，匿名 skip） |
+| `translate` | 反例（不改代码） | 参数依赖语义抽取，不适配——保持 LLM 工具路径 |
+
+### 冒烟
+
+```sh
+# 启动日志：timeout + 预执行工具清单
+[PRETOOL] timeoutMs=2000 preTools=getCurrentTime,getWeather
+# ①"杭州天气怎么样" → thinking 气泡出现「自动查询 查询城市天气信息」（label = 工具自身 description 派生）→ 直接作答（单轮 1 次模型请求，无 getWeather 二次调用）
+# ②"现在几点了"     → 「自动查询 查询当前日期和时间」→ 作答（零参形态）
+# ③"帮我翻译 hello" → 无「自动查询」徽标（反例：正常 LLM 工具路径）
+# ④ TBOX_PRE_TOOL_TIMEOUT_MS=0 复测① → 回退为模型调用工具两轮（对比基准）
+# ⑤ 刷新页面 → 历史消息仍显示「已自动获取」徽标（inputs.preTools 重建）
+# ⑥"杭州天气怎么样"后再问"那纽约呢"（词表外城市） → decide 不命中 → 模型正常调用 getWeather(city=纽约)（无合成工具消息，跨轮不再泛化「已调用过」）
+```
+
 ## 平台能力定制（007 扩展点）
 
 平台轴（安全管道/能力管道/协议客户端）已下沉 `@tbox.cn/app-sdk`，模板保留 3 个注入点 + 模板源码扩展：

package/apps/client/src/cards/CardRenderer.tsx

@@ -1,10 +1,21 @@
 /**
  * 卡片渲染入口 — 注入本地 registry 后委托 SDK 的 CardRenderer。
+ * 011 B3：动作按钮 → sendUiAction componentAction（token 来自 payload.actionTokens）。
  */
 import { CardRenderer as SdkCardRenderer } from '@tbox.cn/app-sdk/client';
 import type { TboxCardPayload } from '@tbox.cn/app-contracts';
 import { CARD_REGISTRY } from './registry';
+import { useChatStore } from '@/store/chat';
 
 export function CardRenderer({ card }: { card: TboxCardPayload }) {
-  return <SdkCardRenderer card={card} registry={CARD_REGISTRY} />;
+  const sendUiAction = useChatStore((s) => s.sendUiAction);
+  return (
+    <SdkCardRenderer
+      card={card}
+      registry={CARD_REGISTRY}
+      onAction={(actionId, contextToken) =>
+        sendUiAction(card.id, { type: 'componentAction', actionId, contextToken })
+      }
+    />
+  );
 }

package/apps/client/src/components/QuickCommands/index.tsx

@@ -1,19 +1,26 @@
 // ⚠️ 平台标准组件：输入框上方的「快捷指令」。视觉还原时不改本组件、不另画。
 // 改内容只改 client/config/chat.json 的 quickCommands 数组（{ label, query, icon? }）。
+// 011 I2：服务端 HelloAck.chatConfig.quickCommands 优先（单一真源），本地 chat.json 为 fallback。
 // label 只写纯文字；前面的星标由本组件渲染（icon 字段或默认 ✦），不要把 ✦/emoji 写进 label。
 import { useChatConfigStore } from '@/store/chat-config';
+import { useChatStore } from '@/store/chat';
 import starIcon from '../../../assets/quick-command-star.svg';
 import './index.less';
 
 export function QuickCommands({ onCommand }: { onCommand: (query: string) => void }) {
-  const commands = useChatConfigStore((s) => s.quickCommands);
+  const staticCommands = useChatConfigStore((s) => s.quickCommands);
+  const serverCommands = useChatStore((s) => s.helloAck?.chatConfig.quickCommands);
+  // 服务端下发优先；未收到 HELLO_ACK（非 mall 部署）回落本地静态
+  const commands = (serverCommands && serverCommands.length > 0
+    ? serverCommands.map((c) => ({ label: c.label, query: c.prompt }))
+    : staticCommands) as { label: string; query: string }[];
   if (!commands.length) return null;
 
   return (
     <div className="quick-commands">
       {commands.map((cmd) => (
         <button key={cmd.label} className="quick-commands__item" onClick={() => onCommand(cmd.query)}>
-          <img className="quick-commands__icon" src={cmd.icon || starIcon} alt="" />
+          <img className="quick-commands__icon" src={starIcon} alt="" />
           <span className="quick-commands__label">{cmd.label}</span>
         </button>
       ))}

package/apps/client/src/components/ToolCallBlock/index.less

@@ -43,6 +43,17 @@
     animation: tool-spin 0.8s linear infinite;
   }
 
+  // 010：前置工具「自动」徽标（与模型主动调用区分）
+  &__badge {
+    font-size: 18px;
+    line-height: 1;
+    padding: 3px 8px;
+    border-radius: 8px;
+    background: rgba(93, 126, 198, 0.12);
+    color: #5f7ec6;
+    flex-shrink: 0;
+  }
+
   &__name {
     font-size: 22px;
     line-height: 1.4;

package/apps/client/src/components/ToolCallBlock/index.tsx

@@ -1,22 +1,51 @@
 import { useState } from 'react';
 import { Check, X } from '@phosphor-icons/react';
 import type { ToolCallInfo } from '@/types/chat';
+import { describeToolCall } from '@tbox.cn/app-sdk/client';
 import './index.less';
 
-/** 工具调用状态卡片（调用中 spinner / 完成 / 失败，可展开详情）。 */
+/**
+ * 工具调用状态卡片（调用中 spinner / 完成 / 失败，可展开详情）。
+ * 010：展示语义判定下沉 SDK describeToolCall（skill/preTool/normal 三分支），
+ * 本组件退化为纯渲染（徽标/颜色/展开交互）。
+ */
 export default function ToolCallBlock({ toolCalls }: { toolCalls: ToolCallInfo[] }) {
   const [expandedId, setExpandedId] = useState<string | null>(null);
 
   return (
     <div className="tool-calls">
       {toolCalls.map((tc) => {
+        const display = describeToolCall(tc);
         const isCalling = tc.status === 'calling';
-        const isError = tc.status === 'error';
-        const isDone = tc.status === 'done';
+        const isError = tc.status === 'error' || (display.kind === 'preTool' && display.status === 'error');
+        const isDone = !isCalling && !isError;
         const isExpanded = expandedId === tc.id;
-        const hasDetail = !!(tc.result || tc.error);
+        const hasDetail = display.kind !== 'skill' && display.hasDetail;
         const stateClass = isError ? 'tool-call--error' : isCalling ? 'tool-call--calling' : 'tool-call--done';
 
+        const displayName = (() => {
+          if (display.kind === 'skill') {
+            return isCalling ? `加载技能 ${display.label}` : `已加载技能 ${display.label}`;
+          }
+          if (display.kind === 'preTool') {
+            if (display.status === 'calling') return `自动查询 ${display.label}`;
+            if (display.status === 'error') return `自动查询失败 ${display.label}`;
+            return `已自动获取 ${display.label}`;
+          }
+          return isCalling
+            ? `调用 ${display.label}`
+            : isDone
+              ? `${display.label} 已完成`
+              : `${display.label} 调用失败`;
+        })();
+
+        const detailText =
+          display.kind === 'preTool'
+            ? (display.status === 'error' ? display.errorText : display.resultText) ?? ''
+            : isError
+              ? tc.error ?? ''
+              : tc.result ?? '';
+
         return (
           <div key={tc.id} className={`tool-call ${stateClass}`}>
             <div
@@ -27,11 +56,10 @@ export default function ToolCallBlock({ toolCalls }: { toolCalls: ToolCallInfo[]
                 {isCalling && <div className="tool-call__spinner" />}
                 {isDone && <Check size={16} color="#10a37f" strokeWidth={2.5} />}
                 {isError && <X size={16} color="#ef4444" strokeWidth={2.5} />}
-                <span className="tool-call__name">
-                  {isCalling && `调用 ${tc.name}`}
-                  {isDone && `${tc.name} 已完成`}
-                  {isError && `${tc.name} 调用失败`}
-                </span>
+                <span className="tool-call__name">{displayName}</span>
+                {display.kind === 'preTool' && (
+                  <span className="tool-call__badge">自动</span>
+                )}
               </div>
               {hasDetail && (
                 <span className={`tool-call__toggle${isExpanded ? ' tool-call__toggle--up' : ''}`}>
@@ -42,7 +70,7 @@ export default function ToolCallBlock({ toolCalls }: { toolCalls: ToolCallInfo[]
             {isExpanded && hasDetail && (
               <div className="tool-call__result">
                 <span className={`tool-call__result-text${isError ? ' tool-call__result-text--error' : ''}`}>
-                  {formatResult(isError ? tc.error! : tc.result!)}
+                  {formatResult(detailText)}
                 </span>
               </div>
             )}

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

@@ -4,9 +4,12 @@
  * 共用同一份 set/get，避免双 store 断裂。
  */
 import { create } from 'zustand';
-import { createCoreChatState, getWsUrl } from '@tbox.cn/app-sdk/client';
+import { createCoreChatState, getWsUrl, configureHelloContext, configureWsScopeErrorHandler } from '@tbox.cn/app-sdk/client';
 import type { CoreChatState } from '@tbox.cn/app-sdk/client';
+import { resolveHistoryMessage, buildHistoryToolCalls } from '@tbox.cn/app-sdk/client';
 import type { CardSnapshot, TboxCardPayload } from '@tbox.cn/app-contracts';
+import type { SkillRecord } from '@tbox.cn/app-contracts';
+import type { PreToolRecord } from '@tbox.cn/app-contracts';
 import type { ChatMessage } from '@/types/chat';
 import type { IFeedbackAdapter } from '@tbox.cn/app-sdk/client';
 import type { AdapterContextValue } from '@tbox.cn/app-sdk/client';
@@ -24,6 +27,10 @@ interface HistoryMessageInfo {
   multiModalInputs?: Record<string, unknown>;
   /** P3 W1：服务端已恢复（migrate + isHistory=true）的卡片快照 */
   cards?: CardSnapshot[];
+  /** 009 D10：服务端已恢复的 skill 加载记录（inputs.skills） */
+  skills?: SkillRecord[];
+  /** 010：服务端已恢复的前置工具记录（inputs.preTools） */
+  preTools?: PreToolRecord[];
 }
 
 function convertHistoryMessages(messages: HistoryMessageInfo[]): ChatMessage[] {
@@ -31,11 +38,14 @@ function convertHistoryMessages(messages: HistoryMessageInfo[]): ChatMessage[] {
   const nextId = (prefix: string) => `${prefix}_${Date.now()}_${idSeq++}`;
   const result: ChatMessage[] = [];
   for (const info of messages) {
+    // 009 D10 + 010：skill/preTool 双表达组合（B1 结构化；skill B2 query 解析补齐）
+    // —— 010 下沉 S4：解析与组合规则在 SDK，模板只消费组合入口
+    const resolved = resolveHistoryMessage(info);
     if (info.query) {
       const userMsg: ChatMessage = {
         id: `history-user-${info.messageId}`,
         role: 'user',
-        content: info.query,
+        content: resolved.content,
         status: 'done',
         createdAt: info.createTime || Date.now(),
         ...(info.outerBusinessId && { requestId: info.outerBusinessId }),
@@ -58,6 +68,15 @@ function convertHistoryMessages(messages: HistoryMessageInfo[]): ChatMessage[] {
         status: 'done',
         createdAt: info.createTime || Date.now(),
         ...(info.outerBusinessId && { requestId: info.outerBusinessId }),
+        // 009 D10 + 010：skill/preTool 加载标记挂在 user 消息后的 assistant 消息（ToolCallBlock 渲染）
+        ...(resolved.skills.length > 0 || resolved.preTools.length > 0
+          ? {
+              toolCalls: buildHistoryToolCalls(
+                resolved,
+                info.messageId ?? nextId('history-skill'),
+              ),
+            }
+          : {}),
       });
     }
   }
@@ -84,8 +103,7 @@ export const useChatStore = create<ChatState>((set, get) => ({
     { getWsUrl: () => getWsUrl(), toast },
     set as (partial: any) => void,
     get as () => any,
-  ),
-  // 业务扩展状态
+  ),  // 业务扩展状态
   historyMessages: [],
   historyHasMore: true,
   isLoadingHistory: false,
@@ -199,3 +217,16 @@ export const useChatStore = create<ChatState>((set, get) => ({
     }
   },
 }));
+
+// 011 L4：HELLO context 采集——mallId 经 URL query 采集（mall 部署；无 mallId 时不携带 context）
+configureHelloContext(() => {
+  const mallId = new URLSearchParams(window.location.search).get('mallId');
+  const miniAppId = new URLSearchParams(window.location.search).get('miniAppId');
+  if (!mallId) return undefined;
+  return { mall: { mallId, ...(miniAppId ? { miniAppId } : {}) } };
+});
+
+// 011 评审 7.2：4002 scope 拒绝 → 停止重连 + 轻提示（L4「切 mall = 新会话 + 轻提示」UI 端接线）
+configureWsScopeErrorHandler((message) => {
+  toast(message);
+});

package/apps/server/package.json

@@ -16,6 +16,7 @@
     "@tbox.cn/agent-plugin": "catalog:",
     "@tbox.cn/app-sdk": "catalog:",
     "@tbox.cn/app-contracts": "catalog:",
+    "@tbox.cn/app-contracts-mall": "catalog:",
     "@tbox-dev-js/sdk": "catalog:",
     "ai": "catalog:",
     "cors": "catalog:",

package/apps/server/skills/shopping-guide-demo/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: shopping-guide-demo
+description: 商圈导购：找店、找商品、楼层导航、优惠活动、停车指引
+metadata:
+  routingTerms: [找店, 导购, 楼层, 导航, 优惠, 活动, 停车, 商场, 逛]
+---
+# 商圈导购 SOP
+
+## 适用意图
+用户询问商场内找店、找商品、楼层分布、优惠活动、停车导航等（如"哪里有运动品牌"、"3 楼有什么吃的"、"最近有什么活动"、"车停哪里"）时，遵循本规范回答。非商场相关提问不要套用本规范。
+
+## 回答组织方式
+1. 先判断用户意图归属（找店 / 优惠活动 / 停车导航），命中后从对应 reference 查找资料；
+2. 回答按"结论先行"组织：先给出店铺/楼层/活动/车位位置，再补充营业时间、规则等细节；
+3. 信息缺失时如实说明"资料未收录"，不要编造楼层或活动信息；
+4. 涉及楼层请使用「1F/2F/B1/B2」格式，停车场使用「B1/B2」格式。
+
+## 全局约束
+- 只回答与商场导购相关的内容；用户问及其他领域时正常转回通用助手；
+- 禁止编造未收录的店铺、活动或停车信息；
+- 回答保持简洁，一次回答聚焦一个问题（复合问题先回答优先级最高的意图）。

package/apps/server/skills/shopping-guide-demo/references/guide/parking.md

@@ -0,0 +1,11 @@
+# 停车导航 SOP
+
+## 停车场信息
+- 停车场：B2 层（含机械车位），B1 层为临时卸货区（不对外停车）；
+- 入口：商场东侧入口（导航定位「东门停车场入口」）；
+- 收费标准：首 2 小时免费，之后每小时 5 元，当日封顶 40 元。
+
+## 停车指引
+1. 用户问「停车/车位/车停哪」→ 告知 B2 停车场与东侧入口；
+2. 问「停车优惠」→ 参考优惠活动中的「观影送停车券」；
+3. 问「充电桩」→ 告知 B2 东区设有新能源充电桩（数量有限，先到先得）。

package/apps/server/skills/shopping-guide-demo/references/mall-directory.md

@@ -0,0 +1,17 @@
+# 楼层与店铺分布
+
+## 楼层总览
+| 楼层 | 业态 | 代表店铺 |
+|---|---|---|
+| B2 | 停车场 | — |
+| B1 | 餐饮 + 超市 | 烘焙工坊、精品超市、美食广场 |
+| 1F | 美妆 + 珠宝 | 美妆集合店、金饰专柜 |
+| 2F | 服饰 | 运动品牌集合店、女装、男装 |
+| 3F | 亲子 + 家居 | 儿童乐园、母婴、家居生活馆 |
+| 4F | 影院 + 餐饮 | 电影院、火锅、日料 |
+
+## 找店指引
+- 问「运动品牌/鞋子」→ 2F 运动品牌集合店；
+- 问「美妆/护肤」→ 1F 美妆集合店；
+- 问「吃饭/餐厅」→ B1 美食广场（快餐）与 4F（正餐）；
+- 问「超市」→ B1 精品超市。

package/apps/server/skills/shopping-guide-demo/references/promotion.md

@@ -0,0 +1,10 @@
+# 优惠活动
+
+## 当前活动（模板示例数据）
+- 周末会员日：全场服饰 8 折（2F），每周末；
+- 餐饮满 100 减 20：B1 与 4F 指定商户，需会员积分抵扣；
+- 观影送停车券：凭 4F 影院当日电影票根，可兑换 B2 停车 2 小时免费。
+
+## 活动规则
+- 活动以商户现场公示为准，本资料为示例数据；
+- 用户问「有什么活动/优惠」→ 按上述条目逐一列出，并给出楼层位置。

package/apps/server/src/app-tools.ts

@@ -0,0 +1,13 @@
+import type { ServerContext } from '@tbox.cn/app-sdk/server';
+import { translateTool } from './tools/translate.js';
+import { clockTool } from './tools/clock.js';
+
+/**
+ * apps 级演示工具统一注册面（010：双注册面同步）：
+ * start()（运行时）与 cli/collect-registry.ts（doctor/inspect 视图）两处同调本函数，
+ * 未来新增 apps 级工具只改此处，避免两处注册面失同步（R 评审修正）。
+ */
+export function registerAppTools(ctx: ServerContext): void {
+  ctx.tools.register(translateTool);
+  ctx.tools.register(clockTool);
+}

package/apps/server/src/cli/collect-registry.ts

@@ -1,6 +1,6 @@
 import { createServerContext, buildToolCardBindings } from '@tbox.cn/app-sdk/server';
 import { registerAll } from '../modules.js';
-import { translateTool } from '../tools/translate.js';
+import { registerAppTools } from '../app-tools.js';
 
 export interface RegistryState {
   staticToolIds: string[];
@@ -11,12 +11,13 @@ export interface RegistryState {
 /**
  * 从自注册闭环收集当前注册状态（静态工具 id / cardType / tool→card 绑定）。
  * 供 plugin-doctor / plugin-inspect 复用——替代已删除的手写 tools/registry.ts + cards/registry.ts。
- * 与运行时（apps/server/src/index.ts start()）保持一致的注册面：registerAll + 模板演示工具 translate。
+ * 与运行时（apps/server/src/index.ts start()）保持一致的注册面：registerAll + registerAppTools
+ * （010：apps 级演示工具统一注册面，双处同调防失同步）。
  */
 export async function collectRegistryState(): Promise<RegistryState> {
   const ctx = createServerContext();
   await registerAll(ctx);
-  ctx.tools.register(translateTool); // 与运行时一致（index.ts 中 translate 为 apps 级演示工具）
+  registerAppTools(ctx); // 与运行时一致（translate + clock 为 apps 级演示工具）
   const cards = ctx.cards.getAll();
   return {
     staticToolIds: Object.keys(ctx.tools.getAll()),

package/apps/server/src/config/deployment.ts

@@ -0,0 +1,81 @@
+/**
+ * 部署控制平面 loader（011 L2：模板装配点专用）。
+ * - DEPLOYMENT_CONTROL_PLANE_PATH 存在 → 读取 + zod 校验 + 无内联密钥断言；
+ * - 未配置 → 返回 undefined（模板退化为通用助手形态，非 mall 部署）。
+ * - mall 语义集中在 contracts-mall（TIER1）；apps 只做装配组合（011 L6 checklist）。
+ */
+import { readFileSync } from 'node:fs';
+import { z } from 'zod';
+import {
+  createMallRuntimeAssembly,
+  type MallDeploymentControlPlane,
+  type MallRuntimeAssembly,
+} from '@tbox.cn/app-contracts-mall';
+
+const providerInstanceSchema = z.object({
+  providerInstanceId: z.string().min(1),
+  providerTemplateId: z.string().min(1),
+  scope: z.record(z.string(), z.string()).optional(),
+  config: z.record(z.string(), z.unknown()).optional(),
+  credentialRef: z.string().optional(),
+  credentialVersion: z.string().optional(),
+  enabled: z.boolean(),
+});
+
+const controlPlaneSchema = z.object({
+  deployment: z.object({
+    miniAppId: z.string().min(1),
+    agentId: z.string().min(1),
+    components: z.array(
+      z.object({
+        componentId: z.string().min(1),
+        enabledFeatures: z.array(z.string()).optional(),
+        optional: z.boolean().optional(),
+      }),
+    ),
+  }),
+  malls: z.array(z.object({ mallId: z.string().min(1), name: z.string().min(1) })),
+  providerTemplates: z
+    .array(
+      z.object({
+        providerTemplateId: z.string().min(1),
+        credentialType: z.string().min(1),
+      }),
+    )
+    .optional(),
+  providerInstances: z.array(providerInstanceSchema),
+});
+
+/** 无内联密钥断言（011 L2）：命中敏感键名即拒（部署配置只放引用不放机密） */
+const SECRET_KEY_PATTERN = /api[-_]?key|private[-_]?key|secret|password|token|credential/i;
+
+function assertNoInlineSecrets(config: unknown, path = '$'): void {
+  if (Array.isArray(config)) {
+    config.forEach((item, i) => assertNoInlineSecrets(item, `${path}[${i}]`));
+    return;
+  }
+  if (config && typeof config === 'object') {
+    for (const [k, v] of Object.entries(config as Record<string, unknown>)) {
+      if (SECRET_KEY_PATTERN.test(k)) {
+        throw new Error(`部署配置含疑似内联密钥字段：${path}.${k}（机密只允许经 credentialRef 引用环境变量）`);
+      }
+      assertNoInlineSecrets(v, `${path}.${k}`);
+    }
+  }
+}
+
+export interface LoadedDeployment {
+  controlPlane: MallDeploymentControlPlane;
+  assembly: MallRuntimeAssembly;
+}
+
+/** 读取并校验部署控制平面（路径未配置 → undefined = 非 mall 部署） */
+export function loadDeploymentControlPlane(envPath?: string): LoadedDeployment | undefined {
+  const p = envPath ?? process.env.DEPLOYMENT_CONTROL_PLANE_PATH;
+  if (!p) return undefined;
+  const raw = JSON.parse(readFileSync(p, 'utf8'));
+  assertNoInlineSecrets(raw);
+  const parsed = controlPlaneSchema.parse(raw);
+  const controlPlane = parsed as MallDeploymentControlPlane;
+  return { controlPlane, assembly: createMallRuntimeAssembly(controlPlane) };
+}

package/apps/server/src/config/feature-gate.ts

@@ -0,0 +1,17 @@
+/**
+ * feature 门控纯函数（011 D10 / 评审 M2 修复）：
+ * 组件未声明 enabledFeatures = 全启用（MallDeploymentComponent 语义，contracts-mall deployment.ts）；
+ * 声明了 → 白名单包含才放行。提取为纯函数供单测与装配共用。
+ */
+export interface FeatureGateComponent {
+  componentId: string;
+  enabledFeatures?: string[];
+}
+
+/** 构造门控判定（components 任一命中即 true） */
+export function createFeatureGate(components: readonly FeatureGateComponent[]) {
+  return (featureId: string): boolean =>
+    components.some(
+      (c) => !c.enabledFeatures || c.enabledFeatures.includes(featureId),
+    );
+}

package/apps/server/src/index.ts

@@ -17,10 +17,30 @@ import {
   createModelProvider,
   createPluginIntegration,
   ConversationService,
+  loadLocalSkills,
+  resolveSkillMode,
+  resolvePreToolTimeout,
+  buildMessageInputs,
 } from '@tbox.cn/app-sdk/server';
 import { installInspector, injectScript, isReady } from '@tbox.cn/app-sdk/platform';
-import { translateTool } from './tools/translate.js';
+import { registerAppTools } from './app-tools.js';
+import { APP_PRE_TOOLS } from './pre-tools.js';
 import { INTENT_ROUTES, createAppIntentDispatcher } from './intent-routes.js';
+import { loadDeploymentControlPlane } from './config/deployment.js';
+import { createFeatureGate } from './config/feature-gate.js';
+// 011 S2/S3：mall 装配原语（条件装配——未配置部署文件时零引用）
+import {
+  createScopeSessionRegistry,
+  createActionGrantService,
+  createComponentActionDispatcher,
+  createEffectRuntime,
+  createProviderRegistry,
+  createAuthenticatedTransportFactory,
+  createAuthStrategyRegistry,
+  createEnvironmentSecretProvider,
+  createInMemoryStateStore,
+  attachCardActionTokens,
+} from '@tbox.cn/app-sdk/server';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const PORT = Number(process.env.PORT) || 8000;
@@ -77,7 +97,44 @@ if (auth.config.devLoginEnabled) {
 
 // 自注册闭环：模块路由挂载到 /api/m/<moduleId>/（在 apiRouter 之前，避免被 /api 兜底 404 截获）
 // ctx 为模块级单例：registerAll 在 start() 内执行，ApiRouteRegistry 共享 root 保证延迟注册即时生效
-const ctx = createServerContext();
+// 011 L1：条件 mall 装配——DEPLOYMENT_CONTROL_PLANE_PATH 存在时注入 runtime/providers/state
+const deployment = loadDeploymentControlPlane();
+// 011 B2：可变认证策略注册表——模块 register 期注册（joycity 签名策略），transportFactory 同引用
+const authStrategies = createAuthStrategyRegistry();
+
+const ctx = createServerContext({
+  ...(deployment
+    ? {
+        state: createInMemoryStateStore(),
+        runtime: {
+          // 011 D10/S5/评审 M2：门控 = 执行期护栏——组件未声明 enabledFeatures = 全启用
+          // （与 MallDeploymentComponent 语义一致；声明了 → 白名单包含才放行）
+          isFeatureEnabled: createFeatureGate(deployment.controlPlane.deployment.components),
+          config: deployment.controlPlane as unknown as Record<string, unknown>,
+        },
+        providers: createProviderRegistry({
+          instances: deployment.controlPlane.providerInstances,
+          // 011 评审 7.1：credentialType 真源参数化——providerTemplates 声明优先，
+          // 缺省回退从实例派生 + joycity-c-signed-v1（向后兼容既有部署配置）
+          templates:
+            deployment.controlPlane.providerTemplates ??
+            deployment.controlPlane.providerInstances.map((i: { providerTemplateId: string }) => ({
+              providerTemplateId: i.providerTemplateId,
+              credentialType: 'joycity-c-signed-v1',
+            })),
+          transportFactory: createAuthenticatedTransportFactory({
+            strategies: authStrategies,
+            secretProvider: createEnvironmentSecretProvider({
+              source: process.env as Record<string, string | undefined>,
+              allowedHeaderNames: ['content-type', 'sign', 'timestamp', 'publickey', 'x-api-key'],
+              production: isProduction,
+            }),
+          }),
+        }),
+      }
+    : {}),
+  authStrategies,
+});
 
 // 全局 /api 鉴权（H2 挂载顺序契约）：除 public（login/dev-login/health）外一律要求 Bearer token；
 // optional 模式缺失 token → 匿名身份（写通道仍被 action gateway 拒绝）
@@ -94,13 +151,30 @@ app.use('/api/action', ctx.actions.middleware());
 app.use('/api', createPlatformApiRouter({ ctx, auth }));
 
 // 从 ServerContext 构造 ChatEngine（自注册闭环组装端）
-async function createEngine() {
-  return createEngineFromContext(ctx, {
+async function createEngine(
+  extra?: { cardActionAttacher: (payload: import('@tbox.cn/app-contracts').TboxCardPayload, sessionId: string) => Promise<import('@tbox.cn/app-contracts').TboxCardPayload> },
+) {
+  // 009：应用级本地 skills（SKILL.md 目录格式，dev/dist 路径恒等 = src/dist 平级 + __dirname 绝对解析）
+  const appSkills = await loadLocalSkills(path.resolve(__dirname, '../skills'));
+  const skillMode = resolveSkillMode(process.env.TBOX_SKILL_MODE);
+  // 010：单次解析（引擎选项与启动日志同源，非法值只 warn 一次）
+  const preToolTimeoutMs = resolvePreToolTimeout(process.env.TBOX_PRE_TOOL_TIMEOUT_MS);
+
+  const engine = await createEngineFromContext(ctx, {
     instructions: AGENT_CONFIG.instructions,
     model: getModel(AI_MODEL_NAME),
     traceExporter: tboxTraceExporter,
     modelName: AI_MODEL_NAME,
     fileUrlPrefix: TBOX_FILE_URL_PREFIX,
+    // 009：双模式全局配置（accelerated 默认：本地路由命中 → reminder 注入当前轮，零额外 LLM 轮次；
+    // progressive：全量注册 InlineSkill，模型渐进 skill_read）
+    skillMode,
+    skills: appSkills,
+    // 010：前置工具加速（应用级声明 + 单工具预算；TBOX_PRE_TOOL_TIMEOUT_MS=0 整体禁用）
+    preTools: APP_PRE_TOOLS,
+    preToolTimeoutMs,
+    // 011 B3：卡片动作 token 签发器（mall 装配时注入）
+    cardActionAttacher: extra?.cardActionAttacher,
     // B21：意图路由接线（业务意图表 + handlerDispatch）
     intentRoutes: INTENT_ROUTES,
     handlerDispatch: createAppIntentDispatcher(ctx),
@@ -110,11 +184,17 @@ async function createEngine() {
       });
       return { tools: loaded.tools, references: loaded.references };
     },
-    saveMessage: async ({ conversationId, query, answer, mediaItems, outerBusinessId, cards }) => {
+    saveMessage: async ({ conversationId, query, answer, mediaItems, outerBusinessId, cards, skills, preTools }) => {
       const agentId = process.env.TBOX_APP_ID;
       const service = getConversationService();
       if (!service || !agentId) return undefined;
       const imageUrls = extractImageUrls(mediaItems, TBOX_FILE_URL_PREFIX);
+      // P3 W1：卡片快照随消息持久化（MessageEmbedded，004 D1）。
+      // 009 D10：skill 加载记录随消息持久化（inputs.skills，前端历史表达重建）。
+      // 010：前置工具记录随消息持久化（inputs.preTools，前端历史表达重建）。
+      // inputs「非空才加」组装规则已下沉 SDK buildMessageInputs（010 S3）。
+      // 若平台拒绝 inputs（V1 验证失败），此处切换为 extraParams 字符串或 FileCardPersistenceBackend 落盘。
+      const inputs = buildMessageInputs({ cards, skills, preTools });
       return await service.saveMessage({
         conversationId,
         agentId,
@@ -124,12 +204,20 @@ async function createEngine() {
         ...(imageUrls.length > 0 && {
           multiModalInputs: { imageUrls },
         }),
-        // P3 W1：卡片快照随消息持久化（MessageEmbedded，004 D1）。
-        // 若平台拒绝 inputs（V1 验证失败），此处切换为 extraParams 字符串或 FileCardPersistenceBackend 落盘。
-        ...(cards && cards.length > 0 && { inputs: { cards } }),
+        ...(inputs && { inputs }),
       });
     },
   });
+
+  // 009：启动日志诊断（仅名称/描述/路由词，不含 SOP 内容）
+  console.log(
+    `[SKILL] mode=${skillMode} skills=${engine.listSkills().map((s) => s.name).join(',') || '(none)'}`,
+  );
+  // 010：前置工具诊断（仅 toolId/描述/路由形态，不含 decide 逻辑）
+  console.log(
+    `[PRETOOL] timeoutMs=${preToolTimeoutMs} preTools=${engine.listPreTools().map((d) => d.toolId).join(',') || '(none)'}`,
+  );
+  return engine;
 }
 
 if (isProduction) {
@@ -178,15 +266,85 @@ if (isProduction) {
 const httpServer = createServer(app);
 
 async function start() {
+  // 011 S6：mall 装配 + 生产环境缺动作授权密钥 → 启动期提示（签发路径运行时兜底报错）
+  if (deployment && isProduction && !process.env.ACTION_TOKEN_SECRET && !process.env.AUTH_TOKEN_SECRET) {
+    console.warn('[ACTION] 生产环境未配置 ACTION_TOKEN_SECRET/AUTH_TOKEN_SECRET——卡片写动作 token 签发将失败');
+  }
+
   // 注册业务模块（自注册闭环）
   await registerAll(ctx);
 
-  // 模板演示工具（apps 级工具，P3 建议迁入模块）：不参与模块体系，直接注册
-  ctx.tools.register(translateTool);
+  // 模板演示工具（apps 级工具，P3 建议迁入模块）：不参与模块体系，经统一注册面注册
+  // （010：start() 与 cli/collect-registry.ts 双处同调，防注册面失同步）
+  registerAppTools(ctx);
+
+  // 011 F2/E2：mall 装配（条件）——scope 会话 + 动作授权先行（engine attacher 依赖）
+  const scopeSessions: ReturnType<typeof createScopeSessionRegistry> | undefined = deployment
+    ? createScopeSessionRegistry({
+        extractScopeKey: deployment.assembly.extractScopeKey,
+        validateScope: deployment.assembly.validateScope,
+        buildScope: deployment.assembly.buildScope,
+      })
+    : undefined;
+  const grants = scopeSessions ? createActionGrantService({ store: ctx.state }) : undefined;
 
-  const engine = await createEngine();
+  // 011 B3：卡片动作 token 签发（build → attach → send；sessionId 引擎登记、scope 经 sessions 查）
+  const cardActionAttacher = grants && scopeSessions
+    ? async (
+        payload: import('@tbox.cn/app-contracts').TboxCardPayload,
+        sessionId: string,
+      ): Promise<import('@tbox.cn/app-contracts').TboxCardPayload> => {
+        const session = scopeSessions.get(sessionId);
+        if (!session) return payload;
+        return attachCardActionTokens({
+          payload,
+          actions: ctx.cardActions,
+          grants: grants,
+          sessionId: session.sessionId,
+          scope: session.scopeFlat,
+        });
+      }
+    : undefined;
+  const engine = await createEngine(cardActionAttacher ? { cardActionAttacher } : undefined);
 
-  const chatWss = createWsServer(engine, { auth: auth.wsAuth });
+  // 011 F2/E2：组件动作分发（依赖 scopeSessions/grants）
+  let componentActions: ReturnType<typeof createComponentActionDispatcher> | undefined;
+  if (deployment && scopeSessions && grants) {
+    componentActions = createComponentActionDispatcher({
+      grants,
+      sessions: scopeSessions,
+      state: ctx.state,
+      actions: ctx.cardActions,
+      cardRegistry: ctx.cards.getAll(),
+      // 011 E5/J7：alipay 授权宿主处理器——二期占位（authCode 回传通道未实现）
+      effects: createEffectRuntime({
+        handleAlipayAuthorization: async () => {
+          console.warn('[ALIPAY] 授权回调通道二期（authCode 回传 + resultActionId 补签未实现），授权效果未执行');
+        },
+      }),
+      extractScopeKey: deployment.assembly.extractScopeKey,
+    });
+    for (const action of ctx.cardActions.getAll().values()) {
+      componentActions.register(action);
+    }
+  }
+
+  const chatWss = createWsServer(engine, {
+    auth: auth.wsAuth,
+    ...(scopeSessions
+      ? {
+          scopeSessions,
+          ...(componentActions ? { componentActions } : {}),
+          chatConfig: {
+            quickCommands: [
+              { label: '找美食', prompt: '帮我找商场里的美食' },
+              { label: '会员积分', prompt: '我的会员积分是多少' },
+            ],
+            enableImageUpload: true,
+          },
+        }
+      : {}),
+  });
   const ttsWss = createTtsProxy();
 
   httpServer.on('error', (err: NodeJS.ErrnoException) => {

package/apps/server/src/modules.ts

@@ -8,6 +8,8 @@
 import type { ServerContext, InferModuleCards } from '@tbox.cn/app-sdk/server';
 
 // @tbox:imports-begin
+// SDK 装配框架（非模块行，CLI 增量维护保留非标行）
+import { registerServerModules } from '@tbox.cn/app-sdk/server';
 import { serverModule as moduleWeather } from '@app/module-weather/server';
 // @tbox:imports-end
 
@@ -20,11 +22,13 @@ const modules = [
 // 自由区：可做装配级定制——条件注册、顺序调整、包裹中间件
 // const dynamicModule = process.env.ENABLE_X ? xModule : null;
 
-/** 注册所有已安装模块（服务端装配——勿与 apps/client/src/modules.ts 混淆） */
-export function registerAll(ctx: ServerContext): void {
-  for (const m of modules) {
-    m.register(ctx);
-  }
+/**
+ * 注册所有已安装模块（服务端装配——勿与 apps/client/src/modules.ts 混淆）。
+ * 010 下沉：声明式字段自动注册（skills/preTools）与 async register 等待由
+ * SDK registerServerModules 承载——未来新增声明式字段只改 SDK，本文件零改动。
+ */
+export function registerAll(ctx: ServerContext): Promise<void> {
+  return registerServerModules(ctx, modules);
 }
 
 // 类型从运行时装配数组自动推导：增删模块后 CardType 自动收缩/扩展（002 §6.7）

package/apps/server/src/pre-tools.ts

@@ -0,0 +1,25 @@
+// 铁律：不直接 import @mastra/core，经 @tbox.cn/app-sdk/server 的 definePreTool 入口（单例铁律）
+import { definePreTool } from '@tbox.cn/app-sdk/server';
+import { clockTool } from './tools/clock.js';
+
+/**
+ * 应用级前置工具声明（010）：BuildEngineOptions.preTools 通道。
+ *
+ * 声明形态（详见 README「前置 Tool 加速执行」节）：
+ *   ① tool —— 工具实例引用（单一真源，id/description 派生）
+ *   ② routing —— 结构化路由：{ mode: 'keywords', terms } 宽召回词表（与 skill 同源打分）
+ *                 或 { mode: 'always' } 必选候选（decide 门控；慎用防每轮噪音）
+ *   ③ decide —— 决策即构造：{ decision: 'run', args } = 预执行 / { decision: 'skip' } = 不生效
+ *
+ * 演示形态：零参工程化——词表命中即生效（decide 恒 run 空参）。
+ * 词表刻意排除「今天/时间」等泛词，防止与天气类 preTool 叠加误触发（词表精度示范）。
+ */
+export const APP_PRE_TOOLS = [
+  definePreTool(clockTool, {
+    routing: {
+      mode: 'keywords',
+      terms: ['几点', '几点了', '现在时间', '日期', '星期几'],
+    },
+    decide: () => ({ decision: 'run', args: {} }),
+  }),
+];

package/apps/server/src/tools/clock.ts

@@ -0,0 +1,24 @@
+// 铁律：不直接 import @mastra/core，经 @tbox.cn/app-sdk/server 的 createTool 入口（单例铁律）
+import { createTool } from '@tbox.cn/app-sdk/server';
+import { z } from 'zod';
+
+/**
+ * 当前时间工具 — 前置工具（pre-tool）演示：零参工具，参数无需模型抽取，
+ * 词表命中即可工程化预执行（见 apps/server/src/pre-tools.ts）。
+ */
+export const clockTool = createTool({
+  id: 'getCurrentTime',
+  description: '查询当前日期和时间',
+  inputSchema: z.object({}),
+  outputSchema: z.object({
+    iso: z.string(),
+    zh: z.string(),
+  }),
+  execute: async () => {
+    const now = new Date();
+    return {
+      iso: now.toISOString(),
+      zh: now.toLocaleString('zh-CN', { timeZone: 'Asia/Shanghai' }),
+    };
+  },
+});

package/apps/server/src/tools/translate.ts

@@ -12,10 +12,11 @@ export const translateTool = createTool({
     '中英文互译工具。当用户需要翻译文本时调用此工具。自动检测源语言并翻译为目标语言：中文→英文，英文→中文。',
   inputSchema: z.object({
     text: z.string().describe('要翻译的文本'),
+    // D11 参数规范：仅 string 形态（LLM 生成字符串最可靠）；非法值工具内回落自动检测
     targetLang: z
-      .enum(['zh', 'en'])
+      .string()
       .optional()
-      .describe('目标语言，不传则自动检测：中文输入翻译为英文，英文输入翻译为中文'),
+      .describe('目标语言（zh 或 en），不传则自动检测：中文输入翻译为英文，英文输入翻译为中文'),
   }),
   outputSchema: z.object({
     original: z.string(),
@@ -24,9 +25,14 @@ export const translateTool = createTool({
     targetLang: z.string(),
   }),
   execute: async ({ text, targetLang }) => {
-    // 简单语言检测：包含中文字符则认为是中文
+    // 简单语言检测：包含中文字符则认为是中文；非法 targetLang 回落自动检测
     const isChinese = /[\u4e00-\u9fff]/.test(text);
-    const detectedTarget = targetLang || (isChinese ? 'en' : 'zh');
+    const detectedTarget =
+      targetLang === 'zh' || targetLang === 'en'
+        ? targetLang
+        : isChinese
+          ? 'en'
+          : 'zh';
     const sourceLang = isChinese ? 'zh' : 'en';
 
     // 注意：这里返回指令让 LLM 来做实际翻译

package/apps/server/tests/feature-gate.test.ts

@@ -0,0 +1,30 @@
+import { describe, expect, it } from 'vitest';
+import { createFeatureGate } from '../src/config/feature-gate.js';
+
+describe('createFeatureGate（011 评审 M2：未声明 enabledFeatures = 全启用）', () => {
+  it('组件未声明 enabledFeatures → 任意 feature 放行', () => {
+    const gate = createFeatureGate([{ componentId: 'shopping-guide' }]);
+    expect(gate('merchant-discovery')).toBe(true);
+    expect(gate('anything')).toBe(true);
+  });
+
+  it('声明白名单 → 包含才放行', () => {
+    const gate = createFeatureGate([
+      { componentId: 'shopping-guide', enabledFeatures: ['merchant-discovery', 'product-search'] },
+    ]);
+    expect(gate('merchant-discovery')).toBe(true);
+    expect(gate('product-search')).toBe(true);
+    expect(gate('navigation')).toBe(false);
+  });
+
+  it('多组件任一命中即放行；空数组 → 全禁用', () => {
+    const gate = createFeatureGate([
+      { componentId: 'member', enabledFeatures: ['member-points'] },
+      { componentId: 'shopping-guide' },
+    ]);
+    expect(gate('member-points')).toBe(true);
+    expect(gate('navigation')).toBe(true);
+    const none = createFeatureGate([]);
+    expect(none('x')).toBe(false);
+  });
+});

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

@@ -1,6 +1,7 @@
 import { describe, expect, it } from 'vitest';
 import { createServerContext, createSdkToolRuntime } from '@tbox.cn/app-sdk/server';
 import { registerAll } from '../src/modules.js';
+import { translateTool } from '../src/tools/translate.js';
 
 describe('tool runtime 宿主装配（自注册闭环）', () => {
   it('合并模块工具并用同一次加载结果创建卡片 resolver', async () => {
@@ -46,4 +47,31 @@ describe('tool runtime 宿主装配（自注册闭环）', () => {
       status: 'unbound',
     });
   });
+
+  describe('translate 参数规范（D11：string 形态 + 工具内 normalize）', () => {
+    // mastra Tool.execute 为可选 + 双参签名（input, context）——测试经非空断言直调
+    const callExecute = (input: { text: string; targetLang?: string }) =>
+      translateTool.execute!(input, {} as never);
+
+    it('合法 targetLang（zh/en）→ 生效', async () => {
+      const r = await callExecute({ text: '你好', targetLang: 'en' });
+      expect(r).toMatchObject({ targetLang: 'en' });
+      const r2 = await callExecute({ text: 'hello', targetLang: 'zh' });
+      expect(r2).toMatchObject({ targetLang: 'zh' });
+    });
+
+    it('非法 targetLang → 回落自动检测（不抛）', async () => {
+      const r = await callExecute({ text: '你好', targetLang: 'fr' });
+      expect(r).toMatchObject({ targetLang: 'en' }); // 中文输入 → 自动检测回落英文
+      const r2 = await callExecute({ text: 'hello', targetLang: 'xx' });
+      expect(r2).toMatchObject({ targetLang: 'zh' }); // 英文输入 → 自动检测回落中文
+    });
+
+    it('缺省 targetLang → 自动检测', async () => {
+      const r = await callExecute({ text: '你好' });
+      expect(r).toMatchObject({ targetLang: 'en' });
+      const r2 = await callExecute({ text: 'hello' });
+      expect(r2).toMatchObject({ targetLang: 'zh' });
+    });
+  });
 });

package/config/deployments/development.json

@@ -0,0 +1,27 @@
+{
+  "deployment": {
+    "miniAppId": "wx-demo-mall-app",
+    "agentId": "mall-guide-agent",
+    "components": [
+      { "componentId": "shopping-guide", "optional": true, "enabledFeatures": ["merchant-discovery", "product-search", "recommendation", "mall-directory", "customer-service", "navigation"] },
+      { "componentId": "member", "optional": true, "enabledFeatures": ["member-profile", "member-card", "member-benefits", "member-points", "member-coupons", "member-enrollment"] }
+    ]
+  },
+  "malls": [
+    { "mallId": "mall-demo", "name": "示例大悦城" }
+  ],
+  "providerTemplates": [
+    { "providerTemplateId": "joycity-commercial@1", "credentialType": "joycity-c-signed-v1" }
+  ],
+  "providerInstances": [
+    {
+      "providerInstanceId": "joycity-demo",
+      "providerTemplateId": "joycity-commercial@1",
+      "scope": { "mallId": "mall-demo" },
+      "config": { "baseUrl": "https://openapi-crm-t.joycity.mobi" },
+      "credentialRef": "secret://JOYCITY_CREDENTIALS",
+      "credentialVersion": "v1",
+      "enabled": true
+    }
+  ]
+}

package/config/llm_provider.json

@@ -1,3 +1,3 @@
 {
-  "modelName": "glm-5.1"
+  "modelName": "deepseek-v4-flash"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tbox.cn/app-template-agent",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "tbox AI Agent 全栈模板（多包 pnpm workspace）：apps/client + apps/server + packages/module-*。客户端同时跑在浏览器与支付宝小程序 web-view 壳里。",
   "engines": {
     "node": ">=24.0.0 <25.0.0"

package/packages/module-weather/package.json

@@ -15,7 +15,8 @@
     "./client": {
       "types": "./src/client/index.ts",
       "import": "./src/client/index.ts"
-    }
+    },
+    "./package.json": "./package.json"
   },
   "scripts": {
     "typecheck": "tsc --noEmit"

package/packages/module-weather/skills/weather-guide/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: weather-guide
+description: 天气查询与穿衣出行建议（调用 getWeather 真实数据）
+metadata:
+  routingTerms: [天气, 穿衣, 温度, 湿度, 出行]
+---
+## 适用意图
+用户询问天气、穿衣建议、出行准备（如"今天穿什么"）时使用本规范。
+
+## 调用工具
+必须调用 getWeather 工具查询真实天气（city 取用户提到的城市），禁止编造温度/天气数据。
+
+## 返回字段说明
+getWeather 返回：temp(温度℃)、weather(天气现象)、humidity(湿度%)。
+
+## 回答组织方式
+1. 先报城市与天气现象、温度、湿度
+2. 再给出穿衣/出行建议（结合温度与天气现象）
+3. 温度 <10℃ 提醒保暖，>30℃ 提醒防晒

package/packages/module-weather/skills/weather-guide/references/dressing-tips.md

@@ -0,0 +1,5 @@
+## 穿衣指数
+- 温度 <10℃：厚外套/羽绒服
+- 10~20℃：夹克/风衣
+- 20~30℃：单衣/薄外套
+- >30℃：短袖，注意防晒

package/packages/module-weather/src/server/index.ts

@@ -1,6 +1,8 @@
 import { weatherTool } from './tool';
 import weatherMeta from './cards/weather/meta';
-import type { ServerContext, ServerModule } from '@tbox.cn/app-sdk/server';
+import { loadModuleSkills } from '@tbox.cn/app-sdk/server';
+import type { LocalSkill, ServerContext, ServerModule } from '@tbox.cn/app-sdk/server';
+import { weatherPreTool } from './pre-tools';
 
 export { weatherTool, weatherMeta };
 
@@ -9,9 +11,32 @@ const cards = {
   weather: weatherMeta,
 } as const;
 
+/**
+ * 模块 skill 声明（009 模块文件化：SKILL.md 目录格式，文件即唯一源）。
+ * - 底层能力：SDK `loadModuleSkills(packageName, import.meta.url)` 单策略定位包根
+ *   （createRequire 包名解析：dev workspace link / 模块 dist / 应用 bundle dist / 发布态
+ *   node_modules 全形态恒命中；失败 warn 可行动 + 恒 resolve []）；
+ * - 顶层 await 加载 → 填回 serverModule.skills 声明式通道（装配端 registerAll 自动注册）；
+ * - 前置：本包 exports 须含 "./package.json"（见 package.json）；
+ * - 生成应用内（codegen 展开）调用名由 CLI 自动改写为 @app/<id>，源码按字面量包名写法。
+ */
+const skills = Object.fromEntries(
+  (await loadModuleSkills('@app/module-weather', import.meta.url)).map((s) => [s.name, s]),
+) satisfies Record<string, LocalSkill>;
+
+/**
+ * 模块前置工具声明（010：key 约定 = toolId，纯数据 + 一个 resolve 函数）。
+ * 装配端 registerServerModules 自动注册（register 内无需代码）。
+ */
+const preTools = {
+  getWeather: weatherPreTool,
+} as const;
+
 /** 模块注册入口：自注册闭环（与客户端 clientModule 对称） */
 export const serverModule = {
   cards,
+  skills,
+  preTools,
   register(ctx: ServerContext): void {
     ctx.tools.register(weatherTool);
     ctx.cards.registerMap(cards);

package/packages/module-weather/src/server/pre-tools.ts

@@ -0,0 +1,20 @@
+import { definePreTool } from '@tbox.cn/app-sdk/server';
+import { weatherTool } from './tool';
+
+/**
+ * 前置工具声明（010）：getWeather 的 city 参数可工程化抽取（城市词表），
+ * 无需模型抽参——词表命中即预执行，模型第一轮直接作答（省一轮 loop）。
+ *
+ * 演示形态：文本工程化抽取——决策即构造：
+ *   抽到城市 → { decision: 'run', args: { city } }（预执行，args 强类型由 tool 推断）；
+ *   抽不到 → { decision: 'skip' }（本轮不生效，模型正常调用工具）。
+ */
+const CITIES = ['北京', '上海', '广州', '深圳', '杭州', '成都', '武汉', '西安', '南京', '重庆'];
+
+export const weatherPreTool = definePreTool(weatherTool, {
+  routing: { mode: 'keywords', terms: ['天气', '气温', '下雨', '下雪', '穿衣', '出行'] },
+  decide: ({ text }) => {
+    const city = CITIES.find((c) => text.includes(c));
+    return city ? { decision: 'run', args: { city } } : { decision: 'skip' };
+  },
+});

package/pnpm-workspace.template.yaml

@@ -26,16 +26,17 @@ catalog:
   "@types/express": ^4.17.21
   ws: ^8.18.0
   "@types/ws": ^8.5.0
-  "@mastra/core": ^1.33.0
-  "@mastra/observability": 1.12.0
+  "@mastra/core": ^1.57.0
+  "@mastra/observability": 1.16.5
+  "gray-matter": ^4.0.3
   "@ag-ui/core": ^0.0.47
   ai: ^6.0.0
   "@ai-sdk/openai": ^3.0.0
   "@ai-sdk/provider": ^3.0.10
   "@tbox.cn/agent-plugin": 0.1.0
-  "@tbox.cn/app-sdk": ^0.1.0
+  "@tbox.cn/app-sdk": ^0.2.0
   "@tbox.cn/app-contracts": ^0.1.0
-  "@tbox.cn/app-contracts-mall": ^0.1.0
+  "@tbox.cn/app-contracts-mall": ^0.2.0
   zustand: ^4.5.5
   commander: ^12.1.0
   diff: ^7.0.0