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

package/packages/agent-ui-kit/src/types.ts

@@ -1,4 +1,4 @@
-/** 媒体 / 消息类型（协议类型已下沉 @tbox.cn/app-sdk/client，此处 re-export 保持单一来源） */
+/** 媒体 / 消息类型（协议类型已下沉 @tbox.cn/app-agent-sdk-client，此处 re-export 保持单一来源） */
 export type {
   MediaType,
   InputMethod,
@@ -8,7 +8,7 @@ export type {
   MessageStatus,
   ToolCallInfo,
   ChatMessage,
-} from '@tbox.cn/app-sdk/client';
+} from '@tbox.cn/app-agent-sdk-client';
 
 /** 单种媒体的上传约束（对齐原模板 FileTypeConfig，UI 层约定，留在模板） */
 export interface FileTypeConfig {

package/packages/agent-ui-kit/src/utils/haptics.test.ts

@@ -4,7 +4,7 @@
 import { afterEach, describe, expect, it, vi } from 'vitest';
 
 const mocks = vi.hoisted(() => ({ callJsapi: vi.fn() }));
-vi.mock('@tbox.cn/app-sdk/client', () => ({ callJsapi: mocks.callJsapi }));
+vi.mock('@tbox.cn/app-agent-sdk-client', () => ({ callJsapi: mocks.callJsapi }));
 
 import { hapticTap, resetHapticBridgeState } from './haptics';
 

package/packages/agent-ui-kit/src/utils/haptics.ts

@@ -8,7 +8,7 @@
  * 注意 iOS 上无论哪条路径都可能无感——Safari 不开放 Taptic Engine 给网页，
  * 容器内是否有感取决于宿主 App 的实现。调用方不应依赖它的成功与否。
  */
-import { callJsapi } from '@tbox.cn/app-sdk/client';
+import { callJsapi } from '@tbox.cn/app-agent-sdk-client';
 
 /** 极短时长（ms）：轻点级别，不是提示级别的长震。 */
 const TAP_DURATION_MS = 10;

package/packages/agent-ui-kit/src/utils/tool-call-display.test.ts

@@ -1,6 +1,6 @@
 import { describe, it, expect } from 'vitest';
 import { describeToolCall, formatCompactToolIo } from './tool-call-display';
-import type { ToolCallInfo } from '@tbox.cn/app-sdk/client';
+import type { ToolCallInfo } from '@tbox.cn/app-agent-sdk-client';
 import { buildPreToolArgsPayload, buildPreToolResultPayload } from '@tbox.cn/app-contracts';
 import {
   buildMemoryToolCallPayload,
@@ -10,7 +10,7 @@ import {
 
 const normal = (over: Partial<ToolCallInfo> = {}): ToolCallInfo => ({
   id: 't1',
-  name: 'getWeather',
+  name: 'queryPoints',
   status: 'done',
   result: JSON.stringify({ temp: 22 }),
   ...over,
@@ -18,7 +18,7 @@ const normal = (over: Partial<ToolCallInfo> = {}): ToolCallInfo => ({
 
 describe('describeToolCall（010 下沉 S5：展示语义三分支）', () => {
   it('skill：label 取 skillName，无详情', () => {
-    const { args } = buildSkillToolCallPayload({ name: 'weather-guide', description: '天气' });
+    const { args } = buildSkillToolCallPayload({ name: 'demo-guide', description: '演示' });
     const d = describeToolCall({
       id: 's1',
       name: '__tbox_skill',
@@ -26,17 +26,17 @@ describe('describeToolCall（010 下沉 S5：展示语义三分支）', () => {
       result: '{}',
       status: 'done',
     });
-    expect(d).toEqual({ kind: 'skill', label: 'weather-guide', hasDetail: false });
+    expect(d).toEqual({ kind: 'skill', label: 'demo-guide', hasDetail: false });
   });
 
   it('preTool done：label 取 description、详情 = 结果文本', () => {
     const args = buildPreToolArgsPayload({
-      toolName: 'getWeather',
-      description: '天气查询',
-      toolArgs: { city: '杭州' },
+      toolName: 'queryPoints',
+      description: '积分查询',
+      toolArgs: { accountId: 'M0001' },
     });
     const result = buildPreToolResultPayload({
-      toolName: 'getWeather',
+      toolName: 'queryPoints',
       status: 'done',
       result: { temp: 22 },
     });
@@ -49,7 +49,7 @@ describe('describeToolCall（010 下沉 S5：展示语义三分支）', () => {
     });
     expect(d.kind).toBe('preTool');
     if (d.kind === 'preTool') {
-      expect(d.label).toBe('天气查询');
+      expect(d.label).toBe('积分查询');
       expect(d.status).toBe('done');
       expect(d.hasDetail).toBe(true);
       expect(d.resultText).toContain('"temp": 22');
@@ -57,7 +57,7 @@ describe('describeToolCall（010 下沉 S5：展示语义三分支）', () => {
   });
 
   it('preTool calling：label 可用（ARGS 先行）、无详情', () => {
-    const args = buildPreToolArgsPayload({ toolName: 'getWeather', description: '天气查询' });
+    const args = buildPreToolArgsPayload({ toolName: 'queryPoints', description: '积分查询' });
     const d = describeToolCall({
       id: 'p2',
       name: '__tbox_pretool',
@@ -68,14 +68,14 @@ describe('describeToolCall（010 下沉 S5：展示语义三分支）', () => {
     if (d.kind === 'preTool') {
       expect(d.status).toBe('calling');
       expect(d.hasDetail).toBe(false);
-      expect(d.label).toBe('天气查询');
+      expect(d.label).toBe('积分查询');
     }
   });
 
   it('preTool error：经 result payload status 判定（ToolCallInfo.status 恒 done，R 语义）', () => {
-    const args = buildPreToolArgsPayload({ toolName: 'getWeather', description: '天气查询' });
+    const args = buildPreToolArgsPayload({ toolName: 'queryPoints', description: '积分查询' });
     const result = buildPreToolResultPayload({
-      toolName: 'getWeather',
+      toolName: 'queryPoints',
       status: 'error',
       error: '超时',
     });
@@ -111,12 +111,12 @@ describe('describeToolCall（010 下沉 S5：展示语义三分支）', () => {
   it('normal：label = 工具名，详情 = 有 result/error', () => {
     expect(describeToolCall(normal())).toEqual({
       kind: 'normal',
-      label: 'getWeather',
+      label: 'queryPoints',
       hasDetail: true,
     });
     expect(describeToolCall(normal({ status: 'calling', result: undefined }))).toEqual({
       kind: 'normal',
-      label: 'getWeather',
+      label: 'queryPoints',
       hasDetail: false,
     });
   });

package/packages/agent-ui-kit/src/utils/tool-call-display.ts

@@ -16,7 +16,7 @@ import {
   parsePreToolToolCallResult,
   parseSkillToolCallArgs,
 } from '@tbox.cn/app-contracts';
-import type { ToolCallInfo } from '@tbox.cn/app-sdk/client';
+import type { ToolCallInfo } from '@tbox.cn/app-agent-sdk-client';
 
 export type ToolCallDisplay =
   | { kind: 'skill'; label: string; hasDetail: false }

package/packages/provider-custom/AGENTS.md

@@ -1,33 +1,59 @@
 # provider-custom —— 自定义 API 实施落点（AI 集成指引）
 
-本包是**自定义厂商（自定义 API）的 adapter 代码落点**：用户在 AI 构建面板为某服务保存
-「自定义 API」配置（内联声明）后，运行时因供给不在场报 `PROVIDER_NOT_IMPLEMENTED`——
-由 AI 助手按本指引在本包实施 adapter，注册命中后配置即刻转 ok。
+本包是**自定义 API（内联声明）的 adapter 代码落点**：某服务槽在 `config/integrations.json`
+保存内联声明（provider 为对象 + implementation 字面量）而 adapter 未实施时，服务调用报
+`PROVIDER_NOT_IMPLEMENTED`——由 AI 助手按本指引在本包实施，注册命中后即恢复。声明写法与
+维度选择见应用根 `AGENTS.md`「自定义服务集成」。
 
 ## 实施三步
 
-1. **读声明**：`config/integrations.json` 中目标服务（如 `parking.query`）的
-   `provider` 为对象（内联声明：`{ provider, credentialType, configSchema? }`）+
-   `implementation` 字面量——这就是要实现的厂商身份与凭据约定。
-2. **实现 adapter**：在 `src/server/` 新建实现文件，实现该服务对应模块的 Port 接口
-   （接口定义见对应业务模块 `src/server/ports/`；连接参数 = 绑定组 `config`，实例键 =
-   `input.instanceId`）。adapter 工厂签名：
-
-   ```ts
-   const factory: ServiceAdapterFactory = (input) => new MyApiServiceImpl(input);
-   ```
-
+1. **读声明**：`config/integrations.json` 中目标服务（如 `parking.query`）的 `provider`
+   为对象（`{ provider, credentialType, configSchema? }`）+ `implementation` 字面量——这是
+   厂商身份与凭据约定。
+2. **实现 adapter**：在 `src/server/` 新建实现文件，实现该服务对应模块的 Port 接口（接口
+   定义见消费模块 `src/server/ports.ts`（或 `ports/` 目录）或 `@app/contracts-mall`
+   契约包——本包按需加 `@app/contracts-mall` 依赖并 `import type`）。HTTP 调用一律经
+   `input.transport`（baseUrl 取自绑定 config；熔断/HTTPS 强制（localhost 的 http 豁免）/
+   响应体 1MB 上限内建）：
+   `await input.transport.request({ path, method, body, query })`。
 3. **注册**：在 `src/server/index.ts` 的 `register(ctx)` 中调用
-   `ctx.integrations?.registerAdapter('<provider 名>', '<implementation>', factory)`。
-   多个自定义 API 均注册到本包（单包多厂商，注册表双键不关心包边界）。
+   `ctx.integrations?.registerAdapter('<provider 名>', 'inline', factory)`——**注册键
+   implementation 段恒为 `'inline'`**（内联声明运行时按合成 `'inline'` 寻址，与声明中的
+   implementation 字面量无关）。
+
+**多服务单键**：同一 provider 名的全部服务共享唯一注册键——重复注册后者覆盖前者。同一
+后端接多个服务 = 只注册一次，factory 内按 `input.service` 分支返回各 Port 实现；或每服务
+用不同 provider 名分键。adapter 内取凭据值（如自签名）：`input.credential()` 惰性 getter
+（返回 `{ scope, type, value }`；未配 credentialRef → undefined）。
+
+## 认证与凭据
+
+| 认证形态 | credentialType（声明与凭据文件一致） | 机制 |
+|---|---|---|
+| 静态头（x-api-key 等白名单头名） | `static-headers-v1`（SDK 内置） | 头自动注入，adapter 全部经 `input.transport` |
+| 其他（Bearer / 自定义签名…） | 自定（如 `bearer-v1`） | 本包 `register(ctx)` 先 `ctx.authStrategies.register({ credentialType, apply(input) {...} })` 注册策略（SDK `ProviderAuthStrategy`），adapter 同走 `input.transport` |
+
+- **勿用 `'-'`**：非 local 供给在 transport 构造期抛「未知认证类型」。
+- 静态头白名单（本应用 `apps/server/src/app.ts`）：`content-type` / `sign` / `timestamp` /
+  `publickey` / `x-api-key`；白名单外头名走自定义策略。
+- 凭据文件（**嵌套形**，运行时读取格式）`config/credentials/<stem>.json`：
+  `{ "type": "<credentialType>", "value": { "<头名/参数名>": "<真值>" } }`（省略 `scope` =
+  全域通配）。声明/实例持 `credentialRef: "secret://<stem>"`；服务级 stem =
+  `${provider}-${service}`，共享 stem = `${provider}-global`（按实例差异化凭据另有
+  `${provider}-${instanceId}-${domain}` 形）。真值只进凭据文件或平台
+  env——不进 integrations.json、代码与 prompt。
+- 槽 `instances` 省略 = 通配激活（**勿写空对象 `{}`** = 零激活）；已绑字符串厂商的槽整组
+  替换前先向用户确认。
 
 ## 完成判据
 
-- 应用重启后 `PROVIDER_NOT_IMPLEMENTED` 消失（register 命中）；
-- AI 构建面板该服务 chip 由「AI 实施中」转为厂商名、issues 清零。
+- `pnpm typecheck && pnpm build` 通过；
+- 平台重启后该服务的调用不再报 `PROVIDER_NOT_IMPLEMENTED`（resolveService 惰性——调用时
+  观测；通配槽下 doctor 不检查凭据，运行时为最终裁判）。
 
 ## 真实厂商接入
 
-对外提供正式 API 的厂商（支付/会员等大规模集成）走官方 provider 包形态：
-manifest `contributes.providers.slots` 声明供给 + 独立包发布——参照
-`modules/provider-mock`（结构样例）与 docs/reference/providers.md。
+对外提供正式 API 的厂商（支付/会员等大规模集成）走官方 provider 包形态：manifest
+`declare.providers.slots` 声明供给 + 独立包发布 + `tbox-app module add` 装配 +
+`tbox-app provider bind` 绑定。样例：`tbox-app module add @tbox.cn/app-provider-mock --mode
+codegen --source @tbox.cn/app-provider-mock` 后参照 `packages/provider-mock` 结构。

package/packages/provider-custom/README.md

@@ -1,6 +1,6 @@
 # @tbox.cn/app-provider-custom
 
-自定义厂商实施落点空包（与 provider-mock 并列的中立空壳）：manifest contributes 全空（零贡献
+自定义厂商实施落点空包（与 provider-mock / provider-mocktest 并列的中立空壳）：manifest contributes 全空（零贡献
 合法——descriptor zod 全 default），出厂无任何供给/需求/卡片声明，纯为 AI 实施自定义 API
 adapter 提供**有形代码落点**。闭环机制见 AGENTS.md（SDK 零改动——registerAdapter 命中即转 ok）。
 

package/packages/provider-custom/package.json

@@ -21,8 +21,9 @@
     "prepack": "pnpm build"
   },
   "dependencies": {
-    "@tbox.cn/app-sdk": "catalog:",
-    "@tbox.cn/app-contracts": "catalog:"
+    "@tbox.cn/app-contracts": "catalog:",
+    "@tbox.cn/app-agent-sdk-client": "catalog:",
+    "@tbox.cn/app-agent-sdk-server": "catalog:"
   },
   "devDependencies": {
     "@types/node": "24.13.3",

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

@@ -1,18 +1,18 @@
 /**
- * 自定义厂商实施落点空包·服务端入口（ai-build D10；单包多厂商——多个自定义 API 的
+ * 自定义厂商实施落点空包·服务端入口（单包多厂商——多个自定义 API 的
  * adapter 均在此包 register，注册表双键不关心包边界）。
  *
  * 零贡献合法（manifest contributes 全空——descriptor zod 全 default）：本包出厂无任何
- * 供给/需求/卡片声明，纯为 AI 实施提供**有形代码落点**。运行时闭环（SDK 零改动）：
- *   1. 用户在面板为某服务保存内联声明（自定义 API：provider 对象 + implementation 字面量）；
- *   2. 应用启动解析该绑定 → 供给不在场 → PROVIDER_NOT_IMPLEMENTED（fail-visible）；
- *   3. AI 按 AGENTS.md 指引在本包实现 adapter（下 factory 工厂签名）并在 register 挂载
- *      registerAdapter(provider, implementation, factory)；
- *   4. 重启后 register 命中 → 内联声明即刻转 ok——转变即完成信号（面板 issues 清零）。
+ * 供给/需求/卡片声明，纯为 AI 实施自定义 API adapter 提供**有形代码落点**。运行时闭环：
+ *   1. 某服务槽保存自定义 API 内联声明（integrations.json：provider 对象 + implementation 字面量）；
+ *   2. 服务调用解析该绑定 → adapter 未注册 → PROVIDER_NOT_IMPLEMENTED（fail-visible）；
+ *   3. AI 按本包 AGENTS.md 指引实现 adapter 并在 register 挂载
+ *      ctx.integrations?.registerAdapter(provider, 'inline', factory)；
+ *   4. 平台重启后 register 命中 → 该服务调用恢复正常（完成信号）。
  *
  * 真实厂商接入（官方 provider 包形态：manifest 槽声明 + 独立包发布）跳转见 AGENTS.md。
  */
-import type { ServerContext, ServerModule } from '@tbox.cn/app-sdk/server';
+import type { ServerContext, ServerModule } from '@tbox.cn/app-agent-sdk-server';
 
 export const PROVIDER_CUSTOM = 'provider-custom';
 
@@ -20,13 +20,16 @@ export const PROVIDER_CUSTOM = 'provider-custom';
  * adapter 工厂签名示例（真实实施时替换本注释为具体 adapter 注册）：
  *
  *   const myApiAdapterFactory: ServiceAdapterFactory = (input) => {
- *     // input.service        服务 id（如 'parking.query'）
+ *     // input.service        服务 id（如 'parking.query'——多服务单键时按此分支返回各 Port）
  *     // input.instanceId     部署实例键（mall 场景 = mallId；通配激活时由框架解析）
- *     // input.config         绑定组五层合并后的连接参数（面板保存的 baseUrl 等）
- *     // 返回：实现该服务 Port 的 adapter 实例（模块 src/server/ports 定义）
+ *     // input.config         绑定组五层合并后的连接参数（baseUrl 等）
+ *     // input.transport      HTTP 通道（baseUrl/认证/熔断/HTTPS 强制内建）：
+ *     //                       await input.transport.request({ path, method, body, query })
+ *     // input.credential?.() 惰性凭据 getter（返回 { scope, type, value }；未配 → undefined）
  *     return new MyApiServiceImpl(input);
  *   };
- *   ctx.integrations?.registerAdapter('my-custom-api', 'my-custom-parking@1', myApiAdapterFactory);
+ *   // 注册键 implementation 段恒为 'inline'（内联声明运行时按合成 'inline' 寻址）：
+ *   ctx.integrations?.registerAdapter('my-custom-api', 'inline', myApiAdapterFactory);
  */
 export function register(ctx: ServerContext): void {
   // 挂点：多个自定义 API 的 adapter 均在此注册（见上方签名示例）。

package/packages/provider-custom/tbox.module.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "name": "provider-custom",
+  "id": "provider-custom",
   "version": "0.1.0",
   "kind": "business",
   "risk": {
@@ -10,7 +10,11 @@
   "distribution": {
     "defaultMode": "codegen"
   },
-  "contributes": {
+  "dependencies": {
+    "modules": []
+  },
+  "env": [],
+  "declare": {
     "handlers": [],
     "tools": [],
     "cards": [],
@@ -20,10 +24,6 @@
     "providers": {
       "slots": []
     },
-    "services": []
-  },
-  "dependencies": {
-    "modules": []
-  },
-  "env": []
+    "consumes": []
+  }
 }