@doubao-dev/plugin-app-dev 0.0.0-stage → 0.0.40-canary-dea0ddc73-20261026073950

package/dist/skills/doubao-plugin-app/references/frontend/doubao-agentic-service-api/13-/347/231/273/345/275/225.md

@@ -0,0 +1,511 @@
+# 豆包应用插件的端能力 API: 登录
+
+豆包一次性登录凭证、Widget 登录交互和 MCP 授权结果回传能力。
+
+[返回目录](./groups.md) | [返回速查](./quick-reference.md)
+
+## 速查
+
+| API | 说明 |
+| --- | --- |
+| [loginWithDoubaoWidget](#loginwithdoubaowidget) | 在 Widget 中拉起平台登录和隐私协议授权交互。 |
+| [login](#login) | 获取当前豆包用户的一次性登录凭证。 |
+| [postLoginResult](#postloginresult) | 向豆包回传三方 MCP 授权登录结果。 |
+
+## API 详情
+
+<a id="loginwithdoubaowidget"></a>
+### loginWithDoubaoWidget()
+
+# loginWithDoubaoWidget
+
+在 Widget 中拉起平台登录和隐私协议授权交互。
+
+## 使用限制
+
+> [!WARNING]
+> **Android、iOS**：Android 仅区分 0（隐私流程）与非 0（登录流程），iOS 按当前隐私授权状态路由、仅记录 loginType 不据其分流，两次弹窗与合并弹窗语义均未生效；调用方无法通过 loginType 精确控制弹窗形态。
+
+## 支持版本
+
+前端库版本不低于 `0.0.19`。
+
+## 支持平台
+
+<table>
+<thead>
+<tr><th>平台</th><th>支持情况</th></tr>
+</thead>
+<tbody>
+<tr><td>Android</td><td>支持</td></tr>
+<tr><td>iOS</td><td>支持</td></tr>
+<tr><td>PC</td><td>不支持</td></tr>
+<tr><td>HarmonyOS</td><td>不支持</td></tr>
+</tbody>
+</table>
+
+## 支持场景
+
+<table>
+<thead>
+<tr><th>场景</th><th>支持情况</th></tr>
+</thead>
+<tbody>
+<tr><td>页面</td><td>支持</td></tr>
+<tr><td>卡片</td><td>支持</td></tr>
+</tbody>
+</table>
+
+## 接入准备
+
+### 前置条件
+
+- **Android**：当前豆包账号需已绑定手机号
+- **iOS**：当前豆包账号需已绑定手机号
+
+## 使用说明
+
+此 API 只处理 `loginType` 对应的平台交互，不会返回 `login()` 的一次性 `login_code`，
+也不会替业务方创建应用插件登录态或完成 MCP Token 交换。
+
+当前豆包账号未绑定手机号时，调用会报错。业务方应捕获错误并降级到自定义登录流程。
+
+业务方仍需按实际场景完成服务端账号登录；MCP 授权登录还需在业务服务端生成三方短期兑换 code，
+并通过 `postLoginResult` 回传最终登录结果。
+
+- 调用会主动拉起授权登录弹窗，请在用户明确触发登录的交互场景中调用；请勿在无用户操作的后台逻辑中调用。调用报错时，业务方应降级到自定义登录流程。
+
+## 调用方式
+
+### 异步 API
+
+```typescript
+loginWithDoubaoWidget(params: LoginWithWidgetRequest): Promise<LoginWithWidgetResult>
+```
+
+## 入参
+
+<table>
+<thead>
+<tr><th>名称</th><th>类型</th><th>必填</th><th>默认值</th><th>约束</th><th>说明</th></tr>
+</thead>
+<tbody>
+<tr><td><code>loginType</code></td><td><code>LoginType</code></td><td>是</td><td>-</td><td>-</td><td>Widget 中需要拉起的平台登录和隐私协议授权组合。Android、iOS：Android 仅区分 0（隐私流程）与非 0（登录流程），iOS 按当前隐私授权状态路由、仅记录 loginType 不据其分流，两次弹窗与合并弹窗语义均未生效。</td></tr>
+</tbody>
+</table>
+
+## 调用示例
+
+```typescript
+import { LoginType, loginWithDoubaoWidget } from '@doubao-dev/framework/api';
+
+try {
+  const { result } = await loginWithDoubaoWidget({
+    loginType: LoginType.LoginWithPrivacy
+  });
+
+  if (!result) {
+    // 用户未完成授权登录，停止后续登录流程。
+  }
+} catch {
+  // 当前账号未绑定手机号或发生其他错误时，降级到业务自定义登录流程。
+  await startCustomLoginFlow();
+}
+```
+
+## 成功返回
+
+<table>
+<thead>
+<tr><th>名称</th><th>类型</th><th>必返</th><th>说明</th></tr>
+</thead>
+<tbody>
+<tr><td><code>result</code></td><td><code>boolean</code></td><td>是</td><td>所选平台交互是否成功完成。<br><br>`true` 仅表示 `loginType` 指定的登录或隐私协议授权交互已完成，<br>不代表三方业务账号登录或 MCP 授权已经完成。</td></tr>
+</tbody>
+</table>
+
+### 返回示例
+
+```json
+{
+  "result": true
+}
+```
+
+## 错误处理
+
+错误对象和通用错误码见 [通用错误处理](./common-errors.md#错误返回)。
+
+### 失败示例
+
+```json
+{
+  "errNo": 112,
+  "errMsg": "invalid result"
+}
+```
+
+### 错误码
+
+<table>
+<thead>
+<tr><th>errNo</th><th>errMsg</th><th>平台</th><th>触发条件</th><th>处理建议</th></tr>
+</thead>
+<tbody>
+<tr><td><code>112</code></td><td><code>invalid result</code></td><td>Android</td><td>状态查询成功但返回关键数据缺失（如手机掩码）</td><td>手机掩码缺失时降级到自定义登录流程；其他情况可稍后重试，持续失败时反馈服务端响应异常。</td></tr>
+</tbody>
+</table>
+
+#### 通用错误码
+
+<table>
+<thead>
+<tr><th>errNo</th><th>errMsg</th><th>说明</th><th>平台</th></tr>
+</thead>
+<tbody>
+<tr><td><code>102</code></td><td><code>internal error</code></td><td>内部错误</td><td>Android、iOS</td></tr>
+</tbody>
+</table>
+
+## 平台差异
+
+- **Android**：状态查询成功但关键数据缺失返回 112；其他失败统一返回 102。
+- **iOS**：失败统一返回 102。
+
+<a id="login"></a>
+### login()
+
+# login
+
+获取当前豆包用户的一次性登录凭证。
+
+## 支持版本
+
+前端库版本不低于 `0.0.19`。
+
+## 支持平台
+
+<table>
+<thead>
+<tr><th>平台</th><th>支持情况</th></tr>
+</thead>
+<tbody>
+<tr><td>Android</td><td>支持</td></tr>
+<tr><td>iOS</td><td>支持</td></tr>
+<tr><td>PC</td><td>不支持</td></tr>
+<tr><td>HarmonyOS</td><td>不支持</td></tr>
+</tbody>
+</table>
+
+## 支持场景
+
+<table>
+<thead>
+<tr><th>场景</th><th>支持情况</th></tr>
+</thead>
+<tbody>
+<tr><td>页面</td><td>支持</td></tr>
+<tr><td>卡片</td><td>支持</td></tr>
+</tbody>
+</table>
+
+## 使用说明
+
+前端获取 `code` 后应立即发送给业务服务端，由业务服务端使用应用凭证调用豆包 OpenAPI
+换取 OpenID，并完成业务账号登录或绑定。不要在前端保存长期 Token，也不要把应用密钥下发到前端。
+
+此 `code` 不是业务登录态、MCP AccessToken，也不是传给 `postLoginResult` 的三方短期兑换 code。
+应用插件内的自定义登录态及其与 OpenID 的绑定关系需要由业务方维护，平台不存储三方登录态。
+用户拒绝登录、登录失败或调用超时时，Promise 将被拒绝。
+
+- 本 API 仅获取一次性登录凭证，不展示登录或授权弹窗。获取 code 后应及时发送到开发者服务端完成登录，不要持久化或输出到日志。
+
+## 调用方式
+
+### 异步 API
+
+```typescript
+login(params?: LoginRequest): Promise<LoginResult>
+```
+
+## 入参
+
+<table>
+<thead>
+<tr><th>名称</th><th>类型</th><th>必填</th><th>默认值</th><th>约束</th><th>说明</th></tr>
+</thead>
+<tbody>
+<tr><td><code>timeout</code></td><td><code>number</code></td><td>否</td><td><code>-</code></td><td>-</td><td>登录调用的超时时间，单位为毫秒。</td></tr>
+</tbody>
+</table>
+
+## 调用示例
+
+```typescript
+import { login } from '@doubao-dev/framework/api';
+
+// 业务方自行实现：将一次性 login_code 发送到业务服务端完成登录；该函数不是 SDK API。
+declare function loginOnBusinessServer(loginCode: string): Promise<void>;
+
+const { code } = await login({ timeout: 30000 });
+await loginOnBusinessServer(code);
+```
+
+## 成功返回
+
+<table>
+<thead>
+<tr><th>名称</th><th>类型</th><th>必返</th><th>说明</th></tr>
+</thead>
+<tbody>
+<tr><td><code>code</code></td><td><code>string</code></td><td>是</td><td>豆包一次性登录凭证 `login_code`。<br><br>该凭证用于业务服务端调用豆包 OpenAPI 换取当前用户的 OpenID。<br>凭证有效期为 5 分钟，使用一次或过期后失效。</td></tr>
+</tbody>
+</table>
+
+### 返回示例
+
+```json
+{
+  "code": "b27f7d84e8f04f24a5f94a32c8200b82"
+}
+```
+
+## 错误处理
+
+错误对象和通用错误码见 [通用错误处理](./common-errors.md#错误返回)。
+
+### 失败示例
+
+```json
+{
+  "errNo": 115,
+  "errMsg": "operation timeout"
+}
+```
+
+### 错误码
+
+<table>
+<thead>
+<tr><th>errNo</th><th>errMsg</th><th>平台</th><th>触发条件</th><th>处理建议</th></tr>
+</thead>
+<tbody>
+<tr><td><code>105</code></td><td><code>authentication fail</code></td><td>Android、iOS</td><td>登录服务拒绝签发登录凭证</td><td>检查应用配置和登录状态，修正后重试。</td></tr>
+<tr><td><code>112</code></td><td><code>invalid result</code></td><td>Android、iOS</td><td>登录服务返回的数据缺少有效凭证或无法解析</td><td>稍后重试；持续失败时反馈服务端响应异常。</td></tr>
+<tr><td><code>115</code></td><td><code>operation timeout</code></td><td>Android、iOS</td><td>调用耗时超过 timeout 指定的时间</td><td>适当增大 timeout 后重试。</td></tr>
+<tr><td><code>301</code></td><td><code>network request cancelled</code></td><td>iOS</td><td>获取登录凭证的网络请求被取消</td><td>确认应用和网络状态后重试。</td></tr>
+<tr><td><code>302</code></td><td><code>connection timed out</code></td><td>Android、iOS</td><td>获取登录凭证的网络连接超时</td><td>检查网络连接后重试。</td></tr>
+<tr><td><code>303</code></td><td><code>no network connection</code></td><td>Android、iOS</td><td>当前无可用网络连接</td><td>恢复网络连接后重试。</td></tr>
+<tr><td><code>305</code></td><td><code>network failure</code></td><td>Android、iOS</td><td>获取登录凭证时发生其他网络错误</td><td>检查网络连接，稍后重试。</td></tr>
+</tbody>
+</table>
+
+#### 通用错误码
+
+<table>
+<thead>
+<tr><th>errNo</th><th>errMsg</th><th>说明</th><th>平台</th></tr>
+</thead>
+<tbody>
+<tr><td><code>102</code></td><td><code>internal error</code></td><td>内部错误</td><td>Android、iOS</td></tr>
+</tbody>
+</table>
+
+## 平台差异
+
+- **iOS**：网络请求被取消时返回 errNo 301；Android 当前没有对应的可达失败回调。
+
+<a id="postloginresult"></a>
+### postLoginResult()
+
+# postLoginResult
+
+向豆包回传三方 MCP 授权登录结果。
+
+## 使用限制
+
+> [!WARNING]
+> **Android、iOS**：Android 在 result 为 false 时正常 resolve，iOS 在 result 为 false 时以失败 reject（message 为 &quot;no login result&quot;）；调用方无法用统一方式判断失败结果是否已回传成功。
+> **Android、iOS**：result 为 true 时若 code 缺省或为空，双端均按失败处理（Android reject、iOS reject）；调用方误以为成功回传可省略 code。
+
+## 支持版本
+
+前端库版本不低于 `0.0.19`。
+
+## 支持平台
+
+<table>
+<thead>
+<tr><th>平台</th><th>支持情况</th></tr>
+</thead>
+<tbody>
+<tr><td>Android</td><td>支持</td></tr>
+<tr><td>iOS</td><td>支持</td></tr>
+<tr><td>PC</td><td>不支持</td></tr>
+<tr><td>HarmonyOS</td><td>不支持</td></tr>
+</tbody>
+</table>
+
+## 支持场景
+
+<table>
+<thead>
+<tr><th>场景</th><th>支持情况</th></tr>
+</thead>
+<tbody>
+<tr><td>页面</td><td>支持</td></tr>
+<tr><td>卡片</td><td>支持</td></tr>
+</tbody>
+</table>
+
+## 接入准备
+
+### 前置条件
+
+- **Android**：先完成登录，并传入登录成功返回的有效 code
+- **iOS**：先完成登录，并传入登录成功返回的有效 code
+
+## 使用说明
+
+仅在 MCP 授权登录流程中调用此 API。业务服务端应先使用 `login()` 返回的一次性 `login_code`
+换取 OpenID、完成业务账号登录或绑定，再生成用于 OAuth Token 交换的三方短期 code。
+
+`result` 为 `true` 时必须传入 `code`。豆包使用该 code 完成 Token 交换后会自动关闭 MCP 登录页。
+用户拒绝登录或登录失败时，传入 `{ result: false }`，不要继续请求用户数据。
+
+MCP AccessToken、RefreshToken 及其生命周期由业务服务端维护，不应下发到前端。
+
+- 仅在完成 MCP 授权登录流程后回传结果；登录成功时必须携带有效 code，回传成功后不要重复回传。
+
+## 调用方式
+
+### 异步 API
+
+```typescript
+postLoginResult(params: PostLoginResultRequest): Promise<object>
+```
+
+## 入参
+
+<table>
+<thead>
+<tr><th>名称</th><th>类型</th><th>必填</th><th>默认值</th><th>约束</th><th>说明</th></tr>
+</thead>
+<tbody>
+<tr><td><code>code</code></td><td><code>string</code></td><td>否</td><td><code>-</code></td><td>-</td><td>三方短期兑换 code，仅在 `result` 为 `true` 时有效且必填。<br><br>该字段必须由业务服务端生成。豆包服务端会使用它调用业务方配置的 OAuth Token endpoint，<br>换取三方颁发的 MCP AccessToken 和 RefreshToken。<br><br>不要传入 `login()` 返回的豆包 `login_code`，也不要直接传入 AccessToken 或 RefreshToken。Android、iOS：result 为 true 时若 code 缺省或为空，双端均按失败处理（Android reject、iOS reject）。</td></tr>
+<tr><td><code>result</code></td><td><code>boolean</code></td><td>是</td><td>-</td><td>-</td><td>三方登录是否成功。<br><br>`true` 表示三方已完成业务账号登录，并提供了可供豆包兑换 MCP Token 的短期 code；<br>`false` 表示用户拒绝登录或登录失败。Android、iOS：Android 在 result 为 false 时正常 resolve，iOS 在 result 为 false 时以失败 reject（message 为 &quot;no login result&quot;）。</td></tr>
+</tbody>
+</table>
+
+## 调用示例
+
+```typescript
+import {
+  postLoginResult,
+  type PostLoginResultRequest
+} from '@doubao-dev/framework/api';
+
+// 业务方自行实现：完成业务登录并生成三方短期兑换 code；该函数不是 SDK API。
+declare function getMcpLoginResultFromBusinessServer(): Promise<PostLoginResultRequest>;
+
+const loginResult = await getMcpLoginResultFromBusinessServer();
+await postLoginResult(loginResult);
+```
+
+## 成功返回
+
+无返回字段。
+
+## 错误处理
+
+错误对象和通用错误码见 [通用错误处理](./common-errors.md#错误返回)。
+
+### 失败示例
+
+```json
+{
+  "errNo": 105,
+  "errMsg": "authentication fail"
+}
+```
+
+### 错误码
+
+<table>
+<thead>
+<tr><th>errNo</th><th>errMsg</th><th>平台</th><th>触发条件</th><th>处理建议</th></tr>
+</thead>
+<tbody>
+<tr><td><code>104</code></td><td><code>invalid parameter</code></td><td>Android</td><td>result 为 true 但缺少有效的兑换 code</td><td>传入业务服务端生成的有效 code 后重试。</td></tr>
+<tr><td><code>105</code></td><td><code>authentication fail</code></td><td>Android、iOS</td><td>登录被拒绝或兑换 code 校验未通过</td><td>确认业务登录状态与 code 是否有效后重试。</td></tr>
+<tr><td><code>112</code></td><td><code>invalid result</code></td><td>Android、iOS</td><td>Token 交换服务返回的数据无法解析</td><td>稍后重试；持续失败时反馈服务端响应异常。</td></tr>
+<tr><td><code>115</code></td><td><code>operation timeout</code></td><td>Android</td><td>Token 交换耗时超过限制</td><td>检查网络后重试。</td></tr>
+<tr><td><code>301</code></td><td><code>network request cancelled</code></td><td>iOS</td><td>Token 交换的网络请求被取消</td><td>确认应用和网络状态后重试。</td></tr>
+<tr><td><code>302</code></td><td><code>connection timed out</code></td><td>Android、iOS</td><td>Token 交换的网络连接超时</td><td>检查网络连接后重试。</td></tr>
+<tr><td><code>303</code></td><td><code>no network connection</code></td><td>Android、iOS</td><td>当前无可用网络连接</td><td>恢复网络连接后重试。</td></tr>
+<tr><td><code>305</code></td><td><code>network failure</code></td><td>Android、iOS</td><td>Token 交换时发生其他网络错误</td><td>检查网络连接，稍后重试。</td></tr>
+</tbody>
+</table>
+
+#### 通用错误码
+
+<table>
+<thead>
+<tr><th>errNo</th><th>errMsg</th><th>说明</th><th>平台</th></tr>
+</thead>
+<tbody>
+<tr><td><code>102</code></td><td><code>internal error</code></td><td>内部错误</td><td>Android、iOS</td></tr>
+</tbody>
+</table>
+
+## 平台差异
+
+- **Android**：缺少有效 code 时返回 104；调用超时返回 115。
+- **iOS**：缺少有效 code 时返回 102；网络请求被取消时返回 301，超时归类为 302。
+
+## 相关类型
+
+<a id="logintype"></a>
+### LoginType
+
+Widget 中需要拉起的平台交互类型。 - 0: 仅隐私协议授权 - 1: 仅登录交互 - 2: 先登录再进行隐私协议授权，两次独立交互 - 3: 登录和隐私协议授权合并为一次交互。
+
+#### Type
+
+`0 | 1 | 2 | 3`
+
+<a id="loginwithwidgetrequest"></a>
+### LoginWithWidgetRequest
+
+#### Properties
+
+• **loginType**: `LoginType` - Widget 中需要拉起的平台登录和隐私协议授权组合
+
+<a id="loginwithwidgetresult"></a>
+### LoginWithWidgetResult
+
+#### Properties
+
+• **result**: `boolean` - 所选平台交互是否成功完成。 true 仅表示 loginType 指定的登录或隐私协议授权交互已完成， 不代表三方业务账号登录或 MCP 授权已经完成
+
+<a id="loginrequest"></a>
+### LoginRequest
+
+#### Properties
+
+• **timeout?**: `number` - 登录调用的超时时间，单位为毫秒
+
+<a id="loginresult"></a>
+### LoginResult
+
+#### Properties
+
+• **code**: `string` - 豆包一次性登录凭证 login_code。 该凭证用于业务服务端调用豆包 OpenAPI 换取当前用户的 OpenID。 凭证有效期为 5 分钟，使用一次或过期后失效
+
+<a id="postloginresultrequest"></a>
+### PostLoginResultRequest
+
+#### Properties
+
+• **result**: `boolean` - 三方登录是否成功。 true 表示三方已完成业务账号登录，并提供了可供豆包兑换 MCP Token 的短期 code； false 表示用户拒绝登录或登录失败
+• **code?**: `string` - 三方短期兑换 code，仅在 result 为 true 时有效且必填。 该字段必须由业务服务端生成。豆包服务端会使用它调用业务方配置的 OAuth Token endpoint， 换取三方颁发的 MCP AccessToken 和 RefreshToken。 不要传入 login() 返回的豆包 login_code，也不要直接传入 AccessToken 或 RefreshToken