diff --git a/server-rs/crates/spacetime-client/src/game_distribution.rs b/server-rs/crates/spacetime-client/src/game_distribution.rs
index 51d5210cf..c026da2d2 100644
--- a/server-rs/crates/spacetime-client/src/game_distribution.rs
+++ b/server-rs/crates/spacetime-client/src/game_distribution.rs
@@ -1358,6 +1358,13 @@ impl SpacetimeClient {
         .await
     }
 
+    /// 统一发布一个版本，返回 `(game, version, replayed)`。
+    ///
+    /// 第三个返回值 `replayed` 表示这次请求命中了同一自然幂等键
+    /// `(game_id, idempotency_key, request_digest)`：服务端没有新建版本，回传的是既有作品与版本行。
+    /// 其中 `idempotency_key` 由 api-server 按 `(game_id, project_key, version_number)` 派生
+    /// （`version_number` 是客户端冻结的对外版本身份，`project_key` 只参与首次发布的作品身份派生），
+    /// `request_digest` 覆盖完整 metadata 与新图字节；同键异摘要会被拒绝，而不是静默重放。
     pub async fn publish_game_distribution_version(
         &self,
         input: GameDistributionPublishVersionRecordInput,