@tbox.cn/app-template-agent 0.8.0 → 0.10.0

package/AGENTS.md

@@ -1,15 +1,6 @@
 # AGENTS.md
 
-template-agent 是多包 pnpm workspace：`apps/` 薄组装端 + `packages/` 模块。客户端同时运行在浏览器和支付宝小程序 web-view 壳中。
-
-> **唯一模板（W4 单一模板统一化）**：缺省出厂 = 空装配（chat 形态）；商圈形态经 `profiles/mall.json` 画像加装
-> （`tbox-app create --profile mall`：mall-core/mall-home + 六业务模块 + config 叠加）。历史 base/mall 双生约定退役。
-
-> **工作区上下文（发布态消费，005 v0.4.0）**：仓库内本目录是**根 workspace 成员子树**（无独立 `pnpm-workspace.yaml`），
-> 平台引用 `catalog:` + 根 `pnpm-workspace.yaml` `overrides: workspace:*` 回指根 `packages/` 真源；`pnpm` 命令在根上下文执行。
-> `tbox-app create` 从模板源（目录或 pack tgz）展开生成应用——**不拼接平台真源**：生成应用 `packages/` 仅业务/local 模块，
-> 平台包以 `catalog:` 引用，验证态经注入 overrides（`file:` 本地 tgz）、生产态经 registry 安装；`pnpm-workspace.yaml` 由
-> `pnpm-workspace.template.yaml` 改名生成。
+本应用是多包 pnpm workspace：`apps/` 薄组装端 + `packages/` 模块。客户端同时运行在浏览器和支付宝小程序 web-view 壳中；缺省为空装配（chat 形态），商圈形态为创建期 `--profile mall` 画像加装产物（应用内以已装模块为准）。
 
 ## 工程结构
 
@@ -17,10 +8,8 @@ template-agent 是多包 pnpm workspace：`apps/` 薄组装端 + `packages/` 模
 |---|---|
 | `apps/server` | Express + WS 装配入口，HTTP 路由，TTS 代理；业务工具/卡片由模块自注册（自注册闭环） |
 | `apps/client` | React/Vite 装配入口，业务页面/组件/adapters/bridge（家页 MallHome 由 mall-home 模块经 home 槽供给） |
-| `packages/` | 模块目录（空装配起点：`tbox-app module add` 生成 `@app/<id>` 成员；根 workspace 内平台真源在根 `packages/`） |
-
-> **画像供能（017 家族）**：mall 形态 = profiles/mall.json 声明的模块序列（mall-core 域装配 + mall-home 家页 + 六业务模块）
-> + profiles/mall/config 叠加；公共能力（协议/机制/配置链）沉淀 SDK/CLI——新增通用能力先落 SDK/kit 再被模板/模块消费。
+| `packages/` | 模块目录（`tbox-app new module <name>` 或 `module add` 生成 `@app/<id>` 成员；出厂预装 `provider-custom`（自定义 API 实施落点）、`agent-ui-kit`（组件库）与 `contracts-mall` shim） |
+| `profiles/` | 创建期画像（`--profile` 加装计划；应用内不再消费，可忽略） |
 
 ## 模块开发（双端自注册闭环，逐行同构）
 
@@ -60,29 +49,95 @@ apps/client/src/cards/registry.ts             # 卡片注册表快照（CardType
 apps/server/src/index.ts                      # 服务端入口（HTTP + WS + Vite middleware + createServerContext + createEngineFromContext）
 apps/server/src/modules.ts                    # 服务端模块装配（registerAll）
 apps/server/src/module-ports.ts               # 模块 ports 动态装配（LinkedPanel/bumpin 数据源；契约派生 + 漂移守卫）
-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（出卡 capture 在 engine 构造期包装，见 tool-cards.ts）
-packages/app-sdk/src/client/chat-store.ts     # ChatStore 工厂
-packages/contracts/src/                       # 跨端类型契约
+packages/provider-custom/src/server/index.ts  # 自定义 API adapter 实施落点（步骤见该包 AGENTS.md）
 config/                                       # chat/model/plugin 配置
 ```
 
-## 常用命令
+## 运行与验证（平台沙箱）
+
+应用构建与运行在平台沙箱中，启动/停止/重启由平台负责——不要运行 `pnpm dev`、`pnpm start`
+等长驻进程命令（沙箱规则 `config/rules/no-persistent-process.md`）；`scripts/` 下生命周期
+脚本（prepare/dev/start/stop/build）同样由平台调用。你只改代码与配置，用一次性命令验证：
 
 ```sh
-pnpm install
-pnpm dev              # 单进程 localhost:8000（API + WS + 页面 + HMR）
+pnpm install                     # 会话开始时 node_modules 缺失先装
 pnpm typecheck
 pnpm test
 pnpm build
-pnpm verify           # typecheck + test + build + verify:generated
-pnpm verify:generated # 装配一致 + 锚点完整 + 无裸露 import
-pnpm plugin:doctor
+pnpm verify                      # typecheck + test + lint + build + verify:generated + check:inspector
+pnpm verify:generated            # 装配一致 + 锚点完整 + 无裸露 import
+pnpm plugin:doctor               # 插件排障
 pnpm plugin:inspect <pluginId> <toolId>
 ```
 
-starter 文档：`tbox-app starter --type agent-mall`；可用类型：`tbox-app starter --list`。在沙箱中使用 `tbox-app create . --name <app-name> --source @tbox.cn/app-template-agent --profile mall` 原地初始化（缺省不带 --profile = 空装配 chat 形态），应用模板的 `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 安装）。
+环境变量与配置面（`config/`）见 `ENV.md`。
+
+## tbox-app CLI（模块与装配管理）
+
+CLI 免安装，命令均经 `npx --yes @tbox.cn/app-cli <cmd>` 运行（下表简写 `tbox-app`；完整
+命令面 `tbox-app --help`）。add/remove/sync 后需 `pnpm install`：
+
+| 命令 | 用途 |
+|---|---|
+| `module add <pkg> --mode codegen --source <pkg\|路径\|tgz>` | 安装模块（codegen 展开 / local 本地目录 / sdk registry 安装） |
+| `module remove <id>` | 卸载模块（见「删除模块」） |
+| `module list` / `sync` / `diff` / `doctor` | 已装清单 / 增量装配 / 漂移对比 / 结构校验 |
+| `module update <module>` | 升级模块（codegen → 3-way merge） |
+| `new <module\|provider\|theme> <name>` | 应用内脚手架（生成 `packages/<id>` 并完成装配） |
+| `provider use / bind / unbind / unuse` | 集成绑定（写 `config/integrations.json`；仅字符串厂商——自定义 API 声明直接编辑该文件；bind/use 整槽覆盖既有 provider，含内联声明） |
+| `theme use <id>` / `theme list` | 主题接线 / 状态 |
+| `starter --list` / `starter --type <type>` | starter 文档查询（商圈模块清单见 `--type agent-mall`） |
+
+## 自定义服务集成（provider-custom）
+
+自定义 API = 服务的真实后端由你自己对接：声明住在 `config/integrations.json`，adapter
+代码住在 `packages/provider-custom/`。服务后端三选一：Mock（演示数据，装 provider-mock
+即用）/ 自定义 API（你自己的后端接口——本节流程）/ 服务商集成（官方 provider 包，
+`module add` + `provider bind`）。收到「为某服务/模块/应用接入自定义 API」（或「对接
+我的 API」等同义说法）的请求时按四步走：
+
+1. **说明并收集信息**：目标不在已装模块服务槽词汇内 → 说明未装该模块，引导
+   `module add` 或 `new module`，不进入后续步骤。在词汇内 → 简要说明目标——服务 = 槽
+   展示名与描述 + Port 能力（消费模块 `src/server/ports.ts`（或 `ports/` 目录）或
+   `@app/contracts-mall`）；模块 = `tbox.module.json` `declare.owns` 清单逐个一句
+   （`*.snapshot` 聚合槽在清单内，数据随底层服务派生——落声明时跳过）；应用 = 已装业务模块服务清单概览
+   （空装配 chat 形态无业务服务，不适用）。再向用户收集：API 地址、认证方式（密钥值经
+   平台凭据引用，不进 prompt/代码/配置明文）、可选连接参数。用户已给出的不重复问。
+   未实施前调用报 `PROVIDER_NOT_IMPLEMENTED` 属预期中间态。
+2. **落声明**：目标槽已有内联声明则跳过；否则直接编辑 `config/integrations.json`
+   （CLI provider 命令仅支持字符串厂商）按下表范围写入槽级声明（`{ provider,
+   credentialType, configSchema? }` + implementation 字面量，仅槽级合法；provider 名自定
+   语义化短标识，同一后端的多服务共用同一 provider 名——单键注册，见
+   `packages/provider-custom/AGENTS.md`；凭据接线见同文件）：
+
+   | 维度 | 声明范围 | 共享连接参数落点 |
+   |---|---|---|
+   | 指定服务 | `services.<slot>` 单槽 | 槽/实例级 `config` |
+   | 指定模块 | 模块 `declare.owns` 全部服务槽（snapshot 除外） | `modules[<install id>].config` |
+   | 应用 | 已装业务模块 owns 并集（空装配不适用） | root `config` |
+
+3. **实施 adapter**：按 `packages/provider-custom/AGENTS.md` 实施（注册键 implementation
+   段 = `'inline'`）。
+4. **验收**：`pnpm typecheck && pnpm build` 通过 + `npx --yes @tbox.cn/app-cli module
+   doctor`；平台重启后该服务的调用不再报 `PROVIDER_NOT_IMPLEMENTED`（resolveService
+   惰性——调用时观测；doctor 对通配槽凭据不设防，运行时判据为最终裁判）。
+
+## 删除模块
+
+模块装卸一律走 CLI——不要手动删 `packages/<id>` 目录或改装配锚点区：
+
+```sh
+npx --yes @tbox.cn/app-cli module list      # 确认模块 id（= packages/ 目录名）
+npx --yes @tbox.cn/app-cli module remove <id>
+pnpm install
+```
+
+- `remove` 自动完成：删包（或恢复 `contracts-mall` SDK shim）+ 清锚点装配 + 清理集成绑定
+  死项 + doctor 复查。
+- 被其他模块 required 依赖时会阻止并列出依赖方：先删依赖方；`--force` 仅确认知情时使用。
+- 删除后跑 `pnpm typecheck`：`CardType` 随装配自动收缩，残留消费方会编译报错——按报错
+  清理引用后 `pnpm verify` 收尾。
+- 提示「contracts-mall 已无依赖者」时可再 `module remove contracts-mall` 恢复 SDK shim。
 
 ## 平台基础设施
 
@@ -96,17 +151,17 @@ starter 文档：`tbox-app starter --type agent-mall`；可用类型：`tbox-app
 
 ## 双运行时与插件
 
-- 原生能力统一走 `@tbox.cn/app-sdk/client` 的 `createPlatformAdapters()`（ASR/TTS/upload/feedback；007 下沉）；业务/UI 不直接判断支付宝壳。
-- API/WS 地址由 `@tbox.cn/app-sdk/client` 的 `configureRuntime({ apiBaseUrl })` 注入（`main.tsx`），不得硬编码 host；不直接读 `import.meta.env` 之外的环境（H1）。
+- 原生能力统一走 `@tbox.cn/app-sdk/client` 的 `createPlatformAdapters()`（ASR/TTS/upload/feedback）；业务/UI 不直接判断支付宝壳。
+- API/WS 地址由 `@tbox.cn/app-sdk/client` 的 `configureRuntime({ apiBaseUrl })` 注入（`main.tsx`），不得硬编码 host；不直接读 `import.meta.env` 之外的环境。
 - **不直接 import `@tbox-dev-js/sdk`（全禁）**——平台能力（auth/会话/TTS/LLM/插件/能力适配器/协议客户端）一律经 `@tbox.cn/app-sdk` 公开 API。
 - 平台"插件"页添加插件时只改 `config/plugins.json`。应用代码不复制插件鉴权、参数注入、runtime ID 或 SDK 客户端。
-- 插件结果出卡时按 `packages/contracts/src/cards.ts` 注册 schema，在模块包内注册 adapter 和 client 组件。
+- 插件结果出卡时按 `@tbox.cn/app-contracts` 的 cards schema 注册，在模块包内注册 adapter 和 client 组件。
 
-## web-view 样式约定（014，POC 沉淀）
+## web-view 样式约定
 
 客户端同时跑浏览器与支付宝小程序 web-view 壳（组件挂载于 H5 视口，非小程序原生渲染），样式遵守：
 
-0. **视觉体系 = mall-vis 蓝系**（视觉真源：仓库 `docs/reference/templates.md`——换肤面四级级联/域色矩阵 member 金 · parking 藏蓝 · sg 蓝 · promotion 红/UI 模式）；视觉值只住 kit tokens / 模块域变量块 / 素材变量消费三层（品牌视觉经主题包覆写——出厂接线 `@tbox.cn/app-theme-tbox` 三行，见 `apps/client/src/main.tsx`），平台 token 名字零增减。
+0. **视觉体系 = mall-vis 蓝系**（换肤面四级级联；域色矩阵 member 金 · parking 藏蓝 · sg 蓝 · promotion 红/UI 模式）；视觉值只住 kit tokens / 模块域变量块 / 素材变量消费三层（品牌视觉经主题包覆写——出厂接线 `@tbox.cn/app-theme-tbox` 三行，见 `apps/client/src/main.tsx`），平台 token 名字零增减。
 1. **长度单位 PX 大写**（如 `800PX`）——web-view 内联字体放大：小写 `px` 被浏览器 rem 缩放改写，大写跳过改写保持视觉尺寸。
 2. **flex 子项设 `flex-shrink: 0`**——壳内内容宽度不定，防元素被压缩变形。
 3. **滚动容器隐藏滚动条**（`::-webkit-scrollbar { display: none }`）——web-view 无原生滚动条，出现即破相。
@@ -115,6 +170,6 @@ starter 文档：`tbox-app starter --type agent-mall`；可用类型：`tbox-app
 ## 工程边界（check-workspace 校验）
 
 - `packages/*` 业务包必须有 `tbox.module.json`；SDK/契约（`app-sdk` / `contracts*` / `shared`）豁免。
-- `scripts/` 下所有文件保持可执行位（git 100755；CLI create 后 chmod 兜底）；双模板 scripts 文件集合镜像全等（guard-workspace R4）。
+- `scripts/` 下所有文件保持可执行位（git 100755；CLI create 后 chmod 兜底）。
 - 装配文件不得裸 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` 已占此位）。
+- 构建序列单源 = 根 `build` / `build:client` script；`scripts/build.sh` 只管环境 + install + 委托（平台调用）。

package/ENV.md

@@ -6,9 +6,9 @@
 
 - **本地开发**:shell export 注入(每次新终端需重新执行;见文末命令块)。生成应用请直接 shell export 或平台配置。
 - **生产**:建议在 tbox 平台页面上配置环境变量(平台托管 env,密钥不进代码仓库、不进 git)。
-  生产部署必须 `NODE_ENV=production`(dev-login 强制关闭 + JWT 密钥链 fail-fast 的依据)。
+  生产部署必须 `NODE_ENV=production`(JWT 密钥链 fail-fast + real hardening 的依据)。
   入口分离后 dist 恒静态供给(vite dev 仅存在于源码 `src/dev.ts` 本地开发入口);`NODE_ENV` 不再决定
-  客户端供给形态——测试环境可用 `node dist/index.js`(不设 NODE_ENV)获得「静态产物 + dev-login」。
+  客户端供给形态——测试环境可用 `node dist/index.js`(不设 NODE_ENV)获得「静态产物 + 开发档登录语义」。
 - 以下变量缺失时服务可启动,但对话/会话/上传链路会 503。
 
 ## 默认商圈（integrations v4）
@@ -23,8 +23,9 @@
     无 `instances` 键 = 无参考表（动态形态）；env 未注入 → 占位 fail-fast 显性暴露。
 - 注入形态：mallId-only（miniAppId 尽力回填——root config `miniAppId` 优先、参考表
   attributes 兜底；双缺仍注入，不阻断默认商圈）。URL 显式参数 `?mallId=` 优先级更高。
-- 本地 mock 链：`tbox-app module add` 装 provider-mock → 生成器派生零拓扑 integrations.json →
-  裸跑免 mallId 全局会话或任意 `?mallId=` 均可演示。零拓扑形态下 provider-mock 于 register 期
+- 本地 mock 链：`tbox-app module add` 装 provider-mock（0.5.0 极简零配置——开箱免集成配置；
+  动态配置验证面 → provider-mocktest，内部档 `pnpm dev mall-mocktest`）→ 生成器派生零拓扑
+  integrations.json → 裸跑免 mallId 全局会话或任意 `?mallId=` 均可演示。零拓扑形态下 provider-mock 于 register 期
   声明隐式默认单实例（mall-demo / 星河 Mock 小镇）——无 URL 参数访问时默认商圈回显照常生效
   （显式 instances/defaultInstanceId 恒赢，声明仅兜底）。
 
@@ -58,7 +59,7 @@ dev/src 与 prod/dist bundle 形态恒等）：
   provider+implementation 从最特异层整组继承（instance > slot > domain > root），组内
   implementation 缺席经 catalog 派生；部署拓扑 = 顶层 `instances` 注册表 + `defaultInstanceId`；
   槽 `instances` 键缺席 = 通配激活）。模板不内置——`tbox-app module add` 装入 local 供给
-  （provider-mock）时由 CLI mock 绑定生成器自动派生零拓扑形态（root.provider + 全 local 槽
+  （provider-mock / provider-mocktest——local 供给双包同语义）时由 CLI mock 绑定生成器自动派生零拓扑形态（root.provider + 全 local 槽
   空对象）；真厂商绑定经 `tbox-app provider use/bind` 或 `--config-dir` 真实素材注入。
 - `config/integrations.json` 顶层 `modules` 节：模块资源绑定（键 = 模块 install id，如
   `module-customer-service`；`resources.<resourceId> = { type: 'knowledge', datasetId | ref, topK?, scoreThreshold? }`）。
@@ -115,13 +116,12 @@ dev/src 与 prod/dist bundle 形态恒等）：
 | `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 字节随机串),生产由平台注入。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(默认 `agent`；如需 mall 独立身份可显式设 `agent-mall`) |
 | `AUTH_EMBED_EXTERNAL_TOKEN` | 是否把外部原始 token 内嵌进自有 JWT(external claim,默认 `true`;`false` 则上游调用需另取) |
@@ -144,7 +144,7 @@ dev/src 与 prod/dist bundle 形态恒等）：
   (上游 Token 寿命未知;自有 JWT 过期即重登换新)。
 - ⚠️ 与 `VITE_AUTH_PROVIDER=external` **互斥**:设 external 走 `AUTH_EXTERNAL_*` HMAC 转发旁路,
   换码器被 platform 路由绕过,两者勿同时启用。
-- 裸跑(无登录槽配置):无换码器注册 → 内置 alipay(未配 → 503)或 dev-login,匿名降级属预期行为。
+- 裸跑(无登录槽配置):无换码器注册 → 内置 alipay(未配 → 503)或 browser 轴 guest(内置换码器 allowsGuestLogin),匿名降级属预期行为。
 - 跨 mall 切换(URL `mallId` 变更)由 SDK `scopeKey` 守卫自动清 token 重登,无需手工登出。
 
 ## 客户端(Vite 注入)
@@ -189,7 +189,7 @@ export MALL_HOME_DEV_SERVICES=true
 
 # tbox-app dev 配置面
 
-- `TBOX_CONFIG_DIR`：dev 命令注入的配置目录覆盖（real-env 档位绝对路径）；未设时使用默认 `config/`。
+- `TBOX_CONFIG_DIR`：dev 命令注入的配置目录覆盖（preset `configDir` / `--config-dir` 旗标显式指定的目录绝对路径——config 恒显式）；未设时使用默认 `config/`。
   覆盖面含 `llm_provider.json`（`modelName`/`thinking`）：注入时 LLM 装配读档位目录文件，
   其 `modelName` 优先于 `APP_AI_MODEL_NAME`；档目录缺该文件 → 链式回退 env（config-dir 独占
   注入语义：缺文件 = 显式不指定，不落回模板默认 config）。

package/README.md

@@ -35,15 +35,16 @@ tbox-app module doctor               # 26 条结构校验
 > 依赖链说明（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 测试登录，开箱即用）；
-> 生产部署必须 `NODE_ENV=production`（dev-login 强制关闭）。非生产环境如需关闭设
-> `AUTH_DEV_LOGIN_DISABLED=true`。
+> 🔐 鉴权（统一登录）：登录面 = `POST /api/auth/login`（`method:'code'|'browser'` 判别）；
+> 浏览器档位（guest/mock/off/auto）经换码器 `browserLoginMode` 能力口治理（登录槽 config，
+> 支持 `${VAR:-default}` 展开经 env 分档）；生产部署必须 `NODE_ENV=production`。
 
 ## 工程结构
 
 ```text
 template-agent/
-  profiles/                  模板画像（mall.json 加装计划 + config 叠加；create --profile 消费）
+  profiles/                  模板画像（mall.json 加装计划 + config 叠加 + rootFiles 根文件 TEMPLATE.md；
+                                create --profile 消费——根文件落地应用根）
   apps/
     client/                    React/Vite 装配端（业务页面/组件/hooks/样式；平台能力经 @tbox.cn/app-sdk/client）
     server/                    Express + WS 装配端（~120 行装配：auth 中间件 + 模块挂载 + 平台路由面/TTS/WS）
@@ -175,7 +176,7 @@ definePreTool(findStoreTool, {
 | `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`）；**应用级单例**——重复调用幂等返回首建实例，首建选项生效 |
+| `createAuthClient({ loginPlatform, scopeKey })` | `@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`） |
 | bridge 透传 | `@tbox.cn/app-sdk/client` 的 `callJsapi` | 业务新能力（扫码/导航/分享等，壳子补 JSAPI 白名单） |
 

package/apps/client/index.html

@@ -26,8 +26,8 @@
         window.addEventListener('orientationchange', setRootFontSize);
       })();
     </script>
-    <!-- 品牌标题真源 = 主题包 brand.js（出厂 theme-tbox 同值兜底；换主题随 brand.js 覆盖，此处不做品牌配置锚） -->
-    <title>商圈搭子</title>
+    <!-- 出厂标题 = 此处静态值（theme-tbox brand.js 出厂不覆写标题）；租户主题经其 brand.js 运行时覆写 document.title -->
+    <title>AI 助手</title>
     <!-- 平台微调(inspector) runtime：由 server 提供 GET /__vs_inspector__.js；dev 下经 Vite 代理到 server。-->
     <script src="/__vs_inspector__.js" defer></script>
   </head>

package/apps/client/package.json

@@ -11,7 +11,6 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@tbox.cn/app-sdk": "catalog:",
     "@tbox.cn/app-contracts": "catalog:",
     "@tbox.cn/app-theme-tbox": "catalog:",
     "react": "catalog:",
@@ -19,7 +18,8 @@
     "zustand": "catalog:",
     "@app/provider-custom": "workspace:*",
     "@app/agent-ui-kit": "workspace:*",
-    "@app/contracts-mall": "workspace:*"
+    "@app/contracts-mall": "workspace:*",
+    "@tbox.cn/app-agent-sdk-client": "catalog:"
   },
   "devDependencies": {
     "@types/node": "catalog:",

package/apps/client/src/app.tsx

@@ -11,7 +11,7 @@ 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('@tbox.cn/app-agent-sdk-client/client/card-preview'),
         import('@/cards/registry'),
         import('@/platform/agent-runtime'),
       ]);

package/apps/client/src/cards/registry.ts

@@ -11,7 +11,7 @@
  * - CLIENT_SLOTS = 槽注册表（home 槽由模块注册）。
  */
 import type { CardComponent, TboxCardPayload } from '@tbox.cn/app-contracts';
-import { createClientContext } from '@tbox.cn/app-sdk/client';
+import { createClientContext } from '@tbox.cn/app-agent-sdk-client';
 import { registerAll, type CardType } from '../modules';
 
 /** 组装端单例：注册全部模块客户端能力（模块加载期执行一次；注册幂等告警） */

package/apps/client/src/main.tsx

@@ -1,6 +1,6 @@
 import { StrictMode } from 'react';
 import { createRoot } from 'react-dom/client';
-import { configureRuntime, createLogger, installGlobalErrorReporting } from '@tbox.cn/app-sdk/client';
+import { configureRuntime, createLogger, installGlobalErrorReporting } from '@tbox.cn/app-agent-sdk-client';
 import App from './app';
 import { configureChatConfigDefaults } from '@app/agent-ui-kit';
 import '@app/agent-ui-kit/theme/global.less';

package/apps/client/src/modules.ts

@@ -5,7 +5,7 @@
  * 锚点区：@tbox:imports-begin/end（模块 import 行）+ @tbox:register-begin/end（模块数组）
  * CLI 行为：增量插入/删除模块行，保留非标行。
  */
-import type { ClientContext, InferModuleCards } from '@tbox.cn/app-sdk/client';
+import type { ClientContext, InferModuleCards } from '@tbox.cn/app-agent-sdk-client';
 
 // @tbox:imports-begin
 // 其余能力经 `tbox-app module add` 扩展（shopping-guide/member 等商圈模块；mall-home 经 profiles/mall）

package/apps/client/src/platform/AgentChatApp.tsx

@@ -1,9 +1,9 @@
-import { createLogger } from '@tbox.cn/app-sdk/client';
+import { createLogger } from '@tbox.cn/app-agent-sdk-client';
 
 const appLogger = createLogger('AgentChatApp');
 
 import { useCallback, useEffect, useMemo, useState } from 'react';
-import { AdapterProvider, createPlatformAdapters, type AdapterContextValue } from '@tbox.cn/app-sdk/client';
+import { AdapterProvider, createPlatformAdapters, type AdapterContextValue } from '@tbox.cn/app-agent-sdk-client';
 import type { TboxSessionData } from '@tbox.cn/app-contracts';
 import IndexPage from '@/pages/index/index';
 import { authClient, platformApi } from './agent-runtime';
@@ -17,15 +17,16 @@ export default function AgentChatApp() {
   useEffect(() => {
     authClient
       .ensureAuth()
-      .then((auth) => platformApi.getTboxSession(auth.identity.userId))
+      // 会话 β 收口：身份恒取 token（服务端 401/403），userId 不再上行
+      .then(() => platformApi.getTboxSession())
       .then(setSession)
       .catch((err) => appLogger.error('tbox session init failed:', err));
   }, []);
 
   const refreshSession = useCallback(async (): Promise<AdapterContextValue> => {
     platformApi.clearTboxSession();
-    const auth = await authClient.refreshAuth();
-    const data = await platformApi.getTboxSession(auth.identity.userId, true);
+    await authClient.refreshAuth();
+    const data = await platformApi.getTboxSession(true);
     setSession(data);
     return { tts, ...createPlatformAdapters(data, { tts }), refreshSession };
   }, [tts]);

package/apps/client/src/platform/agent-runtime.ts

@@ -1,9 +1,9 @@
 /**
- * 平台运行时装配（client 平台轴，已下沉 @tbox.cn/app-sdk/client）。
+ * 平台运行时装配（client 平台轴，已下沉 @tbox.cn/app-agent-sdk-client）。
  * 模板唯一的 SDK 单例持有点：authClient（鉴权）+ platformApi（能力凭证/会话/历史）。
  * 环境值（VITE_API_URL / VITE_AUTH_PROVIDER）由 main.tsx 经 configureRuntime / 选项注入（H1）。
  */
-import { createAuthClient, createPlatformApi } from '@tbox.cn/app-sdk/client';
+import { createAuthClient, createPlatformApi } from '@tbox.cn/app-agent-sdk-client';
 // 读源归位 TIER1（W1-①）：mall-scope-url 契约助手（search-only 语义；壳 URL 改写层契约见包注释）
 import { readMallIdFromUrl } from '@app/contracts-mall';
 

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

@@ -10,8 +10,8 @@ import {
   getLocation,
   configureHelloContext,
   subscribeSessionUpgradeDrain,
-} from '@tbox.cn/app-sdk/client';
-import type { CoreChatState } from '@tbox.cn/app-sdk/client';
+} from '@tbox.cn/app-agent-sdk-client';
+import type { CoreChatState } from '@tbox.cn/app-agent-sdk-client';
 import { toast } from '@app/agent-ui-kit';
 import { readMallIdFromUrl, readMiniAppIdFromUrl } from '@app/contracts-mall';
 import { authClient, platformApi } from '@/platform/agent-runtime';

package/apps/client/vite.config.ts

@@ -7,7 +7,7 @@ import { resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
 // 平台微调配套 babel plugin（随 @tbox.cn/app-sdk 分发）：给每个 JSX 注入 data-code-inspect-*
 // 源码位置属性，供 inspector runtime(/__vs_inspector__.js) 点选元素→定位源码。仅 dev 启用（见下）。
-import codeInspectPlugin from '@tbox.cn/app-sdk/platform/code-inspect';
+import codeInspectPlugin from '@tbox.cn/app-agent-sdk-client/platform/code-inspect';
 
 const pxToRemPlugin = pxToRem({
   rootValue: 100,
@@ -48,8 +48,6 @@ export default defineConfig(async ({ command }) => {
     resolve: {
       alias: {
         '@': resolve(__dirname, 'src'),
-        fs: resolve(__dirname, 'src/shims/node-stub.ts'),
-        path: resolve(__dirname, 'src/shims/node-stub.ts'),
       },
       // dev 域 React 单实例（G1/G2 防线）：双 dev 入口经本文件合并生效（middleware
       // dev 加载本文件且 command==='serve'）；build 恒不继承——产物位稳定性。

package/apps/server/package.json

@@ -12,17 +12,15 @@
   },
   "dependencies": {
     "@tbox.cn/agent-plugin": "catalog:",
-    "@tbox.cn/app-sdk": "catalog:",
     "@tbox.cn/app-contracts": "catalog:",
     "@app/contracts-mall": "workspace:*",
     "@tbox-dev-js/sdk": "catalog:",
-    "cors": "catalog:",
     "express": "catalog:",
     "zod": "catalog:",
-    "@app/provider-custom": "workspace:*"
+    "@app/provider-custom": "workspace:*",
+    "@tbox.cn/app-agent-sdk-server": "catalog:"
   },
   "devDependencies": {
-    "@types/cors": "catalog:",
     "@types/express": "catalog:",
     "@types/node": "catalog:",
     "tsx": "catalog:",

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

@@ -1,4 +1,4 @@
-import type { ServerContext } from '@tbox.cn/app-sdk/server';
+import type { ServerContext } from '@tbox.cn/app-agent-sdk-server';
 import { translateTool } from './tools/translate.js';
 import { clockTool } from './tools/clock.js';