Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。
TypeScript agentai-agentai-assistantandroidclaude-codecodexelectroniosllmmacosreact-nativetypescriptwindows
import { PROTOCOL_VERSION, type Envelope } from './protocol.js';
/**
* Device-link 端到端可靠传输能力。
*
* relay 只看 kind / dst,payload 对 relay 不透明,所以可靠传输可以作为
* 现有 invoke / invoke-result / push 的 payload wrapper 增量加入,不需要
* 改动 v1 的路由集合,也不会让旧客户端收到新的 kind。
*/
export const DEVICE_LINK_CAPABILITY_RELIABLE_TRANSPORT = 'reliable-transport-v1';
/**
* 声明本端理解 link-close(transport-timeout) 的瞬时重置语义(收到后保留可靠层
* 并立即重建链路)。被控端**只对声明了该能力的控制端**发送 transport-timeout;
* 对旧控制端(未声明)保留整连接重连的兼容恢复路径——旧版把未知 reason 当永久
* 关闭处理且不会自动重开,relay/presence 又保持在线,订阅与在途请求会静默挂死。
*/
export const DEVICE_LINK_CAPABILITY_TRANSPORT_TIMEOUT_CLOSE = 'transport-timeout-close-v1';
/**
* 声明本端会在真正处理 link-accept、安装对端可靠 stream 基线后,回一条带
* linkRequestId 的 transport ACK。被控端只有收到这条确认才恢复向该控制端
* drain pending,避免把「accept 已写进本地 WebSocket」误当成「对端已提交链路」。
*
* 能力是 append-only:任一端未声明时继续沿用 v1 的即时 ready 语义,保证新旧
* Desktop / Mobile 可以独立升级;relay 仍只路由普通 push,不需要服务端改动。
*/
export const DEVICE_LINK_CAPABILITY_RELIABLE_LINK_CONFIRM = 'reliable-link-confirm-v1';
/** Mobile understands tool-input detail references and bounded plain result previews in
* list/created/maker:event. Around reads retain full detail; old peers stay unchanged. */
export const DEVICE_LINK_CAPABILITY_COMPACT_MESSAGE_HISTORY_V1 = 'compact-message-history-v1';
/** Desktop declares support for the structured history projection channels. */
export const DEVICE_LINK_CAPABILITY_HISTORY_VIEW_V1 = 'history-view-v1';
/** transport ACK 使用普通 push 承载,且 ACK 本身永不再包 transport。 */
export const DEVICE_LINK_TRANSPORT_ACK_CHANNEL = '__cindy/device-link/transport-ack';
/** 分片目标大小;给 JSON envelope 的路由头和 wrapper 留出足够余量。 */
export const MAX_TRANSPORT_CHUNK_BYTES = 128 * 1024;
/** 单条逻辑消息最多允许的分片数。 */
export const MAX_TRANSPORT_SEGMENTS = 64;
/** 单条逻辑消息上限;大于旧 2MB 帧上限,但必须能被有界 pending 完整保留。 */
export const MAX_TRANSPORT_MESSAGE_BYTES = 4 * 1024 * 1024;
/** 同一接收 stream 的待重组/待交付总字节上限。 */
export const MAX_TRANSPORT_REASSEMBLY_BYTES = 16 * 1024 * 1024;
/** 同一 peer 同时等待的重组消息上限。 */
export const MAX_TRANSPORT_REASSEMBLIES = 16;
/** 允许的最大乱序窗口;与发送端 pending 消息上限一致。 */
export const MAX_TRANSPORT_SEQUENCE_WINDOW = 64;
/** 单个 peer 未确认的逻辑消息上限。 */
export const MAX_TRANSPORT_PENDING_MESSAGES = 64;
/** 单个 peer 未确认消息的总字节上限。 */
export const MAX_TRANSPORT_PENDING_BYTES = 16 * 1024 * 1024;
/** WebSocket native send buffer 上限,超过后让可靠层收敛而不是继续灌数据。 */
export const MAX_TRANSPORT_WEBSOCKET_BUFFERED_BYTES = 8 * 1024 * 1024;
/** 未收到 ACK 时的重发间隔。 */
export const TRANSPORT_RETRY_INTERVAL_MS = 2_000;
/** 连续重发上限;之后保留消息等待重连,避免弱网下无限制造流量。 */
export const TRANSPORT_MAX_RETRY_ATTEMPTS = 5;
/**
* **定时器驱动**的单趟重发条数上限(旧→新,与累计 ACK 需要的顺序一致)。
*
* 为什么必须有这个上限:定时重发原本一趟遍历整个 pending 窗口(上限
* MAX_TRANSPORT_PENDING_MESSAGES = 64 条逻辑消息,每条还可能分多帧),在**一个同步
* 循环里**全部写进 ws。对端 relay 路由已失效时,这些帧逐帧弹回 DEVICE_OFFLINE ——
* 2026-08-08 线上单簇 213 条、单日 449 条,8-06 单簇 125 条,全部是这个形状。
*
* 这条路径原本有两道刹车,但都装在错的量上:
* - per-peer 制动(收到带 dst 的 DEVICE_OFFLINE → 复位该 peer 收发方向 + 清重试定时器,
* #1187)是**异步**的:relay-error 要一个 RTT 才回来,那一趟早已全部上线路,它只
* 拦得住下一轮;
* - 单趟中断(ws 容量抛 BACKPRESSURE → break,#2167)的阈值是 8MB buffered bytes,
* 而 64 条 maker:event 级小帧总共 1–2MB —— 灵敏度比这个故障低三个数量级。
*
* 于是「一趟重发多少条」从来没有上限,由「窗口里有多少条」决定,而窗口有多满又由
* 洪峰决定,两个失控量互相喂。本常量给它一个显式上限:健康 peer 的 ACK 正常回流、
* 队头被确认后窗口前移,后面的消息自然轮到;失联 peer 每趟只浪费这么多帧,第一条
* relay-error 回来后既有制动接管。
*
* 取 8 而不是 1:一趟只发一条会把「N 条积压 + 对端只是慢」的恢复拖成 N×重发间隔;
* 8 条既能在几趟内推进队头,又把失联时的单簇规模压到原来的 1/8 以下(线上最大簇
* 213 条 → 上限 8 条/趟)。它是**每趟**上限,不是窗口上限,不改变可靠交付语义:
* 没发出去的消息仍在 pending 里,下一趟继续。
*
* **所有恢复发送共用这一预算**(定时重发、link 重建 replay、outbox / drain
* 经 sendPeerEnvelope 的首发)。对端刚 accept 只证明 inbound 到了,outbound
* 仍可能立刻 DEVICE_OFFLINE;再给 replay 无限额度会把同一批 pending 在反复
* open 之间倒很多遍。恢复态先按本预算探测,收到可靠 ACK 后再继续 drain。
*/
export const TRANSPORT_RETRY_PASS_BUDGET = 8;
/**
* pending 里 push 帧的最大滞留时长(按单调时钟计量,不受墙钟校正影响)。push 是
* 尽力而为的实时镜像旁路,长时间未被 ACK(典型是对端离线)后只剩历史价值;
* 超龄后在普通入队压力下被兜底清扫,避免陈旧 push 独占有界 pending 缓冲。
* 重连重放前与 invoke-result 腾位不看此 TTL:这两条路径直接丢弃队头整个可丢弃
* 前缀(含新鲜 push 与 transport-skip 占位),保证 invoke-result 是最早的 live seq。
*/
export const TRANSPORT_PENDING_PUSH_MAX_AGE_MS = 5 * 60_000;
/**
* 自适应重发间隔的上限。弱网(机上 Wi-Fi、卫星链路)往返常达数秒,固定 2s 重发会
* 在 ACK 回来前反复写出同一帧,2026-10-12 机上实测 40% 出站字节是重发;但间隔也
* 不能无限拉长,否则真正断掉的链路要很久才走到重试耗尽的止损。
*/
export const TRANSPORT_ADAPTIVE_RETRY_MAX_MS = 10_000;
/**
* RFC 6298 平滑往返估计,样本取小消息从本轮首次写出到被累计 ACK 的时长。
* 不套用 Karn 规则(只采未重发的消息):链路往返超过重发间隔时每帧都会先被
* 重发,按 Karn 永远采不到样本,自适应恰在最需要时失效。代价是真丢包时样本
* 偏大,单样本按 TRANSPORT_ADAPTIVE_RETRY_MAX_MS 截断。
*/
export interface RetransmitEstimate {
srttMs: number | null;
rttVarMs: number;
/** End-to-end delivery, including relay queues; never inferred from socket drain. */
deliveryBytesPerMs?: number;
}
/** Only first-attempt ACKs give an unambiguous large-message delivery sample. */
export function updateDeliveryEstimate(estimate: RetransmitEstimate, bytes: number, elapsedMs: number): void {
if (bytes < 64 * 1024 || !Number.isFinite(elapsedMs) || elapsedMs <= 0) return;
const sample = bytes / elapsedMs;
const previous = estimate.deliveryBytesPerMs;
// Slow down immediately, recover gradually; bursts must not erase a slow-path observation.
estimate.deliveryBytesPerMs = previous === undefined ? sample : Math.min(sample, previous * 0.75 + sample * 0.25);
}
export function updateRetransmitEstimate(estimate: RetransmitEstimate, sampleMs: number): void {
const sample = Math.min(TRANSPORT_ADAPTIVE_RETRY_MAX_MS, Math.max(0, sampleMs));
if (estimate.srttMs === null) {
estimate.srttMs = sample;
estimate.rttVarMs = sample / 2;
return;
}
estimate.rttVarMs = 0.75 * estimate.rttVarMs + 0.25 * Math.abs(estimate.srttMs - sample);
estimate.srttMs = 0.875 * estimate.srttMs + 0.125 * sample;
}
/** 重发基准间隔:不低于配置值,慢链路按 SRTT + 4·RTTVAR 放宽,封顶。 */
export function retransmitBaseMs(estimate: RetransmitEstimate, configuredMs: number): number {
if (estimate.srttMs === null) return configuredMs;
const adaptive = Math.min(
TRANSPORT_ADAPTIVE_RETRY_MAX_MS,
estimate.srttMs + 4 * estimate.rttVarMs,
);
return Math.max(configuredMs, adaptive);
}
/**
* 单条可靠消息距上次写出后多久可以重发。字节节奏和已确认的交付速度估算传输耗时;
* 超过 512KiB 的回包再按次数退避,传输等待封顶 120s。小消息保留 RTT 退避,
* 请求自身的响应截止时间不因重传延长。
*/
export function reliableRetryDelayMs(
estimate: RetransmitEstimate,
configuredMs: number,
sizeIntervals: number,
attempts: number,
bytes = 0,
): number {
const backoff = Math.min(4, 2 ** Math.max(0, attempts - 1));
const measuredDelivery = bytes >= 64 * 1024 && estimate.deliveryBytesPerMs
? bytes / estimate.deliveryBytesPerMs * 1.5 : 0;
// A 1.85 MB result needs roughly two minutes at 128 Kbit/s. The old 30s
// size ceiling repeatedly copied it before its first ACK. Keep a finite
// ceiling and retry exhaustion, while leaving small-message timing intact.
const delivery = Math.min(120_000,
Math.max(configuredMs * sizeIntervals, measuredDelivery) * (bytes > 512 * 1024 ? backoff : 1));
return Math.max(delivery, retransmitBaseMs(estimate, configuredMs) * backoff);
}
const TRANSPORT_MARKER = '__cindyDeviceLinkTransport';
const TRANSPORT_SKIP_MARKER = '__cindyDeviceLinkTransportSkip';
const TRANSPORT_VERSION = 1;
export interface ReliableTransportMeta {
version: 1;
streamId: string;
seq: number;
/** 发送端当前仍可能重放的最小 seq,用于接收端进程重启后恢复累计 ACK 基线。 */
baseSeq?: number;
segment?: {
index: number;
total: number;
totalBytes: number;
};
}
export interface ReliableTransportPayload {
[TRANSPORT_MARKER]: ReliableTransportMeta;
/** JSON.stringify(payload) 的 UTF-8 字符串;分片时是一个片段。 */
data: string;
}
export interface TransportAckPayload {
streamId: string;
ackSeq: number;
/** 处理 link-accept 后回显其 request id;缺省表示普通累计 ACK / 旧客户端。 */
linkRequestId?: string;
}
export interface TransportSkipPayload {
[TRANSPORT_SKIP_MARKER]: true;
}
export interface ParsedTransportPayload {
meta: ReliableTransportMeta;
data: string;
}
export function byteLength(text: string): number {
let bytes = 0;
for (let index = 0; index < text.length; index += 1) {
const codePoint = text.codePointAt(index)!;
if (codePoint > 0xffff) index += 1;
bytes += codePoint <= 0x7f
? 1
: codePoint <= 0x7ff
? 2
: codePoint <= 0xffff
? 3
: 4;
}
return bytes;
}
/**
* 把 JSON 文本按 UTF-8 字节切开,不从多字节字符中间切断。
* for...of 按 code point 遍历,因此不会拆开 surrogate pair。
*/
function splitUtf8(text: string, maxBytes: number): string[] {
if (maxBytes <= 0) throw new Error('maxBytes must be positive');
const chunks: string[] = [];
let chunkStart = 0;
let offset = 0;
let chunkBytes = 0;
for (const char of text) {
const codePoint = char.codePointAt(0)!;
const charBytes = codePoint <= 0x7f
? 1
: codePoint <= 0x7ff
? 2
: codePoint <= 0xffff
? 3
: 4;
if (offset > chunkStart && chunkBytes + charBytes > maxBytes) {
chunks.push(text.slice(chunkStart, offset));
chunkStart = offset;
chunkBytes = 0;
}
// 单个 code point 不可能超过 4 bytes;保留这个分支让边界参数错误
// 变成显式失败,而不是生成一个超过约定大小的片段。
if (charBytes > maxBytes) throw new Error('transport chunk size is smaller than one code point');
offset += char.length;
chunkBytes += charBytes;
}
if (offset > chunkStart || text.length === 0) chunks.push(text.slice(chunkStart, offset));
return chunks;
}
function isRecord(value: unknown): value is Record<string, unknown> {
return typeof value === 'object' && value !== null && !Array.isArray(value);
}
export function makeTransportSkipPayload(): TransportSkipPayload {
return { [TRANSPORT_SKIP_MARKER]: true };
}
export function isTransportSkipPayload(payload: unknown): payload is TransportSkipPayload {
return isRecord(payload) && payload[TRANSPORT_SKIP_MARKER] === true;
}
/** 创建一个或多个仍使用原 kind 的 payload 分片。 */
export function encodeReliableFrames(
env: Envelope,
streamId: string,
seq: number,
baseSeq = 1,
): Envelope[] {
if (
!streamId
|| !Number.isSafeInteger(seq)
|| seq <= 0
|| !Number.isSafeInteger(baseSeq)
|| baseSeq <= 0
|| baseSeq > seq
) {
throw new Error('invalid transport stream metadata');
}
const json = JSON.stringify(env.payload);
if (typeof json !== 'string') throw new Error('transport payload is not JSON serializable');
const totalBytes = byteLength(json);
if (totalBytes > MAX_TRANSPORT_MESSAGE_BYTES) {
throw new Error(`transport payload exceeds ${MAX_TRANSPORT_MESSAGE_BYTES} bytes`);
}
const chunks = splitUtf8(json, MAX_TRANSPORT_CHUNK_BYTES);
if (chunks.length > MAX_TRANSPORT_SEGMENTS) {
throw new Error(`transport payload exceeds ${MAX_TRANSPORT_SEGMENTS} segments`);
}
return chunks.map((data, index) => {
const meta: ReliableTransportMeta = {
version: TRANSPORT_VERSION,
streamId,
seq,
...(baseSeq > 1 ? { baseSeq } : {}),
...(chunks.length > 1
? { segment: { index, total: chunks.length, totalBytes } }
: {}),
};
return {
...env,
payload: {
[TRANSPORT_MARKER]: meta,
data,
} satisfies ReliableTransportPayload,
};
});
}
/** 返回 null 表示这是旧客户端的普通 payload,而不是 transport 帧。 */
export function parseTransportPayload(payload: unknown): ParsedTransportPayload | null {
if (!isRecord(payload)) return null;
const rawMeta = payload[TRANSPORT_MARKER];
if (!isRecord(rawMeta) || rawMeta.version !== TRANSPORT_VERSION) return null;
const streamId = rawMeta.streamId;
const seq = rawMeta.seq;
const baseSeq = rawMeta.baseSeq === undefined ? 1 : rawMeta.baseSeq;
if (
typeof streamId !== 'string' ||
streamId.length < 1 ||
streamId.length > 128 ||
typeof seq !== 'number' ||
!Number.isSafeInteger(seq) ||
seq <= 0 ||
typeof baseSeq !== 'number' ||
!Number.isSafeInteger(baseSeq) ||
baseSeq <= 0 ||
baseSeq > seq ||
typeof payload.data !== 'string'
) {
return null;
}
const segment = rawMeta.segment;
if (segment !== undefined) {
if (!isRecord(segment)) return null;
const index = segment.index;
const total = segment.total;
const totalBytes = segment.totalBytes;
if (
typeof index !== 'number' ||
typeof total !== 'number' ||
typeof totalBytes !== 'number' ||
!Number.isSafeInteger(index) ||
!Number.isSafeInteger(total) ||
!Number.isSafeInteger(totalBytes) ||
index < 0 ||
total < 2 ||
index >= total ||
total > MAX_TRANSPORT_SEGMENTS ||
totalBytes < 0 ||
totalBytes > MAX_TRANSPORT_MESSAGE_BYTES ||
totalBytes <= MAX_TRANSPORT_CHUNK_BYTES ||
totalBytes > total * MAX_TRANSPORT_CHUNK_BYTES
) {
return null;
}
return {
meta: {
version: TRANSPORT_VERSION,
streamId,
seq,
...(baseSeq > 1 ? { baseSeq } : {}),
segment: {
index,
total,
totalBytes,
},
},
data: payload.data,
};
}
return {
meta: {
version: TRANSPORT_VERSION,
streamId,
seq,
...(baseSeq > 1 ? { baseSeq } : {}),
},
data: payload.data,
};
}
export function decodeTransportJson(json: string, expectedBytes?: number): unknown {
if (expectedBytes !== undefined && byteLength(json) !== expectedBytes) {
throw new Error('transport payload byte length mismatch');
}
return JSON.parse(json);
}
export function makeTransportAck(
dst: string,
streamId: string,
ackSeq: number,
linkRequestId?: string,
): Envelope {
return {
v: PROTOCOL_VERSION,
kind: 'push',
dst,
payload: {
channel: DEVICE_LINK_TRANSPORT_ACK_CHANNEL,
payload: {
streamId,
ackSeq,
...(linkRequestId ? { linkRequestId } : {}),
} satisfies TransportAckPayload,
},
};
}
export function parseTransportAck(env: Envelope): TransportAckPayload | null {
if (env.kind !== 'push' || !isRecord(env.payload)) return null;
if (env.payload.channel !== DEVICE_LINK_TRANSPORT_ACK_CHANNEL) return null;
const payload = env.payload.payload;
const streamId = isRecord(payload) ? payload.streamId : undefined;
const ackSeq = isRecord(payload) ? payload.ackSeq : undefined;
const linkRequestId = isRecord(payload) ? payload.linkRequestId : undefined;
if (
typeof streamId !== 'string' ||
typeof ackSeq !== 'number' ||
!Number.isSafeInteger(ackSeq) ||
ackSeq < 0 ||
(linkRequestId !== undefined && (
typeof linkRequestId !== 'string'
|| linkRequestId.length < 1
|| linkRequestId.length > 256
))
) {
return null;
}
return {
streamId,
ackSeq,
...(typeof linkRequestId === 'string' ? { linkRequestId } : {}),
};
}