ts-mobile-go/docs/sdk文档-go.md

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 示例：

[
  {
    "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
  }
]

典型用法

// 获取详细频道列表
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	音乐/高保真音频

典型用法：

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() 生成）

典型用法：

// 首次使用：生成并持久化
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 调用次数

返回格式：

{
  "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 对象