Document local SpacetimeDB dev skip and clear workflows

.hermes/shared-memory/pitfalls.md

@@ -83,6 +83,22 @@
 - 验证：`spacetime --root-dir server-rs/.spacetimedb/local list --server http://127.0.0.1:3101` 能看到目标库；重新发布不再使用无权限的全局 identity。
 - 关联：`scripts/dev-rust-stack.sh`、`docs/technical/SPACETIMEDB_START_SH_PUBLISH_403_IDENTITY_FIX_2026-04-26.md`。
 
+## 本地 SpacetimeDB 联调可按阶段跳过宿主或发布
+
+- 现象：本地 `npm run dev` 因 `3101` 已占用、重复发布 SpacetimeDB wasm 编译太慢，或只想检查 `spacetime-module` 语法而被完整联调链路拖慢。
+- 原因：`npm run dev` 默认同时启动 SpacetimeDB standalone、发布 `server-rs/crates/spacetime-module`、启动 Rust `api-server`、主站 Vite 与后台 Vite；并非每个阶段都需要完整重启和重新发布。
+- 处理：`3101` 已被可复用 standalone 占用时使用 `npm run dev -- --skip-spacetime`；未修改 `spacetime-module` 时使用 `npm run dev -- --skip-publish`；只查模块语法时执行 `cargo check -p spacetime-module --manifest-path server-rs/Cargo.toml`。
+- 验证：`--skip-spacetime` 后脚本复用现有 `http://127.0.0.1:3101`；`--skip-publish` 后不再进入 publish 阶段；`cargo check -p spacetime-module --manifest-path server-rs/Cargo.toml` 能完成 Rust 语法和类型检查。
+- 关联：`docs/technical/RUST_LOCAL_AND_REMOTE_DEPLOYMENT_SCRIPTS_2026-04-22.md`、`scripts/dev-rust-stack.sh`。
+
+## 本地 SpacetimeDB publish 401 可清本地库重发
+
+- 现象：本地 `spacetime publish` 显示 `401` 无权限，或重新发布仍像是在更新旧库。
+- 原因：本地开发 root-dir 中保留的数据库、控制库身份或发布身份与当前目标不一致。
+- 处理：确认本地开发数据可以丢弃后，执行 `spacetime --root-dir=server-rs/.spacetimedb/local server clear`，再重新运行 `npm run dev` 或本地 publish。
+- 验证：重新发布日志应显示创建新的数据库，而不是更新旧数据库；若仍显示更新或继续 `401`，继续检查 root-dir、库名和 CLI 身份。
+- 关联：`docs/technical/RUST_LOCAL_AND_REMOTE_DEPLOYMENT_SCRIPTS_2026-04-22.md`、`docs/technical/SPACETIMEDB_START_SH_PUBLISH_403_IDENTITY_FIX_2026-04-26.md`。
+
 ## Vite SPA fallback 吞掉 API 请求
 
 - 现象：本地请求 `/api/profile/*` 等接口时返回 HTML，被前端当 JSON 解析报错。