@tbox.cn/app-template-agent 0.10.5 → 0.10.7

package/AGENTS.md

@@ -166,7 +166,7 @@ integrations.config → integrations.configByInstance[instId] → modules[owner]
 services[slot].instances[instId].credentialRef → services[slot].credentialRef → integrations.credentialRefByInstance[instId] → integrations.credentialRef
 ```
 
-**implementation 派生**：显式 `slot.implementation` / `inst.implementation` 优先；字符串厂商缺省则按 `supplies[provider\u0000service]` 查表派生（unique→自动取一 / 0→`PROVIDER_NOT_SUPPLIED` / 多→要求显式）；内联声明必须显式（zod 已拦）。
+**implementation 派生**：显式 `slot.implementation` / `inst.implementation` 优先；字符串厂商缺省则按 `supplies[provider\u0000service]` 查表派生（unique→自动取一 / 0→`BINDING_UNRESOLVED` / 多→要求显式）；内联声明必须显式（zod 已拦）。
 
 > 内联声明对象只在 `services[slot].provider` 层合法。`modules[].provider` 与 `integrations.provider` 只接受字符串厂商名——这是 zod 直接拒导致 fail-visible 的常见错点。
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tbox.cn/app-template-agent",
-  "version": "0.10.5",
+  "version": "0.10.7",
   "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"

package/packages/provider-custom/AGENTS.md

@@ -26,6 +26,102 @@
 用不同 provider 名分键。adapter 内取凭据值（如自签名）：`input.credential()` 惰性 getter
 （返回 `{ scope, type, value }`；未配 credentialRef → undefined）。
 
+## 声明形态 ⇔ 实现落点（先选对形态再动手）
+
+| 声明形态（services.<slot>.provider） | adapter 落点 | 失配信号 |
+|---|---|---|
+| 内联对象 `{ provider, credentialType }` | **本包**（provider-custom） | 未注册 → `PROVIDER_NOT_IMPLEMENTED` |
+| 字符串厂商名（如 `"mall-demo"`） | 对应正式 provider 包（catalog 来源；`packages/provider-mock` 为样例） | catalog 无此厂商 → **`PROVIDER_NOT_FOUND`** |
+
+**本包 adapter 禁止配字符串声明**：本包零贡献（manifest 无
+`declare.providers.slots`），永不进 provider catalog——字符串声明运行时按
+catalog 查表，必报 `PROVIDER_NOT_FOUND`（错误文案「provider 未命中
+catalog」≠ 名字拼错，是**形态落错**）。
+
+## 内联声明 JSON 片段（可复制形态）
+
+`config/integrations.json` 槽级写法（`provider` 对象与 `implementation`
+是**兄弟键**——implementation 不在对象内；省略 `instances` = 通配激活）：
+
+```json
+{
+  "services": {
+    "parking.query": {
+      "provider": { "provider": "my-api", "credentialType": "static-headers-v1" },
+      "implementation": "my-api@1",
+      "config": { "baseUrl": "https://api.example.com" },
+      "credentialRef": "secret://my-api-parking.query"
+    }
+  }
+}
+```
+
+**错误形态对照**：
+
+| ❌ 错误 | 原因 |
+|---|---|
+| `"provider": { "provider": "my-api", "implementation": "my-api@1" }` | `implementation` 不是内联对象字段（zod 拒） |
+| `"provider": "my-api"` 而 adapter 在本包 | catalog 查表失配 → `PROVIDER_NOT_FOUND`（见上节） |
+| `"instances": {}` | 零激活（省略 = 通配激活） |
+
+实参（config 值 / 凭据 stem / 槽名）按用户 API 文档填；凭据真值只进
+`config/credentials/<stem>.json` 嵌套形（格式见「认证与凭据」）。
+
+## 最小代码骨架
+
+类型 import 双源（全部 `import type`——typecheck 首祸排除）：
+
+- `ServiceAdapterFactory` / `ServerContext` ← `@tbox.cn/app-agent-sdk-server`
+- Port 接口 ← 服务域契约包（mall 域 = `@app/contracts-mall`；消费模块
+  `src/server/ports.ts` 的 import 行可反查正确来源——如 `parking.query` 的
+  供给接口 `ParkingQueryPort`；本包 `package.json` 按需补该依赖）
+
+```ts
+// packages/provider-custom/src/server/my-api.ts
+import type { ServiceAdapterFactory } from '@tbox.cn/app-agent-sdk-server';
+import type { ParkingQueryPort } from '@app/contracts-mall';
+
+export const myApiFactory: ServiceAdapterFactory = (input) => {
+  const impl: ParkingQueryPort = {
+    async queryFee(q, req) {
+      // input.transport：HTTP 通道（baseUrl/认证/熔断/HTTPS 强制内建）
+      const res = await input.transport.request({
+        path: '/v1/parking/fee',
+        method: 'POST',
+        body: { plateNo: req.plateNo },
+      });
+      return mapFee(res);
+    },
+    // ...Port 其余方法签名照抄接口定义
+  };
+  return impl;
+};
+```
+
+**Port 形状检索工作法（零猜测）**：
+
+```sh
+rg "export (interface|type) .*Port" packages/<消费模块>/src/server/ports.ts
+rg "<接口名>" packages/contracts-mall/src/
+```
+
+- Port 方法签名 = 实现清单——逐个照抄（参数/返回值与工具语义一一对应）；
+- 厂商响应 → contracts 结构转换后返回，不透传厂商字段名。
+
+注册（`src/server/index.ts` 的 `register(ctx)` 内）：
+
+```ts
+import type { ServerContext } from '@tbox.cn/app-agent-sdk-server';
+import { myApiFactory } from './my-api';
+
+// register(ctx) 内：
+ctx.integrations?.registerAdapter('my-api', 'inline', myApiFactory);
+```
+
+单 factory 多服务：按 `input.service` 分支返回不同 Port 实现（服务清单见
+消费模块 `tbox.module.json` `declare.owns`）；或每服务独立 provider 名
+分键注册。`input` 字段全集见 `src/server/index.ts` 签名示例注释。
+
 ## provider 名三处一致
 
 取的 provider 名必须下三处同名（任一处失配则运行时报 `PROVIDER_NOT_IMPLEMENTED`——
@@ -89,8 +185,9 @@ resolveService 惰性查表查不到对应 adapter）：
 ## 完成判据
 
 - `pnpm typecheck && pnpm build` 通过；
-- 平台重启后该服务的调用不再报 `PROVIDER_NOT_IMPLEMENTED`（resolveService 惰性——调用时
-  观测；通配槽下 doctor 不检查凭据，运行时为最终裁判）。
+- 对话或 curl 触发一次该服务的工具调用，确认正常出结果（typecheck/build 与 doctor
+  均不触运行时——resolveService 惰性，调用时才判 `PROVIDER_NOT_IMPLEMENTED`）；
+- 通配槽下 doctor 不检查凭据，运行时为最终裁判。
 
 ## 真实厂商接入
 

package/pnpm-lock.template.yaml

@@ -16,17 +16,17 @@ catalogs:
       specifier: 0.1.0
       version: 0.1.0
     '@tbox.cn/app-agent-sdk-client':
-      specifier: 0.1.2
-      version: 0.1.2
+      specifier: 0.1.3
+      version: 0.1.3
     '@tbox.cn/app-agent-sdk-server':
-      specifier: 0.1.2
-      version: 0.1.2
+      specifier: 0.1.4
+      version: 0.1.4
     '@tbox.cn/app-contracts':
-      specifier: 0.12.2
-      version: 0.12.2
+      specifier: 0.12.3
+      version: 0.12.3
     '@tbox.cn/app-contracts-mall':
-      specifier: 0.12.2
-      version: 0.12.2
+      specifier: 0.12.3
+      version: 0.12.3
     '@tbox.cn/app-sdk-server':
       specifier: 0.21.1
       version: 0.21.1
@@ -142,10 +142,10 @@ importers:
         version: link:../../packages/provider-custom
       '@tbox.cn/app-agent-sdk-client':
         specifier: 'catalog:'
-        version: 0.1.2(@types/react@18.3.31)
+        version: 0.1.3(@types/react@18.3.31)
       '@tbox.cn/app-contracts':
         specifier: 'catalog:'
-        version: 0.12.2
+        version: 0.12.3
       '@tbox.cn/app-theme-tbox':
         specifier: 'catalog:'
         version: 0.1.3
@@ -206,10 +206,10 @@ importers:
         version: 0.1.0(@mastra/core@1.59.0(ai@6.0.246(zod@3.25.76))(express@4.22.2)(rxjs@7.8.1)(zod@3.25.76))(@tbox-dev-js/sdk@0.1.18)(zod@3.25.76)
       '@tbox.cn/app-agent-sdk-server':
         specifier: 'catalog:'
-        version: 0.1.2(@tbox-dev-js/sdk@0.1.18)(rxjs@7.8.1)
+        version: 0.1.4(@tbox-dev-js/sdk@0.1.18)(rxjs@7.8.1)
       '@tbox.cn/app-contracts':
         specifier: 'catalog:'
-        version: 0.12.2
+        version: 0.12.3
       express:
         specifier: 'catalog:'
         version: 4.22.2
@@ -246,10 +246,10 @@ importers:
         version: 2.1.10(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
       '@tbox.cn/app-agent-sdk-client':
         specifier: 'catalog:'
-        version: 0.1.2(@types/react@18.3.31)
+        version: 0.1.3(@types/react@18.3.31)
       '@tbox.cn/app-contracts':
         specifier: 'catalog:'
-        version: 0.12.2
+        version: 0.12.3
       antd-mobile:
         specifier: 'catalog:'
         version: 5.42.3(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
@@ -298,7 +298,7 @@ importers:
     dependencies:
       '@tbox.cn/app-contracts-mall':
         specifier: 'catalog:'
-        version: 0.12.2
+        version: 0.12.3
     devDependencies:
       '@types/node':
         specifier: 24.13.3
@@ -314,13 +314,13 @@ importers:
     dependencies:
       '@tbox.cn/app-agent-sdk-client':
         specifier: 'catalog:'
-        version: 0.1.2(@types/react@18.3.31)
+        version: 0.1.3(@types/react@18.3.31)
       '@tbox.cn/app-agent-sdk-server':
         specifier: 'catalog:'
-        version: 0.1.2(@tbox-dev-js/sdk@0.1.18)(rxjs@7.8.1)
+        version: 0.1.4(@tbox-dev-js/sdk@0.1.18)(rxjs@7.8.1)
       '@tbox.cn/app-contracts':
         specifier: 'catalog:'
-        version: 0.12.2
+        version: 0.12.3
     devDependencies:
       '@types/node':
         specifier: 24.13.3
@@ -1335,16 +1335,16 @@ packages:
       '@tbox-dev-js/sdk': '>=0.1.18 <0.2.0'
       zod: '>=3.24.0 <4.0.0'
 
-  '@tbox.cn/app-agent-sdk-client@0.1.2':
-    resolution: {integrity: sha512-Ba5n4PUCWsj8+jByOYGGAXS5lzEioBYmaMxvLL0Axvc3Id9gVYF31Jj5H4U+bVzO4Jtbb7huqG9sf3qX69lffw==}
+  '@tbox.cn/app-agent-sdk-client@0.1.3':
+    resolution: {integrity: sha512-oyHvufpJ1bWfoEAm82Kkh07d0NbuK9NQkZGEvprB3UBKEQRgyydKps58K1IHHjVZ/eDMBeGA8DgAxqAbC8rQCw==}
     engines: {node: '>=20.0.0'}
 
-  '@tbox.cn/app-agent-sdk-server@0.1.2':
-    resolution: {integrity: sha512-qS9RDPAGHiFB+FesBtgc2QLZnGNgXrG62fCyPQ663Cb9xfF0Fs0r+fTPXpG2ewsBkoST7c1oy/ZlfMO85o7/pw==}
+  '@tbox.cn/app-agent-sdk-server@0.1.4':
+    resolution: {integrity: sha512-V4XS+DkanVTdX/5TsgPFgBV/6+iNx0lgA4AjGfhR4eIyV3fhlBU0qS3KN+ZPbfQQfgh95fqenV4n6jMO8iothw==}
     engines: {node: '>=20.0.0'}
 
-  '@tbox.cn/app-contracts-mall@0.12.2':
-    resolution: {integrity: sha512-/vBCWpvFsCagnUSHbogHFFrnCURic9QUZ//AURasTzZoSv5u5/OetHAQ8JON1ukJ8ItLzfhjRJ1IBvFNMA3xhg==}
+  '@tbox.cn/app-contracts-mall@0.12.3':
+    resolution: {integrity: sha512-ahV/yVeJCcO6PioAoVRPfnSNNFOAcHwtkTns6dK2xnpPIN1ouHPcZd6NoM4kZaTs/ZWNwVMPQEfqFBjLnS9heA==}
     engines: {node: '>=20.0.0'}
 
   '@tbox.cn/app-contracts@0.12.0':
@@ -1355,8 +1355,8 @@ packages:
     resolution: {integrity: sha512-h5HXIfk5frNx6hufY2IBE+hISCk3/2n8A7G3EtnAF4JsR91Pm/uwdmn4zYtZOz0r9cL7Wk1SrUMcokMZ9HkbLw==}
     engines: {node: '>=20.0.0'}
 
-  '@tbox.cn/app-contracts@0.12.2':
-    resolution: {integrity: sha512-SnteKq3+kQjwDHb4BN2HX2Eawd7ws84IxPkJziaeKaDGBfJ1RzPRUAQyL/Zo4kJLCzsY3ViE2AEh1SG10r4MXw==}
+  '@tbox.cn/app-contracts@0.12.3':
+    resolution: {integrity: sha512-b71WtU1Kk9rC3lwaefb48ymKPgkdb7MJcJQ0lTeUZu/jSNHsqQ4ZZI9ZUbHQ/rzYvWmZbdxe5H94328jAfJoVA==}
     engines: {node: '>=20.0.0'}
 
   '@tbox.cn/app-sdk-client@0.21.1':
@@ -1371,10 +1371,9 @@ packages:
     resolution: {integrity: sha512-OSncc0sjhcuEQAlcANLCKNP0V+hgVhP0qol6pIyYSxSUUVLf69naiGWC4CBtY7PTIYlhximMw6bIn8tqNYKFXg==}
     engines: {node: '>=20.0.0'}
 
-  '@tbox.cn/app-sdk-server@0.21.0':
-    resolution: {integrity: sha512-buiwhnT46Jb1P99UJN1p0ATjRzhFIXIgqIYQDT4aT3fVbmMxWUuAPpFYhM3uTFGx5oPh18/ju3MVz0FxZ5DMCg==}
+  '@tbox.cn/app-sdk-core@0.20.2':
+    resolution: {integrity: sha512-KDcFdIrIEOlwDvIqBu29CzR5vDjt0BCADMBrgrd5WlRqjrPM1/jM/RcaRO6gRuElmQCp5LfsoAkVeYTZE/6rpw==}
     engines: {node: '>=20.0.0'}
-    hasBin: true
 
   '@tbox.cn/app-sdk-server@0.21.1':
     resolution: {integrity: sha512-LCB9gH6n5ILdLDHQUAq1NLrclLjmB0dsqGVHe4Zb4yucUPb16jxk/53NREYq0NzsHiTDxc29IvcreVaxRpVmXw==}
@@ -1384,10 +1383,6 @@ packages:
   '@tbox.cn/app-theme-tbox@0.1.3':
     resolution: {integrity: sha512-Wf2umpT/k+Ppy1oKuCDqe6M5yvp4F/tjdGpU7uygGWMaEduwFnoK0EVh4eDcA6dMlERLCAjxFlEUY68xXGq99A==}
 
-  '@tbox.cn/app-toolkit@0.5.0':
-    resolution: {integrity: sha512-ShLYwxsMzhr8V5sjixo4GFGBZbAw4/8CoTnCigrbBcRLtydf2ezLrLDR9jHfi/d5fQworFR5ZBzI7xDSjvR2zA==}
-    engines: {node: '>=20.0.0'}
-
   '@tbox.cn/app-toolkit@0.7.2':
     resolution: {integrity: sha512-bvq5l7rwwX3EJe0hQm4dnwSh0tuDmoucCkCfX306PvNbhSv0H9uHSljg/jeXh08DBtc2gjIJyvPsfDxrv5X6Uw==}
     engines: {node: '>=20.0.0'}
@@ -4090,11 +4085,11 @@ snapshots:
       '@tbox-dev-js/sdk': 0.1.18
       zod: 3.25.76
 
-  '@tbox.cn/app-agent-sdk-client@0.1.2(@types/react@18.3.31)':
+  '@tbox.cn/app-agent-sdk-client@0.1.3(@types/react@18.3.31)':
     dependencies:
-      '@tbox.cn/app-contracts': 0.12.1
+      '@tbox.cn/app-contracts': 0.12.3
       '@tbox.cn/app-sdk-client': 0.21.1
-      '@tbox.cn/app-sdk-core': 0.20.1
+      '@tbox.cn/app-sdk-core': 0.20.2
       react: 18.3.1
       react-dom: 18.3.1(react@18.3.1)
       zustand: 4.5.7(@types/react@18.3.31)(react@18.3.1)
@@ -4102,7 +4097,7 @@ snapshots:
       - '@types/react'
       - immer
 
-  '@tbox.cn/app-agent-sdk-server@0.1.2(@tbox-dev-js/sdk@0.1.18)(rxjs@7.8.1)':
+  '@tbox.cn/app-agent-sdk-server@0.1.4(@tbox-dev-js/sdk@0.1.18)(rxjs@7.8.1)':
     dependencies:
       '@ag-ui/core': 0.0.47
       '@ai-sdk/openai-compatible': 2.0.68(zod@3.25.76)
@@ -4110,9 +4105,9 @@ snapshots:
       '@mastra/core': 1.59.0(ai@6.0.246(zod@3.25.76))(express@4.22.2)(rxjs@7.8.1)(zod@3.25.76)
       '@mastra/observability': 1.16.5(@mastra/core@1.59.0(ai@6.0.246(zod@3.25.76))(express@4.22.2)(rxjs@7.8.1)(zod@3.25.76))(zod@3.25.76)
       '@tbox.cn/agent-plugin': 0.1.0(@mastra/core@1.59.0(ai@6.0.246(zod@3.25.76))(express@4.22.2)(rxjs@7.8.1)(zod@3.25.76))(@tbox-dev-js/sdk@0.1.18)(zod@3.25.76)
-      '@tbox.cn/app-contracts': 0.12.1
-      '@tbox.cn/app-sdk-core': 0.20.1
-      '@tbox.cn/app-sdk-server': 0.21.0
+      '@tbox.cn/app-contracts': 0.12.3
+      '@tbox.cn/app-sdk-core': 0.20.2
+      '@tbox.cn/app-sdk-server': 0.21.1
       ai: 6.0.246(zod@3.25.76)
       express: 4.22.2
       gray-matter: 4.0.3
@@ -4130,9 +4125,9 @@ snapshots:
       - utf-8-validate
       - workflow
 
-  '@tbox.cn/app-contracts-mall@0.12.2':
+  '@tbox.cn/app-contracts-mall@0.12.3':
     dependencies:
-      '@tbox.cn/app-contracts': 0.12.1
+      '@tbox.cn/app-contracts': 0.12.3
       zod: 3.25.76
 
   '@tbox.cn/app-contracts@0.12.0':
@@ -4147,7 +4142,7 @@ snapshots:
       react: 18.3.1
       zod: 3.25.76
 
-  '@tbox.cn/app-contracts@0.12.2':
+  '@tbox.cn/app-contracts@0.12.3':
     dependencies:
       '@ag-ui/core': 0.0.47
       react: 18.3.1
@@ -4168,17 +4163,9 @@ snapshots:
     dependencies:
       '@tbox.cn/app-contracts': 0.12.1
 
-  '@tbox.cn/app-sdk-server@0.21.0':
+  '@tbox.cn/app-sdk-core@0.20.2':
     dependencies:
-      '@ag-ui/core': 0.0.47
-      '@tbox.cn/app-contracts': 0.12.0
-      '@tbox.cn/app-sdk-core': 0.20.0
-      '@tbox.cn/app-toolkit': 0.5.0
-      express: 4.22.2
-      jose: 6.2.8
-      zod: 3.25.76
-    transitivePeerDependencies:
-      - supports-color
+      '@tbox.cn/app-contracts': 0.12.3
 
   '@tbox.cn/app-sdk-server@0.21.1':
     dependencies:
@@ -4194,11 +4181,6 @@ snapshots:
 
   '@tbox.cn/app-theme-tbox@0.1.3': {}
 
-  '@tbox.cn/app-toolkit@0.5.0':
-    dependencies:
-      ajv: 8.20.0
-      zod: 3.25.76
-
   '@tbox.cn/app-toolkit@0.7.2':
     dependencies:
       ajv: 8.20.0

package/pnpm-workspace.template.yaml

@@ -38,13 +38,13 @@ catalog:
   ws: 8.21.3
   "@types/ws": 8.18.1
   "@tbox.cn/agent-plugin": 0.1.0
-  "@tbox.cn/app-sdk-core": 0.20.1
+  "@tbox.cn/app-sdk-core": 0.20.2
   "@tbox.cn/app-sdk-client": 0.21.1
   "@tbox.cn/app-sdk-server": 0.21.1
-  "@tbox.cn/app-agent-sdk-server": 0.1.2
-  "@tbox.cn/app-agent-sdk-client": 0.1.2
-  "@tbox.cn/app-contracts": 0.12.2
-  "@tbox.cn/app-contracts-mall": 0.12.2
+  "@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
+  "@tbox.cn/app-contracts-mall": 0.12.3
   "@tbox.cn/app-theme-tbox": 0.1.3
   zustand: 4.5.7
   eslint: 9.39.5