Merge branch 'master' into editor-agent-abortable

# Conflicts: # docs/project-memory/shared-memory/decision-log.md
2026-07-23 18:53:01 +08:00
parent fe29e8ffef a2ee879fc8
commit 0c077a876e
255 changed files with 22921 additions and 2245 deletions
@@ -1,6 +1,6 @@
 ---
 name: spacetimedb-cli
-description: SpacetimeDB 2.6 CLI reference for Genarrative. Use for spacetime build, publish, generate, call, sql, logs, server management, local dev, explicit server targeting, version checks, and remote runtime verification.
+description: SpacetimeDB 2.7 CLI reference for Genarrative. Use for spacetime build, publish, generate, call, sql, logs, server management, local dev, explicit server targeting, version checks, and remote runtime verification.
 ---

 # SpacetimeDB CLI
@@ -68,6 +68,31 @@ spacetime call --server http://127.0.0.1:3101 my-db reducer_needing_identity 0xa
 spacetime subscribe my-db "SELECT * FROM users" --num-updates 10 --server http://127.0.0.1:3101
 ```

+## Standalone MCP Endpoint (2.7)
+
+SpacetimeDB 2.7 standalone exposes an authenticated JSON-RPC MCP endpoint at
+`POST /v1/database/{name_or_identity}/mcp`. It advertises `ping`, `get_schema`,
+`sql`, and `call`. The SQL and reducer tools execute with the bearer token's
+identity, so keep routine smoke checks read-only.
+
+```bash
+curl -fsS \
+  -H "Authorization: Bearer ${SPACETIME_TOKEN}" \
+  -H 'Content-Type: application/json' \
+  --data '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"genarrative-smoke","version":"1.0.0"}}}' \
+  http://127.0.0.1:3101/v1/database/my-db/mcp
+
+curl -fsS \
+  -H "Authorization: Bearer ${SPACETIME_TOKEN}" \
+  -H 'Content-Type: application/json' \
+  --data '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"ping","arguments":{"message":"genarrative"}}}' \
+  http://127.0.0.1:3101/v1/database/my-db/mcp
+```
+
+For repository upgrade validation, also call `tools/list` and the read-only
+`get_schema` tool against an isolated local database. Do not use `sql` or `call`
+for writes unless that mutation is explicitly in scope.
+
 ## Server & Auth

 ```bash
@@ -102,7 +127,7 @@ curl -fsS http://127.0.0.1:3101/v1/ping
 | Flag | Description |
 |------|-------------|
 | `--server`, `-s` | Target server nickname, host, or URL |
-| `--yes`, `-y` | Non-interactive prompt skipping; in 2.6 use scoped values |
+| `--yes`, `-y` | Non-interactive prompt skipping; in 2.6+ use scoped values |
 | `--delete-data`, `-c` | Publish data policy: `always`, `on-conflict`, or `never` |
 | `--module-path`, `-p` | Module project path |
 | `--bin-path`, `-b` | Publish/generate from compiled wasm |
@@ -146,6 +171,8 @@ pid="$(systemctl show spacetimedb.service -p MainPID --value)"

 ## Notes

- Procedure calls remain stable in 2.6; module HTTP handlers/webhooks and RLS capabilities still require their documented gates.
- 2.5 fixed `publish --delete-data` config fallback; 2.6 keeps that behavior and improves CLI binary distribution.
+- Procedure calls remain stable in 2.7; module HTTP handlers/webhooks and RLS capabilities still require their documented gates.
+- 2.5 fixed `publish --delete-data` config fallback; 2.6 kept that behavior and improved CLI binary distribution; 2.7 adds `spacetime sql --format json` and database `lock` / `unlock`.
+- The official 2.7.0 Linux release archives and container image currently use the `v2.7.0-hotfix3` asset tag while binaries report `2.7.0`; keep the asset tag distinct from the runtime version check.
+- Do not assume `spacetime version install 2.7.0` selected hotfix3: stale updater metadata can install bare-tag commit `a08663c7...`. For the current release, verify CLI commit `d220349a...` and use the official hotfix3 archive or repository provision flow when it differs.
 - Genarrative scripts should pass `--server` or `--server-url` explicitly instead of relying on CLI defaults.
@@ -1,6 +1,6 @@
 ---
 name: spacetimedb-concepts
-description: Understand SpacetimeDB 2.6 architecture, reducer/procedure/table/view semantics, schema evolution, subscriptions, identity, and Genarrative-specific backend boundaries. Use when designing or reviewing SpacetimeDB-backed features.
+description: Understand SpacetimeDB 2.7 architecture, reducer/procedure/table/view semantics, schema evolution, subscriptions, identity, and Genarrative-specific backend boundaries. Use when designing or reviewing SpacetimeDB-backed features.
 ---

 # SpacetimeDB Core Concepts
@@ -20,7 +20,7 @@ SpacetimeDB is a relational database that also executes application logic in upl

 1. **Reducers are transactional**: they do not return data to callers. Read through subscriptions, read models, views, or BFF endpoints.
 2. **Reducers are deterministic**: no filesystem, network, wall-clock, or external RNG. Use `ctx.timestamp`, `ctx.rng()` / `ctx.random()`, and tables.
-3. **Procedures are stable in 2.6**: they can use explicit transactions and outgoing HTTP via `ctx.http`.
+3. **Procedures are stable in 2.7**: they can use explicit transactions and outgoing HTTP via `ctx.http`.
 4. **Identity comes from context**: use `ctx.sender()` or language equivalent for authorization. Never trust identity passed as an argument.
 5. **Auto-increment IDs are not ordering guarantees**: gaps are normal. Use timestamps or explicit sequence columns for ordering.
 6. **Schema changes need migration discipline**: existing Genarrative table fields must be appended with defaults; update migration code, table catalog, generated bindings, and run `npm run check:spacetime-schema`.
@@ -44,25 +44,25 @@ Reducers are deterministic transactional functions. They are the primary client-

 ## Procedures

-Procedures are stable in 2.6. They can be scheduled, can open explicit transactions with `with_tx` / `try_with_tx`, and can use outgoing HTTP (`ctx.http`).
+Procedures are stable in 2.7. They can be scheduled, can open explicit transactions with `with_tx` / `try_with_tx`, and can use outgoing HTTP (`ctx.http`).

 Genarrative default: keep external provider protocols in `platform-*` and orchestration in `api-server` unless a task explicitly moves a workflow into a module procedure.

-Module HTTP handlers/webhooks and RLS `client_visibility_filter` remain subject to their documented gates in 2.6.
+Module HTTP handlers/webhooks and RLS `client_visibility_filter` remain subject to their documented gates in 2.7.

 ## Views

-Views expose computed read-only data. SpacetimeDB 2.6 supports primary keys on procedural views in Rust, TypeScript, and C#. Clients can receive `OnUpdate` events when subscribed to such views with primary keys. Ensure the view never returns duplicate primary keys, because that can fail view refresh and roll back the triggering transaction.
+Views expose computed read-only data. SpacetimeDB 2.7 supports primary keys on procedural views in Rust, TypeScript, C#, and C++. Clients can receive update events when subscribed to such views with primary keys. Ensure the view never returns duplicate primary keys, because that can fail view refresh and roll back the triggering transaction.

 ## Event Tables

 Event tables broadcast reducer/procedure-specific facts to subscribers and must be subscribed explicitly. They are excluded from `subscribe_to_all_tables()`.

-2.6 supports broader layout-altering automigrations for event tables, including column removal, reordering, and type changes that regular tables reject. This relaxed migration behavior is for event-only tables, not persistent tables.
+Since 2.6, event tables support broader layout-altering automigrations, including column removal, reordering, and type changes that regular tables reject. This relaxed migration behavior is for event-only tables, not persistent tables.

 Event-table primary keys and constraints are transaction-scoped. They can reject duplicate event rows within one transaction, but event rows are not retained in client cache, so clients observe event tables through insert callbacks only. Do not design Genarrative event tables around `OnUpdate` / `on_update` / `onUpdate`; use a persistent table or a primary-keyed procedural view when update callbacks are required.

-Official 2.4.1 through 2.6 release notes document primary-key-backed update callbacks for procedural views, not event tables.
+Official 2.4.1 through 2.7 release notes document primary-key-backed update callbacks for procedural views, not event tables.

 ## Subscriptions

@@ -78,7 +78,18 @@ Best practices:
 - Avoid overlapping queries that duplicate row delivery.
 - Use indexes for subscribed filters.

-## 2.2.0 to 2.6.1 Delta
+## Standalone MCP
+
+SpacetimeDB 2.7 standalone exposes `POST /v1/database/{name_or_identity}/mcp`
+using MCP JSON-RPC protocol `2025-06-18`. Its tools are `ping`, `get_schema`,
+`sql`, and `call`; SQL and reducer calls run with the authenticated caller's
+identity. In Genarrative this is an operator/developer integration surface, not
+a replacement for `api-server` BFF routes, `spacetime-client` facades, or public
+read models. Upgrade smoke should use an isolated local database and restrict
+itself to `initialize`, `tools/list`, `ping`, and `get_schema` unless writes are
+explicitly intended.
+
+## 2.2.0 to 2.7.0 Delta

 Genarrative introduced SpacetimeDB around 2.2.0. Important changes since then:

@@ -89,6 +100,7 @@ Genarrative introduced SpacetimeDB around 2.2.0. Important changes since then:
 - **2.5.0**: procedures are stable, C# procedural views gain primary keys, event tables allow broader layout-altering automigrations, BTreeSet storage makes row insertion deterministic and avoids accidentally quadratic bulk insert behavior, `wasm_memory_bytes` billing metric semantics changed, template version constraints unified, `publish --delete-data` config fallback fixed, CLI `call` accepts hex Identity arguments.
 - **2.6.0**: procedural-view primary keys are available across Rust, TypeScript, and C#, commitlog gains `max_segment_size` / `write_buffer_size` / `preallocate_segments`, the default write buffer increases for throughput, event-table automigrations improve, and CLI binary distribution expands.
 - **2.6.1**: procedure contexts again receive the caller `Identity` and `ConnectionId`; generated TypeScript `Option<T>` fields use optional keys; `spacetime init --template` lists available templates when no template argument is supplied.
+- **2.7.0**: existing tables can add unique or primary-key constraints when current data satisfies them; standalone exposes an authenticated database MCP endpoint; Rust adds context-capability and table-accessor traits; `spacetime sql --format json` and database locking are available; view cleanup, backing-table migration, connection metrics, and memory metrics improve. Official current release assets use the `v2.7.0-hotfix3` tag while binaries report `2.7.0`.

 ## Debugging Checklist

@@ -1,6 +1,6 @@
 ---
 name: spacetimedb-rust
-description: Develop SpacetimeDB 2.6 server modules in Rust for Genarrative. Use when writing or reviewing tables, reducers, procedures, views, migrations, row mappers, schema changes, and module logic.
+description: Develop SpacetimeDB 2.7 server modules in Rust for Genarrative. Use when writing or reviewing tables, reducers, procedures, views, migrations, row mappers, schema changes, and module logic.
 ---

 # SpacetimeDB Rust Module Development
@@ -181,11 +181,11 @@ fn deal_damage(ctx: &ReducerContext, target: Identity, amount: u32) {

 Event tables must be subscribed explicitly and are excluded from `subscribe_to_all_tables()`.

-In 2.6, event tables support broader layout-altering automigrations than regular tables, including column removal, reordering, and type changes. This relaxed migration policy does not apply to persistent tables.
+Since 2.6, event tables support broader layout-altering automigrations than regular tables, including column removal, reordering, and type changes. This relaxed migration policy does not apply to persistent tables.

 Event-table primary keys and constraints are enforced only within the current transaction. They do not make event rows persistent, and client SDKs expose event tables as insert-only event streams. Do not rely on `OnUpdate` / `on_update` / `onUpdate` for event tables; use a persistent table or a primary-keyed procedural view when update callbacks are required.

-Official 2.4.1 through 2.6 release notes tie primary-key-backed update callbacks to procedural views, not event tables.
+Official 2.4.1 through 2.7 release notes tie primary-key-backed update callbacks to procedural views, not event tables.

 ## Views

@@ -228,7 +228,7 @@ For scheduled reducers, check `ctx.sender_auth().is_internal()` when the reducer

 ## Procedures

-Procedures remain stable in 2.6 and no longer require the `unstable` feature.
+Procedures remain stable in 2.7 and no longer require the `unstable` feature.

 ```rust
 use spacetimedb::{procedure, ProcedureContext};
@@ -143,6 +143,19 @@ ALIYUN_OSS_POST_EXPIRE_SECONDS="600"
 ALIYUN_OSS_POST_MAX_SIZE_BYTES="20971520"
 ALIYUN_OSS_SUCCESS_ACTION_STATUS="200"

+# BgFilter 受限资源 worker。父 api-server / external-generation-worker 与唯一的
+# `GENARRATIVE_PROCESS_ROLE=bgfilter-worker` 进程必须使用同一个内部 Token。
+# `npm run dev` 与 `npm run dev:api-server` 都会自动带起并验活唯一 worker，不要再开第二个终端重复启动。
+# 只有需要脱离父 API 单独验证 worker 时才运行 `npm run dev:bgfilter-worker`；不要让 `all` 角色兼任它。
+GENARRATIVE_BGFILTER_WORKER_HOST="127.0.0.1"
+GENARRATIVE_BGFILTER_WORKER_PORT="8083"
+GENARRATIVE_BGFILTER_WORKER_BASE_URL="http://127.0.0.1:8083"
+GENARRATIVE_BGFILTER_INTERNAL_TOKEN="CHANGE_ME_FOR_LOCAL"
+GENARRATIVE_BGFILTER_WORKER_CONCURRENCY="16"
+GENARRATIVE_EDITOR_BGFILTER_SINGLE_IMAGE_ESTIMATE_MS="5000"
+GENARRATIVE_BGFILTER_WORKER_MAX_REQUESTS="2048"
+GENARRATIVE_BGFILTER_WORKER_CONNECT_TIMEOUT_MS="2000"
+
 # SpacetimeDB 数据目录备份到 OSS。备份 bucket 可与资源 bucket 分离；未设置时脚本回退使用 ALIYUN_OSS_BUCKET。
 GENARRATIVE_DATABASE_BACKUP_DATA_DIR=""
 GENARRATIVE_DATABASE_BACKUP_WORK_DIR=""
@@ -386,7 +386,6 @@ module.exports = {
    'src/data/**',
    'src/prompts/**',
    'apps/admin-web/src/pages/AdminCreationEntrySwitchPage*',
-    'apps/admin-web/src/pages/AdminGrayReleaseConfigPage*',
    'apps/admin-web/src/pages/AdminWorkVisibilityPage*',
    'src/services/recommendedRuntimeGuestLaunch.test.ts',
    'src/data/sceneEncounterPreviews.ts',
@@ -106,6 +106,18 @@ jobs:
      - name: Run frontend and script tests
        run: npm run test

+      - name: Run BgFilter worker smoke harness tests
+        run: npm run bgfilter-worker:smoke-test
+
+      - name: Validate production health patrol behavior
+        run: npm run check:production-health-patrol
+
+      - name: Validate production API release behavior
+        run: npm run check:production-api-release
+
+      - name: Validate production API deploy behavior
+        run: npm run check:production-api-deploy
+
  backend-tests:
    name: Backend tests
    runs-on: genarrative-ci
@@ -1,8 +1,8 @@
 ---
 name: genarrative-dev-stack-port-routing
 short_description: 修改 Genarrative 本地 dev 启动端口、代理目标、端口冲突处理时使用。
-description: 在 Genarrative 中修改 npm run dev / dev:spacetime / dev:api-server / dev:web / dev:admin-web 的本地启动端口、端口可用性探测、端口漂移、SpacetimeDB publish server、api-server 环境变量、Vite 代理目标和后台 admin-web 启动串联时使用。
-version: 1.0.0
+description: 在 Genarrative 中修改 npm run dev / dev:spacetime / dev:api-server / dev:bgfilter-worker / dev:web / dev:admin-web 的本地启动端口、端口可用性探测、端口漂移、SpacetimeDB publish server、Rust 进程环境变量、Vite 代理目标和后台 admin-web 启动串联时使用。
+version: 1.1.0
 author: Hermes Agent
 license: MIT
 metadata:
@@ -13,7 +13,7 @@ metadata:

 # Genarrative 本地 dev 启动端口与代理目标串联流程

-用于维护 Genarrative 本地开发栈启动脚本，重点覆盖 `npm run dev` 与四个 `dev:*` 单模块命令的端口检查、端口漂移和后续流程目标传递。
+用于维护 Genarrative 本地开发栈启动脚本，重点覆盖 `npm run dev` 与五个 `dev:*` 单模块命令的端口检查、端口漂移和后续流程目标传递。

 ## 适用场景

@@ -31,40 +31,44 @@ metadata:
 2. Rust `api-server`：`8082`，健康检查为 `http://127.0.0.1:<api-port>/healthz`。
 3. SpacetimeDB standalone：`3101`，健康检查为 `http://127.0.0.1:<spacetime-port>/v1/ping`。
 4. 后台 Vite：`3102`，后台地址为 `http://127.0.0.1:<admin-web-port>/admin/`。
+5. 独立 BgFilter worker：`8083`，就绪检查为 `http://127.0.0.1:<bgfilter-worker-port>/readyz`。

 端口不可用时，脚本会从优先端口开始向后寻找可用端口。后续流程必须以解析后的实际端口为准，不能继续使用默认端口。

-Linux 多用户并发开发时，`GENARRATIVE_DEV_PORT_RANGE` 或 `--port-range` 会先向系统级注册表 `/var/tmp/genarrative-dev-port-ranges/registry.json` 申请一个端口段，再把该段映射为 `web = start`、`api = start + 1`、`spacetime = start + 2`、`adminWeb = start + 3`。注册表锁文件是 `/var/tmp/genarrative-dev-port-ranges/registry.lock`，可通过 `GENARRATIVE_DEV_PORT_RANGE_REGISTRY_DIR` 覆盖目录。自动分配从 `10000-10099` 起，每次占用 100 个端口块，后续块按 `10100-10199`、`10200-10299` 递增；当前口径是“一个用户固定占用一个段，后续启动继续复用这段并在段内漂移”；该注册表只在 Linux 上生效；Windows 继续沿用原有端口探测、漂移和复用逻辑，不读系统级注册表。
+Linux 多用户并发开发时，`GENARRATIVE_DEV_PORT_RANGE` 或 `--port-range` 会先向系统级注册表 `/var/tmp/genarrative-dev-port-ranges/registry.json` 申请一个端口段，再把该段映射为 `web = start`、`api = start + 1`、`spacetime = start + 2`、`adminWeb = start + 3`、`bgfilterWorker = start + 4`。注册表锁文件是 `/var/tmp/genarrative-dev-port-ranges/registry.lock`，可通过 `GENARRATIVE_DEV_PORT_RANGE_REGISTRY_DIR` 覆盖目录。自动分配从 `10000-10099` 起，每次占用 100 个端口块，后续块按 `10100-10199`、`10200-10299` 递增；当前口径是“一个用户固定占用一个段，后续启动继续复用这段并在段内漂移”；该注册表只在 Linux 上生效；Windows 继续沿用原有统一端口探测和漂移逻辑，不读系统级注册表。

 ## 实现入口

 - `package.json`
-  - `dev`：执行 `node scripts/dev.mjs`，启动完整四模块。
-  - `dev:spacetime` / `dev:api-server` / `dev:web` / `dev:admin-web`：执行 `node scripts/dev.mjs <module>`。
+  - `dev`：执行 `node scripts/dev.mjs`，启动完整五服务。
+  - `dev:spacetime` / `dev:api-server` / `dev:bgfilter-worker` / `dev:web` / `dev:admin-web`：执行 `node scripts/dev.mjs <module>`；`dev:api-server` 会安全带起其依赖的 BgFilter worker。
 - `scripts/dev-stack-port-utils.mjs`
  - `isPortAvailable(...)`：探测端口是否可监听。
  - `findAvailablePort(...)`：从优先端口向后寻找可用端口，`0` 表示申请临时端口。
-  - `resolveDevStackPorts(...)`：一次性解析 SpacetimeDB、api-server、主站 Vite、后台 Vite 端口，并避免本次解析结果互相冲突。
+  - `resolveDevStackPorts(...)`：一次性解析 SpacetimeDB、api-server、主站 Vite、后台 Vite、BgFilter worker 端口，并避免本次解析结果互相冲突。
  - Linux 注册表分配：`reserveLinuxDevPortRange(...)` / `releaseLinuxDevPortRange(...)`，仅在 Linux 上启用系统级端口段登记与用户段复用，自动分配从 `10000-10099` 起。
-  - CLI 模式：`node scripts/dev-stack-port-utils.mjs resolve-dev-stack spacetime:127.0.0.1:3101 api:127.0.0.1:8082 web:0.0.0.0:3000 adminWeb:127.0.0.1:3102`。
+  - CLI 模式：`node scripts/dev-stack-port-utils.mjs resolve-dev-stack spacetime:127.0.0.1:3101 api:127.0.0.1:8082 web:0.0.0.0:3000 adminWeb:127.0.0.1:3102 bgfilterWorker:127.0.0.1:8083`。
 - `scripts/dev.mjs`
  - 解析 CLI 参数后统一计算 client host、端口、`SPACETIME_SERVER`、`RUST_SERVER_TARGET`。
-  - 完整栈按 SpacetimeDB、publish、api-server、主站 Vite、后台 Vite 顺序启动。
-  - Linux 下会先申请系统级端口段并把它映射成四个 dev 端口；自动分配从 `10000-10099` 起，Windows 则直接沿用原有参数解析与端口漂移逻辑。
+  - 完整栈按 SpacetimeDB、publish、BgFilter worker readiness、api-server readiness、主站 Vite、后台 Vite 顺序启动。
+  - Linux 下会先申请系统级端口段并把它映射成五个 dev 端口；自动分配从 `10000-10099` 起，Windows 则把第五个服务纳入原有统一参数解析与端口漂移逻辑。
+  - 完整栈和 `dev:api-server` 把两个 Rust 进程作为同一重启单元，先全部停止，再先启动 BgFilter worker、后启动 api-server；不要为同一份 Rust 源码创建两个并发 `cargo` watcher。
  - 单模块命令复用同一套参数和 env 解析。

 ## 必须保持的传递链路

-`npm run dev` 和四个 `dev:*` 单模块命令中端口解析后，必须同步到以下位置：
+`npm run dev` 和五个 `dev:*` 单模块命令中端口解析后，必须同步到以下位置：

 1. SpacetimeDB 启动：`spacetime start --listen-addr "${SPACETIME_HOST}:${SPACETIME_PORT}"`。
 2. SpacetimeDB 发布：`spacetime publish ... --server "${SPACETIME_SERVER}"`。
 3. Rust api-server：`GENARRATIVE_API_HOST`、`GENARRATIVE_API_PORT`、`GENARRATIVE_SPACETIME_SERVER_URL`、`GENARRATIVE_SPACETIME_DATABASE`。
 4. api-server 健康检查：`wait_for_api_server "${RUST_SERVER_TARGET}/healthz" ...`。
-5. 主站 Vite：`RUST_SERVER_TARGET`、`GENARRATIVE_RUNTIME_SERVER_TARGET`、`ADMIN_WEB_TARGET`、`ADMIN_WEB_PORT`、`--port=${WEB_PORT}`、`--host=${WEB_HOST}`。
-6. 后台 Vite：`ADMIN_API_TARGET`、`GENARRATIVE_API_TARGET`、`GENARRATIVE_API_PORT`、`--port=${ADMIN_WEB_PORT}`。
-7. 控制台日志：`[dev:ports]` 和 `[dev] web/admin web/api-server/spacetime` 必须显示最终实际地址。
-8. Linux 端口段注册：`[dev] port-range:` 与 `[dev] port-range-registry:` 只在 Linux 输出，Windows 不应依赖系统级注册表。
+5. BgFilter worker：`GENARRATIVE_PROCESS_ROLE=bgfilter-worker`、解析后的 `HOST / PORT`、与父 API 相同的 `GENARRATIVE_BGFILTER_WORKER_BASE_URL` / `GENARRATIVE_BGFILTER_INTERNAL_TOKEN`，以及显式有效的 `N / Q`。
+6. BgFilter worker readiness：父 API 启动前检查解析后地址的 `/readyz`。
+7. 主站 Vite：`RUST_SERVER_TARGET`、`GENARRATIVE_RUNTIME_SERVER_TARGET`、`ADMIN_WEB_TARGET`、`ADMIN_WEB_PORT`、`--port=${WEB_PORT}`、`--host=${WEB_HOST}`。
+8. 后台 Vite：`ADMIN_API_TARGET`、`GENARRATIVE_API_TARGET`、`GENARRATIVE_API_PORT`、`--port=${ADMIN_WEB_PORT}`。
+9. 控制台日志：`[dev:ports]` 和 `[dev] web/admin web/api-server/bgfilter-worker/spacetime` 必须显示最终实际地址。
+10. Linux 端口段注册：`[dev] port-range:` 与 `[dev] port-range-registry:` 只在 Linux 输出，Windows 不应依赖系统级注册表。

 如果只改了其中一段，通常会出现：浏览器打开的前端可用，但 `/api/*` 代理到旧端口；后台页面可用但后台 API 失败；SpacetimeDB 启动在新端口但 publish 仍发往旧端口。

@@ -74,7 +78,7 @@ Linux 多用户并发开发时，`GENARRATIVE_DEV_PORT_RANGE` 或 `--port-range`
   - `scripts/dev-stack-port-utils.mjs`
   - `scripts/dev.mjs`
   - `scripts/dev-utils.mjs`
-   - `docs/technical/RUST_LOCAL_AND_REMOTE_DEPLOYMENT_SCRIPTS_2026-04-22.md`
+   - `docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`
   - `docs/project-memory/shared-memory/pitfalls.md`
 2. 优先改公共端口工具，不要把端口探测逻辑复制到多个脚本。
 3. 修改 `scripts/dev.mjs` 时确认变量顺序：先解析参数和端口，再构造 `SPACETIME_SERVER` / `RUST_SERVER_TARGET`，最后启动对应 service。
@@ -91,21 +95,21 @@ Linux 多用户并发开发时，`GENARRATIVE_DEV_PORT_RANGE` 或 `--port-range`
 node --check scripts/dev.mjs
 npm run test -- scripts/dev-stack-port-utils.test.ts
 npm run check:encoding
-node scripts/dev-stack-port-utils.mjs resolve-dev-stack spacetime:127.0.0.1:0 api:127.0.0.1:0 web:0.0.0.0:0 adminWeb:127.0.0.1:0
+node scripts/dev-stack-port-utils.mjs resolve-dev-stack spacetime:127.0.0.1:0 api:127.0.0.1:0 web:0.0.0.0:0 adminWeb:127.0.0.1:0 bgfilterWorker:127.0.0.1:0
 ```

 端口冲突回归测试建议：

 1. 用测试或临时 Node server 占用某个优先端口。
 2. 调用 `findAvailablePort`，断言结果大于被占用端口。
-3. 调用 `resolveDevStackPorts`，断言四个结果互不相同。
+3. 调用 `resolveDevStackPorts`，断言五个结果互不相同。
 4. 如果实际启动完整栈，观察控制台：
   - `[dev:ports] ... 不可用，改用 ...`
   - `[dev] api-server: http://...:<actual-api-port>`
   - `[dev] spacetime: http://...:<actual-spacetime-port>`
   - 主站和后台 Vite 启动端口与日志一致。

-完整启动属于长驻进程。需要 smoke 时用 background 方式启动，并另开命令检查 `/healthz`、`/v1/ping` 和页面端口；不要等待 `npm run dev` 自然退出。
+完整启动属于长驻进程。需要 smoke 时用 background 方式启动，并另开命令检查 api-server `/healthz`、BgFilter worker `/readyz`、SpacetimeDB `/v1/ping` 和两个页面端口；不要等待 `npm run dev` 自然退出。检查地址必须取 `.app/dev-stack.json` 或启动日志中的实际端口，不能假定 worker 一定停在 `8083`。

 ## 常见坑

@@ -122,7 +126,8 @@ node scripts/dev-stack-port-utils.mjs resolve-dev-stack spacetime:127.0.0.1:0 ap
 - [ ] Linux 注册表分配、同用户复用固定段并继续漂移、自动分配从 `10000-10099` 起、Windows bypass 都有测试覆盖。
 - [ ] `scripts/dev.mjs` 通过 `node --check`。
 - [ ] `npm run dev` 的 SpacetimeDB、publish、api-server、主站 Vite、后台 Vite 都使用实际端口。
+- [ ] BgFilter worker 在 api-server 前 ready，父子共享实际 base URL / Token，Rust watch 只触发一次组合重启。
 - [ ] `npm run dev:web` 在主站端口不可用时能切换到可用端口。
- [ ] 文档同步更新 `docs/technical/RUST_LOCAL_AND_REMOTE_DEPLOYMENT_SCRIPTS_2026-04-22.md`。
+- [ ] 文档同步更新 `docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。
 - [ ] 长期踩坑同步更新 `docs/project-memory/shared-memory/pitfalls.md`。
 - [ ] 修改中文文件后运行 `npm run check:encoding`。
@@ -44,10 +44,10 @@ npm run dev

 补充说明：

- `npm run dev` 会启动 SpacetimeDB standalone、Rust `api-server`、主站 Vite 与后台 Vite，适合完整联调。
+- `npm run dev` 会启动 SpacetimeDB standalone、独立 `bgfilter-worker`、Rust `api-server`、主站 Vite 与后台 Vite，适合完整联调；内部 worker ready 后才启动 API。
 - 主站默认地址是 `http://127.0.0.1:3000`，后台可从 `http://127.0.0.1:3000/admin/` 进入，也可直连 `http://127.0.0.1:3102`。
- 四个模块可独立启动：`npm run dev:spacetime`、`npm run dev:api-server`、`npm run dev:web`、`npm run dev:admin-web`。
- 如需自动刷新后端模块，使用 `npm run dev -- --watch`；其中 `spacetime-module` 改动后只会重新发布模块，不会重启 standalone，`api-server` 改动后会重启 Rust 进程。主站和后台前端源码变化交给 Vite 自身 HMR，不由外层 watcher 重启。非 watch 模式下可在 `npm run dev` 终端输入 `rs api-server`、`rs web`、`rs admin-web`、`rs spacetime` 或 `rs all`，其中 `rs spacetime` 也是只重新发布模块。
+- 五个模块可独立启动：`npm run dev:spacetime`、`npm run dev:api-server`、`npm run dev:bgfilter-worker`、`npm run dev:web`、`npm run dev:admin-web`；其中 `dev:api-server` 会安全带起同 runner 的 BgFilter worker 依赖。
+- 如需自动刷新后端模块，使用 `npm run dev -- --watch`；其中 `spacetime-module` 改动后只会重新发布模块，不会重启 standalone，Rust 源码改动会把 `api-server` 与 `bgfilter-worker` 作为一个组合单元重启。主站和后台前端源码变化交给 Vite 自身 HMR，不由外层 watcher 重启。非 watch 模式下可在 `npm run dev` 终端输入 `rs api-server`、`rs bgfilter-worker`、`rs web`、`rs admin-web`、`rs spacetime` 或 `rs all`，其中 `rs spacetime` 也是只重新发布模块。

 构建生产包：

@@ -3,10 +3,13 @@ import { afterEach, expect, test, vi } from 'vitest';
 import {
  createAdminAccount,
  executeAdminRechargeRefund,
+  getAdminFeatureGateConfig,
  getAdminUserDetail,
  listAdminRechargeOrders,
  resolveAdminRechargeRefundManualReview,
  updateAdminAccount,
+  uploadAdminEditorShowcaseCampaignImage,
+  upsertAdminFeatureGateConfig,
 } from './adminApiClient';

 afterEach(() => {
@@ -16,7 +19,7 @@ afterEach(() => {
 test('后台账号创建和更新携带 owner 会话与 Tab 权限', async () => {
  const fetchMock = vi.fn().mockImplementation(() =>
    Promise.resolve(
-      new Response(JSON.stringify({account: {accountId: 'member-1'}}), {
+      new Response(JSON.stringify({ account: { accountId: 'member-1' } }), {
        status: 200,
      }),
    ),
@@ -40,7 +43,7 @@ test('后台账号创建和更新携带 owner 会话与 Tab 权限', async () =>
  expect(fetchMock.mock.calls[0]?.[1]).toEqual(
    expect.objectContaining({
      method: 'POST',
-      headers: expect.objectContaining({Authorization: 'Bearer owner-token'}),
+      headers: expect.objectContaining({ Authorization: 'Bearer owner-token' }),
    }),
  );
  expect(fetchMock.mock.calls[1]?.[0]).toBe('/admin/api/accounts/member%2F1');
@@ -56,6 +59,132 @@ test('后台账号创建和更新携带 owner 会话与 Tab 权限', async () =>
  );
 });

+test('灰度配置读写只使用通用 feature-gates 管理接口', async () => {
+  const fetchMock = vi.fn().mockImplementation(() =>
+    Promise.resolve(
+      new Response(JSON.stringify({ gates: [] }), {
+        status: 200,
+        headers: { 'content-type': 'application/json' },
+      }),
+    ),
+  );
+  vi.stubGlobal('fetch', fetchMock);
+
+  await getAdminFeatureGateConfig('gray-token');
+  await upsertAdminFeatureGateConfig('gray-token', {
+    gateKey: 'image-editor:agent-sidebar',
+    enabled: true,
+    rolloutPercent: 25,
+    allowUserIds: ['user-1'],
+    allowUserTags: ['beta'],
+    denyUserIds: ['blocked-1'],
+    description: '画布 Agent 入口灰度',
+  });
+
+  expect(fetchMock.mock.calls[0]?.[0]).toBe('/admin/api/feature-gates');
+  expect(fetchMock.mock.calls[0]?.[1]).toEqual(
+    expect.objectContaining({
+      headers: expect.objectContaining({ Authorization: 'Bearer gray-token' }),
+    }),
+  );
+  expect(fetchMock.mock.calls[1]?.[0]).toBe('/admin/api/feature-gates');
+  expect(fetchMock.mock.calls[1]?.[1]).toEqual(
+    expect.objectContaining({
+      method: 'PUT',
+      headers: expect.objectContaining({ Authorization: 'Bearer gray-token' }),
+      body: JSON.stringify({
+        gateKey: 'image-editor:agent-sidebar',
+        enabled: true,
+        rolloutPercent: 25,
+        allowUserIds: ['user-1'],
+        allowUserTags: ['beta'],
+        denyUserIds: ['blocked-1'],
+        description: '画布 Agent 入口灰度',
+      }),
+    }),
+  );
+});
+
+test('活动卡图片上传成功后先确认正式私有对象再返回图片引用', async () => {
+  const closeBitmap = vi.fn();
+  vi.stubGlobal(
+    'createImageBitmap',
+    vi
+      .fn()
+      .mockResolvedValue({ width: 1024, height: 1536, close: closeBitmap }),
+  );
+  const fetchMock = vi
+    .fn()
+    .mockResolvedValueOnce(
+      new Response(
+        JSON.stringify({
+          upload: {
+            bucket: 'genarrative-release',
+            host: 'https://genarrative-release.oss.example.com',
+            objectKey:
+              'generated-character-drafts/editor/showcase-campaign/current/card.png',
+            legacyPublicPath:
+              '/generated-character-drafts/editor/showcase-campaign/current/card.png',
+            contentType: 'image/png',
+            formFields: { key: 'campaign-key', policy: 'signed-policy' },
+          },
+        }),
+        { status: 200, headers: { 'content-type': 'application/json' } },
+      ),
+    )
+    .mockResolvedValueOnce(new Response('', { status: 200 }))
+    .mockResolvedValueOnce(
+      new Response(
+        JSON.stringify({ assetObject: { assetObjectId: 'assetobj-1' } }),
+        {
+          status: 200,
+          headers: { 'content-type': 'application/json' },
+        },
+      ),
+    );
+  vi.stubGlobal('fetch', fetchMock);
+  const file = new File(['image-bytes'], 'card.png', { type: 'image/png' });
+
+  const uploaded = await uploadAdminEditorShowcaseCampaignImage(
+    'admin-token',
+    file,
+  );
+
+  expect(fetchMock.mock.calls[0]?.[0]).toBe(
+    '/admin/api/editor-showcase/campaign/image-upload-ticket',
+  );
+  expect(fetchMock.mock.calls[1]?.[0]).toBe(
+    'https://genarrative-release.oss.example.com',
+  );
+  expect(fetchMock.mock.calls[2]?.[0]).toBe(
+    '/admin/api/editor-showcase/campaign/image-upload-confirm',
+  );
+  expect(fetchMock.mock.calls[2]?.[1]).toEqual(
+    expect.objectContaining({
+      method: 'POST',
+      headers: expect.objectContaining({ Authorization: 'Bearer admin-token' }),
+      body: JSON.stringify({
+        bucket: 'genarrative-release',
+        objectKey:
+          'generated-character-drafts/editor/showcase-campaign/current/card.png',
+        contentType: 'image/png',
+        contentLength: file.size,
+      }),
+    }),
+  );
+  expect(uploaded).toEqual({
+    imageSrc:
+      '/generated-character-drafts/editor/showcase-campaign/current/card.png',
+    imageObjectKey:
+      'generated-character-drafts/editor/showcase-campaign/current/card.png',
+    imageWidth: 1024,
+    imageHeight: 1536,
+    legacyPublicPath:
+      '/generated-character-drafts/editor/showcase-campaign/current/card.png',
+  });
+  expect(closeBitmap).toHaveBeenCalledOnce();
+});
+
 test('充值订单查询按后台契约序列化筛选参数', async () => {
  const fetchMock = vi.fn().mockResolvedValue(
    new Response(JSON.stringify({ entries: [] }), {
@@ -110,13 +239,11 @@ test('用户详情只发送实际提供的用户定位字段', async () => {
 });

 test('退款执行使用独立 execute 管理员路由', async () => {
-  const fetchMock = vi
-    .fn()
-    .mockResolvedValue(
-      new Response(JSON.stringify({ outRefundNo: 'refund-1' }), {
-        status: 200,
-      }),
-    );
+  const fetchMock = vi.fn().mockResolvedValue(
+    new Response(JSON.stringify({ outRefundNo: 'refund-1' }), {
+      status: 200,
+    }),
+  );
  vi.stubGlobal('fetch', fetchMock);

  await executeAdminRechargeRefund('token-1', {
@@ -143,13 +270,11 @@ test('退款执行使用独立 execute 管理员路由', async () => {
 });

 test('退款人工复核使用独立 resolve 管理员路由', async () => {
-  const fetchMock = vi
-    .fn()
-    .mockResolvedValue(
-      new Response(JSON.stringify({ outRefundNo: 'refund-1' }), {
-        status: 200,
-      }),
-    );
+  const fetchMock = vi.fn().mockResolvedValue(
+    new Response(JSON.stringify({ outRefundNo: 'refund-1' }), {
+      status: 200,
+    }),
+  );
  vi.stubGlobal('fetch', fetchMock);

  await resolveAdminRechargeRefundManualReview('token-1', {
@@ -1,5 +1,6 @@
 import type {
  AdminAccountListResponse,
+  AdminConfirmEditorShowcaseCampaignImageUploadRequest,
  AdminCreateAccountRequest,
  AdminCreateAccountResponse,
  AdminCreateEditorShowcaseCampaignImageUploadTicketRequest,
@@ -22,6 +23,7 @@ import type {
  AdminEditorShowcaseListQuery,
  AdminEditorShowcaseListResponse,
  AdminEditorShowcaseReviewRequest,
+  AdminFeatureGateConfigResponse,
  AdminLoginResponse,
  AdminMeResponse,
  AdminOverviewResponse,
@@ -40,6 +42,7 @@ import type {
  AdminUpdateAccountResponse,
  AdminUploadedEditorShowcaseCampaignImage,
  AdminUpsertEditorShowcaseCampaignRequest,
+  AdminUpsertFeatureGateConfigRequest,
  AdminUpsertProfileInviteCodeRequest,
  AdminUpsertProfileRechargeProductRequest,
  AdminUpsertProfileRedeemCodeRequest,
@@ -266,6 +269,23 @@ export function listAdminTrackingEventKeys(token: string) {
  );
 }

+export function getAdminFeatureGateConfig(token: string) {
+  return request<AdminFeatureGateConfigResponse>('/admin/api/feature-gates', {
+    token,
+  });
+}
+
+export function upsertAdminFeatureGateConfig(
+  token: string,
+  payload: AdminUpsertFeatureGateConfigRequest,
+) {
+  return request<AdminFeatureGateConfigResponse>('/admin/api/feature-gates', {
+    method: 'PUT',
+    token,
+    body: payload,
+  });
+}
+
 export function getAdminEditorGenerationPricing(token: string) {
  return request<EditorGenerationPricingConfigPayload>(
    '/admin/api/editor-generation-pricing',
@@ -388,6 +408,19 @@ export async function uploadAdminEditorShowcaseCampaignImage(
    );
  await postAdminDirectUploadFile(response.upload, file);
  const objectKey = response.upload.objectKey.trim().replace(/^\/+/u, '');
+  await request<unknown>(
+    '/admin/api/editor-showcase/campaign/image-upload-confirm',
+    {
+      method: 'POST',
+      token,
+      body: {
+        bucket: response.upload.bucket,
+        objectKey,
+        contentType,
+        contentLength: file.size,
+      } satisfies AdminConfirmEditorShowcaseCampaignImageUploadRequest,
+    },
+  );
  return {
    imageSrc: objectKey ? `/${objectKey}` : response.upload.legacyPublicPath,
    imageObjectKey: objectKey,
@@ -286,6 +286,26 @@ export interface AdminTrackingEventListQuery {
  exportAll?: boolean;
 }

+export interface AdminFeatureGateConfigPayload {
+  gateKey: string;
+  enabled: boolean;
+  rolloutPercent: number;
+  allowUserIds: string[];
+  allowUserTags: string[];
+  denyUserIds: string[];
+  description: string;
+  updatedAt: string;
+}
+
+export interface AdminFeatureGateConfigResponse {
+  gates: AdminFeatureGateConfigPayload[];
+}
+
+export type AdminUpsertFeatureGateConfigRequest = Omit<
+  AdminFeatureGateConfigPayload,
+  'updatedAt'
+>;
+
 /** 图片画布生成模型泥点定价配置。 */
 export type EditorGenerationPricingUnitPayload = 'perGeneration' | 'perSecond';

@@ -372,6 +392,7 @@ export interface AdminEditorShowcaseAssetPayload {
  taskId?: string | null;
  assetKind?: string | null;
  generationInputs?: Record<string, unknown> | null;
+  thumbnailSrc?: string | null;
  generationCostMudPoints: number;
  refundMudPoints: number;
  reviewStatus: 'pending' | 'approved' | 'rejected' | string;
@@ -459,6 +480,13 @@ export interface AdminCreateEditorShowcaseCampaignImageUploadTicketResponse {
  upload: AdminDirectUploadTicketPayload;
 }

+export interface AdminConfirmEditorShowcaseCampaignImageUploadRequest {
+  bucket: string;
+  objectKey: string;
+  contentType: string;
+  contentLength: number;
+}
+
 export interface AdminUploadedEditorShowcaseCampaignImage {
  imageSrc: string;
  imageObjectKey: string;
@@ -24,6 +24,7 @@ import { AdminDebugHttpPage } from '../pages/AdminDebugHttpPage';
 import { AdminEditorAssetQueryPage } from '../pages/AdminEditorAssetQueryPage';
 import { AdminEditorGenerationPricingPage } from '../pages/AdminEditorGenerationPricingPage';
 import { AdminEditorShowcaseReviewPage } from '../pages/AdminEditorShowcaseReviewPage';
+import { AdminGrayReleaseConfigPage } from '../pages/AdminGrayReleaseConfigPage';
 import { AdminInviteCodePage } from '../pages/AdminInviteCodePage';
 import { AdminLoginPage } from '../pages/AdminLoginPage';
 import { AdminOverviewPage } from '../pages/AdminOverviewPage';
@@ -227,6 +228,12 @@ export function AdminApp() {
          onUnauthorized={handleUnauthorized}
        />
      ) : null}
+      {activeRouteId === 'gray-release' ? (
+        <AdminGrayReleaseConfigPage
+          token={token}
+          onUnauthorized={handleUnauthorized}
+        />
+      ) : null}
      {activeRouteId === 'redeem' ? (
        <AdminRedeemCodePage
          token={token}
@@ -4,6 +4,7 @@ import {
  Bug,
  Coins,
  Database,
+  GitBranch,
  Images,
  LayoutDashboard,
  ListChecks,
@@ -37,6 +38,7 @@ const routeIcons = {
  tables: Database,
  debug: Bug,
  tracking: Table2,
+  'gray-release': GitBranch,
  redeem: TicketPercent,
  invite: TicketCheck,
  'profile-wallet': WalletCards,
@@ -33,12 +33,22 @@ test('后台模型定价路由可通过导航和 hash 访问', () => {
  );
 });

+test('后台灰度发布路由可通过导航和 hash 访问', () => {
+  expect(adminRoutes).toContainEqual({
+    id: 'gray-release',
+    label: '灰度发布',
+    hash: '#gray-release',
+  });
+  expect(resolveAdminRoute('#gray-release')).toBe('gray-release');
+  expect(routeHash('gray-release')).toBe('#gray-release');
+});
+
 test('后台不再暴露旧创作模板管理路由', () => {
  expect(resolveAdminRoute('#creation-entry')).toBe('dashboard');
  expect(resolveAdminRoute('#creation-announcement')).toBe('dashboard');
-  expect(resolveAdminRoute('#gray-release')).toBe('dashboard');
  expect(resolveAdminRoute('#work-visibility')).toBe('dashboard');
 });
+
 test('后台素材查询路由可通过导航和 hash 访问', () => {
  expect(adminRoutes).toContainEqual({
    id: 'editor-assets',
@@ -93,6 +103,17 @@ test('member 只访问已分配 Tab 且无权 hash 回落到第一项', () => {
  );
 });

+test('member 可单独获得灰度发布 Tab 权限', () => {
+  const routes = getAccessibleAdminRoutes({
+    accountRole: 'member',
+    tabPermissions: ['gray-release'],
+  });
+  expect(routes.map((route) => route.id)).toEqual(['gray-release']);
+  expect(resolveAccessibleAdminRoute('#gray-release', routes)).toBe(
+    'gray-release',
+  );
+});
+
 test('零权限 member 不回落到 Dashboard', () => {
  const routes = getAccessibleAdminRoutes({
    accountRole: 'member',
@@ -1,10 +1,11 @@
-/** 后台单页应用可导航的路由标识，入口公告独立于入口开关维护。 */
+/** 后台单页应用可导航的路由标识。 */
 export type AdminRouteId =
  | 'dashboard'
  | 'overview'
  | 'tables'
  | 'debug'
  | 'tracking'
+  | 'gray-release'
  | 'redeem'
  | 'invite'
  | 'profile-wallet'
@@ -32,6 +33,7 @@ export const adminRoutes: AdminRouteDefinition[] = [
  { id: 'tables', label: '表查询', hash: '#tables' },
  { id: 'debug', label: 'API 调试', hash: '#debug' },
  { id: 'tracking', label: '埋点数据', hash: '#tracking' },
+  { id: 'gray-release', label: '灰度发布', hash: '#gray-release' },
  { id: 'redeem', label: '兑换码', hash: '#redeem' },
  { id: 'invite', label: '邀请码', hash: '#invite' },
  { id: 'profile-wallet', label: '账号配置', hash: '#profile-wallet' },
@@ -0,0 +1,436 @@
+import { X } from 'lucide-react';
+import { useCallback, useEffect, useState } from 'react';
+
+import type { AdminAssetReadUrlResponse } from '../api/adminApiClient';
+import { getAdminAssetReadUrl, isAdminApiError } from '../api/adminApiClient';
+
+const ADMIN_ASSET_READ_EXPIRE_SECONDS = 300;
+const ADMIN_ASSET_READ_DISPATCH_SPACING_MS = 40;
+const ADMIN_ASSET_READ_RETRY_DELAYS_MS = [400, 1_200, 3_000] as const;
+const ADMIN_ASSET_THUMBNAIL_ROOT_MARGIN = '240px 0px';
+const AUDIO_ASSET_COVER_SRC = `${import.meta.env.DEV ? import.meta.env.BASE_URL : '/'}creation-home/audio-asset-cover.png`;
+let adminAssetReadDispatchTail = Promise.resolve();
+
+export interface AdminPreviewableEditorAsset {
+  assetId: string;
+  label: string;
+  imageSrc: string;
+  objectKey?: string | null;
+  assetKind?: string | null;
+  thumbnailSrc?: string | null;
+}
+
+export function AdminEditorAssetThumbnail({
+  entry,
+  token,
+  altPrefix = '素材',
+}: {
+  entry: AdminPreviewableEditorAsset;
+  token: string;
+  altPrefix?: string;
+}) {
+  const thumbnailSource = resolveAdminAssetThumbnailSource(entry);
+  const { observeElement, shouldLoad } = useAdminAssetThumbnailVisibility();
+  const imageSrc = useAdminResolvedAssetUrl(
+    token,
+    thumbnailSource.src,
+    thumbnailSource.objectKey,
+    shouldLoad,
+  );
+  const alt = `${altPrefix}：${entry.label || entry.assetId}`;
+
+  return imageSrc ? (
+    <img
+      ref={observeElement}
+      alt={alt}
+      className="admin-asset-query-thumb"
+      src={imageSrc}
+    />
+  ) : (
+    <div
+      ref={observeElement}
+      className="admin-asset-query-thumb admin-asset-query-thumb-placeholder"
+    />
+  );
+}
+
+export function AdminEditorAssetPreviewDialog({
+  entry,
+  token,
+  onClose,
+}: {
+  entry: AdminPreviewableEditorAsset;
+  token: string;
+  onClose: () => void;
+}) {
+  return (
+    <div className="admin-confirm-backdrop" role="presentation">
+      <section
+        aria-label="素材预览"
+        className="admin-detail-panel admin-asset-query-preview-dialog"
+        role="dialog"
+      >
+        <div className="admin-panel-heading">
+          <div>
+            <h3>{entry.label || entry.assetId}</h3>
+            <span>{entry.assetId}</span>
+          </div>
+          <button
+            aria-label="关闭素材预览"
+            className="admin-ghost-button"
+            type="button"
+            onClick={onClose}
+          >
+            <X size={17} aria-hidden="true" />
+          </button>
+        </div>
+        <AdminEditorAssetPreviewMedia entry={entry} token={token} />
+      </section>
+    </div>
+  );
+}
+
+function AdminEditorAssetPreviewMedia({
+  entry,
+  token,
+}: {
+  entry: AdminPreviewableEditorAsset;
+  token: string;
+}) {
+  const mediaKind = resolveAdminAssetMediaKind(entry);
+  const isAudio = mediaKind === 'audio';
+  const isVideo = mediaKind === 'video';
+  const mediaSrc = useAdminResolvedAssetUrl(
+    token,
+    entry.imageSrc,
+    entry.objectKey,
+  );
+  const posterSrc = useAdminResolvedAssetUrl(
+    token,
+    isVideo ? (entry.thumbnailSrc ?? '') : '',
+    null,
+  );
+  const label = entry.label || entry.assetId;
+
+  if (isAudio) {
+    return (
+      <div className="admin-asset-query-preview-audio">
+        <img
+          alt={`音频封面：${label}`}
+          className="admin-asset-query-preview-cover"
+          src={AUDIO_ASSET_COVER_SRC}
+        />
+        {mediaSrc ? (
+          <audio
+            aria-label={`音频预览：${label}`}
+            className="admin-asset-query-preview-player"
+            controls
+            preload="metadata"
+            src={mediaSrc}
+          />
+        ) : (
+          <div className="admin-asset-query-preview-placeholder" />
+        )}
+      </div>
+    );
+  }
+
+  if (isVideo) {
+    return mediaSrc ? (
+      <video
+        aria-label={`视频预览：${label}`}
+        className="admin-asset-query-preview-media"
+        controls
+        playsInline
+        poster={posterSrc || undefined}
+        preload="metadata"
+        src={mediaSrc}
+      />
+    ) : (
+      <div className="admin-asset-query-preview-placeholder" />
+    );
+  }
+
+  return mediaSrc ? (
+    <img
+      alt={`图片预览：${label}`}
+      className="admin-asset-query-preview-media"
+      src={mediaSrc}
+    />
+  ) : (
+    <div className="admin-asset-query-preview-placeholder" />
+  );
+}
+
+function resolveAdminAssetThumbnailSource(entry: AdminPreviewableEditorAsset) {
+  const mediaKind = resolveAdminAssetMediaKind(entry);
+  if (mediaKind === 'audio') {
+    return { src: AUDIO_ASSET_COVER_SRC, objectKey: null };
+  }
+  if (mediaKind === 'video') {
+    return { src: entry.thumbnailSrc || '', objectKey: null };
+  }
+  if (entry.thumbnailSrc?.trim()) {
+    return {
+      src: entry.thumbnailSrc,
+      objectKey: adminAssetPathsMatch(entry.thumbnailSrc, entry.imageSrc)
+        ? entry.objectKey
+        : null,
+    };
+  }
+  return {
+    src: entry.imageSrc,
+    objectKey: entry.objectKey,
+  };
+}
+
+function useAdminAssetThumbnailVisibility() {
+  const [element, setElement] = useState<HTMLElement | null>(null);
+  const [shouldLoad, setShouldLoad] = useState(false);
+  const observeElement = useCallback((nextElement: HTMLElement | null) => {
+    setElement(nextElement);
+  }, []);
+
+  useEffect(() => {
+    if (shouldLoad || !element) {
+      return;
+    }
+    if (typeof IntersectionObserver === 'undefined') {
+      setShouldLoad(true);
+      return;
+    }
+
+    const observer = new IntersectionObserver(
+      (entries) => {
+        if (entries.some((entry) => entry.isIntersecting)) {
+          setShouldLoad(true);
+          observer.disconnect();
+        }
+      },
+      { rootMargin: ADMIN_ASSET_THUMBNAIL_ROOT_MARGIN },
+    );
+    observer.observe(element);
+    return () => observer.disconnect();
+  }, [element, shouldLoad]);
+
+  return { observeElement, shouldLoad };
+}
+
+type AdminAssetMediaKind = 'image' | 'audio' | 'video';
+
+function resolveAdminAssetMediaKind(
+  entry: AdminPreviewableEditorAsset,
+): AdminAssetMediaKind {
+  const pathMediaKind =
+    resolveAdminAssetMediaKindFromPath(entry.imageSrc) ??
+    resolveAdminAssetMediaKindFromPath(entry.objectKey ?? '');
+  if (pathMediaKind) {
+    return pathMediaKind;
+  }
+
+  const assetKind = entry.assetKind?.trim() ?? '';
+  if (
+    assetKind === 'sound-effect' ||
+    assetKind === 'background-music' ||
+    assetKind === 'editor_uploaded_audio'
+  ) {
+    return 'audio';
+  }
+  if (
+    assetKind === 'video' ||
+    assetKind === 'editor_video' ||
+    assetKind === 'editor-video' ||
+    assetKind === 'editor_uploaded_video'
+  ) {
+    return 'video';
+  }
+  return 'image';
+}
+
+function resolveAdminAssetMediaKindFromPath(
+  value: string,
+): AdminAssetMediaKind | null {
+  const normalizedValue = value.trim();
+  if (/^data:image\//iu.test(normalizedValue)) {
+    return 'image';
+  }
+  if (/^data:audio\//iu.test(normalizedValue)) {
+    return 'audio';
+  }
+  if (/^data:video\//iu.test(normalizedValue)) {
+    return 'video';
+  }
+  if (
+    /\.(?:avif|bmp|gif|jpe?g|png|svg|webp)(?:$|[?#])/iu.test(normalizedValue)
+  ) {
+    return 'image';
+  }
+  if (/\.(?:aac|flac|m4a|mp3|ogg|opus|wav)(?:$|[?#])/iu.test(normalizedValue)) {
+    return 'audio';
+  }
+  if (/\.(?:m4v|mov|mp4|ogv|webm)(?:$|[?#])/iu.test(normalizedValue)) {
+    return 'video';
+  }
+  return null;
+}
+
+function useAdminResolvedAssetUrl(
+  token: string,
+  imageSrc: string | null | undefined,
+  objectKey: string | null | undefined,
+  enabled = true,
+) {
+  const normalizedImageSrc = imageSrc?.trim() ?? '';
+  const normalizedObjectKey = normalizeAdminObjectKey(objectKey);
+  const normalizedLegacyPublicPath = isGeneratedLegacyPath(normalizedImageSrc)
+    ? normalizedImageSrc
+    : resolveAdminGeneratedLegacyPathFromUrl(normalizedImageSrc);
+  const shouldResolve =
+    Boolean(normalizedObjectKey) || Boolean(normalizedLegacyPublicPath);
+  const [resolvedImageSrc, setResolvedImageSrc] = useState(
+    shouldResolve ? '' : normalizedImageSrc,
+  );
+
+  useEffect(() => {
+    if (!normalizedImageSrc && !normalizedObjectKey) {
+      setResolvedImageSrc('');
+      return;
+    }
+    if (!shouldResolve) {
+      setResolvedImageSrc(normalizedImageSrc);
+      return;
+    }
+    if (!enabled) {
+      setResolvedImageSrc('');
+      return;
+    }
+
+    let cancelled = false;
+    let retryTimer: ReturnType<typeof setTimeout> | null = null;
+    let retryIndex = 0;
+    const dispatchController = new AbortController();
+    setResolvedImageSrc('');
+
+    const resolveReadUrl = async () => {
+      try {
+        await waitForAdminAssetReadDispatch(dispatchController.signal);
+        if (cancelled) {
+          return;
+        }
+        const response = await getAdminAssetReadUrl(
+          token,
+          normalizedObjectKey
+            ? {
+                objectKey: normalizedObjectKey,
+                expireSeconds: ADMIN_ASSET_READ_EXPIRE_SECONDS,
+              }
+            : {
+                legacyPublicPath: normalizedLegacyPublicPath,
+                expireSeconds: ADMIN_ASSET_READ_EXPIRE_SECONDS,
+              },
+        );
+        if (!cancelled) {
+          setResolvedImageSrc(resolveAdminAssetReadSignedUrl(response));
+        }
+      } catch (error: unknown) {
+        if (cancelled) {
+          return;
+        }
+        const retryDelay = ADMIN_ASSET_READ_RETRY_DELAYS_MS[retryIndex];
+        if (
+          isAdminApiError(error) &&
+          error.status === 429 &&
+          typeof retryDelay === 'number'
+        ) {
+          retryIndex += 1;
+          retryTimer = setTimeout(() => void resolveReadUrl(), retryDelay);
+          return;
+        }
+        setResolvedImageSrc('');
+      }
+    };
+
+    void resolveReadUrl();
+
+    return () => {
+      cancelled = true;
+      dispatchController.abort();
+      if (retryTimer !== null) {
+        clearTimeout(retryTimer);
+      }
+    };
+  }, [
+    enabled,
+    normalizedImageSrc,
+    normalizedLegacyPublicPath,
+    normalizedObjectKey,
+    shouldResolve,
+    token,
+  ]);
+
+  return resolvedImageSrc;
+}
+
+async function waitForAdminAssetReadDispatch(signal: AbortSignal) {
+  const dispatch = adminAssetReadDispatchTail.then(
+    () => waitForAdminAssetReadDispatchSpacing(signal),
+    () => waitForAdminAssetReadDispatchSpacing(signal),
+  );
+  adminAssetReadDispatchTail = dispatch.catch(() => undefined);
+  await dispatch;
+}
+
+async function waitForAdminAssetReadDispatchSpacing(signal: AbortSignal) {
+  if (signal.aborted) {
+    throw new DOMException('The operation was aborted.', 'AbortError');
+  }
+  await new Promise<void>((resolve, reject) => {
+    const timer = setTimeout(() => {
+      signal.removeEventListener('abort', handleAbort);
+      resolve();
+    }, ADMIN_ASSET_READ_DISPATCH_SPACING_MS);
+
+    function handleAbort() {
+      clearTimeout(timer);
+      reject(new DOMException('The operation was aborted.', 'AbortError'));
+    }
+
+    signal.addEventListener('abort', handleAbort, { once: true });
+  });
+}
+
+function normalizeAdminObjectKey(value: string | null | undefined) {
+  return value?.trim().replace(/^\/+/u, '') ?? '';
+}
+
+function adminAssetPathsMatch(left: string, right: string) {
+  return (
+    left.trim().replace(/^\/+|[?#].*$/gu, '') ===
+    right.trim().replace(/^\/+|[?#].*$/gu, '')
+  );
+}
+
+function isGeneratedLegacyPath(value: string) {
+  return /^\/?generated-[^/?#]+\/.+/u.test(value.trim());
+}
+
+function resolveAdminGeneratedLegacyPathFromUrl(value: string) {
+  try {
+    const parsedUrl = new URL(value);
+    if (
+      parsedUrl.protocol !== 'https:' ||
+      !/^[^.]+\.oss-[^.]+\.aliyuncs\.com$/iu.test(parsedUrl.hostname)
+    ) {
+      return '';
+    }
+    const legacyPublicPath = decodeURIComponent(parsedUrl.pathname);
+    return isGeneratedLegacyPath(legacyPublicPath) ? legacyPublicPath : '';
+  } catch {
+    return '';
+  }
+}
+
+function resolveAdminAssetReadSignedUrl(response: AdminAssetReadUrlResponse) {
+  const read = response.read ?? response;
+  return typeof read.signedUrl === 'string' ? read.signedUrl.trim() : '';
+}
@@ -1,13 +1,14 @@
 /* @vitest-environment jsdom */

 import {
+  act,
  fireEvent,
  render,
  screen,
  waitFor,
  within,
 } from '@testing-library/react';
-import { beforeEach, expect, test, vi } from 'vitest';
+import { afterEach, beforeEach, expect, test, vi } from 'vitest';

 import {
  getAdminAssetReadUrl,
@@ -23,6 +24,13 @@ import { AdminEditorShowcaseReviewPage } from './AdminEditorShowcaseReviewPage';

 vi.mock('../api/adminApiClient', () => ({
  getAdminAssetReadUrl: vi.fn(),
+  isAdminApiError: vi.fn(
+    (error: unknown) =>
+      typeof error === 'object' &&
+      error !== null &&
+      'status' in error &&
+      typeof error.status === 'number',
+  ),
  getAdminEditorShowcaseCampaign: vi.fn(),
  listAdminEditorShowcaseAssets: vi.fn(),
  reviewAdminEditorShowcaseAsset: vi.fn(),
@@ -31,8 +39,87 @@ vi.mock('../api/adminApiClient', () => ({
  upsertAdminEditorShowcaseCampaign: vi.fn(),
 }));

+interface MockIntersectionObserverController {
+  enter: (target: Element) => void;
+  isObserved: (target: Element) => boolean;
+}
+
+function installIntersectionObserverMock(): MockIntersectionObserverController {
+  const observed = new Map<
+    Element,
+    {
+      callback: IntersectionObserverCallback;
+      observer: IntersectionObserver;
+    }
+  >();
+
+  class MockIntersectionObserver implements IntersectionObserver {
+    readonly root = null;
+    readonly rootMargin: string;
+    readonly thresholds = [0];
+    private readonly targets = new Set<Element>();
+
+    constructor(
+      private readonly callback: IntersectionObserverCallback,
+      options: IntersectionObserverInit = {},
+    ) {
+      this.rootMargin = options.rootMargin ?? '0px';
+    }
+
+    observe(target: Element) {
+      this.targets.add(target);
+      observed.set(target, {
+        callback: this.callback,
+        observer: this as unknown as IntersectionObserver,
+      });
+    }
+
+    unobserve(target: Element) {
+      this.targets.delete(target);
+      observed.delete(target);
+    }
+
+    disconnect() {
+      this.targets.forEach((target) => observed.delete(target));
+      this.targets.clear();
+    }
+
+    takeRecords() {
+      return [];
+    }
+  }
+
+  vi.stubGlobal('IntersectionObserver', MockIntersectionObserver);
+
+  return {
+    enter(target) {
+      const record = observed.get(target);
+      if (!record) {
+        throw new Error('目标精选缩略图尚未进入 IntersectionObserver');
+      }
+      act(() => {
+        record.callback(
+          [
+            {
+              isIntersecting: true,
+              target,
+            } as IntersectionObserverEntry,
+          ],
+          record.observer,
+        );
+      });
+    },
+    isObserved(target) {
+      return observed.has(target);
+    },
+  };
+}
+
 vi.mock('../components/AdminUserReferenceButton', () => ({
-  AdminUserReferenceButton: ({ userId, publicUserCode }: {
+  AdminUserReferenceButton: ({
+    userId,
+    publicUserCode,
+  }: {
    userId?: string;
    publicUserCode?: string | null;
  }) => (
@@ -160,6 +247,10 @@ beforeEach(() => {
  });
 });

+afterEach(() => {
+  vi.unstubAllGlobals();
+});
+
 test('后台精选审核展示待审核素材和活动卡配置', async () => {
  render(
    <AdminEditorShowcaseReviewPage
@@ -184,10 +275,114 @@ test('后台精选审核展示待审核素材和活动卡配置', async () => {
    submittedBefore: null,
    limit: 80,
  });
+  await waitFor(() => {
+    expect(getAdminAssetReadUrl).toHaveBeenCalledWith('admin-token', {
+      objectKey: 'generated-character-drafts/editor/spec.png',
+      expireSeconds: 300,
+    });
+  });
+});
+
+test('后台精选审核缩略图进入视口后换签并可打开图片预览', async () => {
+  const observer = installIntersectionObserverMock();
+  render(
+    <AdminEditorShowcaseReviewPage
+      token="admin-token"
+      onUnauthorized={vi.fn()}
+    />,
+  );
+
+  expect(await screen.findByText('角色形象 1')).toBeTruthy();
+  const previewButton = screen.getByTitle('预览素材');
+  const thumbnail = previewButton.querySelector('.admin-asset-query-thumb');
+  expect(thumbnail).not.toBeNull();
+  await waitFor(() => expect(observer.isObserved(thumbnail!)).toBe(true));
+  expect(getAdminAssetReadUrl).not.toHaveBeenCalled();
+
+  observer.enter(thumbnail!);
+  const image = await screen.findByRole('img', {
+    name: '精选素材：角色形象 1',
+  });
+  expect(image.getAttribute('src')).toBe('https://signed.example.com/spec.png');
+
+  fireEvent.click(previewButton);
+  const dialog = await screen.findByRole('dialog', { name: '素材预览' });
+  const previewImage = await within(dialog).findByRole('img', {
+    name: '图片预览：角色形象 1',
+  });
+  await waitFor(() => {
+    expect(previewImage.getAttribute('src')).toBe(
+      'https://signed.example.com/spec.png',
+    );
+  });
+  expect(screen.queryByRole('dialog', { name: '精选素材详情' })).toBeNull();
+});
+
+test('后台精选审核将无 objectKey 的绝对 OSS 图片地址换签后预览', async () => {
+  vi.mocked(listAdminEditorShowcaseAssets).mockResolvedValueOnce({
+    entries: [
+      {
+        ...pendingShowcaseAsset,
+        imageSrc:
+          'https://genarrative.oss-cn-shanghai.aliyuncs.com/generated-character-drafts/editor/absolute.png?x-oss-process=image/resize,w_320',
+        objectKey: null,
+      },
+    ],
+    nextCursor: null,
+  });
+  vi.mocked(getAdminAssetReadUrl).mockResolvedValue({
+    read: {
+      objectKey: 'generated-character-drafts/editor/absolute.png',
+      signedUrl: 'https://signed.example.com/absolute.png',
+      expiresAt: '2026-07-04T11:00:00Z',
+    },
+  });
+
+  render(
+    <AdminEditorShowcaseReviewPage
+      token="admin-token"
+      onUnauthorized={vi.fn()}
+    />,
+  );
+
+  const image = await screen.findByRole('img', {
+    name: '精选素材：角色形象 1',
+  });
+  expect(image.getAttribute('src')).toBe(
+    'https://signed.example.com/absolute.png',
+  );
  expect(getAdminAssetReadUrl).toHaveBeenCalledWith('admin-token', {
-    objectKey: 'generated-character-drafts/editor/spec.png',
+    legacyPublicPath: '/generated-character-drafts/editor/absolute.png',
    expireSeconds: 300,
  });
+
+  fireEvent.click(screen.getByTitle('预览素材'));
+  const dialog = await screen.findByRole('dialog', { name: '素材预览' });
+  expect(
+    await within(dialog).findByRole('img', {
+      name: '图片预览：角色形象 1',
+    }),
+  ).toHaveProperty('src', 'https://signed.example.com/absolute.png');
+});
+
+test('后台精选审核详情中的缩略图也可打开素材预览', async () => {
+  render(
+    <AdminEditorShowcaseReviewPage
+      token="admin-token"
+      onUnauthorized={vi.fn()}
+    />,
+  );
+
+  fireEvent.click(await screen.findByRole('button', { name: '详情' }));
+  const detail = await screen.findByRole('dialog', { name: '精选素材详情' });
+  fireEvent.click(within(detail).getByTitle('预览素材'));
+
+  const preview = await screen.findByRole('dialog', { name: '素材预览' });
+  expect(
+    await within(preview).findByRole('img', {
+      name: '图片预览：角色形象 1',
+    }),
+  ).toBeTruthy();
 });

 test('后台精选审核格式化微秒时间并显示素材名', async () => {
@@ -2,9 +2,7 @@ import { Eye, FileText, RefreshCcw, Upload, X } from 'lucide-react';
 import type { ReactNode } from 'react';
 import { useEffect, useRef, useState } from 'react';

-import type { AdminAssetReadUrlResponse } from '../api/adminApiClient';
 import {
-  getAdminAssetReadUrl,
  getAdminEditorShowcaseCampaign,
  listAdminEditorShowcaseAssets,
  reviewAdminEditorShowcaseAsset,
@@ -17,6 +15,10 @@ import type {
  AdminEditorShowcaseCampaignPayload,
  AdminEditorShowcaseListQuery,
 } from '../api/adminApiTypes';
+import {
+  AdminEditorAssetPreviewDialog,
+  AdminEditorAssetThumbnail,
+} from '../components/AdminEditorAssetMedia';
 import { AdminUserReferenceButton } from '../components/AdminUserReferenceButton';
 import { handlePageError } from './pageUtils';

@@ -25,9 +27,6 @@ interface AdminEditorShowcaseReviewPageProps {
  onUnauthorized: (message?: string) => void;
 }

-const ADMIN_SHOWCASE_READ_EXPIRE_SECONDS = 300;
-const AUDIO_ASSET_COVER_SRC = `${import.meta.env.DEV ? import.meta.env.BASE_URL : '/'}creation-home/audio-asset-cover.png`;
-
 const showcaseCategoryOptions = [
  { value: 'characters', label: '角色' },
  { value: 'ui', label: 'UI' },
@@ -58,6 +57,8 @@ export function AdminEditorShowcaseReviewPage({
  const [reviewNotes, setReviewNotes] = useState<Record<string, string>>({});
  const [detailEntry, setDetailEntry] =
    useState<AdminEditorShowcaseAssetPayload | null>(null);
+  const [previewEntry, setPreviewEntry] =
+    useState<AdminEditorShowcaseAssetPayload | null>(null);
  const [promptPreview, setPromptPreview] = useState<{
    title: string;
    prompt: string;
@@ -342,11 +343,15 @@ export function AdminEditorShowcaseReviewPage({
                    <td>
                      <button
                        className="admin-asset-query-thumb-button"
-                        title="查看详情"
+                        title="预览素材"
                        type="button"
-                        onClick={() => setDetailEntry(entry)}
+                        onClick={() => setPreviewEntry(entry)}
                      >
-                        <AdminShowcaseThumbnail entry={entry} token={token} />
+                        <AdminEditorAssetThumbnail
+                          entry={entry}
+                          token={token}
+                          altPrefix="精选素材"
+                        />
                      </button>
                      <small>{entry.label || '-'}</small>
                    </td>
@@ -355,7 +360,9 @@ export function AdminEditorShowcaseReviewPage({
                      <div className="admin-inline-identity">
                        <div>
                          {authorDisplayName(entry)}
-                          <small>{entry.authorPublicUserCode?.trim() || '-'}</small>
+                          <small>
+                            {entry.authorPublicUserCode?.trim() || '-'}
+                          </small>
                        </div>
                        <AdminUserReferenceButton
                          token={token}
@@ -611,6 +618,7 @@ export function AdminEditorShowcaseReviewPage({
          token={token}
          onUnauthorized={onUnauthorized}
          onClose={() => setDetailEntry(null)}
+          onPreview={(entry) => setPreviewEntry(entry)}
          onPromptPreview={(entry, prompt) =>
            setPromptPreview({
              title: entry.label || entry.showcaseId,
@@ -620,6 +628,14 @@ export function AdminEditorShowcaseReviewPage({
        />
      ) : null}

+      {previewEntry ? (
+        <AdminEditorAssetPreviewDialog
+          entry={previewEntry}
+          token={token}
+          onClose={() => setPreviewEntry(null)}
+        />
+      ) : null}
+
      {promptPreview ? (
        <div className="admin-confirm-backdrop" role="presentation">
          <section
@@ -652,48 +668,18 @@ export function AdminEditorShowcaseReviewPage({
  );
 }

-function AdminShowcaseThumbnail({
-  entry,
-  token,
-}: {
-  entry: AdminEditorShowcaseAssetPayload;
-  token: string;
-}) {
-  const isAudio = isAdminShowcaseAudioAsset(entry);
-  const imageSrc = useAdminResolvedAssetImageSrc(
-    token,
-    isAudio ? AUDIO_ASSET_COVER_SRC : entry.imageSrc,
-    isAudio ? null : entry.objectKey,
-  );
-  const alt = `精选素材：${entry.label || entry.showcaseId}`;
-
-  return imageSrc ? (
-    <img alt={alt} className="admin-asset-query-thumb" src={imageSrc} />
-  ) : (
-    <div className="admin-asset-query-thumb admin-asset-query-thumb-placeholder" />
-  );
-}
-
-function isAdminShowcaseAudioAsset(entry: AdminEditorShowcaseAssetPayload) {
-  const assetKind = entry.assetKind?.trim() ?? '';
-  return (
-    assetKind === 'sound-effect' ||
-    assetKind === 'background-music' ||
-    assetKind === 'editor_uploaded_audio' ||
-    /\.(?:mp3|wav|m4a|aac|ogg)(?:$|[?#])/iu.test(entry.imageSrc.trim())
-  );
-}
-
 function AdminShowcaseDetailDialog({
  entry,
  token,
  onClose,
+  onPreview,
  onPromptPreview,
  onUnauthorized,
 }: {
  entry: AdminEditorShowcaseAssetPayload;
  token: string;
  onClose: () => void;
+  onPreview: (entry: AdminEditorShowcaseAssetPayload) => void;
  onUnauthorized: (message?: string) => void;
  onPromptPreview: (
    entry: AdminEditorShowcaseAssetPayload,
@@ -723,7 +709,18 @@ function AdminShowcaseDetailDialog({
          </button>
        </div>
        <div className="admin-asset-query-detail-layout">
-          <AdminShowcaseThumbnail entry={entry} token={token} />
+          <button
+            className="admin-asset-query-thumb-button admin-asset-query-detail-thumb-button"
+            title="预览素材"
+            type="button"
+            onClick={() => onPreview(entry)}
+          >
+            <AdminEditorAssetThumbnail
+              entry={entry}
+              token={token}
+              altPrefix="精选素材"
+            />
+          </button>
          <dl className="admin-info-list admin-detail-list">
            <AdminInfoItem label="作者">
              <div className="admin-inline-identity">
@@ -815,77 +812,6 @@ function AdminInfoItem({
  );
 }

-function useAdminResolvedAssetImageSrc(
-  token: string,
-  imageSrc: string | null | undefined,
-  objectKey: string | null | undefined,
-) {
-  const normalizedImageSrc = imageSrc?.trim() ?? '';
-  const normalizedObjectKey = normalizeAdminObjectKey(objectKey);
-  const shouldResolve =
-    Boolean(normalizedObjectKey) || isGeneratedLegacyPath(normalizedImageSrc);
-  const [resolvedImageSrc, setResolvedImageSrc] = useState(
-    shouldResolve ? '' : normalizedImageSrc,
-  );
-
-  useEffect(() => {
-    if (!normalizedImageSrc && !normalizedObjectKey) {
-      setResolvedImageSrc('');
-      return;
-    }
-    if (!shouldResolve) {
-      setResolvedImageSrc(normalizedImageSrc);
-      return;
-    }
-
-    let cancelled = false;
-    setResolvedImageSrc('');
-
-    void getAdminAssetReadUrl(
-      token,
-      normalizedObjectKey
-        ? {
-            objectKey: normalizedObjectKey,
-            expireSeconds: ADMIN_SHOWCASE_READ_EXPIRE_SECONDS,
-          }
-        : {
-            legacyPublicPath: normalizedImageSrc,
-            expireSeconds: ADMIN_SHOWCASE_READ_EXPIRE_SECONDS,
-          },
-    )
-      .then(resolveAdminAssetReadSignedUrl)
-      .then((signedUrl) => {
-        if (!cancelled) {
-          setResolvedImageSrc(signedUrl);
-        }
-      })
-      .catch(() => {
-        if (!cancelled) {
-          setResolvedImageSrc('');
-        }
-      });
-
-    return () => {
-      cancelled = true;
-    };
-  }, [normalizedImageSrc, normalizedObjectKey, shouldResolve, token]);
-
-  return resolvedImageSrc;
-}
-
-function normalizeAdminObjectKey(value: string | null | undefined) {
-  return value?.trim().replace(/^\/+/u, '') ?? '';
-}
-
-function isGeneratedLegacyPath(value: string) {
-  return /^\/?generated-[^/?#]+\/.+/u.test(value.trim());
-}
-
-function resolveAdminAssetReadSignedUrl(response: AdminAssetReadUrlResponse) {
-  const read = response.read ?? response;
-  return typeof read.signedUrl === 'string' ? read.signedUrl.trim() : '';
-}
-
 function mergeShowcaseEntries(
  current: AdminEditorShowcaseAssetPayload[],
  incoming: AdminEditorShowcaseAssetPayload[],
@@ -5,21 +5,16 @@ import userEvent from '@testing-library/user-event';
 import { beforeEach, expect, test, vi } from 'vitest';

 import {
-  getAdminCreationEntryConfig,
  getAdminFeatureGateConfig,
  upsertAdminFeatureGateConfig,
 } from '../api/adminApiClient';
-import type {
-  AdminCreationEntryConfigResponse,
-  AdminFeatureGateConfigResponse,
-} from '../api/adminApiTypes';
+import type { AdminFeatureGateConfigResponse } from '../api/adminApiTypes';
 import { AdminGrayReleaseConfigPage } from './AdminGrayReleaseConfigPage';

 vi.mock('../api/adminApiClient', () => ({
  formatAdminApiError: vi.fn((error: unknown) =>
    error instanceof Error ? error.message : '请求失败',
  ),
-  getAdminCreationEntryConfig: vi.fn(),
  getAdminFeatureGateConfig: vi.fn(),
  isAdminApiError: vi.fn(() => false),
  upsertAdminFeatureGateConfig: vi.fn(),
@@ -50,48 +45,8 @@ const configResponse: AdminFeatureGateConfigResponse = {
  ],
 };

-const creationEntryResponse: AdminCreationEntryConfigResponse = {
-  entries: [
-    {
-      id: 'puzzle',
-      title: '拼图',
-      subtitle: '',
-      badge: '',
-      imageSrc: '',
-      visible: true,
-      open: true,
-      sortOrder: 10,
-      categoryId: 'default',
-      categoryLabel: '默认',
-      categorySortOrder: 0,
-      updatedAtMicros: 0,
-      unifiedCreationSpec: null,
-    },
-    {
-      id: 'match3d',
-      title: '3D 消除',
-      subtitle: '',
-      badge: '',
-      imageSrc: '',
-      visible: true,
-      open: true,
-      sortOrder: 20,
-      categoryId: 'default',
-      categoryLabel: '默认',
-      categorySortOrder: 0,
-      updatedAtMicros: 0,
-      unifiedCreationSpec: null,
-    },
-  ],
-  eventBanners: [],
-  publicWorkInteractions: [],
-};
-
 beforeEach(() => {
  vi.clearAllMocks();
-  vi.mocked(getAdminCreationEntryConfig).mockResolvedValue(
-    creationEntryResponse,
-  );
  vi.mocked(getAdminFeatureGateConfig).mockResolvedValue(configResponse);
  vi.mocked(upsertAdminFeatureGateConfig).mockResolvedValue(configResponse);
 });
@@ -109,7 +64,6 @@ test('灰度发布页加载并展示 gate 列表', async () => {
  ).toBeTruthy();
  expect(screen.getByText('25%')).toBeTruthy();
  expect(getAdminFeatureGateConfig).toHaveBeenCalledWith('admin-token');
-  expect(getAdminCreationEntryConfig).toHaveBeenCalledWith('admin-token');
 });

 test('灰度发布页可选择已有 gate 编辑', async () => {
@@ -152,12 +106,11 @@ test('灰度发布页选择新 target 时重置旧 gate 规则', async () => {
    await screen.findByRole('button', { name: 'editor.new-toolbar' }),
  );
  await user.selectOptions(screen.getByLabelText('Gate Key 前缀'), [
-    'creation-entry',
+    'image-editor',
  ]);
-  await user.selectOptions(screen.getByLabelText('Gate Key 目标'), ['match3d']);

  expect((screen.getByLabelText('Gate Key') as HTMLInputElement).value).toBe(
-    'creation-entry:match3d',
+    'image-editor:agent-sidebar',
  );
  expect((screen.getByLabelText('启用') as HTMLInputElement).checked).toBe(
    false,
@@ -175,27 +128,7 @@ test('灰度发布页选择新 target 时重置旧 gate 规则', async () => {
    (screen.getByLabelText('拒绝用户 ID') as HTMLTextAreaElement).value,
  ).toBe('');
  expect((screen.getByLabelText('描述') as HTMLTextAreaElement).value).toBe(
-    '3D 消除创作入口灰度',
-  );
-});
-
-test('灰度发布页可通过创作入口生成 Gate Key', async () => {
-  const user = userEvent.setup();
-  render(
-    <AdminGrayReleaseConfigPage token="admin-token" onUnauthorized={vi.fn()} />,
-  );
-
-  await screen.findByRole('button', { name: 'editor.new-toolbar' });
-  await user.selectOptions(screen.getByLabelText('Gate Key 前缀'), [
-    'creation-entry',
-  ]);
-  await user.selectOptions(screen.getByLabelText('Gate Key 目标'), ['puzzle']);
-
-  expect((screen.getByLabelText('Gate Key') as HTMLInputElement).value).toBe(
-    'creation-entry:puzzle',
-  );
-  expect((screen.getByLabelText('描述') as HTMLTextAreaElement).value).toBe(
-    '拼图创作入口灰度',
+    '画布 Agent 入口灰度',
  );
 });

@@ -281,7 +214,6 @@ test('灰度发布页保存时转换数组和百分比', async () => {
 test('灰度发布页无 token 时不请求配置', () => {
  render(<AdminGrayReleaseConfigPage token="" onUnauthorized={vi.fn()} />);

-  expect(getAdminCreationEntryConfig).not.toHaveBeenCalled();
  expect(getAdminFeatureGateConfig).not.toHaveBeenCalled();
  expect(upsertAdminFeatureGateConfig).not.toHaveBeenCalled();
 });
@@ -1,13 +1,11 @@
 import { Plus, RefreshCcw, Save } from 'lucide-react';
-import { FormEvent, useEffect, useState } from 'react';
+import { type FormEvent, useEffect, useState } from 'react';

 import {
-  getAdminCreationEntryConfig,
  getAdminFeatureGateConfig,
  upsertAdminFeatureGateConfig,
 } from '../api/adminApiClient';
 import type {
-  AdminCreationEntryTypeConfigPayload,
  AdminFeatureGateConfigPayload,
  AdminUpsertFeatureGateConfigRequest,
 } from '../api/adminApiTypes';
@@ -28,7 +26,6 @@ interface GateTargetOption {
 }

 const GATE_PREFIX_LABELS: Record<string, string> = {
-  'creation-entry': '创作入口',
  'image-editor': '画布',
 };

@@ -47,9 +44,6 @@ export function AdminGrayReleaseConfigPage({
  onUnauthorized,
 }: AdminGrayReleaseConfigPageProps) {
  const [gates, setGates] = useState<AdminFeatureGateConfigPayload[]>([]);
-  const [creationEntries, setCreationEntries] = useState<
-    AdminCreationEntryTypeConfigPayload[]
-  >([]);
  const [selectedGateKey, setSelectedGateKey] = useState('');
  const [gatePrefix, setGatePrefix] = useState('');
  const [gateKey, setGateKey] = useState('');
@@ -74,7 +68,6 @@ export function AdminGrayReleaseConfigPage({
    const requestToken = token.trim();
    if (!requestToken) {
      setGates([]);
-      setCreationEntries([]);
      setListErrorMessage('');
      setIsLoading(false);
      return;
@@ -83,12 +76,8 @@ export function AdminGrayReleaseConfigPage({
    setIsLoading(true);
    setListErrorMessage('');
    try {
-      const [featureGateResponse, creationEntryResponse] = await Promise.all([
-        getAdminFeatureGateConfig(requestToken),
-        getAdminCreationEntryConfig(requestToken),
-      ]);
+      const featureGateResponse = await getAdminFeatureGateConfig(requestToken);
      setGates(featureGateResponse.gates);
-      setCreationEntries(creationEntryResponse.entries);
      const selectedGate = featureGateResponse.gates.find(
        (gate) => gate.gateKey === selectedGateKey,
      );
@@ -240,7 +229,7 @@ export function AdminGrayReleaseConfigPage({

  const canSave =
    gateKey.trim().length > 0 && isRolloutPercentInputValid(rolloutPercent);
-  const gateTargetOptions = buildGateTargetOptions(creationEntries);
+  const gateTargetOptions = FIXED_GATE_TARGETS;
  const gatePrefixOptions = buildGatePrefixOptions(gateTargetOptions);
  const gateTargetsForPrefix = gateTargetOptions.filter(
    (option) => option.prefix === gatePrefix,
@@ -466,27 +455,6 @@ function isRolloutPercentInputValid(value: string) {
  return Number.isFinite(parsed) && parsed >= 0 && parsed <= 100;
 }

-function creationEntryGateKey(entryId: string) {
-  return `creation-entry:${entryId.trim()}`;
-}
-
-function buildGateTargetOptions(
-  creationEntries: AdminCreationEntryTypeConfigPayload[],
-): GateTargetOption[] {
-  return [
-    ...creationEntries.map((entry) => ({
-      prefix: 'creation-entry',
-      suffix: entry.id,
-      key: creationEntryGateKey(entry.id),
-      label: entry.title.trim() || entry.id,
-      description: entry.title.trim()
-        ? `${entry.title.trim()}创作入口灰度`
-        : '创作入口灰度',
-    })),
-    ...FIXED_GATE_TARGETS,
-  ];
-}
-
 function buildGatePrefixOptions(gateTargetOptions: GateTargetOption[]) {
  const seen = new Set<string>();
  return gateTargetOptions.flatMap((option) => {
@@ -19,8 +19,6 @@
  "exclude": [
    "src/pages/AdminCreationEntrySwitchPage.tsx",
    "src/pages/AdminCreationEntrySwitchPage.test.tsx",
-    "src/pages/AdminGrayReleaseConfigPage.tsx",
-    "src/pages/AdminGrayReleaseConfigPage.test.tsx",
    "src/pages/AdminWorkVisibilityPage.tsx"
  ]
 }
@@ -1,6 +1,6 @@
 # Genarrative 容器化压测、隔离部署与 CI Job 镜像

-本目录同时保存两类互不替代的容器资产：本机或预发的容器化模拟压测，以及 Gitea Actions 使用的预构建 CI job 镜像。它们都不替换当前生产 `systemd + Nginx + Jenkins` 发布路径；生产服务器仍以 `deploy/systemd/`、`deploy/nginx/`、`scripts/jenkins-*.sh` 和 `scripts/deploy/production-api-deploy.sh` 为准。
+本目录同时保存两类互不替代的容器资产：本机或预发的容器化模拟压测，以及 Gitea Actions 使用的预构建 CI job 镜像。它们都不替换当前生产 `systemd + Nginx + Jenkins` 发布路径；生产服务器仍以 `deploy/systemd/`、`deploy/nginx/`、`scripts/jenkins-*.sh` 和 `scripts/deploy/production-api-deploy.sh` 为准。当前 compose 不包含独立 `bgfilter-worker`，因此不是完整 BgFilter 预发拓扑，也不覆盖会触发 BgFilter 的现役任务；这里只验证非 BgFilter 路径，或使用 unsupported job 检查队列 claim / fail 回写和 API / worker 进程隔离。

 ## 拓扑

@@ -15,7 +15,7 @@ Docker Compose

 当前容器模拟参数按 `genarrative-release` 服务器采样值收口为 2 vCPU / 2 GiB RAM / 4096 soft nofile / 768 worker_connections，并已在 compose 里落实到 `spacetimedb cpus=1.0 mem_limit=896m`、`api-server cpus=2.0 mem_limit=1g`、`external-generation-worker cpus=2.0 mem_limit=1g`、`nginx cpus=0.5 mem_limit=128m`、`otelcol cpus=0.25 mem_limit=128m`。SpacetimeDB 同时设置 `--page_pool_max_size=402653184`，给 reducer、订阅与运行时保留更多非 page pool 内存。
 容器 `api-server` 默认 `GENARRATIVE_API_WORKER_THREADS=4`，用于让 Tokio 在 2 vCPU 配额内有更多 I/O 调度 worker；该值不会突破 compose 里的 `cpus=2.0` CPU 上限。
-容器默认 `GENARRATIVE_EXTERNAL_GENERATION_MODE=queue`，用于验证 `api-server -> external_generation_job -> external-generation-worker` 链路；如只想本地同步排查 provider/OSS/SpacetimeDB 写回，可在本机 env 临时改为 `inline`，但该模式不会覆盖 worker 动态扩缩容验证。
+容器默认 `GENARRATIVE_EXTERNAL_GENERATION_MODE=queue`，用于验证不经过 BgFilter 的 `api-server -> external_generation_job -> external-generation-worker` 链路；会触发 BgFilter 的任务不属于当前 compose 验收范围。如只想本地同步排查非 BgFilter provider / OSS / SpacetimeDB 写回，可在本机 env 临时改为 `inline`，但该模式不会覆盖 worker 动态扩缩容验证。
 Collector 镜像使用 `otel/opentelemetry-collector-contrib:0.151.0`。
 生产服务器若启用 Collector，则由 `deploy/systemd/otelcol-contrib.service` 和 `deploy/otelcol/genarrative-debug.yaml` 托管，不走容器镜像。

@@ -56,7 +56,7 @@ Linux Docker Engine 若要从宿主机 CLI 连到容器内服务，直接用 `ht

 ## 构建工具链

-`api-server` 容器镜像只构建 Linux release API 二进制，不构建 `spacetime-module`。当前 `api-server -> spacetime-client -> spacetimedb-sdk 2.6.1` 依赖链要求 Rust 1.93，因此 `deploy/container/api-server.Dockerfile` 的 Rust builder 固定为 `rust:1.93-bookworm`。镜像构建阶段会同时复制 `public/`，用于满足 API 二进制里 `include_bytes!` 引用的内置素材；不要把 `public/generated-*` 放入镜像上下文。如果本机 Docker Hub 拉取失败，可以先在本机准备同名本地 builder 镜像，但不要把临时 bootstrap 容器或私有 registry 凭据写入仓库。
+`api-server` 容器镜像只构建 Linux release API 二进制，不构建 `spacetime-module`。当前 `api-server -> spacetime-client -> spacetimedb-sdk 2.7.0` 依赖链继续兼容 Rust 1.93，因此 `deploy/container/api-server.Dockerfile` 的 Rust builder 固定为 `rust:1.93-bookworm`。镜像构建阶段会同时复制 `public/`，用于满足 API 二进制里 `include_bytes!` 引用的内置素材；不要把 `public/generated-*` 放入镜像上下文。如果本机 Docker Hub 拉取失败，可以先在本机准备同名本地 builder 镜像，但不要把临时 bootstrap 容器或私有 registry 凭据写入仓库。

 ### Gitea CI 预构建 Job 镜像

@@ -67,13 +67,13 @@ Linux Docker Engine 若要从宿主机 CLI 连到容器内服务，直接用 `ht
 ```bash
 bash scripts/gitea-ci-job-image.sh build
 bash scripts/gitea-ci-job-image.sh verify
-bash scripts/gitea-ci-job-image.sh export /仓库外受控路径/genarrative-gitea-project-ci-20260722.2.tar.zst
+bash scripts/gitea-ci-job-image.sh export /仓库外受控路径/genarrative-gitea-project-ci-20260723.1.tar.zst
 bash scripts/gitea-ci-job-image.sh load-runner
 ```

-默认构建 tag 为 `genarrative/gitea-project-ci:20260722.2`。脚本通过 NUL 分隔白名单 tar 流只发送 Dockerfile、checkout 脚本、npm manifests/lock 和 Cargo manifests/lock；当前构建 context 约 `1.638 MB`，不会把业务源码、素材或本地私密文件发送给 Docker daemon。镜像除固定工具链外，还按当前根 `package-lock.json`、`server-rs/Cargo.lock` 和桌面壳 `Cargo.lock` 预热 npm / Cargo 下载缓存，并在构建阶段执行离线完整性校验；不包含 `node_modules` 或 Cargo `target`。`build` 完成后会自动运行环境校验，`load-runner` 还会比对宿主和 runner 内层的完整 Image ID，并在内层执行 bwrap 与 Chrome headless canary。当前验证镜像约 `1.788 GB`，完整 Image ID 为 `sha256:548431a2529d325b5ab546f242799a4076f979779ee832a0871ac1af881a4946`。执行这些命令不要求必须使用 root，但执行账号必须有权访问宿主 Docker API 并管理 runner 容器；没有该权限时交给 runner 运维人员执行。
+默认构建 tag 为 `genarrative/gitea-project-ci:20260723.1`。脚本通过 NUL 分隔白名单 tar 流只发送 Dockerfile、checkout 脚本、npm manifests/lock 和 Cargo manifests/lock；当前构建 context 约 `1.638 MB`，不会把业务源码、素材或本地私密文件发送给 Docker daemon。镜像除固定工具链外，还按当前根 `package-lock.json`、`server-rs/Cargo.lock` 和桌面壳 `Cargo.lock` 预热 npm / Cargo 下载缓存；两个 `cargo fetch --locked` 最多执行 5 次整命令级有界重试，再以断网 `cargo fetch --locked` 验证缓存闭合，不包含 `node_modules` 或 Cargo `target`。`build` 完成后会自动运行环境校验，`load-runner` 还会比对宿主和 runner 内层的完整 Image ID，并在内层执行 bwrap 与 Chrome headless canary。当前验证镜像约 `1.788 GB`，完整 Image ID 为 `sha256:c04b114b1f145072c9df7842c4c974e1bb2eaaf391d95d84c9212a460546b7d5`。执行这些命令不要求必须使用 root，但执行账号必须有权访问宿主 Docker API 并管理 runner 容器；没有该权限时交给 runner 运维人员执行。

-runner 配置保留原 `ubuntu-latest` 映射，另外增加 `genarrative-ci:docker://sha256:548431a2529d325b5ab546f242799a4076f979779ee832a0871ac1af881a4946`。内层 Docker 数据必须持久化，`force_pull` 保持 `false`；该精确 Image ID 在内层不存在时 job 应直接失败，不回退到浮动 tag 或现场拉取。四个 job 使用镜像内 `genarrative-gitea-checkout` 直接从当前 Gitea 拉取事件 commit，带 5 次有界重试，不再运行时下载 GitHub checkout action；随后以 `GENARRATIVE_GITEA_CI_CHECK_RUNTIME=1` 执行 `scripts/check-gitea-ci-job-image.sh`，同时校验工具链、缓存锁命中状态、bwrap 和 Chrome headless。它们仍各自运行干净的 `npm ci` 以校验当前 lockfile 并隔离 PR 依赖，但使用镜像内 npm cache 和 `prefer-offline`；锁文件新增依赖时允许经受控网络补齐，本阶段不启用共享 Actions cache。
+runner 配置保留原 `ubuntu-latest` 映射，另外增加 `genarrative-ci:docker://sha256:c04b114b1f145072c9df7842c4c974e1bb2eaaf391d95d84c9212a460546b7d5`。内层 Docker 数据必须持久化，`force_pull` 保持 `false`；该精确 Image ID 在内层不存在时 job 应直接失败，不回退到浮动 tag 或现场拉取。四个 job 使用镜像内 `genarrative-gitea-checkout` 直接从当前 Gitea 拉取事件 commit，带 5 次有界重试，不再运行时下载 GitHub checkout action；随后以 `GENARRATIVE_GITEA_CI_CHECK_RUNTIME=1` 执行 `scripts/check-gitea-ci-job-image.sh`，同时校验工具链、缓存锁命中状态、bwrap 和 Chrome headless。它们仍各自运行干净的 `npm ci` 以校验当前 lockfile 并隔离 PR 依赖，但使用镜像内 npm cache 和 `prefer-offline`；锁文件新增依赖时允许经受控网络补齐，本阶段不启用共享 Actions cache。

 更新顺序固定为：

@@ -156,7 +156,7 @@ npm run container:worker-smoke -- status
 npm run container:worker-smoke -- smoke --force
 ```

-`container:worker-smoke` 默认会把本机 `spacetime` 2.6.1 CLI 打成轻量 SpacetimeDB 镜像，避免首次 smoke 必须拉取官方大镜像；普通 `npm run container:*` 压测默认使用 `clockworklabs/spacetime:v2.6.1`。如果 Docker build 阶段在容器内拉取 crates.io 依赖不稳定，可让容器内 Cargo 复用本机 Cargo 缓存构建当前二进制，再打入临时 smoke 镜像。该模式默认使用 `rust:1.93-bookworm` 作为 builder、Debian bookworm smoke runtime 承载构建产物；需要换 builder 镜像时设置 `GENARRATIVE_WORKER_SMOKE_CARGO_IMAGE`，需要换运行时基础镜像时设置 `GENARRATIVE_WORKER_SMOKE_LOCAL_BASE_IMAGE`：
+`container:worker-smoke` 默认会把本机 `spacetime` 2.7.0 CLI 打成轻量 SpacetimeDB 镜像，避免首次 smoke 必须拉取官方大镜像；普通 `npm run container:*` 压测默认使用 `clockworklabs/spacetime:v2.7.0-hotfix3`（容器内二进制报告 2.7.0）。如果 Docker build 阶段在容器内拉取 crates.io 依赖不稳定，可让容器内 Cargo 复用本机 Cargo 缓存构建当前二进制，再打入临时 smoke 镜像。该模式默认使用 `rust:1.93-bookworm` 作为 builder、Debian bookworm smoke runtime 承载构建产物；需要换 builder 镜像时设置 `GENARRATIVE_WORKER_SMOKE_CARGO_IMAGE`，需要换运行时基础镜像时设置 `GENARRATIVE_WORKER_SMOKE_LOCAL_BASE_IMAGE`：

 ```bash
 npm run container:worker-smoke -- smoke --local-binary
@@ -30,9 +30,10 @@ GENARRATIVE_WALLET_REFUND_OUTBOX_DIR=/var/lib/genarrative/wallet-refund-outbox
 GENARRATIVE_WALLET_REFUND_OUTBOX_BATCH_SIZE=100
 GENARRATIVE_WALLET_REFUND_OUTBOX_FLUSH_INTERVAL_MS=1000
 GENARRATIVE_WALLET_REFUND_OUTBOX_MAX_BYTES=67108864
-GENARRATIVE_EDITOR_BGFILTER_REQUEST_TIMEOUT_MS=180000
+GENARRATIVE_BGFILTER_WORKER_CONCURRENCY=16
+GENARRATIVE_EDITOR_BGFILTER_SINGLE_IMAGE_ESTIMATE_MS=5000
 GENARRATIVE_EDITOR_BGFILTER_CIRCUIT_FAILURE_THRESHOLD=3
-GENARRATIVE_EDITOR_BGFILTER_CIRCUIT_COOLDOWN_SECONDS=300
+GENARRATIVE_EDITOR_BGFILTER_CIRCUIT_COOLDOWN_SECONDS=120
 # BgFilter 失败后的中间兜底：阿里云通用抠图（SegmentCommonImage）。AccessKey 留空则跳过该层，
 # BgFilter 失败直接本地 editor_green_screen 去背；填入后恢复 BgFilter→阿里云→本地三级兜底。
 # AccessKey 也可复用标准 SDK 命名 ALIBABA_CLOUD_ACCESS_KEY_ID / ALIBABA_CLOUD_ACCESS_KEY_SECRET。
@@ -2,7 +2,7 @@ name: genarrative-container-loadtest

 services:
  spacetimedb:
-    image: ${GENARRATIVE_CONTAINER_SPACETIME_IMAGE:-clockworklabs/spacetime:v2.6.1}
+    image: ${GENARRATIVE_CONTAINER_SPACETIME_IMAGE:-clockworklabs/spacetime:v2.7.0-hotfix3}
    user: root
    command:
      [
--- a/Show More
+++ b/Show More