首次推送

2026-07-20 19:01:03 +08:00
parent ea01b9cf99
commit ef1bf61f9f
4484 changed files with 937163 additions and 1 deletions
@@ -0,0 +1,888 @@
+# teamspeak-go SDK 文档
+
+基于 `github.com/honeybbq/teamspeak-go` 源码整理。
+
+触发形式说明：
+
+- **客户端请求** — 客户端主动发送命令到服务端，等待响应
+- **服务端推送** — 服务端主动下发通知，客户端被动接收
+- **本地调用** — 纯客户端本地操作，不涉及网络通信
+
+> **关于"通过指令构建的能力"**: 部分 API 标注为"通过指令构建的能力"，表示其底层封装了 TS3 协议命令（如 `serverinfo`、`channelinfo`、`banlist` 等），通过 SDK 的 `ExecCommand` / `ExecCommandWithResponse` 基础设施发送并解析响应。这些命令与 SDK 原生内置的命令（如握手、事件通知）不同，是通过协议命令扩展出的额外能力，可参考对应的协议命令语法进行调试或扩展。
+
+---
+
+## 1. 连接管理
+
+### 构造与连接
+
+| 方法 | 触发形式 | 用法 | 作用 | 描述 |
+|------|----------|------|------|------|
+| `NewClient` | 本地调用 | `NewClient(identity, addr, nickname, ...options) *Client` | 创建客户端 | 创建 TeamSpeak 客户端实例。`identity` 为加密身份，`addr` 为服务器地址，`nickname` 为昵称，`options` 可选配置 |
+| `Connect` | 客户端请求 | `Connect() error` | 连接服务器 | 发起 UDP 会话和握手连接 |
+| `Disconnect` | 客户端请求 | `Disconnect() error` | 断开连接 | 优雅断开连接，发送 shutdown reason |
+| `WaitConnected` | 本地调用 | `WaitConnected(ctx context.Context) error` | 等待连接就绪 | 阻塞等待握手完成，支持 context 取消。发送命令前必须先调用 |
+
+### 连接选项（ClientOption）
+
+| 方法 | 触发形式 | 用法 | 作用 | 描述 |
+|------|----------|------|------|------|
+| `WithLogger` | 本地调用 | `WithLogger(logger *slog.Logger)` | 设置日志 | 注入自定义 slog.Logger |
+| `WithResolver` | 本地调用 | `WithResolver(r AddrResolver)` | 设置解析器 | 自定义 DNS/TSDNS 解析 |
+| `WithServerPassword` | 本地调用 | `WithServerPassword(password string)` | 服务器密码 | 连接时使用的服务器密码 |
+| `WithDefaultChannel` | 本地调用 | `WithDefaultChannel(channel string)` | 默认频道 | 连接后自动加入的频道名 |
+| `WithDefaultChannelPassword` | 本地调用 | `WithDefaultChannelPassword(password string)` | 默认频道密码 | 默认频道的密码 |
+| `WithCommandMiddleware` | 本地调用 | `WithCommandMiddleware(mw ...CommandMiddleware)` | 命令中间件 | 拦截/修改发送的命令 |
+| `WithEventMiddleware` | 本地调用 | `WithEventMiddleware(mw ...EventMiddleware)` | 事件中间件 | 拦截/修改接收的事件 |
+
+---
+
+## 2. 事件注册
+
+### 事件处理器
+
+| 方法 | 触发形式 | 用法 | 作用 | 描述                                                     |
+|------|----------|------|------|--------------------------------------------------------|
+| `OnConnected` | 服务端推送 | `OnConnected(fn func())` | 连接成功 | 客户端完成握手后触发                                             |
+| `OnDisconnected` | 服务端推送 | `OnDisconnected(fn func(error))` | 断开连接 | 连接断开时触发，携带错误原因                                         |
+| `OnTextMessage` | 服务端推送 | `OnTextMessage(fn func(TextMessage))` | 收到消息 | 收到文本消息（私聊/频道/服务器），对应 `notifytextmessage`               |
+| `OnClientEnter` | 服务端推送 | `OnClientEnter(fn func(ClientInfo))` | 用户进入 | 客户端进入视野（进入服务器），对应 `notifycliententerview`              |
+| `OnClientLeave` | 服务端推送 | `OnClientLeave(fn func(ClientLeftViewEvent))` | 用户离开 | 客户端离开视野（离开服务器），对应 `notifyclientleftview`               |
+| `OnClientMoved` | 服务端推送 | `OnClientMoved(fn func(ClientMovedEvent))` | 用户移动 | 客户端在频道间移动，对应 `notifyclientmoved`                       |
+| `OnPoked` | 服务端推送 | `OnPoked(fn func(PokeEvent))` | 被戳一戳 | 收到其他用户的 Poke，对应 `notifyclientpoke`                     |
+| `OnKicked` | 服务端推送 | `OnKicked(fn func(string))` | 被踢出 | 自己被踢出频道或服务器，从 `notifyclientleftview` 中 reasonid=4/5 触发 |
+| `OnVoiceData` | 服务端推送 | `OnVoiceData(fn func(VoiceDataEvent))` | 收到语音 | 收到同频道其他客户端发送的 Opus 语音帧，通过 UDP 二进制包传输          |
+
+### VoiceDataEvent 结构
+
+收到语音数据的事件载荷，由 `OnVoiceData` 回调接收。
+
+| 字段 | 类型 | 描述 |
+|------|------|------|
+| `ClientID` | `uint16` | 发送者客户端 ID |
+| `Data` | `[]byte` | Opus 编码的语音帧原始数据 |
+| `Codec` | `byte` | 编解码器类型：4 = Opus Voice（语音），5 = Opus Music（音乐） |
+
+**语音包 UDP 二进制格式**（SDK 内部解析后填充 `VoiceDataEvent`）：
+
+```
+Offset  Size   Field
+0       2      packetID（big-endian）
+2       2      clientID（little-endian）
+4       1      codec（4=Opus Voice, 5=Opus Music）
+5       N      Opus 编码数据
+```
+
+**语音接收流程**：
+
+```
+Server UDP 语音包
+  → PacketHandler 解密
+  → handlePacket() 路由 PacketTypeVoice(0) / PacketTypeVoiceWhisper(1)
+  → 解析 clientID、codec、opusData
+  → notifyEvent(VoiceDataEvent{...})
+  → startEventLoop 串行分发
+  → OnVoiceData 注册的所有 handler 依次调用
+```
+
+---
+
+## 3. 聊天命令
+
+| 方法 | 触发形式 | 用法 | 作用 | 描述 |
+|------|----------|------|------|------|
+| `SendTextMessage` | 客户端请求 | `SendTextMessage(targetMode int, targetID uint64, msg string) error` | 发送文本消息 | `targetMode`: 1=私聊, 2=频道, 3=服务器。对应协议 `sendtextmessage` |
+| `Poke` | 客户端请求 | `Poke(clid uint16, msg string) error` | 发送 Poke | 向指定用户发送戳一戳消息。对应协议 `clientpoke` |
+
+### TextMessage 结构
+
+| 字段 | 类型 | 描述 |
+|------|------|------|
+| `TargetMode` | `int` | 1=私聊, 2=频道, 3=服务器 |
+| `Target` | `uint64` | 目标 ID（频道 ID 或客户端 ID） |
+| `InvokerID` | `uint16` | 发送者客户端 ID |
+| `InvokerName` | `string` | 发送者昵称 |
+| `InvokerUID` | `string` | 发送者唯一标识 |
+| `InvokerGroups` | `[]string` | 发送者所在组 |
+| `Message` | `string` | 消息内容 |
+
+### PokeEvent 结构
+
+| 字段 | 类型 | 描述 |
+|------|------|------|
+| `InvokerID` | `uint16` | 发送者客户端 ID |
+| `InvokerName` | `string` | 发送者昵称 |
+| `InvokerUID` | `string` | 发送者唯一标识 |
+| `Message` | `string` | Poke 消息内容 |
+
+---
+
+## 4. 客户端命令
+
+### 基础客户端操作
+
+| 方法 | 触发形式 | 用法 | 作用 | 描述 |
+|------|----------|------|------|------|
+| `ClientID` | 本地调用 | `ClientID() uint16` | 获取自身 ID | 返回服务器分配的客户端 ID（本地缓存） |
+| `ListClients` | 客户端请求 | `ListClients() ([]ClientInfo, error)` | 在线用户列表 | 返回当前服务器所有在线客户端。对应协议 `clientlist` |
+| `ClientMove` | 客户端请求 | `ClientMove(clid uint16, channelID uint64, password string) error` | 移动用户 | 将客户端移至指定频道。对应协议 `clientmove` |
+
+### 客户端信息查询
+
+> **通过指令构建的能力** — 底层封装 TS3 协议命令 `clientinfo`、`clientdblist`、`clientdbfind`。
+
+| 方法 | 触发形式 | 协议命令 | 用法 | 作用 |
+|------|----------|----------|------|------|
+| `GetClientInfo` | 客户端请求 | `clientinfo clid=X` | `GetClientInfo(clid uint16) (map[string]string, error)` | 查询在线用户详情（原始 map） |
+| `GetClientDetailInfo` | 客户端请求 | `clientinfo clid=X` | `GetClientDetailInfo(clid uint16) (*ClientDetailInfo, error)` | 查询在线用户详情（结构化） |
+| `ListDBClients` | 客户端请求 | `clientdblist start=X duration=X` | `ListDBClients(start, duration int) ([]DBClient, error)` | 数据库客户端列表 |
+| `FindClientByName` | 客户端请求 | `clientdbfind pattern=X -uid` | `FindClientByName(nickname string) (uid string, dbid uint64, err error)` | 按昵称搜索数据库用户 |
+| `FindClientByDBID` | 客户端请求 | `clientdbfind -uid cldbid=X` | `FindClientByDBID(dbid uint64) (string, error)` | 按 DBID 查找 UID |
+
+### 客户端状态与操作
+
+> **通过指令构建的能力** — 底层封装 TS3 协议命令 `clientupdate`、`clientkick`。
+
+| 方法 | 触发形式 | 协议命令 | 用法 | 作用 |
+|------|----------|----------|------|------|
+| `UpdateSelf` | 客户端请求 | `clientupdate` | `UpdateSelf(properties map[string]string) error` | 更新自身属性（昵称、away、静音等） |
+| `KickClient` | 客户端请求 | `clientkick clid=X reasonid=X reasonmsg=X` | `KickClient(clid uint16, reasonID int, reasonMsg string) error` | 踢出用户（4=频道踢出, 5=服务器踢出） |
+
+### ClientInfo 结构
+
+| 字段 | 类型 | 描述 |
+|------|------|------|
+| `ID` | `uint16` | 客户端 ID |
+| `Nickname` | `string` | 昵称 |
+| `ChannelID` | `uint64` | 所在频道 ID |
+| `UID` | `string` | 唯一标识 |
+| `Type` | `int` | 客户端类型 |
+| `ServerGroups` | `[]string` | 所在服务器组 |
+
+### ClientDetailInfo 结构
+
+通过 `clientinfo clid=X` 获取的完整客户端信息。比 `ClientInfo` 多出 away 状态、平台、版本、IP 等字段。
+
+| 字段 | 类型 | 描述 |
+|------|------|------|
+| `ID` | `uint16` | 客户端 ID (clid) |
+| `Nickname` | `string` | 昵称 |
+| `UID` | `string` | 唯一标识 |
+| `ChannelID` | `uint64` | 所在频道 ID |
+| `Type` | `int` | 客户端类型 |
+| `ServerGroups` | `[]string` | 所在服务器组 |
+| `Away` | `bool` | 是否离开 |
+| `AwayMessage` | `string` | 离开消息 |
+| `InputMuted` | `bool` | 输入静音 |
+| `OutputMuted` | `bool` | 输出静音 |
+| `Platform` | `string` | 客户端平台 |
+| `Version` | `string` | 客户端版本 |
+| `IP` | `string` | 客户端 IP（需权限） |
+| `Created` | `int64` | 首次连接时间（unix 时间戳） |
+| `LastConnected` | `int64` | 最近连接时间 |
+| `TotalConnections` | `int` | 总连接次数 |
+| `Description` | `string` | 用户描述 |
+| `IconID` | `int64` | 用户图标 ID |
+
+### DBClient 结构
+
+| 字段 | 类型 | 描述 |
+|------|------|------|
+| `DBID` | `uint64` | 数据库 ID (cldbid) |
+| `UID` | `string` | 唯一标识 |
+| `Nickname` | `string` | 昵称 |
+| `Created` | `int64` | 首次连接时间 |
+| `LastConnected` | `int64` | 最近连接时间 |
+| `TotalConnections` | `int` | 总连接次数 |
+| `Description` | `string` | 用户描述 |
+
+### UpdateSelf 常用参数
+
+| 参数 | 值 | 说明 |
+|------|------|------|
+| `client_nickname` | 字符串 | 新昵称 |
+| `client_away` | `"1"` / `"0"` | 是否离开 |
+| `client_away_message` | 字符串 | 离开消息 |
+| `client_input_muted` | `"1"` / `"0"` | 输入静音 |
+| `client_output_muted` | `"1"` / `"0"` | 输出静音 |
+| `client_phonetic_nickname` | 字符串 | 语音昵称 |
+
+### Bridge 层 JSON 接口
+
+| 方法 | 返回 | 描述 |
+|------|------|------|
+| `GetClientsJSON()` | `string` | 在线客户端列表（含 isSelf 标志） |
+| `GetClientDetailInfoJSON(clid int)` | `string` | 单个客户端详细信息 |
+| `ListDBClientsJSON(start, duration int)` | `string` | 数据库客户端列表 |
+| `UpdateSelfJSON(propertiesJSON string)` | `string` | 更新自身（错误信息或空串） |
+| `KickClient(clid int, reasonID int, reasonMsg string)` | `string` | 踢出用户（错误信息或空串） |
+
+### ClientLeftViewEvent 结构
+
+| 字段 | 类型 | 描述 |
+|------|------|------|
+| `ClientID` | `uint16` | 离开的客户端 ID |
+| `ReasonID` | `int` | 原因：0=正常离开, 4=频道踢, 5=服务器踢 |
+| `ReasonMessage` | `string` | 原因描述 |
+| `IsSelf` | `bool` | 是否是自己 |
+
+### ClientMovedEvent 结构
+
+| 字段 | 类型 | 描述 |
+|------|------|------|
+| `ClientID` | `uint16` | 被移动的客户端 ID |
+| `TargetChannelID` | `uint64` | 目标频道 ID |
+| `ReasonID` | `int` | 原因 |
+| `InvokerID` | `uint16` | 操作者 ID |
+| `InvokerName` | `string` | 操作者昵称 |
+| `InvokerUID` | `string` | 操作者唯一标识 |
+
+---
+
+## 5. 频道命令
+
+### 基础频道列表
+
+| 方法 | 触发形式 | 用法 | 作用 | 描述 |
+|------|----------|------|------|------|
+| `ListChannels` | 客户端请求 | `ListChannels() ([]ChannelInfo, error)` | 频道列表（基础） | 返回服务器所有频道的基础信息（ID、父频道、名称）。对应协议 `channellist` |
+
+### 详细频道列表
+
+| 方法 | 触发形式 | 用法 | 作用 | 描述 |
+|------|----------|------|------|------|
+| `ListChannelsDetailed` | 客户端请求 | `ListChannelsDetailed() ([]ChannelInfoDetailed, error)` | 频道列表（详细） | 返回服务器所有频道的完整属性。对应协议 `channellist -topic -flags -voice -limits -icon` |
+
+`channellist` 命令支持的 flag 参数：
+
+| Flag | 返回字段 | 说明 |
+|------|---------|------|
+| `-topic` | `channel_topic` | 频道主题描述 |
+| `-flags` | `channel_flag_permanent`, `channel_flag_semi_permanent`, `channel_flag_default`, `channel_flag_password`, `channel_flag_maxclients_unlimited`, `channel_flag_maxfamilyclients_unlimited`, `channel_order` | 频道标志位（永久、半永久、默认、密码、人数限制、排序） |
+| `-voice` | `channel_codec`, `channel_codec_quality`, `channel_needed_talk_power` | 语音编解码相关 |
+| `-limits` | `channel_maxclients`, `channel_maxfamilyclients` | 频道人数限制 |
+| `-icon` | `channel_icon_id` | 频道自定义图标 ID |
+
+### 频道查询
+
+> **通过指令构建的能力** — 底层封装 TS3 协议命令 `channelinfo`、`channelfind`。
+
+| 方法 | 触发形式 | 协议命令 | 用法 | 作用 |
+|------|----------|----------|------|------|
+| `GetChannelInfo` | 客户端请求 | `channelinfo cid=X` | `GetChannelInfo(channelID uint64) (*ChannelDetailInfo, error)` | 单频道完整详情（含 description） |
+| `FindChannels` | 客户端请求 | `channelfind pattern=X` | `FindChannels(pattern string) ([]ChannelInfo, error)` | 按名称搜索频道 |
+
+### 频道管理
+
+> **通过指令构建的能力** — 底层封装 TS3 协议命令 `channelcreate`、`channeledit`、`channeldelete`、`channelmove`。
+
+| 方法 | 触发形式 | 协议命令 | 用法 | 作用 |
+|------|----------|----------|------|------|
+| `CreateChannel` | 客户端请求 | `channelcreate channel_name=X ...` | `CreateChannel(name string, options map[string]string) (uint64, error)` | 创建频道，返回新频道 ID |
+| `EditChannel` | 客户端请求 | `channeledit cid=X ...` | `EditChannel(channelID uint64, properties map[string]string) error` | 编辑频道属性 |
+| `DeleteChannel` | 客户端请求 | `channeldelete cid=X force=X` | `DeleteChannel(channelID uint64, force bool) error` | 删除频道，force=true 强制删除 |
+| `MoveChannel` | 客户端请求 | `channelmove cid=X cpid=X order=X` | `MoveChannel(channelID, parentID, order uint64) error` | 移动频道到新父频道或调整排序 |
+
+#### CreateChannel 常用可选参数
+
+| 参数 | 值 | 说明 |
+|------|------|------|
+| `channel_topic` | 字符串 | 频道主题 |
+| `channel_flag_permanent` | `"1"` / `"0"` | 永久频道 |
+| `channel_flag_semi_permanent` | `"1"` / `"0"` | 半永久频道 |
+| `channel_flag_default` | `"1"` / `"0"` | 默认频道 |
+| `channel_password` | 字符串 | 频道密码 |
+| `cpid` | 字符串（父频道ID） | 父频道 |
+| `channel_maxclients` | 字符串 | 最大人数 |
+| `channel_codec` | 字符串 | 编解码器（0-5） |
+
+### ChannelInfo 结构（基础）
+
+| 字段 | 类型 | 描述 |
+|------|------|------|
+| `ID` | `uint64` | 频道 ID |
+| `ParentID` | `uint64` | 父频道 ID（0 = 顶层频道） |
+| `Name` | `string` | 频道名称（已 Unescape） |
+| `Description` | `string` | 频道描述（`ListChannels` 返回为空） |
+
+### ChannelInfoDetailed 结构（详细列表项）
+
+来自 `channellist -topic -flags -voice -limits -icon` 的批量列表项。
+
+| 字段 | 类型 | 描述 |
+|------|------|------|
+| **基础** | | |
+| `ID` | `uint64` | 频道 ID |
+| `ParentID` | `uint64` | 父频道 ID（0 = 顶层频道） |
+| `Order` | `uint64` | 排序顺序（前一个频道 ID，0 = 最顶部） |
+| `Name` | `string` | 频道名称 |
+| `Topic` | `string` | 频道主题（来自 `-topic`） |
+| **语音（`-voice`）** | | |
+| `Codec` | `int` | 0=Speex Narrowband, 1=Speex Wideband, 2=Speex UltraWideband, 3=CELT Mono, **4=Opus Voice**, **5=Opus Music** |
+| `CodecQuality` | `int` | 编解码质量（0-10） |
+| `NeededTalkPower` | `int` | 发言所需权限等级 |
+| **限制（`-limits`）** | | |
+| `MaxClients` | `int` | 最大客户端数 |
+| `MaxFamilyClients` | `int` | 最大族客户端数 |
+| `IsMaxClientsUnlimited` | `bool` | 是否无限人数 |
+| `IsMaxFamilyClientsUnlimited` | `bool` | 是否无限族人数 |
+| **标志（`-flags`）** | | |
+| `IsPermanent` | `bool` | 永久频道 |
+| `IsSemiPermanent` | `bool` | 半永久频道 |
+| `IsDefault` | `bool` | 默认频道 |
+| `IsPassword` | `bool` | 是否设置密码 |
+| `IsOrdered` | `bool` | 是否手动排序 |
+| `NeededModifyPower` | `int` | 修改频道所需权限 |
+| **图标（`-icon`）** | | |
+| `IconID` | `int64` | 频道图标 ID |
+
+### ChannelDetailInfo 结构（单频道详情）
+
+来自 `channelinfo cid=X` 的完整频道信息，比 `ChannelInfoDetailed` 多出 `Description`（完整描述）和 `BannerGfxURL` 等字段。
+
+| 字段 | 类型 | 描述 |
+|------|------|------|
+| `ID` | `uint64` | 频道 ID |
+| `ParentID` | `uint64` | 父频道 ID |
+| `Name` | `string` | 频道名称 |
+| `Topic` | `string` | 频道主题 |
+| `Description` | `string` | 完整描述 |
+| `Codec` | `int` | 编解码器 |
+| `CodecQuality` | `int` | 编解码质量 |
+| `MaxClients` | `int` | 最大人数 |
+| `MaxFamilyClients` | `int` | 最大族人数 |
+| `NeededTalkPower` | `int` | 发言权限 |
+| `IconID` | `int64` | 图标 ID |
+| `IsPermanent` | `bool` | 永久 |
+| `IsSemiPermanent` | `bool` | 半永久 |
+| `IsDefault` | `bool` | 默认 |
+| `IsPassword` | `bool` | 有密码 |
+| `Order` | `uint64` | 排序 |
+| `BannerGfxURL` | `string` | Banner 图片 URL |
+
+### Bridge 层 JSON 接口
+
+| 方法 | 返回 | 描述 |
+|------|------|------|
+| `GetChannelsJSON()` | `string` | 基础频道列表（向后兼容） |
+| `GetChannelsDetailedJSON()` | `string` | 详细频道列表（含 flags/voice/limits/icon） |
+| `GetChannelDetailInfoJSON(channelIDStr string)` | `string` | 单频道完整详情 |
+| `CreateChannelJSON(name, propertiesJSON string)` | `string` | 创建频道，返回新频道 ID（空串=失败） |
+| `EditChannelJSON(channelIDStr, propertiesJSON string)` | `string` | 编辑频道（错误信息或空串） |
+| `DeleteChannel(channelIDStr string, force bool)` | `string` | 删除频道（错误信息或空串） |
+
+`GetChannelsDetailedJSON()` 返回的 JSON 示例：
+
+```json
+[
+  {
+    "id": "1",
+    "name": "Lobby",
+    "parentId": "0",
+    "topic": "欢迎来到大厅",
+    "order": "0",
+    "codec": 4,
+    "codecQuality": 7,
+    "neededTalkPower": 0,
+    "maxClients": -1,
+    "maxFamilyClients": -1,
+    "isMaxClientsUnlimited": true,
+    "isMaxFamilyClientsUnlimited": true,
+    "isPermanent": true,
+    "isSemiPermanent": false,
+    "isDefault": true,
+    "isPassword": false,
+    "isOrdered": false,
+    "iconId": "0",
+    "neededModifyPower": 75
+  }
+]
+```
+
+### 典型用法
+
+```go
+// 获取详细频道列表
+channels, err := client.ListChannelsDetailed()
+if err != nil {
+    return err
+}
+
+for _, ch := range channels {
+    // 显示频道名和状态图标
+    icons := ""
+    if ch.IsPassword { icons += "🔒" }
+    if ch.IsPermanent  { icons += "📌" }
+    if !ch.IsMaxClientsUnlimited {
+        icons += fmt.Sprintf(" 👥%d", ch.MaxClients)
+    }
+    log.Printf("%s %s %s", icons, ch.Name, ch.Topic)
+
+    // 根据编解码器选择解码策略
+    switch ch.Codec {
+    case 4: // Opus Voice — 20ms 帧，适合语音
+    case 5: // Opus Music — 更高采样率，适合音乐
+    }
+}
+```
+
+---
+
+## 6. 语音命令
+
+### 发送语音
+
+| 方法 | 触发形式 | 用法 | 作用 | 描述 |
+|------|----------|------|------|------|
+| `SendVoice` | 客户端请求 | `SendVoice(data []byte, codec byte) error` | 发送语音帧 | 发送原始 Opus 帧。codec: 4=Opus 语音, 5=Opus 音乐。通过 UDP 传输 |
+
+### 接收语音
+
+接收语音通过事件回调实现，无需主动调用。
+
+| 方法 | 触发形式 | 用法 | 作用 | 描述 |
+|------|----------|------|------|------|
+| `OnVoiceData` | 服务端推送 | `OnVoiceData(fn func(VoiceDataEvent))` | 注册语音接收回调 | 当同频道其他客户端发送语音时，SDK 解密后触发回调 |
+
+**Codec 值说明**：
+
+| 值 | 类型 | 适用场景 |
+|----|------|---------|
+| `4` | Opus Voice | 语音通话（默认） |
+| `5` | Opus Music | 音乐/高保真音频 |
+
+**典型用法**：
+
+```go
+client.OnVoiceData(func(evt teamspeak.VoiceDataEvent) {
+    // evt.ClientID — 发送者客户端 ID
+    // evt.Data     — Opus 编码帧，可直接送入解码器
+    // evt.Codec    — 4=Opus Voice, 5=Opus Music
+    decoded := opusDecoder.Decode(evt.Data, pcmBuffer)
+    audioTrack.Write(pcmBuffer[:decoded])
+})
+```
+
+**注意事项**：
+
+- `OnVoiceData` 回调在事件循环 goroutine 中串行执行，**不要在回调中做耗时操作**（如 Opus 解码），应将数据推入 channel 由独立协程处理
+- SDK 不内置 Opus 解码器，需要在应用层（Kotlin/Go）集成 `opus.Decode()`
+- 语音帧以 20ms 为单位发送，采样率通常为 48kHz
+
+---
+
+## 7. 服务器查询
+
+> **通过指令构建的能力** — 底层封装 TS3 协议命令 `serverinfo`。
+
+### 服务器信息
+
+| 方法 | 触发形式 | 协议命令 | 用法 | 作用 |
+|------|----------|----------|------|------|
+| `GetServerInfo` | 客户端请求 | `serverinfo` | `GetServerInfo() (*ServerInfo, error)` | 获取服务器完整信息 |
+
+### ServerInfo 结构
+
+| 字段 | 类型 | 描述 |
+|------|------|------|
+| `Name` | `string` | 服务器名称 |
+| `WelcomeMessage` | `string` | 欢迎消息 |
+| `MaxClients` | `int` | 最大客户端数 |
+| `ClientsOnline` | `int` | 在线客户端数 |
+| `ChannelsOnline` | `int` | 在线频道数 |
+| `Uptime` | `int64` | 服务器运行时长（秒） |
+| `Version` | `string` | 服务器版本 |
+| `Platform` | `string` | 服务器平台 |
+| `Created` | `int64` | 创建时间（unix 时间戳） |
+| `IconID` | `int64` | 服务器图标 ID |
+| `DefaultServerGroup` | `int` | 默认服务器组 ID |
+| `DefaultChannelGroup` | `int` | 默认频道组 ID |
+
+### Bridge 层 JSON 接口
+
+| 方法 | 返回 | 描述 |
+|------|------|------|
+| `GetServerInfoJSON()` | `string` | 服务器信息（JSON 对象，空 `"{}"` 表示未连接或出错） |
+
+---
+
+## 8. Ban 管理
+
+> **通过指令构建的能力** — 底层封装 TS3 协议命令 `banlist`、`banadd`、`bandel`、`bandelall`。
+
+### Ban 操作
+
+| 方法 | 触发形式 | 协议命令 | 用法 | 作用 |
+|------|----------|----------|------|------|
+| `ListBans` | 客户端请求 | `banlist` | `ListBans() ([]BanEntry, error)` | 获取所有封禁记录 |
+| `AddBan` | 客户端请求 | `banadd ip=X name=X uid=X time=X banreason=X` | `AddBan(ip, name, uid string, timeSeconds int, reason string) error` | 添加封禁（ip/name/uid 至少指定一个，time=0 为永久） |
+| `DeleteBan` | 客户端请求 | `bandel banid=X` | `DeleteBan(banID int64) error` | 解除指定封禁 |
+| `DeleteAllBans` | 客户端请求 | `bandelall` | `DeleteAllBans() error` | 清除所有封禁 |
+
+### BanEntry 结构
+
+| 字段 | 类型 | 描述 |
+|------|------|------|
+| `BanID` | `int64` | 封禁 ID |
+| `IP` | `string` | IP（可能为空或部分掩码） |
+| `Name` | `string` | 名称模式 |
+| `UID` | `string` | 唯一标识 |
+| `Created` | `int64` | 封禁时间（unix 时间戳） |
+| `InvokerName` | `string` | 操作者昵称 |
+| `InvokerUID` | `string` | 操作者 UID |
+| `Reason` | `string` | 封禁原因 |
+| `Enforcement` | `bool` | 是否立即执行 |
+
+### Bridge 层 JSON 接口
+
+| 方法 | 返回 | 描述 |
+|------|------|------|
+| `ListBansJSON()` | `string` | Ban 列表 |
+| `AddBan(ip, name, uid string, timeSeconds int, reason string)` | `string` | 添加封禁（错误信息或空串） |
+| `DeleteBan(banIDStr string)` | `string` | 删除封禁（错误信息或空串） |
+
+---
+
+## 9. Token 管理
+
+> **通过指令构建的能力** — 底层封装 TS3 协议命令 `tokenlist`、`tokenuse`。
+
+Token（权限密钥）用于让用户自动获得服务器组/频道组权限。
+
+### Token 操作
+
+| 方法 | 触发形式 | 协议命令 | 用法 | 作用 |
+|------|----------|----------|------|------|
+| `ListTokens` | 客户端请求 | `tokenlist` | `ListTokens() ([]TokenEntry, error)` | 获取所有权限密钥 |
+| `UseToken` | 客户端请求 | `tokenuse token=X` | `UseToken(token string) error` | 激活权限密钥 |
+
+### TokenEntry 结构
+
+| 字段 | 类型 | 描述 |
+|------|------|------|
+| `Token` | `string` | 权限密钥字符串 |
+| `TokenType` | `int` | 类型：0=服务器组, 1=频道组 |
+| `TokenID1` | `int64` | 组 ID |
+| `TokenID2` | `int64` | 频道 ID（仅 token_type=1 时有效） |
+| `Created` | `int64` | 创建时间（unix 时间戳） |
+| `Description` | `string` | 描述 |
+
+### Bridge 层 JSON 接口
+
+| 方法 | 返回 | 描述 |
+|------|------|------|
+| `ListTokensJSON()` | `string` | Token 列表 |
+| `UseToken(token string)` | `string` | 使用 Token（错误信息或空串） |
+
+---
+
+## 10. 投诉管理
+
+> **通过指令构建的能力** — 底层封装 TS3 协议命令 `complainlist`、`complainadd`、`complaindel`。
+
+### 投诉操作
+
+| 方法 | 触发形式 | 协议命令 | 用法 | 作用 |
+|------|----------|----------|------|------|
+| `ListComplaints` | 客户端请求 | `complainlist [tcldbid=X]` | `ListComplaints(targetDBID uint64) ([]ComplaintEntry, error)` | 查询投诉（targetDBID=0 查全部） |
+| `AddComplaint` | 客户端请求 | `complainadd tcldbid=X message=X` | `AddComplaint(targetDBID uint64, message string) error` | 提交投诉 |
+| `DeleteComplaint` | 客户端请求 | `complaindel tcldbid=X fcldbid=X` | `DeleteComplaint(targetDBID, fromDBID uint64) error` | 删除投诉 |
+
+### ComplaintEntry 结构
+
+| 字段 | 类型 | 描述 |
+|------|------|------|
+| `FromDBID` | `uint64` | 投诉者 DBID |
+| `ToDBID` | `uint64` | 被投诉者 DBID |
+| `Message` | `string` | 投诉内容 |
+| `Timestamp` | `int64` | 投诉时间（unix 时间戳） |
+
+### Bridge 层 JSON 接口
+
+| 方法 | 返回 | 描述 |
+|------|------|------|
+| `ListComplaintsJSON(targetDBIDStr string)` | `string` | 投诉列表（`"0"` 表示全部） |
+| `AddComplaint(targetDBIDStr, message string)` | `string` | 提交投诉（错误信息或空串） |
+
+---
+
+## 11. 文件传输
+
+| 方法 | 触发形式 | 用法 | 作用 | 描述 |
+|------|----------|------|------|------|
+| `FileTransferInitUpload` | 客户端请求 | `FileTransferInitUpload(channelID uint64, path string, password string, size uint64, overwrite bool) (*FileUploadInfo, error)` | 初始化上传 | 请求上传文件到频道文件目录。对应协议 `ftinitupload` |
+| `FileTransferInitDownload` | 客户端请求 | `FileTransferInitDownload(channelID uint64, path string, password string) (*FileDownloadInfo, error)` | 初始化下载 | 请求下载频道文件。对应协议 `ftinitdownload` |
+| `FileTransferDeleteFile` | 客户端请求 | `FileTransferDeleteFile(channelID uint64, paths []string) error` | 删除文件 | 删除频道中的文件。对应协议 `ftdeletefile` |
+
+### 文件列表查询
+
+> **通过指令构建的能力** — 底层封装 TS3 协议命令 `ftgetfilelist`。
+
+| 方法 | 触发形式 | 协议命令 | 用法 | 作用 |
+|------|----------|----------|------|------|
+| `ListFiles` | 客户端请求 | `ftgetfilelist cid=X path=X` | `ListFiles(channelID uint64, path string) ([]FileEntry, error)` | 列出频道目录下的文件和子目录（path 为虚拟路径，根目录为 `/`） |
+
+### FileEntry 结构
+
+| 字段 | 类型 | 描述 |
+|------|------|------|
+| `Name` | `string` | 文件/目录名 |
+| `Size` | `uint64` | 文件大小（字节，目录为 0） |
+| `DateTime` | `int64` | 修改时间（unix 时间戳） |
+| `IsFile` | `bool` | 是否为文件（false = 目录） |
+
+### Bridge 层 JSON 接口
+
+| 方法 | 返回 | 描述 |
+|------|------|------|
+| `ListFilesJSON(channelIDStr, path string)` | `string` | 频道文件列表 |
+
+### 辅助函数
+
+| 函数 | 触发形式 | 用法 | 作用 | 描述 |
+|------|----------|------|------|------|
+| `DialFileTransfer` | 客户端请求 | `DialFileTransfer(host string, port uint16, key string) (net.Conn, error)` | 建立文件传输连接 | 建立到文件传输端口的 TCP 连接 |
+| `UploadFileData` | 客户端请求 | `UploadFileData(host string, info *FileUploadInfo, data io.Reader) error` | 上传数据 | 通过已初始化的连接上传文件数据 |
+| `DownloadFileData` | 客户端请求 | `DownloadFileData(host string, info *FileDownloadInfo, dest io.Writer) error` | 下载数据 | 通过已初始化的连接下载文件数据 |
+
+---
+
+## 12. 中间件
+
+| 类型 | 触发形式 | 定义 | 作用 | 描述 |
+|------|----------|------|------|------|
+| `CommandMiddleware` | 本地调用 | `func(next func(string) error) func(string) error` | 命令中间件 | 拦截/修改即将发送的命令字符串 |
+| `EventMiddleware` | 本地调用 | `func(next func(any)) func(any)` | 事件中间件 | 拦截/修改即将分发的事件 |
+
+---
+
+## 13. 解析器接口
+
+| 类型 | 触发形式 | 定义 | 作用 | 描述 |
+|------|----------|------|------|------|
+| `AddrResolver` | 本地调用 | `Resolve(ctx context.Context, addr string) ([]discovery.ResolvedAddr, error)` | 地址解析器 | 自定义 DNS/TSDNS 服务器地址解析 |
+
+---
+
+## 14. 协议转义
+
+| 函数 | 触发形式 | 用法 | 作用 | 描述 |
+|------|----------|------|------|------|
+| `commands.Escape` | 本地调用 | `commands.Escape(s string) string` | 转义 | 将字符串转义为 TS3 协议安全格式 |
+| `commands.Unescape` | 本地调用 | `commands.Unescape(s string) string` | 反转义 | 将 TS3 协议转义字符串还原 |
+| `commands.BuildCommand` | 本地调用 | `commands.BuildCommand(cmd string, params map[string]string) string` | 构建命令 | 从命令名和参数 map 构建协议命令字符串 |
+| `commands.BuildCommandOrdered` | 本地调用 | `commands.BuildCommandOrdered(cmd string, params [][2]string) string` | 构建命令（有序） | 同上，但保持参数顺序 |
+
+---
+
+## 15. 服务器通知（内部处理）
+
+以下通知由 SDK 内部解析并转换为事件，开发者通过 `On*` 方法注册处理器即可，无需直接处理。
+
+| 通知 ID | 触发形式 | 事件类型 | 描述                      |
+|---------|----------|----------|-------------------------|
+| `notifycliententerview` | 服务端推送 | `ClientInfo` | 客户端进入服务器(事件数据结构频道id未生效) |
+| `notifyclientleftview` | 服务端推送 | `ClientLeftViewEvent` | 客户端离开视野（含踢出）            |
+| `notifyclientmoved` | 服务端推送 | `ClientMovedEvent` | 客户端频道移动                 |
+| `notifytextmessage` | 服务端推送 | `TextMessage` | 收到文本消息                  |
+| `notifyclientpoke` | 服务端推送 | `PokeEvent` | 收到 Poke                 |
+| `notifyclientneededpermissions` | 服务端推送 | — | 仅 Debug 日志，无事件          |
+| `notifystartupload` | 服务端推送 | `FileUploadInfo` | 文件上传开始                  |
+| `notifystartdownload` | 服务端推送 | `FileDownloadInfo` | 文件下载开始                  |
+| `notifystatusfiletransfer` | 服务端推送 | `FileTransferStatusInfo` | 文件传输状态变更                |
+
+---
+
+## 16. 未实现的 TS3 协议命令
+
+以下命令在 teamspeak-go 中尚未封装，如需支持可在 `api.go` 中按现有模式扩展（通过 `ExecCommand` / `ExecCommandWithResponse` 发送协议命令）。
+
+### 用户管理
+
+| 命令 | 触发形式 | 用法 | 作用 | 描述 |
+|------|----------|------|------|------|
+| `clientdbedit` | 客户端请求 | `clientdbedit cldbid=X ...` | 编辑数据库用户 | 修改数据库用户属性（描述、昵称等） |
+| `clientsetservergroup` | 客户端请求 | `clientsetservergroup cldbid=X sgid=X` | 设置服务器组 | 将用户添加到指定服务器组 |
+| `clientgetdbidfromuid` | 客户端请求 | `clientgetdbidfromuid cluid=X` | UID→DBID | 从唯一标识获取数据库 ID |
+| `clientgetnamefromuid` | 客户端请求 | `clientgetnamefromuid cluid=X` | UID→昵称 | 从唯一标识获取昵称 |
+| `clientgetnamefromdbid` | 客户端请求 | `clientgetnamefromdbid cldbid=X` | DBID→昵称 | 从数据库 ID 获取昵称 |
+| `clientgetids` | 客户端请求 | `clientgetids cluid=X` | UID→clid | 从唯一标识获取在线客户端 ID |
+
+### 服务器组管理
+
+| 命令 | 触发形式 | 用法 | 作用 | 描述 |
+|------|----------|------|------|------|
+| `servergroupadd` | 客户端请求 | `servergroupadd name=X` | 创建服务器组 | 创建新的服务器组 |
+| `servergroupdel` | 客户端请求 | `servergroupdel sgid=X force=1` | 删除服务器组 | 删除指定服务器组 |
+| `servergroupaddclient` | 客户端请求 | `servergroupaddclient sgid=X cldbid=X` | 添加用户到组 | 将数据库用户添加到服务器组 |
+| `servergroupdelclient` | 客户端请求 | `servergroupdelclient sgid=X cldbid=X` | 从组移除用户 | 将用户从服务器组移除 |
+| `servergrouplist` | 客户端请求 | `servergrouplist` | 服务器组列表 | 获取所有服务器组 |
+
+### 服务器管理
+
+| 命令 | 触发形式 | 用法 | 作用 | 描述 |
+|------|----------|------|------|------|
+| `serveredit` | 客户端请求 | `serveredit virtualserver_name=X ...` | 编辑服务器 | 修改服务器属性 |
+| `serverprocessstop` | 客户端请求 | `serverprocessstop reasonmsg=X` | 关闭服务器 | 停止服务器进程 |
+
+### 权限查询
+
+| 命令 | 触发形式 | 用法 | 作用 | 描述 |
+|------|----------|------|------|------|
+| `permoverview` | 客户端请求 | `permoverview cid=X cldbid=X` | 权限概览 | 获取用户在指定频道的权限概览 |
+| `permget` | 客户端请求 | `permget permid=X` | 获取权限 | 获取指定权限的当前值 |
+| `permfind` | 客户端请求 | `permfind permid=X` | 查找权限 | 查找拥有指定权限的所有对象 |
+
+### 其他
+
+| 命令 | 触发形式 | 用法 | 作用 | 描述 |
+|------|----------|------|------|------|
+| `sendpluginmessage` | 客户端请求 | `sendpluginmessage target=X msg=X` | 插件消息 | 向指定目标发送插件消息 |
+| `tokenadd` | 客户端请求 | `tokenadd tokentype=X ...` | 创建 Token | 创建新的权限 Token |
+| `tokendelete` | 客户端请求 | `tokendelete token=X` | 删除 Token | 删除指定 Token |
+| `banclient` | 客户端请求 | `banclient clid=X time=X banreason=X` | 踢+Ban | 踢出并封禁指定在线客户端 |
+
+---
+
+## 17. Bridge 层 Kotlin 友好 API（kotlin_api.go）
+
+`go/teamspeak/kotlin_api.go` 是对 `bridge.go` 的补充封装，暴露 SDK 中已有但 bridge.go 未导出的能力，并提供 Identity 管理接口。
+
+所有方法遵循 bridge.go 的 gomobile 导出约定：
+- 返回 `string`：空字符串=成功，非空=错误信息
+- 返回 JSON `string`：查询结果以 JSON 编码
+
+### 17.1 Identity 管理
+
+| 方法 | 触发形式 | 用法 | 作用 | 描述 |
+|------|----------|------|------|------|
+| `GenerateIdentity` | 本地调用 | `GenerateIdentity(securityLevel int) string` | 生成身份 | 生成加密身份并序列化为字符串。`securityLevel` 推荐值 8。Kotlin 侧应持久化返回值，后续通过 `ConnectWithIdentity` 复用 |
+| `ConnectWithIdentity` | 客户端请求 | `ConnectWithIdentity(identityStr, host, nickname, password, defaultChannel, defaultChannelPassword string, cb EventCallback) string` | 用已有身份连接 | 使用已持久化的 identity 字符串连接。行为与 `Connect` 相同 |
+
+**Identity 序列化格式**: `"base64EncodedPrivateKey:offset"`（由 SDK 的 `Identity.String()` 生成）
+
+**典型用法**：
+
+```kotlin
+// 首次使用：生成并持久化
+val identity = GenerateIdentity(8)
+preferences.edit().putString("ts_identity", identity).apply()
+
+// 后续使用：从持久化读取
+val identity = preferences.getString("ts_identity", "") ?: ""
+val error = client.connectWithIdentity(identity, host, nickname, password, "", "", callback)
+```
+
+### 17.2 查询能力（补充）
+
+以下方法补充 bridge.go 中未暴露的 SDK 查询能力。
+
+| 方法 | 返回 | 描述 |
+|------|------|------|
+| `FindChannelsJSON(pattern string) string` | JSON 数组 | 按名称搜索频道。返回 `[{"id":"1","name":"匹配的频道"}]` |
+| `FindClientByNameJSON(nickname string) string` | JSON 对象 | 按昵称搜索数据库客户端。返回 `{"uid":"xxx","dbid":"123"}` |
+| `FindClientByDBIDJSON(dbidStr string) string` | JSON 对象 | 按 DBID 查找客户端 UID。返回 `{"uid":"xxx"}` |
+
+### 17.3 操作能力（补充）
+
+以下方法补充 bridge.go 中未暴露的 SDK 操作能力。
+
+| 方法 | 返回 | 描述 |
+|------|------|------|
+| `MoveClient(clientID int, channelIDStr, password string) string` | 错误信息 | 将指定客户端移动到目标频道 |
+| `MoveChannel(channelIDStr, parentIDStr, orderStr string) string` | 错误信息 | 移动频道到新父频道或调整排序 |
+| `DeleteAllBans() string` | 错误信息 | 清除所有封禁记录 |
+| `DeleteComplaint(targetDBIDStr, fromDBIDStr string) string` | 错误信息 | 删除指定投诉 |
+
+### 17.4 文件传输（初始化）
+
+文件传输遵循三阶段流程：初始化 → TCP 连接 → 数据传输。以下方法封装初始化阶段。
+
+| 方法 | 返回 | 描述 |
+|------|------|------|
+| `FileTransferInitUploadJSON(channelIDStr, path string, size int64, overwrite bool) string` | JSON 对象 | 初始化上传。返回 `{"port":0,"key":"...","clientFileTransferID":0,"serverFileTransferID":0,"seekPosition":0}` |
+| `FileTransferInitDownloadJSON(channelIDStr, path string) string` | JSON 对象 | 初始化下载。返回 `{"port":0,"key":"...","size":0,"clientFileTransferID":0,"serverFileTransferID":0}` |
+| `DeleteFile(channelIDStr, pathsJSON string) string` | 错误信息 | 删除频道文件。`pathsJSON` 为 JSON 数组如 `["/file1.txt","/file2.txt"]` |
+
+**注意**：TCP 连接的 host 为当前服务器地址，port 从初始化返回的 JSON 中获取。完整的文件传输流程（TCP 连接 + 数据传输）需要额外封装。
+
+### 17.5 批量查询（首次同步优化）
+
+| 方法 | 返回 | 描述 |
+|------|------|------|
+| `GetInitialSyncJSON() string` | JSON 对象 | 一次性返回首次同步所需的全部数据，减少 JNI 调用次数 |
+
+返回格式：
+
+```json
+{
+  "channels": [
+    {"id":"1","name":"Lobby","parentId":"0","topic":"","order":"0","codec":4,"codecQuality":7,...}
+  ],
+  "clients": [
+    {"id":1,"nickname":"User","uid":"xxx","channelId":"1","serverGroups":[],"isSelf":true}
+  ],
+  "selfId": 1,
+  "selfChannelId": "1",
+  "server": {
+    "name":"My Server","welcomeMessage":"","maxClients":100,"clientsOnline":5,"channelsOnline":3,...
+  }
+}
+```
+
+任一子查询失败时对应字段为 null/空数组，不影响其他字段。
+
+### 17.6 Bridge 层方法完整索引
+
+#### bridge.go 已有方法
+
+| 分类 | 方法 | 返回 |
+|------|------|------|
+| 连接 | `Connect(host, nickname, password, defaultChannel, defaultChannelPassword, cb)` | 错误信息 |
+| 连接 | `Disconnect()` | — |
+| 连接 | `IsConnected()` | bool |
+| 连接 | `GetClientID()` | int |
+| 连接 | `GetChannelID()` | string |
+| 查询 | `GetChannelsJSON()` | JSON 数组 |
+| 查询 | `GetChannelsDetailedJSON()` | JSON 数组 |
+| 查询 | `GetClientsJSON()` | JSON 数组 |
+| 查询 | `GetServerInfoJSON()` | JSON 对象 |
+| 查询 | `GetChannelDetailInfoJSON(channelIDStr)` | JSON 对象 |
+| 查询 | `GetClientDetailInfoJSON(clid)` | JSON 对象 |
+| 查询 | `ListDBClientsJSON(start, duration)` | JSON 数组 |
+| 查询 | `ListBansJSON()` | JSON 数组 |
+| 查询 | `ListTokensJSON()` | JSON 数组 |
+| 查询 | `ListFilesJSON(channelIDStr, path)` | JSON 数组 |
+| 查询 | `ListComplaintsJSON(targetDBIDStr)` | JSON 数组 |
+| 操作 | `SendChannelMessage(channelIDStr, message)` | 错误信息 |
+| 操作 | `SendTextMessage(targetMode, targetIDStr, message)` | 错误信息 |
+| 操作 | `MoveToChannel(channelIDStr, password)` | 错误信息 |
+| 操作 | `Poke(clidStr, message)` | 错误信息 |
+| 操作 | `SendVoice(data, codec)` | 错误信息 |
+| 操作 | `CreateChannelJSON(name, propertiesJSON)` | 新频道 ID |
+| 操作 | `EditChannelJSON(channelIDStr, propertiesJSON)` | 错误信息 |
+| 操作 | `DeleteChannel(channelIDStr, force)` | 错误信息 |
+| 操作 | `UpdateSelfJSON(propertiesJSON)` | 错误信息 |
+| 操作 | `KickClient(clid, reasonID, reasonMsg)` | 错误信息 |
+| 操作 | `AddBan(ip, name, uid, timeSeconds, reason)` | 错误信息 |
+| 操作 | `DeleteBan(banIDStr)` | 错误信息 |
+| 操作 | `UseToken(token)` | 错误信息 |
+| 操作 | `AddComplaint(targetDBIDStr, message)` | 错误信息 |
+
+#### kotlin_api.go 新增方法
+
+| 分类 | 方法 | 返回 |
+|------|------|------|
+| Identity | `GenerateIdentity(securityLevel)` | 序列化的 identity 字符串 |
+| Identity | `ConnectWithIdentity(identityStr, host, nickname, password, defaultChannel, defaultChannelPassword, cb)` | 错误信息 |
+| 查询 | `FindChannelsJSON(pattern)` | JSON 数组 |
+| 查询 | `FindClientByNameJSON(nickname)` | JSON 对象 |
+| 查询 | `FindClientByDBIDJSON(dbidStr)` | JSON 对象 |
+| 操作 | `MoveClient(clientID, channelIDStr, password)` | 错误信息 |
+| 操作 | `MoveChannel(channelIDStr, parentIDStr, orderStr)` | 错误信息 |
+| 操作 | `DeleteAllBans()` | 错误信息 |
+| 操作 | `DeleteComplaint(targetDBIDStr, fromDBIDStr)` | 错误信息 |
+| 文件 | `FileTransferInitUploadJSON(channelIDStr, path, size, overwrite)` | JSON 对象 |
+| 文件 | `FileTransferInitDownloadJSON(channelIDStr, path)` | JSON 对象 |
+| 文件 | `DeleteFile(channelIDStr, pathsJSON)` | 错误信息 |
+| 批量 | `GetInitialSyncJSON()` | JSON 对象 |