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

package/packages/agent-ui-kit/src/ChatPage.tsx

@@ -7,7 +7,7 @@
  * - 域自持段（首屏数据/门禁/详情弹层/活动预热）经槽渲染函数自带——本页零域语义。
  */
 import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from 'react';
-import { consumeAutoSendQuery, runAutoSend } from '@tbox.cn/app-sdk/client';
+import { consumeAutoSendQuery, runAutoSend } from '@tbox.cn/app-agent-sdk-client';
 import { usePullDownHistory } from './hooks/use-pull-down-history';
 import type { TboxCardPayload } from '@tbox.cn/app-contracts';
 import { CardRenderer } from './components/CardRenderer';

package/packages/agent-ui-kit/src/chat-config.ts

@@ -6,7 +6,7 @@
  * - HELLO_ACK settings 水合：服务端单一真源（applyServerSettings；五键整组语义，禁部分水合）。
  */
 import { create } from 'zustand';
-import type { ChatUiSettings } from '@tbox.cn/app-sdk/client';
+import type { ChatUiSettings } from '@tbox.cn/app-agent-sdk-client';
 
 export interface QuickCommand {
   /** 纯文案；前导星标/图标由 QuickCommands 组件渲染，不要写进 label */

package/packages/agent-ui-kit/src/components/ActionBar/DebugButton.tsx

@@ -1,4 +1,4 @@
-import { createLogger } from '@tbox.cn/app-sdk/client';
+import { createLogger } from '@tbox.cn/app-agent-sdk-client';
 
 const debugLogger = createLogger('DebugButton');
 

package/packages/agent-ui-kit/src/components/ActionBar/index.tsx

@@ -1,11 +1,11 @@
 import { useEffect, useState, useSyncExternalStore } from 'react';
-import { createLogger } from '@tbox.cn/app-sdk/client';
+import { createLogger } from '@tbox.cn/app-agent-sdk-client';
 
 const ttsActionLogger = createLogger('tts');
 import { Copy, SpeakerHigh, ThumbsDown, ThumbsUp } from '@phosphor-icons/react';
 import { useChatStore } from '../../store-context';
 import { useChatConfigStore } from '../../chat-config';
-import { useFeedbackAdapter, useRefreshSession, useTTSAdapter } from '@tbox.cn/app-sdk/client';
+import { useFeedbackAdapter, useRefreshSession, useTTSAdapter } from '@tbox.cn/app-agent-sdk-client';
 import type { ChatMessage } from '../../types';
 import { copyText } from '../../utils/copyText';
 import { toast } from '../../utils/toast';

package/packages/agent-ui-kit/src/components/CardRenderer.tsx

@@ -6,7 +6,7 @@
  * - CardRenderer：聊天入口（组合层覆盖注册表 cards）；
  * - RawCardRenderer：原始形态（rawCards，无覆盖）——首页详情弹层 body 等防嵌套入口。
  */
-import { CardRenderer as SdkCardRenderer } from '@tbox.cn/app-sdk/client';
+import { CardRenderer as SdkCardRenderer } from '@tbox.cn/app-agent-sdk-client';
 import type { TboxCardPayload, UiAction } from '@tbox.cn/app-contracts';
 import { useChatCards, useChatRawCards, useChatStore } from '../store-context';
 

package/packages/agent-ui-kit/src/components/ChatInput/index.test.tsx

@@ -8,7 +8,7 @@ const mocks = vi.hoisted(() => ({
   interactionState: 'idle' as VoiceInteractionState,
 }));
 
-vi.mock('@tbox.cn/app-sdk/client', () => ({
+vi.mock('@tbox.cn/app-agent-sdk-client', () => ({
   isInAlipayShell: () => false,
   useASRAdapter: () => undefined,
 }));

package/packages/agent-ui-kit/src/components/ChatInput/index.tsx

@@ -1,6 +1,6 @@
 import { useEffect, useRef, useState } from 'react';
 import { useMediaUpload } from '../../hooks/useMediaUpload';
-import { useASRAdapter, isInAlipayShell } from '@tbox.cn/app-sdk/client';
+import { useASRAdapter, isInAlipayShell } from '@tbox.cn/app-agent-sdk-client';
 import { useChatConfigStore } from '../../chat-config';
 
 import type { ChatInputMessage, InputMethod } from '../../types';

package/packages/agent-ui-kit/src/components/ChatInput/voice/useVoicePress.ts

@@ -1,6 +1,6 @@
 import { useCallback, useEffect, useRef, useState } from 'react';
-import type { IASRAdapter } from '@tbox.cn/app-sdk/client';
-import { useRefreshSession } from '@tbox.cn/app-sdk/client';
+import type { IASRAdapter } from '@tbox.cn/app-agent-sdk-client';
+import { useRefreshSession } from '@tbox.cn/app-agent-sdk-client';
 import { isSessionExpiredError } from '../../../utils/session-error';
 import { toast } from '../../../utils/toast';
 import {

package/packages/agent-ui-kit/src/components/MessageBubble/index.tsx

@@ -9,7 +9,7 @@ import ToolCallBlock from '../../components/ToolCallBlock';
 import { ActionBar, CopyButton, getMessageCopyText } from '../../components/ActionBar';
 import { DebugButton } from '../../components/ActionBar/DebugButton';
 import { CardRenderer } from '../CardRenderer';
-import { CardCarousel } from '@tbox.cn/app-sdk/client';
+import { CardCarousel } from '@tbox.cn/app-agent-sdk-client';
 import { useChatStore, useInlineCardFilter } from '../../store-context';
 import { copyText } from '../../utils/copyText';
 import { toast } from '../../utils/toast';

package/packages/agent-ui-kit/src/components/QuickCommands/index.test.tsx

@@ -8,7 +8,7 @@ import { createRoot } from 'react-dom/client';
 import { flushSync } from 'react-dom';
 import type { ReactNode } from 'react';
 import { create } from 'zustand';
-import type { CoreChatStore } from '@tbox.cn/app-sdk/client';
+import type { CoreChatStore } from '@tbox.cn/app-agent-sdk-client';
 import { configureChatConfigDefaults, useChatConfigStore } from '../../chat-config';
 import { KitChatProvider } from '../../store-context';
 import { QuickCommands } from './index';

package/packages/agent-ui-kit/src/components/ToolCallBlock/detail.test.ts

@@ -9,7 +9,7 @@ import {
   PRE_TOOL_CALL_NAME,
   SKILL_TOOL_CALL_NAME,
 } from '@tbox.cn/app-contracts';
-import type { ToolCallInfo } from '@tbox.cn/app-sdk/client';
+import type { ToolCallInfo } from '@tbox.cn/app-agent-sdk-client';
 import {
   buildSummaryText,
   deriveSummary,

package/packages/agent-ui-kit/src/components/ToolCallBlock/detail.ts

@@ -5,7 +5,7 @@
  * debug 门控在渲染层（组件 debug prop）——视图模型保持纯数据投影，不感知环境。
  */
 import { describeToolCall } from '../../utils/tool-call-display';
-import type { ToolCallInfo } from '@tbox.cn/app-sdk/client';
+import type { ToolCallInfo } from '@tbox.cn/app-agent-sdk-client';
 import {
   MEMORY_TOOL_CALL_NAME,
   parseMemoryToolCallArgs,

package/packages/agent-ui-kit/src/hooks/useMediaUpload.ts

@@ -1,9 +1,9 @@
-import { createLogger } from '@tbox.cn/app-sdk/client';
+import { createLogger } from '@tbox.cn/app-agent-sdk-client';
 
 const mediaLogger = createLogger('media');
 
 import { useCallback, useEffect, useRef, useState } from 'react';
-import { useUploadAdapter, useRefreshSession, chooseImage, chooseVideo } from '@tbox.cn/app-sdk/client';
+import { useUploadAdapter, useRefreshSession, chooseImage, chooseVideo } from '@tbox.cn/app-agent-sdk-client';
 
 import { isSessionExpiredError } from '../utils/session-error';
 import { toast } from '../utils/toast';

package/packages/agent-ui-kit/src/hooks/useTTSAutoPlay.ts

@@ -1,7 +1,7 @@
 import { useEffect } from 'react';
-import type { CoreChatState } from '@tbox.cn/app-sdk/client';
+import type { CoreChatState } from '@tbox.cn/app-agent-sdk-client';
 import { useChatStoreApi } from '../store-context';
-import { useTTSAdapter } from '@tbox.cn/app-sdk/client';
+import { useTTSAdapter } from '@tbox.cn/app-agent-sdk-client';
 
 const FLUSH_MS = 300; // 累积 delta 后批量送，避免过多 WS 消息
 

package/packages/agent-ui-kit/src/store-context.tsx

@@ -10,7 +10,7 @@
  */
 import { createContext, useContext, useMemo, type ReactNode } from 'react';
 import type { CardComponent, TboxCardPayload } from '@tbox.cn/app-contracts';
-import type { ClientSlotRegistry, CoreChatState, CoreChatStore } from '@tbox.cn/app-sdk/client';
+import type { ClientSlotRegistry, CoreChatState, CoreChatStore } from '@tbox.cn/app-agent-sdk-client';
 
 export interface KitChatContextValue {
   /** 应用注入的 chat store（zustand 绑定 hook + API） */

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,

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": []
+  }
 }