合并master并融合抠图链路优化

合入 master 的 BgFilter 重试、cross-check、complex 模式和动作帧超时策略。保留生成原图 OSS URL 调用、阿里云按需下载及本地 fallback 内存释放。保留 AuthorizeFileUpload 正式临时上传链路并融合相关文档。
2026-07-17 05:42:51 +00:00
parent 9e0a20aac4 ed1a972c9e
commit b36485fdd0
123 changed files with 10978 additions and 1383 deletions
@@ -14,20 +14,40 @@ if (hookInput && !isGitCommitCommand(extractShellCommand(hookInput))) {
 }

 const validationSteps = [
+  {
+    label: 'Rust format check',
+    command: npmCommand,
+    args:
+      process.platform === 'win32'
+        ? ['/d', '/s', '/c', 'npm run check:rustfmt']
+        : ['run', 'check:rustfmt'],
+  },
  {
    label: 'TypeScript typecheck',
    command: npmCommand,
-    args: process.platform === 'win32' ? ['/d', '/s', '/c', 'npm run typecheck'] : ['run', 'typecheck'],
+    args:
+      process.platform === 'win32'
+        ? ['/d', '/s', '/c', 'npm run typecheck']
+        : ['run', 'typecheck'],
  },
  {
    label: 'Admin web typecheck',
    command: npmCommand,
-    args: process.platform === 'win32' ? ['/d', '/s', '/c', 'npm run admin-web:typecheck'] : ['run', 'admin-web:typecheck'],
+    args:
+      process.platform === 'win32'
+        ? ['/d', '/s', '/c', 'npm run admin-web:typecheck']
+        : ['run', 'admin-web:typecheck'],
  },
  {
    label: 'Rust api-server compile check',
    command: 'cargo',
-    args: ['check', '-p', 'api-server', '--manifest-path', 'server-rs/Cargo.toml'],
+    args: [
+      'check',
+      '-p',
+      'api-server',
+      '--manifest-path',
+      'server-rs/Cargo.toml',
+    ],
  },
 ];

@@ -66,7 +86,9 @@ function runStep(step) {
  }

  if (result.error) {
-    console.error(`[codex-hook] ${step.label} 启动失败：${result.error.message}`);
+    console.error(
+      `[codex-hook] ${step.label} 启动失败：${result.error.message}`,
+    );
    return { ok: false, status: 1 };
  }

@@ -104,12 +126,15 @@ function extractShellCommand(input) {
    input?.command,
  ];

-  const command = candidates.find(value => typeof value === 'string' && value.trim().length > 0);
+  const command = candidates.find(
+    (value) => typeof value === 'string' && value.trim().length > 0,
+  );
  if (command) {
    return command;
  }

-  const shellCommand = input?.tool_input?.cmd ?? input?.toolInput?.cmd ?? input?.arguments?.cmd;
+  const shellCommand =
+    input?.tool_input?.cmd ?? input?.toolInput?.cmd ?? input?.arguments?.cmd;
  if (Array.isArray(shellCommand)) {
    return shellCommand.join(' ');
  }
@@ -318,6 +318,14 @@ For image edit/redraw that should replace an existing canvas layer, pass `projec

 For sound effects and BGM, `assetFolderId` and `assetLabel` can write the generated audio to the account asset library, same as image/video generation.

+## Successful Responses with Warnings
+
+Character image generation (including character redraw through `kind: "character"`), icon spritesheet generation, and UI asset extraction can return HTTP 2xx with an optional structured `warning`. A 2xx response means the task completed, but it does not guarantee that every requested post-processed derivative exists.
+
+- Apply the returned `project` and media snapshots before interpreting optional derivatives: character responses use `resource` / `asset`, while icon spritesheet and UI extraction responses use `spritesheetResource` / `spritesheetAsset`. When `warning.code` is `postprocess-failed-source-preserved`, the saved provider source image is the authoritative main result. Character output has no transparent derivative; icon spritesheet and UI extraction output have neither a transparent spritesheet nor slices. Display `warning.reason` directly, and do not synthesize missing derivatives or restart generation.
+- `sliceWarning` is a separate condition used only when transparent spritesheet post-processing succeeded but automatic slicing failed. Keep `sliceWarning.reason` as the original diagnostic and continue using the complete transparent spritesheet; a UI may add context when displaying it, but must not rewrite the stored reason.
+- The service contract keeps `warning` and `sliceWarning` mutually exclusive. As defensive handling for a malformed response containing both, treat the general `warning` as authoritative and do not misclassify the source-preserved result as a slicing-only warning.
+
 ## Guardrails

 - Do not invent endpoints outside the OpenAPI, especially internal worker or runtime task-list routes.
@@ -78,6 +78,14 @@ Ask a follow-up only when two routes could both be correct and produce different

 All generation requests should be placed into both the current canvas and its same-name asset-library folder. For endpoints that support `assetLabel`, pass it. For UI extraction, use `spritesheetLabel`. For icon spritesheet, the folder is enough. For character animation, the endpoint does not return `asset`; after success call `POST /api/external/v1/editor/assets` using the first returned frame as `imageSrc`, the session `assetFolderId`, and `assetKind: "character-animation"`.

+## HTTP 2xx Warning Handling
+
+Character image generation (including character redraw through `kind: "character"`), icon spritesheet generation, and UI asset extraction may return HTTP 2xx while carrying a structured `warning`; completion does not imply that all post-processed derivatives exist.
+
+- Consume the returned `project` and media snapshots as authoritative: character responses use `resource` / `asset`, while icon spritesheet and UI extraction responses use `spritesheetResource` / `spritesheetAsset`. `warning.code: "postprocess-failed-source-preserved"` means the saved provider source is the main result. Character output has no transparent derivative, while icon spritesheet and UI extraction have no transparent spritesheet and no slices. Display `warning.reason` directly; do not construct missing assets or retry the provider generation from scratch.
+- `sliceWarning` is only for a transparent spritesheet that was created successfully but could not be split automatically. Use the complete transparent spritesheet and preserve `sliceWarning.reason` as the original diagnostic; it is not a post-processing/source-preserved warning.
+- The service contract keeps `warning` and `sliceWarning` mutually exclusive. If a malformed response contains both, prioritize the general `warning` over `sliceWarning` defensively.
+
 ## Reference Image Upload

 If the user provides a local file as a reference image, run upload before the generation request:
@@ -29,6 +29,7 @@ GENARRATIVE_LLM_PROVIDER="ark"
 GENARRATIVE_LLM_BASE_URL="https://ark.cn-beijing.volces.com/api/v3"
 GENARRATIVE_LLM_API_KEY="eb750614-e0b5-402a-bfea-4224862d251e"
 GENARRATIVE_LLM_MODEL="doubao-1-5-pro-32k-character-250715"
+GENARRATIVE_EDITOR_BGFILTER_BASE_URL="https://u1082648-b442-cd409e05.westx.seetacloud.com:8443"
 APIMART_BASE_URL="https://api.apimart.ai/v1"
 APIMART_API_KEY=""
 APIMART_IMAGE_REQUEST_TIMEOUT_MS=180000
@@ -36,6 +37,7 @@ DASHSCOPE_SCENE_IMAGE_MODEL="wan2.2-t2i-flash"
 DASHSCOPE_REFERENCE_IMAGE_MODEL="qwen-image-2.0"
 DASHSCOPE_COVER_IMAGE_MODEL="wan2.2-t2i-flash"
 ARK_CHARACTER_VIDEO_REQUEST_TIMEOUT_MS=420000
+
 # 启用服务端大模型调试日志（记录所有输入输出）
 LLM_DEBUG_LOG="true"

@@ -50,6 +50,7 @@ temp*build*/
 .worktrees/
 .rag/
 .env.secrets.local
+nohup.out
 spacetime.local.json
 deploy/container/api-server.env
 deploy/container/worker-smoke/
@@ -398,10 +398,11 @@ export function getAdminAssetReadUrl(
 export function listAdminEditorAssets(
  token: string,
  query: AdminEditorAssetListQuery = {},
+  signal?: AbortSignal,
 ) {
  return request<AdminEditorAssetListResponse>(
    `/admin/api/editor-assets${buildEditorAssetListQuery(query)}`,
-    { token },
+    { token, signal },
  );
 }

@@ -128,6 +128,7 @@ export interface AdminDashboardMetricsPayload {
  consumedMudPoints: number;
  totalRegisteredUsers: number;
  newRegisteredUsers: number;
+  newUserPaymentConversion: AdminDashboardPaymentConversionPayload;
  day1Retention: AdminDashboardRetentionMetricPayload;
  day7Retention: AdminDashboardRetentionMetricPayload;
  visitUsers: number;
@@ -137,6 +138,12 @@ export interface AdminDashboardMetricsPayload {
  currentUsers: number;
 }

+export interface AdminDashboardPaymentConversionPayload {
+  paidUsers: number;
+  newRegisteredUsers: number;
+  rateBasisPoints: number;
+}
+
 export interface AdminDashboardRetentionMetricPayload {
  eligibleUsers: number;
  retainedUsers: number;
@@ -460,6 +467,7 @@ export interface AdminEditorAssetPayload {
  model?: string | null;
  provider?: string | null;
  taskId?: string | null;
+  groupTaskId?: string | null;
  assetKind?: string | null;
  generationInputs?: Record<string, unknown> | null;
  sourceResourceId?: string | null;
@@ -35,6 +35,11 @@ const dashboardResponse: AdminDashboardResponse = {
    consumedMudPoints: 88,
    totalRegisteredUsers: 1200,
    newRegisteredUsers: 16,
+    newUserPaymentConversion: {
+      paidUsers: 5,
+      newRegisteredUsers: 16,
+      rateBasisPoints: 3125,
+    },
    day1Retention: {
      eligibleUsers: 12,
      retainedUsers: 3,
@@ -101,7 +106,20 @@ test('Dashboard 默认加载今日指标并支持运营汇总页签', async () =
  expect(screen.getByText('本日生产素材数')).toBeTruthy();
  expect(screen.getByText('总注册用户')).toBeTruthy();
  expect(screen.getByText('本日新增用户数')).toBeTruthy();
-  expect(screen.getByText('新增用户留存')).toBeTruthy();
+  expect(screen.getByText('新增用户转化与留存')).toBeTruthy();
+  const paymentRateCard = screen
+    .getByText('本日新增用户付费率')
+    .closest('article');
+  expect(paymentRateCard).toBeTruthy();
+  expect(
+    within(paymentRateCard as HTMLElement).getByText('31.25%'),
+  ).toBeTruthy();
+  expect(
+    within(paymentRateCard as HTMLElement).getByText('付费人数 / 新增人数'),
+  ).toBeTruthy();
+  expect(
+    within(paymentRateCard as HTMLElement).getByText('5 / 16 人'),
+  ).toBeTruthy();
  expect(screen.getByText('次日留存')).toBeTruthy();
  expect(screen.getByText('25%')).toBeTruthy();
  expect(screen.getByText('3 / 12 人')).toBeTruthy();
@@ -218,6 +236,33 @@ test('Dashboard 手动选择起止日期时使用本时段查询', async () => {
    });
  });
  expect(screen.getByText('本时段新增用户数')).toBeTruthy();
+  expect(screen.getByText('本时段新增用户付费率')).toBeTruthy();
+});
+
+test('Dashboard 新增用户付费率分母为零时显示横线', async () => {
+  vi.mocked(getAdminDashboard).mockResolvedValue({
+    ...dashboardResponse,
+    metrics: {
+      ...dashboardResponse.metrics,
+      newRegisteredUsers: 0,
+      newUserPaymentConversion: {
+        paidUsers: 0,
+        newRegisteredUsers: 0,
+        rateBasisPoints: 0,
+      },
+    },
+  });
+
+  render(<AdminDashboardPage token="admin-token" onUnauthorized={vi.fn()} />);
+
+  const paymentRateCard = (
+    await screen.findByText('本日新增用户付费率')
+  ).closest('article');
+  expect(paymentRateCard).toBeTruthy();
+  expect(within(paymentRateCard as HTMLElement).getByText('-')).toBeTruthy();
+  expect(
+    within(paymentRateCard as HTMLElement).getByText('0 / 0 人'),
+  ).toBeTruthy();
 });

 test('Dashboard 手动选择日期时不允许查询北京时间今天之后', async () => {
@@ -6,7 +6,6 @@ import type {
  AdminDashboardBreakdownRowPayload,
  AdminDashboardChartPayload,
  AdminDashboardGranularity,
-  AdminDashboardRetentionMetricPayload,
  AdminDashboardResponse,
 } from '../api/adminApiTypes';
 import { handlePageError } from './pageUtils';
@@ -292,12 +291,38 @@ export function AdminDashboardPage({

          <section className="admin-panel">
            <div className="admin-panel-heading">
-              <h3>新增用户留存</h3>
+              <h3>新增用户转化与留存</h3>
              <span>{dashboard?.range.periodLabel ?? '-'}</span>
            </div>
            <div className="admin-dashboard-retention-grid">
-              <RetentionCard label="次日留存" metric={metrics?.day1Retention} />
-              <RetentionCard label="七日留存" metric={metrics?.day7Retention} />
+              <RateCard
+                label={`${rangePrefix(granularity)}新增用户付费率`}
+                numeratorLabel="付费人数"
+                denominatorLabel="新增人数"
+                numerator={metrics?.newUserPaymentConversion?.paidUsers}
+                denominator={
+                  metrics?.newUserPaymentConversion?.newRegisteredUsers
+                }
+                rateBasisPoints={
+                  metrics?.newUserPaymentConversion?.rateBasisPoints
+                }
+              />
+              <RateCard
+                label="次日留存"
+                numeratorLabel="留存人数"
+                denominatorLabel="可观察新增人数"
+                numerator={metrics?.day1Retention.retainedUsers}
+                denominator={metrics?.day1Retention.eligibleUsers}
+                rateBasisPoints={metrics?.day1Retention.rateBasisPoints}
+              />
+              <RateCard
+                label="七日留存"
+                numeratorLabel="留存人数"
+                denominatorLabel="可观察新增人数"
+                numerator={metrics?.day7Retention.retainedUsers}
+                denominator={metrics?.day7Retention.eligibleUsers}
+                rateBasisPoints={metrics?.day7Retention.rateBasisPoints}
+              />
            </div>
          </section>

@@ -406,27 +431,37 @@ function MetricCard({
  );
 }

-function RetentionCard({
+function RateCard({
  label,
-  metric,
+  numeratorLabel,
+  denominatorLabel,
+  numerator,
+  denominator,
+  rateBasisPoints,
 }: {
  label: string;
-  metric?: AdminDashboardRetentionMetricPayload;
+  numeratorLabel: string;
+  denominatorLabel: string;
+  numerator?: number;
+  denominator?: number;
+  rateBasisPoints?: number;
 }) {
-  const hasEligibleUsers = Boolean(metric?.eligibleUsers);
+  const hasDenominator = Boolean(denominator);
  return (
    <article className="admin-dashboard-retention-card">
      <span>{label}</span>
      <strong>
-        {hasEligibleUsers && metric
-          ? formatRateBasisPoints(metric.rateBasisPoints)
+        {hasDenominator && rateBasisPoints !== undefined
+          ? formatRateBasisPoints(rateBasisPoints)
          : '-'}
      </strong>
      <div>
-        <small>留存人数 / 可观察新增人数</small>
+        <small>
+          {numeratorLabel} / {denominatorLabel}
+        </small>
        <b>
-          {metric
-            ? `${formatNumber(metric.retainedUsers)} / ${formatNumber(metric.eligibleUsers)} 人`
+          {numerator !== undefined && denominator !== undefined
+            ? `${formatNumber(numerator)} / ${formatNumber(denominator)} 人`
            : '-'}
        </b>
      </div>
@@ -1,6 +1,6 @@
 import { ChevronDown, ChevronRight, Eye, FileText, RefreshCcw, X } from 'lucide-react';
 import { Fragment, type ReactNode } from 'react';
-import { useCallback, useEffect, useState } from 'react';
+import { useCallback, useEffect, useRef, useState } from 'react';

 import {
  getAdminAssetReadUrl,
@@ -24,6 +24,7 @@ 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 ADMIN_EDITOR_ASSET_FILTER_DEBOUNCE_MS = 300;
 const AUDIO_ASSET_COVER_SRC = `${import.meta.env.DEV ? import.meta.env.BASE_URL : '/'}creation-home/audio-asset-cover.png`;
 let adminAssetReadDispatchTail = Promise.resolve();

@@ -37,6 +38,9 @@ export function AdminEditorAssetQueryPage({
  const [createdAfter, setCreatedAfter] = useState('');
  const [createdBefore, setCreatedBefore] = useState('');
  const [nextCursor, setNextCursor] = useState<string | null>(null);
+  const [committedQueryKey, setCommittedQueryKey] = useState<string | null>(
+    null,
+  );
  const [isLoading, setIsLoading] = useState(false);
  const [isLoadingMore, setIsLoadingMore] = useState(false);
  const [errorMessage, setErrorMessage] = useState('');
@@ -51,49 +55,147 @@ export function AdminEditorAssetQueryPage({
    title: string;
    prompt: string;
  } | null>(null);
+  const listRequestGenerationRef = useRef(0);
+  const listRequestAbortControllerRef = useRef<AbortController | null>(null);
+  const automaticQueryInitializedRef = useRef(false);
+  const automaticQueryTokenRef = useRef(token);
+  const activeQuery = buildListQuery();
+  const activeQueryKey = editorAssetListQueryKey(token, activeQuery);
+  const hasCurrentQuerySnapshot = committedQueryKey === activeQueryKey;
+  const visibleEntries = hasCurrentQuerySnapshot ? entries : [];
+  const visibleNextCursor = hasCurrentQuerySnapshot ? nextCursor : null;

  useEffect(() => {
-    void refreshPage();
+    const runImmediately =
+      !automaticQueryInitializedRef.current ||
+      automaticQueryTokenRef.current !== token;
+    automaticQueryInitializedRef.current = true;
+    automaticQueryTokenRef.current = token;
+
+    if (runImmediately) {
+      void refreshPage();
+      return;
+    }
+
+    invalidateListRequest();
+    setIsLoading(true);
+    setIsLoadingMore(false);
+    setErrorMessage('');
+    const timer = setTimeout(
+      () => void refreshPage(),
+      ADMIN_EDITOR_ASSET_FILTER_DEBOUNCE_MS,
+    );
+    return () => clearTimeout(timer);
    // eslint-disable-next-line react-hooks/exhaustive-deps
  }, [token, ownerUserId, keyword, createdAfter, createdBefore]);

+  useEffect(
+    () => () => {
+      automaticQueryInitializedRef.current = false;
+      invalidateListRequest();
+    },
+    [],
+  );
+
  async function refreshPage() {
+    const query = buildListQuery();
+    const queryKey = editorAssetListQueryKey(token, query);
+    const { requestGeneration, abortController } = beginListRequest();
    setIsLoading(true);
+    setIsLoadingMore(false);
    setErrorMessage('');
    try {
-      const response = await listAdminEditorAssets(token, buildListQuery());
+      const response = await listAdminEditorAssets(
+        token,
+        query,
+        abortController.signal,
+      );
+      if (listRequestGenerationRef.current !== requestGeneration) {
+        return;
+      }
      setEntries(response.entries);
      setNextCursor(response.nextCursor ?? null);
+      setCommittedQueryKey(queryKey);
    } catch (error: unknown) {
+      if (
+        listRequestGenerationRef.current !== requestGeneration ||
+        isAbortError(error)
+      ) {
+        return;
+      }
      handlePageError(error, onUnauthorized, setErrorMessage);
    } finally {
-      setIsLoading(false);
+      if (listRequestGenerationRef.current === requestGeneration) {
+        if (listRequestAbortControllerRef.current === abortController) {
+          listRequestAbortControllerRef.current = null;
+        }
+        setIsLoading(false);
+      }
    }
  }

  async function loadMore() {
-    if (!nextCursor || isLoadingMore) {
+    if (!visibleNextCursor || isLoading || isLoadingMore) {
      return;
    }
+    const query = buildListQuery();
+    const queryKey = editorAssetListQueryKey(token, query);
+    if (committedQueryKey !== queryKey) {
+      return;
+    }
+    const cursor = visibleNextCursor;
+    const { requestGeneration, abortController } = beginListRequest();
    setIsLoadingMore(true);
    setErrorMessage('');
    try {
-      const response = await listAdminEditorAssets(token, {
-        ...buildListQuery(),
-        cursor: nextCursor,
-      });
+      const response = await listAdminEditorAssets(
+        token,
+        {
+          ...query,
+          cursor,
+        },
+        abortController.signal,
+      );
+      if (listRequestGenerationRef.current !== requestGeneration) {
+        return;
+      }
      setEntries((current) => mergeAssetEntries(current, response.entries));
      setNextCursor(response.nextCursor ?? null);
    } catch (error: unknown) {
+      if (
+        listRequestGenerationRef.current !== requestGeneration ||
+        isAbortError(error)
+      ) {
+        return;
+      }
      handlePageError(error, onUnauthorized, setErrorMessage);
    } finally {
-      setIsLoadingMore(false);
+      if (listRequestGenerationRef.current === requestGeneration) {
+        if (listRequestAbortControllerRef.current === abortController) {
+          listRequestAbortControllerRef.current = null;
+        }
+        setIsLoadingMore(false);
+      }
    }
  }

+  function beginListRequest() {
+    invalidateListRequest();
+    const abortController = new AbortController();
+    listRequestAbortControllerRef.current = abortController;
+    const requestGeneration = listRequestGenerationRef.current;
+    return { requestGeneration, abortController };
+  }
+
+  function invalidateListRequest() {
+    listRequestGenerationRef.current += 1;
+    listRequestAbortControllerRef.current?.abort();
+    listRequestAbortControllerRef.current = null;
+  }
+
  function buildListQuery(): AdminEditorAssetListQuery {
    return {
-      ownerUserId: ownerUserId || null,
+      ownerUserId: ownerUserId.trim() || null,
      keyword: keyword.trim() || null,
      createdAfter: dateInputToStartRfc3339(createdAfter),
      createdBefore: dateInputToEndRfc3339(createdBefore),
@@ -143,7 +245,7 @@ export function AdminEditorAssetQueryPage({
            />
          </label>
          <label className="admin-field">
-            <span>用户 ID</span>
+            <span>用户 ID / 陶泥号</span>
            <input
              value={ownerUserId}
              onChange={(event) => setOwnerUserId(event.target.value)}
@@ -173,7 +275,7 @@ export function AdminEditorAssetQueryPage({
              </tr>
            </thead>
            <tbody>
-              {entries.map((entry) => {
+              {visibleEntries.map((entry) => {
                const promptText = entry.prompt || entry.actualPrompt || '-';
                const expanded = expandedTaskIds.has(entry.assetId);
                const children = entry.children ?? [];
@@ -318,13 +420,13 @@ export function AdminEditorAssetQueryPage({
          </table>
        </div>

-        {!isLoading && entries.length === 0 ? (
+        {!isLoading && !errorMessage && visibleEntries.length === 0 ? (
          <div className="admin-empty-state">暂无生成素材</div>
        ) : null}
-        {nextCursor ? (
+        {visibleNextCursor ? (
          <button
            className="admin-secondary-button"
-            disabled={isLoadingMore}
+            disabled={isLoading || isLoadingMore}
            type="button"
            onClick={loadMore}
          >
@@ -645,6 +747,12 @@ function AdminAssetDetailDialog({
              {entry.provider || '-'}
            </AdminInfoItem>
            <AdminInfoItem label="Task ID">{entry.taskId || '-'}</AdminInfoItem>
+            {entry.groupTaskId?.trim() &&
+            entry.groupTaskId.trim() !== entry.taskId?.trim() ? (
+              <AdminInfoItem label="归组 Task ID">
+                {entry.groupTaskId.trim()}
+              </AdminInfoItem>
+            ) : null}
            <AdminInfoItem label="Object Key">
              {entry.objectKey || '-'}
            </AdminInfoItem>
@@ -988,6 +1096,29 @@ function mergeAssetEntries(
  );
 }

+function editorAssetListQueryKey(
+  token: string,
+  query: AdminEditorAssetListQuery,
+) {
+  return JSON.stringify([
+    token.trim(),
+    query.ownerUserId?.trim() || null,
+    query.keyword?.trim() || null,
+    query.createdAfter?.trim() || null,
+    query.createdBefore?.trim() || null,
+    query.limit ?? null,
+  ]);
+}
+
+function isAbortError(error: unknown) {
+  return (
+    typeof error === 'object' &&
+    error !== null &&
+    'name' in error &&
+    error.name === 'AbortError'
+  );
+}
+
 function dateInputToStartRfc3339(value: string) {
  return value ? `${value}T00:00:00+08:00` : null;
 }
@@ -363,7 +363,7 @@ button:disabled {

 .admin-dashboard-retention-grid {
  display: grid;
-  grid-template-columns: repeat(2, minmax(0, 1fr));
+  grid-template-columns: repeat(3, minmax(0, 1fr));
  gap: 14px;
 }

@@ -2120,6 +2120,14 @@ button:disabled {
    grid-template-columns: repeat(2, minmax(0, 1fr));
  }

+  .admin-dashboard-retention-card:nth-child(odd) {
+    border-left: 0;
+  }
+
+  .admin-dashboard-retention-card:nth-child(n + 3) {
+    border-top: 1px solid #ead8ca;
+  }
+
  .admin-field-compact {
    max-width: none;
  }
@@ -58,6 +58,7 @@ AUTH_REFRESH_COOKIE_SECURE=false
 GENARRATIVE_SPACETIME_SERVER_URL=http://spacetimedb:3101
 GENARRATIVE_SPACETIME_DATABASE=genarrative-loadtest
 GENARRATIVE_SPACETIME_TOKEN=
+# HTTP 角色使用 8 条无 read-model 订阅的调用连接，并额外创建 1 条共享缓存读连接。
 GENARRATIVE_SPACETIME_POOL_SIZE=8
 GENARRATIVE_SPACETIME_PROCEDURE_TIMEOUT_SECONDS=45

@@ -69,6 +69,7 @@ GENARRATIVE_SPACETIME_DATABASE=genarrative-prod
 GENARRATIVE_SPACETIME_TOKEN=
 # 只保存受保护文件路径；不要把 bootstrap secret 明文写入生产 env。
 GENARRATIVE_SPACETIME_RUNTIME_SERVICE_BOOTSTRAP_SECRET_FILE=/var/lib/genarrative/spacetime/runtime-service-bootstrap-secret.txt
+# HTTP 角色使用 8 条无 read-model 订阅的调用连接，并额外创建 1 条共享缓存读连接。
 GENARRATIVE_SPACETIME_POOL_SIZE=8
 GENARRATIVE_SPACETIME_PROCEDURE_TIMEOUT_SECONDS=45

@@ -156,8 +157,18 @@ GENARRATIVE_DATABASE_BACKUP_OSS_BUCKET=
 GENARRATIVE_DATABASE_BACKUP_OSS_ENDPOINT=oss-cn-shanghai.aliyuncs.com
 GENARRATIVE_DATABASE_BACKUP_OSS_PREFIX=database-backups
 GENARRATIVE_DATABASE_BACKUP_KEEP_LOCAL=false
+# 可选：files 为逐文件 CAS + catalog，不生成 tar.gz；archive 保留旧全量压缩包兼容行为。
+GENARRATIVE_DATABASE_BACKUP_STORAGE_FORMAT=archive
+# files 模式并行 PUT/HEAD 数量，必须为 1-64；默认 16。
+GENARRATIVE_DATABASE_BACKUP_FILES_CONCURRENCY=16
+# 可选：仅限制备份进程上传总带宽，单位 bytes/s；为空或 0 表示不限速。
+GENARRATIVE_DATABASE_BACKUP_UPLOAD_MAX_BYTES_PER_SECOND=
 # 可选：显式要求备份工作目录所在文件系统至少保留的可用空间；为空时按数据目录大小 + 安全余量估算。
 GENARRATIVE_DATABASE_BACKUP_MIN_FREE_BYTES=
+# archive history 模式持久化已验真 full baseline 与追加批次；files 模式改用 work-dir 下的 files state。
+GENARRATIVE_DATABASE_BACKUP_BASELINE_STATE=/var/lib/genarrative/database-backups/genarrative-prod-history-state.json
+# 仅 archive history 首次从 uploadStatus=uploaded 的 full manifest 初始化 state 时设置；初始化后可留空。
+GENARRATIVE_DATABASE_BACKUP_BASELINE_MANIFEST=
 # 可选：定时 / publish 前备份使用独立最小权限 AccessKey；为空时回退 ALIYUN_OSS_ACCESS_KEY_*。
 GENARRATIVE_DATABASE_BACKUP_OSS_ACCESS_KEY_ID=
 GENARRATIVE_DATABASE_BACKUP_OSS_ACCESS_KEY_SECRET=
@@ -0,0 +1,3 @@
+[Service]
+ExecStart=
+ExecStart=/usr/bin/node -- /opt/genarrative/current/scripts/database-backup-to-oss.mjs --env-file /etc/genarrative/api-server.env --storage-format files --mode history --work-dir /var/lib/genarrative/database-backups/files-history
@@ -969,7 +969,7 @@
          "Editor Images"
        ],
        "operationId": "generateExternalEditorIconSpritesheet",
-        "summary": "按规范图生成并拆分图标素材",
+        "summary": "按规范图生成图标 spritesheet 并尝试拆分",
        "security": [
          {
            "ExternalApiKey": []
@@ -987,7 +987,7 @@
        },
        "responses": {
          "200": {
-            "description": "图标 spritesheet、切片结果与落库资源",
+            "description": "图标 spritesheet、实际切片结果、可选非阻断告警与落库资源",
            "content": {
              "application/json": {
                "schema": {
@@ -1017,7 +1017,7 @@
          "Editor Images"
        ],
        "operationId": "extractExternalEditorUiDesignAssets",
-        "summary": "从 UI 设计图拆分素材",
+        "summary": "从 UI 设计图生成素材 spritesheet 并尝试拆分",
        "security": [
          {
            "ExternalApiKey": []
@@ -1035,7 +1035,7 @@
        },
        "responses": {
          "200": {
-            "description": "UI 设计图素材 spritesheet、切片结果与落库资源",
+            "description": "UI 设计图素材 spritesheet、实际切片结果、可选非阻断告警与落库资源",
            "content": {
              "application/json": {
                "schema": {
@@ -2737,7 +2737,27 @@
            "type": "string"
          },
          "model": {
-            "type": "string"
+            "type": "string",
+            "description": "支持 gpt-image-2、gemini-3.1-flash-image-preview、nanobanana2、nano-banana。"
+          },
+          "aspectRatio": {
+            "type": "string",
+            "enum": [
+              "1:1",
+              "4:3",
+              "3:2",
+              "2:3",
+              "9:16",
+              "16:9"
+            ]
+          },
+          "imageSize": {
+            "type": "string",
+            "enum": [
+              "0.5K",
+              "1K",
+              "2K"
+            ]
          },
          "referenceImageSrcs": {
            "type": "array",
@@ -2849,6 +2869,17 @@
              }
            ],
            "description": "当请求携带 canvasCompletion 且服务端成功写入画布布局时返回最新项目快照。"
+          },
+          "warning": {
+            "anyOf": [
+              {
+                "$ref": "#/components/schemas/EditorGenerationWarning"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "生成成功但后处理降级时返回的非阻断告警。"
          }
        }
      },
@@ -3090,6 +3121,25 @@
        },
        "additionalProperties": false
      },
+      "EditorGenerationWarning": {
+        "type": "object",
+        "required": [
+          "code",
+          "reason"
+        ],
+        "properties": {
+          "code": {
+            "type": "string",
+            "const": "postprocess-failed-source-preserved",
+            "description": "透明背景处理最终失败并保留 provider 原图时的稳定原因码。"
+          },
+          "reason": {
+            "type": "string",
+            "description": "可直接展示给调用方的非阻断告警原因。"
+          }
+        },
+        "additionalProperties": false
+      },
      "EditorIconSpritesheetGenerationResponse": {
        "type": "object",
        "required": [
@@ -3130,7 +3180,7 @@
                "type": "null"
              }
            ],
-            "description": "图集已成功持久化，但自动拆分未完成时返回；此时 iconImageSrcs 为空，调用方仍应使用整张图集。"
+            "description": "图集已成功持久化，但自动拆分未完成时返回；此时 iconImageSrcs 为空，调用方仍应使用整张图集。与通用 warning 互斥。"
          },
          "prompt": {
            "type": "string"
@@ -3184,7 +3234,24 @@
              }
            ],
            "description": "当请求携带 canvasCompletion 且服务端成功写入画布布局时返回最新项目快照。"
+          },
+          "warning": {
+            "anyOf": [
+              {
+                "$ref": "#/components/schemas/EditorGenerationWarning"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "透明背景处理最终失败、provider 原图作为主结果时返回的非阻断告警。与 sliceWarning 互斥。"
          }
+        },
+        "not": {
+          "required": [
+            "warning",
+            "sliceWarning"
+          ]
        }
      },
      "EditorCharacterAnimationGenerationRequest": {
@@ -37,6 +37,65 @@
 - 影响范围：`server-rs/crates/platform-matting`、阿里云抠图冒烟示例、后端架构与开发运维文档；不改变 api-server DTO、动作拆帧、BgFilter 或业务降级契约。
 - 验证方式：`cargo test -p platform-matting --manifest-path server-rs/Cargo.toml`、`cargo check -p api-server --manifest-path server-rs/Cargo.toml`，并用真实图片运行 `segment_smoke`，确认授权上传 host 来自动态上海 OSS 且 `SegmentCommonImage` 成功返回。
 - 关联文档：`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`、阿里云“通用图像分割”与“文件 URL 处理”官方文档。
+## 2026-07-15 角色动作 BgFilter 请求超时按帧数扩展
+
+- 背景：角色动作全部序列帧会并发进入 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`、后端架构、开发运维和图片画布专题文档。
+- 验证方式：运行角色动作超时公式、BgFilter request override 与逐帧流水线定向测试，执行 `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-05-15.md`、`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`。
+
+## 2026-07-15 手动复杂去背景复用 BgFilter 单次重试
+
+- 背景：图片画布手动去背景已经改用 BgFilter `background_mode=complex`，但 worker 仍只发送一次上游请求，短暂网络抖动会直接让任务失败。
+- 决策：手动去背景的 complex 请求复用现有 `EDITOR_BGFILTER_RETRY_COUNT=1`，首次请求失败后立即重试一次，两次都失败仍返回最终错误；本次不把手动 complex 接入标准纯色背景链路的阿里云 / 本地兜底，也不改变 flat 路径的熔断状态。
+- 影响范围：图片画布手动去背景 worker、BgFilter complex 请求日志和 api-server 定向测试。
+- 验证方式：运行 `cargo test -p api-server editor_manual_background_removal_retries_once --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/project-memory/shared-memory/decision-log.md`、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`。
+
+## 2026-07-14 手动去背景迁移到 BgFilter complex 模式
+
+- 背景：图片画布手动“去除背景”此前单独代理 BiRefNet 服务；BgFilter 已增加 `background_mode=complex`，可直接处理非纯色背景，继续保留独立服务会形成重复的上游、配置和错误处理链路。
+- 决策：`POST /api/editor/images/background-removals` 保持前端与 BFF 契约不变，worker 改用现有 BgFilter 地址、token、超时和共享 HTTP client。multipart 提交图片文件、`background_mode=complex`、`seg_model=birefnet` 与 `cross_check=off`，不提交 `screen_color`。标准纯色背景的角色形象、图标 spritesheet、UI 素材提取和角色动作逐帧抠图继续使用 `background_mode=flat`。删除独立 BiRefNet base URL / timeout 配置；旧 `GENARRATIVE_EDITOR_BACKGROUND_REMOVAL_TOKEN` 仅作为 `GENARRATIVE_EDITOR_BGFILTER_TOKEN` 的兼容回退别名。
+- 影响范围：图片画布手动去背景 worker、BgFilter HTTP 协议、api-server 配置、资源元数据、前端 provider 展示和相关文档。
+- 验证方式：运行 api-server BGFilter / 手动去背景定向测试、前端 editorProjectClient / 画布 workflow 定向测试、`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/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。
+
+## 2026-07-13 外部生成任务持久化真实执行阶段
+
+- 背景：图片画布任务列表此前把所有 `running` 任务固定映射为“正在生成”，角色生图、图标/UI spritesheet、角色动作和手动去背景进入抠图后仍无法展示“正在处理”；前端按耗时推断阶段会产生新的非正式业务真相。
+- 决策：不新增 DB 表，在既有 `external_generation_job` 与 `external_generation_job_summary` 末尾追加带默认值的可选 `phase`。worker claim 时写 `generating`；角色生图、图标 spritesheet、UI 素材提取在调用 BgFilter 前，角色动作在视频生成返回并开始抽帧/逐帧抠图前，手动去背景在执行开始时，通过 `job_id + worker_id + lease_token` 保护的 procedure 写 `processing`。phase procedure 用结构化结果区分 `LeaseFencingRejected` 与 `OtherRejected`；api-server 对 `LeaseFencingRejected` 立即终止，对 `OtherRejected` 以及 SDK 的 `Procedure` / `Runtime` 错误不重试，仅对 `Build` / `ConnectDropped` / `Timeout` 在同一 job attempt 内重试 `1` 次。编辑器 job 固定 `max_attempts=1`，第二次传输失败后进入 `failed`，不回 `pending`、不重新调用 provider，也不按错误文案猜测拒绝类型。BFF 将 `running + processing` 映射为“正在处理”，其它 `running`（含旧数据 `phase=None`）映射为“正在生成”；前端只展示后端投影。
+- 影响范围：`external_generation_job`、`external_generation_job_summary`、SpacetimeDB procedure / typed client / bindings、图片画布生成 worker、任务列表 BFF 与相关文档。
+- 验证方式：运行 `npm run spacetime:generate`、`npm run check:spacetime-schema`、外部生成 module/client/api-server 定向测试、`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/technical/【后端架构】外部生成Worker化方案-2026-06-03.md`、`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`。
+
+## 2026-07-13 角色动作逐帧开启 BgFilter cross-check
+
+- 背景：角色动作逐帧抠图此前为减少额外推理开销固定传 `cross_check=off`，但动作帧同样需要保留发丝、镂空和运动边缘质量。
+- 决策：角色动作逐帧 BgFilter 请求固定显式传 `cross_check=on`，与角色形象保持一致；图标 spritesheet 和 UI 设计图素材提取继续固定传 `off`。该策略仍属于后端内部供应商参数，不进入前端或外部 OpenAPI。
+- 影响范围：`server-rs/crates/api-server/src/editor_project.rs`、`server-rs/crates/api-server/src/character_animation_assets.rs`、后端架构文档和图片画布技术文档。
+- 验证方式：运行 `cargo test -p api-server editor_bgfilter_cross_check --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server editor_character_animation_frames_use_three_stage_matting_fallback --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/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`。
+
+## 2026-07-13 角色动作 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`、后端架构文档和图片画布技术文档。
+- 验证方式：运行 `cargo test -p api-server editor_bgfilter_retries_once_before_fallback --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server editor_character_animation_frames_use_three_stage_matting_fallback --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server editor_canvas_screen_background_generation_uses_bgfilter_postprocess --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/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`。
+## 2026-07-16 SpacetimeDB 备份采用逐文件基线、CAS 增量与安全历史清理
+
+- 背景：SpacetimeDB standalone 2.6.0 不自动删除已被 snapshot 覆盖的历史 commitlog 与旧 snapshot；反复压缩整个 `/stdb` 会重复占用磁盘、停机和 OSS 带宽。上游 issue #5542 的 contributor 明确说明，不触碰最新 snapshot 与重启所需 commitlog suffix 时，可在运行中移动或删除这些历史文件。
+- 决策：统一脚本新增 `--storage-format files`，完整基线递归保留目录、文件和 data-dir 内部相对符号链接，普通文件按 SHA-256 上传为不可变 CAS 对象，catalog 记录目录、路径、长度、SHA、对象 key 与相对链接目标；绝对或越界链接拒绝备份。相同内容不重复 PUT，后续 full 扫描只上传新增或变化内容，不再生成 tar.gz。旧 `archive` 路径保留兼容。full 必须从停库目录或已验证的冻结副本生成，不能把在线跨文件扫描称为一致时点备份。
+- history 继续按 replica 计算安全边界：只接受完整、未锁定且含同 offset `.snapshot_bsatn` 的 snapshot，保留跨越最新 snapshot 的边界 segment 及全部后缀。旧 segment 对和旧 snapshot 被递归映射为单文件 CAS 对象；对象、history catalog、full baseline catalog、候选 fingerprint 与当前边界全部验真后才删除源文件。同库执行用 work-dir PID lock 互斥。
+- OSS 固定恢复入口为 `<prefix>/<database>/latest.json`。CAS 文件和 full/history catalog 保持不可变；latest pointer 只保存最新 full catalog 与已发布 history catalog 的 object key、长度和 SHA，不包含主机绝对路径或文件内容。每次 state 变化先验真全部引用 catalog，再覆盖上传并 HEAD 验真 latest pointer，成功后才落本地 state；history 还必须在 pointer 成功后才允许删除源文件。全新机器可仅凭 bucket、database、prefix 与 OSS 凭据自动下载 pointer 和 full catalog。
+- dev 带宽不足时，允许把已冻结的 dev 基线经 `10.2.0.10 -> 10.2.4.16` 内网 rsync 到 release 独立 staging，再用 release 出口上传 dev bucket；staging 不得指向 release `/stdb`，不得停止或修改 release 服务，传输凭据必须临时创建并在演练后移除。catalog 不记录 staging 绝对路径，files state 可回传 dev 继续 history。
+- 恢复边界：恢复时默认从 OSS `latest.json` 自动定位 full catalog，创建目录并按相对路径下载每个对象、逐文件校验长度与 SHA；本地 state 只用于备份续跑，不再是异机恢复前置条件。远程 dev 已完成真实 OSS、清理、重启和异机隔离恢复演练；release timer 与 publish 前备份继续保持原行为。
+- systemd 接线：主 service 保持 `archive-full`。Server-Provision 新增默认值为 `archive-full` 的 `DATABASE_BACKUP_PROFILE`；dev 或 release 显式选择 `files-history` 时，必须为各自主机指定独立 work-dir，并先用 current release 脚本执行 history dry-run，确认已有 full state 后才安装仓库托管 drop-in，并删除现场手写旧 drop-in。切回默认 profile 必须删除所有 history 覆盖。
+- 影响范围：`scripts/database-backup-to-oss.mjs`、备份门禁、生产 env 示例、systemd 模板、Server-Provision、SpacetimeDB 运维与恢复流程；release timer 可在独立 baseline 验证后显式选择 profile，publish 前备份是否切换仍需单独决策。
+- 验证方式：`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-14 后台账号采用 owner 引导账号与一级 Tab 实时授权

@@ -57,8 +116,9 @@
 ## 2026-07-13 图片画布多产物生成任务必须保存全部可恢复产物

 - 背景：角色形象、图标 spritesheet 和 UI 素材提取会先得到带纯色背景的原图，再执行抠图或拆分；图片修改会先得到模型对齐尺寸的原始输出，角色动作会先得到绿幕预览视频，再抽帧和抠图。此前部分原始产物只登记到 OSS，或者要等后处理成功后才进入项目资源，用户无法在失败后找回已经生成成功的内容。
- 决策：凡一次资产生成任务产生多个具有独立复用价值的产物，后端必须把上游已返回的中间产物写入 OSS、`asset_object`、项目资源和账号素材库，再执行抠图、抽帧或拆分；未指定素材文件夹时进入默认“项目”文件夹。角色形象、图标 spritesheet 和 UI 素材提取同时保留纯色背景原图与透明后处理结果。普通图片和图片修改的纯尺寸变换不属于独立产物：provider 回图保留在内存，变换成功只上传变换结果，变换失败只上传 provider 原图，整个流程只写一次 OSS 并只创建一个素材，不能制造重复“原始输出”。`nanobanana2` 使用标量清晰度档位和独立比例，保留 provider 输出尺寸，不按 `WIDTHxHEIGHT` 解析。角色动作把绿幕预览视频作为一个可复用素材保存，逐帧源图继续留在同一任务 OSS 路径，不把 32 至 48 帧逐张灌入素材库。去背景、音频等没有独立上游中间产物的任务不制造重复副本。
- 画布、成本与降级：有项目上下文的图片多产物继续由同一次 `canvasCompletion` 写入权威画布快照，生成器 `generatedLayerId` 锚定主后处理结果。图标和 UI 图集自动拆分是 best-effort；识别或切片持久化失败仍完成整张透明图集，并在 inline、队列轮询和刷新后任务列表中提示非阻断 warning，不得借用失败错误字段。provider 原图或角色动作预览视频承载该任务的模型生成成本，抠图、逐帧处理、透明图集和切片等后处理派生产物的 `generation_cost_mud_points = 0`，避免把生图成本误显示成抠图成本；所有中间产物沿用所属任务的真实 `asset_kind`，角色原图仍为 `character`、图标和 UI 图集原图仍为 `icon-spritesheet`、角色动作预览仍为 `character-animation`，不得再写新的“原图类型”。后台素材查询按任务分页，最终产物作为父行并显示任务总成本，每个中间产物作为可展开的独立子行显示阶段生成器和阶段成本。扣费确认边界保持为 provider 成功，OSS、尺寸恢复和画布回填不延长退款保护。
+- 决策：凡一次资产生成任务产生多个具有独立复用价值的产物，后端必须把上游已返回的中间产物写入 OSS、`asset_object`、项目资源和账号素材库，再执行抠图、抽帧或拆分；未指定素材文件夹时进入默认“项目”文件夹。角色形象、图标 spritesheet 和 UI 素材提取在透明背景处理正常成功时同时保留纯色背景原图与透明后处理结果；透明背景处理最终失败时只保留已经持久化的 provider 原图，并按下一条降级规则收口。普通图片和图片修改的纯尺寸变换不属于独立产物：provider 回图保留在内存，变换成功只上传变换结果，变换失败只上传 provider 原图，整个流程只写一次 OSS 并只创建一个素材，不能制造重复“原始输出”。`nanobanana2` 使用标量清晰度档位和独立比例，保留 provider 输出尺寸，不按 `WIDTHxHEIGHT` 解析。角色动作把绿幕预览视频作为一个可复用素材保存，逐帧源图继续留在同一任务 OSS 路径，不把 32 至 48 帧逐张灌入素材库。去背景、音频等没有独立上游中间产物的任务不制造重复副本。
+- 画布、成本与降级：有项目上下文的图片多产物继续由同一次 `canvasCompletion` 写入权威画布快照，正常成功时生成器 `generatedLayerId` 锚定主后处理结果。角色形象、图标 spritesheet 或 UI 素材提取已经保存 provider 原图、但透明背景处理最终失败时，任务以 `completed + warning` 收口，原图作为唯一主图完成画布占位；不写入不存在的透明处理图，图标和 UI 也不继续拆分。透明处理成功后的图标和 UI 图集自动拆分仍是 best-effort；识别或切片持久化失败继续完成整张透明图集，并在 inline、队列轮询和刷新后任务列表中提示非阻断 warning，不得借用失败错误字段。provider 原图或角色动作预览视频承载该任务的模型生成成本，抠图、逐帧处理、透明图集和切片等后处理派生产物的 `generation_cost_mud_points = 0`，避免把生图成本误显示成抠图成本；所有中间产物沿用所属任务的真实 `asset_kind`，角色原图仍为 `character`、图标和 UI 图集原图仍为 `icon-spritesheet`、角色动作预览仍为 `character-animation`，不得再写新的“原图类型”。后台素材查询按任务分页，最终产物作为父行并显示任务总成本，每个中间产物作为可展开的独立子行显示阶段生成器和阶段成本。扣费确认边界保持为 provider 成功，OSS、尺寸恢复和画布回填不延长退款保护。
+- 2026-07-16 告警契约补充：inline / external v1 继续返回结构化原始诊断；queue 有意把通用 `warning` 或 `sliceWarning` 归一为展示就绪字符串，通用 `warning.reason` 原样保留，`sliceWarning.reason` 由 worker 添加“图集已生成，但自动拆分未完成：”前缀，摘要与 BFF 原样投影，Web 直接展示。历史值保留写入时快照，不按新格式回填或推断；该内部字符串契约通过 API/worker 与 Web 同一维护窗口、同版本发布收口，不增加混部兼容层。
 - 影响范围：`server-rs/crates/api-server/src/editor_project.rs`、`character_animation_assets.rs`、外部生成任务摘要、图片画布完成快照、账号素材库和前端生成提示。
 - 验证方式：覆盖中间产物登记先于后处理、默认素材文件夹、图集拆分降级、inline / queue warning 和主结果锚定的定向测试，并运行 `cargo check -p api-server --manifest-path server-rs/Cargo.toml`、`npm run check:spacetime-schema`、前端定向测试、`npm run check:encoding`、`git diff --check`。
 - 关联文档：`docs/【编辑器】生成类面板Lovart统一改造方案-2026-06-17.md`、`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`。
@@ -79,6 +139,14 @@
 - 验证方式：`npm run spacetime:generate`、`npm run check:spacetime-schema`、钱包定向 Rust 测试、个人中心定向前端测试、`npm run typecheck`、`npm run check:encoding`、`git diff --check`。
 - 关联文档：`docs/【项目基线】当前产品与工程约束-2026-05-15.md`、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`。

+## 2026-07-11 BgFilter 交叉模型否决用于角色形象与角色动作
+
+- 背景：新版 BgFilter 的 `cross_check` 默认开启，会额外运行 HR-matting 第二意见模型；角色形象与角色动作序列帧需要保留发丝、镂空和运动边缘质量；图标 spritesheet 和 UI 素材提取不需要承担这部分额外推理开销。
+- 决策：api-server 调用 BgFilter 时必须显式发送 multipart 字段 `cross_check`，不依赖服务端默认值。角色形象生成和角色动作逐帧去背固定传 `on`；图标 spritesheet 生成和 UI 设计图素材提取固定传 `off`。角色动作逐帧去背与三条静态生图路线复用同一条 `BgFilter → 阿里云通用抠图 → 本地键色` 降级链和同一 BgFilter 熔断器。该字段是后端内部供应商策略，不进入前端请求或外部 OpenAPI。
+- 影响范围：`server-rs/crates/api-server/src/editor_project.rs`、`server-rs/crates/api-server/src/character_animation_assets.rs`、图片画布 BgFilter 调用文档。
+- 验证方式：运行 `cargo test -p api-server editor_bgfilter_cross_check --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server editor_canvas_screen_background_generation_uses_bgfilter_postprocess --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server editor_character_animation_frames_use_three_stage_matting_fallback --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/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`。
+
 ## 2026-07-11 SpacetimeDB 工具链统一升级到 2.6.0

 - 背景：生产数据副本验证已使用 2.6.0 standalone，而仓库 Rust crate、本地 CLI、生成 bindings、容器与 server provision 仍锁定 2.5.0 或更早版本，继续混用会增加 BSATN / procedure 返回值与发布产物错配风险。
@@ -114,7 +182,7 @@
 ## 2026-07-09 角色动作视频生成背景色统一为多色自动决策 + 阿里云抠帧

 - 背景：角色动作视频抽帧过去固定 legacy `#00FF00` 绿幕 + 本地 `editor_green_screen`，与生图链路的多色自动决策不一致；实测出现背景色与前景 / 皮肤撞色（蓝撞蓝、桃 / 黄撞肤色）以及图生视频背景变白的问题。
- 决策：角色动作视频背景色与生图统一。`screenColor=auto` 时由视觉 LLM（`gpt-5-mini`，Responses 协议、`reasoning_effort=low`，`max_tokens=1024`）读源角色图自动决策，并经硬过滤器（Lab 危险质量 + 皮肤专属三判据：ΔE 距离 / 色调投影 / RGB 分离）剔除与前景及皮肤撞色的候选，手动 hex 仍尊重用户选择；透明源角色图在提交 Ark 图生视频前先合成到选定背景色实色，使视频背景确定性等于抠图键色。抽帧后逐帧优先走阿里云通用抠图，失败降级本地 `editor_green_screen` 键色兜底（按生成时选定的背景色，而非固定 `#00FF00`）。BgFilter 与阿里云抠图失败均写入 `external_api_call_failure` 失败审计。调色板新增中明度低饱和「灰竹绿 `#A0BBA0`」补齐冷区绿色段。
+- 决策：角色动作视频背景色与生图统一。`screenColor=auto` 时由视觉 LLM（`gpt-5-mini`，Responses 协议、`reasoning_effort=low`，`max_tokens=1024`）读源角色图自动决策，并经硬过滤器（Lab 危险质量 + 皮肤专属三判据：ΔE 距离 / 色调投影 / RGB 分离）剔除与前景及皮肤撞色的候选，手动 hex 仍尊重用户选择；透明源角色图在提交 Ark 图生视频前先合成到选定背景色实色，使视频背景确定性等于抠图键色。抽帧后逐帧优先走 BgFilter（固定 `seg_model=birefnet`、`cross_check=on`），失败依次降级阿里云通用抠图和本地 `editor_green_screen` 键色兜底（按生成时选定的背景色，而非固定 `#00FF00`）。BgFilter 与阿里云抠图失败均写入 `external_api_call_failure` 失败审计。调色板新增中明度低饱和「灰竹绿 `#A0BBA0`」补齐冷区绿色段。
 - 影响范围：`server-rs/crates/api-server/src/character_animation_assets.rs`、`editor_screen_background_decision.rs`、`editor_screen_background_filter.rs`（新增硬过滤模块）、`editor_green_screen.rs`（调色板）、`external_api_audit.rs`、`llm_model_routing.rs`、图片画布 MVP 与后端数据契约文档。
 - 验证方式：`cargo test -p api-server editor_screen_background character_animation --manifest-path server-rs/Cargo.toml`、`cargo check -p api-server --manifest-path server-rs/Cargo.toml`、真机对源角色图跑视觉决策与候选危险度表、抽帧后采样序列帧背景色确认落在冷区安全集。
 - 关联文档：`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`、`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`。
@@ -199,6 +267,7 @@
 - 决策：`陶泥儿精选` 的公开事实改为独立 `editor_showcase_asset` 审核表。生成素材默认不公开；用户在账号级素材库对 `sourceType="generated"` 且有媒体内容的素材提交审核，后端快照素材信息并写入 `pending`。后台审核通过后写入 `approved`，但默认 `display_enabled=false` 且 `showcase_category=null`，运营可按前台具体 Tab 手动设置分类并开启展示；未设置分类的素材展示开启后进入前台“全部”，但不进入角色 / UI / 音乐 / 美宣具体分类。审核通过时按 `generation_cost_mud_points` 返还 50% 泥点；拒绝后写入 `rejected`。公开接口 `GET /api/editor/showcase/resources` 返回已通过、展示开启且媒体非空的快照，按通过时间和 `showcaseId` 倒序分页，并可携带后台配置的固定活动卡。旧 `editor_project_resource.public_showcase_enabled` 和旧 PATCH 接口只保留兼容，不再驱动精选公开。
 - 影响范围：`server-rs/crates/spacetime-module/src/editor_project_storage.rs`、`spacetime-client` 绑定与 mapper、`api-server` 编辑器和后台路由、admin-web 精选审核页、素材库右键菜单、`/creation` 精选瀑布流、图片画布文档和后端表目录。
 - 验证方式：运行 `npm run spacetime:generate`、`npm run check:spacetime-schema`、`cargo check --manifest-path server-rs/Cargo.toml -p spacetime-module -p spacetime-client -p api-server`、前端 / 后台 typecheck 与精选相关组件测试，确认默认不公开、提交后 pending、审核通过后展示和返还、展示开关与点赞生效。
+- 后续修正：精选批准、确定性返还流水和返还完成标记必须由同一个 SpacetimeDB procedure 在单事务内落地，失败时不得先留下 `approved`；已公开精选私有对象通过同 owner 的精确 `assetObjectId` / `objectKey` 派生匿名读取授权，不把 `generated-*` 前缀整体公开。
 - 关联文档：`docs/【玩法创作】创作主页与项目入口改版计划-2026-06-18.md`、`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`。

 ## 2026-07-03 外部编辑器 API 生成默认写入画布与素材库
@@ -365,7 +434,7 @@
 ## 2026-06-18 图片画布 UI 设计图提取素材保留图集

 - 背景：UI 设计图需要从成图中继续抽取可复用独立素材；原图标素材生成只把拆分后的图标放入画布，spritesheet 原图没有保留，后续追溯和二次切图不方便。
- 决策：`assetKind="ui-design"` 图层浮动工具栏新增 `提取素材`，点击后先进入红框素材框选编辑态，默认矩形框选，并支持椭圆框选和画笔自由框选。至少存在一个框选区域后才能提交；前端把红色轮廓绘入原 UI 设计图并将合成图作为 `/api/editor/ui-designs/assets/extractions` 的参考图。后端固定 `gpt-image-2` 和纯色背景素材提取提示词，返回结构复用图标 spritesheet 响应。UI 提取把 spritesheet 图集作为 `assetKind="icon-spritesheet"` 图层放到画布，再放拆分后的 `assetKind="icon"` 素材。2026-07-03 起，UI 提取的纯色背景由 `screenColor` 选择并经 BgFilter 透明化。2026-07-13 起，图标素材生成先把带背景原图和透明 spritesheet 同时写入项目资源、账号素材库并回填画布，未指定文件夹时落默认“项目”文件夹，再 best-effort 按 alpha 连通域拆分独立图标；拆分失败不改变生成成功状态，响应以空 `iconImageSrcs` 和结构化 `sliceWarning` 返回原因，用户可从图集工具栏手动重试。手动拆分不计费，限制单边 `4096`、总像素 `2048×2048`、最多 `64` 个切片，所有切片用 `sourceResourceId` 指向透明图集。`icon-spritesheet` 图集继续显示并允许快速编辑，只有拆分后的 `assetKind="icon"` 单图标隐藏并拒绝快速编辑；工具栏、右键菜单、打开流程和提交兜底必须共用同一判定。本条新决策取代“图标素材生成只保留图集”的旧口径。
+- 决策：`assetKind="ui-design"` 图层浮动工具栏新增 `提取素材`，点击后先进入红框素材框选编辑态，默认矩形框选，并支持椭圆框选和画笔自由框选。至少存在一个框选区域后才能提交；前端把红色轮廓绘入原 UI 设计图并将合成图作为 `/api/editor/ui-designs/assets/extractions` 的参考图。后端固定 `gpt-image-2` 和纯色背景素材提取提示词，返回结构复用图标 spritesheet 响应。透明背景处理正常成功时，UI 提取把透明 spritesheet 图集作为 `assetKind="icon-spritesheet"` 图层放到画布，再放拆分成功的 `assetKind="icon"` 素材。2026-07-03 起，UI 提取的纯色背景由 `screenColor` 选择并经 BgFilter 透明化。2026-07-13 起，图标素材生成在透明背景处理正常成功时把带背景原图和透明 spritesheet 同时写入项目资源、账号素材库并回填画布，未指定文件夹时落默认“项目”文件夹，再 best-effort 按 alpha 连通域拆分独立图标；拆分失败不改变生成成功状态，响应以空 `iconImageSrcs` 和结构化 `sliceWarning` 返回原因，用户可从图集工具栏手动重试。2026-07-16 起，透明背景处理最终失败时只把已经持久化的 provider 原图作为唯一主图放入画布，以 `completed + warning` 收口，不创建透明图集，也不继续拆分。手动拆分不计费，限制单边 `4096`、总像素 `2048×2048`、最多 `64` 个切片，所有切片用 `sourceResourceId` 指向透明图集。`icon-spritesheet` 图集继续显示并允许快速编辑，只有拆分后的 `assetKind="icon"` 单图标隐藏并拒绝快速编辑；工具栏、右键菜单、打开流程和提交兜底必须共用同一判定。本条新决策取代“图标素材生成只保留图集”的旧口径。
 - 影响范围：图片画布浮动工具栏、编辑器图片生成 BFF、`platform-image` 图集连通域拆分、画布图层类型和编辑器文档。
 - 验证方式：运行图片画布工具栏 / 图集落层 / 生成提交相关前端测试，`cargo test -p platform-image generated_asset_sheets --manifest-path server-rs/Cargo.toml`，以及 `cargo test -p api-server editor_ui_design_asset_extraction_prompt_is_fixed --manifest-path server-rs/Cargo.toml`。
 - 关联文档：`docs/【编辑器】画板UI设计图生成入口设计-2026-06-17.md`、`docs/【编辑器】画板图标素材生成入口设计-2026-06-15.md`。
@@ -1353,7 +1422,7 @@
 - 2026-06-07 追加：`GENARRATIVE_EXTERNAL_GENERATION_MODE` 使用 `queue|inline` 显式策略；生产和容器扩缩容验证保持 `queue`。本地开发若需要同步等待结果，应通过 `.env.local` 或本机环境显式配置为 `inline`，由 HTTP handler 复用同一 worker executor 直接返回 `completed`，不创建 `external_generation_job`，不支持 worker 动态扩缩容；脚本不得硬编码该策略。拼图写回 guard 字段改为可选，queue 路径仍必须完整校验 `job_id + worker_id + lease_token`；inline 路径只允许三项同时为空，半空 guard 仍拒绝。
 - 2026-06-11 追加：生产新增固定 `external-generation-controller` 进程角色和 `genarrative-external-generation-controller.service`。controller 只读取 `get_external_generation_queue_stats_and_return` 队列统计并管理 `genarrative-external-generation-worker@N.service`，不监听 HTTP、不执行外部生成任务；默认保留 `@1`，按 `claimable_pending + running_active + expired_running` 计算目标实例数，上限由 `GENARRATIVE_EXTERNAL_GENERATION_CONTROLLER_MAX_WORKERS` 控制，缩容需要连续空闲轮数且每轮只停最高编号一个实例。
 - 2026-07-08 追加：生产 worker/controller 作为轻量 SpacetimeDB 客户端运行，专属 env 示例默认 `GENARRATIVE_SPACETIME_POOL_SIZE=1`；非 HTTP 角色只保留 `external_generation_job` 队列窄订阅作为响应式唤醒信号，实际抢占和扩缩容判断仍走 SpacetimeDB procedure，且不再订阅 API 读模型连接池。worker/controller poll interval 只作为订阅失效、漏事件和 lease 过期这类时间条件的兜底，不作为正常领取任务的主路径。
- 2026-07-08 追加：worker lease 默认从 `3600s` 收短到 `600s`，普通 job 执行预算默认 `900s`，视频 / 角色动作等长 job 默认 `1800s`；预算到期后当前 worker 结束本次尝试、写失败 / 重试状态并释放 worker 槽位，若 SpacetimeDB 当时不可写则最多等到较短 lease 过期后重新领取，避免无进展续租无限延长。资产计费层对已扣费但 future 被取消的外部生成操作做异步补偿退款，避免超时取消绕过退款 outbox。
+- 2026-07-08 追加：worker lease 默认从 `3600s` 收短到 `600s`，普通 job 执行预算默认 `900s`，视频 / 角色动作等长 job 默认 `1800s`；预算到期后当前 worker 停止续租并释放 worker 槽位，但不取消已启动的业务 future，也不主动写失败 / 重试状态。在途写回由 lease fencing 仲裁：有效租约内照常完成，租约过期后任务可被重新认领，attempt 耗尽时由认领事务原子标记失败并结算退款，避免客户端取消与服务端写回发生竞态。
 - 影响范围：`server-rs/crates/spacetime-module/src/external_generation.rs`、`server-rs/crates/spacetime-client/src/external_generation.rs`、`server-rs/crates/api-server/src/external_generation_worker.rs`、`server-rs/crates/api-server/src/external_generation_worker_controller.rs`、`deploy/systemd/genarrative-external-generation-worker@.service`、`deploy/systemd/genarrative-external-generation-controller.service`、`deploy/env/external-generation-controller.env.example`、`scripts/deploy/production-api-deploy.sh`、`scripts/jenkins-server-provision.sh`、拼图 `compile_puzzle_draft`、拼图 `generate_puzzle_images`、拼图 `generate_puzzle_ui_background`、生产 env 模板和运维文档。
 - 验证方式：`npm run spacetime:generate`、`npm run check:spacetime-schema`、`npm run check:server-rs-ddd`、`cargo check -p api-server --manifest-path server-rs/Cargo.toml`，并在 queue 模式下用 `GENARRATIVE_PROCESS_ROLE=all npm run dev` smoke 至少一次 queued -> worker 完成链路；本地 inline 排查只确认不创建 `external_generation_job`。
 - 关联文档：`docs/technical/【后端架构】外部生成Worker化方案-2026-06-03.md`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`。
@@ -3161,8 +3230,9 @@
 ## 2026-06-19 编辑器角色形象回填改用通用抠图

 - 背景：画板编辑器里的 `生成角色形象` 属于编辑器图片生成链路，用户要求把“人物抠图”改成通用抠图方法，不再与 RPG / 资产工坊角色主图专用后处理绑定。
- 决策：仅 `/api/editor/images/generations` 中 `kind = "character"` 的编辑器角色形象回填改用 `platform-image::generated_asset_sheets` 通用绿幕 / 近白去背能力，并开启内部镂空检测；输出仍归一为透明 PNG。`character_visual_assets::try_apply_background_alpha_to_png` 继续服务 RPG 角色主图与 Big Fish 等“角色主图口径”调用者，本轮不改变这些链路。
+- 决策：仅 `/api/editor/images/generations` 中 `kind = "character"` 的编辑器角色形象回填改用 `platform-image::generated_asset_sheets` 通用绿幕 / 近白去背能力，并开启内部镂空检测；透明背景处理正常成功时输出归一为透明 PNG。`character_visual_assets::try_apply_background_alpha_to_png` 继续服务 RPG 角色主图与 Big Fish 等“角色主图口径”调用者，本轮不改变这些链路。
 - 2026-06-22 补充：所有明确设置绿幕用于后续抠图的 prompt 都必须固定写明 `#00FF00 / RGB(0,255,0)`，不能只写“纯绿色绿幕”或“接近 #00FF00”；编辑器角色图通用抠图额外开启暗绿 / 灰绿绿幕背景识别，只作为生成模型偏离标准亮绿时的兜底。该宽松识别只参与从画布边缘连通扩散出的背景清理，不参与全图断开绿色区域删除，避免误伤角色衣物或纹理。
+- 2026-07-16 补充：透明背景处理最终失败、但 provider 原图已持久化时，角色任务以 `completed + warning` 收口，provider 原图作为唯一主图放入画布，不创建透明处理图。
 - 影响范围：`server-rs/crates/api-server/src/editor_project.rs`、`docs/【编辑器】画板角色形象生成入口设计-2026-06-15.md`。
 - 验证方式：`cargo test -p api-server --manifest-path server-rs/Cargo.toml editor_character_image_general_cutout`、`cargo test -p platform-image --manifest-path server-rs/Cargo.toml generated_asset_sheet_muted_green_alpha_requires_explicit_option`、`cargo check -p api-server --manifest-path server-rs/Cargo.toml`、`npm run check:encoding`、`git diff --check`。

@@ -4134,3 +4204,19 @@
 - 留存口径：筛选范围内 `profile_dashboard_state.created_at` 的北京时间注册日构成 cohort；在精确 `D+1` / `D+7` 存在有效登录 user scope 日聚合即留存。观察日必须早于今天；D1、D7 分别返回留存人数、可观察人数和四舍五入后的基点率，按人数加权汇总，零分母前端显示 `-`。
 - 影响范围：SpacetimeDB Dashboard 聚合 procedure、`spacetime-client` facade、`/admin/api/dashboard` 与 shared contracts、`apps/admin-web` Dashboard 页面和运营文档。
 - 验证方式：SpacetimeDB 聚合与 api-server 定向 Rust 测试、Dashboard Vitest、`npm run admin-web:typecheck`、`npm run check:spacetime-schema`、`npm run check:spacetime-runtime-access`、`npm run check:encoding`、`git diff --check`，并用桌面 / 移动浏览器核对留存、日期、每日 UV、零值与滚动同步。
+
+## 2026-07-15 后台 Dashboard 增加新增用户付费率
+
+- 背景：Dashboard 已能展示筛选时段的新增用户数和 D1 / D7 留存，但缺少同一新增 cohort 的真实付费转化指标。
+- 决策：新增用户付费率的分母为筛选期内 `profile_dashboard_state.created_at` 归属的新增用户，分子为其中截至查询时至少有一笔 `profile_recharge_order.paid_at` 的去重用户；已退款仍代表曾发生付费转化，未支付订单不计。
+- 聚合边界：继续扩展仅 runtime service identity 可调用的 `get_admin_dashboard_stats_and_return` procedure，不新增持久化表或字段，前端只展示 BFF 返回的付费人数、新增用户数和基点率。
+- 验证方式：SpacetimeDB Dashboard 聚合测试、api-server admin 测试、Dashboard Vitest、`npm run admin-web:typecheck`、`npm run check:spacetime-schema`、`npm run check:spacetime-runtime-access`、`npm run check:encoding`、`git diff --check`，并用桌面 / 移动浏览器核对付费率卡片。
+
+## 2026-07-14 SpacetimeDB 调用池与缓存读连接分离
+
+- 背景：HTTP 角色原先在每个 `GENARRATIVE_SPACETIME_POOL_SIZE` 槽位首次建连时订阅同一批 read model；release 配置为 8 时会保存 8 份相同行缓存和 subscription handles，放大 api-server 内存。
+- 决策：`pool_size` 条连接只承接 procedure / reducer 调用并保持无订阅；HTTP 角色额外创建且只创建 1 条共享缓存读连接，全部 `read_after_connect` 读取统一路由到该连接。缓存连接只在应用 facade 中作为只读用途，不宣称 SDK 或 identity 具备连接级只读权限。
+- 并发与恢复：缓存读连接通过 `Arc` 共享，读取不占用调用池 permit，也不使用单槽租约串行化；只有首次初始化和 broken 后重建使用单飞锁。首次建连与全部订阅共用一次总超时预算；required subscriptions 全部 applied、optional 阶段连接仍未 broken 后才发布新连接，旧连接由在途读取自然释放。
+- 就绪边界：HTTP `/readyz` 同时验证调用池握手和缓存读连接；required subscription 失败必须不就绪。非 HTTP worker / controller 不创建缓存读连接，继续使用 1 条调用连接和各自的队列窄订阅。
+- 运维口径：`GENARRATIVE_SPACETIME_POOL_SIZE=8` 表示 8 条调用连接，HTTP 基础拓扑另加 1 条缓存读连接；外部生成和充值过期监听的独立窄订阅不计入该值。读模型行缓存从 8 份降为 1 份，但 SDK 空 table metadata、8 条调用 socket 和 runner 仍存在，不承诺总 RSS 等比例降为八分之一。
+- 验证方式：`cargo test -p spacetime-client --manifest-path server-rs/Cargo.toml --lib`、`cargo check -p api-server --manifest-path server-rs/Cargo.toml`、`npm run check:encoding`、`git diff --check`；发布后在 8 个调用槽暖机后对比 api-server cgroup memory / PSS，并确认 `/readyz` 与代表性 gallery、公开详情、创作入口和用户标签读取正常。
@@ -173,6 +173,19 @@ RAG 主要供 Agent 检索项目上下文，开发者仍按 `AGENTS.md`、`docs/

 ## 常用检查命令

+Rust 格式检查：
+
+```bash
+npm run check:rustfmt
+```
+
+仓库通过根目录 `rust-toolchain.toml` 固定 Rust `1.96.0` 和 `rustfmt` 组件，
+并通过 `rustfmt.toml` 固定 Edition 2024 格式口径。需要修复格式时运行：
+
+```bash
+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`。

 编码检查：
@@ -14,6 +14,14 @@
 - 关联：相关文件、文档、提交或 Issue
 ```

+## phase 上报的业务拒绝与传输失败不能共用字符串错误
+
+- 现象：provider 已经返回并保存原图，worker 上报 `processing` 时一次断连或超时就直接把任务判为失败；或者为了规避误杀而重试所有错误，导致 stale lease 的旧 worker 继续执行后处理。
+- 原因：phase procedure 的 lease / fencing 业务拒绝与 SDK 建连、断连、超时错误被压成同一种字符串错误，调用方无法可靠决定是否重试；按中文或 SDK 文案匹配会在错误文本变化后失效。
+- 处理：procedure 返回结构化 `LeaseFencingRejected` / `OtherRejected`，typed client 再把模块拒绝与 RPC 错误分开。`LeaseFencingRejected` 立即终止，`OtherRejected` 以及 SDK 的 `Procedure` / `Runtime` 错误不重试；只有 `Build` / `ConnectDropped` / `Timeout` 在同一 job attempt 内重试一次。编辑器 job 固定 `max_attempts=1`，第二次传输失败后进入 `failed`，不回 `pending`、不重新调用 provider。不得让 phase 上报错误落入“后处理失败保留原图”的降级分支。
+- 验证：分别覆盖 lease / fencing 拒绝、其它拒绝、建连、断连、超时和第二次失败，确认最多调用两次；同时断言角色、图标和 UI 的原图降级只包住透明背景处理，不包住 phase 上报。
+- 关联：`server-rs/crates/spacetime-module/src/external_generation.rs`、`server-rs/crates/spacetime-client/src/external_generation.rs`、`server-rs/crates/api-server/src/editor_project.rs`、`docs/technical/【后端架构】外部生成Worker化方案-2026-06-03.md`。
+
 ## 禁止 Data URL 持久化时不要漏掉异步任务 JSON

 - 现象：工程、素材、图层和元数据都已禁止 Data URL 后，服务器仍在生成高峰出现 SpacetimeDB / api-server 内存急剧膨胀甚至 OOM；读取少量正式生成任务也会造成远大于响应体的瞬时内存增长。
@@ -47,6 +55,14 @@
 - 验证：`cargo check -p spacetime-client --manifest-path server-rs/Cargo.toml`、`cargo check -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/editor_project.rs`、`server-rs/crates/api-server/src/admin.rs`。

+## 后台素材查询要在分页前归一用户、游标和派生任务
+
+- 现象：输入 `SY-*` 陶泥号查不到已有素材；无筛选时只显示 80 个任务且没有“读取更多”；手动重拆图集后，`素材 N` 被单独当成零成本父任务，原图集又显示成另一组。
+- 原因：`editor_asset.owner_user_id` 保存内部 `user_id`，不保存公开陶泥号；作者陶泥号在 procedure 返回后才映射，不能直接参与素材表过滤。`spacetime-client` 的统一时间文本是 `seconds.microsZ`，若 cursor 只按 RFC3339 解析，第 80 个任务无法生成 `nextCursor`。手动图集拆分使用独立 `editor-atlas-split-*` 任务号，但切片项目资源通过 `source_resource_id` 指回原图集资源，只按当前 `task_id` 分组会割裂同一条素材生产链。
+- 处理：`api-server` 在调用素材 procedure 前把“用户 ID / 陶泥号”字段或精确 `SY-*` keyword 解析成内部 `user_id`；游标解析同时接受整数微秒、统一 `seconds.microsZ` 和 RFC3339，编码失败必须返回服务错误，不能伪装成末页，客户端传入的非法 cursor 必须返回 `400`，不能静默回到第一页。手动拆分素材保留真实 `task_id`，通过 `editor_asset_group_source_provenance` 按原 resource、asset object 或 Object Key 查找服务端生成账号素材的可信来源任务，再把来源任务写入 `editor_asset.group_task_id`；跨项目复用时同时携带当前和原始 source resource，首次历史回溯命中后补写 provenance，后续不再扫描账号全量素材。没有可信来源的新批次显式以自己的拆分任务作为 `group_task_id`，不得落回可读取用户资源元数据的 legacy 分支。每片保存 `group_task_expected_asset_count`，全部切片落库后再写不可逆的 `editor_asset_group_cohort` 完成事实；read model 依据完成事实判断批次资格，不用当前剩余行数猜测初始是否完整，因此用户后来删除切片不会让批次脱组。部分失败批次没有完成事实，始终保留为独立拆分任务。历史行兼容沿资源链回溯，删除项目时只固化直接引用待删资源且尚未固化的历史切片；固化始终保存真实来源任务，有界展示分组不得反写覆盖来源。read model 只让同根任务的一个完整拆分批次并入原任务，重复批次按真实拆分任务独立分页。带 owner 条件时先走 `by_editor_asset_owner_user_id`，不要为单用户查询扫描全站素材。后台筛选输入使用防抖并取消旧 transport；手动刷新同一查询失败时保留已有结果和游标，筛选已变化时不展示旧查询结果。
+- 验证：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`。
@@ -364,9 +380,9 @@

 - 现象：用户点击图片素材的“快速编辑”后，画布上额外出现 `Quick Edit Generator` 占位，像是新建了一个生成器；但用户预期是在原图下方框选区域、填写一个提示词和模型，然后直接修改当前图。
 - 原因：快速编辑入口和提交链路误用了 `createQuickEditGenerationDialogDraft(...)` / `CanvasGenerationDialogState`，把“覆盖源图”的快速编辑伪装成会产出新图层的生成器占位。
- 处理：图片快速编辑必须走 `QuickEditPanelState`，打开时归档当前 active generation dialog 但不创建新的 `mode="quick-edit"` dialog；提交时调用 `/api/editor/images/edits`，把当前图片或带编号标注的图片作为 `sourceImageSrc`，成功后覆盖源图，失败时保留快速编辑面板。图片重绘、去背景、视频快速编辑等会产出新图层或异步占位的入口仍可走 generation dialog / placement 链路。
- 验证：`npm run test -- src/components/image-editor/useImageCanvasGenerationWorkflow.test.tsx src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.test.tsx src/components/image-editor/ImageCanvasQuickEditPanelView.test.tsx -- --runInBand`，以及按需运行 `npm run test -- src/components/image-editor/ImageCanvasEditorGenerationIntegration.test.tsx -t "快速编辑|quick edit" -- --runInBand`。
- 关联：`src/components/image-editor/useImageCanvasGenerationWorkflow.ts`、`src/components/image-editor/ImageCanvasGenerationSubmissionModel.ts`、`src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.ts`、`src/services/image-editor/editorImageReference.ts`。
+- 处理：图片快速编辑必须走 `QuickEditPanelState`，打开时归档当前 active generation dialog 但不创建新的 `mode="quick-edit"` dialog；提交时调用 `/api/editor/images/edits`，把当前图片或带编号标注的图片作为 `sourceImageSrc`，成功后覆盖源图，失败时保留快速编辑面板。快速编辑任务进入 `generating` 后必须移除框选工具和覆盖层，禁止继续新增框选；失败恢复面板后可继续调整框选再重试。图片重绘、去背景、视频快速编辑等会产出新图层或异步占位的入口仍可走 generation dialog / placement 链路。
+- 验证：`npm run test -- src/components/image-editor/useImageCanvasGenerationWorkflow.test.tsx src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.test.tsx src/components/image-editor/ImageCanvasQuickEditPanelView.test.tsx src/components/image-editor/ImageCanvasEditorView.test.tsx -- --runInBand`，以及按需运行 `npm run test -- src/components/image-editor/ImageCanvasEditorGenerationIntegration.test.tsx -t "快速编辑|quick edit" -- --runInBand`。
+- 关联：`src/components/image-editor/ImageCanvasEditorView.tsx`、`src/components/image-editor/useImageCanvasGenerationWorkflow.ts`、`src/components/image-editor/ImageCanvasGenerationSubmissionModel.ts`、`src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.ts`、`src/services/image-editor/editorImageReference.ts`。

 ## 图片画布快速编辑完成必须按目标图层回写

@@ -384,6 +400,14 @@
 - 验证：`npm run test -- src/components/image-editor/ImageCanvasGenerationDialogModel.test.ts src/components/image-editor/ImageCanvasQuickEditPanelView.test.tsx src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.test.tsx` 覆盖来源参数继承、模型参数切换、目标尺寸提交和图层回填；`cargo test -p api-server editor_image_edit --manifest-path server-rs/Cargo.toml` 覆盖图标类拒绝、provider 尺寸对齐和回图恢复。
 - 关联：`src/components/image-editor/ImageCanvasGenerationSubmissionModel.ts`、`src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.ts`、`src/components/image-editor/ImageCanvasGenerationLayerModel.ts`、`server-rs/crates/api-server/src/editor_project.rs`。

+## 图片画布快速编辑模型必须在后端选择正确的 provider 协议
+
+- 现象：快速编辑继承或选择 `nanobanana2` 后，上游返回 `not supported model for image generation`；图集开放快速编辑后尤其容易触发。
+- 原因：前端把 `gemini-3.1-flash-image-preview` 正常提交到 `/api/editor/images/edits`，但后端无条件使用只支持 `gpt-image-2` 的 VectorEngine `/v1/images/edits` multipart 协议。
+- 处理：快速编辑请求同时提交 `model / aspectRatio / imageSize`。api-server 归一模型后分流：`nanobanana2` 使用 `/v1beta/models/{model}:generateContent`，把原图和参考图放入 `inline_data`，并传递 `generationConfig.imageConfig`；`gpt-image-2` 继续使用 `/v1/images/edits` multipart 和 16 像素 provider 边界对齐。nanobanana2 保留 provider 输出几何尺寸，不套用 GPT edits 的像素恢复。
+- 验证：`npm run test -- src/services/image-editor/editorProjectClient.test.ts src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.test.tsx` 覆盖前端参数提交；`cargo test -p api-server editor_image_edit --manifest-path server-rs/Cargo.toml` 覆盖模型分流、尺寸档位计费与 GPT 对齐恢复。
+- 关联：`src/services/image-editor/editorProjectClient.ts`、`src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.ts`、`server-rs/crates/api-server/src/editor_project.rs`、`server-rs/crates/api-server/src/openai_image_generation.rs`。
+
 ## 图片画布纯尺寸变换必须先在内存决策再单次上传

 - 现象：`nanobanana2` 已返回并成功解码图片，任务随后报“尺寸无效”；普通生图若把尺寸恢复作为硬失败，provider 已成功回图后仍可能没有素材进入素材库和画布。
@@ -1602,6 +1626,14 @@
 - 验证：`npm run dev -- --watch` 下修改 `apps/admin-web/src/**` 应由 Vite HMR 处理，不应出现连续 `[dev] 重启 admin-web`；`scripts/dev.test.ts` 覆盖 web/admin-web 不注册外层 watch。
 - 关联：`scripts/dev.mjs`、`docs/technical/RUST_LOCAL_AND_REMOTE_DEPLOYMENT_SCRIPTS_2026-04-22.md`。

+## 根目录 `nohup.out` 持续写入会触发主站 Vite 刷新循环
+
+- 现象：在仓库根目录用 `nohup npm run dev ... &` 启动完整 dev 栈后，即使没有修改前端源码，主站页面也会反复整页刷新；`nohup.out` 同时持续增长。
+- 原因：未显式重定向 stdout / stderr 时，`nohup.out` 会收集 SpacetimeDB、api-server 和两套 Vite 的整套 dev 栈输出。主站 Vite 的 root 是仓库根目录，若 watcher 未忽略这个持续写入的文件，每次追加日志都会被当成文件变化；后台 Vite root 是 `apps/admin-web`，仓库根日志不在其监听根内。
+- 处理：主站 `vite.config.ts` 的 `server.watch.ignored` 保持忽略 `**/nohup.out`，Git 同时忽略 `nohup.out`。修改配置后重启主站 Vite。若显式重定向到其它仓库内日志文件，该文件不会自动受保护，应写到 Vite root 之外或补充精确忽略规则。
+- 验证：在仓库根目录追加 `nohup.out` 时主站不再刷新，真实源码修改仍正常触发 HMR；`git check-ignore nohup.out` 能命中忽略规则，`git status` 不出现该日志。
+- 关联：`vite.config.ts`、`.gitignore`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。
+
 ## 本地 SpacetimeDB publish 401 可清本地库重发

 - 现象：本地 `spacetime publish` 显示 `401` 无权限，或重新发布仍像是在更新旧库。
@@ -3109,3 +3141,11 @@
 - 原因：`.admin-info-list div` 会命中列表内所有后代 `div`，把字段值内部的 `.admin-inline-identity` 和昵称容器也覆盖成双列 grid；陶泥号又允许任意位置换行，最终只剩单字符宽度。素材详情布局若始终固定为 `220px + 信息列`，移动端也没有足够空间。
 - 处理：信息列表的行布局只使用直接子选择器 `.admin-info-list > div`；作者昵称与陶泥号在身份组件内分行，陶泥号保持单行并在真正不足时省略。`560px` 以下的素材详情改为单列，缩略图居中；素材查询与精选审核共用该规则。
 - 验证：在桌面、560px、390px 和 320px 浏览器宽度打开素材详情，确认 `.admin-inline-identity` 的 computed `display` 为 `flex`、陶泥号横向显示、详情字段不溢出页面。
+
+## SpacetimeDB 历史归档不能按文件名小于 snapshot 就全部删除
+
+- 现象：看到最新 `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。
+- 关联：`scripts/database-backup-to-oss.mjs`、`scripts/check-database-backup-to-oss.mjs`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。
@@ -25,6 +25,7 @@
 - 消耗泥点数：`profile_wallet_ledger` 中 `source_type = asset_operation_consume` 且 `amount_delta < 0` 的流水绝对值，按 `created_at` 映射到北京时间业务日。
 - 总注册用户：`profile_dashboard_state` 行数。
 - 新增用户数：`profile_dashboard_state` 中 `created_at` 落在当前筛选时间窗内的账号数，按北京时间业务日归属，支持本日 / 本周 / 本月快捷日期范围。
+- 新增用户付费率：分母为当前筛选时间窗内的新增用户，分子为这些用户中截至本次查询时已至少完成一次真实支付的去重人数。真实支付以 `profile_recharge_order.paid_at` 存在且不晚于本次查询时刻为准；只创建订单或未支付订单不计，已退款订单仍表示曾经发生过付费转化，因此保留在分子。返回付费人数、新增用户数和四舍五入后的基点率；分母为 0 时 DTO 返回 0，前端百分比显示 `-`。
 - 访问次数：`tracking_daily_stat` 中 `scope_kind = site` 的日聚合次数。它表示站点级成功路由 / 站点级事件，不把用户级钱包、任务、生成等业务操作混入访问次数。
 - 访问人数：当前数据只具备登录用户维度，按 `tracking_daily_stat` 中 `scope_kind = user`、`count > 0` 且 `scope_id` 非空、非 `anonymous` 的用户去重；匿名访问人数需要未来补充稳定 visitor id 后才能统计。时段指标按整个筛选范围跨日去重，趋势图按 `day_key + scope_id` 每日去重，不能把时段 UV 塞到终止日，也不能把每日 UV 之和当成时段 UV。
 - 近 5 分钟活跃用户：以请求时刻为终点，最近 5 分钟内 `tracking_event` 中有 `user_id` 的登录用户去重；不跟随页面选择的历史日 / 周 / 月。这是滚动窗口，不是每 5 分钟才采样一次。
@@ -1,6 +1,6 @@
 # 外部生成 Worker 化方案

-更新时间：`2026-06-24`
+更新时间：`2026-07-15`

 ## 背景

@@ -13,8 +13,8 @@
 - 多个 worker 进程通过 SpacetimeDB 任务表抢占任务，依赖 lease 超时恢复，支持按进程数和单进程并发动态缩扩容。
 - 本地或小流量同步排查可显式启用 `inline` 模式，由 HTTP handler 复用同一 worker executor 同步执行并返回 `completed`；该模式不创建队列任务，也不具备 worker 横向扩容能力。
 - SpacetimeDB reducer / procedure 只做任务状态流转，不做网络、文件系统或外部 provider I/O。
- 已接入拼图 `compile_puzzle_draft`、结果页 `generate_puzzle_images` 与结果页 `generate_puzzle_ui_background`，跳一跳、拼消消和敲木鱼的外部图片生成动作，以及图片画布编辑器的图片、改图、图标 spritesheet、UI 素材提取、角色动作、视频、音效和背景音乐生成。后续玩法和编辑器生成入口继续复用同一队列 Module，不再为每个入口发明独立队列。
- 第一版外部生成队列粒度固定为“单个用户动作对应单个 job”。例如草稿编译、结果页单槽重生、图集重生都各自入一个 job；job 内部可以串行或并行调用 provider、OSS、SpacetimeDB 写回，但不再拆成“提示词 / 生图 / 切图 / 去背景 / 持久化 / 回写”等阶段 job。阶段进度只作为 `request_payload_json` / 业务 session 的展示状态，不作为队列调度单位。
+- 已接入拼图 `compile_puzzle_draft`、结果页 `generate_puzzle_images` 与结果页 `generate_puzzle_ui_background`，跳一跳、拼消消和敲木鱼的外部图片生成动作，以及图片画布编辑器的图片、改图、手动去背景、图标 spritesheet、UI 素材提取、角色动作、视频、音效和背景音乐生成。后续玩法和编辑器生成入口继续复用同一队列 Module，不再为每个入口发明独立队列。
+- 第一版外部生成队列粒度固定为“单个用户动作对应单个 job”。例如草稿编译、结果页单槽重生、图集重生都各自入一个 job；job 内部可以串行或并行调用 provider、OSS、SpacetimeDB 写回，但不再拆成“提示词 / 生图 / 切图 / 去背景 / 持久化 / 回写”等阶段 job。用户可见执行阶段通过现有任务行及摘要投影的轻量 `phase` 保存，不作为队列调度单位，也不写回大 payload。
 - 不调用外部图片 / 音频 / LLM provider 的动作继续 inline 执行，不为了统一排队而进入 `external_generation_job`。

 ## Module 与 Interface
@@ -24,12 +24,15 @@
 - `enqueue_external_generation_job_and_return`：按 `dedupe_key` 幂等创建或返回现有任务。
 - `claim_external_generation_jobs_and_return`：worker 按 `worker_id`、`limit` 和 lease 时长抢占 `pending` 或 lease 过期的 `running` 任务，返回本次 claim 的 `lease_token`。
 - `renew_external_generation_job_lease_and_return`：worker 长任务执行期间按 `worker_id + lease_token` 续租，防止外部生成超过单次 lease 后被重复领取。
+- `update_external_generation_job_phase_and_return`：worker 按 `job_id + worker_id + lease_token` 把当前执行阶段更新为 `generating` 或 `processing`，并同步现有摘要投影；不新增阶段任务或阶段表。procedure 用结构化结果区分 `LeaseFencingRejected` 与 `OtherRejected`，调用方不解析错误文案；`LeaseFencingRejected` 立即终止，`OtherRejected` 以及 SDK 的 `Procedure` / `Runtime` 错误不重试，只有 `Build` / `ConnectDropped` / `Timeout` 在同一个 job attempt 内重试 `1` 次。该重试只重新上报 phase，不把任务写回 `pending`，也不重新调用 provider；编辑器 job 入队固定 `max_attempts=1`，第二次传输失败后任务进入 `failed`，不会回到 `pending` 或从 provider 生成起点重跑。
 - `complete_external_generation_job_and_return`：worker 成功后按 `worker_id + lease_token` 写入 `result_payload_json`，任务进入 `completed`。
 - `fail_external_generation_job_and_return`：worker 失败后按 `worker_id + lease_token` 回写错误，并按 `max_attempts` 决定回到 `pending` 重试或进入 `failed`。
- `list_external_generation_jobs_and_return`：按当前账号读取正式生成任务列表，返回 pending / running / 未确认终态数量、任务价格和完成提示确认状态。
- `acknowledge_external_generation_jobs_and_return`：按当前账号确认已终态任务的完成 / 失败提示，写入 `notification_acknowledged_at` 并追加审计事件。
+- `list_external_generation_job_summaries_and_return`：按当前账号从轻量摘要投影读取正式生成任务列表，返回 pending / running / 未确认终态数量、任务价格、执行阶段和完成提示确认状态。
+- `acknowledge_external_generation_job_summaries_and_return`：按当前账号确认已终态任务的完成 / 失败提示，写入摘要投影的 `notification_acknowledged_at` 并追加审计事件。
 - `get_external_generation_queue_stats_and_return`：controller 读取队列积压、运行中任务和过期 lease 数量，用于计算 worker 目标实例数；该 procedure 只读 `external_generation_job`，不直接操作 systemd。
- `get_external_generation_job_and_return`：按 `job_id` 读取单个任务状态，给 BFF 和生成页展示使用；必须只返回调用者有权读取的任务，不能暴露其它用户的 payload、错误详情或 worker 内部字段。
+- `get_external_generation_job_summary_and_return`：按 `job_id` 从轻量摘要投影读取单个任务状态，给 BFF 和生成页展示使用；必须只返回调用者有权读取的任务，不能暴露其它用户的 payload、错误详情或 worker 内部字段。
+
+不带 `summary / summaries` 的旧 `get / list / acknowledge_external_generation_job*` procedure 只保留给受控内部兼容，不是 BFF 正式读取入口。

 这个 Module 的 **Seam** 在 SpacetimeDB procedure + `spacetime-client` facade；`api-server` HTTP role 和 worker role 都只依赖这个 Interface。外部 provider、OSS、计费补偿、玩法草稿回写仍留在 `api-server` worker implementation 内，不进入 SpacetimeDB reducer。

@@ -38,11 +41,12 @@
 队列状态对前端只通过 `api-server` BFF 暴露，不允许前端直接查询 SpacetimeDB private table：

 - `GET /api/runtime/external-generation/queue-overview`：当前账号队列概览，用于兼容旧展示和轻量状态读取。返回 pending、running、未确认终态数量和更新时间。
- `GET /api/runtime/external-generation/jobs?limit=20&includeAcknowledgedTerminal=false`：当前账号正式生成任务列表，用于 `我的` 页签任务列表和完成 / 失败提示。返回每个任务的 job id、kind、source、可展示 label、状态、进度、错误、`priceMudPoints`、`refundLedgerId`、`notificationAcknowledgedAt` 和时间戳。默认不返回已确认的终态任务；需要拆分活跃和完成列表时可追加 `statuses=running,queued` 或 `statuses=completed,failed`，BFF 仍只返回当前账号任务。
+- `GET /api/runtime/external-generation/jobs?limit=20&includeAcknowledgedTerminal=false`：当前账号正式生成任务列表，用于 `我的` 页签任务列表和完成 / 失败提示。返回每个任务的 job id、kind、source、可展示 label、状态、进度、错误、可选 `warning`、`priceMudPoints`、`refundLedgerId`、`notificationAcknowledgedAt` 和时间戳。默认不返回已确认的终态任务；需要拆分活跃和完成列表时可追加 `statuses=running,queued` 或 `statuses=completed,failed`，BFF 仍只返回当前账号任务。
+- 任务被 claim 后默认处于 `generating`，BFF 显示“正在生成”；真实进入 BgFilter、逐帧抠图或手动去背景时切换为 `processing`，BFF 显示“正在处理”。旧任务 `phase=None` 按 `generating` 兼容，前端不得按耗时或 job kind 推断阶段。
 - `POST /api/runtime/external-generation/jobs/acknowledge`：生成完成 / 失败提示展示后由前端后台调用，BFF 只传当前账号 job ids，后端只确认属于当前账号且已终态的任务。
- `GET /api/runtime/external-generation/jobs/{jobId}`：单 job 状态，用于生成页轮询某次动作。返回 `jobId`、`jobKind`、`sourceModule`、`sourceEntityId`、`status`、`attempt`、`maxAttempts`、`createdAt`、`startedAt`、`completedAt`、`updatedAt`、可展示的 `requestLabel`、可展示的 `lastErrorMessage`、以及业务侧下一次轮询所需的 source 标识。
+- `GET /api/runtime/external-generation/jobs/{jobId}`：单 job 状态，用于生成页轮询某次动作。返回 `operationId`（即任务 ID）、`status`、`phaseLabel`、`phaseDetail`、`progress`、`error`、`updatedAtMicros`，以及可选、可直接展示的 `warning` 完整文案。生成页轮询只依赖状态、阶段、进度、错误和警告；`jobKind`、source 和完整时间信息继续由任务列表接口或业务快照提供。`attempt` / `maxAttempts` 属于 worker 调度事实，不向该前端契约暴露；若未来需要面向用户展示，必须单独完成产品、契约和摘要投影设计。

-BFF 只做鉴权、授权裁剪、字段脱敏和契约映射；队列事实仍以 `external_generation_job` 为准，业务结果仍以玩法 session / work profile 为准。生成页 / 进度页只展示当前玩法业务进度；用户可见任务列表放在 `我的` 页签，必要时再用单 job 状态补充排障信息，并继续按原玩法 session/detail 接口收敛到 ready 或 failed。队列接口不替代玩法恢复接口，也不把 private `request_payload_json` 原样传给前端。终态提示的弹出与否以后端 `notification_acknowledged_at` 为准；前端在提示展示后后台调用 acknowledge 接口，关闭按钮只负责收起本地弹窗，不能只靠本地 dismiss 永久吞掉任务。
+BFF 只做鉴权、授权裁剪、字段脱敏和契约映射；worker 调度、lease、执行和计费事实仍以 `external_generation_job` 为准，用户可见任务列表、单任务状态、执行阶段和通知确认的正式读取事实源为 `external_generation_job_summary`，业务结果仍以玩法 session / work profile 为准。生成页 / 进度页只展示当前玩法业务进度；用户可见任务列表放在 `我的` 页签，必要时再用单 job 状态补充排障信息，并继续按原玩法 session/detail 接口收敛到 ready 或 failed。队列接口不替代玩法恢复接口，也不把 private `request_payload_json` 原样传给前端。终态提示的弹出与否以后端 `notification_acknowledged_at` 为准；前端在提示展示后后台调用 acknowledge 接口，关闭按钮只负责收起本地弹窗，不能只靠本地 dismiss 永久吞掉任务。

 ## 任务表

@@ -52,7 +56,7 @@ BFF 只做鉴权、授权裁剪、字段脱敏和契约映射；队列事实仍
 | --- | --- |
 | `job_id` | 主键，`extgen-` 前缀 UUID |
 | `dedupe_key` | 唯一键，建议为 `play/action/session/scope` |
-| `job_kind` | 执行类型，当前覆盖 `puzzle_compile_draft`、`puzzle_generate_images`、`puzzle_generate_ui_background`、跳一跳 / 拼消消 / 敲木鱼生成动作，以及 `editor_image_generation`、`editor_image_edit`、`editor_icon_spritesheet_generation`、`editor_ui_design_asset_extraction`、`editor_character_animation_generation`、`editor_video_generation`、`editor_sound_effect_generation`、`editor_background_music_generation` |
+| `job_kind` | 执行类型，当前覆盖 `puzzle_compile_draft`、`puzzle_generate_images`、`puzzle_generate_ui_background`、跳一跳 / 拼消消 / 敲木鱼生成动作，以及 `editor_image_generation`、`editor_image_edit`、`editor_background_removal`、`editor_icon_spritesheet_generation`、`editor_ui_design_asset_extraction`、`editor_character_animation_generation`、`editor_video_generation`、`editor_sound_effect_generation`、`editor_background_music_generation` |
 | `owner_user_id` | 触发用户 |
 | `source_module` | 玩法或能力名，例如 `puzzle` |
 | `source_entity_id` | session/profile/work 等作用域 |
@@ -70,6 +74,9 @@ BFF 只做鉴权、授权裁剪、字段脱敏和契约映射；队列事实仍
 | `price_mud_points` | 后端计算的本任务价格，用于任务列表展示和排障 |
 | `refund_ledger_id` | 失败退款产生的钱包退款流水 ID，便于从任务追到退款记录 |
 | `notification_acknowledged_at` | 用户已确认完成 / 失败提示的时间，未确认终态任务下次登录继续集中弹出 |
+| `phase` | 尾部可选字段；`null / generating / processing`，claim 时写 `generating`，进入正式后处理时写 `processing` |
+
+用户正式读取使用私有轻量投影 `external_generation_job_summary`。该表同步保存 owner、来源、状态、`phase`、价格、有限错误/告警摘要、通知确认和时间字段，不复制 request/result payload、worker lease 或 dedupe 内部字段；enqueue、claim、renew、phase update、complete、fail 与 acknowledge 都必须维护对应投影语义。

 新增私有审计表 `external_generation_job_event`，记录 `enqueued/claimed/lease_renewed/completed/failed/acknowledged` 等事件。事件表只追加状态转换事实，不作为当前状态源；排障时先看 `external_generation_job` 当前状态，再按 `job_id` 追 `external_generation_job_event` 时间线。

@@ -113,7 +120,7 @@ worker 配置：
 - `GENARRATIVE_EXTERNAL_GENERATION_WORKER_CONCURRENCY`：单进程并发领取/执行数量。
 - `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 槽位，避免任务长期保持 `running_active`；若业务 future 已在计费操作内被取消，计费层会按外部生成 job id 异步补偿退款。
+- `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`。

 controller 配置：
@@ -126,7 +133,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 长时间无返回，执行预算到期后会结束当前尝试并释放槽位；如果当时 SpacetimeDB 写回失败，任务也会按较短 lease 进入可重领窗口，避免无进展续租无限延长。容器链路已有独立 `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 重新领取。若 worker 内业务 future 长时间无返回，执行预算到期后 worker 会停止续租并释放槽位，在途 future 继续运行至租约仲裁窗口；有效租约内的写回仍可完成，租约过期后才会由其它 worker 重新认领，避免客户端取消与服务端写回竞态。容器链路已有独立 `external-generation-worker` compose service；扩 worker 必须扩这个 worker service，不能只扩 `api-server` HTTP service。

 ## 已接入的拼图纵切

@@ -178,6 +185,7 @@ controller 配置：

 - `editor_image_generation`：普通图片、生成规范、角色形象、UI 设计图、宣发素材和图片快速编辑。
 - `editor_image_edit`：图片编辑 / 修改结果。
+- `editor_background_removal`：手动去除任意图片背景，worker 使用 BgFilter complex 模式、首次失败后重试 `1` 次，并把执行阶段标记为 `processing`。
 - `editor_icon_spritesheet_generation`：图标素材 spritesheet 生成和拆分。
 - `editor_ui_design_asset_extraction`：UI 设计图红框素材提取。
 - `editor_character_animation_generation`：角色动作视频和帧素材生成。
@@ -186,6 +194,10 @@ controller 配置：

 画板结果的业务真相仍是 `editor_project_resource`、账号级 `editor_asset` 和 `editor_canvas.layers_json`。请求携带 `projectId + canvasCompletion` 时，worker 成功后读取当前项目 layout，用最新 generation dialog placeholder 或无 dialog 完成占位写入结果图层，并保存项目快照；前端轮询单 job 到 completed 后重新读取项目快照，不从队列 payload 或本地临时响应重建正式图层。生成器已被删除时，worker 只保留生成出的资源 / 素材记录，不把结果重新塞回画布。

+角色形象、图标 spritesheet 和 UI 素材提取在 provider 原图已经持久化后，如果透明背景处理最终失败，只用原图完成 `canvasCompletion`，不创建或回填透明处理图，图标和 UI 也不继续拆分，任务保持 `completed`。这个 source-only 降级只包住透明背景处理的最终失败；phase 上报、provider 原图持久化、透明处理图持久化或画布写回失败仍按任务错误传播。
+
+inline 与 external v1 成功响应继续使用结构化 `warning.code/reason`；图标 / UI 的透明图已经成功、只有自动拆分失败时，继续返回结构化 `sliceWarning.code/reason`，其中 `sliceWarning.reason` 保留原始诊断。queue worker 把两类告警归一为有界的 `result_payload_json.warning`：通用 `warning` 优先并原样保留完整 `reason`；只有不存在通用 `warning` 时，才给 `sliceWarning.reason` 添加“图集已生成，但自动拆分未完成：”前缀。任务摘要将该展示就绪的 `reason` 原样提取到 `warning_message`，单 job 状态和刷新后的任务列表 BFF 再以 `warning: string` 返回；Web 必须直接展示，不再补前缀或按 code 推断类型。历史任务保留写入时的 `reason` 快照，摘要 backfill 不按当前格式重新解释或补写前缀。该字符串语义是 worker / BFF / Web 的内部同版本契约，三者必须协调发布，不承诺滚动混部或旧 Web 缓存下的跨版本字符串兼容。
+
 ## 验收

 基础检查：
@@ -30,11 +30,24 @@

 ## 验收

- `cargo test -p spacetime-client --manifest-path server-rs/Cargo.toml --lib`（35 通过，含上述新测试）
+- `cargo test -p spacetime-client --manifest-path server-rs/Cargo.toml --lib`（44 通过，含上述连接池与缓存连接测试）
 - `cargo test -p api-server --manifest-path server-rs/Cargo.toml readyz`（2 通过）
 - `cargo check -p api-server --manifest-path server-rs/Cargo.toml`

+## 2026-07-14 缓存读连接拆分
+
+HTTP 角色的连接拓扑调整为“`pool_size` 条调用连接 + 1 条缓存读连接”：
+
+1. 调用连接池只承接 procedure / reducer 回调，不订阅 read model，也不装载订阅行；`GENARRATIVE_SPACETIME_POOL_SIZE=8` 表示 8 条调用连接，不包含额外的缓存读连接。
+2. 缓存读连接只由 `read_after_connect` 使用，并持有一份 required / optional read-model subscriptions。多个本地读取通过 `Arc` 共享同一 SDK `ClientCache`，初始化和断线重建使用单飞锁，读取本身不经过单槽 semaphore 串行化。
+3. 缓存读连接断线后，下一次读取只重建一条连接并等待 required subscriptions 全部 applied；首次建连与 required / optional 订阅共用一次总超时预算，optional 阶段发生断线时禁止发布 broken 连接；旧连接由在途读取持有到结束后再断开。
+4. `/readyz` 对 HTTP 角色同时检查调用池连接和缓存读连接；required subscription 失败时不得报告 ready。worker / controller 关闭 read-model cache 时不创建额外连接。
+5. 这里的“只读”是 facade 用途边界。SpacetimeDB Rust SDK 2.6 没有连接级 read-only builder；缓存连接仍使用相同 runtime identity，但代码不向 procedure / reducer 调用路径暴露它。
+
+该拆分把相同 read-model 行缓存从 `pool_size` 份降为 1 份；SDK 每条连接仍会注册空 table metadata，总 WebSocket 数在 HTTP 角色中会从 `pool_size` 增加到 `pool_size + 1`，因此不能把总 RSS 简单承诺为原来的 `1 / pool_size`。
+
 ## 运维提示

 - 此修复解决的是"取消导致的永久泄漏"。StDB 真慢时仍会出现成批 45 秒超时（连接被在途请求合法占用），那是容量/上游问题，应结合 `GENARRATIVE_SPACETIME_POOL_SIZE` 与 StDB 负载排查，不要再怀疑池泄漏。
 - 健康检查 `/readyz` 在池被在途请求占满时仍可能短暂 503（stage=pool_acquire），恢复后自动转好，无需重启。
+- HTTP 角色排查连接数时按“调用池 + 1 条缓存读连接”计算；外部生成唤醒和充值过期监听还有各自的窄订阅连接，不属于调用池或缓存读连接。
@@ -42,6 +42,8 @@ v1 只开放以下能力：
 - `POST /api/external/v1/editor/audios/background-music/generations`：生成编辑器背景音乐素材。
 - `GET /api/external/v1/openapi.json`：导出本版本 OpenAPI 3.1 JSON。

+角色图生成、图标 spritesheet 和 UI 素材提取的 2xx 成功响应可携带可选结构化 `warning { code, reason }`，当前稳定 `code` 为 `postprocess-failed-source-preserved`。provider 原图已保存但透明背景处理最终失败时，接口返回原图，不返回不存在的透明处理图，图标和 UI 也不继续拆分；有 `projectId + canvasCompletion` 时由原图完成画布写回，无画布上下文时只返回原图及实际存在的资源 / 素材快照。调用方应展示 warning，但不得把任务改判为失败。该降级只覆盖透明背景处理的最终失败，phase 上报、原图或透明处理图持久化、画布写回失败仍返回错误。图标 / UI 已成功生成透明图、只有自动拆分失败时继续使用既有 `sliceWarning`；服务端保证通用 `warning` 与 `sliceWarning` 互斥，防御性客户端若收到异常双字段响应仍以通用 `warning` 为准。
+
 管理 API Key 的登录态接口保留在站内个人中心链路，但不写入外部 OpenAPI JSON：

 ```text
@@ -137,6 +139,7 @@ docs/openapi/genarrative-external-v1.openapi.json
 - API Key 创建只返回一次明文，列表不返回明文。
 - 撤销后的 API Key 调用外部接口返回 `401`。
 - 外部图片生成、重绘、图标拆分、UI 素材拆分、视频、音效和音乐生成成功后，生成结果按请求同时出现在画布资源和账号级素材库。
+- 角色图、图标 spritesheet 和 UI 素材提取的 2xx 成功响应允许携带 `EditorGenerationWarning`；provider 原图保留降级与自动拆分降级必须保持成功状态，并分别使用通用 `warning` 与兼容 `sliceWarning` 表达。
 - 外部视频、角色动画、音效和音乐接口使用站内编辑器相同的请求校验、模型限制和价格校验。
 - OpenAPI JSON 能被 `serde_json` 解析，且 security scheme 为 Bearer API Key。
 - OpenAPI JSON 不包含 `/api/profile/api-keys`、`UserAccessToken` 或 API Key 管理 schema。
--- a/Show More
+++ b/Show More