Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。
供应商分享:跨仓协议契约
状态:实现契约(2026-10-07)。客户端(本仓)与服务端(
cindy-server的device-link-server、auth-server、packages/device-link-protocol)按本文同步实现;任何一侧要改字段语义,先改本文。 产品规则见product-rules/provider-sharing.md, 工作拆分见provider-sharing-implementation-plan.md。
1. 名词
- 分享(share):一个分享者账号在一台电脑(host device)上的一个供应商。
shareId由服务端生成。 - 成员(member):被同意的受邀者在某个分享里的身份。
memberId由服务端生成,全局唯一。 - 链接(link):一次性口令(43 位 base64url,
randomBytes(32)),5 分钟过期,服务端只存 sha256。 - 申请(request):受邀者凭链接发出的申请,24 小时过期,带 4 位配对码。
- 受邀者键(guestKey):同区域为受邀者账号的
membershipId;跨区域为x:<region>:<sub>(P3)。
2. relay 范围(packages/device-link-protocol,两仓同文件 providerShare.ts)
export const PROVIDER_SHARE_RELAY_CAPABILITY = 'provider-share-v1';
export type ProviderShareEndpoint = { role: 'host' } | { role: 'guest'; memberId: string };
export interface ProviderShareScope {
shareId: string;
target: ProviderShareEndpoint;
/** 只由 relay 写入,永不信任发送方提供的值。 */
source?: ProviderShareEndpoint;
}
export function providerShareIdentifier(value: unknown): string; // 规则同 sharedTaskIdentifier
export function parseProviderShareScope(value: unknown, withSource?: boolean): ProviderShareScope | null;
Envelope新增可选providerShare?: ProviderShareScope。同一帧不得同时带sharedTask与providerShare(relay 回BAD_REQUEST)。- 能力协商:客户端在 hello
capabilities声明provider-share-v1;relay 在 hello-ack 声明同名能力。客户端只在 relay 声明后发送带范围的帧;relay 要求收发双方都声明,否则回VERSION_MISMATCH。 - 受邀者 → 分享者:只允许
link-open / link-close / invoke / push,其中 push 只允许__cindy/device-link/transport-ack。条件:分享active;成员active(paused / removed / left一律拒绝);发送设备已登记到该成员(首次link-open自动登记同一受邀者账号的新设备,每个成员最多 64 台);dst等于分享的hostDeviceId;分享者设备在线;link-open与invoke还要求分享者设备remoteControlEnabled = true(否则REMOTE_DISABLED)。relay 把source改写为{ role: 'guest', memberId }。 - 分享者 → 受邀者:只允许
link-accept / link-close / invoke-result / push。发送方必须是分享者账号且设备等于hostDeviceId;target.memberId必须属于该分享,dst必须是该成员已登记的设备。source改写为{ role: 'host' }。成员不再 active 时也允许link-close与invoke-result(收尾)。 - 被拒绝的帧回
relay-error,code 用DEVICE_OFFLINE(不暴露原因;受邀者原因看 REST),回带原范围。 - 分享不随分享者离线关闭(与共享任务不同,没有离线宽限与关闭扫描)。
- 跨实例 Redis bus 携带
providerShareSource,订阅端重新校验,跳数上限与共享任务相同。
客户端本地 peer key(只在客户端,不上 wire)
packages/device-link/src/providerSharePeer.ts:JSON.stringify(['provider-share', shareId, role, memberId | null, deviceId]).padEnd(129, '~'),
长度恒大于真实设备 ID 上限 128,不会与真实设备或共享任务 key 碰撞;只在 socket 边界编解码。
3. REST:/api/device-link/provider-shares
全部需要 auth-server Access Token,且必须绑定设备(actor = { accountId: membershipId, deviceId })。
请求体拒绝多余字段;响应 Cache-Control: no-store;错误统一 { error: { code, message } };
写操作沿用按账号限流;口令只出现在请求体,不进 URL 与日志。
3.1 分享者(只能在 hostDeviceId 那台设备上调用)
| 方法 | 请求体 | 响应 |
|---|---|---|
GET / |
— | { shares: OwnerShare[] }(本账号、本设备的 active 分享) |
POST /links |
{ providerId, providerLabel, deviceName, identityCard } |
{ shareId, invitation, linkId, expiresAt } |
POST /requests/:requestId/approve |
{} |
{ shareId, memberId } |
POST /requests/:requestId/reject |
{} |
{ requestId, status: 'rejected' } |
POST /members/:memberId/pause |
{} |
{ memberId, status: 'paused' } |
POST /members/:memberId/resume |
{} |
{ memberId, status: 'active' } |
POST /members/:memberId/remove |
{} |
{ memberId, status: 'removed' } |
interface Person { displayName: string; avatarUrl: string | null; region: 'cn' | 'global' }
interface OwnerShare {
shareId: string; providerId: string; providerLabel: string; hostDeviceId: string; createdAt: string;
members: Array<Person & { memberId: string; status: 'active' | 'paused'; joinedAt: string }>;
requests: Array<Person & { requestId: string; linkId: string; pairingCode: string; createdAt: string; expiresAt: string }>;
}
linkId 是一次性随机邀请口令的 SHA-256 小写十六进制摘要,只标识具体链接,不暴露口令,不能用于加入分享。
服务端从 POST /links 返回它,并附在 owner 列表的每条待处理申请上。同一供应商的多个链接复用 shareId,
审批弹窗归属必须按 linkId 区分,不能仅按 shareId、host 或 provider 匹配。
这是 additive 字段:旧客户端忽略;新客户端读取及本机生成链接接受缺字段的旧服务器。跨电脑生成需要合法 linkId, 缺失时提示更新、不向用户返回或登记可复制链接,不降级成按供应商监听。先将服务端更新到该区域所有副本,再发布 客户端;完整去重需要生成端和供应商所在电脑同时支持。只返回已有 linkDigest,无 migration、鉴权或环境变量变化。
POST /links:同一(分享者、设备、providerId)已有 active 分享则复用,否则新建;同时用名片刷新分享者快照与providerLabel、deviceName。identityCard.purpose = 'share-link',nonce = sha256hex(hostDeviceId + ':' + providerId)。- 批准:申请必须
pending且未过期;成员按(分享、guestKey)幂等:已有removed / left行时恢复为active(新 memberId 不必变),链接置consumed。 - 拒绝、撤回、过期:链接置为对应终态,不可再用。
3.2 受邀者
| 方法 | 请求体 | 响应 |
|---|---|---|
POST /preview |
{ invitation } |
LinkPreview |
POST /requests |
{ invitation, identityCard } |
{ requestId, pairingCode, status: 'pending', expiresAt } |
GET /requests/:requestId |
— | { requestId, status, pairingCode, expiresAt, shareId?, memberId? } |
POST /requests/:requestId/withdraw |
{} |
{ requestId, status: 'withdrawn' } |
GET /received |
— | { shares: ReceivedShare[] } |
POST /received/:memberId/leave |
{} |
{ memberId, status: 'left' } |
interface LinkPreview {
shareId: string; providerId: string; providerLabel: string; deviceName: string; owner: Person;
state: 'unused' | 'used' | 'expired'; expiresAt: string;
}
interface ReceivedShare {
shareId: string; memberId: string; providerId: string; providerLabel: string;
hostDeviceId: string; deviceName: string; owner: Person;
status: 'active' | 'paused';
hostOnline: boolean; // relay presence
hostCapable: boolean; // 分享者设备声明了 provider-share-v1
}
- 申请:
identityCard.purpose = 'share-request',nonce = sha256hex(invitation);同区域要求名片sub等于请求的accountId。 - 申请状态:
pending | approved | rejected | withdrawn | expired;GET只对申请人可见。 - 配对码:
crypto.randomInt(0, 10000)补零 4 位,只出现在申请人的申请响应/状态查询与分享者的requests里。
3.3 错误码
| code | HTTP | 场景 |
|---|---|---|
NOT_FOUND |
404 | 口令格式不对、不存在;申请/成员不存在或不属于调用方 |
PROVIDER_SHARE_LINK_USED |
409 | 链接已被申请或已作废 |
PROVIDER_SHARE_LINK_EXPIRED |
410 | 链接或申请已过期 |
PROVIDER_SHARE_SELF |
409 | 分享者打开自己的链接 |
PROVIDER_SHARE_ALREADY_MEMBER |
409 | 受邀者已是该分享的 active / paused 成员 |
PROVIDER_SHARE_IDENTITY_INVALID |
400 | 名片验签失败、过期、用途或 nonce 不符、sub 不一致 |
PROVIDER_SHARE_NOT_HOST_DEVICE |
403 | 分享者接口不是从分享所在设备调用 |
PROVIDER_SHARE_CROSS_REGION_DISABLED |
403 | P3:跨区开关关闭 |
PERMISSION_DENIED / CONFLICT / BAD_REQUEST |
— | 沿用现有语义 |
3.4 过期与清理
链接 5 分钟、申请 24 小时;接口内按 expiresAt 即时判定,后台扫描把过期行置为 expired 并定期删除已过期超过 7 天的链接与终态申请。成员行保留为墓碑。
3.5 公开加入页 /provider-share/join
仿 /shared-task/join:口令在 # 之后(#<token>[?app=cindy|cindycn|cindydev]),页面不访问数据库。
桌面浏览器一律唤起 cindy://provider-share/join?invitation=<token>&server=<origin+prefix>(与共享任务一致:各区域与 dev 的桌面版
都注册 cindy://;app 提示只给手机网页用)。唤起失败时提示把链接粘贴到 Cindy(设置 → 模型供应商 → 右上角「输入分享链接…」;2026-10-08 起入口从左栏组末移到这里,加入页文案需同步)。
手机浏览器不唤起 App,显示「请在电脑上打开这个链接」并提供复制链接。五种语言、深浅色、严格 CSP。
4. 身份名片(auth-server)
POST /api/me/identity-card,普通用户 Access Token,按账号限流。
- 请求:
{ audience: 'cindy-provider-share', purpose: 'share-link' | 'share-request' | 'share-session', nonce: string(1..128) }(share-session只用于 P3 跨区,见 §6.2) - 响应:
{ card: string, expiresAt: string } card为 RS256 JWT,沿用现有签名 key 与 JWKS(kid)。claims:{ typ: 'identity-card', iss, aud: 'cindy-provider-share', sub: <membershipId>, name: <displayName>, picture: <avatarUrl|null>, region: 'cn'|'global', purpose, nonce, iat, exp: iat + 300 }。- 只放昵称与头像;不放邮箱、手机号(含脱敏)、组织。
- device-link-server 用 issuer 的 JWKS 验签并核对
typ / aud / purpose / nonce / exp;同区域只信任本区域 issuer;P3 才额外信任对方区域 issuer(且只用于名片)。
5. 分享者电脑本地(客户端)
- 受邀者对端由 peer key 判定(
controllerTrust返回 guest);准入要求:允许远程控制、该分享供应商的「允许被远程调用」、本机缓存里分享与成员 active。 - 只放行 invoke channel:
maker:remote-agent:v1、maker:provider:list(只返回该分享的供应商),以及模型列表与发送前检查要读的maker:get-capabilities(只留该供应商的模型)、maker:list-available-agents(只留它支持的 Agent)、maker:agent:status(只回该供应商支持的 Agent 是否装好binaryReady,不带本机路径、登录身份与分享者自己的登录状态);订阅与其他 channel 全拒,迟到的结果在撤权后改写为拒绝。 - 远程 Agent 运行按受邀者设备隔离(peer key 含分享、成员与设备):运行数上限沿用每个控制端的上限;暂停或删除时立即结束任务,删除时清理本机会话数据(影子工作区、附件、会话记录);用量记录保留。
6. P3 跨区域(服务端开关 PROVIDER_SHARE_CROSS_REGION_ENABLED,默认关)
分享属于分享者区域。受邀者在另一个区域时,不使用本区域 Access Token 访问对方区域,而是用本区域 auth-server
签发的身份名片换取只限分享的凭证。开关关闭时下列 /x/* 接口一律 403 PROVIDER_SHARE_CROSS_REGION_DISABLED,
WebSocket 拒绝 ProviderShareGuest 认证;同区域分享不受影响。
6.1 配置(分享者区域的 device-link-server)
| 变量 | 说明 |
|---|---|
PROVIDER_SHARE_CROSS_REGION_ENABLED |
true 才开放;默认关 |
PROVIDER_SHARE_PEER_REGION |
对方区域:cn 或 global |
PROVIDER_SHARE_PEER_ISSUER |
对方区域 auth-server 的 issuer(名片 iss 必须精确等于它) |
PROVIDER_SHARE_PEER_JWKS_URL |
对方区域 auth-server 的 JWKS 地址(只用于验证名片) |
对方区域名片的 region claim 必须等于 PROVIDER_SHARE_PEER_REGION。跨区 guestKey = x:<peerRegion>:<sub>,
跨区设备 id = x:<peerRegion>:<sha256hex(guest 设备 id) 前 32 位>(不与本区域设备 id 冲突)。
6.2 REST:/api/device-link/provider-shares/x(不需要 Access Token)
| 方法 | 认证 | 请求体 | 响应 |
|---|---|---|---|
POST /x/preview |
名片 | { invitation, identityCard } |
LinkPreview |
POST /x/requests |
名片 | { invitation, identityCard } |
{ requestId, pairingCode, status: 'pending', expiresAt, requestToken } |
POST /x/requests/:requestId |
requestToken | { requestToken } |
申请状态(同 GET /requests/:id) |
POST /x/requests/:requestId/withdraw |
requestToken | { requestToken } |
{ requestId, status: 'withdrawn' } |
POST /x/session |
名片 | { identityCard, deviceId, deviceName, platform } |
{ credential, expiresAt, deviceId, shares: ReceivedShare[] } |
POST /x/received/:memberId/leave |
凭证 | {} |
{ memberId, status: 'left' } |
- 名片:
preview、requests用purpose = 'share-request'、nonce = sha256hex(invitation)(同一张名片可先预览再申请);session用purpose = 'share-session'、nonce = sha256hex(deviceId),deviceId是受邀者在本区域的设备 id。 requestToken:43 位 base64url,只存摘要,只能查询与撤回这一条申请。session:为该 guestKey 的全部 active / paused 成员登记这台设备(每个成员最多 64 台),签发一个连接凭证credential(43 位 base64url,只存摘要,24 小时过期,同一设备再次调用即轮换、旧凭证失效);shares只含这个 guestKey 的分享(字段同同区域ReceivedShare)。没有任何成员时返回空shares且不签发凭证 (credential: null)。受邀者的电脑定期(≤ 12 小时)或凭证失效时重新调用。leave用Authorization: ProviderShareGuest <credential>;只能退出该凭证所属 guestKey 的成员。- 限流:按 guestKey(名片
sub)与来源 IP 限流,口径同同区域写操作。
6.3 relay
- WebSocket 升级接受
Authorization: ProviderShareGuest <credential>(同区域连接仍用 Access Token)。该连接的身份是 跨区设备 id,hello 必须声明provider-share-v1;只能收发带providerShare范围的帧(规则同 §2 受邀者 → 分享者), 不加入任何账号的 presence,不能订阅、不能访问共享任务或其他 relay 能力。 - 凭证过期、被轮换,或者它关联的成员全部不再 active 时,relay 断开该连接(close code 4401)。
- 分享者 → 跨区受邀者的帧按 §2 投递到该跨区设备。
6.4 客户端(受邀者)
- 链接的服务地址属于另一个官方区域(按内置的对方区域清单判定)时走跨区流程;其他地址一律拒绝。
- 名片向自己区域的 auth-server 换取(同 §4);对方区域的 REST 地址与 relay 地址取自内置的对方区域清单。
- 对方区域的请求一律不带本区域 Access Token,对方区域的 401 也不会刷新或登出本区域账号。
- 凭证只在内存里:启动、过期前与申请被同意后,用新名片调用
/x/session重新换取;本机只记一个不含凭证的标记 (userData/remote-agent/provider-share-regions.json:账号摘要 → 区域),表示「这个账号在对方区域发过申请或加入过 分享」。没有标记的账号从不联系对方区域;/x/session返回没有分享时清除标记。 - 远程 Agent 经第二条 relay 连接(对方区域,
ProviderShareGuest认证,hello 声明remoteControlEnabled: false)访问 分享者电脑,任务绑定与同区域相同(share:<shareId>)。