@tbox.cn/app-template-agent 0.10.20 → 0.10.22

package/AGENTS.md

@@ -8,12 +8,12 @@
 |---|---|
 | `apps/server` | Express + WS 装配入口，HTTP 路由，TTS 代理；业务工具/卡片由模块自注册（自注册闭环） |
 | `apps/client` | React/Vite 装配入口，业务页面/组件/adapters/bridge（家页 MallHome 由 mall-core 模块经 home 槽供给） |
-| `packages/` | 模块目录（`tbox-app new module <name>` 或 `module add` 生成 `@app/<id>` 成员；出厂预装 `provider-custom`（自定义 API 实施落点）、`agent-ui-kit`（组件库）与 `contracts-mall` shim） |
+| `packages/` | 模块目录（`npx --yes @tbox.cn/app-cli new module <name>` 或 `module add` 生成 `@app/<id>` 成员；出厂预装 `provider-custom`（自定义 API 实施落点）、`agent-ui-kit`（组件库）与 `contracts-mall` shim） |
 | `profiles/` | 创建期画像（`--profile` 加装计划；应用内不再消费，可忽略） |
 
 ## 模块开发（双端自注册闭环，逐行同构）
 
-`packages/module-*`（经 `tbox-app module add` 生成）是双端单包，两端入口导出**模块描述对象**并自注册：
+`packages/module-*`（经 `npx --yes @tbox.cn/app-cli module add` 生成）是双端单包，两端入口导出**模块描述对象**并自注册：
 
 - server 入口 `src/server/index.ts`：`export const serverModule = { cards, register(ctx) {...} } satisfies ServerModule`；
   `register` 内经 `ctx.tools/cards.registerMap/handlers/routes/services/bus` 自注册；只注册不解析（resolveService 仅 handle/事件回调内）。
@@ -21,7 +21,7 @@
   `register` 内经 `ctx.cards.registerMap(cards)` 注册卡片组件。
 - `cards` map 的 **key 约定 = meta.cardType**（server 端 meta 的 cardType；doctor 会校验），无卡片模块写 `cards: {}`；
   模块对象必须用 `satisfies`（不能 `: ServerModule` 标注——标注会把 cards 泛化导致类型推导失效）。
-- 每个模块根目录有 `tbox.module.json`（schema v1）声明 contributes（tools/cards/handlers/routes/pages/tabs）。
+- 每个模块根目录有 `tbox.module.json`（schema v1）声明 `declare`（tools/cards/handlers/routes/pages/tabs + `owns`/`consumes` 服务面）。
   跨模块写操作走 `ctx.services.register/resolve` + 类型化事件总线，业务代码只 import `@tbox.cn/app-contracts`（或领域契约包），不 import `apps/*`。
 
 ## 装配文件（双锚点，双端逐行同构）
@@ -46,25 +46,37 @@ apps/client/src/business/App.tsx              # 业务应用入口
 apps/client/src/platform/AgentChatApp.tsx     # 默认对话运行时
 apps/client/src/modules.ts                    # 客户端模块装配（与 server 端同构）
 apps/client/src/cards/registry.ts             # 卡片注册表快照（CardType → CardComponent）
-apps/server/src/index.ts                      # 服务端入口（HTTP + WS + Vite middleware + createServerContext + createEngineFromContext）
+apps/server/src/index.ts                      # 服务端入口（静态产物 HTTP + WS；vite dev 链 = src/dev.ts）
 apps/server/src/modules.ts                    # 服务端模块装配（registerAll）
 apps/server/src/module-ports.ts               # 模块 ports 动态装配（LinkedPanel/bumpin 数据源；契约派生 + 漂移守卫）
-packages/provider-custom/src/server/index.ts  # 自定义 API adapter 实施落点（指引见 packages/provider-custom/INTEGRATION.md）
-config/                                       # chat/model/plugin 配置
+packages/provider-custom/src/server/index.ts  # 自定义 API adapter 实施落点（指引：npx --yes @tbox.cn/app-cli skills get provider-custom）
+config/                                       # 应用配置面（integrations/chat/agent 等，见 config/README.md）
 ```
 
 ## 运行与验证（平台沙箱）
 
 应用构建与运行在平台沙箱中，启动/停止/重启由平台负责——不要运行 `pnpm dev`、`pnpm start`
-等长驻进程命令（沙箱规则 `config/rules/no-persistent-process.md`）；`scripts/` 下生命周期
-脚本（prepare/dev/start/stop/build）同样由平台调用。你只改代码与配置，用一次性命令验证：
+等长驻进程命令；`scripts/` 下生命周期脚本（prepare/dev/start/stop/build）同样由平台调用。
+验证走三级回路，按改动面选最小充分集：
+
+| 改动 | 验证 | 命令 |
+|---|---|---|
+| 代码（类型/契约） | 静态 | `pnpm typecheck`（单模块 `pnpm --filter <pkg> typecheck` 秒级） |
+| 集成/配置/新增模块 | 一次性运行时 | `pnpm smoke`（boot + browser 登录 + `/api/auth/me`，随机端口） |
+| 看运行效果 | 8000 活体 | `curl -s http://127.0.0.1:8000/api/health` |
+
+- **编译验证 = typecheck + smoke**；`pnpm smoke` 失败时先读尾部日志（fail-soft 配置降级在此可见）。
+- **不要运行 `pnpm build` / `pnpm verify`**：冷构建超过沙箱命令时限（必超时），且 dev/smoke 不消费 `dist`；产物构建归平台生命周期脚本。
+- `pnpm verify:fast` = typecheck + test + verify:generated + check（提交前静态收口）。
+- `curl` 连接被拒绝 ≠ 应用损坏：平台在轮末自启服务，8000 空窗属正常态。
+- 长驻进程纪律：不要用 `&`/`nohup` 方式自行拉起 server；一次性验证只允许 `pnpm smoke`（自带进程组清理）。
 
 ```sh
 pnpm install                     # 会话开始时 node_modules 缺失先装
 pnpm typecheck
 pnpm test
-pnpm build
-pnpm verify                      # typecheck + test + lint + build + verify:generated + check:inspector
+pnpm smoke                       # 一次性运行时冒烟（随机端口，自动清理）
+pnpm verify:fast                 # 静态收口（不含 build/lint）
 pnpm verify:generated            # 装配一致 + 锚点完整 + 无裸露 import
 pnpm plugin:doctor               # 插件排障
 pnpm plugin:inspect <pluginId> <toolId>
@@ -74,8 +86,8 @@ pnpm plugin:inspect <pluginId> <toolId>
 
 ## tbox-app CLI（模块与装配管理）
 
-CLI 免安装，命令均经 `npx --yes @tbox.cn/app-cli <cmd>` 运行（下表简写 `tbox-app`；完整
-命令面 `tbox-app --help`）。add/remove/sync 后需 `pnpm install`：
+CLI 免安装，命令一律以 `npx --yes @tbox.cn/app-cli <cmd>` 运行（完整命令面加 `--help`）。
+add/remove/sync 后需 `pnpm install`：
 
 | 命令 | 用途 |
 |---|---|
@@ -83,17 +95,21 @@ CLI 免安装，命令均经 `npx --yes @tbox.cn/app-cli <cmd>` 运行（下表
 | `module remove <id>` | 卸载模块（见「删除模块」） |
 | `module list` / `sync` / `diff` / `doctor` | 已装清单 / 增量装配 / 漂移对比 / 结构校验 |
 | `module update <module>` | 升级模块（codegen → 3-way merge） |
+| `module inspect [id]` | 能力/服务绑定矩阵（`--json` 机器可读） |
 | `new <module\|provider\|theme> <name>` | 应用内脚手架（生成 `packages/<id>` 并完成装配） |
 | `provider use / bind / unbind / unuse` | 集成绑定（写 `config/integrations.json`；v8 起自定义 API 统一 `provider-custom` 字符串厂商——CLI 全覆盖三层，含 `--module` 模块级单点绑定；bind/use 整槽覆盖既有 provider） |
+| `provider use <p> --activate` | 应用默认厂商 + 该厂商供给面槽位批量激活（`*.snapshot` 聚合槽除外） |
+| `skills list` / `skills get <topic>` | 流程知识（integration / provider-custom / verify / miniapp-container） |
+| `schema [file]` | 配置形状（`config/integrations.json` / `tbox.module.json`） |
 | `theme use <id>` / `theme list` | 主题接线 / 状态 |
 | `starter --list` / `starter --type <type>` | starter 文档查询（商圈模块清单见 `--type agent-mall`） |
 
 ## 自定义服务集成（provider-custom）
 
 自定义 API = 服务的真实后端由你自己对接。收到「为某服务/模块/应用接入自定义 API」
-（或「对接我的 API」「先要接口清单」等同义说法）请求时：**完整流程、任务路由与接入
-材料清单规范见应用根 `INTEGRATION.md`——先读它再动手**。本节不再展开（指引真源 =
-INTEGRATION.md，勿在本节扩展）。
+（或「对接我的 API」「先要接口清单」等同义说法）请求时：**先执行
+`npx --yes @tbox.cn/app-cli skills get integration` 读取完整流程、任务路由与接入材料清单
+规范，再动手**。本节不再展开（指引真源 = CLI skills，勿在本节扩展）。
 
 ## 删除模块
 
@@ -109,12 +125,12 @@ pnpm install
   死项 + doctor 复查。
 - 被其他模块 required 依赖时会阻止并列出依赖方：先删依赖方；`--force` 仅确认知情时使用。
 - 删除后跑 `pnpm typecheck`：`CardType` 随装配自动收缩，残留消费方会编译报错——按报错
-  清理引用后 `pnpm verify` 收尾。
+  清理引用后 `pnpm verify:fast` 收尾。
 - 提示「contracts-mall 已无依赖者」时可再 `module remove contracts-mall` 恢复 SDK shim。
 
 ## 平台基础设施
 
-以下链路受保护，不得删除或绕过（守卫随 `@tbox.cn/app-sdk` 分发：`pnpm check:inspector` / `tbox-inspector-check`，已入 `pnpm verify` 链）：
+以下链路受保护，不得删除或绕过（守卫随 `@tbox.cn/app-sdk` 分发：`pnpm check:inspector` / `tbox-inspector-check`，已入 `pnpm check` 静态门禁）：
 
 - `@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` 约定不变）
@@ -151,4 +167,4 @@ pnpm install
 
 修改本应用任何代码时，导出面与装配文件的注释保持**自包含短文档**（用途 + 关键约束 +
 消费视角）；不引用仓库内部路径与决策编号——它们对沙箱外的读者无意义。指引类内容
-不写进注释：集成指引见 `INTEGRATION.md`（真源），本文件为发现入口。
+不写进注释：集成指引用 `npx --yes @tbox.cn/app-cli skills get integration`（真源），本文件为发现入口。

package/ENV.md

@@ -23,7 +23,7 @@
     无 `instances` 键 = 无参考表（动态形态）；env 未注入 → 占位 fail-fast 显性暴露。
 - 注入形态：mallId-only（miniAppId 尽力回填——root config `miniAppId` 优先、参考表
   attributes 兜底；双缺仍注入，不阻断默认商圈）。URL 显式参数 `?mallId=` 优先级更高。
-- 本地 mock 链：`tbox-app module add` 装 provider-mock（0.5.0 极简零配置——开箱免集成配置；
+- 本地 mock 链：`npx --yes @tbox.cn/app-cli module add` 装 provider-mock（0.5.0 极简零配置——开箱免集成配置；
   动态配置验证面 → provider-mocktest，内部档 `pnpm dev mall-mocktest`）→ 生成器派生零拓扑
   integrations.json → 裸跑免 mallId 全局会话或任意 `?mallId=` 均可演示。零拓扑形态下 provider-mock 于 register 期
   声明隐式默认单实例（mall-demo / 星河 Mock 小镇）——无 URL 参数访问时默认商圈回显照常生效
@@ -55,17 +55,18 @@
 
 ## 应用配置（config/，非 env）
 
-`config/` 为应用配置目录（真实值经 `tbox-app create --config-dir <目录>` 合并注入，生成应用自包含；
+`config/` 为应用配置目录（真实值经 `npx --yes @tbox.cn/app-cli create --config-dir <目录>` 合并注入，生成应用自包含；
 模板内为 demo 占位形态）。配置目录由 server entry 锚定解析（`__dirname` 3 级上溯 = 应用根，
 dev/src 与 prod/dist bundle 形态恒等）：
 
 - `config/integrations.json`：provider 绑定与部署拓扑唯一真源（integrations v4：绑定组
   provider+implementation 从最特异层整组继承（instance > slot > domain > root），组内
   implementation 缺席经 catalog 派生；部署拓扑 = 顶层 `instances` 注册表 + `defaultInstanceId`；
-  槽 `instances` 键缺席 = 通配激活）。模板不内置——`tbox-app module add` 装入 local 供给
-  （provider-mock / provider-mocktest——local 供给双包同语义）时由 CLI mock 绑定生成器自动派生零拓扑形态（root.provider + 全 local 槽
-  空对象）；真厂商绑定经 `tbox-app provider use/bind` 或 `--config-dir` 真实素材注入。
-  自定义 API 接入操作指引（任务路由/材料清单/落声明/adapter 实施）见应用根 `INTEGRATION.md`。
+  槽 `instances` 键缺席 = 通配激活）。模板出厂携带 pristine 种子（仅 `$comment` 指针 + `services: {}`）——
+  `npx --yes @tbox.cn/app-cli module add` 装入 local 供给（provider-mock / provider-mocktest——local 供给双包同语义）时，
+  CLI mock 绑定生成器视同缺席自动派生零拓扑形态（root.provider + 全 local 槽空对象，种子元键保全）；
+  真厂商绑定经 `npx --yes @tbox.cn/app-cli provider use/bind` 或 `--config-dir` 真实素材注入。
+  自定义 API 接入操作指引（任务路由/材料清单/落声明/adapter 实施）：`npx --yes @tbox.cn/app-cli skills get integration`。
 - `config/integrations.json` 顶层 `modules` 节：模块资源绑定（键 = 模块 install id，如
   `module-customer-service`；`resources.<resourceId> = { type: 'knowledge', datasetId | ref, topK?, scoreThreshold? }`）。
   经 SDK `createModuleResourceResolver`（zod discriminatedUnion + 无内联密钥断言）→ `app-config` 服务

package/README.md

@@ -1,12 +1,12 @@
 # template-agent
 
 tbox AI Agent 全栈模板（npm 包名 `@tbox.cn/app-template-agent`，唯一模板——W4 单一模板统一化），多包 pnpm workspace：`apps/` 薄组装端 + `packages/` 模块。
-缺省出厂 = 带 AI 支付体验的 chat 形态；**商圈形态经 `profiles/mall` 画像加装**（`tbox-app create --profile mall`：mall-core + 七业务模块 + 商圈配置叠加）。
+缺省出厂 = 带 AI 支付体验的 chat 形态；**商圈形态经 `profiles/mall` 画像加装**（`npx --yes @tbox.cn/app-cli create --profile mall`：mall-core + 七业务模块 + 商圈配置叠加）。
 客户端同时支持浏览器和支付宝小程序 web-view；平台能力（鉴权/会话/TTS/ASR/上传/反馈）经 `@tbox.cn/app-sdk` 统一提供（007 下沉）。
 
 创建应用时按 `.tbox/default-modules.json` 加装 AI 支付模块，源码落在 `packages/module-ai-payment`。
 
-创建应用时默认使用 `@tbox.cn/app-miniapp-container-alipay@0.2.5` 生成 `apps/miniapp-container-alipay`，容器计划见 `.tbox/miniapp-containers.json`。使用前配置小程序 AppId 和 H5 地址；重复创建保留已登记的容器。
+创建应用时默认使用 `@tbox.cn/app-miniapp-container-alipay@0.2.6` 生成 `apps/miniapp-container-alipay`，容器计划见 `.tbox/miniapp-containers.json`。使用前配置小程序 AppId 和 H5 地址；重复创建保留已登记的容器。
 
 `pnpm dev` 始终启动原有 H5/server；容器已安装且 PATH 中有 `minidev` 时同时启动容器，否则跳过。容器异常退出不影响 H5/server，Ctrl+C 统一停止本次启动的进程。
 
@@ -15,16 +15,17 @@ tbox AI Agent 全栈模板（npm 包名 `@tbox.cn/app-template-agent`，唯一
 ```sh
 pnpm install
 pnpm dev          # H5/server + 可选 minidev 小程序容器
-pnpm verify       # typecheck + test + build
+pnpm smoke        # 一次性运行时冒烟（随机端口）
+pnpm verify:fast  # typecheck + test + verify:generated + check
 ```
 
 **能力加装**（已有 AI 支付体验，能力即模块；mall 全套可改用 `create --profile mall` 一步到位）：
 
 ```sh
-tbox-app module add shopping-guide   # 导购/找店/业态/客服（模块级 intents + LLM 工具 + 卡片）
-tbox-app module add member           # 会员卡/积分/优惠券（queryPoints preTool always 身份预执行）
-tbox-app module add parking promotion # 停车/活动（可选）
-tbox-app module doctor               # 26 条结构校验
+npx --yes @tbox.cn/app-cli module add shopping-guide   # 导购/找店/业态/客服（模块级 intents + LLM 工具 + 卡片）
+npx --yes @tbox.cn/app-cli module add member           # 会员卡/积分/优惠券（queryPoints preTool always 身份预执行）
+npx --yes @tbox.cn/app-cli module add parking promotion # 停车/活动（可选）
+npx --yes @tbox.cn/app-cli module doctor   # 30 条结构校验
 ```
 
 **MallHome 服务域**（015；`--profile mall` 加装 mall-core 后生效）：家页 `packages/module-mall-core` 四域开箱——导购/会员/活动优惠（promotion）/停车服务（parking）；域 query 走工具与意图路由链（模块 add/remove 即增删能力，无部署级门控）。
@@ -35,7 +36,7 @@ tbox-app module doctor               # 26 条结构校验
 > 生产建议在 tbox 平台页面上配置（平台托管 env，密钥不进代码仓库）。
 
 > 平台包消费（005 v0.4.0 发布态）：模板通过 `@app/contracts-mall` shim 使用 `catalog:` 引用的发布包；创建时默认安装 AI 支付模块，CLI 按依赖将 shim 替换为本地源码包——
-> 生产（registry 已发布）直接 `pnpm install`；平台包未发布 npm 时，由 `tbox-app create --local-deps <平台 tgz 目录>`
+> 生产（registry 已发布）直接 `pnpm install`；平台包未发布 npm 时，由 `npx --yes @tbox.cn/app-cli create --local-deps <平台 tgz 目录>`
 > 注入 overrides（`file:` 本地发布态产物）后 install 离线可用。
 >
 > 依赖链说明（007）：`@tbox.cn/app-sdk` 新增 dependencies `@tbox-dev-js/sdk`（平台能力客户端）、`@ai-sdk/openai-compatible`（LLM）——
@@ -56,7 +57,7 @@ template-agent/
     server/                    Express + WS 装配端（~120 行装配：auth 中间件 + 模块挂载 + 平台路由面/TTS/WS）
     server/skills/             本地 Skill（SKILL.md 目录格式，随模板复制/pack）
   packages/
-    模块目录（空装配：能力经 `tbox-app module add` 扩展——`@app/<id>` 成员在此生成）
+    模块目录（空装配：能力经 `npx --yes @tbox.cn/app-cli module add` 扩展——`@app/<id>` 成员在此生成）
   config/                      chat/model/plugin 配置
   scripts/                     构建、检查和平台脚本
   pnpm-workspace.template.yaml 应用 workspace 模板（create 生成应用 pnpm-workspace.yaml 的来源）
@@ -155,7 +156,7 @@ definePreTool(findStoreTool, {
 |---|---|---|
 | `getCurrentTime` | `apps/server/src/pre-tools.ts` + `tools/clock.ts` | 零参工程化（词表命中即执行） |
 | `mall-info` | `modules/module-mall-core`（W3-1 自模板迁入；`--profile mall`/module add 后经模块声明式 preTools 通道生效） | always + mall scope 入参化（每轮背景注入；会话内 dedup 一次） |
-| `queryPoints` | `modules/module-member`（`tbox-app module add member` 后） | `always` 必选 + 身份门控（identity 取 userId，匿名 skip） |
+| `queryPoints` | `modules/module-member`（`npx --yes @tbox.cn/app-cli module add member` 后） | `always` 必选 + 身份门控（identity 取 userId，匿名 skip） |
 | `translate` | 反例（不改代码） | 参数依赖语义抽取，不适配——保持 LLM 工具路径 |
 
 ### 冒烟
@@ -164,7 +165,7 @@ definePreTool(findStoreTool, {
 # 启动日志：timeout + 预执行工具清单
 [PRETOOL] timeoutMs=2000 preTools=getCurrentTime
 # ①"现在几点了"     → 「自动查询 查询当前日期和时间」→ 作答（零参形态）
-# ② 安装 member 后（tbox-app module add member）"我的积分有多少" → 「自动查询」徽标（always + 身份门控）→ 积分卡
+# ② 安装 member 后（npx --yes @tbox.cn/app-cli module add member）"我的积分有多少" → 「自动查询」徽标（always + 身份门控）→ 积分卡
 # ③"帮我翻译 hello" → 无「自动查询」徽标（反例：正常 LLM 工具路径）
 # ④ TBOX_PRE_TOOL_TIMEOUT_MS=0 复测① → 回退为模型调用工具两轮（对比基准）
 # ⑤ 刷新页面 → 历史消息仍显示「已自动获取」徽标（inputs.preTools 重建）
@@ -190,7 +191,7 @@ UI 表现与编排（组件/hooks/容器/样式/id 前缀约定）、业务意
 
 > **发布态消费（005 v0.4.0）**：仓库内本模板是根 workspace 成员子树（无独立 `pnpm-workspace.yaml`/lock），
 > 平台引用 `catalog:` + 根 `pnpm-workspace.yaml` `overrides: workspace:*` 回指根 `packages/` 真源；
-> `tbox-app create` 从模板源（目录、pack tgz 或 registry 包 `@tbox.cn/app-template-agent[@version]`）展开生成应用——
+> `npx --yes @tbox.cn/app-cli create` 从模板源（目录、pack tgz 或 registry 包 `@tbox.cn/app-template-agent[@version]`）展开生成应用——
 > 生成应用**不含平台成员**，平台包经注入 overrides（`file:` 本地 tgz，验证态）或 registry（生产态）安装；
 > `pnpm-workspace.yaml` 由 `pnpm-workspace.template.yaml` 改名生成。CLI 未安装时：`pnpm add -g @tbox.cn/app-cli`。
 

package/apps/client/src/business/App.tsx

@@ -3,7 +3,7 @@ import AgentChatApp from '@/platform/AgentChatApp';
 /**
  * 业务应用唯一入口。
  * mall 模板：空态首屏由 IndexPage 内 MallHome 呈现（商圈主屏），无需 landing 注入；
- * 业务能力经 `tbox-app module add` 扩展（shopping-guide/member 等）。
+ * 业务能力经 `npx --yes @tbox.cn/app-cli module add` 扩展（shopping-guide/member 等）。
  * 新应用替换本组件；需要定制首屏时组合 AgentChatApp 或改 pages/index。
  */
 export default function BusinessApp() {

package/apps/client/src/business/README.md

@@ -1,8 +1,8 @@
 # Business application entry
 
-`App.tsx` 是业务应用的唯一入口。缺省出厂 = 空装配 chat 形态（`AgentChatApp` 直出对话流，无 landing 注入——014 已退役）。商圈形态经 `tbox-app create --profile mall` 加装：mall-core 模块经 home 槽供给联单式主屏（欢迎区 + 单一联单活动主卡 + 会员/停车双快览 + 四域开发测试入口），消息追加在首页内容下方，底部保留三枚快捷指令与输入区。四域开发测试入口可见性由后端开关控制（`MALL_HOME_DEV_SERVICES` env → `GET /api/m/mall-core/config`，fail-closed 缺省隐藏；详见模板 ENV.md）。会员快览严格区分登录与入会状态，仅对已入会用户展示服务端返回的真实积分。
+`App.tsx` 是业务应用的唯一入口。缺省出厂 = 空装配 chat 形态（`AgentChatApp` 直出对话流，无 landing 注入——014 已退役）。商圈形态经 `npx --yes @tbox.cn/app-cli create --profile mall` 加装：mall-core 模块经 home 槽供给联单式主屏（欢迎区 + 单一联单活动主卡 + 会员/停车双快览 + 四域开发测试入口），消息追加在首页内容下方，底部保留三枚快捷指令与输入区。四域开发测试入口可见性由后端开关控制（`MALL_HOME_DEV_SERVICES` env → `GET /api/m/mall-core/config`，fail-closed 缺省隐藏；详见模板 ENV.md）。会员快览严格区分登录与入会状态，仅对已入会用户展示服务端返回的真实积分。
 
-业务能力经 `tbox-app module add` 扩展（shopping-guide/member/parking/promotion/alipay-activity），安装后自动装配进双端 `modules.ts`；联单节点是支付宝活动回执的支付笔数投影（mall-core 家页面），不从会话业务卡或本地默认值派生。生成完成后运行 `pnpm verify:generated`。
+业务能力经 `npx --yes @tbox.cn/app-cli module add` 扩展（shopping-guide/member/parking/promotion/alipay-activity），安装后自动装配进双端 `modules.ts`；联单节点是支付宝活动回执的支付笔数投影（mall-core 家页面），不从会话业务卡或本地默认值派生。生成完成后运行 `pnpm verify:generated`。
 
 ## 本地交互应用
 

package/apps/client/src/modules.ts

@@ -8,7 +8,7 @@
 import type { ClientContext, InferModuleCards } from '@tbox.cn/app-agent-sdk-client';
 
 // @tbox:imports-begin
-// 其余能力经 `tbox-app module add` 扩展（shopping-guide/member 等商圈模块；mall-core 经 profiles/mall）
+// 其余能力经 `npx --yes @tbox.cn/app-cli module add` 扩展（shopping-guide/member 等商圈模块；mall-core 经 profiles/mall）
 // @tbox:imports-end
 
 // @tbox:register-begin

package/apps/server/src/modules.ts

@@ -15,7 +15,7 @@ import { serverModule as providerCustom } from '@app/provider-custom/server';
 
 // @tbox:register-begin
 //  单一模板统一化：缺省出厂 = 空装配（仅 provider-custom 自定义 API 落点 + contracts-mall shim）——
-// mall 能力（mall-core + 业务模块）经 profiles/mall 加装（tbox-app create --profile mall， 接线）
+// mall 能力（mall-core + 业务模块）经 profiles/mall 加装（npx --yes @tbox.cn/app-cli create --profile mall， 接线）
 // footer `] as const` 为空数组类型锚（CLI 增删模块时保留变体）
 const modules = [
   providerCustom,

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

@@ -37,9 +37,11 @@ describe('工具 / 卡片 registry 一致性（自注册闭环）', () => {
   });
 
   it('插件装配读取根目录 config/plugins.json', () => {
+    // 断言面边界：plugins 是配置形状（恒真面）；warnings 是用户配置衍生的 advisory 运行态
+    // （合法配置也可能产生），只断形状不断空值（testing/2026-10-20-template-shipped-test-boundary.md）。
     expect(createPluginIntegration().readConfig()).toMatchObject({
       plugins: expect.any(Array),
-      warnings: [],
+      warnings: expect.any(Array),
     });
   });
 });

package/config/README.md

@@ -0,0 +1,20 @@
+# config/ —— 应用配置面
+
+| 文件 | 用途 | 加载失败 |
+|---|---|---|
+| `integrations.json` | 服务绑定/激活/实例/凭据引用 | **boot-fatal**（strict zod；拼错键启动即报） |
+| `chat.json` | 对话运行时参数 | fail-soft（静默降级） |
+| `llm_provider.json` | 模型与 provider | fail-soft |
+| `plugins.json` | 插件清单 | fail-soft |
+| `agent.jsonc` | Agent 提示词/画像（JSONC，允许注释与尾逗号；mall 画像按需生成） | fail-soft |
+| `knowledge.json` | 知识库资源（按需生成） | fail-soft |
+| `service-slots.json` | 服务词汇引导快照（create 按需生成；可由 module sync 重算） | fail-soft |
+
+- 形状查询：`npx --yes @tbox.cn/app-cli schema config/integrations.json`
+- 全部配置面：`npx --yes @tbox.cn/app-cli schema`
+- 流程知识：`npx --yes @tbox.cn/app-cli skills get integration` / `skills get provider-custom`
+- 校验：`npx --yes @tbox.cn/app-cli module doctor`（㉙ config-schema）
+- 密钥真值只放平台凭据/环境变量，**不要写进本目录的 `config.*` 字段**。
+
+元键 `$comment` / `$schema` 仅作为文档指针，行为惰性；`agent.jsonc` 与 `plugins.json`
+不写入元键（前者 strict 形状、后者由外部插件 loader 解释）。

package/config/integrations.json

@@ -0,0 +1,4 @@
+{
+  "$comment": "配置形状: npx --yes @tbox.cn/app-cli schema config/integrations.json；接入流程: npx --yes @tbox.cn/app-cli skills get integration",
+  "services": {}
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tbox.cn/app-template-agent",
-  "version": "0.10.20",
-  "description": "tbox AI Agent 全栈模板（多包 pnpm workspace）：apps/client + apps/server。唯一模板（W4 单一模板统一化：缺省带 AI 支付体验的 chat 形态；mall 能力经 profiles/mall 加装），能力经 tbox-app module add 模块扩展（shopping-guide/member 等）。",
+  "version": "0.10.22",
+  "description": "tbox AI Agent 全栈模板（多包 pnpm workspace）：apps/client + apps/server。唯一模板（W4 单一模板统一化：缺省带 AI 支付体验的 chat 形态；mall 能力经 profiles/mall 加装），能力经 CLI module add 模块扩展（shopping-guide/member 等）。",
   "engines": {
     "node": ">=24.0.0 <25.0.0"
   },
@@ -22,7 +22,6 @@
     ".gitignore",
     ".nvmrc",
     "AGENTS.md",
-    "INTEGRATION.md",
     "ENV.md",
     "LEGAL.md",
     "README.md",
@@ -50,7 +49,9 @@
     "typecheck": "pnpm -r --filter \"./{apps,packages}/*\" typecheck",
     "test": "pnpm -r --filter \"./{apps,packages}/*\" test",
     "lint": "eslint apps $(find packages -mindepth 1 -maxdepth 1 -type d -print -quit 2>/dev/null | grep -q . && echo packages)",
-    "verify": "pnpm typecheck && pnpm test && pnpm lint && pnpm build && pnpm verify:generated && pnpm check:inspector",
+    "smoke": "node scripts/smoke.mjs",
+    "verify": "pnpm typecheck && pnpm test && pnpm lint && pnpm build && pnpm smoke --self-test && pnpm verify:generated && pnpm check:inspector",
+    "verify:fast": "pnpm typecheck && pnpm test && pnpm verify:generated && pnpm check",
     "verify:generated": "node scripts/verify-generated.mjs",
     "check": "pnpm check:workspace && pnpm check:inspector",
     "check:workspace": "node scripts/check-workspace.mjs",

package/packages/provider-custom/AGENTS.md

@@ -1,41 +1,27 @@
 # provider-custom —— 自定义 API 实施落点（AI 集成指引）
 
-本包是**自定义 API（内联声明）的 adapter 代码落点**：某服务槽在 `config/integrations.json`
-保存内联声明（provider 为对象 + implementation 字面量）而 adapter 未实施时，服务调用报
-`PROVIDER_NOT_IMPLEMENTED`——按指引实施并注册命中后即恢复。
+本包是自定义 API 的 adapter 代码落点：某服务槽声明 `provider-custom` 而 adapter 未实施时，
+服务调用报 `PROVIDER_NOT_IMPLEMENTED`——按指引实施并注册命中后即恢复。
 
-收到接入请求或需要实施排障时：**完整实施指引（实施三步 / 声明形态对照 / 可复制 JSON
-片段 / 代码骨架 / provider 名三处一致 / 认证与凭据 / 完成判据）见本包 `INTEGRATION.md`
-——先读它再动手**。接入材料清单规范与任务路由见应用根 `INTEGRATION.md`。
+**先读流程知识（随 CLI 发布，无需安装）**：
 
-## 实施三步
+```sh
+npx --yes @tbox.cn/app-cli skills get provider-custom   # 实施三步/声明形态/代码骨架/注册/凭据
+npx --yes @tbox.cn/app-cli skills get integration        # 接入材料清单与任务路由
+```
 
-见本包 `INTEGRATION.md`「实施三步」。
-
-## 声明形态 ⇔ 实现落点（先选对形态再动手）
-
-见本包 `INTEGRATION.md`「声明形态 ⇔ 实现落点」。
-
-## 内联声明 JSON 片段（可复制形态）
-
-见本包 `INTEGRATION.md`「内联声明 JSON 片段」。
-
-## 最小代码骨架
-
-见本包 `INTEGRATION.md`「最小代码骨架」。
+代码骨架、参数模板、注册形态与凭据见 `npx --yes @tbox.cn/app-cli skills get provider-custom`；
+模板出厂形态另含完整未接线参考实现 `src/server/example-adapter.ts`（registry 安装形态无此文件——
+以上述骨架为准）。
 
 ## provider 名三处一致
 
-见本包 `INTEGRATION.md`「provider 名三处一致」（全仓唯一真源在本节对应处）。
+声明侧（`config/integrations.json`）、注册侧（`src/server/index.ts` 的
+`registerAdapter` 第一参）、凭据侧（`config/credentials/<provider>-<service>.json` stem）
+必须同名。完整规则见 `npx --yes @tbox.cn/app-cli skills get provider-custom`。
 
 ## 认证与凭据
 
-见本包 `INTEGRATION.md`「认证与凭据」（含 config/configSchema/凭据数据可见性边界表）。
-
-## 完成判据
-
-见本包 `INTEGRATION.md`「完成判据」。
-
-## 真实厂商接入
-
-见本包 `INTEGRATION.md`「真实厂商接入」。
+凭据真值只进 `config/credentials/<stem>.json` 嵌套形或平台 env；禁止写入 prompt、源码或
+`integrations.json` 的 `config.*`。完整形态（static-headers-v1 / 自定义策略 /
+数据可见性边界）见 `npx --yes @tbox.cn/app-cli skills get provider-custom`「认证与凭据」。

package/packages/provider-custom/README.md

@@ -1,8 +1,9 @@
 # @tbox.cn/app-provider-custom
 
-自定义厂商实施落点空包（与 provider-mock / provider-mocktest 并列的中立空壳）：manifest contributes 全空（零贡献
+自定义厂商实施落点空包（与 provider-mock / provider-mocktest 并列的中立空壳）：manifest declare 全空（零贡献
 合法——descriptor zod 全 default），出厂无任何供给/需求/卡片声明，纯为 AI 实施自定义 API
 adapter 提供**有形代码落点**。闭环机制见 AGENTS.md（SDK 零改动——registerAdapter 命中即转 ok）。
 
-单包多厂商：多个自定义 API 的 adapter 均在此包注册。依赖精确裁剪 = app-sdk + app-contracts
-（不消费领域 Port 类型，无 contracts-mall）；无 client 入口；无 peerDependencies。
+单包多厂商：多个自定义 API 的 adapter 均在此包注册。运行依赖精确裁剪 = app-sdk + app-contracts；
+领域 Port 仅以 `import type` 出现在模板镜像的 `src/server/example-adapter.ts`（devDependency
+`@app/contracts-mall`，零运行依赖）；无 client 入口；无 peerDependencies。

package/packages/provider-custom/package.json

@@ -29,7 +29,8 @@
     "@types/node": "24.13.3",
     "typescript": "5.9.3",
     "vitest": "4.1.10",
-    "tsup": "8.5.1"
+    "tsup": "8.5.1",
+    "@app/contracts-mall": "workspace:*"
   },
   "files": [
     "dist",
@@ -39,7 +40,6 @@
     "tsconfig.json",
     "tsup.config.ts",
     "AGENTS.md",
-    "INTEGRATION.md",
     "README.md",
     "LICENSE"
   ],

package/packages/provider-custom/src/server/example-adapter.ts

@@ -0,0 +1,58 @@
+/**
+ * 完整参考实现（未接线——复制改造我）。
+ *
+ * 形态：字符串厂商 `provider-custom` 的多服务分支 factory。真实接入步骤见
+ * `npx --yes @tbox.cn/app-cli skills get provider-custom`：
+ *   1. 在 tbox.module.json `declare.providers.slots` 声明供给槽（消费 config 键的槽同步声明
+ *      configSchema 参数模板——见 `skills get provider-custom`「参数模板声明」）；
+ *   2. 复制本文件为 `<你的服务>.ts`，替换 Port 类型与方法实现；
+ *   3. 在 index.ts register 中 `ctx.integrations?.registerAdapter('provider-custom', '<implementation>', factory)`；
+ *   4. 绑定并验证：`provider bind <slot> provider-custom` + `pnpm smoke` +
+ *      `npx --yes @tbox.cn/app-cli module doctor`。
+ *
+ * 本文件不注册、不声明槽位——零行为，仅作为可复制模板。
+ */
+import type { ServiceAdapterFactory } from '@tbox.cn/app-agent-sdk-server';
+import type { MallInfo, MallInfoPort } from '@app/contracts-mall';
+
+interface MallInfoResponse {
+  name?: unknown;
+  address?: unknown;
+  latitude?: unknown;
+  longitude?: unknown;
+  cityId?: unknown;
+}
+
+export const mallInfoExampleFactory: ServiceAdapterFactory = (input) => {
+  // 多服务单键：按 input.service 分支返回各 Port 实现。
+  if (input.service === 'mall.info') {
+    const port: MallInfoPort = {
+      async getMallInfo(mallId: string): Promise<MallInfo | undefined> {
+        // 实现方负责形状守卫（防 path 注入进上游 URL）。
+        if (!/^[A-Za-z0-9_-]+$/.test(mallId)) return undefined;
+        // 惰性凭据：未配置 credentialRef → undefined；真实值不进代码/配置明文。
+        // 真实实现通常把 credential.value 映射为签名/请求头；此处仅演示读取时机。
+        const credential = input.credential?.();
+        void credential;
+        const timeoutMs = typeof input.config.timeoutMs === 'number' ? input.config.timeoutMs : undefined;
+        const response = (await input.transport.request({
+          path: `/v1/malls/${encodeURIComponent(mallId)}`,
+          method: 'GET',
+          ...(timeoutMs !== undefined ? { timeoutMs } : {}),
+        })) as MallInfoResponse;
+        if (!response || typeof response.name !== 'string') return undefined;
+        return {
+          mallId,
+          name: response.name,
+          ...(typeof response.address === 'string' ? { address: response.address } : {}),
+          ...(typeof response.latitude === 'number' ? { latitude: response.latitude } : {}),
+          ...(typeof response.longitude === 'number' ? { longitude: response.longitude } : {}),
+          ...(typeof response.cityId === 'string' ? { cityId: response.cityId } : {}),
+        };
+      },
+    };
+    return port;
+  }
+  // 其他服务：继续分支，或返回 undefined（未命中 = 该槽不由此 factory 供给）。
+  return undefined;
+};

package/packages/provider-custom/src/server/index.ts

@@ -2,15 +2,15 @@
  * 自定义厂商实施落点空包·服务端入口（单包多厂商——多个自定义 API 的
  * adapter 均在此包 register，注册表双键不关心包边界）。
  *
- * 零贡献合法（manifest contributes 全空——descriptor zod 全 default）：本包出厂无任何
+ * 零贡献合法（manifest declare 全空——descriptor zod 全 default）：本包出厂无任何
  * 供给/需求/卡片声明，纯为 AI 实施自定义 API adapter 提供**有形代码落点**。运行时闭环：
- *   1. 某服务槽保存自定义 API 内联声明（integrations.json：provider 对象 + implementation 字面量）；
+ *   1. 某服务槽声明厂商（推荐字符串 `provider-custom`；存量内联对象读兼容）；
  *   2. 服务调用解析该绑定 → adapter 未注册 → PROVIDER_NOT_IMPLEMENTED（fail-visible）；
- *   3. AI 按本包 AGENTS.md 指引实现 adapter 并在 register 挂载
+ *   3. AI 按 `npx --yes @tbox.cn/app-cli skills get provider-custom` 指引实现 adapter 并在 register 挂载
  *      ctx.integrations?.registerAdapter(provider, 'inline', factory)；
  *   4. 平台重启后 register 命中 → 该服务调用恢复正常（完成信号）。
  *
- * 真实厂商接入（官方 provider 包形态：manifest 槽声明 + 独立包发布）跳转见 AGENTS.md。
+ * 真实厂商接入（官方 provider 包形态：manifest 槽声明 + 独立包发布）见 skills get provider-custom。
  */
 import type { ServerContext, ServerModule } from '@tbox.cn/app-agent-sdk-server';
 
@@ -28,8 +28,9 @@ export const PROVIDER_CUSTOM = 'provider-custom';
  *     // input.credential?.() 惰性凭据 getter（返回 { scope, type, value }；未配 → undefined）
  *     return new MyApiServiceImpl(input);
  *   };
- *   // 注册键 implementation 段恒为 'inline'（内联声明运行时按合成 'inline' 寻址）：
- *   ctx.integrations?.registerAdapter('my-custom-api', 'inline', myApiAdapterFactory);
+ *   // 字符串声明（推荐）：registerAdapter('provider-custom', '<implementation>', factory)
+ *   // 内联对象声明（存量）：registerAdapter('<provider 名>', 'inline', factory)
+ *   ctx.integrations?.registerAdapter('provider-custom', '<implementation>', myApiAdapterFactory);
  */
 export function register(ctx: ServerContext): void {
   // 挂点：多个自定义 API 的 adapter 均在此注册（见上方签名示例）。

package/packages/provider-custom/tests/provider-custom.test.ts

@@ -2,16 +2,14 @@ import { describe, expect, it } from 'vitest';
 import { providerId } from '../src/index';
 import { serverModule } from '../src/server/index';
 
-describe('provider-custom 空包（D10 落点）', () => {
-  it('serverModule 形状：moduleId + 空 cards + register 可调用', () => {
+// 模块身份守卫：moduleId/providerId 与包身份恒等——register 键为运行时绑定锚（registry
+// 解析 / doctor 对账），误改即红灯。刻意不断言声明内容与 register 行为：那是应用实施面
+// （AGENTS.md/INTEGRATION.md 指引），本测试随包分发进生成应用，不得钉死用户实施
+// （testing/2026-10-20-template-shipped-test-boundary.md）。
+describe('provider-custom 模块身份（D10 落点）', () => {
+  it('register 键与包身份一致', () => {
     expect(serverModule.declaration.moduleId).toBe('provider-custom');
-    expect(serverModule.cards).toEqual({});
-    expect(typeof serverModule.register).toBe('function');
     expect(providerId).toBe('provider-custom');
-  });
-
-  it('register 零贡献：调用不抛（mock ctx 无 integrations 挂点）', () => {
-    const ctx = {} as never;
-    expect(() => serverModule.register(ctx)).not.toThrow();
+    expect(typeof serverModule.register).toBe('function');
   });
 });