diff --git a/apps/ai-game-creator-shell/src/view/project-development/ResourcePreviewMedia.tsx b/apps/ai-game-creator-shell/src/view/project-development/ResourcePreviewMedia.tsx
index 637ab9103..281ce517c 100644
--- a/apps/ai-game-creator-shell/src/view/project-development/ResourcePreviewMedia.tsx
+++ b/apps/ai-game-creator-shell/src/view/project-development/ResourcePreviewMedia.tsx
@@ -1,10 +1,17 @@
-import { FileCode2, Image as ImageIcon, Music2, Video } from 'lucide-react';
+import {
+ FileCode2,
+ Image as ImageIcon,
+ Music2,
+ SlidersHorizontal,
+ Video,
+} from 'lucide-react';
import { useEffect, useRef } from 'react';
import {
projectResourceCardPreviewKind,
type ProjectResourceCardPreviewState,
projectResourceCardPreviewVariant,
+ projectResourceJsonPresentation,
} from './resourceCardPreviewModel';
import type { ProjectResource } from './resourceProjectionModel';
@@ -90,6 +97,16 @@ export function ResourcePreviewMedia({
const sourceUrl =
preview.status === 'loaded' ? (preview.preview.sourceUrl ?? null) : null;
const visual = (() => {
+ const jsonPresentation = resource
+ ? projectResourceJsonPresentation(resource, preview)
+ : null;
+ if (jsonPresentation) {
+ return jsonPresentation === 'ui-design' ? (
+
+ ) : (
+
+ );
+ }
if (sourceUrl && (kind === 'raster-image' || kind === 'media-image')) {
return (
![](){kind===}
{
+ if (jsonPresentation) {
+ return (
+
+ {jsonPresentation === 'ui-design' ? (
+
+ ) : (
+
+ )}
+
+ {jsonPresentation === 'ui-design' ? 'UI 编辑器' : 'JSON'}
+
+
+ );
+ }
if ((kind === 'raster-image' || kind === 'media-image') && sourceUrl) {
return (
![]()
- {resourceCategoryLabel}
+ {cardTypeLabel}
{lineage ? (
// 文字是给人看的关系，`data-resource-lineage` 是给端到端验收的稳定判据
@@ -1345,6 +1370,7 @@ function ResourceBookScene({
onPointerMove={onPointerMove}
onPointerUp={onPointerUp}
onPointerCancel={onPointerCancel}
+ onLostPointerCapture={onPointerCancel}
>
>(new Set());
const resourceCanvasPanRef = useRef<{
pointerId: number;
+ captureTarget: HTMLElement;
category: ResourceBookTarget;
startClientX: number;
startClientY: number;
@@ -3366,15 +3394,14 @@ export default function ProjectDevelopmentView({
);
const cancelResourceCanvasPan = useCallback(() => {
- const pan = resourceCanvasPanRef.current;
- if (!pan) {
- return;
- }
- const canvas = resourceCanvasRef.current;
- if (canvas?.hasPointerCapture?.(pan.pointerId)) {
- canvas.releasePointerCapture?.(pan.pointerId);
- }
+ const pans = [resourceCanvasPanRef.current, resourceBookMainPanRef.current];
resourceCanvasPanRef.current = null;
+ resourceBookMainPanRef.current = null;
+ for (const pan of pans) {
+ if (pan?.captureTarget.hasPointerCapture?.(pan.pointerId)) {
+ pan.captureTarget.releasePointerCapture(pan.pointerId);
+ }
+ }
}, []);
const cancelResourceCardDrag = useCallback(() => {
@@ -4752,6 +4779,8 @@ export default function ProjectDevelopmentView({
};
const handleBlur = () => {
resourceCanvasSpacePanRef.current = false;
+ cancelResourceCanvasPan();
+ setResourceCanvasMarquee(null);
};
window.addEventListener('keydown', handleKeyDown);
window.addEventListener('keyup', handleKeyUp);
@@ -4761,7 +4790,7 @@ export default function ProjectDevelopmentView({
window.removeEventListener('keyup', handleKeyUp);
window.removeEventListener('blur', handleBlur);
};
- }, []);
+ }, [cancelResourceCanvasPan]);
const handleResourceBookWheel = useCallback(
(event: ReactWheelEvent
| WheelEvent) => {
@@ -4858,7 +4887,10 @@ export default function ProjectDevelopmentView({
const handleResourceBookMainPointerDown = useCallback(
(event: ReactPointerEvent) => {
- if (resourceBookView !== 'main' || event.button !== 0) {
+ if (
+ resourceBookView !== 'main' ||
+ (event.button !== 0 && event.button !== 2)
+ ) {
return;
}
const target = event.target as HTMLElement;
@@ -4874,6 +4906,7 @@ export default function ProjectDevelopmentView({
resourceBookTransitionControllerRef.current.settle();
resourceBookMainPanRef.current = {
pointerId: event.pointerId,
+ captureTarget: event.currentTarget,
startClientX: event.clientX,
startClientY: event.clientY,
startViewport: resourceBookMainViewportRef.current,
@@ -5099,11 +5132,19 @@ export default function ProjectDevelopmentView({
const canvasTarget = resourceBookOpensAllResources
? RESOURCE_BOOK_ALL_TARGET
: activePageCategory;
- if (!canvasTarget || event.button > 1) {
+ if (!canvasTarget || event.button > 2) {
return;
}
const target = event.target as HTMLElement;
- if (isResourceCanvasInteractionTarget(target)) {
+ const isPan =
+ event.button === 2 ||
+ event.button === 1 ||
+ resourceCanvasSpacePanRef.current;
+ if (
+ event.button === 2
+ ? !isResourceCanvasPanTarget(target)
+ : isResourceCanvasInteractionTarget(target)
+ ) {
return;
}
// 点选态下空白处的左键不起框选、也不清画布焦点/选中：点选只认资源卡，
@@ -5117,12 +5158,13 @@ export default function ProjectDevelopmentView({
return;
}
resourceBookTransitionControllerRef.current.settle();
- // 与美术画布一致：中键或按住空格是平移，左键在空白处是框选。
- if (event.button === 1 || resourceCanvasSpacePanRef.current) {
+ // 右键平移，保留中键/空格抓手；空白处左键继续框选。
+ if (isPan) {
event.preventDefault();
event.currentTarget.setPointerCapture(event.pointerId);
resourceCanvasPanRef.current = {
pointerId: event.pointerId,
+ captureTarget: event.currentTarget,
category: canvasTarget,
startClientX: event.clientX,
startClientY: event.clientY,
@@ -5295,12 +5337,22 @@ export default function ProjectDevelopmentView({
const openResourceUiEditor = useCallback(
(resource: ProjectResource) => {
- if (resource.subtype === 'ui-prototype') {
+ const identity = resourceCardPreviews.identityByResourceId.get(
+ resource.id,
+ );
+ const jsonPresentation = projectResourceJsonPresentation(
+ resource,
+ identity ? resourceCardPreviews.previews.get(identity) : null,
+ );
+ if (resource.subtype === 'ui-prototype' && jsonPresentation === null) {
void openUiDesignEditor(resource);
return;
}
- if (resource.manifestAssetId === null) {
- setResourceWorkbenchNotice('该 UI 资源缺少有效的正式资产身份');
+ if (
+ resource.manifestAssetId === null ||
+ jsonPresentation !== 'ui-design'
+ ) {
+ setResourceWorkbenchNotice('该资源尚未通过 UI 设计 JSON 校验');
return;
}
canvasOpenEpochRef.current += 1;
@@ -5321,7 +5373,13 @@ export default function ProjectDevelopmentView({
: {}),
});
},
- [advanceFocusGeneration, manifest.assets, openUiDesignEditor],
+ [
+ advanceFocusGeneration,
+ manifest.assets,
+ openUiDesignEditor,
+ resourceCardPreviews.identityByResourceId,
+ resourceCardPreviews.previews,
+ ],
);
/**
@@ -6205,8 +6263,7 @@ export default function ProjectDevelopmentView({
setMode('run');
}
- const showRunUnavailableHint =
- !runAvailable && selectedResourceIds.length === 0 && !uiEditorRoute;
+ const showRunUnavailableHint = !runAvailable && !uiEditorRoute;
const renderResourceBookCard = useCallback(
(
@@ -7460,9 +7517,16 @@ export default function ProjectDevelopmentView({
: null,
[manifest, selectedResource],
);
+ const selectedResourceJsonPresentation = selectedResource
+ ? projectResourceJsonPresentation(
+ selectedResource,
+ selectedResourceCardPreview,
+ )
+ : null;
const selectedResourceOpensUiEditor =
- selectedResource?.subtype === 'UI' ||
- selectedResource?.subtype === 'ui-prototype';
+ selectedResourceJsonPresentation === 'ui-design' ||
+ (selectedResourceJsonPresentation === null &&
+ selectedResource?.subtype === 'ui-prototype');
const selectedToolbarStyle = selectedResourceLayer
? resolveSelectedToolbarStyle({
@@ -7850,10 +7914,24 @@ export default function ProjectDevelopmentView({
className={`game-resource-manager game-resource-book-manager game-resource-book-manager--${resourceBookState.view} game-resource-book-manager--${resourceBookState.phase}`}
data-resource-book-view={resourceBookState.view}
data-resource-book-transition={resourceBookState.phase}
+ onContextMenu={(event) => {
+ const target = event.target as Element;
+ if (
+ event.button === 2 &&
+ event.currentTarget.contains(target) &&
+ target.closest(
+ '.game-resource-book-scene, .game-resource-canvas, .game-resource-book-main',
+ ) &&
+ isResourceCanvasPanTarget(target)
+ ) {
+ event.preventDefault();
+ }
+ }}
onPointerDownCapture={(event) => {
if (
event.currentTarget.dataset.resourceBookTransition !==
'idle' &&
+ event.button === 0 &&
(event.target as Element).closest('.game-resource-card')
) {
event.preventDefault();
@@ -7927,7 +8005,8 @@ export default function ProjectDevelopmentView({
预览
) : null}
- {selectedResourceOpensUiEditor ? (
+ {selectedResource &&
+ selectedResourceOpensUiEditor ? (
{sortMode === 'dependency' &&
dependencyRelationshipDescriptions.length > 0 ? (
diff --git a/apps/ai-game-creator-shell/src/view/project-development/resourceCardPreviewModel.ts b/apps/ai-game-creator-shell/src/view/project-development/resourceCardPreviewModel.ts
index c97057461..979015c52 100644
--- a/apps/ai-game-creator-shell/src/view/project-development/resourceCardPreviewModel.ts
+++ b/apps/ai-game-creator-shell/src/view/project-development/resourceCardPreviewModel.ts
@@ -58,6 +58,8 @@ export type ProjectResourceCardPreviewPayload = {
hasAlpha?: boolean;
sourceUrl?: string;
content?: string;
+ /** 原生侧完整校验过的 UI State 资产身份，不由前端解析 JSON 推断。 */
+ uiDesignAssetId?: string;
};
export type ProjectResourceCardPreviewTransportPayload = Omit<
@@ -219,7 +221,8 @@ const markdownExtension = /\.(md|markdown|mdx)$/iu;
* 与 `resourceProjectionModel` 的 `gameCodeExtension` 是两份口径，刻意不复用：
* 那份用于**筛选与归属**，改动会波及画布栏目与计数；这份只决定**卡面怎么画**。
* 这里按用户口径把 `.yaml` / `.toml` / `.xml` / `.html` / `.css` / `.sql`
- * 一并算代码；JSON 规格属于文档预览。
+ * 一并算代码。JSON 留在文本读取通道，由原生内容识别区分普通 JSON 和 UI 设计，
+ * 不能像源码卡一样跳过预取；卡面不显示 JSON 正文。
*/
const cardCodeExtension =
/\.(ts|tsx|mts|cts|js|jsx|mjs|cjs|rs|py|go|java|kt|kts|cs|cpp|cc|cxx|c|h|hpp|swift|php|rb|lua|sh|bash|zsh|ps1|psm1|ya?ml|toml|xml|html?|css|scss|less|sql|graphql|gql|vue|svelte)$/iu;
@@ -236,6 +239,30 @@ export function projectResourcePathExtension(path: string): string | null {
return matched ? matched[1]!.toLowerCase() : null;
}
+export function isProjectResourceJson(
+ resource: Pick,
+): boolean {
+ return (
+ projectResourcePathExtension(resource.path) === 'json' ||
+ (projectResourcePathExtension(resource.path) === null &&
+ resource.mediaType.toLowerCase().includes('json'))
+ );
+}
+
+/** 读取结果必须仍属于当前卡片；元数据中的 UI 标签本身不能授予编辑入口。 */
+export function projectResourceJsonPresentation(
+ resource: ProjectResource,
+ preview: ProjectResourceCardPreviewState | null | undefined,
+): 'json' | 'ui-design' | null {
+ if (!isProjectResourceJson(resource)) return null;
+ return resource.manifestAssetId &&
+ preview?.status === 'loaded' &&
+ preview.preview.path === resource.path &&
+ preview.preview.uiDesignAssetId === resource.manifestAssetId
+ ? 'ui-design'
+ : 'json';
+}
+
/** 代码文件的类型标签（如 `.ts` → `TS`）；不是代码文件时返回 `null`。 */
export function projectResourceCodeTypeLabel(path: string): string | null {
const trimmed = path.trim();
@@ -256,7 +283,7 @@ export function projectResourceCardPreviewKind(
return 'document';
}
// Markdown / 代码在扩展名这一层就分流，不再依赖上游登记类型：
- // 上游把 JSON 规格登记成「文档」，卡面按文档预览；代码文件按扩展名分流。
+ // JSON 使用文档读取通道完成原生语义识别；源码文件按扩展名分流。
if (markdownExtension.test(resource.path)) {
return 'document';
}
diff --git a/apps/ai-game-creator-shell/src/view/project-development/resourceEditModel.ts b/apps/ai-game-creator-shell/src/view/project-development/resourceEditModel.ts
index ae4bfe73e..4d739bec6 100644
--- a/apps/ai-game-creator-shell/src/view/project-development/resourceEditModel.ts
+++ b/apps/ai-game-creator-shell/src/view/project-development/resourceEditModel.ts
@@ -224,6 +224,12 @@ export function defaultCharacterAnimationResourceName(
return `${resourceBaseName(resource) || '资源'}-角色动画`;
}
+/**
+ * 资源编辑提示词上限：与 Rust `resource_edit_prompt_max_chars`
+ * （`src-tauri/src/project/resource_editor.rs`）逐值同口径，UI、资源编辑提交、
+ * `agc_tools` MCP 工具层与客户端工具桥共用同一组数字。改这里必须同时改那里，
+ * 并按 kind 同步 `direct_tools_mcp.rs` 工具 schema 里的 `prompt.maxLength`。
+ */
export function resourceEditPromptMaxLength(
editKind: LocalProjectResourceEditKind,
) {
diff --git a/apps/ai-game-creator-shell/src/view/project-development/useProjectResourceCardPreviews.ts b/apps/ai-game-creator-shell/src/view/project-development/useProjectResourceCardPreviews.ts
index f175264ba..729658ceb 100644
--- a/apps/ai-game-creator-shell/src/view/project-development/useProjectResourceCardPreviews.ts
+++ b/apps/ai-game-creator-shell/src/view/project-development/useProjectResourceCardPreviews.ts
@@ -167,6 +167,7 @@ function materializeProjectResourceCardPreview(
pixelHeight: transport.pixelHeight,
hasAlpha: transport.hasAlpha,
content: transport.content,
+ uiDesignAssetId: transport.uiDesignAssetId,
},
retainedBytes:
transport.content === undefined
diff --git a/apps/ai-game-creator-shell/src/view/template-library/TemplateCard.tsx b/apps/ai-game-creator-shell/src/view/template-library/TemplateCard.tsx
new file mode 100644
index 000000000..c484074ba
--- /dev/null
+++ b/apps/ai-game-creator-shell/src/view/template-library/TemplateCard.tsx
@@ -0,0 +1,139 @@
+import { BadgeCheck, Download, Loader2, Play } from 'lucide-react';
+import { memo } from 'react';
+
+import type { GameTemplateEntry } from '../../features/template-library/templateLibraryModel';
+import {
+ formatGameTemplateSize,
+ needsTemplateDownload,
+ templateRuntimeLabel,
+} from '../../features/template-library/templateLibraryModel';
+
+export type TemplateCardActions = {
+ busyKind: 'download' | 'create' | null;
+ busyTemplateId: string | null;
+ onDownload: (template: GameTemplateEntry) => void;
+ onUse: (template: GameTemplateEntry) => void;
+};
+
+/**
+ * 虚拟列表里的单个模板卡片：高度由行高契约固定（封面 16:9 + 固定文字区），
+ * 用 memo 包住，滚动时只重渲染可视区域内的少量卡片。
+ */
+function TemplateCardView({
+ template,
+ busyKind,
+ busyTemplateId,
+ onDownload,
+ onUse,
+}: { template: GameTemplateEntry } & TemplateCardActions) {
+ const busy = busyTemplateId === template.id;
+ const needsDownload = needsTemplateDownload(template);
+ const busyLabel =
+ busy && busyKind === 'download'
+ ? '正在下载模板'
+ : busy && busyKind === 'create'
+ ? '正在创建项目'
+ : '';
+ const meta = [
+ templateRuntimeLabel(template.runtime),
+ template.engine,
+ `v${template.templateVersion}`,
+ formatGameTemplateSize(template.zipSizeBytes),
+ ]
+ .filter((value) => value && value.trim())
+ .join(' · ');
+
+ return (
+
+
+
+ {template.installed ? (
+
+
+ 已下载
+
+ ) : null}
+
+
+ {template.title}
+
+
+ {meta}
+
+ {template.summary ? (
+
+ {template.summary}
+
+ ) : null}
+ {template.tags.length > 0 ? (
+
+ {template.tags.map((tag) => (
+
+ {tag}
+
+ ))}
+
+ ) : null}
+
+
+ {/* 已下载且版本一致时不再提供下载入口；只有缺包或版本落后才显示（落后时按「更新」）。 */}
+ {needsDownload ? (
+
+ ) : null}
+ {busyLabel ? (
+
+ {busyLabel}
+
+ ) : null}
+
+
+
+
+ );
+}
+
+export default function TemplateLibraryView({
+ controller,
+ onBack,
+}: TemplateLibraryViewProps) {
+ const {
+ status,
+ error,
+ notice,
+ templates,
+ visibleTemplates,
+ tagOptions,
+ runtimeOptions,
+ installedCount,
+ filters,
+ filtersActive,
+ setQuery,
+ selectRuntime,
+ toggleTag,
+ setInstalledOnly,
+ clearFilters,
+ busyTemplateId,
+ busyKind,
+ refresh,
+ downloadTemplate,
+ createProjectFromTemplate,
+ clearNotice,
+ } = controller;
+
+ const gridRef = useRef(null);
+ const viewportRef = useRef(null);
+ const sectionRef = useRef(null);
+ const [sectionHeight, setSectionHeight] = useState(null);
+ const [viewportSize, setViewportSize] = useState({ width: 0, height: 0 });
+
+ const showEmptyLibrary = status === 'ready' && templates.length === 0;
+ const showNoMatch =
+ status === 'ready' && templates.length > 0 && visibleTemplates.length === 0;
+ const showGrid = status === 'ready' && visibleTemplates.length > 0;
+
+ /**
+ * 页面高度按**父级实测高度**定，不用百分比也不用 100vh。
+ *
+ * 外壳样式 `.launcher-main > .platform-theme { height: 100% }` 特异性高于 Tailwind
+ * 工具类，而它的百分比在 `.launcher-shell { min-height: 100vh }` 这条链上是不定高，
+ * 页面会退化成内容高度（虚拟网格视口高度 0、卡片区空白）；`100vh` 又比真实舞台高
+ * 一个标题栏（窗口 100vh=800、舞台 750），底部会被裁掉。这里直接量父级。
+ */
+ useEffect(() => {
+ const section = sectionRef.current;
+ const parent = section?.parentElement;
+ if (!section || !parent) {
+ return;
+ }
+ const apply = () => {
+ const height = Math.round(parent.getBoundingClientRect().height);
+ if (height > 0) {
+ setSectionHeight((current) => (current === height ? current : height));
+ }
+ };
+ apply();
+ if (typeof ResizeObserver === 'undefined') {
+ window.addEventListener('resize', apply);
+ return () => window.removeEventListener('resize', apply);
+ }
+ const observer = new ResizeObserver(apply);
+ observer.observe(parent);
+ return () => observer.disconnect();
+ }, []);
+
+ useEffect(() => {
+ const element = viewportRef.current;
+ if (!element) {
+ return;
+ }
+ const measure = () => {
+ const rect = element.getBoundingClientRect();
+ const width = Math.round(rect.width);
+ const height = Math.round(rect.height);
+ setViewportSize((current) =>
+ current.width === width && current.height === height
+ ? current
+ : { width, height },
+ );
+ };
+ measure();
+ if (typeof ResizeObserver === 'undefined') {
+ window.addEventListener('resize', measure);
+ return () => window.removeEventListener('resize', measure);
+ }
+ const observer = new ResizeObserver(measure);
+ observer.observe(element);
+ return () => observer.disconnect();
+ }, [showGrid]);
+
+ const layout = useMemo(
+ () =>
+ computeTemplateGridLayout({
+ containerWidth: viewportSize.width,
+ itemCount: visibleTemplates.length,
+ }),
+ [viewportSize.width, visibleTemplates.length],
+ );
+ const rows = useMemo(
+ () => buildTemplateRows(visibleTemplates, layout.columnCount),
+ [visibleTemplates, layout.columnCount],
+ );
+
+ // 换筛选条件回到列表顶部：否则筛选后条目变少会把视口留在空白处，看起来像“卡住”。
+ useEffect(() => {
+ gridRef.current?.scrollTo({ scrollTop: 0 });
+ }, [
+ filters.query,
+ filters.tags,
+ filters.runtime,
+ filters.installedOnly,
+ layout.columnCount,
+ ]);
+
+ const handleDownload = useMemo(
+ () => (template: GameTemplateEntry) => {
+ void downloadTemplate(template).catch(() => undefined);
+ },
+ [downloadTemplate],
+ );
+ const handleUse = useMemo(
+ () => (template: GameTemplateEntry) => {
+ void createProjectFromTemplate(template).catch(() => undefined);
+ },
+ [createProjectFromTemplate],
+ );
+ const cellData = useMemo(
+ () => ({
+ rows,
+ busyKind,
+ busyTemplateId,
+ onDownload: handleDownload,
+ onUse: handleUse,
+ }),
+ [rows, busyKind, busyTemplateId, handleDownload, handleUse],
+ );
+
+ return (
+
+
+
+
+
+ 模板库
+
+
+ 共 {templates.length} 个模板 · 已下载 {installedCount} 个
+
+
+
+
+
+ {/* 标签/运行时筛选区可独立滚动：标签数量随库量增长时不会把卡片区挤出窗口。 */}
+
+
+
+
+ {filtersActive ? (
+
+ ) : null}
+
+ {runtimeOptions.length > 0 ? (
+
+
+
+ 运行时
+
+ {runtimeOptions.map((runtime) => (
+
+ ))}
+
+ ) : null}
+ {tagOptions.length > 0 ? (
+
+
+ 标签
+
+ {tagOptions.map((tag) => (
+
+ ))}
+
+ ) : null}
+
+ {error}
+
+
+ ) : null}
+
+ {status === 'loading' && templates.length === 0 ? (
+
+ 正在读取模板库…
+
+ ) : null}
+ {showEmptyLibrary ? (
+
+ 模板库暂时还没有可用的模板。
+
+ ) : null}
+ {showNoMatch ? (
+
+
+ 没有符合当前筛选的模板
+
+
+ ) : null}
+
+ {showGrid ? (
+
+ {viewportSize.width > 0 && viewportSize.height > 0 ? (
+
+ templateGridItemKey(rowIndex, columnIndex)
+ }
+ >
+ {TemplateGridCell}
+
+ ) : null}
+
+ ) : null}
+
+ );
+}
diff --git a/apps/ai-game-creator-shell/template-library/v1/blank-2d-canvas/cover.svg b/apps/ai-game-creator-shell/template-library/v1/blank-2d-canvas/cover.svg
new file mode 100644
index 000000000..48439503b
--- /dev/null
+++ b/apps/ai-game-creator-shell/template-library/v1/blank-2d-canvas/cover.svg
@@ -0,0 +1,13 @@
+
diff --git a/apps/ai-game-creator-shell/template-library/v1/blank-2d-canvas/meta.json b/apps/ai-game-creator-shell/template-library/v1/blank-2d-canvas/meta.json
new file mode 100644
index 000000000..5c3bdbb8e
--- /dev/null
+++ b/apps/ai-game-creator-shell/template-library/v1/blank-2d-canvas/meta.json
@@ -0,0 +1,18 @@
+{
+ "id": "blank-2d-canvas",
+ "title": "空白二维画布工程",
+ "summary": "原生 Canvas 二维空白工程：自适应画布、按设备像素比缩放与 requestAnimationFrame 主循环已就绪。",
+ "tags": [
+ "空白",
+ "起步工程",
+ "2d",
+ "canvas"
+ ],
+ "runtime": "html",
+ "engine": "canvas",
+ "engineVersion": "",
+ "templateVersion": "0.1.0",
+ "entry": "game/index.html",
+ "coverWidth": 960,
+ "coverHeight": 540
+}
diff --git a/apps/ai-game-creator-shell/template-library/v1/blank-2d-canvas/project/game/index.html b/apps/ai-game-creator-shell/template-library/v1/blank-2d-canvas/project/game/index.html
new file mode 100644
index 000000000..0aa1ef189
--- /dev/null
+++ b/apps/ai-game-creator-shell/template-library/v1/blank-2d-canvas/project/game/index.html
@@ -0,0 +1,10 @@
+
+
+
+
+
+ Genarrative Game Draft
+
+
+
+
diff --git a/apps/ai-game-creator-shell/template-library/v1/blank-2d-canvas/project/game/main.js b/apps/ai-game-creator-shell/template-library/v1/blank-2d-canvas/project/game/main.js
new file mode 100644
index 000000000..bfdce3f80
--- /dev/null
+++ b/apps/ai-game-creator-shell/template-library/v1/blank-2d-canvas/project/game/main.js
@@ -0,0 +1,30 @@
+const canvas = document.querySelector('#stage');
+const context = canvas.getContext('2d');
+let viewport = { width: 0, height: 0 };
+
+function resize() {
+ const ratio = window.devicePixelRatio || 1;
+ viewport = { width: window.innerWidth, height: window.innerHeight };
+ canvas.width = Math.floor(viewport.width * ratio);
+ canvas.height = Math.floor(viewport.height * ratio);
+ context.setTransform(ratio, 0, 0, ratio, 0, 0);
+}
+
+function update(_deltaSeconds) {}
+
+function render() {
+ context.clearRect(0, 0, viewport.width, viewport.height);
+}
+
+let previous = performance.now();
+function frame(now) {
+ const deltaSeconds = Math.min((now - previous) / 1000, 0.1);
+ previous = now;
+ update(deltaSeconds);
+ render();
+ requestAnimationFrame(frame);
+}
+
+window.addEventListener('resize', resize);
+resize();
+requestAnimationFrame(frame);
diff --git a/apps/ai-game-creator-shell/template-library/v1/blank-2d-canvas/project/game/package.json b/apps/ai-game-creator-shell/template-library/v1/blank-2d-canvas/project/game/package.json
new file mode 100644
index 000000000..6352b75bc
--- /dev/null
+++ b/apps/ai-game-creator-shell/template-library/v1/blank-2d-canvas/project/game/package.json
@@ -0,0 +1,12 @@
+{
+ "name": "agc-game",
+ "private": true,
+ "type": "module",
+ "scripts": {
+ "build": "vite build",
+ "dev": "vite"
+ },
+ "devDependencies": {
+ "vite": "^6.2.0"
+ }
+}
diff --git a/apps/ai-game-creator-shell/template-library/v1/blank-2d-canvas/project/game/style.css b/apps/ai-game-creator-shell/template-library/v1/blank-2d-canvas/project/game/style.css
new file mode 100644
index 000000000..f1256b925
--- /dev/null
+++ b/apps/ai-game-creator-shell/template-library/v1/blank-2d-canvas/project/game/style.css
@@ -0,0 +1,3 @@
+body { margin: 0; overflow: hidden; background: #0b1512; }
+main { display: block; width: 100vw; height: 100vh; }
+canvas { display: block; width: 100%; height: 100%; }
diff --git a/apps/ai-game-creator-shell/template-library/v1/blank-2d-canvas/project/game/vite.config.js b/apps/ai-game-creator-shell/template-library/v1/blank-2d-canvas/project/game/vite.config.js
new file mode 100644
index 000000000..d8e631e07
--- /dev/null
+++ b/apps/ai-game-creator-shell/template-library/v1/blank-2d-canvas/project/game/vite.config.js
@@ -0,0 +1,7 @@
+import { defineConfig } from 'vite';
+
+export default defineConfig({
+ root: '.',
+ base: './',
+ build: { outDir: 'dist', emptyOutDir: true },
+});
diff --git a/apps/ai-game-creator-shell/template-library/v1/blank-3d-scene/cover.svg b/apps/ai-game-creator-shell/template-library/v1/blank-3d-scene/cover.svg
new file mode 100644
index 000000000..8da38262d
--- /dev/null
+++ b/apps/ai-game-creator-shell/template-library/v1/blank-3d-scene/cover.svg
@@ -0,0 +1,13 @@
+
diff --git a/apps/ai-game-creator-shell/template-library/v1/blank-3d-scene/meta.json b/apps/ai-game-creator-shell/template-library/v1/blank-3d-scene/meta.json
new file mode 100644
index 000000000..f099612e4
--- /dev/null
+++ b/apps/ai-game-creator-shell/template-library/v1/blank-3d-scene/meta.json
@@ -0,0 +1,18 @@
+{
+ "id": "blank-3d-scene",
+ "title": "空白三维场景工程",
+ "summary": "Three.js 空白场景：空场景、透视相机、网格地面与自适应视口已就绪，适合从零搭三维玩法。",
+ "tags": [
+ "空白",
+ "起步工程",
+ "3d",
+ "three.js"
+ ],
+ "runtime": "html",
+ "engine": "three.js",
+ "engineVersion": "0.180.0",
+ "templateVersion": "0.1.0",
+ "entry": "game/index.html",
+ "coverWidth": 960,
+ "coverHeight": 540
+}
diff --git a/apps/ai-game-creator-shell/template-library/v1/blank-3d-scene/project/game/index.html b/apps/ai-game-creator-shell/template-library/v1/blank-3d-scene/project/game/index.html
new file mode 100644
index 000000000..d01aa860a
--- /dev/null
+++ b/apps/ai-game-creator-shell/template-library/v1/blank-3d-scene/project/game/index.html
@@ -0,0 +1,10 @@
+
+
+
+
+
+ Genarrative Game Draft
+
+
+
+
diff --git a/apps/ai-game-creator-shell/template-library/v1/blank-3d-scene/project/game/main.js b/apps/ai-game-creator-shell/template-library/v1/blank-3d-scene/project/game/main.js
new file mode 100644
index 000000000..73c37324b
--- /dev/null
+++ b/apps/ai-game-creator-shell/template-library/v1/blank-3d-scene/project/game/main.js
@@ -0,0 +1,38 @@
+import * as THREE from 'three';
+
+const container = document.querySelector('#game');
+const scene = new THREE.Scene();
+scene.background = new THREE.Color(0x070b14);
+
+const camera = new THREE.PerspectiveCamera(
+ 60,
+ window.innerWidth / window.innerHeight,
+ 0.1,
+ 200,
+);
+camera.position.set(0, 3, 6);
+camera.lookAt(0, 0, 0);
+
+const renderer = new THREE.WebGLRenderer({ antialias: true });
+renderer.setPixelRatio(window.devicePixelRatio);
+renderer.setSize(window.innerWidth, window.innerHeight);
+container.append(renderer.domElement);
+
+const light = new THREE.DirectionalLight(0xffffff, 1.2);
+light.position.set(4, 8, 6);
+scene.add(light, new THREE.AmbientLight(0x8899ff, 0.5));
+
+const grid = new THREE.GridHelper(20, 20, 0x3b4a6b, 0x1d2739);
+scene.add(grid);
+
+window.addEventListener('resize', () => {
+ camera.aspect = window.innerWidth / window.innerHeight;
+ camera.updateProjectionMatrix();
+ renderer.setSize(window.innerWidth, window.innerHeight);
+});
+
+function render() {
+ renderer.render(scene, camera);
+ requestAnimationFrame(render);
+}
+render();
diff --git a/apps/ai-game-creator-shell/template-library/v1/blank-3d-scene/project/game/package.json b/apps/ai-game-creator-shell/template-library/v1/blank-3d-scene/project/game/package.json
new file mode 100644
index 000000000..496deca74
--- /dev/null
+++ b/apps/ai-game-creator-shell/template-library/v1/blank-3d-scene/project/game/package.json
@@ -0,0 +1,15 @@
+{
+ "name": "agc-game",
+ "private": true,
+ "type": "module",
+ "scripts": {
+ "build": "vite build",
+ "dev": "vite"
+ },
+ "dependencies": {
+ "three": "^0.180.0"
+ },
+ "devDependencies": {
+ "vite": "^6.2.0"
+ }
+}
diff --git a/apps/ai-game-creator-shell/template-library/v1/blank-3d-scene/project/game/style.css b/apps/ai-game-creator-shell/template-library/v1/blank-3d-scene/project/game/style.css
new file mode 100644
index 000000000..a3c5a9c8c
--- /dev/null
+++ b/apps/ai-game-creator-shell/template-library/v1/blank-3d-scene/project/game/style.css
@@ -0,0 +1,3 @@
+body { margin: 0; overflow: hidden; background: #05070d; }
+main { display: block; width: 100vw; height: 100vh; }
+canvas { display: block; }
diff --git a/apps/ai-game-creator-shell/template-library/v1/blank-3d-scene/project/game/vite.config.js b/apps/ai-game-creator-shell/template-library/v1/blank-3d-scene/project/game/vite.config.js
new file mode 100644
index 000000000..d8e631e07
--- /dev/null
+++ b/apps/ai-game-creator-shell/template-library/v1/blank-3d-scene/project/game/vite.config.js
@@ -0,0 +1,7 @@
+import { defineConfig } from 'vite';
+
+export default defineConfig({
+ root: '.',
+ base: './',
+ build: { outDir: 'dist', emptyOutDir: true },
+});
diff --git a/apps/ai-game-creator-shell/template-library/v1/blank-web/cover.svg b/apps/ai-game-creator-shell/template-library/v1/blank-web/cover.svg
new file mode 100644
index 000000000..ac7c02d1b
--- /dev/null
+++ b/apps/ai-game-creator-shell/template-library/v1/blank-web/cover.svg
@@ -0,0 +1,13 @@
+
diff --git a/apps/ai-game-creator-shell/template-library/v1/blank-web/meta.json b/apps/ai-game-creator-shell/template-library/v1/blank-web/meta.json
new file mode 100644
index 000000000..a92652137
--- /dev/null
+++ b/apps/ai-game-creator-shell/template-library/v1/blank-web/meta.json
@@ -0,0 +1,18 @@
+{
+ "id": "blank-web",
+ "title": "空白网页工程",
+ "summary": "最小网页工程（HTML + CSS + 原生 JS + Vite），没有任何引擎依赖，适合从零写玩法。",
+ "tags": [
+ "空白",
+ "起步工程",
+ "网页",
+ "原生"
+ ],
+ "runtime": "html",
+ "engine": "none",
+ "engineVersion": "",
+ "templateVersion": "0.1.0",
+ "entry": "game/index.html",
+ "coverWidth": 960,
+ "coverHeight": 540
+}
diff --git a/apps/ai-game-creator-shell/template-library/v1/blank-web/project/game/index.html b/apps/ai-game-creator-shell/template-library/v1/blank-web/project/game/index.html
new file mode 100644
index 000000000..d01aa860a
--- /dev/null
+++ b/apps/ai-game-creator-shell/template-library/v1/blank-web/project/game/index.html
@@ -0,0 +1,10 @@
+
+
+
+
+
+ Genarrative Game Draft
+
+
+
+
diff --git a/apps/ai-game-creator-shell/template-library/v1/blank-web/project/game/main.js b/apps/ai-game-creator-shell/template-library/v1/blank-web/project/game/main.js
new file mode 100644
index 000000000..f2307680d
--- /dev/null
+++ b/apps/ai-game-creator-shell/template-library/v1/blank-web/project/game/main.js
@@ -0,0 +1,2 @@
+const root = document.querySelector('#game');
+root.textContent = '';
diff --git a/apps/ai-game-creator-shell/template-library/v1/blank-web/project/game/package.json b/apps/ai-game-creator-shell/template-library/v1/blank-web/project/game/package.json
new file mode 100644
index 000000000..6352b75bc
--- /dev/null
+++ b/apps/ai-game-creator-shell/template-library/v1/blank-web/project/game/package.json
@@ -0,0 +1,12 @@
+{
+ "name": "agc-game",
+ "private": true,
+ "type": "module",
+ "scripts": {
+ "build": "vite build",
+ "dev": "vite"
+ },
+ "devDependencies": {
+ "vite": "^6.2.0"
+ }
+}
diff --git a/apps/ai-game-creator-shell/template-library/v1/blank-web/project/game/style.css b/apps/ai-game-creator-shell/template-library/v1/blank-web/project/game/style.css
new file mode 100644
index 000000000..e40ed7036
--- /dev/null
+++ b/apps/ai-game-creator-shell/template-library/v1/blank-web/project/game/style.css
@@ -0,0 +1,2 @@
+body { margin: 0; background: #0f1218; color: #e8eefc; font: 16px system-ui, sans-serif; }
+main { display: grid; min-height: 100vh; place-items: center; }
diff --git a/apps/ai-game-creator-shell/template-library/v1/blank-web/project/game/vite.config.js b/apps/ai-game-creator-shell/template-library/v1/blank-web/project/game/vite.config.js
new file mode 100644
index 000000000..d8e631e07
--- /dev/null
+++ b/apps/ai-game-creator-shell/template-library/v1/blank-web/project/game/vite.config.js
@@ -0,0 +1,7 @@
+import { defineConfig } from 'vite';
+
+export default defineConfig({
+ root: '.',
+ base: './',
+ build: { outDir: 'dist', emptyOutDir: true },
+});
diff --git a/apps/ai-game-creator-shell/template-library/v1/phaser-2d-starter/cover.svg b/apps/ai-game-creator-shell/template-library/v1/phaser-2d-starter/cover.svg
new file mode 100644
index 000000000..0d00d4b79
--- /dev/null
+++ b/apps/ai-game-creator-shell/template-library/v1/phaser-2d-starter/cover.svg
@@ -0,0 +1,13 @@
+
diff --git a/apps/ai-game-creator-shell/template-library/v1/phaser-2d-starter/meta.json b/apps/ai-game-creator-shell/template-library/v1/phaser-2d-starter/meta.json
new file mode 100644
index 000000000..71f52ba90
--- /dev/null
+++ b/apps/ai-game-creator-shell/template-library/v1/phaser-2d-starter/meta.json
@@ -0,0 +1,18 @@
+{
+ "id": "phaser-2d-starter",
+ "title": "Phaser 2D 起步工程",
+ "summary": "AGC 新建项目使用的默认二维起步工程（Phaser 4 + Vite），解压后即为可运行项目根。",
+ "tags": [
+ "起步工程",
+ "2d",
+ "phaser",
+ "像素"
+ ],
+ "runtime": "html",
+ "engine": "phaser",
+ "engineVersion": "4.2.1",
+ "templateVersion": "0.1.0",
+ "entry": "game/index.html",
+ "coverWidth": 960,
+ "coverHeight": 540
+}
diff --git a/apps/ai-game-creator-shell/template-library/v1/phaser-2d-starter/project/game/game.js b/apps/ai-game-creator-shell/template-library/v1/phaser-2d-starter/project/game/game.js
new file mode 100644
index 000000000..a77ba6be9
--- /dev/null
+++ b/apps/ai-game-creator-shell/template-library/v1/phaser-2d-starter/project/game/game.js
@@ -0,0 +1,21 @@
+import './style.css';
+
+import Phaser from 'phaser';
+
+class PlaceholderScene extends Phaser.Scene {
+ create() {
+ this.add.text(
+ 24,
+ 24,
+ '还没有生成游戏。回到聊天输入创意并确认生成后，这里会写入可试玩原型。',
+ );
+ }
+}
+
+new Phaser.Game({
+ type: Phaser.AUTO,
+ width: 720,
+ height: 420,
+ parent: 'game',
+ scene: PlaceholderScene,
+});
diff --git a/apps/ai-game-creator-shell/template-library/v1/phaser-2d-starter/project/game/index.html b/apps/ai-game-creator-shell/template-library/v1/phaser-2d-starter/project/game/index.html
new file mode 100644
index 000000000..3447d5909
--- /dev/null
+++ b/apps/ai-game-creator-shell/template-library/v1/phaser-2d-starter/project/game/index.html
@@ -0,0 +1,9 @@
+
+
+
+
+
+ Genarrative Game Draft
+
+
+
diff --git a/apps/ai-game-creator-shell/template-library/v1/phaser-2d-starter/project/game/package.json b/apps/ai-game-creator-shell/template-library/v1/phaser-2d-starter/project/game/package.json
new file mode 100644
index 000000000..6504e9aee
--- /dev/null
+++ b/apps/ai-game-creator-shell/template-library/v1/phaser-2d-starter/project/game/package.json
@@ -0,0 +1,15 @@
+{
+ "name": "agc-game",
+ "private": true,
+ "type": "module",
+ "scripts": {
+ "build": "vite build",
+ "dev": "vite"
+ },
+ "dependencies": {
+ "phaser": "4.2.1"
+ },
+ "devDependencies": {
+ "vite": "^6.2.0"
+ }
+}
diff --git a/apps/ai-game-creator-shell/template-library/v1/phaser-2d-starter/project/game/style.css b/apps/ai-game-creator-shell/template-library/v1/phaser-2d-starter/project/game/style.css
new file mode 100644
index 000000000..8b3c907f4
--- /dev/null
+++ b/apps/ai-game-creator-shell/template-library/v1/phaser-2d-starter/project/game/style.css
@@ -0,0 +1,2 @@
+body { margin: 0; display: grid; min-height: 100vh; place-items: center; background: #101827; color: #d9e7ff; font: 16px system-ui, sans-serif; }
+main { width: min(720px, calc(100vw - 32px)); }
diff --git a/apps/ai-game-creator-shell/template-library/v1/phaser-2d-starter/project/game/vite.config.js b/apps/ai-game-creator-shell/template-library/v1/phaser-2d-starter/project/game/vite.config.js
new file mode 100644
index 000000000..d8e631e07
--- /dev/null
+++ b/apps/ai-game-creator-shell/template-library/v1/phaser-2d-starter/project/game/vite.config.js
@@ -0,0 +1,7 @@
+import { defineConfig } from 'vite';
+
+export default defineConfig({
+ root: '.',
+ base: './',
+ build: { outDir: 'dist', emptyOutDir: true },
+});
diff --git a/apps/ai-game-creator-shell/template-library/v1/threejs-3d-starter/cover.svg b/apps/ai-game-creator-shell/template-library/v1/threejs-3d-starter/cover.svg
new file mode 100644
index 000000000..f08503a3f
--- /dev/null
+++ b/apps/ai-game-creator-shell/template-library/v1/threejs-3d-starter/cover.svg
@@ -0,0 +1,13 @@
+
diff --git a/apps/ai-game-creator-shell/template-library/v1/threejs-3d-starter/meta.json b/apps/ai-game-creator-shell/template-library/v1/threejs-3d-starter/meta.json
new file mode 100644
index 000000000..2b492a71d
--- /dev/null
+++ b/apps/ai-game-creator-shell/template-library/v1/threejs-3d-starter/meta.json
@@ -0,0 +1,18 @@
+{
+ "id": "threejs-3d-starter",
+ "title": "Three.js 3D 起步工程",
+ "summary": "网页三维起步工程（Three.js + Vite），自带可旋转立方体场景、方向光与自适应视口。",
+ "tags": [
+ "起步工程",
+ "3d",
+ "three.js",
+ "网页"
+ ],
+ "runtime": "html",
+ "engine": "three.js",
+ "engineVersion": "0.180.0",
+ "templateVersion": "0.1.0",
+ "entry": "game/index.html",
+ "coverWidth": 960,
+ "coverHeight": 540
+}
diff --git a/apps/ai-game-creator-shell/template-library/v1/threejs-3d-starter/project/game/index.html b/apps/ai-game-creator-shell/template-library/v1/threejs-3d-starter/project/game/index.html
new file mode 100644
index 000000000..d01aa860a
--- /dev/null
+++ b/apps/ai-game-creator-shell/template-library/v1/threejs-3d-starter/project/game/index.html
@@ -0,0 +1,10 @@
+
+
+
+
+
+ Genarrative Game Draft
+
+
+
+
diff --git a/apps/ai-game-creator-shell/template-library/v1/threejs-3d-starter/project/game/main.js b/apps/ai-game-creator-shell/template-library/v1/threejs-3d-starter/project/game/main.js
new file mode 100644
index 000000000..211f285ef
--- /dev/null
+++ b/apps/ai-game-creator-shell/template-library/v1/threejs-3d-starter/project/game/main.js
@@ -0,0 +1,43 @@
+import * as THREE from 'three';
+
+const container = document.querySelector('#game');
+const scene = new THREE.Scene();
+scene.background = new THREE.Color(0x0b1120);
+
+const camera = new THREE.PerspectiveCamera(
+ 60,
+ window.innerWidth / window.innerHeight,
+ 0.1,
+ 100,
+);
+camera.position.set(2.4, 1.8, 3.2);
+camera.lookAt(0, 0, 0);
+
+const renderer = new THREE.WebGLRenderer({ antialias: true });
+renderer.setPixelRatio(window.devicePixelRatio);
+renderer.setSize(window.innerWidth, window.innerHeight);
+container.append(renderer.domElement);
+
+const light = new THREE.DirectionalLight(0xffffff, 1.4);
+light.position.set(3, 5, 4);
+scene.add(light, new THREE.AmbientLight(0x8899ff, 0.6));
+
+const cube = new THREE.Mesh(
+ new THREE.BoxGeometry(1, 1, 1),
+ new THREE.MeshStandardMaterial({ color: 0xe0a060 }),
+);
+scene.add(cube);
+
+window.addEventListener('resize', () => {
+ camera.aspect = window.innerWidth / window.innerHeight;
+ camera.updateProjectionMatrix();
+ renderer.setSize(window.innerWidth, window.innerHeight);
+});
+
+function tick() {
+ cube.rotation.y += 0.01;
+ cube.rotation.x += 0.004;
+ renderer.render(scene, camera);
+ requestAnimationFrame(tick);
+}
+tick();
diff --git a/apps/ai-game-creator-shell/template-library/v1/threejs-3d-starter/project/game/package.json b/apps/ai-game-creator-shell/template-library/v1/threejs-3d-starter/project/game/package.json
new file mode 100644
index 000000000..496deca74
--- /dev/null
+++ b/apps/ai-game-creator-shell/template-library/v1/threejs-3d-starter/project/game/package.json
@@ -0,0 +1,15 @@
+{
+ "name": "agc-game",
+ "private": true,
+ "type": "module",
+ "scripts": {
+ "build": "vite build",
+ "dev": "vite"
+ },
+ "dependencies": {
+ "three": "^0.180.0"
+ },
+ "devDependencies": {
+ "vite": "^6.2.0"
+ }
+}
diff --git a/apps/ai-game-creator-shell/template-library/v1/threejs-3d-starter/project/game/style.css b/apps/ai-game-creator-shell/template-library/v1/threejs-3d-starter/project/game/style.css
new file mode 100644
index 000000000..b25e3e5ae
--- /dev/null
+++ b/apps/ai-game-creator-shell/template-library/v1/threejs-3d-starter/project/game/style.css
@@ -0,0 +1,3 @@
+body { margin: 0; overflow: hidden; background: #06080f; }
+main { display: block; width: 100vw; height: 100vh; }
+canvas { display: block; }
diff --git a/apps/ai-game-creator-shell/template-library/v1/threejs-3d-starter/project/game/vite.config.js b/apps/ai-game-creator-shell/template-library/v1/threejs-3d-starter/project/game/vite.config.js
new file mode 100644
index 000000000..d8e631e07
--- /dev/null
+++ b/apps/ai-game-creator-shell/template-library/v1/threejs-3d-starter/project/game/vite.config.js
@@ -0,0 +1,7 @@
+import { defineConfig } from 'vite';
+
+export default defineConfig({
+ root: '.',
+ base: './',
+ build: { outDir: 'dist', emptyOutDir: true },
+});
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 01e5f217d..47e386b36 100644
--- a/apps/ai-game-creator-shell/tests/appSurface/home.suite.ts
+++ b/apps/ai-game-creator-shell/tests/appSurface/home.suite.ts
@@ -182,24 +182,98 @@ export function registerClientHomeTests() {
);
});
- it('shows the built-in inspiration masonry gallery and opens a dismissible preview without requesting the retired feed', async () => {
+ it('shows the home template recommendations and opens the library without creating a project', async () => {
const fetchSpy = vi.spyOn(globalThis, 'fetch');
+ const templateLibrarySnapshot = {
+ schemaVersion: 'game-template-library.v1',
+ library: 'genarrative-official',
+ libraryVersion: 3,
+ updatedAt: '2026-09-17T00:00:00Z',
+ fetchedAtMillis: 1,
+ source: 'remote',
+ templates: [
+ {
+ id: 'lane-defense',
+ title: '星际防线',
+ summary: '塔防原型',
+ tags: ['塔防'],
+ runtime: 'phaser',
+ engine: 'Phaser',
+ engineVersion: '4.2.1',
+ templateVersion: '1.0.0',
+ updatedAt: '2026-09-17T00:00:00Z',
+ entry: 'index.html',
+ zipUrl:
+ 'https://agc-dev.oss-rg-china-mainland.aliyuncs.com/agc/templates/lane-defense.zip',
+ zipSizeBytes: 2048,
+ zipSha256: 'a'.repeat(64),
+ coverUrl:
+ 'https://agc-dev.oss-rg-china-mainland.aliyuncs.com/agc/templates/lane-defense.png',
+ coverWidth: 320,
+ coverHeight: 180,
+ installed: true,
+ installedVersion: '1.0.0',
+ installedAtMillis: 2,
+ },
+ {
+ id: 'cozy-farm',
+ title: '悠然农场',
+ summary: '经营原型',
+ tags: ['经营'],
+ runtime: 'phaser',
+ engine: 'Phaser',
+ engineVersion: '4.2.1',
+ templateVersion: '1.0.0',
+ updatedAt: '2026-09-17T00:00:00Z',
+ entry: 'index.html',
+ zipUrl:
+ 'https://agc-dev.oss-rg-china-mainland.aliyuncs.com/agc/templates/cozy-farm.zip',
+ zipSizeBytes: 4096,
+ zipSha256: 'b'.repeat(64),
+ coverUrl:
+ 'https://agc-dev.oss-rg-china-mainland.aliyuncs.com/agc/templates/cozy-farm.png',
+ coverWidth: 320,
+ coverHeight: 180,
+ installed: false,
+ installedVersion: null,
+ installedAtMillis: null,
+ },
+ ],
+ };
+ const invoke = vi.fn(async (command: string) => {
+ if (command === 'read_game_creator_app_config') {
+ return { config: { selectedModelId: 'quality' } };
+ }
+ if (command === 'fetch_game_template_library') {
+ return templateLibrarySnapshot;
+ }
+ throw new Error(`unexpected invoke ${command}`);
+ });
+ window.__TAURI__ = { core: { invoke } };
renderLauncherAt('/?launcher');
- const inspiration = screen.getByLabelText('灵感推荐');
- const inspirationImages = within(inspiration).getAllByRole('button', {
- name: /查看灵感图片/,
+ // 首页推荐位只展示封面、标题、运行时与已下载徽标，本机灵感图库已随模板库上线删除。
+ const recommendations = await screen.findByLabelText('模板库推荐');
+ const recommendationCards = within(recommendations).getAllByRole('button', {
+ name: /^查看模板 /u,
});
- expect(inspirationImages.length).toBeGreaterThan(0);
- expect(inspiration.closest('.overflow-y-auto')).not.toBeNull();
- expect(screen.queryByText('暂无灵感')).toBeNull();
+ expect(recommendationCards.length).toBe(2);
+ expect(within(recommendationCards[0]!).getByText('已下载')).not.toBeNull();
- fireEvent.click(inspirationImages[0]!);
- const preview = screen.getByRole('dialog', { name: '查看灵感图片' });
- fireEvent.click(screen.getByAltText('放大的灵感图片'));
- expect(screen.getByRole('dialog', { name: '查看灵感图片' })).not.toBeNull();
- fireEvent.click(preview);
- expect(screen.queryByRole('dialog', { name: '查看灵感图片' })).toBeNull();
+ fireEvent.click(recommendationCards[0]!);
+
+ // 点击推荐位只进入模板库页面，不在首页直接下载或创建项目。
+ const librarySummary = await screen.findByText('共 2 个模板 · 已下载 1 个');
+ expect(librarySummary).not.toBeNull();
+ expect(screen.getByRole('button', { name: '返回' })).not.toBeNull();
+ expect(screen.queryByLabelText('模板库推荐')).toBeNull();
+ expect(
+ invoke.mock.calls.some(
+ ([command]) =>
+ command === 'download_game_template' ||
+ command === 'create_automatic_local_game_project_from_template',
+ ),
+ ).toBe(false);
await act(async () => {
await Promise.resolve();
@@ -2450,7 +2524,7 @@ export function registerHomeProjectCreationTests() {
};
}
if (command === 'read_direct_project_history_slice') {
- expect(args).toEqual({ projectPath, limit: 20 });
+ expect(args).toEqual({ projectPath, limit: 20, messagesOnly: true });
return { items: [...persistedMessages], hasMore: false };
}
if (command === 'append_local_conversation_message') {
@@ -2536,7 +2610,7 @@ export function registerHomeProjectCreationTests() {
return manifest;
}
if (command === 'read_direct_project_history_slice') {
- expect(args).toEqual({ projectPath, limit: 20 });
+ expect(args).toEqual({ projectPath, limit: 20, messagesOnly: true });
return { items: [...persistedMessages], hasMore: false };
}
if (command === 'append_local_permission_log') {
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 f751841f6..636ec3d74 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
@@ -5853,6 +5853,20 @@ export function registerProjectWorkbenchFoundationTests() {
expect(styles).toMatch(
/\.game-workbench-chat \.project-supervisor-conversation\s*\{[^}]*position:\s*relative[^}]*display:\s*block[^}]*height:\s*100%[^}]*min-height:\s*0[^}]*overflow:\s*hidden/s,
);
+ // 输入盒里的弹层不能被上面这条（连同 surface、聊天列共三层）裁掉：控制排最左侧是
+ // 「推理档」，它的菜单贴着触发钮右缘向左展开，窄布局（视口 ≤1000px 时面板只有
+ // 280px 宽）下会伸到面板左侧之外，档位文字正好落在被裁掉的那半边，点开只剩一个空
+ // 盒子。所以 direct-codex 这三层的裁切必须放开；菜单位置和尺寸不变，真机几何
+ // （整块可见、位置不动）由浏览器实测确认，这里只钉声明。
+ expect(styles).toMatch(
+ /\.game-workbench-chat:has\(\s*\.project-supervisor-composer\.is-direct-codex\s*\)\s*\{[^}]*overflow:\s*visible/s,
+ );
+ expect(styles).toMatch(
+ /\.game-workbench-chat \.project-supervisor-surface\.is-direct-codex\s*\{[^}]*overflow:\s*visible/s,
+ );
+ expect(styles).toMatch(
+ /\.game-workbench-chat\s+\.project-supervisor-surface\.is-direct-codex\s+\.project-supervisor-conversation\s*\{[^}]*overflow:\s*visible/s,
+ );
expect(styles).toMatch(
/\.game-workbench-chat \.project-supervisor-message-list\s*\{[^}]*height:\s*100%[^}]*min-height:\s*96px[^}]*overflow-y:\s*auto[^}]*padding-bottom:\s*12px[^}]*scroll-padding-bottom:\s*12px/s,
);
@@ -5985,7 +5999,7 @@ export function registerProjectWorkbenchFoundationTests() {
expect(chatWalletSlots).toHaveLength(1);
expect(projectDevelopmentSource).toMatch(/walletEntry=\{walletEntry\}/);
expect(projectDevelopmentSource).toMatch(
- /const showRunUnavailableHint\s*=\s*!runAvailable\s*&&\s*selectedResourceIds\.length === 0\s*&&\s*!uiEditorRoute/s,
+ /const showRunUnavailableHint\s*=\s*!runAvailable\s*&&\s*!uiEditorRoute\s*;/s,
);
expect(projectDevelopmentSource).toMatch(
/aria-describedby=\{\s*showRunUnavailableHint\s*\?\s*'run-unavailable-hint'\s*:\s*undefined\s*\}/s,
@@ -6049,6 +6063,15 @@ export function registerProjectWorkbenchFoundationTests() {
},
};
}
+ if (command === 'read_local_project_text_preview') {
+ return {
+ path: 'assets/ui-design.json',
+ mediaType: 'application/json',
+ byteLen: 2,
+ content: '{}',
+ uiDesignAssetId: 'ui-design-resource',
+ };
+ }
throw new Error(`unexpected invoke ${command}`);
},
);
@@ -9130,6 +9153,7 @@ export function registerProjectSupervisorSurfaceTests() {
expect(invoke).toHaveBeenCalledWith('read_direct_project_history_slice', {
projectPath,
limit: 20,
+ messagesOnly: true,
}),
);
// 默认任务占位行也不能触发专业 Agent 历史的批量读取。
diff --git a/apps/ai-game-creator-shell/tests/appSurface/runtime-settings.suite.ts b/apps/ai-game-creator-shell/tests/appSurface/runtime-settings.suite.ts
index d78f10a0d..78c1da3c1 100644
--- a/apps/ai-game-creator-shell/tests/appSurface/runtime-settings.suite.ts
+++ b/apps/ai-game-creator-shell/tests/appSurface/runtime-settings.suite.ts
@@ -1034,7 +1034,7 @@ export function registerPublishedRuntimeSettingsTests() {
autoCompactTokenLimit: 64000,
toolOutputTokenLimit: 12000,
requestTimeoutMs: 180000,
- maxRetries: 2,
+ maxRetries: 10,
retryBackoffMs: 500,
}),
agentLlm: {},
diff --git a/apps/ai-game-creator-shell/tests/appUpdate.test.ts b/apps/ai-game-creator-shell/tests/appUpdate.test.ts
index 8bbe1e596..bd89c3a3a 100644
--- a/apps/ai-game-creator-shell/tests/appUpdate.test.ts
+++ b/apps/ai-game-creator-shell/tests/appUpdate.test.ts
@@ -1,47 +1,137 @@
-import { afterEach, describe, expect, it } from 'vitest';
+import { check } from '@tauri-apps/plugin-updater';
+import { afterEach, describe, expect, it, vi } from 'vitest';
-import {
- isNewerVersion,
- parseAppUpdateManifest,
- resetAppUpdateCheckForTests,
-} from '../src/services/appUpdate';
+vi.mock('@tauri-apps/plugin-updater', () => ({ check: vi.fn() }));
-afterEach(() => resetAppUpdateCheckForTests());
+const checkMock = vi.mocked(check);
-describe('AGC update manifest', () => {
- it('compares semantic versions and accepts v prefixes', () => {
- expect(isNewerVersion('v0.1.13', '0.1.12')).toBe(true);
- expect(isNewerVersion('0.1.12', '0.1.12')).toBe(false);
- expect(isNewerVersion('0.1.11', '0.1.12')).toBe(false);
+type FakeDownloadEvent =
+ | { event: 'Started'; data: { contentLength?: number } }
+ | { event: 'Progress'; data: { chunkLength: number } }
+ | { event: 'Finished' };
+
+function fakeUpdate() {
+ return {
+ version: '99.0.0',
+ currentVersion: '0.1.47',
+ body: '修复与改进',
+ downloadAndInstall: vi.fn(
+ async (onEvent: (event: FakeDownloadEvent) => void) => {
+ onEvent({ event: 'Started', data: { contentLength: 100 } });
+ onEvent({ event: 'Progress', data: { chunkLength: 40 } });
+ onEvent({ event: 'Progress', data: { chunkLength: 60 } });
+ onEvent({ event: 'Finished' });
+ },
+ ),
+ };
+}
+
+function stubTauriWindow() {
+ const invoke = vi.fn(async () => undefined);
+ vi.stubGlobal('window', { __TAURI__: { core: { invoke } } });
+ return invoke;
+}
+
+afterEach(() => {
+ vi.unstubAllEnvs();
+ vi.unstubAllGlobals();
+ vi.resetModules();
+ checkMock.mockReset();
+});
+
+describe('AGC 客户端更新', () => {
+ it('开发态开关关闭时不请求清单', async () => {
+ vi.stubEnv('VITE_AGC_ENABLE_APP_UPDATE_CHECK', '0');
+ vi.resetModules();
+ const { checkForAppUpdate, resetAppUpdateCheckForTests } = await import(
+ '../src/services/appUpdate'
+ );
+
+ await expect(checkForAppUpdate()).resolves.toBeNull();
+ expect(checkMock).not.toHaveBeenCalled();
+ resetAppUpdateCheckForTests();
});
- it('validates an OSS manifest and rejects non-HTTPS downloads', () => {
- expect(
- parseAppUpdateManifest({
- version: '0.1.13',
- downloadUrl: 'https://oss.example/agc.exe',
- }),
- ).toMatchObject({
- version: '0.1.13',
- downloadUrl: 'https://oss.example/agc.exe',
+ it('开关打开时把插件返回的更新映射给界面，且同一生命周期只查一次', async () => {
+ vi.stubEnv('VITE_AGC_ENABLE_APP_UPDATE_CHECK', '1');
+ vi.resetModules();
+ checkMock.mockResolvedValue(fakeUpdate() as never);
+ const { checkForAppUpdate, resetAppUpdateCheckForTests } = await import(
+ '../src/services/appUpdate'
+ );
+
+ await expect(checkForAppUpdate()).resolves.toEqual({
+ version: '99.0.0',
+ currentVersion: '0.1.47',
+ releaseNotes: '修复与改进',
});
- expect(
- parseAppUpdateManifest({
- version: '0.1.13',
- downloadUrl: 'http://oss.example/agc.exe',
- }),
- ).toBeNull();
+ await checkForAppUpdate();
+ expect(checkMock).toHaveBeenCalledTimes(1);
+ resetAppUpdateCheckForTests();
});
- it('preserves multiline release notes', () => {
- expect(
- parseAppUpdateManifest({
- version: '0.1.13',
- downloadUrl: 'https://oss.example/agc.exe',
- releaseNotes: '第一行\n第二行\r\n第三行',
- }),
- ).toMatchObject({
- releaseNotes: '第一行\n第二行\r\n第三行',
- });
+ it('清单缺失或网络失败时静默按无更新收口', async () => {
+ vi.stubEnv('VITE_AGC_ENABLE_APP_UPDATE_CHECK', '1');
+ vi.resetModules();
+ checkMock.mockRejectedValue(new Error('updater: manifest 404'));
+ const { checkForAppUpdate, resetAppUpdateCheckForTests } = await import(
+ '../src/services/appUpdate'
+ );
+
+ await expect(checkForAppUpdate()).resolves.toBeNull();
+ resetAppUpdateCheckForTests();
+ });
+
+ it('安装时按下载事件上报进度并在完成后重启进程', async () => {
+ vi.stubEnv('VITE_AGC_ENABLE_APP_UPDATE_CHECK', '1');
+ vi.resetModules();
+ const invoke = stubTauriWindow();
+ const update = fakeUpdate();
+ checkMock.mockResolvedValue(update as never);
+ const { checkForAppUpdate, installAppUpdate, resetAppUpdateCheckForTests } =
+ await import('../src/services/appUpdate');
+
+ await checkForAppUpdate();
+ const progress: Array<{ downloadedBytes: number; totalBytes?: number }> =
+ [];
+ await installAppUpdate((value) => progress.push(value));
+
+ expect(update.downloadAndInstall).toHaveBeenCalledTimes(1);
+ expect(progress).toEqual([
+ { downloadedBytes: 0, totalBytes: 100 },
+ { downloadedBytes: 40, totalBytes: 100 },
+ { downloadedBytes: 100, totalBytes: 100 },
+ { downloadedBytes: 100, totalBytes: 100 },
+ ]);
+ expect(invoke).toHaveBeenCalledWith('restart_agc_app');
+ resetAppUpdateCheckForTests();
+ });
+
+ it('没有待安装更新时安装请求失败关闭', async () => {
+ vi.stubEnv('VITE_AGC_ENABLE_APP_UPDATE_CHECK', '1');
+ vi.resetModules();
+ const { installAppUpdate, resetAppUpdateCheckForTests } = await import(
+ '../src/services/appUpdate'
+ );
+
+ await expect(installAppUpdate()).rejects.toThrow('没有可安装的更新');
+ resetAppUpdateCheckForTests();
+ });
+
+ it('下载失败后仍可重试安装', async () => {
+ vi.stubEnv('VITE_AGC_ENABLE_APP_UPDATE_CHECK', '1');
+ vi.resetModules();
+ const update = fakeUpdate();
+ update.downloadAndInstall.mockRejectedValue(new Error('下载更新失败'));
+ checkMock.mockResolvedValue(update as never);
+ const { checkForAppUpdate, installAppUpdate, resetAppUpdateCheckForTests } =
+ await import('../src/services/appUpdate');
+
+ await checkForAppUpdate();
+ await expect(installAppUpdate()).rejects.toThrow('下载更新失败');
+ // 重试仍能拿到待装更新，而不是报“没有可安装的更新”。
+ await expect(installAppUpdate()).rejects.toThrow('下载更新失败');
+ expect(update.downloadAndInstall).toHaveBeenCalledTimes(2);
+ resetAppUpdateCheckForTests();
});
});
diff --git a/apps/ai-game-creator-shell/tests/dev-feature-flags.test.ts b/apps/ai-game-creator-shell/tests/dev-feature-flags.test.ts
new file mode 100644
index 000000000..0f93e5095
--- /dev/null
+++ b/apps/ai-game-creator-shell/tests/dev-feature-flags.test.ts
@@ -0,0 +1,24 @@
+import { describe, expect, test } from 'vitest';
+
+import {
+ agcAppUpdateCheckEnvKey,
+ withAgcDevFeatureFlags,
+} from '../scripts/dev-feature-flags.mjs';
+
+describe('AGC dev 特性开关环境', () => {
+ test('未显式配置时下发关闭检测更新的默认值', () => {
+ expect(withAgcDevFeatureFlags({ KEEP_ME: 'yes' })).toMatchObject({
+ KEEP_ME: 'yes',
+ [agcAppUpdateCheckEnvKey]: '0',
+ });
+ });
+
+ test('保留显式配置的开关取值，忽略空白取值', () => {
+ expect(
+ withAgcDevFeatureFlags({ [agcAppUpdateCheckEnvKey]: '1' }),
+ ).toMatchObject({ [agcAppUpdateCheckEnvKey]: '1' });
+ expect(
+ withAgcDevFeatureFlags({ [agcAppUpdateCheckEnvKey]: ' ' }),
+ ).toMatchObject({ [agcAppUpdateCheckEnvKey]: '0' });
+ });
+});
diff --git a/apps/ai-game-creator-shell/tests/directActiveTurns.test.tsx b/apps/ai-game-creator-shell/tests/directActiveTurns.test.tsx
index 71fc665ef..521cf634a 100644
--- a/apps/ai-game-creator-shell/tests/directActiveTurns.test.tsx
+++ b/apps/ai-game-creator-shell/tests/directActiveTurns.test.tsx
@@ -1,5 +1,4 @@
// @vitest-environment jsdom
-
import {
act,
cleanup,
@@ -7,120 +6,179 @@ import {
render,
renderHook,
screen,
+ waitFor,
} from '@testing-library/react';
-import { afterEach, expect, it, vi } from 'vitest';
+import { afterEach, describe, expect, it, vi } from 'vitest';
-import { useDirectActiveTurns } from '../src/features/agent-runtime/directActiveTurns';
+import type { GameCreatorDirectActiveTurn } from '../src/app/types';
+import {
+ DIRECT_ACTIVE_TURNS_POLL_INTERVAL_MS,
+ useDirectActiveTurns,
+} from '../src/features/agent-runtime/directActiveTurns';
import { ActiveProjectRunsPanel } from '../src/features/app-shell/ActiveProjectRunsPanel';
afterEach(() => cleanup());
-it('读取失败后的重试定时器会在卸载后清理', async () => {
- vi.useFakeTimers();
- const invoke = vi.fn(async () => {
- throw new Error('temporarily unavailable');
- });
- const clearTimeoutSpy = vi.spyOn(window, 'clearTimeout');
+const ACTIVE_TURN = {
+ projectPath: 'C:/projects/demo',
+ agentId: 'project-supervisor',
+ runId: 'run-1',
+} as unknown as GameCreatorDirectActiveTurn;
- try {
- const { unmount } = renderHook(() =>
- useDirectActiveTurns({ invoke, enabled: true }),
+describe('useDirectActiveTurns', () => {
+ it('keeps the snapshot identity when the poll returns the same content', async () => {
+ // 回归点：轮询每次都 setActiveTurns(新数组) 会让所有依赖 activeTurns 的 effect
+ // 反复重跑（窗口标题栏的活动项目面板曾因此无限 setState）。
+ const invoke = vi.fn(async () => [ACTIVE_TURN]) as never;
+ const { result } = renderHook(() =>
+ useDirectActiveTurns({
+ invoke,
+ enabled: true,
+ pollIntervalMs: DIRECT_ACTIVE_TURNS_POLL_INTERVAL_MS,
+ }),
);
- await act(async () => {
- await vi.advanceTimersByTimeAsync(0);
- });
- expect(invoke).toHaveBeenCalledTimes(1);
- unmount();
- expect(clearTimeoutSpy).toHaveBeenCalled();
+ await waitFor(() => {
+ expect(result.current.activeTurns).toHaveLength(1);
+ });
+ const firstSnapshot = result.current.activeTurns;
await act(async () => {
- await vi.advanceTimersByTimeAsync(1_000);
+ await result.current.refreshActiveTurns();
+ await result.current.refreshActiveTurns();
});
- expect(invoke).toHaveBeenCalledTimes(1);
- } finally {
- vi.useRealTimers();
- clearTimeoutSpy.mockRestore();
- }
+ expect(result.current.activeTurns).toBe(firstSnapshot);
+ });
+
+ it('clears to a stable empty snapshot when the hook is disabled', async () => {
+ const invoke = vi.fn(
+ async () => [] as GameCreatorDirectActiveTurn[],
+ ) as never;
+ const { result, rerender } = renderHook(
+ ({ enabled }: { enabled: boolean }) =>
+ useDirectActiveTurns({ invoke, enabled, pollIntervalMs: 60_000 }),
+ { initialProps: { enabled: true } },
+ );
+
+ await waitFor(() => {
+ expect(result.current.activeTurns).toEqual([]);
+ });
+ const emptySnapshot = result.current.activeTurns;
+ rerender({ enabled: false });
+ expect(result.current.activeTurns).toBe(emptySnapshot);
+ });
+
+ it('读取失败后的重试定时器会在卸载后清理', async () => {
+ vi.useFakeTimers();
+ const invoke = vi.fn(async () => {
+ throw new Error('temporarily unavailable');
+ });
+ const clearTimeoutSpy = vi.spyOn(window, 'clearTimeout');
+
+ try {
+ const { unmount } = renderHook(() =>
+ useDirectActiveTurns({ invoke, enabled: true }),
+ );
+ await act(async () => {
+ await vi.advanceTimersByTimeAsync(0);
+ });
+ expect(invoke).toHaveBeenCalledTimes(1);
+
+ unmount();
+ expect(clearTimeoutSpy).toHaveBeenCalled();
+
+ await act(async () => {
+ await vi.advanceTimersByTimeAsync(1_000);
+ });
+ expect(invoke).toHaveBeenCalledTimes(1);
+ } finally {
+ vi.useRealTimers();
+ clearTimeoutSpy.mockRestore();
+ }
+ });
});
-it('按开始时间展示正在运行的项目并支持进入项目', () => {
- const onOpenProject = vi.fn();
- render(
- ,
- );
+describe('ActiveProjectRunsPanel', () => {
+ it('按开始时间展示正在运行的项目并支持进入项目', () => {
+ const onOpenProject = vi.fn();
+ render(
+ ,
+ );
- const items = screen.getAllByRole('button');
- expect(items.map((item) => item.textContent?.includes('先开始'))).toEqual([
- true,
- false,
- ]);
- fireEvent.click(items[0]);
- expect(onOpenProject).toHaveBeenCalledWith('C:/projects/first');
-});
-
-it('读取失败时保留明确的读取提示，不伪装成没有运行项目', () => {
- render();
-
- expect(screen.getByRole('status').textContent).toBe('未能读取正在运行的项目');
-});
-
-it('标题栏入口只显示最后开始的项目，展开后列出全部项目', () => {
- const onOpenProject = vi.fn();
- render(
- ,
- );
-
- expect(screen.getByRole('button', { name: /后开始/ })).toBeTruthy();
- expect(screen.queryByRole('menu')).toBeNull();
- fireEvent.click(screen.getByRole('button', { name: /后开始/ }));
- expect(screen.getByRole('menu')).toBeTruthy();
- expect(screen.getAllByRole('menuitem')).toHaveLength(2);
- fireEvent.click(screen.getByRole('menuitem', { name: /先开始/ }));
- expect(onOpenProject).toHaveBeenCalledWith('C:/projects/first');
+ const items = screen.getAllByRole('button');
+ expect(items.map((item) => item.textContent?.includes('先开始'))).toEqual([
+ true,
+ false,
+ ]);
+ fireEvent.click(items[0]);
+ expect(onOpenProject).toHaveBeenCalledWith('C:/projects/first');
+ });
+
+ it('读取失败时保留明确的读取提示，不伪装成没有运行项目', () => {
+ render();
+
+ expect(screen.getByRole('status').textContent).toBe(
+ '未能读取正在运行的项目',
+ );
+ });
+
+ it('标题栏入口只显示最后开始的项目，展开后列出全部项目', () => {
+ const onOpenProject = vi.fn();
+ render(
+ ,
+ );
+
+ expect(screen.getByRole('button', { name: /后开始/ })).toBeTruthy();
+ expect(screen.queryByRole('menu')).toBeNull();
+ fireEvent.click(screen.getByRole('button', { name: /后开始/ }));
+ expect(screen.getByRole('menu')).toBeTruthy();
+ expect(screen.getAllByRole('menuitem')).toHaveLength(2);
+ fireEvent.click(screen.getByRole('menuitem', { name: /先开始/ }));
+ expect(onOpenProject).toHaveBeenCalledWith('C:/projects/first');
+ });
});
diff --git a/apps/ai-game-creator-shell/tests/directHistoryPagination.test.tsx b/apps/ai-game-creator-shell/tests/directHistoryPagination.test.tsx
new file mode 100644
index 000000000..8c0f00a19
--- /dev/null
+++ b/apps/ai-game-creator-shell/tests/directHistoryPagination.test.tsx
@@ -0,0 +1,269 @@
+/** @vitest-environment jsdom */
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import type { DirectThreadHistorySlice } from '../src/features/project-workspace/directThreadEvents';
+import {
+ act,
+ App,
+ createGameCreationAppManifest,
+ fireEvent,
+ React,
+ render,
+ screen,
+ setComposerText,
+} from './appSurface/harness';
+
+const projectPath = '/tmp/direct-message-pages';
+const manifest = createGameCreationAppManifest(
+ 'direct-message-pages',
+ '历史分页',
+);
+const messages = Array.from({ length: 26 }, (_, index) => ({
+ id: `direct-codex:turn-${Math.floor(index / 2)}:${index % 2 ? 'assistant' : 'user'}`,
+ type: 'message',
+ role: index % 2 ? 'assistant' : 'user',
+ content: [
+ {
+ type: index % 2 ? 'output_text' : 'input_text',
+ text: `历史正文 ${index}`,
+ },
+ ],
+}));
+function page(
+ items: typeof messages,
+ hasMore: boolean,
+): DirectThreadHistorySlice {
+ return { items, hasMore, oldestItemId: items[0]?.id ?? null };
+}
+function deferred() {
+ let resolve!: (value: DirectThreadHistorySlice) => void;
+ let reject!: (error: Error) => void;
+ const promise = new Promise((yes, no) => {
+ resolve = yes;
+ reject = no;
+ });
+ return { promise, resolve, reject };
+}
+function install(
+ read: (
+ args: Record,
+ ) => DirectThreadHistorySlice | Promise,
+) {
+ const invoke = vi.fn(
+ async (command: string, args?: Record) => {
+ if (command === 'read_direct_project_history_slice') {
+ expect(args?.messagesOnly).toBe(true);
+ return read(args!);
+ }
+ if (command === 'read_project_permission_policy')
+ return {
+ path: '.agent/policy.json',
+ policy: { deniedCommands: [], confirmCommands: [] },
+ };
+ if (command === 'get_local_game_manifest') return manifest;
+ if (command === 'read_game_creator_app_config')
+ return {
+ config: {
+ selectedModelId: 'quality',
+ selectedModelIsDefault: true,
+ llm: { customEnabled: false },
+ },
+ };
+ if (
+ command === 'read_direct_tool_calls' ||
+ command === 'read_direct_turn_stream' ||
+ command === 'list_game_creator_direct_active_turns'
+ )
+ return [];
+ return null;
+ },
+ );
+ window.__TAURI__ = { core: { invoke } } as unknown as typeof window.__TAURI__;
+ return invoke;
+}
+function mount(path = projectPath) {
+ return render(
+ ,
+ );
+}
+const earlier = () => screen.getByRole('button', { name: /显示更早/ });
+afterEach(() => {
+ delete window.__TAURI__;
+});
+
+describe('Direct 聊天历史分页集成', () => {
+ it('加载旧页后重读历史回到最新页，再翻页仍按原顺序且不重复', async () => {
+ const invoke = install((args) =>
+ args.beforeItemId
+ ? page(messages.slice(0, 6), false)
+ : page(messages.slice(6), true),
+ );
+ mount();
+ await screen.findByText('历史正文 25');
+ fireEvent.click(earlier());
+ await screen.findByText('历史正文 0');
+ await setComposerText(screen.getByLabelText('陶泥儿对话内容'), '/history');
+ fireEvent.click(screen.getByRole('button', { name: '发送' }));
+ await act(async () => {
+ await Promise.resolve();
+ });
+ expect(screen.queryByText('历史正文 0')).toBeNull();
+ expect(screen.getByText('历史正文 25')).not.toBeNull();
+ fireEvent.click(earlier());
+ await screen.findByText('历史正文 0');
+ for (let index = 0; index < messages.length; index += 1) {
+ expect(screen.getAllByText(`历史正文 ${index}`)).toHaveLength(1);
+ if (index > 0) {
+ expect(
+ screen
+ .getByText(`历史正文 ${index - 1}`)
+ .compareDocumentPosition(screen.getByText(`历史正文 ${index}`)) &
+ Node.DOCUMENT_POSITION_FOLLOWING,
+ ).not.toBe(0);
+ }
+ }
+ expect(
+ invoke.mock.calls.filter(
+ ([command]) => command === 'read_direct_project_history_slice',
+ ),
+ ).toHaveLength(4);
+ });
+
+ it('首屏按消息加载20条，更早消息使用原生游标，原始工具记录不占页', async () => {
+ const invoke = install((args) =>
+ args.beforeItemId
+ ? page(messages.slice(0, 6), false)
+ : page(messages.slice(6), true),
+ );
+ mount();
+ await screen.findByText('历史正文 25');
+ expect(screen.queryByText('历史正文 0')).toBeNull();
+ fireEvent.click(earlier());
+ await screen.findByText('历史正文 0');
+ expect(screen.queryByRole('button', { name: /显示更早/ })).toBeNull();
+ expect(invoke).toHaveBeenCalledWith('read_direct_project_history_slice', {
+ projectPath,
+ beforeItemId: messages[6]!.id,
+ limit: 20,
+ messagesOnly: true,
+ });
+ });
+
+ it('重复点击单飞，失败保留游标可重试，重叠消息不重复', async () => {
+ const pending = deferred();
+ let attempts = 0;
+ const invoke = install((args) => {
+ if (!args.beforeItemId) return page(messages.slice(6), true);
+ attempts += 1;
+ return attempts === 1
+ ? pending.promise
+ : page(messages.slice(0, 8), false);
+ });
+ mount();
+ await screen.findByText('历史正文 25');
+ fireEvent.click(earlier());
+ fireEvent.click(earlier());
+ expect(attempts).toBe(1);
+ await act(async () => pending.reject(new Error('模拟读取失败')));
+ expect(screen.getByText('历史正文 25')).not.toBeNull();
+ fireEvent.click(earlier());
+ await screen.findByText('历史正文 0');
+ expect(screen.getAllByText('历史正文 6')).toHaveLength(1);
+ expect(screen.getAllByText('历史正文 7')).toHaveLength(1);
+ const loads = invoke.mock.calls.filter(
+ ([command, args]) =>
+ command === 'read_direct_project_history_slice' && args?.beforeItemId,
+ );
+ expect(loads.map(([, args]) => args?.beforeItemId)).toEqual([
+ messages[6]!.id,
+ messages[6]!.id,
+ ]);
+ });
+
+ it('同项目重新加载使旧翻页失效，旧 finally 不解除新请求的单飞', async () => {
+ const old = deferred();
+ const fresh = deferred();
+ let fullLoads = 0;
+ let olderLoads = 0;
+ const recent = messages.slice(6).map((item) => ({
+ ...item,
+ content: [{ type: 'output_text', text: `重读 ${item.content[0]!.text}` }],
+ }));
+ install((args) => {
+ if (!args.beforeItemId) {
+ fullLoads += 1;
+ return page(fullLoads === 1 ? messages.slice(6) : recent, true);
+ }
+ olderLoads += 1;
+ return olderLoads === 1 ? old.promise : fresh.promise;
+ });
+ mount();
+ await screen.findByText('历史正文 25');
+ fireEvent.click(earlier());
+ await setComposerText(screen.getByLabelText('陶泥儿对话内容'), '/history');
+ fireEvent.click(screen.getByRole('button', { name: '发送' }));
+ await screen.findByText('重读 历史正文 25');
+ fireEvent.click(earlier());
+ await act(async () =>
+ old.resolve(
+ page(
+ [
+ {
+ ...messages[0]!,
+ id: 'stale',
+ content: [{ type: 'input_text', text: '过期消息' }],
+ },
+ ],
+ false,
+ ),
+ ),
+ );
+ expect(screen.queryByText('过期消息')).toBeNull();
+ fireEvent.click(earlier());
+ expect(olderLoads).toBe(2);
+ await act(async () => fresh.resolve(page(messages.slice(0, 6), false)));
+ await screen.findByText('历史正文 0');
+ });
+
+ it('离开项目并重进后，旧请求不能污染新实例', async () => {
+ const old = deferred();
+ const invoke = install((args) =>
+ args.beforeItemId ? old.promise : page(messages.slice(6), true),
+ );
+ const first = mount();
+ await screen.findByText('历史正文 25');
+ fireEvent.click(earlier());
+ first.unmount();
+ const other = mount('/tmp/another-project');
+ await screen.findByText('历史正文 25');
+ other.unmount();
+ mount();
+ await screen.findByText('历史正文 25');
+ await act(async () =>
+ old.resolve(
+ page(
+ [
+ {
+ ...messages[0]!,
+ id: 'stale',
+ content: [{ type: 'input_text', text: '旧项目迟到消息' }],
+ },
+ ],
+ false,
+ ),
+ ),
+ );
+ expect(screen.queryByText('旧项目迟到消息')).toBeNull();
+ expect(earlier()).not.toBeNull();
+ expect(
+ invoke.mock.calls.filter(
+ ([command]) => command === 'read_direct_project_history_slice',
+ ),
+ ).toHaveLength(4);
+ });
+});
diff --git a/apps/ai-game-creator-shell/tests/directThreadEvents.test.ts b/apps/ai-game-creator-shell/tests/directThreadEvents.test.ts
index 128cdf135..ff7849dfc 100644
--- a/apps/ai-game-creator-shell/tests/directThreadEvents.test.ts
+++ b/apps/ai-game-creator-shell/tests/directThreadEvents.test.ts
@@ -2,10 +2,59 @@ import { describe, expect, it } from 'vitest';
import {
directThreadHistoryItemsToMessages,
+ directThreadHistoryPage,
isDirectTurnInProgress,
+ prependDirectHistoryMessages,
} from '../src/features/project-workspace/directThreadEvents';
describe('Direct 回合状态与历史时间', () => {
+ it('游标来自原始切片，不从没有聊天消息的工具页倒推', () => {
+ const page = directThreadHistoryPage(
+ {
+ items: [{ id: 'tool-older', type: 'function_call_output' }],
+ hasMore: true,
+ oldestItemId: 'tool-older',
+ },
+ 'message-newer',
+ );
+ expect(page.messages).toEqual([]);
+ expect(page.cursor).toBe('tool-older');
+ });
+ it('空历史结束，无 ID 或不前进的非终页明确失败而不循环', () => {
+ expect(directThreadHistoryPage({ items: [], hasMore: false })).toEqual({
+ messages: [],
+ cursor: null,
+ hasMore: false,
+ });
+ expect(() => directThreadHistoryPage({ items: [], hasMore: true })).toThrow(
+ '游标未前进',
+ );
+ expect(() =>
+ directThreadHistoryPage(
+ {
+ items: [{ id: 'same' }],
+ hasMore: true,
+ oldestItemId: 'same',
+ },
+ 'same',
+ ),
+ ).toThrow('游标未前进');
+ });
+ it('重叠页按原始 ID 去重，保留当前正文，旧无 ID 消息不删除', () => {
+ const current = [
+ { role: 'assistant' as const, text: '完整正文', messageId: 'a' },
+ ];
+ const old = { role: 'user' as const, text: '用户输入', messageId: 'u' };
+ expect(
+ prependDirectHistoryMessages(current, [
+ old,
+ old,
+ { role: 'assistant', text: '旧快照', messageId: 'a' },
+ { role: 'assistant', text: '无身份旧消息' },
+ ]),
+ ).toEqual([old, { role: 'assistant', text: '无身份旧消息' }, ...current]);
+ });
+
it('终态和空状态不恢复为活动回合', () => {
for (const status of [
'completed',
diff --git a/apps/ai-game-creator-shell/tests/featureFlags.test.ts b/apps/ai-game-creator-shell/tests/featureFlags.test.ts
new file mode 100644
index 000000000..1ee1092b4
--- /dev/null
+++ b/apps/ai-game-creator-shell/tests/featureFlags.test.ts
@@ -0,0 +1,23 @@
+import { describe, expect, it } from 'vitest';
+
+import { resolveAppUpdateCheckEnabled } from '../src/app/featureFlags';
+
+describe('AGC 客户端特性开关', () => {
+ it('开发态（agc 启动）默认关闭检测更新', () => {
+ expect(resolveAppUpdateCheckEnabled('', true)).toBe(false);
+ });
+
+ it('正式包默认开启检测更新', () => {
+ expect(resolveAppUpdateCheckEnabled('', false)).toBe(true);
+ });
+
+ it('显式配置的开关优先于环境默认值', () => {
+ expect(resolveAppUpdateCheckEnabled('1', true)).toBe(true);
+ expect(resolveAppUpdateCheckEnabled('0', false)).toBe(false);
+ });
+
+ it('忽略无法识别的开关取值并回落到环境默认值', () => {
+ expect(resolveAppUpdateCheckEnabled('2', true)).toBe(false);
+ expect(resolveAppUpdateCheckEnabled(' ', false)).toBe(true);
+ });
+});
diff --git a/apps/ai-game-creator-shell/tests/resourceCanvasFloatingDismiss.test.tsx b/apps/ai-game-creator-shell/tests/resourceCanvasFloatingDismiss.test.tsx
index f3a58a319..22018450b 100644
--- a/apps/ai-game-creator-shell/tests/resourceCanvasFloatingDismiss.test.tsx
+++ b/apps/ai-game-creator-shell/tests/resourceCanvasFloatingDismiss.test.tsx
@@ -14,6 +14,7 @@ import {
canDismissResourceCanvasQuickEdit,
isResourceCanvasHostOverlayOpen,
isResourceCanvasInteractionTarget,
+ isResourceCanvasPanTarget,
isResourceCanvasWheelOverlayTarget,
resolveResourceCanvasFloatingPanelDismissOpen,
resolveResourceCanvasFloatingPanelOpen,
@@ -41,6 +42,38 @@ const RESOURCE_FOCUS_SOURCE_LAYER: CanvasLayer = {
};
describe('resourceCanvasFocusModel', () => {
+ test('右键抓手允许卡面和选中按钮，不抢媒体控件、编辑器及浮层', () => {
+ document.body.innerHTML = `
+
+
+
+
+
+
+
+ 筛选
+ 操作
+
+ `;
+ for (const id of ['blank', 'card', 'select']) {
+ expect(isResourceCanvasPanTarget(document.getElementById(id))).toBe(true);
+ }
+ for (const id of [
+ 'play',
+ 'video',
+ 'input',
+ 'editor',
+ 'filter',
+ 'toolbar',
+ 'title',
+ ]) {
+ expect(isResourceCanvasPanTarget(document.getElementById(id))).toBe(
+ false,
+ );
+ }
+ expect(isResourceCanvasPanTarget(null)).toBe(false);
+ });
+
test('点在资源卡、交互控件与画布浮层里时不清画布焦点', () => {
document.body.innerHTML = `
diff --git a/apps/ai-game-creator-shell/tests/resourceCanvasManualLayout.test.tsx b/apps/ai-game-creator-shell/tests/resourceCanvasManualLayout.test.tsx
index 49b9c3dfa..e1de7b91e 100644
--- a/apps/ai-game-creator-shell/tests/resourceCanvasManualLayout.test.tsx
+++ b/apps/ai-game-creator-shell/tests/resourceCanvasManualLayout.test.tsx
@@ -340,6 +340,323 @@ afterEach(() => {
vi.restoreAllMocks();
});
+async function mountPointerWorkbench(
+ target: 'main' | 'character' | 'all' = 'character',
+) {
+ const projectId = 'pointer-workbench';
+ const projectPath = '/tmp/pointer-workbench';
+ const tauri = installLayoutTauri({
+ projectIdsByPath: { [projectPath]: projectId },
+ });
+ render(
+
,
+ );
+ await settleFocusChain();
+ const manager = document.querySelector
(
+ '.game-resource-book-manager',
+ )!;
+ vi.spyOn(manager, 'getBoundingClientRect').mockReturnValue({
+ x: 0,
+ y: 0,
+ left: 0,
+ top: 0,
+ right: 800,
+ bottom: 600,
+ width: 800,
+ height: 600,
+ toJSON: () => ({}),
+ } as DOMRect);
+ act(() => window.dispatchEvent(new Event('resize')));
+ if (target !== 'main') {
+ fireEvent.click(
+ screen.getByRole('button', {
+ name: target === 'all' ? '打开所有资源' : '打开角色与对象',
+ }),
+ );
+ }
+ await settleFocusChain();
+ const surface = manager.querySelector(
+ target === 'main'
+ ? '.game-resource-book-main'
+ : '.game-resource-book-scene',
+ )!;
+ const capture = new Set();
+ Object.defineProperties(surface, {
+ setPointerCapture: {
+ configurable: true,
+ value: vi.fn((id: number) => capture.add(id)),
+ },
+ hasPointerCapture: {
+ configurable: true,
+ value: (id: number) => capture.has(id),
+ },
+ releasePointerCapture: {
+ configurable: true,
+ value: vi.fn((id: number) => capture.delete(id)),
+ },
+ });
+ const world = manager.querySelector(
+ '.game-resource-book-scene-world',
+ )!;
+ const viewport = () =>
+ Array.from(world.style.transform.matchAll(/-?\d+(?:\.\d+)?/g), (m) =>
+ Number(m[0]),
+ );
+ return { manager, surface, world, viewport, tauri };
+}
+
+describe('资源画布指针与运行提示', () => {
+ it('资源卡左键拖动仍提交手动坐标，不平移视口', async () => {
+ const { manager, viewport, tauri } = await mountPointerWorkbench();
+ const card = manager.querySelector(
+ '.is-expanded .game-resource-card[data-resource-card-id="asset:pointer-a"]',
+ )!;
+ const before = viewport();
+ const writes = tauri.layoutWrites.length;
+ fireEvent.pointerDown(card, {
+ pointerId: 30,
+ button: 0,
+ clientX: 100,
+ clientY: 100,
+ });
+ fireEvent.pointerMove(card, {
+ pointerId: 30,
+ buttons: 1,
+ clientX: 180,
+ clientY: 140,
+ });
+ fireEvent.pointerUp(card, {
+ pointerId: 30,
+ button: 0,
+ clientX: 180,
+ clientY: 140,
+ });
+ await waitFor(() =>
+ expect(tauri.layoutWrites.length).toBeGreaterThan(writes),
+ );
+ expect(tauri.layoutWrites.at(-1)?.positions).toEqual(
+ expect.arrayContaining([
+ expect.objectContaining({
+ resourceId: 'asset:pointer-a',
+ manuallyPlaced: true,
+ }),
+ ]),
+ );
+ expect(viewport()).toEqual(before);
+ expect(
+ document.querySelector('.genarrative-image-canvas__selection-overlay'),
+ ).toBeNull();
+ });
+
+ it('资源选中不移除运行不可用提示或改变运行能力', async () => {
+ const { manager } = await mountPointerWorkbench();
+ const hint = '首个可运行原型尚未完成，运行视图暂不可用';
+ expect(screen.getByText(hint)).not.toBeNull();
+ fireEvent.click(
+ manager.querySelector(
+ '.is-expanded [data-resource-id="asset:pointer-a"]',
+ )!,
+ );
+ expect(screen.getByText(hint)).not.toBeNull();
+ const run = screen.getByRole('tab', { name: '运行' });
+ expect(run.getAttribute('data-unavailable')).toBe('true');
+ expect(run.getAttribute('aria-describedby')).toBe('run-unavailable-hint');
+ fireEvent.click(run);
+ expect(run.getAttribute('aria-selected')).toBe('false');
+ });
+
+ it.each(['main', 'character', 'all'] as const)(
+ '%s 的空白处支持右键平移且不写资源布局',
+ async (target) => {
+ const { surface, viewport, tauri } = await mountPointerWorkbench(target);
+ const before = viewport();
+ const writes = tauri.layoutWrites.length;
+ fireEvent.pointerDown(surface, {
+ pointerId: 31,
+ button: 2,
+ clientX: 100,
+ clientY: 100,
+ });
+ fireEvent.pointerMove(surface, {
+ pointerId: 31,
+ buttons: 2,
+ clientX: 170,
+ clientY: 140,
+ });
+ expect(viewport()).toEqual([before[0]! + 70, before[1]! + 40, before[2]]);
+ expect(fireEvent.contextMenu(surface, { button: 2 })).toBe(false);
+ fireEvent.pointerUp(surface, {
+ pointerId: 31,
+ button: 2,
+ clientX: 170,
+ clientY: 140,
+ });
+ expect(
+ document.querySelector('.genarrative-image-canvas__selection-overlay'),
+ ).toBeNull();
+ expect(tauri.layoutWrites).toHaveLength(writes);
+ },
+ );
+
+ it('资源卡右键平移保留选中，左键空白拖动仍框选', async () => {
+ const { manager, surface, viewport, tauri } = await mountPointerWorkbench();
+ const card = manager.querySelector(
+ '.is-expanded [data-resource-id="asset:pointer-a"]',
+ )!;
+ fireEvent.click(card);
+ const before = viewport();
+ const writes = tauri.layoutWrites.length;
+ fireEvent.pointerDown(card, {
+ pointerId: 32,
+ button: 2,
+ clientX: 100,
+ clientY: 100,
+ });
+ fireEvent.pointerMove(surface, {
+ pointerId: 32,
+ buttons: 2,
+ clientX: 150,
+ clientY: 160,
+ });
+ fireEvent.pointerUp(surface, {
+ pointerId: 32,
+ button: 2,
+ clientX: 150,
+ clientY: 160,
+ });
+ expect(viewport()).toEqual([before[0]! + 50, before[1]! + 60, before[2]]);
+ expect(card.getAttribute('aria-pressed')).toBe('true');
+ expect(tauri.layoutWrites).toHaveLength(writes);
+ const panned = viewport();
+ fireEvent.pointerDown(surface, {
+ pointerId: 33,
+ button: 0,
+ clientX: 10,
+ clientY: 10,
+ });
+ fireEvent.pointerMove(surface, {
+ pointerId: 33,
+ buttons: 1,
+ clientX: 780,
+ clientY: 580,
+ });
+ expect(
+ document.querySelector('.genarrative-image-canvas__selection-overlay'),
+ ).not.toBeNull();
+ expect(selectedResourceIdsInDom()).toContain('asset:pointer-a');
+ expect(viewport()).toEqual(panned);
+ fireEvent.pointerUp(surface, { pointerId: 33, button: 0 });
+ expect(
+ document.querySelector('.genarrative-image-canvas__selection-overlay'),
+ ).toBeNull();
+ });
+
+ it.each(['cancel', 'capture', 'blur'] as const)(
+ '%s 后右键平移不会继续跟随指针',
+ async (reason) => {
+ const { surface, viewport } = await mountPointerWorkbench();
+ const before = viewport();
+ fireEvent.pointerDown(surface, {
+ pointerId: 34,
+ button: 2,
+ clientX: 100,
+ clientY: 100,
+ });
+ fireEvent.pointerMove(surface, {
+ pointerId: 34,
+ buttons: 2,
+ clientX: 110,
+ clientY: 120,
+ });
+ const moved = viewport();
+ expect(moved).toEqual([before[0]! + 10, before[1]! + 20, before[2]]);
+ if (reason === 'cancel')
+ fireEvent.pointerCancel(surface, { pointerId: 34 });
+ else if (reason === 'capture')
+ fireEvent.lostPointerCapture(surface, { pointerId: 34 });
+ else act(() => window.dispatchEvent(new Event('blur')));
+ fireEvent.pointerMove(surface, {
+ pointerId: 34,
+ clientX: 300,
+ clientY: 300,
+ });
+ expect(viewport()).toEqual(moved);
+ },
+ );
+
+ it('总览失焦终止右键平移，子画布切换释放实际捕获节点', async () => {
+ const { surface, viewport } = await mountPointerWorkbench('main');
+ const before = viewport();
+ fireEvent.pointerDown(surface, {
+ pointerId: 36,
+ button: 2,
+ clientX: 10,
+ clientY: 10,
+ });
+ fireEvent.pointerMove(surface, {
+ pointerId: 36,
+ buttons: 2,
+ clientX: 40,
+ clientY: 40,
+ });
+ const moved = viewport();
+ expect(moved).toEqual([before[0]! + 30, before[1]! + 30, before[2]]);
+ act(() => window.dispatchEvent(new Event('blur')));
+ expect(surface.releasePointerCapture).toHaveBeenCalledWith(36);
+ fireEvent.pointerMove(surface, {
+ pointerId: 36,
+ clientX: 100,
+ clientY: 100,
+ });
+ expect(viewport()).toEqual(moved);
+ fireEvent.pointerDown(surface, {
+ pointerId: 37,
+ button: 2,
+ clientX: 10,
+ clientY: 10,
+ });
+ fireEvent.click(screen.getByRole('button', { name: '打开角色与对象' }));
+ expect(surface.releasePointerCapture).toHaveBeenCalledWith(37);
+ });
+
+ it('控件右键不被画布接管，初次打开不整理也能连续双指平移', async () => {
+ const { manager, surface, viewport } = await mountPointerWorkbench();
+ const zoom = screen.getByRole('button', { name: '放大画布' });
+ const before = viewport();
+ fireEvent.pointerDown(zoom, {
+ pointerId: 35,
+ button: 2,
+ clientX: 100,
+ clientY: 100,
+ });
+ fireEvent.pointerMove(surface, {
+ pointerId: 35,
+ buttons: 2,
+ clientX: 200,
+ clientY: 200,
+ });
+ expect(viewport()).toEqual(before);
+ expect(fireEvent.contextMenu(zoom, { button: 2 })).toBe(true);
+ await act(async () => {
+ for (let i = 0; i < 100; i++) {
+ fireEvent.wheel(manager, { deltaX: 3, deltaY: 6 });
+ }
+ });
+ expect(viewport()).toEqual([before[0]! - 300, before[1]! - 600, before[2]]);
+ });
+});
+
describe('资源画布手动重排口径', () => {
it('hook：rederiveNow 按 rederive 策略重算自动坐标并写回一次', async () => {
const projectId = 'manual-rederive-project';
diff --git a/apps/ai-game-creator-shell/tests/resourceCardPreviewRealManifest.test.ts b/apps/ai-game-creator-shell/tests/resourceCardPreviewRealManifest.test.ts
index bd46086ea..127bcc9db 100644
--- a/apps/ai-game-creator-shell/tests/resourceCardPreviewRealManifest.test.ts
+++ b/apps/ai-game-creator-shell/tests/resourceCardPreviewRealManifest.test.ts
@@ -206,7 +206,7 @@ describe('真机 manifest 取证：占位卡片计数与栏目分布', () => {
// `artKind`（其中含 `ui`）而被判成 art，于是角标显示「图片」，而预览调度按 art 走
// 图像分支、又因 mediaType 不是图像而兜底成 placeholder —— 卡片永不发起读取，
// 表现为「标着图片却只有占位图标」。类型判定改为 mediaType/扩展名优先、kind 只做
- // 兜底后，它们正确落文档分支，卡面渲染 JSON 文本摘要。
+ // 兜底后，它们进入文本读取通道；卡面再消费原生识别结果显示 UI 设计或 JSON。
expect(byPreviewKind).toEqual({
'raster-image': 52,
document: 8,
diff --git a/apps/ai-game-creator-shell/tests/resourceDocumentPreviewModel.test.ts b/apps/ai-game-creator-shell/tests/resourceDocumentPreviewModel.test.ts
index c89d79e99..00a6bd53e 100644
--- a/apps/ai-game-creator-shell/tests/resourceDocumentPreviewModel.test.ts
+++ b/apps/ai-game-creator-shell/tests/resourceDocumentPreviewModel.test.ts
@@ -40,19 +40,21 @@ describe('resourceDocumentPreviewMarkdown', () => {
['game/main.ts', 'typescript'],
['game/main.js', 'javascript'],
['game/main.py', 'python'],
+ ['assets/data.json', 'json'],
+ ['assets/DESIGN.JSON', 'json'],
])('%s 包为 %s 代码块', (path, language) => {
expect(
resourceDocumentPreviewMarkdown(resource(path), ' source\n\n\n'),
).toBe(`\`\`\`${language}\n source\n\n\n\`\`\``);
});
- it('JSON 规格按文档原文预览，不包成代码块', () => {
+ it('JSON 规格按原文代码块预览，不把字段值当 Markdown', () => {
expect(
resourceDocumentPreviewMarkdown(
resource('assets/data.json'),
- ' source\n\n\n',
+ '{ "text": "# 不应成为标题" }\n',
),
- ).toBe(' source\n\n\n');
+ ).toBe('```json\n{ "text": "# 不应成为标题" }\n```');
});
it('正文包含 Markdown 围栏时不会逃出代码块', () => {
diff --git a/apps/ai-game-creator-shell/tests/resourceJsonCanvas.test.tsx b/apps/ai-game-creator-shell/tests/resourceJsonCanvas.test.tsx
new file mode 100644
index 000000000..7e04d094e
--- /dev/null
+++ b/apps/ai-game-creator-shell/tests/resourceJsonCanvas.test.tsx
@@ -0,0 +1,205 @@
+/** @vitest-environment jsdom */
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import {
+ createGameCreationAppManifest,
+ fireEvent,
+ installResizeObserverStub,
+ ProjectDevelopmentView,
+ React,
+ render,
+ screen,
+ waitFor,
+ within,
+} from './appSurface/harness';
+
+vi.mock('@tauri-apps/api/core', async () => ({
+ ...(await vi.importActual(
+ '@tauri-apps/api/core',
+ )),
+ invoke: (command: string, args?: Record) =>
+ window.__TAURI__!.core.invoke(command, args),
+}));
+
+const projectId = 'json-canvas';
+const projectPath = '/tmp/json-canvas';
+const emptyState = {
+ ui_trees: [],
+ ui_design_images: {},
+ sprite_assets: {},
+ font_assets: {},
+};
+
+async function mountJsonCanvas(kind = 'ui', rejectPreview = false) {
+ installResizeObserverStub();
+ const manifest = createGameCreationAppManifest(projectId, 'JSON 资源测试');
+ manifest.assets = [
+ { id: 'design', kind, localPath: 'ui/design.json' },
+ { id: 'ordinary', kind: 'UI', localPath: 'assets/ordinary.json' },
+ { id: 'spoof', kind: 'UI', localPath: 'ui/spoof.json' },
+ ].map((asset) => ({
+ ...asset,
+ mediaType: 'application/json',
+ category: 'document' as const,
+ source: { kind: 'generated' as const },
+ }));
+ const invoke = vi.fn(
+ async (command: string, args?: Record) => {
+ if (command === 'read_local_project_resource_graph') {
+ const ids = (args?.resources as Array<{ resourceId: string }>).map(
+ (item) => item.resourceId,
+ );
+ return {
+ resourceIds: ids,
+ referenceEdges: [],
+ taskFlows: [],
+ producerAssignments: [],
+ dependencyDepths: ids.map((resourceId) => ({
+ resourceId,
+ dependencyDepth: 0,
+ })),
+ connectionIndex: ids.map((resourceId) => ({
+ resourceId,
+ upstreamReferenceResourceIds: [],
+ downstreamReferenceResourceIds: [],
+ referenceEdgeIds: [],
+ taskFlowIds: [],
+ })),
+ unresolvedReferenceResourceIds: [],
+ cyclicResourceIds: [],
+ cyclicTaskIds: [],
+ producerMappingTruncated: false,
+ };
+ }
+ if (
+ command === 'read_local_project_resource_canvas_layout' ||
+ command === 'update_local_project_resource_canvas_layout'
+ ) {
+ const layout = {
+ schemaVersion: 'game-creator-resource-layout.v1',
+ projectId,
+ mode: args?.mode,
+ revision: Number(args?.expectedRevision ?? 0) + 1,
+ positions: args?.positions ?? [],
+ updatedAt: 1,
+ };
+ return command.startsWith('update_')
+ ? { status: 'updated', layout }
+ : layout;
+ }
+ if (command === 'read_local_project_text_preview') {
+ if (rejectPreview) throw new Error('文档读取失败');
+ const path = args?.relativePath;
+ return {
+ path,
+ mediaType: 'application/json',
+ byteLen: 20,
+ content:
+ path === 'assets/ordinary.json'
+ ? '{"text":"# 不应当作标题"}'
+ : JSON.stringify({
+ schemaVersion: 'game-creator-ui-design-state.v1',
+ state: emptyState,
+ }),
+ ...(path === 'ui/design.json' ? { uiDesignAssetId: 'design' } : {}),
+ };
+ }
+ if (command === 'load_ui_design_state')
+ return { revision: 0, state: emptyState };
+ if (
+ command === 'list_pending_local_project_resource_edits' ||
+ command === 'list_local_project_asset_generations'
+ )
+ return [];
+ throw new Error(`unexpected command ${command}`);
+ },
+ );
+ window.__TAURI__ = { core: { invoke } } as unknown as typeof window.__TAURI__;
+ const onManifestChange = vi.fn();
+ render(
+ 对话![]()
直接取）
+```
+
+`index.json`（schema `agc-template-library.v1`）：
+
+| 字段 | 说明 |
+| --- | --- |
+| `schemaVersion` | 固定 `agc-template-library.v1`；破坏性变更换 schema，不原地改语义 |
+| `library` / `libraryVersion` / `updatedAt` | 库标识、库格式版本、本次更新时间 |
+| `templates[].id` | 稳定标识，`[a-z0-9][a-z0-9._-]{0,63}`，同时是目录名 |
+| `templates[].title/summary/tags[]` | 展示与搜索/筛选用文案；`tags` 参与标签筛选与关键词命中 |
+| `templates[].runtime` | `html` / `unity` / `godot` / `cocos` |
+| `templates[].engine` / `engineVersion` | 引擎标识与版本（如 `phaser` 4.2.1、`three.js` 0.180.0） |
+| `templates[].templateVersion` / `updatedAt` | 模板内容版本；客户端按它判断是否需要重新下载 |
+| `templates[].entry` | 解压后的项目入口相对路径，如 `game/index.html` |
+| `templates[].zipKey` / `zipSizeBytes` / `zipSha256` | 模板包对象键、字节数、SHA-256（下载后强校验） |
+| `templates[].coverKey` / `coverWidth` / `coverHeight` / `coverSha256` | 封面对象键与尺寸/摘要 |
+| `templates[].metadataKey` | 单模板元数据对象键（`template.json`） |
+
+约束：
+
+- 所有对象键必须落在 `templates/` 前缀内；客户端只用「受信任 OSS 主机 + 对象键」自行拼 URL，**不直接信任清单里的地址**。
+- 任何一项校验失败（schema、标识符、sha256、尺寸、键前缀）都让整次清单读取失败，前端拿到的是全有或全无的清单。
+- 模板源在仓库 `apps/ai-game-creator-shell/template-library/`：`v1//{meta.json, project/**, cover.(png|jpg|webp|svg)}`，`template.zip` **不落仓库**，由脚本按 `project/` 现场打包（条目排序、固定时间戳，同内容重复打包摘要一致）。
+- 上传与校验由 [`scripts/agc-template-library-publish.mjs`](../../scripts/agc-template-library-publish.mjs) 完成：`--source apps/ai-game-creator-shell/template-library [--dry-run] [--prune]`，脚本生成 `template.json` 与 `index.json`、上传后回读 zip 摘要；`--prune` 清理该模板前缀下本次没有产出的旧对象（例如换封面扩展名后的残留）。
+- 当前模板：`blank-web`（空白网页）、`blank-2d-canvas`（空白二维画布）、`blank-3d-scene`（空白三维场景）、`phaser-2d-starter`（Phaser 2D 起步工程）、`threejs-3d-starter`（Three.js 3D 起步工程）。
+- 客户端可用 `AGC_TEMPLATE_LIBRARY_BASE_URL` 覆盖库地址；只接受 `https://agc-dev.oss-rg-china-mainland.aliyuncs.com`（拒绝其他主机、路径、http）。
+
+## 客户端实现
+
+### Rust：`apps/ai-game-creator-shell/src-tauri/src/template_library.rs`
+
+| 命令 | 行为 |
+| --- | --- |
+| `fetch_game_template_library` | 读 `templates/index.json`（≤4 MiB），校验后缓存到 `/templates/index.json`；网络失败时回退本机缓存并在 `source` 标 `cache` |
+| `download_game_template` | 取清单里对应条目，流式下载 zip（≤512 MiB），校验字节数与 SHA-256，解压到 `/templates/installed///`，最后写 `installed.json` 作为安装完成的唯一标记 |
+| `create_automatic_local_game_project_from_template` | 需要时先安装模板，然后在 `/projects/` 下按既有自动工作区规则建目录：先复制模板文件，再走 `init_local_game_project_at` 补 `.agent` 清单与标准目录 |
+
+安全与健壮性：
+
+- 解压只接受普通文件与目录：拒绝绝对路径、`..`、盘符、反斜杠、符号链接，并有文件数（4096）与单文件大小（256 MiB）上限。
+- 安装目录名由标识符白名单拼出，不拼接远端字符串；重装时只清理该模板自己的安装目录。
+- 模板文件与安装记录统一走 `write_game_creator_private_file` / `ensure_game_creator_private_directory_tree`，保持项目目录的私有 DACL 口径。
+- 建项目失败时删除刚创建的项目目录，不留半成品。
+
+### 前端
+
+- `src/features/template-library/templateLibraryModel.ts`：清单类型、搜索（空白分隔多关键词「与」）、标签/运行时/已下载筛选、标签选项聚合、体积格式化等纯函数。
+- `src/features/template-library/useTemplateLibrary.ts`：一次拉清单，暴露筛选状态、下载与「用模板建项目」；下载成功后只就地更新该条目的已下载状态。
+- `src/view/template-library/index.tsx`：模板库全屏页（返回、刷新、搜索、运行时/标签筛选、仅看已下载、卡片显示封面与已下载徽标、下载/使用模板）。
+ - 卡片动作按安装状态收口：已下载且版本一致时**不再显示下载入口**，只留「使用模板」；版本落后才显示「更新」；缺包显示「下载」。
+ - 过程提示（下载完成、开始建项目）走浮层 toast（复用 `packages/shared` 的 `PlatformRuntimeStatusToast`，`document.body` 浮层 + 2.6 秒自动消失），不再占用页面内位置；页面内只保留可操作的错误与空态。
+- 首页「灵感推荐」替换为「模板库」推荐位（`src/view/home/TemplateRecommendations.tsx`）：只展示封面、标题、运行时与已下载徽标，点击进入模板库页面；首页不再直接触发建项目。
+- 左侧导航新增模板库入口（`LauncherView = 'template-library'`）。
+- `src-tauri/tauri.conf.json` 的 `csp` / `devCsp` 在 `img-src` 放行 `https://agc-dev.oss-rg-china-mainland.aliyuncs.com`，用于封面图；`connect-src` 原本已放行同一域名。
+- 旧的本机灵感图目录 `src/view/home/assets/inspiration/` 与 `InspirationGallery.tsx` 一并删除，不再保留退役实现。
+
+## 验收与验证
+
+## 本地压测假数据注入（feature 控制）
+
+模板库的数据源在 Rust 侧（清单校验、安装状态、下载与建项目都在这里），TS 只消费快照做渲染，所以假数据注入也放在 Rust 侧，走与真实完全一致的链路。
+
+- 开关：Cargo feature `template-library-fixtures`（**默认关闭**）。关闭时 `apply_template_library_fixtures` 是恒等透传，正式产物里不存在注入分支，并有单测保证这一点。
+- 条数：环境变量 `AGC_TEMPLATE_LIBRARY_SYNTHETIC_COUNT`（默认 1000；`0` 表示不注入；上限 20000）。
+- 假数据特征：真实条目保留在最前，其余按真实条目循环复制；`id`/标题唯一，封面地址追加 `?synthetic=N`（强制逐张请求，模拟“每个模板各自封面”）；标签追加 `批次-00..19`；安装态按 1/3 混合。
+- 运行方式：
+
+```bash
+# 本机 dev 客户端（保留 Windows 默认 feature）
+AGC_DEV_CARGO_FEATURES=cocos-editor-execute,template-library-fixtures npm run dev
+# 直接跑二进制
+cargo run --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml --features template-library-fixtures
+# 覆盖条数
+AGC_TEMPLATE_LIBRARY_SYNTHETIC_COUNT=300 AGC_DEV_CARGO_FEATURES=template-library-fixtures npm run dev
+```
+
+两种编译模式都要过模板库单测：默认构建跑「恒等透传」用例，`--features template-library-fixtures` 跑「补齐到配置条数」用例。
+
+### 1000 条实测结论
+
+### 卡片列表虚拟滚动（react-window）
+
+- 列表改用 workspace 里已有的 `react-window@1.8.11` 的 `FixedSizeGrid`（`react-arborist` 已在用同一版本，不引入新包；类型来自 devDependency `@types/react-window`）。
+- 布局契约收在纯函数 `templateLibraryGrid.ts`（单测覆盖）：列数 = `floor((容器宽 + gap) / (最小卡宽 + gap))`、列宽 = 容器宽 / 列数、行高 = `卡片宽 × 9/16 + 文字区 150 + gap`；`buildTemplateRows` 按行切分并在行尾补 `null` 占位。
+- 卡片抽成 `TemplateCard`（`memo`），网格只渲染可视行 + 2 行 overscan；筛选条件（关键词/标签/运行时/仅看已下载）变化时把滚动位置复位到顶部，避免"从筛选切回全量后停在空白处"。
+- **页面高度契约**：页面根节点的高度按**父级 `.launcher-main` 的实测高度**内联设置，既不用百分比也不用 `100vh`。原因：外壳样式 `.launcher-main > .platform-theme { height: 100% }` 特异性高于 Tailwind 工具类，而这条百分比在 `.launcher-shell { min-height: 100vh }` 链路上是不定高，页面会退化成内容高度（虚拟网格视口高度 0、卡片区整片空白）；`100vh` 又比真实舞台高一个标题栏高度（窗口 100vh=800 / 舞台 750），底部会被裁掉。
+- 筛选区（运行时/标签）改成可独立滚动的区块（`max-h-[24vh]`），标签数量随库量增长时不再把卡片区挤出窗口。
+- 回归：`templateLibraryGrid.test.ts` 覆盖列数/行高/行数/切行；页面测试用固定视口断言「1000 条只渲染 ≤ 40 张卡片，滚动高度仍按 250 行计算」。
+
+- 页面能正常渲染 1000 张卡片（头部显示「共 1000 个模板 · 已下载 335 个」），并且滚动容器生效（窗口高度压到 430px 时右侧出现滚动条，页面内容被裁切而不是溢出到窗口外）。
+- 需要后续收口的两点（本次未改）：① 标签筛选条随库量膨胀——1000 条时聚合出 35 个标签、占三行；② 一次性渲染 1000 个卡片节点并触发 1000 次封面请求。建议标签只展示 Top N + 「更多」，卡片列表加分页或虚拟滚动。
+- 前端回归：1000 条渲染 + 已安装过滤（334）/标签过滤（50）/关键词过滤数量自洽，见 `apps/ai-game-creator-shell/tests/templateLibraryView.test.tsx`。
+
+```bash
+# 模板库单测（清单校验、键安全、解压路径逃逸、安装与建项目）
+cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml --bin genarrative-ai-game-creator-shell template_library
+# 模板库真连检查（可选，需要网络）：读线上清单、下载安装线上模板包并据此建项目
+cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml --bin genarrative-ai-game-creator-shell template_library -- --ignored
+# 前端模型与页面单测（AGC 测试统一在 apps/ai-game-creator-shell/tests/）
+npx vitest run apps/ai-game-creator-shell/tests/templateLibraryModel.test.ts apps/ai-game-creator-shell/tests/templateLibraryView.test.tsx
+# 类型检查 / 编码 / 空白
+cd apps/ai-game-creator-shell && npm run typecheck
+npm run check:encoding
+git diff --check
+# OSS 侧匿名可读
+curl -s https://agc-dev.oss-rg-china-mainland.aliyuncs.com/templates/index.json
+```
+
+手工验收：打开模板库 → 搜索与筛选 → 下载（出现「已下载」徽标）→ 「使用模板」→ 进入项目工作台且项目里已有模板文件。
+
+运行态核验（客户端真的拉过清单时）：本机缓存 `/templates/index.json` 与线上 `templates/index.json` 逐字节一致；`/templates/installed///installed.json` 出现即表示该模板已下载完成。
+
+## 失败与回退
+
+- 清单读不到且没有本机缓存：模板库页显示错误与重试，首页推荐位显示「模板库暂时没有可用的模板」。
+- 版本落后：`installedVersion != templateVersion` 视为需要重新下载，点「使用模板」会先重下再建项目。
+- 需要回退整条链路时，删除 `templates/` 前缀即可让客户端回到"空模板库"；客户端代码路径不受影响。
diff --git a/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md b/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md
index 5eb7d09f2..457c89436 100644
--- a/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md
+++ b/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md
@@ -1,5 +1,24 @@
# AI 游戏创作智能体 App 实施计划
+## 策划 Agent 批量局部修改
+
+`patch_file` 的所有 edits 均匹配同一份原文件，参数顺序不影响结果。完成唯一匹配与不重叠校验后，按原文起点升序拼接未修改片段与替换文本，最后一次性写入；任一校验失败时不写文件。回归用例覆盖乱序 edits、中文内容与替换长度增减，并核对完整落盘内容。此行为仅属于策划 Agent 文件工具。
+
+## 策划 Agent 运行 panic 边界
+
+`finish_design_command` 的运行段包在 `catch_unwind` 边界内：任何运行期 panic 被转成一次普通失败，由既有错误分支从最后一个持久检查点恢复，向会话写入固定公开文案"策划运行发生内部错误，本轮已中断，可直接重试；若反复出现请反馈。"，并以 `running=false、可重试、lastError 有值` 的视图正常返回。panic 负载只写入私有 design_debug，不进入用户可见消息；continue、recover_uncertain 与 decide 三个入口共享同一边界。边界不改变工具错误、Provider 瞬态重试和批次不确定恢复的既有语义。
+
+运行段通过 task-local 携带项目根；首次运行时安装的 panic hook 在 panic 瞬间把代码位置（file:line:column）和负载追加写入私有 design_debug，随后交给原 hook 维持既有 stderr 输出。hook 只在策划运行段内生效（其它任务无 task-local 上下文时直接透传），多线程 runtime 下 future 跨 worker 迁移也能正确归因。
+
+## 资源画布交互与工作台状态同步
+
+- 工作台向窗口标题栏发布正在运行的项目时，输入未变化不得形成重复发布与清理的渲染循环；打开项目动作始终使用当前工作台处理逻辑，退出工作台后清除其标题栏状态。
+- 资源子画布（含「所有资源」）保留空白处左键框选、资源卡左键选中/拖动、触摸板双指平移及捏合缩放；右键按住空白处或资源卡拖动时平移画布，不改变资源选择与布局。中键和空格抓手继续可用。总览保留既有左键平移，并支持右键平移。
+- 画布接管的右键手势不弹出原生菜单；输入框、媒体操作、工具条和独立浮层不被画布抢占。指针取消、捕获丢失或窗口失焦后终止平移，不能继续跟随指针。
+- 运行不可用提示只取决于运行能力与 UI 编辑器状态，不因资源选中、取消选中或框选而消失，且不改变运行入口的真实可用性。
+- 本次边界不包含布局算法、持久化坐标、预览读取预算或后端契约调整。首次进入抖动与平移异常须在更新循环消除后单独实测，不能仅凭状态循环修复宣称已解决。
+- 验收包含真实窗口 Context 与工作台的状态同步回归、运行提示与选中并存、左右键分流、平移中断及连续滚轮事件；真实客户端首次进入与触摸板手感为独立人工验收项。
+
## 资源卡选中工具栏与导出
- 共享选中工具栏按实际显示的快速编辑、编辑动作、改造、导出与宿主动作组生成分隔线；空组不产生分隔线，不依赖宿主 CSS 隐藏重复线。
@@ -8,6 +27,10 @@
## 文档与代码素材预览
+- JSON 资源的卡片按内容语义分流：普通 JSON 显示 JSON 图标/标签，详情按 JSON 代码块显示；UI 设计 JSON 显示 UI 设计标识并提供现有 UI 编辑器入口，不再把 State 原文铺在卡面上。功能分类、manifest kind 和资产身份不因识别而改写。
+- UI 识别由原生文本预览在已登记、受控、完整读取的同一份 UTF-8 内容上完成，复用编辑器的 `game-creator-ui-design-state.v1` 契约解析、canonical 校验、revision/State 校验及项目/资产身份校验。前端只消费识别结果，不按文件名、kind 大小写或正文片段自行认定 UI；普通、损坏、未知 schema、跨项目或跨资产 JSON 不获得 UI 编辑能力。
+- JSON 为完成内容识别继续走现有受限预取队列、并发/容量和 2 MiB 原生文本读取上限。识别失败不写文件、不生成空 State、不做格式迁移；能读取的原文仍可按 JSON 查看，读取失败仍展示原有错误。非 JSON 代码卡继续仅按用户详情请求读取。
+- 编辑器加载/保存/代码生成复核当前项目的已登记 JSON 资产及完整文档，不以 kind 必须精确等于 `UI` 阻断合法已有设计；创建新 UI 状态仍要求正式 UI 资源，不能借普通 JSON 预览初始化或覆盖文件。现有 State 保存锁、CAS、revision 与恢复边界不变。
- 文档与代码素材选中工具栏提供「预览」，打开独立、可滚动的只读弹窗；关闭、切换素材或项目后不残留旧内容。加载中、空文件与读取失败分别呈现，允许重试可重试的错误。
- 复用资源预览队列、身份缓存、项目 scope、失效与权限校验，继续调用 `read_local_project_text_preview`。代码卡不做可见性预取，仅用户显式打开详情时读取；不新增 IPC，不扩大可读取文件范围，不增加编辑/保存能力。
- 文档正文统一使用现有 Markdown 渲染器；代码文件以按扩展名标注语言的 Markdown 围栏代码块呈现。围栏必须长于正文内的反引号串，正文空行与缩进保持原样，不把源码当 Markdown 正文或 HTML 执行。
@@ -19,6 +42,10 @@
## 2026-09-16 DirectProject 回合展示唯一归属
+- 聊天历史使用 `read_direct_project_history_slice` 的 `messagesOnly: true` 模式，按有正文的 user/assistant 消息分页，默认 20 条；工具/推理原始记录不占聊天页名额、不进入聊天分页响应，也不从磁盘删除。接口省略该选项时维持原始 item 切片语义。响应给出明确的 `oldestItemId` 游标；消息投影不能重新发明分页位置。
+- 消息模式读取逐行过滤原始记录，不在内存中积累整份工具输出；正文、原始 ID 和信封时间原样保留。旧的无 ID 消息不能凭空生成身份，必要时向前扩展到已有消息 ID 边界；没有更早消息时结束分页。
+- 首屏和加载更早消息共用分页解析；重复点击只发一个请求，重叠消息按原始 ID 去重并保留当前显示版本。切项目、同项目重新加载及 A→B→A 的迟到响应不得覆盖当前消息、游标或加载状态；失败保留已有消息与分页位置并允许重试。
+- 历史读取来源与 Runtime 所有权分开记录；从磁盘分页读出的消息不能当作未落盘实时消息保留到新页末尾。重新读取历史时回到最新页，旧页仍可从原生游标再次向前加载；真正尚未回读到的实时消息继续保留，不改原始日志、时间或内容。
- 交付合同：实时消息、历史回读、工具详情与最终回复先归一为按 `clientTurnId` 唯一的回合，再渲染一次。用户消息始终保留；同一回合的正文、工具和耗时不能从消息、实时尾部、未归属尾部等多个出口重复展示。
- 归属来自 `direct-codex:{clientTurnId}:{role}`、文本流中保留的原始 item ID，以及项目历史内明确用户记录之后的 assistant 记录。先在已加载的完整消息集合中关联，再做可见分页；持久历史继续通过 canonical item 切片懒加载，`hasMore` 为真时，未加载回合的工具流不得漂到当前页尾部。禁止将第 N 个有工具回合配给第 N 条用户消息，禁止按文本长度、标点或时间窗猜测归属。缺身份的旧记录保留，不猜造其与其它回合的关联。
- 有回合流时正文与工具位置仅来自 item 边界与 `seq`，工具详情按该回合的 `callId` 关联；没有流时同一个回合容器显示历史消息与工具。整轮累计文本仅在活动回合尚无流和持久 assistant 时作兜底，不另建实时消息出口。
@@ -133,6 +160,7 @@ npm 游戏的可预览产物固定为对应 package 目录下的 `dist/index.htm
## 2026-08-24 Direct Codex 已登记资源查询与媒体生成语义工具
- `agc_tools` 新增 `agc_list_registered_assets` 与 `agc_create_or_derive_resource`。前者按 `kind / assetId / offset / limit` 有界查询客户端权威 manifest，并可显式返回角色动画正式序列帧的稳定 objectKey、assetObjectId 和尺寸；结果不包含完整 manifest、prompt、model、provider route、签名 URL、宿主路径或凭据。后者只接受 `kind / mode / sourceLocalAssetId / prompt / assetName`，`create` 仅允许无源视频、音效和背景音乐，`derive` 必须引用当前项目已登记的 localAssetId，角色动画固定为 derive。
+- `prompt` 上限按 `kind` 分别生效，且工具 schema、MCP 校验、客户端工具桥与提交校验共用同一权威口径（`resource_edit_prompt_max_chars`）：背景音乐 140、音效 1900、视频与角色动画 4000、图片编辑 32000。schema 逐 kind 声明 `maxLength` 并在 `prompt` 描述里写明数字，超限必须在发起任何桥请求与付费提交之前失败并回报真实上限；`sourceLocalAssetId` 不是当前项目已登记资源时，错误文案必须直接给出 `agc_list_registered_assets` 与 `agc_list_project_files` → `agc_import_account_assets.localPaths` 两步后续动作。
- 项目路径、projectId、当前 revision、源文件路径与媒体类型、operationId、Idempotency-Key、登录态、项目锁、付费提交、轮询恢复、下载校验与 manifest 事务全部由客户端持有。模型不能提交或覆盖这些字段。同一 Direct `clientTurnId + 规范语义参数` 生成稳定 UUID v4 身份；单回合同参重试复用原 operation，不同请求串行且最多四项。跨回合存在完全匹配的 pending 账本时优先恢复原 operation，不能换键重发。
- 资源查询同时投影未完成 operation 的安全状态。媒体工具成功只返回 operation、本地相对路径、资源类型、Canvas/resource/asset/task 身份、正式序列帧以及脱敏后的 `warnings / sliceWarnings`；错误继续使用统一脱敏边界。客户端资源账本持久化 completed 结果的两类告警，committed replay 不能把历史告警伪装成空集合。
- 角色动画、视频、音效和背景音乐在构造新的远端请求前统一准备当前项目同名画布与素材目录上下文，并在端点支持时携带 `projectId / assetFolderId / canvasCompletion`。角色动画 placeholder 使用源图片真实宽高，避免非方形角色进入画布时失真；正式 resource/asset 与序列帧继续直接复用 External 返回身份，不从首帧伪造重复资源。已有冻结 request body 或已受理 operation 保持不变，不因本次升级重建请求或重复扣费。
@@ -1502,3 +1530,56 @@ Direct 回合的所有权属于进程内项目身份锁，不属于当前页面
- 两个窗口同时对同一项目发起 Runtime 写请求时，用户体验仍由项目级写锁串行决定；本次不引入跨窗口排队提示。
- 平台会话在窗口间传播依赖共享 localStorage 与 Runner 权威；渲染层不做跨窗口事件推送，另一个窗口在下一次会话校验或刷新时收敛。
+
+## 2026-09-17 AGC 项目定时快照上传（agc-dev）
+
+### 目标与非目标
+
+- 目标：AGC 在项目工作区打开期间按固定周期把用户项目增量上传到 OSS `agc-dev`，并在项目关闭时立即补一次同步；重复内容不重复上传，远端占用跟随当前清单收敛。
+- 非目标：不做云端下载/恢复、不做跨设备合并、不保留多版本历史、不新增面向用户的上传界面、不修改 `/api/external/v1` 与 OpenAPI、不新增 SpacetimeDB 表。
+- 非目标：不把 OSS AccessKey 放进客户端；客户端不直连 OSS。
+
+### 参与入口、状态与跨模块边界
+
+- 触发入口有两个：工作区窗口 `main` 存活期间的周期定时器、工作区窗口关闭事件（`CloseRequested`）。两者共用同一个进程内同步器，同一项目的同步串行执行，周期触发在已有同步进行时直接让位，不排队堆积。
+- 应用退出（`RunEvent::Exit`）不重复发起同步：该时刻窗口已销毁，按窗口重新枚举项目只会得到空集；退出路径只负责在有界预算（15 秒）内等待在途同步收尾，让关窗触发的那一次同步能写完索引再退出。
+- 客户端扫描、差异对比、索引持久化与上传编排都在 Tauri Rust 进程（`src-tauri/src/project_snapshot/`）；WebView 只读状态，不参与差异计算。
+- 本地索引是增量对比的唯一依据：`/project-snapshots//index.json` 保存上次成功同步的相对路径、校验和、字节数和修改时间。项目根使用现有 manifest 的稳定 `project_id` 作为远端身份，路径不再作为身份。
+- 可观测性按产品口径收敛到本机日志：同步结果、失败分类、延后与跳过计数只写入 AppData 诊断日志（`project_snapshot.sync.*` 前缀），客户端界面不暴露上传状态、时间线或入口按钮。`read_local_project_snapshot_state` 与 `sync_local_project_snapshot` 两条命令仅作为 native-only 的排障与联调入口登记，不在渲染层调用。
+- 远端写入经 `api-server`，客户端只持平台登录态 Access Token。两条登录态路由：`POST /api/agc/project-snapshots/files`（单文件，正文为原始字节，元数据走查询串）与 `POST /api/agc/project-snapshots/manifest`（本次同步后的完整清单）。
+- 对象键与清单由服务端决定：文件键为 `agc/project-snapshots/v1/{userId}/{projectId}/files/{sizeBytes}-{checksumDigest}/{relPath}`，清单键为 `agc/project-snapshots/v1/{userId}/{projectId}/manifest.json`。键里带字节数与摘要，因此"对象已存在且长度一致"可以作为内容一致的判据；路径按原始大小写保留，不走 `put_object` 的低位规范化。`agc` 前缀继续是服务端专用私有前缀，通用对象键解析与客户端直传票据都不覆盖它。
+- 目标 bucket 使用独立配置 `GENARRATIVE_AGC_PROJECT_SNAPSHOT_OSS_BUCKET` / `_ENDPOINT` / `_ACCESS_KEY_ID` / `_ACCESS_KEY_SECRET`，默认 `agc-dev` + `oss-rg-china-mainland.aliyuncs.com`，未配置时回退 `ALIYUN_OSS_*`；与"资源 bucket 与备份 bucket 分离"的既有口径一致。
+
+### 正常、失败、重试与幂等行为
+
+- 差异对比口径：先按 `相对路径 + 字节数 + 修改时间` 判定是否候选变更，命中旧记录则复用已存 `sha256`，只有 `(size, mtime)` 变化才重算摘要。产出新增、修改、删除三类集合，只上传新增与修改的文件。
+- 每次成功同步的最后一步上传该项目的 `manifest.json`（当前全量文件清单：相对路径、摘要、字节数、同步序号）。清单描述的是项目当前全量内容，因此清单体积就是该项目在 OSS 上的常驻占用。
+- 远端回收：清单写入成功后，服务端读取上一版清单，按 `(路径, 字节数, 摘要)` 反推出不再被当前清单引用的对象键并删除。只处理上一版清单登记过的键，不做 LIST，因此不可能误删其它项目或其它功能的对象；单次最多回收 2000 个对象，剩余部分留到下一次清单写入继续；上一版清单读不到或解析失败时整轮跳过回收（fail-closed）。单个删除失败只记日志，不影响本次同步语义。
+- 因此本功能是"当前状态镜像 + 清单"，不保留历史版本：同一路径的内容变化会覆盖式替换远端对象，回滚能力不在本轮范围内。
+- 幂等：同一摘要与字节数的对象重复提交由服务端 HEAD 校验后跳过；探测失败按"未存在"处理并照常 PUT，宁可多传一次也不漏传。索引只在清单写入成功后推进，失败时保留旧索引以便下次重算。
+- 与项目写锁解耦：同步不持有项目写锁，也不阻塞 Agent 写入。读取摘要后与上传前各按 `(字节数, 修改时间)` 复核一次，任一处不一致就判定该文件"同步期间发生变化"：本轮不上传、不写入索引；若该路径上一轮已同步过则沿用旧记录，避免被误判成删除而触发远端回收。这类文件在下一个周期或下次关窗时重算重试。
+- 失败关闭：单个文件失败不推进该文件的索引项，失败文件与剩余文件在下一次周期或下次关闭时重试。鉴权失败（401/403）与格式类拒绝（400/413）是确定性失败，停止本轮剩余请求并等待用户处理后重试；服务端配额或频率拒绝（429）与传输类失败按可重试处理。
+- 配额与限流：单文件 64 MiB、单次同步上传预算 512 MiB（超出部分延后到下一次）、单项目常驻上限 2 GiB（客户端在扫描后先判，超限直接给出明确失败；服务端按清单累计体积复核并返回 413）；服务端按用户做进程内小时配额（文件 3000 次、清单 120 次）并对同一项目强制 5 秒最小清单间隔，超限返回 429 且带 `Retry-After`。进程内配额只用于抑制异常客户端与失控重试，跨节点配额由"单项目上限 + 清单引用回收"保证。
+- 生命周期：同步有界超时（单文件与整次同步分别设上限），项目关闭与应用退出路径不因同步失败而阻塞或延迟退出超过超时上限。
+- 上传内容边界：复用项目索引与 checkpoint 同一份 `should_skip_project_snapshot_path` 口径——整个 `.agent`（含 runtime、logs、checkpoint、manifest、project.lock）、版本控制目录、`node_modules`/`target`/`dist`/`build`/`coverage`/`.cache`、凭据目录与 `.pem`/`.key` 等敏感后缀都不参与同步；符号链接与重解析点同样跳过。单文件（64 MiB）与单次同步总量（512 MiB）各有上限，超限文件进入跳过或延后清单而不是静默丢弃。
+
+### 契约与兼容
+
+- 新增登录态内部路由 `POST /api/agc/project-snapshots/files`，请求 DTO 放在 `shared-contracts`；不属于 `/api/external/v1`，因此不更新 External OpenAPI，与 `/api/error-reports` 同类。
+- 服务端校验 `projectId` 形态（拒绝路径分隔符、`..`、控制字符与超长值）、相对路径规范（正斜杠、拒绝绝对路径与穿越）、摘要形态（`fnv1a64:` + 16 位十六进制）和字节数上限，任何越界返回 4xx 而不是写入 OSS。
+- 不改变客户端与 Runner 的本机协议、平台会话语义、项目写锁与 manifest 结构；新增索引文件位于 AppData，不进入用户项目目录。
+
+### 验收标准与证据来源
+
+- 定向 Rust 测试：首次同步全量、仅改一个文件时只产生一个修改项、删除文件只体现在清单、`(size,mtime)` 未变时复用旧摘要、排除规则与上限跳过、同步失败不推进索引、同一项目并发触发串行化。
+- 服务端测试：越界 `projectId`/相对路径/摘要被拒；相同摘要重复提交走跳过分支；超过单项目上限返回 413；超过用户小时配额返回 429；鉴权缺失返回 401；OSS 未配置返回明确的 5xx 而不是写入空对象。
+- 运行时 smoke：AGC 开发态打开项目、观察索引写入与同步日志、关闭工作区窗口后确认关闭触发的那次同步执行；报告为"客户端 diff 已验证 / 服务端已配置环境联调"两层，不合并成一句"已通"。
+- 边界：新增日志与错误文案不含 Access Token、AccessKey、绝对路径与项目内容。
+
+### 未决问题
+
+- 用户侧看不到同步状态与失败原因（界面按产品口径不暴露），排障只能读 AppData 诊断日志或调用 native-only 命令；如果后续要支持用户自助排查，需要先确认是否允许在客户端出现上传相关 UI。
+- 历史版本：本轮只保留"当前状态镜像 + 清单"，旧内容对象在清单写入成功后即被回收，没有回滚能力；要保留历史版本需要先定"保留几个 revision + 由谁回收"的策略。
+- 用户级配额：跨节点的用户总量配额与计费口径未定；当前用单项目 2 GiB 上限 + 清单引用回收保证常驻占用有界，用户级总量只能靠项目数间接约束。
+- 目标 bucket 的生命周期规则（例如转低频/过期删除）需要在部署环境确认后单独收口；功能本身已不再依赖它来控制增长。
+- 大项目（素材数量多、单文件大）的首轮全量上传耗时与带宽占用未实测；单次预算 512 MiB 会把超出部分留到下一次同步，但并发上限与断点续传仍未引入。
diff --git a/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md b/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md
index 0d1af4ab8..d13920f03 100644
--- a/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md
+++ b/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md
@@ -70,7 +70,7 @@ 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`。该入口由 `apps/ai-game-creator-shell/scripts/start-tauri-dev.mjs` 解析 AGC Vite 实际端口：Linux 默认取当前用户端口段的 `start + 5`，占用时只在本用户段内漂移；Windows / macOS 保留 `3080` 为兼容首选并允许统一漂移。最终端口通过 `GENARRATIVE_AGC_VITE_PORT` 传给 `beforeDevCommand` 和配套后端端口解析器，通过 Tauri CLI 动态 `build.devUrl` 配置传给 WebView，并通过 Vite CLI `--port` 启动严格监听；Vite 继续使用 `strictPort`，任何一层都不得自行改到另一个端口。AGC 配套后端的 `backend` 模式启动 SpacetimeDB、独立 `bgfilter-worker` 和 `api-server`，并在复用现有后端前同时检查三者状态及 `/v1/ping`、`/readyz`、`/healthz`；worker 缺失时不得把不完整的 API/数据库组合误判为 ready。任一配套服务在启动阶段进入 `failed` 时，外层启动器必须立即报告具体服务和退出原因，不能继续等待前端地址超时。端口健康不等于归属正确：复用前还必须证明端口上的监听进程属于当前工作树（Windows 按 `server-rs/target/debug/api-server.exe` 绝对路径与 SpacetimeDB `--data-dir` 校验，探测不可用时退化为旧行为），无法证明归属时一律不复用，改为启动本工作树自己的后端并在需要时端口漂移；否则上个工作树 Ctrl+C 残留的后端会被当成自己的后端复用，改了数据库的工作树会连到旧库。启动器在创建原生窗口前预检最终地址；AGC Vite marker 同时提供 `repoRoot + processId + port`，与 `.app/dev-stack.json` 的 `instanceId` 和 API target 交叉核对；若竞态中该地址被 AGC Vite、无响应监听器或其它服务占用，一律失败关闭，不复用、也不擅自终止无法证明归属的进程。
+AI 游戏创作客户端使用 `npm run agc`。该入口由 `apps/ai-game-creator-shell/scripts/start-tauri-dev.mjs` 解析 AGC Vite 实际端口：Linux 默认取当前用户端口段的 `start + 5`，占用时只在本用户段内漂移；Windows / macOS 保留 `3080` 为兼容首选并允许统一漂移。最终端口通过 `GENARRATIVE_AGC_VITE_PORT` 传给 `beforeDevCommand` 和配套后端端口解析器，通过 Tauri CLI 动态 `build.devUrl` 配置传给 WebView，并通过 Vite CLI `--port` 启动严格监听；Vite 继续使用 `strictPort`，任何一层都不得自行改到另一个端口。AGC 配套后端的 `backend` 模式启动 SpacetimeDB、独立 `bgfilter-worker` 和 `api-server`，并在复用现有后端前同时检查三者状态及 `/v1/ping`、`/readyz`、`/healthz`；worker 缺失时不得把不完整的 API/数据库组合误判为 ready。任一配套服务在启动阶段进入 `failed` 时，外层启动器必须立即报告具体服务和退出原因，不能继续等待前端地址超时。端口健康不等于归属正确：复用前还必须证明端口上的监听进程属于当前工作树（Windows 按 `server-rs/target/debug/api-server.exe` 绝对路径与 SpacetimeDB `--data-dir` 校验，探测不可用时退化为旧行为），无法证明归属时一律不复用，改为启动本工作树自己的后端并在需要时端口漂移；否则上个工作树 Ctrl+C 残留的后端会被当成自己的后端复用，改了数据库的工作树会连到旧库。启动器在创建原生窗口前预检最终地址；AGC Vite marker 同时提供 `repoRoot + processId + port`，与 `.app/dev-stack.json` 的 `instanceId` 和 API target 交叉核对；若竞态中该地址被 AGC Vite、无响应监听器或其它服务占用，一律失败关闭，不复用、也不擅自终止无法证明归属的进程。开发态客户端不检查更新：启动器给 AGC Vite 注入 `VITE_AGC_ENABLE_APP_UPDATE_CHECK=0`，客户端不请求 OSS 更新清单、也不显示更新入口；需要联调更新流程时显式传 `VITE_AGC_ENABLE_APP_UPDATE_CHECK=1`。
AGC 开发态还会按后台 Web 的端口约定额外拉起 `apps/admin-web`：Linux 用当前用户端口段的 `start + 3` 槽位，非 Linux 以 `3102` 为兼容首选并允许统一漂移，`ADMIN_WEB_PORT` 可显式指定且必须避开已解析的 AGC Vite 端口；设置 `AGC_DEV_ADMIN_WEB=0` 可关闭。后台 Vite 与 AGC Vite 一样由 `start-dev-stack.mjs` 直接持有并随启动器退出收束，不走 `npm run dev:admin-web`——后者会整体重写 `.app/dev-stack.json`，覆盖本次配套后端的归属状态；后台 Web 的端口解析、启动失败或运行中意外退出都只打印告警，不阻断也不连带停止 AGC 客户端与配套后端。前端与配套后端就绪后，启动器会打印一行 `[ai-game-creator-shell] 启动汇总:`，依次给出前端、后端、后台、数据库与 `bgfilter-worker` 的实际地址；端口漂移或默认端口被其它工作树占用时，以这一行为准。
@@ -540,6 +540,50 @@ curl -fsS --max-time 5 http://127.0.0.1/api/editor/showcase/resources >/dev/null
角色动画源帧 PUT、透明帧 PUT 和最终帧 HEAD 使用 `AppState` 内同一个 OSS HTTP Client/连接池，并受进程级 8 路 OSS permit 保护；BgFilter、阿里云抠图和本地处理不占用该 permit。每个 OSS attempt 最多 3 次（首次 + 2 次重试），退避为 250ms、500ms；只重试 timeout、无 HTTP 响应传输错误、OSS PutObject 的 `400 + RequestTimeout`、PUT 400 错误体读取失败（未解析出 `Code`，按 timeout/transport 归类）、408、429 和 500–599。动作帧 PUT 收到 400 时只读取最多 16 KiB OSS 错误 XML，提取 `Code` 和 `RequestId`；`oss_request_id` 优先使用响应头 `x-oss-request-id`，XML 字段只作回退。错误体读取超时/断流不再按确定性 400 处理：已解析出的 `Code` 优先生效；未解析出 `Code` 时按读取失败原因置 `timeout`/`transport` 并重试，message 追加「错误响应体读取失败」。日志字段包括 `frame_index`、`object_key`、`operation=source_put|final_put|final_head`、`attempt`、`max_attempts`、`retryable`、`will_retry`、`retry_delay_ms`、`permit_wait_ms`、`timeout`、`connect`、`transport`、`oss_code`、`oss_request_id`、`status` 和 `elapsed_ms`。`请求 OSS 失败` 时，`timeout/connect/transport=true` 表示传输类失败；`status=400, oss_code=RequestTimeout, timeout=true`、`status=429` 或 `500–599` 表示暂时性失败，PUT 的 `status=400`、`oss_code` 为空且 `timeout=true` 或 `transport=true`（message 含「错误响应体读取失败」）同样是暂时性失败。除 `RequestTimeout` 和该错误体读取失败两类例外外，其他 400、401/403/404、配置、URL 和签名错误是确定性失败，不会重试。最终帧 HEAD 失败只会重试 HEAD，不会重复 PUT；如果任一帧最终失败，确认整段动作已排空已启动 Future，并检查任务按现有契约退款且没有发布缺帧动画。
+### AGC 项目快照上传目标
+
+AGC 客户端按周期与项目关闭时机把用户项目增量上传到 `agc-dev`。客户端只持有平台登录态 Access
+Token，经 `POST /api/agc/project-snapshots/files`（单文件原始字节）与
+`POST /api/agc/project-snapshots/manifest`（本次同步清单）交给 `api-server`，由服务端写入私有前缀
+`agc/project-snapshots/v1/{user}/{project}/`；客户端不直连 OSS，也不持有 OSS 凭据。
+
+```env
+GENARRATIVE_AGC_PROJECT_SNAPSHOT_OSS_BUCKET=agc-dev
+GENARRATIVE_AGC_PROJECT_SNAPSHOT_OSS_ENDPOINT=oss-rg-china-mainland.aliyuncs.com
+GENARRATIVE_AGC_PROJECT_SNAPSHOT_OSS_ACCESS_KEY_ID=
+GENARRATIVE_AGC_PROJECT_SNAPSHOT_OSS_ACCESS_KEY_SECRET=
+```
+
+专用凭据为空时回退 `ALIYUN_OSS_ACCESS_KEY_ID` / `ALIYUN_OSS_ACCESS_KEY_SECRET`，bucket 与 endpoint
+仍默认指向 AGC 发行 bucket，因此回退凭据必须具备目标 bucket 该前缀的 `PutObject` / `GetObject` /
+`DeleteObject` 权限；`api-server` 启动时会打印一行 `AGC 项目快照 OSS 客户端已启用`（含 bucket、
+endpoint 与凭据来源，不含密钥），凭据缺失或只配一半则跳过该客户端、接口返回 `503`，客户端按失败关闭
+处理：不写空对象，也不推进本地增量索引，下一次触发重算重试。
+
+远端占用按当前清单收敛：每次清单写入成功后，服务端用上一版清单反推不再被引用的对象键并删除，单次最多
+回收 2000 个，上一版清单不可读时整轮跳过（不会误删）。因此不需要额外配置 bucket 生命周期来防止无界
+增长；`agc/project-snapshots/v1/` 下同一路径只保留当前内容，历史版本不保留。配额口径：单文件 64 MiB、
+单次同步上传预算 512 MiB、单项目常驻 2 GiB；超限分别表现为跳过/延后/413。服务端另有进程内小时配额
+（文件 3000 次、清单 120 次）与同一项目 5 秒最小清单间隔，超限返回 `429` 并带 `Retry-After`。
+
+两层可重复的现场验证：
+
+```bash
+# 1. 存储层：直接对真实 bucket 做内部前缀写入、读回与清理，并在结束时删除探针对象。
+cargo run -p platform-oss --example agc_project_snapshot_live_smoke --manifest-path server-rs/Cargo.toml
+
+# 2. 客户端链路：真实差异引擎 → 本地 api-server → 真实 OSS。第一次必须 synced 且上传 > 0，
+# 紧接着的第二次必须 no-op 且上传 0 个文件；需要先取得登录态并指定项目与索引目录。
+cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml \
+ project_snapshot_live_sync -- --ignored --nocapture
+```
+
+客户端冒烟读取 `GENARRATIVE_AGC_PROJECT_SNAPSHOT_LIVE_PROJECT`（项目绝对路径，建议用可丢弃的副本）、
+`..._LIVE_TOKEN`、`..._LIVE_API_BASE_URL`、`..._LIVE_USER_ID` 与 `..._LIVE_CONFIG_DIR`（索引目录，
+`cargo test` 进程没有窗口 setup 初始化 AppData 配置目录，必须显式指定）；未设置时用例自我跳过。
+本地联调可用 `npm run dev:api-server` 起 api-server，并用密码登录（开发态默认允许未知手机号自动注册）
+取得 Access Token。
+
## 生产运维
生产部署当前口径：
diff --git a/docs/【编辑器】画布Agent对话面板-2026-07-03.md b/docs/【编辑器】画布Agent对话面板-2026-07-03.md
index fec3db0e7..b5c244b6e 100644
--- a/docs/【编辑器】画布Agent对话面板-2026-07-03.md
+++ b/docs/【编辑器】画布Agent对话面板-2026-07-03.md
@@ -27,6 +27,7 @@
- 下面的工具选择口径属于 Agent 规划 prompt / function-calling 约束，不是侧边栏 UI 说明文案；侧边栏面板不展示这些规则解释。
- 用户要求“规范图 / 视觉规范图 / 风格规范图 / 素材规范展板”时，规划默认选择 `generate_image`，并在 prompt 中明确要求生成规范展板，包含统一视角、线条粗细、色卡、材质、阴影、圆角、状态层级、尺寸标注等可落地的视觉规范元素。
- 用户要求“角色规范图”且语义是角色的规范展板、风格展板或设定板时，仍走 `generate_image`，不要误分流到 `generate_character`；只有实际生成角色立绘、角色主形象或角色视觉资产时才走 `generate_character`。用户要求多个图标素材、图集或 spritesheet 时才走 `generate_icon_spritesheet`。
+- 画布 Agent 的 `generate-icon-spritesheet` 不暴露切分模式参数，链路固定显式传 `sliceMode=connected-components`；等分网格或固定槽位需求必须由外部 API 调用方显式传 `sliceMode=grid` 与来自需求的 `gridX`/`gridY`，画板工具栏的 `拆分图集` 仍只做连通域拆分。禁止在工具描述、确认卡或回复里承诺按 `2×2` 等网格切分。
- 所有生成必须走 `execute_billable_asset_operation_with_cost` 与模型定价配置，禁止绕过定价收口。
- function-calling 的 JSON Schema 必须与参数默认值和运行时校验保持一致，不能只在 description 中提示会被运行时拒绝的组合。`generate-ui-design` 固定 `gpt-image-2`，因此 `image_size` 只暴露 `1K / 2K`；其它可切换图片模型的工具通过共享条件 schema 在显式选择 `gpt-image-2` 时同样把 `image_size` 限制为 `1K / 2K`，省略模型时仍按默认 nanobanana2 允许 `0.5K`。`generate-video` 省略 `model` 时按默认 `seedance2.0-fast` 约束 `resolution` 为 `480p / 720p`，显式选择其它模型时仍使用其现有分辨率范围。运行时强类型校验继续作为最终防线。
- `generate-sound-effect` 与站内 / External v1 的 SFX V2 契约一致：Prompt 使用 ECMAScript `String.trim()` 等值 canonicalization 且限制 `1–2048` Unicode code points，model 固定 `eleven_text_to_sound_v2`，`duration` 缺省为手动 `5s`、显式 `null` 为自动时长、数值范围为有限 `0.5–30` 小数，`loop` 缺省 false。显式 `duration:null` 必须绕过通用“顶层 null 当缺省”兼容层，不能在 job payload 中变回 `5s`；确认后的 canonical payload 继续进入现有 `editor_sound_effect_generation` Worker，不新增 Agent 专属音频链路。
diff --git a/docs/【编辑器】画板图标素材生成入口设计-2026-06-15.md b/docs/【编辑器】画板图标素材生成入口设计-2026-06-15.md
index ae769d8b3..b362711d4 100644
--- a/docs/【编辑器】画板图标素材生成入口设计-2026-06-15.md
+++ b/docs/【编辑器】画板图标素材生成入口设计-2026-06-15.md
@@ -2,7 +2,7 @@
日期：`2026-06-15`
-更新时间：`2026-08-10`
+更新时间：`2026-09-17`
## 背景
@@ -40,7 +40,15 @@
## 生成契约
- 前端提交到 `POST /api/editor/icon-spritesheets/generations`。
-- 图集拆分通过 `sliceMode` 显式选择：`connected-components` 按透明像素连通域切分（默认），`grid` 按用户提供的 `gridX × gridY` 网格切分。
+- 图集拆分模式必须由调用方显式声明，任何入口都不得存在隐式默认值：`sliceMode` 是图标图集生成请求的必填字段，`connected-components` 按透明像素连通域切分，`grid` 按调用方提供的 `gridX × gridY` 网格切分。
+- 请求缺失 `sliceMode`、传 `null` 或空字符串时，`POST /api/editor/icon-spritesheets/generations` 与 `POST /api/external/v1/editor/icon-spritesheets/generations` 都必须在引用解析、定价、入队和任何 provider / OSS 副作用之前返回 `400`，错误体带 `field=sliceMode`，message 复述本节的决策要求；服务端不得用兜底模式继续执行，也不得为该字段保留默认值。
+- `grid` 必须同时提供 `gridX` 与 `gridY`（各 `1..32`，乘积不得超过当时生效的图集切片上限）；只提供其中一个、越界或乘积超限同样在副作用之前 `400`。
+- `connected-components` 不得同时携带 `gridX` / `gridY`：连通域切分不接受网格尺寸，二者同时出现时按请求自相矛盾在副作用之前返回 `400`（`field=gridX/gridY`），避免调用方以为网格已生效而实际按连通域执行。
+- 决策要求（服务端、客户端、Agent、工具说明和 Skill 必须一致）：只有在用户或需求明确要求等分网格、固定槽位或指定行列数时，才使用 `grid`，并把该行列数作为 `gridX` / `gridY` 传入；行列数必须来自用户或需求本身，不得由生成方自行假定，也不得用固定 `2×2` 表达“四类素材”。自由排布、数量不定或只要求“一张图集”时，显式传 `connected-components`；需要约束素材张数时使用 `sliceCount`，不得用网格参数表达张数。调用方、客户端和 Agent 都不得依赖、补齐或推断省略值。
+- 响应继续回显实际采用的 `sliceMode`，`grid` 时同时回显生效的 `gridX` / `gridY`。
+- 错误必须可执行：缺失、空白和未知取值统一返回 `400` 且带 `field=sliceMode`，`grid` 与网格参数的矛盾带 `field=gridX/gridY`，message 说明允许取值、缺参时该走哪条决策分支，以及 `sliceCount` 才是张数约束；不得只回报通用 JSON 解析错误。
+- `sliceCount` 只约束 `connected-components` 的目标张数，取值 `1..256`；识别结果与该目标不一致、为 `0` 或超过上限时返回 `422` 并回报实际识别数量，`grid` 不接受该字段。
+- 客户端的标准美术包（四类 canonical 素材）必须显式声明 `sliceMode=connected-components` 与 `sliceCount=4`：平台要么给出四张切片，要么以可执行的 `422` 说明实际识别数量；本地按用途位置映射前必须再次校验切片数量正好是四张，数量不符时失败关闭，禁止靠截断或补位写出用途错位的切片清单。
- 图标规范生成在 inline 模式下也必须先建立带稳定请求指纹的 generation operation，并由编辑器生成 durable billing 边界包住共享执行器；不得在 `operation=None` 时调用 provider 后再进入原子结果持久化。
- 图标 spritesheet 的入队与实际执行路径都必须在引用解析、generation input 重建、定价和 provider / OSS 副作用之前预检 owner、项目和最终素材目录，并将返回的 canonical `projectId + assetFolderId` 回写到后续流程；请求省略目录时按实际写入的 owner 默认目录预检，worker 不得只信任入队时的旧校验结果。
- queued 图标规范生成由共享原子结果持久化使用 worker caller 中的 lease 一并完成任务并清理 lease；共享执行器返回成功后 worker 只能返回 `Ok(())`，不得再次调用 job completion。
@@ -89,7 +97,7 @@
- 透明背景处理正常成功时，父流程把带背景原图和经完整解码 / 尺寸守卫验证的透明 spritesheet 写入 OSS、项目资源和账号素材库，再识别 alpha 连通域并执行附加拆分。BgFilter 最终失败或后续 Alpha / 尺寸恢复、原图回读、透明图完整解码失败、但 provider 原图已经持久化时，任务以 `completed + warning` 收口，只把 provider 原图作为唯一主图放入画布，不创建透明图集，也不继续拆分，`iconImageSrcs=[]`、`sliceWarning=null`。该收口不捕获 phase 上报、provider 原图持久化或 `canvasCompletion` 写回错误；provider 原图本身解码失败时在首次持久化前失败，不允许用 `512×512` 伪造元数据。
- 自动拆分只在透明图集成功后执行，属于 best-effort 附加动作，不参与图集生成的成功判定。连通域识别或切片持久化失败时，接口仍返回并回填整张透明图集，`iconImageSrcs=[]`，并通过 `sliceWarning.code/reason` 暴露非阻断原因；`sliceWarning` 与透明背景最终失败使用的通用 `warning` 互斥，因为透明背景失败时不会进入拆分，但可与风格归一化或像素规整产生的通用 `warning` 并存。前者只表示透明图集成功但自动拆分失败，`sliceWarning.reason` 原始契约保持不变。前端在 inline、worker 队列完成和刷新恢复三条路径统一显示对应 warning toast，用户可在图集工具栏手动重试。
- 响应通过 `iconImageSrcs` 返回成功切片素材。图标自动拆分、手动 `拆分图集` 和 UI 提取复用同一个 bounded CPU helper 和 platform 实现：全部原始连通域（包括随后过滤的噪点）最多 `4096` 个，辅助部件通过 `64px` 空间网格只检查最大 `48px` 邻域候选；有效输出按视觉阅读顺序命名为 `素材 N`。
-- 三条拆分路径共同限制单边最多 `4096` 像素、总像素最多 `2048×2048`、最多 `64` 个输出；输出限制在排序、裁剪和 PNG 编码前检查。整段图片 CPU 工作在 2 路 semaphore、30 秒本地上限与请求 deadline 共同保护的 `spawn_blocking` 中执行，permit 由 blocking 闭包持有。自动拆分超限以稳定 `sliceWarning` 非阻断降级且不产生切片 PUT、资源或画布切片；手动拆分超限在首次持久化前返回 `422`。
+- 三条拆分路径共同限制单边最多 `4096` 像素、总像素最多 `2048×2048`、最多 `256` 个输出；输出上限与 `grid` 的 `gridX × gridY` 上限、`sliceCount` 上限取同一个值，并在排序、裁剪和 PNG 编码前检查。整段图片 CPU 工作在 2 路 semaphore、30 秒本地上限与请求 deadline 共同保护的 `spawn_blocking` 中执行，permit 由 blocking 闭包持有。自动拆分超限以稳定 `sliceWarning` 非阻断降级且不产生切片 PUT、资源或画布切片；手动拆分超限在首次持久化前返回 `422`。
## 前端铺放规则
@@ -110,3 +118,4 @@
- 选中透明图集图层时显示 `拆分图集`；点击后源图集显示扫描蒙层与 `拆图中` 状态，工具栏按钮同步切换为旋转图标和 `拆图中` 并禁用重复提交。完成后恢复工具栏，不新增第二张图集，只在 provider 原图右侧追加自动识别的独立素材，并同步写入素材库。
- 把同源派生图层从其它标签改为“图集”时，在项目资源返回新 `resourceId` 前“拆分图集”保持禁用；持久化成功后拆分请求必须指向 `assetKind: "icon-spritesheet"` 的新资源，失败时标签回滚且不发起拆分请求。
- 生成图标素材的提交体不包含 `priceMudPoints`；后端必须按归一化后的模型和尺寸计算价格，不信任客户端声明。queue 任务的计费、退款和结果投影使用入队时冻结的同一价格。
+- 图集生成请求省略 `sliceMode`（或显式传 `null` / 空字符串）时返回 `400` 且 `field=sliceMode`，不产生定价、入队、扣费、provider 调用或 OSS 写入；`sliceMode=connected-components` 同时携带 `gridX`/`gridY` 时同样在副作用之前 `400`；`grid` 缺任一维度时 `400`。响应回显的 `sliceMode` 必须与请求声明一致。
diff --git a/jenkins/Jenkinsfile.ai-game-creator-shell-build b/jenkins/Jenkinsfile.ai-game-creator-shell-build
index 3e304cf63..8ac2484e2 100644
--- a/jenkins/Jenkinsfile.ai-game-creator-shell-build
+++ b/jenkins/Jenkinsfile.ai-game-creator-shell-build
@@ -21,8 +21,10 @@ pipeline {
parameters {
string(name: 'SOURCE_BRANCH', defaultValue: 'master', description: '源码分支')
string(name: 'COMMIT_HASH', defaultValue: '', description: '可选，指定属于 SOURCE_BRANCH 的 Git commit')
- string(name: 'AGC_RELEASE_VERSION', defaultValue: '', description: '可选，指定三段版本号；留空则按 OSS 与本地版本自动递增 patch')
- text(name: 'AGC_UPDATE_RELEASE_NOTES', defaultValue: '', description: '可选，支持多行文本，写入 latest.json 的发布说明')
+ string(name: 'AGC_RELEASE_VERSION', defaultValue: '', description: '可选，指定三段版本号；留空则按该渠道 OSS 与本地版本自动递增 patch')
+ choice(name: 'AGC_UPDATE_CHANNEL', choices: ['dev-win', 'dev-mac'], description: 'AGC 发布渠道；dev-win 在 Windows 节点执行，dev-mac 需在 macOS 构建机本地执行')
+ booleanParam(name: 'AGC_RELEASE_DRY_RUN', defaultValue: false, description: '勾选后只构建并打印将要执行的上传命令，不写入 OSS')
+ text(name: 'AGC_UPDATE_RELEASE_NOTES', defaultValue: '', description: '可选，支持多行文本，写入渠道清单的发布说明')
string(name: 'OSSUTIL_BIN', defaultValue: 'ossutil', description: 'ossutil 或 ossutil.exe 的绝对路径/命令名')
}
@@ -123,11 +125,15 @@ pipeline {
withCredentials([
string(credentialsId: 'AliyunAccessKeyId', variable: 'AGC_OSS_ACCESS_KEY_ID'),
string(credentialsId: 'AliyunaccessKeySecret', variable: 'AGC_OSS_ACCESS_KEY_SECRET'),
+ string(credentialsId: 'AgcUpdaterSigningKey', variable: 'TAURI_SIGNING_PRIVATE_KEY'),
+ string(credentialsId: 'AgcUpdaterSigningKeyPassword', variable: 'TAURI_SIGNING_PRIVATE_KEY_PASSWORD'),
]) {
withEnv([
"PATH=${env.AGC_WINDOWS_PATH}",
"OSSUTIL_BIN=${params.OSSUTIL_BIN}",
"AGC_RELEASE_VERSION=${params.AGC_RELEASE_VERSION}",
+ "AGC_UPDATE_CHANNEL=${params.AGC_UPDATE_CHANNEL}",
+ "AGC_RELEASE_DRY_RUN=${params.AGC_RELEASE_DRY_RUN ? '1' : '0'}",
"AGC_UPDATE_RELEASE_NOTES=${params.AGC_UPDATE_RELEASE_NOTES}",
]) {
powershell '''
@@ -153,14 +159,16 @@ pipeline {
stage('Archive release') {
steps {
- archiveArtifacts artifacts: 'apps/ai-game-creator-shell/src-tauri/target/x86_64-pc-windows-msvc/release/bundle/**/*.exe,apps/ai-game-creator-shell/src-tauri/target/x86_64-pc-windows-msvc/release/bundle/latest.json,.jenkins-source-commit', fingerprint: true
+ archiveArtifacts artifacts: 'apps/ai-game-creator-shell/src-tauri/target/x86_64-pc-windows-msvc/release/bundle/**/*.exe,apps/ai-game-creator-shell/src-tauri/target/x86_64-pc-windows-msvc/release/bundle/**/*.sig,apps/ai-game-creator-shell/src-tauri/target/x86_64-pc-windows-msvc/release/bundle/latest.json,apps/ai-game-creator-shell/src-tauri/target/x86_64-pc-windows-msvc/release/bundle/legacy-latest.json,.jenkins-source-commit', fingerprint: true
}
}
}
post {
success {
- echo 'AGC Windows x64 安装包已构建并上传 OSS。'
+ echo params.AGC_RELEASE_DRY_RUN
+ ? "AGC ${params.AGC_UPDATE_CHANNEL} 渠道演练完成：已构建并生成清单，未写入 OSS。"
+ : "AGC ${params.AGC_UPDATE_CHANNEL} 渠道安装包、签名与渠道清单已构建并上传 OSS。"
}
}
}
diff --git a/package-lock.json b/package-lock.json
index 54339f53d..ccb4be9ec 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -108,6 +108,7 @@
"@tauri-apps/plugin-dialog": "^2.7.2",
"@tauri-apps/plugin-http": "^2.5.9",
"@tauri-apps/plugin-opener": "~2",
+ "@tauri-apps/plugin-updater": "2.11.0",
"@vitejs/plugin-react": "^5.0.4",
"focus-trap-react": "^12.0.3",
"lexical": "^0.47.0",
@@ -118,6 +119,7 @@
"react-colorful": "^5.8.0",
"react-dom": "^19.0.0",
"react-markdown": "^10.1.0",
+ "react-window": "^1.8.11",
"rehype-highlight": "^7.0.2",
"remark-gfm": "^4.0.1",
"vite": "^6.2.0",
@@ -131,6 +133,7 @@
"@testing-library/user-event": "^14.6.1",
"@types/react": "^19.2.14",
"@types/react-dom": "^19.2.3",
+ "@types/react-window": "^1.8.8",
"tailwindcss": "^4.1.14",
"typescript": "~5.8.2",
"vitest": "^0.34.6"
@@ -8091,6 +8094,15 @@
"@tauri-apps/api": "^2.11.0"
}
},
+ "node_modules/@tauri-apps/plugin-updater": {
+ "version": "2.11.0",
+ "resolved": "https://registry.npmjs.org/@tauri-apps/plugin-updater/-/plugin-updater-2.11.0.tgz",
+ "integrity": "sha512-AE36XkOoSna24G40jZMY15nzAnkXEPL/73tGoseGrtGOHuI/cZwWzHpZFLjKXDPgzYZ435z1gHu28LgrsBwIxQ==",
+ "license": "MIT OR Apache-2.0",
+ "dependencies": {
+ "@tauri-apps/api": "^2.11.0"
+ }
+ },
"node_modules/@testing-library/dom": {
"version": "10.4.1",
"resolved": "https://registry.npmjs.org/@testing-library/dom/-/dom-10.4.1.tgz",
@@ -8421,6 +8433,16 @@
"@types/react": "^19.2.0"
}
},
+ "node_modules/@types/react-window": {
+ "version": "1.8.8",
+ "resolved": "https://registry.npmjs.org/@types/react-window/-/react-window-1.8.8.tgz",
+ "integrity": "sha512-8Ls660bHR1AUA2kuRvVG9D/4XpRC6wjAaPT9dil7Ckc76eP9TKWZwwmgfq8Q1LANX3QNDnoU4Zp48A3w+zK69Q==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "@types/react": "*"
+ }
+ },
"node_modules/@types/semver": {
"version": "7.7.1",
"resolved": "https://registry.npmjs.org/@types/semver/-/semver-7.7.1.tgz",
@@ -26447,10 +26469,12 @@
"@tauri-apps/plugin-dialog": "^2.7.2",
"@tauri-apps/plugin-http": "^2.5.9",
"@tauri-apps/plugin-opener": "~2",
+ "@tauri-apps/plugin-updater": "2.11.0",
"@testing-library/react": "^16.3.2",
"@testing-library/user-event": "^14.6.1",
"@types/react": "^19.2.14",
"@types/react-dom": "^19.2.3",
+ "@types/react-window": "^1.8.8",
"@vitejs/plugin-react": "^5.0.4",
"focus-trap-react": "^12.0.3",
"lexical": "^0.47.0",
@@ -26461,6 +26485,7 @@
"react-colorful": "^5.8.0",
"react-dom": "^19.0.0",
"react-markdown": "^10.1.0",
+ "react-window": "^1.8.11",
"rehype-highlight": "^7.0.2",
"remark-gfm": "^4.0.1",
"tailwindcss": "^4.1.14",
@@ -28212,6 +28237,14 @@
"@tauri-apps/api": "^2.11.0"
}
},
+ "@tauri-apps/plugin-updater": {
+ "version": "2.11.0",
+ "resolved": "https://registry.npmjs.org/@tauri-apps/plugin-updater/-/plugin-updater-2.11.0.tgz",
+ "integrity": "sha512-AE36XkOoSna24G40jZMY15nzAnkXEPL/73tGoseGrtGOHuI/cZwWzHpZFLjKXDPgzYZ435z1gHu28LgrsBwIxQ==",
+ "requires": {
+ "@tauri-apps/api": "^2.11.0"
+ }
+ },
"@testing-library/dom": {
"version": "10.4.1",
"resolved": "https://registry.npmjs.org/@testing-library/dom/-/dom-10.4.1.tgz",
@@ -28483,6 +28516,15 @@
"peer": true,
"requires": {}
},
+ "@types/react-window": {
+ "version": "1.8.8",
+ "resolved": "https://registry.npmjs.org/@types/react-window/-/react-window-1.8.8.tgz",
+ "integrity": "sha512-8Ls660bHR1AUA2kuRvVG9D/4XpRC6wjAaPT9dil7Ckc76eP9TKWZwwmgfq8Q1LANX3QNDnoU4Zp48A3w+zK69Q==",
+ "dev": true,
+ "requires": {
+ "@types/react": "*"
+ }
+ },
"@types/semver": {
"version": "7.7.1",
"resolved": "https://registry.npmjs.org/@types/semver/-/semver-7.7.1.tgz",
diff --git a/scripts/agc-template-library-publish.mjs b/scripts/agc-template-library-publish.mjs
new file mode 100644
index 000000000..aa0281caa
--- /dev/null
+++ b/scripts/agc-template-library-publish.mjs
@@ -0,0 +1,522 @@
+#!/usr/bin/env node
+/**
+ * 打包并发布 AGC 模板库到 OSS。
+ *
+ * 用法：
+ * node scripts/agc-template-library-publish.mjs --source