合并 master 最新更新

合入 master 的 BgFilter、CI、运维与现役平台改造。保留 AI 游戏创作 Runtime、独立锁文件与原生壳验证链路。修复共享充值账单组件、LLM 网关与退役 Agent 兼容边界。同步冲突文档、锁文件和开发脚本。
2026-07-27 18:28:26 +08:00
parent 0ef5c2bb79 38c5a1a11a
commit 6bcd176bdf
1304 changed files with 170414 additions and 36096 deletions
@@ -28,6 +28,7 @@
 ### 后端与公开数据

 - [外部生成 Worker 化方案](./technical/【后端架构】外部生成Worker化方案-2026-06-03.md)
+- [BgFilter 受限资源调度方案（同步内部 HTTP 原地等待版）](./technical/【后端架构】BgFilter受限资源调度方案-2026-07-21.md)
 - [统一公开作品 Read Model 设计](./technical/【后端架构】统一公开作品ReadModel设计-2026-05-26.md)
 - [外部 OpenAPI 与 API Key 接入方案](./【后端架构】外部OpenAPI与APIKey接入方案-2026-06-19.md)
 - [SpacetimeDB 连接池取消安全](./【后端架构】SpacetimeDB连接池租约Drop兜底与取消安全-2026-06-11.md)
@@ -503,6 +503,9 @@
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
+          },
+          "409": {
+            "$ref": "#/components/responses/Conflict"
          }
        }
      }
@@ -1327,6 +1330,16 @@
          }
        }
      },
+      "Conflict": {
+        "description": "画布 revision 冲突，需重新读取最新快照后合并或重试",
+        "content": {
+          "application/json": {
+            "schema": {
+              "$ref": "#/components/schemas/ErrorResponse"
+            }
+          }
+        }
+      },
      "UpstreamError": {
        "description": "上游生成服务失败",
        "content": {
@@ -1755,8 +1768,17 @@
            "$ref": "#/components/schemas/EditorCanvasViewport"
          },
          "layers": {
-            "type": "object",
-            "description": "画布图层 JSON，最大约 256KB。"
+            "type": "array",
+            "items": {
+              "type": "object",
+              "additionalProperties": true
+            },
+            "description": "兼容画布布局 JSON，最大 2 MiB；服务端会拆分为结构化图层与生成对话框行。"
+          },
+          "expectedRevision": {
+            "type": "integer",
+            "minimum": 0,
+            "description": "可选的画布 revision CAS；不匹配时返回 409。"
          }
        },
        "additionalProperties": false
@@ -2110,7 +2132,11 @@
            "$ref": "#/components/schemas/EditorCanvasViewport"
          },
          "layers": {
-            "type": "object"
+            "type": "array",
+            "items": {
+              "type": "object",
+              "additionalProperties": true
+            }
          },
          "resources": {
            "type": "array",
@@ -2132,6 +2158,8 @@
          "title",
          "viewport",
          "layers",
+          "revision",
+          "layoutStorageVersion",
          "createdAt",
          "updatedAt"
        ],
@@ -2149,7 +2177,25 @@
            "$ref": "#/components/schemas/EditorCanvasViewport"
          },
          "layers": {
-            "type": "object"
+            "type": "array",
+            "items": {
+              "type": "object",
+              "additionalProperties": true
+            }
+          },
+          "revision": {
+            "type": "integer",
+            "minimum": 0
+          },
+          "layoutStorageVersion": {
+            "type": "integer",
+            "minimum": 0
+          },
+          "backgroundColor": {
+            "type": [
+              "string",
+              "null"
+            ]
          },
          "createdAt": {
            "type": "string",
@@ -114,6 +114,70 @@
 - 验证方式：确定性测试覆盖发现根、优先级、YAML/路径/符号链接/预算、metadata 清洗、正文按需可见和 fingerprint 漂移；正式 `openai_chat / gpt-5.5` 的 `project-skill` suite 必须证明 hash-only fixture 先失败、匹配 Skill 在首个变更前读取、无关 Skill 不读取、唯一目标文件修改、Agent 与宿主验证通过，以及 Provider lifecycle、唯一回复、配置隔离和零泄漏全部闭合。
 - 关联文档：`docs/technical/【技术方案】AI游戏创作Agent Runtime V1.1-2026-07-12.md`、`docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md`。

+## 2026-07-23 BgFilter 失败审计使用硬上限与独立 tracking outbox
+
+- 背景：BgFilter worker 每个已发出的失败 provider attempt 都会启动 detached 审计任务；专用 worker 又关闭了 tracking outbox，使任务逐条等待 SpacetimeDB。`Q` 只约束内部 HTTP 请求生命周期，响应结束后无法限制仍在等待数据库的审计任务，部分失败、预算截短 timeout、重试恢复和熔断重置场景下可能持续堆积。
+- 决策：BgFilter worker 的失败审计在 `tokio::spawn` 前统一获取进程级 `1024` 个硬上限 permit，满载时直接丢弃并记录低基数指标，不创建等待任务。获准任务优先写入 worker 独立 tracking outbox，目录固定派生为共享 `GENARRATIVE_TRACKING_OUTBOX_DIR` 下的 `bgfilter-worker/` 子目录；worker 启动 outbox flush worker，退出时先排空已获准审计 enqueue，再封存并尽力 flush。BgFilter 专用策略在 outbox 缺失、容量拒绝或写盘失败时丢弃并观测，不回退同步直写 SpacetimeDB；其它外部 API 审计保持原有 fallback 语义。
+- 影响范围：`api-server` BgFilter worker、外部 API 失败审计策略、tracking outbox 进程接线、指标与测试、BgFilter 架构和开发运维文档；不修改 SpacetimeDB schema、procedure、bindings、前端或公开 DTO。
+- 验证方式：覆盖 spawn 前容量拒绝、flat / complex 共享总上限、permit 生命周期、独立 outbox 目录、outbox 满载 / 写盘失败不直写、SpacetimeDB 不可用时任务与磁盘保持有界，以及退出时 tracker drain 后再 flush；运行 api-server 定向测试、BgFilter fault smoke、Rust check、编码和 diff 检查。
+- 关联文档：`docs/technical/【后端架构】BgFilter受限资源调度方案-2026-07-21.md`、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。
+
+---
+
+## 2026-07-22 BgFilter flat 与 complex 使用独立熔断状态
+
+- 背景：complex 请求在 provider 持续快速失败时仍会不断发起真实 provider attempt，并为每次已发出的失败生成异步审计；现有 flat 熔断不能约束 complex，且五分钟冷却会让短暂故障恢复后的等待过长。
+- 决策：把现有 flat 熔断行为按原语义复用到 complex。flat / complex 共享 `GENARRATIVE_EDITOR_BGFILTER_CIRCUIT_FAILURE_THRESHOLD=3` 与 `GENARRATIVE_EDITOR_BGFILTER_CIRCUIT_COOLDOWN_SECONDS=120`，但在唯一 `bgfilter-worker` 内分别维护独立的连续失败数和打开截止时间；真实 provider attempt 的失败或成功只更新当前模式。两种模式都在排队前及取得 provider permit 后、第一次真实 HTTP 前检查自身熔断；已经通过第二次检查的逻辑调用仍可完成自己的第二次顺序 attempt。complex 熔断仍直接使父流程失败，不获得 flat 的阿里云 / 本地 fallback；本次不修改失败审计的异步处理流程。
+- 部署边界：deploy / Provision 将 worker env 中历史模板默认 cooldown `300` 定向迁移到 `120`，其它显式自定义值保持不变；`bgfilter_circuit_state` 分别上报 `mode=flat` 与 `mode=complex`。
+- 影响范围：`api-server` BgFilter worker、熔断指标与测试、worker 环境模板、生产部署迁移门禁、BgFilter 架构和运维文档；不修改 SpacetimeDB schema、父业务 fallback、计费或失败审计流程。
+- 验证方式：覆盖两种模式状态隔离、阈值、成功重置、cooldown 到期、permit 前二次检查和部署默认值迁移；运行 api-server BgFilter 定向测试、生产部署脚本门禁、编码检查与 diff 检查。
+- 关联文档：`docs/technical/【后端架构】BgFilter受限资源调度方案-2026-07-21.md`、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。
+
+## 2026-07-21 BgFilter 首版采用单实例同步内部 HTTP 与父流程原地等待
+
+- 背景：角色动画在单个 `external_generation_job` 内通过 `buffer_unordered(frame_count)` 可并发发射最多 `48` 次 BgFilter 请求；限制父 worker 并发不能限制单个父 job 内的实际 BgFilter 并发。父 job checkpoint / continuation 和 SpacetimeDB 持久子任务都会扩大父状态机、attempt、计费、恢复和清理改动，而当前 BgFilter 成功结果本来就是 HTTP 图片二进制。
+- 决策：父 future 保持原调用栈、lease 和 attempt，等待期间继续占用通用 worker 槽并由现有 heartbeat 续租；所有调用统一同步请求唯一 `bgfilter-worker` 的内部 loopback HTTP。输入只传 OSS object key、参数、`maxQueueWaitMs / callBudgetMs` 和有界审计关联，成功直接返回经过校验的图片二进制。子 worker 使用有界 admission `Q` 和进程内 `Semaphore(N)`，负责最多两次顺序 provider attempt、flat 进程级熔断和失败审计；父流程继续负责 flat 降级、complex 失败、Alpha / 尺寸恢复、动画 finalizer、最终 OSS、业务写回、计费和父终态。
+- 超时边界：父 job 总预算仍为普通 `900s` / 长任务 `1800s`，并保留现有 `60s` 终态写回窗口。内部协议拆成互不挪用的 `maxQueueWaitMs` 与 `callBudgetMs`：前者由父剩余绝对预算扣除调用预算和父侧预留后派生，只限制等待 provider permit；flat 的 `39s` 父侧预留由 `37s` fallback（阿里云 `30s` + 本地 `7s`）与 `2s` 传输窗组成，complex 只留 `2s` 传输窗。后者从取得 permit 后起算，覆盖签名、最多两次 attempt、结果校验和响应构造。provider attempt 上限按 `N × est × 2` 派生，调用预算按 `2 × attempt + 1s` 派生；额外 `1s` 吸收 attempt 间开销，只要剩余时间仍能容纳完整 attempt 就不得先扣响应预留。父内部 client timeout 精确取 `maxQueueWaitMs + callBudgetMs + 2s`，不在发送阶段重新裁剪两笔相对预算。冻结 `N=16`、`est=5000ms` 时 attempt / callBudget 分别为 `160s / 321s`。动画删除旧的按帧数 timeout 增量，父侧不得在内部 timeout / 断连后重试整次 RPC。
+- 故障边界：首版不新增 `bgfilter_task_group`、`bgfilter_request_task`、raw OSS、checkpoint、continuation、数据库 capacity slot、共享熔断或 QPS token bucket。父或子进程崩溃、RPC 丢失时不查询、不恢复结果；父 job 沿用现有 lease / `max_attempts=1` 失败退款语义。动画首版保持所有已提交帧 collect / drain，不增加跨帧取消组。
+- 部署边界：专用进程首版仍复用完整 `AppState`，因此 systemd unit 先加载共享 `/etc/genarrative/api-server.env`，再加载 `/etc/genarrative/bgfilter-worker.env` 覆盖 worker 独占参数；父子共同依赖的 `N=16` 与 `est=5000ms` 必须来自共享基础环境，worker 专属环境只管理 flat 熔断参数和默认 `Q=2048` 保险丝。发布切换前校验父子使用同一个非空、非符号链接、`root:genarrative 0440` 的内部 Token 文件，并拒绝父子内部 URL、Token、连接参数、`N / est`、OSS bucket 或 endpoint 漂移（同 bucket 的独立 AK 允许）。worker 停机时立即拒绝仍在排队的请求，只排空已取得 provider permit 的调用；unit 使用 `TimeoutStopSec=900` 覆盖默认 `321s` 调用预算及响应收口。运行期巡检同时检查唯一 worker unit active 与 loopback readiness；本地 `npm run dev` 同样启动独立子进程并解析第五个 dev 端口，`ProcessRole::All` 不内嵌 listener。
+- 影响范围：已实施范围包括 `api-server` 内部 HTTP client、专用 `bgfilter-worker` listener / process role、并发与超时配置、部署和运维观测；未修改 SpacetimeDB schema、父 job schema、用户任务 DTO、任务列表或收费归属，当前待生产压测后启用。
+- 验证方式：`48` 帧并发进入父 future 时，健康唯一子 worker 进程持有的 BgFilter HTTP future 峰值不得超过生产显式配置的 `N`，且 `queued + running + egress` 不超过 `Q`（admission permit 持有到 response body 发送完成或 drop）；覆盖 flat / complex 降级矩阵、内部 deadline、断连后已启动请求排空、动画全帧 drain、External v1 / inline 旁路扫描、二进制大小 / MIME / 尺寸门禁、单实例部署、DDD、编码和 diff 门禁。
+- 关联文档：`docs/technical/【后端架构】BgFilter受限资源调度方案-2026-07-21.md`、`docs/technical/【后端架构】外部生成Worker化方案-2026-06-03.md`、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`。
+
+---
+
+## 2026-07-20 角色动作抠图前禁止透明 padding
+
+- 背景：图片画布角色动作此前在 BgFilter 前复用最终帧 finalizer，把 FFmpeg 抽帧先转成目标尺寸 RGBA 画布并用透明黑像素补边；透明区域进入 BgFilter、阿里云和本地键色共同读取的 OSS 源帧后，会干扰主体边缘判断并降低抠图质量。
+- 决策：仅图片画布角色动作链路在抠图前把 FFmpeg 帧转为 RGB8，按最终帧宽高的 contain 比例使用 `Triangle` 缩放到内容尺寸，不创建最终目标画布、不引入 Alpha、不插入 padding；该 RGB8 PNG owned 上传 OSS 后由三段抠图链共享。抠图返回后继续复用原最终帧 finalizer，转为 RGBA8、居中放入最终目标尺寸，并以 `RGBA(0,0,0,0)` 补边。`560×752 → 323×480` 的固定验收结果为 `323×434 RGB8` 抠图输入和上下各 `23px` 透明补边的 `323×480 RGBA8` 最终帧。
+- 补充（2026-07-21 实现收口）：转 RGB8 时若解码帧携带 Alpha 通道（共享 FFmpeg 抽帧命令不固定 `-pix_fmt`，源视频为 alpha 格式时 PNG 可能是 RGBA），必须先把像素按白底合成为不透明再转 RGB8（`flatten_alpha_onto_white_rgb`），禁止直接丢弃 Alpha——全透明像素下未定义的 RGB 值会以杂色进入抠图输入，重新引入本决策要消除的杂色边缘。该白底合成职责只属于图片画布角色动作的 BgFilter 输入准备阶段，不得为此在共享抽帧命令里固定像素格式。
+- 边界：不改变最终帧的 RGBA/padding 语义与透明帧格式、BgFilter 请求、OSS 上传与签名、抽帧数量和采样时间，也不改变旧 `/api/assets/character-animation/*` 动作发布链路；因为降级链复用同一个 object key，阿里云和本地键色同样读取新的无补边 RGB8 源帧。
+- 影响范围：`server-rs/crates/api-server/src/character_animation_assets.rs`、后端融合架构、角色动作专题和图片画布当前接入方案；不涉及 DTO、前端接口、SpacetimeDB schema 或运维配置。
+- 验证方式：像素测试断言 `560×752 RGB8 → 323×434 RGB8` 且无 Alpha/补边，并断言抠图结果最终成为上下各 `23px` 透明补边的 `323×480 RGBA8`；运行 `cargo test -p api-server character_animation --manifest-path server-rs/Cargo.toml`、`cargo check -p api-server --manifest-path server-rs/Cargo.toml`、`npm run check:encoding` 和 `git diff --check`。
+- 关联文档：`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`、`docs/【编辑器】画板角色形象生成入口设计-2026-06-15.md`、`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`。
+
+---
+
+## 2026-07-20 角色动画帧 OSS 请求使用专用连接池、并发保护与结构化重试
+
+- 背景：角色动作逐帧流水线会同时发起源帧 PUT、透明帧 PUT 和最终帧 HEAD；原路径每次请求新建 `reqwest::Client`，且 OSS 请求错误丢失 HTTP 状态和 timeout/connect/transport 分类，多个动画任务叠加时无法在进程级限制 OSS 在途请求，也无法安全区分 PUT 与 HEAD 的失败。
+- 决策：`AppState` 仅为角色动画帧初始化一次 OSS HTTP Client 和 8 路 `Semaphore`。全帧 Future 仍保持 `buffer_unordered(frame_count.max(1))`，BgFilter、阿里云抠图和本地处理不占 OSS permit；每次 PUT/HEAD 网络 attempt 单独获取 permit，退避期间释放。`platform-oss` 保留 `OssErrorKind::Request`，但在 `OssError::Request` 中保留 operation、status、timeout、connect、transport、OSS code、OSS request-id 和原脱敏 message，并为动画帧提供 3 次 attempt、250ms/500ms 退避的 PUT/HEAD 独立重试。仅无响应传输错误、timeout、OSS PutObject 的 `400 + RequestTimeout`、PUT 400 错误体读取失败（未解析出 `Code`，按 timeout/transport 归类）、408、429 和 5xx 可重试；动作帧 PUT 对 400 错误体最多读取 16 KiB，只提取 `Code` 和响应头优先的 `x-oss-request-id`，不记录完整 XML；错误体读取超时/断流时保留已读字节，已解析出的 `Code` 优先生效。除 `RequestTimeout` 与该错误体读取失败情形外的确定性 4xx、配置、签名、URL、空请求体、抠图和素材登记错误不重试。重试体在 platform-oss 内一次转为可复用 `Bytes`，每次重新签名和构造 Request，不复制整帧字节。
+- 失败语义：最终帧 PUT 成功后才执行 HEAD；HEAD 失败只重试 HEAD，不重复 PUT。任一帧最终失败仍排空已启动的 Future、整段动作退款并禁止发布缺帧动画，帧结果继续按原始序号排序。
+- 影响范围：`state.rs`、`platform-oss/lib.rs`、`character_animation_assets.rs`、对应 Cargo 依赖和架构 / 运维文档；不改变其他 OSS 调用方、BgFilter/阿里云降级、worker、计费退款、SpacetimeDB schema/DTO 或前端接口。
+- 验证方式：`cargo test -p platform-oss --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server character_animation --manifest-path server-rs/Cargo.toml`、`cargo check -p api-server --manifest-path server-rs/Cargo.toml`、`npm run check:encoding`、`git diff --check`。
+
+---
+
+## 2026-07-19 角色动作视频使用单进程批量抽帧
+
+- 背景：角色动作生成在拿到预览视频后，原实现会为 `32 / 40 / 48` 个采样点分别启动一次 FFmpeg、重复解码同一视频。release 的 2 vCPU 主机在一次 32 帧任务中因此出现约 10 秒的 CPU 尖刺，且进程启动和重复解码都不是业务必需开销。
+- 决策：角色动作抽帧必须先沿用 `compute_sample_time_seconds()` 计算全部采样点，再通过一个 FFmpeg filter graph 对输入统一 `setpts`、`split`，各分支按精确 `select=gte(t\,<target>)` 输出一帧。不得改用会漂移现有采样时刻的粗粒度 `fps` 抽帧。单次命令完成后逐一确认全部目标文件存在，任一缺帧继续使用原有用户错误文案，并在 details 中保留首个缺帧的 `targetSeconds / outputPath`、整批 `missingFrames` 和 stdout/stderr。视频封面等单帧调用保留兼容 helper，但内部复用同一批量实现。
+- 影响范围：`server-rs/crates/api-server/src/character_animation_assets.rs` 的角色动作视频本地抽帧和单帧视频封面抽取；不改变尾帧安全步长、BgFilter 并发、OSS 路径、帧编号、透明化后处理或前后端结果契约。
+- 验证方式：运行 `cargo test -p api-server editor_character_animation --manifest-path server-rs/Cargo.toml`，真实短视频回归必须由一次 FFmpeg 命令产出整批帧，并继续断言 `32帧·4秒` 最后一帧为 `3.875s`；追加 `cargo check -p api-server --manifest-path server-rs/Cargo.toml`、Rust 格式、编码和 diff 门禁。
+- 关联文档：`docs/【编辑器】画板角色形象生成入口设计-2026-06-15.md`、`docs/project-memory/shared-memory/pitfalls.md`。
+
+---
+
 ## 2026-07-18 图片生成 K 档由 provider 直接生成

 - 背景：旧 gpt-image-2 尺寸表会把 2K 竖版回落到 `1024x1536`，图标入口又使用固定 `360x360 / 512x512` 占位；角色去背景结果变小时还会直接放大整张透明成品，导致 UI 显示的 2K 与模型实际生成清晰度不一致。
@@ -178,6 +242,8 @@

 ## 2026-07-15 BgFilter 输入改用私有 OSS 短期签名 URL

+> 后续更正（2026-07-21）：复用 object key、通过 `image_url` 提交且不传 `file` 的协议语义保留，但 600 秒 OSS GET URL 的签发和 BgFilter provider multipart 调用已迁入唯一 `bgfilter-worker`。父流程只向内部 worker 发送一次 object key、参数和剩余预算，不签发 BgFilter URL，也不重试已被 worker 接收的内部 RPC（2026-07-23 起：连接从未建立的失败按调度方案 §5.1 有界重连，见当日决策条目）。下文保留作历史记录。
+
 - 背景：角色形象、图标图集、UI 素材图集、角色动作抽取帧和手动去背景在调用 BgFilter 前都已有私有 OSS object key；继续由 api-server 下载或保留图片并作为 multipart `file` 再上传，会重复传输图片字节并占用 API 进程网络与内存。
 - 决策：上述抠图链路统一复用 object key，签发 600 秒 OSS GET URL，并通过 BgFilter multipart 的 `image_url` 字段提交；请求中不再携带 `file`。签名 URL 只交给 BgFilter，不写日志或持久化。2026-07-17 起，生成原图和动作帧上传后不再保留图片字节；进入“阿里云通用抠图 → 本地键色”兜底链时按阶段从私有 OSS 重新下载。
 - 影响范围：`server-rs/crates/api-server/src/editor_project.rs`、`server-rs/crates/api-server/src/character_animation_assets.rs`、相关测试与文档；不改变 BgFilter endpoint、鉴权、`screen_color`、`seg_model`、输出校验、熔断规则、阿里云上传协议或降级顺序。
@@ -193,6 +259,8 @@

 ## 2026-07-15 角色动作 BgFilter 请求超时按帧数扩展

+> 后续更正（2026-07-21）：本条按帧数增加 timeout 的决策已被 2026-07-21「BgFilter 首版采用单实例同步内部 HTTP 与父流程原地等待」的公式化双预算取代。当前每帧分别携带 `maxQueueWaitMs` 与 `callBudgetMs`：排队预算只约束等待 provider permit，取得 permit 后才启动调用预算；provider attempt 按 `N × est × 2`、调用预算按 `2 × attempt + 1s` 运行时派生，冻结 `N=16`、`est=5000ms` 时为 `160s / 321s`，不再按 `32 / 40 / 48` 帧扩展。下文保留作历史记录。
+
 - 背景：角色动作全部序列帧会并发进入 BgFilter，而服务端可能在自身进程内排队；固定 `180000ms` 会把排队时间和单帧推理共用同一预算，靠后的请求可能在服务仍正常处理时被 api-server 提前取消。
 - 决策：保留 `GENARRATIVE_EDITOR_BGFILTER_REQUEST_TIMEOUT_MS` 作为统一基准值。只有角色动作逐帧 BgFilter 在共享 Client 的 RequestBuilder 上把每一次 HTTP attempt 覆盖为“基准值 + `2000ms × 本次实际帧数`”，默认 `32 / 40 / 48` 帧为 `244000 / 260000 / 276000ms`；角色形象单图、图标、UI 和手动去背景不增加帧预算。该 timeout 覆盖请求发起到响应体读取完成；首次失败后的重试重新获得同样的 request deadline，整批并发策略、失败排空语义和 worker long-job 总预算不变。
 - 影响范围：`server-rs/crates/api-server/src/editor_project.rs`、`server-rs/crates/api-server/src/character_animation_assets.rs`、后端架构、开发运维和图片画布专题文档。
@@ -201,6 +269,8 @@

 ## 2026-07-15 手动复杂去背景复用 BgFilter 单次重试

+> 后续更正（2026-07-21）：首次失败后再尝试一次、即同一次 complex 逻辑调用最多两次顺序 provider attempt 的语义保留，但重试所有权已迁入唯一 `bgfilter-worker`。父 `external-generation-worker` 至多让 worker 接收一次内部 HTTP RPC，不重试已被接收的 RPC（2026-07-23 起：连接从未建立的失败按调度方案 §5.1 有界重连，见当日决策条目）；两次 provider attempt 都失败时，子 worker 把最终类型化错误返回父流程，complex 仍不接入 flat 的阿里云 / 本地 fallback。下文所称“worker 重试”按此边界理解。
+
 - 背景：图片画布手动去背景已经改用 BgFilter `background_mode=complex`，但 worker 仍只发送一次上游请求，短暂网络抖动会直接让任务失败。
 - 决策：手动去背景的 complex 请求复用现有 `EDITOR_BGFILTER_RETRY_COUNT=1`，首次请求失败后立即重试一次，两次都失败仍返回最终错误；本次不把手动 complex 接入标准纯色背景链路的阿里云 / 本地兜底，也不改变 flat 路径的熔断状态。
 - 影响范围：图片画布手动去背景 worker、BgFilter complex 请求日志和 api-server 定向测试。
@@ -235,6 +305,8 @@

 ## 2026-07-13 角色动作 BgFilter 全帧流水线与单次重试

+> 后续更正（2026-07-23）：本条「每次 BgFilter 调用失败后立即重试 1 次」与「不新增供应商进程锁或全局 Semaphore」已被 2026-07-21 起的唯一 `bgfilter-worker` 架构取代。重试所有权迁入子 worker：对一次逻辑调用最多两次顺序 provider attempt，provider 并发由 worker 进程内 `Semaphore(N)`（生产 `N=16`）约束；父侧不重试已被 worker 接收的内部 RPC，仅 TCP 连接从未建立的失败按调度方案 §5.1 有界重连（见 2026-07-23「BgFilter 父侧连接失败有界重连与冷启动宽限」条目）。全帧独立流水化、失败排空与整任务失败退款的语义保留。下文保留作历史记录。
+
 - 背景：角色动作抽帧后原先固定 `buffered(3)`，并在整批绿幕源帧串行落 OSS 后才开始抠图；每帧还单独创建 HTTP Client。公网 BgFilter 的网络等待会让服务端推理队列出现空档，且首个最终错误会通过 `try_collect` 提前取消 api-server 中其余已发 Future。
 - 决策：BgFilter HTTP Client 在 `AppState` 中统一创建并复用 keep-alive 连接池；每次 BgFilter 调用失败后立即重试 `1` 次，两次都失败才进入既有“阿里云通用抠图 → 本地键色”降级链，每次已发失败调用都保留审计。角色动作全部 `32 / 40 / 48` 帧按“单帧绿幕源图落 OSS → BgFilter/降级 → 透明帧落 OSS”独立流水化，使用覆盖本次全部帧的 `buffer_unordered` 连续发射并携带原始帧序，完成后排序；不在 api-server 新增供应商进程锁或全局 Semaphore。任一帧最终失败时先排空全部已启动 Future，再让整个动作任务失败退款，不发布缺帧动画。
 - 影响范围：`server-rs/crates/api-server/src/state.rs`、`server-rs/crates/api-server/src/editor_project.rs`、`server-rs/crates/api-server/src/character_animation_assets.rs`、后端架构文档和图片画布技术文档。
@@ -254,6 +326,14 @@
 - 验证方式：`npm run check:database-backup`、`npm run check:production-ops`、`npm run check:encoding`、`git diff --check`；dev 现场必须完成逐文件 full catalog、重复 full 零 PUT、history dry-run、上传后清理、STDB 重启和按 catalog 隔离恢复 roundtrip。
 - 关联：<https://github.com/clockworklabs/SpacetimeDB/issues/5542#issuecomment-4981566448>。

+## 2026-07-27 逐文件备份本地元数据采用去重 state 与 gzip 保留
+
+- 背景：files v1 本地 state 同时在 `baselineCatalog`、`latestCatalog` 和每个 `historyCatalogs[]` 中嵌入完整文件清单，且每次成功 history 的本地 catalog 与 `--result-file` 再复制同一清单；release 独立 work-dir 已由此累积约 840 MiB JSON，但 OSS-only 恢复实际只依赖 `latest.json`、catalog 引用和 CAS 对象。
+- 决策：OSS catalog/latest schema、对象 key、序列化字节与恢复链保持不变。本地 state 升级为 gzip v2，只保存去重后的 catalog 引用；旧 v1 JSON 可读，并且只在非 dry-run 成功发布、验真 latest、原子写入 v2 后删除。full 增量复用从本地 latest full catalog gzip 缓存读取，缓存缺失时退化为逐对象 OSS HEAD，不影响正确性；缓存长度或 SHA 与 state 不一致时失败关闭。
+- 清理边界：成功运行后只压缩保留 latest full catalog；已验真的本地 history catalog、旧 full catalog和严格文件名匹配的失败/dry-run 遗留 catalog 清理。`--result-file` 只写紧凑引用和计数。任一 state 压缩或本地 metadata 清理失败都发生在 `/stdb` history 源文件删除之前；OSS catalog、latest 和 CAS 对象永不由本地 metadata 清理删除。
+- 兼容与验证：`--restore-files-state` 同时接受 v1 JSON 与 v2 gzip，`--restore-files-latest` 不受本地格式影响。门禁覆盖 v1 迁移、gzip/state/catalog 损坏拒绝、full 增量复用、history catalog 本地清理、紧凑 result、pointer 失败不清源和 OSS-only 恢复。
+- 关联：`scripts/database-backup-to-oss.mjs`、`scripts/check-database-backup-to-oss.mjs`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。
+
 ## 2026-07-14 后台账号采用 owner 引导账号与一级 Tab 实时授权

 - 背景：后台此前只支持一组环境变量管理员，所有 `/admin/api/*` 共用统一 admin 门禁，无法给运营、审核等人员分配独立账号和页面范围。
@@ -321,6 +401,14 @@
 - 验证方式：核对 `spacetime --version`，运行 `npm run spacetime:generate`、`npm run check:spacetime-schema`、`cargo check` / 定向测试、server provision 工具测试、encoding / diff 门禁。
 - 关联文档：`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。

+## 2026-07-23 SpacetimeDB 工具链统一升级到 2.7.0
+
+- 背景：SpacetimeDB 2.7.0 增加满足数据约束时的 unique / primary-key 非破坏迁移、Rust SDK capability traits、standalone MCP endpoint、SQL JSON 输出和更多连接/视图/内存指标，并修复旧 procedural-view backing table 的自动迁移。官方当前发行资产位于 `v2.7.0-hotfix3` 标签，二进制和 Rust crates 版本仍为 2.7.0。
+- 决策：`server-rs/Cargo.toml` 的 `spacetimedb`、`spacetimedb-sdk`、`spacetimedb-lib` 精确锁定 2.7.0；本地 CLI / standalone 与 Rust bindings 使用官方 2.7.0 hotfix3 构建，worker smoke 本地镜像按运行版本标记 2.7.0，官方容器和生产 provision 下载根固定到 `v2.7.0-hotfix3`。provision 从 hotfix 资产标签解析运行版本时必须得到 2.7.0，并同时核对 CLI commit 为 `d220349a...`；裸 tag `a08663c7...` 不得因版本号相同而被复用，下载 / 安装结果也必须通过同一 commit 门禁。
+- 影响范围：Rust workspace lockfile、SpacetimeDB bindings、本地 dev 版本门禁、容器 smoke / loadtest、server provision Jenkins 与项目 SpacetimeDB skills / 文档；现役 module 没有 procedural view，本次不修改 schema 或 migration。
+- 验证方式：核对 CLI 版本和 commit，重新生成 Rust bindings，运行 `npm run check:spacetime-schema`、相关 Cargo check、server provision 工具测试、容器配置、Rust 1.93 兼容检查、standalone `/v1/ping`、encoding 和 diff 门禁。
+- 关联文档：`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。
+
 ## 2026-07-10 外部生成任务只持久化轻量媒体引用并独立维护摘要投影

 - 背景：编辑器 worker 化后直接把同步接口 payload 序列化进 `external_generation_job.request_payload_json`；前端又把已有 OSS `objectKey` 下载成 Data URL 再提交，导致单个任务 JSON 膨胀到数 MB，正式任务列表读取 20 条任务时同时搬运约 65 MB payload，并放大为 SpacetimeDB 与 api-server 的瞬时内存峰值。此前“禁止 Data URL 持久化”只覆盖工程、素材、图层和元数据，遗漏了正式生成任务表。
@@ -492,7 +580,7 @@

 ## 2026-07-03 图片画布生成纯色背景资产接入 BgFilter

-> 后续更正：本条关于 multipart `file`、手动去背景独立 BiRefNet 配置以及 BgFilter 失败后直接本地兜底的描述，已分别由 2026-07-14、2026-07-15 OSS 签名 URL 决策和 2026-07-17 内存生命周期决策取代。下文保留作历史记录。
+> 后续更正：本条关于 multipart `file`、手动去背景独立 BiRefNet 配置以及 BgFilter 失败后直接本地兜底的描述，已分别由 2026-07-14、2026-07-15 OSS 签名 URL 决策和 2026-07-17 内存生命周期决策取代；其中固定 provider timeout 配置也已被 2026-07-21 的公式化双预算取代，当前请求分别携带 `maxQueueWaitMs / callBudgetMs`，attempt 按 `N × est × 2` 派生，冻结 `N=16 / est=5000ms` 时为 `160s`，调用预算为 `321s`。下文保留作历史记录。

 - 背景：独立 BgFilter 服务已部署在 image host，并提供 `POST /bgfilter/remove-background`，支持显式 `screen_color` 和 `seg_model`。手动去背景已有独立 BiRefNet BFF，不能把两个服务的配置或语义混在一起。
 - 决策：角色形象生成、图标 spritesheet 生成和 UI 设计图素材提取在保存带纯色背景源图后，统一调用 BgFilter 生成透明 PNG；请求 multipart 字段为 `file`、`screen_color=<screenColor>` 和内部固定的 `seg_model=birefnet`。`segModel` 虽是后端可识别的内部兼容字段（另保留 `anime-seg`），但不向用户或外部 OpenAPI 暴露：当前 BgFilter 的内存与并发容量不适合由调用方自由切换模型。BgFilter 使用独立配置 `GENARRATIVE_EDITOR_BGFILTER_BASE_URL`、`GENARRATIVE_EDITOR_BGFILTER_TOKEN`、`GENARRATIVE_EDITOR_BGFILTER_REQUEST_TIMEOUT_MS`，默认 base URL 为 `http://58.87.105.82/bgfilter`，默认请求超时 `180000ms`，token 未配置时复用 `GENARRATIVE_EDITOR_BACKGROUND_REMOVAL_TOKEN`。手动 `POST /api/editor/images/background-removals` 继续使用独立 BiRefNet 配置 `GENARRATIVE_EDITOR_BACKGROUND_REMOVAL_BASE_URL`，不受 BgFilter 影响。BgFilter 参数里的 `seg_model=birefnet` 只表示 BgFilter 内部分割后端，不等于手动去背景的独立 BiRefNet 服务。若 BgFilter 失败，api-server 对这些标准纯色背景生成图使用本地 `editor_green_screen` 兜底；连续失败达到 `GENARRATIVE_EDITOR_BGFILTER_CIRCUIT_FAILURE_THRESHOLD`（默认 `3`）后，`GENARRATIVE_EDITOR_BGFILTER_CIRCUIT_COOLDOWN_SECONDS`（默认 `300`）内直接本地兜底。角色动作背景色和抠帧口径已由 2026-07-09 决策取代：角色动作同样使用多色自动决策，抽帧后优先阿里云通用抠图，失败再按选定背景色本地兜底。更正（截至 2026-07-10 实现）：BgFilter 失败与熔断期本条描述的「直接本地兜底」已过时——角色形象/图标/UI 三条静态生图链路同样先走阿里云通用抠图，仅阿里云也失败才本地 `editor_green_screen` 兜底。
@@ -960,6 +1048,7 @@
 - 2026-06-20 桌面能力清单单测边界：Tauri `capabilities.rs` 必须用 Rust 单测同时覆盖桌面 runtime capability 清单顺序、无重复、真实桌面能力完整包含，并显式排除 `auth.requestLogin`、`payment.request`、`file.captureImage`、`scanner.scanQrCode` 和 `haptics.impact` 等未接入能力；桌面单端配置检查会反查该测试边界，避免只靠方案文档或共享 profile 发现桌面壳能力伪声明。
 - 2026-06-20 桌面本地通知契约镜像：Tauri `notification.showLocal` 的 title / body 归一化、长度上限和成功结果 action 必须镜像共享 HostBridge 契约；Rust 侧常量使用 `HOST_BRIDGE_LOCAL_NOTIFICATION_TITLE_MAX_LENGTH`、`HOST_BRIDGE_LOCAL_NOTIFICATION_BODY_MAX_LENGTH` 和 `HOST_BRIDGE_LOCAL_NOTIFICATION_DELIVERED_TO_SYSTEM_ACTION` 命名，桌面单端配置检查会与 `packages/shared/src/contracts/hostBridge.ts` 比对数值并反查成功结果由该 action 常量组装，避免通知 payload 边界变成桌面壳本地规则。
 - 2026-06-19 桌面壳外链打开 helper 共用：Tauri WebView 外域拦截和 HostBridge `app.openExternalUrl` 都必须复用 `open_normalized_desktop_external_url` 执行系统外链打开动作；HostBridge 分支仍先用 `normalize_external_url` 保留 payload 错误语义并把 opener 错误回传给 H5，WebView 拦截保持 best-effort 静默处理。桌面壳配置检查会拒绝 `dispatch.rs` 直接调用 `app.opener().open_url` 绕过该 helper，避免两条离壳路径漂移。
+  > 2026-07-18 覆盖说明：本段后续关于微信 `navigation.openNativePage`、生成结果订阅页、`[subscribe-message]` 日志和订阅页路由门禁的 2026-06 决策均已由旧创作模板退役决策废止，只作为历史记录。Expo / Tauri 的同源 H5 受控导航及微信登录、支付、分享能力继续有效。
 - 2026-06-20 H5 原生导航预校验：`navigateHostNativePage()` 在 `native_app` 下发送 `navigation.openNativePage` 前必须先拒绝空值、控制字符、协议相对 URL、外域绝对 URL 和非 `http:` / `https:` 协议目标；同源绝对 URL、`/path` 和保留给桌面壳兼容的相对 route 继续交给 Expo / Tauri 壳二次归一并补写宿主上下文。微信小程序分支仍按小程序页面 URL 语义走 `wx.miniProgram.navigateTo`，不套原生 App 同源 H5 预校验。根级 `npm run check:native-shells` 会反查 H5 facade 仍使用 `normalizeNativeAppPageUrl(...)` 且发送归一后的 URL，避免明显不安全目标触达原生壳。
 - 2026-06-20 微信受控原生页能力声明：微信小程序壳真实 capability profile 声明 `navigation.openNativePage`，用于承接已经登记并测试的小程序原生页 flow；当前订阅生成结果通知页通过 H5 `requestGenerationResultSubscribePermission()` 调用 `navigateHostNativePage()` 打开 `/pages/subscribe-message/index`，小程序页再调用真实 `wx.requestSubscribeMessage` 并按既有结果协议回灌。根级 `npm run check:native-shells` 必须把该能力反查到共享 profile、微信 `WECHAT_HOST_CAPABILITIES` 镜像、订阅页协议常量、H5 入口、小程序 host-bridge / shell / page 文件和相关测试；该能力不代表开放任意小程序页面跳转。
 - 2026-06-18 能力声明收紧：`packages/shared/src/contracts/hostBridge.ts` 提供 HostBridge method / capability 白名单，H5 的 `getHostRuntime()` 会解析并过滤 `hostCapabilities`；`openHostShare`、`writeHostClipboardText`、`requestHostHapticsImpact`、`setHostAppTitle`、`exportHostTextFile` 等 native 能力只在宿主声明对应 capability 后调用。发布分享弹窗只有声明 `share.open` 时才显示受控分享动作，并按 `hostShell` 区分 Expo 系统分享面板和 Tauri 剪贴板复制表达，避免旧壳或裁剪壳露出不可用入口。
@@ -1088,6 +1177,8 @@

 ## 2026-06-17 H5 宿主壳能力统一走 HostBridge

+> 2026-07-18 覆盖说明：以下订阅授权、订阅页和旧玩法导航部分已退役；登录、支付、分享、九宫切图与通用 HostBridge 分层仍有效。
+
 - 背景：主站同时运行在普通浏览器、微信小程序 `web-view` 和未来可能出现的原生 App WebView 中；登录、支付、分享、订阅授权和运行态分享目标同步曾散落在业务组件与服务文件里，后续新增宿主壳会导致同一业务重复分叉。
 - 决策：前端宿主运行态识别、微信小程序 JS SDK 加载、原生页跳转、支付跳转、登录跳转、九宫切图和 `postMessage` 统一收口到 `src/services/host-bridge/hostBridge.ts`，业务层优先调用 `getHostRuntime`、`requestHostLogin`、`requestHostPayment`、`navigateHostNativePage`、`setHostShareTarget` 和 `openHostShareGrid`。`authService`、分享服务、订阅授权和个人中心充值可保留兼容导出或业务编排，但不再自行加载微信 JS SDK 或直接判断 `wx.miniProgram`。固定内置玩法不走代码包下载流程；AI 生成 H5 沙箱后续单独定义受限 `GameBridge`，不得直接暴露完整 `HostBridge`。
 - 影响范围：`src/services/host-bridge/`、`src/services/authService.ts`、`src/services/payment/paymentPlatform.ts`、`src/services/wechatMiniProgramShareGrid.ts`、`src/services/wechatMiniProgramShareTarget.ts`、`src/services/wechatMiniProgramSubscribe.ts`、`src/components/platform-entry/usePlatformProfileCenterController.ts`、微信小程序壳和未来原生 App 壳接入。
@@ -1903,7 +1994,7 @@
 ## 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 继续沿用原有端口探测与漂移逻辑，不读注册表。
+- 决策：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`，2026-07-21 按顶部 BgFilter 决策扩展 `bgfilter-worker = start + 4`；注册表会拒绝不同用户的相同或重叠段，并让同一用户后续启动继续复用自己已占用的固定段。`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`。
@@ -5338,3 +5429,98 @@
 - 并发补验：确定性 Provider 只在 Runtime 明确返回 revision blocker、专业 verification-only repair、成功验证 observation，或项目锁 / repository context drift 这两类可恢复 observation 时重放终态；每个 logical run 最多 16 次。只读职责不得借补验调用未授权命令，验证失败或缺少 `ok` observation 不能交付，Provider completion 计数始终 exactly-once。
 - 画布审计：资源 manifest 可以保留生成 prompt 作为本地来源元数据，但公开 `asset.register / asset.update` 审计记录必须移除 `source.prompt`，只保留 canvas/resource/task/model 等身份字段，避免完整生成正文进入公开 Agent DB 表面。
 - 当前测试事实：已有回归覆盖固定画布合同不允许被模型改写、已登记 spritesheet 禁止先删除、只有静态 repair 可原位替换、替换期间原文件 fingerprint 漂移时拒绝覆盖，以及 `design-foundation` 对 `game/index.html` 的 write / patchset / delete 和预览工具均被 Runtime 策略阻断。2026-07-27 的独立 75 分钟上限外部真实 E2E 已按上一节单轮证据完整 **PASS**；后续合同变化仍须新起独立轮次，不能复用这次结果替代未来验收。
+- 最终落地：本次退役范围覆盖整个旧创作模板体系，包括 RPG / 自定义世界、拼图、拼消消、大鱼吃小鱼、敲木鱼、方洞挑战、视觉小说、汪汪声浪、寓教于乐、Creative Agent、Match3D、跳一跳和儿童动作 Demo。全部相关历史表继续作为数据壳参与 `spacetime-module` 编译，`migration.rs` 白名单与历史数据不变；旧 reducer/procedure/view、API 路由/handler/worker、前端页面/工作台/运行态、共享业务 DTO 和纯业务 crate 从编译链与依赖图移除，但旧源码和素材保留在仓库中用于历史追溯。
+- 兼容读取：只保留历史审计、迁移和资产归属核对所需的最小读取定义；旧 `worldType`、公开作品号、URL、详情页和专属运行态均不再形成用户可访问入口。
+- 方案文档：`docs/technical/【架构下线】旧创作模板业务退役方案-2026-07-17.md`。
+
+## 2026-07-18 恢复现役平台公共壳但禁止旧业务依赖回流
+
+- 背景：旧创作模板退役时误把新版 `/creation`、桌面公共侧边栏和“我的”完整资料页一起缩减；只恢复视觉后，现役 profile client 又经 `rpg-entry` barrel 把旧作品库、旧 runtime request 和展示模型重新带入 Vite 与 TypeScript 图。
+- 决策：桌面端继续使用原平台公共结构，一级导航固定为 `创作 / 项目 / 我的`；顶栏保留编辑器项目 / 素材搜索、泥点入口和账号胶囊；“我的”全宽保留资料编辑、陶泥号、三项统计、充值、兑换码、社区、反馈、通用设置、API Key 和法律信息。搜索只面向编辑器项目与公开编辑器素材，不恢复旧公开作品搜索。
+- 依赖边界：公共 dashboard、钱包、充值、兑换码、邀请码、API Key 和设置请求迁入 `services/platform-entry`，公共账单展示迁入现役 profile model。Vite 新增退役模块 graph 门禁，ESLint 对现役源码禁止导入旧目录；目录 watch ignore、Tailwind source、tsconfig include 和 tree-shaking 都不能作为依赖隔离证明。
+- 路由与响应式边界：`/creation`、`/project`、`/profile` 都是可刷新、可前进 / 后退的稳定路由；桌面端使用侧边栏，移动端必须提供同样 `创作 / 项目 / 我的` 的三项底部 dock，不得因隐藏桌面侧边栏而丢失移动导航。
+- 公共设置边界：`runtime_setting` 保持原表结构与历史数据，但它是音乐音量和平台主题的现役账号级公共能力，不归入旧玩法数据壳。鉴权后的 `GET/PUT /api/runtime/settings` 必须经 `spacetime-client` 调用 `get_runtime_setting_or_default` / `upsert_runtime_setting_and_return`；保留该路由不构成恢复旧 runtime API 的先例。
+- 编译门禁：除旧业务目录外，`src/uiAssets.ts`、`src/types.ts`、`src/types/**`、`src/services/runtimeAudioFeedback.ts` 和 `src/services/publicWorkCode.ts` 也是顶层退役 module，必须同时退出 Vite module graph、TypeScript、ESLint 和 Vitest；`/audio/**`、`/chat.png`、`/fusion-pixel.ttf` 及旧 pixel / story-tab / 玩法 CSS 不得进入 dev 服务或生产产物。验收时必须同时检查 `tsc --listFilesOnly`、Vite 依赖图 / 产物和退役资产路径，不能只依赖 tree-shaking。
+- Rust 产物边界：`module-runtime` 继续承载账号、钱包、公共设置、追踪和 feature gate，但 `CreationEntry*`、旧公开作品、存档、浏览历史与游玩统计 DTO / command / mapper / 规则必须退出实际 rlib；只保留历史表需要的 `RuntimeBrowseHistoryThemeMode`、完整保序的钱包流水来源枚举等持久化 ABI。`check:server-rs-ddd` 必须执行 `check:module-runtime-artifact`，同时验证旧符号和字面量为零、必要 ABI 仍存在，不能以源码存在 `#[cfg(any())]` 或路由未挂载代替产物证明。
+- 外围编译边界：`platform-auth` 不再编译 runtime guest token，`platform-wechat` 不再编译旧玩法生成结果订阅消息，小程序不再注册订阅授权页；旧公开作品资产授权 view 退出 SpacetimeDB module，匿名素材读取只保留现役 editor showcase 派生授权。
+- 历史队列边界：现役 external generation worker 只领取 `source_module = editor-canvas` 的任务，历史旧玩法 pending / running 行保持原状态，不得被新 worker 领取后改写为失败。
+- Agent crate 边界：`platform-agent` 的执行器、工具注册表、回调和拼图 Phase 1 输入均属于已退役 Creative Agent 业务，不得因现役编辑器 Agent 共用一个模型名常量而留在 workspace 或 `api-server` 依赖图。该常量收口到 `platform-llm`，`platform-agent` 与仅由它引入的 `langchainrust` 退出在运 Cargo resolve graph，源码目录继续仅作历史追溯。
+- AI 游戏创作兼容边界：独立 AGC Tauri 壳仍复用 `platform-agent::game_creation` 的任务图与隔离协作数据模型。`platform-agent` 继续排除在 `server-rs` workspace 之外，但其独立 manifest 默认只编译 `game_creation` / `error`，旧执行器、工具注册表、回调、拼图 Phase 1 与 `langchainrust` 统一受关闭的 `legacy-creative-agent` feature 隔离；AGC lock 不得重新引入这些退役依赖。
+- 防回流补充：顶层 `creationEntryConfigService`、`creationUrlState`、`customWorld*`、`runtimeGuestAuth`、`runtimeRequest`、`input-devices`、`useCombatFlow`、`useStoryOptions`、`useMocapInput` 和微信生成订阅 facade 同样属于退役前端模块；Vite dev 对旧 `/api/creation*` 与 `/api/public-works*` 前缀直接返回 404，不能回落 SPA HTML。
+- Vite 全量边界补充：`src/games/**`、`src/data/**`、`src/prompts/**`、旧顶层 App / Playground、旧路由和 `services/ai.ts` 必须由 pre-transform 门禁直接拒绝；所有同源 `/generated-*` 裸读在 dev 与生产统一为空 `404`，历史对象只经现役签名读取接口兼容，不允许 SPA fallback 伪装成资产成功响应。
+- 前端混合根目录补充：`src/components`、`src/hooks`、`src/persistence`、`src/routing`、`src/services` 的根级文件实行现役白名单，Vite 与 ESLint 使用同一口径阻断旧 RPG / 玩法根文件；子目录仍按现役目录和退役目录分别管理，新增公共根文件必须显式登记。
+- 影响范围：`PlatformEntryActiveFlowShell`、`PlatformActiveProfileView`、编辑器 / 项目搜索、平台 profile clients、`module-runtime`、`platform-llm`、Cargo workspace / resolve graph、Vite / ESLint / Rust 产物门禁及旧业务退役方案。
+
+## 2026-07-20 VectorEngine 图片任务预算收口到 worker deadline
+
+- 决策：`editor_image_generation`、`editor_image_edit`、`editor_icon_spritesheet_generation` 和 `editor_ui_design_asset_extraction` 使用默认 `1800s` long job 预算。worker 从同一起点计算绝对 job deadline，并向 provider 提前保留 `min(60s, job 预算 / 2)` 作为审计、OSS 和终态写回窗口。deadline 只经进程内 `RequestContext` 传递；VectorEngine 单 attempt 取配置 timeout 与剩余预算的较小值，退避加下一次 attempt 无法落在同一 deadline 内时停止重试，参考图和响应图片下载也受同一 deadline 限制。普通 HTTP / `inline` 保持无 deadline 行为；`VECTOR_ENGINE_IMAGE_REQUEST_TIMEOUT_MS` 默认仍为 `1000000`，配置加载层允许显式值更低。lease 续租 / fencing、迟到写回仲裁、attempt 耗尽和原子退款语义不变。
+
+## 2026-07-21 VectorEngine 图片首选 gpt-image-2 并以 gpt-image-2-c 兜底
+
+- 决策：前端、DTO、计费配置、持久化和 `platform-image` 的 `/v1/images/generations` / `/v1/images/edits` provider 首选请求统一使用 `gpt-image-2`；符合条件时才回退到兜底模型 `gpt-image-2-c`。不在业务 handler、前端或价格表中新增平行模型。
+- 回退边界：明确模型不存在 / 不支持、408、非内容拒绝类 429、5xx、响应解析失败或非拒绝类缺图可以切模型；401 / 403、普通参数 / 内容安全拒绝、本地配置与参考图错误、发送 / 连接错误、request budget 耗尽和已生成图片下载失败不切模型。一次业务请求总发送上限仍为 5 次，两个模型共享同一 worker provider deadline 和 attempt 预算。
+- 观测边界：审计 `image_model` 记录实际 provider attempt；首选 `gpt-image-2` 失败但兜底 `gpt-image-2-c` 恢复成功时，首选失败仍写入 `external_api_call_failure`，最终成功运行摘要记录 `recoveredFailureCount`。日志用 `fallback_from_model` / `fallback_to_model` 标识切换，不改变业务模型、扣费、素材 metadata 或终态语义。
+- 脚本边界：仓库 `gpt-image-2-apimart` skill 的现役生成脚本采用同一首选 / 回退顺序；认证、请求发送不确定错误和下载失败不重新生图，避免重复上游成本。
+
+## 2026-07-21 图片画布滚轮与中键平移统一为二维视口移动
+
+- 背景：画布中键拖拽的平移模型已同时计算 X / Y，但普通滚轮分支只消费 `deltaY`，横向滚轮或触控板的 `deltaX` 被丢弃，且缺少中键横向拖动的状态机回归覆盖。
+- 决策：普通滚轮原样消费设备上报的 `deltaX / deltaY` 二维平移 viewport；当按住 Shift 且设备上报 `deltaX = 0` 时，输入适配层把 `deltaY` 映射为横向位移并将纵向位移置零，核心平移模型不感知修饰键。`Ctrl / Cmd + 滚轮` 继续只负责围绕指针缩放；中键和抓手拖拽继续同时更新 X / Y。
+- 验证：交互模型单测覆盖原始 `deltaX / deltaY` 和缩放边界；viewport hook 单测覆盖二维滚轮、Shift 横向适配与 Ctrl 缩放；stage 状态机单测覆盖中键水平、垂直同时移动。
+
+## 2026-07-22 Gitea CI 使用预构建工具链 Job 镜像
+
+- 背景：Gitea Actions 的四个 job 彼此隔离，原 workflow 在每个 job 内重复运行 apt、setup-node、rustup 和原生系统依赖安装，后端与原生壳仅安装阶段就消耗数分钟，并重复承受软件源和代理瞬时失败。
+- 决策：新增 `deploy/container/gitea-ci-job.Dockerfile`，固定 Ubuntu job base digest `sha256:58ea92624c7c09582e05594d95488331045053d3a3f34cf09649f2a32313a614`、Rust stage digest `sha256:19817ead3289c8c631c73df281e18b59b172f6a31f4f563290f69cddd06c30e9`、带 SHA-256 校验的 Node `22.23.1` 发行包、Google Linux 主签名指纹和 Chrome `150.0.7871.181-1`。镜像预装 Rust 1.96、`rustfmt`、Chrome、`bwrap`、`rg`、`ffmpeg`、`clang/lld` 及 Tauri / 后端系统依赖，按当前锁预热根 npm、server-rs 与桌面壳 Cargo 下载缓存，并设置 `RUSTUP_AUTO_INSTALL=0`。构建脚本通过 NUL 分隔白名单 tar 流只发送约 `1.638 MB` 的 Dockerfile、checkout 脚本与依赖 manifests/lock，不发送业务源码、素材或本地私密文件。
+- 镜像事实：当前验证镜像约 `1.788 GB`，默认 tag 为 `genarrative/gitea-project-ci:20260722.2`，完整 Image ID 为 `sha256:548431a2529d325b5ab546f242799a4076f979779ee832a0871ac1af881a4946`。runner config 保留 `ubuntu-latest`，并新增 `genarrative-ci:docker://sha256:548431a2529d325b5ab546f242799a4076f979779ee832a0871ac1af881a4946`；内层 Docker 数据持久化，`force_pull: false`，精确 ID 缺失时失败关闭，不回退浮动 tag 或现场拉取。
+- workflow 边界：`Repository checks`、`Frontend tests`、`Backend tests` 和 `Native shell tests` 统一 `runs-on: genarrative-ci`，删除 GitHub checkout action、apt、setup-node 和 rustup 安装 step；镜像内 checkout 直接从当前 Gitea 拉事件 commit，并带 5 次有界重试。随后以 `GENARRATIVE_GITEA_CI_CHECK_RUNTIME=1` 执行 `scripts/check-gitea-ci-job-image.sh`，同时校验缓存锁、工具链、bwrap sandbox 与 Chrome headless。每个 job 仍各自执行干净的 `npm ci`，以当前 lockfile 为准隔离 PR 依赖；命中镜像 cache 时只做本地解包，锁新增依赖时经受控网络补齐。不烘入 `node_modules` / Cargo `target`，不挂载跨 PR 可写 cache。仓库 toolchain 变更时先重建镜像，不允许 job 现场下载 Rust。
+- 运维与回滚：用 `scripts/gitea-ci-job-image.sh build|verify|export|load-runner` 管理镜像，按 `build/verify -> export 仓库外镜像归档和 SHA-256 sidecar -> load-runner -> 确认无活跃 job -> 备份 config -> 增加或替换 label -> docker restart --timeout 660` 切换。config 与镜像归档只放仓库外受控位置；共享文档只记录通用备份规则，不记录宿主绝对路径、注册信息或 token。重启后先验证真实 CI 再清理旧镜像；回滚先把 workflow `runs-on` 改回 `ubuntu-latest`，再恢复 config 备份并重启 runner。
+- 影响范围：`.gitea/workflows/project-ci.yml`、`deploy/container/gitea-ci-job.Dockerfile`、`scripts/gitea-ci-job-image.sh`、`scripts/check-gitea-ci-job-image.sh`、`scripts/check-gitea-ci-job-runtime.sh`、runner label/config 和 Gitea CI 运维文档。
+- 验证方式：构建脚本校验宿主与 runner 内层 Image ID 一致；环境脚本校验 Node、Rust、`rustfmt`、Chrome、bwrap、原生命令与 pkg-config 依赖；runtime 脚本执行完整 bwrap 和 Chrome headless canary；真实 PR 的四个 job 全部通过，同时复核 `Privileged=false`、`Binds=[]`、`MaskedPaths=[]`、`ReadonlyPaths=[]` 和独立网络。
+
+## 2026-07-23 BgFilter 父侧连接失败有界重连与冷启动宽限
+
+- 背景：主机重启或 worker 崩溃拉起期间，父侧对 loopback BgFilter worker 的 TCP 连接失败此前直接映射 `internal_error`：complex（队列 `max_attempts=1`）终态失败不可自愈，flat 被迫降级。systemd 层修复被否决——`After=` 在 `Type=simple` 下只提供进程启动排序，不构成「已监听」的 readiness 保证；而任何显式 readiness 交接（`Type=notify`、阻塞式 `ExecStartPost` 探活、socket activation 等）一旦成为 API / external worker 的启动硬依赖，都会把 BgFilter 故障扩大为整套服务不可启动。
+- 决策：仅对「TCP 连接从未建立」的失败（连接拒绝 / 不可达 / connect 阶段超时）做有界退避重连——这类请求从未进入 worker admission，无副作用、天然幂等；连接已建立后的任何失败（结果未知）与收到任何 HTTP 响应（含 5xx）维持原「不重试」禁令。每轮重连前按现有公式重算 `maxQueueWaitMs`，不突破「预算不足不发送」不变量。计量单位澄清：一次逻辑调用至多被 worker 接收一次 RPC，重连增加的只是连接尝试次数。
+- 冷启动宽限：重连配额按「本进程是否已连通过 worker」（收到任意 HTTP 响应即算，`AppState` 级标记）分档——冷启动档 flat 22.5s / complex 约 62.5s（覆盖开机竞态与慢开机），常规档 flat ≤1.5s（不侵蚀 39s fallback 预留）/ complex 22.5s（覆盖 `RestartSec=5s`+ 启动窗）；档位单次调用内锁定。新增 `bgfilter_internal_connect_retry_total{mode}` 指标。
+- 平台差异（Windows 开发环境）：连接已关闭的 loopback 端口不回 RST 而是挂到 connect timeout，错误呈现为 `deadline_exceeded` 且 `is_connect` 为真；重连判定只看 connect 分类，不看错误码。生产 Linux 即时拒绝，呈现 `internal_error`。
+- 安全不变量测试：除配额 / 跨窗 / deadline 地板路径外，专项覆盖「TCP 已 accept、未回任何 HTTP 字节即断开 → 不得发起第二次连接」，以 mock listener 的 accept 计数证明父侧未重连。
+- 影响范围：`server-rs/crates/api-server/src/bgfilter_worker.rs`、`state.rs`、`editor_project.rs`、调度方案 §5.1/§7/§9.3/§11、数据契约「BgFilter 连接复用、超时与动作帧流水线」条目、运维文档及各编辑器专题文档的旧禁令措辞统一改为「不重试已被 worker 接收的内部 RPC」。
+
+## 2026-07-23 生产 API 发布按实际路径渲染 worker systemd unit
+
+- 背景：Server-Provision 支持自定义 current link、API env 和角色 env，并在首次安装时渲染三个 worker unit；API deploy 为下发随 release 更新的 unit 又原样覆盖目标机配置，导致自定义路径在下一次发布时退回模板默认值。
+- 决策：`production-api-deploy.sh` 继续随 release 安装默认命名的 BgFilter、external-generation worker 和 controller unit，但安装前必须用本次部署参数渲染临时文件；新增 `--controller-env-file` 补齐 controller 专属 env 输入。release 内模板保持默认路径，供 provision 和 deploy 共同作为单一模板来源；自定义服务名仍由目标机自行管理，不强制覆盖。
+- 影响范围：`scripts/deploy/production-api-deploy.sh`、`scripts/check-production-api-deploy.mjs`、`jenkins/Jenkinsfile.production-api-deploy`、`jenkins/Jenkinsfile.production-full-build-and-deploy`、`scripts/check-production-ops-guardrails.mjs`、生产运维文档和 worker systemd 发布契约。
+- 验证方式：`bash -n scripts/deploy/production-api-deploy.sh`、`node --check scripts/check-production-api-deploy.mjs`、`npm run check:production-api-deploy`、`npm run check:production-ops`、`npm run check:encoding`、`git diff --check`。
+
+## 2026-07-23 Gitea CI 镜像刷新到 SpacetimeDB 2.7.0 锁
+
+- 背景：`server-rs/Cargo.lock` 已从镜像预热时的 SpacetimeDB 2.6.1 前移到 2.7.0，runtime 校验因此报告 `server_rust_cache_lock=partial`。受控 Cargo egress proxy 连续返回 CONNECT tunnel 502 时，Backend job 在 `check:module-runtime-artifact` 依赖解析阶段失败，尚未进入 workspace tests。
+- 决策：刷新默认镜像 tag 为 `genarrative/gitea-project-ci:20260723.1`，完整 Image ID 为 `sha256:c04b114b1f145072c9df7842c4c974e1bb2eaaf391d95d84c9212a460546b7d5`，并将 Runner `genarrative-ci` label 映射到该精确 ID。镜像内 server-rs lock SHA-256 为 `ab1e07479b5716a98ddab9824bf95664121935aea30ab719f76f0705e1f96bbb`，包含 `spacetimedb`、`spacetimedb-lib` 和 `spacetimedb-sdk` 2.7.0 缓存。
+- 构建边界：两个 `cargo fetch --locked` 在 Cargo 自身网络重试外再执行最多 5 次整命令级重试，处理 registry index / config TLS 握手直接失败；版本解析仍受 lockfile 固定，构建末尾继续以 `CARGO_NET_OFFLINE=true cargo fetch --locked` 证明缓存闭合。
+- 运维边界：镜像归档、SHA-256 sidecar、切换前 Runner config 与注册文件备份只保存到仓库外受控目录。切换前连续确认 Gitea 无 `in_progress` run 且内层 Docker 无容器，切换后等待 rootless Docker socket 恢复，再验证 Image ID、label 注册、bwrap 与 Chrome canary；旧镜像在真实 CI 通过前保留。
+- 验证方式：新镜像在 `--network none` 下按当前锁完成 `cargo fetch --offline`，并完成 `module-runtime`、`platform-auth`、`platform-wechat` 构建；宿主与 runner 内层 Image ID 一致。真实 master CI 还必须确认 cache lock 命中并完成原 Backend workspace tests。
+
+## 2026-07-22 陶泥儿精选改为顺序循环分列 Masonry
+
+- 背景：CSS multi-column 会按纵向高度平衡卡片，少量素材或活动卡与普通素材高度差较大时，桌面首行会只放一到两张，后续卡片提前从左侧下一段开始，无法满足“每行填满三张再换行”。
+- 决策：`/creation` 陶泥儿精选保持平面 DOM 顺序，按当前列数将第 `index` 张循环分配到 `index % columns` 列。三列下第 1/2/3 张分别进入第 1/2/3 列，第 4/5/6 张再分别接续三列；不采用最短列贪心排序，避免同一组多张连续进入同一列。
+- 宽度与高度边界：列数由精选容器实际宽度、0.92rem computed gap 和 288px 首选最小列宽共同决定，最多三列。卡片先获得目标列宽，再按真实 preview aspect ratio 和内容测量高度；同列紧凑堆叠，不拉伸、裁切或等待其它列高卡。循环分列只消除列内空洞，较短列在整个容器底部仍可有尾部高度差。
+- 动态与可用性边界：`useLayoutEffect` 首次同步测量，`ResizeObserver + requestAnimationFrame` 在容器变宽、卡高变化、筛选重排和 cursor 追加后全量重排。只有当宽度、卡数和所有高度完整时才进入 absolute ready；否则保留 Grid fallback，防止卡片重叠和分页 sentinel 提前触发。DOM/Tab/读屏顺序始终不变，容器与卡片显式为 list/listitem。
+- 兼容边界：保留现有 `.creation-landing__asset-waterfall` 类名、筛选、排序、cursor 分页、预览与点赞链路；只替换布局算法。该决策覆盖 2026-07-07 multi-column 及本日早先 row-major Grid 的布局部分，不改变精选仍是动态素材流的产品定位。
+- 验证方式：纯函数测试锁定容器临界宽度、循环列序、列内 top 和容器高度；`src/index.test.ts` 锁定 Grid fallback 与 Masonry ready。Playwright 在同一 viewport 中变更容器宽度，核对 3/2/1 列、每列 gap、容器高度、DOM 顺序、无重叠/横溢出和 console/page error。
+
+## 2026-07-23 恢复通用灰度发布后台控制面
+
+- 背景：旧创作模板退役时，后台灰度页因同时加载 `creation-entry:*` 动态目标与现役 `image-editor:agent-sidebar` 固定目标，被整页从路由、TypeScript、ESLint 和 Vitest 编译链摘除；通用 feature gate 后端、权限和现役画布 Agent 判定仍在，形成有 API 无正式控制面的不一致。
+- 决策：恢复后台 `#gray-release` 导航、member Tab 权限展示、前端 DTO/client、页面渲染和页面测试；页面只读取和写入 `GET/PUT /admin/api/feature-gates`，不再请求已退役 `/admin/api/creation-entry/config`。
+- 目标边界：固定目标列表只登记现役 `image-editor:agent-sidebar`；管理员仍可直接输入其他通用 Gate Key。不得恢复 `creation-entry:*` 动态目标、入口公告、入口开关、旧作品可见性页面或任何旧模板接口。
+- 运行语义：环境变量继续是画布 Agent 总开关，feature gate 只在总开关开启后做黑名单、白名单、标签和稳定百分比受众限制；本次不修改 SpacetimeDB schema、灰度优先级或后端契约。
+- 验证方式：后台路由与灰度页面 Vitest、`npm run admin-web:typecheck`、定向 ESLint、`npm run check:encoding`、`git diff --check`。
+
+## 2026-07-23 手机号认证统一使用国家码与纯号码双字段
+
+- 决策：普通手机号认证请求统一使用可选 `countryCode` 与必填 `purePhoneNumber`，省略国家码时默认中国大陆 `86`，直接替换旧 `phone` 字段。前端把浏览器 E.164 自动填充值拆成这两个字段；后端先验证国家码，再复用纯手机号规范化并生成 E.164 存储。
+- 微信边界：小程序客户端仍只上传 `wechatPhoneCode`；`platform-auth` 必须要求微信成功响应中的 `phoneNumber`、`countryCode` 与 `purePhoneNumber` 均存在且非空，但只使用后两项执行国家码校验和 E.164 构造。腾讯官方仅说明境外 `phoneNumber` 会带区号，并未承诺 E.164 格式，中国号码示例中它与纯号码相同，因此不得校验 `phoneNumber == +{countryCode}{purePhoneNumber}`。微信字段缺失时失败关闭，不能使用普通请求的 `86` 默认值。
+- 数据边界：认证投影与 SpacetimeDB 的 `phone_number_e164` 保持不变，不新增国家码或纯号码列，也不需要 schema 迁移或 bindings 生成。
@@ -240,18 +240,19 @@ npm run ai-game-creator-shell:agent-runtime:real-e2e -- --config-dir <AppData> -

 `npm run agc` 会启动 Tauri 开发客户端；其 `beforeDevCommand` 通过 `npm run agc:serve` 先完成壳 typecheck，再启动或复用配套 SpacetimeDB、`api-server` 和固定 `127.0.0.1:3080` Vite。只需要浏览器预览同一客户端时可用 `npm run agc:serve`；只启动配套后端和数据库时可用 `npm run agc:backend -- --database <name>`。

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

-本地 `npm run dev`、`npm run dev:spacetime` 和 `npm run dev:api-server` 会在 Rust 子进程环境中绕过项目默认 `sccache` wrapper，避免损坏的本机 cache daemon 阻断 `spacetime publish` 或 `api-server` 启动；显式设置的非 sccache 自定义 wrapper 会被保留。生产 / Jenkins 构建仍按流水线自身的 sccache 策略执行。
+本地 `npm run dev`、`npm run dev:spacetime`、`npm run dev:api-server` 和 `npm run dev:bgfilter-worker` 会在 Rust 子进程环境中绕过项目默认 `sccache` wrapper，避免损坏的本机 cache daemon 阻断 `spacetime publish` 或 Rust 服务启动；显式设置的非 sccache 自定义 wrapper 会被保留。生产 / Jenkins 构建仍按流水线自身的 sccache 策略执行。

 该命令会启动：

 - SpacetimeDB standalone
+- 独立 `bgfilter-worker`
 - Rust `api-server`
 - 主站 Vite
 - 后台 Vite

-`npm run dev` 和单模块 `dev:*` 命令会更新根目录 `.app/dev-stack.json`，记录四个本地服务的 pid、端口、URL、启动状态和当前命令。该目录只作本机运行态观测，不提交 Git。
+`npm run dev` 和单模块 `dev:*` 命令会更新根目录 `.app/dev-stack.json`，记录五个本地服务的 pid、端口、URL、启动状态和当前命令。该目录只作本机运行态观测，不提交 Git。

 开启自动刷新：

@@ -259,9 +260,9 @@ Linux 多用户共享同一台机器开发时，本地 dev 脚本会为当前 Li
 npm run dev -- --watch
 ```

-watch 模式只由外层调度器自动处理后端侧刷新：`spacetime-module` 改动后重新发布模块但不重启 standalone 宿主，`api-server` 改动后重启 Rust 进程。主站 Vite 与后台 Vite 的源码变化交给 Vite 自身 HMR，避免外层 watcher 监听到依赖缓存或临时文件后循环重启。
+watch 模式只由外层调度器自动处理后端侧刷新：`spacetime-module` 改动后重新发布模块但不重启 standalone 宿主；完整栈和 `dev:api-server` 只创建一套 Rust watcher，改动后先停止 API 与 BgFilter worker，再先启动并验活 worker、最后启动并验活 API。主站 Vite 与后台 Vite 的源码变化交给 Vite 自身 HMR，避免外层 watcher 监听到依赖缓存或临时文件后循环重启。

-非 watch 模式下，`npm run dev` 终端支持输入 `rs spacetime`、`rs api-server`、`rs web`、`rs admin-web` 或 `rs all`。其中 `rs spacetime` 只会重新发布 `spacetime-module`，不会重启 standalone 宿主；其他模块仍按进程重启。
+非 watch 模式下，`npm run dev` 终端支持输入 `rs spacetime`、`rs api-server`、`rs bgfilter-worker`、`rs web`、`rs admin-web` 或 `rs all`。其中 `rs spacetime` 只会重新发布 `spacetime-module`，不会重启 standalone 宿主；重启任一 Rust 角色都会走 API / BgFilter worker 组合重启。

 单独启动 SpacetimeDB：

@@ -275,6 +276,12 @@ npm run dev:spacetime
 npm run dev:api-server
 ```

+该命令会由同一 runner 自动带起独立 BgFilter worker，确保共享实际内部 base URL 和 Token。只单独启动内部 worker 时使用：
+
+```bash
+npm run dev:bgfilter-worker
+```
+
 单独启动前端：

 ```bash
@@ -296,7 +303,7 @@ npm run server-manager:panel
 该命令启动 `server-rs/crates/server-manager-panel` 的 egui 桌面工具，从本机 `~/.ssh/config` 读取可用 `Host` alias，支持多服务器健康巡检、可折叠侧边栏和受控 systemd 服务启停。服务操作通过远端 `sudo -n systemctl start|stop|restart <unit>` 执行，目标服务器需要提前配置对应 unit 的免交互 sudo 权限。
 面板启动时会自动注入本机中文字体；如开发机中文仍显示为方块，可设置 `GENARRATIVE_SERVER_PANEL_CJK_FONT=/path/to/font.ttc|index` 指向本机 CJK 字体。

-`npm run dev:api-server` 会保留终端实时输出，并把同一份输出持久化到 `logs/api-server/api-server-<timestamp>.log`。完整联调入口 `npm run dev` 启动的 Rust `api-server` 使用同一套日志规则。如需改写路径，可设置 `GENARRATIVE_API_SERVER_LOG_FILE`；如只改目录，可设置 `GENARRATIVE_API_SERVER_LOG_DIR`。
+`npm run dev:api-server` 会保留终端实时输出，并把 API 输出持久化到 `logs/api-server/api-server-<timestamp>.log`、BgFilter worker 输出持久化到 `logs/bgfilter-worker/bgfilter-worker-<timestamp>.log`。完整联调入口 `npm run dev` 使用同一套日志规则。API 日志可通过 `GENARRATIVE_API_SERVER_LOG_FILE` / `GENARRATIVE_API_SERVER_LOG_DIR` 改写，worker 日志可通过 `GENARRATIVE_BGFILTER_WORKER_LOG_FILE` / `GENARRATIVE_BGFILTER_WORKER_LOG_DIR` 改写。

 开发态 `npm run dev` / `npm run dev:api-server` 默认打开 `GENARRATIVE_DEV_PASSWORD_ENTRY_AUTO_REGISTER_ENABLED=true`，密码入口可以直接注册未知手机号账号；生产默认仍关闭该开关。

@@ -375,7 +382,7 @@ npm run check:rustfmt
 cargo fmt --all --manifest-path server-rs/Cargo.toml
 ```

- 后端通用用户行为埋点统一通过 `record_tracking_event_and_return` procedure、`SpacetimeRuntimeClient::record_tracking_event(...)` 与 api-server `tracking` 中间件写入 `tracking_event` / `tracking_daily_stat`；后台、RPG、大鱼吃小鱼、Visual Novel、Story、Combat 默认排除；作品级游玩埋点统一使用 `work_play_start`，详细事件清单见 `docs/technical/BACKEND_TRACKING_EVENT_COVERAGE_2026-05-09.md`。
+- 后端通用用户行为埋点统一通过 `record_tracking_event_and_return` procedure、`SpacetimeRuntimeClient::record_tracking_event(...)` 与 api-server `tracking` 中间件写入 `tracking_event` / `tracking_daily_stat`；现役账号、钱包、编辑器、项目、精选素材和公共设置路由按 `tracking.rs` 的显式静态路由表记录，后台路由默认排除。旧玩法、公开作品和专属运行态路由已经退役，不再维护作品级游玩埋点覆盖。

 编码检查：

@@ -420,23 +427,15 @@ npm run check:native-shells
 ```

 该命令会覆盖 H5 HostBridge 关键测试、微信 / Expo / Tauri 三端桥接层文件结构门禁、完整相对路径文档反查、微信 capability 到真实 WebView / 支付 / 分享页面流程和测试清单的映射门禁、H5 HostBridge 事件订阅双能力门控反查、H5 `navigation.canGoBack` 消费 hook 与直达二级页返回锚点测试、移动端和桌面端单端源码清单门禁、Expo 壳 typecheck / test / EAS build config smoke / config smoke / Metro export smoke、Tauri 壳 typecheck / cargo test、桌面壳 release `--no-bundle` 构建烟测，以及可分发壳与 H5 HostBridge 真实调用链的临时替身词扫描，确认 Expo managed config、移动端 EAS 原生包构建 profile、移动端 iOS / Android production bundle、打包 H5 资产、Tauri release 入口、H5 页面内导航保留完整原生宿主上下文和 H5 HostBridge 真实调用链没有漂移；扫描范围包含微信小程序壳生产 `.js`、Tauri `Info.plist`、共享 HostBridge 契约、H5 native transport，并自动覆盖已接入真实宿主能力 facade 的 H5 生产调用链文件，但不扫描 Expo export、Tauri `target/`、Cargo / Metro 缓存或 release 构建产物。移动壳配置检查必须反查 EAS 生产 profile、文本 / 文档 / 图片 / 音频导入边界都来自共享 HostBridge 契约。登录与支付外链跳转必须保持在该调用链扫描内，`src/services/authService.ts` 和 `src/services/payment/paymentRedirect.ts` 是必扫文件；`AuthGate` 的登录成功、退出登录、身份边界刷新和登录状态异常重试都必须通过 `app.reloadWebView` 优先路径，并由 `src/components/auth/AuthGate.test.tsx` 进入该门禁。壳源码和配置继续严格禁止 mock / fake / placeholder / stub / TODO / FIXME / 占位 / 模拟 / 伪造 / 未实现 / 临时；H5 业务调用链允许正常表单 `placeholder` 属性、业务占位图文案和真实兼容 / 故障语义中的“未实现”“临时”表述，但仍禁止 mock / fake / stub / TODO / FIXME / 模拟 / 伪造等替身痕迹。
-创作 Agent 原生壳文档导入优先走 `file.importDocument`，旧壳只声明 `file.importText` 时才回退文本导入；相关变更必须让根级和单端门禁覆盖共享 method、capability profile、文档 MIME / 5 MiB 上限、读取前 size 校验，以及 H5 base64 转 `File` 后继续走后端文档解析的链路。
-创作 Agent 参考图上传在原生壳声明 `file.importImage` 时必须优先走宿主图片导入，并把 H5 base64 转 `File` 后继续交给既有 `onReferenceImageChange` 校验链路；用户取消原生选择不应再连带弹出浏览器文件输入，普通浏览器、小程序和未声明能力的裁剪壳才使用原隐藏文件输入。
-创作 Agent 轻输入 composer 的参考图按钮在原生壳声明 `file.importImage` 时必须优先走宿主图片导入；移动壳声明 `file.captureImage` 时才显示拍摄参考图入口，并把宿主图片同样转为 `File` 后复用 `readPuzzleReferenceImageAsDataUrl` 的类型、大小、压缩和预览链路。
 反馈页上传凭证在原生壳声明 `file.importImage` 时必须优先走宿主图片导入；移动壳声明 `file.captureImage` 时才显示拍摄凭证入口，并把拍摄图片同样转为 `File` 后复用反馈页原有数量、大小、MIME、data URL 预览和提交 payload 校验。
-固定内置 H5 体验入口在原生壳声明 `navigation.openNativePage` 时必须优先走 `navigateHostNativePage()`；例如儿童动作热身 Demo 从平台首页进入 `/child-motion-demo` 时应由 HostBridge 发出 `navigation.openNativePage`，宿主不可用时才回退浏览器跳转。
+Expo / Tauri 声明 `navigation.openNativePage` 时，只用于现役同源 H5 路由的受控导航和宿主上下文续接；微信小程序不再声明该能力。旧儿童动作 Demo、模板工作台、生成页、结果页和运行态不得作为 HostBridge 导航验收入口。
 H5 支付链接跳转在原生壳声明 `app.openExternalUrl` 时必须优先走宿主系统浏览器；原生壳未接真实支付 SDK 前不得声明 `payment.request`，也不得把外部 H5 支付跳转伪装成原生支付成功。
 微信 OAuth 登录授权 URL 在原生壳声明 `app.openExternalUrl` 时必须优先走宿主系统浏览器；原生壳未接真实登录 SDK 前不得声明 `auth.requestLogin`，也不得把网页登录跳转伪装成原生登录成功。
-汪汪声浪结果页玩家 / 对手 / UI 背景三图槽位上传在原生壳声明 `file.importImage` 时必须优先走宿主图片导入，并把 H5 base64 转 `File` 后继续交给 `uploadBarkBattleAsset` 与当前槽位写回链路；用户取消原生选择不应再连带弹出浏览器文件输入，普通浏览器、小程序和未声明能力的裁剪壳才使用原隐藏文件输入。
-抓大鹅结果页发布封面图和封面参考图上传在原生壳声明 `file.importImage` 时必须优先走宿主图片导入，并把 H5 base64 转 `File` 后复用现有封面 data URL 读取、AI 重绘开关、参考图集合和封面生成 payload 链路；用户取消原生选择不应再连带弹出浏览器文件输入。
-RPG 角色资产工作室的角色参考图上传在原生壳声明 `file.importImage` 时必须优先走宿主图片导入，并把 H5 base64 转 `File` 后复用现有 `readFileAsDataUrl` 参考图集合和角色形象生成 payload 链路；用户取消原生选择不应再连带弹出浏览器文件输入。
-RPG 作品封面上传在原生壳声明 `file.importImage` 时必须优先走宿主图片导入，并把 H5 base64 转 `File` 后复用现有 10 MiB 校验、图片尺寸读取、16:9 裁剪和 `uploadCustomWorldCoverImage` 保存链路；用户取消原生选择不应再连带弹出浏览器文件输入。
-RPG 作品封面参考图上传在原生壳声明 `file.importImage` 时必须优先走宿主图片导入，并把 H5 base64 转 `File` 后复用现有 `readImageFileAsDataUrl` 读取、预览和 `generateCustomWorldCoverImage` payload 链路；用户取消原生选择不应再连带弹出浏览器文件输入。
-RPG 场景图片参考图上传在原生壳声明 `file.importImage` 时必须优先走宿主图片导入，并把 H5 base64 转 `File` 后复用现有 `readImageFileAsDataUrl` 读取、预览和 `rpgCreationAssetClient.generateSceneImage` payload 链路；用户取消原生选择不应再连带弹出浏览器文件输入。
+现役编辑器与个人中心新增文件导入能力时，继续复用共享 `file.importDocument`、`file.importImage`、`file.captureImage` 和 MIME / 大小门禁，不得把已退役模板的上传 service、玩法 DTO 或页面测试重新纳入原生壳门禁。
 视觉小说结果页封面 / 角色 / 场景图片和音乐 / 环境音上传在原生壳声明 `file.importImage` / `file.importAudio` 时必须优先走宿主受控导入，并把 H5 base64 转 `File` 后继续交给 `uploadVisualNovelAsset` 与当前素材字段写回链路；用户取消原生选择不应再连带弹出浏览器文件输入，历史素材选择和 AI 图片生成保持原链路。
 该命令会反查微信小程序 `WECHAT_HOST_CAPABILITIES` 与共享 `HOST_BRIDGE_WECHAT_MINI_PROGRAM_CAPABILITIES` 一致；小程序生产代码继续保留 CommonJS 运行时镜像，不直接 import TypeScript shared 包。
 该命令同时会运行微信小程序 `miniprogram/host-bridge/`、`miniprogram/shell/`、`pages/web-view` 样式和 `scripts/miniprogram-web-view-auth.test.ts` 的壳层测试，保证微信桥接层拆分后的支付、订阅消息、九宫切图、分享目标和 WebView 登录 / 分享入口行为与 Expo、Tauri 壳一起验收。
-该命令还会反查微信小程序 `app.json.pages` 与 `host-bridge/protocol.js` 页面 URL、H5 小程序页面常量、H5 订阅授权页面常量、WebView 分享入口、分享目标消息类型、`WEB_VIEW_SOURCE_QUERY`、微信请求头运行时标记、H5 runtime parser、H5 路由保留字段和 H5 / API base URL 格式，避免页面路由、来源标记、宿主上下文 query 或域名配置在微信壳、H5 HostBridge 与运行时配置之间分叉。生产 / 开发 H5 与 API 域名都必须显式配置为纯 HTTPS domain，运行时开发域名回退生产域名只作为异常兜底。
+该命令还会反查微信小程序 `app.json.pages` 与 `host-bridge/protocol.js` 现役页面 URL、H5 小程序页面常量、WebView 分享入口、分享目标消息类型、`WEB_VIEW_SOURCE_QUERY`、微信请求头运行时标记、H5 runtime parser、H5 路由保留字段和 H5 / API base URL 格式，避免页面路由、来源标记、宿主上下文 query 或域名配置在微信壳、H5 HostBridge 与运行时配置之间分叉。旧生成结果订阅授权页和对应 H5 service 不再进入清单。生产 / 开发 H5 与 API 域名都必须显式配置为纯 HTTPS domain，运行时开发域名回退生产域名只作为异常兜底。

 内容检查：

@@ -468,6 +467,12 @@ npm run check:server-rs-ddd
 - 普通 PR job 不读取业务 secret，不运行真实 API/SpacetimeDB/OSS/支付/生成/live smoke，也不执行会修改外部状态的维护、迁移、发布或备份命令。
 - Gitea 至少升级到 `1.26.4` 后才能注册执行 PR job 的 runner；`ubuntu-latest` 标签只映射到固定 digest 的 Ubuntu 24.04 级 Docker/临时隔离镜像，不使用浮动镜像 tag，不映射 host，不向 job 暴露 Docker socket、业务 secret 或不必要内网。runner 能访问 Gitea、GitHub Actions 与 `actions/node-versions`、nodejs.org、npm、Rust 分发、crates.io 和 Google Chrome 的 `dl.google.com` 官方签名 APT 源；workflow 的官方 action 固定完整 commit，若内网禁用 GitHub，先在当前 Gitea 镜像对应 commit 并改用绝对 URL。受控镜像优先预装 rustup。Gitea 1.26 的任务超时由 runner 全局配置控制；首次运行成功后，`master` 分支保护必须要求上述四个 job 全部成功。
 - `genarrative-station` 当前使用 Gitea `1.26.4` + 基于 Runner `2.0.0-dind-rootless` 的固定 digest 修补镜像：只修复 `systempaths=unconfined` 的空 slice 被 `mergo` 丢失，真实 job 必须保持 `MaskedPaths=[]`、`ReadonlyPaths=[]`；外层仍非 privileged、无 `CAP_SYS_ADMIN`，内部 Docker 只监听 Unix socket，`docker_host: "-"` 阻止 socket 进入 job。job 只在 `gitea-actions` internal network，通过 `/git` reverse gateway 访问 Gitea，通过拒绝私网、保留地址和 metadata 的 80/443 proxy 访问公共依赖；直连公网和 Gitea 数据网必须失败。内层 bwrap 所需 namespace/proc 选项只能用于该 rootless DinD，不能放宽宿主 rootful runner。系统依赖步骤在 root job 中不调用 sudo，非 root 时用 `sudo -E` 保留受控 proxy；Cargo 关闭 HTTP multiplexing 并设置 10 次网络重试，rustup bootstrap/toolchain 安装也按有界次数重试。AI 原生壳 job 把 Node 发行目录与 rustup proxy 安装到 `/usr/local` 的受信任只读路径，并在测试前执行完整 bwrap canary。宿主 compose helper 必须把 `/opt/gitea-stack` 挂到同名绝对路径，避免相对 volume 错误落到 `/stack` 空目录。
+- 四个 job 共同覆盖 `npm run check`，并追加 `npm run bgfilter-worker:smoke-test`、`npm run check:production-health-patrol`、`npm run check:production-api-release`、`npm run check:production-api-deploy`、`npm run check:server-rs-ddd`、`cargo test --locked --workspace --no-fail-fast --manifest-path server-rs/Cargo.toml`、`cargo check -p api-server --all-targets --manifest-path server-rs/Cargo.toml` 和 `cargo check -p spacetime-module --manifest-path server-rs/Cargo.toml`。BgFilter 的 `.test.mjs` 使用 Node test runner，必须由 workflow 显式调用；生产巡检 / 发布 / 部署行为检查只运行无密钥临时 fixture，不连接现场环境。`ffmpeg` 由预构建 job 镜像提供，避免视频抽帧测试因工具缺失提前返回。`codex/ai-game-creator-app` 分支的原生壳入口还必须覆盖 `npm run ai-game-creator-shell:check` 和 release build smoke。
+- checkout 必须使用完整历史。PR 将 base SHA 写入 `SPACETIME_SCHEMA_BASE_REF`，直接推送 `master` 使用 before SHA；事件基线不可解析时直接失败。Gitea 检查的是 PR head 而非预合并 commit，workflow 必须拒绝不包含最新 base commit 的过期 PR，分支保护同时保持“PR 过期禁止合并”。
+- 普通 PR job 不读取业务 secret，不运行真实 API/SpacetimeDB/OSS/支付/生成/live smoke，也不执行会修改外部状态的维护、迁移、发布或备份命令。
+- Gitea 至少升级到 `1.26.4` 后才能注册执行 PR job 的 runner。runner 保留 `ubuntu-latest` 固定 digest 映射，并把 workflow 使用的 `genarrative-ci` 映射到 runner 内层 Docker 已装入的完整 Image ID；不映射 host，不向 job 暴露 Docker socket、业务 secret 或不必要内网。当前 CI 镜像约 `1.788 GB`，Image ID 为 `sha256:c04b114b1f145072c9df7842c4c974e1bb2eaaf391d95d84c9212a460546b7d5`，标签映射为 `genarrative-ci:docker://sha256:c04b114b1f145072c9df7842c4c974e1bb2eaaf391d95d84c9212a460546b7d5`。内层 Docker 数据持久化且 `force_pull: false`，该 ID 缺失时失败关闭，不现场拉取或回退浮动 tag。Runner 2.0.0 支持 job 级 `timeout-minutes`，但 runner 全局 `3h` 仍是硬上限；首次运行成功后，`master` 分支保护必须要求上述四个 job 全部成功。
+- `deploy/container/gitea-ci-job.Dockerfile` 固定 Ubuntu base digest `sha256:58ea92624c7c09582e05594d95488331045053d3a3f34cf09649f2a32313a614`、Rust stage digest `sha256:19817ead3289c8c631c73df281e18b59b172f6a31f4f563290f69cddd06c30e9`、带 SHA-256 校验的 Node `22.23.1`、Google Linux 主签名指纹和 Chrome `150.0.7871.181-1`，预装 Rust 1.96、`rustfmt`、Chrome、`bwrap`、`rg`、`ffmpeg`、`clang/lld` 与 Tauri / 后端系统依赖，并预热根 npm、server-rs 与桌面壳 Cargo 下载缓存。构建脚本使用约 `1.638 MB` 的白名单 tar context，不发送源码、素材或本地私密文件；`cargo fetch --locked` 同时受 Cargo 网络重试和最多 5 次整命令级重试保护，最后必须通过断网 fetch。更新按 `scripts/gitea-ci-job-image.sh build/verify -> export 仓库外镜像归档 -> load-runner -> 确认无活跃 job -> 仓库外备份 config -> 替换 label -> docker restart --timeout 660` 执行；真实 CI 全部通过后才清旧镜像。回滚先把 workflow 改回 `ubuntu-latest`，再恢复 config 备份并重启。备份不进 Git，不在共享文档记录宿主私密路径或注册信息。
+- 四个 workflow job 都使用 `runs-on: genarrative-ci`，先用镜像内脚本直接从 Gitea checkout，再以 `GENARRATIVE_GITEA_CI_CHECK_RUNTIME=1` 运行 `scripts/check-gitea-ci-job-image.sh`，同时校验缓存锁、工具链、完整 bwrap sandbox 和 Chrome headless。workflow 不再包含 GitHub checkout action、apt、setup-node 或 rustup 安装，并设置 `RUSTUP_AUTO_INSTALL=0`；工具链变更时先重建镜像。每个 job 仍各自执行 `npm ci` 以校验 lockfile 和隔离 PR 依赖，但优先复用镜像只读 cache，不烘入 `node_modules`，不挂载跨 PR 可写 Actions cache。`genarrative-station` 继续使用固定 digest 的 Runner `2.0.0-dind-rootless` 修补镜像，真实 job 保持 `MaskedPaths=[]`、`ReadonlyPaths=[]`、`Privileged=false`、`Binds=[]`，`docker_host: "-"` 阻止 socket 进入 job。job 只在 `gitea-actions` internal network，锁文件差量依赖只经拒绝私网、保留地址和 metadata 的 80/443 proxy，直连公网和 Gitea 数据网必须失败；npm 与 Cargo 都设置 10 次网络重试，Cargo 继续关闭 HTTP multiplexing。

 ## 后端相关默认验证

@@ -513,8 +518,8 @@ npm run check:server-rs-ddd

 - 移动端优先，再兼容网页端。
 - 页面只展示后端返回的状态，不自行计算结论型业务状态。
- 创作中心入口配置事实源在 SpacetimeDB，通过 `GET /api/creation-entry/config` 下发；前端只在 `platformEntryCreationTypes.ts` 做展示派生，api-server 路由熔断也使用同一份配置，禁止恢复前端硬编码入口配置文件。底部加号创作入口页公告位也跟随后端 `eventBanners` 配置，前端只做展示和轮播；后台公告用表单维护标题与 HTML 内容，保存时再序列化为后端 `eventBannersJson` 传输字段。`最近创作` 不属于模板分类，不能作为分类缺失兜底；生成中和生成失败的真实草稿摘要都应进入最近创作。
- 一期统一创作页字段 spec 同样跟随 `GET /api/creation-entry/config`，由 `creationTypes[].unifiedCreationSpec` 下发；拼图、抓大鹅、敲木鱼之外的模板不接入该扩展位，前端只保留旧后端缺字段时的兜底默认。
+- 现役一级入口为 `/creation`、`/project`、`/profile`，桌面侧边栏和移动端底部 dock 都固定显示“创作 / 项目 / 我的”。`/creation` 只读取图片编辑器项目与 `GET /api/editor/showcase/resources`，不得重新接入旧模板入口配置、旧作品架或专属运行态。
+- 旧创作模板目录和顶层旧业务模块必须持续退出 Vite、TypeScript、ESLint 与 Vitest；旧 `/api/creation-entry/config`、模板 API、公开作品详情和运行态 API 必须保持未挂载。SpacetimeDB 历史表、迁移白名单与必要兼容类型只作为数据壳保留，不得据此恢复业务逻辑。
 - 优先复用现有面板、抽屉、弹窗，不新建独立大系统。
 - 不在 UI 中默认写功能说明类文本。
 - 弹出独立面板的交互不要实现成在当前面板下方追加内容。
@@ -528,7 +533,7 @@ npm run check:server-rs-ddd

 ## 提交前建议让 Agent 执行

-涉及拼图、抓大鹅、敲木鱼统一创作 / 生成链路、Phase 2 之后的跨玩法回归或本地 dev 栈时，先按 `quality-gates/README.md`、`quality-gates/【玩法创作】跨玩法回归与冒烟门禁-2026-05-30.md` 和对应单项门禁文档执行自动脚本与体验检查。
+涉及现役编辑器、项目、精选素材、账号、钱包、公共设置或本地 dev 栈时，按对应定向测试、类型检查、Rust / SpacetimeDB 门禁、真实浏览器 smoke 与本文件当前命令验收。旧跨玩法回归和单玩法质量门禁只作历史记录，不再作为提交前现役检查入口。

 ```text
 请检查当前 git diff，指出：
@@ -102,6 +102,14 @@
 - 验证：覆盖三类任务正常成功都落透明结果与原图、原图位于透明图右侧、`generatedLayerId` 指向透明图、图标 / UI 拆分素材位于原图右侧，以及透明处理失败仍由原图单独完成占位。
 - 关联：`server-rs/crates/api-server/src/editor_project.rs`、`docs/technical/【后端架构】外部生成Worker化方案-2026-06-03.md`。

+## Vite 源码 CSS 清理插件必须早于 Tailwind 执行
+
+- 现象：生产构建通过，但本地 dev 打开主站后全页白屏，`/src/index.css` 返回 500，Vite 报 `Unknown word updateStyle`。
+- 原因：自定义 CSS 插件使用 `enforce: 'post'`，在 Tailwind/Vite 已把 CSS 转为包含 `updateStyle` import 的 JavaScript 模块后，仍调用 `postcss.parse`。
+- 处理：需要改写原始 CSS 的 transform 固定使用 `enforce: 'pre'`；最终构建产物清理继续放在 `generateBundle`，不要混用两个阶段的输入格式。
+- 验证：真实启动 `npm run dev` 后请求 `/src/index.css` 必须返回 200，并在浏览器确认 `#root` 已挂载且控制台无 CSS transform 错误。
+- 关联：`vite.config.ts`、`scripts/vite-retired-css-plugin.test.ts`。
+
 ## phase 上报的业务拒绝与传输失败不能共用字符串错误

 - 现象：provider 已经返回并保存原图，worker 上报 `processing` 时一次断连或超时就直接把任务判为失败；或者为了规避误杀而重试所有错误，导致 stale lease 的旧 worker 继续执行后处理。
@@ -127,6 +135,22 @@
 - 验证：运行触达文件的定向 `vitest`，必要时追加 `npm run typecheck`、`npm run check:encoding` 和 `git diff --check`。
 - 关联：`docs/technical/【前端测试】React组件测试准则-2026-06-26.md`、`src/components/image-editor/useCanvasGenerationDialogs.test.tsx`、`src/components/image-editor/ImageCanvasBottomToolbarView.test.tsx`。

+## Rust 并行测试不要在 await 跨度内修改进程环境变量
+
+- 现象：单独运行的异步测试稳定通过，默认并行运行整个 crate 时却看到临时目录多出其它测试的文件、文件对被拆散，或目录清理与并发写入互相竞争；Gitea Backend CI 可能表现为日志数量断言偶发增加。
+- 原因：`std::env::set_var` / `remove_var` 修改整个测试进程，不属于当前 async task。测试在 `await` 前设置目录、结束后恢复时，同一 test binary 的其它用例会在中间窗口读取该值；只锁修改环境变量的测试也无效，除非所有间接读取方都参与同一把锁。
+- 处理：文件、队列、缓存等副作用目录进入实例配置，在构造时一次性解析环境默认值，并允许测试显式注入唯一临时目录。不要靠 `--test-threads=1`、固定 sleep 或只过滤自己的文件名掩盖错误路由；纯环境解析测试只有在全部相关读写都封闭于同一 `OnceLock<Mutex<()>>` 时才使用全局锁。
+- 验证：先精确运行目标用例，再以默认并行度重复运行完整 crate；失败类测试同时执行时，各实例目录只能包含自己的输入 / 输出日志，测试结束后临时目录必须清理。
+- 关联：`server-rs/crates/platform-llm/src/lib.rs`、`server-rs/crates/api-server/src/creation_agent_llm_turn.rs`、`server-rs/crates/api-server/src/custom_world_foundation_draft.rs`。
+
+## 带 objectKey 的画布图片测试要等待换签后可见
+
+- 现象：测试点击“添加素材”后，图层状态已经写入，但立即用 `getByAltText('画布图片：...')` 偶发或稳定找不到图片；前一张图可能通过，紧接着添加的第二张失败。
+- 原因：带 `objectKey` 的画布图片通过 `useResolvedAssetReadUrl` 异步获取签名 URL，`resolvedUrl` 就绪前不会渲染带 `alt` 的 `<img>`。`user.click` 只等待点击交互完成，不等待 effect 内的换签 Promise；前一张图在后续操作期间出现只是调度时机，不是同步契约。
+- 处理：每次点击添加后分别用 `await screen.findByAltText(...)` 等待对应图片可见，再执行依赖该图层的下一步操作；不要用固定 sleep，也不要只等待最后一张图而让前面的断言依赖偶然调度。
+- 验证：先精确运行目标用例并连续重复，再运行所在测试文件和完整前端测试；删除场景仍要保留 A/B 都消失、两个删除调用和撤销不恢复已删除素材的断言。
+- 关联：`src/hooks/useResolvedAssetReadUrl.ts`、`src/components/image-editor/ImageCanvasWorldView.tsx`、`src/components/image-editor/ImageCanvasEditorAssetsIntegration.test.tsx`。
+
 ## 图片画布素材库删除要匹配 sourceResourceId

 - 现象：素材库中删除了已经生成并进入素材库的资源，但画布上对应图层仍然存在，刷新后还可能从已保存布局里恢复。
@@ -151,13 +175,13 @@
 - 验证：API 测试覆盖陶泥号组合条件、未知陶泥号、可信来源归组、`seconds.microsZ` / 极值游标和真实 / 归组 Task ID；SpacetimeDB 测试覆盖资源删除后稳定归组、部分失败批次不抢占根任务、重复拆分有界无丢失和 owner 索引分支；后台页面测试覆盖逐字输入防抖、请求取消、刷新失败保留结果、筛选请求乱序、旧分页响应失效和“用户 ID / 陶泥号”请求。再运行 `cargo test -p api-server admin_editor_asset --manifest-path server-rs/Cargo.toml`、`cargo test -p spacetime-module admin_editor_asset --manifest-path server-rs/Cargo.toml` 和 `npm run test -- apps/admin-web/src/pages/AdminEditorAssetQueryPage.test.tsx`。
 - 关联：`apps/admin-web/src/pages/AdminEditorAssetQueryPage.tsx`、`server-rs/crates/api-server/src/admin.rs`、`server-rs/crates/spacetime-module/src/editor_project_storage.rs`。

-## 后台素材缩略图不要在首次挂载时全量换签
+## 后台素材查询与精选审核缩略图不要在首次挂载时全量换签

- 现象：后台“素材查询”首批缩略图正常，继续向下滚动或读取更多后长期显示占位图；api-server journald 中已到达的 `/admin/api/assets/read-url` 可能全部是 `200`。
+- 现象：后台“素材查询”或“精选审核”首批缩略图正常，继续向下滚动、读取更多或一次加载较多审核项后长期显示占位图；api-server journald 中已到达的 `/admin/api/assets/read-url` 可能全部是 `200`。
 - 原因：列表一次挂载 80 条私有素材时，每个缩略图同时换签，会在同秒突发请求。production Nginx 的 `genarrative_admin_rps` 为 `30r/s burst=16`，超出部分在进入 api-server 前已返回 `429`，因此仅查 api-server 日志会漏掉失败请求。
- 处理：缩略图使用 `IntersectionObserver` 在进入视口附近时再调用管理端换签；对 `429` 使用有上限的退避重试，并在条目卸载后停止更新状态和安排重试。不得为单页突发放大 Nginx 通用管理端限流，也不得在单次限流失败后永久保留无图占位。
- 验证：前端定向测试覆盖首屏外的后续行进入可见区后才换签、“读取更多”追加行可继续显示缩略图、`429` 后有限重试恢复、卸载后不再重试；真实浏览器滚动验收时同时核对 Nginx access/error log、api-server journald 和 Network 面板，不以单一日志面判定成功。
- 关联：`apps/admin-web/src/pages/AdminEditorAssetQueryPage.tsx`、`apps/admin-web/src/pages/AdminEditorAssetQueryPage.test.tsx`。
+- 处理：素材查询与精选审核共用缩略图和预览组件；缩略图使用 `IntersectionObserver` 在进入视口附近时再调用管理端换签；对 `429` 使用有上限的退避重试，并在条目卸载后停止更新状态和安排重试。无 `objectKey` 的绝对 OSS generated 地址先提取 legacy path 再换签。不得为单页突发放大 Nginx 通用管理端限流，也不得在单次限流失败后永久保留无图占位。
+- 验证：前端定向测试覆盖两页共用换签组件、首屏外的后续行进入可见区后才换签、“读取更多”追加行可继续显示缩略图、`429` 后有限重试恢复、卸载后不再重试、绝对 OSS 地址换签和点击缩略图打开媒体预览；真实浏览器滚动验收时同时核对 Nginx access/error log、api-server journald 和 Network 面板，不以单一日志面判定成功。
+- 关联：`apps/admin-web/src/components/AdminEditorAssetMedia.tsx`、`apps/admin-web/src/pages/AdminEditorAssetQueryPage.tsx`、`apps/admin-web/src/pages/AdminEditorShowcaseReviewPage.tsx` 及对应测试。

 ## 陶泥儿精选重复先查同源同媒体画布副本

@@ -175,13 +199,14 @@
 - 验证：`creationShowcaseModel.test.ts` 覆盖展示名优先、陶泥号兜底和内部 owner/user id 不展示；`editorProjectClient.test.ts` 覆盖公开精选接口客户端保留公开作者字段；若改动 SpacetimeDB read model，再运行 `npm run spacetime:generate`、`cargo check -p spacetime-client -p api-server --manifest-path server-rs/Cargo.toml` 和 `npm run check:spacetime-schema`。
 - 关联：`server-rs/crates/spacetime-module/src/editor_project_storage.rs`、`server-rs/crates/spacetime-client/src/mapper/editor_project.rs`、`server-rs/crates/api-server/src/editor_project.rs`、`src/components/creation-home/creationShowcaseModel.ts`。

-## 陶泥儿精选瀑布流变宽先查 multi-column 容器宽度
+## 陶泥儿精选顺序分列不要用 multi-column 或共享 Grid 行高

- 现象：release `/creation` 桌面端精选卡片明显变宽，第三列被裁到屏幕外，页面内部可横向滑动；dev 看起来正常。
- 原因：精选瀑布流使用 `column-count`，当它作为 grid item 时如果没有显式 `width: 100%` / `min-width: 0`，Chrome 会用多列内容的 intrinsic width 反向撑开 grid track。线上实测 1920 视口下 section 为 `1296px`，waterfall 被撑到约 `2048px`，单卡宽约 `672px`。
- 处理：保留 multi-column 瀑布流时，`.creation-landing__asset-waterfall` 必须显式约束 `width: 100%` 和 `min-width: 0`；不要只看单张图片天然尺寸或改卡片宽度。
- 验证：Playwright / CSSOM 检查 `.creation-landing__section`、`.creation-landing__asset-waterfall`、首张 `.creation-landing__asset-card` 的 `getBoundingClientRect()`，waterfall 宽度应等于 section 宽度。
- 关联：`src/index.css`、`src/components/creation-home/CreationLandingView.tsx`。
+- 现象：`/creation` 桌面端主内容区明明能放下三张卡，首行却只出现一到两张，后续素材提前回到左侧下一段；活动卡与普通素材高度差较大时尤其明显。
+- 原因：`column-count` 按纵向文章列流入并平衡，三张卡可排成 `2 + 1 + 0` 列；标准 CSS Grid 虽会横向先填三张，但整行共用最高卡行轨，短卡下会留下高度差。`align-items: start` 只是不拉伸短卡，不能消除行轨空白；`grid-auto-flow: dense` 也不能填单个网格项内的剩余高度。
+- 处理：保留平面 DOM 和 `.creation-landing__asset-waterfall` 旧类名，按当前列数将第 `index` 张显式放入 `index % columns` 列；三列时第 1/2/3 张分别进入三列，第 4/5/6 张再分别接到三列下方。列数以容器实际宽度和 288px 首选最小列宽计算，不以 viewport 硬切；先设目标卡宽再测真实卡高，列内用 computed gap 紧凑堆叠。
+- 动态边界：只有当容器宽度、卡数和所有卡高有效时才进入 absolute Masonry ready；否则保留 Grid fallback。`ResizeObserver + requestAnimationFrame` 在容器变宽、图片/字体/文本改变高度、筛选重排和 cursor 追加后全量重算；cleanup 必须兼容 StrictMode，避免分页 sentinel 因容器短暂零高提前触发。
+- 验证：纯函数测试锁定容器宽度临界值、`index % columns` 和最高列容器高；样式契约同时锁定 Grid fallback 与 Masonry ready。Playwright 需在同一 viewport 内改容器宽度验证 3/2/1 列，检查每列相邻卡间距等于 gap、容器高等于最高列底、DOM 顺序不变且无重叠/横向溢出。
+- 关联：`src/index.css`、`src/index.test.ts`、`src/components/creation-home/CreationLandingView.tsx`、`src/components/creation-home/showcaseMasonryLayout.ts`。

 ## 画板外部生成排队超时不是失败

@@ -211,10 +236,18 @@

 - 现象：主站或 External API 只要拿到另一个账号的 generated `objectKey` 就能换签，已登记的私有对象因为 key 同时命中 legacy 前缀而被匿名读取，或者 `/api/assets/read-url` 已拒绝但 `/api/assets/read-bytes` 仍能读出原始字节；后台资源预览为解决跨账号读取又误把主站入口整体放开。
 - 原因：`legacyPublicPath` 与 `objectKey` 代表两种不同信任边界。前者仅用于未登记历史公开作品兼容，后者是正式对象引用；只检查 generated 前缀、或在查询 `asset_object` metadata 前直接接受 legacy 白名单，都不能证明对象公开或属于调用方。签名 URL 和 bytes proxy 如果各写一套判断也容易漂移。
- 处理：`read-url` 与 `read-bytes` 必须共用 `authorize_asset_read_target`，先按配置 bucket / 精确 key 查询 `asset_object`；metadata 一旦存在，即使 key 命中 legacy 前缀，也严格执行 `PublicRead` / owner ACL。只有 metadata 不存在且显式 `legacyPublicPath` 命中 `platform_oss::LEGACY_PUBLIC_PREFIXES` 时才允许匿名兼容；任意 `objectKey` 必须登记。External read-url 使用 API Key owner。主站和 External 的 object confirm owner 必须来自认证主体，同 bucket / key 已登记后不能改变 owner，不能让请求体 owner 接管对象。后台跨 owner 换签只用于管理员资源预览，成功后以 `admin_asset_read_url` 持久化管理员 subject、请求对象和有效期，且不得记录 signed URL；不能为此把 admin 能力下沉到主站入口。无权访问统一返回不存在，避免泄露对象是否存在。
- 验证：覆盖未登记 curated legacy public path、命中 legacy 前缀但已有私有 metadata、未登记 objectKey、公开对象、本人私有对象、跨 owner、匿名私有、External owner、confirm owner 不可变和 admin-only endpoint；对 `read-url` 与 `read-bytes` 使用同一组授权矩阵，并断言 Admin 成功换签会生成不含 signed URL 的管理员主体审计事件。
+- 处理：`read-url` 与 `read-bytes` 必须共用 `authorize_asset_read_target`，先按配置 bucket / 精确 key 查询 `asset_object`；metadata 一旦存在，即使 key 命中 legacy 前缀，也严格执行 `PublicRead` / owner ACL。只有 metadata 不存在且显式 `legacyPublicPath` 命中 `platform_oss::LEGACY_PUBLIC_PREFIXES` 时才允许匿名兼容；普通 `objectKey` 必须登记。唯一窄例外是历史精选活动卡：`global` 配置已启用、请求 key 位于 `generated-character-drafts/editor/showcase-campaign/` 且与当前 `image_object_key` 精确匹配时，可在 metadata 缺失期间派生公开读取，禁用或换图后旧 key 立即失效；新上传活动卡仍必须 confirm。External read-url 使用 API Key owner。主站和 External 的 object confirm owner 必须来自认证主体，同 bucket / key 已登记后不能改变 owner，不能让请求体 owner 接管对象。后台跨 owner 换签只用于管理员资源预览，成功后以 `admin_asset_read_url` 持久化管理员 subject、请求对象和有效期，且不得记录 signed URL；不能为此把 admin 能力下沉到主站入口。无权访问统一返回不存在，避免泄露对象是否存在。
+- 验证：覆盖未登记 curated legacy public path、命中 legacy 前缀但已有私有 metadata、未登记普通 objectKey、活动卡当前/禁用/替换/越目录 exact key、公开对象、本人私有对象、跨 owner、匿名私有、External owner、confirm owner 不可变和 admin-only endpoint；对 `read-url` 与 `read-bytes` 使用同一组授权矩阵，并断言 Admin 成功换签会生成不含 signed URL 的管理员主体审计事件。
 - 关联：`server-rs/crates/api-server/src/assets.rs`、`server-rs/crates/api-server/src/external_assets_api.rs`、`server-rs/crates/api-server/src/admin.rs`、`server-rs/crates/api-server/src/modules/admin.rs`。

+## 精选活动卡上传成功但网站空图先查对象确认和 exact grant
+
+- 现象：后台精选活动卡能保存标题、作者、尺寸和图片地址，`GET /api/editor/showcase/resources` 也返回已启用 campaign，但网站卡片只有占位区域，没有 `<img>`；Network 中活动卡的 `/api/assets/read-url?objectKey=...` 返回 `404 资源不存在或无权访问`。
+- 原因：活动卡旧上传链路只完成 signed POST 并保存 `imageSrc + imageObjectKey`，没有调用 object confirm；同时公开授权只扫描普通 `editor_showcase_asset`，没有识别当前活动卡。前端见到 `imageObjectKey` 后会优先走正式 objectKey 换签，失败时按安全规则保持空 src，不回退裸 private 路径。
+- 处理：后台上传必须按 ticket -> OSS POST -> `/admin/api/editor-showcase/campaign/image-upload-confirm` -> 写回表单执行，confirm 复用统一 OSS HEAD、bucket/长度校验和 `asset_object` upsert，并由管理员会话绑定 owner、强制 private/固定 asset kind/活动卡专用目录。读取 procedure 在同一事务中对当前 enabled global campaign 的专用目录 exact key 派生授权，使历史未登记当前卡无需重新上传即可恢复；api-server 仅接受 procedure 明确返回的这一 grant，其他未登记 objectKey 继续 404。
+- 验证：SpacetimeDB 测试覆盖 current key、disabled、missing key、replaced old key、越目录 key 和普通精选 grant；api-server 测试覆盖 metadata 缺失时 exact grant 可读、无 grant 仍 404、confirm 路径/MIME/大小/固定 private 约束；admin-web 测试锁定 ticket -> OSS -> confirm 顺序。真实浏览器应看到活动卡图片，Network 中 objectKey 换签返回 200，禁用或换图后旧 key 返回 404。
+- 关联：`apps/admin-web/src/api/adminApiClient.ts`、`server-rs/crates/api-server/src/admin.rs`、`server-rs/crates/api-server/src/assets.rs`、`server-rs/crates/spacetime-module/src/asset_metadata/objects.rs`、`server-rs/crates/spacetime-module/src/editor_project_storage.rs`。
+
 ## 编辑器生成按钮显示泥点后仍要查真实钱包预扣

 - 现象：画板生成按钮显示 `N泥点`，后端也能按模型配置计算出价格，但用户点击后钱包余额不变。
@@ -352,12 +385,12 @@
 - 验证：`npm run test -- src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.test.tsx`；`cargo test -p api-server editor_character_animation --manifest-path server-rs/Cargo.toml`。
 - 关联：`src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.ts`、`server-rs/crates/api-server/src/character_animation_assets.rs`、`server-rs/crates/api-server/src/app.rs`、`docs/【编辑器】画板角色形象生成入口设计-2026-06-15.md`。

-## 图片编辑器角色动画抽帧不要采到视频尾点
+## 图片编辑器角色动画抽帧不要采到视频尾点或逐帧重启 FFmpeg

 - 现象：画板角色图点击 `生成动画` 后，Ark 视频已生成并上传 OSS，但后端返回 `ffmpeg 已执行但未产出动作帧文件(requestId:...)`。
- 原因：FFmpeg 在 `-ss` 采样时间落到视频尾点附近时可能退出码仍为 `0`，但实际输出 `0` 帧；如果后端按 `duration - 0.001` 抽最后一帧，低帧率或短视频很容易踩到不可解码尾点。
- 处理：角色动画抽帧按目标帧数预留一个采样步长，例如 `32帧·4秒` 最后一帧采 `3.875s`，不要采 `3.999s`；`ffmpeg` 返回成功但无输出文件时，错误 details 保留 `targetSeconds`、`stdout`、`stderr` 和输出路径，用户主文案保持简短。
- 验证：`cargo test -p api-server editor_character_animation --manifest-path server-rs/Cargo.toml`，其中 `editor_character_animation_extracts_final_sample_from_short_video` 应覆盖本机 FFmpeg 8 的 0 帧回归。
+- 原因：FFmpeg 在采样时间落到视频尾点附近时可能退出码仍为 `0`，但实际输出 `0` 帧；如果后端按 `duration - 0.001` 抽最后一帧，低帧率或短视频很容易踩到不可解码尾点。旧实现还会为 `32 / 40 / 48` 个采样点分别启动 FFmpeg、重复解码同一视频，在低配 worker 上形成不必要的多秒 CPU 尖刺。
+- 处理：角色动画先按目标帧数计算全部安全采样时刻，例如 `32帧·4秒` 最后一帧采 `3.875s`，不要采 `3.999s`；随后使用单个 `setpts + split + select` filter graph 批量输出全部帧，不改用粗粒度 `fps` 抽帧。命令返回后逐一检查输出，缺帧时用户主文案保持简短，details 保留首个缺帧的 `targetSeconds / outputPath`、整批 `missingFrames` 和 stdout/stderr。
+- 验证：`cargo test -p api-server editor_character_animation --manifest-path server-rs/Cargo.toml`；`editor_character_animation_batch_extracts_all_samples_from_short_video` 必须用一次 FFmpeg 产出整批短视频帧，尾帧测试继续锁定 `3.875s`。
 - 关联：`server-rs/crates/api-server/src/character_animation_assets.rs`、`docs/【编辑器】画板角色形象生成入口设计-2026-06-15.md`。

 ## Windows 本地角色动画抽帧找不到 ffmpeg 先查 dev 子进程环境
@@ -440,6 +473,14 @@
 - 验证：测试断言菜单不包含在底部工具栏 / 参考图行里，并且生成面板打开时底部 `AI画布工具栏` 仍存在；规范参考图来源菜单应能通过 portal 点击“从画布中选择 / 上传图片”并写回规范参考图。
 - 关联：`src/components/common/PlatformFloatingMenu.tsx`、`src/components/image-editor/ImageCanvasEditorView.tsx`、`src/components/image-editor/ImageCanvasEditorGenerationIntegration.test.tsx`。

+## 图片编辑器 portal 菜单必须显式继承画板主题 token
+
+- 现象：生成视频参数面板里点击“静音”后，开关轨道和白色滑块一起消失；如果直接把轨道改成 `#00ff00`，虽然重新可见，却变成与画板主题不一致的荧光绿。相同比例、清晰度、slider、时长文字和模型选中勾选也可能丢失选中态主题。
+- 原因：`renderEditorPortal(...)` 把 `.image-canvas-editor__portal-menu` 挂到 `document.body`，它不再是 `.image-canvas-editor` 的后代，无法继承只定义在编辑器根节点上的 `--image-canvas-brand-*` 自定义属性。浏览器会把依赖缺失变量且没有 fallback 的声明按无效值处理，轨道背景最终为透明。
+- 处理：portal 继续挂到 `document.body` 以避免局部 `overflow` 裁切，但外层必须通过 `.image-canvas-editor__portal-theme` 同步当前 `platform-theme--light / platform-theme--dark`；画板品牌 token 由 `.image-canvas-editor`、主题桥接层与 `.image-canvas-editor__portal-menu` 共用同一组声明。控件继续消费主题变量，不使用单点硬编码颜色，也不要只给静音轨道补 fallback 而遗漏同一 portal 内其它 token 消费者。
+- 验证：`scripts/image-canvas-portal-theme.test.ts` 应锁定编辑器根节点、portal 主题桥接层与 portal 菜单共享完整品牌 token，静音 pressed 轨道仍使用 `var(--image-canvas-brand-accent)` 且不出现 `#00ff00`；`useImageCanvasGenerationSurface.test.tsx` 应覆盖暗色主题 class 被桥接到 `document.body` 下的 portal。真实浏览器从 `生成视频 -> 视频参数 -> 静音` 点击后，轨道 computed background 应为非透明当前主题色，portal 内 `--image-canvas-brand-accent`、`--image-canvas-brand-border-strong` 和 `--image-canvas-brand-soft` 均应有值。
+- 关联：`src/index.css`、`scripts/image-canvas-portal-theme.test.ts`、`src/components/image-editor/ImageCanvasEditorPortal.tsx`、`src/components/image-editor/useImageCanvasGenerationSurface.tsx`、`src/components/image-editor/ImageCanvasGenerationComposerView.tsx`。
+
 ## 图片编辑器规范图片面板不要脱离统一生成 shell

 - 现象：生成 UI 设计图或新建图标规范时，面板参考图、输入区和底部生成按钮相对生成图片 / 生成角色 / 生成视频错位；图标规范甚至可能缺少首行参考图入口。
@@ -994,6 +1035,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`。

+## Full Build 的维护退出节点不得 checkout Git
+
+- 现象：Full Build 的 Stdb、API 和 Web 都已发布成功，`Exit Maintenance` 进入目标部署 agent 后却先执行 `checkout scm`，用 `ssh://git@127.0.0.1:2222/...` 拉仓库并报 `Connection refused`，导致已部署的维护退出脚本根本没有执行。
+- 原因：`127.0.0.1:2222` 只是 Jenkins controller 上的 Gitea SSH 端口，在部署 agent 上代表部署机自身。该次流水线在 Jenkins 重启后恢复，Declarative 的阶段 `agent` 路径未继续遵守顶层 `skipDefaultCheckout(true)`，在 `steps` 前注入了不必要的 SCM checkout。
+- 处理：`Exit Maintenance` 保持 `agent none`，在 `steps` 内根据 `DEPLOY_TARGET` 用显式 `node(deployLabel)` 分配目标机，只从绝对路径执行 current release 已携带的 `/opt/genarrative/current/scripts/deploy/maintenance-off.sh`。不要在这个节点添加 GitSCM、Git SSH 凭据或 Jenkins workspace 相对路径。
+- 验证：运行 `npm run check:production-ops`；重放流水线时，`Exit Maintenance` 的 `Running on <deploy-agent>` 之后应直接进入 `sh`，不应出现 `checkout`、`GitSCM` 或 Git 凭据日志。
+- 关联：`jenkins/Jenkinsfile.production-full-build-and-deploy`、`scripts/check-production-ops-guardrails.mjs`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。
+
 ## Linux 多用户 dev 端口冲突先查系统级端口段注册表

 - 现象：同一台 Linux 机器上多个用户同时开发时，`npm run dev` 报端口段已被其他用户占用、同一用户已有活跃端口段，或 SpacetimeDB 复用记录指向当前用户端口段之外的地址；未手动指定时自动分配应从 `10000-10099` 起步。
@@ -1558,7 +1607,7 @@

 - 现象：配置了 `APIMART_BASE_URL` / `APIMART_API_KEY` 后，RPG、拼图或方洞的 GPT-image-2 生图仍返回缺配置，或请求体里还出现 `official_fallback` / `image_urls`。
 - 原因：2026-05-21 后 GPT-image-2 图片生成按 VectorEngine 创建/编辑接口分流；2026-07-05 后创意 Agent 文本链路也改为 VectorEngine Chat Completions `gpt-5.4-mini`，APIMart 不再作为当前创意 Agent 来源。
- 处理：为图片生成配置 `VECTOR_ENGINE_BASE_URL=https://api.vectorengine.ai`、`VECTOR_ENGINE_API_KEY`、`VECTOR_ENGINE_IMAGE_REQUEST_TIMEOUT_MS`；排查请求体时确认无参考图路径为 `/v1/images/generations`、有参考图路径为 `/v1/images/edits`，模型为 `gpt-image-2`。
+- 处理：为图片生成配置 `VECTOR_ENGINE_BASE_URL=https://api.vectorengine.ai`、`VECTOR_ENGINE_API_KEY`、`VECTOR_ENGINE_IMAGE_REQUEST_TIMEOUT_MS`；排查请求体时确认无参考图路径为 `/v1/images/generations`、有参考图路径为 `/v1/images/edits`，业务 / 计费与 provider 首发模型均为 `gpt-image-2`，仅在符合条件的 provider 失败后切到兜底模型 `gpt-image-2-c`。
 - 验证：运行 `cargo test -p api-server openai_image --manifest-path server-rs/Cargo.toml` 和相关玩法图片生成测试；真实联调只在本地私密环境放置 VectorEngine key。
 - 关联：`docs/technical/VECTOR_ENGINE_GPT_IMAGE_2_GENERATION_2026-05-09.md`、`server-rs/crates/api-server/src/openai_image_generation.rs`。

@@ -1838,6 +1887,14 @@
 - 验证：即使 `/api/auth/login-options` 返回空、失败或只返回 `["password"]`，登录弹窗也应同时显示 `短信登录`、`密码登录`、`验证码` 输入和“获取验证码”按钮；短信发送真实可用性再通过 `POST /api/auth/phone/send-code` 验证。
 - 关联：`src/components/auth/AuthGate.tsx`、`src/components/auth/LoginScreen.tsx`、`src/components/auth/AuthGate.test.tsx`、`scripts/dev-utils.mjs`、`scripts/dev.mjs`。

+## 浏览器自动填充手机号带 `+86`
+
+- 现象：登录弹窗的手机号被浏览器回填为 `+86 1xxxxxxxxxx`，点击获取验证码或登录后返回“手机号格式不正确”。
+- 原因：`autocomplete="tel"` 允许浏览器回填含国家码的完整电话号码，`inputMode="numeric"` 只提示软键盘布局，不会过滤自动填充；如果把完整号码和纯号码混在一个 `phone` 字段中，微信 `purePhoneNumber` 又与 `countryCode` 分开传递，后端容易在国家码丢失后把境外号码误判为 `+86`。
+- 处理：手机号字段保留 `autocomplete="tel"`；`authService` 在请求前把 `+86 1xxxxxxxxxx`、`86 1xxxxxxxxxx` 拆为 `countryCode=86 + purePhoneNumber=1xxxxxxxxxx`。普通认证请求缺少 `countryCode` 时默认 `86`，但微信授权必须使用 provider 真实返回的 `countryCode + purePhoneNumber`，不能默认国家码。`module-auth` 先校验国家码，再用原纯手机号规则校验 `purePhoneNumber` 并生成 E.164；数据库仍只保存 E.164。
+- 验证：`cargo test -p module-auth --manifest-path server-rs/Cargo.toml`、定向 `api-server` 认证测试和 `npm run test -- src/services/authService.test.ts src/components/auth/AuthGate.test.tsx`，覆盖省略 / 显式 `86`、境外国家码、浏览器 `+86` 自动填充以及微信 provider 国家码路径。
+- 关联：`server-rs/crates/module-auth/src/domain.rs`、`server-rs/crates/module-auth/src/errors.rs`、`server-rs/crates/api-server/src/phone_auth.rs`、`server-rs/crates/api-server/src/wechat/auth.rs`、`src/services/authService.ts`、`src/components/auth/LoginScreen.tsx`。
+
 ## 本地短信收不到验证码先查 provider

 - 现象：登录弹窗可以进入短信页签，但点击“获取验证码”后，手机没有收到短信。
@@ -3025,6 +3082,8 @@

 ## 小程序订阅消息授权不要依赖 web-view bindmessage

+> 2026-07-18：本节及下一节只作为历史记录。生成结果订阅页、H5 service、HostBridge capability 和后端发送链路已随旧创作模板业务退役，不得按这些排障步骤恢复。
+
 - 现象：拼图点击生成后，H5 以为已经请求了生成结果订阅授权，但小程序没有弹出 `wx.requestSubscribeMessage` 授权框。
 - 原因：`web-view bindmessage` / `wx.miniProgram.postMessage` 不适合承接“当前用户点击后立刻请求授权”的时序，消息可能等到 web-view 后退、分享或销毁时才派发，导致授权请求没有发生在 `compile_puzzle_draft` 前。
 - 处理：不要在原生页 `onLoad` 自动触发 `wx.requestSubscribeMessage`，真机会闪页返回且不弹授权框。H5 在 `compile_puzzle_draft` 前应先进入生成进度态并立即发起生成 action，再通过微信 JS SDK `miniProgram.navigateTo` 非阻塞跳转到小程序原生订阅页尝试请求授权；用户接受、拒绝或返回都不能阻塞生成。原生页不要改写上一页 `webViewUrl`，否则 web-view 可能重新加载首页并丢失进度页状态。后端发送订阅消息仍只允许在拼图资产成功或失败终态后执行。
@@ -3033,6 +3092,8 @@

 ## 微信订阅消息 time 字段不能用内部时间戳

+> 2026-07-18：该能力已退役，本节不再作为现役排障入口。
+
 - 现象：dev 服务器拼图资产生成终态后已经调用订阅消息发送，但日志出现 `微信订阅消息发送失败：argument invalid! data.time4.value invalid`，用户收不到生成结果通知。
 - 原因：微信模板 `time` 字段不接受内部微秒时间戳、秒级时间戳或带 `Z` / 时区后缀的字符串；发送 `1713686401.234567Z` 或类似 `2026-06-08 08:09:18Z` 会被微信拒绝。
 - 处理：`api-server` 构造生成结果订阅消息时，`time4` 固定格式化为北京时间 `YYYY-MM-DD HH:mm`；不要复用 `shared_kernel::format_timestamp_micros`。
@@ -3468,8 +3529,8 @@

 - 现象：看到最新 `N.snapshot_dir` 后，把所有起始 offset 小于 `N` 的 `.stdb.log` 删除，或者只把旧日志上传 OSS 就宣称已有完整增量灾备。
 - 原因：segment 文件名只表示该段最早事务；起始 offset 小于等于最新 snapshot 的最后一个 segment 可能跨越 snapshot 边界，重启仍需要它。历史归档也不会及时覆盖 control-db、program bytes、最新 snapshot 和 active segment。
- 处理：latest snapshot 必须是未锁定且存在同 offset `.snapshot_bsatn` 的完整目录，空目录或同名 `.lock` 存在时忽略。每个 replica 独立保留 `max(segment_start <= latest_snapshot)` 及全部后缀，只处理更早 segment 对；旧 snapshot 只保留最新一个。`--storage-format files` 必须先发布完整 full catalog；history 对每个候选文件 CAS 对象、history catalog 和 full catalog 执行 HEAD 长度/SHA 验真，再复算边界与 stat fingerprint，最后发布并验真固定 `latest.json`；pointer 失败时不得推进 state 或删除源文件。不要把在线逐文件 full 扫描当成跨文件一致备份，基线必须来自停库目录或已验证冻结副本。SSH 或工具超时后先检查 work-dir PID lock 与原进程，不要直接并发重跑；不要在 history 模式传 `--stop-service`。定时任务通过 Server-Provision 的显式 profile 和仓库 drop-in 管理，启用前 dry-run 验证 baseline，切回 archive 时同时移除托管与现场遗留 drop-in；不要在 `/etc/systemd/system` 长期保留手写覆盖，release 必须建立和验证自己的 full baseline 与 work-dir，不能直接复用 dev 的本地 state。
- 验证：dry-run 输出 replica 的 `latestSnapshot`、`boundarySegment` 和候选清单；从另一台机器仅凭 OSS `latest.json` 自动定位 full catalog，创建目录、下载文件并逐项校验长度/SHA，启动隔离 data-dir 验证 `/v1/ping`、snapshot restore、commitlog replay、module launch、代表性 SQL 与 reducer。
+- 处理：latest snapshot 必须是未锁定且存在同 offset `.snapshot_bsatn` 的完整目录，空目录或同名 `.lock` 存在时忽略。每个 replica 独立保留 `max(segment_start <= latest_snapshot)` 及全部后缀，只处理更早 segment 对；旧 snapshot 只保留最新一个。`--storage-format files` 必须先发布完整 full catalog；history 对每个候选文件 CAS 对象、history catalog 和 full catalog 执行 HEAD 长度/SHA 验真，再复算边界与 stat fingerprint，最后发布并验真固定 `latest.json`；pointer 失败时不得推进 state 或删除源文件。不要把在线逐文件 full 扫描当成跨文件一致备份，基线必须来自停库目录或已验证冻结副本。SSH 或工具超时后先检查 work-dir PID lock 与原进程，不要直接并发重跑；不要在 history 模式传 `--stop-service`。定时任务通过 Server-Provision 的显式 profile 和仓库 drop-in 管理，启用前 dry-run 验证 baseline，切回 archive 时同时移除托管与现场遗留 drop-in；不要在 `/etc/systemd/system` 长期保留手写覆盖，release 必须建立和验证自己的 full baseline 与 work-dir，不能直接复用 dev 的本地 state。files 本地 state 只能保存去重后的 catalog 引用并使用 gzip 原子落盘；本地只保留 latest full catalog 压缩缓存，history/旧 full catalog 和紧凑 result 不得再次复制完整清单。metadata 压缩或清理失败必须早于 `/stdb` history 源文件删除。
+- 验证：dry-run 输出 replica 的 `latestSnapshot`、`boundarySegment` 和候选清单；从另一台机器仅凭 OSS `latest.json` 自动定位 full catalog，创建目录、下载文件并逐项校验长度/SHA，启动隔离 data-dir 验证 `/v1/ping`、snapshot restore、commitlog replay、module launch、代表性 SQL 与 reducer。备份门禁还必须覆盖 v1 JSON 到 v2 gzip 迁移、损坏 gzip 不回退、full 增量复用、本地 catalog SHA 校验、history catalog 清理与紧凑 result。
 - 关联：`scripts/database-backup-to-oss.mjs`、`scripts/check-database-backup-to-oss.mjs`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。

 ## Procedure 事务鉴权要兼容 SpacetimeDB 2.6.0 的匿名 TxContext
@@ -3684,3 +3745,92 @@
 - 原因：Runtime 工具最终只接受项目相对路径，但 Provider 不一定始终遵守提示；交接层此前只能拒绝全部绝对路径，无法区分“当前项目内、可无损转换”的输入与项目外越界输入。
 - 处理：成功响应写入 tool-plan handoff 前，只对内置 Runtime 原生函数和 legacy tool-plan wrapper 的合法、无重复 key JSON arguments 按工具 schema 的精确位置做规范化；仅改写完整字符串且位于当前项目根目录内的 `file.*.path`、`project.patchset.changes[*].path`、`project.git_commit.paths[*]`、`command.*.cwd`、`image.inspect.paths[*]` 与 `canvas.asset_generate.outputPath` 等真实路径字段。源码/叙述字段、任务产物描述和动态 MCP arguments 不改写。项目外绝对路径、畸形或重复 key JSON、敏感 key 和真实凭据继续失败关闭。规范化后的 handoff 同时作为当前进程执行值和重启 replay 值，避免 live/restart 语义漂移。
 - 验证：覆盖项目内 `path`、项目根 `cwd`、`paths` 数组的相对化与落账重放，源码 `content` 原文保持不变，动态 MCP 和项目外绝对路径仍拒绝，并运行全部 tool-plan handoff 回归。
+- 关联：`src/components/project/ProjectGalleryView.tsx`、`src/components/image-editor/EditorAgentConversation/EditorAgentConversationPanelView.tsx`、`src/components/common/PlatformToolModalShell.tsx`、`src/components/common/UnifiedModal.tsx`。
+
+## 待用户确认的 Agent 工具不能依赖模型自行结束回合
+
+- 现象：画布 Agent 已生成有效工具规划，却最终只保存 `ERROR max turns reached: 3`，助手文本和待确认工具卡都消失。
+- 原因：八类画布工具的 `call()` 只返回待用户确认的规划结果，但 function-calling runner 在成功工具后仍继续请求 LLM，只靠 prompt 要求模型不再重试；模型连续返回工具调用直到上限后，错误结果又丢弃此前累积的输出。
+- 处理：工具通过框架契约显式声明 `requires_user_confirmation`；当本批全部工具都成功且等待确认时，runner 在处理完整批次后立即返回已有助手文本和工具结果。未知工具、参数错误、hook skip、普通连续工具和不可解析响应仍继续受 `max_turns` 门禁保护。不要用单纯提高轮次上限掩盖终止条件缺失。
+- 验证：runner 回归测试必须同时覆盖“待确认工具只调用一次 LLM 并成功结束”和“普通连续工具仍会触发 max-turn 门禁”。
+- 关联：`server-rs/crates/platform-editor-agent/src/framework/run.rs`、`server-rs/crates/platform-editor-agent/src/framework/tool.rs`、`server-rs/crates/platform-editor-agent/src/agent/tools/`。
+
+## 画布 Agent 的规划请求不能关闭瞬时失败重试
+
+- 现象：美术 Agent 对话返回红色错误气泡 `completion error: LLM 请求超时，累计尝试 1 次`；HTTP 本身仍返回 200，前端 20 分钟 transport timeout 没有触发。
+- 原因：规划请求虽然有 Agent 专用单次 timeout，但 `editor_agent_llm_client` 把 `max_retries` 硬编码为 0；VectorEngine `gpt-5.4-mini` 的偶发长尾、连接超时或可重试上游状态会在第一次失败后直接持久化成 system error。framework 的英文 `completion error` 前缀也被原样暴露给用户。
+- 处理：120 秒改为前端软提示阈值：POST 仍 pending 时显示不入库的“仍在处理中，请耐心等待”；provider 明确断开/失败才写正式错误。专用 provider 单 attempt 使用 8 分钟 hard timeout，请求发起阶段读取 `GENARRATIVE_LLM_MAX_RETRIES`，但画布 Agent 最多重试 1 次且重试退避最多 60 秒。不要只计算单次 complete 的最坏时间：runner 还可因非法 JSON/工具校验失败进入后续轮次，必须从 handler 入口开始计算 18 分钟总 deadline，进入 `agent.prompt(...)` 时扣除会话锁/上下文准备已用时间，为持久化和前端 20 分钟 timeout 留出余量。响应头后的体读取/解析错误按明确失败收口，必须使用真实 attempt 计数；规划、配置和定价错误对用户统一为中文，原始诊断只记后端日志。重试发生在任何生成工具执行前，不会重复提交生成任务或扣费，不要通过提高前端 timeout 或 runner `max_turns` 掩盖 provider 重试缺失。
+- 验证：`platform-editor-agent` 测试锁定 8 分钟 hard timeout 与中文错误；前端 fake timer 用例锁定 120 秒前只显示思考动画、到点后显示耐心等待、成功/失败后移除；`platform-llm` 回归用例锁定第二次 attempt 成功响应头后的 body timeout 仍报累计 2 次；`api-server` 测试锁定专用 client retry、18 分钟整体 deadline 与中文直达错误。运行态排障按同一 request id 对齐 `platform_llm` failure stage 与 `/messages` 总耗时，并确认仍 pending 的请求不再在 120 秒形成错误气泡。
+- 关联：`server-rs/crates/platform-editor-agent/src/agent/agent.rs`、`server-rs/crates/platform-editor-agent/src/framework/error.rs`、`server-rs/crates/api-server/src/state.rs`、`src/components/image-editor/EditorAgentConversation/useEditorAgentConversation.ts`、`src/components/image-editor/EditorAgentConversation/MessageBubble.tsx`、`src/services/image-editor/editorAgentClient.ts`。
+
+## 前端退役目录不能只靠扫描和 ignore 隔离
+
+- 现象：Tailwind `@source`、TypeScript 根 `include`、ESLint ignore 和 Vitest include 都排除了旧创作目录，但干净打开新版页面时，Vite 仍转换 `services/rpg-entry/index.ts`，构建产物也包含旧作品库和旧 profile 逻辑。
+- 原因：现役模块的静态 import 会让 Vite、TypeScript 和打包器递归解析依赖；watch ignore 只停止监听，Tailwind source 只控制 class 扫描，tree-shaking 也发生在模块已经加载之后。经 barrel 只取一个公共函数尤其容易把同文件的旧导出一起带回图中。
+- 处理：把仍在用的公共账号 / 钱包 / 设置能力迁到明确的现役 client 与 presentation model；Vite `pre` transform 对退役模块真实路径直接失败，ESLint 在现役源上增加 restricted imports。每次恢复公共 UI 后用 `tsc --listFilesOnly` 和全新浏览器 context 复核，不能用已有 HMR 会话判绿。
+- 关联：`vite.config.ts`、`.eslintrc.cjs`、`src/services/platform-entry/`、`docs/technical/【架构下线】旧创作模板业务退役方案-2026-07-17.md`。
+
+## SpacetimeDB schema guard 的基线不能递归扫描保留源码
+
+- 现象：旧业务按“数据壳保留、业务实现退役”落地后，`check:spacetime-schema` 报几十个 `legacy_schema` 与原路径 accessor 重复；同一提交对自身比较也失败，但 `cargo` 实际可以正常编译 module。
+- 原因：当前工作树按 `Cargo.toml [lib].path` 的 crate root 可达模块扫描，基线提交却通过 `git ls-tree -r` 扫描整个 `spacetime-module/src`。原 `src/lib.rs` 和旧业务源码只供追溯、不进入 active crate，但基线全目录扫描仍会把它们与 `#[path]` 引入的历史数据壳同时解析。
+- 处理：current 与 base 必须各自读取所在快照的 Cargo manifest，并沿各自 `mod` / `#[path]` 图扫描；base 文件存在性和内容从该 Git tree 读取，不能复用当前工作树。不要忽略 `legacy_schema`、删除历史源码或吞掉 base duplicate，因为历史数据壳正是正式 schema，真实可达重复仍须失败。
+- 验证：回归测试同时覆盖“不可达旧源码同 accessor 不报错”和“两个可达模块同 accessor 仍失败”；再运行 `npm run check:spacetime-schema -- --base-ref HEAD`，确认 self-base 按当前 136 张表通过。
+- 关联：`scripts/check-spacetime-schema-guard.mjs`、`scripts/check-spacetime-schema-guard.test.ts`、`server-rs/crates/spacetime-module/Cargo.toml`、`docs/technical/【架构下线】旧创作模板业务退役方案-2026-07-17.md`。
+
+## VectorEngine 请求超时不能脱离 worker 绝对预算（2026-07-20）
+
+- 现象：VectorEngine 单次请求超时大于 worker job 执行预算时，worker 已停止续租，provider 才超时或开始重试；最终 lease 过期、任务失败并退款，上游却可能继续消耗资源或迟到成功。
+- 原因：单 attempt timeout、重试退避、图片下载与 worker / lease 分别使用独立的相对计时，没有共享同一绝对 deadline；只抬高 worker timeout 或单独压低 provider timeout 都无法保证留出终态写回窗口。
+- 处理：实际调用 VectorEngine 的四类图片 job 使用 `1800s` long 预算；从 job 开始的同一起点派生 provider deadline，常规提前 `60s`、短预算提前一半。每次 attempt、退避、下一次 attempt 和图片下载都必须在该 deadline 内；普通 HTTP / `inline` 不伪造 worker deadline。修复时不改动 lease fencing、迟到写回仲裁和原子退款语义。
+
+## 同一 Rust 二进制的本地双进程不能各自并发 watch 重启（2026-07-21）
+
+- 现象：本地把 `api-server` 与独立 `bgfilter-worker` 都用 `cargo run -p api-server` 启动后，一次 Rust 源码变更触发两套 watcher 并发停止、编译和链接；Windows 常因另一个实例仍占用 `api-server.exe` 而链接失败，或出现 API 已恢复但内部 worker 尚未 ready 的半更新状态。
+- 原因：两个进程角色共享同一 crate、target 和可执行文件，却被错误地当成两个互不相关的 dev service。更危险的是先启动 `GENARRATIVE_PROCESS_ROLE=all` 的 API：它会立即消费外部生成队列，可能在内部 BgFilter worker 尚未 ready 时领取任务。
+- 处理：`npm run dev` 与 `npm run dev:api-server` 只创建一套 Rust watcher，并把两个进程作为组合重启单元：先停止 API 与 BgFilter worker，再只让 worker 的 `cargo run` 完成必要构建，等待 worker `/readyz`，最后启动并验活 API。交互 `rs api-server`、`rs bgfilter-worker` 在完整栈内也必须走同一组合重启。`ProcessRole::All` 永远不内嵌 BgFilter listener；父子进程共享解析后的内部 base URL / Token，Linux 第五端口固定为端口段 `start + 4`，Windows 把第五端口纳入统一探测和漂移。
+- 验证：定向测试断言组合重启顺序为“stop API → stop worker → start/ready worker → start/ready API”，`dev:api-server` 自动带起同 runner worker，端口解析得到五个互不冲突的端口；再运行 `node --check scripts/dev.mjs`、dev-stack 定向测试和编码检查。
+- 关联：`scripts/dev.mjs`、`scripts/dev-stack-port-utils.mjs`、`.hermes/skills/genarrative-dev-stack-port-routing/SKILL.md`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。
+
+## 固定 digest 不等于每个 CI job 都要强制拉镜像
+
+- 现象：四个 Gitea Actions job 在约 20 秒内同时失败，checkout 和测试都没开始；setup 日志显示 Docker 对已固定的 `docker.gitea.com/runner-images@sha256:...` 发起 manifest HEAD，随后以 `net/http: TLS handshake timeout` 结束。
+- 原因：镜像 label 固定 digest 只防止内容漂移；`container.force_pull: true` 仍会让每个 job 调用 Docker image create/pull 并依赖 registry 即时可用，即使 rootless Docker 本地已有该精确 RepoDigest。并发四个 job 还会同时放大同一外网 TLS 故障。
+- 处理：继续使用完整 digest，把 Runner 设为 `force_pull: false`；首次部署或变更 digest 时，在切换 label 前对精确 digest 执行有界重试拉取，并用内层 `docker image inspect` 核对 RepoDigest。保留上一份 runner 配置和已验证镜像备份，切换失败时回滚配置，不改用浮动 tag。
+- 验证：重启 runner 后先等待内层 `docker info` 就绪，再 inspect 精确 digest 并确认 runner declare；重跑真实 PR 的四个 job，必须越过原先的启动失败窗口。运行中 job 仍要复核 `Privileged=false`、`Binds=[]`、`MaskedPaths=[]`、`ReadonlyPaths=[]` 和独立网络，防止稳定性修正意外放宽隔离。
+- 关联：`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`、`docs/project-memory/shared-memory/development-workflow.md`。
+
+## 四个 Gitea CI job 不要重复现场安装固定工具链
+
+- 现象：`Repository checks`、`Frontend tests`、`Backend tests` 和 `Native shell tests` 都从全新 job 容器开始，apt、setup-node、rustup 和原生系统库在不同 job 里重复安装；后端与原生壳的安装时间可达数分钟，并把软件源和代理瞬时失败放大为四份。
+- 原因：Gitea Actions job 彼此隔离，上一个 job 在容器内安装的包不会自动进入下一个 job；把同一套不随 PR 变化的工具链写在 workflow step 中，必然每次重做。
+- 处理：用 `deploy/container/gitea-ci-job.Dockerfile` 预装 Node 22、Rust 1.96、`rustfmt`、Chrome、`bwrap`、`rg`、`ffmpeg`、`clang/lld` 和 Tauri / 后端系统依赖，并按锁预热根 npm、server-rs 与桌面壳 Cargo 下载缓存。四个 job 统一 `runs-on: genarrative-ci`，先用镜像内脚本直接从 Gitea checkout，再以 runtime 模式运行 `scripts/check-gitea-ci-job-image.sh`，同时检查缓存锁、工具链、完整 bwrap 与 Chrome headless。`RUSTUP_AUTO_INSTALL=0`；`rust-toolchain.toml` 变更时先重建镜像，不把下载 fallback 放回 job。
+- 依赖边界：每个 job 仍必须各自执行 `npm ci`，让当前 lockfile 和 PR 依赖在干净环境中验证；区别是命中镜像 cache 时只做本地解包，锁新增依赖时才走受控网络。不要把 `node_modules` 或 Cargo `target` 烘进镜像，也不要向不受信任 PR 挂载跨 job 可写 cache。
+- 锁漂移边界：runtime 校验输出 `server_rust_cache_lock=partial` 说明镜像内 Cargo lock 与当前 checkout 不同，不代表新增 crate 已经缓存。必须在新镜像中以 `--network none` 对当前 lock 执行真实 `cargo fetch/build --offline`；`cargo metadata --no-deps` 不会证明依赖 archive 可用，不能作为替代。
+- 构建网络边界：`CARGO_NET_RETRY` 只覆盖部分 crate 下载，registry `config.json` / index TLS 握手仍可能直接终止整次 fetch。Dockerfile 对每个 `cargo fetch --locked` 再做最多 5 次整命令级有界重试，最终仍执行断网 fetch，不能降低为无锁重试或省略离线闭合验证。
+- 验证：workflow 不再出现 GitHub checkout action、apt、setup-node 或 rustup 安装 step；镜像在 `--network none` 下能按当前 npm / Cargo lock 完成依赖准备，四个 job 的环境校验、干净 `npm ci` 和原有测试门禁仍全部执行。
+
+## Gitea CI 预构建镜像不能只靠 tag 判断内容
+
+- 现象：宿主已重建带日期修订 tag 的 `genarrative/gitea-project-ci` 镜像，但 `genarrative-ci` job 仍跑旧内容，或直接报 image not found；另一种危险操作是只改 runner label，没把对应镜像装入 rootless runner 的内层 Docker。
+- 原因：宿主 Docker 和 runner 内层 Docker 是两个镜像库，同名 tag 可指向不同 Image ID。基础镜像 digest 和 Node tarball 哈希能锁定关键输入，但重建后仍必须把最终完整 Image ID 当作 runner 映射的事实源，不能从 tag 名推断二进制内容。
+- 处理：使用 `scripts/gitea-ci-job-image.sh build/verify`，用 `export` 在仓库外保存镜像归档与便携 SHA-256 sidecar，再用 `load-runner` 将镜像导入内层、比对两侧 Image ID 并执行 bwrap / Chrome canary。确认无活跃 job 后，把当前 config 备份到仓库外受控位置，再将 `genarrative-ci` 映射到新的 `docker://sha256:...` 并执行 `docker restart --timeout 660 gitea-runner`。保持内层 Docker 持久化和 `force_pull: false`；精确 ID 缺失时失败关闭，不回退浮动 tag。
+- 验证与回滚：重启后先跑真实 PR 的四个 job，再清理旧镜像。失败时先把 workflow `runs-on` 改回 `ubuntu-latest`，再恢复 runner config 备份并重启；不在 Git、共享文档或日志中记录 config 备份路径、注册信息或 token。
+- 重启边界：`docker restart --timeout 660` 只设置容器停止宽限，不能替代 Runner drain。rootless DinD supervisor 可能与 runner 同时停止内层 dockerd，使仍在收尾的 job 因连接关闭被标记失败；切换前必须同时确认 Gitea 没有 `in_progress` run 且内层 `docker ps` 为空。误触发时只重跑受影响的失败 job，不重跑已成功项。
+- 关联：`deploy/container/README.md`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`、`docs/project-memory/shared-memory/development-workflow.md`。
+
+## 生产 API 发布重装 worker unit 不能丢失自定义路径（2026-07-23）
+
+- 现象：Server-Provision 已按自定义 current link 和 env 路径安装 worker systemd unit，但下一次 API 发布后，worker 可能重新读取 `/opt/genarrative/current` 与 `/etc/genarrative/*.env`；默认路径仍有旧 release 时，服务 active 和部署成功都不能证明新二进制已运行。
+- 原因：发布包中的 BgFilter、external-generation worker 和 controller unit 是带默认路径的模板；deploy 若直接 `install` 原文件，会覆盖 provision 已渲染的目标机 unit。external-generation 专属 env 还是可选加载，错误路径可能不会阻止服务进入 active。
+- 处理：API deploy 安装三个 unit 前必须按本次 current、API env 和各角色 env 参数渲染临时文件，安装后保留 release 内原始模板不变；controller 自定义 env 由 `--controller-env-file` 显式传入。API Deploy 与 Full Job 必须同步暴露并透传 controller/BgFilter env，不能让流水线回退默认路径。自定义服务名表示沿用目标机自管 unit，不进入默认 unit 安装分支。
+- 验证：部署 guard 使用临时自定义绝对路径，直接读取实际安装目录中的三个 unit，核对 `WorkingDirectory`、`ExecStart`、共享 API env 与角色 env，不能只用 fake `systemctl is-active` 判绿。
+- 关联：`scripts/deploy/production-api-deploy.sh`、`scripts/check-production-api-deploy.mjs`、`scripts/jenkins-server-provision.sh`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。
+
+## 通用灰度后台页不能依赖已退役业务配置
+
+- 现象：通用 `feature_gate_config`、`/admin/api/feature-gates` 和现役功能 gate 仍在，但后台“灰度发布”Tab 随旧创作模板入口一起消失；Rust 权限仍可授予 `gray-release`，前端却没有对应路由。
+- 原因：灰度页同时请求通用 gate 与旧 `/admin/api/creation-entry/config`，并把 `creation-entry:*` 动态目标和现役固定目标混在同一页面；按页面清理旧入口时连带摘除了通用控制面。
+- 处理：灰度页只能以 `/admin/api/feature-gates` 为数据源，固定目标列表只登记现役功能；新增或退役业务 target 只修改固定目标注册，不得让通用页面依赖业务列表接口。旧 `creation-entry:*` 目标、接口和页面保持退役。
+- 验证：`adminRoutes` 必须包含 `gray-release`，admin-web TypeScript/ESLint/Vitest 不得排除灰度页；页面测试必须断言只请求 feature-gates，并继续覆盖现役固定 target、直接 Gate Key 保存与新 target 状态重置。
+- 关联：`apps/admin-web/src/pages/AdminGrayReleaseConfigPage.tsx`、`apps/admin-web/src/app/adminRoutes.ts`、`server-rs/crates/api-server/src/modules/admin.rs`、`docs/technical/【架构下线】旧创作模板业务退役方案-2026-07-17.md`。
@@ -1,6 +1,6 @@
 # Genarrative 项目共享概览

-更新时间：`2026-07-17`
+更新时间：`2026-07-23`

 ## 一句话定位

@@ -10,12 +10,7 @@ Genarrative / 陶泥儿是一个 AI 原生互动内容与小游戏平台，把 A

 ## 当前主要能力

- RPG / 自定义世界创作与运行时。
- 拼图玩法创作、草稿、发布、运行态和排行榜。
- 拼消消玩法创作、素材图集生成、结果页、发布、统一作品详情、正式运行态和基础统计。
- 敲木鱼玩法创作、草稿、发布、运行态、公开详情和分享码。
- 抓大鹅 Match3D 创作、2D 多视角素材生成、发布和运行态。
- 大鱼吃小鱼、方洞挑战、视觉小说、汪汪声浪和儿童向寓教于乐玩法。
+- 图片画布编辑器、项目与资产管理。
 - 账号、短信 / 密码 / 微信登录、个人资料、任务、钱包、邀请码、充值、反馈、法律信息和后台管理。

 ## 当前入口
@@ -26,7 +21,7 @@ Genarrative / 陶泥儿是一个 AI 原生互动内容与小游戏平台，把 A
 - 小程序 WebView 外壳：`miniprogram/`。
 - 法律文本：`media/files/user_agreement.md`、`media/files/privacy_policy.md`、`media/files/disclaimer.md`。

-移动端一级 Tab：`推荐 / 发现 / 我的`。桌面端导航保留 `创作` 并新增 `项目`，其中 `/creation` 是独立创作工具主页，`/project` 是画布项目入口。
+桌面端侧边栏和移动端底部 dock 的一级入口统一为 `创作 / 项目 / 我的`。`/creation` 是独立创作工具主页，`/project` 是画布项目入口，`/profile` 是“我的”稳定路由，继续承载账号、钱包、统计和通用设置等平台公共能力；刷新及浏览器前进 / 后退必须保持当前入口与选中态一致。

 ## 当前后端路线

@@ -36,7 +31,7 @@ Genarrative / 陶泥儿是一个 AI 原生互动内容与小游戏平台，把 A
 server-rs + Axum + SpacetimeDB
 ```

-当前 SpacetimeDB crate、SDK、CLI / standalone、生成 bindings 和容器压测镜像统一按 `2.6.1` 对齐；遇到版本不匹配时先升级到 `server-rs/Cargo.toml` 锁定版本，升级后重启对应 SpacetimeDB 进程再重试。
+当前 SpacetimeDB crate、SDK、CLI / standalone 和生成 bindings 统一按 `2.7.0` 对齐；官方 CLI / standalone 发行包与容器镜像使用 `v2.7.0-hotfix3` 资产标签，二进制仍报告 `2.7.0`。遇到版本不匹配时先升级到 `server-rs/Cargo.toml` 锁定版本，升级后重启对应 SpacetimeDB 进程再重试。

 职责边界：

@@ -50,6 +45,8 @@ server-rs + Axum + SpacetimeDB

 明确废弃：旧 `server-node`、Express、PostgreSQL、Go 服务端、`maincloud`、人工 `spacetime --root-dir` 口径，以及前端承接正式业务真相的路线。

+全部旧创作模板及其创作、生成、发布、公开业务详情与专属运行态已于 2026-07-17 退役。相关历史持久化表只以最小 schema 数据壳继续参与 `spacetime-module` 编译，迁移白名单与历史数据保持不变；旧前端、API、worker、procedure/reducer 和纯业务 crate 源码仅供追溯，不属于当前编译或运行能力。
+
 ## 当前文档入口

 - `docs/README.md`
@@ -1,5 +1,7 @@
 # 【前端架构】Platform Selection Stage Model 收口计划

+> 2026-07-18 退役覆盖：本文涉及旧玩法 stage、生成页、结果页、公开详情和运行态的规则仅作为历史设计记录，不再进入现役前端编译链。当前稳定入口为 `/creation`、`/project` 与 `/profile`。
+
 ## 背景

 `PlatformEntryFlowShellImpl.tsx` 在受保护数据失效后会清空当前用户的私有作品、运行态、草稿 notice 和生成状态。清理完成后，壳层还要判断当前 `SelectionStage` 是否还能继续展示：公开首页、公开详情、工作台入口等阶段可保留；结果页、生成页、运行态、个人反馈等依赖私有数据或运行态快照的阶段必须回到首页。
@@ -68,7 +68,7 @@
 ## 第六阶段模块

 - `ImageCanvasInteractionModel.ts`
-  - 承载画布交互纯计算：适合视图、中心缩放、普通滚轮纵向滚动、Ctrl / Cmd 滚轮缩放、画布坐标换算、框选命中、平移、生成占位框拖拽、图层拖拽吸附、小地图投影、小地图点击定位和小地图拖拽视图移动。
+  - 承载画布交互纯计算：适合视图、中心缩放、普通滚轮按原始 `deltaX / deltaY` 二维平移、Shift 且 `deltaX = 0` 时由输入适配层把 `deltaY` 映射为横向位移、Ctrl / Cmd 滚轮缩放、画布坐标换算、框选命中、平移、生成占位框拖拽、图层拖拽吸附、小地图投影、小地图点击定位和小地图拖拽视图移动。
  - 主视图继续负责 React 事件对象、pointer capture、history 快照、生成对象回写、选中态和 `setState`。
  - 该模块用独立单测覆盖小地图灵敏度、吸附、多选拖拽和滚轮缩放等之前容易回退的交互规则。

@@ -151,7 +151,7 @@
 ## 第十七阶段模块

 - `useImageCanvasViewportControls.ts`
-  - 承载画布视口控制：`viewport`、`canvasSize`、小地图投影、适合视图、中心缩放、普通滚轮纵向滚动、Ctrl / Cmd 滚轮缩放、屏幕点到画布 / 世界坐标换算和小地图点击 / 拖拽移动视图。
+  - 承载画布视口控制：`viewport`、`canvasSize`、小地图投影、适合视图、中心缩放、普通滚轮按原始 `deltaX / deltaY` 二维平移、Shift 且 `deltaX = 0` 时的横向位移适配、Ctrl / Cmd 滚轮缩放、屏幕点到画布 / 世界坐标换算和小地图点击 / 拖拽移动视图。
  - 主视图继续负责图层拖拽、生成占位框拖拽、框选、多选、历史触发时机、上传 drop 分流和小地图 pointer down 事件；该 hook 只作为视口控制协调器，不接管画布完整 pointer 状态机。
  - 该 hook 用独立单测覆盖尺寸同步、适合视图、中心缩放、坐标换算、滚轮语义和小地图移动，为后续抽 `useImageCanvasStageInteractions` 预留更清晰的视口接口。

@@ -1,6 +1,6 @@
 # 后台管理多账号与 Tab 访问权限方案

-更新时间：`2026-07-14`
+更新时间：`2026-07-23`

 ## 1. 文档定位

@@ -10,12 +10,12 @@

 ## 2. 当前基线与目标

-当前后台由 `GENARRATIVE_ADMIN_USERNAME`、`GENARRATIVE_ADMIN_PASSWORD` 提供唯一管理员账号，`apps/admin-web/src/app/adminRoutes.ts` 定义 18 个一级 Tab，`server-rs/crates/api-server/src/modules/admin.rs` 中的后台路由只校验统一的管理员 JWT。
+当前后台由 `GENARRATIVE_ADMIN_USERNAME`、`GENARRATIVE_ADMIN_PASSWORD` 提供唯一管理员账号，`apps/admin-web/src/app/adminRoutes.ts` 定义 15 个可分配业务 Tab，并另有 owner-only 的“账号管理”Tab；`server-rs/crates/api-server/src/modules/admin.rs` 中的后台路由只校验统一的管理员 JWT。

 改造后的目标如下：

 1. 现有环境变量账号升级为 `owner`，仍由部署环境提供，不迁移、不复制到 SpacetimeDB。
-2. owner 始终拥有全部 18 个业务 Tab 权限，并独占“账号管理”Tab 和账号管理 API。
+2. owner 始终拥有全部 15 个业务 Tab 权限，并独占“账号管理”Tab 和账号管理 API。
 3. owner 可以创建、修改、启停 member；member 保存在 SpacetimeDB 私有表 `admin_account`。
 4. member 按一级 Tab 分配权限；获得一个 Tab 权限即获得该页面内全部读写能力，页面内部二级 Tab、弹窗和操作区继承一级权限。
 5. member JWT 每次请求都重新读取当前账号并校验 `enabled`、`token_version` 和实时权限，权限、密码或启停变更应立即让旧 JWT 失效。
@@ -26,7 +26,7 @@

 - owner 用户名和密码继续读取 `GENARRATIVE_ADMIN_USERNAME`、`GENARRATIVE_ADMIN_PASSWORD`。
 - owner 是环境变量构造的虚拟账号，不写入 `admin_account`，不允许通过后台改名、改密、禁用或删除。
- owner 始终拥有本文列出的全部 18 个可分配权限，不能在前端取消，也不从数据库加载权限。
+- owner 始终拥有本文列出的全部 15 个可分配权限，不能在前端取消，也不从数据库加载权限。
 - “账号管理”是 owner-only 能力。它可以作为新增一级路由 `accounts` / `#accounts` 展示，但 `accounts` 不进入 `ADMIN_TAB_PERMISSIONS`，不能写入 member 的 `permissions_json`。
 - owner 会话返回 `accountRole = "owner"`、`roles = ["admin", "owner"]`；账号管理权限必须根据服务端确认的 `accountRole` 判断，不能只相信前端角色字符串。
 - owner 配置缺失时，后台整体保持未启用状态；不能依赖数据库中的 member 绕过 owner 引导配置启动后台。
@@ -41,7 +41,7 @@

 ## 4. 权限标识

-`ADMIN_TAB_PERMISSIONS` 必须是 shared-contracts 与 admin-web 共用的闭合集合，值与现有 `AdminRouteId` 一致。18 个可分配权限如下，顺序同时作为前端寻找“第一可访问项”的稳定顺序：
+`ADMIN_TAB_PERMISSIONS` 必须是 shared-contracts 与 admin-web 共用的闭合集合，值与现有 `AdminRouteId` 一致。15 个可分配权限如下，顺序同时作为前端寻找“第一可访问项”的稳定顺序：

 | permission id | 一级 Tab | hash |
 | --- | --- | --- |
@@ -60,9 +60,6 @@
 | `editor-generation-pricing` | 模型定价 | `#editor-generation-pricing` |
 | `editor-showcase` | 精选审核 | `#editor-showcase` |
 | `editor-assets` | 素材查询 | `#editor-assets` |
-| `creation-announcement` | 入口公告 | `#creation-announcement` |
-| `creation-entry` | 入口开关 | `#creation-entry` |
-| `work-visibility` | 作品可见性 | `#work-visibility` |

 权限数组必须去重并按上表顺序规范化后保存。保存时拒绝未知值和 `accounts`；读取旧数据时遇到未知值应忽略并记录告警，绝不能将未知值解释为全权限。空数组合法，表示 member 可以登录但没有业务页面权限。

@@ -83,7 +80,7 @@
 | `username` | `String` | `unique`；登录名，创建后不可修改；按 `trim + ASCII lowercase` 规范化 |
 | `display_name` | `String` | 展示名，去除首尾空白后 1 至 64 字符 |
 | `password_hash` | `String` | Argon2id PHC 字符串；只在内部登录查询中返回给 api-server，永不进入 HTTP DTO、日志或前端状态 |
-| `permissions_json` | `String` | 规范化后的 Tab permission JSON；只允许第 4 节 18 个值，空数组为 `[]` |
+| `permissions_json` | `String` | 规范化后的 Tab permission JSON；只允许第 4 节 15 个值，空数组为 `[]` |
 | `enabled` | `bool` | 是否允许登录和继续使用现有 JWT |
 | `token_version` | `u64` | 初始为 `1`；权限、密码或启停状态发生有效变化时加 `1` |
 | `created_by` | `String` | 创建者后台 subject；当前只能是 owner subject |
@@ -163,7 +160,7 @@ accountRole: "owner" | "member"
 tabPermissions: string[]
 ```

-owner 返回全部 18 个 permission id；member 返回数据库中的实时规范化数组。`GET /admin/api/me` 同样执行逐请求校验并返回实时权限，供刷新页面后恢复导航。
+owner 返回全部 15 个 permission id；member 返回数据库中的实时规范化数组。`GET /admin/api/me` 同样执行逐请求校验并返回实时权限，供刷新页面后恢复导航。

 后台所有面向运营展示的管理员身份统一使用 `displayName`。审计表继续保存稳定 subject，例如 owner subject 或 `admin-account-<uuid>`；api-server 在返回兑换码、邀请码等操作记录时，按 owner 运行态和 `admin_account` 批量解析显示名称，同时兼容历史用户名记录。已无法解析的历史主体统一展示“已停用管理员”，前端不得直接渲染 `operatorUserId`、账号 ID 或登录用户名代替显示名称。对写接口，显示名目录必须在主事务前加载，或在主事务成功后降级为占位文案；不得因二次读取失败把已提交写入伪装成失败。

@@ -196,10 +193,6 @@ owner 返回全部 18 个 permission id；member 返回数据库中的实时规
 | `GET` | `/admin/api/tracking/event-keys` | `tracking OR tasks` |
 | `GET` | `/admin/api/database/tables` | `tables` |
 | `GET` | `/admin/api/database/tables/{table_name}/rows` | `tables` |
-| `GET` | `/admin/api/creation-entry/config` | `gray-release OR creation-announcement OR creation-entry` |
-| `POST` | `/admin/api/creation-entry/config` | `creation-entry` |
-| `POST` | `/admin/api/creation-entry/config/banners` | `creation-announcement` |
-| `POST` | `/admin/api/creation-entry/config/interactions` | `creation-entry` |
 | `GET` | `/admin/api/feature-gates` | `gray-release` |
 | `PUT` | `/admin/api/feature-gates` | `gray-release` |
 | `GET` | `/admin/api/editor-generation-pricing` | `editor-generation-pricing` |
@@ -212,8 +205,6 @@ owner 返回全部 18 个 permission id；member 返回数据库中的实时规
 | `GET` | `/admin/api/editor-showcase/campaign` | `editor-showcase` |
 | `POST` | `/admin/api/editor-showcase/campaign` | `editor-showcase` |
 | `POST` | `/admin/api/editor-showcase/campaign/image-upload-ticket` | `editor-showcase` |
-| `GET` | `/admin/api/works/visibility` | `work-visibility` |
-| `POST` | `/admin/api/works/visibility` | `work-visibility` |
 | `GET` | `/admin/api/profile/redeem-codes` | `redeem` |
 | `POST` | `/admin/api/profile/redeem-codes` | `redeem` |
 | `POST` | `/admin/api/profile/redeem-codes/disable` | `redeem` |
@@ -231,17 +222,18 @@ owner 返回全部 18 个 permission id；member 返回数据库中的实时规
 | `POST` | `/admin/api/profile/recharge-refunds/execute` | `recharge-orders` |
 | `POST` | `/admin/api/profile/recharge-refunds/register` | `recharge-orders` |
 | `POST` | `/admin/api/profile/recharge-refunds/manual-review/resolve` | `recharge-orders` |
-| `GET` | `/admin/api/profile/users/detail` | `tables OR tracking OR recharge-orders OR editor-showcase OR editor-assets OR work-visibility` |
+| `GET` | `/admin/api/profile/users/detail` | `tables OR tracking OR recharge-orders OR editor-showcase OR editor-assets` |
 | `POST` | `/admin/api/profile/wallet-restriction` | `recharge-orders` |
 | `GET` | `/admin/api/accounts` | owner-only |
 | `POST` | `/admin/api/accounts` | owner-only |
 | `PUT` | `/admin/api/accounts/{account_id}` | owner-only |

-三个共享读取接口必须按 OR 规则实现，不能为了复用简单中间件扩大成“任意 member 可访问”：
+两个共享读取接口必须按 OR 规则实现，不能为了复用简单中间件扩大成“任意 member 可访问”：

 - `/admin/api/assets/read-url` 只服务素材查询和精选审核。
- `/admin/api/profile/users/detail` 只服务当前实际包含用户详情入口的表查询、埋点数据、充值管理、精选审核、素材查询和作品可见性页面。
- `GET /admin/api/creation-entry/config` 同时为灰度发布、入口公告和入口开关提供页面初始化数据；写操作仍按具体页面单独收紧。
+- `/admin/api/profile/users/detail` 只服务当前实际包含用户详情入口的表查询、埋点数据、充值管理、精选审核和素材查询页面。
+
+`gray-release` 页面只调用 `GET/PUT /admin/api/feature-gates`；旧 `/admin/api/creation-entry/config*` 已退役，不能再作为灰度页面初始化依赖。页面固定目标只登记现役功能，其他通用 gate 仍可通过 Gate Key 直接管理。

 ## 10. 账号管理 HTTP 契约

@@ -303,7 +295,7 @@ accounts: Array<{

 ### 11.1 路由与导航

- `adminRoutes` 增加权限元数据；18 个业务路由使用同名 permission id。
+- `adminRoutes` 增加权限元数据；15 个业务路由使用同名 permission id。
 - `accounts` 路由只在 `admin.accountRole === "owner"` 时加入侧栏和移动底栏，不属于 member 可分配列表。
 - member 导航只渲染 `admin.tabPermissions` 包含的业务路由。页面组件也必须只在当前路由已授权时挂载，避免隐藏导航后仍发起无权限 API。
 - owner 渲染全部业务路由和账号管理路由。
@@ -315,13 +307,13 @@ accounts: Array<{
 1. 当前 hash 对应可访问路由时保持不变。
 2. hash 未知、属于无权限业务 Tab，或 member 访问 `#accounts` 时，使用 `replaceState` 回落到按第 4 节顺序找到的第一可访问业务 Tab。
 3. member 权限为空时，不回落 Dashboard；渲染独立的零权限空态，只保留账号信息和退出登录，不挂载任何业务页，也不发起业务 API。
-4. owner 的默认项仍可保持 Dashboard；账号管理不改变 18 个业务路由的排序。
+4. owner 的默认项仍可保持 Dashboard；账号管理不改变 15 个业务路由的排序。

 后端返回 `403` 时，前端重新请求 `/me` 获取实时权限并执行上述回落。即使前端状态陈旧或被篡改，后端权限 middleware 仍必须拒绝越权请求。

 ### 11.3 账号管理页

- 权限编辑器展示 18 个明确的 checkbox，每项使用现有 Tab 中文名称；不能展示或提交 `accounts`。
+- 权限编辑器展示 15 个明确的 checkbox，每项使用现有 Tab 中文名称；不能展示或提交 `accounts`。
 - 创建和编辑使用独立弹窗或抽屉，不在列表下方追加表单。
 - 编辑时密码字段默认空，空表示请求中省略 `password`；页面永不展示现有密码或 hash。
 - 停用使用开关并二次确认。保存成功后以 API 返回 account snapshot 更新列表。
@@ -391,12 +383,12 @@ spacetime publish <database> \
 - 权限、密码、启停更新各自会递增 `token_version`；同一次请求修改多项只递增一次；仅改展示名不递增。
 - member 被停用、改密或改权限后，旧 JWT 下一次请求返回 401；重新登录后获得实时权限。
 - API-to-Tab 矩阵逐路由覆盖 `modules/admin.rs`，每条路由至少测试 owner 成功、具备权限的 member 成功、缺权限 member 返回 403。
- 三个共享读取接口分别覆盖每个允许 permission 的成功用例，以及无关 permission 的 403 用例。
+- 两个共享读取接口分别覆盖每个允许 permission 的成功用例，以及无关 permission 的 403 用例。
 - owner-only 账号 API 对任意 member 都返回 403，即使其 `permissions_json` 被污染为包含 `accounts`。

 ### 14.2 前端

- owner 看到 18 个业务 Tab 和账号管理；member 只看到被分配的业务 Tab。
+- owner 看到 15 个业务 Tab 和账号管理；member 只看到被分配的业务 Tab。
 - 每个一级 Tab 内的二级 Tab、弹窗和写操作继承一级权限并正常使用，不出现“页面可见但内部 API 403”的错误映射。
 - 直接输入无权限 hash 自动替换为第一可访问项，不短暂挂载无权限页面。
 - 当前 Tab 权限被 owner 收回后，下一请求触发重新登录；新会话恢复后落到第一可访问项。
@@ -1,6 +1,10 @@
 # 外部生成 Worker 化方案

-更新时间：`2026-07-15`
+> 2026-07-18 退役覆盖：旧创作模板 job 类型、玩法写回和玩法恢复链路均已退出现役 worker。当前 worker 只领取 `source_module = editor-canvas` 的任务；本文涉及拼图、跳一跳、拼消消、敲木鱼等玩法的内容仅作为历史设计记录，历史队列行不得被领取或改写。
+
+> 2026-07-21 已实施、待生产压测专题：BgFilter 作为受限内部资源，仍遵守“单用户动作一个外部生成 job”；用户可见层与调度层都只有父 `external_generation_job`。父 future 保持原 lease 和 attempt，在当前调用栈内同步请求唯一 `bgfilter-worker` 的内部 HTTP，成功图片字节直接返回父流程。首版不新增 SpacetimeDB 子任务表、父 checkpoint / continuation 或 raw 中间结果 OSS。完整边界见 [`BgFilter 受限资源调度方案（同步内部 HTTP 原地等待版）`](./【后端架构】BgFilter受限资源调度方案-2026-07-21.md)。
+
+更新时间：`2026-07-21`

 ## 背景

@@ -122,7 +126,11 @@ worker 配置：
 - `GENARRATIVE_EXTERNAL_GENERATION_WORKER_POLL_INTERVAL_MS`：空队列轮询间隔。
 - `GENARRATIVE_EXTERNAL_GENERATION_WORKER_LEASE_SECONDS`：任务 lease 时长，默认 `600`；worker 会按约三分之一 lease、最长 30 秒的间隔续租。该值应覆盖一次心跳网络抖动窗口，不需要大于完整外部生成链路耗时。
 - `GENARRATIVE_EXTERNAL_GENERATION_WORKER_JOB_TIMEOUT_SECONDS`：普通外部生成 job 的执行预算，默认 `900`。超过预算后当前 worker 停止续租并释放 worker 槽位，但不取消已启动的业务 future，也不主动写入失败 / 重试状态；在途执行交由 lease fencing 仲裁：写回在租约有效期内到达则照常完成，否则被拒绝，租约过期后任务可被重新认领，attempt 耗尽时由认领事务原子标记失败并结算退款。
- `GENARRATIVE_EXTERNAL_GENERATION_WORKER_LONG_JOB_TIMEOUT_SECONDS`：视频、角色动作等长耗时 job 的执行预算，默认 `1800`。
+- `GENARRATIVE_EXTERNAL_GENERATION_WORKER_LONG_JOB_TIMEOUT_SECONDS`：VectorEngine 图片生成 / 编辑、图标 spritesheet 生成、UI 素材提取以及角色动作、视频等长耗时 job 的执行预算，默认 `1800`。其中四类 VectorEngine 图片 job 固定为 `editor_image_generation`、`editor_image_edit`、`editor_icon_spritesheet_generation` 和 `editor_ui_design_asset_extraction`；手动去背景等不直接调用 VectorEngine 的 job 继续使用普通预算。
+
+worker 在单次 job 开始执行时从同一个单调时钟起点计算绝对 `job deadline` 和更早的 `provider deadline`：常规情况下为终态审计、OSS 持久化及 `complete/fail` 回写保留 `60` 秒；当整个 job 预算小于 `120` 秒时，保留其一半，避免 provider 预算被全部吃掉。该 deadline 只通过进程内 `RequestContext` 传给 VectorEngine 图片调用，不写入 HTTP DTO、队列 payload 或 SpacetimeDB；普通 HTTP / `inline` 上下文没有 deadline，保持原有行为。
+
+VectorEngine 每次发送的实际 timeout 取 `min(VECTOR_ENGINE_IMAGE_REQUEST_TIMEOUT_MS, provider 剩余预算)`。遇到可重试传输错误或 408 / 429 / 5xx 时，只有当剩余预算还容得下本次退避和下一次 attempt 才继续；否则立即停止重试并返回当前 provider 错误，deadline 耗尽时返回 timeout。同一绝对 deadline 同时覆盖参考图下载、provider 请求 / 响应和响应图片 URL 下载，不允许请求已返回后的图片下载越过 provider 预算。`VECTOR_ENGINE_IMAGE_REQUEST_TIMEOUT_MS` 默认仍为 `1000000`；配置加载层允许显式值低于默认值，不再在读取环境变量时强制抬升。

 controller 配置：

@@ -134,7 +142,7 @@ controller 配置：
 - `GENARRATIVE_EXTERNAL_GENERATION_CONTROLLER_SERVICE_TEMPLATE`：systemd worker 模板，默认 `genarrative-external-generation-worker@{}.service`。
 - `GENARRATIVE_EXTERNAL_GENERATION_CONTROLLER_DRY_RUN`：只记录决策不执行 systemctl，默认 `false`。

-动态缩扩容方式：生产默认由 `deploy/systemd/genarrative-external-generation-controller.service` 启动 `GENARRATIVE_PROCESS_ROLE=external-generation-controller`，controller 读取 `get_external_generation_queue_stats_and_return` 后对 `genarrative-external-generation-worker@N.service` 执行精确 `systemctl start/stop`；无需改变 HTTP 进程数。controller 只操作 `@1..@MAX` 中的缺口或最高编号多余实例，保留 `@1` 作为保底 worker。缩容或发布重启 worker 时，进程收到 SIGINT/SIGTERM 后会停止 claim 新任务并等待当前任务完成；若进程被硬杀、机器断电或超过 systemd `TimeoutStopSec`，未完成任务会在 lease 过期后被其它 worker 重新领取。若 worker 内业务 future 长时间无返回，执行预算到期后 worker 会停止续租并释放槽位，在途 future 继续运行至租约仲裁窗口；有效租约内的写回仍可完成，租约过期后才会由其它 worker 重新认领，避免客户端取消与服务端写回竞态。容器链路已有独立 `external-generation-worker` compose service；扩 worker 必须扩这个 worker service，不能只扩 `api-server` HTTP service。
+动态缩扩容方式：生产默认由 `deploy/systemd/genarrative-external-generation-controller.service` 启动 `GENARRATIVE_PROCESS_ROLE=external-generation-controller`，controller 读取 `get_external_generation_queue_stats_and_return` 后对 `genarrative-external-generation-worker@N.service` 执行精确 `systemctl start/stop`；无需改变 HTTP 进程数。controller 只操作 `@1..@MAX` 中的缺口或最高编号多余实例，保留 `@1` 作为保底 worker。缩容或发布重启 worker 时，进程收到 SIGINT/SIGTERM 后会停止 claim 新任务并等待当前任务完成；若进程被硬杀、机器断电或超过 systemd `TimeoutStopSec`，未完成任务会在 lease 过期后被其它 worker 重新领取。VectorEngine 图片链路会先于整个 job 执行预算停止 provider 发送 / 重试，以便 worker 在有效 lease 内完成终态写回；若其他业务 future 仍长时间无返回，执行预算到期后 worker 会停止续租并释放槽位，在途 future 继续运行至租约仲裁窗口；有效租约内的写回仍可完成，租约过期后才会由其它 worker 重新认领，避免客户端取消与服务端写回竞态。本次预算收口不改变 lease 续租 / fencing、迟到写回仲裁、attempt 耗尽收口和原子退款语义。容器链路已有独立 `external-generation-worker` compose service；扩 worker 必须扩这个 worker service，不能只扩 `api-server` HTTP service。

 ## 已接入的拼图纵切

@@ -186,7 +194,7 @@ controller 配置：

 - `editor_image_generation`：普通图片、生成规范、角色形象、UI 设计图、宣发素材和图片快速编辑。
 - `editor_image_edit`：图片编辑 / 修改结果。
- `editor_background_removal`：手动去除任意图片背景，worker 使用 BgFilter complex 模式、首次失败后重试 `1` 次，并把执行阶段标记为 `processing`。
+- `editor_background_removal`：手动去除任意图片背景，父 `external-generation-worker` 至多让 worker 接收一次内部 HTTP RPC（连接从未建立时按调度方案 §5.1 有界重连）并把执行阶段标记为 `processing`；唯一 `bgfilter-worker` 使用 BgFilter complex 模式，对同一次逻辑调用最多执行两次顺序 provider attempt，两次都失败时把类型化错误返回父流程。
 - `editor_icon_spritesheet_generation`：图标素材 spritesheet 生成和拆分。
 - `editor_ui_design_asset_extraction`：UI 设计图红框素材提取。
 - `editor_character_animation_generation`：角色动作视频和帧素材生成。
@@ -1,5 +1,7 @@
 # 统一公开作品 ReadModel 设计

+> 2026-07-18 退役覆盖：统一公开作品 BFF、read model、逐玩法 source view 和互动链路均已退出现役编译与路由。相关历史表只作为 schema 数据壳保留；新版 `/creation` 只读取编辑器精选素材。本文其余内容仅作为历史设计记录。
+
 更新时间：`2026-05-26`

 ## 背景
@@ -18,7 +18,7 @@
 - 代理路径上的上游连接失败会返回统一 JSON；`502` 使用 `GATEWAY_UPSTREAM_ERROR`，`504` 使用 `GATEWAY_UPSTREAM_TIMEOUT`，避免 shadow / canary 阶段把框架默认错误页透给前端或巡检。
 - 上游超时显式配置在 Pingora peer 上：连接超时默认 `3000ms`，没有 Nginx 显式长超时的代理路由读取默认 `60s`，通用 `/api`、公开列表 / 详情和 SpacetimeDB subscribe 读取默认 `3600s`，写入超时默认 `3600s`。读 / 写 / 连接超时统一映射为 JSON `504 GATEWAY_UPSTREAM_TIMEOUT`。
 - 默认开启 gzip 响应压缩，`GENARRATIVE_PINGORA_GATEWAY_GZIP_LEVEL=5` 和 `GENARRATIVE_PINGORA_GATEWAY_GZIP_MIN_LENGTH_BYTES=1024` 对齐当前 Nginx `gzip_comp_level 5` / `gzip_min_length 1024`；`GENARRATIVE_PINGORA_GATEWAY_GZIP_ENABLED=false` 时禁用。`GENARRATIVE_PINGORA_GATEWAY_COMPRESSION_ALGORITHMS=gzip` 是当前唯一允许的压缩算法白名单；网关会在进入 Pingora compression 模块前把 `Accept-Encoding` 收敛为 gzip，避免未验收的 `br` / `zstd` 被隐式打开。压缩能力由 `check:pingora-gateway-smoke` 用小响应不压缩、图片资源不压缩、大响应 `Accept-Encoding: gzip`、`Accept-Encoding: br, gzip`、`Content-Encoding: gzip`、`Vary: Accept-Encoding` 和解压后的响应体一起验证。Brotli 不进入当前 Pingora 正式化口径，仍由 Nginx / 前置代理能力探测承担；直连 Pingora 时不把 Brotli parity 作为切换门禁。
- 默认开启单进程内接流保护，按客户端 IP 与路由组执行并发上限、RPS 和 burst 限制。保护组默认对齐当前 Nginx：`admin_api=64/30rps/16burst`、`gallery_list=320/5000rps/4096burst`、`gallery_detail=32/300rps/32burst`、`api=64/300rps/64burst`、`spacetime=256/1000rps/256burst`。超限返回 JSON `429` 并带 `Retry-After: 1`。
+- 默认开启单进程内接流保护，按客户端 IP 与路由组执行并发上限、RPS 和 burst 限制。保护组默认对齐当前 Nginx：`admin_api=64/30rps/16burst`、`api=64/300rps/64burst`、`spacetime=256/1000rps/256burst`。超限返回 JSON `429` 并带 `Retry-After: 1`。
 - 当前接流保护的默认正式口径是单 Pingora 实例。`GENARRATIVE_PINGORA_GATEWAY_INSTANCE_COUNT` 默认 `1`；若 `GENARRATIVE_PINGORA_GATEWAY_PROTECTION_ENABLED=true` 且 `GENARRATIVE_PINGORA_GATEWAY_INSTANCE_COUNT>1`，必须先落地共享限流 / 共享并发保护层，并显式设置 `GENARRATIVE_PINGORA_GATEWAY_SHARED_PROTECTION_CONFIRMED=true`，否则网关启动和目标机 direct preflight 都会失败。若关闭网关保护后横向多实例运行，则全局接流保护必须由前置 Nginx / LB 承担。
 - 默认以 TCP 对端 IP 作为限流 client key；只有在 Pingora 前置代理已经清洗 `X-Forwarded-For` 时，才允许开启 `GENARRATIVE_PINGORA_GATEWAY_TRUST_X_FORWARDED_FOR=true` 使用首个转发 IP。开启时必须同时设置 `GENARRATIVE_PINGORA_GATEWAY_TRUSTED_FRONT_PROXY_CONFIRMED=true`，否则网关会拒绝启动。若 Pingora 直接监听公网地址，`TRUST_X_FORWARDED_FOR` 必须保持 `false`，目标机 direct preflight 会在看到公网监听加该开关时失败。
 - 可选配置 `GENARRATIVE_PINGORA_GATEWAY_GITEA_HOSTS` 和 `GENARRATIVE_PINGORA_GATEWAY_GITEA_UPSTREAM` 后，网关会先按 `Host` 归一化匹配 Gitea 域名，命中时整站代理到 Gitea 上游。Gitea 路由不走应用维护页、API 请求体上限或网关接流保护，避免影响 git clone / push。用于同一公网 IP 同时承载 `dev.genarrative.world` 与 `git.genarrative.world` 的直连切换时，TLS 证书必须同时覆盖两个域名；当前单 listener 配置只加载一组 cert/key。
@@ -70,7 +70,7 @@ npm run check:pingora-release-readiness

 `check:pingora-canary-docker` 会启动 mock `api-server`、mock SpacetimeDB、真实 `pingora-gateway` 和 Docker Nginx，把前缀 canary 与真实路径 canary 两份 snippet 都渲染到临时 Nginx 中，再复用 `check:pingora-canary-live` 验证 Nginx -> Pingora -> 上游的 handoff 链路。临时 Nginx 使用生产同口径 `genarrative_upstream` access log，live smoke 后会继续调用 `scripts/check-pingora-canary-access-log-parity.mjs`，按同一 `request_id` 对账 canary healthz、代表性 API、SpacetimeDB identity 和静态资源路径；前缀模式确认 Nginx rewrite 后路径与 Pingora access log 一致，真实路径模式除 healthz 探针外要求 Nginx path 与 Pingora path 完全一致。默认不拉取镜像；缺少 Docker daemon 或 `nginx:1.27-alpine` 镜像时跳过。CI / 目标 agent 上需要把它作为硬门禁时执行 `node scripts/check-pingora-canary-docker.mjs --require-docker --pull`。

-`check:pingora-canary-access-log-parity` 会烟测只读脚本 `scripts/check-pingora-canary-access-log-parity.mjs`，用于目标机 canary 后按 `request_id` 对照 Nginx handoff access log 和 Pingora tab-separated access log。真实目标机前缀 canary 执行时使用 `/opt/genarrative/current/scripts/check-pingora-canary-access-log-parity.mjs --nginx-log-file /var/log/nginx/genarrative.access.log --pingora-log-file /var/log/genarrative/pingora-gateway.access.log --path /__genarrative_pingora_canary/healthz --path /__genarrative_pingora_canary/api/creation-entry/config`；真实路径 canary 执行时追加 `--realpath --nginx-log-file /var/log/nginx/genarrative-pingora-realpath-canary.access.log --path /__genarrative_pingora_realpath_canary/healthz --path /api/creation-entry/config --path /v1/identity --path /assets/app.js`。脚本只读日志，不修改日志、不 reload Nginx 或 Pingora。
+`check:pingora-canary-access-log-parity` 会烟测只读脚本 `scripts/check-pingora-canary-access-log-parity.mjs`，用于目标机 canary 后按 `request_id` 对照 Nginx handoff access log 和 Pingora tab-separated access log。真实目标机前缀 canary 执行时使用 `/opt/genarrative/current/scripts/check-pingora-canary-access-log-parity.mjs --nginx-log-file /var/log/nginx/genarrative.access.log --pingora-log-file /var/log/genarrative/pingora-gateway.access.log --path /__genarrative_pingora_canary/healthz --path /__genarrative_pingora_canary/api/editor/showcase/resources`；真实路径 canary 执行时追加 `--realpath --nginx-log-file /var/log/nginx/genarrative-pingora-realpath-canary.access.log --path /__genarrative_pingora_realpath_canary/healthz --path /api/editor/showcase/resources --path /v1/identity --path /assets/app.js`。脚本只读日志，不修改日志、不 reload Nginx 或 Pingora。

 `check:pingora-direct-preflight` 默认只检查仓库内主 service、direct-entry drop-in 和 env 示例，适合本机提交前护栏。目标机直连切换窗口必须提供真实 env 并打开现场检查：

@@ -351,8 +351,8 @@ node -- /opt/genarrative/current/scripts/deploy/pingora-health-patrol-env-switch
 4. 在 `server {}` 内人工 include 该 snippet，并保持 `allow 127.0.0.1; allow ::1; deny all;` 或改成当次可信来源。
 5. 执行 `npm run check:nginx-pingora-canary`；目标机或 CI 有 Nginx 时执行 `node scripts/check-nginx-pingora-canary.mjs --require-nginx`，再执行 `nginx -t && nginx -s reload`。
 6. 执行 `GENARRATIVE_PINGORA_CANARY_BASE_URL=http://127.0.0.1 GENARRATIVE_PINGORA_CANARY_HOST=<域名> npm run check:pingora-canary-live`，确认 healthz、API、SpacetimeDB identity、静态资源和拒绝入口都带 `X-Genarrative-Nginx-Handoff: pingora-canary`。
-7. 必要时再用同一前缀访问其它代表性路由，例如 `/__genarrative_pingora_canary/api/creation-entry/config`、`/__genarrative_pingora_canary/v1/identity` 和 `/__genarrative_pingora_canary/assets/app.js`，并对照直连 Nginx 正常入口和 Pingora shadow 日志。
-8. 执行 current release 随包 `scripts/check-pingora-canary-access-log-parity.mjs --nginx-log-file /var/log/nginx/genarrative.access.log --pingora-log-file /var/log/genarrative/pingora-gateway.access.log --path /__genarrative_pingora_canary/healthz --path /__genarrative_pingora_canary/api/creation-entry/config`，确认同一 `request_id`、`path`、`status` 和 `proxy_target` 与 Nginx access log 可对齐。对账脚本的日志路径、canary prefix、必需路径和 `--since-lines` / `GENARRATIVE_PINGORA_CANARY_ACCESS_LOG_SINCE_LINES` 都不能包含换行或 NUL；若 access log 行里解析出的 URI / path 含控制字符，脚本也会把对应行记为失败，避免污染值进入 JSON 对账输出。
+7. 必要时再用同一前缀访问其它代表性路由，例如 `/__genarrative_pingora_canary/api/editor/showcase/resources`、`/__genarrative_pingora_canary/v1/identity` 和 `/__genarrative_pingora_canary/assets/app.js`，并对照直连 Nginx 正常入口和 Pingora shadow 日志。
+8. 执行 current release 随包 `scripts/check-pingora-canary-access-log-parity.mjs --nginx-log-file /var/log/nginx/genarrative.access.log --pingora-log-file /var/log/genarrative/pingora-gateway.access.log --path /__genarrative_pingora_canary/healthz --path /__genarrative_pingora_canary/api/editor/showcase/resources`，确认同一 `request_id`、`path`、`status` 和 `proxy_target` 与 Nginx access log 可对齐。对账脚本的日志路径、canary prefix、必需路径和 `--since-lines` / `GENARRATIVE_PINGORA_CANARY_ACCESS_LOG_SINCE_LINES` 都不能包含换行或 NUL；若 access log 行里解析出的 URI / path 含控制字符，脚本也会把对应行记为失败，避免污染值进入 JSON 对账输出。
 9. 验证结束后移除 include 并 reload Nginx；不要把该前缀入口当作正式公网 URL。

 ## dev shadow service 验收记录
@@ -499,7 +499,7 @@ dev 根盘空间在安装后曾接近满盘；2026-06-17 进入 canary 前已清
 | `GENARRATIVE_PINGORA_GATEWAY_UPSTREAM_CONNECT_TIMEOUT_MS`           | `3000`                                     | 连接上游的超时，必须大于 `0`。                                                                     |
 | `GENARRATIVE_PINGORA_GATEWAY_UPSTREAM_DEFAULT_READ_TIMEOUT_SECONDS` | `60`                                       | 没有 Nginx 显式长超时的代理路由读取超时，必须大于 `0`。                                            |
 | `GENARRATIVE_PINGORA_GATEWAY_UPSTREAM_API_READ_TIMEOUT_SECONDS`     | `3600`                                     | 通用 `/api` 路由读取超时，对齐当前 Nginx `proxy_read_timeout 3600s`。                              |
-| `GENARRATIVE_PINGORA_GATEWAY_UPSTREAM_LONG_READ_TIMEOUT_SECONDS`    | `3600`                                     | 公开列表 / 详情和 SpacetimeDB subscribe 长连接读取超时。                                           |
+| `GENARRATIVE_PINGORA_GATEWAY_UPSTREAM_LONG_READ_TIMEOUT_SECONDS`    | `3600`                                     | SpacetimeDB subscribe 长连接读取超时。                                                              |
 | `GENARRATIVE_PINGORA_GATEWAY_UPSTREAM_WRITE_TIMEOUT_SECONDS`        | `3600`                                     | 写上游请求头 / 请求体超时，对齐当前 Nginx `proxy_send_timeout 3600s` 口径。                        |
 | `GENARRATIVE_PINGORA_GATEWAY_TRUST_X_FORWARDED_FOR`                 | `false`                                    | 是否用 `X-Forwarded-For` 首个 IP 作为接流保护 client key；公网直连 Pingora 时必须保持 `false`，direct preflight 会阻断公网监听误开启。 |
 | `GENARRATIVE_PINGORA_GATEWAY_TRUSTED_FRONT_PROXY_CONFIRMED`         | `false`                                    | 开启 `TRUST_X_FORWARDED_FOR` 时必须显式设为 `true`，表示前置代理会清洗 `X-Forwarded-For`。         |
@@ -509,12 +509,6 @@ dev 根盘空间在安装后曾接近满盘；2026-06-17 进入 canary 前已清
 | `GENARRATIVE_PINGORA_GATEWAY_ADMIN_API_MAX_CONCURRENT`              | `64`                                       | `/admin/api/*` 每 client 并发上限；`0` 表示不限制并发。                                            |
 | `GENARRATIVE_PINGORA_GATEWAY_ADMIN_API_RATE_PER_SECOND`             | `30`                                       | `/admin/api/*` 每 client token bucket 回填速率；`0` 表示不限制 RPS。                               |
 | `GENARRATIVE_PINGORA_GATEWAY_ADMIN_API_BURST`                       | `16`                                       | `/admin/api/*` 每 client 额外 burst。                                                              |
-| `GENARRATIVE_PINGORA_GATEWAY_GALLERY_LIST_MAX_CONCURRENT`           | `320`                                      | 公开列表路由每 client 并发上限。                                                                   |
-| `GENARRATIVE_PINGORA_GATEWAY_GALLERY_LIST_RATE_PER_SECOND`          | `5000`                                     | 公开列表路由每 client RPS。                                                                        |
-| `GENARRATIVE_PINGORA_GATEWAY_GALLERY_LIST_BURST`                    | `4096`                                     | 公开列表路由每 client burst。                                                                      |
-| `GENARRATIVE_PINGORA_GATEWAY_GALLERY_DETAIL_MAX_CONCURRENT`         | `32`                                       | 公开详情兼容路由每 client 并发上限。                                                               |
-| `GENARRATIVE_PINGORA_GATEWAY_GALLERY_DETAIL_RATE_PER_SECOND`        | `300`                                      | 公开详情兼容路由每 client RPS。                                                                    |
-| `GENARRATIVE_PINGORA_GATEWAY_GALLERY_DETAIL_BURST`                  | `32`                                       | 公开详情兼容路由每 client burst。                                                                  |
 | `GENARRATIVE_PINGORA_GATEWAY_API_MAX_CONCURRENT`                    | `64`                                       | 通用 `/api` 路由每 client 并发上限。                                                               |
 | `GENARRATIVE_PINGORA_GATEWAY_API_RATE_PER_SECOND`                   | `300`                                      | 通用 `/api` 路由每 client RPS。                                                                    |
 | `GENARRATIVE_PINGORA_GATEWAY_API_BURST`                             | `64`                                       | 通用 `/api` 路由每 client burst。                                                                  |
@@ -536,13 +530,11 @@ dev 根盘空间在安装后曾接近满盘；2026-06-17 进入 canary 前已清
 | `/admin/assets/*`                                                                         | 从 Web 根目录精确读取静态文件；带 Vite 指纹的文件默认长期缓存，其它文件默认 `no-cache`，并支持条件请求返回 `304` 与单段 `Range: bytes=` 返回 `206` / 越界返回 `416`。 |
 | `/admin/*`                                                                                | 先读取静态文件或目录 index，失败回退 `/admin/index.html`，HTML 默认 `no-cache`，并支持条件请求返回 `304` 与单段 `Range: bytes=` 返回 `206` / 越界返回 `416`。 |
 | `/assets/*`                                                                               | 从 Web 根目录精确读取静态文件；带 Vite 指纹的文件默认长期缓存，其它文件默认 `no-cache`，并支持条件请求返回 `304` 与单段 `Range: bytes=` 返回 `206` / 越界返回 `416`。 |
-| `/api/runtime/puzzle/gallery`、`/api/runtime/custom-world-gallery`                        | 转发到 `api-server`。                                                                  |
-| `/api/runtime/puzzle/gallery/{id}`、`/api/runtime/custom-world-gallery/{profile}/{owner}` | 转发到 `api-server`。                                                                  |
 | `/api`、`/api/*`                                                                          | 转发到 `api-server`，按配置执行 `Content-Length` 与流式 body 累计上限检查。            |
 | `/v1/database/{db}/subscribe`、`/v1/identity*`                                            | 转发到 SpacetimeDB，保留 WebSocket Upgrade 头。                                        |
 | `/__genarrative_pingora/healthz`                                                          | 仅在携带 `X-Genarrative-Pingora-Probe` 且匹配配置 token 时返回 shadow JSON，否则 404。 |
 | `/v1/*`、`/generated-*`、`/healthz*`、`/readyz*`                                          | 返回 404，保持生产公网不暴露口径。                                                     |
-| 主站 SPA allowlist                                                                        | 只对当前前端完整路由及兼容恢复路径 `/creation/rpg/agent` 失败回退 `/index.html`；匹配大小写不敏感并允许一个尾部斜杠，HTML 默认 `no-cache`。 |
+| 主站 SPA allowlist                                                                        | 只对 `/`、`/creation`、`/project`、`/profile` 与 `/editor/canvas` 失败回退 `/index.html`；匹配大小写不敏感并允许一个尾部斜杠，HTML 默认 `no-cache`。 |
 | 其它 Web 路径                                                                             | 只读取真实静态文件或目录 index，缺失时返回真实 404；`/creation/not-exist`、`/runtime/not-exist`、`/puzzle/not-exist` 不进入 SPA fallback。 |

 维护模式下，公网 API-like 路由返回 JSON `503`；公网 Web 静态路由先读取 `GENARRATIVE_PINGORA_GATEWAY_MAINTENANCE_PAGE_FILE` 指向的 release 外运行态公告，缺失时回退 `GENARRATIVE_PINGORA_GATEWAY_WEB_ROOT/maintenance.html`，两者都不存在时返回纯文本 `503`。版本化默认页不得包含日期或具体时段，临时公告由 `maintenance-on.sh --page-file` 安装并在 `maintenance-off.sh` 时清理。IPv4 loopback / RFC1918 / link-local 和 IPv6 loopback / ULA / link-local 来源绕过整站维护闸，主站页面与静态资源、普通 API、后台页面与后台 API、SpacetimeDB 路由均按非维护状态继续处理；应用层登录、管理员鉴权和其它业务鉴权保持不变。Pingora 直连按 TCP peer 判定来源；仅当 peer 是 loopback 的同机 Nginx 时才接受 Nginx 强制覆盖的 `X-Real-IP`，绝不使用客户端可伪造的 `X-Forwarded-For` 做维护放行。该放行只绕过网关维护响应；若 `pause-after-stdb` 已停止 api-server，内网普通 API 和后台 API 仍不可用。
@@ -556,7 +548,7 @@ dev 根盘空间在安装后曾接近满盘；2026-06-17 进入 canary 前已清
 2. 涉及 Nginx 模板、Pingora 路由、限流分组或路由文档时，同步更新 `deploy/pingora/nginx-route-parity.matrix.json`，并运行 `npm run check:pingora-route-parity` 与 `cargo test -p pingora-gateway --manifest-path server-rs/Cargo.toml matches_nginx_route_parity_matrix`。
 3. 容器内使用同一份 Web 产物、同一组真实上游地址跑 Pingora smoke，并继续对照 `deploy/nginx/genarrative.conf` 扩展真实上游路由 parity 自动测试。
 4. 使用 `deploy/nginx/snippets/genarrative-pingora-canary.conf` 做 Nginx 前缀 canary；启用前先跑 `npm run check:nginx-pingora-canary` 和 `npm run check:pingora-canary-docker`，有 Nginx 或 Docker 的目标环境分别强制跑 `node scripts/check-nginx-pingora-canary.mjs --require-nginx` 与 `node scripts/check-pingora-canary-docker.mjs --require-docker --pull`，其中 Docker handoff 会自动对账临时 Nginx 与 Pingora access log。启用后跑 `npm run check:pingora-canary-live`，再用 current release 随包 access log parity 脚本对账目标机 Nginx 与 Pingora access log。canary live 的 base URL、prefix、Host、额外 path 和 timeout 不能包含换行或 NUL；canary live timeout 和 access log `since-lines` 必须是正整数，非法值直接失败。
-5. 前缀 canary 通过后，再使用 current release 随包 `/opt/genarrative/current/scripts/deploy/pingora-realpath-canary-enable.sh --apply --probe-token <token> --host <域名> --base-url http://127.0.0.1:18083` 启用真实路径 canary；它会把 `deploy/nginx/snippets/genarrative-pingora-realpath-canary.conf` 渲染成独立本机 `server`，写入 `/etc/nginx/conf.d/zz-genarrative-pingora-realpath-canary.conf`，不能 include 到生产 `443` server 内。该片段使用 `access_log ... genarrative_upstream`，文件名必须保证晚于定义 `log_format genarrative_upstream` 的主站配置加载；否则 `nginx -t` 会报 `unknown log format "genarrative_upstream"`。启用脚本会先执行 `nginx -t`、reload Nginx，再默认运行 realpath live smoke，任一阶段失败都会恢复写入前配置。关闭时执行 `/opt/genarrative/current/scripts/deploy/pingora-realpath-canary-disable.sh --apply`，脚本会在 `nginx -t` 或 reload 失败时恢复删除前配置。启用后跑 `node -- /opt/genarrative/current/scripts/check-pingora-canary-live.mjs --realpath --base-url http://127.0.0.1:18083 --host <域名>`，再用 current release 随包 access log parity 脚本传 `--realpath --nginx-log-file /var/log/nginx/genarrative-pingora-realpath-canary.access.log` 对账 `/api/creation-entry/config`、`/v1/identity` 和 `/assets/app.js` 等真实路径。
+5. 前缀 canary 通过后，再使用 current release 随包 `/opt/genarrative/current/scripts/deploy/pingora-realpath-canary-enable.sh --apply --probe-token <token> --host <域名> --base-url http://127.0.0.1:18083` 启用真实路径 canary；它会把 `deploy/nginx/snippets/genarrative-pingora-realpath-canary.conf` 渲染成独立本机 `server`，写入 `/etc/nginx/conf.d/zz-genarrative-pingora-realpath-canary.conf`，不能 include 到生产 `443` server 内。该片段使用 `access_log ... genarrative_upstream`，文件名必须保证晚于定义 `log_format genarrative_upstream` 的主站配置加载；否则 `nginx -t` 会报 `unknown log format "genarrative_upstream"`。启用脚本会先执行 `nginx -t`、reload Nginx，再默认运行 realpath live smoke，任一阶段失败都会恢复写入前配置。关闭时执行 `/opt/genarrative/current/scripts/deploy/pingora-realpath-canary-disable.sh --apply`，脚本会在 `nginx -t` 或 reload 失败时恢复删除前配置。启用后跑 `node -- /opt/genarrative/current/scripts/check-pingora-canary-live.mjs --realpath --base-url http://127.0.0.1:18083 --host <域名>`，再用 current release 随包 access log parity 脚本传 `--realpath --nginx-log-file /var/log/nginx/genarrative-pingora-realpath-canary.access.log` 对账 `/api/editor/showcase/resources`、`/v1/identity` 和 `/assets/app.js` 等真实路径。
 6. 目标机 canary include 后必须跑正式切换聚合门禁，并按现场已启用的 canary 入口选择参数：前缀 canary 已启用时，源码 checkout / CI / 构建环境执行 `node scripts/check-pingora-release-readiness.mjs --require-docker --pull-docker --require-nginx --require-live --live-base-url http://127.0.0.1 --live-host <域名> --live-nginx-access-log /var/log/nginx/genarrative.access.log --live-pingora-access-log /var/log/genarrative/pingora-gateway.access.log`，目标机 current release 执行 `/opt/genarrative/current/scripts/check-pingora-release-readiness.mjs --release-runtime-only --require-live --live-base-url http://127.0.0.1 --live-host <域名> --live-nginx-access-log /var/log/nginx/genarrative.access.log --live-pingora-access-log /var/log/genarrative/pingora-gateway.access.log`；真实路径 canary 已启用时，追加或单独使用 `--require-realpath-live --realpath-live-base-url http://127.0.0.1:18083 --realpath-live-host <域名> --realpath-live-nginx-access-log /var/log/nginx/genarrative-pingora-realpath-canary.access.log --realpath-live-pingora-access-log /var/log/genarrative/pingora-gateway.access.log`。如果现场只启用了真实路径 canary，不要同时传 `--require-live`；缺少 Host 会直接失败，避免 live canary 误测默认 vhost。live smoke 后还会按 `request_id` 对账 Nginx 与 Pingora access log，缺少同一请求的 Pingora 日志、状态码、方法或 path 漂移都会失败。
 7. 如需评估 Pingora 直连公网入口，必须显式配置 `TLS_LISTEN`、证书、私钥和 `HTTP_REDIRECT_LISTEN`；Certbot 证书先用随包 `scripts/deploy/pingora-tls-cert-sync.mjs` 同步到 `/etc/genarrative/pingora-tls/<域名>/`，不要直接 chmod Let’s Encrypt live/archive 原路径；同一 IP 上还有 Gitea 域名时，还必须配置 `GITEA_HOSTS` / `GITEA_UPSTREAM` 并确认 TLS 证书覆盖所有由 Pingora 直连接管的 Host。绑定 `80/443` 时还必须人工启用 `genarrative-pingora-gateway-direct-entry.conf` drop-in 授予 `CAP_NET_BIND_SERVICE`。随后用 `npm run check:pingora-gateway-smoke` 覆盖 TLS / HTTP/2 ALPN / redirect / WSS subscribe / Gitea Host 分流；目标机必须先跑 `npm run check:pingora-direct-preflight -- --env-file /etc/genarrative/pingora-gateway.env --require-live-env --systemd-cat --check-cert-readable --check-service-env-file --check-service-user-cert-readable --check-service-binary-executable --check-ports-free`，再跑 `npm run check:pingora-direct-live` 或 release readiness 的 `--require-direct`，且 `--require-direct` 必须带 direct HTTPS base URL、direct HTTP base URL、正式域名 Host/SNI、redirect Location host、Pingora access log 文件、health patrol env 文件、direct preflight env 文件、systemd drop-in 生效检查、service EnvironmentFile 一致性检查、当前用户和 systemd 服务用户证书可读检查、service 二进制可执行检查、显式 SpacetimeDB 数据库名，并会拒绝 `--skip-wss`。高端口 rehearsal 使用 `https://127.0.0.1:<高端口>` 打入但期望 HTTP redirect Location 指向正式域名默认 HTTPS 入口时，额外传 `--direct-redirect-base-url https://<域名>`；`--direct-redirect-host` 仍必须保留，用于 runbook Host 一致性约束。direct live 会用生成的 `request_id` 反查 Pingora access log；缺少对应日志、method 漂移、path 漂移或 status 漂移都算直连门禁失败。direct preflight 会拒绝开启网关保护但未确认共享保护层的 `GENARRATIVE_PINGORA_GATEWAY_INSTANCE_COUNT>1` 配置；`--env-file`、`--systemd-service`、服务用户和 env 中的 listen / cert / key 值都不能包含换行或 NUL，执行 `systemctl cat` 或 `sudo -u <serviceUser> test -r <file>` 前还会复核子命令参数，避免污染参数进入目标机预检命令；direct live 的 URL、Host、redirect base URL、probe token、额外 path、数据库名、access log 路径、timeout 和布尔 env 也不能包含换行或 NUL，且会在发起请求前失败；direct live timeout 必须是正整数，直连相关布尔 env 只接受 `true/false`、`1/0`、`yes/no`、`on/off` 或空值，非法值直接失败。证书申请与续期仍由 Certbot / 外部自动化承担，网关只读取现有文件。
 8. 正式直连 runbook 的启用前基础门禁和启用后 `--require-direct` 复核必须调用 `/opt/genarrative/current/scripts/check-pingora-release-readiness.mjs --release-runtime-only`。该脚本、`scripts/check-pingora-canary-live.mjs`、`scripts/ops/pingora-direct-rehearsal-status.mjs`、realpath canary 启停脚本和 `deploy/nginx/` 必须进入生产 API release、Jenkins API Build 归档、Jenkins API Deploy 复制清单和目标机 current release；缺失时部署应 fail-fast，切换窗口不能依赖源码 checkout 或 Jenkins workspace。
@@ -1426,16 +1426,16 @@ V1.41 为 V1.40 明确留下的成功响应交接窗口增加 `.agent/runtime/pr

 ### 确定性测试矩阵

-| 范围 | 故障/恢复窗口 | 必须断言 | 定向用例 |
-| --- | --- | --- | --- |
-| sidecar 契约 | 首次写入、同内容重写、`.previous`、损坏/超限/路径或内容冲突 | 严格 schema、`0600` 原子交接、实际 requestId 稳定、tool call 拒绝、thinking/密钥/路径零落盘 | `provider_handoff_*` 单元用例 |
-| final-reply handoff-first | Provider 成功交接后、lifecycle 终态前停止 | 恢复零新网络请求，原 requestId `started -> completed`，唯一 assistant/completed/committed stream，终局零 retry/handoff/finalization | `provider_handoff_final_reply_restart_replays_success_without_network_request` |
-| compaction consumer | 前置压缩 handoff 已落盘、compaction sidecar 未提交，以及 sidecar 已提交但 handoff 未清理 | 压缩结果回读后清理，不重放 tool-plan/压缩，只发后续 final-reply | `provider_handoff_final_reply_compaction_restart_only_requests_final_reply` |
-| identity/retry 冲突 | Goal/steer/revision/request/config 漂移，或 retry identity/attempt/slot 与 handoff 不一致 | 漂移先闭合旧 lifecycle 再作废，审计零响应正文；retry 冲突进入 reconciliation 且零 Provider 请求 | `provider_handoff_identity_drift_closes_lifecycle_without_leaking_response` 及 `provider_handoff_` 冲突门禁 |
-| finalization schema/身份 | v4 slot 被篡改，或读取缺少 slot 的 v3 journal 与 v1-v4 lifecycle | v4 `responseRequestSlot` 进入 `finalizationId` 指纹；v3 按旧身份可读；Agent DB lifecycle 白名单接受 v1-v4 journal schema | `finalization_v4_binds_response_request_slot_into_identity`、`finalization_v3_without_response_request_slot_remains_readable`、`finalization_lifecycle_accepts_supported_v1_through_v4_journals` |
-| finalization 四 checkpoint | `Prepared / AssistantAppended / RuntimeCompleted / ResponseStreamCommitted` 任一点中断 | 原 messageId/finalizationId 幂等恢复，无 Provider/工具重放，最终 journal/handoff 清理 | `finalization_*` 与 `response_stream_committed_checkpoint_recovers_by_idempotent_cleanup` |
-| 回复流重建 | stream 缺失、停在 streaming、commit 写失败、已 committed 后清理中断 | 按 v4 固定 slot 从 journal 重建 ready，committed 写后回读，正文唯一，冲突失败关闭 | `response_stream_finalization_recovers_missing_stream_after_project_revision_drift`、`response_stream_finalization_repairs_streaming_after_commit_write_failure`、`response_stream_committed_checkpoint_recovers_by_idempotent_cleanup` |
-| Runner busy | primary、`.previous` 或损坏 handoff 存在时请求 idle shutdown | `idle=false`，不进入 draining；清理后才可 shutdown | `durable_provider_handoff_prevents_shutdown_even_when_corrupt` |
+| 范围                       | 故障/恢复窗口                                                                             | 必须断言                                                                                                                            | 定向用例                                                                                                                                                                                                                                |
+| -------------------------- | ----------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| sidecar 契约               | 首次写入、同内容重写、`.previous`、损坏/超限/路径或内容冲突                               | 严格 schema、`0600` 原子交接、实际 requestId 稳定、tool call 拒绝、thinking/密钥/路径零落盘                                         | `provider_handoff_*` 单元用例                                                                                                                                                                                                           |
+| final-reply handoff-first  | Provider 成功交接后、lifecycle 终态前停止                                                 | 恢复零新网络请求，原 requestId `started -> completed`，唯一 assistant/completed/committed stream，终局零 retry/handoff/finalization | `provider_handoff_final_reply_restart_replays_success_without_network_request`                                                                                                                                                          |
+| compaction consumer        | 前置压缩 handoff 已落盘、compaction sidecar 未提交，以及 sidecar 已提交但 handoff 未清理  | 压缩结果回读后清理，不重放 tool-plan/压缩，只发后续 final-reply                                                                     | `provider_handoff_final_reply_compaction_restart_only_requests_final_reply`                                                                                                                                                             |
+| identity/retry 冲突        | Goal/steer/revision/request/config 漂移，或 retry identity/attempt/slot 与 handoff 不一致 | 漂移先闭合旧 lifecycle 再作废，审计零响应正文；retry 冲突进入 reconciliation 且零 Provider 请求                                     | `provider_handoff_identity_drift_closes_lifecycle_without_leaking_response` 及 `provider_handoff_` 冲突门禁                                                                                                                             |
+| finalization schema/身份   | v4 slot 被篡改，或读取缺少 slot 的 v3 journal 与 v1-v4 lifecycle                          | v4 `responseRequestSlot` 进入 `finalizationId` 指纹；v3 按旧身份可读；Agent DB lifecycle 白名单接受 v1-v4 journal schema            | `finalization_v4_binds_response_request_slot_into_identity`、`finalization_v3_without_response_request_slot_remains_readable`、`finalization_lifecycle_accepts_supported_v1_through_v4_journals`                                        |
+| finalization 四 checkpoint | `Prepared / AssistantAppended / RuntimeCompleted / ResponseStreamCommitted` 任一点中断    | 原 messageId/finalizationId 幂等恢复，无 Provider/工具重放，最终 journal/handoff 清理                                               | `finalization_*` 与 `response_stream_committed_checkpoint_recovers_by_idempotent_cleanup`                                                                                                                                               |
+| 回复流重建                 | stream 缺失、停在 streaming、commit 写失败、已 committed 后清理中断                       | 按 v4 固定 slot 从 journal 重建 ready，committed 写后回读，正文唯一，冲突失败关闭                                                   | `response_stream_finalization_recovers_missing_stream_after_project_revision_drift`、`response_stream_finalization_repairs_streaming_after_commit_write_failure`、`response_stream_committed_checkpoint_recovers_by_idempotent_cleanup` |
+| Runner busy                | primary、`.previous` 或损坏 handoff 存在时请求 idle shutdown                              | `idle=false`，不进入 draining；清理后才可 shutdown                                                                                  | `durable_provider_handoff_prevents_shutdown_even_when_corrupt`                                                                                                                                                                          |

 2026-07-20 当前最终实现的最新验证证据为：`provider_retry_` 21/21、`response_stream_` 23/23、`finalization_resume_` 12/12；Tauri/Rust 串行全量共 989 tests，`985 passed / 4 ignored / 0 failed`。这些数字替代 V1.40 较早快照，后续当前结果统一使用本行口径。

@@ -1524,7 +1524,7 @@ V1.43 不放宽 V1.41 的文本型 `game-creator-provider-handoff.v1`，而是
 - `npm run test -- apps/ai-game-creator-shell/tests`
 - `cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml`
 - `cargo check --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml --target x86_64-pc-windows-gnu`
- `cargo test -p platform-agent --manifest-path server-rs/Cargo.toml game_creation`
+- `cargo test -p platform-llm --manifest-path server-rs/Cargo.toml`
 - `cargo test -p shared-contracts --manifest-path server-rs/Cargo.toml game_creation_app`
 - `npm run ai-game-creator-shell:agent-run:smoke`
 - `npm run ai-game-creator-shell:agent-runtime:real-e2e -- --config-dir <AppData> --suite llm-runtime`
@@ -499,7 +499,7 @@ game-project/
 - 单窗口首页和项目组页可选择、打开、新建或显示当前输入的项目绝对路径；最近项目行也可显示目录，非法或相对路径不会调用系统文件管理器。
 - 普通用户侧的生成、上传、运行、自检、预览状态 / 启动 / 打开 / 停止、记忆写入和画板资产导入都必须先完成 `/project` 初始化；未初始化时只提示设置本地项目，不落到默认临时目录。
 - 终端可用 `npm run ai-game-creator-shell:llm-status` 检查 LLM 客户端配置是否就绪；桌面 App 主窗口“配置”面板可读写 Tauri 应用配置目录中的 `game-creator.config.json`，`/llm-status` / 生成入口读取同一份配置，CLI 开发入口无 AppHandle 时才回退读取仓库旁边的配置模板和 gitignored 本机覆盖文件；不请求上游、不显示 API Key，缺配置时以非零状态退出或在聊天里提示未就绪。
- 终端可用 `npm run ai-game-creator-shell:check` 跑 v1 开发验收：壳 typecheck、`platform-agent` 编排测试、共享契约测试、Tauri Rust 测试和无密钥本地 provider 端到端 smoke。
+- 终端可用 `npm run ai-game-creator-shell:check` 跑 v1 开发验收：壳 typecheck、`platform-llm` 网关测试、共享契约测试、Tauri Rust 测试和无密钥本地 provider 端到端 smoke；已退役的 `platform-agent` 不再进入 workspace 或该门禁。
 - 终端可用 `npm run ai-game-creator-shell:agent-run -- /绝对项目路径 "游戏创作需求"` 跑一次真实 LLM 生成、落盘、`game.static_smoke` 和本地 HTTP 预览；发布 App 读取 Tauri 应用配置目录中的 `game-creator.config.json`，开发 CLI 无 AppHandle 时才读取仓库旁边的配置模板和 gitignored 本机覆盖文件，不把 API Key 写入仓库或项目文件。自动验证可加 `--no-wait`，例如 `npm run ai-game-creator-shell:agent-run -- --no-wait /tmp/genarrative-ai-game-test "像素风反弹弹幕厨房"`，生成预览 trace 后立即停止本地预览，避免终端卡在回车等待。默认 API kind 为 `openai_responses`；旧 Chat Completions 兼容网关设置 `llm.apiKind` 为 `openai_chat`，Anthropic Messages 网关设置 `llm.apiKind` 为 `anthropic`。真实 OpenAI-compatible 网关建议设置 `llm.stream` 为 `true` 跑 Planner 和 Generator，避免长请求非流式空闲断连。
 - 终端可用 `npm run ai-game-creator-shell:agent-run:smoke` 跑一次无密钥本地端到端 smoke：脚本启动本机 OpenAI-compatible SSE 流式测试 provider，预置一个本地上传图片和一个本地上传音频，复用真实 `--agent-run`、Planner / Orchestrator / 角色 agent / Generator / Evaluator loop、本地落盘、`game.static_smoke` 和本地 HTTP 预览，并断言每次 provider 请求都使用 `stream: true`、Planner 与 Generator 分别命中自己的 `agentLlm` provider 配置、provider prompt 收到图片与音频资产上下文以及最近对话上下文、生成 HTML 引用这些资产、预览服务能用 `GET` 读取 `/assets/...`、用 `HEAD` 返回真实资源长度和对应 MIME、headless Chrome 打开预览后至少执行一帧游戏 JS，且通过确定性亮色探针采样证明 canvas 不是空白画布、`.agent/run.latest.json` 的 step group 覆盖 design / balance / art / audio / code / publishing 六组、第二轮会重跑 Evaluator 命中任务及其下游影响任务，未受影响角色 carry-over；随后脚本自动给 CLI 发送回车停止预览。该脚本只用于开发验证，不进入产品生成路径。
 - `npm run ai-game-creator-shell:dev` 的 Tauri `devUrl` 固定为 `http://127.0.0.1:3080/`，Vite 必须 `strictPort` 对齐；`beforeDevCommand` 先复用已经跑在 3080 且页面标题为 `AI 游戏创作` 的本 app Vite server，否则才启动新的 Vite，若端口被其它服务占用则直接失败并提示释放端口。
@@ -0,0 +1,87 @@
+# 旧创作模板业务退役方案
+
+更新时间：`2026-07-21`
+
+## 目标
+
+退役整个旧创作模板体系及其专属运行态，同时保留全部相关历史持久化表、迁移白名单和必要的兼容读取定义。历史数据不删除，持久化表及字段不删除、不改名、不重排、不改变类型。
+
+本次执行口径是“数据壳保留，业务实现退役”：历史表继续以最小 schema 代码随 `spacetime-module` 编译和发布；旧模板选择、生成、发布、公开业务详情、作品广场、排行榜和专属运行态不再进入正式编译链或运行路由。基于图片编辑器项目与公开素材的新版 `/creation` 创作工具主页及平台公共侧边栏继续作为现役能力保留。
+
+## 范围
+
+### 退役
+
+- RPG / 自定义世界、拼图、拼消消、大鱼吃小鱼、敲木鱼、方洞挑战、视觉小说、汪汪声浪、寓教于乐、Creative Agent、Match3D、跳一跳和儿童动作 Demo 的前端页面、路由、工作台、结果页、运行态、service、测试及专属素材生成入口。
+- `api-server` 中上述业务的 router、handler、service、生成与发布编排、公开详情、专属 runtime 和 worker 启动点。
+- `spacetime-client` 的模板业务 facade、mapper、reducer/procedure 调用和业务 DTO 依赖。
+- `spacetime-module` 的模板 reducer、procedure、业务 view、初始化逻辑和领域规则调用。
+- 所有纯模板 crate、RPG 专属运行态 crate 及旧 Creative Agent 的 `platform-agent` crate 的 workspace/default 目标和在运依赖边。
+- 后台及主站中只服务于旧创作入口的配置、灰度、展示、搜索、启动、追踪和运维门禁。
+
+### 保留
+
+- 全部旧模板历史持久化表及其原有字段顺序、字段类型、默认值、索引和可见性。
+- `migration.rs` 中相关表的迁移白名单、表名兼容和字段目录。
+- 为历史审计、迁移、资产归属核对所必需的最小只读表定义；不得借兼容读取重新暴露旧创作、发布、公开详情或运行接口。
+- 编辑器、项目、账号、钱包、资产、HostBridge、运维和安全等平台公共能力。
+- 通用 `feature_gate_config`、`GET/PUT /admin/api/feature-gates` 与后台 `#gray-release` 控制页。灰度页只读取通用 gate，不再请求旧 `/admin/api/creation-entry/config`，固定目标只登记现役功能；不得恢复 `creation-entry:*` 动态目标。
+- 新版 `/creation` 创作工具主页、`/project` 项目入口、稳定的 `/profile` 个人页路由、`creation-home` 展示组件与现役静态资产。桌面端保留“创作 / 项目 / 我的”公共侧边栏，移动端保留同样三项的底部 dock；“我的”保留头像 / 昵称编辑、陶泥号复制、钱包与账单、统计、充值、兑换码、玩家社区、反馈、通用设置、开发者 API Key 和法律信息，不恢复旧模板入口、旧作品架或生成队列。
+- `runtime_setting` 是账号级公共设置事实，不属于旧模板运行态。原表结构和数据不变，继续由鉴权后的 `GET/PUT /api/runtime/settings`、`get_runtime_setting_or_default` 与 `upsert_runtime_setting_and_return` procedure 支撑音乐音量和平台主题读写。
+- 旧页面、测试、素材、handler、service、worker、生成 bindings 和纯业务 crate 的源码目录；它们仅用于历史追溯，不属于任何正式入口或编译目标。
+
+## 编译边界
+
+### 前端
+
+- 主路由、Vite 入口和运行时动态 import 不得引用旧业务目录。
+- 正式应用入口使用 `active-main.tsx`、`ActiveApp.tsx`、`routing/activeAppRoutes.tsx`、`routing/activeAppPageRoutes.ts`、`services/activeAppTitle.ts`、`platform-entry/PlatformEntryActiveFlowShell.tsx`、`platformEntryActiveTypes.ts` 和 `creation-home/`；原同名非 active 文件保持历史源码原貌并退出 Vite、TypeScript、ESLint 和 Vitest。
+- 旧业务源码与素材保留在仓库中；Vite 不得再引用入口或动态 import，TypeScript、ESLint、Vitest 必须明确排除旧目录和专属测试。退役源码只用于历史追溯，不允许从在运代码重新导入。
+- 平台公共 profile 请求与展示模型必须位于 `services/platform-entry/` 和现役 `platform-entry` 文件，不得因为沿用账号、钱包或设置能力而继续 import `services/rpg-entry`、`services/rpg-runtime` 或 `components/rpg-entry`。Vite 对退役模块实行实际 module graph 门禁，命中即中止 dev/build；ESLint restricted imports 作为更早的源码反馈。
+- 原 `main.tsx`、`App.tsx`、旧路由、旧标题映射、`PlatformEntryFlowShellImpl.tsx` 与旧入口类型保持原样；正式链路由 `active-main.tsx`、`ActiveApp.tsx`、`activeApp*`、`PlatformEntryActiveFlowShell.tsx` 和 `platformEntryActiveTypes.ts` 承载，只包含新版创作主页、项目、编辑器、账号、设置与钱包公共能力。`retired/legacy-creation-templates/frontend/original/` 另保留逐文件原样快照。
+- 退役 CSS 的源码过滤必须在 Tailwind/Vite 转换前执行，产物过滤留在 `generateBundle`；禁止在 `post` transform 中把 Vite 已生成的 JavaScript 样式模块重新交给 PostCSS 解析。
+- 顶层退役 module 也必须受编译门禁约束：`src/uiAssets.ts`、`src/types.ts`、`src/types/**`、`src/services/runtimeAudioFeedback.ts`、`src/services/publicWorkCode.ts`、`creationEntryConfigService`、`creationUrlState`、`customWorld*`、`runtimeGuestAuth`、`runtimeRequest`、`input-devices/**`、`useMocapInput`、`wechatMiniProgramSubscribe`、`useCombatFlow` 和 `useStoryOptions` 不得进入 Vite module graph、TypeScript、ESLint 或 Vitest，现役公共品牌资产应从独立公共定义导入。
+- `src/games/**`、`src/data/**`、`src/prompts/**`、旧 `App.tsx` / `main.tsx` / `RpgRuntimeApp.tsx` / `*PlaygroundApp.tsx`、旧 `appRoutes` / `appPageRoutes` 和 `services/ai.ts` 同属退役源码边界；Vite 必须在 pre-transform 阶段拒绝直接请求，不能只依赖现役入口未 import 或构建 tree-shaking。
+- `src/components`、`src/hooks`、`src/persistence`、`src/routing` 和 `src/services` 根级文件是新旧混合区，Vite 与 ESLint 必须使用显式现役白名单。当前只放行正式入口实际依赖的根级公共模块；新增根级公共模块时必须同步登记，未登记文件按退役源码处理。各现役子目录继续按独立目录边界放行。
+- 退役静态资产 `/audio/**`、`/chat.png` 和 `/fusion-pixel.ttf` 不得由 Vite dev server 提供，也不得进入生产产物；旧 pixel / story-tab / 玩法 CSS 仅能在历史源码中存在。
+- 所有同源 `/generated-*` 裸读路径在 Vite、Nginx、Pingora 和 `api-server` 均返回空 `404`；历史对象 key 只允许作为 `legacyPublicPath` 进入 `/api/assets/read-url` 等现役签名读取链，不恢复旧生成资产代理。
+- `/creation`、`/project` 和 `/profile` 是现役稳定路由，刷新及浏览器前进 / 后退必须保持当前页签。生产网关对旧子路径返回 404，客户端若收到未知旧页面路径则回落当前平台公共首页；Vite dev 对旧 `/api/creation*` 与 `/api/public-works*` 直接返回 404，不能回落为 SPA HTML。小程序不再注册旧生成结果订阅授权页。
+
+### Rust
+
+- `api-server` 不声明模板模块，不挂模板路由，不保留模板 worker 启动点。
+- 现役 external generation worker 只领取 `source_module = editor-canvas` 的任务，历史旧玩法 pending / running 行不得被领取或改写。
+- `spacetime-client` 不保留模板业务 facade 和 mutation 调用；历史表生成绑定只允许服务必要兼容读取。
+- `spacetime-module` 对旧模板只编译历史表结构，不导出旧 reducer、procedure、业务 view 或领域规则。
+- 旧 `public_work_asset_read_grant` view 与十类旧作品授权计算退出 module；匿名资产读取只保留现役 editor showcase 授权。
+- `spacetime-module` 与 `spacetime-client` 的 Cargo `lib.path` 固定指向各自的 `src/active.rs`；原 `src/lib.rs` 及旧业务源码继续原位保留，但不再作为 crate 根参与编译。
+- 历史表最小定义集中在 `spacetime-module/src/legacy_schema/` 与 `spacetime-module/src/runtime/legacy_schema/`，混合 profile 表的在运数据壳位于 `spacetime-module/src/runtime/active/profile.rs`；这些目录只允许 schema 和必要兼容读取定义。
+- SpacetimeDB schema guard 比较当前工作树与基线提交时，两侧都必须分别读取各自 `Cargo.toml` 的 `lib.path`，再沿 `mod` / `#[path]` 只扫描该快照 crate root 可达的 schema；不得递归扫描整个 `src/`，否则原位保留的旧源码会与现役历史数据壳产生假 accessor 重复。
+- `module-runtime` 仍是账号、钱包、公共设置、追踪和 feature gate 的现役领域 crate；其混合源码中的 `CreationEntry*`、旧公开作品、旧存档 / 浏览历史 / 游玩统计 DTO、command、mapper 和规则必须以编译条件退出，且不再依赖只为旧创作契约存在的 `shared-contracts`。历史 schema 只继续编译 `RuntimeBrowseHistoryThemeMode` 六个变体和完整保序的 `RuntimeProfileWalletLedgerSourceType` 等持久化 ABI，不保留围绕这些类型的旧业务实现。
+- 纯模板 crate 和专属运行态 crate 不属于 workspace members、default members 或任何在运 crate 的依赖图；源码目录保持原样。
+- `platform-agent` 及其专属 `langchainrust` 依赖同样退出 workspace 与 `api-server` 依赖图；现役编辑器 Agent 仅需的模型常量收口到 `platform-llm`，不再通过旧拼图 Phase 1 / Creative Agent 执行器 crate 复用。
+- `platform-auth` 不再编译 runtime guest token；`platform-wechat` 不再编译旧生成结果订阅服务，只保留现役认证和支付协议。
+
+## 验收
+
+- 旧 URL 不再命中旧页面或后端路由。
+- `/creation`、`/project` 与 `/profile` 在桌面端显示“创作 / 项目 / 我的”公共侧边栏，在 `390x844` 等移动视口显示同样三项的底部 dock；点击、刷新及浏览器前进 / 后退均保持路由与选中态一致。新创作主页只调用编辑器项目和公开编辑器素材接口；顶栏保持现役搜索、公共泥点入口与账号胶囊，不重新拼装平行账号按钮组。
+- “我的”桌面布局按原平台公共资料页全宽展示四个常用入口、两行设置和法律栏；头像、昵称、复制、充值、兑换码、社区、反馈、API Key 等入口可用，但不发起旧模板、旧公开作品或旧运行态请求。
+- 鉴权访问 `GET/PUT /api/runtime/settings` 不得返回 404，读写必须经 `spacetime-client` 调用现役 settings procedure；未鉴权请求返回 401，不恢复任何旧运行态设置路由。
+- `tsc --listFilesOnly` 与 Vite 干净加载均不得出现旧业务目录、上述顶层退役 module 或小程序旧订阅授权实现。
+- 直接请求代表性的旧 `games` / `data` / `prompts` / 顶层 App 模块必须被 Vite module graph 门禁拒绝；现役 `creation-home`、项目、profile 与 editor 模块仍正常转换。
+- 根级旧组件、hook、persistence、routing 和 service 必须同时被 Vite 拒绝并被 ESLint 忽略；现役根级图片解析、设置、路由和 API client 文件必须继续参与两套门禁。
+- Vite 构建产物和依赖图不包含旧前端业务目录、Fusion Pixel / pixel 业务样式或旧 runtime 声音签名；产物中不存在 `dist/audio/**`、`dist/chat.png` 或 `dist/fusion-pixel.ttf`。
+- 旧生成资产前缀和现役 editor 对象前缀的同源裸读都必须返回空 `404`，不能返回 `index.html` 形成 soft 404；编辑器真实资产读取继续走签名 URL。
+- `cargo tree` 中不存在纯模板 crate、专属运行态 crate、`platform-agent` 或 `langchainrust`。
+- `npm run check:module-runtime-artifact` 对实际 `module_runtime.rlib` 的 object 成员执行负向扫描：旧创作、存档、浏览与游玩符号和字面量必须为零，同时 `RuntimeBrowseHistoryThemeMode`、`RuntimeProfileWalletLedgerSourceType` 与 `RuntimeSettingSnapshot` 等兼容 ABI 必须仍存在。
+- `spacetime-module` 编译结果仍包含全部历史表，但不包含任何旧模板 reducer、procedure 和业务 view。
+- `platform_auth.rlib` 不包含 runtime guest token 符号，`platform_wechat.rlib` 不包含订阅消息发送符号；历史旧队列行不满足现役 worker claim 条件。
+- `npm run check:spacetime-schema`、定向 Rust 检查、前端类型检查、`npm run check:encoding`、`git diff --check` 通过。
+
+## 历史记录兼容
+
+- 历史数据库行、作品号、`worldType` 和资产对象前缀可以继续被审计或迁移工具识别，但不再形成面向用户的列表、详情、创作或运行入口。
+- 旧公开作品号、创作 URL 和统一创作规格不再作为前端可启动契约；未知或旧 URL 统一回落平台公共首页。
+- 历史表名、资产对象前缀和后台数据库表目录可继续出现旧域名，它们属于数据审计与资产读取边界，不代表旧业务仍在运行。
+- 原本与历史表混在同一文件的 reducer/procedure 实现按模块保存在 `retired/legacy-creation-templates/rust/`，不属于任何 Cargo workspace/module；从全局样式表移出的专属 CSS 保存在同目录的 `frontend/` 下且不被 Vite 导入。
@@ -56,7 +56,7 @@ RAG 默认不安装运行时依赖，也不把 LanceDB、Transformers.js 或本
 - 移动端优先，同时保证桌面端体验完整。
 - 弹出独立面板的交互使用弹窗、抽屉、popover 或页面级 portal，不在当前面板下面追加内容。
 - 页面展示以后端返回状态为准，不在前端自行计算结论型业务状态。
- 创作入口事实源来自 SpacetimeDB，经 `/api/creation-entry/config` 下发；前端只做展示派生。
+- 现役平台入口固定为 `/creation`、`/project`、`/profile`：创作主页只读取图片编辑器项目与公开编辑器素材，个人页只复用账号、钱包和公共设置能力。旧 `/api/creation-entry/config` 及模板工作台、公开作品和专属运行态已经退役，不得因历史表仍在而恢复前端入口或后端接口。
 - 优先扩展现有公共组件，例如平台弹窗、图片输入、媒体预览、状态提示和动作按钮，不在业务页复制通用逻辑。

 ## 后端与数据真相
@@ -20,7 +20,6 @@
 - API 契约：`packages/shared/src/contracts/runtime.ts`、`server-rs/crates/shared-contracts/src/runtime.rs`
 - 后端下单与订单编排：`server-rs/crates/api-server/src/runtime_profile.rs`、`server-rs/crates/api-server/src/wechat/pay.rs`
 - 微信支付 / 虚拟支付协议适配：`server-rs/crates/platform-wechat/src/pay.rs`
- 微信订阅消息协议适配：`server-rs/crates/platform-wechat/src/subscribe_message.rs`
 - WebView 回流确认：`GET /api/profile/recharge/orders/{orderId}/wechat/events`、`POST /api/profile/recharge/orders/{orderId}/wechat/confirm`
 - 微信登录态保存：`server-rs/crates/platform-auth/src/lib.rs`、`server-rs/crates/module-auth/src/lib.rs`

@@ -38,9 +37,6 @@ WECHAT_MINI_PROGRAM_VIRTUAL_PAYMENT_QUERY_ORDER_ENDPOINT=https://api.weixin.qq.c
 WECHAT_MINI_PROGRAM_VIRTUAL_PAYMENT_NOTIFY_PROVIDE_GOODS_ENDPOINT=https://api.weixin.qq.com/xpay/notify_provide_goods
 WECHAT_MINIPROGRAM_MESSAGE_TOKEN=<微信消息推送 Token>
 WECHAT_MINIPROGRAM_MESSAGE_ENCODING_AES_KEY=<微信消息推送 EncodingAESKey>
-WECHAT_MINIPROGRAM_SUBSCRIBE_MESSAGE_ENABLED=true
-WECHAT_MINIPROGRAM_GENERATION_RESULT_TEMPLATE_ID=m5z7BkkBhJGbcH0cdDeHaeRU2tViDEguP38XdrRRCdU
-WECHAT_MINIPROGRAM_SUBSCRIBE_MESSAGE_STATE=formal
 WECHAT_MINI_PROGRAM_VIRTUAL_PAYMENT_ENV=0
 ```

@@ -187,5 +183,4 @@ npm run spacetime:wechat-virtual-payment:reconcile -- \
 - Web 侧在拉起虚拟支付后会短时轮询 `wx_pay_result`，即使小程序 `web-view` 回写 hash 没触发浏览器 `hashchange`，也必须展示回写的微信错误内容。
 - WebView 返回但没有拿到 `wx_pay_result` 时，前端必须主动调用订单确认接口，并接入 `/api/profile/recharge/orders/{orderId}/wechat/events` 的 SSE 事件流作为服务端推送兜底；虚拟支付确认接口会使用当前用户后端保存的小程序 `openid` 调用官方 `/xpay/query_order`，查到已支付且契约校验通过后写入订单。后端通过消息推送或查单入账后都会发布订单更新，SSE 先推当前订单快照，再在订单结束时推 `done`。
 - Web Native 二维码弹窗也必须在展示后立即订阅同一订单 SSE，收到支付回调入账后的 `paid` 快照时自动关闭二维码、刷新充值中心与全局余额并展示一次成功结果；“我已支付”只作为主动查单兜底，不能是扫码付款后的唯一状态推进入口。SSE 在等待窗口结束或短暂断线时按订单过期时间重连，关闭弹窗时必须取消订阅。
- 小程序订阅消息用于 AI 创作生成结果通知：H5 在生成动作发起前先把页面切到生成进度态并立即调用生成 action，同时非阻塞跳转到小程序原生订阅授权页尝试请求授权；授权接受、拒绝或页面返回都不得阻塞或取消生成。原生页不得改写上一页 `webViewUrl`，避免返回后丢失 H5 当前进度页状态。通知发送只允许发生在玩法草稿生成成功或失败终态之后，api-server 使用当前用户微信登录保存的 openid 调用微信 `subscribeMessage.send`。发送失败只记录 warning，不阻断作品生成。模板 `thing1` 发送玩法模板名，`number6` 发送本次生成结算后的实际泥点扣除，失败退款后固定为 `0`；模板 `time4` 字段必须是北京时间 `YYYY-MM-DD HH:mm`。`WECHAT_MINIPROGRAM_SUBSCRIBE_MESSAGE_STATE` 支持 `formal` / `trial` / `developer`，应与当前发布环境一致。
 - WebView 返回后，在订单状态拉取或 SSE 等待期间展示不可关闭遮罩“正在确认支付”，阻止用户离开或继续操作；只有确认到最终订单状态后才展示一次最终结果弹窗，不能先弹“正在支付/支付已提交”再二次弹成功。
@@ -1,5 +1,7 @@
 # 创作主页与项目入口改版计划

+> 2026-07-18 退役覆盖：本文关于旧模板入口、`/creation/<play>`、移动端隐藏“创作 / 项目”和 `/api/creation-entry/config` 的内容均已被后续实现替代，只保留为阶段设计记录。现役口径是桌面侧边栏与移动端底部 dock 都显示“创作 / 项目 / 我的”，稳定路由为 `/creation`、`/project`、`/profile`；旧模板业务只保留历史数据壳。当前实现与验收以 `docs/technical/【架构下线】旧创作模板业务退役方案-2026-07-17.md` 为准。
+
 日期：2026-06-18

 ## 背景
@@ -73,11 +75,11 @@

 ### 陶泥儿精选

-`陶泥儿精选` 是页面底部的全站公开画布生成素材瀑布流，不承载玩法入口列表。瀑布流卡片按真实素材宽高设置预览比例，同一行允许出现不同高度卡片，不使用固定等高网格。创作入口配置仍继续来自 `/api/creation-entry/config`，供旧创作入口和具体 `/creation/<play>` 工作台使用，但不作为本页精选区内容。
+`陶泥儿精选` 是页面底部的全站公开画布生成素材流，不承载玩法入口列表。列表按 DOM 顺序做循环分列：当前为三列时，第 1 / 2 / 3 张分别进入第 1 / 2 / 3 列，第 4 / 5 / 6 张再分别接到这三列下方，后续持续循环；不用最短列贪心分配改变每组的列归属。列数根据精选容器真实可用宽度自动在三、二、一列之间切换，不以整个 viewport 宽度硬判断。卡片仍按真实素材宽高设置预览比例，每张紧贴本列上一张且保留正常 gap，不拉伸、裁成等高卡，也不使用 multi-column 的纵向平衡或标准 Grid 的共享行高。

 精选内容只使用用户从账号级素材库主动提交、后台审核通过且展示状态开启的 `editor_showcase_asset` 快照。新生成素材不会默认公开，审核通过后也不会自动展示；运营可在后台按前台具体 Tab 设置分类（角色、UI、音乐、美宣）并开启展示，未设置分类的素材不会隐藏，会进入前台“全部”。旧 `editor_project_resource.public_showcase_enabled` 只保留历史兼容，不再作为 `/creation` 精选事实源。账号级 `editor_asset` 仍是素材库私有事实；只有 `sourceType="generated"`、有媒体内容、提交审核并通过的素材才可进入精选，上传素材、公开作品图片和 `mock_generated` 资源都不进入精选。审核通过时按生成成本返还 50% 泥点，返还流水使用确定性 `editor-showcase-refund:{showcaseId}` 保证幂等；批准状态、钱包返还流水和 `refund_completed_at` 必须在同一个 SpacetimeDB 事务中完成，任一步失败都保持待审核，历史已通过但未返还记录重复批准时按同一流水补齐且不得重复入账。已通过、已开启展示且返还完成的精选快照必须按同 owner 的精确 `assetObjectId` 或 `objectKey` 派生匿名读取授权，不能放开整个 `generated-*` 前缀。公开 BFF 必须返回作者公开展示字段：优先 `authorDisplayName` / `display_name`，没有展示名时兜底 `authorPublicUserCode` / 陶泥号；前端展示绝不能兜底到内部 `ownerUserId` / `user_id`。若现有数据缺少提示词、作者公开标识或成本字段，v1 显示保守占位，不伪造内容。

-瀑布流通过 `GET /api/editor/showcase/resources` 按通过审核时间 / `showcaseId` 倒序 cursor 分页读取，每页最多 36 条；响应有 `nextCursor` 时，页面滚动到底部继续请求 `?cursor=...` 并追加到现有瀑布流，而不是固定只展示首屏数量。响应可以额外携带后台配置的固定活动卡，用于在列表首位展示运营精选。
+精选素材流通过 `GET /api/editor/showcase/resources` 按通过审核时间 / `showcaseId` 倒序 cursor 分页读取，每页最多 36 条；响应有 `nextCursor` 时，页面滚动到底部继续请求 `?cursor=...` 并追加到现有列表，而不是固定只展示首屏数量。追加、筛选、分类和容器/卡片尺寸变化都必须按当前完整 DOM 顺序重算循环分列；位置未完整时保留正常文档流 fallback，不能让分页 sentinel 因容器短暂零高提前触发。响应可以额外携带后台配置的固定活动卡，用于在列表首位展示运营精选；活动卡作为第一张进入第一列，普通素材从第二张继续同一循环列序。活动卡图片继续保持 private：后台直传 OSS 后必须先确认正式 `asset_object`，公开读取只由已启用 `global` 配置对活动卡专用目录中的当前 exact `imageObjectKey` 派生，禁用或替换图片后旧 key 不再可读；历史缺 metadata 的当前活动卡可通过同一 exact 配置授权恢复，但新上传不能跳过 confirm。

 Tab：

@@ -120,6 +122,7 @@ Tab：
 - 上传素材、公开作品图片、mock 资源和假组合都不进入精选。
 - 任意画布左侧素材列表中，单个素材右键打开素材菜单；原外置删除按钮移入该菜单，以文字 `删除` 展示。生成素材菜单内提供 `提交精选审核`，调用 `POST /api/editor/assets/{assetId}/showcase-submissions` 后进入 `pending` 状态；已提交、已通过或已拒绝的素材显示对应状态，不再显示默认打开的公开勾选项。素材不可提交或后端拒绝提交时，菜单必须显示具体原因，例如非生成素材、素材尚未保存、没有媒体内容或审核未通过不能重复提交。
 - 后台新增纯素材查询页，读取账号级 `editor_asset` 中 `sourceType="generated"` 的素材，用于查看所有用户生成素材。该页只提供时间、用户 ID 和关键词查询，以及缩略图详情、提示词全文、生成成本、作者展示名和陶泥号查看；不提供分类筛选，也不承载审核、返还、展示开关或活动卡配置操作。
+- 后台“素材查询”和“精选审核”必须共用同一套素材缩略图、媒体类型判断、私有地址换签与放大预览弹窗：缩略图只在进入视口附近后错峰换签，遇到管理端限流时执行有上限的退避重试；点击缩略图直接打开图片、音频或视频预览，详情继续由独立“详情”按钮进入。无 `objectKey` 的历史绝对 OSS 地址也必须先归一为 generated legacy path 再换签，不能把私有裸地址直接交给浏览器。
 - 不为了填满展示区创建假素材、假作者、假泥点成本或假组合关系。
 - 暂无真实数据的 Tab 保留 Tab 入口，但内容区显示简洁空态。

@@ -161,7 +164,7 @@ Tab：
 ### 创作主页

 - 新增 `CreationLandingView`。
- 实现首屏主视觉、九大功能区、最近项目区和陶泥儿精选素材瀑布流。
+- 实现首屏主视觉、九大功能区、最近项目区和陶泥儿精选顺序循环分列素材流。
 - 九大功能区卡片必须是可点击按钮；已开放卡片复用 `createEditorProject` 和画布现有生成器，不新增入口系统；暂未开放卡片复用移动端欢迎弹窗样式。
 - 桌面端复用现有平台壳层，保留上方栏和左侧导航栏。
 - 主页整体采用浅色布局，避免外站品牌文案。
@@ -220,8 +223,8 @@ git diff --check
 - 移动端进入 `/` 首页时显示 `欢迎` 弹窗，正文包含移动端仅支持作品展示和电脑端访问提示，按钮为 `好`。
 - 移动端直达 `/creation` 显示“请在桌面端打开创作主页”，点击“返回首页”回到 `/`。
 - “我的”页没有项目快捷入口。
- 陶泥儿精选素材瀑布流不出现账号级非项目素材、公开作品补充、上传素材、mock 素材、假作者或假泥点成本。
- 陶泥儿精选素材卡按真实素材宽高呈现瀑布流，不退化为固定等高网格。
+- 陶泥儿精选素材流不出现账号级非项目素材、公开作品补充、上传素材、mock 素材、假作者或假泥点成本。
+- 陶泥儿精选按 DOM 索引循环分列，每组卡片依次占用当前所有列，列内不因其它列的高卡留空；卡片按真实素材宽高呈现，不强制固定等高。列数必须根据精选容器实际宽度自动变为三/二/一列，不以 viewport 断点代替容器宽度。
 - 陶泥儿精选不出现玩法入口卡或公开作品图片补充展示。

 ## 非目标
@@ -1,8 +1,24 @@
 # 平台入口与玩法链路

-更新时间：`2026-06-10`
+> 2026-07-17 退役覆盖：全部旧创作模板的前端、API、worker、reducer/procedure、纯业务 crate、生成发布链路、公开业务详情和专属运行态已下线，仅保留相关历史表的数据壳与必要兼容读取。本文后续玩法章节只作为历史设计记录，不再描述当前可用能力；当前实现与验收以 `docs/technical/【架构下线】旧创作模板业务退役方案-2026-07-17.md` 为准。

-## 平台创作入口
+更新时间：`2026-07-18`
+
+## 现役平台壳
+
+旧创作模板退役后，桌面端继续保留统一平台壳，一级导航固定为 `创作 / 项目 / 我的`：
+
+- `/creation` 展示基于图片编辑器的创作工具主页，只读取编辑器项目与公开编辑器素材。
+- `/project` 展示当前账号的图片编辑器项目，项目卡继续进入 `/editor/canvas`。
+- `/profile` 是“我的”稳定路由，保留头像与昵称编辑、陶泥号复制、泥点余额与账单、累计统计、泥点充值、兑换码、玩家社区、反馈与建议、通用设置、开发者 API Key 和法律信息等平台公共能力。
+- 桌面顶栏保留现役项目 / 素材搜索、泥点入口和账号胶囊。搜索只筛选当前编辑器项目与已读取的公开编辑器素材，不恢复旧公开作品号搜索、旧广场、旧作品详情或旧运行态。
+- 桌面端使用公共侧边栏，移动端使用同样包含“创作 / 项目 / 我的”的三项底部 dock；点击、刷新及浏览器前进 / 后退都必须保持 URL、标题和选中态一致。
+
+现役入口和公共资料能力只能依赖 `creation-home`、`project`、`image-editor`、公共组件及 `services/platform-entry` 等现役模块。Vite 模块门禁会拒绝 `components/rpg-entry`、`services/rpg-entry`、旧玩法目录和旧平台业务模块进入依赖图；Tailwind `@source`、TypeScript `include`、ESLint ignore 或 Vite watch ignore 都不能替代这条运行时依赖门禁。
+
+## 历史平台创作入口
+
+本节及后续玩法章节保留退役前的设计记录，其中出现的 `/api/creation-entry/config`、`/creation/<play>`、模板工作台、公开作品和专属运行态均不是现役契约，不得用于当前实现或运维验收。

 创作入口配置事实源在 SpacetimeDB，通过 `GET /api/creation-entry/config` 下发；后台通过 `/admin/api/creation-entry/config` 管理入口开关，通过 `/admin/api/creation-entry/config/interactions` 管理公开作品点赞 / 改造能力矩阵。前端只在展示层派生可见卡片、入口状态和作品详情互动状态，`api-server` 路由熔断也使用同一份配置。不要恢复前端硬编码入口配置文件。

--- a/Show More
+++ b/Show More