diff --git a/apps/ai-game-creator-shell/scripts/build-macos-ci.mjs b/apps/ai-game-creator-shell/scripts/build-macos-ci.mjs
index 442df54d1..49bf93abf 100644
--- a/apps/ai-game-creator-shell/scripts/build-macos-ci.mjs
+++ b/apps/ai-game-creator-shell/scripts/build-macos-ci.mjs
@@ -9,6 +9,7 @@ import { fileURLToPath } from 'node:url';
 import {
   generateUpdateManifest,
   prepareReleaseVersion,
+  resolveManifestPlatformKeys,
   resolveReleaseContext,
   resolveReleasePartition,
   runTauriBuild,
@@ -20,10 +21,13 @@ import {
 } from './verify-updater-signature.mjs';
 
 /**
- * AGC macOS 分区（`<channel>-mac`）发布入口：构建 universal 包 → 双架构 smoke → 生成 universal DMG
+ * AGC macOS 分区（`<channel>-mac`）发布入口：构建 arm64 单架构包 → arm64 隔离 smoke → 生成 arm64 DMG
  * → 生成分区清单 latest.json → 用产物内烘焙的公钥验签 → 按 dry-run 决定是否上传 OSS。
  *
  * 边界：
+ * - 只出 Apple Silicon（arm64）单架构：清单只登记 `darwin-aarch64`。Intel 侧要可用，前提是随包 Node
+ *   也能按架构各带一份（`stage-node-runtime.mjs` 对 universal 目标失败关闭）；在实现之前**不得**
+ *   把 arm64 产物登记成 `darwin-x86_64`，否则 Intel 客户端会装到跑不起来的包。
  * - Apple 签名与公证暂缺：本入口剥离 `APPLE_*` 凭据让 Tauri 跳过 Apple 签名，但**不能传
  *   `--no-sign`** —— 该标志同时会跳过 updater 的 minisign 签名，产物就没有 `.sig`；
  *   未签名 + 未公证必须显式记录而非静默通过；
@@ -94,11 +98,14 @@ process.env.AGC_UPDATE_OSS_BASE_URL ||= `https://${bucket}.${endpoint}/agc`;
 const dryRun = readReleaseDryRun();
 
 process.env.CARGO_TARGET_DIR = path.join(appRoot, 'src-tauri/target');
-const context = resolveReleaseContext(['--target=universal-apple-darwin']);
+// 单架构目标：清单侧 `resolveManifestPlatformKeys` 只为它登记 darwin-aarch64。
+const macTarget = 'aarch64-apple-darwin';
+const context = resolveReleaseContext([`--target=${macTarget}`]);
 const partition = resolveReleasePartition(context.channel, context.target);
 const version = await prepareReleaseVersion(context);
-// 首装包名必须保持 `<产品名>_<版本>_universal.dmg`：清单侧按该后缀唯一匹配本次产物。
-const firstInstallName = `${productName}_${version}_universal.dmg`;
+// 首装包名必须让清单侧的单架构分支唯一匹配：`<产品名>_<版本>_<架构>.dmg`，
+// 架构段用 Tauri 的 aarch64 口径（不是 updater 平台键的 arm64 / x86_64）。
+const firstInstallName = `${productName}_${version}_aarch64.dmg`;
 
 // 幂等边界：workspace 会保留上一轮产物。先删掉本次将要写出的对象，否则
 //  1) hdiutil 会因同名 DMG 已存在直接失败（首次实跑即命中）；
@@ -117,7 +124,7 @@ for (const stale of [
 }
 
 const args = [
-  '--target=universal-apple-darwin',
+  `--target=${macTarget}`,
   '--bundles',
   'app',
   '--ci',
@@ -132,16 +139,13 @@ const command = (binary, argv, options = {}) =>
 runTauriBuild(args, context);
 
 const app = path.join(context.bundleRoot, 'macos', appBundleName);
-for (const architecture of ['arm64', 'x86_64']) {
-  command(process.execPath, [
-    path.join(appRoot, 'scripts/check-macos-bundle.mjs'),
-    app,
-    architecture,
-    '--universal',
-  ]);
-}
+command(process.execPath, [
+  path.join(appRoot, 'scripts/check-macos-bundle.mjs'),
+  app,
+  'arm64',
+]);
 
-// DMG 放在 bundle 根目录下：渠道清单的首装包选择会扫描该目录，命名必须匹配 `_<version>_universal.dmg`。
+// DMG 放在 bundle 根目录下：渠道清单的首装包选择会扫描该目录，命名必须匹配 `_<version>_aarch64.dmg`。
 const dmgDirectory = path.join(context.bundleRoot, 'macos');
 fs.mkdirSync(dmgDirectory, { recursive: true });
 const dmg = path.join(dmgDirectory, firstInstallName);
@@ -170,7 +174,7 @@ const release = await generateUpdateManifest(context);
 assert.equal(
   path.resolve(release.downloadArtifact),
   path.resolve(dmg),
-  '首装包必须锁定本次生成的 universal DMG',
+  '首装包必须锁定本次生成的 arm64 DMG',
 );
 
 // 上传前门禁：用产物里烘焙的公钥复核更新包签名。验不过就停在这里，绝不写 OSS。
@@ -266,8 +270,9 @@ fs.writeFileSync(
         firstInstallSha256: dmgHash,
         manifest: 'latest.json',
       },
-      smokes: ['arm64', 'x86_64'],
-      intelSmoke: process.arch === 'arm64' ? 'Rosetta' : 'native',
+      // 单架构发布：只跑 arm64 隔离 smoke；Intel 未支持（清单里没有 darwin-x86_64 键）。
+      smokes: ['arm64'],
+      manifestPlatformKeys: resolveManifestPlatformKeys(context.target),
     },
     null,
     2,
diff --git a/apps/ai-game-creator-shell/scripts/build-release.test.mjs b/apps/ai-game-creator-shell/scripts/build-release.test.mjs
index 732302eb1..59e1a878b 100644
--- a/apps/ai-game-creator-shell/scripts/build-release.test.mjs
+++ b/apps/ai-game-creator-shell/scripts/build-release.test.mjs
@@ -211,6 +211,9 @@ test('packaged renderer receives the same channel as the updater manifest', () =
   });
   let spawnOptions;
   runTauriBuild([], context, {
+    // 必须 stub：真实 staging 会用宿主平台（如 macOS 的 darwin/arm64）去对默认的
+    // Windows 目标做一致性校验，在非 Windows 主机上直接失败——本用例只关心渠道注入。
+    stageRuntime: () => {},
     spawn: (_binary, _args, options) => {
       spawnOptions = options;
       return { status: 0 };
diff --git a/apps/ai-game-creator-shell/scripts/prepare-macos-codex.test.mjs b/apps/ai-game-creator-shell/scripts/prepare-macos-codex.test.mjs
index 4caae3656..b62fe76a1 100644
--- a/apps/ai-game-creator-shell/scripts/prepare-macos-codex.test.mjs
+++ b/apps/ai-game-creator-shell/scripts/prepare-macos-codex.test.mjs
@@ -178,8 +178,12 @@ test('macOS release entry and smoke script derive product names from config and
   assert.ok(entry.includes('readProductName'), '入口必须从 Tauri 配置读产品名');
   assert.ok(!entry.includes('陶泥儿'), 'macOS 发布入口不得写死产品名');
   assert.ok(
-    entry.includes('_${version}_universal.dmg'),
-    '首装包名必须保留清单侧唯一匹配所需的后缀',
+    entry.includes("const macTarget = 'aarch64-apple-darwin'"),
+    'macOS 发布入口必须固定单架构目标',
+  );
+  assert.ok(
+    entry.includes('_${version}_aarch64.dmg'),
+    '首装包名必须保留清单侧单架构分支唯一匹配所需的后缀（Tauri 口径 aarch64）',
   );
 
   const smoke = fs.readFileSync(
diff --git a/apps/ai-game-creator-shell/scripts/stage-node-runtime.mjs b/apps/ai-game-creator-shell/scripts/stage-node-runtime.mjs
index e712534d6..489ce0b2b 100644
--- a/apps/ai-game-creator-shell/scripts/stage-node-runtime.mjs
+++ b/apps/ai-game-creator-shell/scripts/stage-node-runtime.mjs
@@ -65,6 +65,17 @@ export function targetRuntime(target) {
     'aarch64-apple-darwin': ['darwin', 'arm64'],
     'x86_64-apple-darwin': ['darwin', 'x64'],
   };
+  // 随包 Node 是**单架构**官方发行版：一份运行时只服务它自己的架构。
+  // macOS 发布当前固定为 aarch64-apple-darwin 单架构包（Intel 未支持），
+  // universal 目标没有正确的运行时来源，必须失败关闭——绝不能退化成
+  // 「按宿主架构暂存一份 arm64」：那样通用包自检（按 process.arch）能过，
+  // 但 Intel 机器上这份运行时不可执行，用户拿到的是坏包。
+  if (target === 'universal-apple-darwin')
+    throw new Error(
+      'Node 运行时不支持 universal-apple-darwin：随包 Node 只有单架构发行版，' +
+        '通用包需按架构各带一份（另行下载另一架构官方发行版）之后才能构建；' +
+        '当前 macOS 发布固定为 aarch64-apple-darwin 单架构',
+    );
   const value = targets[target];
   if (!value) throw new Error(`Node 运行时不支持发布目标：${target}`);
   return { platform: value[0], arch: value[1] };
diff --git a/apps/ai-game-creator-shell/scripts/stage-node-runtime.test.mjs b/apps/ai-game-creator-shell/scripts/stage-node-runtime.test.mjs
index 8a55c6b3a..c2b52afb1 100644
--- a/apps/ai-game-creator-shell/scripts/stage-node-runtime.test.mjs
+++ b/apps/ai-game-creator-shell/scripts/stage-node-runtime.test.mjs
@@ -281,7 +281,11 @@ test('native target and macOS dynamic dependency policy reject nonportable Node'
     platform: 'darwin',
     arch: 'arm64',
   });
-  assert.throws(() => targetRuntime('universal-apple-darwin'), /不支持/u);
+  // universal 必须失败关闭：只带宿主架构那一份运行时，Intel 上不可执行。
+  assert.throws(
+    () => targetRuntime('universal-apple-darwin'),
+    /universal-apple-darwin/u,
+  );
   assertPortableMacNode(
     '/node:\n\t/usr/lib/libSystem.B.dylib (compatibility version 1)\n',
   );
diff --git a/apps/ai-game-creator-shell/src/features/resource-canvas/ResourceCanvasAssetGenerationPanelView.tsx b/apps/ai-game-creator-shell/src/features/resource-canvas/ResourceCanvasAssetGenerationPanelView.tsx
index 68886de45..e1e5f215d 100644
--- a/apps/ai-game-creator-shell/src/features/resource-canvas/ResourceCanvasAssetGenerationPanelView.tsx
+++ b/apps/ai-game-creator-shell/src/features/resource-canvas/ResourceCanvasAssetGenerationPanelView.tsx
@@ -235,8 +235,14 @@ export function ResourceCanvasAssetGenerationPanelView({
   /**
    * 参考选择只对有真实参考能力的入口呈现。
    *
-   * 图集只接受单张规范引用、图标规范本身就是权威规范图产出方：这两类入口不给选择器，
-   * 原生侧同样拒绝额外参考（不是静默丢弃）。
+   * `@` 引用输入区是**共享组件**（`ResourceReferenceInput`，聊天 / 快速编辑 / 这里同一份），
+   * 这一处只是「要不要挂它」的唯一分支：判据在 `resourceCanvasAssetGenerationAcceptsReferences`，
+   * 不在这里另写一套 kind 清单。
+   *
+   * 拒绝用户参考的只有**图集**（`icon-spritesheet`）：按合同它只接受单张权威规范引用，
+   * 原生侧对多余参考是**显式拒绝**（不是静默丢弃）。图标规范（`icon-spec`）虽然产出权威规范图，
+   * 但生成时同样可以带参考图，上限与普通生成一致——它**有** `@` 选择器。
+   * 两端必须同一个词：Rust 侧是 `platform_art_asset_kind_accepts_user_reference_assets`。
    */
   const referenceEnabled =
     resourceCanvasAssetGenerationAcceptsReferences(action);
@@ -494,6 +500,25 @@ export function ResourceCanvasAssetGenerationPanelView({
             {resolveEditorImageSizeLabel({ aspectRatio, imageSize })}
           </span>
         )}
+        {referenceEnabled ? null : (
+          /*
+            不给 `@` 的入口要**当场**说清为什么，否则用户只会读成「这里漏了一个按钮」
+            （验收现场那条「生成图标素材没法 @」就是这么来的）。
+
+            原因在通道而不在 UI：图集走平台 `icon-spritesheets` 通道，提交体只有一张
+            `referenceId`（独立权威规范图）+ `iconDescriptions` + 切片参数，客户端这一侧对
+            「图集带用户参考」是**显式拒绝**（`normalize_platform_art_reference_asset_ids`：
+            「透明美术图集只接受规范图引用，不接受用户参考素材」），所以放开 UI 也提交不出去。
+            判据与文案都由同一处给出，别的 reference-free 入口将来接入时不必各写一份。
+          */
+          <p
+            className="resource-canvas-asset-generation-reference-free"
+            data-resource-canvas-generation-reference-free={action.assetKind}
+          >
+            该入口走平台图集通道：参考只有一张权威规范图（图标规范），
+            不支持另挑参考图——把需要哪些图标写进提示词。
+          </p>
+        )}
         {referenceProblemNotice ? (
           <p
             className="game-resource-generation-error"
diff --git a/apps/ai-game-creator-shell/src/features/resource-canvas/ResourceCanvasAssetGenerationTasksPanelView.tsx b/apps/ai-game-creator-shell/src/features/resource-canvas/ResourceCanvasAssetGenerationTasksPanelView.tsx
index 539131016..f526ea984 100644
--- a/apps/ai-game-creator-shell/src/features/resource-canvas/ResourceCanvasAssetGenerationTasksPanelView.tsx
+++ b/apps/ai-game-creator-shell/src/features/resource-canvas/ResourceCanvasAssetGenerationTasksPanelView.tsx
@@ -3,6 +3,7 @@ import './resourceCanvasAssetGenerationTasksSidebar.css';
 import { ListChecks, X } from 'lucide-react';
 import { useEffect, useMemo, useRef, useState } from 'react';
 
+import { useLiveNow } from '../project-workspace/useLiveNow';
 import {
   RESOURCE_CANVAS_ASSET_GENERATION_STATUS_LABELS,
   resourceCanvasAssetGenerationElapsedLabel,
@@ -44,12 +45,18 @@ export type ResourceCanvasAssetGenerationTasksPanelViewProps = {
   /** 定位到该任务产出的素材卡（宿主复用既有 `pendingResourceFocusRef` 聚焦链）。 */
   onFocusTask: (task: ResourceCanvasAssetGenerationTask) => void;
   /**
-   * 锚点落在哪个工作面：资源栏目画布 / 运行表现层 / UI 编辑器。
+   * 锚点落在哪个工作面：资源总览页 / 资源栏目画布 / 运行表现层 / UI 编辑器。
    *
-   * 三处右上角的既有 chrome 不同（运行表现层右上角是版本入口、UI 编辑器是整页编辑器壳），
-   * 所以坐标由这一档在样式里分档给出；缺省按资源栏目画布算。
+   * 四处的既有 chrome 不同，所以坐标由这一档在样式里分档给出；缺省按资源栏目画布算：
+   * - `canvas-overview`（资源总览 / 画本）：顶部没有钉死的栏目标题栏，锚点贴画布顶边内缩；
+   * - `canvas`（资源栏目画布）：顶部钉着**整宽**的栏目标题栏（含「返回资源总览」入口），
+   *   锚点必须让开它，否则会压在那条标题栏上（验收现场那条「生成任务和标题栏重叠」）；
+   * - `run`：右上角被版本入口占着；
+   * - `editor`：UI 编辑器是整页编辑器壳。
+   *
+   * 两页之间切换时锚点高度走样式里的 transition，不瞬移。
    */
-  placement?: 'canvas' | 'run' | 'editor';
+  placement?: 'canvas-overview' | 'canvas' | 'run' | 'editor';
 };
 
 /**
@@ -98,9 +105,57 @@ function sortResourceCanvasGenerationTaskRows(
   );
 }
 
+/**
+ * 一条图片类生成任务的「已耗时」。
+ *
+ * 刷新粒度走对话侧同一份 `useLiveNow`（`LIVE_TIMER_TICK_MS = 100`）：不足一分钟的耗时显示到
+ * 0.1 秒，若按 1 秒一跳，用户看到的是一块「带小数却一格一格跳」的表，像卡住不动。
+ *
+ * 时钟只订在**这一行**上（叶子节点）：面板上通常同时挂着多条任务，把 100ms 的 tick 放在整块
+ * 面板上等于每 0.1 秒重建整个列表——`useLiveNow` 的注释写明「调用方必须是叶子节点」。任务收口
+ * 后（终态）不再订阅，已耗时就定格在账本给的结束时间上。
+ */
+function AssetGenerationElapsedLabel({
+  task,
+}: {
+  task: ResourceCanvasAssetGenerationTask;
+}) {
+  const now = useLiveNow(!resourceCanvasAssetGenerationTaskIsTerminal(task));
+  return (
+    <span className="game-resource-generation-task-card-elapsed">
+      {`已耗时 ${resourceCanvasAssetGenerationElapsedLabel(
+        resourceCanvasAssetGenerationTaskElapsedMillis(task, now),
+      )}`}
+    </span>
+  );
+}
+
+/**
+ * 一条派生/修改任务的「已耗时」。
+ *
+ * 同上：粒度与对话侧同一份 `useLiveNow`，只换资源编辑账本那一份文案入口。从原生账本恢复来的
+ * 收口记录没有结束时间（`elapsedMillis === null`）时整格不渲染——宁可不显示，也不拿创建时间
+ * 冒充耗时。
+ */
+function ResourceEditElapsedLabel({
+  task,
+}: {
+  task: ResourceCanvasResourceEditTask;
+}) {
+  const now = useLiveNow(!resourceCanvasResourceEditTaskIsTerminal(task));
+  const elapsedMillis = resourceCanvasResourceEditTaskElapsedMillis(task, now);
+  if (elapsedMillis === null) {
+    return null;
+  }
+  return (
+    <span className="game-resource-generation-task-card-elapsed">
+      {`已耗时 ${resourceCanvasResourceEditElapsedLabel(elapsedMillis)}`}
+    </span>
+  );
+}
+
 function assetGenerationTaskRow(
   task: ResourceCanvasAssetGenerationTask,
-  nowMillis: number,
   onFocusTask: (task: ResourceCanvasAssetGenerationTask) => void,
 ) {
   const focusable = task.status === 'completed' && Boolean(task.assetId);
@@ -128,11 +183,7 @@ function assetGenerationTaskRow(
         <span className="game-resource-generation-task-card-phase">
           {task.phaseDetail}
         </span>
-        <span className="game-resource-generation-task-card-elapsed">
-          {`已耗时 ${resourceCanvasAssetGenerationElapsedLabel(
-            resourceCanvasAssetGenerationTaskElapsedMillis(task, nowMillis),
-          )}`}
-        </span>
+        <AssetGenerationElapsedLabel task={task} />
       </div>
       {task.error ? (
         <p className="game-resource-generation-task-card-error" role="alert">
@@ -160,14 +211,7 @@ function assetGenerationTaskRow(
  * 给的待办记录里没有产物 id，编一个指向不明的跳转不如不给；② 提示词单独一行，用户要能认出手上
  * 这行是哪一次修改。
  */
-function resourceEditTaskRow(
-  task: ResourceCanvasResourceEditTask,
-  nowMillis: number,
-) {
-  const elapsedMillis = resourceCanvasResourceEditTaskElapsedMillis(
-    task,
-    nowMillis,
-  );
+function resourceEditTaskRow(task: ResourceCanvasResourceEditTask) {
   return (
     <li
       key={task.operationId}
@@ -193,11 +237,7 @@ function resourceEditTaskRow(
         <span className="game-resource-generation-task-card-phase">
           {task.phaseDetail}
         </span>
-        {elapsedMillis === null ? null : (
-          <span className="game-resource-generation-task-card-elapsed">
-            {`已耗时 ${resourceCanvasResourceEditElapsedLabel(elapsedMillis)}`}
-          </span>
-        )}
+        <ResourceEditElapsedLabel task={task} />
       </div>
       {task.error ? (
         <p className="game-resource-generation-task-card-error" role="alert">
@@ -218,12 +258,11 @@ function resourceEditTaskRow(
 
 function resourceCanvasGenerationTaskRowNode(
   row: ResourceCanvasGenerationTaskRow,
-  nowMillis: number,
   onFocusTask: (task: ResourceCanvasAssetGenerationTask) => void,
 ) {
   return row.source === 'asset-generation'
-    ? assetGenerationTaskRow(row.task, nowMillis, onFocusTask)
-    : resourceEditTaskRow(row.task, nowMillis);
+    ? assetGenerationTaskRow(row.task, onFocusTask)
+    : resourceEditTaskRow(row.task);
 }
 
 /**
@@ -251,7 +290,6 @@ export function ResourceCanvasAssetGenerationTasksPanelView({
   onFocusTask,
   placement = 'canvas',
 }: ResourceCanvasAssetGenerationTasksPanelViewProps) {
-  const [nowMillis, setNowMillis] = useState(() => Date.now());
   /**
    * 收起动画期：`open` 已经变 false，但侧栏还要留在 DOM 里把 `…-leave` 播完
    * （`entering` 是刚打开时给根节点挂进场动画的那一档）。
@@ -285,7 +323,6 @@ export function ResourceCanvasAssetGenerationTasksPanelView({
   );
   const done = ordered.filter(resourceCanvasGenerationTaskRowIsTerminal);
   const inFlightCount = active.length;
-  const hasLiveTask = inFlightCount > 0;
   const visibleDone = done.slice(
     0,
     RESOURCE_CANVAS_ASSET_GENERATION_DONE_SECTION_LIMIT,
@@ -314,14 +351,12 @@ export function ResourceCanvasAssetGenerationTasksPanelView({
     ? { inFlightCount, ordered, active, visibleDone, done }
     : lastRenderedRef.current;
 
-  // 已耗时是前端计时（后端只给时间戳）：只在还有未终态任务时走秒表，全部收口后停掉。
-  useEffect(() => {
-    if (!hasLiveTask) {
-      return undefined;
-    }
-    const timer = setInterval(() => setNowMillis(Date.now()), 1_000);
-    return () => clearInterval(timer);
-  }, [hasLiveTask]);
+  /*
+   * 已耗时是前端计时（后端只给时间戳）：秒表**不在这一层**——面板上通常同时挂着多条任务，
+   * 在这里订阅 100ms 的 tick 等于每 0.1 秒重建整个侧栏。计时下沉到每一行的
+   * `AssetGenerationElapsedLabel` / `ResourceEditElapsedLabel`，只在**还有未终态任务**时
+   * 订阅（终态行定格在账本的结束时间上）。
+   */
 
   /**
    * open → 进场，close → 先留一帧播 `…-leave` 再卸载。
@@ -430,11 +465,7 @@ export function ResourceCanvasAssetGenerationTasksPanelView({
                   ) : (
                     <ul className="game-resource-generation-tasks-list">
                       {rendered.active.map((row) =>
-                        resourceCanvasGenerationTaskRowNode(
-                          row,
-                          nowMillis,
-                          onFocusTask,
-                        ),
+                        resourceCanvasGenerationTaskRowNode(row, onFocusTask),
                       )}
                     </ul>
                   )}
@@ -457,11 +488,7 @@ export function ResourceCanvasAssetGenerationTasksPanelView({
                     <>
                       <ul className="game-resource-generation-tasks-list">
                         {rendered.visibleDone.map((row) =>
-                          resourceCanvasGenerationTaskRowNode(
-                            row,
-                            nowMillis,
-                            onFocusTask,
-                          ),
+                          resourceCanvasGenerationTaskRowNode(row, onFocusTask),
                         )}
                       </ul>
                       {rendered.done.length > rendered.visibleDone.length ? (
diff --git a/apps/ai-game-creator-shell/src/features/resource-canvas/ResourceCanvasGenerationPlaceholderCardView.tsx b/apps/ai-game-creator-shell/src/features/resource-canvas/ResourceCanvasGenerationPlaceholderCardView.tsx
index 2c0305d3b..503a6489a 100644
--- a/apps/ai-game-creator-shell/src/features/resource-canvas/ResourceCanvasGenerationPlaceholderCardView.tsx
+++ b/apps/ai-game-creator-shell/src/features/resource-canvas/ResourceCanvasGenerationPlaceholderCardView.tsx
@@ -2,6 +2,7 @@ import './resourceCanvasGenerationPanel.css';
 
 import { Sparkles, X } from 'lucide-react';
 import type { PointerEvent as ReactPointerEvent } from 'react';
+import { useRef } from 'react';
 
 import {
   RESOURCE_CANVAS_GENERATION_PLACEHOLDER_STATUS_LABELS,
@@ -44,6 +45,14 @@ export function ResourceCanvasGenerationPlaceholderCardView({
   onTogglePanel,
   onRemove,
 }: ResourceCanvasGenerationPlaceholderCardViewProps) {
+  /**
+   * 这一次点击手势是从哪儿起手的。
+   *
+   * 删除按钮自己会 `stopPropagation`，所以「按在删除按钮上、松手落回卡片」这种手势里，
+   * 浏览器把 `click` 派给两者的共同祖先（也就是这张卡）——删除按钮的删除没发生，卡片的
+   * 「开合生成浮层」却执行了。判据不看移动距离：**从删除按钮起手的手势永远不是「点卡片」**。
+   */
+  const gestureOriginRef = useRef<'card' | 'remove'>('card');
   return (
     <div
       className={`game-resource-generation-placeholder${active ? ' is-active' : ''}${dragging ? ' is-dragging' : ''}`}
@@ -58,13 +67,21 @@ export function ResourceCanvasGenerationPlaceholderCardView({
       role="button"
       tabIndex={0}
       aria-label={`${placeholder.assetName}（${RESOURCE_CANVAS_GENERATION_PLACEHOLDER_STATUS_LABELS[placeholder.status]}）`}
-      onPointerDown={onPointerDown}
+      onPointerDown={(event) => {
+        gestureOriginRef.current = 'card';
+        onPointerDown(event);
+      }}
       onPointerMove={onPointerMove}
       onPointerUp={onPointerUp}
       onPointerCancel={onPointerCancel}
       onLostPointerCapture={onPointerCancel}
       onClick={(event) => {
         event.stopPropagation();
+        const origin = gestureOriginRef.current;
+        gestureOriginRef.current = 'card';
+        if (origin === 'remove') {
+          return;
+        }
         onTogglePanel();
       }}
       onKeyDown={(event) => {
@@ -87,7 +104,12 @@ export function ResourceCanvasGenerationPlaceholderCardView({
       <button
         type="button"
         aria-label={`删除占位 ${placeholder.assetName}`}
-        onPointerDown={(event) => event.stopPropagation()}
+        onPointerDown={(event) => {
+          // 卡片不接管这一次手势（不拖动），但把起手点记下来：松手落回卡片时那次 click
+          // 不该被当成「点卡片开浮层」。
+          gestureOriginRef.current = 'remove';
+          event.stopPropagation();
+        }}
         onClick={(event) => {
           event.stopPropagation();
           onRemove();
diff --git a/apps/ai-game-creator-shell/src/features/resource-canvas/resourceCanvasAssetGenerationTasksSidebar.css b/apps/ai-game-creator-shell/src/features/resource-canvas/resourceCanvasAssetGenerationTasksSidebar.css
index 0605445d1..fc6cbf3d3 100644
--- a/apps/ai-game-creator-shell/src/features/resource-canvas/resourceCanvasAssetGenerationTasksSidebar.css
+++ b/apps/ai-game-creator-shell/src/features/resource-canvas/resourceCanvasAssetGenerationTasksSidebar.css
@@ -37,6 +37,34 @@
   align-items: flex-start;
   gap: 0.45rem;
   pointer-events: auto;
+  /*
+   * 资源总览 ↔ 资源栏目画布之间切换时，锚点要往下挪开那条钉死的标题栏：高度差走一段过渡，
+   * 不瞬移（两页的坐标档见下面的 `[data-generation-tasks-placement]` 规则）。
+   *
+   * 只过渡 `margin-top`：锚点是 stage 网格里 `align-self: start` 的覆盖式条目，改它的外边距
+   * 不会让工作面那一行 reflow，画布与资源卡排布一动不动。
+   */
+  transition: margin-top 180ms ease-out;
+}
+
+/*
+ * 资源总览（画本）页：顶部没有钉死的标题栏——栏目名与计数都活在画本世界里跟着视口平移，
+ * 所以锚点仍按「画布顶边内缩一小段」定位。这一档显式写出来，是为了让「两页高度不同」这件事
+ * 在样式里看得见，而不是靠缺省值隐式成立。
+ */
+.game-resource-generation-tasks-anchor[data-generation-tasks-placement='canvas-overview'] {
+  margin-top: 0.85rem;
+}
+
+/*
+ * 资源栏目画布页：顶部钉着**整宽**的栏目标题栏（`.game-resource-book-scene-titlebar`，
+ * 最小高 42px，`styles.css` 里定义），右端就是「返回资源总览」入口。锚点必须让开这一条，
+ * 否则那枚开关会直接压在它上面（验收现场那条「生成任务和标题栏重叠」就是这么来的）。
+ *
+ * 2.625rem 就是那条标题栏的 42px：两处必须一起改（有声明级守卫用例钉住这个关系）。
+ */
+.game-resource-generation-tasks-anchor[data-generation-tasks-placement='canvas'] {
+  margin-top: calc(2.625rem + 0.5rem);
 }
 
 .game-resource-generation-tasks-anchor[data-generation-tasks-placement='run'] {
@@ -439,6 +467,11 @@
 
 /* 降低动效偏好：进场 / 收起动画、悬停位移与呼吸全部关掉。 */
 @media (prefers-reduced-motion: reduce) {
+  /* 锚点高度过渡也关掉：两页切换时锚点直接落到目标高度。 */
+  .game-resource-generation-tasks-anchor {
+    transition: none;
+  }
+
   .game-resource-generation-tasks-sidebar,
   .game-resource-generation-tasks-sidebar.is-leaving {
     animation: none;
diff --git a/apps/ai-game-creator-shell/src/features/resource-canvas/resourceCanvasCardGestureModel.ts b/apps/ai-game-creator-shell/src/features/resource-canvas/resourceCanvasCardGestureModel.ts
new file mode 100644
index 000000000..34f19c897
--- /dev/null
+++ b/apps/ai-game-creator-shell/src/features/resource-canvas/resourceCanvasCardGestureModel.ts
@@ -0,0 +1,46 @@
+import { RESOURCE_CANVAS_DRAG_THRESHOLD } from '../../view/project-development/resourceCanvasLayoutModel';
+
+/**
+ * 画布上「这一次手势是拖动还是点击」的唯一判据。
+ *
+ * 画布上的卡片既是可点的控件、又是可拖的对象，而浏览器在 pointerdown 与 pointerup 落在同一个
+ * 节点上时**一定会补一次 `click`**——中间移动了多少都不管。所以：
+ *
+ * 1. 「开始拖动」这件事只能由**移动距离**判，不能由「收到过 pointermove」判：按下时浏览器
+ *    就可能补一次零位移的 move，用后者会让一次普通点击直接变成一次拖动；
+ * 2. 拖动结束后紧跟的那次 `click` 是这次拖动的副产物，必须被**一次性吃掉**，否则拖完卡片会
+ *    顺手触发卡片自己的点击语义（资源卡是选中、生成占位卡是开合生成浮层）。
+ *
+ * 资源卡（`view/project-development/index.tsx`）与生成占位卡
+ * （`useResourceCanvasGenerationPlaceholders`）共用这里的阈值与判据：两处各写一份的结果就是
+ * 一边修好、另一边继续漏（占位卡拖一下就弹生成浮层，就是这么来的）。
+ */
+export function resourceCanvasGestureExceededDragThreshold({
+  startClientX,
+  startClientY,
+  clientX,
+  clientY,
+  threshold = RESOURCE_CANVAS_DRAG_THRESHOLD,
+}: {
+  /** 按下时的屏幕坐标。 */
+  startClientX: number;
+  startClientY: number;
+  /** 当前屏幕坐标。 */
+  clientX: number;
+  clientY: number;
+  /** 阈值（屏幕 px）；缺省用画布统一口径 `RESOURCE_CANVAS_DRAG_THRESHOLD`。 */
+  threshold?: number;
+}): boolean {
+  if (
+    ![startClientX, startClientY, clientX, clientY, threshold].every((value) =>
+      Number.isFinite(value),
+    )
+  ) {
+    // 几何不成立时按「没有拖动」算：宁可把一次拖动当点击（用户再点一下即可），
+    // 也不能把一次点击误判成拖动而吃掉它。
+    return false;
+  }
+  return (
+    Math.hypot(clientX - startClientX, clientY - startClientY) >= threshold
+  );
+}
diff --git a/apps/ai-game-creator-shell/src/features/resource-canvas/resourceCanvasGenerationPanel.css b/apps/ai-game-creator-shell/src/features/resource-canvas/resourceCanvasGenerationPanel.css
index 9983b191c..566d0cff2 100644
--- a/apps/ai-game-creator-shell/src/features/resource-canvas/resourceCanvasGenerationPanel.css
+++ b/apps/ai-game-creator-shell/src/features/resource-canvas/resourceCanvasGenerationPanel.css
@@ -78,8 +78,16 @@
 .game-approval-dialog.resource-canvas-generation-floating-panel {
   position: absolute;
   z-index: 70;
-  /* 锚点给的是占位卡中心：不居中就会整体右偏半个面板宽（真实浏览器 x287 vs 卡中心 286 复现过）。 */
+  /*
+   * 锚点给的是占位卡中心（宿主会把它收进「浮层左右两边各留 12px」的区间，卡片靠边时浮层仍
+   * 完整落在画布内）：不居中就会整体右偏半个面板宽（真实浏览器 x287 vs 卡中心 286 复现过）。
+   */
   transform: translateX(-50%);
+  /*
+   * 宽度口径：`min(560px, 100% - 24px)`。这两个数在宿主侧算水平收口时要用同一份
+   * （`resourceCanvasGenerationVisibilityModel` 的 `RESOURCE_CANVAS_GENERATION_PANEL_MAX_WIDTH`
+   * 与 `..._VIEWPORT_INSET`），改一处必须改另一处，有声明级守卫用例钉住这个关系。
+   */
   width: min(560px, calc(100% - 24px));
   /* 外形走基类 token（= 网页端画布面板那一套），三块浮层因此长得一样。 */
   border: 1px solid var(--game-canvas-card-border, #e4c8ba);
@@ -172,3 +180,16 @@
   font-size: 11px;
   white-space: nowrap;
 }
+
+/*
+ * 「这一档为什么不给 @ 选择器」的说明行：只出现在不走用户参考的入口（今天是图集）。
+ *
+ * 它替掉的选择器不是「省一个控件」，而是一条平台通道差异——不写出来，用户只会看到
+ * 「提示词栏少了 @ 按钮」。允许折行（说明是句子，不是计数）。
+ */
+.resource-canvas-asset-generation-reference-free {
+  margin: 0;
+  color: #9a7d70;
+  font-size: 11px;
+  line-height: 1.45;
+}
diff --git a/apps/ai-game-creator-shell/src/features/resource-canvas/resourceCanvasGenerationVisibilityModel.ts b/apps/ai-game-creator-shell/src/features/resource-canvas/resourceCanvasGenerationVisibilityModel.ts
index b70d3ac3c..cf38149fa 100644
--- a/apps/ai-game-creator-shell/src/features/resource-canvas/resourceCanvasGenerationVisibilityModel.ts
+++ b/apps/ai-game-creator-shell/src/features/resource-canvas/resourceCanvasGenerationVisibilityModel.ts
@@ -90,16 +90,86 @@ export function revealResourceCanvasGenerationContent({
 }
 
 /**
- * 浮层该占多高、以及它挂在占位卡下面还是直接盖住占位卡。
+ * 生成浮层的宽度口径：最大宽度，以及与画布可视边之间必须留出的内缩。
+ *
+ * 与 `resourceCanvasGenerationPanel.css` 里的 `width: min(560px, calc(100% - 24px))` 同口径
+ * （24px = 两侧各 12px）。宿主按这对值算**水平收口**：浮层贴着占位卡，但恒定留在画布可视
+ * 范围内，不被画布边界切掉。两处一起改（有声明级守卫用例钉住这个关系）。
+ */
+export const RESOURCE_CANVAS_GENERATION_PANEL_MAX_WIDTH = 560;
+export const RESOURCE_CANVAS_GENERATION_PANEL_VIEWPORT_INSET = 12;
+
+/** 浮层在这个画布宽下的实际宽度（CSS px）。画布未就绪时退回最大宽度。 */
+export function resourceCanvasGenerationPanelWidth(
+  canvasWidth: number,
+): number {
+  if (!Number.isFinite(canvasWidth) || canvasWidth <= 0) {
+    return RESOURCE_CANVAS_GENERATION_PANEL_MAX_WIDTH;
+  }
+  return Math.max(
+    0,
+    Math.min(
+      RESOURCE_CANVAS_GENERATION_PANEL_MAX_WIDTH,
+      canvasWidth - RESOURCE_CANVAS_GENERATION_PANEL_VIEWPORT_INSET * 2,
+    ),
+  );
+}
+
+/**
+ * 浮层锚点（贴着占位卡下沿居中那条水平中线）的收口。
+ *
+ * 生成浮层比资源卡宽得多（560 vs 180），卡片靠近画布左右边缘时，居中展开的浮层会有一半落到
+ * 画布之外被 `overflow: hidden` 切掉——用户看到的就是「生成窗口和画布边缘撞在一起」。这里把
+ * 锚点收在「浮层左右两边各留 `inset`」的区间里：浮层仍然贴着卡片，但**恒定完整落在画布内**，
+ * 平移、缩放、拖动卡片都不需要另做补偿。
+ *
+ * 画布比浮层还窄时不硬撑：居中交给 CSS 的宽度收口（`calc(100% - 24px)`）。
+ */
+export function clampResourceCanvasGenerationPanelAnchorX({
+  centerX,
+  canvasWidth,
+  panelWidth,
+  inset = RESOURCE_CANVAS_GENERATION_PANEL_VIEWPORT_INSET,
+}: {
+  /** 未收口锚点：占位卡中心的屏幕 X（画布内坐标）。 */
+  centerX: number;
+  canvasWidth: number;
+  panelWidth: number;
+  inset?: number;
+}): number {
+  if (
+    ![centerX, canvasWidth, panelWidth, inset].every((value) =>
+      Number.isFinite(value),
+    ) ||
+    canvasWidth <= 0 ||
+    panelWidth <= 0
+  ) {
+    return centerX;
+  }
+  const min = Math.max(0, inset) + panelWidth / 2;
+  const max = canvasWidth - Math.max(0, inset) - panelWidth / 2;
+  if (max <= min) {
+    return canvasWidth / 2;
+  }
+  return Math.min(max, Math.max(min, centerX));
+}
+
+/**
+ * 浮层该占多高、顶边落在哪、以及它挂在占位卡下面还是直接盖住占位卡。
  *
  * 三版都踩过的坑，这里一次钉住：
  * 1. 用 `window.innerHeight` 当上界 → 面板垂到底栏下面，提交按钮点不到；
  * 2. 用「当前顶边到安全底边」当上界 → 打开瞬间只剩一百多像素，只见标题与提交行；
  * 3. 用固定最小高度硬顶 → 底边反过来被顶出画布（`overflow: hidden` 直接切掉）。
  *
- * 正确口径：只按**画布安全带**（画布高 − 顶栏 − 底栏）分配。装得下「占位卡 + 间隙 + 浮层」时
- * 浮层挂在卡下面；装不下时（例如缩放 1.5，卡就占 192px）浮层改为**与卡顶边对齐、盖住占位卡**，
- * 用整条安全带当编辑高度——占位允许被压到浮层后面，但全局缩放不变、提交按钮永远可见。
+ * 正确口径：按**占位卡在画布上的真实屏幕位置**分配「卡下沿到安全底边」这一段。装得下可编辑
+ * 高度时浮层挂在卡下面；装不下时（例如缩放 1.5，卡就占 192px；又或者占位被排到画布下半屏）
+ * 浮层改为**与卡顶边对齐、盖住占位卡**，用「卡顶边到安全底边」当编辑高度——占位允许被压到
+ * 浮层后面，但全局缩放不变、提交按钮永远可见。
+ *
+ * 第四版修的就是这里：早先只吃「安全带高度 − 卡高」，等于假设占位卡永远贴在安全带上沿。占位卡
+ * 是追加在栏目内容最下方的，落到下半屏是常态，于是浮层底边越过画布下沿被切掉——验收现场那条
+ * 「生成窗口和画布边缘碰撞」。现在顶边与可用高度都由真实位置算出来，浮层恒定完整落在画布内。
  */
 export const RESOURCE_CANVAS_GENERATION_PANEL_MIN_HEIGHT = 280;
 export const RESOURCE_CANVAS_GENERATION_PANEL_FLOOR_HEIGHT = 160;
@@ -108,6 +178,8 @@ export const RESOURCE_CANVAS_GENERATION_PANEL_MAX_HEIGHT = 520;
 export type ResourceCanvasGenerationPanelPlacement = {
   /** 浮层顶边是否与占位卡顶边对齐（盖住占位）而不是挂在卡下面。 */
   overlaysAnchor: boolean;
+  /** 浮层顶边（CSS px，画布内坐标，已收进安全带）。 */
+  top: number;
   /** 浮层可用的高度（CSS px）。 */
   availableHeight: number;
 };
@@ -116,6 +188,7 @@ export function resolveResourceCanvasGenerationPanelPlacement({
   canvasHeight,
   topInset,
   bottomInset,
+  anchorTop,
   anchorHeight,
   gap = 12,
   minHeight = RESOURCE_CANVAS_GENERATION_PANEL_MIN_HEIGHT,
@@ -126,6 +199,8 @@ export function resolveResourceCanvasGenerationPanelPlacement({
   canvasHeight: number;
   topInset: number;
   bottomInset: number;
+  /** 浮层锚点那一块（占位卡）的**屏幕**顶边（画布内坐标）。 */
+  anchorTop: number;
   /** 浮层锚点那一块（占位卡）的**屏幕**高度（世界尺寸 × 当前缩放）。 */
   anchorHeight: number;
   gap?: number;
@@ -133,28 +208,41 @@ export function resolveResourceCanvasGenerationPanelPlacement({
   floor?: number;
   maxHeight?: number;
 }): ResourceCanvasGenerationPanelPlacement {
+  const safeTop = Math.max(0, topInset);
+  const safeBottom = Math.max(
+    safeTop + 1,
+    canvasHeight - Math.max(0, bottomInset),
+  );
   if (
     !Number.isFinite(canvasHeight) ||
+    !Number.isFinite(anchorTop) ||
     !Number.isFinite(anchorHeight) ||
     canvasHeight <= 0
   ) {
-    return { overlaysAnchor: false, availableHeight: minHeight };
-  }
-  const bandHeight = Math.max(
-    0,
-    canvasHeight - Math.max(0, topInset) - Math.max(0, bottomInset),
-  );
-  const below = bandHeight - Math.max(0, anchorHeight) - Math.max(0, gap);
-  if (below >= minHeight) {
     return {
       overlaysAnchor: false,
-      availableHeight: Math.min(maxHeight, Math.floor(below)),
+      top: safeTop,
+      availableHeight: minHeight,
     };
   }
-  // 卡下面塞不下可编辑高度：改用「盖住占位卡」的整条安全带。
-  const overlayBudget = Math.max(0, bandHeight - Math.max(0, gap));
+  const belowTop = anchorTop + Math.max(0, anchorHeight) + Math.max(0, gap);
+  const belowSpace = safeBottom - belowTop;
+  if (belowSpace >= minHeight) {
+    return {
+      overlaysAnchor: false,
+      top: belowTop,
+      availableHeight: Math.min(maxHeight, Math.floor(belowSpace)),
+    };
+  }
+  /*
+   * 卡下面塞不下可编辑高度：改用「盖住占位卡」——顶边取卡顶边，但不能越出安全带
+   * （卡自己贴着下沿时，至少给出一屏可编辑高度，而不是把浮层顶到画布外面去）。
+   */
+  const overlayTop = Math.max(safeTop, Math.min(anchorTop, safeBottom - floor));
+  const overlayBudget = Math.max(0, safeBottom - overlayTop);
   return {
     overlaysAnchor: true,
+    top: overlayTop,
     availableHeight:
       overlayBudget >= floor
         ? Math.min(maxHeight, Math.floor(overlayBudget))
diff --git a/apps/ai-game-creator-shell/src/features/resource-canvas/useResourceCanvasGenerationPlaceholders.ts b/apps/ai-game-creator-shell/src/features/resource-canvas/useResourceCanvasGenerationPlaceholders.ts
index 753d259fa..0beb13a7c 100644
--- a/apps/ai-game-creator-shell/src/features/resource-canvas/useResourceCanvasGenerationPlaceholders.ts
+++ b/apps/ai-game-creator-shell/src/features/resource-canvas/useResourceCanvasGenerationPlaceholders.ts
@@ -2,6 +2,7 @@ import type { PointerEvent as ReactPointerEvent } from 'react';
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 
 import type { ProjectResourceCanvasCategory } from '../../../../../packages/shared/src/contracts/gameCreationApp';
+import { resourceCanvasGestureExceededDragThreshold } from './resourceCanvasCardGestureModel';
 import {
   bindResourceCanvasGenerationPlaceholderTask,
   failResourceCanvasGenerationPlaceholder,
@@ -33,6 +34,7 @@ type PlaceholderDragState = {
   startX: number;
   startY: number;
   scale: number;
+  /** 这次手势**已经越过拖动阈值**（不是「收到过 pointermove」）。 */
   changed: boolean;
 };
 
@@ -70,17 +72,34 @@ export function useResourceCanvasGenerationPlaceholders({
   const placeholdersRef = useRef<ResourceCanvasGenerationPlaceholder[]>([]);
   placeholdersRef.current = placeholders;
   const dragRef = useRef<PlaceholderDragState | null>(null);
+  /**
+   * 拖动收尾的那次 `click` 一次性抑制：拖动（down/up 落在同一张卡上）必然引出一次 click，
+   * 不挡掉它，拖完占位就会顺手开合一次生成浮层。与资源卡那条链路同一口径
+   * （`skipNextResourceCardClickRef` + `deferSkippedResourceCardClickCleanup`）。
+   */
+  const suppressedClickDraftIdRef = useRef<string | null>(null);
+  const suppressedClickTimerRef = useRef<number | null>(null);
   const projectIdRef = useRef(projectId);
   projectIdRef.current = projectId;
 
+  /** 取消抑制（这一次手势不会有收尾 click，或者手势被取消时用）。 */
+  const clearDragClickSuppression = useCallback(() => {
+    if (suppressedClickTimerRef.current !== null) {
+      window.clearTimeout(suppressedClickTimerRef.current);
+      suppressedClickTimerRef.current = null;
+    }
+    suppressedClickDraftIdRef.current = null;
+  }, []);
+
   // 切项目：未提交草稿与界面位置一并作废，拖动中也要收掉，避免把上一份会话的占位写进新项目。
   useEffect(() => {
     dragRef.current = null;
     setDraggingDraftId(null);
+    clearDragClickSuppression();
     setPlaceholders((current) =>
       resourceCanvasGenerationPlaceholdersForProject(current, projectId),
     );
-  }, [projectId]);
+  }, [clearDragClickSuppression, projectId]);
 
   const createPlaceholder = useCallback(
     (input: ResourceCanvasGenerationPlaceholderDraftInput) => {
@@ -166,6 +185,47 @@ export function useResourceCanvasGenerationPlaceholders({
     return drag;
   }, []);
 
+  /**
+   * 松手之后把抑制再留**一个宏任务**，然后按 draftId 收干净。
+   *
+   * 计时起点是这条链路的关键：抑制必须在**手势越过阈值那一刻**就登记（那时还不知道会不会
+   * 出现收尾 click），但只能在**松手那一刻**才开始计时——`click` 是浏览器紧接着 `pointerup`
+   * 补发的（同一轮任务内），而一次真实拖动里 pointermove 会横跨很多轮宏任务。若在越过阈值时
+   * 就起 0ms 计时器，计时器早在松手之前就把抑制清掉了，收尾 click 照样生效；jsdom 里同步发
+   * move / up 看不见这一档，真实鼠标一定看得见（验收现场「拖一下就触发点击」仍在）。
+   *
+   * 与资源卡那条链路同口径（`deferSkippedResourceCardClickCleanup`）。
+   */
+  const deferDragClickSuppressionCleanup = useCallback((draftId: string) => {
+    if (suppressedClickTimerRef.current !== null) {
+      window.clearTimeout(suppressedClickTimerRef.current);
+    }
+    suppressedClickTimerRef.current = window.setTimeout(() => {
+      if (suppressedClickDraftIdRef.current === draftId) {
+        suppressedClickDraftIdRef.current = null;
+      }
+      suppressedClickTimerRef.current = null;
+    }, 0);
+  }, []);
+
+  /**
+   * 消费一次「这次 click 是拖动收尾的副产物」：宿主在开合浮层前问一次，返回 true 就跳过。
+   *
+   * 判定要写在手势那一侧（这里），不能写进卡片组件：拖动状态、阈值与坐标都在这一层，
+   * 卡片只该拿到「点我一下」这个语义。
+   */
+  const consumeDragClick = useCallback((draftId: string) => {
+    if (suppressedClickDraftIdRef.current !== draftId) {
+      return false;
+    }
+    suppressedClickDraftIdRef.current = null;
+    if (suppressedClickTimerRef.current !== null) {
+      window.clearTimeout(suppressedClickTimerRef.current);
+      suppressedClickTimerRef.current = null;
+    }
+    return true;
+  }, []);
+
   /**
    * 占位卡自己的指针拖动。
    *
@@ -200,7 +260,7 @@ export function useResourceCanvasGenerationPlaceholders({
           scale: Number.isFinite(scale) && scale > 0 ? scale : 1,
           changed: false,
         };
-        setDraggingDraftId(placeholder.draftId);
+        // 「拖动中」不在这里置位：按下还不一定是拖动（见 onPointerMove 的阈值判据）。
       },
       onPointerMove: (event: ReactPointerEvent<HTMLDivElement>) => {
         const drag = dragRef.current;
@@ -208,11 +268,31 @@ export function useResourceCanvasGenerationPlaceholders({
           return;
         }
         event.stopPropagation();
+        if (!drag.changed) {
+          /*
+           * 只有真的移过阈值才算拖动：按下时浏览器就可能补一次零位移的 pointermove，把「收到过
+           * move」当拖动信号，会让一次普通点击直接吞掉自己的 click（点占位卡打不开浮层）。
+           */
+          if (
+            !resourceCanvasGestureExceededDragThreshold({
+              startClientX: drag.startClientX,
+              startClientY: drag.startClientY,
+              clientX: event.clientX,
+              clientY: event.clientY,
+            })
+          ) {
+            return;
+          }
+          drag.changed = true;
+          // 只登记，不起计时器：计时起点必须是松手那一刻（见 deferDragClickSuppressionCleanup）。
+          suppressedClickDraftIdRef.current = drag.draftId;
+          // 拖动样式也从越过阈值这一刻起才亮：点一下不该闪一次「拖动中」。
+          setDraggingDraftId(drag.draftId);
+        }
         const nextX =
           drag.startX + (event.clientX - drag.startClientX) / drag.scale;
         const nextY =
           drag.startY + (event.clientY - drag.startClientY) / drag.scale;
-        drag.changed = true;
         move(drag.draftId, nextX, nextY);
       },
       onPointerUp: (event: ReactPointerEvent<HTMLDivElement>) => {
@@ -221,6 +301,12 @@ export function useResourceCanvasGenerationPlaceholders({
           return;
         }
         event.stopPropagation();
+        // 收尾那次 click 就在这一轮任务里跟着来：抑制从现在起再活一个宏任务。
+        if (drag.changed) {
+          deferDragClickSuppressionCleanup(drag.draftId);
+        } else {
+          clearDragClickSuppression();
+        }
       },
       onPointerCancel: (event: ReactPointerEvent<HTMLDivElement>) => {
         const drag = clearDrag(event.pointerId);
@@ -229,9 +315,17 @@ export function useResourceCanvasGenerationPlaceholders({
         }
         // 取消手势（指针捕获丢失 / 窗口失焦）：回到拖动前的位置，不留下半截坐标。
         move(drag.draftId, drag.startX, drag.startY);
+        // 取消不会有收尾 click：抑制立刻收干净，别留到下一次真点击上。
+        clearDragClickSuppression();
       },
     }),
-    [clearDrag, move, viewportScale],
+    [
+      clearDrag,
+      clearDragClickSuppression,
+      deferDragClickSuppressionCleanup,
+      move,
+      viewportScale,
+    ],
   );
 
   const projectPlaceholders = useMemo(
@@ -250,6 +344,7 @@ export function useResourceCanvasGenerationPlaceholders({
     remove,
     move,
     dragHandlersFor,
+    consumeDragClick,
     placeholderByTaskId: (taskId: string) =>
       resourceCanvasGenerationPlaceholderByTaskId(
         placeholdersRef.current,
diff --git a/apps/ai-game-creator-shell/src/view/project-development/index.tsx b/apps/ai-game-creator-shell/src/view/project-development/index.tsx
index f956ccf58..6ee08fe4a 100644
--- a/apps/ai-game-creator-shell/src/view/project-development/index.tsx
+++ b/apps/ai-game-creator-shell/src/view/project-development/index.tsx
@@ -168,6 +168,7 @@ import {
   type ResourceCanvasBottomToolAction,
 } from '../../features/resource-canvas/resourceCanvasBottomToolbarModel';
 import { ResourceCanvasBottomToolbarView } from '../../features/resource-canvas/ResourceCanvasBottomToolbarView';
+import { resourceCanvasGestureExceededDragThreshold } from '../../features/resource-canvas/resourceCanvasCardGestureModel';
 import {
   isResourceCanvasInteractionTarget,
   isResourceCanvasPanTarget,
@@ -188,7 +189,9 @@ import {
   type ResourceCanvasGenerationPlaceholder,
 } from '../../features/resource-canvas/resourceCanvasGenerationPlaceholderModel';
 import {
+  clampResourceCanvasGenerationPanelAnchorX,
   resolveResourceCanvasGenerationPanelPlacement,
+  resourceCanvasGenerationPanelWidth,
   revealResourceCanvasGenerationContent,
 } from '../../features/resource-canvas/resourceCanvasGenerationVisibilityModel';
 import {
@@ -326,7 +329,6 @@ import {
   normalizeInfiniteResourceCanvasViewport,
   RESOURCE_CANVAS_CARD_HEIGHT,
   RESOURCE_CANVAS_CARD_WIDTH,
-  RESOURCE_CANVAS_DRAG_THRESHOLD,
   RESOURCE_CANVAS_FIT_PADDING,
   RESOURCE_CANVAS_INITIAL_FIT_MAX_SCALE,
   RESOURCE_CANVAS_SECTION_MIN_HEIGHT,
@@ -717,8 +719,6 @@ const RESOURCE_GENERATION_SAFE_INSET_FALLBACK = {
 };
 /** 面板高度量不到时的兜底（与浮层的 `max-height` 同量级），宁多留不贴栏。 */
 const RESOURCE_CANVAS_GENERATION_PANEL_HEIGHT_FALLBACK = 320;
-/** 面板宽度量不到时的兜底：与浮层 CSS 的 `min(560px, 100% - 24px)` 同口径。 */
-const RESOURCE_CANVAS_GENERATION_PANEL_WIDTH_FALLBACK = 560;
 /** 占位卡与它下沿浮层之间的间隙：与浮层锚点用同一个数。 */
 const RESOURCE_CANVAS_GENERATION_PANEL_GAP = 12;
 function resourceGenerationOverlaySafeInsets(element: HTMLElement | null) {
@@ -5979,7 +5979,14 @@ export default function ProjectDevelopmentView({
       const deltaY = event.clientY - drag.startClientY;
       if (
         !drag.changed &&
-        Math.hypot(deltaX, deltaY) < RESOURCE_CANVAS_DRAG_THRESHOLD
+        // 「拖动还是点击」与生成占位卡共用同一条判据（`resourceCanvasCardGestureModel`）：
+        // 卡类手势的阈值只该有一份，两边各写一套的结果是占位卡那条链路漏掉抑制。
+        !resourceCanvasGestureExceededDragThreshold({
+          startClientX: drag.startClientX,
+          startClientY: drag.startClientY,
+          clientX: event.clientX,
+          clientY: event.clientY,
+        })
       ) {
         return;
       }
@@ -9194,44 +9201,61 @@ export default function ProjectDevelopmentView({
       })
     : null;
   /**
-   * 浮层高度上界：按**画布安全带**算（画布可视高 − 顶栏 − 底栏 − 占位卡 − 间隙）。
+   * 画布几何只量一次，浮层的竖向与横向收口共用同一份数：
+   * 这里每读一次都会触发一次布局（`getBoundingClientRect` / `clientHeight`），
+   * 分开量既多花时间，也可能读到两个不同帧的值。
+   */
+  const resourceGenerationPanelCanvasSize = resourceCanvasElementSize(
+    resourceCanvasRef.current,
+  );
+  const resourceGenerationPanelInsets = resourceGenerationOverlaySafeInsets(
+    resourceCanvasRef.current,
+  );
+  /**
+   * 浮层顶边与高度：按**占位卡在画布上的真实屏幕位置**算（卡下沿 → 安全底边那一段）。
    *
    * 三条实测教训：用 `window.innerHeight` 会让面板垂到底栏下面；用「当前顶边到安全底边」会在
    * 打开瞬间只给一百多像素（只见标题与提交行）；用固定的最小高度兜底又会反过来把底边顶出去。
-   * 所以上界只看安全带：平移由 reveal 负责，浮层自己必须有完整可编辑高度。
+   * 第四条：只吃「安全带高度 − 卡高」等于假设占位卡永远贴在安全带上沿——占位是追加在栏目内容
+   * 最下方的，落到下半屏是常态，于是浮层底边越过画布下沿被 `overflow: hidden` 切掉（验收现场
+   * 那条「生成窗口和画布边缘碰撞」）。所以这里把卡的**屏幕顶边**一起给进去，顶边与可用高度都由
+   * 真实位置算出来；平移仍由 reveal 负责，浮层自己必须有完整可编辑高度。
    */
   const resourceGenerationPanelPlacement = resourceGenerationPanelStyle
     ? resolveResourceCanvasGenerationPanelPlacement({
-        canvasHeight: resourceCanvasElementSize(resourceCanvasRef.current)
-          .height,
-        topInset: resourceGenerationOverlaySafeInsets(resourceCanvasRef.current)
-          .top,
-        bottomInset: resourceGenerationOverlaySafeInsets(
-          resourceCanvasRef.current,
-        ).bottom,
+        canvasHeight: resourceGenerationPanelCanvasSize.height,
+        topInset: resourceGenerationPanelInsets.top,
+        bottomInset: resourceGenerationPanelInsets.bottom,
+        // 占位卡的坐标是**世界坐标**，安全带是 CSS px：按当前缩放与视口位移换算到画布内坐标。
+        anchorTop:
+          resourceCanvasSceneViewportRef.current.y +
+          (resourceGenerationPanelPlaceholder?.y ?? 0) *
+            (resourceCanvasSceneViewportRef.current.scale || 1),
         // 占位卡高度是**世界坐标**，安全带是 CSS px：按当前缩放换算成屏幕高度再扣。
         anchorHeight:
           (resourceGenerationPanelPlaceholder?.height ?? 0) *
           (resourceCanvasSceneViewportRef.current.scale || 1),
+        // 卡与浮层之间的间隙：与 reveal 算「整块要带进可视区」时用同一个数。
+        gap: RESOURCE_CANVAS_GENERATION_PANEL_GAP,
       })
     : null;
   /**
-   * 浮层位置与高度：位置口径仍与快速编辑 / 信息浮层一致（贴着占位下沿居中，CSS 负责
-   * `translateX(-50%)`）；只有「卡下面塞不下可编辑高度」时才改为与卡顶边对齐、盖住占位。
+   * 浮层位置与高度：竖向由上面那档给（贴着占位下沿居中，塞不下就改为盖住占位）；
+   * 横向把锚点收进画布可视范围——浮层比资源卡宽得多，不收口时卡片靠边就会有一半落到画布之外
+   * 被切掉（CSS 负责 `translateX(-50%)`，所以这里收的是那条中线）。
    */
   const resourceGenerationPanelFloatingStyle =
     resourceGenerationPanelStyle && resourceGenerationPanelPlacement
       ? {
           ...resourceGenerationPanelStyle,
-          ...(resourceGenerationPanelPlacement.overlaysAnchor &&
-          resourceGenerationPanelPlaceholder
-            ? {
-                top:
-                  resourceCanvasSceneViewportRef.current.y +
-                  resourceGenerationPanelPlaceholder.y *
-                    (resourceCanvasSceneViewportRef.current.scale || 1),
-              }
-            : {}),
+          left: clampResourceCanvasGenerationPanelAnchorX({
+            centerX: resourceGenerationPanelStyle.left,
+            canvasWidth: resourceGenerationPanelCanvasSize.width,
+            panelWidth: resourceCanvasGenerationPanelWidth(
+              resourceGenerationPanelCanvasSize.width,
+            ),
+          }),
+          top: resourceGenerationPanelPlacement.top,
           maxHeight: `${resourceGenerationPanelPlacement.availableHeight}px`,
         }
       : null;
@@ -9276,7 +9300,8 @@ export default function ProjectDevelopmentView({
     const panelWidth = Math.max(
       0,
       panelElement?.getBoundingClientRect().width ??
-        RESOURCE_CANVAS_GENERATION_PANEL_WIDTH_FALLBACK,
+        // 量不到时按同一套宽度口径估：`min(560, 画布宽 - 24)`。
+        resourceCanvasGenerationPanelWidth(canvasSize.width),
     );
     const viewport = normalizeResourceBookViewport(
       category === RESOURCE_BOOK_ALL_TARGET
@@ -9794,9 +9819,16 @@ export default function ProjectDevelopmentView({
                                   placeholder,
                                 )}
                                 onTogglePanel={() =>
-                                  toggleResourceGenerationPlaceholderPanel(
-                                    placeholder,
+                                  // 拖动收尾那一次 click 是拖动的副产物（down/up 落在同一张卡上
+                                  // 浏览器必补一次 click）：吃掉它，否则拖一下占位就会顺手把生成
+                                  // 浮层弹开。与资源卡拖拽后的抑制同一口径。
+                                  resourceGenerationPlaceholders.consumeDragClick(
+                                    placeholder.draftId,
                                   )
+                                    ? undefined
+                                    : toggleResourceGenerationPlaceholderPanel(
+                                        placeholder,
+                                      )
                                 }
                                 onRemove={() =>
                                   removeResourceGenerationPlaceholderCard(
@@ -10875,8 +10907,19 @@ export default function ProjectDevelopmentView({
               setResourceAssetGenerationTasksPanelOpen((current) => !current)
             }
             onFocusTask={focusResourceAssetGenerationTask}
+            /*
+              资源总览页与资源栏目画布页的顶部 chrome 不同：画布页钉着整宽的栏目标题栏
+              （含「返回资源总览」），总览页没有。两页因此各有一档坐标（见样式里的
+              `[data-generation-tasks-placement]`），切换时走锚点高度过渡。
+            */
             placement={
-              uiEditorRoute ? 'editor' : mode === 'run' ? 'run' : 'canvas'
+              uiEditorRoute
+                ? 'editor'
+                : mode === 'run'
+                  ? 'run'
+                  : resourceBookView === 'child'
+                    ? 'canvas'
+                    : 'canvas-overview'
             }
           />
         </section>
diff --git a/apps/ai-game-creator-shell/tests/resourceCanvasAssetGenerationReferences.test.tsx b/apps/ai-game-creator-shell/tests/resourceCanvasAssetGenerationReferences.test.tsx
index a8001ff90..db0e195da 100644
--- a/apps/ai-game-creator-shell/tests/resourceCanvasAssetGenerationReferences.test.tsx
+++ b/apps/ai-game-creator-shell/tests/resourceCanvasAssetGenerationReferences.test.tsx
@@ -23,7 +23,11 @@ import {
   resourceCanvasAssetGenerationReferenceIssue,
   resourceCanvasAssetGenerationUserReferenceLimit,
 } from '../src/features/resource-canvas/resourceCanvasAssetGenerationReferenceModel';
-import type { ResourceCanvasAssetToolAction } from '../src/features/resource-canvas/resourceCanvasBottomToolbarModel';
+import {
+  resolveResourceCanvasBottomTools,
+  type ResourceCanvasAssetToolAction,
+  resourceCanvasBottomToolActions,
+} from '../src/features/resource-canvas/resourceCanvasBottomToolbarModel';
 
 afterEach(() => {
   cleanup();
@@ -265,6 +269,126 @@ describe('生成面板的参考接线', () => {
     });
   });
 
+  /**
+   * 图标规范（`icon-spec`）是验收现场被问到的那一条：「生成图标规范时没法 @」。
+   *
+   * 面板里那段注释曾写成「图集与图标规范这两类入口不给选择器」，与判据不一致，容易被读成
+   * 「图标规范被有意排除」。这里把它钉成可执行的事实：图标规范与普通生成一致地呈现 `@`
+   * 与参考计数，并且提交时真的把引用带出去。
+   */
+  test('图标规范入口呈现参考计数与引用输入区，提交带回引用', async () => {
+    const user = userEvent.setup();
+    const onSubmit =
+      vi.fn<(input: ResourceCanvasAssetGenerationSubmitInput) => void>();
+    const imageAsset = asset('asset-a', 'image/png', 'assets/素材-a.png');
+    const references = [resourceReferenceFromAsset(imageAsset, 'asset-picker')];
+    render(
+      <ResourceCanvasAssetGenerationPanelView
+        action={iconSpecAction}
+        assets={[imageAsset]}
+        projectPath="/tmp/project"
+        draft={{
+          prompt: '按这套界面风格出图标规范 @素材-a',
+          assetName: '图标规范',
+          aspectRatio: '1:1',
+          imageSize: '1K',
+          references,
+        }}
+        onSubmit={onSubmit}
+        onClose={() => undefined}
+      />,
+    );
+
+    const panel = screen.getByRole('dialog', { name: '图标规范' });
+    expect(panel.textContent).toContain('参考图 1/5');
+    expect(
+      within(panel).getByRole('button', { name: '插入素材引用' }),
+    ).not.toBeNull();
+
+    await user.click(within(panel).getByRole('button', { name: '图标规范' }));
+    expect(onSubmit).toHaveBeenCalledTimes(1);
+    expect(onSubmit.mock.calls[0]?.[0]).toMatchObject({
+      kind: 'icon-spec',
+      references: [expect.objectContaining({ resourceId: 'asset-a' })],
+    });
+  });
+
+  test('图标规范的 @ 真的能开出素材选择器（不是只画了一枚按钮）', async () => {
+    const user = userEvent.setup();
+    const imageAsset = asset('asset-a', 'image/png', 'assets/素材-a.png');
+    render(
+      <ResourceCanvasAssetGenerationPanelView
+        action={iconSpecAction}
+        assets={[imageAsset]}
+        projectPath="/tmp/project"
+        onSubmit={vi.fn()}
+        onClose={() => undefined}
+      />,
+    );
+
+    await user.click(screen.getByRole('button', { name: '插入素材引用' }));
+    expect(
+      await screen.findByRole('dialog', { name: '选择素材' }),
+    ).not.toBeNull();
+  });
+
+  /**
+   * 反向守卫：`@` 的有无只由**一条**判据决定，不是每条入口各自决定。
+   *
+   * 遍历底部工具栏里真实存在的生成入口逐条渲染面板，断言「面板里有没有 @」与
+   * `resourceCanvasAssetGenerationAcceptsReferences` 完全一致；并钉住唯一的例外是图集。
+   * 这条用例的价值在增量：以后新增一条入口忘了接 `@`，或者有人把某条入口按类型硬编码成
+   * 没有选择器，这里立刻会红。
+   */
+  test('底部工具栏每条生成入口的 @ 与判据完全一致，唯一例外是图集', () => {
+    const imageAsset = asset('asset-a', 'image/png', 'assets/素材-a.png');
+    const actions = (
+      ['ui-interaction', 'character', 'scene', 'audio'] as const
+    ).flatMap((category) =>
+      resolveResourceCanvasBottomTools(category).flatMap((tool) =>
+        resourceCanvasBottomToolActions(tool),
+      ),
+    );
+    const generationActions = actions.filter(
+      (candidate) => candidate.route === 'asset',
+    );
+    expect(generationActions.length).toBeGreaterThan(0);
+    expect(
+      generationActions
+        .filter(
+          (candidate) =>
+            !resourceCanvasAssetGenerationAcceptsReferences(candidate),
+        )
+        .map((candidate) => candidate.id),
+    ).toEqual(['generate-icon-spritesheet']);
+    // 图标规范就在这一批入口里：这条断言同时挡住「入口被改名 / 被摘掉」的静默漂移。
+    expect(generationActions.map((candidate) => candidate.id)).toContain(
+      'generate-spec-icon',
+    );
+
+    for (const candidate of generationActions) {
+      const view = render(
+        <ResourceCanvasAssetGenerationPanelView
+          action={candidate}
+          assets={[imageAsset]}
+          projectPath="/tmp/project"
+          onSubmit={vi.fn()}
+          onClose={() => undefined}
+        />,
+      );
+      expect(
+        screen.queryByRole('button', { name: '插入素材引用' }) !== null,
+        `${candidate.id}（${candidate.label}）`,
+      ).toBe(resourceCanvasAssetGenerationAcceptsReferences(candidate));
+      // 说明行与选择器互补：有 @ 就不该出现「为什么不给 @」，反之必须在场。
+      expect(
+        screen.queryByText(/不支持另挑参考图/u) !== null,
+        `${candidate.id}（${candidate.label}）的参考口径说明`,
+      ).toBe(!resourceCanvasAssetGenerationAcceptsReferences(candidate));
+      view.unmount();
+    }
+  });
+
   test('图集入口不呈现参考选择，只提交纯提示词', async () => {
     const user = userEvent.setup();
     const onSubmit =
@@ -286,10 +410,28 @@ describe('生成面板的参考接线', () => {
     );
 
     const panel = screen.getByRole('dialog', { name: '生成图标素材' });
-    expect(panel.textContent).not.toContain('参考图');
+    /*
+     * 「不呈现参考选择」的判据落在**计数与选择器**上，不落在「正文里出现过『参考图』三个字」上：
+     * 这一档现在会有一段说明行解释为什么不给 `@`（「…不支持另挑参考图…」），按词匹配会把
+     * 说明行也一起判失败。
+     */
+    expect(
+      panel.querySelector('[data-resource-canvas-generation-reference-count]'),
+    ).toBeNull();
+    expect(panel.textContent).not.toMatch(/参考图\s*\d+\s*\/\s*\d+/u);
     const prompt = screen.getByLabelText('生成提示词');
     expect((prompt as HTMLTextAreaElement).tagName).toBe('TEXTAREA');
 
+    /*
+     * 不给 `@` 的入口必须当场说清为什么：验收现场那条「生成图标素材没法 @」读起来像漏了一个
+     * 按钮，真实原因却在那条平台通道上（只有一张权威规范图 `referenceId` + `iconDescriptions`，
+     * 客户端对图集的用户参考是显式拒绝）。说明行带 `data-*` 标记，便于逐条入口对照判据。
+     */
+    expect(
+      panel.querySelector('[data-resource-canvas-generation-reference-free]')
+        ?.textContent,
+    ).toContain('权威规范图');
+
     await user.click(
       within(panel).getByRole('button', { name: '生成图标素材' }),
     );
diff --git a/apps/ai-game-creator-shell/tests/resourceCanvasAssetGenerationTasksPanel.test.tsx b/apps/ai-game-creator-shell/tests/resourceCanvasAssetGenerationTasksPanel.test.tsx
index bcf79b2b6..5d01d2ac8 100644
--- a/apps/ai-game-creator-shell/tests/resourceCanvasAssetGenerationTasksPanel.test.tsx
+++ b/apps/ai-game-creator-shell/tests/resourceCanvasAssetGenerationTasksPanel.test.tsx
@@ -57,7 +57,7 @@ function renderSidebar(
   tasks: readonly ResourceCanvasAssetGenerationTask[],
   options: {
     open?: boolean;
-    placement?: 'canvas' | 'run' | 'editor';
+    placement?: 'canvas-overview' | 'canvas' | 'run' | 'editor';
   } = {},
 ) {
   const onToggleOpen = vi.fn();
@@ -133,6 +133,100 @@ describe('「生成任务」侧栏', () => {
     ).toBeGreaterThan(0);
   });
 
+  /**
+   * 读秒粒度：与对话侧同一份 `useLiveNow`（`LIVE_TIMER_TICK_MS = 100`）。
+   *
+   * 不足一分钟的耗时显示到 0.1 秒，刷新就必须是 100ms——按 1 秒一跳时，用户看到的是一块
+   * 「带小数却一格一格跳」的表，像卡住不动（验收现场「生成任务里的读秒更新频率应为 0.1s」）。
+   */
+  test('读秒按 100ms 刷新：不足一分钟的耗时以 0.1 秒递增', () => {
+    vi.useFakeTimers();
+    try {
+      // 假时钟与任务的创建时间对齐（夹具的 `nowMillis` 是 1000）。
+      vi.setSystemTime(1_000);
+      renderSidebar([
+        task({
+          taskId: 't1',
+          dispatched: true,
+          status: 'running',
+          phaseDetail: '正在生成。',
+        }),
+      ]);
+      const elapsed = () => screen.getByText(/^已耗时 /u).textContent;
+      expect(elapsed()).toBe('已耗时 0.0秒');
+
+      act(() => {
+        vi.advanceTimersByTime(100);
+      });
+      expect(elapsed()).toBe('已耗时 0.1秒');
+
+      // 1 秒一跳的实现会停在上面的 0.1 秒：再走 400ms 必须继续往上加。
+      act(() => {
+        vi.advanceTimersByTime(400);
+      });
+      expect(elapsed()).toBe('已耗时 0.5秒');
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  test('任务收口后不再走表：已耗时定格在账本给的结束时间上', () => {
+    vi.useFakeTimers();
+    try {
+      vi.setSystemTime(1_000);
+      renderSidebar([
+        task({
+          taskId: 't1',
+          dispatched: true,
+          status: 'completed',
+          phaseDetail: '生成已完成。',
+          assetId: 'asset-1',
+          finishedAtMillis: 2_500,
+        }),
+      ]);
+      const elapsed = () => screen.getByText(/^已耗时 /u).textContent;
+      expect(elapsed()).toBe('已耗时 1.5秒');
+
+      act(() => {
+        vi.advanceTimersByTime(5_000);
+      });
+      expect(elapsed()).toBe('已耗时 1.5秒');
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  /**
+   * 秒表只订在**运行中的那一行**上：终态行不订阅，面板本身也不订阅。
+   *
+   * 这条是性能约束的可执行版本——100ms 的 tick 若落在整块面板或终态行上，每 0.1 秒都会重建
+   * 整个侧栏（`useLiveNow` 的注释写明「调用方必须是叶子节点」）。
+   */
+  test('秒表只订在运行中的那一行上，终态行与面板本身都不订阅时钟', () => {
+    const spy = vi.spyOn(globalThis, 'setInterval');
+    try {
+      renderSidebar([
+        task({
+          taskId: 'live',
+          dispatched: true,
+          status: 'running',
+          phaseDetail: '正在生成。',
+        }),
+        task({
+          taskId: 'done',
+          dispatched: true,
+          status: 'completed',
+          phaseDetail: '生成已完成。',
+          assetId: 'asset-done',
+          finishedAtMillis: 2_000,
+        }),
+      ]);
+      expect(spy).toHaveBeenCalledTimes(1);
+    } finally {
+      spy.mockRestore();
+    }
+  });
+
   test('收起只有一个入口：头部那枚关闭按钮，收起即整块让出画布', async () => {
     const user = userEvent.setup();
     const { onToggleOpen } = renderSidebar([task({ taskId: 't1' })]);
@@ -283,6 +377,18 @@ describe('「生成任务」侧栏', () => {
       />,
     );
     expect(placementOf()).toBe('canvas');
+
+    // 资源总览（画本）页单独一档：那一页顶部没有钉死的栏目标题栏。
+    rerender(
+      <ResourceCanvasAssetGenerationTasksPanelView
+        tasks={[]}
+        open
+        onToggleOpen={vi.fn()}
+        onFocusTask={vi.fn()}
+        placement="canvas-overview"
+      />,
+    );
+    expect(placementOf()).toBe('canvas-overview');
   });
 
   test('收起时先播完收起动画再卸载，动画期间列表内容不跳', () => {
diff --git a/apps/ai-game-creator-shell/tests/resourceCanvasAssetGenerationTasksSidebarStyle.test.ts b/apps/ai-game-creator-shell/tests/resourceCanvasAssetGenerationTasksSidebarStyle.test.ts
index 776d25ef2..d3aea4611 100644
--- a/apps/ai-game-creator-shell/tests/resourceCanvasAssetGenerationTasksSidebarStyle.test.ts
+++ b/apps/ai-game-creator-shell/tests/resourceCanvasAssetGenerationTasksSidebarStyle.test.ts
@@ -22,6 +22,38 @@ const SIDEBAR_CSS_PATH = repoPath(
 );
 const rules = parseStyleSheet(readFileSync(SIDEBAR_CSS_PATH, 'utf8'));
 
+/**
+ * 锚点在「资源栏目画布」那一档要让开的、钉死的栏目标题栏（`.game-resource-book-scene-titlebar`）。
+ * 它的高度定义在全局样式表里，而让开多少写在侧栏样式里——两个文件，必须一起改，
+ * 所以这里读真实声明把关系钉住。
+ */
+const GLOBAL_CSS_PATH = repoPath('apps/ai-game-creator-shell/src/styles.css');
+const globalRules = parseStyleSheet(readFileSync(GLOBAL_CSS_PATH, 'utf8'));
+// 同一个求值器限制：全局表里也有 `prefers-reduced-motion` 档，求值时先排除掉。
+const globalWidthRules = globalRules.filter(
+  (rule) => !(rule.media ?? '').includes('prefers-reduced-motion'),
+);
+
+/** 声明里允许的形状就这两种：单个长度，或「几个长度相加」的 `calc`（本文件不解析别的函数）。 */
+function cssLengthToPx(value: string): number {
+  const raw = value.trim();
+  const calc = /^calc\((.+)\)$/u.exec(raw);
+  if (calc) {
+    return calc[1]
+      .split('+')
+      .map((term) => cssLengthToPx(term))
+      .reduce((total, term) => total + term, 0);
+  }
+  const match = raw.match(/^(-?\d+(?:\.\d+)?)(px|rem)$/u);
+  if (!match) {
+    throw new Error(`不是可换算的长度：${value}`);
+  }
+  const [, amount, unit] = match;
+  // 根字号取浏览器 / WebView 的默认 16px（全局样式表没有改写 `html` 的字号），
+  // 这个换算只用在那条「让开多少 ≥ 标题栏多高」的守卫上。
+  return Number(amount) * (unit === 'rem' ? 16 : 1);
+}
+
 /**
  * `styleCascade` 的求值器只认识宽度媒体查询，遇到 `prefers-reduced-motion` 会主动报错；
  * 那条规则的生效与否单独在下面按声明断言，所以求值时先把它排除掉。
@@ -229,6 +261,40 @@ describe('「生成任务」侧栏样式', () => {
     expect(declaration(editorAnchor, 'grid-row')).toBe('2');
     expect(declaration(editorAnchor, 'margin')).toBe('0.85rem');
 
+    /*
+     * 资源总览页与资源栏目画布页的**锚点高度不同**：画布页顶部钉着整宽的栏目标题栏
+     * （右端就是「返回资源总览」入口），锚点必须让开它，否则那枚开关会压在标题栏上
+     * （验收现场那条「生成任务和标题栏重叠」）。让开的高度与标题栏真实高度是跨文件关系，
+     * 所以这里读全局样式表里的 min-height 断言「让开得比它高」。
+     */
+    const titlebarMinHeight = cssLengthToPx(
+      declaration(
+        resolveDeclarations(globalWidthRules, [
+          '.game-resource-book-scene-titlebar',
+        ]),
+        'min-height',
+      ),
+    );
+    const canvasAnchor = resolved([
+      '.game-resource-generation-tasks-anchor',
+      ".game-resource-generation-tasks-anchor[data-generation-tasks-placement='canvas']",
+    ]);
+    const canvasAnchorTop = cssLengthToPx(
+      declaration(canvasAnchor, 'margin-top'),
+    );
+    expect(canvasAnchorTop).toBeGreaterThan(titlebarMinHeight);
+
+    const overviewAnchor = resolved([
+      '.game-resource-generation-tasks-anchor',
+      ".game-resource-generation-tasks-anchor[data-generation-tasks-placement='canvas-overview']",
+    ]);
+    const overviewAnchorTop = cssLengthToPx(
+      declaration(overviewAnchor, 'margin-top'),
+    );
+    // 总览页没有那条标题栏：仍贴画布顶边内缩，而且确实比画布页高一档。
+    expect(overviewAnchorTop).toBe(cssLengthToPx('0.85rem'));
+    expect(overviewAnchorTop).toBeLessThan(canvasAnchorTop);
+
     // 开关保留原来工具条那一枚的外观（次级胶囊），只是搬到画布上并加一档面板投影；
     // 取值仍然全部走平台 token，不引入第二套色板。
     const toggle = resolved(['.game-resource-generation-tasks-toggle']);
@@ -286,6 +352,22 @@ describe('「生成任务」侧栏样式', () => {
     ).toBe(true);
   });
 
+  test('资源总览 ↔ 资源画布切换时锚点高度有过渡，减动效下关掉', () => {
+    const anchor = resolved(['.game-resource-generation-tasks-anchor']);
+    expect(declaration(anchor, 'transition')).toContain('margin-top');
+
+    const reduced = rules.filter((rule) =>
+      (rule.media ?? '').includes('prefers-reduced-motion'),
+    );
+    expect(
+      reduced.some(
+        (rule) =>
+          rule.selectors.includes('.game-resource-generation-tasks-anchor') &&
+          rule.declarations.get('transition') === 'none',
+      ),
+    ).toBe(true);
+  });
+
   test('焦点环可见（键盘可见焦点用平台 token）', () => {
     const focusRule = rules.find((rule) =>
       rule.selectors.includes(
diff --git a/apps/ai-game-creator-shell/tests/resourceCanvasCardGestureModel.test.ts b/apps/ai-game-creator-shell/tests/resourceCanvasCardGestureModel.test.ts
new file mode 100644
index 000000000..0f1050784
--- /dev/null
+++ b/apps/ai-game-creator-shell/tests/resourceCanvasCardGestureModel.test.ts
@@ -0,0 +1,49 @@
+import { describe, expect, test } from 'vitest';
+
+import { resourceCanvasGestureExceededDragThreshold } from '../src/features/resource-canvas/resourceCanvasCardGestureModel';
+import { RESOURCE_CANVAS_DRAG_THRESHOLD } from '../src/view/project-development/resourceCanvasLayoutModel';
+
+describe('画布卡片手势：拖动 / 点击的唯一判据', () => {
+  const gesture = (deltaX: number, deltaY: number) =>
+    resourceCanvasGestureExceededDragThreshold({
+      startClientX: 100,
+      startClientY: 100,
+      clientX: 100 + deltaX,
+      clientY: 100 + deltaY,
+    });
+
+  test('正好到阈值算拖动，差一点点仍算点击（与资源卡同一个阈值）', () => {
+    expect(RESOURCE_CANVAS_DRAG_THRESHOLD).toBe(5);
+    expect(gesture(RESOURCE_CANVAS_DRAG_THRESHOLD, 0)).toBe(true);
+    expect(gesture(RESOURCE_CANVAS_DRAG_THRESHOLD - 0.1, 0)).toBe(false);
+    expect(gesture(0, 0)).toBe(false);
+  });
+
+  test('位移按欧氏距离算：斜向 3/4 就是 5', () => {
+    expect(gesture(3, 4)).toBe(true);
+    expect(gesture(2, 3)).toBe(false);
+  });
+
+  test('阈值可覆盖（各档手势需要更紧或更松时只改参数，不改判据）', () => {
+    expect(
+      resourceCanvasGestureExceededDragThreshold({
+        startClientX: 0,
+        startClientY: 0,
+        clientX: 1,
+        clientY: 0,
+        threshold: 1,
+      }),
+    ).toBe(true);
+  });
+
+  test('几何非法时按「没有拖动」算：宁可把拖动当点击，也不能把点击误判成拖动', () => {
+    expect(
+      resourceCanvasGestureExceededDragThreshold({
+        startClientX: Number.NaN,
+        startClientY: 100,
+        clientX: 200,
+        clientY: 100,
+      }),
+    ).toBe(false);
+  });
+});
diff --git a/apps/ai-game-creator-shell/tests/resourceCanvasGenerationFloatingPanelChrome.test.tsx b/apps/ai-game-creator-shell/tests/resourceCanvasGenerationFloatingPanelChrome.test.tsx
index 6d3a686d3..e6608e7f6 100644
--- a/apps/ai-game-creator-shell/tests/resourceCanvasGenerationFloatingPanelChrome.test.tsx
+++ b/apps/ai-game-creator-shell/tests/resourceCanvasGenerationFloatingPanelChrome.test.tsx
@@ -8,6 +8,10 @@ import { afterEach, describe, expect, test, vi } from 'vitest';
 import { ResourceCanvasAssetGenerationPanelView } from '../src/features/resource-canvas/ResourceCanvasAssetGenerationPanelView';
 import type { ResourceCanvasAssetToolAction } from '../src/features/resource-canvas/resourceCanvasBottomToolbarModel';
 import { ResourceCanvasGenerationPanelView } from '../src/features/resource-canvas/ResourceCanvasGenerationPanelView';
+import {
+  RESOURCE_CANVAS_GENERATION_PANEL_MAX_WIDTH,
+  RESOURCE_CANVAS_GENERATION_PANEL_VIEWPORT_INSET,
+} from '../src/features/resource-canvas/resourceCanvasGenerationVisibilityModel';
 import { repoPath } from './repoPath';
 
 afterEach(cleanup);
@@ -142,4 +146,16 @@ describe('生成浮层样式结构', () => {
       /\.game-resource-generation-actions \{[\s\S]*?bottom: 0;[\s\S]*?background:/u,
     );
   });
+
+  /**
+   * 宿主算「水平收口」用的是模型里那对常量（浮层最大宽 + 左右内缩），CSS 这里是同一对数的另一份
+   * 写法：两边必须一致，否则收口算的是 560 宽、画出来的却是另一个宽度，卡片靠边时又会露出去。
+   */
+  test('宽度口径与宿主算水平收口的常量同源', () => {
+    expect(panelCss()).toContain(
+      `width: min(${RESOURCE_CANVAS_GENERATION_PANEL_MAX_WIDTH}px, calc(100% - ${
+        RESOURCE_CANVAS_GENERATION_PANEL_VIEWPORT_INSET * 2
+      }px));`,
+    );
+  });
 });
diff --git a/apps/ai-game-creator-shell/tests/resourceCanvasGenerationHostLifecycle.test.tsx b/apps/ai-game-creator-shell/tests/resourceCanvasGenerationHostLifecycle.test.tsx
index 351f79175..9d2c9b104 100644
--- a/apps/ai-game-creator-shell/tests/resourceCanvasGenerationHostLifecycle.test.tsx
+++ b/apps/ai-game-creator-shell/tests/resourceCanvasGenerationHostLifecycle.test.tsx
@@ -1012,3 +1012,67 @@ describe('生成浮层按占位隔离（宿主回归）', () => {
     expect(tauri.assetGenerationStarts[1]!.prompt).toBe(originalPrompt);
   });
 });
+
+/**
+ * 验收现场那条「拖动未生成的资源卡片会触发点击事件」（至少背景音乐与音效会）。
+ *
+ * 浏览器在 pointerdown 与 pointerup 落在同一个节点上时**一定会补一次 `click`**——拖完卡片
+ * 松手，紧跟着的那次 click 会把卡片自己的点击语义再执行一遍。占位卡的点击语义就是开合生成浮层，
+ * 所以表现为「拖一下就把浮层弹开 / 收起」。这里从真实宿主上钉住两件事：拖动收尾的 click 被吃掉，
+ * 而一次真正的点击仍然照常开合（抑制只活过一次手势）。
+ */
+describe('拖动生成占位卡不触发卡片的点击（宿主回归）', () => {
+  test('拖动收尾的那次 click 被吃掉，普通点击仍然照常开合浮层', async () => {
+    const tauri = installHostTauri({
+      assets: [seedBgmAsset('seed-bgm')],
+    });
+    render(<HostWorkbench assets={[seedBgmAsset('seed-bgm')]} />);
+    await settle();
+
+    const { draftId } = await openBgmEntry();
+    // 点入口时浮层是开着的（占位与浮层由同一个动作产生）。
+    expect(floatingPanel()).not.toBeNull();
+
+    const placeholder = placeholderElement(draftId)!;
+    fireEvent.pointerDown(placeholder, {
+      pointerId: 7,
+      button: 0,
+      isPrimary: true,
+      clientX: 200,
+      clientY: 200,
+    });
+    fireEvent.pointerMove(placeholder, {
+      pointerId: 7,
+      clientX: 260,
+      clientY: 230,
+    });
+    /*
+     * 真实鼠标的拖动会横跨很多轮宏任务（pointermove 一次次派发）：这里让时钟真的走一轮再松手。
+     * 抑制的计时起点必须在松手那一刻；若实现改回「越过阈值时就起 0ms 计时器」，这一轮之后抑制
+     * 就已经被清掉，紧随其后的那次 click 会把浮层关掉，下面的断言立刻红。
+     */
+    await settle();
+    fireEvent.pointerUp(placeholder, {
+      pointerId: 7,
+      clientX: 260,
+      clientY: 230,
+    });
+    /*
+     * 真实浏览器在 pointerup 之后会自动释放指针捕获并补一个 `lostpointercapture`（卡片把它接到
+     * 取消手势上）。它必须**不能**把这次拖动的点击抑制一起清掉——否则补上来的 click 又会漏过去。
+     */
+    fireEvent.lostPointerCapture(placeholder, { pointerId: 7 });
+    // 浏览器补的那一次 click：抑制没生效时这里会立刻把浮层关掉。
+    fireEvent.click(placeholder);
+    await settle();
+    expect(floatingPanel()).not.toBeNull();
+
+    // 对照：没移动的点击是「点击」，仍然开合浮层（抑制不是把点击永久关掉）。
+    fireEvent.click(placeholder);
+    await settle();
+    expect(floatingPanel()).toBeNull();
+    // 拖动本身照常生效（拖动只改坐标，不取消这次生成）。
+    expect(placeholderElement(draftId)).not.toBeNull();
+    expect(tauri.assetGenerationStarts).toEqual([]);
+  }, 20_000);
+});
diff --git a/apps/ai-game-creator-shell/tests/resourceCanvasGenerationPlaceholder.test.tsx b/apps/ai-game-creator-shell/tests/resourceCanvasGenerationPlaceholder.test.tsx
index 0f73b84c6..41bbf3ec1 100644
--- a/apps/ai-game-creator-shell/tests/resourceCanvasGenerationPlaceholder.test.tsx
+++ b/apps/ai-game-creator-shell/tests/resourceCanvasGenerationPlaceholder.test.tsx
@@ -190,6 +190,58 @@ describe('占位卡组件', () => {
     // 删除按钮不能把点击透到卡片上（否则删完立刻又开一次浮层）。
     expect(onTogglePanel).toHaveBeenCalledTimes(1);
   });
+
+  /**
+   * 同一类缺陷的相邻一档：删除按钮自己 `stopPropagation`，「按在删除按钮上、松手落回卡片」
+   * 那次 click 会被派给共同祖先（卡片）。判据按**起手点**判，不看移动距离——从删除按钮起手的
+   * 手势永远不是「点卡片」。
+   */
+  test('从删除按钮起手、松手落回卡片时不当作点卡片', () => {
+    const onTogglePanel = vi.fn();
+    const onRemove = vi.fn();
+    render(
+      <ResourceCanvasGenerationPlaceholderCardView
+        placeholder={placeholderFixture()}
+        active={false}
+        dragging={false}
+        onPointerDown={() => undefined}
+        onPointerMove={() => undefined}
+        onPointerUp={() => undefined}
+        onPointerCancel={() => undefined}
+        onTogglePanel={onTogglePanel}
+        onRemove={onRemove}
+      />,
+    );
+
+    const card = screen.getByRole('button', {
+      name: 'AI 生成图片（待提交）',
+    });
+    const remove = screen.getByRole('button', {
+      name: '删除占位 AI 生成图片',
+    });
+    fireEvent.pointerDown(remove, {
+      pointerId: 3,
+      button: 0,
+      isPrimary: true,
+      clientX: 10,
+      clientY: 10,
+    });
+    // 松手落回卡片：浏览器把 click 派给共同祖先（卡片）。
+    fireEvent.click(card);
+    expect(onTogglePanel).not.toHaveBeenCalled();
+    expect(onRemove).not.toHaveBeenCalled();
+
+    // 之后正常点卡片仍然开合浮层（起手标记不残留到下一手势）。
+    fireEvent.pointerDown(card, {
+      pointerId: 4,
+      button: 0,
+      isPrimary: true,
+      clientX: 20,
+      clientY: 20,
+    });
+    fireEvent.click(card);
+    expect(onTogglePanel).toHaveBeenCalledTimes(1);
+  });
 });
 
 describe('占位宿主 Hook', () => {
@@ -262,7 +314,16 @@ describe('占位宿主 Hook', () => {
     expect(hook.result.current.placeholders).toEqual([]);
   });
 
-  test('拖动按视口缩放换算坐标，指针取消回到拖动前位置', () => {
+  /**
+   * 把 hook 的返回值也带出来：阈值、拖动中标记与点击抑制都在 hook 这一层，
+   * 只渲染卡片看不到它们。
+   */
+  function renderDragHarness() {
+    const hookRef: {
+      current: ReturnType<
+        typeof useResourceCanvasGenerationPlaceholders
+      > | null;
+    } = { current: null };
     function Harness() {
       const [created, setCreated] = useState(false);
       const placeholders = useResourceCanvasGenerationPlaceholders({
@@ -270,6 +331,7 @@ describe('占位宿主 Hook', () => {
         resolvePlacement: () => ({ x: 10, y: 20 }),
         viewportScale: () => 2,
       });
+      hookRef.current = placeholders;
       useEffect(() => {
         if (created) {
           return;
@@ -300,6 +362,17 @@ describe('占位宿主 Hook', () => {
     }
 
     render(<Harness />);
+    const hook = () => {
+      if (!hookRef.current) {
+        throw new Error('hook 还没挂上');
+      }
+      return hookRef.current;
+    };
+    return { hook };
+  }
+
+  test('拖动按视口缩放换算坐标，指针取消回到拖动前位置', () => {
+    renderDragHarness();
     const card = screen.getByRole('button', {
       name: 'AI 生成图片（待提交）',
     });
@@ -341,4 +414,73 @@ describe('占位宿主 Hook', () => {
     expect(card.style.left).toBe('30px');
     expect(card.style.top).toBe('35px');
   });
+
+  /**
+   * 验收现场那条「拖动未生成的资源卡片会触发点击事件」在单元层的钉子：
+   * 拖动与点击的判据是**移动距离**（与资源卡共用 `RESOURCE_CANVAS_DRAG_THRESHOLD`），
+   * 而且拖动收尾那一次 click 要被吃掉一次——只有这一次。
+   */
+  test('位移没越过阈值不算拖动：卡片不动、也不吃掉后面的点击', () => {
+    const { hook } = renderDragHarness();
+    const card = screen.getByRole('button', {
+      name: 'AI 生成图片（待提交）',
+    });
+    const draftId = hook().placeholders[0]!.draftId;
+
+    fireEvent.pointerDown(card, {
+      pointerId: 11,
+      button: 0,
+      isPrimary: true,
+      clientX: 100,
+      clientY: 100,
+    });
+    // 按下还不算拖动：拖动样式不该在点一下的时候闪。
+    expect(hook().draggingDraftId).toBeNull();
+    // 抖动 2px（阈值 5px）不构成拖动。
+    fireEvent.pointerMove(card, { pointerId: 11, clientX: 102, clientY: 101 });
+    expect(card.style.left).toBe('10px');
+    expect(card.style.top).toBe('20px');
+    expect(hook().draggingDraftId).toBeNull();
+
+    fireEvent.pointerUp(card, { pointerId: 11, clientX: 102, clientY: 101 });
+    // 这一次是点击而不是拖动：后面的 click 必须照常生效。
+    expect(hook().consumeDragClick(draftId)).toBe(false);
+  });
+
+  test('越过阈值才算拖动：抑制活到松手那一刻，下一次点击照常生效', async () => {
+    const { hook } = renderDragHarness();
+    const card = screen.getByRole('button', {
+      name: 'AI 生成图片（待提交）',
+    });
+    const draftId = hook().placeholders[0]!.draftId;
+
+    fireEvent.pointerDown(card, {
+      pointerId: 12,
+      button: 0,
+      isPrimary: true,
+      clientX: 100,
+      clientY: 100,
+    });
+    // 视口缩放 2：屏幕 6px > 阈值 5px，越过阈值这一刻才算拖动的开始。
+    fireEvent.pointerMove(card, { pointerId: 12, clientX: 106, clientY: 100 });
+    expect(hook().draggingDraftId).toBe(draftId);
+    expect(card.style.left).toBe('13px');
+
+    /*
+     * 真实鼠标的拖动会横跨很多轮宏任务：这里显式让时钟走一轮再继续。
+     *
+     * 这一行是这条用例的关键——抑制的**计时起点**必须是松手那一刻；如果实现改回「越过阈值时
+     * 就起 0ms 计时器」，抑制会在松手之前被清掉，下面那次 `consumeDragClick` 就会变成 false，
+     * 而真实浏览器里表现为「拖一下还是触发了点击」（jsdom 同步发 move / up 时看不见这一档）。
+     */
+    await act(async () => {
+      await new Promise((resolve) => setTimeout(resolve, 0));
+    });
+
+    fireEvent.pointerUp(card, { pointerId: 12, clientX: 106, clientY: 100 });
+    expect(hook().draggingDraftId).toBeNull();
+    // 拖动收尾那次 click 被吃掉一次，之后恢复正常。
+    expect(hook().consumeDragClick(draftId)).toBe(true);
+    expect(hook().consumeDragClick(draftId)).toBe(false);
+  });
 });
diff --git a/apps/ai-game-creator-shell/tests/resourceCanvasGenerationTasksSidebarDismiss.test.tsx b/apps/ai-game-creator-shell/tests/resourceCanvasGenerationTasksSidebarDismiss.test.tsx
index dc109b077..8cb151d57 100644
--- a/apps/ai-game-creator-shell/tests/resourceCanvasGenerationTasksSidebarDismiss.test.tsx
+++ b/apps/ai-game-creator-shell/tests/resourceCanvasGenerationTasksSidebarDismiss.test.tsx
@@ -154,8 +154,14 @@ describe('「生成任务」侧栏的开合与入口位置', () => {
       '.game-resource-generation-tasks-anchor',
     );
     expect(anchor).not.toBeNull();
+    /*
+     * 这一份夹具停在**资源总览**（没有打开任何栏目页），所以锚点用的是总览那一档：
+     * 总览页顶部没有钉死的栏目标题栏，锚点贴画布顶边内缩即可；栏目画布页会因为那条整宽的
+     * 标题栏（右端是「返回资源总览」）而多让开一段高度，两档的坐标与过渡见
+     * `resourceCanvasAssetGenerationTasksSidebarStyle.test.ts`。
+     */
     expect(anchor?.getAttribute('data-generation-tasks-placement')).toBe(
-      'canvas',
+      'canvas-overview',
     );
     expect(
       document
diff --git a/apps/ai-game-creator-shell/tests/resourceCanvasGenerationVisibility.test.ts b/apps/ai-game-creator-shell/tests/resourceCanvasGenerationVisibility.test.ts
index d9270e2e6..a4ffcb09a 100644
--- a/apps/ai-game-creator-shell/tests/resourceCanvasGenerationVisibility.test.ts
+++ b/apps/ai-game-creator-shell/tests/resourceCanvasGenerationVisibility.test.ts
@@ -1,7 +1,13 @@
 import { describe, expect, test } from 'vitest';
 
-import { revealResourceCanvasGenerationContent } from '../src/features/resource-canvas/resourceCanvasGenerationVisibilityModel';
-import { resolveResourceCanvasGenerationPanelPlacement } from '../src/features/resource-canvas/resourceCanvasGenerationVisibilityModel';
+import {
+  clampResourceCanvasGenerationPanelAnchorX,
+  resolveResourceCanvasGenerationPanelPlacement,
+  RESOURCE_CANVAS_GENERATION_PANEL_MAX_WIDTH,
+  RESOURCE_CANVAS_GENERATION_PANEL_VIEWPORT_INSET,
+  resourceCanvasGenerationPanelWidth,
+  revealResourceCanvasGenerationContent,
+} from '../src/features/resource-canvas/resourceCanvasGenerationVisibilityModel';
 
 const canvasSize = { width: 800, height: 600 };
 const insets = { top: 60, bottom: 90 };
@@ -88,46 +94,84 @@ describe('生成浮层与占位的可见性', () => {
   });
 });
 
-describe('浮层高度与「盖住占位」判定按画布安全带算', () => {
+describe('浮层顶边与高度按占位卡的真实屏幕位置算', () => {
   const placement = (input: {
     canvasHeight: number;
     topInset: number;
     bottomInset: number;
+    anchorTop: number;
     anchorHeight: number;
   }) => resolveResourceCanvasGenerationPanelPlacement(input);
 
-  test('空间够时挂在卡下面，高度 = 安全带 - 卡 - 间隙', () => {
+  test('空间够时挂在卡下面：顶边贴卡下沿，高度 = 卡下沿到安全底边', () => {
     const result = placement({
       canvasHeight: 568,
       topInset: 54,
       bottomInset: 84,
+      anchorTop: 54,
       anchorHeight: 128,
     });
     expect(result.overlaysAnchor).toBe(false);
-    // 安全带 430 - 卡 128 - 间隙 12 = 290：落在「至少 260 可编辑」的区间里。
+    // 安全底边 484 - 卡下沿（54 + 128） - 间隙 12 = 290。
+    expect(result.top).toBe(54 + 128 + 12);
     expect(result.availableHeight).toBe(290);
+    expect(result.top + result.availableHeight).toBe(568 - 84);
   });
 
-  test('安全带给不出可编辑高度时改为盖住占位，拿整条安全带', () => {
-    // 缩放 1.5：占位卡视觉 192px，卡下面只剩 224 (< 280) → 盖住占位。
+  test('安全带给不出可编辑高度时改为盖住占位，拿「卡顶边到安全底边」', () => {
+    // 缩放 1.5：占位卡视觉 192px，卡下面只剩 234 (< 280) → 盖住占位。
     const result = placement({
       canvasHeight: 568,
       topInset: 58,
       bottomInset: 72,
+      anchorTop: 58,
       anchorHeight: 192,
     });
     expect(result.overlaysAnchor).toBe(true);
-    // 安全带 438 - 间隙 12 = 426：远大于「一百多像素」的旧表现。
-    expect(result.availableHeight).toBe(426);
+    expect(result.top).toBe(58);
+    // 568 - 72 - 58 = 438：远大于「一百多像素」的旧表现。
+    expect(result.availableHeight).toBe(438);
     expect(result.availableHeight).toBeGreaterThanOrEqual(260);
   });
 
+  /**
+   * 验收现场那条「生成窗口和画布边缘碰撞」的回归：占位卡是追加在栏目内容最下方的，
+   * 落到画布下半屏是常态。旧口径只吃「安全带高度 − 卡高」，等于假设卡永远贴在安全带上沿，
+   * 于是浮层底边越过画布下沿被 `overflow: hidden` 切掉。
+   */
+  test('占位卡落到下半屏时浮层底边仍收在安全底边以内', () => {
+    const result = placement({
+      canvasHeight: 600,
+      topInset: 60,
+      bottomInset: 90,
+      anchorTop: 470,
+      anchorHeight: 128,
+    });
+    expect(result.overlaysAnchor).toBe(true);
+    // 卡顶边 470 会顶出安全底边（510 - 160 = 350），所以顶边先收到 350，再给一整段可编辑高度。
+    expect(result.top).toBe(350);
+    expect(result.top + result.availableHeight).toBeLessThanOrEqual(600 - 90);
+
+    // 中间位置同理：顶边贴卡顶，底边贴安全底边。
+    const middle = placement({
+      canvasHeight: 600,
+      topInset: 60,
+      bottomInset: 90,
+      anchorTop: 260,
+      anchorHeight: 128,
+    });
+    expect(middle.overlaysAnchor).toBe(true);
+    expect(middle.top).toBe(260);
+    expect(middle.top + middle.availableHeight).toBe(600 - 90);
+  });
+
   test('空间充足时收到上限，几何非法时回退到最小编辑高度', () => {
     expect(
       placement({
         canvasHeight: 1400,
         topInset: 54,
         bottomInset: 84,
+        anchorTop: 54,
         anchorHeight: 128,
       }).availableHeight,
     ).toBe(520);
@@ -136,17 +180,92 @@ describe('浮层高度与「盖住占位」判定按画布安全带算', () => {
         canvasHeight: 0,
         topInset: 54,
         bottomInset: 84,
+        anchorTop: 54,
         anchorHeight: 128,
       }),
-    ).toEqual({ overlaysAnchor: false, availableHeight: 280 });
+    ).toEqual({ overlaysAnchor: false, top: 54, availableHeight: 280 });
     // 画布小到连安全带都装不下：退到安全带能给的量，但仍有可编辑高度。
     const tiny = placement({
       canvasHeight: 240,
       topInset: 40,
       bottomInset: 40,
+      anchorTop: 40,
       anchorHeight: 128,
     });
     expect(tiny.overlaysAnchor).toBe(true);
     expect(tiny.availableHeight).toBe(160);
+    expect(tiny.top + tiny.availableHeight).toBeLessThanOrEqual(240 - 40);
+  });
+});
+
+describe('浮层水平收口：贴着卡片，但恒定留在画布内', () => {
+  const canvasWidth = 900;
+  const panelWidth = resourceCanvasGenerationPanelWidth(canvasWidth);
+
+  test('宽度口径与浮层 CSS 同源：min(560, 画布宽 - 24)', () => {
+    expect(panelWidth).toBe(RESOURCE_CANVAS_GENERATION_PANEL_MAX_WIDTH);
+    expect(resourceCanvasGenerationPanelWidth(500)).toBe(
+      500 - RESOURCE_CANVAS_GENERATION_PANEL_VIEWPORT_INSET * 2,
+    );
+    // 画布未就绪（量不到宽）时退回最大宽度，交给 CSS 收。
+    expect(resourceCanvasGenerationPanelWidth(0)).toBe(
+      RESOURCE_CANVAS_GENERATION_PANEL_MAX_WIDTH,
+    );
+  });
+
+  test('卡片贴左边 / 贴右边时锚点收进来，浮层两边各留 12px', () => {
+    const left = clampResourceCanvasGenerationPanelAnchorX({
+      centerX: 20,
+      canvasWidth,
+      panelWidth,
+    });
+    expect(left - panelWidth / 2).toBe(
+      RESOURCE_CANVAS_GENERATION_PANEL_VIEWPORT_INSET,
+    );
+
+    const right = clampResourceCanvasGenerationPanelAnchorX({
+      centerX: canvasWidth - 5,
+      canvasWidth,
+      panelWidth,
+    });
+    expect(right + panelWidth / 2).toBe(
+      canvasWidth - RESOURCE_CANVAS_GENERATION_PANEL_VIEWPORT_INSET,
+    );
+
+    // 卡片在中间时不动：收口只在真的会越界时才生效。
+    expect(
+      clampResourceCanvasGenerationPanelAnchorX({
+        centerX: canvasWidth / 2,
+        canvasWidth,
+        panelWidth,
+      }),
+    ).toBe(canvasWidth / 2);
+  });
+
+  test('画布比浮层还窄时居中（宽度收口交给 CSS），几何非法时原样返回', () => {
+    const narrowCanvas = 400;
+    const narrowPanel = resourceCanvasGenerationPanelWidth(narrowCanvas);
+    expect(
+      clampResourceCanvasGenerationPanelAnchorX({
+        centerX: 10,
+        canvasWidth: narrowCanvas,
+        panelWidth: narrowPanel,
+      }),
+    ).toBe(narrowCanvas / 2);
+
+    expect(
+      clampResourceCanvasGenerationPanelAnchorX({
+        centerX: 33,
+        canvasWidth: Number.NaN,
+        panelWidth: 560,
+      }),
+    ).toBe(33);
+    expect(
+      clampResourceCanvasGenerationPanelAnchorX({
+        centerX: 33,
+        canvasWidth: 800,
+        panelWidth: 0,
+      }),
+    ).toBe(33);
   });
 });
diff --git a/deploy/systemd/genarrative-database-backup-files-minimal.conf b/deploy/systemd/genarrative-database-backup-files-minimal.conf
new file mode 100644
index 000000000..c8d2e43fe
--- /dev/null
+++ b/deploy/systemd/genarrative-database-backup-files-minimal.conf
@@ -0,0 +1,5 @@
+[Service]
+Environment=GENARRATIVE_DATABASE_BACKUP_FILES_CONCURRENCY=4
+Environment=GENARRATIVE_DATABASE_BACKUP_UPLOAD_MAX_BYTES_PER_SECOND=20971520
+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 full --minimal --retain-snapshots 2 --freeze-dir /var/lib/genarrative/database-backups/files-minimal-freeze --data-dir /stdb --work-dir /var/lib/genarrative/database-backups/files-minimal
diff --git a/docs/project-memory/plans/【里程碑】AGC更新发布管线渠道化-2026-09-17.md b/docs/project-memory/plans/【里程碑】AGC更新发布管线渠道化-2026-09-17.md
index 5191b0129..3498047bd 100644
--- a/docs/project-memory/plans/【里程碑】AGC更新发布管线渠道化-2026-09-17.md
+++ b/docs/project-memory/plans/【里程碑】AGC更新发布管线渠道化-2026-09-17.md
@@ -13,7 +13,7 @@
 
 ## 范围
 
-- 构建期按渠道生成清单：版本按渠道独立递增，清单包含该渠道平台的下载地址与签名；`dev-mac` 的 universal 包按同一地址与签名同时写入 `darwin-aarch64` 与 `darwin-x86_64`。
+- 构建期按渠道生成清单：版本按渠道独立递增，清单包含该渠道平台的下载地址与签名；macOS 自 2026-09-21 起只出 arm64 单架构，`dev-mac` 只登记 `darwin-aarch64`（原 universal 双键口径已作废：随包 Node 只有单架构官方发行版，需先实现双架构运行时才能恢复 Intel，见 `docs/project-memory/shared-memory/decision-log.md`）。
 - 构建期生成更新产物签名，并在缺少签名私钥或私钥不可用时失败关闭。
 - 渠道参数与目标平台绑定校验：Windows 目标只能发布 `dev-win`，macOS 目标只能发布 `dev-mac`；未显式指定时按目标平台取默认渠道。
 - 上传按渠道落位：安装包与签名进版本目录，清单覆盖写渠道路径的 latest 指针。
diff --git a/docs/project-memory/shared-memory/decision-log.md b/docs/project-memory/shared-memory/decision-log.md
index 1be83edca..881074f0d 100644
--- a/docs/project-memory/shared-memory/decision-log.md
+++ b/docs/project-memory/shared-memory/decision-log.md
@@ -1,5 +1,15 @@
 # 决策记录
 
+## 2026-09-21 macOS 发布改为只出 arm64 单架构（Intel 暂不支持）
+
+- 背景：Mac 发布管线按 `universal-apple-darwin` 构建，但随包 Node 便携运行时只有**单架构官方发行版**（`stage-node-runtime.mjs` 从 `process.execPath` 取材），于是 macOS Job #7~#13 连续失败在「Node 运行时不支持发布目标：universal-apple-darwin」。期间出现过一版「按宿主架构放行」的过渡实现，它能骗过通用包自检（`check-macos-bundle.mjs` 按 `process.arch` 校验），但 Intel 上那份 arm64 侧车不可执行，并且已发布的 dev-mac 0.1.86 就带着这个缺陷。
+- 决策：macOS 固定只构建 `aarch64-apple-darwin`，渠道清单只登记 `darwin-aarch64`（不再登记 `darwin-x86_64`，避免把 arm64 产物发给 Intel 客户端）；`targetRuntime('universal-apple-darwin')` 保持失败关闭，入口 `build-macos-ci.mjs` 只跑 arm64 隔离 smoke，首装包命名 `<产品名>_<版本>_aarch64.dmg`。
+- 原因：要让 Intel 真正可用，必须让发布包按架构各带一份**同版本**运行时（另下载另一架构官方发行版）+ 通用包自检按架构分别校验，这是一条独立且更大的改动；在 DDL 前用「只带宿主架构」糊过去等于把坏包发给 Intel 用户，比暂不支持更糟。单架构同时把构建时间与产物体积减半。
+- 验证：`node --test apps/ai-game-creator-shell/scripts/*.test.mjs` 92/92（含 `targetRuntime('universal-apple-darwin')` 必须抛错、入口固定 arm64 目标与 `_aarch64.dmg` 后缀的守卫用例）；`npm run check:production-ops`、`check:encoding`、`check:doc-index`、prettier、eslint、`git diff --check` 通过；真实端到端由 Jenkins Mac Job 验证（清单只含 `darwin-aarch64`、DMG 与更新包唯一匹配）。
+- 影响范围：`apps/ai-game-creator-shell/scripts/{build-macos-ci.mjs,stage-node-runtime.mjs,prepare-macos-codex.test.mjs}`、`jenkins/Jenkinsfile.ai-game-creator-shell-macos-build`、本仓三份技术/运维文档与共享记忆。未动 Windows 渠道、未动 Rust 侧运行时解析（单架构仍是扁平 `game-runtime/node/`）。
+- 恢复 Intel 的路径：先在 staging 支持按架构各带一份同版本运行时并让通用包自检按架构校验，再切回 universal 目标、把 `darwin-x86_64` 键登记回去并补 Intel 真机验收。
+- 已知未覆盖：Intel Mac 用户的更新体验（清单缺 `darwin-x86_64` 键，客户端会「无可用更新」，未实测其 UI 文案）；Mac 包里仍并列携带两套 Codex 原生依赖（只运行 arm64 切片，可按需瘦身）。
+
 ## 2026-09-21 图集切片上限：客户端结果门从 64 对齐到平台契约的 256
 
 - 背景：现场（项目 `gameagent-6e53c9e8`，2026-09-21 07:54）「AI 生成图标素材」失败：`platform-generation-result-unknown: 异步生成完成结果无法绑定到 operationId：External Editor 旧同步结果的图集切片超过 64 个`。任务账本（`.agent/runtime/asset-generation-tasks/tasks.json`）显示它跑了 99 秒、`assetId` 为空、没有落任何素材；对应的持久化请求（`canvas-generation-requests/manual-canvas-asset-generate/slot-560175669f….json`）是 `sliceMode: connected-components` + `sliceCount: null`（自动切分）。也就是**平台已经生成并切完图了，是客户端在绑定结果这一步把整条结果判失败**，付费产物被丢弃。
diff --git a/docs/project-memory/shared-memory/pitfalls.md b/docs/project-memory/shared-memory/pitfalls.md
index 51ed5f002..cf6db49d9 100644
--- a/docs/project-memory/shared-memory/pitfalls.md
+++ b/docs/project-memory/shared-memory/pitfalls.md
@@ -1,5 +1,15 @@
 # 踩坑与排障记录
 
+## macOS 只出 arm64 单架构，universal 必须失败关闭
+
+`stage-node-runtime.mjs` 只把**构建宿主的 Node**打成便携运行时（官方发行版是单架构，没有 universal 发行版），而 2026-09-21 之前 `build-macos-ci.mjs` 构建的是 `universal-apple-darwin`：macOS Job #7~#13 因此在 `stageNodeRuntime` 直接抛「Node 运行时不支持发布目标：universal-apple-darwin」。期间出现过一版「按宿主架构放行」的过渡实现（`targetRuntime` 对 universal 返回宿主架构），它能骗过通用包自检（`check-macos-bundle.mjs` 按 `process.arch` 校验），但**Intel Mac 上这份 arm64 侧车不可执行**，等于把坏包发出去。当前决策：macOS 固定只构建 `aarch64-apple-darwin`，清单只登记 `darwin-aarch64`，`targetRuntime('universal-apple-darwin')` 保持失败关闭。恢复 Intel 的正确路径是先在 staging 支持按架构各带一份**同版本**运行时（另下载另一架构官方发行版）并让通用包自检按架构分别校验，再切回 universal 目标、把 `darwin-x86_64` 键登记回去；不得用「只带宿主架构」充数，也不得把 arm64 产物登记成 x86_64 键。
+
+## release 冷备空间不足会把生产留在维护态
+
+`Genarrative-Stdb-Module-Publish` 先进入维护模式、停掉 API/controller/worker，再执行发布前冷备份；archive 口径要求 `data × 1.1`（40.6GiB 数据 → 44.7GiB，加上生产根盘只剩 13.5GiB），于是 2026-09-21 的 release 发布在停服后失败并保持维护态，站点 503 直到人工恢复。规则：空间预检必须先于 `maintenance-on` 与停服；archive 不足且未显式禁用降级时改用 files（`max(data × 0.05, 2GiB)`，不落地本地归档，但 files 不支持 `--defer-upload`，会从 async 收敛为 sync）；只有真正开始 `spacetime publish` 之后的失败才允许保持维护态。另：定时备份的失效锁在当前仓库版本会自动清理，但生产机 `/var/lib/genarrative/backup-tools/database-backup-to-oss.mjs` 若是旧版会拒绝抢锁并要求人工删锁，需随 provision 更新。
+
+按上游 [#5555](https://github.com/clockworklabs/SpacetimeDB/pull/5555) 的 retention 语义，只有最近 `retain-snapshots`（默认 2）份 snapshot 与覆盖它之后的 commitlog 段是重启所需，其余历史可丢；因此备份改为 `files + full + --minimal --retain-snapshots 2`（release 实测 40G → 3.6G，热备不停服），不再做增量差异计算，也不需要 44.7G 冷备空间。
+
 ## copyArtifacts 报「Unable to find project for artifact copy」的用户触发构建差异
 
 Copy Artifact 插件在**非 SYSTEM 认证**下按「认证用户」判权：只有当被复制 Job 的 `CopyArtifactPermissionProperty`（仓库里由 Declarative 的 `copyArtifactPermission(...)` 维护）显式列出当前消费者，或者该 Job 对认证用户开放 Item.Read 时才放行；`ACL.SYSTEM2` 的定时构建会短路通过。因此会出现「定时调度一路成功、手动发布必挂」的现象（2026-09-21 手动发布 #6/#7 与同期的用户触发探测全部命中，定时调度 #104+ 正常）。`Genarrative-Agc-Global-Version-Issue` 生产权限模式的授权名单必须同时包含 `Genarrative-Scheduled-Revision-Trigger` 与 `Genarrative-Manual-Build-And-Deploy`；改完 `copyArtifactPermission` 后要先跑一次发号 Job 把 Job property 写回 Jenkins，只改仓库文件不生效。
@@ -11,6 +21,23 @@ Copy Artifact 插件在**非 SYSTEM 认证**下按「认证用户」判权：只
 - 处理：客户端门统一到 `PLATFORM_ART_SPRITESHEET_MAX_SLICES = 256`，判据与文案各只留一份（数字由常量插值），并在注释里点名三处同值权威（平台切分常量、工具 schema、公开契约）。
 - 复用判据：凡是「平台产出 → 客户端校验后落盘」的链路，客户端门只能表达**安全 / 预算**约束，不得比平台的产品上限更严；两边上限要引同一个常量或同一份文档，改一边时必须同时改另一边，并补一条「上限之内必须能落盘」的回归用例。
 
+## 2026-09-21 画布卡片「拖一下就触发点击」：阈值与点击抑制必须是卡类手势的一份判据
+
+- **现象**：拖动未生成的资源占位卡（背景音乐 / 音效等所有类型）松手后，卡片自己的点击语义被多执行一次——生成浮层被顺手弹开或收起。
+- **成因**：浏览器在 `pointerdown` 与 `pointerup` 落在同一节点上时**一定会补一次 `click`**，与中间移动了多少无关。生成占位卡那条手势把「收到过 pointermove」当成拖动信号（按下时浏览器就可能补一次零位移的 move），而且没有任何点击抑制；资源卡那条链路早就用 `RESOURCE_CANVAS_DRAG_THRESHOLD`（5px）+ `skipNextResourceCardClickRef` 处理过这件事，两条链路各写一套，于是只有占位卡漏。
+- **处理（现行口径）**：卡类手势只有一份判据 `resourceCanvasGestureExceededDragThreshold`（`features/resource-canvas/resourceCanvasCardGestureModel.ts`，阈值仍取 `RESOURCE_CANVAS_DRAG_THRESHOLD`）；拖动收尾那次 `click` 由手势层登记一次性抑制、宿主在「点卡片」的入口消费（占位卡是 `consumeDragClick`，资源卡是 `skipNextResourceCardClickRef`），抑制活过一个宏任务就清干净。「拖动中」样式也从越过阈值那一刻起才亮。
+- **相邻一档**：从删除按钮起手、松手落回卡片的手势，`click` 会被派给共同祖先（卡片）——判据要看**起手点**（`ResourceCanvasGenerationPlaceholderCardView` 的 `gestureOriginRef`），不能只看移动距离。
+- **易错点**：把「拖动样式」放在 `pointerdown` 上置位，等于承认「按下即拖动」，紧接着的点击又会被自己的抑制吃掉；阈值与抑制必须同时按同一判据走。
+
+## 2026-09-21 画布浮层几何只能按卡片的真实屏幕位置算，分页锚点必须让开钉死的标题栏
+
+- **现象一（浮层与画布边缘碰撞）**：生成浮层底边越过画布下沿被 `overflow: hidden` 切掉，卡片靠左右边时浮层还会有一半落到画布之外。
+- **成因**：可用高度只按「安全带高度 − 卡高」算，等于假设占位卡永远贴在安全带上沿；占位卡是追加在栏目内容最下方的，落到下半屏是常态。水平方向则完全没有收口——浮层 560px 宽、按卡片中心居中展开，卡片靠边必然越界。
+- **处理（现行口径）**：`resolveResourceCanvasGenerationPanelPlacement` 吃卡片的**屏幕顶边**，顶边与可用高度都由真实位置算（卡下面塞不下就改为盖住占位，且顶边收进安全带）；水平用 `clampResourceCanvasGenerationPanelAnchorX` 把锚点收进「浮层左右各留 12px」的区间。浮层宽度口径（`min(560px, calc(100% - 24px))`）在 CSS 与模型里各一份，有声明级守卫用例钉住同源。
+- **现象二（生成任务开关压在标题栏上）**：资源栏目画布页顶部钉着整宽的栏目标题栏（`.game-resource-book-scene-titlebar`，42px，右端是「返回资源总览」），右上角开关按总览页的坐标摆就会直接压在它上面。
+- **处理（现行口径）**：「生成任务」锚点按页分档（`canvas-overview` / `canvas` / `run` / `editor`）：画布页让开那条标题栏的高度再加一段间隙，总览页仍贴画布顶边内缩；两档之间的高度差走 `margin-top` 过渡（`prefers-reduced-motion` 下关掉）。让开多少与标题栏多高是**跨文件关系**，守卫用例读全局样式表里那条 `min-height` 断言「让开得比它高」。
+- **易错点**：给锚点写死 `top`，或只按某一页的 chrome 算一次坐标，工具条换行、页面切换或标题栏高度调整后都会重新压上去。
+
 ## Jenkins Windows 节点的 PATH 白名单决定 Godot 原生扩展能否构建
 
 `Genarrative-Agc-Windows-Build` 在阶段里用 `AGC_WINDOWS_PATH` 整体替换 PATH、不继承节点机器的 PATH，所以 Godot C++ 引导需要的 CMake 与 Python 必须显式写进这份白名单，装在机器 PATH 上并不生效。2026-09-21 的 #97–#99 连续失败都停在 `Get-Command cmake.exe`（#93–#96 是更早的手写 C ABI 在 MSVC C 模式下的对齐问题）：节点只有 Visual Studio Build Tools（`C:\BuildTools`）自带的 CMake 3.31，缺 Python 3。修复后白名单包含 `C:\BuildTools\Common7\IDE\CommonExtensions\Microsoft\CMake\CMake\bin`、`C:\Python312`、`C:\Python312\Scripts`，preflight 校验 CMake ≥3.25、Python 3 和 Visual Studio 17 2022 生成器；把 `cmake.exe` 单独复制到别的目录会丢掉 `share/cmake-*/Modules`，不能替代加入安装目录。新节点的 Python 用 `python-3.12.10-amd64.exe /quiet InstallAllUsers=1 TargetDir=C:\Python312 PrependPath=1 Include_launcher=1 InstallLauncherAllUsers=1` 静默安装即可，CMake 不必另装。
@@ -96,6 +123,7 @@ Vite 默认监听应用根下的 Rust `src-tauri/target`，构建产物较多时
 - **易错点**：① 把弹层改成 `left: 0` 或往右挪也能让它可见，但那是改变展开方向，弹层会跑到触发钮右边（用户明确否决）；② 只放开最外层聊天列不够——surface 与 conversation 各自都会裁，三层必须同时放开；③ 只按宽度比大小会误判：280px 面板里控制排本身也超出（发送钮右侧溢出 22px，被窗口右缘吃掉），那不是本条的原因，别顺手去改控制排布局。
 - **验证**：`apps/ai-game-creator-shell/tests/appSurface/project-development.suite.ts` 的 `keeps the landscape workbench edge-to-edge with internal chat scrolling` 钉住三条 override 声明在场（删掉任一条即红）。真机几何用 playwright-cli 打开一份只含真实 `styles.css` 与真实 composer DOM 的最小复现页实测（视口 1000×700、面板 280px）：弹层 rect 修复前后都是 `[-42, 108]`（位置未动），`elementFromPoint` 的命中区间从修复前的 `[2, 108]` 变成整块；档位文字在截图中完整可见。
 - **关联**：`apps/ai-game-creator-shell/src/styles.css`（`面板纵向布局（2026-07 Codex 风格改造）` 区块之后）、`apps/ai-game-creator-shell/tests/appSurface/project-development.suite.ts`。
+
 ## 2026-09-17 资源卡「内容跟着边框动」与「模型缩略图被拉伸」是两条不同的几何陷阱
 
 - **内容跟着状态边框位移**：卡片底态是 `border: 0`，悬停 / 选中才加 1px 边框；卡片是 `box-sizing: border-box`，而卡面（`.game-resource-card-visual`）与角标都是 `position: absolute; inset: 0`（包含块 = **padding box**）⇒ 状态一切换，内容盒四边各被吃掉 1px，卡面与角标整体位移并缩小 2px。修法：底态写成 `border: 1px solid transparent;`，状态只点亮 `border-color`；契约用例改成断言「资源卡规则里不得出现非 1px 的 `border` / `border-width`」。
@@ -142,6 +170,7 @@ Direct 工具桥会 canonicalize 项目根，事件中的路径可能带 `\\?\`
 - **处理（现行口径）**：① 渲染 `ProjectDevelopmentView` 的桩统一登记 `list_local_project_asset_generations`（返回**数组**，空账本 `[]`；Rust 侧返回 `Vec<AssetGenerationTaskRecord>`，不是 `{ tasks: [] }`）；② `unexpectedCommands` 这类门禁**不要放宽**，只登记合法命令；③ 生产代码对 IPC 返回值做形状防御（`Array.isArray` 归一化），IPC 拒绝走既有提示路径，不产生 unhandled rejection（`resourceCanvasAssetGenerationTaskModel.ts` / `resourceCanvasAssetGenerationQueue.ts` / `index.tsx` 的恢复 effect）。
 - **易错点**：① 桩返回**非数组**时用例可能"看着绿"但同时报 unhandled rejection（实测：把 `[]` 误写成 `{ tasks: [] }` 就是 8 passed + 7 unhandled error），所以判"绿"必须同时看 unhandled 计数；② 新增挂载期 IPC 后要一次性 grep 所有 `ProjectDevelopmentView` 的桩，而不是等 CI 逐个炸；③ 提示条类断言（如「无读时提示」）会把「桩抛错」翻译成「多了一条提示」，排查时先看 unhandled，再看断言。
 - **关联**：`apps/ai-game-creator-shell/tests/resourceCanvasManualLayout.test.tsx`、`apps/ai-game-creator-shell/tests/appSurface/project-development.suite.ts`、`apps/ai-game-creator-shell/src/features/resource-canvas/resourceCanvasAssetGenerationTaskModel.ts`。
+
 ## 2026-09-14 UI 编辑器返回后资源画布滚轮平移失效
 
 - **现象**：资源管理打开 UI 编辑器再返回后，资源画布滚轮平移/缩放不再响应；返回前同一手势正常。
@@ -149,6 +178,7 @@ Direct 工具桥会 canonicalize 项目根，事件中的路径可能带 `\\?\`
 - **处理**：将 `uiEditorRoute` 纳入 wheel effect 依赖，使进入/退出 UI 编辑器时先清理旧节点监听，再给返回后的新 manager 绑定同一处理器。
 - **验证**：`npx vitest run apps/ai-game-creator-shell/tests/appSurface.test.ts -t "restores resource canvas panning"`；回归用例覆盖打开栏目、wheel 平移、进入 UI 编辑器、返回并再次 wheel 平移。
 - **关联**：`apps/ai-game-creator-shell/src/view/project-development/index.tsx`、`apps/ai-game-creator-shell/tests/appSurface/project-development.suite.ts`。
+
 ## 2026-09-14 AGC 就绪等待被 WMI 拖成分钟级：端口归属探测从 Get-NetTCPConnection 换成 netstat
 
 - **现象**：`npm run agc` 从 `[ai-game-creator-shell] starting backend stack` 到 `backend ready` 要等约 80 秒，中途反复出现 `等待配套后端就绪时归属校验未通过（api-server-owner-mismatch: 未知进程）`；而这段时间后端其实已经好了（实测 api-server 12:39:01 已在 8084 监听、`/healthz` 已 200，12:40:19 才判 ready）。
@@ -157,6 +187,7 @@ Direct 工具桥会 canonicalize 项目根，事件中的路径可能带 `\\?\`
 - **验证**：`apps/ai-game-creator-shell/tests/start-dev-stack.test.ts` 新增两条——「探测脚本使用 netstat 且不再出现 Get-NetTCPConnection」「命令行按 PID 缓存后随请求下发、TTL 过期即失效」；定向 vitest 55 passed。本机实测：不含 SpacetimeDB 端口的探测 368 ms（原约 22 秒）、含 SpacetimeDB 端口 3.8 秒、命中缓存 368 ms；`npm run agc:serve` 的 `starting backend stack` → `backend ready` 由约 80 秒降到 16.7 秒（其中归属校验只占 4.4 秒，其余是 SpacetimeDB + api-server 的真实启动时间）。
 - **残留**：这台机器上首次 WMI 调用本身仍是秒级（曾见 18 秒），所以「新 SpacetimeDB PID 的第一次探测」仍可能多花几秒；命令行在进程存活期内不变，TTL 只用来限制 PID 复用造成的误判窗口。
 - **关联**：`apps/ai-game-creator-shell/scripts/start-dev-stack.mjs`（`readWindowsPortOwnerIdentities`）、`apps/ai-game-creator-shell/tests/start-dev-stack.test.ts`、`apps/ai-game-creator-shell/scripts/dev-windows-process.mjs`（退出清理仍走整份 `Win32_Process` 快照，自带 1 秒缓存，不在本次范围）。
+
 ## 2026-09-15 AGC JSON API 的响应体也必须有等待上限
 
 - `fetchClientHttp` 的超时只覆盖请求到响应头返回；随后直接等待 `response.text()` 仍可能无限挂起。模型目录共用一个在途 Promise，响应体卡住会使后续刷新复用同一挂起请求、选择器持续忙碌。
@@ -181,6 +212,7 @@ Direct 工具桥会 canonicalize 项目根，事件中的路径可能带 `\\?\`
 - **处理**：`runNativeShellGate` 收窄为 `(group, gate)`，label 回到各门禁执行体里以字面量打印；分组能力与 `--groups=` 语义不变。脚本内已注明"不要把 label 抽成变量"，外部壳的 `check-config` 是它的消费者。
 - **验证**：`node apps/mobile-shell/scripts/check-config.mjs` exit 0；`node apps/desktop-shell/scripts/check-config.mjs` 已越过第 740–777 行的根脚本断言段（本机随后卡在本机不存在的 Tauri 生成产物目录，与本次改动无关）；`--groups=contract`、vitest `scripts/project-ci-workflow.test.ts`、eslint 均通过。修复后 run 2097 六个 job 全绿。
 - **关联**：`scripts/check-native-shells.mjs`（`runNativeShellGate`）、`apps/desktop-shell/scripts/check-config.mjs`、`apps/mobile-shell/scripts/check-config.mjs`。
+
 ## 2026-09-14 AGC 资源画布不要恢复「无条件重派生」，否则新增一张素材就整张重排
 
 - **现象**：用户生成一张新素材后，画布上既有卡片全部移位，刚摆好的位置失效。
diff --git a/docs/technical/【AGC】栏目画布底部工具栏入口矩阵-2026-09-13.md b/docs/technical/【AGC】栏目画布底部工具栏入口矩阵-2026-09-13.md
index e95d7f07d..1de78d7c0 100644
--- a/docs/technical/【AGC】栏目画布底部工具栏入口矩阵-2026-09-13.md
+++ b/docs/technical/【AGC】栏目画布底部工具栏入口矩阵-2026-09-13.md
@@ -59,8 +59,10 @@
 - **工具条动作行的间距只有一套**：行内按钮之间统一 24px（行 `gap: 7px` + 按钮左右 `padding: 11px`；「依赖 / 类型」分段控件内部是 0 间距的连通分段，靠 `margin-left: 17px` 与前一按钮保持同样的 24px）。**布局状态提示（`game-resource-reorder-status`）不进这一行**——它是随保存过程变长的文案（空 →「保存中」→「布局已保存」→ 失败原因），作为 flex 子项会把右侧按钮按文本宽度顶开，同一行不同时刻的按钮间距就会不一样；它改为工具条内的绝对定位，位置固定。
 
 - **复用**：比例 / 尺寸选项与默认值来自网页端美术画布的纯模型 `src/components/image-editor/ImageCanvasGenerationModel.ts`（`EDITOR_IMAGE_DIMENSION_OPTIONS` / `IMAGE_MODEL_NANOBANANA2`），尺寸标签复用 `resolveEditorImageSizeLabel`；提示词上限复用 AGC 自己的 `resourceEditPromptMaxLength`（图片类默认 32000，与 Rust `LOCAL_PROJECT_ASSET_MAX_PROMPT_CHARS` 同口径）；「AI 润色」复用 `ResourcePromptPolishSlot`（`polish_local_project_prompt`）；面板外壳复用 AGC 的 `ThemedModal`（与「生成素材」面板同一套宿主 chrome）。
+- **参考图（`@` 引用）**：提示词输入区就是聊天 / 快速编辑同一个共享组件 `ResourceReferenceInput`（`@` 按钮的文案是「插入素材引用」，候选集只放当前项目已登记的位图，SVG 与未落盘条目排除）。是否挂它只由**一条**判据决定：`resourceCanvasAssetGenerationAcceptsReferences`（前端）与 `platform_art_asset_kind_accepts_user_reference_assets`（Rust）——**唯一例外是图集 `icon-spritesheet`**（合同只接受单张权威规范引用，原生对多余参考是显式拒绝）。图标规范 `icon-spec` 虽然产出权威规范图，但生成时同样可以带参考，上限与普通生成一致（5 张；带规范前置的入口是「权威规范图 1 张 + 用户参考 4 张」）。面板里那句「图标规范不给选择器」是 kind 词汇收敛前的残留注释，已按现行判据改写，并补了「逐条入口的 `@` 与判据一致」的用例防止再漂。
+- **图集（生成图标素材）为什么没有 `@`**：图集走的是**另一条平台通道** `POST /api/external/v1/editor/icon-spritesheets/generations`，客户端提交体是 `referenceId`（唯一一张独立权威规范图）+ `iconDescriptions` + 切片参数（`sliceMode` / `sliceCount` / `gridX` / `gridY` / `screenColor`），**没有** `referenceImageSrcs`；结果绑定阶段还硬校验「参考集合恰好一张、且不等于产物自身」（`strict spritesheet 图集必须绑定唯一且独立的 art-spec resourceId`）。也就是说图集的「参考」在客户端合同里被定义为那一张权威规范图，图标内容靠 `iconDescriptions`（由提示词派生）描述。因此前端不给选择器、原生对用户参考是**显式拒绝**（错误原文：`透明美术图集只接受规范图引用，不接受用户参考素材`），而不是静默丢弃；面板里那句「该入口走平台图集通道……」就是这条口径的当面说明。**可行但未做**：平台 OpenAPI 的 `EditorIconSpritesheetGenerationRequest` 里**有** `referenceImageSrcs` 字段（客户端目前不发），所以「放开图集的用户参考」是产品 + 平台口径变更，需要同时改 Rust（判据 / 请求体 / 结果绑定校验与上限）与前端，不在本轮范围内。
 - **收窄**：本地 IPC 的比例白名单是 `1:1 / 2:3 / 3:2 / 9:16 / 16:9`，网页端还有 `4:3`。前端做的是「主站纯模型 ∩ 本地白名单」，不是另抄一份选项表（测试钉住两者包含关系与 `4:3` 缺席）。
-- **没有复用到的**：网页端的生成 composer 子视图（`ImageCanvasBasicGenerationComposerView` / `ImageCanvasCharacterGenerationComposerView` / `ImageCanvasIconSpritesheetComposerView` / `ImageCanvasSpecGenerationPanelView` / `ImageCanvasGenerationImageOptionsView`）。原因有二：① 它们的比例选项含本地通道拒绝的 `4:3`；② 它们自带模型选择器、参考图槽位、BFF 直连（`ImageCanvasSpecGenerationPanelView` 直连 `/api/editor/llm/icon-specs/*`，AGC 无该通道），本地 IPC 既没有 `model` 也没有参考图入参，照搬会渲染一批改不了请求的假控件。因此面板是 AGC 自己的薄壳，只把**纯模型**接进来。
+- **没有复用到的**：网页端的生成 composer 子视图（`ImageCanvasBasicGenerationComposerView` / `ImageCanvasCharacterGenerationComposerView` / `ImageCanvasIconSpritesheetComposerView` / `ImageCanvasSpecGenerationPanelView` / `ImageCanvasGenerationImageOptionsView`）。原因有二：① 它们的比例选项含本地通道拒绝的 `4:3`；② 它们自带模型选择器与 BFF 直连（`ImageCanvasSpecGenerationPanelView` 直连 `/api/editor/llm/icon-specs/*`，AGC 无该通道），本地 IPC 没有 `model` 入参，照搬会渲染一批改不了请求的假控件。参考图入参**不属于**这类缺口：AGC 侧由 `referenceAssetIds` 交原生按当前账号重新绑定（见上一条），面板照常呈现 `@`。因此面板是 AGC 自己的薄壳，只把**纯模型**接进来。
 - **不做的**：不改 Rust、不改 external v1 / OpenAPI、不改 `packages/`（共享包只被消费）、不复制主站 `src/components/image-editor/` 目录。
 
 ## 6. 前置规范图与不可用原因
diff --git a/docs/technical/【技术方案】AGC客户端更新检查与下载-2026-08-31.md b/docs/technical/【技术方案】AGC客户端更新检查与下载-2026-08-31.md
index 8fa50c4f1..69559ba2a 100644
--- a/docs/technical/【技术方案】AGC客户端更新检查与下载-2026-08-31.md
+++ b/docs/technical/【技术方案】AGC客户端更新检查与下载-2026-08-31.md
@@ -98,11 +98,11 @@
 | 系统      | 构建目标                 | 清单平台键                                     | 更新包                   | 清单地址                             |
 | --------- | ------------------------ | ---------------------------------------------- | ------------------------ | ------------------------------------ |
 | Windows | `x86_64-pc-windows-msvc` | `windows-x86_64`                               | NSIS `.exe` + `.exe.sig` | `<OSS base>/agc/<channel>-win/latest.json` |
-| macOS | `universal-apple-darwin` | `darwin-aarch64` + `darwin-x86_64`（同一对象） | `*.app.tar.gz` + `.sig` | `<OSS base>/agc/<channel>-mac/latest.json` |
+| macOS | `aarch64-apple-darwin` | `darwin-aarch64` | `*.app.tar.gz` + `.sig` | `<OSS base>/agc/<channel>-mac/latest.json` |
 
 - 对象布局：清单固定写成 `agc/<channel>-win|mac/latest.json`；安装包与签名写成同一分区的 `<version>/<file>` 与 `<file>.sig`。
-- macOS 正式交付使用 universal 主程序：两个平台键指向同一个 `.app.tar.gz` 与签名，一份产物同时服务 Apple Silicon 与 Intel。单架构目标（`aarch64-apple-darwin` / `x86_64-apple-darwin`）只用于本机诊断，不登记正式分区清单——单架构构建不可轮流覆盖同一个 `latest.json` 并宣称双架构均可更新。
-- universal 主程序同时携带分目录的 arm64/x64 原生 Codex 组件：每个组件保持上游单架构布局与独立 SHA-256 清单，运行中的主程序切片只选择同架构目录，不得把两套原生包的元数据或辅助程序混装。
+- macOS 当前只出 Apple Silicon 单架构包（`aarch64-apple-darwin`），清单只登记 `darwin-aarch64`；**不再**登记 `darwin-x86_64`，避免把 arm64 产物发给 Intel 客户端。恢复 Intel（universal）的前置条件是随包 Node 也能按架构各带一份：`stage-node-runtime.mjs` 对 universal 目标失败关闭，因为一台构建机只能提供宿主架构的官方 Node，只带一份会让 Intel 上该运行时不可执行，而通用包自检按 `process.arch` 校验、抓不到这个问题。
+- 主程序当前只出 arm64 单架构，但 `tauri.macos.conf.json` 仍并列映射 `darwin-arm64` / `darwin-x64` 两套原生 Codex 组件：每个组件保持上游单架构布局与独立 SHA-256 清单，运行中的主程序切片只选择同架构目录，不得把两套原生包的元数据或辅助程序混装；随包 Node 只有宿主架构那一份（本地自检会按架构核对并实际执行它）。
 - 构建期要求：打开 `bundle.createUpdaterArtifacts` 以生成 `.sig`；构建环境提供签名私钥与密码（私钥内容不得入库）；公钥写入客户端配置。公钥在首个带更新能力的版本发布后不可更换，更换等于放弃自动更新（只能手动重装）。
 - 版本递增按渠道及系统分区独立进行：发布脚本读取该分区远端 `latest.json` 的 `version`，与本地版本取较高者递增 patch；不同分区的远端版本互不影响。
 - 版本高水位：仅 dev 的 Windows 分区在迁移窗口内取「分区清单版本」与「旧协议迁移指针版本」较大值再递增，避免已发布旧客户端版本倒退。迁移窗口结束（旧指针 404）后只读分区清单；release、自定义渠道与所有 Mac 分区均不参与旧指针比较。
@@ -146,7 +146,7 @@
 | 条款                         | 验收方式                                                                | 证据                                                                                                                                 |
 | ---------------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
 | 渠道与端点映射、渠道校验     | `node --test apps/ai-game-creator-shell/scripts/build-release.test.mjs` | 通过（默认渠道、错配失败关闭、未知渠道失败关闭）                                                                                     |
-| macOS universal 清单与双架构依赖 | 定向发布脚本与安装包验证 | 两个平台键同 URL/签名；两套资源独立校验，真机验收另记 |
+| macOS 单架构清单与随包资源 | 定向发布脚本与安装包验证 | 清单只有 `darwin-aarch64`；DMG/更新包按架构命名并唯一匹配；真机验收另记 |
 | 缺签名时失败关闭             | 同上                                                                    | 通过                                                                                                                                 |
 | 开发态不检查更新             | `vitest run apps/ai-game-creator-shell/tests/appUpdate.test.ts`         | 通过（开关关闭时不请求清单）                                                                                                         |
 | 旧自研链路整条删除           | 代码检索无残留命令、事件与白名单条目                                    | 通过（`download_agc_update` / 下载事件 / 清单常量均无残留）                                                                          |
@@ -168,10 +168,10 @@
 
 已决策：
 
-- macOS 采用 universal 包，两个平台键对应同一更新产物；主程序用 lipo 检查两种架构，Codex 资源分别做原生身份/摘要与启动验证。Rosetta 结果不代替 Intel 真机验收。
+- macOS 当前只验 arm64：主程序用 `lipo` 检查架构，Codex 与随包 Node 做原生身份/摘要与启动验证。恢复 Intel 后必须补回双架构 smoke 与 Intel 真机验收，Rosetta 结果不能替代。
 - 旧客户端迁移桥：保留一个版本周期。渠道清单上线后，发布管线同时把旧的 `agc/latest.json`（sha256 格式）指向 `dev-win` 最新安装包，让已发布客户端自动升级到新协议；下个周期整条删除。
 - 签名密钥：由本仓库维护者生成并保管，私钥保存在仓库外（`%USERPROFILE%\.tauri\genarrative-agc-updater.key`），只有公钥进入客户端配置；Jenkins 用受保护凭据 `AgcUpdaterSigningKey` 与 `AgcUpdaterSigningKeyPassword` 注入为 Tauri 打包器读取的 `TAURI_SIGNING_PRIVATE_KEY` 与 `TAURI_SIGNING_PRIVATE_KEY_PASSWORD`，本机可用 `TAURI_SIGNING_PRIVATE_KEY_PATH` 指向同一私钥。当前密钥不带密码；首次发布前仍可重新生成，首次发布后不可更换。
-- macOS 发布方式：已接入专用 macOS Jenkins 节点（label `genarrative-agc-macos`，EXCLUSIVE 单 executor），由 `Jenkinsfile.ai-game-creator-shell-macos-build` 执行 `scripts/build-macos-ci.mjs` 完成 universal 构建、双架构隔离 smoke、universal DMG、分区清单生成、更新包验签与 OSS 上传。`AGC_RELEASE_DRY_RUN` 默认为关（与 Windows 渠道对称，即直接发布），只有勾选后才退化为「只打印上传计划、不写 OSS」的演练。
+- macOS 发布方式：已接入专用 macOS Jenkins 节点（label `genarrative-agc-macos`，EXCLUSIVE 单 executor），由 `Jenkinsfile.ai-game-creator-shell-macos-build` 执行 `scripts/build-macos-ci.mjs` 完成 arm64 单架构构建、arm64 隔离 smoke、arm64 DMG（`<产品名>_<版本>_aarch64.dmg`）、分区清单生成、更新包验签与 OSS 上传。`AGC_RELEASE_DRY_RUN` 默认为关（与 Windows 渠道对称，即直接发布），只有勾选后才退化为「只打印上传计划、不写 OSS」的演练。
 - macOS 代码签名与公证暂缺：产物为未签名 + 未公证，构建入口剥离 `APPLE_*` 凭据跳过 Apple 签名，不传 `--no-sign`（它还会跳过 updater 的 minisign 签名，产物将没有 `.sig`）；构建清单实测记录 `appleSigned` 与签名类型，`latest.json` 侧固定记录 `notarized=false`，首装需用户在 Gatekeeper 中手动放行。该限制作为已知未验证项记录，不静默通过；「安装 → 重启接管新版本」的自动更新闭环仍需实机验收。
 - 更新包验签门禁：构建完成、上传 OSS 之前，用产物内烘焙的 `plugins.updater.pubkey` 复核 `<更新包>.sig`（Tauri 使用 minisign 的 `ED` 预哈希模式）。keyId 不一致或校验失败立即失败关闭，禁止上传——客户端校验失败会直接拒绝安装，且公钥发布后不可更换。
 
diff --git a/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md b/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md
index 0657da9a2..5417661f7 100644
--- a/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md
+++ b/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md
@@ -71,7 +71,7 @@
 
 ### 环境与工作流
 
-- 客户端交付配套 Node/npm；发布包从本机已安装且与目标平台/架构一致的工具链制作受校验资源，保留许可并校验内容摘要。安装态不依赖系统 PATH 的 Node；开发态可使用已验证的宿主运行时。不得从项目或相对 PATH 加载伪造运行时。
+- 客户端交付配套 Node/npm；发布包从本机已安装且与目标平台/架构一致的工具链制作受校验资源，保留许可并校验内容摘要。安装态不依赖系统 PATH 的 Node；开发态可使用已验证的宿主运行时。不得从项目或相对 PATH 加载伪造运行时。随包运行时是**单架构**官方发行版，因此 macOS 当前只构建 `aarch64-apple-darwin` 单架构包；要出 universal 必须先让 staging 支持按架构各带一份同版本运行时，在此之前 universal 目标失败关闭，不得只带宿主架构那一份糊过去。
 - 新建 Web 游戏在生图和大量实现前执行客户端环境预检，检查 Node/npm 的实际版本、浏览器启动和 CDP 可用性。报告只包含安全状态、版本、耗时和错误码。缺失或异常必须尽早返回阻塞，不能指示模型改宿主环境、全盘搜索或自行下载一套运行时。编辑器工程不强制 Web 工具链。
 - 预检不安装依赖、不修改项目 revision、不请求平台生成；构建仍执行项目自己的 npm 脚本。Codex 隔离 HOME 与平台凭据边界保持不变，客户端把已验证的运行时加入执行 PATH，不能把宿主凭据目录交给模型。
 - 第一轮先明确本次必需玩法、素材和验收项。同批独立读取尽量合并，必需图片一次规划；已有且可用的资产复用。已有目标全部通过后给出交付结果，非阻塞的新点子列为后续工作，不在收尾时主动开启新的生产链。
@@ -579,7 +579,7 @@ Supervisor 认领该回执后，由父 run 自己为每个原 delivery 逐一创
 - 调度边界：正式 DAG、manifest、Agent task/session/run 身份、队列、锁、委派、all-join、完成门、Provider lifecycle、持久 retry/handoff 与 `needs-reconciliation` 继续由现有 AGC Runtime 掌控。每个被调度节点在 `codex_cli` 模式下直接启动一次非交互 `codex exec` 充当该节点的推理 Agent；Codex 返回当前 Runtime 广告函数的结构化调用，Runtime 仍是唯一 ToolHost，不允许 CLI 自己写项目、执行命令、调用 MCP 或形成第二套 revision / verification 真相。
 - 安装包侧车：Windows x64 release 固定随 Tauri resource 打包 `@openai/codex@0.155.1` 的原生 `codex.exe`；Rust build script 从 AGC 子包锁定依赖 stage 到 resource，并写入版本与 SHA-256 清单。固定版本只在 `build_support/codex_bundle.rs` 声明一次，构建脚本、宿主补丁执行器身份、逐次审批协议允许列表和模型目录捕获共同引用它，避免多处字面量漂移。Windows 侧车映射只写入 `tauri.windows.conf.json`，通用 `tauri.conf.json` 不得让 Linux / macOS 构建依赖未生成的 Windows 二进制。运行时只在文件摘要和 `codex-cli` 版本同时匹配清单时优先选内置侧车；缺失、损坏或版本漂移时跳过它，按既有 npm 安装、PATH 顺序回退。安装包同时携带 Apache-2.0 第三方声明；API Key、`auth.json`、Cookie、Token、用户 `CODEX_HOME`、用户配置和项目数据绝不打包。
 - Windows x64 release 安装包只生成 NSIS，不生成 MSI：`tauri.windows.conf.json` 的 `bundle.targets` 固定为 `["nsis"]`，通用配置继续保留其它平台的默认打包目标。安装后的产品名、开始菜单 / 桌面快捷方式和 EXE 产品描述统一由 `tauri.conf.json` 的 `productName: "陶泥儿"` 生成；应用 identifier 与内部可执行文件名保持稳定。内置 Codex 资源安装到顶层 `coding-agent/win-x64/`，运行时从同一路径查找 `bin/codex.exe` 与 `manifest.json`；仓库 staging 仍使用 `resources/codex/win-x64/`，包内子目录、组件名、版本和完整性校验保持原合同。
-- macOS 安装包必须携带锁定版本的原生 Codex、`codex-code-mode-host`、`rg`、上游 zsh、`codex-package.json` 和第三方声明，保留上游相对布局；构建时按 Cargo 目标选择 npm 原生依赖，缺文件、版本或目标不匹配立即失败，不借用开发机 PATH 里的 Codex。资源只在 `tauri.macos.conf.json` 映射到 `Contents/Resources/coding-agent/mac-native/darwin-arm64/` 与 `darwin-x64/`。构建与运行共享平台文件白名单，运行时由当前 `.app/Contents/MacOS` 定位相邻 `Resources`，完整性与版本验证通过后优先使用内置组件；失败沿既有外部安装回退，不能运行未校验的内置文件。universal 主程序同时携带两套独立原生资源，运行切片按 Cargo 目标只选择对应目录；macOS 构建必须预备两套锁定原生依赖，不读取全局 Codex。
+- macOS 安装包必须携带锁定版本的原生 Codex、`codex-code-mode-host`、`rg`、上游 zsh、`codex-package.json` 和第三方声明，保留上游相对布局；构建时按 Cargo 目标选择 npm 原生依赖，缺文件、版本或目标不匹配立即失败，不借用开发机 PATH 里的 Codex。资源只在 `tauri.macos.conf.json` 映射到 `Contents/Resources/coding-agent/mac-native/darwin-arm64/` 与 `darwin-x64/`。构建与运行共享平台文件白名单，运行时由当前 `.app/Contents/MacOS` 定位相邻 `Resources`，完整性与版本验证通过后优先使用内置组件；失败沿既有外部安装回退，不能运行未校验的内置文件。macOS 当前只构建 arm64 单架构，但资源映射仍并列携带两套锁定原生 Codex 依赖（运行切片按 Cargo 目标只选择对应目录），恢复 Intel 时无需改动资源布局；随包 Node 只有宿主架构那一份，所以不得构建 universal 包。不读取全局 Codex。
 - 内置插件的清单、运行入口与面板同时在 Windows/macOS 随包分发，继续由既有 PluginHost 的应用资源目录扫描入口发现；不携带开发依赖、缓存、测试或私有配置。插件文件随包不等于原生适配器跨平台：Cocos 进程桥接仍受现有 Windows 实现和 feature 门禁约束，macOS 原生桥接另行设计与验收，不复制 Windows DLL 冒充支持。系统 Node、用户 Cocos Creator、账号登录、网络和生成工程的 npm 工具链仍是现有外部前提，不在此次 Codex 侧车补齐中隐式变更。
 - macOS 安装包验收必须包括：脱离仓库位置的 `.app` 资源与架构检查、受限 PATH/隔离 HOME 下内置 Codex 启动和 app-server 握手、必需文件缺失/篡改/平台错误的拒绝测试，以及 DMG 完整性检查。真实登录、Provider 对话、GUI 和 Cocos 操作必须独立列出证据，不能用压缩包生成或 `--version` 成功替代。未配置正式签名、公证的本地测试包不得作为公开发行包。
 - macOS 安装包的系统下限取主程序和全部原生组件中的最高要求；锁定 Codex 0.155.1 原生依赖中 `codex-resources/zsh/bin/zsh` 的 `LC_BUILD_VERSION` 下限为 macOS 15.0（`bin/codex`、`codex-code-mode-host`、`codex-path/rg` 分别为 11.0 / 10.12），因此 `bundle.macOS.minimumSystemVersion` 明确为 `15.0`。更新原生依赖时重新检查 Mach-O 的系统下限，不能只按 AGC 主程序宣称兼容版本。0.155.1 的 macOS 原生包新增 `codex-resources/voice/`（语音宿主与 GStreamer 动态库）；AGC 不启用语音能力，侧车清单只 stage 上述组件，不打包该目录，未来如启用语音需重新评估依赖与许可。
diff --git a/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md b/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md
index 8879824d4..efbc5bf6d 100644
--- a/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md
+++ b/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md
@@ -449,7 +449,7 @@ UI 相关修改要重点验证：
 npm run database:backup:oss -- --data-dir /stdb --stop-service spacetimedb.service --restart-service-after genarrative-api.service --restart-service-after genarrative-external-generation-worker@1.service --restart-service-after genarrative-external-generation-controller.service
 ```
 
-脚本会将数据目录打包成 `tar.gz`，上传到 `oss://<bucket>/<prefix>/<database>/<database>-<UTC时间>.tar.gz`。备份使用同库进程锁：仍存活的备份进程会阻断并发执行；持有锁的进程已退出时，脚本会自动清理失效锁并重试获取，不需要人工删除锁文件。生产建议做冷备份：传入 `--stop-service spacetimedb.service`，脚本会在打包前停止服务、打包后恢复服务，再上传 OSS；因 `genarrative-api.service`、`genarrative-external-generation-worker@*.service` 和 `genarrative-external-generation-controller.service` 都依赖 `spacetimedb.service`，生产定时冷备份还必须传入对应的 `--restart-service-after`，确保备份后 API、保底 worker 和 controller 随数据库一起恢复。`2026-06-10` release 故障就是现场 unit 漏掉 API 重启参数，`03:20` 冷备份停止 SpacetimeDB 后 API 被依赖关系一并停止，备份脚本只恢复了 SpacetimeDB，API 直到人工重启前都不可用；`2026-06-24` release 又出现同类依赖停机后只恢复 API、未恢复外部生成 worker/controller，导致图片画布生成任务长期停留在队列中。后续现场变更、provision 模板和 Jenkins 归档都必须通过 `npm run check:production-ops` 防止回退。由于 OSS 上传可能受服务器带宽限制，`Genarrative-Stdb-Module-Publish` 默认使用 `DATABASE_BACKUP_MODE=async`：先在 publish 前用 `--defer-upload` 生成本地冷备份和 `.manifest.json`，随后继续执行 publish；发布脚本退出前会用独立 `systemd-run` transient service 执行 `--upload-deferred-dir <backup-dir>`，串行补传该目录内同库的 `deferred/pending` 归档，不依赖 Jenkins 作业进程树存活。任一归档只有在 OSS archive、manifest 和 baseline state 全部上传并验真后，才按 `keep-local` 规则删除；失败归档保留原 manifest，由下次 publish 重试。`Genarrative-Full-Build-And-Deploy` 必须显式暴露并透传同一个 `DATABASE_BACKUP_MODE`，不得静默使用下游 `async`；release 已有验真冷备且明确禁止再上传时，Full 必须选择 `skip`。发布脚本在校验 wasm 后、执行 `spacetime publish` 前会等待显式 `SPACETIME_SERVER_URL` 的 `/v1/ping` 就绪，默认最多等待 `60` 秒；如生产机器冷备份恢复 `spacetimedb.service` 较慢，可临时设置 `GENARRATIVE_STDB_PUBLISH_READY_TIMEOUT_SECONDS` 调整等待时间。需要强一致发布闸门时改用 `DATABASE_BACKUP_MODE=sync`（等价脚本参数 `--backup-mode sync`），备份会在 publish 前同步打包并上传，失败会阻断 publish；确认已有其他备份窗口时才使用 `DATABASE_BACKUP_MODE=skip`（兼容脚本参数 `--skip-backup`）。若业务不能接受停机窗口，应先规划 SpacetimeDB 原生快照或主备策略，不要直接在写入中的数据目录上做热拷贝并当作强一致备份。
+脚本会将数据目录打包成 `tar.gz`，上传到 `oss://<bucket>/<prefix>/<database>/<database>-<UTC时间>.tar.gz`。备份使用同库进程锁：仍存活的备份进程会阻断并发执行；持有锁的进程已退出时，脚本会自动清理失效锁并重试获取，不需要人工删除锁文件。生产建议做冷备份：传入 `--stop-service spacetimedb.service`，脚本会在打包前停止服务、打包后恢复服务，再上传 OSS；因 `genarrative-api.service`、`genarrative-external-generation-worker@*.service` 和 `genarrative-external-generation-controller.service` 都依赖 `spacetimedb.service`，生产定时冷备份还必须传入对应的 `--restart-service-after`，确保备份后 API、保底 worker 和 controller 随数据库一起恢复。`2026-06-10` release 故障就是现场 unit 漏掉 API 重启参数，`03:20` 冷备份停止 SpacetimeDB 后 API 被依赖关系一并停止，备份脚本只恢复了 SpacetimeDB，API 直到人工重启前都不可用；`2026-06-24` release 又出现同类依赖停机后只恢复 API、未恢复外部生成 worker/controller，导致图片画布生成任务长期停留在队列中。后续现场变更、provision 模板和 Jenkins 归档都必须通过 `npm run check:production-ops` 防止回退。由于 OSS 上传可能受服务器带宽限制，`Genarrative-Stdb-Module-Publish` 默认使用 `DATABASE_BACKUP_MODE=async`：先在 publish 前用 `--defer-upload` 生成本地冷备份和 `.manifest.json`，随后继续执行 publish；发布脚本退出前会用独立 `systemd-run` transient service 执行 `--upload-deferred-dir <backup-dir>`，串行补传该目录内同库的 `deferred/pending` 归档，不依赖 Jenkins 作业进程树存活。任一归档只有在 OSS archive、manifest 和 baseline state 全部上传并验真后，才按 `keep-local` 规则删除；失败归档保留原 manifest，由下次 publish 重试。`Genarrative-Full-Build-And-Deploy` 必须显式暴露并透传同一个 `DATABASE_BACKUP_MODE`，不得静默使用下游 `async`；release 已有验真冷备且明确禁止再上传时，Full 必须选择 `skip`。发布脚本在校验 wasm 后、执行 `spacetime publish` 前会等待显式 `SPACETIME_SERVER_URL` 的 `/v1/ping` 就绪，默认最多等待 `60` 秒；如生产机器冷备份恢复 `spacetimedb.service` 较慢，可临时设置 `GENARRATIVE_STDB_PUBLISH_READY_TIMEOUT_SECONDS` 调整等待时间。需要强一致发布闸门时改用 `DATABASE_BACKUP_MODE=sync`（等价脚本参数 `--backup-mode sync`），备份会在 publish 前同步打包并上传，失败会阻断 publish；确认已有其他备份窗口时才使用 `DATABASE_BACKUP_MODE=skip`（兼容脚本参数 `--skip-backup`）。若业务不能接受停机窗口，应先规划 SpacetimeDB 原生快照或主备策略，不要直接在写入中的数据目录上做热拷贝并当作强一致备份。 `2026-09-21` 又命中一次同类事故：release 冷备按 `archive` 口径要求 `data × 1.1`（40.6GiB → 44.7GiB），生产根盘只剩 13.5GiB，备份在停服后才失败，生产被留在维护态。现在 `production-stdb-publish.sh` 在进入维护模式与停服务之前先执行 `database-backup-to-oss.mjs --check-space-only`：archive 口径为 `max(data × 1.1, data + 512MiB)`，files 口径为 `max(data × 0.05, 2GiB)`，空间不足以退出码 `3` 返回。archive 空间不足且未显式设置 `GENARRATIVE_STDB_PUBLISH_AUTO_FILES_FALLBACK=0` 时，脚本自动降级为 `--storage-format files`（不落地本地归档；files 不支持 `--defer-upload`，因此 `DATABASE_BACKUP_MODE=async` 会收敛为 `sync`，窗口内直传 OSS）；也可用 `GENARRATIVE_STDB_PUBLISH_BACKUP_STORAGE_FORMAT=files` 直接指定。任何「尚未开始 `spacetime publish`」的失败（空间预检、备份执行等）都会自动把本次停掉的 API/controller/worker 拉回并退出维护，只有真正开始发布之后的失败才保持维护态等待人工；该自动恢复可用 `GENARRATIVE_STDB_PUBLISH_AUTO_RECOVER_ON_PREPUBLISH_FAILURE=0` 关闭。定时备份的失效锁：当前仓库版本在持有者进程退出后会自动清理并重试，而生产机 `/var/lib/genarrative/backup-tools/database-backup-to-oss.mjs` 若仍是旧版（2026-07-16 前）会拒绝抢锁并需要人工删锁，必须随 provision 一起更新。 上游确认（[#5542](https://github.com/clockworklabs/SpacetimeDB/issues/5542) / [#5555](https://github.com/clockworklabs/SpacetimeDB/pull/5555)）只保留最近 `retain-snapshots`（默认 2）份 snapshot 与覆盖它之后的 commitlog 段就足以重启数据库，更早的 snapshot/commitlog 属于可丢弃历史；因此备份不再需要"保留每一版 + 计算增量"，改为 `database-backup-to-oss.mjs --storage-format files --mode full --minimal --retain-snapshots 2`：每个 replica 取最近 2 份 snapshot、覆盖最老保留 snapshot 的 commitlog 边界段及其后全部段，外加身份/`data/config.toml`/`data/metadata.toml`/`data/control-db`/`data/program-bytes`，其余历史不备份。实测 release `replicas/2` 为 55 个 snapshot(18G)+108 个 clog 文件(22G)，minimal 口径只需约 3.6GiB（16 个候选），因此定时任务与发布前备份都可以在**不停服**的前提下完成，也不再需要 44.7GiB 的冷备空间；Server-Provision 新增 `DATABASE_BACKUP_PROFILE=files-minimal`（release 推荐，`files-history` 继续禁止），发布前备份默认走 minimal（`GENARRATIVE_STDB_PUBLISH_BACKUP_MINIMAL=0` 可回到冷备）。本地磁盘上的历史数据仍由 SpacetimeDB 自己保留（PR #5555 尚未合并），升级到含该特性的版本后可配置 `[retention] policy = "delete"` 回收。
 
 生产环境变量模板在 `deploy/env/api-server.env.example`：
 
@@ -728,19 +728,19 @@ Pingora current release 自审脚本 `scripts/ops/pingora-current-release-audit.
 
 ### AGC macOS 手动构建节点
 
-Mac universal 构建脚本位于 `jenkins/Jenkinsfile.ai-game-creator-shell-macos-build`，只对专用 `genarrative-agc-macos` 标签运行。节点按 EXCLUSIVE、单 executor 配置，Job 禁止并发且不设置 trigger；不接入现有每小时版本调度，不改 Windows 发布职责。它使它只在专用 Agent 目录下构建：默认按约定匹配 `$HOME/Library/Jenkins/agents/<node>/workspace/`（不写死节点名，节点改名后仍成立），也可用 `AGC_AGENT_ROOT` 显式覆盖；禁止指向开发 checkout 或共享其可写 target/node_modules。
+Mac 单架构（arm64）构建脚本位于 `jenkins/Jenkinsfile.ai-game-creator-shell-macos-build`，只对专用 `genarrative-agc-macos` 标签运行。节点按 EXCLUSIVE、单 executor 配置，Job 禁止并发且不设置 trigger；不接入现有每小时版本调度，不改 Windows 发布职责。它使它只在专用 Agent 目录下构建：默认按约定匹配 `$HOME/Library/Jenkins/agents/<node>/workspace/`（不写死节点名，节点改名后仍成立），也可用 `AGC_AGENT_ROOT` 显式覆盖；禁止指向开发 checkout 或共享其可写 target/node_modules。
 
 Job 名为 `Genarrative-Agc-MacOS-Build`，SCM 直接读取仓库内上述 Jenkinsfile，参数为 `SOURCE_BRANCH`、`COMMIT_HASH`、`AGC_UPDATE_CHANNEL`、`AGC_RELEASE_VERSION`、`AGC_RELEASE_DRY_RUN`、`AGC_UPDATE_RELEASE_NOTES`、`OSSUTIL_BIN`、`CARGO_BUILD_JOBS`。渠道参数是基础名（不含系统，默认 `dev`），脚本不接受 `dev-mac` 这类系统后缀，写入分区固定推导为 `<channel>-mac`：这与 Windows Job 的 `<channel>-win` 对称，也延续已发布客户端的端点。
 
-该 Job 的职责是构建并发布 `<channel>-mac` 分区更新：执行 `npm ci` 后使用锁文件校验并补齐两种 macOS Codex 原生依赖，再调用 `scripts/build-macos-ci.mjs`（AGC 应用目录下）生成 universal app、arm64/x86_64 隔离 smoke、universal DMG 与分区清单 `latest.json`，用产物内烘焙的公钥复核更新包签名（`verify-updater-signature.mjs`），最后按 `AGC_RELEASE_DRY_RUN` 决定是否上传 OSS。签到会同时取 `master`，让渠道清单里上一次发布的 commit 可解析——缺了它更新摘要会退化成「最近客户端改动」（该步失败只降级摘要，不阻断发布）。产物名（`*.app`、updater 归档、DMG、卷名）一律从 Tauri `productName` 推导，校验脚本从包内 `Info.plist` 读取可执行名，改产品名不会让入口静默找错对象；隔离 smoke 用 `ditto --clone` 复制副本（实测整轮 6.8 秒，此前整包复制约 1 分钟），并在构建前删除本次将写出的 DMG/更新包/签名，保证归档产物一定来自本次构建。归档限 `artifacts/` 下的 DMG、SHA-256、`latest.json`、更新包签名、更新摘要、非敏感构建清单和源码 commit；不归档用户 HOME、Jenkins secret、原始工作目录或全量日志。
+该 Job 的职责是构建并发布 `<channel>-mac` 分区更新：执行 `npm ci` 后使用锁文件校验并补齐两种 macOS Codex 原生依赖，再调用 `scripts/build-macos-ci.mjs`（AGC 应用目录下）生成 arm64 单架构 app、arm64 隔离 smoke、arm64 DMG（`<产品名>_<版本>_aarch64.dmg`）与分区清单 `latest.json`，用产物内烘焙的公钥复核更新包签名（`verify-updater-signature.mjs`），最后按 `AGC_RELEASE_DRY_RUN` 决定是否上传 OSS。签到会同时取 `master`，让渠道清单里上一次发布的 commit 可解析——缺了它更新摘要会退化成「最近客户端改动」（该步失败只降级摘要，不阻断发布）。产物名（`*.app`、updater 归档、DMG、卷名）一律从 Tauri `productName` 推导，校验脚本从包内 `Info.plist` 读取可执行名，改产品名不会让入口静默找错对象；隔离 smoke 用 `ditto --clone` 复制副本（实测整轮 6.8 秒，此前整包复制约 1 分钟），并在构建前删除本次将写出的 DMG/更新包/签名，保证归档产物一定来自本次构建。归档限 `artifacts/` 下的 DMG、SHA-256、`latest.json`、更新包签名、更新摘要、非敏感构建清单和源码 commit；不归档用户 HOME、Jenkins secret、原始工作目录或全量日志。
 
 发布凭据全部走 Jenkins 全局凭据，并在 `withCredentials` 内注入当前进程：`AgcUpdaterSigningKey`（与 `AgcUpdaterSigningKeyPassword`）映射为 `TAURI_SIGNING_PRIVATE_KEY` / `TAURI_SIGNING_PRIVATE_KEY_PASSWORD`，`AliyunAccessKeyId` / `AliyunaccessKeySecret` 映射为 `AGC_OSS_ACCESS_KEY_ID` / `AGC_OSS_ACCESS_KEY_SECRET`；私钥与凭据不写入 workspace、日志或归档产物。上传顺序为更新包、签名、首装包，三者全部成功后才覆盖 `agc/<channel>-mac/latest.json` 指针；`AGC_RELEASE_DRY_RUN` 与 Windows 渠道对称：默认关闭即真发布，勾选后才退化为演练（只打印将上传的对象、不写任何 OSS 对象）。本 Job 是正式发布入口，调度器在发号后与 Windows 一起触发它，并额外传 `SKIP_IF_SUPERSEDED=true`——Mac 节点是日常办公机，离线期间排队的旧构建在节点回来后若已被源码分支推进，直接跳过而不发布过期版本。Mac 节点需要 `ossutil`（实测 1.7.19 原生 arm64 可用，装在 `~/.local/bin`，已在 Job 的 PATH 内），可用 `OSSUTIL_BIN` 指定命令名或绝对路径。首次发布建议显式指定 `AGC_RELEASE_VERSION`，避免按渠道高水位递增时出现版本链回退。
 
 产物边界：macOS 代码签名与公证暂缺，构建通过剥离 `APPLE_*` 凭据让 Tauri 跳过 Apple 签名，**不得使用 `--no-sign`**——该标志会连带跳过 updater 的 minisign 签名，产物缺少 `.sig` 会直接卡在验签门禁（首次实跑即命中该坑）。构建清单按 `codesign -dv` 实测记录 `appleSigned` / `appleSignatureKind`（如 `adhoc`），并固定记录 `notarized=false`。用户首次安装需要在 Gatekeeper 中手动放行；更新包校验本身只依赖 minisign 签名，因此未签名不阻断自动更新的校验环节，但「安装 → 重启接管新版本」的实机闭环仍未验证，不得以构建成功替代。
 
-Job 描述与节点描述是 Jenkins 侧元数据，**不随仓库同步**：Jenkinsfile 只回写参数定义，描述必须手工维护，否则会停留在建 Job 时的口径（2026-09-20 就出现过描述还写着「只构建归档、不签名不上传」，而实际已经是含签名、分区清单、验签与 OSS 上传的发布管线）。当前口径：Job 描述说明「构建 universal → 双架构 smoke → DMG → `<channel>-mac` 分区清单 → 更新包验签 → 按 dry-run 决定上传，未做 Apple 签名与公证」；节点描述说明「`genarrative-agc-macos`、EXCLUSIVE 单 executor、仅手动触发、独立 workspace、sccache 在 HOME」。维护手法：该 Job 上 `POST job/<name>/config.xml` 会返回 500，节点侧同接口正常；因此改 Job 描述用脚本接口原地更新（保留构建历史），不要为了改描述删 Job 重建。
+Job 描述与节点描述是 Jenkins 侧元数据，**不随仓库同步**：Jenkinsfile 只回写参数定义，描述必须手工维护，否则会停留在建 Job 时的口径（2026-09-20 就出现过描述还写着「只构建归档、不签名不上传」，而实际已经是含签名、分区清单、验签与 OSS 上传的发布管线）。当前口径：Job 描述说明「构建 arm64 单架构 → arm64 smoke → DMG → `<channel>-mac` 分区清单（只登记 `darwin-aarch64`）→ 更新包验签 → 按 dry-run 决定上传，未做 Apple 签名与公证」；节点描述说明「`genarrative-agc-macos`、EXCLUSIVE 单 executor、仅手动触发、独立 workspace、sccache 在 HOME」。维护手法：该 Job 上 `POST job/<name>/config.xml` 会返回 500，节点侧同接口正常；因此改 Job 描述用脚本接口原地更新（保留构建历史），不要为了改描述删 Job 重建。
 
-该 Job 的 Rust 编译走 sccache 对象缓存，与 `Genarrative-Api-Build`、`Genarrative-Stdb-Module-Build` 一致：`RUSTC_WRAPPER=sccache`、`CARGO_INCREMENTAL=0`、`SCCACHE_CACHE_SIZE=20G`。`SCCACHE_DIR` 默认落在稳定缓存根 `~/caches/genarrative-jenkins/agc-macos/sccache`，可用 `GENARRATIVE_AGC_MACOS_CACHE_ROOT` 覆盖；缓存根固定在 HOME 下而不是 `WORKSPACE` 内，避免 workspace 重建后无改动也触发近似冷构建。节点是 8 逻辑核（4P+4E）的共用机器，`CARGO_BUILD_JOBS` 因此做成 Job 参数（默认 `8`，吃满节点）。该值不只是并行 crate 数——cargo 会把它作为 jobserver 令牌上限传给 rustc，主 crate 的 codegen 也受它限制，因此写小会直接拖长整条构建；节点只有 24 GB 内存且是日常办公机，若构建期间出现明显换页再临时调低。首次构建 sccache 必然全未命中（实测 0 命中 / 407 未命中），此后的构建才逐步吃到缓存。节点未安装 sccache 时管线打印提示并回退到真实 `rustc`，不阻断构建。universal 双架构各自独立编译，依赖 crate 的复用收益约为单架构的两倍；命中情况由构建末尾的 `sccache --show-stats` 输出，供判断是否需要预热或调整缓存上限。
+该 Job 的 Rust 编译走 sccache 对象缓存，与 `Genarrative-Api-Build`、`Genarrative-Stdb-Module-Build` 一致：`RUSTC_WRAPPER=sccache`、`CARGO_INCREMENTAL=0`、`SCCACHE_CACHE_SIZE=20G`。`SCCACHE_DIR` 默认落在稳定缓存根 `~/caches/genarrative-jenkins/agc-macos/sccache`，可用 `GENARRATIVE_AGC_MACOS_CACHE_ROOT` 覆盖；缓存根固定在 HOME 下而不是 `WORKSPACE` 内，避免 workspace 重建后无改动也触发近似冷构建。节点是 8 逻辑核（4P+4E）的共用机器，`CARGO_BUILD_JOBS` 因此做成 Job 参数（默认 `8`，吃满节点）。该值不只是并行 crate 数——cargo 会把它作为 jobserver 令牌上限传给 rustc，主 crate 的 codegen 也受它限制，因此写小会直接拖长整条构建；节点只有 24 GB 内存且是日常办公机，若构建期间出现明显换页再临时调低。首次构建 sccache 必然全未命中（实测 0 命中 / 407 未命中），此后的构建才逐步吃到缓存。节点未安装 sccache 时管线打印提示并回退到真实 `rustc`，不阻断构建。单架构发布后依赖 crate 的复用更彻底（此前每次要编 aarch64 与 x86_64 两遍）；命中情况由构建末尾的 `sccache --show-stats` 输出，供判断是否需要预热或调整缓存上限。工作区 `target/` 目录跨构建保留（Checkout 只跑 `git clean -fd`，不动 ignored 目录），因此仓库内 path 依赖之外的 crate 只编一次。
 
 首次端到端验证（2026-09-20，build #3）：`SUCCESS`，43 分钟。产出 `陶泥儿_0.1.68_universal.dmg`、`陶泥儿.app.tar.gz` 与 `.sig`、`latest.json`、`build-manifest.json`；两个架构的隔离 smoke（arm64 / Rosetta x86_64）通过，更新包用产物内烘焙公钥复核通过（`alg=ED`，`keyId=cb883447e3e87c4e`），dry-run 只打印 4 个上传对象、未写 OSS。构建清单实测记录 `appleSigned=false`、`appleSignatureKind=adhoc`、`notarized=false`。首次实跑暴露并修掉两个入口缺陷：传 `--no-sign` 会连带跳过 updater 的 minisign 签名（产物无 `.sig`），以及复用 workspace 里残留的同名 DMG 让 `hdiutil create` 直接失败、残留旧 `.sig` 还可能让验签误通过——入口现在会在构建前删除本次将写出的确切产物并要求 `hdiutil -ov`。
 
diff --git a/jenkins/Jenkinsfile.ai-game-creator-shell-macos-build b/jenkins/Jenkinsfile.ai-game-creator-shell-macos-build
index 91bcfdc97..6e57007b8 100644
--- a/jenkins/Jenkinsfile.ai-game-creator-shell-macos-build
+++ b/jenkins/Jenkinsfile.ai-game-creator-shell-macos-build
@@ -10,7 +10,7 @@ pipeline {
     timestamps()
   }
   parameters {
-    string(name: 'SOURCE_BRANCH', defaultValue: 'master', description: '必须含 universal 双架构依赖实现的受信任分支')
+    string(name: 'SOURCE_BRANCH', defaultValue: 'master', description: '必须含 macOS 单架构（arm64）发布实现的受信任分支')
     string(name: 'COMMIT_HASH', defaultValue: '', description: '可选，固定属于源码分支的提交；不递增应用版本')
     string(name: 'AGC_UPDATE_CHANNEL', defaultValue: 'dev', description: 'AGC 发布渠道（基础名，不含系统）：dev、release 或自定义小写名称；写入的分区固定为 <channel>-mac')
     string(name: 'AGC_RELEASE_VERSION', defaultValue: '', description: '可选三段版本号；留空则按 <channel>-mac 分区清单高水位递增 patch。首次发布建议显式指定，避免版本链回退')
@@ -26,7 +26,7 @@ pipeline {
     AGC_OSS_BUCKET = 'agc-dev'
     AGC_OSS_ENDPOINT = 'oss-rg-china-mainland.aliyuncs.com'
     // 与 Linux 生产管线（api-build / stdb-module-build）对齐：Rust 编译走 sccache 对象缓存。
-    // 本 Job 是 universal 双架构（aarch64 + x86_64）各自独立编译，缓存收益约为单架构的两倍。
+    // 本 Job 只编译 aarch64-apple-darwin 单架构（Intel 未支持）：sccache 与工作区 target 目录跨构建复用。
     // 缓存根固定在 HOME 下的稳定目录，避免 WORKSPACE 重建导致近似冷构建；可用下面的变量覆盖。
     GENARRATIVE_AGC_MACOS_CACHE_ROOT = 'caches/genarrative-jenkins/agc-macos'
     RUSTC_WRAPPER = 'sccache'
@@ -143,7 +143,7 @@ pipeline {
             sh '''
             set -eu
             export PATH="$HOME/.local/bin:$HOME/.cargo/bin:${AGC_EXTRA_PATH}"
-            echo "[agc-macos] 渠道=${AGC_UPDATE_CHANNEL} 分区=${AGC_UPDATE_CHANNEL}-mac 目标=universal-apple-darwin dry-run=${AGC_RELEASE_DRY_RUN}"
+            echo "[agc-macos] 渠道=${AGC_UPDATE_CHANNEL} 分区=${AGC_UPDATE_CHANNEL}-mac 目标=aarch64-apple-darwin（单架构，Intel 未支持）dry-run=${AGC_RELEASE_DRY_RUN}"
               ossutil_bin="${OSSUTIL_BIN:-ossutil}"
               if command -v "${ossutil_bin}" >/dev/null 2>&1; then
                 "${ossutil_bin}" --version | head -1
@@ -194,8 +194,8 @@ pipeline {
     }
     success {
       echo params.AGC_RELEASE_DRY_RUN
-        ? 'macOS universal 渠道演练完成：已构建、验签并生成清单，未写入 OSS；Apple 签名与公证暂缺。'
-        : "macOS universal 更新包、签名、首装包与 ${params.AGC_UPDATE_CHANNEL}-mac 分区清单已上传 OSS；Apple 签名与公证暂缺，首装需手动放行。"
+        ? 'macOS arm64 渠道演练完成：已构建、验签并生成清单，未写入 OSS；Apple 签名与公证暂缺。'
+        : "macOS arm64 更新包、签名、首装包与 ${params.AGC_UPDATE_CHANNEL}-mac 分区清单已上传 OSS（清单只登记 darwin-aarch64）；Apple 签名与公证暂缺，首装需手动放行。"
     }
   }
 }
diff --git a/jenkins/Jenkinsfile.production-server-provision b/jenkins/Jenkinsfile.production-server-provision
index d2104e68c..28a940332 100644
--- a/jenkins/Jenkinsfile.production-server-provision
+++ b/jenkins/Jenkinsfile.production-server-provision
@@ -34,7 +34,7 @@ pipeline {
     string(name: 'WEB_LINK', defaultValue: '/srv/genarrative/web', description: 'Nginx 静态站点目录或软链接')
     string(name: 'API_ENV_FILE', defaultValue: '/etc/genarrative/api-server.env', description: 'api-server 环境文件')
     string(name: 'API_PORT', defaultValue: '8082', description: 'api-server 本机监听端口')
-    choice(name: 'DATABASE_BACKUP_PROFILE', choices: ['archive-full', 'files-history'], description: '数据库定时备份 profile；release 仅允许 archive-full，files-history 仅供 development 在指定 work-dir 已有完整 full baseline 后启用')
+    choice(name: 'DATABASE_BACKUP_PROFILE', choices: ['archive-full', 'files-minimal', 'files-history'], description: '数据库定时备份 profile；release 用 files-minimal（最近 snapshot + 其后 commitlog 的热备）或 archive-full，files-history 因内存峰值仅 development 使用')
     string(name: 'DATABASE_BACKUP_FILES_HISTORY_WORK_DIR', defaultValue: '/var/lib/genarrative/database-backups/files-history', description: 'development files-history 的本地 state/catalog 目录；必须使用已建立 full baseline 的独立目录')
     choice(name: 'NGINX_CONFIG_MODE', choices: ['none', 'production-https', 'development-http'], description: 'Nginx 配置模式；开发服无域名时选 development-http，release 正式入口选 production-https')
     booleanParam(name: 'ENABLE_SERVICES', defaultValue: true, description: '启用并启动 spacetimedb 与 api-server systemd 服务')
@@ -110,11 +110,11 @@ pipeline {
             error('release 目标禁止安装 development-http Nginx 配置；无证书初始化请使用 NGINX_CONFIG_MODE=none。')
           }
           def databaseBackupProfile = params.DATABASE_BACKUP_PROFILE?.trim()
-          if (!(databaseBackupProfile in ['archive-full', 'files-history'])) {
-            error("DATABASE_BACKUP_PROFILE 只能是 archive-full 或 files-history，当前值: ${params.DATABASE_BACKUP_PROFILE}")
+          if (!(databaseBackupProfile in ['archive-full', 'files-minimal', 'files-history'])) {
+            error("DATABASE_BACKUP_PROFILE 只能是 archive-full、files-minimal 或 files-history，当前值: ${params.DATABASE_BACKUP_PROFILE}")
           }
           if (params.DEPLOY_TARGET == 'release' && databaseBackupProfile == 'files-history') {
-            error('release 仅允许 archive-full；files-history 会把整棵历史目录加载到 Node 内存，需先完成流式 catalog 改造后才能重新启用。')
+            error('release 不允许 files-history；files-history 会把整棵历史目录加载到 Node 内存。release 请选择 files-minimal（最近 snapshot + 其后 commitlog）或 archive-full。')
           }
           def databaseBackupFilesHistoryWorkDir = params.DATABASE_BACKUP_FILES_HISTORY_WORK_DIR?.trim()
           if (!(databaseBackupFilesHistoryWorkDir ==~ /^\/var\/lib\/genarrative\/database-backups\/[A-Za-z0-9._\/-]+$/) || databaseBackupFilesHistoryWorkDir.contains('..')) {
diff --git a/scripts/check-database-backup-to-oss.mjs b/scripts/check-database-backup-to-oss.mjs
index 44060f394..049d7d851 100644
--- a/scripts/check-database-backup-to-oss.mjs
+++ b/scripts/check-database-backup-to-oss.mjs
@@ -26,8 +26,10 @@ import {
   cleanupHistoryCandidates,
   collectDirectFileEntries,
   createUploadBandwidthLimiter,
+  describeBackupSpaceRequirement,
   discoverDeferredArchiveUploads,
   discoverHistoryPlan,
+  discoverMinimalPlan,
   restoreDirectFilesBackup,
   restoreDirectFilesLatest,
   resumeUploadedHistoryBatch,
@@ -64,6 +66,8 @@ async function main() {
   assertDeferredArchiveDiscoveryIsBoundedAndDeterministic();
   assertCanonicalQueryAndAuthorizationIncludeMultipartParameters();
   assertInsufficientSpaceStopsBeforeServiceChanges();
+  assertCheckSpaceOnlyUsesFormatSpecificRequirement();
+  assertMinimalPlanKeepsOnlyRetainedSnapshotAndTrailingCommitlog();
   assertStopFailureRetainsRecoveryMarker();
   assertArchiveFailureStillRestoresDependentServices();
   await assertMultipartUploadRetriesAndVerifiesRemoteLength();
@@ -1198,7 +1202,7 @@ function assertInsufficientSpaceStopsBeforeServiceChanges() {
     '999999999999999999',
   ]);
 
-  assertStatus(result, 1, '空间不足时必须失败。');
+  assertStatus(result, 3, '空间不足必须用独立退出码 3 失败。');
   assertIncludes(
     result.stdout,
     '备份空间预检',
@@ -1213,6 +1217,66 @@ function assertInsufficientSpaceStopsBeforeServiceChanges() {
   assertFileMissing(fixture.tarLog, '空间不足时不能调用 tar。');
 }
 
+function assertCheckSpaceOnlyUsesFormatSpecificRequirement() {
+  const fixture = createFixture('check-space-only');
+
+  const filesOk = runBackup(
+    fixture,
+    ['--check-space-only', '--storage-format', 'files'],
+    { GENARRATIVE_DATABASE_BACKUP_FILES_MIN_FREE_BYTES: '1M' },
+  );
+  assertStatus(filesOk, 0, 'files 模式空间预检应在阈值满足时通过。');
+  assertIncludes(
+    filesOk.stdout,
+    '备份空间预检(files)',
+    'files 预检必须打印 files 口径的预检结果。',
+  );
+  assertIncludes(
+    filesOk.stdout,
+    '空间预检通过(check-space-only)',
+    'check-space-only 通过时必须给出显式成功标记。',
+  );
+  assertFileMissing(fixture.systemctlLog, '空间预检不得调用 systemctl。');
+  assertFileMissing(fixture.tarLog, '空间预检不得调用 tar。');
+
+  const filesInsufficient = runBackup(
+    fixture,
+    ['--check-space-only', '--storage-format', 'files'],
+    { GENARRATIVE_DATABASE_BACKUP_FILES_MIN_FREE_BYTES: '1000T' },
+  );
+  assertStatus(filesInsufficient, 3, 'files 空间不足同样使用退出码 3。');
+
+  const archiveInsufficient = runBackup(
+    fixture,
+    ['--check-space-only', '--storage-format', 'archive'],
+    { GENARRATIVE_DATABASE_BACKUP_MIN_FREE_BYTES: '1000T' },
+  );
+  assertStatus(archiveInsufficient, 3, 'archive 空间不足必须使用退出码 3。');
+
+  const archive = describeBackupSpaceRequirement({
+    dataDir: fixture.dataDir,
+    workDir: fixture.workDir,
+    storageFormat: 'archive',
+    args: {},
+    env: { GENARRATIVE_DATABASE_BACKUP_MIN_FREE_BYTES: '1G' },
+  });
+  const files = describeBackupSpaceRequirement({
+    dataDir: fixture.dataDir,
+    workDir: fixture.workDir,
+    storageFormat: 'files',
+    args: {},
+    env: { GENARRATIVE_DATABASE_BACKUP_FILES_MIN_FREE_BYTES: '1G' },
+  });
+  if (archive.requiredFreeBytes !== 1024n ** 3n || files.requiredFreeBytes !== 1024n ** 3n) {
+    failures.push(
+      `空间口径覆盖参数应生效：archive=${archive.requiredFreeBytes} files=${files.requiredFreeBytes}`,
+    );
+  }
+  if (archive.storageFormat !== 'archive' || files.storageFormat !== 'files') {
+    failures.push('空间预检结果必须回显实际 storage-format。');
+  }
+}
+
 function assertStopFailureRetainsRecoveryMarker() {
   const fixture = createFixture('stop-failure-marker');
   writeExecutable(
@@ -2500,6 +2564,106 @@ async function assertHistoryResumeReverifiesArchiveAndManifest() {
   }
 }
 
+function assertMinimalPlanKeepsOnlyRetainedSnapshotAndTrailingCommitlog() {
+  const fixture = createHistoryFixture('minimal-plan', { nestedData: true });
+  const replicaDir = path.join(fixture.replicasDir, '2');
+  const snapshotsDir = path.join(replicaDir, 'snapshots');
+  const clogDir = path.join(replicaDir, 'clog');
+  mkdirSync(snapshotsDir, { recursive: true });
+  mkdirSync(clogDir, { recursive: true });
+  for (const transaction of ['100', '200', '300']) {
+    const padded = transaction.padStart(20, '0');
+    const snapshotDir = path.join(snapshotsDir, `${padded}.snapshot_dir`);
+    mkdirSync(snapshotDir, { recursive: true });
+    writeFileSync(
+      path.join(snapshotDir, `${padded}.snapshot_bsatn`),
+      'snapshot',
+    );
+  }
+  for (const transaction of ['50', '150', '250', '350']) {
+    const padded = transaction.padStart(20, '0');
+    writeFileSync(path.join(clogDir, `${padded}.stdb.log`), 'log');
+    writeFileSync(path.join(clogDir, `${padded}.stdb.ofs`), 'ofs');
+  }
+  for (const relativeDir of ['config', 'data/control-db', 'data/program-bytes']) {
+    const directory = path.join(fixture.dataDir, relativeDir);
+    mkdirSync(directory, { recursive: true });
+    writeFileSync(path.join(directory, 'state.bin'), 'state');
+  }
+  writeFileSync(path.join(fixture.dataDir, 'data/config.toml'), 'config');
+  writeFileSync(path.join(fixture.dataDir, 'data/metadata.toml'), 'metadata');
+
+  const plan = discoverMinimalPlan({ dataDir: fixture.dataDir });
+  const paths = plan.candidates.map((item) => item.path);
+  const expect = (condition, reason) => {
+    if (!condition) {
+      failures.push(reason);
+    }
+  };
+
+  expect(
+    plan.retainSnapshots === 2,
+    `minimal 默认应保留 2 份 snapshot，实际 ${plan.retainSnapshots}`,
+  );
+  expect(
+    paths.includes(
+      'data/replicas/2/snapshots/00000000000000000200.snapshot_dir',
+    ),
+    'minimal 必须保留次新 snapshot。',
+  );
+  expect(
+    paths.includes(
+      'data/replicas/2/snapshots/00000000000000000300.snapshot_dir',
+    ),
+    'minimal 必须保留最新 snapshot。',
+  );
+  expect(
+    !paths.includes(
+      'data/replicas/2/snapshots/00000000000000000100.snapshot_dir',
+    ),
+    'minimal 不得备份更早的 snapshot。',
+  );
+  expect(
+    paths.includes('data/replicas/2/clog/00000000000000000150.stdb.log'),
+    'minimal 必须保留覆盖最老保留 snapshot 的边界 commitlog 段。',
+  );
+  expect(
+    paths.includes('data/replicas/2/clog/00000000000000000350.stdb.log'),
+    'minimal 必须保留最新 commitlog 段。',
+  );
+  expect(
+    !paths.includes('data/replicas/2/clog/00000000000000000050.stdb.log'),
+    'minimal 不得备份更早的 commitlog 段。',
+  );
+  for (const staticPath of [
+    'config',
+    'data/config.toml',
+    'data/metadata.toml',
+    'data/control-db',
+    'data/program-bytes',
+  ]) {
+    expect(
+      paths.includes(staticPath),
+      `minimal 必须保留状态路径 ${staticPath}。`,
+    );
+  }
+  const replica = plan.replicas.find((item) => item.replicaId === '2');
+  expect(
+    replica?.retainedSnapshots === 2 && replica?.droppedSnapshots === 1,
+    'minimal 必须报告保留/丢弃的 snapshot 数量。',
+  );
+  expect(
+    replica?.droppedSegments === 1,
+    `minimal 必须报告丢弃的 commitlog 段数量，实际 ${replica?.droppedSegments}`,
+  );
+
+  assertThrows(
+    () => discoverMinimalPlan({ dataDir: fixture.dataDir, retainSnapshots: 0 }),
+    '--retain-snapshots 必须是 >= 1 的整数',
+    'minimal 必须校验保留 snapshot 数量。',
+  );
+}
+
 function createHistoryFixture(name, { nestedData }) {
   const root = path.join(tmpRoot, name);
   const dataDir = path.join(root, 'stdb');
@@ -2695,7 +2859,7 @@ exit 2
   return { root, binDir, dataDir, workDir, systemctlLog, tarLog };
 }
 
-function runBackup(fixture, extraArgs = []) {
+function runBackup(fixture, extraArgs = [], envOverrides = {}) {
   return spawnSync(
     process.execPath,
     [
@@ -2720,6 +2884,7 @@ function runBackup(fixture, extraArgs = []) {
       env: {
         ...process.env,
         PATH: `${fixture.binDir}${path.delimiter}${process.env.PATH ?? ''}`,
+        ...envOverrides,
       },
     },
   );
diff --git a/scripts/check-production-ops-guardrails.mjs b/scripts/check-production-ops-guardrails.mjs
index 323a17e6a..f6f2cf056 100644
--- a/scripts/check-production-ops-guardrails.mjs
+++ b/scripts/check-production-ops-guardrails.mjs
@@ -258,6 +258,50 @@ const checks = [
     reason:
       'Stdb 先于 API 发布时必须先补齐 api-server env 的 FILE 路径，保证首次 rollout 重启即可读取 secret。',
   },
+  {
+    file: 'scripts/deploy/production-stdb-publish.sh',
+    includes:
+      'precheck_backup_space_before_maintenance\n\n"${SCRIPT_DIR}/maintenance-on.sh" "spacetime module publish ${DATABASE}"',
+    reason:
+      '备份空间预检必须先于进入维护模式执行：磁盘不足时不得停服务或把生产留在维护态。',
+  },
+  {
+    file: 'scripts/deploy/production-stdb-publish.sh',
+    includes: '--check-space-only',
+    reason:
+      '生产 Stdb publish 必须复用备份脚本的 --check-space-only 预检，保证空间口径与真实备份一致。',
+  },
+  {
+    file: 'scripts/deploy/production-stdb-publish.sh',
+    includes: 'GENARRATIVE_STDB_PUBLISH_AUTO_FILES_FALLBACK',
+    reason:
+      'archive 冷备份空间不足时必须能自动降级为 files 存储格式（不落地本地归档）。',
+  },
+  {
+    file: 'scripts/deploy/production-stdb-publish.sh',
+    includes: 'timeout waiting for transaction confirmation',
+    reason:
+      'publish 客户端等确认超时不能直接判失败：必须重试同版本 publish 以确认模块是否已生效，避免把生产留在维护态。',
+  },
+  {
+    file: 'scripts/deploy/production-stdb-publish.sh',
+    includes: 'restore_runtime_services_before_publish',
+    reason:
+      '尚未开始 publish 的失败必须自动恢复运行时服务并退出维护，避免生产停在维护态等人工。',
+  },
+  {
+    file: 'scripts/deploy/production-stdb-publish.sh',
+    includes:
+      'if [[ "${PUBLISH_STARTED}" -ne 1 && "${AUTO_RECOVER_BEFORE_PUBLISH}" == "1" ]]; then',
+    reason:
+      '只有尚未开始 publish 的失败才允许自动恢复并退出维护，半发布状态必须保持维护。',
+  },
+  {
+    file: 'scripts/database-backup-to-oss.mjs',
+    includes: 'SPACE_INSUFFICIENT_EXIT_CODE',
+    reason:
+      '备份空间不足必须使用独立退出码，调用方据此决定降级存储格式而不是一律失败。',
+  },
   {
     file: 'scripts/deploy/production-stdb-publish.sh',
     includes: 'stop_runtime_services_for_rollout_gate',
@@ -900,7 +944,7 @@ const checks = [
   },
   {
     file: 'scripts/jenkins-server-provision.sh',
-    includes: 'archive-full|files-history)',
+    includes: 'archive-full|files-history|files-minimal)',
     reason: 'Server-Provision 必须拒绝未知数据库备份 profile。',
   },
   {
@@ -925,7 +969,7 @@ const checks = [
   {
     file: 'jenkins/Jenkinsfile.production-server-provision',
     includes:
-      "choice(name: 'DATABASE_BACKUP_PROFILE', choices: ['archive-full', 'files-history']",
+      "choice(name: 'DATABASE_BACKUP_PROFILE', choices: ['archive-full', 'files-minimal', 'files-history']",
     reason:
       'Server-Provision Job 必须显式暴露 archive-first 的数据库备份 profile。',
   },
@@ -978,13 +1022,32 @@ const checks = [
   },
   {
     file: 'jenkins/Jenkinsfile.production-server-provision',
-    includes: 'release 仅允许 archive-full；files-history',
+    includes: 'release 不允许 files-history',
     reason:
       'release 必须拒绝 files-history，避免逐文件 catalog 扫描再次触发生产内存峰值。',
   },
+  {
+    file: 'jenkins/Jenkinsfile.production-server-provision',
+    includes: 'files-minimal',
+    reason:
+      'release 定时备份必须提供 files-minimal profile：只备最近 snapshot 与其后 commitlog，热备不停服。',
+  },
+  {
+    file: 'deploy/systemd/genarrative-database-backup-files-minimal.conf',
+    includes: '--mode full --minimal --retain-snapshots 2 --freeze-dir',
+    reason:
+      'files-minimal 定时备份必须使用 minimal 口径并保留上游默认的最近 2 份 snapshot。',
+  },
+  {
+    file: 'scripts/deploy/production-stdb-publish.sh',
+    includes: '--freeze-dir',
+    reason:
+      '发布前备份默认使用 minimal 热备，避免 40G 级冷备空间门槛与停服。',
+  },
   {
     file: 'scripts/database-backup-to-oss.mjs',
-    includes: 'assertSufficientWorkDirSpace({dataDir, workDir, args, env})',
+    includes:
+      "assertSufficientWorkDirSpace({ dataDir, workDir, args, env, storageFormat: 'archive' })",
     normalizeWhitespace: true,
     reason: '生产冷备份必须先做工作目录剩余空间预检，避免停库后写满磁盘。',
   },
diff --git a/scripts/database-backup-to-oss.mjs b/scripts/database-backup-to-oss.mjs
index bc215509f..26d8cf232 100644
--- a/scripts/database-backup-to-oss.mjs
+++ b/scripts/database-backup-to-oss.mjs
@@ -55,6 +55,21 @@ const DEFAULT_DATABASE_BACKUP_STOP_MARKER = join(
 );
 const DEFAULT_SPACE_SAFETY_RATIO = 1.1;
 const DEFAULT_EXTRA_FREE_BYTES = 512 * 1024 * 1024;
+// files 模式不落地本地归档（只写 catalog/state），所需空间远小于数据目录本身。
+// minimal 备份保留的最近 snapshot 数（与上游 retention 默认值一致）。
+const DEFAULT_RETAIN_SNAPSHOTS = 2;
+// minimal 备份额外保留的小体积状态：身份、standalone 配置、控制库与模块字节。
+const MINIMAL_STATIC_PATHS = [
+  'config',
+  'data/config.toml',
+  'data/metadata.toml',
+  'data/control-db',
+  'data/program-bytes',
+];
+const DEFAULT_FILES_SPACE_SAFETY_RATIO = 0.05;
+const DEFAULT_FILES_EXTRA_FREE_BYTES = 2 * 1024 * 1024 * 1024;
+// 空间不足用独立退出码，调用方可据此决定是否降级存储格式。
+const SPACE_INSUFFICIENT_EXIT_CODE = 3;
 const OSS_ALGORITHM = 'OSS4-HMAC-SHA256';
 const OSS_SERVICE = 'oss';
 const OSS_REQUEST = 'aliyun_v4_request';
@@ -79,7 +94,8 @@ const DIRECT_FILES_LATEST_SCHEMA_VERSION = 1;
 
 function usage() {
   console.log(`用法:
-  npm run database:backup:oss -- [--mode full|history] [--storage-format archive|files] [--data-dir <path>] [--work-dir <path>] [--bucket <bucket>] [--object-prefix <prefix>] [--keep-local]
+  npm run database:backup:oss -- [--mode full|history] [--minimal] [--retain-snapshots 2] [--storage-format archive|files] [--data-dir <path>] [--work-dir <path>] [--bucket <bucket>] [--object-prefix <prefix>] [--keep-local]
+  npm run database:backup:oss -- --check-space-only [--storage-format archive|files] [--data-dir <path>] [--work-dir <path>]
   node -- scripts/database-backup-to-oss.mjs [--stop-service spacetimedb.service] [--restart-service-after genarrative-api.service] [--defer-upload]
   node -- scripts/database-backup-to-oss.mjs --upload-archive <path>
   node -- scripts/database-backup-to-oss.mjs --upload-deferred-dir <path>
@@ -91,6 +107,8 @@ function usage() {
   将 SpacetimeDB 数据目录以 .tar.gz 或逐文件 catalog 形式上传到阿里云 OSS 指定 bucket。
   默认 full 模式保持原有全量冷备行为；history 模式只归档已被最新 snapshot 覆盖的历史 commitlog 与旧 snapshot。
   --storage-format files 不打包：按原相对路径建立 catalog，文件内容以 SHA-256 不可变对象上传；重复运行只上传新增或变化内容。
+  --freeze-dir <path> 仅用于 --minimal：先把选中子集 rsync 成冻结副本再上传，避免热备时最新 commitlog 追加导致 stat 漂移；副本内保持原始相对路径。
+  --minimal 只备份上游 retention 语义下仍需要的部分（最近 --retain-snapshots 份 snapshot + 其后 commitlog 段 + 身份/配置/控制库/模块字节）；只支持 files 格式，且不停止任何服务。
   archive history 必须有已验真的 full baseline state；files history 必须复用同一 work-dir 中已发布的 full catalog state。
   --defer-upload 只生成本地冷备份和 manifest，不上传；后续用 --upload-archive 异步上传。
   --upload-deferred-dir 串行收敛目录内 deferred/pending 及已上传未清理归档；只有 OSS 上传与验真完成后才按 keep-local 规则删除。
@@ -106,6 +124,8 @@ function usage() {
   GENARRATIVE_DATABASE_BACKUP_STORAGE_FORMAT  archive（默认）或 files
   GENARRATIVE_DATABASE_BACKUP_KEEP_LOCAL      true 时保留本地 tar.gz
   GENARRATIVE_DATABASE_BACKUP_MIN_FREE_BYTES  备份前要求 work dir 所在文件系统至少有这些可用字节；未设置时按数据目录大小估算
+  GENARRATIVE_DATABASE_BACKUP_FILES_MIN_FREE_BYTES  files 模式的最小可用字节（默认 2GiB）
+  GENARRATIVE_DATABASE_BACKUP_FILES_SPACE_SAFETY_RATIO  files 模式按数据目录比例要求的可用空间（默认 0.05）
   GENARRATIVE_DATABASE_BACKUP_BASELINE_STATE  history 使用的 full baseline 与追加批次状态文件
   GENARRATIVE_DATABASE_BACKUP_BASELINE_MANIFEST 首次初始化 history state 的 uploaded full manifest
   ALIYUN_OSS_ACCESS_KEY_ID / ALIYUN_OSS_ACCESS_KEY_SECRET
@@ -175,6 +195,7 @@ function parseArgs(argv) {
     restartServicesAfter: [],
     database: '',
     dryRun: false,
+    checkSpaceOnly: false,
     deferUpload: false,
     uploadArchive: '',
     uploadDeferredDir: '',
@@ -183,6 +204,9 @@ function parseArgs(argv) {
     resultFile: '',
     minFreeBytes: '',
     mode: 'full',
+    minimal: false,
+    freezeDir: '',
+    retainSnapshots: DEFAULT_RETAIN_SNAPSHOTS,
     baselineState: '',
     baselineManifest: '',
     publishManifest: '',
@@ -273,6 +297,15 @@ function parseArgs(argv) {
       case '--mode':
         options.mode = readValue();
         break;
+      case '--minimal':
+        options.minimal = true;
+        break;
+      case '--retain-snapshots':
+        options.retainSnapshots = readValue();
+        break;
+      case '--freeze-dir':
+        options.freezeDir = readValue();
+        break;
       case '--baseline-state':
         options.baselineState = readValue();
         break;
@@ -282,6 +315,9 @@ function parseArgs(argv) {
       case '--publish-manifest':
         options.publishManifest = readValue();
         break;
+      case '--check-space-only':
+        options.checkSpaceOnly = true;
+        break;
       case '--storage-format':
         options.storageFormat = readValue();
         break;
@@ -1013,6 +1049,20 @@ function parseSafetyRatio(rawValue) {
   return ratio;
 }
 
+function parseFilesSpaceSafetyRatio(rawValue) {
+  const value = String(rawValue ?? '').trim();
+  if (!value) {
+    return DEFAULT_FILES_SPACE_SAFETY_RATIO;
+  }
+  const ratio = Number(value);
+  if (!Number.isFinite(ratio) || ratio <= 0) {
+    throw new Error(
+      `GENARRATIVE_DATABASE_BACKUP_FILES_SPACE_SAFETY_RATIO 必须是 > 0 的数字，实际: ${rawValue}`,
+    );
+  }
+  return ratio;
+}
+
 function calculateRequiredFreeBytes({ dataSizeBytes, args, env }) {
   const explicitMinFreeBytes = parseByteSize(
     firstNonEmpty(
@@ -1042,22 +1092,57 @@ function calculateRequiredFreeBytes({ dataSizeBytes, args, env }) {
     : extraRequirement;
 }
 
-function assertSufficientWorkDirSpace({ dataDir, workDir, args, env }) {
+function calculateFilesRequiredFreeBytes({ dataSizeBytes, env }) {
+  const explicitMinFreeBytes = parseByteSize(
+    env.GENARRATIVE_DATABASE_BACKUP_FILES_MIN_FREE_BYTES,
+    'GENARRATIVE_DATABASE_BACKUP_FILES_MIN_FREE_BYTES',
+  );
+  if (explicitMinFreeBytes !== null) {
+    return explicitMinFreeBytes;
+  }
+  const ratio = parseFilesSpaceSafetyRatio(
+    env.GENARRATIVE_DATABASE_BACKUP_FILES_SPACE_SAFETY_RATIO,
+  );
+  const ratioBasisPoints = BigInt(Math.ceil(ratio * 10000));
+  const ratioRequirement = (dataSizeBytes * ratioBasisPoints + 9999n) / 10000n;
+  const floorRequirement = BigInt(DEFAULT_FILES_EXTRA_FREE_BYTES);
+  return ratioRequirement > floorRequirement ? ratioRequirement : floorRequirement;
+}
+
+export function describeBackupSpaceRequirement({
+  dataDir,
+  workDir,
+  storageFormat = 'archive',
+  args = {},
+  env = {},
+}) {
   mkdirSync(workDir, { recursive: true });
   const dataSizeBytes = getDirectorySizeBytes(dataDir);
   const availableBytes = getAvailableBytes(workDir);
-  const requiredFreeBytes = calculateRequiredFreeBytes({
-    dataSizeBytes,
-    args,
-    env,
-  });
+  const requiredFreeBytes =
+    storageFormat === 'files'
+      ? calculateFilesRequiredFreeBytes({ dataSizeBytes, env })
+      : calculateRequiredFreeBytes({ dataSizeBytes, args, env });
+  return { storageFormat, dataSizeBytes, availableBytes, requiredFreeBytes };
+}
+
+function assertSufficientWorkDirSpace({ dataDir, workDir, args, env, storageFormat = 'archive' }) {
+  const { dataSizeBytes, availableBytes, requiredFreeBytes } =
+    describeBackupSpaceRequirement({
+      dataDir,
+      workDir,
+      storageFormat,
+      args,
+      env,
+    });
   console.log(
-    `[database-backup] 备份空间预检: data=${formatBytes(dataSizeBytes)}, available=${formatBytes(availableBytes)}, required=${formatBytes(requiredFreeBytes)}`,
+    `[database-backup] 备份空间预检(${storageFormat}): data=${formatBytes(dataSizeBytes)}, available=${formatBytes(availableBytes)}, required=${formatBytes(requiredFreeBytes)}`,
   );
   if (availableBytes < requiredFreeBytes) {
-    throw new Error(
+    const error = new Error(
       [
         `备份工作目录所在文件系统剩余空间不足: ${workDir}`,
+        `storage-format=${storageFormat}`,
         `available=${formatBytes(availableBytes)}`,
         `required=${formatBytes(requiredFreeBytes)}`,
         `dataDir=${dataDir}`,
@@ -1065,7 +1150,10 @@ function assertSufficientWorkDirSpace({ dataDir, workDir, args, env }) {
         '为避免停库后写满磁盘，本次备份已在停止服务前中止。',
       ].join('；'),
     );
+    error.spaceInsufficient = true;
+    throw error;
   }
+  return { dataSizeBytes, availableBytes, requiredFreeBytes };
 }
 
 function assertSufficientHistoryWorkDirSpace({
@@ -1319,6 +1407,217 @@ function candidateKey(candidate) {
   return `${candidate.kind}\0${candidate.path}`;
 }
 
+/**
+ * minimal 备份只保留上游 retention 语义下仍然需要的部分：
+ * 每个 replica 最近 retainSnapshots 份 snapshot、覆盖最老保留 snapshot 的
+ * commitlog 边界段及其后的全部 commitlog（段边界与上游 pruner 一致），
+ * 外加身份、standalone 配置、控制库与模块字节等小体积状态。
+ * 历史 snapshot 与更早的 commitlog 段不再备份，因此也不需要计算增量差异。
+ */
+export function discoverMinimalPlan({
+  dataDir,
+  retainSnapshots = DEFAULT_RETAIN_SNAPSHOTS,
+}) {
+  const retainCount = Number(retainSnapshots);
+  if (!Number.isInteger(retainCount) || retainCount < 1) {
+    throw new Error(
+      `--retain-snapshots 必须是 >= 1 的整数，实际: ${retainSnapshots}`,
+    );
+  }
+  const resolvedDataDir = resolvePath(dataDir);
+  const replicasDir = findReplicasDir(resolvedDataDir);
+  const replicas = [];
+  const candidates = [];
+
+  const replicaIds = readdirSync(replicasDir, { withFileTypes: true })
+    .sort((left, right) => left.name.localeCompare(right.name))
+    .flatMap((entry) => {
+      if (!entry.isDirectory()) {
+        return [];
+      }
+      if (!/^\d+$/u.test(entry.name)) {
+        throw new Error(`replica 目录名不符合预期: ${entry.name}`);
+      }
+      return [entry.name];
+    });
+
+  for (const replicaId of replicaIds) {
+    const replicaDir = join(replicasDir, replicaId);
+    const snapshotsDir = join(replicaDir, 'snapshots');
+    const clogDir = join(replicaDir, 'clog');
+    if (!existsSync(snapshotsDir) || !lstatSync(snapshotsDir).isDirectory()) {
+      replicas.push({
+        replicaId,
+        status: 'skipped',
+        reason: 'no-snapshots-directory',
+      });
+      continue;
+    }
+    const snapshots = readdirSync(snapshotsDir, { withFileTypes: true })
+      .flatMap((entry) => {
+        const match = /^(\d{20})[.]snapshot_dir$/u.exec(entry.name);
+        if (!match) {
+          return [];
+        }
+        const transaction = BigInt(match[1]);
+        if (transaction > 0xffff_ffff_ffff_ffffn) {
+          throw new Error(`snapshot transaction 超出 u64: ${entry.name}`);
+        }
+        if (!entry.isDirectory()) {
+          throw new Error(
+            `snapshot 候选必须是目录: ${join(snapshotsDir, entry.name)}`,
+          );
+        }
+        const snapshotDir = join(snapshotsDir, entry.name);
+        const lockPath = join(snapshotsDir, `${match[1]}.lock`);
+        const snapshotFile = join(snapshotDir, `${match[1]}.snapshot_bsatn`);
+        if (
+          existsSync(lockPath) ||
+          !existsSync(snapshotFile) ||
+          !lstatSync(snapshotFile).isFile()
+        ) {
+          return [];
+        }
+        return [{ name: entry.name, transaction }];
+      })
+      .sort((left, right) =>
+        left.transaction < right.transaction
+          ? -1
+          : left.transaction > right.transaction
+            ? 1
+            : 0,
+      );
+    if (snapshots.length === 0) {
+      replicas.push({ replicaId, status: 'skipped', reason: 'no-snapshot' });
+      continue;
+    }
+    if (!existsSync(clogDir) || !lstatSync(clogDir).isDirectory()) {
+      throw new Error(`replica ${replicaId} 缺少 clog 目录。`);
+    }
+    const segmentFiles = new Map();
+    for (const entry of readdirSync(clogDir, { withFileTypes: true })) {
+      const match = /^(\d{20})[.]stdb[.](log|ofs)$/u.exec(entry.name);
+      if (!match) {
+        throw new Error(`commitlog 文件名不符合预期: ${entry.name}`);
+      }
+      if (!entry.isFile()) {
+        throw new Error(
+          `commitlog 候选必须是普通文件: ${join(clogDir, entry.name)}`,
+        );
+      }
+      const transaction = BigInt(match[1]);
+      if (transaction > 0xffff_ffff_ffff_ffffn) {
+        throw new Error(`commitlog transaction 超出 u64: ${entry.name}`);
+      }
+      const key = transaction.toString();
+      const group = segmentFiles.get(key) ?? { transaction };
+      group[match[2]] = entry.name;
+      segmentFiles.set(key, group);
+    }
+    for (const group of segmentFiles.values()) {
+      if (group.ofs && !group.log) {
+        throw new Error(
+          `commitlog offset 缺少对应 log: replica=${replicaId}, transaction=${group.transaction}`,
+        );
+      }
+    }
+    const segments = [...segmentFiles.values()]
+      .filter((group) => group.log)
+      .sort((left, right) =>
+        left.transaction < right.transaction
+          ? -1
+          : left.transaction > right.transaction
+            ? 1
+            : 0,
+      );
+
+    const retainedSnapshots = snapshots.slice(-retainCount);
+    const oldestRetainedSnapshot = retainedSnapshots[0].transaction;
+    const boundarySegment = segments
+      .filter((segment) => segment.transaction <= oldestRetainedSnapshot)
+      .at(-1);
+    if (!boundarySegment) {
+      throw new Error(
+        `replica ${replicaId} 无法找到覆盖最老保留 snapshot ${oldestRetainedSnapshot} 的 commitlog 边界。`,
+      );
+    }
+    const retainedSegments = segments.filter(
+      (segment) => segment.transaction >= boundarySegment.transaction,
+    );
+
+    for (const snapshot of retainedSnapshots) {
+      candidates.push(
+        historyCandidate({
+          dataDir: resolvedDataDir,
+          absolutePath: join(snapshotsDir, snapshot.name),
+          kind: 'snapshot',
+          replicaId,
+          transaction: snapshot.transaction,
+        }),
+      );
+    }
+    for (const segment of retainedSegments) {
+      candidates.push(
+        historyCandidate({
+          dataDir: resolvedDataDir,
+          absolutePath: join(clogDir, segment.log),
+          kind: 'commitlog',
+          replicaId,
+          transaction: segment.transaction,
+        }),
+      );
+      if (segment.ofs) {
+        candidates.push(
+          historyCandidate({
+            dataDir: resolvedDataDir,
+            absolutePath: join(clogDir, segment.ofs),
+            kind: 'commitlog-offset',
+            replicaId,
+            transaction: segment.transaction,
+          }),
+        );
+      }
+    }
+    replicas.push({
+      replicaId,
+      status: 'ready',
+      retainedSnapshots: retainedSnapshots.length,
+      droppedSnapshots: snapshots.length - retainedSnapshots.length,
+      oldestRetainedSnapshot: oldestRetainedSnapshot.toString(),
+      boundarySegment: boundarySegment.transaction.toString(),
+      droppedSegments: segments.length - retainedSegments.length,
+    });
+  }
+
+  for (const relativePath of MINIMAL_STATIC_PATHS) {
+    const absolutePath = resolve(resolvedDataDir, relativePath);
+    if (!existsSync(absolutePath)) {
+      continue;
+    }
+    candidates.push(
+      historyCandidate({
+        dataDir: resolvedDataDir,
+        absolutePath,
+        kind: 'state',
+        replicaId: 'state',
+        transaction: 0n,
+      }),
+    );
+  }
+
+  candidates.sort((left, right) => left.path.localeCompare(right.path));
+  return {
+    dataDir: resolvedDataDir,
+    replicasDir: assertSafeRelativePath(resolvedDataDir, replicasDir),
+    replicas,
+    retainSnapshots: retainCount,
+    candidates,
+    totalSizeBytes: candidates
+      .reduce((sum, item) => sum + BigInt(item.sizeBytes), 0n)
+      .toString(),
+  };
+}
+
 export function cleanupHistoryCandidates({ dataDir, candidates }) {
   const currentPlan = discoverHistoryPlan({ dataDir });
   const eligible = new Map(
@@ -2050,6 +2349,8 @@ async function publishDirectFilesLatest({
 
 export async function runDirectFilesBackup({
   mode,
+  minimal = false,
+  retainSnapshots = DEFAULT_RETAIN_SNAPSHOTS,
   dataDir,
   workDir,
   database,
@@ -2075,7 +2376,17 @@ export async function runDirectFilesBackup({
       `files history 模式缺少已发布 full baseline catalog: ${statePath}`,
     );
   }
-  const plan = mode === 'history' ? discoverHistoryPlan({ dataDir }) : null;
+  const plan =
+    mode === 'history'
+      ? discoverHistoryPlan({ dataDir })
+      : minimal
+        ? discoverMinimalPlan({ dataDir, retainSnapshots })
+        : null;
+  if (minimal) {
+    console.log(
+      `[database-backup] files minimal: retainSnapshots=${plan.retainSnapshots}, candidates=${plan.candidates.length}, size=${plan.totalSizeBytes}`,
+    );
+  }
   const collected = await collectDirectFileEntries({
     dataDir,
     candidates: plan?.candidates ?? null,
@@ -4081,7 +4392,7 @@ async function main() {
   const env = loadEffectiveEnv(args.envFiles);
   const isProductionLike =
     existsSync(DEFAULT_PRODUCTION_DATA_DIR) && process.platform !== 'win32';
-  const dataDir = resolvePath(
+  let dataDir = resolvePath(
     firstNonEmpty(
       args.dataDir,
       env.GENARRATIVE_DATABASE_BACKUP_DATA_DIR,
@@ -4153,6 +4464,71 @@ async function main() {
       `--storage-format 只能是 archive 或 files，实际: ${storageFormat}`,
     );
   }
+  if (args.minimal && storageFormat !== 'files') {
+    throw new Error('--minimal 只支持 --storage-format files。');
+  }
+  if (args.minimal && args.mode === 'history') {
+    throw new Error('--minimal 只支持 --mode full：minimal 自身就是自包含快照。');
+  }
+
+  if (args.minimal && args.freezeDir) {
+    if (storageFormat !== 'files') {
+      throw new Error('--freeze-dir 只支持 --minimal --storage-format files。');
+    }
+    const freezeDir = resolvePath(args.freezeDir);
+    const plan = discoverMinimalPlan({
+      dataDir,
+      retainSnapshots: args.retainSnapshots,
+    });
+    console.log(
+      `[database-backup] minimal freeze: candidates=${plan.candidates.length}, size=${plan.totalSizeBytes}, freezeDir=${freezeDir}`,
+    );
+    if (!args.dryRun) {
+      mkdirSync(freezeDir, { recursive: true });
+      const listPath = join(workDir, 'minimal-freeze-files.txt');
+      mkdirSync(workDir, { recursive: true });
+      writeFileSync(
+        listPath,
+        `${plan.candidates.map((item) => item.path).join('\n')}\n`,
+        'utf8',
+      );
+      const result = spawnSync(
+        'rsync',
+        [
+          '-a',
+          '-r',
+          '--delete',
+          `--files-from=${listPath}`,
+          `${dataDir}/`,
+          `${freezeDir}/`,
+        ],
+        { stdio: 'inherit' },
+      );
+      if (result.status !== 0) {
+        throw new Error(
+          `minimal freeze 拷贝失败: rsync exit=${result.status ?? '<signal>'}`,
+        );
+      }
+      console.log(
+        `[database-backup] minimal freeze 完成，后续从冻结副本上传: ${freezeDir}`,
+      );
+    }
+    dataDir = freezeDir;
+  }
+
+  if (args.checkSpaceOnly) {
+    assertSufficientWorkDirSpace({
+      dataDir,
+      workDir,
+      args,
+      env,
+      storageFormat,
+    });
+    console.log(
+      `[database-backup] 空间预检通过(check-space-only): storage-format=${storageFormat}, workDir=${workDir}`,
+    );
+    return;
+  }
 
   for (const [label, value] of Object.entries({
     bucket,
@@ -4273,11 +4649,13 @@ async function main() {
     let backupError = null;
     let restoreError = null;
     try {
-      if (args.mode === 'full' && !args.dryRun) {
+      if (args.mode === 'full' && !args.minimal && !args.dryRun) {
         serviceStopped = stopServiceIfNeeded(stopService, stopMarkerPath);
       }
       await runDirectFilesBackup({
         mode: args.mode,
+        minimal: args.minimal,
+        retainSnapshots: args.retainSnapshots,
         dataDir,
         workDir,
         database,
@@ -4369,7 +4747,7 @@ async function main() {
   const restartServicesAfter = collectRestartServicesAfterBackup({ args, env });
   const stopMarkerPath = databaseBackupStopMarkerPath(workDir);
   try {
-    assertSufficientWorkDirSpace({ dataDir, workDir, args, env });
+    assertSufficientWorkDirSpace({ dataDir, workDir, args, env, storageFormat: 'archive' });
     serviceStopped = stopServiceIfNeeded(stopService, stopMarkerPath);
     archivePath = createArchive({ dataDir, workDir, fileName });
   } catch (error) {
@@ -4558,6 +4936,6 @@ if (
     } catch {
       // 参数解析或状态文件写入失败时，不能掩盖原始备份错误。
     }
-    process.exit(1);
+    process.exit(error?.spaceInsufficient ? SPACE_INSUFFICIENT_EXIT_CODE : 1);
   });
 }
diff --git a/scripts/deploy/production-stdb-publish.sh b/scripts/deploy/production-stdb-publish.sh
index e96210ecb..37933968d 100644
--- a/scripts/deploy/production-stdb-publish.sh
+++ b/scripts/deploy/production-stdb-publish.sh
@@ -18,9 +18,18 @@ usage() {
   如需强制等待备份完成并在失败时阻断 publish，传入 --backup-mode sync。
   发布成功后会补齐生产 API/worker env 的固定 bootstrap secret FILE 路径，再重启并验活重启前 active 的服务。
   --keep-maintenance-mode 会在 publish 前停止旧 API/controller/worker，并在成功后保持维护态，交由后续 API deploy 恢复服务。
+  发布前先做备份空间预检（不进入维护、不停服务）；archive 空间不足且未显式关闭自动降级时，
+  自动改用 files 存储格式（不落地本地归档，改为同步直传 OSS），避免磁盘不足把生产留在维护态。
+
+环境变量：
+  GENARRATIVE_STDB_PUBLISH_BACKUP_STORAGE_FORMAT=archive|files（默认 archive）
+  GENARRATIVE_STDB_PUBLISH_AUTO_FILES_FALLBACK=1|0（默认 1：archive 空间不足自动降级 files）
+  GENARRATIVE_STDB_PUBLISH_BACKUP_MINIMAL=1|0（默认 1：发布前备份只保留最近 N 份 snapshot + 其后 commitlog，热备不停服）
+  GENARRATIVE_STDB_PUBLISH_BACKUP_RETAIN_SNAPSHOTS=N（默认 2，仅在 minimal 模式下生效）
+  GENARRATIVE_STDB_PUBLISH_AUTO_RECOVER_ON_PREPUBLISH_FAILURE=1|0（默认 1：尚未开始 publish 的失败自动恢复服务并退出维护）
   migration bootstrap secret 必须由 Jenkins Secret File credential 或等价的受保护文件提供，不从构建 artifact 读取。
   如果 API 重启前为 active，会在退出维护模式前等待本机 /healthz readiness 通过。
-  失败时保留维护模式。
+  失败时：尚未开始 publish 的失败会自动恢复运行时服务并退出维护；真正开始 publish 之后的失败保留维护模式。
 EOF
 }
 
@@ -55,7 +64,15 @@ API_ENV_FILE="${GENARRATIVE_STDB_PUBLISH_API_ENV_FILE:-/etc/genarrative/api-serv
 WORKER_ENV_FILE="${GENARRATIVE_STDB_PUBLISH_WORKER_ENV_FILE:-/etc/genarrative/external-generation-worker.env}"
 KEEP_MAINTENANCE_MODE=0
 BACKUP_MODE="${GENARRATIVE_STDB_PUBLISH_BACKUP_MODE:-async}"
+BACKUP_STORAGE_FORMAT="${GENARRATIVE_STDB_PUBLISH_BACKUP_STORAGE_FORMAT:-archive}"
+AUTO_FILES_FALLBACK="${GENARRATIVE_STDB_PUBLISH_AUTO_FILES_FALLBACK:-1}"
+AUTO_RECOVER_BEFORE_PUBLISH="${GENARRATIVE_STDB_PUBLISH_AUTO_RECOVER_ON_PREPUBLISH_FAILURE:-1}"
+BACKUP_MINIMAL="${GENARRATIVE_STDB_PUBLISH_BACKUP_MINIMAL:-1}"
+BACKUP_RETAIN_SNAPSHOTS="${GENARRATIVE_STDB_PUBLISH_BACKUP_RETAIN_SNAPSHOTS:-2}"
 DEPLOY_COMPLETED=0
+PUBLISH_STARTED=0
+MAINTENANCE_ENTERED=0
+STOPPED_RUNTIME_SERVICES=()
 PUBLISH_TMP_DIR=""
 ASYNC_BACKUP_STATUS_FILE=""
 ASYNC_BACKUP_SCRIPT=""
@@ -287,6 +304,114 @@ restart_runtime_services_after_bootstrap_secret_install() {
   fi
 }
 
+backup_script_path() {
+  local candidate=""
+  for candidate in \
+    "${SCRIPT_DIR}/../database-backup-to-oss.mjs" \
+    "${SOURCE_DIR}/scripts/database-backup-to-oss.mjs"; do
+    if [[ -f "${candidate}" ]]; then
+      printf '%s\n' "${candidate}"
+      return 0
+    fi
+  done
+  return 1
+}
+
+run_backup_space_precheck() {
+  local storage_format="$1"
+  local backup_script=""
+  if ! backup_script="$(backup_script_path)"; then
+    echo "[production-stdb-publish] 缺少数据库备份脚本，无法做备份空间预检" >&2
+    return 1
+  fi
+  node -- "${backup_script}" \
+    --env-file /etc/genarrative/api-server.env \
+    --data-dir "${SPACETIME_ROOT_DIR}" \
+    --database "${DATABASE}" \
+    --storage-format "${storage_format}" \
+    --check-space-only
+}
+
+# 空间预检必须发生在进入维护模式与停服务之前：磁盘不够时不允许再动生产。
+precheck_backup_space_before_maintenance() {
+  if [[ "${BACKUP_MODE}" == "skip" ]]; then
+    echo "[production-stdb-publish] 已跳过发布前备份空间预检（--backup-mode skip）"
+    return 0
+  fi
+  if [[ "${BACKUP_MINIMAL}" == "1" ]]; then
+    # minimal 备份是热备：只保留最近 N 份 snapshot + 其后 commitlog，不落地归档也不停服务。
+    BACKUP_STORAGE_FORMAT="files"
+    if [[ "${BACKUP_MODE}" == "async" ]]; then
+      echo "[production-stdb-publish] minimal 备份为同步热备（无本地归档），备份模式由 async 调整为 sync。" >&2
+      BACKUP_MODE="sync"
+    fi
+  fi
+
+  local status=0
+  run_backup_space_precheck "${BACKUP_STORAGE_FORMAT}" || status=$?
+  if [[ "${status}" -eq 0 ]]; then
+    echo "[production-stdb-publish] 发布前备份空间预检通过: storage-format=${BACKUP_STORAGE_FORMAT}（尚未进入维护模式、未停服务）"
+    return 0
+  fi
+  if [[ "${status}" -ne 3 ]]; then
+    echo "[production-stdb-publish] 发布前备份空间预检失败（非空间原因），中止发布；未进入维护模式、未停服务。" >&2
+    exit 1
+  fi
+  if [[ "${BACKUP_STORAGE_FORMAT}" == "files" ]]; then
+    echo "[production-stdb-publish] files 模式备份空间仍不足，中止发布；未进入维护模式、未停服务。" >&2
+    exit 1
+  fi
+  if [[ "${AUTO_FILES_FALLBACK}" != "1" ]]; then
+    echo "[production-stdb-publish] archive 备份空间不足且已禁用自动降级（GENARRATIVE_STDB_PUBLISH_AUTO_FILES_FALLBACK=${AUTO_FILES_FALLBACK}），中止发布；未进入维护模式、未停服务。" >&2
+    exit 1
+  fi
+
+  echo "[production-stdb-publish] archive 冷备份空间不足：自动降级为 files 存储格式（不落地本地归档，改为文件级 catalog 直传 OSS）。" >&2
+  BACKUP_STORAGE_FORMAT="files"
+  if [[ "${BACKUP_MODE}" == "async" ]]; then
+    echo "[production-stdb-publish] files 模式不支持 --defer-upload，本次备份改为同步执行。" >&2
+    BACKUP_MODE="sync"
+  fi
+  status=0
+  run_backup_space_precheck "${BACKUP_STORAGE_FORMAT}" || status=$?
+  if [[ "${status}" -ne 0 ]]; then
+    echo "[production-stdb-publish] 降级为 files 后空间预检仍失败，中止发布；未进入维护模式、未停服务。" >&2
+    exit 1
+  fi
+  echo "[production-stdb-publish] 已降级为 files 存储格式且空间预检通过。"
+}
+
+# 仅在「尚未开始 publish」的失败路径调用：把本次停掉的运行时服务拉回来。
+restore_runtime_services_before_publish() {
+  if [[ "${#STOPPED_RUNTIME_SERVICES[@]}" -eq 0 ]]; then
+    return 0
+  fi
+  local service=""
+  local state=""
+  local attempt=0
+  echo "[production-stdb-publish] 发布尚未开始，恢复本次停掉的运行时服务: ${STOPPED_RUNTIME_SERVICES[*]}"
+  if ! run_privileged systemctl start "${STOPPED_RUNTIME_SERVICES[@]}"; then
+    echo "[production-stdb-publish] 启动运行时服务失败: ${STOPPED_RUNTIME_SERVICES[*]}" >&2
+    return 1
+  fi
+  for service in "${STOPPED_RUNTIME_SERVICES[@]}"; do
+    state=""
+    for attempt in $(seq 1 15); do
+      state="$(get_runtime_service_active_state "${service}" 2>/dev/null || true)"
+      if [[ "${state}" == "active" ]]; then
+        break
+      fi
+      sleep 1
+    done
+    if [[ "${state}" != "active" ]]; then
+      echo "[production-stdb-publish] 运行时服务未恢复 active: ${service}, state=${state}" >&2
+      return 1
+    fi
+    echo "[production-stdb-publish] 运行时服务已恢复 active: ${service}"
+  done
+  return 0
+}
+
 stop_runtime_services_for_rollout_gate() {
   local api_state=""
   local controller_state=""
@@ -326,6 +451,7 @@ stop_runtime_services_for_rollout_gate() {
   fi
 
   echo "[production-stdb-publish] 停止旧运行时服务并保持维护态: ${services_to_stop[*]}"
+  STOPPED_RUNTIME_SERVICES=("${services_to_stop[@]}")
   run_privileged systemctl stop "${services_to_stop[@]}"
   for worker_service in "${services_to_stop[@]}"; do
     if [[ "$(get_runtime_service_active_state "${worker_service}")" == "active" ]]; then
@@ -402,6 +528,10 @@ while [[ $# -gt 0 ]]; do
       BACKUP_MODE="${2:?缺少 --backup-mode 的值}"
       shift 2
       ;;
+    --backup-storage-format)
+      BACKUP_STORAGE_FORMAT="${2:?缺少 --backup-storage-format 的值}"
+      shift 2
+      ;;
     *)
       echo "[production-stdb-publish] 未知参数: $1" >&2
       usage >&2
@@ -431,6 +561,14 @@ for runtime_env_file in "${API_ENV_FILE}" "${WORKER_ENV_FILE}"; do
   fi
 done
 
+if [[ ! "${BACKUP_STORAGE_FORMAT}" =~ ^(archive|files)$ ]]; then
+  echo "[production-stdb-publish] --backup-storage-format 只能是 archive 或 files: ${BACKUP_STORAGE_FORMAT}" >&2
+  exit 1
+fi
+if [[ "${BACKUP_STORAGE_FORMAT}" == "files" && "${BACKUP_MODE}" == "async" ]]; then
+  echo "[production-stdb-publish] files 存储格式不支持 --defer-upload，备份模式由 async 调整为 sync" >&2
+  BACKUP_MODE="sync"
+fi
 if [[ ! "${BACKUP_MODE}" =~ ^(async|sync|skip)$ ]]; then
   echo "[production-stdb-publish] --backup-mode 只能是 async、sync 或 skip: ${BACKUP_MODE}" >&2
   exit 1
@@ -497,7 +635,22 @@ on_exit() {
     rm -rf "${PUBLISH_TMP_DIR}"
   fi
   if [[ "${exit_code}" -ne 0 && "${DEPLOY_COMPLETED}" -ne 1 ]]; then
-    echo "[production-stdb-publish] 发布失败，保持维护模式。" >&2
+    if [[ "${PUBLISH_STARTED}" -ne 1 && "${AUTO_RECOVER_BEFORE_PUBLISH}" == "1" ]]; then
+      # 尚未开始 publish 就失败（例如备份空间/备份执行失败）：本次没有任何发布变更，
+      # 必须把停掉的运行时服务拉回来并退出维护，避免生产停在维护态等人工救。
+      if restore_runtime_services_before_publish; then
+        if [[ "${MAINTENANCE_ENTERED}" -eq 1 ]]; then
+          if ! "${SCRIPT_DIR}/maintenance-off.sh"; then
+            echo "[production-stdb-publish] 自动退出维护模式失败，请手工执行 maintenance-off.sh。" >&2
+          fi
+        fi
+        echo "[production-stdb-publish] 发布尚未开始即失败，已自动恢复运行时服务并退出维护模式。"
+      else
+        echo "[production-stdb-publish] 自动恢复运行时服务失败，保持维护模式，请手工处理。" >&2
+      fi
+    else
+      echo "[production-stdb-publish] 发布失败，保持维护模式。" >&2
+    fi
   fi
   exit "${exit_code}"
 }
@@ -506,12 +659,8 @@ trap on_exit EXIT
 
 prepare_async_backup() {
   local -a restart_service_args=()
-  ASYNC_BACKUP_SCRIPT="${SCRIPT_DIR}/../database-backup-to-oss.mjs"
-  if [[ ! -f "${ASYNC_BACKUP_SCRIPT}" ]]; then
-    ASYNC_BACKUP_SCRIPT="${SOURCE_DIR}/scripts/database-backup-to-oss.mjs"
-  fi
-  if [[ ! -f "${ASYNC_BACKUP_SCRIPT}" ]]; then
-    echo "[production-stdb-publish] 缺少数据库备份脚本: ${ASYNC_BACKUP_SCRIPT}" >&2
+  if ! ASYNC_BACKUP_SCRIPT="$(backup_script_path)"; then
+    echo "[production-stdb-publish] 缺少数据库备份脚本: ${SOURCE_DIR}/scripts/database-backup-to-oss.mjs" >&2
     exit 1
   fi
 
@@ -527,6 +676,7 @@ prepare_async_backup() {
     --env-file /etc/genarrative/api-server.env \
     --data-dir "${SPACETIME_ROOT_DIR}" \
     --database "${DATABASE}" \
+    --storage-format "${BACKUP_STORAGE_FORMAT}" \
     --stop-service spacetimedb.service \
     "${restart_service_args[@]}" \
     --defer-upload \
@@ -676,7 +826,10 @@ wait_for_api_healthz_ready() {
   return 1
 }
 
+precheck_backup_space_before_maintenance
+
 "${SCRIPT_DIR}/maintenance-on.sh" "spacetime module publish ${DATABASE}"
+MAINTENANCE_ENTERED=1
 if [[ "${KEEP_MAINTENANCE_MODE}" -eq 1 ]]; then
   stop_runtime_services_for_rollout_gate
 fi
@@ -687,25 +840,34 @@ case "${BACKUP_MODE}" in
     ;;
   sync)
     SYNC_BACKUP_RESTART_SERVICE_ARGS=()
-    BACKUP_SCRIPT="${SCRIPT_DIR}/../database-backup-to-oss.mjs"
-    if [[ ! -f "${BACKUP_SCRIPT}" ]]; then
-      BACKUP_SCRIPT="${SOURCE_DIR}/scripts/database-backup-to-oss.mjs"
-    fi
-    if [[ ! -f "${BACKUP_SCRIPT}" ]]; then
-      echo "[production-stdb-publish] 缺少 publish 前数据库备份脚本: ${BACKUP_SCRIPT}" >&2
+    if ! BACKUP_SCRIPT="$(backup_script_path)"; then
+      echo "[production-stdb-publish] 缺少 publish 前数据库备份脚本: ${SOURCE_DIR}/scripts/database-backup-to-oss.mjs" >&2
       exit 1
     fi
     if [[ "${KEEP_MAINTENANCE_MODE}" -ne 1 ]]; then
       SYNC_BACKUP_RESTART_SERVICE_ARGS+=(--restart-service-after genarrative-api.service)
     fi
 
-    echo "[production-stdb-publish] publish 前同步执行 OSS 冷备份，失败会阻断发布"
-    node -- "${BACKUP_SCRIPT}" \
-      --env-file /etc/genarrative/api-server.env \
-      --data-dir "${SPACETIME_ROOT_DIR}" \
-      --database "${DATABASE}" \
-      --stop-service spacetimedb.service \
-      "${SYNC_BACKUP_RESTART_SERVICE_ARGS[@]}"
+    SYNC_BACKUP_ARGS=(
+      --env-file /etc/genarrative/api-server.env
+      --data-dir "${SPACETIME_ROOT_DIR}"
+      --database "${DATABASE}"
+      --storage-format "${BACKUP_STORAGE_FORMAT}"
+    )
+    if [[ "${BACKUP_MINIMAL}" == "1" ]]; then
+      echo "[production-stdb-publish] publish 前执行 minimal 热备（最近 ${BACKUP_RETAIN_SNAPSHOTS} 份 snapshot + 其后 commitlog），不停服务"
+      SYNC_BACKUP_ARGS+=(
+        --mode full
+        --minimal
+        --retain-snapshots "${BACKUP_RETAIN_SNAPSHOTS}"
+        --freeze-dir "${GENARRATIVE_STDB_PUBLISH_BACKUP_FREEZE_DIR:-/var/lib/genarrative/database-backups/publish-minimal-freeze}"
+      )
+    else
+      echo "[production-stdb-publish] publish 前同步执行 OSS 冷备份（storage-format=${BACKUP_STORAGE_FORMAT}），失败会阻断发布"
+      SYNC_BACKUP_ARGS+=(--stop-service spacetimedb.service)
+      SYNC_BACKUP_ARGS+=("${SYNC_BACKUP_RESTART_SERVICE_ARGS[@]}")
+    fi
+    node -- "${BACKUP_SCRIPT}" "${SYNC_BACKUP_ARGS[@]}"
     ;;
   skip)
     echo "[production-stdb-publish] 已按参数跳过 publish 前数据库备份"
@@ -742,6 +904,34 @@ else
   echo "[production-stdb-publish] 发布 SpacetimeDB module: ${DATABASE} -> ${SERVER_ALIAS}, root=${SPACETIME_ROOT_DIR}"
 fi
 
+# 迁移已提交但客户端等确认超时（HTTP 504 / timeout waiting for transaction confirmation）
+# 时不能直接判失败：重试一次同版本 publish，SpacetimeDB 对已生效的同版本是幂等的 no-op，
+# 重试成功即说明目标模块已在位，避免把生产留在维护态。
+run_spacetime_publish() {
+  local attempt=1
+  local output=""
+  local status=0
+  while :; do
+    output=""
+    status=0
+    if [[ -n "${RUN_AS_USER}" && "$(id -u)" -eq 0 ]]; then
+      output="$(runuser -u "${RUN_AS_USER}" -- spacetime "${PUBLISH_ARGS[@]}" 2>&1)" || status=$?
+    else
+      output="$(spacetime "${PUBLISH_ARGS[@]}" 2>&1)" || status=$?
+    fi
+    printf '%s\n' "${output}"
+    if [[ "${status}" -eq 0 ]]; then
+      return 0
+    fi
+    if [[ "${attempt}" -ge 2 || "${output}" != *"timeout waiting for transaction confirmation"* ]]; then
+      return "${status}"
+    fi
+    echo "[production-stdb-publish] publish 客户端等事务确认超时，可能迁移已提交；重试一次同版本 publish 以确认模块状态。" >&2
+    attempt=$((attempt + 1))
+    sleep 5
+  done
+}
+
 if [[ -n "${RUN_AS_USER}" && "$(id -u)" -eq 0 ]]; then
   if ! id "${RUN_AS_USER}" >/dev/null 2>&1; then
     echo "[production-stdb-publish] 发布用户不存在: ${RUN_AS_USER}" >&2
@@ -768,9 +958,11 @@ if [[ -n "${RUN_AS_USER}" && "$(id -u)" -eq 0 ]]; then
   else
     PUBLISH_ARGS+=(--server "${SERVER_ALIAS}")
   fi
-  runuser -u "${RUN_AS_USER}" -- spacetime "${PUBLISH_ARGS[@]}"
+  PUBLISH_STARTED=1
+  run_spacetime_publish
 else
-  spacetime "${PUBLISH_ARGS[@]}"
+  PUBLISH_STARTED=1
+  run_spacetime_publish
 fi
 
 RUNTIME_SERVICE_BOOTSTRAP_SECRET_DIR="$(dirname "${RUNTIME_SERVICE_BOOTSTRAP_SECRET_FILE}")"
diff --git a/scripts/jenkins-server-provision.sh b/scripts/jenkins-server-provision.sh
index 259b6f6c8..9d2bda38a 100755
--- a/scripts/jenkins-server-provision.sh
+++ b/scripts/jenkins-server-provision.sh
@@ -15,6 +15,8 @@ DATABASE_BACKUP_PROFILE="${DATABASE_BACKUP_PROFILE:-archive-full}"
 DATABASE_BACKUP_FILES_HISTORY_WORK_DIR="${DATABASE_BACKUP_FILES_HISTORY_WORK_DIR:-/var/lib/genarrative/database-backups/files-history}"
 DATABASE_BACKUP_FILES_HISTORY_DROP_IN_DIR="/etc/systemd/system/genarrative-database-backup.service.d"
 DATABASE_BACKUP_FILES_HISTORY_DROP_IN="${DATABASE_BACKUP_FILES_HISTORY_DROP_IN_DIR}/10-files-history.conf"
+DATABASE_BACKUP_FILES_MINIMAL_WORK_DIR="${DATABASE_BACKUP_FILES_MINIMAL_WORK_DIR:-/var/lib/genarrative/database-backups/files-minimal}"
+DATABASE_BACKUP_FILES_MINIMAL_DROP_IN="${DATABASE_BACKUP_FILES_HISTORY_DROP_IN_DIR}/10-files-minimal.conf"
 DATABASE_BACKUP_LEGACY_DEV_DROP_IN="${DATABASE_BACKUP_FILES_HISTORY_DROP_IN_DIR}/10-dev-files.conf"
 
 require_non_root_relative_path() {
@@ -71,10 +73,10 @@ validate_server_names() {
 
 validate_database_backup_profile() {
   case "${DATABASE_BACKUP_PROFILE}" in
-    archive-full|files-history)
+    archive-full|files-history|files-minimal)
       ;;
     *)
-      echo "[server-provision] DATABASE_BACKUP_PROFILE 只能是 archive-full 或 files-history，当前值: ${DATABASE_BACKUP_PROFILE}" >&2
+      echo "[server-provision] DATABASE_BACKUP_PROFILE 只能是 archive-full、files-history 或 files-minimal，当前值: ${DATABASE_BACKUP_PROFILE}" >&2
       exit 1
       ;;
   esac
@@ -1323,12 +1325,29 @@ render_database_backup_files_history_drop_in() {
     deploy/systemd/genarrative-database-backup-files-history.conf
 }
 
+render_database_backup_files_minimal_drop_in() {
+  local current_escaped env_escaped work_dir_escaped
+  current_escaped="$(escape_sed_replacement "${CURRENT_LINK}")"
+  env_escaped="$(escape_sed_replacement "${API_ENV_FILE}")"
+  work_dir_escaped="$(escape_sed_replacement "${DATABASE_BACKUP_FILES_MINIMAL_WORK_DIR}")"
+  sed \
+    -e "s|/opt/genarrative/current|${current_escaped}|g" \
+    -e "s|/etc/genarrative/api-server.env|${env_escaped}|g" \
+    -e "s|/var/lib/genarrative/database-backups/files-minimal|${work_dir_escaped}|g" \
+    deploy/systemd/genarrative-database-backup-files-minimal.conf
+}
+
 configure_database_backup_profile() {
   local rendered_drop_in
 
   if [[ "${DATABASE_BACKUP_PROFILE}" == "archive-full" ]]; then
     echo "[server-provision] 数据库备份 profile=archive-full，保留主 service 的全量冷备行为。"
-    run_cmd rm -f "${DATABASE_BACKUP_FILES_HISTORY_DROP_IN}" "${DATABASE_BACKUP_LEGACY_DEV_DROP_IN}"
+    run_cmd rm -f "${DATABASE_BACKUP_FILES_HISTORY_DROP_IN}" "${DATABASE_BACKUP_FILES_MINIMAL_DROP_IN}" "${DATABASE_BACKUP_LEGACY_DEV_DROP_IN}"
+    return
+  fi
+
+  if [[ "${DATABASE_BACKUP_PROFILE}" == "files-minimal" ]]; then
+    configure_database_backup_files_minimal_profile
     return
   fi
 
@@ -1350,13 +1369,26 @@ configure_database_backup_profile() {
 
   run_cmd install -d -o genarrative -g genarrative -m 0750 "${DATABASE_BACKUP_FILES_HISTORY_WORK_DIR}"
   run_cmd install -d -o root -g root -m 0755 "${DATABASE_BACKUP_FILES_HISTORY_DROP_IN_DIR}"
-  run_cmd rm -f "${DATABASE_BACKUP_LEGACY_DEV_DROP_IN}"
+  run_cmd rm -f "${DATABASE_BACKUP_FILES_MINIMAL_DROP_IN}" "${DATABASE_BACKUP_LEGACY_DEV_DROP_IN}"
   rendered_drop_in="$(mktemp)"
   render_database_backup_files_history_drop_in >"${rendered_drop_in}"
   install_file "${rendered_drop_in}" "${DATABASE_BACKUP_FILES_HISTORY_DROP_IN}" 0644
   rm -f "${rendered_drop_in}"
 }
 
+configure_database_backup_files_minimal_profile() {
+  local rendered_drop_in
+
+  echo "[server-provision] 数据库备份 profile=files-minimal，只保留最近 snapshot 与其后 commitlog（热备、不停服）。"
+  run_cmd install -d -o genarrative -g genarrative -m 0750 "${DATABASE_BACKUP_FILES_MINIMAL_WORK_DIR}"
+  run_cmd install -d -o root -g root -m 0755 "${DATABASE_BACKUP_FILES_HISTORY_DROP_IN_DIR}"
+  run_cmd rm -f "${DATABASE_BACKUP_FILES_HISTORY_DROP_IN}" "${DATABASE_BACKUP_LEGACY_DEV_DROP_IN}"
+  rendered_drop_in="$(mktemp)"
+  render_database_backup_files_minimal_drop_in >"${rendered_drop_in}"
+  install_file "${rendered_drop_in}" "${DATABASE_BACKUP_FILES_MINIMAL_DROP_IN}" 0644
+  rm -f "${rendered_drop_in}"
+}
+
 render_health_patrol_service() {
   local current_escaped
   current_escaped="$(escape_sed_replacement "${CURRENT_LINK}")"
@@ -1372,6 +1404,7 @@ require_path deploy/systemd/genarrative-external-generation-controller.service
 require_path deploy/systemd/genarrative-bgfilter-worker.service
 require_path deploy/systemd/genarrative-database-backup.service
 require_path deploy/systemd/genarrative-database-backup-files-history.conf
+require_path deploy/systemd/genarrative-database-backup-files-minimal.conf
 require_path deploy/systemd/genarrative-database-backup.timer
 require_path deploy/systemd/genarrative-health-patrol.service
 require_path deploy/systemd/genarrative-health-patrol.timer