Refactor local dev stack scheduler

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

@@ -1,7 +1,7 @@
 ---
 name: genarrative-dev-stack-port-routing
 short_description: 修改 Genarrative 本地 dev 启动端口、代理目标、端口冲突处理时使用。
-description: 在 Genarrative 中修改 npm run dev / npm run dev:rust / npm run dev:web 的本地启动端口、端口可用性探测、端口漂移、SpacetimeDB publish server、api-server 环境变量、Vite 代理目标和后台 admin-web 启动串联时使用。
+description: 在 Genarrative 中修改 npm run dev / dev:spacetime / dev:api-server / dev:web / dev:admin-web 的本地启动端口、端口可用性探测、端口漂移、SpacetimeDB publish server、api-server 环境变量、Vite 代理目标和后台 admin-web 启动串联时使用。
 version: 1.0.0
 author: Hermes Agent
 license: MIT
@@ -13,11 +13,11 @@ metadata:
 
 # Genarrative 本地 dev 启动端口与代理目标串联流程
 
-用于维护 Genarrative 本地开发栈启动脚本，重点覆盖 `npm run dev` / `npm run dev:rust` / `npm run dev:web` 的端口检查、端口漂移和后续流程目标传递。
+用于维护 Genarrative 本地开发栈启动脚本，重点覆盖 `npm run dev` 与四个 `dev:*` 单模块命令的端口检查、端口漂移和后续流程目标传递。
 
 ## 适用场景
 
-- 修改 `scripts/dev-rust-stack.sh`、`scripts/dev-web-rust.mjs`、`scripts/dev-stack-port-utils.mjs`。
+- 修改 `scripts/dev.mjs`、`scripts/dev-utils.mjs`、`scripts/dev-stack-port-utils.mjs`。
 - 处理 `3000`、`3101`、`3102`、`8082` 等端口被占用导致本地开发栈启动失败。
 - 排查 Vite 代理仍指向旧 api-server 端口、前端打开了旧 dev server、后台代理错配。
 - 调整 SpacetimeDB standalone、publish、Rust `api-server`、主站 Vite、后台 Vite 的启动顺序。
@@ -37,23 +37,21 @@ metadata:
 ## 实现入口
 
 - `package.json`
-  - `dev` 和 `dev:rust`：执行 `node scripts/run-bash-script.mjs scripts/dev-rust-stack.sh`。
-  - `dev:web`：执行 `node scripts/dev-web-rust.mjs`。
+  - `dev`：执行 `node scripts/dev.mjs`，启动完整四模块。
+  - `dev:spacetime` / `dev:api-server` / `dev:web` / `dev:admin-web`：执行 `node scripts/dev.mjs <module>`。
 - `scripts/dev-stack-port-utils.mjs`
   - `isPortAvailable(...)`：探测端口是否可监听。
   - `findAvailablePort(...)`：从优先端口向后寻找可用端口，`0` 表示申请临时端口。
   - `resolveDevStackPorts(...)`：一次性解析 SpacetimeDB、api-server、主站 Vite、后台 Vite 端口，并避免本次解析结果互相冲突。
   - 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-rust-stack.sh`
-  - 解析 CLI 参数后，先计算 `API_TARGET_HOST` 与 `ADMIN_WEB_TARGET_HOST`。
-  - 调用 `resolve_dev_stack_ports` 覆盖 `SPACETIME_PORT`、`API_PORT`、`WEB_PORT`、`ADMIN_WEB_PORT`。
-  - 再构造 `SPACETIME_SERVER` 和 `RUST_SERVER_TARGET`。
-- `scripts/dev-web-rust.mjs`
-  - 单独启动主站前端时，也先用 `findAvailablePort` 检查 `WEB_PORT` / 默认 `3000`。
+- `scripts/dev.mjs`
+  - 解析 CLI 参数后统一计算 client host、端口、`SPACETIME_SERVER`、`RUST_SERVER_TARGET`。
+  - 完整栈按 SpacetimeDB、publish、api-server、主站 Vite、后台 Vite 顺序启动。
+  - 单模块命令复用同一套参数和 env 解析。
 
 ## 必须保持的传递链路
 
-`npm run dev` / `npm run dev:rust` 中端口解析后，必须同步到以下位置：
+`npm run dev` 和四个 `dev:*` 单模块命令中端口解析后，必须同步到以下位置：
 
 1. SpacetimeDB 启动：`spacetime start --listen-addr "${SPACETIME_HOST}:${SPACETIME_PORT}"`。
 2. SpacetimeDB 发布：`spacetime publish ... --server "${SPACETIME_SERVER}"`。
@@ -61,7 +59,7 @@ metadata:
 4. api-server 健康检查：`wait_for_api_server "${RUST_SERVER_TARGET}/healthz" ...`。
 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:rust] web/admin web/rust api/spacetime` 必须显示最终实际地址。
+7. 控制台日志：`[dev:ports]` 和 `[dev] web/admin web/api-server/spacetime` 必须显示最终实际地址。
 
 如果只改了其中一段，通常会出现：浏览器打开的前端可用，但 `/api/*` 代理到旧端口；后台页面可用但后台 API 失败；SpacetimeDB 启动在新端口但 publish 仍发往旧端口。
 
@@ -69,17 +67,13 @@ metadata:
 
 1. 先读当前脚本和文档：
    - `scripts/dev-stack-port-utils.mjs`
-   - `scripts/dev-rust-stack.sh`
-   - `scripts/dev-web-rust.mjs`
-   - `docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`
+   - `scripts/dev.mjs`
+   - `scripts/dev-utils.mjs`
+   - `docs/technical/RUST_LOCAL_AND_REMOTE_DEPLOYMENT_SCRIPTS_2026-04-22.md`
    - `.hermes/shared-memory/pitfalls.md`
 2. 优先改公共端口工具，不要把端口探测逻辑复制到多个脚本。
-3. 对 Bash 脚本只做局部补丁，避免整文件重写导致中文注释或换行大面积变化。
-4. 修改 `dev-rust-stack.sh` 时确认变量顺序：
-   - 先有 `REPO_ROOT`。
-   - 再计算 `API_TARGET_HOST` / `ADMIN_WEB_TARGET_HOST`。
-   - 再调用端口解析工具。
-   - 再构造 `SPACETIME_SERVER` / `RUST_SERVER_TARGET`。
+3. 修改 `scripts/dev.mjs` 时确认变量顺序：先解析参数和端口，再构造 `SPACETIME_SERVER` / `RUST_SERVER_TARGET`，最后启动对应 service。
+4. 修改 watch 时保持模块边界：SpacetimeDB 只监听 `spacetime-module` 且改动后重新 publish，不重启 standalone 宿主；api-server 排除 `spacetime-module`；web/admin-web 源码变化交给 Vite 自身 HMR，外层调度器不要再监听前端目录重启 Vite。
 5. 修改 `dev:web` 时不要自动改后端目标策略；`dev:web` 只负责主站 Vite 端口可用性与已有后端目标选择。
 6. 同步更新技术文档和团队共享记忆。
 
@@ -88,7 +82,7 @@ metadata:
 最小验证：
 
 ```bash
-bash -n scripts/dev-rust-stack.sh
+node --check scripts/dev.mjs
 npm run test -- scripts/dev-stack-port-utils.test.ts
 npm run check:encoding
 node scripts/dev-stack-port-utils.mjs resolve-dev-stack spacetime:127.0.0.1:0 api:127.0.0.1:0 web:0.0.0.0:0 adminWeb:127.0.0.1:0
@@ -101,8 +95,8 @@ node scripts/dev-stack-port-utils.mjs resolve-dev-stack spacetime:127.0.0.1:0 ap
 3. 调用 `resolveDevStackPorts`，断言四个结果互不相同。
 4. 如果实际启动完整栈，观察控制台：
    - `[dev:ports] ... 不可用，改用 ...`
-   - `[dev:rust] rust api: http://...:<actual-api-port>`
-   - `[dev:rust] spacetime: http://...:<actual-spacetime-port>`
+   - `[dev] api-server: http://...:<actual-api-port>`
+   - `[dev] spacetime: http://...:<actual-spacetime-port>`
    - 主站和后台 Vite 启动端口与日志一致。
 
 完整启动属于长驻进程。需要 smoke 时用 background 方式启动，并另开命令检查 `/healthz`、`/v1/ping` 和页面端口；不要等待 `npm run dev` 自然退出。
@@ -119,9 +113,9 @@ node scripts/dev-stack-port-utils.mjs resolve-dev-stack spacetime:127.0.0.1:0 ap
 ## 验收清单
 
 - [ ] 端口工具有测试覆盖端口被占用和多端口互斥解析。
-- [ ] `dev-rust-stack.sh` 通过 `bash -n`。
-- [ ] `npm run dev` / `npm run dev:rust` 的 SpacetimeDB、publish、api-server、主站 Vite、后台 Vite 都使用实际端口。
+- [ ] `scripts/dev.mjs` 通过 `node --check`。
+- [ ] `npm run dev` 的 SpacetimeDB、publish、api-server、主站 Vite、后台 Vite 都使用实际端口。
 - [ ] `npm run dev:web` 在主站端口不可用时能切换到可用端口。
-- [ ] 文档同步更新 `docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。
+- [ ] 文档同步更新 `docs/technical/RUST_LOCAL_AND_REMOTE_DEPLOYMENT_SCRIPTS_2026-04-22.md`。
 - [ ] 长期踩坑同步更新 `.hermes/shared-memory/pitfalls.md`。
 - [ ] 修改中文文件后运行 `npm run check:encoding`。