From 8531a9af3e449b9d107d76ccf6b8239c9cccbff8 Mon Sep 17 00:00:00 2001
From: menghao <mh18530625731@163.com>
Date: Fri, 31 Jul 2026 15:13:18 +0800
Subject: [PATCH 01/27] =?UTF-8?q?=E5=AE=9E=E7=8E=B0=E8=B5=84=E6=BA=90?=
 =?UTF-8?q?=E4=BE=9D=E8=B5=96=E5=85=B3=E7=B3=BB=E5=9B=BE=E5=B1=82?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

新增资源依赖图模型、去重、环检测与上下游查询。

使用原生 SVG 渲染资源引用和聚合任务流，并接入搜索、高亮、拖动及生命周期清理。

修复资源自引用连线被卡片遮挡的问题。

补充前端回归测试并同步工作台 PRD、技术方案和决策记录。
---
 apps/ai-game-creator-shell/src/styles.css     |  77 +++-
 .../ResourceDependencyOverlay.tsx             | 379 ++++++++++++++++++
 .../src/view/project-development/index.tsx    | 279 ++++++++-----
 .../resourceDependencyGraphModel.ts           | 343 ++++++++++++++++
 .../tests/ResourceDependencyOverlay.test.ts   | 263 ++++++++++++
 .../appSurface/project-development.suite.ts   | 157 ++++++++
 .../resourceDependencyGraphModel.test.ts      | 157 ++++++++
 ...AI游戏创作】项目开发工作台PRD-2026-07-20.md |  43 +-
 .../shared-memory/decision-log.md             |   9 +
 ...�案】AI游戏创作智能体App实施计划-2026-06-24.md |  23 +-
 10 files changed, 1615 insertions(+), 115 deletions(-)
 create mode 100644 apps/ai-game-creator-shell/src/view/project-development/ResourceDependencyOverlay.tsx
 create mode 100644 apps/ai-game-creator-shell/src/view/project-development/resourceDependencyGraphModel.ts
 create mode 100644 apps/ai-game-creator-shell/tests/ResourceDependencyOverlay.test.ts
 create mode 100644 apps/ai-game-creator-shell/tests/resourceDependencyGraphModel.test.ts

diff --git a/apps/ai-game-creator-shell/src/styles.css b/apps/ai-game-creator-shell/src/styles.css
index cafeb314c..f849b43ca 100644
--- a/apps/ai-game-creator-shell/src/styles.css
+++ b/apps/ai-game-creator-shell/src/styles.css
@@ -3871,8 +3871,6 @@ iframe.preview-frame {
 
 .game-resource-canvas {
   position: relative;
-  display: grid;
-  align-content: start;
   flex: 1;
   min-height: 0;
   padding: 12px;
@@ -3882,7 +3880,73 @@ iframe.preview-frame {
   background-size: 18px 18px;
 }
 
+.game-resource-canvas-content {
+  position: relative;
+  display: grid;
+  align-content: start;
+  width: max-content;
+  min-width: 100%;
+  min-height: 100%;
+}
+
+.game-resource-dependency-overlay {
+  position: absolute;
+  inset: 0;
+  z-index: 0;
+  width: 100%;
+  height: 100%;
+  overflow: visible;
+  pointer-events: none;
+}
+
+.game-resource-dependency-edge,
+.game-resource-dependency-edge path {
+  fill: none;
+  vector-effect: non-scaling-stroke;
+  transition:
+    opacity 140ms ease,
+    stroke-width 140ms ease;
+}
+
+.game-resource-dependency-edge--reference {
+  stroke: #d87342;
+  stroke-width: 2px;
+}
+
+.game-resource-dependency-edge--task,
+.game-resource-dependency-edge--task path {
+  stroke: #9d948f;
+  stroke-width: 1.5px;
+  stroke-dasharray: 7 6;
+}
+
+.game-resource-dependency-edge.is-highlighted,
+.game-resource-dependency-edge.is-highlighted path {
+  opacity: 1;
+  stroke-width: 2.8px;
+}
+
+.game-resource-dependency-edge.is-dimmed,
+.game-resource-dependency-edge.is-dimmed path {
+  opacity: 0.14;
+}
+
+.game-resource-dependency-edge.is-cyclic,
+.game-resource-dependency-edge.is-cyclic path {
+  stroke-dashoffset: 4;
+}
+
+.game-resource-dependency-marker--reference path {
+  fill: #d87342;
+}
+
+.game-resource-dependency-marker--task path {
+  fill: #9d948f;
+}
+
 .game-resource-section {
+  position: relative;
+  z-index: 1;
   display: grid;
   gap: 10px;
   min-width: 620px;
@@ -3978,6 +4042,15 @@ iframe.preview-frame {
     0 0 0 2px rgb(213 123 81 / 18%);
 }
 
+.game-resource-card.is-relation-upstream,
+.game-resource-card.is-relation-downstream,
+.game-resource-card.is-relation-both {
+  border-color: #d87342;
+  box-shadow:
+    0 8px 22px rgb(195 105 62 / 18%),
+    0 0 0 2px rgb(216 115 66 / 14%);
+}
+
 .game-resource-card-icon {
   display: grid;
   grid-row: 1 / 4;
diff --git a/apps/ai-game-creator-shell/src/view/project-development/ResourceDependencyOverlay.tsx b/apps/ai-game-creator-shell/src/view/project-development/ResourceDependencyOverlay.tsx
new file mode 100644
index 000000000..e318ad0e4
--- /dev/null
+++ b/apps/ai-game-creator-shell/src/view/project-development/ResourceDependencyOverlay.tsx
@@ -0,0 +1,379 @@
+import { useId, useLayoutEffect, useMemo, useRef, useState } from 'react';
+
+import type {
+  ProjectResourceCanvasPosition,
+  ProjectResourceCanvasSection,
+} from '../../../../../packages/shared/src/contracts/gameCreationApp';
+import {
+  RESOURCE_CANVAS_CARD_HEIGHT,
+  RESOURCE_CANVAS_CARD_WIDTH,
+} from './resourceCanvasLayoutModel';
+import {
+  type ProjectResourceGraph,
+  projectResourceGraphNeighbors,
+  type ProjectResourceReferenceEdge,
+  type ProjectResourceTaskFlow,
+} from './resourceDependencyGraphModel';
+
+type Point = {
+  x: number;
+  y: number;
+};
+
+type Rect = Point & {
+  width: number;
+  height: number;
+};
+
+type SectionOrigins = Partial<Record<ProjectResourceCanvasSection, Point>>;
+
+export type ResourceDependencyOverlayProps = {
+  graph: ProjectResourceGraph;
+  positions: readonly ProjectResourceCanvasPosition[];
+  visibleResourceIds: ReadonlySet<string>;
+  selectedResourceId: string | null;
+};
+
+const SECTION_SELECTOR = '[data-resource-section-plane]';
+const TASK_FLOW_HUB_GAP = 20;
+const SELF_REFERENCE_LOOP_WIDTH = 56;
+const SELF_REFERENCE_LOOP_ANCHOR_OFFSET = 18;
+
+function pointsEqual(left: SectionOrigins, right: SectionOrigins) {
+  const sections: ProjectResourceCanvasSection[] = [
+    'document',
+    'version',
+    'art',
+    'audio',
+  ];
+  return sections.every(
+    (section) =>
+      left[section]?.x === right[section]?.x &&
+      left[section]?.y === right[section]?.y,
+  );
+}
+
+function connectionPath(source: Point, target: Point) {
+  if (source.x === target.x && source.y === target.y) {
+    return `M ${source.x} ${source.y} C ${source.x + 48} ${source.y - 48}, ${
+      source.x + 48
+    } ${source.y + 48}, ${source.x} ${source.y + 1}`;
+  }
+  const direction = target.x >= source.x ? 1 : -1;
+  const bend = Math.max(36, Math.abs(target.x - source.x) * 0.45);
+  return `M ${source.x} ${source.y} C ${source.x + direction * bend} ${
+    source.y
+  }, ${target.x - direction * bend} ${target.y}, ${target.x} ${target.y}`;
+}
+
+function linePath(source: Point, target: Point) {
+  const middleX = (source.x + target.x) / 2;
+  return `M ${source.x} ${source.y} L ${middleX} ${source.y} L ${middleX} ${
+    target.y
+  } L ${target.x} ${target.y}`;
+}
+
+function rectCenter(rect: Rect): Point {
+  return {
+    x: rect.x + rect.width / 2,
+    y: rect.y + rect.height / 2,
+  };
+}
+
+function average(values: readonly number[]) {
+  return values.reduce((sum, value) => sum + value, 0) / values.length;
+}
+
+function rectAnchor(rect: Rect, direction: 1 | -1): Point {
+  return {
+    x: direction === 1 ? rect.x + rect.width : rect.x,
+    y: rect.y + rect.height / 2,
+  };
+}
+
+function referenceGeometry(
+  edge: ProjectResourceReferenceEdge,
+  rectByResourceId: ReadonlyMap<string, Rect>,
+) {
+  const sourceRect = rectByResourceId.get(edge.sourceResourceId);
+  const targetRect = rectByResourceId.get(edge.targetResourceId);
+  if (!sourceRect || !targetRect) {
+    return null;
+  }
+  if (edge.sourceResourceId === edge.targetResourceId) {
+    const anchorX = sourceRect.x + sourceRect.width;
+    const centerY = sourceRect.y + sourceRect.height / 2;
+    const sourceY = centerY + SELF_REFERENCE_LOOP_ANCHOR_OFFSET;
+    const targetY = centerY - SELF_REFERENCE_LOOP_ANCHOR_OFFSET;
+    const loopX = anchorX + SELF_REFERENCE_LOOP_WIDTH;
+    return {
+      path: `M ${anchorX} ${sourceY} C ${loopX} ${sourceY}, ${loopX} ${targetY}, ${anchorX} ${targetY}`,
+      selfLoop: true,
+    };
+  }
+  const sourceCenter = rectCenter(sourceRect);
+  const targetCenter = rectCenter(targetRect);
+  const direction: 1 | -1 = targetCenter.x >= sourceCenter.x ? 1 : -1;
+  const source = rectAnchor(sourceRect, direction);
+  const target = rectAnchor(targetRect, direction === 1 ? -1 : 1);
+  return {
+    path: connectionPath(source, target),
+    selfLoop: false,
+  };
+}
+
+function taskFlowGeometry(
+  flow: ProjectResourceTaskFlow,
+  rectByResourceId: ReadonlyMap<string, Rect>,
+) {
+  const sourceRects = flow.sourceResourceIds.flatMap((resourceId) => {
+    const rect = rectByResourceId.get(resourceId);
+    return rect ? [{ resourceId, rect }] : [];
+  });
+  const targetRects = flow.targetResourceIds.flatMap((resourceId) => {
+    const rect = rectByResourceId.get(resourceId);
+    return rect ? [{ resourceId, rect }] : [];
+  });
+  if (sourceRects.length === 0 || targetRects.length === 0) {
+    return null;
+  }
+  const sourceCenterX = average(
+    sourceRects.map(({ rect }) => rectCenter(rect).x),
+  );
+  const targetCenterX = average(
+    targetRects.map(({ rect }) => rectCenter(rect).x),
+  );
+  const direction: 1 | -1 = targetCenterX >= sourceCenterX ? 1 : -1;
+  const sourceAnchors = sourceRects.map(({ resourceId, rect }) => ({
+    resourceId,
+    point: rectAnchor(rect, direction),
+  }));
+  const targetAnchors = targetRects.map(({ resourceId, rect }) => ({
+    resourceId,
+    point: rectAnchor(rect, direction === 1 ? -1 : 1),
+  }));
+  const sourceHub: Point = {
+    x:
+      (direction === 1
+        ? Math.max(...sourceAnchors.map(({ point }) => point.x))
+        : Math.min(...sourceAnchors.map(({ point }) => point.x))) +
+      direction * TASK_FLOW_HUB_GAP,
+    y: average(sourceAnchors.map(({ point }) => point.y)),
+  };
+  const targetHub: Point = {
+    x:
+      (direction === 1
+        ? Math.min(...targetAnchors.map(({ point }) => point.x))
+        : Math.max(...targetAnchors.map(({ point }) => point.x))) -
+      direction * TASK_FLOW_HUB_GAP,
+    y: average(targetAnchors.map(({ point }) => point.y)),
+  };
+  return { sourceAnchors, targetAnchors, sourceHub, targetHub };
+}
+
+export function ResourceDependencyOverlay({
+  graph,
+  positions,
+  visibleResourceIds,
+  selectedResourceId,
+}: ResourceDependencyOverlayProps) {
+  const markerPrefix = useId().replace(/[^a-zA-Z0-9_-]/gu, '');
+  const overlayRef = useRef<SVGSVGElement>(null);
+  const [sectionOrigins, setSectionOrigins] = useState<SectionOrigins>({});
+
+  useLayoutEffect(() => {
+    const canvas = overlayRef.current?.parentElement;
+    if (!canvas) {
+      return undefined;
+    }
+    let frameId: number | null = null;
+    const measure = () => {
+      frameId = null;
+      const canvasRect = canvas.getBoundingClientRect();
+      const next: SectionOrigins = {};
+      canvas
+        .querySelectorAll<HTMLElement>(SECTION_SELECTOR)
+        .forEach((plane) => {
+          const section = plane.dataset.resourceSectionPlane as
+            | ProjectResourceCanvasSection
+            | undefined;
+          if (!section) {
+            return;
+          }
+          const planeRect = plane.getBoundingClientRect();
+          next[section] = {
+            x: planeRect.left - canvasRect.left,
+            y: planeRect.top - canvasRect.top,
+          };
+        });
+      setSectionOrigins((current) =>
+        pointsEqual(current, next) ? current : next,
+      );
+    };
+    const scheduleMeasure = () => {
+      if (frameId !== null) {
+        return;
+      }
+      frameId = window.requestAnimationFrame(measure);
+    };
+    measure();
+    const ResizeObserverClass = window.ResizeObserver;
+    const observer = ResizeObserverClass
+      ? new ResizeObserverClass(scheduleMeasure)
+      : null;
+    observer?.observe(canvas);
+    canvas
+      .querySelectorAll<HTMLElement>(SECTION_SELECTOR)
+      .forEach((plane) => observer?.observe(plane));
+    window.addEventListener('resize', scheduleMeasure);
+    return () => {
+      if (frameId !== null) {
+        window.cancelAnimationFrame(frameId);
+      }
+      observer?.disconnect();
+      window.removeEventListener('resize', scheduleMeasure);
+    };
+  }, [graph, positions, visibleResourceIds]);
+
+  const rectByResourceId = useMemo(() => {
+    const result = new Map<string, Rect>();
+    for (const position of positions) {
+      if (
+        !graph.resourceIds.has(position.resourceId) ||
+        !visibleResourceIds.has(position.resourceId)
+      ) {
+        continue;
+      }
+      const origin = sectionOrigins[position.section];
+      if (!origin) {
+        continue;
+      }
+      result.set(position.resourceId, {
+        x: origin.x + position.x,
+        y: origin.y + position.y,
+        width: RESOURCE_CANVAS_CARD_WIDTH,
+        height: RESOURCE_CANVAS_CARD_HEIGHT,
+      });
+    }
+    return result;
+  }, [graph.resourceIds, positions, sectionOrigins, visibleResourceIds]);
+
+  const neighbors = useMemo(
+    () => projectResourceGraphNeighbors(graph, selectedResourceId),
+    [graph, selectedResourceId],
+  );
+  const selected = Boolean(
+    selectedResourceId && graph.resourceIds.has(selectedResourceId),
+  );
+
+  return (
+    <svg
+      ref={overlayRef}
+      className="game-resource-dependency-overlay"
+      data-testid="resource-dependency-overlay"
+      aria-hidden="true"
+      focusable="false"
+    >
+      <defs>
+        <marker
+          id={`${markerPrefix}-asset-reference-arrow`}
+          className="game-resource-dependency-marker game-resource-dependency-marker--reference"
+          markerWidth="8"
+          markerHeight="8"
+          refX="7"
+          refY="4"
+          orient="auto"
+          markerUnits="strokeWidth"
+        >
+          <path d="M 0 0 L 8 4 L 0 8 z" />
+        </marker>
+        <marker
+          id={`${markerPrefix}-task-flow-arrow`}
+          className="game-resource-dependency-marker game-resource-dependency-marker--task"
+          markerWidth="8"
+          markerHeight="8"
+          refX="7"
+          refY="4"
+          orient="auto"
+          markerUnits="strokeWidth"
+        >
+          <path d="M 0 0 L 8 4 L 0 8 z" />
+        </marker>
+      </defs>
+
+      {graph.taskFlows.map((flow) => {
+        const geometry = taskFlowGeometry(flow, rectByResourceId);
+        if (!geometry) {
+          return null;
+        }
+        const highlighted = neighbors.connectedEdgeIds.has(flow.id);
+        const className = `game-resource-dependency-edge game-resource-dependency-edge--task${
+          highlighted ? ' is-highlighted' : selected ? ' is-dimmed' : ''
+        }${flow.cyclic ? ' is-cyclic' : ''}`;
+        return (
+          <g
+            key={flow.id}
+            className={className}
+            data-edge-kind="task-flow"
+            data-edge-id={flow.id}
+            data-source-task-id={flow.sourceTaskId}
+            data-target-task-id={flow.targetTaskId}
+            data-cyclic={flow.cyclic || undefined}
+          >
+            <title>{`任务流转：${flow.sourceTaskId} → ${flow.targetTaskId}${
+              flow.cyclic ? '（检测到依赖环）' : ''
+            }`}</title>
+            {geometry.sourceAnchors.map(({ resourceId, point }) => (
+              <path
+                key={`source:${resourceId}`}
+                className="game-resource-dependency-branch"
+                data-resource-id={resourceId}
+                d={linePath(point, geometry.sourceHub)}
+              />
+            ))}
+            <path
+              className="game-resource-dependency-trunk"
+              d={connectionPath(geometry.sourceHub, geometry.targetHub)}
+            />
+            {geometry.targetAnchors.map(({ resourceId, point }) => (
+              <path
+                key={`target:${resourceId}`}
+                className="game-resource-dependency-branch"
+                data-resource-id={resourceId}
+                d={linePath(geometry.targetHub, point)}
+                markerEnd={`url(#${markerPrefix}-task-flow-arrow)`}
+              />
+            ))}
+          </g>
+        );
+      })}
+
+      {graph.referenceEdges.map((edge) => {
+        const geometry = referenceGeometry(edge, rectByResourceId);
+        if (!geometry) {
+          return null;
+        }
+        const highlighted = neighbors.connectedEdgeIds.has(edge.id);
+        const className = `game-resource-dependency-edge game-resource-dependency-edge--reference${
+          highlighted ? ' is-highlighted' : selected ? ' is-dimmed' : ''
+        }${edge.cyclic ? ' is-cyclic' : ''}`;
+        return (
+          <path
+            key={edge.id}
+            className={className}
+            data-edge-kind="asset-reference"
+            data-edge-id={edge.id}
+            data-source-resource-id={edge.sourceResourceId}
+            data-target-resource-id={edge.targetResourceId}
+            data-cyclic={edge.cyclic || undefined}
+            data-self-loop={geometry.selfLoop || undefined}
+            d={geometry.path}
+            markerEnd={`url(#${markerPrefix}-asset-reference-arrow)`}
+          >
+            <title>{`资源引用${edge.cyclic ? '（检测到依赖环）' : ''}`}</title>
+          </path>
+        );
+      })}
+    </svg>
+  );
+}
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 dd5e99492..b391a4a74 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
@@ -46,6 +46,11 @@ import {
   RESOURCE_CANVAS_DRAG_THRESHOLD,
   resourceCanvasSectionExtent,
 } from './resourceCanvasLayoutModel';
+import {
+  createProjectResourceGraph,
+  projectResourceGraphNeighbors,
+} from './resourceDependencyGraphModel';
+import { ResourceDependencyOverlay } from './ResourceDependencyOverlay';
 import { useProjectResourceCanvasLayout } from './useProjectResourceCanvasLayout';
 
 type AttachmentResult = {
@@ -86,6 +91,9 @@ type ProjectResource = {
   mediaType: string;
   sourceLabel: string;
   taskTitle: string | null;
+  producerTaskId: string | null;
+  externalResourceId: string | null;
+  referenceResourceIds: string[];
   dependencies: string[];
   dependencyDepth: number;
   content?: string;
@@ -310,6 +318,9 @@ function resourcesFromProject(
         mediaType: category === 'document' ? '项目文档' : '项目产物',
         sourceLabel: '任务产物',
         taskTitle: task.title,
+        producerTaskId: task.id,
+        externalResourceId: null,
+        referenceResourceIds: [],
         dependencies: task.dependencies,
         dependencyDepth: taskDependencyDepth(task, taskById),
       });
@@ -341,6 +352,9 @@ function resourcesFromProject(
               ? 'Agent 生成'
               : '用户上传',
       taskTitle: task?.title ?? null,
+      producerTaskId: task?.id ?? null,
+      externalResourceId: asset.source.resourceId ?? null,
+      referenceResourceIds: asset.source.referenceResourceIds ?? [],
       dependencies: task?.dependencies ?? [],
       dependencyDepth: task ? taskDependencyDepth(task, taskById) : 0,
     });
@@ -362,6 +376,9 @@ function resourcesFromProject(
       mediaType: attachment.mediaType || '未知媒体类型',
       sourceLabel: '用户上传',
       taskTitle: null,
+      producerTaskId: null,
+      externalResourceId: null,
+      referenceResourceIds: [],
       dependencies: [],
       dependencyDepth: 0,
     });
@@ -377,6 +394,9 @@ function resourcesFromProject(
       mediaType: 'Agent 历史文本回执',
       sourceLabel: `历史成果 · ${result.label}`,
       taskTitle: null,
+      producerTaskId: taskById.has(result.agentId) ? result.agentId : null,
+      externalResourceId: null,
+      referenceResourceIds: [],
       dependencies: [],
       dependencyDepth: 0,
       content: result.content,
@@ -440,6 +460,7 @@ function ResourceCard({
   resource,
   selected,
   dragging,
+  relationState,
   x,
   y,
   onSelect,
@@ -451,6 +472,7 @@ function ResourceCard({
   resource: ProjectResource;
   selected: boolean;
   dragging: boolean;
+  relationState: 'upstream' | 'downstream' | 'both' | null;
   x: number;
   y: number;
   onSelect: () => void;
@@ -465,7 +487,7 @@ function ResourceCard({
       type="button"
       className={`game-resource-card${selected ? ' is-selected' : ''}${
         dragging ? ' is-dragging' : ''
-      }`}
+      }${relationState ? ` is-relation-${relationState}` : ''}`}
       aria-pressed={selected}
       data-resource-id={resource.id}
       title="拖动调整资源位置"
@@ -562,16 +584,45 @@ export default function ProjectDevelopmentView({
   const resourcePositionById = new Map(
     resourceLayout.positions.map((position) => [position.resourceId, position]),
   );
+  const resourceGraph = useMemo(
+    () => createProjectResourceGraph(resources, manifest.tasks),
+    [manifest.tasks, resources],
+  );
+  const selectedResourceNeighbors = useMemo(
+    () => projectResourceGraphNeighbors(resourceGraph, selectedResourceId),
+    [resourceGraph, selectedResourceId],
+  );
   const normalizedSearch = searchText.trim().toLowerCase();
-  const visibleResources = resources.filter((resource) =>
-    normalizedSearch
-      ? [
-          resource.label,
-          resource.path,
-          resource.mediaType,
-          resource.taskTitle ?? '',
-        ].some((value) => value.toLowerCase().includes(normalizedSearch))
-      : true,
+  const visibleResources = useMemo(
+    () =>
+      resources.filter((resource) =>
+        normalizedSearch
+          ? [
+              resource.label,
+              resource.path,
+              resource.mediaType,
+              resource.taskTitle ?? '',
+            ].some((value) => value.toLowerCase().includes(normalizedSearch))
+          : true,
+      ),
+    [normalizedSearch, resources],
+  );
+  const visibleResourceIds = useMemo(
+    () => new Set(visibleResources.map((resource) => resource.id)),
+    [visibleResources],
+  );
+  const resourceDependencyPositions = useMemo(
+    () =>
+      resourceLayout.positions.map((position) =>
+        resourceDragPreview?.resourceId === position.resourceId
+          ? {
+              ...position,
+              x: resourceDragPreview.x,
+              y: resourceDragPreview.y,
+            }
+          : position,
+      ),
+    [resourceDragPreview, resourceLayout.positions],
   );
   const selectedResource =
     resources.find((resource) => resource.id === selectedResourceId) ?? null;
@@ -994,95 +1045,129 @@ export default function ProjectDevelopmentView({
                 }
                 aria-busy={resourceLayoutSaving}
               >
-                {categoryOrder.map((category) => {
-                  const categoryResources = visibleResources.filter(
-                    (resource) => resource.category === category,
-                  );
-                  const categoryPositions = resourceLayout.positions.filter(
-                    (position) => position.section === category,
-                  );
-                  const extent = resourceCanvasSectionExtent(
-                    categoryPositions.map((position) =>
-                      resourceDragPreview?.resourceId === position.resourceId
-                        ? {
-                            ...position,
-                            x: resourceDragPreview.x,
-                            y: resourceDragPreview.y,
-                          }
-                        : position,
-                    ),
-                  );
-                  const Icon = categoryIcons[category];
-                  return (
-                    <section
-                      className="game-resource-section"
-                      aria-label={categoryLabels[category]}
-                      key={category}
-                    >
-                      <header>
-                        <span>
-                          <Icon size={16} aria-hidden="true" />
-                          {categoryLabels[category]}
-                        </span>
-                        <small>{categoryResources.length}</small>
-                      </header>
-                      {categoryResources.length > 0 ? (
-                        <div
-                          className="game-resource-plane"
-                          style={{
-                            width: `${extent.width}px`,
-                            height: `${extent.height}px`,
-                          }}
-                        >
-                          {categoryResources.map((resource) => {
-                            const position = resourcePositionById.get(
-                              resource.id,
-                            );
-                            if (!position) {
-                              return null;
+                <div className="game-resource-canvas-content">
+                  {sortMode === 'dependency' ? (
+                    <ResourceDependencyOverlay
+                      key={`${projectPath}:${manifest.projectId}`}
+                      graph={resourceGraph}
+                      positions={resourceDependencyPositions}
+                      visibleResourceIds={visibleResourceIds}
+                      selectedResourceId={selectedResourceId}
+                    />
+                  ) : null}
+                  {categoryOrder.map((category) => {
+                    const categoryResources = visibleResources.filter(
+                      (resource) => resource.category === category,
+                    );
+                    const categoryPositions = resourceLayout.positions.filter(
+                      (position) => position.section === category,
+                    );
+                    const extent = resourceCanvasSectionExtent(
+                      categoryPositions.map((position) =>
+                        resourceDragPreview?.resourceId === position.resourceId
+                          ? {
+                              ...position,
+                              x: resourceDragPreview.x,
+                              y: resourceDragPreview.y,
                             }
-                            const preview =
-                              resourceDragPreview?.resourceId === resource.id
-                                ? resourceDragPreview
-                                : null;
-                            return (
-                              <ResourceCard
-                                key={resource.id}
-                                resource={resource}
-                                selected={resource.id === selectedResourceId}
-                                dragging={resource.id === draggedResourceId}
-                                x={preview?.x ?? position.x}
-                                y={preview?.y ?? position.y}
-                                onSelect={() => {
-                                  if (
-                                    suppressResourceClickRef.current ===
-                                    resource.id
-                                  ) {
-                                    suppressResourceClickRef.current = null;
-                                    return;
+                          : position,
+                      ),
+                    );
+                    const Icon = categoryIcons[category];
+                    return (
+                      <section
+                        className="game-resource-section"
+                        aria-label={categoryLabels[category]}
+                        key={category}
+                      >
+                        <header>
+                          <span>
+                            <Icon size={16} aria-hidden="true" />
+                            {categoryLabels[category]}
+                          </span>
+                          <small>{categoryResources.length}</small>
+                        </header>
+                        {categoryResources.length > 0 ? (
+                          <div
+                            className="game-resource-plane"
+                            data-resource-section-plane={category}
+                            style={{
+                              width: `${extent.width}px`,
+                              height: `${extent.height}px`,
+                            }}
+                          >
+                            {categoryResources.map((resource) => {
+                              const position = resourcePositionById.get(
+                                resource.id,
+                              );
+                              if (!position) {
+                                return null;
+                              }
+                              const preview =
+                                resourceDragPreview?.resourceId === resource.id
+                                  ? resourceDragPreview
+                                  : null;
+                              const upstream =
+                                sortMode === 'dependency' &&
+                                selectedResourceNeighbors.upstreamResourceIds.has(
+                                  resource.id,
+                                );
+                              const downstream =
+                                sortMode === 'dependency' &&
+                                selectedResourceNeighbors.downstreamResourceIds.has(
+                                  resource.id,
+                                );
+                              const relationState =
+                                upstream && downstream
+                                  ? 'both'
+                                  : upstream
+                                    ? 'upstream'
+                                    : downstream
+                                      ? 'downstream'
+                                      : null;
+                              return (
+                                <ResourceCard
+                                  key={resource.id}
+                                  resource={resource}
+                                  selected={resource.id === selectedResourceId}
+                                  dragging={resource.id === draggedResourceId}
+                                  relationState={relationState}
+                                  x={preview?.x ?? position.x}
+                                  y={preview?.y ?? position.y}
+                                  onSelect={() => {
+                                    if (
+                                      suppressResourceClickRef.current ===
+                                      resource.id
+                                    ) {
+                                      suppressResourceClickRef.current = null;
+                                      return;
+                                    }
+                                    setSelectedResourceId(resource.id);
+                                  }}
+                                  onPointerDown={(event) =>
+                                    handleResourceCardPointerDown(
+                                      event,
+                                      resource,
+                                    )
                                   }
-                                  setSelectedResourceId(resource.id);
-                                }}
-                                onPointerDown={(event) =>
-                                  handleResourceCardPointerDown(event, resource)
-                                }
-                                onPointerMove={handleResourceCardPointerMove}
-                                onPointerUp={(event) =>
-                                  handleResourceCardPointerEnd(event, false)
-                                }
-                                onPointerCancel={(event) =>
-                                  handleResourceCardPointerEnd(event, true)
-                                }
-                              />
-                            );
-                          })}
-                        </div>
-                      ) : (
-                        <p>暂无已登记资源</p>
-                      )}
-                    </section>
-                  );
-                })}
+                                  onPointerMove={handleResourceCardPointerMove}
+                                  onPointerUp={(event) =>
+                                    handleResourceCardPointerEnd(event, false)
+                                  }
+                                  onPointerCancel={(event) =>
+                                    handleResourceCardPointerEnd(event, true)
+                                  }
+                                />
+                              );
+                            })}
+                          </div>
+                        ) : (
+                          <p>暂无已登记资源</p>
+                        )}
+                      </section>
+                    );
+                  })}
+                </div>
               </div>
             </div>
           ) : (
diff --git a/apps/ai-game-creator-shell/src/view/project-development/resourceDependencyGraphModel.ts b/apps/ai-game-creator-shell/src/view/project-development/resourceDependencyGraphModel.ts
new file mode 100644
index 000000000..ea0b5b906
--- /dev/null
+++ b/apps/ai-game-creator-shell/src/view/project-development/resourceDependencyGraphModel.ts
@@ -0,0 +1,343 @@
+export type ProjectResourceGraphNodeInput = {
+  id: string;
+  producerTaskId: string | null;
+  externalResourceId: string | null;
+  referenceResourceIds: readonly string[];
+};
+
+export type ProjectResourceGraphTaskInput = {
+  id: string;
+  dependencies: readonly string[];
+};
+
+export type ProjectResourceReferenceEdge = {
+  id: string;
+  kind: 'asset-reference';
+  sourceResourceId: string;
+  targetResourceId: string;
+  cyclic: boolean;
+};
+
+export type ProjectResourceTaskFlow = {
+  id: string;
+  kind: 'task-flow';
+  sourceTaskId: string;
+  targetTaskId: string;
+  sourceResourceIds: string[];
+  targetResourceIds: string[];
+  cyclic: boolean;
+};
+
+export type ProjectResourceGraph = {
+  resourceIds: ReadonlySet<string>;
+  referenceEdges: ProjectResourceReferenceEdge[];
+  taskFlows: ProjectResourceTaskFlow[];
+  unresolvedReferenceResourceIds: string[];
+  cyclicResourceIds: ReadonlySet<string>;
+  cyclicTaskIds: ReadonlySet<string>;
+};
+
+export type ProjectResourceGraphNeighbors = {
+  upstreamResourceIds: ReadonlySet<string>;
+  downstreamResourceIds: ReadonlySet<string>;
+  connectedEdgeIds: ReadonlySet<string>;
+};
+
+type DirectedEdge = {
+  id: string;
+  sourceId: string;
+  targetId: string;
+};
+
+type CycleAnalysis = {
+  cyclicNodeIds: Set<string>;
+  cyclicEdgeIds: Set<string>;
+};
+
+const emptyStringSet: ReadonlySet<string> = new Set<string>();
+
+export const EMPTY_PROJECT_RESOURCE_GRAPH_NEIGHBORS: ProjectResourceGraphNeighbors =
+  {
+    upstreamResourceIds: emptyStringSet,
+    downstreamResourceIds: emptyStringSet,
+    connectedEdgeIds: emptyStringSet,
+  };
+
+function stableEdgeId(
+  kind: ProjectResourceReferenceEdge['kind'] | ProjectResourceTaskFlow['kind'],
+  sourceId: string,
+  targetId: string,
+) {
+  return `${kind}:${JSON.stringify([sourceId, targetId])}`;
+}
+
+function uniqueSorted(values: Iterable<string>) {
+  return Array.from(new Set(values)).sort((left, right) =>
+    left < right ? -1 : left > right ? 1 : 0,
+  );
+}
+
+function analyzeDirectedCycles(
+  nodeIds: Iterable<string>,
+  edges: readonly DirectedEdge[],
+): CycleAnalysis {
+  const nodes = new Set(nodeIds);
+  for (const edge of edges) {
+    nodes.add(edge.sourceId);
+    nodes.add(edge.targetId);
+  }
+  const adjacency = new Map<string, string[]>();
+  const reverseAdjacency = new Map<string, string[]>();
+  for (const nodeId of nodes) {
+    adjacency.set(nodeId, []);
+    reverseAdjacency.set(nodeId, []);
+  }
+  for (const edge of edges) {
+    adjacency.get(edge.sourceId)?.push(edge.targetId);
+    reverseAdjacency.get(edge.targetId)?.push(edge.sourceId);
+  }
+
+  const visited = new Set<string>();
+  const finishOrder: string[] = [];
+  for (const root of nodes) {
+    if (visited.has(root)) {
+      continue;
+    }
+    visited.add(root);
+    const stack: Array<{ nodeId: string; nextIndex: number }> = [
+      { nodeId: root, nextIndex: 0 },
+    ];
+    while (stack.length > 0) {
+      const frame = stack[stack.length - 1];
+      if (!frame) {
+        break;
+      }
+      const neighbors = adjacency.get(frame.nodeId) ?? [];
+      const next = neighbors[frame.nextIndex];
+      if (next === undefined) {
+        finishOrder.push(frame.nodeId);
+        stack.pop();
+        continue;
+      }
+      frame.nextIndex += 1;
+      if (!visited.has(next)) {
+        visited.add(next);
+        stack.push({ nodeId: next, nextIndex: 0 });
+      }
+    }
+  }
+
+  const componentByNode = new Map<string, number>();
+  const componentSizes: number[] = [];
+  for (let index = finishOrder.length - 1; index >= 0; index -= 1) {
+    const root = finishOrder[index];
+    if (root === undefined || componentByNode.has(root)) {
+      continue;
+    }
+    const componentId = componentSizes.length;
+    let size = 0;
+    const stack = [root];
+    componentByNode.set(root, componentId);
+    while (stack.length > 0) {
+      const nodeId = stack.pop();
+      if (nodeId === undefined) {
+        continue;
+      }
+      size += 1;
+      for (const neighbor of reverseAdjacency.get(nodeId) ?? []) {
+        if (!componentByNode.has(neighbor)) {
+          componentByNode.set(neighbor, componentId);
+          stack.push(neighbor);
+        }
+      }
+    }
+    componentSizes.push(size);
+  }
+
+  const cyclicNodeIds = new Set<string>();
+  const cyclicEdgeIds = new Set<string>();
+  for (const edge of edges) {
+    const sourceComponent = componentByNode.get(edge.sourceId);
+    const targetComponent = componentByNode.get(edge.targetId);
+    if (
+      sourceComponent !== undefined &&
+      sourceComponent === targetComponent &&
+      ((componentSizes[sourceComponent] ?? 0) > 1 ||
+        edge.sourceId === edge.targetId)
+    ) {
+      cyclicNodeIds.add(edge.sourceId);
+      cyclicNodeIds.add(edge.targetId);
+      cyclicEdgeIds.add(edge.id);
+    }
+  }
+  return { cyclicNodeIds, cyclicEdgeIds };
+}
+
+export function createProjectResourceGraph(
+  resources: readonly ProjectResourceGraphNodeInput[],
+  tasks: readonly ProjectResourceGraphTaskInput[],
+): ProjectResourceGraph {
+  const resourceById = new Map(
+    resources.map((resource) => [resource.id, resource]),
+  );
+  const resourcesByTask = new Map<string, string[]>();
+  const resourcesByExternalId = new Map<string, string[]>();
+  for (const resource of resources) {
+    if (resource.producerTaskId) {
+      const taskResources = resourcesByTask.get(resource.producerTaskId) ?? [];
+      taskResources.push(resource.id);
+      resourcesByTask.set(resource.producerTaskId, taskResources);
+    }
+    if (resource.externalResourceId) {
+      const externalResources =
+        resourcesByExternalId.get(resource.externalResourceId) ?? [];
+      externalResources.push(resource.id);
+      resourcesByExternalId.set(resource.externalResourceId, externalResources);
+    }
+  }
+  for (const [taskId, resourceIds] of resourcesByTask) {
+    resourcesByTask.set(taskId, uniqueSorted(resourceIds));
+  }
+
+  const unresolvedReferenceResourceIds = new Set<string>();
+  const referenceEdgeById = new Map<string, ProjectResourceReferenceEdge>();
+  for (const target of resources) {
+    for (const externalReferenceId of new Set(target.referenceResourceIds)) {
+      const sourceCandidates =
+        resourcesByExternalId.get(externalReferenceId) ?? [];
+      if (sourceCandidates.length !== 1) {
+        unresolvedReferenceResourceIds.add(externalReferenceId);
+        continue;
+      }
+      const sourceResourceId = sourceCandidates[0];
+      if (sourceResourceId === undefined) {
+        unresolvedReferenceResourceIds.add(externalReferenceId);
+        continue;
+      }
+      if (!resourceById.has(sourceResourceId) || !resourceById.has(target.id)) {
+        continue;
+      }
+      const id = stableEdgeId('asset-reference', sourceResourceId, target.id);
+      referenceEdgeById.set(id, {
+        id,
+        kind: 'asset-reference',
+        sourceResourceId,
+        targetResourceId: target.id,
+        cyclic: false,
+      });
+    }
+  }
+  const referenceEdges = Array.from(referenceEdgeById.values()).sort(
+    (left, right) => left.id.localeCompare(right.id),
+  );
+  const referenceCycles = analyzeDirectedCycles(
+    resourceById.keys(),
+    referenceEdges.map((edge) => ({
+      id: edge.id,
+      sourceId: edge.sourceResourceId,
+      targetId: edge.targetResourceId,
+    })),
+  );
+  for (const edge of referenceEdges) {
+    edge.cyclic = referenceCycles.cyclicEdgeIds.has(edge.id);
+  }
+
+  const taskById = new Map(tasks.map((task) => [task.id, task]));
+  const taskDependencyEdges: DirectedEdge[] = [];
+  for (const targetTask of tasks) {
+    for (const sourceTaskId of new Set(targetTask.dependencies)) {
+      if (!taskById.has(sourceTaskId)) {
+        continue;
+      }
+      taskDependencyEdges.push({
+        id: stableEdgeId('task-flow', sourceTaskId, targetTask.id),
+        sourceId: sourceTaskId,
+        targetId: targetTask.id,
+      });
+    }
+  }
+  const taskCycles = analyzeDirectedCycles(
+    taskById.keys(),
+    taskDependencyEdges,
+  );
+  const taskFlowById = new Map<string, ProjectResourceTaskFlow>();
+  for (const targetTask of tasks) {
+    const targetResourceIds = resourcesByTask.get(targetTask.id) ?? [];
+    if (targetResourceIds.length === 0) {
+      continue;
+    }
+    for (const sourceTaskId of new Set(targetTask.dependencies)) {
+      if (!taskById.has(sourceTaskId)) {
+        continue;
+      }
+      const sourceResourceIds = resourcesByTask.get(sourceTaskId) ?? [];
+      if (sourceResourceIds.length === 0) {
+        continue;
+      }
+      const id = stableEdgeId('task-flow', sourceTaskId, targetTask.id);
+      taskFlowById.set(id, {
+        id,
+        kind: 'task-flow',
+        sourceTaskId,
+        targetTaskId: targetTask.id,
+        sourceResourceIds,
+        targetResourceIds,
+        cyclic: false,
+      });
+    }
+  }
+  const taskFlows = Array.from(taskFlowById.values()).sort((left, right) =>
+    left.id.localeCompare(right.id),
+  );
+  for (const flow of taskFlows) {
+    flow.cyclic = taskCycles.cyclicEdgeIds.has(flow.id);
+  }
+
+  return {
+    resourceIds: new Set(resourceById.keys()),
+    referenceEdges,
+    taskFlows,
+    unresolvedReferenceResourceIds: uniqueSorted(
+      unresolvedReferenceResourceIds,
+    ),
+    cyclicResourceIds: referenceCycles.cyclicNodeIds,
+    cyclicTaskIds: taskCycles.cyclicNodeIds,
+  };
+}
+
+export function projectResourceGraphNeighbors(
+  graph: ProjectResourceGraph,
+  resourceId: string | null,
+): ProjectResourceGraphNeighbors {
+  if (!resourceId || !graph.resourceIds.has(resourceId)) {
+    return EMPTY_PROJECT_RESOURCE_GRAPH_NEIGHBORS;
+  }
+  const upstreamResourceIds = new Set<string>();
+  const downstreamResourceIds = new Set<string>();
+  const connectedEdgeIds = new Set<string>();
+
+  for (const edge of graph.referenceEdges) {
+    if (edge.targetResourceId === resourceId) {
+      upstreamResourceIds.add(edge.sourceResourceId);
+      connectedEdgeIds.add(edge.id);
+    }
+    if (edge.sourceResourceId === resourceId) {
+      downstreamResourceIds.add(edge.targetResourceId);
+      connectedEdgeIds.add(edge.id);
+    }
+  }
+  for (const flow of graph.taskFlows) {
+    if (flow.targetResourceIds.includes(resourceId)) {
+      flow.sourceResourceIds.forEach((id) => upstreamResourceIds.add(id));
+      connectedEdgeIds.add(flow.id);
+    }
+    if (flow.sourceResourceIds.includes(resourceId)) {
+      flow.targetResourceIds.forEach((id) => downstreamResourceIds.add(id));
+      connectedEdgeIds.add(flow.id);
+    }
+  }
+
+  upstreamResourceIds.delete(resourceId);
+  downstreamResourceIds.delete(resourceId);
+  return { upstreamResourceIds, downstreamResourceIds, connectedEdgeIds };
+}
diff --git a/apps/ai-game-creator-shell/tests/ResourceDependencyOverlay.test.ts b/apps/ai-game-creator-shell/tests/ResourceDependencyOverlay.test.ts
new file mode 100644
index 000000000..2f56beff8
--- /dev/null
+++ b/apps/ai-game-creator-shell/tests/ResourceDependencyOverlay.test.ts
@@ -0,0 +1,263 @@
+/** @vitest-environment jsdom */
+import { render, screen, waitFor } from '@testing-library/react';
+import React from 'react';
+import { describe, expect, it, vi } from 'vitest';
+
+import type { ProjectResourceCanvasPosition } from '../../../packages/shared/src/contracts/gameCreationApp';
+import {
+  createProjectResourceGraph,
+  type ProjectResourceGraph,
+} from '../src/view/project-development/resourceDependencyGraphModel';
+import { ResourceDependencyOverlay } from '../src/view/project-development/ResourceDependencyOverlay';
+
+function position(
+  resourceId: string,
+  x: number,
+  y: number,
+): ProjectResourceCanvasPosition {
+  return {
+    resourceId,
+    section: 'art',
+    x,
+    y,
+    manuallyPlaced: false,
+  };
+}
+
+function graphFixture() {
+  return createProjectResourceGraph(
+    [
+      {
+        id: 'source:one',
+        producerTaskId: 'source-task',
+        externalResourceId: 'external-source',
+        referenceResourceIds: [],
+      },
+      ...['source:two', 'source:three'].map((id) => ({
+        id,
+        producerTaskId: 'source-task',
+        externalResourceId: null,
+        referenceResourceIds: [],
+      })),
+      {
+        id: 'target:one',
+        producerTaskId: 'target-task',
+        externalResourceId: null,
+        referenceResourceIds: ['external-source'],
+      },
+      ...['target:two', 'target:three'].map((id) => ({
+        id,
+        producerTaskId: 'target-task',
+        externalResourceId: null,
+        referenceResourceIds: [],
+      })),
+      {
+        id: 'unrelated',
+        producerTaskId: 'unrelated-task',
+        externalResourceId: 'external-unrelated',
+        referenceResourceIds: ['external-unrelated'],
+      },
+    ],
+    [
+      { id: 'source-task', dependencies: [] },
+      { id: 'target-task', dependencies: ['source-task'] },
+      { id: 'unrelated-task', dependencies: [] },
+    ],
+  );
+}
+
+function OverlayHarness({
+  graph,
+  positions,
+  visibleResourceIds,
+  selectedResourceId = null,
+}: {
+  graph: ProjectResourceGraph;
+  positions: ProjectResourceCanvasPosition[];
+  visibleResourceIds: ReadonlySet<string>;
+  selectedResourceId?: string | null;
+}) {
+  return React.createElement(
+    'div',
+    null,
+    React.createElement('div', { 'data-resource-section-plane': 'art' }),
+    React.createElement(ResourceDependencyOverlay, {
+      graph,
+      positions,
+      visibleResourceIds,
+      selectedResourceId,
+    }),
+  );
+}
+
+function overlayView(
+  graph: ProjectResourceGraph,
+  positions: ProjectResourceCanvasPosition[],
+  visibleResourceIds: ReadonlySet<string>,
+  selectedResourceId: string | null = null,
+) {
+  return React.createElement(OverlayHarness, {
+    graph,
+    positions,
+    visibleResourceIds,
+    selectedResourceId,
+  });
+}
+
+describe('ResourceDependencyOverlay', () => {
+  it('renders exact references and one aggregated task trunk without cartesian paths', async () => {
+    const graph = graphFixture();
+    const positions = Array.from(graph.resourceIds).map((resourceId, index) =>
+      position(resourceId, (index % 3) * 220, Math.floor(index / 3) * 120),
+    );
+    render(overlayView(graph, positions, new Set(graph.resourceIds)));
+
+    const overlay = await screen.findByTestId('resource-dependency-overlay');
+    await waitFor(() =>
+      expect(
+        overlay.querySelectorAll('[data-edge-kind="asset-reference"]'),
+      ).toHaveLength(2),
+    );
+    const taskFlow = overlay.querySelector('[data-edge-kind="task-flow"]');
+    expect(taskFlow).not.toBeNull();
+    expect(taskFlow?.querySelectorAll('path')).toHaveLength(7);
+    expect(taskFlow?.querySelectorAll('path[marker-end]')).toHaveLength(3);
+  });
+
+  it('filters hidden endpoints and updates path geometry when positions change', async () => {
+    const graph = graphFixture();
+    const positions = [
+      position('source:one', 0, 0),
+      position('target:one', 240, 0),
+    ];
+    const view = render(
+      overlayView(graph, positions, new Set(['source:one', 'target:one'])),
+    );
+    const overlay = await screen.findByTestId('resource-dependency-overlay');
+    const firstPath = await waitFor(() => {
+      const path = overlay.querySelector<SVGPathElement>(
+        '[data-edge-kind="asset-reference"]',
+      );
+      expect(path).not.toBeNull();
+      return path?.getAttribute('d');
+    });
+
+    view.rerender(
+      overlayView(
+        graph,
+        [position('source:one', 80, 40), position('target:one', 240, 0)],
+        new Set(['source:one', 'target:one']),
+      ),
+    );
+    await waitFor(() =>
+      expect(
+        overlay
+          .querySelector('[data-edge-kind="asset-reference"]')
+          ?.getAttribute('d'),
+      ).not.toBe(firstPath),
+    );
+
+    view.rerender(overlayView(graph, positions, new Set(['target:one'])));
+    await waitFor(() =>
+      expect(
+        overlay.querySelector('[data-edge-kind="asset-reference"]'),
+      ).toBeNull(),
+    );
+  });
+
+  it('routes a cyclic self-reference outside the resource card and moves it with the card', async () => {
+    const graph = graphFixture();
+    const view = render(
+      overlayView(
+        graph,
+        [position('unrelated', 24, 32)],
+        new Set(['unrelated']),
+      ),
+    );
+    const overlay = await screen.findByTestId('resource-dependency-overlay');
+    const selfLoopSelector =
+      '[data-edge-kind="asset-reference"]' +
+      '[data-source-resource-id="unrelated"]' +
+      '[data-target-resource-id="unrelated"]';
+    const selfLoop = await waitFor(() => {
+      const path = overlay.querySelector<SVGPathElement>(selfLoopSelector);
+      expect(path).not.toBeNull();
+      return path as SVGPathElement;
+    });
+
+    expect(selfLoop.getAttribute('data-cyclic')).toBe('true');
+    expect(selfLoop.getAttribute('data-self-loop')).toBe('true');
+    expect(selfLoop.getAttribute('d')).toBe(
+      'M 204 96 C 260 96, 260 60, 204 60',
+    );
+    expect(selfLoop.getAttribute('marker-end')).toContain(
+      'asset-reference-arrow',
+    );
+
+    view.rerender(
+      overlayView(
+        graph,
+        [position('unrelated', 84, 48)],
+        new Set(['unrelated']),
+      ),
+    );
+    await waitFor(() =>
+      expect(selfLoop.getAttribute('d')).toBe(
+        'M 264 112 C 320 112, 320 76, 264 76',
+      ),
+    );
+  });
+
+  it('highlights direct edges and dims unrelated cyclic edges for a selection', async () => {
+    const graph = graphFixture();
+    const positions = Array.from(graph.resourceIds).map((resourceId, index) =>
+      position(resourceId, index * 200, 0),
+    );
+    render(
+      overlayView(graph, positions, new Set(graph.resourceIds), 'target:one'),
+    );
+    const overlay = await screen.findByTestId('resource-dependency-overlay');
+    await waitFor(() =>
+      expect(
+        overlay.querySelectorAll('.is-highlighted').length,
+      ).toBeGreaterThan(0),
+    );
+    const unrelated = Array.from(
+      overlay.querySelectorAll<SVGElement>(
+        '[data-edge-kind="asset-reference"]',
+      ),
+    ).find((edge) => edge.getAttribute('data-cyclic') === 'true');
+    expect(unrelated?.classList.contains('is-dimmed')).toBe(true);
+  });
+
+  it('disconnects layout observers when the SVG layer is destroyed', () => {
+    const observe = vi.fn();
+    const disconnect = vi.fn();
+    class TestResizeObserver {
+      constructor(_callback: ResizeObserverCallback) {}
+
+      observe = observe;
+      unobserve = vi.fn();
+      disconnect = disconnect;
+    }
+    vi.stubGlobal('ResizeObserver', TestResizeObserver);
+    try {
+      const graph = graphFixture();
+      const view = render(
+        overlayView(
+          graph,
+          Array.from(graph.resourceIds).map((resourceId, index) =>
+            position(resourceId, index * 200, 0),
+          ),
+          new Set(graph.resourceIds),
+        ),
+      );
+
+      expect(observe).toHaveBeenCalledTimes(2);
+      view.unmount();
+      expect(disconnect).toHaveBeenCalledTimes(1);
+    } finally {
+      vi.unstubAllGlobals();
+    }
+  });
+});
diff --git a/apps/ai-game-creator-shell/tests/appSurface/project-development.suite.ts b/apps/ai-game-creator-shell/tests/appSurface/project-development.suite.ts
index 932dab81c..258b83448 100644
--- a/apps/ai-game-creator-shell/tests/appSurface/project-development.suite.ts
+++ b/apps/ai-game-creator-shell/tests/appSurface/project-development.suite.ts
@@ -359,6 +359,163 @@ export function registerProjectWorkbenchFoundationTests() {
     expect(receiptDialog.querySelector('strong')).not.toBeNull();
   });
 
+  it('renders, filters, highlights, moves, and destroys the resource dependency overlay', async () => {
+    const manifest = createGameCreationAppManifest(
+      'workbench-resource-graph',
+      '资源依赖图测试',
+    );
+    manifest.assets.push(
+      {
+        id: 'dependency-spec',
+        kind: 'design-spec',
+        mediaType: 'application/json',
+        localPath: 'assets/spec-source.json',
+        source: {
+          kind: 'canvas',
+          taskId: 'art-director',
+          resourceId: 'canvas-spec-source',
+        },
+      },
+      {
+        id: 'dependency-ui',
+        kind: 'ui-prototype',
+        mediaType: 'application/json',
+        localPath: 'assets/ui-dependency.json',
+        source: {
+          kind: 'canvas',
+          taskId: 'design-foundation',
+          resourceId: 'canvas-ui-target',
+          referenceResourceIds: ['canvas-spec-source'],
+        },
+      },
+      {
+        id: 'unrelated-cycle',
+        kind: 'metadata',
+        mediaType: 'application/json',
+        localPath: 'assets/unrelated-cycle.json',
+        source: {
+          kind: 'canvas',
+          resourceId: 'canvas-unrelated',
+          referenceResourceIds: ['canvas-unrelated'],
+        },
+      },
+    );
+
+    const view = render(
+      React.createElement(ProjectDevelopmentView, {
+        projectName: '资源依赖图测试',
+        projectPath: '/tmp/workbench-resource-graph',
+        manifest,
+        attachments: [],
+        recentRunStatus: null,
+        recentRunStopReason: null,
+        supervisor: React.createElement('div', null, '项目总控'),
+        onHomeOpen: vi.fn(),
+        onProjectsOpen: vi.fn(),
+      }),
+    );
+
+    let overlay = await screen.findByTestId('resource-dependency-overlay');
+    await waitFor(() => {
+      expect(
+        overlay.querySelectorAll('[data-edge-kind="asset-reference"]'),
+      ).toHaveLength(2);
+      expect(
+        overlay.querySelectorAll('[data-edge-kind="task-flow"]'),
+      ).toHaveLength(1);
+    });
+
+    fireEvent.click(screen.getByRole('button', { name: '按类型' }));
+    expect(screen.queryByTestId('resource-dependency-overlay')).toBeNull();
+    fireEvent.click(screen.getByRole('button', { name: '按依赖' }));
+    overlay = await screen.findByTestId('resource-dependency-overlay');
+
+    const search = screen.getByLabelText('搜索项目资源');
+    fireEvent.change(search, { target: { value: 'ui-dependency' } });
+    await waitFor(() => {
+      expect(overlay.querySelector('[data-edge-kind]')).toBeNull();
+    });
+    fireEvent.change(search, { target: { value: '' } });
+
+    const sourceCard = screen.getByRole('button', {
+      name: /spec-source\.json/,
+    });
+    const targetCard = screen.getByRole('button', {
+      name: /ui-dependency\.json/,
+    });
+    const referenceSelector =
+      '[data-edge-kind="asset-reference"]' +
+      '[data-source-resource-id="asset:dependency-spec"]' +
+      '[data-target-resource-id="asset:dependency-ui"]';
+    const firstPath = await waitFor(() => {
+      const path = overlay.querySelector(referenceSelector);
+      expect(path).not.toBeNull();
+      return path?.getAttribute('d');
+    });
+
+    fireEvent.pointerDown(sourceCard, {
+      pointerId: 27,
+      button: 0,
+      clientX: 0,
+      clientY: 0,
+    });
+    fireEvent.pointerMove(sourceCard, {
+      pointerId: 27,
+      clientX: 72,
+      clientY: 28,
+    });
+    await waitFor(() => {
+      expect(
+        overlay.querySelector(referenceSelector)?.getAttribute('d'),
+      ).not.toBe(firstPath);
+    });
+    fireEvent.pointerUp(sourceCard, {
+      pointerId: 27,
+      clientX: 72,
+      clientY: 28,
+    });
+
+    fireEvent.click(targetCard);
+    await waitFor(() => {
+      expect(sourceCard.classList.contains('is-relation-upstream')).toBe(true);
+      expect(
+        overlay
+          .querySelector(referenceSelector)
+          ?.classList.contains('is-highlighted'),
+      ).toBe(true);
+    });
+    expect(
+      overlay
+        .querySelector('[data-source-resource-id="asset:unrelated-cycle"]')
+        ?.classList.contains('is-dimmed'),
+    ).toBe(true);
+
+    const previousOverlay = overlay;
+    const nextManifest = createGameCreationAppManifest(
+      'workbench-resource-graph-next',
+      '新资源依赖图测试',
+    );
+    view.rerender(
+      React.createElement(ProjectDevelopmentView, {
+        projectName: '新资源依赖图测试',
+        projectPath: '/tmp/workbench-resource-graph-next',
+        manifest: nextManifest,
+        attachments: [],
+        recentRunStatus: null,
+        recentRunStopReason: null,
+        supervisor: React.createElement('div', null, '项目总控'),
+        onHomeOpen: vi.fn(),
+        onProjectsOpen: vi.fn(),
+      }),
+    );
+    const nextOverlay = await screen.findByTestId(
+      'resource-dependency-overlay',
+    );
+    expect(nextOverlay).not.toBe(previousOverlay);
+    expect(previousOverlay.isConnected).toBe(false);
+    expect(nextOverlay.querySelector('[data-edge-kind]')).toBeNull();
+  });
+
   it('persists a resource position with CAS and restores it after remount', async () => {
     const projectId = 'workbench-layout-persistence';
     const projectPath = '/tmp/workbench-layout-persistence';
diff --git a/apps/ai-game-creator-shell/tests/resourceDependencyGraphModel.test.ts b/apps/ai-game-creator-shell/tests/resourceDependencyGraphModel.test.ts
new file mode 100644
index 000000000..18b526081
--- /dev/null
+++ b/apps/ai-game-creator-shell/tests/resourceDependencyGraphModel.test.ts
@@ -0,0 +1,157 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  createProjectResourceGraph,
+  projectResourceGraphNeighbors,
+  type ProjectResourceGraphNodeInput,
+} from '../src/view/project-development/resourceDependencyGraphModel';
+
+function resource(
+  id: string,
+  producerTaskId: string | null,
+  options: Partial<ProjectResourceGraphNodeInput> = {},
+): ProjectResourceGraphNodeInput {
+  return {
+    id,
+    producerTaskId,
+    externalResourceId: null,
+    referenceResourceIds: [],
+    ...options,
+  };
+}
+
+describe('resource dependency graph model', () => {
+  it('maps exact external asset references, deduplicates them, and filters missing resources', () => {
+    const graph = createProjectResourceGraph(
+      [
+        resource('asset:spec', 'art-director', {
+          externalResourceId: 'canvas-resource-spec',
+        }),
+        resource('asset:ui', 'design-foundation', {
+          externalResourceId: 'canvas-resource-ui',
+          referenceResourceIds: [
+            'canvas-resource-spec',
+            'canvas-resource-spec',
+            'missing-resource',
+          ],
+        }),
+      ],
+      [
+        { id: 'art-director', dependencies: [] },
+        { id: 'design-foundation', dependencies: ['art-director'] },
+      ],
+    );
+
+    expect(graph.referenceEdges).toEqual([
+      expect.objectContaining({
+        kind: 'asset-reference',
+        sourceResourceId: 'asset:spec',
+        targetResourceId: 'asset:ui',
+        cyclic: false,
+      }),
+    ]);
+    expect(graph.unresolvedReferenceResourceIds).toEqual(['missing-resource']);
+  });
+
+  it('aggregates each task dependency into one flow instead of a resource cartesian product', () => {
+    const graph = createProjectResourceGraph(
+      [
+        resource('upstream:a', 'task-a'),
+        resource('upstream:b', 'task-a'),
+        resource('downstream:a', 'task-b'),
+        resource('downstream:b', 'task-b'),
+        resource('downstream:c', 'task-b'),
+      ],
+      [
+        { id: 'task-a', dependencies: [] },
+        { id: 'task-b', dependencies: ['task-a', 'task-a'] },
+      ],
+    );
+
+    expect(graph.taskFlows).toHaveLength(1);
+    expect(graph.taskFlows[0]).toMatchObject({
+      sourceTaskId: 'task-a',
+      targetTaskId: 'task-b',
+      sourceResourceIds: ['upstream:a', 'upstream:b'],
+      targetResourceIds: ['downstream:a', 'downstream:b', 'downstream:c'],
+    });
+  });
+
+  it('detects resource and task dependency cycles without recursive traversal', () => {
+    const graph = createProjectResourceGraph(
+      [
+        resource('asset:a', 'task-a', {
+          externalResourceId: 'external-a',
+          referenceResourceIds: ['external-b'],
+        }),
+        resource('asset:b', 'task-b', {
+          externalResourceId: 'external-b',
+          referenceResourceIds: ['external-a'],
+        }),
+      ],
+      [
+        { id: 'task-a', dependencies: ['task-b'] },
+        { id: 'task-b', dependencies: ['task-a'] },
+      ],
+    );
+
+    expect(graph.cyclicResourceIds).toEqual(new Set(['asset:a', 'asset:b']));
+    expect(graph.referenceEdges.every((edge) => edge.cyclic)).toBe(true);
+    expect(graph.cyclicTaskIds).toEqual(new Set(['task-a', 'task-b']));
+    expect(graph.taskFlows.every((flow) => flow.cyclic)).toBe(true);
+  });
+
+  it('detects task cycles even when a cyclic task has no resource card', () => {
+    const graph = createProjectResourceGraph(
+      [resource('asset:a', 'task-a')],
+      [
+        { id: 'task-a', dependencies: ['task-b'] },
+        { id: 'task-b', dependencies: ['task-a'] },
+      ],
+    );
+
+    expect(graph.taskFlows).toHaveLength(0);
+    expect(graph.cyclicTaskIds).toEqual(new Set(['task-a', 'task-b']));
+  });
+
+  it('returns direct upstream and downstream resources for exact and aggregated edges', () => {
+    const graph = createProjectResourceGraph(
+      [
+        resource('task-a:one', 'task-a', {
+          externalResourceId: 'external-a',
+        }),
+        resource('task-a:two', 'task-a'),
+        resource('task-b:one', 'task-b', {
+          referenceResourceIds: ['external-a'],
+        }),
+      ],
+      [
+        { id: 'task-a', dependencies: [] },
+        { id: 'task-b', dependencies: ['task-a'] },
+      ],
+    );
+
+    const neighbors = projectResourceGraphNeighbors(graph, 'task-b:one');
+    expect(neighbors.upstreamResourceIds).toEqual(
+      new Set(['task-a:one', 'task-a:two']),
+    );
+    expect(neighbors.downstreamResourceIds).toEqual(new Set());
+    expect(neighbors.connectedEdgeIds.size).toBe(2);
+  });
+
+  it('keeps graph construction linear for the supported resource bound', () => {
+    const resources = Array.from({ length: 4096 }, (_, index) =>
+      resource(`resource:${index}`, `task:${index}`),
+    );
+    const tasks = Array.from({ length: 4096 }, (_, index) => ({
+      id: `task:${index}`,
+      dependencies: index === 0 ? [] : [`task:${index - 1}`],
+    }));
+    const startedAt = performance.now();
+    const graph = createProjectResourceGraph(resources, tasks);
+    const elapsedMs = performance.now() - startedAt;
+
+    expect(graph.taskFlows).toHaveLength(4095);
+    expect(elapsedMs).toBeLessThan(2000);
+  });
+});
diff --git a/docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md b/docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md
index 11a3771c3..7e18fc25f 100644
--- a/docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md
+++ b/docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md
@@ -1,6 +1,6 @@
 # AI 游戏创作项目开发工作台 PRD
 
-更新时间：`2026-07-28`
+更新时间：`2026-07-31`
 
 ## 1. 产品定位
 
@@ -58,14 +58,14 @@
 
 现有六个专业组为：
 
-| group | 普通用户名称 | 当前职责 |
-| --- | --- | --- |
-| `design` | 策划组 | 玩法规格、界面原型、规则与验收口径 |
-| `art` | 美术组 | 角色、场景、UI、动画和美术素材 |
-| `code` | 程序组 | 可运行原型、模块实现和工程验证 |
-| `balance` | 数值组 | 速度、生命、得分和难度参数 |
-| `audio` | 音频组 | 背景音乐、音效和音频资源 |
-| `publishing` | 发布组 | 质量评审、试玩、打包和发布准备 |
+| group        | 普通用户名称 | 当前职责                           |
+| ------------ | ------------ | ---------------------------------- |
+| `design`     | 策划组       | 玩法规格、界面原型、规则与验收口径 |
+| `art`        | 美术组       | 角色、场景、UI、动画和美术素材     |
+| `code`       | 程序组       | 可运行原型、模块实现和工程验证     |
+| `balance`    | 数值组       | 速度、生命、得分和难度参数         |
+| `audio`      | 音频组       | 背景音乐、音效和音频资源           |
+| `publishing` | 发布组       | 质量评审、试玩、打包和发布准备     |
 
 - 底栏默认突出策划、美术、程序三组。
 - 允许在同一底栏展开数值、音频、发布组，不删除既有专业组。
@@ -153,7 +153,7 @@ P0 中 `approvalMode` 只能有效写入 `strict`；其它值只能作为不可
 
 ### 5.2 资源画布布局（P1）
 
-实现状态（2026-07-28）：本节布局合同已在独立客户端落地，dependency / type 双模式通过项目内 CAS sidecar 独立持久化；关系线、资源替换、缩放 / 平移等其余 P1 能力仍按本文非目标保持未实现。
+实现状态（2026-07-31）：本节布局合同已在独立客户端落地，dependency / type 双模式通过项目内 CAS sidecar 独立持久化；dependency 模式的前端资源依赖关系图层也已落地，但不写入布局 sidecar。资源替换、缩放 / 平移等其余 P1 能力仍按本文非目标保持未实现。
 
 ```ts
 type ProjectResourceCanvasLayout = {
@@ -247,6 +247,18 @@ type UpdateProjectResourceCanvasLayoutResult =
 - CAS 冲突时直接载入返回的最新布局并提示“布局已在其他窗口更新，请重新拖动”，丢弃所有基于冲突前快照排队的手动拖动，不得自动重放本地旧坐标或静默覆盖另一窗口结果。即使当前在途请求是允许自动重试的资源协调，只要本次冲突实际清除了任何排队手动拖动，也必须按当前 scope 保留重新拖动提示；后续资源协调成功、失败或通用提示定时器都不得静默清除，只有新的手动布局成功保存或切换 scope 才能解除。资源自动协调可以基于冲突返回的新 revision 有界重试，单次资源签名最多追加 `2` 次，持续跨窗口写入时不得无限自旋。
 - 缺少 Tauri bridge 的浏览器开发态可以保留当前会话内布局用于界面测试，但不得宣称已经持久保存。
 
+#### 5.2.5 资源依赖关系图层
+
+- 图层只在 dependency 模式挂载；type 模式不得渲染 SVG、连线或 marker。切换 mode、切换项目或卸载工作台时必须销毁旧图层，并清理尺寸观察和窗口事件监听。
+- 输入固定为当前资源投影的全部卡片坐标与前端 `ProjectResourceGraph`；输出使用原生 SVG 的 path 和箭头 marker。SVG 叠加在资源卡底层并设置 `pointer-events: none`，不得引入 D3、React Flow 等图表库，也不得阻断卡片点击和 Pointer Events 拖动。
+- `asset-reference` 表示精确资源引用，使用橙色实线。`GameCreationAppAssetManifestEntry.source.referenceResourceIds` 中的外部资源 ID 必须先唯一匹配另一项资产的 `source.resourceId`，再映射为当前资源卡 ID；缺失、重复或已删除的目标均不得渲染幽灵连线。
+- `task-flow` 表示任务产物流转，使用灰色虚线。任务依赖按 `sourceTaskId -> targetTaskId` 聚合为一条主线，两端资源仅绘制分支；禁止对上下游资源生成笛卡尔积连线。
+- 图模型必须对资源引用图和完整任务依赖图做迭代式环检测，不得用无界递归遍历；参与环的可见边保留渲染并标记 cyclic，环本身不能造成重复生成或死循环。
+- 资源自引用的起点与终点为同一张卡片时，必须绘制在卡片外侧的可见闭环并保留箭头，不得让路径穿过卡片后被底层 SVG 层级遮挡。
+- 搜索只允许为当前可见端点生成几何；任一精确引用端点隐藏时该线隐藏，聚合任务流只保留仍可见的两端分支，任一侧没有可见资源时整条任务流隐藏。
+- 选中资源后，高亮其直接上游、直接下游卡片和关联边，弱化其余边；不做跨多层递归高亮。选中 ID 已失效时按未选中处理。
+- 拖动预览坐标必须直接进入 SVG 几何计算，使连线随 pointer move 实时更新；拖动结束仍只保存卡片布局坐标，不持久化 path、marker、section 原点或任何图结构。
+
 ### 5.3 资源类型与替换兼容性（P1）
 
 ```ts
@@ -382,9 +394,18 @@ type ProjectAgentMudPointAttribution = {
 6. 布局读写不改变 manifest、游戏项目 mutation revision、Runtime verification、Agent 权限与预览状态。
 7. `1280×800` 最小横屏下全部资源可通过分区滚动访问，不出现页面级横向或纵向溢出，右侧对话和底部 Agent 状态栏保持可见。
 
+### 7.3 P1 资源依赖关系图验收
+
+1. dependency 模式同时正确显示橙色实线资源引用与灰色虚线任务流；type 模式没有图层或连线。
+2. 精确引用只接受唯一有效的外部资源 ID 映射，删除或不存在的资源不产生幽灵连线。
+3. 多资源任务依赖只形成一条聚合主线与 `O(S+T)` 条端点分支，不产生 `S×T` 连线。
+4. 资源引用环和无资源产物参与的任务环都可被有限遍历识别，界面不死循环。
+5. 搜索、选择和拖动分别触发端点过滤、直接上下游高亮和实时几何更新；原有点击、详情浮层与拖动保存行为不回归。
+6. 切换布局模式或项目后旧 SVG、ResizeObserver 与窗口监听全部清理；图层从不写入 layout sidecar、manifest 或其它持久化。
+
 ## 8. 非目标
 
-- 资源画布布局持久化切片不实现资源关系线、资源替换、不可变迭代版本、画板编辑状态、测试切片、数值参数或泥点归因。
+- 本切片仍不实现资源替换、不可变迭代版本、画板编辑状态、测试切片、数值参数或泥点归因；已实现的资源关系图只提供前端派生展示，不建立新的资源业务真相。
 - 本切片不保存资源详情浮层位置、画布缩放 / 平移、搜索条件、筛选条件或当前 mode；这些状态如需持久化必须另行扩展合同，不能塞入 `game-creator-resource-layout.v1`。
 - 不修改 SpacetimeDB schema。
 - 不开放普通用户 Agent.md/Skill。
diff --git a/docs/project-memory/shared-memory/decision-log.md b/docs/project-memory/shared-memory/decision-log.md
index 75ae6f4f2..5f1328abf 100644
--- a/docs/project-memory/shared-memory/decision-log.md
+++ b/docs/project-memory/shared-memory/decision-log.md
@@ -16,6 +16,15 @@
 
 ---
 
+## 2026-07-31 AI 游戏创作资源依赖图采用纯前端派生 SVG
+
+- 背景：资源画布已有 dependency / type 双模式坐标与本地 CAS sidecar，但 dependency 模式尚未把当前 manifest 中可证明的资源引用和任务流转可视化；关系图不能反向污染布局持久化或建立第二套资源真相。
+- 决策：dependency 模式从当前资源卡投影与 manifest task 派生 `ProjectResourceGraph`，使用原生 SVG 底层图层渲染。资产 `source.referenceResourceIds` 只在唯一匹配另一资产 `source.resourceId` 后形成橙色实线；任务依赖按任务对聚合为灰色虚线主线与两端分支，禁止资源笛卡尔积。图模型以迭代式强连通分量分析识别资源环和完整任务 DAG 环；搜索、选择、拖动只改变当前图层几何和高亮。
+- 生命周期与边界：type 模式不挂载图层；切换 mode、项目或卸载工作台时销毁 SVG、ResizeObserver 和窗口监听。SVG 统一 `pointer-events: none`，不干扰卡片点击/拖动；path、marker、图结构和 section 原点从不持久化。本切片不修改 Rust、Tauri command、layout sidecar、`resourceCanvasLayoutModel.ts`、manifest、api-server 或 SpacetimeDB，也不引入第三方图表库。
+- 影响范围：`apps/ai-game-creator-shell` 项目开发资源投影、依赖图模型、SVG overlay、样式与前端测试，以及工作台 PRD 和客户端实施计划。
+- 验证方式：图模型与 SVG 定向测试覆盖去重、无效 ID、完整任务环、可见资源自引用闭环、任务流聚合、搜索过滤、选择高亮和拖动几何；AppSurface 覆盖两种边、type 模式卸载和项目切换销毁，并运行 shell typecheck、编码检查与 `git diff --check`。
+- 关联文档：`docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md`、`docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md`。
+
 ## 2026-07-28 AI 游戏创作资源画布布局使用本地双模式 CAS sidecar
 
 - 背景：项目开发工作台当前只在 React 会话内保存同分类资源的一维拖拽顺序，项目切换或客户端重启后重建默认排列；工作台 PRD 虽已给出二维位置字段，但缺少落盘路径、坐标系、Tauri API、CAS、异常与安全边界，仍不足以直接编码。
diff --git a/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md b/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md
index b0d24a812..611186dc0 100644
--- a/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md
+++ b/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md
@@ -318,8 +318,8 @@ game-project/
 
 - 页面骨架固定为左侧现有全局导航、中间主视窗、右侧陶泥儿对话和底部子 Agent 状态栏；不新建第二套客户端或平行项目页。
 - 中间主视窗提供 `资源管理 / 运行` 切换。`code-prototype` 任务完成前运行入口保持视觉不可用，但仍可点击查看“当前无可运行版本”，不能使用会阻断说明交互的原生 `disabled` 或 `aria-disabled`；完成后才允许进入运行表现层。切回资源管理只修改前端展示态，不伪造后端预览暂停结果。
-- 资源管理从当前 `GameCreationAppManifest` 派生项目文档、项目版本和 `assets`，并把首页已导入附件作为当前项目上传资源展示。资源按文档、版本、美术、动作、音乐音效分区；`按依赖 / 按类型` 只改变当前前端排列方式，不写回 manifest，也不伪造资源依赖。
-- 资源卡支持选择聚焦、文档展开 / 收起、搜索和类型筛选的界面交互。2026-07-28 起，原一维会话拖拽已替换为两套二维坐标与本地 CAS sidecar；画板编辑、生成关系连线、同类型版本资源替换仍不得在缺少各自正式写回契约时保存为业务事实。
+- 资源管理从当前 `GameCreationAppManifest` 派生项目文档、项目版本和 `assets`，并把首页已导入附件作为当前项目上传资源展示。资源按文档、版本、美术、动作、音乐音效分区；`按依赖 / 按类型` 使用各自前端排列，dependency 模式额外绘制当前 manifest 与资源投影可证明的依赖关系。排列与图层都不写回 manifest，不能推断或伪造缺失依赖。
+- 资源卡支持选择聚焦、文档展开 / 收起、搜索和类型筛选的界面交互。2026-07-28 起，原一维会话拖拽已替换为两套二维坐标与本地 CAS sidecar；2026-07-31 起，dependency 模式增加不持久化的原生 SVG 关系图层。画板编辑和同类型版本资源替换仍不得在缺少各自正式写回契约时保存为业务事实。
 - 运行表现层首版直接嵌入当前项目的 loopback 游戏画面，并展示上一项 / 暂停继续 / 下一项切片控制、素材信息和数值微调面板。`preview.start` 启动本地 server 后把真实 URL 回写工作台，`preview.open` 只激活客户端内运行视图，不再调用系统浏览器；切片、参数调整和自然语言新增调节项首版仍只保留本地 UI 草稿，不修改代码或 manifest。
 - 右侧继续复用现有 Project Supervisor 会话、Runtime 澄清和确认链路；输入区展示 `严格审批 / 风险审批 / 无需审批` 独立面板。P0 只有严格审批可选；风险审批和无需审批保持视觉不可用但允许点击查看原因，不替代 Runtime 的逐动作权限、确认、sandbox 或 reconciliation 门禁。风险 Rank 算法记录在 `docs/project-memory/todos/【待解决】AI游戏创作高风险审批Rank-2026-07-20.md`，前端不得自行计算。
 - 底部状态栏默认展示策划、美术、程序 3 组，并允许在同一栏展开数值、音频、发布组；状态来自 manifest 与当前 Supervisor run 的 Runtime，悬停显示当前任务与进度。累计泥点必须等待后端计费归因投影；Agent.md 编辑和自定义 Skill 在来源审核、版本、权限、sandbox 与回滚合同完备前不向普通用户开放。
@@ -328,7 +328,7 @@ game-project/
 - 当前独立 App 只交付横屏桌面工作台，Tauri `client` 默认与最小窗口统一为 `1280×800`；用户不能继续缩小到破坏双栏结构的窄屏尺寸。桌面工作台占满壳内剩余视口，四周只保留必要安全边距；右侧消息、Runtime 状态和输入区保持在同一栏内，专业状态过长时只滚动 Runtime 区，不得把输入区、底部 Agent 状态栏或整页撑出视口。`≤760px` 的浏览器样式仅保留开发兼容，不作为当前客户端交付口径。
 - 项目总控失败摘要必须提供“在当前项目重试总控”的明确恢复动作并说明不会新建项目；旧父 run 下仍在运行的专业 Agent 继续展示真实状态。terminal 总控下不得单独重试专业 Agent，避免创建没有可交付父级的孤立委派；新总控 run 负责重新建立后续专业委派合同。
 - 外部 Runner 模式下，重试命令的 Session Runtime 快照可能仍指向旧 run，因此响应必须额外返回精确 `acceptedRunId` 作为入队受理事实，前端据此锁定恢复按钮并持续同步该 run，不能用 `state.runId` 是否立即切换判断失败。同一 `agentId + sourceRunId` 已存在非终态 retry successor 时必须幂等复用并返回其 `acceptedRunId`，不得再次入队或追加第二条 retry audit。
-- 该界面切片只允许受限的 loopback iframe，不得引入远程 URL、第二套资产模型、前端正式资源关系、前端版本替换真相或前端计费结论。
+- 该界面切片只允许受限的 loopback iframe，不得引入远程 URL、第二套资产模型、前端版本替换真相或前端计费结论。资源关系图只能读取当前 manifest 与资源投影做派生展示，不得成为前端正式资源关系真相。
 
 ### 资源画布布局持久化 V1
 
@@ -341,7 +341,7 @@ game-project/
 - 新资源只在第一次进入某个 mode 时计算默认不重叠位置；全部现存坐标保持不变。搜索、筛选、窗口 resize 和 mode 切换不得重排或回写已有坐标，窄视图通过 section 画布范围与滚动访问，不裁切持久坐标。
 - type 默认布局固定按 `subtype -> mediaType -> label -> id` 排序。manifest 资产的 subtype 使用 `asset.kind`，任务产物、导入附件和 Agent 文本成果使用稳定的来源 fallback；subtype 必须进入资源协调签名，不能因 MIME 相同而退化成按名称混排。
 - 普通保存失败恢复最近可信持久布局；CAS 冲突载入对方最新布局并要求用户重新拖动，同时清除基于旧快照排队的全部手动意图，不自动重放旧坐标。即使冲突发生在允许自动重试的资源协调请求上，只要本次冲突清除了排队手动意图，重新拖动提示就必须绑定当前 scope 保留，不得被后续资源协调成功、失败或通用提示定时器静默清除；新的手动布局成功保存或 scope 切换后才解除。资源自动协调可基于冲突布局最多追加两次重试，持续跨窗口竞争时停止自旋并保留当前会话协调结果。损坏、未知 schema、身份冲突、超限与链接文件失败关闭，不能用空布局覆盖原文件。
-- 本切片不包含资源关系线、资源替换、详情浮层位置、缩放 / 平移、搜索 / 筛选条件、当前 mode，也不修改 `api-server` 或 SpacetimeDB。关系线与其它 P1 能力必须在本切片独立验收后继续接入。
+- 本布局持久化切片不包含资源关系线、资源替换、详情浮层位置、缩放 / 平移、搜索 / 筛选条件、当前 mode，也不修改 `api-server` 或 SpacetimeDB。资源关系线已在后续独立的纯前端切片接入，不改变本段 sidecar 合同；其余 P1 能力继续独立实施。
 
 实施顺序固定为：先同步 TypeScript / Rust DTO 与序列化测试，再实现 Tauri sidecar 读写和 CAS，随后接入前端纯模型、持久 Hook 与二维拖动，最后完成 Rust 安全测试、React 交互测试、跨重启 / 双窗口验收和文档状态回写。任何一步不得用 `localStorage`、manifest 字段或只在当前 React 会话有效的状态冒充项目持久化。
 
@@ -349,6 +349,19 @@ game-project/
 
 2026-07-30 Rust 并发与零副作用加固状态：资源布局锁已由 `create_new + mtime stale 删除` 改为持久锁文件上的 Unix `flock` / Windows 独占句柄，活锁即使 mtime 很旧也不能被另一个写入者回收，释放后仍复用同一文件实例。更新命令携带只用于校验的 `expectedProjectId`，在任何目录创建前先读取 manifest 并拒绝旧项目窗口，锁内再次核对 projectId；不存在根、非项目根、损坏 manifest 和路径重建后的旧窗口均不产生 `.agent/workbench`。revision 在共享 serde、Tauri 命令和前端 IPC 三层限制到 `Number.MAX_SAFE_INTEGER`，达到上限时保持原文件并失败关闭，不能让 Rust `u64` 值在 JavaScript 中失真后击穿 CAS。
 
+### 资源依赖关系图层 V1
+
+2026-07-31 起，项目工作台在不修改 Rust、layout sidecar 和既有布局模型的前提下增加纯前端资源依赖图层：
+
+- `resourceDependencyGraphModel.ts` 负责从当前资源卡投影和 manifest task 构建 `ProjectResourceGraph`。精确引用把资产 `source.referenceResourceIds` 唯一匹配到另一资产的 `source.resourceId`，再转换为实际卡片 ID；无匹配、多匹配和已删除资源只记录为 unresolved，不生成边。引用边按 `sourceResourceId + targetResourceId` 稳定去重。
+- task flow 只读取存在于当前 manifest 的任务依赖。资源按 `producerTaskId` 分组，每个 `sourceTaskId -> targetTaskId` 只生成一个聚合 flow；SVG 侧绘制 source 分支、唯一主线和 target 分支，路径数量为 `O(S+T)`，禁止资源笛卡尔积。
+- 资源引用图和完整任务依赖图分别使用迭代式强连通分量分析。任务环检测不能依赖可视 task flow 是否有两端资源，否则无产物任务参与的环会漏报；循环边只带 cyclic 标记，不触发递归展开。
+- `ResourceDependencyOverlay.tsx` 使用原生 SVG path/marker，绝对定位在 `.game-resource-canvas-content` 底层并统一 `pointer-events: none`。橙色实线表示 `asset-reference`，灰色虚线表示 `task-flow`；不引入 D3、React Flow 或其它图表依赖。
+- `asset-reference` 的 source / target 是同一资源时使用卡片右侧外绕贝塞尔闭环，两个锚点分开且 marker 保留在返回锚点；路径不穿过卡片，并与普通边一样直接由拖动预览坐标重算。
+- 图层用 SVG 自身节点定位所属画布容器，测量各 section plane 相对原点；`ResizeObserver` 与 window resize 只负责重新测量，并在卸载时清理。这样不依赖父组件 ref 在子组件 layout effect 中的绑定时序。type 模式不挂载图层；项目身份作为 key，切换 mode、项目或工作台卸载都会销毁旧 SVG。
+- 搜索可见 ID 在几何阶段过滤端点；选中资源只查询一跳上下游与关联边，关联卡片和边高亮，其余边弱化。拖动预览坐标直接替换当前卡片坐标传入图层，pointer move 实时更新 path；结束后仍只通过原布局 Hook 保存卡片坐标，SVG 几何从不持久化。
+- 前端模型、SVG 单测和工作台 AppSurface 回归覆盖精确引用、去重、无效 ID、完整任务环、聚合复杂度、搜索过滤、选择高亮、拖动更新、type 模式卸载与项目切换销毁。该切片不修改 `resourceCanvasLayoutModel.ts`、Tauri command、layout sidecar、`api-server`、Rust 或 SpacetimeDB。
+
 ## 分阶段实施
 
 1. 在 `platform-agent` 建立游戏创作专业组与种子任务图契约。
@@ -361,7 +374,7 @@ game-project/
 
 - 用户能创建本地 Web 游戏项目。
 - 用户进入项目开发页后能看到资源管理主视窗、陶泥儿对话栏和底部策划 / 美术 / 程序 Agent 状态栏；`1280×800` 最小横屏窗口和更大桌面窗口均不得出现页面级横向 / 纵向溢出，对话输入与底部 Agent 状态栏始终位于视口内。
-- 资源管理可在按依赖 / 按类型之间切换、搜索资源、展开文档和聚焦资源；所有展示数据来自当前 manifest 或当前项目导入附件。
+- 资源管理可在按依赖 / 按类型之间切换、搜索资源、展开文档和聚焦资源；dependency 模式展示可验证的资源引用和聚合任务流，搜索、选择与拖动同步更新线段；所有展示数据来自当前 manifest、当前资源投影或当前项目导入附件。
 - 首个 `code-prototype` 任务未完成时运行入口不可进入并给出可感知提示；完成后可进入运行表现层，真实预览直接加载到客户端内受限运行容器。
 - 审批档位通过独立弹出面板切换，默认严格审批；界面选择不得绕过 Runtime 现有确认门禁。
 - 聊天输入 `/plan` 可在普通聊天消息里查看下一轮分工计划，不读取任务文件、不启动 run、不修改项目，也不新增普通用户计划面板。
-- 
2.52.0


From 11140b9fb610151e8ddbdff1455e93fbb51d5423 Mon Sep 17 00:00:00 2001
From: menghao <mh18530625731@163.com>
Date: Fri, 31 Jul 2026 16:31:09 +0800
Subject: [PATCH 02/27] =?UTF-8?q?=E4=BF=AE=E5=A4=8D=E5=90=8E=E7=AB=AF?=
 =?UTF-8?q?=E6=BA=90=E7=A0=81=E7=BA=A6=E6=9D=9F=E6=B5=8B=E8=AF=95?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

同步 UI 素材切片持久化失败断言至现有 warning 映射函数
保持生产逻辑和持久层不变
---
 server-rs/crates/api-server/src/editor_project.rs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/server-rs/crates/api-server/src/editor_project.rs b/server-rs/crates/api-server/src/editor_project.rs
index 7b0b54eb9..bf9400509 100644
--- a/server-rs/crates/api-server/src/editor_project.rs
+++ b/server-rs/crates/api-server/src/editor_project.rs
@@ -13704,7 +13704,7 @@ mod tests {
             "pub(crate) fn editor_project_payload_from_record",
             &[
                 "EDITOR_ASSET_DEFAULT_FOLDER_ID",
-                "EDITOR_ICON_SPRITESHEET_SLICE_WARNING_PERSISTENCE",
+                "editor_icon_spritesheet_warning_after_persist_error",
                 "slice_editor_icon_spritesheet_all",
             ],
         );
-- 
2.52.0


From f582ecf032e081175f68c7377a36e2640135e9e8 Mon Sep 17 00:00:00 2001
From: menghao <mh18530625731@163.com>
Date: Fri, 31 Jul 2026 18:36:21 +0800
Subject: [PATCH 03/27] =?UTF-8?q?=E4=BC=98=E5=8C=96=E8=B5=84=E6=BA=90?=
 =?UTF-8?q?=E4=BE=9D=E8=B5=96=E5=9B=BE=E8=BF=9E=E7=BA=BF=E5=A4=96=E8=A7=82?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

将任务流分支改为平滑贝塞尔曲线
调整两类连线的线宽、虚线和箭头样式
补充连线几何测试与相关文档
---
 apps/ai-game-creator-shell/src/styles.css     | 55 ++++++++++++-----
 .../ResourceDependencyOverlay.tsx             | 60 +++++++++++++------
 .../tests/ResourceDependencyOverlay.test.ts   | 16 ++++-
 ...AI游戏创作】项目开发工作台PRD-2026-07-20.md |  4 +-
 ...�案】AI游戏创作智能体App实施计划-2026-06-24.md |  2 +-
 5 files changed, 100 insertions(+), 37 deletions(-)

diff --git a/apps/ai-game-creator-shell/src/styles.css b/apps/ai-game-creator-shell/src/styles.css
index f849b43ca..75f08c70f 100644
--- a/apps/ai-game-creator-shell/src/styles.css
+++ b/apps/ai-game-creator-shell/src/styles.css
@@ -3902,6 +3902,8 @@ iframe.preview-frame {
 .game-resource-dependency-edge,
 .game-resource-dependency-edge path {
   fill: none;
+  stroke-linecap: round;
+  stroke-linejoin: round;
   vector-effect: non-scaling-stroke;
   transition:
     opacity 140ms ease,
@@ -3909,25 +3911,44 @@ iframe.preview-frame {
 }
 
 .game-resource-dependency-edge--reference {
-  stroke: #d87342;
+  stroke: #d96f3d;
+  stroke-width: 2.25px;
+  opacity: 0.94;
+}
+
+.game-resource-dependency-edge--task path {
+  stroke: #918b87;
+  stroke-width: 1.4px;
+  stroke-dasharray: 4 7;
+}
+
+.game-resource-dependency-edge--task .game-resource-dependency-trunk {
+  stroke-width: 1.7px;
+  opacity: 0.88;
+}
+
+.game-resource-dependency-edge--task .game-resource-dependency-branch {
+  opacity: 0.72;
+}
+
+.game-resource-dependency-edge.is-highlighted {
+  opacity: 1;
+}
+
+.game-resource-dependency-edge--reference.is-highlighted {
+  stroke-width: 3px;
+}
+
+.game-resource-dependency-edge--task.is-highlighted path {
+  opacity: 1;
   stroke-width: 2px;
 }
 
-.game-resource-dependency-edge--task,
-.game-resource-dependency-edge--task path {
-  stroke: #9d948f;
-  stroke-width: 1.5px;
-  stroke-dasharray: 7 6;
+.game-resource-dependency-edge--task.is-highlighted .game-resource-dependency-trunk {
+  stroke-width: 2.4px;
 }
 
-.game-resource-dependency-edge.is-highlighted,
-.game-resource-dependency-edge.is-highlighted path {
-  opacity: 1;
-  stroke-width: 2.8px;
-}
-
-.game-resource-dependency-edge.is-dimmed,
-.game-resource-dependency-edge.is-dimmed path {
+.game-resource-dependency-edge.is-dimmed {
   opacity: 0.14;
 }
 
@@ -3937,11 +3958,13 @@ iframe.preview-frame {
 }
 
 .game-resource-dependency-marker--reference path {
-  fill: #d87342;
+  fill: #d96f3d;
+  stroke-linejoin: round;
 }
 
 .game-resource-dependency-marker--task path {
-  fill: #9d948f;
+  fill: #918b87;
+  stroke-linejoin: round;
 }
 
 .game-resource-section {
diff --git a/apps/ai-game-creator-shell/src/view/project-development/ResourceDependencyOverlay.tsx b/apps/ai-game-creator-shell/src/view/project-development/ResourceDependencyOverlay.tsx
index e318ad0e4..a3ffc1ab4 100644
--- a/apps/ai-game-creator-shell/src/view/project-development/ResourceDependencyOverlay.tsx
+++ b/apps/ai-game-creator-shell/src/view/project-development/ResourceDependencyOverlay.tsx
@@ -36,6 +36,8 @@ export type ResourceDependencyOverlayProps = {
 
 const SECTION_SELECTOR = '[data-resource-section-plane]';
 const TASK_FLOW_HUB_GAP = 20;
+const CONNECTION_MAX_HANDLE = 180;
+const TASK_FLOW_BRANCH_MAX_HANDLE = 96;
 const SELF_REFERENCE_LOOP_WIDTH = 56;
 const SELF_REFERENCE_LOOP_ANCHOR_OFFSET = 18;
 
@@ -60,17 +62,39 @@ function connectionPath(source: Point, target: Point) {
     } ${source.y + 48}, ${source.x} ${source.y + 1}`;
   }
   const direction = target.x >= source.x ? 1 : -1;
-  const bend = Math.max(36, Math.abs(target.x - source.x) * 0.45);
+  const bend = Math.min(
+    CONNECTION_MAX_HANDLE,
+    Math.max(
+      32,
+      Math.abs(target.x - source.x) * 0.42 +
+        Math.abs(target.y - source.y) * 0.08,
+    ),
+  );
   return `M ${source.x} ${source.y} C ${source.x + direction * bend} ${
     source.y
   }, ${target.x - direction * bend} ${target.y}, ${target.x} ${target.y}`;
 }
 
-function linePath(source: Point, target: Point) {
-  const middleX = (source.x + target.x) / 2;
-  return `M ${source.x} ${source.y} L ${middleX} ${source.y} L ${middleX} ${
-    target.y
-  } L ${target.x} ${target.y}`;
+function taskFlowBranchPath(source: Point, target: Point) {
+  const horizontalDistance = Math.abs(target.x - source.x);
+  if (horizontalDistance < 1) {
+    const direction = target.y >= source.y ? 1 : -1;
+    const handle = Math.min(
+      TASK_FLOW_BRANCH_MAX_HANDLE,
+      Math.abs(target.y - source.y) * 0.5,
+    );
+    return `M ${source.x} ${source.y} C ${source.x} ${
+      source.y + direction * handle
+    }, ${target.x} ${target.y - direction * handle}, ${target.x} ${target.y}`;
+  }
+  const direction = target.x >= source.x ? 1 : -1;
+  const handle = Math.min(
+    TASK_FLOW_BRANCH_MAX_HANDLE,
+    horizontalDistance * 0.5,
+  );
+  return `M ${source.x} ${source.y} C ${source.x + direction * handle} ${
+    source.y
+  }, ${target.x - direction * handle} ${target.y}, ${target.x} ${target.y}`;
 }
 
 function rectCenter(rect: Rect): Point {
@@ -278,26 +302,28 @@ export function ResourceDependencyOverlay({
         <marker
           id={`${markerPrefix}-asset-reference-arrow`}
           className="game-resource-dependency-marker game-resource-dependency-marker--reference"
-          markerWidth="8"
-          markerHeight="8"
-          refX="7"
-          refY="4"
+          markerWidth="9"
+          markerHeight="9"
+          refX="8"
+          refY="4.5"
           orient="auto"
-          markerUnits="strokeWidth"
+          markerUnits="userSpaceOnUse"
+          viewBox="0 0 9 9"
         >
-          <path d="M 0 0 L 8 4 L 0 8 z" />
+          <path d="M 1 1 L 8 4.5 L 1 8 z" />
         </marker>
         <marker
           id={`${markerPrefix}-task-flow-arrow`}
           className="game-resource-dependency-marker game-resource-dependency-marker--task"
           markerWidth="8"
           markerHeight="8"
-          refX="7"
+          refX="7.25"
           refY="4"
           orient="auto"
-          markerUnits="strokeWidth"
+          markerUnits="userSpaceOnUse"
+          viewBox="0 0 8 8"
         >
-          <path d="M 0 0 L 8 4 L 0 8 z" />
+          <path d="M 1 1.25 L 7 4 L 1 6.75 z" />
         </marker>
       </defs>
 
@@ -328,7 +354,7 @@ export function ResourceDependencyOverlay({
                 key={`source:${resourceId}`}
                 className="game-resource-dependency-branch"
                 data-resource-id={resourceId}
-                d={linePath(point, geometry.sourceHub)}
+                d={taskFlowBranchPath(point, geometry.sourceHub)}
               />
             ))}
             <path
@@ -340,7 +366,7 @@ export function ResourceDependencyOverlay({
                 key={`target:${resourceId}`}
                 className="game-resource-dependency-branch"
                 data-resource-id={resourceId}
-                d={linePath(geometry.targetHub, point)}
+                d={taskFlowBranchPath(geometry.targetHub, point)}
                 markerEnd={`url(#${markerPrefix}-task-flow-arrow)`}
               />
             ))}
diff --git a/apps/ai-game-creator-shell/tests/ResourceDependencyOverlay.test.ts b/apps/ai-game-creator-shell/tests/ResourceDependencyOverlay.test.ts
index 2f56beff8..e5b508d09 100644
--- a/apps/ai-game-creator-shell/tests/ResourceDependencyOverlay.test.ts
+++ b/apps/ai-game-creator-shell/tests/ResourceDependencyOverlay.test.ts
@@ -120,8 +120,22 @@ describe('ResourceDependencyOverlay', () => {
     );
     const taskFlow = overlay.querySelector('[data-edge-kind="task-flow"]');
     expect(taskFlow).not.toBeNull();
-    expect(taskFlow?.querySelectorAll('path')).toHaveLength(7);
+    const taskPaths = Array.from(
+      taskFlow?.querySelectorAll<SVGPathElement>('path') ?? [],
+    );
+    expect(taskPaths).toHaveLength(7);
+    expect(
+      taskPaths.every((path) => path.getAttribute('d')?.includes(' C ')),
+    ).toBe(true);
+    expect(
+      taskPaths.some((path) => path.getAttribute('d')?.includes(' L ')),
+    ).toBe(false);
     expect(taskFlow?.querySelectorAll('path[marker-end]')).toHaveLength(3);
+    expect(
+      overlay
+        .querySelector('marker[id$="-task-flow-arrow"]')
+        ?.getAttribute('markerUnits'),
+    ).toBe('userSpaceOnUse');
   });
 
   it('filters hidden endpoints and updates path geometry when positions change', async () => {
diff --git a/docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md b/docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md
index 7e18fc25f..e00ab7567 100644
--- a/docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md
+++ b/docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md
@@ -251,8 +251,8 @@ type UpdateProjectResourceCanvasLayoutResult =
 
 - 图层只在 dependency 模式挂载；type 模式不得渲染 SVG、连线或 marker。切换 mode、切换项目或卸载工作台时必须销毁旧图层，并清理尺寸观察和窗口事件监听。
 - 输入固定为当前资源投影的全部卡片坐标与前端 `ProjectResourceGraph`；输出使用原生 SVG 的 path 和箭头 marker。SVG 叠加在资源卡底层并设置 `pointer-events: none`，不得引入 D3、React Flow 等图表库，也不得阻断卡片点击和 Pointer Events 拖动。
-- `asset-reference` 表示精确资源引用，使用橙色实线。`GameCreationAppAssetManifestEntry.source.referenceResourceIds` 中的外部资源 ID 必须先唯一匹配另一项资产的 `source.resourceId`，再映射为当前资源卡 ID；缺失、重复或已删除的目标均不得渲染幽灵连线。
-- `task-flow` 表示任务产物流转，使用灰色虚线。任务依赖按 `sourceTaskId -> targetTaskId` 聚合为一条主线，两端资源仅绘制分支；禁止对上下游资源生成笛卡尔积连线。
+- `asset-reference` 表示精确资源引用，使用橙色实线与连续贝塞尔曲线。`GameCreationAppAssetManifestEntry.source.referenceResourceIds` 中的外部资源 ID 必须先唯一匹配另一项资产的 `source.resourceId`，再映射为当前资源卡 ID；缺失、重复或已删除的目标均不得渲染幽灵连线。
+- `task-flow` 表示任务产物流转，使用灰色圆头虚线。任务依赖按 `sourceTaskId -> targetTaskId` 聚合为一条主线，两端资源仅绘制平滑曲线分支，不得出现直角折线；禁止对上下游资源生成笛卡尔积连线。任务主线与分支可以使用不同线宽和透明度表达聚合层级，但不能改变端点或方向语义。
 - 图模型必须对资源引用图和完整任务依赖图做迭代式环检测，不得用无界递归遍历；参与环的可见边保留渲染并标记 cyclic，环本身不能造成重复生成或死循环。
 - 资源自引用的起点与终点为同一张卡片时，必须绘制在卡片外侧的可见闭环并保留箭头，不得让路径穿过卡片后被底层 SVG 层级遮挡。
 - 搜索只允许为当前可见端点生成几何；任一精确引用端点隐藏时该线隐藏，聚合任务流只保留仍可见的两端分支，任一侧没有可见资源时整条任务流隐藏。
diff --git a/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md b/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md
index 63a147601..e45244831 100644
--- a/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md
+++ b/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md
@@ -371,7 +371,7 @@ game-project/
 - `resourceDependencyGraphModel.ts` 负责从当前资源卡投影和 manifest task 构建 `ProjectResourceGraph`。精确引用把资产 `source.referenceResourceIds` 唯一匹配到另一资产的 `source.resourceId`，再转换为实际卡片 ID；无匹配、多匹配和已删除资源只记录为 unresolved，不生成边。引用边按 `sourceResourceId + targetResourceId` 稳定去重。
 - task flow 只读取存在于当前 manifest 的任务依赖。资源按 `producerTaskId` 分组，每个 `sourceTaskId -> targetTaskId` 只生成一个聚合 flow；SVG 侧绘制 source 分支、唯一主线和 target 分支，路径数量为 `O(S+T)`，禁止资源笛卡尔积。
 - 资源引用图和完整任务依赖图分别使用迭代式强连通分量分析。任务环检测不能依赖可视 task flow 是否有两端资源，否则无产物任务参与的环会漏报；循环边只带 cyclic 标记，不触发递归展开。
-- `ResourceDependencyOverlay.tsx` 使用原生 SVG path/marker，绝对定位在 `.game-resource-canvas-content` 底层并统一 `pointer-events: none`。橙色实线表示 `asset-reference`，灰色虚线表示 `task-flow`；不引入 D3、React Flow 或其它图表依赖。
+- `ResourceDependencyOverlay.tsx` 使用原生 SVG path/marker，绝对定位在 `.game-resource-canvas-content` 底层并统一 `pointer-events: none`。橙色实线表示 `asset-reference`，灰色圆头虚线表示 `task-flow`；两类连线统一使用连续贝塞尔曲线，任务主线略强于两端分支，箭头使用不随高亮线宽缩放的稳定用户空间尺寸，避免直角折线、突兀拐弯和箭头跳变。不引入 D3、React Flow 或其它图表依赖。
 - `asset-reference` 的 source / target 是同一资源时使用卡片右侧外绕贝塞尔闭环，两个锚点分开且 marker 保留在返回锚点；路径不穿过卡片，并与普通边一样直接由拖动预览坐标重算。
 - 图层用 SVG 自身节点定位所属画布容器，测量各 section plane 相对原点；`ResizeObserver` 与 window resize 只负责重新测量，并在卸载时清理。这样不依赖父组件 ref 在子组件 layout effect 中的绑定时序。type 模式不挂载图层；项目身份作为 key，切换 mode、项目或工作台卸载都会销毁旧 SVG。
 - 搜索可见 ID 在几何阶段过滤端点；选中资源只查询一跳上下游与关联边，关联卡片和边高亮，其余边弱化。拖动预览坐标直接替换当前卡片坐标传入图层，pointer move 实时更新 path；结束后仍只通过原布局 Hook 保存卡片坐标，SVG 几何从不持久化。
-- 
2.52.0


From 29dce59b352e4d1156ca958df3792f2d26322d08 Mon Sep 17 00:00:00 2001
From: menghao <mh18530625731@163.com>
Date: Fri, 31 Jul 2026 19:09:57 +0800
Subject: [PATCH 04/27] =?UTF-8?q?=E5=B0=86=E8=B5=84=E6=BA=90=E4=BE=9D?=
 =?UTF-8?q?=E8=B5=96=E5=9B=BE=E8=AE=A1=E7=AE=97=E8=BF=81=E7=A7=BB=E5=88=B0?=
 =?UTF-8?q?Rust?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

新增只读资源依赖图模型，完成过滤、去重、环检测和任务流聚合
前端SVG仅负责几何渲染、搜索联动、选中高亮和拖动预览
补充资源图、覆盖层和工作台回归测试
同步更新工作台PRD、技术方案与项目记忆
---
 .../src-tauri/src/commands.rs                 |  11 +
 .../src-tauri/src/main.rs                     |   2 +
 .../src-tauri/src/project.rs                  |   2 +
 .../src/project/resource_dependency_graph.rs  | 738 ++++++++++++++++++
 .../ResourceDependencyOverlay.tsx             | 300 +++++--
 .../src/view/project-development/index.tsx    | 296 +++++--
 .../resourceDependencyGraphModel.ts           | 405 ++++------
 .../tests/ResourceDependencyOverlay.test.ts   | 246 +++++-
 .../appSurface/project-development.suite.ts   | 128 ++-
 .../resourceDependencyGraphModel.test.ts      | 255 +++---
 ...AI游戏创作】项目开发工作台PRD-2026-07-20.md |   9 +-
 .../shared-memory/decision-log.md             |  12 +-
 docs/project-memory/shared-memory/pitfalls.md |   8 +
 ...�案】AI游戏创作智能体App实施计划-2026-06-24.md |  20 +-
 14 files changed, 1874 insertions(+), 558 deletions(-)
 create mode 100644 apps/ai-game-creator-shell/src-tauri/src/project/resource_dependency_graph.rs

diff --git a/apps/ai-game-creator-shell/src-tauri/src/commands.rs b/apps/ai-game-creator-shell/src-tauri/src/commands.rs
index 67a4f83f4..3ed2341dc 100644
--- a/apps/ai-game-creator-shell/src-tauri/src/commands.rs
+++ b/apps/ai-game-creator-shell/src-tauri/src/commands.rs
@@ -204,6 +204,17 @@ pub(crate) fn read_local_project_resource_canvas_layout(
     read_project_resource_canvas_layout_at(Path::new(project_path.trim()), mode)
 }
 
+#[tauri::command]
+pub(crate) fn read_local_project_resource_graph(
+    project_path: String,
+    expected_project_id: String,
+    resources: Vec<ProjectResourceGraphNodeInput>,
+) -> Result<ProjectResourceGraphReadModel, String> {
+    let root = validated_local_project_directory_path(project_path.trim())?;
+    enforce_project_auto_permission_policy(&root, "asset.list")?;
+    read_project_resource_graph_at(&root, expected_project_id.trim(), resources)
+}
+
 #[tauri::command]
 pub(crate) fn update_local_project_resource_canvas_layout(
     project_path: String,
diff --git a/apps/ai-game-creator-shell/src-tauri/src/main.rs b/apps/ai-game-creator-shell/src-tauri/src/main.rs
index 8f72f2bcc..d400fadd3 100644
--- a/apps/ai-game-creator-shell/src-tauri/src/main.rs
+++ b/apps/ai-game-creator-shell/src-tauri/src/main.rs
@@ -1969,6 +1969,7 @@ fn handle_game_creator_gui_run_event(event: &tauri::RunEvent) {
     }
 }
 
+#[cfg(not(test))]
 fn main() {
     let mut args = std::env::args().skip(1).collect::<Vec<_>>();
     #[cfg(target_os = "linux")]
@@ -2322,6 +2323,7 @@ fn main() {
             stop_local_game_preview_if_matches,
             get_local_game_preview_status,
             read_local_project_resource_canvas_layout,
+            read_local_project_resource_graph,
             update_local_project_resource_canvas_layout,
             get_local_game_project_revision,
             get_local_game_manifest
diff --git a/apps/ai-game-creator-shell/src-tauri/src/project.rs b/apps/ai-game-creator-shell/src-tauri/src/project.rs
index aee2ea42a..1099d78e8 100644
--- a/apps/ai-game-creator-shell/src-tauri/src/project.rs
+++ b/apps/ai-game-creator-shell/src-tauri/src/project.rs
@@ -10,6 +10,7 @@ mod export;
 mod filesystem;
 mod manifest;
 mod memory;
+mod resource_dependency_graph;
 mod resource_layout;
 mod verification;
 
@@ -20,5 +21,6 @@ pub(crate) use export::*;
 pub(crate) use filesystem::*;
 pub(crate) use manifest::*;
 pub(crate) use memory::*;
+pub(crate) use resource_dependency_graph::*;
 pub(crate) use resource_layout::*;
 pub(crate) use verification::*;
diff --git a/apps/ai-game-creator-shell/src-tauri/src/project/resource_dependency_graph.rs b/apps/ai-game-creator-shell/src-tauri/src/project/resource_dependency_graph.rs
new file mode 100644
index 000000000..54630f25e
--- /dev/null
+++ b/apps/ai-game-creator-shell/src-tauri/src/project/resource_dependency_graph.rs
@@ -0,0 +1,738 @@
+use super::*;
+use std::collections::{BTreeMap, BTreeSet};
+
+const RESOURCE_GRAPH_AGENT_DB_READ_BYTES: u64 = 32 * 1024 * 1024;
+
+#[derive(Clone, Debug, Deserialize, Eq, PartialEq)]
+#[serde(rename_all = "camelCase")]
+pub(crate) struct ProjectResourceGraphNodeInput {
+    pub resource_id: String,
+    #[serde(default)]
+    pub manifest_asset_id: Option<String>,
+    #[serde(default)]
+    pub producer_task_id: Option<String>,
+}
+
+#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub(crate) struct ProjectResourceReferenceEdge {
+    pub id: String,
+    pub kind: String,
+    pub source_resource_id: String,
+    pub target_resource_id: String,
+    pub cyclic: bool,
+}
+
+#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub(crate) struct ProjectResourceTaskFlow {
+    pub id: String,
+    pub kind: String,
+    pub source_task_id: String,
+    pub target_task_id: String,
+    pub source_resource_ids: Vec<String>,
+    pub target_resource_ids: Vec<String>,
+    pub cyclic: bool,
+}
+
+#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub(crate) struct ProjectResourceConnectionIndex {
+    pub resource_id: String,
+    pub upstream_reference_resource_ids: Vec<String>,
+    pub downstream_reference_resource_ids: Vec<String>,
+    pub reference_edge_ids: Vec<String>,
+    pub task_flow_ids: Vec<String>,
+}
+
+#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub(crate) struct ProjectResourceProducerAssignment {
+    pub resource_id: String,
+    pub task_id: String,
+}
+
+#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub(crate) struct ProjectResourceGraphReadModel {
+    pub resource_ids: Vec<String>,
+    pub reference_edges: Vec<ProjectResourceReferenceEdge>,
+    pub task_flows: Vec<ProjectResourceTaskFlow>,
+    pub connection_index: Vec<ProjectResourceConnectionIndex>,
+    pub producer_assignments: Vec<ProjectResourceProducerAssignment>,
+    pub unresolved_reference_resource_ids: Vec<String>,
+    pub cyclic_resource_ids: Vec<String>,
+    pub cyclic_task_ids: Vec<String>,
+    pub producer_mapping_truncated: bool,
+}
+
+#[derive(Clone, Debug, Eq, PartialEq)]
+struct DirectedEdge {
+    id: String,
+    source_id: String,
+    target_id: String,
+}
+
+#[derive(Debug, Default)]
+struct CycleAnalysis {
+    cyclic_node_ids: BTreeSet<String>,
+    cyclic_edge_ids: BTreeSet<String>,
+}
+
+#[derive(Debug, Default)]
+struct MutableConnectionIndex {
+    upstream_reference_resource_ids: BTreeSet<String>,
+    downstream_reference_resource_ids: BTreeSet<String>,
+    reference_edge_ids: BTreeSet<String>,
+    task_flow_ids: BTreeSet<String>,
+}
+
+fn stable_edge_id(kind: &str, source_id: &str, target_id: &str) -> String {
+    let pair = serde_json::to_string(&(source_id, target_id))
+        .expect("serializing two resource graph identifiers cannot fail");
+    format!("{kind}:{pair}")
+}
+
+fn analyze_directed_cycles<'a>(
+    node_ids: impl IntoIterator<Item = &'a String>,
+    edges: &[DirectedEdge],
+) -> CycleAnalysis {
+    let mut nodes = node_ids.into_iter().cloned().collect::<BTreeSet<_>>();
+    for edge in edges {
+        nodes.insert(edge.source_id.clone());
+        nodes.insert(edge.target_id.clone());
+    }
+
+    let mut adjacency = nodes
+        .iter()
+        .map(|node_id| (node_id.clone(), Vec::<String>::new()))
+        .collect::<BTreeMap<_, _>>();
+    let mut reverse_adjacency = adjacency.clone();
+    for edge in edges {
+        adjacency
+            .entry(edge.source_id.clone())
+            .or_default()
+            .push(edge.target_id.clone());
+        reverse_adjacency
+            .entry(edge.target_id.clone())
+            .or_default()
+            .push(edge.source_id.clone());
+    }
+
+    let mut visited = BTreeSet::new();
+    let mut finish_order = Vec::with_capacity(nodes.len());
+    for root in &nodes {
+        if !visited.insert(root.clone()) {
+            continue;
+        }
+        let mut stack = vec![(root.clone(), 0usize)];
+        while let Some((node_id, next_index)) = stack.last_mut() {
+            let neighbors = adjacency.get(node_id).map(Vec::as_slice).unwrap_or(&[]);
+            if let Some(next) = neighbors.get(*next_index) {
+                *next_index += 1;
+                if visited.insert(next.clone()) {
+                    stack.push((next.clone(), 0));
+                }
+            } else {
+                let completed = node_id.clone();
+                stack.pop();
+                finish_order.push(completed);
+            }
+        }
+    }
+
+    let mut component_by_node = BTreeMap::<String, usize>::new();
+    let mut component_sizes = Vec::<usize>::new();
+    for root in finish_order.into_iter().rev() {
+        if component_by_node.contains_key(&root) {
+            continue;
+        }
+        let component_id = component_sizes.len();
+        let mut size = 0usize;
+        let mut stack = vec![root.clone()];
+        component_by_node.insert(root, component_id);
+        while let Some(node_id) = stack.pop() {
+            size += 1;
+            for neighbor in reverse_adjacency
+                .get(&node_id)
+                .map(Vec::as_slice)
+                .unwrap_or(&[])
+            {
+                if !component_by_node.contains_key(neighbor) {
+                    component_by_node.insert(neighbor.clone(), component_id);
+                    stack.push(neighbor.clone());
+                }
+            }
+        }
+        component_sizes.push(size);
+    }
+
+    let mut result = CycleAnalysis::default();
+    for edge in edges {
+        let source_component = component_by_node.get(&edge.source_id);
+        let target_component = component_by_node.get(&edge.target_id);
+        if source_component.is_some()
+            && source_component == target_component
+            && (component_sizes
+                .get(source_component.copied().unwrap_or_default())
+                .copied()
+                .unwrap_or_default()
+                > 1
+                || edge.source_id == edge.target_id)
+        {
+            result.cyclic_node_ids.insert(edge.source_id.clone());
+            result.cyclic_node_ids.insert(edge.target_id.clone());
+            result.cyclic_edge_ids.insert(edge.id.clone());
+        }
+    }
+    result
+}
+
+fn audit_asset_producers(
+    records: &[serde_json::Value],
+    task_ids: &BTreeSet<String>,
+) -> BTreeMap<String, String> {
+    let mut candidates = BTreeMap::<String, BTreeSet<String>>::new();
+    for record in records {
+        if record.get("recordType").and_then(serde_json::Value::as_str)
+            != Some("agent.runtime.canvas.asset_generate")
+        {
+            continue;
+        }
+        let Some(asset_id) = record
+            .get("assetId")
+            .and_then(serde_json::Value::as_str)
+            .map(str::trim)
+            .filter(|value| !value.is_empty())
+        else {
+            continue;
+        };
+        let Some(agent_id) = record
+            .get("agentId")
+            .and_then(serde_json::Value::as_str)
+            .map(str::trim)
+            .filter(|value| task_ids.contains(*value))
+        else {
+            continue;
+        };
+        candidates
+            .entry(asset_id.to_string())
+            .or_default()
+            .insert(agent_id.to_string());
+    }
+    candidates
+        .into_iter()
+        .filter_map(|(asset_id, agents)| {
+            (agents.len() == 1).then(|| (asset_id, agents.into_iter().next().unwrap_or_default()))
+        })
+        .collect()
+}
+
+pub(crate) fn build_project_resource_graph(
+    manifest: &GameCreationAppManifest,
+    resources: Vec<ProjectResourceGraphNodeInput>,
+    agent_db_records: &[serde_json::Value],
+    producer_mapping_truncated: bool,
+) -> ProjectResourceGraphReadModel {
+    let resource_by_id = resources
+        .into_iter()
+        .filter_map(|mut resource| {
+            resource.resource_id = resource.resource_id.trim().to_string();
+            (!resource.resource_id.is_empty()).then_some((resource.resource_id.clone(), resource))
+        })
+        .collect::<BTreeMap<_, _>>();
+    let task_by_id = manifest
+        .tasks
+        .iter()
+        .map(|task| (task.id.clone(), task))
+        .collect::<BTreeMap<_, _>>();
+    let task_ids = task_by_id.keys().cloned().collect::<BTreeSet<_>>();
+    let manifest_asset_by_id = manifest
+        .assets
+        .iter()
+        .map(|asset| (asset.id.clone(), asset))
+        .collect::<BTreeMap<_, _>>();
+    let audit_producer_by_asset_id = audit_asset_producers(agent_db_records, &task_ids);
+
+    let mut resource_ids_by_manifest_asset = BTreeMap::<String, Vec<String>>::new();
+    for resource in resource_by_id.values() {
+        if let Some(asset_id) = resource
+            .manifest_asset_id
+            .as_deref()
+            .map(str::trim)
+            .filter(|asset_id| manifest_asset_by_id.contains_key(*asset_id))
+        {
+            resource_ids_by_manifest_asset
+                .entry(asset_id.to_string())
+                .or_default()
+                .push(resource.resource_id.clone());
+        }
+    }
+
+    let mut producer_by_resource_id = BTreeMap::<String, String>::new();
+    for resource in resource_by_id.values() {
+        let producer = if let Some(asset_id) = resource
+            .manifest_asset_id
+            .as_deref()
+            .map(str::trim)
+            .filter(|asset_id| {
+                resource_ids_by_manifest_asset
+                    .get(*asset_id)
+                    .is_some_and(|resource_ids| resource_ids.len() == 1)
+            }) {
+            audit_producer_by_asset_id.get(asset_id).cloned()
+        } else {
+            resource
+                .producer_task_id
+                .as_deref()
+                .map(str::trim)
+                .filter(|task_id| task_ids.contains(*task_id))
+                .map(ToOwned::to_owned)
+        };
+        if let Some(producer) = producer {
+            producer_by_resource_id.insert(resource.resource_id.clone(), producer);
+        }
+    }
+
+    let mut resources_by_task = BTreeMap::<String, Vec<String>>::new();
+    for (resource_id, task_id) in &producer_by_resource_id {
+        resources_by_task
+            .entry(task_id.clone())
+            .or_default()
+            .push(resource_id.clone());
+    }
+
+    let mut resources_by_external_id = BTreeMap::<String, Vec<String>>::new();
+    for (asset_id, resource_ids) in &resource_ids_by_manifest_asset {
+        if resource_ids.len() != 1 {
+            continue;
+        }
+        let Some(external_resource_id) = manifest_asset_by_id
+            .get(asset_id)
+            .and_then(|asset| asset.source.resource_id.as_deref())
+            .map(str::trim)
+            .filter(|value| !value.is_empty())
+        else {
+            continue;
+        };
+        resources_by_external_id
+            .entry(external_resource_id.to_string())
+            .or_default()
+            .push(resource_ids[0].clone());
+    }
+
+    let mut unresolved_reference_resource_ids = BTreeSet::new();
+    let mut reference_edge_by_id = BTreeMap::<String, ProjectResourceReferenceEdge>::new();
+    for (asset_id, target_resource_ids) in &resource_ids_by_manifest_asset {
+        if target_resource_ids.len() != 1 {
+            continue;
+        }
+        let Some(asset) = manifest_asset_by_id.get(asset_id) else {
+            continue;
+        };
+        let target_resource_id = &target_resource_ids[0];
+        for external_reference_id in asset
+            .source
+            .reference_resource_ids
+            .iter()
+            .map(|value| value.trim())
+            .filter(|value| !value.is_empty())
+            .collect::<BTreeSet<_>>()
+        {
+            let source_candidates = resources_by_external_id
+                .get(external_reference_id)
+                .map(Vec::as_slice)
+                .unwrap_or(&[]);
+            if source_candidates.len() != 1 {
+                unresolved_reference_resource_ids.insert(external_reference_id.to_string());
+                continue;
+            }
+            let source_resource_id = &source_candidates[0];
+            if !resource_by_id.contains_key(source_resource_id)
+                || !resource_by_id.contains_key(target_resource_id)
+            {
+                continue;
+            }
+            let id = stable_edge_id("asset-reference", source_resource_id, target_resource_id);
+            reference_edge_by_id.insert(
+                id.clone(),
+                ProjectResourceReferenceEdge {
+                    id,
+                    kind: "asset-reference".to_string(),
+                    source_resource_id: source_resource_id.clone(),
+                    target_resource_id: target_resource_id.clone(),
+                    cyclic: false,
+                },
+            );
+        }
+    }
+    let reference_directed_edges = reference_edge_by_id
+        .values()
+        .map(|edge| DirectedEdge {
+            id: edge.id.clone(),
+            source_id: edge.source_resource_id.clone(),
+            target_id: edge.target_resource_id.clone(),
+        })
+        .collect::<Vec<_>>();
+    let reference_cycles =
+        analyze_directed_cycles(resource_by_id.keys(), &reference_directed_edges);
+    let reference_edges = reference_edge_by_id
+        .into_values()
+        .map(|mut edge| {
+            edge.cyclic = reference_cycles.cyclic_edge_ids.contains(&edge.id);
+            edge
+        })
+        .collect::<Vec<_>>();
+
+    let task_dependency_edges = manifest
+        .tasks
+        .iter()
+        .flat_map(|target_task| {
+            target_task
+                .dependencies
+                .iter()
+                .collect::<BTreeSet<_>>()
+                .into_iter()
+                .filter(|source_task_id| task_by_id.contains_key(*source_task_id))
+                .map(|source_task_id| DirectedEdge {
+                    id: stable_edge_id("task-flow", source_task_id, &target_task.id),
+                    source_id: source_task_id.clone(),
+                    target_id: target_task.id.clone(),
+                })
+                .collect::<Vec<_>>()
+        })
+        .collect::<Vec<_>>();
+    let task_cycles = analyze_directed_cycles(task_by_id.keys(), &task_dependency_edges);
+    let task_flows = task_dependency_edges
+        .iter()
+        .filter_map(|edge| {
+            let source_resource_ids = resources_by_task.get(&edge.source_id)?;
+            let target_resource_ids = resources_by_task.get(&edge.target_id)?;
+            (!source_resource_ids.is_empty() && !target_resource_ids.is_empty()).then(|| {
+                ProjectResourceTaskFlow {
+                    id: edge.id.clone(),
+                    kind: "task-flow".to_string(),
+                    source_task_id: edge.source_id.clone(),
+                    target_task_id: edge.target_id.clone(),
+                    source_resource_ids: source_resource_ids.clone(),
+                    target_resource_ids: target_resource_ids.clone(),
+                    cyclic: task_cycles.cyclic_edge_ids.contains(&edge.id),
+                }
+            })
+        })
+        .collect::<Vec<_>>();
+
+    let mut connection_by_resource_id = resource_by_id
+        .keys()
+        .map(|resource_id| (resource_id.clone(), MutableConnectionIndex::default()))
+        .collect::<BTreeMap<_, _>>();
+    for edge in &reference_edges {
+        if let Some(target) = connection_by_resource_id.get_mut(&edge.target_resource_id) {
+            target
+                .upstream_reference_resource_ids
+                .insert(edge.source_resource_id.clone());
+            target.reference_edge_ids.insert(edge.id.clone());
+        }
+        if let Some(source) = connection_by_resource_id.get_mut(&edge.source_resource_id) {
+            source
+                .downstream_reference_resource_ids
+                .insert(edge.target_resource_id.clone());
+            source.reference_edge_ids.insert(edge.id.clone());
+        }
+    }
+    for flow in &task_flows {
+        for resource_id in flow
+            .source_resource_ids
+            .iter()
+            .chain(flow.target_resource_ids.iter())
+        {
+            if let Some(index) = connection_by_resource_id.get_mut(resource_id) {
+                index.task_flow_ids.insert(flow.id.clone());
+            }
+        }
+    }
+
+    ProjectResourceGraphReadModel {
+        resource_ids: resource_by_id.keys().cloned().collect(),
+        reference_edges,
+        task_flows,
+        connection_index: connection_by_resource_id
+            .into_iter()
+            .map(|(resource_id, index)| ProjectResourceConnectionIndex {
+                resource_id,
+                upstream_reference_resource_ids: index
+                    .upstream_reference_resource_ids
+                    .into_iter()
+                    .collect(),
+                downstream_reference_resource_ids: index
+                    .downstream_reference_resource_ids
+                    .into_iter()
+                    .collect(),
+                reference_edge_ids: index.reference_edge_ids.into_iter().collect(),
+                task_flow_ids: index.task_flow_ids.into_iter().collect(),
+            })
+            .collect(),
+        producer_assignments: producer_by_resource_id
+            .into_iter()
+            .map(|(resource_id, task_id)| ProjectResourceProducerAssignment {
+                resource_id,
+                task_id,
+            })
+            .collect(),
+        unresolved_reference_resource_ids: unresolved_reference_resource_ids.into_iter().collect(),
+        cyclic_resource_ids: reference_cycles.cyclic_node_ids.into_iter().collect(),
+        cyclic_task_ids: task_cycles.cyclic_node_ids.into_iter().collect(),
+        producer_mapping_truncated,
+    }
+}
+
+pub(crate) fn read_project_resource_graph_at(
+    root: &Path,
+    expected_project_id: &str,
+    resources: Vec<ProjectResourceGraphNodeInput>,
+) -> Result<ProjectResourceGraphReadModel, String> {
+    let manifest = read_existing_manifest_for_project(root)?;
+    if manifest.project_id != expected_project_id {
+        return Err("资源依赖图项目身份不匹配".to_string());
+    }
+    let (records, truncated) =
+        read_agent_db_records_bounded(root, RESOURCE_GRAPH_AGENT_DB_READ_BYTES)?;
+    Ok(build_project_resource_graph(
+        &manifest, resources, &records, truncated,
+    ))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn resource(
+        resource_id: &str,
+        manifest_asset_id: Option<&str>,
+        producer_task_id: Option<&str>,
+    ) -> ProjectResourceGraphNodeInput {
+        ProjectResourceGraphNodeInput {
+            resource_id: resource_id.to_string(),
+            manifest_asset_id: manifest_asset_id.map(ToOwned::to_owned),
+            producer_task_id: producer_task_id.map(ToOwned::to_owned),
+        }
+    }
+
+    fn asset(
+        id: &str,
+        external_resource_id: Option<&str>,
+        references: &[&str],
+        external_task_id: Option<&str>,
+    ) -> GameCreationAppAssetManifestEntry {
+        GameCreationAppAssetManifestEntry {
+            id: id.to_string(),
+            kind: "test".to_string(),
+            media_type: "image/png".to_string(),
+            local_path: format!("assets/{id}.png"),
+            source: GameCreationAppAssetSource {
+                kind: GameCreationAppAssetSourceKind::Canvas,
+                canvas_project_id: None,
+                resource_id: external_resource_id.map(ToOwned::to_owned),
+                asset_object_id: None,
+                task_id: external_task_id.map(ToOwned::to_owned),
+                prompt: None,
+                model: None,
+                generation_route: None,
+                generation_kind: None,
+                reference_resource_ids: references.iter().map(|value| value.to_string()).collect(),
+            },
+        }
+    }
+
+    fn task(id: &str, dependencies: &[&str]) -> GameCreationAppTaskState {
+        GameCreationAppTaskState {
+            id: id.to_string(),
+            title: id.to_string(),
+            group: GameCreationAppAgentGroup::Art,
+            role: "test".to_string(),
+            dependencies: dependencies.iter().map(|value| value.to_string()).collect(),
+            artifacts: Vec::new(),
+            acceptance_criteria: Vec::new(),
+            status: GameCreationAppTaskStatus::Completed,
+        }
+    }
+
+    fn manifest(
+        tasks: Vec<GameCreationAppTaskState>,
+        assets: Vec<GameCreationAppAssetManifestEntry>,
+    ) -> GameCreationAppManifest {
+        let mut manifest = new_game_creation_app_manifest("graph-project", "Graph project");
+        manifest.tasks = tasks;
+        manifest.assets = assets;
+        manifest
+    }
+
+    #[test]
+    fn graph_uses_runtime_agent_identity_instead_of_external_task_id() {
+        let manifest = manifest(
+            vec![
+                task("art-director", &[]),
+                task("design-foundation", &["art-director"]),
+            ],
+            vec![
+                asset("spec", Some("external-spec"), &[], Some("task-1")),
+                asset(
+                    "ui",
+                    Some("external-ui"),
+                    &["external-spec"],
+                    Some("task-2"),
+                ),
+            ],
+        );
+        let records = vec![
+            serde_json::json!({
+                "recordType": "agent.runtime.canvas.asset_generate",
+                "assetId": "spec",
+                "agentId": "art-director"
+            }),
+            serde_json::json!({
+                "recordType": "agent.runtime.canvas.asset_generate",
+                "assetId": "ui",
+                "agentId": "design-foundation"
+            }),
+        ];
+        let graph = build_project_resource_graph(
+            &manifest,
+            vec![
+                resource("asset:spec", Some("spec"), None),
+                resource("asset:ui", Some("ui"), None),
+            ],
+            &records,
+            false,
+        );
+
+        assert_eq!(graph.reference_edges.len(), 1);
+        assert_eq!(graph.task_flows.len(), 1);
+        assert_eq!(graph.task_flows[0].source_task_id, "art-director");
+        assert_eq!(graph.task_flows[0].target_task_id, "design-foundation");
+        assert!(graph
+            .producer_assignments
+            .iter()
+            .all(|assignment| assignment.task_id != "task-1" && assignment.task_id != "task-2"));
+    }
+
+    #[test]
+    fn graph_omits_task_flow_without_reliable_runtime_producer_evidence() {
+        let manifest = manifest(
+            vec![
+                task("art-director", &[]),
+                task("design-foundation", &["art-director"]),
+            ],
+            vec![
+                asset("spec", Some("external-spec"), &[], Some("art-director")),
+                asset(
+                    "ui",
+                    Some("external-ui"),
+                    &["external-spec"],
+                    Some("design-foundation"),
+                ),
+            ],
+        );
+        let graph = build_project_resource_graph(
+            &manifest,
+            vec![
+                resource("asset:spec", Some("spec"), None),
+                resource("asset:ui", Some("ui"), None),
+            ],
+            &[],
+            false,
+        );
+
+        assert_eq!(graph.reference_edges.len(), 1);
+        assert!(graph.task_flows.is_empty());
+        assert!(graph.producer_assignments.is_empty());
+    }
+
+    #[test]
+    fn graph_aggregates_flows_filters_missing_resources_and_detects_cycles_iteratively() {
+        let manifest = manifest(
+            vec![task("task-a", &["task-b"]), task("task-b", &["task-a"])],
+            vec![
+                asset(
+                    "a",
+                    Some("external-a"),
+                    &["external-b", "missing"],
+                    Some("task-1"),
+                ),
+                asset("b", Some("external-b"), &["external-a"], Some("task-2")),
+            ],
+        );
+        let records = vec![
+            serde_json::json!({"recordType": "agent.runtime.canvas.asset_generate", "assetId": "a", "agentId": "task-a"}),
+            serde_json::json!({"recordType": "agent.runtime.canvas.asset_generate", "assetId": "b", "agentId": "task-b"}),
+        ];
+        let graph = build_project_resource_graph(
+            &manifest,
+            vec![
+                resource("asset:a", Some("a"), None),
+                resource("asset:b", Some("b"), None),
+                resource("task-a:artifact", None, Some("task-a")),
+                resource("task-b:artifact", None, Some("task-b")),
+            ],
+            &records,
+            false,
+        );
+
+        assert_eq!(graph.reference_edges.len(), 2);
+        assert!(graph.reference_edges.iter().all(|edge| edge.cyclic));
+        assert_eq!(graph.task_flows.len(), 2);
+        assert!(graph.task_flows.iter().all(|flow| flow.cyclic));
+        assert_eq!(graph.unresolved_reference_resource_ids, vec!["missing"]);
+        assert_eq!(graph.cyclic_resource_ids, vec!["asset:a", "asset:b"]);
+        assert_eq!(graph.cyclic_task_ids, vec!["task-a", "task-b"]);
+        assert!(
+            graph
+                .task_flows
+                .iter()
+                .all(|flow| flow.source_resource_ids.len() == 2
+                    && flow.target_resource_ids.len() == 2)
+        );
+    }
+
+    #[test]
+    fn graph_handles_4096_task_chain_without_recursive_traversal_or_cartesian_edges() {
+        let tasks = (0..4096)
+            .map(|index| {
+                let id = format!("task:{index}");
+                let dependencies = if index == 0 {
+                    Vec::new()
+                } else {
+                    vec![format!("task:{}", index - 1)]
+                };
+                GameCreationAppTaskState {
+                    id: id.clone(),
+                    title: id,
+                    group: GameCreationAppAgentGroup::Code,
+                    role: "test".to_string(),
+                    dependencies,
+                    artifacts: Vec::new(),
+                    acceptance_criteria: Vec::new(),
+                    status: GameCreationAppTaskStatus::Completed,
+                }
+            })
+            .collect::<Vec<_>>();
+        let resources = (0..4096)
+            .map(|index| {
+                resource(
+                    &format!("resource:{index}"),
+                    None,
+                    Some(&format!("task:{index}")),
+                )
+            })
+            .collect::<Vec<_>>();
+        let graph =
+            build_project_resource_graph(&manifest(tasks, Vec::new()), resources, &[], false);
+
+        assert_eq!(graph.task_flows.len(), 4095);
+        assert_eq!(graph.connection_index.len(), 4096);
+        assert!(graph
+            .connection_index
+            .iter()
+            .all(|index| index.task_flow_ids.len() <= 2));
+    }
+}
diff --git a/apps/ai-game-creator-shell/src/view/project-development/ResourceDependencyOverlay.tsx b/apps/ai-game-creator-shell/src/view/project-development/ResourceDependencyOverlay.tsx
index a3ffc1ab4..238abba58 100644
--- a/apps/ai-game-creator-shell/src/view/project-development/ResourceDependencyOverlay.tsx
+++ b/apps/ai-game-creator-shell/src/view/project-development/ResourceDependencyOverlay.tsx
@@ -27,9 +27,14 @@ type Rect = Point & {
 
 type SectionOrigins = Partial<Record<ProjectResourceCanvasSection, Point>>;
 
+type RectLookup = {
+  get(resourceId: string): Rect | undefined;
+};
+
 export type ResourceDependencyOverlayProps = {
   graph: ProjectResourceGraph;
   positions: readonly ProjectResourceCanvasPosition[];
+  dragPreview: (Point & { resourceId: string }) | null;
   visibleResourceIds: ReadonlySet<string>;
   selectedResourceId: string | null;
 };
@@ -117,7 +122,7 @@ function rectAnchor(rect: Rect, direction: 1 | -1): Point {
 
 function referenceGeometry(
   edge: ProjectResourceReferenceEdge,
-  rectByResourceId: ReadonlyMap<string, Rect>,
+  rectByResourceId: RectLookup,
 ) {
   const sourceRect = rectByResourceId.get(edge.sourceResourceId);
   const targetRect = rectByResourceId.get(edge.targetResourceId);
@@ -148,7 +153,7 @@ function referenceGeometry(
 
 function taskFlowGeometry(
   flow: ProjectResourceTaskFlow,
-  rectByResourceId: ReadonlyMap<string, Rect>,
+  rectByResourceId: RectLookup,
 ) {
   const sourceRects = flow.sourceResourceIds.flatMap((resourceId) => {
     const rect = rectByResourceId.get(resourceId);
@@ -198,11 +203,15 @@ function taskFlowGeometry(
 export function ResourceDependencyOverlay({
   graph,
   positions,
+  dragPreview,
   visibleResourceIds,
   selectedResourceId,
 }: ResourceDependencyOverlayProps) {
   const markerPrefix = useId().replace(/[^a-zA-Z0-9_-]/gu, '');
   const overlayRef = useRef<SVGSVGElement>(null);
+  const referencePathRefs = useRef(new Map<string, SVGPathElement>());
+  const taskFlowGroupRefs = useRef(new Map<string, SVGGElement>());
+  const activeDragResourceIdRef = useRef<string | null>(null);
   const [sectionOrigins, setSectionOrigins] = useState<SectionOrigins>({});
 
   useLayoutEffect(() => {
@@ -257,7 +266,7 @@ export function ResourceDependencyOverlay({
       observer?.disconnect();
       window.removeEventListener('resize', scheduleMeasure);
     };
-  }, [graph, positions, visibleResourceIds]);
+  }, []);
 
   const rectByResourceId = useMemo(() => {
     const result = new Map<string, Rect>();
@@ -290,6 +299,216 @@ export function ResourceDependencyOverlay({
     selectedResourceId && graph.resourceIds.has(selectedResourceId),
   );
 
+  const renderTaskFlows = useMemo(
+    () =>
+      graph.taskFlows.map((flow) => {
+        const geometry = taskFlowGeometry(flow, rectByResourceId);
+        if (!geometry) {
+          return null;
+        }
+        const highlighted = neighbors.connectedEdgeIds.has(flow.id);
+        const className = `game-resource-dependency-edge game-resource-dependency-edge--task${
+          highlighted ? ' is-highlighted' : selected ? ' is-dimmed' : ''
+        }${flow.cyclic ? ' is-cyclic' : ''}`;
+        return (
+          <g
+            ref={(node) => {
+              if (node) {
+                taskFlowGroupRefs.current.set(flow.id, node);
+              } else {
+                taskFlowGroupRefs.current.delete(flow.id);
+              }
+            }}
+            key={flow.id}
+            className={className}
+            data-edge-kind="task-flow"
+            data-edge-id={flow.id}
+            data-source-task-id={flow.sourceTaskId}
+            data-target-task-id={flow.targetTaskId}
+            data-cyclic={flow.cyclic || undefined}
+          >
+            <title>{`任务流转：${flow.sourceTaskId} → ${flow.targetTaskId}${
+              flow.cyclic ? '（检测到依赖环）' : ''
+            }`}</title>
+            {geometry.sourceAnchors.map(({ resourceId, point }) => (
+              <path
+                key={`source:${resourceId}`}
+                className="game-resource-dependency-branch"
+                data-branch-side="source"
+                data-resource-id={resourceId}
+                d={taskFlowBranchPath(point, geometry.sourceHub)}
+              />
+            ))}
+            <path
+              className="game-resource-dependency-trunk"
+              d={connectionPath(geometry.sourceHub, geometry.targetHub)}
+            />
+            {geometry.targetAnchors.map(({ resourceId, point }) => (
+              <path
+                key={`target:${resourceId}`}
+                className="game-resource-dependency-branch"
+                data-branch-side="target"
+                data-resource-id={resourceId}
+                d={taskFlowBranchPath(geometry.targetHub, point)}
+                markerEnd={`url(#${markerPrefix}-task-flow-arrow)`}
+              />
+            ))}
+          </g>
+        );
+      }),
+    [
+      graph.taskFlows,
+      markerPrefix,
+      neighbors.connectedEdgeIds,
+      rectByResourceId,
+      selected,
+    ],
+  );
+
+  const renderReferenceEdges = useMemo(
+    () =>
+      graph.referenceEdges.map((edge) => {
+        const geometry = referenceGeometry(edge, rectByResourceId);
+        if (!geometry) {
+          return null;
+        }
+        const highlighted = neighbors.connectedEdgeIds.has(edge.id);
+        const className = `game-resource-dependency-edge game-resource-dependency-edge--reference${
+          highlighted ? ' is-highlighted' : selected ? ' is-dimmed' : ''
+        }${edge.cyclic ? ' is-cyclic' : ''}`;
+        return (
+          <path
+            ref={(node) => {
+              if (node) {
+                referencePathRefs.current.set(edge.id, node);
+              } else {
+                referencePathRefs.current.delete(edge.id);
+              }
+            }}
+            key={edge.id}
+            className={className}
+            data-edge-kind="asset-reference"
+            data-edge-id={edge.id}
+            data-source-resource-id={edge.sourceResourceId}
+            data-target-resource-id={edge.targetResourceId}
+            data-cyclic={edge.cyclic || undefined}
+            data-self-loop={geometry.selfLoop || undefined}
+            d={geometry.path}
+            markerEnd={`url(#${markerPrefix}-asset-reference-arrow)`}
+          >
+            <title>{`资源引用${edge.cyclic ? '（检测到依赖环）' : ''}`}</title>
+          </path>
+        );
+      }),
+    [
+      graph.referenceEdges,
+      markerPrefix,
+      neighbors.connectedEdgeIds,
+      rectByResourceId,
+      selected,
+    ],
+  );
+
+  useLayoutEffect(() => {
+    const affectedResourceIds = new Set<string>();
+    if (activeDragResourceIdRef.current) {
+      affectedResourceIds.add(activeDragResourceIdRef.current);
+    }
+    if (dragPreview) {
+      affectedResourceIds.add(dragPreview.resourceId);
+    }
+    activeDragResourceIdRef.current = dragPreview?.resourceId ?? null;
+    if (affectedResourceIds.size === 0) {
+      return;
+    }
+    const dragBasePosition = dragPreview
+      ? positions.find(
+          (position) => position.resourceId === dragPreview.resourceId,
+        )
+      : undefined;
+    const rectLookup = {
+      get(resourceId: string) {
+        const rect = rectByResourceId.get(resourceId);
+        if (!rect) {
+          return undefined;
+        }
+        return dragPreview?.resourceId === resourceId
+          ? {
+              ...rect,
+              x:
+                rect.x - (dragBasePosition?.x ?? 0) + dragPreview.x,
+              y:
+                rect.y - (dragBasePosition?.y ?? 0) + dragPreview.y,
+            }
+          : rect;
+      },
+    };
+    const affectedEdgeIds = new Set<string>();
+    for (const resourceId of affectedResourceIds) {
+      const index = graph.connectionIndex.get(resourceId);
+      index?.referenceEdgeIds.forEach((edgeId) =>
+        affectedEdgeIds.add(edgeId),
+      );
+      index?.taskFlowIds.forEach((flowId) => affectedEdgeIds.add(flowId));
+    }
+    for (const edgeId of affectedEdgeIds) {
+      const referenceEdge = graph.referenceEdgeById.get(edgeId);
+      if (referenceEdge) {
+        const geometry = referenceGeometry(referenceEdge, rectLookup);
+        const path = referencePathRefs.current.get(edgeId);
+        if (geometry && path) {
+          path.setAttribute('d', geometry.path);
+        }
+        continue;
+      }
+      const flow = graph.taskFlowById.get(edgeId);
+      const group = taskFlowGroupRefs.current.get(edgeId);
+      if (!flow || !group) {
+        continue;
+      }
+      const geometry = taskFlowGeometry(flow, rectLookup);
+      if (!geometry) {
+        continue;
+      }
+      const sourcePathByResourceId = new Map<string, SVGPathElement>();
+      const targetPathByResourceId = new Map<string, SVGPathElement>();
+      group
+        .querySelectorAll<SVGPathElement>('.game-resource-dependency-branch')
+        .forEach((path) => {
+          const resourceId = path.dataset.resourceId;
+          if (!resourceId) {
+            return;
+          }
+          (path.dataset.branchSide === 'source'
+            ? sourcePathByResourceId
+            : targetPathByResourceId
+          ).set(resourceId, path);
+        });
+      geometry.sourceAnchors.forEach(({ resourceId, point }) => {
+        sourcePathByResourceId
+          .get(resourceId)
+          ?.setAttribute(
+            'd',
+            taskFlowBranchPath(point, geometry.sourceHub),
+          );
+      });
+      group
+        .querySelector<SVGPathElement>('.game-resource-dependency-trunk')
+        ?.setAttribute(
+          'd',
+          connectionPath(geometry.sourceHub, geometry.targetHub),
+        );
+      geometry.targetAnchors.forEach(({ resourceId, point }) => {
+        targetPathByResourceId
+          .get(resourceId)
+          ?.setAttribute(
+            'd',
+            taskFlowBranchPath(geometry.targetHub, point),
+          );
+      });
+    }
+  }, [dragPreview, graph, positions, rectByResourceId]);
+
   return (
     <svg
       ref={overlayRef}
@@ -327,79 +546,8 @@ export function ResourceDependencyOverlay({
         </marker>
       </defs>
 
-      {graph.taskFlows.map((flow) => {
-        const geometry = taskFlowGeometry(flow, rectByResourceId);
-        if (!geometry) {
-          return null;
-        }
-        const highlighted = neighbors.connectedEdgeIds.has(flow.id);
-        const className = `game-resource-dependency-edge game-resource-dependency-edge--task${
-          highlighted ? ' is-highlighted' : selected ? ' is-dimmed' : ''
-        }${flow.cyclic ? ' is-cyclic' : ''}`;
-        return (
-          <g
-            key={flow.id}
-            className={className}
-            data-edge-kind="task-flow"
-            data-edge-id={flow.id}
-            data-source-task-id={flow.sourceTaskId}
-            data-target-task-id={flow.targetTaskId}
-            data-cyclic={flow.cyclic || undefined}
-          >
-            <title>{`任务流转：${flow.sourceTaskId} → ${flow.targetTaskId}${
-              flow.cyclic ? '（检测到依赖环）' : ''
-            }`}</title>
-            {geometry.sourceAnchors.map(({ resourceId, point }) => (
-              <path
-                key={`source:${resourceId}`}
-                className="game-resource-dependency-branch"
-                data-resource-id={resourceId}
-                d={taskFlowBranchPath(point, geometry.sourceHub)}
-              />
-            ))}
-            <path
-              className="game-resource-dependency-trunk"
-              d={connectionPath(geometry.sourceHub, geometry.targetHub)}
-            />
-            {geometry.targetAnchors.map(({ resourceId, point }) => (
-              <path
-                key={`target:${resourceId}`}
-                className="game-resource-dependency-branch"
-                data-resource-id={resourceId}
-                d={taskFlowBranchPath(geometry.targetHub, point)}
-                markerEnd={`url(#${markerPrefix}-task-flow-arrow)`}
-              />
-            ))}
-          </g>
-        );
-      })}
-
-      {graph.referenceEdges.map((edge) => {
-        const geometry = referenceGeometry(edge, rectByResourceId);
-        if (!geometry) {
-          return null;
-        }
-        const highlighted = neighbors.connectedEdgeIds.has(edge.id);
-        const className = `game-resource-dependency-edge game-resource-dependency-edge--reference${
-          highlighted ? ' is-highlighted' : selected ? ' is-dimmed' : ''
-        }${edge.cyclic ? ' is-cyclic' : ''}`;
-        return (
-          <path
-            key={edge.id}
-            className={className}
-            data-edge-kind="asset-reference"
-            data-edge-id={edge.id}
-            data-source-resource-id={edge.sourceResourceId}
-            data-target-resource-id={edge.targetResourceId}
-            data-cyclic={edge.cyclic || undefined}
-            data-self-loop={geometry.selfLoop || undefined}
-            d={geometry.path}
-            markerEnd={`url(#${markerPrefix}-asset-reference-arrow)`}
-          >
-            <title>{`资源引用${edge.cyclic ? '（检测到依赖环）' : ''}`}</title>
-          </path>
-        );
-      })}
+      {renderTaskFlows}
+      {renderReferenceEdges}
     </svg>
   );
 }
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 b391a4a74..3d8ed61bc 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
@@ -43,12 +43,20 @@ import {
   resolveEmbeddedPreviewUrl,
 } from '../../features/project-workspace/LocalGamePreviewFrame';
 import {
+  RESOURCE_CANVAS_CARD_HEIGHT,
+  RESOURCE_CANVAS_CARD_WIDTH,
+  RESOURCE_CANVAS_COLUMN_GAP,
   RESOURCE_CANVAS_DRAG_THRESHOLD,
+  RESOURCE_CANVAS_ROW_GAP,
   resourceCanvasSectionExtent,
 } from './resourceCanvasLayoutModel';
 import {
-  createProjectResourceGraph,
+  EMPTY_PROJECT_RESOURCE_GRAPH,
+  normalizeProjectResourceGraph,
+  type ProjectResourceGraph,
   projectResourceGraphNeighbors,
+  type ProjectResourceGraphNodeInput,
+  type ProjectResourceGraphReadModel,
 } from './resourceDependencyGraphModel';
 import { ResourceDependencyOverlay } from './ResourceDependencyOverlay';
 import { useProjectResourceCanvasLayout } from './useProjectResourceCanvasLayout';
@@ -91,6 +99,7 @@ type ProjectResource = {
   mediaType: string;
   sourceLabel: string;
   taskTitle: string | null;
+  manifestAssetId: string | null;
   producerTaskId: string | null;
   externalResourceId: string | null;
   referenceResourceIds: string[];
@@ -139,6 +148,7 @@ export type ProjectAgentRuntimeSummary = {
 
 const emptyProjectAgentRuntimeSummaries: ProjectAgentRuntimeSummary[] = [];
 const emptyProjectAgentResults: ProjectAgentResultSummary[] = [];
+const RESOURCE_DEPENDENCY_VISUAL_GUTTER = 64;
 
 type AgentSummary = ProjectAgentRuntimeSummary;
 
@@ -318,6 +328,7 @@ function resourcesFromProject(
         mediaType: category === 'document' ? '项目文档' : '项目产物',
         sourceLabel: '任务产物',
         taskTitle: task.title,
+        manifestAssetId: null,
         producerTaskId: task.id,
         externalResourceId: null,
         referenceResourceIds: [],
@@ -328,9 +339,6 @@ function resourcesFromProject(
   }
 
   for (const asset of manifest.assets) {
-    const task = asset.source.taskId
-      ? taskById.get(asset.source.taskId)
-      : undefined;
     const isPendingUiPrototype =
       asset.kind === 'ui-prototype' &&
       taskById.get('design-foundation')?.status !== 'completed';
@@ -351,12 +359,13 @@ function resourcesFromProject(
             : asset.source.kind === 'generated'
               ? 'Agent 生成'
               : '用户上传',
-      taskTitle: task?.title ?? null,
-      producerTaskId: task?.id ?? null,
+      taskTitle: null,
+      manifestAssetId: asset.id,
+      producerTaskId: null,
       externalResourceId: asset.source.resourceId ?? null,
       referenceResourceIds: asset.source.referenceResourceIds ?? [],
-      dependencies: task?.dependencies ?? [],
-      dependencyDepth: task ? taskDependencyDepth(task, taskById) : 0,
+      dependencies: [],
+      dependencyDepth: 0,
     });
   }
 
@@ -376,6 +385,7 @@ function resourcesFromProject(
       mediaType: attachment.mediaType || '未知媒体类型',
       sourceLabel: '用户上传',
       taskTitle: null,
+      manifestAssetId: null,
       producerTaskId: null,
       externalResourceId: null,
       referenceResourceIds: [],
@@ -394,6 +404,7 @@ function resourcesFromProject(
       mediaType: 'Agent 历史文本回执',
       sourceLabel: `历史成果 · ${result.label}`,
       taskTitle: null,
+      manifestAssetId: null,
       producerTaskId: taskById.has(result.agentId) ? result.agentId : null,
       externalResourceId: null,
       referenceResourceIds: [],
@@ -552,6 +563,10 @@ export default function ProjectDevelopmentView({
   const dockRef = useRef<HTMLElement>(null);
   const resourceDialogRef = useRef<HTMLElement>(null);
   const resourceCardDragRef = useRef<ResourceCardDrag | null>(null);
+  const pendingResourceDragPreviewRef = useRef<
+    (Point & { resourceId: string }) | null
+  >(null);
+  const resourceDragFrameRef = useRef<number | null>(null);
   const suppressResourceClickRef = useRef<string | null>(null);
   const resourceDialogDragRef = useRef<{
     pointerId: number;
@@ -566,10 +581,121 @@ export default function ProjectDevelopmentView({
     manifest.tasks.some(
       (task) => task.id === 'code-prototype' && task.status === 'completed',
     );
-  const resources = useMemo(
+  const projectedResources = useMemo(
     () => resourcesFromProject(manifest, attachments, agentResults),
     [agentResults, attachments, manifest],
   );
+  const resourceGraphInputs = useMemo<ProjectResourceGraphNodeInput[]>(
+    () =>
+      projectedResources.map((resource) => ({
+        resourceId: resource.id,
+        manifestAssetId: resource.manifestAssetId,
+        producerTaskId: resource.producerTaskId,
+      })),
+    [projectedResources],
+  );
+  const resourceGraphScopeKey = useMemo(
+    () =>
+      JSON.stringify([
+        projectPath,
+        manifest.projectId,
+        resourceGraphInputs,
+      ]),
+    [manifest.projectId, projectPath, resourceGraphInputs],
+  );
+  const [resourceGraphState, setResourceGraphState] = useState<{
+    scopeKey: string;
+    graph: ProjectResourceGraph;
+  }>({ scopeKey: '', graph: EMPTY_PROJECT_RESOURCE_GRAPH });
+
+  useEffect(() => {
+    let cancelled = false;
+    if (sortMode !== 'dependency') {
+      setResourceGraphState({
+        scopeKey: '',
+        graph: EMPTY_PROJECT_RESOURCE_GRAPH,
+      });
+      return () => {
+        cancelled = true;
+      };
+    }
+    const invoke = window.__TAURI__?.core?.invoke;
+    if (!invoke) {
+      setResourceGraphState({
+        scopeKey: resourceGraphScopeKey,
+        graph: EMPTY_PROJECT_RESOURCE_GRAPH,
+      });
+      return () => {
+        cancelled = true;
+      };
+    }
+    void invoke<ProjectResourceGraphReadModel>(
+      'read_local_project_resource_graph',
+      {
+        projectPath,
+        expectedProjectId: manifest.projectId,
+        resources: resourceGraphInputs,
+      },
+    )
+      .then((readModel) => {
+        if (!cancelled) {
+          setResourceGraphState({
+            scopeKey: resourceGraphScopeKey,
+            graph: normalizeProjectResourceGraph(readModel),
+          });
+        }
+      })
+      .catch(() => {
+        if (!cancelled) {
+          setResourceGraphState({
+            scopeKey: resourceGraphScopeKey,
+            graph: EMPTY_PROJECT_RESOURCE_GRAPH,
+          });
+        }
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [
+    manifest.projectId,
+    projectPath,
+    resourceGraphInputs,
+    resourceGraphScopeKey,
+    sortMode,
+  ]);
+
+  const resourceGraph =
+    resourceGraphState.scopeKey === resourceGraphScopeKey
+      ? resourceGraphState.graph
+      : EMPTY_PROJECT_RESOURCE_GRAPH;
+  const manifestTaskById = useMemo(
+    () => new Map(manifest.tasks.map((task) => [task.id, task])),
+    [manifest.tasks],
+  );
+  const resources = useMemo(
+    () =>
+      projectedResources.map((resource) => {
+        const producerTaskId =
+          resourceGraph.producerTaskIdByResourceId.get(resource.id) ??
+          resource.producerTaskId;
+        const producerTask = producerTaskId
+          ? manifestTaskById.get(producerTaskId)
+          : undefined;
+        return producerTask && producerTaskId !== resource.producerTaskId
+          ? {
+              ...resource,
+              taskTitle: producerTask.title,
+              producerTaskId,
+              dependencies: producerTask.dependencies,
+              dependencyDepth: taskDependencyDepth(
+                producerTask,
+                manifestTaskById,
+              ),
+            }
+          : resource;
+      }),
+    [manifestTaskById, projectedResources, resourceGraph],
+  );
   const {
     layout: resourceLayout,
     notice: resourceLayoutNotice,
@@ -581,12 +707,15 @@ export default function ProjectDevelopmentView({
     mode: sortMode,
     resources,
   });
-  const resourcePositionById = new Map(
-    resourceLayout.positions.map((position) => [position.resourceId, position]),
-  );
-  const resourceGraph = useMemo(
-    () => createProjectResourceGraph(resources, manifest.tasks),
-    [manifest.tasks, resources],
+  const resourcePositionById = useMemo(
+    () =>
+      new Map(
+        resourceLayout.positions.map((position) => [
+          position.resourceId,
+          position,
+        ]),
+      ),
+    [resourceLayout.positions],
   );
   const selectedResourceNeighbors = useMemo(
     () => projectResourceGraphNeighbors(resourceGraph, selectedResourceId),
@@ -611,18 +740,41 @@ export default function ProjectDevelopmentView({
     () => new Set(visibleResources.map((resource) => resource.id)),
     [visibleResources],
   );
-  const resourceDependencyPositions = useMemo(
+  const visibleResourcesByCategory = useMemo(
     () =>
-      resourceLayout.positions.map((position) =>
-        resourceDragPreview?.resourceId === position.resourceId
-          ? {
-              ...position,
-              x: resourceDragPreview.x,
-              y: resourceDragPreview.y,
-            }
-          : position,
+      new Map(
+        categoryOrder.map((category) => [
+          category,
+          visibleResources.filter(
+            (resource) => resource.category === category,
+          ),
+        ]),
       ),
-    [resourceDragPreview, resourceLayout.positions],
+    [visibleResources],
+  );
+  const resourcePositionsByCategory = useMemo(
+    () =>
+      new Map(
+        categoryOrder.map((category) => [
+          category,
+          resourceLayout.positions.filter(
+            (position) => position.section === category,
+          ),
+        ]),
+      ),
+    [resourceLayout.positions],
+  );
+  const resourceBaseExtentByCategory = useMemo(
+    () =>
+      new Map(
+        categoryOrder.map((category) => [
+          category,
+          resourceCanvasSectionExtent(
+            resourcePositionsByCategory.get(category) ?? [],
+          ),
+        ]),
+      ),
+    [resourcePositionsByCategory],
   );
   const selectedResource =
     resources.find((resource) => resource.id === selectedResourceId) ?? null;
@@ -665,6 +817,39 @@ export default function ProjectDevelopmentView({
     approvalOptions.find((option) => option.id === approvalMode)?.label ??
     '严格审批';
 
+  const scheduleResourceDragPreview = useCallback(
+    (preview: Point & { resourceId: string }) => {
+      pendingResourceDragPreviewRef.current = preview;
+      if (resourceDragFrameRef.current !== null) {
+        return;
+      }
+      resourceDragFrameRef.current = window.requestAnimationFrame(() => {
+        resourceDragFrameRef.current = null;
+        const pending = pendingResourceDragPreviewRef.current;
+        pendingResourceDragPreviewRef.current = null;
+        if (pending) {
+          setResourceDragPreview(pending);
+        }
+      });
+    },
+    [],
+  );
+
+  const clearScheduledResourceDragPreview = useCallback(() => {
+    pendingResourceDragPreviewRef.current = null;
+    if (resourceDragFrameRef.current !== null) {
+      window.cancelAnimationFrame(resourceDragFrameRef.current);
+      resourceDragFrameRef.current = null;
+    }
+  }, []);
+
+  useEffect(
+    () => () => {
+      clearScheduledResourceDragPreview();
+    },
+    [clearScheduledResourceDragPreview],
+  );
+
   useEffect(() => {
     if (embeddedPreviewUrl) {
       setMode('run');
@@ -674,9 +859,10 @@ export default function ProjectDevelopmentView({
   useEffect(() => {
     setSelectedResourceId(null);
     resourceCardDragRef.current = null;
+    clearScheduledResourceDragPreview();
     setDraggedResourceId(null);
     setResourceDragPreview(null);
-  }, [projectPath]);
+  }, [clearScheduledResourceDragPreview, projectPath]);
 
   useEffect(() => {
     if (!selectedResourceId) {
@@ -812,6 +998,7 @@ export default function ProjectDevelopmentView({
     if (!position || position.section !== resource.category) {
       return;
     }
+    clearScheduledResourceDragPreview();
     resourceCardDragRef.current = {
       pointerId: event.pointerId,
       resourceId: resource.id,
@@ -842,7 +1029,7 @@ export default function ProjectDevelopmentView({
     }
     drag.moved = true;
     setDraggedResourceId(drag.resourceId);
-    setResourceDragPreview({
+    scheduleResourceDragPreview({
       resourceId: drag.resourceId,
       x: Math.max(0, drag.startX + deltaX),
       y: Math.max(0, drag.startY + deltaY),
@@ -858,6 +1045,7 @@ export default function ProjectDevelopmentView({
     if (!drag || drag.pointerId !== event.pointerId) {
       return;
     }
+    clearScheduledResourceDragPreview();
     resourceCardDragRef.current = null;
     if (event.currentTarget.hasPointerCapture?.(event.pointerId)) {
       event.currentTarget.releasePointerCapture?.(event.pointerId);
@@ -1050,29 +1238,49 @@ export default function ProjectDevelopmentView({
                     <ResourceDependencyOverlay
                       key={`${projectPath}:${manifest.projectId}`}
                       graph={resourceGraph}
-                      positions={resourceDependencyPositions}
+                      positions={resourceLayout.positions}
+                      dragPreview={resourceDragPreview}
                       visibleResourceIds={visibleResourceIds}
                       selectedResourceId={selectedResourceId}
                     />
                   ) : null}
                   {categoryOrder.map((category) => {
-                    const categoryResources = visibleResources.filter(
-                      (resource) => resource.category === category,
-                    );
-                    const categoryPositions = resourceLayout.positions.filter(
-                      (position) => position.section === category,
-                    );
-                    const extent = resourceCanvasSectionExtent(
-                      categoryPositions.map((position) =>
-                        resourceDragPreview?.resourceId === position.resourceId
-                          ? {
-                              ...position,
-                              x: resourceDragPreview.x,
-                              y: resourceDragPreview.y,
-                            }
-                          : position,
+                    const categoryResources =
+                      visibleResourcesByCategory.get(category) ?? [];
+                    const baseExtent = resourceBaseExtentByCategory.get(
+                      category,
+                    ) ?? { width: 0, height: 0 };
+                    const dragPosition = resourceDragPreview
+                      ? resourcePositionById.get(
+                          resourceDragPreview.resourceId,
+                        )
+                      : undefined;
+                    const previewInCategory =
+                      dragPosition?.section === category
+                        ? resourceDragPreview
+                        : null;
+                    const extent = {
+                      width:
+                        Math.max(
+                          baseExtent.width,
+                          previewInCategory
+                            ? previewInCategory.x +
+                                RESOURCE_CANVAS_CARD_WIDTH +
+                                RESOURCE_CANVAS_COLUMN_GAP
+                            : 0,
+                        ) +
+                        (sortMode === 'dependency'
+                          ? RESOURCE_DEPENDENCY_VISUAL_GUTTER
+                          : 0),
+                      height: Math.max(
+                        baseExtent.height,
+                        previewInCategory
+                          ? previewInCategory.y +
+                            RESOURCE_CANVAS_CARD_HEIGHT +
+                            RESOURCE_CANVAS_ROW_GAP
+                          : 0,
                       ),
-                    );
+                    };
                     const Icon = categoryIcons[category];
                     return (
                       <section
diff --git a/apps/ai-game-creator-shell/src/view/project-development/resourceDependencyGraphModel.ts b/apps/ai-game-creator-shell/src/view/project-development/resourceDependencyGraphModel.ts
index ea0b5b906..ff46e11c5 100644
--- a/apps/ai-game-creator-shell/src/view/project-development/resourceDependencyGraphModel.ts
+++ b/apps/ai-game-creator-shell/src/view/project-development/resourceDependencyGraphModel.ts
@@ -1,13 +1,7 @@
 export type ProjectResourceGraphNodeInput = {
-  id: string;
+  resourceId: string;
+  manifestAssetId: string | null;
   producerTaskId: string | null;
-  externalResourceId: string | null;
-  referenceResourceIds: readonly string[];
-};
-
-export type ProjectResourceGraphTaskInput = {
-  id: string;
-  dependencies: readonly string[];
 };
 
 export type ProjectResourceReferenceEdge = {
@@ -28,13 +22,50 @@ export type ProjectResourceTaskFlow = {
   cyclic: boolean;
 };
 
+export type ProjectResourceConnectionIndexDto = {
+  resourceId: string;
+  upstreamReferenceResourceIds: string[];
+  downstreamReferenceResourceIds: string[];
+  referenceEdgeIds: string[];
+  taskFlowIds: string[];
+};
+
+export type ProjectResourceProducerAssignment = {
+  resourceId: string;
+  taskId: string;
+};
+
+export type ProjectResourceGraphReadModel = {
+  resourceIds: string[];
+  referenceEdges: ProjectResourceReferenceEdge[];
+  taskFlows: ProjectResourceTaskFlow[];
+  connectionIndex: ProjectResourceConnectionIndexDto[];
+  producerAssignments: ProjectResourceProducerAssignment[];
+  unresolvedReferenceResourceIds: string[];
+  cyclicResourceIds: string[];
+  cyclicTaskIds: string[];
+  producerMappingTruncated: boolean;
+};
+
+type ProjectResourceConnectionIndex = {
+  upstreamReferenceResourceIds: ReadonlySet<string>;
+  downstreamReferenceResourceIds: ReadonlySet<string>;
+  referenceEdgeIds: ReadonlySet<string>;
+  taskFlowIds: ReadonlySet<string>;
+};
+
 export type ProjectResourceGraph = {
   resourceIds: ReadonlySet<string>;
   referenceEdges: ProjectResourceReferenceEdge[];
+  referenceEdgeById: ReadonlyMap<string, ProjectResourceReferenceEdge>;
   taskFlows: ProjectResourceTaskFlow[];
+  taskFlowById: ReadonlyMap<string, ProjectResourceTaskFlow>;
+  connectionIndex: ReadonlyMap<string, ProjectResourceConnectionIndex>;
+  producerTaskIdByResourceId: ReadonlyMap<string, string>;
   unresolvedReferenceResourceIds: string[];
   cyclicResourceIds: ReadonlySet<string>;
   cyclicTaskIds: ReadonlySet<string>;
+  producerMappingTruncated: boolean;
 };
 
 export type ProjectResourceGraphNeighbors = {
@@ -43,18 +74,18 @@ export type ProjectResourceGraphNeighbors = {
   connectedEdgeIds: ReadonlySet<string>;
 };
 
-type DirectedEdge = {
-  id: string;
-  sourceId: string;
-  targetId: string;
-};
-
-type CycleAnalysis = {
-  cyclicNodeIds: Set<string>;
-  cyclicEdgeIds: Set<string>;
-};
-
 const emptyStringSet: ReadonlySet<string> = new Set<string>();
+const emptyStringMap: ReadonlyMap<string, string> = new Map<string, string>();
+const emptyConnectionMap: ReadonlyMap<string, ProjectResourceConnectionIndex> =
+  new Map<string, ProjectResourceConnectionIndex>();
+const emptyTaskFlowMap: ReadonlyMap<string, ProjectResourceTaskFlow> = new Map<
+  string,
+  ProjectResourceTaskFlow
+>();
+const emptyReferenceEdgeMap: ReadonlyMap<
+  string,
+  ProjectResourceReferenceEdge
+> = new Map<string, ProjectResourceReferenceEdge>();
 
 export const EMPTY_PROJECT_RESOURCE_GRAPH_NEIGHBORS: ProjectResourceGraphNeighbors =
   {
@@ -63,13 +94,19 @@ export const EMPTY_PROJECT_RESOURCE_GRAPH_NEIGHBORS: ProjectResourceGraphNeighbo
     connectedEdgeIds: emptyStringSet,
   };
 
-function stableEdgeId(
-  kind: ProjectResourceReferenceEdge['kind'] | ProjectResourceTaskFlow['kind'],
-  sourceId: string,
-  targetId: string,
-) {
-  return `${kind}:${JSON.stringify([sourceId, targetId])}`;
-}
+export const EMPTY_PROJECT_RESOURCE_GRAPH: ProjectResourceGraph = {
+  resourceIds: emptyStringSet,
+  referenceEdges: [],
+  referenceEdgeById: emptyReferenceEdgeMap,
+  taskFlows: [],
+  taskFlowById: emptyTaskFlowMap,
+  connectionIndex: emptyConnectionMap,
+  producerTaskIdByResourceId: emptyStringMap,
+  unresolvedReferenceResourceIds: [],
+  cyclicResourceIds: emptyStringSet,
+  cyclicTaskIds: emptyStringSet,
+  producerMappingTruncated: false,
+};
 
 function uniqueSorted(values: Iterable<string>) {
   return Array.from(new Set(values)).sort((left, right) =>
@@ -77,231 +114,92 @@ function uniqueSorted(values: Iterable<string>) {
   );
 }
 
-function analyzeDirectedCycles(
-  nodeIds: Iterable<string>,
-  edges: readonly DirectedEdge[],
-): CycleAnalysis {
-  const nodes = new Set(nodeIds);
-  for (const edge of edges) {
-    nodes.add(edge.sourceId);
-    nodes.add(edge.targetId);
-  }
-  const adjacency = new Map<string, string[]>();
-  const reverseAdjacency = new Map<string, string[]>();
-  for (const nodeId of nodes) {
-    adjacency.set(nodeId, []);
-    reverseAdjacency.set(nodeId, []);
-  }
-  for (const edge of edges) {
-    adjacency.get(edge.sourceId)?.push(edge.targetId);
-    reverseAdjacency.get(edge.targetId)?.push(edge.sourceId);
-  }
-
-  const visited = new Set<string>();
-  const finishOrder: string[] = [];
-  for (const root of nodes) {
-    if (visited.has(root)) {
-      continue;
-    }
-    visited.add(root);
-    const stack: Array<{ nodeId: string; nextIndex: number }> = [
-      { nodeId: root, nextIndex: 0 },
-    ];
-    while (stack.length > 0) {
-      const frame = stack[stack.length - 1];
-      if (!frame) {
-        break;
-      }
-      const neighbors = adjacency.get(frame.nodeId) ?? [];
-      const next = neighbors[frame.nextIndex];
-      if (next === undefined) {
-        finishOrder.push(frame.nodeId);
-        stack.pop();
-        continue;
-      }
-      frame.nextIndex += 1;
-      if (!visited.has(next)) {
-        visited.add(next);
-        stack.push({ nodeId: next, nextIndex: 0 });
-      }
-    }
-  }
-
-  const componentByNode = new Map<string, number>();
-  const componentSizes: number[] = [];
-  for (let index = finishOrder.length - 1; index >= 0; index -= 1) {
-    const root = finishOrder[index];
-    if (root === undefined || componentByNode.has(root)) {
-      continue;
-    }
-    const componentId = componentSizes.length;
-    let size = 0;
-    const stack = [root];
-    componentByNode.set(root, componentId);
-    while (stack.length > 0) {
-      const nodeId = stack.pop();
-      if (nodeId === undefined) {
-        continue;
-      }
-      size += 1;
-      for (const neighbor of reverseAdjacency.get(nodeId) ?? []) {
-        if (!componentByNode.has(neighbor)) {
-          componentByNode.set(neighbor, componentId);
-          stack.push(neighbor);
-        }
-      }
-    }
-    componentSizes.push(size);
-  }
-
-  const cyclicNodeIds = new Set<string>();
-  const cyclicEdgeIds = new Set<string>();
-  for (const edge of edges) {
-    const sourceComponent = componentByNode.get(edge.sourceId);
-    const targetComponent = componentByNode.get(edge.targetId);
-    if (
-      sourceComponent !== undefined &&
-      sourceComponent === targetComponent &&
-      ((componentSizes[sourceComponent] ?? 0) > 1 ||
-        edge.sourceId === edge.targetId)
-    ) {
-      cyclicNodeIds.add(edge.sourceId);
-      cyclicNodeIds.add(edge.targetId);
-      cyclicEdgeIds.add(edge.id);
-    }
-  }
-  return { cyclicNodeIds, cyclicEdgeIds };
-}
-
-export function createProjectResourceGraph(
-  resources: readonly ProjectResourceGraphNodeInput[],
-  tasks: readonly ProjectResourceGraphTaskInput[],
+export function normalizeProjectResourceGraph(
+  readModel: ProjectResourceGraphReadModel,
 ): ProjectResourceGraph {
-  const resourceById = new Map(
-    resources.map((resource) => [resource.id, resource]),
-  );
-  const resourcesByTask = new Map<string, string[]>();
-  const resourcesByExternalId = new Map<string, string[]>();
-  for (const resource of resources) {
-    if (resource.producerTaskId) {
-      const taskResources = resourcesByTask.get(resource.producerTaskId) ?? [];
-      taskResources.push(resource.id);
-      resourcesByTask.set(resource.producerTaskId, taskResources);
-    }
-    if (resource.externalResourceId) {
-      const externalResources =
-        resourcesByExternalId.get(resource.externalResourceId) ?? [];
-      externalResources.push(resource.id);
-      resourcesByExternalId.set(resource.externalResourceId, externalResources);
-    }
-  }
-  for (const [taskId, resourceIds] of resourcesByTask) {
-    resourcesByTask.set(taskId, uniqueSorted(resourceIds));
-  }
-
-  const unresolvedReferenceResourceIds = new Set<string>();
-  const referenceEdgeById = new Map<string, ProjectResourceReferenceEdge>();
-  for (const target of resources) {
-    for (const externalReferenceId of new Set(target.referenceResourceIds)) {
-      const sourceCandidates =
-        resourcesByExternalId.get(externalReferenceId) ?? [];
-      if (sourceCandidates.length !== 1) {
-        unresolvedReferenceResourceIds.add(externalReferenceId);
-        continue;
+  const resourceIds = new Set(uniqueSorted(readModel.resourceIds));
+  const referenceEdges = readModel.referenceEdges
+    .filter(
+      (edge) =>
+        edge.kind === 'asset-reference' &&
+        resourceIds.has(edge.sourceResourceId) &&
+        resourceIds.has(edge.targetResourceId),
+    )
+    .sort((left, right) => left.id.localeCompare(right.id));
+  const referenceEdgeIds = new Set(referenceEdges.map((edge) => edge.id));
+  const taskFlows = readModel.taskFlows
+    .flatMap((flow) => {
+      if (flow.kind !== 'task-flow') {
+        return [];
       }
-      const sourceResourceId = sourceCandidates[0];
-      if (sourceResourceId === undefined) {
-        unresolvedReferenceResourceIds.add(externalReferenceId);
-        continue;
-      }
-      if (!resourceById.has(sourceResourceId) || !resourceById.has(target.id)) {
-        continue;
-      }
-      const id = stableEdgeId('asset-reference', sourceResourceId, target.id);
-      referenceEdgeById.set(id, {
-        id,
-        kind: 'asset-reference',
-        sourceResourceId,
-        targetResourceId: target.id,
-        cyclic: false,
-      });
-    }
-  }
-  const referenceEdges = Array.from(referenceEdgeById.values()).sort(
-    (left, right) => left.id.localeCompare(right.id),
-  );
-  const referenceCycles = analyzeDirectedCycles(
-    resourceById.keys(),
-    referenceEdges.map((edge) => ({
-      id: edge.id,
-      sourceId: edge.sourceResourceId,
-      targetId: edge.targetResourceId,
-    })),
-  );
-  for (const edge of referenceEdges) {
-    edge.cyclic = referenceCycles.cyclicEdgeIds.has(edge.id);
-  }
-
-  const taskById = new Map(tasks.map((task) => [task.id, task]));
-  const taskDependencyEdges: DirectedEdge[] = [];
-  for (const targetTask of tasks) {
-    for (const sourceTaskId of new Set(targetTask.dependencies)) {
-      if (!taskById.has(sourceTaskId)) {
-        continue;
-      }
-      taskDependencyEdges.push({
-        id: stableEdgeId('task-flow', sourceTaskId, targetTask.id),
-        sourceId: sourceTaskId,
-        targetId: targetTask.id,
-      });
-    }
-  }
-  const taskCycles = analyzeDirectedCycles(
-    taskById.keys(),
-    taskDependencyEdges,
-  );
-  const taskFlowById = new Map<string, ProjectResourceTaskFlow>();
-  for (const targetTask of tasks) {
-    const targetResourceIds = resourcesByTask.get(targetTask.id) ?? [];
-    if (targetResourceIds.length === 0) {
+      const sourceResourceIds = uniqueSorted(
+        flow.sourceResourceIds.filter((resourceId) =>
+          resourceIds.has(resourceId),
+        ),
+      );
+      const targetResourceIds = uniqueSorted(
+        flow.targetResourceIds.filter((resourceId) =>
+          resourceIds.has(resourceId),
+        ),
+      );
+      return sourceResourceIds.length > 0 && targetResourceIds.length > 0
+        ? [{ ...flow, sourceResourceIds, targetResourceIds }]
+        : [];
+    })
+    .sort((left, right) => left.id.localeCompare(right.id));
+  const taskFlowIds = new Set(taskFlows.map((flow) => flow.id));
+  const connectionIndex = new Map<string, ProjectResourceConnectionIndex>();
+  for (const index of readModel.connectionIndex) {
+    if (!resourceIds.has(index.resourceId)) {
       continue;
     }
-    for (const sourceTaskId of new Set(targetTask.dependencies)) {
-      if (!taskById.has(sourceTaskId)) {
-        continue;
-      }
-      const sourceResourceIds = resourcesByTask.get(sourceTaskId) ?? [];
-      if (sourceResourceIds.length === 0) {
-        continue;
-      }
-      const id = stableEdgeId('task-flow', sourceTaskId, targetTask.id);
-      taskFlowById.set(id, {
-        id,
-        kind: 'task-flow',
-        sourceTaskId,
-        targetTaskId: targetTask.id,
-        sourceResourceIds,
-        targetResourceIds,
-        cyclic: false,
-      });
-    }
+    connectionIndex.set(index.resourceId, {
+      upstreamReferenceResourceIds: new Set(
+        index.upstreamReferenceResourceIds.filter((resourceId) =>
+          resourceIds.has(resourceId),
+        ),
+      ),
+      downstreamReferenceResourceIds: new Set(
+        index.downstreamReferenceResourceIds.filter((resourceId) =>
+          resourceIds.has(resourceId),
+        ),
+      ),
+      referenceEdgeIds: new Set(
+        index.referenceEdgeIds.filter((edgeId) =>
+          referenceEdgeIds.has(edgeId),
+        ),
+      ),
+      taskFlowIds: new Set(
+        index.taskFlowIds.filter((flowId) => taskFlowIds.has(flowId)),
+      ),
+    });
   }
-  const taskFlows = Array.from(taskFlowById.values()).sort((left, right) =>
-    left.id.localeCompare(right.id),
+  const producerTaskIdByResourceId = new Map(
+    readModel.producerAssignments.flatMap((assignment) =>
+      resourceIds.has(assignment.resourceId) && assignment.taskId
+        ? [[assignment.resourceId, assignment.taskId] as const]
+        : [],
+    ),
   );
-  for (const flow of taskFlows) {
-    flow.cyclic = taskCycles.cyclicEdgeIds.has(flow.id);
-  }
 
   return {
-    resourceIds: new Set(resourceById.keys()),
+    resourceIds,
     referenceEdges,
+    referenceEdgeById: new Map(referenceEdges.map((edge) => [edge.id, edge])),
     taskFlows,
+    taskFlowById: new Map(taskFlows.map((flow) => [flow.id, flow])),
+    connectionIndex,
+    producerTaskIdByResourceId,
     unresolvedReferenceResourceIds: uniqueSorted(
-      unresolvedReferenceResourceIds,
+      readModel.unresolvedReferenceResourceIds,
     ),
-    cyclicResourceIds: referenceCycles.cyclicNodeIds,
-    cyclicTaskIds: taskCycles.cyclicNodeIds,
+    cyclicResourceIds: new Set(
+      readModel.cyclicResourceIds.filter((resourceId) =>
+        resourceIds.has(resourceId),
+      ),
+    ),
+    cyclicTaskIds: new Set(readModel.cyclicTaskIds),
+    producerMappingTruncated: Boolean(readModel.producerMappingTruncated),
   };
 }
 
@@ -312,21 +210,22 @@ export function projectResourceGraphNeighbors(
   if (!resourceId || !graph.resourceIds.has(resourceId)) {
     return EMPTY_PROJECT_RESOURCE_GRAPH_NEIGHBORS;
   }
-  const upstreamResourceIds = new Set<string>();
-  const downstreamResourceIds = new Set<string>();
-  const connectedEdgeIds = new Set<string>();
-
-  for (const edge of graph.referenceEdges) {
-    if (edge.targetResourceId === resourceId) {
-      upstreamResourceIds.add(edge.sourceResourceId);
-      connectedEdgeIds.add(edge.id);
-    }
-    if (edge.sourceResourceId === resourceId) {
-      downstreamResourceIds.add(edge.targetResourceId);
-      connectedEdgeIds.add(edge.id);
-    }
+  const index = graph.connectionIndex.get(resourceId);
+  if (!index) {
+    return EMPTY_PROJECT_RESOURCE_GRAPH_NEIGHBORS;
   }
-  for (const flow of graph.taskFlows) {
+  const upstreamResourceIds = new Set(
+    index.upstreamReferenceResourceIds,
+  );
+  const downstreamResourceIds = new Set(
+    index.downstreamReferenceResourceIds,
+  );
+  const connectedEdgeIds = new Set(index.referenceEdgeIds);
+  for (const flowId of index.taskFlowIds) {
+    const flow = graph.taskFlowById.get(flowId);
+    if (!flow) {
+      continue;
+    }
     if (flow.targetResourceIds.includes(resourceId)) {
       flow.sourceResourceIds.forEach((id) => upstreamResourceIds.add(id));
       connectedEdgeIds.add(flow.id);
diff --git a/apps/ai-game-creator-shell/tests/ResourceDependencyOverlay.test.ts b/apps/ai-game-creator-shell/tests/ResourceDependencyOverlay.test.ts
index e5b508d09..da4df334a 100644
--- a/apps/ai-game-creator-shell/tests/ResourceDependencyOverlay.test.ts
+++ b/apps/ai-game-creator-shell/tests/ResourceDependencyOverlay.test.ts
@@ -5,8 +5,9 @@ import { describe, expect, it, vi } from 'vitest';
 
 import type { ProjectResourceCanvasPosition } from '../../../packages/shared/src/contracts/gameCreationApp';
 import {
-  createProjectResourceGraph,
+  normalizeProjectResourceGraph,
   type ProjectResourceGraph,
+  type ProjectResourceGraphReadModel,
 } from '../src/view/project-development/resourceDependencyGraphModel';
 import { ResourceDependencyOverlay } from '../src/view/project-development/ResourceDependencyOverlay';
 
@@ -25,45 +26,76 @@ function position(
 }
 
 function graphFixture() {
-  return createProjectResourceGraph(
-    [
+  const referenceId = 'asset-reference:["source:one","target:one"]';
+  const selfReferenceId = 'asset-reference:["unrelated","unrelated"]';
+  const flowId = 'task-flow:["source-task","target-task"]';
+  const resourceIds = [
+    'source:one',
+    'source:two',
+    'source:three',
+    'target:one',
+    'target:two',
+    'target:three',
+    'unrelated',
+  ];
+  const readModel: ProjectResourceGraphReadModel = {
+    resourceIds,
+    referenceEdges: [
       {
-        id: 'source:one',
-        producerTaskId: 'source-task',
-        externalResourceId: 'external-source',
-        referenceResourceIds: [],
+        id: referenceId,
+        kind: 'asset-reference',
+        sourceResourceId: 'source:one',
+        targetResourceId: 'target:one',
+        cyclic: false,
       },
-      ...['source:two', 'source:three'].map((id) => ({
-        id,
-        producerTaskId: 'source-task',
-        externalResourceId: null,
-        referenceResourceIds: [],
-      })),
       {
-        id: 'target:one',
-        producerTaskId: 'target-task',
-        externalResourceId: null,
-        referenceResourceIds: ['external-source'],
-      },
-      ...['target:two', 'target:three'].map((id) => ({
-        id,
-        producerTaskId: 'target-task',
-        externalResourceId: null,
-        referenceResourceIds: [],
-      })),
-      {
-        id: 'unrelated',
-        producerTaskId: 'unrelated-task',
-        externalResourceId: 'external-unrelated',
-        referenceResourceIds: ['external-unrelated'],
+        id: selfReferenceId,
+        kind: 'asset-reference',
+        sourceResourceId: 'unrelated',
+        targetResourceId: 'unrelated',
+        cyclic: true,
       },
     ],
-    [
-      { id: 'source-task', dependencies: [] },
-      { id: 'target-task', dependencies: ['source-task'] },
-      { id: 'unrelated-task', dependencies: [] },
+    taskFlows: [
+      {
+        id: flowId,
+        kind: 'task-flow',
+        sourceTaskId: 'source-task',
+        targetTaskId: 'target-task',
+        sourceResourceIds: ['source:one', 'source:two', 'source:three'],
+        targetResourceIds: ['target:one', 'target:two', 'target:three'],
+        cyclic: false,
+      },
     ],
-  );
+    connectionIndex: resourceIds.map((resourceId) => ({
+      resourceId,
+      upstreamReferenceResourceIds:
+        resourceId === 'target:one'
+          ? ['source:one']
+          : resourceId === 'unrelated'
+            ? ['unrelated']
+            : [],
+      downstreamReferenceResourceIds:
+        resourceId === 'source:one'
+          ? ['target:one']
+          : resourceId === 'unrelated'
+            ? ['unrelated']
+            : [],
+      referenceEdgeIds:
+        resourceId === 'source:one' || resourceId === 'target:one'
+          ? [referenceId]
+          : resourceId === 'unrelated'
+            ? [selfReferenceId]
+            : [],
+      taskFlowIds: resourceId === 'unrelated' ? [] : [flowId],
+    })),
+    producerAssignments: [],
+    unresolvedReferenceResourceIds: [],
+    cyclicResourceIds: ['unrelated'],
+    cyclicTaskIds: [],
+    producerMappingTruncated: false,
+  };
+  return normalizeProjectResourceGraph(readModel);
 }
 
 function OverlayHarness({
@@ -71,11 +103,13 @@ function OverlayHarness({
   positions,
   visibleResourceIds,
   selectedResourceId = null,
+  dragPreview = null,
 }: {
   graph: ProjectResourceGraph;
   positions: ProjectResourceCanvasPosition[];
   visibleResourceIds: ReadonlySet<string>;
   selectedResourceId?: string | null;
+  dragPreview?: { resourceId: string; x: number; y: number } | null;
 }) {
   return React.createElement(
     'div',
@@ -84,6 +118,7 @@ function OverlayHarness({
     React.createElement(ResourceDependencyOverlay, {
       graph,
       positions,
+      dragPreview,
       visibleResourceIds,
       selectedResourceId,
     }),
@@ -95,12 +130,14 @@ function overlayView(
   positions: ProjectResourceCanvasPosition[],
   visibleResourceIds: ReadonlySet<string>,
   selectedResourceId: string | null = null,
+  dragPreview: { resourceId: string; x: number; y: number } | null = null,
 ) {
   return React.createElement(OverlayHarness, {
     graph,
     positions,
     visibleResourceIds,
     selectedResourceId,
+    dragPreview,
   });
 }
 
@@ -159,8 +196,10 @@ describe('ResourceDependencyOverlay', () => {
     view.rerender(
       overlayView(
         graph,
-        [position('source:one', 80, 40), position('target:one', 240, 0)],
+        positions,
         new Set(['source:one', 'target:one']),
+        null,
+        { resourceId: 'source:one', x: 80, y: 40 },
       ),
     );
     await waitFor(() =>
@@ -179,6 +218,56 @@ describe('ResourceDependencyOverlay', () => {
     );
   });
 
+  it('keeps the section origin when updating a dragged path', async () => {
+    const getBoundingClientRect = vi
+      .spyOn(HTMLElement.prototype, 'getBoundingClientRect')
+      .mockImplementation(function () {
+        const isPlane = this.hasAttribute('data-resource-section-plane');
+        return {
+          x: isPlane ? 160 : 20,
+          y: isPlane ? 90 : 10,
+          left: isPlane ? 160 : 20,
+          top: isPlane ? 90 : 10,
+          right: 0,
+          bottom: 0,
+          width: 0,
+          height: 0,
+          toJSON: () => ({}),
+        };
+      });
+    try {
+      const graph = graphFixture();
+      const positions = [
+        position('source:one', 0, 0),
+        position('target:one', 240, 0),
+      ];
+      const visible = new Set(['source:one', 'target:one']);
+      const view = render(overlayView(graph, positions, visible));
+      const overlay = await screen.findByTestId('resource-dependency-overlay');
+      const selector = '[data-edge-kind="asset-reference"]';
+      await waitFor(() =>
+        expect(overlay.querySelector(selector)?.getAttribute('d')).toContain(
+          'M 320 126',
+        ),
+      );
+
+      view.rerender(
+        overlayView(graph, positions, visible, null, {
+          resourceId: 'source:one',
+          x: 80,
+          y: 40,
+        }),
+      );
+      await waitFor(() =>
+        expect(overlay.querySelector(selector)?.getAttribute('d')).toContain(
+          'M 400 166',
+        ),
+      );
+    } finally {
+      getBoundingClientRect.mockRestore();
+    }
+  });
+
   it('routes a cyclic self-reference outside the resource card and moves it with the card', async () => {
     const graph = graphFixture();
     const view = render(
@@ -244,6 +333,76 @@ describe('ResourceDependencyOverlay', () => {
     expect(unrelated?.classList.contains('is-dimmed')).toBe(true);
   });
 
+  it('updates only adjacent paths while dragging inside a 4096-resource topology', async () => {
+    const resourceIds = Array.from(
+      { length: 4096 },
+      (_, index) => `resource:${index}`,
+    );
+    const taskFlows = resourceIds.slice(1).map((resourceId, index) => ({
+      id: `flow:${index}:${index + 1}`,
+      kind: 'task-flow' as const,
+      sourceTaskId: `task:${index}`,
+      targetTaskId: `task:${index + 1}`,
+      sourceResourceIds: [`resource:${index}`],
+      targetResourceIds: [resourceId],
+      cyclic: false,
+    }));
+    const graph = normalizeProjectResourceGraph({
+      resourceIds,
+      referenceEdges: [],
+      taskFlows,
+      connectionIndex: resourceIds.map((resourceId, index) => ({
+        resourceId,
+        upstreamReferenceResourceIds: [],
+        downstreamReferenceResourceIds: [],
+        referenceEdgeIds: [],
+        taskFlowIds: [
+          ...(index > 0 ? [`flow:${index - 1}:${index}`] : []),
+          ...(index < resourceIds.length - 1
+            ? [`flow:${index}:${index + 1}`]
+            : []),
+        ],
+      })),
+      producerAssignments: [],
+      unresolvedReferenceResourceIds: [],
+      cyclicResourceIds: [],
+      cyclicTaskIds: [],
+      producerMappingTruncated: false,
+    });
+    const positions = [
+      position('resource:2047', 0, 0),
+      position('resource:2048', 220, 0),
+      position('resource:2049', 440, 0),
+    ];
+    const visible = new Set(positions.map(({ resourceId }) => resourceId));
+    const view = render(overlayView(graph, positions, visible));
+    const overlay = await screen.findByTestId('resource-dependency-overlay');
+    await waitFor(() =>
+      expect(
+        overlay.querySelectorAll('[data-edge-kind="task-flow"]'),
+      ).toHaveLength(2),
+    );
+    const setAttribute = vi.spyOn(
+      SVGElement.prototype,
+      'setAttribute',
+    );
+    try {
+      view.rerender(
+        overlayView(graph, positions, visible, null, {
+          resourceId: 'resource:2048',
+          x: 260,
+          y: 32,
+        }),
+      );
+      const geometryUpdates = setAttribute.mock.calls.filter(
+        ([name]) => name === 'd',
+      );
+      expect(geometryUpdates).toHaveLength(6);
+    } finally {
+      setAttribute.mockRestore();
+    }
+  });
+
   it('disconnects layout observers when the SVG layer is destroyed', () => {
     const observe = vi.fn();
     const disconnect = vi.fn();
@@ -257,16 +416,27 @@ describe('ResourceDependencyOverlay', () => {
     vi.stubGlobal('ResizeObserver', TestResizeObserver);
     try {
       const graph = graphFixture();
+      const positions = Array.from(graph.resourceIds).map(
+        (resourceId, index) => position(resourceId, index * 200, 0),
+      );
       const view = render(
         overlayView(
           graph,
-          Array.from(graph.resourceIds).map((resourceId, index) =>
-            position(resourceId, index * 200, 0),
-          ),
+          positions,
           new Set(graph.resourceIds),
         ),
       );
 
+      expect(observe).toHaveBeenCalledTimes(2);
+      view.rerender(
+        overlayView(
+          graph,
+          positions,
+          new Set(graph.resourceIds),
+          null,
+          { resourceId: 'source:one', x: 32, y: 24 },
+        ),
+      );
       expect(observe).toHaveBeenCalledTimes(2);
       view.unmount();
       expect(disconnect).toHaveBeenCalledTimes(1);
diff --git a/apps/ai-game-creator-shell/tests/appSurface/project-development.suite.ts b/apps/ai-game-creator-shell/tests/appSurface/project-development.suite.ts
index d1e10a9a9..449123398 100644
--- a/apps/ai-game-creator-shell/tests/appSurface/project-development.suite.ts
+++ b/apps/ai-game-creator-shell/tests/appSurface/project-development.suite.ts
@@ -732,7 +732,7 @@ export function registerProjectWorkbenchFoundationTests() {
         localPath: 'assets/spec-source.json',
         source: {
           kind: 'canvas',
-          taskId: 'art-director',
+          taskId: 'task-1',
           resourceId: 'canvas-spec-source',
         },
       },
@@ -743,7 +743,7 @@ export function registerProjectWorkbenchFoundationTests() {
         localPath: 'assets/ui-dependency.json',
         source: {
           kind: 'canvas',
-          taskId: 'design-foundation',
+          taskId: 'task-2',
           resourceId: 'canvas-ui-target',
           referenceResourceIds: ['canvas-spec-source'],
         },
@@ -761,6 +761,130 @@ export function registerProjectWorkbenchFoundationTests() {
       },
     );
 
+    const referenceId =
+      'asset-reference:["asset:dependency-spec","asset:dependency-ui"]';
+    const selfReferenceId =
+      'asset-reference:["asset:unrelated-cycle","asset:unrelated-cycle"]';
+    const flowId =
+      'task-flow:["art-director","design-foundation"]';
+    let layoutRevision = 0;
+    const invoke = vi.fn(
+      async (command: string, args?: Record<string, unknown>) => {
+        if (command === 'read_local_project_resource_graph') {
+          expect(args?.resources).toEqual(
+            expect.arrayContaining([
+              expect.objectContaining({
+                resourceId: 'asset:dependency-spec',
+                manifestAssetId: 'dependency-spec',
+                producerTaskId: null,
+              }),
+            ]),
+          );
+          return {
+            resourceIds: [
+              'asset:dependency-spec',
+              'asset:dependency-ui',
+              'asset:unrelated-cycle',
+            ],
+            referenceEdges: [
+              {
+                id: referenceId,
+                kind: 'asset-reference',
+                sourceResourceId: 'asset:dependency-spec',
+                targetResourceId: 'asset:dependency-ui',
+                cyclic: false,
+              },
+              {
+                id: selfReferenceId,
+                kind: 'asset-reference',
+                sourceResourceId: 'asset:unrelated-cycle',
+                targetResourceId: 'asset:unrelated-cycle',
+                cyclic: true,
+              },
+            ],
+            taskFlows: [
+              {
+                id: flowId,
+                kind: 'task-flow',
+                sourceTaskId: 'art-director',
+                targetTaskId: 'design-foundation',
+                sourceResourceIds: ['asset:dependency-spec'],
+                targetResourceIds: ['asset:dependency-ui'],
+                cyclic: false,
+              },
+            ],
+            connectionIndex: [
+              {
+                resourceId: 'asset:dependency-spec',
+                upstreamReferenceResourceIds: [],
+                downstreamReferenceResourceIds: ['asset:dependency-ui'],
+                referenceEdgeIds: [referenceId],
+                taskFlowIds: [flowId],
+              },
+              {
+                resourceId: 'asset:dependency-ui',
+                upstreamReferenceResourceIds: ['asset:dependency-spec'],
+                downstreamReferenceResourceIds: [],
+                referenceEdgeIds: [referenceId],
+                taskFlowIds: [flowId],
+              },
+              {
+                resourceId: 'asset:unrelated-cycle',
+                upstreamReferenceResourceIds: [
+                  'asset:unrelated-cycle',
+                ],
+                downstreamReferenceResourceIds: [
+                  'asset:unrelated-cycle',
+                ],
+                referenceEdgeIds: [selfReferenceId],
+                taskFlowIds: [],
+              },
+            ],
+            producerAssignments: [
+              {
+                resourceId: 'asset:dependency-spec',
+                taskId: 'art-director',
+              },
+              {
+                resourceId: 'asset:dependency-ui',
+                taskId: 'design-foundation',
+              },
+            ],
+            unresolvedReferenceResourceIds: [],
+            cyclicResourceIds: ['asset:unrelated-cycle'],
+            cyclicTaskIds: [],
+            producerMappingTruncated: false,
+          };
+        }
+        if (command === 'read_local_project_resource_canvas_layout') {
+          return {
+            schemaVersion: 'game-creator-resource-layout.v1',
+            projectId: 'workbench-resource-graph',
+            mode: args?.mode,
+            revision: layoutRevision,
+            positions: [],
+            updatedAt: 0,
+          };
+        }
+        if (command === 'update_local_project_resource_canvas_layout') {
+          layoutRevision += 1;
+          return {
+            status: 'updated',
+            layout: {
+              schemaVersion: 'game-creator-resource-layout.v1',
+              projectId: 'workbench-resource-graph',
+              mode: args?.mode,
+              revision: layoutRevision,
+              positions: args?.positions,
+              updatedAt: layoutRevision,
+            },
+          };
+        }
+        throw new Error(`unexpected invoke ${command}`);
+      },
+    );
+    window.__TAURI__ = { core: { invoke } };
+
     const view = render(
       React.createElement(ProjectDevelopmentView, {
         projectName: '资源依赖图测试',
diff --git a/apps/ai-game-creator-shell/tests/resourceDependencyGraphModel.test.ts b/apps/ai-game-creator-shell/tests/resourceDependencyGraphModel.test.ts
index 18b526081..0566384ae 100644
--- a/apps/ai-game-creator-shell/tests/resourceDependencyGraphModel.test.ts
+++ b/apps/ai-game-creator-shell/tests/resourceDependencyGraphModel.test.ts
@@ -1,157 +1,156 @@
 import { describe, expect, it } from 'vitest';
 
 import {
-  createProjectResourceGraph,
+  normalizeProjectResourceGraph,
   projectResourceGraphNeighbors,
-  type ProjectResourceGraphNodeInput,
+  type ProjectResourceGraphReadModel,
 } from '../src/view/project-development/resourceDependencyGraphModel';
 
-function resource(
-  id: string,
-  producerTaskId: string | null,
-  options: Partial<ProjectResourceGraphNodeInput> = {},
-): ProjectResourceGraphNodeInput {
+function readModel(
+  overrides: Partial<ProjectResourceGraphReadModel> = {},
+): ProjectResourceGraphReadModel {
   return {
-    id,
-    producerTaskId,
-    externalResourceId: null,
-    referenceResourceIds: [],
-    ...options,
+    resourceIds: [],
+    referenceEdges: [],
+    taskFlows: [],
+    connectionIndex: [],
+    producerAssignments: [],
+    unresolvedReferenceResourceIds: [],
+    cyclicResourceIds: [],
+    cyclicTaskIds: [],
+    producerMappingTruncated: false,
+    ...overrides,
   };
 }
 
 describe('resource dependency graph model', () => {
-  it('maps exact external asset references, deduplicates them, and filters missing resources', () => {
-    const graph = createProjectResourceGraph(
-      [
-        resource('asset:spec', 'art-director', {
-          externalResourceId: 'canvas-resource-spec',
-        }),
-        resource('asset:ui', 'design-foundation', {
-          externalResourceId: 'canvas-resource-ui',
-          referenceResourceIds: [
-            'canvas-resource-spec',
-            'canvas-resource-spec',
-            'missing-resource',
-          ],
-        }),
-      ],
-      [
-        { id: 'art-director', dependencies: [] },
-        { id: 'design-foundation', dependencies: ['art-director'] },
-      ],
+  it('normalizes the Rust read model and filters stale resource endpoints', () => {
+    const graph = normalizeProjectResourceGraph(
+      readModel({
+        resourceIds: ['asset:source', 'asset:target'],
+        referenceEdges: [
+          {
+            id: 'valid-reference',
+            kind: 'asset-reference',
+            sourceResourceId: 'asset:source',
+            targetResourceId: 'asset:target',
+            cyclic: false,
+          },
+          {
+            id: 'ghost-reference',
+            kind: 'asset-reference',
+            sourceResourceId: 'asset:deleted',
+            targetResourceId: 'asset:target',
+            cyclic: false,
+          },
+        ],
+        taskFlows: [
+          {
+            id: 'valid-flow',
+            kind: 'task-flow',
+            sourceTaskId: 'source-task',
+            targetTaskId: 'target-task',
+            sourceResourceIds: ['asset:source', 'asset:deleted'],
+            targetResourceIds: ['asset:target'],
+            cyclic: false,
+          },
+          {
+            id: 'ghost-flow',
+            kind: 'task-flow',
+            sourceTaskId: 'deleted-task',
+            targetTaskId: 'target-task',
+            sourceResourceIds: ['asset:deleted'],
+            targetResourceIds: ['asset:target'],
+            cyclic: false,
+          },
+        ],
+        cyclicResourceIds: ['asset:source', 'asset:deleted'],
+      }),
     );
 
-    expect(graph.referenceEdges).toEqual([
+    expect(graph.referenceEdges.map((edge) => edge.id)).toEqual([
+      'valid-reference',
+    ]);
+    expect(graph.taskFlows).toEqual([
       expect.objectContaining({
-        kind: 'asset-reference',
-        sourceResourceId: 'asset:spec',
-        targetResourceId: 'asset:ui',
-        cyclic: false,
+        id: 'valid-flow',
+        sourceResourceIds: ['asset:source'],
+        targetResourceIds: ['asset:target'],
       }),
     ]);
-    expect(graph.unresolvedReferenceResourceIds).toEqual(['missing-resource']);
+    expect(graph.cyclicResourceIds).toEqual(new Set(['asset:source']));
   });
 
-  it('aggregates each task dependency into one flow instead of a resource cartesian product', () => {
-    const graph = createProjectResourceGraph(
-      [
-        resource('upstream:a', 'task-a'),
-        resource('upstream:b', 'task-a'),
-        resource('downstream:a', 'task-b'),
-        resource('downstream:b', 'task-b'),
-        resource('downstream:c', 'task-b'),
-      ],
-      [
-        { id: 'task-a', dependencies: [] },
-        { id: 'task-b', dependencies: ['task-a', 'task-a'] },
-      ],
+  it('queries direct reference and aggregated task-flow neighbors from the bounded index', () => {
+    const graph = normalizeProjectResourceGraph(
+      readModel({
+        resourceIds: ['source:a', 'source:b', 'target:a', 'target:b'],
+        referenceEdges: [
+          {
+            id: 'reference:a',
+            kind: 'asset-reference',
+            sourceResourceId: 'source:a',
+            targetResourceId: 'target:a',
+            cyclic: false,
+          },
+        ],
+        taskFlows: [
+          {
+            id: 'flow:a-b',
+            kind: 'task-flow',
+            sourceTaskId: 'task:a',
+            targetTaskId: 'task:b',
+            sourceResourceIds: ['source:a', 'source:b'],
+            targetResourceIds: ['target:a', 'target:b'],
+            cyclic: false,
+          },
+        ],
+        connectionIndex: [
+          {
+            resourceId: 'target:a',
+            upstreamReferenceResourceIds: ['source:a'],
+            downstreamReferenceResourceIds: [],
+            referenceEdgeIds: ['reference:a'],
+            taskFlowIds: ['flow:a-b'],
+          },
+        ],
+      }),
     );
 
-    expect(graph.taskFlows).toHaveLength(1);
-    expect(graph.taskFlows[0]).toMatchObject({
-      sourceTaskId: 'task-a',
-      targetTaskId: 'task-b',
-      sourceResourceIds: ['upstream:a', 'upstream:b'],
-      targetResourceIds: ['downstream:a', 'downstream:b', 'downstream:c'],
-    });
-  });
-
-  it('detects resource and task dependency cycles without recursive traversal', () => {
-    const graph = createProjectResourceGraph(
-      [
-        resource('asset:a', 'task-a', {
-          externalResourceId: 'external-a',
-          referenceResourceIds: ['external-b'],
-        }),
-        resource('asset:b', 'task-b', {
-          externalResourceId: 'external-b',
-          referenceResourceIds: ['external-a'],
-        }),
-      ],
-      [
-        { id: 'task-a', dependencies: ['task-b'] },
-        { id: 'task-b', dependencies: ['task-a'] },
-      ],
-    );
-
-    expect(graph.cyclicResourceIds).toEqual(new Set(['asset:a', 'asset:b']));
-    expect(graph.referenceEdges.every((edge) => edge.cyclic)).toBe(true);
-    expect(graph.cyclicTaskIds).toEqual(new Set(['task-a', 'task-b']));
-    expect(graph.taskFlows.every((flow) => flow.cyclic)).toBe(true);
-  });
-
-  it('detects task cycles even when a cyclic task has no resource card', () => {
-    const graph = createProjectResourceGraph(
-      [resource('asset:a', 'task-a')],
-      [
-        { id: 'task-a', dependencies: ['task-b'] },
-        { id: 'task-b', dependencies: ['task-a'] },
-      ],
-    );
-
-    expect(graph.taskFlows).toHaveLength(0);
-    expect(graph.cyclicTaskIds).toEqual(new Set(['task-a', 'task-b']));
-  });
-
-  it('returns direct upstream and downstream resources for exact and aggregated edges', () => {
-    const graph = createProjectResourceGraph(
-      [
-        resource('task-a:one', 'task-a', {
-          externalResourceId: 'external-a',
-        }),
-        resource('task-a:two', 'task-a'),
-        resource('task-b:one', 'task-b', {
-          referenceResourceIds: ['external-a'],
-        }),
-      ],
-      [
-        { id: 'task-a', dependencies: [] },
-        { id: 'task-b', dependencies: ['task-a'] },
-      ],
-    );
-
-    const neighbors = projectResourceGraphNeighbors(graph, 'task-b:one');
+    const neighbors = projectResourceGraphNeighbors(graph, 'target:a');
     expect(neighbors.upstreamResourceIds).toEqual(
-      new Set(['task-a:one', 'task-a:two']),
+      new Set(['source:a', 'source:b']),
     );
     expect(neighbors.downstreamResourceIds).toEqual(new Set());
-    expect(neighbors.connectedEdgeIds.size).toBe(2);
+    expect(neighbors.connectedEdgeIds).toEqual(
+      new Set(['reference:a', 'flow:a-b']),
+    );
   });
 
-  it('keeps graph construction linear for the supported resource bound', () => {
-    const resources = Array.from({ length: 4096 }, (_, index) =>
-      resource(`resource:${index}`, `task:${index}`),
+  it('keeps real producer assignments and audit truncation metadata', () => {
+    const graph = normalizeProjectResourceGraph(
+      readModel({
+        resourceIds: ['asset:spec', 'asset:ui'],
+        producerAssignments: [
+          { resourceId: 'asset:spec', taskId: 'art-director' },
+          { resourceId: 'asset:ui', taskId: 'design-foundation' },
+          { resourceId: 'asset:deleted', taskId: 'task-1' },
+        ],
+        producerMappingTruncated: true,
+      }),
     );
-    const tasks = Array.from({ length: 4096 }, (_, index) => ({
-      id: `task:${index}`,
-      dependencies: index === 0 ? [] : [`task:${index - 1}`],
-    }));
-    const startedAt = performance.now();
-    const graph = createProjectResourceGraph(resources, tasks);
-    const elapsedMs = performance.now() - startedAt;
 
-    expect(graph.taskFlows).toHaveLength(4095);
-    expect(elapsedMs).toBeLessThan(2000);
+    expect(graph.producerTaskIdByResourceId).toEqual(
+      new Map([
+        ['asset:spec', 'art-director'],
+        ['asset:ui', 'design-foundation'],
+      ]),
+    );
+    expect(graph.producerMappingTruncated).toBe(true);
+    expect(projectResourceGraphNeighbors(graph, 'asset:deleted')).toEqual({
+      upstreamResourceIds: new Set(),
+      downstreamResourceIds: new Set(),
+      connectedEdgeIds: new Set(),
+    });
   });
 });
diff --git a/docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md b/docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md
index e00ab7567..ef4fa28e4 100644
--- a/docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md
+++ b/docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md
@@ -153,7 +153,7 @@ P0 中 `approvalMode` 只能有效写入 `strict`；其它值只能作为不可
 
 ### 5.2 资源画布布局（P1）
 
-实现状态（2026-07-31）：本节布局合同已在独立客户端落地，dependency / type 双模式通过项目内 CAS sidecar 独立持久化；dependency 模式的前端资源依赖关系图层也已落地，但不写入布局 sidecar。资源替换、缩放 / 平移等其余 P1 能力仍按本文非目标保持未实现。
+实现状态（2026-07-31）：本节布局合同已在独立客户端落地，dependency / type 双模式通过项目内 CAS sidecar 独立持久化；dependency 模式由 Tauri Rust 只读构建关系拓扑、前端 SVG 派生几何，图结构和线段均不写入布局 sidecar。资源替换、缩放 / 平移等其余 P1 能力仍按本文非目标保持未实现。
 
 ```ts
 type ProjectResourceCanvasLayout = {
@@ -250,14 +250,16 @@ type UpdateProjectResourceCanvasLayoutResult =
 #### 5.2.5 资源依赖关系图层
 
 - 图层只在 dependency 模式挂载；type 模式不得渲染 SVG、连线或 marker。切换 mode、切换项目或卸载工作台时必须销毁旧图层，并清理尺寸观察和窗口事件监听。
-- 输入固定为当前资源投影的全部卡片坐标与前端 `ProjectResourceGraph`；输出使用原生 SVG 的 path 和箭头 marker。SVG 叠加在资源卡底层并设置 `pointer-events: none`，不得引入 D3、React Flow 等图表库，也不得阻断卡片点击和 Pointer Events 拖动。
+- 输入固定为当前资源投影的全部卡片身份 / 坐标与 Tauri Rust 返回的 `ProjectResourceGraph` 只读 DTO；Rust 负责资源过滤、去重、环检测、任务流聚合和一跳连接索引，前端只负责 DTO 防御归一化、浏览器几何与原生 SVG path / marker。SVG 叠加在资源卡底层并设置 `pointer-events: none`，不得引入 D3、React Flow 等图表库，也不得阻断卡片点击和 Pointer Events 拖动。
 - `asset-reference` 表示精确资源引用，使用橙色实线与连续贝塞尔曲线。`GameCreationAppAssetManifestEntry.source.referenceResourceIds` 中的外部资源 ID 必须先唯一匹配另一项资产的 `source.resourceId`，再映射为当前资源卡 ID；缺失、重复或已删除的目标均不得渲染幽灵连线。
 - `task-flow` 表示任务产物流转，使用灰色圆头虚线。任务依赖按 `sourceTaskId -> targetTaskId` 聚合为一条主线，两端资源仅绘制平滑曲线分支，不得出现直角折线；禁止对上下游资源生成笛卡尔积连线。任务主线与分支可以使用不同线宽和透明度表达聚合层级，但不能改变端点或方向语义。
+- 画布资产 producer 只能来自 `agent.runtime.canvas.asset_generate` 的 `assetId -> agentId` 审计且 `agentId` 必须存在于当前 manifest；External Editor `source.taskId` 属于平台生成任务命名空间，禁止当作 manifest task ID。证据缺失、冲突或有界审计读取未覆盖时不生成对应 task flow，不猜测归属。
 - 图模型必须对资源引用图和完整任务依赖图做迭代式环检测，不得用无界递归遍历；参与环的可见边保留渲染并标记 cyclic，环本身不能造成重复生成或死循环。
 - 资源自引用的起点与终点为同一张卡片时，必须绘制在卡片外侧的可见闭环并保留箭头，不得让路径穿过卡片后被底层 SVG 层级遮挡。
 - 搜索只允许为当前可见端点生成几何；任一精确引用端点隐藏时该线隐藏，聚合任务流只保留仍可见的两端分支，任一侧没有可见资源时整条任务流隐藏。
 - 选中资源后，高亮其直接上游、直接下游卡片和关联边，弱化其余边；不做跨多层递归高亮。选中 ID 已失效时按未选中处理。
 - 拖动预览坐标必须直接进入 SVG 几何计算，使连线随 pointer move 实时更新；拖动结束仍只保存卡片布局坐标，不持久化 path、marker、section 原点或任何图结构。
+- Pointer Move 必须按动画帧合并；基础 positions 不随每帧复制，静态 SVG 拓扑保持复用，每帧只更新当前资源局部索引关联的 path。`ResizeObserver` 在单个图层生命周期只允许构造一次。dependency section 额外提供至少 `64px` 右侧视觉 gutter，确保最右侧自环和箭头可完整滚动显示，但不得修改卡片坐标或布局 sidecar。
 
 ### 5.3 资源类型与替换兼容性（P1）
 
@@ -402,10 +404,11 @@ type ProjectAgentMudPointAttribution = {
 4. 资源引用环和无资源产物参与的任务环都可被有限遍历识别，界面不死循环。
 5. 搜索、选择和拖动分别触发端点过滤、直接上下游高亮和实时几何更新；原有点击、详情浮层与拖动保存行为不回归。
 6. 切换布局模式或项目后旧 SVG、ResizeObserver 与窗口监听全部清理；图层从不写入 layout sidecar、manifest 或其它持久化。
+7. 4096 资源链式 fixture 下，拖动一张卡片只更新它关联的线段；同一图层 100 次拖动期间 Observer 仍只构造一次。真实 Chromium 目标为拖动 p95 小于 `16.7ms`、不出现超过 `50ms` 的 long task，并完整显示最右侧自环与箭头。
 
 ## 8. 非目标
 
-- 本切片仍不实现资源替换、不可变迭代版本、画板编辑状态、测试切片、数值参数或泥点归因；已实现的资源关系图只提供前端派生展示，不建立新的资源业务真相。
+- 本切片仍不实现资源替换、不可变迭代版本、画板编辑状态、测试切片、数值参数或泥点归因；已实现的资源关系图只提供 Rust 只读拓扑与前端派生展示，不建立新的资源业务真相。
 - 本切片不保存资源详情浮层位置、画布缩放 / 平移、搜索条件、筛选条件或当前 mode；这些状态如需持久化必须另行扩展合同，不能塞入 `game-creator-resource-layout.v1`。
 - 不修改 SpacetimeDB schema。
 - 不开放普通用户 Agent.md/Skill。
diff --git a/docs/project-memory/shared-memory/decision-log.md b/docs/project-memory/shared-memory/decision-log.md
index 206355a44..693abc26c 100644
--- a/docs/project-memory/shared-memory/decision-log.md
+++ b/docs/project-memory/shared-memory/decision-log.md
@@ -16,13 +16,15 @@
 
 ---
 
-## 2026-07-31 AI 游戏创作资源依赖图采用纯前端派生 SVG
+## 2026-07-31 AI 游戏创作资源依赖图采用 Rust 只读拓扑与前端派生 SVG
 
 - 背景：资源画布已有 dependency / type 双模式坐标与本地 CAS sidecar，但 dependency 模式尚未把当前 manifest 中可证明的资源引用和任务流转可视化；关系图不能反向污染布局持久化或建立第二套资源真相。
-- 决策：dependency 模式从当前资源卡投影与 manifest task 派生 `ProjectResourceGraph`，使用原生 SVG 底层图层渲染。资产 `source.referenceResourceIds` 只在唯一匹配另一资产 `source.resourceId` 后形成橙色实线；任务依赖按任务对聚合为灰色虚线主线与两端分支，禁止资源笛卡尔积。图模型以迭代式强连通分量分析识别资源环和完整任务 DAG 环；搜索、选择、拖动只改变当前图层几何和高亮。
-- 生命周期与边界：type 模式不挂载图层；切换 mode、项目或卸载工作台时销毁 SVG、ResizeObserver 和窗口监听。SVG 统一 `pointer-events: none`，不干扰卡片点击/拖动；path、marker、图结构和 section 原点从不持久化。本切片不修改 Rust、Tauri command、layout sidecar、`resourceCanvasLayoutModel.ts`、manifest、api-server 或 SpacetimeDB，也不引入第三方图表库。
-- 影响范围：`apps/ai-game-creator-shell` 项目开发资源投影、依赖图模型、SVG overlay、样式与前端测试，以及工作台 PRD 和客户端实施计划。
-- 验证方式：图模型与 SVG 定向测试覆盖去重、无效 ID、完整任务环、可见资源自引用闭环、任务流聚合、搜索过滤、选择高亮和拖动几何；AppSurface 覆盖两种边、type 模式卸载和项目切换销毁，并运行 shell typecheck、编码检查与 `git diff --check`。
+- 决策：dependency 模式由 Tauri Rust 只读命令从当前 manifest、资源卡身份和有界 `.agent/agent.db` 审计构建稳定 `ProjectResourceGraph` read model，前端只归一化 DTO、测量卡片坐标并用原生 SVG 渲染。资产 `source.referenceResourceIds` 只在唯一匹配另一资产 `source.resourceId` 后形成橙色实线；任务依赖按任务对聚合为灰色虚线主线与两端分支，禁止资源笛卡尔积。Rust 以迭代式强连通分量分析识别资源环和完整任务 DAG 环，并返回资源局部连接索引。
+- 任务身份：External Editor 响应中的 `source.taskId` 是平台生成任务 ID，不等于本地 manifest task ID，禁止据此分配 producer。画布资产只接受 `agent.runtime.canvas.asset_generate` 审计中经当前 manifest task 校验的 `assetId -> agentId`；证据缺失、冲突或已超出有界读取窗口时不生成对应 task flow。任务产物与 Agent 回执继续使用自身已有的 manifest task 身份。
+- 生命周期与边界：Pointer Move 先用 `requestAnimationFrame` 合帧；基础 positions 与拖动预览分离，SVG 静态拓扑保持复用，每帧只按局部索引更新拖动资源关联的 reference edge 和 task flow。`ResizeObserver` 在单个图层生命周期只创建一次。type 模式不挂载图层；切换 mode、项目或卸载工作台时销毁 SVG、Observer 和窗口监听。SVG 统一 `pointer-events: none`；path、marker、图结构和 section 原点从不持久化。
+- 数据边界：本切片只新增 Tauri Rust 只读 read model，不修改 layout sidecar、`resourceCanvasLayoutModel.ts`、manifest、api-server、SpacetimeDB schema 或生成绑定，也不引入第三方图表库。dependency section 只在显示层额外预留 `64px` 右侧视觉 gutter，卡片坐标和持久化布局不变。
+- 影响范围：`apps/ai-game-creator-shell` 的 Tauri project read model/command、项目开发资源投影、依赖图 DTO、SVG overlay、样式与前后端测试，以及工作台 PRD 和客户端实施计划。
+- 验证方式：Rust 定向测试覆盖真实 producer 映射、拒绝复用外部 `taskId`、证据缺失、去重、无效 ID、完整任务环、4096 任务链与聚合复杂度；前端模型和 SVG 测试覆盖 DTO 防御过滤、局部上下游、可见资源自引用闭环、搜索、高亮、单帧局部 path 更新和稳定 Observer；AppSurface 覆盖生产数据形状、两种边、type 模式卸载和项目切换销毁，并运行 shell typecheck、编码检查与 `git diff --check`。
 - 关联文档：`docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md`、`docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md`。
 
 ---
diff --git a/docs/project-memory/shared-memory/pitfalls.md b/docs/project-memory/shared-memory/pitfalls.md
index fe9792898..8a5d2f94d 100644
--- a/docs/project-memory/shared-memory/pitfalls.md
+++ b/docs/project-memory/shared-memory/pitfalls.md
@@ -14,6 +14,14 @@
 - 关联：相关文件、文档、提交或 Issue
 ```
 
+## External Editor taskId 不能当作本地 manifest taskId
+
+- 现象：画布资产之间已有橙色精确引用线，但依赖任务之间没有灰色 task flow；测试用 `design-foundation` 之类字符串时正常，真实生成返回 `task-1` 后失败。
+- 原因：`GameCreationAppAssetSource.taskId` 保存的是 External Editor 生成任务身份，命名空间与本地 `.agent/manifest.json` 的 Agent/task 身份不同；前端用 `taskById.get(source.taskId)` 会让真实画布资产全部失去 producer。
+- 处理：资源依赖图的 Tauri Rust read model 从有界 `.agent/agent.db` 读取 `agent.runtime.canvas.asset_generate`，以 `assetId -> agentId` 映射 producer，并要求 `agentId` 存在于当前 manifest。记录缺失、多个不同有效 Agent 冲突或读取已截断时失败关闭该资产的 task flow，不回退 `source.taskId`。精确 `asset-reference` 仍只依赖 manifest 中外部 resourceId 的唯一匹配。
+- 验证：Rust fixture 把 `source.taskId` 固定为 `task-1 / task-2`，只有审计提供 `art-director / design-foundation` 后才生成 task flow；移除审计后橙色引用保留、灰色任务流消失。AppSurface 使用相同生产数据形状回归。
+- 关联：`apps/ai-game-creator-shell/src-tauri/src/project/resource_dependency_graph.rs`、`apps/ai-game-creator-shell/src/view/project-development/resourceDependencyGraphModel.ts`、`docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md`。
+
 ## Jenkins 异步备份不能用 nohup 脱离作业
 
 - 现象：Stdb Publish 成功，上传日志只留下“已获取进程锁 / 上传已有备份 / 目标对象”，没有成功或可捕获错误；本地 tar.gz 和 `uploadStatus=deferred` manifest 每次发布后继续增长。
diff --git a/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md b/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md
index e45244831..028317ddd 100644
--- a/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md
+++ b/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md
@@ -364,18 +364,20 @@ game-project/
 
 2026-07-30 Rust 并发与零副作用加固状态：资源布局锁已由 `create_new + mtime stale 删除` 改为持久锁文件上的 Unix `flock` / Windows 独占句柄，活锁即使 mtime 很旧也不能被另一个写入者回收，释放后仍复用同一文件实例。更新命令携带只用于校验的 `expectedProjectId`，在任何目录创建前先读取 manifest 并拒绝旧项目窗口，锁内再次核对 projectId；不存在根、非项目根、损坏 manifest 和路径重建后的旧窗口均不产生 `.agent/workbench`。revision 在共享 serde、Tauri 命令和前端 IPC 三层限制到 `Number.MAX_SAFE_INTEGER`，达到上限时保持原文件并失败关闭，不能让 Rust `u64` 值在 JavaScript 中失真后击穿 CAS。
 
-### 资源依赖关系图层 V1
+### 资源依赖关系图层 V1.1
 
-2026-07-31 起，项目工作台在不修改 Rust、layout sidecar 和既有布局模型的前提下增加纯前端资源依赖图层：
+2026-07-31 起，项目工作台使用“Tauri Rust 只读拓扑 + 前端原生 SVG 几何”的资源依赖图层；不修改 layout sidecar、既有布局模型、api-server 或 SpacetimeDB：
 
-- `resourceDependencyGraphModel.ts` 负责从当前资源卡投影和 manifest task 构建 `ProjectResourceGraph`。精确引用把资产 `source.referenceResourceIds` 唯一匹配到另一资产的 `source.resourceId`，再转换为实际卡片 ID；无匹配、多匹配和已删除资源只记录为 unresolved，不生成边。引用边按 `sourceResourceId + targetResourceId` 稳定去重。
-- task flow 只读取存在于当前 manifest 的任务依赖。资源按 `producerTaskId` 分组，每个 `sourceTaskId -> targetTaskId` 只生成一个聚合 flow；SVG 侧绘制 source 分支、唯一主线和 target 分支，路径数量为 `O(S+T)`，禁止资源笛卡尔积。
-- 资源引用图和完整任务依赖图分别使用迭代式强连通分量分析。任务环检测不能依赖可视 task flow 是否有两端资源，否则无产物任务参与的环会漏报；循环边只带 cyclic 标记，不触发递归展开。
+- `read_local_project_resource_graph` 读取当前 manifest、前端资源卡身份列表和最多 `32 MiB` 的安全 Agent DB 尾部，通过 Rust 构建稳定 read model；读取使用既有 Agent DB 普通文件 / 链接 / 追加锁边界，不新增数据库或 sidecar。返回资源 ID、引用边、聚合任务流、producer assignment、循环集合、unresolved 外部 ID、局部连接索引和 `producerMappingTruncated`。
+- 精确引用把 manifest 资产 `source.referenceResourceIds` 唯一匹配到另一资产的 `source.resourceId`，再转换为本次资源卡 ID；无匹配、多匹配、重复卡片或已删除资源只记录为 unresolved / 忽略，不生成边。引用边按 `sourceResourceId + targetResourceId` 稳定去重；前端 `resourceDependencyGraphModel.ts` 再做一次 DTO 端点防御过滤，避免异步切项目时出现幽灵线。
+- task flow 只读取存在于当前 manifest 的任务依赖。画布资产 producer 仅接受 `agent.runtime.canvas.asset_generate` 中经 manifest 校验的 `assetId -> agentId`；External Editor 返回并保存在 `source.taskId` 的 `task-1` 等身份属于平台生成任务，禁止复用为 manifest task。多个有效 Agent 对同一资产形成冲突或证据缺失时，不生成该资产对应 task flow。任务产物 / Agent 回执继续使用资源投影中已有的 manifest task 身份。
+- 资源按可信 producer 分组，每个 `sourceTaskId -> targetTaskId` 只生成一个聚合 flow；SVG 侧绘制 source 分支、唯一主线和 target 分支，路径数量为 `O(S+T)`，禁止资源笛卡尔积。局部连接索引保存 resource 关联的 reference edge ID / task flow ID，不预先展开 `S×T` 邻接矩阵。
+- 资源引用图和完整任务依赖图在 Rust 分别使用迭代式强连通分量分析。任务环检测不能依赖可视 task flow 是否有两端资源，否则无产物任务参与的环会漏报；循环边只带 cyclic 标记，不触发递归展开。
 - `ResourceDependencyOverlay.tsx` 使用原生 SVG path/marker，绝对定位在 `.game-resource-canvas-content` 底层并统一 `pointer-events: none`。橙色实线表示 `asset-reference`，灰色圆头虚线表示 `task-flow`；两类连线统一使用连续贝塞尔曲线，任务主线略强于两端分支，箭头使用不随高亮线宽缩放的稳定用户空间尺寸，避免直角折线、突兀拐弯和箭头跳变。不引入 D3、React Flow 或其它图表依赖。
-- `asset-reference` 的 source / target 是同一资源时使用卡片右侧外绕贝塞尔闭环，两个锚点分开且 marker 保留在返回锚点；路径不穿过卡片，并与普通边一样直接由拖动预览坐标重算。
-- 图层用 SVG 自身节点定位所属画布容器，测量各 section plane 相对原点；`ResizeObserver` 与 window resize 只负责重新测量，并在卸载时清理。这样不依赖父组件 ref 在子组件 layout effect 中的绑定时序。type 模式不挂载图层；项目身份作为 key，切换 mode、项目或工作台卸载都会销毁旧 SVG。
-- 搜索可见 ID 在几何阶段过滤端点；选中资源只查询一跳上下游与关联边，关联卡片和边高亮，其余边弱化。拖动预览坐标直接替换当前卡片坐标传入图层，pointer move 实时更新 path；结束后仍只通过原布局 Hook 保存卡片坐标，SVG 几何从不持久化。
-- 前端模型、SVG 单测和工作台 AppSurface 回归覆盖精确引用、去重、无效 ID、完整任务环、聚合复杂度、搜索过滤、选择高亮、拖动更新、type 模式卸载与项目切换销毁。该切片不修改 `resourceCanvasLayoutModel.ts`、Tauri command、layout sidecar、`api-server`、Rust 或 SpacetimeDB。
+- `asset-reference` 的 source / target 是同一资源时使用卡片右侧外绕贝塞尔闭环，两个锚点分开且 marker 保留在返回锚点；路径不穿过卡片。dependency section 在现有 extent 外额外增加 `64px` 右侧视觉 gutter，确保最右卡片的闭环和箭头可滚动显示；不改卡片坐标、`resourceCanvasLayoutModel.ts` 或 sidecar。
+- 图层用 SVG 自身节点定位所属画布容器，测量各 section plane 相对原点；`ResizeObserver` 在图层挂载时只创建一次，与 window resize 一起负责重新测量并在卸载时清理。type 模式不挂载图层且释放 graph state；项目身份作为 key，切换 mode、项目或工作台卸载都会销毁旧 SVG。
+- 基础 positions 保持稳定，拖动预览单独传入。Pointer Move 通过 `requestAnimationFrame` 合帧；静态 task/reference React SVG 子树不依赖 drag preview，每帧只按局部连接索引重新计算当前资源关联的 edge / flow 并更新对应 path `d`。搜索、选择、项目切换、真实 positions 或 section origin 变化才允许重新协调静态图层；结束后仍只通过原布局 Hook 保存卡片坐标，SVG 几何从不持久化。
+- Rust、前端 DTO/SVG 和工作台 AppSurface 回归覆盖生产 `task-1` 数据形状、真实 producer、证据缺失、精确引用、去重、无效 ID、完整任务环、4096 链式拓扑、聚合复杂度、搜索过滤、选择高亮、局部拖动更新、稳定 Observer、type 模式卸载与项目切换销毁。真实 Chromium 性能目标为拖动 p95 `<16.7ms`、不出现 `>50ms` long task；若实测仍超过预算，再增加 viewport + overscan 边裁剪，不在首轮预先引入额外复杂度。
 
 ## 分阶段实施
 
-- 
2.52.0


From cced839da513f7484d3c5623e395793254ce3345 Mon Sep 17 00:00:00 2001
From: menghao <mh18530625731@163.com>
Date: Fri, 31 Jul 2026 19:31:24 +0800
Subject: [PATCH 05/27] =?UTF-8?q?=E4=BF=AE=E5=A4=8D=E5=90=88=E5=B9=B6?=
 =?UTF-8?q?=E5=90=8E=E7=9A=84=E5=89=8D=E7=AB=AFLint=E9=97=A8=E7=A6=81?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

稳定项目总控响应流更新回调并补齐Effect依赖
调整Agent Runtime模型测试的导入顺序
通过完整ESLint、类型检查和AppSurface回归测试
---
 apps/ai-game-creator-shell/src/App.tsx        | 124 +++++++++---------
 .../tests/agentRuntimeModel.test.ts           |   2 +-
 2 files changed, 66 insertions(+), 60 deletions(-)

diff --git a/apps/ai-game-creator-shell/src/App.tsx b/apps/ai-game-creator-shell/src/App.tsx
index f24759d9e..561be140e 100644
--- a/apps/ai-game-creator-shell/src/App.tsx
+++ b/apps/ai-game-creator-shell/src/App.tsx
@@ -815,67 +815,70 @@ export function App({
     [gameChatOnly],
   );
 
-  function updateProjectSupervisorResponseStream(
-    incoming: AgentRuntimeResponseStream | null | undefined,
-    runtime: AgentRuntimeState,
-  ) {
-    let nextStream = mergeProjectSupervisorResponseStream(
-      projectSupervisorResponseStreamRef.current,
-      incoming,
-      runtime,
-    );
-    const candidateStream = nextStream;
-    if (candidateStream?.status === 'ready' && gameChatOnly) {
-      const text = candidateStream.accumulatedText.trim();
-      const responseKey = projectSupervisorResponseStreamIdentity(
-        candidateStream,
+  const updateProjectSupervisorResponseStream = useCallback(
+    (
+      incoming: AgentRuntimeResponseStream | null | undefined,
+      runtime: AgentRuntimeState,
+    ) => {
+      let nextStream = mergeProjectSupervisorResponseStream(
+        projectSupervisorResponseStreamRef.current,
+        incoming,
+        runtime,
       );
-      const messageId = `runtime-response:${responseKey}`;
-      const alreadyCommitted =
-        gameChatCommittedResponseStreamKeysRef.current.has(responseKey) ||
-        latestMessagesRef.current.some(
-          (message) => message.messageId === messageId,
+      const candidateStream = nextStream;
+      if (candidateStream?.status === 'ready' && gameChatOnly) {
+        const text = candidateStream.accumulatedText.trim();
+        const responseKey = projectSupervisorResponseStreamIdentity(
+          candidateStream,
         );
-      if (text && !alreadyCommitted) {
-        gameChatCommittedResponseStreamKeysRef.current.add(responseKey);
-        const nextMessage: ChatMessage = {
-          role: 'assistant',
-          text: candidateStream.accumulatedText,
-          messageId,
-          agentId: PROJECT_SUPERVISOR_AGENT_ID,
-          updatedAt: candidateStream.updatedAt,
-          runtimeOwned: true,
-        };
-        setMessages((current) => {
-          if (current.some((message) => message.messageId === messageId)) {
-            latestMessagesRef.current = current;
-            return current;
-          }
-          const nextMessages = [...current, nextMessage];
-          latestMessagesRef.current = nextMessages;
-          return nextMessages;
-        });
+        const messageId = `runtime-response:${responseKey}`;
+        const alreadyCommitted =
+          gameChatCommittedResponseStreamKeysRef.current.has(responseKey) ||
+          latestMessagesRef.current.some(
+            (message) => message.messageId === messageId,
+          );
+        if (text && !alreadyCommitted) {
+          gameChatCommittedResponseStreamKeysRef.current.add(responseKey);
+          const nextMessage: ChatMessage = {
+            role: 'assistant',
+            text: candidateStream.accumulatedText,
+            messageId,
+            agentId: PROJECT_SUPERVISOR_AGENT_ID,
+            updatedAt: candidateStream.updatedAt,
+            runtimeOwned: true,
+          };
+          setMessages((current) => {
+            if (current.some((message) => message.messageId === messageId)) {
+              latestMessagesRef.current = current;
+              return current;
+            }
+            const nextMessages = [...current, nextMessage];
+            latestMessagesRef.current = nextMessages;
+            return nextMessages;
+          });
+        }
+        // Ready text is now a normal chat message; transientReply must not show
+        // the same response a second time while polling/event delivery catches up.
+        nextStream = null;
+      } else if (
+        candidateStream &&
+        latestMessagesRef.current.some(
+          (message) =>
+            message.runtimeOwned &&
+            message.role === 'assistant' &&
+            message.text === candidateStream.accumulatedText &&
+            typeof message.updatedAt === 'number' &&
+            message.updatedAt >= candidateStream.startedAt,
+        )
+      ) {
+        // Keep the existing supervisor-chat behavior for restored history.
+        nextStream = null;
       }
-      // Ready text is now a normal chat message; transientReply must not show
-      // the same response a second time while polling/event delivery catches up.
-      nextStream = null;
-    } else if (
-      candidateStream &&
-      latestMessagesRef.current.some(
-        (message) =>
-          message.runtimeOwned &&
-          message.role === 'assistant' &&
-          message.text === candidateStream.accumulatedText &&
-          typeof message.updatedAt === 'number' &&
-          message.updatedAt >= candidateStream.startedAt,
-      )
-    ) {
-      // Keep the existing supervisor-chat behavior for restored history.
-      nextStream = null;
-    }
-    projectSupervisorResponseStreamRef.current = nextStream;
-    setProjectSupervisorResponseStream(nextStream);
-  }
+      projectSupervisorResponseStreamRef.current = nextStream;
+      setProjectSupervisorResponseStream(nextStream);
+    },
+    [gameChatOnly],
+  );
 
   function resetProjectSupervisorState() {
     projectSupervisorHistoryLoadVersionRef.current += 1;
@@ -1155,7 +1158,10 @@ export function App({
       disposed = true;
       cleanup?.();
     };
-  }, [updateProjectSupervisorRuntime]);
+  }, [
+    updateProjectSupervisorResponseStream,
+    updateProjectSupervisorRuntime,
+  ]);
 
   useEffect(() => {
     const invoke = resolveTauriInvoke();
diff --git a/apps/ai-game-creator-shell/tests/agentRuntimeModel.test.ts b/apps/ai-game-creator-shell/tests/agentRuntimeModel.test.ts
index 7757782ff..746c6c2a5 100644
--- a/apps/ai-game-creator-shell/tests/agentRuntimeModel.test.ts
+++ b/apps/ai-game-creator-shell/tests/agentRuntimeModel.test.ts
@@ -8,12 +8,12 @@ import type {
 } from '../src/app/types';
 import {
   formatAgentRuntimeEvent,
+  mergeGameChatRuntimeResponseMessagesIntoHistory,
   projectRuntimeVisibleCurrentWork,
   projectRuntimeVisibleError,
   projectSupervisorChatRuntimeStatus,
   projectSupervisorResponseStreamIdentity,
   projectSupervisorVisibleConversationText,
-  mergeGameChatRuntimeResponseMessagesIntoHistory,
   submitProjectSupervisorRuntimeTask,
 } from '../src/features/agent-runtime/model';
 
-- 
2.52.0


From 05c608214ec2ba7ae11051138ccb44855e6d3a0b Mon Sep 17 00:00:00 2001
From: menghao <mh18530625731@163.com>
Date: Mon, 3 Aug 2026 11:16:02 +0800
Subject: [PATCH 06/27] =?UTF-8?q?=E4=BF=AE=E5=A4=8D=E8=B5=84=E6=BA=90?=
 =?UTF-8?q?=E4=BE=9D=E8=B5=96=E5=9B=BE=E5=B8=83=E5=B1=80=E5=88=9D=E5=A7=8B?=
 =?UTF-8?q?=E5=8C=96=E4=B8=8E=E6=8B=96=E5=8A=A8=E6=80=A7=E8=83=BD?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

将任务依赖深度迁移到 Rust SCC 压缩图并返回稳定结果

为 dependency 模式增加图加载屏障并重派生自动布局

通过 DOM 热路径和局部 SVG 缓存避免拖动全量 React 重渲染

补充 4096 资源、异步初始化及布局保持回归测试

同步工作台 PRD、技术方案与共享项目记忆
---
 .../src/project/resource_dependency_graph.rs  | 115 +++++
 .../ResourceDependencyOverlay.tsx             | 207 ++++++---
 .../src/view/project-development/index.tsx    | 401 ++++++++++--------
 .../resourceDependencyGraphModel.ts           |  29 +-
 .../useProjectResourceCanvasLayout.ts         | 123 +++++-
 .../tests/ResourceDependencyOverlay.test.ts   |  71 ++--
 .../tests/appSurface/home.suite.ts            |   4 +-
 .../appSurface/project-development.suite.ts   | 277 +++++++++++-
 .../resourceDependencyGraphModel.test.ts      |  24 +-
 .../useProjectResourceCanvasLayout.test.ts    | 122 ++++++
 ...AI游戏创作】项目开发工作台PRD-2026-07-20.md |  13 +-
 .../shared-memory/decision-log.md             |   7 +
 docs/project-memory/shared-memory/pitfalls.md |   8 +
 ...�案】AI游戏创作智能体App实施计划-2026-06-24.md |   4 +
 14 files changed, 1087 insertions(+), 318 deletions(-)

diff --git a/apps/ai-game-creator-shell/src-tauri/src/project/resource_dependency_graph.rs b/apps/ai-game-creator-shell/src-tauri/src/project/resource_dependency_graph.rs
index 54630f25e..3cf87fe77 100644
--- a/apps/ai-game-creator-shell/src-tauri/src/project/resource_dependency_graph.rs
+++ b/apps/ai-game-creator-shell/src-tauri/src/project/resource_dependency_graph.rs
@@ -50,6 +50,7 @@ pub(crate) struct ProjectResourceConnectionIndex {
 pub(crate) struct ProjectResourceProducerAssignment {
     pub resource_id: String,
     pub task_id: String,
+    pub dependency_depth: u32,
 }
 
 #[derive(Clone, Debug, Eq, PartialEq, Serialize)]
@@ -77,6 +78,7 @@ struct DirectedEdge {
 struct CycleAnalysis {
     cyclic_node_ids: BTreeSet<String>,
     cyclic_edge_ids: BTreeSet<String>,
+    component_by_node: BTreeMap<String, usize>,
 }
 
 #[derive(Debug, Default)]
@@ -185,9 +187,68 @@ fn analyze_directed_cycles<'a>(
             result.cyclic_edge_ids.insert(edge.id.clone());
         }
     }
+    result.component_by_node = component_by_node;
     result
 }
 
+fn dependency_depth_by_node(
+    analysis: &CycleAnalysis,
+    edges: &[DirectedEdge],
+) -> BTreeMap<String, u32> {
+    let component_count = analysis
+        .component_by_node
+        .values()
+        .copied()
+        .max()
+        .map_or(0, |max_component| max_component + 1);
+    let mut outgoing = vec![BTreeSet::<usize>::new(); component_count];
+    let mut indegree = vec![0usize; component_count];
+    for edge in edges {
+        let Some(&source_component) = analysis.component_by_node.get(&edge.source_id) else {
+            continue;
+        };
+        let Some(&target_component) = analysis.component_by_node.get(&edge.target_id) else {
+            continue;
+        };
+        if source_component != target_component
+            && outgoing[source_component].insert(target_component)
+        {
+            indegree[target_component] += 1;
+        }
+    }
+
+    let mut ready = indegree
+        .iter()
+        .enumerate()
+        .filter_map(|(component, degree)| (*degree == 0).then_some(component))
+        .collect::<BTreeSet<_>>();
+    let mut depth_by_component = vec![0u32; component_count];
+    while let Some(component) = ready.pop_first() {
+        for &target in &outgoing[component] {
+            depth_by_component[target] =
+                depth_by_component[target].max(depth_by_component[component].saturating_add(1));
+            indegree[target] -= 1;
+            if indegree[target] == 0 {
+                ready.insert(target);
+            }
+        }
+    }
+
+    analysis
+        .component_by_node
+        .iter()
+        .map(|(node_id, component)| {
+            (
+                node_id.clone(),
+                depth_by_component
+                    .get(*component)
+                    .copied()
+                    .unwrap_or_default(),
+            )
+        })
+        .collect()
+}
+
 fn audit_asset_producers(
     records: &[serde_json::Value],
     task_ids: &BTreeSet<String>,
@@ -403,6 +464,7 @@ pub(crate) fn build_project_resource_graph(
         })
         .collect::<Vec<_>>();
     let task_cycles = analyze_directed_cycles(task_by_id.keys(), &task_dependency_edges);
+    let task_dependency_depths = dependency_depth_by_node(&task_cycles, &task_dependency_edges);
     let task_flows = task_dependency_edges
         .iter()
         .filter_map(|edge| {
@@ -476,6 +538,10 @@ pub(crate) fn build_project_resource_graph(
             .into_iter()
             .map(|(resource_id, task_id)| ProjectResourceProducerAssignment {
                 resource_id,
+                dependency_depth: task_dependency_depths
+                    .get(&task_id)
+                    .copied()
+                    .unwrap_or_default(),
                 task_id,
             })
             .collect(),
@@ -610,6 +676,14 @@ mod tests {
         assert_eq!(graph.task_flows.len(), 1);
         assert_eq!(graph.task_flows[0].source_task_id, "art-director");
         assert_eq!(graph.task_flows[0].target_task_id, "design-foundation");
+        assert_eq!(
+            graph
+                .producer_assignments
+                .iter()
+                .map(|assignment| (assignment.resource_id.as_str(), assignment.dependency_depth,))
+                .collect::<BTreeMap<_, _>>(),
+            BTreeMap::from([("asset:spec", 0), ("asset:ui", 1)]),
+        );
         assert!(graph
             .producer_assignments
             .iter()
@@ -734,5 +808,46 @@ mod tests {
             .connection_index
             .iter()
             .all(|index| index.task_flow_ids.len() <= 2));
+        assert_eq!(
+            graph
+                .producer_assignments
+                .iter()
+                .find(|assignment| assignment.resource_id == "resource:4095")
+                .map(|assignment| assignment.dependency_depth),
+            Some(4095),
+        );
+    }
+
+    #[test]
+    fn dependency_depth_collapses_cycles_before_following_downstream_tasks() {
+        let graph = build_project_resource_graph(
+            &manifest(
+                vec![
+                    task("source", &[]),
+                    task("cycle-a", &["source", "cycle-b"]),
+                    task("cycle-b", &["cycle-a"]),
+                    task("target", &["cycle-b"]),
+                ],
+                Vec::new(),
+            ),
+            vec![
+                resource("source-resource", None, Some("source")),
+                resource("cycle-a-resource", None, Some("cycle-a")),
+                resource("cycle-b-resource", None, Some("cycle-b")),
+                resource("target-resource", None, Some("target")),
+            ],
+            &[],
+            false,
+        );
+
+        let depths = graph
+            .producer_assignments
+            .iter()
+            .map(|assignment| (assignment.resource_id.as_str(), assignment.dependency_depth))
+            .collect::<BTreeMap<_, _>>();
+        assert_eq!(depths["source-resource"], 0);
+        assert_eq!(depths["cycle-a-resource"], 1);
+        assert_eq!(depths["cycle-b-resource"], 1);
+        assert_eq!(depths["target-resource"], 2);
     }
 }
diff --git a/apps/ai-game-creator-shell/src/view/project-development/ResourceDependencyOverlay.tsx b/apps/ai-game-creator-shell/src/view/project-development/ResourceDependencyOverlay.tsx
index 238abba58..19ccd9bbb 100644
--- a/apps/ai-game-creator-shell/src/view/project-development/ResourceDependencyOverlay.tsx
+++ b/apps/ai-game-creator-shell/src/view/project-development/ResourceDependencyOverlay.tsx
@@ -1,4 +1,13 @@
-import { useId, useLayoutEffect, useMemo, useRef, useState } from 'react';
+import {
+  forwardRef,
+  useCallback,
+  useId,
+  useImperativeHandle,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useState,
+} from 'react';
 
 import type {
   ProjectResourceCanvasPosition,
@@ -34,11 +43,21 @@ type RectLookup = {
 export type ResourceDependencyOverlayProps = {
   graph: ProjectResourceGraph;
   positions: readonly ProjectResourceCanvasPosition[];
-  dragPreview: (Point & { resourceId: string }) | null;
   visibleResourceIds: ReadonlySet<string>;
   selectedResourceId: string | null;
 };
 
+export type ResourceDependencyOverlayHandle = {
+  updateDragPreview: (preview: Point & { resourceId: string }) => void;
+  clearDragPreview: () => void;
+};
+
+type TaskFlowPathRefs = {
+  sourceBranches: Map<string, SVGPathElement>;
+  targetBranches: Map<string, SVGPathElement>;
+  trunk: SVGPathElement | null;
+};
+
 const SECTION_SELECTOR = '[data-resource-section-plane]';
 const TASK_FLOW_HUB_GAP = 20;
 const CONNECTION_MAX_HANDLE = 180;
@@ -200,18 +219,25 @@ function taskFlowGeometry(
   return { sourceAnchors, targetAnchors, sourceHub, targetHub };
 }
 
-export function ResourceDependencyOverlay({
-  graph,
-  positions,
-  dragPreview,
-  visibleResourceIds,
-  selectedResourceId,
-}: ResourceDependencyOverlayProps) {
+export const ResourceDependencyOverlay = forwardRef<
+  ResourceDependencyOverlayHandle,
+  ResourceDependencyOverlayProps
+>(function ResourceDependencyOverlay(
+  { graph, positions, visibleResourceIds, selectedResourceId },
+  ref,
+) {
   const markerPrefix = useId().replace(/[^a-zA-Z0-9_-]/gu, '');
   const overlayRef = useRef<SVGSVGElement>(null);
   const referencePathRefs = useRef(new Map<string, SVGPathElement>());
-  const taskFlowGroupRefs = useRef(new Map<string, SVGGElement>());
-  const activeDragResourceIdRef = useRef<string | null>(null);
+  const taskFlowPathRefs = useRef(new Map<string, TaskFlowPathRefs>());
+  const activeDragPreviewRef = useRef<
+    (Point & { resourceId: string }) | null
+  >(null);
+  const graphRef = useRef(graph);
+  const positionByResourceIdRef = useRef(
+    new Map(positions.map((position) => [position.resourceId, position])),
+  );
+  const rectByResourceIdRef = useRef<Map<string, Rect>>(new Map());
   const [sectionOrigins, setSectionOrigins] = useState<SectionOrigins>({});
 
   useLayoutEffect(() => {
@@ -290,6 +316,11 @@ export function ResourceDependencyOverlay({
     }
     return result;
   }, [graph.resourceIds, positions, sectionOrigins, visibleResourceIds]);
+  graphRef.current = graph;
+  positionByResourceIdRef.current = new Map(
+    positions.map((position) => [position.resourceId, position]),
+  );
+  rectByResourceIdRef.current = rectByResourceId;
 
   const neighbors = useMemo(
     () => projectResourceGraphNeighbors(graph, selectedResourceId),
@@ -312,13 +343,6 @@ export function ResourceDependencyOverlay({
         }${flow.cyclic ? ' is-cyclic' : ''}`;
         return (
           <g
-            ref={(node) => {
-              if (node) {
-                taskFlowGroupRefs.current.set(flow.id, node);
-              } else {
-                taskFlowGroupRefs.current.delete(flow.id);
-              }
-            }}
             key={flow.id}
             className={className}
             data-edge-kind="task-flow"
@@ -332,6 +356,22 @@ export function ResourceDependencyOverlay({
             }`}</title>
             {geometry.sourceAnchors.map(({ resourceId, point }) => (
               <path
+                ref={(node) => {
+                  let refs = taskFlowPathRefs.current.get(flow.id);
+                  if (!refs) {
+                    refs = {
+                      sourceBranches: new Map(),
+                      targetBranches: new Map(),
+                      trunk: null,
+                    };
+                    taskFlowPathRefs.current.set(flow.id, refs);
+                  }
+                  if (node) {
+                    refs.sourceBranches.set(resourceId, node);
+                  } else {
+                    refs.sourceBranches.delete(resourceId);
+                  }
+                }}
                 key={`source:${resourceId}`}
                 className="game-resource-dependency-branch"
                 data-branch-side="source"
@@ -340,11 +380,39 @@ export function ResourceDependencyOverlay({
               />
             ))}
             <path
+              ref={(node) => {
+                let refs = taskFlowPathRefs.current.get(flow.id);
+                if (!refs) {
+                  refs = {
+                    sourceBranches: new Map(),
+                    targetBranches: new Map(),
+                    trunk: null,
+                  };
+                  taskFlowPathRefs.current.set(flow.id, refs);
+                }
+                refs.trunk = node;
+              }}
               className="game-resource-dependency-trunk"
               d={connectionPath(geometry.sourceHub, geometry.targetHub)}
             />
             {geometry.targetAnchors.map(({ resourceId, point }) => (
               <path
+                ref={(node) => {
+                  let refs = taskFlowPathRefs.current.get(flow.id);
+                  if (!refs) {
+                    refs = {
+                      sourceBranches: new Map(),
+                      targetBranches: new Map(),
+                      trunk: null,
+                    };
+                    taskFlowPathRefs.current.set(flow.id, refs);
+                  }
+                  if (node) {
+                    refs.targetBranches.set(resourceId, node);
+                  } else {
+                    refs.targetBranches.delete(resourceId);
+                  }
+                }}
                 key={`target:${resourceId}`}
                 className="game-resource-dependency-branch"
                 data-branch-side="target"
@@ -410,49 +478,49 @@ export function ResourceDependencyOverlay({
   );
 
   useLayoutEffect(() => {
-    const affectedResourceIds = new Set<string>();
-    if (activeDragResourceIdRef.current) {
-      affectedResourceIds.add(activeDragResourceIdRef.current);
-    }
-    if (dragPreview) {
-      affectedResourceIds.add(dragPreview.resourceId);
-    }
-    activeDragResourceIdRef.current = dragPreview?.resourceId ?? null;
-    if (affectedResourceIds.size === 0) {
-      return;
+    const activeFlowIds = new Set(graph.taskFlows.map((flow) => flow.id));
+    for (const flowId of taskFlowPathRefs.current.keys()) {
+      if (!activeFlowIds.has(flowId)) {
+        taskFlowPathRefs.current.delete(flowId);
+      }
     }
+  }, [graph.taskFlows]);
+
+  const updateAffectedGeometry = useCallback(
+    (
+      affectedResourceIds: ReadonlySet<string>,
+      dragPreview: (Point & { resourceId: string }) | null,
+    ) => {
+    const currentGraph = graphRef.current;
+    const currentRects = rectByResourceIdRef.current;
     const dragBasePosition = dragPreview
-      ? positions.find(
-          (position) => position.resourceId === dragPreview.resourceId,
-        )
+      ? positionByResourceIdRef.current.get(dragPreview.resourceId)
       : undefined;
     const rectLookup = {
       get(resourceId: string) {
-        const rect = rectByResourceId.get(resourceId);
+        const rect = currentRects.get(resourceId);
         if (!rect) {
           return undefined;
         }
         return dragPreview?.resourceId === resourceId
           ? {
               ...rect,
-              x:
-                rect.x - (dragBasePosition?.x ?? 0) + dragPreview.x,
-              y:
-                rect.y - (dragBasePosition?.y ?? 0) + dragPreview.y,
+              x: rect.x - (dragBasePosition?.x ?? 0) + dragPreview.x,
+              y: rect.y - (dragBasePosition?.y ?? 0) + dragPreview.y,
             }
           : rect;
       },
     };
     const affectedEdgeIds = new Set<string>();
     for (const resourceId of affectedResourceIds) {
-      const index = graph.connectionIndex.get(resourceId);
+      const index = currentGraph.connectionIndex.get(resourceId);
       index?.referenceEdgeIds.forEach((edgeId) =>
         affectedEdgeIds.add(edgeId),
       );
       index?.taskFlowIds.forEach((flowId) => affectedEdgeIds.add(flowId));
     }
     for (const edgeId of affectedEdgeIds) {
-      const referenceEdge = graph.referenceEdgeById.get(edgeId);
+      const referenceEdge = currentGraph.referenceEdgeById.get(edgeId);
       if (referenceEdge) {
         const geometry = referenceGeometry(referenceEdge, rectLookup);
         const path = referencePathRefs.current.get(edgeId);
@@ -461,45 +529,29 @@ export function ResourceDependencyOverlay({
         }
         continue;
       }
-      const flow = graph.taskFlowById.get(edgeId);
-      const group = taskFlowGroupRefs.current.get(edgeId);
-      if (!flow || !group) {
+      const flow = currentGraph.taskFlowById.get(edgeId);
+      const paths = taskFlowPathRefs.current.get(edgeId);
+      if (!flow || !paths) {
         continue;
       }
       const geometry = taskFlowGeometry(flow, rectLookup);
       if (!geometry) {
         continue;
       }
-      const sourcePathByResourceId = new Map<string, SVGPathElement>();
-      const targetPathByResourceId = new Map<string, SVGPathElement>();
-      group
-        .querySelectorAll<SVGPathElement>('.game-resource-dependency-branch')
-        .forEach((path) => {
-          const resourceId = path.dataset.resourceId;
-          if (!resourceId) {
-            return;
-          }
-          (path.dataset.branchSide === 'source'
-            ? sourcePathByResourceId
-            : targetPathByResourceId
-          ).set(resourceId, path);
-        });
       geometry.sourceAnchors.forEach(({ resourceId, point }) => {
-        sourcePathByResourceId
+        paths.sourceBranches
           .get(resourceId)
           ?.setAttribute(
             'd',
             taskFlowBranchPath(point, geometry.sourceHub),
           );
       });
-      group
-        .querySelector<SVGPathElement>('.game-resource-dependency-trunk')
-        ?.setAttribute(
-          'd',
-          connectionPath(geometry.sourceHub, geometry.targetHub),
-        );
+      paths.trunk?.setAttribute(
+        'd',
+        connectionPath(geometry.sourceHub, geometry.targetHub),
+      );
       geometry.targetAnchors.forEach(({ resourceId, point }) => {
-        targetPathByResourceId
+        paths.targetBranches
           .get(resourceId)
           ?.setAttribute(
             'd',
@@ -507,7 +559,32 @@ export function ResourceDependencyOverlay({
           );
       });
     }
-  }, [dragPreview, graph, positions, rectByResourceId]);
+    },
+    [],
+  );
+
+  useImperativeHandle(
+    ref,
+    () => ({
+      updateDragPreview(preview) {
+        const affectedResourceIds = new Set<string>();
+        if (activeDragPreviewRef.current) {
+          affectedResourceIds.add(activeDragPreviewRef.current.resourceId);
+        }
+        affectedResourceIds.add(preview.resourceId);
+        activeDragPreviewRef.current = preview;
+        updateAffectedGeometry(affectedResourceIds, preview);
+      },
+      clearDragPreview() {
+        const active = activeDragPreviewRef.current;
+        activeDragPreviewRef.current = null;
+        if (active) {
+          updateAffectedGeometry(new Set([active.resourceId]), null);
+        }
+      },
+    }),
+    [updateAffectedGeometry],
+  );
 
   return (
     <svg
@@ -550,4 +627,4 @@ export function ResourceDependencyOverlay({
       {renderReferenceEdges}
     </svg>
   );
-}
+});
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 3d8ed61bc..99870dfe7 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
@@ -18,6 +18,7 @@ import {
 } from 'lucide-react';
 import {
   type CSSProperties,
+  memo,
   type PointerEvent as ReactPointerEvent,
   type ReactNode,
   useCallback,
@@ -34,7 +35,6 @@ import type {
   GameCreationAppAgentGroup,
   GameCreationAppManifest,
   GameCreationAppPreviewState,
-  GameCreationAppTaskState,
   ProjectResourceCanvasLayoutMode,
   ProjectResourceCanvasSection,
 } from '../../../../../packages/shared/src/contracts/gameCreationApp';
@@ -58,7 +58,10 @@ import {
   type ProjectResourceGraphNodeInput,
   type ProjectResourceGraphReadModel,
 } from './resourceDependencyGraphModel';
-import { ResourceDependencyOverlay } from './ResourceDependencyOverlay';
+import {
+  ResourceDependencyOverlay,
+  type ResourceDependencyOverlayHandle,
+} from './ResourceDependencyOverlay';
 import { useProjectResourceCanvasLayout } from './useProjectResourceCanvasLayout';
 
 type AttachmentResult = {
@@ -88,6 +91,11 @@ type ResourceCardDrag = {
   startX: number;
   startY: number;
   moved: boolean;
+  element: HTMLButtonElement;
+  plane: HTMLElement | null;
+  planeBaseWidth: number;
+  planeBaseHeight: number;
+  visualGutter: number;
 };
 
 type ProjectResource = {
@@ -282,29 +290,6 @@ function imagePreviewErrorMessage(error: unknown) {
   return '图片暂时无法读取，请关闭后重试';
 }
 
-function taskDependencyDepth(
-  task: GameCreationAppTaskState,
-  taskById: Map<string, GameCreationAppTaskState>,
-  seen = new Set<string>(),
-): number {
-  if (seen.has(task.id) || task.dependencies.length === 0) {
-    return 0;
-  }
-  const nextSeen = new Set(seen).add(task.id);
-  return (
-    1 +
-    Math.max(
-      0,
-      ...task.dependencies.map((dependency) => {
-        const dependencyTask = taskById.get(dependency);
-        return dependencyTask
-          ? taskDependencyDepth(dependencyTask, taskById, nextSeen)
-          : 0;
-      }),
-    )
-  );
-}
-
 function resourcesFromProject(
   manifest: GameCreationAppManifest,
   attachments: AttachmentResult[],
@@ -333,7 +318,7 @@ function resourcesFromProject(
         externalResourceId: null,
         referenceResourceIds: [],
         dependencies: task.dependencies,
-        dependencyDepth: taskDependencyDepth(task, taskById),
+        dependencyDepth: 0,
       });
     }
   }
@@ -467,7 +452,7 @@ function summarizeAgent(
   };
 }
 
-function ResourceCard({
+const ResourceCard = memo(function ResourceCard({
   resource,
   selected,
   dragging,
@@ -486,8 +471,11 @@ function ResourceCard({
   relationState: 'upstream' | 'downstream' | 'both' | null;
   x: number;
   y: number;
-  onSelect: () => void;
-  onPointerDown: (event: ReactPointerEvent<HTMLButtonElement>) => void;
+  onSelect: (resourceId: string) => void;
+  onPointerDown: (
+    event: ReactPointerEvent<HTMLButtonElement>,
+    resource: ProjectResource,
+  ) => void;
   onPointerMove: (event: ReactPointerEvent<HTMLButtonElement>) => void;
   onPointerUp: (event: ReactPointerEvent<HTMLButtonElement>) => void;
   onPointerCancel: (event: ReactPointerEvent<HTMLButtonElement>) => void;
@@ -508,8 +496,8 @@ function ResourceCard({
           '--resource-y': `${y}px`,
         } as CSSProperties
       }
-      onClick={onSelect}
-      onPointerDown={onPointerDown}
+      onClick={() => onSelect(resource.id)}
+      onPointerDown={(event) => onPointerDown(event, resource)}
       onPointerMove={onPointerMove}
       onPointerUp={onPointerUp}
       onPointerCancel={onPointerCancel}
@@ -522,7 +510,7 @@ function ResourceCard({
       <small>{resource.path}</small>
     </button>
   );
-}
+});
 
 export default function ProjectDevelopmentView({
   projectName,
@@ -549,9 +537,6 @@ export default function ProjectDevelopmentView({
   const [draggedResourceId, setDraggedResourceId] = useState<string | null>(
     null,
   );
-  const [resourceDragPreview, setResourceDragPreview] = useState<
-    (Point & { resourceId: string }) | null
-  >(null);
   const [resourceDialogPosition, setResourceDialogPosition] =
     useState<Point | null>(null);
   const [imagePreview, setImagePreview] = useState<ImagePreviewState>({
@@ -563,6 +548,8 @@ export default function ProjectDevelopmentView({
   const dockRef = useRef<HTMLElement>(null);
   const resourceDialogRef = useRef<HTMLElement>(null);
   const resourceCardDragRef = useRef<ResourceCardDrag | null>(null);
+  const resourceDependencyOverlayRef =
+    useRef<ResourceDependencyOverlayHandle>(null);
   const pendingResourceDragPreviewRef = useRef<
     (Point & { resourceId: string }) | null
   >(null);
@@ -605,14 +592,20 @@ export default function ProjectDevelopmentView({
   );
   const [resourceGraphState, setResourceGraphState] = useState<{
     scopeKey: string;
+    status: 'idle' | 'loading' | 'ready' | 'failed';
     graph: ProjectResourceGraph;
-  }>({ scopeKey: '', graph: EMPTY_PROJECT_RESOURCE_GRAPH });
+  }>({
+    scopeKey: '',
+    status: 'idle',
+    graph: EMPTY_PROJECT_RESOURCE_GRAPH,
+  });
 
   useEffect(() => {
     let cancelled = false;
     if (sortMode !== 'dependency') {
       setResourceGraphState({
         scopeKey: '',
+        status: 'idle',
         graph: EMPTY_PROJECT_RESOURCE_GRAPH,
       });
       return () => {
@@ -623,12 +616,18 @@ export default function ProjectDevelopmentView({
     if (!invoke) {
       setResourceGraphState({
         scopeKey: resourceGraphScopeKey,
+        status: 'failed',
         graph: EMPTY_PROJECT_RESOURCE_GRAPH,
       });
       return () => {
         cancelled = true;
       };
     }
+    setResourceGraphState({
+      scopeKey: resourceGraphScopeKey,
+      status: 'loading',
+      graph: EMPTY_PROJECT_RESOURCE_GRAPH,
+    });
     void invoke<ProjectResourceGraphReadModel>(
       'read_local_project_resource_graph',
       {
@@ -641,6 +640,7 @@ export default function ProjectDevelopmentView({
         if (!cancelled) {
           setResourceGraphState({
             scopeKey: resourceGraphScopeKey,
+            status: 'ready',
             graph: normalizeProjectResourceGraph(readModel),
           });
         }
@@ -649,6 +649,7 @@ export default function ProjectDevelopmentView({
         if (!cancelled) {
           setResourceGraphState({
             scopeKey: resourceGraphScopeKey,
+            status: 'failed',
             graph: EMPTY_PROJECT_RESOURCE_GRAPH,
           });
         }
@@ -664,10 +665,19 @@ export default function ProjectDevelopmentView({
     sortMode,
   ]);
 
+  const resourceGraphScopeMatches =
+    resourceGraphState.scopeKey === resourceGraphScopeKey;
+  const resourceGraphReady =
+    resourceGraphScopeMatches && resourceGraphState.status === 'ready';
   const resourceGraph =
-    resourceGraphState.scopeKey === resourceGraphScopeKey
+    resourceGraphReady
       ? resourceGraphState.graph
       : EMPTY_PROJECT_RESOURCE_GRAPH;
+  const resourceGraphInitializationReady =
+    sortMode !== 'dependency' ||
+    (resourceGraphScopeMatches &&
+      (resourceGraphState.status === 'ready' ||
+        resourceGraphState.status === 'failed'));
   const manifestTaskById = useMemo(
     () => new Map(manifest.tasks.map((task) => [task.id, task])),
     [manifest.tasks],
@@ -681,18 +691,14 @@ export default function ProjectDevelopmentView({
         const producerTask = producerTaskId
           ? manifestTaskById.get(producerTaskId)
           : undefined;
-        return producerTask && producerTaskId !== resource.producerTaskId
-          ? {
-              ...resource,
-              taskTitle: producerTask.title,
-              producerTaskId,
-              dependencies: producerTask.dependencies,
-              dependencyDepth: taskDependencyDepth(
-                producerTask,
-                manifestTaskById,
-              ),
-            }
-          : resource;
+        return {
+          ...resource,
+          taskTitle: producerTask?.title ?? resource.taskTitle,
+          producerTaskId,
+          dependencies: producerTask?.dependencies ?? resource.dependencies,
+          dependencyDepth:
+            resourceGraph.dependencyDepthByResourceId.get(resource.id) ?? 0,
+        };
       }),
     [manifestTaskById, projectedResources, resourceGraph],
   );
@@ -706,6 +712,9 @@ export default function ProjectDevelopmentView({
     projectId: manifest.projectId,
     mode: sortMode,
     resources,
+    initializationReady: resourceGraphInitializationReady,
+    rederiveAutomaticPositions:
+      sortMode === 'dependency' && resourceGraphReady,
   });
   const resourcePositionById = useMemo(
     () =>
@@ -817,6 +826,34 @@ export default function ProjectDevelopmentView({
     approvalOptions.find((option) => option.id === approvalMode)?.label ??
     '严格审批';
 
+  const applyResourceDragPreview = useCallback(
+    (preview: Point & { resourceId: string }) => {
+      const drag = resourceCardDragRef.current;
+      if (!drag || drag.resourceId !== preview.resourceId) {
+        return;
+      }
+      drag.element.style.setProperty('--resource-x', `${preview.x}px`);
+      drag.element.style.setProperty('--resource-y', `${preview.y}px`);
+      if (drag.plane) {
+        drag.plane.style.width = `${Math.max(
+          drag.planeBaseWidth,
+          preview.x +
+            RESOURCE_CANVAS_CARD_WIDTH +
+            RESOURCE_CANVAS_COLUMN_GAP +
+            drag.visualGutter,
+        )}px`;
+        drag.plane.style.height = `${Math.max(
+          drag.planeBaseHeight,
+          preview.y +
+            RESOURCE_CANVAS_CARD_HEIGHT +
+            RESOURCE_CANVAS_ROW_GAP,
+        )}px`;
+      }
+      resourceDependencyOverlayRef.current?.updateDragPreview(preview);
+    },
+    [],
+  );
+
   const scheduleResourceDragPreview = useCallback(
     (preview: Point & { resourceId: string }) => {
       pendingResourceDragPreviewRef.current = preview;
@@ -828,11 +865,11 @@ export default function ProjectDevelopmentView({
         const pending = pendingResourceDragPreviewRef.current;
         pendingResourceDragPreviewRef.current = null;
         if (pending) {
-          setResourceDragPreview(pending);
+          applyResourceDragPreview(pending);
         }
       });
     },
-    [],
+    [applyResourceDragPreview],
   );
 
   const clearScheduledResourceDragPreview = useCallback(() => {
@@ -846,6 +883,7 @@ export default function ProjectDevelopmentView({
   useEffect(
     () => () => {
       clearScheduledResourceDragPreview();
+      resourceDependencyOverlayRef.current?.clearDragPreview();
     },
     [clearScheduledResourceDragPreview],
   );
@@ -860,8 +898,8 @@ export default function ProjectDevelopmentView({
     setSelectedResourceId(null);
     resourceCardDragRef.current = null;
     clearScheduledResourceDragPreview();
+    resourceDependencyOverlayRef.current?.clearDragPreview();
     setDraggedResourceId(null);
-    setResourceDragPreview(null);
   }, [clearScheduledResourceDragPreview, projectPath]);
 
   useEffect(() => {
@@ -987,81 +1025,135 @@ export default function ProjectDevelopmentView({
     return () => window.removeEventListener('resize', clampOnResize);
   }, [clampResourceDialogPosition, selectedResource]);
 
-  function handleResourceCardPointerDown(
-    event: ReactPointerEvent<HTMLButtonElement>,
-    resource: ProjectResource,
-  ) {
-    if (event.button !== 0) {
+  const handleResourceSelect = useCallback((resourceId: string) => {
+    if (suppressResourceClickRef.current === resourceId) {
+      suppressResourceClickRef.current = null;
       return;
     }
-    const position = resourcePositionById.get(resource.id);
-    if (!position || position.section !== resource.category) {
-      return;
-    }
-    clearScheduledResourceDragPreview();
-    resourceCardDragRef.current = {
-      pointerId: event.pointerId,
-      resourceId: resource.id,
-      section: resource.category,
-      startClientX: event.clientX,
-      startClientY: event.clientY,
-      startX: position.x,
-      startY: position.y,
-      moved: false,
-    };
-    event.currentTarget.setPointerCapture?.(event.pointerId);
-  }
+    setSelectedResourceId(resourceId);
+  }, []);
 
-  function handleResourceCardPointerMove(
-    event: ReactPointerEvent<HTMLButtonElement>,
-  ) {
-    const drag = resourceCardDragRef.current;
-    if (!drag || drag.pointerId !== event.pointerId) {
-      return;
-    }
-    const deltaX = event.clientX - drag.startClientX;
-    const deltaY = event.clientY - drag.startClientY;
-    if (
-      !drag.moved &&
-      Math.hypot(deltaX, deltaY) < RESOURCE_CANVAS_DRAG_THRESHOLD
-    ) {
-      return;
-    }
-    drag.moved = true;
-    setDraggedResourceId(drag.resourceId);
-    scheduleResourceDragPreview({
-      resourceId: drag.resourceId,
-      x: Math.max(0, drag.startX + deltaX),
-      y: Math.max(0, drag.startY + deltaY),
-    });
-    event.preventDefault();
-  }
+  const handleResourceCardPointerDown = useCallback(
+    (
+      event: ReactPointerEvent<HTMLButtonElement>,
+      resource: ProjectResource,
+    ) => {
+      if (event.button !== 0) {
+        return;
+      }
+      const position = resourcePositionById.get(resource.id);
+      if (!position || position.section !== resource.category) {
+        return;
+      }
+      clearScheduledResourceDragPreview();
+      const plane = event.currentTarget.parentElement;
+      resourceCardDragRef.current = {
+        pointerId: event.pointerId,
+        resourceId: resource.id,
+        section: resource.category,
+        startClientX: event.clientX,
+        startClientY: event.clientY,
+        startX: position.x,
+        startY: position.y,
+        moved: false,
+        element: event.currentTarget,
+        plane,
+        planeBaseWidth:
+          Number.parseFloat(plane?.style.width ?? '') ||
+          plane?.getBoundingClientRect().width ||
+          0,
+        planeBaseHeight:
+          Number.parseFloat(plane?.style.height ?? '') ||
+          plane?.getBoundingClientRect().height ||
+          0,
+        visualGutter:
+          sortMode === 'dependency' ? RESOURCE_DEPENDENCY_VISUAL_GUTTER : 0,
+      };
+      event.currentTarget.setPointerCapture?.(event.pointerId);
+    },
+    [clearScheduledResourceDragPreview, resourcePositionById, sortMode],
+  );
 
-  function handleResourceCardPointerEnd(
-    event: ReactPointerEvent<HTMLButtonElement>,
-    cancelled: boolean,
-  ) {
-    const drag = resourceCardDragRef.current;
-    if (!drag || drag.pointerId !== event.pointerId) {
-      return;
-    }
-    clearScheduledResourceDragPreview();
-    resourceCardDragRef.current = null;
-    if (event.currentTarget.hasPointerCapture?.(event.pointerId)) {
-      event.currentTarget.releasePointerCapture?.(event.pointerId);
-    }
-    if (drag.moved && !cancelled) {
-      suppressResourceClickRef.current = drag.resourceId;
-      commitResourcePosition(
-        drag.resourceId,
-        drag.section,
-        Math.max(0, drag.startX + event.clientX - drag.startClientX),
-        Math.max(0, drag.startY + event.clientY - drag.startClientY),
-      );
-    }
-    setDraggedResourceId(null);
-    setResourceDragPreview(null);
-  }
+  const handleResourceCardPointerMove = useCallback(
+    (event: ReactPointerEvent<HTMLButtonElement>) => {
+      const drag = resourceCardDragRef.current;
+      if (!drag || drag.pointerId !== event.pointerId) {
+        return;
+      }
+      const deltaX = event.clientX - drag.startClientX;
+      const deltaY = event.clientY - drag.startClientY;
+      if (
+        !drag.moved &&
+        Math.hypot(deltaX, deltaY) < RESOURCE_CANVAS_DRAG_THRESHOLD
+      ) {
+        return;
+      }
+      if (!drag.moved) {
+        drag.moved = true;
+        setDraggedResourceId(drag.resourceId);
+      }
+      scheduleResourceDragPreview({
+        resourceId: drag.resourceId,
+        x: Math.max(0, drag.startX + deltaX),
+        y: Math.max(0, drag.startY + deltaY),
+      });
+      event.preventDefault();
+    },
+    [scheduleResourceDragPreview],
+  );
+
+  const handleResourceCardPointerEnd = useCallback(
+    (event: ReactPointerEvent<HTMLButtonElement>, cancelled: boolean) => {
+      const drag = resourceCardDragRef.current;
+      if (!drag || drag.pointerId !== event.pointerId) {
+        return;
+      }
+      clearScheduledResourceDragPreview();
+      const finalPreview = {
+        resourceId: drag.resourceId,
+        x: cancelled
+          ? drag.startX
+          : Math.max(0, drag.startX + event.clientX - drag.startClientX),
+        y: cancelled
+          ? drag.startY
+          : Math.max(0, drag.startY + event.clientY - drag.startClientY),
+      };
+      applyResourceDragPreview(finalPreview);
+      resourceCardDragRef.current = null;
+      if (event.currentTarget.hasPointerCapture?.(event.pointerId)) {
+        event.currentTarget.releasePointerCapture?.(event.pointerId);
+      }
+      if (drag.moved && !cancelled) {
+        suppressResourceClickRef.current = drag.resourceId;
+        commitResourcePosition(
+          drag.resourceId,
+          drag.section,
+          finalPreview.x,
+          finalPreview.y,
+        );
+        const overlay = resourceDependencyOverlayRef.current;
+        window.requestAnimationFrame(() => overlay?.clearDragPreview());
+      } else {
+        resourceDependencyOverlayRef.current?.clearDragPreview();
+      }
+      setDraggedResourceId(null);
+    },
+    [
+      applyResourceDragPreview,
+      clearScheduledResourceDragPreview,
+      commitResourcePosition,
+    ],
+  );
+  const handleResourceCardPointerUp = useCallback(
+    (event: ReactPointerEvent<HTMLButtonElement>) =>
+      handleResourceCardPointerEnd(event, false),
+    [handleResourceCardPointerEnd],
+  );
+  const handleResourceCardPointerCancel = useCallback(
+    (event: ReactPointerEvent<HTMLButtonElement>) =>
+      handleResourceCardPointerEnd(event, true),
+    [handleResourceCardPointerEnd],
+  );
 
   function handleResourceDialogPointerDown(
     event: ReactPointerEvent<HTMLElement>,
@@ -1236,10 +1328,10 @@ export default function ProjectDevelopmentView({
                 <div className="game-resource-canvas-content">
                   {sortMode === 'dependency' ? (
                     <ResourceDependencyOverlay
+                      ref={resourceDependencyOverlayRef}
                       key={`${projectPath}:${manifest.projectId}`}
                       graph={resourceGraph}
                       positions={resourceLayout.positions}
-                      dragPreview={resourceDragPreview}
                       visibleResourceIds={visibleResourceIds}
                       selectedResourceId={selectedResourceId}
                     />
@@ -1250,36 +1342,13 @@ export default function ProjectDevelopmentView({
                     const baseExtent = resourceBaseExtentByCategory.get(
                       category,
                     ) ?? { width: 0, height: 0 };
-                    const dragPosition = resourceDragPreview
-                      ? resourcePositionById.get(
-                          resourceDragPreview.resourceId,
-                        )
-                      : undefined;
-                    const previewInCategory =
-                      dragPosition?.section === category
-                        ? resourceDragPreview
-                        : null;
                     const extent = {
                       width:
-                        Math.max(
-                          baseExtent.width,
-                          previewInCategory
-                            ? previewInCategory.x +
-                                RESOURCE_CANVAS_CARD_WIDTH +
-                                RESOURCE_CANVAS_COLUMN_GAP
-                            : 0,
-                        ) +
+                        baseExtent.width +
                         (sortMode === 'dependency'
                           ? RESOURCE_DEPENDENCY_VISUAL_GUTTER
                           : 0),
-                      height: Math.max(
-                        baseExtent.height,
-                        previewInCategory
-                          ? previewInCategory.y +
-                            RESOURCE_CANVAS_CARD_HEIGHT +
-                            RESOURCE_CANVAS_ROW_GAP
-                          : 0,
-                      ),
+                      height: baseExtent.height,
                     };
                     const Icon = categoryIcons[category];
                     return (
@@ -1311,10 +1380,6 @@ export default function ProjectDevelopmentView({
                               if (!position) {
                                 return null;
                               }
-                              const preview =
-                                resourceDragPreview?.resourceId === resource.id
-                                  ? resourceDragPreview
-                                  : null;
                               const upstream =
                                 sortMode === 'dependency' &&
                                 selectedResourceNeighbors.upstreamResourceIds.has(
@@ -1340,30 +1405,14 @@ export default function ProjectDevelopmentView({
                                   selected={resource.id === selectedResourceId}
                                   dragging={resource.id === draggedResourceId}
                                   relationState={relationState}
-                                  x={preview?.x ?? position.x}
-                                  y={preview?.y ?? position.y}
-                                  onSelect={() => {
-                                    if (
-                                      suppressResourceClickRef.current ===
-                                      resource.id
-                                    ) {
-                                      suppressResourceClickRef.current = null;
-                                      return;
-                                    }
-                                    setSelectedResourceId(resource.id);
-                                  }}
-                                  onPointerDown={(event) =>
-                                    handleResourceCardPointerDown(
-                                      event,
-                                      resource,
-                                    )
-                                  }
+                                  x={position.x}
+                                  y={position.y}
+                                  onSelect={handleResourceSelect}
+                                  onPointerDown={handleResourceCardPointerDown}
                                   onPointerMove={handleResourceCardPointerMove}
-                                  onPointerUp={(event) =>
-                                    handleResourceCardPointerEnd(event, false)
-                                  }
-                                  onPointerCancel={(event) =>
-                                    handleResourceCardPointerEnd(event, true)
+                                  onPointerUp={handleResourceCardPointerUp}
+                                  onPointerCancel={
+                                    handleResourceCardPointerCancel
                                   }
                                 />
                               );
diff --git a/apps/ai-game-creator-shell/src/view/project-development/resourceDependencyGraphModel.ts b/apps/ai-game-creator-shell/src/view/project-development/resourceDependencyGraphModel.ts
index ff46e11c5..57d56662f 100644
--- a/apps/ai-game-creator-shell/src/view/project-development/resourceDependencyGraphModel.ts
+++ b/apps/ai-game-creator-shell/src/view/project-development/resourceDependencyGraphModel.ts
@@ -33,6 +33,7 @@ export type ProjectResourceConnectionIndexDto = {
 export type ProjectResourceProducerAssignment = {
   resourceId: string;
   taskId: string;
+  dependencyDepth: number;
 };
 
 export type ProjectResourceGraphReadModel = {
@@ -62,6 +63,7 @@ export type ProjectResourceGraph = {
   taskFlowById: ReadonlyMap<string, ProjectResourceTaskFlow>;
   connectionIndex: ReadonlyMap<string, ProjectResourceConnectionIndex>;
   producerTaskIdByResourceId: ReadonlyMap<string, string>;
+  dependencyDepthByResourceId: ReadonlyMap<string, number>;
   unresolvedReferenceResourceIds: string[];
   cyclicResourceIds: ReadonlySet<string>;
   cyclicTaskIds: ReadonlySet<string>;
@@ -76,6 +78,7 @@ export type ProjectResourceGraphNeighbors = {
 
 const emptyStringSet: ReadonlySet<string> = new Set<string>();
 const emptyStringMap: ReadonlyMap<string, string> = new Map<string, string>();
+const emptyNumberMap: ReadonlyMap<string, number> = new Map<string, number>();
 const emptyConnectionMap: ReadonlyMap<string, ProjectResourceConnectionIndex> =
   new Map<string, ProjectResourceConnectionIndex>();
 const emptyTaskFlowMap: ReadonlyMap<string, ProjectResourceTaskFlow> = new Map<
@@ -102,6 +105,7 @@ export const EMPTY_PROJECT_RESOURCE_GRAPH: ProjectResourceGraph = {
   taskFlowById: emptyTaskFlowMap,
   connectionIndex: emptyConnectionMap,
   producerTaskIdByResourceId: emptyStringMap,
+  dependencyDepthByResourceId: emptyNumberMap,
   unresolvedReferenceResourceIds: [],
   cyclicResourceIds: emptyStringSet,
   cyclicTaskIds: emptyStringSet,
@@ -174,13 +178,23 @@ export function normalizeProjectResourceGraph(
       ),
     });
   }
-  const producerTaskIdByResourceId = new Map(
-    readModel.producerAssignments.flatMap((assignment) =>
-      resourceIds.has(assignment.resourceId) && assignment.taskId
-        ? [[assignment.resourceId, assignment.taskId] as const]
-        : [],
-    ),
-  );
+  const producerTaskIdByResourceId = new Map<string, string>();
+  const dependencyDepthByResourceId = new Map<string, number>();
+  for (const assignment of readModel.producerAssignments) {
+    if (!resourceIds.has(assignment.resourceId) || !assignment.taskId) {
+      continue;
+    }
+    producerTaskIdByResourceId.set(assignment.resourceId, assignment.taskId);
+    if (
+      Number.isSafeInteger(assignment.dependencyDepth) &&
+      assignment.dependencyDepth >= 0
+    ) {
+      dependencyDepthByResourceId.set(
+        assignment.resourceId,
+        assignment.dependencyDepth,
+      );
+    }
+  }
 
   return {
     resourceIds,
@@ -190,6 +204,7 @@ export function normalizeProjectResourceGraph(
     taskFlowById: new Map(taskFlows.map((flow) => [flow.id, flow])),
     connectionIndex,
     producerTaskIdByResourceId,
+    dependencyDepthByResourceId,
     unresolvedReferenceResourceIds: uniqueSorted(
       readModel.unresolvedReferenceResourceIds,
     ),
diff --git a/apps/ai-game-creator-shell/src/view/project-development/useProjectResourceCanvasLayout.ts b/apps/ai-game-creator-shell/src/view/project-development/useProjectResourceCanvasLayout.ts
index 745ca2c37..746ee88b8 100644
--- a/apps/ai-game-creator-shell/src/view/project-development/useProjectResourceCanvasLayout.ts
+++ b/apps/ai-game-creator-shell/src/view/project-development/useProjectResourceCanvasLayout.ts
@@ -81,16 +81,58 @@ function layoutMatchesScope(
   return layout.projectId === scope.projectId && layout.mode === scope.mode;
 }
 
+function positionsEqual(
+  left: ProjectResourceCanvasLayout['positions'],
+  right: ProjectResourceCanvasLayout['positions'],
+) {
+  return (
+    left.length === right.length &&
+    left.every((position, index) => {
+      const other = right[index];
+      return (
+        other?.resourceId === position.resourceId &&
+        other.section === position.section &&
+        other.x === position.x &&
+        other.y === position.y &&
+        other.manuallyPlaced === position.manuallyPlaced
+      );
+    })
+  );
+}
+
+function reconcileLayout(
+  source: ProjectResourceCanvasLayout,
+  resources: ResourceCanvasItem[],
+  rederiveAutomaticPositions: boolean,
+) {
+  if (!rederiveAutomaticPositions) {
+    return reconcileResourceCanvasLayout(source, resources);
+  }
+  const manualSource = {
+    ...source,
+    positions: source.positions.filter((position) => position.manuallyPlaced),
+  };
+  const reconciled = reconcileResourceCanvasLayout(manualSource, resources);
+  return {
+    layout: reconciled.layout,
+    changed: !positionsEqual(source.positions, reconciled.layout.positions),
+  };
+}
+
 export function useProjectResourceCanvasLayout({
   projectPath,
   projectId,
   mode,
   resources,
+  initializationReady = true,
+  rederiveAutomaticPositions = false,
 }: {
   projectPath: string;
   projectId: string;
   mode: ProjectResourceCanvasLayoutMode;
   resources: ResourceCanvasItem[];
+  initializationReady?: boolean;
+  rederiveAutomaticPositions?: boolean;
 }) {
   const scopeKey = createScopeKey(projectPath, projectId, mode);
   const resourceSignature = useMemo(
@@ -98,13 +140,18 @@ export function useProjectResourceCanvasLayout({
     [resources],
   );
   const fallback = useMemo(
-    () =>
-      reconcileResourceCanvasLayout(
-        createEmptyResourceCanvasLayout(projectId, mode),
-        resources,
-      ).layout,
-    [mode, projectId, resources],
-  );
+    () => {
+      const empty = createEmptyResourceCanvasLayout(projectId, mode);
+      return initializationReady
+        ? reconcileLayout(empty, resources, rederiveAutomaticPositions).layout
+        : empty;
+    }, [
+      initializationReady,
+      mode,
+      projectId,
+      rederiveAutomaticPositions,
+      resources,
+    ]);
   const [layout, setLayout] = useState<ProjectResourceCanvasLayout>(fallback);
   const [notice, setNotice] = useState<LayoutNotice>('');
   const [saving, setSaving] = useState(false);
@@ -151,9 +198,10 @@ export function useProjectResourceCanvasLayout({
       if (scope.epoch !== scopeEpoch) {
         return;
       }
-      let next = reconcileResourceCanvasLayout(
+      let next = reconcileLayout(
         persistedLayoutRef.current,
         resourcesRef.current,
+        rederiveAutomaticPositions,
       ).layout;
       for (const intent of writeQueueRef.current) {
         if (intent.scopeEpoch === scopeEpoch && intent.kind === 'manual') {
@@ -168,7 +216,7 @@ export function useProjectResourceCanvasLayout({
       }
       applyLayout(next);
     },
-    [applyLayout],
+    [applyLayout, rederiveAutomaticPositions],
   );
 
   enqueueResourceSyncRef.current = (scopeEpoch, conflictRetries = 0) => {
@@ -229,9 +277,10 @@ export function useProjectResourceCanvasLayout({
       return;
     }
 
-    const reconciled = reconcileResourceCanvasLayout(
+    const reconciled = reconcileLayout(
       persistedLayoutRef.current,
       resourcesRef.current,
+      rederiveAutomaticPositions,
     );
     if (intent.kind === 'resources' && !reconciled.changed) {
       removeWriteIntent(intent);
@@ -330,7 +379,11 @@ export function useProjectResourceCanvasLayout({
             setNotice('布局已保存');
           }
           if (
-            reconcileResourceCanvasLayout(result.layout, resourcesRef.current)
+            reconcileLayout(
+              result.layout,
+              resourcesRef.current,
+              rederiveAutomaticPositions,
+            )
               .changed
           ) {
             enqueueResourceSyncRef.current(currentScope.epoch);
@@ -346,9 +399,10 @@ export function useProjectResourceCanvasLayout({
               queued.scopeEpoch !== currentScope.epoch ||
               queued.kind !== 'manual',
           );
-          const needsResourceSync = reconcileResourceCanvasLayout(
+          const needsResourceSync = reconcileLayout(
             result.layout,
             resourcesRef.current,
+            rederiveAutomaticPositions,
           ).changed;
           const nextRetry =
             intent.kind === 'resources' ? intent.conflictRetries + 1 : 0;
@@ -435,9 +489,18 @@ export function useProjectResourceCanvasLayout({
     writeQueueRef.current = [];
     activeWriteIntentRef.current = null;
     redragRequiredScopeEpochRef.current = null;
-    const initialFallback = reconcileResourceCanvasLayout(
-      createEmptyResourceCanvasLayout(projectId, mode),
+    const emptyLayout = createEmptyResourceCanvasLayout(projectId, mode);
+    if (!initializationReady) {
+      persistedLayoutRef.current = emptyLayout;
+      applyLayout(emptyLayout);
+      setNotice('');
+      setSaving(false);
+      return undefined;
+    }
+    const initialFallback = reconcileLayout(
+      emptyLayout,
       resourcesRef.current,
+      rederiveAutomaticPositions,
     ).layout;
     persistedLayoutRef.current = initialFallback;
     applyLayout(initialFallback);
@@ -469,7 +532,11 @@ export function useProjectResourceCanvasLayout({
         persistedLayoutRef.current = loaded;
         initializedScopeEpochRef.current = epoch;
         if (
-          reconcileResourceCanvasLayout(loaded, resourcesRef.current).changed
+          reconcileLayout(
+            loaded,
+            resourcesRef.current,
+            rederiveAutomaticPositions,
+          ).changed
         ) {
           enqueueResourceSyncRef.current(epoch);
         }
@@ -491,10 +558,12 @@ export function useProjectResourceCanvasLayout({
     };
   }, [
     applyLayout,
+    initializationReady,
     mode,
     projectId,
     projectPath,
     rebuildOptimisticLayout,
+    rederiveAutomaticPositions,
     scopeKey,
   ]);
 
@@ -502,25 +571,34 @@ export function useProjectResourceCanvasLayout({
     const scope = scopeRef.current;
     if (
       scope.key !== scopeKey ||
+      !initializationReady ||
       initializedScopeEpochRef.current !== scope.epoch
     ) {
       return;
     }
-    const reconciledCurrent = reconcileResourceCanvasLayout(
+    const reconciledCurrent = reconcileLayout(
       layoutRef.current,
       resourcesRef.current,
+      rederiveAutomaticPositions,
     );
     applyLayout(reconciledCurrent.layout);
     if (
       window.__TAURI__?.core?.invoke &&
-      reconcileResourceCanvasLayout(
+      reconcileLayout(
         persistedLayoutRef.current,
         resourcesRef.current,
+        rederiveAutomaticPositions,
       ).changed
     ) {
       enqueueResourceSyncRef.current(scope.epoch);
     }
-  }, [applyLayout, resourceSignature, scopeKey]);
+  }, [
+    applyLayout,
+    initializationReady,
+    rederiveAutomaticPositions,
+    resourceSignature,
+    scopeKey,
+  ]);
 
   useEffect(() => {
     if (!notice) {
@@ -544,7 +622,11 @@ export function useProjectResourceCanvasLayout({
       y: number,
     ) => {
       const scope = scopeRef.current;
-      if (scope.key !== scopeKey) {
+      if (
+        scope.key !== scopeKey ||
+        !initializationReady ||
+        initializedScopeEpochRef.current !== scope.epoch
+      ) {
         return;
       }
       const queuedIntent = writeQueueRef.current.find(
@@ -580,10 +662,11 @@ export function useProjectResourceCanvasLayout({
       setSaving(true);
       pumpWritesRef.current();
     },
-    [applyLayout, scopeKey],
+    [applyLayout, initializationReady, scopeKey],
   );
 
   const scopeMatches =
+    initializationReady &&
     scopeRef.current.key === scopeKey &&
     layout.projectId === projectId &&
     layout.mode === mode;
diff --git a/apps/ai-game-creator-shell/tests/ResourceDependencyOverlay.test.ts b/apps/ai-game-creator-shell/tests/ResourceDependencyOverlay.test.ts
index da4df334a..6348de9bf 100644
--- a/apps/ai-game-creator-shell/tests/ResourceDependencyOverlay.test.ts
+++ b/apps/ai-game-creator-shell/tests/ResourceDependencyOverlay.test.ts
@@ -1,5 +1,5 @@
 /** @vitest-environment jsdom */
-import { render, screen, waitFor } from '@testing-library/react';
+import { act, render, screen, waitFor } from '@testing-library/react';
 import React from 'react';
 import { describe, expect, it, vi } from 'vitest';
 
@@ -9,7 +9,10 @@ import {
   type ProjectResourceGraph,
   type ProjectResourceGraphReadModel,
 } from '../src/view/project-development/resourceDependencyGraphModel';
-import { ResourceDependencyOverlay } from '../src/view/project-development/ResourceDependencyOverlay';
+import {
+  ResourceDependencyOverlay,
+  type ResourceDependencyOverlayHandle,
+} from '../src/view/project-development/ResourceDependencyOverlay';
 
 function position(
   resourceId: string,
@@ -103,22 +106,22 @@ function OverlayHarness({
   positions,
   visibleResourceIds,
   selectedResourceId = null,
-  dragPreview = null,
+  overlayRef,
 }: {
   graph: ProjectResourceGraph;
   positions: ProjectResourceCanvasPosition[];
   visibleResourceIds: ReadonlySet<string>;
   selectedResourceId?: string | null;
-  dragPreview?: { resourceId: string; x: number; y: number } | null;
+  overlayRef?: React.Ref<ResourceDependencyOverlayHandle>;
 }) {
   return React.createElement(
     'div',
     null,
     React.createElement('div', { 'data-resource-section-plane': 'art' }),
     React.createElement(ResourceDependencyOverlay, {
+      ref: overlayRef,
       graph,
       positions,
-      dragPreview,
       visibleResourceIds,
       selectedResourceId,
     }),
@@ -130,14 +133,14 @@ function overlayView(
   positions: ProjectResourceCanvasPosition[],
   visibleResourceIds: ReadonlySet<string>,
   selectedResourceId: string | null = null,
-  dragPreview: { resourceId: string; x: number; y: number } | null = null,
+  overlayRef?: React.Ref<ResourceDependencyOverlayHandle>,
 ) {
   return React.createElement(OverlayHarness, {
     graph,
     positions,
     visibleResourceIds,
     selectedResourceId,
-    dragPreview,
+    overlayRef,
   });
 }
 
@@ -181,8 +184,15 @@ describe('ResourceDependencyOverlay', () => {
       position('source:one', 0, 0),
       position('target:one', 240, 0),
     ];
+    const overlayRef = React.createRef<ResourceDependencyOverlayHandle>();
     const view = render(
-      overlayView(graph, positions, new Set(['source:one', 'target:one'])),
+      overlayView(
+        graph,
+        positions,
+        new Set(['source:one', 'target:one']),
+        null,
+        overlayRef,
+      ),
     );
     const overlay = await screen.findByTestId('resource-dependency-overlay');
     const firstPath = await waitFor(() => {
@@ -193,14 +203,12 @@ describe('ResourceDependencyOverlay', () => {
       return path?.getAttribute('d');
     });
 
-    view.rerender(
-      overlayView(
-        graph,
-        positions,
-        new Set(['source:one', 'target:one']),
-        null,
-        { resourceId: 'source:one', x: 80, y: 40 },
-      ),
+    act(() =>
+      overlayRef.current?.updateDragPreview({
+        resourceId: 'source:one',
+        x: 80,
+        y: 40,
+      }),
     );
     await waitFor(() =>
       expect(
@@ -242,7 +250,8 @@ describe('ResourceDependencyOverlay', () => {
         position('target:one', 240, 0),
       ];
       const visible = new Set(['source:one', 'target:one']);
-      const view = render(overlayView(graph, positions, visible));
+      const overlayRef = React.createRef<ResourceDependencyOverlayHandle>();
+      render(overlayView(graph, positions, visible, null, overlayRef));
       const overlay = await screen.findByTestId('resource-dependency-overlay');
       const selector = '[data-edge-kind="asset-reference"]';
       await waitFor(() =>
@@ -251,8 +260,8 @@ describe('ResourceDependencyOverlay', () => {
         ),
       );
 
-      view.rerender(
-        overlayView(graph, positions, visible, null, {
+      act(() =>
+        overlayRef.current?.updateDragPreview({
           resourceId: 'source:one',
           x: 80,
           y: 40,
@@ -375,7 +384,8 @@ describe('ResourceDependencyOverlay', () => {
       position('resource:2049', 440, 0),
     ];
     const visible = new Set(positions.map(({ resourceId }) => resourceId));
-    const view = render(overlayView(graph, positions, visible));
+    const overlayRef = React.createRef<ResourceDependencyOverlayHandle>();
+    render(overlayView(graph, positions, visible, null, overlayRef));
     const overlay = await screen.findByTestId('resource-dependency-overlay');
     await waitFor(() =>
       expect(
@@ -387,8 +397,8 @@ describe('ResourceDependencyOverlay', () => {
       'setAttribute',
     );
     try {
-      view.rerender(
-        overlayView(graph, positions, visible, null, {
+      act(() =>
+        overlayRef.current?.updateDragPreview({
           resourceId: 'resource:2048',
           x: 260,
           y: 32,
@@ -419,23 +429,24 @@ describe('ResourceDependencyOverlay', () => {
       const positions = Array.from(graph.resourceIds).map(
         (resourceId, index) => position(resourceId, index * 200, 0),
       );
+      const overlayRef = React.createRef<ResourceDependencyOverlayHandle>();
       const view = render(
         overlayView(
           graph,
           positions,
           new Set(graph.resourceIds),
+          null,
+          overlayRef,
         ),
       );
 
       expect(observe).toHaveBeenCalledTimes(2);
-      view.rerender(
-        overlayView(
-          graph,
-          positions,
-          new Set(graph.resourceIds),
-          null,
-          { resourceId: 'source:one', x: 32, y: 24 },
-        ),
+      act(() =>
+        overlayRef.current?.updateDragPreview({
+          resourceId: 'source:one',
+          x: 32,
+          y: 24,
+        }),
       );
       expect(observe).toHaveBeenCalledTimes(2);
       view.unmount();
diff --git a/apps/ai-game-creator-shell/tests/appSurface/home.suite.ts b/apps/ai-game-creator-shell/tests/appSurface/home.suite.ts
index 733c41033..96bee78ed 100644
--- a/apps/ai-game-creator-shell/tests/appSurface/home.suite.ts
+++ b/apps/ai-game-creator-shell/tests/appSurface/home.suite.ts
@@ -801,7 +801,9 @@ export function registerHomeProjectCreationTests() {
     expect(screen.getByLabelText('项目总控消息').textContent).toContain(
       '第一行\n第二行\n第三行',
     );
-    expect(screen.getByText('assets/uploads/reference.png')).not.toBeNull();
+    expect(
+      await screen.findByText('assets/uploads/reference.png'),
+    ).not.toBeNull();
     expect(invoke).toHaveBeenCalledWith('init_local_game_project', {
       projectPath: '/tmp/home-created-game',
       projectId: 'local-project-draft',
diff --git a/apps/ai-game-creator-shell/tests/appSurface/project-development.suite.ts b/apps/ai-game-creator-shell/tests/appSurface/project-development.suite.ts
index 7d70a4a2d..5997a0fab 100644
--- a/apps/ai-game-creator-shell/tests/appSurface/project-development.suite.ts
+++ b/apps/ai-game-creator-shell/tests/appSurface/project-development.suite.ts
@@ -56,6 +56,40 @@ import {
   within,
 } from './harness';
 
+function resourceGraphForInputs(args?: Record<string, unknown>) {
+  const resources =
+    (args?.resources as
+      | Array<{ resourceId: string; producerTaskId: string | null }>
+      | undefined) ?? [];
+  return {
+    resourceIds: resources.map(({ resourceId }) => resourceId),
+    referenceEdges: [],
+    taskFlows: [],
+    connectionIndex: resources.map(({ resourceId }) => ({
+      resourceId,
+      upstreamReferenceResourceIds: [],
+      downstreamReferenceResourceIds: [],
+      referenceEdgeIds: [],
+      taskFlowIds: [],
+    })),
+    producerAssignments: resources.flatMap((resource) =>
+      resource.producerTaskId
+        ? [
+            {
+              resourceId: resource.resourceId,
+              taskId: resource.producerTaskId,
+              dependencyDepth: 0,
+            },
+          ]
+        : [],
+    ),
+    unresolvedReferenceResourceIds: [],
+    cyclicResourceIds: [],
+    cyclicTaskIds: [],
+    producerMappingTruncated: false,
+  };
+}
+
 function gameChatRuntimeEvent({
   agentId = 'project-supervisor',
   taskId = agentId,
@@ -869,10 +903,12 @@ export function registerProjectWorkbenchFoundationTests() {
               {
                 resourceId: 'asset:dependency-spec',
                 taskId: 'art-director',
+                dependencyDepth: 0,
               },
               {
                 resourceId: 'asset:dependency-ui',
                 taskId: 'design-foundation',
+                dependencyDepth: 1,
               },
             ],
             unresolvedReferenceResourceIds: [],
@@ -1025,6 +1061,204 @@ export function registerProjectWorkbenchFoundationTests() {
     expect(nextOverlay.querySelector('[data-edge-kind]')).toBeNull();
   });
 
+  it('waits for the scoped resource graph before initializing dependency layout', async () => {
+    const projectId = 'workbench-delayed-resource-graph';
+    const projectPath = '/tmp/workbench-delayed-resource-graph';
+    const manifest = createGameCreationAppManifest(projectId, '延迟依赖图测试');
+    const agentResults = [
+      {
+        agentId: 'design-foundation',
+        runId: 'delayed-graph-run',
+        label: '玩法策划 Agent',
+        title: '延迟依赖图回执',
+        content: '图就绪后再初始化布局',
+        updatedAt: 1,
+      },
+    ];
+    let resolveGraph: (() => void) | null = null;
+    let layoutReads = 0;
+    let layoutRevision = 0;
+    const invoke = vi.fn(
+      async (command: string, args?: Record<string, unknown>) => {
+        if (command === 'read_local_project_resource_graph') {
+          return await new Promise((resolve) => {
+            resolveGraph = () => resolve(resourceGraphForInputs(args));
+          });
+        }
+        if (command === 'read_local_project_resource_canvas_layout') {
+          layoutReads += 1;
+          return {
+            schemaVersion: 'game-creator-resource-layout.v1',
+            projectId,
+            mode: 'dependency',
+            revision: layoutRevision,
+            positions: [],
+            updatedAt: 0,
+          };
+        }
+        if (command === 'update_local_project_resource_canvas_layout') {
+          layoutRevision += 1;
+          return {
+            status: 'updated',
+            layout: {
+              schemaVersion: 'game-creator-resource-layout.v1',
+              projectId,
+              mode: 'dependency',
+              revision: layoutRevision,
+              positions: args?.positions,
+              updatedAt: layoutRevision,
+            },
+          };
+        }
+        throw new Error(`unexpected invoke ${command}`);
+      },
+    );
+    window.__TAURI__ = { core: { invoke } };
+
+    render(
+      React.createElement(ProjectDevelopmentView, {
+        projectName: '延迟依赖图测试',
+        projectPath,
+        manifest,
+        attachments: [],
+        agentResults,
+        supervisor: React.createElement('div', null, '项目总控'),
+      }),
+    );
+
+    await waitFor(() => expect(resolveGraph).not.toBeNull());
+    expect(layoutReads).toBe(0);
+    expect(screen.queryByText('延迟依赖图回执')).toBeNull();
+
+    await act(async () => {
+      resolveGraph?.();
+      await Promise.resolve();
+    });
+    expect(await screen.findByText('延迟依赖图回执')).not.toBeNull();
+    expect(layoutReads).toBe(1);
+  });
+
+  it(
+    'keeps 4096 real resource cards out of React commits during preview frames',
+    async () => {
+      const projectId = 'workbench-resource-drag-performance';
+      const projectPath = '/tmp/workbench-resource-drag-performance';
+      const manifest = createGameCreationAppManifest(
+        projectId,
+        '资源拖动性能测试',
+      );
+      const agentResults = Array.from({ length: 4096 }, (_, index) => ({
+        agentId: 'design-foundation',
+        runId: `performance-run-${index}`,
+        label: `性能 Agent ${index}`,
+        title: `性能资源 ${index}`,
+        content: `性能正文 ${index}`,
+        updatedAt: index,
+      }));
+      let layoutRevision = 0;
+      const invoke = vi.fn(
+        async (command: string, args?: Record<string, unknown>) => {
+          if (command === 'read_local_project_resource_graph') {
+            return resourceGraphForInputs(args);
+          }
+          if (command === 'read_local_project_resource_canvas_layout') {
+            return {
+              schemaVersion: 'game-creator-resource-layout.v1',
+              projectId,
+              mode: 'dependency',
+              revision: layoutRevision,
+              positions: [],
+              updatedAt: 0,
+            };
+          }
+          if (command === 'update_local_project_resource_canvas_layout') {
+            layoutRevision += 1;
+            return {
+              status: 'updated',
+              layout: {
+                schemaVersion: 'game-creator-resource-layout.v1',
+                projectId,
+                mode: 'dependency',
+                revision: layoutRevision,
+                positions: args?.positions,
+                updatedAt: layoutRevision,
+              },
+            };
+          }
+          throw new Error(`unexpected invoke ${command}`);
+        },
+      );
+      window.__TAURI__ = { core: { invoke } };
+      const commits: string[] = [];
+
+      render(
+        React.createElement(
+          React.Profiler,
+          {
+            id: 'resource-workbench',
+            onRender: () => commits.push('commit'),
+          },
+          React.createElement(ProjectDevelopmentView, {
+            projectName: '资源拖动性能测试',
+            projectPath,
+            manifest,
+            attachments: [],
+            agentResults,
+            supervisor: React.createElement('div', null, '项目总控'),
+          }),
+        ),
+      );
+
+      const target = (await screen.findByText('性能资源 2048')).closest(
+        'button',
+      );
+      expect(target).not.toBeNull();
+      expect(document.querySelectorAll('.game-resource-card')).toHaveLength(
+        4096,
+      );
+      commits.length = 0;
+      let previewFrame: FrameRequestCallback | null = null;
+      const requestAnimationFrame = vi
+        .spyOn(window, 'requestAnimationFrame')
+        .mockImplementation((callback) => {
+          previewFrame = callback;
+          return 77;
+        });
+      const cancelAnimationFrame = vi
+        .spyOn(window, 'cancelAnimationFrame')
+        .mockImplementation(() => undefined);
+      try {
+        fireEvent.pointerDown(target!, {
+          pointerId: 88,
+          button: 0,
+          clientX: 20,
+          clientY: 30,
+        });
+        for (let index = 0; index < 100; index += 1) {
+          fireEvent.pointerMove(target!, {
+            pointerId: 88,
+            clientX: 40 + index,
+            clientY: 60 + index,
+          });
+        }
+        act(() => previewFrame?.(16));
+
+        expect(commits).toHaveLength(1);
+        expect(target?.getAttribute('style')).toContain('--resource-x: 119px');
+        expect(requestAnimationFrame).toHaveBeenCalledTimes(1);
+      } finally {
+        fireEvent.pointerCancel(target!, {
+          pointerId: 88,
+          clientX: 139,
+          clientY: 159,
+        });
+        requestAnimationFrame.mockRestore();
+        cancelAnimationFrame.mockRestore();
+      }
+    },
+    15_000,
+  );
+
   it('persists a resource position with CAS and restores it after remount', async () => {
     const projectId = 'workbench-layout-persistence';
     const projectPath = '/tmp/workbench-layout-persistence';
@@ -1058,6 +1292,9 @@ export function registerProjectWorkbenchFoundationTests() {
     };
     const invoke = vi.fn(
       async (command: string, args?: Record<string, unknown>) => {
+        if (command === 'read_local_project_resource_graph') {
+          return resourceGraphForInputs(args);
+        }
         if (command === 'read_local_project_resource_canvas_layout') {
           return structuredClone(persistedLayout);
         }
@@ -1097,7 +1334,7 @@ export function registerProjectWorkbenchFoundationTests() {
     }
 
     renderWorkbench();
-    const card = screen.getByText('布局持久化回执').closest('button');
+    const card = (await screen.findByText('布局持久化回执')).closest('button');
     expect(card).not.toBeNull();
     await waitFor(() => {
       expect(card?.getAttribute('style')).toContain('--resource-x: 12px');
@@ -1142,7 +1379,9 @@ export function registerProjectWorkbenchFoundationTests() {
 
     cleanup();
     renderWorkbench();
-    const restoredCard = screen.getByText('布局持久化回执').closest('button');
+    const restoredCard = (
+      await screen.findByText('布局持久化回执')
+    ).closest('button');
     await waitFor(() => {
       expect(restoredCard?.getAttribute('style')).toContain(
         '--resource-x: 92px',
@@ -1174,7 +1413,11 @@ export function registerProjectWorkbenchFoundationTests() {
       ],
       updatedAt: 400,
     };
-    const invoke = vi.fn(async (command: string) => {
+    const invoke = vi.fn(
+      async (command: string, args?: Record<string, unknown>) => {
+      if (command === 'read_local_project_resource_graph') {
+        return resourceGraphForInputs(args);
+      }
       if (command === 'read_local_project_resource_canvas_layout') {
         return {
           ...structuredClone(latestLayout),
@@ -1192,7 +1435,8 @@ export function registerProjectWorkbenchFoundationTests() {
         return { status: 'conflict', layout: structuredClone(latestLayout) };
       }
       throw new Error(`unexpected invoke ${command}`);
-    });
+      },
+    );
     window.__TAURI__ = { core: { invoke } };
 
     render(
@@ -1214,7 +1458,7 @@ export function registerProjectWorkbenchFoundationTests() {
         supervisor: React.createElement('div', null, '项目总控'),
       }),
     );
-    const card = screen.getByText('布局冲突回执').closest('button');
+    const card = (await screen.findByText('布局冲突回执')).closest('button');
     await waitFor(() => {
       expect(card?.getAttribute('style')).toContain('--resource-x: 20px');
     });
@@ -1280,7 +1524,11 @@ export function registerProjectWorkbenchFoundationTests() {
         }) => void)
       | null = null;
     let updateCalls = 0;
-    const invoke = vi.fn(async (command: string) => {
+    const invoke = vi.fn(
+      async (command: string, args?: Record<string, unknown>) => {
+      if (command === 'read_local_project_resource_graph') {
+        return resourceGraphForInputs(args);
+      }
       if (command === 'read_local_project_resource_canvas_layout') {
         return {
           ...structuredClone(latestLayout),
@@ -1295,7 +1543,8 @@ export function registerProjectWorkbenchFoundationTests() {
         });
       }
       throw new Error(`unexpected invoke ${command}`);
-    });
+      },
+    );
     window.__TAURI__ = { core: { invoke } };
 
     render(
@@ -1317,7 +1566,7 @@ export function registerProjectWorkbenchFoundationTests() {
         supervisor: React.createElement('div', null, '项目总控'),
       }),
     );
-    const card = screen.getByText('排队冲突回执').closest('button');
+    const card = (await screen.findByText('排队冲突回执')).closest('button');
     await waitFor(() => {
       expect(card?.getAttribute('style')).toContain('--resource-x: 20px');
     });
@@ -1391,6 +1640,9 @@ export function registerProjectWorkbenchFoundationTests() {
     }> = [];
     const invoke = vi.fn(
       async (command: string, args?: Record<string, unknown>) => {
+        if (command === 'read_local_project_resource_graph') {
+          return resourceGraphForInputs(args);
+        }
         const mode = args?.mode as 'dependency' | 'type';
         if (command === 'read_local_project_resource_canvas_layout') {
           return {
@@ -1464,7 +1716,11 @@ export function registerProjectWorkbenchFoundationTests() {
   it('keeps newly reconciled resources visible when their automatic layout save fails', async () => {
     const projectId = 'workbench-layout-save-failure';
     const manifest = createGameCreationAppManifest(projectId, '布局失败测试');
-    const invoke = vi.fn(async (command: string) => {
+    const invoke = vi.fn(
+      async (command: string, args?: Record<string, unknown>) => {
+      if (command === 'read_local_project_resource_graph') {
+        return resourceGraphForInputs(args);
+      }
       if (command === 'read_local_project_resource_canvas_layout') {
         return {
           schemaVersion: 'game-creator-resource-layout.v1',
@@ -1479,7 +1735,8 @@ export function registerProjectWorkbenchFoundationTests() {
         throw new Error('disk full');
       }
       throw new Error(`unexpected invoke ${command}`);
-    });
+      },
+    );
     window.__TAURI__ = { core: { invoke } };
 
     render(
diff --git a/apps/ai-game-creator-shell/tests/resourceDependencyGraphModel.test.ts b/apps/ai-game-creator-shell/tests/resourceDependencyGraphModel.test.ts
index 0566384ae..0ed293914 100644
--- a/apps/ai-game-creator-shell/tests/resourceDependencyGraphModel.test.ts
+++ b/apps/ai-game-creator-shell/tests/resourceDependencyGraphModel.test.ts
@@ -132,9 +132,21 @@ describe('resource dependency graph model', () => {
       readModel({
         resourceIds: ['asset:spec', 'asset:ui'],
         producerAssignments: [
-          { resourceId: 'asset:spec', taskId: 'art-director' },
-          { resourceId: 'asset:ui', taskId: 'design-foundation' },
-          { resourceId: 'asset:deleted', taskId: 'task-1' },
+          {
+            resourceId: 'asset:spec',
+            taskId: 'art-director',
+            dependencyDepth: 0,
+          },
+          {
+            resourceId: 'asset:ui',
+            taskId: 'design-foundation',
+            dependencyDepth: 1,
+          },
+          {
+            resourceId: 'asset:deleted',
+            taskId: 'task-1',
+            dependencyDepth: 99,
+          },
         ],
         producerMappingTruncated: true,
       }),
@@ -146,6 +158,12 @@ describe('resource dependency graph model', () => {
         ['asset:ui', 'design-foundation'],
       ]),
     );
+    expect(graph.dependencyDepthByResourceId).toEqual(
+      new Map([
+        ['asset:spec', 0],
+        ['asset:ui', 1],
+      ]),
+    );
     expect(graph.producerMappingTruncated).toBe(true);
     expect(projectResourceGraphNeighbors(graph, 'asset:deleted')).toEqual({
       upstreamResourceIds: new Set(),
diff --git a/apps/ai-game-creator-shell/tests/useProjectResourceCanvasLayout.test.ts b/apps/ai-game-creator-shell/tests/useProjectResourceCanvasLayout.test.ts
index d07892f34..ac8add1d8 100644
--- a/apps/ai-game-creator-shell/tests/useProjectResourceCanvasLayout.test.ts
+++ b/apps/ai-game-creator-shell/tests/useProjectResourceCanvasLayout.test.ts
@@ -58,6 +58,17 @@ function position(
   };
 }
 
+function automaticPosition(
+  resourceId: string,
+  x: number,
+  y: number,
+): ProjectResourceCanvasPosition {
+  return {
+    ...position(resourceId, x, y),
+    manuallyPlaced: false,
+  };
+}
+
 afterEach(() => {
   cleanup();
   window.__TAURI__ = undefined;
@@ -72,6 +83,117 @@ describe('useProjectResourceCanvasLayout', () => {
     );
   });
 
+  it('waits for dependency graph initialization before reading or writing layout', async () => {
+    const updates: ProjectResourceCanvasPosition[][] = [];
+    const invoke = vi.fn(
+      async (command: string, args?: Record<string, unknown>) => {
+        if (command === 'read_local_project_resource_canvas_layout') {
+          return persistedLayout('dependency', 0, []);
+        }
+        if (command === 'update_local_project_resource_canvas_layout') {
+          const positions = structuredClone(
+            args?.positions as ProjectResourceCanvasPosition[],
+          );
+          updates.push(positions);
+          return {
+            status: 'updated',
+            layout: persistedLayout('dependency', 1, positions),
+          };
+        }
+        throw new Error(`unexpected invoke ${command}`);
+      },
+    );
+    window.__TAURI__ = { core: { invoke } };
+    const shallowResource = resource('resource-a');
+    const deepResource = { ...shallowResource, dependencyDepth: 2 };
+    const { result, rerender } = renderHook(
+      ({ initializationReady, resources }) =>
+        useProjectResourceCanvasLayout({
+          projectPath,
+          projectId,
+          mode: 'dependency',
+          resources,
+          initializationReady,
+          rederiveAutomaticPositions: true,
+        }),
+      {
+        initialProps: {
+          initializationReady: false,
+          resources: [shallowResource],
+        },
+      },
+    );
+
+    expect(invoke).not.toHaveBeenCalled();
+    expect(result.current.layout.positions).toEqual([]);
+
+    rerender({ initializationReady: true, resources: [deepResource] });
+    await waitFor(() => expect(updates).toHaveLength(1));
+    expect(result.current.layout.positions[0]).toMatchObject({
+      resourceId: 'resource-a',
+      x: 392,
+      manuallyPlaced: false,
+    });
+    expect(invoke.mock.calls[0]?.[0]).toBe(
+      'read_local_project_resource_canvas_layout',
+    );
+  });
+
+  it('rederives automatic dependency positions while preserving manual positions', async () => {
+    const resourceA = { ...resource('resource-a'), dependencyDepth: 2 };
+    const resourceB = resource('resource-b');
+    const updates: ProjectResourceCanvasPosition[][] = [];
+    const invoke = vi.fn(
+      async (command: string, args?: Record<string, unknown>) => {
+        if (command === 'read_local_project_resource_canvas_layout') {
+          return persistedLayout('dependency', 4, [
+            automaticPosition('resource-a', 0, 0),
+            position('resource-b', 600, 40),
+          ]);
+        }
+        if (command === 'update_local_project_resource_canvas_layout') {
+          const positions = structuredClone(
+            args?.positions as ProjectResourceCanvasPosition[],
+          );
+          updates.push(positions);
+          return {
+            status: 'updated',
+            layout: persistedLayout('dependency', 5, positions),
+          };
+        }
+        throw new Error(`unexpected invoke ${command}`);
+      },
+    );
+    window.__TAURI__ = { core: { invoke } };
+
+    const { result } = renderHook(() =>
+      useProjectResourceCanvasLayout({
+        projectPath,
+        projectId,
+        mode: 'dependency',
+        resources: [resourceA, resourceB],
+        rederiveAutomaticPositions: true,
+      }),
+    );
+
+    await waitFor(() => expect(updates).toHaveLength(1));
+    expect(result.current.layout.positions).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          resourceId: 'resource-a',
+          x: 392,
+          manuallyPlaced: false,
+        }),
+        expect.objectContaining({
+          resourceId: 'resource-b',
+          x: 600,
+          y: 40,
+          manuallyPlaced: true,
+        }),
+      ]),
+    );
+  });
+
   it('rejects an unsafe revision from the initial IPC read without writing', async () => {
     const resourceA = resource('resource-a');
     const invoke = vi.fn(async (command: string) => {
diff --git a/docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md b/docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md
index ef4fa28e4..2ca695d2a 100644
--- a/docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md
+++ b/docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md
@@ -1,6 +1,6 @@
 # AI 游戏创作项目开发工作台 PRD
 
-更新时间：`2026-07-31`
+更新时间：`2026-08-03`
 
 ## 1. 产品定位
 
@@ -153,7 +153,7 @@ P0 中 `approvalMode` 只能有效写入 `strict`；其它值只能作为不可
 
 ### 5.2 资源画布布局（P1）
 
-实现状态（2026-07-31）：本节布局合同已在独立客户端落地，dependency / type 双模式通过项目内 CAS sidecar 独立持久化；dependency 模式由 Tauri Rust 只读构建关系拓扑、前端 SVG 派生几何，图结构和线段均不写入布局 sidecar。资源替换、缩放 / 平移等其余 P1 能力仍按本文非目标保持未实现。
+实现状态（2026-08-03）：本节布局合同已在独立客户端落地，dependency / type 双模式通过项目内 CAS sidecar 独立持久化；dependency 模式由 Tauri Rust 只读构建关系拓扑与确定性依赖深度、前端 SVG 派生几何，图结构和线段均不写入布局 sidecar。依赖图加载完成前设布局初始化屏障，避免以临时 `dependencyDepth=0` 生成并持久化错误坐标。资源替换、缩放 / 平移等其余 P1 能力仍按本文非目标保持未实现。
 
 ```ts
 type ProjectResourceCanvasLayout = {
@@ -237,10 +237,10 @@ type UpdateProjectResourceCanvasLayoutResult =
 - 资源卡改用 Pointer Events 驱动二维拖动；超过统一移动阈值后才进入拖动态，普通点击仍打开唯一资源详情浮层，`pointercancel` 恢复拖动前位置。
 - 资源只能在原 `section` 内拖动。不同 section 之间既不能通过指针拖入，也不能通过持久 payload 改变当前资源的前端分类事实。
 - dependency 默认布局按 `dependencyDepth` 形成横向层级，同层资源纵向寻找第一个不重叠位置；type 默认布局固定按“资源子类型 -> 媒体类型 -> 名称 -> 资源 ID”稳定排序，在分区内从左到右、从上到下寻找第一个空位。布局模型的 `subtype` 必填：manifest 资产使用 `asset.kind`，任务产物、导入附件与 Agent 文本成果分别使用稳定的 `task-artifact`、`attachment`、`agent-result`，不得以缺失值或显示文案兜底；资源协调签名必须包含 subtype。卡片尺寸、间距和拖动阈值必须由单一前端布局模型常量维护。
-- 资源集合变化时保留全部仍存在的坐标，只为新 ID 计算默认位置，并删除已确认失效的旧 ID；无论 `manuallyPlaced` 为何，已经写入的现存坐标都不得因重新排序、模式切换或新增资源被自动改写。
+- type 模式资源集合变化时保留全部仍存在的坐标，只为新 ID 计算默认位置，并删除已确认失效的旧 ID。dependency 模式只永久保留 `manuallyPlaced=true` 的用户坐标；`manuallyPlaced=false` 属于可派生自动位置，在 Rust 关系图首次就绪或可信 producer / dependency depth 变化后按最终拓扑确定性重算。自动重算不得移动手动坐标，协调结果与持久布局逐项一致时不得产生 CAS 写入。
 - 搜索或筛选只隐藏卡片，不删除、压缩或重排其坐标；清空搜索后恢复原位置。
 - 窗口尺寸变化只改变可视范围和分区滚动边界，不回写、裁切或缩放持久坐标。当前客户端继续以 `1280×800` 横屏合同验收。
-- 打开项目、切换 mode 或当前 mode 首次出现新资源时执行“读取 -> 协调 -> 必要时 CAS 写入”；项目或 mode 已切换后返回的旧异步结果必须丢弃。
+- 打开项目、切换 mode 或当前 mode 首次出现新资源时执行“读取 -> 协调 -> 必要时 CAS 写入”；dependency 模式必须先等待与当前 `projectPath + projectId + resource inputs` 匹配的 Rust 图进入 `ready` 或 `failed` 终态，等待期间不得创建 fallback、读取 sidecar、协调资源或入队保存。`failed` 只允许以空图降级初始化一次。项目或 mode 已切换后返回的旧异步结果必须丢弃。
 - 同一 `projectPath + projectId + mode` 的首次读取与资源集合协调必须分开：资源集合变化不得取消已经发出的读取或保存。同一 scope 内全部手动拖动和资源自动协调写入使用同一 FIFO，任一时刻最多一个 CAS 在途，后一笔必须使用前一笔成功返回的 revision，不能用“最后请求获胜”跳过中间 CAS。切换项目或 mode 后，旧 scope 的在途请求不能阻塞新 scope 队列；前端放弃旧请求槽位并丢弃其迟到响应，后端继续依靠 `expectedProjectId + expectedRevision + 系统锁` 仲裁已发出的请求。
 - 某笔 CAS 在途期间，同一 scope 内对相同 `resourceId + section` 重复产生但尚未发送的拖动意图必须折叠为最后坐标；已经在途的请求不得取消，不同资源的顺序不得跨越。队列增长必须受当前资源与分区数量约束，不能随连续 pointer 事件无界累积。
 - 用户拖动结束后先乐观更新，再立即提交一次 CAS。成功后以返回布局更新 revision；普通写入失败时恢复最近可信持久布局并提示“布局保存失败，已恢复上次布局”。
@@ -250,7 +250,7 @@ type UpdateProjectResourceCanvasLayoutResult =
 #### 5.2.5 资源依赖关系图层
 
 - 图层只在 dependency 模式挂载；type 模式不得渲染 SVG、连线或 marker。切换 mode、切换项目或卸载工作台时必须销毁旧图层，并清理尺寸观察和窗口事件监听。
-- 输入固定为当前资源投影的全部卡片身份 / 坐标与 Tauri Rust 返回的 `ProjectResourceGraph` 只读 DTO；Rust 负责资源过滤、去重、环检测、任务流聚合和一跳连接索引，前端只负责 DTO 防御归一化、浏览器几何与原生 SVG path / marker。SVG 叠加在资源卡底层并设置 `pointer-events: none`，不得引入 D3、React Flow 等图表库，也不得阻断卡片点击和 Pointer Events 拖动。
+- 输入固定为当前资源投影的全部卡片身份 / 坐标与 Tauri Rust 返回的 `ProjectResourceGraph` 只读 DTO；Rust 负责资源过滤、去重、迭代式环检测、SCC 压缩后的确定性依赖深度、任务流聚合和一跳连接索引，前端只负责 DTO 防御归一化、浏览器几何与原生 SVG path / marker。SVG 叠加在资源卡底层并设置 `pointer-events: none`，不得引入 D3、React Flow 等图表库，也不得阻断卡片点击和 Pointer Events 拖动。实时拖动坐标属于 DOM 临时状态，不得逐帧通过 Tauri IPC 交给 Rust。
 - `asset-reference` 表示精确资源引用，使用橙色实线与连续贝塞尔曲线。`GameCreationAppAssetManifestEntry.source.referenceResourceIds` 中的外部资源 ID 必须先唯一匹配另一项资产的 `source.resourceId`，再映射为当前资源卡 ID；缺失、重复或已删除的目标均不得渲染幽灵连线。
 - `task-flow` 表示任务产物流转，使用灰色圆头虚线。任务依赖按 `sourceTaskId -> targetTaskId` 聚合为一条主线，两端资源仅绘制平滑曲线分支，不得出现直角折线；禁止对上下游资源生成笛卡尔积连线。任务主线与分支可以使用不同线宽和透明度表达聚合层级，但不能改变端点或方向语义。
 - 画布资产 producer 只能来自 `agent.runtime.canvas.asset_generate` 的 `assetId -> agentId` 审计且 `agentId` 必须存在于当前 manifest；External Editor `source.taskId` 属于平台生成任务命名空间，禁止当作 manifest task ID。证据缺失、冲突或有界审计读取未覆盖时不生成对应 task flow，不猜测归属。
@@ -259,7 +259,7 @@ type UpdateProjectResourceCanvasLayoutResult =
 - 搜索只允许为当前可见端点生成几何；任一精确引用端点隐藏时该线隐藏，聚合任务流只保留仍可见的两端分支，任一侧没有可见资源时整条任务流隐藏。
 - 选中资源后，高亮其直接上游、直接下游卡片和关联边，弱化其余边；不做跨多层递归高亮。选中 ID 已失效时按未选中处理。
 - 拖动预览坐标必须直接进入 SVG 几何计算，使连线随 pointer move 实时更新；拖动结束仍只保存卡片布局坐标，不持久化 path、marker、section 原点或任何图结构。
-- Pointer Move 必须按动画帧合并；基础 positions 不随每帧复制，静态 SVG 拓扑保持复用，每帧只更新当前资源局部索引关联的 path。`ResizeObserver` 在单个图层生命周期只允许构造一次。dependency section 额外提供至少 `64px` 右侧视觉 gutter，确保最右侧自环和箭头可完整滚动显示，但不得修改卡片坐标或布局 sidecar。
+- Pointer Move 必须按动画帧合并并完全避开工作台父组件 state：拖动卡片通过 ref 直接更新 CSS 坐标，SVG 通过命令式句柄只更新当前资源局部索引关联的 path。基础 positions 不随每帧复制，静态卡片和 SVG 拓扑保持复用，非拖动卡片不得因预览帧重新渲染。`ResizeObserver` 在单个图层生命周期只允许构造一次。dependency section 额外提供至少 `64px` 右侧视觉 gutter，确保最右侧自环和箭头可完整滚动显示，但不得修改卡片坐标或布局 sidecar。
 
 ### 5.3 资源类型与替换兼容性（P1）
 
@@ -405,6 +405,7 @@ type ProjectAgentMudPointAttribution = {
 5. 搜索、选择和拖动分别触发端点过滤、直接上下游高亮和实时几何更新；原有点击、详情浮层与拖动保存行为不回归。
 6. 切换布局模式或项目后旧 SVG、ResizeObserver 与窗口监听全部清理；图层从不写入 layout sidecar、manifest 或其它持久化。
 7. 4096 资源链式 fixture 下，拖动一张卡片只更新它关联的线段；同一图层 100 次拖动期间 Observer 仍只构造一次。真实 Chromium 目标为拖动 p95 小于 `16.7ms`、不出现超过 `50ms` 的 long task，并完整显示最右侧自环与箭头。
+8. Rust 图读取延迟时，dependency sidecar 在图进入 `ready / failed` 前没有读取或写入；首次布局直接使用 Rust 返回的最终 producer 与 dependency depth。重新打开旧布局时手动位置逐项不变，自动位置按最终拓扑协调且相同结果不增加 revision。
 
 ## 8. 非目标
 
diff --git a/docs/project-memory/shared-memory/decision-log.md b/docs/project-memory/shared-memory/decision-log.md
index 1b4d0dae0..9b889b71f 100644
--- a/docs/project-memory/shared-memory/decision-log.md
+++ b/docs/project-memory/shared-memory/decision-log.md
@@ -1,5 +1,12 @@
 # 决策记录
 
+## 2026-08-03 依赖布局等待 Rust 图终态且拖动热路径脱离 React state
+
+- 背景：资源图异步返回前，dependency 布局会先以 `dependencyDepth=0` 创建并持久化自动坐标；图返回后的 reconcile 保留既有位置，导致首次布局永久停留在错误层级。4096 张真实资源卡拖动时，逐帧父组件 state 还会重渲染全部卡片，即使 SVG 已只更新局部 path 也无法满足帧预算。
+- 决策：Rust 关系图 read model 负责在完整任务图 SCC 压缩后返回确定性 resource dependency depth；dependency 模式等待当前 scope 图进入 `ready / failed` 后才启动布局读取与协调。手动位置永久保留，自动位置允许按最终图重新派生。拖动 preview 留在前端 ref/DOM 热路径，命令式更新卡片 CSS 与局部 SVG path，不逐帧跨 Tauri IPC，也不写 layout sidecar。
+- 边界：不修改 `game-creator-resource-layout.v1`、布局 Rust 持久层、manifest、api-server 或 SpacetimeDB；type 模式不等待资源图且继续保留全部已有坐标。图失败只降级初始化一次，项目或 mode 切换后旧图结果必须丢弃。
+- 验证：延迟图 Promise 证明终态前零布局读取/写入，手动位置保持且自动位置按最终深度协调；4096 张真实卡片连续拖动证明非拖动卡片零重渲染、静态 SVG 不重建、Observer 单实例，并以 Chromium p95 `<16.7ms` 和零 `>50ms` long task 验收。
+
 > 用途：记录已经确认、会影响后续开发的长期技术/产品/协作决策。短期讨论不要写在这里。
 
 ## 记录格式
diff --git a/docs/project-memory/shared-memory/pitfalls.md b/docs/project-memory/shared-memory/pitfalls.md
index 8a5d2f94d..1df822307 100644
--- a/docs/project-memory/shared-memory/pitfalls.md
+++ b/docs/project-memory/shared-memory/pitfalls.md
@@ -22,6 +22,14 @@
 - 验证：Rust fixture 把 `source.taskId` 固定为 `task-1 / task-2`，只有审计提供 `art-director / design-foundation` 后才生成 task flow；移除审计后橙色引用保留、灰色任务流消失。AppSurface 使用相同生产数据形状回归。
 - 关联：`apps/ai-game-creator-shell/src-tauri/src/project/resource_dependency_graph.rs`、`apps/ai-game-creator-shell/src/view/project-development/resourceDependencyGraphModel.ts`、`docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md`。
 
+## 依赖图未就绪时不能先初始化资源布局
+
+- 现象：首次打开 dependency 画布时所有资源短暂按深度 0 排列；Rust 图返回后连线正确，但卡片仍停留在同一列，错误自动坐标还可能已经写入 sidecar。
+- 原因：资源图和布局读取独立异步启动，布局 Hook 在图未返回时使用空图资源创建 fallback；后续 reconcile 按旧合同保留全部已有坐标，真实 producer 与 dependency depth 无法纠正首次自动位置。
+- 处理：dependency 模式增加按项目与资源输入隔离的图加载屏障，`ready / failed` 前不启动布局 Hook 的 fallback、读取、协调或保存。Rust read model 返回确定性依赖深度；已有布局只永久保留手动位置，自动位置按最终图重新派生。type 模式不受图加载影响。
+- 验证：用 deferred graph Promise 断言终态前 Tauri layout read/update 调用均为 0；图就绪后首次坐标直接按最终深度生成，旧 scope 迟到结果无效，手动坐标不变且相同自动布局不增加 revision。
+- 关联：`apps/ai-game-creator-shell/src/view/project-development/index.tsx`、`apps/ai-game-creator-shell/src/view/project-development/useProjectResourceCanvasLayout.ts`、`apps/ai-game-creator-shell/src-tauri/src/project/resource_dependency_graph.rs`。
+
 ## Jenkins 异步备份不能用 nohup 脱离作业
 
 - 现象：Stdb Publish 成功，上传日志只留下“已获取进程锁 / 上传已有备份 / 目标对象”，没有成功或可捕获错误；本地 tar.gz 和 `uploadStatus=deferred` manifest 每次发布后继续增长。
diff --git a/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md b/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md
index e2a6f4f4b..283fa5b6a 100644
--- a/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md
+++ b/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md
@@ -396,6 +396,10 @@ game-project/
 - 基础 positions 保持稳定，拖动预览单独传入。Pointer Move 通过 `requestAnimationFrame` 合帧；静态 task/reference React SVG 子树不依赖 drag preview，每帧只按局部连接索引重新计算当前资源关联的 edge / flow 并更新对应 path `d`。搜索、选择、项目切换、真实 positions 或 section origin 变化才允许重新协调静态图层；结束后仍只通过原布局 Hook 保存卡片坐标，SVG 几何从不持久化。
 - Rust、前端 DTO/SVG 和工作台 AppSurface 回归覆盖生产 `task-1` 数据形状、真实 producer、证据缺失、精确引用、去重、无效 ID、完整任务环、4096 链式拓扑、聚合复杂度、搜索过滤、选择高亮、局部拖动更新、稳定 Observer、type 模式卸载与项目切换销毁。真实 Chromium 性能目标为拖动 p95 `<16.7ms`、不出现 `>50ms` long task；若实测仍超过预算，再增加 viewport + overscan 边裁剪，不在首轮预先引入额外复杂度。
 
+2026-08-03 评审加固：Rust read model 在现有 producer assignment 上同时返回经完整任务图 SCC 压缩计算的确定性 `dependencyDepth`，前端不再递归推导正式依赖层级。dependency 模式以 scope 化 `idle / loading / ready / failed` 状态阻断布局 Hook；图终态前不创建 fallback、不读取或写入 sidecar，图失败只以空图初始化一次。读取已有 dependency 布局时保留全部 `manuallyPlaced=true` 坐标，把 `manuallyPlaced=false` 作为可派生自动位置按最终深度重新协调；结果未变化时不写入。
+
+拖动热路径不再把 preview 写入工作台父组件 state。卡片使用稳定回调与 `React.memo`，动画帧直接更新拖动卡片 CSS 变量和 section 临时 extent；SVG 图层暴露命令式 preview 句柄，复用 Rust 局部连接索引和已缓存 path 节点，只更新受影响 reference / task-flow 几何。ResizeObserver 仍为单图层单实例。4096 张真实卡片测试必须证明非拖动卡片零重渲染、静态 SVG 子树不重建，Chromium p95 继续以 `<16.7ms` 为门槛。实时 DOM 几何不得通过 Tauri IPC 往返 Rust。
+
 ## 分阶段实施
 
 1. 在 `platform-agent` 建立游戏创作专业组与种子任务图契约。
-- 
2.52.0


From 7f038490f18360745bbb4d35c5b305ee53fd3fb6 Mon Sep 17 00:00:00 2001
From: menghao <mh18530625731@163.com>
Date: Mon, 3 Aug 2026 11:53:59 +0800
Subject: [PATCH 07/27] =?UTF-8?q?=E4=BF=AE=E5=A4=8D=E8=BF=90=E8=A1=8C?=
 =?UTF-8?q?=E6=97=B6=E6=81=A2=E5=A4=8D=E8=B7=AF=E5=BE=84=E6=A0=88=E6=BA=A2?=
 =?UTF-8?q?=E5=87=BA?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

为 pending continuation 与后台主循环增加可取消的 Tokio 任务边界
保留 durable batch 恢复防重和父任务取消语义
补充运行时技术约束与共享排障记录
---
 .../agent/runtime_driver/pending_execution.rs | 36 +++++++++++++++++--
 docs/project-memory/shared-memory/pitfalls.md |  8 +++++
 ...�案】AI游戏创作智能体App实施计划-2026-06-24.md |  1 +
 3 files changed, 43 insertions(+), 2 deletions(-)

diff --git a/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_driver/pending_execution.rs b/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_driver/pending_execution.rs
index 385d4066b..826ff7701 100644
--- a/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_driver/pending_execution.rs
+++ b/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_driver/pending_execution.rs
@@ -1,5 +1,37 @@
 use super::*;
 
+async fn run_game_creator_agent_background_task_after_pending_stack_boundary(
+    root: PathBuf,
+    agent_id: String,
+    task: String,
+    runtime: AgentRuntimeState,
+    continuation: AgentRuntimeContinuationContext,
+) -> AgentBackgroundTaskOutcome {
+    // Debug builds give both pending execution and the background main loop large poll frames.
+    // A joined child task prevents those frames from sharing one Tokio worker stack while
+    // JoinSet still aborts the child if its parent continuation is dropped.
+    let mut tasks = tokio::task::JoinSet::new();
+    tasks.spawn(async move {
+        run_game_creator_agent_background_task_with_context(
+            root,
+            agent_id,
+            task,
+            runtime,
+            continuation,
+        )
+        .await
+    });
+    match tasks
+        .join_next()
+        .await
+        .expect("pending continuation task must exist")
+    {
+        Ok(outcome) => outcome,
+        Err(error) if error.is_panic() => std::panic::resume_unwind(error.into_panic()),
+        Err(error) => panic!("pending continuation task was cancelled: {error}"),
+    }
+}
+
 pub(crate) async fn continue_game_creator_agent_pending_tool_action(
     root: PathBuf,
     agent_id: String,
@@ -61,7 +93,7 @@ pub(crate) async fn continue_game_creator_agent_pending_tool_action(
             usize::try_from(batch.loop_iteration.saturating_sub(1)).unwrap_or(usize::MAX);
         continuation.context_stalled = false;
         continuation.applied_steer_cursor = batch.planned_steer_cursor;
-        let outcome = run_game_creator_agent_background_task_with_context(
+        let outcome = run_game_creator_agent_background_task_after_pending_stack_boundary(
             root.clone(),
             agent_id.clone(),
             pending.task.clone(),
@@ -787,7 +819,7 @@ pub(crate) async fn continue_game_creator_agent_pending_tool_action(
             return;
         }
     }
-    let outcome = run_game_creator_agent_background_task_with_context(
+    let outcome = run_game_creator_agent_background_task_after_pending_stack_boundary(
         root.clone(),
         agent_id.clone(),
         pending.task.clone(),
diff --git a/docs/project-memory/shared-memory/pitfalls.md b/docs/project-memory/shared-memory/pitfalls.md
index 1df822307..db596d07c 100644
--- a/docs/project-memory/shared-memory/pitfalls.md
+++ b/docs/project-memory/shared-memory/pitfalls.md
@@ -3986,6 +3986,14 @@
 - 处理：先以 CAS 单独 commit `queued -> executing`，成功后才调 ToolHost；调用返回后再 commit observation。恢复见到 executing 或 ToolHost 返回 Unknown 时只能进入 reconciliation，不得自动重执行。重复 resume 不得继续增 revision 或重复 event。
 - 验证：在“ToolHost 已调用、observation commit 失败”处注入故障，序列化快照并用新 engine 重载；断言重复 resume 后 ToolHost 计数仍为 1，且只有显式 reconcile observation 才恢复 running。
 
+## 大型 async 状态机不能在同一 Tokio poll 调用栈连续嵌套（2026-08-03）
+
+- 现象：Supervisor collaboration durable isolated spawn 恢复测试在默认 Tokio worker 栈下稳定 `stack overflow`；单独运行同样失败，提高 `RUST_MIN_STACK` 后通过。
+- 原因：不是业务递归。debug 构建中 pending action continuation、后台 task queue 和 Agent 主循环各自形成大型 async poll frame；恢复路径在同一次 poll 调用链直接进入下一层状态机，累计超过 worker 默认栈。
+- 处理：在 pending continuation 与后台主循环之间建立独立 Tokio task 轮询边界，使 pending poll 先退栈后再轮询主循环。边界必须保留结构化取消语义；当前使用 `JoinSet`，父 continuation 被丢弃时同步 abort 子任务。不得只增大 CI 的 `RUST_MIN_STACK`，否则生产默认栈仍可能崩溃。
+- 验证：失败用例必须在未设置 `RUST_MIN_STACK` 时通过；同时覆盖 policy batch 全组和 pending/cancellation 回归，证明恢复不重复生成 isolated spawn、父任务取消不遗留后台子任务。
+- 关联：`apps/ai-game-creator-shell/src-tauri/src/agent/runtime_driver/pending_execution.rs`。
+
 ## Provider 可扩展不能用一个全局 protocol 枚举代替实例隔离
 
 - 现象：把 `openai_chat / openai_responses / anthropic` 直接当 Provider 身份，注册第二个同协议 endpoint 时发生 ID 冲突；或为方便调用把 API Key、base URL、raw-log 目录放进全局状态，并行请求后日志串目录。
diff --git a/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md b/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md
index 283fa5b6a..87f5971ce 100644
--- a/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md
+++ b/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md
@@ -756,6 +756,7 @@ game-project/
 - 开发模式可通过本地项目文件面板执行 `file.list/read/write/delete`，普通用户界面不暴露文件面板。
 - 2026-07-17 起，同一 Runtime 文档的“V1.32 Runtime 强制 Supervisor 协作合同”作为 mixed swarm 可靠性事实源。项目可用 `.agent/collaboration-policy.json` 约束首波 static/isolated 模式、数量和 required static Agent；Runtime 在任何 child 副作用前整批校验并把合同指纹固化进 Provider batch v2。当前父 run 一旦形成 delivery/group，正式 `project-supervisor` 默认只负责编排、状态认领和验证，不再直接执行项目 mutation；专业 Agent/isolated child 权限与唯一 Supervisor 最终回复边界保持不变。
 - 2026-07-17 V1.32 最终代码已完成独立真实 Provider PASS：首批 mixed batch、三 isolated child、Runner 强杀恢复、专业返工、宿主验证、唯一最终回复与零重复/残留/泄漏同时成立。真实报告计数、隔离重试配置和仍待收敛的 tool-plan repair 成本统一以 Runtime 文档 V1.32 章节与共享决策记录为准。
+- 2026-08-03 恢复执行补充约束：pending action continuation 进入后台主循环时必须先跨越独立 Tokio task 轮询边界，不能让 pending executor、task queue 与 Agent 主循环的大型 async poll frame 在同一 worker 调用栈连续嵌套。边界必须随父 continuation 取消子任务并保持 durable action、batch、run/session 身份及恢复防重语义；当前使用 `JoinSet` 承担结构化取消。CI 和生产均使用默认 worker 栈验证，不以提高 `RUST_MIN_STACK` 代替代码边界。
 - 2026-07-18 起，同一 Runtime 文档的“V1.34 动态隔离子 Agent writeScopes 命令绕过封堵”作为 isolated child 的现行能力事实源。在 scope-aware OS sandbox 完成前，动态 child 无条件禁用 `project.verify / project.git_commit / command.exec / command.start / command.stdin / preview.start / agent.delegate / agent.spawn_isolated / project.restore / agent.schedule_ready / canvas.asset_generate / task.create / task.update / blackboard.write` 和全部 MCP；原生工具策略统一显示 `denied`，模板、项目 policy 与用户确认均不能放宽。保留固定只读 `command.run_limited`、同身份 `command.output_read / command.poll / command.terminate`、既有预览的 `preview.validate`，以及严格位于 `writeScopes` 内的 `file.write / file.patch / file.delete / project.patchset`。
 - V1.34 的新单动作在 confirmation 和 OS launcher 前拒绝；新多 action 原生 batch 只要含一个 denied member 就在独立 pending-action sidecar、confirmation、OS spawn、revision 和任何成员项目副作用前整批 abort，只保留 `aborted / nextActionIndex=0` batch 事实。旧 pending / approval / batch 真正进入执行器时仍重新应用当前 child 边界，旧 executing 未知结果继续进入既有 reconciliation。该安全收紧由恶意 sibling 写入、策略快照、batch、旧 pending 执行器重验和 isolated/mixed/collaboration/provider-batch 回归证明；不因本切片重跑已通过且 isolated mutation 为 0 的 V1.31/V1.32 外部 Provider suite。通用命令只有在后续 scope-aware OS sandbox 对所有后代强制同一 `writeScopes` 并通过独立决策与测试后才可重新评估开放。
 - 2026-07-18 起，同一 Runtime 文档的“V1.35 多 ready isolated all-join 原子认领与恢复”作为 `agent.run_status` 同父 run 多 group 认领的现行事实源。Runtime 按 `delegationGroupId` 排序并一次性预取全部 join 锁；任一后续锁忙时保持零 delivery mutation、零 claim sidecar。全锁就绪后，同一 action 的 durable claim journal 按 `prepared -> committed -> observed` 推进；部分 commit 或 Runner 恢复只能复用该 journal 幂等补齐。只认领可完整放入优先 `readyIsolatedJoins` 观察预算的有序前缀，未观察旧 claim 可由后续 action 完整重放，但不创建第二份 isolated claim。每个 claimed delivery 必须由匹配原 action/group 的 journal 覆盖；无 journal 的旧 delivery 每轮只迁移一个原 action，已有 journal 不得扩写或状态倒退，跨 action group 归属冲突失败关闭。成功 observation 写入 pending sidecar 后只能把本轮完整输出的 claim 标记 `observed`，任一未观察或无 journal claim 继续阻断 finalization；每个 group 审计按 `actionId + delegationGroupId` 唯一，并在 Agent DB 锁内修复 torn tail、全量核对后幂等追加。
-- 
2.52.0


From bda0d0d3988d6bbfa20fd5c078072b919e0891e6 Mon Sep 17 00:00:00 2001
From: menghao <mh18530625731@163.com>
Date: Mon, 3 Aug 2026 13:34:25 +0800
Subject: [PATCH 08/27] =?UTF-8?q?=E4=BF=AE=E5=A4=8DLinux=E8=BF=9B=E7=A8=8B?=
 =?UTF-8?q?=E6=A0=91=E6=8E=A2=E6=B4=BB=E4=B8=8ERuntime=E9=BB=98=E8=AE=A4?=
 =?UTF-8?q?=E6=A0=88=E6=BA=A2=E5=87=BA?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Linux进程组探活忽略已终止但未回收的zombie成员

pending恢复与后续队列统一跨越装箱的Tokio任务边界

补充Tauri生命周期和Runtime默认栈回归测试与文档
---
 .../scripts/start-dev-stack.mjs               | 98 +++++++++++++++++--
 .../agent/runtime_driver/pending_execution.rs | 98 ++++++++++++++-----
 .../tests/start-dev-stack.test.ts             | 36 +++++++
 .../tests/start-tauri-dev.test.ts             |  8 +-
 docs/project-memory/shared-memory/pitfalls.md |  8 +-
 ...�案】AI游戏创作智能体App实施计划-2026-06-24.md |  2 +-
 ...发运维】本地开发验证与生产运维-2026-05-15.md |  2 +-
 7 files changed, 215 insertions(+), 37 deletions(-)

diff --git a/apps/ai-game-creator-shell/scripts/start-dev-stack.mjs b/apps/ai-game-creator-shell/scripts/start-dev-stack.mjs
index 81fae0bee..3d079a82f 100644
--- a/apps/ai-game-creator-shell/scripts/start-dev-stack.mjs
+++ b/apps/ai-game-creator-shell/scripts/start-dev-stack.mjs
@@ -1,8 +1,8 @@
 import { spawn } from 'node:child_process';
-import { existsSync, readFileSync } from 'node:fs';
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
 import http from 'node:http';
 import net from 'node:net';
-import { resolve } from 'node:path';
+import { join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 const appRoot = fileURLToPath(new URL('..', import.meta.url));
@@ -300,16 +300,100 @@ function stopChild(child, signal = 'SIGTERM') {
   }
 }
 
-function isProcessGroupAlive(processGroupId, killImpl = process.kill) {
+function parseLinuxProcessStat(value) {
+  const commandEnd = value.lastIndexOf(')');
+  if (commandEnd < 0) {
+    return null;
+  }
+  const fields = value
+    .slice(commandEnd + 1)
+    .trim()
+    .split(/\s+/);
+  if (fields.length < 3 || fields[0].length !== 1) {
+    return null;
+  }
+  const processGroupId = Number(fields[2]);
+  if (!Number.isInteger(processGroupId)) {
+    return null;
+  }
+  return { state: fields[0], processGroupId };
+}
+
+function readLinuxProcessGroupRunning(
+  processGroupId,
+  {
+    procRoot = '/proc',
+    readdirImpl = readdirSync,
+    readFileImpl = readFileSync,
+  } = {},
+) {
+  let entries;
+  try {
+    entries = readdirImpl(procRoot, { withFileTypes: true });
+  } catch {
+    return null;
+  }
+
+  let inspectedProcess = false;
+  for (const entry of entries) {
+    const name = typeof entry === 'string' ? entry : entry.name;
+    if (!/^\d+$/.test(name)) {
+      continue;
+    }
+    if (typeof entry !== 'string' && !entry.isDirectory()) {
+      continue;
+    }
+    let stat;
+    try {
+      stat = readFileImpl(join(procRoot, name, 'stat'), 'utf8');
+    } catch (error) {
+      // 进程可能在枚举后立刻退出；继续检查同组的其它成员。
+      if (error?.code === 'ENOENT' || error?.code === 'ESRCH') {
+        continue;
+      }
+      return null;
+    }
+    const parsed = parseLinuxProcessStat(stat);
+    if (!parsed) {
+      return null;
+    }
+    inspectedProcess = true;
+    if (
+      parsed?.processGroupId === processGroupId &&
+      !['Z', 'X', 'x'].includes(parsed.state)
+    ) {
+      return true;
+    }
+  }
+  return inspectedProcess ? false : null;
+}
+
+function isProcessGroupRunning(
+  processGroupId,
+  {
+    platform = process.platform,
+    killImpl = process.kill,
+    readLinuxProcessGroup = readLinuxProcessGroupRunning,
+  } = {},
+) {
   if (!Number.isInteger(processGroupId)) {
     return false;
   }
   try {
     killImpl(-processGroupId, 0);
-    return true;
   } catch (error) {
     return error?.code !== 'ESRCH';
   }
+  if (platform !== 'linux') {
+    return true;
+  }
+  try {
+    // Linux 的 kill(-PGID, 0) 会把尚未被容器 PID 1 回收的 zombie 也视为
+    // 存在；zombie 已不能执行代码，不应让有界清理被误判为失败。
+    return readLinuxProcessGroup(processGroupId) ?? true;
+  } catch {
+    return true;
+  }
 }
 
 async function waitUntil(check, timeoutMs, pollIntervalMs = 25) {
@@ -415,7 +499,7 @@ async function terminateChildTree(
   stopChild(child, 'SIGTERM');
   if (
     await waitUntil(
-      () => !isProcessGroupAlive(processGroupId, killImpl),
+      () => !isProcessGroupRunning(processGroupId, { platform, killImpl }),
       gracefulTimeoutMs,
     )
   ) {
@@ -430,7 +514,7 @@ async function terminateChildTree(
     }
   }
   const stopped = await waitUntil(
-    () => !isProcessGroupAlive(processGroupId, killImpl),
+    () => !isProcessGroupRunning(processGroupId, { platform, killImpl }),
     forceTimeoutMs,
   );
   return { stopped, forced: true };
@@ -600,8 +684,10 @@ export {
   ensureBackend,
   formatChildFailure,
   isDirectModuleExecution,
+  isProcessGroupRunning,
   preflightExistingVite,
   readChildFailure,
+  readLinuxProcessGroupRunning,
   resolveBackendTargetsFromState,
   runWindowsTaskkill,
   spawnChild,
diff --git a/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_driver/pending_execution.rs b/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_driver/pending_execution.rs
index 826ff7701..672ea98f7 100644
--- a/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_driver/pending_execution.rs
+++ b/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_driver/pending_execution.rs
@@ -1,5 +1,28 @@
 use super::*;
 
+async fn run_after_pending_stack_boundary<T>(
+    future: std::pin::Pin<Box<dyn std::future::Future<Output = T> + Send + 'static>>,
+) -> T
+where
+    T: Send + 'static,
+{
+    // Debug builds give pending execution, the background main loop, and queue draining large
+    // poll frames. The boxed future keeps that large frame out of its caller before a joined child
+    // task gives it an independent poll boundary. JoinSet still aborts the child if its parent
+    // continuation is dropped.
+    let mut tasks = tokio::task::JoinSet::new();
+    tasks.spawn(future);
+    match tasks
+        .join_next()
+        .await
+        .expect("pending continuation task must exist")
+    {
+        Ok(output) => output,
+        Err(error) if error.is_panic() => std::panic::resume_unwind(error.into_panic()),
+        Err(error) => panic!("pending continuation task was cancelled: {error}"),
+    }
+}
+
 async fn run_game_creator_agent_background_task_after_pending_stack_boundary(
     root: PathBuf,
     agent_id: String,
@@ -7,11 +30,7 @@ async fn run_game_creator_agent_background_task_after_pending_stack_boundary(
     runtime: AgentRuntimeState,
     continuation: AgentRuntimeContinuationContext,
 ) -> AgentBackgroundTaskOutcome {
-    // Debug builds give both pending execution and the background main loop large poll frames.
-    // A joined child task prevents those frames from sharing one Tokio worker stack while
-    // JoinSet still aborts the child if its parent continuation is dropped.
-    let mut tasks = tokio::task::JoinSet::new();
-    tasks.spawn(async move {
+    run_after_pending_stack_boundary(Box::pin(async move {
         run_game_creator_agent_background_task_with_context(
             root,
             agent_id,
@@ -20,19 +39,36 @@ async fn run_game_creator_agent_background_task_after_pending_stack_boundary(
             continuation,
         )
         .await
-    });
-    match tasks
-        .join_next()
-        .await
-        .expect("pending continuation task must exist")
-    {
-        Ok(outcome) => outcome,
-        Err(error) if error.is_panic() => std::panic::resume_unwind(error.into_panic()),
-        Err(error) => panic!("pending continuation task was cancelled: {error}"),
-    }
+    }))
+    .await
+}
+
+async fn drain_next_game_creator_agent_background_tasks_after_pending_stack_boundary(
+    root: PathBuf,
+    agent_id: String,
+) {
+    run_after_pending_stack_boundary(Box::pin(async move {
+        drain_next_game_creator_agent_background_tasks(root, agent_id).await;
+    }))
+    .await;
 }
 
 pub(crate) async fn continue_game_creator_agent_pending_tool_action(
+    root: PathBuf,
+    agent_id: String,
+    pending: AgentRuntimePendingToolAction,
+    runtime: AgentRuntimeState,
+) {
+    run_after_pending_stack_boundary(Box::pin(async move {
+        continue_game_creator_agent_pending_tool_action_within_stack_boundary(
+            root, agent_id, pending, runtime,
+        )
+        .await;
+    }))
+    .await;
+}
+
+async fn continue_game_creator_agent_pending_tool_action_within_stack_boundary(
     root: PathBuf,
     agent_id: String,
     mut pending: AgentRuntimePendingToolAction,
@@ -102,7 +138,10 @@ pub(crate) async fn continue_game_creator_agent_pending_tool_action(
         )
         .await;
         if matches!(outcome, AgentBackgroundTaskOutcome::Finished) {
-            drain_next_game_creator_agent_background_tasks(root, agent_id).await;
+            drain_next_game_creator_agent_background_tasks_after_pending_stack_boundary(
+                root, agent_id,
+            )
+            .await;
         }
         return;
     }
@@ -111,7 +150,8 @@ pub(crate) async fn continue_game_creator_agent_pending_tool_action(
     if !has_persisted_terminal_observation
         && stop_game_creator_agent_runtime_if_cancel_requested(&root, &mut runtime)
     {
-        drain_next_game_creator_agent_background_tasks(root, agent_id).await;
+        drain_next_game_creator_agent_background_tasks_after_pending_stack_boundary(root, agent_id)
+            .await;
         return;
     }
     if let Err(error) = validate_agent_runtime_pending_context(&root, &runtime, &pending) {
@@ -373,14 +413,18 @@ pub(crate) async fn continue_game_creator_agent_pending_tool_action(
             &pending,
             &observation,
         ) {
-            drain_next_game_creator_agent_background_tasks(root, agent_id).await;
+            drain_next_game_creator_agent_background_tasks_after_pending_stack_boundary(
+                root, agent_id,
+            )
+            .await;
         }
         return;
     }
     if observation.is_waiting_for_confirmation()
         && stop_game_creator_agent_runtime_if_cancel_requested(&root, &mut runtime)
     {
-        drain_next_game_creator_agent_background_tasks(root, agent_id).await;
+        drain_next_game_creator_agent_background_tasks_after_pending_stack_boundary(root, agent_id)
+            .await;
         return;
     }
     if observation.is_waiting_for_confirmation() {
@@ -557,7 +601,8 @@ pub(crate) async fn continue_game_creator_agent_pending_tool_action(
         }),
     );
     if stop_game_creator_agent_runtime_if_cancel_requested(&root, &mut runtime) {
-        drain_next_game_creator_agent_background_tasks(root, agent_id).await;
+        drain_next_game_creator_agent_background_tasks_after_pending_stack_boundary(root, agent_id)
+            .await;
         return;
     }
     if !auto_execution {
@@ -734,7 +779,10 @@ pub(crate) async fn continue_game_creator_agent_pending_tool_action(
                 runtime,
                 &format!("恢复 Agent Runtime context bundle 失败：{error}"),
             );
-            drain_next_game_creator_agent_background_tasks(root, agent_id).await;
+            drain_next_game_creator_agent_background_tasks_after_pending_stack_boundary(
+                root, agent_id,
+            )
+            .await;
             return;
         }
     };
@@ -785,7 +833,10 @@ pub(crate) async fn continue_game_creator_agent_pending_tool_action(
                 runtime,
                 &format!("持久化 Agent Runtime context bundle 失败：{error}"),
             );
-            drain_next_game_creator_agent_background_tasks(root, agent_id).await;
+            drain_next_game_creator_agent_background_tasks_after_pending_stack_boundary(
+                root, agent_id,
+            )
+            .await;
             return;
         }
     };
@@ -828,7 +879,8 @@ pub(crate) async fn continue_game_creator_agent_pending_tool_action(
     )
     .await;
     if matches!(outcome, AgentBackgroundTaskOutcome::Finished) {
-        drain_next_game_creator_agent_background_tasks(root, agent_id).await;
+        drain_next_game_creator_agent_background_tasks_after_pending_stack_boundary(root, agent_id)
+            .await;
     }
 }
 
diff --git a/apps/ai-game-creator-shell/tests/start-dev-stack.test.ts b/apps/ai-game-creator-shell/tests/start-dev-stack.test.ts
index 50ea09925..c80615e14 100644
--- a/apps/ai-game-creator-shell/tests/start-dev-stack.test.ts
+++ b/apps/ai-game-creator-shell/tests/start-dev-stack.test.ts
@@ -7,7 +7,9 @@ import { describe, expect, test, vi } from 'vitest';
 
 import {
   ensureBackend,
+  isProcessGroupRunning,
   preflightExistingVite,
+  readLinuxProcessGroupRunning,
   resolveBackendTargetsFromState,
   runWindowsTaskkill,
   spawnChild,
@@ -154,6 +156,40 @@ describe('AI 游戏创作启动子进程生命周期', () => {
     }
   });
 
+  test('Linux 进程组探活忽略已退出但尚未回收的 zombie', () => {
+    const stats = new Map([
+      ['/proc/4822/stat', '4822 (node worker) Z 1 4821 4821'],
+      ['/proc/7001/stat', '7001 (other) S 1 7001 7001'],
+    ]);
+    const readLinuxGroup = () =>
+      readLinuxProcessGroupRunning(4821, {
+        readdirImpl: () => [
+          { name: '4822', isDirectory: () => true },
+          { name: '7001', isDirectory: () => true },
+        ],
+        readFileImpl: (path) => stats.get(path),
+      });
+
+    expect(readLinuxGroup()).toBe(false);
+    expect(
+      isProcessGroupRunning(4821, {
+        platform: 'linux',
+        killImpl: vi.fn(),
+        readLinuxProcessGroup: readLinuxGroup,
+      }),
+    ).toBe(false);
+    expect(
+      isProcessGroupRunning(4821, {
+        platform: 'linux',
+        killImpl: vi.fn(),
+        readLinuxProcessGroup: () => null,
+      }),
+    ).toBe(true);
+
+    stats.set('/proc/4822/stat', '4822 (node worker) R 1 4821 4821');
+    expect(readLinuxGroup()).toBe(true);
+  });
+
   test('后端句柄在 ready 等待前交给外层且异常时立即清理', async () => {
     const child = Object.assign(new EventEmitter(), {
       exitCode: null,
diff --git a/apps/ai-game-creator-shell/tests/start-tauri-dev.test.ts b/apps/ai-game-creator-shell/tests/start-tauri-dev.test.ts
index d5e73f03b..9193eb134 100644
--- a/apps/ai-game-creator-shell/tests/start-tauri-dev.test.ts
+++ b/apps/ai-game-creator-shell/tests/start-tauri-dev.test.ts
@@ -5,7 +5,11 @@ import { join } from 'node:path';
 
 import { describe, expect, test, vi } from 'vitest';
 
-import { spawnChild, terminateChildTree } from '../scripts/start-dev-stack.mjs';
+import {
+  isProcessGroupRunning,
+  spawnChild,
+  terminateChildTree,
+} from '../scripts/start-dev-stack.mjs';
 import {
   buildTauriArguments,
   runTauriDev,
@@ -200,7 +204,7 @@ describe('AI 游戏创作 Tauri dev 生命周期', () => {
       });
 
       expect(result).toBe(42);
-      expect(() => process.kill(-cliChild.pid, 0)).toThrow();
+      expect(isProcessGroupRunning(cliChild.pid)).toBe(false);
     } finally {
       if (Number.isInteger(cliChild?.pid)) {
         try {
diff --git a/docs/project-memory/shared-memory/pitfalls.md b/docs/project-memory/shared-memory/pitfalls.md
index e5d0aa652..fb8d79f99 100644
--- a/docs/project-memory/shared-memory/pitfalls.md
+++ b/docs/project-memory/shared-memory/pitfalls.md
@@ -3990,8 +3990,8 @@
 
 - 现象：Supervisor collaboration durable isolated spawn 恢复测试在默认 Tokio worker 栈下稳定 `stack overflow`；单独运行同样失败，提高 `RUST_MIN_STACK` 后通过。
 - 原因：不是业务递归。debug 构建中 pending action continuation、后台 task queue 和 Agent 主循环各自形成大型 async poll frame；恢复路径在同一次 poll 调用链直接进入下一层状态机，累计超过 worker 默认栈。
-- 处理：在 pending continuation 与后台主循环之间建立独立 Tokio task 轮询边界，使 pending poll 先退栈后再轮询主循环。边界必须保留结构化取消语义；当前使用 `JoinSet`，父 continuation 被丢弃时同步 abort 子任务。不得只增大 CI 的 `RUST_MIN_STACK`，否则生产默认栈仍可能崩溃。
-- 验证：失败用例必须在未设置 `RUST_MIN_STACK` 时通过；同时覆盖 policy batch 全组和 pending/cancellation 回归，证明恢复不重复生成 isolated spawn、父任务取消不遗留后台子任务。
+- 处理：整个 pending continuation、它进入的后台主循环，以及完成、取消或失败后 drain 同 Agent 后续队列时，都必须跨越独立 Tokio task 轮询边界，使上层 poll 先退栈后再轮询下一层状态机。传入边界的 future 必须先装箱；若泛型 helper 直接持有大型 future，即使随后 `spawn`，调用方 async frame 仍会把它保留在默认 worker 栈上。边界必须保留结构化取消语义；当前使用 boxed future 与 `JoinSet`，父 continuation 被丢弃时同步 abort 子任务。不得只增大 CI 的 `RUST_MIN_STACK`，否则生产默认栈仍可能崩溃。
+- 验证：失败用例必须在未设置 `RUST_MIN_STACK` 时通过；同时覆盖 policy batch 全组、拒绝 pending 后重规划并 drain 下一任务，以及 pending/cancellation 回归，证明恢复不重复生成 isolated spawn、队列继续推进且父任务取消不遗留后台子任务。
 - 关联：`apps/ai-game-creator-shell/src-tauri/src/agent/runtime_driver/pending_execution.rs`。
 
 ## Provider 可扩展不能用一个全局 protocol 枚举代替实例隔离
@@ -4027,8 +4027,8 @@
 
 - 现象：旧 worktree 的 AGC Vite 长期占用 `127.0.0.1:3080`，marker 仍指向旧 API；新 worktree 启动 game-chat 后，配套后端在新端口 ready，随后 `beforeDevCommand` 因代理 target 不匹配返回非零，终端已经回到提示符，但原生客户端和它启动的 Runner 仍存活。客户端 WebView 实际加载旧 Vite，因此当前 master 的界面优化看起来全部缺失。
 - 原因：Tauri 的字符串 `beforeDevCommand` 默认 `wait=false`。只要固定 `devUrl` 上已有可访问页面，Tauri CLI 可以在配套启动脚本完成前创建原生窗口；旧实现又直接从 npm 启动 Tauri CLI，没有在 CLI leader 退出后继续持有其 PGID / Windows 进程树。`start-dev-stack.mjs` 虽会在后端 ready 后识别 marker/API 错配，但检查时机已经晚于窗口创建，且只清理自己登记的后端和 Vite。
-- 处理：`dev` 与 `game-chat` 统一先进入 `start-tauri-dev.mjs`，在启动 Tauri CLI 前无副作用检查 3080。现有 marker 只有 API target，不能证明监听器属于当前 worktree，因此任何已存在的 3080 都失败关闭，不主动杀不能证明归属的旧服务，也不因 target 看似匹配而复用。Tauri CLI 使用独立 POSIX 进程组，任意退出后按负 PGID 先 TERM、有界等待、再 KILL；Windows 固定调用 `taskkill /PID <pid> /T /F`。`start-dev-stack.mjs` 自己的后端 / Vite 独立组也在返回前有界收束。
-- 验证：定向测试必须覆盖旧 marker target 在 CLI spawn 前被拒绝、target 看似匹配仍拒绝无归属 Vite、非 HTTP 3080 失败、预检调用顺序、CLI leader 先退出后同 PGID 客户端仍收到 TERM、忽略 TERM 时升级 KILL，以及 Windows taskkill 的 `/PID /T /F` 参数。人工复验旧 worktree 占用 3080 时，新命令不得启动后端或弹出新窗口；正常启动后退出，确认 Tauri 客户端、Runner 和本轮自有后端 / Vite 均按生命周期收束。
+- 处理：`dev` 与 `game-chat` 统一先进入 `start-tauri-dev.mjs`，在启动 Tauri CLI 前无副作用检查 3080。现有 marker 只有 API target，不能证明监听器属于当前 worktree，因此任何已存在的 3080 都失败关闭，不主动杀不能证明归属的旧服务，也不因 target 看似匹配而复用。Tauri CLI 使用独立 POSIX 进程组，任意退出后按负 PGID 先 TERM、有界等待、再 KILL；Windows 固定调用 `taskkill /PID <pid> /T /F`。Linux 容器的 PID 1 可能不及时回收已退出的孤儿后代，`kill(-PGID, 0)` 会继续命中 zombie；Linux 探活必须扫描 `/proc/<pid>/stat`，只把同 PGID 的非 zombie 成员视为仍在运行，`/proc` 不可读时继续失败关闭。`start-dev-stack.mjs` 自己的后端 / Vite 独立组也在返回前有界收束。
+- 验证：定向测试必须覆盖旧 marker target 在 CLI spawn 前被拒绝、target 看似匹配仍拒绝无归属 Vite、非 HTTP 3080 失败、预检调用顺序、CLI leader 先退出后同 PGID 客户端仍收到 TERM、忽略 TERM 时升级 KILL、Linux 同组只剩 zombie 时视为已停止，以及 Windows taskkill 的 `/PID /T /F` 参数。人工复验旧 worktree 占用 3080 时，新命令不得启动后端或弹出新窗口；正常启动后退出，确认 Tauri 客户端、Runner 和本轮自有后端 / Vite 均按生命周期收束。
 - 关联：`apps/ai-game-creator-shell/scripts/start-tauri-dev.mjs`、`apps/ai-game-creator-shell/scripts/start-dev-stack.mjs`、`apps/ai-game-creator-shell/tests/start-tauri-dev.test.ts`、`apps/ai-game-creator-shell/tests/start-dev-stack.test.ts`。
 
 ## game-chat 快车道首波与已提交回复不能被后续 revision 破坏（2026-08-03）
diff --git a/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md b/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md
index de8811ebc..b9f062085 100644
--- a/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md
+++ b/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md
@@ -765,7 +765,7 @@ game-project/
 - 开发模式可通过本地项目文件面板执行 `file.list/read/write/delete`，普通用户界面不暴露文件面板。
 - 2026-07-17 起，同一 Runtime 文档的“V1.32 Runtime 强制 Supervisor 协作合同”作为 mixed swarm 可靠性事实源。项目可用 `.agent/collaboration-policy.json` 约束首波 static/isolated 模式、数量和 required static Agent；Runtime 在任何 child 副作用前整批校验并把合同指纹固化进 Provider batch v2。当前父 run 一旦形成 delivery/group，正式 `project-supervisor` 默认只负责编排、状态认领和验证，不再直接执行项目 mutation；专业 Agent/isolated child 权限与唯一 Supervisor 最终回复边界保持不变。
 - 2026-07-17 V1.32 最终代码已完成独立真实 Provider PASS：首批 mixed batch、三 isolated child、Runner 强杀恢复、专业返工、宿主验证、唯一最终回复与零重复/残留/泄漏同时成立。真实报告计数、隔离重试配置和仍待收敛的 tool-plan repair 成本统一以 Runtime 文档 V1.32 章节与共享决策记录为准。
-- 2026-08-03 恢复执行补充约束：pending action continuation 进入后台主循环时必须先跨越独立 Tokio task 轮询边界，不能让 pending executor、task queue 与 Agent 主循环的大型 async poll frame 在同一 worker 调用栈连续嵌套。边界必须随父 continuation 取消子任务并保持 durable action、batch、run/session 身份及恢复防重语义；当前使用 `JoinSet` 承担结构化取消。CI 和生产均使用默认 worker 栈验证，不以提高 `RUST_MIN_STACK` 代替代码边界。
+- 2026-08-03 恢复执行补充约束：整个 pending action continuation、它进入的后台主循环，以及完成、取消或失败后 drain 同 Agent 后续队列时，都必须跨越独立 Tokio task 轮询边界，不能让 pending executor、task queue 与 Agent 主循环的大型 async poll frame 在同一 worker 调用栈连续嵌套。边界输入必须先装箱，避免泛型 helper 在真正 spawn 前仍把大型 future 保留在调用方 async frame；边界同时必须随父 continuation 取消子任务并保持 durable action、batch、run/session 身份及恢复防重语义，当前使用 boxed future 与 `JoinSet` 承担该约束。CI 和生产均使用默认 worker 栈验证，不以提高 `RUST_MIN_STACK` 代替代码边界。
 - 2026-07-18 起，同一 Runtime 文档的“V1.34 动态隔离子 Agent writeScopes 命令绕过封堵”作为 isolated child 的现行能力事实源。在 scope-aware OS sandbox 完成前，动态 child 无条件禁用 `project.verify / project.git_commit / command.exec / command.start / command.stdin / preview.start / agent.delegate / agent.spawn_isolated / project.restore / agent.schedule_ready / canvas.asset_generate / task.create / task.update / blackboard.write` 和全部 MCP；原生工具策略统一显示 `denied`，模板、项目 policy 与用户确认均不能放宽。保留固定只读 `command.run_limited`、同身份 `command.output_read / command.poll / command.terminate`、既有预览的 `preview.validate`，以及严格位于 `writeScopes` 内的 `file.write / file.patch / file.delete / project.patchset`。
 - V1.34 的新单动作在 confirmation 和 OS launcher 前拒绝；新多 action 原生 batch 只要含一个 denied member 就在独立 pending-action sidecar、confirmation、OS spawn、revision 和任何成员项目副作用前整批 abort，只保留 `aborted / nextActionIndex=0` batch 事实。旧 pending / approval / batch 真正进入执行器时仍重新应用当前 child 边界，旧 executing 未知结果继续进入既有 reconciliation。该安全收紧由恶意 sibling 写入、策略快照、batch、旧 pending 执行器重验和 isolated/mixed/collaboration/provider-batch 回归证明；不因本切片重跑已通过且 isolated mutation 为 0 的 V1.31/V1.32 外部 Provider suite。通用命令只有在后续 scope-aware OS sandbox 对所有后代强制同一 `writeScopes` 并通过独立决策与测试后才可重新评估开放。
 - 2026-07-18 起，同一 Runtime 文档的“V1.35 多 ready isolated all-join 原子认领与恢复”作为 `agent.run_status` 同父 run 多 group 认领的现行事实源。Runtime 按 `delegationGroupId` 排序并一次性预取全部 join 锁；任一后续锁忙时保持零 delivery mutation、零 claim sidecar。全锁就绪后，同一 action 的 durable claim journal 按 `prepared -> committed -> observed` 推进；部分 commit 或 Runner 恢复只能复用该 journal 幂等补齐。只认领可完整放入优先 `readyIsolatedJoins` 观察预算的有序前缀，未观察旧 claim 可由后续 action 完整重放，但不创建第二份 isolated claim。每个 claimed delivery 必须由匹配原 action/group 的 journal 覆盖；无 journal 的旧 delivery 每轮只迁移一个原 action，已有 journal 不得扩写或状态倒退，跨 action group 归属冲突失败关闭。成功 observation 写入 pending sidecar 后只能把本轮完整输出的 claim 标记 `observed`，任一未观察或无 journal claim 继续阻断 finalization；每个 group 审计按 `actionId + delegationGroupId` 唯一，并在 Agent DB 锁内修复 torn tail、全量核对后幂等追加。
diff --git a/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md b/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md
index 943e1857f..cf62e1db0 100644
--- a/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md
+++ b/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md
@@ -60,7 +60,7 @@ Linux 本机多用户并发开发时，`npm run dev` 和 `npm run dev:*` 单模
 
 AI 游戏创作客户端使用 `npm run agc`，开发态 game-chat 使用 `npm run agc:game-chat`。两个入口都先由 `apps/ai-game-creator-shell/scripts/start-tauri-dev.mjs` 在 Tauri CLI 启动前检查固定地址 `http://127.0.0.1:3080/`：只有端口空闲时才继续启动。现有 marker 只包含 API target，不能证明监听器属于当前 worktree；即使页面和 target 看似匹配，也不得复用已经存在的 3080。旧 worktree Vite、无响应监听器或非 AGC 服务一律在创建原生窗口前失败关闭，并提示先停止旧服务；启动器不擅自终止无法证明归属的进程。
 
-Tauri `beforeDevCommand` 默认与客户端构建并行，不能把上述检查只放在 `beforeDevCommand` 内：旧 3080 已就绪时，Tauri 可能先创建加载旧前端的窗口，随后配套后端才因代理不匹配退出。外层启动器会把 Tauri CLI 放入受控进程树；CLI 正常退出、启动失败或收到终止信号后，POSIX 先向保留的 PGID 发送 `SIGTERM`、有界等待后升级 `SIGKILL`，Windows 使用 `taskkill /PID <pid> /T /F`。配套后端和 Vite 仍由 `start-dev-stack.mjs` 各自持有，退出时同样有界收束，避免只剩客户端、Runner、Cargo 或旧订阅进程。排障时同时核对 3080 marker、`.app/dev-stack.json` 的实际 API URL 和进程 cwd；不要把“终端已返回”当成客户端及其 Runner 已退出的证据。
+Tauri `beforeDevCommand` 默认与客户端构建并行，不能把上述检查只放在 `beforeDevCommand` 内：旧 3080 已就绪时，Tauri 可能先创建加载旧前端的窗口，随后配套后端才因代理不匹配退出。外层启动器会把 Tauri CLI 放入受控进程树；CLI 正常退出、启动失败或收到终止信号后，POSIX 先向保留的 PGID 发送 `SIGTERM`、有界等待后升级 `SIGKILL`，Windows 使用 `taskkill /PID <pid> /T /F`。Linux 容器中的孤儿后代退出后可能暂时保留为 zombie，`kill(-PGID, 0)` 仍会返回成功；启动器必须结合 `/proc/<pid>/stat` 判断同组是否还存在非 zombie 成员，不能把等待 PID 1 回收误报为清理失败。配套后端和 Vite 仍由 `start-dev-stack.mjs` 各自持有，退出时同样有界收束，避免只剩客户端、Runner、Cargo 或旧订阅进程。排障时同时核对 3080 marker、`.app/dev-stack.json` 的实际 API URL 和进程 cwd；不要把“终端已返回”当成客户端及其 Runner 已退出的证据。
 
 Windows 本地 `npm run dev` / `npm run dev:api-server` / `npm run dev:bgfilter-worker` 会用空的 `RUSTC_WRAPPER` / `CARGO_BUILD_RUSTC_WRAPPER` 覆盖 `server-rs/.cargo/config.toml` 里的 `sccache`，从而直连真实 `rustc`。完整栈和 `dev:api-server` 把 API 与 BgFilter worker 作为一个 Rust 重启单元：源码变化时先停两个进程，再先启动并验活 worker、最后启动并验活 API，避免两个 `cargo run` 并发链接同一个 Windows 可执行文件。不要把 wrapper 绕过值写成 `rustc`；Cargo 会按 wrapper 协议调用 `rustc <真实rustc路径> - ...`，最终报 `multiple input filenames provided` 并导致 api-server 无法启动。排查本地启动失败时，先看 dev 日志是否出现该错误，再确认脚本注入的 wrapper 为空。
 
-- 
2.52.0


From d8064eff49f80fcf6b30113aa382f90ec2a24e93 Mon Sep 17 00:00:00 2001
From: menghao <mh18530625731@163.com>
Date: Mon, 3 Aug 2026 14:21:30 +0800
Subject: [PATCH 09/27] =?UTF-8?q?=E5=90=8C=E6=AD=A5=E8=87=AA=E4=B8=BB?=
 =?UTF-8?q?=E9=A6=96=E6=89=B9=E4=BB=BB=E5=8A=A1=E5=9B=BE=E6=B5=8B=E8=AF=95?=
 =?UTF-8?q?=E5=A4=B9=E5=85=B7?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

补齐可信 Supervisor 根任务与三 Leader 首批合同测试数据

更新视觉失败和 Ready 任务调度断言以匹配最新任务图

修复 Provider 重试恢复响应仍使用旧底层 Agent 合同的问题
---
 .../runtime_actions/autonomous_policy.rs      |  18 ++
 .../agent/runtime_driver/main_loop_tests.rs   |   8 +-
 .../collaboration/supervisor_planning.rs      | 202 ++++++------------
 .../src-tauri/src/tests/provider.rs           |  51 +++--
 .../tests/runtime_actions/action_execution.rs |   2 +-
 5 files changed, 124 insertions(+), 157 deletions(-)

diff --git a/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_actions/autonomous_policy.rs b/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_actions/autonomous_policy.rs
index 8c8c4f998..d2c62d7d5 100644
--- a/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_actions/autonomous_policy.rs
+++ b/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_actions/autonomous_policy.rs
@@ -1609,6 +1609,24 @@ mod tests {
         let root = temporary.path().join("project");
         init_local_game_project_at(&root, "manifest-dag-policy", "测试正式任务图等待")
             .expect("init manifest DAG policy project");
+        let session_id = resolve_agent_conversation_session_id_at(
+            &root,
+            GAME_CREATOR_PROJECT_SUPERVISOR_AGENT_ID,
+            None,
+            true,
+        )
+        .expect("resolve manifest DAG Supervisor session");
+        append_unique_game_creator_agent_runtime_pending_task(
+            &root,
+            GAME_CREATOR_PROJECT_SUPERVISOR_AGENT_ID,
+            &session_id,
+            "测试正式任务图等待",
+            "manifest-dag-policy-run",
+            AGENT_RUNTIME_SUPERVISOR_CLI_SOURCE,
+            Some(AGENT_RUNTIME_RUN_PROFILE_AUTONOMOUS_GAME_BUILD),
+            None,
+        )
+        .expect("queue trusted autonomous root task");
         assert!(!autonomous_manifest_dag_in_progress_at(&root).expect("read pending DAG"));
 
         update_manifest_task_status_at(
diff --git a/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_driver/main_loop_tests.rs b/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_driver/main_loop_tests.rs
index 98dfec582..6981f58f4 100644
--- a/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_driver/main_loop_tests.rs
+++ b/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_driver/main_loop_tests.rs
@@ -937,14 +937,16 @@ async fn missing_completed_visual_asset_fails_same_child_without_retry() {
         "missing visual output must fail the current logical task"
     );
 
-    assert!(schedule_autonomous_game_build_ready_tasks_at(
+    let scheduled_after_failure = schedule_autonomous_game_build_ready_tasks_at(
         &root,
         GAME_CREATOR_PROJECT_SUPERVISOR_AGENT_ID,
         PARENT_RUN_ID,
         1,
     )
-    .expect("repeat scheduling after visual failure")
-    .is_empty());
+    .expect("schedule other ready work after visual failure");
+    assert!(scheduled_after_failure
+        .iter()
+        .all(|scheduled| scheduled.state.agent_id != CHILD_ID));
     let records = read_all_game_creator_agent_runtime_tasks(&game_creator_agent_runtime_task_path(
         &root, CHILD_ID,
     ))
diff --git a/apps/ai-game-creator-shell/src-tauri/src/tests/collaboration/supervisor_planning.rs b/apps/ai-game-creator-shell/src-tauri/src/tests/collaboration/supervisor_planning.rs
index 641ce4acf..f2b2e0f69 100644
--- a/apps/ai-game-creator-shell/src-tauri/src/tests/collaboration/supervisor_planning.rs
+++ b/apps/ai-game-creator-shell/src-tauri/src/tests/collaboration/supervisor_planning.rs
@@ -300,55 +300,36 @@ async fn supervisor_autonomous_durable_batch_rejects_invalid_responsibilities_wi
     let AgentRuntimeProviderActionBatchPreparation::Ready(valid_batch) = preparation else {
         panic!("valid autonomous responsibilities must form a ready durable batch");
     };
-    assert_eq!(valid_batch.actions.len(), 2);
+    assert_eq!(valid_batch.actions.len(), 3);
     assert!(valid_batch.collaboration_contract.is_some());
     let valid_batch_id = valid_batch.batch_id.clone();
-    let mut quality_not_read_only = autonomous_initial_responsibility_actions_for_test(
-        "创建或修改 game/index.html，完成可直接试玩的游戏实现并执行静态验证。",
-        &["game/index.html"],
-        "直接修改 game/index.html，修复试玩阻塞并重新验证。",
-        &[],
-    );
-    quality_not_read_only[1].input["acceptanceCriteria"] = serde_json::json!([
-        "直接写入 game/index.html 修复试玩问题",
-        "修改后执行静态验证并交付新 revision"
-    ]);
+    let mut design_not_read_only = valid_autonomous_initial_responsibility_actions_for_test();
+    design_not_read_only[0].input["task"] = serde_json::json!("直接修改项目并完成首轮策划实现。");
+    design_not_read_only[0].input["acceptanceCriteria"] = serde_json::json!(["直接修改项目文件"]);
+    let mut design_with_artifacts = valid_autonomous_initial_responsibility_actions_for_test();
+    design_with_artifacts[0].input["expectedArtifacts"] =
+        serde_json::json!(["game/game_design.md"]);
+    let mut art_missing_spec = valid_autonomous_initial_responsibility_actions_for_test();
+    art_missing_spec[1].input["expectedArtifacts"] = serde_json::json!(["assets/art-preview.png"]);
+    let mut code_with_artifacts = valid_autonomous_initial_responsibility_actions_for_test();
+    code_with_artifacts[2].input["expectedArtifacts"] = serde_json::json!(["game/index.html"]);
 
     let invalid_cases = vec![
         (
-            "code-missing-game-index",
-            "game/index.html",
-            autonomous_initial_responsibility_actions_for_test(
-                "创建可直接试玩的游戏实现并执行静态验证。",
-                &["game/main.js"],
-                "只读验收 game/index.html 的可玩性；不要修改任何项目文件。",
-                &[],
-            ),
+            "design-not-read-only",
+            "design-director",
+            design_not_read_only,
         ),
         (
-            "code-read-only",
-            "code-prototype",
-            autonomous_initial_responsibility_actions_for_test(
-                "只读检查 game/index.html，不要修改任何项目文件。",
-                &["game/index.html"],
-                "只读验收 game/index.html 的可玩性；不要修改任何项目文件。",
-                &[],
-            ),
-        ),
-        (
-            "quality-not-read-only",
-            "quality-review",
-            quality_not_read_only,
-        ),
-        (
-            "quality-with-artifacts",
+            "design-with-artifacts",
             "expectedArtifacts",
-            autonomous_initial_responsibility_actions_for_test(
-                "创建或修改 game/index.html，完成可直接试玩的游戏实现并执行静态验证。",
-                &["game/index.html"],
-                "只读验收 game/index.html 的可玩性；不要修改任何项目文件。",
-                &["game/index.html"],
-            ),
+            design_with_artifacts,
+        ),
+        ("art-missing-spec", "assets/art-spec.png", art_missing_spec),
+        (
+            "code-with-artifacts",
+            "expectedArtifacts",
+            code_with_artifacts,
         ),
     ];
     for (case_name, expected_error, actions) in invalid_cases {
@@ -389,12 +370,7 @@ async fn supervisor_autonomous_durable_batch_rejects_invalid_responsibilities_wi
     rewrite_autonomous_responsibility_batch_actions_for_test(
         &root,
         &mut legacy_v2_batch,
-        autonomous_initial_responsibility_actions_for_test(
-            "创建或修改 game/index.html，完成可直接试玩的游戏实现并执行静态验证。",
-            &["game/index.html"],
-            "直接修改 game/index.html，修复试玩阻塞并重新验证。",
-            &[],
-        ),
+        valid_autonomous_initial_responsibility_actions_for_test(),
     );
     let legacy_v2_schema = "game-creator-provider-action-batch.v2";
     legacy_v2_batch.schema_version = legacy_v2_schema.to_string();
@@ -600,68 +576,37 @@ async fn autonomous_game_build_repairs_supervisor_failed_playtest_stall_into_mut
     fs::remove_dir_all(root).ok();
 }
 
-fn autonomous_initial_responsibility_actions_for_test(
-    code_task: &str,
-    code_artifacts: &[&str],
-    quality_task: &str,
-    quality_artifacts: &[&str],
-) -> Vec<AgentRuntimeToolAction> {
+fn valid_autonomous_initial_responsibility_actions_for_test() -> Vec<AgentRuntimeToolAction> {
     vec![
-        AgentRuntimeToolAction {
-            tool: "agent.delegate".to_string(),
-            reason: Some("委派程序 Agent 形成可玩入口".to_string()),
-            input: serde_json::json!({
-                "agentId": "code-prototype",
-                "task": code_task,
-                "acceptanceCriteria": [
-                    "game/index.html 必须形成可直接试玩的完整入口",
-                    "程序交付必须完成当前 revision 的静态验证"
-                ],
-                "expectedArtifacts": code_artifacts,
-                "repairOfDelegationId": null,
-                "runId": null
-            }),
-        },
-        AgentRuntimeToolAction {
-            tool: "agent.delegate".to_string(),
-            reason: Some("委派质量 Agent 独立只读验收".to_string()),
-            input: serde_json::json!({
-                "agentId": "quality-review",
-                "task": quality_task,
-                "acceptanceCriteria": [
-                    "只读核对可玩性、交互闭环和阻塞问题",
-                    "返回可追溯的验收结论，不修改项目文件"
-                ],
-                "expectedArtifacts": quality_artifacts,
-                "repairOfDelegationId": null,
-                "runId": null
-            }),
-        },
+        autonomous_initial_leader_responsibility_action_for_test("design-director", &[]),
+        autonomous_initial_leader_responsibility_action_for_test(
+            "art-director",
+            &["assets/art-spec.png"],
+        ),
+        autonomous_initial_leader_responsibility_action_for_test("code-director", &[]),
     ]
 }
 
-fn valid_autonomous_initial_responsibility_actions_for_test() -> Vec<AgentRuntimeToolAction> {
-    autonomous_initial_responsibility_actions_for_test(
-        "创建或修改 game/index.html，完成可直接试玩的游戏实现并执行静态验证。",
-        &["game/index.html"],
-        "只读验收 game/index.html 的可玩性与交互闭环；不要修改任何项目文件。",
-        &[],
-    )
-}
-
-fn autonomous_art_director_responsibility_action_for_test(
+fn autonomous_initial_leader_responsibility_action_for_test(
+    agent_id: &str,
     expected_artifacts: &[&str],
 ) -> AgentRuntimeToolAction {
+    let read_only = matches!(agent_id, "design-director" | "code-director");
     AgentRuntimeToolAction {
         tool: "agent.delegate".to_string(),
-        reason: Some("委派美术总监生成统一视觉规范图".to_string()),
+        reason: Some("建立首批 Leader 专业规划".to_string()),
         input: serde_json::json!({
-            "agentId": "art-director",
-            "task": "生成项目统一视觉规范图并写入项目资产目录。",
-            "acceptanceCriteria": [
-                "使用画布生成接口产出后续 UI 与图集共用的规范图",
-                "生成结果必须登记为项目本地 icon-spec 资产"
-            ],
+            "agentId": agent_id,
+            "task": if read_only {
+                format!("由 {agent_id} 只读完成首轮专业规划，不得修改项目")
+            } else {
+                "生成首轮统一视觉规范图供后续专业 Agent 使用".to_string()
+            },
+            "acceptanceCriteria": if read_only {
+                serde_json::json!(["只读输出专业规划，不得修改项目文件"])
+            } else {
+                serde_json::json!(["生成并登记统一视觉规范图"])
+            },
             "expectedArtifacts": expected_artifacts,
             "repairOfDelegationId": null,
             "runId": null
@@ -713,9 +658,7 @@ async fn supervisor_autonomous_initial_art_director_requires_canonical_art_spec_
     )
     .expect("start autonomous Supervisor runtime");
     let mut actions = valid_autonomous_initial_responsibility_actions_for_test();
-    actions.push(autonomous_art_director_responsibility_action_for_test(&[
-        "assets/art-preview.png",
-    ]));
+    actions[1].input["expectedArtifacts"] = serde_json::json!(["assets/art-preview.png"]);
     let plan = supervisor_collaboration_plan_for_test(actions);
     let revision = read_game_creator_agent_runtime_project_revision(&root)
         .expect("read art contract project revision");
@@ -834,40 +777,21 @@ async fn supervisor_autonomous_initial_responsibilities_reject_invalid_plans_bef
     )
     .expect("start autonomous Supervisor runtime");
 
-    let code_missing_game_index = autonomous_initial_responsibility_actions_for_test(
-        "创建可直接试玩的游戏实现并执行静态验证。",
-        &["game/main.js"],
-        "只读验收 game/index.html 的可玩性；不要修改任何项目文件。",
-        &[],
-    );
-    let code_read_only = autonomous_initial_responsibility_actions_for_test(
-        "只读检查 game/index.html，不要修改任何项目文件。",
-        &["game/index.html"],
-        "只读验收 game/index.html 的可玩性；不要修改任何项目文件。",
-        &[],
-    );
-    let mut quality_not_read_only = autonomous_initial_responsibility_actions_for_test(
-        "创建或修改 game/index.html，完成可直接试玩的游戏实现并执行静态验证。",
-        &["game/index.html"],
-        "直接修改 game/index.html，修复试玩阻塞并重新验证。",
-        &[],
-    );
-    quality_not_read_only[1].input["acceptanceCriteria"] = serde_json::json!([
-        "直接写入 game/index.html 修复试玩问题",
-        "修改后执行静态验证并交付新 revision"
-    ]);
-    let quality_with_artifacts = autonomous_initial_responsibility_actions_for_test(
-        "创建或修改 game/index.html，完成可直接试玩的游戏实现并执行静态验证。",
-        &["game/index.html"],
-        "只读验收 game/index.html 的可玩性；不要修改任何项目文件。",
-        &["game/index.html"],
-    );
     let valid = valid_autonomous_initial_responsibility_actions_for_test();
+    let mut missing_design = valid.clone();
+    missing_design.remove(0);
+    let mut design_not_read_only = valid.clone();
+    design_not_read_only[0].input["task"] = serde_json::json!("直接修改项目完成策划实现");
+    design_not_read_only[0].input["acceptanceCriteria"] = serde_json::json!(["直接修改项目文件"]);
+    let mut art_missing_spec = valid.clone();
+    art_missing_spec[1].input["expectedArtifacts"] = serde_json::json!(["assets/art-preview.png"]);
+    let mut code_with_artifacts = valid.clone();
+    code_with_artifacts[2].input["expectedArtifacts"] = serde_json::json!(["game/index.html"]);
     let responses = [
-        ("code-missing-game-index", &code_missing_game_index),
-        ("code-read-only", &code_read_only),
-        ("quality-not-read-only", &quality_not_read_only),
-        ("quality-with-artifacts", &quality_with_artifacts),
+        ("missing-design", &missing_design),
+        ("design-not-read-only", &design_not_read_only),
+        ("art-missing-spec", &art_missing_spec),
+        ("code-with-artifacts", &code_with_artifacts),
         ("valid-responsibilities", &valid),
     ]
     .into_iter()
@@ -904,7 +828,13 @@ async fn supervisor_autonomous_initial_responsibilities_reject_invalid_plans_bef
     .await
     .expect("repair invalid initial responsibilities")
     .expect("valid initial responsibility plan");
-    assert_eq!(plan.actions, valid);
+    let mut expected_valid = valid.clone();
+    expected_valid.sort_by(|left, right| {
+        left.input["agentId"]
+            .as_str()
+            .cmp(&right.input["agentId"].as_str())
+    });
+    assert_eq!(plan.actions, expected_valid);
     assert!(plan.response.is_empty());
 
     let requests = (0..5)
diff --git a/apps/ai-game-creator-shell/src-tauri/src/tests/provider.rs b/apps/ai-game-creator-shell/src-tauri/src/tests/provider.rs
index 4f098396f..8c10a9fb5 100644
--- a/apps/ai-game-creator-shell/src-tauri/src/tests/provider.rs
+++ b/apps/ai-game-creator-shell/src-tauri/src/tests/provider.rs
@@ -4922,24 +4922,36 @@ async fn provider_transient_retry_autonomous_upstream_400_retries_with_bounded_b
         .expect("project init");
     let delegate_function =
         native_runtime_function_name("agent.delegate").expect("delegate function");
-    let code_arguments = serde_json::json!({
-        "reason": "委派可玩原型实现",
+    let design_arguments = serde_json::json!({
+        "reason": "委派策划 Leader",
         "input": {
-            "agentId": "code-prototype",
-            "task": "实现可直接试玩的游戏原型",
-            "acceptanceCriteria": ["项目能够启动并完成最小玩法闭环"],
-            "expectedArtifacts": ["game/index.html"],
+            "agentId": "design-director",
+            "task": "只读拆解首轮玩法目标和专业分工，不得修改项目",
+            "acceptanceCriteria": ["只读输出策划规划，不得修改项目文件"],
+            "expectedArtifacts": [],
             "repairOfDelegationId": null,
             "runId": null
         }
     })
     .to_string();
-    let quality_arguments = serde_json::json!({
-        "reason": "委派独立质量评审",
+    let art_arguments = serde_json::json!({
+        "reason": "委派美术 Leader",
         "input": {
-            "agentId": "quality-review",
-            "task": "只读评审可玩性与闯关闭环，不要修改任何项目文件",
-            "acceptanceCriteria": ["只读给出阻塞试玩的问题和验收结论"],
+            "agentId": "art-director",
+            "task": "生成首轮统一视觉规范图供后续专业 Agent 使用",
+            "acceptanceCriteria": ["生成并登记统一视觉规范图"],
+            "expectedArtifacts": ["assets/art-spec.png"],
+            "repairOfDelegationId": null,
+            "runId": null
+        }
+    })
+    .to_string();
+    let code_arguments = serde_json::json!({
+        "reason": "委派程序 Leader",
+        "input": {
+            "agentId": "code-director",
+            "task": "只读拆解首轮程序实现边界，不得修改项目",
+            "acceptanceCriteria": ["只读输出程序规划，不得修改项目文件"],
             "expectedArtifacts": [],
             "repairOfDelegationId": null,
             "runId": null
@@ -4947,16 +4959,21 @@ async fn provider_transient_retry_autonomous_upstream_400_retries_with_bounded_b
     })
     .to_string();
     let recovered_response = native_agent_tool_plan_chat_response_with_calls(vec![
+        (
+            "call-autonomous-upstream-400-design",
+            delegate_function.as_str(),
+            design_arguments,
+        ),
+        (
+            "call-autonomous-upstream-400-art",
+            delegate_function.as_str(),
+            art_arguments,
+        ),
         (
             "call-autonomous-upstream-400-code",
             delegate_function.as_str(),
             code_arguments,
         ),
-        (
-            "call-autonomous-upstream-400-quality",
-            delegate_function.as_str(),
-            quality_arguments,
-        ),
     ]);
     let (request_notice_sender, request_notice_receiver) = mpsc::channel();
     let base_url = spawn_mock_llm_upstream_400_then_raw_response(
@@ -5042,7 +5059,7 @@ async fn provider_transient_retry_autonomous_upstream_400_retries_with_bounded_b
     assert!(request_notice_receiver
         .recv_timeout(Duration::from_millis(100))
         .is_err());
-    assert_eq!(plan.actions.len(), 2);
+    assert_eq!(plan.actions.len(), 3);
     assert!(plan
         .actions
         .iter()
diff --git a/apps/ai-game-creator-shell/src-tauri/src/tests/runtime_actions/action_execution.rs b/apps/ai-game-creator-shell/src-tauri/src/tests/runtime_actions/action_execution.rs
index cd234fa8e..c138e990a 100644
--- a/apps/ai-game-creator-shell/src-tauri/src/tests/runtime_actions/action_execution.rs
+++ b/apps/ai-game-creator-shell/src-tauri/src/tests/runtime_actions/action_execution.rs
@@ -707,7 +707,7 @@ async fn background_agent_runtime_can_schedule_ready_manifest_tasks() {
     ));
 
     let scheduled =
-        schedule_game_creator_agent_ready_tasks_at(&root, 0).expect("schedule ready tasks");
+        schedule_game_creator_agent_ready_tasks_at(&root, 1).expect("schedule one ready task");
     assert_eq!(scheduled.len(), 1);
     assert_eq!(scheduled[0].state.agent_id, "design-director");
     assert_eq!(scheduled[0].state.source, "agent-ready-task-scheduler");
-- 
2.52.0


From 7339bb5da154c3d972e6f6c0dbf3e6f54f8acca7 Mon Sep 17 00:00:00 2001
From: menghao <mh18530625731@163.com>
Date: Mon, 3 Aug 2026 15:35:54 +0800
Subject: [PATCH 10/27] =?UTF-8?q?=E6=9A=82=E7=BC=93=E8=B5=84=E6=BA=90?=
 =?UTF-8?q?=E5=8D=A1=E6=8B=96=E5=8A=A8=E5=B9=B6=E7=BB=9F=E4=B8=80=E8=B5=84?=
 =?UTF-8?q?=E6=BA=90=E7=AE=A1=E7=90=86=E5=90=88=E5=90=8C?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

移除资源卡 Pointer 拖动入口并保留点击详情
改写交互与布局测试，覆盖指针不改坐标且不提交 CAS
同步工作台 PRD、技术方案和项目决策记录
---
 apps/ai-game-creator-shell/src/styles.css     |  14 +-
 .../src/view/project-development/index.tsx    | 267 +----------
 .../useProjectResourceCanvasLayout.ts         |   6 +-
 .../appSurface/project-development.suite.ts   | 451 +++---------------
 .../useProjectResourceCanvasLayout.test.ts    |  10 +-
 ...AI游戏创作】项目开发工作台PRD-2026-07-20.md |  54 ++-
 .../shared-memory/decision-log.md             |  15 +-
 ...�案】AI游戏创作智能体App实施计划-2026-06-24.md |  22 +-
 8 files changed, 130 insertions(+), 709 deletions(-)

diff --git a/apps/ai-game-creator-shell/src/styles.css b/apps/ai-game-creator-shell/src/styles.css
index 75f08c70f..3014f539e 100644
--- a/apps/ai-game-creator-shell/src/styles.css
+++ b/apps/ai-game-creator-shell/src/styles.css
@@ -4041,11 +4041,10 @@ iframe.preview-frame {
   color: #4e382f;
   text-align: left;
   box-shadow: 0 6px 18px rgb(96 62 47 / 6%);
-  cursor: grab;
-  touch-action: none;
+  cursor: pointer;
+  touch-action: manipulation;
   user-select: none;
   transform: translate3d(var(--resource-x, 0), var(--resource-y, 0), 0);
-  will-change: transform;
 }
 
 .game-resource-card:hover,
@@ -4056,15 +4055,6 @@ iframe.preview-frame {
   box-shadow: 0 8px 22px rgb(195 105 62 / 15%);
 }
 
-.game-resource-card.is-dragging {
-  z-index: 2;
-  opacity: 0.72;
-  cursor: grabbing;
-  box-shadow:
-    0 12px 28px rgb(195 105 62 / 24%),
-    0 0 0 2px rgb(213 123 81 / 18%);
-}
-
 .game-resource-card.is-relation-upstream,
 .game-resource-card.is-relation-downstream,
 .game-resource-card.is-relation-both {
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 99870dfe7..0186d1110 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
@@ -42,14 +42,7 @@ import {
   LocalGamePreviewFrame,
   resolveEmbeddedPreviewUrl,
 } from '../../features/project-workspace/LocalGamePreviewFrame';
-import {
-  RESOURCE_CANVAS_CARD_HEIGHT,
-  RESOURCE_CANVAS_CARD_WIDTH,
-  RESOURCE_CANVAS_COLUMN_GAP,
-  RESOURCE_CANVAS_DRAG_THRESHOLD,
-  RESOURCE_CANVAS_ROW_GAP,
-  resourceCanvasSectionExtent,
-} from './resourceCanvasLayoutModel';
+import { resourceCanvasSectionExtent } from './resourceCanvasLayoutModel';
 import {
   EMPTY_PROJECT_RESOURCE_GRAPH,
   normalizeProjectResourceGraph,
@@ -58,10 +51,7 @@ import {
   type ProjectResourceGraphNodeInput,
   type ProjectResourceGraphReadModel,
 } from './resourceDependencyGraphModel';
-import {
-  ResourceDependencyOverlay,
-  type ResourceDependencyOverlayHandle,
-} from './ResourceDependencyOverlay';
+import { ResourceDependencyOverlay } from './ResourceDependencyOverlay';
 import { useProjectResourceCanvasLayout } from './useProjectResourceCanvasLayout';
 
 type AttachmentResult = {
@@ -82,22 +72,6 @@ type Point = {
   y: number;
 };
 
-type ResourceCardDrag = {
-  pointerId: number;
-  resourceId: string;
-  section: ResourceCategory;
-  startClientX: number;
-  startClientY: number;
-  startX: number;
-  startY: number;
-  moved: boolean;
-  element: HTMLButtonElement;
-  plane: HTMLElement | null;
-  planeBaseWidth: number;
-  planeBaseHeight: number;
-  visualGutter: number;
-};
-
 type ProjectResource = {
   id: string;
   category: ResourceCategory;
@@ -455,41 +429,28 @@ function summarizeAgent(
 const ResourceCard = memo(function ResourceCard({
   resource,
   selected,
-  dragging,
   relationState,
   x,
   y,
   onSelect,
-  onPointerDown,
-  onPointerMove,
-  onPointerUp,
-  onPointerCancel,
 }: {
   resource: ProjectResource;
   selected: boolean;
-  dragging: boolean;
   relationState: 'upstream' | 'downstream' | 'both' | null;
   x: number;
   y: number;
   onSelect: (resourceId: string) => void;
-  onPointerDown: (
-    event: ReactPointerEvent<HTMLButtonElement>,
-    resource: ProjectResource,
-  ) => void;
-  onPointerMove: (event: ReactPointerEvent<HTMLButtonElement>) => void;
-  onPointerUp: (event: ReactPointerEvent<HTMLButtonElement>) => void;
-  onPointerCancel: (event: ReactPointerEvent<HTMLButtonElement>) => void;
 }) {
   const Icon = categoryIcons[resource.category];
   return (
     <button
       type="button"
       className={`game-resource-card${selected ? ' is-selected' : ''}${
-        dragging ? ' is-dragging' : ''
-      }${relationState ? ` is-relation-${relationState}` : ''}`}
+        relationState ? ` is-relation-${relationState}` : ''
+      }`}
       aria-pressed={selected}
       data-resource-id={resource.id}
-      title="拖动调整资源位置"
+      title="打开资源详情"
       style={
         {
           '--resource-x': `${x}px`,
@@ -497,10 +458,6 @@ const ResourceCard = memo(function ResourceCard({
         } as CSSProperties
       }
       onClick={() => onSelect(resource.id)}
-      onPointerDown={(event) => onPointerDown(event, resource)}
-      onPointerMove={onPointerMove}
-      onPointerUp={onPointerUp}
-      onPointerCancel={onPointerCancel}
     >
       <span className="game-resource-card-icon">
         <Icon size={20} aria-hidden="true" />
@@ -534,9 +491,6 @@ export default function ProjectDevelopmentView({
   const [showAllAgentGroups, setShowAllAgentGroups] = useState(false);
   const [runPlaying, setRunPlaying] = useState(false);
   const [activeSlice, setActiveSlice] = useState(0);
-  const [draggedResourceId, setDraggedResourceId] = useState<string | null>(
-    null,
-  );
   const [resourceDialogPosition, setResourceDialogPosition] =
     useState<Point | null>(null);
   const [imagePreview, setImagePreview] = useState<ImagePreviewState>({
@@ -547,14 +501,6 @@ export default function ProjectDevelopmentView({
   const stageRef = useRef<HTMLElement>(null);
   const dockRef = useRef<HTMLElement>(null);
   const resourceDialogRef = useRef<HTMLElement>(null);
-  const resourceCardDragRef = useRef<ResourceCardDrag | null>(null);
-  const resourceDependencyOverlayRef =
-    useRef<ResourceDependencyOverlayHandle>(null);
-  const pendingResourceDragPreviewRef = useRef<
-    (Point & { resourceId: string }) | null
-  >(null);
-  const resourceDragFrameRef = useRef<number | null>(null);
-  const suppressResourceClickRef = useRef<string | null>(null);
   const resourceDialogDragRef = useRef<{
     pointerId: number;
     offsetX: number;
@@ -706,7 +652,6 @@ export default function ProjectDevelopmentView({
     layout: resourceLayout,
     notice: resourceLayoutNotice,
     saving: resourceLayoutSaving,
-    commitPosition: commitResourcePosition,
   } = useProjectResourceCanvasLayout({
     projectPath,
     projectId: manifest.projectId,
@@ -826,68 +771,6 @@ export default function ProjectDevelopmentView({
     approvalOptions.find((option) => option.id === approvalMode)?.label ??
     '严格审批';
 
-  const applyResourceDragPreview = useCallback(
-    (preview: Point & { resourceId: string }) => {
-      const drag = resourceCardDragRef.current;
-      if (!drag || drag.resourceId !== preview.resourceId) {
-        return;
-      }
-      drag.element.style.setProperty('--resource-x', `${preview.x}px`);
-      drag.element.style.setProperty('--resource-y', `${preview.y}px`);
-      if (drag.plane) {
-        drag.plane.style.width = `${Math.max(
-          drag.planeBaseWidth,
-          preview.x +
-            RESOURCE_CANVAS_CARD_WIDTH +
-            RESOURCE_CANVAS_COLUMN_GAP +
-            drag.visualGutter,
-        )}px`;
-        drag.plane.style.height = `${Math.max(
-          drag.planeBaseHeight,
-          preview.y +
-            RESOURCE_CANVAS_CARD_HEIGHT +
-            RESOURCE_CANVAS_ROW_GAP,
-        )}px`;
-      }
-      resourceDependencyOverlayRef.current?.updateDragPreview(preview);
-    },
-    [],
-  );
-
-  const scheduleResourceDragPreview = useCallback(
-    (preview: Point & { resourceId: string }) => {
-      pendingResourceDragPreviewRef.current = preview;
-      if (resourceDragFrameRef.current !== null) {
-        return;
-      }
-      resourceDragFrameRef.current = window.requestAnimationFrame(() => {
-        resourceDragFrameRef.current = null;
-        const pending = pendingResourceDragPreviewRef.current;
-        pendingResourceDragPreviewRef.current = null;
-        if (pending) {
-          applyResourceDragPreview(pending);
-        }
-      });
-    },
-    [applyResourceDragPreview],
-  );
-
-  const clearScheduledResourceDragPreview = useCallback(() => {
-    pendingResourceDragPreviewRef.current = null;
-    if (resourceDragFrameRef.current !== null) {
-      window.cancelAnimationFrame(resourceDragFrameRef.current);
-      resourceDragFrameRef.current = null;
-    }
-  }, []);
-
-  useEffect(
-    () => () => {
-      clearScheduledResourceDragPreview();
-      resourceDependencyOverlayRef.current?.clearDragPreview();
-    },
-    [clearScheduledResourceDragPreview],
-  );
-
   useEffect(() => {
     if (embeddedPreviewUrl) {
       setMode('run');
@@ -896,11 +779,7 @@ export default function ProjectDevelopmentView({
 
   useEffect(() => {
     setSelectedResourceId(null);
-    resourceCardDragRef.current = null;
-    clearScheduledResourceDragPreview();
-    resourceDependencyOverlayRef.current?.clearDragPreview();
-    setDraggedResourceId(null);
-  }, [clearScheduledResourceDragPreview, projectPath]);
+  }, [projectPath]);
 
   useEffect(() => {
     if (!selectedResourceId) {
@@ -1026,135 +905,9 @@ export default function ProjectDevelopmentView({
   }, [clampResourceDialogPosition, selectedResource]);
 
   const handleResourceSelect = useCallback((resourceId: string) => {
-    if (suppressResourceClickRef.current === resourceId) {
-      suppressResourceClickRef.current = null;
-      return;
-    }
     setSelectedResourceId(resourceId);
   }, []);
 
-  const handleResourceCardPointerDown = useCallback(
-    (
-      event: ReactPointerEvent<HTMLButtonElement>,
-      resource: ProjectResource,
-    ) => {
-      if (event.button !== 0) {
-        return;
-      }
-      const position = resourcePositionById.get(resource.id);
-      if (!position || position.section !== resource.category) {
-        return;
-      }
-      clearScheduledResourceDragPreview();
-      const plane = event.currentTarget.parentElement;
-      resourceCardDragRef.current = {
-        pointerId: event.pointerId,
-        resourceId: resource.id,
-        section: resource.category,
-        startClientX: event.clientX,
-        startClientY: event.clientY,
-        startX: position.x,
-        startY: position.y,
-        moved: false,
-        element: event.currentTarget,
-        plane,
-        planeBaseWidth:
-          Number.parseFloat(plane?.style.width ?? '') ||
-          plane?.getBoundingClientRect().width ||
-          0,
-        planeBaseHeight:
-          Number.parseFloat(plane?.style.height ?? '') ||
-          plane?.getBoundingClientRect().height ||
-          0,
-        visualGutter:
-          sortMode === 'dependency' ? RESOURCE_DEPENDENCY_VISUAL_GUTTER : 0,
-      };
-      event.currentTarget.setPointerCapture?.(event.pointerId);
-    },
-    [clearScheduledResourceDragPreview, resourcePositionById, sortMode],
-  );
-
-  const handleResourceCardPointerMove = useCallback(
-    (event: ReactPointerEvent<HTMLButtonElement>) => {
-      const drag = resourceCardDragRef.current;
-      if (!drag || drag.pointerId !== event.pointerId) {
-        return;
-      }
-      const deltaX = event.clientX - drag.startClientX;
-      const deltaY = event.clientY - drag.startClientY;
-      if (
-        !drag.moved &&
-        Math.hypot(deltaX, deltaY) < RESOURCE_CANVAS_DRAG_THRESHOLD
-      ) {
-        return;
-      }
-      if (!drag.moved) {
-        drag.moved = true;
-        setDraggedResourceId(drag.resourceId);
-      }
-      scheduleResourceDragPreview({
-        resourceId: drag.resourceId,
-        x: Math.max(0, drag.startX + deltaX),
-        y: Math.max(0, drag.startY + deltaY),
-      });
-      event.preventDefault();
-    },
-    [scheduleResourceDragPreview],
-  );
-
-  const handleResourceCardPointerEnd = useCallback(
-    (event: ReactPointerEvent<HTMLButtonElement>, cancelled: boolean) => {
-      const drag = resourceCardDragRef.current;
-      if (!drag || drag.pointerId !== event.pointerId) {
-        return;
-      }
-      clearScheduledResourceDragPreview();
-      const finalPreview = {
-        resourceId: drag.resourceId,
-        x: cancelled
-          ? drag.startX
-          : Math.max(0, drag.startX + event.clientX - drag.startClientX),
-        y: cancelled
-          ? drag.startY
-          : Math.max(0, drag.startY + event.clientY - drag.startClientY),
-      };
-      applyResourceDragPreview(finalPreview);
-      resourceCardDragRef.current = null;
-      if (event.currentTarget.hasPointerCapture?.(event.pointerId)) {
-        event.currentTarget.releasePointerCapture?.(event.pointerId);
-      }
-      if (drag.moved && !cancelled) {
-        suppressResourceClickRef.current = drag.resourceId;
-        commitResourcePosition(
-          drag.resourceId,
-          drag.section,
-          finalPreview.x,
-          finalPreview.y,
-        );
-        const overlay = resourceDependencyOverlayRef.current;
-        window.requestAnimationFrame(() => overlay?.clearDragPreview());
-      } else {
-        resourceDependencyOverlayRef.current?.clearDragPreview();
-      }
-      setDraggedResourceId(null);
-    },
-    [
-      applyResourceDragPreview,
-      clearScheduledResourceDragPreview,
-      commitResourcePosition,
-    ],
-  );
-  const handleResourceCardPointerUp = useCallback(
-    (event: ReactPointerEvent<HTMLButtonElement>) =>
-      handleResourceCardPointerEnd(event, false),
-    [handleResourceCardPointerEnd],
-  );
-  const handleResourceCardPointerCancel = useCallback(
-    (event: ReactPointerEvent<HTMLButtonElement>) =>
-      handleResourceCardPointerEnd(event, true),
-    [handleResourceCardPointerEnd],
-  );
-
   function handleResourceDialogPointerDown(
     event: ReactPointerEvent<HTMLElement>,
   ) {
@@ -1328,7 +1081,6 @@ export default function ProjectDevelopmentView({
                 <div className="game-resource-canvas-content">
                   {sortMode === 'dependency' ? (
                     <ResourceDependencyOverlay
-                      ref={resourceDependencyOverlayRef}
                       key={`${projectPath}:${manifest.projectId}`}
                       graph={resourceGraph}
                       positions={resourceLayout.positions}
@@ -1403,17 +1155,10 @@ export default function ProjectDevelopmentView({
                                   key={resource.id}
                                   resource={resource}
                                   selected={resource.id === selectedResourceId}
-                                  dragging={resource.id === draggedResourceId}
                                   relationState={relationState}
                                   x={position.x}
                                   y={position.y}
                                   onSelect={handleResourceSelect}
-                                  onPointerDown={handleResourceCardPointerDown}
-                                  onPointerMove={handleResourceCardPointerMove}
-                                  onPointerUp={handleResourceCardPointerUp}
-                                  onPointerCancel={
-                                    handleResourceCardPointerCancel
-                                  }
                                 />
                               );
                             })}
diff --git a/apps/ai-game-creator-shell/src/view/project-development/useProjectResourceCanvasLayout.ts b/apps/ai-game-creator-shell/src/view/project-development/useProjectResourceCanvasLayout.ts
index 746ee88b8..66a6a6802 100644
--- a/apps/ai-game-creator-shell/src/view/project-development/useProjectResourceCanvasLayout.ts
+++ b/apps/ai-game-creator-shell/src/view/project-development/useProjectResourceCanvasLayout.ts
@@ -20,7 +20,7 @@ type LayoutNotice =
   | '布局读取失败，已使用当前会话布局'
   | '布局保存失败，已保留当前会话布局'
   | '布局保存失败，已恢复上次布局'
-  | '布局已在其他窗口更新，请重新拖动';
+  | '布局已在其他窗口更新';
 
 type LayoutScope = {
   key: string;
@@ -418,7 +418,7 @@ export function useProjectResourceCanvasLayout({
             enqueueResourceSyncRef.current(currentScope.epoch, nextRetry);
           }
           if (redragRequired || !willRetryResourceSync) {
-            setNotice('布局已在其他窗口更新，请重新拖动');
+            setNotice('布局已在其他窗口更新');
           }
         }
         rebuildOptimisticLayout(currentScope.epoch);
@@ -605,7 +605,7 @@ export function useProjectResourceCanvasLayout({
       return undefined;
     }
     if (
-      notice === '布局已在其他窗口更新，请重新拖动' &&
+      notice === '布局已在其他窗口更新' &&
       redragRequiredScopeEpochRef.current === scopeRef.current.epoch
     ) {
       return undefined;
diff --git a/apps/ai-game-creator-shell/tests/appSurface/project-development.suite.ts b/apps/ai-game-creator-shell/tests/appSurface/project-development.suite.ts
index 3979b83e7..ba3db4787 100644
--- a/apps/ai-game-creator-shell/tests/appSurface/project-development.suite.ts
+++ b/apps/ai-game-creator-shell/tests/appSurface/project-development.suite.ts
@@ -676,15 +676,15 @@ export function registerProjectWorkbenchFoundationTests() {
     expect(screen.getByRole('article', { name: /发布 Agent/ })).not.toBeNull();
   });
 
-  it('keeps project chrome out, moves resources by pointer, and contains text receipts in a dialog', () => {
+  it('keeps project chrome out and opens text receipts from non-draggable resource cards', () => {
     const manifest = createGameCreationAppManifest(
-      'workbench-resource-drag',
+      'workbench-resource-details',
       '不应显示的项目标题',
     );
     render(
       React.createElement(ProjectDevelopmentView, {
         projectName: '不应显示的项目标题',
-        projectPath: '/tmp/workbench-resource-drag',
+        projectPath: '/tmp/workbench-resource-details',
         manifest,
         attachments: [],
         recentRunStatus: null,
@@ -735,11 +735,12 @@ export function registerProjectWorkbenchFoundationTests() {
       screen.getByText('美术资源计划已完成，尚未生成或登记图片'),
     ).not.toBeNull();
 
-    const resourceCards = screen.getAllByTitle('拖动调整资源位置');
+    const resourceCards = screen.getAllByTitle('打开资源详情');
     const artReceiptCard = resourceCards.find((card) =>
       card.textContent?.includes('美术资源计划 Agent 文本回执'),
     );
     expect(artReceiptCard).not.toBeUndefined();
+    const originalStyle = artReceiptCard?.getAttribute('style');
     fireEvent.pointerDown(artReceiptCard!, {
       pointerId: 7,
       button: 0,
@@ -756,11 +757,18 @@ export function registerProjectWorkbenchFoundationTests() {
       clientX: 240,
       clientY: 32,
     });
-    expect(artReceiptCard?.getAttribute('style')).toContain(
-      '--resource-x: 240px',
+    fireEvent.pointerCancel(artReceiptCard!, { pointerId: 7 });
+    expect(artReceiptCard?.getAttribute('style')).toBe(originalStyle);
+    expect(artReceiptCard?.classList.contains('is-dragging')).toBe(false);
+    const styles = readFileSync(
+      resolve(process.cwd(), 'apps/ai-game-creator-shell/src/styles.css'),
+      'utf8',
     );
+    expect(styles).toMatch(
+      /\.game-resource-card\s*\{[^}]*cursor:\s*pointer[^}]*touch-action:\s*manipulation/s,
+    );
+    expect(styles).not.toMatch(/\.game-resource-card\.is-dragging/);
 
-    fireEvent.click(artReceiptCard!);
     fireEvent.click(artReceiptCard!);
     const receiptDialog = screen.getByRole('dialog', {
       name: '美术资源计划 Agent 文本回执',
@@ -780,7 +788,7 @@ export function registerProjectWorkbenchFoundationTests() {
     expect(receiptDialog.querySelector('strong')).not.toBeNull();
   });
 
-  it('renders, filters, highlights, moves, and destroys the resource dependency overlay', async () => {
+  it('renders, filters, highlights, and destroys the resource dependency overlay without pointer previews', async () => {
     const manifest = createGameCreationAppManifest(
       'workbench-resource-graph',
       '资源依赖图测试',
@@ -999,6 +1007,10 @@ export function registerProjectWorkbenchFoundationTests() {
       expect(path).not.toBeNull();
       return path?.getAttribute('d');
     });
+    const sourceStyle = sourceCard.getAttribute('style');
+    const layoutUpdatesBeforePointer = invoke.mock.calls.filter(
+      ([command]) => command === 'update_local_project_resource_canvas_layout',
+    ).length;
 
     fireEvent.pointerDown(sourceCard, {
       pointerId: 27,
@@ -1011,16 +1023,23 @@ export function registerProjectWorkbenchFoundationTests() {
       clientX: 72,
       clientY: 28,
     });
-    await waitFor(() => {
-      expect(
-        overlay.querySelector(referenceSelector)?.getAttribute('d'),
-      ).not.toBe(firstPath);
-    });
     fireEvent.pointerUp(sourceCard, {
       pointerId: 27,
       clientX: 72,
       clientY: 28,
     });
+    fireEvent.pointerCancel(sourceCard, { pointerId: 27 });
+    expect(sourceCard.getAttribute('style')).toBe(sourceStyle);
+    expect(sourceCard.classList.contains('is-dragging')).toBe(false);
+    expect(overlay.querySelector(referenceSelector)?.getAttribute('d')).toBe(
+      firstPath,
+    );
+    expect(
+      invoke.mock.calls.filter(
+        ([command]) =>
+          command === 'update_local_project_resource_canvas_layout',
+      ),
+    ).toHaveLength(layoutUpdatesBeforePointer);
 
     fireEvent.click(targetCard);
     await waitFor(() => {
@@ -1140,128 +1159,7 @@ export function registerProjectWorkbenchFoundationTests() {
     expect(layoutReads).toBe(1);
   });
 
-  it(
-    'keeps 4096 real resource cards out of React commits during preview frames',
-    async () => {
-      const projectId = 'workbench-resource-drag-performance';
-      const projectPath = '/tmp/workbench-resource-drag-performance';
-      const manifest = createGameCreationAppManifest(
-        projectId,
-        '资源拖动性能测试',
-      );
-      const agentResults = Array.from({ length: 4096 }, (_, index) => ({
-        agentId: 'design-foundation',
-        runId: `performance-run-${index}`,
-        label: `性能 Agent ${index}`,
-        title: `性能资源 ${index}`,
-        content: `性能正文 ${index}`,
-        updatedAt: index,
-      }));
-      let layoutRevision = 0;
-      const invoke = vi.fn(
-        async (command: string, args?: Record<string, unknown>) => {
-          if (command === 'read_local_project_resource_graph') {
-            return resourceGraphForInputs(args);
-          }
-          if (command === 'read_local_project_resource_canvas_layout') {
-            return {
-              schemaVersion: 'game-creator-resource-layout.v1',
-              projectId,
-              mode: 'dependency',
-              revision: layoutRevision,
-              positions: [],
-              updatedAt: 0,
-            };
-          }
-          if (command === 'update_local_project_resource_canvas_layout') {
-            layoutRevision += 1;
-            return {
-              status: 'updated',
-              layout: {
-                schemaVersion: 'game-creator-resource-layout.v1',
-                projectId,
-                mode: 'dependency',
-                revision: layoutRevision,
-                positions: args?.positions,
-                updatedAt: layoutRevision,
-              },
-            };
-          }
-          throw new Error(`unexpected invoke ${command}`);
-        },
-      );
-      window.__TAURI__ = { core: { invoke } };
-      const commits: string[] = [];
-
-      render(
-        React.createElement(
-          React.Profiler,
-          {
-            id: 'resource-workbench',
-            onRender: () => commits.push('commit'),
-          },
-          React.createElement(ProjectDevelopmentView, {
-            projectName: '资源拖动性能测试',
-            projectPath,
-            manifest,
-            attachments: [],
-            agentResults,
-            supervisor: React.createElement('div', null, '项目总控'),
-          }),
-        ),
-      );
-
-      const target = (await screen.findByText('性能资源 2048')).closest(
-        'button',
-      );
-      expect(target).not.toBeNull();
-      expect(document.querySelectorAll('.game-resource-card')).toHaveLength(
-        4096,
-      );
-      commits.length = 0;
-      let previewFrame: FrameRequestCallback | null = null;
-      const requestAnimationFrame = vi
-        .spyOn(window, 'requestAnimationFrame')
-        .mockImplementation((callback) => {
-          previewFrame = callback;
-          return 77;
-        });
-      const cancelAnimationFrame = vi
-        .spyOn(window, 'cancelAnimationFrame')
-        .mockImplementation(() => undefined);
-      try {
-        fireEvent.pointerDown(target!, {
-          pointerId: 88,
-          button: 0,
-          clientX: 20,
-          clientY: 30,
-        });
-        for (let index = 0; index < 100; index += 1) {
-          fireEvent.pointerMove(target!, {
-            pointerId: 88,
-            clientX: 40 + index,
-            clientY: 60 + index,
-          });
-        }
-        act(() => previewFrame?.(16));
-
-        expect(commits).toHaveLength(1);
-        expect(target?.getAttribute('style')).toContain('--resource-x: 119px');
-        expect(requestAnimationFrame).toHaveBeenCalledTimes(1);
-      } finally {
-        fireEvent.pointerCancel(target!, {
-          pointerId: 88,
-          clientX: 139,
-          clientY: 159,
-        });
-        requestAnimationFrame.mockRestore();
-        cancelAnimationFrame.mockRestore();
-      }
-    },
-    15_000,
-  );
-
-  it('persists a resource position with CAS and restores it after remount', async () => {
+  it('restores historical resource positions but never moves or persists them from pointer input', async () => {
     const projectId = 'workbench-layout-persistence';
     const projectPath = '/tmp/workbench-layout-persistence';
     const resourceId = 'agent-result:design-foundation:layout-result-run';
@@ -1276,7 +1174,7 @@ export function registerProjectWorkbenchFoundationTests() {
         updatedAt: 1,
       },
     ];
-    let persistedLayout: ProjectResourceCanvasLayout = {
+    const persistedLayout: ProjectResourceCanvasLayout = {
       schemaVersion: 'game-creator-resource-layout.v1',
       projectId,
       mode: 'dependency',
@@ -1301,21 +1199,7 @@ export function registerProjectWorkbenchFoundationTests() {
           return structuredClone(persistedLayout);
         }
         if (command === 'update_local_project_resource_canvas_layout') {
-          const input = args as {
-            expectedRevision: number;
-            positions: ProjectResourceCanvasPosition[];
-          };
-          expect(input.expectedRevision).toBe(persistedLayout.revision);
-          persistedLayout = {
-            ...persistedLayout,
-            revision: persistedLayout.revision + 1,
-            positions: structuredClone(input.positions),
-            updatedAt: persistedLayout.updatedAt + 1,
-          };
-          return {
-            status: 'updated',
-            layout: structuredClone(persistedLayout),
-          };
+          throw new Error('pointer input must not submit a manual layout CAS');
         }
         throw new Error(`unexpected invoke ${command}`);
       },
@@ -1342,6 +1226,10 @@ export function registerProjectWorkbenchFoundationTests() {
       expect(card?.getAttribute('style')).toContain('--resource-x: 12px');
       expect(card?.getAttribute('style')).toContain('--resource-y: 24px');
     });
+    const originalStyle = card?.getAttribute('style');
+    const layoutUpdatesBeforePointer = invoke.mock.calls.filter(
+      ([command]) => command === 'update_local_project_resource_canvas_layout',
+    ).length;
 
     fireEvent.pointerDown(card!, {
       pointerId: 11,
@@ -1359,259 +1247,34 @@ export function registerProjectWorkbenchFoundationTests() {
       clientX: 100,
       clientY: 60,
     });
-
-    await waitFor(() => {
-      expect(persistedLayout.revision).toBe(2);
-      expect(persistedLayout.positions).toContainEqual({
-        resourceId,
-        section: 'document',
-        x: 92,
-        y: 54,
-        manuallyPlaced: true,
-      });
-    });
-    expect(invoke).toHaveBeenCalledWith(
-      'update_local_project_resource_canvas_layout',
-      expect.objectContaining({
-        projectPath,
-        mode: 'dependency',
-        expectedRevision: 1,
-      }),
-    );
-
-    cleanup();
-    renderWorkbench();
-    const restoredCard = (
-      await screen.findByText('布局持久化回执')
-    ).closest('button');
-    await waitFor(() => {
-      expect(restoredCard?.getAttribute('style')).toContain(
-        '--resource-x: 92px',
-      );
-      expect(restoredCard?.getAttribute('style')).toContain(
-        '--resource-y: 54px',
-      );
-    });
-  });
-
-  it('loads the latest layout after a CAS conflict without replaying the drag', async () => {
-    const projectId = 'workbench-layout-conflict';
-    const projectPath = '/tmp/workbench-layout-conflict';
-    const resourceId = 'agent-result:design-foundation:conflict-result-run';
-    const manifest = createGameCreationAppManifest(projectId, '布局冲突测试');
-    const latestLayout: ProjectResourceCanvasLayout = {
-      schemaVersion: 'game-creator-resource-layout.v1',
-      projectId,
-      mode: 'dependency',
-      revision: 4,
-      positions: [
-        {
-          resourceId,
-          section: 'document',
-          x: 400,
-          y: 80,
-          manuallyPlaced: true,
-        },
-      ],
-      updatedAt: 400,
-    };
-    const invoke = vi.fn(
-      async (command: string, args?: Record<string, unknown>) => {
-      if (command === 'read_local_project_resource_graph') {
-        return resourceGraphForInputs(args);
-      }
-      if (command === 'read_local_project_resource_canvas_layout') {
-        return {
-          ...structuredClone(latestLayout),
-          revision: 3,
-          positions: [
-            {
-              ...latestLayout.positions[0],
-              x: 20,
-              y: 30,
-            },
-          ],
-        };
-      }
-      if (command === 'update_local_project_resource_canvas_layout') {
-        return { status: 'conflict', layout: structuredClone(latestLayout) };
-      }
-      throw new Error(`unexpected invoke ${command}`);
-      },
-    );
-    window.__TAURI__ = { core: { invoke } };
-
-    render(
-      React.createElement(ProjectDevelopmentView, {
-        projectName: '布局冲突测试',
-        projectPath,
-        manifest,
-        attachments: [],
-        agentResults: [
-          {
-            agentId: 'design-foundation',
-            runId: 'conflict-result-run',
-            label: '玩法策划 Agent',
-            title: '布局冲突回执',
-            content: '布局冲突正文',
-            updatedAt: 1,
-          },
-        ],
-        supervisor: React.createElement('div', null, '项目总控'),
-      }),
-    );
-    const card = (await screen.findByText('布局冲突回执')).closest('button');
-    await waitFor(() => {
-      expect(card?.getAttribute('style')).toContain('--resource-x: 20px');
-    });
-
-    fireEvent.pointerDown(card!, {
-      pointerId: 12,
-      button: 0,
-      clientX: 0,
-      clientY: 0,
-    });
-    fireEvent.pointerMove(card!, {
-      pointerId: 12,
-      clientX: 200,
-      clientY: 40,
-    });
-    fireEvent.pointerUp(card!, {
-      pointerId: 12,
-      clientX: 200,
-      clientY: 40,
-    });
-
-    expect(
-      await screen.findByText('布局已在其他窗口更新，请重新拖动'),
-    ).not.toBeNull();
-    expect(card?.getAttribute('style')).toContain('--resource-x: 400px');
-    expect(card?.getAttribute('style')).toContain('--resource-y: 80px');
+    fireEvent.pointerCancel(card!, { pointerId: 11 });
+    expect(card?.getAttribute('style')).toBe(originalStyle);
+    expect(card?.classList.contains('is-dragging')).toBe(false);
     expect(
       invoke.mock.calls.filter(
         ([command]) =>
           command === 'update_local_project_resource_canvas_layout',
       ),
-    ).toHaveLength(1);
-  });
-
-  it('drops manual writes queued behind a CAS conflict so stale coordinates cannot overwrite the winner', async () => {
-    const projectId = 'workbench-layout-queued-conflict';
-    const projectPath = '/tmp/workbench-layout-queued-conflict';
-    const resourceId = 'agent-result:design-foundation:queued-conflict-run';
-    const manifest = createGameCreationAppManifest(
-      projectId,
-      '布局排队冲突测试',
-    );
-    const latestLayout: ProjectResourceCanvasLayout = {
-      schemaVersion: 'game-creator-resource-layout.v1',
-      projectId,
-      mode: 'dependency',
-      revision: 2,
-      positions: [
-        {
-          resourceId,
-          section: 'document',
-          x: 400,
-          y: 80,
-          manuallyPlaced: true,
-        },
-      ],
-      updatedAt: 200,
-    };
-    let resolveFirstUpdate:
-      | ((result: {
-          status: 'conflict';
-          layout: ProjectResourceCanvasLayout;
-        }) => void)
-      | null = null;
-    let updateCalls = 0;
-    const invoke = vi.fn(
-      async (command: string, args?: Record<string, unknown>) => {
-      if (command === 'read_local_project_resource_graph') {
-        return resourceGraphForInputs(args);
-      }
-      if (command === 'read_local_project_resource_canvas_layout') {
-        return {
-          ...structuredClone(latestLayout),
-          revision: 1,
-          positions: [{ ...latestLayout.positions[0], x: 20, y: 30 }],
-        };
-      }
-      if (command === 'update_local_project_resource_canvas_layout') {
-        updateCalls += 1;
-        return await new Promise((resolve) => {
-          resolveFirstUpdate = resolve;
-        });
-      }
-      throw new Error(`unexpected invoke ${command}`);
-      },
-    );
-    window.__TAURI__ = { core: { invoke } };
-
-    render(
-      React.createElement(ProjectDevelopmentView, {
-        projectName: '布局排队冲突测试',
-        projectPath,
-        manifest,
-        attachments: [],
-        agentResults: [
-          {
-            agentId: 'design-foundation',
-            runId: 'queued-conflict-run',
-            label: '玩法策划 Agent',
-            title: '排队冲突回执',
-            content: '排队冲突正文',
-            updatedAt: 1,
-          },
-        ],
-        supervisor: React.createElement('div', null, '项目总控'),
-      }),
-    );
-    const card = (await screen.findByText('排队冲突回执')).closest('button');
-    await waitFor(() => {
-      expect(card?.getAttribute('style')).toContain('--resource-x: 20px');
-    });
-
-    for (const [pointerId, startX, endX] of [
-      [31, 0, 100],
-      [32, 100, 220],
-    ] as const) {
-      fireEvent.pointerDown(card!, {
-        pointerId,
-        button: 0,
-        clientX: startX,
-        clientY: 0,
-      });
-      fireEvent.pointerMove(card!, {
-        pointerId,
-        clientX: endX,
-        clientY: 20,
-      });
-      fireEvent.pointerUp(card!, {
-        pointerId,
-        clientX: endX,
-        clientY: 20,
-      });
-    }
-    expect(updateCalls).toBe(1);
-
-    await act(async () => {
-      resolveFirstUpdate?.({
-        status: 'conflict',
-        layout: structuredClone(latestLayout),
-      });
-      await Promise.resolve();
-    });
+    ).toHaveLength(layoutUpdatesBeforePointer);
 
+    fireEvent.click(card!);
     expect(
-      await screen.findByText('布局已在其他窗口更新，请重新拖动'),
+      screen.getByRole('dialog', { name: '布局持久化回执' }),
     ).not.toBeNull();
+
+    cleanup();
+    renderWorkbench();
+    const restoredCard = (await screen.findByText('布局持久化回执')).closest(
+      'button',
+    );
     await waitFor(() => {
-      expect(card?.getAttribute('style')).toContain('--resource-x: 400px');
-      expect(card?.getAttribute('style')).toContain('--resource-y: 80px');
+      expect(restoredCard?.getAttribute('style')).toContain(
+        '--resource-x: 12px',
+      );
+      expect(restoredCard?.getAttribute('style')).toContain(
+        '--resource-y: 24px',
+      );
     });
-    expect(updateCalls).toBe(1);
   });
 
   it('maps manifest asset kinds into stable type layout ordering', async () => {
diff --git a/apps/ai-game-creator-shell/tests/useProjectResourceCanvasLayout.test.ts b/apps/ai-game-creator-shell/tests/useProjectResourceCanvasLayout.test.ts
index ac8add1d8..2a975210d 100644
--- a/apps/ai-game-creator-shell/tests/useProjectResourceCanvasLayout.test.ts
+++ b/apps/ai-game-creator-shell/tests/useProjectResourceCanvasLayout.test.ts
@@ -438,7 +438,7 @@ describe('useProjectResourceCanvasLayout', () => {
     ).toBe(true);
   });
 
-  it('coalesces repeated queued drags for the same resource behind an in-flight CAS', async () => {
+  it('coalesces repeated queued manual placements for the same resource behind an in-flight CAS', async () => {
     const resourceA = resource('resource-a');
     const updates: Array<{
       expectedRevision: number;
@@ -577,11 +577,11 @@ describe('useProjectResourceCanvasLayout', () => {
       });
       expect(result.current.saving).toBe(false);
     });
-    expect(result.current.notice).toBe('布局已在其他窗口更新，请重新拖动');
+    expect(result.current.notice).toBe('布局已在其他窗口更新');
     expect(updateCalls).toBe(1);
   });
 
-  it('keeps the redrag notice when resource reconciliation drops a queued manual intent and retries', async () => {
+  it('keeps the manual conflict notice when resource reconciliation drops a queued manual intent and retries', async () => {
     const resourceA = resource('resource-a');
     const resourceB = resource('resource-b');
     const updates: Array<{
@@ -675,7 +675,7 @@ describe('useProjectResourceCanvasLayout', () => {
         expect.objectContaining({ resourceId: 'resource-a', x: 400, y: 80 }),
       ]),
     );
-    expect(result.current.notice).toBe('布局已在其他窗口更新，请重新拖动');
+    expect(result.current.notice).toBe('布局已在其他窗口更新');
     expect(setTimeoutSpy.mock.calls.some(([, delay]) => delay === 2400)).toBe(
       false,
     );
@@ -858,7 +858,7 @@ describe('useProjectResourceCanvasLayout', () => {
     await waitFor(() => expect(expectedRevisions).toHaveLength(3));
     await waitFor(() => expect(result.current.saving).toBe(false));
     expect(expectedRevisions).toEqual([1, 2, 3]);
-    expect(result.current.notice).toBe('布局已在其他窗口更新，请重新拖动');
+    expect(result.current.notice).toBe('布局已在其他窗口更新');
     expect(
       result.current.layout.positions.some(
         ({ resourceId }) => resourceId === 'resource-b',
diff --git a/docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md b/docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md
index 2ca695d2a..bd89e59ab 100644
--- a/docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md
+++ b/docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md
@@ -43,10 +43,12 @@
 ### 3.3 资源布局
 
 - “按依赖”和“按类型”分别保存画布位置。
-- 切换布局模式后恢复该模式最后一次用户手动拖动结果。
+- 当前只允许 dependency / type 自动布局与资源卡点击，不提供资源卡手动拖动入口。
+- 切换布局模式后恢复该模式 sidecar 中已有坐标；历史手动坐标只读恢复，不删除、不重置、不迁移。
 - 新资源首次进入某个布局时才执行默认不重叠排版；已有坐标不得被自动排序覆盖。
 - 依赖布局使用资源生成/引用关系；类型布局按资源大类、子类型、尺寸规格排序。
-- 不同资源分区不可互相拖入。
+- 资源分区由资源投影固定，前端交互不能改变分类。
+- 资源卡手动拖动、拖动持久化、拖动性能与冲突后的重新拖动提示全部暂缓，不作为当前产品合同或验收条件。
 
 ### 3.4 数值微调
 
@@ -124,6 +126,8 @@ idle -> focused(document|art|audio|version) -> idle
 - 文档：在中央画布展开并独立滚动。
 - 美术/音频：进入对应媒体聚焦状态，工具能力复用现有编辑器。
 - 版本：高亮版本引用资源；替换动作只创建下一迭代版本。
+- mentor 最新决定：资源聚焦不提供工具栏，也不提供工具侧边栏。
+- 本阶段只保留点击资源打开当前已有详情，不实施后续文档读取、美术编辑、音频能力、项目版本或运行模块。
 
 ### 4.4 历史成果与当前状态
 
@@ -153,7 +157,7 @@ P0 中 `approvalMode` 只能有效写入 `strict`；其它值只能作为不可
 
 ### 5.2 资源画布布局（P1）
 
-实现状态（2026-08-03）：本节布局合同已在独立客户端落地，dependency / type 双模式通过项目内 CAS sidecar 独立持久化；dependency 模式由 Tauri Rust 只读构建关系拓扑与确定性依赖深度、前端 SVG 派生几何，图结构和线段均不写入布局 sidecar。依赖图加载完成前设布局初始化屏障，避免以临时 `dependencyDepth=0` 生成并持久化错误坐标。资源替换、缩放 / 平移等其余 P1 能力仍按本文非目标保持未实现。
+实现状态（2026-08-03）：dependency / type 双模式通过项目内 CAS sidecar 独立持久化；dependency 模式由 Tauri Rust 只读构建关系拓扑与确定性依赖深度、前端 SVG 派生几何，图结构和线段均不写入布局 sidecar。依赖图加载完成前设布局初始化屏障，避免以临时 `dependencyDepth=0` 生成并持久化错误坐标。当前用户入口只允许自动布局与资源卡点击；资源卡手动拖动已按 mentor 决定暂缓。历史 sidecar 坐标继续只读恢复，底层布局读写与 CAS 合同保留，但当前没有用户手动布局入口。资源替换、缩放 / 平移等其余 P1 能力仍按本文非目标保持未实现。
 
 ```ts
 type ProjectResourceCanvasLayout = {
@@ -179,7 +183,7 @@ type ProjectResourceCanvasLayout = {
 - `x / y` 是相对所属 `section` 内容原点的 CSS 像素坐标，落盘前四舍五入为非负整数；坐标不使用 viewport、页面或资源详情浮层坐标系。
 - `updatedAt` 是持久层生成的 Unix 毫秒时间戳，前端不得自行覆盖。
 - `revision` 从 `0` 开始；布局文件不存在时读取接口合成 `revision=0 / positions=[]`，首次成功写入返回 `revision=1`，后续每次成功 CAS 写入递增 `1`。JSON / Tauri / TypeScript 全链路合法范围固定为 `0..=9_007_199_254_740_991`（`Number.MAX_SAFE_INTEGER`），读取、返回或提交负数、小数、非有限值与超限整数都必须失败关闭。
-- 新资源第一次进入某个 mode 时由默认布局写入 `manuallyPlaced=false`；用户完成一次有效拖动后写为 `true`。
+- 新资源第一次进入某个 mode 时由默认布局写入 `manuallyPlaced=false`。`manuallyPlaced=true` 仅用于兼容历史 sidecar 和保留底层合同；当前界面不会因指针操作新增该值。
 - 同一份布局中 `resourceId` 必须唯一。持久层允许暂时存在当前资源投影中没有的旧 ID，因为 Agent 文本成果等资源可能晚于 manifest 恢复；前端协调后必须在下一次成功写入中清除已确认失效的坐标。
 - 单份布局最多保存 `4096` 个位置，序列化文件不得超过 `2 MiB`；`resourceId` 最多 `512` 个 Unicode 字符，`x / y` 取值范围固定为 `0..=1_000_000`。
 
@@ -234,23 +238,27 @@ type UpdateProjectResourceCanvasLayoutResult =
 
 #### 5.2.4 前端布局与协调合同
 
-- 资源卡改用 Pointer Events 驱动二维拖动；超过统一移动阈值后才进入拖动态，普通点击仍打开唯一资源详情浮层，`pointercancel` 恢复拖动前位置。
-- 资源只能在原 `section` 内拖动。不同 section 之间既不能通过指针拖入，也不能通过持久 payload 改变当前资源的前端分类事实。
-- dependency 默认布局按 `dependencyDepth` 形成横向层级，同层资源纵向寻找第一个不重叠位置；type 默认布局固定按“资源子类型 -> 媒体类型 -> 名称 -> 资源 ID”稳定排序，在分区内从左到右、从上到下寻找第一个空位。布局模型的 `subtype` 必填：manifest 资产使用 `asset.kind`，任务产物、导入附件与 Agent 文本成果分别使用稳定的 `task-artifact`、`attachment`、`agent-result`，不得以缺失值或显示文案兜底；资源协调签名必须包含 subtype。卡片尺寸、间距和拖动阈值必须由单一前端布局模型常量维护。
+- 资源卡是可点击按钮，只负责选择资源并打开当前唯一资源详情浮层；不得绑定卡片级 `pointerdown / pointermove / pointerup / pointercancel` 拖动处理器。
+- 指针移动不得修改卡片 `x / y`、不得产生拖动预览、不得更新依赖线几何，也不得提交手动布局 CAS。卡片 title、cursor、`touch-action` 和 class 不得暗示可拖动。
+- dependency 默认布局按 `dependencyDepth` 形成横向层级，同层资源纵向寻找第一个不重叠位置；type 默认布局固定按“资源子类型 -> 媒体类型 -> 名称 -> 资源 ID”稳定排序，在分区内从左到右、从上到下寻找第一个空位。布局模型的 `subtype` 必填：manifest 资产使用 `asset.kind`，任务产物、导入附件与 Agent 文本成果分别使用稳定的 `task-artifact`、`attachment`、`agent-result`，不得以缺失值或显示文案兜底；资源协调签名必须包含 subtype。卡片尺寸与间距由单一前端布局模型常量维护。
 - type 模式资源集合变化时保留全部仍存在的坐标，只为新 ID 计算默认位置，并删除已确认失效的旧 ID。dependency 模式只永久保留 `manuallyPlaced=true` 的用户坐标；`manuallyPlaced=false` 属于可派生自动位置，在 Rust 关系图首次就绪或可信 producer / dependency depth 变化后按最终拓扑确定性重算。自动重算不得移动手动坐标，协调结果与持久布局逐项一致时不得产生 CAS 写入。
 - 搜索或筛选只隐藏卡片，不删除、压缩或重排其坐标；清空搜索后恢复原位置。
 - 窗口尺寸变化只改变可视范围和分区滚动边界，不回写、裁切或缩放持久坐标。当前客户端继续以 `1280×800` 横屏合同验收。
 - 打开项目、切换 mode 或当前 mode 首次出现新资源时执行“读取 -> 协调 -> 必要时 CAS 写入”；dependency 模式必须先等待与当前 `projectPath + projectId + resource inputs` 匹配的 Rust 图进入 `ready` 或 `failed` 终态，等待期间不得创建 fallback、读取 sidecar、协调资源或入队保存。`failed` 只允许以空图降级初始化一次。项目或 mode 已切换后返回的旧异步结果必须丢弃。
-- 同一 `projectPath + projectId + mode` 的首次读取与资源集合协调必须分开：资源集合变化不得取消已经发出的读取或保存。同一 scope 内全部手动拖动和资源自动协调写入使用同一 FIFO，任一时刻最多一个 CAS 在途，后一笔必须使用前一笔成功返回的 revision，不能用“最后请求获胜”跳过中间 CAS。切换项目或 mode 后，旧 scope 的在途请求不能阻塞新 scope 队列；前端放弃旧请求槽位并丢弃其迟到响应，后端继续依靠 `expectedProjectId + expectedRevision + 系统锁` 仲裁已发出的请求。
-- 某笔 CAS 在途期间，同一 scope 内对相同 `resourceId + section` 重复产生但尚未发送的拖动意图必须折叠为最后坐标；已经在途的请求不得取消，不同资源的顺序不得跨越。队列增长必须受当前资源与分区数量约束，不能随连续 pointer 事件无界累积。
-- 用户拖动结束后先乐观更新，再立即提交一次 CAS。成功后以返回布局更新 revision；普通写入失败时恢复最近可信持久布局并提示“布局保存失败，已恢复上次布局”。
-- CAS 冲突时直接载入返回的最新布局并提示“布局已在其他窗口更新，请重新拖动”，丢弃所有基于冲突前快照排队的手动拖动，不得自动重放本地旧坐标或静默覆盖另一窗口结果。即使当前在途请求是允许自动重试的资源协调，只要本次冲突实际清除了任何排队手动拖动，也必须按当前 scope 保留重新拖动提示；后续资源协调成功、失败或通用提示定时器都不得静默清除，只有新的手动布局成功保存或切换 scope 才能解除。资源自动协调可以基于冲突返回的新 revision 有界重试，单次资源签名最多追加 `2` 次，持续跨窗口写入时不得无限自旋。
+- 同一 `projectPath + projectId + mode` 的首次读取与资源集合协调必须分开：资源集合变化不得取消已经发出的读取或保存。当前 scope 内资源自动协调写入使用单写者 FIFO，任一时刻最多一个 CAS 在途，后一笔必须使用前一笔成功返回的 revision。切换项目或 mode 后，旧 scope 的在途请求不能阻塞新 scope 队列；前端放弃旧请求槽位并丢弃其迟到响应，后端继续依靠 `expectedProjectId + expectedRevision + 系统锁` 仲裁已发出的请求。
+- 自动协调 CAS 冲突时直接载入返回的最新布局；仍需协调时可以基于权威 revision 最多追加 `2` 次重试，持续跨窗口写入时不得无限自旋。当前提示只说明“布局已在其他窗口更新”，不得要求用户重新拖动。
 - 缺少 Tauri bridge 的浏览器开发态可以保留当前会话内布局用于界面测试，但不得宣称已经持久保存。
 
-#### 5.2.5 资源依赖关系图层
+#### 5.2.5 暂缓的手动拖动合同
+
+- Pointer Events 二维拖动、移动阈值、拖动态 class、乐观手动坐标与结束时单次 CAS 提交暂缓。
+- 手动意图折叠、冲突后丢弃旧手动坐标、重新拖动提示和 4096 卡片拖动帧预算暂缓，不进入当前验收。
+- 已有 Hook 手动意图、命令式 SVG preview、sidecar 字段和 Rust CAS 基础设施可以保留为未接线技术资产；当前资源卡不得调用这些入口。
+
+#### 5.2.6 资源依赖关系图层
 
 - 图层只在 dependency 模式挂载；type 模式不得渲染 SVG、连线或 marker。切换 mode、切换项目或卸载工作台时必须销毁旧图层，并清理尺寸观察和窗口事件监听。
-- 输入固定为当前资源投影的全部卡片身份 / 坐标与 Tauri Rust 返回的 `ProjectResourceGraph` 只读 DTO；Rust 负责资源过滤、去重、迭代式环检测、SCC 压缩后的确定性依赖深度、任务流聚合和一跳连接索引，前端只负责 DTO 防御归一化、浏览器几何与原生 SVG path / marker。SVG 叠加在资源卡底层并设置 `pointer-events: none`，不得引入 D3、React Flow 等图表库，也不得阻断卡片点击和 Pointer Events 拖动。实时拖动坐标属于 DOM 临时状态，不得逐帧通过 Tauri IPC 交给 Rust。
+- 输入固定为当前资源投影的全部卡片身份 / 坐标与 Tauri Rust 返回的 `ProjectResourceGraph` 只读 DTO；Rust 负责资源过滤、去重、迭代式环检测、SCC 压缩后的确定性依赖深度、任务流聚合和一跳连接索引，前端只负责 DTO 防御归一化、浏览器几何与原生 SVG path / marker。SVG 叠加在资源卡底层并设置 `pointer-events: none`，不得引入 D3、React Flow 等图表库，也不得阻断卡片点击。
 - `asset-reference` 表示精确资源引用，使用橙色实线与连续贝塞尔曲线。`GameCreationAppAssetManifestEntry.source.referenceResourceIds` 中的外部资源 ID 必须先唯一匹配另一项资产的 `source.resourceId`，再映射为当前资源卡 ID；缺失、重复或已删除的目标均不得渲染幽灵连线。
 - `task-flow` 表示任务产物流转，使用灰色圆头虚线。任务依赖按 `sourceTaskId -> targetTaskId` 聚合为一条主线，两端资源仅绘制平滑曲线分支，不得出现直角折线；禁止对上下游资源生成笛卡尔积连线。任务主线与分支可以使用不同线宽和透明度表达聚合层级，但不能改变端点或方向语义。
 - 画布资产 producer 只能来自 `agent.runtime.canvas.asset_generate` 的 `assetId -> agentId` 审计且 `agentId` 必须存在于当前 manifest；External Editor `source.taskId` 属于平台生成任务命名空间，禁止当作 manifest task ID。证据缺失、冲突或有界审计读取未覆盖时不生成对应 task flow，不猜测归属。
@@ -258,8 +266,8 @@ type UpdateProjectResourceCanvasLayoutResult =
 - 资源自引用的起点与终点为同一张卡片时，必须绘制在卡片外侧的可见闭环并保留箭头，不得让路径穿过卡片后被底层 SVG 层级遮挡。
 - 搜索只允许为当前可见端点生成几何；任一精确引用端点隐藏时该线隐藏，聚合任务流只保留仍可见的两端分支，任一侧没有可见资源时整条任务流隐藏。
 - 选中资源后，高亮其直接上游、直接下游卡片和关联边，弱化其余边；不做跨多层递归高亮。选中 ID 已失效时按未选中处理。
-- 拖动预览坐标必须直接进入 SVG 几何计算，使连线随 pointer move 实时更新；拖动结束仍只保存卡片布局坐标，不持久化 path、marker、section 原点或任何图结构。
-- Pointer Move 必须按动画帧合并并完全避开工作台父组件 state：拖动卡片通过 ref 直接更新 CSS 坐标，SVG 通过命令式句柄只更新当前资源局部索引关联的 path。基础 positions 不随每帧复制，静态卡片和 SVG 拓扑保持复用，非拖动卡片不得因预览帧重新渲染。`ResizeObserver` 在单个图层生命周期只允许构造一次。dependency section 额外提供至少 `64px` 右侧视觉 gutter，确保最右侧自环和箭头可完整滚动显示，但不得修改卡片坐标或布局 sidecar。
+- 资源卡 Pointer Move 不改变基础 positions 或 SVG 几何。连线只随布局读取、资源自动协调、搜索、选择、项目切换或 section origin 变化而更新。
+- `ResizeObserver` 在单个图层生命周期只允许构造一次。dependency section 额外提供至少 `64px` 右侧视觉 gutter，确保最右侧自环和箭头可完整滚动显示，但不得修改卡片坐标或布局 sidecar。
 
 ### 5.3 资源类型与替换兼容性（P1）
 
@@ -353,7 +361,7 @@ type ProjectAgentMudPointAttribution = {
 
 - 复用现有四区工作台壳。
 - 资源/运行切换与客户端内 loopback 预览。
-- 只读资源画布、文档展开、美术/音频聚焦入口。
+- 只读资源画布与资源卡点击详情；资源聚焦工具栏 / 工具侧边栏及后续媒体能力暂缓。
 - Supervisor 正式会话、上传、Runtime 确认与安全错误。
 - 当前 run 专业状态与项目历史成果分离。
 - 默认三专业组，并可展开另外三组。
@@ -362,7 +370,7 @@ type ProjectAgentMudPointAttribution = {
 
 ### P1
 
-- 先实施依赖/类型两套坐标持久化、首次默认不重叠布局、跨重启恢复与 CAS 冲突处理。
+- 已实施依赖/类型两套坐标持久化、首次默认不重叠布局、历史坐标跨重启恢复与自动协调 CAS 冲突处理；资源卡手动拖动暂缓。
 - 资源关系线在布局持久化验收通过后单独实施，不与本切片捆绑伪造完成。
 - 版本资源高亮、兼容性判断和不可变下一迭代版本。
 - 美术/音频编辑状态接线。
@@ -388,10 +396,10 @@ type ProjectAgentMudPointAttribution = {
 
 ### 7.2 P1 资源画布布局持久化验收
 
-1. 同一项目在 dependency 与 type mode 分别拖动资源后，关闭并重启客户端，两种 mode 都恢复各自最后一次成功保存的位置。
+1. 同一项目在 dependency 与 type mode 分别读取并协调布局，关闭并重启客户端后恢复各自 sidecar 坐标；历史 `manuallyPlaced=true` 坐标保持不变。
 2. 新资源进入任一 mode 时获得不重叠默认位置，现存资源坐标保持逐项不变；删除资源后，下一次成功写入不再包含已确认失效的 ID。
-3. 资源不能跨 document、version、art、audio 分区；点击、搜索、筛选和资源详情浮层行为不因二维拖动回归。
-4. 两个窗口基于同一 revision 写入时最多一个成功；失败方收到 `conflict` 与最新完整布局，界面不静默覆盖成功方结果。
+3. 资源卡 title、cursor、`touch-action` 与 class 只表达可点击；Pointer Down / Move / Up / Cancel 不改变坐标、不产生拖动预览、不提交手动布局 CAS，点击仍打开当前资源详情。
+4. 两个窗口基于同一 revision 执行资源自动协调写入时最多一个成功；失败方收到 `conflict` 与最新完整布局，界面不静默覆盖成功方结果。
 5. 布局文件缺失的旧项目可以无迁移打开；损坏、未知 schema、身份冲突、超限和链接文件失败关闭，且原文件不被空布局覆盖。
 6. 布局读写不改变 manifest、游戏项目 mutation revision、Runtime verification、Agent 权限与预览状态。
 7. `1280×800` 最小横屏下全部资源可通过分区滚动访问，不出现页面级横向或纵向溢出，右侧对话和底部 Agent 状态栏保持可见。
@@ -402,14 +410,14 @@ type ProjectAgentMudPointAttribution = {
 2. 精确引用只接受唯一有效的外部资源 ID 映射，删除或不存在的资源不产生幽灵连线。
 3. 多资源任务依赖只形成一条聚合主线与 `O(S+T)` 条端点分支，不产生 `S×T` 连线。
 4. 资源引用环和无资源产物参与的任务环都可被有限遍历识别，界面不死循环。
-5. 搜索、选择和拖动分别触发端点过滤、直接上下游高亮和实时几何更新；原有点击、详情浮层与拖动保存行为不回归。
+5. 搜索触发端点过滤，选择触发直接上下游与关联边高亮；资源卡指针移动不更新线段，点击与详情浮层行为不回归。
 6. 切换布局模式或项目后旧 SVG、ResizeObserver 与窗口监听全部清理；图层从不写入 layout sidecar、manifest 或其它持久化。
-7. 4096 资源链式 fixture 下，拖动一张卡片只更新它关联的线段；同一图层 100 次拖动期间 Observer 仍只构造一次。真实 Chromium 目标为拖动 p95 小于 `16.7ms`、不出现超过 `50ms` 的 long task，并完整显示最右侧自环与箭头。
+7. 4096 资源链式 fixture 继续验证拓扑、聚合复杂度和自动布局性能；拖动局部更新与真实 Chromium 拖动帧预算暂缓，不作为当前验收条件。最右侧自环与箭头仍需完整显示。
 8. Rust 图读取延迟时，dependency sidecar 在图进入 `ready / failed` 前没有读取或写入；首次布局直接使用 Rust 返回的最终 producer 与 dependency depth。重新打开旧布局时手动位置逐项不变，自动位置按最终拓扑协调且相同结果不增加 revision。
 
 ## 8. 非目标
 
-- 本切片仍不实现资源替换、不可变迭代版本、画板编辑状态、测试切片、数值参数或泥点归因；已实现的资源关系图只提供 Rust 只读拓扑与前端派生展示，不建立新的资源业务真相。
+- 本切片不实现资源卡手动拖动，也不实现资源聚焦工具栏、资源聚焦工具侧边栏、后续文档读取、美术编辑、音频能力、资源替换、不可变迭代版本、运行模块扩展、测试切片、数值参数或泥点归因；已实现的资源关系图只提供 Rust 只读拓扑与前端派生展示，不建立新的资源业务真相。
 - 本切片不保存资源详情浮层位置、画布缩放 / 平移、搜索条件、筛选条件或当前 mode；这些状态如需持久化必须另行扩展合同，不能塞入 `game-creator-resource-layout.v1`。
 - 不修改 SpacetimeDB schema。
 - 不开放普通用户 Agent.md/Skill。
diff --git a/docs/project-memory/shared-memory/decision-log.md b/docs/project-memory/shared-memory/decision-log.md
index cb0b8213c..83659ca2d 100644
--- a/docs/project-memory/shared-memory/decision-log.md
+++ b/docs/project-memory/shared-memory/decision-log.md
@@ -1,7 +1,18 @@
 # 决策记录
 
+## 2026-08-03 资源卡手动拖动暂缓且当前只开放自动布局与点击详情
+
+- 背景：飞书《陶泥儿GameAgent-V1.0 项目开发界面需求》曾要求资源卡可拖动，并由后续 PRD、技术方案和实现扩展为手动布局 CAS、依赖线拖动预览与性能验收；mentor 最新决定明确资源卡暂时禁止拖动，资源聚焦也不需要工具栏或工具侧边栏。
+- 决策：当前资源卡不绑定 `pointerdown / pointermove / pointerup / pointercancel` 拖动入口，title、cursor、`touch-action` 与 class 只表达可点击；Pointer Move 不改变坐标、不更新依赖线、不提交手动布局。资源卡点击继续打开已有详情；dependency / type 自动布局、搜索、依赖线和直接上下游高亮保持现役。
+- 保留边界：项目内 dependency / type 布局 sidecar、历史坐标读取、资源集合自动协调、scope FIFO、跨窗口系统锁、Tauri/Rust CAS 与命令式 SVG preview 基础设施可以保留；历史 `manuallyPlaced=true` 坐标不删除、不重置、不迁移，但当前没有用户手动布局入口。手动拖动持久化、拖动性能和冲突后的重新拖动提示不再是当前验收条件。
+- 后续边界：本阶段不继续实现资源聚焦、文档读取、美术编辑、音频能力、项目版本或运行模块；若重新开放手动拖动，必须先更新 PRD、技术方案和 AppSurface 验收合同。
+- 验证方式：AppSurface 覆盖 Pointer Down / Move / Up / Cancel 后卡片坐标、SVG path 与布局更新调用均不变，并继续覆盖点击详情、dependency / type 切换、搜索、依赖图和直接上下游高亮；追加 shell typecheck、编码检查与 `git diff --check`。
+- 关联文档：`docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md`、`docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md`。
+
 ## 2026-08-03 依赖布局等待 Rust 图终态且拖动热路径脱离 React state
 
+> 状态：其中依赖图初始化屏障继续生效；手动拖动热路径与性能验收已由上一条 mentor 最新决定暂缓。
+
 - 背景：资源图异步返回前，dependency 布局会先以 `dependencyDepth=0` 创建并持久化自动坐标；图返回后的 reconcile 保留既有位置，导致首次布局永久停留在错误层级。4096 张真实资源卡拖动时，逐帧父组件 state 还会重渲染全部卡片，即使 SVG 已只更新局部 path 也无法满足帧预算。
 - 决策：Rust 关系图 read model 负责在完整任务图 SCC 压缩后返回确定性 resource dependency depth；dependency 模式等待当前 scope 图进入 `ready / failed` 后才启动布局读取与协调。手动位置永久保留，自动位置允许按最终图重新派生。拖动 preview 留在前端 ref/DOM 热路径，命令式更新卡片 CSS 与局部 SVG path，不逐帧跨 Tauri IPC，也不写 layout sidecar。
 - 边界：不修改 `game-creator-resource-layout.v1`、布局 Rust 持久层、manifest、api-server 或 SpacetimeDB；type 模式不等待资源图且继续保留全部已有坐标。图失败只降级初始化一次，项目或 mode 切换后旧图结果必须丢弃。
@@ -25,6 +36,8 @@
 
 ## 2026-07-31 AI 游戏创作资源依赖图采用 Rust 只读拓扑与前端派生 SVG
 
+> 状态：其中资源卡 Pointer Move 拖动预览与局部更新验收已由 2026-08-03 mentor 最新决定暂缓；只读拓扑、SVG 派生展示、搜索与选择高亮合同继续生效。
+
 - 背景：资源画布已有 dependency / type 双模式坐标与本地 CAS sidecar，但 dependency 模式尚未把当前 manifest 中可证明的资源引用和任务流转可视化；关系图不能反向污染布局持久化或建立第二套资源真相。
 - 决策：dependency 模式由 Tauri Rust 只读命令从当前 manifest、资源卡身份和有界 `.agent/agent.db` 审计构建稳定 `ProjectResourceGraph` read model，前端只归一化 DTO、测量卡片坐标并用原生 SVG 渲染。资产 `source.referenceResourceIds` 只在唯一匹配另一资产 `source.resourceId` 后形成橙色实线；任务依赖按任务对聚合为灰色虚线主线与两端分支，禁止资源笛卡尔积。Rust 以迭代式强连通分量分析识别资源环和完整任务 DAG 环，并返回资源局部连接索引。
 - 任务身份：External Editor 响应中的 `source.taskId` 是平台生成任务 ID，不等于本地 manifest task ID，禁止据此分配 producer。画布资产只接受 `agent.runtime.canvas.asset_generate` 审计中经当前 manifest task 校验的 `assetId -> agentId`；证据缺失、冲突或已超出有界读取窗口时不生成对应 task flow。任务产物与 Agent 回执继续使用自身已有的 manifest task 身份。
@@ -5546,7 +5559,7 @@
 - 资源投影：上述回执同步投影到“资源管理 → 文档”，保留来源 Agent 和 run 身份。它是持久回执的可见视图，不得冒充 manifest asset、项目目录中的实际文件或可下载交付物。
 - 重试确认：`agent.resume` 默认仍为 `confirm`。普通自动 retry command 保留 auto gate；正式失败卡的“在当前项目重试”按钮本身视为本次明确确认，调用单独的 confirmed retry command，但仍不得绕过 deny。点击后必须在原卡即时显示提交中、成功或安全错误，不能把错误放到专业列表末尾。若总控已为同一 delegation 准备精确 repair，按钮优先确认该 repair，不再创建重复的无合同重试。
 - 回执命名：无文件的 completed 结果统一称“专业 Agent 文本回执”，不得称“美术产物”或直接暴露 `design-foundation / art-asset-plan / balance-seed` 等内部 ID。美术任务只完成计划且 manifest 没有图片时，普通界面明确显示“仅完成计划，尚未生成或登记图片”。
-- 工作台布局：PDF 方案外的顶部项目标题条不进入项目工作台；资源卡支持同分类、当前会话内的真实拖拽重排，不宣称持久保存。资源详情使用独立可拖动浮层，位置约束在工作台与 viewport 内并避开底部 Agent dock，长正文独立滚动。工作区与 dock 精确占满客户端可用高度，不保留 dock 下方空白。
+- 工作台布局：PDF 方案外的顶部项目标题条不进入项目工作台；本条原定的资源卡同分类、当前会话内拖拽重排已由 2026-08-03 mentor 最新决定取代，当前资源卡只允许自动布局与点击详情。资源详情使用独立可拖动浮层，位置约束在工作台与 viewport 内并避开底部 Agent dock，长正文独立滚动。工作区与 dock 精确占满客户端可用高度，不保留 dock 下方空白。
 
 ## 2026-07-20 AI 游戏创作策划与美术图片交付门禁
 
diff --git a/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md b/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md
index 07448ea03..07e75280f 100644
--- a/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md
+++ b/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md
@@ -154,7 +154,7 @@ V1.17 计划快照随 `game-creator-runtime-context-bundle.v3` 持久化，v2 
 
 2026-07-19 起，当前父 run 下的专业 Agent 进入 `failed` 后，正式工作台必须提供“在当前项目重试”恢复入口，不得要求用户新建项目。重试必须精确核对原 `agentId + runId + parentRunId`，复用原 task、active Session 和父 run 归属，同时生成新的专业 Agent runId；新 run 继承已持久化的上下文和父子绑定，不覆写旧失败 run 的审计事实，也不得把 UI 重试解释为底层 transport 根因已修复。`agent.resume` 默认 `confirm` 不变：自动 retry command 继续执行 auto gate；正式失败卡按钮自身是本次明确确认，使用 deny-only 的 confirmed retry command。按钮必须原卡即时显示“正在提交重试”、受理或安全错误；若 Supervisor 已为同一 delegation 准备合同 repair，则该按钮优先确认既有 repair，避免重复派发。
 
-completed 专业 Agent 的用户可见成果不能仅依赖项目文件。当委派合同为 `expectedArtifacts=[]` 或未产生显式文件时，工作台必须读取该 Agent 持久对话的最后一条 assistant，作为明确标注的“专业 Agent 文本回执”提供查看，并投影到“资源管理 → 文档”。该投影是持久回执的可见视图，必须保留来源 Agent 与 run 身份，不冒充 manifest asset、项目目录中的实际文件或可下载交付物；内部 Agent ID 不进入用户资源名。美术只交付计划且 manifest 没有图片时必须显示“仅完成计划，尚未生成或登记图片”，不能把文本回执称为美术图片产物。策划 `design-foundation` 与美术 `art-asset-plan` 从 2026-07-20 起属于图片产物型 canonical task：前者必须生成并登记 `assets/ui-prototype.png` 横屏界面原型图，后者必须生成并登记 `assets/art-spritesheet.png` 首版核心美术素材；只有文本计划或空 `expectedArtifacts` 不构成完成。策划图还必须由 `design-foundation` 的 `image.inspect` 对当前图片 SHA 形成 `ui-prototype.v2` 结构化视觉验收：信息 HUD、主要可玩区域、当前玩法的关键实体、主要操作、失败/重开流程、移动端布局意图、实现清晰度与原创主题八项全部通过且问题列表为空。验收不得预设塔防或任何固定玩法；`ui-prototype.v1` 仅供历史动作回执安全读取，不能作为新建或恢复 run 的 completion authority。Runtime finalization 只接受同 run、当前 SHA 的 v2 证据。视觉调用失败、响应不可解析、检查未通过或图片被替换后 SHA 不一致都继续阻塞。未通过的已登记图片在工作台只称“候选界面图（待视觉验收）”，不得冒充正式 UI 原型。图片生成未配置、待确认或失败时保持阻塞/失败，不得投影为 completed。资源卡允许同分类内做当前会话拖拽重排；详情使用受 viewport 与底部 dock 约束的独立可拖浮层，长正文由唯一外层滚动容器承载并用 Markdown 安全渲染。PDF 方案外的顶部项目标题条移除，dock 下方不得保留空白；底部专业 Agent 为只读状态卡，不得因点击保留多个详情浮层。
+completed 专业 Agent 的用户可见成果不能仅依赖项目文件。当委派合同为 `expectedArtifacts=[]` 或未产生显式文件时，工作台必须读取该 Agent 持久对话的最后一条 assistant，作为明确标注的“专业 Agent 文本回执”提供查看，并投影到“资源管理 → 文档”。该投影是持久回执的可见视图，必须保留来源 Agent 与 run 身份，不冒充 manifest asset、项目目录中的实际文件或可下载交付物；内部 Agent ID 不进入用户资源名。美术只交付计划且 manifest 没有图片时必须显示“仅完成计划，尚未生成或登记图片”，不能把文本回执称为美术图片产物。策划 `design-foundation` 与美术 `art-asset-plan` 从 2026-07-20 起属于图片产物型 canonical task：前者必须生成并登记 `assets/ui-prototype.png` 横屏界面原型图，后者必须生成并登记 `assets/art-spritesheet.png` 首版核心美术素材；只有文本计划或空 `expectedArtifacts` 不构成完成。策划图还必须由 `design-foundation` 的 `image.inspect` 对当前图片 SHA 形成 `ui-prototype.v2` 结构化视觉验收：信息 HUD、主要可玩区域、当前玩法的关键实体、主要操作、失败/重开流程、移动端布局意图、实现清晰度与原创主题八项全部通过且问题列表为空。验收不得预设塔防或任何固定玩法；`ui-prototype.v1` 仅供历史动作回执安全读取，不能作为新建或恢复 run 的 completion authority。Runtime finalization 只接受同 run、当前 SHA 的 v2 证据。视觉调用失败、响应不可解析、检查未通过或图片被替换后 SHA 不一致都继续阻塞。未通过的已登记图片在工作台只称“候选界面图（待视觉验收）”，不得冒充正式 UI 原型。图片生成未配置、待确认或失败时保持阻塞/失败，不得投影为 completed。资源卡当前只允许点击打开详情，不提供拖动重排；详情继续使用受 viewport 与底部 dock 约束的独立可拖浮层，长正文由唯一外层滚动容器承载并用 Markdown 安全渲染。PDF 方案外的顶部项目标题条移除，dock 下方不得保留空白；底部专业 Agent 为只读状态卡，不得因点击保留多个详情浮层。
 
 V1.17 同时把 finalization journal 升级为 v2 并绑定最终完整计划快照：assistant 已落盘而 Runtime state 丢失时，从 v2 journal 恢复原结构化计划后补齐终态；assistant 尚未落盘且 state 丢失时失败关闭。外层 `failed / budget-exhausted` 只保留最后可信计划，不把未完成步骤机械改成失败。thinking summary、legacy plan event 和 tool-plan repair 公共审计只保留哈希、字符数或计数，必要的模型输出与错误上下文仅留在有界私有 repair 请求中。
 
@@ -360,7 +360,7 @@ game-project/
 - 页面骨架固定为左侧现有全局导航、中间主视窗、右侧陶泥儿对话和底部子 Agent 状态栏；不新建第二套客户端或平行项目页。
 - 中间主视窗提供 `资源管理 / 运行` 切换。`code-prototype` 任务完成前运行入口保持视觉不可用，但仍可点击查看“当前无可运行版本”，不能使用会阻断说明交互的原生 `disabled` 或 `aria-disabled`；完成后才允许进入运行表现层。切回资源管理只修改前端展示态，不伪造后端预览暂停结果。
 - 资源管理从当前 `GameCreationAppManifest` 派生项目文档、项目版本和 `assets`，并把首页已导入附件作为当前项目上传资源展示。资源按文档、版本、美术、动作、音乐音效分区；`按依赖 / 按类型` 使用各自前端排列，dependency 模式额外绘制当前 manifest 与资源投影可证明的依赖关系。排列与图层都不写回 manifest，不能推断或伪造缺失依赖。
-- 资源卡支持选择聚焦、文档展开 / 收起、搜索和类型筛选的界面交互。2026-07-28 起，原一维会话拖拽已替换为两套二维坐标与本地 CAS sidecar；2026-07-31 起，dependency 模式增加不持久化的原生 SVG 关系图层。画板编辑和同类型版本资源替换仍不得在缺少各自正式写回契约时保存为业务事实。
+- 资源卡支持点击详情、搜索和类型筛选。2026-07-28 起完成两套二维坐标与本地 CAS sidecar；2026-07-31 起 dependency 模式增加不持久化的原生 SVG 关系图层。2026-08-03 mentor 决定暂缓资源卡拖动，当前卡片不挂载 Pointer Down / Move / Up / Cancel 拖动入口，只允许自动布局和点击详情。资源聚焦不提供工具栏或工具侧边栏；本阶段不继续实现文档读取、美术编辑、音频能力、项目版本或运行模块。
 - 运行表现层首版直接嵌入当前项目的 loopback 游戏画面，并展示上一项 / 暂停继续 / 下一项切片控制、素材信息和数值微调面板。`preview.start` 启动本地 server 后把真实 URL 回写工作台，`preview.open` 只激活客户端内运行视图，不再调用系统浏览器；切片、参数调整和自然语言新增调节项首版仍只保留本地 UI 草稿，不修改代码或 manifest。
 - 右侧继续复用现有 Project Supervisor 会话、Runtime 澄清和确认链路；输入区展示 `严格审批 / 风险审批 / 无需审批` 独立面板。P0 只有严格审批可选；风险审批和无需审批保持视觉不可用但允许点击查看原因，不替代 Runtime 的逐动作权限、确认、sandbox 或 reconciliation 门禁。风险 Rank 算法记录在 `docs/project-memory/todos/【待解决】AI游戏创作高风险审批Rank-2026-07-20.md`，前端不得自行计算。
 - 底部状态栏默认展示策划、美术、程序 3 组，并允许在同一栏展开数值、音频、发布组；状态来自 manifest 与当前 Supervisor run 的 Runtime，悬停显示当前任务与进度。累计泥点必须等待后端计费归因投影；Agent.md 编辑和自定义 Skill 在来源审核、版本、权限、sandbox 与回滚合同完备前不向普通用户开放。
@@ -375,18 +375,20 @@ game-project/
 
 2026-07-28 起，资源画布布局持久化以工作台 PRD §5.2 和 §7.2 为唯一编码合同，实施边界如下：
 
+2026-08-03 需求收口：资源卡手动拖动暂缓。历史 sidecar 坐标继续只读恢复，自动布局仍可为资源集合协调提交 CAS；sidecar schema、布局读取、FIFO、跨窗口系统锁和 Rust CAS 基础设施全部保留，但当前没有用户手动布局入口。
+
 - dependency 与 type 分别保存到 `.agent/workbench/resource-layouts/dependency.json` 和 `type.json`，schema 固定为 `game-creator-resource-layout.v1`。布局是本地工作台 UI sidecar，不进入 manifest、游戏项目 mutation revision、Runtime verification、Agent 产物、资产或云端事实。
 - `x / y` 使用 section 内容坐标，`updatedAt` 使用 Unix 毫秒；文件缺失只合成 revision `0` 空布局且不产生只读副作用。每个 mode 按 `projectId + mode + expectedRevision` 做 CAS，成功 revision 加一，冲突返回最新完整布局且不写文件。revision 虽在 Rust 中使用 `u64`，但跨 JSON / Tauri / TypeScript 的合法域固定为 `0..=Number.MAX_SAFE_INTEGER`；共享 DTO 序列化与反序列化、Tauri 输入和前端 IPC 响应均执行同一边界校验。
 - Tauri 命令固定为 `read_local_project_resource_canvas_layout` 与 `update_local_project_resource_canvas_layout`。写命令先只读确认有效 manifest，再通过持久 `.layout.lock` 入口获取句柄级跨窗口系统锁，并在锁内复核 projectId、重新读取当前 sidecar。Unix 使用 `flock`，Windows 使用不共享文件句柄；释放只通过句柄 Drop / 进程退出完成，不使用 mtime stale 回收，也不删除锁文件。其余写入继续复用安全路径、链接检查、容量上限、恢复副本与原子替换能力；不能只依赖 React 状态或进程内锁。
-- 前端从当前项目开发大组件中拆出纯布局模型与持久 Hook。默认布局、碰撞检查、资源增删协调和 section 边界由纯模型负责；读取、异步身份、CAS、错误回滚和冲突载入由 Hook 负责。Hook 以 `projectPath + projectId + mode` epoch 隔离异步结果，资源变化不取消首读或在途保存；单窗口写入经同一 FIFO 串行提交，每笔都使用最近一次成功 / 冲突响应的权威 revision。视图使用 Pointer Events 做二维拖动，保存中仍允许继续拖动并排队，普通点击、搜索、筛选和唯一资源详情浮层语义保持不变。
+- 前端从当前项目开发大组件中拆出纯布局模型与持久 Hook。默认布局、碰撞检查、资源增删协调和 section 边界由纯模型负责；读取、异步身份、CAS、错误回滚和冲突载入由 Hook 负责。Hook 以 `projectPath + projectId + mode` epoch 隔离异步结果，资源变化不取消首读或在途保存；自动协调写入经同一 FIFO 串行提交，每笔都使用最近一次成功 / 冲突响应的权威 revision。资源卡是普通可点击按钮，不绑定卡片级 Pointer 拖动处理器；指针移动不修改 CSS 坐标、不调用 SVG preview、不提交手动布局 CAS。
 - 新资源只在第一次进入某个 mode 时计算默认不重叠位置；全部现存坐标保持不变。搜索、筛选、窗口 resize 和 mode 切换不得重排或回写已有坐标，窄视图通过 section 画布范围与滚动访问，不裁切持久坐标。
 - type 默认布局固定按 `subtype -> mediaType -> label -> id` 排序。manifest 资产的 subtype 使用 `asset.kind`，任务产物、导入附件和 Agent 文本成果使用稳定的来源 fallback；subtype 必须进入资源协调签名，不能因 MIME 相同而退化成按名称混排。
-- 普通保存失败恢复最近可信持久布局；CAS 冲突载入对方最新布局并要求用户重新拖动，同时清除基于旧快照排队的全部手动意图，不自动重放旧坐标。即使冲突发生在允许自动重试的资源协调请求上，只要本次冲突清除了排队手动意图，重新拖动提示就必须绑定当前 scope 保留，不得被后续资源协调成功、失败或通用提示定时器静默清除；新的手动布局成功保存或 scope 切换后才解除。资源自动协调可基于冲突布局最多追加两次重试，持续跨窗口竞争时停止自旋并保留当前会话协调结果。损坏、未知 schema、身份冲突、超限与链接文件失败关闭，不能用空布局覆盖原文件。
+- 自动协调保存失败时保留当前会话布局；CAS 冲突载入对方最新布局，需要继续协调时最多追加两次重试，持续跨窗口竞争时停止自旋。用户提示只说明“布局已在其他窗口更新”，不要求重新拖动。损坏、未知 schema、身份冲突、超限与链接文件失败关闭，不能用空布局覆盖原文件。
 - 本布局持久化切片不包含资源关系线、资源替换、详情浮层位置、缩放 / 平移、搜索 / 筛选条件、当前 mode，也不修改 `api-server` 或 SpacetimeDB。资源关系线已在后续独立的纯前端切片接入，不改变本段 sidecar 合同；其余 P1 能力继续独立实施。
 
-实施顺序固定为：先同步 TypeScript / Rust DTO 与序列化测试，再实现 Tauri sidecar 读写和 CAS，随后接入前端纯模型、持久 Hook 与二维拖动，最后完成 Rust 安全测试、React 交互测试、跨重启 / 双窗口验收和文档状态回写。任何一步不得用 `localStorage`、manifest 字段或只在当前 React 会话有效的状态冒充项目持久化。
+历史实施顺序已完成 TypeScript / Rust DTO、Tauri sidecar/CAS、前端纯模型与持久 Hook。二维手动拖动接线现已暂缓；重新开放前必须先更新 PRD 与验收合同。任何后续步骤不得用 `localStorage`、manifest 字段或只在当前 React 会话有效的状态冒充项目持久化。
 
-2026-07-30 前端并发与性能加固状态：首读、资源更新和拖动保存已拆成 scope epoch + scope 内单写者 FIFO；定向 Hook 测试覆盖首读期间资源变化、在途手动 CAS 后资源协调、冲突清除排队拖动、旧 mode 迟到读取 / 写入、新 scope 不等待旧 scope 卡死请求、持续冲突有界停止，以及在途 CAS 后同资源连续拖动折叠为最后坐标。旧 scope 请求已经发出后不做不安全取消，但会释放前端活动槽并由 epoch 丢弃迟到响应；同 scope 的在途请求仍保持唯一。默认布局用 section 分组与二维占用索引替代逐 slot 全量扫描，dependency 使用按列单调游标，type 使用单调 slot 游标；`4096` 项双模式性能回归纳入前端测试，避免恢复到接近 `O(N³)` 的主线程阻塞实现。
+2026-07-30 前端并发与性能加固形成的 scope epoch、scope 内单写者 FIFO、手动意图折叠和冲突恢复实现继续保留为底层技术资产；当前用户入口只消费布局读取与资源自动协调。默认布局仍使用 section 分组与二维占用索引，dependency 使用按列单调游标，type 使用单调 slot 游标；`4096` 项双模式自动布局性能回归继续防止恢复到接近 `O(N³)` 的主线程阻塞实现。手动拖动帧预算、局部 preview 性能和重新拖动提示不再是当前验收条件。
 
 2026-07-30 Rust 并发与零副作用加固状态：资源布局锁已由 `create_new + mtime stale 删除` 改为持久锁文件上的 Unix `flock` / Windows 独占句柄，活锁即使 mtime 很旧也不能被另一个写入者回收，释放后仍复用同一文件实例。更新命令携带只用于校验的 `expectedProjectId`，在任何目录创建前先读取 manifest 并拒绝旧项目窗口，锁内再次核对 projectId；不存在根、非项目根、损坏 manifest 和路径重建后的旧窗口均不产生 `.agent/workbench`。revision 在共享 serde、Tauri 命令和前端 IPC 三层限制到 `Number.MAX_SAFE_INTEGER`，达到上限时保持原文件并失败关闭，不能让 Rust `u64` 值在 JavaScript 中失真后击穿 CAS。
 
@@ -402,12 +404,12 @@ game-project/
 - `ResourceDependencyOverlay.tsx` 使用原生 SVG path/marker，绝对定位在 `.game-resource-canvas-content` 底层并统一 `pointer-events: none`。橙色实线表示 `asset-reference`，灰色圆头虚线表示 `task-flow`；两类连线统一使用连续贝塞尔曲线，任务主线略强于两端分支，箭头使用不随高亮线宽缩放的稳定用户空间尺寸，避免直角折线、突兀拐弯和箭头跳变。不引入 D3、React Flow 或其它图表依赖。
 - `asset-reference` 的 source / target 是同一资源时使用卡片右侧外绕贝塞尔闭环，两个锚点分开且 marker 保留在返回锚点；路径不穿过卡片。dependency section 在现有 extent 外额外增加 `64px` 右侧视觉 gutter，确保最右卡片的闭环和箭头可滚动显示；不改卡片坐标、`resourceCanvasLayoutModel.ts` 或 sidecar。
 - 图层用 SVG 自身节点定位所属画布容器，测量各 section plane 相对原点；`ResizeObserver` 在图层挂载时只创建一次，与 window resize 一起负责重新测量并在卸载时清理。type 模式不挂载图层且释放 graph state；项目身份作为 key，切换 mode、项目或工作台卸载都会销毁旧 SVG。
-- 基础 positions 保持稳定，拖动预览单独传入。Pointer Move 通过 `requestAnimationFrame` 合帧；静态 task/reference React SVG 子树不依赖 drag preview，每帧只按局部连接索引重新计算当前资源关联的 edge / flow 并更新对应 path `d`。搜索、选择、项目切换、真实 positions 或 section origin 变化才允许重新协调静态图层；结束后仍只通过原布局 Hook 保存卡片坐标，SVG 几何从不持久化。
-- Rust、前端 DTO/SVG 和工作台 AppSurface 回归覆盖生产 `task-1` 数据形状、真实 producer、证据缺失、精确引用、去重、无效 ID、完整任务环、4096 链式拓扑、聚合复杂度、搜索过滤、选择高亮、局部拖动更新、稳定 Observer、type 模式卸载与项目切换销毁。真实 Chromium 性能目标为拖动 p95 `<16.7ms`、不出现 `>50ms` long task；若实测仍超过预算，再增加 viewport + overscan 边裁剪，不在首轮预先引入额外复杂度。
+- 基础 positions 保持稳定；卡片 Pointer Move 不进入 SVG preview，只有搜索、选择、项目切换、真实 positions 或 section origin 变化才重新协调图层。SVG 几何从不持久化。
+- Rust、前端 DTO/SVG 和工作台 AppSurface 回归覆盖生产 `task-1` 数据形状、真实 producer、证据缺失、精确引用、去重、无效 ID、完整任务环、4096 链式拓扑、聚合复杂度、搜索过滤、选择高亮、稳定 Observer、type 模式卸载与项目切换销毁。局部拖动更新与真实 Chromium 拖动性能目标暂缓。
 
 2026-08-03 评审加固：Rust read model 在现有 producer assignment 上同时返回经完整任务图 SCC 压缩计算的确定性 `dependencyDepth`，前端不再递归推导正式依赖层级。dependency 模式以 scope 化 `idle / loading / ready / failed` 状态阻断布局 Hook；图终态前不创建 fallback、不读取或写入 sidecar，图失败只以空图初始化一次。读取已有 dependency 布局时保留全部 `manuallyPlaced=true` 坐标，把 `manuallyPlaced=false` 作为可派生自动位置按最终深度重新协调；结果未变化时不写入。
 
-拖动热路径不再把 preview 写入工作台父组件 state。卡片使用稳定回调与 `React.memo`，动画帧直接更新拖动卡片 CSS 变量和 section 临时 extent；SVG 图层暴露命令式 preview 句柄，复用 Rust 局部连接索引和已缓存 path 节点，只更新受影响 reference / task-flow 几何。ResizeObserver 仍为单图层单实例。4096 张真实卡片测试必须证明非拖动卡片零重渲染、静态 SVG 子树不重建，Chromium p95 继续以 `<16.7ms` 为门槛。实时 DOM 几何不得通过 Tauri IPC 往返 Rust。
+历史命令式 drag preview 句柄与局部连接索引可以保留，但项目工作台不再向资源卡传入该入口。拖动热路径、4096 张真实卡片拖动重渲染和 Chromium p95 门槛统一暂缓；当前回归只要求 Pointer Move 不改变卡片坐标、SVG path 或布局 revision。`ResizeObserver` 仍保持单图层单实例，任何实时 DOM 几何都不得通过 Tauri IPC 往返 Rust。
 
 ## 分阶段实施
 
@@ -421,7 +423,7 @@ game-project/
 
 - 用户能创建本地 Web 游戏项目。
 - 用户进入项目开发页后能看到资源管理主视窗、陶泥儿对话栏和底部策划 / 美术 / 程序 Agent 状态栏；`1280×800` 最小横屏窗口和更大桌面窗口均不得出现页面级横向 / 纵向溢出，对话输入与底部 Agent 状态栏始终位于视口内。
-- 资源管理可在按依赖 / 按类型之间切换、搜索资源、展开文档和聚焦资源；dependency 模式展示可验证的资源引用和聚合任务流，搜索、选择与拖动同步更新线段；所有展示数据来自当前 manifest、当前资源投影或当前项目导入附件。
+- 资源管理可在按依赖 / 按类型之间切换、搜索资源并点击打开当前资源详情；dependency 模式展示可验证的资源引用和聚合任务流，搜索过滤端点、选择高亮直接上下游。资源卡不可拖动，Pointer Move 不更新坐标、线段或手动布局；所有展示数据来自当前 manifest、当前资源投影或当前项目导入附件。
 - 首个 `code-prototype` 任务未完成时运行入口不可进入并给出可感知提示；完成后可进入运行表现层，真实预览直接加载到客户端内受限运行容器。
 - 审批档位通过独立弹出面板切换，默认严格审批；界面选择不得绕过 Runtime 现有确认门禁。
 - 聊天输入 `/plan` 可在普通聊天消息里查看下一轮分工计划，不读取任务文件、不启动 run、不修改项目，也不新增普通用户计划面板。
-- 
2.52.0


From 2c65878b6078891fe4ef6b35916b0a9a08e522fd Mon Sep 17 00:00:00 2001
From: menghao <mh18530625731@163.com>
Date: Mon, 3 Aug 2026 16:39:43 +0800
Subject: [PATCH 11/27] =?UTF-8?q?=E5=AE=8C=E6=88=90=E8=B5=84=E6=BA=90?=
 =?UTF-8?q?=E5=88=86=E7=B1=BB=E6=8A=95=E5=BD=B1=E4=B8=8E=E4=B8=AD=E5=A4=AE?=
 =?UTF-8?q?=E8=81=9A=E7=84=A6?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

收口文档、版本、美术和音频资源分类
将资源详情改为中央主视窗聚焦并恢复列表上下文
补充资源身份、聚焦状态和依赖图回归测试
同步工作台PRD、技术方案和项目决策记录
---
 apps/ai-game-creator-shell/src/styles.css     | 110 +--
 .../src/view/project-development/index.tsx    | 630 ++++++------------
 .../resourceProjectionModel.ts                | 264 ++++++++
 .../appSurface/project-development.suite.ts   | 129 ++--
 .../projectResourceProjectionModel.test.ts    | 186 ++++++
 ...AI游戏创作】项目开发工作台PRD-2026-07-20.md |  24 +-
 .../shared-memory/decision-log.md             |  11 +-
 ...�案】AI游戏创作智能体App实施计划-2026-06-24.md |  10 +-
 8 files changed, 816 insertions(+), 548 deletions(-)
 create mode 100644 apps/ai-game-creator-shell/src/view/project-development/resourceProjectionModel.ts
 create mode 100644 apps/ai-game-creator-shell/tests/projectResourceProjectionModel.test.ts

diff --git a/apps/ai-game-creator-shell/src/styles.css b/apps/ai-game-creator-shell/src/styles.css
index 3014f539e..e692bba45 100644
--- a/apps/ai-game-creator-shell/src/styles.css
+++ b/apps/ai-game-creator-shell/src/styles.css
@@ -3944,7 +3944,8 @@ iframe.preview-frame {
   stroke-width: 2px;
 }
 
-.game-resource-dependency-edge--task.is-highlighted .game-resource-dependency-trunk {
+.game-resource-dependency-edge--task.is-highlighted
+  .game-resource-dependency-trunk {
   stroke-width: 2.4px;
 }
 
@@ -4092,38 +4093,16 @@ iframe.preview-frame {
   font-size: 9px;
 }
 
-.game-resource-focus-layer {
-  position: fixed;
-  inset: 0;
-  z-index: 240;
-  pointer-events: none;
-}
-
 .game-resource-focus {
-  position: fixed;
-  left: 50%;
-  top: 50%;
   display: grid;
   grid-template-rows: auto minmax(0, 1fr);
-  width: min(520px, calc(100vw - 108px));
-  max-height: min(620px, calc(100dvh - 190px));
+  width: 100%;
+  min-width: 0;
+  min-height: 0;
   overflow: hidden;
-  border: 1px solid #dda07e;
-  border-radius: 16px;
-  background: rgb(255 251 247 / 97%);
+  background: #fffdfa;
   color: #563b31;
-  box-shadow: 0 20px 42px rgb(84 49 34 / 18%);
   outline: 0;
-  pointer-events: auto;
-  transform: translate(-50%, -50%);
-}
-
-.game-resource-focus[style] {
-  transform: none;
-}
-
-.game-resource-focus--art {
-  width: min(760px, calc(100vw - 140px));
 }
 
 .game-resource-focus-titlebar {
@@ -4132,16 +4111,9 @@ iframe.preview-frame {
   justify-content: space-between;
   gap: 12px;
   min-height: 58px;
-  padding: 10px 12px 10px 14px;
+  padding: 10px 14px 10px 16px;
   border-bottom: 1px solid #ead8cf;
   background: #fff8f3;
-  cursor: grab;
-  touch-action: none;
-  user-select: none;
-}
-
-.game-resource-focus-titlebar:active {
-  cursor: grabbing;
 }
 
 .game-resource-focus-heading {
@@ -4151,6 +4123,17 @@ iframe.preview-frame {
   min-width: 0;
 }
 
+.game-resource-focus-heading > span:last-child {
+  display: grid;
+  min-width: 0;
+}
+
+.game-resource-focus-heading small {
+  color: #a27764;
+  font-size: 9px;
+  font-weight: 700;
+}
+
 .game-resource-focus-icon {
   display: grid;
   width: 36px;
@@ -4176,26 +4159,12 @@ iframe.preview-frame {
   align-content: start;
   gap: 6px;
   min-height: 0;
-  padding: 14px 16px 16px;
+  padding: 18px 20px 24px;
   overflow: auto;
   overscroll-behavior: contain;
   scrollbar-gutter: stable;
 }
 
-.game-resource-focus span,
-.game-resource-focus small {
-  overflow-wrap: anywhere;
-}
-
-.game-resource-focus span {
-  font-size: 11px;
-}
-
-.game-resource-focus small {
-  color: #92776c;
-  font-size: 10px;
-}
-
 .game-resource-focus-close {
   display: grid;
   width: 28px;
@@ -4210,10 +4179,43 @@ iframe.preview-frame {
   cursor: pointer;
 }
 
+.game-resource-focus-metadata {
+  display: grid;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  gap: 8px 18px;
+  margin: 0 0 8px;
+  padding: 12px 14px;
+  border: 1px solid #eaded8;
+  border-radius: 12px;
+  background: #fff;
+}
+
+.game-resource-focus-metadata > div {
+  display: grid;
+  grid-template-columns: 72px minmax(0, 1fr);
+  gap: 8px;
+  min-width: 0;
+}
+
+.game-resource-focus-metadata dt,
+.game-resource-focus-metadata dd {
+  margin: 0;
+  overflow-wrap: anywhere;
+  font-size: 10px;
+}
+
+.game-resource-focus-metadata dt {
+  color: #a08377;
+}
+
+.game-resource-focus-metadata dd {
+  color: #5d4339;
+}
+
 .game-resource-image-preview {
   position: relative;
   display: grid;
-  height: min(420px, calc(100dvh - 360px));
+  height: min(460px, calc(100dvh - 330px));
   min-height: 260px;
   margin-bottom: 8px;
   overflow: hidden;
@@ -4251,13 +4253,13 @@ iframe.preview-frame {
 
 .game-resource-document-body {
   height: max-content;
-  min-height: 120px;
+  min-height: 220px;
   margin-top: 6px;
   padding: 14px;
   border-radius: 10px;
   background: #f8f2ee;
-  color: #9e8579;
-  font-size: 11px;
+  color: #765c51;
+  font-size: 12px;
   line-height: 1.6;
   overflow: hidden;
   overflow-wrap: anywhere;
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 0186d1110..41bdd78ea 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
@@ -19,7 +19,6 @@ import {
 import {
   type CSSProperties,
   memo,
-  type PointerEvent as ReactPointerEvent,
   type ReactNode,
   useCallback,
   useEffect,
@@ -36,7 +35,6 @@ import type {
   GameCreationAppManifest,
   GameCreationAppPreviewState,
   ProjectResourceCanvasLayoutMode,
-  ProjectResourceCanvasSection,
 } from '../../../../../packages/shared/src/contracts/gameCreationApp';
 import {
   LocalGamePreviewFrame,
@@ -53,43 +51,25 @@ import {
 } from './resourceDependencyGraphModel';
 import { ResourceDependencyOverlay } from './ResourceDependencyOverlay';
 import { useProjectResourceCanvasLayout } from './useProjectResourceCanvasLayout';
+import {
+  type ProjectAgentResultSummary,
+  type ProjectAttachmentResult,
+  type ProjectResource,
+  type ProjectResourceCategory,
+  type ProjectVersionResourceSummary,
+  projectResourcesFromReadModels,
+} from './resourceProjectionModel';
 
-type AttachmentResult = {
-  fileName: string;
-  mediaType: string;
-  localPath?: string;
-  status: 'imported' | 'failed';
-  error?: string;
-};
+export type {
+  ProjectAgentResultSummary,
+  ProjectVersionResourceSummary,
+} from './resourceProjectionModel';
 
-type ResourceCategory = ProjectResourceCanvasSection;
+type ResourceCategory = ProjectResourceCategory;
 type ResourceSortMode = ProjectResourceCanvasLayoutMode;
 type WorkbenchMode = 'resources' | 'run';
 type ApprovalMode = 'strict' | 'risk' | 'none';
 
-type Point = {
-  x: number;
-  y: number;
-};
-
-type ProjectResource = {
-  id: string;
-  category: ResourceCategory;
-  subtype: string;
-  label: string;
-  path: string;
-  mediaType: string;
-  sourceLabel: string;
-  taskTitle: string | null;
-  manifestAssetId: string | null;
-  producerTaskId: string | null;
-  externalResourceId: string | null;
-  referenceResourceIds: string[];
-  dependencies: string[];
-  dependencyDepth: number;
-  content?: string;
-};
-
 type LocalProjectImagePreview = {
   path: string;
   mediaType: string;
@@ -107,15 +87,6 @@ type ImagePreviewState =
     }
   | { status: 'failed'; resourceId: string; error: string };
 
-export type ProjectAgentResultSummary = {
-  agentId: string;
-  runId: string;
-  label: string;
-  title: string;
-  content: string;
-  updatedAt: number;
-};
-
 export type ProjectAgentRuntimeSummary = {
   group: GameCreationAppAgentGroup;
   label: string;
@@ -130,6 +101,7 @@ export type ProjectAgentRuntimeSummary = {
 
 const emptyProjectAgentRuntimeSummaries: ProjectAgentRuntimeSummary[] = [];
 const emptyProjectAgentResults: ProjectAgentResultSummary[] = [];
+const emptyProjectVersions: ProjectVersionResourceSummary[] = [];
 const RESOURCE_DEPENDENCY_VISUAL_GUTTER = 64;
 
 type AgentSummary = ProjectAgentRuntimeSummary;
@@ -138,12 +110,13 @@ export type ProjectDevelopmentViewProps = {
   projectName: string;
   projectPath: string;
   manifest: GameCreationAppManifest;
-  attachments: AttachmentResult[];
+  attachments: ProjectAttachmentResult[];
   recentRunStatus: string | null;
   recentRunStopReason: string | null;
   preview?: GameCreationAppPreviewState | null;
   agentRuntimeSummaries?: ProjectAgentRuntimeSummary[];
   agentResults?: ProjectAgentResultSummary[];
+  projectVersions?: ProjectVersionResourceSummary[];
   supervisor: ReactNode;
   onHomeOpen: () => void;
   onProjectsOpen: () => void;
@@ -196,36 +169,6 @@ const approvalOptions: Array<{
   },
 ];
 
-function fileName(path: string) {
-  return path.split(/[\\/]/).filter(Boolean).pop() || path;
-}
-
-function categoryFromResource(path: string, mediaType: string) {
-  const normalizedPath = path.toLowerCase();
-  const normalizedMediaType = mediaType.toLowerCase();
-  if (
-    normalizedMediaType.startsWith('audio/') ||
-    /\.(mp3|wav|ogg|m4a|aac|flac)$/u.test(normalizedPath)
-  ) {
-    return 'audio' as const;
-  }
-  if (
-    normalizedMediaType.startsWith('image/') ||
-    normalizedMediaType.startsWith('video/') ||
-    /\.(png|jpe?g|webp|gif|svg|mp4|webm)$/u.test(normalizedPath)
-  ) {
-    return 'art' as const;
-  }
-  if (
-    normalizedMediaType.includes('json') ||
-    normalizedMediaType.startsWith('text/') ||
-    /\.(md|txt|json|ya?ml|toml)$/u.test(normalizedPath)
-  ) {
-    return 'document' as const;
-  }
-  return 'version' as const;
-}
-
 function isRasterImageResource(resource: ProjectResource) {
   const mediaType = resource.mediaType.toLowerCase();
   return (
@@ -264,125 +207,6 @@ function imagePreviewErrorMessage(error: unknown) {
   return '图片暂时无法读取，请关闭后重试';
 }
 
-function resourcesFromProject(
-  manifest: GameCreationAppManifest,
-  attachments: AttachmentResult[],
-  agentResults: ProjectAgentResultSummary[],
-) {
-  const taskById = new Map(manifest.tasks.map((task) => [task.id, task]));
-  const resources: ProjectResource[] = [];
-
-  for (const task of manifest.tasks) {
-    if (task.status !== 'completed') {
-      continue;
-    }
-    for (const path of task.artifacts) {
-      const category = categoryFromResource(path, '');
-      resources.push({
-        id: `task:${task.id}:${path}`,
-        category,
-        subtype: 'task-artifact',
-        label: fileName(path),
-        path,
-        mediaType: category === 'document' ? '项目文档' : '项目产物',
-        sourceLabel: '任务产物',
-        taskTitle: task.title,
-        manifestAssetId: null,
-        producerTaskId: task.id,
-        externalResourceId: null,
-        referenceResourceIds: [],
-        dependencies: task.dependencies,
-        dependencyDepth: 0,
-      });
-    }
-  }
-
-  for (const asset of manifest.assets) {
-    const isPendingUiPrototype =
-      asset.kind === 'ui-prototype' &&
-      taskById.get('design-foundation')?.status !== 'completed';
-    resources.push({
-      id: `asset:${asset.id}`,
-      category: categoryFromResource(asset.localPath, asset.mediaType),
-      subtype: asset.kind,
-      label: `${fileName(asset.localPath)}${
-        isPendingUiPrototype ? '（待视觉验收）' : ''
-      }`,
-      path: asset.localPath,
-      mediaType: asset.mediaType,
-      sourceLabel:
-        isPendingUiPrototype && asset.source.kind === 'canvas'
-          ? '画板 · 候选界面图'
-          : asset.source.kind === 'canvas'
-            ? '画板'
-            : asset.source.kind === 'generated'
-              ? 'Agent 生成'
-              : '用户上传',
-      taskTitle: null,
-      manifestAssetId: asset.id,
-      producerTaskId: null,
-      externalResourceId: asset.source.resourceId ?? null,
-      referenceResourceIds: asset.source.referenceResourceIds ?? [],
-      dependencies: [],
-      dependencyDepth: 0,
-    });
-  }
-
-  for (const attachment of attachments) {
-    if (attachment.status !== 'imported' || !attachment.localPath) {
-      continue;
-    }
-    resources.push({
-      id: `attachment:${attachment.localPath}`,
-      category: categoryFromResource(
-        attachment.localPath,
-        attachment.mediaType,
-      ),
-      subtype: 'attachment',
-      label: attachment.fileName,
-      path: attachment.localPath,
-      mediaType: attachment.mediaType || '未知媒体类型',
-      sourceLabel: '用户上传',
-      taskTitle: null,
-      manifestAssetId: null,
-      producerTaskId: null,
-      externalResourceId: null,
-      referenceResourceIds: [],
-      dependencies: [],
-      dependencyDepth: 0,
-    });
-  }
-
-  for (const result of agentResults) {
-    resources.push({
-      id: `agent-result:${result.agentId}:${result.runId}`,
-      category: 'document',
-      subtype: 'agent-result',
-      label: result.title,
-      path: `专业 Agent 文本回执 · ${result.label}`,
-      mediaType: 'Agent 历史文本回执',
-      sourceLabel: `历史成果 · ${result.label}`,
-      taskTitle: null,
-      manifestAssetId: null,
-      producerTaskId: taskById.has(result.agentId) ? result.agentId : null,
-      externalResourceId: null,
-      referenceResourceIds: [],
-      dependencies: [],
-      dependencyDepth: 0,
-      content: result.content,
-    });
-  }
-
-  const uniqueByPath = new Map<string, ProjectResource>();
-  for (const resource of resources) {
-    const existing = uniqueByPath.get(resource.path);
-    if (!existing || resource.id.startsWith('asset:')) {
-      uniqueByPath.set(resource.path, resource);
-    }
-  }
-  return Array.from(uniqueByPath.values());
-}
-
 function summarizeAgent(
   manifest: GameCreationAppManifest,
   group: AgentSummary['group'],
@@ -477,6 +301,7 @@ export default function ProjectDevelopmentView({
   preview: previewOverride,
   agentRuntimeSummaries = emptyProjectAgentRuntimeSummaries,
   agentResults = emptyProjectAgentResults,
+  projectVersions = emptyProjectVersions,
   supervisor,
 }: ProjectDevelopmentViewProps) {
   const [mode, setMode] = useState<WorkbenchMode>('resources');
@@ -485,27 +310,23 @@ export default function ProjectDevelopmentView({
   const [selectedResourceId, setSelectedResourceId] = useState<string | null>(
     null,
   );
+  const [focusedResourceId, setFocusedResourceId] = useState<string | null>(
+    null,
+  );
   const [approvalMode, setApprovalMode] = useState<ApprovalMode>('strict');
   const [approvalDialogOpen, setApprovalDialogOpen] = useState(false);
   const [approvalNotice, setApprovalNotice] = useState('');
   const [showAllAgentGroups, setShowAllAgentGroups] = useState(false);
   const [runPlaying, setRunPlaying] = useState(false);
   const [activeSlice, setActiveSlice] = useState(0);
-  const [resourceDialogPosition, setResourceDialogPosition] =
-    useState<Point | null>(null);
   const [imagePreview, setImagePreview] = useState<ImagePreviewState>({
     status: 'idle',
     resourceId: null,
   });
-  const workbenchRef = useRef<HTMLElement>(null);
-  const stageRef = useRef<HTMLElement>(null);
-  const dockRef = useRef<HTMLElement>(null);
-  const resourceDialogRef = useRef<HTMLElement>(null);
-  const resourceDialogDragRef = useRef<{
-    pointerId: number;
-    offsetX: number;
-    offsetY: number;
-  } | null>(null);
+  const resourceCanvasRef = useRef<HTMLDivElement>(null);
+  const resourceFocusRef = useRef<HTMLElement>(null);
+  const resourceListScrollRef = useRef({ left: 0, top: 0 });
+  const restoreResourceListScrollRef = useRef(false);
 
   const preview = previewOverride ?? manifest.preview ?? null;
   const embeddedPreviewUrl = resolveEmbeddedPreviewUrl(preview);
@@ -515,8 +336,14 @@ export default function ProjectDevelopmentView({
       (task) => task.id === 'code-prototype' && task.status === 'completed',
     );
   const projectedResources = useMemo(
-    () => resourcesFromProject(manifest, attachments, agentResults),
-    [agentResults, attachments, manifest],
+    () =>
+      projectResourcesFromReadModels(
+        manifest,
+        attachments,
+        agentResults,
+        projectVersions,
+      ),
+    [agentResults, attachments, manifest, projectVersions],
   );
   const resourceGraphInputs = useMemo<ProjectResourceGraphNodeInput[]>(
     () =>
@@ -529,11 +356,7 @@ export default function ProjectDevelopmentView({
   );
   const resourceGraphScopeKey = useMemo(
     () =>
-      JSON.stringify([
-        projectPath,
-        manifest.projectId,
-        resourceGraphInputs,
-      ]),
+      JSON.stringify([projectPath, manifest.projectId, resourceGraphInputs]),
     [manifest.projectId, projectPath, resourceGraphInputs],
   );
   const [resourceGraphState, setResourceGraphState] = useState<{
@@ -615,10 +438,9 @@ export default function ProjectDevelopmentView({
     resourceGraphState.scopeKey === resourceGraphScopeKey;
   const resourceGraphReady =
     resourceGraphScopeMatches && resourceGraphState.status === 'ready';
-  const resourceGraph =
-    resourceGraphReady
-      ? resourceGraphState.graph
-      : EMPTY_PROJECT_RESOURCE_GRAPH;
+  const resourceGraph = resourceGraphReady
+    ? resourceGraphState.graph
+    : EMPTY_PROJECT_RESOURCE_GRAPH;
   const resourceGraphInitializationReady =
     sortMode !== 'dependency' ||
     (resourceGraphScopeMatches &&
@@ -658,8 +480,7 @@ export default function ProjectDevelopmentView({
     mode: sortMode,
     resources,
     initializationReady: resourceGraphInitializationReady,
-    rederiveAutomaticPositions:
-      sortMode === 'dependency' && resourceGraphReady,
+    rederiveAutomaticPositions: sortMode === 'dependency' && resourceGraphReady,
   });
   const resourcePositionById = useMemo(
     () =>
@@ -699,9 +520,7 @@ export default function ProjectDevelopmentView({
       new Map(
         categoryOrder.map((category) => [
           category,
-          visibleResources.filter(
-            (resource) => resource.category === category,
-          ),
+          visibleResources.filter((resource) => resource.category === category),
         ]),
       ),
     [visibleResources],
@@ -732,8 +551,10 @@ export default function ProjectDevelopmentView({
   );
   const selectedResource =
     resources.find((resource) => resource.id === selectedResourceId) ?? null;
-  const selectedResourceIsImage = Boolean(
-    selectedResource && isRasterImageResource(selectedResource),
+  const focusedResource =
+    resources.find((resource) => resource.id === focusedResourceId) ?? null;
+  const focusedResourceIsImage = Boolean(
+    focusedResource && isRasterImageResource(focusedResource),
   );
   const hasRegisteredArtImageAssets = manifest.assets.some(
     (asset) =>
@@ -770,32 +591,40 @@ export default function ProjectDevelopmentView({
   const currentApprovalLabel =
     approvalOptions.find((option) => option.id === approvalMode)?.label ??
     '严格审批';
+  const FocusIcon = focusedResource
+    ? categoryIcons[focusedResource.category]
+    : FileText;
 
   useEffect(() => {
     if (embeddedPreviewUrl) {
+      setFocusedResourceId(null);
       setMode('run');
     }
   }, [embeddedPreviewUrl]);
 
   useEffect(() => {
     setSelectedResourceId(null);
+    setFocusedResourceId(null);
+    resourceListScrollRef.current = { left: 0, top: 0 };
+    restoreResourceListScrollRef.current = false;
   }, [projectPath]);
 
   useEffect(() => {
-    if (!selectedResourceId) {
+    if (!focusedResourceId) {
       return undefined;
     }
     function closeOnEscape(event: KeyboardEvent) {
       if (event.key === 'Escape') {
-        setSelectedResourceId(null);
+        restoreResourceListScrollRef.current = true;
+        setFocusedResourceId(null);
       }
     }
     window.addEventListener('keydown', closeOnEscape);
     return () => window.removeEventListener('keydown', closeOnEscape);
-  }, [selectedResourceId]);
+  }, [focusedResourceId]);
 
   useEffect(() => {
-    if (!selectedResource || !selectedResourceIsImage) {
+    if (!focusedResource || !focusedResourceIsImage) {
       setImagePreview({ status: 'idle', resourceId: null });
       return undefined;
     }
@@ -803,23 +632,23 @@ export default function ProjectDevelopmentView({
     if (!invoke) {
       setImagePreview({
         status: 'failed',
-        resourceId: selectedResource.id,
+        resourceId: focusedResource.id,
         error: '图片预览需要在客户端内打开',
       });
       return undefined;
     }
 
     let cancelled = false;
-    setImagePreview({ status: 'loading', resourceId: selectedResource.id });
+    setImagePreview({ status: 'loading', resourceId: focusedResource.id });
     void invoke<LocalProjectImagePreview>('read_local_project_image_preview', {
       projectPath,
-      relativePath: selectedResource.path,
+      relativePath: focusedResource.path,
     })
       .then((preview) => {
         if (!cancelled) {
           setImagePreview({
             status: 'loaded',
-            resourceId: selectedResource.id,
+            resourceId: focusedResource.id,
             preview,
           });
         }
@@ -828,7 +657,7 @@ export default function ProjectDevelopmentView({
         if (!cancelled) {
           setImagePreview({
             status: 'failed',
-            resourceId: selectedResource.id,
+            resourceId: focusedResource.id,
             error: imagePreviewErrorMessage(error),
           });
         }
@@ -836,142 +665,65 @@ export default function ProjectDevelopmentView({
     return () => {
       cancelled = true;
     };
-  }, [projectPath, selectedResource, selectedResourceIsImage]);
-
-  const clampResourceDialogPosition = useCallback((x: number, y: number) => {
-    const dialog = resourceDialogRef.current;
-    const workbench = workbenchRef.current;
-    const dock = dockRef.current;
-    if (!dialog) {
-      return { x, y };
-    }
-
-    const dialogRect = dialog.getBoundingClientRect();
-    const workbenchRect = workbench?.getBoundingClientRect();
-    const dockRect = dock?.getBoundingClientRect();
-    const viewportWidth = document.documentElement.clientWidth;
-    const viewportHeight = document.documentElement.clientHeight;
-    const minX = Math.max(12, (workbenchRect?.left ?? 0) + 12);
-    const maxRight = Math.min(
-      viewportWidth - 12,
-      (workbenchRect?.right ?? viewportWidth) - 12,
-    );
-    const minY = Math.max(12, (workbenchRect?.top ?? 0) + 12);
-    const maxBottom = Math.min(
-      viewportHeight - 12,
-      dockRect ? dockRect.top - 12 : viewportHeight - 12,
-    );
-    const maxX = Math.max(minX, maxRight - dialogRect.width);
-    const maxY = Math.max(minY, maxBottom - dialogRect.height);
-
-    return {
-      x: Math.min(Math.max(x, minX), maxX),
-      y: Math.min(Math.max(y, minY), maxY),
-    };
-  }, []);
+  }, [focusedResource, focusedResourceIsImage, projectPath]);
 
   useLayoutEffect(() => {
-    if (!selectedResource) {
-      setResourceDialogPosition(null);
+    if (focusedResource) {
+      resourceFocusRef.current?.focus({ preventScroll: true });
       return;
     }
-    const dialog = resourceDialogRef.current;
-    const stage = stageRef.current;
-    if (!dialog || !stage) {
+    if (!restoreResourceListScrollRef.current) {
       return;
     }
-    const dialogRect = dialog.getBoundingClientRect();
-    const stageRect = stage.getBoundingClientRect();
-    setResourceDialogPosition(
-      clampResourceDialogPosition(
-        stageRect.left + (stageRect.width - dialogRect.width) / 2,
-        stageRect.top + (stageRect.height - dialogRect.height) / 2,
-      ),
-    );
-    dialog.focus({ preventScroll: true });
-  }, [clampResourceDialogPosition, selectedResource]);
-
-  useEffect(() => {
-    if (!selectedResource) {
-      return undefined;
+    const canvas = resourceCanvasRef.current;
+    if (canvas) {
+      canvas.scrollLeft = resourceListScrollRef.current.left;
+      canvas.scrollTop = resourceListScrollRef.current.top;
+      restoreResourceListScrollRef.current = false;
     }
-    function clampOnResize() {
-      setResourceDialogPosition((current) =>
-        current ? clampResourceDialogPosition(current.x, current.y) : current,
-      );
-    }
-    window.addEventListener('resize', clampOnResize);
-    return () => window.removeEventListener('resize', clampOnResize);
-  }, [clampResourceDialogPosition, selectedResource]);
+  }, [focusedResource]);
 
   const handleResourceSelect = useCallback((resourceId: string) => {
+    const canvas = resourceCanvasRef.current;
+    if (canvas) {
+      resourceListScrollRef.current = {
+        left: canvas.scrollLeft,
+        top: canvas.scrollTop,
+      };
+    }
     setSelectedResourceId(resourceId);
+    setFocusedResourceId(resourceId);
   }, []);
 
-  function handleResourceDialogPointerDown(
-    event: ReactPointerEvent<HTMLElement>,
-  ) {
-    if (event.button !== 0 || (event.target as HTMLElement).closest('button')) {
-      return;
-    }
-    const dialogRect = resourceDialogRef.current?.getBoundingClientRect();
-    if (!dialogRect) {
-      return;
-    }
-    resourceDialogDragRef.current = {
-      pointerId: event.pointerId,
-      offsetX: event.clientX - dialogRect.left,
-      offsetY: event.clientY - dialogRect.top,
-    };
-    event.currentTarget.setPointerCapture(event.pointerId);
-    event.preventDefault();
-  }
-
-  function handleResourceDialogPointerMove(
-    event: ReactPointerEvent<HTMLElement>,
-  ) {
-    const drag = resourceDialogDragRef.current;
-    if (!drag || drag.pointerId !== event.pointerId) {
-      return;
-    }
-    setResourceDialogPosition(
-      clampResourceDialogPosition(
-        event.clientX - drag.offsetX,
-        event.clientY - drag.offsetY,
-      ),
-    );
-  }
-
-  function handleResourceDialogPointerEnd(
-    event: ReactPointerEvent<HTMLElement>,
-  ) {
-    if (resourceDialogDragRef.current?.pointerId !== event.pointerId) {
-      return;
-    }
-    resourceDialogDragRef.current = null;
-    if (event.currentTarget.hasPointerCapture(event.pointerId)) {
-      event.currentTarget.releasePointerCapture(event.pointerId);
-    }
+  function closeResourceFocus() {
+    restoreResourceListScrollRef.current = true;
+    setFocusedResourceId(null);
   }
 
   function showRunView() {
     if (!runAvailable) {
       return;
     }
+    setFocusedResourceId(null);
     setMode('run');
   }
 
   return (
     <section
-      ref={workbenchRef}
       className="launcher-page launcher-project-development game-project-workbench"
       aria-label="项目开发工作台"
     >
       <div className="game-workbench-layout">
         <section
-          ref={stageRef}
           className="game-workbench-stage"
           aria-label="项目主视窗"
+          data-resource-view-state={
+            mode === 'resources'
+              ? focusedResource
+                ? `resources.focused.${focusedResource.category}`
+                : 'resources.list'
+              : undefined
+          }
         >
           <div className="game-workbench-toolbar">
             <div className="game-workbench-tabs" role="tablist">
@@ -999,7 +751,7 @@ export default function ProjectDevelopmentView({
               </button>
             </div>
             <div className="game-workbench-view-actions">
-              {mode === 'resources' ? (
+              {mode === 'resources' && !focusedResource ? (
                 <>
                   <button
                     type="button"
@@ -1031,7 +783,7 @@ export default function ProjectDevelopmentView({
             </div>
           </div>
 
-          {!runAvailable ? (
+          {!runAvailable && !focusedResource ? (
             <p
               id="run-unavailable-hint"
               className="game-run-unavailable"
@@ -1041,7 +793,107 @@ export default function ProjectDevelopmentView({
             </p>
           ) : null}
 
-          {mode === 'resources' ? (
+          {mode === 'resources' && focusedResource ? (
+            <section
+              ref={resourceFocusRef}
+              className={`game-resource-focus game-resource-focus--${focusedResource.category}`}
+              aria-labelledby="game-resource-focus-title"
+              role="region"
+              tabIndex={-1}
+            >
+              <header className="game-resource-focus-titlebar">
+                <span className="game-resource-focus-heading">
+                  <span className="game-resource-focus-icon">
+                    <FocusIcon size={22} aria-hidden="true" />
+                  </span>
+                  <span>
+                    <small>{categoryLabels[focusedResource.category]}</small>
+                    <strong id="game-resource-focus-title">
+                      {focusedResource.label}
+                    </strong>
+                  </span>
+                </span>
+                <button
+                  type="button"
+                  className="game-resource-focus-close"
+                  aria-label="收起资源"
+                  onClick={closeResourceFocus}
+                >
+                  <X size={16} aria-hidden="true" />
+                </button>
+              </header>
+              <div className="game-resource-focus-body">
+                {focusedResourceIsImage ? (
+                  <div
+                    className="game-resource-image-preview"
+                    aria-label={`${focusedResource.label} 图片预览`}
+                  >
+                    {imagePreview.status === 'loaded' &&
+                    imagePreview.resourceId === focusedResource.id ? (
+                      <img
+                        src={imagePreview.preview.dataUrl}
+                        alt={`${focusedResource.label} 图片预览`}
+                        onError={() =>
+                          setImagePreview({
+                            status: 'failed',
+                            resourceId: focusedResource.id,
+                            error: '图片内容无法解码，请重新生成或替换该资源',
+                          })
+                        }
+                      />
+                    ) : imagePreview.status === 'failed' &&
+                      imagePreview.resourceId === focusedResource.id ? (
+                      <p role="alert">{imagePreview.error}</p>
+                    ) : (
+                      <p role="status">正在载入图片…</p>
+                    )}
+                  </div>
+                ) : null}
+                <dl className="game-resource-focus-metadata">
+                  <div>
+                    <dt>资源路径</dt>
+                    <dd>{focusedResource.path}</dd>
+                  </div>
+                  <div>
+                    <dt>资源类型</dt>
+                    <dd>{focusedResource.mediaType}</dd>
+                  </div>
+                  <div>
+                    <dt>资源来源</dt>
+                    <dd>{focusedResource.sourceLabel}</dd>
+                  </div>
+                  {focusedResource.taskTitle ? (
+                    <div>
+                      <dt>来源任务</dt>
+                      <dd>{focusedResource.taskTitle}</dd>
+                    </div>
+                  ) : null}
+                  {focusedResource.version ? (
+                    <>
+                      <div>
+                        <dt>项目修订</dt>
+                        <dd>{focusedResource.version.projectRevision}</dd>
+                      </div>
+                      <div>
+                        <dt>父版本</dt>
+                        <dd>
+                          {focusedResource.version.parentVersionId ??
+                            '首个版本'}
+                        </dd>
+                      </div>
+                    </>
+                  ) : null}
+                </dl>
+                {focusedResource.category === 'document' ? (
+                  <div className="game-resource-document-body">
+                    <ReactMarkdown remarkPlugins={[remarkGfm]}>
+                      {focusedResource.content ?? '文档内容尚未载入'}
+                    </ReactMarkdown>
+                  </div>
+                ) : null}
+              </div>
+            </section>
+          ) : mode === 'resources' ? (
             <div className="game-resource-manager">
               <label className="game-resource-search">
                 <Search size={16} aria-hidden="true" />
@@ -1072,6 +924,7 @@ export default function ProjectDevelopmentView({
                 </section>
               ) : null}
               <div
+                ref={resourceCanvasRef}
                 className={`game-resource-canvas game-resource-canvas--${sortMode}`}
                 aria-label={
                   sortMode === 'dependency' ? '资源依赖视图' : '资源类型视图'
@@ -1294,11 +1147,7 @@ export default function ProjectDevelopmentView({
         </aside>
       </div>
 
-      <footer
-        ref={dockRef}
-        className="game-agent-dock"
-        aria-label="子 Agent 状态栏"
-      >
+      <footer className="game-agent-dock" aria-label="子 Agent 状态栏">
         {agentSummaries.map((agent) => (
           <article
             className={`game-agent-dock-item is-${agent.status}`}
@@ -1348,99 +1197,6 @@ export default function ProjectDevelopmentView({
         </button>
       </footer>
 
-      {selectedResource ? (
-        <div className="game-resource-focus-layer">
-          <aside
-            ref={resourceDialogRef}
-            className={`game-resource-focus game-resource-focus--${selectedResource.category}`}
-            aria-label="资源焦点"
-            aria-labelledby="game-resource-focus-title"
-            role="dialog"
-            tabIndex={-1}
-            style={
-              resourceDialogPosition
-                ? {
-                    left: resourceDialogPosition.x,
-                    top: resourceDialogPosition.y,
-                  }
-                : undefined
-            }
-          >
-            <header
-              className="game-resource-focus-titlebar"
-              onPointerDown={handleResourceDialogPointerDown}
-              onPointerMove={handleResourceDialogPointerMove}
-              onPointerUp={handleResourceDialogPointerEnd}
-              onPointerCancel={handleResourceDialogPointerEnd}
-            >
-              <span className="game-resource-focus-heading">
-                <span className="game-resource-focus-icon">
-                  {selectedResource.category === 'document' ? (
-                    <FileText size={22} aria-hidden="true" />
-                  ) : selectedResource.category === 'audio' ? (
-                    <Music2 size={22} aria-hidden="true" />
-                  ) : (
-                    <Image size={22} aria-hidden="true" />
-                  )}
-                </span>
-                <strong id="game-resource-focus-title">
-                  {selectedResource.label}
-                </strong>
-              </span>
-              <button
-                type="button"
-                className="game-resource-focus-close"
-                aria-label="收起资源"
-                onClick={() => setSelectedResourceId(null)}
-              >
-                <X size={16} aria-hidden="true" />
-              </button>
-            </header>
-            <div className="game-resource-focus-body">
-              {selectedResourceIsImage ? (
-                <div
-                  className="game-resource-image-preview"
-                  aria-label={`${selectedResource.label} 图片预览`}
-                >
-                  {imagePreview.status === 'loaded' &&
-                  imagePreview.resourceId === selectedResource.id ? (
-                    <img
-                      src={imagePreview.preview.dataUrl}
-                      alt={`${selectedResource.label} 图片预览`}
-                      onError={() =>
-                        setImagePreview({
-                          status: 'failed',
-                          resourceId: selectedResource.id,
-                          error: '图片内容无法解码，请重新生成或替换该资源',
-                        })
-                      }
-                    />
-                  ) : imagePreview.status === 'failed' &&
-                    imagePreview.resourceId === selectedResource.id ? (
-                    <p role="alert">{imagePreview.error}</p>
-                  ) : (
-                    <p role="status">正在载入图片…</p>
-                  )}
-                </div>
-              ) : null}
-              <span>{selectedResource.path}</span>
-              <small>{selectedResource.mediaType}</small>
-              <small>{selectedResource.sourceLabel}</small>
-              {selectedResource.taskTitle ? (
-                <small>{`来源任务：${selectedResource.taskTitle}`}</small>
-              ) : null}
-              {selectedResource.category === 'document' ? (
-                <div className="game-resource-document-body">
-                  <ReactMarkdown remarkPlugins={[remarkGfm]}>
-                    {selectedResource.content ?? '文档内容尚未载入'}
-                  </ReactMarkdown>
-                </div>
-              ) : null}
-            </div>
-          </aside>
-        </div>
-      ) : null}
-
       {approvalDialogOpen ? (
         <div
           className="game-approval-backdrop"
diff --git a/apps/ai-game-creator-shell/src/view/project-development/resourceProjectionModel.ts b/apps/ai-game-creator-shell/src/view/project-development/resourceProjectionModel.ts
new file mode 100644
index 000000000..f084a475d
--- /dev/null
+++ b/apps/ai-game-creator-shell/src/view/project-development/resourceProjectionModel.ts
@@ -0,0 +1,264 @@
+import type {
+  GameCreationAppManifest,
+  ProjectResourceCanvasSection,
+} from '../../../../../packages/shared/src/contracts/gameCreationApp';
+
+export type ProjectResourceCategory = ProjectResourceCanvasSection;
+
+export type ProjectAttachmentResult = {
+  fileName: string;
+  mediaType: string;
+  localPath?: string;
+  status: 'imported' | 'failed';
+  error?: string;
+};
+
+export type ProjectAgentResultSummary = {
+  agentId: string;
+  runId: string;
+  label: string;
+  title: string;
+  content: string;
+  updatedAt: number;
+};
+
+export type ProjectVersionResourceSummary = {
+  versionId: string;
+  label: string;
+  projectRevision: number;
+  parentVersionId: string | null;
+  createdAt: number;
+};
+
+export type ProjectResource = {
+  id: string;
+  category: ProjectResourceCategory;
+  subtype: string;
+  label: string;
+  path: string;
+  mediaType: string;
+  sourceLabel: string;
+  taskTitle: string | null;
+  manifestAssetId: string | null;
+  producerTaskId: string | null;
+  externalResourceId: string | null;
+  referenceResourceIds: string[];
+  dependencies: string[];
+  dependencyDepth: number;
+  content?: string;
+  version?: ProjectVersionResourceSummary;
+};
+
+const documentExtension = /\.(md|markdown|mdx|txt|json|ya?ml|toml)$/iu;
+const artExtension = /\.(png|jpe?g|webp|gif|svg|avif|bmp|mp4|webm|mov)$/iu;
+const audioExtension = /\.(mp3|wav|ogg|m4a|aac|flac|opus)$/iu;
+const artKind =
+  /(?:^|[-_])(art|animation|character|icon|image|scene|sprite|spritesheet|ui|video)(?:$|[-_])/iu;
+const audioKind = /(?:^|[-_])(audio|bgm|music|sfx|sound|voice)(?:$|[-_])/iu;
+
+function fileName(path: string) {
+  return path.split(/[\\/]/u).filter(Boolean).pop() || path;
+}
+
+export function classifyProjectedResource(input: {
+  path: string;
+  mediaType: string;
+  kind?: string;
+}): Exclude<ProjectResourceCategory, 'version'> | null {
+  const normalizedPath = input.path.trim().toLowerCase();
+  const normalizedMediaType = input.mediaType.trim().toLowerCase();
+  const normalizedKind = input.kind?.trim().toLowerCase() ?? '';
+
+  if (
+    normalizedMediaType.startsWith('audio/') ||
+    audioExtension.test(normalizedPath) ||
+    audioKind.test(normalizedKind)
+  ) {
+    return 'audio';
+  }
+  if (
+    normalizedMediaType.startsWith('image/') ||
+    normalizedMediaType.startsWith('video/') ||
+    artExtension.test(normalizedPath) ||
+    artKind.test(normalizedKind)
+  ) {
+    return 'art';
+  }
+  if (
+    normalizedMediaType.includes('json') ||
+    normalizedMediaType.includes('yaml') ||
+    normalizedMediaType.startsWith('text/') ||
+    documentExtension.test(normalizedPath)
+  ) {
+    return 'document';
+  }
+  return null;
+}
+
+function resourcePriority(resource: ProjectResource) {
+  if (resource.manifestAssetId) {
+    return 4;
+  }
+  if (resource.id.startsWith('attachment:')) {
+    return 3;
+  }
+  if (resource.id.startsWith('task:')) {
+    return 2;
+  }
+  return 1;
+}
+
+export function projectResourcesFromReadModels(
+  manifest: GameCreationAppManifest,
+  attachments: ProjectAttachmentResult[],
+  agentResults: ProjectAgentResultSummary[],
+  projectVersions: ProjectVersionResourceSummary[] = [],
+) {
+  const taskById = new Map(manifest.tasks.map((task) => [task.id, task]));
+  const resources: ProjectResource[] = [];
+
+  for (const task of manifest.tasks) {
+    if (task.status !== 'completed') {
+      continue;
+    }
+    for (const path of task.artifacts) {
+      const category = classifyProjectedResource({ path, mediaType: '' });
+      if (!category || category === 'audio') {
+        continue;
+      }
+      resources.push({
+        id: `task:${task.id}:${path}`,
+        category,
+        subtype: 'task-artifact',
+        label: fileName(path),
+        path,
+        mediaType: category === 'document' ? '项目文档' : '美术产物',
+        sourceLabel: '任务产物',
+        taskTitle: task.title,
+        manifestAssetId: null,
+        producerTaskId: task.id,
+        externalResourceId: null,
+        referenceResourceIds: [],
+        dependencies: task.dependencies,
+        dependencyDepth: 0,
+      });
+    }
+  }
+
+  for (const asset of manifest.assets) {
+    const category = classifyProjectedResource({
+      path: asset.localPath,
+      mediaType: asset.mediaType,
+      kind: asset.kind,
+    });
+    if (!category) {
+      continue;
+    }
+    const isPendingUiPrototype =
+      asset.kind === 'ui-prototype' &&
+      taskById.get('design-foundation')?.status !== 'completed';
+    resources.push({
+      id: `asset:${asset.id}`,
+      category,
+      subtype: asset.kind,
+      label: `${fileName(asset.localPath)}${
+        isPendingUiPrototype ? '（待视觉验收）' : ''
+      }`,
+      path: asset.localPath,
+      mediaType: asset.mediaType,
+      sourceLabel:
+        isPendingUiPrototype && asset.source.kind === 'canvas'
+          ? '画板 · 候选界面图'
+          : asset.source.kind === 'canvas'
+            ? '画板'
+            : asset.source.kind === 'generated'
+              ? 'Agent 生成'
+              : '用户上传',
+      taskTitle: null,
+      manifestAssetId: asset.id,
+      producerTaskId: null,
+      externalResourceId: asset.source.resourceId ?? null,
+      referenceResourceIds: asset.source.referenceResourceIds ?? [],
+      dependencies: [],
+      dependencyDepth: 0,
+    });
+  }
+
+  for (const attachment of attachments) {
+    if (attachment.status !== 'imported' || !attachment.localPath) {
+      continue;
+    }
+    const category = classifyProjectedResource({
+      path: attachment.localPath,
+      mediaType: attachment.mediaType,
+    });
+    if (!category) {
+      continue;
+    }
+    resources.push({
+      id: `attachment:${attachment.localPath}`,
+      category,
+      subtype: 'attachment',
+      label: attachment.fileName,
+      path: attachment.localPath,
+      mediaType: attachment.mediaType || '未知媒体类型',
+      sourceLabel: '用户上传',
+      taskTitle: null,
+      manifestAssetId: null,
+      producerTaskId: null,
+      externalResourceId: null,
+      referenceResourceIds: [],
+      dependencies: [],
+      dependencyDepth: 0,
+    });
+  }
+
+  for (const result of agentResults) {
+    resources.push({
+      id: `agent-result:${result.agentId}:${result.runId}`,
+      category: 'document',
+      subtype: 'agent-result',
+      label: result.title,
+      path: `专业 Agent 文本回执 · ${result.label}`,
+      mediaType: 'Agent 历史文本回执',
+      sourceLabel: `历史成果 · ${result.label}`,
+      taskTitle: null,
+      manifestAssetId: null,
+      producerTaskId: taskById.has(result.agentId) ? result.agentId : null,
+      externalResourceId: null,
+      referenceResourceIds: [],
+      dependencies: [],
+      dependencyDepth: 0,
+      content: result.content,
+    });
+  }
+
+  for (const version of projectVersions) {
+    resources.push({
+      id: `version:${version.versionId}`,
+      category: 'version',
+      subtype: 'project-version',
+      label: version.label,
+      path: `项目版本 · ${version.versionId}`,
+      mediaType: '正式项目版本',
+      sourceLabel: `项目修订 ${version.projectRevision}`,
+      taskTitle: null,
+      manifestAssetId: null,
+      producerTaskId: null,
+      externalResourceId: null,
+      referenceResourceIds: [],
+      dependencies: [],
+      dependencyDepth: 0,
+      version,
+    });
+  }
+
+  const uniqueByPath = new Map<string, ProjectResource>();
+  for (const resource of resources) {
+    const existing = uniqueByPath.get(resource.path);
+    if (!existing || resourcePriority(resource) > resourcePriority(existing)) {
+      uniqueByPath.set(resource.path, resource);
+    }
+  }
+  return Array.from(uniqueByPath.values());
+}
diff --git a/apps/ai-game-creator-shell/tests/appSurface/project-development.suite.ts b/apps/ai-game-creator-shell/tests/appSurface/project-development.suite.ts
index ba3db4787..866cca49c 100644
--- a/apps/ai-game-creator-shell/tests/appSurface/project-development.suite.ts
+++ b/apps/ai-game-creator-shell/tests/appSurface/project-development.suite.ts
@@ -676,7 +676,7 @@ export function registerProjectWorkbenchFoundationTests() {
     expect(screen.getByRole('article', { name: /发布 Agent/ })).not.toBeNull();
   });
 
-  it('keeps project chrome out and opens text receipts from non-draggable resource cards', () => {
+  it('opens text receipts in the central focus state and restores the resource list context', () => {
     const manifest = createGameCreationAppManifest(
       'workbench-resource-details',
       '不应显示的项目标题',
@@ -735,6 +735,17 @@ export function registerProjectWorkbenchFoundationTests() {
       screen.getByText('美术资源计划已完成，尚未生成或登记图片'),
     ).not.toBeNull();
 
+    fireEvent.click(screen.getByRole('button', { name: '按类型' }));
+    const searchInput = screen.getByLabelText(
+      '搜索项目资源',
+    ) as HTMLInputElement;
+    fireEvent.change(searchInput, { target: { value: '美术资源计划' } });
+    const resourceCanvas = screen.getByLabelText(
+      '资源类型视图',
+    ) as HTMLDivElement;
+    resourceCanvas.scrollLeft = 48;
+    resourceCanvas.scrollTop = 36;
+
     const resourceCards = screen.getAllByTitle('打开资源详情');
     const artReceiptCard = resourceCards.find((card) =>
       card.textContent?.includes('美术资源计划 Agent 文本回执'),
@@ -770,22 +781,59 @@ export function registerProjectWorkbenchFoundationTests() {
     expect(styles).not.toMatch(/\.game-resource-card\.is-dragging/);
 
     fireEvent.click(artReceiptCard!);
-    const receiptDialog = screen.getByRole('dialog', {
+    const workbenchStage = screen.getByLabelText('项目主视窗');
+    expect(workbenchStage.getAttribute('data-resource-view-state')).toBe(
+      'resources.focused.document',
+    );
+    expect(screen.queryByLabelText('搜索项目资源')).toBeNull();
+    expect(screen.queryByRole('button', { name: '按类型' })).toBeNull();
+    expect(screen.getByLabelText('陶泥儿 Agent 对话')).not.toBeNull();
+    expect(screen.getByLabelText('子 Agent 状态栏')).not.toBeNull();
+    const receiptFocus = screen.getByRole('region', {
       name: '美术资源计划 Agent 文本回执',
     });
     expect(
-      within(receiptDialog).getByRole('heading', { name: '美术计划' }),
+      within(receiptFocus).getByRole('heading', { name: '美术计划' }),
     ).not.toBeNull();
-    expect(within(receiptDialog).getByText('仅有美术计划')).not.toBeNull();
-    expect(within(receiptDialog).getByText('没有图片文件')).not.toBeNull();
+    expect(within(receiptFocus).getByText('仅有美术计划')).not.toBeNull();
+    expect(within(receiptFocus).getByText('没有图片文件')).not.toBeNull();
+    expect(within(receiptFocus).getByText('等待实际素材生成。')).not.toBeNull();
     expect(
-      within(receiptDialog).getByText('等待实际素材生成。'),
+      receiptFocus.querySelector('.game-resource-focus-body'),
     ).not.toBeNull();
+    expect(receiptFocus.querySelector('ul')).not.toBeNull();
+    expect(receiptFocus.querySelector('strong')).not.toBeNull();
+    expect(receiptFocus.closest('.game-workbench-stage')).toBe(workbenchStage);
+    expect(receiptFocus.closest('.game-resource-focus-layer')).toBeNull();
+    expect(styles).not.toMatch(
+      /\.game-resource-focus-titlebar\s*\{[^}]*cursor:/s,
+    );
+
+    fireEvent.click(
+      within(receiptFocus).getByRole('button', { name: '收起资源' }),
+    );
+    expect(workbenchStage.getAttribute('data-resource-view-state')).toBe(
+      'resources.list',
+    );
     expect(
-      receiptDialog.querySelector('.game-resource-focus-body'),
-    ).not.toBeNull();
-    expect(receiptDialog.querySelector('ul')).not.toBeNull();
-    expect(receiptDialog.querySelector('strong')).not.toBeNull();
+      (screen.getByLabelText('搜索项目资源') as HTMLInputElement).value,
+    ).toBe('美术资源计划');
+    expect(
+      screen
+        .getByRole('button', { name: '按类型' })
+        .getAttribute('aria-pressed'),
+    ).toBe('true');
+    const restoredCanvas = screen.getByLabelText(
+      '资源类型视图',
+    ) as HTMLDivElement;
+    expect(restoredCanvas.scrollLeft).toBe(48);
+    expect(restoredCanvas.scrollTop).toBe(36);
+    const restoredCard = screen
+      .getAllByTitle('打开资源详情')
+      .find((card) =>
+        card.textContent?.includes('美术资源计划 Agent 文本回执'),
+      );
+    expect(restoredCard?.getAttribute('aria-pressed')).toBe('true');
   });
 
   it('renders, filters, highlights, and destroys the resource dependency overlay without pointer previews', async () => {
@@ -834,8 +882,7 @@ export function registerProjectWorkbenchFoundationTests() {
       'asset-reference:["asset:dependency-spec","asset:dependency-ui"]';
     const selfReferenceId =
       'asset-reference:["asset:unrelated-cycle","asset:unrelated-cycle"]';
-    const flowId =
-      'task-flow:["art-director","design-foundation"]';
+    const flowId = 'task-flow:["art-director","design-foundation"]';
     let layoutRevision = 0;
     const invoke = vi.fn(
       async (command: string, args?: Record<string, unknown>) => {
@@ -899,12 +946,8 @@ export function registerProjectWorkbenchFoundationTests() {
               },
               {
                 resourceId: 'asset:unrelated-cycle',
-                upstreamReferenceResourceIds: [
-                  'asset:unrelated-cycle',
-                ],
-                downstreamReferenceResourceIds: [
-                  'asset:unrelated-cycle',
-                ],
+                upstreamReferenceResourceIds: ['asset:unrelated-cycle'],
+                downstreamReferenceResourceIds: ['asset:unrelated-cycle'],
                 referenceEdgeIds: [selfReferenceId],
                 taskFlowIds: [],
               },
@@ -992,7 +1035,7 @@ export function registerProjectWorkbenchFoundationTests() {
     });
     fireEvent.change(search, { target: { value: '' } });
 
-    const sourceCard = screen.getByRole('button', {
+    let sourceCard = screen.getByRole('button', {
       name: /spec-source\.json/,
     });
     const targetCard = screen.getByRole('button', {
@@ -1042,6 +1085,14 @@ export function registerProjectWorkbenchFoundationTests() {
     ).toHaveLength(layoutUpdatesBeforePointer);
 
     fireEvent.click(targetCard);
+    const targetFocus = screen.getByRole('region', {
+      name: /ui-dependency\.json/u,
+    });
+    fireEvent.click(
+      within(targetFocus).getByRole('button', { name: '收起资源' }),
+    );
+    overlay = await screen.findByTestId('resource-dependency-overlay');
+    sourceCard = screen.getByRole('button', { name: /spec-source\.json/ });
     await waitFor(() => {
       expect(sourceCard.classList.contains('is-relation-upstream')).toBe(true);
       expect(
@@ -1259,7 +1310,7 @@ export function registerProjectWorkbenchFoundationTests() {
 
     fireEvent.click(card!);
     expect(
-      screen.getByRole('dialog', { name: '布局持久化回执' }),
+      screen.getByRole('region', { name: '布局持久化回执' }),
     ).not.toBeNull();
 
     cleanup();
@@ -1383,23 +1434,23 @@ export function registerProjectWorkbenchFoundationTests() {
     const manifest = createGameCreationAppManifest(projectId, '布局失败测试');
     const invoke = vi.fn(
       async (command: string, args?: Record<string, unknown>) => {
-      if (command === 'read_local_project_resource_graph') {
-        return resourceGraphForInputs(args);
-      }
-      if (command === 'read_local_project_resource_canvas_layout') {
-        return {
-          schemaVersion: 'game-creator-resource-layout.v1',
-          projectId,
-          mode: 'dependency',
-          revision: 2,
-          positions: [],
-          updatedAt: 200,
-        };
-      }
-      if (command === 'update_local_project_resource_canvas_layout') {
-        throw new Error('disk full');
-      }
-      throw new Error(`unexpected invoke ${command}`);
+        if (command === 'read_local_project_resource_graph') {
+          return resourceGraphForInputs(args);
+        }
+        if (command === 'read_local_project_resource_canvas_layout') {
+          return {
+            schemaVersion: 'game-creator-resource-layout.v1',
+            projectId,
+            mode: 'dependency',
+            revision: 2,
+            positions: [],
+            updatedAt: 200,
+          };
+        }
+        if (command === 'update_local_project_resource_canvas_layout') {
+          throw new Error('disk full');
+        }
+        throw new Error(`unexpected invoke ${command}`);
       },
     );
     window.__TAURI__ = { core: { invoke } };
@@ -1551,7 +1602,7 @@ export function registerProjectWorkbenchFoundationTests() {
       target: { value: 'hero.png' },
     });
     fireEvent.click(screen.getByRole('button', { name: /hero\.png/ }));
-    expect(screen.getByLabelText('资源焦点')).not.toBeNull();
+    expect(screen.getByRole('region', { name: 'hero.png' })).not.toBeNull();
     expect(screen.getAllByText('assets/hero.png').length).toBeGreaterThan(0);
     const previewImage = await screen.findByRole('img', {
       name: 'hero.png 图片预览',
@@ -6945,7 +6996,7 @@ export function registerProjectSupervisorSurfaceTests() {
       return card;
     });
     fireEvent.click(updatedDesignCard);
-    const updatedDesignDialog = await screen.findByRole('dialog', {
+    const updatedDesignDialog = await screen.findByRole('region', {
       name: '策划 Agent 文本回执',
     });
     expect(
diff --git a/apps/ai-game-creator-shell/tests/projectResourceProjectionModel.test.ts b/apps/ai-game-creator-shell/tests/projectResourceProjectionModel.test.ts
new file mode 100644
index 000000000..829a430cb
--- /dev/null
+++ b/apps/ai-game-creator-shell/tests/projectResourceProjectionModel.test.ts
@@ -0,0 +1,186 @@
+import { describe, expect, it } from 'vitest';
+
+import { createGameCreationAppManifest } from '../../../packages/shared/src/contracts/gameCreationApp';
+import { projectResourcesFromReadModels } from '../src/view/project-development/resourceProjectionModel';
+
+describe('项目资源投影', () => {
+  it('只把明确资源投影到固定分类，未知任务产物不会伪装成项目版本', () => {
+    const manifest = createGameCreationAppManifest(
+      'resource-projection',
+      '资源投影测试',
+    );
+    const designTask = manifest.tasks.find(
+      (task) => task.id === 'design-foundation',
+    );
+    const audioTask = manifest.tasks.find(
+      (task) => task.id === 'audio-asset-plan',
+    );
+    if (!designTask || !audioTask) {
+      throw new Error('缺少资源投影测试任务');
+    }
+    designTask.status = 'completed';
+    designTask.artifacts = [
+      'memory/game-design.md',
+      'assets/ui-preview.svg',
+      'build/game.bundle',
+    ];
+    audioTask.status = 'completed';
+    audioTask.artifacts = ['audio/unregistered-bgm.wav'];
+    manifest.assets = [
+      {
+        id: 'registered-bgm',
+        kind: 'bgm',
+        mediaType: 'audio/wav',
+        localPath: 'audio/registered-bgm.wav',
+        source: { kind: 'generated' },
+      },
+      {
+        id: 'character-animation',
+        kind: 'character-animation',
+        mediaType: 'application/json',
+        localPath: 'assets/character-animation.json',
+        source: { kind: 'generated' },
+      },
+      {
+        id: 'unknown-binary',
+        kind: 'binary',
+        mediaType: 'application/octet-stream',
+        localPath: 'build/game.bundle',
+        source: { kind: 'generated' },
+      },
+    ];
+
+    const resources = projectResourcesFromReadModels(
+      manifest,
+      [
+        {
+          fileName: 'rules.yaml',
+          mediaType: 'application/yaml',
+          localPath: 'imports/rules.yaml',
+          status: 'imported',
+        },
+        {
+          fileName: 'voice.ogg',
+          mediaType: 'audio/ogg',
+          localPath: 'imports/voice.ogg',
+          status: 'imported',
+        },
+        {
+          fileName: 'archive.zip',
+          mediaType: 'application/zip',
+          localPath: 'imports/archive.zip',
+          status: 'imported',
+        },
+      ],
+      [
+        {
+          agentId: 'design-foundation',
+          runId: 'final-run',
+          label: '玩法策划 Agent',
+          title: '玩法文档回执',
+          content: '回执正文',
+          updatedAt: 1,
+        },
+      ],
+      [
+        {
+          versionId: 'version-1',
+          label: '首个可运行版本',
+          projectRevision: 7,
+          parentVersionId: null,
+          createdAt: 1,
+        },
+      ],
+    );
+
+    expect(resources.map(({ id, category }) => ({ id, category }))).toEqual(
+      expect.arrayContaining([
+        {
+          id: 'task:design-foundation:memory/game-design.md',
+          category: 'document',
+        },
+        {
+          id: 'task:design-foundation:assets/ui-preview.svg',
+          category: 'art',
+        },
+        { id: 'asset:registered-bgm', category: 'audio' },
+        { id: 'asset:character-animation', category: 'art' },
+        { id: 'attachment:imports/rules.yaml', category: 'document' },
+        { id: 'attachment:imports/voice.ogg', category: 'audio' },
+        {
+          id: 'agent-result:design-foundation:final-run',
+          category: 'document',
+        },
+        { id: 'version:version-1', category: 'version' },
+      ]),
+    );
+    expect(
+      resources.some(({ id }) =>
+        [
+          'task:design-foundation:build/game.bundle',
+          'task:audio-asset-plan:audio/unregistered-bgm.wav',
+          'asset:unknown-binary',
+          'attachment:imports/archive.zip',
+        ].includes(id),
+      ),
+    ).toBe(false);
+    expect(
+      resources.filter(({ category }) => category === 'version'),
+    ).toHaveLength(1);
+  });
+
+  it('显示名称变化不会改变正式资源身份', () => {
+    const manifest = createGameCreationAppManifest(
+      'stable-resource-id',
+      '稳定资源身份测试',
+    );
+    const first = projectResourcesFromReadModels(
+      manifest,
+      [],
+      [
+        {
+          agentId: 'design-foundation',
+          runId: 'stable-run',
+          label: '策划 Agent',
+          title: '旧标题',
+          content: '正文',
+          updatedAt: 1,
+        },
+      ],
+      [
+        {
+          versionId: 'stable-version',
+          label: '旧版本名',
+          projectRevision: 1,
+          parentVersionId: null,
+          createdAt: 1,
+        },
+      ],
+    );
+    const second = projectResourcesFromReadModels(
+      manifest,
+      [],
+      [
+        {
+          agentId: 'design-foundation',
+          runId: 'stable-run',
+          label: '策划 Agent',
+          title: '新标题',
+          content: '正文',
+          updatedAt: 2,
+        },
+      ],
+      [
+        {
+          versionId: 'stable-version',
+          label: '新版本名',
+          projectRevision: 1,
+          parentVersionId: null,
+          createdAt: 1,
+        },
+      ],
+    );
+
+    expect(first.map(({ id }) => id)).toEqual(second.map(({ id }) => id));
+  });
+});
diff --git a/docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md b/docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md
index bd89e59ab..b4c7ecc2c 100644
--- a/docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md
+++ b/docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md
@@ -124,10 +124,12 @@ idle -> focused(document|art|audio|version) -> idle
 ```
 
 - 文档：在中央画布展开并独立滚动。
-- 美术/音频：进入对应媒体聚焦状态，工具能力复用现有编辑器。
-- 版本：高亮版本引用资源；替换动作只创建下一迭代版本。
+- 美术/音频：进入对应媒体聚焦状态，当前只展示已有预览或资源元数据。
+- 版本：只展示正式版本 read model 的身份与修订元数据；版本引用高亮和替换留给后续切片。
 - mentor 最新决定：资源聚焦不提供工具栏，也不提供工具侧边栏。
-- 本阶段只保留点击资源打开当前已有详情，不实施后续文档读取、美术编辑、音频能力、项目版本或运行模块。
+- 点击资源后，中央主视窗从 `resources.list` 切换为 `resources.focused.document / art / audio / version`，左侧平台导航、右侧 Supervisor 对话和底部 Agent 状态栏保持原位；聚焦容器只包含标题、资源主体、必要元数据与右上角收起按钮，不使用页面级浮层或可拖动标题栏。
+- 退出聚焦后恢复进入前的搜索条件、dependency / type 布局模式、资源画布滚动位置和选中资源；这些只属于当前前端会话，不写入布局 sidecar。
+- 本阶段不新增项目文件读取命令、美术编辑、音频播放 / 编辑、版本替换或运行模块。
 
 ### 4.4 历史成果与当前状态
 
@@ -238,7 +240,7 @@ type UpdateProjectResourceCanvasLayoutResult =
 
 #### 5.2.4 前端布局与协调合同
 
-- 资源卡是可点击按钮，只负责选择资源并打开当前唯一资源详情浮层；不得绑定卡片级 `pointerdown / pointermove / pointerup / pointercancel` 拖动处理器。
+- 资源卡是可点击按钮，只负责选择资源并让中央主视窗进入当前唯一资源聚焦状态；不得绑定卡片级 `pointerdown / pointermove / pointerup / pointercancel` 拖动处理器。
 - 指针移动不得修改卡片 `x / y`、不得产生拖动预览、不得更新依赖线几何，也不得提交手动布局 CAS。卡片 title、cursor、`touch-action` 和 class 不得暗示可拖动。
 - dependency 默认布局按 `dependencyDepth` 形成横向层级，同层资源纵向寻找第一个不重叠位置；type 默认布局固定按“资源子类型 -> 媒体类型 -> 名称 -> 资源 ID”稳定排序，在分区内从左到右、从上到下寻找第一个空位。布局模型的 `subtype` 必填：manifest 资产使用 `asset.kind`，任务产物、导入附件与 Agent 文本成果分别使用稳定的 `task-artifact`、`attachment`、`agent-result`，不得以缺失值或显示文案兜底；资源协调签名必须包含 subtype。卡片尺寸与间距由单一前端布局模型常量维护。
 - type 模式资源集合变化时保留全部仍存在的坐标，只为新 ID 计算默认位置，并删除已确认失效的旧 ID。dependency 模式只永久保留 `manuallyPlaced=true` 的用户坐标；`manuallyPlaced=false` 属于可派生自动位置，在 Rust 关系图首次就绪或可信 producer / dependency depth 变化后按最终拓扑确定性重算。自动重算不得移动手动坐标，协调结果与持久布局逐项一致时不得产生 CAS 写入。
@@ -271,6 +273,10 @@ type UpdateProjectResourceCanvasLayoutResult =
 
 ### 5.3 资源类型与替换兼容性（P1）
 
+实现状态（2026-08-03）：当前资源投影已收口到固定的“文档 -> 项目版本 -> 美术资源 -> 音乐音效资源”四区。文档只接收 Markdown / 文本 / JSON / YAML 等正式项目文档和合法 Agent 文本回执；项目版本只接收显式 `ProjectVersionResourceSummary` read model，未知任务产物不得兜底为版本；美术接收图片、SVG、动画和视频类产物；音频只接收 manifest 已登记音频资产或已成功导入的音频附件，任务声明中的未登记音频路径不冒充正式音频资源。无法识别的二进制任务产物和附件不进入资源画布。
+
+资源身份固定使用 manifest asset ID、正式 version ID、Agent ID + run ID 或已导入资源稳定路径；显示标题、来源文案变化不得改变 `resourceId`，从而避免布局、依赖边、选择和聚焦状态因改名失效。
+
 ```ts
 type ProjectResourceDescriptor = {
   resourceId: string;
@@ -361,7 +367,7 @@ type ProjectAgentMudPointAttribution = {
 
 - 复用现有四区工作台壳。
 - 资源/运行切换与客户端内 loopback 预览。
-- 只读资源画布与资源卡点击详情；资源聚焦工具栏 / 工具侧边栏及后续媒体能力暂缓。
+- 固定四类资源投影、只读资源画布与中央主视窗资源聚焦；资源聚焦工具栏 / 工具侧边栏及后续媒体能力暂缓。
 - Supervisor 正式会话、上传、Runtime 确认与安全错误。
 - 当前 run 专业状态与项目历史成果分离。
 - 默认三专业组，并可展开另外三组。
@@ -393,6 +399,8 @@ type ProjectAgentMudPointAttribution = {
 4. 底栏默认显示策划、美术、程序，可展开数值、音频、发布；状态与任务来自真实 Runtime/manifest。
 5. 风险审批和无需审批不能改变运行策略，点击后明确提示尚未开放；严格审批继续使用现有 Runtime 门禁。
 6. 不显示伪造泥点、伪造资源完成度、伪造图片或外部浏览器成功提示。
+7. 未识别任务产物不进入“项目版本”，只有正式版本 read model 可以生成版本卡；资源显示名称变化不改变资源身份。
+8. 点击任一资源后只替换中央主视窗，右侧对话与底部 Agent 状态栏保持原位；收起或按 Escape 退出后恢复原搜索、布局模式、滚动位置和选中资源。
 
 ### 7.2 P1 资源画布布局持久化验收
 
@@ -410,15 +418,15 @@ type ProjectAgentMudPointAttribution = {
 2. 精确引用只接受唯一有效的外部资源 ID 映射，删除或不存在的资源不产生幽灵连线。
 3. 多资源任务依赖只形成一条聚合主线与 `O(S+T)` 条端点分支，不产生 `S×T` 连线。
 4. 资源引用环和无资源产物参与的任务环都可被有限遍历识别，界面不死循环。
-5. 搜索触发端点过滤，选择触发直接上下游与关联边高亮；资源卡指针移动不更新线段，点击与详情浮层行为不回归。
+5. 搜索触发端点过滤，选择触发直接上下游与关联边高亮；资源卡指针移动不更新线段，点击与中央聚焦行为不回归。
 6. 切换布局模式或项目后旧 SVG、ResizeObserver 与窗口监听全部清理；图层从不写入 layout sidecar、manifest 或其它持久化。
 7. 4096 资源链式 fixture 继续验证拓扑、聚合复杂度和自动布局性能；拖动局部更新与真实 Chromium 拖动帧预算暂缓，不作为当前验收条件。最右侧自环与箭头仍需完整显示。
 8. Rust 图读取延迟时，dependency sidecar 在图进入 `ready / failed` 前没有读取或写入；首次布局直接使用 Rust 返回的最终 producer 与 dependency depth。重新打开旧布局时手动位置逐项不变，自动位置按最终拓扑协调且相同结果不增加 revision。
 
 ## 8. 非目标
 
-- 本切片不实现资源卡手动拖动，也不实现资源聚焦工具栏、资源聚焦工具侧边栏、后续文档读取、美术编辑、音频能力、资源替换、不可变迭代版本、运行模块扩展、测试切片、数值参数或泥点归因；已实现的资源关系图只提供 Rust 只读拓扑与前端派生展示，不建立新的资源业务真相。
-- 本切片不保存资源详情浮层位置、画布缩放 / 平移、搜索条件、筛选条件或当前 mode；这些状态如需持久化必须另行扩展合同，不能塞入 `game-creator-resource-layout.v1`。
+- 本切片不实现资源卡手动拖动，也不实现资源聚焦工具栏、资源聚焦工具侧边栏、后续项目文件读取、美术编辑、音频播放 / 编辑、资源替换、不可变迭代版本写入、运行模块扩展、测试切片、数值参数或泥点归因；已实现的资源关系图只提供 Rust 只读拓扑与前端派生展示，不建立新的资源业务真相。
+- 本切片不持久化资源聚焦状态、画布缩放 / 平移、搜索条件、筛选条件或当前 mode；聚焦退出时的列表上下文恢复只限当前前端会话，这些状态如需跨重启保存必须另行扩展合同，不能塞入 `game-creator-resource-layout.v1`。
 - 不修改 SpacetimeDB schema。
 - 不开放普通用户 Agent.md/Skill。
 - 不自动确认 Agent 动作，不自动触发可能扣费的生成。
diff --git a/docs/project-memory/shared-memory/decision-log.md b/docs/project-memory/shared-memory/decision-log.md
index 83659ca2d..c70289246 100644
--- a/docs/project-memory/shared-memory/decision-log.md
+++ b/docs/project-memory/shared-memory/decision-log.md
@@ -1,12 +1,13 @@
 # 决策记录
 
-## 2026-08-03 资源卡手动拖动暂缓且当前只开放自动布局与点击详情
+## 2026-08-03 资源卡手动拖动暂缓并完成固定资源投影与中央聚焦
 
 - 背景：飞书《陶泥儿GameAgent-V1.0 项目开发界面需求》曾要求资源卡可拖动，并由后续 PRD、技术方案和实现扩展为手动布局 CAS、依赖线拖动预览与性能验收；mentor 最新决定明确资源卡暂时禁止拖动，资源聚焦也不需要工具栏或工具侧边栏。
-- 决策：当前资源卡不绑定 `pointerdown / pointermove / pointerup / pointercancel` 拖动入口，title、cursor、`touch-action` 与 class 只表达可点击；Pointer Move 不改变坐标、不更新依赖线、不提交手动布局。资源卡点击继续打开已有详情；dependency / type 自动布局、搜索、依赖线和直接上下游高亮保持现役。
+- 决策：当前资源卡不绑定 `pointerdown / pointermove / pointerup / pointercancel` 拖动入口，title、cursor、`touch-action` 与 class 只表达可点击；Pointer Move 不改变坐标、不更新依赖线、不提交手动布局。资源投影固定为文档、项目版本、美术资源、音乐音效资源四区；未知任务产物不兜底为版本，版本只接受显式 read model，音频只接受正式登记资产或已导入附件。资源身份不使用显示名称。
 - 保留边界：项目内 dependency / type 布局 sidecar、历史坐标读取、资源集合自动协调、scope FIFO、跨窗口系统锁、Tauri/Rust CAS 与命令式 SVG preview 基础设施可以保留；历史 `manuallyPlaced=true` 坐标不删除、不重置、不迁移，但当前没有用户手动布局入口。手动拖动持久化、拖动性能和冲突后的重新拖动提示不再是当前验收条件。
-- 后续边界：本阶段不继续实现资源聚焦、文档读取、美术编辑、音频能力、项目版本或运行模块；若重新开放手动拖动，必须先更新 PRD、技术方案和 AppSurface 验收合同。
-- 验证方式：AppSurface 覆盖 Pointer Down / Move / Up / Cancel 后卡片坐标、SVG path 与布局更新调用均不变，并继续覆盖点击详情、dependency / type 切换、搜索、依赖图和直接上下游高亮；追加 shell typecheck、编码检查与 `git diff --check`。
+- 聚焦边界：点击资源后只把中央主视窗切换为 `resources.focused.document / art / audio / version`，不遮盖或替换右侧 Supervisor 与底部 Agent 状态栏；通用容器不提供工具栏、工具侧边栏、底部画板工具栏或可拖动标题栏。退出恢复当前会话内搜索、dependency / type、画布滚动位置和选中资源，不把这些状态写入 sidecar。
+- 后续边界：本阶段不新增项目文件读取、美术编辑、音频播放 / 编辑、版本替换或运行模块；若重新开放手动拖动，必须先更新 PRD、技术方案和 AppSurface 验收合同。
+- 验证方式：纯投影测试覆盖四类映射、未知产物拒绝和显示名称改动下身份稳定；AppSurface 覆盖 Pointer Down / Move / Up / Cancel 后卡片坐标、SVG path 与布局更新调用均不变，并覆盖中央聚焦、上下文恢复、dependency / type 切换、搜索、依赖图和直接上下游高亮；追加 shell typecheck、编码检查与 `git diff --check`。
 - 关联文档：`docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md`、`docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md`。
 
 ## 2026-08-03 依赖布局等待 Rust 图终态且拖动热路径脱离 React state
@@ -5559,7 +5560,7 @@
 - 资源投影：上述回执同步投影到“资源管理 → 文档”，保留来源 Agent 和 run 身份。它是持久回执的可见视图，不得冒充 manifest asset、项目目录中的实际文件或可下载交付物。
 - 重试确认：`agent.resume` 默认仍为 `confirm`。普通自动 retry command 保留 auto gate；正式失败卡的“在当前项目重试”按钮本身视为本次明确确认，调用单独的 confirmed retry command，但仍不得绕过 deny。点击后必须在原卡即时显示提交中、成功或安全错误，不能把错误放到专业列表末尾。若总控已为同一 delegation 准备精确 repair，按钮优先确认该 repair，不再创建重复的无合同重试。
 - 回执命名：无文件的 completed 结果统一称“专业 Agent 文本回执”，不得称“美术产物”或直接暴露 `design-foundation / art-asset-plan / balance-seed` 等内部 ID。美术任务只完成计划且 manifest 没有图片时，普通界面明确显示“仅完成计划，尚未生成或登记图片”。
-- 工作台布局：PDF 方案外的顶部项目标题条不进入项目工作台；本条原定的资源卡同分类、当前会话内拖拽重排已由 2026-08-03 mentor 最新决定取代，当前资源卡只允许自动布局与点击详情。资源详情使用独立可拖动浮层，位置约束在工作台与 viewport 内并避开底部 Agent dock，长正文独立滚动。工作区与 dock 精确占满客户端可用高度，不保留 dock 下方空白。
+- 工作台布局：PDF 方案外的顶部项目标题条不进入项目工作台；本条原定的资源卡同分类、当前会话内拖拽重排已由 2026-08-03 mentor 最新决定取代，当前资源卡只允许自动布局与点击聚焦。原独立可拖动详情浮层已被同日后续阶段三替换为中央主视窗资源聚焦状态，右侧对话与底部 Agent dock 常驻，长正文在聚焦主体内独立滚动；退出恢复当前会话的列表上下文。工作区与 dock 精确占满客户端可用高度，不保留 dock 下方空白。
 
 ## 2026-07-20 AI 游戏创作策划与美术图片交付门禁
 
diff --git a/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md b/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md
index 07e75280f..aa0182fc4 100644
--- a/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md
+++ b/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md
@@ -154,7 +154,7 @@ V1.17 计划快照随 `game-creator-runtime-context-bundle.v3` 持久化，v2 
 
 2026-07-19 起，当前父 run 下的专业 Agent 进入 `failed` 后，正式工作台必须提供“在当前项目重试”恢复入口，不得要求用户新建项目。重试必须精确核对原 `agentId + runId + parentRunId`，复用原 task、active Session 和父 run 归属，同时生成新的专业 Agent runId；新 run 继承已持久化的上下文和父子绑定，不覆写旧失败 run 的审计事实，也不得把 UI 重试解释为底层 transport 根因已修复。`agent.resume` 默认 `confirm` 不变：自动 retry command 继续执行 auto gate；正式失败卡按钮自身是本次明确确认，使用 deny-only 的 confirmed retry command。按钮必须原卡即时显示“正在提交重试”、受理或安全错误；若 Supervisor 已为同一 delegation 准备合同 repair，则该按钮优先确认既有 repair，避免重复派发。
 
-completed 专业 Agent 的用户可见成果不能仅依赖项目文件。当委派合同为 `expectedArtifacts=[]` 或未产生显式文件时，工作台必须读取该 Agent 持久对话的最后一条 assistant，作为明确标注的“专业 Agent 文本回执”提供查看，并投影到“资源管理 → 文档”。该投影是持久回执的可见视图，必须保留来源 Agent 与 run 身份，不冒充 manifest asset、项目目录中的实际文件或可下载交付物；内部 Agent ID 不进入用户资源名。美术只交付计划且 manifest 没有图片时必须显示“仅完成计划，尚未生成或登记图片”，不能把文本回执称为美术图片产物。策划 `design-foundation` 与美术 `art-asset-plan` 从 2026-07-20 起属于图片产物型 canonical task：前者必须生成并登记 `assets/ui-prototype.png` 横屏界面原型图，后者必须生成并登记 `assets/art-spritesheet.png` 首版核心美术素材；只有文本计划或空 `expectedArtifacts` 不构成完成。策划图还必须由 `design-foundation` 的 `image.inspect` 对当前图片 SHA 形成 `ui-prototype.v2` 结构化视觉验收：信息 HUD、主要可玩区域、当前玩法的关键实体、主要操作、失败/重开流程、移动端布局意图、实现清晰度与原创主题八项全部通过且问题列表为空。验收不得预设塔防或任何固定玩法；`ui-prototype.v1` 仅供历史动作回执安全读取，不能作为新建或恢复 run 的 completion authority。Runtime finalization 只接受同 run、当前 SHA 的 v2 证据。视觉调用失败、响应不可解析、检查未通过或图片被替换后 SHA 不一致都继续阻塞。未通过的已登记图片在工作台只称“候选界面图（待视觉验收）”，不得冒充正式 UI 原型。图片生成未配置、待确认或失败时保持阻塞/失败，不得投影为 completed。资源卡当前只允许点击打开详情，不提供拖动重排；详情继续使用受 viewport 与底部 dock 约束的独立可拖浮层，长正文由唯一外层滚动容器承载并用 Markdown 安全渲染。PDF 方案外的顶部项目标题条移除，dock 下方不得保留空白；底部专业 Agent 为只读状态卡，不得因点击保留多个详情浮层。
+completed 专业 Agent 的用户可见成果不能仅依赖项目文件。当委派合同为 `expectedArtifacts=[]` 或未产生显式文件时，工作台必须读取该 Agent 持久对话的最后一条 assistant，作为明确标注的“专业 Agent 文本回执”提供查看，并投影到“资源管理 → 文档”。该投影是持久回执的可见视图，必须保留来源 Agent 与 run 身份，不冒充 manifest asset、项目目录中的实际文件或可下载交付物；内部 Agent ID 不进入用户资源名。美术只交付计划且 manifest 没有图片时必须显示“仅完成计划，尚未生成或登记图片”，不能把文本回执称为美术图片产物。策划 `design-foundation` 与美术 `art-asset-plan` 从 2026-07-20 起属于图片产物型 canonical task：前者必须生成并登记 `assets/ui-prototype.png` 横屏界面原型图，后者必须生成并登记 `assets/art-spritesheet.png` 首版核心美术素材；只有文本计划或空 `expectedArtifacts` 不构成完成。策划图还必须由 `design-foundation` 的 `image.inspect` 对当前图片 SHA 形成 `ui-prototype.v2` 结构化视觉验收：信息 HUD、主要可玩区域、当前玩法的关键实体、主要操作、失败/重开流程、移动端布局意图、实现清晰度与原创主题八项全部通过且问题列表为空。验收不得预设塔防或任何固定玩法；`ui-prototype.v1` 仅供历史动作回执安全读取，不能作为新建或恢复 run 的 completion authority。Runtime finalization 只接受同 run、当前 SHA 的 v2 证据。视觉调用失败、响应不可解析、检查未通过或图片被替换后 SHA 不一致都继续阻塞。未通过的已登记图片在工作台只称“候选界面图（待视觉验收）”，不得冒充正式 UI 原型。图片生成未配置、待确认或失败时保持阻塞/失败，不得投影为 completed。资源卡当前只允许点击聚焦，不提供拖动重排；详情使用中央主视窗内唯一聚焦状态，长正文在聚焦主体内独立滚动并用 Markdown 安全渲染。PDF 方案外的顶部项目标题条移除，右侧对话和底部 Agent dock 常驻且 dock 下方不得保留空白；底部专业 Agent 为只读状态卡。
 
 V1.17 同时把 finalization journal 升级为 v2 并绑定最终完整计划快照：assistant 已落盘而 Runtime state 丢失时，从 v2 journal 恢复原结构化计划后补齐终态；assistant 尚未落盘且 state 丢失时失败关闭。外层 `failed / budget-exhausted` 只保留最后可信计划，不把未完成步骤机械改成失败。thinking summary、legacy plan event 和 tool-plan repair 公共审计只保留哈希、字符数或计数，必要的模型输出与错误上下文仅留在有界私有 repair 请求中。
 
@@ -348,7 +348,7 @@ game-project/
 - `canvas.project_sync` 复用 Genarrative External Editor API，读取用户平台 API Key 可访问的画板项目快照，通过 `/api/external/v1/assets/read-url` 换签并把资源下载到本地项目 `assets/canvas-sync/`；默认 API base URL 为 `http://127.0.0.1:8082`，可用 Tauri 应用配置目录中的 `game-creator.config.json` 的 `editorApi.baseUrl` 覆盖，API Key 从同一配置的 `editorApi.apiKey` 读取，不写入项目文件、trace、manifest 或日志。
 - Agent loop 中美术组 `Asset` 和音乐组 `SFX` 会读取 `.agent/manifest.json`；图片生成先通过 External Editor API 项目与素材库接口准备同名画布会话，再调用 `/api/external/v1/editor/images/generations`，携带 `projectId`、`assetFolderId`、`assetLabel`、`generationInputs.artSpec` 和 `canvasCompletion`，随后通过 `/api/external/v1/assets/read-url` 换签下载到受控本地 `assets/` 路径，登记为 `canvas` 来源资产并追加 `canvas.asset_generate` 本地索引记录。API Key 不写入项目文件、agent.db、trace、manifest 或日志；未配置 Key 或生成失败时，图片产物型任务保持阻塞/失败，不能以文字计划完成。音乐组仍只建议同步已有音频资源，不调用图片生成接口。
 - `canvas.asset_import` 当前作为最小真实链路：导入项目目录内已有文件为 `canvas` 来源资产，并要求记录画板项目 ID 以及 resourceId 或 assetObjectId。
-- 项目工作台点击已登记图片时必须在客户端资源浮层中直接渲染图片，而不是只展示路径与 MIME。图片通过受控 Tauri 命令从项目 `assets/` / `game/` 读取，只允许 manifest 已登记资产或已完成任务产物，并复用 `file.read` auto 权限、图片魔数、文件大小、像素尺寸、普通文件、路径漂移和符号链接校验后以 data URL 返回；首版只支持 PNG、JPEG、WEBP，不向 WebView 暴露任意本机文件协议或绝对路径。
+- 项目工作台点击已登记图片时必须在中央主视窗的资源聚焦状态中直接渲染图片，而不是只展示路径与 MIME。图片通过受控 Tauri 命令从项目 `assets/` / `game/` 读取，只允许 manifest 已登记资产或已完成任务产物，并复用 `file.read` auto 权限、图片魔数、文件大小、像素尺寸、普通文件、路径漂移和符号链接校验后以 data URL 返回；首版只支持 PNG、JPEG、WEBP，不向 WebView 暴露任意本机文件协议或绝对路径。
 - `canvas.export_import` 复用 `/editor/canvas` 已有素材导出 ZIP 格式，读取根 `metadata.json`、复制 `images/` / `media/` / `sequences/` 到本地项目 `assets/canvas-imports/`，再按导出层登记为 `canvas` 来源资产；导出包不保存真实 resourceId 时，使用 `canvas-export:<file>` 作为可追踪 assetObjectId，不伪造后端资源行。
 
 ## GameAgent V1.0 项目开发工作台首版界面
@@ -359,8 +359,8 @@ game-project/
 
 - 页面骨架固定为左侧现有全局导航、中间主视窗、右侧陶泥儿对话和底部子 Agent 状态栏；不新建第二套客户端或平行项目页。
 - 中间主视窗提供 `资源管理 / 运行` 切换。`code-prototype` 任务完成前运行入口保持视觉不可用，但仍可点击查看“当前无可运行版本”，不能使用会阻断说明交互的原生 `disabled` 或 `aria-disabled`；完成后才允许进入运行表现层。切回资源管理只修改前端展示态，不伪造后端预览暂停结果。
-- 资源管理从当前 `GameCreationAppManifest` 派生项目文档、项目版本和 `assets`，并把首页已导入附件作为当前项目上传资源展示。资源按文档、版本、美术、动作、音乐音效分区；`按依赖 / 按类型` 使用各自前端排列，dependency 模式额外绘制当前 manifest 与资源投影可证明的依赖关系。排列与图层都不写回 manifest，不能推断或伪造缺失依赖。
-- 资源卡支持点击详情、搜索和类型筛选。2026-07-28 起完成两套二维坐标与本地 CAS sidecar；2026-07-31 起 dependency 模式增加不持久化的原生 SVG 关系图层。2026-08-03 mentor 决定暂缓资源卡拖动，当前卡片不挂载 Pointer Down / Move / Up / Cancel 拖动入口，只允许自动布局和点击详情。资源聚焦不提供工具栏或工具侧边栏；本阶段不继续实现文档读取、美术编辑、音频能力、项目版本或运行模块。
+- 资源管理从当前 `GameCreationAppManifest`、合法 Agent 文本回执、已导入附件和显式项目版本 read model 派生资源，固定按文档、项目版本、美术资源、音乐音效资源分区；未知任务产物不再兜底为版本，任务声明中的未登记音频也不冒充正式音频。`按依赖 / 按类型` 使用各自前端排列，dependency 模式额外绘制当前 manifest 与资源投影可证明的依赖关系。排列与图层都不写回 manifest，不能推断或伪造缺失依赖。
+- 资源卡支持点击聚焦、搜索和类型筛选。2026-07-28 起完成两套二维坐标与本地 CAS sidecar；2026-07-31 起 dependency 模式增加不持久化的原生 SVG 关系图层。2026-08-03 mentor 决定暂缓资源卡拖动，当前卡片不挂载 Pointer Down / Move / Up / Cancel 拖动入口，只允许自动布局和点击聚焦。聚焦态替换中央主视窗内容，保留左侧导航、右侧对话和底部 Agent 状态栏，退出后恢复搜索、布局模式、滚动位置与选中资源；不提供工具栏、工具侧边栏或可拖动标题栏。本阶段不新增项目文件读取、美术编辑、音频播放 / 编辑、版本替换或运行模块。
 - 运行表现层首版直接嵌入当前项目的 loopback 游戏画面，并展示上一项 / 暂停继续 / 下一项切片控制、素材信息和数值微调面板。`preview.start` 启动本地 server 后把真实 URL 回写工作台，`preview.open` 只激活客户端内运行视图，不再调用系统浏览器；切片、参数调整和自然语言新增调节项首版仍只保留本地 UI 草稿，不修改代码或 manifest。
 - 右侧继续复用现有 Project Supervisor 会话、Runtime 澄清和确认链路；输入区展示 `严格审批 / 风险审批 / 无需审批` 独立面板。P0 只有严格审批可选；风险审批和无需审批保持视觉不可用但允许点击查看原因，不替代 Runtime 的逐动作权限、确认、sandbox 或 reconciliation 门禁。风险 Rank 算法记录在 `docs/project-memory/todos/【待解决】AI游戏创作高风险审批Rank-2026-07-20.md`，前端不得自行计算。
 - 底部状态栏默认展示策划、美术、程序 3 组，并允许在同一栏展开数值、音频、发布组；状态来自 manifest 与当前 Supervisor run 的 Runtime，悬停显示当前任务与进度。累计泥点必须等待后端计费归因投影；Agent.md 编辑和自定义 Skill 在来源审核、版本、权限、sandbox 与回滚合同完备前不向普通用户开放。
@@ -384,7 +384,7 @@ game-project/
 - 新资源只在第一次进入某个 mode 时计算默认不重叠位置；全部现存坐标保持不变。搜索、筛选、窗口 resize 和 mode 切换不得重排或回写已有坐标，窄视图通过 section 画布范围与滚动访问，不裁切持久坐标。
 - type 默认布局固定按 `subtype -> mediaType -> label -> id` 排序。manifest 资产的 subtype 使用 `asset.kind`，任务产物、导入附件和 Agent 文本成果使用稳定的来源 fallback；subtype 必须进入资源协调签名，不能因 MIME 相同而退化成按名称混排。
 - 自动协调保存失败时保留当前会话布局；CAS 冲突载入对方最新布局，需要继续协调时最多追加两次重试，持续跨窗口竞争时停止自旋。用户提示只说明“布局已在其他窗口更新”，不要求重新拖动。损坏、未知 schema、身份冲突、超限与链接文件失败关闭，不能用空布局覆盖原文件。
-- 本布局持久化切片不包含资源关系线、资源替换、详情浮层位置、缩放 / 平移、搜索 / 筛选条件、当前 mode，也不修改 `api-server` 或 SpacetimeDB。资源关系线已在后续独立的纯前端切片接入，不改变本段 sidecar 合同；其余 P1 能力继续独立实施。
+- 本布局持久化切片不包含资源关系线、资源替换、聚焦态持久化、缩放 / 平移、搜索 / 筛选条件、当前 mode，也不修改 `api-server` 或 SpacetimeDB。资源关系线与当前会话内中央聚焦已在后续独立前端切片接入，不改变本段 sidecar 合同；其余 P1 能力继续独立实施。
 
 历史实施顺序已完成 TypeScript / Rust DTO、Tauri sidecar/CAS、前端纯模型与持久 Hook。二维手动拖动接线现已暂缓；重新开放前必须先更新 PRD 与验收合同。任何后续步骤不得用 `localStorage`、manifest 字段或只在当前 React 会话有效的状态冒充项目持久化。
 
-- 
2.52.0


From d374f3292ab1dd9daafe157d8e7b03afdd0df08f Mon Sep 17 00:00:00 2001
From: menghao <mh18530625731@163.com>
Date: Mon, 3 Aug 2026 17:20:14 +0800
Subject: [PATCH 12/27] =?UTF-8?q?=E5=AE=8C=E6=88=90=E8=B5=84=E6=BA=90?=
 =?UTF-8?q?=E8=81=9A=E7=84=A6=E9=98=B6=E6=AE=B5=E5=9B=9B?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

新增项目文档与媒体资源安全读取命令
补齐Markdown、扩展美术媒体与音频聚焦展示
增加安全边界与工作台回归测试
同步PRD、技术方案与共享决策
---
 .../src-tauri/src/commands.rs                 |  60 +++
 .../src-tauri/src/image_inspect.rs            |  15 +-
 .../src-tauri/src/main.rs                     |   4 +
 .../src-tauri/src/resource_inspect.rs         | 441 ++++++++++++++++++
 .../src-tauri/src/tests/project_tools.rs      | 104 +++++
 apps/ai-game-creator-shell/src/styles.css     |  93 +++-
 .../src/view/project-development/index.tsx    | 351 +++++++++++++-
 .../appSurface/project-development.suite.ts   | 147 ++++++
 ...AI游戏创作】项目开发工作台PRD-2026-07-20.md |  11 +-
 .../shared-memory/decision-log.md             |   8 +
 ...�案】AI游戏创作智能体App实施计划-2026-06-24.md |   3 +-
 11 files changed, 1211 insertions(+), 26 deletions(-)
 create mode 100644 apps/ai-game-creator-shell/src-tauri/src/resource_inspect.rs

diff --git a/apps/ai-game-creator-shell/src-tauri/src/commands.rs b/apps/ai-game-creator-shell/src-tauri/src/commands.rs
index acee27f43..bff274d4b 100644
--- a/apps/ai-game-creator-shell/src-tauri/src/commands.rs
+++ b/apps/ai-game-creator-shell/src-tauri/src/commands.rs
@@ -1177,6 +1177,66 @@ pub(crate) fn read_local_project_image_preview(
     load_local_project_image_preview(root, &normalized_path)
 }
 
+#[tauri::command]
+pub(crate) fn read_local_project_text_preview(
+    project_path: String,
+    relative_path: String,
+) -> Result<LocalProjectTextPreview, String> {
+    let root = Path::new(project_path.trim());
+    enforce_project_auto_permission_policy(root, "file.read")?;
+    let normalized_path = normalize_relative_path(relative_path.trim())?;
+    let manifest = read_manifest(&root.join(".agent/manifest.json"))?;
+    let is_registered_document = manifest.assets.iter().any(|asset| {
+        asset.local_path == normalized_path
+            && is_supported_project_text_resource(&asset.local_path, &asset.media_type)
+    }) || manifest.tasks.iter().any(|task| {
+        task.status == GameCreationAppTaskStatus::Completed
+            && task.artifacts.iter().any(|path| path == &normalized_path)
+            && is_supported_project_text_resource(&normalized_path, "")
+    });
+    if !is_registered_document {
+        return Err("只能读取当前项目已登记的文档资源".to_string());
+    }
+    load_local_project_text_preview(root, &normalized_path)
+}
+
+#[tauri::command]
+pub(crate) fn read_local_project_media_preview(
+    project_path: String,
+    relative_path: String,
+    category: String,
+) -> Result<LocalProjectMediaPreview, String> {
+    let root = Path::new(project_path.trim());
+    enforce_project_auto_permission_policy(root, "file.read")?;
+    let normalized_path = normalize_relative_path(relative_path.trim())?;
+    let manifest = read_manifest(&root.join(".agent/manifest.json"))?;
+    let kind = match category.trim() {
+        "art" => ProjectMediaPreviewKind::Art,
+        "audio" => ProjectMediaPreviewKind::Audio,
+        _ => return Err("媒体预览类别只支持 art 或 audio".to_string()),
+    };
+    let is_registered_media = manifest.assets.iter().any(|asset| {
+        asset.local_path == normalized_path
+            && match kind {
+                ProjectMediaPreviewKind::Art => {
+                    is_supported_project_art_media_resource(&asset.local_path, &asset.media_type)
+                }
+                ProjectMediaPreviewKind::Audio => {
+                    is_supported_project_audio_resource(&asset.local_path, &asset.media_type)
+                }
+            }
+    }) || (kind == ProjectMediaPreviewKind::Art
+        && manifest.tasks.iter().any(|task| {
+            task.status == GameCreationAppTaskStatus::Completed
+                && task.artifacts.iter().any(|path| path == &normalized_path)
+                && is_supported_project_art_media_resource(&normalized_path, "")
+        }));
+    if !is_registered_media {
+        return Err("只能预览当前项目已登记的媒体资源".to_string());
+    }
+    load_local_project_media_preview(root, &normalized_path, kind)
+}
+
 #[tauri::command]
 pub(crate) fn write_local_project_file(
     project_path: String,
diff --git a/apps/ai-game-creator-shell/src-tauri/src/image_inspect.rs b/apps/ai-game-creator-shell/src-tauri/src/image_inspect.rs
index 6ab5a5979..5d6362ba5 100644
--- a/apps/ai-game-creator-shell/src-tauri/src/image_inspect.rs
+++ b/apps/ai-game-creator-shell/src-tauri/src/image_inspect.rs
@@ -204,7 +204,10 @@ fn validate_agent_runtime_inspection_path(
     Ok(())
 }
 
-fn validate_agent_runtime_inspection_ancestors(root: &Path, path: &Path) -> Result<(), String> {
+pub(crate) fn validate_agent_runtime_inspection_ancestors(
+    root: &Path,
+    path: &Path,
+) -> Result<(), String> {
     let relative = path
         .strip_prefix(root)
         .map_err(|_| "image.inspect 图片路径超出项目目录".to_string())?;
@@ -450,7 +453,7 @@ fn metadata_is_windows_reparse_point(_metadata: &fs::Metadata) -> bool {
 }
 
 #[cfg(unix)]
-fn same_open_file_snapshot(left: &fs::Metadata, right: &fs::Metadata) -> bool {
+pub(crate) fn same_open_file_snapshot(left: &fs::Metadata, right: &fs::Metadata) -> bool {
     use std::os::unix::fs::MetadataExt;
     left.dev() == right.dev()
         && left.ino() == right.ino()
@@ -463,12 +466,12 @@ fn same_open_file_snapshot(left: &fs::Metadata, right: &fs::Metadata) -> bool {
 }
 
 #[cfg(not(unix))]
-fn same_open_file_snapshot(left: &fs::Metadata, right: &fs::Metadata) -> bool {
+pub(crate) fn same_open_file_snapshot(left: &fs::Metadata, right: &fs::Metadata) -> bool {
     left.len() == right.len() && left.modified().ok() == right.modified().ok()
 }
 
 #[cfg(unix)]
-fn same_open_file_identity(
+pub(crate) fn same_open_file_identity(
     _left_file: &fs::File,
     left: &fs::Metadata,
     _right_file: &fs::File,
@@ -479,7 +482,7 @@ fn same_open_file_identity(
 }
 
 #[cfg(windows)]
-fn same_open_file_identity(
+pub(crate) fn same_open_file_identity(
     left_file: &fs::File,
     _left: &fs::Metadata,
     right_file: &fs::File,
@@ -489,7 +492,7 @@ fn same_open_file_identity(
 }
 
 #[cfg(not(any(unix, windows)))]
-fn same_open_file_identity(
+pub(crate) fn same_open_file_identity(
     _left_file: &fs::File,
     left: &fs::Metadata,
     _right_file: &fs::File,
diff --git a/apps/ai-game-creator-shell/src-tauri/src/main.rs b/apps/ai-game-creator-shell/src-tauri/src/main.rs
index 61fd376e2..422db1039 100644
--- a/apps/ai-game-creator-shell/src-tauri/src/main.rs
+++ b/apps/ai-game-creator-shell/src-tauri/src/main.rs
@@ -72,6 +72,7 @@ mod project;
 mod provider_handoff;
 mod provider_retry;
 mod repository_context;
+mod resource_inspect;
 mod runner;
 mod swarm_cli;
 mod tool_plan_handoff;
@@ -101,6 +102,7 @@ use preview::*;
 use process_session::*;
 use project::*;
 use repository_context::*;
+use resource_inspect::*;
 use runner::*;
 use swarm_cli::*;
 use user_input::*;
@@ -2348,6 +2350,8 @@ fn main() {
             list_local_project_files,
             read_local_project_file,
             read_local_project_image_preview,
+            read_local_project_text_preview,
+            read_local_project_media_preview,
             write_local_project_file,
             delete_local_project_file,
             read_local_game_memory,
diff --git a/apps/ai-game-creator-shell/src-tauri/src/resource_inspect.rs b/apps/ai-game-creator-shell/src-tauri/src/resource_inspect.rs
new file mode 100644
index 000000000..129b01f75
--- /dev/null
+++ b/apps/ai-game-creator-shell/src-tauri/src/resource_inspect.rs
@@ -0,0 +1,441 @@
+use crate::image_inspect::{
+    same_open_file_identity, same_open_file_snapshot, validate_agent_runtime_inspection_ancestors,
+};
+use crate::project::{
+    normalize_relative_path, open_project_snapshot_regular_file,
+    reject_sensitive_project_file_read, resolve_local_project_path,
+};
+use base64::Engine as _;
+use serde::Serialize;
+use std::io::Read;
+use std::path::Path;
+
+const PROJECT_TEXT_PREVIEW_MAX_FILE_BYTES: u64 = 2 * 1024 * 1024;
+const PROJECT_MEDIA_PREVIEW_MAX_FILE_BYTES: u64 = 32 * 1024 * 1024;
+
+#[derive(Debug, Eq, PartialEq, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub(crate) struct LocalProjectTextPreview {
+    pub(crate) path: String,
+    pub(crate) media_type: String,
+    pub(crate) byte_len: u64,
+    pub(crate) content: String,
+}
+
+#[derive(Debug, Eq, PartialEq, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub(crate) struct LocalProjectMediaPreview {
+    pub(crate) path: String,
+    pub(crate) media_type: String,
+    pub(crate) byte_len: u64,
+    pub(crate) data_url: String,
+}
+
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub(crate) enum ProjectMediaPreviewKind {
+    Art,
+    Audio,
+}
+
+pub(crate) fn is_supported_project_text_resource(path: &str, media_type: &str) -> bool {
+    let media_type = media_type.trim().to_ascii_lowercase();
+    matches!(
+        path_extension(path).as_deref(),
+        Some("md" | "markdown" | "mdx" | "txt" | "json" | "yaml" | "yml" | "toml")
+    ) && (media_type.is_empty()
+        || media_type.starts_with("text/")
+        || media_type.contains("json")
+        || media_type.contains("yaml")
+        || matches!(
+            media_type.as_str(),
+            "项目文档" | "application/toml" | "application/mdx"
+        ))
+}
+
+pub(crate) fn is_supported_project_art_media_resource(path: &str, media_type: &str) -> bool {
+    let media_type = media_type.trim().to_ascii_lowercase();
+    matches!(
+        path_extension(path).as_deref(),
+        Some("gif" | "svg" | "avif" | "bmp" | "mp4" | "webm" | "mov")
+    ) || media_type.starts_with("video/")
+        || media_type == "image/svg+xml"
+}
+
+pub(crate) fn is_supported_project_audio_resource(path: &str, media_type: &str) -> bool {
+    let media_type = media_type.trim().to_ascii_lowercase();
+    matches!(
+        path_extension(path).as_deref(),
+        Some("mp3" | "wav" | "ogg" | "m4a" | "aac" | "flac" | "opus")
+    ) || media_type.starts_with("audio/")
+}
+
+pub(crate) fn load_local_project_text_preview(
+    root: &Path,
+    relative_path: &str,
+) -> Result<LocalProjectTextPreview, String> {
+    let normalized = normalize_relative_path(relative_path.trim())?;
+    reject_sensitive_project_file_read(&normalized)?;
+    let media_type = project_text_media_type(&normalized)
+        .ok_or_else(|| "文档预览只支持 Markdown、文本、JSON、YAML 和 TOML".to_string())?;
+    let bytes = read_stable_project_resource(
+        root,
+        &normalized,
+        PROJECT_TEXT_PREVIEW_MAX_FILE_BYTES,
+        "项目文档",
+    )?;
+    let content =
+        String::from_utf8(bytes).map_err(|_| "文档预览只支持 UTF-8 编码的文本文件".to_string())?;
+    Ok(LocalProjectTextPreview {
+        path: normalized,
+        media_type: media_type.to_string(),
+        byte_len: content.len() as u64,
+        content,
+    })
+}
+
+pub(crate) fn load_local_project_media_preview(
+    root: &Path,
+    relative_path: &str,
+    kind: ProjectMediaPreviewKind,
+) -> Result<LocalProjectMediaPreview, String> {
+    let normalized = normalize_relative_path(relative_path.trim())?;
+    reject_sensitive_project_file_read(&normalized)?;
+    let bytes = read_stable_project_resource(
+        root,
+        &normalized,
+        PROJECT_MEDIA_PREVIEW_MAX_FILE_BYTES,
+        "项目媒体资源",
+    )?;
+    if bytes.is_empty() {
+        return Err("媒体文件为空，无法预览".to_string());
+    }
+    let media_type = detect_project_media_type(&normalized, &bytes, kind)?;
+    Ok(LocalProjectMediaPreview {
+        path: normalized,
+        media_type: media_type.to_string(),
+        byte_len: bytes.len() as u64,
+        data_url: format!(
+            "data:{media_type};base64,{}",
+            base64::engine::general_purpose::STANDARD.encode(bytes)
+        ),
+    })
+}
+
+fn read_stable_project_resource(
+    root: &Path,
+    normalized: &str,
+    max_bytes: u64,
+    label: &str,
+) -> Result<Vec<u8>, String> {
+    let absolute = resolve_local_project_path(root, normalized)?;
+    validate_agent_runtime_inspection_ancestors(root, &absolute)?;
+    let (mut file, initial_metadata) = open_project_snapshot_regular_file(&absolute, label)?;
+    if initial_metadata.len() > max_bytes {
+        return Err(format!("{label}不能超过 {} MiB", max_bytes / 1024 / 1024));
+    }
+    let mut bytes = Vec::with_capacity(initial_metadata.len() as usize);
+    file.by_ref()
+        .take(max_bytes + 1)
+        .read_to_end(&mut bytes)
+        .map_err(|error| format!("读取{label}失败：{normalized}: {error}"))?;
+    if bytes.len() as u64 > max_bytes {
+        return Err(format!("{label}不能超过 {} MiB", max_bytes / 1024 / 1024));
+    }
+    let final_metadata = file
+        .metadata()
+        .map_err(|error| format!("复核{label}失败：{normalized}: {error}"))?;
+    if initial_metadata.len() != bytes.len() as u64
+        || final_metadata.len() != bytes.len() as u64
+        || !same_open_file_snapshot(&initial_metadata, &final_metadata)
+    {
+        return Err(format!("{label}读取期间发生漂移：{normalized}"));
+    }
+    let (reopened, reopened_metadata) = open_project_snapshot_regular_file(&absolute, label)?;
+    if !same_open_file_identity(&file, &initial_metadata, &reopened, &reopened_metadata)? {
+        return Err(format!("{label}路径读取期间发生替换：{normalized}"));
+    }
+    Ok(bytes)
+}
+
+fn project_text_media_type(path: &str) -> Option<&'static str> {
+    match path_extension(path).as_deref()? {
+        "md" | "markdown" | "mdx" => Some("text/markdown"),
+        "txt" => Some("text/plain"),
+        "json" => Some("application/json"),
+        "yaml" | "yml" => Some("application/yaml"),
+        "toml" => Some("application/toml"),
+        _ => None,
+    }
+}
+
+fn detect_project_media_type(
+    path: &str,
+    bytes: &[u8],
+    kind: ProjectMediaPreviewKind,
+) -> Result<&'static str, String> {
+    if kind == ProjectMediaPreviewKind::Art && path_extension(path).as_deref() == Some("svg") {
+        validate_safe_svg(bytes)?;
+        return Ok("image/svg+xml");
+    }
+    if kind == ProjectMediaPreviewKind::Art {
+        if bytes.starts_with(b"GIF87a") || bytes.starts_with(b"GIF89a") {
+            return Ok("image/gif");
+        }
+        if bytes.starts_with(b"BM") {
+            return Ok("image/bmp");
+        }
+        if is_avif(bytes) {
+            return Ok("image/avif");
+        }
+        if is_iso_base_media(bytes) {
+            return Ok(if path_extension(path).as_deref() == Some("mov") {
+                "video/quicktime"
+            } else {
+                "video/mp4"
+            });
+        }
+        if bytes.starts_with(&[0x1a, 0x45, 0xdf, 0xa3]) {
+            return Ok("video/webm");
+        }
+        return Err("美术媒体预览只支持 GIF、安全 SVG、AVIF、BMP、MP4、WebM 或 MOV".to_string());
+    }
+
+    if looks_like_id3(bytes) || looks_like_mp3_frame(bytes) {
+        Ok("audio/mpeg")
+    } else if bytes.len() >= 12 && bytes.starts_with(b"RIFF") && &bytes[8..12] == b"WAVE" {
+        Ok("audio/wav")
+    } else if bytes.starts_with(b"OggS") {
+        Ok("audio/ogg")
+    } else if bytes.starts_with(b"fLaC") {
+        Ok("audio/flac")
+    } else if is_avif(bytes) {
+        Err("音乐音效文件签名与登记类型不一致".to_string())
+    } else if is_iso_base_media(bytes) {
+        Ok("audio/mp4")
+    } else if looks_like_aac_adts(bytes) {
+        Ok("audio/aac")
+    } else {
+        Err("音乐音效预览只支持 MP3、WAV、OGG、M4A、AAC、FLAC 或 Opus".to_string())
+    }
+}
+
+fn validate_safe_svg(bytes: &[u8]) -> Result<(), String> {
+    let text = std::str::from_utf8(bytes).map_err(|_| "SVG 必须使用 UTF-8 编码".to_string())?;
+    let lower = text.to_ascii_lowercase();
+    if !lower.contains("<svg") {
+        return Err("SVG 内容无效，无法预览".to_string());
+    }
+    let forbidden = [
+        "<script",
+        "<style",
+        "<foreignobject",
+        "<image",
+        "<!doctype",
+        "<!entity",
+        "&#",
+        "javascript:",
+        "file:",
+        "@import",
+    ];
+    let external_url_probe = lower
+        .replace("http://www.w3.org/2000/svg", "")
+        .replace("http://www.w3.org/1999/xlink", "");
+    if forbidden.iter().any(|value| lower.contains(value))
+        || external_url_probe.contains("http://")
+        || external_url_probe.contains("https://")
+        || contains_svg_event_handler(&lower)
+        || contains_unsafe_svg_href(&lower)
+        || contains_unsafe_svg_url(&lower)
+    {
+        return Err("SVG 包含脚本或外部资源引用，无法安全预览".to_string());
+    }
+    Ok(())
+}
+
+fn contains_unsafe_svg_href(text: &str) -> bool {
+    let mut remaining = text;
+    while let Some(index) = remaining.find("href") {
+        let after_name = &remaining[index + 4..];
+        let Some(after_equals) = after_name.trim_start().strip_prefix('=') else {
+            remaining = after_name;
+            continue;
+        };
+        let value = after_equals.trim_start();
+        let value = value
+            .strip_prefix('\'')
+            .or_else(|| value.strip_prefix('"'))
+            .unwrap_or(value)
+            .trim_start();
+        if !value.starts_with('#') {
+            return true;
+        }
+        remaining = after_name;
+    }
+    false
+}
+
+fn contains_unsafe_svg_url(text: &str) -> bool {
+    let mut remaining = text;
+    while let Some(index) = remaining.find("url(") {
+        let value = remaining[index + 4..].trim_start();
+        let value = value
+            .strip_prefix('\'')
+            .or_else(|| value.strip_prefix('"'))
+            .unwrap_or(value)
+            .trim_start();
+        if !value.starts_with('#') {
+            return true;
+        }
+        remaining = &remaining[index + 4..];
+    }
+    false
+}
+
+fn contains_svg_event_handler(text: &str) -> bool {
+    let bytes = text.as_bytes();
+    let mut index = 0usize;
+    while index + 3 < bytes.len() {
+        if bytes[index].is_ascii_whitespace() && bytes[index + 1..].starts_with(b"on") {
+            let mut cursor = index + 3;
+            while cursor < bytes.len() && bytes[cursor].is_ascii_alphabetic() {
+                cursor += 1;
+            }
+            while cursor < bytes.len() && bytes[cursor].is_ascii_whitespace() {
+                cursor += 1;
+            }
+            if cursor < bytes.len() && bytes[cursor] == b'=' {
+                return true;
+            }
+        }
+        index += 1;
+    }
+    false
+}
+
+fn is_iso_base_media(bytes: &[u8]) -> bool {
+    bytes.len() >= 12 && &bytes[4..8] == b"ftyp"
+}
+
+fn is_avif(bytes: &[u8]) -> bool {
+    is_iso_base_media(bytes)
+        && (&bytes[8..12] == b"avif"
+            || &bytes[8..12] == b"avis"
+            || bytes[8..].windows(4).any(|brand| brand == b"avif"))
+}
+
+fn looks_like_mp3_frame(bytes: &[u8]) -> bool {
+    bytes.len() >= 4
+        && bytes[0] == 0xff
+        && bytes[1] & 0xe0 == 0xe0
+        && bytes[1] & 0x06 != 0
+        && bytes[2] & 0xf0 != 0xf0
+        && bytes[2] & 0x0c != 0x0c
+}
+
+fn looks_like_id3(bytes: &[u8]) -> bool {
+    if bytes.len() < 10 || !bytes.starts_with(b"ID3") || bytes[3] == 0xff || bytes[4] == 0xff {
+        return false;
+    }
+    let size_bytes = &bytes[6..10];
+    if size_bytes.iter().any(|byte| byte & 0x80 != 0) {
+        return false;
+    }
+    let tag_size = size_bytes
+        .iter()
+        .fold(0usize, |size, byte| (size << 7) | usize::from(*byte));
+    10usize
+        .checked_add(tag_size)
+        .is_some_and(|required| required <= bytes.len())
+}
+
+fn looks_like_aac_adts(bytes: &[u8]) -> bool {
+    bytes.len() >= 2 && bytes[0] == 0xff && bytes[1] & 0xf6 == 0xf0
+}
+
+fn path_extension(path: &str) -> Option<String> {
+    Path::new(path)
+        .extension()
+        .and_then(|extension| extension.to_str())
+        .map(str::to_ascii_lowercase)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::fs;
+
+    #[test]
+    fn text_preview_requires_utf8_and_a_supported_extension() {
+        let root = tempfile::tempdir().expect("temp root");
+        fs::create_dir_all(root.path().join("docs")).expect("docs dir");
+        fs::write(root.path().join("docs/design.md"), "# 设计\n\n正文").expect("markdown");
+        fs::write(root.path().join("docs/legacy.txt"), [0xff, 0xfe]).expect("legacy text");
+        fs::write(root.path().join("docs/page.html"), "<h1>unsafe</h1>").expect("html");
+
+        let preview =
+            load_local_project_text_preview(root.path(), "docs/design.md").expect("load markdown");
+        assert_eq!(preview.media_type, "text/markdown");
+        assert!(preview.content.contains("正文"));
+        assert!(load_local_project_text_preview(root.path(), "docs/legacy.txt").is_err());
+        assert!(load_local_project_text_preview(root.path(), "docs/page.html").is_err());
+    }
+
+    #[test]
+    fn media_preview_accepts_safe_svg_and_rejects_active_svg() {
+        let root = tempfile::tempdir().expect("temp root");
+        fs::create_dir_all(root.path().join("assets")).expect("assets dir");
+        fs::write(
+            root.path().join("assets/icon.svg"),
+            "<svg xmlns=\"http://www.w3.org/2000/svg\"><path d=\"M0 0\"/></svg>",
+        )
+        .expect("svg");
+        fs::write(
+            root.path().join("assets/active.svg"),
+            "<svg xmlns=\"http://www.w3.org/2000/svg\" onload=\"alert(1)\"/>",
+        )
+        .expect("active svg");
+        fs::write(
+            root.path().join("assets/external.svg"),
+            "<svg xmlns=\"http://www.w3.org/2000/svg\"><use href = \"https://example.com/icon.svg#x\"/></svg>",
+        )
+        .expect("external svg");
+
+        let preview = load_local_project_media_preview(
+            root.path(),
+            "assets/icon.svg",
+            ProjectMediaPreviewKind::Art,
+        )
+        .expect("safe svg");
+        assert_eq!(preview.media_type, "image/svg+xml");
+        assert!(preview.data_url.starts_with("data:image/svg+xml;base64,"));
+        assert!(load_local_project_media_preview(
+            root.path(),
+            "assets/active.svg",
+            ProjectMediaPreviewKind::Art,
+        )
+        .is_err());
+        assert!(load_local_project_media_preview(
+            root.path(),
+            "assets/external.svg",
+            ProjectMediaPreviewKind::Art,
+        )
+        .is_err());
+    }
+
+    #[cfg(unix)]
+    #[test]
+    fn resource_preview_rejects_symlink_and_hardlink_files() {
+        use std::os::unix::fs::symlink;
+
+        let root = tempfile::tempdir().expect("temp root");
+        let outside = tempfile::tempdir().expect("outside");
+        fs::create_dir_all(root.path().join("docs")).expect("docs dir");
+        let source = outside.path().join("source.md");
+        fs::write(&source, "secret").expect("source");
+        symlink(&source, root.path().join("docs/link.md")).expect("symlink");
+        fs::hard_link(&source, root.path().join("docs/hard.md")).expect("hardlink");
+
+        assert!(load_local_project_text_preview(root.path(), "docs/link.md").is_err());
+        assert!(load_local_project_text_preview(root.path(), "docs/hard.md").is_err());
+    }
+}
diff --git a/apps/ai-game-creator-shell/src-tauri/src/tests/project_tools.rs b/apps/ai-game-creator-shell/src-tauri/src/tests/project_tools.rs
index 4ff135ddf..141878dab 100644
--- a/apps/ai-game-creator-shell/src-tauri/src/tests/project_tools.rs
+++ b/apps/ai-game-creator-shell/src-tauri/src/tests/project_tools.rs
@@ -6090,3 +6090,107 @@ fn local_project_image_preview_obeys_auto_file_read_policy() {
 
     fs::remove_dir_all(root).ok();
 }
+
+#[test]
+fn local_project_resource_previews_require_registered_safe_resources() {
+    let root = unique_project_path();
+    init_local_game_project_at(&root, "resource-preview-policy", "资源预览策略项目")
+        .expect("project init");
+    fs::create_dir_all(root.join("assets")).expect("asset dir");
+    fs::create_dir_all(root.join("game")).expect("game dir");
+    fs::write(root.join("game/design.md"), "# 玩法设计\n\n安全正文").expect("project document");
+    fs::write(
+        root.join("assets/icon.svg"),
+        "<svg xmlns=\"http://www.w3.org/2000/svg\"><circle cx=\"2\" cy=\"2\" r=\"2\"/></svg>",
+    )
+    .expect("svg resource");
+    fs::write(
+        root.join("assets/bgm.mp3"),
+        [b'I', b'D', b'3', 4, 0, 0, 0, 0, 0, 0],
+    )
+    .expect("audio resource");
+    fs::write(root.join("game/unregistered.md"), "不应读取").expect("unregistered document");
+
+    let source = || GameCreationAppAssetSource {
+        kind: GameCreationAppAssetSourceKind::Generated,
+        canvas_project_id: None,
+        resource_id: None,
+        asset_object_id: None,
+        task_id: None,
+        prompt: None,
+        model: None,
+        generation_route: None,
+        generation_kind: None,
+        reference_resource_ids: Vec::new(),
+    };
+    register_local_asset_at(
+        &root,
+        "game/design.md",
+        "design-document",
+        "text/markdown",
+        "generated",
+        source(),
+    )
+    .expect("register document");
+    register_local_asset_at(
+        &root,
+        "assets/icon.svg",
+        "icon",
+        "image/svg+xml",
+        "generated",
+        source(),
+    )
+    .expect("register svg");
+    register_local_asset_at(
+        &root,
+        "assets/bgm.mp3",
+        "bgm",
+        "audio/mpeg",
+        "generated",
+        source(),
+    )
+    .expect("register audio");
+
+    let document = read_local_project_text_preview(
+        root.to_string_lossy().into_owned(),
+        "game/design.md".to_string(),
+    )
+    .expect("read registered document");
+    assert_eq!(document.media_type, "text/markdown");
+    assert!(document.content.contains("安全正文"));
+
+    let svg = read_local_project_media_preview(
+        root.to_string_lossy().into_owned(),
+        "assets/icon.svg".to_string(),
+        "art".to_string(),
+    )
+    .expect("read registered svg");
+    assert_eq!(svg.media_type, "image/svg+xml");
+    let audio = read_local_project_media_preview(
+        root.to_string_lossy().into_owned(),
+        "assets/bgm.mp3".to_string(),
+        "audio".to_string(),
+    )
+    .expect("read registered audio");
+    assert_eq!(audio.media_type, "audio/mpeg");
+
+    let unregistered_error = read_local_project_text_preview(
+        root.to_string_lossy().into_owned(),
+        "game/unregistered.md".to_string(),
+    )
+    .expect_err("unregistered document rejected");
+    assert!(unregistered_error.contains("已登记的文档资源"));
+    assert!(read_local_project_text_preview(
+        root.to_string_lossy().into_owned(),
+        "../outside.md".to_string(),
+    )
+    .is_err());
+    assert!(read_local_project_media_preview(
+        root.to_string_lossy().into_owned(),
+        "assets/bgm.mp3".to_string(),
+        "art".to_string(),
+    )
+    .is_err());
+
+    fs::remove_dir_all(root).ok();
+}
diff --git a/apps/ai-game-creator-shell/src/styles.css b/apps/ai-game-creator-shell/src/styles.css
index e692bba45..6131b64a1 100644
--- a/apps/ai-game-creator-shell/src/styles.css
+++ b/apps/ai-game-creator-shell/src/styles.css
@@ -4160,11 +4160,21 @@ iframe.preview-frame {
   gap: 6px;
   min-height: 0;
   padding: 18px 20px 24px;
-  overflow: auto;
+  overflow: hidden;
   overscroll-behavior: contain;
   scrollbar-gutter: stable;
 }
 
+.game-resource-focus--document .game-resource-focus-body,
+.game-resource-focus--art .game-resource-focus-body,
+.game-resource-focus--audio .game-resource-focus-body {
+  grid-template-rows: minmax(0, 1fr) auto;
+}
+
+.game-resource-focus--version .game-resource-focus-body {
+  overflow: auto;
+}
+
 .game-resource-focus-close {
   display: grid;
   width: 28px;
@@ -4234,6 +4244,66 @@ iframe.preview-frame {
   place-items: center;
 }
 
+.game-resource-media-preview,
+.game-resource-audio-preview {
+  position: relative;
+  display: grid;
+  min-width: 0;
+  min-height: 0;
+  margin-bottom: 8px;
+  overflow: hidden;
+  border: 1px solid #ead8cf;
+  border-radius: 12px;
+  background: #faf7f5;
+  place-items: center;
+}
+
+.game-resource-media-preview {
+  background: linear-gradient(45deg, #f1ebe7 25%, transparent 25%),
+    linear-gradient(-45deg, #f1ebe7 25%, transparent 25%),
+    linear-gradient(45deg, transparent 75%, #f1ebe7 75%),
+    linear-gradient(-45deg, transparent 75%, #f1ebe7 75%), #faf7f5;
+  background-position:
+    0 0,
+    0 8px,
+    8px -8px,
+    -8px 0;
+  background-size: 16px 16px;
+}
+
+.game-resource-media-preview img,
+.game-resource-media-preview video {
+  display: block;
+  max-width: 100%;
+  max-height: 100%;
+  object-fit: contain;
+}
+
+.game-resource-media-preview video {
+  width: 100%;
+  height: 100%;
+  background: #211d1b;
+}
+
+.game-resource-audio-preview {
+  align-content: center;
+  padding: 28px;
+  background: linear-gradient(145deg, #fffaf6, #f5e7df);
+}
+
+.game-resource-audio-preview audio {
+  width: min(620px, 100%);
+}
+
+.game-resource-media-preview p,
+.game-resource-audio-preview p {
+  margin: 0;
+  padding: 20px;
+  color: #92776c;
+  font-size: 12px;
+  text-align: center;
+}
+
 .game-resource-image-preview img {
   position: absolute;
   inset: 0;
@@ -4252,8 +4322,8 @@ iframe.preview-frame {
 }
 
 .game-resource-document-body {
-  height: max-content;
-  min-height: 220px;
+  min-width: 0;
+  min-height: 0;
   margin-top: 6px;
   padding: 14px;
   border-radius: 10px;
@@ -4261,8 +4331,10 @@ iframe.preview-frame {
   color: #765c51;
   font-size: 12px;
   line-height: 1.6;
-  overflow: hidden;
+  overflow: auto;
   overflow-wrap: anywhere;
+  overscroll-behavior: contain;
+  scrollbar-gutter: stable;
   user-select: text;
 }
 
@@ -4344,6 +4416,19 @@ iframe.preview-frame {
   text-decoration: underline;
 }
 
+.game-resource-document-link-text {
+  color: #8f5e49;
+  text-decoration: underline dotted;
+}
+
+.game-resource-document-image-placeholder {
+  display: inline-block;
+  padding: 0.2em 0.45em;
+  border-radius: 5px;
+  background: #eaded7;
+  color: #806559;
+}
+
 .game-resource-document-body table {
   width: 100%;
   border-collapse: collapse;
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 41bdd78ea..2e8cc4c12 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
@@ -50,15 +50,15 @@ import {
   type ProjectResourceGraphReadModel,
 } from './resourceDependencyGraphModel';
 import { ResourceDependencyOverlay } from './ResourceDependencyOverlay';
-import { useProjectResourceCanvasLayout } from './useProjectResourceCanvasLayout';
 import {
   type ProjectAgentResultSummary,
   type ProjectAttachmentResult,
   type ProjectResource,
   type ProjectResourceCategory,
-  type ProjectVersionResourceSummary,
   projectResourcesFromReadModels,
+  type ProjectVersionResourceSummary,
 } from './resourceProjectionModel';
+import { useProjectResourceCanvasLayout } from './useProjectResourceCanvasLayout';
 
 export type {
   ProjectAgentResultSummary,
@@ -77,6 +77,20 @@ type LocalProjectImagePreview = {
   dataUrl: string;
 };
 
+type LocalProjectTextPreview = {
+  path: string;
+  mediaType: string;
+  byteLen: number;
+  content: string;
+};
+
+type LocalProjectMediaPreview = {
+  path: string;
+  mediaType: string;
+  byteLen: number;
+  dataUrl: string;
+};
+
 type ImagePreviewState =
   | { status: 'idle'; resourceId: null }
   | { status: 'loading'; resourceId: string }
@@ -87,6 +101,26 @@ type ImagePreviewState =
     }
   | { status: 'failed'; resourceId: string; error: string };
 
+type TextPreviewState =
+  | { status: 'idle'; resourceId: null }
+  | { status: 'loading'; resourceId: string }
+  | {
+      status: 'loaded';
+      resourceId: string;
+      preview: LocalProjectTextPreview;
+    }
+  | { status: 'failed'; resourceId: string; error: string };
+
+type MediaPreviewState =
+  | { status: 'idle'; resourceId: null }
+  | { status: 'loading'; resourceId: string }
+  | {
+      status: 'loaded';
+      resourceId: string;
+      preview: LocalProjectMediaPreview;
+    }
+  | { status: 'failed'; resourceId: string; error: string };
+
 export type ProjectAgentRuntimeSummary = {
   group: GameCreationAppAgentGroup;
   label: string;
@@ -178,6 +212,70 @@ function isRasterImageResource(resource: ProjectResource) {
   );
 }
 
+function isExtendedArtMediaResource(resource: ProjectResource) {
+  const mediaType = resource.mediaType.toLowerCase();
+  return (
+    resource.category === 'art' &&
+    (mediaType === 'image/svg+xml' ||
+      mediaType.startsWith('video/') ||
+      /\.(gif|svg|avif|bmp|mp4|webm|mov)$/iu.test(resource.path))
+  );
+}
+
+function mediaPreviewErrorMessage(error: unknown) {
+  const message = error instanceof Error ? error.message : String(error);
+  if (message.includes('项目权限策略要求用户确认')) {
+    return '当前项目策略要求先确认读取资源';
+  }
+  if (message.includes('项目权限策略拒绝执行')) {
+    return '当前项目策略不允许读取资源';
+  }
+  if (message.includes('不能超过')) {
+    return message;
+  }
+  if (message.includes('UTF-8') || message.includes('只支持')) {
+    return message;
+  }
+  if (message.includes('脚本或外部资源引用')) {
+    return message;
+  }
+  if (message.includes('发生漂移') || message.includes('发生替换')) {
+    return '资源读取期间发生变化，请关闭后重试';
+  }
+  return '资源暂时无法读取，请关闭后重试';
+}
+
+function formatMediaDuration(duration: number | null) {
+  if (duration === null || !Number.isFinite(duration) || duration < 0) {
+    return '载入后显示';
+  }
+  const totalSeconds = Math.floor(duration);
+  const minutes = Math.floor(totalSeconds / 60);
+  const seconds = totalSeconds % 60;
+  return `${minutes}:${seconds.toString().padStart(2, '0')}`;
+}
+
+function SafeProjectMarkdown({ content }: { content: string }) {
+  return (
+    <ReactMarkdown
+      skipHtml
+      remarkPlugins={[remarkGfm]}
+      components={{
+        a: ({ children }) => (
+          <span className="game-resource-document-link-text">{children}</span>
+        ),
+        img: ({ alt }) => (
+          <span className="game-resource-document-image-placeholder">
+            {alt ? `图片：${alt}` : '文档图片已省略'}
+          </span>
+        ),
+      }}
+    >
+      {content}
+    </ReactMarkdown>
+  );
+}
+
 function imagePreviewErrorMessage(error: unknown) {
   const message = error instanceof Error ? error.message : String(error);
   if (message.includes('项目权限策略要求用户确认')) {
@@ -323,6 +421,15 @@ export default function ProjectDevelopmentView({
     status: 'idle',
     resourceId: null,
   });
+  const [textPreview, setTextPreview] = useState<TextPreviewState>({
+    status: 'idle',
+    resourceId: null,
+  });
+  const [mediaPreview, setMediaPreview] = useState<MediaPreviewState>({
+    status: 'idle',
+    resourceId: null,
+  });
+  const [mediaDuration, setMediaDuration] = useState<number | null>(null);
   const resourceCanvasRef = useRef<HTMLDivElement>(null);
   const resourceFocusRef = useRef<HTMLElement>(null);
   const resourceListScrollRef = useRef({ left: 0, top: 0 });
@@ -556,6 +663,10 @@ export default function ProjectDevelopmentView({
   const focusedResourceIsImage = Boolean(
     focusedResource && isRasterImageResource(focusedResource),
   );
+  const focusedResourceIsExtendedArtMedia = Boolean(
+    focusedResource && isExtendedArtMediaResource(focusedResource),
+  );
+  const focusedResourceIsAudio = focusedResource?.category === 'audio';
   const hasRegisteredArtImageAssets = manifest.assets.some(
     (asset) =>
       asset.kind === 'art-spritesheet' && asset.mediaType.startsWith('image/'),
@@ -594,6 +705,20 @@ export default function ProjectDevelopmentView({
   const FocusIcon = focusedResource
     ? categoryIcons[focusedResource.category]
     : FileText;
+  const focusedPreviewMediaType =
+    focusedResource &&
+    mediaPreview.status === 'loaded' &&
+    mediaPreview.resourceId === focusedResource.id
+      ? mediaPreview.preview.mediaType
+      : focusedResource &&
+          imagePreview.status === 'loaded' &&
+          imagePreview.resourceId === focusedResource.id
+        ? imagePreview.preview.mediaType
+        : focusedResource &&
+            textPreview.status === 'loaded' &&
+            textPreview.resourceId === focusedResource.id
+          ? textPreview.preview.mediaType
+          : focusedResource?.mediaType;
 
   useEffect(() => {
     if (embeddedPreviewUrl) {
@@ -667,6 +792,118 @@ export default function ProjectDevelopmentView({
     };
   }, [focusedResource, focusedResourceIsImage, projectPath]);
 
+  useEffect(() => {
+    if (!focusedResource || focusedResource.category !== 'document') {
+      setTextPreview({ status: 'idle', resourceId: null });
+      return undefined;
+    }
+    if (focusedResource.content !== undefined) {
+      setTextPreview({
+        status: 'loaded',
+        resourceId: focusedResource.id,
+        preview: {
+          path: focusedResource.path,
+          mediaType: focusedResource.mediaType,
+          byteLen: new TextEncoder().encode(focusedResource.content).byteLength,
+          content: focusedResource.content,
+        },
+      });
+      return undefined;
+    }
+    const invoke = window.__TAURI__?.core?.invoke;
+    if (!invoke) {
+      setTextPreview({
+        status: 'failed',
+        resourceId: focusedResource.id,
+        error: '文档预览需要在客户端内打开',
+      });
+      return undefined;
+    }
+
+    let cancelled = false;
+    setTextPreview({ status: 'loading', resourceId: focusedResource.id });
+    void invoke<LocalProjectTextPreview>('read_local_project_text_preview', {
+      projectPath,
+      relativePath: focusedResource.path,
+    })
+      .then((preview) => {
+        if (!cancelled) {
+          setTextPreview({
+            status: 'loaded',
+            resourceId: focusedResource.id,
+            preview,
+          });
+        }
+      })
+      .catch((error: unknown) => {
+        if (!cancelled) {
+          setTextPreview({
+            status: 'failed',
+            resourceId: focusedResource.id,
+            error: mediaPreviewErrorMessage(error),
+          });
+        }
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [focusedResource, projectPath]);
+
+  useEffect(() => {
+    if (
+      !focusedResource ||
+      (!focusedResourceIsExtendedArtMedia && !focusedResourceIsAudio)
+    ) {
+      setMediaPreview({ status: 'idle', resourceId: null });
+      setMediaDuration(null);
+      return undefined;
+    }
+    const invoke = window.__TAURI__?.core?.invoke;
+    if (!invoke) {
+      setMediaPreview({
+        status: 'failed',
+        resourceId: focusedResource.id,
+        error: '媒体预览需要在客户端内打开',
+      });
+      return undefined;
+    }
+
+    let cancelled = false;
+    setMediaDuration(null);
+    setMediaPreview({ status: 'loading', resourceId: focusedResource.id });
+    void invoke<LocalProjectMediaPreview>('read_local_project_media_preview', {
+      projectPath,
+      relativePath: focusedResource.path,
+      category: focusedResource.category,
+    })
+      .then((preview) => {
+        if (!cancelled) {
+          setMediaPreview({
+            status: 'loaded',
+            resourceId: focusedResource.id,
+            preview,
+          });
+        }
+      })
+      .catch((error: unknown) => {
+        if (!cancelled) {
+          setMediaPreview({
+            status: 'failed',
+            resourceId: focusedResource.id,
+            error: mediaPreviewErrorMessage(error),
+          });
+        }
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [
+    focusedResource,
+    focusedResourceIsAudio,
+    focusedResourceIsExtendedArtMedia,
+    projectPath,
+  ]);
+
   useLayoutEffect(() => {
     if (focusedResource) {
       resourceFocusRef.current?.focus({ preventScroll: true });
@@ -849,6 +1086,101 @@ export default function ProjectDevelopmentView({
                     )}
                   </div>
                 ) : null}
+                {focusedResourceIsExtendedArtMedia ? (
+                  <div
+                    className="game-resource-media-preview"
+                    aria-label={`${focusedResource.label} 美术媒体预览`}
+                  >
+                    {mediaPreview.status === 'loaded' &&
+                    mediaPreview.resourceId === focusedResource.id ? (
+                      mediaPreview.preview.mediaType.startsWith('video/') ? (
+                        <video
+                          src={mediaPreview.preview.dataUrl}
+                          controls
+                          preload="metadata"
+                          aria-label={`${focusedResource.label} 视频预览`}
+                          onError={() =>
+                            setMediaPreview({
+                              status: 'failed',
+                              resourceId: focusedResource.id,
+                              error: '视频内容无法解码，请重新生成或替换该资源',
+                            })
+                          }
+                        />
+                      ) : (
+                        <img
+                          src={mediaPreview.preview.dataUrl}
+                          alt={`${focusedResource.label} 美术媒体预览`}
+                          onError={() =>
+                            setMediaPreview({
+                              status: 'failed',
+                              resourceId: focusedResource.id,
+                              error: '美术资源无法解码，请重新生成或替换该资源',
+                            })
+                          }
+                        />
+                      )
+                    ) : mediaPreview.status === 'failed' &&
+                      mediaPreview.resourceId === focusedResource.id ? (
+                      <p role="alert">{mediaPreview.error}</p>
+                    ) : (
+                      <p role="status">正在载入美术资源…</p>
+                    )}
+                  </div>
+                ) : null}
+                {focusedResourceIsAudio ? (
+                  <div
+                    className="game-resource-audio-preview"
+                    aria-label={`${focusedResource.label} 音频预览`}
+                  >
+                    {mediaPreview.status === 'loaded' &&
+                    mediaPreview.resourceId === focusedResource.id ? (
+                      <audio
+                        src={mediaPreview.preview.dataUrl}
+                        controls
+                        preload="metadata"
+                        aria-label={`${focusedResource.label} 音频播放器`}
+                        onLoadedMetadata={(event) =>
+                          setMediaDuration(event.currentTarget.duration)
+                        }
+                        onDurationChange={(event) =>
+                          setMediaDuration(event.currentTarget.duration)
+                        }
+                        onError={() =>
+                          setMediaPreview({
+                            status: 'failed',
+                            resourceId: focusedResource.id,
+                            error: '音频内容无法解码，请重新生成或替换该资源',
+                          })
+                        }
+                      />
+                    ) : mediaPreview.status === 'failed' &&
+                      mediaPreview.resourceId === focusedResource.id ? (
+                      <p role="alert">{mediaPreview.error}</p>
+                    ) : (
+                      <p role="status">正在载入音频…</p>
+                    )}
+                  </div>
+                ) : null}
+                {focusedResource.category === 'document' ? (
+                  <div className="game-resource-document-body">
+                    {textPreview.status === 'loaded' &&
+                    textPreview.resourceId === focusedResource.id ? (
+                      textPreview.preview.content.trim() ? (
+                        <SafeProjectMarkdown
+                          content={textPreview.preview.content}
+                        />
+                      ) : (
+                        <p role="status">文档为空</p>
+                      )
+                    ) : textPreview.status === 'failed' &&
+                      textPreview.resourceId === focusedResource.id ? (
+                      <p role="alert">{textPreview.error}</p>
+                    ) : (
+                      <p role="status">正在载入文档…</p>
+                    )}
+                  </div>
+                ) : null}
                 <dl className="game-resource-focus-metadata">
                   <div>
                     <dt>资源路径</dt>
@@ -856,7 +1188,7 @@ export default function ProjectDevelopmentView({
                   </div>
                   <div>
                     <dt>资源类型</dt>
-                    <dd>{focusedResource.mediaType}</dd>
+                    <dd>{focusedPreviewMediaType}</dd>
                   </div>
                   <div>
                     <dt>资源来源</dt>
@@ -868,6 +1200,12 @@ export default function ProjectDevelopmentView({
                       <dd>{focusedResource.taskTitle}</dd>
                     </div>
                   ) : null}
+                  {focusedResourceIsAudio ? (
+                    <div>
+                      <dt>音频时长</dt>
+                      <dd>{formatMediaDuration(mediaDuration)}</dd>
+                    </div>
+                  ) : null}
                   {focusedResource.version ? (
                     <>
                       <div>
@@ -884,13 +1222,6 @@ export default function ProjectDevelopmentView({
                     </>
                   ) : null}
                 </dl>
-                {focusedResource.category === 'document' ? (
-                  <div className="game-resource-document-body">
-                    <ReactMarkdown remarkPlugins={[remarkGfm]}>
-                      {focusedResource.content ?? '文档内容尚未载入'}
-                    </ReactMarkdown>
-                  </div>
-                ) : null}
               </div>
             </section>
           ) : mode === 'resources' ? (
diff --git a/apps/ai-game-creator-shell/tests/appSurface/project-development.suite.ts b/apps/ai-game-creator-shell/tests/appSurface/project-development.suite.ts
index 866cca49c..f1b9ec5b5 100644
--- a/apps/ai-game-creator-shell/tests/appSurface/project-development.suite.ts
+++ b/apps/ai-game-creator-shell/tests/appSurface/project-development.suite.ts
@@ -836,6 +836,153 @@ export function registerProjectWorkbenchFoundationTests() {
     expect(restoredCard?.getAttribute('aria-pressed')).toBe('true');
   });
 
+  it('loads registered documents, art media, and audio inside the central focus state', async () => {
+    const manifest = createGameCreationAppManifest(
+      'workbench-resource-media',
+      '资源媒体测试',
+    );
+    manifest.assets.push(
+      {
+        id: 'design-document',
+        kind: 'design-document',
+        mediaType: 'text/markdown',
+        localPath: 'game/design.md',
+        source: { kind: 'generated' },
+      },
+      {
+        id: 'art-svg',
+        kind: 'icon',
+        mediaType: 'image/svg+xml',
+        localPath: 'assets/icon.svg',
+        source: { kind: 'generated' },
+      },
+      {
+        id: 'audio-bgm',
+        kind: 'bgm',
+        mediaType: 'audio/mpeg',
+        localPath: 'assets/bgm.mp3',
+        source: { kind: 'generated' },
+      },
+    );
+    let layoutRevision = 0;
+    const invoke = vi.fn(
+      async (command: string, args?: Record<string, unknown>) => {
+        if (command === 'read_local_project_resource_graph') {
+          return resourceGraphForInputs(args);
+        }
+        if (command === 'read_local_project_resource_canvas_layout') {
+          return {
+            schemaVersion: 'game-creator-resource-layout.v1',
+            projectId: manifest.projectId,
+            mode: args?.mode,
+            revision: layoutRevision,
+            positions: [],
+            updatedAt: 0,
+          };
+        }
+        if (command === 'update_local_project_resource_canvas_layout') {
+          layoutRevision += 1;
+          return {
+            status: 'updated',
+            layout: {
+              schemaVersion: 'game-creator-resource-layout.v1',
+              projectId: manifest.projectId,
+              mode: args?.mode,
+              revision: layoutRevision,
+              positions: args?.positions,
+              updatedAt: layoutRevision,
+            },
+          };
+        }
+        if (command === 'read_local_project_text_preview') {
+          expect(args).toMatchObject({
+            projectPath: '/tmp/workbench-resource-media',
+            relativePath: 'game/design.md',
+          });
+          return {
+            path: 'game/design.md',
+            mediaType: 'text/markdown',
+            byteLen: 64,
+            content:
+              '# 本地设计文档\n\n[外部链接](https://example.com)\n\n![远程图片](https://example.com/image.png)\n\n<script>window.pwned = true</script>',
+          };
+        }
+        if (command === 'read_local_project_media_preview') {
+          if (args?.category === 'art') {
+            return {
+              path: 'assets/icon.svg',
+              mediaType: 'image/svg+xml',
+              byteLen: 48,
+              dataUrl: 'data:image/svg+xml;base64,PHN2Zy8+',
+            };
+          }
+          return {
+            path: 'assets/bgm.mp3',
+            mediaType: 'audio/mpeg',
+            byteLen: 1024,
+            dataUrl: 'data:audio/mpeg;base64,SUQz',
+          };
+        }
+        throw new Error(`unexpected invoke ${command}`);
+      },
+    );
+    window.__TAURI__ = { core: { invoke } };
+
+    render(
+      React.createElement(ProjectDevelopmentView, {
+        projectName: '资源媒体测试',
+        projectPath: '/tmp/workbench-resource-media',
+        manifest,
+        attachments: [],
+        recentRunStatus: null,
+        recentRunStopReason: null,
+        supervisor: React.createElement('div', null, '项目总控'),
+        onHomeOpen: vi.fn(),
+        onProjectsOpen: vi.fn(),
+      }),
+    );
+
+    fireEvent.click(await screen.findByRole('button', { name: /design\.md/ }));
+    const documentFocus = await screen.findByRole('region', {
+      name: 'design.md',
+    });
+    expect(
+      within(documentFocus).getByRole('heading', { name: '本地设计文档' }),
+    ).not.toBeNull();
+    expect(documentFocus.querySelector('script')).toBeNull();
+    expect(documentFocus.querySelector('a')).toBeNull();
+    expect(within(documentFocus).getByText('图片：远程图片')).not.toBeNull();
+    fireEvent.click(
+      within(documentFocus).getByRole('button', { name: '收起资源' }),
+    );
+
+    fireEvent.click(screen.getByRole('button', { name: /icon\.svg/ }));
+    const artPreview = await screen.findByLabelText('icon.svg 美术媒体预览');
+    await waitFor(() => {
+      expect(artPreview.querySelector('img')?.getAttribute('src')).toBe(
+        'data:image/svg+xml;base64,PHN2Zy8+',
+      );
+    });
+    fireEvent.click(
+      within(screen.getByRole('region', { name: 'icon.svg' })).getByRole(
+        'button',
+        { name: '收起资源' },
+      ),
+    );
+
+    fireEvent.click(screen.getByRole('button', { name: /bgm\.mp3/ }));
+    const audio = (await screen.findByLabelText(
+      'bgm.mp3 音频播放器',
+    )) as HTMLAudioElement;
+    expect(audio.controls).toBe(true);
+    expect(audio.getAttribute('src')).toBe('data:audio/mpeg;base64,SUQz');
+    expect(screen.getByText('载入后显示')).not.toBeNull();
+    expect(invoke).toHaveBeenCalledWith(
+      'read_local_project_media_preview',
+      expect.objectContaining({ category: 'audio' }),
+    );
+  });
+
   it('renders, filters, highlights, and destroys the resource dependency overlay without pointer previews', async () => {
     const manifest = createGameCreationAppManifest(
       'workbench-resource-graph',
diff --git a/docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md b/docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md
index b4c7ecc2c..3886475cf 100644
--- a/docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md
+++ b/docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md
@@ -123,13 +123,14 @@ completed -> starting(nextSlice)
 idle -> focused(document|art|audio|version) -> idle
 ```
 
-- 文档：在中央画布展开并独立滚动。
-- 美术/音频：进入对应媒体聚焦状态，当前只展示已有预览或资源元数据。
+- 文档：合法 Agent 文本回执直接使用对话投影内容；项目文件只允许读取当前 manifest 已登记资产或已完成任务产物中的 Markdown、文本、JSON、YAML、TOML，必须经过 `file.read` auto 权限、相对路径、项目边界、普通文件、符号链接 / 硬链接、读取漂移、2 MiB、UTF-8 与扩展名白名单校验。正文使用不执行 HTML、不加载远程图片、不产生可点击外链的安全 Markdown 渲染，并在中央画布内独立滚动；读取失败显示错误空态。
+- 美术：PNG、JPEG、WEBP 继续使用图片魔数与像素边界预览；GIF、SVG、AVIF、BMP、MP4、WebM、MOV 通过新增受控媒体读取链路按文件签名校验后在中央画布放大聚焦。SVG 额外拒绝脚本、事件处理器、外部资源引用和实体声明；视频使用内置播放控件。读取失败显示错误空态。
+- 音频：只读取 manifest 已登记音频或已成功导入且登记到 manifest 的附件，按文件签名接受 MP3、WAV、OGG / Opus、M4A、AAC、FLAC；聚焦态展示实际格式、浏览器解码后的时长以及带播放进度和暂停能力的内置播放器。音频任务声明中的未登记路径继续不得读取或播放。
 - 版本：只展示正式版本 read model 的身份与修订元数据；版本引用高亮和替换留给后续切片。
 - mentor 最新决定：资源聚焦不提供工具栏，也不提供工具侧边栏。
 - 点击资源后，中央主视窗从 `resources.list` 切换为 `resources.focused.document / art / audio / version`，左侧平台导航、右侧 Supervisor 对话和底部 Agent 状态栏保持原位；聚焦容器只包含标题、资源主体、必要元数据与右上角收起按钮，不使用页面级浮层或可拖动标题栏。
 - 退出聚焦后恢复进入前的搜索条件、dependency / type 布局模式、资源画布滚动位置和选中资源；这些只属于当前前端会话，不写入布局 sidecar。
-- 本阶段不新增项目文件读取命令、美术编辑、音频播放 / 编辑、版本替换或运行模块。
+- 阶段四只新增上述受控读取与媒体展示，不新增资源聚焦工具栏 / 工具侧边栏，不新增美术编辑、音频编辑 / 替换、资源重新生成、不可变版本写入或运行模块。飞书原需求中“编辑并生成新资源”的条件项仍暂缓，不能只打开画板却缺少回写、`referenceResourceIds` 血缘登记、新资源自动选中与邻近布局的完整闭环。
 
 ### 4.4 历史成果与当前状态
 
@@ -273,7 +274,7 @@ type UpdateProjectResourceCanvasLayoutResult =
 
 ### 5.3 资源类型与替换兼容性（P1）
 
-实现状态（2026-08-03）：当前资源投影已收口到固定的“文档 -> 项目版本 -> 美术资源 -> 音乐音效资源”四区。文档只接收 Markdown / 文本 / JSON / YAML 等正式项目文档和合法 Agent 文本回执；项目版本只接收显式 `ProjectVersionResourceSummary` read model，未知任务产物不得兜底为版本；美术接收图片、SVG、动画和视频类产物；音频只接收 manifest 已登记音频资产或已成功导入的音频附件，任务声明中的未登记音频路径不冒充正式音频资源。无法识别的二进制任务产物和附件不进入资源画布。
+实现状态（2026-08-03）：当前资源投影已收口到固定的“文档 -> 项目版本 -> 美术资源 -> 音乐音效资源”四区。文档只接收 Markdown / 文本 / JSON / YAML 等正式项目文档和合法 Agent 文本回执；项目版本只接收显式 `ProjectVersionResourceSummary` read model，未知任务产物不得兜底为版本；美术接收图片、SVG、动画和视频类产物；音频只接收 manifest 已登记音频资产或已成功导入并登记到 manifest 的音频附件，任务声明中的未登记音频路径不冒充正式音频资源。无法识别的二进制任务产物和附件不进入资源画布。阶段四已为本地文档、安全 SVG / 扩展图片 / 视频和音频补齐受控读取、中央聚焦、失败空态与媒体播放；这些都是只读表现层，不改变资源投影或 manifest 真相。
 
 资源身份固定使用 manifest asset ID、正式 version ID、Agent ID + run ID 或已导入资源稳定路径；显示标题、来源文案变化不得改变 `resourceId`，从而避免布局、依赖边、选择和聚焦状态因改名失效。
 
@@ -425,7 +426,7 @@ type ProjectAgentMudPointAttribution = {
 
 ## 8. 非目标
 
-- 本切片不实现资源卡手动拖动，也不实现资源聚焦工具栏、资源聚焦工具侧边栏、后续项目文件读取、美术编辑、音频播放 / 编辑、资源替换、不可变迭代版本写入、运行模块扩展、测试切片、数值参数或泥点归因；已实现的资源关系图只提供 Rust 只读拓扑与前端派生展示，不建立新的资源业务真相。
+- 本切片不实现资源卡手动拖动，也不实现资源聚焦工具栏、资源聚焦工具侧边栏、美术编辑、音频编辑 / 替换、资源重新生成、资源替换、不可变迭代版本写入、运行模块扩展、测试切片、数值参数或泥点归因；已实现的资源读取和关系图只提供 Rust 只读模型与前端派生展示，不建立新的资源业务真相。
 - 本切片不持久化资源聚焦状态、画布缩放 / 平移、搜索条件、筛选条件或当前 mode；聚焦退出时的列表上下文恢复只限当前前端会话，这些状态如需跨重启保存必须另行扩展合同，不能塞入 `game-creator-resource-layout.v1`。
 - 不修改 SpacetimeDB schema。
 - 不开放普通用户 Agent.md/Skill。
diff --git a/docs/project-memory/shared-memory/decision-log.md b/docs/project-memory/shared-memory/decision-log.md
index c70289246..89510f57e 100644
--- a/docs/project-memory/shared-memory/decision-log.md
+++ b/docs/project-memory/shared-memory/decision-log.md
@@ -1,5 +1,13 @@
 # 决策记录
 
+## 2026-08-03 资源聚焦阶段四采用只读受控文档与媒体链路
+
+- 背景：阶段一至三已经完成资源卡禁拖、固定四类资源投影与中央聚焦容器，但只有 PNG / JPEG / WEBP 和合法 Agent 文本回执具备真实主体预览；本地文档、SVG / 视频与音频仍只有路径和元数据。飞书需求同时把“编辑并生成新资源”写为条件项，而当前仓库尚未具备从画板返回后的血缘登记与自动选中闭环。
+- 决策：本地文档和媒体统一通过 Tauri 只读命令消费当前 manifest / 已完成任务登记范围，执行 `file.read` auto 权限、路径边界、普通文件、链接、大小、读取漂移与文件身份复核；文本限白名单格式和 UTF-8，Markdown 不执行 HTML、不加载远程图片、不提供活动外链；媒体按文件签名校验，SVG 拒绝活动内容与外部引用，音视频使用 WebView 原生控件。Agent 文本回执继续直接使用对话投影。当前不增加半成品美术编辑按钮，必须等画板回写、保留原资源、`referenceResourceIds`、新资源自动选中和邻近自动布局可一次闭环时再开放。
+- 边界：不修改 manifest、SpacetimeDB、资源投影身份、布局 sidecar、资源卡拖动或 External Editor API；不提供资源聚焦工具栏 / 工具侧边栏，不做音频编辑 / 替换或美术资源重生成。
+- 验证方式：Rust 单测与命令测试覆盖 UTF-8 / 扩展名、文件签名、活动 SVG、符号链接 / 硬链接、未登记资源、类别错配和权限；AppSurface 覆盖本地 Markdown 安全渲染、SVG data URL、音频播放器和中央聚焦状态；追加 shell typecheck、Rust 定向测试、编码检查与 `git diff --check`。
+- 关联文档：`docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md`、`docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md`。
+
 ## 2026-08-03 资源卡手动拖动暂缓并完成固定资源投影与中央聚焦
 
 - 背景：飞书《陶泥儿GameAgent-V1.0 项目开发界面需求》曾要求资源卡可拖动，并由后续 PRD、技术方案和实现扩展为手动布局 CAS、依赖线拖动预览与性能验收；mentor 最新决定明确资源卡暂时禁止拖动，资源聚焦也不需要工具栏或工具侧边栏。
diff --git a/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md b/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md
index aa0182fc4..745ee19a0 100644
--- a/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md
+++ b/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md
@@ -349,6 +349,7 @@ game-project/
 - Agent loop 中美术组 `Asset` 和音乐组 `SFX` 会读取 `.agent/manifest.json`；图片生成先通过 External Editor API 项目与素材库接口准备同名画布会话，再调用 `/api/external/v1/editor/images/generations`，携带 `projectId`、`assetFolderId`、`assetLabel`、`generationInputs.artSpec` 和 `canvasCompletion`，随后通过 `/api/external/v1/assets/read-url` 换签下载到受控本地 `assets/` 路径，登记为 `canvas` 来源资产并追加 `canvas.asset_generate` 本地索引记录。API Key 不写入项目文件、agent.db、trace、manifest 或日志；未配置 Key 或生成失败时，图片产物型任务保持阻塞/失败，不能以文字计划完成。音乐组仍只建议同步已有音频资源，不调用图片生成接口。
 - `canvas.asset_import` 当前作为最小真实链路：导入项目目录内已有文件为 `canvas` 来源资产，并要求记录画板项目 ID 以及 resourceId 或 assetObjectId。
 - 项目工作台点击已登记图片时必须在中央主视窗的资源聚焦状态中直接渲染图片，而不是只展示路径与 MIME。图片通过受控 Tauri 命令从项目 `assets/` / `game/` 读取，只允许 manifest 已登记资产或已完成任务产物，并复用 `file.read` auto 权限、图片魔数、文件大小、像素尺寸、普通文件、路径漂移和符号链接校验后以 data URL 返回；首版只支持 PNG、JPEG、WEBP，不向 WebView 暴露任意本机文件协议或绝对路径。
+- 2026-08-03 阶段四在上述图片链路外新增 `read_local_project_text_preview` 与 `read_local_project_media_preview`。前者只接收当前 manifest 已登记文档或已完成任务中的 Markdown / 文本 / JSON / YAML / TOML，限制 2 MiB 与 UTF-8；Agent 文本回执继续直接消费合法对话投影，不反查本地路径。后者的美术分支接收 GIF、安全 SVG、AVIF、BMP、MP4、WebM、MOV，音频分支只接收 manifest 已登记的 MP3、WAV、OGG / Opus、M4A、AAC、FLAC，二进制媒体限制 32 MiB。两条命令统一执行 `file.read` auto 权限、规范化相对路径、项目边界、敏感路径、普通文件、父目录链接、硬链接、读取漂移和重开身份复核；媒体按文件签名而非只按扩展名或 MIME 建立 data URL，SVG 额外拒绝活动内容与外部引用。
 - `canvas.export_import` 复用 `/editor/canvas` 已有素材导出 ZIP 格式，读取根 `metadata.json`、复制 `images/` / `media/` / `sequences/` 到本地项目 `assets/canvas-imports/`，再按导出层登记为 `canvas` 来源资产；导出包不保存真实 resourceId 时，使用 `canvas-export:<file>` 作为可追踪 assetObjectId，不伪造后端资源行。
 
 ## GameAgent V1.0 项目开发工作台首版界面
@@ -360,7 +361,7 @@ game-project/
 - 页面骨架固定为左侧现有全局导航、中间主视窗、右侧陶泥儿对话和底部子 Agent 状态栏；不新建第二套客户端或平行项目页。
 - 中间主视窗提供 `资源管理 / 运行` 切换。`code-prototype` 任务完成前运行入口保持视觉不可用，但仍可点击查看“当前无可运行版本”，不能使用会阻断说明交互的原生 `disabled` 或 `aria-disabled`；完成后才允许进入运行表现层。切回资源管理只修改前端展示态，不伪造后端预览暂停结果。
 - 资源管理从当前 `GameCreationAppManifest`、合法 Agent 文本回执、已导入附件和显式项目版本 read model 派生资源，固定按文档、项目版本、美术资源、音乐音效资源分区；未知任务产物不再兜底为版本，任务声明中的未登记音频也不冒充正式音频。`按依赖 / 按类型` 使用各自前端排列，dependency 模式额外绘制当前 manifest 与资源投影可证明的依赖关系。排列与图层都不写回 manifest，不能推断或伪造缺失依赖。
-- 资源卡支持点击聚焦、搜索和类型筛选。2026-07-28 起完成两套二维坐标与本地 CAS sidecar；2026-07-31 起 dependency 模式增加不持久化的原生 SVG 关系图层。2026-08-03 mentor 决定暂缓资源卡拖动，当前卡片不挂载 Pointer Down / Move / Up / Cancel 拖动入口，只允许自动布局和点击聚焦。聚焦态替换中央主视窗内容，保留左侧导航、右侧对话和底部 Agent 状态栏，退出后恢复搜索、布局模式、滚动位置与选中资源；不提供工具栏、工具侧边栏或可拖动标题栏。本阶段不新增项目文件读取、美术编辑、音频播放 / 编辑、版本替换或运行模块。
+- 资源卡支持点击聚焦、搜索和类型筛选。2026-07-28 起完成两套二维坐标与本地 CAS sidecar；2026-07-31 起 dependency 模式增加不持久化的原生 SVG 关系图层。2026-08-03 mentor 决定暂缓资源卡拖动，当前卡片不挂载 Pointer Down / Move / Up / Cancel 拖动入口，只允许自动布局和点击聚焦。聚焦态替换中央主视窗内容，保留左侧导航、右侧对话和底部 Agent 状态栏，退出后恢复搜索、布局模式、滚动位置与选中资源；不提供工具栏、工具侧边栏或可拖动标题栏。阶段四已补齐安全本地文档、扩展美术媒体与音频聚焦，正文独立滚动，视频 / 音频使用内置媒体控件，失败显示空态；美术编辑、音频编辑 / 替换、版本替换或运行模块仍不在本阶段。
 - 运行表现层首版直接嵌入当前项目的 loopback 游戏画面，并展示上一项 / 暂停继续 / 下一项切片控制、素材信息和数值微调面板。`preview.start` 启动本地 server 后把真实 URL 回写工作台，`preview.open` 只激活客户端内运行视图，不再调用系统浏览器；切片、参数调整和自然语言新增调节项首版仍只保留本地 UI 草稿，不修改代码或 manifest。
 - 右侧继续复用现有 Project Supervisor 会话、Runtime 澄清和确认链路；输入区展示 `严格审批 / 风险审批 / 无需审批` 独立面板。P0 只有严格审批可选；风险审批和无需审批保持视觉不可用但允许点击查看原因，不替代 Runtime 的逐动作权限、确认、sandbox 或 reconciliation 门禁。风险 Rank 算法记录在 `docs/project-memory/todos/【待解决】AI游戏创作高风险审批Rank-2026-07-20.md`，前端不得自行计算。
 - 底部状态栏默认展示策划、美术、程序 3 组，并允许在同一栏展开数值、音频、发布组；状态来自 manifest 与当前 Supervisor run 的 Runtime，悬停显示当前任务与进度。累计泥点必须等待后端计费归因投影；Agent.md 编辑和自定义 Skill 在来源审核、版本、权限、sandbox 与回滚合同完备前不向普通用户开放。
-- 
2.52.0


From ba996aad80105aab763f016e2695ee46ba9f57a7 Mon Sep 17 00:00:00 2001
From: menghao <mh18530625731@163.com>
Date: Mon, 3 Aug 2026 17:51:59 +0800
Subject: [PATCH 13/27] =?UTF-8?q?=E5=AE=8C=E6=88=90=E8=B5=84=E6=BA=90?=
 =?UTF-8?q?=E4=BE=9D=E8=B5=96=E6=8E=92=E5=88=97=E9=98=B6=E6=AE=B5=E4=BA=94?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

计算资源引用 SCC 与任务深度下限
拆分 producer assignment 和布局深度合同
补齐依赖布局回归测试
同步工作台 PRD、技术方案与项目记忆
---
 .../src/project/resource_dependency_graph.rs  | 134 ++++++++++++++++--
 .../resourceDependencyGraphModel.ts           |  19 ++-
 .../tests/ResourceDependencyOverlay.test.ts   |   2 +
 .../appSurface/project-development.suite.ts   |  19 ++-
 .../resourceDependencyGraphModel.test.ts      |  27 +++-
 ...AI游戏创作】项目开发工作台PRD-2026-07-20.md |   2 +
 .../shared-memory/decision-log.md             |   8 ++
 ...�案】AI游戏创作智能体App实施计划-2026-06-24.md |   4 +-
 8 files changed, 193 insertions(+), 22 deletions(-)

diff --git a/apps/ai-game-creator-shell/src-tauri/src/project/resource_dependency_graph.rs b/apps/ai-game-creator-shell/src-tauri/src/project/resource_dependency_graph.rs
index 3cf87fe77..917071ea2 100644
--- a/apps/ai-game-creator-shell/src-tauri/src/project/resource_dependency_graph.rs
+++ b/apps/ai-game-creator-shell/src-tauri/src/project/resource_dependency_graph.rs
@@ -50,6 +50,12 @@ pub(crate) struct ProjectResourceConnectionIndex {
 pub(crate) struct ProjectResourceProducerAssignment {
     pub resource_id: String,
     pub task_id: String,
+}
+
+#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub(crate) struct ProjectResourceDependencyDepth {
+    pub resource_id: String,
     pub dependency_depth: u32,
 }
 
@@ -61,6 +67,7 @@ pub(crate) struct ProjectResourceGraphReadModel {
     pub task_flows: Vec<ProjectResourceTaskFlow>,
     pub connection_index: Vec<ProjectResourceConnectionIndex>,
     pub producer_assignments: Vec<ProjectResourceProducerAssignment>,
+    pub dependency_depths: Vec<ProjectResourceDependencyDepth>,
     pub unresolved_reference_resource_ids: Vec<String>,
     pub cyclic_resource_ids: Vec<String>,
     pub cyclic_task_ids: Vec<String>,
@@ -194,6 +201,7 @@ fn analyze_directed_cycles<'a>(
 fn dependency_depth_by_node(
     analysis: &CycleAnalysis,
     edges: &[DirectedEdge],
+    minimum_depth_by_node: &BTreeMap<String, u32>,
 ) -> BTreeMap<String, u32> {
     let component_count = analysis
         .component_by_node
@@ -223,6 +231,12 @@ fn dependency_depth_by_node(
         .filter_map(|(component, degree)| (*degree == 0).then_some(component))
         .collect::<BTreeSet<_>>();
     let mut depth_by_component = vec![0u32; component_count];
+    for (node_id, minimum_depth) in minimum_depth_by_node {
+        let Some(component) = analysis.component_by_node.get(node_id) else {
+            continue;
+        };
+        depth_by_component[*component] = depth_by_component[*component].max(*minimum_depth);
+    }
     while let Some(component) = ready.pop_first() {
         for &target in &outgoing[component] {
             depth_by_component[target] =
@@ -464,7 +478,22 @@ pub(crate) fn build_project_resource_graph(
         })
         .collect::<Vec<_>>();
     let task_cycles = analyze_directed_cycles(task_by_id.keys(), &task_dependency_edges);
-    let task_dependency_depths = dependency_depth_by_node(&task_cycles, &task_dependency_edges);
+    let task_dependency_depths =
+        dependency_depth_by_node(&task_cycles, &task_dependency_edges, &BTreeMap::new());
+    let minimum_resource_dependency_depths = producer_by_resource_id
+        .iter()
+        .filter_map(|(resource_id, task_id)| {
+            task_dependency_depths
+                .get(task_id)
+                .copied()
+                .map(|depth| (resource_id.clone(), depth))
+        })
+        .collect::<BTreeMap<_, _>>();
+    let resource_dependency_depths = dependency_depth_by_node(
+        &reference_cycles,
+        &reference_directed_edges,
+        &minimum_resource_dependency_depths,
+    );
     let task_flows = task_dependency_edges
         .iter()
         .filter_map(|edge| {
@@ -538,13 +567,18 @@ pub(crate) fn build_project_resource_graph(
             .into_iter()
             .map(|(resource_id, task_id)| ProjectResourceProducerAssignment {
                 resource_id,
-                dependency_depth: task_dependency_depths
-                    .get(&task_id)
-                    .copied()
-                    .unwrap_or_default(),
                 task_id,
             })
             .collect(),
+        dependency_depths: resource_dependency_depths
+            .into_iter()
+            .map(
+                |(resource_id, dependency_depth)| ProjectResourceDependencyDepth {
+                    resource_id,
+                    dependency_depth,
+                },
+            )
+            .collect(),
         unresolved_reference_resource_ids: unresolved_reference_resource_ids.into_iter().collect(),
         cyclic_resource_ids: reference_cycles.cyclic_node_ids.into_iter().collect(),
         cyclic_task_ids: task_cycles.cyclic_node_ids.into_iter().collect(),
@@ -680,7 +714,18 @@ mod tests {
             graph
                 .producer_assignments
                 .iter()
-                .map(|assignment| (assignment.resource_id.as_str(), assignment.dependency_depth,))
+                .map(|assignment| (assignment.resource_id.as_str(), assignment.task_id.as_str()))
+                .collect::<BTreeMap<_, _>>(),
+            BTreeMap::from([
+                ("asset:spec", "art-director"),
+                ("asset:ui", "design-foundation"),
+            ]),
+        );
+        assert_eq!(
+            graph
+                .dependency_depths
+                .iter()
+                .map(|depth| (depth.resource_id.as_str(), depth.dependency_depth))
                 .collect::<BTreeMap<_, _>>(),
             BTreeMap::from([("asset:spec", 0), ("asset:ui", 1)]),
         );
@@ -720,6 +765,14 @@ mod tests {
         assert_eq!(graph.reference_edges.len(), 1);
         assert!(graph.task_flows.is_empty());
         assert!(graph.producer_assignments.is_empty());
+        assert_eq!(
+            graph
+                .dependency_depths
+                .iter()
+                .map(|depth| (depth.resource_id.as_str(), depth.dependency_depth))
+                .collect::<BTreeMap<_, _>>(),
+            BTreeMap::from([("asset:spec", 0), ("asset:ui", 1)]),
+        );
     }
 
     #[test]
@@ -810,10 +863,10 @@ mod tests {
             .all(|index| index.task_flow_ids.len() <= 2));
         assert_eq!(
             graph
-                .producer_assignments
+                .dependency_depths
                 .iter()
-                .find(|assignment| assignment.resource_id == "resource:4095")
-                .map(|assignment| assignment.dependency_depth),
+                .find(|depth| depth.resource_id == "resource:4095")
+                .map(|depth| depth.dependency_depth),
             Some(4095),
         );
     }
@@ -841,13 +894,72 @@ mod tests {
         );
 
         let depths = graph
-            .producer_assignments
+            .dependency_depths
             .iter()
-            .map(|assignment| (assignment.resource_id.as_str(), assignment.dependency_depth))
+            .map(|depth| (depth.resource_id.as_str(), depth.dependency_depth))
             .collect::<BTreeMap<_, _>>();
         assert_eq!(depths["source-resource"], 0);
         assert_eq!(depths["cycle-a-resource"], 1);
         assert_eq!(depths["cycle-b-resource"], 1);
         assert_eq!(depths["target-resource"], 2);
     }
+
+    #[test]
+    fn dependency_depth_uses_reference_sccs_after_task_depth_floors() {
+        let graph = build_project_resource_graph(
+            &manifest(
+                vec![
+                    task("source-task", &[]),
+                    task("late-task", &["source-task"]),
+                ],
+                vec![
+                    asset("base", Some("external-base"), &[], None),
+                    asset(
+                        "cycle-a",
+                        Some("external-cycle-a"),
+                        &["external-base", "external-cycle-b"],
+                        None,
+                    ),
+                    asset(
+                        "cycle-b",
+                        Some("external-cycle-b"),
+                        &["external-cycle-a"],
+                        None,
+                    ),
+                    asset(
+                        "target",
+                        Some("external-target"),
+                        &["external-cycle-b"],
+                        None,
+                    ),
+                ],
+            ),
+            vec![
+                resource("asset:base", Some("base"), None),
+                resource("asset:cycle-a", Some("cycle-a"), None),
+                resource("asset:cycle-b", Some("cycle-b"), None),
+                resource("asset:target", Some("target"), None),
+            ],
+            &[
+                serde_json::json!({"recordType": "agent.runtime.canvas.asset_generate", "assetId": "base", "agentId": "source-task"}),
+                serde_json::json!({"recordType": "agent.runtime.canvas.asset_generate", "assetId": "cycle-a", "agentId": "late-task"}),
+            ],
+            false,
+        );
+
+        let depths = graph
+            .dependency_depths
+            .iter()
+            .map(|depth| (depth.resource_id.as_str(), depth.dependency_depth))
+            .collect::<BTreeMap<_, _>>();
+        assert_eq!(depths["asset:base"], 0);
+        assert_eq!(depths["asset:cycle-a"], 1);
+        assert_eq!(depths["asset:cycle-b"], 1);
+        assert_eq!(depths["asset:target"], 2);
+        assert_eq!(
+            graph.cyclic_resource_ids,
+            vec!["asset:cycle-a", "asset:cycle-b"]
+        );
+        assert_eq!(graph.task_flows.len(), 1);
+    }
 }
diff --git a/apps/ai-game-creator-shell/src/view/project-development/resourceDependencyGraphModel.ts b/apps/ai-game-creator-shell/src/view/project-development/resourceDependencyGraphModel.ts
index 57d56662f..648c88700 100644
--- a/apps/ai-game-creator-shell/src/view/project-development/resourceDependencyGraphModel.ts
+++ b/apps/ai-game-creator-shell/src/view/project-development/resourceDependencyGraphModel.ts
@@ -33,6 +33,10 @@ export type ProjectResourceConnectionIndexDto = {
 export type ProjectResourceProducerAssignment = {
   resourceId: string;
   taskId: string;
+};
+
+export type ProjectResourceDependencyDepth = {
+  resourceId: string;
   dependencyDepth: number;
 };
 
@@ -42,6 +46,7 @@ export type ProjectResourceGraphReadModel = {
   taskFlows: ProjectResourceTaskFlow[];
   connectionIndex: ProjectResourceConnectionIndexDto[];
   producerAssignments: ProjectResourceProducerAssignment[];
+  dependencyDepths: ProjectResourceDependencyDepth[];
   unresolvedReferenceResourceIds: string[];
   cyclicResourceIds: string[];
   cyclicTaskIds: string[];
@@ -185,13 +190,19 @@ export function normalizeProjectResourceGraph(
       continue;
     }
     producerTaskIdByResourceId.set(assignment.resourceId, assignment.taskId);
+  }
+  for (const depth of readModel.dependencyDepths) {
     if (
-      Number.isSafeInteger(assignment.dependencyDepth) &&
-      assignment.dependencyDepth >= 0
+      resourceIds.has(depth.resourceId) &&
+      Number.isSafeInteger(depth.dependencyDepth) &&
+      depth.dependencyDepth >= 0
     ) {
       dependencyDepthByResourceId.set(
-        assignment.resourceId,
-        assignment.dependencyDepth,
+        depth.resourceId,
+        Math.max(
+          dependencyDepthByResourceId.get(depth.resourceId) ?? 0,
+          depth.dependencyDepth,
+        ),
       );
     }
   }
diff --git a/apps/ai-game-creator-shell/tests/ResourceDependencyOverlay.test.ts b/apps/ai-game-creator-shell/tests/ResourceDependencyOverlay.test.ts
index 6348de9bf..a81ab0602 100644
--- a/apps/ai-game-creator-shell/tests/ResourceDependencyOverlay.test.ts
+++ b/apps/ai-game-creator-shell/tests/ResourceDependencyOverlay.test.ts
@@ -93,6 +93,7 @@ function graphFixture() {
       taskFlowIds: resourceId === 'unrelated' ? [] : [flowId],
     })),
     producerAssignments: [],
+    dependencyDepths: [],
     unresolvedReferenceResourceIds: [],
     cyclicResourceIds: ['unrelated'],
     cyclicTaskIds: [],
@@ -373,6 +374,7 @@ describe('ResourceDependencyOverlay', () => {
         ],
       })),
       producerAssignments: [],
+      dependencyDepths: [],
       unresolvedReferenceResourceIds: [],
       cyclicResourceIds: [],
       cyclicTaskIds: [],
diff --git a/apps/ai-game-creator-shell/tests/appSurface/project-development.suite.ts b/apps/ai-game-creator-shell/tests/appSurface/project-development.suite.ts
index f1b9ec5b5..7e4795549 100644
--- a/apps/ai-game-creator-shell/tests/appSurface/project-development.suite.ts
+++ b/apps/ai-game-creator-shell/tests/appSurface/project-development.suite.ts
@@ -78,11 +78,14 @@ function resourceGraphForInputs(args?: Record<string, unknown>) {
             {
               resourceId: resource.resourceId,
               taskId: resource.producerTaskId,
-              dependencyDepth: 0,
             },
           ]
         : [],
     ),
+    dependencyDepths: resources.map((resource) => ({
+      resourceId: resource.resourceId,
+      dependencyDepth: 0,
+    })),
     unresolvedReferenceResourceIds: [],
     cyclicResourceIds: [],
     cyclicTaskIds: [],
@@ -1103,13 +1106,25 @@ export function registerProjectWorkbenchFoundationTests() {
               {
                 resourceId: 'asset:dependency-spec',
                 taskId: 'art-director',
-                dependencyDepth: 0,
               },
               {
                 resourceId: 'asset:dependency-ui',
                 taskId: 'design-foundation',
+              },
+            ],
+            dependencyDepths: [
+              {
+                resourceId: 'asset:dependency-spec',
+                dependencyDepth: 0,
+              },
+              {
+                resourceId: 'asset:dependency-ui',
                 dependencyDepth: 1,
               },
+              {
+                resourceId: 'asset:unrelated-cycle',
+                dependencyDepth: 0,
+              },
             ],
             unresolvedReferenceResourceIds: [],
             cyclicResourceIds: ['asset:unrelated-cycle'],
diff --git a/apps/ai-game-creator-shell/tests/resourceDependencyGraphModel.test.ts b/apps/ai-game-creator-shell/tests/resourceDependencyGraphModel.test.ts
index 0ed293914..92bc6da08 100644
--- a/apps/ai-game-creator-shell/tests/resourceDependencyGraphModel.test.ts
+++ b/apps/ai-game-creator-shell/tests/resourceDependencyGraphModel.test.ts
@@ -15,6 +15,7 @@ function readModel(
     taskFlows: [],
     connectionIndex: [],
     producerAssignments: [],
+    dependencyDepths: [],
     unresolvedReferenceResourceIds: [],
     cyclicResourceIds: [],
     cyclicTaskIds: [],
@@ -130,23 +131,42 @@ describe('resource dependency graph model', () => {
   it('keeps real producer assignments and audit truncation metadata', () => {
     const graph = normalizeProjectResourceGraph(
       readModel({
-        resourceIds: ['asset:spec', 'asset:ui'],
+        resourceIds: ['asset:spec', 'asset:ui', 'asset:derived'],
         producerAssignments: [
           {
             resourceId: 'asset:spec',
             taskId: 'art-director',
-            dependencyDepth: 0,
           },
           {
             resourceId: 'asset:ui',
             taskId: 'design-foundation',
-            dependencyDepth: 1,
           },
           {
             resourceId: 'asset:deleted',
             taskId: 'task-1',
+          },
+        ],
+        dependencyDepths: [
+          {
+            resourceId: 'asset:spec',
+            dependencyDepth: 0,
+          },
+          {
+            resourceId: 'asset:ui',
+            dependencyDepth: 1,
+          },
+          {
+            resourceId: 'asset:deleted',
             dependencyDepth: 99,
           },
+          {
+            resourceId: 'asset:ui',
+            dependencyDepth: 0,
+          },
+          {
+            resourceId: 'asset:derived',
+            dependencyDepth: 2,
+          },
         ],
         producerMappingTruncated: true,
       }),
@@ -162,6 +182,7 @@ describe('resource dependency graph model', () => {
       new Map([
         ['asset:spec', 0],
         ['asset:ui', 1],
+        ['asset:derived', 2],
       ]),
     );
     expect(graph.producerMappingTruncated).toBe(true);
diff --git a/docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md b/docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md
index 3886475cf..bb8020892 100644
--- a/docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md
+++ b/docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md
@@ -260,6 +260,7 @@ type UpdateProjectResourceCanvasLayoutResult =
 
 #### 5.2.6 资源依赖关系图层
 
+- 阶段五实现状态（2026-08-03）：dependency 自动排列同时消费任务 DAG 与精确资源引用。Rust 把可信 producer 的任务深度作为资源深度下限，再对 `asset-reference` 图做迭代式 SCC 压缩与确定性层级传播；被引用资源位于引用资源之前，同一引用环共享稳定深度，环后资源继续递增，没有引用关系的资源保持默认不重叠位置。布局深度通过独立 `dependencyDepths` 返回，不能把 producer assignment 冒充全部资源的布局结果。
 - 图层只在 dependency 模式挂载；type 模式不得渲染 SVG、连线或 marker。切换 mode、切换项目或卸载工作台时必须销毁旧图层，并清理尺寸观察和窗口事件监听。
 - 输入固定为当前资源投影的全部卡片身份 / 坐标与 Tauri Rust 返回的 `ProjectResourceGraph` 只读 DTO；Rust 负责资源过滤、去重、迭代式环检测、SCC 压缩后的确定性依赖深度、任务流聚合和一跳连接索引，前端只负责 DTO 防御归一化、浏览器几何与原生 SVG path / marker。SVG 叠加在资源卡底层并设置 `pointer-events: none`，不得引入 D3、React Flow 等图表库，也不得阻断卡片点击。
 - `asset-reference` 表示精确资源引用，使用橙色实线与连续贝塞尔曲线。`GameCreationAppAssetManifestEntry.source.referenceResourceIds` 中的外部资源 ID 必须先唯一匹配另一项资产的 `source.resourceId`，再映射为当前资源卡 ID；缺失、重复或已删除的目标均不得渲染幽灵连线。
@@ -271,6 +272,7 @@ type UpdateProjectResourceCanvasLayoutResult =
 - 选中资源后，高亮其直接上游、直接下游卡片和关联边，弱化其余边；不做跨多层递归高亮。选中 ID 已失效时按未选中处理。
 - 资源卡 Pointer Move 不改变基础 positions 或 SVG 几何。连线只随布局读取、资源自动协调、搜索、选择、项目切换或 section origin 变化而更新。
 - `ResizeObserver` 在单个图层生命周期只允许构造一次。dependency section 额外提供至少 `64px` 右侧视觉 gutter，确保最右侧自环和箭头可完整滚动显示，但不得修改卡片坐标或布局 sidecar。
+- 阶段五不改变手动位置边界：已有 `manuallyPlaced=true` 坐标原样保留，资源引用新增或变化只允许重新派生 `manuallyPlaced=false` 的自动坐标；任务流继续按任务对聚合，禁止为了计算深度或绘线生成资源笛卡尔积。
 
 ### 5.3 资源类型与替换兼容性（P1）
 
diff --git a/docs/project-memory/shared-memory/decision-log.md b/docs/project-memory/shared-memory/decision-log.md
index 89510f57e..10b6e04ff 100644
--- a/docs/project-memory/shared-memory/decision-log.md
+++ b/docs/project-memory/shared-memory/decision-log.md
@@ -1,5 +1,13 @@
 # 决策记录
 
+## 2026-08-03 资源依赖阶段五以引用 SCC 深度驱动自动排列
+
+- 背景：资源关系图已经能展示精确引用与聚合任务流，但 dependency 自动布局只消费可信 producer 对应的任务 DAG 深度；同一任务生成的派生资源、没有 producer 审计的 manifest 资源和资源引用环均无法稳定体现“被引用资源在前、引用资源在后”的顺序。
+- 决策：`read_local_project_resource_graph` 把 producer assignment 与布局深度拆成两个只读字段。Rust 先压缩完整任务图并把可信 producer 的任务深度作为资源下限，再对精确资源引用图做迭代式 SCC 压缩和确定性最长层级传播；同一引用环共享深度，环后资源递增一层，没有引用关系的资源保持默认深度 `0`。前端只校验并消费 `dependencyDepths`，沿用现有自动位置协调和 SVG 几何，不自行推导关系。
+- 边界：不修改 manifest、layout sidecar、External Editor API、api-server 或 SpacetimeDB；不恢复资源卡拖动。已有 `manuallyPlaced=true` 坐标继续保留，只有可派生自动坐标会按新深度重算；任务流继续按任务对聚合，不展开资源笛卡尔积。
+- 验证方式：Rust 定向测试覆盖无 producer 的精确引用、任务深度下限、资源引用环 SCC、环后资源与 4096 任务链；前端 DTO、布局 Hook、纯布局和 SVG 测试覆盖独立深度字段、自动重排与手动坐标保留，并运行 shell typecheck、编码检查和 `git diff --check`。
+- 关联文档：`docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md`、`docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md`。
+
 ## 2026-08-03 资源聚焦阶段四采用只读受控文档与媒体链路
 
 - 背景：阶段一至三已经完成资源卡禁拖、固定四类资源投影与中央聚焦容器，但只有 PNG / JPEG / WEBP 和合法 Agent 文本回执具备真实主体预览；本地文档、SVG / 视频与音频仍只有路径和元数据。飞书需求同时把“编辑并生成新资源”写为条件项，而当前仓库尚未具备从画板返回后的血缘登记与自动选中闭环。
diff --git a/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md b/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md
index 745ee19a0..cda56e3c0 100644
--- a/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md
+++ b/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md
@@ -397,7 +397,7 @@ game-project/
 
 2026-07-31 起，项目工作台使用“Tauri Rust 只读拓扑 + 前端原生 SVG 几何”的资源依赖图层；不修改 layout sidecar、既有布局模型、api-server 或 SpacetimeDB：
 
-- `read_local_project_resource_graph` 读取当前 manifest、前端资源卡身份列表和最多 `32 MiB` 的安全 Agent DB 尾部，通过 Rust 构建稳定 read model；读取使用既有 Agent DB 普通文件 / 链接 / 追加锁边界，不新增数据库或 sidecar。返回资源 ID、引用边、聚合任务流、producer assignment、循环集合、unresolved 外部 ID、局部连接索引和 `producerMappingTruncated`。
+- `read_local_project_resource_graph` 读取当前 manifest、前端资源卡身份列表和最多 `32 MiB` 的安全 Agent DB 尾部，通过 Rust 构建稳定 read model；读取使用既有 Agent DB 普通文件 / 链接 / 追加锁边界，不新增数据库或 sidecar。返回资源 ID、引用边、聚合任务流、producer assignment、独立 `dependencyDepths`、循环集合、unresolved 外部 ID、局部连接索引和 `producerMappingTruncated`。
 - 精确引用把 manifest 资产 `source.referenceResourceIds` 唯一匹配到另一资产的 `source.resourceId`，再转换为本次资源卡 ID；无匹配、多匹配、重复卡片或已删除资源只记录为 unresolved / 忽略，不生成边。引用边按 `sourceResourceId + targetResourceId` 稳定去重；前端 `resourceDependencyGraphModel.ts` 再做一次 DTO 端点防御过滤，避免异步切项目时出现幽灵线。
 - task flow 只读取存在于当前 manifest 的任务依赖。画布资产 producer 仅接受 `agent.runtime.canvas.asset_generate` 中经 manifest 校验的 `assetId -> agentId`；External Editor 返回并保存在 `source.taskId` 的 `task-1` 等身份属于平台生成任务，禁止复用为 manifest task。多个有效 Agent 对同一资产形成冲突或证据缺失时，不生成该资产对应 task flow。任务产物 / Agent 回执继续使用资源投影中已有的 manifest task 身份。
 - 资源按可信 producer 分组，每个 `sourceTaskId -> targetTaskId` 只生成一个聚合 flow；SVG 侧绘制 source 分支、唯一主线和 target 分支，路径数量为 `O(S+T)`，禁止资源笛卡尔积。局部连接索引保存 resource 关联的 reference edge ID / task flow ID，不预先展开 `S×T` 邻接矩阵。
@@ -408,7 +408,7 @@ game-project/
 - 基础 positions 保持稳定；卡片 Pointer Move 不进入 SVG preview，只有搜索、选择、项目切换、真实 positions 或 section origin 变化才重新协调图层。SVG 几何从不持久化。
 - Rust、前端 DTO/SVG 和工作台 AppSurface 回归覆盖生产 `task-1` 数据形状、真实 producer、证据缺失、精确引用、去重、无效 ID、完整任务环、4096 链式拓扑、聚合复杂度、搜索过滤、选择高亮、稳定 Observer、type 模式卸载与项目切换销毁。局部拖动更新与真实 Chromium 拖动性能目标暂缓。
 
-2026-08-03 评审加固：Rust read model 在现有 producer assignment 上同时返回经完整任务图 SCC 压缩计算的确定性 `dependencyDepth`，前端不再递归推导正式依赖层级。dependency 模式以 scope 化 `idle / loading / ready / failed` 状态阻断布局 Hook；图终态前不创建 fallback、不读取或写入 sidecar，图失败只以空图初始化一次。读取已有 dependency 布局时保留全部 `manuallyPlaced=true` 坐标，把 `manuallyPlaced=false` 作为可派生自动位置按最终深度重新协调；结果未变化时不写入。
+2026-08-03 阶段五加固：Rust read model 把 producer assignment 与布局深度分离。完整任务图先经 SCC 压缩形成可信 producer 的任务深度下限，精确资源引用图再经迭代式 SCC 压缩和确定性最长层级传播形成所有可见资源的 `dependencyDepths`；因此同一任务的派生资源、缺少 producer 审计的 manifest 资源和引用环都能稳定满足“被引用资源在前、引用资源在后”，没有引用关系的资源保持深度 `0`。前端不递归推导正式依赖层级。dependency 模式以 scope 化 `idle / loading / ready / failed` 状态阻断布局 Hook；图终态前不创建 fallback、不读取或写入 sidecar，图失败只以空图初始化一次。读取已有 dependency 布局时保留全部 `manuallyPlaced=true` 坐标，把 `manuallyPlaced=false` 作为可派生自动位置按最终深度重新协调；结果未变化时不写入。任务流仍按任务对聚合，不为布局计算或 SVG 绘制生成资源笛卡尔积。
 
 历史命令式 drag preview 句柄与局部连接索引可以保留，但项目工作台不再向资源卡传入该入口。拖动热路径、4096 张真实卡片拖动重渲染和 Chromium p95 门槛统一暂缓；当前回归只要求 Pointer Move 不改变卡片坐标、SVG path 或布局 revision。`ResizeObserver` 仍保持单图层单实例，任何实时 DOM 几何都不得通过 Tauri IPC 往返 Rust。
 
-- 
2.52.0


From fef53b634eeb77cce9dbe984f3622d5dab537937 Mon Sep 17 00:00:00 2001
From: menghao <mh18530625731@163.com>
Date: Mon, 3 Aug 2026 19:04:01 +0800
Subject: [PATCH 14/27] =?UTF-8?q?=E5=AE=8C=E6=88=90=E6=AD=A3=E5=BC=8F?=
 =?UTF-8?q?=E9=A1=B9=E7=9B=AE=E7=89=88=E6=9C=AC=E9=98=B6=E6=AE=B5=E5=85=AD?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

扩展 manifest 正式迭代版本合同并强制历史记录追加不可变
接入版本卡、父子关系与绑定资源高亮
补齐共享契约、Tauri 存储与工作台回归测试
同步工作台 PRD、技术方案与项目记忆
---
 .../src-tauri/src/main.rs                     |   5 +-
 .../src-tauri/src/project/manifest.rs         |  21 +-
 .../src/project/manifest/recovery_tests.rs    |  56 ++++
 apps/ai-game-creator-shell/src/styles.css     |   3 +-
 .../src/view/project-development/index.tsx    | 113 ++++++--
 .../resourceProjectionModel.ts                |  30 ++-
 .../appSurface/project-development.suite.ts   |  92 +++++++
 .../projectResourceProjectionModel.test.ts    |  85 ++++--
 ...AI游戏创作】项目开发工作台PRD-2026-07-20.md |  33 ++-
 .../shared-memory/decision-log.md             |   8 +
 ...�案】AI游戏创作智能体App实施计划-2026-06-24.md |   6 +-
 .../src/contracts/gameCreationApp.test.ts     |  20 ++
 .../shared/src/contracts/gameCreationApp.ts   |  20 ++
 .../shared-contracts/src/game_creation_app.rs | 241 +++++++++++++++++-
 14 files changed, 664 insertions(+), 69 deletions(-)

diff --git a/apps/ai-game-creator-shell/src-tauri/src/main.rs b/apps/ai-game-creator-shell/src-tauri/src/main.rs
index 422db1039..1e1357c73 100644
--- a/apps/ai-game-creator-shell/src-tauri/src/main.rs
+++ b/apps/ai-game-creator-shell/src-tauri/src/main.rs
@@ -23,8 +23,9 @@ use reqwest::header;
 use serde::{Deserialize, Serialize};
 use shared_contracts::game_creation_app::{
     new_game_creation_app_manifest, new_game_creation_app_seed_tasks,
-    GameCreationAgentArtifactTrace, GameCreationAgentCapabilityDescriptor,
-    GameCreationAgentPassPlanTrace, GameCreationAgentRepairRouteTrace, GameCreationAgentRunStep,
+    validate_game_iteration_versions, GameCreationAgentArtifactTrace,
+    GameCreationAgentCapabilityDescriptor, GameCreationAgentPassPlanTrace,
+    GameCreationAgentRepairRouteTrace, GameCreationAgentRunStep,
     GameCreationAgentRunTaskGraphTrace, GameCreationAgentRunTrace, GameCreationAgentToolCallTrace,
     GameCreationAppAgentGroup, GameCreationAppAssetManifestEntry, GameCreationAppAssetSource,
     GameCreationAppAssetSourceKind, GameCreationAppCommandRunState,
diff --git a/apps/ai-game-creator-shell/src-tauri/src/project/manifest.rs b/apps/ai-game-creator-shell/src-tauri/src/project/manifest.rs
index 91fb6a9ff..5fd595ec1 100644
--- a/apps/ai-game-creator-shell/src-tauri/src/project/manifest.rs
+++ b/apps/ai-game-creator-shell/src-tauri/src/project/manifest.rs
@@ -631,8 +631,11 @@ pub(crate) fn read_manifest(path: &Path) -> Result<GameCreationAppManifest, Stri
         .open(source_path)
         .and_then(|mut file| file.read_to_string(&mut payload))
         .map_err(|error| format!("读取 {label} 失败：{}: {error}", source_path.display()))?;
-    serde_json::from_str(&payload)
-        .map_err(|error| format!("解析 {label} 失败：{}: {error}", source_path.display()))
+    let manifest: GameCreationAppManifest = serde_json::from_str(&payload)
+        .map_err(|error| format!("解析 {label} 失败：{}: {error}", source_path.display()))?;
+    validate_game_iteration_versions(&manifest.versions)
+        .map_err(|error| format!("校验 {label} 项目版本失败：{error}"))?;
+    Ok(manifest)
 }
 
 fn install_manifest_temp_with<F>(
@@ -709,6 +712,20 @@ pub(crate) fn write_manifest(
     path: &Path,
     manifest: &GameCreationAppManifest,
 ) -> Result<(), String> {
+    validate_game_iteration_versions(&manifest.versions)
+        .map_err(|error| format!("校验 manifest 项目版本失败：{error}"))?;
+    if manifest_storage_exists(path)? {
+        let existing = read_manifest(path)?;
+        if existing.versions.len() > manifest.versions.len()
+            || existing
+                .versions
+                .iter()
+                .zip(&manifest.versions)
+                .any(|(existing, candidate)| existing != candidate)
+        {
+            return Err("项目版本记录写入后不可修改、删除或重排".to_string());
+        }
+    }
     let payload = serde_json::to_string_pretty(manifest)
         .map_err(|error| format!("序列化 manifest 失败：{error}"))?;
     if let Some(parent) = path.parent() {
diff --git a/apps/ai-game-creator-shell/src-tauri/src/project/manifest/recovery_tests.rs b/apps/ai-game-creator-shell/src-tauri/src/project/manifest/recovery_tests.rs
index c82b0144d..1388bfe92 100644
--- a/apps/ai-game-creator-shell/src-tauri/src/project/manifest/recovery_tests.rs
+++ b/apps/ai-game-creator-shell/src-tauri/src/project/manifest/recovery_tests.rs
@@ -1,4 +1,7 @@
 use super::*;
+use shared_contracts::game_creation_app::{
+    GameIterationVersion, GameIterationVersionCreatedReason, GameIterationVersionResourceBinding,
+};
 
 fn unique_manifest_test_root(test_name: &str) -> PathBuf {
     std::env::temp_dir().join(format!(
@@ -40,6 +43,59 @@ fn manifest_read_and_project_write_recover_previous_file() {
     fs::remove_dir_all(root).ok();
 }
 
+fn version_fixture(
+    version_id: &str,
+    parent_version_id: Option<&str>,
+    project_revision: u64,
+    created_reason: GameIterationVersionCreatedReason,
+) -> GameIterationVersion {
+    GameIterationVersion {
+        version_id: version_id.to_string(),
+        parent_version_id: parent_version_id.map(str::to_string),
+        project_revision,
+        resource_bindings: vec![GameIterationVersionResourceBinding {
+            slot_id: "player".to_string(),
+            resource_id: "asset-player".to_string(),
+        }],
+        created_reason,
+        created_at: project_revision,
+    }
+}
+
+#[test]
+fn manifest_versions_are_append_only_at_the_storage_boundary() {
+    let root = unique_manifest_test_root("versions-append-only");
+    let manifest_path = root.join(".agent/manifest.json");
+    let mut manifest = new_game_creation_app_manifest("project-versioned", "版本项目");
+    manifest.versions.push(version_fixture(
+        "version-root",
+        None,
+        1,
+        GameIterationVersionCreatedReason::Initial,
+    ));
+    write_manifest(&manifest_path, &manifest).expect("write initial version");
+
+    manifest.versions.push(version_fixture(
+        "version-child",
+        Some("version-root"),
+        2,
+        GameIterationVersionCreatedReason::AgentRevision,
+    ));
+    write_manifest(&manifest_path, &manifest).expect("append child version");
+
+    let stable_payload = fs::read(&manifest_path).expect("read stable manifest bytes");
+    manifest.versions[0].resource_bindings[0].resource_id = "asset-mutated".to_string();
+    let error =
+        write_manifest(&manifest_path, &manifest).expect_err("reject mutation of existing version");
+    assert!(error.contains("不可修改、删除或重排"), "{error}");
+    assert_eq!(
+        fs::read(&manifest_path).expect("read untouched manifest bytes"),
+        stable_payload
+    );
+
+    fs::remove_dir_all(root).ok();
+}
+
 #[test]
 fn manifest_install_uses_previous_when_direct_replace_fails() {
     let root = unique_manifest_test_root("replace-fallback");
diff --git a/apps/ai-game-creator-shell/src/styles.css b/apps/ai-game-creator-shell/src/styles.css
index 6131b64a1..78d72898d 100644
--- a/apps/ai-game-creator-shell/src/styles.css
+++ b/apps/ai-game-creator-shell/src/styles.css
@@ -4058,7 +4058,8 @@ iframe.preview-frame {
 
 .game-resource-card.is-relation-upstream,
 .game-resource-card.is-relation-downstream,
-.game-resource-card.is-relation-both {
+.game-resource-card.is-relation-both,
+.game-resource-card.is-relation-version-binding {
   border-color: #d87342;
   box-shadow:
     0 8px 22px rgb(195 105 62 / 18%),
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 2e8cc4c12..75c52a682 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
@@ -135,7 +135,6 @@ export type ProjectAgentRuntimeSummary = {
 
 const emptyProjectAgentRuntimeSummaries: ProjectAgentRuntimeSummary[] = [];
 const emptyProjectAgentResults: ProjectAgentResultSummary[] = [];
-const emptyProjectVersions: ProjectVersionResourceSummary[] = [];
 const RESOURCE_DEPENDENCY_VISUAL_GUTTER = 64;
 
 type AgentSummary = ProjectAgentRuntimeSummary;
@@ -150,7 +149,6 @@ export type ProjectDevelopmentViewProps = {
   preview?: GameCreationAppPreviewState | null;
   agentRuntimeSummaries?: ProjectAgentRuntimeSummary[];
   agentResults?: ProjectAgentResultSummary[];
-  projectVersions?: ProjectVersionResourceSummary[];
   supervisor: ReactNode;
   onHomeOpen: () => void;
   onProjectsOpen: () => void;
@@ -255,6 +253,13 @@ function formatMediaDuration(duration: number | null) {
   return `${minutes}:${seconds.toString().padStart(2, '0')}`;
 }
 
+function formatVersionCreatedAt(createdAt: number) {
+  const value = new Date(createdAt);
+  return Number.isFinite(value.getTime())
+    ? value.toLocaleString('zh-CN')
+    : String(createdAt);
+}
+
 function SafeProjectMarkdown({ content }: { content: string }) {
   return (
     <ReactMarkdown
@@ -358,7 +363,7 @@ const ResourceCard = memo(function ResourceCard({
 }: {
   resource: ProjectResource;
   selected: boolean;
-  relationState: 'upstream' | 'downstream' | 'both' | null;
+  relationState: 'upstream' | 'downstream' | 'both' | 'version-binding' | null;
   x: number;
   y: number;
   onSelect: (resourceId: string) => void;
@@ -386,7 +391,13 @@ const ResourceCard = memo(function ResourceCard({
       </span>
       <strong>{resource.label}</strong>
       <small>{resource.sourceLabel}</small>
-      <small>{resource.path}</small>
+      <small>
+        {resource.version
+          ? resource.version.childVersionIds.length > 0
+            ? `${resource.version.childVersionIds.length} 个直接子版本`
+            : '暂无直接子版本'
+          : resource.path}
+      </small>
     </button>
   );
 });
@@ -399,7 +410,6 @@ export default function ProjectDevelopmentView({
   preview: previewOverride,
   agentRuntimeSummaries = emptyProjectAgentRuntimeSummaries,
   agentResults = emptyProjectAgentResults,
-  projectVersions = emptyProjectVersions,
   supervisor,
 }: ProjectDevelopmentViewProps) {
   const [mode, setMode] = useState<WorkbenchMode>('resources');
@@ -443,14 +453,8 @@ export default function ProjectDevelopmentView({
       (task) => task.id === 'code-prototype' && task.status === 'completed',
     );
   const projectedResources = useMemo(
-    () =>
-      projectResourcesFromReadModels(
-        manifest,
-        attachments,
-        agentResults,
-        projectVersions,
-      ),
-    [agentResults, attachments, manifest, projectVersions],
+    () => projectResourcesFromReadModels(manifest, attachments, agentResults),
+    [agentResults, attachments, manifest],
   );
   const resourceGraphInputs = useMemo<ProjectResourceGraphNodeInput[]>(
     () =>
@@ -603,6 +607,26 @@ export default function ProjectDevelopmentView({
     () => projectResourceGraphNeighbors(resourceGraph, selectedResourceId),
     [resourceGraph, selectedResourceId],
   );
+  const selectedVersionBindingResourceIds = useMemo(() => {
+    const selectedVersion = resources.find(
+      (resource) => resource.id === selectedResourceId,
+    )?.version;
+    if (!selectedVersion) {
+      return new Set<string>();
+    }
+    const boundManifestAssetIds = new Set(
+      selectedVersion.resourceBindings.map((binding) => binding.resourceId),
+    );
+    return new Set(
+      resources
+        .filter(
+          (resource) =>
+            resource.manifestAssetId !== null &&
+            boundManifestAssetIds.has(resource.manifestAssetId),
+        )
+        .map((resource) => resource.id),
+    );
+  }, [resources, selectedResourceId]);
   const normalizedSearch = searchText.trim().toLowerCase();
   const visibleResources = useMemo(
     () =>
@@ -1208,6 +1232,10 @@ export default function ProjectDevelopmentView({
                   ) : null}
                   {focusedResource.version ? (
                     <>
+                      <div>
+                        <dt>版本 ID</dt>
+                        <dd>{focusedResource.version.versionId}</dd>
+                      </div>
                       <div>
                         <dt>项目修订</dt>
                         <dd>{focusedResource.version.projectRevision}</dd>
@@ -1219,6 +1247,47 @@ export default function ProjectDevelopmentView({
                             '首个版本'}
                         </dd>
                       </div>
+                      <div>
+                        <dt>直接子版本</dt>
+                        <dd>
+                          {focusedResource.version.childVersionIds.length > 0
+                            ? focusedResource.version.childVersionIds.join('、')
+                            : '暂无'}
+                        </dd>
+                      </div>
+                      <div>
+                        <dt>创建原因</dt>
+                        <dd>
+                          {
+                            {
+                              initial: '初始版本',
+                              'resource-replacement': '资源替换',
+                              'agent-revision': 'Agent 修订',
+                            }[focusedResource.version.createdReason]
+                          }
+                        </dd>
+                      </div>
+                      <div>
+                        <dt>创建时间</dt>
+                        <dd>
+                          {formatVersionCreatedAt(
+                            focusedResource.version.createdAt,
+                          )}
+                        </dd>
+                      </div>
+                      <div>
+                        <dt>资源绑定</dt>
+                        <dd>
+                          {focusedResource.version.resourceBindings.length > 0
+                            ? focusedResource.version.resourceBindings
+                                .map(
+                                  (binding) =>
+                                    `${binding.slotId} → ${binding.resourceId}`,
+                                )
+                                .join('；')
+                            : '暂无'}
+                        </dd>
+                      </div>
                     </>
                   ) : null}
                 </dl>
@@ -1327,13 +1396,17 @@ export default function ProjectDevelopmentView({
                                   resource.id,
                                 );
                               const relationState =
-                                upstream && downstream
-                                  ? 'both'
-                                  : upstream
-                                    ? 'upstream'
-                                    : downstream
-                                      ? 'downstream'
-                                      : null;
+                                selectedVersionBindingResourceIds.has(
+                                  resource.id,
+                                )
+                                  ? 'version-binding'
+                                  : upstream && downstream
+                                    ? 'both'
+                                    : upstream
+                                      ? 'upstream'
+                                      : downstream
+                                        ? 'downstream'
+                                        : null;
                               return (
                                 <ResourceCard
                                   key={resource.id}
diff --git a/apps/ai-game-creator-shell/src/view/project-development/resourceProjectionModel.ts b/apps/ai-game-creator-shell/src/view/project-development/resourceProjectionModel.ts
index f084a475d..4f2e58f74 100644
--- a/apps/ai-game-creator-shell/src/view/project-development/resourceProjectionModel.ts
+++ b/apps/ai-game-creator-shell/src/view/project-development/resourceProjectionModel.ts
@@ -1,4 +1,5 @@
 import type {
+  GameIterationVersion,
   GameCreationAppManifest,
   ProjectResourceCanvasSection,
 } from '../../../../../packages/shared/src/contracts/gameCreationApp';
@@ -22,12 +23,9 @@ export type ProjectAgentResultSummary = {
   updatedAt: number;
 };
 
-export type ProjectVersionResourceSummary = {
-  versionId: string;
+export type ProjectVersionResourceSummary = GameIterationVersion & {
   label: string;
-  projectRevision: number;
-  parentVersionId: string | null;
-  createdAt: number;
+  childVersionIds: string[];
 };
 
 export type ProjectResource = {
@@ -112,7 +110,6 @@ export function projectResourcesFromReadModels(
   manifest: GameCreationAppManifest,
   attachments: ProjectAttachmentResult[],
   agentResults: ProjectAgentResultSummary[],
-  projectVersions: ProjectVersionResourceSummary[] = [],
 ) {
   const taskById = new Map(manifest.tasks.map((task) => [task.id, task]));
   const resources: ProjectResource[] = [];
@@ -233,7 +230,22 @@ export function projectResourcesFromReadModels(
     });
   }
 
-  for (const version of projectVersions) {
+  const childVersionIdsByParent = new Map<string, string[]>();
+  for (const version of manifest.versions ?? []) {
+    if (!version.parentVersionId) {
+      continue;
+    }
+    const children = childVersionIdsByParent.get(version.parentVersionId) ?? [];
+    children.push(version.versionId);
+    childVersionIdsByParent.set(version.parentVersionId, children);
+  }
+  for (const [index, manifestVersion] of (manifest.versions ?? []).entries()) {
+    const version: ProjectVersionResourceSummary = {
+      ...manifestVersion,
+      label: `版本 ${index + 1}`,
+      childVersionIds:
+        childVersionIdsByParent.get(manifestVersion.versionId) ?? [],
+    };
     resources.push({
       id: `version:${version.versionId}`,
       category: 'version',
@@ -241,7 +253,9 @@ export function projectResourcesFromReadModels(
       label: version.label,
       path: `项目版本 · ${version.versionId}`,
       mediaType: '正式项目版本',
-      sourceLabel: `项目修订 ${version.projectRevision}`,
+      sourceLabel: version.parentVersionId
+        ? `项目修订 ${version.projectRevision} · 父版本 ${version.parentVersionId}`
+        : `项目修订 ${version.projectRevision} · 初始版本`,
       taskTitle: null,
       manifestAssetId: null,
       producerTaskId: null,
diff --git a/apps/ai-game-creator-shell/tests/appSurface/project-development.suite.ts b/apps/ai-game-creator-shell/tests/appSurface/project-development.suite.ts
index 7e4795549..0fb7a155f 100644
--- a/apps/ai-game-creator-shell/tests/appSurface/project-development.suite.ts
+++ b/apps/ai-game-creator-shell/tests/appSurface/project-development.suite.ts
@@ -679,6 +679,98 @@ export function registerProjectWorkbenchFoundationTests() {
     expect(screen.getByRole('article', { name: /发布 Agent/ })).not.toBeNull();
   });
 
+  it('renders immutable manifest versions, their parent graph, and bound asset highlights', async () => {
+    const manifest = createGameCreationAppManifest(
+      'workbench-versions',
+      '版本工作台测试',
+    );
+    manifest.assets = [
+      {
+        id: 'asset-player',
+        kind: 'character',
+        mediaType: 'image/png',
+        localPath: 'assets/player.png',
+        source: { kind: 'generated' },
+      },
+    ];
+    manifest.versions = [
+      {
+        versionId: 'version-root',
+        parentVersionId: null,
+        projectRevision: 3,
+        resourceBindings: [{ slotId: 'player', resourceId: 'asset-player' }],
+        createdReason: 'initial',
+        createdAt: 100,
+      },
+      {
+        versionId: 'version-child',
+        parentVersionId: 'version-root',
+        projectRevision: 4,
+        resourceBindings: [
+          { slotId: 'player', resourceId: 'asset-player' },
+          { slotId: 'historical', resourceId: 'asset-removed' },
+        ],
+        createdReason: 'agent-revision',
+        createdAt: 200,
+      },
+    ];
+
+    render(
+      React.createElement(ProjectDevelopmentView, {
+        projectName: manifest.name,
+        projectPath: '/tmp/workbench-versions',
+        manifest,
+        attachments: [],
+        recentRunStatus: null,
+        recentRunStopReason: null,
+        supervisor: React.createElement('div', null, '项目总控'),
+        onHomeOpen: vi.fn(),
+        onProjectsOpen: vi.fn(),
+      }),
+    );
+
+    fireEvent.click(screen.getByRole('button', { name: '按类型' }));
+    const resourceCards = screen.getAllByTitle('打开资源详情');
+    const rootVersionCard = resourceCards.find((card) =>
+      card.textContent?.includes('版本 1'),
+    );
+    const childVersionCard = resourceCards.find((card) =>
+      card.textContent?.includes('版本 2'),
+    );
+    expect(rootVersionCard?.textContent).toContain('1 个直接子版本');
+    expect(childVersionCard?.textContent).toContain('父版本 version-root');
+
+    fireEvent.click(childVersionCard!);
+    const versionFocus = screen.getByRole('region', { name: '版本 2' });
+    expect(within(versionFocus).getByText('version-child')).not.toBeNull();
+    expect(within(versionFocus).getByText('version-root')).not.toBeNull();
+    expect(within(versionFocus).getByText('Agent 修订')).not.toBeNull();
+    expect(
+      within(versionFocus).getByText(
+        'player → asset-player；historical → asset-removed',
+      ),
+    ).not.toBeNull();
+    expect(screen.queryByText('asset:asset-removed')).toBeNull();
+
+    fireEvent.click(screen.getByRole('button', { name: '收起资源' }));
+    const playerCard = screen
+      .getAllByTitle('打开资源详情')
+      .find((card) => card.textContent?.includes('player.png'));
+    expect(playerCard?.classList.contains('is-relation-version-binding')).toBe(
+      true,
+    );
+
+    fireEvent.click(screen.getByRole('button', { name: '按依赖' }));
+    await waitFor(() => {
+      const dependencyPlayerCard = screen
+        .getAllByTitle('打开资源详情')
+        .find((card) => card.textContent?.includes('player.png'));
+      expect(
+        dependencyPlayerCard?.classList.contains('is-relation-version-binding'),
+      ).toBe(true);
+    });
+  });
+
   it('opens text receipts in the central focus state and restores the resource list context', () => {
     const manifest = createGameCreationAppManifest(
       'workbench-resource-details',
diff --git a/apps/ai-game-creator-shell/tests/projectResourceProjectionModel.test.ts b/apps/ai-game-creator-shell/tests/projectResourceProjectionModel.test.ts
index 829a430cb..7f98d4175 100644
--- a/apps/ai-game-creator-shell/tests/projectResourceProjectionModel.test.ts
+++ b/apps/ai-game-creator-shell/tests/projectResourceProjectionModel.test.ts
@@ -49,6 +49,18 @@ describe('项目资源投影', () => {
         source: { kind: 'generated' },
       },
     ];
+    manifest.versions = [
+      {
+        versionId: 'version-1',
+        parentVersionId: null,
+        projectRevision: 7,
+        resourceBindings: [
+          { slotId: 'background-music', resourceId: 'registered-bgm' },
+        ],
+        createdReason: 'initial',
+        createdAt: 1,
+      },
+    ];
 
     const resources = projectResourcesFromReadModels(
       manifest,
@@ -82,15 +94,6 @@ describe('项目资源投影', () => {
           updatedAt: 1,
         },
       ],
-      [
-        {
-          versionId: 'version-1',
-          label: '首个可运行版本',
-          projectRevision: 7,
-          parentVersionId: null,
-          createdAt: 1,
-        },
-      ],
     );
 
     expect(resources.map(({ id, category }) => ({ id, category }))).toEqual(
@@ -134,6 +137,16 @@ describe('项目资源投影', () => {
       'stable-resource-id',
       '稳定资源身份测试',
     );
+    manifest.versions = [
+      {
+        versionId: 'stable-version',
+        parentVersionId: null,
+        projectRevision: 1,
+        resourceBindings: [],
+        createdReason: 'initial',
+        createdAt: 1,
+      },
+    ];
     const first = projectResourcesFromReadModels(
       manifest,
       [],
@@ -147,15 +160,6 @@ describe('项目资源投影', () => {
           updatedAt: 1,
         },
       ],
-      [
-        {
-          versionId: 'stable-version',
-          label: '旧版本名',
-          projectRevision: 1,
-          parentVersionId: null,
-          createdAt: 1,
-        },
-      ],
     );
     const second = projectResourcesFromReadModels(
       manifest,
@@ -170,17 +174,44 @@ describe('项目资源投影', () => {
           updatedAt: 2,
         },
       ],
-      [
-        {
-          versionId: 'stable-version',
-          label: '新版本名',
-          projectRevision: 1,
-          parentVersionId: null,
-          createdAt: 1,
-        },
-      ],
     );
 
     expect(first.map(({ id }) => id)).toEqual(second.map(({ id }) => id));
   });
+
+  it('只从 manifest 投影版本并保留直接父子关系', () => {
+    const manifest = createGameCreationAppManifest(
+      'version-projection',
+      '版本投影测试',
+    );
+    manifest.versions = [
+      {
+        versionId: 'version-root',
+        parentVersionId: null,
+        projectRevision: 2,
+        resourceBindings: [],
+        createdReason: 'initial',
+        createdAt: 100,
+      },
+      {
+        versionId: 'version-child',
+        parentVersionId: 'version-root',
+        projectRevision: 3,
+        resourceBindings: [],
+        createdReason: 'agent-revision',
+        createdAt: 200,
+      },
+    ];
+
+    const versions = projectResourcesFromReadModels(manifest, [], []).filter(
+      (resource) => resource.category === 'version',
+    );
+
+    expect(versions.map((version) => version.label)).toEqual([
+      '版本 1',
+      '版本 2',
+    ]);
+    expect(versions[0]?.version?.childVersionIds).toEqual(['version-child']);
+    expect(versions[1]?.version?.parentVersionId).toBe('version-root');
+  });
 });
diff --git a/docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md b/docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md
index bb8020892..2786b73e8 100644
--- a/docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md
+++ b/docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md
@@ -1,6 +1,6 @@
 # AI 游戏创作项目开发工作台 PRD
 
-更新时间：`2026-08-03`
+更新时间：`2026-08-03`（阶段六）
 
 ## 1. 产品定位
 
@@ -126,11 +126,11 @@ idle -> focused(document|art|audio|version) -> idle
 - 文档：合法 Agent 文本回执直接使用对话投影内容；项目文件只允许读取当前 manifest 已登记资产或已完成任务产物中的 Markdown、文本、JSON、YAML、TOML，必须经过 `file.read` auto 权限、相对路径、项目边界、普通文件、符号链接 / 硬链接、读取漂移、2 MiB、UTF-8 与扩展名白名单校验。正文使用不执行 HTML、不加载远程图片、不产生可点击外链的安全 Markdown 渲染，并在中央画布内独立滚动；读取失败显示错误空态。
 - 美术：PNG、JPEG、WEBP 继续使用图片魔数与像素边界预览；GIF、SVG、AVIF、BMP、MP4、WebM、MOV 通过新增受控媒体读取链路按文件签名校验后在中央画布放大聚焦。SVG 额外拒绝脚本、事件处理器、外部资源引用和实体声明；视频使用内置播放控件。读取失败显示错误空态。
 - 音频：只读取 manifest 已登记音频或已成功导入且登记到 manifest 的附件，按文件签名接受 MP3、WAV、OGG / Opus、M4A、AAC、FLAC；聚焦态展示实际格式、浏览器解码后的时长以及带播放进度和暂停能力的内置播放器。音频任务声明中的未登记路径继续不得读取或播放。
-- 版本：只展示正式版本 read model 的身份与修订元数据；版本引用高亮和替换留给后续切片。
+- 版本：只展示 manifest 中正式、不可变的迭代版本记录；版本卡展示项目修订、创建原因与父版本，聚焦态同时展示直接子版本和资源绑定。点击版本卡后高亮仍存在于当前资源投影中的引用资源；缺失历史资源只保留绑定身份，不生成幽灵资源卡。资源替换仍留给后续切片。
 - mentor 最新决定：资源聚焦不提供工具栏，也不提供工具侧边栏。
 - 点击资源后，中央主视窗从 `resources.list` 切换为 `resources.focused.document / art / audio / version`，左侧平台导航、右侧 Supervisor 对话和底部 Agent 状态栏保持原位；聚焦容器只包含标题、资源主体、必要元数据与右上角收起按钮，不使用页面级浮层或可拖动标题栏。
 - 退出聚焦后恢复进入前的搜索条件、dependency / type 布局模式、资源画布滚动位置和选中资源；这些只属于当前前端会话，不写入布局 sidecar。
-- 阶段四只新增上述受控读取与媒体展示，不新增资源聚焦工具栏 / 工具侧边栏，不新增美术编辑、音频编辑 / 替换、资源重新生成、不可变版本写入或运行模块。飞书原需求中“编辑并生成新资源”的条件项仍暂缓，不能只打开画板却缺少回写、`referenceResourceIds` 血缘登记、新资源自动选中与邻近布局的完整闭环。
+- 阶段四只新增上述受控读取与媒体展示；阶段六在同一聚焦容器内补齐正式版本只读展示和引用高亮，但不新增资源聚焦工具栏 / 工具侧边栏，不新增美术编辑、音频编辑 / 替换、资源重新生成、版本替换或运行模块。飞书原需求中“编辑并生成新资源”的条件项仍暂缓，不能只打开画板却缺少回写、`referenceResourceIds` 血缘登记、新资源自动选中与邻近布局的完整闭环。
 
 ### 4.4 历史成果与当前状态
 
@@ -307,19 +307,29 @@ type ProjectVersionResourceReplacement = {
 
 ### 5.4 游戏迭代版本（P1）
 
+阶段六实现状态（2026-08-03）：正式版本业务真相扩展在本地项目 `.agent/manifest.json` 的可选 `versions` 字段中；旧项目字段缺失时等价于空列表，不根据 checkpoint、布局 sidecar、预览记录或 `game-creator-project-revision.v1` 自动伪造版本。版本数组只允许追加，已有记录不得删除、重排或修改；首轮没有版本创建按钮，也不自动把当前编辑态登记为版本。
+
 ```ts
 type GameIterationVersion = {
   versionId: string;
   parentVersionId: string | null;
   projectRevision: number;
   resourceBindings: Array<{ slotId: string; resourceId: string }>;
-  parameterSnapshotId: string;
   createdReason: 'initial' | 'resource-replacement' | 'agent-revision';
   createdAt: number;
 };
+
+type GameCreationAppManifest = {
+  // 既有字段省略
+  versions?: GameIterationVersion[];
+};
 ```
 
-版本写入后不可修改。
+- `versions` 按追加顺序保存。第一条必须是 `initial + parentVersionId=null`；后续记录必须引用数组中更早出现的父版本，创建原因不能再是 `initial`，从而天然排除自引用、悬空父版本和父子环。
+- `projectRevision` 与 `createdAt` 必须是 JavaScript 安全非负整数；子版本的修订必须严格大于父版本，创建时间不得早于父版本。
+- 同一版本内 `slotId` 唯一；`resourceId` 固定保存 manifest asset ID，不保存资源卡显示名称、External Editor resource ID、路径或布局 ID。历史资源已不在当前 manifest 时仍保留原绑定，但界面不为其合成资源卡。
+- Tauri manifest 存储边界在每次写入前校验完整版本图，并与磁盘中的旧 `versions` 前缀逐项比较；只允许追加新记录，已有记录被修改、删除或重排时写入失败且原文件保持不变。
+- 版本卡标题由稳定追加序号生成，卡片与聚焦态展示 `versionId / projectRevision / createdReason / parentVersionId`；聚焦态额外展示直接子版本和全部 slot 绑定。点击版本卡只高亮当前投影中唯一匹配 `asset:<resourceId>` 的资源卡，不修改版本或资源。
 
 ### 5.5 测试切片与数值参数（P2）
 
@@ -381,7 +391,7 @@ type ProjectAgentMudPointAttribution = {
 
 - 已实施依赖/类型两套坐标持久化、首次默认不重叠布局、历史坐标跨重启恢复与自动协调 CAS 冲突处理；资源卡手动拖动暂缓。
 - 资源关系线在布局持久化验收通过后单独实施，不与本切片捆绑伪造完成。
-- 版本资源高亮、兼容性判断和不可变下一迭代版本。
+- 已实施正式版本只读模型、版本卡、父子关系与引用资源高亮；资源兼容性判断和不可变下一迭代版本创建仍待后续切片。
 - 美术/音频编辑状态接线。
 
 ### P2
@@ -426,9 +436,18 @@ type ProjectAgentMudPointAttribution = {
 7. 4096 资源链式 fixture 继续验证拓扑、聚合复杂度和自动布局性能；拖动局部更新与真实 Chromium 拖动帧预算暂缓，不作为当前验收条件。最右侧自环与箭头仍需完整显示。
 8. Rust 图读取延迟时，dependency sidecar 在图进入 `ready / failed` 前没有读取或写入；首次布局直接使用 Rust 返回的最终 producer 与 dependency depth。重新打开旧布局时手动位置逐项不变，自动位置按最终拓扑协调且相同结果不增加 revision。
 
+### 7.4 P1 正式项目版本阶段六验收
+
+1. manifest 缺少 `versions` 时旧项目正常打开且不显示伪造版本；存在合法记录时，固定“项目版本”分区按追加顺序显示稳定版本卡。
+2. 根版本、父版本和直接子版本关系在卡片或聚焦态可见；悬空父版本、自引用、重复 ID、非递增修订、倒退时间、重复 slot 和超限数字均失败关闭。
+3. 点击版本卡后，当前 manifest 中仍存在的绑定资产卡被高亮；历史已删除资产只在版本详情保留 ID，不创建幽灵卡，也不把 External Editor resource ID 猜成 manifest asset ID。
+4. 版本聚焦态只读展示身份、修订、创建原因、父子关系、创建时间和 slot 绑定，不提供编辑、替换、切换、回滚或运行按钮。
+5. 任意现有 manifest 写入只能保留磁盘版本前缀并追加新记录；修改、删除或重排已有版本时写入失败，原 manifest 字节不被覆盖。
+6. 版本选择和高亮不写 manifest、布局 sidecar 或 project revision；dependency / type 两种布局都可显示绑定高亮，既有依赖关系 SVG 语义不变。
+
 ## 8. 非目标
 
-- 本切片不实现资源卡手动拖动，也不实现资源聚焦工具栏、资源聚焦工具侧边栏、美术编辑、音频编辑 / 替换、资源重新生成、资源替换、不可变迭代版本写入、运行模块扩展、测试切片、数值参数或泥点归因；已实现的资源读取和关系图只提供 Rust 只读模型与前端派生展示，不建立新的资源业务真相。
+- 阶段六不实现资源卡手动拖动，也不实现资源聚焦工具栏、资源聚焦工具侧边栏、美术编辑、音频编辑 / 替换、资源重新生成、资源替换、下一迭代版本创建入口、运行版本切换、版本回滚、运行模块扩展、测试切片、运行态消费版本、数值参数或泥点归因。正式版本记录已经成为 manifest 业务真相，但本阶段只读取、校验和展示已有记录。
 - 本切片不持久化资源聚焦状态、画布缩放 / 平移、搜索条件、筛选条件或当前 mode；聚焦退出时的列表上下文恢复只限当前前端会话，这些状态如需跨重启保存必须另行扩展合同，不能塞入 `game-creator-resource-layout.v1`。
 - 不修改 SpacetimeDB schema。
 - 不开放普通用户 Agent.md/Skill。
diff --git a/docs/project-memory/shared-memory/decision-log.md b/docs/project-memory/shared-memory/decision-log.md
index 10b6e04ff..cc8dd701a 100644
--- a/docs/project-memory/shared-memory/decision-log.md
+++ b/docs/project-memory/shared-memory/decision-log.md
@@ -1,5 +1,13 @@
 # 决策记录
 
+## 2026-08-03 正式项目版本阶段六落在 manifest 追加不可变记录
+
+- 背景：阶段一至五已经完成资源卡禁拖、固定分类投影、中央聚焦、依赖关系图和引用深度排列，但“项目版本”仍只能接受未接线的前端 read model；checkpoint、布局 sidecar 和项目 mutation revision 都不能代表正式可追溯版本。
+- 决策：本地 `.agent/manifest.json` 新增可选 `versions` 数组，旧项目缺失时只读为空。版本父子图使用父先于子的追加序列，Rust 在读写边界验证完整合同，并在覆盖 manifest 前要求已有磁盘版本是新版本数组的相等前缀，以此禁止修改、删除和重排。前端只从 manifest 投影版本卡；绑定 `resourceId` 固定解释为 manifest asset ID，点击版本在两种布局中高亮仍存在的资产卡。
+- 边界：阶段六只实现版本卡、父子关系、聚焦详情、引用资源高亮和不可变存储门禁；不自动回填版本，不创建下一版本，不做资源替换、运行版本切换、回滚、测试切片或运行态消费。SpacetimeDB、checkpoint、project revision 与布局 sidecar 均不改变。
+- 验证方式：共享 Rust / TypeScript 契约测试覆盖 camelCase 与缺省兼容；Tauri manifest 测试覆盖合法追加和历史修改拒绝；前端资源投影与 AppSurface 覆盖版本卡、父子详情、缺失历史资产和 dependency / type 绑定高亮，并运行 shell typecheck、编码检查与 `git diff --check`。
+- 关联文档：`docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md`、`docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md`。
+
 ## 2026-08-03 资源依赖阶段五以引用 SCC 深度驱动自动排列
 
 - 背景：资源关系图已经能展示精确引用与聚合任务流，但 dependency 自动布局只消费可信 producer 对应的任务 DAG 深度；同一任务生成的派生资源、没有 producer 审计的 manifest 资源和资源引用环均无法稳定体现“被引用资源在前、引用资源在后”的顺序。
diff --git a/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md b/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md
index cda56e3c0..852c55885 100644
--- a/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md
+++ b/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md
@@ -360,7 +360,7 @@ game-project/
 
 - 页面骨架固定为左侧现有全局导航、中间主视窗、右侧陶泥儿对话和底部子 Agent 状态栏；不新建第二套客户端或平行项目页。
 - 中间主视窗提供 `资源管理 / 运行` 切换。`code-prototype` 任务完成前运行入口保持视觉不可用，但仍可点击查看“当前无可运行版本”，不能使用会阻断说明交互的原生 `disabled` 或 `aria-disabled`；完成后才允许进入运行表现层。切回资源管理只修改前端展示态，不伪造后端预览暂停结果。
-- 资源管理从当前 `GameCreationAppManifest`、合法 Agent 文本回执、已导入附件和显式项目版本 read model 派生资源，固定按文档、项目版本、美术资源、音乐音效资源分区；未知任务产物不再兜底为版本，任务声明中的未登记音频也不冒充正式音频。`按依赖 / 按类型` 使用各自前端排列，dependency 模式额外绘制当前 manifest 与资源投影可证明的依赖关系。排列与图层都不写回 manifest，不能推断或伪造缺失依赖。
+- 资源管理从当前 `GameCreationAppManifest`（包含可选 `versions`）、合法 Agent 文本回执和已导入附件派生资源，固定按文档、项目版本、美术资源、音乐音效资源分区；未知任务产物不再兜底为版本，任务声明中的未登记音频也不冒充正式音频。`按依赖 / 按类型` 使用各自前端排列，dependency 模式额外绘制当前 manifest 与资源投影可证明的依赖关系。排列与图层都不写回 manifest，不能推断或伪造缺失依赖。
 - 资源卡支持点击聚焦、搜索和类型筛选。2026-07-28 起完成两套二维坐标与本地 CAS sidecar；2026-07-31 起 dependency 模式增加不持久化的原生 SVG 关系图层。2026-08-03 mentor 决定暂缓资源卡拖动，当前卡片不挂载 Pointer Down / Move / Up / Cancel 拖动入口，只允许自动布局和点击聚焦。聚焦态替换中央主视窗内容，保留左侧导航、右侧对话和底部 Agent 状态栏，退出后恢复搜索、布局模式、滚动位置与选中资源；不提供工具栏、工具侧边栏或可拖动标题栏。阶段四已补齐安全本地文档、扩展美术媒体与音频聚焦，正文独立滚动，视频 / 音频使用内置媒体控件，失败显示空态；美术编辑、音频编辑 / 替换、版本替换或运行模块仍不在本阶段。
 - 运行表现层首版直接嵌入当前项目的 loopback 游戏画面，并展示上一项 / 暂停继续 / 下一项切片控制、素材信息和数值微调面板。`preview.start` 启动本地 server 后把真实 URL 回写工作台，`preview.open` 只激活客户端内运行视图，不再调用系统浏览器；切片、参数调整和自然语言新增调节项首版仍只保留本地 UI 草稿，不修改代码或 manifest。
 - 右侧继续复用现有 Project Supervisor 会话、Runtime 澄清和确认链路；输入区展示 `严格审批 / 风险审批 / 无需审批` 独立面板。P0 只有严格审批可选；风险审批和无需审批保持视觉不可用但允许点击查看原因，不替代 Runtime 的逐动作权限、确认、sandbox 或 reconciliation 门禁。风险 Rank 算法记录在 `docs/project-memory/todos/【待解决】AI游戏创作高风险审批Rank-2026-07-20.md`，前端不得自行计算。
@@ -410,6 +410,10 @@ game-project/
 
 2026-08-03 阶段五加固：Rust read model 把 producer assignment 与布局深度分离。完整任务图先经 SCC 压缩形成可信 producer 的任务深度下限，精确资源引用图再经迭代式 SCC 压缩和确定性最长层级传播形成所有可见资源的 `dependencyDepths`；因此同一任务的派生资源、缺少 producer 审计的 manifest 资源和引用环都能稳定满足“被引用资源在前、引用资源在后”，没有引用关系的资源保持深度 `0`。前端不递归推导正式依赖层级。dependency 模式以 scope 化 `idle / loading / ready / failed` 状态阻断布局 Hook；图终态前不创建 fallback、不读取或写入 sidecar，图失败只以空图初始化一次。读取已有 dependency 布局时保留全部 `manuallyPlaced=true` 坐标，把 `manuallyPlaced=false` 作为可派生自动位置按最终深度重新协调；结果未变化时不写入。任务流仍按任务对聚合，不为布局计算或 SVG 绘制生成资源笛卡尔积。
 
+2026-08-03 阶段六：正式迭代版本直接扩展本地 `.agent/manifest.json`，不新增 checkpoint / layout sidecar / SpacetimeDB 平行业务真相。共享 Rust / TypeScript 合同新增可选 `versions: GameIterationVersion[]`；旧项目缺失字段时只读为空，不回填。Rust 在 manifest 读写边界校验版本唯一性、父先于子、根/原因一致、父子修订与时间单调、slot 唯一和 JavaScript 安全整数，并在覆盖已有 manifest 前要求磁盘版本数组是新数组的逐项相等前缀，从存储边界保证历史记录不可修改、删除或重排。
+
+工作台资源投影只从 `manifest.versions` 构建版本卡，按数组追加顺序生成稳定“版本 N”标题；不再接收前端独立 `projectVersions` 注入。`resourceBindings.resourceId` 只解释为 manifest asset ID，并映射到现有 `asset:<id>` 卡片。选中版本后在 dependency / type 两种布局中高亮当前仍存在的绑定资产；缺失历史资产只留在版本聚焦详情，不能合成幽灵卡或猜测 External Editor resource ID。版本聚焦复用中央只读容器，展示身份、修订、原因、父版本、直接子版本、创建时间与 slot 绑定。本阶段不提供版本创建、替换、切换、回滚、测试切片或运行态消费入口。
+
 历史命令式 drag preview 句柄与局部连接索引可以保留，但项目工作台不再向资源卡传入该入口。拖动热路径、4096 张真实卡片拖动重渲染和 Chromium p95 门槛统一暂缓；当前回归只要求 Pointer Move 不改变卡片坐标、SVG path 或布局 revision。`ResizeObserver` 仍保持单图层单实例，任何实时 DOM 几何都不得通过 Tauri IPC 往返 Rust。
 
 ## 分阶段实施
diff --git a/packages/shared/src/contracts/gameCreationApp.test.ts b/packages/shared/src/contracts/gameCreationApp.test.ts
index 655329af0..0e0b97cf5 100644
--- a/packages/shared/src/contracts/gameCreationApp.test.ts
+++ b/packages/shared/src/contracts/gameCreationApp.test.ts
@@ -638,6 +638,16 @@ describe('AI 游戏创作 App 共享契约', () => {
           updatedAt: 123,
         },
       ],
+      versions: [
+        {
+          versionId: 'version-1',
+          parentVersionId: null,
+          projectRevision: 7,
+          resourceBindings: [{ slotId: 'player', resourceId: 'asset-player' }],
+          createdReason: 'initial',
+          createdAt: 456,
+        },
+      ],
       assets: [
         {
           id: 'asset-player',
@@ -678,6 +688,16 @@ describe('AI 游戏创作 App 共享契约', () => {
           logPath: '.agent/logs/command.log',
         },
       ],
+      versions: [
+        {
+          versionId: 'version-1',
+          parentVersionId: null,
+          projectRevision: 7,
+          resourceBindings: [{ slotId: 'player', resourceId: 'asset-player' }],
+          createdReason: 'initial',
+          createdAt: 456,
+        },
+      ],
     });
   });
 });
diff --git a/packages/shared/src/contracts/gameCreationApp.ts b/packages/shared/src/contracts/gameCreationApp.ts
index adcba62ba..40b891a51 100644
--- a/packages/shared/src/contracts/gameCreationApp.ts
+++ b/packages/shared/src/contracts/gameCreationApp.ts
@@ -537,6 +537,25 @@ export interface GameCreationAppCommandRunState {
   updatedAt: number;
 }
 
+export type GameIterationVersionCreatedReason =
+  | 'initial'
+  | 'resource-replacement'
+  | 'agent-revision';
+
+export interface GameIterationVersionResourceBinding {
+  slotId: string;
+  resourceId: string;
+}
+
+export interface GameIterationVersion {
+  versionId: string;
+  parentVersionId: string | null;
+  projectRevision: number;
+  resourceBindings: GameIterationVersionResourceBinding[];
+  createdReason: GameIterationVersionCreatedReason;
+  createdAt: number;
+}
+
 export interface GameCreationAppManifest {
   schemaVersion: string;
   projectId: string;
@@ -546,6 +565,7 @@ export interface GameCreationAppManifest {
   assets: GameCreationAppAssetManifestEntry[];
   preview?: GameCreationAppPreviewState | null;
   commandRuns?: GameCreationAppCommandRunState[];
+  versions?: GameIterationVersion[];
 }
 
 export interface GameCreationAgentToolCallTrace {
diff --git a/server-rs/crates/shared-contracts/src/game_creation_app.rs b/server-rs/crates/shared-contracts/src/game_creation_app.rs
index 0d2225abe..5da4426df 100644
--- a/server-rs/crates/shared-contracts/src/game_creation_app.rs
+++ b/server-rs/crates/shared-contracts/src/game_creation_app.rs
@@ -1,5 +1,5 @@
 use serde::{Deserialize, Serialize};
-use std::collections::HashSet;
+use std::collections::{HashMap, HashSet};
 
 pub const GAME_CREATION_APP_MANIFEST_SCHEMA_VERSION: &str = "game-creation-app.manifest.v1";
 pub const GAME_CREATION_AGENT_RUN_SCHEMA_VERSION: &str = "game-creator-agent-run.v1";
@@ -611,6 +611,142 @@ pub struct GameCreationAppCommandRunState {
     pub updated_at: u64,
 }
 
+pub const GAME_ITERATION_VERSION_MAX_COUNT: usize = 4096;
+pub const GAME_ITERATION_VERSION_MAX_BINDING_COUNT: usize = 4096;
+pub const GAME_ITERATION_VERSION_MAX_SAFE_INTEGER: u64 = 9_007_199_254_740_991;
+
+#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
+#[serde(rename_all = "kebab-case")]
+pub enum GameIterationVersionCreatedReason {
+    Initial,
+    ResourceReplacement,
+    AgentRevision,
+}
+
+#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct GameIterationVersionResourceBinding {
+    pub slot_id: String,
+    pub resource_id: String,
+}
+
+#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct GameIterationVersion {
+    pub version_id: String,
+    pub parent_version_id: Option<String>,
+    pub project_revision: u64,
+    pub resource_bindings: Vec<GameIterationVersionResourceBinding>,
+    pub created_reason: GameIterationVersionCreatedReason,
+    pub created_at: u64,
+}
+
+fn validate_iteration_version_id(value: &str, label: &str, max_chars: usize) -> Result<(), String> {
+    if value.is_empty() || value.trim() != value {
+        return Err(format!("{label}不能为空或包含首尾空白"));
+    }
+    if value.chars().count() > max_chars || value.chars().any(char::is_control) {
+        return Err(format!("{label}无效"));
+    }
+    Ok(())
+}
+
+pub fn validate_game_iteration_versions(versions: &[GameIterationVersion]) -> Result<(), String> {
+    if versions.len() > GAME_ITERATION_VERSION_MAX_COUNT {
+        return Err(format!(
+            "项目版本最多支持 {GAME_ITERATION_VERSION_MAX_COUNT} 条"
+        ));
+    }
+
+    let mut previous_versions = HashMap::<&str, (u64, u64)>::new();
+    for (index, version) in versions.iter().enumerate() {
+        validate_iteration_version_id(&version.version_id, "版本 ID", 128)?;
+        if previous_versions.contains_key(version.version_id.as_str()) {
+            return Err(format!("项目版本 ID 重复：{}", version.version_id));
+        }
+        if version.project_revision > GAME_ITERATION_VERSION_MAX_SAFE_INTEGER {
+            return Err(format!(
+                "项目版本 {} 的 projectRevision 超出 JavaScript 安全整数范围",
+                version.version_id
+            ));
+        }
+        if version.created_at > GAME_ITERATION_VERSION_MAX_SAFE_INTEGER {
+            return Err(format!(
+                "项目版本 {} 的 createdAt 超出 JavaScript 安全整数范围",
+                version.version_id
+            ));
+        }
+
+        if index == 0 {
+            if version.parent_version_id.is_some()
+                || version.created_reason != GameIterationVersionCreatedReason::Initial
+            {
+                return Err(format!(
+                    "项目版本 {} 的首条记录必须是无父版本的 initial 版本",
+                    version.version_id
+                ));
+            }
+        } else {
+            if version.created_reason == GameIterationVersionCreatedReason::Initial {
+                return Err(format!(
+                    "项目版本 {} 只有首个版本可以使用 initial 创建原因",
+                    version.version_id
+                ));
+            }
+            let Some(parent_version_id) = &version.parent_version_id else {
+                return Err(format!(
+                    "项目版本 {} 只有首个 initial 版本可以没有父版本",
+                    version.version_id
+                ));
+            };
+            validate_iteration_version_id(parent_version_id, "父版本 ID", 128)?;
+            let Some((parent_revision, parent_created_at)) =
+                previous_versions.get(parent_version_id.as_str())
+            else {
+                return Err(format!(
+                    "项目版本 {} 的父版本必须先于子版本存在",
+                    version.version_id
+                ));
+            };
+            if version.project_revision <= *parent_revision {
+                return Err(format!(
+                    "项目版本 {} 的 projectRevision 必须大于父版本",
+                    version.version_id
+                ));
+            }
+            if version.created_at < *parent_created_at {
+                return Err(format!(
+                    "项目版本 {} 的 createdAt 不能早于父版本",
+                    version.version_id
+                ));
+            }
+        }
+
+        if version.resource_bindings.len() > GAME_ITERATION_VERSION_MAX_BINDING_COUNT {
+            return Err(format!(
+                "项目版本 {} 的资源绑定最多支持 {GAME_ITERATION_VERSION_MAX_BINDING_COUNT} 项",
+                version.version_id
+            ));
+        }
+        let mut slot_ids = HashSet::new();
+        for binding in &version.resource_bindings {
+            validate_iteration_version_id(&binding.slot_id, "版本资源槽位 ID", 256)?;
+            validate_iteration_version_id(&binding.resource_id, "版本资源 ID", 512)?;
+            if !slot_ids.insert(binding.slot_id.as_str()) {
+                return Err(format!(
+                    "项目版本 {} 的资源槽位重复：{}",
+                    version.version_id, binding.slot_id
+                ));
+            }
+        }
+        previous_versions.insert(
+            version.version_id.as_str(),
+            (version.project_revision, version.created_at),
+        );
+    }
+    Ok(())
+}
+
 #[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
 #[serde(rename_all = "camelCase")]
 pub struct GameCreationAppManifest {
@@ -626,6 +762,8 @@ pub struct GameCreationAppManifest {
     pub preview: Option<GameCreationAppPreviewState>,
     #[serde(default, skip_serializing_if = "Vec::is_empty")]
     pub command_runs: Vec<GameCreationAppCommandRunState>,
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub versions: Vec<GameIterationVersion>,
 }
 
 #[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
@@ -757,6 +895,7 @@ pub fn new_game_creation_app_manifest(
         assets: Vec::new(),
         preview: None,
         command_runs: Vec::new(),
+        versions: Vec::new(),
     }
 }
 
@@ -1594,6 +1733,17 @@ mod tests {
             log_path: ".agent/logs/command.log".to_string(),
             updated_at: 123,
         });
+        manifest.versions.push(GameIterationVersion {
+            version_id: "version-1".to_string(),
+            parent_version_id: None,
+            project_revision: 7,
+            resource_bindings: vec![GameIterationVersionResourceBinding {
+                slot_id: "player".to_string(),
+                resource_id: "asset-player".to_string(),
+            }],
+            created_reason: GameIterationVersionCreatedReason::Initial,
+            created_at: 456,
+        });
         manifest.assets.push(GameCreationAppAssetManifestEntry {
             id: "asset-player".to_string(),
             kind: "character".to_string(),
@@ -1630,6 +1780,95 @@ mod tests {
             payload["assets"][0]["source"]["canvasProjectId"],
             json!("canvas-project-1")
         );
+        assert_eq!(payload["versions"][0]["versionId"], json!("version-1"));
+        assert_eq!(
+            payload["versions"][0]["resourceBindings"][0]["slotId"],
+            json!("player")
+        );
+        assert_eq!(payload["versions"][0]["createdReason"], json!("initial"));
+    }
+
+    #[test]
+    fn iteration_versions_require_an_append_ordered_parent_graph() {
+        let root = GameIterationVersion {
+            version_id: "version-root".to_string(),
+            parent_version_id: None,
+            project_revision: 4,
+            resource_bindings: vec![GameIterationVersionResourceBinding {
+                slot_id: "player".to_string(),
+                resource_id: "asset-player".to_string(),
+            }],
+            created_reason: GameIterationVersionCreatedReason::Initial,
+            created_at: 100,
+        };
+        let child = GameIterationVersion {
+            version_id: "version-child".to_string(),
+            parent_version_id: Some(root.version_id.clone()),
+            project_revision: 5,
+            resource_bindings: Vec::new(),
+            created_reason: GameIterationVersionCreatedReason::AgentRevision,
+            created_at: 101,
+        };
+
+        validate_game_iteration_versions(&[root.clone(), child.clone()])
+            .expect("valid version graph");
+
+        let mut invalid_child = child.clone();
+        invalid_child.version_id = root.version_id.clone();
+        assert!(
+            validate_game_iteration_versions(&[root.clone(), invalid_child])
+                .expect_err("reject duplicate version id")
+                .contains("版本 ID 重复")
+        );
+
+        let mut invalid_child = child.clone();
+        invalid_child.parent_version_id = Some("missing".to_string());
+        assert!(
+            validate_game_iteration_versions(&[root.clone(), invalid_child])
+                .expect_err("reject missing parent")
+                .contains("父版本必须先于子版本存在")
+        );
+
+        let mut invalid_child = child.clone();
+        invalid_child.project_revision = root.project_revision;
+        assert!(
+            validate_game_iteration_versions(&[root.clone(), invalid_child])
+                .expect_err("reject non-increasing revision")
+                .contains("projectRevision 必须大于父版本")
+        );
+
+        let mut invalid_child = child.clone();
+        invalid_child.created_at = root.created_at - 1;
+        assert!(
+            validate_game_iteration_versions(&[root.clone(), invalid_child])
+                .expect_err("reject time before parent")
+                .contains("createdAt 不能早于父版本")
+        );
+
+        let mut invalid_child = child.clone();
+        invalid_child.project_revision = GAME_ITERATION_VERSION_MAX_SAFE_INTEGER + 1;
+        assert!(
+            validate_game_iteration_versions(&[root.clone(), invalid_child])
+                .expect_err("reject unsafe project revision")
+                .contains("超出 JavaScript 安全整数范围")
+        );
+
+        let mut invalid_child = child;
+        invalid_child.resource_bindings = vec![
+            GameIterationVersionResourceBinding {
+                slot_id: "player".to_string(),
+                resource_id: "asset-player".to_string(),
+            },
+            GameIterationVersionResourceBinding {
+                slot_id: "player".to_string(),
+                resource_id: "asset-player-next".to_string(),
+            },
+        ];
+        assert!(
+            validate_game_iteration_versions(&[root, invalid_child])
+                .expect_err("reject duplicate slot")
+                .contains("资源槽位重复")
+        );
     }
 
     #[test]
-- 
2.52.0


From 80bcb4ba0e2cc60ab6556892b5cb540d4d40ecaf Mon Sep 17 00:00:00 2001
From: menghao <mh18530625731@163.com>
Date: Tue, 4 Aug 2026 10:06:12 +0800
Subject: [PATCH 15/27] =?UTF-8?q?=E5=AE=8C=E6=88=90=E8=B5=84=E6=BA=90?=
 =?UTF-8?q?=E7=AE=A1=E7=90=86=E9=98=B6=E6=AE=B5=E4=B8=83=E9=AA=8C=E6=94=B6?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

补齐视频与资源读取失败空态测试
完成全量前后端和 Rust CI 验收
修复 macOS/BSD 跨平台门禁与测试隔离
更新阶段七验收与共享项目记忆
---
 .../smoke-agent-run-local-provider.mjs        |  4 ++
 .../src/agent/generation/canvas_generation.rs |  2 +-
 .../generation/external_generation_state.rs   |  4 +-
 .../pending_confirmation_ledger.rs            |  2 +-
 .../provider_request_builders.rs              |  2 +-
 .../main_loop_deadline_tests.rs               | 20 ++-----
 .../agent/runtime_driver/main_loop_tests.rs   |  4 +-
 .../src/agent/runtime_driver/recovery_scan.rs |  2 +-
 .../agent/runtime_protocol/context_bundle.rs  |  5 +-
 .../src-tauri/src/mcp.rs                      |  5 +-
 .../src/tests/collaboration/recovery.rs       |  7 +++
 .../src-tauri/src/tests/mod.rs                | 10 ++++
 .../src/view/project-development/index.tsx    |  1 -
 .../resourceProjectionModel.ts                |  2 +-
 .../appSurface/project-development.suite.ts   | 56 ++++++++++++++++-
 ...AI游戏创作】项目开发工作台PRD-2026-07-20.md | 12 +++-
 .../shared-memory/decision-log.md             |  8 +++
 docs/project-memory/shared-memory/pitfalls.md |  9 +++
 ...�案】AI游戏创作智能体App实施计划-2026-06-24.md |  1 +
 ...发运维】本地开发验证与生产运维-2026-05-15.md |  2 +-
 scripts/check-maintenance-page.mjs            |  8 +++
 scripts/check-module-runtime-artifact.mjs     |  3 +-
 scripts/check-production-api-deploy.mjs       | 60 +++++++++++++++++--
 scripts/deploy/maintenance-on.sh              | 17 +++++-
 scripts/deploy/production-api-deploy.sh       | 12 +++-
 ...acetime-repair-editor-canvas-resources.mjs | 20 ++++++-
 26 files changed, 233 insertions(+), 45 deletions(-)

diff --git a/apps/ai-game-creator-shell/scripts/smoke-agent-run-local-provider.mjs b/apps/ai-game-creator-shell/scripts/smoke-agent-run-local-provider.mjs
index ad77d7f19..6b03ae39c 100644
--- a/apps/ai-game-creator-shell/scripts/smoke-agent-run-local-provider.mjs
+++ b/apps/ai-game-creator-shell/scripts/smoke-agent-run-local-provider.mjs
@@ -885,6 +885,10 @@ function readBrowserDom(url) {
 
 function resolveChromeBin() {
   for (const candidate of [
+    '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+    '/Applications/Chromium.app/Contents/MacOS/Chromium',
+    '/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge',
+    '/opt/google/chrome/chrome',
     '/usr/bin/google-chrome',
     '/usr/bin/google-chrome-stable',
     '/usr/bin/chromium',
diff --git a/apps/ai-game-creator-shell/src-tauri/src/agent/generation/canvas_generation.rs b/apps/ai-game-creator-shell/src-tauri/src/agent/generation/canvas_generation.rs
index 6f7f7d55f..ca61da923 100644
--- a/apps/ai-game-creator-shell/src-tauri/src/agent/generation/canvas_generation.rs
+++ b/apps/ai-game-creator-shell/src-tauri/src/agent/generation/canvas_generation.rs
@@ -2057,7 +2057,7 @@ mod canvas_generation_tests {
 
     #[tokio::test]
     async fn recovery_scan_resumes_accepted_generation_on_default_worker_stack() {
-        let temporary = tempfile::tempdir().expect("create accepted scan project");
+        let temporary = crate::tests::canonical_test_tempdir("accepted-generation-scan-");
         let root = temporary.path();
         init_local_game_project_at(root, "accepted-scan", "恢复扫描测试")
             .expect("init accepted scan project");
diff --git a/apps/ai-game-creator-shell/src-tauri/src/agent/generation/external_generation_state.rs b/apps/ai-game-creator-shell/src-tauri/src/agent/generation/external_generation_state.rs
index 16bcd0a62..490540b08 100644
--- a/apps/ai-game-creator-shell/src-tauri/src/agent/generation/external_generation_state.rs
+++ b/apps/ai-game-creator-shell/src-tauri/src/agent/generation/external_generation_state.rs
@@ -736,7 +736,7 @@ mod external_generation_state_tests {
 
     #[test]
     fn prepared_generation_state_reuses_identity_and_only_accepted_can_resume() {
-        let temporary = tempfile::tempdir().expect("create generation ledger project");
+        let temporary = crate::tests::canonical_test_tempdir("external-generation-ledger-");
         let root = temporary.path();
         init_local_game_project_at(root, "generation-ledger", "生成账本测试")
             .expect("init project");
@@ -846,7 +846,7 @@ mod external_generation_state_tests {
 
     #[test]
     fn legacy_completed_generation_persists_only_allowlisted_safe_download_fields() {
-        let temporary = tempfile::tempdir().expect("create legacy generation ledger project");
+        let temporary = crate::tests::canonical_test_tempdir("legacy-generation-ledger-");
         let root = temporary.path();
         init_local_game_project_at(root, "legacy-generation-ledger", "旧同步生成账本测试")
             .expect("init project");
diff --git a/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_actions/pending_confirmation_ledger.rs b/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_actions/pending_confirmation_ledger.rs
index fa5493585..6de6a816e 100644
--- a/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_actions/pending_confirmation_ledger.rs
+++ b/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_actions/pending_confirmation_ledger.rs
@@ -790,7 +790,7 @@ mod tests {
 
     #[test]
     fn generation_cleanup_failure_preserves_pending_identity_anchor() {
-        let temporary = tempfile::tempdir().expect("create pending cleanup project");
+        let temporary = crate::tests::canonical_test_tempdir("pending-generation-cleanup-");
         let root = temporary.path();
         let run_id = "generation-cleanup-order-run";
         init_local_game_project_at(root, "generation-cleanup-order", "生成账本清理顺序测试")
diff --git a/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_actions/provider_request_builders.rs b/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_actions/provider_request_builders.rs
index 383a7c415..71370aaf8 100644
--- a/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_actions/provider_request_builders.rs
+++ b/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_actions/provider_request_builders.rs
@@ -425,7 +425,7 @@ mod tests {
         const ORDINARY_NOTICE: &str = "除下方有界仓库启动上下文、当前 Session 未压缩对话尾部或历史压缩摘要外，项目记忆、资产和源码正文不会预加载";
         const MEMORY_MARKER: &str = "supervisor-preloaded-context-marker";
 
-        let directory = tempfile::tempdir().expect("temp project directory");
+        let directory = crate::tests::canonical_test_tempdir("provider-request-project-");
         let root = directory.path().join("project");
         init_local_game_project_at(&root, "project-1", "项目总控预加载说明测试")
             .expect("project init");
diff --git a/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_driver/main_loop_deadline_tests.rs b/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_driver/main_loop_deadline_tests.rs
index 843dc4c06..c7e1e211d 100644
--- a/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_driver/main_loop_deadline_tests.rs
+++ b/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_driver/main_loop_deadline_tests.rs
@@ -64,14 +64,8 @@ async fn game_chat_absolute_deadline_returns_an_in_flight_result_before_expiry()
 
 #[tokio::test]
 async fn game_chat_absolute_deadline_preserves_external_generation_reconciliation() {
-    let root = std::env::temp_dir().join(format!(
-        "genarrative-game-chat-deadline-reconciliation-{}-{}",
-        std::process::id(),
-        std::time::SystemTime::now()
-            .duration_since(std::time::UNIX_EPOCH)
-            .expect("system clock")
-            .as_nanos()
-    ));
+    let temporary = crate::tests::canonical_test_tempdir("game-chat-deadline-reconciliation-");
+    let root = temporary.path().join("project");
     init_local_game_project_at(&root, "deadline-reconciliation", "硬截止收尾测试")
         .expect("project init");
     bind_game_creator_agent_runtime_run_profile_at(
@@ -271,14 +265,8 @@ async fn game_chat_absolute_deadline_preserves_external_generation_reconciliatio
 
 #[test]
 fn game_chat_absolute_deadline_still_cleans_local_action_recovery() {
-    let root = std::env::temp_dir().join(format!(
-        "genarrative-game-chat-deadline-local-cleanup-{}-{}",
-        std::process::id(),
-        std::time::SystemTime::now()
-            .duration_since(std::time::UNIX_EPOCH)
-            .expect("system clock")
-            .as_nanos()
-    ));
+    let temporary = crate::tests::canonical_test_tempdir("game-chat-deadline-local-cleanup-");
+    let root = temporary.path().join("project");
     init_local_game_project_at(&root, "deadline-local-cleanup", "硬截止本地清理测试")
         .expect("project init");
     let mut runtime = start_game_creator_agent_runtime_task_at(
diff --git a/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_driver/main_loop_tests.rs b/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_driver/main_loop_tests.rs
index 6981f58f4..6339a811e 100644
--- a/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_driver/main_loop_tests.rs
+++ b/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_driver/main_loop_tests.rs
@@ -767,7 +767,7 @@ fn standard_specialist_empty_plan_has_no_deterministic_final_reply_fallback() {
 fn autonomous_manifest_waiting_context_persists_without_finishing_parent_run() {
     const RUN_ID: &str = "autonomous-manifest-waiting-parent";
     const TASK: &str = "生成完整小游戏并完成项目任务图";
-    let temporary = tempfile::tempdir().expect("create manifest waiting root");
+    let temporary = crate::tests::canonical_test_tempdir("manifest-waiting-");
     let root = temporary.path().join("project");
     init_local_game_project_at(&root, "manifest-waiting-project", TASK)
         .expect("init manifest waiting project");
@@ -981,7 +981,7 @@ async fn autonomous_supervisor_converged_final_reply_deserialize_commits_fallbac
     const TASK: &str = "生成一个可完成静态检查和双视口试玩的塔防游戏";
     const TEST_KEY: &str = "autonomous-final-reply-fallback-key";
 
-    let temporary = tempfile::tempdir().expect("create autonomous fallback root");
+    let temporary = crate::tests::canonical_test_tempdir("autonomous-fallback-");
     let root = temporary.path().join("project");
     init_local_game_project_at(&root, "autonomous-fallback-project", TASK)
         .expect("init autonomous fallback project");
diff --git a/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_driver/recovery_scan.rs b/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_driver/recovery_scan.rs
index 974216689..364eca9cc 100644
--- a/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_driver/recovery_scan.rs
+++ b/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_driver/recovery_scan.rs
@@ -1221,7 +1221,7 @@ mod orphaned_external_generation_recovery_tests {
 
     #[test]
     fn recovery_scan_preserves_active_generation_orphan_then_cleans_terminal_legacy_orphan() {
-        let temporary = tempfile::tempdir().expect("create orphan generation recovery project");
+        let temporary = crate::tests::canonical_test_tempdir("orphan-generation-recovery-");
         let root = temporary.path();
         let run_id = "orphan-generation-recovery-run";
         init_local_game_project_at(root, "orphan-generation-recovery", "孤儿生成账本恢复测试")
diff --git a/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_protocol/context_bundle.rs b/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_protocol/context_bundle.rs
index 6c162f963..17973d262 100644
--- a/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_protocol/context_bundle.rs
+++ b/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_protocol/context_bundle.rs
@@ -827,10 +827,11 @@ mod tests {
             .duration_since(UNIX_EPOCH)
             .expect("system clock should be after epoch")
             .as_nanos();
-        let root = std::env::temp_dir().join(format!(
-            "genarrative-context-window-boundary-{}-{unique}",
+        let temporary = crate::tests::canonical_test_tempdir(&format!(
+            "context-window-boundary-{}-{unique}-",
             std::process::id()
         ));
+        let root = temporary.path().join("project");
         init_local_game_project_at(&root, "project-1", "上下文窗口边界恢复项目")
             .expect("project init");
         let mut runtime = start_game_creator_agent_runtime_task_at(
diff --git a/apps/ai-game-creator-shell/src-tauri/src/mcp.rs b/apps/ai-game-creator-shell/src-tauri/src/mcp.rs
index 2c5f26c40..28cc2f1c6 100644
--- a/apps/ai-game-creator-shell/src-tauri/src/mcp.rs
+++ b/apps/ai-game-creator-shell/src-tauri/src/mcp.rs
@@ -1931,7 +1931,10 @@ mod tests {
     }
 
     fn mcp_test_project(label: &str) -> PathBuf {
-        let root = std::env::temp_dir().join(format!(
+        let temp_root = std::env::temp_dir()
+            .canonicalize()
+            .expect("canonicalize MCP test temp root");
+        let root = temp_root.join(format!(
             "game-creator-mcp-{label}-{}-{}",
             std::process::id(),
             MCP_TEST_PROJECT_COUNTER.fetch_add(1, Ordering::Relaxed)
diff --git a/apps/ai-game-creator-shell/src-tauri/src/tests/collaboration/recovery.rs b/apps/ai-game-creator-shell/src-tauri/src/tests/collaboration/recovery.rs
index a255f8748..8365f3873 100644
--- a/apps/ai-game-creator-shell/src-tauri/src/tests/collaboration/recovery.rs
+++ b/apps/ai-game-creator-shell/src-tauri/src/tests/collaboration/recovery.rs
@@ -1606,5 +1606,12 @@ async fn project_supervisor_resume_rechecks_delegate_policy_after_delivery_reser
     .expect("read barrier after rejecting reserved delivery")
     .is_clear());
 
+    let released = wait_for_agent_runtime_lane_release_async(
+        &root,
+        GAME_CREATOR_PROJECT_SUPERVISOR_AGENT_ID,
+    )
+    .await;
+    assert_eq!(released.state.run_id, parent_run_id);
+
     fs::remove_dir_all(root).ok();
 }
diff --git a/apps/ai-game-creator-shell/src-tauri/src/tests/mod.rs b/apps/ai-game-creator-shell/src-tauri/src/tests/mod.rs
index 7eb2310e6..83488c15f 100644
--- a/apps/ai-game-creator-shell/src-tauri/src/tests/mod.rs
+++ b/apps/ai-game-creator-shell/src-tauri/src/tests/mod.rs
@@ -120,6 +120,16 @@ fn unique_project_path() -> PathBuf {
     ))
 }
 
+pub(crate) fn canonical_test_tempdir(prefix: &str) -> tempfile::TempDir {
+    let temp_root = std::env::temp_dir()
+        .canonicalize()
+        .expect("canonicalize test temp root");
+    tempfile::Builder::new()
+        .prefix(prefix)
+        .tempdir_in(temp_root)
+        .expect("create test temp directory under canonical root")
+}
+
 fn agent_goal_sidecar_path_for_test(root: &Path, agent_id: &str, session_id: &str) -> PathBuf {
     let path_key = |value: &str| {
         format!("{:x}", Sha256::digest(value.as_bytes()))
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 75c52a682..8d7663508 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
@@ -56,7 +56,6 @@ import {
   type ProjectResource,
   type ProjectResourceCategory,
   projectResourcesFromReadModels,
-  type ProjectVersionResourceSummary,
 } from './resourceProjectionModel';
 import { useProjectResourceCanvasLayout } from './useProjectResourceCanvasLayout';
 
diff --git a/apps/ai-game-creator-shell/src/view/project-development/resourceProjectionModel.ts b/apps/ai-game-creator-shell/src/view/project-development/resourceProjectionModel.ts
index 4f2e58f74..6cc98c8e5 100644
--- a/apps/ai-game-creator-shell/src/view/project-development/resourceProjectionModel.ts
+++ b/apps/ai-game-creator-shell/src/view/project-development/resourceProjectionModel.ts
@@ -1,6 +1,6 @@
 import type {
-  GameIterationVersion,
   GameCreationAppManifest,
+  GameIterationVersion,
   ProjectResourceCanvasSection,
 } from '../../../../../packages/shared/src/contracts/gameCreationApp';
 
diff --git a/apps/ai-game-creator-shell/tests/appSurface/project-development.suite.ts b/apps/ai-game-creator-shell/tests/appSurface/project-development.suite.ts
index 0fb7a155f..18b7c4bff 100644
--- a/apps/ai-game-creator-shell/tests/appSurface/project-development.suite.ts
+++ b/apps/ai-game-creator-shell/tests/appSurface/project-development.suite.ts
@@ -931,7 +931,7 @@ export function registerProjectWorkbenchFoundationTests() {
     expect(restoredCard?.getAttribute('aria-pressed')).toBe('true');
   });
 
-  it('loads registered documents, art media, and audio inside the central focus state', async () => {
+  it('loads registered documents, art media, video, and audio with safe failure states inside central focus', async () => {
     const manifest = createGameCreationAppManifest(
       'workbench-resource-media',
       '资源媒体测试',
@@ -951,6 +951,13 @@ export function registerProjectWorkbenchFoundationTests() {
         localPath: 'assets/icon.svg',
         source: { kind: 'generated' },
       },
+      {
+        id: 'art-video',
+        kind: 'animation',
+        mediaType: 'video/mp4',
+        localPath: 'assets/intro.mp4',
+        source: { kind: 'generated' },
+      },
       {
         id: 'audio-bgm',
         kind: 'bgm',
@@ -958,6 +965,13 @@ export function registerProjectWorkbenchFoundationTests() {
         localPath: 'assets/bgm.mp3',
         source: { kind: 'generated' },
       },
+      {
+        id: 'blocked-document',
+        kind: 'design-document',
+        mediaType: 'text/markdown',
+        localPath: 'game/blocked.md',
+        source: { kind: 'generated' },
+      },
     );
     let layoutRevision = 0;
     const invoke = vi.fn(
@@ -990,6 +1004,9 @@ export function registerProjectWorkbenchFoundationTests() {
           };
         }
         if (command === 'read_local_project_text_preview') {
+          if (args?.relativePath === 'game/blocked.md') {
+            throw new Error('项目权限策略要求用户确认：file.read');
+          }
           expect(args).toMatchObject({
             projectPath: '/tmp/workbench-resource-media',
             relativePath: 'game/design.md',
@@ -1004,6 +1021,14 @@ export function registerProjectWorkbenchFoundationTests() {
         }
         if (command === 'read_local_project_media_preview') {
           if (args?.category === 'art') {
+            if (args?.relativePath === 'assets/intro.mp4') {
+              return {
+                path: 'assets/intro.mp4',
+                mediaType: 'video/mp4',
+                byteLen: 128,
+                dataUrl: 'data:video/mp4;base64,AAAAIGZ0eXA=',
+              };
+            }
             return {
               path: 'assets/icon.svg',
               mediaType: 'image/svg+xml',
@@ -1065,6 +1090,22 @@ export function registerProjectWorkbenchFoundationTests() {
       ),
     );
 
+    fireEvent.click(screen.getByRole('button', { name: /intro\.mp4/ }));
+    const video = (await screen.findByLabelText(
+      'intro.mp4 视频预览',
+    )) as HTMLVideoElement;
+    expect(video.controls).toBe(true);
+    expect(video.preload).toBe('metadata');
+    expect(video.getAttribute('src')).toBe(
+      'data:video/mp4;base64,AAAAIGZ0eXA=',
+    );
+    fireEvent.click(
+      within(screen.getByRole('region', { name: 'intro.mp4' })).getByRole(
+        'button',
+        { name: '收起资源' },
+      ),
+    );
+
     fireEvent.click(screen.getByRole('button', { name: /bgm\.mp3/ }));
     const audio = (await screen.findByLabelText(
       'bgm.mp3 音频播放器',
@@ -1076,6 +1117,19 @@ export function registerProjectWorkbenchFoundationTests() {
       'read_local_project_media_preview',
       expect.objectContaining({ category: 'audio' }),
     );
+    fireEvent.click(
+      within(screen.getByRole('region', { name: 'bgm.mp3' })).getByRole(
+        'button',
+        { name: '收起资源' },
+      ),
+    );
+
+    fireEvent.click(screen.getByRole('button', { name: /blocked\.md/ }));
+    expect((await screen.findByRole('alert')).textContent).toBe(
+      '当前项目策略要求先确认读取资源',
+    );
+    expect(screen.getByLabelText('陶泥儿 Agent 对话')).not.toBeNull();
+    expect(screen.getByLabelText('子 Agent 状态栏')).not.toBeNull();
   });
 
   it('renders, filters, highlights, and destroys the resource dependency overlay without pointer previews', async () => {
diff --git a/docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md b/docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md
index 2786b73e8..46a1ab8de 100644
--- a/docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md
+++ b/docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md
@@ -1,6 +1,6 @@
 # AI 游戏创作项目开发工作台 PRD
 
-更新时间：`2026-08-03`（阶段六）
+更新时间：`2026-08-03`（阶段七验收收口）
 
 ## 1. 产品定位
 
@@ -445,9 +445,17 @@ type ProjectAgentMudPointAttribution = {
 5. 任意现有 manifest 写入只能保留磁盘版本前缀并追加新记录；修改、删除或重排已有版本时写入失败，原 manifest 字节不被覆盖。
 6. 版本选择和高亮不写 manifest、布局 sidecar 或 project revision；dependency / type 两种布局都可显示绑定高亮，既有依赖关系 SVG 语义不变。
 
+### 7.5 阶段七完整验收
+
+1. 对照飞书需求、当前 PRD、技术方案、代码、测试与阶段提交复核阶段零至阶段六；美术编辑生成新资源继续按本 PRD 已确认的闭环条件暂缓，不作为遗漏或伪完成。
+2. AppSurface 同时覆盖文档、图片、SVG、音频和视频聚焦；视频必须使用原生 `controls` 且 `preload="metadata"`，读取策略失败时中央主视窗显示安全空态，右侧对话和底部 Agent 状态栏继续存在。
+3. `1280×800` 应用内浏览器实测 `window`、document 与 body 均无页面级横向或纵向溢出。浏览器开发页受真实登录门禁保护，不为验收绕过认证或伪造 Tauri；工作台内部结构由 AppSurface 集成测试与资源布局 CSS 合同测试复核。
+4. 根目录全量 Vitest、前后端 typecheck / lint / build、Rust workspace test / check、SpacetimeDB schema、原生壳、内容 / 编码、生产运维与部署门禁全部通过后，阶段七才允许提交。
+5. 本地 `.env`、`.env.local`、密钥、缓存、日志和构建产物不进入阶段七提交；提交前再次执行编码检查和 `git diff --check`。
+
 ## 8. 非目标
 
-- 阶段六不实现资源卡手动拖动，也不实现资源聚焦工具栏、资源聚焦工具侧边栏、美术编辑、音频编辑 / 替换、资源重新生成、资源替换、下一迭代版本创建入口、运行版本切换、版本回滚、运行模块扩展、测试切片、运行态消费版本、数值参数或泥点归因。正式版本记录已经成为 manifest 业务真相，但本阶段只读取、校验和展示已有记录。
+- 当前收口不实现资源卡手动拖动，也不实现资源聚焦工具栏、资源聚焦工具侧边栏、美术编辑、音频编辑 / 替换、资源重新生成、资源替换、下一迭代版本创建入口、运行版本切换、版本回滚、运行模块扩展、测试切片、运行态消费版本、数值参数或泥点归因。正式版本记录已经成为 manifest 业务真相，但当前只读取、校验和展示已有记录。
 - 本切片不持久化资源聚焦状态、画布缩放 / 平移、搜索条件、筛选条件或当前 mode；聚焦退出时的列表上下文恢复只限当前前端会话，这些状态如需跨重启保存必须另行扩展合同，不能塞入 `game-creator-resource-layout.v1`。
 - 不修改 SpacetimeDB schema。
 - 不开放普通用户 Agent.md/Skill。
diff --git a/docs/project-memory/shared-memory/decision-log.md b/docs/project-memory/shared-memory/decision-log.md
index 0f542c3f4..8bc135b27 100644
--- a/docs/project-memory/shared-memory/decision-log.md
+++ b/docs/project-memory/shared-memory/decision-log.md
@@ -1,5 +1,13 @@
 # 决策记录
 
+## 2026-08-03 资源管理阶段七以完整 CI 与可重复界面合同收口
+
+- 背景：飞书资源管理需求的阶段零至阶段六已经分别完成资源卡禁拖、固定资源投影、中央聚焦、安全文档 / 媒体预览、依赖深度与正式版本只读模型；最后需要统一复核需求边界并用当前主分支完整门禁排除集成回归。
+- 决策：阶段七不新增平行功能，只补齐视频原生控件和资源读取策略失败空态的 AppSurface 证据，运行完整前端 / Rust / 运维 CI，并以真实 `1280×800` 浏览器测量证明页面级无溢出。开发页的真实登录门禁不得为验收绕过，工作台内部以 AppSurface 与 CSS 合同测试复核；美术编辑继续等待画板回写、血缘登记、新资源自动选中与邻近布局闭环。
+- 影响范围：`apps/ai-game-creator-shell` 资源管理测试、跨平台 CI / 运维测试脚本、工作台 PRD、AI 游戏创作实施计划和共享项目记忆；不修改 SpacetimeDB schema、manifest 业务合同或资源布局 sidecar。
+- 验证方式：根目录全量 Vitest `171` 个文件、`2155 passed / 5 skipped`；追加 lint、build、Rust workspace test / check、schema、原生壳、内容 / 编码和生产运维门禁；应用内浏览器在 `1280×800` 下 document/body client 与 scroll 尺寸相等。
+- 关联文档：`docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md`、`docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。
+
 ## 2026-08-03 正式项目版本阶段六落在 manifest 追加不可变记录
 
 - 背景：阶段一至五已经完成资源卡禁拖、固定分类投影、中央聚焦、依赖关系图和引用深度排列，但“项目版本”仍只能接受未接线的前端 read model；checkpoint、布局 sidecar 和项目 mutation revision 都不能代表正式可追溯版本。
diff --git a/docs/project-memory/shared-memory/pitfalls.md b/docs/project-memory/shared-memory/pitfalls.md
index 30f5b50dc..35d24bd12 100644
--- a/docs/project-memory/shared-memory/pitfalls.md
+++ b/docs/project-memory/shared-memory/pitfalls.md
@@ -14,6 +14,14 @@
 - 关联：相关文件、文档、提交或 Issue
 ```
 
+## Linux 生产脚本门禁不能假设本地也是 GNU userland
+
+- 现象：macOS 本地运行维护页、生产 API 部署和 Rust 产物门禁时，依次出现 `mv: illegal option -- T`、`mapfile: command not found`、`/usr/bin/cp` / `/usr/bin/chmod` 不存在，以及 `.rlib` 明明含有 `.o` 却报告“没有可扫描成员”；安全修复计划还会把 `/var/folders` 到 `/private/var/folders` 的系统别名误判为用户符号链接。
+- 原因：生产机是 Linux/GNU，而本地门禁运行在 BSD userland、Bash 3.2 和 BSD ar；测试桩硬编码 Linux 二进制路径与参数，归档解析器没有去掉 BSD 扩展成员名的尾随 NUL，路径校验也直接比较了未规范化字符串。
+- 处理：维护 marker 使用同目录临时文件加 POSIX `mv -f`；生产部署测试桩在 macOS 忠实模拟 GNU `mv/ln -T` 的“目标不是目录”语义，并按平台选择系统工具；脚本收集服务使用 Bash 3.2 可用的 `while read`；rlib 解析清理 BSD 成员名 NUL；计划文件只规范化系统临时目录别名，仍拒绝其下用户创建的符号链接组件。
+- 验证：运行 `npm run check:maintenance-page`、`npm run check:production-api-deploy`、`npm run check:server-rs-ddd`、`npm run test -- scripts/spacetime-repair-editor-canvas-resources.test.ts`，并在 Linux CI 保留同一生产脚本语义。
+- 关联：`scripts/deploy/maintenance-on.sh`、`scripts/check-maintenance-page.mjs`、`scripts/check-production-api-deploy.mjs`、`scripts/deploy/production-api-deploy.sh`、`scripts/check-module-runtime-artifact.mjs`、`scripts/spacetime-repair-editor-canvas-resources.mjs`。
+
 ## External Editor taskId 不能当作本地 manifest taskId
 
 - 现象：画布资产之间已有橙色精确引用线，但依赖任务之间没有灰色 task flow；测试用 `design-foundation` 之类字符串时正常，真实生成返回 `task-1` 后失败。
@@ -3707,6 +3715,7 @@
 - 原因：`libc::stat.st_dev` 跟随平台 `dev_t`，macOS 为有符号整数，而 `std::os::unix::fs::MetadataExt::dev()` 统一返回 `u64`；直接比较会把 Linux 的类型偶合误当成 Unix 通用契约。
 - 处理：与 Rust 标准库的 Unix `MetadataExt` 实现保持一致，先把 `st_dev / st_ino` 规范为 `u64`，再与 `metadata.dev() / metadata.ino()` 比较；设备号、inode 和文件类型三重检查均必须保留。
 - macOS 测试夹具：`std::env::temp_dir()` 可能返回 `/var/folders/...`，而 `/var` 是系统兼容符号链接。需要真实项目根的 Runtime 测试应先 canonicalize 已存在的临时根目录，再创建唯一子目录；不得为了让夹具通过而放宽生产 Runtime 的项目根及祖先符号链接拒绝规则。
+- 异步测试隔离：测试触发后台 continuation 后，必须等待对应 Agent lane 完整释放，再删除项目夹具或安装下一项全局 mock 配置；否则前一项后台任务可能抢占后一项的唯一 mock 响应，形成只在全量顺序执行时出现的跨测试污染。
 - 验证：macOS 本机运行 `cargo check --locked --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml`，并复跑 Agent DB、project owner 和 tool-plan handoff 的 Unix 相对句柄替换检测；Linux CI 继续覆盖原有安全回归。
 - 关联：`apps/ai-game-creator-shell/src-tauri/src/project.rs`、`runner.rs`、`tool_plan_handoff.rs`。
 
diff --git a/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md b/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md
index a5037f384..580ed42db 100644
--- a/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md
+++ b/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md
@@ -499,6 +499,7 @@ game-project/
 
 ## v1 验收证据矩阵
 
+- 2026-08-03 资源管理阶段七收口：阶段零至阶段六已逐项对照飞书需求、当前 PRD、实现、测试与提交证据，剩余工作仅为完整验收。AppSurface 新增原生视频 `controls + preload="metadata"` 与资源读取策略失败安全空态回归，并确认失败时右侧 Project Supervisor 对话和底部 Agent Dock 不被中央主视窗替换；全量 Vitest 为 `171` 个文件、`2155 passed / 5 skipped`。应用内浏览器固定 `1280×800` 后，`window`、document 与 body 的 client / scroll 宽高均为 `1280×800`，未出现页面级溢出；开发页真实登录门禁未被绕过，工作台内部结构继续由 AppSurface 和 CSS 合同测试作为可重复证据。最终门禁还包括 lint、build、Rust workspace test / check、SpacetimeDB schema、原生壳、内容 / 编码和生产运维检查；本地 `.env*` 不进入提交。
 - `npm run ai-game-creator-shell:check`：覆盖壳 typecheck、聊天命令单测、用户 / 开发窗口 UI 边界 smoke、主窗口命令按钮复用 `/help` 命令列表、主窗口项目摘要从 manifest / trace 派生任务完成数、ready 数、资产来源分布和最近命令且未选项目时不显示、灵感草稿只填充输入框不提交、能力按钮复用 `/capabilities`、LLM状态按钮复用 `/llm-status` 且结果回填 Agent 状态列表、聊天侧 `/agents` 汇总和单 Agent 对话的 provider / 模型 / 流式 / API Key 读取状态、开发日志面板只读读取 `.agent/logs/command.log` / `preview.log` / `agent.log`、项目状态按钮复用 `/status`、权限按钮复用 `/policy` 且策略草稿按钮只填入 `/policy-confirm project.index` / `/policy-confirm asset.register` / `/policy-confirm memory.write` / `/policy-confirm preview.start` / `/policy-confirm preview.open` / `/policy-confirm preview.stop` / `/policy-confirm agent.run_status` / `/policy-confirm conversation.read` / `/policy-confirm conversation.write`、审计按钮复用 `/audit`、资产按钮复用 `/assets` 且资产结果可一键复用 `/read`、任务按钮复用 `/tasks`、聊天侧 `/agents` 汇总每个 Agent 的当前状态、聊天侧 `/agent-conversations` 列出 Agent 对话读取命令、聊天侧 `/agent-memories` 列出 Agent 私有记忆读取命令、Trace 按钮复用 `/trace`、文件按钮复用 `/files` 且文件结果可一键复用 `/read`、索引按钮复用 `/index`、记忆 / 短期记忆 / 黑板按钮复用 `/memory long|short|blackboard`、快照按钮复用 `/checkpoint`、快照列表按钮复用 `/checkpoints` 且 checkpoint 结果可一键复用 `/diff` / `/restore`、历史按钮复用 `/history`、受限命令白名单按钮复用 `/commands` 且无需项目初始化、静态自检快捷按钮复用 `/smoke`、预览状态快捷按钮复用 `/preview-status`、主窗口运行时配置面板读写 Tauri 配置目录中的 `game-creator.config.json`、支持全局与每个 agent 单独选择 LLM Provider 且不把 API Key 写入聊天、单 Agent 对话面板可手动追加私有记忆且走 `memory.write` 策略、主窗口提供音效登记、画板音频导入和常用生成产物读取草稿入口，聊天侧 `/art` 可盘点美术素材且不直接触发平台生成或画板同步，聊天侧 `/context` 可盘点生成上下文来源且不直接读取上下文文件，聊天侧 `/timeline` 可汇总项目活动时间线且不直接读取日志或 trace 文件，聊天侧 `/artifacts` 可列出常用生成产物读取命令，聊天侧 `/run-artifacts` 可列出最近 run 产物读取命令，聊天侧 `/run-files` 可列出 Agent 运行辅助文件读取命令，聊天侧 `/logs` 可列出固定日志读取命令且不直接读取日志，聊天侧 `/brief` 只基于当前已加载的 manifest / 最近 run trace / 预览状态 / 资产数量 / 最近命令生成项目简报，聊天侧 `/goal` 只基于当前 manifest.goal / 最近 run goal / taskGraph.goal 汇总创作目标来源，提供 `/next` 或 `/agent-resume 细化目标：` 后续草稿且不直接触发 Tauri 读写、文件读取、预览启动或新增面板，聊天侧 `/mvp` 只基于当前 manifest / 最近 run trace / preview / 任务 / 资产 / 最近命令汇总本轮最小可玩范围，提供 `/run` 等后续草稿且不直接触发 Tauri 读写、文件读取、预览启动、导出或新增面板，聊天侧 `/audience` 只基于当前 manifest / 最近 run trace / preview 准备首批试玩对象和观察重点且不直接触发 Tauri 读写、预览启动、导出或继续 run，聊天侧 `/feedback` 只基于当前 manifest / 最近 run trace / preview 准备试玩反馈模板和修改说明草稿且不直接触发 Tauri 读写、预览启动或继续 run，聊天侧 `/next` 基于当前已加载的 manifest / 最近 run trace 输出下一步建议和 `/goal` / `/mvp` / `/accessibility` / `/performance` / `/tasks` / `/criteria` / `/groups` / `/budget` / `/qa` / `/changes` / `/trace` / `/run` / `/open-preview` / `/test-plan` / `/audience` / `/feedback` / `/assets` / `/art` / `/context` / `/timeline` / `/artifacts` / `/run-artifacts` / `/run-files` / `/logs` / `/agent-resume ` 等安全命令草稿方向，提供一个首选草稿且不直接触发 Tauri 读写、预览启动或文件读取，聊天侧 `/capabilities` 展示标准 Agent 能力清单且不打开开发面板、聊天侧 `/audit` 从 manifest / 本地文件 / `.agent/run.latest.json` 分别汇总用户面、6 组任务配置、6 组协作证据、任务编排、loop、记忆、本地产物、HTTP 预览、画板回流和权限日志证据且不打开开发面板；未生成 `.agent/run.latest.json` 前，`/audit` 只能标记任务配置通过，不能把 6 组协作证据误判为通过；trace 已存在但状态为 `failed`、`needs-revision`、`running`、`max-passes-exhausted` 或缺少 `Evaluator passed` 步骤时，`/audit` 不能把 loop 误判为通过。聊天侧 `/llm-status` 只显示 base_url / model / API Key 已读取状态且不泄露密钥本体、聊天侧长期记忆查看 / 追加 / 覆盖 / 删除的授权本地项目路径、上传资产写入后的 manifest 刷新和 `/assets` 聊天可见性、`/smoke` 聊天侧确认后只通过授权本地项目路径执行白名单 `game.static_smoke`、`/run` 聊天侧确认后通过授权本地项目路径执行 `game.static_smoke`、启动 `127.0.0.1` 本地预览并切换客户端运行视图、`/preview` 聊天侧确认后通过授权本地项目路径启动 `127.0.0.1` 本地预览并切换客户端运行视图、`/status` 聊天侧项目 / 任务 / 资产 / 预览 / 最近命令汇总、`/files` 聊天侧本地项目文件列表、`/read` 聊天侧文件读取的授权本地项目路径、`/tasks` 聊天侧任务拆分与下一步专业组展示的授权本地项目路径、聊天确认生成后实时展示 Planner / Orchestrator / 角色 brief / Generator / Evaluator / 写盘 / 自检进度，并自动读取 `.agent/run.latest.json` 在普通聊天消息里展示 Run、LLM 对话、loop 轮次、工具调用、active / carry-over 任务、返工焦点、编排轮次、最近步骤、画板同步建议命令和本地产物快照、`/trace` 聊天侧读取 `.agent/run.latest.json` 并展示 loop 轮次 / active 任务 / 返工路线 / dependency waves 的授权本地项目路径、`platform-agent` 编排测试、共享契约测试、Tauri 本地能力测试和无密钥本地 provider 端到端 smoke；用于证明独立 App、真实 LLM-compatible loop、本地落盘、自检和 HTTP 预览闭环，并覆盖 loop 跑满 3 轮失败时不会写入最终游戏产物。
 - V1.17 单 Agent 持久计划验收：Rust 定向用例覆盖 native function 显式 `planUpdate`、文本 JSON omission 兼容、输入上限、单调 revision、外层 failed / budget-exhausted 保留最后可信进度、终态保留、工具 action 下标零推进、未完成步骤阻止 final、损坏状态失败关闭、context bundle v3/v2 恢复、finalization v2 计划快照与 assistant 已落盘后的 state 丢失恢复，以及 thinking / legacy plan / repair 公共审计零正文；`appSurface.test.ts` 覆盖开发 UI 刷新后完整 8 步仍在，以及普通用户 Supervisor 只显示完成数、当前步骤、等待、下一步和协作数量。2026-07-16 正式 `openai_chat / gpt-5.5` 的 `steer-runner-kill` suite 已证明 Runner boot 切换和 same-run steer 后 Agent/Session/run 不变、终态步骤不丢、revision 不回退、旧动作零执行、副作用零重放、唯一 assistant/completed 与零正文/密钥/路径公共泄漏，当前门禁状态为 PASS。
 - V1.18 单 Agent 持久 Goal mode 验收：Rust/Runner 定向用例覆盖 Goal CAS 生命周期、当前 Session/run 隔离、Provider 中断安全边界、paused 重启不自启、同 run resume、旧 cancel tombstone 清理、当前 v5 context、v5 pending action 的 Goal 快照门禁、旧 schema 失败关闭、Goal edit 后自动/确认动作转 `blocked` 并重规划、finalization v3 以及 assistant 后 Runtime/Goal completed 顺序；`appSurface.test.ts` 覆盖 `执行 / 聊天 / 目标`、独立 Goal 弹层、完整控制动作和正式用户界面隔离。2026-07-16 真实 `openai_chat / gpt-5.5` 已完成 revision 1 -> 2、旧动作 blocked 且零执行、真实失败后 patchset 修复、pause、Runner pidfd 强杀换 boot、重启零推进、显式同 run resume；最终代码快照复跑有 11 组 Provider lifecycle 闭合、计划 revision 11 八步完成、唯一 assistant、零副作用重放和零 Goal/密钥/路径公共泄漏，门禁状态为 PASS。
diff --git a/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md b/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md
index cf62e1db0..fae019c5f 100644
--- a/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md
+++ b/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md
@@ -607,7 +607,7 @@ Nginx 与 Pingora 在维护 marker 存在时对内网来源绕过整站维护闸
 
 该规则只绕过网关维护响应，不会自动拉起 api-server、SpacetimeDB 或其它已停止的服务。人工执行 `maintenance-on.sh` 且后端仍运行时，可以从内网继续访问整站和修改后台数据；`pause-after-stdb` 会停止旧 API/controller/worker，在 API 被停期间静态页面可能仍可加载，但普通 API 与 `/admin/api/**` 仍不可用。验证使用 `npm run check:nginx-spa-routes`、`npm run check:pingora-route-parity`、`cargo test -p pingora-gateway --manifest-path server-rs/Cargo.toml`、`npm run check:pingora-gateway-smoke` 和 `npm run check:production-ops`，不要在 live 机器上为测试临时创建维护 marker。
 
-版本化默认维护页固定为 `public/maintenance.html`，使用 `public/branding/taonier-maintenance-page.png` 作为品牌视觉，只允许保存无日期、无具体时段的通用文案；正常 Web 构建由 Vite 复制到发布包根目录的 `web/maintenance.html`，并由 `check-maintenance-page.mjs` 在打包前拒绝“今天 / 今晚”、具体日期或 `HH:MM` 等临时公告。计划内停服的临时公告必须放在 release 外文件中，通过 `/opt/genarrative/current/scripts/deploy/maintenance-on.sh --page-file <公告HTML> <维护原因>` 原子安装到 `/var/lib/genarrative/maintenance/page.html`。Nginx 与 Pingora 在该文件存在时优先返回它，缺失时回退当前 Web 制品的默认维护页；同一维护窗口内 Stdb / API 的后续 `maintenance-on.sh` 调用保留已安装公告，`maintenance-off.sh` 同时删除 marker 和运行态公告，避免下次维护复活旧内容。公告启用后同时用 `genarrative.world` 与 `www.genarrative.world` 的真实 HTTPS 响应校验 `503` 和公告正文。
+版本化默认维护页固定为 `public/maintenance.html`，使用 `public/branding/taonier-maintenance-page.png` 作为品牌视觉，只允许保存无日期、无具体时段的通用文案；正常 Web 构建由 Vite 复制到发布包根目录的 `web/maintenance.html`，并由 `check-maintenance-page.mjs` 在打包前拒绝“今天 / 今晚”、具体日期或 `HH:MM` 等临时公告。计划内停服的临时公告必须放在 release 外文件中，通过 `/opt/genarrative/current/scripts/deploy/maintenance-on.sh --page-file <公告HTML> <维护原因>` 原子安装到 `/var/lib/genarrative/maintenance/page.html`；公告页和 marker 都使用同目录临时文件加 POSIX 兼容 `mv -f` 的原子替换，不得依赖 GNU `mv -T`，确保 Linux 生产机与 macOS/BSD 本地门禁语义一致。Nginx 与 Pingora 在该文件存在时优先返回它，缺失时回退当前 Web 制品的默认维护页；同一维护窗口内 Stdb / API 的后续 `maintenance-on.sh` 调用保留已安装公告，`maintenance-off.sh` 同时删除 marker 和运行态公告，避免下次维护复活旧内容。公告启用后同时用 `genarrative.world` 与 `www.genarrative.world` 的真实 HTTPS 响应校验 `503` 和公告正文。
 
 生产 Jenkins 的 `Pipeline script from SCM` 由 Jenkins controller 读取 Jenkinsfile。所有生产 Job 的 SCM URL，以及 Jenkinsfile 内部在 Jenkins Built-In Node 执行的源码准备，统一使用 `ssh://git@127.0.0.1:2222/GenarrativeAI/Genarrative.git`，并显式传入 Jenkins SSH 凭据 `genarrative-local-gitea-ssh`；不再配置局域网 IP、`https://git.genarrative.world/...` 公网 fallback 或 `http://genarrative-station/git/GenarrativeAI/Genarrative.git`。所有 `GitSCM checkout` 都必须保留单分支 refspec、`shallow=true`、`depth=1`、`noTags=true` 与 `honorRefspec=true`。API / Web / Stdb 发布类流水线不在目标机器 checkout Git，统一执行上游构建归档里的部署脚本；Server-Provision 和数据库导入导出也由带 `linux && genarrative-build` 标签的 Jenkins Built-In Node 先 checkout 并 stash 所需脚本，再交给目标 dev / release agent，避免目标机把 `127.0.0.1` 误解为远端 Gitea 或让产物 commit 与执行脚本漂移。
 
diff --git a/scripts/check-maintenance-page.mjs b/scripts/check-maintenance-page.mjs
index d82e1f2e4..2c199cf4f 100644
--- a/scripts/check-maintenance-page.mjs
+++ b/scripts/check-maintenance-page.mjs
@@ -68,11 +68,19 @@ function validateRuntimePageLifecycle() {
   const sourcePageFile = path.join(tempRoot, 'announcement.html');
   const onScript = path.join(repoRoot, 'scripts/deploy/maintenance-on.sh');
   const offScript = path.join(repoRoot, 'scripts/deploy/maintenance-off.sh');
+  const onScriptSource = readFileSync(onScript, 'utf8');
   const env = {
     GENARRATIVE_MAINTENANCE_FILE: markerFile,
     GENARRATIVE_MAINTENANCE_PAGE_FILE: runtimePageFile,
   };
 
+  if (!onScriptSource.includes('replace_file_atomically')) {
+    fail('maintenance-on 必须通过统一 helper 原子替换公告页和 marker。');
+  }
+  if (/\bmv\s+-[^\s]*T\b/u.test(onScriptSource)) {
+    fail('maintenance-on 不得使用 GNU mv 专属的 -T 参数。');
+  }
+
   try {
     const announcement = '<!doctype html><title>planned maintenance</title>\n';
     writeFileSync(sourcePageFile, announcement);
diff --git a/scripts/check-module-runtime-artifact.mjs b/scripts/check-module-runtime-artifact.mjs
index 00992cbab..ad3ea0dc4 100644
--- a/scripts/check-module-runtime-artifact.mjs
+++ b/scripts/check-module-runtime-artifact.mjs
@@ -165,7 +165,8 @@ function parseArchiveObjectMembers(artifact) {
       }
       memberName = artifact
         .subarray(contentStart, contentStart + nameLength)
-        .toString('utf8');
+        .toString('utf8')
+        .replace(/\0+$/u, '');
       contentStart += nameLength;
     }
 
diff --git a/scripts/check-production-api-deploy.mjs b/scripts/check-production-api-deploy.mjs
index efeb4aa84..4532c6351 100644
--- a/scripts/check-production-api-deploy.mjs
+++ b/scripts/check-production-api-deploy.mjs
@@ -15,6 +15,22 @@ import { tmpdir } from 'node:os';
 import path from 'node:path';
 
 const failures = [];
+const systemCpPath = ['/usr/bin/cp', '/bin/cp'].find((candidate) =>
+  existsSync(candidate),
+);
+const systemMvPath = ['/usr/bin/mv', '/bin/mv'].find((candidate) =>
+  existsSync(candidate),
+);
+const systemLnPath = ['/usr/bin/ln', '/bin/ln'].find((candidate) =>
+  existsSync(candidate),
+);
+const systemChmodPath = ['/usr/bin/chmod', '/bin/chmod'].find((candidate) =>
+  existsSync(candidate),
+);
+const systemStatModeCommand =
+  process.platform === 'darwin'
+    ? '/usr/bin/stat -f %Lp'
+    : '/usr/bin/stat -c %a --';
 const tmpRoot = mkdtempSync(
   path.join(tmpdir(), 'genarrative-production-api-deploy-'),
 );
@@ -2421,7 +2437,7 @@ function prepareFixture(name) {
     [
       '#!/usr/bin/env bash',
       'set -euo pipefail',
-      '/usr/bin/cp "$@"',
+      `${shellQuote(systemCpPath ?? 'cp')} "$@"`,
       'if [[ "${FAKE_CREATE_RELEASE_DURING_COPY:-false}" == "true" ]]; then',
       '  marker="${FAKE_RELEASE_ROOT}/.${FAKE_RELEASE_VERSION}.race-created"',
       '  if [[ ! -e "${marker}" ]]; then',
@@ -2434,6 +2450,40 @@ function prepareFixture(name) {
     ].join('\n'),
     'utf8',
   );
+  writeFileSync(
+    path.join(fakeBin, 'mv'),
+    [
+      '#!/usr/bin/env bash',
+      'set -euo pipefail',
+      'if [[ "${1:-}" == "-T" ]]; then',
+      '  shift',
+      '  if [[ "$#" -ne 2 || ( -d "$2" && ! -L "$2" ) ]]; then',
+      '    exit 1',
+      '  fi',
+      `  exec ${shellQuote(systemMvPath ?? 'mv')} "$1" "$2"`,
+      'fi',
+      `exec ${shellQuote(systemMvPath ?? 'mv')} "$@"`,
+      '',
+    ].join('\n'),
+    'utf8',
+  );
+  writeFileSync(
+    path.join(fakeBin, 'ln'),
+    [
+      '#!/usr/bin/env bash',
+      'set -euo pipefail',
+      'if [[ "${1:-}" == "-sfnT" ]]; then',
+      '  shift',
+      '  if [[ "$#" -ne 2 || ( -d "$2" && ! -L "$2" ) ]]; then',
+      '    exit 1',
+      '  fi',
+      `  exec ${shellQuote(systemLnPath ?? 'ln')} -sfn "$1" "$2"`,
+      'fi',
+      `exec ${shellQuote(systemLnPath ?? 'ln')} "$@"`,
+      '',
+    ].join('\n'),
+    'utf8',
+  );
   writeFileSync(
     path.join(fakeBin, 'install'),
     [
@@ -2479,15 +2529,15 @@ function prepareFixture(name) {
       '  IFS="|" read -r -a env_files <<< "${FAKE_SUDO_ENV_FILES}"',
       '  modes=()',
       '  for env_file in "${env_files[@]}"; do',
-      '    modes+=("$(/usr/bin/stat -c %a -- "${env_file}")")',
-      '    /usr/bin/chmod u+rw -- "${env_file}"',
+      `    modes+=("$(${systemStatModeCommand} "\${env_file}")")`,
+      `    ${shellQuote(systemChmodPath ?? 'chmod')} u+rw "\${env_file}"`,
       '  done',
       '  set +e',
       '  "$@"',
       '  status=$?',
       '  set -e',
       '  for index in "${!env_files[@]}"; do',
-      '    /usr/bin/chmod "${modes[$index]}" -- "${env_files[$index]}"',
+      `    ${shellQuote(systemChmodPath ?? 'chmod')} "\${modes[$index]}" "\${env_files[$index]}"`,
       '  done',
       '  exit "${status}"',
       'fi',
@@ -2501,6 +2551,8 @@ function prepareFixture(name) {
   chmodExecutable(path.join(fakeBin, 'sleep'));
   chmodExecutable(path.join(fakeBin, 'stat'));
   chmodExecutable(path.join(fakeBin, 'cp'));
+  chmodExecutable(path.join(fakeBin, 'mv'));
+  chmodExecutable(path.join(fakeBin, 'ln'));
   chmodExecutable(path.join(fakeBin, 'install'));
   chmodExecutable(path.join(fakeBin, 'sudo'));
 
diff --git a/scripts/deploy/maintenance-on.sh b/scripts/deploy/maintenance-on.sh
index 66df9ddb4..9948b029e 100644
--- a/scripts/deploy/maintenance-on.sh
+++ b/scripts/deploy/maintenance-on.sh
@@ -7,6 +7,19 @@ MAINTENANCE_PAGE_FILE="${GENARRATIVE_MAINTENANCE_PAGE_FILE:-/var/lib/genarrative
 PAGE_SOURCE=""
 REASON_PARTS=()
 
+replace_file_atomically() {
+  local source_file="$1"
+  local target_file="$2"
+
+  if [[ -d "${target_file}" && ! -L "${target_file}" ]]; then
+    echo "[maintenance] 原子替换目标不能是目录: ${target_file}" >&2
+    exit 1
+  fi
+  # 源文件与目标文件位于同一目录，POSIX rename 语义即可保证原子替换。
+  # 不使用 GNU mv 专属的 -T，确保 macOS/BSD 本地门禁也能执行。
+  mv -f "${source_file}" "${target_file}"
+}
+
 while [[ $# -gt 0 ]]; do
   case "$1" in
     --page-file)
@@ -41,7 +54,7 @@ if [[ -n "${PAGE_SOURCE}" ]]; then
   page_temp="$(mktemp "${MAINTENANCE_PAGE_FILE}.tmp.XXXXXX")"
   trap 'rm -f "${page_temp:-}" "${marker_temp:-}"' EXIT
   install -m 0644 -- "${PAGE_SOURCE}" "${page_temp}"
-  mv -fT -- "${page_temp}" "${MAINTENANCE_PAGE_FILE}"
+  replace_file_atomically "${page_temp}" "${MAINTENANCE_PAGE_FILE}"
   page_temp=""
   echo "[maintenance] 已安装本次运行态公告页: ${MAINTENANCE_PAGE_FILE}"
 elif [[ ! -f "${MAINTENANCE_FILE}" && ( -e "${MAINTENANCE_PAGE_FILE}" || -L "${MAINTENANCE_PAGE_FILE}" ) ]]; then
@@ -55,7 +68,7 @@ marker_temp="$(mktemp "${MAINTENANCE_FILE}.tmp.XXXXXX")"
 } >"${marker_temp}"
 
 chmod 0644 "${marker_temp}"
-mv -fT -- "${marker_temp}" "${MAINTENANCE_FILE}"
+replace_file_atomically "${marker_temp}" "${MAINTENANCE_FILE}"
 marker_temp=""
 trap - EXIT
 echo "[maintenance] 已进入维护模式: ${MAINTENANCE_FILE}"
diff --git a/scripts/deploy/production-api-deploy.sh b/scripts/deploy/production-api-deploy.sh
index b3713bbab..5919fa220 100644
--- a/scripts/deploy/production-api-deploy.sh
+++ b/scripts/deploy/production-api-deploy.sh
@@ -892,7 +892,9 @@ ensure_default_worker_service() {
     return 1
   fi
 
-  mapfile -t services < <(list_worker_services "${pattern}")
+  while IFS= read -r service; do
+    services+=("${service}")
+  done < <(list_worker_services "${pattern}")
   if [[ "${#services[@]}" -gt 0 ]]; then
     return 0
   fi
@@ -1033,7 +1035,9 @@ restart_worker_services() {
   fi
 
   ensure_default_worker_service "${pattern}"
-  mapfile -t services < <(list_worker_services "${pattern}")
+  while IFS= read -r service; do
+    services+=("${service}")
+  done < <(list_worker_services "${pattern}")
   if [[ "${#services[@]}" -eq 0 ]]; then
     echo "[production-api-deploy] 未发现已加载的外部生成 worker 单元: ${pattern}" >&2
     return 1
@@ -1052,7 +1056,9 @@ wait_for_worker_services() {
     return 0
   fi
 
-  mapfile -t services < <(list_worker_services "${pattern}")
+  while IFS= read -r service; do
+    services+=("${service}")
+  done < <(list_worker_services "${pattern}")
   if [[ "${#services[@]}" -eq 0 ]]; then
     echo "[production-api-deploy] 外部生成 worker 单元不存在，发布失败: ${pattern}" >&2
     return 1
diff --git a/scripts/spacetime-repair-editor-canvas-resources.mjs b/scripts/spacetime-repair-editor-canvas-resources.mjs
index a8967d9c7..35562225c 100644
--- a/scripts/spacetime-repair-editor-canvas-resources.mjs
+++ b/scripts/spacetime-repair-editor-canvas-resources.mjs
@@ -2,6 +2,7 @@
 
 import { createHash } from 'node:crypto';
 import { lstat, readFile, realpath } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
@@ -85,15 +86,20 @@ export async function readRepairPlan(planFile, { repoRoot = REPO_ROOT } = {}) {
   const resolvedPath = path.resolve(planFile);
   const resolvedRepoRoot = path.resolve(repoRoot);
   let canonicalPath;
+  let canonicalRepoRoot;
   try {
     canonicalPath = await realpath(resolvedPath);
+    canonicalRepoRoot = await realpath(resolvedRepoRoot);
   } catch {
     throw new Error('--plan-file 无法解析或不存在。');
   }
-  if (canonicalPath !== resolvedPath) {
+  const pathWithoutSystemTempAlias = await normalizeSystemTempAlias(
+    resolvedPath,
+  );
+  if (canonicalPath !== pathWithoutSystemTempAlias) {
     throw new Error('--plan-file 路径链不能包含符号链接。');
   }
-  if (isPathInside(canonicalPath, resolvedRepoRoot)) {
+  if (isPathInside(canonicalPath, canonicalRepoRoot)) {
     throw new Error('--plan-file 必须位于仓库外，避免真实 ID 进入工作区。');
   }
 
@@ -539,6 +545,16 @@ function isPathInside(candidate, root) {
   );
 }
 
+async function normalizeSystemTempAlias(candidate) {
+  const resolvedTempRoot = path.resolve(tmpdir());
+  if (!isPathInside(candidate, resolvedTempRoot)) {
+    return candidate;
+  }
+
+  const canonicalTempRoot = await realpath(resolvedTempRoot);
+  return path.join(canonicalTempRoot, path.relative(resolvedTempRoot, candidate));
+}
+
 function assertPlainObject(value, label) {
   if (!value || typeof value !== 'object' || Array.isArray(value)) {
     throw new Error(`${label} 必须是对象。`);
-- 
2.52.0


From 6d8c7ae496a5e77ccdf475af633913382af118e2 Mon Sep 17 00:00:00 2001
From: menghao <mh18530625731@163.com>
Date: Tue, 4 Aug 2026 10:38:28 +0800
Subject: [PATCH 16/27] =?UTF-8?q?=E4=BF=AE=E5=A4=8D=E5=89=8D=E7=AB=AF?=
 =?UTF-8?q?=E5=BC=82=E6=AD=A5=E8=AF=BB=E5=8F=96=E5=8D=B8=E8=BD=BD=E7=AB=9E?=
 =?UTF-8?q?=E6=80=81?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

未登录画布不再触发受保护的钱包刷新
充值中心读取在换代与卸载时中止并失效
补充卸载取消回归测试与共享排障经验
---
 docs/project-memory/shared-memory/pitfalls.md |  7 ++
 .../image-editor/ImageCanvasEditorView.tsx    |  3 +
 ...sePlatformProfileCenterController.test.tsx | 82 +++++++++++++++++++
 .../usePlatformProfileCenterController.ts     | 30 ++++++-
 4 files changed, 119 insertions(+), 3 deletions(-)
 create mode 100644 src/components/platform-entry/usePlatformProfileCenterController.test.tsx

diff --git a/docs/project-memory/shared-memory/pitfalls.md b/docs/project-memory/shared-memory/pitfalls.md
index 35d24bd12..85a6cb48e 100644
--- a/docs/project-memory/shared-memory/pitfalls.md
+++ b/docs/project-memory/shared-memory/pitfalls.md
@@ -4083,3 +4083,10 @@
 
 - 现象：可选 server 已成功连接，但返回超限 schema、重复 tool identity 或要求未支持 task-mode 时，整个 MCP catalog 和本轮 Agent planning 一起失败。
 - 处理：连接、tools/list、工具归一化与聚合容量都使用同一 required / optional 边界。optional 将该 server 投影为 `connected=false + error + tool_count=0`，required 保持失败关闭；被包入 `action.input` 的 `$ref` 只重定位当前 document 根的 `#` / `#/...` JSON Pointer，命名 anchor、外部 URI 与带 `$id` 的 schema resource 内 fragment 不得改写。
+
+## React 异步读取必须在组件卸载时中止并失效（2026-08-04）
+
+- 现象：单个 Vitest 文件全部通过，全量 CI 却在 jsdom 环境销毁后出现 `ReferenceError: window is not defined`；栈指向请求 Promise 的 `finally` 中调用 React `setState`。
+- 原因：测试触发了与断言无关的账户读取，较快环境中请求会在用例结束前失败，较慢 CI 中请求延迟到组件和 jsdom 均已销毁后才收束。仅用 revision 丢弃旧请求而不在卸载时推进 revision，最后一个在途请求仍会被误认作当前请求。
+- 处理：调用方在未认证时不得启动受保护的钱包刷新；可取消的读取要为每轮分配 `AbortController`，新读取先失效并中止旧读取，组件卸载时同时推进 revision、abort 当前请求并清空句柄。所有 `then / catch / finally` 在更新状态前都要检查 signal 与 revision。
+- 验证：定向测试覆盖卸载后请求 signal 已中止；同时复跑触发钱包刷新回调的画布生成集成测试和完整前端测试，不能以单文件偶然快速收束代替全量验证。
diff --git a/src/components/image-editor/ImageCanvasEditorView.tsx b/src/components/image-editor/ImageCanvasEditorView.tsx
index f608fe9c1..4e6d23d72 100644
--- a/src/components/image-editor/ImageCanvasEditorView.tsx
+++ b/src/components/image-editor/ImageCanvasEditorView.tsx
@@ -544,6 +544,9 @@ export function ImageCanvasEditorView({
     currentUser: authUi?.user ?? null,
   });
   const refreshEditorWalletState = useCallback(() => {
+    if (!authUiRef.current?.canAccessProtectedData || !authUiRef.current.user) {
+      return;
+    }
     refreshEditorWalletBalance();
     loadRechargeCenter();
   }, [loadRechargeCenter, refreshEditorWalletBalance]);
diff --git a/src/components/platform-entry/usePlatformProfileCenterController.test.tsx b/src/components/platform-entry/usePlatformProfileCenterController.test.tsx
new file mode 100644
index 000000000..c57737032
--- /dev/null
+++ b/src/components/platform-entry/usePlatformProfileCenterController.test.tsx
@@ -0,0 +1,82 @@
+/* @vitest-environment jsdom */
+
+import { act, renderHook } from '@testing-library/react';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import type { ProfileRechargeCenterResponse } from '../../../packages/shared/src/contracts/runtime';
+import { usePlatformProfileCenterController } from './usePlatformProfileCenterController';
+
+const getPlatformProfileRechargeCenterMock = vi.hoisted(() => vi.fn());
+
+vi.mock('../../services/platform-entry/platformProfileClient', async () => {
+  const actual = await vi.importActual<
+    typeof import('../../services/platform-entry/platformProfileClient')
+  >('../../services/platform-entry/platformProfileClient');
+  return {
+    ...actual,
+    getPlatformProfileRechargeCenter: getPlatformProfileRechargeCenterMock,
+  };
+});
+
+const rechargeCenter: ProfileRechargeCenterResponse = {
+  walletBalance: 100,
+  mudPointBalance: {
+    totalPoints: 100,
+    permanentPoints: 100,
+    limitedPoints: 0,
+    limitedExpiresAt: null,
+    dailyFreePoints: 0,
+    dailyFreeResetPoints: 0,
+    dailyFreeResetsAt: null,
+  },
+  membership: {
+    status: 'normal',
+    tier: 'normal',
+    startedAt: null,
+    expiresAt: null,
+    updatedAt: null,
+    cycleStartedAt: null,
+    cycleResetsAt: null,
+    cycleGrantedPoints: 0,
+    cycleRemainingPoints: 0,
+    cyclePeriodDays: 30,
+  },
+  pointProducts: [],
+  membershipProducts: [],
+  benefits: [],
+  latestOrder: null,
+  hasPointsRecharged: false,
+};
+
+describe('usePlatformProfileCenterController', () => {
+  afterEach(() => {
+    getPlatformProfileRechargeCenterMock.mockReset();
+  });
+
+  it('aborts an unfinished recharge center read when the consumer unmounts', async () => {
+    let resolveRechargeCenter!: (center: ProfileRechargeCenterResponse) => void;
+    const pendingRead = new Promise<ProfileRechargeCenterResponse>((resolve) => {
+      resolveRechargeCenter = resolve;
+    });
+    getPlatformProfileRechargeCenterMock.mockReturnValue(pendingRead);
+    const { result, unmount } = renderHook(() =>
+      usePlatformProfileCenterController({
+        activeTab: 'editor-canvas',
+        isAuthenticated: false,
+        showRechargeEntry: true,
+        requestLogin: vi.fn(),
+        currentUser: null,
+      }),
+    );
+
+    act(() => result.current.loadRechargeCenter());
+    const requestOptions = getPlatformProfileRechargeCenterMock.mock.calls[0]?.[0];
+    expect(requestOptions?.signal.aborted).toBe(false);
+
+    unmount();
+    expect(requestOptions?.signal.aborted).toBe(true);
+
+    resolveRechargeCenter(rechargeCenter);
+    await pendingRead;
+  });
+});
diff --git a/src/components/platform-entry/usePlatformProfileCenterController.ts b/src/components/platform-entry/usePlatformProfileCenterController.ts
index 94c8d2f71..a3a0c966e 100644
--- a/src/components/platform-entry/usePlatformProfileCenterController.ts
+++ b/src/components/platform-entry/usePlatformProfileCenterController.ts
@@ -354,6 +354,16 @@ export function usePlatformProfileCenterController({
   const pendingWechatRechargeOrderIdRef = useRef<string | null>(null);
   const confirmingWechatRechargeOrderIdRef = useRef<string | null>(null);
   const rechargeCenterReadRevisionRef = useRef(0);
+  const rechargeCenterReadAbortControllerRef =
+    useRef<AbortController | null>(null);
+
+  useEffect(() => {
+    return () => {
+      rechargeCenterReadRevisionRef.current += 1;
+      rechargeCenterReadAbortControllerRef.current?.abort();
+      rechargeCenterReadAbortControllerRef.current = null;
+    };
+  }, []);
 
   // 中文注释：支持带邀请码 query 的直达场景，登录成功后自动打开兑换面板并复用同一套输入状态。
   useEffect(() => {
@@ -398,6 +408,8 @@ export function usePlatformProfileCenterController({
   const applyRechargeCenter = useCallback(
     (center: ProfileRechargeCenterResponse) => {
       rechargeCenterReadRevisionRef.current += 1;
+      rechargeCenterReadAbortControllerRef.current?.abort();
+      rechargeCenterReadAbortControllerRef.current = null;
       setIsLoadingRechargeCenter(false);
       setRechargeError(null);
       setRechargeCenter(center);
@@ -407,16 +419,25 @@ export function usePlatformProfileCenterController({
 
   const loadRechargeCenter = useCallback(() => {
     const revision = ++rechargeCenterReadRevisionRef.current;
+    rechargeCenterReadAbortControllerRef.current?.abort();
+    const abortController = new AbortController();
+    rechargeCenterReadAbortControllerRef.current = abortController;
     setRechargeError(null);
     setIsLoadingRechargeCenter(true);
-    void getPlatformProfileRechargeCenter()
+    void getPlatformProfileRechargeCenter({ signal: abortController.signal })
       .then((center) => {
-        if (revision === rechargeCenterReadRevisionRef.current) {
+        if (
+          !abortController.signal.aborted &&
+          revision === rechargeCenterReadRevisionRef.current
+        ) {
           setRechargeCenter(center);
         }
       })
       .catch((error: unknown) => {
-        if (revision !== rechargeCenterReadRevisionRef.current) {
+        if (
+          abortController.signal.aborted ||
+          revision !== rechargeCenterReadRevisionRef.current
+        ) {
           return;
         }
         setRechargeCenter(null);
@@ -425,6 +446,9 @@ export function usePlatformProfileCenterController({
         );
       })
       .finally(() => {
+        if (rechargeCenterReadAbortControllerRef.current === abortController) {
+          rechargeCenterReadAbortControllerRef.current = null;
+        }
         if (revision === rechargeCenterReadRevisionRef.current) {
           setIsLoadingRechargeCenter(false);
         }
-- 
2.52.0


From ab16c87c5da29ac7d638a905c8af323c70c67971 Mon Sep 17 00:00:00 2001
From: menghao <mh18530625731@163.com>
Date: Tue, 4 Aug 2026 11:20:58 +0800
Subject: [PATCH 17/27] =?UTF-8?q?=E8=B0=83=E6=95=B4=E8=B5=84=E6=BA=90?=
 =?UTF-8?q?=E4=BE=9D=E8=B5=96=E8=A7=86=E5=9B=BE=E8=BF=9E=E7=BA=BF=E8=A7=84?=
 =?UTF-8?q?=E5=88=99?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

限制任务虚线仅在同资源类型分区内渲染
调亮精确资源引用橙线并保持持续展示
取消资源点击后的依赖高亮与无关连线弱化
补充依赖图单元测试与工作台集成测试
同步更新项目开发工作台 PRD
---
 apps/ai-game-creator-shell/src/styles.css     |  36 +--
 .../ResourceDependencyOverlay.tsx             | 284 ++++++++++--------
 .../src/view/project-development/index.tsx    |  26 +-
 .../tests/ResourceDependencyOverlay.test.ts   | 113 ++++---
 .../appSurface/project-development.suite.ts   |  23 +-
 ...AI游戏创作】项目开发工作台PRD-2026-07-20.md |  18 +-
 6 files changed, 269 insertions(+), 231 deletions(-)

diff --git a/apps/ai-game-creator-shell/src/styles.css b/apps/ai-game-creator-shell/src/styles.css
index 78d72898d..d80e496b0 100644
--- a/apps/ai-game-creator-shell/src/styles.css
+++ b/apps/ai-game-creator-shell/src/styles.css
@@ -3905,15 +3905,12 @@ iframe.preview-frame {
   stroke-linecap: round;
   stroke-linejoin: round;
   vector-effect: non-scaling-stroke;
-  transition:
-    opacity 140ms ease,
-    stroke-width 140ms ease;
 }
 
 .game-resource-dependency-edge--reference {
-  stroke: #d96f3d;
-  stroke-width: 2.25px;
-  opacity: 0.94;
+  stroke: #f28a52;
+  stroke-width: 2.4px;
+  opacity: 1;
 }
 
 .game-resource-dependency-edge--task path {
@@ -3931,35 +3928,13 @@ iframe.preview-frame {
   opacity: 0.72;
 }
 
-.game-resource-dependency-edge.is-highlighted {
-  opacity: 1;
-}
-
-.game-resource-dependency-edge--reference.is-highlighted {
-  stroke-width: 3px;
-}
-
-.game-resource-dependency-edge--task.is-highlighted path {
-  opacity: 1;
-  stroke-width: 2px;
-}
-
-.game-resource-dependency-edge--task.is-highlighted
-  .game-resource-dependency-trunk {
-  stroke-width: 2.4px;
-}
-
-.game-resource-dependency-edge.is-dimmed {
-  opacity: 0.14;
-}
-
 .game-resource-dependency-edge.is-cyclic,
 .game-resource-dependency-edge.is-cyclic path {
   stroke-dashoffset: 4;
 }
 
 .game-resource-dependency-marker--reference path {
-  fill: #d96f3d;
+  fill: #f28a52;
   stroke-linejoin: round;
 }
 
@@ -4056,9 +4031,6 @@ iframe.preview-frame {
   box-shadow: 0 8px 22px rgb(195 105 62 / 15%);
 }
 
-.game-resource-card.is-relation-upstream,
-.game-resource-card.is-relation-downstream,
-.game-resource-card.is-relation-both,
 .game-resource-card.is-relation-version-binding {
   border-color: #d87342;
   box-shadow:
diff --git a/apps/ai-game-creator-shell/src/view/project-development/ResourceDependencyOverlay.tsx b/apps/ai-game-creator-shell/src/view/project-development/ResourceDependencyOverlay.tsx
index 19ccd9bbb..38a51a13c 100644
--- a/apps/ai-game-creator-shell/src/view/project-development/ResourceDependencyOverlay.tsx
+++ b/apps/ai-game-creator-shell/src/view/project-development/ResourceDependencyOverlay.tsx
@@ -19,7 +19,6 @@ import {
 } from './resourceCanvasLayoutModel';
 import {
   type ProjectResourceGraph,
-  projectResourceGraphNeighbors,
   type ProjectResourceReferenceEdge,
   type ProjectResourceTaskFlow,
 } from './resourceDependencyGraphModel';
@@ -44,7 +43,6 @@ export type ResourceDependencyOverlayProps = {
   graph: ProjectResourceGraph;
   positions: readonly ProjectResourceCanvasPosition[];
   visibleResourceIds: ReadonlySet<string>;
-  selectedResourceId: string | null;
 };
 
 export type ResourceDependencyOverlayHandle = {
@@ -58,21 +56,27 @@ type TaskFlowPathRefs = {
   trunk: SVGPathElement | null;
 };
 
+type TaskFlowSectionGeometry = NonNullable<
+  ReturnType<typeof taskFlowGeometry>
+> & {
+  section: ProjectResourceCanvasSection;
+};
+
 const SECTION_SELECTOR = '[data-resource-section-plane]';
 const TASK_FLOW_HUB_GAP = 20;
 const CONNECTION_MAX_HANDLE = 180;
 const TASK_FLOW_BRANCH_MAX_HANDLE = 96;
 const SELF_REFERENCE_LOOP_WIDTH = 56;
 const SELF_REFERENCE_LOOP_ANCHOR_OFFSET = 18;
+const RESOURCE_SECTIONS: readonly ProjectResourceCanvasSection[] = [
+  'document',
+  'version',
+  'art',
+  'audio',
+];
 
 function pointsEqual(left: SectionOrigins, right: SectionOrigins) {
-  const sections: ProjectResourceCanvasSection[] = [
-    'document',
-    'version',
-    'art',
-    'audio',
-  ];
-  return sections.every(
+  return RESOURCE_SECTIONS.every(
     (section) =>
       left[section]?.x === right[section]?.x &&
       left[section]?.y === right[section]?.y,
@@ -219,20 +223,49 @@ function taskFlowGeometry(
   return { sourceAnchors, targetAnchors, sourceHub, targetHub };
 }
 
+function taskFlowSectionGeometries(
+  flow: ProjectResourceTaskFlow,
+  rectByResourceId: RectLookup,
+  sectionByResourceId: ReadonlyMap<string, ProjectResourceCanvasSection>,
+): TaskFlowSectionGeometry[] {
+  return RESOURCE_SECTIONS.flatMap((section) => {
+    const geometry = taskFlowGeometry(
+      {
+        ...flow,
+        sourceResourceIds: flow.sourceResourceIds.filter(
+          (resourceId) => sectionByResourceId.get(resourceId) === section,
+        ),
+        targetResourceIds: flow.targetResourceIds.filter(
+          (resourceId) => sectionByResourceId.get(resourceId) === section,
+        ),
+      },
+      rectByResourceId,
+    );
+    return geometry ? [{ ...geometry, section }] : [];
+  });
+}
+
+function taskFlowRenderKey(
+  flowId: string,
+  section: ProjectResourceCanvasSection,
+) {
+  return `${flowId}\n${section}`;
+}
+
 export const ResourceDependencyOverlay = forwardRef<
   ResourceDependencyOverlayHandle,
   ResourceDependencyOverlayProps
 >(function ResourceDependencyOverlay(
-  { graph, positions, visibleResourceIds, selectedResourceId },
+  { graph, positions, visibleResourceIds },
   ref,
 ) {
   const markerPrefix = useId().replace(/[^a-zA-Z0-9_-]/gu, '');
   const overlayRef = useRef<SVGSVGElement>(null);
   const referencePathRefs = useRef(new Map<string, SVGPathElement>());
   const taskFlowPathRefs = useRef(new Map<string, TaskFlowPathRefs>());
-  const activeDragPreviewRef = useRef<
-    (Point & { resourceId: string }) | null
-  >(null);
+  const activeDragPreviewRef = useRef<(Point & { resourceId: string }) | null>(
+    null,
+  );
   const graphRef = useRef(graph);
   const positionByResourceIdRef = useRef(
     new Map(positions.map((position) => [position.resourceId, position])),
@@ -316,37 +349,48 @@ export const ResourceDependencyOverlay = forwardRef<
     }
     return result;
   }, [graph.resourceIds, positions, sectionOrigins, visibleResourceIds]);
+  const sectionByResourceId = useMemo(
+    () =>
+      new Map(
+        positions.map((position) => [position.resourceId, position.section]),
+      ),
+    [positions],
+  );
   graphRef.current = graph;
   positionByResourceIdRef.current = new Map(
     positions.map((position) => [position.resourceId, position]),
   );
   rectByResourceIdRef.current = rectByResourceId;
 
-  const neighbors = useMemo(
-    () => projectResourceGraphNeighbors(graph, selectedResourceId),
-    [graph, selectedResourceId],
-  );
-  const selected = Boolean(
-    selectedResourceId && graph.resourceIds.has(selectedResourceId),
+  const taskFlowRenderEntries = useMemo(
+    () =>
+      graph.taskFlows.flatMap((flow) =>
+        taskFlowSectionGeometries(
+          flow,
+          rectByResourceId,
+          sectionByResourceId,
+        ).map((geometry) => ({
+          flow,
+          geometry,
+          renderKey: taskFlowRenderKey(flow.id, geometry.section),
+        })),
+      ),
+    [graph.taskFlows, rectByResourceId, sectionByResourceId],
   );
 
   const renderTaskFlows = useMemo(
     () =>
-      graph.taskFlows.map((flow) => {
-        const geometry = taskFlowGeometry(flow, rectByResourceId);
-        if (!geometry) {
-          return null;
-        }
-        const highlighted = neighbors.connectedEdgeIds.has(flow.id);
+      taskFlowRenderEntries.map(({ flow, geometry, renderKey }) => {
         const className = `game-resource-dependency-edge game-resource-dependency-edge--task${
-          highlighted ? ' is-highlighted' : selected ? ' is-dimmed' : ''
-        }${flow.cyclic ? ' is-cyclic' : ''}`;
+          flow.cyclic ? ' is-cyclic' : ''
+        }`;
         return (
           <g
-            key={flow.id}
+            key={renderKey}
             className={className}
             data-edge-kind="task-flow"
             data-edge-id={flow.id}
+            data-resource-section={geometry.section}
             data-source-task-id={flow.sourceTaskId}
             data-target-task-id={flow.targetTaskId}
             data-cyclic={flow.cyclic || undefined}
@@ -357,14 +401,14 @@ export const ResourceDependencyOverlay = forwardRef<
             {geometry.sourceAnchors.map(({ resourceId, point }) => (
               <path
                 ref={(node) => {
-                  let refs = taskFlowPathRefs.current.get(flow.id);
+                  let refs = taskFlowPathRefs.current.get(renderKey);
                   if (!refs) {
                     refs = {
                       sourceBranches: new Map(),
                       targetBranches: new Map(),
                       trunk: null,
                     };
-                    taskFlowPathRefs.current.set(flow.id, refs);
+                    taskFlowPathRefs.current.set(renderKey, refs);
                   }
                   if (node) {
                     refs.sourceBranches.set(resourceId, node);
@@ -381,14 +425,14 @@ export const ResourceDependencyOverlay = forwardRef<
             ))}
             <path
               ref={(node) => {
-                let refs = taskFlowPathRefs.current.get(flow.id);
+                let refs = taskFlowPathRefs.current.get(renderKey);
                 if (!refs) {
                   refs = {
                     sourceBranches: new Map(),
                     targetBranches: new Map(),
                     trunk: null,
                   };
-                  taskFlowPathRefs.current.set(flow.id, refs);
+                  taskFlowPathRefs.current.set(renderKey, refs);
                 }
                 refs.trunk = node;
               }}
@@ -398,14 +442,14 @@ export const ResourceDependencyOverlay = forwardRef<
             {geometry.targetAnchors.map(({ resourceId, point }) => (
               <path
                 ref={(node) => {
-                  let refs = taskFlowPathRefs.current.get(flow.id);
+                  let refs = taskFlowPathRefs.current.get(renderKey);
                   if (!refs) {
                     refs = {
                       sourceBranches: new Map(),
                       targetBranches: new Map(),
                       trunk: null,
                     };
-                    taskFlowPathRefs.current.set(flow.id, refs);
+                    taskFlowPathRefs.current.set(renderKey, refs);
                   }
                   if (node) {
                     refs.targetBranches.set(resourceId, node);
@@ -424,13 +468,7 @@ export const ResourceDependencyOverlay = forwardRef<
           </g>
         );
       }),
-    [
-      graph.taskFlows,
-      markerPrefix,
-      neighbors.connectedEdgeIds,
-      rectByResourceId,
-      selected,
-    ],
+    [markerPrefix, taskFlowRenderEntries],
   );
 
   const renderReferenceEdges = useMemo(
@@ -440,10 +478,9 @@ export const ResourceDependencyOverlay = forwardRef<
         if (!geometry) {
           return null;
         }
-        const highlighted = neighbors.connectedEdgeIds.has(edge.id);
         const className = `game-resource-dependency-edge game-resource-dependency-edge--reference${
-          highlighted ? ' is-highlighted' : selected ? ' is-dimmed' : ''
-        }${edge.cyclic ? ' is-cyclic' : ''}`;
+          edge.cyclic ? ' is-cyclic' : ''
+        }`;
         return (
           <path
             ref={(node) => {
@@ -468,97 +505,106 @@ export const ResourceDependencyOverlay = forwardRef<
           </path>
         );
       }),
-    [
-      graph.referenceEdges,
-      markerPrefix,
-      neighbors.connectedEdgeIds,
-      rectByResourceId,
-      selected,
-    ],
+    [graph.referenceEdges, markerPrefix, rectByResourceId],
   );
 
   useLayoutEffect(() => {
-    const activeFlowIds = new Set(graph.taskFlows.map((flow) => flow.id));
-    for (const flowId of taskFlowPathRefs.current.keys()) {
-      if (!activeFlowIds.has(flowId)) {
-        taskFlowPathRefs.current.delete(flowId);
+    const activeRenderKeys = new Set(
+      taskFlowRenderEntries.map((entry) => entry.renderKey),
+    );
+    for (const renderKey of taskFlowPathRefs.current.keys()) {
+      if (!activeRenderKeys.has(renderKey)) {
+        taskFlowPathRefs.current.delete(renderKey);
       }
     }
-  }, [graph.taskFlows]);
+  }, [taskFlowRenderEntries]);
 
   const updateAffectedGeometry = useCallback(
     (
       affectedResourceIds: ReadonlySet<string>,
       dragPreview: (Point & { resourceId: string }) | null,
     ) => {
-    const currentGraph = graphRef.current;
-    const currentRects = rectByResourceIdRef.current;
-    const dragBasePosition = dragPreview
-      ? positionByResourceIdRef.current.get(dragPreview.resourceId)
-      : undefined;
-    const rectLookup = {
-      get(resourceId: string) {
-        const rect = currentRects.get(resourceId);
-        if (!rect) {
-          return undefined;
+      const currentGraph = graphRef.current;
+      const currentRects = rectByResourceIdRef.current;
+      const dragBasePosition = dragPreview
+        ? positionByResourceIdRef.current.get(dragPreview.resourceId)
+        : undefined;
+      const rectLookup = {
+        get(resourceId: string) {
+          const rect = currentRects.get(resourceId);
+          if (!rect) {
+            return undefined;
+          }
+          return dragPreview?.resourceId === resourceId
+            ? {
+                ...rect,
+                x: rect.x - (dragBasePosition?.x ?? 0) + dragPreview.x,
+                y: rect.y - (dragBasePosition?.y ?? 0) + dragPreview.y,
+              }
+            : rect;
+        },
+      };
+      const affectedEdgeIds = new Set<string>();
+      for (const resourceId of affectedResourceIds) {
+        const index = currentGraph.connectionIndex.get(resourceId);
+        index?.referenceEdgeIds.forEach((edgeId) =>
+          affectedEdgeIds.add(edgeId),
+        );
+        index?.taskFlowIds.forEach((flowId) => affectedEdgeIds.add(flowId));
+      }
+      for (const edgeId of affectedEdgeIds) {
+        const referenceEdge = currentGraph.referenceEdgeById.get(edgeId);
+        if (referenceEdge) {
+          const geometry = referenceGeometry(referenceEdge, rectLookup);
+          const path = referencePathRefs.current.get(edgeId);
+          if (geometry && path) {
+            path.setAttribute('d', geometry.path);
+          }
+          continue;
         }
-        return dragPreview?.resourceId === resourceId
-          ? {
-              ...rect,
-              x: rect.x - (dragBasePosition?.x ?? 0) + dragPreview.x,
-              y: rect.y - (dragBasePosition?.y ?? 0) + dragPreview.y,
-            }
-          : rect;
-      },
-    };
-    const affectedEdgeIds = new Set<string>();
-    for (const resourceId of affectedResourceIds) {
-      const index = currentGraph.connectionIndex.get(resourceId);
-      index?.referenceEdgeIds.forEach((edgeId) =>
-        affectedEdgeIds.add(edgeId),
-      );
-      index?.taskFlowIds.forEach((flowId) => affectedEdgeIds.add(flowId));
-    }
-    for (const edgeId of affectedEdgeIds) {
-      const referenceEdge = currentGraph.referenceEdgeById.get(edgeId);
-      if (referenceEdge) {
-        const geometry = referenceGeometry(referenceEdge, rectLookup);
-        const path = referencePathRefs.current.get(edgeId);
-        if (geometry && path) {
-          path.setAttribute('d', geometry.path);
+        const flow = currentGraph.taskFlowById.get(edgeId);
+        if (!flow) {
+          continue;
         }
-        continue;
-      }
-      const flow = currentGraph.taskFlowById.get(edgeId);
-      const paths = taskFlowPathRefs.current.get(edgeId);
-      if (!flow || !paths) {
-        continue;
-      }
-      const geometry = taskFlowGeometry(flow, rectLookup);
-      if (!geometry) {
-        continue;
-      }
-      geometry.sourceAnchors.forEach(({ resourceId, point }) => {
-        paths.sourceBranches
-          .get(resourceId)
-          ?.setAttribute(
-            'd',
-            taskFlowBranchPath(point, geometry.sourceHub),
+        const sectionByResourceId = new Map(
+          Array.from(
+            positionByResourceIdRef.current.values(),
+            (position) => [position.resourceId, position.section] as const,
+          ),
+        );
+        for (const geometry of taskFlowSectionGeometries(
+          flow,
+          rectLookup,
+          sectionByResourceId,
+        )) {
+          const paths = taskFlowPathRefs.current.get(
+            taskFlowRenderKey(flow.id, geometry.section),
           );
-      });
-      paths.trunk?.setAttribute(
-        'd',
-        connectionPath(geometry.sourceHub, geometry.targetHub),
-      );
-      geometry.targetAnchors.forEach(({ resourceId, point }) => {
-        paths.targetBranches
-          .get(resourceId)
-          ?.setAttribute(
+          if (!paths) {
+            continue;
+          }
+          geometry.sourceAnchors.forEach(({ resourceId, point }) => {
+            paths.sourceBranches
+              .get(resourceId)
+              ?.setAttribute(
+                'd',
+                taskFlowBranchPath(point, geometry.sourceHub),
+              );
+          });
+          paths.trunk?.setAttribute(
             'd',
-            taskFlowBranchPath(geometry.targetHub, point),
+            connectionPath(geometry.sourceHub, geometry.targetHub),
           );
-      });
-    }
+          geometry.targetAnchors.forEach(({ resourceId, point }) => {
+            paths.targetBranches
+              .get(resourceId)
+              ?.setAttribute(
+                'd',
+                taskFlowBranchPath(geometry.targetHub, point),
+              );
+          });
+        }
+      }
     },
     [],
   );
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 8d7663508..11b813a51 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
@@ -45,7 +45,6 @@ import {
   EMPTY_PROJECT_RESOURCE_GRAPH,
   normalizeProjectResourceGraph,
   type ProjectResourceGraph,
-  projectResourceGraphNeighbors,
   type ProjectResourceGraphNodeInput,
   type ProjectResourceGraphReadModel,
 } from './resourceDependencyGraphModel';
@@ -362,7 +361,7 @@ const ResourceCard = memo(function ResourceCard({
 }: {
   resource: ProjectResource;
   selected: boolean;
-  relationState: 'upstream' | 'downstream' | 'both' | 'version-binding' | null;
+  relationState: 'version-binding' | null;
   x: number;
   y: number;
   onSelect: (resourceId: string) => void;
@@ -602,10 +601,6 @@ export default function ProjectDevelopmentView({
       ),
     [resourceLayout.positions],
   );
-  const selectedResourceNeighbors = useMemo(
-    () => projectResourceGraphNeighbors(resourceGraph, selectedResourceId),
-    [resourceGraph, selectedResourceId],
-  );
   const selectedVersionBindingResourceIds = useMemo(() => {
     const selectedVersion = resources.find(
       (resource) => resource.id === selectedResourceId,
@@ -1337,7 +1332,6 @@ export default function ProjectDevelopmentView({
                       graph={resourceGraph}
                       positions={resourceLayout.positions}
                       visibleResourceIds={visibleResourceIds}
-                      selectedResourceId={selectedResourceId}
                     />
                   ) : null}
                   {categoryOrder.map((category) => {
@@ -1384,28 +1378,12 @@ export default function ProjectDevelopmentView({
                               if (!position) {
                                 return null;
                               }
-                              const upstream =
-                                sortMode === 'dependency' &&
-                                selectedResourceNeighbors.upstreamResourceIds.has(
-                                  resource.id,
-                                );
-                              const downstream =
-                                sortMode === 'dependency' &&
-                                selectedResourceNeighbors.downstreamResourceIds.has(
-                                  resource.id,
-                                );
                               const relationState =
                                 selectedVersionBindingResourceIds.has(
                                   resource.id,
                                 )
                                   ? 'version-binding'
-                                  : upstream && downstream
-                                    ? 'both'
-                                    : upstream
-                                      ? 'upstream'
-                                      : downstream
-                                        ? 'downstream'
-                                        : null;
+                                  : null;
                               return (
                                 <ResourceCard
                                   key={resource.id}
diff --git a/apps/ai-game-creator-shell/tests/ResourceDependencyOverlay.test.ts b/apps/ai-game-creator-shell/tests/ResourceDependencyOverlay.test.ts
index a81ab0602..9ae652ff4 100644
--- a/apps/ai-game-creator-shell/tests/ResourceDependencyOverlay.test.ts
+++ b/apps/ai-game-creator-shell/tests/ResourceDependencyOverlay.test.ts
@@ -1,9 +1,12 @@
 /** @vitest-environment jsdom */
 import { act, render, screen, waitFor } from '@testing-library/react';
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
 import React from 'react';
 import { describe, expect, it, vi } from 'vitest';
 
 import type { ProjectResourceCanvasPosition } from '../../../packages/shared/src/contracts/gameCreationApp';
+import type { ProjectResourceCanvasSection } from '../../../packages/shared/src/contracts/gameCreationApp';
 import {
   normalizeProjectResourceGraph,
   type ProjectResourceGraph,
@@ -18,10 +21,11 @@ function position(
   resourceId: string,
   x: number,
   y: number,
+  section: ProjectResourceCanvasSection = 'art',
 ): ProjectResourceCanvasPosition {
   return {
     resourceId,
-    section: 'art',
+    section,
     x,
     y,
     manuallyPlaced: false,
@@ -106,25 +110,30 @@ function OverlayHarness({
   graph,
   positions,
   visibleResourceIds,
-  selectedResourceId = null,
   overlayRef,
 }: {
   graph: ProjectResourceGraph;
   positions: ProjectResourceCanvasPosition[];
   visibleResourceIds: ReadonlySet<string>;
-  selectedResourceId?: string | null;
   overlayRef?: React.Ref<ResourceDependencyOverlayHandle>;
 }) {
+  const sections = Array.from(
+    new Set(positions.map((position) => position.section)),
+  );
   return React.createElement(
     'div',
     null,
-    React.createElement('div', { 'data-resource-section-plane': 'art' }),
+    ...sections.map((section) =>
+      React.createElement('div', {
+        key: section,
+        'data-resource-section-plane': section,
+      }),
+    ),
     React.createElement(ResourceDependencyOverlay, {
       ref: overlayRef,
       graph,
       positions,
       visibleResourceIds,
-      selectedResourceId,
     }),
   );
 }
@@ -133,14 +142,12 @@ function overlayView(
   graph: ProjectResourceGraph,
   positions: ProjectResourceCanvasPosition[],
   visibleResourceIds: ReadonlySet<string>,
-  selectedResourceId: string | null = null,
   overlayRef?: React.Ref<ResourceDependencyOverlayHandle>,
 ) {
   return React.createElement(OverlayHarness, {
     graph,
     positions,
     visibleResourceIds,
-    selectedResourceId,
     overlayRef,
   });
 }
@@ -179,6 +186,42 @@ describe('ResourceDependencyOverlay', () => {
     ).toBe('userSpaceOnUse');
   });
 
+  it('omits cross-section task endpoints and keeps same-section task flow groups', async () => {
+    const graph = graphFixture();
+    const positions = [
+      position('source:one', 0, 0, 'document'),
+      position('source:two', 0, 0, 'art'),
+      position('source:three', 0, 120, 'document'),
+      position('target:one', 240, 0, 'art'),
+      position('target:two', 240, 120, 'art'),
+      position('target:three', 240, 0, 'audio'),
+    ];
+    render(
+      overlayView(
+        graph,
+        positions,
+        new Set(positions.map((position) => position.resourceId)),
+      ),
+    );
+
+    const overlay = await screen.findByTestId('resource-dependency-overlay');
+    const taskFlow = await waitFor(() => {
+      const flows = overlay.querySelectorAll('[data-edge-kind="task-flow"]');
+      expect(flows).toHaveLength(1);
+      return flows.item(0);
+    });
+    expect(taskFlow.getAttribute('data-resource-section')).toBe('art');
+    expect(taskFlow.querySelectorAll('path')).toHaveLength(4);
+    expect(
+      Array.from(taskFlow.querySelectorAll('[data-resource-id]')).map((node) =>
+        node.getAttribute('data-resource-id'),
+      ),
+    ).toEqual(['source:two', 'target:one', 'target:two']);
+    expect(
+      overlay.querySelectorAll('[data-edge-kind="asset-reference"]'),
+    ).toHaveLength(1);
+  });
+
   it('filters hidden endpoints and updates path geometry when positions change', async () => {
     const graph = graphFixture();
     const positions = [
@@ -191,7 +234,6 @@ describe('ResourceDependencyOverlay', () => {
         graph,
         positions,
         new Set(['source:one', 'target:one']),
-        null,
         overlayRef,
       ),
     );
@@ -252,7 +294,7 @@ describe('ResourceDependencyOverlay', () => {
       ];
       const visible = new Set(['source:one', 'target:one']);
       const overlayRef = React.createRef<ResourceDependencyOverlayHandle>();
-      render(overlayView(graph, positions, visible, null, overlayRef));
+      render(overlayView(graph, positions, visible, overlayRef));
       const overlay = await screen.findByTestId('resource-dependency-overlay');
       const selector = '[data-edge-kind="asset-reference"]';
       await waitFor(() =>
@@ -321,26 +363,18 @@ describe('ResourceDependencyOverlay', () => {
     );
   });
 
-  it('highlights direct edges and dims unrelated cyclic edges for a selection', async () => {
+  it('keeps every rendered relationship at its default visual state', async () => {
     const graph = graphFixture();
     const positions = Array.from(graph.resourceIds).map((resourceId, index) =>
       position(resourceId, index * 200, 0),
     );
-    render(
-      overlayView(graph, positions, new Set(graph.resourceIds), 'target:one'),
-    );
+    render(overlayView(graph, positions, new Set(graph.resourceIds)));
     const overlay = await screen.findByTestId('resource-dependency-overlay');
     await waitFor(() =>
-      expect(
-        overlay.querySelectorAll('.is-highlighted').length,
-      ).toBeGreaterThan(0),
+      expect(overlay.querySelectorAll('[data-edge-kind]')).toHaveLength(3),
     );
-    const unrelated = Array.from(
-      overlay.querySelectorAll<SVGElement>(
-        '[data-edge-kind="asset-reference"]',
-      ),
-    ).find((edge) => edge.getAttribute('data-cyclic') === 'true');
-    expect(unrelated?.classList.contains('is-dimmed')).toBe(true);
+    expect(overlay.querySelector('.is-highlighted')).toBeNull();
+    expect(overlay.querySelector('.is-dimmed')).toBeNull();
   });
 
   it('updates only adjacent paths while dragging inside a 4096-resource topology', async () => {
@@ -387,17 +421,14 @@ describe('ResourceDependencyOverlay', () => {
     ];
     const visible = new Set(positions.map(({ resourceId }) => resourceId));
     const overlayRef = React.createRef<ResourceDependencyOverlayHandle>();
-    render(overlayView(graph, positions, visible, null, overlayRef));
+    render(overlayView(graph, positions, visible, overlayRef));
     const overlay = await screen.findByTestId('resource-dependency-overlay');
     await waitFor(() =>
       expect(
         overlay.querySelectorAll('[data-edge-kind="task-flow"]'),
       ).toHaveLength(2),
     );
-    const setAttribute = vi.spyOn(
-      SVGElement.prototype,
-      'setAttribute',
-    );
+    const setAttribute = vi.spyOn(SVGElement.prototype, 'setAttribute');
     try {
       act(() =>
         overlayRef.current?.updateDragPreview({
@@ -428,18 +459,12 @@ describe('ResourceDependencyOverlay', () => {
     vi.stubGlobal('ResizeObserver', TestResizeObserver);
     try {
       const graph = graphFixture();
-      const positions = Array.from(graph.resourceIds).map(
-        (resourceId, index) => position(resourceId, index * 200, 0),
+      const positions = Array.from(graph.resourceIds).map((resourceId, index) =>
+        position(resourceId, index * 200, 0),
       );
       const overlayRef = React.createRef<ResourceDependencyOverlayHandle>();
       const view = render(
-        overlayView(
-          graph,
-          positions,
-          new Set(graph.resourceIds),
-          null,
-          overlayRef,
-        ),
+        overlayView(graph, positions, new Set(graph.resourceIds), overlayRef),
       );
 
       expect(observe).toHaveBeenCalledTimes(2);
@@ -457,4 +482,20 @@ describe('ResourceDependencyOverlay', () => {
       vi.unstubAllGlobals();
     }
   });
+
+  it('uses a bright persistent orange without selection-dependent edge styles', () => {
+    const styles = readFileSync(
+      resolve(process.cwd(), 'apps/ai-game-creator-shell/src/styles.css'),
+      'utf8',
+    );
+    expect(styles).toMatch(
+      /\.game-resource-dependency-edge--reference\s*\{[^}]*stroke:\s*#f28a52[^}]*opacity:\s*1/s,
+    );
+    expect(styles).toMatch(
+      /\.game-resource-dependency-marker--reference path\s*\{[^}]*fill:\s*#f28a52/s,
+    );
+    expect(styles).not.toMatch(
+      /\.game-resource-dependency-edge\.is-(?:highlighted|dimmed)/,
+    );
+  });
 });
diff --git a/apps/ai-game-creator-shell/tests/appSurface/project-development.suite.ts b/apps/ai-game-creator-shell/tests/appSurface/project-development.suite.ts
index 18b7c4bff..8dbd13a61 100644
--- a/apps/ai-game-creator-shell/tests/appSurface/project-development.suite.ts
+++ b/apps/ai-game-creator-shell/tests/appSurface/project-development.suite.ts
@@ -1132,7 +1132,7 @@ export function registerProjectWorkbenchFoundationTests() {
     expect(screen.getByLabelText('子 Agent 状态栏')).not.toBeNull();
   });
 
-  it('renders, filters, highlights, and destroys the resource dependency overlay without pointer previews', async () => {
+  it('renders, filters, and destroys persistent resource dependency lines without cross-section task flows', async () => {
     const manifest = createGameCreationAppManifest(
       'workbench-resource-graph',
       '资源依赖图测试',
@@ -1328,7 +1328,7 @@ export function registerProjectWorkbenchFoundationTests() {
       ).toHaveLength(2);
       expect(
         overlay.querySelectorAll('[data-edge-kind="task-flow"]'),
-      ).toHaveLength(1);
+      ).toHaveLength(0);
     });
 
     fireEvent.click(screen.getByRole('button', { name: '按类型' }));
@@ -1401,19 +1401,20 @@ export function registerProjectWorkbenchFoundationTests() {
     );
     overlay = await screen.findByTestId('resource-dependency-overlay');
     sourceCard = screen.getByRole('button', { name: /spec-source\.json/ });
-    await waitFor(() => {
-      expect(sourceCard.classList.contains('is-relation-upstream')).toBe(true);
-      expect(
-        overlay
-          .querySelector(referenceSelector)
-          ?.classList.contains('is-highlighted'),
-      ).toBe(true);
-    });
+    await waitFor(() =>
+      expect(overlay.querySelector(referenceSelector)).not.toBeNull(),
+    );
+    expect(sourceCard.classList.contains('is-relation-upstream')).toBe(false);
+    expect(
+      overlay
+        .querySelector(referenceSelector)
+        ?.classList.contains('is-highlighted'),
+    ).toBe(false);
     expect(
       overlay
         .querySelector('[data-source-resource-id="asset:unrelated-cycle"]')
         ?.classList.contains('is-dimmed'),
-    ).toBe(true);
+    ).toBe(false);
 
     const previousOverlay = overlay;
     const nextManifest = createGameCreationAppManifest(
diff --git a/docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md b/docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md
index 46a1ab8de..d94743946 100644
--- a/docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md
+++ b/docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md
@@ -1,6 +1,6 @@
 # AI 游戏创作项目开发工作台 PRD
 
-更新时间：`2026-08-03`（阶段七验收收口）
+更新时间：`2026-08-04`（依赖视图视觉口径调整）
 
 ## 1. 产品定位
 
@@ -263,16 +263,16 @@ type UpdateProjectResourceCanvasLayoutResult =
 - 阶段五实现状态（2026-08-03）：dependency 自动排列同时消费任务 DAG 与精确资源引用。Rust 把可信 producer 的任务深度作为资源深度下限，再对 `asset-reference` 图做迭代式 SCC 压缩与确定性层级传播；被引用资源位于引用资源之前，同一引用环共享稳定深度，环后资源继续递增，没有引用关系的资源保持默认不重叠位置。布局深度通过独立 `dependencyDepths` 返回，不能把 producer assignment 冒充全部资源的布局结果。
 - 图层只在 dependency 模式挂载；type 模式不得渲染 SVG、连线或 marker。切换 mode、切换项目或卸载工作台时必须销毁旧图层，并清理尺寸观察和窗口事件监听。
 - 输入固定为当前资源投影的全部卡片身份 / 坐标与 Tauri Rust 返回的 `ProjectResourceGraph` 只读 DTO；Rust 负责资源过滤、去重、迭代式环检测、SCC 压缩后的确定性依赖深度、任务流聚合和一跳连接索引，前端只负责 DTO 防御归一化、浏览器几何与原生 SVG path / marker。SVG 叠加在资源卡底层并设置 `pointer-events: none`，不得引入 D3、React Flow 等图表库，也不得阻断卡片点击。
-- `asset-reference` 表示精确资源引用，使用橙色实线与连续贝塞尔曲线。`GameCreationAppAssetManifestEntry.source.referenceResourceIds` 中的外部资源 ID 必须先唯一匹配另一项资产的 `source.resourceId`，再映射为当前资源卡 ID；缺失、重复或已删除的目标均不得渲染幽灵连线。
-- `task-flow` 表示任务产物流转，使用灰色圆头虚线。任务依赖按 `sourceTaskId -> targetTaskId` 聚合为一条主线，两端资源仅绘制平滑曲线分支，不得出现直角折线；禁止对上下游资源生成笛卡尔积连线。任务主线与分支可以使用不同线宽和透明度表达聚合层级，但不能改变端点或方向语义。
+- `asset-reference` 表示精确资源引用，使用明亮橙色实线与连续贝塞尔曲线。`GameCreationAppAssetManifestEntry.source.referenceResourceIds` 中的外部资源 ID 必须先唯一匹配另一项资产的 `source.resourceId`，再映射为当前资源卡 ID；缺失、重复或已删除的目标均不得渲染幽灵连线。
+- `task-flow` 表示同一资源类型内的任务产物流转，使用灰色圆头虚线；文档、项目版本、美术、音频之间不得绘制跨分区虚线。任务依赖按 `sourceTaskId -> targetTaskId + section` 分区聚合为一条主线，两端只保留同分区资源并绘制平滑曲线分支，不得出现直角折线；禁止对上下游资源生成笛卡尔积连线。任务主线与分支可以使用不同线宽和透明度表达聚合层级，但不能改变端点或方向语义。
 - 画布资产 producer 只能来自 `agent.runtime.canvas.asset_generate` 的 `assetId -> agentId` 审计且 `agentId` 必须存在于当前 manifest；External Editor `source.taskId` 属于平台生成任务命名空间，禁止当作 manifest task ID。证据缺失、冲突或有界审计读取未覆盖时不生成对应 task flow，不猜测归属。
 - 图模型必须对资源引用图和完整任务依赖图做迭代式环检测，不得用无界递归遍历；参与环的可见边保留渲染并标记 cyclic，环本身不能造成重复生成或死循环。
 - 资源自引用的起点与终点为同一张卡片时，必须绘制在卡片外侧的可见闭环并保留箭头，不得让路径穿过卡片后被底层 SVG 层级遮挡。
 - 搜索只允许为当前可见端点生成几何；任一精确引用端点隐藏时该线隐藏，聚合任务流只保留仍可见的两端分支，任一侧没有可见资源时整条任务流隐藏。
-- 选中资源后，高亮其直接上游、直接下游卡片和关联边，弱化其余边；不做跨多层递归高亮。选中 ID 已失效时按未选中处理。
-- 资源卡 Pointer Move 不改变基础 positions 或 SVG 几何。连线只随布局读取、资源自动协调、搜索、选择、项目切换或 section origin 变化而更新。
+- 资源点击只进入中央聚焦并保留当前选中卡片，不改变依赖卡片或连线的颜色、线宽与透明度；关系线始终直接展示，不提供点击后的上下游高亮或无关线弱化。
+- 资源卡 Pointer Move 不改变基础 positions 或 SVG 几何。连线只随布局读取、资源自动协调、搜索、项目切换或 section origin 变化而更新。
 - `ResizeObserver` 在单个图层生命周期只允许构造一次。dependency section 额外提供至少 `64px` 右侧视觉 gutter，确保最右侧自环和箭头可完整滚动显示，但不得修改卡片坐标或布局 sidecar。
-- 阶段五不改变手动位置边界：已有 `manuallyPlaced=true` 坐标原样保留，资源引用新增或变化只允许重新派生 `manuallyPlaced=false` 的自动坐标；任务流继续按任务对聚合，禁止为了计算深度或绘线生成资源笛卡尔积。
+- 阶段五不改变手动位置边界：已有 `manuallyPlaced=true` 坐标原样保留，资源引用新增或变化只允许重新派生 `manuallyPlaced=false` 的自动坐标；任务流继续按任务对与资源分区聚合，禁止为了计算深度或绘线生成资源笛卡尔积。
 
 ### 5.3 资源类型与替换兼容性（P1）
 
@@ -427,11 +427,11 @@ type ProjectAgentMudPointAttribution = {
 
 ### 7.3 P1 资源依赖关系图验收
 
-1. dependency 模式同时正确显示橙色实线资源引用与灰色虚线任务流；type 模式没有图层或连线。
+1. dependency 模式显示明亮橙色实线资源引用，并只在同一资源类型分区内显示灰色虚线任务流；跨类型不显示虚线，type 模式没有图层或连线。
 2. 精确引用只接受唯一有效的外部资源 ID 映射，删除或不存在的资源不产生幽灵连线。
-3. 多资源任务依赖只形成一条聚合主线与 `O(S+T)` 条端点分支，不产生 `S×T` 连线。
+3. 多资源任务依赖按资源类型分区后，各分区只形成一条聚合主线与 `O(S+T)` 条端点分支，不产生 `S×T` 连线或跨分区虚线。
 4. 资源引用环和无资源产物参与的任务环都可被有限遍历识别，界面不死循环。
-5. 搜索触发端点过滤，选择触发直接上下游与关联边高亮；资源卡指针移动不更新线段，点击与中央聚焦行为不回归。
+5. 搜索触发端点过滤；资源点击不改变上下游卡片或任何连线的视觉状态，资源卡指针移动不更新线段，点击与中央聚焦行为不回归。
 6. 切换布局模式或项目后旧 SVG、ResizeObserver 与窗口监听全部清理；图层从不写入 layout sidecar、manifest 或其它持久化。
 7. 4096 资源链式 fixture 继续验证拓扑、聚合复杂度和自动布局性能；拖动局部更新与真实 Chromium 拖动帧预算暂缓，不作为当前验收条件。最右侧自环与箭头仍需完整显示。
 8. Rust 图读取延迟时，dependency sidecar 在图进入 `ready / failed` 前没有读取或写入；首次布局直接使用 Rust 返回的最终 producer 与 dependency depth。重新打开旧布局时手动位置逐项不变，自动位置按最终拓扑协调且相同结果不增加 revision。
-- 
2.52.0


From 2e0ef02fdac915971c047c7fcdf54b556baffe59 Mon Sep 17 00:00:00 2001
From: menghao <mh18530625731@163.com>
Date: Tue, 4 Aug 2026 12:00:04 +0800
Subject: [PATCH 18/27] =?UTF-8?q?=E4=BF=AE=E5=A4=8DCI=E4=BE=9D=E8=B5=96?=
 =?UTF-8?q?=E5=87=86=E5=A4=87=E9=A1=BA=E5=BA=8F?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

修复依赖图测试import排序门禁

在后端构建门禁前预取锁定Cargo依赖

新增Backend-CI执行顺序回归测试

同步更新Gitea-CI开发运维约定
---
 .gitea/workflows/project-ci.yml               |  6 ++--
 .../tests/ResourceDependencyOverlay.test.ts   |  3 +-
 .../shared-memory/development-workflow.md     |  2 +-
 ...发运维】本地开发验证与生产运维-2026-05-15.md |  2 +-
 scripts/project-ci-workflow.test.ts           | 36 +++++++++++++++++++
 5 files changed, 43 insertions(+), 6 deletions(-)
 create mode 100644 scripts/project-ci-workflow.test.ts

diff --git a/.gitea/workflows/project-ci.yml b/.gitea/workflows/project-ci.yml
index 4bdbb49cd..e19b10e7e 100644
--- a/.gitea/workflows/project-ci.yml
+++ b/.gitea/workflows/project-ci.yml
@@ -161,9 +161,6 @@ jobs:
       - name: Install npm dependencies
         run: npm ci
 
-      - name: Check server-rs boundaries
-        run: npm run check:server-rs-ddd
-
       - name: Prepare server-rs Rust dependencies
         shell: bash
         run: |
@@ -181,6 +178,9 @@ jobs:
             sleep $((attempt * 2))
           done
 
+      - name: Check server-rs boundaries
+        run: npm run check:server-rs-ddd
+
       - name: Run server-rs workspace tests
         run: cargo test --locked --workspace --no-fail-fast --manifest-path server-rs/Cargo.toml
 
diff --git a/apps/ai-game-creator-shell/tests/ResourceDependencyOverlay.test.ts b/apps/ai-game-creator-shell/tests/ResourceDependencyOverlay.test.ts
index 9ae652ff4..0f4e20e51 100644
--- a/apps/ai-game-creator-shell/tests/ResourceDependencyOverlay.test.ts
+++ b/apps/ai-game-creator-shell/tests/ResourceDependencyOverlay.test.ts
@@ -1,7 +1,8 @@
 /** @vitest-environment jsdom */
-import { act, render, screen, waitFor } from '@testing-library/react';
 import { readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
+
+import { act, render, screen, waitFor } from '@testing-library/react';
 import React from 'react';
 import { describe, expect, it, vi } from 'vitest';
 
diff --git a/docs/project-memory/shared-memory/development-workflow.md b/docs/project-memory/shared-memory/development-workflow.md
index acc57dd6f..7905231fd 100644
--- a/docs/project-memory/shared-memory/development-workflow.md
+++ b/docs/project-memory/shared-memory/development-workflow.md
@@ -539,7 +539,7 @@ npm run check:server-rs-ddd
 
 - 仓库 CI 入口是 `.gitea/workflows/project-ci.yml`，向 `master`、`codex/ai-game-creator-app` 推送和所有 PR 创建、更新时必须运行，也允许手工触发。
 - CI 固定拆分为 `Repository checks`、`Frontend tests`、`Backend tests`、`Native shell tests` 四个 required job；对应 PR context 完整名称是 `Project CI / Repository checks (pull_request)`、`Project CI / Frontend tests (pull_request)`、`Project CI / Backend tests (pull_request)`、`Project CI / Native shell tests (pull_request)`，首次运行后仍须从 Gitea 最近一周 context 表复核。测试使用独立 job，不能只藏在综合检查 step 中；原生壳验收单独运行以便定位重型构建失败。
-- 四个 job 共同覆盖 `npm run check`，并追加 `npm run check:server-rs-ddd`、`cargo test --locked --workspace --no-fail-fast --manifest-path server-rs/Cargo.toml`、`cargo check -p api-server --all-targets --manifest-path server-rs/Cargo.toml` 和 `cargo check -p spacetime-module --manifest-path server-rs/Cargo.toml`。后端 runner 安装 `ffmpeg`，避免视频抽帧测试因工具缺失提前返回。`codex/ai-game-creator-app` 分支必须用独立 lockfile 安装 AI 游戏创作壳依赖，其原生壳入口还必须覆盖 `npm run ai-game-creator-shell:check`、release build smoke，并检查 AI Tauri `Cargo.lock` 不漂移。原生壳 job 还要通过 Google 官方签名 APT 源安装 `google-chrome-stable`，用于 headless preview 的真实 DOM / canvas smoke；同时安装 `ripgrep`，把 `actions/setup-node` 的完整 Node.js 22 发行目录与 root-owned rustup proxy 映射到 `/usr/local`，供只接受受信任系统命令目录的 `command.exec` 沙箱测试使用，不能放宽生产命令目录白名单。Tauri 的 1132 项级别 suite 固定 `--test-threads=1`，避免共享 Agent Runtime 后台锁与异步终态在 libtest 并行调度下互相干扰。
+- 四个 job 共同覆盖 `npm run check`，并追加 `npm run check:server-rs-ddd`、`cargo test --locked --workspace --no-fail-fast --manifest-path server-rs/Cargo.toml`、`cargo check -p api-server --all-targets --manifest-path server-rs/Cargo.toml` 和 `cargo check -p spacetime-module --manifest-path server-rs/Cargo.toml`。Backend job 必须先用 `cargo fetch --locked` 的 5 次整命令级有界重试准备当前 `server-rs` 锁定依赖，再进入会触发 `cargo build` 的 DDD / module-runtime 产物边界门禁；不得把依赖准备放在该门禁之后，否则镜像缺少锁新增 crate 时会在首次 registry / TLS 抖动处提前失败。后端 runner 安装 `ffmpeg`，避免视频抽帧测试因工具缺失提前返回。`codex/ai-game-creator-app` 分支必须用独立 lockfile 安装 AI 游戏创作壳依赖，其原生壳入口还必须覆盖 `npm run ai-game-creator-shell:check`、release build smoke，并检查 AI Tauri `Cargo.lock` 不漂移。原生壳 job 还要通过 Google 官方签名 APT 源安装 `google-chrome-stable`，用于 headless preview 的真实 DOM / canvas smoke；同时安装 `ripgrep`，把 `actions/setup-node` 的完整 Node.js 22 发行目录与 root-owned rustup proxy 映射到 `/usr/local`，供只接受受信任系统命令目录的 `command.exec` 沙箱测试使用，不能放宽生产命令目录白名单。Tauri 的 1132 项级别 suite 固定 `--test-threads=1`，避免共享 Agent Runtime 后台锁与异步终态在 libtest 并行调度下互相干扰。
 - checkout 必须使用完整历史。PR 将 base SHA 写入 `SPACETIME_SCHEMA_BASE_REF`，直接推送 `master` 使用 before SHA；事件基线不可解析时直接失败。Gitea 检查的是 PR head 而非预合并 commit，workflow 必须拒绝不包含最新 base commit 的过期 PR，分支保护同时保持“PR 过期禁止合并”。
 - 普通 PR job 不读取业务 secret，不运行真实 API/SpacetimeDB/OSS/支付/生成/live smoke，也不执行会修改外部状态的维护、迁移、发布或备份命令。
 - Gitea 至少升级到 `1.26.4` 后才能注册执行 PR job 的 runner；`ubuntu-latest` 标签只映射到固定 digest 的 Ubuntu 24.04 级 Docker/临时隔离镜像，不使用浮动镜像 tag，不映射 host，不向 job 暴露 Docker socket、业务 secret 或不必要内网。runner 能访问 Gitea、GitHub Actions 与 `actions/node-versions`、nodejs.org、npm、Rust 分发、crates.io 和 Google Chrome 的 `dl.google.com` 官方签名 APT 源；workflow 的官方 action 固定完整 commit，若内网禁用 GitHub，先在当前 Gitea 镜像对应 commit 并改用绝对 URL。受控镜像优先预装 rustup。Gitea 1.26 的任务超时由 runner 全局配置控制；首次运行成功后，`master` 分支保护必须要求上述四个 job 全部成功。
diff --git a/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md b/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md
index fae019c5f..48914ebf8 100644
--- a/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md
+++ b/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md
@@ -230,7 +230,7 @@ npm run check
 
 - `Repository checks`：执行 `npm run lint`、主站与后台生产构建、内容数据检查和提交差异空白检查。
 - `Frontend tests`：按根 lockfile 与 `apps/ai-game-creator-shell/package-lock.json` 分别执行干净的 `npm ci`，再独立执行根 `npm run test`、`npm run bgfilter-worker:smoke-test`、`npm run check:production-health-patrol`、`npm run check:production-api-release` 和 `npm run check:production-api-deploy`，让 Vitest、Node test smoke harness 及不依赖真实服务的生产巡检 / 发布 / 部署行为 fixture 在 Gitea job 中持续执行；其中 `.test.mjs` 使用 Node test runner，不依赖 Vitest 的 `scripts/**/*.test.ts` 收集规则。
-- `Backend tests`：执行 `npm run check:server-rs-ddd`、`cargo test --locked --workspace --no-fail-fast`、`api-server --all-targets` 编译和 `spacetime-module` 编译；runner 安装 `ffmpeg`，避免视频抽帧测试因工具缺失提前返回。依赖真实服务或密钥的测试必须显式 `ignored`，不能让普通 PR job访问现场环境。
+- `Backend tests`：先对 `server-rs/Cargo.lock` 执行带 5 次整命令级有界重试的 `cargo fetch --locked`，再执行 `npm run check:server-rs-ddd`、`cargo test --locked --workspace --no-fail-fast`、`api-server --all-targets` 编译和 `spacetime-module` 编译；依赖准备必须位于会触发 Cargo build 的 DDD / 产物边界门禁之前，避免锁新增依赖未命中镜像缓存时绕过既有下载重试。runner 安装 `ffmpeg`，避免视频抽帧测试因工具缺失提前返回。依赖真实服务或密钥的测试必须显式 `ignored`，不能让普通 PR job访问现场环境。
 - `Native shell tests`：按根 lockfile 与 AI 游戏创作壳独立 lockfile 安装依赖后执行 `npm run check:native-shells`，覆盖微信壳、Expo 和 Tauri 的完整验收，并确认桌面壳与 AI 游戏创作壳的 `Cargo.lock` 都没有被构建过程改写。`codex/ai-game-creator-app` 分支的同名脚本还会执行 `npm run ai-game-creator-shell:check` 和 AI 游戏创作壳 release build smoke；共享 Agent Runtime 后台锁 suite 固定 `--test-threads=1`，不能用并行偶发失败后的逐项通过替代整套稳定门禁。
 
 四个 job 合起来覆盖根 `npm run check`，并补齐根检查没有包含的 BgFilter worker smoke harness、无密钥生产巡检 / 发布 / 部署行为 fixture、server-rs DDD、正式 workspace Rust 测试与现役后端编译门禁。普通 PR CI 不注入业务密钥，不启动真实 API、SpacetimeDB、OSS、支付、图片生成或生产 live smoke；需要现场环境、可变外部状态、Docker 编排或发布凭据的 `check:*` 继续按对应专题和 Jenkins 发布流程执行，不能遍历所有同名前缀脚本冒充 PR 门禁。
diff --git a/scripts/project-ci-workflow.test.ts b/scripts/project-ci-workflow.test.ts
new file mode 100644
index 000000000..cd0e94ee9
--- /dev/null
+++ b/scripts/project-ci-workflow.test.ts
@@ -0,0 +1,36 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+import { describe, expect, it } from 'vitest';
+
+const workflow = readFileSync(
+  resolve(process.cwd(), '.gitea/workflows/project-ci.yml'),
+  'utf8',
+);
+
+function backendStepIndex(stepName: string) {
+  const backendJobStart = workflow.indexOf('  backend-tests:');
+  const nativeShellJobStart = workflow.indexOf('  native-shell-tests:');
+  expect(backendJobStart).toBeGreaterThanOrEqual(0);
+  expect(nativeShellJobStart).toBeGreaterThan(backendJobStart);
+
+  return workflow
+    .slice(backendJobStart, nativeShellJobStart)
+    .indexOf(`      - name: ${stepName}`);
+}
+
+describe('project CI workflow', () => {
+  it('prepares locked server-rs dependencies before the first Cargo build gate', () => {
+    const prepareDependencies = backendStepIndex(
+      'Prepare server-rs Rust dependencies',
+    );
+    const checkBoundaries = backendStepIndex('Check server-rs boundaries');
+    const runWorkspaceTests = backendStepIndex('Run server-rs workspace tests');
+
+    expect(prepareDependencies).toBeGreaterThanOrEqual(0);
+    expect(checkBoundaries).toBeGreaterThan(prepareDependencies);
+    expect(runWorkspaceTests).toBeGreaterThan(checkBoundaries);
+    expect(workflow).toContain('cargo fetch --locked');
+    expect(workflow).toContain('for attempt in $(seq 1 5); do');
+  });
+});
-- 
2.52.0


From d1a47c0fe786bae8e36c4b1e282e0e183b278299 Mon Sep 17 00:00:00 2001
From: menghao <mh18530625731@163.com>
Date: Tue, 4 Aug 2026 15:21:55 +0800
Subject: [PATCH 19/27] =?UTF-8?q?=E5=AE=9E=E7=8E=B0=E6=B8=B8=E6=88=8F?=
 =?UTF-8?q?=E5=B7=A5=E4=BD=9C=E5=8F=B0P0/P1=E5=8F=AF=E8=BF=90=E8=A1=8C?=
 =?UTF-8?q?=E7=89=88=E6=9C=AC=E8=83=BD=E5=8A=9B?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

冻结工作台运行版本、会话、参数、资源与消息跨端合同
新增可信 Runtime 验证后的不可变可运行版本登记与快照校验
支持 Tauri 客户端选择、切换并运行历史版本快照
收紧普通预览授权边界并同步资源高亮与明确错误展示
补充前后端测试、PRD、技术方案和项目决策记录
---
 .../src/agent/runtime_driver/task_start.rs    |  82 +++
 .../autonomous_completion_contract_tests.rs   | 132 ++++
 .../src-tauri/src/main.rs                     |  20 +-
 .../src-tauri/src/preview.rs                  |  89 ++-
 .../src-tauri/src/project.rs                  |   2 +
 .../src-tauri/src/project/manifest.rs         |  21 +
 .../src/project/runnable_versions.rs          | 587 ++++++++++++++++++
 .../src-tauri/src/tests/project.rs            |  33 +
 apps/ai-game-creator-shell/src/App.tsx        |   7 +
 .../features/app-shell/WorkspaceLauncher.tsx  |   4 +
 .../src/features/app-shell/model.ts           |   1 +
 .../app-shell/useHomeProjectCreation.ts       |  12 +
 apps/ai-game-creator-shell/src/styles.css     |  36 +-
 .../src/view/project-development/index.tsx    | 238 ++++---
 .../resourceProjectionModel.ts                |  14 +-
 .../appSurface/project-development.suite.ts   | 266 +++++++-
 .../projectResourceProjectionModel.test.ts    |  79 ++-
 ...AI游戏创作】项目开发工作台PRD-2026-07-20.md | 110 +++-
 .../shared-memory/decision-log.md             |   9 +
 ...�案】AI游戏创作智能体App实施计划-2026-06-24.md |  16 +-
 .../shared/src/contracts/gameCreationApp.ts   | 102 +++
 .../shared-contracts/src/game_creation_app.rs | 505 +++++++++++++++
 22 files changed, 2170 insertions(+), 195 deletions(-)
 create mode 100644 apps/ai-game-creator-shell/src-tauri/src/project/runnable_versions.rs

diff --git a/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_driver/task_start.rs b/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_driver/task_start.rs
index cfe56d75b..fddd0fbac 100644
--- a/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_driver/task_start.rs
+++ b/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_driver/task_start.rs
@@ -1249,6 +1249,88 @@ pub(in crate::agent) fn project_autonomous_manifest_ready_task_terminal_at_locke
             }),
         )?;
     }
+    if status == GameCreationAppTaskStatus::Completed && state.agent_id == "preview-playtest" {
+        let manifest_before_completion = read_manifest_for_project(root)?;
+        let required_tasks = autonomous_manifest_seed_tasks_for_source(&root_parent_binding.source);
+        let required_by_id = required_tasks
+            .iter()
+            .map(|task| (task.id.as_str(), task))
+            .collect::<std::collections::HashMap<_, _>>();
+        let mut prerequisite_ids = std::collections::BTreeSet::new();
+        let mut pending_ids = vec![state.agent_id.as_str()];
+        while let Some(task_id) = pending_ids.pop() {
+            if !prerequisite_ids.insert(task_id) {
+                continue;
+            }
+            let task = required_by_id
+                .get(task_id)
+                .ok_or_else(|| format!("可运行版本项目完整性合同缺少任务：{task_id}"))?;
+            pending_ids.extend(task.dependencies.iter().map(String::as_str));
+        }
+        let incomplete = required_tasks
+            .iter()
+            .filter(|required| prerequisite_ids.contains(required.id.as_str()))
+            .filter(|required| required.id != state.agent_id)
+            .filter(|required| {
+                manifest_before_completion
+                    .tasks
+                    .iter()
+                    .find(|task| task.id == required.id)
+                    .is_none_or(|task| task.status != GameCreationAppTaskStatus::Completed)
+            })
+            .map(|task| task.id.as_str())
+            .collect::<Vec<_>>();
+        if !incomplete.is_empty() {
+            return Err(format!(
+                "可运行版本项目完整性检查未通过：{}",
+                incomplete.join("、")
+            ));
+        }
+        let readiness_records =
+            latest_game_creator_agent_runtime_tasks(read_all_game_creator_agent_runtime_tasks(
+                &game_creator_agent_runtime_task_path(root, "preview-readiness"),
+            )?);
+        let readiness = readiness_records
+            .iter()
+            .rev()
+            .find(|record| {
+                record.parent_agent_id.as_deref() == Some(parent_agent_id.as_str())
+                    && record.parent_run_id.as_deref() == Some(parent_run_id.as_str())
+                    && record.status == "completed"
+            })
+            .ok_or_else(|| "可运行版本缺少 preview-readiness 完成回执".to_string())?;
+        let current_revision = read_game_creator_agent_runtime_project_revision(root)?;
+        let readiness_gate = read_game_creator_agent_runtime_verification_gate(
+            root,
+            &readiness.agent_id,
+            &readiness.run_id,
+        )?;
+        if readiness_gate.last_verification_tool.as_deref() != Some("game.static_smoke")
+            || readiness_gate.last_verification_status.as_deref()
+                != Some(AGENT_RUNTIME_VERIFICATION_STATUS_PASSED)
+            || readiness_gate.verified_revision != Some(current_revision.revision)
+        {
+            return Err("可运行版本缺少当前 revision 的 game.static_smoke 通过凭证".to_string());
+        }
+        let contract = autonomous_playtest_completion_contract_for_state_at(root, state)?
+            .ok_or_else(|| "可运行版本缺少 preview.validate 完成合同".to_string())?;
+        let receipt = read_autonomous_playtest_receipt(root, &contract)?
+            .ok_or_else(|| "可运行版本缺少 preview.validate 成功回执".to_string())?;
+        verify_autonomous_playtest_evidence_files_at(root, &receipt)?;
+        if receipt.revision != current_revision.revision {
+            return Err(format!(
+                "可运行版本 revision 不一致：receipt={} current={}",
+                receipt.revision, current_revision.revision
+            ));
+        }
+        register_current_runnable_game_version_at(
+            root,
+            current_revision.revision,
+            &receipt.agent_id,
+            &receipt.run_id,
+            &receipt.report.path,
+        )?;
+    }
     update_manifest_task_status_at(root, &state.agent_id, status.clone())?;
     append_agent_db_record(
         root,
diff --git a/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_protocol/autonomous_completion_contract_tests.rs b/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_protocol/autonomous_completion_contract_tests.rs
index c38d8e71e..725bfa711 100644
--- a/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_protocol/autonomous_completion_contract_tests.rs
+++ b/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_protocol/autonomous_completion_contract_tests.rs
@@ -698,6 +698,138 @@ fn autonomous_preview_manifest_tasks_accept_bound_current_revision_receipts() {
     assert!(autonomous_game_build_completion_blocker_at_locked(&root, &playtest_state).is_none());
 }
 
+#[test]
+fn preview_playtest_terminal_registers_a_runnable_snapshot_before_downstream_publish_tasks_complete(
+) {
+    let (_temporary, root, parent_state, contract) =
+        autonomous_fixture("做一个完整小游戏", "autonomous-runnable-version-parent");
+    for task_id in ["publish-strategy", "publish-package"] {
+        update_manifest_task_status_at(&root, task_id, GameCreationAppTaskStatus::Pending)
+            .unwrap_or_else(|error| panic!("leave downstream {task_id} pending: {error}"));
+    }
+    let task_ids = read_manifest_for_project(&root)
+        .expect("read autonomous manifest")
+        .tasks
+        .into_iter()
+        .map(|task| task.id)
+        .collect::<Vec<_>>();
+    for task_id in task_ids {
+        if !matches!(
+            task_id.as_str(),
+            "preview-readiness" | "preview-playtest" | "publish-strategy" | "publish-package"
+        ) {
+            update_manifest_task_status_at(&root, &task_id, GameCreationAppTaskStatus::Completed)
+                .unwrap_or_else(|error| panic!("complete prerequisite {task_id}: {error}"));
+        }
+    }
+
+    update_manifest_task_status_at(
+        &root,
+        "preview-readiness",
+        GameCreationAppTaskStatus::Running,
+    )
+    .expect("mark preview readiness running");
+    let readiness_child =
+        queue_autonomous_manifest_child_fixture(&root, &parent_state, "preview-readiness");
+    let revision = advance_game_index_revision(
+        &root,
+        &parent_state,
+        "<!doctype html><title>可运行版本</title><canvas></canvas>",
+    );
+    let readiness_state = agent_runtime_state_from_task_record(&readiness_child);
+    mark_verification_passed(&root, &readiness_state, "game.static_smoke");
+    let readiness_terminal = AgentRuntimeTaskRecord {
+        status: "completed".to_string(),
+        phase: "completed".to_string(),
+        updated_at: unix_timestamp(),
+        ..readiness_child
+    };
+    append_game_creator_agent_runtime_task_record(&root, &readiness_terminal)
+        .expect("persist completed preview readiness record");
+    project_autonomous_manifest_ready_task_terminal_at(
+        &root,
+        &agent_runtime_state_from_task_record(&readiness_terminal),
+    )
+    .expect("project preview readiness completion");
+
+    update_manifest_task_status_at(
+        &root,
+        "preview-playtest",
+        GameCreationAppTaskStatus::Running,
+    )
+    .expect("mark preview playtest running");
+    let playtest_child =
+        queue_autonomous_manifest_child_fixture(&root, &parent_state, "preview-playtest");
+    let playtest_state = agent_runtime_state_from_task_record(&playtest_child);
+    let result = browser_result_fixture(
+        &root,
+        &parent_state,
+        revision,
+        BrowserPlaytestScenario::GenericV1,
+    );
+    let action = AgentRuntimeToolAction {
+        tool: "preview.validate".to_string(),
+        reason: Some("验证可运行版本".to_string()),
+        input: serde_json::json!({}),
+    };
+    let action_fingerprint =
+        agent_runtime_tool_action_fingerprint(&action, &playtest_state.current_task);
+    let action_id =
+        agent_runtime_tool_action_id(&playtest_state.run_id, 1, 0, 1, &action_fingerprint);
+    write_autonomous_playtest_receipt_at(
+        &root,
+        &contract,
+        &action_id,
+        &action_fingerprint,
+        revision,
+        &result,
+    )
+    .expect("persist runnable playtest receipt");
+    let playtest_terminal = AgentRuntimeTaskRecord {
+        status: "completed".to_string(),
+        phase: "completed".to_string(),
+        updated_at: unix_timestamp(),
+        ..playtest_child
+    };
+    append_game_creator_agent_runtime_task_record(&root, &playtest_terminal)
+        .expect("persist completed preview playtest record");
+    project_autonomous_manifest_ready_task_terminal_at(
+        &root,
+        &agent_runtime_state_from_task_record(&playtest_terminal),
+    )
+    .expect("project preview playtest and register runnable version");
+
+    let manifest = read_manifest_for_project(&root).expect("read runnable manifest");
+    assert_eq!(manifest.runnable_versions.len(), 1);
+    let version = &manifest.runnable_versions[0];
+    assert_eq!(version.project_revision, revision);
+    assert_eq!(
+        version.created_reason,
+        RunnableGameVersionCreatedReason::Initial
+    );
+    assert_eq!(
+        manifest.current_runnable_version_id.as_deref(),
+        Some(version.version_id.as_str())
+    );
+    assert!(root
+        .join(&version.artifact_path)
+        .join("game/index.html")
+        .is_file());
+    for task_id in ["publish-strategy", "publish-package"] {
+        let status = manifest
+            .tasks
+            .iter()
+            .find(|task| task.id == task_id)
+            .map(|task| &task.status)
+            .unwrap_or_else(|| panic!("missing downstream task {task_id}"));
+        assert_ne!(
+            status,
+            &GameCreationAppTaskStatus::Completed,
+            "runnable registration must not wait for downstream {task_id} completion"
+        );
+    }
+}
+
 #[test]
 fn autonomous_completion_rejects_formal_artifact_unchanged_from_run_baseline() {
     let baseline_bytes =
diff --git a/apps/ai-game-creator-shell/src-tauri/src/main.rs b/apps/ai-game-creator-shell/src-tauri/src/main.rs
index 8aa4f0b35..f068b3b24 100644
--- a/apps/ai-game-creator-shell/src-tauri/src/main.rs
+++ b/apps/ai-game-creator-shell/src-tauri/src/main.rs
@@ -23,20 +23,23 @@ use reqwest::header;
 use serde::{Deserialize, Serialize};
 use shared_contracts::game_creation_app::{
     new_game_creation_app_manifest, new_game_creation_app_seed_tasks,
-    validate_game_iteration_versions, GameCreationAgentArtifactTrace,
-    GameCreationAgentCapabilityDescriptor, GameCreationAgentPassPlanTrace,
-    GameCreationAgentRepairRouteTrace, GameCreationAgentRunStep,
+    validate_game_iteration_versions, validate_runnable_game_versions,
+    GameCreationAgentArtifactTrace, GameCreationAgentCapabilityDescriptor,
+    GameCreationAgentPassPlanTrace, GameCreationAgentRepairRouteTrace, GameCreationAgentRunStep,
     GameCreationAgentRunTaskGraphTrace, GameCreationAgentRunTrace, GameCreationAgentToolCallTrace,
     GameCreationAppAgentGroup, GameCreationAppAssetManifestEntry, GameCreationAppAssetSource,
     GameCreationAppAssetSourceKind, GameCreationAppCommandRunState,
     GameCreationAppCommandRunStatus, GameCreationAppLimitedRunCommandDescriptor,
     GameCreationAppManifest, GameCreationAppPermission, GameCreationAppPreviewState,
     GameCreationAppPreviewStatus, GameCreationAppTaskState, GameCreationAppTaskStatus,
-    ProjectResourceCanvasLayout, ProjectResourceCanvasLayoutMode, ProjectResourceCanvasPosition,
+    GameIterationVersionResourceBinding, ProjectResourceCanvasLayout,
+    ProjectResourceCanvasLayoutMode, ProjectResourceCanvasPosition, RunnableGameVersion,
+    RunnableGameVersionCreatedReason, RunnableGameVersionValidation,
     UpdateProjectResourceCanvasLayoutResult, UpdateProjectResourceCanvasLayoutStatus,
     GAME_CREATION_AGENT_CAPABILITIES, GAME_CREATION_AGENT_RUN_SCHEMA_VERSION,
     GAME_CREATION_AGENT_TOOL_CALL_MAX, GAME_CREATION_APP_COMMANDS,
     GAME_CREATION_APP_LIMITED_RUN_COMMANDS, GAME_CREATION_RESOURCE_LAYOUT_SCHEMA_VERSION,
+    RUNNABLE_GAME_VERSION_SCHEMA_VERSION,
 };
 use tauri::{Emitter, Manager};
 use tauri_plugin_dialog::DialogExt;
@@ -147,6 +150,14 @@ struct LocalPreviewStatus {
     root: Option<String>,
 }
 
+#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
+#[serde(rename_all = "camelCase")]
+struct RunnableGameVersionLaunchResult {
+    manifest: GameCreationAppManifest,
+    version: RunnableGameVersion,
+    preview: LocalPreviewResult,
+}
+
 #[derive(Clone, Debug, Eq, PartialEq, Serialize)]
 #[serde(rename_all = "camelCase")]
 struct LocalGameProjectRevisionStatus {
@@ -2380,6 +2391,7 @@ fn main() {
             open_game_creator_launcher_window,
             open_project_supervisor_chat_window,
             start_local_game_preview,
+            launch_local_game_runnable_version,
             activate_local_game_preview,
             stop_local_game_preview,
             stop_local_game_preview_if_matches,
diff --git a/apps/ai-game-creator-shell/src-tauri/src/preview.rs b/apps/ai-game-creator-shell/src-tauri/src/preview.rs
index 056d25ce3..717a5c3cf 100644
--- a/apps/ai-game-creator-shell/src-tauri/src/preview.rs
+++ b/apps/ai-game-creator-shell/src-tauri/src/preview.rs
@@ -382,6 +382,14 @@ pub(crate) fn activate_local_game_preview(
 pub(crate) fn start_local_game_preview_for_project(
     root: &Path,
 ) -> Result<(LocalPreviewResult, mpsc::Sender<()>), String> {
+    start_local_game_preview_for_served_root(root, root)
+}
+
+pub(crate) fn start_local_game_preview_for_served_root(
+    project_root: &Path,
+    served_root: &Path,
+) -> Result<(LocalPreviewResult, mpsc::Sender<()>), String> {
+    let root = project_root;
     if root.as_os_str().is_empty() {
         return Err("项目目录不能为空".to_string());
     }
@@ -389,7 +397,10 @@ pub(crate) fn start_local_game_preview_for_project(
         return Err("项目目录必须是绝对路径".to_string());
     }
 
-    let game_root = root.join("game");
+    if served_root.as_os_str().is_empty() || !served_root.is_absolute() {
+        return Err("预览产物目录无效".to_string());
+    }
+    let game_root = served_root.join("game");
     if !game_root.is_dir() {
         return Err(format!("游戏目录不存在：{}", game_root.display()));
     }
@@ -409,7 +420,7 @@ pub(crate) fn start_local_game_preview_for_project(
     listener
         .set_nonblocking(true)
         .map_err(|error| format!("设置预览监听失败：{error}"))?;
-    let served_root = root.to_path_buf();
+    let served_root = served_root.to_path_buf();
     let (stop_sender, stop_receiver) = mpsc::channel();
 
     thread::spawn(move || loop {
@@ -443,6 +454,80 @@ pub(crate) fn start_local_game_preview_for_project(
     ))
 }
 
+#[tauri::command]
+pub(crate) fn launch_local_game_runnable_version(
+    project_path: String,
+    expected_project_id: String,
+    version_id: Option<String>,
+    registry: tauri::State<'_, PreviewRegistry>,
+) -> Result<RunnableGameVersionLaunchResult, String> {
+    let root = Path::new(project_path.trim());
+    enforce_project_permission_policy(root, "preview.start")?;
+    let _lock = acquire_project_write_lock(root, "preview.start")?;
+    let current_manifest = read_existing_manifest_for_project(root)?;
+    if current_manifest.project_id != expected_project_id.trim() {
+        return Err("可运行版本项目身份不一致".to_string());
+    }
+    let version_id = version_id
+        .as_deref()
+        .map(str::trim)
+        .filter(|value| !value.is_empty())
+        .map(str::to_string)
+        .or(current_manifest.current_runnable_version_id.clone())
+        .ok_or_else(|| "当前无可运行版本".to_string())?;
+
+    let _ = registry.stop_for_project(Some(root));
+    let (_, version, artifact_root) =
+        resolve_runnable_game_version_at(root, expected_project_id.trim(), &version_id)?;
+    let (preview, stop) = match start_local_game_preview_for_served_root(root, &artifact_root) {
+        Ok(result) => result,
+        Err(error) => {
+            let _ = record_preview_state(root, GameCreationAppPreviewStatus::Failed, None, None);
+            return Err(format!("可运行版本预览启动失败：{error}"));
+        }
+    };
+    if let Err(error) = record_preview_state(
+        root,
+        GameCreationAppPreviewStatus::Running,
+        Some(preview.url.clone()),
+        Some(preview.port),
+    ) {
+        let _ = stop.send(());
+        return Err(error);
+    }
+    if let Err(error) = append_preview_log(root, "running", Some(&preview.url)) {
+        let _ = stop.send(());
+        let _ = record_preview_state(root, GameCreationAppPreviewStatus::Failed, None, None);
+        return Err(error);
+    }
+    let (preview, previous_preview) = registry.set_running(preview, stop);
+    if let Some(previous_preview) = previous_preview.as_ref() {
+        record_replaced_preview_stop(previous_preview);
+    }
+    if let Err(error) = append_preview_start_trace_step(root, &preview) {
+        let _ = registry.stop();
+        let _ = record_preview_state(root, GameCreationAppPreviewStatus::Failed, None, None);
+        return Err(error);
+    }
+    let (manifest, selected_version, _) = match select_current_runnable_game_version_at(
+        root,
+        expected_project_id.trim(),
+        &version.version_id,
+    ) {
+        Ok(selected) => selected,
+        Err(error) => {
+            let _ = registry.stop();
+            let _ = record_preview_state(root, GameCreationAppPreviewStatus::Failed, None, None);
+            return Err(error);
+        }
+    };
+    Ok(RunnableGameVersionLaunchResult {
+        manifest,
+        version: selected_version,
+        preview,
+    })
+}
+
 fn handle_preview_stream(mut stream: TcpStream, root: &Path) {
     // The listener is nonblocking so its accept loop can observe the stop channel. Windows may
     // inherit that mode on accepted sockets; switch each connection back to blocking mode before
diff --git a/apps/ai-game-creator-shell/src-tauri/src/project.rs b/apps/ai-game-creator-shell/src-tauri/src/project.rs
index 1099d78e8..fb877c095 100644
--- a/apps/ai-game-creator-shell/src-tauri/src/project.rs
+++ b/apps/ai-game-creator-shell/src-tauri/src/project.rs
@@ -12,6 +12,7 @@ mod manifest;
 mod memory;
 mod resource_dependency_graph;
 mod resource_layout;
+mod runnable_versions;
 mod verification;
 
 pub(crate) use agent_db::*;
@@ -23,4 +24,5 @@ pub(crate) use manifest::*;
 pub(crate) use memory::*;
 pub(crate) use resource_dependency_graph::*;
 pub(crate) use resource_layout::*;
+pub(crate) use runnable_versions::*;
 pub(crate) use verification::*;
diff --git a/apps/ai-game-creator-shell/src-tauri/src/project/manifest.rs b/apps/ai-game-creator-shell/src-tauri/src/project/manifest.rs
index 5fd595ec1..704e02cd2 100644
--- a/apps/ai-game-creator-shell/src-tauri/src/project/manifest.rs
+++ b/apps/ai-game-creator-shell/src-tauri/src/project/manifest.rs
@@ -635,6 +635,12 @@ pub(crate) fn read_manifest(path: &Path) -> Result<GameCreationAppManifest, Stri
         .map_err(|error| format!("解析 {label} 失败：{}: {error}", source_path.display()))?;
     validate_game_iteration_versions(&manifest.versions)
         .map_err(|error| format!("校验 {label} 项目版本失败：{error}"))?;
+    validate_runnable_game_versions(
+        &manifest.project_id,
+        &manifest.runnable_versions,
+        manifest.current_runnable_version_id.as_deref(),
+    )
+    .map_err(|error| format!("校验 {label} 可运行版本失败：{error}"))?;
     Ok(manifest)
 }
 
@@ -714,6 +720,12 @@ pub(crate) fn write_manifest(
 ) -> Result<(), String> {
     validate_game_iteration_versions(&manifest.versions)
         .map_err(|error| format!("校验 manifest 项目版本失败：{error}"))?;
+    validate_runnable_game_versions(
+        &manifest.project_id,
+        &manifest.runnable_versions,
+        manifest.current_runnable_version_id.as_deref(),
+    )
+    .map_err(|error| format!("校验 manifest 可运行版本失败：{error}"))?;
     if manifest_storage_exists(path)? {
         let existing = read_manifest(path)?;
         if existing.versions.len() > manifest.versions.len()
@@ -725,6 +737,15 @@ pub(crate) fn write_manifest(
         {
             return Err("项目版本记录写入后不可修改、删除或重排".to_string());
         }
+        if existing.runnable_versions.len() > manifest.runnable_versions.len()
+            || existing
+                .runnable_versions
+                .iter()
+                .zip(&manifest.runnable_versions)
+                .any(|(existing, candidate)| existing != candidate)
+        {
+            return Err("可运行版本记录写入后不可修改、删除或重排".to_string());
+        }
     }
     let payload = serde_json::to_string_pretty(manifest)
         .map_err(|error| format!("序列化 manifest 失败：{error}"))?;
diff --git a/apps/ai-game-creator-shell/src-tauri/src/project/runnable_versions.rs b/apps/ai-game-creator-shell/src-tauri/src/project/runnable_versions.rs
new file mode 100644
index 000000000..16820415c
--- /dev/null
+++ b/apps/ai-game-creator-shell/src-tauri/src/project/runnable_versions.rs
@@ -0,0 +1,587 @@
+use super::*;
+
+const RUNNABLE_ARTIFACT_DESCRIPTOR_SCHEMA_VERSION: &str = "game-creator-runnable-artifact.v1";
+const RUNNABLE_ARTIFACT_MAX_FILES: usize = 4_096;
+const RUNNABLE_ARTIFACT_MAX_FILE_BYTES: u64 = 64 * 1024 * 1024;
+const RUNNABLE_ARTIFACT_MAX_TOTAL_BYTES: u64 = 512 * 1024 * 1024;
+
+#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
+#[serde(deny_unknown_fields, rename_all = "camelCase")]
+struct RunnableArtifactDescriptor {
+    schema_version: String,
+    project_id: String,
+    version_id: String,
+    project_revision: u64,
+    artifact_sha256: String,
+    created_at: u64,
+}
+
+#[derive(Clone, Debug, Eq, PartialEq)]
+struct WrittenRunnableArtifactSnapshot {
+    artifact_sha256: String,
+    created_at: u64,
+}
+
+fn runnable_version_id(revision: u64) -> String {
+    format!("runnable-r{revision}")
+}
+
+fn runnable_version_root(root: &Path, version_id: &str) -> PathBuf {
+    root.join(".agent/runnable-versions").join(version_id)
+}
+
+fn collect_runnable_artifact_files(
+    base: &Path,
+    directory: &Path,
+    output: &mut Vec<(String, PathBuf, u64)>,
+    total_bytes: &mut u64,
+) -> Result<(), String> {
+    let metadata =
+        fs::symlink_metadata(directory).map_err(|_| "可运行版本源目录不存在".to_string())?;
+    if metadata.file_type().is_symlink() || !metadata.is_dir() {
+        return Err("可运行版本源目录必须是普通目录".to_string());
+    }
+    let mut entries = fs::read_dir(directory)
+        .map_err(|_| "读取可运行版本源目录失败".to_string())?
+        .collect::<Result<Vec<_>, _>>()
+        .map_err(|_| "读取可运行版本源目录失败".to_string())?;
+    entries.sort_by_key(|entry| entry.file_name());
+    for entry in entries {
+        let path = entry.path();
+        let metadata =
+            fs::symlink_metadata(&path).map_err(|_| "读取可运行版本源文件失败".to_string())?;
+        if metadata.file_type().is_symlink() {
+            return Err("可运行版本不允许包含符号链接".to_string());
+        }
+        if metadata.is_dir() {
+            collect_runnable_artifact_files(base, &path, output, total_bytes)?;
+            continue;
+        }
+        if !metadata.is_file() {
+            return Err("可运行版本只允许包含普通文件".to_string());
+        }
+        if metadata.len() > RUNNABLE_ARTIFACT_MAX_FILE_BYTES {
+            return Err("可运行版本包含超限文件".to_string());
+        }
+        *total_bytes = total_bytes
+            .checked_add(metadata.len())
+            .ok_or_else(|| "可运行版本总大小已溢出".to_string())?;
+        if *total_bytes > RUNNABLE_ARTIFACT_MAX_TOTAL_BYTES {
+            return Err("可运行版本总大小超过 512 MiB".to_string());
+        }
+        let relative = path
+            .strip_prefix(base)
+            .map_err(|_| "可运行版本源路径越界".to_string())?
+            .components()
+            .map(|component| component.as_os_str().to_string_lossy())
+            .collect::<Vec<_>>()
+            .join("/");
+        if relative.is_empty() || relative.chars().any(char::is_control) {
+            return Err("可运行版本源路径无效".to_string());
+        }
+        output.push((relative, path, metadata.len()));
+        if output.len() > RUNNABLE_ARTIFACT_MAX_FILES {
+            return Err("可运行版本文件数量超过 4096".to_string());
+        }
+    }
+    Ok(())
+}
+
+fn read_runnable_source_file(path: &Path, expected_len: u64) -> Result<Vec<u8>, String> {
+    let mut options = fs::OpenOptions::new();
+    options.read(true);
+    #[cfg(unix)]
+    {
+        use std::os::unix::fs::OpenOptionsExt;
+        options.custom_flags(libc::O_NOFOLLOW);
+    }
+    let mut file = options
+        .open(path)
+        .map_err(|_| "读取可运行版本源文件失败".to_string())?;
+    let metadata = file
+        .metadata()
+        .map_err(|_| "读取可运行版本源文件元数据失败".to_string())?;
+    if !metadata.is_file() || metadata.len() != expected_len {
+        return Err("可运行版本源文件在登记期间发生变化".to_string());
+    }
+    let mut bytes = Vec::with_capacity(usize::try_from(expected_len).unwrap_or(0));
+    file.read_to_end(&mut bytes)
+        .map_err(|_| "读取可运行版本源文件失败".to_string())?;
+    if u64::try_from(bytes.len()).ok() != Some(expected_len) {
+        return Err("可运行版本源文件在登记期间发生变化".to_string());
+    }
+    Ok(bytes)
+}
+
+fn hash_runnable_artifact_files(files: &[(String, Vec<u8>)]) -> String {
+    let mut hasher = Sha256::new();
+    for (relative, bytes) in files {
+        hasher.update((relative.len() as u64).to_be_bytes());
+        hasher.update(relative.as_bytes());
+        hasher.update((bytes.len() as u64).to_be_bytes());
+        hasher.update(bytes);
+    }
+    format!("{:x}", hasher.finalize())
+}
+
+fn read_runnable_artifact_files(root: &Path) -> Result<Vec<(String, Vec<u8>)>, String> {
+    let mut sources = Vec::new();
+    let mut total_bytes = 0;
+    collect_runnable_artifact_files(root, &root.join("game"), &mut sources, &mut total_bytes)?;
+    let assets = root.join("assets");
+    if assets.exists() {
+        collect_runnable_artifact_files(root, &assets, &mut sources, &mut total_bytes)?;
+    }
+    sources.sort_by(|left, right| left.0.cmp(&right.0));
+    sources
+        .into_iter()
+        .map(|(relative, path, expected_len)| {
+            read_runnable_source_file(&path, expected_len).map(|bytes| (relative, bytes))
+        })
+        .collect()
+}
+
+fn write_runnable_artifact_snapshot(
+    root: &Path,
+    project_id: &str,
+    version_id: &str,
+    revision: u64,
+    created_at: u64,
+) -> Result<WrittenRunnableArtifactSnapshot, String> {
+    let files = read_runnable_artifact_files(root)?;
+    if !files.iter().any(|(path, _)| path == "game/index.html") {
+        return Err("项目完整性检查失败：缺少 game/index.html".to_string());
+    }
+    let artifact_sha256 = hash_runnable_artifact_files(&files);
+    let versions_root = root.join(".agent/runnable-versions");
+    fs::create_dir_all(&versions_root).map_err(|_| "创建可运行版本目录失败".to_string())?;
+    let final_root = runnable_version_root(root, version_id);
+    if final_root.exists() {
+        let final_metadata = fs::symlink_metadata(&final_root)
+            .map_err(|_| "可运行版本快照冲突：无法读取已有版本目录".to_string())?;
+        if final_metadata.file_type().is_symlink() || !final_metadata.is_dir() {
+            return Err("可运行版本快照冲突：已有版本目录无效".to_string());
+        }
+        let descriptor_path = final_root.join("version.json");
+        let descriptor_metadata = fs::symlink_metadata(&descriptor_path)
+            .map_err(|_| "可运行版本快照冲突：无法读取已有版本描述".to_string())?;
+        if descriptor_metadata.file_type().is_symlink() || !descriptor_metadata.is_file() {
+            return Err("可运行版本快照冲突：已有版本描述不是普通文件".to_string());
+        }
+        let descriptor = serde_json::from_str::<RunnableArtifactDescriptor>(
+            &fs::read_to_string(&descriptor_path)
+                .map_err(|_| "可运行版本快照冲突：无法读取已有版本描述".to_string())?,
+        )
+        .map_err(|_| "可运行版本快照冲突：已有版本描述无效".to_string())?;
+        if descriptor.schema_version != RUNNABLE_ARTIFACT_DESCRIPTOR_SCHEMA_VERSION
+            || descriptor.project_id != project_id
+            || descriptor.version_id != version_id
+            || descriptor.project_revision != revision
+        {
+            return Err("可运行版本快照冲突：已有版本身份或 revision 不一致".to_string());
+        }
+        let existing_files = read_runnable_artifact_files(&final_root.join("artifact"))
+            .map_err(|error| format!("可运行版本快照冲突：{error}"))?;
+        let existing_sha256 = hash_runnable_artifact_files(&existing_files);
+        if existing_sha256 != descriptor.artifact_sha256
+            || descriptor.artifact_sha256 != artifact_sha256
+        {
+            return Err("可运行版本快照冲突：已有版本产物摘要不一致".to_string());
+        }
+        return Ok(WrittenRunnableArtifactSnapshot {
+            artifact_sha256: descriptor.artifact_sha256,
+            created_at: descriptor.created_at,
+        });
+    }
+    let stage_root = versions_root.join(format!(
+        ".tmp-{version_id}-{}-{}",
+        std::process::id(),
+        SystemTime::now()
+            .duration_since(UNIX_EPOCH)
+            .unwrap_or_default()
+            .as_nanos()
+    ));
+    let stage_artifact = stage_root.join("artifact");
+    let install_result = (|| {
+        for (relative, bytes) in &files {
+            let target = stage_artifact.join(relative);
+            if let Some(parent) = target.parent() {
+                fs::create_dir_all(parent).map_err(|_| "创建可运行版本快照目录失败".to_string())?;
+            }
+            fs::write(&target, bytes).map_err(|_| "写入可运行版本快照失败".to_string())?;
+        }
+        let descriptor = RunnableArtifactDescriptor {
+            schema_version: RUNNABLE_ARTIFACT_DESCRIPTOR_SCHEMA_VERSION.to_string(),
+            project_id: project_id.to_string(),
+            version_id: version_id.to_string(),
+            project_revision: revision,
+            artifact_sha256: artifact_sha256.clone(),
+            created_at,
+        };
+        let payload = serde_json::to_string_pretty(&descriptor)
+            .map_err(|_| "序列化可运行版本描述失败".to_string())?;
+        fs::write(stage_root.join("version.json"), format!("{payload}\n"))
+            .map_err(|_| "写入可运行版本描述失败".to_string())?;
+        fs::rename(&stage_root, &final_root).map_err(|_| "安装可运行版本快照失败".to_string())?;
+        Ok(())
+    })();
+    if install_result.is_err() {
+        let _ = fs::remove_dir_all(&stage_root);
+    }
+    install_result.map(|()| WrittenRunnableArtifactSnapshot {
+        artifact_sha256,
+        created_at,
+    })
+}
+
+pub(crate) fn validate_runnable_game_version_artifact_at(
+    root: &Path,
+    version: &RunnableGameVersion,
+) -> Result<PathBuf, String> {
+    let version_root = runnable_version_root(root, &version.version_id);
+    let version_root_metadata = fs::symlink_metadata(&version_root)
+        .map_err(|_| "可运行版本已损坏：版本目录不存在".to_string())?;
+    if version_root_metadata.file_type().is_symlink() || !version_root_metadata.is_dir() {
+        return Err("可运行版本已损坏：版本目录无效".to_string());
+    }
+    let descriptor_path = version_root.join("version.json");
+    let metadata = fs::symlink_metadata(&descriptor_path)
+        .map_err(|_| "可运行版本已损坏：版本描述不存在".to_string())?;
+    if metadata.file_type().is_symlink() || !metadata.is_file() {
+        return Err("可运行版本已损坏：版本描述不是普通文件".to_string());
+    }
+    let descriptor = serde_json::from_str::<RunnableArtifactDescriptor>(
+        &fs::read_to_string(&descriptor_path)
+            .map_err(|_| "可运行版本已损坏：无法读取版本描述".to_string())?,
+    )
+    .map_err(|_| "可运行版本已损坏：版本描述无效".to_string())?;
+    if descriptor.schema_version != RUNNABLE_ARTIFACT_DESCRIPTOR_SCHEMA_VERSION
+        || descriptor.project_id != version.project_id
+        || descriptor.version_id != version.version_id
+    {
+        return Err("可运行版本已损坏：版本身份不一致".to_string());
+    }
+    if descriptor.project_revision != version.project_revision {
+        return Err("可运行版本 revision 不一致".to_string());
+    }
+    if descriptor.artifact_sha256 != version.artifact_sha256
+        || descriptor.created_at != version.created_at
+    {
+        return Err("可运行版本已损坏：版本描述与 manifest 不一致".to_string());
+    }
+    let artifact_root = version_root.join("artifact");
+    let files = read_runnable_artifact_files(&artifact_root)
+        .map_err(|error| format!("可运行版本已损坏：{error}"))?;
+    if hash_runnable_artifact_files(&files) != version.artifact_sha256 {
+        return Err("可运行版本已损坏：产物摘要不一致".to_string());
+    }
+    Ok(artifact_root)
+}
+
+pub(crate) fn register_current_runnable_game_version_at(
+    root: &Path,
+    revision: u64,
+    validation_agent_id: &str,
+    validation_run_id: &str,
+    report_path: &str,
+) -> Result<RunnableGameVersion, String> {
+    let manifest_path = root.join(".agent/manifest.json");
+    let mut manifest = read_manifest(&manifest_path)?;
+    if let Some(existing) = manifest
+        .runnable_versions
+        .iter()
+        .find(|version| version.project_revision == revision)
+    {
+        validate_runnable_game_version_artifact_at(root, existing)?;
+        return Ok(existing.clone());
+    }
+    if manifest
+        .runnable_versions
+        .last()
+        .is_some_and(|version| version.project_revision >= revision)
+    {
+        return Err("可运行版本 revision 必须严格递增".to_string());
+    }
+    let version_id = runnable_version_id(revision);
+    let created_at = unix_timestamp_millis();
+    let snapshot = write_runnable_artifact_snapshot(
+        root,
+        &manifest.project_id,
+        &version_id,
+        revision,
+        created_at,
+    )?;
+    let created_at = snapshot.created_at;
+    let parent_version_id = manifest
+        .runnable_versions
+        .last()
+        .map(|version| version.version_id.clone());
+    let created_reason = if parent_version_id.is_some() {
+        RunnableGameVersionCreatedReason::AgentRevision
+    } else {
+        RunnableGameVersionCreatedReason::Initial
+    };
+    let mut resource_bindings = manifest
+        .assets
+        .iter()
+        .map(|asset| GameIterationVersionResourceBinding {
+            slot_id: asset.id.clone(),
+            resource_id: asset.id.clone(),
+        })
+        .collect::<Vec<_>>();
+    resource_bindings.sort_by(|left, right| left.slot_id.cmp(&right.slot_id));
+    let version = RunnableGameVersion {
+        schema_version: RUNNABLE_GAME_VERSION_SCHEMA_VERSION.to_string(),
+        version_id: version_id.clone(),
+        project_id: manifest.project_id.clone(),
+        parent_version_id,
+        project_revision: revision,
+        artifact_path: format!(".agent/runnable-versions/{version_id}/artifact"),
+        artifact_sha256: snapshot.artifact_sha256,
+        entry_path: "game/index.html".to_string(),
+        resource_bindings,
+        created_reason,
+        validation: RunnableGameVersionValidation {
+            static_smoke_passed: true,
+            preview_validate_passed: true,
+            playtest_passed: true,
+            agent_id: validation_agent_id.to_string(),
+            run_id: validation_run_id.to_string(),
+            report_path: report_path.to_string(),
+        },
+        created_at,
+    };
+    manifest.runnable_versions.push(version.clone());
+    manifest.current_runnable_version_id = Some(version.version_id.clone());
+    write_manifest(&manifest_path, &manifest)?;
+    // manifest 是可运行版本的唯一事实源；快照和 manifest 已提交后，审计写入失败
+    // 不能再把一次成功登记伪装成失败，否则重试会看到版本存在却缺少首轮成功结果。
+    let _ = append_agent_db_record(
+        root,
+        serde_json::json!({
+            "recordType": "project.runnable_version.registered",
+            "versionId": version.version_id,
+            "projectRevision": version.project_revision,
+            "parentVersionId": version.parent_version_id,
+            "artifactSha256": version.artifact_sha256,
+            "validationAgentId": validation_agent_id,
+            "validationRunId": validation_run_id,
+        }),
+    );
+    Ok(version)
+}
+
+pub(crate) fn select_current_runnable_game_version_at(
+    root: &Path,
+    expected_project_id: &str,
+    version_id: &str,
+) -> Result<(GameCreationAppManifest, RunnableGameVersion, PathBuf), String> {
+    let (mut manifest, version, artifact_root) =
+        resolve_runnable_game_version_at(root, expected_project_id, version_id)?;
+    let manifest_path = root.join(".agent/manifest.json");
+    manifest.current_runnable_version_id = Some(version.version_id.clone());
+    write_manifest(&manifest_path, &manifest)?;
+    Ok((manifest, version, artifact_root))
+}
+
+pub(crate) fn resolve_runnable_game_version_at(
+    root: &Path,
+    expected_project_id: &str,
+    version_id: &str,
+) -> Result<(GameCreationAppManifest, RunnableGameVersion, PathBuf), String> {
+    let manifest_path = root.join(".agent/manifest.json");
+    let manifest = read_manifest(&manifest_path)?;
+    if manifest.project_id != expected_project_id {
+        return Err("可运行版本项目身份不一致".to_string());
+    }
+    let version = manifest
+        .runnable_versions
+        .iter()
+        .find(|version| version.version_id == version_id)
+        .cloned()
+        .ok_or_else(|| "当前无可运行版本".to_string())?;
+    let artifact_root = validate_runnable_game_version_artifact_at(root, &version)?;
+    Ok((manifest, version, artifact_root))
+}
+
+fn unix_timestamp_millis() -> u64 {
+    SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .unwrap_or_default()
+        .as_millis()
+        .try_into()
+        .unwrap_or(u64::MAX)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn runnable_version_test_root(label: &str) -> PathBuf {
+        std::env::temp_dir().join(format!(
+            "genarrative-runnable-version-{label}-{}-{}",
+            std::process::id(),
+            SystemTime::now()
+                .duration_since(UNIX_EPOCH)
+                .unwrap_or_default()
+                .as_nanos()
+        ))
+    }
+
+    fn init_runnable_version_test_project(label: &str) -> PathBuf {
+        let root = runnable_version_test_root(label);
+        fs::create_dir_all(root.join("game")).expect("create game directory");
+        fs::create_dir_all(root.join("assets")).expect("create assets directory");
+        fs::write(root.join("game/index.html"), "<main>revision one</main>")
+            .expect("write game entry");
+        fs::write(root.join("assets/player.txt"), "player one").expect("write game asset");
+        let manifest = new_game_creation_app_manifest(
+            format!("project-{label}"),
+            format!("可运行版本测试 {label}"),
+        );
+        write_manifest(&root.join(".agent/manifest.json"), &manifest)
+            .expect("write project manifest");
+        root
+    }
+
+    fn register_test_version(root: &Path, revision: u64) -> RunnableGameVersion {
+        register_current_runnable_game_version_at(
+            root,
+            revision,
+            "program-agent",
+            &format!("run-{revision}"),
+            &format!(
+                ".agent/runtime/browser-validations/program-agent/run-{revision}/1/validation.json"
+            ),
+        )
+        .expect("register runnable version")
+    }
+
+    #[test]
+    fn runnable_versions_register_idempotently_and_keep_immutable_snapshots() {
+        let root = init_runnable_version_test_project("register");
+        let first = register_test_version(&root, 1);
+        assert_eq!(first.version_id, "runnable-r1");
+        assert_eq!(first.parent_version_id, None);
+        assert_eq!(
+            first.created_reason,
+            RunnableGameVersionCreatedReason::Initial
+        );
+        assert_eq!(
+            fs::read_to_string(
+                root.join(".agent/runnable-versions/runnable-r1/artifact/game/index.html")
+            )
+            .expect("read first snapshot"),
+            "<main>revision one</main>"
+        );
+
+        fs::write(root.join("game/index.html"), "<main>revision two</main>")
+            .expect("update working tree");
+        fs::write(root.join("assets/player.txt"), "player two").expect("update working tree asset");
+        assert_eq!(register_test_version(&root, 1), first);
+
+        let second = register_test_version(&root, 2);
+        assert_eq!(second.parent_version_id.as_deref(), Some("runnable-r1"));
+        assert_eq!(
+            second.created_reason,
+            RunnableGameVersionCreatedReason::AgentRevision
+        );
+        assert_ne!(second.artifact_sha256, first.artifact_sha256);
+        assert_eq!(
+            fs::read_to_string(
+                root.join(".agent/runnable-versions/runnable-r1/artifact/game/index.html")
+            )
+            .expect("read unchanged first snapshot"),
+            "<main>revision one</main>"
+        );
+
+        let manifest =
+            read_manifest(&root.join(".agent/manifest.json")).expect("read registered manifest");
+        assert_eq!(manifest.runnable_versions, vec![first, second.clone()]);
+        assert_eq!(
+            manifest.current_runnable_version_id.as_deref(),
+            Some(second.version_id.as_str())
+        );
+        fs::remove_dir_all(root).ok();
+    }
+
+    #[test]
+    fn runnable_snapshot_retry_reuses_original_descriptor_timestamp() {
+        let root = init_runnable_version_test_project("orphan-retry");
+        let project_id = "project-orphan-retry";
+        let first = write_runnable_artifact_snapshot(&root, project_id, "runnable-r1", 1, 100)
+            .expect("write orphan snapshot");
+        let retried = write_runnable_artifact_snapshot(&root, project_id, "runnable-r1", 1, 200)
+            .expect("reuse orphan snapshot");
+        assert_eq!(retried, first);
+        assert_eq!(retried.created_at, 100);
+        fs::remove_dir_all(root).ok();
+    }
+
+    #[test]
+    fn runnable_version_validation_rejects_digest_and_revision_tampering() {
+        let root = init_runnable_version_test_project("tamper");
+        let version = register_test_version(&root, 1);
+        let snapshot_entry =
+            root.join(".agent/runnable-versions/runnable-r1/artifact/game/index.html");
+        fs::write(&snapshot_entry, "<main>tampered</main>").expect("tamper snapshot");
+        let error = validate_runnable_game_version_artifact_at(&root, &version)
+            .expect_err("reject digest tampering");
+        assert!(error.contains("产物摘要不一致"), "{error}");
+
+        fs::write(&snapshot_entry, "<main>revision one</main>").expect("restore snapshot");
+        let descriptor_path = root.join(".agent/runnable-versions/runnable-r1/version.json");
+        let mut descriptor = serde_json::from_str::<RunnableArtifactDescriptor>(
+            &fs::read_to_string(&descriptor_path).expect("read descriptor"),
+        )
+        .expect("parse descriptor");
+        descriptor.project_revision = 2;
+        fs::write(
+            &descriptor_path,
+            format!(
+                "{}\n",
+                serde_json::to_string_pretty(&descriptor).expect("serialize descriptor")
+            ),
+        )
+        .expect("tamper descriptor revision");
+        let error = validate_runnable_game_version_artifact_at(&root, &version)
+            .expect_err("reject revision tampering");
+        assert_eq!(error, "可运行版本 revision 不一致");
+        fs::remove_dir_all(root).ok();
+    }
+
+    #[test]
+    fn runnable_version_selection_serves_snapshot_and_manifest_history_is_append_only() {
+        let root = init_runnable_version_test_project("select");
+        let version = register_test_version(&root, 1);
+        fs::write(root.join("game/index.html"), "<main>unverified edit</main>")
+            .expect("edit working tree after registration");
+
+        let (selected_manifest, selected, artifact_root) =
+            select_current_runnable_game_version_at(&root, "project-select", &version.version_id)
+                .expect("select registered version");
+        assert_eq!(selected, version);
+        assert_eq!(
+            fs::read_to_string(artifact_root.join("game/index.html"))
+                .expect("read selected snapshot"),
+            "<main>revision one</main>"
+        );
+        assert_eq!(
+            selected_manifest.current_runnable_version_id.as_deref(),
+            Some("runnable-r1")
+        );
+
+        let manifest_path = root.join(".agent/manifest.json");
+        let stable_payload = fs::read(&manifest_path).expect("read stable manifest");
+        let mut mutated = selected_manifest;
+        mutated.runnable_versions[0].artifact_sha256 = "b".repeat(64);
+        let error = write_manifest(&manifest_path, &mutated)
+            .expect_err("reject mutation of registered version");
+        assert!(error.contains("不可修改、删除或重排"), "{error}");
+        assert_eq!(
+            fs::read(&manifest_path).expect("read unchanged manifest"),
+            stable_payload
+        );
+        fs::remove_dir_all(root).ok();
+    }
+}
diff --git a/apps/ai-game-creator-shell/src-tauri/src/tests/project.rs b/apps/ai-game-creator-shell/src-tauri/src/tests/project.rs
index 48305afff..2f638d6bb 100644
--- a/apps/ai-game-creator-shell/src-tauri/src/tests/project.rs
+++ b/apps/ai-game-creator-shell/src-tauri/src/tests/project.rs
@@ -3221,6 +3221,39 @@ fn local_preview_server_serves_game_index() {
     fs::remove_dir_all(root).ok();
 }
 
+#[test]
+fn local_preview_can_serve_an_immutable_version_snapshot_instead_of_the_working_tree() {
+    let root = unique_project_path();
+    init_local_game_project_at(&root, "project-snapshot", "快照预览测试").expect("project init");
+    fs::write(root.join("game/index.html"), "<main>working tree</main>")
+        .expect("write working tree game");
+    let snapshot_root = root.join(".agent/runnable-versions/runnable-r1/artifact");
+    fs::create_dir_all(snapshot_root.join("game")).expect("create snapshot game directory");
+    fs::create_dir_all(snapshot_root.join("assets")).expect("create snapshot assets directory");
+    fs::write(
+        snapshot_root.join("game/index.html"),
+        "<main>immutable snapshot</main>",
+    )
+    .expect("write snapshot game");
+
+    let (preview, stop) = start_local_game_preview_for_served_root(&root, &snapshot_root)
+        .expect("snapshot preview start");
+    let mut stream = TcpStream::connect(("127.0.0.1", preview.port)).expect("preview connect");
+    stream
+        .write_all(b"GET / HTTP/1.1\r\nHost: 127.0.0.1\r\n\r\n")
+        .expect("request");
+    let mut response = String::new();
+    stream.read_to_string(&mut response).expect("response");
+
+    assert!(response.contains("200 OK"), "{response}");
+    assert!(response.contains("immutable snapshot"), "{response}");
+    assert!(!response.contains("working tree"), "{response}");
+    assert_eq!(preview.root, root.to_string_lossy());
+
+    let _ = stop.send(());
+    fs::remove_dir_all(root).ok();
+}
+
 #[test]
 fn local_preview_server_drains_split_browser_headers_before_response() {
     let root = unique_project_path();
diff --git a/apps/ai-game-creator-shell/src/App.tsx b/apps/ai-game-creator-shell/src/App.tsx
index 7d2652110..82c57a8a6 100644
--- a/apps/ai-game-creator-shell/src/App.tsx
+++ b/apps/ai-game-creator-shell/src/App.tsx
@@ -566,6 +566,7 @@ type AppProps = {
   gameChatOnly?: boolean;
   initialSupervisorMessage?: string;
   onPreviewChange?: (preview: GameCreationAppPreviewState | null) => void;
+  onManifestChange?: (manifest: GameCreationAppManifest) => void;
   onAgentRuntimeSummariesChange?: (
     summaries: ProjectAgentRuntimeSummary[],
   ) => void;
@@ -580,6 +581,7 @@ export function App({
   gameChatOnly = false,
   initialSupervisorMessage = '',
   onPreviewChange,
+  onManifestChange,
   onAgentRuntimeSummariesChange,
   onAgentResultsChange,
 }: AppProps = {}) {
@@ -609,6 +611,11 @@ export function App({
   const [manifest, setManifest] = useState<GameCreationAppManifest>(
     initialProjectManifest ?? seedManifest,
   );
+  useEffect(() => {
+    if (projectSupervisorOnly) {
+      onManifestChange?.(manifest);
+    }
+  }, [manifest, onManifestChange, projectSupervisorOnly]);
   const [projectStatus, setProjectStatus] = useState(
     eagerSupervisorProject ? '已初始化' : '未初始化',
   );
diff --git a/apps/ai-game-creator-shell/src/features/app-shell/WorkspaceLauncher.tsx b/apps/ai-game-creator-shell/src/features/app-shell/WorkspaceLauncher.tsx
index e9a84d703..f4f88dc1b 100644
--- a/apps/ai-game-creator-shell/src/features/app-shell/WorkspaceLauncher.tsx
+++ b/apps/ai-game-creator-shell/src/features/app-shell/WorkspaceLauncher.tsx
@@ -51,6 +51,7 @@ export function WorkspaceLauncherShell({
     setAgentRuntimeSummaries: setActiveProjectAgentRuntimeSummaries,
     activeProjectAgentResults,
     setAgentResults: setActiveProjectAgentResults,
+    updateCurrentProjectManifest,
     resetLauncherHomeDraft,
     createHomeDraft,
     openProject,
@@ -157,6 +158,8 @@ export function WorkspaceLauncherShell({
             agentResults={activeProjectAgentResults}
             onHomeOpen={() => setLauncherView('home')}
             onProjectsOpen={() => setLauncherView('projects')}
+            onManifestChange={updateCurrentProjectManifest}
+            onPreviewChange={setActiveProjectPreview}
             supervisor={
               <ProjectSupervisor
                 key={currentProjectContext.projectPath}
@@ -164,6 +167,7 @@ export function WorkspaceLauncherShell({
                 initialProjectManifest={currentProjectContext.manifest}
                 projectSupervisorOnly
                 onPreviewChange={setActiveProjectPreview}
+                onManifestChange={updateCurrentProjectManifest}
                 onAgentRuntimeSummariesChange={
                   setActiveProjectAgentRuntimeSummaries
                 }
diff --git a/apps/ai-game-creator-shell/src/features/app-shell/model.ts b/apps/ai-game-creator-shell/src/features/app-shell/model.ts
index 624d2bec5..183fbe3db 100644
--- a/apps/ai-game-creator-shell/src/features/app-shell/model.ts
+++ b/apps/ai-game-creator-shell/src/features/app-shell/model.ts
@@ -35,6 +35,7 @@ export type ProjectSupervisorComponentProps = {
   initialProjectManifest?: GameCreationAppManifest;
   projectSupervisorOnly?: boolean;
   onPreviewChange?: (preview: GameCreationAppPreviewState | null) => void;
+  onManifestChange?: (manifest: GameCreationAppManifest) => void;
   onAgentRuntimeSummariesChange?: (
     summaries: ProjectAgentRuntimeSummary[],
   ) => void;
diff --git a/apps/ai-game-creator-shell/src/features/app-shell/useHomeProjectCreation.ts b/apps/ai-game-creator-shell/src/features/app-shell/useHomeProjectCreation.ts
index 9d15570cb..af7ce9a9a 100644
--- a/apps/ai-game-creator-shell/src/features/app-shell/useHomeProjectCreation.ts
+++ b/apps/ai-game-creator-shell/src/features/app-shell/useHomeProjectCreation.ts
@@ -2,6 +2,7 @@ import {
   type Dispatch,
   type FormEvent,
   type SetStateAction,
+  useCallback,
   useState,
 } from 'react';
 
@@ -96,6 +97,16 @@ export function useHomeProjectCreation({
     rememberRecentWorkspace(context.projectPath);
   }
 
+  const updateCurrentProjectManifest = useCallback((manifest: GameCreationAppManifest) => {
+    setCurrentProjectContext((current) =>
+      current && current.manifest.projectId === manifest.projectId
+        ? current.manifest === manifest
+          ? current
+          : { ...current, manifest }
+        : current,
+    );
+  }, []);
+
   async function importHomeAttachments(
     invoke: TauriInvoke,
     nextProjectPath: string,
@@ -436,6 +447,7 @@ export function useHomeProjectCreation({
     setAgentRuntimeSummaries,
     activeProjectAgentResults,
     setAgentResults,
+    updateCurrentProjectManifest,
     pendingNonEmptyProject,
     resetLauncherHomeDraft,
     createHomeDraft,
diff --git a/apps/ai-game-creator-shell/src/styles.css b/apps/ai-game-creator-shell/src/styles.css
index d80e496b0..3d311811c 100644
--- a/apps/ai-game-creator-shell/src/styles.css
+++ b/apps/ai-game-creator-shell/src/styles.css
@@ -4038,6 +4038,14 @@ iframe.preview-frame {
     0 0 0 2px rgb(216 115 66 / 14%);
 }
 
+.game-resource-card.is-current-version {
+  border-color: #c85f31;
+  background: #fff7f1;
+  box-shadow:
+    0 8px 22px rgb(195 105 62 / 18%),
+    inset 0 0 0 2px rgb(216 115 66 / 16%);
+}
+
 .game-resource-card-icon {
   display: grid;
   grid-row: 1 / 4;
@@ -4423,6 +4431,25 @@ iframe.preview-frame {
   background: #fffdfa;
 }
 
+.game-run-version-picker {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  color: #76574a;
+  font-size: 10px;
+  font-weight: 700;
+}
+
+.game-run-version-picker select {
+  min-width: 190px;
+  height: 30px;
+  border: 1px solid #e4cfc4;
+  border-radius: 9px;
+  background: #fff;
+  color: #65483d;
+  font-size: 10px;
+}
+
 .game-run-preview {
   position: relative;
   display: grid;
@@ -4497,10 +4524,17 @@ iframe.preview-frame {
 
 .game-run-panels {
   display: grid;
-  grid-template-columns: repeat(2, minmax(0, 1fr));
+  grid-template-columns: minmax(0, 1fr);
   gap: 10px;
 }
 
+.game-run-status {
+  margin: 0;
+  color: #8b634f;
+  font-size: 10px;
+  text-align: center;
+}
+
 .game-run-panels > section {
   display: grid;
   align-content: start;
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 11b813a51..f2ae126da 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
@@ -1,6 +1,4 @@
 import {
-  ChevronLeft,
-  ChevronRight,
   FileText,
   FolderTree,
   Gamepad2,
@@ -8,11 +6,8 @@ import {
   Info,
   ListFilter,
   Music2,
-  Pause,
-  Play,
   Search,
   Settings2,
-  SlidersHorizontal,
   Sparkles,
   X,
 } from 'lucide-react';
@@ -35,7 +30,9 @@ import type {
   GameCreationAppManifest,
   GameCreationAppPreviewState,
   ProjectResourceCanvasLayoutMode,
+  RunnableGameVersion,
 } from '../../../../../packages/shared/src/contracts/gameCreationApp';
+import { resolveTauriInvoke } from '../../app/tauri';
 import {
   LocalGamePreviewFrame,
   resolveEmbeddedPreviewUrl,
@@ -150,6 +147,18 @@ export type ProjectDevelopmentViewProps = {
   supervisor: ReactNode;
   onHomeOpen: () => void;
   onProjectsOpen: () => void;
+  onManifestChange?: (manifest: GameCreationAppManifest) => void;
+  onPreviewChange?: (preview: GameCreationAppPreviewState | null) => void;
+};
+
+type RunnableGameVersionLaunchResult = {
+  manifest: GameCreationAppManifest;
+  version: RunnableGameVersion;
+  preview: {
+    url: string;
+    port: number;
+    root: string;
+  };
 };
 
 const categoryOrder: ResourceCategory[] = [
@@ -354,6 +363,7 @@ function summarizeAgent(
 const ResourceCard = memo(function ResourceCard({
   resource,
   selected,
+  currentVersion,
   relationState,
   x,
   y,
@@ -361,6 +371,7 @@ const ResourceCard = memo(function ResourceCard({
 }: {
   resource: ProjectResource;
   selected: boolean;
+  currentVersion: boolean;
   relationState: 'version-binding' | null;
   x: number;
   y: number;
@@ -371,6 +382,8 @@ const ResourceCard = memo(function ResourceCard({
     <button
       type="button"
       className={`game-resource-card${selected ? ' is-selected' : ''}${
+        currentVersion ? ' is-current-version' : ''
+      }${
         relationState ? ` is-relation-${relationState}` : ''
       }`}
       aria-pressed={selected}
@@ -409,6 +422,8 @@ export default function ProjectDevelopmentView({
   agentRuntimeSummaries = emptyProjectAgentRuntimeSummaries,
   agentResults = emptyProjectAgentResults,
   supervisor,
+  onManifestChange,
+  onPreviewChange,
 }: ProjectDevelopmentViewProps) {
   const [mode, setMode] = useState<WorkbenchMode>('resources');
   const [sortMode, setSortMode] = useState<ResourceSortMode>('dependency');
@@ -423,8 +438,13 @@ export default function ProjectDevelopmentView({
   const [approvalDialogOpen, setApprovalDialogOpen] = useState(false);
   const [approvalNotice, setApprovalNotice] = useState('');
   const [showAllAgentGroups, setShowAllAgentGroups] = useState(false);
-  const [runPlaying, setRunPlaying] = useState(false);
-  const [activeSlice, setActiveSlice] = useState(0);
+  const [runStatus, setRunStatus] = useState('');
+  const [runSwitching, setRunSwitching] = useState(false);
+  const [selectedRunnableVersionId, setSelectedRunnableVersionId] = useState(
+    manifest.currentRunnableVersionId ?? '',
+  );
+  const [activeRunnablePreviewVersionId, setActiveRunnablePreviewVersionId] =
+    useState<string | null>(null);
   const [imagePreview, setImagePreview] = useState<ImagePreviewState>({
     status: 'idle',
     resourceId: null,
@@ -443,13 +463,22 @@ export default function ProjectDevelopmentView({
   const resourceListScrollRef = useRef({ left: 0, top: 0 });
   const restoreResourceListScrollRef = useRef(false);
 
-  const preview = previewOverride ?? manifest.preview ?? null;
-  const embeddedPreviewUrl = resolveEmbeddedPreviewUrl(preview);
-  const runAvailable =
-    embeddedPreviewUrl !== null ||
-    manifest.tasks.some(
-      (task) => task.id === 'code-prototype' && task.status === 'completed',
-    );
+  const preview =
+    previewOverride !== undefined
+      ? previewOverride
+      : (manifest.preview ?? null);
+  const runnableVersions = manifest.runnableVersions ?? [];
+  const currentRunnableVersionId =
+    selectedRunnableVersionId || manifest.currentRunnableVersionId || '';
+  const currentRunnableVersion =
+    runnableVersions.find(
+      (version) => version.versionId === currentRunnableVersionId,
+    ) ?? null;
+  const embeddedPreviewUrl =
+    activeRunnablePreviewVersionId === currentRunnableVersionId
+      ? resolveEmbeddedPreviewUrl(preview)
+      : null;
+  const runAvailable = runnableVersions.length > 0 && currentRunnableVersion !== null;
   const projectedResources = useMemo(
     () => projectResourcesFromReadModels(manifest, attachments, agentResults),
     [agentResults, attachments, manifest],
@@ -602,14 +631,13 @@ export default function ProjectDevelopmentView({
     [resourceLayout.positions],
   );
   const selectedVersionBindingResourceIds = useMemo(() => {
-    const selectedVersion = resources.find(
-      (resource) => resource.id === selectedResourceId,
-    )?.version;
-    if (!selectedVersion) {
+    if (!currentRunnableVersion) {
       return new Set<string>();
     }
     const boundManifestAssetIds = new Set(
-      selectedVersion.resourceBindings.map((binding) => binding.resourceId),
+      currentRunnableVersion.resourceBindings.map(
+        (binding) => binding.resourceId,
+      ),
     );
     return new Set(
       resources
@@ -620,7 +648,7 @@ export default function ProjectDevelopmentView({
         )
         .map((resource) => resource.id),
     );
-  }, [resources, selectedResourceId]);
+  }, [currentRunnableVersion, resources]);
   const normalizedSearch = searchText.trim().toLowerCase();
   const visibleResources = useMemo(
     () =>
@@ -738,6 +766,14 @@ export default function ProjectDevelopmentView({
           ? textPreview.preview.mediaType
           : focusedResource?.mediaType;
 
+  useEffect(() => {
+    setSelectedRunnableVersionId(manifest.currentRunnableVersionId ?? '');
+  }, [manifest.currentRunnableVersionId, manifest.projectId]);
+
+  useEffect(() => {
+    setActiveRunnablePreviewVersionId(null);
+  }, [manifest.projectId]);
+
   useEffect(() => {
     if (embeddedPreviewUrl) {
       setFocusedResourceId(null);
@@ -955,12 +991,60 @@ export default function ProjectDevelopmentView({
     setFocusedResourceId(null);
   }
 
+  async function launchRunnableVersion(versionId: string) {
+    const invoke = resolveTauriInvoke();
+    if (!invoke) {
+      setRunStatus('需要在 Tauri App 内运行');
+      return false;
+    }
+    setRunSwitching(true);
+    setRunStatus('正在启动可运行版本');
+    setSelectedRunnableVersionId(versionId);
+    setActiveRunnablePreviewVersionId(null);
+    onPreviewChange?.(null);
+    try {
+      const result = await invoke<RunnableGameVersionLaunchResult>(
+        'launch_local_game_runnable_version',
+        {
+          projectPath,
+          expectedProjectId: manifest.projectId,
+          versionId,
+        },
+      );
+      onManifestChange?.(result.manifest);
+      onPreviewChange?.({
+        status: 'running',
+        url: result.preview.url,
+        port: result.preview.port,
+      });
+      setSelectedRunnableVersionId(result.version.versionId);
+      setActiveRunnablePreviewVersionId(result.version.versionId);
+      setRunStatus(`正在运行版本 ${result.version.versionId}`);
+      return true;
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      setSelectedRunnableVersionId(manifest.currentRunnableVersionId ?? '');
+      setActiveRunnablePreviewVersionId(null);
+      setRunStatus(message);
+      onPreviewChange?.({ status: 'failed' });
+      return false;
+    } finally {
+      setRunSwitching(false);
+    }
+  }
+
   function showRunView() {
-    if (!runAvailable) {
+    if (!currentRunnableVersion) {
+      setRunStatus(
+        runnableVersions.length > 0
+          ? '当前可运行版本选择无效'
+          : '当前无可运行版本',
+      );
       return;
     }
     setFocusedResourceId(null);
     setMode('run');
+    void launchRunnableVersion(currentRunnableVersion.versionId);
   }
 
   return (
@@ -1034,6 +1118,26 @@ export default function ProjectDevelopmentView({
                     按类型
                   </button>
                 </>
+              ) : mode === 'run' && currentRunnableVersion ? (
+                <label className="game-run-version-picker">
+                  运行版本
+                  <select
+                    aria-label="当前运行版本"
+                    value={currentRunnableVersion.versionId}
+                    disabled={runSwitching}
+                    onChange={(event) => {
+                      const versionId = event.currentTarget.value;
+                      setSelectedRunnableVersionId(versionId);
+                      void launchRunnableVersion(versionId);
+                    }}
+                  >
+                    {runnableVersions.map((version, index) => (
+                      <option key={version.versionId} value={version.versionId}>
+                        {`版本 ${index + 1} · revision ${version.projectRevision}`}
+                      </option>
+                    ))}
+                  </select>
+                </label>
               ) : null}
             </div>
           </div>
@@ -1044,7 +1148,7 @@ export default function ProjectDevelopmentView({
               className="game-run-unavailable"
               role="status"
             >
-              首个可运行原型尚未完成，运行视图暂不可用
+              {runStatus || '当前无可运行版本'}
             </p>
           ) : null}
 
@@ -1389,6 +1493,10 @@ export default function ProjectDevelopmentView({
                                   key={resource.id}
                                   resource={resource}
                                   selected={resource.id === selectedResourceId}
+                                  currentVersion={
+                                    resource.version?.versionId ===
+                                    currentRunnableVersion?.versionId
+                                  }
                                   relationState={relationState}
                                   x={position.x}
                                   y={position.y}
@@ -1417,92 +1525,44 @@ export default function ProjectDevelopmentView({
                 ) : (
                   <div className="game-run-preview-empty">
                     <Sparkles size={28} aria-hidden="true" />
-                    <strong>客户端运行画面尚未载入</strong>
-                    <span>发送 /run 或 /preview 后将在这里直接运行游戏</span>
+                    <strong>
+                      {runSwitching ? '正在切换可运行版本' : '运行画面未启动'}
+                    </strong>
+                    <span>{runStatus || '请重新启动当前可运行版本'}</span>
                   </div>
                 )}
               </div>
-              <div
-                className="game-run-slice-controls"
-                aria-label="测试切片控件"
-              >
-                <button
-                  type="button"
-                  aria-label="上一个测试切片"
-                  onClick={() =>
-                    setActiveSlice((current) => Math.max(0, current - 1))
-                  }
-                >
-                  <ChevronLeft size={16} aria-hidden="true" />
-                  上一项
-                </button>
-                <button
-                  type="button"
-                  aria-label={runPlaying ? '暂停测试' : '播放测试'}
-                  onClick={() => setRunPlaying((playing) => !playing)}
-                >
-                  {runPlaying ? (
-                    <Pause size={18} aria-hidden="true" />
-                  ) : (
-                    <Play size={18} aria-hidden="true" />
-                  )}
-                </button>
-                <span>{`测试切片 ${activeSlice + 1}`}</span>
-                <button
-                  type="button"
-                  aria-label="下一个测试切片"
-                  onClick={() => setActiveSlice((current) => current + 1)}
-                >
-                  下一项
-                  <ChevronRight size={16} aria-hidden="true" />
-                </button>
-              </div>
               <div className="game-run-panels">
-                <section aria-label="资源信息面板">
+                <section aria-label="可运行版本信息">
                   <header>
                     <Info size={16} aria-hidden="true" />
-                    信息展示
+                    当前版本
                   </header>
-                  {selectedResource ? (
+                  {currentRunnableVersion ? (
                     <dl>
                       <div>
-                        <dt>名称</dt>
-                        <dd>{selectedResource.label}</dd>
+                        <dt>版本</dt>
+                        <dd>{currentRunnableVersion.versionId}</dd>
                       </div>
                       <div>
-                        <dt>路径</dt>
-                        <dd>{selectedResource.path}</dd>
+                        <dt>修订</dt>
+                        <dd>{currentRunnableVersion.projectRevision}</dd>
                       </div>
                       <div>
-                        <dt>类型</dt>
-                        <dd>{selectedResource.mediaType}</dd>
+                        <dt>验证</dt>
+                        <dd>静态检查与交互试玩均通过</dd>
                       </div>
                     </dl>
                   ) : (
-                    <p>暂停后选择资源可查看已登记信息</p>
+                    <p>当前无可运行版本</p>
                   )}
                 </section>
-                <section aria-label="数值微调面板">
-                  <header>
-                    <SlidersHorizontal size={16} aria-hidden="true" />
-                    数值微调
-                  </header>
-                  <label>
-                    角色移动速度
-                    <input type="number" disabled placeholder="未载入" />
-                  </label>
-                  <label>
-                    跳跃高度
-                    <input type="number" disabled placeholder="未载入" />
-                  </label>
-                  <input
-                    type="text"
-                    disabled
-                    aria-label="新增微调数值项"
-                    placeholder="用自然语言新增微调项（尚未接入）"
-                  />
-                </section>
               </div>
+              {runStatus ? (
+                <p className="game-run-status" role="status">
+                  {runStatus}
+                </p>
+              ) : null}
             </section>
           )}
         </section>
diff --git a/apps/ai-game-creator-shell/src/view/project-development/resourceProjectionModel.ts b/apps/ai-game-creator-shell/src/view/project-development/resourceProjectionModel.ts
index 6cc98c8e5..c021ccfe6 100644
--- a/apps/ai-game-creator-shell/src/view/project-development/resourceProjectionModel.ts
+++ b/apps/ai-game-creator-shell/src/view/project-development/resourceProjectionModel.ts
@@ -1,7 +1,7 @@
 import type {
   GameCreationAppManifest,
-  GameIterationVersion,
   ProjectResourceCanvasSection,
+  RunnableGameVersion,
 } from '../../../../../packages/shared/src/contracts/gameCreationApp';
 
 export type ProjectResourceCategory = ProjectResourceCanvasSection;
@@ -23,7 +23,7 @@ export type ProjectAgentResultSummary = {
   updatedAt: number;
 };
 
-export type ProjectVersionResourceSummary = GameIterationVersion & {
+export type ProjectVersionResourceSummary = RunnableGameVersion & {
   label: string;
   childVersionIds: string[];
 };
@@ -231,7 +231,7 @@ export function projectResourcesFromReadModels(
   }
 
   const childVersionIdsByParent = new Map<string, string[]>();
-  for (const version of manifest.versions ?? []) {
+  for (const version of manifest.runnableVersions ?? []) {
     if (!version.parentVersionId) {
       continue;
     }
@@ -239,7 +239,9 @@ export function projectResourcesFromReadModels(
     children.push(version.versionId);
     childVersionIdsByParent.set(version.parentVersionId, children);
   }
-  for (const [index, manifestVersion] of (manifest.versions ?? []).entries()) {
+  for (const [index, manifestVersion] of (
+    manifest.runnableVersions ?? []
+  ).entries()) {
     const version: ProjectVersionResourceSummary = {
       ...manifestVersion,
       label: `版本 ${index + 1}`,
@@ -251,8 +253,8 @@ export function projectResourcesFromReadModels(
       category: 'version',
       subtype: 'project-version',
       label: version.label,
-      path: `项目版本 · ${version.versionId}`,
-      mediaType: '正式项目版本',
+      path: `可运行版本 · ${version.versionId}`,
+      mediaType: '正式可运行版本',
       sourceLabel: version.parentVersionId
         ? `项目修订 ${version.projectRevision} · 父版本 ${version.parentVersionId}`
         : `项目修订 ${version.projectRevision} · 初始版本`,
diff --git a/apps/ai-game-creator-shell/tests/appSurface/project-development.suite.ts b/apps/ai-game-creator-shell/tests/appSurface/project-development.suite.ts
index 8dbd13a61..090b14a70 100644
--- a/apps/ai-game-creator-shell/tests/appSurface/project-development.suite.ts
+++ b/apps/ai-game-creator-shell/tests/appSurface/project-development.suite.ts
@@ -1,6 +1,7 @@
 import type {
   ProjectResourceCanvasLayout,
   ProjectResourceCanvasPosition,
+  RunnableGameVersion,
 } from '../../../../packages/shared/src/contracts/gameCreationApp';
 import {
   consumeInitialGameChatMessage,
@@ -56,6 +57,36 @@ import {
   within,
 } from './harness';
 
+function runnableVersionFixture(
+  projectId: string,
+  versionId: string,
+  projectRevision: number,
+  overrides: Partial<RunnableGameVersion> = {},
+): RunnableGameVersion {
+  return {
+    schemaVersion: 'game-creator-runnable-version.v1',
+    versionId,
+    projectId,
+    parentVersionId: null,
+    projectRevision,
+    artifactPath: `.agent/runnable-versions/${versionId}/artifact`,
+    artifactSha256: 'a'.repeat(64),
+    entryPath: 'game/index.html',
+    resourceBindings: [],
+    createdReason: 'initial',
+    validation: {
+      staticSmokePassed: true,
+      previewValidatePassed: true,
+      playtestPassed: true,
+      agentId: 'program-agent',
+      runId: `run-${projectRevision}`,
+      reportPath: `.agent/runtime/browser-validations/program-agent/run-${projectRevision}/1/validation.json`,
+    },
+    createdAt: projectRevision * 100,
+    ...overrides,
+  };
+}
+
 function resourceGraphForInputs(args?: Record<string, unknown>) {
   const resources =
     (args?.resources as
@@ -647,7 +678,7 @@ export function registerProjectWorkbenchFoundationTests() {
     fireEvent.click(runTab);
     expect(runTab.getAttribute('aria-selected')).toBe('false');
     expect(
-      screen.getByText('首个可运行原型尚未完成，运行视图暂不可用'),
+      screen.getByText('当前无可运行版本'),
     ).not.toBeNull();
     expect(screen.getByLabelText('附件导入失败')).not.toBeNull();
     expect(screen.getByText('broken-reference.png')).not.toBeNull();
@@ -693,27 +724,20 @@ export function registerProjectWorkbenchFoundationTests() {
         source: { kind: 'generated' },
       },
     ];
-    manifest.versions = [
-      {
-        versionId: 'version-root',
-        parentVersionId: null,
-        projectRevision: 3,
+    manifest.runnableVersions = [
+      runnableVersionFixture('workbench-versions', 'version-root', 3, {
         resourceBindings: [{ slotId: 'player', resourceId: 'asset-player' }],
-        createdReason: 'initial',
-        createdAt: 100,
-      },
-      {
-        versionId: 'version-child',
+      }),
+      runnableVersionFixture('workbench-versions', 'version-child', 4, {
         parentVersionId: 'version-root',
-        projectRevision: 4,
         resourceBindings: [
           { slotId: 'player', resourceId: 'asset-player' },
           { slotId: 'historical', resourceId: 'asset-removed' },
         ],
         createdReason: 'agent-revision',
-        createdAt: 200,
-      },
+      }),
     ];
+    manifest.currentRunnableVersionId = 'version-child';
 
     render(
       React.createElement(ProjectDevelopmentView, {
@@ -1838,6 +1862,13 @@ export function registerProjectWorkbenchFoundationTests() {
       throw new Error('missing code-prototype seed task');
     }
     codePrototype.status = 'completed';
+    const runnableVersion = runnableVersionFixture(
+      'workbench-runnable',
+      'runnable-r7',
+      7,
+    );
+    manifest.runnableVersions = [runnableVersion];
+    manifest.currentRunnableVersionId = runnableVersion.versionId;
     manifest.preview = {
       status: 'running',
       url: 'http://127.0.0.1:4173',
@@ -1868,6 +1899,22 @@ export function registerProjectWorkbenchFoundationTests() {
               'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+A8AAQUBAScY42YAAAAASUVORK5CYII=',
           };
         }
+        if (command === 'launch_local_game_runnable_version') {
+          expect(args).toEqual({
+            projectPath: '/tmp/workbench-runnable',
+            expectedProjectId: 'workbench-runnable',
+            versionId: 'runnable-r7',
+          });
+          return {
+            manifest,
+            version: runnableVersion,
+            preview: {
+              url: 'http://127.0.0.1:4173',
+              port: 4173,
+              root: '/tmp/workbench-runnable',
+            },
+          };
+        }
         throw new Error(`unexpected invoke ${command}`);
       },
     );
@@ -1893,16 +1940,26 @@ export function registerProjectWorkbenchFoundationTests() {
     expect(runTab.disabled).toBe(false);
     fireEvent.click(runTab);
     expect(screen.getByLabelText('运行表现层')).not.toBeNull();
-    const previewFrame = screen.getByTitle(
+    const previewFrame = (await screen.findByTitle(
       '可运行工作台 游戏运行画面',
-    ) as HTMLIFrameElement;
+    )) as HTMLIFrameElement;
     expect(previewFrame.getAttribute('src')).toBe('http://127.0.0.1:4173/');
     expect(previewFrame.getAttribute('sandbox')).toBe(
       'allow-scripts allow-same-origin allow-forms allow-pointer-lock',
     );
-    expect(screen.getByLabelText('测试切片控件')).not.toBeNull();
-    expect(screen.getByLabelText('资源信息面板')).not.toBeNull();
-    expect(screen.getByLabelText('数值微调面板')).not.toBeNull();
+    await waitFor(() => {
+      expect(invoke).toHaveBeenCalledWith(
+        'launch_local_game_runnable_version',
+        {
+          projectPath: '/tmp/workbench-runnable',
+          expectedProjectId: 'workbench-runnable',
+          versionId: 'runnable-r7',
+        },
+      );
+    });
+    expect(screen.getByLabelText('可运行版本信息')).not.toBeNull();
+    expect(screen.queryByLabelText('测试切片控件')).toBeNull();
+    expect(screen.queryByLabelText('数值微调面板')).toBeNull();
 
     fireEvent.click(screen.getByRole('tab', { name: '资源管理' }));
     fireEvent.click(screen.getByRole('button', { name: '按类型' }));
@@ -1930,6 +1987,166 @@ export function registerProjectWorkbenchFoundationTests() {
     );
   });
 
+  it('unloads the old iframe before switching to another runnable version snapshot', async () => {
+    const manifest = createGameCreationAppManifest(
+      'workbench-version-switch',
+      '版本切换测试',
+    );
+    const first = runnableVersionFixture(
+      manifest.projectId,
+      'runnable-r1',
+      1,
+    );
+    const second = runnableVersionFixture(
+      manifest.projectId,
+      'runnable-r2',
+      2,
+      {
+        parentVersionId: first.versionId,
+        createdReason: 'agent-revision',
+      },
+    );
+    manifest.runnableVersions = [first, second];
+    manifest.currentRunnableVersionId = first.versionId;
+    manifest.preview = {
+      status: 'running',
+      url: 'http://127.0.0.1:4101',
+      port: 4101,
+    };
+    let resolveSecondLaunch: ((value: unknown) => void) | null = null;
+    const secondLaunch = new Promise((resolve) => {
+      resolveSecondLaunch = resolve;
+    });
+    const invoke = vi.fn(async (command: string, args?: Record<string, unknown>) => {
+      if (command !== 'launch_local_game_runnable_version') {
+        throw new Error(`unexpected invoke ${command}`);
+      }
+      if (args?.versionId === first.versionId) {
+        return {
+          manifest,
+          version: first,
+          preview: {
+            url: 'http://127.0.0.1:4101',
+            port: 4101,
+            root: '/tmp/workbench-version-switch',
+          },
+        };
+      }
+      return secondLaunch;
+    });
+    window.__TAURI__ = { core: { invoke } };
+
+    function StatefulWorkbench() {
+      const [liveManifest, setLiveManifest] = React.useState(manifest);
+      const [preview, setPreview] = React.useState(manifest.preview ?? null);
+      return React.createElement(ProjectDevelopmentView, {
+        projectName: manifest.name,
+        projectPath: '/tmp/workbench-version-switch',
+        manifest: liveManifest,
+        attachments: [],
+        recentRunStatus: null,
+        recentRunStopReason: null,
+        preview,
+        supervisor: React.createElement('div', null, '项目总控'),
+        onHomeOpen: vi.fn(),
+        onProjectsOpen: vi.fn(),
+        onManifestChange: setLiveManifest,
+        onPreviewChange: setPreview,
+      });
+    }
+
+    render(React.createElement(StatefulWorkbench));
+    fireEvent.click(screen.getByRole('tab', { name: '运行' }));
+    await waitFor(() => {
+      expect(
+        screen
+          .getByTitle('版本切换测试 游戏运行画面')
+          .getAttribute('src'),
+      ).toBe('http://127.0.0.1:4101/');
+    });
+
+    fireEvent.change(screen.getByLabelText('当前运行版本'), {
+      target: { value: second.versionId },
+    });
+    expect(screen.queryByTitle('版本切换测试 游戏运行画面')).toBeNull();
+    expect(screen.getByText('正在切换可运行版本')).not.toBeNull();
+    expect(invoke).toHaveBeenCalledWith(
+      'launch_local_game_runnable_version',
+      {
+        projectPath: '/tmp/workbench-version-switch',
+        expectedProjectId: manifest.projectId,
+        versionId: second.versionId,
+      },
+    );
+
+    const switchedManifest = {
+      ...manifest,
+      currentRunnableVersionId: second.versionId,
+      preview: {
+        status: 'running' as const,
+        url: 'http://127.0.0.1:4102',
+        port: 4102,
+      },
+    };
+    await act(async () => {
+      resolveSecondLaunch?.({
+        manifest: switchedManifest,
+        version: second,
+        preview: {
+          url: 'http://127.0.0.1:4102',
+          port: 4102,
+          root: '/tmp/workbench-version-switch',
+        },
+      });
+      await secondLaunch;
+    });
+    await waitFor(() => {
+      expect(
+        screen
+          .getByTitle('版本切换测试 游戏运行画面')
+          .getAttribute('src'),
+      ).toBe('http://127.0.0.1:4102/');
+    });
+  });
+
+  it('shows a precise runnable version launch failure without embedding a preview', async () => {
+    const manifest = createGameCreationAppManifest(
+      'workbench-version-failure',
+      '版本错误测试',
+    );
+    const version = runnableVersionFixture(
+      manifest.projectId,
+      'runnable-r3',
+      3,
+    );
+    manifest.runnableVersions = [version];
+    manifest.currentRunnableVersionId = version.versionId;
+    const invoke = vi.fn(async () => {
+      throw new Error('可运行版本 revision 不一致');
+    });
+    window.__TAURI__ = { core: { invoke } };
+
+    render(
+      React.createElement(ProjectDevelopmentView, {
+        projectName: manifest.name,
+        projectPath: '/tmp/workbench-version-failure',
+        manifest,
+        attachments: [],
+        recentRunStatus: null,
+        recentRunStopReason: null,
+        supervisor: React.createElement('div', null, '项目总控'),
+        onHomeOpen: vi.fn(),
+        onProjectsOpen: vi.fn(),
+      }),
+    );
+
+    fireEvent.click(screen.getByRole('tab', { name: '运行' }));
+    expect(
+      (await screen.findAllByText('可运行版本 revision 不一致')).length,
+    ).toBeGreaterThan(0);
+    expect(screen.queryByTitle('版本错误测试 游戏运行画面')).toBeNull();
+  });
+
   it('marks an unvalidated UI prototype as a candidate image', () => {
     const manifest = createGameCreationAppManifest(
       'workbench-ui-candidate',
@@ -1984,7 +2201,7 @@ export function registerProjectWorkbenchFoundationTests() {
     ).not.toBeNull();
   });
 
-  it('refuses to embed a non-loopback game preview in the client workbench', () => {
+  it('does not treat completed code or an ordinary loopback preview as run authorization', () => {
     const manifest = createGameCreationAppManifest(
       'workbench-remote-preview',
       '远程预览拒绝测试',
@@ -1998,8 +2215,8 @@ export function registerProjectWorkbenchFoundationTests() {
     codePrototype.status = 'completed';
     manifest.preview = {
       status: 'running',
-      url: 'https://example.com/game',
-      port: 443,
+      url: 'http://127.0.0.1:4188',
+      port: 4188,
     };
 
     render(
@@ -2018,7 +2235,10 @@ export function registerProjectWorkbenchFoundationTests() {
 
     fireEvent.click(screen.getByRole('tab', { name: '运行' }));
     expect(screen.queryByTitle('远程预览拒绝测试 游戏运行画面')).toBeNull();
-    expect(screen.getByText('客户端运行画面尚未载入')).not.toBeNull();
+    expect(screen.getByText('当前无可运行版本')).not.toBeNull();
+    expect(
+      screen.getByRole('tab', { name: '运行' }).getAttribute('aria-selected'),
+    ).toBe('false');
   });
 }
 
diff --git a/apps/ai-game-creator-shell/tests/projectResourceProjectionModel.test.ts b/apps/ai-game-creator-shell/tests/projectResourceProjectionModel.test.ts
index 7f98d4175..06acb6276 100644
--- a/apps/ai-game-creator-shell/tests/projectResourceProjectionModel.test.ts
+++ b/apps/ai-game-creator-shell/tests/projectResourceProjectionModel.test.ts
@@ -1,8 +1,41 @@
 import { describe, expect, it } from 'vitest';
 
-import { createGameCreationAppManifest } from '../../../packages/shared/src/contracts/gameCreationApp';
+import {
+  createGameCreationAppManifest,
+  type RunnableGameVersion,
+} from '../../../packages/shared/src/contracts/gameCreationApp';
 import { projectResourcesFromReadModels } from '../src/view/project-development/resourceProjectionModel';
 
+function runnableVersionFixture(
+  projectId: string,
+  versionId: string,
+  projectRevision: number,
+  overrides: Partial<RunnableGameVersion> = {},
+): RunnableGameVersion {
+  return {
+    schemaVersion: 'game-creator-runnable-version.v1',
+    versionId,
+    projectId,
+    parentVersionId: null,
+    projectRevision,
+    artifactPath: `.agent/runnable-versions/${versionId}/artifact`,
+    artifactSha256: 'a'.repeat(64),
+    entryPath: 'game/index.html',
+    resourceBindings: [],
+    createdReason: 'initial',
+    validation: {
+      staticSmokePassed: true,
+      previewValidatePassed: true,
+      playtestPassed: true,
+      agentId: 'program-agent',
+      runId: `run-${projectRevision}`,
+      reportPath: `.agent/runtime/browser-validations/program-agent/run-${projectRevision}/1/validation.json`,
+    },
+    createdAt: projectRevision * 100,
+    ...overrides,
+  };
+}
+
 describe('项目资源投影', () => {
   it('只把明确资源投影到固定分类，未知任务产物不会伪装成项目版本', () => {
     const manifest = createGameCreationAppManifest(
@@ -49,18 +82,14 @@ describe('项目资源投影', () => {
         source: { kind: 'generated' },
       },
     ];
-    manifest.versions = [
-      {
-        versionId: 'version-1',
-        parentVersionId: null,
-        projectRevision: 7,
+    manifest.runnableVersions = [
+      runnableVersionFixture('resource-projection', 'version-1', 7, {
         resourceBindings: [
           { slotId: 'background-music', resourceId: 'registered-bgm' },
         ],
-        createdReason: 'initial',
-        createdAt: 1,
-      },
+      }),
     ];
+    manifest.currentRunnableVersionId = 'version-1';
 
     const resources = projectResourcesFromReadModels(
       manifest,
@@ -137,16 +166,10 @@ describe('项目资源投影', () => {
       'stable-resource-id',
       '稳定资源身份测试',
     );
-    manifest.versions = [
-      {
-        versionId: 'stable-version',
-        parentVersionId: null,
-        projectRevision: 1,
-        resourceBindings: [],
-        createdReason: 'initial',
-        createdAt: 1,
-      },
+    manifest.runnableVersions = [
+      runnableVersionFixture('stable-resource-id', 'stable-version', 1),
     ];
+    manifest.currentRunnableVersionId = 'stable-version';
     const first = projectResourcesFromReadModels(
       manifest,
       [],
@@ -184,24 +207,14 @@ describe('项目资源投影', () => {
       'version-projection',
       '版本投影测试',
     );
-    manifest.versions = [
-      {
-        versionId: 'version-root',
-        parentVersionId: null,
-        projectRevision: 2,
-        resourceBindings: [],
-        createdReason: 'initial',
-        createdAt: 100,
-      },
-      {
-        versionId: 'version-child',
+    manifest.runnableVersions = [
+      runnableVersionFixture('version-projection', 'version-root', 2),
+      runnableVersionFixture('version-projection', 'version-child', 3, {
         parentVersionId: 'version-root',
-        projectRevision: 3,
-        resourceBindings: [],
         createdReason: 'agent-revision',
-        createdAt: 200,
-      },
+      }),
     ];
+    manifest.currentRunnableVersionId = 'version-child';
 
     const versions = projectResourcesFromReadModels(manifest, [], []).filter(
       (resource) => resource.category === 'version',
diff --git a/docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md b/docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md
index d94743946..1d3d3978f 100644
--- a/docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md
+++ b/docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md
@@ -1,6 +1,6 @@
 # AI 游戏创作项目开发工作台 PRD
 
-更新时间：`2026-08-04`（依赖视图视觉口径调整）
+更新时间：`2026-08-04`（可运行版本 P0/P1）
 
 ## 1. 产品定位
 
@@ -281,7 +281,7 @@ type UpdateProjectResourceCanvasLayoutResult =
 资源身份固定使用 manifest asset ID、正式 version ID、Agent ID + run ID 或已导入资源稳定路径；显示标题、来源文案变化不得改变 `resourceId`，从而避免布局、依赖边、选择和聚焦状态因改名失效。
 
 ```ts
-type ProjectResourceDescriptor = {
+type GameResourceDescriptor = {
   resourceId: string;
   category: 'document' | 'version' | 'art' | 'audio';
   subtype: string;
@@ -305,31 +305,48 @@ type ProjectVersionResourceReplacement = {
 
 三项兼容性必须同时为 true 才能创建下一版本。
 
-### 5.4 游戏迭代版本（P1）
+### 5.4 可运行游戏版本（P0 合同，P1 实现）
 
-阶段六实现状态（2026-08-03）：正式版本业务真相扩展在本地项目 `.agent/manifest.json` 的可选 `versions` 字段中；旧项目字段缺失时等价于空列表，不根据 checkpoint、布局 sidecar、预览记录或 `game-creator-project-revision.v1` 自动伪造版本。版本数组只允许追加，已有记录不得删除、重排或修改；首轮没有版本创建按钮，也不自动把当前编辑态登记为版本。
+`GameIterationVersion` 与 manifest `versions` 是上一阶段资源管理使用的只读迭代记录，不代表已经通过试玩，也不再作为运行入口授权。唯一可运行事实源是 `.agent/manifest.json` 中由可信 Rust / Runtime 追加的 `runnableVersions` 与可变选择指针 `currentRunnableVersionId`；前端、Agent 文本、任务完成状态、checkpoint、布局 sidecar 和普通 preview 状态均无权自行创建可运行版本。
 
 ```ts
-type GameIterationVersion = {
+type RunnableGameVersion = {
+  schemaVersion: 'game-creator-runnable-version.v1';
   versionId: string;
+  projectId: string;
   parentVersionId: string | null;
   projectRevision: number;
+  artifactPath: `.agent/runnable-versions/${string}/artifact`;
+  artifactSha256: string;
+  entryPath: 'game/index.html';
   resourceBindings: Array<{ slotId: string; resourceId: string }>;
-  createdReason: 'initial' | 'resource-replacement' | 'agent-revision';
+  createdReason: 'initial' | 'agent-revision';
+  validation: {
+    staticSmokePassed: true;
+    previewValidatePassed: true;
+    playtestPassed: true;
+    agentId: string;
+    runId: string;
+    reportPath: string;
+  };
   createdAt: number;
 };
 
 type GameCreationAppManifest = {
   // 既有字段省略
-  versions?: GameIterationVersion[];
+  runnableVersions?: RunnableGameVersion[];
+  currentRunnableVersionId?: string | null;
 };
 ```
 
-- `versions` 按追加顺序保存。第一条必须是 `initial + parentVersionId=null`；后续记录必须引用数组中更早出现的父版本，创建原因不能再是 `initial`，从而天然排除自引用、悬空父版本和父子环。
-- `projectRevision` 与 `createdAt` 必须是 JavaScript 安全非负整数；子版本的修订必须严格大于父版本，创建时间不得早于父版本。
+- 当前 revision 只有同时满足 `preview-playtest` 传递前置任务闭包的项目完整性检查、当前 revision 的 `game.static_smoke` 通过、当前 revision 的 `preview.validate` 与真实交互试玩通过，才允许由 Runtime 登记版本。试玩后的 `publish-strategy / publish-package` 等下游交付节点不阻断可运行版本登记。首个通过版本自动登记为 `initial`；后续 Agent 修订重新完整通过后登记为 `agent-revision`。
+- 每条版本在登记时把 `game/` 与 `assets/` 复制到受保护的不可变快照目录，计算确定性 SHA-256；运行旧版本只服务该快照，不读取当前编辑工作树。启动前必须复核目录、版本描述、revision 与摘要，任何漂移都按“版本损坏”失败关闭。
+- `runnableVersions` 按追加顺序保存。第一条必须是 `initial + parentVersionId=null`；后续记录必须引用数组中更早出现的父版本并使用 `agent-revision`。同一 project revision 最多一条，重复完成投影必须幂等返回原记录。
+- `projectId` 必须等于当前 manifest，`projectRevision` 必须为 JavaScript 安全正整数；子版本 revision 严格大于父版本，创建时间不得早于父版本。
 - 同一版本内 `slotId` 唯一；`resourceId` 固定保存 manifest asset ID，不保存资源卡显示名称、External Editor resource ID、路径或布局 ID。历史资源已不在当前 manifest 时仍保留原绑定，但界面不为其合成资源卡。
-- Tauri manifest 存储边界在每次写入前校验完整版本图，并与磁盘中的旧 `versions` 前缀逐项比较；只允许追加新记录，已有记录被修改、删除或重排时写入失败且原文件保持不变。
-- 版本卡标题由稳定追加序号生成，卡片与聚焦态展示 `versionId / projectRevision / createdReason / parentVersionId`；聚焦态额外展示直接子版本和全部 slot 绑定。点击版本卡只高亮当前投影中唯一匹配 `asset:<resourceId>` 的资源卡，不修改版本或资源。
+- Tauri manifest 存储边界在每次写入前校验完整版本图，并与磁盘中的旧 `runnableVersions` 前缀逐项比较；只允许追加，已有记录被修改、删除或重排时写入失败且原文件保持不变。`currentRunnableVersionId` 只能指向现存记录，允许通过专用 Tauri 命令更新。
+- 运行入口只读取当前可运行版本。切换版本时先停止当前项目旧 preview、立即卸载 iframe，再复核并启动目标快照；启动成功后回写当前选择和 loopback preview。无版本、版本损坏、版本描述 revision 不一致、权限拒绝或预览启动失败分别显示明确原因。
+- 资源管理只从 `runnableVersions` 投影“可运行版本”卡。当前选择版本的全部现存绑定资产始终高亮；点击其它版本可只读查看其父子关系和历史绑定，不改变当前运行选择。
 
 ### 5.5 测试切片与数值参数（P2）
 
@@ -355,9 +372,40 @@ type GameTunableParameterDefinition = {
   writePath: string;
   codeMutationAllowed: false;
 };
+
+type GameRunSession = {
+  sessionId: string;
+  projectId: string;
+  versionId: string;
+  projectRevision: number;
+  status: 'starting' | 'playing' | 'paused' | 'stopped' | 'failed';
+  stale: boolean;
+  staleReason: 'project-revision-changed' | 'version-changed' | null;
+  startedAt: number;
+  updatedAt: number;
+};
+
+type GameHostMessage = {
+  schemaVersion: 'game-creator-host-message.v1';
+  sessionId: string;
+  sequence: number;
+  type: 'host.start' | 'host.pause' | 'host.resume' | 'host.stop';
+  versionId: string;
+  projectRevision: number;
+};
+
+type GameRuntimeMessage = {
+  schemaVersion: 'game-creator-runtime-message.v1';
+  sessionId: string;
+  sequence: number;
+  type: 'runtime.ready' | 'runtime.state' | 'runtime.completed' | 'runtime.failed';
+  versionId: string;
+  projectRevision: number;
+  detail?: Record<string, unknown>;
+};
 ```
 
-参数写入立即增加编辑态 revision；当前 preview/slice 保持旧 revision，并显示“需要重新拉起”。
+revision 不一致统一表示编辑工作树已经晚于当前 Session 绑定版本；Session 和切片标记 `stale`，但不热更新、不改写旧版本，也不把 stale 当失败。参数写入立即增加编辑态 revision；当前 preview/slice 保持旧 revision，并显示“需要重新拉起”。P1 尚不实现切片、参数和 Runtime message bridge。
 
 ### 5.6 Agent 泥点归因（P2）
 
@@ -376,23 +424,19 @@ type ProjectAgentMudPointAttribution = {
 
 ## 6. 分阶段范围
 
-### P0：当前实施切片
+### P0：合同冻结
 
-- 复用现有四区工作台壳。
-- 资源/运行切换与客户端内 loopback 预览。
-- 固定四类资源投影、只读资源画布与中央主视窗资源聚焦；资源聚焦工具栏 / 工具侧边栏及后续媒体能力暂缓。
-- Supervisor 正式会话、上传、Runtime 确认与安全错误。
-- 当前 run 专业状态与项目历史成果分离。
-- 默认三专业组，并可展开另外三组。
-- 严格审批有效；风险/无需审批可点击查看未开放原因。
-- 橙色低保真视觉与 `1280×800` 横屏边界。
+- 冻结 `RunnableGameVersion`、`GameTestSlice`、`GameRunSession`、`GameTunableParameterDefinition`、`GameResourceDescriptor`、`GameHostMessage`、`GameRuntimeMessage`。
+- 冻结 revision 不一致与 stale 语义；切片和参数属于正式 P2，技术方案不得再称为本地 UI 草稿。
+- 明确 `versions` 不是运行授权，`runnableVersions` 才是唯一权威来源。
 
 ### P1
 
-- 已实施依赖/类型两套坐标持久化、首次默认不重叠布局、历史坐标跨重启恢复与自动协调 CAS 冲突处理；资源卡手动拖动暂缓。
-- 资源关系线在布局持久化验收通过后单独实施，不与本切片捆绑伪造完成。
-- 已实施正式版本只读模型、版本卡、父子关系与引用资源高亮；资源兼容性判断和不可变下一迭代版本创建仍待后续切片。
-- 美术/音频编辑状态接线。
+- Runtime 在首轮完整验证通过后自动登记首个不可变可运行版本。
+- Agent 后续修订在新 revision 完整验证通过后登记 `agent-revision` 子版本。
+- 工作台运行入口、当前版本选择、旧 preview 停止、iframe 卸载和目标快照启动全部消费正式可运行版本。
+- 当前版本绑定资源在 dependency / type 两种资源管理布局中高亮。
+- 无版本、损坏、revision 不一致和 preview 启动失败提供独立错误状态。
 
 ### P2
 
@@ -436,14 +480,14 @@ type ProjectAgentMudPointAttribution = {
 7. 4096 资源链式 fixture 继续验证拓扑、聚合复杂度和自动布局性能；拖动局部更新与真实 Chromium 拖动帧预算暂缓，不作为当前验收条件。最右侧自环与箭头仍需完整显示。
 8. Rust 图读取延迟时，dependency sidecar 在图进入 `ready / failed` 前没有读取或写入；首次布局直接使用 Rust 返回的最终 producer 与 dependency depth。重新打开旧布局时手动位置逐项不变，自动位置按最终拓扑协调且相同结果不增加 revision。
 
-### 7.4 P1 正式项目版本阶段六验收
+### 7.4 P1 可运行版本验收
 
-1. manifest 缺少 `versions` 时旧项目正常打开且不显示伪造版本；存在合法记录时，固定“项目版本”分区按追加顺序显示稳定版本卡。
-2. 根版本、父版本和直接子版本关系在卡片或聚焦态可见；悬空父版本、自引用、重复 ID、非递增修订、倒退时间、重复 slot 和超限数字均失败关闭。
-3. 点击版本卡后，当前 manifest 中仍存在的绑定资产卡被高亮；历史已删除资产只在版本详情保留 ID，不创建幽灵卡，也不把 External Editor resource ID 猜成 manifest asset ID。
-4. 版本聚焦态只读展示身份、修订、创建原因、父子关系、创建时间和 slot 绑定，不提供编辑、替换、切换、回滚或运行按钮。
-5. 任意现有 manifest 写入只能保留磁盘版本前缀并追加新记录；修改、删除或重排已有版本时写入失败，原 manifest 字节不被覆盖。
-6. 版本选择和高亮不写 manifest、布局 sidecar 或 project revision；dependency / type 两种布局都可显示绑定高亮，既有依赖关系 SVG 语义不变。
+1. 任务完成或 `code-prototype=completed` 不能直接放行运行；只有同 revision 完整性、static smoke、preview.validate 和 playtest 全部通过后，Rust 才自动登记版本。
+2. 首版登记为 `initial`，后续新 revision 登记为 `agent-revision`；同一 revision 重放幂等，记录只允许追加且旧记录不可修改、删除或重排。
+3. 每个版本持有独立 `game/assets` 快照与摘要。当前工作树后续变化不改变旧版本；摘要、描述或 revision 被篡改时启动失败且不回退当前工作树。
+4. manifest 没有 `runnableVersions` 时点击运行显示“当前无可运行版本”；合法版本存在时运行入口启动 `currentRunnableVersionId`，不读取 `code-prototype` 状态决定可用性。
+5. 切换版本先停止旧 preview 并卸载 iframe，再启动目标 loopback 快照；失败时不继续显示旧 iframe，并给出损坏、revision 不一致或启动失败的明确原因。
+6. 当前版本卡与仍存在的绑定资产在 dependency / type 两种布局中高亮；历史已删除绑定只留在版本详情，不创建幽灵卡。
 
 ### 7.5 阶段七完整验收
 
@@ -455,7 +499,7 @@ type ProjectAgentMudPointAttribution = {
 
 ## 8. 非目标
 
-- 当前收口不实现资源卡手动拖动，也不实现资源聚焦工具栏、资源聚焦工具侧边栏、美术编辑、音频编辑 / 替换、资源重新生成、资源替换、下一迭代版本创建入口、运行版本切换、版本回滚、运行模块扩展、测试切片、运行态消费版本、数值参数或泥点归因。正式版本记录已经成为 manifest 业务真相，但当前只读取、校验和展示已有记录。
+- 当前收口不实现资源卡手动拖动，也不实现资源聚焦工具栏、资源聚焦工具侧边栏、美术编辑、音频编辑 / 替换、资源重新生成、资源替换、手动创建版本或版本回滚。P1 实现运行版本登记、选择、切换和运行态消费；测试切片、数值参数、Host/Runtime 消息桥与泥点归因仍属于 P2。
 - 本切片不持久化资源聚焦状态、画布缩放 / 平移、搜索条件、筛选条件或当前 mode；聚焦退出时的列表上下文恢复只限当前前端会话，这些状态如需跨重启保存必须另行扩展合同，不能塞入 `game-creator-resource-layout.v1`。
 - 不修改 SpacetimeDB schema。
 - 不开放普通用户 Agent.md/Skill。
diff --git a/docs/project-memory/shared-memory/decision-log.md b/docs/project-memory/shared-memory/decision-log.md
index 8bc135b27..e33a6f9af 100644
--- a/docs/project-memory/shared-memory/decision-log.md
+++ b/docs/project-memory/shared-memory/decision-log.md
@@ -1,5 +1,14 @@
 # 决策记录
 
+## 2026-08-04 工作台 P0/P1 以不可变快照建立唯一可运行版本事实源
+
+- 背景：2026-08-03 资源管理阶段新增的 `manifest.versions` 只用于只读项目迭代卡，当时明确不承担运行版本切换；本轮飞书需求正式进入运行工作台 P0/P1，不能再以 `code-prototype=completed`、普通 preview、checkpoint 或前端状态推断游戏已经可运行。
+- 决策：保留 `manifest.versions` 作为通用迭代历史，新增由可信 Rust / Runtime 独占追加的 `runnableVersions` 与唯一可变选择指针 `currentRunnableVersionId`。每条记录必须绑定 project/revision、父版本、三项通过凭证、固定 entry、资源槽位和不可变 SHA-256；首版为 `initial`，后续为 `agent-revision`，已有记录在 manifest 存储边界禁止修改、删除或重排。
+- 产物边界：Runtime 只有在当前 revision 的 `preview-playtest` 传递前置任务闭包、`game.static_smoke`、`preview.validate` 与真实试玩证据全部通过后才自动登记；试玩后的发布节点不阻断登记。`game/` 与可选 `assets/` 被有界复制到 `.agent/runnable-versions/<versionId>/artifact`，版本描述与文件摘要在每次启动前复核。旧版本始终运行该快照，不运行当前工作树；快照已安装但 manifest 写入中断时，重试复用原描述时间与摘要，身份或内容冲突则失败关闭。
+- 工作台消费：运行入口只读取 `runnableVersions/currentRunnableVersionId`。切换时先停止旧 preview 并卸载 iframe，复核并启动目标快照，成功后才更新选择指针和 loopback preview；无版本、项目身份不符、快照损坏、revision 不一致和启动失败必须原样展示明确错误。资源管理只投影正式可运行版本，并持续高亮当前版本仍存在的绑定资产。
+- P0/P2 边界：同时冻结测试切片、运行会话、数值参数、资源描述及 Host/Runtime 消息的 TypeScript/Rust 合同；数值参数的 `codeMutationAllowed` 固定为 `false`，消息类型固定为 `host.* / runtime.*`。本轮不实现测试切片、数值微调、消息桥、泥点归因或资源替换，这些仍属于 P2。
+- 关联文档：`docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md`、`docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md`。
+
 ## 2026-08-03 资源管理阶段七以完整 CI 与可重复界面合同收口
 
 - 背景：飞书资源管理需求的阶段零至阶段六已经分别完成资源卡禁拖、固定资源投影、中央聚焦、安全文档 / 媒体预览、依赖深度与正式版本只读模型；最后需要统一复核需求边界并用当前主分支完整门禁排除集成回归。
diff --git a/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md b/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md
index 580ed42db..7cc677d05 100644
--- a/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md
+++ b/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md
@@ -361,10 +361,10 @@ game-project/
 2026-07-20 起，产品状态机、P0/P1/P2 范围与后续数据合同以 [`【AI游戏创作】项目开发工作台PRD-2026-07-20.md`](../prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md) 为准；本节只保留当前实现边界。
 
 - 页面骨架固定为左侧现有全局导航、中间主视窗、右侧陶泥儿对话和底部子 Agent 状态栏；不新建第二套客户端或平行项目页。
-- 中间主视窗提供 `资源管理 / 运行` 切换。`code-prototype` 任务完成前运行入口保持视觉不可用，但仍可点击查看“当前无可运行版本”，不能使用会阻断说明交互的原生 `disabled` 或 `aria-disabled`；完成后才允许进入运行表现层。切回资源管理只修改前端展示态，不伪造后端预览暂停结果。
+- 中间主视窗提供 `资源管理 / 运行` 切换。2026-08-04 起运行入口不再读取 `code-prototype` 任务状态，只读取 manifest 的正式 `runnableVersions + currentRunnableVersionId`；无版本时保持视觉不可用但仍可点击查看“当前无可运行版本”，不能使用会阻断说明交互的原生 `disabled` 或 `aria-disabled`。切回资源管理只修改前端展示态，不伪造后端预览暂停结果。
 - 资源管理从当前 `GameCreationAppManifest`（包含可选 `versions`）、合法 Agent 文本回执和已导入附件派生资源，固定按文档、项目版本、美术资源、音乐音效资源分区；未知任务产物不再兜底为版本，任务声明中的未登记音频也不冒充正式音频。`按依赖 / 按类型` 使用各自前端排列，dependency 模式额外绘制当前 manifest 与资源投影可证明的依赖关系。排列与图层都不写回 manifest，不能推断或伪造缺失依赖。
 - 资源卡支持点击聚焦、搜索和类型筛选。2026-07-28 起完成两套二维坐标与本地 CAS sidecar；2026-07-31 起 dependency 模式增加不持久化的原生 SVG 关系图层。2026-08-03 mentor 决定暂缓资源卡拖动，当前卡片不挂载 Pointer Down / Move / Up / Cancel 拖动入口，只允许自动布局和点击聚焦。聚焦态替换中央主视窗内容，保留左侧导航、右侧对话和底部 Agent 状态栏，退出后恢复搜索、布局模式、滚动位置与选中资源；不提供工具栏、工具侧边栏或可拖动标题栏。阶段四已补齐安全本地文档、扩展美术媒体与音频聚焦，正文独立滚动，视频 / 音频使用内置媒体控件，失败显示空态；美术编辑、音频编辑 / 替换、版本替换或运行模块仍不在本阶段。
-- 运行表现层首版直接嵌入当前项目的 loopback 游戏画面，并展示上一项 / 暂停继续 / 下一项切片控制、素材信息和数值微调面板。`preview.start` 启动本地 server 后把真实 URL 回写工作台，`preview.open` 只激活客户端内运行视图，不再调用系统浏览器；切片、参数调整和自然语言新增调节项首版仍只保留本地 UI 草稿，不修改代码或 manifest。
+- 运行表现层嵌入当前项目的 loopback 游戏画面。P1 由专用可运行版本命令停止旧 preview、卸载 iframe、复核版本快照并启动目标版本；普通 `preview.start` 继续服务 Agent 当前工作树验证，不能作为工作台运行授权或旧版本切换入口。测试切片、参数调整和 Host/Runtime message bridge 已冻结为正式 P2 合同，不再称为本地 UI 草稿，本轮不接线。
 - 右侧继续复用现有 Project Supervisor 会话、Runtime 澄清和确认链路；输入区展示 `严格审批 / 风险审批 / 无需审批` 独立面板。P0 只有严格审批可选；风险审批和无需审批保持视觉不可用但允许点击查看原因，不替代 Runtime 的逐动作权限、确认、sandbox 或 reconciliation 门禁。风险 Rank 算法记录在 `docs/project-memory/todos/【待解决】AI游戏创作高风险审批Rank-2026-07-20.md`，前端不得自行计算。
 - 底部状态栏默认展示策划、美术、程序 3 组，并允许在同一栏展开数值、音频、发布组；状态来自 manifest 与当前 Supervisor run 的 Runtime，悬停显示当前任务与进度。累计泥点必须等待后端计费归因投影；Agent.md 编辑和自定义 Skill 在来源审核、版本、权限、sandbox 与回滚合同完备前不向普通用户开放。
 - 当前 run 专业状态与项目历史成果分离：状态继续严格匹配当前 `parentRunId`；已有文本成果从专业 Agent 持久对话中合法的 `agent-finalization-<32 lower hex>` assistant 恢复，并以“历史成果”来源投影到资源管理文档区。新 run 失败、待确认、候选为空或持久对话瞬时读取失败不得清除已恢复的旧成功回执，普通失败 assistant 也不得被当作成果。
@@ -414,7 +414,15 @@ game-project/
 
 2026-08-03 阶段六：正式迭代版本直接扩展本地 `.agent/manifest.json`，不新增 checkpoint / layout sidecar / SpacetimeDB 平行业务真相。共享 Rust / TypeScript 合同新增可选 `versions: GameIterationVersion[]`；旧项目缺失字段时只读为空，不回填。Rust 在 manifest 读写边界校验版本唯一性、父先于子、根/原因一致、父子修订与时间单调、slot 唯一和 JavaScript 安全整数，并在覆盖已有 manifest 前要求磁盘版本数组是新数组的逐项相等前缀，从存储边界保证历史记录不可修改、删除或重排。
 
-工作台资源投影只从 `manifest.versions` 构建版本卡，按数组追加顺序生成稳定“版本 N”标题；不再接收前端独立 `projectVersions` 注入。`resourceBindings.resourceId` 只解释为 manifest asset ID，并映射到现有 `asset:<id>` 卡片。选中版本后在 dependency / type 两种布局中高亮当前仍存在的绑定资产；缺失历史资产只留在版本聚焦详情，不能合成幽灵卡或猜测 External Editor resource ID。版本聚焦复用中央只读容器，展示身份、修订、原因、父版本、直接子版本、创建时间与 slot 绑定。本阶段不提供版本创建、替换、切换、回滚、测试切片或运行态消费入口。
+2026-08-04 起工作台资源投影只从 `manifest.runnableVersions` 构建可运行版本卡，按数组追加顺序生成稳定“版本 N”标题；旧 `manifest.versions` 继续保留上一阶段通用迭代历史，但不提供运行授权。`resourceBindings.resourceId` 只解释为 manifest asset ID，并映射到现有 `asset:<id>` 卡片。当前运行版本在 dependency / type 两种布局中持续高亮仍存在的绑定资产；缺失历史资产只留在版本聚焦详情，不能合成幽灵卡或猜测 External Editor resource ID。版本聚焦复用中央只读容器，展示身份、修订、原因、父版本、直接子版本、创建时间与 slot 绑定。
+
+### 可运行版本 P0/P1
+
+- P0 权威合同位于工作台 PRD §5.3-§5.5 与前后端 `shared-contracts`：`RunnableGameVersion`、`GameTestSlice`、`GameRunSession`、`GameTunableParameterDefinition`、`GameResourceDescriptor`、`GameHostMessage`、`GameRuntimeMessage`。revision 不一致只产生 `stale`，不热更新旧 Session，也不原地修改旧版本。
+- P1 登记点位于自主 Runtime `preview-playtest` 成功终态投影。该点必须已经通过当前 source 中 `preview-playtest` 的传递前置任务闭包、当前 revision `game.static_smoke`、当前 revision `preview.validate`、真实 playtest 回执和证据文件复核；试玩后的发布下游节点不参与登记门禁，其它任务状态、Agent 文本或前端事件均不能登记。
+- 登记时在项目写锁内复制普通文件 `game/` 与 `assets/` 到 `.agent/runnable-versions/<versionId>/artifact/`，拒绝链接、越界、超限和入口缺失，生成包含 projectId / versionId / revision 的受保护描述与确定性 SHA-256，再向 `.agent/manifest.json` 追加版本。首条为 `initial`，后续为 `agent-revision`；同 revision 重放幂等。版本记录和快照都不可原地修改。
+- `currentRunnableVersionId` 是唯一可变选择指针。专用 Tauri 命令在项目锁内复核项目身份、版本结构、快照描述、revision 与摘要；切换时先停止当前项目 registry server，再启动目标快照。启动失败不得回退当前工作树或继续展示旧 iframe。
+- 普通 Agent `preview.start / preview.validate` 仍对当前编辑工作树执行，Runner registry 与 Tauri 用户可见 registry 的既有隔离不变；工作台运行专用命令只能服务已登记快照。
 
 历史命令式 drag preview 句柄与局部连接索引可以保留，但项目工作台不再向资源卡传入该入口。拖动热路径、4096 张真实卡片拖动重渲染和 Chromium p95 门槛统一暂缓；当前回归只要求 Pointer Move 不改变卡片坐标、SVG path 或布局 revision。`ResizeObserver` 仍保持单图层单实例，任何实时 DOM 几何都不得通过 Tauri IPC 往返 Rust。
 
@@ -431,7 +439,7 @@ game-project/
 - 用户能创建本地 Web 游戏项目。
 - 用户进入项目开发页后能看到资源管理主视窗、陶泥儿对话栏和底部策划 / 美术 / 程序 Agent 状态栏；`1280×800` 最小横屏窗口和更大桌面窗口均不得出现页面级横向 / 纵向溢出，对话输入与底部 Agent 状态栏始终位于视口内。
 - 资源管理可在按依赖 / 按类型之间切换、搜索资源并点击打开当前资源详情；dependency 模式展示可验证的资源引用和聚合任务流，搜索过滤端点、选择高亮直接上下游。资源卡不可拖动，Pointer Move 不更新坐标、线段或手动布局；所有展示数据来自当前 manifest、当前资源投影或当前项目导入附件。
-- 首个 `code-prototype` 任务未完成时运行入口不可进入并给出可感知提示；完成后可进入运行表现层，真实预览直接加载到客户端内受限运行容器。
+- manifest 没有合法 `runnableVersions + currentRunnableVersionId` 时运行入口不可进入并提示“当前无可运行版本”；只有 Runtime 为通过完整性、静态检查、preview.validate 与真实试玩的当前 revision 登记正式版本后，运行入口才从该版本的不可变快照加载受限 loopback 画面，`code-prototype` 任务状态本身不授权运行。
 - 审批档位通过独立弹出面板切换，默认严格审批；界面选择不得绕过 Runtime 现有确认门禁。
 - 聊天输入 `/plan` 可在普通聊天消息里查看下一轮分工计划，不读取任务文件、不启动 run、不修改项目，也不新增普通用户计划面板。
 - 聊天输入 `/guide` 可在普通聊天消息里查看普通用户操作导引，不读取文件、不启动 run、不启动预览、不写项目，也不新增普通用户导引面板。
diff --git a/packages/shared/src/contracts/gameCreationApp.ts b/packages/shared/src/contracts/gameCreationApp.ts
index 40b891a51..8847be972 100644
--- a/packages/shared/src/contracts/gameCreationApp.ts
+++ b/packages/shared/src/contracts/gameCreationApp.ts
@@ -556,6 +556,106 @@ export interface GameIterationVersion {
   createdAt: number;
 }
 
+export const RUNNABLE_GAME_VERSION_SCHEMA_VERSION =
+  'game-creator-runnable-version.v1' as const;
+
+export type RunnableGameVersionCreatedReason = 'initial' | 'agent-revision';
+
+export interface RunnableGameVersionValidation {
+  staticSmokePassed: true;
+  previewValidatePassed: true;
+  playtestPassed: true;
+  agentId: string;
+  runId: string;
+  reportPath: string;
+}
+
+export interface RunnableGameVersion {
+  schemaVersion: typeof RUNNABLE_GAME_VERSION_SCHEMA_VERSION;
+  versionId: string;
+  projectId: string;
+  parentVersionId: string | null;
+  projectRevision: number;
+  artifactPath: string;
+  artifactSha256: string;
+  entryPath: 'game/index.html';
+  resourceBindings: GameIterationVersionResourceBinding[];
+  createdReason: RunnableGameVersionCreatedReason;
+  validation: RunnableGameVersionValidation;
+  createdAt: number;
+}
+
+export type GameTestSliceStatus =
+  | 'idle'
+  | 'starting'
+  | 'playing'
+  | 'paused'
+  | 'completed'
+  | 'failed';
+
+export interface GameTestSlice {
+  sliceId: string;
+  versionId: string;
+  title: string;
+  order: number;
+  startCondition: string;
+  endCondition: string;
+  status: GameTestSliceStatus;
+}
+
+export interface GameRunSession {
+  sessionId: string;
+  projectId: string;
+  versionId: string;
+  projectRevision: number;
+  status: 'starting' | 'playing' | 'paused' | 'stopped' | 'failed';
+  stale: boolean;
+  staleReason: 'project-revision-changed' | 'version-changed' | null;
+  startedAt: number;
+  updatedAt: number;
+}
+
+export interface GameTunableParameterDefinition {
+  parameterId: string;
+  label: string;
+  valueType: 'integer' | 'number' | 'boolean' | 'enum';
+  min?: number;
+  max?: number;
+  step?: number;
+  enumValues?: string[];
+  writePath: string;
+  codeMutationAllowed: false;
+}
+
+export interface GameResourceDescriptor {
+  resourceId: string;
+  category: 'document' | 'version' | 'art' | 'audio';
+  subtype: string;
+  width?: number;
+  height?: number;
+  durationMs?: number;
+  format: string;
+}
+
+export interface GameHostMessage {
+  schemaVersion: 'game-creator-host-message.v1';
+  sessionId: string;
+  sequence: number;
+  type: 'host.start' | 'host.pause' | 'host.resume' | 'host.stop';
+  versionId: string;
+  projectRevision: number;
+}
+
+export interface GameRuntimeMessage {
+  schemaVersion: 'game-creator-runtime-message.v1';
+  sessionId: string;
+  sequence: number;
+  type: 'runtime.ready' | 'runtime.state' | 'runtime.completed' | 'runtime.failed';
+  versionId: string;
+  projectRevision: number;
+  detail?: Record<string, unknown>;
+}
+
 export interface GameCreationAppManifest {
   schemaVersion: string;
   projectId: string;
@@ -566,6 +666,8 @@ export interface GameCreationAppManifest {
   preview?: GameCreationAppPreviewState | null;
   commandRuns?: GameCreationAppCommandRunState[];
   versions?: GameIterationVersion[];
+  runnableVersions?: RunnableGameVersion[];
+  currentRunnableVersionId?: string | null;
 }
 
 export interface GameCreationAgentToolCallTrace {
diff --git a/server-rs/crates/shared-contracts/src/game_creation_app.rs b/server-rs/crates/shared-contracts/src/game_creation_app.rs
index 5da4426df..f1b75e388 100644
--- a/server-rs/crates/shared-contracts/src/game_creation_app.rs
+++ b/server-rs/crates/shared-contracts/src/game_creation_app.rs
@@ -641,6 +641,225 @@ pub struct GameIterationVersion {
     pub created_at: u64,
 }
 
+pub const RUNNABLE_GAME_VERSION_SCHEMA_VERSION: &str = "game-creator-runnable-version.v1";
+
+#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
+#[serde(rename_all = "kebab-case")]
+pub enum RunnableGameVersionCreatedReason {
+    Initial,
+    AgentRevision,
+}
+
+#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct RunnableGameVersionValidation {
+    pub static_smoke_passed: bool,
+    pub preview_validate_passed: bool,
+    pub playtest_passed: bool,
+    pub agent_id: String,
+    pub run_id: String,
+    pub report_path: String,
+}
+
+#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct RunnableGameVersion {
+    pub schema_version: String,
+    pub version_id: String,
+    pub project_id: String,
+    pub parent_version_id: Option<String>,
+    pub project_revision: u64,
+    pub artifact_path: String,
+    pub artifact_sha256: String,
+    pub entry_path: String,
+    pub resource_bindings: Vec<GameIterationVersionResourceBinding>,
+    pub created_reason: RunnableGameVersionCreatedReason,
+    pub validation: RunnableGameVersionValidation,
+    pub created_at: u64,
+}
+
+#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
+#[serde(rename_all = "kebab-case")]
+pub enum GameTestSliceStatus {
+    Idle,
+    Starting,
+    Playing,
+    Paused,
+    Completed,
+    Failed,
+}
+
+#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct GameTestSlice {
+    pub slice_id: String,
+    pub version_id: String,
+    pub title: String,
+    pub order: u32,
+    pub start_condition: String,
+    pub end_condition: String,
+    pub status: GameTestSliceStatus,
+}
+
+#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
+#[serde(rename_all = "kebab-case")]
+pub enum GameRunSessionStatus {
+    Starting,
+    Playing,
+    Paused,
+    Stopped,
+    Failed,
+}
+
+#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
+#[serde(rename_all = "kebab-case")]
+pub enum GameRunSessionStaleReason {
+    ProjectRevisionChanged,
+    VersionChanged,
+}
+
+#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct GameRunSession {
+    pub session_id: String,
+    pub project_id: String,
+    pub version_id: String,
+    pub project_revision: u64,
+    pub status: GameRunSessionStatus,
+    pub stale: bool,
+    pub stale_reason: Option<GameRunSessionStaleReason>,
+    pub started_at: u64,
+    pub updated_at: u64,
+}
+
+#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
+#[serde(rename_all = "kebab-case")]
+pub enum GameTunableParameterValueType {
+    Integer,
+    Number,
+    Boolean,
+    Enum,
+}
+
+#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
+pub struct GameCodeMutationAllowed;
+
+impl Serialize for GameCodeMutationAllowed {
+    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
+    where
+        S: serde::Serializer,
+    {
+        serializer.serialize_bool(false)
+    }
+}
+
+impl<'de> Deserialize<'de> for GameCodeMutationAllowed {
+    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
+    where
+        D: serde::Deserializer<'de>,
+    {
+        if bool::deserialize(deserializer)? {
+            Err(serde::de::Error::custom(
+                "codeMutationAllowed 必须固定为 false",
+            ))
+        } else {
+            Ok(Self)
+        }
+    }
+}
+
+#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct GameTunableParameterDefinition {
+    pub parameter_id: String,
+    pub label: String,
+    pub value_type: GameTunableParameterValueType,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub min: Option<f64>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub max: Option<f64>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub step: Option<f64>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub enum_values: Option<Vec<String>>,
+    pub write_path: String,
+    pub code_mutation_allowed: GameCodeMutationAllowed,
+}
+
+#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
+#[serde(rename_all = "kebab-case")]
+pub enum GameResourceCategory {
+    Document,
+    Version,
+    Art,
+    Audio,
+}
+
+#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct GameResourceDescriptor {
+    pub resource_id: String,
+    pub category: GameResourceCategory,
+    pub subtype: String,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub width: Option<u32>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub height: Option<u32>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub duration_ms: Option<u64>,
+    pub format: String,
+}
+
+#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
+pub enum GameHostMessageType {
+    #[serde(rename = "host.start")]
+    HostStart,
+    #[serde(rename = "host.pause")]
+    HostPause,
+    #[serde(rename = "host.resume")]
+    HostResume,
+    #[serde(rename = "host.stop")]
+    HostStop,
+}
+
+#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct GameHostMessage {
+    pub schema_version: String,
+    pub session_id: String,
+    pub sequence: u64,
+    #[serde(rename = "type")]
+    pub message_type: GameHostMessageType,
+    pub version_id: String,
+    pub project_revision: u64,
+}
+
+#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
+pub enum GameRuntimeMessageType {
+    #[serde(rename = "runtime.ready")]
+    RuntimeReady,
+    #[serde(rename = "runtime.state")]
+    RuntimeState,
+    #[serde(rename = "runtime.completed")]
+    RuntimeCompleted,
+    #[serde(rename = "runtime.failed")]
+    RuntimeFailed,
+}
+
+#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct GameRuntimeMessage {
+    pub schema_version: String,
+    pub session_id: String,
+    pub sequence: u64,
+    #[serde(rename = "type")]
+    pub message_type: GameRuntimeMessageType,
+    pub version_id: String,
+    pub project_revision: u64,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub detail: Option<serde_json::Value>,
+}
+
 fn validate_iteration_version_id(value: &str, label: &str, max_chars: usize) -> Result<(), String> {
     if value.is_empty() || value.trim() != value {
         return Err(format!("{label}不能为空或包含首尾空白"));
@@ -747,6 +966,138 @@ pub fn validate_game_iteration_versions(versions: &[GameIterationVersion]) -> Re
     Ok(())
 }
 
+pub fn validate_runnable_game_versions(
+    project_id: &str,
+    versions: &[RunnableGameVersion],
+    current_version_id: Option<&str>,
+) -> Result<(), String> {
+    if versions.len() > GAME_ITERATION_VERSION_MAX_COUNT {
+        return Err(format!(
+            "可运行版本最多支持 {GAME_ITERATION_VERSION_MAX_COUNT} 条"
+        ));
+    }
+    let mut previous_versions = HashMap::<&str, (u64, u64)>::new();
+    for (index, version) in versions.iter().enumerate() {
+        if version.schema_version != RUNNABLE_GAME_VERSION_SCHEMA_VERSION {
+            return Err(format!(
+                "不支持的可运行版本合同：{}",
+                version.schema_version
+            ));
+        }
+        validate_iteration_version_id(&version.version_id, "可运行版本 ID", 128)?;
+        if previous_versions.contains_key(version.version_id.as_str()) {
+            return Err(format!("可运行版本 ID 重复：{}", version.version_id));
+        }
+        if version.project_id != project_id {
+            return Err(format!("可运行版本 {} 不属于当前项目", version.version_id));
+        }
+        if version.project_revision == 0
+            || version.project_revision > GAME_ITERATION_VERSION_MAX_SAFE_INTEGER
+            || version.created_at > GAME_ITERATION_VERSION_MAX_SAFE_INTEGER
+        {
+            return Err(format!(
+                "可运行版本 {} 的 revision 或创建时间无效",
+                version.version_id
+            ));
+        }
+        let expected_artifact_path =
+            format!(".agent/runnable-versions/{}/artifact", version.version_id);
+        if version.artifact_path != expected_artifact_path
+            || version.entry_path != "game/index.html"
+            || version.artifact_sha256.len() != 64
+            || !version
+                .artifact_sha256
+                .bytes()
+                .all(|value| value.is_ascii_digit() || (b'a'..=b'f').contains(&value))
+        {
+            return Err(format!(
+                "可运行版本 {} 的不可变产物身份无效",
+                version.version_id
+            ));
+        }
+        if !version.validation.static_smoke_passed
+            || !version.validation.preview_validate_passed
+            || !version.validation.playtest_passed
+        {
+            return Err(format!(
+                "可运行版本 {} 缺少完整验证凭证",
+                version.version_id
+            ));
+        }
+        validate_iteration_version_id(&version.validation.agent_id, "验证 Agent ID", 128)?;
+        validate_iteration_version_id(&version.validation.run_id, "验证 run ID", 128)?;
+        if !version
+            .validation
+            .report_path
+            .starts_with(".agent/runtime/browser-validations/")
+            || !version.validation.report_path.ends_with("/validation.json")
+            || version.validation.report_path.contains("..")
+            || version.validation.report_path.chars().any(char::is_control)
+        {
+            return Err(format!(
+                "可运行版本 {} 的 preview.validate 报告路径无效",
+                version.version_id
+            ));
+        }
+
+        if index == 0 {
+            if version.parent_version_id.is_some()
+                || version.created_reason != RunnableGameVersionCreatedReason::Initial
+            {
+                return Err("首个可运行版本必须是无父版本的 initial 版本".to_string());
+            }
+        } else {
+            if version.created_reason != RunnableGameVersionCreatedReason::AgentRevision {
+                return Err("后续可运行版本必须使用 agent-revision 创建原因".to_string());
+            }
+            let Some(parent_id) = version.parent_version_id.as_deref() else {
+                return Err("后续可运行版本必须引用更早的父版本".to_string());
+            };
+            let Some((parent_revision, parent_created_at)) = previous_versions.get(parent_id)
+            else {
+                return Err(format!(
+                    "可运行版本 {} 的父版本必须先于子版本存在",
+                    version.version_id
+                ));
+            };
+            if version.project_revision <= *parent_revision
+                || version.created_at < *parent_created_at
+            {
+                return Err(format!(
+                    "可运行版本 {} 的 revision 或创建时间早于父版本",
+                    version.version_id
+                ));
+            }
+        }
+
+        if version.resource_bindings.len() > GAME_ITERATION_VERSION_MAX_BINDING_COUNT {
+            return Err(format!("可运行版本 {} 的资源绑定过多", version.version_id));
+        }
+        let mut slot_ids = HashSet::new();
+        for binding in &version.resource_bindings {
+            validate_iteration_version_id(&binding.slot_id, "可运行版本资源槽位 ID", 256)?;
+            validate_iteration_version_id(&binding.resource_id, "可运行版本资源 ID", 512)?;
+            if !slot_ids.insert(binding.slot_id.as_str()) {
+                return Err(format!(
+                    "可运行版本 {} 的资源槽位重复：{}",
+                    version.version_id, binding.slot_id
+                ));
+            }
+        }
+        previous_versions.insert(
+            version.version_id.as_str(),
+            (version.project_revision, version.created_at),
+        );
+    }
+
+    match current_version_id {
+        Some(current) if versions.iter().any(|version| version.version_id == current) => Ok(()),
+        Some(_) => Err("当前可运行版本不存在于版本 manifest".to_string()),
+        None if versions.is_empty() => Ok(()),
+        None => Err("存在可运行版本时必须选择当前运行版本".to_string()),
+    }
+}
+
 #[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
 #[serde(rename_all = "camelCase")]
 pub struct GameCreationAppManifest {
@@ -764,6 +1115,10 @@ pub struct GameCreationAppManifest {
     pub command_runs: Vec<GameCreationAppCommandRunState>,
     #[serde(default, skip_serializing_if = "Vec::is_empty")]
     pub versions: Vec<GameIterationVersion>,
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub runnable_versions: Vec<RunnableGameVersion>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub current_runnable_version_id: Option<String>,
 }
 
 #[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
@@ -896,6 +1251,8 @@ pub fn new_game_creation_app_manifest(
         preview: None,
         command_runs: Vec::new(),
         versions: Vec::new(),
+        runnable_versions: Vec::new(),
+        current_runnable_version_id: None,
     }
 }
 
@@ -1943,4 +2300,152 @@ mod tests {
         });
         assert!(serde_json::from_value::<ProjectResourceCanvasLayout>(unsafe_payload).is_err());
     }
+
+    fn runnable_version_fixture(
+        version_id: &str,
+        parent_version_id: Option<&str>,
+        revision: u64,
+        created_reason: RunnableGameVersionCreatedReason,
+    ) -> RunnableGameVersion {
+        RunnableGameVersion {
+            schema_version: RUNNABLE_GAME_VERSION_SCHEMA_VERSION.to_string(),
+            version_id: version_id.to_string(),
+            project_id: "project-runnable".to_string(),
+            parent_version_id: parent_version_id.map(str::to_string),
+            project_revision: revision,
+            artifact_path: format!(".agent/runnable-versions/{version_id}/artifact"),
+            artifact_sha256: "a".repeat(64),
+            entry_path: "game/index.html".to_string(),
+            resource_bindings: vec![GameIterationVersionResourceBinding {
+                slot_id: "player".to_string(),
+                resource_id: "asset-player".to_string(),
+            }],
+            created_reason,
+            validation: RunnableGameVersionValidation {
+                static_smoke_passed: true,
+                preview_validate_passed: true,
+                playtest_passed: true,
+                agent_id: "program-agent".to_string(),
+                run_id: format!("run-{revision}"),
+                report_path: format!(
+                    ".agent/runtime/browser-validations/program-agent/run-{revision}/{revision}/validation.json"
+                ),
+            },
+            created_at: revision * 100,
+        }
+    }
+
+    #[test]
+    fn runnable_versions_require_a_valid_append_graph_and_current_pointer() {
+        let root = runnable_version_fixture(
+            "runnable-r1",
+            None,
+            1,
+            RunnableGameVersionCreatedReason::Initial,
+        );
+        let child = runnable_version_fixture(
+            "runnable-r2",
+            Some("runnable-r1"),
+            2,
+            RunnableGameVersionCreatedReason::AgentRevision,
+        );
+        validate_runnable_game_versions(
+            "project-runnable",
+            &[root.clone(), child.clone()],
+            Some("runnable-r2"),
+        )
+        .expect("accept valid runnable version graph");
+
+        assert!(
+            validate_runnable_game_versions(
+                "project-runnable",
+                &[root.clone(), child.clone()],
+                Some("missing")
+            )
+            .expect_err("reject missing current version")
+            .contains("当前可运行版本不存在")
+        );
+
+        let mut invalid_child = child.clone();
+        invalid_child.validation.playtest_passed = false;
+        assert!(
+            validate_runnable_game_versions(
+                "project-runnable",
+                &[root.clone(), invalid_child],
+                Some("runnable-r2")
+            )
+            .expect_err("reject incomplete validation")
+            .contains("缺少完整验证凭证")
+        );
+
+        let mut invalid_child = child;
+        invalid_child.artifact_path = ".agent/runnable-versions/other/artifact".to_string();
+        assert!(
+            validate_runnable_game_versions(
+                "project-runnable",
+                &[root, invalid_child],
+                Some("runnable-r2")
+            )
+            .expect_err("reject mutable artifact identity")
+            .contains("不可变产物身份无效")
+        );
+    }
+
+    #[test]
+    fn workbench_p2_message_types_keep_the_frozen_wire_values() {
+        let host = GameHostMessage {
+            schema_version: "game-creator-host-message.v1".to_string(),
+            session_id: "session-1".to_string(),
+            sequence: 1,
+            message_type: GameHostMessageType::HostStart,
+            version_id: "runnable-r7".to_string(),
+            project_revision: 7,
+        };
+        assert_eq!(
+            serde_json::to_value(host).expect("serialize host message"),
+            json!({
+                "schemaVersion": "game-creator-host-message.v1",
+                "sessionId": "session-1",
+                "sequence": 1,
+                "type": "host.start",
+                "versionId": "runnable-r7",
+                "projectRevision": 7
+            })
+        );
+
+        let runtime = GameRuntimeMessage {
+            schema_version: "game-creator-runtime-message.v1".to_string(),
+            session_id: "session-1".to_string(),
+            sequence: 2,
+            message_type: GameRuntimeMessageType::RuntimeReady,
+            version_id: "runnable-r7".to_string(),
+            project_revision: 7,
+            detail: None,
+        };
+        let value = serde_json::to_value(runtime).expect("serialize runtime message");
+        assert_eq!(value["type"], "runtime.ready");
+        assert!(value.get("detail").is_none());
+    }
+
+    #[test]
+    fn tunable_parameter_contract_can_never_authorize_code_mutation() {
+        let definition = GameTunableParameterDefinition {
+            parameter_id: "enemy-speed".to_string(),
+            label: "敌人速度".to_string(),
+            value_type: GameTunableParameterValueType::Number,
+            min: Some(0.5),
+            max: Some(2.0),
+            step: Some(0.1),
+            enum_values: None,
+            write_path: "game.balance.enemySpeed".to_string(),
+            code_mutation_allowed: GameCodeMutationAllowed,
+        };
+        let value = serde_json::to_value(definition).expect("serialize tunable parameter");
+        assert_eq!(value["codeMutationAllowed"], false);
+        assert!(value.get("enumValues").is_none());
+
+        let mut invalid = value;
+        invalid["codeMutationAllowed"] = json!(true);
+        assert!(serde_json::from_value::<GameTunableParameterDefinition>(invalid).is_err());
+    }
 }
-- 
2.52.0


From 203ce5b9e749d373c5eb624086761b3a6dea6f16 Mon Sep 17 00:00:00 2001
From: menghao <mh18530625731@163.com>
Date: Tue, 4 Aug 2026 16:16:04 +0800
Subject: [PATCH 20/27] =?UTF-8?q?=E5=AE=9E=E7=8E=B0=E6=B8=B8=E6=88=8F?=
 =?UTF-8?q?=E8=BF=90=E8=A1=8C=E4=BC=9A=E8=AF=9D=E4=B8=8E=E6=A1=A5=E6=8E=A5?=
 =?UTF-8?q?=E5=8D=8F=E8=AE=AE?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

冻结 Host/Game Bridge 双向消息合同与安全校验
为 PreviewRegistry 增加预览身份并注入宿主 bootstrap
接入 iframe 一次性会话、状态投影和暂停继续控制
补充协议、AppSurface、Rust 生命周期与共享合同测试
同步更新工作台 PRD、技术方案和共享决策记录
---
 .../src-tauri/src/main.rs                     |   8 +
 .../src-tauri/src/preview.rs                  | 194 +++++++-
 .../src-tauri/src/tests/project.rs            |  65 +++
 .../LocalGamePreviewFrame.tsx                 | 204 +++++++-
 .../project-workspace/gameRunBridge.ts        | 467 ++++++++++++++++++
 apps/ai-game-creator-shell/src/styles.css     |  19 +-
 .../src/view/project-development/index.tsx    | 126 ++++-
 .../appSurface/project-development.suite.ts   | 149 ++++++
 .../tests/gameRunBridge.test.ts               | 215 ++++++++
 ...AI游戏创作】项目开发工作台PRD-2026-07-20.md |  68 ++-
 .../shared-memory/decision-log.md             |  12 +-
 ...�案】AI游戏创作智能体App实施计划-2026-06-24.md |  14 +-
 .../shared/src/contracts/gameCreationApp.ts   |  77 ++-
 .../shared-contracts/src/game_creation_app.rs |  51 +-
 14 files changed, 1624 insertions(+), 45 deletions(-)
 create mode 100644 apps/ai-game-creator-shell/src/features/project-workspace/gameRunBridge.ts
 create mode 100644 apps/ai-game-creator-shell/tests/gameRunBridge.test.ts

diff --git a/apps/ai-game-creator-shell/src-tauri/src/main.rs b/apps/ai-game-creator-shell/src-tauri/src/main.rs
index f068b3b24..cb2bacc74 100644
--- a/apps/ai-game-creator-shell/src-tauri/src/main.rs
+++ b/apps/ai-game-creator-shell/src-tauri/src/main.rs
@@ -141,6 +141,13 @@ struct LocalPreviewResult {
     root: String,
 }
 
+#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
+#[serde(rename_all = "camelCase")]
+struct LocalPreviewIdentity {
+    preview_id: String,
+    origin: String,
+}
+
 #[derive(Clone, Debug, Eq, PartialEq, Serialize)]
 #[serde(rename_all = "camelCase")]
 struct LocalPreviewStatus {
@@ -156,6 +163,7 @@ struct RunnableGameVersionLaunchResult {
     manifest: GameCreationAppManifest,
     version: RunnableGameVersion,
     preview: LocalPreviewResult,
+    preview_identity: LocalPreviewIdentity,
 }
 
 #[derive(Clone, Debug, Eq, PartialEq, Serialize)]
diff --git a/apps/ai-game-creator-shell/src-tauri/src/preview.rs b/apps/ai-game-creator-shell/src-tauri/src/preview.rs
index 717a5c3cf..8ed4abde0 100644
--- a/apps/ai-game-creator-shell/src-tauri/src/preview.rs
+++ b/apps/ai-game-creator-shell/src-tauri/src/preview.rs
@@ -7,6 +7,7 @@ pub(crate) struct PreviewRegistry {
 
 struct PreviewServer {
     preview: LocalPreviewResult,
+    identity: LocalPreviewIdentity,
     stop: mpsc::Sender<()>,
 }
 
@@ -16,6 +17,19 @@ impl PreviewRegistry {
         preview: LocalPreviewResult,
         stop: mpsc::Sender<()>,
     ) -> (LocalPreviewResult, Option<LocalPreviewResult>) {
+        let (preview, _, previous_preview) = self.set_running_with_identity(preview, stop);
+        (preview, previous_preview)
+    }
+
+    pub(crate) fn set_running_with_identity(
+        &self,
+        preview: LocalPreviewResult,
+        stop: mpsc::Sender<()>,
+    ) -> (
+        LocalPreviewResult,
+        LocalPreviewIdentity,
+        Option<LocalPreviewResult>,
+    ) {
         let mut current = self.current.lock().expect("preview registry lock");
         let previous_preview = if let Some(previous) = current.take() {
             let preview = previous.preview;
@@ -24,11 +38,21 @@ impl PreviewRegistry {
         } else {
             None
         };
+        let identity = LocalPreviewIdentity {
+            preview_id: format!("preview-{}", uuid::Uuid::new_v4().simple()),
+            origin: format!("http://127.0.0.1:{}", preview.port),
+        };
         *current = Some(PreviewServer {
             preview: preview.clone(),
+            identity: identity.clone(),
             stop,
         });
-        (preview, previous_preview)
+        let registry_identity = current
+            .as_ref()
+            .expect("preview registry current server")
+            .identity
+            .clone();
+        (preview, registry_identity, previous_preview)
     }
 
     pub(crate) fn status(&self) -> LocalPreviewStatus {
@@ -89,6 +113,125 @@ const PREVIEW_REQUEST_MAX_HEADER_BYTES: usize = 32 * 1024;
 const PREVIEW_REQUEST_MAX_HEADER_LINES: usize = 100;
 const PREVIEW_RESPONSE_DRAIN_TIMEOUT: Duration = Duration::from_millis(250);
 const PREVIEW_RESPONSE_DRAIN_MAX_BYTES: usize = 32 * 1024;
+const GAME_RUN_BRIDGE_SCRIPT_PATH: &str = "/.genarrative/game-bridge.v1.js";
+const GAME_RUN_BRIDGE_SCRIPT_TAG: &str =
+    r#"<script src="/.genarrative/game-bridge.v1.js" data-genarrative-game-bridge="v1"></script>"#;
+const GAME_RUN_BRIDGE_BOOTSTRAP: &str = r#"(() => {
+  'use strict';
+  const protocolVersion = 'game-creator-run-bridge.v1';
+  const hostSchema = 'game-creator-host-message.v1';
+  const runtimeSchema = 'game-creator-runtime-message.v1';
+  const hostTypes = new Set(['host.start', 'host.pause', 'host.resume', 'host.stop', 'host.state.request', 'host.inspection.request']);
+  let session = null;
+  let hostOrigin = null;
+  let hostSequence = 0;
+  let runtimeSequence = 0;
+  let state = 'starting';
+  const hostRequestIds = new Set();
+
+  const randomId = () => {
+    const bytes = new Uint8Array(16);
+    crypto.getRandomValues(bytes);
+    return `runtime-request-${Array.from(bytes, value => value.toString(16).padStart(2, '0')).join('')}`;
+  };
+  const sameIdentity = message => session &&
+    message.sessionId === session.sessionId &&
+    message.previewId === session.previewId &&
+    message.projectId === session.projectId &&
+    message.versionId === session.versionId &&
+    message.projectRevision === session.projectRevision;
+  const send = (type, payload, responseTo) => {
+    if (!session || !hostOrigin) return false;
+    const message = {
+      schemaVersion: runtimeSchema,
+      protocolVersion,
+      requestId: randomId(),
+      sessionId: session.sessionId,
+      previewId: session.previewId,
+      projectId: session.projectId,
+      sequence: ++runtimeSequence,
+      type,
+      versionId: session.versionId,
+      projectRevision: session.projectRevision,
+      payload,
+    };
+    if (responseTo) message.responseTo = responseTo;
+    parent.postMessage(message, hostOrigin);
+    return true;
+  };
+  const reportState = (nextState, summary) => {
+    state = nextState;
+    return send('runtime.state', summary === undefined ? { status: nextState } : { status: nextState, summary });
+  };
+  const reportError = (code, message, recoverable = false) =>
+    send('runtime.error', { code, message, recoverable });
+  const reportSlice = (sliceId, title, status, summary) =>
+    send('runtime.slice', summary === undefined ? { sliceId, title, status } : { sliceId, title, status, summary });
+  const reportInspection = (inspectionId, label, metrics, summary) =>
+    send('runtime.inspection', summary === undefined ? { inspectionId, label, metrics } : { inspectionId, label, metrics, summary });
+
+  Object.defineProperty(window, 'genarrativeGameBridge', {
+    configurable: false,
+    enumerable: false,
+    writable: false,
+    value: Object.freeze({ protocolVersion, reportState, reportError, reportSlice, reportInspection }),
+  });
+
+  addEventListener('message', event => {
+    const message = event.data;
+    if (event.source !== parent || !message || typeof message !== 'object' ||
+        message.schemaVersion !== hostSchema || message.protocolVersion !== protocolVersion ||
+        !hostTypes.has(message.type) || !Number.isSafeInteger(message.sequence) ||
+        typeof message.requestId !== 'string' || hostRequestIds.has(message.requestId)) return;
+    if (message.type === 'host.start') {
+      if (session || message.sequence !== 1 || typeof message.sessionId !== 'string' ||
+          typeof message.previewId !== 'string' || typeof message.projectId !== 'string' ||
+          typeof message.versionId !== 'string' || !Number.isSafeInteger(message.projectRevision)) return;
+      hostOrigin = event.origin;
+      hostSequence = 1;
+      hostRequestIds.add(message.requestId);
+      session = {
+        sessionId: message.sessionId,
+        previewId: message.previewId,
+        projectId: message.projectId,
+        versionId: message.versionId,
+        projectRevision: message.projectRevision,
+      };
+      send('runtime.ready', { capabilities: ['state', 'slice', 'inspection'] }, message.requestId);
+      state = 'playing';
+      send('runtime.state', { status: state });
+      dispatchEvent(new CustomEvent('genarrative:host-message', { detail: message }));
+      return;
+    }
+    if (event.origin !== hostOrigin || !sameIdentity(message) || message.sequence !== hostSequence + 1) return;
+    hostSequence = message.sequence;
+    hostRequestIds.add(message.requestId);
+    if (message.type === 'host.pause') {
+      state = 'paused';
+      send('runtime.state', { status: state }, message.requestId);
+    } else if (message.type === 'host.resume') {
+      state = 'playing';
+      send('runtime.state', { status: state }, message.requestId);
+    } else if (message.type === 'host.state.request') {
+      send('runtime.state', { status: state }, message.requestId);
+    } else if (message.type === 'host.inspection.request') {
+      send('runtime.inspection', {
+        inspectionId: 'host-baseline',
+        label: '运行画面',
+        metrics: { state, viewportWidth: innerWidth, viewportHeight: innerHeight },
+      }, message.requestId);
+    } else if (message.type === 'host.stop') {
+      state = 'stopped';
+      send('runtime.state', { status: state }, message.requestId);
+    }
+    dispatchEvent(new CustomEvent('genarrative:host-message', { detail: message }));
+    if (message.type === 'host.stop') {
+      session = null;
+      hostOrigin = null;
+    }
+  });
+})();
+"#;
 
 #[derive(Clone, Copy, Debug, Eq, PartialEq)]
 pub(crate) enum PreviewListenerAcceptDisposition {
@@ -500,7 +643,8 @@ pub(crate) fn launch_local_game_runnable_version(
         let _ = record_preview_state(root, GameCreationAppPreviewStatus::Failed, None, None);
         return Err(error);
     }
-    let (preview, previous_preview) = registry.set_running(preview, stop);
+    let (preview, preview_identity, previous_preview) =
+        registry.set_running_with_identity(preview, stop);
     if let Some(previous_preview) = previous_preview.as_ref() {
         record_replaced_preview_stop(previous_preview);
     }
@@ -525,6 +669,7 @@ pub(crate) fn launch_local_game_runnable_version(
         manifest,
         version: selected_version,
         preview,
+        preview_identity,
     })
 }
 
@@ -645,6 +790,21 @@ pub(crate) fn build_preview_response(root: &Path, method: &str, url_path: &str)
         );
     }
 
+    if url_path.split('?').next() == Some(GAME_RUN_BRIDGE_SCRIPT_PATH) {
+        let content_length = GAME_RUN_BRIDGE_BOOTSTRAP.len();
+        let body = if is_head {
+            Vec::new()
+        } else {
+            GAME_RUN_BRIDGE_BOOTSTRAP.as_bytes().to_vec()
+        };
+        return http_response(
+            "200 OK",
+            "text/javascript; charset=utf-8",
+            &body,
+            content_length,
+        );
+    }
+
     let file_path = match resolve_preview_path(root, url_path) {
         Ok(path) => path,
         Err(_) => {
@@ -659,11 +819,41 @@ pub(crate) fn build_preview_response(root: &Path, method: &str, url_path: &str)
             return http_response("404 Not Found", "text/plain", body, b"not found".len());
         }
     };
+    let body = if file_path.extension().and_then(|value| value.to_str()) == Some("html") {
+        inject_game_run_bridge_tag(body)
+    } else {
+        body
+    };
     let content_length = body.len();
     let body = if is_head { Vec::new() } else { body };
     http_response("200 OK", content_type(&file_path), &body, content_length)
 }
 
+fn inject_game_run_bridge_tag(body: Vec<u8>) -> Vec<u8> {
+    let html = match String::from_utf8(body) {
+        Ok(html) => html,
+        Err(error) => return error.into_bytes(),
+    };
+    if html.contains("data-genarrative-game-bridge=") {
+        return html.into_bytes();
+    }
+    let lowercase = html.to_ascii_lowercase();
+    let insertion_index = lowercase
+        .find("<head")
+        .and_then(|start| {
+            lowercase[start..]
+                .find('>')
+                .map(|offset| start + offset + 1)
+        })
+        .or_else(|| lowercase.find("</body>"))
+        .unwrap_or(html.len());
+    let mut injected = String::with_capacity(html.len() + GAME_RUN_BRIDGE_SCRIPT_TAG.len());
+    injected.push_str(&html[..insertion_index]);
+    injected.push_str(GAME_RUN_BRIDGE_SCRIPT_TAG);
+    injected.push_str(&html[insertion_index..]);
+    injected.into_bytes()
+}
+
 pub(crate) fn resolve_preview_path(root: &Path, url_path: &str) -> Result<PathBuf, String> {
     let path = url_path.split('?').next().unwrap_or("/");
     let decoded = percent_decode_path(path).ok_or_else(|| "预览路径非法".to_string())?;
diff --git a/apps/ai-game-creator-shell/src-tauri/src/tests/project.rs b/apps/ai-game-creator-shell/src-tauri/src/tests/project.rs
index 2f638d6bb..cd5b82ef9 100644
--- a/apps/ai-game-creator-shell/src-tauri/src/tests/project.rs
+++ b/apps/ai-game-creator-shell/src-tauri/src/tests/project.rs
@@ -2414,6 +2414,41 @@ fn preview_registry_reports_status_and_stops_previous_server() {
     assert_eq!(registry.status().status, "stopped");
 }
 
+#[test]
+fn preview_registry_rotates_p3_identity_with_the_owned_server() {
+    let registry = PreviewRegistry::default();
+    let (first_stop, first_receiver) = mpsc::channel();
+    let (_, first_identity, previous) = registry.set_running_with_identity(
+        LocalPreviewResult {
+            url: "http://127.0.0.1:4101/".to_string(),
+            port: 4101,
+            root: "/tmp/game-one".to_string(),
+        },
+        first_stop,
+    );
+    assert!(previous.is_none());
+    assert_eq!(first_identity.origin, "http://127.0.0.1:4101");
+    assert!(first_identity.preview_id.starts_with("preview-"));
+
+    let (second_stop, _) = mpsc::channel();
+    let (_, second_identity, previous) = registry.set_running_with_identity(
+        LocalPreviewResult {
+            url: "http://127.0.0.1:4102/".to_string(),
+            port: 4102,
+            root: "/tmp/game-two".to_string(),
+        },
+        second_stop,
+    );
+    assert!(first_receiver.try_recv().is_ok());
+    assert_eq!(
+        previous.expect("replaced preview").url,
+        "http://127.0.0.1:4101/"
+    );
+    assert_ne!(first_identity.preview_id, second_identity.preview_id);
+    assert_eq!(second_identity.origin, "http://127.0.0.1:4102");
+    registry.stop();
+}
+
 #[test]
 fn replaced_preview_records_stopped_state() {
     let root = unique_project_path();
@@ -3254,6 +3289,36 @@ fn local_preview_can_serve_an_immutable_version_snapshot_instead_of_the_working_
     fs::remove_dir_all(root).ok();
 }
 
+#[test]
+fn local_preview_injects_the_host_owned_p3_bridge_without_mutating_html() {
+    let root = unique_project_path();
+    init_local_game_project_at(&root, "project-bridge", "运行桥预览测试").expect("project init");
+    let original = "<!doctype html><html><head><title>Bridge</title></head><body></body></html>";
+    fs::write(root.join("game/index.html"), original).expect("write bridge fixture");
+
+    let html_response =
+        String::from_utf8(build_preview_response(&root, "GET", "/")).expect("html response");
+    assert!(html_response.contains("data-genarrative-game-bridge=\"v1\""));
+    assert!(html_response.contains("/.genarrative/game-bridge.v1.js"));
+    assert_eq!(
+        fs::read_to_string(root.join("game/index.html")).expect("read original html"),
+        original
+    );
+
+    let script_response = String::from_utf8(build_preview_response(
+        &root,
+        "GET",
+        "/.genarrative/game-bridge.v1.js",
+    ))
+    .expect("bridge response");
+    assert!(script_response.contains("Content-Type: text/javascript; charset=utf-8"));
+    assert!(script_response.contains("game-creator-run-bridge.v1"));
+    assert!(script_response.contains("runtime.ready"));
+    assert!(script_response.contains("event.source !== parent"));
+
+    fs::remove_dir_all(root).ok();
+}
+
 #[test]
 fn local_preview_server_drains_split_browser_headers_before_response() {
     let root = unique_project_path();
diff --git a/apps/ai-game-creator-shell/src/features/project-workspace/LocalGamePreviewFrame.tsx b/apps/ai-game-creator-shell/src/features/project-workspace/LocalGamePreviewFrame.tsx
index 401757601..c706366bb 100644
--- a/apps/ai-game-creator-shell/src/features/project-workspace/LocalGamePreviewFrame.tsx
+++ b/apps/ai-game-creator-shell/src/features/project-workspace/LocalGamePreviewFrame.tsx
@@ -1,10 +1,49 @@
-/* eslint-disable react-refresh/only-export-components -- The URL guard is exported with its small rendering adapter for focused tests. */
+/* eslint-disable react-refresh/only-export-components -- The URL guard is exported with its rendering adapter for focused tests. */
+
+import {
+  forwardRef,
+  useCallback,
+  useEffect,
+  useImperativeHandle,
+  useRef,
+} from 'react';
+
+import type {
+  GameHostMessageType,
+  GameRunSession,
+  GameRuntimeMessage,
+} from '../../../../../packages/shared/src/contracts/gameCreationApp';
+import {
+  createGameHostMessage,
+  createGameRunSession,
+  type GameRunBridgeIdentity,
+  GameRunBridgeRuntimeGuard,
+  gameRunSessionFromRuntimeMessage,
+  newGameRunBridgeRequestId,
+  newGameRunSessionId,
+  validateGameRunBridgeIdentity,
+} from './gameRunBridge';
 
 export type LocalGamePreviewLike = {
   status?: string | null;
   url?: string | null;
 };
 
+export type LocalGamePreviewFrameHandle = {
+  pause: () => boolean;
+  resume: () => boolean;
+  stop: () => boolean;
+  requestState: () => boolean;
+  requestInspection: () => boolean;
+};
+
+type ActiveBridgeSession = {
+  guard: GameRunBridgeRuntimeGuard;
+  identity: GameRunBridgeIdentity;
+  nextHostSequence: number;
+  session: GameRunSession;
+};
+
 export function resolveEmbeddedPreviewUrl(
   preview: LocalGamePreviewLike | null | undefined,
 ) {
@@ -25,26 +64,169 @@ export function resolveEmbeddedPreviewUrl(
   }
 }
 
-export function LocalGamePreviewFrame({
-  preview,
-  title,
-  className,
-}: {
-  preview: LocalGamePreviewLike | null | undefined;
-  title: string;
-  className?: string;
-}) {
+export const LocalGamePreviewFrame = forwardRef<
+  LocalGamePreviewFrameHandle,
+  {
+    preview: LocalGamePreviewLike | null | undefined;
+    title: string;
+    className?: string;
+    runIdentity?: GameRunBridgeIdentity | null;
+    onSessionChange?: (session: GameRunSession) => void;
+    onRuntimeMessage?: (message: GameRuntimeMessage) => void;
+    onBridgeError?: (message: string) => void;
+  }
+>(function LocalGamePreviewFrame(
+  {
+    preview,
+    title,
+    className,
+    runIdentity,
+    onSessionChange,
+    onRuntimeMessage,
+    onBridgeError,
+  },
+  forwardedRef,
+) {
   const embeddedUrl = resolveEmbeddedPreviewUrl(preview);
+  const iframeRef = useRef<HTMLIFrameElement>(null);
+  const activeRef = useRef<ActiveBridgeSession | null>(null);
+  const callbacksRef = useRef({
+    onBridgeError,
+    onRuntimeMessage,
+    onSessionChange,
+  });
+  callbacksRef.current = {
+    onBridgeError,
+    onRuntimeMessage,
+    onSessionChange,
+  };
+
+  const sendHostMessage = useCallback((type: GameHostMessageType) => {
+    const active = activeRef.current;
+    const targetWindow = iframeRef.current?.contentWindow;
+    if (!active || !targetWindow) {
+      return false;
+    }
+    const requestId = newGameRunBridgeRequestId('host');
+    if (!requestId || !active.guard.registerHostRequest(requestId, type)) {
+      callbacksRef.current.onBridgeError?.('运行会话无法创建安全请求身份');
+      return false;
+    }
+    const message = createGameHostMessage({
+      identity: active.identity,
+      sessionId: active.session.sessionId,
+      requestId,
+      sequence: active.nextHostSequence,
+      type,
+    });
+    active.nextHostSequence += 1;
+    targetWindow.postMessage(message, active.identity.previewOrigin);
+    return true;
+  }, []);
+
+  const stopActiveSession = useCallback(
+    (notify: boolean) => {
+      const active = activeRef.current;
+      if (!active) {
+        return false;
+      }
+      sendHostMessage('host.stop');
+      activeRef.current = null;
+      if (notify) {
+        callbacksRef.current.onSessionChange?.({
+          ...active.session,
+          status: 'stopped',
+          updatedAt: Date.now(),
+        });
+      }
+      return true;
+    },
+    [sendHostMessage],
+  );
+
+  useImperativeHandle(
+    forwardedRef,
+    () => ({
+      pause: () => sendHostMessage('host.pause'),
+      resume: () => sendHostMessage('host.resume'),
+      stop: () => stopActiveSession(true),
+      requestState: () => sendHostMessage('host.state.request'),
+      requestInspection: () => sendHostMessage('host.inspection.request'),
+    }),
+    [sendHostMessage, stopActiveSession],
+  );
+
+  useEffect(() => {
+    function receiveRuntimeMessage(event: MessageEvent<unknown>) {
+      const active = activeRef.current;
+      if (
+        !active ||
+        event.source !== iframeRef.current?.contentWindow ||
+        event.origin !== active.identity.previewOrigin
+      ) {
+        return;
+      }
+      const message = active.guard.accept(event.data);
+      if (!message) {
+        return;
+      }
+      active.session = gameRunSessionFromRuntimeMessage(
+        active.session,
+        message,
+        Date.now(),
+      );
+      callbacksRef.current.onSessionChange?.(active.session);
+      callbacksRef.current.onRuntimeMessage?.(message);
+    }
+    window.addEventListener('message', receiveRuntimeMessage);
+    return () => {
+      window.removeEventListener('message', receiveRuntimeMessage);
+      stopActiveSession(false);
+    };
+  }, [stopActiveSession]);
+
+  function handleLoad() {
+    stopActiveSession(true);
+    if (!runIdentity || !embeddedUrl) {
+      return;
+    }
+    const identity = validateGameRunBridgeIdentity(runIdentity);
+    if (!identity || new URL(embeddedUrl).origin !== identity.previewOrigin) {
+      callbacksRef.current.onBridgeError?.(
+        '运行预览身份与 loopback origin 不一致',
+      );
+      return;
+    }
+    const sessionId = newGameRunSessionId();
+    if (!sessionId) {
+      callbacksRef.current.onBridgeError?.('当前 WebView 不支持安全运行会话');
+      return;
+    }
+    const session = createGameRunSession(identity, sessionId, Date.now());
+    activeRef.current = {
+      guard: new GameRunBridgeRuntimeGuard(identity, sessionId),
+      identity,
+      nextHostSequence: 1,
+      session,
+    };
+    callbacksRef.current.onSessionChange?.(session);
+    if (!sendHostMessage('host.start')) {
+      activeRef.current = null;
+    }
+  }
+
   if (!embeddedUrl) {
     return null;
   }
   return (
     <iframe
+      ref={iframeRef}
       className={className}
       title={title}
       src={embeddedUrl}
       sandbox="allow-scripts allow-same-origin allow-forms allow-pointer-lock"
       allow="autoplay; fullscreen; gamepad"
+      onLoad={handleLoad}
     />
   );
-}
+});
diff --git a/apps/ai-game-creator-shell/src/features/project-workspace/gameRunBridge.ts b/apps/ai-game-creator-shell/src/features/project-workspace/gameRunBridge.ts
new file mode 100644
index 000000000..ced61e597
--- /dev/null
+++ b/apps/ai-game-creator-shell/src/features/project-workspace/gameRunBridge.ts
@@ -0,0 +1,467 @@
+import type {
+  GameHostMessage,
+  GameHostMessageType,
+  GameRunSession,
+  GameRuntimeInspectionMetric,
+  GameRuntimeMessage,
+} from '../../../../../packages/shared/src/contracts/gameCreationApp';
+import {
+  GAME_HOST_MESSAGE_SCHEMA_VERSION,
+  GAME_RUN_BRIDGE_MAX_MESSAGE_BYTES,
+  GAME_RUN_BRIDGE_PROTOCOL_VERSION,
+  GAME_RUNTIME_MESSAGE_SCHEMA_VERSION,
+} from '../../../../../packages/shared/src/contracts/gameCreationApp';
+
+export type GameRunBridgeIdentity = {
+  projectId: string;
+  versionId: string;
+  projectRevision: number;
+  previewId: string;
+  previewOrigin: string;
+};
+
+const RUNTIME_MESSAGE_TYPES = new Set([
+  'runtime.ready',
+  'runtime.state',
+  'runtime.error',
+  'runtime.slice',
+  'runtime.inspection',
+]);
+const RUNTIME_CAPABILITIES = new Set(['state', 'slice', 'inspection']);
+const RUNTIME_STATES = new Set([
+  'starting',
+  'playing',
+  'paused',
+  'completed',
+  'stopped',
+]);
+const SLICE_STATES = new Set([
+  'idle',
+  'starting',
+  'playing',
+  'paused',
+  'completed',
+  'failed',
+]);
+const DANGEROUS_FIELD =
+  /(?:^|[-_])(path|file|url|href|src|html|script|command|shell|tauri|invoke)(?:$|[-_])/iu;
+const HTML_OR_ACTIVE_URL =
+  /<\/?[a-z][^>]*>|(?:https?|file|javascript|data):|\bhost\.[a-z]/iu;
+const WINDOWS_ABSOLUTE_PATH = /^[a-z]:[\\/]/iu;
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    return false;
+  }
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+
+function hasExactKeys(
+  value: Record<string, unknown>,
+  required: readonly string[],
+  optional: readonly string[] = [],
+) {
+  const keys = Object.keys(value);
+  return (
+    required.every((key) => Object.hasOwn(value, key)) &&
+    keys.every((key) => required.includes(key) || optional.includes(key))
+  );
+}
+
+function hasForbiddenControlCharacter(value: string, allowLineBreaks: boolean) {
+  for (const character of value) {
+    const code = character.charCodeAt(0);
+    if (
+      code === 0x7f ||
+      (code < 0x20 &&
+        (!allowLineBreaks || (code !== 0x09 && code !== 0x0a && code !== 0x0d)))
+    ) {
+      return true;
+    }
+  }
+  return false;
+}
+
+function isSafeIdentifier(value: unknown, maxChars = 256): value is string {
+  return (
+    typeof value === 'string' &&
+    value.length > 0 &&
+    value.length <= maxChars &&
+    value.trim() === value &&
+    !hasForbiddenControlCharacter(value, false)
+  );
+}
+
+function isSafeText(value: unknown, maxChars: number): value is string {
+  return (
+    typeof value === 'string' &&
+    value.length <= maxChars &&
+    !hasForbiddenControlCharacter(value, true) &&
+    !HTML_OR_ACTIVE_URL.test(value) &&
+    !value.startsWith('/') &&
+    !value.startsWith('\\') &&
+    !WINDOWS_ABSOLUTE_PATH.test(value)
+  );
+}
+
+function safeSerializedSize(value: unknown) {
+  try {
+    const serialized = JSON.stringify(value);
+    if (serialized === undefined) {
+      return null;
+    }
+    return new TextEncoder().encode(serialized).byteLength;
+  } catch {
+    return null;
+  }
+}
+
+function validateReadyPayload(payload: unknown) {
+  if (
+    !isPlainObject(payload) ||
+    !hasExactKeys(payload, ['capabilities']) ||
+    !Array.isArray(payload.capabilities) ||
+    payload.capabilities.length > RUNTIME_CAPABILITIES.size
+  ) {
+    return false;
+  }
+  const capabilities = payload.capabilities;
+  return (
+    new Set(capabilities).size === capabilities.length &&
+    capabilities.every(
+      (capability) =>
+        typeof capability === 'string' && RUNTIME_CAPABILITIES.has(capability),
+    )
+  );
+}
+
+function validateStatePayload(payload: unknown) {
+  return (
+    isPlainObject(payload) &&
+    hasExactKeys(payload, ['status'], ['summary']) &&
+    typeof payload.status === 'string' &&
+    RUNTIME_STATES.has(payload.status) &&
+    (payload.summary === undefined || isSafeText(payload.summary, 512))
+  );
+}
+
+function validateErrorPayload(payload: unknown) {
+  return (
+    isPlainObject(payload) &&
+    hasExactKeys(payload, ['code', 'message', 'recoverable']) &&
+    isSafeIdentifier(payload.code, 96) &&
+    isSafeText(payload.message, 512) &&
+    typeof payload.recoverable === 'boolean'
+  );
+}
+
+function validateSlicePayload(payload: unknown) {
+  return (
+    isPlainObject(payload) &&
+    hasExactKeys(payload, ['sliceId', 'title', 'status'], ['summary']) &&
+    isSafeIdentifier(payload.sliceId, 128) &&
+    isSafeText(payload.title, 128) &&
+    typeof payload.status === 'string' &&
+    SLICE_STATES.has(payload.status) &&
+    (payload.summary === undefined || isSafeText(payload.summary, 512))
+  );
+}
+
+function isInspectionMetric(
+  value: unknown,
+): value is GameRuntimeInspectionMetric {
+  return (
+    value === null ||
+    typeof value === 'boolean' ||
+    (typeof value === 'number' && Number.isFinite(value)) ||
+    isSafeText(value, 256)
+  );
+}
+
+function validateInspectionPayload(payload: unknown) {
+  if (
+    !isPlainObject(payload) ||
+    !hasExactKeys(payload, ['inspectionId', 'label', 'metrics'], ['summary']) ||
+    !isSafeIdentifier(payload.inspectionId, 128) ||
+    !isSafeText(payload.label, 128) ||
+    (payload.summary !== undefined && !isSafeText(payload.summary, 512)) ||
+    !isPlainObject(payload.metrics)
+  ) {
+    return false;
+  }
+  const metrics = Object.entries(payload.metrics);
+  return (
+    metrics.length <= 32 &&
+    metrics.every(
+      ([key, value]) =>
+        isSafeIdentifier(key, 64) &&
+        !DANGEROUS_FIELD.test(key) &&
+        isInspectionMetric(value),
+    )
+  );
+}
+
+function validatePayload(type: string, payload: unknown) {
+  switch (type) {
+    case 'runtime.ready':
+      return validateReadyPayload(payload);
+    case 'runtime.state':
+      return validateStatePayload(payload);
+    case 'runtime.error':
+      return validateErrorPayload(payload);
+    case 'runtime.slice':
+      return validateSlicePayload(payload);
+    case 'runtime.inspection':
+      return validateInspectionPayload(payload);
+    default:
+      return false;
+  }
+}
+
+function normalizePreviewOrigin(value: string) {
+  try {
+    const url = new URL(value);
+    if (
+      url.protocol !== 'http:' ||
+      url.hostname !== '127.0.0.1' ||
+      !url.port ||
+      url.pathname !== '/' ||
+      url.search ||
+      url.hash
+    ) {
+      return null;
+    }
+    return url.origin;
+  } catch {
+    return null;
+  }
+}
+
+export function validateGameRunBridgeIdentity(identity: GameRunBridgeIdentity) {
+  const previewOrigin = normalizePreviewOrigin(identity.previewOrigin);
+  if (
+    !isSafeIdentifier(identity.projectId) ||
+    !isSafeIdentifier(identity.versionId) ||
+    !isSafeIdentifier(identity.previewId) ||
+    !Number.isSafeInteger(identity.projectRevision) ||
+    identity.projectRevision <= 0 ||
+    previewOrigin === null
+  ) {
+    return null;
+  }
+  return { ...identity, previewOrigin };
+}
+
+function randomHex(bytesLength: number) {
+  if (!globalThis.crypto?.getRandomValues) {
+    return null;
+  }
+  const bytes = new Uint8Array(bytesLength);
+  globalThis.crypto.getRandomValues(bytes);
+  return Array.from(bytes, (value) => value.toString(16).padStart(2, '0')).join(
+    '',
+  );
+}
+
+export function newGameRunSessionId() {
+  const value = randomHex(16);
+  return value ? `game-run-session-${value}` : null;
+}
+
+export function newGameRunBridgeRequestId(direction: 'host' | 'runtime') {
+  const value = randomHex(16);
+  return value ? `${direction}-request-${value}` : null;
+}
+
+export function createGameRunSession(
+  identity: GameRunBridgeIdentity,
+  sessionId: string,
+  now: number,
+): GameRunSession {
+  return {
+    schemaVersion: 'game-creator-run-session.v1',
+    protocolVersion: GAME_RUN_BRIDGE_PROTOCOL_VERSION,
+    sessionId,
+    previewId: identity.previewId,
+    previewOrigin: identity.previewOrigin,
+    projectId: identity.projectId,
+    versionId: identity.versionId,
+    projectRevision: identity.projectRevision,
+    status: 'starting',
+    stale: false,
+    staleReason: null,
+    startedAt: now,
+    updatedAt: now,
+  };
+}
+
+export function createGameHostMessage({
+  identity,
+  sessionId,
+  requestId,
+  sequence,
+  type,
+}: {
+  identity: GameRunBridgeIdentity;
+  sessionId: string;
+  requestId: string;
+  sequence: number;
+  type: GameHostMessageType;
+}): GameHostMessage {
+  return {
+    schemaVersion: GAME_HOST_MESSAGE_SCHEMA_VERSION,
+    protocolVersion: GAME_RUN_BRIDGE_PROTOCOL_VERSION,
+    requestId,
+    sessionId,
+    previewId: identity.previewId,
+    projectId: identity.projectId,
+    sequence,
+    type,
+    versionId: identity.versionId,
+    projectRevision: identity.projectRevision,
+  };
+}
+
+function responseTypeMatches(
+  runtimeType: string,
+  hostType: GameHostMessageType,
+) {
+  if (runtimeType === 'runtime.error') {
+    return true;
+  }
+  if (runtimeType === 'runtime.ready') {
+    return hostType === 'host.start';
+  }
+  if (runtimeType === 'runtime.state') {
+    return [
+      'host.pause',
+      'host.resume',
+      'host.stop',
+      'host.state.request',
+    ].includes(hostType);
+  }
+  return (
+    runtimeType === 'runtime.inspection' &&
+    hostType === 'host.inspection.request'
+  );
+}
+
+export class GameRunBridgeRuntimeGuard {
+  readonly #identity: GameRunBridgeIdentity;
+  readonly #sessionId: string;
+  readonly #pendingRequests = new Map<string, GameHostMessageType>();
+  readonly #runtimeRequestIds = new Set<string>();
+  #lastRuntimeSequence = 0;
+  #ready = false;
+
+  constructor(identity: GameRunBridgeIdentity, sessionId: string) {
+    this.#identity = identity;
+    this.#sessionId = sessionId;
+  }
+
+  registerHostRequest(requestId: string, type: GameHostMessageType) {
+    if (
+      !isSafeIdentifier(requestId, 128) ||
+      this.#pendingRequests.has(requestId)
+    ) {
+      return false;
+    }
+    this.#pendingRequests.set(requestId, type);
+    return true;
+  }
+
+  accept(data: unknown): GameRuntimeMessage | null {
+    const size = safeSerializedSize(data);
+    if (
+      size === null ||
+      size > GAME_RUN_BRIDGE_MAX_MESSAGE_BYTES ||
+      !isPlainObject(data) ||
+      !hasExactKeys(
+        data,
+        [
+          'schemaVersion',
+          'protocolVersion',
+          'requestId',
+          'sessionId',
+          'previewId',
+          'projectId',
+          'sequence',
+          'type',
+          'versionId',
+          'projectRevision',
+          'payload',
+        ],
+        ['responseTo'],
+      )
+    ) {
+      return null;
+    }
+    if (
+      data.schemaVersion !== GAME_RUNTIME_MESSAGE_SCHEMA_VERSION ||
+      data.protocolVersion !== GAME_RUN_BRIDGE_PROTOCOL_VERSION ||
+      data.sessionId !== this.#sessionId ||
+      data.previewId !== this.#identity.previewId ||
+      data.projectId !== this.#identity.projectId ||
+      data.versionId !== this.#identity.versionId ||
+      data.projectRevision !== this.#identity.projectRevision ||
+      !isSafeIdentifier(data.requestId, 128) ||
+      this.#runtimeRequestIds.has(data.requestId) ||
+      !Number.isSafeInteger(data.sequence) ||
+      data.sequence !== this.#lastRuntimeSequence + 1 ||
+      typeof data.type !== 'string' ||
+      !RUNTIME_MESSAGE_TYPES.has(data.type) ||
+      !validatePayload(data.type, data.payload)
+    ) {
+      return null;
+    }
+    const responseTo = data.responseTo;
+    if (responseTo !== undefined) {
+      if (!isSafeIdentifier(responseTo, 128)) {
+        return null;
+      }
+      const hostType = this.#pendingRequests.get(responseTo);
+      if (!hostType || !responseTypeMatches(data.type, hostType)) {
+        return null;
+      }
+    } else if (data.type === 'runtime.ready' || !this.#ready) {
+      return null;
+    }
+    if (data.type === 'runtime.ready' && this.#ready) {
+      return null;
+    }
+
+    this.#lastRuntimeSequence = data.sequence;
+    this.#runtimeRequestIds.add(data.requestId);
+    if (responseTo !== undefined) {
+      this.#pendingRequests.delete(responseTo);
+    }
+    if (data.type === 'runtime.ready') {
+      this.#ready = true;
+    }
+    return data as unknown as GameRuntimeMessage;
+  }
+}
+
+export function gameRunSessionFromRuntimeMessage(
+  session: GameRunSession,
+  message: GameRuntimeMessage,
+  now: number,
+): GameRunSession {
+  if (message.type === 'runtime.error') {
+    return { ...session, status: 'failed', updatedAt: now };
+  }
+  if (message.type === 'runtime.ready') {
+    return { ...session, status: 'playing', updatedAt: now };
+  }
+  if (message.type !== 'runtime.state') {
+    return { ...session, updatedAt: now };
+  }
+  const status =
+    message.payload.status === 'completed'
+      ? 'paused'
+      : message.payload.status === 'starting'
+        ? 'starting'
+        : message.payload.status;
+  return { ...session, status, updatedAt: now };
+}
diff --git a/apps/ai-game-creator-shell/src/styles.css b/apps/ai-game-creator-shell/src/styles.css
index 3d311811c..0b256136f 100644
--- a/apps/ai-game-creator-shell/src/styles.css
+++ b/apps/ai-game-creator-shell/src/styles.css
@@ -4524,7 +4524,7 @@ iframe.preview-frame {
 
 .game-run-panels {
   display: grid;
-  grid-template-columns: minmax(0, 1fr);
+  grid-template-columns: repeat(2, minmax(0, 1fr));
   gap: 10px;
 }
 
@@ -4602,6 +4602,23 @@ iframe.preview-frame {
   font-size: 10px;
 }
 
+.game-run-panels button {
+  justify-self: start;
+  min-height: 28px;
+  padding: 0 12px;
+  border: 1px solid #dfb59f;
+  border-radius: 999px;
+  background: #fff8f4;
+  color: #855c4c;
+  font-size: 10px;
+  cursor: pointer;
+}
+
+.game-run-panels button:disabled {
+  cursor: default;
+  opacity: 0.5;
+}
+
 .game-workbench-chat {
   display: grid;
   grid-template-rows: auto minmax(0, 1fr);
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 f2ae126da..1aa047af5 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
@@ -29,12 +29,15 @@ import type {
   GameCreationAppAgentGroup,
   GameCreationAppManifest,
   GameCreationAppPreviewState,
+  GameRunSession,
+  GameRuntimeMessage,
   ProjectResourceCanvasLayoutMode,
   RunnableGameVersion,
 } from '../../../../../packages/shared/src/contracts/gameCreationApp';
 import { resolveTauriInvoke } from '../../app/tauri';
 import {
   LocalGamePreviewFrame,
+  type LocalGamePreviewFrameHandle,
   resolveEmbeddedPreviewUrl,
 } from '../../features/project-workspace/LocalGamePreviewFrame';
 import { resourceCanvasSectionExtent } from './resourceCanvasLayoutModel';
@@ -159,6 +162,10 @@ type RunnableGameVersionLaunchResult = {
     port: number;
     root: string;
   };
+  previewIdentity: {
+    previewId: string;
+    origin: string;
+  };
 };
 
 const categoryOrder: ResourceCategory[] = [
@@ -445,6 +452,14 @@ export default function ProjectDevelopmentView({
   );
   const [activeRunnablePreviewVersionId, setActiveRunnablePreviewVersionId] =
     useState<string | null>(null);
+  const [activePreviewIdentity, setActivePreviewIdentity] = useState<{
+    previewId: string;
+    origin: string;
+  } | null>(null);
+  const [gameRunSession, setGameRunSession] =
+    useState<GameRunSession | null>(null);
+  const [latestRuntimeMessage, setLatestRuntimeMessage] =
+    useState<GameRuntimeMessage | null>(null);
   const [imagePreview, setImagePreview] = useState<ImagePreviewState>({
     status: 'idle',
     resourceId: null,
@@ -459,6 +474,7 @@ export default function ProjectDevelopmentView({
   });
   const [mediaDuration, setMediaDuration] = useState<number | null>(null);
   const resourceCanvasRef = useRef<HTMLDivElement>(null);
+  const gamePreviewFrameRef = useRef<LocalGamePreviewFrameHandle>(null);
   const resourceFocusRef = useRef<HTMLElement>(null);
   const resourceListScrollRef = useRef({ left: 0, top: 0 });
   const restoreResourceListScrollRef = useRef(false);
@@ -478,6 +494,16 @@ export default function ProjectDevelopmentView({
     activeRunnablePreviewVersionId === currentRunnableVersionId
       ? resolveEmbeddedPreviewUrl(preview)
       : null;
+  const runBridgeIdentity =
+    embeddedPreviewUrl && currentRunnableVersion && activePreviewIdentity
+      ? {
+          projectId: manifest.projectId,
+          versionId: currentRunnableVersion.versionId,
+          projectRevision: currentRunnableVersion.projectRevision,
+          previewId: activePreviewIdentity.previewId,
+          previewOrigin: activePreviewIdentity.origin,
+        }
+      : null;
   const runAvailable = runnableVersions.length > 0 && currentRunnableVersion !== null;
   const projectedResources = useMemo(
     () => projectResourcesFromReadModels(manifest, attachments, agentResults),
@@ -772,6 +798,9 @@ export default function ProjectDevelopmentView({
 
   useEffect(() => {
     setActiveRunnablePreviewVersionId(null);
+    setActivePreviewIdentity(null);
+    setGameRunSession(null);
+    setLatestRuntimeMessage(null);
   }, [manifest.projectId]);
 
   useEffect(() => {
@@ -1001,6 +1030,9 @@ export default function ProjectDevelopmentView({
     setRunStatus('正在启动可运行版本');
     setSelectedRunnableVersionId(versionId);
     setActiveRunnablePreviewVersionId(null);
+    setActivePreviewIdentity(null);
+    setGameRunSession(null);
+    setLatestRuntimeMessage(null);
     onPreviewChange?.(null);
     try {
       const result = await invoke<RunnableGameVersionLaunchResult>(
@@ -1019,12 +1051,16 @@ export default function ProjectDevelopmentView({
       });
       setSelectedRunnableVersionId(result.version.versionId);
       setActiveRunnablePreviewVersionId(result.version.versionId);
-      setRunStatus(`正在运行版本 ${result.version.versionId}`);
+      setActivePreviewIdentity(result.previewIdentity ?? null);
+      setRunStatus(`正在建立版本 ${result.version.versionId} 的运行会话`);
       return true;
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
       setSelectedRunnableVersionId(manifest.currentRunnableVersionId ?? '');
       setActiveRunnablePreviewVersionId(null);
+      setActivePreviewIdentity(null);
+      setGameRunSession(null);
+      setLatestRuntimeMessage(null);
       setRunStatus(message);
       onPreviewChange?.({ status: 'failed' });
       return false;
@@ -1047,6 +1083,53 @@ export default function ProjectDevelopmentView({
     void launchRunnableVersion(currentRunnableVersion.versionId);
   }
 
+  function showResourcesView() {
+    gamePreviewFrameRef.current?.stop();
+    setMode('resources');
+  }
+
+  function handleGameRunSessionChange(session: GameRunSession) {
+    setGameRunSession(session);
+    if (session.status === 'starting') {
+      setLatestRuntimeMessage(null);
+    }
+    setRunStatus(
+      {
+        starting: '等待游戏运行时就绪',
+        playing: `正在运行版本 ${session.versionId}`,
+        paused: `版本 ${session.versionId} 已暂停`,
+        stopped: '运行会话已停止',
+        failed: '游戏运行会话失败',
+      }[session.status],
+    );
+  }
+
+  function handleGameRuntimeMessage(message: GameRuntimeMessage) {
+    setLatestRuntimeMessage(message);
+    if (message.type === 'runtime.error') {
+      setRunStatus(message.payload.message || '游戏运行时报告错误');
+    } else if (message.type === 'runtime.slice') {
+      setRunStatus(`测试切片：${message.payload.title} · ${message.payload.status}`);
+    } else if (message.type === 'runtime.inspection') {
+      setRunStatus(`已接收检查结果：${message.payload.label}`);
+    }
+  }
+
+  function toggleGameRunPause() {
+    if (gameRunSession?.status === 'paused') {
+      if (gamePreviewFrameRef.current?.resume()) {
+        setRunStatus('正在继续运行会话');
+      }
+      return;
+    }
+    if (
+      gameRunSession?.status === 'playing' &&
+      gamePreviewFrameRef.current?.pause()
+    ) {
+      setRunStatus('正在暂停运行会话');
+    }
+  }
+
   return (
     <section
       className="launcher-page launcher-project-development game-project-workbench"
@@ -1071,7 +1154,7 @@ export default function ProjectDevelopmentView({
                 role="tab"
                 aria-selected={mode === 'resources'}
                 className={mode === 'resources' ? 'is-active' : ''}
-                onClick={() => setMode('resources')}
+                onClick={showResourcesView}
               >
                 资源管理
               </button>
@@ -1519,8 +1602,13 @@ export default function ProjectDevelopmentView({
               <div className="game-run-preview">
                 {embeddedPreviewUrl ? (
                   <LocalGamePreviewFrame
+                    ref={gamePreviewFrameRef}
                     title={`${projectName} 游戏运行画面`}
                     preview={preview}
+                    runIdentity={runBridgeIdentity}
+                    onSessionChange={handleGameRunSessionChange}
+                    onRuntimeMessage={handleGameRuntimeMessage}
+                    onBridgeError={setRunStatus}
                   />
                 ) : (
                   <div className="game-run-preview-empty">
@@ -1557,6 +1645,40 @@ export default function ProjectDevelopmentView({
                     <p>当前无可运行版本</p>
                   )}
                 </section>
+                <section aria-label="运行会话信息">
+                  <header>
+                    <Gamepad2 size={16} aria-hidden="true" />
+                    运行会话
+                  </header>
+                  {gameRunSession ? (
+                    <dl>
+                      <div>
+                        <dt>状态</dt>
+                        <dd>{gameRunSession.status}</dd>
+                      </div>
+                      <div>
+                        <dt>协议</dt>
+                        <dd>{gameRunSession.protocolVersion}</dd>
+                      </div>
+                      <div>
+                        <dt>消息</dt>
+                        <dd>{latestRuntimeMessage?.type ?? '等待 ready'}</dd>
+                      </div>
+                    </dl>
+                  ) : (
+                    <p>等待 iframe 建立会话</p>
+                  )}
+                  <button
+                    type="button"
+                    disabled={
+                      gameRunSession?.status !== 'playing' &&
+                      gameRunSession?.status !== 'paused'
+                    }
+                    onClick={toggleGameRunPause}
+                  >
+                    {gameRunSession?.status === 'paused' ? '继续' : '暂停'}
+                  </button>
+                </section>
               </div>
               {runStatus ? (
                 <p className="game-run-status" role="status">
diff --git a/apps/ai-game-creator-shell/tests/appSurface/project-development.suite.ts b/apps/ai-game-creator-shell/tests/appSurface/project-development.suite.ts
index 090b14a70..c55707612 100644
--- a/apps/ai-game-creator-shell/tests/appSurface/project-development.suite.ts
+++ b/apps/ai-game-creator-shell/tests/appSurface/project-development.suite.ts
@@ -2109,6 +2109,155 @@ export function registerProjectWorkbenchFoundationTests() {
     });
   });
 
+  it('binds P3 runtime messages to the current iframe, origin, preview and reload session', async () => {
+    const manifest = createGameCreationAppManifest(
+      'workbench-run-bridge',
+      '运行桥测试',
+    );
+    const version = runnableVersionFixture(
+      manifest.projectId,
+      'runnable-r9',
+      9,
+    );
+    manifest.runnableVersions = [version];
+    manifest.currentRunnableVersionId = version.versionId;
+    const previewIdentity = {
+      previewId: 'preview-run-bridge-1',
+      origin: 'http://127.0.0.1:4199',
+    };
+    manifest.preview = {
+      status: 'running',
+      url: `${previewIdentity.origin}/`,
+      port: 4199,
+    };
+    const invoke = vi.fn(async () => ({
+      manifest,
+      version,
+      preview: {
+        url: `${previewIdentity.origin}/`,
+        port: 4199,
+        root: '/tmp/workbench-run-bridge',
+      },
+      previewIdentity,
+    }));
+    window.__TAURI__ = { core: { invoke } };
+
+    render(
+      React.createElement(ProjectDevelopmentView, {
+        projectName: manifest.name,
+        projectPath: '/tmp/workbench-run-bridge',
+        manifest,
+        attachments: [],
+        recentRunStatus: null,
+        recentRunStopReason: null,
+        supervisor: React.createElement('div', null, '项目总控'),
+        onHomeOpen: vi.fn(),
+        onProjectsOpen: vi.fn(),
+      }),
+    );
+    fireEvent.click(screen.getByRole('tab', { name: '运行' }));
+    const iframe = (await screen.findByTitle(
+      '运行桥测试 游戏运行画面',
+    )) as HTMLIFrameElement;
+    const frameWindow = iframe.contentWindow;
+    if (!frameWindow) {
+      throw new Error('missing iframe contentWindow');
+    }
+    const postMessage = vi.spyOn(frameWindow, 'postMessage');
+    fireEvent.load(iframe);
+    expect(postMessage).toHaveBeenCalledTimes(1);
+    const start = postMessage.mock.calls[0]?.[0] as Record<string, unknown>;
+    expect(start).toMatchObject({
+      protocolVersion: 'game-creator-run-bridge.v1',
+      projectId: manifest.projectId,
+      previewId: previewIdentity.previewId,
+      sequence: 1,
+      type: 'host.start',
+      versionId: version.versionId,
+      projectRevision: version.projectRevision,
+    });
+    expect(postMessage.mock.calls[0]?.[1]).toBe(previewIdentity.origin);
+
+    const ready = {
+      schemaVersion: 'game-creator-runtime-message.v1',
+      protocolVersion: 'game-creator-run-bridge.v1',
+      requestId: 'runtime-request-ready',
+      responseTo: start.requestId,
+      sessionId: start.sessionId,
+      previewId: start.previewId,
+      projectId: start.projectId,
+      sequence: 1,
+      type: 'runtime.ready',
+      versionId: start.versionId,
+      projectRevision: start.projectRevision,
+      payload: { capabilities: ['state', 'slice', 'inspection'] },
+    };
+    window.dispatchEvent(
+      new MessageEvent('message', {
+        data: ready,
+        origin: 'http://127.0.0.1:4200',
+        source: frameWindow,
+      }),
+    );
+    expect(screen.getByText('等待游戏运行时就绪')).not.toBeNull();
+    await act(async () => {
+      window.dispatchEvent(
+        new MessageEvent('message', {
+          data: ready,
+          origin: previewIdentity.origin,
+          source: frameWindow,
+        }),
+      );
+      await Promise.resolve();
+    });
+    expect(await screen.findByText('playing')).not.toBeNull();
+
+    fireEvent.click(screen.getByRole('button', { name: '暂停' }));
+    const pause = postMessage.mock.calls.at(-1)?.[0] as Record<string, unknown>;
+    expect(pause).toMatchObject({ sequence: 2, type: 'host.pause' });
+    await act(async () => {
+      window.dispatchEvent(
+        new MessageEvent('message', {
+          data: {
+            ...ready,
+            requestId: 'runtime-request-pause',
+            responseTo: pause.requestId,
+            sequence: 2,
+            type: 'runtime.state',
+            payload: { status: 'paused' },
+          },
+          origin: previewIdentity.origin,
+          source: frameWindow,
+        }),
+      );
+      await Promise.resolve();
+    });
+    expect(await screen.findByText('paused')).not.toBeNull();
+
+    fireEvent.load(iframe);
+    const reloadedStart = postMessage.mock.calls.at(-1)?.[0] as Record<
+      string,
+      unknown
+    >;
+    expect(reloadedStart).toMatchObject({ sequence: 1, type: 'host.start' });
+    expect(reloadedStart.sessionId).not.toBe(start.sessionId);
+    window.dispatchEvent(
+      new MessageEvent('message', {
+        data: {
+          ...ready,
+          requestId: 'runtime-request-old-session',
+          responseTo: undefined,
+          sequence: 3,
+          type: 'runtime.state',
+          payload: { status: 'playing' },
+        },
+        origin: previewIdentity.origin,
+        source: frameWindow,
+      }),
+    );
+    expect(screen.getByText('starting')).not.toBeNull();
+  });
+
   it('shows a precise runnable version launch failure without embedding a preview', async () => {
     const manifest = createGameCreationAppManifest(
       'workbench-version-failure',
diff --git a/apps/ai-game-creator-shell/tests/gameRunBridge.test.ts b/apps/ai-game-creator-shell/tests/gameRunBridge.test.ts
new file mode 100644
index 000000000..40bc09c1b
--- /dev/null
+++ b/apps/ai-game-creator-shell/tests/gameRunBridge.test.ts
@@ -0,0 +1,215 @@
+import { describe, expect, it } from 'vitest';
+
+import type { GameRuntimeMessage } from '../../../../packages/shared/src/contracts/gameCreationApp';
+import {
+  createGameHostMessage,
+  createGameRunSession,
+  type GameRunBridgeIdentity,
+  GameRunBridgeRuntimeGuard,
+  gameRunSessionFromRuntimeMessage,
+  validateGameRunBridgeIdentity,
+} from '../src/features/project-workspace/gameRunBridge';
+
+const identity: GameRunBridgeIdentity = {
+  projectId: 'project-1',
+  versionId: 'runnable-r7',
+  projectRevision: 7,
+  previewId: 'preview-1',
+  previewOrigin: 'http://127.0.0.1:4173',
+};
+
+function runtimeMessage(
+  overrides: Partial<GameRuntimeMessage> = {},
+): GameRuntimeMessage {
+  return {
+    schemaVersion: 'game-creator-runtime-message.v1',
+    protocolVersion: 'game-creator-run-bridge.v1',
+    requestId: 'runtime-request-1',
+    responseTo: 'host-request-1',
+    sessionId: 'session-1',
+    previewId: identity.previewId,
+    projectId: identity.projectId,
+    sequence: 1,
+    type: 'runtime.ready',
+    versionId: identity.versionId,
+    projectRevision: identity.projectRevision,
+    payload: { capabilities: ['state', 'slice', 'inspection'] },
+    ...overrides,
+  } as GameRuntimeMessage;
+}
+
+describe('P3 Game Run Bridge', () => {
+  it('creates a fully bound host request and accepts its exact ready response', () => {
+    expect(validateGameRunBridgeIdentity(identity)).toEqual(identity);
+    const host = createGameHostMessage({
+      identity,
+      sessionId: 'session-1',
+      requestId: 'host-request-1',
+      sequence: 1,
+      type: 'host.start',
+    });
+    expect(host).toMatchObject({
+      protocolVersion: 'game-creator-run-bridge.v1',
+      projectId: identity.projectId,
+      previewId: identity.previewId,
+      type: 'host.start',
+    });
+
+    const guard = new GameRunBridgeRuntimeGuard(identity, 'session-1');
+    expect(guard.registerHostRequest(host.requestId, host.type)).toBe(true);
+    expect(guard.accept(runtimeMessage())).toEqual(runtimeMessage());
+    expect(
+      guard.accept(
+        runtimeMessage({
+          requestId: 'runtime-request-2',
+          responseTo: undefined,
+          sequence: 2,
+          type: 'runtime.state',
+          payload: { status: 'playing' },
+        }),
+      ),
+    ).toMatchObject({ type: 'runtime.state' });
+  });
+
+  it('rejects stale identities, bad ordering and uncorrelated ready messages', () => {
+    const guard = new GameRunBridgeRuntimeGuard(identity, 'session-1');
+    guard.registerHostRequest('host-request-1', 'host.start');
+    expect(
+      guard.accept(runtimeMessage({ responseTo: 'unknown-request' })),
+    ).toBeNull();
+    expect(
+      guard.accept(runtimeMessage({ projectId: 'other-project' })),
+    ).toBeNull();
+    expect(guard.accept(runtimeMessage({ sequence: 2 }))).toBeNull();
+    expect(guard.accept(runtimeMessage())).not.toBeNull();
+    expect(
+      guard.accept(
+        runtimeMessage({
+          requestId: 'runtime-request-2',
+          responseTo: undefined,
+          sequence: 2,
+          previewId: 'old-preview',
+          type: 'runtime.state',
+          payload: { status: 'paused' },
+        }),
+      ),
+    ).toBeNull();
+  });
+
+  it('enforces message and payload whitelists without consuming a rejected sequence', () => {
+    const guard = new GameRunBridgeRuntimeGuard(identity, 'session-1');
+    guard.registerHostRequest('host-request-1', 'host.start');
+    expect(guard.accept(runtimeMessage())).not.toBeNull();
+
+    const rejectedPayloads = [
+      {
+        type: 'runtime.state',
+        payload: { status: 'playing', summary: '/tmp/secret' },
+      },
+      {
+        type: 'runtime.state',
+        payload: { status: 'playing', summary: 'https://untrusted.example' },
+      },
+      {
+        type: 'runtime.state',
+        payload: { status: 'playing', summary: '<script>run()</script>' },
+      },
+      {
+        type: 'runtime.inspection',
+        payload: {
+          inspectionId: 'inspection-1',
+          label: '运行画面',
+          metrics: { filePath: '/tmp/secret' },
+        },
+      },
+      {
+        type: 'runtime.inspection',
+        payload: {
+          inspectionId: 'inspection-1',
+          label: '运行画面',
+          metrics: { nested: { command: 'host.stop' } },
+        },
+      },
+    ] as const;
+    for (const [index, rejected] of rejectedPayloads.entries()) {
+      expect(
+        guard.accept(
+          runtimeMessage({
+            requestId: `runtime-request-rejected-${index}`,
+            responseTo: undefined,
+            sequence: 2,
+            ...rejected,
+          } as Partial<GameRuntimeMessage>),
+        ),
+      ).toBeNull();
+    }
+    expect(
+      guard.accept({
+        ...runtimeMessage({
+          requestId: 'runtime-request-extra-field',
+          responseTo: undefined,
+          sequence: 2,
+          type: 'runtime.state',
+          payload: { status: 'playing' },
+        }),
+        command: 'host.stop',
+      }),
+    ).toBeNull();
+    expect(
+      guard.accept(
+        runtimeMessage({
+          requestId: 'runtime-request-2',
+          responseTo: undefined,
+          sequence: 2,
+          type: 'runtime.inspection',
+          payload: {
+            inspectionId: 'inspection-1',
+            label: '运行画面',
+            metrics: { fps: 60, visible: true },
+          },
+        }),
+      ),
+    ).toMatchObject({ type: 'runtime.inspection' });
+
+    const oversized = runtimeMessage({
+      requestId: 'runtime-request-3',
+      responseTo: undefined,
+      sequence: 3,
+      type: 'runtime.state',
+      payload: { status: 'playing', summary: 'x'.repeat(70 * 1024) },
+    });
+    expect(guard.accept(oversized)).toBeNull();
+  });
+
+  it('projects only validated runtime states into the ephemeral session', () => {
+    const session = createGameRunSession(identity, 'session-1', 100);
+    expect(session.status).toBe('starting');
+    const ready = runtimeMessage();
+    const playing = gameRunSessionFromRuntimeMessage(session, ready, 101);
+    expect(playing).toMatchObject({ status: 'playing', updatedAt: 101 });
+    const failed = gameRunSessionFromRuntimeMessage(
+      playing,
+      runtimeMessage({
+        type: 'runtime.error',
+        payload: { code: 'game-error', message: '运行失败', recoverable: true },
+      }),
+      102,
+    );
+    expect(failed).toMatchObject({ status: 'failed', updatedAt: 102 });
+  });
+
+  it('accepts only exact 127.0.0.1 origins with explicit ports', () => {
+    expect(
+      validateGameRunBridgeIdentity({
+        ...identity,
+        previewOrigin: 'http://localhost:4173',
+      }),
+    ).toBeNull();
+    expect(
+      validateGameRunBridgeIdentity({
+        ...identity,
+        previewOrigin: 'http://127.0.0.1:4173/path',
+      }),
+    ).toBeNull();
+  });
+});
diff --git a/docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md b/docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md
index 1d3d3978f..54044c472 100644
--- a/docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md
+++ b/docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md
@@ -1,6 +1,6 @@
 # AI 游戏创作项目开发工作台 PRD
 
-更新时间：`2026-08-04`（可运行版本 P0/P1）
+更新时间：`2026-08-04`（可运行版本 P0/P1，运行桥 P3）
 
 ## 1. 产品定位
 
@@ -348,7 +348,7 @@ type GameCreationAppManifest = {
 - 运行入口只读取当前可运行版本。切换版本时先停止当前项目旧 preview、立即卸载 iframe，再复核并启动目标快照；启动成功后回写当前选择和 loopback preview。无版本、版本损坏、版本描述 revision 不一致、权限拒绝或预览启动失败分别显示明确原因。
 - 资源管理只从 `runnableVersions` 投影“可运行版本”卡。当前选择版本的全部现存绑定资产始终高亮；点击其它版本可只读查看其父子关系和历史绑定，不改变当前运行选择。
 
-### 5.5 测试切片与数值参数（P2）
+### 5.5 运行会话与 Host/Game Bridge（P3）
 
 ```ts
 type GameTestSlice = {
@@ -374,7 +374,11 @@ type GameTunableParameterDefinition = {
 };
 
 type GameRunSession = {
+  schemaVersion: 'game-creator-run-session.v1';
+  protocolVersion: 'game-creator-run-bridge.v1';
   sessionId: string;
+  previewId: string;
+  previewOrigin: `http://127.0.0.1:${number}`;
   projectId: string;
   versionId: string;
   projectRevision: number;
@@ -387,25 +391,51 @@ type GameRunSession = {
 
 type GameHostMessage = {
   schemaVersion: 'game-creator-host-message.v1';
+  protocolVersion: 'game-creator-run-bridge.v1';
+  requestId: string;
   sessionId: string;
+  previewId: string;
+  projectId: string;
   sequence: number;
-  type: 'host.start' | 'host.pause' | 'host.resume' | 'host.stop';
+  type:
+    | 'host.start'
+    | 'host.pause'
+    | 'host.resume'
+    | 'host.stop'
+    | 'host.state.request'
+    | 'host.inspection.request';
   versionId: string;
   projectRevision: number;
 };
 
 type GameRuntimeMessage = {
   schemaVersion: 'game-creator-runtime-message.v1';
+  protocolVersion: 'game-creator-run-bridge.v1';
+  requestId: string;
+  responseTo?: string;
   sessionId: string;
+  previewId: string;
+  projectId: string;
   sequence: number;
-  type: 'runtime.ready' | 'runtime.state' | 'runtime.completed' | 'runtime.failed';
+  type:
+    | 'runtime.ready'
+    | 'runtime.state'
+    | 'runtime.error'
+    | 'runtime.slice'
+    | 'runtime.inspection';
   versionId: string;
   projectRevision: number;
-  detail?: Record<string, unknown>;
+  payload: RuntimeReadyPayload | RuntimeStatePayload | RuntimeErrorPayload
+    | RuntimeSlicePayload | RuntimeInspectionPayload;
 };
 ```
 
-revision 不一致统一表示编辑工作树已经晚于当前 Session 绑定版本；Session 和切片标记 `stale`，但不热更新、不改写旧版本，也不把 stale 当失败。参数写入立即增加编辑态 revision；当前 preview/slice 保持旧 revision，并显示“需要重新拉起”。P1 尚不实现切片、参数和 Runtime message bridge。
+- P3 只在 P1 已启动的正式可运行版本 loopback preview 上建立会话，不接受普通工作树 preview、远程 URL 或其它项目的预览。`PreviewRegistry` 为每次服务启动生成新的 `previewId` 并返回精确 `http://127.0.0.1:<port>` origin；iframe 每次 load 生成新的 `sessionId`，旧 iframe、旧 preview、旧 session 与组件卸载后的消息全部失效。
+- 宿主发送 `host.start` 后，游戏必须用 `runtime.ready.responseTo` 关联该 request；其后 `runtime.state / runtime.error / runtime.slice / runtime.inspection` 可以作为受控主动上报，带 `responseTo` 时必须精确命中仍在等待且类型相容的 Host request。Host 与 Runtime 各自的 `sequence` 从 `1` 开始严格连续递增，重复、倒序或跳号消息丢弃。
+- 宿主只接受 `event.source === 当前 iframe.contentWindow` 且 `event.origin === PreviewRegistry 返回 origin` 的消息；随后逐项校验 protocol、schema、projectId、versionId、projectRevision、previewId 与 sessionId。iframe 重载、版本切换、preview 替换和会话停止时，先发送当前 session 的 `host.stop`，再清空请求表、序列与 Runtime 投影。
+- 单条消息结构化序列化后最多 `64 KiB`，顶层和 payload 都使用字段白名单。`runtime.ready` 只声明 `state / slice / inspection` 能力；`runtime.state` 只上报运行状态和短摘要；`runtime.error` 只上报受限错误码、文本和是否可恢复；`runtime.slice` 只上报切片身份、标题、状态和摘要；`runtime.inspection` 只上报受限 label/summary 与最多 32 个标量 metric。路径、URL、HTML、脚本、宿主命令、嵌套对象与未知字段一律拒绝，游戏消息不能触发 Tauri、文件、命令、Agent 或生成能力。
+- 预览服务在响应 HTML 时只注入宿主拥有的同源 `game-creator-run-bridge.v1` bootstrap，不修改不可变版本快照字节或摘要。bootstrap 为旧可运行版本提供 ready/state/pause/resume/stop 基线，并向游戏暴露仅能上报上述五类安全消息的 API；权限和安全结论始终由宿主校验，不信任游戏脚本自报。
+- revision 不一致继续表示编辑工作树已经晚于当前 Session 绑定版本；Session 标记 `stale`，但不热更新、不改写旧版本，也不把 stale 当失败。本次不实现 P2 资源替换与下一版本，也不实现测试切片编排、参数写入或数值面板；`runtime.slice` 只是 P3 传输层的安全上报能力。
 
 ### 5.6 Agent 泥点归因（P2）
 
@@ -438,13 +468,16 @@ type ProjectAgentMudPointAttribution = {
 - 当前版本绑定资源在 dependency / type 两种资源管理布局中高亮。
 - 无版本、损坏、revision 不一致和 preview 启动失败提供独立错误状态。
 
-### P2
+### P2（本次跳过）
 
-- 测试切片正式协议与恢复。
-- 参数注册表、立即写编辑态和预览重新拉起。
-- 泥点归因 read model。
-- Agent.md/Skill 安全合同。
-- 高风险审批 Rank 与无需审批运行合同。
+- 资源替换与下一不可变版本按独立方案后续实现；P3 不得提前写入 `resource-replacement` 版本。
+
+### P3
+
+- 在现有 `PreviewRegistry` 生命周期中增加 preview 身份和精确 loopback origin，不重建预览服务。
+- 工作台 iframe 建立一次性 `GameRunSession`，完成 Host/Game 双向桥、状态投影、request 关联和严格失效处理。
+- 接入 host-owned 同源 bootstrap，使当前正式可运行版本可以完成 ready/state 基线握手，并为游戏提供受限上报 API。
+- 覆盖来源窗口、origin、全身份、协议、消息类型、payload、容量、顺序、重载、切换和停止负向测试。
 
 ## 7. 验收
 
@@ -497,9 +530,18 @@ type ProjectAgentMudPointAttribution = {
 4. 根目录全量 Vitest、前后端 typecheck / lint / build、Rust workspace test / check、SpacetimeDB schema、原生壳、内容 / 编码、生产运维与部署门禁全部通过后，阶段七才允许提交。
 5. 本地 `.env`、`.env.local`、密钥、缓存、日志和构建产物不进入阶段七提交；提交前再次执行编码检查和 `git diff --check`。
 
+### 7.6 P3 运行会话与桥验收
+
+1. 启动正式可运行版本后，PreviewRegistry 返回新的 previewId 与精确 loopback origin；iframe load 创建新 session，Host 发出的第一条消息固定为 `host.start / sequence=1`。
+2. 只有当前 iframe contentWindow、精确 origin、完整身份匹配、schema/protocol 正确、sequence 连续且 request 关联合法的消息能推进会话；旧 iframe、旧端口、旧 preview/session 和其它项目消息均不改变 UI。
+3. ready/state/error/slice/inspection 五类消息按各自 payload 白名单通过；未知类型、超过 64 KiB、额外字段、嵌套数据、路径、URL、HTML、脚本或宿主命令内容被拒绝。
+4. iframe reload、切换版本、切回资源管理或组件卸载都会停止并失效旧 session；迟到消息不能复活旧状态，新 load 使用新 sessionId 和从 1 重新开始的双向 sequence。
+5. 预览响应注入的 bootstrap 不修改快照文件或摘要；旧版本至少完成 ready/playing 基线握手，pause/resume/stop 与 state/inspection request 均按 requestId 回应。
+6. 本阶段不出现资源替换、新版本写入、测试切片控件、数值微调面板或任何游戏触发的 Tauri/文件/命令能力。
+
 ## 8. 非目标
 
-- 当前收口不实现资源卡手动拖动，也不实现资源聚焦工具栏、资源聚焦工具侧边栏、美术编辑、音频编辑 / 替换、资源重新生成、资源替换、手动创建版本或版本回滚。P1 实现运行版本登记、选择、切换和运行态消费；测试切片、数值参数、Host/Runtime 消息桥与泥点归因仍属于 P2。
+- 当前收口不实现资源卡手动拖动，也不实现资源聚焦工具栏、资源聚焦工具侧边栏、美术编辑、音频编辑 / 替换、资源重新生成、资源替换、手动创建版本或版本回滚。P1 实现运行版本登记、选择、切换和运行态消费；P3 只实现运行会话与 Host/Game Bridge，测试切片编排、数值参数和泥点归因仍不在本次范围。
 - 本切片不持久化资源聚焦状态、画布缩放 / 平移、搜索条件、筛选条件或当前 mode；聚焦退出时的列表上下文恢复只限当前前端会话，这些状态如需跨重启保存必须另行扩展合同，不能塞入 `game-creator-resource-layout.v1`。
 - 不修改 SpacetimeDB schema。
 - 不开放普通用户 Agent.md/Skill。
diff --git a/docs/project-memory/shared-memory/decision-log.md b/docs/project-memory/shared-memory/decision-log.md
index e33a6f9af..1ad8fcd41 100644
--- a/docs/project-memory/shared-memory/decision-log.md
+++ b/docs/project-memory/shared-memory/decision-log.md
@@ -1,12 +1,22 @@
 # 决策记录
 
+## 2026-08-04 工作台 P3 在正式可运行预览上建立一次性 Host/Game Bridge
+
+- 背景：P0/P1 已用不可变快照和专用启动命令建立正式可运行版本，但运行 iframe 仍没有可验证的会话身份、消息顺序、请求关联和 reload 后失效语义；飞书需求同时明确本次跳过 P2 资源替换，只实现 P3 底层运行桥。
+- 决策：协议固定为 `game-creator-run-bridge.v1`。每次正式可运行 preview 启动由 `PreviewRegistry` 生成新的 `previewId` 和精确 `http://127.0.0.1:<port>` origin，每次 iframe load 用 Web Crypto 生成新的 `sessionId`；Host/Runtime 消息完整绑定 project/version/revision/preview/session，双向 sequence 从 1 严格连续，ready 必须关联 start，其它响应只能命中仍在等待且类型相容的 request。
+- 安全边界：Host 只接受当前 iframe `contentWindow` 和 Registry origin 的消息，再执行 64 KiB、精确字段、类型白名单与各 payload 白名单校验；文本、inspection 标量及数量均有界，并拒绝路径、URL、HTML、脚本、宿主命令和嵌套数据。合法消息只投影前端临时会话状态，不得触发 Tauri、文件、命令、Agent 或生成能力。iframe reload、版本/preview 切换、停止、返回资源管理和卸载都会先 best-effort stop，再失效旧会话。
+- 兼容策略：loopback preview 在 HTML 响应中注入宿主拥有的同源 bootstrap，不修改不可变快照文件或摘要；旧游戏至少具备 ready/state/pause/resume/stop 和 state/inspection request 基线。游戏暴露 API 只能上报 ready/state/error/slice/inspection 合同内数据，最终信任判断仍只在 Host 守卫完成。
+- 范围：本次不实现 P2 资源替换或下一版本，不实现测试切片编排、数值参数写入、微调面板或泥点归因；`runtime.slice` 仅是 P3 安全传输类型。
+- 验证方式：前端纯协议测试覆盖身份、顺序、关联、白名单、危险字段和大小限制；AppSurface 覆盖 iframe/source/origin、暂停响应、reload 新 session 与旧消息拒绝；Rust 覆盖 Registry 身份轮换、bootstrap 注入和快照字节不变，并运行 shell typecheck、编码检查与 `git diff --check`。
+- 关联文档：`docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md`、`docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md`。
+
 ## 2026-08-04 工作台 P0/P1 以不可变快照建立唯一可运行版本事实源
 
 - 背景：2026-08-03 资源管理阶段新增的 `manifest.versions` 只用于只读项目迭代卡，当时明确不承担运行版本切换；本轮飞书需求正式进入运行工作台 P0/P1，不能再以 `code-prototype=completed`、普通 preview、checkpoint 或前端状态推断游戏已经可运行。
 - 决策：保留 `manifest.versions` 作为通用迭代历史，新增由可信 Rust / Runtime 独占追加的 `runnableVersions` 与唯一可变选择指针 `currentRunnableVersionId`。每条记录必须绑定 project/revision、父版本、三项通过凭证、固定 entry、资源槽位和不可变 SHA-256；首版为 `initial`，后续为 `agent-revision`，已有记录在 manifest 存储边界禁止修改、删除或重排。
 - 产物边界：Runtime 只有在当前 revision 的 `preview-playtest` 传递前置任务闭包、`game.static_smoke`、`preview.validate` 与真实试玩证据全部通过后才自动登记；试玩后的发布节点不阻断登记。`game/` 与可选 `assets/` 被有界复制到 `.agent/runnable-versions/<versionId>/artifact`，版本描述与文件摘要在每次启动前复核。旧版本始终运行该快照，不运行当前工作树；快照已安装但 manifest 写入中断时，重试复用原描述时间与摘要，身份或内容冲突则失败关闭。
 - 工作台消费：运行入口只读取 `runnableVersions/currentRunnableVersionId`。切换时先停止旧 preview 并卸载 iframe，复核并启动目标快照，成功后才更新选择指针和 loopback preview；无版本、项目身份不符、快照损坏、revision 不一致和启动失败必须原样展示明确错误。资源管理只投影正式可运行版本，并持续高亮当前版本仍存在的绑定资产。
-- P0/P2 边界：同时冻结测试切片、运行会话、数值参数、资源描述及 Host/Runtime 消息的 TypeScript/Rust 合同；数值参数的 `codeMutationAllowed` 固定为 `false`，消息类型固定为 `host.* / runtime.*`。本轮不实现测试切片、数值微调、消息桥、泥点归因或资源替换，这些仍属于 P2。
+- 当时的实现边界：同时冻结测试切片、运行会话、数值参数、资源描述及 Host/Runtime 消息的 TypeScript/Rust 合同；数值参数的 `codeMutationAllowed` 固定为 `false`，消息类型固定为 `host.* / runtime.*`。该 P0/P1 变更当时不实现测试切片、数值微调、消息桥、泥点归因或资源替换；其中消息桥随后按本文件 P3 决策实现，资源替换仍属于 P2。
 - 关联文档：`docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md`、`docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md`。
 
 ## 2026-08-03 资源管理阶段七以完整 CI 与可重复界面合同收口
diff --git a/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md b/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md
index 7cc677d05..9a54a6a88 100644
--- a/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md
+++ b/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md
@@ -358,13 +358,13 @@ game-project/
 
 2026-07-18 起，项目开发页按《陶泥儿GameAgent-V1.0 项目开发界面需求》先落一版可交互工作台。该切片替代“正式用户项目页只有聊天与只读 Agent 列表”的旧视觉口径，但不改变 Runtime、manifest、预览和计费事实源。
 
-2026-07-20 起，产品状态机、P0/P1/P2 范围与后续数据合同以 [`【AI游戏创作】项目开发工作台PRD-2026-07-20.md`](../prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md) 为准；本节只保留当前实现边界。
+2026-07-20 起，产品状态机、P0/P1/P2/P3 范围与后续数据合同以 [`【AI游戏创作】项目开发工作台PRD-2026-07-20.md`](../prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md) 为准；本节只保留当前实现边界。
 
 - 页面骨架固定为左侧现有全局导航、中间主视窗、右侧陶泥儿对话和底部子 Agent 状态栏；不新建第二套客户端或平行项目页。
 - 中间主视窗提供 `资源管理 / 运行` 切换。2026-08-04 起运行入口不再读取 `code-prototype` 任务状态，只读取 manifest 的正式 `runnableVersions + currentRunnableVersionId`；无版本时保持视觉不可用但仍可点击查看“当前无可运行版本”，不能使用会阻断说明交互的原生 `disabled` 或 `aria-disabled`。切回资源管理只修改前端展示态，不伪造后端预览暂停结果。
 - 资源管理从当前 `GameCreationAppManifest`（包含可选 `versions`）、合法 Agent 文本回执和已导入附件派生资源，固定按文档、项目版本、美术资源、音乐音效资源分区；未知任务产物不再兜底为版本，任务声明中的未登记音频也不冒充正式音频。`按依赖 / 按类型` 使用各自前端排列，dependency 模式额外绘制当前 manifest 与资源投影可证明的依赖关系。排列与图层都不写回 manifest，不能推断或伪造缺失依赖。
 - 资源卡支持点击聚焦、搜索和类型筛选。2026-07-28 起完成两套二维坐标与本地 CAS sidecar；2026-07-31 起 dependency 模式增加不持久化的原生 SVG 关系图层。2026-08-03 mentor 决定暂缓资源卡拖动，当前卡片不挂载 Pointer Down / Move / Up / Cancel 拖动入口，只允许自动布局和点击聚焦。聚焦态替换中央主视窗内容，保留左侧导航、右侧对话和底部 Agent 状态栏，退出后恢复搜索、布局模式、滚动位置与选中资源；不提供工具栏、工具侧边栏或可拖动标题栏。阶段四已补齐安全本地文档、扩展美术媒体与音频聚焦，正文独立滚动，视频 / 音频使用内置媒体控件，失败显示空态；美术编辑、音频编辑 / 替换、版本替换或运行模块仍不在本阶段。
-- 运行表现层嵌入当前项目的 loopback 游戏画面。P1 由专用可运行版本命令停止旧 preview、卸载 iframe、复核版本快照并启动目标版本；普通 `preview.start` 继续服务 Agent 当前工作树验证，不能作为工作台运行授权或旧版本切换入口。测试切片、参数调整和 Host/Runtime message bridge 已冻结为正式 P2 合同，不再称为本地 UI 草稿，本轮不接线。
+- 运行表现层嵌入当前项目的 loopback 游戏画面。P1 由专用可运行版本命令停止旧 preview、卸载 iframe、复核版本快照并启动目标版本；普通 `preview.start` 继续服务 Agent 当前工作树验证，不能作为工作台运行授权或旧版本切换入口。2026-08-04 起 P3 在该生命周期上接入运行会话与 Host/Game Bridge；P2 资源替换与下一版本继续跳过，测试切片编排和参数调整也不在 P3 内接线。
 - 右侧继续复用现有 Project Supervisor 会话、Runtime 澄清和确认链路；输入区展示 `严格审批 / 风险审批 / 无需审批` 独立面板。P0 只有严格审批可选；风险审批和无需审批保持视觉不可用但允许点击查看原因，不替代 Runtime 的逐动作权限、确认、sandbox 或 reconciliation 门禁。风险 Rank 算法记录在 `docs/project-memory/todos/【待解决】AI游戏创作高风险审批Rank-2026-07-20.md`，前端不得自行计算。
 - 底部状态栏默认展示策划、美术、程序 3 组，并允许在同一栏展开数值、音频、发布组；状态来自 manifest 与当前 Supervisor run 的 Runtime，悬停显示当前任务与进度。累计泥点必须等待后端计费归因投影；Agent.md 编辑和自定义 Skill 在来源审核、版本、权限、sandbox 与回滚合同完备前不向普通用户开放。
 - 当前 run 专业状态与项目历史成果分离：状态继续严格匹配当前 `parentRunId`；已有文本成果从专业 Agent 持久对话中合法的 `agent-finalization-<32 lower hex>` assistant 恢复，并以“历史成果”来源投影到资源管理文档区。新 run 失败、待确认、候选为空或持久对话瞬时读取失败不得清除已恢复的旧成功回执，普通失败 assistant 也不得被当作成果。
@@ -424,6 +424,16 @@ game-project/
 - `currentRunnableVersionId` 是唯一可变选择指针。专用 Tauri 命令在项目锁内复核项目身份、版本结构、快照描述、revision 与摘要；切换时先停止当前项目 registry server，再启动目标快照。启动失败不得回退当前工作树或继续展示旧 iframe。
 - 普通 Agent `preview.start / preview.validate` 仍对当前编辑工作树执行，Runner registry 与 Tauri 用户可见 registry 的既有隔离不变；工作台运行专用命令只能服务已登记快照。
 
+### 运行会话与 Host/Game Bridge P3
+
+- `PreviewRegistry` 继续是唯一进程内预览所有者，只在当前 `PreviewServer` 上增加 UUID `previewId` 与由监听端口确定的精确 `http://127.0.0.1:<port>` origin。专用可运行版本启动结果返回该身份；普通 preview API 不获得工作台运行授权。
+- 前端 `LocalGamePreviewFrame` 只在同时拿到 P1 版本身份和 Registry preview 身份时启用桥。每次 iframe load 使用 Web Crypto 生成新的 128-bit sessionId，建立独立 Host/Runtime sequence、pending request 和已消费 runtime request 集合；reload、unmount、版本/preview key 变化先 best-effort 发送 `host.stop`，再原子失效旧会话。
+- wire protocol 固定为 `game-creator-run-bridge.v1`，Host/Runtime 分别使用 `game-creator-host-message.v1` 与 `game-creator-runtime-message.v1`。所有消息携带 request/session/preview/project/version/revision 身份；Host 类型只开放 start/pause/resume/stop/state.request/inspection.request，Runtime 类型只开放 ready/state/error/slice/inspection。
+- `message` listener 先检查当前 iframe `contentWindow` 与 Registry origin，再执行 64 KiB、plain object、精确字段、JavaScript 安全正整数、连续 sequence、request/response 类型相容和 payload 专用校验。inspection metrics 只允许最多 32 个标量；全部文本有界并拒绝路径、URL、HTML/脚本和宿主命令痕迹。通过的消息只更新 React 运行会话投影，不调用 Tauri invoke，也不进入 Agent/文件/命令/生成链路。
+- loopback server 对 HTML 响应注入固定同源外部 bootstrap 标签，并在保留原文件不变的前提下提供 `/.genarrative/game-bridge.v1.js`。bootstrap 只接受 parent 发来的合法 Host envelope，锁定首个 start 的 origin 与完整身份，基线响应 ready/state 并处理 pause/resume/stop/state/inspection；同时暴露受限 reportState/reportError/reportSlice/reportInspection API，业务游戏不能指定宿主命令、文件路径或 envelope 身份。
+- 工作台显示真实 session 状态并提供 pause/resume；ready 之前保持 starting，error 进入 failed，runtime state 只按白名单状态推进。`runtime.slice` 与 `runtime.inspection` 作为安全传输与展示投影存在，不等于已实现 P2 测试切片流程、检查工具或数值编辑。
+- 定向门禁覆盖 Rust Registry 身份轮换和 HTML/bootstrap 响应；TypeScript 纯协议覆盖白名单、容量、身份、sequence、request 关联与危险 payload；AppSurface 覆盖真实 iframe source/origin、reload/session 失效、版本切换卸载和 UI 状态。最后运行 shared-contracts、Tauri project/preview、AGC typecheck、定向 Vitest、编码检查与 `git diff --check`。
+
 历史命令式 drag preview 句柄与局部连接索引可以保留，但项目工作台不再向资源卡传入该入口。拖动热路径、4096 张真实卡片拖动重渲染和 Chromium p95 门槛统一暂缓；当前回归只要求 Pointer Move 不改变卡片坐标、SVG path 或布局 revision。`ResizeObserver` 仍保持单图层单实例，任何实时 DOM 几何都不得通过 Tauri IPC 往返 Rust。
 
 ## 分阶段实施
diff --git a/packages/shared/src/contracts/gameCreationApp.ts b/packages/shared/src/contracts/gameCreationApp.ts
index 8847be972..0c405865c 100644
--- a/packages/shared/src/contracts/gameCreationApp.ts
+++ b/packages/shared/src/contracts/gameCreationApp.ts
@@ -604,7 +604,11 @@ export interface GameTestSlice {
 }
 
 export interface GameRunSession {
+  schemaVersion: 'game-creator-run-session.v1';
+  protocolVersion: 'game-creator-run-bridge.v1';
   sessionId: string;
+  previewId: string;
+  previewOrigin: string;
   projectId: string;
   versionId: string;
   projectRevision: number;
@@ -637,25 +641,90 @@ export interface GameResourceDescriptor {
   format: string;
 }
 
+export const GAME_RUN_BRIDGE_PROTOCOL_VERSION =
+  'game-creator-run-bridge.v1' as const;
+export const GAME_HOST_MESSAGE_SCHEMA_VERSION =
+  'game-creator-host-message.v1' as const;
+export const GAME_RUNTIME_MESSAGE_SCHEMA_VERSION =
+  'game-creator-runtime-message.v1' as const;
+export const GAME_RUN_BRIDGE_MAX_MESSAGE_BYTES = 64 * 1024;
+
+export type GameHostMessageType =
+  | 'host.start'
+  | 'host.pause'
+  | 'host.resume'
+  | 'host.stop'
+  | 'host.state.request'
+  | 'host.inspection.request';
+
 export interface GameHostMessage {
   schemaVersion: 'game-creator-host-message.v1';
+  protocolVersion: 'game-creator-run-bridge.v1';
+  requestId: string;
   sessionId: string;
+  previewId: string;
+  projectId: string;
   sequence: number;
-  type: 'host.start' | 'host.pause' | 'host.resume' | 'host.stop';
+  type: GameHostMessageType;
   versionId: string;
   projectRevision: number;
 }
 
-export interface GameRuntimeMessage {
+export type GameRuntimeCapability = 'state' | 'slice' | 'inspection';
+
+export interface GameRuntimeReadyPayload {
+  capabilities: GameRuntimeCapability[];
+}
+
+export interface GameRuntimeStatePayload {
+  status: 'starting' | 'playing' | 'paused' | 'completed' | 'stopped';
+  summary?: string;
+}
+
+export interface GameRuntimeErrorPayload {
+  code: string;
+  message: string;
+  recoverable: boolean;
+}
+
+export interface GameRuntimeSlicePayload {
+  sliceId: string;
+  title: string;
+  status: GameTestSliceStatus;
+  summary?: string;
+}
+
+export type GameRuntimeInspectionMetric = string | number | boolean | null;
+
+export interface GameRuntimeInspectionPayload {
+  inspectionId: string;
+  label: string;
+  summary?: string;
+  metrics: Record<string, GameRuntimeInspectionMetric>;
+}
+
+interface GameRuntimeMessageBase {
   schemaVersion: 'game-creator-runtime-message.v1';
+  protocolVersion: 'game-creator-run-bridge.v1';
+  requestId: string;
+  responseTo?: string;
   sessionId: string;
+  previewId: string;
+  projectId: string;
   sequence: number;
-  type: 'runtime.ready' | 'runtime.state' | 'runtime.completed' | 'runtime.failed';
   versionId: string;
   projectRevision: number;
-  detail?: Record<string, unknown>;
 }
 
+export type GameRuntimeMessage = GameRuntimeMessageBase &
+  (
+    | { type: 'runtime.ready'; payload: GameRuntimeReadyPayload }
+    | { type: 'runtime.state'; payload: GameRuntimeStatePayload }
+    | { type: 'runtime.error'; payload: GameRuntimeErrorPayload }
+    | { type: 'runtime.slice'; payload: GameRuntimeSlicePayload }
+    | { type: 'runtime.inspection'; payload: GameRuntimeInspectionPayload }
+  );
+
 export interface GameCreationAppManifest {
   schemaVersion: string;
   projectId: string;
diff --git a/server-rs/crates/shared-contracts/src/game_creation_app.rs b/server-rs/crates/shared-contracts/src/game_creation_app.rs
index f1b75e388..c7bfb95a2 100644
--- a/server-rs/crates/shared-contracts/src/game_creation_app.rs
+++ b/server-rs/crates/shared-contracts/src/game_creation_app.rs
@@ -721,7 +721,11 @@ pub enum GameRunSessionStaleReason {
 #[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
 #[serde(rename_all = "camelCase")]
 pub struct GameRunSession {
+    pub schema_version: String,
+    pub protocol_version: String,
     pub session_id: String,
+    pub preview_id: String,
+    pub preview_origin: String,
     pub project_id: String,
     pub version_id: String,
     pub project_revision: u64,
@@ -820,13 +824,21 @@ pub enum GameHostMessageType {
     HostResume,
     #[serde(rename = "host.stop")]
     HostStop,
+    #[serde(rename = "host.state.request")]
+    HostStateRequest,
+    #[serde(rename = "host.inspection.request")]
+    HostInspectionRequest,
 }
 
 #[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
 #[serde(rename_all = "camelCase")]
 pub struct GameHostMessage {
     pub schema_version: String,
+    pub protocol_version: String,
+    pub request_id: String,
     pub session_id: String,
+    pub preview_id: String,
+    pub project_id: String,
     pub sequence: u64,
     #[serde(rename = "type")]
     pub message_type: GameHostMessageType,
@@ -840,24 +852,31 @@ pub enum GameRuntimeMessageType {
     RuntimeReady,
     #[serde(rename = "runtime.state")]
     RuntimeState,
-    #[serde(rename = "runtime.completed")]
-    RuntimeCompleted,
-    #[serde(rename = "runtime.failed")]
-    RuntimeFailed,
+    #[serde(rename = "runtime.error")]
+    RuntimeError,
+    #[serde(rename = "runtime.slice")]
+    RuntimeSlice,
+    #[serde(rename = "runtime.inspection")]
+    RuntimeInspection,
 }
 
 #[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
 #[serde(rename_all = "camelCase")]
 pub struct GameRuntimeMessage {
     pub schema_version: String,
+    pub protocol_version: String,
+    pub request_id: String,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub response_to: Option<String>,
     pub session_id: String,
+    pub preview_id: String,
+    pub project_id: String,
     pub sequence: u64,
     #[serde(rename = "type")]
     pub message_type: GameRuntimeMessageType,
     pub version_id: String,
     pub project_revision: u64,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub detail: Option<serde_json::Value>,
+    pub payload: serde_json::Value,
 }
 
 fn validate_iteration_version_id(value: &str, label: &str, max_chars: usize) -> Result<(), String> {
@@ -2392,10 +2411,14 @@ mod tests {
     }
 
     #[test]
-    fn workbench_p2_message_types_keep_the_frozen_wire_values() {
+    fn workbench_p3_message_types_keep_the_frozen_wire_values() {
         let host = GameHostMessage {
             schema_version: "game-creator-host-message.v1".to_string(),
+            protocol_version: "game-creator-run-bridge.v1".to_string(),
+            request_id: "host-request-1".to_string(),
             session_id: "session-1".to_string(),
+            preview_id: "preview-1".to_string(),
+            project_id: "project-1".to_string(),
             sequence: 1,
             message_type: GameHostMessageType::HostStart,
             version_id: "runnable-r7".to_string(),
@@ -2405,7 +2428,11 @@ mod tests {
             serde_json::to_value(host).expect("serialize host message"),
             json!({
                 "schemaVersion": "game-creator-host-message.v1",
+                "protocolVersion": "game-creator-run-bridge.v1",
+                "requestId": "host-request-1",
                 "sessionId": "session-1",
+                "previewId": "preview-1",
+                "projectId": "project-1",
                 "sequence": 1,
                 "type": "host.start",
                 "versionId": "runnable-r7",
@@ -2415,16 +2442,22 @@ mod tests {
 
         let runtime = GameRuntimeMessage {
             schema_version: "game-creator-runtime-message.v1".to_string(),
+            protocol_version: "game-creator-run-bridge.v1".to_string(),
+            request_id: "runtime-request-1".to_string(),
+            response_to: Some("host-request-1".to_string()),
             session_id: "session-1".to_string(),
+            preview_id: "preview-1".to_string(),
+            project_id: "project-1".to_string(),
             sequence: 2,
             message_type: GameRuntimeMessageType::RuntimeReady,
             version_id: "runnable-r7".to_string(),
             project_revision: 7,
-            detail: None,
+            payload: json!({ "capabilities": ["state", "slice", "inspection"] }),
         };
         let value = serde_json::to_value(runtime).expect("serialize runtime message");
         assert_eq!(value["type"], "runtime.ready");
-        assert!(value.get("detail").is_none());
+        assert_eq!(value["responseTo"], "host-request-1");
+        assert_eq!(value["payload"]["capabilities"][0], "state");
     }
 
     #[test]
-- 
2.52.0


From 752505547d1b7ac61af300d15b2363fe850b0384 Mon Sep 17 00:00:00 2001
From: menghao <mh18530625731@163.com>
Date: Tue, 4 Aug 2026 17:06:24 +0800
Subject: [PATCH 21/27] =?UTF-8?q?=E5=AE=9E=E7=8E=B0=E8=BF=90=E8=A1=8C?=
 =?UTF-8?q?=E5=B7=A5=E4=BD=9C=E5=8F=B0=E6=AD=A3=E5=BC=8F=E6=B5=8B=E8=AF=95?=
 =?UTF-8?q?=E5=88=87=E7=89=87=E4=B8=8E=E6=82=AC=E5=81=9C=E4=BF=A1=E6=81=AF?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

新增正式测试切片合同、状态机与上一项/播放暂停/下一项控制
新增可信悬停资源解析与资源管理画布定位
扩展 Tauri 版本登记、运行 Bridge 和 Agent 生成合同
补齐 TypeScript、Rust 与 AppSurface 回归测试
同步工作台 PRD、技术方案与共享决策记录
保持 P2 资源替换、参数写入和下一版本能力未接线
---
 .../src/agent/runtime_driver/task_start.rs    |   1 +
 .../runtime_protocol/autonomous_completion.rs |   6 +-
 .../autonomous_completion_contract_tests.rs   |  26 ++
 .../src-tauri/src/main.rs                     |   3 +-
 .../src-tauri/src/preview.rs                  |  33 +-
 .../src/project/runnable_versions.rs          | 236 +++++++++++-
 .../src-tauri/src/tests/project.rs            |   7 +-
 .../LocalGamePreviewFrame.tsx                 |  10 +-
 .../project-workspace/gameRunBridge.ts        |  48 ++-
 .../project-workspace/gameTestSliceModel.ts   | 158 ++++++++
 apps/ai-game-creator-shell/src/styles.css     |   9 +-
 .../src/view/project-development/index.tsx    | 289 +++++++++++++-
 .../appSurface/project-development.suite.ts   | 354 ++++++++++++++++--
 .../tests/gameRunBridge.test.ts               |  22 ++
 .../tests/gameTestSliceModel.test.ts          | 226 +++++++++++
 ...AI游戏创作】项目开发工作台PRD-2026-07-20.md |  39 +-
 .../shared-memory/decision-log.md             |   9 +
 ...�案】AI游戏创作智能体App实施计划-2026-06-24.md |   8 +
 .../shared/src/contracts/gameCreationApp.ts   |  14 +-
 .../shared-contracts/src/game_creation_app.rs | 149 ++++++++
 20 files changed, 1581 insertions(+), 66 deletions(-)
 create mode 100644 apps/ai-game-creator-shell/src/features/project-workspace/gameTestSliceModel.ts
 create mode 100644 apps/ai-game-creator-shell/tests/gameTestSliceModel.test.ts

diff --git a/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_driver/task_start.rs b/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_driver/task_start.rs
index fddd0fbac..de06e0c84 100644
--- a/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_driver/task_start.rs
+++ b/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_driver/task_start.rs
@@ -1329,6 +1329,7 @@ pub(in crate::agent) fn project_autonomous_manifest_ready_task_terminal_at_locke
             &receipt.agent_id,
             &receipt.run_id,
             &receipt.report.path,
+            receipt.playtest_scenario,
         )?;
     }
     update_manifest_task_status_at(root, &state.agent_id, status.clone())?;
diff --git a/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_protocol/autonomous_completion.rs b/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_protocol/autonomous_completion.rs
index 1afbb5d25..38d5906ce 100644
--- a/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_protocol/autonomous_completion.rs
+++ b/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_protocol/autonomous_completion.rs
@@ -1690,7 +1690,8 @@ pub(in crate::agent) fn autonomous_playtest_contract_prompt(
             concat!(
                 "完成合同要求 generic-v1 交互试玩。game/index.html 必须持续更新 <script id=\"playable-web-game-state\" type=\"application/json\">，JSON 固定包含 schemaVersion=playable-web-game-state.v1、单调递增 sequence、phase=ready|playing|won|lost、正整数 level；",
                 "界面必须提供 data-playtest-id=\"start\"、data-playtest-id=\"primary-action\" 与 data-playtest-id=\"restart\" 的真实可点击控件；primary-action 必须映射游戏的真实主要玩法操作，并在动作发生时推进 state sequence，不能使用空操作或仅更新装饰 UI 的按钮；每个固定 data-playtest-id 在对应受控试玩步骤都必须恰好匹配一个可见且启用（disabled=false）的真实可点击 HTMLElement，同一固定值不得出现在多个控件上。",
-                "初始状态必须是 ready 且 level 为正整数；start 后状态必须推进并进入 playing，并先至少持续 2 秒保持 playing，让玩家获得可操作机会，在 primary-action 之前进入 ready、won 或 lost 都会失败；随后 primary-action 必须再次严格推进 sequence，primary-action 后 phase 可为 playing、won 或 lost，单次 won 或 lost 都是正常游戏终态，不会仅凭一次 lost 判定试玩失败；若动作后仍为 playing，则最多继续观察 3 秒，期间 won/lost 可提前形成首轮结果，始终 playing 也可在观察完成后证明非失败推进。restart 后必须再次推进，且至少持续 3 秒的稳定观察窗口内只能保持 ready 或 playing，进入 won 或 lost 都会失败；如果首轮 primary-action 结果为 lost，重开稳定后必须自动执行第二次受控尝试，恢复为 ready 时先 start 推进到 playing，随后无论重开结果原本是 ready 还是 playing，都必须再次完成至少 2 秒的 playing 操作机会，再次点击 primary-action 且严格推进 sequence；第二次必须进入 won，或保持 playing 并完成 3 秒观察，观察期间可进入 won 但不得进入 lost。两次受控尝试都进入 lost 说明游戏存在无法正常推进的固定失败，必须判定试玩失败；全部观察期间 sequence 始终不得回退。"
+                "初始状态必须是 ready 且 level 为正整数；start 后状态必须推进并进入 playing，并先至少持续 2 秒保持 playing，让玩家获得可操作机会，在 primary-action 之前进入 ready、won 或 lost 都会失败；随后 primary-action 必须再次严格推进 sequence，primary-action 后 phase 可为 playing、won 或 lost，单次 won 或 lost 都是正常游戏终态，不会仅凭一次 lost 判定试玩失败；若动作后仍为 playing，则最多继续观察 3 秒，期间 won/lost 可提前形成首轮结果，始终 playing 也可在观察完成后证明非失败推进。restart 后必须再次推进，且至少持续 3 秒的稳定观察窗口内只能保持 ready 或 playing，进入 won 或 lost 都会失败；如果首轮 primary-action 结果为 lost，重开稳定后必须自动执行第二次受控尝试，恢复为 ready 时先 start 推进到 playing，随后无论重开结果原本是 ready 还是 playing，都必须再次完成至少 2 秒的 playing 操作机会，再次点击 primary-action 且严格推进 sequence；第二次必须进入 won，或保持 playing 并完成 3 秒观察，观察期间可进入 won 但不得进入 lost。两次受控尝试都进入 lost 说明游戏存在无法正常推进的固定失败，必须判定试玩失败；全部观察期间 sequence 始终不得回退。",
+                "还必须监听 genarrative:host-message 中的 host.slice.start / host.slice.stop；generic-v1 的正式 sliceId 固定为 core-gameplay，必须通过 window.genarrativeGameBridge.reportSlice 上报该 ID 的 playing、paused、completed 或 failed。游戏自身 hit-test / hover 只允许通过 reportTargetInspection 上报当前 .agent/manifest.json 已登记的 asset.id，或与该 asset.id 对应的资源槽位 slotId；离开对象调用 clearInspection，不得上报资源名称、路径、HTML 或宿主命令。"
             )
         }
         BrowserPlaytestScenario::LaneDefenseV1 => {
@@ -1698,7 +1699,8 @@ pub(in crate::agent) fn autonomous_playtest_contract_prompt(
                 "完成合同要求 lane-defense-v1 交互试玩。game/index.html 必须持续更新 <script id=\"playable-web-game-state\" type=\"application/json\">，JSON 固定包含 schemaVersion=playable-web-game-state.v1、单调递增 sequence、phase=ready|playing|won|lost、正整数 level、selectedDefenderId、defenders 数组、enemies 数组；每个 enemy 必须含非空 id、非负 lane、会随移动变化的 position、health 与正数 maxHealth。",
                 "界面必须清晰显示一个原创项目标题、至少两个原创防御单位选项、资源与波次状态，以及开始、加速、下一关和重开等可理解操作；玩法类型不授权复刻现有游戏，不得沿用、翻译或近似改写现有作品的角色、单位名、Logo、贴图、标志性布局或受保护视觉语言。界面必须提供 data-playtest-id=\"start\"、data-playtest-id=\"defender-option\"、data-playtest-id=\"lane-cell\"、data-playtest-id=\"speed-up\"、data-playtest-id=\"next-level\"、data-playtest-id=\"restart\" 的真实可点击控件；每个固定 data-playtest-id 在对应受控试玩步骤都必须恰好匹配一个可见且启用（disabled=false）的真实可点击 HTMLElement，同一固定值不得出现在多个控件上。",
                 "防御单位多选项 UI 只能给一个真实控件设置 data-playtest-id=\"defender-option\" 作为自动化入口，关卡多格 UI 只能给一个真实控件设置 data-playtest-id=\"lane-cell\" 作为自动化入口，其余选项和格子不得复用这两个固定值。",
-                "受控试玩会依次开始、选择并放置防御单位、加速，要求敌人移动并受伤、关卡进入 won；随后 next-level 必须让 level 增加，restart 必须再次推进 sequence 并回到 ready 或 playing。"
+                "受控试玩会依次开始、选择并放置防御单位、加速，要求敌人移动并受伤、关卡进入 won；随后 next-level 必须让 level 增加，restart 必须再次推进 sequence 并回到 ready 或 playing。",
+                "还必须监听 genarrative:host-message 中的 host.slice.start / host.slice.stop；lane-defense-v1 的正式 sliceId 依次固定为 deploy-defender、resolve-wave、advance-level，必须通过 window.genarrativeGameBridge.reportSlice 上报当前 ID 的 playing、paused、completed 或 failed。游戏自身 hit-test / hover 只允许通过 reportTargetInspection 上报当前 .agent/manifest.json 已登记的 asset.id，或与该 asset.id 对应的资源槽位 slotId；离开对象调用 clearInspection，不得上报资源名称、路径、HTML 或宿主命令。"
             )
         }
     }
diff --git a/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_protocol/autonomous_completion_contract_tests.rs b/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_protocol/autonomous_completion_contract_tests.rs
index 725bfa711..60fea7d14 100644
--- a/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_protocol/autonomous_completion_contract_tests.rs
+++ b/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_protocol/autonomous_completion_contract_tests.rs
@@ -928,6 +928,32 @@ fn autonomous_playtest_contract_requires_unique_visible_enabled_automation_contr
     }
 }
 
+#[test]
+fn autonomous_playtest_contract_freezes_formal_slice_and_hover_identifiers() {
+    let generic = autonomous_playtest_contract_prompt(BrowserPlaytestScenario::GenericV1);
+    for requirement in [
+        "host.slice.start / host.slice.stop",
+        "sliceId 固定为 core-gameplay",
+        "window.genarrativeGameBridge.reportSlice",
+        ".agent/manifest.json 已登记的 asset.id",
+        "资源槽位 slotId",
+        "clearInspection",
+    ] {
+        assert!(
+            generic.contains(requirement),
+            "missing generic P4/P5 requirement: {requirement}"
+        );
+    }
+
+    let lane = autonomous_playtest_contract_prompt(BrowserPlaytestScenario::LaneDefenseV1);
+    for slice_id in ["deploy-defender", "resolve-wave", "advance-level"] {
+        assert!(
+            lane.contains(slice_id),
+            "missing lane-defense formal slice ID: {slice_id}"
+        );
+    }
+}
+
 #[test]
 fn generic_playtest_contract_requires_play_opportunity_and_post_action_outcome() {
     let prompt = autonomous_playtest_contract_prompt(BrowserPlaytestScenario::GenericV1);
diff --git a/apps/ai-game-creator-shell/src-tauri/src/main.rs b/apps/ai-game-creator-shell/src-tauri/src/main.rs
index cb2bacc74..de08aaffd 100644
--- a/apps/ai-game-creator-shell/src-tauri/src/main.rs
+++ b/apps/ai-game-creator-shell/src-tauri/src/main.rs
@@ -32,7 +32,8 @@ use shared_contracts::game_creation_app::{
     GameCreationAppCommandRunStatus, GameCreationAppLimitedRunCommandDescriptor,
     GameCreationAppManifest, GameCreationAppPermission, GameCreationAppPreviewState,
     GameCreationAppPreviewStatus, GameCreationAppTaskState, GameCreationAppTaskStatus,
-    GameIterationVersionResourceBinding, ProjectResourceCanvasLayout,
+    GameIterationVersionResourceBinding, GameResourceCategory, GameResourceDescriptor,
+    GameTestSlice, GameTestSliceStatus, ProjectResourceCanvasLayout,
     ProjectResourceCanvasLayoutMode, ProjectResourceCanvasPosition, RunnableGameVersion,
     RunnableGameVersionCreatedReason, RunnableGameVersionValidation,
     UpdateProjectResourceCanvasLayoutResult, UpdateProjectResourceCanvasLayoutStatus,
diff --git a/apps/ai-game-creator-shell/src-tauri/src/preview.rs b/apps/ai-game-creator-shell/src-tauri/src/preview.rs
index 8ed4abde0..e64a0b2df 100644
--- a/apps/ai-game-creator-shell/src-tauri/src/preview.rs
+++ b/apps/ai-game-creator-shell/src-tauri/src/preview.rs
@@ -121,12 +121,13 @@ const GAME_RUN_BRIDGE_BOOTSTRAP: &str = r#"(() => {
   const protocolVersion = 'game-creator-run-bridge.v1';
   const hostSchema = 'game-creator-host-message.v1';
   const runtimeSchema = 'game-creator-runtime-message.v1';
-  const hostTypes = new Set(['host.start', 'host.pause', 'host.resume', 'host.stop', 'host.state.request', 'host.inspection.request']);
+  const hostTypes = new Set(['host.start', 'host.pause', 'host.resume', 'host.stop', 'host.state.request', 'host.inspection.request', 'host.slice.start', 'host.slice.stop']);
   let session = null;
   let hostOrigin = null;
   let hostSequence = 0;
   let runtimeSequence = 0;
   let state = 'starting';
+  let currentSlice = null;
   const hostRequestIds = new Set();
 
   const randomId = () => {
@@ -165,16 +166,22 @@ const GAME_RUN_BRIDGE_BOOTSTRAP: &str = r#"(() => {
   };
   const reportError = (code, message, recoverable = false) =>
     send('runtime.error', { code, message, recoverable });
-  const reportSlice = (sliceId, title, status, summary) =>
-    send('runtime.slice', summary === undefined ? { sliceId, title, status } : { sliceId, title, status, summary });
+  const reportSlice = (sliceId, title, status, summary) => {
+    if (currentSlice && currentSlice.sliceId === sliceId) currentSlice.status = status;
+    return send('runtime.slice', summary === undefined ? { sliceId, title, status } : { sliceId, title, status, summary });
+  };
   const reportInspection = (inspectionId, label, metrics, summary) =>
     send('runtime.inspection', summary === undefined ? { inspectionId, label, metrics } : { inspectionId, label, metrics, summary });
+  const reportTargetInspection = (targetKind, targetId) =>
+    send('runtime.inspection', { inspectionId: `hover-${targetKind}`, label: '', metrics: {}, targetKind, targetId });
+  const clearInspection = () =>
+    send('runtime.inspection', { inspectionId: 'hover-clear', label: '', metrics: {}, targetKind: 'none' });
 
   Object.defineProperty(window, 'genarrativeGameBridge', {
     configurable: false,
     enumerable: false,
     writable: false,
-    value: Object.freeze({ protocolVersion, reportState, reportError, reportSlice, reportInspection }),
+    value: Object.freeze({ protocolVersion, reportState, reportError, reportSlice, reportInspection, reportTargetInspection, clearInspection }),
   });
 
   addEventListener('message', event => {
@@ -204,6 +211,9 @@ const GAME_RUN_BRIDGE_BOOTSTRAP: &str = r#"(() => {
       return;
     }
     if (event.origin !== hostOrigin || !sameIdentity(message) || message.sequence !== hostSequence + 1) return;
+    if ((message.type === 'host.slice.start' || message.type === 'host.slice.stop') &&
+        (!message.payload || typeof message.payload !== 'object' || Object.keys(message.payload).length !== 1 ||
+         typeof message.payload.sliceId !== 'string' || !message.payload.sliceId)) return;
     hostSequence = message.sequence;
     hostRequestIds.add(message.requestId);
     if (message.type === 'host.pause') {
@@ -220,6 +230,21 @@ const GAME_RUN_BRIDGE_BOOTSTRAP: &str = r#"(() => {
         label: '运行画面',
         metrics: { state, viewportWidth: innerWidth, viewportHeight: innerHeight },
       }, message.requestId);
+    } else if (message.type === 'host.slice.start') {
+      currentSlice = { sliceId: message.payload.sliceId, status: 'starting' };
+      send('runtime.slice', { sliceId: currentSlice.sliceId, title: '', status: 'starting' }, message.requestId);
+      dispatchEvent(new CustomEvent('genarrative:host-message', { detail: message }));
+      if (currentSlice && currentSlice.sliceId === message.payload.sliceId && currentSlice.status === 'starting') {
+        currentSlice.status = 'playing';
+        send('runtime.slice', { sliceId: currentSlice.sliceId, title: '', status: 'playing' });
+      }
+      return;
+    } else if (message.type === 'host.slice.stop') {
+      const sliceId = message.payload.sliceId;
+      if (currentSlice && currentSlice.sliceId === sliceId) currentSlice.status = 'paused';
+      send('runtime.slice', { sliceId, title: '', status: 'paused' }, message.requestId);
+      currentSlice = null;
+      clearInspection();
     } else if (message.type === 'host.stop') {
       state = 'stopped';
       send('runtime.state', { status: state }, message.requestId);
diff --git a/apps/ai-game-creator-shell/src-tauri/src/project/runnable_versions.rs b/apps/ai-game-creator-shell/src-tauri/src/project/runnable_versions.rs
index 16820415c..a4a62fedd 100644
--- a/apps/ai-game-creator-shell/src-tauri/src/project/runnable_versions.rs
+++ b/apps/ai-game-creator-shell/src-tauri/src/project/runnable_versions.rs
@@ -30,6 +30,166 @@ fn runnable_version_root(root: &Path, version_id: &str) -> PathBuf {
     root.join(".agent/runnable-versions").join(version_id)
 }
 
+fn runnable_test_slices(version_id: &str, scenario: BrowserPlaytestScenario) -> Vec<GameTestSlice> {
+    let definitions: &[(&str, &str, &str, &str)] = match scenario {
+        BrowserPlaytestScenario::GenericV1 => &[((
+            "core-gameplay",
+            "核心玩法",
+            "游戏进入 ready",
+            "游戏进入 won 或 lost",
+        ))],
+        BrowserPlaytestScenario::LaneDefenseV1 => &[
+            (
+                "deploy-defender",
+                "部署防御单位",
+                "关卡进入 ready",
+                "防御单位完成部署",
+            ),
+            (
+                "resolve-wave",
+                "推进当前波次",
+                "防御单位已部署",
+                "当前波次进入 won 或 lost",
+            ),
+            (
+                "advance-level",
+                "进入下一关",
+                "当前波次已完成",
+                "下一关恢复 ready",
+            ),
+        ],
+    };
+    definitions
+        .iter()
+        .enumerate()
+        .map(
+            |(order, (slice_id, title, start_condition, end_condition))| GameTestSlice {
+                slice_id: (*slice_id).to_string(),
+                version_id: version_id.to_string(),
+                title: (*title).to_string(),
+                order: u32::try_from(order).unwrap_or(u32::MAX),
+                start_condition: (*start_condition).to_string(),
+                end_condition: (*end_condition).to_string(),
+                status: GameTestSliceStatus::Idle,
+            },
+        )
+        .collect()
+}
+
+fn runnable_resource_category(
+    media_type: &str,
+    kind: &str,
+    local_path: &str,
+) -> Option<GameResourceCategory> {
+    let media_type = media_type.to_ascii_lowercase();
+    let kind = kind.to_ascii_lowercase();
+    let local_path = local_path.to_ascii_lowercase();
+    if media_type.starts_with("audio/")
+        || [".mp3", ".wav", ".ogg", ".m4a", ".aac", ".flac", ".opus"]
+            .iter()
+            .any(|extension| local_path.ends_with(extension))
+        || ["audio", "bgm", "music", "sfx", "sound", "voice"]
+            .iter()
+            .any(|token| kind.contains(token))
+    {
+        return Some(GameResourceCategory::Audio);
+    }
+    if media_type.starts_with("image/")
+        || media_type.starts_with("video/")
+        || [
+            ".png", ".jpg", ".jpeg", ".webp", ".gif", ".svg", ".avif", ".bmp", ".mp4", ".webm",
+            ".mov",
+        ]
+        .iter()
+        .any(|extension| local_path.ends_with(extension))
+        || [
+            "art",
+            "animation",
+            "character",
+            "icon",
+            "image",
+            "scene",
+            "sprite",
+            "ui",
+            "video",
+        ]
+        .iter()
+        .any(|token| kind.contains(token))
+    {
+        return Some(GameResourceCategory::Art);
+    }
+    if media_type.starts_with("text/")
+        || media_type.contains("json")
+        || media_type.contains("yaml")
+        || [
+            ".md",
+            ".markdown",
+            ".txt",
+            ".json",
+            ".yaml",
+            ".yml",
+            ".toml",
+        ]
+        .iter()
+        .any(|extension| local_path.ends_with(extension))
+    {
+        return Some(GameResourceCategory::Document);
+    }
+    None
+}
+
+fn runnable_resource_descriptors(
+    root: &Path,
+    manifest: &GameCreationAppManifest,
+) -> Vec<GameResourceDescriptor> {
+    manifest
+        .assets
+        .iter()
+        .filter_map(|asset| {
+            let category =
+                runnable_resource_category(&asset.media_type, &asset.kind, &asset.local_path)?;
+            let (width, height) = if asset.media_type.starts_with("image/") {
+                normalize_relative_path(&asset.local_path)
+                    .ok()
+                    .and_then(|relative| resolve_local_project_path(root, &relative).ok())
+                    .and_then(|path| {
+                        let metadata = fs::metadata(&path).ok()?;
+                        if !metadata.is_file() || metadata.len() > RUNNABLE_ARTIFACT_MAX_FILE_BYTES
+                        {
+                            return None;
+                        }
+                        fs::read(path).ok()
+                    })
+                    .and_then(|bytes| {
+                        image::ImageReader::new(std::io::Cursor::new(bytes))
+                            .with_guessed_format()
+                            .ok()?
+                            .into_dimensions()
+                            .ok()
+                    })
+                    .map_or((None, None), |(width, height)| (Some(width), Some(height)))
+            } else {
+                (None, None)
+            };
+            let name = Path::new(&asset.local_path)
+                .file_name()
+                .and_then(|value| value.to_str())
+                .unwrap_or(asset.id.as_str())
+                .to_string();
+            Some(GameResourceDescriptor {
+                resource_id: asset.id.clone(),
+                name,
+                category,
+                subtype: asset.kind.clone(),
+                width,
+                height,
+                duration_ms: None,
+                format: asset.media_type.clone(),
+            })
+        })
+        .collect()
+}
+
 fn collect_runnable_artifact_files(
     base: &Path,
     directory: &Path,
@@ -284,6 +444,7 @@ pub(crate) fn register_current_runnable_game_version_at(
     validation_agent_id: &str,
     validation_run_id: &str,
     report_path: &str,
+    playtest_scenario: BrowserPlaytestScenario,
 ) -> Result<RunnableGameVersion, String> {
     let manifest_path = root.join(".agent/manifest.json");
     let mut manifest = read_manifest(&manifest_path)?;
@@ -330,6 +491,8 @@ pub(crate) fn register_current_runnable_game_version_at(
         })
         .collect::<Vec<_>>();
     resource_bindings.sort_by(|left, right| left.slot_id.cmp(&right.slot_id));
+    let test_slices = runnable_test_slices(&version_id, playtest_scenario);
+    let resource_descriptors = runnable_resource_descriptors(root, &manifest);
     let version = RunnableGameVersion {
         schema_version: RUNNABLE_GAME_VERSION_SCHEMA_VERSION.to_string(),
         version_id: version_id.clone(),
@@ -340,6 +503,8 @@ pub(crate) fn register_current_runnable_game_version_at(
         artifact_sha256: snapshot.artifact_sha256,
         entry_path: "game/index.html".to_string(),
         resource_bindings,
+        test_slices,
+        resource_descriptors,
         created_reason,
         validation: RunnableGameVersionValidation {
             static_smoke_passed: true,
@@ -435,10 +600,28 @@ mod tests {
         fs::write(root.join("game/index.html"), "<main>revision one</main>")
             .expect("write game entry");
         fs::write(root.join("assets/player.txt"), "player one").expect("write game asset");
-        let manifest = new_game_creation_app_manifest(
+        let mut manifest = new_game_creation_app_manifest(
             format!("project-{label}"),
             format!("可运行版本测试 {label}"),
         );
+        manifest.assets.push(GameCreationAppAssetManifestEntry {
+            id: "player-document".to_string(),
+            kind: "design-document".to_string(),
+            media_type: "text/plain".to_string(),
+            local_path: "assets/player.txt".to_string(),
+            source: GameCreationAppAssetSource {
+                kind: GameCreationAppAssetSourceKind::Generated,
+                canvas_project_id: None,
+                resource_id: None,
+                asset_object_id: None,
+                task_id: None,
+                prompt: None,
+                model: None,
+                generation_route: None,
+                generation_kind: None,
+                reference_resource_ids: Vec::new(),
+            },
+        });
         write_manifest(&root.join(".agent/manifest.json"), &manifest)
             .expect("write project manifest");
         root
@@ -453,6 +636,7 @@ mod tests {
             &format!(
                 ".agent/runtime/browser-validations/program-agent/run-{revision}/1/validation.json"
             ),
+            BrowserPlaytestScenario::GenericV1,
         )
         .expect("register runnable version")
     }
@@ -467,6 +651,29 @@ mod tests {
             first.created_reason,
             RunnableGameVersionCreatedReason::Initial
         );
+        assert_eq!(
+            first
+                .test_slices
+                .iter()
+                .map(|slice| slice.slice_id.as_str())
+                .collect::<Vec<_>>(),
+            vec!["core-gameplay"]
+        );
+        assert_eq!(first.test_slices[0].version_id, first.version_id);
+        assert_eq!(first.test_slices[0].status, GameTestSliceStatus::Idle);
+        assert_eq!(
+            first.resource_descriptors,
+            vec![GameResourceDescriptor {
+                resource_id: "player-document".to_string(),
+                name: "player.txt".to_string(),
+                category: GameResourceCategory::Document,
+                subtype: "design-document".to_string(),
+                width: None,
+                height: None,
+                duration_ms: None,
+                format: "text/plain".to_string(),
+            }]
+        );
         assert_eq!(
             fs::read_to_string(
                 root.join(".agent/runnable-versions/runnable-r1/artifact/game/index.html")
@@ -505,6 +712,33 @@ mod tests {
         fs::remove_dir_all(root).ok();
     }
 
+    #[test]
+    fn runnable_test_slices_follow_the_verified_playtest_scenario() {
+        let generic = runnable_test_slices("runnable-r1", BrowserPlaytestScenario::GenericV1);
+        assert_eq!(
+            generic
+                .iter()
+                .map(|slice| slice.slice_id.as_str())
+                .collect::<Vec<_>>(),
+            vec!["core-gameplay"]
+        );
+
+        let lane = runnable_test_slices("runnable-r2", BrowserPlaytestScenario::LaneDefenseV1);
+        assert_eq!(
+            lane.iter()
+                .map(|slice| (slice.order, slice.slice_id.as_str()))
+                .collect::<Vec<_>>(),
+            vec![
+                (0, "deploy-defender"),
+                (1, "resolve-wave"),
+                (2, "advance-level"),
+            ]
+        );
+        assert!(lane.iter().all(|slice| {
+            slice.version_id == "runnable-r2" && slice.status == GameTestSliceStatus::Idle
+        }));
+    }
+
     #[test]
     fn runnable_snapshot_retry_reuses_original_descriptor_timestamp() {
         let root = init_runnable_version_test_project("orphan-retry");
diff --git a/apps/ai-game-creator-shell/src-tauri/src/tests/project.rs b/apps/ai-game-creator-shell/src-tauri/src/tests/project.rs
index cd5b82ef9..10b6b62ff 100644
--- a/apps/ai-game-creator-shell/src-tauri/src/tests/project.rs
+++ b/apps/ai-game-creator-shell/src-tauri/src/tests/project.rs
@@ -3290,7 +3290,7 @@ fn local_preview_can_serve_an_immutable_version_snapshot_instead_of_the_working_
 }
 
 #[test]
-fn local_preview_injects_the_host_owned_p3_bridge_without_mutating_html() {
+fn local_preview_injects_the_host_owned_runtime_bridge_without_mutating_html() {
     let root = unique_project_path();
     init_local_game_project_at(&root, "project-bridge", "运行桥预览测试").expect("project init");
     let original = "<!doctype html><html><head><title>Bridge</title></head><body></body></html>";
@@ -3315,6 +3315,11 @@ fn local_preview_injects_the_host_owned_p3_bridge_without_mutating_html() {
     assert!(script_response.contains("game-creator-run-bridge.v1"));
     assert!(script_response.contains("runtime.ready"));
     assert!(script_response.contains("event.source !== parent"));
+    assert!(script_response.contains("host.slice.start"));
+    assert!(script_response.contains("host.slice.stop"));
+    assert!(script_response.contains("reportTargetInspection"));
+    assert!(script_response.contains("clearInspection"));
+    assert!(script_response.contains("Object.keys(message.payload).length !== 1"));
 
     fs::remove_dir_all(root).ok();
 }
diff --git a/apps/ai-game-creator-shell/src/features/project-workspace/LocalGamePreviewFrame.tsx b/apps/ai-game-creator-shell/src/features/project-workspace/LocalGamePreviewFrame.tsx
index c706366bb..0fd32943c 100644
--- a/apps/ai-game-creator-shell/src/features/project-workspace/LocalGamePreviewFrame.tsx
+++ b/apps/ai-game-creator-shell/src/features/project-workspace/LocalGamePreviewFrame.tsx
@@ -35,6 +35,8 @@ export type LocalGamePreviewFrameHandle = {
   stop: () => boolean;
   requestState: () => boolean;
   requestInspection: () => boolean;
+  startSlice: (sliceId: string) => boolean;
+  stopSlice: (sliceId: string) => boolean;
 };
 
 type ActiveBridgeSession = {
@@ -101,7 +103,10 @@ export const LocalGamePreviewFrame = forwardRef<
     onSessionChange,
   };
 
-  const sendHostMessage = useCallback((type: GameHostMessageType) => {
+  const sendHostMessage = useCallback((
+    type: GameHostMessageType,
+    sliceId?: string,
+  ) => {
     const active = activeRef.current;
     const targetWindow = iframeRef.current?.contentWindow;
     if (!active || !targetWindow) {
@@ -118,6 +123,7 @@ export const LocalGamePreviewFrame = forwardRef<
       requestId,
       sequence: active.nextHostSequence,
       type,
+      payload: sliceId ? { sliceId } : undefined,
     });
     active.nextHostSequence += 1;
     targetWindow.postMessage(message, active.identity.previewOrigin);
@@ -152,6 +158,8 @@ export const LocalGamePreviewFrame = forwardRef<
       stop: () => stopActiveSession(true),
       requestState: () => sendHostMessage('host.state.request'),
       requestInspection: () => sendHostMessage('host.inspection.request'),
+      startSlice: (sliceId) => sendHostMessage('host.slice.start', sliceId),
+      stopSlice: (sliceId) => sendHostMessage('host.slice.stop', sliceId),
     }),
     [sendHostMessage, stopActiveSession],
   );
diff --git a/apps/ai-game-creator-shell/src/features/project-workspace/gameRunBridge.ts b/apps/ai-game-creator-shell/src/features/project-workspace/gameRunBridge.ts
index ced61e597..45a66d5dc 100644
--- a/apps/ai-game-creator-shell/src/features/project-workspace/gameRunBridge.ts
+++ b/apps/ai-game-creator-shell/src/features/project-workspace/gameRunBridge.ts
@@ -1,5 +1,6 @@
 import type {
   GameHostMessage,
+  GameHostSlicePayload,
   GameHostMessageType,
   GameRunSession,
   GameRuntimeInspectionMetric,
@@ -182,7 +183,11 @@ function isInspectionMetric(
 function validateInspectionPayload(payload: unknown) {
   if (
     !isPlainObject(payload) ||
-    !hasExactKeys(payload, ['inspectionId', 'label', 'metrics'], ['summary']) ||
+    !hasExactKeys(
+      payload,
+      ['inspectionId', 'label', 'metrics'],
+      ['summary', 'targetKind', 'targetId'],
+    ) ||
     !isSafeIdentifier(payload.inspectionId, 128) ||
     !isSafeText(payload.label, 128) ||
     (payload.summary !== undefined && !isSafeText(payload.summary, 512)) ||
@@ -190,6 +195,23 @@ function validateInspectionPayload(payload: unknown) {
   ) {
     return false;
   }
+  if (
+    payload.targetKind !== undefined &&
+    !['resource', 'entity', 'none'].includes(String(payload.targetKind))
+  ) {
+    return false;
+  }
+  if (
+    payload.targetKind === 'none'
+      ? payload.targetId !== undefined
+      : payload.targetKind !== undefined &&
+        !isSafeIdentifier(payload.targetId, 512)
+  ) {
+    return false;
+  }
+  if (payload.targetKind === undefined && payload.targetId !== undefined) {
+    return false;
+  }
   const metrics = Object.entries(payload.metrics);
   return (
     metrics.length <= 32 &&
@@ -302,14 +324,16 @@ export function createGameHostMessage({
   requestId,
   sequence,
   type,
+  payload,
 }: {
   identity: GameRunBridgeIdentity;
   sessionId: string;
   requestId: string;
   sequence: number;
   type: GameHostMessageType;
+  payload?: GameHostSlicePayload;
 }): GameHostMessage {
-  return {
+  const message: GameHostMessage = {
     schemaVersion: GAME_HOST_MESSAGE_SCHEMA_VERSION,
     protocolVersion: GAME_RUN_BRIDGE_PROTOCOL_VERSION,
     requestId,
@@ -321,6 +345,10 @@ export function createGameHostMessage({
     versionId: identity.versionId,
     projectRevision: identity.projectRevision,
   };
+  if (payload) {
+    message.payload = payload;
+  }
+  return message;
 }
 
 function responseTypeMatches(
@@ -341,6 +369,9 @@ function responseTypeMatches(
       'host.state.request',
     ].includes(hostType);
   }
+  if (runtimeType === 'runtime.slice') {
+    return hostType === 'host.slice.start' || hostType === 'host.slice.stop';
+  }
   return (
     runtimeType === 'runtime.inspection' &&
     hostType === 'host.inspection.request'
@@ -455,6 +486,19 @@ export function gameRunSessionFromRuntimeMessage(
     return { ...session, status: 'playing', updatedAt: now };
   }
   if (message.type !== 'runtime.state') {
+    if (message.type === 'runtime.slice') {
+      const status =
+        message.payload.status === 'completed'
+          ? 'paused'
+          : message.payload.status === 'failed'
+            ? 'failed'
+            : message.payload.status === 'playing'
+              ? 'playing'
+              : message.payload.status === 'paused'
+                ? 'paused'
+                : session.status;
+      return { ...session, status, updatedAt: now };
+    }
     return { ...session, updatedAt: now };
   }
   const status =
diff --git a/apps/ai-game-creator-shell/src/features/project-workspace/gameTestSliceModel.ts b/apps/ai-game-creator-shell/src/features/project-workspace/gameTestSliceModel.ts
new file mode 100644
index 000000000..8d1111432
--- /dev/null
+++ b/apps/ai-game-creator-shell/src/features/project-workspace/gameTestSliceModel.ts
@@ -0,0 +1,158 @@
+import type {
+  GameRuntimeMessage,
+  GameTestSlice,
+  GameTestSliceStatus,
+  RunnableGameVersion,
+} from '../../../../../packages/shared/src/contracts/gameCreationApp';
+
+export type ActiveGameTestSlice = GameTestSlice & {
+  stale: boolean;
+};
+
+export type TrustedGameResourceInspection = {
+  targetKind: 'resource' | 'entity';
+  targetId: string;
+  resourceId: string;
+  slotId: string;
+  name: string;
+  category: 'document' | 'version' | 'art' | 'audio';
+  subtype: string;
+  format: string;
+  width?: number;
+  height?: number;
+  durationMs?: number;
+  versionId: string;
+};
+
+const transitions: Record<
+  GameTestSliceStatus,
+  ReadonlySet<GameTestSliceStatus>
+> = {
+  idle: new Set(['starting']),
+  starting: new Set(['playing', 'failed']),
+  playing: new Set(['paused', 'completed', 'failed']),
+  paused: new Set(['playing', 'completed', 'failed']),
+  completed: new Set(['starting']),
+  failed: new Set(['starting']),
+};
+
+function validSliceText(value: string, maxChars: number) {
+  return value.length > 0 && value.length <= maxChars && value.trim() === value;
+}
+
+export function formalGameTestSlices(version: RunnableGameVersion | null) {
+  if (!version?.testSlices || version.testSlices.length > 64) {
+    return [];
+  }
+  const ids = new Set<string>();
+  const orders = new Set<number>();
+  for (const slice of version.testSlices) {
+    if (
+      slice.versionId !== version.versionId ||
+      slice.status !== 'idle' ||
+      !validSliceText(slice.sliceId, 128) ||
+      !validSliceText(slice.title, 128) ||
+      !Number.isSafeInteger(slice.order) ||
+      slice.order < 0 ||
+      ids.has(slice.sliceId) ||
+      orders.has(slice.order)
+    ) {
+      return [];
+    }
+    ids.add(slice.sliceId);
+    orders.add(slice.order);
+  }
+  return [...version.testSlices].sort(
+    (left, right) =>
+      left.order - right.order || left.sliceId.localeCompare(right.sliceId),
+  );
+}
+
+export function beginGameTestSlice(slice: GameTestSlice): ActiveGameTestSlice {
+  return { ...slice, status: 'starting', stale: false };
+}
+
+export function projectGameTestSliceMessage(
+  active: ActiveGameTestSlice | null,
+  message: GameRuntimeMessage,
+): ActiveGameTestSlice | null {
+  if (
+    !active ||
+    active.stale ||
+    message.type !== 'runtime.slice' ||
+    message.payload.sliceId !== active.sliceId
+  ) {
+    return active;
+  }
+  const nextStatus = message.payload.status;
+  if (
+    nextStatus === active.status ||
+    transitions[active.status].has(nextStatus)
+  ) {
+    return { ...active, status: nextStatus };
+  }
+  return active;
+}
+
+export function projectGameTestSliceSessionStatus(
+  active: ActiveGameTestSlice | null,
+  message: GameRuntimeMessage,
+): ActiveGameTestSlice | null {
+  if (!active || active.stale || message.type !== 'runtime.state') {
+    return active;
+  }
+  const nextStatus =
+    message.payload.status === 'paused'
+      ? 'paused'
+      : message.payload.status === 'playing'
+        ? 'playing'
+        : null;
+  if (!nextStatus || !transitions[active.status].has(nextStatus)) {
+    return active;
+  }
+  return { ...active, status: nextStatus };
+}
+
+export function trustedInspectionFromRuntimeMessage(
+  version: RunnableGameVersion | null,
+  message: GameRuntimeMessage,
+): TrustedGameResourceInspection | null | undefined {
+  if (!version || message.type !== 'runtime.inspection') {
+    return undefined;
+  }
+  const { targetKind, targetId } = message.payload;
+  if (targetKind === 'none') {
+    return null;
+  }
+  if ((targetKind !== 'resource' && targetKind !== 'entity') || !targetId) {
+    return undefined;
+  }
+  const binding = version.resourceBindings.find((candidate) =>
+    targetKind === 'resource'
+      ? candidate.resourceId === targetId
+      : candidate.slotId === targetId,
+  );
+  if (!binding) {
+    return null;
+  }
+  const descriptor = version.resourceDescriptors?.find(
+    (candidate) => candidate.resourceId === binding.resourceId,
+  );
+  if (!descriptor) {
+    return null;
+  }
+  return {
+    targetKind,
+    targetId,
+    resourceId: descriptor.resourceId,
+    slotId: binding.slotId,
+    name: descriptor.name,
+    category: descriptor.category,
+    subtype: descriptor.subtype,
+    format: descriptor.format,
+    width: descriptor.width,
+    height: descriptor.height,
+    durationMs: descriptor.durationMs,
+    versionId: version.versionId,
+  };
+}
diff --git a/apps/ai-game-creator-shell/src/styles.css b/apps/ai-game-creator-shell/src/styles.css
index 0b256136f..c23c5a6a7 100644
--- a/apps/ai-game-creator-shell/src/styles.css
+++ b/apps/ai-game-creator-shell/src/styles.css
@@ -4424,7 +4424,7 @@ iframe.preview-frame {
 
 .game-run-surface {
   display: grid;
-  grid-template-rows: minmax(300px, 1fr) auto auto;
+  grid-template-rows: minmax(300px, 1fr) auto auto auto;
   gap: 12px;
   min-height: 0;
   padding: 12px;
@@ -4516,6 +4516,11 @@ iframe.preview-frame {
   cursor: pointer;
 }
 
+.game-run-slice-controls button:disabled {
+  cursor: default;
+  opacity: 0.45;
+}
+
 .game-run-slice-controls span {
   color: #9a7d70;
   font-size: 11px;
@@ -4524,7 +4529,7 @@ iframe.preview-frame {
 
 .game-run-panels {
   display: grid;
-  grid-template-columns: repeat(2, minmax(0, 1fr));
+  grid-template-columns: repeat(3, minmax(0, 1fr));
   gap: 10px;
 }
 
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 1aa047af5..7f194efce 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
@@ -1,4 +1,6 @@
 import {
+  ChevronLeft,
+  ChevronRight,
   FileText,
   FolderTree,
   Gamepad2,
@@ -6,6 +8,8 @@ import {
   Info,
   ListFilter,
   Music2,
+  Pause,
+  Play,
   Search,
   Settings2,
   Sparkles,
@@ -35,6 +39,15 @@ import type {
   RunnableGameVersion,
 } from '../../../../../packages/shared/src/contracts/gameCreationApp';
 import { resolveTauriInvoke } from '../../app/tauri';
+import {
+  beginGameTestSlice,
+  formalGameTestSlices,
+  type ActiveGameTestSlice,
+  type TrustedGameResourceInspection,
+  projectGameTestSliceMessage,
+  projectGameTestSliceSessionStatus,
+  trustedInspectionFromRuntimeMessage,
+} from '../../features/project-workspace/gameTestSliceModel';
 import {
   LocalGamePreviewFrame,
   type LocalGamePreviewFrameHandle,
@@ -390,9 +403,7 @@ const ResourceCard = memo(function ResourceCard({
       type="button"
       className={`game-resource-card${selected ? ' is-selected' : ''}${
         currentVersion ? ' is-current-version' : ''
-      }${
-        relationState ? ` is-relation-${relationState}` : ''
-      }`}
+      }${relationState ? ` is-relation-${relationState}` : ''}`}
       aria-pressed={selected}
       data-resource-id={resource.id}
       title="打开资源详情"
@@ -456,10 +467,16 @@ export default function ProjectDevelopmentView({
     previewId: string;
     origin: string;
   } | null>(null);
-  const [gameRunSession, setGameRunSession] =
-    useState<GameRunSession | null>(null);
+  const [gameRunSession, setGameRunSession] = useState<GameRunSession | null>(
+    null,
+  );
   const [latestRuntimeMessage, setLatestRuntimeMessage] =
     useState<GameRuntimeMessage | null>(null);
+  const [selectedTestSliceId, setSelectedTestSliceId] = useState('');
+  const [activeTestSlice, setActiveTestSlice] =
+    useState<ActiveGameTestSlice | null>(null);
+  const [trustedInspection, setTrustedInspection] =
+    useState<TrustedGameResourceInspection | null>(null);
   const [imagePreview, setImagePreview] = useState<ImagePreviewState>({
     status: 'idle',
     resourceId: null,
@@ -476,6 +493,7 @@ export default function ProjectDevelopmentView({
   const resourceCanvasRef = useRef<HTMLDivElement>(null);
   const gamePreviewFrameRef = useRef<LocalGamePreviewFrameHandle>(null);
   const resourceFocusRef = useRef<HTMLElement>(null);
+  const pendingResourceLocateRef = useRef<string | null>(null);
   const resourceListScrollRef = useRef({ left: 0, top: 0 });
   const restoreResourceListScrollRef = useRef(false);
 
@@ -504,7 +522,17 @@ export default function ProjectDevelopmentView({
           previewOrigin: activePreviewIdentity.origin,
         }
       : null;
-  const runAvailable = runnableVersions.length > 0 && currentRunnableVersion !== null;
+  const runAvailable =
+    runnableVersions.length > 0 && currentRunnableVersion !== null;
+  const testSlices = useMemo(
+    () => formalGameTestSlices(currentRunnableVersion),
+    [currentRunnableVersion],
+  );
+  const selectedTestSliceIndex = Math.max(
+    0,
+    testSlices.findIndex((slice) => slice.sliceId === selectedTestSliceId),
+  );
+  const selectedTestSlice = testSlices[selectedTestSliceIndex] ?? null;
   const projectedResources = useMemo(
     () => projectResourcesFromReadModels(manifest, attachments, agentResults),
     [agentResults, attachments, manifest],
@@ -732,6 +760,11 @@ export default function ProjectDevelopmentView({
     resources.find((resource) => resource.id === selectedResourceId) ?? null;
   const focusedResource =
     resources.find((resource) => resource.id === focusedResourceId) ?? null;
+  const trustedInspectionResource = trustedInspection
+    ? (resources.find(
+        (resource) => resource.manifestAssetId === trustedInspection.resourceId,
+      ) ?? null)
+    : null;
   const focusedResourceIsImage = Boolean(
     focusedResource && isRasterImageResource(focusedResource),
   );
@@ -796,11 +829,19 @@ export default function ProjectDevelopmentView({
     setSelectedRunnableVersionId(manifest.currentRunnableVersionId ?? '');
   }, [manifest.currentRunnableVersionId, manifest.projectId]);
 
+  useEffect(() => {
+    setSelectedTestSliceId(testSlices[0]?.sliceId ?? '');
+    setActiveTestSlice(null);
+    setTrustedInspection(null);
+  }, [currentRunnableVersion?.versionId]);
+
   useEffect(() => {
     setActiveRunnablePreviewVersionId(null);
     setActivePreviewIdentity(null);
     setGameRunSession(null);
     setLatestRuntimeMessage(null);
+    setActiveTestSlice(null);
+    setTrustedInspection(null);
   }, [manifest.projectId]);
 
   useEffect(() => {
@@ -1003,6 +1044,24 @@ export default function ProjectDevelopmentView({
     }
   }, [focusedResource]);
 
+  useEffect(() => {
+    const pendingResourceId = pendingResourceLocateRef.current;
+    if (mode !== 'resources' || focusedResource || !pendingResourceId) {
+      return;
+    }
+    const card = Array.from(
+      resourceCanvasRef.current?.querySelectorAll<HTMLElement>(
+        '[data-resource-id]',
+      ) ?? [],
+    ).find((candidate) => candidate.dataset.resourceId === pendingResourceId);
+    if (!card) {
+      return;
+    }
+    pendingResourceLocateRef.current = null;
+    card.scrollIntoView?.({ block: 'center', inline: 'center' });
+    card.focus({ preventScroll: true });
+  }, [focusedResource, mode, resourceLayout.positions, selectedResourceId]);
+
   const handleResourceSelect = useCallback((resourceId: string) => {
     const canvas = resourceCanvasRef.current;
     if (canvas) {
@@ -1033,6 +1092,8 @@ export default function ProjectDevelopmentView({
     setActivePreviewIdentity(null);
     setGameRunSession(null);
     setLatestRuntimeMessage(null);
+    setActiveTestSlice(null);
+    setTrustedInspection(null);
     onPreviewChange?.(null);
     try {
       const result = await invoke<RunnableGameVersionLaunchResult>(
@@ -1061,6 +1122,8 @@ export default function ProjectDevelopmentView({
       setActivePreviewIdentity(null);
       setGameRunSession(null);
       setLatestRuntimeMessage(null);
+      setActiveTestSlice(null);
+      setTrustedInspection(null);
       setRunStatus(message);
       onPreviewChange?.({ status: 'failed' });
       return false;
@@ -1085,13 +1148,34 @@ export default function ProjectDevelopmentView({
 
   function showResourcesView() {
     gamePreviewFrameRef.current?.stop();
+    setActiveTestSlice(null);
+    setTrustedInspection(null);
     setMode('resources');
   }
 
+  function locateTrustedInspectionResource() {
+    if (!trustedInspectionResource) {
+      setRunStatus('当前悬停资源未登记在资源管理画布中');
+      return;
+    }
+    const resourceId = trustedInspectionResource.id;
+    gamePreviewFrameRef.current?.stop();
+    pendingResourceLocateRef.current = resourceId;
+    setSearchText('');
+    setFocusedResourceId(null);
+    setSelectedResourceId(resourceId);
+    setActiveTestSlice(null);
+    setTrustedInspection(null);
+    setMode('resources');
+    setRunStatus(`已定位资源：${trustedInspectionResource.label}`);
+  }
+
   function handleGameRunSessionChange(session: GameRunSession) {
     setGameRunSession(session);
     if (session.status === 'starting') {
       setLatestRuntimeMessage(null);
+      setActiveTestSlice(null);
+      setTrustedInspection(null);
     }
     setRunStatus(
       {
@@ -1106,12 +1190,68 @@ export default function ProjectDevelopmentView({
 
   function handleGameRuntimeMessage(message: GameRuntimeMessage) {
     setLatestRuntimeMessage(message);
+    setActiveTestSlice((active) =>
+      projectGameTestSliceSessionStatus(
+        projectGameTestSliceMessage(active, message),
+        message,
+      ),
+    );
+    const inspection = trustedInspectionFromRuntimeMessage(
+      currentRunnableVersion,
+      message,
+    );
+    if (inspection !== undefined) {
+      setTrustedInspection(inspection);
+    }
     if (message.type === 'runtime.error') {
       setRunStatus(message.payload.message || '游戏运行时报告错误');
     } else if (message.type === 'runtime.slice') {
-      setRunStatus(`测试切片：${message.payload.title} · ${message.payload.status}`);
+      const formalSlice = testSlices.find(
+        (slice) => slice.sliceId === message.payload.sliceId,
+      );
+      if (formalSlice) {
+        setRunStatus(
+          `测试切片：${formalSlice.title} · ${message.payload.status}`,
+        );
+      }
     } else if (message.type === 'runtime.inspection') {
-      setRunStatus(`已接收检查结果：${message.payload.label}`);
+      if (inspection !== undefined) {
+        setRunStatus(inspection ? '已更新悬停资源信息' : '悬停资源信息已清除');
+      }
+    }
+  }
+
+  function startTestSlice(slice = selectedTestSlice) {
+    if (!slice || !gameRunSession || gameRunSession.status === 'failed') {
+      setRunStatus('当前运行会话无法启动测试切片');
+      return;
+    }
+    if (activeTestSlice?.stale) {
+      setRunStatus('测试切片已失效，请重新拉起可运行版本');
+      return;
+    }
+    if (
+      activeTestSlice &&
+      activeTestSlice.sliceId !== slice.sliceId &&
+      ['starting', 'playing', 'paused'].includes(activeTestSlice.status)
+    ) {
+      gamePreviewFrameRef.current?.stopSlice(activeTestSlice.sliceId);
+    }
+    setSelectedTestSliceId(slice.sliceId);
+    setTrustedInspection(null);
+    setActiveTestSlice(beginGameTestSlice(slice));
+    if (!gamePreviewFrameRef.current?.startSlice(slice.sliceId)) {
+      setActiveTestSlice(null);
+      setRunStatus('测试切片启动请求发送失败');
+      return;
+    }
+    setRunStatus(`正在启动测试切片：${slice.title}`);
+  }
+
+  function switchTestSlice(offset: -1 | 1) {
+    const target = testSlices[selectedTestSliceIndex + offset];
+    if (target) {
+      startTestSlice(target);
     }
   }
 
@@ -1130,6 +1270,29 @@ export default function ProjectDevelopmentView({
     }
   }
 
+  function toggleTestSlicePlayback() {
+    if (
+      !activeTestSlice ||
+      activeTestSlice.sliceId !== selectedTestSlice?.sliceId
+    ) {
+      startTestSlice();
+      return;
+    }
+    if (activeTestSlice.status === 'playing') {
+      if (gamePreviewFrameRef.current?.pause()) {
+        setRunStatus(`正在暂停测试切片：${activeTestSlice.title}`);
+      }
+      return;
+    }
+    if (activeTestSlice.status === 'paused') {
+      if (gamePreviewFrameRef.current?.resume()) {
+        setRunStatus(`正在继续测试切片：${activeTestSlice.title}`);
+      }
+      return;
+    }
+    startTestSlice();
+  }
+
   return (
     <section
       className="launcher-page launcher-project-development game-project-workbench"
@@ -1620,6 +1783,66 @@ export default function ProjectDevelopmentView({
                   </div>
                 )}
               </div>
+              <div
+                className="game-run-slice-controls"
+                aria-label="测试切片控件"
+              >
+                <button
+                  type="button"
+                  disabled={
+                    !selectedTestSlice ||
+                    selectedTestSliceIndex === 0 ||
+                    activeTestSlice?.stale === true
+                  }
+                  onClick={() => switchTestSlice(-1)}
+                >
+                  <ChevronLeft size={15} aria-hidden="true" />
+                  上一项
+                </button>
+                <button
+                  type="button"
+                  disabled={
+                    !selectedTestSlice ||
+                    gameRunSession?.status === 'failed' ||
+                    activeTestSlice?.stale === true
+                  }
+                  aria-label={
+                    activeTestSlice?.status === 'playing'
+                      ? '暂停测试切片'
+                      : activeTestSlice?.status === 'paused'
+                        ? '继续测试切片'
+                        : '播放测试切片'
+                  }
+                  onClick={toggleTestSlicePlayback}
+                >
+                  {activeTestSlice?.status === 'playing' ? (
+                    <Pause size={15} aria-hidden="true" />
+                  ) : (
+                    <Play size={15} aria-hidden="true" />
+                  )}
+                </button>
+                <span>
+                  {selectedTestSlice
+                    ? `${selectedTestSliceIndex + 1} / ${testSlices.length} · ${selectedTestSlice.title} · ${
+                        activeTestSlice?.sliceId === selectedTestSlice.sliceId
+                          ? activeTestSlice.status
+                          : 'idle'
+                      }`
+                    : '当前版本未登记正式测试切片'}
+                </span>
+                <button
+                  type="button"
+                  disabled={
+                    !selectedTestSlice ||
+                    selectedTestSliceIndex >= testSlices.length - 1 ||
+                    activeTestSlice?.stale === true
+                  }
+                  onClick={() => switchTestSlice(1)}
+                >
+                  下一项
+                  <ChevronRight size={15} aria-hidden="true" />
+                </button>
+              </div>
               <div className="game-run-panels">
                 <section aria-label="可运行版本信息">
                   <header>
@@ -1679,6 +1902,56 @@ export default function ProjectDevelopmentView({
                     {gameRunSession?.status === 'paused' ? '继续' : '暂停'}
                   </button>
                 </section>
+                <section aria-label="悬停资源信息">
+                  <header>
+                    <Info size={16} aria-hidden="true" />
+                    资源信息
+                  </header>
+                  {trustedInspection ? (
+                    <>
+                      <dl>
+                        <div>
+                          <dt>名称</dt>
+                          <dd>{trustedInspection.name}</dd>
+                        </div>
+                        <div>
+                          <dt>类别</dt>
+                          <dd>
+                            {categoryLabels[trustedInspection.category]} ·{' '}
+                            {trustedInspection.format}
+                          </dd>
+                        </div>
+                        <div>
+                          <dt>规格</dt>
+                          <dd>
+                            {trustedInspection.width && trustedInspection.height
+                              ? `${trustedInspection.width} × ${trustedInspection.height}`
+                              : trustedInspection.durationMs
+                                ? `${Math.round(trustedInspection.durationMs / 100) / 10} 秒`
+                                : '未登记'}
+                          </dd>
+                        </div>
+                        <div>
+                          <dt>版本</dt>
+                          <dd>{trustedInspection.versionId}</dd>
+                        </div>
+                        <div>
+                          <dt>绑定</dt>
+                          <dd>{trustedInspection.slotId}</dd>
+                        </div>
+                      </dl>
+                      <button
+                        type="button"
+                        disabled={!trustedInspectionResource}
+                        onClick={locateTrustedInspectionResource}
+                      >
+                        在资源管理中定位
+                      </button>
+                    </>
+                  ) : (
+                    <p>暂无悬停资源</p>
+                  )}
+                </section>
               </div>
               {runStatus ? (
                 <p className="game-run-status" role="status">
diff --git a/apps/ai-game-creator-shell/tests/appSurface/project-development.suite.ts b/apps/ai-game-creator-shell/tests/appSurface/project-development.suite.ts
index c55707612..3475b80ab 100644
--- a/apps/ai-game-creator-shell/tests/appSurface/project-development.suite.ts
+++ b/apps/ai-game-creator-shell/tests/appSurface/project-development.suite.ts
@@ -677,9 +677,7 @@ export function registerProjectWorkbenchFoundationTests() {
     expect(runTab.getAttribute('data-unavailable')).toBe('true');
     fireEvent.click(runTab);
     expect(runTab.getAttribute('aria-selected')).toBe('false');
-    expect(
-      screen.getByText('当前无可运行版本'),
-    ).not.toBeNull();
+    expect(screen.getByText('当前无可运行版本')).not.toBeNull();
     expect(screen.getByLabelText('附件导入失败')).not.toBeNull();
     expect(screen.getByText('broken-reference.png')).not.toBeNull();
     expect(screen.getByText('图片解码失败')).not.toBeNull();
@@ -1958,7 +1956,9 @@ export function registerProjectWorkbenchFoundationTests() {
       );
     });
     expect(screen.getByLabelText('可运行版本信息')).not.toBeNull();
-    expect(screen.queryByLabelText('测试切片控件')).toBeNull();
+    expect(screen.getByLabelText('测试切片控件').textContent).toContain(
+      '当前版本未登记正式测试切片',
+    );
     expect(screen.queryByLabelText('数值微调面板')).toBeNull();
 
     fireEvent.click(screen.getByRole('tab', { name: '资源管理' }));
@@ -1992,11 +1992,7 @@ export function registerProjectWorkbenchFoundationTests() {
       'workbench-version-switch',
       '版本切换测试',
     );
-    const first = runnableVersionFixture(
-      manifest.projectId,
-      'runnable-r1',
-      1,
-    );
+    const first = runnableVersionFixture(manifest.projectId, 'runnable-r1', 1);
     const second = runnableVersionFixture(
       manifest.projectId,
       'runnable-r2',
@@ -2017,23 +2013,25 @@ export function registerProjectWorkbenchFoundationTests() {
     const secondLaunch = new Promise((resolve) => {
       resolveSecondLaunch = resolve;
     });
-    const invoke = vi.fn(async (command: string, args?: Record<string, unknown>) => {
-      if (command !== 'launch_local_game_runnable_version') {
-        throw new Error(`unexpected invoke ${command}`);
-      }
-      if (args?.versionId === first.versionId) {
-        return {
-          manifest,
-          version: first,
-          preview: {
-            url: 'http://127.0.0.1:4101',
-            port: 4101,
-            root: '/tmp/workbench-version-switch',
-          },
-        };
-      }
-      return secondLaunch;
-    });
+    const invoke = vi.fn(
+      async (command: string, args?: Record<string, unknown>) => {
+        if (command !== 'launch_local_game_runnable_version') {
+          throw new Error(`unexpected invoke ${command}`);
+        }
+        if (args?.versionId === first.versionId) {
+          return {
+            manifest,
+            version: first,
+            preview: {
+              url: 'http://127.0.0.1:4101',
+              port: 4101,
+              root: '/tmp/workbench-version-switch',
+            },
+          };
+        }
+        return secondLaunch;
+      },
+    );
     window.__TAURI__ = { core: { invoke } };
 
     function StatefulWorkbench() {
@@ -2059,9 +2057,7 @@ export function registerProjectWorkbenchFoundationTests() {
     fireEvent.click(screen.getByRole('tab', { name: '运行' }));
     await waitFor(() => {
       expect(
-        screen
-          .getByTitle('版本切换测试 游戏运行画面')
-          .getAttribute('src'),
+        screen.getByTitle('版本切换测试 游戏运行画面').getAttribute('src'),
       ).toBe('http://127.0.0.1:4101/');
     });
 
@@ -2070,14 +2066,11 @@ export function registerProjectWorkbenchFoundationTests() {
     });
     expect(screen.queryByTitle('版本切换测试 游戏运行画面')).toBeNull();
     expect(screen.getByText('正在切换可运行版本')).not.toBeNull();
-    expect(invoke).toHaveBeenCalledWith(
-      'launch_local_game_runnable_version',
-      {
-        projectPath: '/tmp/workbench-version-switch',
-        expectedProjectId: manifest.projectId,
-        versionId: second.versionId,
-      },
-    );
+    expect(invoke).toHaveBeenCalledWith('launch_local_game_runnable_version', {
+      projectPath: '/tmp/workbench-version-switch',
+      expectedProjectId: manifest.projectId,
+      versionId: second.versionId,
+    });
 
     const switchedManifest = {
       ...manifest,
@@ -2102,9 +2095,7 @@ export function registerProjectWorkbenchFoundationTests() {
     });
     await waitFor(() => {
       expect(
-        screen
-          .getByTitle('版本切换测试 游戏运行画面')
-          .getAttribute('src'),
+        screen.getByTitle('版本切换测试 游戏运行画面').getAttribute('src'),
       ).toBe('http://127.0.0.1:4102/');
     });
   });
@@ -2258,6 +2249,289 @@ export function registerProjectWorkbenchFoundationTests() {
     expect(screen.getByText('starting')).not.toBeNull();
   });
 
+  it('runs formal P4 slices and resolves P5 hover IDs from trusted version metadata', async () => {
+    const manifest = createGameCreationAppManifest(
+      'workbench-slices',
+      '切片与悬停测试',
+    );
+    manifest.assets.push({
+      id: 'hero-art',
+      kind: 'character',
+      mediaType: 'image/png',
+      localPath: 'assets/hero.png',
+      source: {
+        kind: 'generated',
+        referenceResourceIds: [],
+      },
+    });
+    const version = runnableVersionFixture(
+      manifest.projectId,
+      'runnable-r12',
+      12,
+      {
+        resourceBindings: [{ slotId: 'hero', resourceId: 'hero-art' }],
+        resourceDescriptors: [
+          {
+            resourceId: 'hero-art',
+            name: 'hero.png',
+            category: 'art',
+            subtype: 'character',
+            width: 128,
+            height: 256,
+            format: 'image/png',
+          },
+        ],
+        testSlices: [
+          {
+            sliceId: 'core',
+            versionId: 'runnable-r12',
+            title: '核心玩法',
+            order: 0,
+            startCondition: '游戏 ready',
+            endCondition: '核心循环结束',
+            status: 'idle',
+          },
+          {
+            sliceId: 'boss',
+            versionId: 'runnable-r12',
+            title: '首领战',
+            order: 1,
+            startCondition: '进入首领关',
+            endCondition: '首领战结束',
+            status: 'idle',
+          },
+        ],
+      },
+    );
+    manifest.runnableVersions = [version];
+    manifest.currentRunnableVersionId = version.versionId;
+    const previewIdentity = {
+      previewId: 'preview-slices-1',
+      origin: 'http://127.0.0.1:4299',
+    };
+    manifest.preview = {
+      status: 'running',
+      url: `${previewIdentity.origin}/`,
+      port: 4299,
+    };
+    const invoke = vi.fn(async () => ({
+      manifest,
+      version,
+      preview: {
+        url: `${previewIdentity.origin}/`,
+        port: 4299,
+        root: '/tmp/workbench-slices',
+      },
+      previewIdentity,
+    }));
+    window.__TAURI__ = { core: { invoke } };
+
+    render(
+      React.createElement(ProjectDevelopmentView, {
+        projectName: manifest.name,
+        projectPath: '/tmp/workbench-slices',
+        manifest,
+        attachments: [],
+        recentRunStatus: null,
+        recentRunStopReason: null,
+        supervisor: React.createElement('div', null, '项目总控'),
+        onHomeOpen: vi.fn(),
+        onProjectsOpen: vi.fn(),
+      }),
+    );
+    fireEvent.click(screen.getByRole('tab', { name: '运行' }));
+    const iframe = (await screen.findByTitle(
+      '切片与悬停测试 游戏运行画面',
+    )) as HTMLIFrameElement;
+    const frameWindow = iframe.contentWindow;
+    if (!frameWindow) {
+      throw new Error('missing iframe contentWindow');
+    }
+    const postMessage = vi.spyOn(frameWindow, 'postMessage');
+    fireEvent.load(iframe);
+    const start = postMessage.mock.calls[0]?.[0] as Record<string, unknown>;
+    await act(async () => {
+      window.dispatchEvent(
+        new MessageEvent('message', {
+          data: {
+            schemaVersion: 'game-creator-runtime-message.v1',
+            protocolVersion: 'game-creator-run-bridge.v1',
+            requestId: 'runtime-ready-slices',
+            responseTo: start.requestId,
+            sessionId: start.sessionId,
+            previewId: start.previewId,
+            projectId: start.projectId,
+            sequence: 1,
+            type: 'runtime.ready',
+            versionId: start.versionId,
+            projectRevision: start.projectRevision,
+            payload: { capabilities: ['state', 'slice', 'inspection'] },
+          },
+          origin: previewIdentity.origin,
+          source: frameWindow,
+        }),
+      );
+      await Promise.resolve();
+    });
+
+    expect(
+      (screen.getByRole('button', { name: '上一项' }) as HTMLButtonElement)
+        .disabled,
+    ).toBe(true);
+    fireEvent.click(screen.getByRole('button', { name: '播放测试切片' }));
+    const sliceStart = postMessage.mock.calls.at(-1)?.[0] as Record<
+      string,
+      unknown
+    >;
+    expect(sliceStart).toMatchObject({
+      type: 'host.slice.start',
+      payload: { sliceId: 'core' },
+    });
+    await act(async () => {
+      for (const data of [
+        {
+          requestId: 'runtime-slice-playing',
+          responseTo: sliceStart.requestId,
+          sequence: 2,
+          type: 'runtime.slice',
+          payload: {
+            sliceId: 'core',
+            title: '游戏伪造标题',
+            status: 'playing',
+          },
+        },
+        {
+          requestId: 'runtime-hover-resource',
+          sequence: 3,
+          type: 'runtime.inspection',
+          payload: {
+            inspectionId: 'hover-resource',
+            label: '伪造资源名称',
+            metrics: { name: 'fake.png' },
+            targetKind: 'resource',
+            targetId: 'hero-art',
+          },
+        },
+      ]) {
+        window.dispatchEvent(
+          new MessageEvent('message', {
+            data: {
+              schemaVersion: 'game-creator-runtime-message.v1',
+              protocolVersion: 'game-creator-run-bridge.v1',
+              sessionId: start.sessionId,
+              previewId: start.previewId,
+              projectId: start.projectId,
+              versionId: start.versionId,
+              projectRevision: start.projectRevision,
+              ...data,
+            },
+            origin: previewIdentity.origin,
+            source: frameWindow,
+          }),
+        );
+      }
+      await Promise.resolve();
+    });
+    expect(screen.getByLabelText('测试切片控件').textContent).toContain(
+      '核心玩法 · playing',
+    );
+    const resourceInfo = screen.getByLabelText('悬停资源信息');
+    expect(resourceInfo.textContent).toContain('hero.png');
+    expect(resourceInfo.textContent).toContain('128 × 256');
+    expect(resourceInfo.textContent).not.toContain('fake.png');
+
+    fireEvent.click(screen.getByRole('button', { name: '下一项' }));
+    const switchMessages = postMessage.mock.calls
+      .slice(-2)
+      .map(([message]) => message as Record<string, unknown>);
+    expect(switchMessages).toMatchObject([
+      { type: 'host.slice.stop', payload: { sliceId: 'core' } },
+      { type: 'host.slice.start', payload: { sliceId: 'boss' } },
+    ]);
+    expect(screen.getByLabelText('测试切片控件').textContent).toContain(
+      '首领战 · starting',
+    );
+    expect(resourceInfo.textContent).toContain('暂无悬停资源');
+    expect(
+      (screen.getByRole('button', { name: '下一项' }) as HTMLButtonElement)
+        .disabled,
+    ).toBe(true);
+
+    await act(async () => {
+      for (const [sequence, status] of [
+        [4, 'playing'],
+        [5, 'completed'],
+      ] as const) {
+        window.dispatchEvent(
+          new MessageEvent('message', {
+            data: {
+              schemaVersion: 'game-creator-runtime-message.v1',
+              protocolVersion: 'game-creator-run-bridge.v1',
+              requestId: `runtime-boss-${status}`,
+              sessionId: start.sessionId,
+              previewId: start.previewId,
+              projectId: start.projectId,
+              sequence,
+              type: 'runtime.slice',
+              versionId: start.versionId,
+              projectRevision: start.projectRevision,
+              payload: { sliceId: 'boss', title: '伪造标题', status },
+            },
+            origin: previewIdentity.origin,
+            source: frameWindow,
+          }),
+        );
+      }
+      await Promise.resolve();
+    });
+    expect(screen.getByLabelText('测试切片控件').textContent).toContain(
+      '首领战 · completed',
+    );
+    expect(screen.getByLabelText('运行会话信息').textContent).toContain(
+      'paused',
+    );
+
+    await act(async () => {
+      window.dispatchEvent(
+        new MessageEvent('message', {
+          data: {
+            schemaVersion: 'game-creator-runtime-message.v1',
+            protocolVersion: 'game-creator-run-bridge.v1',
+            requestId: 'runtime-hover-resource-after-complete',
+            sessionId: start.sessionId,
+            previewId: start.previewId,
+            projectId: start.projectId,
+            sequence: 6,
+            type: 'runtime.inspection',
+            versionId: start.versionId,
+            projectRevision: start.projectRevision,
+            payload: {
+              inspectionId: 'hover-resource',
+              label: '伪造资源名称',
+              metrics: {},
+              targetKind: 'resource',
+              targetId: 'hero-art',
+            },
+          },
+          origin: previewIdentity.origin,
+          source: frameWindow,
+        }),
+      );
+      await Promise.resolve();
+    });
+    fireEvent.click(screen.getByRole('button', { name: '在资源管理中定位' }));
+    expect(
+      screen
+        .getByRole('tab', { name: '资源管理' })
+        .getAttribute('aria-selected'),
+    ).toBe('true');
+    expect(
+      screen
+        .getByRole('button', { name: /hero\.png/u })
+        .getAttribute('aria-pressed'),
+    ).toBe('true');
+  });
+
   it('shows a precise runnable version launch failure without embedding a preview', async () => {
     const manifest = createGameCreationAppManifest(
       'workbench-version-failure',
diff --git a/apps/ai-game-creator-shell/tests/gameRunBridge.test.ts b/apps/ai-game-creator-shell/tests/gameRunBridge.test.ts
index 40bc09c1b..2f457b3a7 100644
--- a/apps/ai-game-creator-shell/tests/gameRunBridge.test.ts
+++ b/apps/ai-game-creator-shell/tests/gameRunBridge.test.ts
@@ -55,6 +55,19 @@ describe('P3 Game Run Bridge', () => {
       type: 'host.start',
     });
 
+    const sliceStart = createGameHostMessage({
+      identity,
+      sessionId: 'session-1',
+      requestId: 'host-request-slice',
+      sequence: 2,
+      type: 'host.slice.start',
+      payload: { sliceId: 'core-gameplay' },
+    });
+    expect(sliceStart).toMatchObject({
+      type: 'host.slice.start',
+      payload: { sliceId: 'core-gameplay' },
+    });
+
     const guard = new GameRunBridgeRuntimeGuard(identity, 'session-1');
     expect(guard.registerHostRequest(host.requestId, host.type)).toBe(true);
     expect(guard.accept(runtimeMessage())).toEqual(runtimeMessage());
@@ -122,6 +135,15 @@ describe('P3 Game Run Bridge', () => {
           metrics: { filePath: '/tmp/secret' },
         },
       },
+      {
+        type: 'runtime.inspection',
+        payload: {
+          inspectionId: 'inspection-1',
+          label: '运行画面',
+          metrics: {},
+          targetKind: 'resource',
+        },
+      },
       {
         type: 'runtime.inspection',
         payload: {
diff --git a/apps/ai-game-creator-shell/tests/gameTestSliceModel.test.ts b/apps/ai-game-creator-shell/tests/gameTestSliceModel.test.ts
new file mode 100644
index 000000000..5415cb93b
--- /dev/null
+++ b/apps/ai-game-creator-shell/tests/gameTestSliceModel.test.ts
@@ -0,0 +1,226 @@
+import { describe, expect, it } from 'vitest';
+
+import type {
+  GameRuntimeMessage,
+  RunnableGameVersion,
+} from '../../../../packages/shared/src/contracts/gameCreationApp';
+import {
+  beginGameTestSlice,
+  formalGameTestSlices,
+  projectGameTestSliceMessage,
+  projectGameTestSliceSessionStatus,
+  trustedInspectionFromRuntimeMessage,
+} from '../src/features/project-workspace/gameTestSliceModel';
+
+const version: RunnableGameVersion = {
+  schemaVersion: 'game-creator-runnable-version.v1',
+  versionId: 'runnable-r7',
+  projectId: 'project-1',
+  parentVersionId: null,
+  projectRevision: 7,
+  artifactPath: '.agent/runnable-versions/runnable-r7/artifact',
+  artifactSha256: 'a'.repeat(64),
+  entryPath: 'game/index.html',
+  resourceBindings: [{ slotId: 'hero', resourceId: 'hero-art' }],
+  testSlices: [
+    {
+      sliceId: 'boss',
+      versionId: 'runnable-r7',
+      title: '首领战',
+      order: 2,
+      startCondition: '进入首领关',
+      endCondition: '首领战结束',
+      status: 'idle',
+    },
+    {
+      sliceId: 'core',
+      versionId: 'runnable-r7',
+      title: '核心玩法',
+      order: 1,
+      startCondition: '游戏 ready',
+      endCondition: '核心循环结束',
+      status: 'idle',
+    },
+  ],
+  resourceDescriptors: [
+    {
+      resourceId: 'hero-art',
+      name: 'hero.png',
+      category: 'art',
+      subtype: 'character',
+      width: 128,
+      height: 256,
+      format: 'image/png',
+    },
+  ],
+  createdReason: 'initial',
+  validation: {
+    staticSmokePassed: true,
+    previewValidatePassed: true,
+    playtestPassed: true,
+    agentId: 'program-agent',
+    runId: 'run-7',
+    reportPath:
+      '.agent/runtime/browser-validations/program-agent/run-7/1/validation.json',
+  },
+  createdAt: 700,
+};
+
+function runtimeMessage(
+  type: GameRuntimeMessage['type'],
+  payload: GameRuntimeMessage['payload'],
+): GameRuntimeMessage {
+  return {
+    schemaVersion: 'game-creator-runtime-message.v1',
+    protocolVersion: 'game-creator-run-bridge.v1',
+    requestId: `request-${type}`,
+    sessionId: 'session-1',
+    previewId: 'preview-1',
+    projectId: version.projectId,
+    sequence: 1,
+    type,
+    versionId: version.versionId,
+    projectRevision: version.projectRevision,
+    payload,
+  } as GameRuntimeMessage;
+}
+
+describe('P4/P5 game runtime models', () => {
+  it('uses only valid finite version-owned slices and enforces state transitions', () => {
+    const slices = formalGameTestSlices(version);
+    expect(slices.map((slice) => slice.sliceId)).toEqual(['core', 'boss']);
+    const starting = beginGameTestSlice(slices[0]);
+    const playing = projectGameTestSliceMessage(
+      starting,
+      runtimeMessage('runtime.slice', {
+        sliceId: 'core',
+        title: '不可信标题',
+        status: 'playing',
+      }),
+    );
+    expect(playing?.status).toBe('playing');
+    const completed = projectGameTestSliceMessage(
+      playing,
+      runtimeMessage('runtime.slice', {
+        sliceId: 'core',
+        title: '任意标题',
+        status: 'completed',
+      }),
+    );
+    expect(completed?.status).toBe('completed');
+    expect(
+      projectGameTestSliceMessage(
+        completed,
+        runtimeMessage('runtime.slice', {
+          sliceId: 'core',
+          title: '任意标题',
+          status: 'playing',
+        }),
+      )?.status,
+    ).toBe('completed');
+  });
+
+  it('rejects invalid version slice identities instead of inventing a fallback', () => {
+    expect(
+      formalGameTestSlices({
+        ...version,
+        testSlices: [{ ...version.testSlices![0], versionId: 'other' }],
+      }),
+    ).toEqual([]);
+    expect(formalGameTestSlices({ ...version, testSlices: undefined })).toEqual(
+      [],
+    );
+    expect(
+      formalGameTestSlices({
+        ...version,
+        testSlices: version.testSlices!.map((slice) => ({
+          ...slice,
+          order: 1,
+        })),
+      }),
+    ).toEqual([]);
+    expect(
+      formalGameTestSlices({
+        ...version,
+        testSlices: [{ ...version.testSlices![0], status: 'playing' }],
+      }),
+    ).toEqual([]);
+  });
+
+  it('projects only legal pause and resume transitions from the run session', () => {
+    const playing = projectGameTestSliceMessage(
+      beginGameTestSlice(formalGameTestSlices(version)[0]),
+      runtimeMessage('runtime.slice', {
+        sliceId: 'core',
+        title: '',
+        status: 'playing',
+      }),
+    );
+    const paused = projectGameTestSliceSessionStatus(
+      playing,
+      runtimeMessage('runtime.state', { status: 'paused' }),
+    );
+    expect(paused?.status).toBe('paused');
+    expect(
+      projectGameTestSliceSessionStatus(
+        paused,
+        runtimeMessage('runtime.state', { status: 'playing' }),
+      )?.status,
+    ).toBe('playing');
+  });
+
+  it('resolves hover IDs only through the current version binding and descriptor', () => {
+    const resolved = trustedInspectionFromRuntimeMessage(
+      version,
+      runtimeMessage('runtime.inspection', {
+        inspectionId: 'hover-resource',
+        label: '伪造名称',
+        metrics: { name: '伪造资源' },
+        targetKind: 'resource',
+        targetId: 'hero-art',
+      }),
+    );
+    expect(resolved).toMatchObject({
+      name: 'hero.png',
+      resourceId: 'hero-art',
+      slotId: 'hero',
+      width: 128,
+      height: 256,
+    });
+    expect(
+      trustedInspectionFromRuntimeMessage(
+        version,
+        runtimeMessage('runtime.inspection', {
+          inspectionId: 'hover-entity',
+          label: '',
+          metrics: {},
+          targetKind: 'entity',
+          targetId: 'hero',
+        }),
+      ),
+    ).toMatchObject({ resourceId: 'hero-art', slotId: 'hero' });
+    expect(
+      trustedInspectionFromRuntimeMessage(
+        version,
+        runtimeMessage('runtime.inspection', {
+          inspectionId: 'hover-unbound',
+          label: '伪造名称',
+          metrics: {},
+          targetKind: 'resource',
+          targetId: 'unbound',
+        }),
+      ),
+    ).toBeNull();
+    expect(
+      trustedInspectionFromRuntimeMessage(
+        version,
+        runtimeMessage('runtime.inspection', {
+          inspectionId: 'hover-clear',
+          label: '',
+          metrics: {},
+          targetKind: 'none',
+        }),
+      ),
+    ).toBeNull();
+  });
+});
diff --git a/docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md b/docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md
index 54044c472..3c059d67e 100644
--- a/docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md
+++ b/docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md
@@ -320,6 +320,8 @@ type RunnableGameVersion = {
   artifactSha256: string;
   entryPath: 'game/index.html';
   resourceBindings: Array<{ slotId: string; resourceId: string }>;
+  testSlices: GameTestSlice[];
+  resourceDescriptors: GameResourceDescriptor[];
   createdReason: 'initial' | 'agent-revision';
   validation: {
     staticSmokePassed: true;
@@ -403,9 +405,12 @@ type GameHostMessage = {
     | 'host.resume'
     | 'host.stop'
     | 'host.state.request'
-    | 'host.inspection.request';
+    | 'host.inspection.request'
+    | 'host.slice.start'
+    | 'host.slice.stop';
   versionId: string;
   projectRevision: number;
+  payload?: { sliceId: string };
 };
 
 type GameRuntimeMessage = {
@@ -437,7 +442,16 @@ type GameRuntimeMessage = {
 - 预览服务在响应 HTML 时只注入宿主拥有的同源 `game-creator-run-bridge.v1` bootstrap，不修改不可变版本快照字节或摘要。bootstrap 为旧可运行版本提供 ready/state/pause/resume/stop 基线，并向游戏暴露仅能上报上述五类安全消息的 API；权限和安全结论始终由宿主校验，不信任游戏脚本自报。
 - revision 不一致继续表示编辑工作树已经晚于当前 Session 绑定版本；Session 标记 `stale`，但不热更新、不改写旧版本，也不把 stale 当失败。本次不实现 P2 资源替换与下一版本，也不实现测试切片编排、参数写入或数值面板；`runtime.slice` 只是 P3 传输层的安全上报能力。
 
-### 5.6 Agent 泥点归因（P2）
+### 5.6 正式测试切片与可信悬停信息（P4 / P5）
+
+- `RunnableGameVersion.testSlices` 与 `resourceDescriptors` 在版本登记时由可信 Rust 随不可变快照一并冻结；旧版本字段缺失时按空列表读取，不允许前端或游戏运行时补造正式切片或资源元数据。切片 ID、顺序和标题只信任版本合同，`runtime.slice` 的同名字段只能用于身份匹配与状态上报。
+- `testSlices` 最多 64 项，`sliceId` 和 `order` 在版本内唯一，全部 `versionId` 必须等于所属版本，状态初始固定为 `idle`。宿主按 `order -> sliceId` 排序，首末项分别禁用上一项 / 下一项。
+- 切片状态机固定为 `idle -> starting -> playing <-> paused -> completed`，并允许 `starting / playing / paused -> failed`。切换前先发送 `host.slice.stop` 安全终止当前切片，再以 `host.slice.start` 启动目标切片；版本、项目、preview 或 iframe 身份变化时清空运行态。`runtime.slice completed` 自动把运行会话投影到暂停态。
+- `stale` 是宿主根据项目 / 版本身份变化投影的只读状态；stale 会话不得继续切片控制，只允许重新拉起。P4 不写参数、不修改代码、不创建新版本，也不消费 P2 资源替换。
+- P5 不读取 iframe DOM。游戏捕获可检查对象 hover 后，只能通过 `runtime.inspection` 上报 `targetKind=resource|entity` 与稳定 `targetId`；离开对象上报 `targetKind=none`。宿主只在当前版本 `resourceBindings` 中把 resource ID 或实体 slot ID 解析到 `resourceDescriptors`，匹配后展示可信名称、类别 / 格式、尺寸规格、所属版本和绑定槽位，并仅在该资源仍存在于当前资源画布时提供“在资源管理中定位”按钮；定位会停止当前一次性运行会话、清除筛选并选中对应资源卡。未匹配、离开对象、切换切片或会话失效时清空信息。
+- 游戏上报的 label、summary 和 metrics 仍是不可信提示，不能覆盖宿主资源元数据，也不能触发 Tauri、文件、命令、Agent、生成或资源替换能力。
+
+### 5.7 Agent 泥点归因（P2）
 
 ```ts
 type ProjectAgentMudPointAttribution = {
@@ -479,6 +493,16 @@ type ProjectAgentMudPointAttribution = {
 - 接入 host-owned 同源 bootstrap，使当前正式可运行版本可以完成 ready/state 基线握手，并为游戏提供受限上报 API。
 - 覆盖来源窗口、origin、全身份、协议、消息类型、payload、容量、顺序、重载、切换和停止负向测试。
 
+### P4
+
+- 从当前不可变可运行版本读取正式切片列表，完成上一项 / 播放暂停 / 下一项控制与严格状态机。
+- 切片完成自动暂停；切换、版本 / 项目变化、iframe reload 与 stale 会话安全清理运行态。
+
+### P5
+
+- 游戏只上报稳定实体 / 资源 ID，宿主只用当前版本绑定与资源描述解析可信信息。
+- 离开对象、切换切片、版本 / preview / session 变化时清空信息；不读取跨 origin DOM，不信任游戏展示内容。
+
 ## 7. 验收
 
 ### 7.1 P0 验收
@@ -539,9 +563,18 @@ type ProjectAgentMudPointAttribution = {
 5. 预览响应注入的 bootstrap 不修改快照文件或摘要；旧版本至少完成 ready/playing 基线握手，pause/resume/stop 与 state/inspection request 均按 requestId 回应。
 6. 本阶段不出现资源替换、新版本写入、测试切片控件、数值微调面板或任何游戏触发的 Tauri/文件/命令能力。
 
+### 7.7 P4 / P5 运行测试与信息验收
+
+1. 切片列表只来自当前 `RunnableGameVersion.testSlices`，稳定 ID、唯一有限顺序与版本归属不合法时版本合同拒绝；空列表不伪造默认切片。
+2. 首项禁用上一项、末项禁用下一项；切换先 stop 当前项再 start 目标项，completed 自动暂停，failed 和 stale 不得继续执行控制。
+3. 切换版本、项目、preview、iframe reload 或返回资源管理时，切片运行态与悬停信息全部清空，迟到消息不能复活旧状态。
+4. `runtime.inspection` 只有目标 ID 命中当前版本绑定表并能解析当前版本资源描述时才展示信息；游戏自报 label、summary、metric 文本不得进入可信资源字段。
+5. 信息面板首版展示资源名称、类别 / 格式、尺寸规格、所属版本和绑定位置；资源仍存在于资源画布时可停止当前运行会话并一键定位对应资源卡；离开对象或上报未绑定 ID 时清空。
+6. P4 / P5 全程不写参数、不修改代码、不创建下一版本、不实现资源替换，也不让游戏消息触发任何宿主副作用。
+
 ## 8. 非目标
 
-- 当前收口不实现资源卡手动拖动，也不实现资源聚焦工具栏、资源聚焦工具侧边栏、美术编辑、音频编辑 / 替换、资源重新生成、资源替换、手动创建版本或版本回滚。P1 实现运行版本登记、选择、切换和运行态消费；P3 只实现运行会话与 Host/Game Bridge，测试切片编排、数值参数和泥点归因仍不在本次范围。
+- 当前收口不实现资源卡手动拖动，也不实现资源聚焦工具栏、资源聚焦工具侧边栏、美术编辑、音频编辑 / 替换、资源重新生成、资源替换、手动创建版本或版本回滚。P1 已实现运行版本登记、选择、切换和运行态消费，P3 已实现运行会话与 Host/Game Bridge，P4 / P5 已实现正式测试切片和可信悬停信息；P2 的资源替换、下一版本、数值参数写入、自然语言新增微调项和泥点归因仍不在本次范围。
 - 本切片不持久化资源聚焦状态、画布缩放 / 平移、搜索条件、筛选条件或当前 mode；聚焦退出时的列表上下文恢复只限当前前端会话，这些状态如需跨重启保存必须另行扩展合同，不能塞入 `game-creator-resource-layout.v1`。
 - 不修改 SpacetimeDB schema。
 - 不开放普通用户 Agent.md/Skill。
diff --git a/docs/project-memory/shared-memory/decision-log.md b/docs/project-memory/shared-memory/decision-log.md
index 1ad8fcd41..78b790cdd 100644
--- a/docs/project-memory/shared-memory/decision-log.md
+++ b/docs/project-memory/shared-memory/decision-log.md
@@ -1,5 +1,14 @@
 # 决策记录
 
+## 2026-08-04 工作台 P4/P5 以不可变版本合同驱动正式切片与可信悬停信息
+
+- 背景：P0/P1 已建立不可变可运行版本，P3 已建立一次性 Host/Game Bridge；运行页仍缺少来自正式合同的测试切片控制和不读取 iframe DOM 的游戏内悬停信息。本轮按需求明确跳过 P2，不能借切片或信息面板加入资源替换、参数写入、代码修改或下一版本创建。
+- 决策：`RunnableGameVersion` 在可信 Rust 登记时冻结可选 `testSlices` 与 `resourceDescriptors`，旧版本缺字段按空列表处理且不补造默认切片。正式切片由已通过的 playtest 场景确定，Host 仅通过 `{ sliceId }` 白名单发送 `host.slice.start / host.slice.stop`，前端按有限状态机投影一次性状态；切换、版本 / 项目 / preview / iframe 身份变化立即归零，completed 投影为暂停。
+- 悬停信任边界：游戏只上报 `targetKind=resource|entity|none` 与稳定 `targetId`。宿主只用当前版本 `resourceBindings` 和 `resourceDescriptors` 解析名称、类别 / 格式、尺寸、版本与绑定槽位，游戏自报 label、summary、metrics 不得覆盖可信字段。定位按钮只在资源仍存在于当前 read model 时启用，并在停止当前运行会话后切回资源管理、清除筛选并选中对应资源卡。
+- P2 边界：不实现资源替换、数值参数写入、自然语言新增微调项、代码修改、泥点归因或下一版本；合法游戏消息继续不能触发 Tauri、文件、命令、Agent 或生成副作用。
+- 验证方式：共享 Rust 合同覆盖切片身份 / 顺序 / 初态和未绑定描述拒绝；Tauri 覆盖场景切片冻结、资源描述登记及 bootstrap API；TypeScript 模型 / Bridge 覆盖状态迁移、消息白名单和可信 ID 解析；AppSurface 覆盖首末控制、stop→start、completed 暂停、伪造元数据拒绝与资源定位，并运行 shell typecheck、编码检查和 `git diff --check`。
+- 关联文档：`docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md`、`docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md`。
+
 ## 2026-08-04 工作台 P3 在正式可运行预览上建立一次性 Host/Game Bridge
 
 - 背景：P0/P1 已用不可变快照和专用启动命令建立正式可运行版本，但运行 iframe 仍没有可验证的会话身份、消息顺序、请求关联和 reload 后失效语义；飞书需求同时明确本次跳过 P2 资源替换，只实现 P3 底层运行桥。
diff --git a/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md b/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md
index 9a54a6a88..637185889 100644
--- a/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md
+++ b/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md
@@ -434,6 +434,14 @@ game-project/
 - 工作台显示真实 session 状态并提供 pause/resume；ready 之前保持 starting，error 进入 failed，runtime state 只按白名单状态推进。`runtime.slice` 与 `runtime.inspection` 作为安全传输与展示投影存在，不等于已实现 P2 测试切片流程、检查工具或数值编辑。
 - 定向门禁覆盖 Rust Registry 身份轮换和 HTML/bootstrap 响应；TypeScript 纯协议覆盖白名单、容量、身份、sequence、request 关联与危险 payload；AppSurface 覆盖真实 iframe source/origin、reload/session 失效、版本切换卸载和 UI 状态。最后运行 shared-contracts、Tauri project/preview、AGC typecheck、定向 Vitest、编码检查与 `git diff --check`。
 
+### 正式测试切片与可信悬停信息 P4 / P5
+
+- 可运行版本登记时把当前正式 playtest 场景投影为有限、稳定、初始 `idle` 的 `testSlices`，同时把当前资源绑定对应的名称、类别、subtype、格式和可验证尺寸冻结为 `resourceDescriptors`；两者进入不可变版本记录，旧版本缺失时按空列表读取，不由前端或 iframe 补造。
+- Host Bridge 增加带 `{ sliceId }` 白名单 payload 的 `host.slice.start / host.slice.stop`。bootstrap 只做协议校验、受限事件转发和 `runtime.slice` 基线响应；真实游戏可以通过同源 `genarrative:host-message` 消费切片命令，并用受限桥 API 上报 completed / failed。Host 只接受当前合同中的切片 ID 和合法状态迁移。
+- 工作台控制条使用当前版本的正式切片顺序。切换先 stop 后 start；completed 自动暂停；failed、stale、身份漂移或 reload 后控制失效。切片状态属于一次性前端运行会话，不写 manifest。
+- P5 继续禁止宿主读取 iframe DOM。游戏在自身 hit-test / hover 逻辑中仅上报 `targetKind=resource|entity|none` 和稳定 `targetId`；宿主按当前版本 `resourceBindings` 的 resourceId / slotId 解析 `resourceDescriptors`，只展示宿主可信元数据。匹配资源仍存在于当前资源 read model 时，定位按钮先停止并失效当前运行会话，再清除资源筛选、切回资源管理并选中对应资源卡；未命中、离开对象、切片切换和会话失效立即清空。
+- 该阶段不实现 P2：不写数值、不修改代码、不替换资源、不追加资源替换版本，也不允许消息触发 Tauri、文件、命令、Agent 或生成。
+
 历史命令式 drag preview 句柄与局部连接索引可以保留，但项目工作台不再向资源卡传入该入口。拖动热路径、4096 张真实卡片拖动重渲染和 Chromium p95 门槛统一暂缓；当前回归只要求 Pointer Move 不改变卡片坐标、SVG path 或布局 revision。`ResizeObserver` 仍保持单图层单实例，任何实时 DOM 几何都不得通过 Tauri IPC 往返 Rust。
 
 ## 分阶段实施
diff --git a/packages/shared/src/contracts/gameCreationApp.ts b/packages/shared/src/contracts/gameCreationApp.ts
index 0c405865c..dc7b3386f 100644
--- a/packages/shared/src/contracts/gameCreationApp.ts
+++ b/packages/shared/src/contracts/gameCreationApp.ts
@@ -580,6 +580,8 @@ export interface RunnableGameVersion {
   artifactSha256: string;
   entryPath: 'game/index.html';
   resourceBindings: GameIterationVersionResourceBinding[];
+  testSlices?: GameTestSlice[];
+  resourceDescriptors?: GameResourceDescriptor[];
   createdReason: RunnableGameVersionCreatedReason;
   validation: RunnableGameVersionValidation;
   createdAt: number;
@@ -633,6 +635,7 @@ export interface GameTunableParameterDefinition {
 
 export interface GameResourceDescriptor {
   resourceId: string;
+  name: string;
   category: 'document' | 'version' | 'art' | 'audio';
   subtype: string;
   width?: number;
@@ -655,7 +658,13 @@ export type GameHostMessageType =
   | 'host.resume'
   | 'host.stop'
   | 'host.state.request'
-  | 'host.inspection.request';
+  | 'host.inspection.request'
+  | 'host.slice.start'
+  | 'host.slice.stop';
+
+export interface GameHostSlicePayload {
+  sliceId: string;
+}
 
 export interface GameHostMessage {
   schemaVersion: 'game-creator-host-message.v1';
@@ -668,6 +677,7 @@ export interface GameHostMessage {
   type: GameHostMessageType;
   versionId: string;
   projectRevision: number;
+  payload?: GameHostSlicePayload;
 }
 
 export type GameRuntimeCapability = 'state' | 'slice' | 'inspection';
@@ -701,6 +711,8 @@ export interface GameRuntimeInspectionPayload {
   label: string;
   summary?: string;
   metrics: Record<string, GameRuntimeInspectionMetric>;
+  targetKind?: 'resource' | 'entity' | 'none';
+  targetId?: string;
 }
 
 interface GameRuntimeMessageBase {
diff --git a/server-rs/crates/shared-contracts/src/game_creation_app.rs b/server-rs/crates/shared-contracts/src/game_creation_app.rs
index c7bfb95a2..77fe2a83c 100644
--- a/server-rs/crates/shared-contracts/src/game_creation_app.rs
+++ b/server-rs/crates/shared-contracts/src/game_creation_app.rs
@@ -614,6 +614,7 @@ pub struct GameCreationAppCommandRunState {
 pub const GAME_ITERATION_VERSION_MAX_COUNT: usize = 4096;
 pub const GAME_ITERATION_VERSION_MAX_BINDING_COUNT: usize = 4096;
 pub const GAME_ITERATION_VERSION_MAX_SAFE_INTEGER: u64 = 9_007_199_254_740_991;
+pub const GAME_RUNNABLE_VERSION_MAX_TEST_SLICES: usize = 64;
 
 #[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
 #[serde(rename_all = "kebab-case")]
@@ -673,6 +674,10 @@ pub struct RunnableGameVersion {
     pub artifact_sha256: String,
     pub entry_path: String,
     pub resource_bindings: Vec<GameIterationVersionResourceBinding>,
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub test_slices: Vec<GameTestSlice>,
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub resource_descriptors: Vec<GameResourceDescriptor>,
     pub created_reason: RunnableGameVersionCreatedReason,
     pub validation: RunnableGameVersionValidation,
     pub created_at: u64,
@@ -803,6 +808,7 @@ pub enum GameResourceCategory {
 #[serde(rename_all = "camelCase")]
 pub struct GameResourceDescriptor {
     pub resource_id: String,
+    pub name: String,
     pub category: GameResourceCategory,
     pub subtype: String,
     #[serde(default, skip_serializing_if = "Option::is_none")]
@@ -828,6 +834,10 @@ pub enum GameHostMessageType {
     HostStateRequest,
     #[serde(rename = "host.inspection.request")]
     HostInspectionRequest,
+    #[serde(rename = "host.slice.start")]
+    HostSliceStart,
+    #[serde(rename = "host.slice.stop")]
+    HostSliceStop,
 }
 
 #[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
@@ -844,6 +854,8 @@ pub struct GameHostMessage {
     pub message_type: GameHostMessageType,
     pub version_id: String,
     pub project_revision: u64,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub payload: Option<serde_json::Value>,
 }
 
 #[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
@@ -1093,6 +1105,7 @@ pub fn validate_runnable_game_versions(
             return Err(format!("可运行版本 {} 的资源绑定过多", version.version_id));
         }
         let mut slot_ids = HashSet::new();
+        let mut bound_resource_ids = HashSet::new();
         for binding in &version.resource_bindings {
             validate_iteration_version_id(&binding.slot_id, "可运行版本资源槽位 ID", 256)?;
             validate_iteration_version_id(&binding.resource_id, "可运行版本资源 ID", 512)?;
@@ -1102,6 +1115,70 @@ pub fn validate_runnable_game_versions(
                     version.version_id, binding.slot_id
                 ));
             }
+            bound_resource_ids.insert(binding.resource_id.as_str());
+        }
+        if version.test_slices.len() > GAME_RUNNABLE_VERSION_MAX_TEST_SLICES {
+            return Err(format!(
+                "可运行版本 {} 的测试切片最多支持 {GAME_RUNNABLE_VERSION_MAX_TEST_SLICES} 项",
+                version.version_id
+            ));
+        }
+        let mut slice_ids = HashSet::new();
+        let mut slice_orders = HashSet::new();
+        for slice in &version.test_slices {
+            validate_iteration_version_id(&slice.slice_id, "测试切片 ID", 128)?;
+            validate_iteration_version_id(&slice.title, "测试切片标题", 128)?;
+            validate_iteration_version_id(&slice.start_condition, "测试切片开始条件", 512)?;
+            validate_iteration_version_id(&slice.end_condition, "测试切片结束条件", 512)?;
+            if slice.version_id != version.version_id {
+                return Err(format!(
+                    "可运行版本 {} 的测试切片版本身份不一致：{}",
+                    version.version_id, slice.slice_id
+                ));
+            }
+            if slice.status != GameTestSliceStatus::Idle {
+                return Err(format!(
+                    "可运行版本 {} 的测试切片必须以 idle 登记：{}",
+                    version.version_id, slice.slice_id
+                ));
+            }
+            if !slice_ids.insert(slice.slice_id.as_str()) || !slice_orders.insert(slice.order) {
+                return Err(format!(
+                    "可运行版本 {} 的测试切片 ID 或顺序重复",
+                    version.version_id
+                ));
+            }
+        }
+        if version.resource_descriptors.len() > GAME_ITERATION_VERSION_MAX_BINDING_COUNT {
+            return Err(format!("可运行版本 {} 的资源描述过多", version.version_id));
+        }
+        let mut descriptor_ids = HashSet::new();
+        for descriptor in &version.resource_descriptors {
+            validate_iteration_version_id(&descriptor.resource_id, "资源描述 ID", 512)?;
+            validate_iteration_version_id(&descriptor.name, "资源名称", 256)?;
+            validate_iteration_version_id(&descriptor.subtype, "资源 subtype", 128)?;
+            validate_iteration_version_id(&descriptor.format, "资源格式", 128)?;
+            if !bound_resource_ids.contains(descriptor.resource_id.as_str()) {
+                return Err(format!(
+                    "可运行版本 {} 的资源描述未绑定：{}",
+                    version.version_id, descriptor.resource_id
+                ));
+            }
+            if !descriptor_ids.insert(descriptor.resource_id.as_str()) {
+                return Err(format!(
+                    "可运行版本 {} 的资源描述重复：{}",
+                    version.version_id, descriptor.resource_id
+                ));
+            }
+            if descriptor.width == Some(0)
+                || descriptor.height == Some(0)
+                || descriptor.duration_ms == Some(0)
+            {
+                return Err(format!(
+                    "可运行版本 {} 的资源尺寸规格无效：{}",
+                    version.version_id, descriptor.resource_id
+                ));
+            }
         }
         previous_versions.insert(
             version.version_id.as_str(),
@@ -2339,6 +2416,25 @@ mod tests {
                 slot_id: "player".to_string(),
                 resource_id: "asset-player".to_string(),
             }],
+            test_slices: vec![GameTestSlice {
+                slice_id: "core-gameplay".to_string(),
+                version_id: version_id.to_string(),
+                title: "核心玩法".to_string(),
+                order: 0,
+                start_condition: "游戏进入 ready".to_string(),
+                end_condition: "游戏进入 won 或 lost".to_string(),
+                status: GameTestSliceStatus::Idle,
+            }],
+            resource_descriptors: vec![GameResourceDescriptor {
+                resource_id: "asset-player".to_string(),
+                name: "player.png".to_string(),
+                category: GameResourceCategory::Art,
+                subtype: "character".to_string(),
+                width: Some(128),
+                height: Some(128),
+                duration_ms: None,
+                format: "image/png".to_string(),
+            }],
             created_reason,
             validation: RunnableGameVersionValidation {
                 static_smoke_passed: true,
@@ -2410,6 +2506,58 @@ mod tests {
         );
     }
 
+    #[test]
+    fn runnable_versions_reject_invalid_formal_slices_and_unbound_descriptors() {
+        let version = runnable_version_fixture(
+            "runnable-r1",
+            None,
+            1,
+            RunnableGameVersionCreatedReason::Initial,
+        );
+
+        let mut wrong_version = version.clone();
+        wrong_version.test_slices[0].version_id = "runnable-r2".to_string();
+        assert!(validate_runnable_game_versions(
+            "project-runnable",
+            &[wrong_version],
+            Some("runnable-r1")
+        )
+        .expect_err("reject a slice owned by another version")
+        .contains("测试切片版本身份不一致"));
+
+        let mut duplicate_order = version.clone();
+        let mut second_slice = duplicate_order.test_slices[0].clone();
+        second_slice.slice_id = "boss".to_string();
+        duplicate_order.test_slices.push(second_slice);
+        assert!(validate_runnable_game_versions(
+            "project-runnable",
+            &[duplicate_order],
+            Some("runnable-r1")
+        )
+        .expect_err("reject duplicate slice order")
+        .contains("测试切片 ID 或顺序重复"));
+
+        let mut active_at_registration = version.clone();
+        active_at_registration.test_slices[0].status = GameTestSliceStatus::Playing;
+        assert!(validate_runnable_game_versions(
+            "project-runnable",
+            &[active_at_registration],
+            Some("runnable-r1")
+        )
+        .expect_err("reject a non-idle registered slice")
+        .contains("必须以 idle 登记"));
+
+        let mut unbound_descriptor = version;
+        unbound_descriptor.resource_descriptors[0].resource_id = "unbound".to_string();
+        assert!(validate_runnable_game_versions(
+            "project-runnable",
+            &[unbound_descriptor],
+            Some("runnable-r1")
+        )
+        .expect_err("reject an unbound trusted descriptor")
+        .contains("资源描述未绑定"));
+    }
+
     #[test]
     fn workbench_p3_message_types_keep_the_frozen_wire_values() {
         let host = GameHostMessage {
@@ -2423,6 +2571,7 @@ mod tests {
             message_type: GameHostMessageType::HostStart,
             version_id: "runnable-r7".to_string(),
             project_revision: 7,
+            payload: None,
         };
         assert_eq!(
             serde_json::to_value(host).expect("serialize host message"),
-- 
2.52.0


From 3ec3a09380d9a54a83b321960786907022c1b187 Mon Sep 17 00:00:00 2001
From: menghao <mh18530625731@163.com>
Date: Tue, 4 Aug 2026 18:38:41 +0800
Subject: [PATCH 22/27] =?UTF-8?q?=E5=AE=8C=E6=88=90=E6=B8=B8=E6=88=8F?=
 =?UTF-8?q?=E5=B7=A5=E4=BD=9C=E5=8F=B0=E8=B5=84=E6=BA=90=E6=9B=BF=E6=8D=A2?=
 =?UTF-8?q?=E4=B8=8E=E6=95=B0=E5=80=BC=E5=BE=AE=E8=B0=83?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

实现可信资源规格校验与不可变资源替换子版本
新增登记参数读取、暂停态写入和会话失效链路
补齐前后端合同、生成产物约束与回归测试
同步工作台 PRD、技术方案和共享决策记录
---
 .../src/agent/runtime_driver/task_start.rs    |    7 +-
 .../runtime_protocol/autonomous_completion.rs |    6 +-
 .../autonomous_completion_contract_tests.rs   |   10 +
 .../src-tauri/src/commands.rs                 |   55 +
 .../src-tauri/src/main.rs                     |    8 +-
 .../src/project/runnable_versions.rs          | 1072 ++++++++++++++++-
 .../LocalGamePreviewFrame.tsx                 |   69 +-
 apps/ai-game-creator-shell/src/styles.css     |  141 ++-
 .../src/view/project-development/index.tsx    |  567 ++++++++-
 .../appSurface/project-development.suite.ts   |  379 +++++-
 ...AI游戏创作】项目开发工作台PRD-2026-07-20.md |   40 +-
 .../shared-memory/decision-log.md             |    9 +
 ...�案】AI游戏创作智能体App实施计划-2026-06-24.md |   15 +-
 .../shared/src/contracts/gameCreationApp.ts   |   30 +-
 .../shared-contracts/src/game_creation_app.rs |  160 ++-
 15 files changed, 2436 insertions(+), 132 deletions(-)

diff --git a/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_driver/task_start.rs b/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_driver/task_start.rs
index de06e0c84..f757827a8 100644
--- a/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_driver/task_start.rs
+++ b/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_driver/task_start.rs
@@ -1417,8 +1417,13 @@ pub(in crate::agent) fn render_autonomous_manifest_ready_task_background_prompt(
         } else {
             ""
         };
+        let code_tunable_parameter_requirement = if task.id == "code-prototype" {
+            " 数值微调合同固定为 game/tunable-parameters.json 与 game/tunable-values.json。注册表 schemaVersion 必须为 game-creator-tunable-parameters.v1，parameters 最多 128 项；每项包含稳定 parameterId、label、valueType、defaultValue、currentValue、可选 min/max/step/enumValues/unit、固定 writePath=game/tunable-values.json#/values/<parameterId>、effectMode=next-relaunch、editablePhase=paused、codeMutationAllowed=false。值文件 schemaVersion 必须为 game-creator-tunable-values.v1，values 只包含已登记 parameterId。只登记当前游戏确实读取的少量数值；game/index.html 必须在每次新启动时读取值文件并应用，运行中的 iframe 不得监听或热写该文件。"
+        } else {
+            ""
+        };
         let owner_prompt = format!(
-            "{base}\n\n这是 autonomous-game-build 的正式 owner 写入任务。必须实际生成并写入非空正式产物：{paths}；JSON 文件必须是可解析 JSON，code-prototype 的 game/index.html 不能沿用初始化占位。{publish_package_requirement}任务声明中的视觉图片继续按现有 visual gate 生成、登记并验收。完成修改后按当前 run 的验证门完成验证并直接交付结论；不要调用 task.update，Runtime 会在子 Run 终态后幂等投影 manifest。"
+            "{base}\n\n这是 autonomous-game-build 的正式 owner 写入任务。必须实际生成并写入非空正式产物：{paths}；JSON 文件必须是可解析 JSON，code-prototype 的 game/index.html 不能沿用初始化占位。{publish_package_requirement}{code_tunable_parameter_requirement}任务声明中的视觉图片继续按现有 visual gate 生成、登记并验收。完成修改后按当前 run 的验证门完成验证并直接交付结论；不要调用 task.update，Runtime 会在子 Run 终态后幂等投影 manifest。"
         );
         return format!("{owner_prompt}{code_visual_asset_requirement}");
     }
diff --git a/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_protocol/autonomous_completion.rs b/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_protocol/autonomous_completion.rs
index 38d5906ce..2fc23de6b 100644
--- a/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_protocol/autonomous_completion.rs
+++ b/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_protocol/autonomous_completion.rs
@@ -43,7 +43,11 @@ pub(in crate::agent) fn autonomous_manifest_owner_artifact_paths(
         "balance-seed" => &["game/balance.json"],
         "art-asset-plan" => &["assets/manifest.art.json"],
         "audio-asset-plan" => &["assets/manifest.audio.json"],
-        "code-prototype" => &[AGENT_RUNTIME_GAME_INDEX_PATH],
+        "code-prototype" => &[
+            AGENT_RUNTIME_GAME_INDEX_PATH,
+            "game/tunable-parameters.json",
+            "game/tunable-values.json",
+        ],
         "publish-package" => &["exports/README.md"],
         _ => &[],
     }
diff --git a/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_protocol/autonomous_completion_contract_tests.rs b/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_protocol/autonomous_completion_contract_tests.rs
index 60fea7d14..023c7585d 100644
--- a/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_protocol/autonomous_completion_contract_tests.rs
+++ b/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_protocol/autonomous_completion_contract_tests.rs
@@ -265,6 +265,16 @@ fn prepare_completed_autonomous_manifest_fixture(root: &Path) {
     .expect("write game design fixture");
     fs::write(root.join("game/balance.json"), br#"{"lives":3,"speed":1}"#)
         .expect("write balance fixture");
+    fs::write(
+        root.join("game/tunable-parameters.json"),
+        br#"{"schemaVersion":"game-creator-tunable-parameters.v1","parameters":[]}"#,
+    )
+    .expect("write tunable parameter registry fixture");
+    fs::write(
+        root.join("game/tunable-values.json"),
+        br#"{"schemaVersion":"game-creator-tunable-values.v1","values":{}}"#,
+    )
+    .expect("write tunable parameter values fixture");
     fs::write(
         root.join("assets/manifest.art.json"),
         br#"{"assets":["art-spritesheet.png"]}"#,
diff --git a/apps/ai-game-creator-shell/src-tauri/src/commands.rs b/apps/ai-game-creator-shell/src-tauri/src/commands.rs
index bff274d4b..8dcd02e21 100644
--- a/apps/ai-game-creator-shell/src-tauri/src/commands.rs
+++ b/apps/ai-game-creator-shell/src-tauri/src/commands.rs
@@ -996,6 +996,61 @@ pub(crate) fn register_local_asset(
     )
 }
 
+#[tauri::command]
+pub(crate) fn replace_local_game_runnable_resource(
+    project_path: String,
+    expected_project_id: String,
+    parent_version_id: String,
+    slot_id: String,
+    replacement_resource_id: String,
+    expected_project_revision: u64,
+) -> Result<ReplaceRunnableGameResourceResult, String> {
+    let root = Path::new(project_path.trim());
+    enforce_project_permission_policy(root, "file.write")?;
+    let _lock = acquire_project_write_lock(root, "runnable.resource_replace")?;
+    replace_runnable_game_resource_at(
+        root,
+        expected_project_id.trim(),
+        parent_version_id.trim(),
+        slot_id.trim(),
+        replacement_resource_id.trim(),
+        expected_project_revision,
+    )
+}
+
+#[tauri::command]
+pub(crate) fn read_local_game_tunable_parameters(
+    project_path: String,
+    expected_project_id: String,
+    version_id: String,
+) -> Result<GameTunableParametersReadModel, String> {
+    let root = Path::new(project_path.trim());
+    enforce_project_permission_policy(root, "file.read")?;
+    read_game_tunable_parameters_at(root, expected_project_id.trim(), version_id.trim())
+}
+
+#[tauri::command]
+pub(crate) fn update_local_game_tunable_parameter(
+    project_path: String,
+    expected_project_id: String,
+    version_id: String,
+    parameter_id: String,
+    value: serde_json::Value,
+    expected_project_revision: u64,
+) -> Result<UpdateGameTunableParameterResult, String> {
+    let root = Path::new(project_path.trim());
+    enforce_project_permission_policy(root, "file.write")?;
+    let _lock = acquire_project_write_lock(root, "tunable.update")?;
+    update_game_tunable_parameter_at(
+        root,
+        expected_project_id.trim(),
+        version_id.trim(),
+        parameter_id.trim(),
+        value,
+        expected_project_revision,
+    )
+}
+
 #[tauri::command]
 pub(crate) fn import_canvas_asset(
     project_path: String,
diff --git a/apps/ai-game-creator-shell/src-tauri/src/main.rs b/apps/ai-game-creator-shell/src-tauri/src/main.rs
index de08aaffd..45b87763c 100644
--- a/apps/ai-game-creator-shell/src-tauri/src/main.rs
+++ b/apps/ai-game-creator-shell/src-tauri/src/main.rs
@@ -33,8 +33,9 @@ use shared_contracts::game_creation_app::{
     GameCreationAppManifest, GameCreationAppPermission, GameCreationAppPreviewState,
     GameCreationAppPreviewStatus, GameCreationAppTaskState, GameCreationAppTaskStatus,
     GameIterationVersionResourceBinding, GameResourceCategory, GameResourceDescriptor,
-    GameTestSlice, GameTestSliceStatus, ProjectResourceCanvasLayout,
-    ProjectResourceCanvasLayoutMode, ProjectResourceCanvasPosition, RunnableGameVersion,
+    GameTestSlice, GameTestSliceStatus, GameTunableParameterDefinition,
+    GameTunableParameterValueType, ProjectResourceCanvasLayout, ProjectResourceCanvasLayoutMode,
+    ProjectResourceCanvasPosition, RunnableGameResourceReplacement, RunnableGameVersion,
     RunnableGameVersionCreatedReason, RunnableGameVersionValidation,
     UpdateProjectResourceCanvasLayoutResult, UpdateProjectResourceCanvasLayoutStatus,
     GAME_CREATION_AGENT_CAPABILITIES, GAME_CREATION_AGENT_RUN_SCHEMA_VERSION,
@@ -2360,6 +2361,9 @@ fn main() {
             read_game_creator_mcp_catalog,
             upload_local_asset,
             register_local_asset,
+            replace_local_game_runnable_resource,
+            read_local_game_tunable_parameters,
+            update_local_game_tunable_parameter,
             import_canvas_asset,
             import_canvas_export,
             sync_canvas_project_assets,
diff --git a/apps/ai-game-creator-shell/src-tauri/src/project/runnable_versions.rs b/apps/ai-game-creator-shell/src-tauri/src/project/runnable_versions.rs
index a4a62fedd..0a24b4fae 100644
--- a/apps/ai-game-creator-shell/src-tauri/src/project/runnable_versions.rs
+++ b/apps/ai-game-creator-shell/src-tauri/src/project/runnable_versions.rs
@@ -4,6 +4,12 @@ const RUNNABLE_ARTIFACT_DESCRIPTOR_SCHEMA_VERSION: &str = "game-creator-runnable
 const RUNNABLE_ARTIFACT_MAX_FILES: usize = 4_096;
 const RUNNABLE_ARTIFACT_MAX_FILE_BYTES: u64 = 64 * 1024 * 1024;
 const RUNNABLE_ARTIFACT_MAX_TOTAL_BYTES: u64 = 512 * 1024 * 1024;
+const TUNABLE_PARAMETER_REGISTRY_SCHEMA_VERSION: &str = "game-creator-tunable-parameters.v1";
+const TUNABLE_PARAMETER_VALUES_SCHEMA_VERSION: &str = "game-creator-tunable-values.v1";
+const TUNABLE_PARAMETER_REGISTRY_PATH: &str = "game/tunable-parameters.json";
+const TUNABLE_PARAMETER_VALUES_PATH: &str = "game/tunable-values.json";
+const TUNABLE_PARAMETER_MAX_COUNT: usize = 128;
+const TUNABLE_PARAMETER_FILE_MAX_BYTES: u64 = 256 * 1024;
 
 #[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
 #[serde(deny_unknown_fields, rename_all = "camelCase")]
@@ -22,6 +28,42 @@ struct WrittenRunnableArtifactSnapshot {
     created_at: u64,
 }
 
+#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
+#[serde(deny_unknown_fields, rename_all = "camelCase")]
+struct TunableParameterRegistryFile {
+    schema_version: String,
+    parameters: Vec<GameTunableParameterDefinition>,
+}
+
+#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
+#[serde(deny_unknown_fields, rename_all = "camelCase")]
+struct TunableParameterValuesFile {
+    schema_version: String,
+    values: BTreeMap<String, serde_json::Value>,
+}
+
+#[derive(Clone, Debug, PartialEq, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub(crate) struct GameTunableParametersReadModel {
+    pub(crate) version_id: String,
+    pub(crate) project_revision: u64,
+    pub(crate) parameters: Vec<GameTunableParameterDefinition>,
+}
+
+#[derive(Clone, Debug, PartialEq, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub(crate) struct UpdateGameTunableParameterResult {
+    pub(crate) revision: u64,
+    pub(crate) parameters: Vec<GameTunableParameterDefinition>,
+}
+
+#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub(crate) struct ReplaceRunnableGameResourceResult {
+    pub(crate) manifest: GameCreationAppManifest,
+    pub(crate) version: RunnableGameVersion,
+}
+
 fn runnable_version_id(revision: u64) -> String {
     format!("runnable-r{revision}")
 }
@@ -145,51 +187,129 @@ fn runnable_resource_descriptors(
     manifest
         .assets
         .iter()
-        .filter_map(|asset| {
-            let category =
-                runnable_resource_category(&asset.media_type, &asset.kind, &asset.local_path)?;
-            let (width, height) = if asset.media_type.starts_with("image/") {
-                normalize_relative_path(&asset.local_path)
-                    .ok()
-                    .and_then(|relative| resolve_local_project_path(root, &relative).ok())
-                    .and_then(|path| {
-                        let metadata = fs::metadata(&path).ok()?;
-                        if !metadata.is_file() || metadata.len() > RUNNABLE_ARTIFACT_MAX_FILE_BYTES
-                        {
-                            return None;
-                        }
-                        fs::read(path).ok()
-                    })
-                    .and_then(|bytes| {
-                        image::ImageReader::new(std::io::Cursor::new(bytes))
-                            .with_guessed_format()
-                            .ok()?
-                            .into_dimensions()
-                            .ok()
-                    })
-                    .map_or((None, None), |(width, height)| (Some(width), Some(height)))
-            } else {
-                (None, None)
-            };
-            let name = Path::new(&asset.local_path)
-                .file_name()
-                .and_then(|value| value.to_str())
-                .unwrap_or(asset.id.as_str())
-                .to_string();
-            Some(GameResourceDescriptor {
-                resource_id: asset.id.clone(),
-                name,
-                category,
-                subtype: asset.kind.clone(),
-                width,
-                height,
-                duration_ms: None,
-                format: asset.media_type.clone(),
-            })
-        })
+        .filter_map(|asset| runnable_resource_descriptor(root, asset))
         .collect()
 }
 
+fn runnable_resource_descriptor(
+    root: &Path,
+    asset: &GameCreationAppAssetManifestEntry,
+) -> Option<GameResourceDescriptor> {
+    let category = runnable_resource_category(&asset.media_type, &asset.kind, &asset.local_path)?;
+    let bytes = normalize_relative_path(&asset.local_path)
+        .ok()
+        .and_then(|relative| resolve_local_project_path(root, &relative).ok())
+        .and_then(|path| {
+            let metadata = fs::metadata(&path).ok()?;
+            if !metadata.is_file() || metadata.len() > RUNNABLE_ARTIFACT_MAX_FILE_BYTES {
+                return None;
+            }
+            fs::read(path).ok()
+        });
+    let (width, height) = if asset.media_type.starts_with("image/") {
+        bytes
+            .as_deref()
+            .and_then(|bytes| {
+                image::ImageReader::new(std::io::Cursor::new(bytes))
+                    .with_guessed_format()
+                    .ok()?
+                    .into_dimensions()
+                    .ok()
+            })
+            .map_or((None, None), |(width, height)| (Some(width), Some(height)))
+    } else {
+        (None, None)
+    };
+    let audio_spec = if category == GameResourceCategory::Audio {
+        bytes.as_deref().and_then(parse_wav_size_spec)
+    } else {
+        None
+    };
+    let name = Path::new(&asset.local_path)
+        .file_name()
+        .and_then(|value| value.to_str())
+        .unwrap_or(asset.id.as_str())
+        .to_string();
+    Some(GameResourceDescriptor {
+        resource_id: asset.id.clone(),
+        name,
+        category,
+        subtype: asset.kind.clone(),
+        width,
+        height,
+        duration_ms: audio_spec.as_ref().map(|spec| spec.duration_ms),
+        channel_count: audio_spec.as_ref().map(|spec| spec.channel_count),
+        sample_rate_hz: audio_spec.as_ref().map(|spec| spec.sample_rate_hz),
+        codec: audio_spec.map(|spec| spec.codec),
+        format: asset.media_type.clone(),
+    })
+}
+
+#[derive(Clone, Debug, Eq, PartialEq)]
+struct WavSizeSpec {
+    channel_count: u16,
+    sample_rate_hz: u32,
+    duration_ms: u64,
+    codec: String,
+}
+
+fn parse_wav_size_spec(bytes: &[u8]) -> Option<WavSizeSpec> {
+    if bytes.len() < 12 || &bytes[..4] != b"RIFF" || &bytes[8..12] != b"WAVE" {
+        return None;
+    }
+    let mut offset = 12usize;
+    let mut format = None;
+    let mut data_bytes = None;
+    while offset.checked_add(8)? <= bytes.len() {
+        let chunk_id = &bytes[offset..offset + 4];
+        let chunk_len = u32::from_le_bytes(bytes[offset + 4..offset + 8].try_into().ok()?) as usize;
+        let content_start = offset.checked_add(8)?;
+        let content_end = content_start.checked_add(chunk_len)?;
+        if content_end > bytes.len() {
+            return None;
+        }
+        if chunk_id == b"fmt " && chunk_len >= 16 {
+            let audio_format =
+                u16::from_le_bytes(bytes[content_start..content_start + 2].try_into().ok()?);
+            let channel_count = u16::from_le_bytes(
+                bytes[content_start + 2..content_start + 4]
+                    .try_into()
+                    .ok()?,
+            );
+            let sample_rate_hz = u32::from_le_bytes(
+                bytes[content_start + 4..content_start + 8]
+                    .try_into()
+                    .ok()?,
+            );
+            let byte_rate = u32::from_le_bytes(
+                bytes[content_start + 8..content_start + 12]
+                    .try_into()
+                    .ok()?,
+            );
+            if channel_count == 0 || sample_rate_hz == 0 || byte_rate == 0 {
+                return None;
+            }
+            let codec = match audio_format {
+                1 => "pcm".to_string(),
+                3 => "ieee-float".to_string(),
+                value => format!("wav-format-{value}"),
+            };
+            format = Some((channel_count, sample_rate_hz, byte_rate, codec));
+        } else if chunk_id == b"data" {
+            data_bytes = Some(chunk_len as u64);
+        }
+        offset = content_end.checked_add(chunk_len % 2)?;
+    }
+    let (channel_count, sample_rate_hz, byte_rate, codec) = format?;
+    let duration_ms = data_bytes?.checked_mul(1_000)? / u64::from(byte_rate);
+    Some(WavSizeSpec {
+        channel_count,
+        sample_rate_hz,
+        duration_ms,
+        codec,
+    })
+}
+
 fn collect_runnable_artifact_files(
     base: &Path,
     directory: &Path,
@@ -309,6 +429,19 @@ fn write_runnable_artifact_snapshot(
     created_at: u64,
 ) -> Result<WrittenRunnableArtifactSnapshot, String> {
     let files = read_runnable_artifact_files(root)?;
+    write_runnable_artifact_snapshot_from_files(
+        root, project_id, version_id, revision, created_at, files,
+    )
+}
+
+fn write_runnable_artifact_snapshot_from_files(
+    root: &Path,
+    project_id: &str,
+    version_id: &str,
+    revision: u64,
+    created_at: u64,
+    files: Vec<(String, Vec<u8>)>,
+) -> Result<WrittenRunnableArtifactSnapshot, String> {
     if !files.iter().any(|(path, _)| path == "game/index.html") {
         return Err("项目完整性检查失败：缺少 game/index.html".to_string());
     }
@@ -463,6 +596,13 @@ pub(crate) fn register_current_runnable_game_version_at(
     {
         return Err("可运行版本 revision 必须严格递增".to_string());
     }
+    if root.join(TUNABLE_PARAMETER_REGISTRY_PATH).exists()
+        || root.join(TUNABLE_PARAMETER_VALUES_PATH).exists()
+    {
+        let mut definitions = read_tunable_parameter_registry(root)?;
+        let values = read_editable_tunable_values(root)?;
+        overlay_editable_tunable_values(&mut definitions, values.as_ref())?;
+    }
     let version_id = runnable_version_id(revision);
     let created_at = unix_timestamp_millis();
     let snapshot = write_runnable_artifact_snapshot(
@@ -505,6 +645,7 @@ pub(crate) fn register_current_runnable_game_version_at(
         resource_bindings,
         test_slices,
         resource_descriptors,
+        resource_replacement: None,
         created_reason,
         validation: RunnableGameVersionValidation {
             static_smoke_passed: true,
@@ -569,6 +710,544 @@ pub(crate) fn resolve_runnable_game_version_at(
     Ok((manifest, version, artifact_root))
 }
 
+fn compatible_resource_size_spec(
+    previous: &GameResourceDescriptor,
+    replacement: &GameResourceDescriptor,
+) -> bool {
+    if previous.format != replacement.format {
+        return false;
+    }
+    match previous.category {
+        GameResourceCategory::Art if previous.format.starts_with("image/") => {
+            previous.width.is_some()
+                && previous.height.is_some()
+                && previous.width == replacement.width
+                && previous.height == replacement.height
+        }
+        GameResourceCategory::Art => {
+            previous.width.is_some()
+                && previous.height.is_some()
+                && previous.codec.is_some()
+                && previous.width == replacement.width
+                && previous.height == replacement.height
+                && previous.codec == replacement.codec
+        }
+        GameResourceCategory::Audio => {
+            previous.duration_ms.is_some()
+                && previous.channel_count.is_some()
+                && previous.sample_rate_hz.is_some()
+                && previous.codec.is_some()
+                && previous.duration_ms == replacement.duration_ms
+                && previous.channel_count == replacement.channel_count
+                && previous.sample_rate_hz == replacement.sample_rate_hz
+                && previous.codec == replacement.codec
+        }
+        GameResourceCategory::Document | GameResourceCategory::Version => false,
+    }
+}
+
+fn read_manifest_asset_bytes(
+    root: &Path,
+    asset: &GameCreationAppAssetManifestEntry,
+) -> Result<Vec<u8>, String> {
+    let relative =
+        normalize_relative_path(&asset.local_path).map_err(|_| "候选资源路径无效".to_string())?;
+    let path = resolve_local_project_path(root, &relative)?;
+    let metadata = fs::symlink_metadata(&path).map_err(|_| "候选资源不存在".to_string())?;
+    if metadata.file_type().is_symlink() || !metadata.is_file() {
+        return Err("候选资源必须是项目内普通文件".to_string());
+    }
+    if metadata.len() > RUNNABLE_ARTIFACT_MAX_FILE_BYTES {
+        return Err("候选资源文件大小超过限制".to_string());
+    }
+    read_runnable_source_file(&path, metadata.len())
+        .map_err(|_| "候选资源读取期间发生变化".to_string())
+}
+
+pub(crate) fn replace_runnable_game_resource_at(
+    root: &Path,
+    expected_project_id: &str,
+    parent_version_id: &str,
+    slot_id: &str,
+    replacement_resource_id: &str,
+    expected_project_revision: u64,
+) -> Result<ReplaceRunnableGameResourceResult, String> {
+    let manifest_path = root.join(".agent/manifest.json");
+    let mut manifest = read_manifest(&manifest_path)?;
+    if manifest.project_id != expected_project_id {
+        return Err("资源替换项目身份不一致".to_string());
+    }
+    if manifest.current_runnable_version_id.as_deref() != Some(parent_version_id) {
+        return Err("只能从当前可运行版本发起资源替换".to_string());
+    }
+    let current_revision = read_game_creator_agent_runtime_project_revision(root)?.revision;
+    if current_revision != expected_project_revision {
+        return Err("项目 revision 已变化，请重新选择资源后再试".to_string());
+    }
+    let parent = manifest
+        .runnable_versions
+        .iter()
+        .find(|version| version.version_id == parent_version_id)
+        .cloned()
+        .ok_or_else(|| "资源替换父版本不存在".to_string())?;
+    let parent_artifact = validate_runnable_game_version_artifact_at(root, &parent)?;
+    let previous_binding = parent
+        .resource_bindings
+        .iter()
+        .find(|binding| binding.slot_id == slot_id)
+        .cloned()
+        .ok_or_else(|| "当前版本不存在该资源绑定槽位".to_string())?;
+    if previous_binding.resource_id == replacement_resource_id {
+        return Err("候选资源与当前资源相同".to_string());
+    }
+    let previous_asset = manifest
+        .assets
+        .iter()
+        .find(|asset| asset.id == previous_binding.resource_id)
+        .cloned()
+        .ok_or_else(|| "替换前资源已不在当前项目清单中".to_string())?;
+    let replacement_asset = manifest
+        .assets
+        .iter()
+        .find(|asset| asset.id == replacement_resource_id)
+        .cloned()
+        .ok_or_else(|| "候选资源未登记在当前项目清单中".to_string())?;
+    let previous_descriptor = parent
+        .resource_descriptors
+        .iter()
+        .find(|descriptor| descriptor.resource_id == previous_binding.resource_id)
+        .cloned()
+        .ok_or_else(|| "当前版本缺少替换前资源的可信元数据".to_string())?;
+    let replacement_descriptor = runnable_resource_descriptor(root, &replacement_asset)
+        .ok_or_else(|| "候选资源类型不支持正式替换".to_string())?;
+    if !matches!(
+        previous_descriptor.category,
+        GameResourceCategory::Art | GameResourceCategory::Audio
+    ) {
+        return Err("当前仅支持替换美术或音乐音效资源".to_string());
+    }
+    if previous_descriptor.category != replacement_descriptor.category
+        || previous_descriptor.subtype != replacement_descriptor.subtype
+        || !compatible_resource_size_spec(&previous_descriptor, &replacement_descriptor)
+    {
+        return Err("资源类型不一致，无法替换（类别、subtype 或尺寸规格不匹配）".to_string());
+    }
+    let previous_path = normalize_relative_path(&previous_asset.local_path)
+        .map_err(|_| "替换前资源路径无效".to_string())?;
+    if !previous_path.starts_with("assets/") {
+        return Err("替换前资源不属于可替换的 assets 产物".to_string());
+    }
+    let replacement_bytes = read_manifest_asset_bytes(root, &replacement_asset)?;
+    let mut files = read_runnable_artifact_files(&parent_artifact)?;
+    let Some((_, previous_bytes)) = files.iter_mut().find(|(path, _)| path == &previous_path)
+    else {
+        return Err("父版本快照中不存在替换前资源文件".to_string());
+    };
+    *previous_bytes = replacement_bytes;
+
+    let next_revision = advance_agent_runtime_project_revision_locked(root)?;
+    let version_id = runnable_version_id(next_revision);
+    if manifest
+        .runnable_versions
+        .iter()
+        .any(|version| version.version_id == version_id)
+    {
+        return Err("资源替换目标版本身份已存在".to_string());
+    }
+    let created_at = unix_timestamp_millis();
+    let snapshot = write_runnable_artifact_snapshot_from_files(
+        root,
+        &manifest.project_id,
+        &version_id,
+        next_revision,
+        created_at,
+        files,
+    )?;
+    let mut resource_bindings = parent.resource_bindings.clone();
+    let binding = resource_bindings
+        .iter_mut()
+        .find(|binding| binding.slot_id == slot_id)
+        .ok_or_else(|| "资源替换槽位在提交前消失".to_string())?;
+    binding.resource_id = replacement_resource_id.to_string();
+    let retained_resource_ids = resource_bindings
+        .iter()
+        .map(|binding| binding.resource_id.as_str())
+        .collect::<std::collections::HashSet<_>>();
+    let mut resource_descriptors = parent
+        .resource_descriptors
+        .iter()
+        .filter(|descriptor| retained_resource_ids.contains(descriptor.resource_id.as_str()))
+        .cloned()
+        .collect::<Vec<_>>();
+    if !resource_descriptors
+        .iter()
+        .any(|descriptor| descriptor.resource_id == replacement_descriptor.resource_id)
+    {
+        resource_descriptors.push(replacement_descriptor);
+    }
+    resource_descriptors.sort_by(|left, right| left.resource_id.cmp(&right.resource_id));
+    let test_slices = parent
+        .test_slices
+        .iter()
+        .cloned()
+        .map(|mut slice| {
+            slice.version_id = version_id.clone();
+            slice.status = GameTestSliceStatus::Idle;
+            slice
+        })
+        .collect();
+    let version = RunnableGameVersion {
+        schema_version: RUNNABLE_GAME_VERSION_SCHEMA_VERSION.to_string(),
+        version_id: version_id.clone(),
+        project_id: manifest.project_id.clone(),
+        parent_version_id: Some(parent.version_id.clone()),
+        project_revision: next_revision,
+        artifact_path: format!(".agent/runnable-versions/{version_id}/artifact"),
+        artifact_sha256: snapshot.artifact_sha256,
+        entry_path: "game/index.html".to_string(),
+        resource_bindings,
+        test_slices,
+        resource_descriptors,
+        resource_replacement: Some(RunnableGameResourceReplacement {
+            slot_id: slot_id.to_string(),
+            previous_resource_id: previous_binding.resource_id,
+            replacement_resource_id: replacement_resource_id.to_string(),
+        }),
+        created_reason: RunnableGameVersionCreatedReason::ResourceReplacement,
+        validation: parent.validation,
+        created_at: snapshot.created_at,
+    };
+    manifest.runnable_versions.push(version.clone());
+    write_manifest(&manifest_path, &manifest)?;
+    let _ = append_agent_db_record(
+        root,
+        serde_json::json!({
+            "recordType": "project.runnable_version.resource_replaced",
+            "versionId": version.version_id,
+            "parentVersionId": version.parent_version_id,
+            "projectRevision": version.project_revision,
+            "slotId": slot_id,
+            "previousResourceId": version.resource_replacement.as_ref().map(|value| &value.previous_resource_id),
+            "replacementResourceId": replacement_resource_id,
+        }),
+    );
+    Ok(ReplaceRunnableGameResourceResult { manifest, version })
+}
+
+fn valid_tunable_parameter_id(value: &str) -> bool {
+    !value.is_empty()
+        && value.len() <= 128
+        && value
+            .bytes()
+            .all(|byte| byte.is_ascii_alphanumeric() || matches!(byte, b'.' | b'_' | b'-'))
+}
+
+fn validate_tunable_value(
+    definition: &GameTunableParameterDefinition,
+    value: &serde_json::Value,
+) -> Result<(), String> {
+    match definition.value_type {
+        GameTunableParameterValueType::Boolean => {
+            if !value.is_boolean() {
+                return Err("参数值必须是布尔值".to_string());
+            }
+        }
+        GameTunableParameterValueType::Enum => {
+            let candidate = value
+                .as_str()
+                .ok_or_else(|| "枚举参数值必须是字符串".to_string())?;
+            if !definition
+                .enum_values
+                .as_ref()
+                .is_some_and(|values| values.iter().any(|value| value == candidate))
+            {
+                return Err("枚举参数值不在允许列表中".to_string());
+            }
+        }
+        GameTunableParameterValueType::Integer | GameTunableParameterValueType::Number => {
+            let number = value
+                .as_f64()
+                .filter(|number| number.is_finite())
+                .ok_or_else(|| "数值参数必须是有限数字".to_string())?;
+            if definition.value_type == GameTunableParameterValueType::Integer
+                && number.fract() != 0.0
+            {
+                return Err("整数参数不能包含小数".to_string());
+            }
+            if definition.min.is_some_and(|min| number < min)
+                || definition.max.is_some_and(|max| number > max)
+            {
+                return Err("参数值超出允许范围".to_string());
+            }
+            if let Some(step) = definition.step {
+                let base = definition.min.unwrap_or(0.0);
+                let steps = (number - base) / step;
+                if (steps - steps.round()).abs() > 1e-8 {
+                    return Err("参数值不符合步长约束".to_string());
+                }
+            }
+        }
+    }
+    Ok(())
+}
+
+fn validate_tunable_definition(definition: &GameTunableParameterDefinition) -> Result<(), String> {
+    if !valid_tunable_parameter_id(&definition.parameter_id)
+        || definition.label.trim().is_empty()
+        || definition.label.len() > 128
+    {
+        return Err("参数 ID 或显示名称无效".to_string());
+    }
+    let expected_write_path = format!(
+        "{TUNABLE_PARAMETER_VALUES_PATH}#/values/{}",
+        definition.parameter_id
+    );
+    if definition.write_path != expected_write_path
+        || definition.effect_mode != "next-relaunch"
+        || definition.editable_phase != "paused"
+    {
+        return Err("参数 writePath、生效方式或可编辑阶段不在白名单中".to_string());
+    }
+    if definition.min.is_some_and(|value| !value.is_finite())
+        || definition.max.is_some_and(|value| !value.is_finite())
+        || definition
+            .step
+            .is_some_and(|value| !value.is_finite() || value <= 0.0)
+        || matches!((definition.min, definition.max), (Some(min), Some(max)) if min > max)
+    {
+        return Err("参数范围或步长无效".to_string());
+    }
+    match definition.value_type {
+        GameTunableParameterValueType::Enum => {
+            let values = definition
+                .enum_values
+                .as_ref()
+                .filter(|values| !values.is_empty() && values.len() <= 64)
+                .ok_or_else(|| "枚举参数缺少允许值".to_string())?;
+            let mut unique = std::collections::HashSet::new();
+            if values
+                .iter()
+                .any(|value| value.trim().is_empty() || value.len() > 128 || !unique.insert(value))
+            {
+                return Err("枚举参数允许值无效或重复".to_string());
+            }
+        }
+        _ if definition.enum_values.is_some() => {
+            return Err("非枚举参数不能声明 enumValues".to_string());
+        }
+        _ => {}
+    }
+    validate_tunable_value(definition, &definition.default_value)?;
+    validate_tunable_value(definition, &definition.current_value)
+}
+
+fn read_tunable_parameter_registry(
+    artifact_root: &Path,
+) -> Result<Vec<GameTunableParameterDefinition>, String> {
+    let path = artifact_root.join(TUNABLE_PARAMETER_REGISTRY_PATH);
+    let metadata = match fs::symlink_metadata(&path) {
+        Ok(metadata) => metadata,
+        Err(error) if error.kind() == std::io::ErrorKind::NotFound => return Ok(Vec::new()),
+        Err(_) => return Err("读取数值参数注册表失败".to_string()),
+    };
+    if metadata.file_type().is_symlink()
+        || !metadata.is_file()
+        || metadata.len() > TUNABLE_PARAMETER_FILE_MAX_BYTES
+    {
+        return Err("数值参数注册表必须是受限普通文件".to_string());
+    }
+    let payload = fs::read_to_string(&path).map_err(|_| "读取数值参数注册表失败".to_string())?;
+    let registry = serde_json::from_str::<TunableParameterRegistryFile>(&payload)
+        .map_err(|_| "数值参数注册表格式无效".to_string())?;
+    if registry.schema_version != TUNABLE_PARAMETER_REGISTRY_SCHEMA_VERSION
+        || registry.parameters.len() > TUNABLE_PARAMETER_MAX_COUNT
+    {
+        return Err("数值参数注册表合同或数量无效".to_string());
+    }
+    let mut ids = std::collections::HashSet::new();
+    for definition in &registry.parameters {
+        validate_tunable_definition(definition)?;
+        if !ids.insert(definition.parameter_id.as_str()) {
+            return Err("数值参数注册表包含重复参数 ID".to_string());
+        }
+    }
+    Ok(registry.parameters)
+}
+
+fn read_editable_tunable_values(root: &Path) -> Result<Option<TunableParameterValuesFile>, String> {
+    let path = resolve_local_project_path(root, TUNABLE_PARAMETER_VALUES_PATH)?;
+    let metadata = match fs::symlink_metadata(&path) {
+        Ok(metadata) => metadata,
+        Err(error) if error.kind() == std::io::ErrorKind::NotFound => return Ok(None),
+        Err(_) => return Err("读取编辑态数值配置失败".to_string()),
+    };
+    if metadata.file_type().is_symlink()
+        || !metadata.is_file()
+        || metadata.len() > TUNABLE_PARAMETER_FILE_MAX_BYTES
+    {
+        return Err("编辑态数值配置必须是受限普通文件".to_string());
+    }
+    let payload = fs::read_to_string(path).map_err(|_| "读取编辑态数值配置失败".to_string())?;
+    let values = serde_json::from_str::<TunableParameterValuesFile>(&payload)
+        .map_err(|_| "编辑态数值配置格式无效".to_string())?;
+    if values.schema_version != TUNABLE_PARAMETER_VALUES_SCHEMA_VERSION {
+        return Err("编辑态数值配置合同无效".to_string());
+    }
+    Ok(Some(values))
+}
+
+fn overlay_editable_tunable_values(
+    definitions: &mut [GameTunableParameterDefinition],
+    values: Option<&TunableParameterValuesFile>,
+) -> Result<(), String> {
+    let Some(values) = values else {
+        return Ok(());
+    };
+    let registered = definitions
+        .iter()
+        .map(|definition| definition.parameter_id.as_str())
+        .collect::<std::collections::HashSet<_>>();
+    if values
+        .values
+        .keys()
+        .any(|parameter_id| !registered.contains(parameter_id.as_str()))
+    {
+        return Err("编辑态数值配置包含未登记参数".to_string());
+    }
+    for definition in definitions {
+        if let Some(value) = values.values.get(&definition.parameter_id) {
+            validate_tunable_value(definition, value)?;
+            definition.current_value = value.clone();
+        }
+    }
+    Ok(())
+}
+
+pub(crate) fn read_game_tunable_parameters_at(
+    root: &Path,
+    expected_project_id: &str,
+    version_id: &str,
+) -> Result<GameTunableParametersReadModel, String> {
+    let (_, version, artifact_root) =
+        resolve_runnable_game_version_at(root, expected_project_id, version_id)?;
+    let mut parameters = read_tunable_parameter_registry(&artifact_root)?;
+    let editable = read_editable_tunable_values(root)?;
+    overlay_editable_tunable_values(&mut parameters, editable.as_ref())?;
+    let project_revision = read_game_creator_agent_runtime_project_revision(root)?.revision;
+    Ok(GameTunableParametersReadModel {
+        version_id: version.version_id,
+        project_revision,
+        parameters,
+    })
+}
+
+fn write_tunable_values_atomically(
+    root: &Path,
+    values: &TunableParameterValuesFile,
+) -> Result<(), String> {
+    let path = resolve_local_project_path(root, TUNABLE_PARAMETER_VALUES_PATH)?;
+    if let Some(parent) = path.parent() {
+        fs::create_dir_all(parent).map_err(|_| "创建数值配置目录失败".to_string())?;
+    }
+    if fs::symlink_metadata(&path)
+        .is_ok_and(|metadata| metadata.file_type().is_symlink() || !metadata.is_file())
+    {
+        return Err("编辑态数值配置目标不是普通文件".to_string());
+    }
+    let payload =
+        serde_json::to_string_pretty(values).map_err(|_| "序列化编辑态数值配置失败".to_string())?;
+    if payload.len() > TUNABLE_PARAMETER_FILE_MAX_BYTES as usize {
+        return Err("编辑态数值配置超过大小限制".to_string());
+    }
+    let nonce = SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .unwrap_or_default()
+        .as_nanos();
+    let temp = path.with_file_name(format!(
+        ".tunable-values.tmp.{}.{}",
+        std::process::id(),
+        nonce
+    ));
+    let backup = path.with_file_name(format!(
+        ".tunable-values.previous.{}.{}",
+        std::process::id(),
+        nonce
+    ));
+    fs::write(&temp, format!("{payload}\n"))
+        .map_err(|_| "写入编辑态数值配置临时文件失败".to_string())?;
+    if path.exists() {
+        fs::rename(&path, &backup).map_err(|_| {
+            let _ = fs::remove_file(&temp);
+            "准备替换编辑态数值配置失败".to_string()
+        })?;
+    }
+    if let Err(_) = fs::rename(&temp, &path) {
+        if backup.exists() {
+            let _ = fs::rename(&backup, &path);
+        }
+        let _ = fs::remove_file(&temp);
+        return Err("替换编辑态数值配置失败".to_string());
+    }
+    if backup.exists() {
+        let _ = fs::remove_file(backup);
+    }
+    Ok(())
+}
+
+pub(crate) fn update_game_tunable_parameter_at(
+    root: &Path,
+    expected_project_id: &str,
+    version_id: &str,
+    parameter_id: &str,
+    value: serde_json::Value,
+    expected_project_revision: u64,
+) -> Result<UpdateGameTunableParameterResult, String> {
+    let current_revision = read_game_creator_agent_runtime_project_revision(root)?.revision;
+    if current_revision != expected_project_revision {
+        return Err("项目 revision 已变化，请刷新数值面板后再试".to_string());
+    }
+    let (_, _, artifact_root) =
+        resolve_runnable_game_version_at(root, expected_project_id, version_id)?;
+    let mut parameters = read_tunable_parameter_registry(&artifact_root)?;
+    let definition = parameters
+        .iter()
+        .find(|definition| definition.parameter_id == parameter_id)
+        .cloned()
+        .ok_or_else(|| "数值参数未登记，禁止新增写入路径".to_string())?;
+    validate_tunable_definition(&definition)?;
+    validate_tunable_value(&definition, &value)?;
+    let mut values =
+        read_editable_tunable_values(root)?.unwrap_or_else(|| TunableParameterValuesFile {
+            schema_version: TUNABLE_PARAMETER_VALUES_SCHEMA_VERSION.to_string(),
+            values: parameters
+                .iter()
+                .map(|definition| {
+                    (
+                        definition.parameter_id.clone(),
+                        definition.current_value.clone(),
+                    )
+                })
+                .collect(),
+        });
+    values.values.insert(parameter_id.to_string(), value);
+    overlay_editable_tunable_values(&mut parameters, Some(&values))?;
+    let revision = advance_agent_runtime_project_revision_locked(root)?;
+    write_tunable_values_atomically(root, &values)?;
+    let _ = append_agent_db_record(
+        root,
+        serde_json::json!({
+            "recordType": "project.tunable_parameter.updated",
+            "versionId": version_id,
+            "parameterId": parameter_id,
+            "projectRevision": revision,
+        }),
+    );
+    Ok(UpdateGameTunableParameterResult {
+        revision,
+        parameters,
+    })
+}
+
 fn unix_timestamp_millis() -> u64 {
     SystemTime::now()
         .duration_since(UNIX_EPOCH)
@@ -641,6 +1320,99 @@ mod tests {
         .expect("register runnable version")
     }
 
+    fn set_test_project_revision(root: &Path, revision: u64) {
+        let manifest = read_manifest(&root.join(".agent/manifest.json")).expect("read manifest");
+        write_game_creator_agent_runtime_project_revision(
+            root,
+            &AgentRuntimeProjectRevision {
+                schema_version: AGENT_RUNTIME_PROJECT_REVISION_SCHEMA_VERSION.to_string(),
+                project_id: manifest.project_id,
+                revision,
+                updated_at: unix_timestamp(),
+            },
+        )
+        .expect("write project revision");
+    }
+
+    fn add_test_png_asset(root: &Path, id: &str, file_name: &str, width: u32, height: u32) {
+        let path = root.join("assets").join(file_name);
+        image::RgbaImage::new(width, height)
+            .save(&path)
+            .expect("write png asset");
+        let manifest_path = root.join(".agent/manifest.json");
+        let mut manifest = read_manifest(&manifest_path).expect("read manifest");
+        manifest.assets.push(GameCreationAppAssetManifestEntry {
+            id: id.to_string(),
+            kind: "character".to_string(),
+            media_type: "image/png".to_string(),
+            local_path: format!("assets/{file_name}"),
+            source: GameCreationAppAssetSource {
+                kind: GameCreationAppAssetSourceKind::Generated,
+                canvas_project_id: None,
+                resource_id: None,
+                asset_object_id: None,
+                task_id: None,
+                prompt: None,
+                model: None,
+                generation_route: None,
+                generation_kind: None,
+                reference_resource_ids: Vec::new(),
+            },
+        });
+        write_manifest(&manifest_path, &manifest).expect("write png asset manifest");
+    }
+
+    fn add_test_wav_asset(
+        root: &Path,
+        id: &str,
+        file_name: &str,
+        channel_count: u16,
+        sample_rate_hz: u32,
+        duration_ms: u32,
+    ) {
+        let bytes_per_sample = 2u16;
+        let block_align = channel_count * bytes_per_sample;
+        let byte_rate = sample_rate_hz * u32::from(block_align);
+        let data_len = byte_rate * duration_ms / 1_000;
+        let mut bytes = Vec::with_capacity(44 + data_len as usize);
+        bytes.extend_from_slice(b"RIFF");
+        bytes.extend_from_slice(&(36 + data_len).to_le_bytes());
+        bytes.extend_from_slice(b"WAVEfmt ");
+        bytes.extend_from_slice(&16u32.to_le_bytes());
+        bytes.extend_from_slice(&1u16.to_le_bytes());
+        bytes.extend_from_slice(&channel_count.to_le_bytes());
+        bytes.extend_from_slice(&sample_rate_hz.to_le_bytes());
+        bytes.extend_from_slice(&byte_rate.to_le_bytes());
+        bytes.extend_from_slice(&block_align.to_le_bytes());
+        bytes.extend_from_slice(&(bytes_per_sample * 8).to_le_bytes());
+        bytes.extend_from_slice(b"data");
+        bytes.extend_from_slice(&data_len.to_le_bytes());
+        bytes.resize(44 + data_len as usize, 0);
+        fs::write(root.join("assets").join(file_name), bytes).expect("write wav asset");
+
+        let manifest_path = root.join(".agent/manifest.json");
+        let mut manifest = read_manifest(&manifest_path).expect("read manifest");
+        manifest.assets.push(GameCreationAppAssetManifestEntry {
+            id: id.to_string(),
+            kind: "sound-effect".to_string(),
+            media_type: "audio/wav".to_string(),
+            local_path: format!("assets/{file_name}"),
+            source: GameCreationAppAssetSource {
+                kind: GameCreationAppAssetSourceKind::Generated,
+                canvas_project_id: None,
+                resource_id: None,
+                asset_object_id: None,
+                task_id: None,
+                prompt: None,
+                model: None,
+                generation_route: None,
+                generation_kind: None,
+                reference_resource_ids: Vec::new(),
+            },
+        });
+        write_manifest(&manifest_path, &manifest).expect("write wav asset manifest");
+    }
+
     #[test]
     fn runnable_versions_register_idempotently_and_keep_immutable_snapshots() {
         let root = init_runnable_version_test_project("register");
@@ -671,6 +1443,9 @@ mod tests {
                 width: None,
                 height: None,
                 duration_ms: None,
+                channel_count: None,
+                sample_rate_hz: None,
+                codec: None,
                 format: "text/plain".to_string(),
             }]
         );
@@ -818,4 +1593,217 @@ mod tests {
         );
         fs::remove_dir_all(root).ok();
     }
+
+    #[test]
+    fn resource_replacement_creates_a_child_snapshot_without_switching_the_current_version() {
+        let root = init_runnable_version_test_project("resource-replacement");
+        add_test_png_asset(&root, "hero-a", "hero-a.png", 2, 2);
+        add_test_png_asset(&root, "hero-b", "hero-b.png", 2, 2);
+        image::RgbaImage::from_pixel(2, 2, image::Rgba([255, 0, 0, 255]))
+            .save(root.join("assets/hero-a.png"))
+            .expect("make hero-a bytes distinct");
+        let manifest = read_manifest(&root.join(".agent/manifest.json")).expect("read manifest");
+        let hero_a = manifest
+            .assets
+            .iter()
+            .find(|asset| asset.id == "hero-a")
+            .cloned()
+            .expect("hero-a asset");
+        let descriptor = runnable_resource_descriptor(&root, &hero_a).expect("hero-a descriptor");
+        image::RgbaImage::new(descriptor.width.unwrap(), descriptor.height.unwrap())
+            .save(root.join("assets/hero-b.png"))
+            .expect("rewrite matching hero-b");
+        write_manifest(&root.join(".agent/manifest.json"), &manifest).expect("keep manifest");
+        set_test_project_revision(&root, 1);
+        let parent = register_test_version(&root, 1);
+        let parent_bytes =
+            fs::read(root.join(".agent/runnable-versions/runnable-r1/artifact/assets/hero-a.png"))
+                .expect("read parent hero");
+        let replacement_bytes = fs::read(root.join("assets/hero-b.png")).expect("read candidate");
+
+        let result = replace_runnable_game_resource_at(
+            &root,
+            "project-resource-replacement",
+            &parent.version_id,
+            "hero-a",
+            "hero-b",
+            1,
+        )
+        .expect("replace compatible resource");
+        assert_eq!(
+            result.manifest.current_runnable_version_id.as_deref(),
+            Some(parent.version_id.as_str())
+        );
+        assert_eq!(
+            result.version.created_reason,
+            RunnableGameVersionCreatedReason::ResourceReplacement
+        );
+        assert_eq!(result.version.parent_version_id, Some(parent.version_id));
+        assert_eq!(
+            result.version.resource_replacement,
+            Some(RunnableGameResourceReplacement {
+                slot_id: "hero-a".to_string(),
+                previous_resource_id: "hero-a".to_string(),
+                replacement_resource_id: "hero-b".to_string(),
+            })
+        );
+        assert_eq!(
+            fs::read(root.join(".agent/runnable-versions/runnable-r2/artifact/assets/hero-a.png"))
+                .expect("read child hero"),
+            replacement_bytes
+        );
+        assert_eq!(
+            fs::read(root.join(".agent/runnable-versions/runnable-r1/artifact/assets/hero-a.png"))
+                .expect("read unchanged parent hero"),
+            parent_bytes
+        );
+        fs::remove_dir_all(root).ok();
+    }
+
+    #[test]
+    fn resource_replacement_rejects_incompatible_size_before_advancing_revision() {
+        let root = init_runnable_version_test_project("resource-size-mismatch");
+        add_test_png_asset(&root, "hero-small", "hero-small.png", 2, 2);
+        add_test_png_asset(&root, "hero-large", "hero-large.png", 3, 3);
+        set_test_project_revision(&root, 1);
+        let parent = register_test_version(&root, 1);
+        let error = replace_runnable_game_resource_at(
+            &root,
+            "project-resource-size-mismatch",
+            &parent.version_id,
+            "hero-small",
+            "hero-large",
+            1,
+        )
+        .expect_err("reject incompatible size");
+        assert!(error.contains("尺寸规格不匹配"), "{error}");
+        assert_eq!(
+            read_game_creator_agent_runtime_project_revision(&root)
+                .expect("read stable revision")
+                .revision,
+            1
+        );
+        let manifest = read_manifest(&root.join(".agent/manifest.json")).expect("read manifest");
+        assert_eq!(manifest.runnable_versions.len(), 1);
+        fs::remove_dir_all(root).ok();
+    }
+
+    #[test]
+    fn resource_replacement_uses_trusted_wav_channel_rate_and_duration_metadata() {
+        let root = init_runnable_version_test_project("resource-wav-spec");
+        add_test_wav_asset(&root, "sfx-a", "sfx-a.wav", 1, 44_100, 100);
+        add_test_wav_asset(&root, "sfx-b", "sfx-b.wav", 1, 44_100, 100);
+        add_test_wav_asset(&root, "sfx-stereo", "sfx-stereo.wav", 2, 44_100, 100);
+        set_test_project_revision(&root, 1);
+        let parent = register_test_version(&root, 1);
+        let descriptor = parent
+            .resource_descriptors
+            .iter()
+            .find(|descriptor| descriptor.resource_id == "sfx-a")
+            .expect("registered wav descriptor");
+        assert_eq!(descriptor.channel_count, Some(1));
+        assert_eq!(descriptor.sample_rate_hz, Some(44_100));
+        assert_eq!(descriptor.duration_ms, Some(100));
+        assert_eq!(descriptor.codec.as_deref(), Some("pcm"));
+
+        replace_runnable_game_resource_at(
+            &root,
+            "project-resource-wav-spec",
+            &parent.version_id,
+            "sfx-a",
+            "sfx-b",
+            1,
+        )
+        .expect("replace compatible wav resource");
+        let error = replace_runnable_game_resource_at(
+            &root,
+            "project-resource-wav-spec",
+            &parent.version_id,
+            "sfx-a",
+            "sfx-stereo",
+            2,
+        )
+        .expect_err("reject wav with a different channel count");
+        assert!(error.contains("尺寸规格不匹配"), "{error}");
+        assert_eq!(
+            read_game_creator_agent_runtime_project_revision(&root)
+                .expect("read stable revision")
+                .revision,
+            2
+        );
+        fs::remove_dir_all(root).ok();
+    }
+
+    #[test]
+    fn tunable_parameter_update_is_registry_bound_and_advances_only_editable_revision() {
+        let root = init_runnable_version_test_project("tunable-update");
+        fs::write(
+            root.join(TUNABLE_PARAMETER_REGISTRY_PATH),
+            serde_json::to_string_pretty(&serde_json::json!({
+                "schemaVersion": TUNABLE_PARAMETER_REGISTRY_SCHEMA_VERSION,
+                "parameters": [{
+                    "parameterId": "player.speed",
+                    "label": "移动速度",
+                    "valueType": "number",
+                    "defaultValue": 1.0,
+                    "currentValue": 1.0,
+                    "min": 0.5,
+                    "max": 2.0,
+                    "step": 0.1,
+                    "unit": "倍",
+                    "writePath": "game/tunable-values.json#/values/player.speed",
+                    "effectMode": "next-relaunch",
+                    "editablePhase": "paused",
+                    "codeMutationAllowed": false
+                }]
+            }))
+            .expect("serialize tunable registry"),
+        )
+        .expect("write tunable registry");
+        set_test_project_revision(&root, 1);
+        let version = register_test_version(&root, 1);
+        let initial =
+            read_game_tunable_parameters_at(&root, "project-tunable-update", &version.version_id)
+                .expect("read tunable registry");
+        assert_eq!(initial.parameters[0].current_value, serde_json::json!(1.0));
+
+        let updated = update_game_tunable_parameter_at(
+            &root,
+            "project-tunable-update",
+            &version.version_id,
+            "player.speed",
+            serde_json::json!(1.5),
+            1,
+        )
+        .expect("update registered parameter");
+        assert_eq!(updated.revision, 2);
+        assert_eq!(updated.parameters[0].current_value, serde_json::json!(1.5));
+        let manifest = read_manifest(&root.join(".agent/manifest.json")).expect("read manifest");
+        assert_eq!(manifest.runnable_versions, vec![version.clone()]);
+        assert_eq!(
+            read_game_tunable_parameters_at(&root, "project-tunable-update", &version.version_id,)
+                .expect("read editable tunable value")
+                .parameters[0]
+                .current_value,
+            serde_json::json!(1.5)
+        );
+
+        let error = update_game_tunable_parameter_at(
+            &root,
+            "project-tunable-update",
+            &version.version_id,
+            "unregistered.path",
+            serde_json::json!(1),
+            2,
+        )
+        .expect_err("reject unregistered parameter");
+        assert!(error.contains("未登记"), "{error}");
+        assert_eq!(
+            read_game_creator_agent_runtime_project_revision(&root)
+                .expect("read stable revision")
+                .revision,
+            2
+        );
+        fs::remove_dir_all(root).ok();
+    }
 }
diff --git a/apps/ai-game-creator-shell/src/features/project-workspace/LocalGamePreviewFrame.tsx b/apps/ai-game-creator-shell/src/features/project-workspace/LocalGamePreviewFrame.tsx
index 0fd32943c..5d498de8f 100644
--- a/apps/ai-game-creator-shell/src/features/project-workspace/LocalGamePreviewFrame.tsx
+++ b/apps/ai-game-creator-shell/src/features/project-workspace/LocalGamePreviewFrame.tsx
@@ -37,6 +37,9 @@ export type LocalGamePreviewFrameHandle = {
   requestInspection: () => boolean;
   startSlice: (sliceId: string) => boolean;
   stopSlice: (sliceId: string) => boolean;
+  markStale: (
+    reason: 'project-revision-changed' | 'version-changed',
+  ) => boolean;
 };
 
 type ActiveBridgeSession = {
@@ -103,32 +106,32 @@ export const LocalGamePreviewFrame = forwardRef<
     onSessionChange,
   };
 
-  const sendHostMessage = useCallback((
-    type: GameHostMessageType,
-    sliceId?: string,
-  ) => {
-    const active = activeRef.current;
-    const targetWindow = iframeRef.current?.contentWindow;
-    if (!active || !targetWindow) {
-      return false;
-    }
-    const requestId = newGameRunBridgeRequestId('host');
-    if (!requestId || !active.guard.registerHostRequest(requestId, type)) {
-      callbacksRef.current.onBridgeError?.('运行会话无法创建安全请求身份');
-      return false;
-    }
-    const message = createGameHostMessage({
-      identity: active.identity,
-      sessionId: active.session.sessionId,
-      requestId,
-      sequence: active.nextHostSequence,
-      type,
-      payload: sliceId ? { sliceId } : undefined,
-    });
-    active.nextHostSequence += 1;
-    targetWindow.postMessage(message, active.identity.previewOrigin);
-    return true;
-  }, []);
+  const sendHostMessage = useCallback(
+    (type: GameHostMessageType, sliceId?: string) => {
+      const active = activeRef.current;
+      const targetWindow = iframeRef.current?.contentWindow;
+      if (!active || !targetWindow) {
+        return false;
+      }
+      const requestId = newGameRunBridgeRequestId('host');
+      if (!requestId || !active.guard.registerHostRequest(requestId, type)) {
+        callbacksRef.current.onBridgeError?.('运行会话无法创建安全请求身份');
+        return false;
+      }
+      const message = createGameHostMessage({
+        identity: active.identity,
+        sessionId: active.session.sessionId,
+        requestId,
+        sequence: active.nextHostSequence,
+        type,
+        payload: sliceId ? { sliceId } : undefined,
+      });
+      active.nextHostSequence += 1;
+      targetWindow.postMessage(message, active.identity.previewOrigin);
+      return true;
+    },
+    [],
+  );
 
   const stopActiveSession = useCallback(
     (notify: boolean) => {
@@ -160,6 +163,20 @@ export const LocalGamePreviewFrame = forwardRef<
       requestInspection: () => sendHostMessage('host.inspection.request'),
       startSlice: (sliceId) => sendHostMessage('host.slice.start', sliceId),
       stopSlice: (sliceId) => sendHostMessage('host.slice.stop', sliceId),
+      markStale: (reason) => {
+        const active = activeRef.current;
+        if (!active) {
+          return false;
+        }
+        active.session = {
+          ...active.session,
+          stale: true,
+          staleReason: reason,
+          updatedAt: Date.now(),
+        };
+        callbacksRef.current.onSessionChange?.(active.session);
+        return true;
+      },
     }),
     [sendHostMessage, stopActiveSession],
   );
diff --git a/apps/ai-game-creator-shell/src/styles.css b/apps/ai-game-creator-shell/src/styles.css
index c23c5a6a7..19e02ca38 100644
--- a/apps/ai-game-creator-shell/src/styles.css
+++ b/apps/ai-game-creator-shell/src/styles.css
@@ -4195,6 +4195,19 @@ iframe.preview-frame {
   font-size: 10px;
 }
 
+.game-resource-replace-trigger {
+  justify-self: start;
+  min-height: 32px;
+  padding: 0 14px;
+  border: 1px solid #d87a4d;
+  border-radius: 999px;
+  background: #fff6f0;
+  color: #a8502c;
+  font-size: 11px;
+  font-weight: 700;
+  cursor: pointer;
+}
+
 .game-resource-focus-metadata dt {
   color: #a08377;
 }
@@ -4529,7 +4542,7 @@ iframe.preview-frame {
 
 .game-run-panels {
   display: grid;
-  grid-template-columns: repeat(3, minmax(0, 1fr));
+  grid-template-columns: repeat(2, minmax(0, 1fr));
   gap: 10px;
 }
 
@@ -4624,6 +4637,127 @@ iframe.preview-frame {
   opacity: 0.5;
 }
 
+.game-tunable-panel {
+  grid-column: 1 / -1;
+}
+
+.game-tunable-natural-language {
+  display: grid;
+  grid-template-columns: minmax(0, 1fr) auto;
+  gap: 8px;
+}
+
+.game-tunable-natural-language input {
+  width: 100%;
+}
+
+.game-tunable-list {
+  display: grid;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  gap: 8px;
+}
+
+.game-tunable-item {
+  display: grid;
+  grid-template-columns: minmax(0, 1fr) auto;
+  align-items: end;
+  gap: 8px;
+  padding: 8px;
+  border: 1px solid #eee0d9;
+  border-radius: 9px;
+  background: #fffdfa;
+}
+
+.game-tunable-item.is-matched {
+  border-color: #d87342;
+  box-shadow: 0 0 0 2px rgb(216 115 66 / 12%);
+}
+
+.game-tunable-item label {
+  grid-template-columns: minmax(0, 1fr) 96px;
+}
+
+.game-tunable-item select {
+  min-width: 0;
+  height: 30px;
+  border: 1px solid #eadbd4;
+  border-radius: 8px;
+  background: #faf7f5;
+  color: #62483d;
+  font-size: 10px;
+}
+
+.game-resource-replacement-dialog {
+  display: grid;
+  gap: 14px;
+  width: min(620px, calc(100vw - 32px));
+  max-height: min(680px, calc(100vh - 32px));
+  padding: 18px;
+  overflow: auto;
+  border: 1px solid #e3c9bb;
+  border-radius: 18px;
+  background: #fffdfb;
+  box-shadow: 0 24px 80px rgb(80 43 28 / 25%);
+}
+
+.game-resource-replacement-dialog > header,
+.game-resource-replacement-dialog > footer {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 12px;
+}
+
+.game-resource-replacement-dialog h2,
+.game-resource-replacement-dialog p {
+  margin: 0;
+}
+
+.game-resource-replacement-dialog h2 {
+  color: #5b4035;
+  font-size: 16px;
+}
+
+.game-resource-replacement-dialog p,
+.game-resource-replacement-dialog small {
+  color: #987a6d;
+  font-size: 10px;
+}
+
+.game-resource-replacement-dialog button {
+  min-height: 32px;
+  padding: 0 12px;
+  border: 1px solid #e2c5b6;
+  border-radius: 10px;
+  background: #fff7f2;
+  color: #805747;
+  cursor: pointer;
+}
+
+.game-resource-replacement-dialog button:disabled {
+  cursor: default;
+  opacity: 0.5;
+}
+
+.game-resource-replacement-candidates {
+  display: grid;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  gap: 10px;
+}
+
+.game-resource-replacement-candidates button {
+  display: grid;
+  justify-items: start;
+  gap: 4px;
+  min-height: 72px;
+  text-align: left;
+}
+
+.game-resource-replacement-candidates button.is-selected {
+  border-color: #d87342;
+  background: #fff0e7;
+}
+
 .game-workbench-chat {
   display: grid;
   grid-template-rows: auto minmax(0, 1fr);
@@ -5146,6 +5280,11 @@ iframe.preview-frame {
     grid-template-columns: 1fr;
   }
 
+  .game-tunable-list,
+  .game-resource-replacement-candidates {
+    grid-template-columns: 1fr;
+  }
+
   .game-workbench-chat .project-supervisor-message-list {
     max-height: 52vh;
   }
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 7f194efce..07107ab68 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
@@ -35,6 +35,7 @@ import type {
   GameCreationAppPreviewState,
   GameRunSession,
   GameRuntimeMessage,
+  GameTunableParameterDefinition,
   ProjectResourceCanvasLayoutMode,
   RunnableGameVersion,
 } from '../../../../../packages/shared/src/contracts/gameCreationApp';
@@ -181,6 +182,43 @@ type RunnableGameVersionLaunchResult = {
   };
 };
 
+type LocalGameProjectRevisionStatus = { revision: number };
+
+type ReplaceRunnableGameResourceResult = {
+  manifest: GameCreationAppManifest;
+  version: RunnableGameVersion;
+};
+
+type GameTunableParametersReadModel = {
+  versionId: string;
+  projectRevision: number;
+  parameters: GameTunableParameterDefinition[];
+};
+
+type UpdateGameTunableParameterResult = {
+  revision: number;
+  parameters: GameTunableParameterDefinition[];
+};
+
+type ResourceReplacementState =
+  | { status: 'closed' }
+  | {
+      status: 'loading' | 'ready' | 'submitting' | 'failed';
+      slotId: string;
+      previousResourceId: string;
+      expectedProjectRevision: number | null;
+      candidateResourceId: string;
+      error: string;
+    };
+
+type TunableParametersState =
+  | { status: 'idle' | 'loading'; readModel: null; error: string }
+  | {
+      status: 'ready' | 'saving' | 'failed';
+      readModel: GameTunableParametersReadModel;
+      error: string;
+    };
+
 const categoryOrder: ResourceCategory[] = [
   'document',
   'version',
@@ -490,6 +528,20 @@ export default function ProjectDevelopmentView({
     resourceId: null,
   });
   const [mediaDuration, setMediaDuration] = useState<number | null>(null);
+  const [resourceReplacement, setResourceReplacement] =
+    useState<ResourceReplacementState>({ status: 'closed' });
+  const [tunableParameters, setTunableParameters] =
+    useState<TunableParametersState>({
+      status: 'idle',
+      readModel: null,
+      error: '',
+    });
+  const [tunableDrafts, setTunableDrafts] = useState<
+    Record<string, number | boolean | string>
+  >({});
+  const [tunableNaturalLanguage, setTunableNaturalLanguage] = useState('');
+  const [matchedTunableParameterId, setMatchedTunableParameterId] =
+    useState('');
   const resourceCanvasRef = useRef<HTMLDivElement>(null);
   const gamePreviewFrameRef = useRef<LocalGamePreviewFrameHandle>(null);
   const resourceFocusRef = useRef<HTMLElement>(null);
@@ -760,6 +812,21 @@ export default function ProjectDevelopmentView({
     resources.find((resource) => resource.id === selectedResourceId) ?? null;
   const focusedResource =
     resources.find((resource) => resource.id === focusedResourceId) ?? null;
+  const focusedReplacementBindings =
+    focusedResource?.manifestAssetId && currentRunnableVersion
+      ? currentRunnableVersion.resourceBindings.filter(
+          (binding) => binding.resourceId === focusedResource.manifestAssetId,
+        )
+      : [];
+  const replacementCandidateResources = focusedResource
+    ? resources.filter(
+        (resource) =>
+          resource.manifestAssetId !== null &&
+          resource.manifestAssetId !== focusedResource.manifestAssetId &&
+          resource.category === focusedResource.category &&
+          (resource.category === 'art' || resource.category === 'audio'),
+      )
+    : [];
   const trustedInspectionResource = trustedInspection
     ? (resources.find(
         (resource) => resource.manifestAssetId === trustedInspection.resourceId,
@@ -829,6 +896,59 @@ export default function ProjectDevelopmentView({
     setSelectedRunnableVersionId(manifest.currentRunnableVersionId ?? '');
   }, [manifest.currentRunnableVersionId, manifest.projectId]);
 
+  useEffect(() => {
+    if (mode !== 'run' || !currentRunnableVersion) {
+      setTunableParameters({ status: 'idle', readModel: null, error: '' });
+      setTunableDrafts({});
+      return undefined;
+    }
+    const invoke = resolveTauriInvoke();
+    if (!invoke) {
+      setTunableParameters({
+        status: 'idle',
+        readModel: null,
+        error: '数值参数需要在 Tauri App 内读取',
+      });
+      return undefined;
+    }
+    let cancelled = false;
+    setTunableParameters({ status: 'loading', readModel: null, error: '' });
+    void invoke<GameTunableParametersReadModel>(
+      'read_local_game_tunable_parameters',
+      {
+        projectPath,
+        expectedProjectId: manifest.projectId,
+        versionId: currentRunnableVersion.versionId,
+      },
+    )
+      .then((readModel) => {
+        if (cancelled) {
+          return;
+        }
+        setTunableParameters({ status: 'ready', readModel, error: '' });
+        setTunableDrafts(
+          Object.fromEntries(
+            readModel.parameters.map((parameter) => [
+              parameter.parameterId,
+              parameter.currentValue,
+            ]),
+          ),
+        );
+      })
+      .catch((error: unknown) => {
+        if (!cancelled) {
+          setTunableParameters({
+            status: 'idle',
+            readModel: null,
+            error: error instanceof Error ? error.message : String(error),
+          });
+        }
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [currentRunnableVersion, manifest.projectId, mode, projectPath]);
+
   useEffect(() => {
     setSelectedTestSliceId(testSlices[0]?.sliceId ?? '');
     setActiveTestSlice(null);
@@ -1079,6 +1199,176 @@ export default function ProjectDevelopmentView({
     setFocusedResourceId(null);
   }
 
+  async function openResourceReplacement() {
+    const binding = focusedReplacementBindings[0];
+    if (!focusedResource?.manifestAssetId || !binding) {
+      return;
+    }
+    const invoke = resolveTauriInvoke();
+    if (!invoke) {
+      setRunStatus('资源替换需要在 Tauri App 内执行');
+      return;
+    }
+    setResourceReplacement({
+      status: 'loading',
+      slotId: binding.slotId,
+      previousResourceId: binding.resourceId,
+      expectedProjectRevision: null,
+      candidateResourceId: '',
+      error: '',
+    });
+    try {
+      const revision = await invoke<LocalGameProjectRevisionStatus>(
+        'get_local_game_project_revision',
+        { projectPath },
+      );
+      setResourceReplacement({
+        status: 'ready',
+        slotId: binding.slotId,
+        previousResourceId: binding.resourceId,
+        expectedProjectRevision: revision.revision,
+        candidateResourceId: '',
+        error: '',
+      });
+    } catch (error) {
+      setResourceReplacement({
+        status: 'failed',
+        slotId: binding.slotId,
+        previousResourceId: binding.resourceId,
+        expectedProjectRevision: null,
+        candidateResourceId: '',
+        error: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
+
+  async function submitResourceReplacement() {
+    if (
+      resourceReplacement.status === 'closed' ||
+      resourceReplacement.expectedProjectRevision === null ||
+      !resourceReplacement.candidateResourceId ||
+      !currentRunnableVersion
+    ) {
+      return;
+    }
+    const invoke = resolveTauriInvoke();
+    if (!invoke) {
+      return;
+    }
+    const submitting = {
+      ...resourceReplacement,
+      status: 'submitting' as const,
+    };
+    setResourceReplacement(submitting);
+    try {
+      const result = await invoke<ReplaceRunnableGameResourceResult>(
+        'replace_local_game_runnable_resource',
+        {
+          projectPath,
+          expectedProjectId: manifest.projectId,
+          parentVersionId: currentRunnableVersion.versionId,
+          slotId: resourceReplacement.slotId,
+          replacementResourceId: resourceReplacement.candidateResourceId,
+          expectedProjectRevision: resourceReplacement.expectedProjectRevision,
+        },
+      );
+      onManifestChange?.(result.manifest);
+      setResourceReplacement({ status: 'closed' });
+      setRunStatus(
+        `已创建资源替换版本 ${result.version.versionId}；当前运行版本保持不变`,
+      );
+    } catch (error) {
+      setResourceReplacement({
+        ...submitting,
+        status: 'failed',
+        error: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
+
+  function matchNaturalLanguageTunableParameter() {
+    const text = tunableNaturalLanguage.trim().toLocaleLowerCase('zh-CN');
+    const parameters = tunableParameters.readModel?.parameters ?? [];
+    const match = parameters.find(
+      (parameter) =>
+        text.includes(parameter.label.toLocaleLowerCase('zh-CN')) ||
+        text.includes(parameter.parameterId.toLocaleLowerCase('zh-CN')),
+    );
+    setMatchedTunableParameterId(match?.parameterId ?? '');
+    setRunStatus(
+      match
+        ? `已匹配登记参数：${match.label}`
+        : '未匹配到已登记参数；自然语言不能新增代码或任意写入路径',
+    );
+  }
+
+  async function saveTunableParameter(
+    parameter: GameTunableParameterDefinition,
+  ) {
+    if (
+      tunableParameters.status !== 'ready' ||
+      gameRunSession?.status !== 'paused' ||
+      gameRunSession.stale
+    ) {
+      setRunStatus('数值参数仅能在未失效的暂停会话中修改');
+      return;
+    }
+    const value = tunableDrafts[parameter.parameterId];
+    if (value === undefined) {
+      return;
+    }
+    const invoke = resolveTauriInvoke();
+    if (!invoke) {
+      return;
+    }
+    const readModel = tunableParameters.readModel;
+    setTunableParameters({ status: 'saving', readModel, error: '' });
+    try {
+      const result = await invoke<UpdateGameTunableParameterResult>(
+        'update_local_game_tunable_parameter',
+        {
+          projectPath,
+          expectedProjectId: manifest.projectId,
+          versionId: currentRunnableVersion?.versionId ?? '',
+          parameterId: parameter.parameterId,
+          value,
+          expectedProjectRevision: readModel.projectRevision,
+        },
+      );
+      const nextReadModel = {
+        ...readModel,
+        projectRevision: result.revision,
+        parameters: result.parameters,
+      };
+      setTunableParameters({
+        status: 'ready',
+        readModel: nextReadModel,
+        error: '',
+      });
+      setTunableDrafts(
+        Object.fromEntries(
+          result.parameters.map((definition) => [
+            definition.parameterId,
+            definition.currentValue,
+          ]),
+        ),
+      );
+      gamePreviewFrameRef.current?.markStale('project-revision-changed');
+      setActiveTestSlice((active) =>
+        active ? { ...active, stale: true } : active,
+      );
+      setRunStatus(
+        `数值已写入编辑态 revision ${result.revision}；当前运行会话已失效，变更将在下一可运行版本中生效`,
+      );
+    } catch (error) {
+      setTunableParameters({
+        status: 'ready',
+        readModel,
+        error: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
+
   async function launchRunnableVersion(versionId: string) {
     const invoke = resolveTauriInvoke();
     if (!invoke) {
@@ -1222,7 +1512,12 @@ export default function ProjectDevelopmentView({
   }
 
   function startTestSlice(slice = selectedTestSlice) {
-    if (!slice || !gameRunSession || gameRunSession.status === 'failed') {
+    if (
+      !slice ||
+      !gameRunSession ||
+      gameRunSession.status === 'failed' ||
+      gameRunSession.stale
+    ) {
       setRunStatus('当前运行会话无法启动测试切片');
       return;
     }
@@ -1635,6 +1930,17 @@ export default function ProjectDevelopmentView({
                     </>
                   ) : null}
                 </dl>
+                {focusedReplacementBindings.length > 0 &&
+                (focusedResource.category === 'art' ||
+                  focusedResource.category === 'audio') ? (
+                  <button
+                    type="button"
+                    className="game-resource-replace-trigger"
+                    onClick={() => void openResourceReplacement()}
+                  >
+                    替换资源
+                  </button>
+                ) : null}
               </div>
             </section>
           ) : mode === 'resources' ? (
@@ -1792,7 +2098,8 @@ export default function ProjectDevelopmentView({
                   disabled={
                     !selectedTestSlice ||
                     selectedTestSliceIndex === 0 ||
-                    activeTestSlice?.stale === true
+                    activeTestSlice?.stale === true ||
+                    gameRunSession?.stale === true
                   }
                   onClick={() => switchTestSlice(-1)}
                 >
@@ -1804,7 +2111,8 @@ export default function ProjectDevelopmentView({
                   disabled={
                     !selectedTestSlice ||
                     gameRunSession?.status === 'failed' ||
-                    activeTestSlice?.stale === true
+                    activeTestSlice?.stale === true ||
+                    gameRunSession?.stale === true
                   }
                   aria-label={
                     activeTestSlice?.status === 'playing'
@@ -1835,7 +2143,8 @@ export default function ProjectDevelopmentView({
                   disabled={
                     !selectedTestSlice ||
                     selectedTestSliceIndex >= testSlices.length - 1 ||
-                    activeTestSlice?.stale === true
+                    activeTestSlice?.stale === true ||
+                    gameRunSession?.stale === true
                   }
                   onClick={() => switchTestSlice(1)}
                 >
@@ -1952,6 +2261,148 @@ export default function ProjectDevelopmentView({
                     <p>暂无悬停资源</p>
                   )}
                 </section>
+                <section
+                  className="game-tunable-panel"
+                  aria-label="数值微调面板"
+                >
+                  <header>
+                    <Settings2 size={16} aria-hidden="true" />
+                    数值微调
+                  </header>
+                  <div className="game-tunable-natural-language">
+                    <input
+                      aria-label="自然语言匹配数值参数"
+                      value={tunableNaturalLanguage}
+                      placeholder="例如：把跳跃高度调高一点"
+                      onChange={(event) =>
+                        setTunableNaturalLanguage(event.currentTarget.value)
+                      }
+                    />
+                    <button
+                      type="button"
+                      disabled={
+                        !tunableNaturalLanguage.trim() ||
+                        !tunableParameters.readModel?.parameters.length
+                      }
+                      onClick={matchNaturalLanguageTunableParameter}
+                    >
+                      匹配参数
+                    </button>
+                  </div>
+                  {tunableParameters.status === 'loading' ? (
+                    <p role="status">正在读取参数注册表…</p>
+                  ) : tunableParameters.readModel?.parameters.length ? (
+                    <div className="game-tunable-list">
+                      {tunableParameters.readModel.parameters.map(
+                        (parameter) => {
+                          const editable =
+                            tunableParameters.status === 'ready' &&
+                            gameRunSession?.status === 'paused' &&
+                            !gameRunSession.stale;
+                          const value =
+                            tunableDrafts[parameter.parameterId] ??
+                            parameter.currentValue;
+                          return (
+                            <div
+                              className={`game-tunable-item${
+                                matchedTunableParameterId ===
+                                parameter.parameterId
+                                  ? ' is-matched'
+                                  : ''
+                              }`}
+                              key={parameter.parameterId}
+                              data-parameter-id={parameter.parameterId}
+                            >
+                              <label>
+                                <span>
+                                  {parameter.label}
+                                  {parameter.unit
+                                    ? `（${parameter.unit}）`
+                                    : ''}
+                                </span>
+                                {parameter.valueType === 'enum' ? (
+                                  <select
+                                    aria-label={parameter.label}
+                                    value={String(value)}
+                                    disabled={!editable}
+                                    onChange={(event) => {
+                                      const nextValue = event.currentTarget.value;
+                                      setTunableDrafts((current) => ({
+                                        ...current,
+                                        [parameter.parameterId]: nextValue,
+                                      }));
+                                    }}
+                                  >
+                                    {(parameter.enumValues ?? []).map(
+                                      (option) => (
+                                        <option key={option} value={option}>
+                                          {option}
+                                        </option>
+                                      ),
+                                    )}
+                                  </select>
+                                ) : parameter.valueType === 'boolean' ? (
+                                  <select
+                                    aria-label={parameter.label}
+                                    value={String(value)}
+                                    disabled={!editable}
+                                    onChange={(event) => {
+                                      const nextValue =
+                                        event.currentTarget.value === 'true';
+                                      setTunableDrafts((current) => ({
+                                        ...current,
+                                        [parameter.parameterId]: nextValue,
+                                      }));
+                                    }}
+                                  >
+                                    <option value="true">开启</option>
+                                    <option value="false">关闭</option>
+                                  </select>
+                                ) : (
+                                  <input
+                                    type="number"
+                                    aria-label={parameter.label}
+                                    value={Number(value)}
+                                    min={parameter.min}
+                                    max={parameter.max}
+                                    step={
+                                      parameter.valueType === 'integer'
+                                        ? (parameter.step ?? 1)
+                                        : (parameter.step ?? 'any')
+                                    }
+                                    disabled={!editable}
+                                    onChange={(event) => {
+                                      const nextValue =
+                                        event.currentTarget.valueAsNumber;
+                                      setTunableDrafts((current) => ({
+                                        ...current,
+                                        [parameter.parameterId]: nextValue,
+                                      }));
+                                    }}
+                                  />
+                                )}
+                              </label>
+                              <button
+                                type="button"
+                                disabled={!editable}
+                                onClick={() =>
+                                  void saveTunableParameter(parameter)
+                                }
+                              >
+                                保存
+                              </button>
+                            </div>
+                          );
+                        },
+                      )}
+                    </div>
+                  ) : (
+                    <p>当前版本未登记可微调参数</p>
+                  )}
+                  {tunableParameters.error ? (
+                    <p role="alert">{tunableParameters.error}</p>
+                  ) : null}
+                </section>
               </div>
               {runStatus ? (
                 <p className="game-run-status" role="status">
@@ -1960,6 +2411,11 @@ export default function ProjectDevelopmentView({
               ) : null}
             </section>
           )}
+          {mode !== 'run' && runStatus && (runAvailable || focusedResource) ? (
+            <p className="game-run-status" role="status">
+              {runStatus}
+            </p>
+          ) : null}
         </section>
 
         <aside className="game-workbench-chat" aria-label="陶泥儿 Agent 对话">
@@ -2033,6 +2489,109 @@ export default function ProjectDevelopmentView({
         </button>
       </footer>
 
+      {resourceReplacement.status !== 'closed' ? (
+        <div
+          className="game-approval-backdrop"
+          role="presentation"
+          onMouseDown={(event) => {
+            if (
+              event.target === event.currentTarget &&
+              resourceReplacement.status !== 'submitting'
+            ) {
+              setResourceReplacement({ status: 'closed' });
+            }
+          }}
+        >
+          <section
+            className="game-resource-replacement-dialog"
+            role="dialog"
+            aria-modal="true"
+            aria-labelledby="game-resource-replacement-title"
+          >
+            <header>
+              <div>
+                <h2 id="game-resource-replacement-title">选择替换资源</h2>
+                <p>{`绑定槽位：${resourceReplacement.slotId}`}</p>
+              </div>
+              <button
+                type="button"
+                aria-label="关闭资源替换"
+                disabled={resourceReplacement.status === 'submitting'}
+                onClick={() => setResourceReplacement({ status: 'closed' })}
+              >
+                <X size={16} aria-hidden="true" />
+              </button>
+            </header>
+            {resourceReplacement.status === 'loading' ? (
+              <p role="status">正在锁定项目 revision…</p>
+            ) : replacementCandidateResources.length > 0 ? (
+              <div className="game-resource-replacement-candidates">
+                {replacementCandidateResources.map((resource) => (
+                  <button
+                    type="button"
+                    className={
+                      resourceReplacement.candidateResourceId ===
+                      resource.manifestAssetId
+                        ? 'is-selected'
+                        : ''
+                    }
+                    aria-pressed={
+                      resourceReplacement.candidateResourceId ===
+                      resource.manifestAssetId
+                    }
+                    key={resource.id}
+                    disabled={resourceReplacement.status === 'submitting'}
+                    onClick={() =>
+                      setResourceReplacement((current) =>
+                        current.status === 'closed'
+                          ? current
+                          : {
+                              ...current,
+                              status: 'ready',
+                              candidateResourceId:
+                                resource.manifestAssetId ?? '',
+                              error: '',
+                            },
+                      )
+                    }
+                  >
+                    <strong>{resource.label}</strong>
+                    <small>{resource.path}</small>
+                  </button>
+                ))}
+              </div>
+            ) : (
+              <p>当前项目没有同类别的候选资源</p>
+            )}
+            {resourceReplacement.error ? (
+              <p role="alert">{resourceReplacement.error}</p>
+            ) : null}
+            <footer>
+              <button
+                type="button"
+                onClick={() => setResourceReplacement({ status: 'closed' })}
+              >
+                取消
+              </button>
+              <button
+                type="button"
+                disabled={
+                  resourceReplacement.status === 'loading' ||
+                  resourceReplacement.status === 'submitting' ||
+                  !resourceReplacement.candidateResourceId ||
+                  resourceReplacement.expectedProjectRevision === null
+                }
+                onClick={() => void submitResourceReplacement()}
+              >
+                {resourceReplacement.status === 'submitting'
+                  ? '正在创建版本'
+                  : '创建下一版本'}
+              </button>
+            </footer>
+          </section>
+        </div>
+      ) : null}
+
       {approvalDialogOpen ? (
         <div
           className="game-approval-backdrop"
diff --git a/apps/ai-game-creator-shell/tests/appSurface/project-development.suite.ts b/apps/ai-game-creator-shell/tests/appSurface/project-development.suite.ts
index 3475b80ab..2409f4df3 100644
--- a/apps/ai-game-creator-shell/tests/appSurface/project-development.suite.ts
+++ b/apps/ai-game-creator-shell/tests/appSurface/project-development.suite.ts
@@ -1959,7 +1959,7 @@ export function registerProjectWorkbenchFoundationTests() {
     expect(screen.getByLabelText('测试切片控件').textContent).toContain(
       '当前版本未登记正式测试切片',
     );
-    expect(screen.queryByLabelText('数值微调面板')).toBeNull();
+    expect(screen.getByLabelText('数值微调面板')).not.toBeNull();
 
     fireEvent.click(screen.getByRole('tab', { name: '资源管理' }));
     fireEvent.click(screen.getByRole('button', { name: '按类型' }));
@@ -1987,6 +1987,155 @@ export function registerProjectWorkbenchFoundationTests() {
     );
   });
 
+  it('creates a compatible resource-replacement child version without switching the current version', async () => {
+    const manifest = createGameCreationAppManifest(
+      'workbench-resource-replacement',
+      '资源替换测试',
+    );
+    for (const [id, localPath] of [
+      ['hero-old', 'assets/hero-old.png'],
+      ['hero-new', 'assets/hero-new.png'],
+    ] as const) {
+      manifest.assets.push({
+        id,
+        kind: 'character',
+        mediaType: 'image/png',
+        localPath,
+        source: {
+          kind: 'generated',
+          referenceResourceIds: [],
+        },
+      });
+    }
+    const parent = runnableVersionFixture(
+      manifest.projectId,
+      'runnable-r7',
+      7,
+      {
+        resourceBindings: [{ slotId: 'hero', resourceId: 'hero-old' }],
+        resourceDescriptors: [
+          {
+            resourceId: 'hero-old',
+            name: 'hero-old.png',
+            category: 'art',
+            subtype: 'character',
+            width: 128,
+            height: 128,
+            format: 'image/png',
+          },
+        ],
+      },
+    );
+    manifest.runnableVersions = [parent];
+    manifest.currentRunnableVersionId = parent.versionId;
+    const child = runnableVersionFixture(
+      manifest.projectId,
+      'runnable-r8',
+      8,
+      {
+        parentVersionId: parent.versionId,
+        resourceBindings: [{ slotId: 'hero', resourceId: 'hero-new' }],
+        resourceDescriptors: [
+          {
+            resourceId: 'hero-new',
+            name: 'hero-new.png',
+            category: 'art',
+            subtype: 'character',
+            width: 128,
+            height: 128,
+            format: 'image/png',
+          },
+        ],
+        resourceReplacement: {
+          slotId: 'hero',
+          previousResourceId: 'hero-old',
+          replacementResourceId: 'hero-new',
+        },
+        createdReason: 'resource-replacement',
+      },
+    );
+    const resultManifest = {
+      ...manifest,
+      runnableVersions: [parent, child],
+      currentRunnableVersionId: parent.versionId,
+    };
+    const onManifestChange = vi.fn();
+    const invoke = vi.fn(
+      async (command: string, args?: Record<string, unknown>) => {
+        if (command === 'read_local_project_image_preview') {
+          return {
+            path: String(args?.relativePath ?? ''),
+            mediaType: 'image/png',
+            byteLen: 12,
+            dataUrl:
+              'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+A8AAQUBAScY42YAAAAASUVORK5CYII=',
+          };
+        }
+        if (command === 'get_local_game_project_revision') {
+          expect(args).toEqual({
+            projectPath: '/tmp/workbench-resource-replacement',
+          });
+          return { revision: 7 };
+        }
+        if (command === 'replace_local_game_runnable_resource') {
+          expect(args).toEqual({
+            projectPath: '/tmp/workbench-resource-replacement',
+            expectedProjectId: manifest.projectId,
+            parentVersionId: parent.versionId,
+            slotId: 'hero',
+            replacementResourceId: 'hero-new',
+            expectedProjectRevision: 7,
+          });
+          return { manifest: resultManifest, version: child };
+        }
+        throw new Error(`unexpected invoke ${command}`);
+      },
+    );
+    window.__TAURI__ = { core: { invoke } };
+
+    render(
+      React.createElement(ProjectDevelopmentView, {
+        projectName: manifest.name,
+        projectPath: '/tmp/workbench-resource-replacement',
+        manifest,
+        attachments: [],
+        supervisor: React.createElement('div', null, '项目总控'),
+        onManifestChange,
+      }),
+    );
+
+    fireEvent.click(screen.getByRole('button', { name: '按类型' }));
+    fireEvent.click(screen.getByRole('button', { name: /hero-old\.png/u }));
+    fireEvent.click(
+      await screen.findByRole('button', { name: '替换资源' }),
+    );
+    const dialog = await screen.findByRole('dialog', {
+      name: '选择替换资源',
+    });
+    expect(dialog.textContent).toContain('绑定槽位：hero');
+    fireEvent.click(
+      within(dialog).getByRole('button', { name: /hero-new\.png/u }),
+    );
+    const createVersionButton = within(dialog).getByRole('button', {
+      name: '创建下一版本',
+    }) as HTMLButtonElement;
+    await waitFor(() => expect(createVersionButton.disabled).toBe(false));
+    fireEvent.click(createVersionButton);
+
+    expect(
+      await screen.findByText(
+        '已创建资源替换版本 runnable-r8；当前运行版本保持不变',
+      ),
+    ).not.toBeNull();
+    expect(onManifestChange).toHaveBeenCalledWith(resultManifest);
+    expect(resultManifest.currentRunnableVersionId).toBe(parent.versionId);
+    expect(
+      invoke.mock.calls.some(
+        ([command]) => command === 'launch_local_game_runnable_version',
+      ),
+    ).toBe(false);
+  });
+
   it('unloads the old iframe before switching to another runnable version snapshot', async () => {
     const manifest = createGameCreationAppManifest(
       'workbench-version-switch',
@@ -2249,6 +2398,234 @@ export function registerProjectWorkbenchFoundationTests() {
     expect(screen.getByText('starting')).not.toBeNull();
   });
 
+  it('writes only registered tunable parameters while paused and marks the session and slice stale', async () => {
+    const manifest = createGameCreationAppManifest(
+      'workbench-tunable-parameters',
+      '数值微调测试',
+    );
+    const version = runnableVersionFixture(
+      manifest.projectId,
+      'runnable-r12',
+      12,
+      {
+        testSlices: [
+          {
+            sliceId: 'core',
+            versionId: 'runnable-r12',
+            title: '核心玩法',
+            order: 0,
+            startCondition: '游戏 ready',
+            endCondition: '核心循环结束',
+            status: 'idle',
+          },
+        ],
+      },
+    );
+    manifest.runnableVersions = [version];
+    manifest.currentRunnableVersionId = version.versionId;
+    const previewIdentity = {
+      previewId: 'preview-tunable-1',
+      origin: 'http://127.0.0.1:4399',
+    };
+    manifest.preview = {
+      status: 'running',
+      url: `${previewIdentity.origin}/`,
+      port: 4399,
+    };
+    const tunableParameter = {
+      parameterId: 'player.speed',
+      label: '移动速度',
+      valueType: 'number' as const,
+      defaultValue: 5,
+      currentValue: 5,
+      min: 1,
+      max: 10,
+      step: 0.5,
+      unit: '格/秒',
+      writePath: 'game/tunable-values.json#/values/player.speed',
+      effectMode: 'next-relaunch' as const,
+      editablePhase: 'paused' as const,
+      codeMutationAllowed: false as const,
+    };
+    const invoke = vi.fn(
+      async (command: string, args?: Record<string, unknown>) => {
+        if (command === 'read_local_game_tunable_parameters') {
+          expect(args).toEqual({
+            projectPath: '/tmp/workbench-tunable-parameters',
+            expectedProjectId: manifest.projectId,
+            versionId: version.versionId,
+          });
+          return {
+            versionId: version.versionId,
+            projectRevision: 12,
+            parameters: [tunableParameter],
+          };
+        }
+        if (command === 'launch_local_game_runnable_version') {
+          return {
+            manifest,
+            version,
+            preview: {
+              url: `${previewIdentity.origin}/`,
+              port: 4399,
+              root: '/tmp/workbench-tunable-parameters',
+            },
+            previewIdentity,
+          };
+        }
+        if (command === 'update_local_game_tunable_parameter') {
+          expect(args).toEqual({
+            projectPath: '/tmp/workbench-tunable-parameters',
+            expectedProjectId: manifest.projectId,
+            versionId: version.versionId,
+            parameterId: 'player.speed',
+            value: 7.5,
+            expectedProjectRevision: 12,
+          });
+          return {
+            revision: 13,
+            parameters: [{ ...tunableParameter, currentValue: 7.5 }],
+          };
+        }
+        throw new Error(`unexpected invoke ${command}`);
+      },
+    );
+    window.__TAURI__ = { core: { invoke } };
+
+    render(
+      React.createElement(ProjectDevelopmentView, {
+        projectName: manifest.name,
+        projectPath: '/tmp/workbench-tunable-parameters',
+        manifest,
+        attachments: [],
+        supervisor: React.createElement('div', null, '项目总控'),
+      }),
+    );
+    fireEvent.click(screen.getByRole('tab', { name: '运行' }));
+    const iframe = (await screen.findByTitle(
+      '数值微调测试 游戏运行画面',
+    )) as HTMLIFrameElement;
+    const frameWindow = iframe.contentWindow;
+    if (!frameWindow) {
+      throw new Error('missing iframe contentWindow');
+    }
+    const postMessage = vi.spyOn(frameWindow, 'postMessage');
+    fireEvent.load(iframe);
+    const start = postMessage.mock.calls[0]?.[0] as Record<string, unknown>;
+    const runtimeMessage = (
+      sequence: number,
+      requestId: string,
+      type: string,
+      payload: Record<string, unknown>,
+      responseTo?: unknown,
+    ) => ({
+      schemaVersion: 'game-creator-runtime-message.v1',
+      protocolVersion: 'game-creator-run-bridge.v1',
+      requestId,
+      responseTo,
+      sessionId: start.sessionId,
+      previewId: start.previewId,
+      projectId: start.projectId,
+      sequence,
+      type,
+      versionId: start.versionId,
+      projectRevision: start.projectRevision,
+      payload,
+    });
+    await act(async () => {
+      window.dispatchEvent(
+        new MessageEvent('message', {
+          data: runtimeMessage(
+            1,
+            'runtime-ready-tunable',
+            'runtime.ready',
+            { capabilities: ['state', 'slice', 'inspection'] },
+            start.requestId,
+          ),
+          origin: previewIdentity.origin,
+          source: frameWindow,
+        }),
+      );
+      await Promise.resolve();
+    });
+
+    const speedInput = (await screen.findByLabelText(
+      '移动速度',
+    )) as HTMLInputElement;
+    expect(speedInput.disabled).toBe(true);
+    fireEvent.click(screen.getByRole('button', { name: '播放测试切片' }));
+    const sliceStart = postMessage.mock.calls.at(-1)?.[0] as Record<
+      string,
+      unknown
+    >;
+    await act(async () => {
+      window.dispatchEvent(
+        new MessageEvent('message', {
+          data: runtimeMessage(
+            2,
+            'runtime-slice-tunable',
+            'runtime.slice',
+            { sliceId: 'core', title: '伪造标题', status: 'playing' },
+            sliceStart.requestId,
+          ),
+          origin: previewIdentity.origin,
+          source: frameWindow,
+        }),
+      );
+      await Promise.resolve();
+    });
+    fireEvent.click(screen.getByRole('button', { name: '暂停' }));
+    const pause = postMessage.mock.calls.at(-1)?.[0] as Record<string, unknown>;
+    await act(async () => {
+      window.dispatchEvent(
+        new MessageEvent('message', {
+          data: runtimeMessage(
+            3,
+            'runtime-pause-tunable',
+            'runtime.state',
+            { status: 'paused' },
+            pause.requestId,
+          ),
+          origin: previewIdentity.origin,
+          source: frameWindow,
+        }),
+      );
+      await Promise.resolve();
+    });
+    expect(speedInput.disabled).toBe(false);
+    fireEvent.change(speedInput, { target: { value: '7.5' } });
+    fireEvent.click(
+      within(screen.getByLabelText('数值微调面板')).getByRole('button', {
+        name: '保存',
+      }),
+    );
+
+    expect(
+      await screen.findByText(
+        '数值已写入编辑态 revision 13；当前运行会话已失效，变更将在下一可运行版本中生效',
+      ),
+    ).not.toBeNull();
+    const sliceButtons = screen
+      .getByLabelText('测试切片控件')
+      .querySelectorAll<HTMLButtonElement>('button');
+    expect(sliceButtons[1]?.disabled).toBe(true);
+
+    fireEvent.change(screen.getByLabelText('自然语言匹配数值参数'), {
+      target: { value: '新增无限金币参数' },
+    });
+    fireEvent.click(screen.getByRole('button', { name: '匹配参数' }));
+    expect(
+      screen.getByText(
+        '未匹配到已登记参数；自然语言不能新增代码或任意写入路径',
+      ),
+    ).not.toBeNull();
+    expect(
+      invoke.mock.calls.filter(
+        ([command]) => command === 'update_local_game_tunable_parameter',
+      ),
+    ).toHaveLength(1);
+  });
+
   it('runs formal P4 slices and resolves P5 hover IDs from trusted version metadata', async () => {
     const manifest = createGameCreationAppManifest(
       'workbench-slices',
diff --git a/docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md b/docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md
index 3c059d67e..986c089ef 100644
--- a/docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md
+++ b/docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md
@@ -126,7 +126,7 @@ idle -> focused(document|art|audio|version) -> idle
 - 文档：合法 Agent 文本回执直接使用对话投影内容；项目文件只允许读取当前 manifest 已登记资产或已完成任务产物中的 Markdown、文本、JSON、YAML、TOML，必须经过 `file.read` auto 权限、相对路径、项目边界、普通文件、符号链接 / 硬链接、读取漂移、2 MiB、UTF-8 与扩展名白名单校验。正文使用不执行 HTML、不加载远程图片、不产生可点击外链的安全 Markdown 渲染，并在中央画布内独立滚动；读取失败显示错误空态。
 - 美术：PNG、JPEG、WEBP 继续使用图片魔数与像素边界预览；GIF、SVG、AVIF、BMP、MP4、WebM、MOV 通过新增受控媒体读取链路按文件签名校验后在中央画布放大聚焦。SVG 额外拒绝脚本、事件处理器、外部资源引用和实体声明；视频使用内置播放控件。读取失败显示错误空态。
 - 音频：只读取 manifest 已登记音频或已成功导入且登记到 manifest 的附件，按文件签名接受 MP3、WAV、OGG / Opus、M4A、AAC、FLAC；聚焦态展示实际格式、浏览器解码后的时长以及带播放进度和暂停能力的内置播放器。音频任务声明中的未登记路径继续不得读取或播放。
-- 版本：只展示 manifest 中正式、不可变的迭代版本记录；版本卡展示项目修订、创建原因与父版本，聚焦态同时展示直接子版本和资源绑定。点击版本卡后高亮仍存在于当前资源投影中的引用资源；缺失历史资源只保留绑定身份，不生成幽灵资源卡。资源替换仍留给后续切片。
+- 版本：只展示 manifest 中正式、不可变的迭代版本记录；版本卡展示项目修订、创建原因与父版本，聚焦态同时展示直接子版本和资源绑定。点击版本卡后高亮仍存在于当前资源投影中的引用资源；缺失历史资源只保留绑定身份，不生成幽灵资源卡。当前可运行版本绑定的美术 / 音频资源可通过独立候选面板发起兼容替换，并追加下一不可变版本。
 - mentor 最新决定：资源聚焦不提供工具栏，也不提供工具侧边栏。
 - 点击资源后，中央主视窗从 `resources.list` 切换为 `resources.focused.document / art / audio / version`，左侧平台导航、右侧 Supervisor 对话和底部 Agent 状态栏保持原位；聚焦容器只包含标题、资源主体、必要元数据与右上角收起按钮，不使用页面级浮层或可拖动标题栏。
 - 退出聚焦后恢复进入前的搜索条件、dependency / type 布局模式、资源画布滚动位置和选中资源；这些只属于当前前端会话，不写入布局 sidecar。
@@ -160,7 +160,7 @@ P0 中 `approvalMode` 只能有效写入 `strict`；其它值只能作为不可
 
 ### 5.2 资源画布布局（P1）
 
-实现状态（2026-08-03）：dependency / type 双模式通过项目内 CAS sidecar 独立持久化；dependency 模式由 Tauri Rust 只读构建关系拓扑与确定性依赖深度、前端 SVG 派生几何，图结构和线段均不写入布局 sidecar。依赖图加载完成前设布局初始化屏障，避免以临时 `dependencyDepth=0` 生成并持久化错误坐标。当前用户入口只允许自动布局与资源卡点击；资源卡手动拖动已按 mentor 决定暂缓。历史 sidecar 坐标继续只读恢复，底层布局读写与 CAS 合同保留，但当前没有用户手动布局入口。资源替换、缩放 / 平移等其余 P1 能力仍按本文非目标保持未实现。
+实现状态（2026-08-03）：dependency / type 双模式通过项目内 CAS sidecar 独立持久化；dependency 模式由 Tauri Rust 只读构建关系拓扑与确定性依赖深度、前端 SVG 派生几何，图结构和线段均不写入布局 sidecar。依赖图加载完成前设布局初始化屏障，避免以临时 `dependencyDepth=0` 生成并持久化错误坐标。当前用户入口只允许自动布局与资源卡点击；资源卡手动拖动已按 mentor 决定暂缓。历史 sidecar 坐标继续只读恢复，底层布局读写与 CAS 合同保留，但当前没有用户手动布局入口。该阶段当时未实现资源替换、缩放 / 平移；其中资源替换已于 2026-08-04 按 P2 独立候选面板与不可变子版本合同补齐。
 
 ```ts
 type ProjectResourceCanvasLayout = {
@@ -440,7 +440,7 @@ type GameRuntimeMessage = {
 - 宿主只接受 `event.source === 当前 iframe.contentWindow` 且 `event.origin === PreviewRegistry 返回 origin` 的消息；随后逐项校验 protocol、schema、projectId、versionId、projectRevision、previewId 与 sessionId。iframe 重载、版本切换、preview 替换和会话停止时，先发送当前 session 的 `host.stop`，再清空请求表、序列与 Runtime 投影。
 - 单条消息结构化序列化后最多 `64 KiB`，顶层和 payload 都使用字段白名单。`runtime.ready` 只声明 `state / slice / inspection` 能力；`runtime.state` 只上报运行状态和短摘要；`runtime.error` 只上报受限错误码、文本和是否可恢复；`runtime.slice` 只上报切片身份、标题、状态和摘要；`runtime.inspection` 只上报受限 label/summary 与最多 32 个标量 metric。路径、URL、HTML、脚本、宿主命令、嵌套对象与未知字段一律拒绝，游戏消息不能触发 Tauri、文件、命令、Agent 或生成能力。
 - 预览服务在响应 HTML 时只注入宿主拥有的同源 `game-creator-run-bridge.v1` bootstrap，不修改不可变版本快照字节或摘要。bootstrap 为旧可运行版本提供 ready/state/pause/resume/stop 基线，并向游戏暴露仅能上报上述五类安全消息的 API；权限和安全结论始终由宿主校验，不信任游戏脚本自报。
-- revision 不一致继续表示编辑工作树已经晚于当前 Session 绑定版本；Session 标记 `stale`，但不热更新、不改写旧版本，也不把 stale 当失败。本次不实现 P2 资源替换与下一版本，也不实现测试切片编排、参数写入或数值面板；`runtime.slice` 只是 P3 传输层的安全上报能力。
+- revision 不一致继续表示编辑工作树已经晚于当前 Session 绑定版本；Session 标记 `stale`，但不热更新、不改写旧版本，也不把 stale 当失败。P3 阶段自身只建立安全传输层；资源替换、正式切片和数值写入分别由后续 P2、P4 / P5、P6 合同实现，游戏消息本身始终无权触发这些宿主写操作。
 
 ### 5.6 正式测试切片与可信悬停信息（P4 / P5）
 
@@ -451,7 +451,16 @@ type GameRuntimeMessage = {
 - P5 不读取 iframe DOM。游戏捕获可检查对象 hover 后，只能通过 `runtime.inspection` 上报 `targetKind=resource|entity` 与稳定 `targetId`；离开对象上报 `targetKind=none`。宿主只在当前版本 `resourceBindings` 中把 resource ID 或实体 slot ID 解析到 `resourceDescriptors`，匹配后展示可信名称、类别 / 格式、尺寸规格、所属版本和绑定槽位，并仅在该资源仍存在于当前资源画布时提供“在资源管理中定位”按钮；定位会停止当前一次性运行会话、清除筛选并选中对应资源卡。未匹配、离开对象、切换切片或会话失效时清空信息。
 - 游戏上报的 label、summary 和 metrics 仍是不可信提示，不能覆盖宿主资源元数据，也不能触发 Tauri、文件、命令、Agent、生成或资源替换能力。
 
-### 5.7 Agent 泥点归因（P2）
+### 5.7 资源替换与数值微调（P2 / P6）
+
+- P2 只能从 `currentRunnableVersionId` 指向的当前版本及其既有绑定槽位发起。候选资源必须来自当前 manifest，Rust 读取真实项目文件元数据并严格比较 `category + subtype + sizeSpec + format`；PNG 等可解码图片比较宽高，WAV 比较声道、采样率、时长和 codec，无法取得可信规格的音频 / 视频失败关闭。
+- 替换在项目写锁和 expected revision 下执行。新版本复制父版本不可变快照，只在父资源原路径写入候选字节，追加 `createdReason=resource-replacement` 与替换前后资源记录；父快照和当前运行版本指针保持不变，用户必须明确切换或重新拉起新版本。
+- P6 参数定义由不可变版本快照内 `game/tunable-parameters.json` 提供，schema 固定为 `game-creator-tunable-parameters.v1`。定义包含稳定 ID、显示名、类型、默认值、当前值、范围 / 步长或枚举、单位、权威 writePath、`effectMode=next-relaunch`、`editablePhase=paused` 与 `codeMutationAllowed=false`。
+- 编辑态值只写 `game/tunable-values.json`，schema 固定为 `game-creator-tunable-values.v1`，且 writePath 只能是 `game/tunable-values.json#/values/<parameterId>`。Rust 校验参数是否登记、类型、范围、步长、枚举和 expected revision；运行中全部只读，只有未失效的暂停会话可提交。
+- 保存成功只推进编辑态 revision，不修改当前不可变版本或 iframe；当前 Session 与活动切片立即标记 `stale`，新值由后续 Agent revision 的新不可变版本在下一次启动时读取。自然语言只匹配现有 ID / 名称，不能生成参数、代码或任意写入路径。
+- 新建项目的 `code-prototype` 正式产物包含 `game/index.html`、参数注册表和值文件；游戏只在每次新启动时读取值文件，不监听运行中热更新。旧版本缺少注册表时兼容为空列表。
+
+### 5.8 Agent 泥点归因
 
 ```ts
 type ProjectAgentMudPointAttribution = {
@@ -471,7 +480,7 @@ type ProjectAgentMudPointAttribution = {
 ### P0：合同冻结
 
 - 冻结 `RunnableGameVersion`、`GameTestSlice`、`GameRunSession`、`GameTunableParameterDefinition`、`GameResourceDescriptor`、`GameHostMessage`、`GameRuntimeMessage`。
-- 冻结 revision 不一致与 stale 语义；切片和参数属于正式 P2，技术方案不得再称为本地 UI 草稿。
+- 冻结 revision 不一致与 stale 语义；资源替换、切片和参数分别属于正式 P2、P4 / P5、P6，技术方案不得再称为本地 UI 草稿。
 - 明确 `versions` 不是运行授权，`runnableVersions` 才是唯一权威来源。
 
 ### P1
@@ -482,9 +491,10 @@ type ProjectAgentMudPointAttribution = {
 - 当前版本绑定资源在 dependency / type 两种资源管理布局中高亮。
 - 无版本、损坏、revision 不一致和 preview 启动失败提供独立错误状态。
 
-### P2（本次跳过）
+### P2
 
-- 资源替换与下一不可变版本按独立方案后续实现；P3 不得提前写入 `resource-replacement` 版本。
+- 从当前版本绑定资源打开独立候选面板，使用可信媒体规格、expected revision 和项目锁完成兼容校验。
+- 追加 `resource-replacement` 子版本和不可变快照；父版本与当前运行版本选择保持不变。
 
 ### P3
 
@@ -503,6 +513,12 @@ type ProjectAgentMudPointAttribution = {
 - 游戏只上报稳定实体 / 资源 ID，宿主只用当前版本绑定与资源描述解析可信信息。
 - 离开对象、切换切片、版本 / preview / session 变化时清空信息；不读取跨 origin DOM，不信任游戏展示内容。
 
+### P6
+
+- 从不可变版本读取正式参数注册表；运行中只读，未失效的暂停会话可以向固定编辑态值文件写入已登记参数。
+- 保存后推进编辑 revision，把当前会话和活动切片标记为 stale；新值只在下一可运行版本重新拉起后生效。
+- 自然语言仅匹配已有参数，不新增代码、参数身份或任意 writePath。
+
 ## 7. 验收
 
 ### 7.1 P0 验收
@@ -572,9 +588,17 @@ type ProjectAgentMudPointAttribution = {
 5. 信息面板首版展示资源名称、类别 / 格式、尺寸规格、所属版本和绑定位置；资源仍存在于资源画布时可停止当前运行会话并一键定位对应资源卡；离开对象或上报未绑定 ID 时清空。
 6. P4 / P5 全程不写参数、不修改代码、不创建下一版本、不实现资源替换，也不让游戏消息触发任何宿主副作用。
 
+### 7.8 P2 / P6 资源替换与数值微调验收
+
+1. 只有当前可运行版本的既有美术 / 音频绑定显示替换入口；候选面板独立弹出，类别、subtype、格式或可信尺寸规格不一致时 Rust 拒绝且 revision 不推进。
+2. 兼容替换生成新的 `resource-replacement` 子版本和独立快照，父快照字节不变，`currentRunnableVersionId` 不自动切换，界面明确提示当前运行版本保持不变。
+3. 数值面板只展示当前不可变版本登记的参数；运行中控件只读，只有未失效 paused Session 可保存，未登记 ID、非法 writePath、类型、范围、步长或枚举值均失败关闭。
+4. 保存只写编辑态 `game/tunable-values.json` 并推进 revision，不修改当前快照或 iframe；当前 Session 和活动切片立刻 stale，所有切片写控制禁用，下一可运行版本重新拉起后才消费新值。
+5. 自然语言输入只能匹配已有参数名称 / ID；无法匹配时给出明确提示，不能创建参数、代码或任意路径。游戏 runtime 消息不能调用 P2 / P6 Tauri 命令。
+
 ## 8. 非目标
 
-- 当前收口不实现资源卡手动拖动，也不实现资源聚焦工具栏、资源聚焦工具侧边栏、美术编辑、音频编辑 / 替换、资源重新生成、资源替换、手动创建版本或版本回滚。P1 已实现运行版本登记、选择、切换和运行态消费，P3 已实现运行会话与 Host/Game Bridge，P4 / P5 已实现正式测试切片和可信悬停信息；P2 的资源替换、下一版本、数值参数写入、自然语言新增微调项和泥点归因仍不在本次范围。
+- 当前收口不实现资源卡手动拖动，也不实现资源聚焦工具栏、资源聚焦工具侧边栏、美术编辑生成新资源、资源重新生成、手动创建任意版本或版本回滚。P1 已实现运行版本登记、选择、切换和运行态消费，P2 已实现兼容资源替换与下一不可变版本，P3 已实现运行会话与 Host/Game Bridge，P4 / P5 已实现正式测试切片和可信悬停信息，P6 已实现登记参数的编辑态微调。泥点归因、任意自然语言新增参数和运行中热修改仍不在本次范围。
 - 本切片不持久化资源聚焦状态、画布缩放 / 平移、搜索条件、筛选条件或当前 mode；聚焦退出时的列表上下文恢复只限当前前端会话，这些状态如需跨重启保存必须另行扩展合同，不能塞入 `game-creator-resource-layout.v1`。
 - 不修改 SpacetimeDB schema。
 - 不开放普通用户 Agent.md/Skill。
diff --git a/docs/project-memory/shared-memory/decision-log.md b/docs/project-memory/shared-memory/decision-log.md
index 78b790cdd..36a405670 100644
--- a/docs/project-memory/shared-memory/decision-log.md
+++ b/docs/project-memory/shared-memory/decision-log.md
@@ -1,5 +1,14 @@
 # 决策记录
 
+## 2026-08-04 工作台 P2/P6 以不可变子版本和编辑态参数文件实现显式写入
+
+- 背景：P1 已建立唯一可运行版本和不可变快照，P3-P5 已建立一次性会话、正式切片和可信悬停信息；飞书后续要求资源替换与数值微调，但禁止原地改版本、运行中热写 iframe、信任展示文案或让自然语言生成任意代码 / 路径。
+- P2 决策：资源替换只从当前版本既有绑定发起，候选必须来自 manifest。Rust 使用 category、subtype、format 与可信 sizeSpec 校验；图片读取实际宽高，WAV 解析声道、采样率、时长和 codec，规格缺失失败关闭。提交使用 expected revision 和项目锁，从父快照创建 `resource-replacement` 子快照，父版本与当前选择指针保持不变。
+- P6 决策：参数定义冻结在版本快照 `game/tunable-parameters.json`，编辑值只写工作树 `game/tunable-values.json`。writePath 固定到对应 parameterId，effectMode 固定 `next-relaunch`，editablePhase 固定 `paused`，codeMutationAllowed 固定 false；Rust 校验登记身份、类型、范围、步长、枚举与 revision。保存后当前 Session / Slice stale，不热推 iframe，也不创建未经完整验证的版本。
+- 生成合同：`code-prototype` 在完整 DAG 与 game-chat lane 中都必须交付 `game/index.html`、参数注册表和值文件，并让游戏只在新启动时读取值文件。旧版本缺注册表时兼容为空列表；存在注册表 / 值文件时，可运行版本登记前执行严格语义校验。
+- UI 与安全：资源替换使用独立候选面板并明确提示新版本未自动切换；数值运行中只读、暂停可写，自然语言仅匹配已有名称 / ID。合法游戏消息继续不能触发 P2 / P6 Tauri、文件或 Agent 副作用。
+- 关联文档：`docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md`、`docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md`。
+
 ## 2026-08-04 工作台 P4/P5 以不可变版本合同驱动正式切片与可信悬停信息
 
 - 背景：P0/P1 已建立不可变可运行版本，P3 已建立一次性 Host/Game Bridge；运行页仍缺少来自正式合同的测试切片控制和不读取 iframe DOM 的游戏内悬停信息。本轮按需求明确跳过 P2，不能借切片或信息面板加入资源替换、参数写入、代码修改或下一版本创建。
diff --git a/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md b/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md
index 637185889..fd7361a74 100644
--- a/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md
+++ b/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md
@@ -364,7 +364,7 @@ game-project/
 - 中间主视窗提供 `资源管理 / 运行` 切换。2026-08-04 起运行入口不再读取 `code-prototype` 任务状态，只读取 manifest 的正式 `runnableVersions + currentRunnableVersionId`；无版本时保持视觉不可用但仍可点击查看“当前无可运行版本”，不能使用会阻断说明交互的原生 `disabled` 或 `aria-disabled`。切回资源管理只修改前端展示态，不伪造后端预览暂停结果。
 - 资源管理从当前 `GameCreationAppManifest`（包含可选 `versions`）、合法 Agent 文本回执和已导入附件派生资源，固定按文档、项目版本、美术资源、音乐音效资源分区；未知任务产物不再兜底为版本，任务声明中的未登记音频也不冒充正式音频。`按依赖 / 按类型` 使用各自前端排列，dependency 模式额外绘制当前 manifest 与资源投影可证明的依赖关系。排列与图层都不写回 manifest，不能推断或伪造缺失依赖。
 - 资源卡支持点击聚焦、搜索和类型筛选。2026-07-28 起完成两套二维坐标与本地 CAS sidecar；2026-07-31 起 dependency 模式增加不持久化的原生 SVG 关系图层。2026-08-03 mentor 决定暂缓资源卡拖动，当前卡片不挂载 Pointer Down / Move / Up / Cancel 拖动入口，只允许自动布局和点击聚焦。聚焦态替换中央主视窗内容，保留左侧导航、右侧对话和底部 Agent 状态栏，退出后恢复搜索、布局模式、滚动位置与选中资源；不提供工具栏、工具侧边栏或可拖动标题栏。阶段四已补齐安全本地文档、扩展美术媒体与音频聚焦，正文独立滚动，视频 / 音频使用内置媒体控件，失败显示空态；美术编辑、音频编辑 / 替换、版本替换或运行模块仍不在本阶段。
-- 运行表现层嵌入当前项目的 loopback 游戏画面。P1 由专用可运行版本命令停止旧 preview、卸载 iframe、复核版本快照并启动目标版本；普通 `preview.start` 继续服务 Agent 当前工作树验证，不能作为工作台运行授权或旧版本切换入口。2026-08-04 起 P3 在该生命周期上接入运行会话与 Host/Game Bridge；P2 资源替换与下一版本继续跳过，测试切片编排和参数调整也不在 P3 内接线。
+- 运行表现层嵌入当前项目的 loopback 游戏画面。P1 由专用可运行版本命令停止旧 preview、卸载 iframe、复核版本快照并启动目标版本；普通 `preview.start` 继续服务 Agent 当前工作树验证，不能作为工作台运行授权或旧版本切换入口。2026-08-04 起 P3 在该生命周期上接入运行会话与 Host/Game Bridge；P3 阶段自身未接入资源替换、下一版本、测试切片编排或参数调整，P2 / P6 的当前实现以本节后续对应专节为准。
 - 右侧继续复用现有 Project Supervisor 会话、Runtime 澄清和确认链路；输入区展示 `严格审批 / 风险审批 / 无需审批` 独立面板。P0 只有严格审批可选；风险审批和无需审批保持视觉不可用但允许点击查看原因，不替代 Runtime 的逐动作权限、确认、sandbox 或 reconciliation 门禁。风险 Rank 算法记录在 `docs/project-memory/todos/【待解决】AI游戏创作高风险审批Rank-2026-07-20.md`，前端不得自行计算。
 - 底部状态栏默认展示策划、美术、程序 3 组，并允许在同一栏展开数值、音频、发布组；状态来自 manifest 与当前 Supervisor run 的 Runtime，悬停显示当前任务与进度。累计泥点必须等待后端计费归因投影；Agent.md 编辑和自定义 Skill 在来源审核、版本、权限、sandbox 与回滚合同完备前不向普通用户开放。
 - 当前 run 专业状态与项目历史成果分离：状态继续严格匹配当前 `parentRunId`；已有文本成果从专业 Agent 持久对话中合法的 `agent-finalization-<32 lower hex>` assistant 恢复，并以“历史成果”来源投影到资源管理文档区。新 run 失败、待确认、候选为空或持久对话瞬时读取失败不得清除已恢复的旧成功回执，普通失败 assistant 也不得被当作成果。
@@ -431,7 +431,7 @@ game-project/
 - wire protocol 固定为 `game-creator-run-bridge.v1`，Host/Runtime 分别使用 `game-creator-host-message.v1` 与 `game-creator-runtime-message.v1`。所有消息携带 request/session/preview/project/version/revision 身份；Host 类型只开放 start/pause/resume/stop/state.request/inspection.request，Runtime 类型只开放 ready/state/error/slice/inspection。
 - `message` listener 先检查当前 iframe `contentWindow` 与 Registry origin，再执行 64 KiB、plain object、精确字段、JavaScript 安全正整数、连续 sequence、request/response 类型相容和 payload 专用校验。inspection metrics 只允许最多 32 个标量；全部文本有界并拒绝路径、URL、HTML/脚本和宿主命令痕迹。通过的消息只更新 React 运行会话投影，不调用 Tauri invoke，也不进入 Agent/文件/命令/生成链路。
 - loopback server 对 HTML 响应注入固定同源外部 bootstrap 标签，并在保留原文件不变的前提下提供 `/.genarrative/game-bridge.v1.js`。bootstrap 只接受 parent 发来的合法 Host envelope，锁定首个 start 的 origin 与完整身份，基线响应 ready/state 并处理 pause/resume/stop/state/inspection；同时暴露受限 reportState/reportError/reportSlice/reportInspection API，业务游戏不能指定宿主命令、文件路径或 envelope 身份。
-- 工作台显示真实 session 状态并提供 pause/resume；ready 之前保持 starting，error 进入 failed，runtime state 只按白名单状态推进。`runtime.slice` 与 `runtime.inspection` 作为安全传输与展示投影存在，不等于已实现 P2 测试切片流程、检查工具或数值编辑。
+- 工作台显示真实 session 状态并提供 pause/resume；ready 之前保持 starting，error 进入 failed，runtime state 只按白名单状态推进。`runtime.slice` 与 `runtime.inspection` 在 P3 中只提供安全传输，正式切片、可信检查信息与数值编辑分别由 P4 / P5 / P6 消费。
 - 定向门禁覆盖 Rust Registry 身份轮换和 HTML/bootstrap 响应；TypeScript 纯协议覆盖白名单、容量、身份、sequence、request 关联与危险 payload；AppSurface 覆盖真实 iframe source/origin、reload/session 失效、版本切换卸载和 UI 状态。最后运行 shared-contracts、Tauri project/preview、AGC typecheck、定向 Vitest、编码检查与 `git diff --check`。
 
 ### 正式测试切片与可信悬停信息 P4 / P5
@@ -440,7 +440,16 @@ game-project/
 - Host Bridge 增加带 `{ sliceId }` 白名单 payload 的 `host.slice.start / host.slice.stop`。bootstrap 只做协议校验、受限事件转发和 `runtime.slice` 基线响应；真实游戏可以通过同源 `genarrative:host-message` 消费切片命令，并用受限桥 API 上报 completed / failed。Host 只接受当前合同中的切片 ID 和合法状态迁移。
 - 工作台控制条使用当前版本的正式切片顺序。切换先 stop 后 start；completed 自动暂停；failed、stale、身份漂移或 reload 后控制失效。切片状态属于一次性前端运行会话，不写 manifest。
 - P5 继续禁止宿主读取 iframe DOM。游戏在自身 hit-test / hover 逻辑中仅上报 `targetKind=resource|entity|none` 和稳定 `targetId`；宿主按当前版本 `resourceBindings` 的 resourceId / slotId 解析 `resourceDescriptors`，只展示宿主可信元数据。匹配资源仍存在于当前资源 read model 时，定位按钮先停止并失效当前运行会话，再清除资源筛选、切回资源管理并选中对应资源卡；未命中、离开对象、切片切换和会话失效立即清空。
-- 该阶段不实现 P2：不写数值、不修改代码、不替换资源、不追加资源替换版本，也不允许消息触发 Tauri、文件、命令、Agent 或生成。
+- P4 / P5 自身不写数值、不修改代码、不替换资源、不追加资源替换版本，也不允许消息触发 Tauri、文件、命令、Agent 或生成；P2 / P6 只通过宿主显式 UI 与专用 Tauri 命令执行。
+
+### 资源替换与数值微调 P2 / P6
+
+- P2 命令 `replace_local_game_runnable_resource` 只接受当前版本、既有 slot、manifest 候选资源、expected project revision 与 expected project ID。Rust 在项目写锁内读取可信文件元数据；图片比较可解码宽高，WAV 解析 RIFF `fmt/data` 后比较声道、采样率、时长和 codec，缺失可信规格的音频 / 视频失败关闭。通过后从父快照构建新快照，在父资源原路径替换字节，追加 `resource-replacement` 记录；父快照和 `currentRunnableVersionId` 不变。
+- `GameResourceDescriptor` 除宽高 / 时长外可冻结 `channelCount / sampleRateHz / codec`。这些字段来自 Rust 字节解析，不来自 Agent 文案、文件名、浏览器 metadata 或游戏上报；旧版本字段缺失时只读兼容，但不能据此放行严格替换。
+- P6 命令 `read_local_game_tunable_parameters` 从版本快照读取 `game/tunable-parameters.json`，再叠加编辑工作树 `game/tunable-values.json`；`update_local_game_tunable_parameter` 在项目锁内执行 expected revision、登记 ID、类型、范围、步长、枚举和固定 writePath 校验，原子写值文件并推进编辑 revision。允许值类型为 integer / number / boolean / enum，最多 128 项。
+- 前端运行中只读，只有 `paused && !stale` 可保存。成功后调用 `LocalGamePreviewFrame.markStale('project-revision-changed')`，同时把活动切片标记 stale 并禁用切片写控制；不向 iframe 发热更新，不修改已有版本，也不自动创建未经完整验证的版本。
+- `code-prototype` 的正式 owner 产物新增参数注册表和值文件，完整 DAG 与 game-chat lane 使用同一合同。注册表固定 `game-creator-tunable-parameters.v1`，值文件固定 `game-creator-tunable-values.v1`；新游戏在每次启动时读取值文件，运行中不监听文件变化。旧项目没有注册表时返回空参数列表。
+- AppSurface 覆盖 P2 候选面板、revision 参数、子版本不自动切换，以及 P6 运行只读、暂停保存、Session / Slice stale、自然语言不能新增参数；Rust 定向测试覆盖不可变父快照、尺寸拒绝、WAV 可信规格和注册表白名单。
 
 历史命令式 drag preview 句柄与局部连接索引可以保留，但项目工作台不再向资源卡传入该入口。拖动热路径、4096 张真实卡片拖动重渲染和 Chromium p95 门槛统一暂缓；当前回归只要求 Pointer Move 不改变卡片坐标、SVG path 或布局 revision。`ResizeObserver` 仍保持单图层单实例，任何实时 DOM 几何都不得通过 Tauri IPC 往返 Rust。
 
diff --git a/packages/shared/src/contracts/gameCreationApp.ts b/packages/shared/src/contracts/gameCreationApp.ts
index dc7b3386f..c9ac49bcf 100644
--- a/packages/shared/src/contracts/gameCreationApp.ts
+++ b/packages/shared/src/contracts/gameCreationApp.ts
@@ -375,8 +375,14 @@ export const GAME_CREATION_APP_SEED_TASKS = [
       'art-polish',
       'audio-asset-plan',
     ],
-    artifacts: ['game/'],
-    acceptanceCriteria: ['本地 Web 游戏项目可以通过 HTTP server 打开'],
+    artifacts: [
+      'game/index.html',
+      'game/tunable-parameters.json',
+      'game/tunable-values.json',
+    ],
+    acceptanceCriteria: [
+      '本地 Web 游戏项目可以通过 HTTP server 打开，且登记的数值参数可在下一次启动时读取',
+    ],
   },
   {
     id: 'quality-review',
@@ -559,7 +565,16 @@ export interface GameIterationVersion {
 export const RUNNABLE_GAME_VERSION_SCHEMA_VERSION =
   'game-creator-runnable-version.v1' as const;
 
-export type RunnableGameVersionCreatedReason = 'initial' | 'agent-revision';
+export type RunnableGameVersionCreatedReason =
+  | 'initial'
+  | 'agent-revision'
+  | 'resource-replacement';
+
+export interface RunnableGameResourceReplacement {
+  slotId: string;
+  previousResourceId: string;
+  replacementResourceId: string;
+}
 
 export interface RunnableGameVersionValidation {
   staticSmokePassed: true;
@@ -582,6 +597,7 @@ export interface RunnableGameVersion {
   resourceBindings: GameIterationVersionResourceBinding[];
   testSlices?: GameTestSlice[];
   resourceDescriptors?: GameResourceDescriptor[];
+  resourceReplacement?: RunnableGameResourceReplacement | null;
   createdReason: RunnableGameVersionCreatedReason;
   validation: RunnableGameVersionValidation;
   createdAt: number;
@@ -625,11 +641,16 @@ export interface GameTunableParameterDefinition {
   parameterId: string;
   label: string;
   valueType: 'integer' | 'number' | 'boolean' | 'enum';
+  defaultValue: number | boolean | string;
+  currentValue: number | boolean | string;
   min?: number;
   max?: number;
   step?: number;
   enumValues?: string[];
+  unit?: string;
   writePath: string;
+  effectMode: 'next-relaunch';
+  editablePhase: 'paused';
   codeMutationAllowed: false;
 }
 
@@ -641,6 +662,9 @@ export interface GameResourceDescriptor {
   width?: number;
   height?: number;
   durationMs?: number;
+  channelCount?: number;
+  sampleRateHz?: number;
+  codec?: string;
   format: string;
 }
 
diff --git a/server-rs/crates/shared-contracts/src/game_creation_app.rs b/server-rs/crates/shared-contracts/src/game_creation_app.rs
index 77fe2a83c..57db62f95 100644
--- a/server-rs/crates/shared-contracts/src/game_creation_app.rs
+++ b/server-rs/crates/shared-contracts/src/game_creation_app.rs
@@ -373,8 +373,12 @@ pub fn new_game_creation_app_seed_tasks() -> Vec<GameCreationAppTaskState> {
                 "art-polish",
                 "audio-asset-plan",
             ],
-            ["game/"],
-            ["本地 Web 游戏项目可以通过 HTTP server 打开"],
+            [
+                "game/index.html",
+                "game/tunable-parameters.json",
+                "game/tunable-values.json",
+            ],
+            ["本地 Web 游戏项目可以通过 HTTP server 打开，且登记的数值参数可在下一次启动时读取"],
         ),
         task(
             "quality-review",
@@ -649,6 +653,15 @@ pub const RUNNABLE_GAME_VERSION_SCHEMA_VERSION: &str = "game-creator-runnable-ve
 pub enum RunnableGameVersionCreatedReason {
     Initial,
     AgentRevision,
+    ResourceReplacement,
+}
+
+#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct RunnableGameResourceReplacement {
+    pub slot_id: String,
+    pub previous_resource_id: String,
+    pub replacement_resource_id: String,
 }
 
 #[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
@@ -678,6 +691,8 @@ pub struct RunnableGameVersion {
     pub test_slices: Vec<GameTestSlice>,
     #[serde(default, skip_serializing_if = "Vec::is_empty")]
     pub resource_descriptors: Vec<GameResourceDescriptor>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub resource_replacement: Option<RunnableGameResourceReplacement>,
     pub created_reason: RunnableGameVersionCreatedReason,
     pub validation: RunnableGameVersionValidation,
     pub created_at: u64,
@@ -783,6 +798,8 @@ pub struct GameTunableParameterDefinition {
     pub parameter_id: String,
     pub label: String,
     pub value_type: GameTunableParameterValueType,
+    pub default_value: serde_json::Value,
+    pub current_value: serde_json::Value,
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub min: Option<f64>,
     #[serde(default, skip_serializing_if = "Option::is_none")]
@@ -791,7 +808,11 @@ pub struct GameTunableParameterDefinition {
     pub step: Option<f64>,
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub enum_values: Option<Vec<String>>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub unit: Option<String>,
     pub write_path: String,
+    pub effect_mode: String,
+    pub editable_phase: String,
     pub code_mutation_allowed: GameCodeMutationAllowed,
 }
 
@@ -817,6 +838,12 @@ pub struct GameResourceDescriptor {
     pub height: Option<u32>,
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub duration_ms: Option<u64>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub channel_count: Option<u16>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub sample_rate_hz: Option<u32>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub codec: Option<String>,
     pub format: String,
 }
 
@@ -1007,7 +1034,7 @@ pub fn validate_runnable_game_versions(
             "可运行版本最多支持 {GAME_ITERATION_VERSION_MAX_COUNT} 条"
         ));
     }
-    let mut previous_versions = HashMap::<&str, (u64, u64)>::new();
+    let mut previous_versions = HashMap::<&str, (u64, u64, &RunnableGameVersion)>::new();
     for (index, version) in versions.iter().enumerate() {
         if version.schema_version != RUNNABLE_GAME_VERSION_SCHEMA_VERSION {
             return Err(format!(
@@ -1074,17 +1101,22 @@ pub fn validate_runnable_game_versions(
         if index == 0 {
             if version.parent_version_id.is_some()
                 || version.created_reason != RunnableGameVersionCreatedReason::Initial
+                || version.resource_replacement.is_some()
             {
                 return Err("首个可运行版本必须是无父版本的 initial 版本".to_string());
             }
         } else {
-            if version.created_reason != RunnableGameVersionCreatedReason::AgentRevision {
-                return Err("后续可运行版本必须使用 agent-revision 创建原因".to_string());
+            if version.created_reason == RunnableGameVersionCreatedReason::Initial {
+                return Err(
+                    "后续可运行版本必须使用 agent-revision 或 resource-replacement 创建原因"
+                        .to_string(),
+                );
             }
             let Some(parent_id) = version.parent_version_id.as_deref() else {
                 return Err("后续可运行版本必须引用更早的父版本".to_string());
             };
-            let Some((parent_revision, parent_created_at)) = previous_versions.get(parent_id)
+            let Some((parent_revision, parent_created_at, parent_version)) =
+                previous_versions.get(parent_id)
             else {
                 return Err(format!(
                     "可运行版本 {} 的父版本必须先于子版本存在",
@@ -1099,6 +1131,53 @@ pub fn validate_runnable_game_versions(
                     version.version_id
                 ));
             }
+            match (
+                version.created_reason,
+                version.resource_replacement.as_ref(),
+            ) {
+                (RunnableGameVersionCreatedReason::AgentRevision, None) => {}
+                (RunnableGameVersionCreatedReason::ResourceReplacement, Some(replacement)) => {
+                    validate_iteration_version_id(&replacement.slot_id, "资源替换槽位 ID", 256)?;
+                    validate_iteration_version_id(
+                        &replacement.previous_resource_id,
+                        "替换前资源 ID",
+                        512,
+                    )?;
+                    validate_iteration_version_id(
+                        &replacement.replacement_resource_id,
+                        "替换后资源 ID",
+                        512,
+                    )?;
+                    if replacement.previous_resource_id == replacement.replacement_resource_id {
+                        return Err("资源替换前后资源不能相同".to_string());
+                    }
+                    let changed = version
+                        .resource_bindings
+                        .iter()
+                        .filter_map(|binding| {
+                            let parent = parent_version
+                                .resource_bindings
+                                .iter()
+                                .find(|candidate| candidate.slot_id == binding.slot_id)?;
+                            (parent.resource_id != binding.resource_id).then_some((parent, binding))
+                        })
+                        .collect::<Vec<_>>();
+                    if parent_version.resource_bindings.len() != version.resource_bindings.len()
+                        || changed.len() != 1
+                    {
+                        return Err("资源替换版本必须且只能改变一个既有绑定".to_string());
+                    }
+                    let (previous, next) = changed[0];
+                    if previous.slot_id != replacement.slot_id
+                        || next.slot_id != replacement.slot_id
+                        || previous.resource_id != replacement.previous_resource_id
+                        || next.resource_id != replacement.replacement_resource_id
+                    {
+                        return Err("资源替换记录与父子版本绑定差异不一致".to_string());
+                    }
+                }
+                _ => return Err("可运行版本创建原因与资源替换记录不一致".to_string()),
+            }
         }
 
         if version.resource_bindings.len() > GAME_ITERATION_VERSION_MAX_BINDING_COUNT {
@@ -1182,7 +1261,7 @@ pub fn validate_runnable_game_versions(
         }
         previous_versions.insert(
             version.version_id.as_str(),
-            (version.project_revision, version.created_at),
+            (version.project_revision, version.created_at, version),
         );
     }
 
@@ -2317,11 +2396,9 @@ mod tests {
                 resource_id: "asset-player-next".to_string(),
             },
         ];
-        assert!(
-            validate_game_iteration_versions(&[root, invalid_child])
-                .expect_err("reject duplicate slot")
-                .contains("资源槽位重复")
-        );
+        assert!(validate_game_iteration_versions(&[root, invalid_child])
+            .expect_err("reject duplicate slot")
+            .contains("资源槽位重复"));
     }
 
     #[test]
@@ -2433,8 +2510,12 @@ mod tests {
                 width: Some(128),
                 height: Some(128),
                 duration_ms: None,
+                channel_count: None,
+                sample_rate_hz: None,
+                codec: None,
                 format: "image/png".to_string(),
             }],
+            resource_replacement: None,
             created_reason,
             validation: RunnableGameVersionValidation {
                 static_smoke_passed: true,
@@ -2471,39 +2552,33 @@ mod tests {
         )
         .expect("accept valid runnable version graph");
 
-        assert!(
-            validate_runnable_game_versions(
-                "project-runnable",
-                &[root.clone(), child.clone()],
-                Some("missing")
-            )
-            .expect_err("reject missing current version")
-            .contains("当前可运行版本不存在")
-        );
+        assert!(validate_runnable_game_versions(
+            "project-runnable",
+            &[root.clone(), child.clone()],
+            Some("missing")
+        )
+        .expect_err("reject missing current version")
+        .contains("当前可运行版本不存在"));
 
         let mut invalid_child = child.clone();
         invalid_child.validation.playtest_passed = false;
-        assert!(
-            validate_runnable_game_versions(
-                "project-runnable",
-                &[root.clone(), invalid_child],
-                Some("runnable-r2")
-            )
-            .expect_err("reject incomplete validation")
-            .contains("缺少完整验证凭证")
-        );
+        assert!(validate_runnable_game_versions(
+            "project-runnable",
+            &[root.clone(), invalid_child],
+            Some("runnable-r2")
+        )
+        .expect_err("reject incomplete validation")
+        .contains("缺少完整验证凭证"));
 
         let mut invalid_child = child;
         invalid_child.artifact_path = ".agent/runnable-versions/other/artifact".to_string();
-        assert!(
-            validate_runnable_game_versions(
-                "project-runnable",
-                &[root, invalid_child],
-                Some("runnable-r2")
-            )
-            .expect_err("reject mutable artifact identity")
-            .contains("不可变产物身份无效")
-        );
+        assert!(validate_runnable_game_versions(
+            "project-runnable",
+            &[root, invalid_child],
+            Some("runnable-r2")
+        )
+        .expect_err("reject mutable artifact identity")
+        .contains("不可变产物身份无效"));
     }
 
     #[test]
@@ -2615,11 +2690,16 @@ mod tests {
             parameter_id: "enemy-speed".to_string(),
             label: "敌人速度".to_string(),
             value_type: GameTunableParameterValueType::Number,
+            default_value: json!(1.0),
+            current_value: json!(1.0),
             min: Some(0.5),
             max: Some(2.0),
             step: Some(0.1),
             enum_values: None,
-            write_path: "game.balance.enemySpeed".to_string(),
+            unit: Some("倍".to_string()),
+            write_path: "game/tunable-values.json#/values/enemy-speed".to_string(),
+            effect_mode: "next-relaunch".to_string(),
+            editable_phase: "paused".to_string(),
             code_mutation_allowed: GameCodeMutationAllowed,
         };
         let value = serde_json::to_value(definition).expect("serialize tunable parameter");
-- 
2.52.0


From dc7c7dc6ccdaf6ec776d822af8249ebc925f75b1 Mon Sep 17 00:00:00 2001
From: menghao <mh18530625731@163.com>
Date: Wed, 5 Aug 2026 10:00:09 +0800
Subject: [PATCH 23/27] =?UTF-8?q?=E5=AE=8C=E6=88=90P7=E9=AA=8C=E6=94=B6?=
 =?UTF-8?q?=E4=BF=AE=E5=A4=8D=E4=B8=8ECI=E7=A8=B3=E5=AE=9A=E6=80=A7?=
 =?UTF-8?q?=E5=8A=A0=E5=9B=BA?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

修正工作台前端 lint 与正式测试切片初始化依赖
补齐可调参数完成态测试夹具并稳定生成恢复 HTTP 读取
修正 macOS Mach-O release 产物识别与原生壳门禁
同步阶段七验收文档与长期排障记忆
---
 .../src/agent/generation/canvas_generation.rs |  14 +-
 .../agent/runtime_driver/main_loop_tests.rs   |   8 ++
 .../project-workspace/gameRunBridge.ts        |   2 +-
 .../src/view/project-development/index.tsx    |  11 +-
 apps/desktop-shell/scripts/check-config.mjs   |   3 +
 .../scripts/stage-release-binary.mjs          |   8 +-
 ...AI游戏创作】项目开发工作台PRD-2026-07-20.md |   2 +
 docs/project-memory/shared-memory/pitfalls.md |  16 +++
 scripts/check-native-shells.mjs               |   8 +-
 .../shared-contracts/src/game_creation_app.rs | 120 ++++++++++--------
 10 files changed, 128 insertions(+), 64 deletions(-)

diff --git a/apps/ai-game-creator-shell/src-tauri/src/agent/generation/canvas_generation.rs b/apps/ai-game-creator-shell/src-tauri/src/agent/generation/canvas_generation.rs
index ca61da923..0e3cb2a4b 100644
--- a/apps/ai-game-creator-shell/src-tauri/src/agent/generation/canvas_generation.rs
+++ b/apps/ai-game-creator-shell/src-tauri/src/agent/generation/canvas_generation.rs
@@ -1487,10 +1487,22 @@ mod canvas_generation_tests {
         stream
             .set_read_timeout(Some(Duration::from_secs(2)))
             .expect("set request read timeout");
+        let deadline = std::time::Instant::now() + Duration::from_secs(10);
         let mut bytes = Vec::new();
         let mut buffer = [0_u8; 4096];
         loop {
-            let read = stream.read(&mut buffer).expect("read request bytes");
+            let read = match stream.read(&mut buffer) {
+                Ok(read) => read,
+                Err(error)
+                    if matches!(
+                        error.kind(),
+                        std::io::ErrorKind::WouldBlock | std::io::ErrorKind::TimedOut
+                    ) && std::time::Instant::now() < deadline =>
+                {
+                    continue;
+                }
+                Err(error) => panic!("read request bytes: {error}"),
+            };
             if read == 0 {
                 break;
             }
diff --git a/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_driver/main_loop_tests.rs b/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_driver/main_loop_tests.rs
index 6339a811e..1470bd897 100644
--- a/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_driver/main_loop_tests.rs
+++ b/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_driver/main_loop_tests.rs
@@ -152,6 +152,14 @@ fn prepare_autonomous_completion_evidence(root: &Path, state: &AgentRuntimeState
             ("memory/project.md", "# 项目记忆\n\n正式约束。\n"),
             ("game/game_design.md", "# 游戏设计\n\n核心循环。\n"),
             ("game/balance.json", r#"{"lives":3,"speed":1}"#),
+            (
+                "game/tunable-parameters.json",
+                r#"{"schemaVersion":"game-creator-tunable-parameters.v1","parameters":[]}"#,
+            ),
+            (
+                "game/tunable-values.json",
+                r#"{"schemaVersion":"game-creator-tunable-values.v1","values":{}}"#,
+            ),
             (
                 "assets/manifest.art.json",
                 r#"{"assets":[],"status":"not-generated"}"#,
diff --git a/apps/ai-game-creator-shell/src/features/project-workspace/gameRunBridge.ts b/apps/ai-game-creator-shell/src/features/project-workspace/gameRunBridge.ts
index 45a66d5dc..4d0080831 100644
--- a/apps/ai-game-creator-shell/src/features/project-workspace/gameRunBridge.ts
+++ b/apps/ai-game-creator-shell/src/features/project-workspace/gameRunBridge.ts
@@ -1,7 +1,7 @@
 import type {
   GameHostMessage,
-  GameHostSlicePayload,
   GameHostMessageType,
+  GameHostSlicePayload,
   GameRunSession,
   GameRuntimeInspectionMetric,
   GameRuntimeMessage,
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 07107ab68..c45132196 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
@@ -41,12 +41,12 @@ import type {
 } from '../../../../../packages/shared/src/contracts/gameCreationApp';
 import { resolveTauriInvoke } from '../../app/tauri';
 import {
+  type ActiveGameTestSlice,
   beginGameTestSlice,
   formalGameTestSlices,
-  type ActiveGameTestSlice,
-  type TrustedGameResourceInspection,
   projectGameTestSliceMessage,
   projectGameTestSliceSessionStatus,
+  type TrustedGameResourceInspection,
   trustedInspectionFromRuntimeMessage,
 } from '../../features/project-workspace/gameTestSliceModel';
 import {
@@ -580,6 +580,7 @@ export default function ProjectDevelopmentView({
     () => formalGameTestSlices(currentRunnableVersion),
     [currentRunnableVersion],
   );
+  const firstTestSliceId = testSlices[0]?.sliceId ?? '';
   const selectedTestSliceIndex = Math.max(
     0,
     testSlices.findIndex((slice) => slice.sliceId === selectedTestSliceId),
@@ -808,8 +809,6 @@ export default function ProjectDevelopmentView({
       ),
     [resourcePositionsByCategory],
   );
-  const selectedResource =
-    resources.find((resource) => resource.id === selectedResourceId) ?? null;
   const focusedResource =
     resources.find((resource) => resource.id === focusedResourceId) ?? null;
   const focusedReplacementBindings =
@@ -950,10 +949,10 @@ export default function ProjectDevelopmentView({
   }, [currentRunnableVersion, manifest.projectId, mode, projectPath]);
 
   useEffect(() => {
-    setSelectedTestSliceId(testSlices[0]?.sliceId ?? '');
+    setSelectedTestSliceId(firstTestSliceId);
     setActiveTestSlice(null);
     setTrustedInspection(null);
-  }, [currentRunnableVersion?.versionId]);
+  }, [currentRunnableVersion?.versionId, firstTestSliceId]);
 
   useEffect(() => {
     setActiveRunnablePreviewVersionId(null);
diff --git a/apps/desktop-shell/scripts/check-config.mjs b/apps/desktop-shell/scripts/check-config.mjs
index 26ca9cc53..1bf73082c 100644
--- a/apps/desktop-shell/scripts/check-config.mjs
+++ b/apps/desktop-shell/scripts/check-config.mjs
@@ -733,7 +733,10 @@ for (const snippet of [
   'header[3] === 0x46',
   '(stat.mode & 0o111) === 0',
   'header.readUInt32BE(0)',
+  'machMagic === 0xcafebabf',
+  'machMagic === 0xbfbafeca',
   'machMagic === 0xfeedfacf',
+  'machMagic === 0xcffaedfe',
   'header[0] !== 0x4d',
   'header[1] !== 0x5a',
   "console.log('[check:native-shells] desktop-release-binary-artifact')",
diff --git a/apps/desktop-shell/scripts/stage-release-binary.mjs b/apps/desktop-shell/scripts/stage-release-binary.mjs
index 13ce5bac8..8b50598fc 100644
--- a/apps/desktop-shell/scripts/stage-release-binary.mjs
+++ b/apps/desktop-shell/scripts/stage-release-binary.mjs
@@ -49,9 +49,13 @@ function assertExecutable(filePath, label) {
       const machMagic = header.readUInt32BE(0);
       const isMachO =
         machMagic === 0xcafebabe ||
-        machMagic === 0xcafed00d ||
+        machMagic === 0xcafebabf ||
+        machMagic === 0xbebafeca ||
+        machMagic === 0xbfbafeca ||
         machMagic === 0xfeedface ||
-        machMagic === 0xfeedfacf;
+        machMagic === 0xfeedfacf ||
+        machMagic === 0xcefaedfe ||
+        machMagic === 0xcffaedfe;
       if (!isMachO || (stat.mode & 0o111) === 0) {
         throw new Error(`${label} must be an executable Mach-O file`);
       }
diff --git a/docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md b/docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md
index 986c089ef..a22d58117 100644
--- a/docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md
+++ b/docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md
@@ -564,6 +564,8 @@ type ProjectAgentMudPointAttribution = {
 
 ### 7.5 阶段七完整验收
 
+实施状态（2026-08-04）：已完成阶段零至阶段六的需求、合同、实现与测试映射复核，并按 `.gitea/workflows/project-ci.yml` 完成仓库门禁、前端、后端 workspace 与原生壳回归。阶段七收口修正了 Rust 格式、前端 import / 未使用变量 lint、正式测试切片初始化 effect 的依赖声明、旧完成态测试夹具缺少可调参数正式产物、生成恢复 mock HTTP 读取对短暂 `WouldBlock` 不稳定，以及 macOS 原生 little-endian Mach-O / FAT64 release 二进制魔数识别；`1280×800` 应用内浏览器验证保持真实登录门禁，`window`、document 与 body 的宽高、滚动尺寸完全一致且控制台无错误。工作台内部结构继续由 AppSurface 集成测试和资源布局 CSS 合同测试验证，不引入认证绕过或伪造 Tauri 环境。
+
 1. 对照飞书需求、当前 PRD、技术方案、代码、测试与阶段提交复核阶段零至阶段六；美术编辑生成新资源继续按本 PRD 已确认的闭环条件暂缓，不作为遗漏或伪完成。
 2. AppSurface 同时覆盖文档、图片、SVG、音频和视频聚焦；视频必须使用原生 `controls` 且 `preload="metadata"`，读取策略失败时中央主视窗显示安全空态，右侧对话和底部 Agent 状态栏继续存在。
 3. `1280×800` 应用内浏览器实测 `window`、document 与 body 均无页面级横向或纵向溢出。浏览器开发页受真实登录门禁保护，不为验收绕过认证或伪造 Tauri；工作台内部结构由 AppSurface 集成测试与资源布局 CSS 合同测试复核。
diff --git a/docs/project-memory/shared-memory/pitfalls.md b/docs/project-memory/shared-memory/pitfalls.md
index 85a6cb48e..3887bca27 100644
--- a/docs/project-memory/shared-memory/pitfalls.md
+++ b/docs/project-memory/shared-memory/pitfalls.md
@@ -4090,3 +4090,19 @@
 - 原因：测试触发了与断言无关的账户读取，较快环境中请求会在用例结束前失败，较慢 CI 中请求延迟到组件和 jsdom 均已销毁后才收束。仅用 revision 丢弃旧请求而不在卸载时推进 revision，最后一个在途请求仍会被误认作当前请求。
 - 处理：调用方在未认证时不得启动受保护的钱包刷新；可取消的读取要为每轮分配 `AbortController`，新读取先失效并中止旧读取，组件卸载时同时推进 revision、abort 当前请求并清空句柄。所有 `then / catch / finally` 在更新状态前都要检查 signal 与 revision。
 - 验证：定向测试覆盖卸载后请求 signal 已中止；同时复跑触发钱包刷新回调的画布生成集成测试和完整前端测试，不能以单文件偶然快速收束代替全量验证。
+
+## macOS release 二进制不能只按大端展示值识别 Mach-O（2026-08-04）
+
+- 现象：Tauri release build 已成功生成可执行 arm64 二进制，`file` 也识别为 Mach-O，但桌面壳 staging 与 `check:native-shells` 仍报“must be an executable Mach-O file”。
+- 原因：原生 Mach-O 文件头通常以 little-endian 字节序写入；用 `readUInt32BE(0)` 读取 arm64 的 `cf fa ed fe` 会得到 `0xcffaedfe`。只接受 `0xfeedfacf` 等大端展示值会误拒绝真实产物，原校验还把 FAT64 魔数误写成了无关值。
+- 处理：staging 与根原生壳门禁使用同一完整白名单，同时接受 Mach-O 32/64 与 FAT 32/64 的正向和字节交换魔数；继续校验普通文件、最小体积与可执行权限，不因平台差异放宽产物真实性。
+- 验证：macOS 本机执行 `npm run desktop-shell:build -- --no-bundle`、`npm run desktop-shell:stage-release-binary` 和 `npm run check:native-shells`；Linux CI 继续验证 ELF，两个 Tauri `Cargo.lock` 在门禁前后必须不变。
+- 关联：`apps/desktop-shell/scripts/stage-release-binary.mjs`、`apps/desktop-shell/scripts/check-config.mjs`、`scripts/check-native-shells.mjs`。
+
+## mock HTTP 已设置读超时仍要容忍短暂 WouldBlock（2026-08-04）
+
+- 现象：生成恢复定向测试通常通过，但完整原生壳 suite 偶发在读取 loopback 请求时收到 `Resource temporarily unavailable`，导致 mock server 提前退出，主测试随后只看到 channel 断开。
+- 原因：macOS 上带读取超时的 `TcpStream::read` 可以用 `WouldBlock` 表示本轮超时；完整 suite 调度压力可能让请求字节晚于单次两秒窗口到达。对第一次 `WouldBlock` 直接 panic 会把调度抖动误判成协议失败。
+- 处理：测试 HTTP reader 继续保留单次 socket 超时，并在明确的总 deadline 内重试 `WouldBlock / TimedOut`；超过总 deadline 或出现其它 I/O 错误仍失败关闭。不能移除超时或无限重试，否则真正的请求缺失会把 CI 挂死。
+- 验证：定向复跑 `recovery_scan_resumes_accepted_generation_on_default_worker_stack`，并在 `--test-threads=1` 的完整 AI 游戏壳 suite 中确认生成恢复、下载和账本清理全部通过。
+- 关联：`apps/ai-game-creator-shell/src-tauri/src/agent/generation/canvas_generation.rs`。
diff --git a/scripts/check-native-shells.mjs b/scripts/check-native-shells.mjs
index bbfd91361..622269dfb 100644
--- a/scripts/check-native-shells.mjs
+++ b/scripts/check-native-shells.mjs
@@ -4915,9 +4915,13 @@ function assertDesktopReleaseBinaryArtifact() {
     const machMagic = header.readUInt32BE(0);
     const isMachO =
       machMagic === 0xcafebabe ||
-      machMagic === 0xcafed00d ||
+      machMagic === 0xcafebabf ||
+      machMagic === 0xbebafeca ||
+      machMagic === 0xbfbafeca ||
       machMagic === 0xfeedface ||
-      machMagic === 0xfeedfacf;
+      machMagic === 0xfeedfacf ||
+      machMagic === 0xcefaedfe ||
+      machMagic === 0xcffaedfe;
     if (!isMachO || (stat.mode & 0o111) === 0) {
       throw new Error(
         'desktop macOS release binary must be an executable Mach-O file',
diff --git a/server-rs/crates/shared-contracts/src/game_creation_app.rs b/server-rs/crates/shared-contracts/src/game_creation_app.rs
index 57db62f95..6e95fa499 100644
--- a/server-rs/crates/shared-contracts/src/game_creation_app.rs
+++ b/server-rs/crates/shared-contracts/src/game_creation_app.rs
@@ -2396,9 +2396,11 @@ mod tests {
                 resource_id: "asset-player-next".to_string(),
             },
         ];
-        assert!(validate_game_iteration_versions(&[root, invalid_child])
-            .expect_err("reject duplicate slot")
-            .contains("资源槽位重复"));
+        assert!(
+            validate_game_iteration_versions(&[root, invalid_child])
+                .expect_err("reject duplicate slot")
+                .contains("资源槽位重复")
+        );
     }
 
     #[test]
@@ -2552,33 +2554,39 @@ mod tests {
         )
         .expect("accept valid runnable version graph");
 
-        assert!(validate_runnable_game_versions(
-            "project-runnable",
-            &[root.clone(), child.clone()],
-            Some("missing")
-        )
-        .expect_err("reject missing current version")
-        .contains("当前可运行版本不存在"));
+        assert!(
+            validate_runnable_game_versions(
+                "project-runnable",
+                &[root.clone(), child.clone()],
+                Some("missing")
+            )
+            .expect_err("reject missing current version")
+            .contains("当前可运行版本不存在")
+        );
 
         let mut invalid_child = child.clone();
         invalid_child.validation.playtest_passed = false;
-        assert!(validate_runnable_game_versions(
-            "project-runnable",
-            &[root.clone(), invalid_child],
-            Some("runnable-r2")
-        )
-        .expect_err("reject incomplete validation")
-        .contains("缺少完整验证凭证"));
+        assert!(
+            validate_runnable_game_versions(
+                "project-runnable",
+                &[root.clone(), invalid_child],
+                Some("runnable-r2")
+            )
+            .expect_err("reject incomplete validation")
+            .contains("缺少完整验证凭证")
+        );
 
         let mut invalid_child = child;
         invalid_child.artifact_path = ".agent/runnable-versions/other/artifact".to_string();
-        assert!(validate_runnable_game_versions(
-            "project-runnable",
-            &[root, invalid_child],
-            Some("runnable-r2")
-        )
-        .expect_err("reject mutable artifact identity")
-        .contains("不可变产物身份无效"));
+        assert!(
+            validate_runnable_game_versions(
+                "project-runnable",
+                &[root, invalid_child],
+                Some("runnable-r2")
+            )
+            .expect_err("reject mutable artifact identity")
+            .contains("不可变产物身份无效")
+        );
     }
 
     #[test]
@@ -2592,45 +2600,53 @@ mod tests {
 
         let mut wrong_version = version.clone();
         wrong_version.test_slices[0].version_id = "runnable-r2".to_string();
-        assert!(validate_runnable_game_versions(
-            "project-runnable",
-            &[wrong_version],
-            Some("runnable-r1")
-        )
-        .expect_err("reject a slice owned by another version")
-        .contains("测试切片版本身份不一致"));
+        assert!(
+            validate_runnable_game_versions(
+                "project-runnable",
+                &[wrong_version],
+                Some("runnable-r1")
+            )
+            .expect_err("reject a slice owned by another version")
+            .contains("测试切片版本身份不一致")
+        );
 
         let mut duplicate_order = version.clone();
         let mut second_slice = duplicate_order.test_slices[0].clone();
         second_slice.slice_id = "boss".to_string();
         duplicate_order.test_slices.push(second_slice);
-        assert!(validate_runnable_game_versions(
-            "project-runnable",
-            &[duplicate_order],
-            Some("runnable-r1")
-        )
-        .expect_err("reject duplicate slice order")
-        .contains("测试切片 ID 或顺序重复"));
+        assert!(
+            validate_runnable_game_versions(
+                "project-runnable",
+                &[duplicate_order],
+                Some("runnable-r1")
+            )
+            .expect_err("reject duplicate slice order")
+            .contains("测试切片 ID 或顺序重复")
+        );
 
         let mut active_at_registration = version.clone();
         active_at_registration.test_slices[0].status = GameTestSliceStatus::Playing;
-        assert!(validate_runnable_game_versions(
-            "project-runnable",
-            &[active_at_registration],
-            Some("runnable-r1")
-        )
-        .expect_err("reject a non-idle registered slice")
-        .contains("必须以 idle 登记"));
+        assert!(
+            validate_runnable_game_versions(
+                "project-runnable",
+                &[active_at_registration],
+                Some("runnable-r1")
+            )
+            .expect_err("reject a non-idle registered slice")
+            .contains("必须以 idle 登记")
+        );
 
         let mut unbound_descriptor = version;
         unbound_descriptor.resource_descriptors[0].resource_id = "unbound".to_string();
-        assert!(validate_runnable_game_versions(
-            "project-runnable",
-            &[unbound_descriptor],
-            Some("runnable-r1")
-        )
-        .expect_err("reject an unbound trusted descriptor")
-        .contains("资源描述未绑定"));
+        assert!(
+            validate_runnable_game_versions(
+                "project-runnable",
+                &[unbound_descriptor],
+                Some("runnable-r1")
+            )
+            .expect_err("reject an unbound trusted descriptor")
+            .contains("资源描述未绑定")
+        );
     }
 
     #[test]
-- 
2.52.0


From 53e37ea36199201b9064bb0fa74d478c6e19b8a9 Mon Sep 17 00:00:00 2001
From: menghao <mh18530625731@163.com>
Date: Fri, 7 Aug 2026 10:13:25 +0800
Subject: [PATCH 24/27] =?UTF-8?q?=E6=94=AF=E6=8C=81App=20Run=E5=B9=B6?=
 =?UTF-8?q?=E8=A1=8C=E5=BC=80=E5=8F=91=E5=B9=B6=E4=BF=AE=E5=A4=8D=E8=B5=84?=
 =?UTF-8?q?=E6=BA=90=E7=94=BB=E5=B8=83?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

新增App Run独立开发profile并隔离端口、数据库、Tauri身份与AppData
常驻资源排列切换并避免布局状态挤压操作入口
显式扩展资源画布横向滚动范围并收敛依赖图可见连线
补充启动器、资源布局、界面回归测试与项目文档
---
 apps/ai-game-creator-shell/package.json       |   1 +
 .../scripts/check-config.mjs                  |  33 ++
 .../scripts/start-dev-stack.mjs               | 167 +++++++---
 .../scripts/start-tauri-dev.mjs               |  32 +-
 .../src-tauri/tauri.app-run-dev.conf.json     |  21 ++
 apps/ai-game-creator-shell/src/styles.css     |  57 ++--
 .../ResourceDependencyOverlay.tsx             | 305 ------------------
 .../src/view/project-development/index.tsx    |  60 ++--
 .../resourceCanvasLayoutModel.ts              |  12 +
 .../tests/ResourceDependencyOverlay.test.ts   |  57 +---
 .../appSurface/project-development.suite.ts   |  27 +-
 .../tests/resourceCanvasLayoutModel.test.ts   |  27 ++
 .../tests/start-dev-stack.test.ts             |  77 +++++
 .../tests/start-tauri-dev.test.ts             |  53 +++
 ...AI游戏创作】项目开发工作台PRD-2026-07-20.md |  15 +-
 .../shared-memory/decision-log.md             |  16 +
 .../shared-memory/development-workflow.md     |  10 +-
 docs/project-memory/shared-memory/pitfalls.md |   8 +
 ...�案】AI游戏创作智能体App实施计划-2026-06-24.md |   8 +-
 ...发运维】本地开发验证与生产运维-2026-05-15.md |   4 +-
 package.json                                  |   1 +
 21 files changed, 533 insertions(+), 458 deletions(-)
 create mode 100644 apps/ai-game-creator-shell/src-tauri/tauri.app-run-dev.conf.json

diff --git a/apps/ai-game-creator-shell/package.json b/apps/ai-game-creator-shell/package.json
index e2982bbc3..bc54417c2 100644
--- a/apps/ai-game-creator-shell/package.json
+++ b/apps/ai-game-creator-shell/package.json
@@ -5,6 +5,7 @@
   "type": "module",
   "scripts": {
     "dev": "node scripts/start-tauri-dev.mjs",
+    "dev:app-run": "node scripts/start-tauri-dev.mjs --app-run",
     "game-chat": "node scripts/start-tauri-dev.mjs --game-chat",
     "dev-server": "node scripts/start-dev-server.mjs",
     "dev-stack": "node scripts/start-dev-stack.mjs",
diff --git a/apps/ai-game-creator-shell/scripts/check-config.mjs b/apps/ai-game-creator-shell/scripts/check-config.mjs
index 91e8f5e2d..cf0288064 100644
--- a/apps/ai-game-creator-shell/scripts/check-config.mjs
+++ b/apps/ai-game-creator-shell/scripts/check-config.mjs
@@ -27,6 +27,12 @@ const tauriConfig = JSON.parse(
     'utf8',
   ),
 );
+const appRunTauriConfig = JSON.parse(
+  fs.readFileSync(
+    new URL('../src-tauri/tauri.app-run-dev.conf.json', import.meta.url),
+    'utf8',
+  ),
+);
 const gameChatReleaseTauriConfig = JSON.parse(
   fs.readFileSync(
     new URL('../src-tauri/tauri.game-chat-release.conf.json', import.meta.url),
@@ -1263,6 +1269,33 @@ if (packageConfig.scripts?.dev !== 'node scripts/start-tauri-dev.mjs') {
   );
 }
 
+if (
+  packageConfig.scripts?.['dev:app-run'] !==
+    'node scripts/start-tauri-dev.mjs --app-run' ||
+  rootPackageConfig.scripts?.['agc:app-run'] !==
+    'npm --prefix apps/ai-game-creator-shell run dev:app-run'
+) {
+  throw new Error(
+    'AI game creator app-run dev profile must use the managed Tauri dev launcher',
+  );
+}
+
+const appRunWindow = appRunTauriConfig.app?.windows?.[0];
+if (
+  appRunTauriConfig.productName !==
+    'Genarrative AI Game Creator App Run' ||
+  appRunTauriConfig.identifier !==
+    'world.genarrative.ai-game-creator.app-run' ||
+  appRunTauriConfig.identifier === tauriConfig.identifier ||
+  appRunTauriConfig.build?.devUrl !== 'http://127.0.0.1:3081/' ||
+  appRunWindow?.label !== 'client' ||
+  appRunWindow?.title !== 'AI 游戏创作 · App Run'
+) {
+  throw new Error(
+    'AI game creator app-run profile must keep an independent identity, title, and Vite port',
+  );
+}
+
 if (
   packageConfig.scripts?.['game-chat'] !==
   'node scripts/start-tauri-dev.mjs --game-chat'
diff --git a/apps/ai-game-creator-shell/scripts/start-dev-stack.mjs b/apps/ai-game-creator-shell/scripts/start-dev-stack.mjs
index 562e9baaf..df4d99980 100644
--- a/apps/ai-game-creator-shell/scripts/start-dev-stack.mjs
+++ b/apps/ai-game-creator-shell/scripts/start-dev-stack.mjs
@@ -8,17 +8,56 @@ import { fileURLToPath } from 'node:url';
 const appRoot = fileURLToPath(new URL('..', import.meta.url));
 const repoRoot = resolve(appRoot, '../..');
 const devStackStatePath = resolve(repoRoot, '.app/dev-stack.json');
-const viteHost = '127.0.0.1';
-const vitePort = 3080;
+const devProfileName = process.env.GENARRATIVE_AGC_DEV_PROFILE || 'default';
+
+function resolveDevStackProfile(name = 'default') {
+  switch (name) {
+    case 'default':
+      return {
+        name,
+        viteHost: '127.0.0.1',
+        vitePort: 3080,
+        apiPort: 8082,
+        bgfilterWorkerPort: 8083,
+        spacetimePort: 3101,
+        backendDatabase: 'genarrative-game-creator-dev',
+        backendSpacetimeDataDir: resolve(
+          repoRoot,
+          'server-rs/.spacetimedb/ai-game-creator/data',
+        ),
+      };
+    case 'app-run':
+      return {
+        name,
+        viteHost: '127.0.0.1',
+        vitePort: 3081,
+        apiPort: 8084,
+        bgfilterWorkerPort: 8085,
+        spacetimePort: 3103,
+        backendDatabase: 'genarrative-game-creator-app-run-dev',
+        backendSpacetimeDataDir: resolve(
+          repoRoot,
+          'server-rs/.spacetimedb/ai-game-creator-app-run/data',
+        ),
+      };
+    default:
+      throw new Error(`未知 AI 游戏创作开发 profile: ${name}`);
+  }
+}
+
+const devProfile = resolveDevStackProfile(devProfileName);
+const {
+  viteHost,
+  vitePort,
+  apiPort,
+  bgfilterWorkerPort,
+  spacetimePort,
+  backendDatabase,
+  backendSpacetimeDataDir,
+} = devProfile;
 const viteUrl = `http://${viteHost}:${vitePort}/`;
-const viteMarkerUrl = `${viteUrl}__agc_dev_server.json`;
 const defaultApiTarget =
-  process.env.RUST_SERVER_TARGET || 'http://127.0.0.1:8082';
-const backendDatabase = 'genarrative-game-creator-dev';
-const backendSpacetimeDataDir = resolve(
-  repoRoot,
-  'server-rs/.spacetimedb/ai-game-creator/data',
-);
+  process.env.RUST_SERVER_TARGET || `http://127.0.0.1:${apiPort}`;
 const npm = process.platform === 'win32' ? 'npm.cmd' : 'npm';
 const childLifecycles = new WeakMap();
 
@@ -72,6 +111,7 @@ function resolveBackendTargetsFromState(
     expectedDatabase = backendDatabase,
     expectedSpacetimeDataDir = backendSpacetimeDataDir,
     fallbackApiTarget = defaultApiTarget,
+    fallbackSpacetimeTarget = `http://127.0.0.1:${spacetimePort}`,
   } = {},
 ) {
   const apiServer = state?.services?.['api-server'];
@@ -100,7 +140,7 @@ function resolveBackendTargetsFromState(
       ? spacetime.url
       : requireAgcBackend
         ? ''
-        : 'http://127.0.0.1:3101';
+        : fallbackSpacetimeTarget;
   return {
     apiUrl,
     spacetimeUrl,
@@ -131,13 +171,24 @@ async function isBackendReady() {
   );
 }
 
-async function readExistingViteServer() {
-  return httpGetText(viteUrl);
+function resolveViteProfileUrls(profile = devProfile) {
+  const profileViteUrl = `http://${profile.viteHost}:${profile.vitePort}/`;
+  return {
+    viteUrl: profileViteUrl,
+    viteMarkerUrl: `${profileViteUrl}__agc_dev_server.json`,
+  };
 }
 
-function isVitePortListening() {
+async function readExistingViteServer(profile = devProfile) {
+  return httpGetText(resolveViteProfileUrls(profile).viteUrl);
+}
+
+function isVitePortListening(profile = devProfile) {
   return new Promise((resolveRequest) => {
-    const socket = net.connect({ host: viteHost, port: vitePort });
+    const socket = net.connect({
+      host: profile.viteHost,
+      port: profile.vitePort,
+    });
     socket.once('connect', () => {
       socket.destroy();
       resolveRequest(true);
@@ -160,8 +211,11 @@ function isAiGameCreatorServer(response) {
   );
 }
 
-async function readExistingViteMarker() {
-  const response = await httpGetText(viteMarkerUrl, 2000);
+async function readExistingViteMarker(profile = devProfile) {
+  const response = await httpGetText(
+    resolveViteProfileUrls(profile).viteMarkerUrl,
+    2000,
+  );
   if (!response || response.statusCode !== 200) {
     return null;
   }
@@ -173,15 +227,17 @@ async function readExistingViteMarker() {
 }
 
 async function preflightExistingVite({
-  readServer = readExistingViteServer,
-  portListening = isVitePortListening,
-  readMarker = readExistingViteMarker,
+  profile = devProfile,
+  readServer = () => readExistingViteServer(profile),
+  portListening = () => isVitePortListening(profile),
+  readMarker = () => readExistingViteMarker(profile),
 } = {}) {
+  const { viteUrl: profileViteUrl } = resolveViteProfileUrls(profile);
   const existing = await readServer();
   if (!existing) {
     if (await portListening()) {
       throw new Error(
-        `${viteUrl} is already in use by a non-HTTP or unrecognized server. Stop it before starting Tauri dev.`,
+        `${profileViteUrl} is already in use by a non-HTTP or unrecognized server. Stop it before starting Tauri dev.`,
       );
     }
     return { status: 'available', apiTarget: '' };
@@ -189,7 +245,7 @@ async function preflightExistingVite({
 
   if (!isAiGameCreatorServer(existing)) {
     throw new Error(
-      `${viteUrl} is already in use by another server. Stop it before starting Tauri dev.`,
+      `${profileViteUrl} is already in use by another server. Stop it before starting Tauri dev.`,
     );
   }
 
@@ -202,7 +258,7 @@ async function preflightExistingVite({
       : '';
   const actualTarget = markerApiTarget || 'unknown';
   throw new Error(
-    `${viteUrl} is already running with API target ${actualTarget}. Its owning worktree cannot be proven, so it will not be reused. Stop that Vite dev server before starting Tauri dev.`,
+    `${profileViteUrl} is already running with API target ${actualTarget}. Its owning worktree cannot be proven, so it will not be reused. Stop that Vite dev server before starting Tauri dev.`,
   );
 }
 
@@ -507,27 +563,50 @@ async function waitForBackendReady(backendChild, timeoutMs = 600_000) {
   throw new Error('等待配套后端和数据库启动超时');
 }
 
+function buildBackendStartArguments(profile = devProfile) {
+  return [
+    '--prefix',
+    '../..',
+    'run',
+    'agc:backend',
+    '--',
+    '--database',
+    profile.backendDatabase,
+    '--spacetime-data-dir',
+    profile.backendSpacetimeDataDir,
+    '--api-port',
+    String(profile.apiPort),
+    '--bgfilter-worker-port',
+    String(profile.bgfilterWorkerPort),
+    '--spacetime-port',
+    String(profile.spacetimePort),
+    '--no-interactive',
+  ];
+}
+
+function buildViteStartArguments(profile = devProfile) {
+  return [
+    '--prefix',
+    '../..',
+    'exec',
+    'vite',
+    '--',
+    '--config',
+    'vite.config.ts',
+    '--host',
+    profile.viteHost,
+    '--port',
+    String(profile.vitePort),
+    '--strictPort',
+  ];
+}
+
 async function ensureBackend({
   onBackendChild = () => {},
   checkBackendReady = isBackendReady,
   resolveTargets = readBackendTargets,
   spawnBackend = () =>
-    spawnChild(
-      npm,
-      [
-        '--prefix',
-        '../..',
-        'run',
-        'agc:backend',
-        '--',
-        '--database',
-        backendDatabase,
-        '--spacetime-data-dir',
-        backendSpacetimeDataDir,
-        '--no-interactive',
-      ],
-      { cwd: appRoot },
-    ),
+    spawnChild(npm, buildBackendStartArguments(), { cwd: appRoot }),
   waitUntilReady = waitForBackendReady,
 } = {}) {
   if (await checkBackendReady()) {
@@ -569,11 +648,7 @@ async function startVite(apiTarget) {
     );
   }
 
-  return spawnChild(
-    npm,
-    ['--prefix', '../..', 'exec', 'vite', '--', '--config', 'vite.config.ts'],
-    { cwd: appRoot },
-  );
+  return spawnChild(npm, buildViteStartArguments(), { cwd: appRoot });
 }
 
 async function main() {
@@ -593,6 +668,9 @@ async function main() {
   }
 
   try {
+    console.log(
+      `[ai-game-creator-shell] dev profile ${devProfile.name}: vite=${viteUrl} api=${apiPort} spacetime=${spacetimePort}`,
+    );
     await preflightExistingVite();
     const backend = await ensureBackend({
       onBackendChild(child) {
@@ -650,6 +728,8 @@ function isDirectModuleExecution() {
 }
 
 export {
+  buildBackendStartArguments,
+  buildViteStartArguments,
   ensureBackend,
   formatChildFailure,
   isDirectModuleExecution,
@@ -657,6 +737,7 @@ export {
   preflightExistingVite,
   readChildFailure,
   readLinuxProcessGroupAlive,
+  resolveDevStackProfile,
   resolveBackendTargetsFromState,
   runWindowsTaskkill,
   spawnChild,
diff --git a/apps/ai-game-creator-shell/scripts/start-tauri-dev.mjs b/apps/ai-game-creator-shell/scripts/start-tauri-dev.mjs
index 5c6bba17e..6419a9f13 100644
--- a/apps/ai-game-creator-shell/scripts/start-tauri-dev.mjs
+++ b/apps/ai-game-creator-shell/scripts/start-tauri-dev.mjs
@@ -3,6 +3,7 @@ import { fileURLToPath } from 'node:url';
 
 import {
   preflightExistingVite,
+  resolveDevStackProfile,
   spawnChild,
   stopChild,
   terminateChildTree,
@@ -15,24 +16,43 @@ const tauriCliPath = resolve(repoRoot, 'node_modules/@tauri-apps/cli/tauri.js');
 
 function parseLauncherArguments(argv) {
   const args = [...argv];
+  const appRun = args[0] === '--app-run';
+  if (appRun) {
+    args.shift();
+  }
   const gameChat = args[0] === '--game-chat';
   if (gameChat) {
     args.shift();
   }
-  return { gameChat, args };
+  if (appRun && gameChat) {
+    throw new Error('app-run profile 不能与 game-chat 入口同时使用');
+  }
+  return { appRun, gameChat, args };
 }
 
 function buildTauriArguments(argv) {
-  const { gameChat, args } = parseLauncherArguments(argv);
+  const { appRun, gameChat, args } = parseLauncherArguments(argv);
+  if (appRun) {
+    return [
+      'dev',
+      '--config',
+      'src-tauri/tauri.app-run-dev.conf.json',
+      ...args,
+    ];
+  }
   if (gameChat) {
     return ['dev', '--', '--', '--game-chat', ...args];
   }
   return ['dev', ...args];
 }
 
-function spawnTauriCli(argv) {
+function spawnTauriCli(argv, { profileName = 'default' } = {}) {
   return spawnChild(process.execPath, [tauriCliPath, ...argv], {
     cwd: appRoot,
+    env: {
+      ...process.env,
+      GENARRATIVE_AGC_DEV_PROFILE: profileName,
+    },
     shell: false,
   });
 }
@@ -46,10 +66,12 @@ async function runTauriDev(
     terminateTree = terminateChildTree,
   } = {},
 ) {
-  await preflight();
+  const { appRun } = parseLauncherArguments(argv);
+  const profile = resolveDevStackProfile(appRun ? 'app-run' : 'default');
+  await preflight({ profile });
 
   const tauriArguments = buildTauriArguments(argv);
-  const child = spawnCli(tauriArguments);
+  const child = spawnCli(tauriArguments, { profileName: profile.name });
   let resolveShutdown;
   let shutdownSignal = '';
   let repeatedSignal = false;
diff --git a/apps/ai-game-creator-shell/src-tauri/tauri.app-run-dev.conf.json b/apps/ai-game-creator-shell/src-tauri/tauri.app-run-dev.conf.json
new file mode 100644
index 000000000..5471b636c
--- /dev/null
+++ b/apps/ai-game-creator-shell/src-tauri/tauri.app-run-dev.conf.json
@@ -0,0 +1,21 @@
+{
+  "$schema": "https://schema.tauri.app/config/2",
+  "productName": "Genarrative AI Game Creator App Run",
+  "identifier": "world.genarrative.ai-game-creator.app-run",
+  "build": {
+    "devUrl": "http://127.0.0.1:3081/"
+  },
+  "app": {
+    "windows": [
+      {
+        "label": "client",
+        "title": "AI 游戏创作 · App Run",
+        "url": "index.html",
+        "width": 1280,
+        "height": 800,
+        "minWidth": 1280,
+        "minHeight": 800
+      }
+    ]
+  }
+}
diff --git a/apps/ai-game-creator-shell/src/styles.css b/apps/ai-game-creator-shell/src/styles.css
index 19e02ca38..dd1692763 100644
--- a/apps/ai-game-creator-shell/src/styles.css
+++ b/apps/ai-game-creator-shell/src/styles.css
@@ -3740,9 +3740,9 @@ iframe.preview-frame {
 }
 
 .game-workbench-toolbar {
-  display: flex;
+  display: grid;
+  grid-template-columns: max-content minmax(0, 1fr);
   align-items: center;
-  justify-content: space-between;
   gap: 12px;
   min-height: 48px;
   padding: 8px 12px;
@@ -3751,19 +3751,33 @@ iframe.preview-frame {
 }
 
 .game-workbench-tabs,
-.game-workbench-view-actions {
+.game-workbench-view-actions,
+.game-resource-layout-switch {
   display: flex;
   align-items: center;
-  flex-wrap: wrap;
   gap: 7px;
 }
 
 .game-workbench-tabs {
+  flex: 0 0 auto;
+  flex-wrap: wrap;
   padding: 3px;
   border-radius: 999px;
   background: #f3ded3;
 }
 
+.game-workbench-view-actions {
+  min-width: 0;
+  width: 100%;
+  flex-wrap: nowrap;
+  justify-content: flex-end;
+}
+
+.game-resource-layout-switch {
+  flex: 0 0 auto;
+  flex-wrap: nowrap;
+}
+
 .game-workbench-tabs button,
 .game-workbench-view-actions button {
   display: inline-flex;
@@ -3801,11 +3815,19 @@ iframe.preview-frame {
 
 .game-resource-reorder-status {
   min-width: 0;
+  flex: 1 1 auto;
+  max-width: min(240px, 28vw);
+  overflow: hidden;
   color: #9a725f;
   font-size: 10px;
+  text-overflow: ellipsis;
   white-space: nowrap;
 }
 
+.game-resource-reorder-status:empty {
+  display: none;
+}
+
 .game-run-unavailable {
   margin: 0;
   padding: 7px 14px;
@@ -3913,21 +3935,6 @@ iframe.preview-frame {
   opacity: 1;
 }
 
-.game-resource-dependency-edge--task path {
-  stroke: #918b87;
-  stroke-width: 1.4px;
-  stroke-dasharray: 4 7;
-}
-
-.game-resource-dependency-edge--task .game-resource-dependency-trunk {
-  stroke-width: 1.7px;
-  opacity: 0.88;
-}
-
-.game-resource-dependency-edge--task .game-resource-dependency-branch {
-  opacity: 0.72;
-}
-
 .game-resource-dependency-edge.is-cyclic,
 .game-resource-dependency-edge.is-cyclic path {
   stroke-dashoffset: 4;
@@ -3938,11 +3945,6 @@ iframe.preview-frame {
   stroke-linejoin: round;
 }
 
-.game-resource-dependency-marker--task path {
-  fill: #918b87;
-  stroke-linejoin: round;
-}
-
 .game-resource-section {
   position: relative;
   z-index: 1;
@@ -5227,7 +5229,7 @@ iframe.preview-frame {
 
   .game-workbench-toolbar {
     align-items: stretch;
-    flex-direction: column;
+    grid-template-columns: minmax(0, 1fr);
   }
 
   .game-workbench-view-actions {
@@ -5252,10 +5254,9 @@ iframe.preview-frame {
     min-height: 560px;
   }
 
-  .game-workbench-toolbar,
-  .game-workbench-view-actions {
+  .game-workbench-toolbar {
     align-items: stretch;
-    flex-direction: column;
+    grid-template-columns: minmax(0, 1fr);
   }
 
   .game-workbench-tabs {
diff --git a/apps/ai-game-creator-shell/src/view/project-development/ResourceDependencyOverlay.tsx b/apps/ai-game-creator-shell/src/view/project-development/ResourceDependencyOverlay.tsx
index 38a51a13c..2549b9a50 100644
--- a/apps/ai-game-creator-shell/src/view/project-development/ResourceDependencyOverlay.tsx
+++ b/apps/ai-game-creator-shell/src/view/project-development/ResourceDependencyOverlay.tsx
@@ -20,7 +20,6 @@ import {
 import {
   type ProjectResourceGraph,
   type ProjectResourceReferenceEdge,
-  type ProjectResourceTaskFlow,
 } from './resourceDependencyGraphModel';
 
 type Point = {
@@ -50,22 +49,8 @@ export type ResourceDependencyOverlayHandle = {
   clearDragPreview: () => void;
 };
 
-type TaskFlowPathRefs = {
-  sourceBranches: Map<string, SVGPathElement>;
-  targetBranches: Map<string, SVGPathElement>;
-  trunk: SVGPathElement | null;
-};
-
-type TaskFlowSectionGeometry = NonNullable<
-  ReturnType<typeof taskFlowGeometry>
-> & {
-  section: ProjectResourceCanvasSection;
-};
-
 const SECTION_SELECTOR = '[data-resource-section-plane]';
-const TASK_FLOW_HUB_GAP = 20;
 const CONNECTION_MAX_HANDLE = 180;
-const TASK_FLOW_BRANCH_MAX_HANDLE = 96;
 const SELF_REFERENCE_LOOP_WIDTH = 56;
 const SELF_REFERENCE_LOOP_ANCHOR_OFFSET = 18;
 const RESOURCE_SECTIONS: readonly ProjectResourceCanvasSection[] = [
@@ -103,28 +88,6 @@ function connectionPath(source: Point, target: Point) {
   }, ${target.x - direction * bend} ${target.y}, ${target.x} ${target.y}`;
 }
 
-function taskFlowBranchPath(source: Point, target: Point) {
-  const horizontalDistance = Math.abs(target.x - source.x);
-  if (horizontalDistance < 1) {
-    const direction = target.y >= source.y ? 1 : -1;
-    const handle = Math.min(
-      TASK_FLOW_BRANCH_MAX_HANDLE,
-      Math.abs(target.y - source.y) * 0.5,
-    );
-    return `M ${source.x} ${source.y} C ${source.x} ${
-      source.y + direction * handle
-    }, ${target.x} ${target.y - direction * handle}, ${target.x} ${target.y}`;
-  }
-  const direction = target.x >= source.x ? 1 : -1;
-  const handle = Math.min(
-    TASK_FLOW_BRANCH_MAX_HANDLE,
-    horizontalDistance * 0.5,
-  );
-  return `M ${source.x} ${source.y} C ${source.x + direction * handle} ${
-    source.y
-  }, ${target.x - direction * handle} ${target.y}, ${target.x} ${target.y}`;
-}
-
 function rectCenter(rect: Rect): Point {
   return {
     x: rect.x + rect.width / 2,
@@ -132,10 +95,6 @@ function rectCenter(rect: Rect): Point {
   };
 }
 
-function average(values: readonly number[]) {
-  return values.reduce((sum, value) => sum + value, 0) / values.length;
-}
-
 function rectAnchor(rect: Rect, direction: 1 | -1): Point {
   return {
     x: direction === 1 ? rect.x + rect.width : rect.x,
@@ -174,84 +133,6 @@ function referenceGeometry(
   };
 }
 
-function taskFlowGeometry(
-  flow: ProjectResourceTaskFlow,
-  rectByResourceId: RectLookup,
-) {
-  const sourceRects = flow.sourceResourceIds.flatMap((resourceId) => {
-    const rect = rectByResourceId.get(resourceId);
-    return rect ? [{ resourceId, rect }] : [];
-  });
-  const targetRects = flow.targetResourceIds.flatMap((resourceId) => {
-    const rect = rectByResourceId.get(resourceId);
-    return rect ? [{ resourceId, rect }] : [];
-  });
-  if (sourceRects.length === 0 || targetRects.length === 0) {
-    return null;
-  }
-  const sourceCenterX = average(
-    sourceRects.map(({ rect }) => rectCenter(rect).x),
-  );
-  const targetCenterX = average(
-    targetRects.map(({ rect }) => rectCenter(rect).x),
-  );
-  const direction: 1 | -1 = targetCenterX >= sourceCenterX ? 1 : -1;
-  const sourceAnchors = sourceRects.map(({ resourceId, rect }) => ({
-    resourceId,
-    point: rectAnchor(rect, direction),
-  }));
-  const targetAnchors = targetRects.map(({ resourceId, rect }) => ({
-    resourceId,
-    point: rectAnchor(rect, direction === 1 ? -1 : 1),
-  }));
-  const sourceHub: Point = {
-    x:
-      (direction === 1
-        ? Math.max(...sourceAnchors.map(({ point }) => point.x))
-        : Math.min(...sourceAnchors.map(({ point }) => point.x))) +
-      direction * TASK_FLOW_HUB_GAP,
-    y: average(sourceAnchors.map(({ point }) => point.y)),
-  };
-  const targetHub: Point = {
-    x:
-      (direction === 1
-        ? Math.min(...targetAnchors.map(({ point }) => point.x))
-        : Math.max(...targetAnchors.map(({ point }) => point.x))) -
-      direction * TASK_FLOW_HUB_GAP,
-    y: average(targetAnchors.map(({ point }) => point.y)),
-  };
-  return { sourceAnchors, targetAnchors, sourceHub, targetHub };
-}
-
-function taskFlowSectionGeometries(
-  flow: ProjectResourceTaskFlow,
-  rectByResourceId: RectLookup,
-  sectionByResourceId: ReadonlyMap<string, ProjectResourceCanvasSection>,
-): TaskFlowSectionGeometry[] {
-  return RESOURCE_SECTIONS.flatMap((section) => {
-    const geometry = taskFlowGeometry(
-      {
-        ...flow,
-        sourceResourceIds: flow.sourceResourceIds.filter(
-          (resourceId) => sectionByResourceId.get(resourceId) === section,
-        ),
-        targetResourceIds: flow.targetResourceIds.filter(
-          (resourceId) => sectionByResourceId.get(resourceId) === section,
-        ),
-      },
-      rectByResourceId,
-    );
-    return geometry ? [{ ...geometry, section }] : [];
-  });
-}
-
-function taskFlowRenderKey(
-  flowId: string,
-  section: ProjectResourceCanvasSection,
-) {
-  return `${flowId}\n${section}`;
-}
-
 export const ResourceDependencyOverlay = forwardRef<
   ResourceDependencyOverlayHandle,
   ResourceDependencyOverlayProps
@@ -262,7 +143,6 @@ export const ResourceDependencyOverlay = forwardRef<
   const markerPrefix = useId().replace(/[^a-zA-Z0-9_-]/gu, '');
   const overlayRef = useRef<SVGSVGElement>(null);
   const referencePathRefs = useRef(new Map<string, SVGPathElement>());
-  const taskFlowPathRefs = useRef(new Map<string, TaskFlowPathRefs>());
   const activeDragPreviewRef = useRef<(Point & { resourceId: string }) | null>(
     null,
   );
@@ -349,128 +229,12 @@ export const ResourceDependencyOverlay = forwardRef<
     }
     return result;
   }, [graph.resourceIds, positions, sectionOrigins, visibleResourceIds]);
-  const sectionByResourceId = useMemo(
-    () =>
-      new Map(
-        positions.map((position) => [position.resourceId, position.section]),
-      ),
-    [positions],
-  );
   graphRef.current = graph;
   positionByResourceIdRef.current = new Map(
     positions.map((position) => [position.resourceId, position]),
   );
   rectByResourceIdRef.current = rectByResourceId;
 
-  const taskFlowRenderEntries = useMemo(
-    () =>
-      graph.taskFlows.flatMap((flow) =>
-        taskFlowSectionGeometries(
-          flow,
-          rectByResourceId,
-          sectionByResourceId,
-        ).map((geometry) => ({
-          flow,
-          geometry,
-          renderKey: taskFlowRenderKey(flow.id, geometry.section),
-        })),
-      ),
-    [graph.taskFlows, rectByResourceId, sectionByResourceId],
-  );
-
-  const renderTaskFlows = useMemo(
-    () =>
-      taskFlowRenderEntries.map(({ flow, geometry, renderKey }) => {
-        const className = `game-resource-dependency-edge game-resource-dependency-edge--task${
-          flow.cyclic ? ' is-cyclic' : ''
-        }`;
-        return (
-          <g
-            key={renderKey}
-            className={className}
-            data-edge-kind="task-flow"
-            data-edge-id={flow.id}
-            data-resource-section={geometry.section}
-            data-source-task-id={flow.sourceTaskId}
-            data-target-task-id={flow.targetTaskId}
-            data-cyclic={flow.cyclic || undefined}
-          >
-            <title>{`任务流转：${flow.sourceTaskId} → ${flow.targetTaskId}${
-              flow.cyclic ? '（检测到依赖环）' : ''
-            }`}</title>
-            {geometry.sourceAnchors.map(({ resourceId, point }) => (
-              <path
-                ref={(node) => {
-                  let refs = taskFlowPathRefs.current.get(renderKey);
-                  if (!refs) {
-                    refs = {
-                      sourceBranches: new Map(),
-                      targetBranches: new Map(),
-                      trunk: null,
-                    };
-                    taskFlowPathRefs.current.set(renderKey, refs);
-                  }
-                  if (node) {
-                    refs.sourceBranches.set(resourceId, node);
-                  } else {
-                    refs.sourceBranches.delete(resourceId);
-                  }
-                }}
-                key={`source:${resourceId}`}
-                className="game-resource-dependency-branch"
-                data-branch-side="source"
-                data-resource-id={resourceId}
-                d={taskFlowBranchPath(point, geometry.sourceHub)}
-              />
-            ))}
-            <path
-              ref={(node) => {
-                let refs = taskFlowPathRefs.current.get(renderKey);
-                if (!refs) {
-                  refs = {
-                    sourceBranches: new Map(),
-                    targetBranches: new Map(),
-                    trunk: null,
-                  };
-                  taskFlowPathRefs.current.set(renderKey, refs);
-                }
-                refs.trunk = node;
-              }}
-              className="game-resource-dependency-trunk"
-              d={connectionPath(geometry.sourceHub, geometry.targetHub)}
-            />
-            {geometry.targetAnchors.map(({ resourceId, point }) => (
-              <path
-                ref={(node) => {
-                  let refs = taskFlowPathRefs.current.get(renderKey);
-                  if (!refs) {
-                    refs = {
-                      sourceBranches: new Map(),
-                      targetBranches: new Map(),
-                      trunk: null,
-                    };
-                    taskFlowPathRefs.current.set(renderKey, refs);
-                  }
-                  if (node) {
-                    refs.targetBranches.set(resourceId, node);
-                  } else {
-                    refs.targetBranches.delete(resourceId);
-                  }
-                }}
-                key={`target:${resourceId}`}
-                className="game-resource-dependency-branch"
-                data-branch-side="target"
-                data-resource-id={resourceId}
-                d={taskFlowBranchPath(geometry.targetHub, point)}
-                markerEnd={`url(#${markerPrefix}-task-flow-arrow)`}
-              />
-            ))}
-          </g>
-        );
-      }),
-    [markerPrefix, taskFlowRenderEntries],
-  );
-
   const renderReferenceEdges = useMemo(
     () =>
       graph.referenceEdges.map((edge) => {
@@ -508,17 +272,6 @@ export const ResourceDependencyOverlay = forwardRef<
     [graph.referenceEdges, markerPrefix, rectByResourceId],
   );
 
-  useLayoutEffect(() => {
-    const activeRenderKeys = new Set(
-      taskFlowRenderEntries.map((entry) => entry.renderKey),
-    );
-    for (const renderKey of taskFlowPathRefs.current.keys()) {
-      if (!activeRenderKeys.has(renderKey)) {
-        taskFlowPathRefs.current.delete(renderKey);
-      }
-    }
-  }, [taskFlowRenderEntries]);
-
   const updateAffectedGeometry = useCallback(
     (
       affectedResourceIds: ReadonlySet<string>,
@@ -550,7 +303,6 @@ export const ResourceDependencyOverlay = forwardRef<
         index?.referenceEdgeIds.forEach((edgeId) =>
           affectedEdgeIds.add(edgeId),
         );
-        index?.taskFlowIds.forEach((flowId) => affectedEdgeIds.add(flowId));
       }
       for (const edgeId of affectedEdgeIds) {
         const referenceEdge = currentGraph.referenceEdgeById.get(edgeId);
@@ -560,49 +312,6 @@ export const ResourceDependencyOverlay = forwardRef<
           if (geometry && path) {
             path.setAttribute('d', geometry.path);
           }
-          continue;
-        }
-        const flow = currentGraph.taskFlowById.get(edgeId);
-        if (!flow) {
-          continue;
-        }
-        const sectionByResourceId = new Map(
-          Array.from(
-            positionByResourceIdRef.current.values(),
-            (position) => [position.resourceId, position.section] as const,
-          ),
-        );
-        for (const geometry of taskFlowSectionGeometries(
-          flow,
-          rectLookup,
-          sectionByResourceId,
-        )) {
-          const paths = taskFlowPathRefs.current.get(
-            taskFlowRenderKey(flow.id, geometry.section),
-          );
-          if (!paths) {
-            continue;
-          }
-          geometry.sourceAnchors.forEach(({ resourceId, point }) => {
-            paths.sourceBranches
-              .get(resourceId)
-              ?.setAttribute(
-                'd',
-                taskFlowBranchPath(point, geometry.sourceHub),
-              );
-          });
-          paths.trunk?.setAttribute(
-            'd',
-            connectionPath(geometry.sourceHub, geometry.targetHub),
-          );
-          geometry.targetAnchors.forEach(({ resourceId, point }) => {
-            paths.targetBranches
-              .get(resourceId)
-              ?.setAttribute(
-                'd',
-                taskFlowBranchPath(geometry.targetHub, point),
-              );
-          });
         }
       }
     },
@@ -654,22 +363,8 @@ export const ResourceDependencyOverlay = forwardRef<
         >
           <path d="M 1 1 L 8 4.5 L 1 8 z" />
         </marker>
-        <marker
-          id={`${markerPrefix}-task-flow-arrow`}
-          className="game-resource-dependency-marker game-resource-dependency-marker--task"
-          markerWidth="8"
-          markerHeight="8"
-          refX="7.25"
-          refY="4"
-          orient="auto"
-          markerUnits="userSpaceOnUse"
-          viewBox="0 0 8 8"
-        >
-          <path d="M 1 1.25 L 7 4 L 1 6.75 z" />
-        </marker>
       </defs>
 
-      {renderTaskFlows}
       {renderReferenceEdges}
     </svg>
   );
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 c45132196..4a514df98 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
@@ -54,7 +54,10 @@ import {
   type LocalGamePreviewFrameHandle,
   resolveEmbeddedPreviewUrl,
 } from '../../features/project-workspace/LocalGamePreviewFrame';
-import { resourceCanvasSectionExtent } from './resourceCanvasLayoutModel';
+import {
+  resourceCanvasContentWidth,
+  resourceCanvasSectionExtent,
+} from './resourceCanvasLayoutModel';
 import {
   EMPTY_PROJECT_RESOURCE_GRAPH,
   normalizeProjectResourceGraph,
@@ -809,6 +812,14 @@ export default function ProjectDevelopmentView({
       ),
     [resourcePositionsByCategory],
   );
+  const resourceCanvasWidth = useMemo(
+    () =>
+      resourceCanvasContentWidth(
+        resourceLayout.positions,
+        sortMode === 'dependency' ? RESOURCE_DEPENDENCY_VISUAL_GUTTER : 0,
+      ),
+    [resourceLayout.positions, sortMode],
+  );
   const focusedResource =
     resources.find((resource) => resource.id === focusedResourceId) ?? null;
   const focusedReplacementBindings =
@@ -1630,17 +1641,8 @@ export default function ProjectDevelopmentView({
               </button>
             </div>
             <div className="game-workbench-view-actions">
-              {mode === 'resources' && !focusedResource ? (
+              {mode === 'resources' ? (
                 <>
-                  <button
-                    type="button"
-                    className={sortMode === 'dependency' ? 'is-active' : ''}
-                    aria-pressed={sortMode === 'dependency'}
-                    onClick={() => setSortMode('dependency')}
-                  >
-                    <FolderTree size={15} aria-hidden="true" />
-                    按依赖
-                  </button>
                   <span
                     className="game-resource-reorder-status"
                     role="status"
@@ -1648,15 +1650,30 @@ export default function ProjectDevelopmentView({
                   >
                     {resourceLayoutSaving ? '保存中' : resourceLayoutNotice}
                   </span>
-                  <button
-                    type="button"
-                    className={sortMode === 'type' ? 'is-active' : ''}
-                    aria-pressed={sortMode === 'type'}
-                    onClick={() => setSortMode('type')}
+                  <div
+                    className="game-resource-layout-switch"
+                    role="group"
+                    aria-label="资源排列方式"
                   >
-                    <ListFilter size={15} aria-hidden="true" />
-                    按类型
-                  </button>
+                    <button
+                      type="button"
+                      className={sortMode === 'dependency' ? 'is-active' : ''}
+                      aria-pressed={sortMode === 'dependency'}
+                      onClick={() => setSortMode('dependency')}
+                    >
+                      <FolderTree size={15} aria-hidden="true" />
+                      按依赖
+                    </button>
+                    <button
+                      type="button"
+                      className={sortMode === 'type' ? 'is-active' : ''}
+                      aria-pressed={sortMode === 'type'}
+                      onClick={() => setSortMode('type')}
+                    >
+                      <ListFilter size={15} aria-hidden="true" />
+                      按类型
+                    </button>
+                  </div>
                 </>
               ) : mode === 'run' && currentRunnableVersion ? (
                 <label className="game-run-version-picker">
@@ -1980,7 +1997,10 @@ export default function ProjectDevelopmentView({
                 }
                 aria-busy={resourceLayoutSaving}
               >
-                <div className="game-resource-canvas-content">
+                <div
+                  className="game-resource-canvas-content"
+                  style={{ width: `${resourceCanvasWidth}px` }}
+                >
                   {sortMode === 'dependency' ? (
                     <ResourceDependencyOverlay
                       key={`${projectPath}:${manifest.projectId}`}
diff --git a/apps/ai-game-creator-shell/src/view/project-development/resourceCanvasLayoutModel.ts b/apps/ai-game-creator-shell/src/view/project-development/resourceCanvasLayoutModel.ts
index d488c68f9..3730ceb10 100644
--- a/apps/ai-game-creator-shell/src/view/project-development/resourceCanvasLayoutModel.ts
+++ b/apps/ai-game-creator-shell/src/view/project-development/resourceCanvasLayoutModel.ts
@@ -14,6 +14,7 @@ export const RESOURCE_CANVAS_DRAG_THRESHOLD = 5;
 export const RESOURCE_CANVAS_TYPE_COLUMNS = 3;
 export const RESOURCE_CANVAS_SECTION_MIN_WIDTH = 620;
 export const RESOURCE_CANVAS_SECTION_MIN_HEIGHT = 108;
+export const RESOURCE_CANVAS_SECTION_HORIZONTAL_PADDING = 12;
 
 const sectionOrder: ProjectResourceCanvasSection[] = [
   'document',
@@ -323,3 +324,14 @@ export function resourceCanvasSectionExtent(
     ),
   };
 }
+
+export function resourceCanvasContentWidth(
+  positions: ProjectResourceCanvasPosition[],
+  trailingGutter = 0,
+) {
+  return (
+    resourceCanvasSectionExtent(positions).width +
+    Math.max(0, Math.round(trailingGutter)) +
+    RESOURCE_CANVAS_SECTION_HORIZONTAL_PADDING
+  );
+}
diff --git a/apps/ai-game-creator-shell/tests/ResourceDependencyOverlay.test.ts b/apps/ai-game-creator-shell/tests/ResourceDependencyOverlay.test.ts
index 0f4e20e51..de75e5e7d 100644
--- a/apps/ai-game-creator-shell/tests/ResourceDependencyOverlay.test.ts
+++ b/apps/ai-game-creator-shell/tests/ResourceDependencyOverlay.test.ts
@@ -154,7 +154,7 @@ function overlayView(
 }
 
 describe('ResourceDependencyOverlay', () => {
-  it('renders exact references and one aggregated task trunk without cartesian paths', async () => {
+  it('renders exact references without the noisy aggregated task-flow layer', async () => {
     const graph = graphFixture();
     const positions = Array.from(graph.resourceIds).map((resourceId, index) =>
       position(resourceId, (index % 3) * 220, Math.floor(index / 3) * 120),
@@ -167,27 +167,11 @@ describe('ResourceDependencyOverlay', () => {
         overlay.querySelectorAll('[data-edge-kind="asset-reference"]'),
       ).toHaveLength(2),
     );
-    const taskFlow = overlay.querySelector('[data-edge-kind="task-flow"]');
-    expect(taskFlow).not.toBeNull();
-    const taskPaths = Array.from(
-      taskFlow?.querySelectorAll<SVGPathElement>('path') ?? [],
-    );
-    expect(taskPaths).toHaveLength(7);
-    expect(
-      taskPaths.every((path) => path.getAttribute('d')?.includes(' C ')),
-    ).toBe(true);
-    expect(
-      taskPaths.some((path) => path.getAttribute('d')?.includes(' L ')),
-    ).toBe(false);
-    expect(taskFlow?.querySelectorAll('path[marker-end]')).toHaveLength(3);
-    expect(
-      overlay
-        .querySelector('marker[id$="-task-flow-arrow"]')
-        ?.getAttribute('markerUnits'),
-    ).toBe('userSpaceOnUse');
+    expect(overlay.querySelector('[data-edge-kind="task-flow"]')).toBeNull();
+    expect(overlay.querySelector('marker[id$="-task-flow-arrow"]')).toBeNull();
   });
 
-  it('omits cross-section task endpoints and keeps same-section task flow groups', async () => {
+  it('keeps exact references across sections without rendering task flows', async () => {
     const graph = graphFixture();
     const positions = [
       position('source:one', 0, 0, 'document'),
@@ -206,21 +190,12 @@ describe('ResourceDependencyOverlay', () => {
     );
 
     const overlay = await screen.findByTestId('resource-dependency-overlay');
-    const taskFlow = await waitFor(() => {
-      const flows = overlay.querySelectorAll('[data-edge-kind="task-flow"]');
-      expect(flows).toHaveLength(1);
-      return flows.item(0);
-    });
-    expect(taskFlow.getAttribute('data-resource-section')).toBe('art');
-    expect(taskFlow.querySelectorAll('path')).toHaveLength(4);
-    expect(
-      Array.from(taskFlow.querySelectorAll('[data-resource-id]')).map((node) =>
-        node.getAttribute('data-resource-id'),
-      ),
-    ).toEqual(['source:two', 'target:one', 'target:two']);
-    expect(
-      overlay.querySelectorAll('[data-edge-kind="asset-reference"]'),
-    ).toHaveLength(1);
+    await waitFor(() =>
+      expect(
+        overlay.querySelectorAll('[data-edge-kind="asset-reference"]'),
+      ).toHaveLength(1),
+    );
+    expect(overlay.querySelector('[data-edge-kind="task-flow"]')).toBeNull();
   });
 
   it('filters hidden endpoints and updates path geometry when positions change', async () => {
@@ -372,13 +347,13 @@ describe('ResourceDependencyOverlay', () => {
     render(overlayView(graph, positions, new Set(graph.resourceIds)));
     const overlay = await screen.findByTestId('resource-dependency-overlay');
     await waitFor(() =>
-      expect(overlay.querySelectorAll('[data-edge-kind]')).toHaveLength(3),
+      expect(overlay.querySelectorAll('[data-edge-kind]')).toHaveLength(2),
     );
     expect(overlay.querySelector('.is-highlighted')).toBeNull();
     expect(overlay.querySelector('.is-dimmed')).toBeNull();
   });
 
-  it('updates only adjacent paths while dragging inside a 4096-resource topology', async () => {
+  it('does not render task-flow paths for a 4096-resource topology', async () => {
     const resourceIds = Array.from(
       { length: 4096 },
       (_, index) => `resource:${index}`,
@@ -424,11 +399,7 @@ describe('ResourceDependencyOverlay', () => {
     const overlayRef = React.createRef<ResourceDependencyOverlayHandle>();
     render(overlayView(graph, positions, visible, overlayRef));
     const overlay = await screen.findByTestId('resource-dependency-overlay');
-    await waitFor(() =>
-      expect(
-        overlay.querySelectorAll('[data-edge-kind="task-flow"]'),
-      ).toHaveLength(2),
-    );
+    expect(overlay.querySelector('[data-edge-kind]')).toBeNull();
     const setAttribute = vi.spyOn(SVGElement.prototype, 'setAttribute');
     try {
       act(() =>
@@ -441,7 +412,7 @@ describe('ResourceDependencyOverlay', () => {
       const geometryUpdates = setAttribute.mock.calls.filter(
         ([name]) => name === 'd',
       );
-      expect(geometryUpdates).toHaveLength(6);
+      expect(geometryUpdates).toHaveLength(0);
     } finally {
       setAttribute.mockRestore();
     }
diff --git a/apps/ai-game-creator-shell/tests/appSurface/project-development.suite.ts b/apps/ai-game-creator-shell/tests/appSurface/project-development.suite.ts
index 2409f4df3..ce6cb03f6 100644
--- a/apps/ai-game-creator-shell/tests/appSurface/project-development.suite.ts
+++ b/apps/ai-game-creator-shell/tests/appSurface/project-development.suite.ts
@@ -851,6 +851,20 @@ export function registerProjectWorkbenchFoundationTests() {
     expect(
       screen.getByText('美术资源计划已完成，尚未生成或登记图片'),
     ).not.toBeNull();
+    const layoutSwitch = screen.getByRole('group', {
+      name: '资源排列方式',
+    });
+    expect(
+      within(layoutSwitch).getByRole('button', { name: '按依赖' }),
+    ).not.toBeNull();
+    expect(
+      within(layoutSwitch).getByRole('button', { name: '按类型' }),
+    ).not.toBeNull();
+    expect(layoutSwitch.closest('.game-workbench-view-actions')).not.toBeNull();
+    const canvasContent = document.querySelector<HTMLElement>(
+      '.game-resource-canvas-content',
+    );
+    expect(canvasContent?.style.width).toMatch(/^\d+px$/u);
 
     fireEvent.click(screen.getByRole('button', { name: '按类型' }));
     const searchInput = screen.getByLabelText(
@@ -895,6 +909,12 @@ export function registerProjectWorkbenchFoundationTests() {
     expect(styles).toMatch(
       /\.game-resource-card\s*\{[^}]*cursor:\s*pointer[^}]*touch-action:\s*manipulation/s,
     );
+    expect(styles).toMatch(
+      /\.game-workbench-toolbar\s*\{[^}]*display:\s*grid[^}]*grid-template-columns:\s*max-content minmax\(0, 1fr\)/s,
+    );
+    expect(styles).toMatch(
+      /\.game-resource-layout-switch\s*\{[^}]*flex:\s*0 0 auto[^}]*flex-wrap:\s*nowrap/s,
+    );
     expect(styles).not.toMatch(/\.game-resource-card\.is-dragging/);
 
     fireEvent.click(artReceiptCard!);
@@ -903,7 +923,12 @@ export function registerProjectWorkbenchFoundationTests() {
       'resources.focused.document',
     );
     expect(screen.queryByLabelText('搜索项目资源')).toBeNull();
-    expect(screen.queryByRole('button', { name: '按类型' })).toBeNull();
+    expect(
+      screen.getByRole('button', { name: '按类型' }).getAttribute('aria-pressed'),
+    ).toBe('true');
+    expect(
+      screen.getByRole('button', { name: '按依赖' }).getAttribute('aria-pressed'),
+    ).toBe('false');
     expect(screen.getByLabelText('陶泥儿 Agent 对话')).not.toBeNull();
     expect(screen.getByLabelText('子 Agent 状态栏')).not.toBeNull();
     const receiptFocus = screen.getByRole('region', {
diff --git a/apps/ai-game-creator-shell/tests/resourceCanvasLayoutModel.test.ts b/apps/ai-game-creator-shell/tests/resourceCanvasLayoutModel.test.ts
index 768b3f812..3de69b81c 100644
--- a/apps/ai-game-creator-shell/tests/resourceCanvasLayoutModel.test.ts
+++ b/apps/ai-game-creator-shell/tests/resourceCanvasLayoutModel.test.ts
@@ -4,10 +4,12 @@ import {
   createEmptyResourceCanvasLayout,
   moveResourceCanvasPosition,
   reconcileResourceCanvasLayout,
+  resourceCanvasContentWidth,
   RESOURCE_CANVAS_CARD_HEIGHT,
   RESOURCE_CANVAS_CARD_WIDTH,
   RESOURCE_CANVAS_COLUMN_GAP,
   RESOURCE_CANVAS_ROW_GAP,
+  RESOURCE_CANVAS_SECTION_HORIZONTAL_PADDING,
   type ResourceCanvasItem,
 } from '../src/view/project-development/resourceCanvasLayoutModel';
 
@@ -134,6 +136,31 @@ describe('resource canvas layout model', () => {
     ]);
   });
 
+  it('keeps the furthest card and the trailing visual gutter inside the horizontal scroll range', () => {
+    const furthestX = 1764;
+    const trailingGutter = 64;
+    const width = resourceCanvasContentWidth(
+      [
+        {
+          resourceId: 'furthest-resource',
+          section: 'document',
+          x: furthestX,
+          y: 0,
+          manuallyPlaced: false,
+        },
+      ],
+      trailingGutter,
+    );
+
+    expect(width).toBe(
+      furthestX +
+        RESOURCE_CANVAS_CARD_WIDTH +
+        RESOURCE_CANVAS_COLUMN_GAP +
+        trailingGutter +
+        RESOURCE_CANVAS_SECTION_HORIZONTAL_PADDING,
+    );
+  });
+
   it('sorts type defaults by subtype before media type and label with an id fallback', () => {
     const typeLayout = reconcileResourceCanvasLayout(
       createEmptyResourceCanvasLayout('project-type-order', 'type'),
diff --git a/apps/ai-game-creator-shell/tests/start-dev-stack.test.ts b/apps/ai-game-creator-shell/tests/start-dev-stack.test.ts
index 07e5d6a4f..a178a6e08 100644
--- a/apps/ai-game-creator-shell/tests/start-dev-stack.test.ts
+++ b/apps/ai-game-creator-shell/tests/start-dev-stack.test.ts
@@ -6,10 +6,13 @@ import { join, resolve } from 'node:path';
 import { describe, expect, test, vi } from 'vitest';
 
 import {
+  buildBackendStartArguments,
+  buildViteStartArguments,
   ensureBackend,
   isProcessGroupAlive,
   preflightExistingVite,
   readLinuxProcessGroupAlive,
+  resolveDevStackProfile,
   resolveBackendTargetsFromState,
   runWindowsTaskkill,
   spawnChild,
@@ -21,6 +24,63 @@ import {
 const expectedDatabase = 'genarrative-game-creator-dev';
 const expectedDataDir = resolve('server-rs/.spacetimedb/ai-game-creator/data');
 
+describe('AI 游戏创作开发 profile', () => {
+  test('app-run 使用独立端口、数据库和 SpacetimeDB 数据目录', () => {
+    const profile = resolveDevStackProfile('app-run');
+
+    expect(profile).toMatchObject({
+      name: 'app-run',
+      viteHost: '127.0.0.1',
+      vitePort: 3081,
+      apiPort: 8084,
+      bgfilterWorkerPort: 8085,
+      spacetimePort: 3103,
+      backendDatabase: 'genarrative-game-creator-app-run-dev',
+    });
+    expect(profile.backendSpacetimeDataDir).toBe(
+      resolve('server-rs/.spacetimedb/ai-game-creator-app-run/data'),
+    );
+    expect(buildBackendStartArguments(profile)).toEqual([
+      '--prefix',
+      '../..',
+      'run',
+      'agc:backend',
+      '--',
+      '--database',
+      'genarrative-game-creator-app-run-dev',
+      '--spacetime-data-dir',
+      resolve('server-rs/.spacetimedb/ai-game-creator-app-run/data'),
+      '--api-port',
+      '8084',
+      '--bgfilter-worker-port',
+      '8085',
+      '--spacetime-port',
+      '3103',
+      '--no-interactive',
+    ]);
+    expect(buildViteStartArguments(profile)).toEqual([
+      '--prefix',
+      '../..',
+      'exec',
+      'vite',
+      '--',
+      '--config',
+      'vite.config.ts',
+      '--host',
+      '127.0.0.1',
+      '--port',
+      '3081',
+      '--strictPort',
+    ]);
+  });
+
+  test('未知 profile 失败关闭', () => {
+    expect(() => resolveDevStackProfile('another-worktree')).toThrow(
+      '未知 AI 游戏创作开发 profile',
+    );
+  });
+});
+
 function backendState(spacetimeDataDir?: string) {
   return {
     schemaVersion: spacetimeDataDir ? 2 : 1,
@@ -306,4 +366,21 @@ describe('AI 游戏创作 3080 启动前预检', () => {
       }),
     ).resolves.toEqual({ status: 'available', apiTarget: '' });
   });
+
+  test('app-run 只预检自己的 3081，不引用默认 3080', async () => {
+    await expect(
+      preflightExistingVite({
+        profile: resolveDevStackProfile('app-run'),
+        readServer: async () => agcHtml,
+        portListening: async () => true,
+        readMarker: async () => ({
+          schemaVersion: 1,
+          app: 'ai-game-creator-shell',
+          apiTarget: 'http://127.0.0.1:8084',
+        }),
+      }),
+    ).rejects.toThrow(
+      'http://127.0.0.1:3081/ is already running with API target http://127.0.0.1:8084',
+    );
+  });
 });
diff --git a/apps/ai-game-creator-shell/tests/start-tauri-dev.test.ts b/apps/ai-game-creator-shell/tests/start-tauri-dev.test.ts
index 86a4ba18f..765f784b7 100644
--- a/apps/ai-game-creator-shell/tests/start-tauri-dev.test.ts
+++ b/apps/ai-game-creator-shell/tests/start-tauri-dev.test.ts
@@ -12,6 +12,7 @@ import {
 } from '../scripts/start-dev-stack.mjs';
 import {
   buildTauriArguments,
+  parseLauncherArguments,
   runTauriDev,
 } from '../scripts/start-tauri-dev.mjs';
 
@@ -31,6 +32,26 @@ describe('AI 游戏创作 Tauri dev 启动参数', () => {
     expect(buildTauriArguments(['--no-watch'])).toEqual(['dev', '--no-watch']);
   });
 
+  test('app-run 使用独立 Tauri 配置并保留 CLI 参数', () => {
+    expect(buildTauriArguments(['--app-run', '--no-watch'])).toEqual([
+      'dev',
+      '--config',
+      'src-tauri/tauri.app-run-dev.conf.json',
+      '--no-watch',
+    ]);
+    expect(parseLauncherArguments(['--app-run'])).toEqual({
+      appRun: true,
+      gameChat: false,
+      args: [],
+    });
+  });
+
+  test('app-run 与 game-chat 不允许混用', () => {
+    expect(() =>
+      buildTauriArguments(['--app-run', '--game-chat']),
+    ).toThrow('app-run profile 不能与 game-chat 入口同时使用');
+  });
+
   test('game-chat 参数进入应用参数区且保留项目参数', () => {
     expect(
       buildTauriArguments([
@@ -50,6 +71,38 @@ describe('AI 游戏创作 Tauri dev 启动参数', () => {
 });
 
 describe('AI 游戏创作 Tauri dev 生命周期', () => {
+  test('app-run 预检 3081 profile 并把 profile 传给 Tauri 子进程', async () => {
+    const child = Object.assign(new EventEmitter(), {
+      pid: 1234,
+      exitCode: 0,
+      signalCode: null,
+      kill: vi.fn(),
+    });
+    const preflight = vi.fn(async () => {});
+    const spawnCli = vi.fn(() => child);
+
+    await expect(
+      runTauriDev(['--app-run'], {
+        preflight,
+        spawnCli,
+        waitForCli: async () => ({ type: 'exit', code: 0, signal: null }),
+        terminateTree: async () => ({ stopped: true, forced: false }),
+      }),
+    ).resolves.toBe(0);
+
+    expect(preflight).toHaveBeenCalledWith({
+      profile: expect.objectContaining({ name: 'app-run', vitePort: 3081 }),
+    });
+    expect(spawnCli).toHaveBeenCalledWith(
+      [
+        'dev',
+        '--config',
+        'src-tauri/tauri.app-run-dev.conf.json',
+      ],
+      { profileName: 'app-run' },
+    );
+  });
+
   test('3080 预检失败时不启动 Tauri CLI', async () => {
     const spawnCli = vi.fn();
 
diff --git a/docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md b/docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md
index a22d58117..dda6a90fc 100644
--- a/docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md
+++ b/docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md
@@ -262,17 +262,17 @@ type UpdateProjectResourceCanvasLayoutResult =
 
 - 阶段五实现状态（2026-08-03）：dependency 自动排列同时消费任务 DAG 与精确资源引用。Rust 把可信 producer 的任务深度作为资源深度下限，再对 `asset-reference` 图做迭代式 SCC 压缩与确定性层级传播；被引用资源位于引用资源之前，同一引用环共享稳定深度，环后资源继续递增，没有引用关系的资源保持默认不重叠位置。布局深度通过独立 `dependencyDepths` 返回，不能把 producer assignment 冒充全部资源的布局结果。
 - 图层只在 dependency 模式挂载；type 模式不得渲染 SVG、连线或 marker。切换 mode、切换项目或卸载工作台时必须销毁旧图层，并清理尺寸观察和窗口事件监听。
-- 输入固定为当前资源投影的全部卡片身份 / 坐标与 Tauri Rust 返回的 `ProjectResourceGraph` 只读 DTO；Rust 负责资源过滤、去重、迭代式环检测、SCC 压缩后的确定性依赖深度、任务流聚合和一跳连接索引，前端只负责 DTO 防御归一化、浏览器几何与原生 SVG path / marker。SVG 叠加在资源卡底层并设置 `pointer-events: none`，不得引入 D3、React Flow 等图表库，也不得阻断卡片点击。
+- 输入固定为当前资源投影的全部卡片身份 / 坐标与 Tauri Rust 返回的 `ProjectResourceGraph` 只读 DTO；Rust 负责资源过滤、去重、迭代式环检测、SCC 压缩后的确定性依赖深度、任务流聚合和一跳连接索引，前端只负责 DTO 防御归一化与精确资源引用的浏览器几何。SVG 叠加在资源卡底层并设置 `pointer-events: none`，不得引入 D3、React Flow 等图表库，也不得阻断卡片点击。
 - `asset-reference` 表示精确资源引用，使用明亮橙色实线与连续贝塞尔曲线。`GameCreationAppAssetManifestEntry.source.referenceResourceIds` 中的外部资源 ID 必须先唯一匹配另一项资产的 `source.resourceId`，再映射为当前资源卡 ID；缺失、重复或已删除的目标均不得渲染幽灵连线。
-- `task-flow` 表示同一资源类型内的任务产物流转，使用灰色圆头虚线；文档、项目版本、美术、音频之间不得绘制跨分区虚线。任务依赖按 `sourceTaskId -> targetTaskId + section` 分区聚合为一条主线，两端只保留同分区资源并绘制平滑曲线分支，不得出现直角折线；禁止对上下游资源生成笛卡尔积连线。任务主线与分支可以使用不同线宽和透明度表达聚合层级，但不能改变端点或方向语义。
+- `task-flow` 继续作为 Rust 只读拓扑、依赖深度和局部连接索引的数据，不再在资源画布绘制灰色虚线。真实项目的任务产物数量较多，聚合主线与分支仍会形成大面积交叉，不能作为默认用户可读关系；禁止前端重新把 task flow 展开为资源笛卡尔积连线。
 - 画布资产 producer 只能来自 `agent.runtime.canvas.asset_generate` 的 `assetId -> agentId` 审计且 `agentId` 必须存在于当前 manifest；External Editor `source.taskId` 属于平台生成任务命名空间，禁止当作 manifest task ID。证据缺失、冲突或有界审计读取未覆盖时不生成对应 task flow，不猜测归属。
 - 图模型必须对资源引用图和完整任务依赖图做迭代式环检测，不得用无界递归遍历；参与环的可见边保留渲染并标记 cyclic，环本身不能造成重复生成或死循环。
 - 资源自引用的起点与终点为同一张卡片时，必须绘制在卡片外侧的可见闭环并保留箭头，不得让路径穿过卡片后被底层 SVG 层级遮挡。
-- 搜索只允许为当前可见端点生成几何；任一精确引用端点隐藏时该线隐藏，聚合任务流只保留仍可见的两端分支，任一侧没有可见资源时整条任务流隐藏。
+- 搜索只允许为当前可见端点生成几何；任一精确引用端点隐藏时该线隐藏。
 - 资源点击只进入中央聚焦并保留当前选中卡片，不改变依赖卡片或连线的颜色、线宽与透明度；关系线始终直接展示，不提供点击后的上下游高亮或无关线弱化。
 - 资源卡 Pointer Move 不改变基础 positions 或 SVG 几何。连线只随布局读取、资源自动协调、搜索、项目切换或 section origin 变化而更新。
-- `ResizeObserver` 在单个图层生命周期只允许构造一次。dependency section 额外提供至少 `64px` 右侧视觉 gutter，确保最右侧自环和箭头可完整滚动显示，但不得修改卡片坐标或布局 sidecar。
-- 阶段五不改变手动位置边界：已有 `manuallyPlaced=true` 坐标原样保留，资源引用新增或变化只允许重新派生 `manuallyPlaced=false` 的自动坐标；任务流继续按任务对与资源分区聚合，禁止为了计算深度或绘线生成资源笛卡尔积。
+- `ResizeObserver` 在单个图层生命周期只允许构造一次。资源画布内容宽度必须显式覆盖最右卡片外边界、卡片间距和 section 横向内边距，不能依赖绝对定位卡片隐式撑开滚动范围；dependency section 在此基础上额外提供至少 `64px` 右侧视觉 gutter，确保最右卡片、自环和箭头都可完整滚动显示，但不得修改卡片坐标或布局 sidecar。
+- 阶段五不改变手动位置边界：已有 `manuallyPlaced=true` 坐标原样保留，资源引用新增或变化只允许重新派生 `manuallyPlaced=false` 的自动坐标；任务流继续按任务对聚合供深度计算使用，不进入 SVG 绘制。
 
 ### 5.3 资源类型与替换兼容性（P1）
 
@@ -544,12 +544,13 @@ type ProjectAgentMudPointAttribution = {
 
 ### 7.3 P1 资源依赖关系图验收
 
-1. dependency 模式显示明亮橙色实线资源引用，并只在同一资源类型分区内显示灰色虚线任务流；跨类型不显示虚线，type 模式没有图层或连线。
+1. dependency 模式只显示明亮橙色实线资源引用，不显示灰色任务流虚线；type 模式没有图层或连线。资源列表态和资源聚焦态右上角都必须保留“按依赖 / 按类型”切换。
 2. 精确引用只接受唯一有效的外部资源 ID 映射，删除或不存在的资源不产生幽灵连线。
-3. 多资源任务依赖按资源类型分区后，各分区只形成一条聚合主线与 `O(S+T)` 条端点分支，不产生 `S×T` 连线或跨分区虚线。
+3. 多资源任务依赖继续在 Rust read model 中按任务对聚合，不产生 `S×T` 数据或可见虚线。
 4. 资源引用环和无资源产物参与的任务环都可被有限遍历识别，界面不死循环。
 5. 搜索触发端点过滤；资源点击不改变上下游卡片或任何连线的视觉状态，资源卡指针移动不更新线段，点击与中央聚焦行为不回归。
 6. 切换布局模式或项目后旧 SVG、ResizeObserver 与窗口监听全部清理；图层从不写入 layout sidecar、manifest 或其它持久化。
+7. 横向滚动终点必须完整露出最右资源卡及右侧安全留白；布局状态文字可以截断或隐藏，但不得压缩、遮挡“按依赖 / 按类型”切换。
 7. 4096 资源链式 fixture 继续验证拓扑、聚合复杂度和自动布局性能；拖动局部更新与真实 Chromium 拖动帧预算暂缓，不作为当前验收条件。最右侧自环与箭头仍需完整显示。
 8. Rust 图读取延迟时，dependency sidecar 在图进入 `ready / failed` 前没有读取或写入；首次布局直接使用 Rust 返回的最终 producer 与 dependency depth。重新打开旧布局时手动位置逐项不变，自动位置按最终拓扑协调且相同结果不增加 revision。
 
diff --git a/docs/project-memory/shared-memory/decision-log.md b/docs/project-memory/shared-memory/decision-log.md
index 36a405670..326088fb9 100644
--- a/docs/project-memory/shared-memory/decision-log.md
+++ b/docs/project-memory/shared-memory/decision-log.md
@@ -1,5 +1,21 @@
 # 决策记录
 
+## 2026-08-06 app-run 以独立开发 profile 支持多工作树并行运行
+
+- 背景：多个 Git worktree 能隔离代码和分支，但不会隔离宿主机端口、Tauri identifier、AppData、数据库或本地 data dir。默认 AGC 固定使用 `3080 / 8082 / 8083 / 3101`，另一工作树运行时当前窗口可能被同名实例混淆，默认启动器则会为避免串台直接失败关闭。
+- 决策：保留 `npm run agc` 默认行为，新增 `npm run agc:app-run`；两者复用同一 `start-tauri-dev.mjs` 与 `start-dev-stack.mjs`。`app-run` profile 使用 `3081 / 8084 / 8085 / 3103`、专用数据库与 SpacetimeDB data dir，并通过独立 Tauri 配置隔离 identifier、AppData 和窗口标题。profile 随 Tauri 子进程环境传给 `beforeDevCommand`，禁止只切 Vite 而继续连接默认后端。
+- 边界：不修改、停止或复用其它工作树进程，不改默认 AGC、game-chat release、生产配置或业务契约；未知 profile 和 profile 自身端口冲突均失败关闭。
+- 验证方式：启动器单测锁定 profile 端口、数据库、data dir、3081 预检、Tauri config 与环境传递；配置门禁锁定专用脚本、identifier、标题和 devUrl；并行 smoke 同时核对默认端口仍由另一工作树持有，app-run 端口进程 cwd 指向当前工作树。
+
+
+## 2026-08-06 资源依赖画布移除任务流虚线并常驻布局切换
+
+- 背景：真实项目会把大量任务产物投影到文档区，灰色 task-flow 聚合主线与分支仍形成大面积交叉，遮挡卡片并增加阅读负担；同时布局状态提示的最小内容宽度可能挤压右侧“按依赖 / 按类型”入口，资源聚焦态还会主动隐藏整组入口。
+- 决策：Rust `ProjectResourceGraph` 继续保留 task flow、producer、环和 dependency depth，供可信自动排列与诊断使用；前端 `ResourceDependencyOverlay` 只绘制明确的橙色 `asset-reference`，不再绘制灰色 task-flow 虚线或 marker。资源列表态与中央聚焦态均常驻“按依赖 / 按类型”切换；切换按钮放入不可收缩的独立控件组，工具栏状态文案只能截断或隐藏，不能把操作入口挤出。画布内容宽度显式按最右卡片外边界、section 内边距与 dependency 视觉 gutter 计算，不能依赖绝对定位卡片隐式撑开横向滚动范围。
+- 边界：不修改 manifest、资源图 Tauri DTO、依赖深度、layout sidecar、SpacetimeDB 或资源卡拖动边界；type 模式继续不挂载 SVG，dependency 模式仍使用完整 Rust 拓扑排列资源。
+- 验证方式：SVG 单测断言含 task flow 的 read model 只产生精确引用 path；AppSurface 覆盖独立布局切换控件组、type 模式卸载图层和聚焦态切换按钮常驻；布局模型以最右 `x` 断言滚动内容宽度包含卡片、列间距、`64px` gutter 与 section 内边距；追加 shell typecheck、编码检查与 `git diff --check`。
+- 关联文档：`docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md`、`docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md`。
+
 ## 2026-08-04 工作台 P2/P6 以不可变子版本和编辑态参数文件实现显式写入
 
 - 背景：P1 已建立唯一可运行版本和不可变快照，P3-P5 已建立一次性会话、正式切片和可信悬停信息；飞书后续要求资源替换与数值微调，但禁止原地改版本、运行中热写 iframe、信任展示文案或让自然语言生成任意代码 / 路径。
diff --git a/docs/project-memory/shared-memory/development-workflow.md b/docs/project-memory/shared-memory/development-workflow.md
index 7905231fd..aa7f805e0 100644
--- a/docs/project-memory/shared-memory/development-workflow.md
+++ b/docs/project-memory/shared-memory/development-workflow.md
@@ -59,6 +59,14 @@ AI 游戏创作独立客户端常用短命令：
 npm run agc
 ```
 
+同一台开发机上已有另一工作树运行默认 AGC 时，当前 `app-run` 工作树使用独立 profile：
+
+```bash
+npm run agc:app-run
+```
+
+该 profile 固定使用 Vite `3081`、API `8084`、BgFilter worker `8085`、SpacetimeDB `3103`，并隔离数据库、SpacetimeDB data dir、Tauri identifier、AppData 和窗口标题。它不会探测、复用或停止默认 profile 的 `3080 / 8082 / 8083 / 3101` 进程；`npm run agc` 的默认行为保持不变。
+
 需要构建只能打开“游戏运行 + 聊天”页面的独立 release 包时使用：
 
 ```bash
@@ -314,7 +322,7 @@ npm run ai-game-creator-shell:agent-runtime:real-e2e -- --config-dir <AppData> -
 
 定向命令必须实际匹配到 V1.10 用例，`0 tests` 不算通过。真实 Provider fixture 不得把工具顺序、processId、readiness 文本所在 chunk 或 OS PID 写进任务提示；验收器只按持久 action identity、fixture 计数、私有输出和公共泄漏扫描判定。三项门禁实际通过后才能把日期、Provider、数量和 PASS 结果写入技术方案或 decision log；未运行或被外部配置阻断时只记录 `BLOCKED` / 未验收事实。
 
-`npm run agc` 会启动 Tauri 开发客户端；其 `beforeDevCommand` 通过 `npm run agc:serve` 先完成壳 typecheck，再启动或复用配套 SpacetimeDB、`api-server` 和固定 `127.0.0.1:3080` Vite。开发态只打开游戏创作聊天入口使用 `npm run agc:game-chat -- [--project-path <absolute-path>]`。只需要浏览器预览同一客户端时可用 `npm run agc:serve`；只启动配套后端和数据库时可用 `npm run agc:backend -- --database <name>`。
+`npm run agc` 会启动默认 Tauri 开发客户端；其 `beforeDevCommand` 通过 `npm run agc:serve` 先完成壳 typecheck，再启动或复用配套 SpacetimeDB、`api-server` 和固定 `127.0.0.1:3080` Vite。并行工作树使用 `npm run agc:app-run`，启动器把 `app-run` profile 通过子进程环境传给同一 `beforeDevCommand`，改用独立 `3081 / 8084 / 8085 / 3103` 端口、数据库、data dir 和 Tauri identity；禁止手工只改 Vite 端口而继续连接默认后端或 AppData。开发态只打开游戏创作聊天入口使用 `npm run agc:game-chat -- [--project-path <absolute-path>]`。只需要浏览器预览同一客户端时可用 `npm run agc:serve`；只启动配套后端和数据库时可用 `npm run agc:backend -- --database <name>`。
 
 Linux 多用户共享同一台机器开发时，本地 dev 脚本会为当前 Linux 用户分配一个固定端口段并写入系统级注册表 `/var/tmp/genarrative-dev-port-ranges/registry.json`，自动分配从 `10000-10099` 开始，每段 100 个端口，五个 dev 服务依次使用 `start` 到 `start + 4`，其中 BgFilter worker 固定为 `start + 4`。可用 `GENARRATIVE_DEV_PORT_RANGE` 或 `npm run dev -- --port-range` 手动指定端口段用于特殊场景；注册表会阻止不同用户使用相同或重叠段，并让同一用户后续启动继续复用自己已占用的固定段。该机制只在 Linux 生效，Windows 把第五个服务纳入原有统一端口探测与漂移逻辑。
 
diff --git a/docs/project-memory/shared-memory/pitfalls.md b/docs/project-memory/shared-memory/pitfalls.md
index 3887bca27..33eea3487 100644
--- a/docs/project-memory/shared-memory/pitfalls.md
+++ b/docs/project-memory/shared-memory/pitfalls.md
@@ -14,6 +14,14 @@
 - 关联：相关文件、文档、提交或 Issue
 ```
 
+## 多工作树只隔离代码，不会自动隔离 AGC 运行资源
+
+- 现象：两个工作树同时运行 `npm run agc` 时，后启动者因 `3080` 已占用而失败，或用户在两个同名窗口间误把另一工作树的页面当作当前修改结果。
+- 原因：worktree 只隔离 Git 工作目录；端口、Tauri identifier、AppData、SpacetimeDB 数据库和 data dir 都属于宿主机共享资源。只修改 Vite 端口仍会让代理、Runner 或数据库串到默认实例。
+- 处理：默认工作树继续使用 `npm run agc`；当前 app-run 使用 `npm run agc:app-run`，由统一 profile 同时隔离 `3081 / 8084 / 8085 / 3103`、数据库、data dir、Tauri identifier、AppData 和窗口标题。不要手工终止无法证明归属的进程，也不要只覆盖单个端口。
+- 验证：分别用 `lsof -a -p <pid> -d cwd -Fn` 核对两组监听进程 cwd；app-run 窗口标题必须为“AI 游戏创作 · App Run”，Vite marker API target 必须指向 app-run 的实际 API。
+- 关联：`apps/ai-game-creator-shell/scripts/start-tauri-dev.mjs`、`apps/ai-game-creator-shell/scripts/start-dev-stack.mjs`、`apps/ai-game-creator-shell/src-tauri/tauri.app-run-dev.conf.json`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。
+
 ## Linux 生产脚本门禁不能假设本地也是 GNU userland
 
 - 现象：macOS 本地运行维护页、生产 API 部署和 Rust 产物门禁时，依次出现 `mv: illegal option -- T`、`mapfile: command not found`、`/usr/bin/cp` / `/usr/bin/chmod` 不存在，以及 `.rlib` 明明含有 `.o` 却报告“没有可扫描成员”；安全修复计划还会把 `/var/folders` 到 `/private/var/folders` 的系统别名误判为用户符号链接。
diff --git a/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md b/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md
index fd7361a74..7101b3448 100644
--- a/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md
+++ b/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md
@@ -362,7 +362,7 @@ game-project/
 
 - 页面骨架固定为左侧现有全局导航、中间主视窗、右侧陶泥儿对话和底部子 Agent 状态栏；不新建第二套客户端或平行项目页。
 - 中间主视窗提供 `资源管理 / 运行` 切换。2026-08-04 起运行入口不再读取 `code-prototype` 任务状态，只读取 manifest 的正式 `runnableVersions + currentRunnableVersionId`；无版本时保持视觉不可用但仍可点击查看“当前无可运行版本”，不能使用会阻断说明交互的原生 `disabled` 或 `aria-disabled`。切回资源管理只修改前端展示态，不伪造后端预览暂停结果。
-- 资源管理从当前 `GameCreationAppManifest`（包含可选 `versions`）、合法 Agent 文本回执和已导入附件派生资源，固定按文档、项目版本、美术资源、音乐音效资源分区；未知任务产物不再兜底为版本，任务声明中的未登记音频也不冒充正式音频。`按依赖 / 按类型` 使用各自前端排列，dependency 模式额外绘制当前 manifest 与资源投影可证明的依赖关系。排列与图层都不写回 manifest，不能推断或伪造缺失依赖。
+- 资源管理从当前 `GameCreationAppManifest`（包含可选 `versions`）、合法 Agent 文本回执和已导入附件派生资源，固定按文档、项目版本、美术资源、音乐音效资源分区；未知任务产物不再兜底为版本，任务声明中的未登记音频也不冒充正式音频。`按依赖 / 按类型` 使用各自前端排列并在资源列表态、聚焦态常驻右上角；dependency 模式只额外绘制当前 manifest 与资源投影可证明的精确资源引用。排列与图层都不写回 manifest，不能推断或伪造缺失依赖。
 - 资源卡支持点击聚焦、搜索和类型筛选。2026-07-28 起完成两套二维坐标与本地 CAS sidecar；2026-07-31 起 dependency 模式增加不持久化的原生 SVG 关系图层。2026-08-03 mentor 决定暂缓资源卡拖动，当前卡片不挂载 Pointer Down / Move / Up / Cancel 拖动入口，只允许自动布局和点击聚焦。聚焦态替换中央主视窗内容，保留左侧导航、右侧对话和底部 Agent 状态栏，退出后恢复搜索、布局模式、滚动位置与选中资源；不提供工具栏、工具侧边栏或可拖动标题栏。阶段四已补齐安全本地文档、扩展美术媒体与音频聚焦，正文独立滚动，视频 / 音频使用内置媒体控件，失败显示空态；美术编辑、音频编辑 / 替换、版本替换或运行模块仍不在本阶段。
 - 运行表现层嵌入当前项目的 loopback 游戏画面。P1 由专用可运行版本命令停止旧 preview、卸载 iframe、复核版本快照并启动目标版本；普通 `preview.start` 继续服务 Agent 当前工作树验证，不能作为工作台运行授权或旧版本切换入口。2026-08-04 起 P3 在该生命周期上接入运行会话与 Host/Game Bridge；P3 阶段自身未接入资源替换、下一版本、测试切片编排或参数调整，P2 / P6 的当前实现以本节后续对应专节为准。
 - 右侧继续复用现有 Project Supervisor 会话、Runtime 澄清和确认链路；输入区展示 `严格审批 / 风险审批 / 无需审批` 独立面板。P0 只有严格审批可选；风险审批和无需审批保持视觉不可用但允许点击查看原因，不替代 Runtime 的逐动作权限、确认、sandbox 或 reconciliation 门禁。风险 Rank 算法记录在 `docs/project-memory/todos/【待解决】AI游戏创作高风险审批Rank-2026-07-20.md`，前端不得自行计算。
@@ -402,10 +402,10 @@ game-project/
 - `read_local_project_resource_graph` 读取当前 manifest、前端资源卡身份列表和最多 `32 MiB` 的安全 Agent DB 尾部，通过 Rust 构建稳定 read model；读取使用既有 Agent DB 普通文件 / 链接 / 追加锁边界，不新增数据库或 sidecar。返回资源 ID、引用边、聚合任务流、producer assignment、独立 `dependencyDepths`、循环集合、unresolved 外部 ID、局部连接索引和 `producerMappingTruncated`。
 - 精确引用把 manifest 资产 `source.referenceResourceIds` 唯一匹配到另一资产的 `source.resourceId`，再转换为本次资源卡 ID；无匹配、多匹配、重复卡片或已删除资源只记录为 unresolved / 忽略，不生成边。引用边按 `sourceResourceId + targetResourceId` 稳定去重；前端 `resourceDependencyGraphModel.ts` 再做一次 DTO 端点防御过滤，避免异步切项目时出现幽灵线。
 - task flow 只读取存在于当前 manifest 的任务依赖。画布资产 producer 仅接受 `agent.runtime.canvas.asset_generate` 中经 manifest 校验的 `assetId -> agentId`；External Editor 返回并保存在 `source.taskId` 的 `task-1` 等身份属于平台生成任务，禁止复用为 manifest task。多个有效 Agent 对同一资产形成冲突或证据缺失时，不生成该资产对应 task flow。任务产物 / Agent 回执继续使用资源投影中已有的 manifest task 身份。
-- 资源按可信 producer 分组，每个 `sourceTaskId -> targetTaskId` 只生成一个聚合 flow；SVG 侧绘制 source 分支、唯一主线和 target 分支，路径数量为 `O(S+T)`，禁止资源笛卡尔积。局部连接索引保存 resource 关联的 reference edge ID / task flow ID，不预先展开 `S×T` 邻接矩阵。
+- 资源按可信 producer 分组，每个 `sourceTaskId -> targetTaskId` 只生成一个聚合 flow，供依赖深度、环检测和局部连接索引使用；前端 SVG 不再绘制 task flow。局部连接索引仍保存 resource 关联的 reference edge ID / task flow ID，不预先展开 `S×T` 邻接矩阵。
 - 资源引用图和完整任务依赖图在 Rust 分别使用迭代式强连通分量分析。任务环检测不能依赖可视 task flow 是否有两端资源，否则无产物任务参与的环会漏报；循环边只带 cyclic 标记，不触发递归展开。
-- `ResourceDependencyOverlay.tsx` 使用原生 SVG path/marker，绝对定位在 `.game-resource-canvas-content` 底层并统一 `pointer-events: none`。橙色实线表示 `asset-reference`，灰色圆头虚线表示 `task-flow`；两类连线统一使用连续贝塞尔曲线，任务主线略强于两端分支，箭头使用不随高亮线宽缩放的稳定用户空间尺寸，避免直角折线、突兀拐弯和箭头跳变。不引入 D3、React Flow 或其它图表依赖。
-- `asset-reference` 的 source / target 是同一资源时使用卡片右侧外绕贝塞尔闭环，两个锚点分开且 marker 保留在返回锚点；路径不穿过卡片。dependency section 在现有 extent 外额外增加 `64px` 右侧视觉 gutter，确保最右卡片的闭环和箭头可滚动显示；不改卡片坐标、`resourceCanvasLayoutModel.ts` 或 sidecar。
+- `ResourceDependencyOverlay.tsx` 使用原生 SVG path/marker，绝对定位在 `.game-resource-canvas-content` 底层并统一 `pointer-events: none`。图层只绘制橙色实线 `asset-reference`，不绘制灰色 task flow 虚线；资源引用使用连续贝塞尔曲线和不随线宽缩放的稳定用户空间箭头。不引入 D3、React Flow 或其它图表依赖。
+- `asset-reference` 的 source / target 是同一资源时使用卡片右侧外绕贝塞尔闭环，两个锚点分开且 marker 保留在返回锚点；路径不穿过卡片。`.game-resource-canvas-content` 使用 `resourceCanvasContentWidth(...)` 显式覆盖最右坐标、卡片宽度、列间距与 section 横向内边距，避免绝对定位卡片溢出却没有进入 `scrollWidth`；dependency 模式再追加 `64px` 右侧视觉 gutter，确保最右卡片、闭环和箭头均可滚动显示。该宽度只影响显示层，不改卡片坐标或 layout sidecar。
 - 图层用 SVG 自身节点定位所属画布容器，测量各 section plane 相对原点；`ResizeObserver` 在图层挂载时只创建一次，与 window resize 一起负责重新测量并在卸载时清理。type 模式不挂载图层且释放 graph state；项目身份作为 key，切换 mode、项目或工作台卸载都会销毁旧 SVG。
 - 基础 positions 保持稳定；卡片 Pointer Move 不进入 SVG preview，只有搜索、选择、项目切换、真实 positions 或 section origin 变化才重新协调图层。SVG 几何从不持久化。
 - Rust、前端 DTO/SVG 和工作台 AppSurface 回归覆盖生产 `task-1` 数据形状、真实 producer、证据缺失、精确引用、去重、无效 ID、完整任务环、4096 链式拓扑、聚合复杂度、搜索过滤、选择高亮、稳定 Observer、type 模式卸载与项目切换销毁。局部拖动更新与真实 Chromium 拖动性能目标暂缓。
diff --git a/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md b/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md
index 48914ebf8..8a72f5ced 100644
--- a/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md
+++ b/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md
@@ -58,7 +58,9 @@ Linux 本机多用户并发开发时，`npm run dev` 和 `npm run dev:*` 单模
 
 后端日志默认写入 `logs/api-server/`，独立 BgFilter worker 日志默认写入 `logs/bgfilter-worker/`。后端 API smoke 使用 `npm run dev:api-server`，先检查 BgFilter worker `/readyz`，再检查 API `/healthz`；需要确认 API 实例可接生产流量时检查 API `/readyz`。不要使用旧 `api-server:maincloud` 或任何 `GENARRATIVE_SPACETIME_MAINCLOUD_*` 口径。
 
-AI 游戏创作客户端使用 `npm run agc`，开发态 game-chat 使用 `npm run agc:game-chat`。两个入口都先由 `apps/ai-game-creator-shell/scripts/start-tauri-dev.mjs` 在 Tauri CLI 启动前检查固定地址 `http://127.0.0.1:3080/`：只有端口空闲时才继续启动。现有 marker 只包含 API target，不能证明监听器属于当前 worktree；即使页面和 target 看似匹配，也不得复用已经存在的 3080。旧 worktree Vite、无响应监听器或非 AGC 服务一律在创建原生窗口前失败关闭，并提示先停止旧服务；启动器不擅自终止无法证明归属的进程。
+AI 游戏创作客户端默认使用 `npm run agc`，开发态 game-chat 使用 `npm run agc:game-chat`。两个入口都先由 `apps/ai-game-creator-shell/scripts/start-tauri-dev.mjs` 在 Tauri CLI 启动前检查固定地址 `http://127.0.0.1:3080/`：只有端口空闲时才继续启动。现有 marker 只包含 API target，不能证明监听器属于当前 worktree；即使页面和 target 看似匹配，也不得复用已经存在的 3080。旧 worktree Vite、无响应监听器或非 AGC 服务一律在创建原生窗口前失败关闭，并提示先停止旧服务；启动器不擅自终止无法证明归属的进程。
+
+同一台机器需要并行运行另一工作树时，`app-run` 工作树使用 `npm run agc:app-run`。该命令仍复用同一 Tauri / dev-stack 启动器，但使用独立 profile：Vite `3081`、API `8084`、BgFilter worker `8085`、SpacetimeDB `3103`、数据库 `genarrative-game-creator-app-run-dev`、独立 SpacetimeDB data dir，以及独立的 Tauri identifier、AppData 和“AI 游戏创作 · App Run”窗口标题。profile 只检查和清理自己创建的进程树，不复用、不终止默认 profile 或其它工作树进程。若 profile 自己的端口被占用则失败关闭，不能漂回默认端口。
 
 Tauri `beforeDevCommand` 默认与客户端构建并行，不能把上述检查只放在 `beforeDevCommand` 内：旧 3080 已就绪时，Tauri 可能先创建加载旧前端的窗口，随后配套后端才因代理不匹配退出。外层启动器会把 Tauri CLI 放入受控进程树；CLI 正常退出、启动失败或收到终止信号后，POSIX 先向保留的 PGID 发送 `SIGTERM`、有界等待后升级 `SIGKILL`，Windows 使用 `taskkill /PID <pid> /T /F`。Linux 容器中的孤儿后代退出后可能暂时保留为 zombie，`kill(-PGID, 0)` 仍会返回成功；启动器必须结合 `/proc/<pid>/stat` 判断同组是否还存在非 zombie 成员，不能把等待 PID 1 回收误报为清理失败。配套后端和 Vite 仍由 `start-dev-stack.mjs` 各自持有，退出时同样有界收束，避免只剩客户端、Runner、Cargo 或旧订阅进程。排障时同时核对 3080 marker、`.app/dev-stack.json` 的实际 API URL 和进程 cwd；不要把“终端已返回”当成客户端及其 Runner 已退出的证据。
 
diff --git a/package.json b/package.json
index b26e54986..a518f456c 100644
--- a/package.json
+++ b/package.json
@@ -129,6 +129,7 @@
     "desktop-shell:typecheck": "npm --prefix apps/desktop-shell run typecheck",
     "desktop-shell:test": "cargo test --manifest-path apps/desktop-shell/src-tauri/Cargo.toml",
     "agc": "npm --prefix apps/ai-game-creator-shell run dev",
+    "agc:app-run": "npm --prefix apps/ai-game-creator-shell run dev:app-run",
     "agc:dev": "npm --prefix apps/ai-game-creator-shell run dev",
     "agc:game-chat": "npm --prefix apps/ai-game-creator-shell run game-chat --",
     "agc:serve": "npm run agc:typecheck && npm --prefix apps/ai-game-creator-shell run dev-stack",
-- 
2.52.0


From 8a4b71bf8e5cf4e707f9698d0689dbd0f7f29a13 Mon Sep 17 00:00:00 2001
From: menghao <mh18530625731@163.com>
Date: Fri, 7 Aug 2026 10:53:41 +0800
Subject: [PATCH 25/27] =?UTF-8?q?=E4=BF=AE=E5=A4=8D=E8=B5=84=E6=BA=90?=
 =?UTF-8?q?=E7=94=BB=E5=B8=83=E6=BA=A2=E5=87=BA=E4=B8=8E=E6=A8=A1=E6=9D=BF?=
 =?UTF-8?q?=E8=B5=84=E6=BA=90=E6=8A=95=E5=BD=B1?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

闭合资源画布横向收缩链并增加内部滚动条

过滤任务产物通配模板避免生成无效资源卡

补充布局与资源投影回归测试

同步工作台文档与共享排障记忆
---
 apps/ai-game-creator-shell/src/styles.css     | 34 +++++++++++++++++-
 .../resourceProjectionModel.ts                |  8 +++++
 .../projectResourceProjectionModel.test.ts    |  8 +++++
 .../resourceCanvasLayoutContract.test.ts      | 35 +++++++++++++++++++
 ...AI游戏创作】项目开发工作台PRD-2026-07-20.md |  5 ++-
 .../shared-memory/decision-log.md             |  8 +++++
 docs/project-memory/shared-memory/pitfalls.md | 16 +++++++++
 ...�案】AI游戏创作智能体App实施计划-2026-06-24.md |  3 +-
 8 files changed, 114 insertions(+), 3 deletions(-)

diff --git a/apps/ai-game-creator-shell/src/styles.css b/apps/ai-game-creator-shell/src/styles.css
index dd1692763..493f71c6e 100644
--- a/apps/ai-game-creator-shell/src/styles.css
+++ b/apps/ai-game-creator-shell/src/styles.css
@@ -3736,6 +3736,7 @@ iframe.preview-frame {
 .game-workbench-stage {
   position: relative;
   display: grid;
+  grid-template-columns: minmax(0, 1fr);
   grid-template-rows: auto auto minmax(0, 1fr);
 }
 
@@ -3840,7 +3841,9 @@ iframe.preview-frame {
 .game-resource-manager {
   display: flex;
   flex-direction: column;
+  min-width: 0;
   min-height: 0;
+  overflow: hidden;
 }
 
 .game-resource-search {
@@ -3894,14 +3897,43 @@ iframe.preview-frame {
 .game-resource-canvas {
   position: relative;
   flex: 1;
+  width: 100%;
+  min-width: 0;
   min-height: 0;
   padding: 12px;
-  overflow: auto;
+  overflow-x: auto;
+  overflow-y: auto;
+  scrollbar-color: #d5a089 #f7e7df;
+  scrollbar-width: thin;
   background-color: #fffdfa;
   background-image: radial-gradient(#eaded8 0.8px, transparent 0.8px);
   background-size: 18px 18px;
 }
 
+.game-resource-canvas::-webkit-scrollbar {
+  width: 10px;
+  height: 12px;
+}
+
+.game-resource-canvas::-webkit-scrollbar-track {
+  border-radius: 999px;
+  background: #f7e7df;
+}
+
+.game-resource-canvas::-webkit-scrollbar-thumb {
+  border: 2px solid #f7e7df;
+  border-radius: 999px;
+  background: #d5a089;
+}
+
+.game-resource-canvas::-webkit-scrollbar-thumb:hover {
+  background: #c98566;
+}
+
+.game-resource-canvas::-webkit-scrollbar-corner {
+  background: #f7e7df;
+}
+
 .game-resource-canvas-content {
   position: relative;
   display: grid;
diff --git a/apps/ai-game-creator-shell/src/view/project-development/resourceProjectionModel.ts b/apps/ai-game-creator-shell/src/view/project-development/resourceProjectionModel.ts
index c021ccfe6..82dcb4269 100644
--- a/apps/ai-game-creator-shell/src/view/project-development/resourceProjectionModel.ts
+++ b/apps/ai-game-creator-shell/src/view/project-development/resourceProjectionModel.ts
@@ -58,6 +58,11 @@ function fileName(path: string) {
   return path.split(/[\\/]/u).filter(Boolean).pop() || path;
 }
 
+function isConcreteTaskArtifactPath(path: string) {
+  const normalizedPath = path.trim();
+  return normalizedPath.length > 0 && !/[*?\[\]{}]/u.test(normalizedPath);
+}
+
 export function classifyProjectedResource(input: {
   path: string;
   mediaType: string;
@@ -119,6 +124,9 @@ export function projectResourcesFromReadModels(
       continue;
     }
     for (const path of task.artifacts) {
+      if (!isConcreteTaskArtifactPath(path)) {
+        continue;
+      }
       const category = classifyProjectedResource({ path, mediaType: '' });
       if (!category || category === 'audio') {
         continue;
diff --git a/apps/ai-game-creator-shell/tests/projectResourceProjectionModel.test.ts b/apps/ai-game-creator-shell/tests/projectResourceProjectionModel.test.ts
index 06acb6276..33d3a543c 100644
--- a/apps/ai-game-creator-shell/tests/projectResourceProjectionModel.test.ts
+++ b/apps/ai-game-creator-shell/tests/projectResourceProjectionModel.test.ts
@@ -56,6 +56,10 @@ describe('项目资源投影', () => {
       'memory/game-design.md',
       'assets/ui-preview.svg',
       'build/game.bundle',
+      '.agent/passes/pass-*/groups/design/director.md',
+      'memory/draft?.md',
+      'assets/[ab].png',
+      'memory/{draft,final}.md',
     ];
     audioTask.status = 'completed';
     audioTask.artifacts = ['audio/unregistered-bgm.wav'];
@@ -151,6 +155,10 @@ describe('项目资源投影', () => {
         [
           'task:design-foundation:build/game.bundle',
           'task:audio-asset-plan:audio/unregistered-bgm.wav',
+          'task:design-foundation:.agent/passes/pass-*/groups/design/director.md',
+          'task:design-foundation:memory/draft?.md',
+          'task:design-foundation:assets/[ab].png',
+          'task:design-foundation:memory/{draft,final}.md',
           'asset:unknown-binary',
           'attachment:imports/archive.zip',
         ].includes(id),
diff --git a/apps/ai-game-creator-shell/tests/resourceCanvasLayoutContract.test.ts b/apps/ai-game-creator-shell/tests/resourceCanvasLayoutContract.test.ts
index d90d6772c..376e5001a 100644
--- a/apps/ai-game-creator-shell/tests/resourceCanvasLayoutContract.test.ts
+++ b/apps/ai-game-creator-shell/tests/resourceCanvasLayoutContract.test.ts
@@ -1,3 +1,6 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+
 import { describe, expect, it } from 'vitest';
 
 import {
@@ -6,6 +9,38 @@ import {
 } from '../../../packages/shared/src/contracts/gameCreationApp';
 
 describe('resource canvas layout contract', () => {
+  it('keeps wide resource content inside an explicitly scrollable stage column', () => {
+    const styles = readFileSync(
+      resolve(process.cwd(), 'apps/ai-game-creator-shell/src/styles.css'),
+      'utf8',
+    );
+    const stageRule = styles.match(
+      /\.game-workbench-stage\s*\{([^}]*)\}/s,
+    );
+    const managerRule = styles.match(
+      /\.game-resource-manager\s*\{([^}]*)\}/s,
+    );
+    const canvasRule = styles.match(
+      /\.game-resource-canvas\s*\{([^}]*)\}/s,
+    );
+
+    expect(stageRule?.[1]).toContain(
+      'grid-template-columns: minmax(0, 1fr);',
+    );
+    expect(managerRule?.[1]).toContain('min-width: 0;');
+    expect(managerRule?.[1]).toContain('overflow: hidden;');
+    expect(canvasRule?.[1]).toContain('width: 100%;');
+    expect(canvasRule?.[1]).toContain('min-width: 0;');
+    expect(canvasRule?.[1]).toContain('overflow-x: auto;');
+    expect(canvasRule?.[1]).toContain('overflow-y: auto;');
+    expect(styles).toMatch(
+      /\.game-resource-canvas::-webkit-scrollbar\s*\{[^}]*height:\s*12px/s,
+    );
+    expect(styles).toMatch(
+      /\.game-resource-canvas::-webkit-scrollbar-thumb\s*\{[^}]*background:\s*#d5a089/s,
+    );
+  });
+
   it('keeps revisions inside the JSON safe integer range', () => {
     const maxRevision = GAME_CREATION_RESOURCE_LAYOUT_MAX_SAFE_REVISION;
     expect(JSON.parse(JSON.stringify({ revision: maxRevision }))).toEqual({
diff --git a/docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md b/docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md
index dda6a90fc..d16aa0e27 100644
--- a/docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md
+++ b/docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md
@@ -48,6 +48,8 @@
 - 新资源首次进入某个布局时才执行默认不重叠排版；已有坐标不得被自动排序覆盖。
 - 依赖布局使用资源生成/引用关系；类型布局按资源大类、子类型、尺寸规格排序。
 - 资源分区由资源投影固定，前端交互不能改变分类。
+- 已完成任务的 `artifacts` 只有在声明具体文件路径时才投影为资源；包含 `*`、`?`、`[]` 或 `{}` 的 glob / 模板路径只描述未来可能产物，不生成可点击资源卡。
+- 资源列表态右上角必须常驻“按依赖 / 按类型”切换。画布内容宽于主视窗时只在资源画布内部提供清晰的横向滚动条，不能撑宽主视窗、遮挡切换按钮或裁掉最右资源卡。
 - 资源卡手动拖动、拖动持久化、拖动性能与冲突后的重新拖动提示全部暂缓，不作为当前产品合同或验收条件。
 
 ### 3.4 数值微调
@@ -540,7 +542,8 @@ type ProjectAgentMudPointAttribution = {
 4. 两个窗口基于同一 revision 执行资源自动协调写入时最多一个成功；失败方收到 `conflict` 与最新完整布局，界面不静默覆盖成功方结果。
 5. 布局文件缺失的旧项目可以无迁移打开；损坏、未知 schema、身份冲突、超限和链接文件失败关闭，且原文件不被空布局覆盖。
 6. 布局读写不改变 manifest、游戏项目 mutation revision、Runtime verification、Agent 权限与预览状态。
-7. `1280×800` 最小横屏下全部资源可通过分区滚动访问，不出现页面级横向或纵向溢出，右侧对话和底部 Agent 状态栏保持可见。
+7. `1280×800` 最小横屏下全部资源可通过资源画布内部滚动访问；横向滚动条清晰可操作，最右资源卡与安全留白可完整露出，不出现页面级横向或纵向溢出，右上角布局切换、右侧对话和底部 Agent 状态栏保持可见。
+8. 已完成任务中的具体文档 / 美术文件继续进入资源投影；包含 glob 元字符的产物模板不生成资源卡，也不会触发本地文件读取失败空态。
 
 ### 7.3 P1 资源依赖关系图验收
 
diff --git a/docs/project-memory/shared-memory/decision-log.md b/docs/project-memory/shared-memory/decision-log.md
index 326088fb9..5262e7915 100644
--- a/docs/project-memory/shared-memory/decision-log.md
+++ b/docs/project-memory/shared-memory/decision-log.md
@@ -1,5 +1,13 @@
 # 决策记录
 
+## 2026-08-07 资源画布闭合横向收缩链并拒绝产物模板投影
+
+- 背景：资源画布显式内容宽度超过中央主视窗时，绝对定位卡片的 min-content 宽度把 `.game-workbench-stage` 隐式 grid 列撑宽，外层 `overflow: hidden` 再把右上角布局切换和最右资源卡裁掉；点击卡片进入已有 `min-width: 0` 的聚焦态后按钮重新出现，容易被误判为条件渲染。与此同时，completed task 的 `.agent/passes/pass-*/.../director.md` 只是模板，却被投影成可点击文档并在读取时失败。
+- 布局决策：工作台主视窗显式使用 `grid-template-columns: minmax(0, 1fr)`，资源管理与资源画布逐层允许横向收缩并在管理容器处裁住外溢；资源画布自身固定 `width: 100%`、承担 `overflow-x / overflow-y: auto`，并为 Tauri WebKit 提供可见滚动轨道和滑块。布局切换继续常驻，不依赖资源选中态。
+- 投影决策：只有不含 `*`、`?`、`[]`、`{}` 的具体 task artifact 文件路径可以生成任务产物资源卡。过滤只作用于 task artifact 模板，不扩大到 manifest assets、已导入附件或 Agent 文本回执。
+- 验证方式：资源投影单测同时覆盖具体产物与四类 glob 元字符；CSS 合同锁定 stage grid 列、祖先 `min-width`、内部 overflow 和 WebKit scrollbar；既有布局模型继续验证最右卡片、列间距、安全 gutter 与 section 内边距全部进入 scroll width。
+- 关联：`apps/ai-game-creator-shell/src/styles.css`、`apps/ai-game-creator-shell/src/view/project-development/resourceProjectionModel.ts`、工作台 PRD 与 AI 游戏创作实施计划。
+
 ## 2026-08-06 app-run 以独立开发 profile 支持多工作树并行运行
 
 - 背景：多个 Git worktree 能隔离代码和分支，但不会隔离宿主机端口、Tauri identifier、AppData、数据库或本地 data dir。默认 AGC 固定使用 `3080 / 8082 / 8083 / 3101`，另一工作树运行时当前窗口可能被同名实例混淆，默认启动器则会为避免串台直接失败关闭。
diff --git a/docs/project-memory/shared-memory/pitfalls.md b/docs/project-memory/shared-memory/pitfalls.md
index 33eea3487..56fb973c2 100644
--- a/docs/project-memory/shared-memory/pitfalls.md
+++ b/docs/project-memory/shared-memory/pitfalls.md
@@ -14,6 +14,22 @@
 - 关联：相关文件、文档、提交或 Issue
 ```
 
+## 绝对定位宽画布必须闭合所有祖先的 min-content 收缩链
+
+- 现象：资源列表态右上角布局切换消失、最右资源卡被裁掉且画布没有有效横向滚动；点击任一资源进入聚焦态后按钮又出现，看起来像选中态条件渲染错误。
+- 原因：绝对定位卡片所在内容层有显式超宽尺寸，grid 子项及其 flex 后代缺少 `min-width: 0` 时，min-content 宽度会撑大主视窗隐式列；最外层 `overflow: hidden` 只负责裁切，子画布的 `overflow: auto` 因自身也被撑宽而无法形成正确滚动范围。
+- 处理：从 grid 轨道开始使用 `minmax(0, 1fr)`，中间资源管理容器和实际滚动容器逐层设置 `min-width: 0`；管理容器截住外溢，资源画布固定 `width: 100%` 并独立承担横纵滚动。Tauri WebKit 需要显式 scrollbar track / thumb 样式，不能只验证 DOM 中按钮存在。
+- 验证：CSS 合同同时锁定 grid 列、祖先收缩、内部 overflow 与 WebKit scrollbar；布局模型按最右卡片外边界断言 scroll width。真实窗口还应确认布局按钮始终可见，拖到横向终点能完整看到最右卡片和安全留白。
+- 关联：`apps/ai-game-creator-shell/src/styles.css`、`apps/ai-game-creator-shell/tests/resourceCanvasLayoutContract.test.ts`、`apps/ai-game-creator-shell/tests/resourceCanvasLayoutModel.test.ts`。
+
+## manifest 产物 glob 只是模板，不能直接投影为资源文件
+
+- 现象：资源区出现 `director.md` 等卡片，点击后提示文件读取失败；磁盘上不存在该文件，但 manifest task 看起来已经 completed。
+- 原因：task `artifacts` 中可能保存 `.agent/passes/pass-*/...` 之类未来轮次的路径模板。completed 只说明任务状态，不会把 glob 展开成某个具体文件；把字符串按扩展名直接分类会制造幽灵资源卡。
+- 处理：task artifact 投影前拒绝包含 `*`、`?`、`[]`、`{}` 的路径，只让具体文件路径进入分类和受控读取。不要把此规则泛化到 manifest 已登记资产、已导入附件或 Agent 文本回执。
+- 验证：同一 fixture 同时放入具体 Markdown / 图片路径和各类 glob 模板，断言前者保留、后者完全不进入资源 ID 集合。
+- 关联：`apps/ai-game-creator-shell/src/view/project-development/resourceProjectionModel.ts`、`apps/ai-game-creator-shell/tests/projectResourceProjectionModel.test.ts`。
+
 ## 多工作树只隔离代码，不会自动隔离 AGC 运行资源
 
 - 现象：两个工作树同时运行 `npm run agc` 时，后启动者因 `3080` 已占用而失败，或用户在两个同名窗口间误把另一工作树的页面当作当前修改结果。
diff --git a/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md b/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md
index 7101b3448..24924fcce 100644
--- a/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md
+++ b/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md
@@ -362,7 +362,7 @@ game-project/
 
 - 页面骨架固定为左侧现有全局导航、中间主视窗、右侧陶泥儿对话和底部子 Agent 状态栏；不新建第二套客户端或平行项目页。
 - 中间主视窗提供 `资源管理 / 运行` 切换。2026-08-04 起运行入口不再读取 `code-prototype` 任务状态，只读取 manifest 的正式 `runnableVersions + currentRunnableVersionId`；无版本时保持视觉不可用但仍可点击查看“当前无可运行版本”，不能使用会阻断说明交互的原生 `disabled` 或 `aria-disabled`。切回资源管理只修改前端展示态，不伪造后端预览暂停结果。
-- 资源管理从当前 `GameCreationAppManifest`（包含可选 `versions`）、合法 Agent 文本回执和已导入附件派生资源，固定按文档、项目版本、美术资源、音乐音效资源分区；未知任务产物不再兜底为版本，任务声明中的未登记音频也不冒充正式音频。`按依赖 / 按类型` 使用各自前端排列并在资源列表态、聚焦态常驻右上角；dependency 模式只额外绘制当前 manifest 与资源投影可证明的精确资源引用。排列与图层都不写回 manifest，不能推断或伪造缺失依赖。
+- 资源管理从当前 `GameCreationAppManifest`（包含可选 `versions`）、合法 Agent 文本回执和已导入附件派生资源，固定按文档、项目版本、美术资源、音乐音效资源分区；未知任务产物不再兜底为版本，任务声明中的未登记音频也不冒充正式音频。已完成任务的 `artifacts` 只投影不含 `*`、`?`、`[]`、`{}` glob 元字符的具体文件路径，模板路径不生成资源卡；manifest 已登记资产、已导入附件和 Agent 文本回执保持原投影边界。`按依赖 / 按类型` 使用各自前端排列并在资源列表态、聚焦态常驻右上角；dependency 模式只额外绘制当前 manifest 与资源投影可证明的精确资源引用。排列与图层都不写回 manifest，不能推断或伪造缺失依赖。
 - 资源卡支持点击聚焦、搜索和类型筛选。2026-07-28 起完成两套二维坐标与本地 CAS sidecar；2026-07-31 起 dependency 模式增加不持久化的原生 SVG 关系图层。2026-08-03 mentor 决定暂缓资源卡拖动，当前卡片不挂载 Pointer Down / Move / Up / Cancel 拖动入口，只允许自动布局和点击聚焦。聚焦态替换中央主视窗内容，保留左侧导航、右侧对话和底部 Agent 状态栏，退出后恢复搜索、布局模式、滚动位置与选中资源；不提供工具栏、工具侧边栏或可拖动标题栏。阶段四已补齐安全本地文档、扩展美术媒体与音频聚焦，正文独立滚动，视频 / 音频使用内置媒体控件，失败显示空态；美术编辑、音频编辑 / 替换、版本替换或运行模块仍不在本阶段。
 - 运行表现层嵌入当前项目的 loopback 游戏画面。P1 由专用可运行版本命令停止旧 preview、卸载 iframe、复核版本快照并启动目标版本；普通 `preview.start` 继续服务 Agent 当前工作树验证，不能作为工作台运行授权或旧版本切换入口。2026-08-04 起 P3 在该生命周期上接入运行会话与 Host/Game Bridge；P3 阶段自身未接入资源替换、下一版本、测试切片编排或参数调整，P2 / P6 的当前实现以本节后续对应专节为准。
 - 右侧继续复用现有 Project Supervisor 会话、Runtime 澄清和确认链路；输入区展示 `严格审批 / 风险审批 / 无需审批` 独立面板。P0 只有严格审批可选；风险审批和无需审批保持视觉不可用但允许点击查看原因，不替代 Runtime 的逐动作权限、确认、sandbox 或 reconciliation 门禁。风险 Rank 算法记录在 `docs/project-memory/todos/【待解决】AI游戏创作高风险审批Rank-2026-07-20.md`，前端不得自行计算。
@@ -385,6 +385,7 @@ game-project/
 - Tauri 命令固定为 `read_local_project_resource_canvas_layout` 与 `update_local_project_resource_canvas_layout`。写命令先只读确认有效 manifest，再通过持久 `.layout.lock` 入口获取句柄级跨窗口系统锁，并在锁内复核 projectId、重新读取当前 sidecar。Unix 使用 `flock`，Windows 使用不共享文件句柄；释放只通过句柄 Drop / 进程退出完成，不使用 mtime stale 回收，也不删除锁文件。其余写入继续复用安全路径、链接检查、容量上限、恢复副本与原子替换能力；不能只依赖 React 状态或进程内锁。
 - 前端从当前项目开发大组件中拆出纯布局模型与持久 Hook。默认布局、碰撞检查、资源增删协调和 section 边界由纯模型负责；读取、异步身份、CAS、错误回滚和冲突载入由 Hook 负责。Hook 以 `projectPath + projectId + mode` epoch 隔离异步结果，资源变化不取消首读或在途保存；自动协调写入经同一 FIFO 串行提交，每笔都使用最近一次成功 / 冲突响应的权威 revision。资源卡是普通可点击按钮，不绑定卡片级 Pointer 拖动处理器；指针移动不修改 CSS 坐标、不调用 SVG preview、不提交手动布局 CAS。
 - 新资源只在第一次进入某个 mode 时计算默认不重叠位置；全部现存坐标保持不变。搜索、筛选、窗口 resize 和 mode 切换不得重排或回写已有坐标，窄视图通过 section 画布范围与滚动访问，不裁切持久坐标。
+- 资源卡使用绝对坐标时，最宽内容不能参与主视窗 grid 的 min-content 列宽计算：主视窗列固定为 `minmax(0, 1fr)`，资源管理容器和资源画布逐层设置 `min-width: 0`，由资源画布自身承担横纵滚动。WebKit 横向滚动轨道与滑块必须显式可见；内容未超宽时保持 `auto`，不制造无效页面级滚动。
 - type 默认布局固定按 `subtype -> mediaType -> label -> id` 排序。manifest 资产的 subtype 使用 `asset.kind`，任务产物、导入附件和 Agent 文本成果使用稳定的来源 fallback；subtype 必须进入资源协调签名，不能因 MIME 相同而退化成按名称混排。
 - 自动协调保存失败时保留当前会话布局；CAS 冲突载入对方最新布局，需要继续协调时最多追加两次重试，持续跨窗口竞争时停止自旋。用户提示只说明“布局已在其他窗口更新”，不要求重新拖动。损坏、未知 schema、身份冲突、超限与链接文件失败关闭，不能用空布局覆盖原文件。
 - 本布局持久化切片不包含资源关系线、资源替换、聚焦态持久化、缩放 / 平移、搜索 / 筛选条件、当前 mode，也不修改 `api-server` 或 SpacetimeDB。资源关系线与当前会话内中央聚焦已在后续独立前端切片接入，不改变本段 sidecar 合同；其余 P1 能力继续独立实施。
-- 
2.52.0


From 6fe52a92bbe31d53c11b0678e19c45ee821c1650 Mon Sep 17 00:00:00 2001
From: menghao <mh18530625731@163.com>
Date: Fri, 7 Aug 2026 12:44:29 +0800
Subject: [PATCH 26/27] =?UTF-8?q?=E4=BF=AE=E5=A4=8D=E5=90=88=E5=B9=B6?=
 =?UTF-8?q?=E5=90=8E=E7=9A=84=E4=BB=93=E5=BA=93=E6=A3=80=E6=9F=A5=E5=A4=B1?=
 =?UTF-8?q?=E8=B4=A5?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

删除重复维护页原子替换函数并恢复符号链接防护
清理开发栈未使用变量与资源投影正则告警
统一相关测试导入与开发栈导出顺序
---
 .../scripts/start-dev-stack.mjs                     |  3 +--
 .../project-development/resourceProjectionModel.ts  |  2 +-
 .../tests/appSurface/home.suite.ts                  |  2 +-
 .../tests/resourceCanvasLayoutModel.test.ts         |  2 +-
 .../tests/start-dev-stack.test.ts                   |  2 +-
 scripts/deploy/maintenance-on.sh                    | 13 -------------
 6 files changed, 5 insertions(+), 19 deletions(-)

diff --git a/apps/ai-game-creator-shell/scripts/start-dev-stack.mjs b/apps/ai-game-creator-shell/scripts/start-dev-stack.mjs
index df4d99980..6d15e497a 100644
--- a/apps/ai-game-creator-shell/scripts/start-dev-stack.mjs
+++ b/apps/ai-game-creator-shell/scripts/start-dev-stack.mjs
@@ -50,7 +50,6 @@ const {
   viteHost,
   vitePort,
   apiPort,
-  bgfilterWorkerPort,
   spacetimePort,
   backendDatabase,
   backendSpacetimeDataDir,
@@ -737,8 +736,8 @@ export {
   preflightExistingVite,
   readChildFailure,
   readLinuxProcessGroupAlive,
-  resolveDevStackProfile,
   resolveBackendTargetsFromState,
+  resolveDevStackProfile,
   runWindowsTaskkill,
   spawnChild,
   stopChild,
diff --git a/apps/ai-game-creator-shell/src/view/project-development/resourceProjectionModel.ts b/apps/ai-game-creator-shell/src/view/project-development/resourceProjectionModel.ts
index 82dcb4269..9d0422b01 100644
--- a/apps/ai-game-creator-shell/src/view/project-development/resourceProjectionModel.ts
+++ b/apps/ai-game-creator-shell/src/view/project-development/resourceProjectionModel.ts
@@ -60,7 +60,7 @@ function fileName(path: string) {
 
 function isConcreteTaskArtifactPath(path: string) {
   const normalizedPath = path.trim();
-  return normalizedPath.length > 0 && !/[*?\[\]{}]/u.test(normalizedPath);
+  return normalizedPath.length > 0 && !/[*?[\]{}]/u.test(normalizedPath);
 }
 
 export function classifyProjectedResource(input: {
diff --git a/apps/ai-game-creator-shell/tests/appSurface/home.suite.ts b/apps/ai-game-creator-shell/tests/appSurface/home.suite.ts
index 67cb5a6a6..a8bb6012a 100644
--- a/apps/ai-game-creator-shell/tests/appSurface/home.suite.ts
+++ b/apps/ai-game-creator-shell/tests/appSurface/home.suite.ts
@@ -1,6 +1,6 @@
+import type { RunnableGameVersion } from '../../../../packages/shared/src/contracts/gameCreationApp';
 import type { ProjectSupervisorComponentProps } from '../../src/features/app-shell/model';
 import { WorkspaceLauncherShell } from '../../src/features/app-shell/WorkspaceLauncher';
-import type { RunnableGameVersion } from '../../../../packages/shared/src/contracts/gameCreationApp';
 import {
   act,
   App,
diff --git a/apps/ai-game-creator-shell/tests/resourceCanvasLayoutModel.test.ts b/apps/ai-game-creator-shell/tests/resourceCanvasLayoutModel.test.ts
index 3de69b81c..fd57d11c8 100644
--- a/apps/ai-game-creator-shell/tests/resourceCanvasLayoutModel.test.ts
+++ b/apps/ai-game-creator-shell/tests/resourceCanvasLayoutModel.test.ts
@@ -4,12 +4,12 @@ import {
   createEmptyResourceCanvasLayout,
   moveResourceCanvasPosition,
   reconcileResourceCanvasLayout,
-  resourceCanvasContentWidth,
   RESOURCE_CANVAS_CARD_HEIGHT,
   RESOURCE_CANVAS_CARD_WIDTH,
   RESOURCE_CANVAS_COLUMN_GAP,
   RESOURCE_CANVAS_ROW_GAP,
   RESOURCE_CANVAS_SECTION_HORIZONTAL_PADDING,
+  resourceCanvasContentWidth,
   type ResourceCanvasItem,
 } from '../src/view/project-development/resourceCanvasLayoutModel';
 
diff --git a/apps/ai-game-creator-shell/tests/start-dev-stack.test.ts b/apps/ai-game-creator-shell/tests/start-dev-stack.test.ts
index a178a6e08..80c183deb 100644
--- a/apps/ai-game-creator-shell/tests/start-dev-stack.test.ts
+++ b/apps/ai-game-creator-shell/tests/start-dev-stack.test.ts
@@ -12,8 +12,8 @@ import {
   isProcessGroupAlive,
   preflightExistingVite,
   readLinuxProcessGroupAlive,
-  resolveDevStackProfile,
   resolveBackendTargetsFromState,
+  resolveDevStackProfile,
   runWindowsTaskkill,
   spawnChild,
   stopChild,
diff --git a/scripts/deploy/maintenance-on.sh b/scripts/deploy/maintenance-on.sh
index 48b6b8a2c..c1102c2aa 100644
--- a/scripts/deploy/maintenance-on.sh
+++ b/scripts/deploy/maintenance-on.sh
@@ -37,19 +37,6 @@ replace_file_atomically() {
   mv -f "${source_file}" "${target_file}"
 }
 
-replace_file_atomically() {
-  local source_file="$1"
-  local target_file="$2"
-
-  if [[ -d "${target_file}" && ! -L "${target_file}" ]]; then
-    echo "[maintenance] 原子替换目标不能是目录: ${target_file}" >&2
-    exit 1
-  fi
-  # 源文件与目标文件位于同一目录，POSIX rename 语义即可保证原子替换。
-  # 不使用 GNU mv 专属的 -T，确保 macOS/BSD 本地门禁也能执行。
-  mv -f "${source_file}" "${target_file}"
-}
-
 while [[ $# -gt 0 ]]; do
   case "$1" in
     --page-file)
-- 
2.52.0


From d04339ad7f821b4279a5fc5530af1081d11303db Mon Sep 17 00:00:00 2001
From: menghao <mh18530625731@163.com>
Date: Fri, 7 Aug 2026 13:46:16 +0800
Subject: [PATCH 27/27] =?UTF-8?q?=E4=BF=AE=E5=A4=8D=E8=87=AA=E4=B8=BB?=
 =?UTF-8?q?=E5=AE=8C=E6=88=90=E5=90=88=E5=90=8C=E6=B5=8B=E8=AF=95=E7=AB=9E?=
 =?UTF-8?q?=E6=80=81?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

隔离 readiness 状态投影，避免测试重复调度 preview-playtest child
补充 Runtime 终态投影测试的竞态避坑说明
---
 .../autonomous_completion_contract_tests.rs           | 11 ++++++++---
 docs/project-memory/shared-memory/pitfalls.md         |  7 +++++++
 2 files changed, 15 insertions(+), 3 deletions(-)

diff --git a/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_protocol/autonomous_completion_contract_tests.rs b/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_protocol/autonomous_completion_contract_tests.rs
index 21ac01088..cd27fd58e 100644
--- a/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_protocol/autonomous_completion_contract_tests.rs
+++ b/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_protocol/autonomous_completion_contract_tests.rs
@@ -5418,11 +5418,16 @@ fn preview_playtest_terminal_registers_a_runnable_snapshot_before_downstream_pub
     };
     append_game_creator_agent_runtime_task_record(&root, &readiness_terminal)
         .expect("persist completed preview readiness record");
-    project_autonomous_manifest_ready_task_terminal_at(
+    // This test isolates runnable-version registration. Calling the production
+    // terminal projector here would asynchronously schedule preview-playtest;
+    // the explicit child fixture below could then race it and create a second
+    // logical run with a generated `-dup-*` run id.
+    update_manifest_task_status_at(
         &root,
-        &agent_runtime_state_from_task_record(&readiness_terminal),
+        "preview-readiness",
+        GameCreationAppTaskStatus::Completed,
     )
-    .expect("project preview readiness completion");
+    .expect("project preview readiness completion without scheduling the next wave");
 
     update_manifest_task_status_at(
         &root,
diff --git a/docs/project-memory/shared-memory/pitfalls.md b/docs/project-memory/shared-memory/pitfalls.md
index e5a118125..d4dd1615e 100644
--- a/docs/project-memory/shared-memory/pitfalls.md
+++ b/docs/project-memory/shared-memory/pitfalls.md
@@ -4393,3 +4393,10 @@
 - 原因：冲突两侧代表不同组件架构，逐行保留看似有用的 JSX 会把一个架构中的局部条件拼进另一个架构。import 排序、格式检查和只覆盖单一 mode 的测试都不能证明这种组合成立。
 - 处理：先确定权威组件边界，再按完整调用链解决冲突。图片画布音频入口当前决策是恢复一个共享 `ImageCanvasAudioGenerationComposerView`，由组件内 `isSoundEffect` 分流；BGM/SFX 的 validator、写回、锁和提交契约仍分别保持。不要只补一个常量后继续维持已经废弃的双 composer 边界。
 - 验证：同时渲染 `audio-sound-effect` 与 `audio-background-music`，覆盖两个 mode 的正向控件和互斥负向断言、dialog / mode 切换、BGM 稳定 ID 与 controller 缺失的失败关闭，并运行 `ImageCanvasGenerationComposerView.test.tsx` 与 typecheck。
+
+## Runtime 终态投影测试不能再手工入队下一波 child（2026-08-07）
+
+- 现象：自主完成合同测试单独运行通过，在完整 native shell CI 中却偶发报“autonomous ready-task child journal 存在重复逻辑 Run”，重复项带有通用入队生成的 `-dup-*` runId。
+- 原因：`project_autonomous_manifest_ready_task_terminal_at` 在非 game-chat child 完成后会异步调度下一波；测试调用真实终态投影后，又用非幂等夹具手工入队同一个下一波任务。异步调度先落盘时，通用唯一 runId 逻辑会把手工夹具改成第二个逻辑 Run，正式 exactly-once 门禁随后按设计失败关闭。单测隔离执行时异步任务未必在断言前取得调度机会，因此容易掩盖竞态。
+- 处理：测试若关注终态投影与下一波调度，必须读取并复用生产 scheduler 创建的确定性 child；若只关注下游完成合同，应持久化所需的真实 terminal journal、验证凭证与 manifest 状态，但不要调用会启动异步下一波的终态投影后再手工入队。不得通过放宽生产侧重复逻辑 Run 门禁修复测试竞态。
+- 验证：先定向运行失败用例，再重复运行相关自主完成合同切片和完整 `npm run check:native-shells`；保留同一父 Run、taskId 与 scheduler source 下最多一个 logical child 的断言。
-- 
2.52.0