第三方应用
接入介绍
平台概述
WorkBuddy 开放平台基于 OAuth 2.1 规范 来进行用户身份验证和获取用户授权，同时面向开发者及生态合作伙伴提供了一套基于 HTTPS 协议的 Open API，第三方应用可以在取得用户授权的条件下通过 Open API 进行用户数据操作。
为了保护用户数据的安全和隐私，第三方应用访问用户数据前需要显式地向用户征求授权。用户授权后，平台将遵循 OAuth 规范派发第三方票据，第三方应用可以获取第三方票据并与平台进行所需要的操作。
核心能力
| 能力域 | 说明 |
|---|---|
| 本地助理对话 | 通过 API 与 PC 端本地助理进行消息交互 |
| 云端任务管理 | 创建并管理云端 AI 任务，支持移动端/应用会话 |
| 产物管理 | 会话产物的拉取、增量更新与媒体文件下载 |
| 兑换码核销 | 通过卡券或兑换码为用户兑换WorkBuddy积分（credits） |
术语定义
| 角色 | 说明 | 信任边界 |
|---|---|---|
| Resource Owner | 资源拥有者，通常是 WorkBuddy 用户 | 决定第三方应用或连接器可访问的资源范围 |
| Third Application | 常规第三方应用，开发者基于 WorkBuddy 开放平台开发 | 用户授权后可调用 Open API |
| WorkBuddy | 代表用户执行任务、发起工具调用的智能体运行环境 | 调用前应换取短生命周期凭据 |
| Open Platform | 开放平台，负责应用注册、授权确认、令牌签发、Scope 管理和审计 | 平台级可信边界，所有开放调用的权限源头 |
接入指南
接入流程概览
步骤一：创建应用并完成配置
在 WorkBuddy 开放平台一次性填写应用基本信息、权限管理信息和回调地址配置，完成全部应用配置后提交审核。
步骤二：从用户授权到调用接口
应用引导用户完成 OAuth 2.1 授权，服务端换取访问凭证后即可调用 Open API。整体过程可以分为三个连续阶段：
- 首先由三方应用发起用户授权
- 用户完成授权后，由应用服务端换取访问凭证
- 应用使用访问凭证调用所需的 Open API
授权请求的具体说明请参考「认证授权 API：请求用户授权」，访问凭证的获取与刷新请参考「认证授权 API：换取访问凭证」，具体业务接口的参数、权限和响应结构请参考「Open API 接口」。以下时序图展示从用户授权到接口调用的完整过程。
应用注册与授权认证
硬件接入
新建硬件接入应用时一次性完成应用基本信息、权限管理信息和回调地址配置，提交后进入审核流程。审核通过后，应用发布并启用相应能力。
应用基本配置
- 登录 WorkBuddy 开放平台
- 点击「硬件接入」
- 填写基本信息
- 配置权限管理信息
- 配置 OAuth 回调地址
- 提交审核
凭据说明：应用创建后进入草稿状态，平台生成 client_id 和 client_secret。 client_secret仅在应用创建成功后明文展示一次，请妥善保管 client_secret，不要在前端或客户端代码中暴露。如有遗失，请联系平台处理。
应用状态
| 状态 | 说明 |
|---|---|
| 审核中 | 应用配置已提交，等待平台审核 |
| 已启用 | 应用审核通过并发布，可以调用已授权的 Open API |
| 已驳回 | 应用审核未通过，需要根据审核反馈修改配置后重新提交 |
授权认证相关的 API 接口文档统一归入「Open API 接口」。
授权认证
应用审核通过并启用后，需引导用户完成 OAuth 2.1 授权以获取 access_token。授权流程涉及两类接口，完整 API 文档见「Open API 接口」：
- 「认证授权 API」— GET /authorize（请求用户授权）、POST /token（换取/刷新 Token）
Token 类型一览
| Token 类型 | 用途 | 有效期 | 备注 |
|---|---|---|---|
| access_token | 调用 Open API 的凭证 | 24 小时 | 通过「换取访问凭证」获取；过期后需重新获取。 |
| refresh_token | 刷新 access_token | 60 天 | 通过「换取访问凭证」获取；需安全存储在服务端，不得暴露在前端或客户端代码中。 |
权限配置列表及关联 API
Scope 权限列表
| 分类 | Scope | 权限名称 | 描述 |
|---|---|---|---|
| 用户资料 | user.profile.readable | 读取个人资料 | 读取用户的昵称和头像 |
| 用户资料 | user.contact.readable | 验证联系方式 | 校验调用方提供的手机号是否与用户的手机号一致 |
| 积分与权益 | user.credit.exchange | 卡券兑换积分 | 使用卡券或兑换码为用户兑换WorkBuddy积分 |
| 云端任务 | user.task.invokable | 创建并执行云端任务 | 允许应用按照用户的指令创建并执行云端任务 |
| 云端任务 | user.task.readable | 读取任务列表与详情 | 允许应用读取用户的云端任务列表及任务详情 |
| 本地助理 | user.localassistant.invokable | 向本地助理发送消息 | 向本地助理（用户 PC 端）发送消息，驱动用户本机 Agent 执行任务 |
| 本地助理 | user.localassistant.readable | 读取本地助理在线状态与消息历史 | 读取本地助理（用户 PC 端）的在线状态与会话消息历史 |
权限申请指南
申请步骤
- 在应用管理页面选择需要申请的 Scope
- 说明使用场景和必要性
- 提交审核
最小权限原则：仅申请应用功能所需的 Scope；用户授权时仅请求当前操作所需的 Scope；避免申请超出业务需求的权限。