linkdood-sdk

信源密信（Linkdood）Node.js SDK，用于与 Linkdood 服务端建立 WebSocket 连接并收发消息。

安装

npm install linkdood-sdk

快速开始

import {
  initializeLinkdoodSdkSession,
  connectLinkdoodSdkSocket,
  decodeLinkdoodSdkInboundMessage,
  sendLinkdoodSdkReply,
} from 'linkdood-sdk';

// 1. 配置
const config = {
  server: 'https://192.168.0.176:10443',
  appId: 'your-app-id',
  appSecret: 'your-app-secret',
  rejectUnauthorized: false,  // 内网环境必填
};

// 2. 初始化会话
const session = await initializeLinkdoodSdkSession({ config });

// 3. 建立 WebSocket 连接
const connection = await connectLinkdoodSdkSocket({
  config,
  session,
});

// 4. 监听消息
connection.socket.on('message', (event, payload) => {
  const message = decodeLinkdoodSdkInboundMessage({
    event,
    payload,
    accountId: 'default',
  });

  if (!message) return;

  console.log('收到消息:', message.message.text);

  // 5. 回复消息
  sendLinkdoodSdkReply({
    socket: connection.socket,
    config,
    session: connection.session,
    payload: {
      reply: '收到',
      to: message.message.from.id,
      sessionKey: message.message.conversationId,
    },
  });
});

使用流程

┌─────────────────────────────────────────────────────────────────┐
│                         SDK 使用流程                              │
├─────────────────────────────────────────────────────────────────┤
│                                                                   │
│  1. 配置                                                          │
│     const config = { server, appId, appSecret, ... }            │
│                     │                                            │
│                     ▼                                            │
│  2. 初始化会话                                                     │
│     const session = await initializeLinkdoodSdkSession(...)     │
│                     │                                            │
│                     ▼                                            │
│  3. 建立连接                                                      │
│     const connection = await connectLinkdoodSdkSocket(...)     │
│                     │                                            │
│                     ▼                                            │
│  4. 监听消息                                                      │
│     connection.socket.on('message', (event, payload) => {       │
│       const msg = decodeLinkdoodSdkInboundMessage(...)          │
│     })                                                            │
│                     │                                            │
│                     ▼                                            │
│  5. 发送回复（可选）                                               │
│     await sendLinkdoodSdkReply(...)                             │
│                                                                   │
└─────────────────────────────────────────────────────────────────┘

配置参数

| 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | server | string | ✅ | 服务端地址，如 https://192.168.0.176:10443 | | appId | string | ✅ | 应用 ID | | appSecret | string | ✅ | 应用密钥 | | rejectUnauthorized | boolean | ❌ | 内网环境设为 false（跳过 SSL 验证） |

步骤详解

步骤 1：配置

const config = {
  server: 'https://192.168.0.176:10443',
  appId: 'your-app-id',
  appSecret: 'your-app-secret',
  rejectUnauthorized: false,
};

步骤 2：初始化会话

调用 initializeLinkdoodSdkSession 获取 WebSocket 连接所需的凭证：

const session = await initializeLinkdoodSdkSession({ config });

返回值 session 包含：

• endpoint: WebSocket 连接地址
• token: 认证令牌
• namespace: Socket.IO 命名空间

步骤 3：建立连接

const connection = await connectLinkdoodSdkSocket({
  config,
  session,
});

返回值 connection 包含：

• socket: WebSocket 连接对象
• session: 会话信息
• heartbeatConfig: 心跳配置

步骤 4：监听消息

connection.socket.on('message', (event, payload) => {
  const message = decodeLinkdoodSdkInboundMessage({
    event,
    payload,
    accountId: 'default',
  });

  if (!message) return;  // 系统事件返回 null

  // 处理业务消息
  const { from, text, conversationId, media } = message.message;
  console.log(`收到 ${from.name} 的消息: ${text}`);
});

消息字段：

| 字段 | 说明 | |------|------| | from.id | 发送者用户 ID | | from.name | 发送者昵称 | | text | 文本内容 | | conversationId | 会话 ID | | media | 媒体附件数组 |

步骤 5：发送回复

await sendLinkdoodSdkReply({
  socket: connection.socket,
  config,
  session: connection.session,
  payload: {
    reply: '收到: ' + text,
    to: from.id,           // 回复给发送者
    sessionKey: conversationId,
    end: true,             // 是否结束会话
  },
});

断开连接

// 方法 1：通过 socket 断开
connection.socket.disconnect();

// 方法 2：移除所有监听器
connection.socket.removeAllListeners();

完整示例

import {
  initializeLinkdoodSdkSession,
  connectLinkdoodSdkSocket,
  decodeLinkdoodSdkInboundMessage,
  sendLinkdoodSdkReply,
} from 'linkdood-sdk';

async function main() {
  const config = {
    server: 'https://192.168.0.176:10443',
    appId: 'your-app-id',
    appSecret: 'your-app-secret',
    rejectUnauthorized: false,
  };

  try {
    // 初始化会话
    const session = await initializeLinkdoodSdkSession({ config });

    // 建立连接
    const connection = await connectLinkdoodSdkSocket({
      config,
      session,
    });

    console.log('连接成功');

    // 监听消息
    connection.socket.on('message', async (event, payload) => {
      const message = decodeLinkdoodSdkInboundMessage({
        event,
        payload,
        accountId: 'default',
      });

      if (!message) return;

      const { from, text, conversationId } = message.message;
      console.log(`收到 ${from.name}: ${text}`);

      // 回复
      await sendLinkdoodSdkReply({
        socket: connection.socket,
        config,
        session: connection.session,
        payload: {
          reply: `收到: ${text}`,
          to: from.id,
          sessionKey: conversationId,
        },
      });
    });

    // 监听断开
    connection.socket.on('disconnect', (reason) => {
      console.log('断开连接:', reason);
    });

  } catch (error) {
    console.error('错误:', error);
  }
}

main();

导出说明

连接相关

• initializeLinkdoodSdkSession - 初始化会话
• connectLinkdoodSdkSocket - 建立 WebSocket 连接

消息处理

• decodeLinkdoodSdkInboundMessage - 解码收到的消息
• sendLinkdoodSdkReply - 发送文本回复
• sendLinkdoodSdkAction - 发送结构化动作

日志

• logLinkdoodSdk - 普通日志
• logLinkdoodSdkError - 错误日志
• logLinkdoodSdkSuccess - 成功日志
• logLinkdoodSdkStep - 步骤日志
• logLinkdoodSdkBox - 边框日志

注意事项

1. 内网环境：必须设置 rejectUnauthorized: false，否则连接会失败

2. 消息解码：decodeLinkdoodSdkInboundMessage 对系统事件返回 null，业务消息返回对象

3. Socket.IO 事件：message 事件包含业务消息，其他事件（如 disconnect）需单独监听

4. 重连：SDK 不内置重连，需要开发者自行实现

License

MIT