merge origin/master into codex/wechat-mini-program-virtual-payment

.hermes/shared-memory/decision-log.md

@@ -23,6 +23,13 @@
 - 影响范围：`src/services/payment/paymentPlatform.ts`、`src/components/rpg-entry/RpgEntryHomeView.tsx`、`miniprogram/pages/wechat-pay/`、`server-rs/crates/api-server/src/runtime_profile.rs`、`server-rs/crates/shared-contracts/src/runtime.rs`、`packages/shared/src/contracts/runtime.ts`、微信登录态存储。
 - 验证方式：泥点和会员商品在小程序运行态都请求 `wechat_mp_virtual`；小程序页能按 payload 调用 `wx.requestVirtualPayment` / `wx.requestPayment`；`cargo check -p api-server --manifest-path server-rs/Cargo.toml` 与支付相关前端测试通过。
 - 关联文档：`docs/【技术方案】微信虚拟支付接入-2026-05-26.md`。
+## 2026-05-30 Linux 本地 dev 端口段按系统级注册表分配
+
+- 背景：同一台 Linux 开发机上有多个用户同时跑 `npm run dev` 时，单纯靠各自 `GENARRATIVE_DEV_PORT_RANGE` 容易撞段，且同一用户并发起两个 dev 会话时也会把相同端口段重复拿走。
+- 决策：Linux 上的本地 dev 端口段分配统一收口到系统级注册表 `/var/tmp/genarrative-dev-port-ranges/registry.json`，锁文件为 `/var/tmp/genarrative-dev-port-ranges/registry.lock`，可通过 `GENARRATIVE_DEV_PORT_RANGE_REGISTRY_DIR` 覆盖目录。未手动指定时自动从 `10000-10099` 开始按 100 端口块分配，后续块按 `10100-10199`、`10200-10299` 递增；端口段映射固定为 `web = start`、`api = start + 1`、`spacetime = start + 2`、`admin-web = start + 3`；注册表会拒绝不同用户的相同或重叠段，并让同一用户后续启动继续复用自己已占用的固定段。`GENARRATIVE_DEV_PORT_RANGE` 与 `--port-range` 仍可手动指定端口段，但只在 Linux 生效，Windows 继续沿用原有端口探测与漂移逻辑，不读注册表。
+- 影响范围：`scripts/dev-stack-port-utils.mjs`、`scripts/dev.mjs`、`scripts/dev-stack-port-utils.test.ts`、`scripts/dev.test.ts`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`、本条决策记录、`development-workflow.md`。
+- 验证方式：`node --check scripts/dev-stack-port-utils.mjs`、`node --check scripts/dev.mjs`、`node node_modules/vitest/vitest.mjs run scripts/dev-stack-port-utils.test.ts scripts/dev.test.ts` 通过；Linux 下能看到 `[dev] port-range:` 与 `registry.json` 路径日志，自动分配从 `10000-10099` 起步，Windows 不出现注册表分配日志。
+- 关联文档：`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。
 
 ## 2026-05-27 生成页总进度圆弧锁定固定画布
 

.hermes/shared-memory/development-workflow.md

@@ -50,6 +50,8 @@ npm install
 npm run dev
 ```
 
+Linux 多用户共享同一台机器开发时，本地 dev 脚本会为当前 Linux 用户分配一个固定端口段并写入系统级注册表 `/var/tmp/genarrative-dev-port-ranges/registry.json`，自动分配从 `10000-10099` 开始，每段 100 个端口，四个 dev 服务依次使用 `start` 到 `start + 3`。可用 `GENARRATIVE_DEV_PORT_RANGE` 或 `npm run dev -- --port-range` 手动指定端口段用于特殊场景；注册表会阻止不同用户使用相同或重叠段，并让同一用户后续启动继续复用自己已占用的固定段。该机制只在 Linux 生效，Windows 仍沿用原有端口探测与漂移逻辑。
+
 该命令会启动：
 
 - SpacetimeDB standalone

.hermes/shared-memory/pitfalls.md

@@ -151,6 +151,14 @@
 - 验证：检查 `jenkins/Jenkinsfile.production-stdb-module-publish` 文件开头字节不再是 `EF BB BF`，并用 Jenkins `validateDeclarativePipeline` 或重放 `Genarrative-Stdb-Module-Publish`，不应再停在 `No such DSL method 'pipeline'`。
 - 关联：`jenkins/Jenkinsfile.production-stdb-module-publish`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。
 
+## Linux 多用户 dev 端口冲突先查系统级端口段注册表
+
+- 现象：同一台 Linux 机器上多个用户同时开发时，`npm run dev` 报端口段已被其他用户占用、同一用户已有活跃端口段，或 SpacetimeDB 复用记录指向当前用户端口段之外的地址；未手动指定时自动分配应从 `10000-10099` 起步。
+- 原因：Linux dev 脚本会通过 `/var/tmp/genarrative-dev-port-ranges/registry.json` 做系统级端口段分配，避免两个用户配置相同或重叠端口段；同一用户后续启动会继续复用自己已经占用的固定端口段。注册表会保留该用户的段记录，不会因为多开而要求重新分配。
+- 处理：先确认当前用户已经占用的端口段，再让后续 `npm run dev` / `dev:*` 继续沿用这段；如确实要切换段，手动释放或清掉对应 registry 记录后再重启。需要临时隔离测试时用 `GENARRATIVE_DEV_PORT_RANGE_REGISTRY_DIR=<tmp-dir>` 覆盖注册表目录。不要在 Windows 上按这个注册表排查，Windows 仍走原有端口探测与漂移逻辑。未指定端口段时，系统会从 `10000-10099` 开始顺序分配。
+- 验证：重新启动后终端应打印 `[dev] port-range: <start-end> (<user>)` 与 `[dev] port-range-registry: .../registry.json`；`node node_modules/vitest/vitest.mjs run scripts/dev-stack-port-utils.test.ts scripts/dev.test.ts` 应通过 Linux registry、自动分配 `10000-10099` 与 Windows bypass 用例。
+- 关联：`scripts/dev-stack-port-utils.mjs`、`scripts/dev.mjs`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。
+
 ## SpacetimeDB 入口迁移 helper 合并时不要只保留调用
 
 - 现象：`cargo check -p spacetime-module --manifest-path server-rs/Cargo.toml` 或 Jenkins `Genarrative-Stdb-Module-Build` 报 `E0425 cannot find function migrate_rpg_entry_from_old_hidden_default in this scope`，位置在 `server-rs/crates/spacetime-module/src/runtime/creation_entry_config.rs` 的默认入口配置播种流程。

.hermes/shared-memory/project-overview.md

@@ -1,6 +1,6 @@
 # Genarrative 项目共享概览
 
-更新时间：`2026-05-15`
+更新时间：`2026-05-29`
 
 ## 一句话定位
 
@@ -33,6 +33,8 @@ Genarrative / 陶泥儿是一个 AI 原生互动内容与小游戏平台，把 A
 server-rs + Axum + SpacetimeDB
 ```
 
+当前 SpacetimeDB crate、SDK、CLI / standalone、生成 bindings 和容器压测镜像统一按 `2.3.0` 对齐。
+
 职责边界：
 
 - `api-server`：HTTP / SSE / BFF 门面和外部副作用编排。

.hermes/skills/genarrative-dev-stack-port-routing/SKILL.md

@@ -34,6 +34,8 @@ metadata:
 
 端口不可用时，脚本会从优先端口开始向后寻找可用端口。后续流程必须以解析后的实际端口为准，不能继续使用默认端口。
 
+Linux 多用户并发开发时，`GENARRATIVE_DEV_PORT_RANGE` 或 `--port-range` 会先向系统级注册表 `/var/tmp/genarrative-dev-port-ranges/registry.json` 申请一个端口段，再把该段映射为 `web = start`、`api = start + 1`、`spacetime = start + 2`、`adminWeb = start + 3`。注册表锁文件是 `/var/tmp/genarrative-dev-port-ranges/registry.lock`，可通过 `GENARRATIVE_DEV_PORT_RANGE_REGISTRY_DIR` 覆盖目录。自动分配从 `10000-10099` 起，每次占用 100 个端口块，后续块按 `10100-10199`、`10200-10299` 递增；当前口径是“一个用户固定占用一个段，后续启动继续复用这段并在段内漂移”；该注册表只在 Linux 上生效；Windows 继续沿用原有端口探测、漂移和复用逻辑，不读系统级注册表。
+
 ## 实现入口
 
 - `package.json`
@@ -43,10 +45,12 @@ metadata:
   - `isPortAvailable(...)`：探测端口是否可监听。
   - `findAvailablePort(...)`：从优先端口向后寻找可用端口，`0` 表示申请临时端口。
   - `resolveDevStackPorts(...)`：一次性解析 SpacetimeDB、api-server、主站 Vite、后台 Vite 端口，并避免本次解析结果互相冲突。
+  - Linux 注册表分配：`reserveLinuxDevPortRange(...)` / `releaseLinuxDevPortRange(...)`，仅在 Linux 上启用系统级端口段登记与用户段复用，自动分配从 `10000-10099` 起。
   - CLI 模式：`node scripts/dev-stack-port-utils.mjs resolve-dev-stack spacetime:127.0.0.1:3101 api:127.0.0.1:8082 web:0.0.0.0:3000 adminWeb:127.0.0.1:3102`。
 - `scripts/dev.mjs`
   - 解析 CLI 参数后统一计算 client host、端口、`SPACETIME_SERVER`、`RUST_SERVER_TARGET`。
   - 完整栈按 SpacetimeDB、publish、api-server、主站 Vite、后台 Vite 顺序启动。
+  - Linux 下会先申请系统级端口段并把它映射成四个 dev 端口；自动分配从 `10000-10099` 起，Windows 则直接沿用原有参数解析与端口漂移逻辑。
   - 单模块命令复用同一套参数和 env 解析。
 
 ## 必须保持的传递链路
@@ -60,6 +64,7 @@ metadata:
 5. 主站 Vite：`RUST_SERVER_TARGET`、`GENARRATIVE_RUNTIME_SERVER_TARGET`、`ADMIN_WEB_TARGET`、`ADMIN_WEB_PORT`、`--port=${WEB_PORT}`、`--host=${WEB_HOST}`。
 6. 后台 Vite：`ADMIN_API_TARGET`、`GENARRATIVE_API_TARGET`、`GENARRATIVE_API_PORT`、`--port=${ADMIN_WEB_PORT}`。
 7. 控制台日志：`[dev:ports]` 和 `[dev] web/admin web/api-server/spacetime` 必须显示最终实际地址。
+8. Linux 端口段注册：`[dev] port-range:` 与 `[dev] port-range-registry:` 只在 Linux 输出，Windows 不应依赖系统级注册表。
 
 如果只改了其中一段，通常会出现：浏览器打开的前端可用，但 `/api/*` 代理到旧端口；后台页面可用但后台 API 失败；SpacetimeDB 启动在新端口但 publish 仍发往旧端口。
 
@@ -76,6 +81,7 @@ metadata:
 4. 修改 watch 时保持模块边界：SpacetimeDB 只监听 `spacetime-module` 且改动后重新 publish，不重启 standalone 宿主；api-server 排除 `spacetime-module`；web/admin-web 源码变化交给 Vite 自身 HMR，外层调度器不要再监听前端目录重启 Vite。
 5. 修改 `dev:web` 时不要自动改后端目标策略；`dev:web` 只负责主站 Vite 端口可用性与已有后端目标选择。
 6. 同步更新技术文档和团队共享记忆。
+7. 如果修改 Linux 端口段注册口径，确认 Windows 分支仍保持旧行为，不要把系统级注册表逻辑扩散到 Windows。
 
 ## 测试与验证
 
@@ -113,6 +119,7 @@ node scripts/dev-stack-port-utils.mjs resolve-dev-stack spacetime:127.0.0.1:0 ap
 ## 验收清单
 
 - [ ] 端口工具有测试覆盖端口被占用和多端口互斥解析。
+- [ ] Linux 注册表分配、同用户复用固定段并继续漂移、自动分配从 `10000-10099` 起、Windows bypass 都有测试覆盖。
 - [ ] `scripts/dev.mjs` 通过 `node --check`。
 - [ ] `npm run dev` 的 SpacetimeDB、publish、api-server、主站 Vite、后台 Vite 都使用实际端口。
 - [ ] `npm run dev:web` 在主站端口不可用时能切换到可用端口。