Rocket.Chat core-typings 演进解读：从 6.x 到 8.7 的 Changelog 与平台能力全景

本篇技术文章以 Rocket.Chat 仓库内 packages/core-typings/CHANGELOG.md 为骨架，系统梳理 @rocket.chat/core-typings 从 6.2 到 8.7 各版本的 Minor / Patch / Major 变更，解读这些类型与接口层面的改动背后所对应的真实平台能力——包括防钓鱼多因素认证与新型 OAuth 流、FIPS 合规模式、端到端加密、Omnichannel 联系人识别、会话与设备管理等。读者读完后，既能快速掌握每个版本"改了什么、为什么改、影响谁"，也能将 CHANGELOG 中的条目与仓库内具体的 TypeScript 类型文件、服务端设置与配置文件一一对应，具备可直接追溯源码的实战价值。

一、core-typings 包是什么，以及如何解读它的 CHANGELOG

1.1 包的定位与源码构成

@rocket.chat/core-typings 是 Rocket.Chat 单体仓库中的一个核心依赖包，它不包含任何运行时业务逻辑，而是集中存放整个 Rocket.Chat 前后端共享的 TypeScript 类型定义。从仓库源码结构看，其源码全部位于 packages/core-typings/src，涵盖了消息与附件（IMessage/）、会话（ISession.ts）、用户（IUser.ts）、房间（IRoom.ts）、订阅（ISubscription.ts）、设置（ISetting.ts）、集成脚本（IIntegration.ts）、License（license/）、LDAP（ldap/）、联邦（federation/）、Omnichannel（omnichannel/）等几乎所有领域模型。

在 packages/core-typings/package.json 中可以确认当前仓库内该包版本为 8.9.0-develop（即开发分支快照），其构建流程为 ts-patch install && typia patch 后执行 tsc 编译，产物输出到 dist。依赖上它直接使用 @rocket.chat/message-parser、@rocket.chat/ui-kit，并引入 typia 与 zod 用于运行时类型校验与 schema 化——这也是下文"API 端点 OpenAPI 化"能获得类型安全校验的基础设施。CHANGELOG 中大量"Updated dependencies"条目（如 @rocket.chat/message-parser、@rocket.chat/ui-kit）体现的正是这类共享依赖的版本联动。

1.2 CHANGELOG 的结构约定

这是一份由 changesets 自动化维护的版本记录，遵循语义化版本（SemVer）规范：

• Major Changes：不兼容升级，例如 8.0.0 移除废弃的 Omnichannel VoIP 与 FreeSwitch 集成、7.0.0 移除集成脚本的 "Compatible Sandbox" 选项；
• Minor Changes：向后兼容的新功能，例如新增类型字段、新设置项、新 API 端点；
• Patch Changes：缺陷修复、安全热修复与依赖升级，多数 Patch 行为与类型无关，但会通过 core-typings 的版本推进被发布出去。

同时该文件保留了 RC 预发布阶段记录（如 8.7.0-rc.0、8.7.0-rc.6），正式版内容通常与首个 RC 一致，阅读时可以 RC 与正式版互参去重。

二、8.x 的安全与合规主线：防钓鱼 MFA、现代 OAuth 流与 FIPS

8.x 版本中 core-typings 见证的安全能力演进是本文最值得关注的部分，它们直接决定了 Rocket.Chat 企业部署的安全姿态。

2.1 防钓鱼多因素认证与"现代 OAuth 流"（8.7 / 8.5）

CHANGELOG 在 8.5.0-rc.0（PR #39760）与 8.7.0（PR #40721）两次引入了同一主题：Phishing-Resistant Multi-Factor Authentication（防钓鱼多因素认证），其核心是一套更安全、更可靠的服务端 OAuth 认证流程。四个关键能力点：

• OAuth 登录在服务端完成：凭据与授权码不再经过客户端脚本，降低 token 窃取、钓鱼攻击与客户端凭据拦截的风险；
• 内置 CSRF、state 校验与 PKCE：通过安全的状态校验与 PKCE（授权码交换时的代码挑战）防止请求篡改与授权码被截获；
• OAuth 登录同样要求两步验证：启用邮箱或 TOTP 二次验证的用户，在使用 Google、GitHub、GitLab 等第三方提供方登录时也会被要求完成 2FA；
• 移动端与桌面端深链登录：支持更顺滑且更安全的 deep-link OAuth 登录流程。

管理上，CHANGELOG 明确指出新功能由设置项 Accounts_OAuth_Use_Modern_Flow 控制开关。在仓库中可找到对应实现与注册位置：apps/meteor/server/settings/oauth.ts 负责该设置的声明与默认值；认证提供方相关代码集中在 apps/meteor/server/lib/auth-providers（含 gitlab、apple、drupal、wordpress、dolphin 等），OAuth 服务更新的逻辑位于 apps/meteor/server/lib/oauth/updateOAuthServices.ts。管理员在做升级决策时可据此理解：该设置打开后才会启用上述全部安全特性，建议在验证第三方登录兼容性后再全量开启。

2.2 FIPS 模式支持（8.7，PR #39324）

8.7.0 为运行 FIPS 合规模式提供了端到端支持：

• 覆盖范围：monolith（单体）以及全部微服务（ddp-streamer、account-service、authorization-service、presence-service、queue-worker、omnichannel-transcript）都可以通过 Node.js/OpenSSL FIPS 强制使用 FIPS 合规密码学；
• 交付形态：提供专用的 FIPS Docker 镜像。仓库根目录的 docker-compose-ci.fips.yml 即为 CI 环境下启用 FIPS 的编排示例，可作为自定义 FIPS 部署的参考起点；
• 许可与观测：进入 FIPS 模式需要一份包含新 fips 模块的 License；FIPS 状态会被写入服务端日志与统计信息，便于合规审计。

需要特别提示读者：FIPS 合规涉及底层 OpenSSL 配置与镜像选择，建议在隔离环境先行验证镜像启动与加解密路径后再推进生产。

2.3 安全热修复与原子化并发修复（8.7 等）

8.5.0（PR #40405）、8.6.1（PR #41243）、8.7.0（PR #41069）以及 7.13/7.9 等版本中多次出现 Security Hotfix 条目。Patch 层面还包含一组值得关注的"check-then-write"并发缺陷修复（PR #41174）：

• CAS 登录令牌改为单次原子操作，杜绝同一令牌被两个并发登录同时消费；
• 撤销房间邀请不再产生重复的移除通知；
• 删除集成时把"仅创建者可删"的权限范围检查并入删除操作本身，避免权限竞态。

此类修复通常不改变对外类型，但都会推高 core-typings 版本以触发下游依赖升级，建议始终跟进。

2.4 认证相关 Patch 修复汇总

• 密码策略校验（8.7，PR #41173）：此前允许保存"最大长度小于最小长度"的策略组合，导致任何合法密码都无法设置；现在服务端在保存密码策略设置时会直接拒绝这种配置并给出约束说明。
• PAT 绕过 2FA 失效（8.6，PR #41065）：users.update 等要求 2FA 的 REST 端点会错误地把开启了 "Ignore Two Factor Authentication" 的个人访问令牌请求判为 totp-required；修复后 2FA 授权检查会从 REST 连接解析登录令牌，bypassTwoFactor 令牌重新生效。
• GitHub OAuth 邮箱丢失（8.3，PR #39753）：修复了经 GitHub OAuth 提供方登录的用户邮箱未保存的问题。

三、会话与设备管理类型演进：DeviceManagementSession.current

8.7.0 中一处小而关键的类型级改动（PR #40351）可以直接在本仓库得到印证：

• 为 DeviceManagementSession 类型新增 current 字段；
• 为 aggregateSessionsByUserId 新增 currentLoginToken 参数，使 sessions 端点能够识别并标记"调用者当前活跃会话"。

查看类型定义源码 packages/core-typings/src/ISession.ts：

export type DeviceManagementSession = Pick<ISession, '_id' | 'sessionId' | 'device' | 'host' | 'ip' | 'logoutAt' | 'userId' | 'loginAt'> & {
	current?: boolean;
};

同一文件中还定义了基础 ISession 接口（type 可为 session | computed-session | user_daily，包含 device、loginAt、logoutAt、loginToken、searchTerm 等字段），以及用户/设备/操作系统三个维度的聚合结果类型。这说明设备管理功能的输入侧依赖 currentLoginToken 精确命中调用者自己的会话，从而在"设备列表"中高亮"本设备/当前会话"，方便管理员在异常登录时快速识别并下线非本人设备。若读者需要扩展类似"当前会话标记"的查询或界面逻辑，改动落点就在该类型与 aggregateSessionsByUserId 对应实现中。

四、端到端加密（E2EE）能力的时间线

core-typings 的多个版本记录了 E2EE 从消息加密到文件加密、密钥分发再到运维兜底的完整能力演进：

版本	变更（PR）	核心内容
6.10.0	#32197	异步 E2EE 房间密钥分发：用户无需在线即可在订阅加密房间后异步收到密钥
6.12.0	#33003	新增设置控制 E2EE 房间的文件加密开关；修复加密文件上传与媒体类型白/黑名单的冲突
6.13.0	#32510	新增"在 E2EE 频道启用提醒（mentions）"设置
7.0.0	#33328	授权用户可重置 E2EE 房间加密密钥，防止全员丢失密钥后房间无法访问
8.2.0	#38379	加密消息与加密文件相互关联，删除其一则同步删除另一
7.13.0	#37270	修复加密消息附件描述的编辑

其中 6.12.0 的媒体类型处理逻辑尤其值得运维关注：E2EE 加密文件在服务端统一以 application/octet-stream MIME 暴露（不得泄露真实内容类型），此前该类型若未加入白名单会导致加密上传被拦截。修复后的规则是：即使 application/octet-stream 不在白名单也放行加密上传，但若它被列入黑名单则仍然拦截——白名单语义对 E2EE 上传例外，黑名单语义照常生效。

五、开放平台与开发者接口：OpenAPI、新端点与集成脚本

5.1 REST API 端点逐步 OpenAPI 化

8.2–8.3 的多条 Minor Changes 反映了 Rocket.Chat 将 REST API 迁移到现代链式路由定义并接入共享 AJV schema 的持续工程化工作：

• custom-user-status.list（8.3，PR #36916）；
• commands.get（8.3，PR #36953）；
• oauth-apps.get（7.10，PR #36598）。

共同收益是 API 文档自动生成、请求/响应经由共享 schema 校验并保证类型安全。7.6.0 还实现了对 /v1/users.update 端点的审计事件支持（PR #34494）。

5.2 新增端点与载荷调整

• 8.2.0（PR #38173）：新增单独删除已上传文件的端点；
• 7.9.0（PR #36377）与 7.11.0（PR #36207）：为 Omnichannel **Outbound Message（主动外呼/对外沟通）**新增端点并推出正式特性；
• 7.0.0（PR #33630）：startImport（数据导入）端点载荷精简，所需数据量下降；
• 6.13.0（PR #32693）：Omnichannel 新增"创建联系人"端点；
• 6.6.0（PR #30478）：新增 chat.getURLPreview 端点，用于在发消息前预取 URL 预览；
• 6.3.0（PR #48ac55f4ea）：新增批量创建用户端点；
• 6.5.0（PR #92613680b7）：集成脚本可选择两种脚本引擎；6.4.0 中同类条目出现两次，说明该能力在 RC 阶段逐步收敛。

5.3 集成（Integrations）脚本引擎治理

• 8.4.0（PR #40160）：webhook 集成新增 skipTranspile 标志（默认 false）。置为 true 时集成脚本按原样存储、跳过 Babel 转译——这与 9.0.0 中彻底移除 Babel 的默认行为保持一致，供管理员在升级前逐个集成地验证严格模式兼容性。该字段已标记为弃用，将在 9.0.0 移除。对应类型定义位于 packages/core-typings/src/IIntegration.ts；
• 7.0.0：移除已废弃的 "Compatible Sandbox" 选项及其依赖；
• 8.4.0 前后多版本反复出现的"集成脚本引擎选项"，配合 6.5.0 的部署指纹（deployment fingerprint），共同构成了 8.x → 9.0 升级路径上的兼容性预案。

5.4 应用运行时与 Apps-Engine

• 6.10.0（PR #31821）：引入基于 Deno 平台的新 Apps 运行时（仓库中对应 packages/apps/deno-runtime）；
• 7.6.0（PR #35721）：/api/apps/installed 与 /api/apps/:id/status 在 HA 与微服务部署下可跨集群获取应用状态；
• 6.11.0（PR #32719）：给 apps-engine 的 update 方法新增 user 参数，供新的 onUpdate 钩子获知触发者；
• 6.8.0（PR #32374）：修复未实现 executeViewCloseHandler 的应用导致模态框无法关闭的问题；
• 6.10.2/7.2.0/7.3.0（PR #32935/#34205/#34887）：涵盖子进程重启失败重试、错误传播、失败应用指标上报、应用无法更新/卸载等修复。

5.5 Slack 导入与消息展示修复

8.7.0（PR #41285）修复了 Slack 导入器把共享文件以原始 URL 写入消息正文的问题：导入的文件消息先保持隐藏，待用户点击 "Download Pending Files" 拉取后再以原生附件形式展示并附图片预览；下载失败（例如导出链接失效）不再被静默当作文件内容保存，而是计入错误并可重试。此外 8.5/8.6（PR #40839/#40938）修复了附件图片将 description 误用作替代文本的问题；8.6.0（PR #39273）修复了消息附件字段含非字符串 value 导致 UI 崩溃的问题。

六、Omnichannel（在线客服）领域：联系人识别与运营治理

6.1 Contact Identification（联系人识别）与统计指标

联系人识别是 7.x 中 Omnichannel 的核心功能主线：

• 7.1.0（PR #32727）：全新的 Omnichannel 联系人档案，支持"仅与已知联系人沟通""仅与已验证联系人沟通"、跨渠道合并已验证联系人、屏蔽联系人渠道、解决跨渠道注册的冲突信息，以及高级联系人中心过滤器；
• 7.2.0（PR #33895）：加入联系人识别相关统计项，包括 totalContacts、totalUnknownContacts、totalMergedContacts、totalConflicts、totalResolvedConflicts、totalBlockedContacts、totalPartiallyBlockedContacts、totalFullyBlockedContacts、totalVerifiedContacts、avgChannelsPerContact、totalContactsWithoutChannels、totalImportedContacts、totalUpsellViews、totalUpsellClicks；
• 7.4.0（PR #33816）：工作区 MAC（月活跃联系人）计数由 Livechat 访客改为联系人——启用联系人识别后多个访客可归属同一联系人，计数更准确且通常更小。

core-typings 中的相关类型位于 packages/core-typings/src/omnichannel（如 mac.ts），6.5.0 也已先行加入 omnichannelContactsBySource、uniqueContactsOfLastMonth、uniqueContactsOfLastWeek、uniqueContactsOfYesterday 等统计，并在触及 MAC 上限时限制端点、改善 UI，且将访客"禁用并匿名化"而非直接删除（PR #dea1fe9191/#5b9d6883bf）。

6.2 访客模型字段扩展

• 8.4.0（PR #39535）：ILivechatVisitor 新增 externalIds 字段，用于外部平台身份识别；
• 7.0.0（PR #33569）：新增 source 字段记录访客发消息所用渠道（API、widget、SMS、email-inbox、app 等），并保证每个访客只关联单一来源——同一人经不同渠道接入会被创建为新访客；
• 8.7.0（PR #41112）：管理员房间详情视图返回自定义字段（custom fields）。

6.3 会话分配、部门与排队治理

• 8.2.0（PR #37776）：微服务部署下通过显式的用户级锁串行化坐席分配，防止分配给坐席的会话数超过其 max chats 上限；
• 8.6.0（PR #40274）：为统一 presence 引擎打下后端基础——基于优先级的 claim 系统（internal > manual > external）、状态过期与"恢复先前状态"能力；
• 8.0.0：为房间加入邀请请求（invitation request）支持；
• 7.5.0（PR #35370）：创建/编辑部门的页面新增 Unit（业务单元） 字段；
• 6.8.0（PR #31976）：部门可配置"即使没有在线坐席也接收转接咨询"；6.6.0（PR #31328）修复 Fallback Forward Department 死循环：阻止自身与 1 层深度的循环引用被保存，并新增最大跳数设置；
• 6.12.0（PR #32846）：修复系统消息被计为坐席首次回复、污染"最佳/平均首次回复时间"指标的问题；6.4.0 修复访客放弃计时起点（改为坐席回复后的访客答复时刻）；
• 6.3.0：修复开启 max-chats-per-agent 配置时无法恢复（resume）on-hold 会话的问题；
• 7.6.0（PR #35790/#35832）：修复受 License 模块保护的设置在管理后台偶发不可编辑、语音通话取不到 ICE Server 的问题。

6.4 Livechat 与统计

• 6.7.0（PR #31820/#31268）：付费工作区可隐藏 "powered by Rocket.Chat" 水印并替换 Livechat 小组件 logo（svg/png/jpg）；新增 Livechat 触发器动作"发送消息（外部服务）"；
• 7.3.0（PR #34948）：统计数据加入语音通话数据；7.2.0（PR #34004）允许 Rocket.Chat 存储通话事件；
• 6.4.0：Omnichannel 新增 Reports Metrics Dashboard；7.13.0 在语音通话结束时于会话内生成系统消息（PR #37378）；
• 7.0.0：集成 FreeSwitch 以支持团队协作工作区的 VoIP 通话；而 8.0.0（Major） 则从 Omnichannel 移除已废弃的 VoIP 与 FreeSwitch 集成。

七、管理与设置体验：新输入组件与 LDAP/SAML/日历配置

7.1 通用管理界面

• 7.12.0（PR #37038）：引入 RangeSettingInput 组件，为接受数值范围的设置提供可视化范围输入，改善管理后台的调参体验；
• 6.10.0（PR #32425）：全局保留策略设置可选择时间单位（天/小时/分钟）；
• 7.10.0（PR #36049）：侧边栏导航引入新筛选体系（All / Mentions / Favorites / Discussions、Omnichannel 会话筛选，以及按 Teams / Channels / DMs 分组），需在 Enhanced navigation experience 功能预览中启用；
• 6.13.0（PR #33225）：实现 Sidepanel 的功能预览。

7.2 用户管理与席位

6.9.0（PR #31917）将用户页改为标签页布局并新增 "All"；6.10.0（PR #31987）新增 "Pending Users" 页签列出尚未激活/从未登录的用户、增加 "Pending Action" 列与"加入原因"字段、展示席位超额提示，并限制超额后继续创建用户；8.0.0（PR #37224）则细化用户停用状态的表达，正确区分 pending 与 deactivated。

7.3 LDAP、SAML 与日历

• LDAP 自定义变量字符串函数（7.6.0，PR #35717）：可在 LDAP 数据映射器中配置含字符串操作的自定义变量；
• LDAP 同步联邦用户（7.6.0，PR #35718）；
• LDAP 属性映射用户 extension（7.0.0，PR #33598）；
• SAML 签名算法可选（7.8.0，PR #36037）：新增设置项选择签名 SAML 请求与响应使用的算法；
• Outlook 日历按邮箱域名覆盖设置（7.8.0，PR #36153）；7.13.0 修复日历事件通知按本地时区显示时间（PR #37318）。

八、平台底座：License、部署指纹、消息渲染与杂项修复

• License v3 与 add-ons（6.5.0 PR #5f81a0f3cb + 7.0.0 PR #33433）：实现 License 库（管理过期时间、模块、限额等），新增特性列表更完整的 v3，并保持对 v2 的即时转换兼容；7.0.0 起支持与 License 中签发的 add-ons 交互。对应类型可查看 packages/core-typings/src/license。
• 部署指纹（6.5.0，PR #ec1b2b9846）：由 ${siteUrl}${dbConnectionString} 经 sha256 + base64 哈希生成，用于识别数据库克隆等部署变化；设置环境变量 AUTO_ACCEPT_FINGERPRINT=true 可自动接受预期内的指纹变更。
• 云令牌存储迁移（7.0.0，PR #32856）：新增集合统一存储工作区云令牌，把竞态管理下沉到 MongoDB；同时移除 Cloud_Workspace_Access_Token 与 Cloud_Workspace_Access_Token_Expires_At 两个设置。
• 消息渲染：6.6.0（PR #31349）实现 Bold/Italic/Strike 中的 InlineCode 处理；7.5.0（PR #35369）修复多层递归引用（达到链式引用上限时）导致内部附件显示为空的问题；8.3.0（PR #39425）消息编辑器支持一次上传多个文件；7.6.0（PR #35369 前导修复）同期完善引用展示。
• 自定义 emoji 更新（7.1.0，PR #32991）：修复更新后不生效及缓存问题。
• push 统计（6.5.0，PR #c0ef13a0bf）：push 统计项由三个位构成布尔集合——push 启用 = 0b1 = 1、push 网关启用 = 0b10 = 2、push 网关变更 = 0b100 = 4。
• 消息自定义字段（6.8.0，PR #32224）：仅 API 场景支持、可在工作区设置中开关的消息自定义字段；6.3.0 同时增强了注册流程的自定义字段表单。
• Webhook 目标频道覆盖（6.3.0，PR #12d97e16c2）：允许 Incoming Webhooks 覆盖目标频道；6.4.0 修复 overrideDestinationChannelEnabled 被误当作必填参数、以及 setDefault 端点置 false 后不返回 default 字段的问题。

九、总结：如何用这份 CHANGELOG 指导升级与排查

纵览 6.x → 8.7 的记录，可以提炼出 Rocket.Chat 近几个版本在 core-typings 层面体现的几条演进主线：

1. 安全左移：服务端 OAuth、CSRF/state/PKCE、2FA 与 OAuth 强绑定、FIPS 合规、并发竞态原子化，均集中在 8.4–8.7，建议 8.x 用户优先关注 Accounts_OAuth_Use_Modern_Flow 与安全热修复；
2. E2EE 从"消息"走向"文件+密钥全生命周期治理"：异步密钥分发、文件加密开关、密钥重置、加密文件与消息联动删除，构成完整闭环；
3. Omnichannel 从"会话"升维到"联系人"：MAC 口径切换、冲突合并、跨渠道来源隔离，是 7.x 客服侧的最大变化；
4. API 工程化：OpenAPI/共享 schema 化迁移与 skipTranspile 兼容期字段，为 9.0 移除 Babel 铺路。

在阅读本仓库时，packages/core-typings/src 下每个领域接口（如 ISession.ts、IIntegration.ts、ILivechatVisitor.ts、license/、omnichannel/）都是与本 CHANGELOG 条目一一对照的最佳入口；版本推进详情则以 packages/core-typings/package.json 中的版本号与 packages/core-typings/CHANGELOG.md 为准。升级前，建议结合各 Minor 条目中的设置项名称在 apps/meteor/server/settings 中检索其默认值，并对安全与 E2EE 相关改动做小范围灰度验证。