Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。
TypeScript agentai-agentai-assistantandroidclaude-codecodexelectroniosllmmacosreact-nativetypescriptwindows
/**
* device-link 客户端完整协议(desktop / mobile 共享)。
*
* relay 能理解的信封、连接层 payload 与错误码来自本仓 device-link-protocol;
* 本文件只补充 relay 不解析的端到端隧道 payload、客户端本地错误与 REST 视图。
*/
import {
MAX_FRAME_BYTES,
NOTIFY_BODY_MAX_LENGTH,
NOTIFY_AVATAR_JPEG_MAX_LENGTH,
NOTIFY_COLLAPSE_ID_MAX_LENGTH,
NOTIFY_DEEP_LINK_MAX_LENGTH,
NOTIFY_TITLE_MAX_LENGTH,
PROTOCOL_VERSION,
SERVER_CAPABILITY_NOTIFY,
type DeviceInfo,
type Envelope,
type EnvelopeKind,
type HelloAckPayload,
type HelloPayload,
type NotifyCategory,
type NotifyPayload,
type NotifySender,
type PresenceSetPayload,
type PresenceSnapshot,
type RelayErrorCode,
type RelayErrorPayload,
} from '@cindy/device-link-protocol';
import type { InvokeResultTransfer, InvokeTransferOptions } from './invokeTransfer.js';
import { isProviderSharePeer as isProviderSharePeerLocal } from './providerSharePeer.js';
import { isSharedTaskPeer as isSharedTaskPeerLocal } from './sharedTaskPeer.js';
export { SHARED_TASK_RELAY_CAPABILITY, sharedTaskDeviceId, parseSharedTaskScope, type SharedTaskScope } from '@cindy/device-link-protocol';
export { sharedTaskHostPeer, sharedTaskGuestPeer, isSharedTaskPeer, parseSharedTaskPeer } from './sharedTaskPeer.js';
export type { SharedTaskPeer } from './sharedTaskPeer.js';
export {
PROVIDER_SHARE_RELAY_CAPABILITY,
parseProviderShareScope,
providerShareIdentifier,
type ProviderShareEndpoint,
type ProviderShareScope,
} from '@cindy/device-link-protocol';
export { providerShareHostPeer, providerShareGuestPeer, isProviderSharePeer, parseProviderSharePeer } from './providerSharePeer.js';
export type { ProviderSharePeer } from './providerSharePeer.js';
/** Any cross-account scoped peer (shared task or provider share): never treat as a same-account device. */
export function isScopedPeer(value: unknown): boolean {
return isSharedTaskPeerLocal(value) || isProviderSharePeerLocal(value);
}
export {
MAX_FRAME_BYTES,
NOTIFY_BODY_MAX_LENGTH,
NOTIFY_AVATAR_JPEG_MAX_LENGTH,
NOTIFY_COLLAPSE_ID_MAX_LENGTH,
NOTIFY_DEEP_LINK_MAX_LENGTH,
NOTIFY_TITLE_MAX_LENGTH,
PROTOCOL_VERSION,
SERVER_CAPABILITY_NOTIFY,
};
export type {
DeviceInfo,
Envelope,
EnvelopeKind,
HelloAckPayload,
HelloPayload,
NotifyCategory,
NotifyPayload,
NotifySender,
PresenceSetPayload,
PresenceSnapshot,
RelayErrorCode,
RelayErrorPayload,
};
// ─── 错误码 ───────────────────────────────────────────────────────────────────
/**
* device-link 全链路错误码。
* 前 6 个与 server relay 的 RelayErrorCode 对应;后面是 client / 被控端本地产生。
*/
export type DeviceLinkErrorCode = RelayErrorCode
| 'CHANNEL_NOT_ALLOWED' // channel 不在远程调用白名单
| 'ACCESS_REVOKED' // 被控端已撤销该控制端的访问权限(逐设备黑名单,被控端本地强制)
| 'INVOKE_TIMEOUT' // 控制端等待 invoke-result 超时
| 'PEER_RESET' // peer 传输复位;仅用于可安全重试的幂等读请求
| 'LINK_NOT_OPEN' // 控制链路未建立
| 'NOT_CONNECTED' // 本端尚未连上 relay
| 'BACKPRESSURE' // 本端可靠传输缓冲已满,拒绝继续制造积压
| 'MEDIA_FETCH_FAILED' // 入方向媒体取件失败(被控端解析本机媒体 / 上传 OSS 中转出错)
| 'VOICE_TRANSCRIBE_FAILED' // 出方向手机语音转写失败(被控端下载音频 / ASR 出错)
| 'VOICE_CREDENTIAL_SYNC_FAILED' // 手机语音云端 ASR/refine 临时 credential 同步失败(历史,新桌面已不再返回)
| 'VOICE_CREDENTIAL_SYNC_REMOVED' // 穿透 credential 同步能力已下线:手机语音改走 Cindy 官方托管服务,旧手机据此提示升级
| 'VOICE_DICTIONARY_LEARNING_FAILED' // 手机语音词典学习 evidence 回写失败
| 'VOICE_DICTIONARY_GET_FAILED'; // 手机拉取被控桌面词典快照失败(读同步状态出错)
/** 带结构化错误码的异常,贯穿 client / host 两层 */
export class DeviceLinkError extends Error {
/**
* true = 该错误击中的是一条**已发出**的 in-flight 请求(断连时被 failAllPending
* 批量 reject):请求帧可能已送达对端,只是响应丢了。控制端的自动重试逻辑必须
* 区分它与「发送前本地拒绝」(未置位)——对非幂等操作(如 enqueue)盲重前者
* 会造成对端重复执行。
*/
inFlight?: boolean;
constructor(
public readonly code: DeviceLinkErrorCode,
message: string,
) {
super(message);
this.name = 'DeviceLinkError';
}
}
/** 判定错误是否击中 in-flight 请求(见 DeviceLinkError.inFlight)。 */
export function isInFlightDeviceLinkError(err: unknown): boolean {
return err instanceof DeviceLinkError && err.inFlight === true;
}
// ─── 连接层 payload ───────────────────────────────────────────────────────────
// ─── 隧道层 payload ───────────────────────────────────────────────────────────
export interface LinkOpenPayload {
controllerName: string;
protocolVersion: number;
appVersion: string;
/**
* 控制端支持的端到端可选能力(append-only)。旧控制端缺省为空集;
* 被控端只有在能力明确声明时才发送对应的新 wire 字段。
*/
capabilities?: string[];
/** reliable-transport-v1 下,本端发往对端的 stream generation。 */
transportStreamId?: string;
/** 本端当前仍可能发送的最小 seq;对端重启丢失 ACK 内存时从这里恢复。 */
transportBaseSeq?: number;
}
/** 控制端能安全消费完整 ProviderLogoKind(含 #527 新增品牌)的 maker:provider:list 投影。 */
export const CONTROLLER_CAPABILITY_PROVIDER_LOGO_KINDS_V2 = 'provider-logo-kinds-v2';
/** 控制端能区分 set-model 中显式 providerId:null 与 JSON optional 占位。 */
export const CONTROLLER_CAPABILITY_SET_MODEL_EXPLICIT_PROVIDER_NULL_V1 =
'set-model-explicit-provider-null-v1';
/** 控制端会为有损模型换窗携带用户明确确认过的精确窗口。 */
export const CONTROLLER_CAPABILITY_MODEL_WINDOW_CONFIRMATION_V1 =
'model-window-confirmation-v1';
/**
* 控制端能消费 `maker:event:batch` 微批帧(拆包后逐条按原路消费)。
* 被控端只对声明了本能力的控制端发批,未声明者照旧逐帧转发——旧控制端
* 因此永远收不到该 channel,无需为未知 channel 做任何兼容。
*/
export const CONTROLLER_CAPABILITY_MAKER_EVENT_BATCH_V1 = 'maker-event-batch-v1';
/** Accepts ordered current-text snapshots and history repair hints, including after backpressure. */
export const CONTROLLER_CAPABILITY_SESSION_TEXT_SNAPSHOT_V1 = 'session-text-snapshot-v1';
/**
* 后台链路(link-open / link-accept 双向声明)。控制端在本机没有订阅对端任何 topic 时建链
* 即声明:被控端不装 legacy `'*'` 兼容订阅 —— 不亮被控横幅、不转发推送、不挡无人值守更新
* 重启 —— 直到控制端显式 subscribe。被控端在 link-accept 声明支持;旧被控端忽略该能力,
* 照旧装 legacy `'*'`,只读类后台请求须先确认对端支持(见 desktop remoteBackgroundInvoke)。
*/
export const DEVICE_LINK_CAPABILITY_BACKGROUND_LINK_V1 = 'background-link-v1';
export interface LinkAcceptPayload {
appVersion: string;
/** 被控端 allowlist 的指纹,便于控制端探测版本差异 */
allowlistHash: string;
/**
* 被控端支持的端到端可选能力。旧被控端缺省为空集,控制端只有在
* 看到能力后才启用可靠传输与大消息分片。
*/
capabilities?: string[];
/** reliable-transport-v1 下,本端发往控制端的 stream generation。 */
transportStreamId?: string;
/** 本端当前仍可能发送的最小 seq;对端重启丢失 ACK 内存时从这里恢复。 */
transportBaseSeq?: number;
}
/**
* link-close 的关闭原因。
*
* wire 语义分两档:
* - **永久关闭**(user/toggle-off/shutdown/revoked 及存量客户端眼中的一切未知
* reason):接收方拆可靠层、拒在途请求,不自动重建;只特判 `'revoked'`
* 额外标记撤权。新增枚举值对存量客户端 fail-generic 到这一档——因此
* **任何可恢复语义的新 reason 都必须经能力协商后才可发送**。
* - **可恢复瞬时重置**(`transport-timeout`):被控端对该 peer 的可靠重试
* 耗尽,单独重置这条 link(不拆 relay 连接)。**仅当控制端在 link-open 声明
* 了 `transport-timeout-close-v1` 能力时才会收到**(见 transport.ts);未声明
* 的旧控制端走整连接重连的兼容恢复路径。理解该 reason 的接收端按瞬时
* 重置处理:保留可靠层 stream/pending/在途请求,立即重新 link-open(或触发
* rehydrate);重建后按 reconnect-continuity 语义同 seq 续传。
*/
export type LinkCloseReason = 'user' | 'toggle-off' | 'shutdown' | 'revoked' | 'transport-timeout';
export interface LinkClosePayload {
reason: LinkCloseReason;
}
/** 控制端 → 被控端:执行一次 IPC invoke */
export interface InvokePayload {
channel: string;
args: unknown[];
/** 可选结果传输编码声明(见 invokeTransfer.ts);旧被控端忽略。 */
transfer?: InvokeTransferOptions;
}
/**
* 被控端 → 控制端:invoke 执行结果。
* error.message 透传被控端 throwIpcError 的 `[CODE] message` 编码,
* 控制端 renderer 继续用现有 extractIpcError 解码,错误协议全链路免改。
*/
export type InvokeResultPayload =
| {
ok: true;
result: unknown;
/** 仅在请求声明了 transfer 时出现;控制端 DeviceLinkClient 在交给调用方前还原。 */
transfer?: InvokeResultTransfer;
}
| {
ok: false;
error: { code: DeviceLinkErrorCode | 'IPC_ERROR'; message: string };
};
/** 被控端 → 控制端:广播转发(MAKER_PUSH.* / local-db 推送) */
export interface PushOwnerStamp {
dataOwnerId: string | null;
ownerGeneration: number;
}
export interface PushPayload {
channel: string;
payload: unknown;
/** Optional for compatibility with older controlled desktops. */
ownerStamp?: PushOwnerStamp;
}
// ─── REST 管理面(GET /api/device-link/devices)────────────────────────────────
/** server REST 返回的设备视图(apps/server/src/routes/deviceLink.ts 对应) */
export interface DeviceView {
deviceId: string;
name: string;
selfName?: string | null;
deviceInfo?: DeviceInfo | null;
platform: string | null;
appVersion: string | null;
/** ISO 字符串;从未上线过的离线设备可能为 null */
lastSeenAt: string | null;
online: boolean;
busy: boolean;
remoteControlEnabled: boolean;
isSelf: boolean;
}