@agentdock/sdk

客户端 SDK — Socket.IO 连接管理 + 类型安全 RPC + 离线队列。

概述

sdk 包为 Web 前端和其他客户端提供与 AgentDock server 的连接能力：

• 自动重连：断线后指数退避重连，连接状态实时可观测
• RPC 封装：类型安全的远程调用，Promise 风格
• 离线队列：断线期间的 RPC 调用自动入队，重连后按序 flush
• 事件流：订阅 CoreUpdate 实时推送

在架构中的位置

wire → crypto → sdk → web

依赖 wire（协议定义）和 crypto（加密），被 web 包使用。

模块结构

src/
├── client.ts  # AgentdockClient — 连接管理 + 事件订阅 + 状态监听
├── rpc.ts     # RpcClient — 类型安全 RPC + 离线队列 + flush
└── index.ts   # Barrel exports

API 参考

createClient (client.ts)

import { createClient } from '@agentdock/sdk';
import type { AgentdockClient, ClientConfig } from '@agentdock/sdk';

const client: AgentdockClient = createClient({
  serverUrl: 'https://api.agentdock.dev',
  token: 'user-auth-token',
  clientType: 'web', // 'web' | 'daemon' | 'cli'
  autoConnect: true, // 默认 true
});

// 连接状态监听
const unsub = client.onStatus((status: ConnectionStatus) => {
  // 'connected' | 'connecting' | 'disconnected' | 'error'
  console.log('Connection:', status);
});

// 订阅实时更新
const unsub2 = client.onUpdate((update: CoreUpdate) => {
  // 处理增量更新（会话事件、消息等）
});

// 手动连接/断开
client.connect();
client.disconnect(); // 清理所有事件监听器（L16 教训）

createRpcClient (rpc.ts)

import { createRpcClient } from '@agentdock/sdk';
import type { RpcClient, RpcTransport } from '@agentdock/sdk';

const rpc: RpcClient = createRpcClient(transport);

// 调用 RPC 方法（在线时立即发送，离线时入队）
const result: RpcResult = await rpc.call('method-name', params);

// 离线队列在重连时自动 flush（带互斥锁防竞态，L19 教训）

类型定义

type ConnectionStatus = 'connected' | 'connecting' | 'disconnected' | 'error';
type ClientType = 'web' | 'daemon' | 'cli';
type Unsubscribe = () => void;
type StatusListener = (status: ConnectionStatus) => void;
type UpdateListener = (update: CoreUpdate) => void;

开发

# 运行测试（42 tests）
pnpm --filter @agentdock/sdk test

# 覆盖率（目标 90%+）
pnpm --filter @agentdock/sdk test:coverage

设计决策

• Socket.IO 而非原生 WebSocket：自动重连、命名空间、房间、二进制支持
• RPC + 离线队列：离线期间操作不丢失，重连后补发
• flush 互斥锁：防止两次 reconnect 触发竞态（L19 教训）
• disconnect 清理：所有 on() 注册都有对应 off() 清理（L16 教训）