企业官网建设流程全解析

• 网络安全

这篇技术指南以官方 CHANGELOG 为骨架，系统梳理 Slack 官方 Go SDK（slack-go/slack）从 v0.18.0 到 v0.24.0 的版本演进：包括 Agent 界面（agent-UI）Block Kit 新块、流式消息 chunks API、OAuth PKCE、Socket Mode 可靠性修复，以及多组影响面较大的破坏性变更。读完本文，你将掌握各版本的新能力清单、精确的迁移改写示例，并了解该库在 Sliver 仓库中作为通知依赖的实际落地方式。

仓库中的 slack-go/slack：版本与用途

在 Sliver 仓库中，slack-go/slack 以 vendor 依赖形式固定为 v0.24.0（见 go.mod，标注为 indirect），源码位于 vendor/github.com/slack-go/slack/，其中可以看到本文涉及的block_card.go、block_carousel.go、block_alert.go、block_data_table.go、chat_stream_chunks.go、retry.go等模块文件与 CHANGELOG 一一对应。

该库在 Sliver 中并不直接面向终端用户，而是作为服务端通知链路的底层组件：Sliver 通过nikoksr/notify的 Slack 服务封装调用 slack-go/slack，将服务器事件推送到 Slack 频道。相关实现证据：

• server/configs/notifications.go 定义了SlackConfig，包含内嵌的NotificationServiceConfig（如enabled、events）、api_token与channels字段；
• server/notifications/builder.go 中的buildSlack()在api_token为空或channels为空时报错，随后调用notifyslack.New(cfg.APIToken)并AddReceivers(channels...)；
• server/notifications/builder.go 在services.Slack != nil && svc.Enabled时构建 notifier，并将slack注册为事件通知入口。

这意味着 CHANGELOG 中记录的 API 变化会直接影响任何依赖该库发消息、收事件或做 OAuth 集成的 Go 项目——下面逐版本拆解。

v0.24.0 与 v0.23.x：Agent 界面新块与安全修复

v0.24.0：DataTableBlock

v0.24.0 为 Block Kit 新增了data_table块，对应源码文件 block_data_table.go：

• 构造器NewDataTableBlock，配合AddRow逐行追加数据；
• 提供 raw-text / raw-number / rich-text 三种单元格构造器，覆盖纯文本、数值与富文本单元格；
• 支持WithPageSize（分页大小）与WithRowHeaderColumnIndex（指定行头列索引）两个 builder。

同一版本还修正了NewTaskCardBlock与NewPlanBlock对可变参数选项的 nil 防护，与库内其他块构造器的行为对齐（对应 issue #1236）。

v0.23.1：签名校验安全修复

v0.23.1 是一个纯安全修复版本：NewSecretsVerifier现在拒绝空字符串签名密钥（signing secret）。此前若应用配置缺失该密钥，攻击者可以构造出能通过校验的伪造请求签名；该修复在应用配置错误时直接返回错误而非静默放行，避免伪造事件进入业务逻辑。

v0.23.0：Agent 界面三大新块与流式 API 起点

v0.23.0 是内容最丰富的一个版本，核心是支持 Slack 2026 年 4 月发布的 Agent 界面（agent-UI）新块：

• CardBlock：通过NewCardBlock配合函数式选项（functional-options）构建，提供WithTitle、WithSubtitle、WithBody、WithIcon、WithHeroImage、WithActions等链式 builder。它复用已有的ImageBlockElement/ButtonBlockElement/BlockElements类型，没有引入新的组合对象。
• CarouselBlock：通过NewCarouselBlock接收变长的*CardBlock列表，外加WithBlockID与AddCard辅助方法，用于轮播展示多张卡片。
• AlertBlock：通过NewAlertBlock传入*TextBlockObject作为正文，严重级别由AlertBlockOptionLevel指定，取值包括AlertLevelDefault、AlertLevelInfo、AlertLevelWarning、AlertLevelError、AlertLevelSuccess；块 ID 通过AlertBlockOptionBlockID设置。

三者都接入了Blocks.UnmarshalJSON，保证 JSON 往返（round-trip）不失真。需要特别注意的是：AlertBlock只能通过流式 chunks API 投递，chat.postMessage会以 "Unsupported block type" 拒绝它。

v0.23.0 还引入了MsgOptionTaskDisplayMode选项，用于控制chat.startStream中任务块（task chunks）的渲染方式，取值TaskDisplayModeTimeline（按时间线顺序渲染）或TaskDisplayModePlan（按分组计划渲染）。

v0.23.0 流式消息 chunks API：新 Agent 块的唯一传输通道

伴随 Agent 新块，v0.23.0 为chat.startStream/chat.appendStream/chat.stopStream增加了chunks参数，并新增：

• MsgOptionChunks消息选项；
• StreamChunk接口与四种块类型：MarkdownTextChunk、TaskUpdateChunk、PlanUpdateChunk、BlocksChunk，每种都有对应的New*Chunk构造器。

这一 API 是流式 Block Kit 内容（尤其是上述 agent-UI 块）的官方传输通道。底层实现可见 chat_stream_chunks.go。也就是说，如果你的应用要渲染卡片、轮播或告警块，不能走传统chat.postMessage，而应使用 startStream → appendStream → stopStream 的流式链路，并按类型组装 chunk。

v0.22.0：搜索、富文本与 OAuth PKCE

v0.22.0 的要点：

• assistant 搜索补全：为assistant.search.context补齐Sort、SortDir、Before、After、Highlight、IncludeContextMessages、IncludeDeletedUsers、IncludeMessageBlocks、IncludeArchivedChannels、DisableSemanticSearch、Modifiers、TermClauses等参数，并新增AssistantSearchContextFile、AssistantSearchContextChannel、AssistantSearchContextMessageContext响应类型，对齐 Real-Time Search API 完整面。
• 富文本样式：RichTextSectionTextStyle新增Underline、Highlight、ClientHighlight、Unlink字段；RichTextSectionUserGroupElement新增Style字段。
• OAuth 清单：OAuthScopes新增BotOptional与UserOptional字段。
• PKCE（RFC 7636）：GetOAuthV2Response新增OAuthOptionCodeVerifier选项，并提供GenerateCodeVerifier()与GenerateCodeChallenge()辅助函数；client_secret为空时在GetOAuthV2ResponseContext与RefreshOAuthV2TokenContext中条件性省略。
• 修复：ChannelTypes与ContentTypes现在发送逗号分隔值而非重复 form key（与其他方法约定一致）；Socket Mode 收到畸形 JSON 时不再强制重连，而是抛出错误后维持连接继续运行。

v0.21.x：事件常量、序列化修复与弃用清理

v0.21.1：类型安全的频道判断

新增slackevents.ChannelTypeChannel、ChannelTypeGroup、ChannelTypeIM、ChannelTypeMPIM常量，以及MessageEvent上的IsChannel()、IsGroup()、IsIM()、IsMpIM()方法，调用方不再需要拿事件中的字符串与原始值手工比较。

同一版本修复了MsgOptionAttachments/MsgOptionBlocks的重复序列化问题：attachments 与 blocks 原先既被序列化进类型化结构字段（JSON response-URL 路径），又被序列化进url.Values（表单 POST 路径），导致重复json.Marshal。现在表单路径的序列化移到formSender.BuildRequestContext内部，每个 sender 拥有自己的 marshalling。一个已知副作用：UnsafeApplyMsgOptions返回的config.values中不再包含attachments与blocks键（该函数本身被文档标注为 unsupported）。

v0.21.0：移除遗留类型与方法

v0.21.0 是一次清理型版本：

• 弃用slackevents.ParseActionEvent：它无法解析block_actions载荷（会返回 unmarshal 错误），应改用slack.InteractionCallback+json.Unmarshal，或在 HTTP 场景使用slack.InteractionCallbackParse；InteractionCallback覆盖所有交互类型。
• 弃用仅支持遗留interactive_message的slackevents.MessageAction、MessageActionEntity、MessageActionResponse。
• 移除IM结构体（以及内部imChannel、imResponseFull）：IsUserDeleted字段迁移到Conversation，仅对 IM 类型会话填充。由于该库没有任何公开 API 返回IM，实际影响极小，但构造该类型的代码需要迁移到Conversation。
• 移除早已废弃且无条件返回nil的Info.GetBotByID、GetUserByID、GetChannelByID、GetGroupByID、GetIMByID——若代码仍在调用，直接删除调用即可（本就是 no-op），这是明确的破坏性变更。

v0.21.0 同时新增了大量实用能力（详见 interactions.go、admin_teams.go 等源码）：

• admin.teams.settings.*：AdminTeamsSettingsInfo、SetDefaultChannels、SetDescription、SetDiscoverability、SetIcon、SetName，附带TeamDiscoverability枚举（Open、InviteOnly、Closed、Unlisted）；
• OAuthOptionAPIURL：所有包级 OAuth 函数（GetOAuthV2Response、GetOpenIDConnectToken、RefreshOAuthV2Token等）现在接受可变OAuthOption，可用OAuthOptionAPIURL(url)覆盖默认 API 地址以对接本地测试服务器；
• GetOpenIDConnectUserInfo：通过openid.connect.userInfo返回 token 对应用户的身份信息；
• HTTP 响应头：AuthTestResponse直接暴露Header字段，其他方法可用OptionOnResponseHeaders(func(method string, headers http.Header))注册回调，读取X-OAuth-Scopes、X-Accepted-OAuth-Scopes、X-Ratelimit-*等响应头；
• DNDOptionTeamID：工作区迁移后 Slack 要求team_id，否则返回missing_argument，GetDNDInfo/GetDNDTeamInfo现支持该选项；
• UpdateUserGroupMembersList：接收[]string的便捷封装，可与GetUserGroupMembers链式使用；
• SetUserProfile：通过一个*UserProfile结构体在一次users.profile.set调用中设置多个字段；
• API 警告回调：OptionWarnings(func(warnings []string))接收响应中的warnings字段（弃用提示/用法建议）；
• RTM 事件映射扩充：user_status_changed、user_huddle_changed、user_profile_changed映射到UserStatusChangedEvent、UserHuddleChangedEvent、UserProfileChangedEvent（此前会触发UnmarshallingErrorEvent）；sh_room_join、sh_room_leave、sh_room_update、channel_updated映射到SHRoomJoinEvent、SHRoomLeaveEvent、SHRoomUpdateEvent、ChannelUpdatedEvent；
• 事件载荷补全：UserChangeEvent新增CacheTS、EventTS；MessageEvent新增Blocks；AppMentionEvent新增Blocks、Attachments、Files、Upload；User新增Username；UserProfile新增GuestInvitedBy；
• Socket Mode 三级处理器：HandleShortcut、HandleViewSubmission、HandleViewClosed按CallbackID分发交互，与既有HandleInteractionBlockAction、HandleSlashCommand模式一致（见 websocket_managed_conn.go）；
• BlockFromJSON/MustBlockFromJSON：从原始 JSON 字符串创建块，可直接复用 Slack Block Kit Builder 的输出，或在新块类型尚未被库支持时快速接入；原始 JSON 在 marshalling 时被保留。
• workflows.featuredAPI：WorkflowsFeaturedAdd/List/Remove/Set；
• User新增IsConnectorBot、IsWorkflowBot；修复UnknownBlock往返丢数据——无法识别的块类型现在完整保留 JSON（此前只保留type与block_id）。

v0.21.0 还包含两个破坏性变更：WebhookMessage.UnfurlLinks/UnfurlMedia从bool改为*bool（此前false会被omitempty吞掉，无法显式关闭链接/媒体 unfurl）；User.Has2FA改为*bool（机器人 token 下users.list会省略has_2fa，裸bool无法区分“缺失”与“显式 false”）。对应迁移写法：

// UnfurlLinks 指针化后 t := true msg := slack.WebhookMessage{UnfurlLinks: &t} // Has2FA 指针化后 if user.Has2FA != nil && *user.Has2FA { /* 已启用 2FA */ }

v0.21.0 光标分页迁移：Count/Page 全面退役

v0.21.0 将三个 API 从基于Count/Page/*Paging的分页切换为Cursor/Limit光标分页（Slack 服务端stars.list、team.accessLogs已不再返回paging数据，只返回response_metadata.next_cursor）：

• ListReactions：参数改为Cursor/Limit，返回([]ReactedItem, string, error)，第二个返回值即 next cursor；
• ListStars/GetStarred：StarsParameters增加TeamID，返回string取代*Paging；
• GetAccessLogs：AccessLogParameters增加Before，返回string取代*Paging。

迁移范式（以ListReactions为例）：

params := slack.NewListReactionsParameters() params.Limit = 100 items, nextCursor, err := api.ListReactions(params) // 翻下一页： params.Cursor = nextCursor items, nextCursor, err = api.ListReactions(params)

ListStars与GetAccessLogs的改法完全同构：用Limit替代Count，用返回的 next cursor 回填params.Cursor。

v0.20.0 与 v0.19.0：消息字段补全与 HTTP 重试

v0.20.0（2026-03-21）围绕消息与富文本：

• Message新增workflow_id与trigger_id字段（部分消息类型如bot_message会携带；CHANGELOG 特别警告这两个字段不在官方文档中，使用需谨慎）；
• RichTextQuote新增Border字段；RichTextPreformatted新增Language字段（可为预格式化块启用语法高亮）；
• 破坏性修复：RichTextQuote与RichTextPreformatted不再内嵌RichTextSection，改为扁平化结构，直接使用这些结构体的代码需调整。

v0.19.0（2026-03-04）带来 Web API 的可选 HTTP 重试（默认关闭）：

• OptionRetry(n)：仅对 429 响应重试；
• OptionRetryConfig(cfg)：完整控制，支持 5xx、连接错误与指数退避（exponential backoff）。

实现位于 retry.go。同一版本还新增了task_card与plan两种 Agent 块（对应 block_task_card.go 与 block_plan.go），它们是 v0.23.0 卡片/计划块的前身。

v0.18.x：大版本重构——文件上传、admin 与分页

v0.18.0-rc2：files.upload 退役与 admin.conversations

• 破坏性：移除废弃的UploadFile、UploadFileContext、FileUploadParameters——Slack 已于 2025-11-12 停用files.uploadAPI；同时将UploadFileV2→UploadFile、UploadFileV2Context→UploadFileContext、UploadFileV2Parameters→UploadFileParameters（"V2" 后缀不再需要）。UploadFile现在会按步骤包装错误（GetUploadURLExternal/UploadToURL/CompleteUploadExternal），便于定位三步上传中失败的一步。
• admin.conversations.*全面支持：核心操作（archive、unarchive、create、delete、rename、invite、search、lookup、getTeams、convertToPrivate、convertToPublic、disconnectShared、setTeams）、批量操作（bulkArchive、bulkDelete、bulkMove）、preferences、retention、restrict access 与 EKM 频道信息，见 admin_conversations.go。
• Audit Logs 修复：GetAuditLogs改用api.slack.com端点（Audit Logs API 需要独立 base URL），并新增OptionAuditAPIURL用于测试。
• 修复：Socket Mode 使用自定义 dialer 时增加调试日志（含 dial 失败时的 HTTP 响应状态），便于排查代理/TLS "bad handshake" 问题；MsgOptionPostMessageParameters不再丢弃MetaData。

v0.18.0-rc1：流式聊天、数据访问与表块

• Chat Streaming API、Data Access API完整支持；
• GetUsers与GetAllConversations引入光标分页（后者自动处理分页、限流与服务器错误）；
• Block Kit 新增context_actions块类型、workflow_button元素、table blocks 解析与创建、CallBlock完整调用数据（CallBlockData、CallBlockDataV1、CallBlockIconURLs）、Huddle 相关类型（HuddleRoom、HuddleParticipantEvent、HuddleRecording）；
• SetAssistantThreadsStatus新增loading_messages参数；CreateChannelCanvas支持自定义标题；attachments 新增ImageBytes、ImageHeight、ImageWidth；Conversation新增RecordChannel属性；remote files 支持PreviewImageName。
• 破坏性：GetReactions返回ReactedItem而非[]ItemReaction（对齐真实 API——响应包含消息/文件/文件评论本体与 reactions，迁移时用resp.Reactions取 reactions 切片）；Settings.Interactivity与EventSubscriptions改为指针（为空时可省略）；最低 Go 版本提升到 1.24。

v0.18.0：焦点加载、用户字段与 admin.roles

• 为剩余块元素（static/external/users/conversations/channels select、multi-select、datepicker、timepicker、plain_text_input、checkboxes、radio_buttons、number_input）补全focus_on_load支持；
• File新增PlainText、PreviewPlainText；User、UserProfile、EnterpriseUser补全who_can_share_contact_card、always_active、pronouns、image_1024、is_custom_image、status_text_canonical、huddle_state、huddle_state_expiration_ts、start_date、is_primary_owner等字段；
• Work Objects 支持（chat unfurl 元数据、实体详情 flexpane、entity_details_requested事件及WorkObjectMetadata/WorkObjectEntity/WorkObjectExternalRef类型）；
• admin.roles.*：listAssignments、addAssignments、removeAssignments；
• 修复：UserProfile.Skype的 JSON tag 从"skyp"更正为"skype"；assistant.threads.setSuggestedPrompts的 title 现在非空才发送；BlockElements.UnmarshalJSON补上multi_*_select与file_input分支，并修复toBlockElement对RichTextInputElement、WorkflowButtonElement的处理。

Socket Mode 可靠性：大 Ack 不再静默失败

v0.21.0 修复了 Socket Mode 的两处“静默丢弃”问题：

1. gorilla/websocket 默认 4KB 写缓冲会把消息切成 WebSocket continuation 帧，而 Slack 不重组这些帧——库改用 32KB 写缓冲；
2. Slack 对 ≥20KB 的 Socket Mode 响应会静默丢弃——Ack()、Send()、SendCtx()现在在序列化响应达到该上限时返回error。

这是破坏性变更：Ack()与Send()现在返回error，但已有调用点不接收返回值依然能编译通过。v0.22.0 进一步保证畸形 JSON 消息不再触发无谓重连。这些修复直接关系到长连接应用的稳定性，升级时建议统一处理Ack/Send的返回值。

升级检查清单与迁移速查

综合 v0.18–v0.24，升级时建议逐项核对：

其余提示：Agent 新块（CardBlock、CarouselBlock、AlertBlock、DataTableBlock、task_card、plan）只走流式 chunks API；NewSecretsVerifier要求非空签名密钥；429/5xx 重试默认关闭，按需用OptionRetry/OptionRetryConfig开启；如需捕获响应头或 API 警告，用OptionOnResponseHeaders与OptionWarnings。

结语

从 v0.18 到 v0.24，slack-go/slack 完成了向 Agent 界面新块、流式消息传输、光标分页与更严格安全校验的全面过渡，同时清理了一批历史遗留类型。对 Sliver 这类将 Slack 作为运维通知通道的项目而言，底层依赖升级主要影响事件接收与消息发送路径的编译兼容性；而对直接消费该库的应用，建议以上述迁移速查为纲，配合 CHANGELOG 原文逐版本核对，即可平滑完成升级。

• 网络安全