@doubao-apps/ai 0.0.33 → 0.0.34

package/dist/skills/doubao-apps-dev/references/reference/open-api/10-/344/270/232/345/212/241/350/203/275/345/212/233.md

@@ -0,0 +1,431 @@
+# Open API: 业务能力
+
+开放业务能力、隐私设置、上下文和外部应用打开。
+
+[返回目录](./README.md) | [返回速查](../open-api.md)
+
+## 速查
+
+| API | 说明 |
+| --- | --- |
+| [dispatchActionDirective](#dispatchactiondirective) | 描述用户行为，约束模型行为并指定后续执行路径。 |
+| [expiredWidget](#expiredwidget) | 更新过期的 widget 为固定卡片。 |
+| [openApp](#openapp) | 通过 deep link 等方式打开外部应用。 |
+| [getPrivacySetting](#getprivacysetting) | 获取隐私设置状态。 |
+| [sendQueryMessage](#sendquerymessage) | 以用户身份发送一条消息。<br><br>返回 void，不是 Promise。 |
+| [setAdditionalContext](#setadditionalcontext) | 设置全局上下文供大模型理解。 |
+| [createTask](#createtask) | 创建任务。 |
+| [updateTask](#updatetask) | 更新任务状态或任务详情。 |
+| [getTask](#gettask) | 查询任务。 |
+| [updateModelContext](#updatemodelcontext) | 向 Agent 捐赠上下文。 |
+| [updateWidget](#updatewidget) | 更新指定卡片。 |
+
+## API 详情
+
+<a id="dispatchactiondirective"></a>
+### dispatchActionDirective()
+
+描述用户行为，约束模型行为并指定后续执行路径。
+
+## 代码示例
+
+```typescript
+import { ActionDirectiveType, dispatchActionDirective } from '@doubao-apps/framework/api';
+
+await dispatchActionDirective({
+  widgetInstanceId: 'widget-instance-id',
+  actionType: ActionDirectiveType.BUTTON_CLICK,
+  actionDescribe: '用户点击了支付按钮',
+  expectedAction: '继续完成支付流程'
+});
+```
+
+## 入参
+
+|参数名|类型|必填|说明|
+|---|---|---|---|
+|actionDescribe|`string`|是|自然语言描述，例如：用户点击支付按钮并完成话费支付|
+|actionType|`ActionDirectiveType`|是|动作类型，参见 ActionDirectiveType|
+|actionType.BUTTON_CLICK|`"button_click"`|是|按钮点击|
+|actionType.FORM_SUBMIT|`"form_submit"`|是|表单提交（复杂的信息提交场景）|
+|actionType.OPTION_SELECT|`"option_select"`|是|选择（下拉列表场景）|
+|expectedAction|`string`|是|自然语言描述，例如：调用话费账单查询工具，基于工具返回回复用户。如果有卡片需要引用卡片|
+|responseHint|`string`|否|自然语言描述，例如：严格参照提供的工具入参来调用工具，不要调用除bill_check以外的其他工具，只能严格基于bill_check工具返回结果进行回复|
+|toolName|`string`|否|mcp名称，如果expectedAction里预期要调用工具，需要在这里写明调用工具的mcp name|
+|toolParams|`Record<string, string>`|否|mcp入参，如果expectedAction里预期要调用工具，需要在这里写明调用工具的入参|
+|widgetInstanceId|`string`|是|会话消息关联的卡片ID|
+
+## 返回值
+
+返回一个 Promise，在动作指令成功下发时解析。
+
+<a id="expiredwidget"></a>
+### expiredWidget()
+
+更新过期的 widget 为固定卡片
+
+## 代码示例
+
+```ts
+expiredWidget({
+  widgetInstanceId: 'instance_123',
+  url: '${pageId}?key=value'
+});
+```
+
+## 入参
+
+|参数名|类型|必填|说明|
+|---|---|---|---|
+|detailText|`string`|否|点击失效卡要跳转的页面 detailText|
+|schema|`string`|否|点击失效卡要跳转的页面 schema，格式与 navigateTo 的 url 相同|
+|title|`string`|否|点击失效卡要跳转的页面 title|
+|url|`string`|否|点击失效卡要跳转的页面 url 或 sslocal schema|
+|widgetInstanceId|`string`|是|卡片实例 ID，在卡片环境通过getWidgetInstanceId来获取，其他环境（比如页面）需要通过传参或通信的方式传递过去|
+
+## 返回值
+
+返回 `Promise<object>`。
+
+<a id="openapp"></a>
+### openApp()
+
+通过 deep link 等方式打开外部应用。
+
+## 代码示例
+
+```typescript
+import { openApp } from '@doubao-apps/framework/api';
+
+const { status } = await openApp({
+  uri: 'demo://detail?id=1',
+  fallbackUrl: 'https://example.com/download'
+});
+
+console.log(status);
+```
+
+## 入参
+
+|参数名|类型|必填|说明|
+|---|---|---|---|
+|fallbackUrl|`string`|否|Optional fallback URL when deep link fails|
+|targetPackage|`string`|否|Optional target package name for Android|
+|uri|`string`|是|Target URI to open, e.g. scheme://path?query|
+
+## 返回值
+
+返回外部应用打开结果。
+
+|字段名|类型|说明|
+|---|---|---|
+|status|`OpenAppStatus`|Execution status from client|
+
+**类型说明**
+
+- `OpenAppStatus`: `"deep_link" | "market" | "browser"`
+
+<a id="getprivacysetting"></a>
+### getPrivacySetting()
+
+获取隐私设置状态。
+
+## 代码示例
+
+```typescript
+import { getPrivacySetting } from '@doubao-apps/framework/api';
+
+const { needAuthorization } = await getPrivacySetting();
+
+console.log(needAuthorization);
+```
+
+## 入参
+
+无入参。
+
+## 返回值
+
+返回隐私设置状态。
+
+|字段名|类型|说明|
+|---|---|---|
+|needAuthorization|`boolean`|Whether user authorization for privacy agreement is required|
+
+<a id="sendquerymessage"></a>
+### sendQueryMessage()
+
+以用户身份发送一条消息
+
+由于会自动获取页面上下文来确定向哪个 bot 发送消息，因此只能在卡片或页面中调用
+
+## 代码示例
+
+```ts
+await sendQueryMessage({ content: '订阅消息', type: 'text' })
+
+@public
+```
+
+## 入参
+
+|参数名|类型|必填|说明|
+|---|---|---|---|
+|content|`string`|是|要发送的消息。根据类型不同，序列化方式可能不同|
+|type|`"text"`|是|消息类型，目前仅支持 text|
+
+## 返回值
+
+返回 `void`。
+
+<a id="setadditionalcontext"></a>
+### setAdditionalContext()
+
+设置全局上下文供大模型理解
+
+## 代码示例
+
+```typescript
+import { setAdditionalContext } from '@doubao-apps/framework/api';
+
+await setAdditionalContext({
+  additionalContext: '用户正在查看订单详情页',
+  botId: 'bot-id'
+});
+```
+
+## 入参
+
+|参数名|类型|必填|说明|
+|---|---|---|---|
+|additionalContext|`string`|是|上下文内容|
+|botId|`string`|否|指定 bot id|
+
+## 返回值
+
+返回 `Promise<object>`。
+
+<a id="createtask"></a>
+### createTask()
+
+创建任务。
+
+## 代码示例
+
+```typescript
+import { createTask } from '@doubao-apps/framework/api';
+
+const result = await createTask({
+  outTaskId: 'order-20260529-001',
+  taskTemplate: 'remote_normal_v1',
+  taskType: 'remote',
+  taskDetail: {
+    expire_in_sec: 3600,
+    display_data: {
+      title: '订单处理中',
+      sub_title: '正在为你处理订单，请稍候'
+    }
+  }
+});
+
+console.log(result.taskId, result.token, result.expiresIn);
+```
+
+## 入参
+
+|参数名|类型|必填|说明|
+|---|---|---|---|
+|outTaskId|`string`|是|开发者侧任务唯一标识，用于幂等和关联|
+|taskDetail|`TaskDetail`|是|模板对应的数据，传入对象时会在调用 native 前自动 JSON.stringify|
+|taskDetail.display_data|`TaskDisplayData`|是|任务展示数据|
+|taskDetail.display_data.sub_title|`string`|否|任务副标题|
+|taskDetail.display_data.title|`string`|是|任务标题|
+|taskDetail.expire_in_sec|`number`|是|任务过期时间，单位：秒。任务创建后经过该时间将自动过期|
+|taskDetail.jump_page_data|`JumpSchemaData`|否|点击任务跳转的页面参数|
+|taskDetail.jump_page_data.path|`string`|否|跳转页面|
+|taskDetail.jump_page_data.query|`string`|否|页面参数，小程序内消费时会自动 base64 url encode，需要 decode|
+|taskDetail.progress_data|`TaskProgressData`|否|任务进度数据|
+|taskDetail.progress_data.progress|`number`|否|任务进度值，如百分比 0-100|
+|taskDetail.progress_data.progress_text|`string`|否|进度描述文本，如"正在处理中"|
+|taskDetail.progress_data.remaining_seconds|`number`|否|预估剩余时间，单位：秒|
+|taskDetail.remove_data|`TaskActionParams`|否|移除任务时的操作参数|
+|taskDetail.remove_data.action_key|`string`|否|操作标识|
+|taskDetail.remove_data.page_param|`string`|否|页面参数|
+|taskTemplate|`"remote_normal_v1"`|是|任务样式模板，当前仅支持 remote_normal_v1|
+|taskType|`TaskType`|是|任务类型，当前支持 local 和 remote|
+
+**类型说明**
+
+- `TaskDetail`: `string | RemoteNormalV1Detail`
+- `TaskType`: `"local" | "remote"`
+
+## 返回值
+
+返回创建后的任务 ID、远端任务 token 和过期时间。
+
+|字段名|类型|说明|
+|---|---|---|
+|expiresIn|`number`|任务超时过期时间|
+|taskId|`string`|任务 ID，后续可以使用这个 ID 更新任务|
+|token|`string`|远端任务 token，后续使用 token 通过 OpenAPI 更新远端任务|
+
+<a id="updatetask"></a>
+### updateTask()
+
+更新任务状态或任务详情。
+
+## 代码示例
+
+```typescript
+import { updateTask } from '@doubao-apps/framework/api';
+
+const result = await updateTask({
+  taskId: 'task_123',
+  taskStatus: 'completed',
+  taskDetail: {
+    expire_in_sec: 3600,
+    display_data: {
+      title: '订单已完成',
+      sub_title: '订单处理完成'
+    }
+  }
+});
+
+console.log(result.taskId, result.nextToken, result.expiresIn);
+```
+
+## 入参
+
+|参数名|类型|必填|说明|
+|---|---|---|---|
+|taskDetail|`TaskDetail`|否|模板对应的数据，传入对象时会在调用 native 前自动 JSON.stringify，与 taskStatus 二选一|
+|taskDetail.display_data|`TaskDisplayData`|否|任务展示数据|
+|taskDetail.display_data.sub_title|`string`|否|任务副标题|
+|taskDetail.display_data.title|`string`|否|任务标题|
+|taskDetail.expire_in_sec|`number`|否|任务过期时间，单位：秒。任务创建后经过该时间将自动过期|
+|taskDetail.jump_page_data|`JumpSchemaData`|否|点击任务跳转的页面参数|
+|taskDetail.jump_page_data.path|`string`|否|跳转页面|
+|taskDetail.jump_page_data.query|`string`|否|页面参数，小程序内消费时会自动 base64 url encode，需要 decode|
+|taskDetail.progress_data|`TaskProgressData`|否|任务进度数据|
+|taskDetail.progress_data.progress|`number`|否|任务进度值，如百分比 0-100|
+|taskDetail.progress_data.progress_text|`string`|否|进度描述文本，如"正在处理中"|
+|taskDetail.progress_data.remaining_seconds|`number`|否|预估剩余时间，单位：秒|
+|taskDetail.remove_data|`TaskActionParams`|否|移除任务时的操作参数|
+|taskDetail.remove_data.action_key|`string`|否|操作标识|
+|taskDetail.remove_data.page_param|`string`|否|页面参数|
+|taskId|`string`|是|任务 ID|
+|taskStatus|`TaskStatus`|否|任务状态，与 taskDetail 二选一|
+
+**类型说明**
+
+- `TaskDetail`: `string | RemoteNormalV1Detail`
+- `TaskStatus`: `"running" | "completed"`
+
+## 返回值
+
+返回任务 ID、新 token 和过期时间。
+
+|字段名|类型|说明|
+|---|---|---|
+|expiresIn|`number`|任务超时过期时间|
+|nextToken|`string`|每次更新后旧的 token 失效，必须使用新返回的 token|
+|taskId|`string`|任务 ID，更新后任务 ID 不变|
+
+<a id="gettask"></a>
+### getTask()
+
+查询任务。
+
+## 代码示例
+
+```typescript
+import { getTask } from '@doubao-apps/framework/api';
+
+const task = await getTask({ taskId: 'task_123' });
+
+if (task.taskStatus === 'running') {
+  console.log('任务仍在运行', task.taskDetail);
+}
+```
+
+## 入参
+
+|参数名|类型|必填|说明|
+|---|---|---|---|
+|taskId|`string`|是|任务 ID|
+
+## 返回值
+
+返回任务详情、状态、类型和 token 信息。
+
+|字段名|类型|说明|
+|---|---|---|
+|expiresIn|`number`|任务超时过期时间|
+|taskDetail|`string`|模板对应的数据的 JSON 字符串|
+|taskId|`string`|任务 ID|
+|taskStatus|`TaskStatus`|任务状态，运行中或已完成|
+|taskTemplate|`"remote_normal_v1"`|任务样式模板，当前仅支持 remote_normal_v1|
+|taskType|`TaskType`|任务类型，local 或 remote|
+|token|`string`|每次更新后旧的 token 失效，必须使用新返回的 token|
+
+**类型说明**
+
+- `TaskStatus`: `"running" | "completed"`
+- `TaskType`: `"local" | "remote"`
+
+<a id="updatemodelcontext"></a>
+### updateModelContext()
+
+向 Agent 捐赠上下文
+
+## 代码示例
+
+```typescript
+import { updateModelContext } from '@doubao-apps/framework/api';
+
+await updateModelContext({
+  taskId: 'task-id',
+  entityId: 'entity-id',
+  content: '用户选择了标准配送'
+});
+```
+
+## 入参
+
+|参数名|类型|必填|说明|
+|---|---|---|---|
+|content|`string`|是|上下文内容，格式无约束，可以与 MCP 服务下发的上下文格式保持一致|
+|entityId|`string`|否|上下文所属的 entityID，业务侧管理|
+|taskId|`string`|否|上下文所属任务 ID，业务侧定义|
+
+## 返回值
+
+返回 `Promise<object>`。
+
+<a id="updatewidget"></a>
+### updateWidget()
+
+更新指定卡片
+
+## 代码示例
+
+```typescript
+import { updateWidget } from '@doubao-apps/framework/api';
+
+await updateWidget({
+  widgetInstanceId: 'widget-instance-id',
+  widgetData: JSON.stringify({ title: '更新后的标题' })
+});
+```
+
+## 入参
+
+|参数名|类型|必填|说明|
+|---|---|---|---|
+|widgetData|`string`|是|卡片渲染的数据|
+|widgetId|`string`|否|卡片更新的为新的widgetId|
+|widgetInstanceId|`string`|是|需要更新的widget 实例 ID|
+
+## 返回值
+
+返回 `Promise<object>`。

package/dist/skills/doubao-apps-dev/references/reference/open-api/11-/347/231/273/345/275/225.md

@@ -0,0 +1,110 @@
+# Open API: 登录
+
+豆包登录和登录结果回传能力。
+
+[返回目录](./README.md) | [返回速查](../open-api.md)
+
+## 速查
+
+| API | 说明 |
+| --- | --- |
+| [loginWithDoubaoWidget](#loginwithdoubaowidget) | 发起豆包 Widget 登录。 |
+| [login](#login) | 发起登录并获取登录凭证。 |
+| [postLoginResult](#postloginresult) | 回传 MCP 授权登录凭证。 |
+
+## API 详情
+
+<a id="loginwithdoubaowidget"></a>
+### loginWithDoubaoWidget()
+
+发起豆包 Widget 登录。
+
+## 代码示例
+
+```typescript
+import { LoginType, loginWithDoubaoWidget } from '@doubao-apps/framework/api';
+
+const { result } = await loginWithDoubaoWidget({
+  loginType: LoginType.LoginWithPrivacy
+});
+
+console.log(result);
+```
+
+## 入参
+
+|参数名|类型|必填|说明|
+|---|---|---|---|
+|loginType|`LoginType`|是|Login type identifier|
+|loginType.Login|`number`|是|仅登录|
+|loginType.LoginThenPrivacy|`number`|是|先登录再隐私协议，两次弹窗|
+|loginType.LoginWithPrivacy|`number`|是|登录和隐私协议合并，一次弹窗|
+|loginType.Privacy|`number`|是|隐私协议登录|
+
+**类型说明**
+
+- `LoginType`: `object`
+
+## 返回值
+
+返回登录结果。
+
+|字段名|类型|说明|
+|---|---|---|
+|result|`boolean`|Whether the login is successful|
+
+<a id="login"></a>
+### login()
+
+发起登录并获取登录凭证。
+
+## 代码示例
+
+```typescript
+import { login } from '@doubao-apps/framework/api';
+
+const { code } = await login({ timeout: 30000 });
+
+console.log(code);
+```
+
+## 入参
+
+|参数名|类型|必填|说明|
+|---|---|---|---|
+|timeout|`number`|否|Timeout in milliseconds|
+
+## 返回值
+
+返回包含登录凭证 code 的 Promise。
+
+|字段名|类型|说明|
+|---|---|---|
+|code|`string`|Login credential code|
+
+<a id="postloginresult"></a>
+### postLoginResult()
+
+回传 MCP 授权登录凭证。
+
+## 代码示例
+
+```typescript
+import { postLoginResult } from '@doubao-apps/framework/api';
+
+await postLoginResult({
+  result: true,
+  code: 'login-code'
+});
+```
+
+## 入参
+
+|参数名|类型|必填|说明|
+|---|---|---|---|
+|code|`string`|否|Authorization login credential, valid when login result is true|
+|result|`boolean`|是|Login result, true means success, false means failure|
+
+## 返回值
+
+返回回传完成的 Promise。