晞晗IM · XHIM

主题

XHIM 商用就绪度与发布门禁 ​

产品名称：晞晗IM（XHIM）

文档状态：Active

最近审查：2026-07-26

当前结论：项目代码已进入 0.1 Commercial Beta。真实登录、HTTPS/WSS、 收发/增量同步、社交治理、Push Outbox、单对象附件媒体、五个原生 OS 平台工程 （覆盖 iOS/macOS/Android/Windows/HarmonyOS）和基础 UI 源码已经落地。 凭证重叠轮换、附件分片/缓存/审核状态机、离线只读、通用请求取消、 SQLCipher 接入和正式发布证据门禁已经落地。iOS Device/Simulator 的 Apple 原生 HTTP(S)/WS(S) Product Adapter（生产默认 HTTPS/WSS）、Endpoint Ed25519 校验、Keychain 数据库 Key、Development XCFramework、公司签名和二进制 Swift Package 已于 2026-07-25 完成构建，Demo 已安装登记真机；PostgreSQL 服务端下 Alice/Bob 双向发送、同步和已读已实测通过。实时音视频从纯 IM 首发范围移出，后续通过 可选厂商 Adapter 接入；正式生产域名/KMS/APNs 制品、全平台真机、容量实测、 安全扫描与法务审批仍是 Stable 发布门禁。

这里的 Stable 门禁用于限制“已经完成生产认证”的宣传，不限制 XHIM 以明确标注 的 Commercial Beta、源码授权或受控试用方式销售。销售前不需要替购买方配置 真实生产环境；购买方域名、证书、数据库、Push、对象存储、业务账号和容量验收 属于客户部署责任。XHIM 交付方需要准备的是固定版本的软件包/源码、兼容版本的 Server、文档、示例、许可证、校验值和已知限制。

1. 文档目的 ​

本文用于持续回答三个问题：

  1. XHIM 距离“第三方接入后可以稳定二次开发”还缺什么；
  2. Alpha、Beta、Stable 各阶段必须满足哪些发布门槛；
  3. 下一批开发应按什么顺序推进，避免平台代码、UI 和内核协议相互绑死。

本文是 XHIM 自身的 Stable 发布门禁，不是客户购买前置条件。每次关闭一项缺口， 都必须同时提交实现、测试、文档和可消费产物的证据；仅有设计文档、接口占位、 单元测试 Mock 或某个平台能够编译，不能视为完成。

2. 当前可复用基础 ​

当前仓库已经具备以下可靠性基础：

  • C++17 内核和版本化 C ABI；
  • 单线程 Client Actor、账号 Epoch 和连接 Generation 隔离；
  • SQLite WAL、Schema 迁移、消息与 Outbox 同事务写入；
  • 专用 joinable I/O 线程的 Outbox Worker、future timer、凭证暂停/恢复、 账号范围会话 FIFO、Epoch stage fence、durable cancel tombstone、 revoke/drain、租约恢复和 typed fault；
  • Outbox 有限重试以及 ACK/Sync 乱序归并；
  • 有界 Inbox 去重窗口和 Sync Page/Cursor 原子提交；
  • 后端无关的 HTTP Send、Session、Endpoint 和 WebSocket Port；
  • 实验性 ClientEngine 统一拥有 Backend、Store、Runtime、Coordinator、 Transport 和 Worker；Ready permit 激活、本地发送事务 + Worker wake、 同 Epoch 受控重连期间的 permit 延续，以及 logout/shutdown revoke/drain 已进入同一组合根；
  • Engine 权威状态订阅使用独立的有界单泵 mailbox，发布时捕获订阅者、积压时 latest-wins 合并中间快照并保留最新终止状态；同步 Ready/Fatal 发布先冲刷 已排队旧快照，避免单泵让出执行权后发生状态回退；Worker fault 按账号 Epoch 本地锁存 CredentialRequired/Fatal，并确认 Runtime 终止迁移实际应用，避免 Coordinator 与 Runtime 之间的异步窗口误报 Ready；
  • 可关闭实时 Session、hint 合并、持续 Sync、旧连接 fence、有限指数退避重连 和恢复 Sync 编排；
  • 通用版本化消息信封已经贯通 Storage、Outbox、Sync、Engine 和稳定 C ABI； 旧文本规范化为 text/plain@1，未知类型和高版本二进制 Payload 可原样往返；
  • 当前账号本地安全文本投影支持按会话、发送者和内容类型过滤的 keyset 分页 检索；搜索词不上传服务端，iOS、macOS、Android、Windows 和 HarmonyOS Facade 均提供类型化查询和请求取消；
  • 贴纸、位置、名片、引用回复和合并转发已冻结为 xhim_content_v1.proto，五个原生 OS 的 Facade 提供有界校验和一致的 Protobuf 消息工厂；
  • 媒体消息已有固定的 xhim_media_v1.proto、C++ MediaRef/图片/语音/视频/ 文件模型和严格安全上限校验；Schema v6 引入账号隔离、幂等创建、合法状态 转换、持久进度、可重试失败、执行租约和 revision fence 的 media_tasks； 当前 Schema 为 v12，并保留 v1-v12 冻结 fixture。供应商无关的 MediaTransport、处理器和专用 MediaWorker 已覆盖重试、凭证暂停、Epoch 排空与过期租约恢复；稳定 C ABI 已提供 upload/download create/get/cancel，Reference POSIX Adapter 已实现 严格 Range 下载、partial 恢复、完整性验证和安全 TTL/LRU 缓存执行；
  • shared/static CMake 安装包消费测试。
  • Go 参考服务端、PostgreSQL Store、Ed25519 JWT/Endpoint、HMAC Cursor、 Protobuf HTTP API 和 WebSocket Sync Hint；
  • 版本化好友/群 Protobuf、好友申请接受/拒绝、社交快照、Owner 管理的动态 群成员、revision 乐观并发控制、成员分页，以及和账号事件流同事务提交；
  • C++ reference Product Adapter 的严格 TLS、HTTP/WebSocket、auth/send/sync Codec，以及公共 C ABI 到 Go 服务端的真实网络纵向测试。
  • Apple 原生 Product Adapter 的 URLSession HTTP(S)/WS(S)、生产态系统 SecTrust、默认 HTTPS/WSS fail-closed、显式局域网 Development 策略、 Endpoint allowlist/Ed25519 校验、请求取消、Generation fence 和 Keychain/SQLCipher 数据库 Key；
  • 会话权限绑定的媒体 Prepare/Complete/Download 控制面、PostgreSQL 元数据、 本地 HMAC 对象 Adapter、S3/S3-compatible 预签名 Adapter、服务端 SHA-256/长度/MIME 二次校验，以及上传者到接收者的真实 TLS 媒体 E2E。
  • Schema v9 的好友申请、好友、群、群成员、黑名单、入群申请和群资料本地 投影与稳定 C ABI 分页读取；
  • 服务端黑名单、入群审批、管理员、禁言、群主转让、群名/头像/公告/简介、 持久审计和 Push Outbox；
  • 预研性质的供应商无关 XHIM::RTC Call Actor、服务端持久信令与按用户签发 的短期 RTC Token；这些模块不进入纯 IM 首发完成度计算；
  • SwiftPM/SwiftUI、Gradle/JNI/Kotlin/Compose、.NET/SafeHandle/WPF、 Node-API/ArkTS/ArkUI 的平台 Wrapper/UI 源码与 QuickStart；
  • iOS、macOS、Android、Windows、HarmonyOS 已统一提供版本化自定义消息发送、 插件校验、会话/通知摘要、未知版本 fallback 和可选 UI Renderer Registry。

这些能力证明跨端源码产品骨架已经形成，但不能推出各商店/包管理器的签名制品、 容量 SLO、法务合同和正式发布链路已经完成。

3. 严重级别 ​

级别含义发布规则
P0功能、数据、安全、法务或交付层面的 Stable 阻断未全部关闭时不得宣称“已通过生产认证”或发布 Stable；可以按已知限制交付 Commercial Beta/源码授权
P1Stable 前必须解决的稳定性、兼容性和可维护性问题可用于受控 Beta 集成，但不得作为无人值守的正式 SDK 交付
P2Stable 质量、体验和运营成熟度可按版本迭代完成，但必须有明确负责人和目标版本

4. P0：商用发布阻断 ​

P0-01 生产登录主链路已接通，信任与凭证生命周期仍未封板 ​

公共 C ABI 已改为 fail-closed：未装配真实后端时， xhim_v1_client_login() 返回 XHIM_V1_STATUS_BACKEND_NOT_CONFIGURED， 不会进入 Ready。本地模拟链路只允许由 CLI 和自动化测试显式设置 XHIM_V1_CLIENT_FLAG_LOCAL_PREVIEW 后使用。产品构建现在可以嵌入 adapters/reference_server，连接仓库内 Go 服务端完成 JWT 认证、Endpoint、 WebSocket 和初始同步。

当前实验性 XHIM::Engine 已有唯一组合根 ClientEngine：它统一拥有 SessionBackend、Store、Runtime、SessionCoordinator、Transport 和 OutboxWorker。Coordinator 通过可注入 Backend 串行编排 canonical 认证、 完整 Endpoint、连接和初始分页 Sync，并在 SQLite 到达 high watermark 后才 发布 Ready；Engine 随后交叉校验身份/Epoch、排空旧发送许可并激活新的 Worker permit。Engine 已增加权威状态订阅：首次 Ready 只在 Worker 与发送 许可可用后投递；发布时捕获订阅者，独立有界 mailbox 在极端积压时合并中间 快照并保留最新终止状态。Worker fault 还会按账号 Epoch 在 Engine 本地锁存 CredentialRequired/Fatal，不依赖 Coordinator 已接受就假定 Runtime 一定完成 迁移；fault acknowledgement 为 false 时，匹配 Epoch 会升级 Fatal。同步 Ready/Fatal 发布还会先按 FIFO 冲刷已排队的旧瞬时快照，防止回调积压造成状态 倒退。稳定 xhim_v1 已改为只拥有这一个 ClientEngine；production 端口通过 私有 build-time Product Adapter 强工厂注入，默认未配置强实现继续 fail-closed。FFI 状态只订阅 Engine，send 也只走 Engine 的事务和 Worker 路径，不再维护第二套 Runtime/Store 状态机。Reference Adapter 已在 macOS Apple 系统 libcurl 上完成真实 TLS 纵向联调；系统 curl 没有启用 ws/wss 协议时，由 Adapter 在严格 TLS 连接上执行 HTTP/1.1 WebSocket Upgrade 和 有界 RFC 6455 帧解析。

Reference Adapter 现在同时校验 Endpoint、Key ID、有效期，并使用客户在 DeploymentConfig 提供的 Ed25519 公钥验证服务端签名；未提供运行时部署配置 时，发行方仍可使用构建时最多八个不可变公钥组成的重叠信任环作为默认配置。 服务端 TokenManager 也支持旧 Token 验证、新 kid 原子切换和旧公钥退役，五端 Facade 已有 updateCredential。Apple 原生 Adapter 已通过 URLSession/系统信任链接入 同一工厂，并使用 Keychain 设备绑定随机 Key 打开 SQLCipher；它没有复制第二套 Runtime、Outbox 或 Sync 状态机。本项仍保持 P0，因为 KMS 动态装载、Token 撤销列表、正式生产证书域名、真实滚动发布演练和错误 Token 完整黑盒矩阵尚未 封板。

证据：

  • ffi/src/xhim_v1.cpp 的 Engine 组合、production fail-closed、非阻塞状态 relay、shutdown fan-out 和 C 回调内销毁；
  • product_adapter/ 的 build-only SPI、唯一强工厂与默认未配置实现；
  • engine/src/client_engine.cpp 的唯一组合根、send permit 与 Outbox drain；
  • engine/src/session_coordinator.cpp 的生产会话状态编排；
  • tests/client_engine_test.cpp 的 Ready/send、权威状态顺序、回调内退订、 后订阅者隔离、跨线程退订等待、初次登录积压顺序、mailbox 合并和终止状态保留、 CredentialRequired/Fatal Epoch 锁存、Coordinator 接受与拒绝 Worker fault、 logout drain、shutdown 和串行 Completion 回归测试；
  • tests/session_coordinator_test.cpp 的分页、失败、并发和 Runtime 终止迁移 拒绝 acknowledgement 回归测试；
  • tests/product_adapter_c_abi_test.cpp 的 flags=0 已配置产品 Adapter start → login → Ready → send → ACK → shutdown；
  • server/ 的 JWT、Endpoint、HTTP/WSS、Store 和纵向测试；
  • adapters/reference_server/ 的真实网络实现；
  • adapters/apple_server/ 的原生 HTTPS/WSS、Endpoint 签名与 Keychain Database Key Provider；
  • scripts/run_server_e2e.sh 的 C ABI → TLS/WSS → Server → ACK/Sync → ServerAccepted。

退出条件：

  • Ready 只能由统一的 Client Engine 在以下条件全部成立后发布：
    1. 服务端认证成功并取得 canonical account_id/self_user_id；
    2. 完整 EndpointBundle 已验证签名、有效期和版本；
    3. 实时连接或降级策略已确定；
    4. 初始增量同步成功到达一致性水位；
    5. 对应的账号 Epoch 和连接 Generation 仍然有效；
    6. Engine 已复核 canonical identity、排空旧 Epoch 并激活当前发送 permit。
  • 未配置后端 Adapter 时必须明确返回 NOT_CONFIGURED/UNSUPPORTED，不得模拟成功。
  • Stable 发行构建必须关闭或移除 local preview 能力，不能由生产业务动态开启。
  • 增加“错误 Token 不得进入 Ready”“旧认证响应不得改变新账号状态”的端到端测试。

P0-02 真实网络发送与同步闭环已形成，故障矩阵尚未封板 ​

实验性 ClientEngine 已经组装发送内核：send_text 和通用 send_message 在账号 fence 内提交 Message + Outbox 本地事务并唤醒 OutboxWorker；Worker 使用专用 I/O 线程、 future timer、账号范围会话 FIFO、Epoch stage fence、durable cancel tombstone 和 lease recovery 调用阻塞式 Transport。logout/shutdown 会先 关闭发送准入，再撤销并排空旧 Epoch。这个改动关闭了“实验性 Engine 内部没有 Outbox 调度”的缺口。

Reference Adapter 和 Go Server 已将 本地入队 → HTTPS 发送 → 服务端提交 → WSS hint → Sync → SQLite 归并 跑通；网络 CLI 会等待本地消息进入 SERVER_ACCEPTED，因此不再把“本地入队” 冒充服务端成功。PostgreSQL 持久化路径另有真实集成测试覆盖消息提交、幂等 重放和双方 Event Stream；2026-07-25 的 Docker 环境已验证 Alice/Bob 两个 独立客户端数据库双向发送、同步和服务端已读序号。Go 端使用 Buf 固定版本生成的 Protobuf，C++ 当前使用有界手写 v1 Codec。

单元级网络决策矩阵现已覆盖取消、离线、DNS、超时、TLS、401/403、429、常见 5xx、协议、超限和业务拒绝。本项仍保持 P0，因为还缺固定版本的 C++ 生成式 Codec，以及这些故障、断线重连、进程重启和 ACK/Sync 乱序的真实网络黑盒矩阵。

退出条件：

  • 保留现有唯一 ClientEngine 组合根，在其上接入真实 Backend、Transport、 凭证刷新生命周期并通过现有 Product Adapter 工厂注入；不得另建一套平台 发送、重连或 Sync 状态机；
  • 实现至少一个受支持平台的真实 HTTPS/WSS Adapter；
  • 固定并生成 Protobuf Codec，禁止只靠手写文本 fixture 代表 wire 兼容；
  • 消息完成 本地入队 → HTTP 发送 → ACK/Sync 归并 → UI 可查询状态 的闭环；
  • 覆盖离线、DNS、TLS、超时、401、429、5xx、断线重连、进程重启和 ACK/Sync 乱序；
  • 在真实网络上验证连接 handle 收束、hint 风暴合并、重连退避/抖动、 Retry-After、网络切换和前后台恢复，不以 Fake Backend 单测替代；
  • 普通业务错误不得触发重新登录、域名切换或整个 Client 重启。

P0-03 公共 API 不足以支持第三方二次开发 ​

当前 C ABI 已增加通用 send_message 和三个账号隔离的本地读取切片：第三方 可以发送 content_type + content_version + opaque payload + fallback_text， 并用 client_message_id 异步查询不可变消息快照及发送状态，也可以用不透明 keyset Cursor 分页读取一条会话的权威消息时间线，或按置顶和持久化活动顺序 分页读取会话摘要。未知 ID 使用稳定 NOT_FOUND；页面上限固定且所有借用数据 都有 Callback 生命周期合同。两类分页和单条查询都通过 ClientEngine 和 Runtime 账号 Epoch fence 执行，不允许 FFI 线程 直接读取 SQLite，也不接受调用方传入账号 ID。Storage、Engine 和 C ABI 测试 覆盖消息展示顺序、会话置顶/活动顺序、无重复翻页、Cursor 往返及串行回调线程。 iOS、macOS、Android、Windows 和 HarmonyOS Facade 现已统一提供强类型单消息、 时间线分页、会话分页模型，并在平台 Callback 内复制所有快照和不透明 Cursor； 应用可直接从返回消息的服务端序号提交 markRead，无需接触 C ABI 或 SQLite。

这关闭了“没有通用消息信封”“发送后无法读取单条本地消息状态”“没有会话 时间线分页”和“没有会话列表分页”的基础切片。本轮又增加了账号 Epoch 隔离的永久失败消息重试、发送前取消、凭证更新、变更事件和五端原生 Facade。 服务端权威的跨设备已读也已贯通 Go 服务端、Sync、SQLite、Engine、稳定 C ABI 和五端原生 Facade。版本化 runtime_policy@1 已贯通稳定 C ABI 与五端 Facade， 支持请求超时、Sync Page、重连初始/最大延迟和最大重连次数；Bootstrap/TLS Trust/Endpoint 公钥故意只由 Product Adapter 管理，不允许 App 关闭安全校验。 独立 OfflineReader 已使用只读/query-only 句柄并验证账号绑定；稳定 C ABI 已提供独立同步句柄、消息/检索/会话及六类社交分页，明确借用视图生命周期、 同句柄串行约束、账号/Schema/加密密钥校验，并拒绝在只读路径执行迁移。稳定 C ABI 所有异步请求也已支持逐 request_id 取消，Swift Task、Kotlin 协程、 .NET CancellationToken 和 Harmony 请求 ID 已接入。五端 OfflineReader Facade 与非敏感运行诊断快照已经落地；正式加密数据库真机矩阵、公共日志 策略和更细的能力策略仍未完成，因此本项继续保持 P0。

退出条件：

  • 已提供版本化运行策略，覆盖账号存储隔离、网络超时、同步和有限重连； Bootstrap/TLS Trust/Endpoint 公钥由 Product Adapter 管理；继续补齐公共 日志、正式加密离线模式验收和更细的能力策略；
  • 登录结果使用服务端认证后的 canonical account_id/self_user_id，不能把调用方传入的 user_id 同时当作两者；
  • 提供通用 MessageEnvelope 和文本便捷 API；
  • 提供会话列表、消息时间线和消息状态的分页查询；
  • 已提供 retry、send-before-transport cancel、updateCredential、通用逐请求 cancel 和服务端权威 markRead/read sequence；
  • 事件必须有稳定的 kind、schema version、payload encoding 和变更范围；
  • 平台调用方不需要接触 C++ 指针、SQLite 连接或内部线程。

P0-04 自定义消息与协议前向兼容已完成基础闭环 ​

版本化消息信封和未知二进制 Payload 往返基础已经实现：Storage、Outbox、Sync、 Engine 和稳定 C ABI 都保存 content_type/content_version/payload/fallback， 旧文本 Wire 字段也保持兼容；测试覆盖内嵌 NUL、未知类型、高版本、幂等冲突和 旧文本回放。iOS、macOS、Android、Windows 和 HarmonyOS Facade 现已提供统一的 OutgoingMessage、插件 Registry、发送前校验、会话摘要、通知摘要和基础 UI Renderer Registry；多线程平台使用锁/并发容器，ArkTS Registry 限定在创建它 的同一 isolate 使用。插件未注册、不支持高版本、Payload 不合法或 Renderer 抛错时统一展示 fallback_text，Core 中的原始 Payload 和 Cursor 不受影响。 iOS、macOS、Android、Windows、HarmonyOS QuickStart 已加入商品卡片二次开发示例。

已满足的关闭证据：

  • 消息使用 namespace + content_version + immutable payload + fallback_text；
  • 未识别或高版本 Payload 必须原样持久化、同步和导出，不得丢弃；
  • 提供自定义消息校验、会话摘要、通知摘要和 UI Renderer 的平台插件协议；
  • 插件崩溃或未注册时使用稳定 fallback UI，不能影响 Cursor 推进或导致消息丢失；
  • Core 已覆盖未知版本、跨端 Wire 往返和旧文本 SDK 重放；平台测试覆盖已知/ 未知版本、重复注册、非法信封与 fallback。

P0-05 原生平台源码已实现，跨端框架和正式包仍待封板 ​

platforms/apple、platforms/android、platforms/windows、 platforms/harmony 现在包含原生 Facade、Native Bridge、基础 UI 和 QuickStart；iOS 和 macOS 有独立客户入口，内部只复用 XHIMSwift 实现。 Flutter、Electron 和 Web 已有首批适配源码，但 React Native、Unity、 uni-app 和 Mini Program 尚未形成可消费 Adapter。XHIMSwift 已在 macOS 编译，Android JNI 和 Harmony Node-API 已通过目标头文件 的严格 C++ 语法门禁。iOS Development XCFramework 已包含 Device arm64 与 Simulator arm64/x86_64、使用公司身份签名并由最终二进制 Package Demo 消费； 登记 iPhone 安装已通过。该项仍保持 P0，是因为这不是 Production 制品，且 macOS、Android、Windows、HarmonyOS 和跨端框架尚未全部产出经过目标设备验证、 签名并发布到正式包管理器的二进制。

退出条件：

  • 对每个对外宣称支持的平台提供并验证正式产物：
    • iOS：Device/Simulator XCFramework + XHIMSwift / CocoaPods；
    • macOS：arm64/x86_64 XHIMSwift / CocoaPods + 签名公证；
    • Android：多 ABI AAR + Maven 元数据；
    • Windows：x64/arm64 DLL + NuGet RID assets；
    • HarmonyOS/OpenHarmony：目标 ABI .so + HAR/OHPM；
    • Flutter：pub plugin + iOS/macOS/Android 消费矩阵；
    • Electron：npm + 目标 Electron ABI prebuild；
    • Web：npm ESM 包 + 主流浏览器/弱网/升级消费者矩阵；
    • React Native、Unity、uni-app、Mini Program：各自 Adapter 和包；
  • Wrapper 使用平台原生异步、错误、生命周期和资源管理方式；
  • 每个平台用空白示例工程消费最终打包产物，而不是引用源码工程；
  • UI Kit 作为可选独立包，只依赖原生 Headless Facade；
  • 删除 UI Kit 后，Headless SDK 功能仍然完整。

P0-06 安全/隐私交付基线已建立，法务与制品证明待封板 ​

仓库已加入专有 LICENSE、NOTICE、SECURITY.md、威胁模型、隐私数据清单、 容量/灾备和发布清单，并提供 SPDX/CycloneDX、许可证收集、五端签名、真机、 安全扫描、容量和法务强制门禁。SQLCipher 使用显式 CMake Target，要求加密时 无密钥或误链普通 SQLite 会 fail closed。该项仍保持 P0，因为正式商业合同和 版权主体需律师确认；Apple Keychain/SQLCipher 已有 Development 证据，但 Android Keystore、Windows 安全存储、Harmony HUKS，以及正式签名、SBOM 和 扫描仍需在各平台发布环境验证。

退出条件：

  • 明确商业授权模式，并提供 LICENSE、NOTICE 和第三方许可证清单；
  • 提供 SECURITY.md、漏洞报告渠道、支持版本和修复响应策略；
  • 提供隐私与数据处理说明，列出本地数据、网络数据、日志、诊断和可选遥测；
  • Token、密钥、消息正文、手机号和完整 Cursor 不进入普通日志、Crash 或诊断包；
  • Token/数据库密钥接入 Keychain、Android Keystore、Windows 安全存储和 Harmony HUKS；
  • 生产 HTTPS/WSS 默认严格校验证书，不提供静默关闭校验的发布配置；
  • Release 产物生成 Hash、签名和 SBOM。

P0-07 Core 与平台技术标识已冻结，签名主体仍需发布证据 ​

Core 已完成“晞晗IM / XHIM”硬改名，代码前缀、C ABI、头文件路径、CMake package/target 和核心库名称已经进入品牌门禁。基于组织控制的 xihansoftware.com 命名空间，Apple Module/Pod、Android Maven、Windows NuGet 和 Harmony OHPM 技术标识也已落入构建文件。仍未由仓库证明的是各平台 正式签名证书主体、商店/包管理账号所有权和最终制品签名链；这些属于发布证据， 不能用源码常量代替。

退出条件：

  • 持续由品牌门禁保护已经冻结的 Core 标识：
    • 展示名：晞晗IM；
    • 英文产品名：XHIM；
    • 代码和 C ABI 前缀：xhim / xhim_v1；
    • 头文件路径、CMake package/target 和核心库名称使用 XHIM 标识；
  • 持续冻结并校验 Apple XHIM/XHIMSwiftUI、Android com.xihansoftware.xhim:xhim-sdk/xhim-ui-compose、Windows XHIM.SDK/XHIM.UI.Wpf 和 Harmony @xihansoftware/xhim；
  • 客户 App 自己的 Bundle/Application ID 不由 SDK 强制；XHIM 示例/构建宿主 使用登记的 com.xihansoftware.xhim.*；
  • 各平台包名、资源前缀、真实签名主体和发布账号必须进入同一产品标识表和发布 证据检查；
  • 品牌门禁应拒绝历史标识重新进入现行代码、公共文档和新产物；历史存储兼容信息只能保留在专门的迁移说明中；
  • 首次外部发布后如需更改平台发行标识，必须提供兼容别名、迁移说明和明确的废弃周期。

P0-08 附件消息内核闭环已完成，生产媒体面仍需外部验收 ​

通用消息信封已经为图片、文件及预留媒体类型提供稳定类型入口，供应商无关的 媒体任务调度、断点进度、失败重试、账号 Epoch 排空和崩溃租约恢复也已落地。 服务端现已提供单对象媒体闭环：Prepare 生成稳定 MediaRef 和短期授权， Complete 从对象存储重新读取并校验 SHA-256/长度/MIME 后才进入 Ready，下载 授权按 conversation_id 实时复核成员身份；本地开发使用 HMAC 签名 URL， 生产配置只允许 S3/S3-compatible Adapter。跨账号真实 TLS E2E 已验证 Alice 上传、Bob 下载。

当前上限为 256 MiB。客户端已有媒体 Descriptor Codec、Reference Prepare → PUT/PATCH 断点流式上传 → Complete Adapter、SQLite v12 持久意图、 ClientEngine/MediaWorker 统一所有权，以及完成后生成 Payload 进入 Outbox 和重启恢复。稳定 C ABI 已提供 upload/download create/get/cancel、借用型 任务快照和 schema=1 任务事件；创建 OK 明确只表示持久化受理。事件/快照不 返回本地路径、Token、签名 URL 或上传会话凭证。Reference POSIX 下载严格 拒绝重定向和明文传输，非零偏移只接受匹配的 206 Content-Range；partial 在 发布进度前 fsync，完成后校验大小/SHA-256 并 no-replace 原子发布，缓存根内 按 TTL 优先/LRU 执行有界配额清理。稳定 scoped reader ABI 通过 MediaTransport 可选端口打开并复验完成对象，持有 no-follow 原生句柄后按 offset 有界读取，不返回缓存路径；reader 可独立于 Client 生命周期。

服务端已有完整性校验后的 pending → review_pending → ready/rejected 状态机与可替换 Reviewer Port。 平台不得推测 storage_path 派生路径；iOS、macOS、Android、Windows 和 HarmonyOS Facade 已将 scoped reader 包装成平台 I/O API（Apple 同时覆盖 iOS/macOS）。 仍缺真实病毒/内容审核厂商、缩略图/转码、Windows reparse-point-safe Reference 缓存端口、真实 S3 multipart/CDN 实测及五端真机 弱网证据。本项只约束纯 IM 首发所需的图片、文件等附件消息；实时语音/视频通话 已明确推迟。

退出条件：

  • 媒体消息只保存稳定 MediaRef，上传授权、分片恢复、完成校验、下载缓存、 媒体任务与消息 Outbox 依赖都通过进程重启和弱网测试；
  • 完成图片/文件缩略图、可恢复上传、病毒扫描/内容审核策略、缓存回收和 CDN 策略；
  • 五端 Picker URI/安全作用域、后台传输、磁盘不足、权限撤销和进程重启完成 真机测试；
  • 详细 Definition of Done 以 媒体消息与实时音视频架构 的“附件媒体” 部分为准。

5. P1：Stable 前必须完成 ​

P1-01 收紧稳定边界 ​

当前安装包除 C ABI 外，还导出 Core、Storage、Sync 和 Transport 的 C++ targets 与内部头文件。这会让第三方依赖不承诺 ABI 稳定的实现细节。

退出条件：

  • 默认商业包只暴露稳定的聚合 C ABI 和平台原生 Facade；
  • 需要二次开发的扩展点单独形成版本化 Extension API/ABI；
  • 内部 C++ targets 默认不安装，或明确标记为 source-level、无二进制兼容承诺；
  • CI 保存并比较 C Header、导出符号和 Struct 布局基线。

P1-02 完善错误、日志和诊断模型 ​

稳定 C ABI 已在兼容结构尾部增加 domain/stable code、native code、 retryable/retry-after、user action、operation ID 和 trace ID，iOS、macOS、Android、 Windows、HarmonyOS Facade 均复制为平台原生 Error/Exception，宿主已经可以 避免解析英文文本。稳定 C ABI 现已提供无 I/O 的非敏感诊断快照，覆盖状态、 Epoch/Generation、请求/订阅、队列和拒绝/丢弃/合并计数。公共日志 Sink、 状态转换历史、诊断包导出和统一脱敏自动化仍未完成，因此本项继续保持 P1。

退出条件：

  • 错误包含稳定 domain/code、native/server code、retryable、retry_after、user_action、operation ID 和 trace ID；
  • UI 和宿主只按稳定字段决策，不解析英文错误字符串；
  • 提供可注入日志 Sink、等级、分类、采样和脱敏策略；
  • 提供有界诊断导出，包含 SDK/ABI/Wire/DB 版本、状态转换和失败分类，但不包含敏感内容；
  • 日志、Crash 和诊断包执行同一套自动化敏感信息测试。

P1-03 修正线程、背压和句柄生命周期契约 ​

当前 Client 创建会同步打开/迁移数据库；Client 和 Subscription 的销毁依赖 调用方自行外部串行化。FFI 状态已使用非阻塞单泵有界 relay，Engine observer 不再等待 C Callback 队列；send 的 queued event 与 Completion 共用预留任务， 避免事件单独占满队列。ClientRuntime 的 普通命令/Task 已采用有界准入，受信任生命周期结果和终止控制可通过同一 Actor 的保留控制准入继续收敛；Engine 已受理流程的 Completion 和重连唤醒也使用其 串行 Worker 的控制准入。阻塞发送已经移动到专用 joinable Outbox I/O 线程， 账号撤销可以直接触达 cancel Port，不会排在阻塞发送之后。这些机制仍没有关闭 平台句柄、持久业务事件的通用重新查询/背压协议、分配失败时的 completion 保底和 Adapter 重入契约等缺口。Engine 回调执行器与 FFI 用户回调线程现已 分离，慢 C Callback 不会阻塞 Coordinator/Runtime/Outbox 的内部收束，但会按 合同延迟同一 Client 后续 C Event/Completion 的可见时间。当前合同要求 Callback 尽快返回且不得同步等待另一个 XHIM Callback；当前诊断快照可以发现 队列积压和拒绝增长，后续仍需补充可配置的慢回调监控和持久事件重新查询策略。

退出条件：

  • 长耗时存储、迁移和网络工作不得运行在 UI 线程或 Core Actor；
  • 事件背压采用合并、失效通知、暂停同步或重新查询策略，不能无限阻塞 Actor，也不能静默丢失持久变更；
  • 用户 Callback 阻塞不得阻止内部生命周期收束；若保持单 FIFO 回调线程，必须 明确定义可执行的超时、隔离和诊断策略；
  • Wrapper 提供幂等、线程安全的关闭语义和平台安全句柄；
  • 请求支持取消；销毁、回调内销毁、并发登出和平台进程终止均有压力测试。
  • 注入的 Transport cancel 与 Worker clock interrupt Port 必须明确禁止同步 重入同一个 Outbox Worker 或销毁其 Owner；若未来需要支持重入，必须把 外部 Port 调用移出 join 串行化临界区并增加对应死锁回归测试。

P1-04 建立 ABI、Wire 和 DB 兼容门禁 ​

退出条件：

  • 建立版本化 ABI 符号和布局 baseline，并在 CI 自动 diff；
  • 使用真实 Protobuf 生成代码执行 binary golden round-trip，而非只做文本结构校验；
  • iOS/macOS、Android/JVM、Windows/.NET、HarmonyOS/ArkTS 对大整数、bytes 和未知字段执行跨语言测试；
  • 每个已发布 DB Schema 都保留冻结 fixture；当前已冻结 v1-v12，后续 Schema 升级必须在同一提交加入新 fixture 和所有受支持旧版迁移测试；
  • 覆盖所有受支持旧版本升级、迁移中断、磁盘满、重复启动和新库拒绝旧 SDK 等场景；
  • 包内提供 SDK、Commit SHA、C ABI、Wire Protocol 和 DB Schema 版本清单。

P1-05 数据库恢复和本地数据保护 ​

当前内核连接已统一启用 5 秒有界 SQLite busy timeout：短暂的跨连接写竞争由 SQLite 等待，超时后仍以稳定 kBusy 返回，不会静默丢弃写入；生产集成继续 要求一个账号数据库只由一个 SDK 实例拥有，平台层不得直接打开数据库。

退出条件：

  • 迁移前执行可恢复备份或快照，并定义空间不足处理；
  • 启动执行有界完整性检查，发现损坏后隔离、脱敏诊断并保留可恢复数据；
  • 补齐多实例/多进程误用、长时间占锁和超时诊断的压力门禁；
  • 评估并选择成熟 SQLite 加密方案及其许可证、五端构建和性能；
  • 定义登出、换号、清缓存和卸载时各类数据的保留/删除策略。

P1-06 生产安全工程 ​

退出条件：

  • UUID、密钥和安全随机数使用平台 CSPRNG 或经审查的统一实现；
  • 减少凭证在普通 std::string、队列和临时对象中的复制，并在生命周期结束时可靠清理；
  • 增加 FFI、Proto、WebSocket Frame、数据库恢复和自定义 Payload 的 Fuzz；
  • 固定依赖和工具链版本，执行依赖漏洞、许可证和供应链扫描；
  • 完成独立安全评审和修复闭环。

P1-07 正式发布流水线 ​

退出条件：

  • CI 覆盖所有支持的 OS、CPU ABI、shared/static 和最低系统版本；
  • 产物可重复构建，并从同一已审查 Commit 生成；
  • 空白消费工程、示例 App、真机冒烟、符号检查和签名验证全部通过；
  • 生成 Release Notes、升级说明、校验和、SBOM 和签名；
  • 任何失败不得发布部分平台或不同内核版本的同一产品版本。

P1-08 建立 allocation-free emergency health latch ​

当前 Runtime、Coordinator、Engine 和 Outbox Worker 的普通失败路径使用结构化 Completion/Event，但这些对象和队列节点仍可能需要内存分配。进程级分配耗尽 时，noexcept 边界会 fail closed，可能无法再构造或投递最终 Completion、 Worker fault 或诊断字符串。现有“受支持 resource envelope”约束是诚实的能力 边界，不等于已经具备 OOM 下可观测的收敛保证。

当前 Engine 会先为已经送达的 Worker fault 撤销匹配的发送准入，并按账号 Epoch 本地锁存 CredentialRequired/Fatal；若 Coordinator 或下游 Runtime 未 实际应用凭证终止迁移，还会通过异步 acknowledgement 升级为 Fatal。该普通 resource envelope 内的锁存仍依赖 fault 已经被构造并调用到 sink，不能替代 本项要求的 allocation-free emergency latch。

退出条件：

  • 提供预分配或完全 allocation-free 的单向 emergency health latch，至少能 表达 resource_exhausted/fatal，且状态一旦置位不会被普通成功路径覆盖；
  • 平台 Facade 能通过不分配内存的 snapshot/poll 路径读取该状态，并停止继续 提交业务请求；
  • latch 不尝试在 OOM 后构造动态字符串、普通事件或再次扩容队列；
  • 增加确定性的分配失败注入测试，证明发送、凭证暂停、logout、shutdown 和 Worker fault 在无法投递正常回调时仍会 fail closed，且不会误报健康；
  • 文档明确区分正常资源 envelope 内的 exactly-once Completion 与进程级资源 耗尽时的 emergency 可观测性。

6. P2：Stable 质量与体验 ​

  • 网络 Chaos、长稳、进程强杀、系统时间跳变、代理/VPN 和高丢包测试；
  • 明确 CPU、内存、电量、启动时间、数据库体积和大群消息性能预算；
  • 完整 Quick Start、API Reference、错误码手册、迁移指南和废弃周期；
  • 五端示例工程、常见业务插件示例和后端联调工具；
  • UI Kit 主题、本地化、无障碍、深色模式和视觉回归；
  • 可选指标/遥测的用户授权、关闭开关、数据最小化和留存策略；
  • Alpha → Beta → Stable 的支持范围、SLA、回滚和紧急修复流程。

6.1 后续可选：实时音视频厂商接入 ​

实时语音/视频通话不随纯 IM 首版售卖承诺，现有 Call Actor、信令和 RTC Token 仅作为后续控制面基础保留。决定接入腾讯云、声网、ZEGO 或其他厂商时，必须：

  • 通过版本化 RTC Provider SPI 和独立平台 Call Bridge 接入，不修改消息内核 状态机，也不把厂商对象放进稳定 C ABI；
  • 交付至少一个生产 Provider 和确定性测试 Provider；
  • 单独完成五端权限、音频路由、后台/锁屏、来电 Push、NAT64/TURN、弱网、 跨端互通、录制提示、隐私、质量指标、SLA 与回滚验证；
  • 通过上述门禁后再作为独立可选商品/包发布，不回写为纯 IM 核心依赖。

7. 发布门槛 ​

7.1 Internal Prototype ​

允许：

  • 内核语义验证；
  • 使用 Fake/Mock Adapter 的自动化测试；
  • 单个平台的技术预研。

禁止：

  • 宣称可以连接生产后端；
  • 提供给无源码上下文的第三方作为正式 SDK；
  • 使用真实用户敏感数据。

当前源码成熟度可称为 0.1 Commercial/Source Beta；发行成熟度仍是内部受控 验证，NOT SALEABLE / NOT STABLE，直到对应 P0 制品、安全、法务和真机 证据全部关闭。

7.2 Developer Alpha ​

必须满足：

  • P0-01、P0-02、P0-03 和 P0-04 全部关闭；
  • 有可控测试后端和完整发送/同步闭环；
  • 至少一个平台的正式 Headless 包能被空白工程接入；
  • API、错误码和数据格式仍允许在 Release Notes 中明确标注变更；
  • 文档必须写明“Alpha，不承诺生产 SLA”。

7.3 Partner Beta ​

必须满足：

  • 所有 P0 关闭；
  • 所有 P1 有实现，或经评审记录少量不影响数据、安全和兼容性的例外；
  • 所有对外宣称支持的平台均提供包管理产物和真机证据；
  • 完成安全、隐私、法务和升级演练；
  • 至少一个外部合作方仅依赖发布包和公开文档完成接入。

7.4 Stable / Commercial ​

必须满足：

  • P0、P1 全部关闭且无未评估的高风险例外；
  • 支持矩阵、最低系统版本、兼容策略和 SLA 已冻结；
  • 最终包经过签名、SBOM、Hash、空白消费、真机和回滚验证；
  • 有正式安全响应、版本维护、废弃和紧急修复流程；
  • UI Kit 若随版本发布，必须有独立版本、兼容范围和可替换性验证。

8. 建议实施顺序 ​

按以下顺序推进，前一阶段接口未稳定前，不并行铺开五套 UI：

  1. 维护 XHIM 标识门禁并冻结稳定边界
    • 保持 Core 与 xihansoftware.com 平台技术标识冻结，并由正式证书/账号补齐 签名主体证据；
    • 明确商业包只承诺 C ABI 与原生 Facade；
    • 建立 ABI、Wire、DB 和 Build Info baseline。
  2. 封板已经接入的真实产品 Adapter
    • 保持现有 Backend/Store/Runtime/Coordinator/Transport/Worker 唯一组合根， 不在 FFI 或平台层复制发送、重连和 Sync 状态机；
    • Reference/Apple Adapter、真实网络 E2E 和凭证更新已经落地；下一步用 XHIM_ENABLE_LOCAL_PREVIEW=OFF 生成正式包，并补 KMS/撤销/弱网滚动演练；
    • 继续用 Fake Backend/Transport 做确定性故障测试，但不以此替代真实网络。
  3. 冻结服务端与 Wire 兼容合同
    • Bootstrap/Auth/Send/Sync/WS/Error 主链已落地；补齐 Capability、最低版本 和停用策略；
    • 用固定版本生成器复核/替换当前有界手写 C++ v1 Codec；
    • 完成 N/N-1/N-2、升级回滚和真实故障矩阵。
  4. 扩展可二次开发的公共 API
    • 已交付结构化错误和非敏感诊断快照；继续完成 Configuration、公共日志和 诊断包导出；
    • 已交付通用消息、会话/消息查询、重试/发送前取消、跨设备已读和通用 逐请求取消及五端 OfflineReader Facade；
    • 已交付五端自定义消息插件与 Renderer Registry；继续收紧通用 Extension ABI 边界。
  5. 把五端源码样板变成正式消费制品
    • 四套原生 Facade、Headless/UI 源码和 QuickStart 已落地；
    • 产出并签名 XCFramework/CocoaPods、AAR/Maven、DLL/NuGet、HAR/OHPM；
    • 每端用不访问源码的空白工程、真实设备和升级安装验证最终包。
  6. 补齐平台生产端口与一致性矩阵
    • 完成 Android Keystore、Windows DPAPI/reparse-safe cache、Harmony HUKS 等 Product Adapter，并复用同一 C ABI/contract tests；
    • 验证五端网络恢复、数据库加密、媒体、Push 和大序号一致性；
    • 禁止在 Wrapper 内复制消息状态机。
  7. UI Kit 与生产加固
    • UI 只依赖 Headless Facade；
    • 完成 emergency health latch、安全、数据库恢复、Chaos、性能、签名、 SBOM 和发布演练。

9. 单项关闭的 Definition of Done ​

任何 P0/P1 项目标记为完成前，必须同时满足：

  • 代码已经进入唯一生产路径，没有旁路或仅测试专用实现冒充正式实现；
  • 单元、集成、故障和至少一个下游消费测试通过；
  • 公共 API、线程、所有权、错误和兼容行为已有文档；
  • 不记录 Token、密钥、完整消息正文或完整 Cursor；
  • 对 ABI、Wire 或 DB 有影响时，baseline 和迁移测试已更新；
  • 最终打包产物已经被空白工程消费；
  • README.md 和本文件同步更新，不再保留过时的“已实现”表述；
  • 审查记录包含明确证据，而不是“理论可行”或“编译通过”。

10. 维护规则 ​

  • 每个 P0/P1 条目应在任务系统中拥有对应 Issue，并在合并请求中引用；
  • 新增平台、协议、数据库版本或对外 API 时，必须同步评估本文件；
  • 降低严重级别必须经过架构、安全和发布三方面评审；
  • 若当前实现与本文冲突，以更保守的发布结论为准；
  • 在所有 Stable 门槛满足前，对外统一表述为：

XHIM 当前为 Commercial Beta，可用于受控集成、二次开发和验收；在签名制品、 真机矩阵、安全/容量证据与法务审批全部通过前，不得作为 Stable 生产版本销售。

XHIM 客户端 SDK 与服务端文档

© 2026 晞晗软件 · Xihan Software