Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。
TypeScript agentai-agentai-assistantandroidclaude-codecodexelectroniosllmmacosreact-nativetypescriptwindows
import type { InvokePayload, InvokeResultPayload } from './protocol.js';
import { byteLength } from './transport.js';
/**
* invoke 结果的传输编码(弱网减流量),与业务 channel 无关:
*
* - 控制端在 invoke payload 上可选携带 `transfer`:能解 gzip 时带 `gzip: 1`;
* 本机已持有同一 channel + args 的上一份结果时带它的内容标签 `ifNoneMatch`。
* - 被控端照常执行 handler,只在发出结果时改写:大结果附带内容标签;与
* `ifNoneMatch` 相同则只回 `notModified`;否则在控制端声明可解时 gzip。
*
* handler 每次都真实执行,`notModified` 只省略字节相同的结果,因此对任何
* channel(包括有副作用的)语义不变。旧被控端忽略 `transfer` 回普通结果;
* 旧控制端从不携带 `transfer`,被控端也就不会对它编码。
*/
/** 控制端 → 被控端,逐请求可选。 */
export interface InvokeTransferOptions {
/** 控制端能解开 `gzipBase64` 结果。 */
gzip?: 1;
/** 控制端已持有的同 channel + args 结果的内容标签。 */
ifNoneMatch?: string;
}
/** 被控端 → 控制端,只出现在 ok 结果上;有 `notModified` / `gzipBase64` 时 result 为 null。 */
export interface InvokeResultTransfer {
/** 完整结果 JSON 的内容标签;控制端据此缓存。 */
tag?: string;
notModified?: true;
/** gzip(UTF-8 JSON.stringify(result)) 的 base64。 */
gzipBase64?: string;
}
/** host 注入:device-link 包保持零依赖,压缩与摘要由各端平台实现提供。 */
export interface DeviceLinkTransferCodec {
/**
* 控制端:解开被控端的 gzip 结果。解出的字符串超过 maxChars 时必须在继续
* 分配前抛错——压缩包只受传输大小限制,高压缩比结果可以展开成数百 MB。
*/
gunzipBase64?(base64: string, maxChars: number): string;
/** 被控端:压缩结果。 */
gzipBase64?(text: string): string;
/** 被控端:结果内容标签,须抗碰撞(如 SHA-256)。 */
contentTag?(text: string): string;
}
/** 小结果编码收益抵不过开销,原样发送。 */
export const INVOKE_TRANSFER_MIN_CHARS = 4 * 1024;
/**
* 编码结果的解压上限,与传输层单条逻辑消息上限同量级:更大的结果被控端不编码,
* 仍走原有的超限处理;控制端解压超过即判失败。
*/
export const INVOKE_TRANSFER_MAX_CHARS = 4 * 1024 * 1024;
const MAX_TAG_CHARS = 128;
/** 缓存键(channel + args)过长说明 args 本身就是大载荷,不值得缓存。 */
const MAX_CACHE_KEY_CHARS = 4 * 1024;
const MAX_CACHE_ENTRIES = 32;
/** JS 字符串按 UTF-16 计,约 8MB 内存。 */
const MAX_CACHE_CHARS = INVOKE_TRANSFER_MAX_CHARS;
const MAX_INBOUND_OPTIONS = 512;
export function parseInvokeTransferOptions(value: unknown): InvokeTransferOptions | null {
if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
const raw = value as Record<string, unknown>;
const options: InvokeTransferOptions = {};
if (raw.gzip === 1) options.gzip = 1;
if (typeof raw.ifNoneMatch === 'string' && raw.ifNoneMatch.length > 0
&& raw.ifNoneMatch.length <= MAX_TAG_CHARS) {
options.ifNoneMatch = raw.ifNoneMatch;
}
return options.gzip || options.ifNoneMatch ? options : null;
}
/** 被控端:按控制端在该请求上的声明改写 ok 结果;不满足条件时原样返回。 */
export function encodeInvokeResultTransfer(
options: InvokeTransferOptions,
payload: InvokeResultPayload,
codec: DeviceLinkTransferCodec,
): InvokeResultPayload {
if (!payload.ok || payload.transfer) return payload;
let text: string | undefined;
try {
text = JSON.stringify(payload.result);
} catch {
return payload;
}
if (text === undefined || text.length < INVOKE_TRANSFER_MIN_CHARS
|| text.length > INVOKE_TRANSFER_MAX_CHARS) return payload;
const tag = codec.contentTag?.(text);
if (tag !== undefined && options.ifNoneMatch === tag) {
return { ok: true, result: null, transfer: { tag, notModified: true } };
}
if (options.gzip && codec.gzipBase64) {
const gzipBase64 = codec.gzipBase64(text);
// Base64 is ASCII, whereas Chinese/emoji JSON takes multiple UTF-8 bytes
// per character. Compare transmitted bytes, not JS string lengths.
if (gzipBase64.length < byteLength(text) * 0.9) {
return { ok: true, result: null, transfer: { ...(tag ? { tag } : {}), gzipBase64 } };
}
}
return tag ? { ...payload, transfer: { tag } } : payload;
}
/** 被控端:记住每个入站 invoke 的声明,供回结果(含补发 / 降级重发)时编码。 */
export class InboundInvokeTransferOptions {
private readonly options = new Map<string, InvokeTransferOptions>();
record(src: string, requestId: string, payload: unknown): void {
const transfer = parseInvokeTransferOptions((payload as InvokePayload | undefined)?.transfer);
if (!transfer) return;
const key = `${src}\u0000${requestId}`;
this.options.delete(key);
this.options.set(key, transfer);
while (this.options.size > MAX_INBOUND_OPTIONS) {
this.options.delete(this.options.keys().next().value!);
}
}
get(src: string, requestId: string): InvokeTransferOptions | undefined {
return this.options.get(`${src}\u0000${requestId}`);
}
clear(): void {
this.options.clear();
}
}
interface CachedResult {
tag: string;
text: string;
}
/** 控制端发出一次 invoke 前固定的编码上下文;结果回来时只用这份快照解码。 */
export interface PreparedInvokeTransfer {
payload: InvokePayload;
decode(result: InvokeResultPayload): InvokeResultPayload;
}
/** 控制端:按 peer + channel + args 保留最近的大结果,有界 LRU,只在内存。 */
export class InvokeResultCache {
private readonly entries = new Map<string, CachedResult>();
private chars = 0;
constructor(private readonly codec: DeviceLinkTransferCodec | undefined) {}
prepare(dst: string, payload: InvokePayload): PreparedInvokeTransfer {
const key = cacheKey(dst, payload);
// 请求时固定快照:结果回来前即使被淘汰,notModified 仍能还原。
const cached = key ? this.entries.get(key) : undefined;
const transfer: InvokeTransferOptions = {};
if (this.codec?.gunzipBase64) transfer.gzip = 1;
if (cached) transfer.ifNoneMatch = cached.tag;
const prepared = transfer.gzip || transfer.ifNoneMatch ? { ...payload, transfer } : payload;
return {
payload: prepared,
decode: (result) => this.decode(key, cached, result),
};
}
clear(): void {
this.entries.clear();
this.chars = 0;
}
private decode(
key: string | null,
cached: CachedResult | undefined,
result: InvokeResultPayload,
): InvokeResultPayload {
if (!result.ok || !result.transfer) return result;
const transfer = result.transfer;
let text: string;
let value: unknown;
try {
if (transfer.notModified) {
if (!cached || cached.tag !== transfer.tag) throw new Error('unexpected notModified');
text = cached.text;
value = JSON.parse(text);
} else if (typeof transfer.gzipBase64 === 'string') {
if (!this.codec?.gunzipBase64) throw new Error('unexpected gzip result');
text = this.codec.gunzipBase64(transfer.gzipBase64, INVOKE_TRANSFER_MAX_CHARS);
value = JSON.parse(text);
} else {
value = result.result;
text = JSON.stringify(value);
}
} catch (err) {
return {
ok: false,
error: {
code: 'IPC_ERROR',
message: `[INTERNAL] invalid invoke result transfer: ${err instanceof Error ? err.message : String(err)}`,
},
};
}
if (key && typeof transfer.tag === 'string' && transfer.tag.length <= MAX_TAG_CHARS) {
this.remember(key, { tag: transfer.tag, text });
}
return { ok: true, result: value };
}
private remember(key: string, entry: CachedResult): void {
const previous = this.entries.get(key);
if (previous) {
this.chars -= previous.text.length;
this.entries.delete(key);
}
if (entry.text.length > MAX_CACHE_CHARS) return;
this.entries.set(key, entry);
this.chars += entry.text.length;
while (this.entries.size > MAX_CACHE_ENTRIES || this.chars > MAX_CACHE_CHARS) {
const [oldestKey, oldest] = this.entries.entries().next().value!;
this.chars -= oldest.text.length;
this.entries.delete(oldestKey);
}
}
}
function cacheKey(dst: string, payload: InvokePayload): string | null {
let args: string;
try {
args = JSON.stringify(payload.args ?? []);
} catch {
return null;
}
const key = `${dst}\u0000${payload.channel}\u0000${args}`;
return key.length <= MAX_CACHE_KEY_CHARS ? key : null;
}