@doubao-dev/framework 0.0.42 → 0.1.0

package/dist/components.d.ts

@@ -88,6 +88,10 @@ export declare interface Arc {
     zIndex?: number;
 }
 
+export declare type AudioProps = Omit<VideoEngineProps, 'as' | 'style' | 'poster' | 'objectfit' | 'fullscreenMode' | 'resolution' | 'onFirstFrame' | 'scene' | 'onAppear' | 'onDisappear'>;
+
+export declare type AudioRef = VideoEngineRef;
+
 declare interface BounceConfig {
     /**
      * 是否启用回弹效果，当 loop 为 true 时忽略此设置
@@ -1549,7 +1553,7 @@ export declare interface MapMarkerProps {
 
 export declare type MapMarkerRef = {
     /**
-     * 刷新标记点样式。当自定义内容（children）样式变化时调用此方法更新。
+     * @deprecated 豆包 14.9.0 及以上版本已支持 marker 响应式刷新，无需手动调用。
      */
     refreshMarker: () => void;
 };
@@ -1630,6 +1634,8 @@ export declare interface MapProps {
     showScale?: boolean;
     /**
      * 是否显示当前位置标记。开启后会调用定位 API 获取并监听当前位置变化，使用内置 marker 图标展示。
+     * 使用前需在 Manifest 中声明 `scope.userLocation`，并将该权限配置为 JSB 类型。
+     * 未正确声明时不会触发授权弹窗，也不会展示当前位置标记。
      * @defaultValue false
      */
     showLocation?: boolean;
@@ -4290,8 +4296,8 @@ declare enum VideoEngineOption {
 
 declare type VideoEnginePlaybackCallback = (success: boolean, errCode?: number, errMsg?: string) => void;
 
-export declare interface VideoProps {
-    ref?: ForwardedRef<VideoRef>;
+declare interface VideoEngineProps {
+    ref?: ForwardedRef<VideoEngineRef>;
     /**
      * Style for wrapper, especially for border-radius
      * @zh 包装器的样式，特别用于设置圆角
@@ -4681,7 +4687,7 @@ export declare interface VideoProps {
     onDisappear?: () => void;
 }
 
-export declare interface VideoRef {
+declare interface VideoEngineRef {
     /**
      * Start playing. You should start play after resource redirect (after `onRedirected`)
      * @zh 开始播放。你应该在资源重定向后（`onRedirected`）开始播放
@@ -4851,6 +4857,10 @@ export declare interface VideoRef {
     operatePoster: (display: boolean) => void;
 }
 
+export declare type VideoProps = VideoEngineProps;
+
+export declare type VideoRef = VideoEngineRef;
+
 /**
  * 基础布局容器，用于组织和嵌套其他组件，支持 Flexbox 布局。
  */
@@ -5005,7 +5015,42 @@ declare interface WebGLContextAttributes_2 {
  * // 或按需导入：import { postMessage, onMessage } from '@doubao-dev/webview-jssdk';
  * ```
  *
- * 应用侧：`src` 指向 H5 地址，`ref` 用于拿到 `postMessage`，`onMessage` 接收 H5 消息。
+ * ## H5 可用 API
+ *
+ * WebView JSSDK 当前提供以下 API：
+ *
+ * | API | 返回值 | 说明 |
+ * | --- | --- | --- |
+ * | `doubao.navigateTo({ url })` | `Promise<unknown>` | 保留当前页面，跳转到智能服务内页面 |
+ * | `doubao.navigateBack({ delta? })` | `Promise<unknown>` | 返回智能服务内的上一页或多级页面，`delta` 默认为 `1` |
+ * | `doubao.redirectTo({ url })` | `Promise<unknown>` | 关闭当前页面，跳转到智能服务内页面 |
+ * | `doubao.reLaunch({ url })` | `Promise<unknown>` | 关闭所有页面，跳转到智能服务内页面 |
+ * | `doubao.postMessage({ data })` | `Promise<unknown>` | 向应用侧的 `<web-view onMessage>` 发送消息 |
+ * | `doubao.setTitle({ title })` | `Promise<unknown>` | 设置应用侧 WebView 头部标题 |
+ * | `doubao.onMessage(handler)` | `() => void` | 监听应用侧消息，返回注销函数 |
+ *
+ * 路由 API 的 `url` 是智能服务内页面路径，不是 H5 页面地址。
+ *
+ * ## 安全限制
+ *
+ * 1. **URL 协议限制**：`src` 仅支持 `https://` 协议，不支持 `http://`、`file://` 等其他协议。
+ * 2. **JSB 白名单**：白名单外的 JSB 调用会被拦截并返回错误；其他 API 调用需要通过消息通道
+ *    交给智能服务页面中转。
+ * 3. **域名校验**：需要在豆包智能服务开放平台配置域名白名单，非白名单域名的 URL 将被拒绝加载。
+ *
+ * ## 判断是否在豆包智能服务中打开
+ *
+ * H5 可通过 User-Agent 中是否包含 `DoubaoApps` 判断：
+ *
+ * ```js
+ * const isInDoubaoApps = navigator.userAgent.includes('DoubaoApps');
+ * ```
+ *
+ * ## 双向通信示例
+ *
+ * ### 应用侧
+ *
+ * `src` 指向 H5 地址，`ref` 用于拿到 `postMessage`，`onMessage` 接收 H5 消息。
  *
  * ```tsx
  * import { useRef } from '@doubao-dev/framework';
@@ -5033,7 +5078,9 @@ declare interface WebGLContextAttributes_2 {
  * }
  * ```
  *
- * H5 侧：`doubao.onMessage` 接收应用消息并返回注销函数，`doubao.postMessage` 发送消息给应用。
+ * ### H5 侧
+ *
+ * `doubao.onMessage` 接收应用消息并返回注销函数，`doubao.postMessage` 发送消息给应用。
  *
  * ```js
  * const off = doubao.onMessage((raw) => {
@@ -5050,15 +5097,6 @@ declare interface WebGLContextAttributes_2 {
  * // off();
  * ```
  *
- * 三个容易踩的点：
- *
- * - 首条消息放在 `onLoad` 之后发，H5 尚未加载完成时发送的消息会丢失。
- * - 两个方向的数据形态不同：应用 → H5 时非字符串会被 `JSON.stringify`，H5 收到的是 JSON 字符串，
- *   需要自行 `JSON.parse`；H5 → 应用时 `onMessage` 的 `event.data` 保持 H5 传入的原始值。
- * - 如果两侧都写成“收到就回”，务必按消息 `type` 区分，否则会无限互相回声。
- *
- * 除消息通道外，H5 还可以调用 `doubao.setTitle({ title })` 同步应用侧 WebView 头部标题。
- *
  * ## Web 模拟器差异
  *
  * Web 模拟器中的 `<web-view>` 通过本地代理承载 H5 页面，页面脚本读取到的
@@ -5072,7 +5110,7 @@ export declare interface WebViewProps {
      */
     ref?: Ref<WebViewRef>;
     /**
-     * 网页资源地址
+     * 网页资源地址，仅支持 `https://` 协议；需要在豆包智能服务开放平台配置白名单，并通过校验
      */
     src?: string;
     /**

package/dist/config.d.ts

@@ -253,7 +253,18 @@ export declare interface DoubaoAppsPlugin {
     setup: (api: any) => void | Promise<void>;
 }
 
-export declare type DoubaoAppsToolConfig = string[];
+export declare type DoubaoAppsToolConfig = DoubaoAppsToolEntryConfig[];
+
+export declare type DoubaoAppsToolEntryConfig = string | ({
+    entry: string;
+} & DoubaoAppsToolMetaConfig);
+
+export declare type DoubaoAppsToolMetaConfig = {
+    /**
+     * Tool name. Defaults to the entry directory name.
+     */
+    name?: string;
+};
 
 export declare type DoubaoAppsWidgetConfig = DoubaoAppsWidgetEntryConfig[] | DoubaoAppsLegacyEntryConfig<DoubaoAppsWidgetMetaConfig>;
 

package/dist/index.d.ts

@@ -103,7 +103,66 @@ import { VoidFunctionComponent } from 'react';
 
 export declare type AgentEventCallback = (payload: AgentEventPayload) => void;
 
-declare type AgentEventPayload = Record<string, unknown>;
+export declare type AgentEventHandler = (name: string, payload: AgentEventPayload) => void;
+
+export declare type AgentEventPayload = Record<string, unknown>;
+
+declare interface AgreePrivacyResult {
+    /**
+     * 用户是否同意隐私协议授权。
+     */
+    result: boolean;
+}
+
+declare interface AIAppMetadata {
+    /**
+     *
+     *  豆包应用 ID
+     *
+     */
+    appId: string;
+    /**
+     * 应用名称
+     */
+    name?: string;
+    /**
+     * 应用描述
+     */
+    description?: string;
+    /**
+     * 应用图标
+     *
+     * 1x, 2x, 3x 分别对应 1x, 2x, 3x 倍的图标
+     */
+    icons?: Icons;
+    /**
+     * 应用关键词
+     */
+    keywords?: string[];
+    /**
+     * 应用版本
+     */
+    version?: string;
+    /**
+     * 是否声明小程序已适配深色模式
+     */
+    darkMode?: boolean;
+    /**
+     * 应用级对话框能力配置
+     */
+    chat?: AppletChatConfig;
+}
+
+export declare type AIToolContext = MessageMeta & {
+    /**
+     * callback Id
+     */
+    callbackId: string;
+    /**
+     * feature map
+     */
+    featureMap: Record<string, string> | undefined;
+};
 
 export declare type AIViewContext = MessageMeta & {
     /**
@@ -141,6 +200,44 @@ export declare type AIViewContext = MessageMeta & {
     };
 };
 
+export declare type AnyObject = Record<string, any>;
+
+export declare type App<T extends DefineAppOptions = DefineAppOptions> = T & {
+    readonly eventChannel: EventChannel;
+    __APP__: boolean;
+    __UI__: boolean;
+};
+
+declare type AppAIMeta = Omit<AIAppMetadata, 'appId'> & {
+    appId?: string;
+    package?: string;
+};
+
+declare interface AppletChatConfig {
+    /**
+     * App-level chat feature overrides.
+     */
+    features?: AppletChatFeaturesConfig;
+}
+
+declare interface AppletChatFeatureConfig {
+    /**
+     * Whether the chat feature is enabled.
+     */
+    enabled: boolean;
+}
+
+declare interface AppletChatFeaturesConfig {
+    /**
+     * Camera entry configuration.
+     */
+    camera?: AppletChatFeatureConfig;
+    /**
+     * Extra actions entry configuration.
+     */
+    extraActions?: AppletChatFeatureConfig;
+}
+
 export { Attributes }
 
 export { CElement }
@@ -201,12 +298,216 @@ export { createElement }
 
 export { createRef }
 
+/** 当前页面栈中的页面信息。 */
 export declare interface CurrentPage {
+    /** 页面路由。 */
     route: string;
+    /**
+     * @since 0.1.0
+     * 页面查询参数。
+     */
+    query: Record<string, string>;
 }
 
 export { CustomComponentPropsWithRef }
 
+export declare function defineApp<T extends DefineAppOptions>(options: T & ThisType<T & {
+    readonly aiMeta: AppAIMeta;
+    readonly eventChannel: EventChannel;
+}>): App<T>;
+
+export declare interface DefineAppOptions {
+    [key: string]: any;
+    /**
+     * @deprecated Configure app metadata in src/app.config.ts instead.
+     *
+     * @example
+     * ```ts
+     * // src/app.config.ts
+     * import { defineAppConfig } from '@doubao-dev/framework/config';
+     *
+     * export default defineAppConfig({
+     *   appId: 'your-app-id',
+     *   name: 'Demo App',
+     *   description: 'Describe what this app can do',
+     *   icons: 'https://example.com/icon.png',
+     *   keywords: ['demo', 'doubao']
+     * });
+     * ```
+     */
+    aiMeta?: AppAIMeta;
+    /**
+     * App launched
+     */
+    onLaunch?: () => void;
+    /**
+     * On page opened
+     */
+    onPageOpened?: (params: {
+        viewId: string;
+    }) => void;
+    /**
+     * Handle an event sent by the Agent to the app.
+     */
+    onAgentEvent?: AgentEventHandler;
+    /**
+     * On foreground
+     */
+    onForeground?: () => void;
+    /**
+     * On background
+     */
+    onBackground?: () => void;
+    /**
+     * On destroy
+     */
+    onDestroy?: () => void;
+    /**
+     * Handle errors from other App callbacks or tools in the same Applet.
+     */
+    onError?: (e: Error) => void;
+}
+
+export declare interface DefineFunctionalToolOptions extends Tool {
+    onApply: (input: string, context: AIToolContext) => string | object | Promise<string | object>;
+}
+
+export declare function defineLoginApi(api: LoginApi): LoginApi;
+
+/**
+ * 定义 MCP 登录页面
+ * @param options 定义 MCP 登录页面的选项
+ * @returns 智能服务 MCP 登录页面
+ */
+export declare function defineLoginPage<Data extends AnyObject>(options: Omit<DefinePageToolOptions<Data>, 'aiMeta'> & ThisType<Readonly<PageInstanceMethods<Data>>>): Page<Data>;
+
+export declare function definePage<Data extends AnyObject>(options: DefinePageToolOptions<Data> & ThisType<Readonly<PageInstanceMethods<Data>>>): Page<Data>;
+
+export declare interface DefinePageToolOptions<Data extends AnyObject> extends DefineUIToolOptions<Data, PageToolExtraMetadata> {
+    /**
+     * @deprecated Configure page metadata in src/app.config.ts instead.
+     *
+     * Use `pages` entries in `src/app.config.ts`. For example,
+     * `pages/home/index` maps to `src/pages/home/index.tsx`, and
+     * `pages/account/demo/index` maps to `src/pages/account/demo/index.tsx`.
+     *
+     * @example
+     * ```ts
+     * // src/app.config.ts
+     * import { defineAppConfig } from '@doubao-dev/framework/config';
+     *
+     * export default defineAppConfig({
+     *   appId: 'your-app-id',
+     *   pages: ['pages/home/index']
+     * });
+     * ```
+     */
+    aiMeta?: PageToolMetadata;
+}
+
+export declare function definePrivacyApi(api: PrivacyApi): PrivacyApi;
+
+/**
+ * 定义 MCP 同意登录和隐私协议卡片组件
+ * @param options 定义 MCP 同意登录和隐私协议卡片组件的选项
+ * @returns MCP 同意登录和隐私协议卡片组件
+ */
+export declare function definePrivacyLoginWidget<Data extends AnyObject>(options: Omit<DefineWidgetToolOptions<Data>, 'aiMeta'> & ThisType<Readonly<WidgetInstanceMethods<Data>>>): Widget<Data>;
+
+/**
+ * @deprecated Export a default Client Tool handler and configure it in `app.config.ts` instead.
+ */
+export declare function defineTool(options: DefineFunctionalToolOptions & ThisType<Readonly<FunctionalToolInstanceMethods>>): FunctionalTool;
+
+export declare interface DefineUIToolOptions<Data extends AnyObject, Extra extends AnyObject = AnyObject> extends Tool<Extra> {
+    /**
+     * Initial data
+     */
+    data?: Data;
+    /**
+     * Trigger on view created
+     * @returns
+     */
+    onCreated?: () => void;
+    /**
+     * It is triggered after the view is rendered and will only be called once in the view's life cycle.
+     * @returns
+     */
+    onMounted?: () => void;
+    /**
+     * 1. It is triggered when the view is first displayed.
+     * 2. It is triggered when the view is displayed again after being hidden.
+     * @returns
+     */
+    onShow?: () => void;
+    /**
+     * It is triggered when the view is hidden.
+     * @returns
+     */
+    onHide?: () => void;
+    /**
+     * It is triggered when the view is destroyed.
+     * @returns
+     */
+    onDestroy?: () => void;
+    /**
+     * It is triggered when an error occurs.
+     * @param e
+     * @returns
+     */
+    onError?: (e: Error) => void;
+    /**
+     * Render function
+     * Use getViewData() and getViewContext() to access data and context
+     * @returns
+     */
+    render: () => ReactNode;
+}
+
+export declare function defineWidget<Data extends AnyObject>(options: DefineWidgetToolOptions<Data> & ThisType<Readonly<WidgetInstanceMethods<Data>>>): Widget<Data>;
+
+export declare interface DefineWidgetToolOptions<Data extends AnyObject> extends DefineUIToolOptions<Data, WidgetToolExtraMetadata> {
+    /**
+     * @deprecated Configure widget metadata in src/app.config.ts instead.
+     *
+     * Use `widgets` entries in `src/app.config.ts`. For example,
+     * `widgets/card/index` maps to `src/widgets/card/index.tsx`, and
+     * `widgets/api/demo/index` maps to `src/widgets/api/demo/index.tsx`.
+     *
+     * @example
+     * ```ts
+     * // src/app.config.ts
+     * import { defineAppConfig } from '@doubao-dev/framework/config';
+     *
+     * export default defineAppConfig({
+     *   appId: 'your-app-id',
+     *   widgets: [
+     *     {
+     *       entry: 'widgets/card/index',
+     *       id: 'card-widget',
+     *       name: 'Card Widget',
+     *       description: 'Show card content',
+     *       border: true
+     *     }
+     *   ]
+     * });
+     * ```
+     */
+    aiMeta?: WidgetToolMetadata;
+    /**
+     * 1. It is triggered when the app returns to the foreground from the background.
+     * 2. It is triggered when phone is unlocked.
+     * @returns
+     */
+    onForeground?: () => void;
+    /**
+     * 1. It is triggered when the app is moved to the background.
+     * 2. It is triggered when phone is locked.
+     * @returns
+     */
+    onBackground?: () => void;
+}
+
 export { DependencyList }
 
 export { DeprecatedLifecycle }
@@ -225,6 +526,19 @@ export { ElementRef }
 
 export { ElementType }
 
+export declare type EventCallback = (...args: any[]) => void;
+
+export declare class EventChannel {
+    private readonly handleError;
+    private listeners;
+    constructor(handleError?: (error: unknown) => void);
+    emit(eventName: string, ...args: any[]): void;
+    on(eventName: string, callback: EventCallback): void;
+    once(eventName: string, callback: EventCallback): void;
+    off(eventName: string, callback?: EventCallback): void;
+    private addListener;
+}
+
 export { ExoticComponent }
 
 export { Factory }
@@ -241,24 +555,49 @@ export { ForwardRefRenderFunction }
 
 export { Fragment }
 
+export declare interface FunctionalTool extends DefineFunctionalToolOptions {
+    __FUNCTIONAL__: boolean;
+}
+
+declare type FunctionalToolInstanceMethods = Tool<ToolMetadata>;
+
 export { FunctionComponent }
 
 export { FunctionComponentElement }
 
 export { FunctionComponentFactory }
 
-export declare function getCurrentPages(): CurrentPage[];
+declare function getApp_2<T extends App = App>(): T;
+export { getApp_2 as getApp }
+
+export declare function getCurrentPages(): {
+    route: string;
+    query: Record<string, string>;
+}[];
 
 export { GetDerivedStateFromError }
 
 export { GetDerivedStateFromProps }
 
+declare interface GetPhoneNumberResult {
+    /**
+     * 获取手机号结果码。
+     */
+    code?: string;
+    /**
+     * 获取手机号结果信息。
+     */
+    message?: string;
+}
+
 export declare function getViewContext(): any;
 
 export declare function getViewData<T extends Record<string, any>>(): T;
 
 export declare function getWidgetInstanceId(): string | undefined;
 
+declare type Icons = string | Record<'1x' | '2x' | '3x', string>;
+
 export { isValidElement }
 
 export { JSXElementConstructor }
@@ -275,6 +614,13 @@ declare type LifecycleCallback = () => void;
 
 declare type LifecycleErrorCallback = (error: Error) => void;
 
+export declare interface LoginApi {
+    onLogin: (res: LoginResult) => Promise<void> | void;
+    onRefuseLogin: () => Promise<void> | void;
+}
+
+export declare type LoginResult = GetPhoneNumberResult;
+
 export { memo }
 
 export { MemoExoticComponent }
@@ -322,6 +668,36 @@ export { NamedExoticComponent }
 
 export { NewLifecycle }
 
+/**
+ * Register the runtime error handler.
+ *
+ * Calling this again replaces the previously registered handler.
+ */
+export declare function onError(callback: (error: Error) => void): void;
+
+export declare interface Page<Data extends AnyObject = AnyObject> extends DefineUIToolOptions<Data> {
+    __UI__: boolean;
+    __PAGE__: boolean;
+}
+
+declare type PageInstanceMethods<Data extends AnyObject> = UIInstanceMethods<Data, PageToolExtraMetadata>;
+
+declare type PageToolExtraMetadata = {
+    /**
+     * The page navbar title
+     */
+    title?: string;
+};
+
+export declare type PageToolMetadata = ToolMeta & PageToolExtraMetadata;
+
+export declare type PrivacyAgreeResult = AgreePrivacyResult;
+
+export declare interface PrivacyApi {
+    onAgreePrivacy: (res: PrivacyAgreeResult) => Promise<void> | void;
+    onRefusePrivacy: () => Promise<void> | void;
+}
+
 export { PropsWithChildren }
 
 export { PropsWithoutRef }
@@ -382,10 +758,57 @@ export { Suspense }
 
 export { SVGFactory }
 
+export declare interface Tool<Extra extends AnyObject = AnyObject> {
+    aiMeta?: ToolMeta & Extra;
+}
+
+export declare interface ToolMeta {
+    /**
+     * unique identifier
+     */
+    id: string;
+    /**
+     * name of the tool
+     */
+    name?: string;
+    /**
+     * description of the tool
+     */
+    description?: string;
+    /**
+     * Widget title type
+     * - none: 默认，无标题
+     * - normal: 常规标题
+     * - float: 浮动标题
+     */
+    titleType?: 'none' | 'normal' | 'float';
+}
+
+export declare type ToolMetadata = {
+    /**
+     * specifies when a call to a tool will time out, in ms.
+     */
+    timeout?: number;
+};
+
 export { TransitionFunction }
 
 export { TransitionStartFunction }
 
+export declare interface UIInstanceMethods<Data extends AnyObject, Extra extends AnyObject = AnyObject> extends Tool<Extra> {
+    /**
+     * Instance data
+     */
+    data: Data;
+    /**
+     * Set data asynchronously and trigger view re-rendering
+     * @param data
+     * @param callback
+     * @returns
+     */
+    setData: (data: Partial<Data> & AnyObject, callback?: () => void) => Promise<void>;
+}
+
 export declare function useAgentEvent(eventName: string, callback: AgentEventCallback): void;
 
 export declare function useBackground(callback: LifecycleCallback): void;
@@ -453,4 +876,37 @@ export { VFC }
 
 export { VoidFunctionComponent }
 
+export declare interface Widget<Data extends AnyObject = AnyObject> extends DefineWidgetToolOptions<Data> {
+    __UI__: boolean;
+    __WIDGET__: boolean;
+    setData: (data: Partial<Data>, callback?: () => void) => void;
+}
+
+declare type WidgetInstanceMethods<Data extends AnyObject> = UIInstanceMethods<Data, WidgetToolExtraMetadata>;
+
+declare type WidgetToolExtraMetadata = {
+    /**
+     * Widget box type in Chat UI
+     */
+    boxType?: 'inbox' | 'full_box';
+    /**
+     * Whether add widget border
+     */
+    border?: boolean;
+    /**
+     * Keywords of things
+     */
+    keywords?: string[];
+    /**
+     * Icons
+     */
+    icons?: Icons;
+    /**
+     * Set extra widget properties
+     */
+    prop?: string;
+};
+
+export declare type WidgetToolMetadata = ToolMeta & WidgetToolExtraMetadata;
+
 export { }

package/jsx-runtime.d.ts

@@ -14,6 +14,7 @@ export namespace JSX {
   interface IntrinsicClassAttributes<T> extends React.JSX.IntrinsicClassAttributes<T> {}
   interface IntrinsicElements {
     // Extended components
+    audio: import('./components.d.ts').AudioProps;
     button: import('./components.d.ts').ButtonProps;
     canvas: import('./components.d.ts').CanvasProps;
     map: import('./components.d.ts').MapProps;