@doubao-apps/create 0.0.29-rc.0 → 0.0.30

package/dist/template-starter/references/reference/open-api/09-/345/274/200/346/224/276/350/203/275/345/212/233-/344/270/232/345/212/241/350/203/275/345/212/233.md

@@ -0,0 +1,929 @@
+# Open API: 开放能力 / 业务能力
+
+开放业务能力、支付、隐私设置、上下文和外部应用打开。
+
+[返回目录](./README.md) | [返回速查](../open-api.md)
+
+## 速查
+
+| API | 说明 |
+| --- | --- |
+| [dispatchActionDirective](#dispatchactiondirective) | 描述用户行为，约束模型行为并指定后续执行路径。<br><br>适用于卡片交互后向模型补充结构化动作上下文，例如按钮点击、选项选择或表单提交。 |
+| [expiredWidget](#expiredwidget) | 更新过期的 widget 为固定卡片。 |
+| [loginWithDoubaoWidget](#loginwithdoubaowidget) | 发起豆包 Widget 登录。 |
+| [login](#login) | 发起登录并获取登录凭证。 |
+| [postLoginResult](#postloginresult) | 回传 MCP 授权登录凭证。 |
+| [createSignOrder](#createsignorder) | 创建签约订单。 |
+| [getOrderPaymentWithSign](#getorderpaymentwithsign) | 使用签名信息拉起收银台完成订单支付。 |
+| [getOrderPayment](#getorderpayment) | 拉起收银台完成订单支付。 |
+| [requestCombineOrder](#requestcombineorder) | 请求创建合单订单。 |
+| [requestOrder](#requestorder) | 发起订单支付流程。 |
+| [sign](#sign) | 拉起签约流程。 |
+| [getPrivacySetting](#getprivacysetting) | 获取隐私设置状态。 |
+| [sendQueryMessage](#sendquerymessage) | 以用户身份发送一条消息。<br><br>返回 void，不是 Promise。 |
+| [setAdditionalContext](#setadditionalcontext) | 设置全局上下文供大模型理解。<br><br>设置全局上下文。 |
+| [updateModelContext](#updatemodelcontext) | 向 Agent 捐赠上下文。 |
+| [updateWidget](#updatewidget) | 更新指定卡片。 |
+| [openApp](#openapp) | 通过 deep link 等方式打开外部应用。 |
+
+## API 详情
+
+<a id="dispatchactiondirective"></a>
+### dispatchActionDirective()
+
+> **dispatchActionDirective**(`params`): `Promise`\<`object`\>
+
+描述用户行为，约束模型行为并指定后续执行路径。
+
+#### Parameters
+
+• **params**: [`DispatchActionDirectiveParams`](#dispatchactiondirectiveparams)
+
+动作描述、预期行为及工具调用约束参数。
+
+#### Returns
+
+`Promise`\<`object`\>
+
+返回一个 Promise，在动作指令成功下发时解析。
+
+#### Remarks
+
+适用于卡片交互后向模型补充结构化动作上下文，例如按钮点击、选项选择或表单提交。
+
+<a id="expiredwidget"></a>
+### expiredWidget()
+
+> **expiredWidget**(`__namedParameters`): `Promise`\<`object`\>
+
+更新过期的 widget 为固定卡片
+
+#### Parameters
+
+• **\_\_namedParameters**: [`ExpiredWidgetParams`](#expiredwidgetparams)
+
+#### Returns
+
+`Promise`\<`object`\>
+
+#### Description
+
+用于将状态已经过期的 widget 实例转换为固定的卡片
+
+#### Example
+
+```ts
+expiredWidget({
+  widgetInstanceId: 'instance_123',
+  url: '${pageId}?key=value'
+});
+```
+
+<a id="loginwithdoubaowidget"></a>
+### loginWithDoubaoWidget()
+
+> **loginWithDoubaoWidget**(`params`): `Promise`\<[`LoginWithWidgetResult`](#loginwithwidgetresult)\>
+
+发起豆包 Widget 登录。
+
+#### Parameters
+
+• **params**: [`LoginWithWidgetRequest`](#loginwithwidgetrequest)
+
+Widget 登录参数。
+
+#### Returns
+
+`Promise`\<[`LoginWithWidgetResult`](#loginwithwidgetresult)\>
+
+返回登录结果。
+
+<a id="login"></a>
+### login()
+
+> **login**(`params`?): `Promise`\<[`LoginResult`](#loginresult)\>
+
+发起登录并获取登录凭证。
+
+#### Parameters
+
+• **params?**: [`LoginRequest`](#loginrequest)
+
+登录参数。
+
+#### Returns
+
+`Promise`\<[`LoginResult`](#loginresult)\>
+
+返回包含登录凭证 code 的 Promise。
+
+<a id="postloginresult"></a>
+### postLoginResult()
+
+> **postLoginResult**(`params`): `Promise`\<`object`\>
+
+回传 MCP 授权登录凭证。
+
+#### Parameters
+
+• **params**: [`PostLoginResultRequest`](#postloginresultrequest)
+
+登录结果回传参数。
+
+#### Returns
+
+`Promise`\<`object`\>
+
+返回回传完成的 Promise。
+
+<a id="createsignorder"></a>
+### createSignOrder()
+
+> **createSignOrder**(`params`): `Promise`\<[`CreateSignOrderResult`](#createsignorderresult)\>
+
+创建签约订单。
+
+#### Parameters
+
+• **params**: [`CreateSignOrderParams`](#createsignorderparams)
+
+签约订单参数
+
+#### Returns
+
+`Promise`\<[`CreateSignOrderResult`](#createsignorderresult)\>
+
+返回一个 Promise，解析为签约订单结果。
+
+<a id="getorderpaymentwithsign"></a>
+### getOrderPaymentWithSign()
+
+> **getOrderPaymentWithSign**(`params`): `Promise`\<[`GetOrderPaymentResult`](#getorderpaymentresult)\>
+
+使用签名信息拉起收银台完成订单支付。
+
+#### Parameters
+
+• **params**: [`GetOrderPaymentWithSignParams`](#getorderpaymentwithsignparams)
+
+签名支付参数
+
+#### Returns
+
+`Promise`\<[`GetOrderPaymentResult`](#getorderpaymentresult)\>
+
+返回一个 Promise，成功时解析为订单支付结果。
+
+<a id="getorderpayment"></a>
+### getOrderPayment()
+
+> **getOrderPayment**(`params`): `Promise`\<[`GetOrderPaymentResult`](#getorderpaymentresult)\>
+
+拉起收银台完成订单支付。
+
+#### Parameters
+
+• **params**: [`GetOrderPaymentParams`](#getorderpaymentparams)
+
+支付参数
+
+#### Returns
+
+`Promise`\<[`GetOrderPaymentResult`](#getorderpaymentresult)\>
+
+返回一个 Promise，成功时解析为订单支付结果。
+
+<a id="requestcombineorder"></a>
+### requestCombineOrder()
+
+> **requestCombineOrder**(`params`): `Promise`\<[`RequestCombineOrderResult`](#requestcombineorderresult)\>
+
+请求创建合单订单。
+
+#### Parameters
+
+• **params**: [`RequestCombineOrderParams`](#requestcombineorderparams)
+
+合单订单参数
+
+#### Returns
+
+`Promise`\<[`RequestCombineOrderResult`](#requestcombineorderresult)\>
+
+返回一个 Promise，解析为合单订单结果。
+
+<a id="requestorder"></a>
+### requestOrder()
+
+> **requestOrder**(`params`): `Promise`\<[`RequestOrderResult`](#requestorderresult)\>
+
+发起订单支付流程。
+
+#### Parameters
+
+• **params**: [`RequestOrderParams`](#requestorderparams)
+
+订单支付请求参数。
+
+#### Returns
+
+`Promise`\<[`RequestOrderResult`](#requestorderresult)\>
+
+返回订单支付请求结果。
+
+<a id="sign"></a>
+### sign()
+
+> **sign**(`params`): `Promise`\<[`SignResult`](#signresult)\>
+
+拉起签约流程。
+
+#### Parameters
+
+• **params**: [`SignParams`](#signparams)
+
+签约参数
+
+#### Returns
+
+`Promise`\<[`SignResult`](#signresult)\>
+
+返回一个 Promise，解析为签约结果。
+
+<a id="getprivacysetting"></a>
+### getPrivacySetting()
+
+> **getPrivacySetting**(`params`?): `Promise`\<[`PrivacySettingResult`](#privacysettingresult)\>
+
+获取隐私设置状态。
+
+#### Parameters
+
+• **params?**
+
+#### Returns
+
+`Promise`\<[`PrivacySettingResult`](#privacysettingresult)\>
+
+返回隐私设置状态。
+
+<a id="sendquerymessage"></a>
+### sendQueryMessage()
+
+> **sendQueryMessage**(`params`): `void`
+
+以用户身份发送一条消息
+
+由于会自动获取页面上下文来确定向哪个 bot 发送消息，因此只能在卡片或页面中调用
+
+#### Parameters
+
+• **params**: [`SendQueryMessageParams`](#sendquerymessageparams)
+
+#### Returns
+
+`void`
+
+#### Example
+
+```ts
+await sendQueryMessage({ content: '订阅消息', type: 'text' })
+```
+
+<a id="setadditionalcontext"></a>
+### setAdditionalContext()
+
+> **setAdditionalContext**(`params`): `Promise`\<`object`\>
+
+设置全局上下文供大模型理解
+
+#### Parameters
+
+• **params**: [`SetAdditionalContextParams`](#setadditionalcontextparams)
+
+#### Returns
+
+`Promise`\<`object`\>
+
+#### Remarks
+
+设置全局上下文。
+
+<a id="updatemodelcontext"></a>
+### updateModelContext()
+
+> **updateModelContext**(`params`): `Promise`\<`object`\>
+
+向 Agent 捐赠上下文
+
+#### Parameters
+
+• **params**: [`UpdateModelContextParams`](#updatemodelcontextparams)
+
+#### Returns
+
+`Promise`\<`object`\>
+
+<a id="updatewidget"></a>
+### updateWidget()
+
+> **updateWidget**(`params`): `Promise`\<`object`\>
+
+更新指定卡片
+
+#### Parameters
+
+• **params**: [`UpdateWidgetParams`](#updatewidgetparams)
+
+#### Returns
+
+`Promise`\<`object`\>
+
+<a id="openapp"></a>
+### openApp()
+
+> **openApp**(`params`): `Promise`\<[`OpenAppResult`](#openappresult)\>
+
+通过 deep link 等方式打开外部应用。
+
+#### Parameters
+
+• **params**: [`OpenAppRequest`](#openapprequest)
+
+外部应用打开参数。
+
+#### Returns
+
+`Promise`\<[`OpenAppResult`](#openappresult)\>
+
+返回外部应用打开结果。
+
+## 相关类型
+
+<a id="dispatchactiondirectiveparams"></a>
+### DispatchActionDirectiveParams
+
+下发动作指令的请求参数。
+
+#### Properties
+
+##### actionDescribe
+
+> **actionDescribe**: `string`
+
+自然语言描述，例如：用户点击支付按钮并完成话费支付
+
+##### actionType
+
+> **actionType**: [`ActionDirectiveType`](#actiondirectivetype)
+
+动作类型，参见 [ActionDirectiveType](#actiondirectivetype)
+
+##### expectedAction
+
+> **expectedAction**: `string`
+
+自然语言描述，例如：调用话费账单查询工具，基于工具返回回复用户。如果有卡片需要引用卡片
+
+##### responseHint?
+
+> `optional` **responseHint**: `string`
+
+自然语言描述，例如：严格参照提供的工具入参来调用工具，不要调用除bill_check以外的其他工具，只能严格基于bill_check工具返回结果进行回复
+
+##### toolName?
+
+> `optional` **toolName**: `string`
+
+mcp名称，如果expectedAction里预期要调用工具，需要在这里写明调用工具的mcp name
+
+##### toolParams?
+
+> `optional` **toolParams**: `Record`\<`string`, `string`\>
+
+mcp入参，如果expectedAction里预期要调用工具，需要在这里写明调用工具的入参
+
+##### widgetInstanceId
+
+> **widgetInstanceId**: `string`
+
+会话消息关联的卡片ID
+
+<a id="actiondirectivetype"></a>
+### ActionDirectiveType
+
+用户动作指令类型。
+
+#### Enumeration Members
+
+##### BUTTON\_CLICK
+
+> **BUTTON\_CLICK**: `"button_click"`
+
+按钮点击
+
+##### FORM\_SUBMIT
+
+> **FORM\_SUBMIT**: `"form_submit"`
+
+表单提交（复杂的信息提交场景）
+
+##### OPTION\_SELECT
+
+> **OPTION\_SELECT**: `"option_select"`
+
+选择（下拉列表场景）
+
+<a id="expiredwidgetparams"></a>
+### ExpiredWidgetParams
+
+#### Properties
+
+##### detailText?
+
+> `optional` **detailText**: `string`
+
+点击失效卡要跳转的页面 detailText
+
+##### ~~schema?~~
+
+> `optional` **schema**: `string`
+
+点击失效卡要跳转的页面 schema，格式与 navigateTo 的 url 相同
+
+###### Deprecated
+
+使用 url 字段替代 schema 字段，后续版本将移除 schema 字段，请尽快迁移到 url 字段
+
+##### title?
+
+> `optional` **title**: `string`
+
+点击失效卡要跳转的页面 title
+
+##### url?
+
+> `optional` **url**: `string`
+
+点击失效卡要跳转的页面 url 或 sslocal schema
+
+##### widgetInstanceId
+
+> **widgetInstanceId**: `string`
+
+卡片实例 ID，在卡片环境通过getWidgetInstanceId来获取，其他环境（比如页面）需要通过传参或通信的方式传递过去
+
+<a id="loginwithwidgetrequest"></a>
+### LoginWithWidgetRequest
+
+#### Properties
+
+##### loginType
+
+> **loginType**: [`LoginType`](#logintype-1)
+
+Login type identifier
+
+<a id="loginwithwidgetresult"></a>
+### LoginWithWidgetResult
+
+#### Properties
+
+##### result
+
+> **result**: `boolean`
+
+Whether the login is successful
+
+<a id="logintype-1"></a>
+<a id="logintype"></a>
+### LoginType
+
+> **LoginType**: `0` \| `1` \| `2` \| `3`
+
+Widget 登录类型。
+
+- `0`: 隐私协议登录
+- `1`: 仅登录
+- `2`: 先登录再隐私协议，两次弹窗
+- `3`: 登录和隐私协议合并，一次弹窗
+
+<a id="loginrequest"></a>
+### LoginRequest
+
+#### Properties
+
+##### timeout?
+
+> `optional` **timeout**: `number`
+
+Timeout in milliseconds
+
+<a id="loginresult"></a>
+### LoginResult
+
+#### Properties
+
+##### code
+
+> **code**: `string`
+
+Login credential code
+
+<a id="postloginresultrequest"></a>
+### PostLoginResultRequest
+
+#### Properties
+
+##### code?
+
+> `optional` **code**: `string`
+
+Authorization login credential, valid when login result is true
+
+##### result
+
+> **result**: `boolean`
+
+Login result, true means success, false means failure
+
+<a id="createsignorderparams"></a>
+### CreateSignOrderParams
+
+#### Properties
+
+##### data
+
+> **data**: `string`
+
+签约订单请求数据。
+
+##### dbAuthorization
+
+> **dbAuthorization**: `string`
+
+签约订单授权信息。
+
+<a id="createsignorderresult"></a>
+### CreateSignOrderResult
+
+> **CreateSignOrderResult**: [`CreateSignOrderSuccessResult`](#createsignordersuccessresult) \| [`CreateSignOrderFailResult`](#createsignorderfailresult)
+
+<a id="createsignorderfailresult"></a>
+### CreateSignOrderFailResult
+
+#### Properties
+
+##### errLogId?
+
+> `optional` **errLogId**: `string`
+
+用于问题排查的错误日志 ID。
+
+##### errMsg
+
+> **errMsg**: `string`
+
+错误信息。
+
+##### errNo
+
+> **errNo**: `string`
+
+错误码。
+
+<a id="createsignordersuccessresult"></a>
+### CreateSignOrderSuccessResult
+
+#### Properties
+
+##### authOrderId
+
+> **authOrderId**: `string`
+
+签约订单 ID。
+
+##### logId
+
+> **logId**: `string`
+
+用于问题排查的日志 ID。
+
+<a id="getorderpaymentresult"></a>
+### GetOrderPaymentResult
+
+#### Properties
+
+##### logId
+
+> **logId**: `string`
+
+用于问题排查的日志 ID。
+
+##### orderId
+
+> **orderId**: `string`
+
+订单 ID。
+
+<a id="getorderpaymentwithsignparams"></a>
+### GetOrderPaymentWithSignParams
+
+#### Properties
+
+##### orderId
+
+> **orderId**: `string`
+
+订单 ID。
+
+##### signData
+
+> **signData**: `string`
+
+支付签名数据。
+
+##### signDbAuthorization
+
+> **signDbAuthorization**: `string`
+
+签名支付授权信息。
+
+<a id="getorderpaymentparams"></a>
+### GetOrderPaymentParams
+
+#### Properties
+
+##### orderId
+
+> **orderId**: `string`
+
+订单 ID。
+
+<a id="requestcombineorderparams"></a>
+### RequestCombineOrderParams
+
+#### Properties
+
+##### data
+
+> **data**: `string`
+
+合单订单请求数据。
+
+##### dbAuthorization
+
+> **dbAuthorization**: `string`
+
+合单订单授权信息。
+
+<a id="requestcombineorderresult"></a>
+### RequestCombineOrderResult
+
+> **RequestCombineOrderResult**: [`RequestCombineOrderSuccessResult`](#requestcombineordersuccessresult) \| [`RequestCombineOrderFailResult`](#requestcombineorderfailresult)
+
+<a id="requestcombineorderfailresult"></a>
+### RequestCombineOrderFailResult
+
+#### Properties
+
+##### errLogId?
+
+> `optional` **errLogId**: `string`
+
+用于问题排查的错误日志 ID。
+
+##### errMsg
+
+> **errMsg**: `string`
+
+错误信息。
+
+##### errNo
+
+> **errNo**: `string`
+
+错误码。
+
+<a id="requestcombineordersuccessresult"></a>
+### RequestCombineOrderSuccessResult
+
+#### Properties
+
+##### combineOrderId
+
+> **combineOrderId**: `string`
+
+合单订单 ID。
+
+##### logId
+
+> **logId**: `string`
+
+用于问题排查的日志 ID。
+
+<a id="requestorderparams"></a>
+### RequestOrderParams
+
+#### Properties
+
+##### data
+
+> **data**: `string`
+
+##### dbAuthorization
+
+> **dbAuthorization**: `string`
+
+<a id="requestorderresult"></a>
+### RequestOrderResult
+
+#### Properties
+
+##### logId
+
+> **logId**: `string`
+
+##### orderId
+
+> **orderId**: `string`
+
+<a id="signparams"></a>
+### SignParams
+
+#### Properties
+
+##### orderId
+
+> **orderId**: `string`
+
+签约订单 ID。
+
+<a id="signresult"></a>
+### SignResult
+
+> **SignResult**: [`SignSuccessResult`](#signsuccessresult) \| [`SignFailResult`](#signfailresult)
+
+<a id="signfailresult"></a>
+### SignFailResult
+
+#### Properties
+
+##### code
+
+> **code**: `number`
+
+错误码。
+
+##### errLogId?
+
+> `optional` **errLogId**: `string`
+
+用于问题排查的错误日志 ID。
+
+##### errMsg
+
+> **errMsg**: `string`
+
+错误信息。
+
+##### errNo
+
+> **errNo**: `string`
+
+错误编号。
+
+<a id="signsuccessresult"></a>
+### SignSuccessResult
+
+> **SignSuccessResult**: `Record`\<`string`, `never`\>
+
+<a id="privacysettingresult"></a>
+### PrivacySettingResult
+
+#### Properties
+
+##### needAuthorization
+
+> **needAuthorization**: `boolean`
+
+Whether user authorization for privacy agreement is required
+
+<a id="sendquerymessageparams"></a>
+### SendQueryMessageParams
+
+#### Properties
+
+##### content
+
+> **content**: `string`
+
+要发送的消息。根据类型不同，序列化方式可能不同
+
+##### type
+
+> **type**: `"text"`
+
+消息类型，目前仅支持 text
+
+<a id="setadditionalcontextparams"></a>
+### SetAdditionalContextParams
+
+#### Properties
+
+##### additionalContext
+
+> **additionalContext**: `string`
+
+上下文内容
+
+##### botId?
+
+> `optional` **botId**: `string`
+
+指定 bot id
+
+<a id="updatemodelcontextparams"></a>
+### UpdateModelContextParams
+
+#### Properties
+
+##### content
+
+> **content**: `string`
+
+上下文内容，格式无约束，可以与 MCP 服务下发的上下文格式保持一致
+
+##### entityId?
+
+> `optional` **entityId**: `string`
+
+上下文所属的 entityID，业务侧管理
+
+##### taskId?
+
+> `optional` **taskId**: `string`
+
+上下文所属任务 ID，业务侧定义
+
+<a id="updatewidgetparams"></a>
+### UpdateWidgetParams
+
+#### Properties
+
+##### widgetData
+
+> **widgetData**: `string`
+
+卡片渲染的数据
+
+##### widgetId?
+
+> `optional` **widgetId**: `string`
+
+卡片更新的为新的widgetId
+
+##### widgetInstanceId
+
+> **widgetInstanceId**: `string`
+
+需要更新的widget 实例 ID
+
+<a id="openapprequest"></a>
+### OpenAppRequest
+
+#### Properties
+
+##### fallbackUrl?
+
+> `optional` **fallbackUrl**: `string`
+
+Optional fallback URL when deep link fails
+
+##### targetPackage?
+
+> `optional` **targetPackage**: `string`
+
+Optional target package name for Android
+
+##### uri
+
+> **uri**: `string`
+
+Target URI to open, e.g. scheme://path?query
+
+<a id="openappresult"></a>
+### OpenAppResult
+
+#### Properties
+
+##### status
+
+> **status**: [`OpenAppStatus`](#openappstatus)
+
+Execution status from client
+
+<a id="openappstatus"></a>
+### OpenAppStatus
+
+> **OpenAppStatus**: `"deep_link"` \| `"market"` \| `"browser"`