第三方应用

硬件接入与积分兑换

接入介绍

平台概述

WorkBuddy 开放平台基于 OAuth 2.1 规范 来进行用户身份验证和获取用户授权，同时面向开发者及生态合作伙伴提供了一套基于 HTTPS 协议的 Open API，第三方应用可以在取得用户授权的条件下通过 Open API 进行用户数据操作。

为了保护用户数据的安全和隐私，第三方应用访问用户数据前需要显式地向用户征求授权。用户授权后，平台将遵循 OAuth 规范派发第三方票据，第三方应用可以获取第三方票据并与平台进行所需要的操作。

核心能力

应用类型

开放平台当前支持三类第三方应用，面向不同接入场景：

术语定义

接入指南

接入流程概览

步骤一：创建应用并完成配置

在 WorkBuddy 开放平台一次性填写应用基本信息、权限管理信息和回调地址配置，完成全部应用配置后提交审核。

步骤二：从用户授权到调用接口

应用引导用户完成 OAuth 2.1 授权，服务端换取访问凭证后即可调用 Open API。整体过程可以分为三个连续阶段：

1. 首先由三方应用发起用户授权

2. 用户完成授权后，由应用服务端换取访问凭证 3. 应用使用访问凭证调用所需的 Open API

授权请求的具体说明请参考「认证授权 API：请求用户授权」，访问凭证的获取与刷新请参考「认证授权 API：换取接口调用凭证」，具体业务接口的参数、权限和响应结构请参考「Open API 接口」。以下时序图展示从用户授权到接口调用的完整过程。

应用注册与授权认证

硬件接入

硬件接入面向硬件设备厂商与合作伙伴开放。硬件设备（如智能眼镜、车机等）在开放平台创建硬件接入应用后，引导用户完成 OAuth 2.1 授权，即可通过 Open API 使用本地助理对话、云端任务管理、会话产物等能力，将 WorkBuddy 的智能体能力延伸至硬件终端。

新建硬件接入应用时一次性完成应用基本信息、权限管理信息和回调地址配置，提交后进入审核流程。审核通过后，应用发布并启用相应能力。

应用基本配置

1. 登录 WorkBuddy 开放平台
2. 点击「硬件接入」
3. 填写基本信息
4. 配置权限管理信息
5. 配置 OAuth 回调地址
6. 提交审核

积分应用

积分应用面向开发者和合作伙伴开放积分权益兑换能力。应用取得用户授权后，可通过 Open API 使用卡券或兑换码为用户兑换 WorkBuddy 积分（credits），适用于积分发放等场景。

新建积分应用时一次性完成应用基本信息、权限管理信息和回调地址配置，提交后进入审核流程。审核通过后，应用发布并启用相应能力。

应用基本配置

1. 登录 WorkBuddy 开放平台
2. 点击「其他 > 积分兑换」
3. 填写基本信息
4. 配置权限管理信息（仅开放积分与权益类 Scope）
5. 配置 OAuth 回调地址
6. 提交审核

应用说明

应用凭据说明：应用创建后进入审核状态，平台生成 client_id 和 client_secret。client_secret 仅在应用创建成功后明文展示一次，请妥善保管 client_secret，不要在前端或客户端代码中暴露。如有遗失，请联系平台处理。

授权认证

应用审核通过并启用后，需引导用户完成 OAuth 2.1 授权以获取 access_token。授权流程涉及两类接口，完整 API 文档见「Open API 接口」：

• 「认证授权 API」— GET /authorize（请求用户授权）、POST /token（换取/刷新 Token）

Token 类型一览

权限配置列表及关联 API

Scope 权限列表

权限申请指南

申请步骤

1. 在应用管理页面选择需要申请的 Scope
2. 说明使用场景和必要性
3. 提交审核

最小权限原则：仅申请应用功能所需的 Scope；用户授权时仅请求当前操作所需的 Scope；避免申请超出业务需求的权限。

分享能力接入

功能介绍

WorkBuddy 分享是指第三方应用通过接入该能力，让用户可以从自己的应用把文本、图片、音频、文件、资源链接等内容一键分享到 WorkBuddy。

WorkBuddy 分享功能已向通过企业认证的开发者开放。开发者在 WorkBuddy 开放平台创建分享应用（按「基础配置 → 应用平台信息」两步填写），提交审核后即生成应用 ID，审核通过后生成密钥，即可获得分享接入权限。

WorkBuddy 分享当前支持 PC 端接入（Windows 应用 / macOS 应用）；移动端（Android / iPhone / 鸿蒙应用）后续开放。

接入前准备

接入分享能力前，需在 WorkBuddy 开放平台 创建分享应用、通过审核并生成密钥。请确认用户使用的 WorkBuddy 客户端为 5.8.0 及以上版本，更低版本无法唤起分享。移动端（Android / iPhone / 鸿蒙）接入方式与分享 SDK 后续开放。

进入开放平台「第三方接入 → 分享功能接入」，点击「创建应用」，按 基础配置 → 应用平台信息 两步填写，支持随时「存草稿」。提交审核后立即生成应用 ID 并进入审核（7 个工作日内）；审核通过后到应用详情生成密钥，即可按《PC 端开发手册》接入。

第一步：基础配置

第二步：应用平台信息

先勾选应用的接入端（Windows 应用 / macOS 应用），至少一个；勾中的端各展开一张信息卡。

Windows 应用

一次取出主体与指纹（PowerShell，把路径换成你的 exe 路径）：

$sig = Get-AuthenticodeSignature "C:\Path\To\App.exe"
$sig.SignerCertificate.Subject      # 例：CN="XXX Technology Co., Ltd.", O="XXX Technology Co., Ltd.", C=CN
$sig.SignerCertificate.Thumbprint   # 例：A1B2C3D4E5F6…（40 位十六进制）

应用须使用代码签名证书签名后发布（OV / EV 证书需企业实名申请），自签名或未签名的应用无法通过审核。

macOS 应用

一次取出 Bundle ID 与 Team ID（终端，把路径换成你的 .app 路径）：

defaults read /Applications/你的应用.app/Contents/Info.plist CFBundleIdentifier        # 例：com.example.app
codesign -dv --verbose=4 /Applications/你的应用.app 2>&1 | grep TeamIdentifier          # 例：TeamIdentifier=AB12CD34EF

Team ID 取自 Apple Developer Program 会员资格页，同一团队下所有应用共用；查看不到时确认该账号已加入开发者计划。

字段用途：桌面端唤起时不校验发起方的应用签名，Windows 代码签名主体与指纹、macOS Team ID 用于登记、唯一性校验与审核核验；填错不会导致唤起失败，但会在审核阶段被驳回。

提交与审核

两步填写完整后点击「提交审核」。

生成密钥

密钥在应用审核通过后生成，创建应用阶段不提交密钥。

标识冲突与申诉

申诉：标识或名称确为你所有（如换绑、多账号误占），请发送邮件至 openworkbuddy@tencent.com 提交申诉，邮件中说明被占用的应用名称或标识、你的开发者主体名称，并附上能证明归属的材料（软件著作权证书、应用市场后台截图等）。平台核实认证主体后处理归属。

使用 WorkBuddy 品牌标识

接入分享能力后，你需要在自己应用内唤起分享的入口展示 WorkBuddy 标识（分享面板的分享目标项、设置页的接入标识位），让用户看清内容将发往哪里。标识须遵守 WorkBuddy 品牌设计指南：WorkBuddy 品牌中心（进入后切换至 WorkBuddy 品牌查看，徽标素材在页面「徽标」处下载）。

平台会在应用审核与线上巡查中核验标识使用情况；未按规范使用时，平台可要求整改并暂停分享能力。

常见问题

完成以上准备后，按《PC 端开发手册》接入分享能力。

PC端开发手册

适用版本： WorkBuddy 5.8.0 及以上。

能力概览

第三方应用构造分享消息，使用应用私钥生成签名包，再通过 PC 端 HTTPS 中间页或移动端 SDK 交给 WorkBuddy。WorkBuddy 校验请求后将内容预填到任务输入区；用户可以检查、编辑并发送。唤起成功或内容预填成功，不等于用户已提交任务。 当前分享场景值统一为 newTask。若 WorkBuddy 新建任务输入框中已有内容，分享内容将会覆盖当前任务输入区；否则创建新任务并填充到任务输入区。newTask 是协议场景名称，不表示每次分享都强制创建全新的任务。 当前消息负载使用 TaskPayload，其内容块可以承载文本、图片、音频、文件资源和资源链接。各端对本地资源和内嵌数据的支持存在差异，详见下文。

快速开始：分享一条文本消息

以下示例使用 Node.js 内置模块，在服务端签名并生成 PC 端 HTTPS 中间页链接。你需要先在开放平台获得真实的 appId、kid 和对应私钥。将私钥保存为服务端的 private-key.pem，保留 PEM 头尾与换行；不要将此文件提交到代码仓库。 将以下代码保存为 sign.cjs：

const fs = require('node:fs');
const crypto = require('node:crypto');
const b64 = value => Buffer.from(value, 'utf8').toString('base64');
const appId = process.env.APP_ID;
const kid = process.env.KEY_ID;
if (!appId || !kid) throw new Error('缺少 APP_ID 或 KEY_ID');
const messageObject = {
  title: '分析仓库',
  description: '请总结仓库结构',
  payload: {
    action: 'start',
    promptContentBlocks: [{ type: 'text', text: '分析这个仓库' }]
  }
};
const messageJson = JSON.stringify(messageObject);
if (Buffer.byteLength(messageJson, 'utf8') > 16384) {
  throw new Error('原始消息 JSON 超过 16 KiB');
}
const packet = {
  appId,
  kid,
  message: b64(messageJson),
  nonce: crypto.randomBytes(16).toString('hex'),
  scene: 'newTask',
  timestamp: String(Math.floor(Date.now() / 1000))
};
const signingText = [
  `appId=${b64(packet.appId)}`,
  `kid=${b64(packet.kid)}`,
  `message=${packet.message}`,
  `nonce=${b64(packet.nonce)}`,
  `scene=${b64(packet.scene)}`,
  `timestamp=${b64(packet.timestamp)}`
].join('&');
packet.sig = crypto.sign('sha256', Buffer.from(signingText, 'utf8'), {
  key: fs.readFileSync('./private-key.pem', 'utf8'),
  padding: crypto.constants.RSA_PKCS1_PADDING
}).toString('base64');
const query = new URLSearchParams(packet).toString();
console.log(`https://workbuddy.cn/app/open-deeplink?${query}`);

在保存私钥的服务端目录运行（将值替换为你的实际应用信息）：

APP_ID='你的应用标识' KEY_ID='对应的密钥标识' node sign.cjs

使用输出的 HTTPS 中间页链接，确认可以唤起 WorkBuddy，消息在输入区完成预填，然后由用户编辑并发送。请在用户发起分享时生成签名包；不要提前生成并长期复用链接。

PC 端完整链接

PC 端对外提供 HTTPS 中间页：https://workbuddy.cn/app/open-deeplink。第三方应用在系统浏览器打开带参数的链接，由用户确认后唤起 WorkBuddy；未安装客户端时可引导安装。 链接使用 appId、kid、message、nonce、scene、timestamp、sig 七个查询参数。用 URLSearchParams 对传输参数进行 URL 编码，不要手动拼接 Base64 中的 +、/、=。 下面展示一条字段和值均完整的格式示例。它由临时 RSA-2048 密钥生成并通过本地验签，但 app_demo、kid_demo 并未在平台登记，且示例时间戳会过期，不可用于真实分享。 HTTPS 中间页：

https://workbuddy.cn/app/open-deeplink?appId=app_demo&kid=kid_demo&message=eyJ0aXRsZSI6IkRlbW8iLCJkZXNjcmlwdGlvbiI6IkRlbW8iLCJwYXlsb2FkIjp7ImFjdGlvbiI6InN0YXJ0IiwicHJvbXB0Q29udGVudEJsb2NrcyI6W3sidHlwZSI6InRleHQiLCJ0ZXh0IjoiSGVsbG8gV29ya0J1ZGR5In1dfX0%3D&nonce=9f2c8b1a6d4e7035c8a912f0b7d6e453&scene=newTask&timestamp=1791515336&sig=s%2Bbo02%2BkPMj%2BbJV9iuzAxsIo3oEoPVYLl%2FkgPqQe4J0MTEEqa2kxmSssB%2Bg%2BzhsD1UZrNTlMPLQfUbApszCx05ujCKJ%2Fmn5u3QdoiWsIwl7dejptqHLI9iLIndlVroeliQ7r1mKtZNjLElWH4GNCeQbA2taPZanBcrcTQ5LXPXRRouxmryDPq%2FgbFKH9%2FU5vAoZUFEnKI1NqMs1W2QkEvLhj6kDOz2NmffZK64mHrpMlip6v3hD3ImPECWen1xmJJhetTV4Iy8bsinsio3PG7ccNf9dqYtpevWPlQlQhl09GVvhfNrKjQREkJG5Y6SkA3pIoB8vbNdLSH09D1UgV2Q%3D%3D

上述 message 经 URL 解码，再按标准 Base64 解码，其 UTF-8 JSON 为：

{"title":"Demo","description":"Demo","payload":{"action":"start","promptContentBlocks":[{"type":"text","text":"Hello WorkBuddy"}]}}

这里的 %3D、%2B、%2F 分别是 Base64 字符 =、+、/ 的 URL 编码结果。用于签名的是URL 编码前的字段值；用于链接的是签名完成后的传输值。

参数类型与消息结构

传输签名包

下表描述 URL 查询参数或签名包中的传输值。message 在传输时为 string；解码后才是 WorkBuddyMessage 对象。移动端 SDK 的实际入参形式以其正式接口文档为准。

前六项参与签名，加上 sig 共七项。无需传验签公钥。

WorkBuddyMessage

先序列化整个消息对象，再计算原始 UTF-8 JSON 的字节数。16 KiB 限制针对原始 JSON，不是 URL 长度，也不是 Base64 编码后的字符串长度；如果嵌入多媒体 data，这些字符也计入 JSON 字节数。

TaskPayload

指定的连接器应已发布，且与分享应用所属主体一致；用户是否已授权仍影响资源读取。

ContentBlock 类型

表中 ? 仅表示不同来源可能不提供该字段，不构成字段组合或必填规则的承诺。资源路径或链接是否能由 WorkBuddy 读取，取决于目标端的访问能力；第三方应用可访问的本地 file:// 路径，不一定能由 WorkBuddy 访问。_meta 可以包含如 og:title、og:image、og:description 的预览信息。字段组合、大小上限和各端完整支持矩阵需要以正式 SDK／协议为准。 文本块示例：

{"type":"text","text":"分析这个仓库"}

资源链接块示例：

{"type":"resource_link","name":"产品文档","uri":"https://example.com/docs","_meta":{"og:title":"产品文档"}}

签名生成：详细步骤

签名算法为 RS256：RSA PKCS#1 v1.5 填充、SHA-256 摘要。使用与 kid 配套的 RSA-2048 私钥（PKCS#8 PEM）生成签名；建议由开发者服务端持有和使用私钥。

1. **构造消息对象。**填入 title、description 和 TaskPayload。例如第 3 节的文本消息。
2. **序列化 JSON。**对整个消息对象执行 JSON 序列化，取得确切的 UTF-8 字节序列；原始 JSON 不得超过 16,384 字节。不要在签名与传输之间重新序列化或修改消息，否则字节内容可能变化。
3. 生成 message。将第 2 步的 UTF-8 字节做一次标准 Base64，保留 +、/ 及必要的 = 填充。后续签名时直接使用该值，不再对 message 二次 Base64。
4. **准备其余字段。**读取 appId 与 kid，设置 scene 为 newTask；使用密码学安全随机数生成器生成 16 字节，转为 32 位小写十六进制 nonce；生成本次请求的 Unix 秒级字符串 timestamp。
5. 分别编码普通字段值。对 appId、kid、nonce、scene、timestamp 各自的 UTF-8 字节分别做标准 Base64。此处只编码值，不编码 =、& 或参数名。
6. **拼接待签名串。**按键名的 ASCII 顺序 appId → kid → message → nonce → scene → timestamp 拼接，参数名区分大小写，各项间只放一个 &，末尾不附加空格或换行：

appId=Base64(appId)&kid=Base64(kid)&message=message&nonce=Base64(nonce)&scene=Base64(scene)&timestamp=Base64(timestamp)

7. **生成 sig。**对第 6 步签名串的 UTF-8 字节执行 RS256 签名，把签名二进制做标准 Base64。sig 不参与自身的签名串拼接。
8. **构造传输链接。**把六个原始传输字段值和 sig 作为七项查询参数交给 URLSearchParams 编码。URL 中传输的是原始 appId、kid 等值，不是签名串里使用的 Base64(appId)、Base64(kid)。
9. **检查时效与重试。**要求 -30 ≤ 平台当前时间 − timestamp ≤ 300，单位秒。同次分享重试保留原包；发起新分享或包过期后重新生成 nonce、timestamp、sig。同一 appId + nonce 最多允许应用内验签成功 3 次。

调试签名失败时，先比较双方使用的待签名串原文：确认字段顺序、大小写、Base64 填充、message 是否重复编码，以及是否混入换行；再检查 kid 与私钥是否配套。不要将私钥或完整真实分享链接提交到问题工单。

资源与连接器分享

分享图片、音频、文件或链接前，确认目标端支持相应内容形式，并确保 WorkBuddy 能读取所引用的资源。远程资源链接应保持有效；本地文件 URI 只有在目标端具备访问能力时才能使用。对 PC 端，不要依赖将图片、音频或文件以 data 直接嵌入消息的方式。 需要连接器时，在 TaskPayload.connectorIds 中填写应用主体已发布的连接器。若用户未授权、资源无法访问或内容未通过审查，分享可能无法完成预填；允许用户调整内容后重新发起分享。

错误处理与上线检查

上线前至少验证：纯文本通过 PC 端 HTTPS 中间页正常分享、未安装客户端、错误私钥、过期请求、重复请求、身份不符与不可访问资源。