feat: allocate linux dev port ranges

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

@@ -16,6 +16,14 @@
 
 ---
 
+## 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 生成页总进度圆弧锁定固定画布
 
 - 背景：多轮圆环角度微调后，`GenerationProgressHero` 的 SVG 圆弧仍会出现底部开口偏斜的问题，且圆环还会随着容器宽度伸缩，导致 UI 看起来时大时小、位置漂移。

.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` 的默认入口配置播种流程。