@tbox.cn/app-template-agent 0.10.8 → 0.10.9

package/ENV.md

@@ -171,6 +171,8 @@ dev/src 与 prod/dist bundle 形态恒等）：
 | `MALL_HOME_DEV_SERVICES` | 首页「常用服务」开发测试入口展示开关:`true`/`1` 展示,`false`/`0`/缺席隐藏(fail-closed,正式用户零透出;生产部署不配置即隐藏态)。server 启动期解析,经 `GET /api/m/mall-core/config` 下发前端(响应 `{ showDevServices: boolean }`);env 变更需重启进程。注入走外层 source(档位 env 文件/启动器 scripts/app-dev.mjs),`tbox-app dev` 不注入 env 值 |
 | `HOST` | 服务监听地址(默认 `0.0.0.0`) |
 | `PORT` | 服务监听端口(默认 `8000`) |
+| `TBOX_DEV_TOKEN` | 沙箱 dev server 鉴权 token(方案 W;平台运行时注入,**本地无需设置**):形状 `^[A-Za-z0-9_-]{20,128}$`。在场 → protected 双面裁决——dev 面(凭据 + 浏览器导航/同源信号)完整 vite 能力,static 面(无凭据/跨源子资源)纯 dist + SSE 刷新,零源码泄漏;缺席 → classic(与历史行为字节级等价)。在场但形状不合规 → fail-closed 全 static。配套:`GET /__tbox_dev_hot_reload`(static 面刷新 SSE,凭据无关);HMR WS 凭据走 query(`tbox_dev_token`,页面 bootstrap 自动补参);protected 面 vite `fs.allow` 收窄(client 源 + 工作区依赖真源)+ `fs.deny` 保留 |
+| `TBOX_DEV_SSE_KEEPALIVE_MS` | protected 面 SSE 心跳间隔 ms(缺省 15000;smoke-dev-protected.sh 经此覆盖加速断言。非法/缺席回退缺省) |
 
 ## 本地 export 命令块(必需项,可复制)
 
@@ -193,3 +195,16 @@ export MALL_HOME_DEV_SERVICES=true
   覆盖面含 `llm_provider.json`（`modelName`/`thinking`）：注入时 LLM 装配读档位目录文件，
   其 `modelName` 优先于 `APP_AI_MODEL_NAME`；档目录缺该文件 → 链式回退 env（config-dir 独占
   注入语义：缺文件 = 显式不指定，不落回模板默认 config）。
+
+# dev protected 排障速查（方案 W）
+
+`TBOX_DEV_TOKEN` 注入形态下预览异常时，按症状对日志特征定位（`TBOX_LOG_LEVEL=debug` 开 debug 族）：
+
+| 症状 | 日志特征 | 处置 |
+|---|---|---|
+| 页面白屏且网络面全 404 | `dev_face_decision` reason=`no-cred` | 凭据未送达——确认预览面板 URL 带 `tbox_dev_token`（302 盖戳后以 cookie 存续）；手动验证用 `?tbox_dev_token=<token>` |
+| HMR 不连（浏览器 console `vite:ws:disconnect`） | `dev_hmr_upgrade` outcome=`rejected-401` | WS query 凭据缺失/失效——页面须经 dev 面 HTML 加载（bootstrap 自动补 query）；直接打开裸 URL 无 token |
+| 静态面不刷新（改代码后页面不变） | 无 `dev_build_end` | watch 构建未触发/失败——看 `[dev] watch build failed`；public/ 改动 **dev 面实时生效**（vite publicDir 实时读盘）但 static 面（dist）滞后至下次 rebuild（rollup watch 不监 publicDir——已实测），需手动刷新或 touch 源文件 |
+| 页面反复刷新循环 | `dev_build_end` 高频 | touch 型工具循环改文件——排查写入源 |
+| 302 后 requestId 变化对不上 | 前后两条 `dev_face_decision` requestId 不同 | 302 盖戳是独立一跳（box 侧 `dev_token_redirect`），两跳 requestId 各自独立——按 URL 与时序关联 |
+| 本地 protected 直跑模块 403 | `dev_face_decision` reason 正常但 `/@fs` 403 | 构建区（.tbox-dev.local）缺席时 fs.allow 为收窄半径；workspace 真源目录在 allow 内（`packages/`），应用自有文件按收窄语义拒绝 |

package/apps/client/src/app.tsx

@@ -2,13 +2,15 @@ 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 仍会产出）；
+// - 守卫用**三元**而非 if——`DEV || __TBOX_CARD_PREVIEW__` 在生产构建（define false）被
+//   静态替换为 false，lazy 分支成为可摇除死代码，动态 import 与页面 chunk 一并消失
+//   （若用顶层 if，lazy() 调用本身活过 treeshaking，chunk 仍会产出）；
+// - 方案 W：沙箱 protected 静态面经 __TBOX_CARD_PREVIEW__（build + TBOX_DEV_TOKEN）放行，
+//   dev 面仍由 import.meta.env.DEV 放行——两态共用同一 lazy 装配；
 // - lazy 双动态 import 组装（SDK 页面 + 模板 registry/authClient 单例注入——
 //   authClient 含模板选项，不经预览页自建）。
 const CARD_PREVIEW_PATH = '/_tbox/card-preview';
-const DevCardPreview = import.meta.env.DEV
+const DevCardPreview = import.meta.env.DEV || __TBOX_CARD_PREVIEW__
   ? lazy(async () => {
       const [{ CardPreviewPage }, { CARD_REGISTRY }, { authClient }] = await Promise.all([
         import('@tbox.cn/app-agent-sdk-client/client/card-preview'),
@@ -22,7 +24,7 @@ const DevCardPreview = import.meta.env.DEV
   : null;
 
 export default function App() {
-  if (import.meta.env.DEV && DevCardPreview && window.location.pathname === CARD_PREVIEW_PATH) {
+  if ((import.meta.env.DEV || __TBOX_CARD_PREVIEW__) && DevCardPreview && window.location.pathname === CARD_PREVIEW_PATH) {
     return (
       <Suspense fallback={<div>加载卡片预览…</div>}>
         <DevCardPreview />

package/apps/client/src/vite-env.d.ts

@@ -1,3 +1,6 @@
 /// <reference types="vite/client" />
 
 declare module 'postcss-pxtorem';
+
+// 卡片预览面三态编译常量（vite.config.ts define 注入；guard-dev-probe 断言声明在场）
+declare const __TBOX_CARD_PREVIEW__: boolean;

package/apps/client/vite.config.ts

@@ -45,6 +45,12 @@ export default defineConfig(async ({ command }) => {
       }),
       ...devPlugins,
     ],
+    // 卡片预览面三态（方案 W）：serve 恒 false（dev 面由 import.meta.env.DEV 放行）；
+    // build 无 TBOX_DEV_TOKEN → false（chunk 可摇除，生产零残留）；build 有（沙箱 protected
+    // watch 构建）→ true（static 面 /_tbox/card-preview 可达）。guard-dev-probe 断言本标记。
+    define: {
+      __TBOX_CARD_PREVIEW__: command === 'build' && !!process.env.TBOX_DEV_TOKEN ? 'true' : 'false',
+    },
     resolve: {
       alias: {
         '@': resolve(__dirname, 'src'),

package/apps/server/src/dev.ts

@@ -2,92 +2,125 @@
  * vite dev 入口（仅 tsx 运行：pnpm dev；物理不进 tsup bundle——forbid-vite 插件拦截）。
  * middlewareMode + 单端口：HTTP 与 HMR WS 全走应用端口（沙箱仅暴露一个端口亦可开发）。
  * 部署形态一律走 dist/index.js（静态产物，零 HMR WS）。
+ *
+ * 方案 W（沙箱 dev server 鉴权保护）：TBOX_DEV_TOKEN 在场 → protected 双面裁决
+ * （dev 面 = 凭据 + 导航/同源信号放行 vite；static 面 = 纯 dist + SSE 刷新，零源码泄漏）；
+ * 缺席 → classic，与历史行为字节级等价。裁决机制真源 = SDK platform/dev-runtime
+ * （createTboxDevRuntime），本文件只做装配：vite 实例 + fs.allow 收窄 + 面无关自由区。
  */
 import { createServer } from 'http';
 import path from 'path';
-import { readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
 import { fileURLToPath } from 'url';
-import { createServer as createViteServer } from 'vite';
-import { injectScript, isReady } from '@tbox.cn/app-agent-sdk-server/platform';
+import { build as viteBuild, createServer as createViteServer, searchForWorkspaceRoot } from 'vite';
+import {
+  createTboxDevRuntime,
+  injectScript,
+  isReady,
+  resolveDevTokenFromEnv,
+} from '@tbox.cn/app-agent-sdk-server/platform';
 import { createLogger } from '@tbox.cn/app-agent-sdk-server';
 import { app, registerUpgradeDelegate, start } from './app.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const serverLogger = createLogger('server');
 const clientRoot = path.resolve(__dirname, '../../client');
+const appRoot = path.resolve(__dirname, '../..');
 
 // HMR WS 独立路径：dev 基础设施命名空间（双下划线呼应 /@vite/*），与业务命名空间（/ws*）
-// 解耦——delegate 只认领此路径，根路径归还业务路由。
+// 解耦——upgrade 认领只针对此路径，根路径归还业务路由。协议常量（vite-hmr/vite-ping）、
+// 认领路径 posix.join(base, hmr.path) 与 Spanner 子协议补写均内聚于 SDK handleUpgrade
+// （smoke-dev-hmr.sh 守护该契约面）。
 const HMR_WS_PATH = '/__vite_hmr';
 
-// HMR WS hub：永不 listen 的纯事件载体。hmr.server 在场 → vite 不自建 24678 独立端口，
-// 客户端 __HMR_PORT__=null → 按页面同源端口连接（公网端口映射无关）。vite 对 hub 仅
-// on/off('upgrade')（6.4.3 源码实证）；协议常量（vite-hmr/vite-ping）与认领路径
-// posix.join(base, hmr.path) 是 vite 契约面，由 scripts/smoke-dev-hmr.sh 守护。
+// HMR WS hub：永不 listen 的纯事件载体。hmr.server 在场 → vite 不自建独立端口，
+// 客户端按页面同源端口连接。vite 对 hub 仅 on/off('upgrade')（6.4.3 源码实证）。
 const hmrHub = createServer();
 
+const tokenState = resolveDevTokenFromEnv(process.env);
+const protectedMode = tokenState.mode === 'protected';
+
+// protected 面 fs.allow 收窄（classic 恒默认不传——红线）：client 源 + 工作区依赖真源。
+// 模板原地装配（pnpm dev）时模块图经 workspace 链接解析到仓库 packages/，故并入
+// workspace 两目录（filter(existsSync)：生成应用无此目录时自动滤除，不影响沙箱半径）。
+const workspaceRoot = searchForWorkspaceRoot(clientRoot);
+const fsAllowNarrowed = protectedMode
+  ? [
+      ...new Set(
+        [
+          clientRoot,
+          path.join(appRoot, 'packages'),
+          path.join(appRoot, 'node_modules'),
+          path.join(workspaceRoot, 'packages'),
+          path.join(workspaceRoot, 'node_modules'),
+        ].filter((p) => existsSync(p)),
+      ),
+    ]
+  : undefined;
+
 const vite = await createViteServer({
   root: clientRoot,
   server: {
     middlewareMode: true,
-    // 沙箱域名 Host 透传放行（dev-only；dist 物理不含 vite）。安全边界四条
-    // （cors() 既存全开 / 代理收敛公网入口 / token 轴不变 / /@fs 另有 deny）见 Agent Note 2026-09-09。
+    // 沙箱域名 Host 透传放行（dev-only；dist 物理不含 vite）。安全边界见 Agent Note
+    // 2026-09-09 与方案 W Note（protected 面 /@fs 另有 allow 收窄 + deny 现值保留）
     allowedHosts: true,
-    // /@fs 加固：默认 deny 不含服务端凭证目录（client 永不需要经 /@fs 读它）
-    fs: { deny: ['.env', '.env.*', '*.{crt,pem}', '**/.git/**', '**/config/credentials/**'] },
+    fs: {
+      ...(fsAllowNarrowed ? { allow: fsAllowNarrowed } : {}),
+      // /@fs 加固：默认 deny 不含服务端凭证目录（client 永不需要经 /@fs 读它）
+      deny: ['.env', '.env.*', '*.{crt,pem}', '**/.git/**', '**/config/credentials/**'],
+    },
     hmr: { server: hmrHub, path: HMR_WS_PATH },
   },
-  // custom：不加 Vite 自己的 SPA fallback，由下方 app.use('*') 统一处理 HTML 路由
+  // custom：不加 Vite 自己的 SPA fallback，HTML 路由由 runtime.final() 统一处理
   appType: 'custom',
 });
 
-// 升级委托：pathname === 认领路径（与 vite 同一 resolved config 同式 posix.join 派生——
-// 恒等无漂移，字面比较在未来设 base 时有悬挂方向：delegate 认领转发而 vite 不接，socket
-// 无人销毁）；协议轴 = 子协议补写 + 白名单（见下）。
-// 子协议补写（2026-09-21，详见 .agents/notes/implemented/bug-fix/
-// 2026-09-21-spanner-ws-subprotocol-strip-reload-loop.md）：Spanner 网关（*.coding.tboxpro.cn
-// 车道）把 WS 升级的 Sec-WebSocket-Protocol 视为 hop-by-hop 在下游拨号时剥除（2026-09-09
-// Terminal Note 同源实证：Authorization/Cookie/子协议均剥、query 唯一存活）。剥除后的拨号
-// 无协议头——原逻辑不认领 → 回落 app upgrade destroy → 网关报 "unexpected EOF"；WebKit
-// （Safari/iOS 支付宝·微信）宽松接受网关乐观 101（无协议回显），hmr WS open 即断 → vite
-// client vite:ws:disconnect → vite-ping 探测又被乐观 101 放行（成功判据 = open 事件，先于
-// 下游拨号结果）→ location.reload() 无限循环（Chrome/Blink 严格校验协议回显恒不 open，
-// 走静默分支免疫）。补写让下游握手成立：vite 101 带协议回显 + connected → 连接保持 →
-// 无 disconnect/ping/reload，WebKit 下 HMR 恢复可用。补写在网关透传修复（agtchannel spec
-// 2026-09-21 close/握手头透传，1b）落地后自动退化为死分支——长留不移除（sync 覆盖 + DRM
-// 回滚场景防回归载体）。其余非 vite 协议值仍不认领（smoke ⑤⑥ 语义不变）。
-// 未认领的升级回落 app 路由（业务 /ws、根路径归还业务、fail-fast 语义不变）。
-const viteHmrPath = path.posix.join(vite.config.base, HMR_WS_PATH);
-registerUpgradeDelegate((request, socket, head) => {
-  const { pathname } = new URL(request.url || '/', 'http://localhost');
-  if (pathname !== viteHmrPath) return false;
-  const protocol = request.headers['sec-websocket-protocol'];
-  if (!protocol) {
-    request.headers['sec-websocket-protocol'] = 'vite-hmr';
-  } else if (protocol !== 'vite-hmr' && protocol !== 'vite-ping') {
-    return false;
-  }
-  hmrHub.emit('upgrade', request, socket, head);
-  return true;
+const runtime = createTboxDevRuntime({
+  vite: { middlewares: vite.middlewares, transformIndexHtml: vite.transformIndexHtml },
+  hmrHub,
+  // 与 vite 同一 resolved config 同式 posix.join 派生——恒等无漂移
+  hmrPath: path.posix.join(vite.config.base, HMR_WS_PATH),
+  tokenState,
+  clientRoot,
+  clientDist: path.join(clientRoot, 'dist'),
+  spaExcludePrefixes: ['/api', '/ws'],
+  decorateHtml: (html) => (isReady() ? injectScript(html) : html),
+  logger: serverLogger,
+  fsAllowNarrowed: protectedMode,
+  sseKeepaliveMs: process.env.TBOX_DEV_SSE_KEEPALIVE_MS ? Number(process.env.TBOX_DEV_SSE_KEEPALIVE_MS) : undefined,
 });
 
-// Vite 中间件：静态资源、模块转换、HMR（装配已在 ./app.js import 期完成）
-app.use(vite.middlewares);
+// 面裁决：dev 面 → vite middlewares；static 面 → next()（落 final 的 dist 静态）
+app.use(runtime.gate);
 
-// HTML 路由兜底：非 /api、/ws 一律返回 index.html（经 Vite 转换 + inspector 注入）
-app.use('*', async (req, res, next) => {
-  if (req.originalUrl.startsWith('/api') || req.originalUrl.startsWith('/ws')) {
-    return next();
-  }
-  try {
-    const rawHtml = await readFile(path.join(clientRoot, 'index.html'), 'utf-8');
-    const template = await vite.transformIndexHtml(req.originalUrl, rawHtml);
-    const html = isReady() ? injectScript(template) : template;
-    res.status(200).set({ 'Content-Type': 'text/html' }).end(html);
-  } catch (e) {
-    next(e);
-  }
+// ── 自由区（模板差异 + 应用自定义 middleware；dev/static 两面恒可见）──
+// 探针路由：smoke-dev-protected.sh ⑩ 断言两面可见性（dev 基础设施，dist 物理不含）
+app.get('/__tbox_dev_freezone_probe', (_req, res) => {
+  res.type('text/plain').send('freezone-ok');
 });
+// ── 自由区结束 ──
+
+app.use(runtime.final);
+
+// 升级委托：唯一 WS 入口 = runtime.handleUpgrade（路径认领 + 子协议补写 + protected
+// token 校验，失败 401；未认领回落 app 路由——业务 /ws、根路径、fail-fast 语义不变）
+registerUpgradeDelegate(runtime.handleUpgrade);
+
+// protected 面构建通知：watch 增量构建 → BUNDLE_END → SSE 广播 → static 面 reload。
+// fire-and-forget（不 await、无显式 close——dev 会话生命周期即进程生命周期）；
+// watch 启动 emptyOutDir 清空 dist 为已定价行为（首建完成前 static 面纯 404）。
+if (protectedMode) {
+  viteBuild({ root: clientRoot, build: { watch: {}, sourcemap: false } })
+    .then((result) => {
+      const watcher = Array.isArray(result) ? result[0] : result;
+      if (!watcher || !('on' in watcher)) return;
+      watcher.on('event', (e) => {
+        if (e.code === 'BUNDLE_END') runtime.notifyBuildEnd();
+      });
+    })
+    .catch((err) => serverLogger.error('[dev] watch build failed:', err));
+}
 
 start().catch((err) => {
   serverLogger.error('Failed to start:', err);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tbox.cn/app-template-agent",
-  "version": "0.10.8",
+  "version": "0.10.9",
   "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"
@@ -36,7 +36,7 @@
     "typescript-eslint": "8.67.0",
     "eslint-plugin-react-hooks": "5.2.0",
     "vite": "6.4.3",
-    "@tbox.cn/app-sdk-server": "0.21.2"
+    "@tbox.cn/app-sdk-server": "0.22.0"
   },
   "license": "MIT",
   "publishConfig": {

package/pnpm-lock.template.yaml

@@ -28,8 +28,8 @@ catalogs:
       specifier: 0.12.4
       version: 0.12.4
     '@tbox.cn/app-sdk-server':
-      specifier: 0.21.2
-      version: 0.21.2
+      specifier: 0.22.0
+      version: 0.22.0
     '@tbox.cn/app-theme-tbox':
       specifier: 0.1.3
       version: 0.1.3
@@ -115,7 +115,7 @@ importers:
     devDependencies:
       '@tbox.cn/app-sdk-server':
         specifier: 'catalog:'
-        version: 0.21.2
+        version: 0.22.0
       eslint:
         specifier: 'catalog:'
         version: 9.39.5
@@ -1380,8 +1380,8 @@ packages:
     engines: {node: '>=20.0.0'}
     hasBin: true
 
-  '@tbox.cn/app-sdk-server@0.21.2':
-    resolution: {integrity: sha512-nqBBakAsHjGvG5eO8OLWoC0TTbBFTorrCWZRFLiyKhxHV2OnVThvIZWXTeu08UMBh5se9NFhRfYZxldtAvIwbQ==}
+  '@tbox.cn/app-sdk-server@0.22.0':
+    resolution: {integrity: sha512-St5cP43/y/pH/s6ubXX44Rf0wmysL19tZRvTWSUV/0EmO7ouoRmtTzsWHe+XnqkcUnRgfSYm/evRse+K9ATNhg==}
     engines: {node: '>=20.0.0'}
     hasBin: true
 
@@ -1392,6 +1392,10 @@ packages:
     resolution: {integrity: sha512-bvq5l7rwwX3EJe0hQm4dnwSh0tuDmoucCkCfX306PvNbhSv0H9uHSljg/jeXh08DBtc2gjIJyvPsfDxrv5X6Uw==}
     engines: {node: '>=20.0.0'}
 
+  '@tbox.cn/app-toolkit@0.7.3':
+    resolution: {integrity: sha512-Tdh1XkqRX0DGvTxflrfgJ4WFVW5wiq9cGOd7hpFrGzQ95mXFiSUKyQMgMtIum8kbReUq+aPI5hv8Z87AugZ1yQ==}
+    engines: {node: '>=20.0.0'}
+
   '@types/babel__core@7.20.5':
     resolution: {integrity: sha512-qoQprZvz5wQFJwMDqeseRXWv3rqMvhgpbXFfVyWhbx9X47POIA6i/+dXefEmZKoAgOaTdaIgNSMqMIU61yRyzA==}
 
@@ -4184,12 +4188,12 @@ snapshots:
     transitivePeerDependencies:
       - supports-color
 
-  '@tbox.cn/app-sdk-server@0.21.2':
+  '@tbox.cn/app-sdk-server@0.22.0':
     dependencies:
       '@ag-ui/core': 0.0.47
       '@tbox.cn/app-contracts': 0.12.3
       '@tbox.cn/app-sdk-core': 0.20.2
-      '@tbox.cn/app-toolkit': 0.7.2
+      '@tbox.cn/app-toolkit': 0.7.3
       express: 4.22.2
       jose: 6.2.8
       zod: 3.25.76
@@ -4203,6 +4207,11 @@ snapshots:
       ajv: 8.20.0
       zod: 3.25.76
 
+  '@tbox.cn/app-toolkit@0.7.3':
+    dependencies:
+      ajv: 8.20.0
+      zod: 3.25.76
+
   '@types/babel__core@7.20.5':
     dependencies:
       '@babel/parser': 7.29.8

package/pnpm-workspace.template.yaml

@@ -40,7 +40,7 @@ catalog:
   "@tbox.cn/agent-plugin": 0.1.0
   "@tbox.cn/app-sdk-core": 0.20.2
   "@tbox.cn/app-sdk-client": 0.21.1
-  "@tbox.cn/app-sdk-server": 0.21.2
+  "@tbox.cn/app-sdk-server": 0.22.0
   "@tbox.cn/app-agent-sdk-server": 0.1.4
   "@tbox.cn/app-agent-sdk-client": 0.1.3
   "@tbox.cn/app-contracts": 0.12.3