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

package/.gitignore

@@ -2,6 +2,7 @@ node_modules
 dist
 dist-ssr
 .vite
+*.tsbuildinfo
 *.local
 .DS_Store
 *.log
@@ -11,3 +12,8 @@ dist-ssr
 .env
 .env.*
 !.env.example
+
+# 本地评测产物（tbox-app eval / start -d；报告与轨迹不进版本库）
+.eval/
+.tbox-server.json
+.tbox-server.log

package/.tbox/app.json

@@ -1,4 +1,13 @@
 {
-  "templateVersion": "7.0.0",
-  "npmModules": []
-}
+  "templateVersion": "7.1.0",
+  "npmModules": [
+    {
+      "id": "provider-custom",
+      "package": "@tbox.cn/app-provider-custom",
+      "version": "0.1.0",
+      "mode": "codegen",
+      "baseVersion": "0.1.0"
+    }
+  ],
+  "miniappContainers": []
+}

package/AGENTS.md

@@ -1,6 +1,6 @@
 # AGENTS.md
 
-tbox-agent-app 是多包 pnpm workspace：`apps/` 薄组装端 + `packages/` 模块。客户端同时运行在浏览器和支付宝小程序 web-view 壳中。
+template-agent 是多包 pnpm workspace：`apps/` 薄组装端 + `packages/` 模块。客户端同时运行在浏览器和支付宝小程序 web-view 壳中。
 
 > **工作区上下文（发布态消费，005 v0.4.0）**：仓库内本目录是**根 workspace 成员子树**（无独立 `pnpm-workspace.yaml`），
 > 平台引用 `catalog:` + 根 `pnpm-workspace.yaml` `overrides: workspace:*` 回指根 `packages/` 真源；`pnpm` 命令在根上下文执行。
@@ -26,7 +26,7 @@ tbox-agent-app 是多包 pnpm workspace：`apps/` 薄组装端 + `packages/` 模
   `register` 内经 `ctx.cards.registerMap(cards)` 注册卡片组件。
 - `cards` map 的 **key 约定 = meta.cardType**（server 端 meta 的 cardType；doctor 会校验），无卡片模块写 `cards: {}`；
   模块对象必须用 `satisfies`（不能 `: ServerModule` 标注——标注会把 cards 泛化导致类型推导失效）。
-- 每个模块根目录有 `tbox.component.json`（schema v1）声明 contributes（tools/cards/handlers/routes/pages/tabs）。
+- 每个模块根目录有 `tbox.module.json`（schema v1）声明 contributes（tools/cards/handlers/routes/pages/tabs）。
   跨模块写操作走 `ctx.services.register/resolve` + 类型化事件总线，业务代码只 import `@tbox.cn/app-contracts`（或领域契约包），不 import `apps/*`。
 
 ## 装配文件（双锚点，双端逐行同构）
@@ -55,7 +55,7 @@ apps/server/src/index.ts                      # 服务端入口（HTTP + WS + Vi
 apps/server/src/modules.ts                    # 服务端模块装配（registerAll）
 packages/app-sdk/src/server/chat-engine.ts    # ChatEngine 工厂
 packages/app-sdk/src/server/context.ts        # ServerContext（注册表聚合 + createServerContext）
-packages/app-sdk/src/server/build-engine.ts   # createEngineFromContext / createSdkToolRuntime / buildToolCardBindings
+packages/app-sdk/src/server/build-engine.ts   # createEngineFromContext / createSdkToolRuntime（出卡 capture 在 engine 构造期包装，见 tool-cards.ts）
 packages/app-sdk/src/client/chat-store.ts     # ChatStore 工厂
 packages/contracts/src/                       # 跨端类型契约
 config/                                       # chat/model/plugin 配置
@@ -75,11 +75,11 @@ pnpm plugin:doctor
 pnpm plugin:inspect <pluginId> <toolId>
 ```
 
-模块安装/装配由 `tbox-app` CLI（`@tbox.cn/app-cli`）管理：`create`（顶层）+ `module add --mode local|codegen|sdk --source <路径|tgz|registry包> / remove / list / sync / diff / doctor / update / publish`（模块二级组）。add/remove/sync 后需 `pnpm install`。未安装 CLI 时：`pnpm add -g @tbox.cn/app-cli`（registry 安装）。
+starter 文档：`tbox-app starter --type agent`；可用类型：`tbox-app starter --list`。在沙箱中使用 `tbox-app create . --name <app-name> --source @tbox.cn/app-template-agent` 原地初始化，应用模板的 `AGENTS.md` 会覆盖 starter seed。模块安装/装配由 `tbox-app` CLI（`@tbox.cn/app-cli`）管理：`module add --mode local|codegen|sdk --source <路径|tgz|registry包> / remove / list / sync / diff / doctor / update / publish`。add/remove/sync 后需 `pnpm install`。未安装 CLI 时：`pnpm add -g @tbox.cn/app-cli`（registry 安装）。
 
 ## 平台基础设施
 
-以下链路受保护，不得删除或绕过（`scripts/check-inspector.sh` 校验）：
+以下链路受保护，不得删除或绕过（守卫随 `@tbox.cn/app-sdk` 分发：`pnpm check:inspector` / `tbox-inspector-check`，已入 `pnpm verify` 链）：
 
 - `@tbox.cn/app-sdk/platform` 的 `installInspector`（`@infrastructure-locked`；`apps/server/src/index.ts` 从 `@tbox.cn/app-sdk/platform` import 并调用 `installInspector(app)`）
 - `apps/client/index.html` 中的 `/__vs_inspector__.js`（`RUNTIME_PATH` 约定不变）
@@ -95,7 +95,18 @@ pnpm plugin:inspect <pluginId> <toolId>
 - 平台"插件"页添加插件时只改 `config/plugins.json`。应用代码不复制插件鉴权、参数注入、runtime ID 或 SDK 客户端。
 - 插件结果出卡时按 `packages/contracts/src/cards.ts` 注册 schema，在模块包内注册 adapter 和 client 组件。
 
+## web-view 样式约定（014，POC 沉淀）
+
+客户端同时跑浏览器与支付宝小程序 web-view 壳（组件挂载于 H5 视口，非小程序原生渲染），样式遵守：
+
+1. **长度单位 PX 大写**（如 `800PX`）——web-view 内联字体放大：小写 `px` 被浏览器 rem 缩放改写，大写跳过改写保持视觉尺寸。
+2. **flex 子项设 `flex-shrink: 0`**——壳内内容宽度不定，防元素被压缩变形。
+3. **滚动容器隐藏滚动条**（`::-webkit-scrollbar { display: none }`）——web-view 无原生滚动条，出现即破相。
+4. **颜色用 `rgba()` 传统语法**——避免 `color-mix`/`oklch` 等新语法在低版本 web-view 内核不渲染。
+
 ## 工程边界（check-workspace 校验）
 
-- `packages/*` 业务包必须有 `tbox.component.json`；SDK/契约（`app-sdk` / `contracts*` / `shared`）豁免。
+- `packages/*` 业务包必须有 `tbox.module.json`；SDK/契约（`app-sdk` / `contracts*` / `shared`）豁免。
+- `scripts/` 下所有文件保持可执行位（git 100755；CLI create 后 chmod 兜底）；双模板 scripts 文件集合镜像全等（guard-workspace R4）。
 - 装配文件不得裸 import（全部 import 行在锚区内）；模块包不得 import SDK/契约内部路径（仅公开入口 `@tbox.cn/app-sdk{/server,/client,/platform}` 与 `@tbox.cn/app-contracts`）。
+- 构建序列单源 = 根 `build` / `build:client` script（守卫经 `check` 组合注入）；`build.sh` 只管环境 + install + 委托——新守卫改 `check` 组合，不改 build.sh；零依赖守卫恒可 install 前（`check:workspace` 已占此位）。

package/ENV.md

@@ -4,11 +4,28 @@
 
 ## 配置方式
 
-- **本地开发**:shell export 注入(每次新终端需重新执行;见文末命令块)。tbox 模板仓库根提供 `env.sh.example`(git 跟踪,无密钥)——模板仓库内开发可 `cp env.sh.example env.sh` 填值;生成应用请直接 shell export 或平台配置。
+- **本地开发**:shell export 注入(每次新终端需重新执行;见文末命令块)。生成应用请直接 shell export 或平台配置。
 - **生产**:建议在 tbox 平台页面上配置环境变量(平台托管 env,密钥不进代码仓库、不进 git)。
   生产部署必须 `NODE_ENV=production`(dev-login 强制关闭 + JWT 密钥链 fail-fast 的依据)。
+  入口分离后 dist 恒静态供给(vite dev 仅存在于源码 `src/dev.ts` 本地开发入口);`NODE_ENV` 不再决定
+  客户端供给形态——测试环境可用 `node dist/index.js`(不设 NODE_ENV)获得「静态产物 + dev-login」。
 - 以下变量缺失时服务可启动,但对话/会话/上传链路会 503。
 
+## 配置文件：config/chat.json（会话 UI 设置）
+
+六字段（`quickCommands`/`enableImageUpload`/`enableVideoUpload`/`enableTTS`/`enableVoiceInput`/
+`defaultInputMode`）由 server 经 `loadChatConfig` 读取（zod fail-soft），WS HELLO chatConfig
+**服务端运行时下发单一真源**：`quickCommands` 映射 query→prompt，其余五键经 `settings` 下发 →
+client 水合覆盖构建期快照；`/ws/tts` 通道门同源（`enableTTS:false` 时 upgrade 硬拒）。
+dev 态 `TBOX_CONFIG_DIR` 可指档位目录替换默认 `config/`。**改 chat.json 需重启 server，新连接生效**
+（client 构建期静态 import 仅作 ack 未达/键缺席的回落快照）。
+
+## 配置文件：config/agent.jsonc（agent 提示词）
+
+`instructions` 业务段行数组（首行身份句）+ `memoryInstructions` 可选（装配长期记忆时由 SDK 追加）。
+未配置时 SDK 默认提示词兜底；解析失败 ERROR 日志 + 兜底。改文件需重启 server。（本模板出厂不携带
+该文件——即 SDK 默认形态）
+
 ## 必需
 
 ### 模型服务(OpenAI 兼容接口)
@@ -17,7 +34,9 @@
 |---|---|
 | `APP_AI_BASE_URL` | 模型服务地址(OpenAI 兼容 `/v1`) |
 | `APP_AI_API_KEY` | API 密钥 |
-| `APP_AI_MODEL_NAME` | 模型名称;可留空:`config/llm_provider.json` 的 `modelName` 优先 |
+| `APP_AI_MODEL_NAME` | 模型名称;可留空:`config/llm_provider.json` 的 `modelName` 优先。同文件 `thinking` 字段控制模型思考,优先级高于下方 env 开关 |
+| `APP_AI_THINKING` | 模型思考开关 `true`/`false`/`auto`,缺省 `false`(代码级默认——删除配置文件/字段≠开启思考);`config/llm_provider.json` 的 `thinking` 字段优先级更高,且额外支持 object 形态(字面量合并进请求体顶层,可覆盖 `model`/`messages` 等键——慎用);`"auto"` 为不注入逃生舱;每请求热读,改配置即生效无需重启 |
+| `APP_AI_PARALLEL_TOOL_CALLS` | 并行工具调用 `true`/`false`/`auto`,缺省 `auto`(不注入,走网关按模型默认);`config/llm_provider.json` 的 `parallelToolCalls` 字段优先级更高;每请求热读,改配置即生效无需重启 |
 
 ### tbox 平台凭证
 
@@ -25,16 +44,26 @@
 |---|---|
 | `TBOX_API_KEY` | 平台 API Key:插件直接使用;语音/上传/反馈/TTS 靠它换 session。缺失时插件不加载,`GET /api/tbox/session` 返回 503 → 前端平台能力适配器建不起来 |
 | `TBOX_APP_ID` | 应用 ID |
+| `TBOX_MEMORY_KB_ID` | 长期记忆知识库 ID(`TBOX_MEMORY_STORE=knowledge` 时与 `TBOX_MEMORY_KB_DOC_ID`/平台凭证三缺一回退 inmemory;SDK `bootstrapMemoryKnowledgeBase()` 幂等建库产出固化(生成应用内 `node -e` 调用或联系平台)) |
+| `TBOX_MEMORY_KB_DOC_ID` | 记忆知识库文档 ID(同上必填;addSegment/容量淘汰通道入参) |
+| `TBOX_MEMORY_KB_BASE_URL` | 知识库通道地址(缺省 https://o.tbox.cn;预发联调 https://agtgw-pre.alipay.com) |
+| `TBOX_MEMORY_KB_COOKIE` | 预发访问管控 Cookie 透传(仅预发联调;生产不设——配置会触发 warn。多应用同租户共用知识库时勿共用缺省 KB 名,建库脚本已按 appId 命名) |
+| `TBOX_MEMORY_KB_VALIDATE` | knowledge 启动校验开关(`=1` 异步校验——不阻塞启动;KB 回读不符/超时 → 记忆功能降级:调用时报错+HTTP 503,防 kbId 误配静默击穿跨用户隔离且不拖垮系统;`strict` 同步阻塞校验,不符即启动失败——零窗口合规场景;未设置不校验。仅 knowledge 三件套齐备时生效;生产启用建议 `=1`) |
+| `TBOX_MEMORY_KB_VALIDATE_TIMEOUT_MS` | 校验整体超时毫秒数(缺省 10000;`>=1` 才生效,非法回退缺省。超时按校验失败定性——降级态修复 KB 配置后重启恢复) |
+| `TBOX_MEMORY_RECALL_TIMEOUT_MS` | recall 整体 deadline 毫秒数(缺省 200;`0` = 禁用召回注入。B4 起 withRecallCache 装饰器缺省装配——零记忆用户负缓存短路 recall <10ms,真查询单 RTT 约 150-300ms,超时降级跳过不拖首字) |
+| `TBOX_LLM_AFFINITY` | 会话亲和大容量旋钮(缺省 on;`=off` 关闭——fetch 头 `X-Affinity-Session` 与 body `prompt_cache_key` 双通道均不注入。best-effort 语义:网关负载可覆盖亲和;排障时若网关对未知 body 字段报错可关) |
+| `TBOX_LLM_CONN_BIND` | per-session 连接绑定旋钮(缺省 on;`=off` 关闭——LLM fetch 回退全局连接池。连接=网关缓存池路由单位:per-session 单连接(120s keep-alive)钉死集群分配,保活跨 run 提升前缀缓存命中;排障时可关) |
+| `TBOX_LLM_COOKIE_AFFINITY` | 网关 cookie 亲和旋钮(缺省 on;`=off` 关闭——不回传网关 set-cookie。回传激活 LB 粘性:连接重建后恢复原集群的通道;best-effort) |
 
 ## 统一鉴权(006)
 
 | 变量 | 说明 |
 |---|---|
-| `AUTH_TOKEN_SECRET` | 自有 JWT 密钥(≥32 字节随机串),生产由平台注入。未配置回退:`TBOX_API_KEY`(须 ≥32 字节)→ dev 临时随机;prod 整链空则 fail-fast(拒绝启动)。本地一般无需设置 |
+| `AUTH_TOKEN_SECRET` | 自有 JWT 密钥(≥32 字节随机串),生产由平台注入。006 鉴权与 011 模块动作授权(action-grant)共用统一密钥链:未配置回退 `TBOX_API_KEY`(须 ≥32 字节)→ dev 临时随机;prod 整链空则 fail-fast(拒绝启动)。011 另有 `ACTION_TOKEN_SECRET` 覆盖档。本地一般无需设置 |
 | `AUTH_MODE` | `required`(默认,缺失 token 一律 401)/ `optional`(缺失 token → 匿名,写通道仍拒绝) |
 | `AUTH_DEV_LOGIN_DISABLED` | 非生产环境需关闭 dev-login 时设 `true`(dev-login 非 production 默认开启,生产强制关闭) |
 | `AUTH_TOKEN_TTL_MS` | token 有效期(毫秒,默认 2h) |
-| `AUTH_TOKEN_ISSUER` | token issuer(默认 `tbox-agent-app`) |
+| `AUTH_TOKEN_ISSUER` | token issuer(默认 `agent`) |
 | `AUTH_EMBED_EXTERNAL_TOKEN` | 是否把外部原始 token 内嵌进自有 JWT(external claim,默认 `true`;`false` 则上游调用需另取) |
 | `AUTH_EXTERNAL_TOKEN_MAX_BYTES` | external 原始 token 上限(bytes,默认 16KB=Node http header 上限)。external claim 使自有 JWT 膨胀 ~1.4x,生产网关 header 上限需 ≥16KB |
 | `AUTH_EXTERNAL_EXCHANGE_URL` | 外部 provider 换发地址;配置后 `/api/auth/login(platform=external)` 走 HMAC 转发换发 |
@@ -60,6 +89,10 @@
 | `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` = 整体禁用(预执行全关,行为与未启用逐字节一致)。非法值回退默认 |
+| `TBOX_TOOL_DEBUG` | 工具调试视图(018):`1` 开 / `0` 关;缺省 = 非 `NODE_ENV=production` 开启。开启时 memory 召回/silent 前置工具以伪工具事件下发前端(不持久化)且 HELLO_ACK 携带旗标解锁客户端 dev 工具视图(出入参展开+紧凑格式)。**生产勿开**——测试环境开启会使 silent 检索 query 与用户记忆预览(截断 200 字符)对页面访问者可见。非法值回退缺省 |
+| `TBOX_EARLY_TOOL_EXECUTION` | 尽早工具执行(缺省 `off`):`1`/`true` 开启。模型流中白名单工具(只读查询类,`withEarlyExecution` 标记)参数流完即预执行,多工具轮延迟优化;收益依赖 `parallelToolCalls` 开启;参数漂移自动作废重执行(正确性无损);单工具轮行为等价现状。仅显式 opt-in,观测 journal `tool_preexec` |
 | `HOST` | 服务监听地址(默认 `0.0.0.0`) |
 | `PORT` | 服务监听端口(默认 `8000`) |
 
@@ -73,5 +106,5 @@ export TBOX_API_KEY=...
 export TBOX_APP_ID=...
 # TTS(可选;缺失时 TTS 播放报 CONFIGURATION_ERROR):
 export TTS_AUTH_URL=https://open.tbox.alipay.com/agent/v1/homepage/secret/get
-export TTS_APPKEY=your-tts-appkey   # 敏感值勿提交;本地经 shell export 或 env.sh(gitignore)注入
+export TTS_APPKEY=your-tts-appkey   # 敏感值勿提交;本地 shell export 注入(生产由平台注入)
 ```

package/README.md

@@ -1,4 +1,4 @@
-# tbox-agent-app
+# template-agent
 
 tbox AI Agent 全栈模板（npm 包名 `@tbox.cn/app-template-agent`），多包 pnpm workspace：`apps/` 薄组装端 + `packages/` 模块。
 客户端同时支持浏览器和支付宝小程序 web-view；平台能力（鉴权/会话/TTS/ASR/上传/反馈）经 `@tbox.cn/app-sdk` 统一提供（007 下沉）。
@@ -14,11 +14,11 @@ pnpm verify       # typecheck + test + build
 > 环境变量：本地开发用 shell export 注入（见 `ENV.md`，含必需变量命令块；每次新终端需重新执行），
 > 生产建议在 tbox 平台页面上配置（平台托管 env，密钥不进代码仓库）。
 
-> 平台包消费（005 v0.4.0 发布态）：生成应用以 `catalog:` 引用 `@tbox.cn/{app-sdk,contracts,contracts-mall}`——
+> 平台包消费（005 v0.4.0 发布态）：生成应用初始通过 `@app/contracts-mall` shim 使用 `catalog:` 引用的发布包；添加依赖 contracts-mall 的 codegen 模块后，CLI 将 shim 替换为本地源码包——
 > 生产（registry 已发布）直接 `pnpm install`；平台包未发布 npm 时，由 `tbox-app create --local-deps <平台 tgz 目录>`
 > 注入 overrides（`file:` 本地发布态产物）后 install 离线可用。
 >
-> 依赖链说明（007）：`@tbox.cn/app-sdk` 新增 dependencies `@tbox-dev-js/sdk`（平台能力客户端）、`@ai-sdk/openai`（LLM）——
+> 依赖链说明（007）：`@tbox.cn/app-sdk` 新增 dependencies `@tbox-dev-js/sdk`（平台能力客户端）、`@ai-sdk/openai-compatible`（LLM）——
 > 生成应用 install 时由 pnpm 自动解析（`@tbox-dev-js/sdk` 已发布 npm；内网/离线环境需 registry 镜像或 store 缓存兜底）。
 
 > 🔐 鉴权（006）：非 production 默认开启 dev-login（浏览器 H5 测试登录，开箱即用）；
@@ -28,10 +28,11 @@ pnpm verify       # typecheck + test + build
 ## 工程结构
 
 ```text
-tbox-agent-app/
+template-agent/
   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,13 +40,138 @@ 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>`）；contracts-mall 作为平台 codegen 依赖时，模块 import 与依赖键由同一归一化器改写为 `@app/contracts-mall`。
+
+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`、领域属性经入参 `attributes` 获取（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=纽约)（无合成工具消息，跨轮不再泛化「已调用过」）
+```
+
+## 深链自动发送
+
+打开页面时 URL 携带 `?query=...`（或 `?prompt=...` 兜底，`query` 优先）即自动发送该消息一次，
+与手动输入同通道。参数读取后立即从地址栏剥离（replaceState）：刷新不重发、分享不带参；
+socket 5 秒内未就绪则静默放弃。SDK 单点实现（`@tbox.cn/app-sdk/client` 的
+`consumeAutoSendQuery`/`runAutoSend`），模板侧仅 3 行接线（IndexPage init effect）。
+
+### 冒烟
+
+```sh
+# 浏览器访问 http://127.0.0.1:8000/?query=今天天气怎么样
+# 预期：自动发送一次；地址栏 query 消失（其余参数保留）；刷新不重发；dev 模式（StrictMode）不双发
+```
+
 ## 平台能力定制（007 扩展点）
 
 平台轴（安全管道/能力管道/协议客户端）已下沉 `@tbox.cn/app-sdk`，模板保留 3 个注入点 + 模板源码扩展：
 
 | 口子 | 位置 | 场景 |
 |---|---|---|
-| `createAuthRuntime(readAuthConfig(), { exchanges })` | `@tbox.cn/app-sdk/server` | 自定义/覆盖登录 provider（注入优先于内置 alipay/weapp） |
+| `ctx.authExchanges.register(...)` | `@tbox.cn/app-sdk/server` | 自定义登录换码器（F2 注册制：scoped 谓词路由 / 无条件兜底，机制见 docs/reference/auth.md；静态 `exchanges` 注入仍兼容） |
+| `getToolRequestContext` / `requireToolRequestContext` | `@tbox.cn/app-sdk/server` | 工具 execute 第二参读取运行上下文（fail-soft / 缺失抛 AUTH_FORBIDDEN；上下文统一化） |
+| `createToolExecContext(reqCtx)` | `@tbox.cn/app-sdk/server` | 测试/直调助手：构造工具 execute 第二参（散键与引擎同构） |
 | `createPlatformAdapters(session, overrides)` | `@tbox.cn/app-sdk/client` | 自定义 ASR/TTS/upload/feedback 实现（contracts 接口，UI 零改动） |
 | `createAuthClient({ loginPlatform, devUser })` | `@tbox.cn/app-sdk/client` | 客户端登录配置（`main.tsx`/`platform/agent-runtime.ts`）；**应用级单例**——重复调用幂等返回首建实例，首建选项生效 |
 | `configureRuntime({ apiBaseUrl })` | `@tbox.cn/app-sdk/client` | API/WS 地址注入（`main.tsx`；对应 `VITE_API_URL`） |

package/apps/client/package.json

@@ -19,7 +19,8 @@
     "react-dom": "catalog:",
     "react-markdown": "catalog:",
     "remark-gfm": "catalog:",
-    "zustand": "catalog:"
+    "zustand": "catalog:",
+    "@app/provider-custom": "workspace:*"
   },
   "devDependencies": {
     "@types/node": "catalog:",
@@ -31,4 +32,4 @@
     "typescript": "catalog:",
     "vite": "catalog:"
   }
-}
+}

package/apps/client/src/app.tsx

@@ -1,5 +1,33 @@
+import { lazy, Suspense } from 'react';
 import BusinessApp from '@/business/App';
 
+// dev 卡片预览页（/_tbox/card-preview）：
+// - 守卫用**三元**而非 if——`import.meta.env.DEV` 在生产构建被静态替换为 false，
+//   lazy 分支成为可摇除死代码，动态 import 与页面 chunk 一并消失（若用顶层 if，
+//   lazy() 调用本身活过 treeshaking，chunk 仍会产出）；
+// - lazy 双动态 import 组装（SDK 页面 + 模板 registry/authClient 单例注入——
+//   authClient 含模板选项，不经预览页自建）。
+const CARD_PREVIEW_PATH = '/_tbox/card-preview';
+const DevCardPreview = import.meta.env.DEV
+  ? lazy(async () => {
+      const [{ CardPreviewPage }, { CARD_REGISTRY }, { authClient }] = await Promise.all([
+        import('@tbox.cn/app-sdk/client/card-preview'),
+        import('@/cards/registry'),
+        import('@/platform/agent-runtime'),
+      ]);
+      return {
+        default: () => <CardPreviewPage registry={CARD_REGISTRY} authClient={authClient} />,
+      };
+    })
+  : null;
+
 export default function App() {
+  if (import.meta.env.DEV && DevCardPreview && window.location.pathname === CARD_PREVIEW_PATH) {
+    return (
+      <Suspense fallback={<div>加载卡片预览…</div>}>
+        <DevCardPreview />
+      </Suspense>
+    );
+  }
   return <BusinessApp />;
 }

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

@@ -1,10 +1,20 @@
 /**
  * 卡片渲染入口 — 注入本地 registry 后委托 SDK 的 CardRenderer。
+ * 011 B3：动作按钮 → sendUiAction（token 来自 payload.actionTokens）。
+ * P1：onAction 升级为完整 UiAction（CardRenderer 按 kind 分发后回传，桥一行透传）。
  */
 import { CardRenderer as SdkCardRenderer } from '@tbox.cn/app-sdk/client';
-import type { TboxCardPayload } from '@tbox.cn/app-contracts';
+import type { TboxCardPayload, UiAction } 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={(action: UiAction) => sendUiAction(card.id, action)}
+    />
+  );
 }

package/apps/client/src/components/ActionBar/DebugButton.tsx

@@ -1,3 +1,7 @@
+import { createLogger } from '@tbox.cn/app-sdk/client';
+
+const debugLogger = createLogger('DebugButton');
+
 import debugIcon from '../../../assets/debug.png';
 
 /**
@@ -36,7 +40,7 @@ export function DebugButton({
         '*',
       );
     } catch (err) {
-      console.warn('[DebugButton] postMessage failed:', err);
+      debugLogger.warn('postMessage failed:', err);
     }
   };
 

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

@@ -1,4 +1,7 @@
 import { useEffect, useState, useSyncExternalStore } from 'react';
+import { createLogger } from '@tbox.cn/app-sdk/client';
+
+const ttsActionLogger = createLogger('tts');
 import { useChatStore } from '@/store/chat';
 import { useChatConfigStore } from '@/store/chat-config';
 import { useFeedbackAdapter, useRefreshSession, useTTSAdapter } from '@tbox.cn/app-sdk/client';
@@ -98,7 +101,10 @@ export function ActionBar({ message }: { message: ChatMessage }) {
     }
     _isPlaying = true;
     setPlayingId(message.id);
-    tts.speak(message.content, message.id).catch(() => setPlayingId(null));
+    tts.speak(message.content, message.id).catch((err: unknown) => {
+      ttsActionLogger.warn(`tts.speak 失败：err=${(err as Error)?.message ?? String(err)}`);
+      setPlayingId(null);
+    });
     _isPlaying = false;
   };
 

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

@@ -1,3 +1,11 @@
+.tbox-voice-page-lock,
+.tbox-voice-page-lock * {
+  user-select: none !important;
+  -webkit-user-select: none !important;
+  -webkit-touch-callout: none !important;
+  -webkit-user-drag: none !important;
+}
+
 .tbox-chat-input {
   position: relative;
   z-index: 1;
@@ -12,6 +20,36 @@
     display: flex;
     align-items: flex-end;
     gap: 16px;
+    flex-wrap: wrap;
+  }
+
+  /* 连接终态阻断提示条（禁用输入 + 重试入口；配色沿用既有错误语义，不硬编码新色值） */
+  &__blocked {
+    flex-basis: 100%;
+    display: flex;
+    align-items: center;
+    gap: 12px;
+    padding: 12px 20px;
+    border-radius: 12px;
+    background: rgba(255, 241, 241, 0.9);
+    color: #d5492f;
+    font-size: 24px;
+    line-height: 1.4;
+
+    &-msg {
+      flex: 1;
+      min-width: 0;
+    }
+
+    &-retry {
+      flex-shrink: 0;
+      padding: 6px 20px;
+      border: none;
+      border-radius: 999px;
+      background: #d5492f;
+      color: #fff;
+      font-size: 22px;
+    }
   }
 
   /* 半透明白色药丸 */
@@ -44,6 +82,11 @@
     &::placeholder {
       color: rgba(16, 41, 83, 0.6);
     }
+
+    /* 连接终态阻断（登录失败/scope 拒绝）：禁用态弱化输入框 */
+    &:disabled {
+      opacity: 0.45;
+    }
   }
 
   /* 发送 / 停止（图片图标） */
@@ -212,6 +255,9 @@
   box-sizing: border-box;
   overflow: hidden;
   user-select: none;
+  -webkit-user-select: none;
+  -webkit-touch-callout: none;
+  touch-action: none;
 
   &--disabled {
     opacity: 0.35;
@@ -249,6 +295,10 @@
   position: fixed;
   inset: 0;
   z-index: 300;
+  user-select: none;
+  -webkit-user-select: none;
+  -webkit-touch-callout: none;
+  touch-action: none;
 
   &__mask {
     position: absolute;
@@ -264,6 +314,9 @@
     justify-content: center;
     padding: 0 24px calc(56px + env(safe-area-inset-bottom, 16px));
     box-sizing: border-box;
+    user-select: none;
+    -webkit-user-select: none;
+    touch-action: none;
   }
 
   &__panel {
@@ -328,5 +381,6 @@
     background-image: url('https://mdn.alipayobjects.com/huamei_frp8ut/afts/img/A*5PDvR4j7fBgAAAAAVBAAAAgAet-KAQ/original');
     background-size: 100% 100%;
     background-repeat: no-repeat;
+    pointer-events: none;
   }
 }