Merge branch 'master' of http://82.157.175.59:3000/GenarrativeAI/Genarrative

2026-04-27 14:23:33 +08:00
parent fa2dbb310b 4ac2da5de1
commit ded6f6ee2a
50 changed files with 1908 additions and 270 deletions
--- a/docs/technical/BIG_FISH_CREATION_AND_RUNTIME_MINIMAL_IMPLEMENTATION_2026-04-22.md
+++ b/docs/technical/BIG_FISH_CREATION_AND_RUNTIME_MINIMAL_IMPLEMENTATION_2026-04-22.md
@@ -147,7 +147,7 @@

 ## 6. HTTP contract

-所有接口挂在 `/api/runtime/big-fish/*`，全部需要 Bearer 鉴权。
+所有接口挂在 `/api/runtime/big-fish/*`。创作、私有作品列表、删除、运行态启动与输入推进需要 Bearer 鉴权；公开广场读取接口不要求登录，只返回已发布作品。

 开发态本地链路补充约定：

@@ -191,12 +191,24 @@
 2. `GET /api/runtime/big-fish/runs/{runId}`
 3. `POST /api/runtime/big-fish/runs/{runId}/input`

+运行态启动规则：
+
+1. 当前用户启动自己未发布草稿时，`session.owner_user_id` 必须等于当前登录用户。
+2. 当前用户启动别人作品时，只允许启动 `stage = published` 的公开作品。
+3. 新建的 `big_fish_runtime_run.owner_user_id` 始终写入当前游玩用户，不能写入作品作者，后续 run 查询与输入推进仍按游玩用户隔离。
+
 ### 6.3 作品列表

 1. `GET /api/runtime/big-fish/works`

 开发态 Vite 必须把该同源接口代理到 Rust `api-server`；前端作品页只调用同源 `/api/runtime/big-fish/works`，不得直连 Rust 端口或回退到 `server-node`。

+### 6.4 公开广场
+
+1. `GET /api/runtime/big-fish/gallery`
+
+公开广场只返回 `status = published` 的大鱼吃小鱼作品。响应复用 `BigFishWorksResponse`，每个条目必须包含 `ownerUserId`，供前端生成稳定广场卡片 key 与后续运行态权限判断。发布动作完成后，前端必须同时刷新私有作品列表和公开广场列表，保证发布结果能立即出现在首页与分类页。
+
 `input` 请求体：

 ```json
@@ -242,6 +254,7 @@
 2. 发送聊天、action 和摇杆输入。
 3. 根据后端 snapshot 渲染实体。
 4. 当后端 snapshot 返回 `won` 或 `failed` 时，必须在玩法舞台中央显示清晰结算浮层；通关与失败都不能只依赖顶部状态标签或事件日志。
+5. 结算浮层必须提供可继续操作的出口：`failed` 至少包含“重来”和“退出”，`won` 至少包含“退出”。“重来”只能重新启动当前大鱼作品的一局后端 run，不能在前端本地篡改旧 run snapshot；“退出”回到当前作品结果页或直达入口的上级页面。

 前端禁止：

--- a/docs/technical/BIG_FISH_DIRECT_ROUTE_PLAYGROUND_2026-04-24.md
+++ b/docs/technical/BIG_FISH_DIRECT_ROUTE_PLAYGROUND_2026-04-24.md
@@ -20,6 +20,7 @@
 ## 验收口径

 1. 浏览器访问 `/big-fish` 后直接显示竖屏大鱼吃小鱼舞台。
-2. 左下摇杆可移动玩家实体。
+2. 屏幕任意位置按下并拖动可移动玩家实体。
 3. 玩家碰到不高于自身等级的实体后成长，并在事件日志显示成长结果。
-4. 左上返回按钮在直达页语义为重开当前占位局。
+4. 左上返回按钮在直达页语义为退出到平台首页。
+5. 直达页通关或失败后，结算浮层继续复用正式运行态出口；失败态点击“重来”重开本地占位局，点击“退出”回到平台首页。
--- a/docs/technical/BIG_FISH_RUNTIME_RULE_ENTRY_2026-04-26.md
+++ b/docs/technical/BIG_FISH_RUNTIME_RULE_ENTRY_2026-04-26.md
@@ -0,0 +1,33 @@
+# 大鱼吃小鱼运行页规则入口说明 2026-04-26
+
+## 背景
+
+大鱼吃小鱼玩法规则已经在 PRD 与运行态技术方案中定义，但网站运行页没有给玩家查看规则的入口。玩家进入 `/big-fish` 或正式运行页后，只能看到当前等级、状态和事件日志，无法在游玩前快速理解吞噬、合成、胜负条件。
+
+## 设计结论
+
+1. 规则入口放在运行页顶部操作区，使用 `CircleHelp` 图标按钮。
+2. 默认界面不直接铺规则长文案，点击按钮后打开独立模态窗口。
+3. 模态窗口只保留玩家决策所需的核心规则：
+   - 拖动方向控制移动。
+   - 吃掉低级或同级野生实体并收编。
+   - 碰到更高级野生实体时，己方实体会被吃掉。
+   - 3 个同级己方实体自动合成更高一级。
+   - 拥有最高等级后通关，己方实体归零后失败。
+4. 入口必须在移动端单手可点，不遮挡舞台主体。
+5. 规则内容只做说明，不参与任何前端裁决；真实规则仍以后端运行快照为准。
+
+## 落地范围
+
+1. `src/components/big-fish-runtime/BigFishRuntimeShell.tsx`
+   - 增加规则按钮与规则模态窗口。
+   - 复用 `UnifiedModal`，避免在当前玩法舞台内容流里展开说明。
+2. `src/components/big-fish-runtime/BigFishRuntimeShell.test.tsx`
+   - 覆盖规则入口打开与关闭。
+
+## 验收口径
+
+1. 进入大鱼吃小鱼运行页后，右上角可看到规则图标入口。
+2. 点击规则入口后出现独立弹窗。
+3. 弹窗能展示核心吞噬、合成、通关与失败规则。
+4. 关闭弹窗后回到玩法舞台，不改变当前运行快照。
--- a/docs/technical/FRONTEND_INDEPENDENT_PAGE_ROUTES_2026-04-25.md
+++ b/docs/technical/FRONTEND_INDEPENDENT_PAGE_ROUTES_2026-04-25.md
@@ -12,6 +12,7 @@
 - 正式主应用内部页面路径由 `src/routing/appPageRoutes.ts` 统一维护，不在组件里散落硬编码字符串。
 - `/puzzle` 与 `/big-fish` 保持为玩法调试直达入口；正式链路中的拼图和大鱼运行页使用 `/runtime/puzzle`、`/runtime/big-fish`，避免语义冲突。
 - 独立路径先解决页面阶段语义和浏览器前进后退；依赖运行中内存对象的详情页、结果页和运行页直接刷新后仍允许回退到平台首页或展示现有恢复态，不在本轮扩展资源 ID 深链加载。
+- `sessionStorage` 里的 RPG Agent 恢复指针只能在当前路径属于 `/creation/rpg/*`，或 URL 显式携带 `customWorldSessionId / customWorldOperationId / customWorldGenerationSource` 时生效；刷新平台首页、分类页、作品详情页时不能被本地残留指针强制跳到 `/creation/rpg/agent`。

 ## 页面路径表

@@ -46,3 +47,4 @@
 2. 从页面内切换到结果页、运行页或返回首页时，浏览器路径同步更新。
 3. 浏览器后退/前进能驱动 `selectionStage` 回到对应页面。
 4. `/puzzle` 与 `/big-fish` 仍进入原有玩法调试直达页。
+5. 仅有 `sessionStorage` 残留 RPG Agent 指针时，刷新 `/` 仍停留平台首页；刷新 `/creation/rpg/agent` 才恢复对应 Agent 工作区。
--- a/docs/technical/JENKINS_RUST_BUILD_DEPLOY_PIPELINES_2026-04-23.md
+++ b/docs/technical/JENKINS_RUST_BUILD_DEPLOY_PIPELINES_2026-04-23.md
@@ -8,7 +8,7 @@

 1. `构建`：只负责在仓库根目录执行 `npm run deploy:rust:remote -- --skip-upload`，生成发布包。
 2. `部署`：只负责把指定发布版本部署到 `/var/lib/jenkins/deploy/Genarrative/`，允许人工按参数启动，并支持按参数决定是否清空 SpacetimeDB 数据。
-3. `构建并部署`：先构建，再把构建出的版本号传给 `部署` 流水线并等待部署完成；同时暴露 `WEB_PORT` 参数，默认把发布包 Web 端口写成 `80`，并透传是否清库。
+3. `构建并部署`：先构建，再把构建出的版本号传给 `部署` 流水线并等待部署完成；同时暴露 `WEB_PORT` 参数，默认把发布包 Web 端口写成 `25001`，并把同名端口参数继续透传给下游部署，部署阶段以该参数作为最终监听端口。

 本次只补 Jenkins 编排与本地部署脚本，不改现有 Rust 发布包构建逻辑，不恢复旧 `server-node` 部署链。

@@ -24,6 +24,7 @@
 8. `部署` 流水线读取触发原因时必须使用 `currentBuild.getBuildCauses(...)` 这类白名单方法，不能直接访问 `currentBuild.rawBuild`，否则会被 Jenkins Script Security 拦截。
 9. 由于 Jenkins Pipeline 的 `build` 步骤触发下游时，原因类型通常是 `org.jenkinsci.plugins.workflow.support.steps.build.BuildUpstreamCause`，实现上需要同时兼容它和经典的 `hudson.model.Cause$UpstreamCause`，否则会把真实的上游触发误判成人工执行。
 10. 如果线上进程的启停必须经过 `sudo`，只允许 `start.sh` / `stop.sh` 这两个 hook 使用 `sudo -n` 执行，部署目录清空与文件覆盖仍保持普通权限。
+11. `WEB_PORT` 必须在 `构建并部署` 与 `部署` 两条流水线之间使用同名参数传递；部署脚本会把最终端口写入固定部署目录 `.env.local` 的 `GENARRATIVE_WEB_PORT`，避免 `sudo` 启动 hook 时环境变量被清理导致端口回退。

 ## 3. 节点与工作区要求

@@ -85,6 +86,7 @@ jenkins/Jenkinsfile.deploy
 scripts/jenkins-deploy-release.sh \
  --source-dir <SOURCE_WORKSPACE_ROOT>/build/<BUILD_VERSION> \
  --deploy-dir /var/lib/jenkins/deploy/Genarrative \
+  --web-port <WEB_PORT> \
  [--clear-database] \
  --hook-with-sudo
 ```
@@ -93,13 +95,13 @@ scripts/jenkins-deploy-release.sh \

 1. 若部署目录已有旧版本且存在 `stop.sh`，先执行旧版本 `stop.sh`。
 2. 只删除发布产物白名单中的旧文件，例如 `web/`、`api-server`、`spacetime_module.wasm`、`.env*`、`start.sh`、`stop.sh`、`web-server.mjs`、`README.md`。
-3. 将指定版本目录中的同名发布产物移动到部署目录。
-4. 如果 `CLEAR_DATABASE=true`，部署脚本会以 `./start.sh --clear-database` 启动新版本；这样发布阶段的 `spacetime publish` 会追加 `-c always`。
+3. 将指定版本目录中的同名发布产物复制到部署目录；文件产物使用普通复制，`web/` 等目录产物必须递归复制。
+4. 如果 `CLEAR_DATABASE=true`，部署脚本会以 `./start.sh --clear-database` 启动新版本；这样发布阶段的 `spacetime publish` 会追加 `-c=on-conflict`。
 5. 执行新版本 `start.sh`。

 如果 `RUN_DEPLOY_HOOKS_WITH_SUDO=true`，第 1 步和第 4 步会改为 `sudo -n` 调用；这要求 Jenkins 运行用户提前配置免密 sudo，否则部署会直接失败，不会进入交互式密码提示。

-这样可以满足“发布文件直接覆盖”的要求，同时保留部署目录里像 `spacetimedb-data/`、`logs/`、`run/` 这类运行态目录，不会因为部署被整体删除。发布白名单内的 `.env`、`.env.local` 仍会以构建产物中的文件为准；部署脚本会在启动 hook 前移除这些环境文件中的 UTF-8 BOM 与 CRLF，避免 `start.sh` 在 Bash 下把首行变量名误解析成命令。
+这样可以满足“发布文件直接覆盖”的要求，同时保留部署目录里像 `.spacetimedb/`、`logs/`、`run/` 这类运行态目录，不会因为部署被整体删除。发布白名单内的 `.env`、`.env.local` 会先以构建产物中的文件为准；部署脚本会在启动 hook 前移除这些环境文件中的 UTF-8 BOM 与 CRLF，并把 Jenkins 部署参数 `WEB_PORT` 写入 `.env.local` 的 `GENARRATIVE_WEB_PORT`，避免 `start.sh` 在 Bash 下把首行变量名误解析成命令，也避免端口配置只停留在上游构建阶段。`start.sh` 会先执行 Ubuntu 专用 `sync_ubuntu_spacetime_install`，优先从 `/usr/.local/share/spacetime/bin/<version>/spacetimedb-cli` 或 `$HOME/.local/share/spacetime/bin/<version>/spacetimedb-cli` 同步到部署目录 `.spacetimedb/bin/current/spacetimedb-cli`，后续启动、探活和 root-dir 占用判定都使用部署目录内 `.spacetimedb/`，且不再额外设置 `--data-dir`，避免 Jenkins 机器全局 `spacetime login` 变化影响本地库更新；如遇 `403 Forbidden`，按 `SPACETIMEDB_START_SH_PUBLISH_403_IDENTITY_FIX_2026-04-26.md` 排查数据库所有者与 CLI 身份。

 ### 4.3 构建并部署

@@ -115,12 +117,13 @@ jenkins/Jenkinsfile.build-and-deploy
 2. 复用与 `构建` 相同的构建命令生成 `build/<BUILD_VERSION>/`。
 3. 归档 `build/<BUILD_VERSION>/**`。
 4. 记录当前 `NODE_NAME`、源码根目录、版本号。
-5. 构建时额外透传 `--web-port <WEB_PORT>`，默认生成监听 `80` 的发布包。
+5. 构建时额外透传 `--web-port <WEB_PORT>`，默认生成监听 `25001` 的发布包。
 6. 触发 `部署` 流水线，并传递：
   - `BUILD_VERSION`
   - `SOURCE_WORKSPACE_ROOT`
   - `SOURCE_NODE_NAME`
   - `DEPLOY_DIRECTORY`
+   - `WEB_PORT`
   - `CLEAR_DATABASE`
   - `EXPECTED_UPSTREAM_JOB`

@@ -132,7 +135,7 @@ jenkins/Jenkinsfile.build-and-deploy
 2. `GENARRATIVE_WORKSPACE_ROOT`：源码根目录；为空时回退到 Jenkins 当前工作区。
 3. `BUILD_VERSION`：发布版本号；为空时回退到 `BUILD_NUMBER`。
 4. `RUN_NPM_CI`：是否在构建前执行 `npm ci`。
-5. `WEB_PORT`：发布包内静态网站监听端口；`构建并部署` 默认值为 `80`。
+5. `WEB_PORT`：静态网站监听端口；`构建并部署` 默认值为 `25001`，并通过下游 `部署` 同名参数作为最终启动端口。
 6. `CLEAR_DATABASE`：部署阶段是否清空 SpacetimeDB 数据后再发布 wasm；默认 `false`。

 如果当前 Jenkins 没有额外配置独立 Agent，而是直接在控制器自身执行任务，`AGENT_LABEL` 应填写 `built-in`。
@@ -147,6 +150,7 @@ jenkins/Jenkinsfile.build-and-deploy
 4. `CLEAR_DATABASE`
 5. `RUN_DEPLOY_HOOKS_WITH_SUDO`
 6. `EXPECTED_UPSTREAM_JOB`
+7. `WEB_PORT`

 其中仅 `构建并部署` 流水线还需要：

--- a/docs/technical/PUZZLE_BIG_FISH_DRAFT_PROGRESS_AND_ASSET_CHAIN_2026-04-25.md
+++ b/docs/technical/PUZZLE_BIG_FISH_DRAFT_PROGRESS_AND_ASSET_CHAIN_2026-04-25.md
@@ -43,6 +43,7 @@ RPG 在点击生成草稿后会离开聊天工作区，进入独立的生成进
 - 玩法特有的生成进度只通过 `beforeExecuteAction` 与 `onActionError` 这类回调接入：compile action 发起前切到独立生成页并初始化进度，失败时把进度置为 failed。
 - compile action 成功后继续由通用控制器切到结果页，页面层只补齐生成资产数量、拼图操作记录、作品架与广场刷新等玩法差异。
 - 离开玩法流程时，先清理运行态与生成进度态，再交给通用控制器恢复创作中心，避免流式回复和进度状态在下一次创作中残留。
+- 生成进度页的阶段文本、资产完成文本、草稿写回文本只属于进度读模型和结果页状态，不属于 Agent 聊天历史。后端 compile / asset action 不再追加 `action_result` 聊天消息；前端聊天气泡只展示 `kind === "chat" | "summary" | "warning"` 的消息，历史会话中已经存在的 `action_result` 只作为兼容数据保留，不再渲染。

 ## 验收点

@@ -50,4 +51,5 @@ RPG 在点击生成草稿后会离开聊天工作区，进入独立的生成进
 - 生成中可看到独立进度页，且进度步骤随 action 完成逐步推进。
 - 拼图结果页打开时已有正式图；大鱼结果页打开时主图、动作和背景资产均已写入 `assetSlots`。
 - 前端点击生成草稿时不串行调用多个资产 action；多阶段业务编排收敛在 `server-rs`。
+- 返回 Agent 工作区后，聊天区不出现“拼图结果页草稿已生成。”“本级主图已正式生成，可在结果页继续预览。”这类生成进度页状态消息。
 - 不新增 server-node 依赖，不复活 legacy public 静态资产路径。
--- a/docs/technical/README.md
+++ b/docs/technical/README.md
@@ -4,13 +4,11 @@

 ## 文档列表

- [PUZZLE_RUNTIME_DRAG_RESPONSE_FIX_2026-04-27.md](./PUZZLE_RUNTIME_DRAG_RESPONSE_FIX_2026-04-27.md)：记录拼图运行时拖动跟手延迟的前端根因，冻结 `requestAnimationFrame + DOM transform` 直写方案与不改玩法裁决边界。
- [ASSET_HISTORY_PUZZLE_COVER_KIND_FIX_2026-04-27.md](./ASSET_HISTORY_PUZZLE_COVER_KIND_FIX_2026-04-27.md)：记录资产历史接口补齐 `puzzle_cover_image` 白名单、错误文案与回归测试的修复口径。
- [PUZZLE_IMAGE_PROMPT_MODULE_EXTRACTION_2026-04-27.md](./PUZZLE_IMAGE_PROMPT_MODULE_EXTRACTION_2026-04-27.md)：记录拼图图片生成提示词从 `puzzle.rs` 拆到 `prompt/puzzle_image.rs` 的后端边界，保持 DashScope、OSS 与 SpacetimeDB 写回逻辑不变。
- [PUZZLE_IMAGE_ASSET_PROXY_FIX_2026-04-27.md](./PUZZLE_IMAGE_ASSET_PROXY_FIX_2026-04-27.md)：记录拼图生成图写入 `/generated-puzzle-assets` 后必须同步补齐 Axum 旧资源代理与 Vite dev proxy，避免结果页候选图和参考图读取链路失效。
+- [SPACETIMEDB_START_SH_EARLY_EXIT_DIAGNOSTICS_2026-04-27.md](./SPACETIMEDB_START_SH_EARLY_EXIT_DIAGNOSTICS_2026-04-27.md)：记录发布包 `start.sh` 只输出“SpacetimeDB 进程在就绪前退出”时的诊断补强，启动失败或超时时自动回显 `logs/spacetimedb.log`、`server ping`、端口监听和 root-dir 相关进程。
 - [RPG_AND_AGENT_CHAT_TRUE_SSE_STREAMING_2026-04-26.md](./RPG_AND_AGENT_CHAT_TRUE_SSE_STREAMING_2026-04-26.md)：记录 RPG 运行时 NPC 聊天、RPG/自定义世界 Agent 与大鱼 Agent 从“拼完整 SSE 字符串后一次性返回”改为 `mpsc + Sse<Event>` 真流式输出的后端落地口径。
- [RPG_SCENE_ACT_BACK_ROW_RUNTIME_PRESENTATION_FIX_2026-04-26.md](./RPG_SCENE_ACT_BACK_ROW_RUNTIME_PRESENTATION_FIX_2026-04-26.md)：记录多幕场景后排两个角色未进入幕预览和正式游戏画布的根因，冻结当前幕环境角色渲染、运行时场景 id 别名匹配与主角色优先相遇口径。
+- [SPACETIMEDB_START_SH_ROOT_OWNER_FALSE_POSITIVE_FIX_2026-04-27.md](./SPACETIMEDB_START_SH_ROOT_OWNER_FALSE_POSITIVE_FIX_2026-04-27.md)：记录发布包 `start.sh` root-dir 占用检测把 `grep -F .../.spacetimedb` 误判为 SpacetimeDB 实例的根因、脚本修复和现场处理方式。
 - [RPG_BATTLE_HEALTHBAR_AND_ACTION_PRESENTATION_FIX_2026-04-26.md](./RPG_BATTLE_HEALTHBAR_AND_ACTION_PRESENTATION_FIX_2026-04-26.md)：记录 RPG 战斗血条安全锚点、服务端战斗回包前端短表现，以及 `battle_use_skill` 指定技能兜底结算的修复口径。
+- [SPACETIMEDB_START_SH_PUBLISH_403_IDENTITY_FIX_2026-04-26.md](./SPACETIMEDB_START_SH_PUBLISH_403_IDENTITY_FIX_2026-04-26.md)：记录发布包 `start.sh` 执行 `spacetime publish` 遇到 `403 Forbidden` 的身份根因、`.spacetimedb/` root-dir 隔离修复和排查步骤。
 - [SPACETIMEDB_TABLE_CATALOG.md](./SPACETIMEDB_TABLE_CATALOG.md)：持续维护当前 SpacetimeDB 表目录，按领域说明每张表的作用、字段结构、索引和常用 `spacetime sql` 查询模板。
 - [RPG_OPENING_SCENE_ACT_IMAGE_PRESENTATION_SYNC_2026-04-26.md](./RPG_OPENING_SCENE_ACT_IMAGE_PRESENTATION_SYNC_2026-04-26.md)：记录开局场景与普通场景复用同一场景展示解析服务，修复列表幕缩略图和详情幕背景预览图片不一致的问题。
 - [FRONTEND_FIRST_LOAD_PERFORMANCE_FIX_2026-04-26.md](./FRONTEND_FIRST_LOAD_PERFORMANCE_FIX_2026-04-26.md)：记录网站启动后首次加载约三分钟的前端根因，收口 `RouteImageReadyGate` 首屏图片门控和 Vite dev 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
@@ -142,7 +142,7 @@ npm run deploy:rust:remote
 5. 执行 `cargo build -p spacetime-module --release --target wasm32-unknown-unknown --manifest-path server-rs/Cargo.toml`，并把 `spacetime_module.wasm` 复制到目标目录。
 6. 把仓库根目录的 `.env` 与 `.env.local` 分别复制到目标目录根部和目标目录的 `web/` 下；复制后统一移除 UTF-8 BOM 与 CRLF，避免目标服务器 Bash 加载环境文件失败。
 7. 在目标目录写入 `web-server.mjs`，用于托管 `web/` 并把 `/api/*`、`/generated-*`、`/healthz` 反代到本包内的 `api-server`。
-8. 在目标目录写入 `start.sh` 与 `stop.sh`；`start.sh` 会先按 `KEY=value` 子集加载发布目录根部的 `.env`、`.env.local`，兼容 UTF-8 BOM 与 CRLF，再回退到构建时通过 `--database`、`--api-port`、`--web-port`、`--spacetime-host`、`--spacetime-port` 写入的默认值，并默认导出 `NO_COLOR=1` 与 `CARGO_TERM_COLOR=never`，避免 ANSI 控制码写入日志文件；如果以 `--clear-database` 启动，则内部 `spacetime publish` 会追加 `-c=on-conflict`，仅在 schema 冲突时删除旧模块数据。
+8. 在目标目录写入 `start.sh` 与 `stop.sh`；`start.sh` 会先按 `KEY=value` 子集加载发布目录根部的 `.env`、`.env.local`，兼容 UTF-8 BOM 与 CRLF，再回退到构建时通过 `--database`、`--api-port`、`--web-port`、`--spacetime-host`、`--spacetime-port` 写入的默认值，并默认导出 `NO_COLOR=1` 与 `CARGO_TERM_COLOR=never`，避免 ANSI 控制码写入日志文件；同时按 Ubuntu 发布环境使用发布目录内 `.spacetimedb/` 作为 root-dir，不再额外设置 `--data-dir`，启动前先执行 `sync_ubuntu_spacetime_install`，优先从 `/usr/.local/share/spacetime/bin/<version>/spacetimedb-cli` 或 `$HOME/.local/share/spacetime/bin/<version>/spacetimedb-cli` 同步到 `.spacetimedb/bin/current/spacetimedb-cli`，当前线上 `spacetime` 入口为 `/usr/local/bin/spacetime`；启动参数为 `spacetime --root-dir ./.spacetimedb start --edition standalone --listen-addr <host>:<port>`，探活必须确认 `server ping` 输出包含 `Server is online:`；如果以 `--clear-database` 启动，则内部 `spacetime publish` 会追加 `-c=on-conflict`，仅在 schema 冲突时删除旧模块数据。
 9. 默认执行 `scp -r -i ~\.ssh\dsk.pem build/<timestamp> ubuntu@82.157.175.59:/home/ubuntu/genarrative/` 上传发布包。

 发布包结构：
@@ -178,7 +178,7 @@ cd build/<timestamp>
 ./stop.sh
 ```

-如果后续通过 Jenkins 的部署脚本把发布包覆盖到固定部署目录，部署阶段默认只替换 `web/`、`api-server`、`spacetime_module.wasm`、`.env*`、`start.sh`、`stop.sh`、`web-server.mjs`、`README.md` 等发布产物，不会删除部署目录中的 `spacetimedb-data/`、`logs/`、`run/` 这类运行态目录。
+如果后续通过 Jenkins 的部署脚本把发布包覆盖到固定部署目录，部署阶段默认只替换 `web/`、`api-server`、`spacetime_module.wasm`、`.env*`、`start.sh`、`stop.sh`、`web-server.mjs`、`README.md` 等发布产物；文件产物使用普通复制，`web/` 等目录产物递归复制，不会删除部署目录中的 `.spacetimedb/`、`logs/`、`run/` 这类运行态目录。

 安全边界：

@@ -187,8 +187,10 @@ cd build/<timestamp>
 3. `start.sh` 只解析合法 `KEY=value` 环境行，支持不加引号、双引号和单引号；不执行复杂 shell 表达式，避免把环境文件变成脚本入口。
 4. `start.sh` 默认不追加清理参数；只有显式执行 `./start.sh --clear-database` 才追加 `-c=on-conflict`，在 schema 冲突时清理旧模块数据后重发。
 5. `start.sh` 使用 `spacetime publish --bin-path spacetime_module.wasm --yes` 发布当前包内 wasm；清库模式下会追加 `-c=on-conflict`，仅在 schema 冲突时删除旧模块数据。
-6. 当前脚本是单目录进程启动方案，不替代生产 systemd、Nginx、TLS、日志轮转与守护进程配置。
-7. 如只需要本地生成发布包，可传 `--skip-upload` 跳过默认 scp 上传。
+6. `start.sh` 会先复用已经按目标地址就绪的 SpacetimeDB；如果同一个 `.spacetimedb/` root-dir 已被其他未就绪实例占用，则只输出命令名为 `spacetime` 或 `spacetimedb-cli` 且命令行包含当前 root-dir 的真实占用进程并失败，避免把排查用的 `grep` / `awk` 误判为 SpacetimeDB 实例。
+7. 如果 `spacetime publish` 报 `403 Forbidden`，优先确认 `spacetime --root-dir ./.spacetimedb login show` 输出的身份是否有权更新目标库；`--clear-database` 不能绕过身份授权。
+8. 当前脚本是单目录进程启动方案，不替代生产 systemd、Nginx、TLS、日志轮转与守护进程配置。
+9. 如只需要本地生成发布包，可传 `--skip-upload` 跳过默认 scp 上传。

 目标服务器最小要求：

--- a/docs/technical/SPACETIMEDB_START_SH_EARLY_EXIT_DIAGNOSTICS_2026-04-27.md
+++ b/docs/technical/SPACETIMEDB_START_SH_EARLY_EXIT_DIAGNOSTICS_2026-04-27.md
@@ -0,0 +1,75 @@
+# start.sh SpacetimeDB 就绪前退出诊断补强
+
+日期：`2026-04-27`
+
+## 1. 问题
+
+执行发布包内 `start.sh` 时，可能只看到：
+
+```text
+[start] 启动 spacetimedb
+[start] SpacetimeDB 进程在就绪前退出。
+```
+
+这条信息只能说明 `spacetime start` 子进程在 `server ping` 判定就绪前退出，不能直接说明根因。真实错误通常已经写入发布目录下的 `logs/spacetimedb.log`。
+
+## 2. 常见根因
+
+1. `GENARRATIVE_SPACETIME_PORT` 对应端口已被其他进程占用。
+2. `.spacetimedb/` root-dir 权限不正确，当前用户无法写入数据、bin 或日志目录。
+3. 目标机 `spacetime` 安装不完整，发布包同步不到可执行的 `bin/current/spacetimedb-cli`。
+4. 目标机上的 `spacetime` 版本与脚本启动参数不兼容。
+5. 旧 SpacetimeDB 进程仍持有同一 root-dir 或数据锁，但当前 `GENARRATIVE_SPACETIME_SERVER_URL` 指向的端口未就绪。
+6. `.spacetimedb/bin/current/` 下只有 `spacetimedb-cli`，缺少 `spacetimedb-standalone`，日志会显示 `exec failed for .../spacetimedb-standalone`。
+
+## 3. 落地修复
+
+发布包生成的 `start.sh` 调整为：
+
+1. 等待循环先执行 `server ping`，再检查启动进程是否退出，避免目标服务刚好已就绪但启动包装进程已退出时误报。
+2. `sync_ubuntu_spacetime_install` 不再只判断或复制 `spacetimedb-cli`，而是要求 `bin/current/spacetimedb-cli` 与 `bin/current/spacetimedb-standalone` 同时存在；从 Ubuntu 用户级安装目录同步时也复制完整版本目录。
+3. 当 SpacetimeDB 进程提前退出或等待超时时，自动打印：
+   - `GENARRATIVE_SPACETIME_SERVER_URL` 对应的目标地址。
+   - `GENARRATIVE_SPACETIME_HOST:GENARRATIVE_SPACETIME_PORT` 对应的监听地址。
+   - 当前 `GENARRATIVE_SPACETIME_ROOT_DIR`。
+   - `logs/spacetimedb.log` 最近 120 行。
+   - `spacetime server ping` 的原始输出。
+   - `ss` 或 `netstat` 中当前端口的监听情况。
+   - 同一 root-dir 下仍在运行的 SpacetimeDB 进程。
+
+## 4. 现场排查
+
+在发布目录中执行：
+
+```bash
+tail -n 120 logs/spacetimedb.log
+spacetime --root-dir ./.spacetimedb server ping "${GENARRATIVE_SPACETIME_SERVER_URL:-http://127.0.0.1:3101}"
+ss -ltnp | grep ':3101' || true
+```
+
+如果日志包含：
+
+```text
+exec failed for /var/lib/jenkins/deploy/Genarrative/.spacetimedb/bin/current/spacetimedb-standalone
+No such file or directory (os error 2)
+```
+
+说明发布目录的 SpacetimeDB root-dir 中同步了 CLI，但没有同步 standalone。现场可先执行：
+
+```bash
+cd /var/lib/jenkins/deploy/Genarrative
+SPACETIME_VERSION_DIR="$(find /usr/.local/share/spacetime/bin "$HOME/.local/share/spacetime/bin" -mindepth 1 -maxdepth 1 -type d 2>/dev/null | sort -V | tail -n 1)"
+test -x "${SPACETIME_VERSION_DIR}/spacetimedb-cli"
+test -x "${SPACETIME_VERSION_DIR}/spacetimedb-standalone"
+rm -rf .spacetimedb/bin/current
+mkdir -p .spacetimedb/bin/current
+cp -a "${SPACETIME_VERSION_DIR}/." .spacetimedb/bin/current/
+chmod +x .spacetimedb/bin/current/spacetimedb-cli .spacetimedb/bin/current/spacetimedb-standalone
+./start.sh
+```
+
+如果日志显示端口占用，先确认占用者是否就是旧的 SpacetimeDB。需要复用时，把 `GENARRATIVE_SPACETIME_PORT` 或 `GENARRATIVE_SPACETIME_SERVER_URL` 改成实际端口；需要重启时，优先执行同目录 `./stop.sh`。
+
+如果日志显示权限问题，先修复发布目录、`.spacetimedb/` 和 `logs/` 的所属用户，不要直接删除 `.spacetimedb/` 绕过问题。删除 `.spacetimedb/` 会同时影响本地 SpacetimeDB 数据与 CLI 身份，只能在确认本地库可丢弃时使用。
+
+如果日志显示身份或 `403 Forbidden`，继续按 `SPACETIMEDB_START_SH_PUBLISH_403_IDENTITY_FIX_2026-04-26.md` 处理；这类错误发生在发布阶段，不属于启动进程提前退出。
--- a/docs/technical/SPACETIMEDB_START_SH_PUBLISH_403_IDENTITY_FIX_2026-04-26.md
+++ b/docs/technical/SPACETIMEDB_START_SH_PUBLISH_403_IDENTITY_FIX_2026-04-26.md
@@ -0,0 +1,75 @@
+# start.sh 发布 SpacetimeDB 遇到 403 的处理方案
+
+日期：`2026-04-26`
+
+## 1. 问题
+
+执行发布包内 `start.sh` 时，`spacetime publish` 可能在 `Checking for breaking changes...` 后失败：
+
+```text
+Error: Pre-publish check failed with status 403 Forbidden: <identity> is not authorized to perform action on database <database-identity>: update database
+```
+
+这不是 wasm 构建失败，也不是 schema 冲突。错误含义是：当前 `spacetime` CLI 使用的身份无权更新目标数据库。
+
+## 2. 根因
+
+发布包 `start.sh` 会启动本地 SpacetimeDB，再把当前包内的 `spacetime_module.wasm` 发布到 `GENARRATIVE_SPACETIME_DATABASE`。
+
+SpacetimeDB 的数据库更新权限绑定到创建或被授权的身份。只要出现以下情况之一，就会触发 403：
+
+1. 部署机上执行 `start.sh` 的用户切换过 `spacetime login` 身份。
+2. 固定部署目录保留了旧 `.spacetimedb/`，但当前 CLI 身份不是旧数据库创建者。
+3. `GENARRATIVE_SPACETIME_SERVER_URL` 指向 Maincloud，而当前 CLI 身份不是该 Maincloud 数据库的所有者或授权成员。
+4. `.env.local` 中的 `GENARRATIVE_SPACETIME_DATABASE` 指向了另一个环境的数据库名或数据库 identity。
+
+## 3. 落地修复
+
+发布包生成的 `start.sh` 使用发布目录下的 `.spacetimedb/` 作为 SpacetimeDB root：
+
+```bash
+GENARRATIVE_SPACETIME_ROOT_DIR="${SCRIPT_DIR}/.spacetimedb"
+```
+
+启动、探活和发布统一使用：
+
+```bash
+spacetime --root-dir="${GENARRATIVE_SPACETIME_ROOT_DIR}" ...
+```
+
+`spacetime start` 不再额外设置 `--data-dir`，启动前会先执行 Ubuntu 专用 `sync_ubuntu_spacetime_install`，优先从 `/usr/.local/share/spacetime/bin/<version>/spacetimedb-cli` 或 `$HOME/.local/share/spacetime/bin/<version>/spacetimedb-cli` 同步到 `.spacetimedb/bin/current/spacetimedb-cli`；当前线上 `spacetime` 入口为 `/usr/local/bin/spacetime`。启动参数、探活和 root-dir 占用判定都使用同一个 `.spacetimedb/`。这样可以把发布包与部署机全局 `~/.spacetime` 隔离，避免后续人工 `spacetime login` 影响本地发布包。但如果旧 `.spacetimedb/` 已经由另一个身份创建，仍需要按第 4 节处理。
+
+## 4. 排查与处理
+
+先在执行 `start.sh` 的同一台机器、同一用户下确认身份：
+
+```bash
+spacetime --root-dir ./.spacetimedb login show
+spacetime --root-dir ./.spacetimedb list --server http://127.0.0.1:3101
+```
+
+如果目标是本地部署库，且允许清空本地数据：
+
+```bash
+./stop.sh
+mv .spacetimedb ".spacetimedb.backup.$(date +%Y%m%d-%H%M%S)"
+./start.sh
+```
+
+如果目标是本地部署库，但必须保留数据：
+
+1. 不要删除 `.spacetimedb/`。
+2. 找到创建该数据库的 SpacetimeDB 身份。
+3. 用该身份对应的 CLI root 执行发布，或在 SpacetimeDB 侧补授权后再发布。
+
+如果目标是 Maincloud：
+
+1. 执行 `spacetime login show` 确认当前身份。
+2. 确认该身份对 `GENARRATIVE_SPACETIME_DATABASE` 有更新权限。
+3. 如果只是连错库，修正 `.env.local` 中的 `GENARRATIVE_SPACETIME_DATABASE` / `GENARRATIVE_SPACETIME_SERVER_URL`。
+
+## 5. 约束
+
+1. `--clear-database` 只处理 schema 冲突时的数据清理，不会绕过 SpacetimeDB 身份授权。
+2. 不要通过切回旧 `server-node` 或 PostgreSQL 绕过发布错误。
+3. 前端与 `api-server` 的数据库名必须和 `start.sh` 发布的库名一致，否则后续接口会连到未发布或无权限的库。
--- a/docs/technical/SPACETIMEDB_START_SH_ROOT_OWNER_FALSE_POSITIVE_FIX_2026-04-27.md
+++ b/docs/technical/SPACETIMEDB_START_SH_ROOT_OWNER_FALSE_POSITIVE_FIX_2026-04-27.md
@@ -0,0 +1,44 @@
+# start.sh root-dir 占用误报修复
+
+日期：`2026-04-27`
+
+## 1. 问题
+
+执行发布包内 `start.sh` 时，可能出现：
+
+```text
+[start] 当前 root-dir 已被其他 SpacetimeDB 实例占用，无法再次启动。
+[start] 目标地址未就绪: http://127.0.0.1:3101
+root     2119763 2119760  0 09:06 pts/1    00:00:00 grep -F /var/lib/jenkins/deploy/Genarrative/.spacetimedb
+```
+
+此时执行 `sudo kill 2119763` 会返回 `No such process`。这是正常现象，因为该 pid 是一次性 `grep` 进程，日志打印出来时已经退出。
+
+## 2. 根因
+
+旧的占用检测逻辑使用：
+
+```bash
+ps -ef | grep '[s]pacetime' | grep -F "${SPACETIME_ROOT_DIR}"
+```
+
+第一段 `grep '[s]pacetime'` 能避开自己的 `grep` 命令，但第二段 `grep -F "${SPACETIME_ROOT_DIR}"` 的命令行会包含 `.spacetimedb` 路径。由于 `.spacetimedb` 本身含有 `spacetime` 字符串，第一段过滤会把第二段 `grep` 也当成命中的进程，最终误判 root-dir 已被占用。
+
+## 3. 修复
+
+占用检测改为读取 `ps` 的 `comm` 与 `args` 字段，仅当同时满足以下条件时才输出占用进程：
+
+1. 命令名是 `spacetime` 或 `spacetimedb-cli`。
+2. 完整命令行包含当前 `SPACETIME_ROOT_DIR`。
+
+这样既能定位真实持有同一 root-dir 的 SpacetimeDB 实例，也不会把 `grep`、`awk` 或其他排查命令误列为占用者。
+
+## 4. 现场处理
+
+如果日志里只看到 `grep -F .../.spacetimedb`，不要继续 kill 该 pid；它不是残留 SpacetimeDB。更新发布包中的 `start.sh` 后重新执行启动即可。
+
+如果新日志列出 `spacetime` 或 `spacetimedb-cli`，再按实际场景处理：
+
+1. 如需复用，确认该进程监听的端口，并把 `GENARRATIVE_SPACETIME_PORT` 或 `GENARRATIVE_SPACETIME_SERVER_URL` 改为实际地址。
+2. 如需重启，先执行同目录 `./stop.sh`；若该进程不是本目录脚本启动，再按列出的真实 pid 停止。
+3. 不要删除 `.spacetimedb/` 来绕过身份或数据问题；涉及 403 身份错误时继续按 `SPACETIMEDB_START_SH_PUBLISH_403_IDENTITY_FIX_2026-04-26.md` 排查。