清理spacetimedb绑定生成

2026-04-26 20:41:11 +08:00
parent cbc27bad4a
commit f8ea3b704f
646 changed files with 4230 additions and 17557 deletions
--- a/docs/technical/API_SERVER_CHARACTER_VISUAL_EXTERNAL_GENERATION_RUNTIME_FIX_2026-04-23.md
+++ b/docs/technical/API_SERVER_CHARACTER_VISUAL_EXTERNAL_GENERATION_RUNTIME_FIX_2026-04-23.md
@@ -87,7 +87,7 @@
 4. 重新执行：

 ```powershell
-spacetime generate --no-config --lang rust --out-dir D:\Genarrative\server-rs\crates\spacetime-client\src\module_bindings --module-path D:\Genarrative\server-rs\crates\spacetime-module --include-private --yes
+npm run spacetime:generate
 ```

 说明：
--- a/docs/technical/AXUM_TO_SPACETIMEDB_ASSET_OBJECT_CONFIRM_CALL_DESIGN_2026-04-21.md
+++ b/docs/technical/AXUM_TO_SPACETIMEDB_ASSET_OBJECT_CONFIRM_CALL_DESIGN_2026-04-21.md
@@ -107,7 +107,7 @@
 ```bash
 spacetime start --listen-addr 127.0.0.1:3000
 spacetime publish genarrative-dev --server local --yes --module-path server-rs/crates/spacetime-module
-spacetime generate --lang rust --out-dir server-rs/crates/spacetime-client/src/module_bindings --module-path server-rs/crates/spacetime-module --include-private --yes
+npm run spacetime:generate
 ```

 ## 5. 为什么当前阶段不用 CLI 文本解析
--- a/docs/technical/M4_RPG_RUNTIME_STORY_SPACETIMEDB_BASELINE_2026-04-21.md
+++ b/docs/technical/M4_RPG_RUNTIME_STORY_SPACETIMEDB_BASELINE_2026-04-21.md
@@ -195,7 +195,7 @@
 1. `cargo check -p module-story --manifest-path D:\\Genarrative\\server-rs\\Cargo.toml`
 2. `cargo check -p spacetime-module --manifest-path D:\\Genarrative\\server-rs\\Cargo.toml`
 3. `cargo check -p spacetime-module --target wasm32-unknown-unknown --manifest-path D:\\Genarrative\\server-rs\\Cargo.toml`
-4. `spacetime generate --no-config --lang rust --out-dir D:\\Genarrative\\server-rs\\crates\\spacetime-client\\src\\module_bindings --module-path D:\\Genarrative\\server-rs\\crates\\spacetime-module --include-private --yes`
+4. `npm run spacetime:generate`
 5. `cargo check -p spacetime-client --manifest-path D:\\Genarrative\\server-rs\\Cargo.toml`
 6. `cargo check -p api-server --manifest-path D:\\Genarrative\\server-rs\\Cargo.toml`
 7. `npm run check:encoding`
@@ -234,7 +234,7 @@

 同时，本轮还完成了以下工程收口：

-1. 已重新执行 `spacetime generate --no-config --lang rust --out-dir D:\\Genarrative\\server-rs\\crates\\spacetime-client\\src\\module_bindings --module-path D:\\Genarrative\\server-rs\\crates\\spacetime-module --include-private --yes`。
+1. 已重新执行 `npm run spacetime:generate`。
 2. 已把 `spacetime-client` 中 battle query 的占位实现替换为真实 procedure 调用。
 3. 已再次执行 `cargo check -p spacetime-client --manifest-path D:\\Genarrative\\server-rs\\Cargo.toml` 与 `cargo check -p api-server --manifest-path D:\\Genarrative\\server-rs\\Cargo.toml` 并通过。

--- a/docs/technical/PUZZLE_CREATION_AND_RUNTIME_MINIMAL_IMPLEMENTATION_2026-04-22.md
+++ b/docs/technical/PUZZLE_CREATION_AND_RUNTIME_MINIMAL_IMPLEMENTATION_2026-04-22.md
@@ -340,7 +340,7 @@ finalScore = tagSimilarityScore * 0.7 + sameAuthorScore * 0.3;
 4. `cargo check -p module-puzzle`
 5. `cargo check -p shared-contracts`
 6. `cargo check -p spacetime-module`
-7. `spacetime generate --no-config --lang rust --out-dir server-rs/crates/spacetime-client/src/module_bindings --module-path server-rs/crates/spacetime-module --include-private --yes`
+7. `npm run spacetime:generate`
 8. `cargo check -p spacetime-client`
 9. `cargo check -p api-server`

--- a/docs/technical/RUST_LOCAL_AND_REMOTE_DEPLOYMENT_SCRIPTS_2026-04-22.md
+++ b/docs/technical/RUST_LOCAL_AND_REMOTE_DEPLOYMENT_SCRIPTS_2026-04-22.md
@@ -34,7 +34,7 @@ npm run dev:rust
 1. 检查 `cargo`、`node` 与 `spacetime` CLI。
 2. Windows Git Bash 下如 `server-rs/.spacetimedb/local/bin/current/spacetimedb-cli.exe` 不存在，先把本机 `spacetime` 所在安装目录的 `bin/` 与 `spacetime.exe` 同步到 `server-rs/.spacetimedb/local/`。
 3. 启动 `spacetime --root-dir=server-rs/.spacetimedb/local start --edition standalone --listen-addr 127.0.0.1:3101`，确保本地数据库与 SpacetimeDB 内部日志不会落到开发者全局目录。
-4. 等待 `spacetime --root-dir=server-rs/.spacetimedb/local server ping http://127.0.0.1:3101` 可用。
+4. 等待 `spacetime --root-dir=server-rs/.spacetimedb/local server ping http://127.0.0.1:3101` 可用；判定标准必须包含输出中的 `Server is online:`，不能只依赖 CLI 退出码，因为 SpacetimeDB CLI `2.1.0` 在 `502 Bad Gateway` 时也可能返回退出码 `0`。
 5. 执行 `spacetime --root-dir=server-rs/.spacetimedb/local publish <本地数据库名> --server http://127.0.0.1:3101 --module-path server-rs/crates/spacetime-module -c=on-conflict --yes`，确保 publish 的签名身份与 standalone 的本地控制库一致，并在当前开发阶段允许新版模块表结构变化且发生 schema 冲突时清除旧模块数据。
 6. 注入 `GENARRATIVE_API_*` 与 `GENARRATIVE_SPACETIME_*` 后启动 `cargo run -p api-server`；直接运行 `api-server` 时，如未显式设置 `GENARRATIVE_SPACETIME_DATABASE`，服务端也会向上查找 `spacetime.local.json` 作为本地默认库名。
 7. 等待 `http://127.0.0.1:<api-port>/healthz` 返回 HTTP 响应后再启动 Vite，避免前端初始化请求早于 Rust `api-server` 监听完成并在终端刷出 `ECONNREFUSED 127.0.0.1:<api-port>`。
@@ -65,6 +65,23 @@ npm run dev:rust
 ./scripts/dev-rust-stack.sh --preserve-database
 ```

+bindings 生成：
+
+```bash
+npm run spacetime:generate
+npm run spacetime:generate -- --rust-only
+```
+
+生成规则：
+
+1. `npm run spacetime:generate` 是本仓库刷新 SpacetimeDB Rust client bindings 的唯一推荐入口。
+2. 前端不直连 SpacetimeDB，不生成 TypeScript bindings；前端只通过 Rust `api-server` 暴露的 HTTP / SSE contract 访问后端。
+3. Rust bindings 不生成私有表绑定，不追加 `--include-private`，生成到短临时目录后同步到 `server-rs/crates/spacetime-client/src/module_bindings`。
+4. Windows 下 SpacetimeDB CLI `2.1.0` 会在生成结束后把所有生成文件路径一次性传给 formatter；Rust bindings 文件较多，若直接输出到仓库深目录，可能触发 `Could not format generated files: 文件名或扩展名太长。`。该错误不是单个最长文件路径超过限制，而是 formatter 子进程参数总长超过 Windows `CreateProcess` 限制。
+5. CLI 在上述 formatter 失败时仍可能返回退出码 `0`；脚本会捕获输出，只要出现 `Could not format generated files` 就视为失败。
+6. 根目录 `spacetime.json` 不配置 `generate` 目标，避免裸 `spacetime generate` 在 Windows 上直接碰到 Rust formatter 路径总长限制，也避免误生成前端 bindings。
+7. 不直接手写或局部补 `server-rs/crates/spacetime-client/src/module_bindings` 下的生成文件；schema 变化后重新执行本脚本，并补跑编码检查与对应类型检查。
+
 日志提取：

 ```bash
@@ -86,6 +103,7 @@ npm run dev:rust:logs -- --follow
 2. `spacetime --root-dir=server-rs/.spacetimedb/local list --server http://127.0.0.1:3101` 应能看到 `spacetime.local.json` 中的库名；若没有，执行 `spacetime --root-dir=server-rs/.spacetimedb/local publish <本地数据库名> --server http://127.0.0.1:3101 --module-path server-rs/crates/spacetime-module -c=on-conflict --yes`。
 3. 发布库名与 `GENARRATIVE_SPACETIME_DATABASE` 不一致时，`/api/runtime/custom-world-gallery` 会从 Rust `api-server` 返回 `502`，前端首页只能展示空态或错误提示，无法自行修复。
 4. 如果 Vite 输出 `/api/auth/refresh`、`/api/auth/login-options` 或 `/api/runtime/custom-world-gallery` 的 `ECONNREFUSED`，先确认当前脚本是否已经打印 `等待 api-server 就绪` 并通过；正常情况下 Vite 只会在 `/healthz` 可访问后启动，不应再因为 Rust 监听未完成而代理失败。
+5. 如果 `spacetime server ping` 打印 `Server could not be reached (502 Bad Gateway)`，即使命令退出码为 `0` 也必须视为未就绪；脚本会继续等待新启动实例，或在 root-dir 已被其他实例占用时输出占用进程。

 编译警告治理：

--- a/docs/technical/RUST_LOCAL_DEV_SPACETIMEDB_PUBLISH_GUARD_AND_AGENT_LLM_FAILURE_POLICY_2026-04-23.md
+++ b/docs/technical/RUST_LOCAL_DEV_SPACETIMEDB_PUBLISH_GUARD_AND_AGENT_LLM_FAILURE_POLICY_2026-04-23.md
@@ -48,7 +48,7 @@ spacetime publish xushi-p4wfr --server http://127.0.0.1:3101 --module-path D:\Ge
 publish 成功后，继续执行：

 ```bash
-spacetime generate --no-config --lang rust --out-dir D:\Genarrative\server-rs\crates\spacetime-client\src\module_bindings --module-path D:\Genarrative\server-rs\crates\spacetime-module --include-private --yes
+npm run spacetime:generate
 ```

 要求：
--- a/docs/technical/SPACETIMEDB_CUSTOM_WORLD_AGENT_SESSION_STAGE6_DESIGN_2026-04-22.md
+++ b/docs/technical/SPACETIMEDB_CUSTOM_WORLD_AGENT_SESSION_STAGE6_DESIGN_2026-04-22.md
@@ -164,19 +164,18 @@ Stage 5 已接入 agent `publish_world` action，但调用方仍需要显式提
 本仓默认刷新命令：

 ```bash
-spacetime generate --no-config --lang rust --out-dir server-rs/crates/spacetime-client/src/module_bindings --module-path server-rs/crates/spacetime-module --include-private --yes
+npm run spacetime:generate
 ```

-如果当前工作树里存在其他并行 `cargo build/test/check` 导致 `spacetime generate` 内部构建长期卡在锁竞争，则先在独立目标目录编译 wasm，再使用 `--bin-path` 生成：
+如果当前工作树里存在其他并行 `cargo build/test/check` 导致 `spacetime generate` 内部构建长期卡在锁竞争，则先结束占锁任务后重新执行仓库脚本；脚本内部会使用短临时目录生成公开 Rust bindings，不生成私有表绑定。

 ```bash
-CARGO_TARGET_DIR=server-rs/target-spacetime-bindgen cargo build --manifest-path server-rs/crates/spacetime-module/Cargo.toml --target wasm32-unknown-unknown --release
-spacetime generate --no-config --lang rust --out-dir server-rs/crates/spacetime-client/src/module_bindings --bin-path server-rs/target-spacetime-bindgen/wasm32-unknown-unknown/release/spacetime_module.wasm --include-private --yes
+npm run spacetime:generate
 ```

 这样做的目的固定如下：

-1. 避开根目录 `spacetime.json` 多 generate target 对单次 Rust 生成的参数冲突。
+1. 避开根目录 `spacetime.json` 误触发前端 bindings 或私有表 bindings 生成。
 2. 避开共享 `target/` 目录被其他任务占锁时的构建阻塞。
 3. 保证 `create_custom_world_agent_session` / `get_custom_world_agent_session` 这类新 procedure 与输入输出类型能同步进入 Rust bindings。