@tbox.cn/app-sdk-client 0.21.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 tbox.cn
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,9 @@
+# @tbox.cn/app-sdk-client
+
+tbox AI Agent 平台 SDK client 轴：能力适配器（asr / tts / upload / feedback 均走同源 server 代理）、
+chat 引擎、状态域（zustand）、桥协议 v2、WS 客户端（keepalive / 重连护栏 / 鉴权守卫）、卡片渲染与 dev 预览页。
+
+真实外部依赖仅 react + react-dom + zustand（+ core/contracts）——client 树零 Node 内建、零 server 重依赖
+（2026-09 三包拆分；浏览器直连 o.tbox.cn 的能力已全部收口为同源代理）。
+
+公开入口：`.` / `./client` / `./client/card-preview` / `./platform/code-inspect`（vite 页面微调 babel plugin）。

package/dist/client/index.d.ts

@@ -0,0 +1,459 @@
+import { TboxLogger } from '@tbox.cn/app-sdk-core';
+export { InferModuleCards, LogContext, LogLevel, TboxLogger, createLogger, detailForLog, sanitizeForLog, truncateForLog } from '@tbox.cn/app-sdk-core';
+import * as React from 'react';
+import React__default, { ReactNode, CSSProperties, Component } from 'react';
+import { TboxCardPayload, CardComponent, UiAction, ClientSlotId, ClientSlotValueMap } from '@tbox.cn/app-contracts';
+
+/**
+ * 客户端日志壳：client run 上下文（req/conv 尾缀）+ 全局错误兜底 + transport 扩展点（上报预留）。
+ *
+ * - 级别探测：localStorage['tbox:logLevel'] → ?logLevel= → info（typeof 守卫，SSR/node 测试环境安全）；
+ * - setClientRunContext：chat-store 在 RUN_STARTED/RUN_FINISHED 更新（runId → req= 尾缀）；
+ * - installGlobalErrorReporting：window.onerror + unhandledrejection → logger（10s 窗口去重；
+ *   返回卸载函数；非浏览器环境 no-op）；
+ * - ClientLogTransport：上报扩展点（默认 no-op——WS 上报协议为独立演进方向，此处只留接口）。
+ */
+
+/** run 上下文更新（chat-store RUN_STARTED/RUN_FINISHED 消费；null = 清除） */
+declare function setClientRunContext(ctx: {
+    conversationId?: string;
+    runId?: string;
+} | null): void;
+declare function createClientLogger(tag: string): TboxLogger;
+/** 上报扩展点（P3 预留：默认 no-op，接入 WS 上报时替换实现） */
+interface ClientLogTransport {
+    send(level: string, line: string): void;
+}
+declare function setClientLogTransport(t: ClientLogTransport): void;
+/** 全局错误兜底：未捕获异常/rejection → logger.error + transport；返回卸载函数 */
+declare function installGlobalErrorReporting(logger?: TboxLogger): () => void;
+
+declare function CardRenderer({ card, registry, onAction, }: {
+    card: TboxCardPayload;
+    registry: Record<string, CardComponent>;
+    /** 动作按钮点击回调（应用层注入 sendUiAction 桥：onAction={(a) => sendUiAction(card.id, a)}；
+     *  缺省仅展示不可点） */
+    onAction?: (action: UiAction) => void;
+}): React.JSX.Element;
+
+/**
+ * 多卡纵向铺开（决策出卡多实例展示）：气泡卡片区自上而下顺序排布。
+ * 单卡直出（零 chrome）；多卡纵向 flex 铺开，间距单一来源（宿主 .tbox-card 底部间距）。
+ * 基元模式 inline style（对齐 CardFrame 先例，不引 CSS 文件）；
+ * 输入即已剥离标签的卡片数据，组件不渲染任何协议痕迹。
+ */
+
+declare function CardCarousel({ cards, renderItem, className, }: {
+    cards: TboxCardPayload[];
+    /** 单卡渲染委托（模板传 CardRenderer 包装；key 由本组件 wrapper 持有） */
+    renderItem: (card: TboxCardPayload) => ReactNode;
+    className?: string;
+}): JSX.Element;
+
+/**
+ * 卡片渲染基元（011 J5：封顶 5 件——新增须走提案）。
+ * 模块卡片组件唯一可消费的 SDK 视觉基元：仅依赖 `--tbox-*` CSS 变量 + antd-mobile，
+ * 零业务样式。token 未定义时回退内置默认值（本地预览可用）。
+ */
+
+/**
+ * 自渲染动作标记（0.3.2 D10）：置位的卡片组件在 CardRenderer 内跳过默认动作按钮条
+ * （卡内自持写操作按钮，经 sendCardAction(moduleAction) 直连）。与未置位卡并存，
+ * 旧 SDK 无消费方 → 回落现状双渲染，不 break。
+ */
+type CardComponentWithFlag = CardComponent & {
+    /** 置位后 CardRenderer 不渲染 payload.actions 按钮条（卡内自行处理动作） */
+    selfRendersActions?: boolean;
+};
+/**
+ * 标记卡片为自渲染动作（富卡范式：卡内写按钮 + 交互状态，禁用 SDK 默认按钮条）。
+ * 泛型不限 CardComponent：富卡常带精确 data 类型，与 CardComponent<unknown> 不协变；
+ * 标记仅运行时附加静态标志，消费侧注册处仍按 CardComponent 使用。
+ */
+declare function markSelfRendering<T>(component: T): T & CardComponentWithFlag;
+/** 卡片容器：标题 + 副标题 + 内容槽（模块卡片的统一外框） */
+declare function CardFrame(props: {
+    title?: string;
+    subtitle?: string;
+    children: ReactNode;
+    style?: CSSProperties;
+}): React__default.JSX.Element;
+/** 键值文本行：label 左、value 右（模块卡片的通用信息行） */
+declare function ValueText(props: {
+    label: string;
+    value: string;
+    valueStyle?: CSSProperties;
+}): React__default.JSX.Element;
+type StatusPillTone = 'success' | 'warning' | 'neutral';
+/** 状态徽标：成功/警示/中性（模块卡片的状态展示） */
+declare function StatusPill(props: {
+    tone: StatusPillTone;
+    text: string;
+}): React__default.JSX.Element;
+
+/** 错误边界：子树渲染抛错时显示 fallback，不让单点错误炸掉整页/整条消息。 */
+declare class ErrorBoundary extends Component<{
+    fallback: ReactNode;
+    children: ReactNode;
+}, {
+    hasError: boolean;
+}> {
+    state: {
+        hasError: boolean;
+    };
+    static getDerivedStateFromError(): {
+        hasError: boolean;
+    };
+    componentDidCatch(error: unknown): void;
+    render(): ReactNode;
+}
+
+/**
+ * 支付宝 web-view 桥协议常量 / 类型。
+ *
+ * 必须与壳子 `miniapp-container-alipay/pages/ai-agent/bridge.ts` 对齐：
+ *   H5 → 小程序：my.postMessage({ bridge, action, apiName, params, requestId })
+ *   小程序 → H5：webViewContext.postMessage(receipt) → H5 my.onMessage 收
+ *
+ * 命名空间契约：action = apiName 的解析命名空间——
+ *   'my' / 'my.call' = 支付宝平台 API（壳通用代理透传）；
+ *   'tbox' = 壳注册能力（容器自带裸名 apiName / 应用自实现 app.* 前缀）。
+ * 点分 'tbox.*' 值保留给未来协议级操作（握手/版本协商），勿用作能力命名空间。
+ */
+declare const BRIDGE_NAME = "open-mini-webview-bridge";
+declare const BRIDGE_VERSION = "1.0.0";
+declare const MY_ACTION = "my";
+declare const MY_CALL_ACTION = "my.call";
+/** tbox 能力命名空间：apiName 在壳内注册表解析（容器自带裸名 / 应用自实现 app.* 前缀） */
+declare const TBOX_ACTION = "tbox";
+/** JSAPI 调用模式：invoke = my.xxx；call = my.call(apiName, params, cb) */
+type JsapiMode = 'invoke' | 'call';
+/** H5 发给小程序的请求消息（bridge 标记必带——缺标记消息壳不执行） */
+interface BridgeRequest {
+    bridge: typeof BRIDGE_NAME;
+    action: typeof MY_ACTION | typeof MY_CALL_ACTION | typeof TBOX_ACTION;
+    apiName: string;
+    params: Record<string, unknown>;
+    requestId: string;
+}
+/** 小程序回执（壳子 buildMiniProgramReceipt 产出） */
+interface BridgeReceipt {
+    bridge: typeof BRIDGE_NAME;
+    version: string;
+    sendToWebView: '1';
+    action: string;
+    requestId: string;
+    success: boolean;
+    code: string;
+    data?: unknown;
+    errorMessage: string;
+    received?: unknown;
+}
+declare function isBridgeReceipt(msg: unknown): msg is BridgeReceipt;
+
+/**
+ * 调一个平台 JSAPI，Promise 化。
+ * @param apiName 如 'getLocation' / 'chooseImage' / 'getAuthCode'
+ * @param params  JSAPI 入参
+ * @param mode    'invoke'（默认，my.xxx）| 'call'（my.call）
+ */
+declare function callJsapi<T = unknown>(apiName: string, params?: Record<string, unknown>, mode?: JsapiMode, timeoutMs?: number): Promise<T>;
+/**
+ * 调一个 tbox 命名空间能力（壳注册表内实现，无 mode 维度）。
+ *
+ * 与 callJsapi 的辨析：平台 my.xxx API 用 callJsapi；壳注册能力（容器自带如
+ * 'openPlateKeyboard'，应用自实现约定 app.* 前缀）用本函数。支付宝标准
+ * my JSAPI（包括 startRecord/stopRecord）应使用 callJsapi。
+ */
+declare function callCapability<T = unknown>(apiName: string, params?: Record<string, unknown>, timeoutMs?: number): Promise<T>;
+
+/**
+ * 常用桥 JSAPI 便捷封装（供业务/适配层调用）。
+ * 仅在支付宝壳环境可用；浏览器环境 callJsapi / callCapability 均会抛 BRIDGE_UNAVAILABLE。
+ * 业务新能力（扫码/导航/分享等）经 callJsapi 透传平台 API（壳子可能要补 JSAPI 白名单）；
+ * 壳实现/应用自实现能力（app.* 前缀）经 callCapability（bridge-client）走 tbox 命名空间。
+ */
+
+/** 壳子 chooseImage/chooseVideo 把原生结果转成的 base64 dataURL 文件项 */
+interface BridgeMediaFile {
+    data: string;
+    name?: string;
+    size?: number;
+}
+/** sourceType: ['album'|'camera']；不传由壳子默认（相册+相机）。超时用默认 5min（含授权与壳侧文件读取）。 */
+declare function chooseImage(count?: number, sourceType?: ('album' | 'camera')[]): Promise<{
+    files: BridgeMediaFile[];
+}>;
+declare function chooseVideo(): Promise<{
+    files: BridgeMediaFile[];
+}>;
+/** 定位（壳子已把 getLocation 列入 invoke 白名单）。
+ * 支付宝小程序 getLocation 回传经纬度为字符串，统一转成 number 再返回。
+ */
+declare function getLocation(): Promise<{
+    longitude: number;
+    latitude: number;
+    [k: string]: unknown;
+}>;
+/**
+ * 换登录 authCode：走壳子通用代理直调 my.getAuthCode，壳子无需特殊处理。
+ * scopes 默认 ['auth_base']：静默拿用户标识、不弹窗（拿头像昵称才用 auth_user）。
+ * 返回 { authCode }，交给 server /api/auth/login 换 userId。
+ */
+declare function getAuthCode(scopes?: string[]): Promise<{
+    authCode: string;
+}>;
+/**
+ * 收银台支付拉起（015 P4：my.tradePay，orderInfo = 厂商支付凭证不透明透传）。
+ * 双参数透传：tradeNO（交易号语义，joycity GetPaySign d.sn 审计确认）+ orderStr（签名串语义，
+ * 其他厂商兼容）——my.tradePay 按 tradeNO 优先消费。 resultCode：9000 成功 / 6001 取消 /
+ * 8000·4000 等失败——状态映射在 host-effect-runner。浏览器环境抛 BRIDGE_UNAVAILABLE。
+ */
+declare function requestPayment(orderInfo: string): Promise<{
+    resultCode?: string;
+}>;
+/** Parse a complete支付宝 startapp link and invoke the platform navigateTo JSAPI through the bridge. */
+declare function navigateToAlipayPage(url: string): Promise<unknown>;
+/** 会员登录门禁回执：H5 只消费门控信号（loginStatus + message）。
+ *  回执即使携带 token 等凭证字段也不采信——外部凭证唯一合法入口 = 服务端换码器。 */
+interface LoginGateReceipt {
+    /** success=gate 完成登录（含开卡）；cancel=用户拒绝（仅浏览）；fail=gate 内部失败 */
+    loginStatus: 'success' | 'fail' | 'cancel';
+    message?: string;
+}
+/**
+ * 会员登录门禁（tbox 命名空间能力，壳按名分发）：挂起调起商场侧登录/开卡页
+ * （协议上登录与开卡一体——GUEST 在壳侧即未登录，会开 gate），用户完成/取消后回执。
+ * 未注册该能力的壳（含浏览器）reject BRIDGE_UNAVAILABLE，由调用方按卡型降级
+ * （openLink 深链兜底）。默认超时 5min（对齐媒体级长挂起：gate 页停留期间 web-view 冻结）。
+ */
+declare function getLoginState(params?: Record<string, unknown>, timeoutMs?: number): Promise<LoginGateReceipt>;
+interface PlateKeyboardOptions {
+    value?: string;
+    newEnergy?: boolean;
+}
+interface PlateKeyboardResult {
+    plateNo: string;
+    valid: boolean;
+    newEnergy: boolean;
+}
+/**
+ * 唤起壳内原生车牌键盘（tbox 命名空间能力，壳按名分发）；用户确认后返回车牌号，
+ * 取消时 reject USER_CANCEL。浏览器环境会按普通桥能力返回 BRIDGE_UNAVAILABLE，
+ * 由业务决定是否降级为文本输入。
+ */
+declare function openPlateKeyboard(options?: PlateKeyboardOptions): Promise<PlateKeyboardResult>;
+declare function closePlateKeyboard(): Promise<{
+    closed: boolean;
+}>;
+
+/** 内联流过滤器（域注册；复合序 = 注册序） */
+type InlineCardFilter = (cards: readonly TboxCardPayload[]) => TboxCardPayload[];
+/**
+ * ClientCardRegistry：客户端卡片组件注册表（cardType → CardComponent，无状态）。
+ * 模块在 clientModule.register(ctx) 内 ctx.cards.registerMap(map) 注册组件。
+ * 与 server 端 CardRegistry 对称：server 注册数据契约（CardMeta），client 注册渲染组件。
+ *
+ * 三通道（单一模板统一化 W3-2）：
+ * - 原始注册（registerMap）：模块自有卡组件（RawCardRenderer 消费面）；
+ * - 覆盖注册（registerOverride）：聊天视图组合层覆盖（同 cardType 包装/替换——原始视图不受影响，
+ *   域模块包自持防嵌套语义，如 mall-home 包装 alipay-activity 的联单卡）；
+ * - 内联过滤（registerInlineFilter）：域声明哪些卡不进内联流（由域浮层自持；多域按注册序复合）。
+ * 应用组装端读取：`{...ctx.cards.getAll(), ...ctx.cards.getOverrides()}` 为聊天视图注册表；
+ * `ctx.cards.applyInlineFilters` 为 ChatPage filterInlineCards 注入值。
+ */
+declare class ClientCardRegistry {
+    private cards;
+    private overrides;
+    private inlineFilters;
+    register(cardType: string, component: CardComponent): void;
+    /**
+     * 按 map 批量注册（模块 clientModule.cards 形态；key 即 cardType）。
+     * 幂等：重复注册同一 cardType 告警并覆盖（组装端多次 registerAll 安全）。
+     */
+    registerMap(map: Record<string, CardComponent>): void;
+    /**
+     * 聊天视图覆盖注册（组合层）：同 cardType 覆盖原始注册在聊天流的渲染；
+     * 原始注册不受影响（RawCardRenderer/详情弹层仍取原始形态）。
+     * 幂等：重复覆盖告警并覆盖（组装端多次 registerAll 安全）。
+     */
+    registerOverride(cardType: string, component: CardComponent): void;
+    getOverrides(): Record<string, CardComponent>;
+    /** 内联流过滤注册（域浮层自持卡的剥离声明；复合序 = 注册序）。 */
+    registerInlineFilter(filter: InlineCardFilter): void;
+    /** 内联流过滤复合（无注册 → 恒等返回原数组引用）。 */
+    applyInlineFilters(cards: readonly TboxCardPayload[]): TboxCardPayload[];
+    resolve(cardType: string): CardComponent | undefined;
+    getAll(): Record<string, CardComponent>;
+    has(cardType: string): boolean;
+    get size(): number;
+}
+/**
+ * ClientSlotRegistry：客户端槽位注册表（slotId → 槽值，无状态）。
+ * 模块在 clientModule.register(ctx) 内注册（如 mall-home `ctx.slots.register('home', render)`）；
+ * kit 壳按槽存在性派生应用形态（home 注册 = home-first 主屏；缺席 = chat 流）。
+ * 槽 id 词汇 = TIER0 contracts KNOWN_CLIENT_SLOT_IDS（封闭集）；未知 id =
+ * 版本偏斜信号：warn + 照常注册（前向兼容——老壳消费新模块不炸，resolve 侧自然 miss 降级）。
+ */
+declare class ClientSlotRegistry {
+    private slots;
+    register<K extends ClientSlotId>(slotId: K, value: ClientSlotValueMap[K]): void;
+    resolve<K extends ClientSlotId>(slotId: K): ClientSlotValueMap[K] | undefined;
+    has(slotId: ClientSlotId): boolean;
+    get size(): number;
+}
+/**
+ * ClientContext：模块 clientModule.register(ctx) 的上下文（组装端 createClientContext() 创建一次）。
+ * cards = 卡片组件注册表；slots = 壳渲染槽注册表（单一模板统一化 W1-②：应用形态派生位）。
+ */
+interface ClientContext {
+    /** 卡片组件注册表（cardType → CardComponent） */
+    cards: ClientCardRegistry;
+    /** 壳渲染槽注册表（槽 id 契约 = KNOWN_CLIENT_SLOT_IDS） */
+    slots: ClientSlotRegistry;
+}
+/**
+ * 模块描述对象（客户端）：模块包 client 入口 export 的 clientModule。
+ *
+ * - cards：卡片组件声明 map（key 约定 = cardType；数据 + 类型源，
+ *   供 `InferModuleCards` 从装配数组自动推导 app 端 CardType）。
+ * - register(ctx)：注册期自注册（一期仅 ctx.cards.registerMap(cards)）。
+ *
+ * 与服务端 `ServerModule` 逐行对称；组装端遍历 modules 调 register(ctx)。
+ * register 为函数签名声明：method shorthand 经 `satisfies` 检查（TS 方法 bivariance——
+ * 放行比契约更窄的参数，运行时无危害；缺字段的过宽参数会被拦截）。
+ * cards 为必填属性：无卡片模块写 `cards: {}`（keyof = never，不污染装配类型）。
+ */
+interface ClientModule<C extends Record<string, CardComponent> = Record<string, CardComponent>> {
+    cards: C;
+    register: (ctx: ClientContext) => void | Promise<void>;
+}
+/**
+ * 创建客户端上下文（组装端调用一次，apps/client 模块加载期）。
+ */
+declare function createClientContext(): ClientContext;
+
+/**
+ * 运行环境识别 + API/WS 地址推导 + 启动参数读取（client 平台轴）。
+ *
+ * 本 SDK 同时跑在两种环境（都是 web）：
+ *   1. 浏览器 H5（直接访问）
+ *   2. 支付宝小程序 web-view 壳（agent-chat-h5-template-alipay）里的 H5
+ *      —— 原生能力走 postMessage 桥（见 ./bridge）。
+ *
+ * H1：SDK **零 Vite 依赖**——不读取 import.meta.env；VITE_API_URL 等环境值由组装端
+ * （模板 main.tsx）经 configureRuntime({ apiBaseUrl }) 注入。
+ */
+type RuntimeContainer = 'browser' | 'alipay-miniapp';
+/**
+ * 运行时配置注入（组装端唯一入口，模板 main.tsx 调用一次）。
+ * apiBaseUrl：HTTP API base。空串表示相对路径（同源，前后端同源部署默认形态）。
+ */
+declare function configureRuntime(opts: {
+    apiBaseUrl?: string;
+}): void;
+/** HTTP API base。空串表示相对路径（同源）。 */
+declare function getApiBaseUrl(): string;
+/** 最终 HTTP 源（用于显示/拼接）。 */
+declare function getApiOrigin(): string;
+/** WebSocket 地址：从 API origin 推导 http→ws。 */
+declare function getWsUrl(path?: string): string;
+/** 读取 URL query（壳子会把 agent_id/user_id/channel/code/env 等拼到 index.html?... 上） */
+declare function getRuntimeQuery(): Record<string, string>;
+declare function getQueryParam(key: string): string | undefined;
+/**
+ * 是否运行在支付宝小程序 web-view 壳里。
+ *
+ * 识别策略（按可靠性排序）：
+ *   1. 壳子在 web-view URL 上加的确定性标记 `?container=alipay-miniapp`（最可靠，推荐壳子配合）
+ *   2. UA 含 AlipayClient / AliApp(AP/...)（支付宝客户端 web-view 兜底）
+ * 任一命中即判定为支付宝壳环境。
+ */
+declare function isInAlipayShell(): boolean;
+/** 支付宝 web-view 桥通信能力是否已经可用。 */
+declare function hasAlipayBridge(): boolean;
+declare function getContainer(): RuntimeContainer;
+
+type AlipayNavigation = {
+    apiName: 'navigateTo';
+    params: {
+        url: string;
+    };
+} | {
+    apiName: 'navigateToMiniProgram';
+    params: {
+        appId: string;
+        path: string;
+        query?: string;
+    };
+};
+/**
+ * Resolve an Alipay startapp deep link to the native mini-program navigation API.
+ * The host app id is required because same-app pages must use navigateTo.
+ * 基于 `parseAlipayScheme`（不经 `new URL`），规避安卓/UC 内核对 `alipays://` 非特殊 scheme 的解析差异。
+ */
+declare function resolveAlipayNavigation(url: string, hostMiniAppId?: string): AlipayNavigation | undefined;
+
+interface RequestOptions {
+    /** 追加/覆盖请求头（如鉴权 token） */
+    headers?: Record<string, string>;
+    /** 取消信号 */
+    signal?: AbortSignal;
+    /** fetch 缓存模式透传（'no-store' = 绕过 HTTP 缓存读写，含存量条目） */
+    cache?: RequestCache;
+}
+interface HttpResult<T> {
+    status: number;
+    data: T;
+}
+interface ServiceClient {
+    get<T = any>(path: string, opts?: RequestOptions): Promise<HttpResult<T>>;
+    post<T = any>(path: string, body?: unknown, opts?: RequestOptions): Promise<HttpResult<T>>;
+    /** 二进制上传：Blob body 不 JSON 化、不注入 application/json（Content-Type 由调用方头承载） */
+    postBinary<T = any>(path: string, body: Blob, opts?: RequestOptions): Promise<HttpResult<T>>;
+}
+interface CreateServiceOptions {
+    /** 是否注入同源鉴权 token + 401 自动重登（默认 false；仅 defaultService 显式开启） */
+    auth?: boolean;
+    /** base 动态解析（缺省 false）：请求时调 getApiBaseUrl()——defaultService 专用（H1：configureRuntime 注入后生效，任意时机重配均跟随） */
+    dynamicBase?: boolean;
+}
+declare function configureAuthToken(fn: () => string | null): void;
+/** 401 处理器（auth-client 注册 refreshAuth；返回后调用方用新 token 重试一次） */
+type AuthErrorHandler = () => Promise<unknown>;
+declare function configureAuthErrorHandler(fn: AuthErrorHandler): void;
+/**
+ * 创建绑定到指定域名的请求客户端。
+ *
+ * @param baseUrl 目标域名（如 `https://biz.example.com`）。空串=同源（相对路径）。
+ * @param defaults 该 service 所有请求共用的默认项（如固定鉴权头）。
+ * @param opts.auth 是否注入本地 token + 401 重登（仅同源/受信域名设为 true）。
+ */
+declare function createService(baseUrl?: string, defaults?: RequestOptions, opts?: CreateServiceOptions): ServiceClient;
+/** 默认同源客户端：打本 server 的 `/api/*`。
+ * dynamicBase（H1 时序安全）：base 每次请求经 getApiBaseUrl() 动态解析——
+ * configureRuntime 在模块加载后执行且可重配，base 不得固化于模块加载时。 */
+declare const defaultService: ServiceClient;
+/** 向后兼容导出：等价于 defaultService.get / .post / .postBinary。 */
+declare const httpGet: <T = any>(path: string, opts?: RequestOptions) => Promise<HttpResult<T>>;
+declare const httpPost: <T = any>(path: string, body?: unknown, opts?: RequestOptions) => Promise<HttpResult<T>>;
+declare const httpPostBinary: <T = any>(path: string, body: Blob, opts?: RequestOptions) => Promise<HttpResult<T>>;
+
+declare global {
+    interface Window {
+        my?: AlipayWebViewMy;
+        AlipayJSBridge?: unknown;
+    }
+}
+/** 支付宝 web-view JSSDK 暴露的 my（仅用到的子集） */
+interface AlipayWebViewMy {
+    postMessage: (data: Record<string, unknown>) => void;
+    onMessage?: (e: unknown) => void;
+}
+/**
+ * 确保 JSSDK 就绪，resolve 出 `my`（浏览器环境 resolve null）。
+ * 幂等：多次调用复用同一个 Promise。
+ */
+declare function ensureAlipayJSSDK(): Promise<AlipayWebViewMy | null>;
+
+export { type AlipayNavigation, type AlipayWebViewMy, BRIDGE_NAME, BRIDGE_VERSION, type BridgeMediaFile, type BridgeReceipt, type BridgeRequest, CardCarousel, type CardComponentWithFlag, CardFrame, CardRenderer, ClientCardRegistry, type ClientContext, type ClientLogTransport, type ClientModule, ClientSlotRegistry, type CreateServiceOptions, ErrorBoundary, type HttpResult, type JsapiMode, type LoginGateReceipt, MY_ACTION, MY_CALL_ACTION, type PlateKeyboardOptions, type PlateKeyboardResult, type RequestOptions, type RuntimeContainer, type ServiceClient, StatusPill, type StatusPillTone, TBOX_ACTION, ValueText, callCapability, callJsapi, chooseImage, chooseVideo, closePlateKeyboard, configureAuthErrorHandler, configureAuthToken, configureRuntime, createClientContext, createClientLogger, createService, defaultService, ensureAlipayJSSDK, getApiBaseUrl, getApiOrigin, getAuthCode, getContainer, getLocation, getLoginState, getQueryParam, getRuntimeQuery, getWsUrl, hasAlipayBridge, httpGet, httpPost, httpPostBinary, installGlobalErrorReporting, isBridgeReceipt, isInAlipayShell, markSelfRendering, navigateToAlipayPage, openPlateKeyboard, requestPayment, resolveAlipayNavigation, setClientLogTransport, setClientRunContext };

package/dist/client/index.js

@@ -0,0 +1 @@
+import{createLogger as Vt}from"@tbox.cn/app-sdk-core";import{createCoreLogger as be,resolveLevel as j,setLogContextProvider as Ce}from"@tbox.cn/app-sdk-core";var M=null;Ce(()=>M??void 0);function he(e){M=e?{requestId:e.runId,conversationId:e.conversationId}:null}function ve(){try{if(typeof localStorage<"u")return j(localStorage.getItem("tbox:logLevel")??void 0,"info")}catch{}try{if(typeof location<"u"){let e=new URLSearchParams(location.search).get("logLevel");if(e)return j(e,"info")}}catch{}return"info"}function u(e){return be({tag:e,getLevel:ve,getContext:()=>M??void 0})}var X;function we(e){X=e}function Re(e){if(typeof window>"u"||typeof window.addEventListener!="function")return()=>{};let t=e??u("GLOBAL"),r=new Map,n=1e4,l=a=>{let o=Date.now();for(let[g,s]of r)o-s>=n&&r.delete(g);r.has(a)||(r.set(a,o),t.error(a),X?.send("error",a))},i=a=>{l(`uncaught: ${a.message} @ ${a.filename}:${a.lineno}`)},d=a=>{let o=a.reason instanceof Error?a.reason.message:String(a.reason);l(`unhandledrejection: ${o}`)};return window.addEventListener("error",i),window.addEventListener("unhandledrejection",d),()=>{window.removeEventListener("error",i),window.removeEventListener("unhandledrejection",d)}}import{Component as Te}from"react";var Ae=u("ErrorBoundary"),h=class extends Te{state={hasError:!1};static getDerivedStateFromError(){return{hasError:!0}}componentDidCatch(t){Ae.error("render error:",t)}render(){return this.state.hasError?this.props.fallback:this.props.children}};import{jsx as m,jsxs as Ie}from"react/jsx-runtime";var R={info:{bg:"rgba(22,119,255,0.08)",color:"#1677ff"},warning:{bg:"rgba(250,140,22,0.10)",color:"#d46b08"},error:{bg:"rgba(255,77,79,0.08)",color:"#ff4d4f"}};function Se({notices:e}){return e.length?m("div",{style:{display:"flex",flexDirection:"column",gap:4,marginBottom:8},children:e.map(t=>m("div",{style:{fontSize:12,lineHeight:"18px",padding:"4px 10px",borderRadius:8,background:R[t.level]?.bg??R.info.bg,color:R[t.level]?.color??R.info.color},children:t.message},`${t.code}:${t.message}`))}):null}function Pe({card:e,registry:t,onAction:r}){let n=e.status!=="error"?t[e.cardType]:void 0,l=e.status==="error"||!n,i=n?.selfRendersActions===!0,d=!e.isHistory&&!i&&e.actions?.length?e.actions:[],a=typeof e.expiresAt=="number"&&Date.now()>=e.expiresAt;return Ie("div",{className:`tbox-card${l?" tbox-card--fallback":""}${a?" tbox-card--stale":""}`,style:a?{opacity:.55,filter:"grayscale(1)"}:void 0,children:[m(Se,{notices:e.notices??[]}),e.status==="error"?`卡片渲染失败${e.error?`：${e.error}`:""}`:n?m(h,{fallback:"卡片渲染出错",children:m(n,{data:e.data,cardId:e.id,isHistory:!!e.isHistory,actionTokens:e.actionTokens})}):`未知卡片类型：${e.cardType}`,d.length>0&&m("div",{style:{display:"flex",gap:8,marginTop:8,flexWrap:"wrap"},children:d.map(o=>{let g=!o.kind||o.kind==="moduleAction",s=g?e.actionTokens?.[o.actionId]:void 0,p=o.enabled===!1,c=p||!r||g&&!s,f=()=>o.kind==="sendMessage"?{type:"sendMessage",value:o.value??o.label??o.actionId,visible:o.visible??!0}:o.kind==="openLink"?{type:"openLink",url:o.url??""}:{type:"moduleAction",actionId:o.actionId,contextToken:s??""},B=()=>o.style==="primary"?{fontSize:13,padding:"6px 14px",borderRadius:18,border:"1px solid var(--tbox-primary, #1677ff)",color:"#fff",background:"var(--tbox-primary, #1677ff)"}:o.style==="link"?{fontSize:13,padding:"6px 4px",borderRadius:4,border:"none",color:"var(--tbox-primary, #1677ff)",background:"transparent",textDecoration:"underline"}:{fontSize:13,padding:"6px 14px",borderRadius:18,border:"1px solid var(--tbox-primary, #1677ff)",color:"var(--tbox-primary, #1677ff)",background:"transparent"};return m("button",{type:"button",disabled:c,title:p?o.disabledReason:void 0,onClick:()=>!c&&r?.(f()),style:{...B(),cursor:c?"not-allowed":"pointer",opacity:c?.5:1},children:o.label??o.actionId},o.actionId)})})]})}import{Fragment as Ee,jsx as N}from"react/jsx-runtime";function ke({cards:e,renderItem:t,className:r}){if(e.length<=1)return N(Ee,{children:e.length===1?t(e[0]):null});let n=["tbox-card-stack",r].filter(Boolean).join(" ");return N("div",{className:n,style:{display:"flex",flexDirection:"column"},children:e.map(l=>N("div",{children:t(l)},l.id))})}import{jsx as v,jsxs as q}from"react/jsx-runtime";var x=(e,t)=>`var(--${e}, ${t})`;function Le(e){return e.selfRendersActions=!0,e}function Be(e){return q("div",{style:{borderRadius:12,background:x("tbox-card-bg","#ffffff"),padding:"12px 16px",boxShadow:`0 1px 4px ${x("tbox-shadow","rgba(0,0,0,0.06)")}`,...e.style},children:[(e.title||e.subtitle)&&q("div",{style:{marginBottom:8},children:[e.title&&v("div",{style:{fontSize:15,fontWeight:600,color:x("tbox-text-primary","#1a1a1a"),lineHeight:"20px"},children:e.title}),e.subtitle&&v("div",{style:{fontSize:12,color:x("tbox-text-secondary","#888888"),marginTop:2},children:e.subtitle})]}),e.children]})}function Oe(e){return q("div",{style:{display:"flex",justifyContent:"space-between",alignItems:"center",padding:"4px 0",gap:12},children:[v("span",{style:{fontSize:13,color:x("tbox-text-secondary","#888888"),flexShrink:0},children:e.label}),v("span",{style:{fontSize:13,color:x("tbox-text-primary","#1a1a1a"),textAlign:"right",wordBreak:"break-all",...e.valueStyle},children:e.value})]})}var Me={success:{fg:"#0f8a5f",bg:"#e6f7f0"},warning:{fg:"#b26a00",bg:"#fff4e0"},neutral:{fg:"#666666",bg:"#f2f3f5"}};function Ne(e){let t=Me[e.tone];return v("span",{style:{display:"inline-block",fontSize:11,lineHeight:"18px",padding:"0 8px",borderRadius:9,color:t.fg,background:t.bg,whiteSpace:"nowrap"},children:e.text})}var Y=u("bridge"),_="https://appx/web-view.min.js",b=null;function Q(){return typeof window>"u"?null:window.my&&typeof window.my.postMessage=="function"?window.my:null}function $(){if(typeof window<"u"){let e=Q();if(e)return Promise.resolve(e)}return b||(b=new Promise(e=>{if(typeof window>"u"){e(null);return}let t=!1,r=null,n=null,l=()=>{r&&clearInterval(r),n&&clearTimeout(n),document.removeEventListener("AlipayJSBridgeReady",d)},i=o=>{t||(t=!0,l(),e(o))},d=()=>{let o=Q();o&&i(o)};document.addEventListener("AlipayJSBridgeReady",d);let a=document.querySelector(`script[src="${_}"]`);a||(a=document.createElement("script"),a.src=_,document.head.appendChild(a)),a.addEventListener("load",d,{once:!0}),a.addEventListener("error",()=>{Y.warn("加载支付宝 JSSDK 失败:",_),a?.remove(),i(null)},{once:!0}),r=setInterval(d,50),n=setTimeout(()=>{Y.warn("支付宝 JSSDK 已加载，但 my.postMessage 未就绪"),i(null)},5e3),d()}),b.then(e=>{e||(b=null)}),b)}import{detailForLog as K}from"@tbox.cn/app-sdk-core";var T="open-mini-webview-bridge",qe="1.0.0",D="my",W="my.call",F="tbox";function A(e){return!!e&&typeof e=="object"&&e.bridge===T&&typeof e.requestId=="string"}var C=u("bridge"),S=new Map,Z=0,ee=!1,re=300*1e3;function _e(){return Z+=1,`h5_${Date.now()}_${Z}`}function $e(e){if(A(e)){te(e);return}let t=e,r=e;if(r&&typeof r=="object"&&(r.detail!==void 0?t=r.detail:r.data!==void 0&&(t=r.data)),typeof t=="string")try{t=JSON.parse(t)}catch{return}A(t)&&te(t)}function te(e){let t=S.get(e.requestId);if(!t){C.debug(`收到无 pending 回执 req=${e.requestId} action=${e.action}`);return}clearTimeout(t.timer),S.delete(e.requestId);let r=Date.now()-t.startedAt;e.success?(C.info(`← ${t.apiName} ok ${r}ms req=${e.requestId}`),t.resolve(e.data)):(C.warn(`← ${t.apiName} fail code=${e.code||"BRIDGE_ERROR"} ${r}ms params=${K(t.params)} req=${e.requestId}`),t.reject({code:e.code||"BRIDGE_ERROR",errorMessage:e.errorMessage||"桥调用失败"}))}async function ne(){let e=await $();return e&&!ee&&(e.onMessage=$e,ee=!0),e}function oe(e,t,r,n,l){let i=_e();return new Promise((d,a)=>{let o=setTimeout(()=>{S.delete(i),C.warn(`← ${r} fail code=BRIDGE_TIMEOUT ${l}ms params=${K(n)} req=${i}`),a({code:"BRIDGE_TIMEOUT",errorMessage:`桥调用超时: ${r}`})},l);S.set(i,{resolve:d,reject:a,timer:o,apiName:r,params:n,startedAt:Date.now()}),C.info(`→ ${t} ${r} req=${i}`),C.debug(`params=${K(n)} req=${i}`),e.postMessage({bridge:T,action:t,apiName:r,params:n,requestId:i})})}async function y(e,t={},r="invoke",n=re){let l=await ne();if(!l)throw{code:"BRIDGE_UNAVAILABLE",errorMessage:"支付宝 WebView 桥未就绪"};return oe(l,r==="call"?W:"my",e,t,n)}async function w(e,t={},r=re){let n=await ne();if(!n)throw{code:"BRIDGE_UNAVAILABLE",errorMessage:"支付宝 WebView 桥未就绪"};return oe(n,F,e,t,r)}var H=/^[A-Za-z0-9._-]{1,80}$/u,ie=/[\u0000-\u001F\u007F]/u,ae=/^[A-Za-z][A-Za-z0-9+.-]*:/u;function De(e,t){if(!t||!H.test(t))return;let r;try{r=se(e)}catch{return}if(r.protocol!=="alipays"&&r.protocol!=="alipayrisk"||r.host!=="platformapi"||r.path!=="/startapp")return;let n=(r.appId||r.query.appId||"").trim(),l=(r.query.page||"").trim(),i=(r.query.query||"").trim()||void 0,d=l.replace(/^\/+/,"");if(!(!H.test(n)||!d||ie.test(d)||ae.test(d)||d.split("/").includes(".."))){if(n===t){let a=d.includes("?")?"&":"?";return{apiName:"navigateTo",params:{url:`/${d}${i?`${a}${i}`:""}`}}}return{apiName:"navigateToMiniProgram",params:{appId:n,path:d,...i?{query:i}:{}}}}}function V(e){try{return decodeURIComponent(e)}catch{return e}}function se(e){if(!e||typeof e!="string")throw new Error("Invalid URL");let t={protocol:"",host:"",path:"",query:{page:"",appId:""},appId:"",page:{path:"",query:{}}},r=e.match(/^([a-zA-Z]+):\/\//),n=e;r&&(t.protocol=r[1],n=n.slice(r[0].length));let l=n.indexOf("?"),i=l===-1?n:n.slice(0,l),d=l===-1?"":n.slice(l+1),a=i.indexOf("/");if(a>0?(t.host=i.slice(0,a),t.path=i.slice(a)):t.host=i,d){let o="",g={};for(let s of d.split("&")){if(s.startsWith("page=")){o=s.slice(5);continue}let p=s.indexOf("="),c=p>=0?s.slice(0,p):s;if(!c)continue;let f=p>=0?s.slice(p+1):"";g[c]=V(f)}if(t.query=g,o){t.query.page=V(o),t.query.appId&&(t.appId=t.query.appId);let s=o.indexOf("?"),p=s>=0?o.slice(0,s):o;t.page.path=V(p)}}return t}function le(e){if(typeof e!="string")return;let t;try{t=se(e)}catch{return}if(t.protocol!=="alipays"&&t.protocol!=="alipayrisk"||t.host!=="platformapi"||t.path!=="/startapp")return;let r=(t.appId||t.query.appId||"").trim(),n=(t.query.page||"").trim(),l=(t.query.query||"").trim()||void 0,i=n.replace(/^\/+/,"");if(!H.test(r)||!i||ie.test(i)||ae.test(i)||i.split("/").includes(".."))return;let d=i.includes("?")?"&":"?";return{appId:r,url:`/${i}${l?`${d}${l}`:""}`}}function We(e=9,t){return y("chooseImage",t?{count:e,sourceType:t}:{count:e},"invoke")}function Fe(){return y("chooseVideo",{},"invoke")}async function Ke(){let e=await y("getLocation",{type:0});return{...e,longitude:Number(e.longitude),latitude:Number(e.latitude)}}function Ve(e=["auth_base"]){return y("getAuthCode",{scopes:e})}function He(e){return y("tradePay",{tradeNO:e,orderStr:e})}function Ue(e){let t=le(e);return t?y("navigateTo",{url:t.url}):Promise.reject({code:"INVALID_PARAMS",errorMessage:"支付宝小程序跳转链接无效"})}function Ge(e,t=300*1e3){return w("getLoginState",e??{},t)}function Je(e={}){return w("openPlateKeyboard",{...e})}function ze(){return w("closePlateKeyboard")}import{KNOWN_CLIENT_SLOT_IDS as je}from"@tbox.cn/app-contracts";var P=u("ClientCardRegistry"),de=u("ClientSlotRegistry"),I=class{cards=new Map;overrides=new Map;inlineFilters=[];register(t,r){if(!t){P.warn("register without cardType skipped");return}this.cards.has(t)&&P.warn(`overwriting existing cardType: ${t}`),this.cards.set(t,r)}registerMap(t){for(let[r,n]of Object.entries(t))this.register(r,n)}registerOverride(t,r){if(!t){P.warn("registerOverride without cardType skipped");return}this.overrides.has(t)&&P.warn(`overwriting existing override: ${t}`),this.overrides.set(t,r)}getOverrides(){return Object.fromEntries(this.overrides)}registerInlineFilter(t){this.inlineFilters.push(t)}applyInlineFilters(t){return this.inlineFilters.length===0?[...t]:this.inlineFilters.reduce((r,n)=>n(r),[...t])}resolve(t){return this.cards.get(t)}getAll(){return Object.fromEntries(this.cards)}has(t){return this.cards.has(t)}get size(){return this.cards.size}},k=class{slots=new Map;register(t,r){je.includes(t)||de.warn(`unknown slot id: ${t}（KNOWN_CLIENT_SLOT_IDS 未含——版本偏斜？照常注册）`),this.slots.has(t)&&de.warn(`overwriting existing slot: ${t}`),this.slots.set(t,r)}resolve(t){return this.slots.get(t)}has(t){return this.slots.has(t)}get size(){return this.slots.size}};function Xe(){return{cards:new I,slots:new k}}var pe="";function Ye(e){pe=(e.apiBaseUrl??"").trim().replace(/\/$/,"")}function E(){return pe}function ce(){let e=E();return e||(typeof window<"u"?`${window.location.protocol}//${window.location.host}`:"")}function Qe(e="/ws"){return ce().replace(/^http/,"ws")+e}var U=null;function ue(){if(U)return U;let e={};return typeof window<"u"&&new URLSearchParams(window.location.search).forEach((r,n)=>{e[n]=r}),U=e,e}function ge(e){return ue()[e]}function fe(){let e=ge("container");if(e==="alipay-miniapp"||e==="alipay")return!0;if(typeof navigator<"u"){let t=navigator.userAgent;if(/AlipayClient/i.test(t)||/AliApp\(AP\//i.test(t))return!0}return!1}function Ze(){if(typeof window>"u")return!1;let e=window.my;return!!(e&&typeof e.postMessage=="function")}function et(){return fe()?"alipay-miniapp":"browser"}var tt=u("HTTP"),G=null;function rt(e){G=e}var J=null;function nt(e){J=e}function ot(e,t){if(e!==401)return!1;let r=t?.code;return r==="AUTH_UNAUTHORIZED"||r==="AUTH_TOKEN_EXPIRED"}function it(e){return e.startsWith("/api/auth/")}function ye(e="",t,r={}){let n=e.replace(/\/$/,""),l=r.auth??!1,i=r.dynamicBase??!1,d=s=>({...t?.headers,...s?.headers});function a(){return i?E():n}function o(s){let p=d(s);if(l){let c=G?G():null;c&&!p.Authorization&&(p.Authorization=`Bearer ${c}`)}return p}async function g(s,p,c,f,B=0){let me=s==="POST"&&c instanceof Blob?o(f):s==="POST"?{"Content-Type":"application/json",...o(f)}:o(f),O=await fetch(a()+p,{method:s,headers:me,body:s==="POST"&&c!==void 0?c instanceof Blob?c:JSON.stringify(c):void 0,signal:f?.signal,cache:f?.cache}),z=await O.json().catch(()=>null);if(l&&B===0&&!it(p)&&ot(O.status,z)&&J){try{await J()}catch(xe){tt.warn("401 refresh failed:",xe.message)}return g(s,p,c,f,1)}return{status:O.status,data:z}}return{get:(s,p)=>g("GET",s,void 0,p),post:(s,p,c)=>g("POST",s,p,c),postBinary:(s,p,c)=>g("POST",s,p,c)}}var L=ye("",void 0,{auth:!0,dynamicBase:!0}),at=L.get,st=L.post,lt=L.postBinary;import{sanitizeForLog as ir,detailForLog as ar,truncateForLog as sr}from"@tbox.cn/app-sdk-core";export{T as BRIDGE_NAME,qe as BRIDGE_VERSION,ke as CardCarousel,Be as CardFrame,Pe as CardRenderer,I as ClientCardRegistry,k as ClientSlotRegistry,h as ErrorBoundary,D as MY_ACTION,W as MY_CALL_ACTION,Ne as StatusPill,F as TBOX_ACTION,Oe as ValueText,w as callCapability,y as callJsapi,We as chooseImage,Fe as chooseVideo,ze as closePlateKeyboard,nt as configureAuthErrorHandler,rt as configureAuthToken,Ye as configureRuntime,Xe as createClientContext,u as createClientLogger,Vt as createLogger,ye as createService,L as defaultService,ar as detailForLog,$ as ensureAlipayJSSDK,E as getApiBaseUrl,ce as getApiOrigin,Ve as getAuthCode,et as getContainer,Ke as getLocation,Ge as getLoginState,ge as getQueryParam,ue as getRuntimeQuery,Qe as getWsUrl,Ze as hasAlipayBridge,at as httpGet,st as httpPost,lt as httpPostBinary,Re as installGlobalErrorReporting,A as isBridgeReceipt,fe as isInAlipayShell,Le as markSelfRendering,Ue as navigateToAlipayPage,Je as openPlateKeyboard,He as requestPayment,De as resolveAlipayNavigation,ir as sanitizeForLog,we as setClientLogTransport,he as setClientRunContext,sr as truncateForLog};

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@tbox.cn/app-sdk-client",
+  "version": "0.21.0",
+  "type": "module",
+  "description": "tbox 应用平台 SDK client 轴：runtime/http/logger/error-boundary、桥接（支付宝 web-view）、client-context、卡片渲染基元。agent 前端运行时在 @tbox.cn/app-agent-sdk-client。",
+  "exports": {
+    ".": {
+      "types": "./dist/client/index.d.ts",
+      "import": "./dist/client/index.js"
+    },
+    "./client": {
+      "types": "./dist/client/index.d.ts",
+      "import": "./dist/client/index.js"
+    },
+    "./platform/code-inspect": {
+      "types": "./platform/code-inspect.d.cts",
+      "default": "./platform/code-inspect.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "platform",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@tbox.cn/app-contracts": "0.12.0",
+    "@tbox.cn/app-sdk-core": "0.20.0",
+    "react": "18.3.1",
+    "react-dom": "18.3.1"
+  },
+  "devDependencies": {
+    "@types/node": "24.13.3",
+    "@types/react": "18.3.31",
+    "@types/react-dom": "18.3.7",
+    "tsup": "8.5.1",
+    "typescript": "5.9.3",
+    "vitest": "4.1.10"
+  },
+  "license": "MIT",
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}

package/platform/code-inspect.cjs

@@ -0,0 +1,111 @@
+/**
+ * ============================================================================
+ * 平台配套 babel plugin - 给每个 JSXElement 注入 data-code-inspect-* 属性。
+ * 配合 tbox 平台 inspector runtime（/__vs_inspector__.js）使用，让 host 端微调浮层
+ * 能拿到源码位置，直接走「直改源码」快路径，而不是把意图发回 LLM 重新生成代码。
+ *
+ * 注入的属性（与 inspector runtime 期望严格对齐，名字别改）：
+ *   data-code-inspect-loc-filepath = 绝对路径
+ *   data-code-inspect-loc-line     = "{line}:{column}" (1-based, 来自 JSX opening tag)
+ *   data-code-inspect-jsx-tag      = JSX 标签名 (如 "div" / "Form.Item")
+ *   data-code-inspect-component    = 所在组件名 (爬 AST 找最近的函数/类组件)
+ *
+ * Vite 接入：`import { codeInspectPlugin } from '@tbox.cn/app-sdk/platform/code-inspect'`，
+ * 在 vite.config.ts 里 `react({ babel: { plugins: [...] } })`，仅 dev（command==='serve'）启用。
+ * ============================================================================
+ */
+
+const LOC_FILEPATH_ATTRIBUTE_NAME = 'data-code-inspect-loc-filepath';
+const LOC_LINE_ATTRIBUTE_NAME = 'data-code-inspect-loc-line';
+const TAG_ATTRIBUTE_NAME = 'data-code-inspect-jsx-tag';
+const COMPONENT_ATTRIBUTE_NAME = 'data-code-inspect-component';
+
+const PLUGIN_NAME = 'code-inspect-plugin';
+
+function getJsxName(nameNode) {
+  if (nameNode.type === 'JSXIdentifier') return nameNode.name;
+  if (nameNode.type === 'JSXMemberExpression') {
+    return getJsxName(nameNode.object) + '.' + nameNode.property.name;
+  }
+  return '';
+}
+
+function getCurrentComponentName(path) {
+  let current = path;
+  while (current) {
+    if (current.isFunctionDeclaration() && current.node.id) {
+      return current.node.id.name;
+    }
+    if (
+      current.isVariableDeclarator() &&
+      current.node.id &&
+      current.node.init
+    ) {
+      const init = current.node.init;
+      if (
+        init.type === 'ArrowFunctionExpression' ||
+        init.type === 'FunctionExpression'
+      ) {
+        return current.node.id.name;
+      }
+    }
+    if (current.isClassDeclaration() && current.node.id) {
+      return current.node.id.name;
+    }
+    if (
+      (current.isFunctionExpression() ||
+        current.isArrowFunctionExpression() ||
+        current.isCallExpression()) &&
+      current.parent &&
+      current.parent.type === 'VariableDeclarator' &&
+      current.parent.id
+    ) {
+      return current.parent.id.name;
+    }
+    current = current.parentPath;
+  }
+  return 'Unknown';
+}
+
+function CodeInspectPlugin(babel) {
+  const t = babel.types;
+
+  return {
+    name: PLUGIN_NAME,
+    visitor: {
+      JSXElement(path) {
+        const node = path.node;
+        const nodeName = getJsxName(node.openingElement.name);
+        if (!nodeName) return;
+        if (!node.loc) return;
+
+        const filename = path.hub.file.opts.filename || 'unknown';
+        const { line, column } = node.loc.start;
+        const componentName = getCurrentComponentName(path);
+
+        node.openingElement.attributes.push(
+          t.jsxAttribute(
+            t.jsxIdentifier(LOC_FILEPATH_ATTRIBUTE_NAME),
+            t.stringLiteral(filename),
+          ),
+          t.jsxAttribute(
+            t.jsxIdentifier(LOC_LINE_ATTRIBUTE_NAME),
+            t.stringLiteral(`${line}:${column}`),
+          ),
+          t.jsxAttribute(
+            t.jsxIdentifier(TAG_ATTRIBUTE_NAME),
+            t.stringLiteral(nodeName),
+          ),
+          t.jsxAttribute(
+            t.jsxIdentifier(COMPONENT_ATTRIBUTE_NAME),
+            t.stringLiteral(componentName),
+          ),
+        );
+      },
+    },
+  };
+}
+
+module.exports = CodeInspectPlugin;
+module.exports.CodeInspectPlugin = CodeInspectPlugin;
+module.exports.PLUGIN_NAME = PLUGIN_NAME;

package/platform/code-inspect.d.cts

@@ -0,0 +1,22 @@
+/**
+ * 平台 code-inspect babel plugin 类型声明（最小结构面，不引 @babel/core 类型依赖）。
+ * 运行时实现见同目录 code-inspect.cjs；vite.config.ts 接入示例见 .cjs 头注释。
+ */
+declare function CodeInspectPlugin(babel: {
+  types: {
+    jsxAttribute: (name: unknown, value: unknown) => unknown;
+    jsxIdentifier: (name: string) => unknown;
+    stringLiteral: (value: string) => unknown;
+  };
+}): {
+  name: string;
+  visitor: Record<string, (path: unknown) => void>;
+};
+
+/** default = 插件工厂函数本身（CJS module.exports），.CodeInspectPlugin/.PLUGIN_NAME 为挂载属性 */
+declare const codeInspectPlugin: typeof CodeInspectPlugin & {
+  CodeInspectPlugin: typeof CodeInspectPlugin;
+  PLUGIN_NAME: string;
+};
+
+export default codeInspectPlugin;