{appUpdateCheckEnabled ?
+
-
+
- 陶泥儿
+ {APP_NAME}
GameAgent
diff --git a/apps/ai-game-creator-shell/src/components/modal/ThemedModal.tsx b/apps/ai-game-creator-shell/src/components/modal/ThemedModal.tsx
index 67af6cfbc..ec75bfca4 100644
--- a/apps/ai-game-creator-shell/src/components/modal/ThemedModal.tsx
+++ b/apps/ai-game-creator-shell/src/components/modal/ThemedModal.tsx
@@ -4,6 +4,23 @@ import { createPortal } from 'react-dom';
type ThemedModalTheme = 'light' | 'dark';
+/**
+ * 自绘标题栏的标记：它是窗口边框，不属于模态内容。
+ *
+ * focus-trap 默认会拦下模态之外的所有点击（`click` 事件在 document 捕获阶段直接
+ * `stopImmediatePropagation`），所以任何弹窗打开时「最小化 / 最大化 / 关闭」和标题栏
+ * 拖拽都会静默失效。这里只对落在标题栏内的目标放行；页面内容仍然由遮罩和焦点陷阱
+ * 挡在模态之外，点空白处不会误触底层界面。
+ */
+const WINDOW_CHROME_BAR_SELECTOR = '[data-window-chrome-bar]';
+
+function isWindowChromeBarTarget(target: EventTarget | null) {
+ return (
+ target instanceof Element &&
+ target.closest(WINDOW_CHROME_BAR_SELECTOR) !== null
+ );
+}
+
export type ThemedModalProps = {
open: boolean;
ariaLabel: string;
@@ -55,6 +72,7 @@ export function ThemedModal({
escapeDeactivates: false,
fallbackFocus: () => panelRef.current!,
returnFocusOnDeactivate: true,
+ allowOutsideClick: (event) => isWindowChromeBarTarget(event.target),
}}
>
([]);
+ const historyIdsRef = useRef(new Set());
+ const [replies, setReplies] = useState([]);
+ const publish = useCallback((next: DesignReplyAnimation[]) => {
+ entriesRef.current = next;
+ setReplies(next);
+ }, []);
+
+ const reset = useCallback(
+ (historyIds: string[] = []) => {
+ historyIdsRef.current = new Set(historyIds);
+ publish([]);
+ },
+ [publish],
+ );
+
+ const receiveText = useCallback(
+ (messageId: string, target: string) => {
+ if (historyIdsRef.current.has(messageId)) return;
+ const previous = entriesRef.current.find(
+ (entry) => entry.messageId === messageId,
+ );
+ // 空文本是同一 Provider 请求的 attempt 重置，不能清掉正式回复。
+ if (previous?.persisted) return;
+ const next = {
+ messageId,
+ target,
+ visible: target.startsWith(previous?.visible ?? '')
+ ? (previous?.visible ?? '')
+ : '',
+ persisted: false,
+ };
+ publish(
+ previous
+ ? entriesRef.current.map((entry) =>
+ entry.messageId === messageId ? next : entry,
+ )
+ : [...entriesRef.current, next],
+ );
+ },
+ [publish],
+ );
+
+ const receiveView = useCallback(
+ (view: DesignView) => {
+ let next = [...entriesRef.current];
+ for (const message of view.messages) {
+ if (
+ message.role !== 'assistant' ||
+ historyIdsRef.current.has(message.id)
+ )
+ continue;
+ const index = next.findIndex((entry) => entry.messageId === message.id);
+ const previous = next[index];
+ const entry = {
+ messageId: message.id,
+ target: message.text,
+ visible: message.text.startsWith(previous?.visible ?? '')
+ ? (previous?.visible ?? '')
+ : '',
+ persisted: true,
+ };
+ if (index < 0) next.push(entry);
+ else next[index] = entry;
+ }
+ if (!view.running) {
+ const persistedIds = new Set(
+ view.messages.map((message) => message.id),
+ );
+ next = next.filter((entry) => persistedIds.has(entry.messageId));
+ }
+ publish(next);
+ },
+ [publish],
+ );
+
+ const discardUnpersisted = useCallback(() => {
+ publish(entriesRef.current.filter((entry) => entry.persisted));
+ }, [publish]);
+
+ useEffect(() => {
+ const timer = window.setInterval(() => {
+ let changed = false;
+ const next = entriesRef.current.map((entry) => {
+ const remaining = entry.target.length - entry.visible.length;
+ if (remaining <= 0) return entry;
+ changed = true;
+ const step = remaining > 160 ? 4 : remaining > 48 ? 2 : 1;
+ return {
+ ...entry,
+ visible: entry.target.slice(0, entry.visible.length + step),
+ };
+ });
+ if (changed) publish(next);
+ }, 50);
+ return () => window.clearInterval(timer);
+ }, [publish]);
+
+ return { replies, reset, receiveText, receiveView, discardUnpersisted };
+}
diff --git a/apps/ai-game-creator-shell/tests/WindowChrome.test.tsx b/apps/ai-game-creator-shell/tests/WindowChrome.test.tsx
index 33fc94965..72b8169eb 100644
--- a/apps/ai-game-creator-shell/tests/WindowChrome.test.tsx
+++ b/apps/ai-game-creator-shell/tests/WindowChrome.test.tsx
@@ -2,12 +2,26 @@
import { fireEvent, render, screen } from '@testing-library/react';
import userEvent from '@testing-library/user-event';
-import { describe, expect, it } from 'vitest';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { APP_NAME } from '../src/app/appMetadata';
import type { GameCreatorDirectActiveTurn } from '../src/app/types';
+import { ThemedModal } from '../src/components/modal/ThemedModal';
import { WindowChrome } from '../src/components/WindowChrome';
import { useWindowChrome } from '../src/components/windowChromeContext';
+const nativeWindow = vi.hoisted(() => ({
+ minimize: vi.fn(),
+ toggleMaximize: vi.fn(),
+ isMaximized: vi.fn(),
+ close: vi.fn(),
+ label: 'client',
+}));
+
+vi.mock('@tauri-apps/api/window', () => ({
+ getCurrentWindow: () => nativeWindow,
+}));
+
function TitleSetter({ value }: { value: string }) {
const { setTitle } = useWindowChrome();
return (
@@ -36,6 +50,14 @@ function ActiveRunsSetter({
}
describe('WindowChrome', () => {
+ beforeEach(() => {
+ nativeWindow.minimize.mockReset();
+ nativeWindow.toggleMaximize.mockReset();
+ nativeWindow.isMaximized.mockReset();
+ nativeWindow.close.mockReset();
+ delete (window as unknown as Record).__TAURI_INTERNALS__;
+ });
+
it('renders the陶泥儿 brand, default title, and controls', async () => {
const user = userEvent.setup();
render(
@@ -45,7 +67,7 @@ describe('WindowChrome', () => {
);
expect(screen.getByRole('banner', { name: '窗口标题栏' })).toBeTruthy();
- expect(screen.getByLabelText('陶泥儿 GameAgent')).toBeTruthy();
+ expect(screen.getByLabelText(`${APP_NAME} GameAgent`)).toBeTruthy();
expect(screen.queryByLabelText('本地工作区')).toBeNull();
expect(screen.getByText('创作工作台')).toBeTruthy();
expect(screen.getByText('工作区内容')).toBeTruthy();
@@ -141,4 +163,35 @@ describe('WindowChrome', () => {
);
expect(screen.getAllByRole('menuitem')).toHaveLength(2);
});
+
+ /**
+ * 回归：发布面板等 ThemedModal 弹窗打开时，标题栏在模态之外，焦点陷阱曾把
+ * 标题栏上的点击一起拦下 —— 三个窗口按钮看着正常但点不动。
+ */
+ it('keeps the window controls working while a modal covers the workspace', async () => {
+ const user = userEvent.setup();
+ nativeWindow.minimize.mockResolvedValue(undefined);
+ nativeWindow.toggleMaximize.mockResolvedValue(undefined);
+ nativeWindow.close.mockResolvedValue(undefined);
+ nativeWindow.isMaximized.mockResolvedValue(false);
+ (window as unknown as Record).__TAURI_INTERNALS__ = {};
+
+ render(
+
+ undefined} ariaLabel="测试弹窗">
+
+
+ ,
+ );
+ await screen.findByRole('dialog', { name: '测试弹窗' });
+
+ await user.click(screen.getByRole('button', { name: '最小化' }));
+ expect(nativeWindow.minimize).toHaveBeenCalledTimes(1);
+
+ await user.click(screen.getByRole('button', { name: '最大化' }));
+ expect(nativeWindow.toggleMaximize).toHaveBeenCalledTimes(1);
+
+ await user.click(screen.getByRole('button', { name: '关闭' }));
+ expect(nativeWindow.close).toHaveBeenCalledTimes(1);
+ });
});
diff --git a/apps/ai-game-creator-shell/tests/appSurface/design-agent.suite.ts b/apps/ai-game-creator-shell/tests/appSurface/design-agent.suite.ts
index 79f1e49b7..71baf3f5b 100644
--- a/apps/ai-game-creator-shell/tests/appSurface/design-agent.suite.ts
+++ b/apps/ai-game-creator-shell/tests/appSurface/design-agent.suite.ts
@@ -405,11 +405,159 @@ export function registerDesignAgentSurfaceTests() {
);
});
+ it('keeps one Design Agent reply when repeated completion arrives after typing catches up', async () => {
+ const harness = createProjectChatRuntimeHarness({
+ designAgentView: designConversationView(),
+ });
+ const originalInvoke = harness.invoke.getMockImplementation()!;
+ let finish!: (view: unknown) => void;
+ harness.invoke.mockImplementation((command, args) =>
+ command === 'continue_design_agent_session'
+ ? new Promise((resolve) => {
+ finish = resolve;
+ })
+ : originalInvoke(command, args),
+ );
+ renderDesignAgent(harness);
+ const input = await screen.findByLabelText('项目需求');
+ await expectDesignModelReady();
+ await setComposerText(input, '只回复 pong');
+ fireEvent.submit(input.closest('form') as HTMLFormElement);
+ await waitFor(() => expect(finish).toBeDefined());
+ const call = harness.invoke.mock.calls.find(
+ ([command]) => command === 'continue_design_agent_session',
+ )!;
+ const clientTurnId = String(
+ (call[1] as { clientTurnId: string }).clientTurnId,
+ );
+ const messageId = `${clientTurnId}:response:0`;
+ const view = {
+ ...designConversationView(),
+ messages: [{ id: messageId, role: 'assistant', text: 'pong' }],
+ };
+ const emit = (payload: Record) =>
+ harness.emitDesignAgentEvent({
+ projectPath: harness.projectPath,
+ clientTurnId,
+ ...payload,
+ });
+ act(() => emit({ kind: 'text', messageId, text: 'pong' }));
+ await screen.findByText('pong');
+ act(() => emit({ kind: 'state', view }));
+ act(() => emit({ kind: 'state', view }));
+ await act(async () => {
+ await new Promise((resolve) => setTimeout(resolve, 100));
+ });
+ expect(screen.getAllByText('pong')).toHaveLength(1);
+ expect(screen.queryByLabelText('策划 Agent 实时回复')).toBeNull();
+ await act(async () => finish(view));
+ expect(screen.getAllByText('pong')).toHaveLength(1);
+ expect(
+ harness.invoke.mock.calls.filter(
+ ([command]) => command === 'continue_design_agent_session',
+ ),
+ ).toHaveLength(1);
+ });
+
+ for (const firstDelivery of ['event', 'command'] as const) {
+ it(`animates a whole Design Agent reply once when ${firstDelivery} completes first`, async () => {
+ const history = { id: 'history', role: 'assistant', text: '历史回复' };
+ const harness = createProjectChatRuntimeHarness({
+ designAgentView: { ...designConversationView(), messages: [history] },
+ });
+ const originalInvoke = harness.invoke.getMockImplementation()!;
+ const requests: {
+ clientTurnId: string;
+ finish: (view: unknown) => void;
+ }[] = [];
+ harness.invoke.mockImplementation((command, args) =>
+ command === 'continue_design_agent_session'
+ ? new Promise((resolve) => {
+ requests.push({
+ clientTurnId: String(args?.clientTurnId),
+ finish: resolve,
+ });
+ })
+ : originalInvoke(command, args),
+ );
+ renderDesignAgent(harness);
+ await screen.findByText(history.text);
+ await expectDesignModelReady();
+ const input = screen.getByLabelText('项目需求');
+ await setComposerText(input, '继续');
+ fireEvent.submit(input.closest('form')!);
+ await waitFor(() => expect(requests).toHaveLength(1));
+ const request = requests[0];
+ const messageId = `${request.clientTurnId}:response:0`;
+ const reply = '整块返回也逐步显示';
+ const terminal = {
+ ...designConversationView(),
+ messages: [history, { id: messageId, role: 'assistant', text: reply }],
+ };
+ const emit = (payload: Record) =>
+ harness.emitDesignAgentEvent({
+ projectPath: harness.projectPath,
+ clientTurnId: request.clientTurnId,
+ ...payload,
+ });
+ if (firstDelivery === 'event')
+ act(() => emit({ kind: 'state', view: terminal }));
+ else await act(async () => request.finish(terminal));
+ const bubble = screen.getByLabelText('策划 Agent 实时回复');
+ expect(bubble.textContent).not.toBe(reply);
+ expect(screen.getAllByText(history.text)).toHaveLength(1);
+ expect(
+ screen.getByRole('button', { name: '发送' }).hasAttribute('disabled'),
+ ).toBe(false);
+ await act(async () => {
+ await new Promise((resolve) => setTimeout(resolve, 100));
+ });
+ const prefix = bubble.textContent;
+ expect(prefix?.length).toBeGreaterThan(0);
+ act(() => {
+ emit({ kind: 'state', view: terminal });
+ emit({ kind: 'state', view: terminal });
+ emit({ kind: 'text', messageId, text: '' });
+ });
+ expect(bubble.textContent).toBe(prefix);
+ await screen.findByText(reply);
+ expect(screen.getByText(reply).closest('.message')).toBe(bubble);
+ expect(
+ document.querySelectorAll(`[data-message-id="${messageId}"]`),
+ ).toHaveLength(1);
+ expect(screen.queryByLabelText('策划 Agent 实时回复')).toBeNull();
+
+ // 用户可在旧 invoke 尚未返回时开始下一轮；旧 finally 不能解锁新回合。
+ await setComposerText(input, '下一轮');
+ fireEvent.submit(input.closest('form')!);
+ await waitFor(() => expect(requests).toHaveLength(2));
+ act(() => {
+ emit({ kind: 'text', messageId: 'stale', text: '迟到旧回复' });
+ emit({ kind: 'state', view: terminal });
+ });
+ await act(async () => request.finish(terminal));
+ expect(
+ screen.getByRole('button', { name: '思考中' }).hasAttribute('disabled'),
+ ).toBe(true);
+ expect(screen.queryByText('迟到旧回复')).toBeNull();
+ await act(async () => requests[1].finish(terminal));
+ });
+ }
+
it('follows streamed Design Agent content until the user scrolls up', async () => {
const harness = createProjectChatRuntimeHarness({
designAgentView: designConversationView(),
designAgentContinueView: designConversationView(),
});
+ const originalInvoke = harness.invoke.getMockImplementation()!;
+ let finish!: () => void;
+ const gate = new Promise((resolve) => {
+ finish = resolve;
+ });
+ harness.invoke.mockImplementation(async (command, args) => {
+ if (command === 'continue_design_agent_session') await gate;
+ return originalInvoke(command, args);
+ });
renderDesignAgent(harness);
const input = await screen.findByLabelText('项目需求');
@@ -459,11 +607,26 @@ export function registerDesignAgentSurfaceTests() {
projectPath: harness.projectPath,
clientTurnId,
kind: 'text',
+ messageId: `${clientTurnId}:response:0`,
text: '正在补充关卡节奏',
}),
);
await screen.findByLabelText('策划 Agent 实时回复');
await waitFor(() => expect(messageList.scrollTop).toBe(1000));
+ const replyBeforeTool = screen.getByLabelText('策划 Agent 实时回复');
+ const prefixBeforeTool = replyBeforeTool.textContent;
+ act(() =>
+ harness.emitDesignAgentEvent({
+ projectPath: harness.projectPath,
+ clientTurnId,
+ kind: 'tool',
+ text: '正在读取方案文件',
+ }),
+ );
+ expect(screen.getByLabelText('策划 Agent 工具状态').textContent).toBe(
+ '正在读取方案文件',
+ );
+ expect(replyBeforeTool.textContent).toBe(prefixBeforeTool);
messageList.scrollTop = 120;
fireEvent.scroll(messageList);
@@ -478,6 +641,7 @@ export function registerDesignAgentSurfaceTests() {
projectPath: harness.projectPath,
clientTurnId,
kind: 'text',
+ messageId: `${clientTurnId}:response:0`,
text: '正在补充关卡节奏与多人规则',
});
});
@@ -488,6 +652,7 @@ export function registerDesignAgentSurfaceTests() {
).toContain('多人规则'),
);
expect(messageList.scrollTop).toBe(120);
+ await act(async () => finish());
});
it('shows only known optimistic send times and does not invent persisted times', async () => {
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 9d8c95fb5..95cbf2b10 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
@@ -1,6 +1,6 @@
import fs from 'node:fs';
-import { APP_VERSION } from '../../src/app/appMetadata';
+import { APP_NAME, APP_VERSION } from '../../src/app/appMetadata';
import { repoPath } from '../repoPath';
import {
act,
@@ -348,7 +348,7 @@ export function registerRuntimeSettingsTests() {
fireEvent.click(screen.getByRole('button', { name: /关于/ }));
- expect(screen.getByText('Genarrative AI Game Creator')).not.toBeNull();
+ expect(screen.getByText(APP_NAME)).not.toBeNull();
expect(
screen.getByTestId('runtime-settings-app-logo').getAttribute('src'),
).toContain('taonier-product-ip.png');
diff --git a/apps/ai-game-creator-shell/tests/designReplyAnimation.test.tsx b/apps/ai-game-creator-shell/tests/designReplyAnimation.test.tsx
new file mode 100644
index 000000000..e51bb4fb3
--- /dev/null
+++ b/apps/ai-game-creator-shell/tests/designReplyAnimation.test.tsx
@@ -0,0 +1,99 @@
+// @vitest-environment jsdom
+import { act, cleanup, renderHook } from '@testing-library/react';
+import { afterEach, beforeEach, expect, it, vi } from 'vitest';
+
+import type { DesignView } from '../src/app/types';
+import { useDesignReplyAnimation } from '../src/view/project-development/planning/useDesignReplyAnimation';
+
+beforeEach(() => vi.useFakeTimers());
+afterEach(() => {
+ cleanup();
+ vi.useRealTimers();
+});
+
+function view(messages: DesignView['messages'], running = false): DesignView {
+ return {
+ session: {
+ sessionId: 's',
+ projectId: 'p',
+ currentPhase: 'concept',
+ approvedPhases: [],
+ pendingApproval: null,
+ pendingClarification: null,
+ turnIndex: 1,
+ lastError: null,
+ },
+ messages,
+ running,
+ canRetry: false,
+ };
+}
+
+it('keeps each reply progress across tool snapshots and repeated completion', () => {
+ const { result } = renderHook(useDesignReplyAnimation);
+ const history = { id: 'history', role: 'assistant', text: '历史' };
+ const first = { id: 't:response:0', role: 'assistant', text: '第一条回复' };
+ const second = { id: 't:response:1', role: 'assistant', text: '第二条回复' };
+ act(() => {
+ result.current.reset([history.id]);
+ result.current.receiveText(first.id, first.text);
+ vi.advanceTimersByTime(100);
+ });
+ expect(result.current.replies[0].visible).toBe('第一');
+ act(() =>
+ result.current.receiveView(
+ view(
+ [history, first, { id: 'tool', role: 'tool', text: '工具已完成' }],
+ true,
+ ),
+ ),
+ );
+ expect(result.current.replies).toHaveLength(1);
+ expect(result.current.replies[0].visible).toBe('第一');
+ act(() => result.current.receiveText(second.id, second.text));
+ const terminal = view([history, first, second]);
+ act(() => {
+ result.current.receiveView(terminal);
+ result.current.receiveView(terminal);
+ });
+ expect(result.current.replies.map((reply) => reply.visible)).toEqual([
+ '第一',
+ '',
+ ]);
+ act(() => vi.advanceTimersByTime(500));
+ act(() => result.current.receiveView(terminal));
+ expect(result.current.replies.map((reply) => reply.visible)).toEqual([
+ first.text,
+ second.text,
+ ]);
+});
+
+it('resets only an unpersisted retry attempt and discards failed partial output', () => {
+ const { result } = renderHook(useDesignReplyAnimation);
+ act(() => {
+ result.current.receiveText('t:response:0', '尝试失败');
+ vi.advanceTimersByTime(100);
+ });
+ expect(result.current.replies[0].visible).toBe('尝试');
+ act(() => result.current.receiveText('t:response:0', ''));
+ expect(result.current.replies[0].visible).toBe('');
+ const saved = { id: 't:response:0', role: 'assistant', text: '成功' };
+ act(() => {
+ result.current.receiveText(saved.id, saved.text);
+ result.current.receiveView(view([saved], true));
+ vi.advanceTimersByTime(100);
+ result.current.receiveText(saved.id, '');
+ result.current.receiveText('t:response:1', '未被接受的文本');
+ result.current.receiveView(view([saved]));
+ });
+ expect(result.current.replies).toEqual([
+ { messageId: saved.id, target: '成功', visible: '成功', persisted: true },
+ ]);
+ act(() => {
+ result.current.receiveText('t:response:2', '连接中断');
+ result.current.discardUnpersisted();
+ });
+ expect(result.current.replies).toHaveLength(1);
+ act(() => result.current.reset([saved.id]));
+ expect(result.current.replies).toEqual([]);
+});
diff --git a/apps/ai-game-creator-shell/tests/gameDistributionPublish.test.ts b/apps/ai-game-creator-shell/tests/gameDistributionPublish.test.ts
index 9110172ea..e4aa8e332 100644
--- a/apps/ai-game-creator-shell/tests/gameDistributionPublish.test.ts
+++ b/apps/ai-game-creator-shell/tests/gameDistributionPublish.test.ts
@@ -14,6 +14,12 @@ vi.mock('../src/services/errorReporting', () => ({
captureClientError: vi.fn(),
}));
+// 原生侧上传需要登录凭据；这里只钉住「取到了 token」这一件事。
+vi.mock('../src/services/clientApi', async (importOriginal) => ({
+ ...(await importOriginal()),
+ getStoredAuthAccessToken: () => 'test-access-token',
+}));
+
import type { GameCreationAppManifest } from '../../../packages/shared/src/contracts/gameCreationApp';
import {
generateGameDistributionCover,
@@ -29,6 +35,14 @@ const MANIFEST = {
goal: '守住轨道城',
} as unknown as GameCreationAppManifest;
+/** 归一化发行包的暂存摘要；发布链路只应传递它，不再传整包字节。 */
+const STAGED_PACKAGE = {
+ stagingPath: 'C:/app-data/game-package-staging/aaaa.zip',
+ packageSha256: 'a'.repeat(64),
+ packageSizeBytes: 1024,
+ packageFileCount: 1,
+};
+
function jsonResponse(payload: unknown) {
return new Response(
JSON.stringify({
@@ -66,23 +80,25 @@ test('发布时携带本地项目标识，让重复发布复用同一个平台
status: 'awaiting_upload',
}),
)
- .mockResolvedValueOnce(
- jsonResponse({ versionId: 'gamever_1', status: 'uploaded' }),
- )
.mockResolvedValueOnce(
jsonResponse({ version: { status: 'pending_review' } }),
);
+ const invokeCalls: Array<{ command: string; args: unknown }> = [];
const result = await publishLocalProjectGame({
- invoke: (async (command: string) => {
- expect(command).toBe('read_local_project_export_package');
- return {
- packageRelativePath: 'exports/playtest-package-1.zip',
- packageBytes: [1, 2, 3],
- packageSha256: 'a'.repeat(64),
- packageSizeBytes: 3,
- files: [{ path: 'index.html', sizeBytes: 3, sha256: 'a'.repeat(64) }],
- };
+ invoke: (async (command: string, args?: Record) => {
+ invokeCalls.push({ command, args });
+ if (command === 'prepare_local_project_game_package') {
+ return STAGED_PACKAGE;
+ }
+ if (command === 'upload_local_project_game_package') {
+ return {
+ versionId: 'gamever_1',
+ status: 'uploaded',
+ uploadedBytes: STAGED_PACKAGE.packageSizeBytes,
+ };
+ }
+ throw new Error(`未预期的命令：${command}`);
}) as never,
projectPath: '/tmp/project',
packageRelativePath: 'exports/playtest-package-1.zip',
@@ -113,18 +129,26 @@ test('发布时携带本地项目标识，让重复发布复用同一个平台
expect(result.gameId).toBe('game_1');
expect(result.versionId).toBe('gamever_1');
+
+ // 关键回归：整包字节不再经过 IPC，上传交给原生侧按版本 ID + 暂存路径完成。
+ const uploadCall = invokeCalls.find(
+ (call) => call.command === 'upload_local_project_game_package',
+ );
+ expect(uploadCall?.args).toMatchObject({
+ stagingPath: STAGED_PACKAGE.stagingPath,
+ versionId: 'gamever_1',
+ apiBaseUrl: 'https://dev.genarrative.world',
+ accessToken: 'test-access-token',
+ });
+ expect(Object.keys(uploadCall?.args ?? {})).not.toContain('packageBytes');
+ // 三次 HTTP：创建游戏、创建版本、送审；上传不再占用一条 HTTP 调用。
+ expect(fetchClientHttp).toHaveBeenCalledTimes(3);
});
test('缺少本地项目标识时在发起请求前失败关闭', async () => {
await expect(
publishLocalProjectGame({
- invoke: (async () => ({
- packageRelativePath: 'exports/playtest-package-1.zip',
- packageBytes: [1],
- packageSha256: 'a'.repeat(64),
- packageSizeBytes: 1,
- files: [{ path: 'index.html', sizeBytes: 1, sha256: 'a'.repeat(64) }],
- })) as never,
+ invoke: (async () => STAGED_PACKAGE) as never,
projectPath: '/tmp/project',
packageRelativePath: 'exports/playtest-package-1.zip',
manifest: { ...MANIFEST, projectId: ' ' } as GameCreationAppManifest,
@@ -137,13 +161,7 @@ test('缺少本地项目标识时在发起请求前失败关闭', async () => {
test('缺少封面时在创建游戏前失败关闭', async () => {
await expect(
publishLocalProjectGame({
- invoke: (async () => ({
- packageRelativePath: 'exports/playtest-package-1.zip',
- packageBytes: [1],
- packageSha256: 'a'.repeat(64),
- packageSizeBytes: 1,
- files: [{ path: 'index.html', sizeBytes: 1, sha256: 'a'.repeat(64) }],
- })) as never,
+ invoke: (async () => STAGED_PACKAGE) as never,
projectPath: '/tmp/project',
packageRelativePath: 'exports/playtest-package-1.zip',
manifest: MANIFEST,
@@ -156,13 +174,7 @@ test('缺少封面时在创建游戏前失败关闭', async () => {
test('截图超过 6 张时在创建游戏前失败关闭', async () => {
await expect(
publishLocalProjectGame({
- invoke: (async () => ({
- packageRelativePath: 'exports/playtest-package-1.zip',
- packageBytes: [1],
- packageSha256: 'a'.repeat(64),
- packageSizeBytes: 1,
- files: [{ path: 'index.html', sizeBytes: 1, sha256: 'a'.repeat(64) }],
- })) as never,
+ invoke: (async () => STAGED_PACKAGE) as never,
projectPath: '/tmp/project',
packageRelativePath: 'exports/playtest-package-1.zip',
manifest: MANIFEST,
diff --git a/apps/ai-game-creator-shell/tests/gameDistributionPublishLive.test.ts b/apps/ai-game-creator-shell/tests/gameDistributionPublishLive.test.ts
index 552b6c26c..b79228dd1 100644
--- a/apps/ai-game-creator-shell/tests/gameDistributionPublishLive.test.ts
+++ b/apps/ai-game-creator-shell/tests/gameDistributionPublishLive.test.ts
@@ -7,18 +7,23 @@
* npx vitest run apps/ai-game-creator-shell/tests/gameDistributionPublishLive.test.ts
*
* 开启后测试会注册一个临时作者，并通过真实的 `clientApi` / `clientHttp`（而不是
- * mock 请求层）调用 AGC 的发布函数，覆盖：本地导出包读取、创建游戏、同
- * `localProjectId` 复用游戏身份、真实 ZIP 上传、送审与版本回读。
+ * mock 请求层）调用 AGC 的发布函数，覆盖：本地发行包暂存摘要、创建游戏、同
+ * `localProjectId` 复用游戏身份、真实分片上传、送审与版本回读。
+ *
+ * jsdom 里没有 Tauri 运行时，`upload_local_project_game_package` 由本测试按服务端
+ * 分片协议（upload-state → chunk → complete）代跑，等同于原生上传器的行为；
+ * 原生实现自身的分片规划、权威偏移续传与错误分类在 Rust 单测里覆盖。
*/
-import { createHash } from 'node:crypto';
+import { createHash, randomBytes } from 'node:crypto';
import JSZip from 'jszip';
import { expect, test, vi } from 'vitest';
import type { GameCreationAppManifest } from '../../../packages/shared/src/contracts/gameCreationApp';
-import type { LocalProjectExportPackagePayload } from '../src/app/types';
+import type { StagedGamePackage } from '../src/app/types';
import { uploadPlatformMediaAsset } from '../src/services/assetDirectUpload';
import { setStoredAuthAccessToken } from '../src/services/clientAuth';
+import { setClientServerSelection } from '../src/services/clientHttp';
import { publishLocalProjectGame } from '../src/services/gameDistributionPublish';
/** 1x1 透明 PNG：真实上传一张合法图片作为封面，避免依赖本地素材文件。 */
@@ -37,6 +42,12 @@ const liveBaseUrl = (process.env.GENARRATIVE_AGC_PUBLISH_E2E_BASE_URL ?? '')
.replace(/\/+$/u, '');
const liveTest = liveBaseUrl ? test : test.skip;
+// AGC 服务默认按渠道选 dev / release 域名；跑真实链路时把「平台服务器」切到传入的本地栈，
+// 否则请求会打到线上域名而不是这台机器上的 api-server。
+if (liveBaseUrl) {
+ setClientServerSelection({ preset: 'custom', customBaseUrl: liveBaseUrl });
+}
+
const realFetch = globalThis.fetch.bind(globalThis);
const ENVELOPE_HEADERS = { 'x-genarrative-response-envelope': 'v1' };
@@ -55,21 +66,73 @@ function installFetchBridge() {
: input instanceof URL
? input.toString()
: input;
+ // jsdom realm 的 Headers / AbortSignal / Blob 都不是 undici 认得的类型（同 2026-09-20
+ // 那条「跨 realm BodyInit 被 undici 拒绝」的坑）：统一降级成 Node 侧能接受的原生值。
+ const headers = init?.headers
+ ? Object.fromEntries(Array.from(new Headers(init.headers).entries()))
+ : undefined;
+ const signal = undefined;
const body = init?.body;
+ if (typeof FormData !== 'undefined' && body instanceof FormData) {
+ // jsdom 的 FormData 同样不被 undici 接受：这里手工序列化成 multipart 字节。
+ const multipart = await serializeFormData(body);
+ return realFetch(url as string, {
+ ...init,
+ headers: { ...headers, 'Content-Type': multipart.contentType },
+ signal,
+ body: multipart.body,
+ });
+ }
if (typeof Blob !== 'undefined' && body instanceof Blob) {
// jsdom 的 Blob/ArrayBuffer 属于另一个 realm，且旧版 jsdom 没有
// Blob.arrayBuffer；统一读成字节后复制为 Node 侧 Buffer 再转发。
const bytes = await readBlobBytes(body);
return realFetch(url as string, {
...init,
+ headers,
+ signal,
body: Buffer.from(bytes),
});
}
- return realFetch(url as string, init);
+ return realFetch(url as string, { ...init, headers, signal });
},
);
}
+async function serializeFormData(form: FormData): Promise<{
+ body: Buffer;
+ contentType: string;
+}> {
+ const boundary = `----agcLive${Date.now().toString(16)}`;
+ const chunks: Buffer[] = [];
+ for (const [name, value] of form.entries()) {
+ if (typeof value === 'string') {
+ chunks.push(
+ Buffer.from(
+ `--${boundary}\r\nContent-Disposition: form-data; name="${name}"\r\n\r\n${value}\r\n`,
+ ),
+ );
+ continue;
+ }
+ const bytes = await readBlobBytes(value);
+ const fileName =
+ (value as File).name || `agc-live-${Date.now().toString(16)}.bin`;
+ const contentType = value.type || 'application/octet-stream';
+ chunks.push(
+ Buffer.from(
+ `--${boundary}\r\nContent-Disposition: form-data; name="${name}"; filename="${fileName}"\r\nContent-Type: ${contentType}\r\n\r\n`,
+ ),
+ );
+ chunks.push(Buffer.from(bytes));
+ chunks.push(Buffer.from('\r\n'));
+ }
+ chunks.push(Buffer.from(`--${boundary}--\r\n`));
+ return {
+ body: Buffer.concat(chunks),
+ contentType: `multipart/form-data; boundary=${boundary}`,
+ };
+}
+
async function readBlobBytes(blob: Blob): Promise {
const maybeArrayBuffer = (
blob as Blob & { arrayBuffer?: () => Promise }
@@ -120,7 +183,10 @@ async function registerAuthor(): Promise {
return data.token;
}
-async function buildExportPayload(): Promise {
+async function buildStagedPackage(): Promise<{
+ staged: StagedGamePackage;
+ bytes: Uint8Array;
+}> {
const zip = new JSZip();
const indexHtml =
'AGC Live ' +
@@ -129,28 +195,169 @@ async function buildExportPayload(): Promise {
'window.__agcLive=1;document.documentElement.dataset.booted="agc";';
zip.file('index.html', indexHtml);
zip.file('assets/app.js', appJs);
+ // 让发行包超过单个分片（8 MiB）：分片续传只有跨片才有意义，随机字节保证不可压缩。
+ zip.file('assets/bulk.bin', randomBytes(9 * 1024 * 1024));
const bytes = await zip.generateAsync({ type: 'uint8array' });
const sha256 = createHash('sha256').update(bytes).digest('hex');
return {
- packageRelativePath: 'dist/game.zip',
- packageBytes: Array.from(bytes),
- packageSha256: sha256,
- packageSizeBytes: bytes.length,
- files: [
- {
- path: 'index.html',
- sizeBytes: Buffer.byteLength(indexHtml),
- sha256: createHash('sha256').update(indexHtml).digest('hex'),
- },
- {
- path: 'assets/app.js',
- sizeBytes: Buffer.byteLength(appJs),
- sha256: createHash('sha256').update(appJs).digest('hex'),
- },
- ],
+ staged: {
+ stagingPath: '/tmp/agc-live-staging/game.zip',
+ packageSha256: sha256,
+ packageSizeBytes: bytes.length,
+ packageFileCount: 3,
+ },
+ bytes,
};
}
+type PackageUploadState = {
+ receivedBytes: number;
+ chunkBytes: number;
+ declaredPackageBytes: number;
+};
+
+function packageAuthHeaders(token: string) {
+ return {
+ Authorization: `Bearer ${token}`,
+ ...ENVELOPE_HEADERS,
+ };
+}
+
+/** 读取服务端权威已收字节（原生上传器同样以它为准）。 */
+async function readPackageUploadState(
+ versionId: string,
+ token: string,
+): Promise {
+ return await unwrap(
+ await realFetch(
+ apiUrl(
+ `/api/game-distribution/versions/${versionId}/package/upload-state`,
+ ),
+ { headers: packageAuthHeaders(token) },
+ ),
+ );
+}
+
+/** 上传一个分片；偏移由调用方按权威偏移给出。 */
+async function uploadPackageChunk(input: {
+ versionId: string;
+ token: string;
+ idempotencyKey: string;
+ offset: number;
+ body: Uint8Array;
+}): Promise {
+ const response = await realFetch(
+ apiUrl(`/api/game-distribution/versions/${input.versionId}/package/chunk`),
+ {
+ method: 'PUT',
+ headers: {
+ ...packageAuthHeaders(input.token),
+ 'Content-Type': 'application/octet-stream',
+ 'x-genarrative-upload-offset': String(input.offset),
+ 'Idempotency-Key': `${input.idempotencyKey}:chunk`,
+ },
+ body: Buffer.from(input.body),
+ },
+ );
+ if (!response.ok) {
+ throw new Error(
+ `分片上传失败：${response.status} ${await response.text()}`,
+ );
+ }
+ const payload = (await response.json()) as {
+ data?: { receivedBytes?: number };
+ receivedBytes?: number;
+ };
+ return payload.data?.receivedBytes ?? payload.receivedBytes ?? input.offset;
+}
+
+async function completePackageUpload(input: {
+ versionId: string;
+ token: string;
+ idempotencyKey: string;
+}) {
+ return await unwrap<{ versionId: string; status: string }>(
+ await realFetch(
+ apiUrl(
+ `/api/game-distribution/versions/${input.versionId}/package/complete`,
+ ),
+ {
+ method: 'POST',
+ headers: {
+ ...packageAuthHeaders(input.token),
+ 'Idempotency-Key': `${input.idempotencyKey}:complete`,
+ },
+ },
+ ),
+ );
+}
+
+/** 从权威偏移继续发送剩余分片，返回本次实际发送过的偏移序列。 */
+async function uploadRemainingChunks(input: {
+ versionId: string;
+ bytes: Uint8Array;
+ token: string;
+ idempotencyKey: string;
+}): Promise {
+ const state = await readPackageUploadState(input.versionId, input.token);
+ const sentOffsets: number[] = [];
+ let received = state.receivedBytes;
+ while (received < input.bytes.length) {
+ const length = Math.min(state.chunkBytes, input.bytes.length - received);
+ await uploadPackageChunk({
+ versionId: input.versionId,
+ token: input.token,
+ idempotencyKey: input.idempotencyKey,
+ offset: received,
+ body: input.bytes.subarray(received, received + length),
+ });
+ sentOffsets.push(received);
+ received = (await readPackageUploadState(input.versionId, input.token))
+ .receivedBytes;
+ }
+ return sentOffsets;
+}
+
+/**
+ * 按服务端分片协议上传整包：与原生上传器同一套请求形状，用于验证服务端合同。
+ * 第一次调用会**只传第一片就停下**，模拟传输中断；后续调用按权威偏移续传，
+ * 因此这里能直接证明「中断后不重传已收字节」。
+ */
+async function uploadStagedPackageViaProtocol(input: {
+ versionId: string;
+ bytes: Uint8Array;
+ token: string;
+ idempotencyKey: string;
+ sentOffsets: number[];
+}) {
+ const state = await readPackageUploadState(input.versionId, input.token);
+ if (state.receivedBytes === 0) {
+ const firstLength = Math.min(state.chunkBytes, input.bytes.length);
+ await uploadPackageChunk({
+ versionId: input.versionId,
+ token: input.token,
+ idempotencyKey: input.idempotencyKey,
+ offset: 0,
+ body: input.bytes.subarray(0, firstLength),
+ });
+ input.sentOffsets.push(0);
+ }
+ input.sentOffsets.push(
+ ...(await uploadRemainingChunks({
+ versionId: input.versionId,
+ bytes: input.bytes,
+ token: input.token,
+ idempotencyKey: input.idempotencyKey,
+ })),
+ );
+ const completed = await completePackageUpload({
+ versionId: input.versionId,
+ token: input.token,
+ idempotencyKey: input.idempotencyKey,
+ });
+ return { versionId: completed.versionId, status: completed.status };
+}
+
liveTest(
'AGC 发布函数在真实后端完成创建、上传、送审并在重复发布时复用游戏身份',
async () => {
@@ -158,22 +365,46 @@ liveTest(
const token = await registerAuthor();
setStoredAccessToken(token);
- const payload = await buildExportPayload();
+ const { staged, bytes } = await buildStagedPackage();
const stamp = String(Date.now());
const manifest = {
projectId: `agc-live-${stamp}`,
name: `AGC 真实发布${stamp.slice(-4)}`,
goal: '验证 AGC 一键发布链路',
} as unknown as GameCreationAppManifest;
- const invoke = vi.fn(async () => payload);
+ // 记录本次发布实际发送过的分片偏移，用来证明「中断后不重传已收字节」。
+ const sentOffsets: number[] = [];
+ const invoke = vi.fn(
+ async (command: string, args?: Record) => {
+ if (command === 'prepare_local_project_game_package') {
+ return staged;
+ }
+ if (command === 'upload_local_project_game_package') {
+ const uploaded = await uploadStagedPackageViaProtocol({
+ versionId: String(args?.versionId ?? ''),
+ bytes,
+ token,
+ idempotencyKey: String(args?.idempotencyKey ?? ''),
+ sentOffsets,
+ });
+ return {
+ versionId: uploaded.versionId,
+ status: uploaded.status,
+ uploadedBytes: bytes.length,
+ };
+ }
+ throw new Error(`未预期的命令：${command}`);
+ },
+ );
// 服务端要求发布必须带封面：真实走一遍凭证 → 直传 → confirm。
const uploadedCover = await uploadPlatformMediaAsset({
file: buildLiveCoverFile(),
assetKind: 'game_distribution_cover',
pathSegments: ['game-distribution', 'cover', stamp],
entityId: 'game-distribution-cover',
- // jsdom 里没有 Tauri HTTP 插件，复用测试注入的 fetch bridge 直连 dev OSS。
- fetchImpl: (input, init) => realFetch(apiUrl(input), init),
+ // jsdom 里没有 Tauri HTTP 插件：直传也走同一个桥，跨 realm 的 FormData 会被
+ // 先序列化成 Node 侧 multipart 字节，否则 OSS 会以 405 拒绝。
+ fetchImpl: (input, init) => globalThis.fetch(input, init),
});
expect(uploadedCover.assetObjectId).toMatch(/\S/u);
const metadata = {
@@ -198,7 +429,18 @@ liveTest(
});
expect(first.status).toBe('pending_review');
expect(first.versionNumber).toBe(1);
- expect(first.packageSha256).toBe(payload.packageSha256);
+ expect(first.packageSha256).toBe(staged.packageSha256);
+ // 分片续传证据：第一片（偏移 0）只发送一次；中断后的续传从权威偏移开始，
+ // 已收字节不重放、也不跳段。
+ expect(sentOffsets[0]).toBe(0);
+ expect(sentOffsets.filter((offset) => offset === 0)).toHaveLength(1);
+ expect(sentOffsets[1]).toBeGreaterThan(0);
+ expect(sentOffsets).toEqual(
+ Array.from(
+ { length: Math.ceil(staged.packageSizeBytes / 8 / 1024 / 1024) },
+ (_, index) => index * 8 * 1024 * 1024,
+ ),
+ );
const readResult = await unwrap<{
version: { versionId: string; status: string; recoveryAction: string };
diff --git a/apps/ai-game-creator-shell/tests/gamePublishFeedback.test.tsx b/apps/ai-game-creator-shell/tests/gamePublishFeedback.test.tsx
index 91b84b4a7..786c790a7 100644
--- a/apps/ai-game-creator-shell/tests/gamePublishFeedback.test.tsx
+++ b/apps/ai-game-creator-shell/tests/gamePublishFeedback.test.tsx
@@ -266,7 +266,11 @@ describe('客户端发布入口的可见反馈', () => {
1440,
);
expect(declaration(overlay, 'position')).toBe('fixed');
- expect(declaration(overlay, 'inset')).toBe('0');
+ // 遮罩从自绘标题栏下方开始：发布进行中仍然要能最小化 / 关闭窗口。
+ expect(declaration(overlay, 'top')).toBe('var(--window-chrome-height)');
+ expect(declaration(overlay, 'right')).toBe('0');
+ expect(declaration(overlay, 'bottom')).toBe('0');
+ expect(declaration(overlay, 'left')).toBe('0');
expect(declaration(overlay, 'z-index')).toBe('500');
expect(declaration(overlay, 'pointer-events')).toBe('auto');
expect(declaration(overlay, 'background')).toBe('rgb(35 24 19 / 62%)');
diff --git a/apps/ai-game-creator-shell/tests/referenceSourceProviders.test.ts b/apps/ai-game-creator-shell/tests/referenceSourceProviders.test.ts
index d7e6bf23c..6cfb4cd75 100644
--- a/apps/ai-game-creator-shell/tests/referenceSourceProviders.test.ts
+++ b/apps/ai-game-creator-shell/tests/referenceSourceProviders.test.ts
@@ -82,7 +82,7 @@ describe('资源引用 provider', () => {
expect(provider.isReady?.()).toBe(true);
});
- it('候选只含可提及素材，`match` 按显示名 / id / kind 过滤并截断到 8 条', () => {
+ it('候选只含可提及素材，`fuzzyLookup` 按显示名 / id / kind 模糊过滤并截断到 8 条', () => {
const assets = [
heroAsset,
asset('asset-icon', 'icon', 'image/png', 'assets/btn.png'),
@@ -91,21 +91,21 @@ describe('资源引用 provider', () => {
asset('asset-agent', 'document', 'text/markdown', '.agent/notes.md'),
];
const scoped = createResourceReferenceProvider({ assets });
- expect(scoped.match?.('')).toHaveLength(2);
+ expect(scoped.fuzzyLookup?.('')).toHaveLength(2);
const many = Array.from({ length: 10 }, (_, index) =>
asset(`asset-${index}`, 'image', 'image/png', `assets/pic-${index}.png`),
);
const limited = createResourceReferenceProvider({ assets: many });
- expect(limited.match?.('')).toHaveLength(8);
+ expect(limited.fuzzyLookup?.('')).toHaveLength(8);
- expect(provider.match?.('hero')?.map((item) => item.type)).toEqual([
+ expect(provider.fuzzyLookup?.('hero')?.map((item) => item.type)).toEqual([
'resource',
]);
- expect(provider.match?.('HERO-IDLE')).toHaveLength(1);
- expect(provider.match?.('character')).toHaveLength(1);
- expect(provider.match?.(' hero ')).toHaveLength(1);
- expect(provider.match?.('missing')).toEqual([]);
+ expect(provider.fuzzyLookup?.('HERO-IDLE')).toHaveLength(1);
+ expect(provider.fuzzyLookup?.('character')).toHaveLength(1);
+ expect(provider.fuzzyLookup?.(' hero ')).toHaveLength(1);
+ expect(provider.fuzzyLookup?.('missing')).toEqual([]);
});
it('同名不同目录的素材是两条候选：显示名相同，但身份键不同', () => {
@@ -116,7 +116,7 @@ describe('资源引用 provider', () => {
],
});
- const candidates = sameName.match?.('') ?? [];
+ const candidates = sameName.fuzzyLookup?.('') ?? [];
// 显示 token 会撞（都是 `@hero`），所以候选菜单的 key 不能拿 token 当身份。
expect(candidates.map((item) => chatReferenceMentionToken(item))).toEqual([
'@hero',
@@ -127,6 +127,45 @@ describe('资源引用 provider', () => {
);
});
+ it('`lookup` 给精确查找用的全量清单：与菜单同一份可提及素材，但不受模糊过滤与截断影响', () => {
+ const assets = [
+ heroAsset,
+ asset('asset-orphan', 'image', 'image/png', ''),
+ ...Array.from({ length: 10 }, (_, index) =>
+ asset(
+ `asset-${index}`,
+ 'image',
+ 'image/png',
+ `assets/pic-${index}.png`,
+ ),
+ ),
+ ];
+ const scoped = createResourceReferenceProvider({ assets });
+
+ // 不可提及素材（没有 localPath）不在候选里，条目数与展示名口径与菜单一致。
+ expect(scoped.fuzzyLookup?.('')).toHaveLength(8);
+ expect(scoped.lookup?.()).toHaveLength(11);
+ expect(scoped.lookup?.().map(chatReferenceMentionToken)).toEqual(
+ expect.arrayContaining(['@hero-idle', '@pic-0', '@pic-9']),
+ );
+ // 粘贴解析只认「显示名逐字一致」的 token，所以候选的 token 必须是显示名形态。
+ expect(
+ scoped
+ .lookup?.()
+ .some(
+ (item) => 'resourceId' in item && item.resourceId === 'asset-orphan',
+ ),
+ ).toBe(false);
+ // 菜单就是「同一份候选 + query 过滤 + 截断」，所以截断后的前缀逐字一致。
+ expect(scoped.lookup?.().slice(0, 8)).toEqual(scoped.fuzzyLookup?.(''));
+ });
+
+ it('清单为空时 `lookup` 是空数组：粘贴不会把任何 token 当成引用', () => {
+ expect(createResourceReferenceProvider({ assets: [] }).lookup?.()).toEqual(
+ [],
+ );
+ });
+
it('`toReference` 只认资源 part：资产已删除时不合成引用', () => {
expect(provider.toReference({ type: 'input_text', text: '看素材' })).toBe(
null,
@@ -147,7 +186,7 @@ describe('资源引用 provider', () => {
});
it('`refresh` 按 manifest 换显示名：改名换新引用、未变恒等、已删除原样返回', () => {
- const reference = provider.match?.('hero')?.[0] as ResourceReference;
+ const reference = provider.fuzzyLookup?.('hero')?.[0] as ResourceReference;
expect(provider.refresh(reference)).toBe(reference);
const renamed = createResourceReferenceProvider({
@@ -191,7 +230,23 @@ describe('资源引用 provider', () => {
describe('附件 provider', () => {
it('静默：没有触发符也没有候选，注入它不会加出任何入口', () => {
expect(attachmentReferenceProvider.trigger).toBe(null);
- expect(attachmentReferenceProvider.match).toBeUndefined();
+ expect(attachmentReferenceProvider.fuzzyLookup).toBeUndefined();
+ });
+
+ it('附件名过同一份空白口径：`toReference` 与 `mentionToken` 都是 `@brief-v2.md`', () => {
+ const part = {
+ type: 'agc_attachment_reference' as const,
+ name: 'brief v2.md',
+ mediaType: 'text/markdown',
+ size: 128,
+ localPath: 'notes/brief v2.md',
+ status: 'imported',
+ };
+ expect(attachmentReferenceProvider.toReference(part)).toMatchObject({
+ type: 'attachment',
+ name: 'brief-v2.md',
+ });
+ expect(attachmentReferenceProvider.mentionToken(part)).toBe('@brief-v2.md');
});
it('`toReference` 逐字搬运附件字段，并只认附件 part', () => {
@@ -305,7 +360,7 @@ describe('运行画面区域 provider', () => {
});
describe('Skill provider', () => {
- it('触发符是 `$`：挂载与 `match` 都不发查询，菜单第一次打开时才读应用级目录', async () => {
+ it('触发符是 `$`：挂载与 `fuzzyLookup` 都不发查询，菜单第一次打开时才读应用级目录', async () => {
const invoke = vi.fn(async (command: string) => {
if (command === 'list_agc_skill_catalog') {
return [{ name: 'agc-test-skill', description: '测试 Skill' }];
@@ -319,9 +374,9 @@ describe('Skill provider', () => {
expect(result.current.trigger).toBe('$');
expect(invoke).not.toHaveBeenCalled();
- // `match` 是纯函数：输入区在渲染阶段调它，这里不能替 provider 发起任何读取。
+ // `fuzzyLookup` 是纯函数：输入区在渲染阶段调它，这里不能替 provider 发起任何读取。
act(() => {
- expect(result.current.match?.('')).toEqual([]);
+ expect(result.current.fuzzyLookup?.('')).toEqual([]);
});
expect(invoke).not.toHaveBeenCalled();
@@ -333,7 +388,7 @@ describe('Skill provider', () => {
expect(invoke).toHaveBeenCalledWith('list_agc_skill_catalog');
});
await waitFor(() => {
- expect(result.current.match?.('')).toHaveLength(1);
+ expect(result.current.fuzzyLookup?.('')).toHaveLength(1);
});
// 目录只读一次：后续每次敲 `$` 都复用同一份候选。
expect(invoke).toHaveBeenCalledTimes(2);
@@ -342,12 +397,81 @@ describe('Skill provider', () => {
result.current.onMenuQueryChange?.(null);
});
expect(invoke).toHaveBeenCalledTimes(2);
- expect(result.current.match?.('测试')?.[0]).toMatchObject({
+ expect(result.current.fuzzyLookup?.('测试')?.[0]).toMatchObject({
type: 'skill',
name: 'agc-test-skill',
});
});
+ it('目录里的名字带空白时折成 `-`：候选与 token 是同一份口径', async () => {
+ const invoke = vi.fn(async (command: string) => {
+ if (command === 'list_agc_skill_catalog') {
+ return [{ name: 'agc test skill', description: '测试 Skill' }];
+ }
+ if (command === 'list_client_extensions') {
+ return [
+ {
+ name: 'client skill',
+ extensionType: 'skill',
+ enabled: true,
+ status: 'enabled',
+ },
+ ];
+ }
+ throw new Error(`unexpected invoke ${command}`);
+ });
+ window.__TAURI__ = { core: { invoke: invoke as never } };
+
+ const { result } = renderHook(() => useSkillReferenceProvider());
+ act(() => {
+ result.current.onMenuQueryChange?.('');
+ });
+ await waitFor(() => {
+ expect(result.current.lookup?.()).toHaveLength(2);
+ });
+ expect(
+ result.current
+ .lookup?.()
+ .map((item) => (item.type === 'skill' ? item.name : null)),
+ ).toEqual(['agc-test-skill', 'client-skill']);
+ expect(
+ result.current.mentionToken?.({
+ type: 'agc_skill_reference',
+ name: 'agc test skill',
+ }),
+ ).toBe('$agc-test-skill');
+ });
+
+ it('`lookup` 是纯函数：目录还没读就返回空数组、也不发起读取，菜单打开后才查得到', async () => {
+ const invoke = vi.fn(async (command: string) => {
+ if (command === 'list_agc_skill_catalog') {
+ return [{ name: 'agc-test-skill', description: '测试 Skill' }];
+ }
+ if (command === 'list_client_extensions') return [];
+ throw new Error(`unexpected invoke ${command}`);
+ });
+ window.__TAURI__ = { core: { invoke: invoke as never } };
+
+ const { result } = renderHook(() => useSkillReferenceProvider());
+
+ // 冷启动：精确查找只能看到「此刻就绪」的候选，目录没读过就是空数组——粘贴 `$名称` 因此按字面保留。
+ act(() => {
+ expect(result.current.lookup?.()).toEqual([]);
+ });
+ expect(invoke).not.toHaveBeenCalled();
+
+ // 菜单第一次打开才读目录，读回之后精确查找立刻可用。
+ act(() => {
+ result.current.onMenuQueryChange?.('');
+ });
+ await waitFor(() => {
+ expect(result.current.lookup?.()).toHaveLength(1);
+ });
+ expect(result.current.lookup?.().map(chatReferenceMentionToken)).toEqual([
+ '$agc-test-skill',
+ ]);
+ });
+
it('内置目录与已启用客户端 Skill 合并后按名字去重，并截断到 8 条', async () => {
const invoke = vi.fn(async (command: string) => {
if (command === 'list_agc_skill_catalog') {
@@ -394,17 +518,17 @@ describe('Skill provider', () => {
result.current.onMenuQueryChange?.('');
});
await waitFor(() => {
- expect(result.current.match?.('')).toHaveLength(8);
+ expect(result.current.fuzzyLookup?.('')).toHaveLength(8);
});
// 同名客户端项被内置项挡掉，上限只作用于当前查询的命中集合。
- expect(result.current.match?.('builtin-0')).toHaveLength(1);
- expect(result.current.match?.('builtin-')).toHaveLength(8);
- expect(result.current.match?.('client-skill')).toMatchObject([
+ expect(result.current.fuzzyLookup?.('builtin-0')).toHaveLength(1);
+ expect(result.current.fuzzyLookup?.('builtin-')).toHaveLength(8);
+ expect(result.current.fuzzyLookup?.('client-skill')).toMatchObject([
{ type: 'skill', name: 'client-skill' },
]);
// 未启用与非 Skill 扩展都不是候选。
- expect(result.current.match?.('client-off')).toEqual([]);
- expect(result.current.match?.('client-plugin')).toEqual([]);
+ expect(result.current.fuzzyLookup?.('client-off')).toEqual([]);
+ expect(result.current.fuzzyLookup?.('client-plugin')).toEqual([]);
});
it('一次瞬时失败不锁死候选：下一次 `match` 还会重读目录，并在控制台留痕', async () => {
@@ -432,7 +556,7 @@ describe('Skill provider', () => {
result.current.onMenuQueryChange?.('a');
});
await waitFor(() => {
- expect(result.current.match?.('')).toHaveLength(1);
+ expect(result.current.fuzzyLookup?.('')).toHaveLength(1);
});
expect(invoke).toHaveBeenCalledTimes(4);
// 读取失败不能静默：控制台要留下可排障的一条。
diff --git a/apps/ai-game-creator-shell/tests/resourceReferenceInput.test.tsx b/apps/ai-game-creator-shell/tests/resourceReferenceInput.test.tsx
index 37a5bc8a7..723689942 100644
--- a/apps/ai-game-creator-shell/tests/resourceReferenceInput.test.tsx
+++ b/apps/ai-game-creator-shell/tests/resourceReferenceInput.test.tsx
@@ -33,6 +33,7 @@ import { attachmentReferenceProvider } from '../src/features/project-workspace/r
import { createResourceReferenceProvider } from '../src/features/project-workspace/reference-source/resourceReferenceProvider';
import { runtimeRegionReferenceProvider } from '../src/features/project-workspace/reference-source/runtimeRegionReferenceProvider';
import { useSkillReferenceProvider } from '../src/features/project-workspace/reference-source/skillReferenceProvider';
+import type { ReferenceProvider } from '../src/features/project-workspace/reference-source/types';
import {
ResourceReferenceInput,
type ResourceReferenceInputHandle,
@@ -67,6 +68,65 @@ import {
type RuntimeRegionReference,
} from '../src/features/project-workspace/resourceReferences';
+/**
+ * jsdom 没有 `DragEvent` / `ClipboardEvent` 构造器，而 Lexical 的默认粘贴路径按构造器名字判断
+ * 事件类型（`objectKlassEquals`）；真实客户端（Tauri / Chromium）两者都在。这里只补齐测试环境
+ * 缺的那部分，名字必须与真实构造器逐字一致，否则 Lexical 会把粘贴数据源当成 `null`。
+ */
+function defineEventClassShim(name: 'DragEvent' | 'ClipboardEvent') {
+ if (typeof (globalThis as Record)[name] === 'function')
+ return;
+ const shim = class extends Event {};
+ Object.defineProperty(shim, 'name', { value: name });
+ Object.defineProperty(globalThis, name, {
+ value: shim,
+ configurable: true,
+ writable: true,
+ });
+}
+
+defineEventClassShim('DragEvent');
+defineEventClassShim('ClipboardEvent');
+
+/**
+ * jsdom 的 `Range` 没有 `getBoundingClientRect`，而候选菜单打开时会用它测锚点位置
+ * （`LexicalTypeaheadMenuPlugin` 的 `getRect`）；真实浏览器两者都在，这里只补测试环境缺的那部分。
+ */
+function defineRangeRectShim() {
+ if (typeof Range === 'undefined') return;
+ if (typeof Range.prototype.getBoundingClientRect === 'function') return;
+ Range.prototype.getBoundingClientRect = () =>
+ typeof DOMRect === 'function'
+ ? new DOMRect()
+ : ({
+ x: 0,
+ y: 0,
+ top: 0,
+ left: 0,
+ right: 0,
+ bottom: 0,
+ width: 0,
+ height: 0,
+ } as DOMRect);
+}
+
+defineRangeRectShim();
+
+/** jsdom 没有 `ResizeObserver`，候选菜单打开时会构造它；真实浏览器都有。 */
+function defineResizeObserverShim() {
+ if (typeof window === 'undefined') return;
+ if (typeof window.ResizeObserver === 'function') return;
+ window.ResizeObserver = class ResizeObserverStub {
+ observe() {}
+
+ unobserve() {}
+
+ disconnect() {}
+ } as unknown as typeof ResizeObserver;
+}
+
+defineResizeObserverShim();
+
function asset(
id: string,
kind: string,
@@ -231,6 +291,48 @@ function composerEditor(): {
return editor;
}
+/**
+ * jsdom 里合成一次原生粘贴：Lexical 的 DOM 监听器把 `paste` 事件转成 PASTE_COMMAND，
+ * 所以这条链路和真实粘贴一致（含 `clipboardData` 读取与 `preventDefault`）。
+ */
+function pasteComposerText(
+ text: string,
+ payload: { html?: string; lexical?: string } = {},
+) {
+ // 真实粘贴发生在有焦点的编辑器里；jsdom 不会自己给编辑器设选区，这里先落到草稿末尾，
+ // 否则 Lexical 默认粘贴处理器拿不到 selection，会直接放弃这次粘贴。
+ act(() => {
+ composerEditor().update(() => {
+ $getRoot().selectEnd();
+ });
+ });
+ const element = screen.getByLabelText('聊天');
+ const event = new Event('paste', { bubbles: true, cancelable: true });
+ Object.defineProperty(event, 'clipboardData', {
+ value: {
+ getData: (type: string) => {
+ if (type === 'text/plain') return text;
+ if (type === 'text/html') return payload.html ?? '';
+ if (type === 'application/x-lexical-editor') {
+ return payload.lexical ?? '';
+ }
+ return '';
+ },
+ },
+ });
+ act(() => {
+ element.dispatchEvent(event);
+ });
+ return event;
+}
+
+/** 草稿里的 Skill 引用名，按 content 顺序。 */
+function draftSkillNames(draft: ChatComposerDraft | undefined) {
+ return (draft?.content ?? []).flatMap((part) =>
+ part.type === 'agc_skill_reference' ? [part.name] : [],
+ );
+}
+
/**
* jsdom 里键盘输入不会进入 Lexical，所以直接走编辑器 API 写文本；
* 它触发的是和真实输入同一条更新链路，typeahead 监听器同样会被唤醒。
@@ -332,6 +434,213 @@ describe('ResourceReferenceInput', () => {
}
});
+ test('粘贴含引用的显示文本：原位重建 chip，其余字符逐字保留', async () => {
+ const ref = createRef();
+ render(
+ ();
+ // provider 认得出这个 token（lookup 有候选），但插入那一刻已经解析不出引用（例如资产刚被删）。
+ const ghostProvider: ReferenceProvider = {
+ trigger: '@',
+ lookup: () => [resourceReferenceFromAsset(assets[0]!, 'asset-picker')],
+ toReference: () => null,
+ refresh: (reference) => reference,
+ mentionToken: (part) =>
+ part.type === 'agc_resource_reference' ? '@hero' : null,
+ };
+ render(
+ ();
+ // provider 契约被破坏：lookup 有候选，但 toReference 与 mentionToken 都答不出来。
+ // 这时必须落一段正常文本（资源退回 resourceId），粘贴进来的字不许凭空消失。
+ const brokenProvider: ReferenceProvider = {
+ trigger: '@',
+ lookup: () => [
+ resourceReferenceFromAsset(
+ asset('ghost-asset', 'character', 'image/png', 'assets/幽灵.png'),
+ 'asset-picker',
+ ),
+ ],
+ toReference: () => null,
+ refresh: (reference) => reference,
+ mentionToken: () => null,
+ };
+ render(
+ ();
+ render(
+ ();
+ render(
+ ();
+ render(
+ ();
+ render(
+ ();
+ render(
+ <>
+
+ ();
+ render(
+ undefined} ariaLabel="测试弹窗">
+
+
+
+ );
+}
+
describe('ThemedModal', () => {
beforeEach(() => {
vi.spyOn(HTMLElement.prototype, 'getClientRects').mockImplementation(
@@ -105,4 +133,23 @@ describe('ThemedModal', () => {
await waitFor(() => expect(screen.queryByRole('dialog')).toBeNull());
expect(document.activeElement).toBe(opener);
});
+
+ it('lets window title bar clicks through while workspace clicks stay trapped', async () => {
+ const user = userEvent.setup();
+ const onMinimize = vi.fn();
+ const onWorkspaceClick = vi.fn();
+ render(
+ ();
+ for (const rule of parseStyleSheet(css)) {
+ if (!rule.selectors.includes(selector)) {
+ continue;
+ }
+ for (const [property, value] of rule.declarations) {
+ merged.set(property, value);
+ }
+ }
+ return merged;
+}
+
+describe('窗口标题栏与全屏弹层的层叠约定', () => {
+ const css = readFileSync(STYLES_PATH, 'utf8');
+
+ it.each(WINDOW_CHROME_SAFE_OVERLAYS)('%s 从标题栏下方开始', (selector) => {
+ const declarations = declarationsForSelector(css, selector);
+ expect(
+ declarations.get('top'),
+ `${selector} 必须声明 top: var(--window-chrome-height)`,
+ ).toBe('var(--window-chrome-height)');
+ });
+});
diff --git a/deploy/container/nginx.conf b/deploy/container/nginx.conf
index 9e34fbaca..6d3284ce0 100644
--- a/deploy/container/nginx.conf
+++ b/deploy/container/nginx.conf
@@ -90,8 +90,9 @@ http {
location ~ ^/api(?:/|$) {
default_type application/json;
- # 中文注释：创作接口会携带参考图 Data URL，Nginx 只放行到 api-server；真实大小限制仍由路由 DefaultBodyLimit 和业务字节校验负责。
- client_max_body_size 64m;
+ # 中文注释：创作接口会携带参考图 Data URL，游戏发行包 PUT 更大，Nginx 只负责放行到 api-server；
+ # 真实大小限制仍由路由 DefaultBodyLimit（发行包 200 MiB + 1 KiB）和业务字节校验负责。
+ client_max_body_size 210m;
limit_conn genarrative_api_conn 64;
limit_req zone=genarrative_api_rps burst=64 nodelay;
diff --git a/deploy/nginx/README.md b/deploy/nginx/README.md
index c3c4bff34..6d2b2dffe 100644
--- a/deploy/nginx/README.md
+++ b/deploy/nginx/README.md
@@ -4,8 +4,8 @@
## 请求体大小
-- 生产、开发服和容器模板都在通用 `location ~ ^/api(?:/|$)` 内设置 `client_max_body_size 64m`。
-- 该值只用于让携带参考图 Data URL 的创作接口抵达 `api-server`；不要把它当作业务上传上限。Rust 路由仍通过 `DefaultBodyLimit` 和解码后字节校验限制具体接口，例如拼图参考图路由只放宽到 12 MiB 请求体，图片字节继续按业务规则拒绝。
+- 生产、开发服和容器模板都在通用 `location ~ ^/api(?:/|$)` 内设置 `client_max_body_size 210m`。
+- 该值只用于让携带参考图 Data URL 的创作接口和游戏发行包 PUT（路由上限 200 MiB + 1 KiB）抵达 `api-server`；不要把它当作业务上传上限。Rust 路由仍通过 `DefaultBodyLimit` 和解码后字节校验限制具体接口，例如拼图参考图路由只放宽到 12 MiB 请求体，图片字节继续按业务规则拒绝。Pingora 网关侧的 `GENARRATIVE_PINGORA_GATEWAY_MAX_API_BODY_BYTES` 必须同样不低于该值，否则请求会在网关层被 413。
- 若线上看到 `413 Request Entity Too Large`，并且 access log 里 `request_time=0.000 upstream_status=-`，通常是 Nginx 没有加载该模板或未 reload；先执行 `nginx -T | grep client_max_body_size` 和 `nginx -t` 再检查 `api-server`。
## gzip
diff --git a/deploy/nginx/genarrative-dev-http.conf b/deploy/nginx/genarrative-dev-http.conf
index f210766ab..640ef088c 100644
--- a/deploy/nginx/genarrative-dev-http.conf
+++ b/deploy/nginx/genarrative-dev-http.conf
@@ -119,8 +119,9 @@ server {
# 临时兼容主站仍在使用的 /api/* HTTP facade；前端完成 SpacetimeDB SDK 迁移后删除。
location ~ ^/api(?:/|$) {
default_type application/json;
- # 中文注释：创作接口会携带参考图 Data URL，Nginx 只放行到 api-server；真实大小限制仍由路由 DefaultBodyLimit 和业务字节校验负责。
- client_max_body_size 64m;
+ # 中文注释：创作接口会携带参考图 Data URL，游戏发行包 PUT 更大，Nginx 只负责放行到 api-server；
+ # 真实大小限制仍由路由 DefaultBodyLimit（发行包 200 MiB + 1 KiB）和业务字节校验负责。
+ client_max_body_size 210m;
limit_conn genarrative_api_conn 64;
limit_req zone=genarrative_api_rps burst=64 nodelay;
diff --git a/deploy/nginx/genarrative.conf b/deploy/nginx/genarrative.conf
index 87bf769e3..b7d1c433a 100644
--- a/deploy/nginx/genarrative.conf
+++ b/deploy/nginx/genarrative.conf
@@ -139,8 +139,9 @@ server {
# 临时兼容主站仍在使用的 /api/* HTTP facade；前端完成 SpacetimeDB SDK 迁移后删除。
location ~ ^/api(?:/|$) {
default_type application/json;
- # 中文注释：创作接口会携带参考图 Data URL，Nginx 只放行到 api-server；真实大小限制仍由路由 DefaultBodyLimit 和业务字节校验负责。
- client_max_body_size 64m;
+ # 中文注释：创作接口会携带参考图 Data URL，游戏发行包 PUT 更大，Nginx 只负责放行到 api-server；
+ # 真实大小限制仍由路由 DefaultBodyLimit（发行包 200 MiB + 1 KiB）和业务字节校验负责。
+ client_max_body_size 210m;
limit_conn genarrative_api_conn 64;
limit_req zone=genarrative_api_rps burst=64 nodelay;
diff --git a/deploy/pingora/nginx-route-parity.matrix.json b/deploy/pingora/nginx-route-parity.matrix.json
index 59eaaa850..f1c90ee98 100644
--- a/deploy/pingora/nginx-route-parity.matrix.json
+++ b/deploy/pingora/nginx-route-parity.matrix.json
@@ -124,14 +124,14 @@
"nginx": {
"production": [
"location ~ ^/api(?:/|$)",
- "client_max_body_size 64m;",
+ "client_max_body_size 210m;",
"limit_conn genarrative_api_conn 64;",
"limit_req zone=genarrative_api_rps burst=64 nodelay;",
"add_header X-Accel-Buffering no always;"
],
"development": [
"location ~ ^/api(?:/|$)",
- "client_max_body_size 64m;",
+ "client_max_body_size 210m;",
"limit_conn genarrative_api_conn 64;",
"limit_req zone=genarrative_api_rps burst=64 nodelay;",
"add_header X-Accel-Buffering no always;"
diff --git a/deploy/pingora/pingora-gateway.env.example b/deploy/pingora/pingora-gateway.env.example
index 467d559d2..d85eb293a 100644
--- a/deploy/pingora/pingora-gateway.env.example
+++ b/deploy/pingora/pingora-gateway.env.example
@@ -28,7 +28,7 @@ GENARRATIVE_PINGORA_GATEWAY_MAINTENANCE_FILE=/var/lib/genarrative/maintenance/en
GENARRATIVE_PINGORA_GATEWAY_MAINTENANCE_PAGE_FILE=/var/lib/genarrative/maintenance/page.html
GENARRATIVE_PINGORA_GATEWAY_FORWARDED_PROTO=http
-GENARRATIVE_PINGORA_GATEWAY_MAX_API_BODY_BYTES=67108864
+GENARRATIVE_PINGORA_GATEWAY_MAX_API_BODY_BYTES=220200960
# gzip 默认开启；等级和最小响应长度对齐 Nginx gzip_comp_level 5 / gzip_min_length 1024。
# Pingora 正式化口径固定为 gzip-only；br / zstd 不进入当前网关，Brotli 继续由 Nginx / 前置代理承担。
GENARRATIVE_PINGORA_GATEWAY_COMPRESSION_ALGORITHMS=gzip
diff --git a/docs/adr/【ADR】引用候选由宿主注入-2026-09-22.md b/docs/adr/【ADR】引用候选由宿主注入-2026-09-22.md
index bd50d9767..47cadf7df 100644
--- a/docs/adr/【ADR】引用候选由宿主注入-2026-09-22.md
+++ b/docs/adr/【ADR】引用候选由宿主注入-2026-09-22.md
@@ -16,6 +16,21 @@
- 输入区删除 `versions` / `activeVersionId` / `showTriggerButton` / `onReferencePickerOpen` / `skills`，`assets` 被注入的 provider 取代；`projectPath` 只保留给输入区自己的润色链路。
- 输入区与宿主之间只留三个通用接缝：`providers`（引用来源）、`inputActions`（操作排里的宿主控件，例如 `@` 触发钮）、`submitSuppressed`（宿主浮层打开时 Enter 让位）。引用种类一个都不进输入区。
-- `provider.match` 必须是纯函数（输入区在渲染阶段调它取候选）；懒加载走 provider 的可选 `onMenuQueryChange(query)`，由输入区在 `useEffect` 里回调，菜单关闭时收到 `null`。Skill 目录因此第一次敲出 `$` 时才读，渲染期不再有 invokes 或 ref 写入。
+- `provider.fuzzyLookup` 必须是纯函数（输入区在渲染阶段调它取候选）；懒加载走 provider 的可选 `onMenuQueryChange(query)`，由输入区在 `useEffect` 里回调，菜单关闭时收到 `null`。Skill 目录因此第一次敲出 `$` 时才读，渲染期不再有 invokes 或 ref 写入。
- 附件并入 `ChatReference`，编辑器收敛为单一引用节点类型，附件 chip 的 DOM 契约逐字保留；附件导入成功后以芯片进入正文，失败不插入；控制器不再持有附件数组，`MAX_CHAT_COMPOSER_ATTACHMENTS` 改为按草稿中的附件芯片数计算，导入进行中禁止发送。
- 用户可见行为保持不变，唯一例外是已裁决的缺陷修复：非 DirectProject 宿主不再出现 `$` Skill 候选。
+
+## 修订（2026-09-22）：粘贴解析需要第二道只读缝
+
+粘贴进来的纯文本要按同一套引用文本语法反解析回正文芯片，因此 provider 的两个查询能力按「模糊 / 精确」分开命名，各自说清自己的语义：
+
+- `fuzzyLookup(query)`：候选菜单那条路——按 query 做包含匹配、大小写不敏感，并在 provider 内部截断到候选上限。名字写明它是模糊的，避免被拿去反查 token。
+- `lookup()`：精确查找那条路——某一刻 provider 真正能解析出的全部引用，不做模糊过滤、不截断，与菜单共用同一份候选来源；仍是纯函数，由输入区在粘贴事件里同步调用，数据没到就是空数组。
+
+这不推翻本 ADR 的懒加载结论：`onMenuQueryChange` 仍是唯一的懒加载入口，粘贴解析**只用此刻就绪的候选**，不等待、不补读。Skill 目录因此还是「用户第一次敲出 `$` 才读」——冷启动时粘贴 `$名称` 就按字面文本保留（看得见、不是猜错），不为了粘贴去提前读盘。
+
+附件与运行画面区域仍是静默 provider：它们没有候选，所以粘贴解析不认 `@附件名` / `@区域标签`，这两类 token 粘贴时逐字保留（附件与运行区域的身份来自文件与 run，纯文本重建不出来）。
+
+歧义口径：同一个 token 对应多条引用身份（同名素材）时一律按文本保留；解析只认显示名逐字一致（不认扩展名、resourceId、大小写变体），未命中的 token 与其余文字逐字保留。
+
+（本次把上一条同名决策里的 `match` / `candidates` 改名为 `fuzzyLookup` / `lookup`，语义不变；旧名不再保留。）
diff --git a/docs/project-memory/plans/【实施计划】AGC发行包分片续传上传-2026-09-23.md b/docs/project-memory/plans/【实施计划】AGC发行包分片续传上传-2026-09-23.md
new file mode 100644
index 000000000..21aa5c760
--- /dev/null
+++ b/docs/project-memory/plans/【实施计划】AGC发行包分片续传上传-2026-09-23.md
@@ -0,0 +1,49 @@
+# AGC 发行包分片续传上传实施计划
+
+| 字段 | 值 |
+| --- | --- |
+| Version | 1.0 |
+| Status | runtime-smoke-passed（存储原语、服务端入口、原生上传器、渲染进程接线与真实栈分片续传 smoke 均已落地） |
+| Date | 2026-09-23 |
+| Parent Milestone | `docs/project-memory/plans/【里程碑】AGC发行包分片续传上传-2026-09-23.md` |
+
+## 修改边界与顺序
+
+1. **存储原语（已完成）**：`server-rs/crates/platform-oss/src/lib.rs` 新增 `append_internal_object` / `append_internal_object_with_retry` 与 `OssAppendInternalObjectRequest` / `OssAppendInternalObjectResponse`；复用现役 V4 签名助手 `signed_request_builder`（查询串已参与签名）与 `run_internal_put_with_retry` 的可重试分类。`position = 0` 追加到末尾，`position > 0` 必须等于对象当前长度；返回 `next_position` 作为权威已收字节。
+2. **服务端入口（已完成）**：`server-rs/crates/api-server/src/modules/game_distribution.rs`
+ - 新增 `GET .../package/upload-state`、`PUT .../package/chunk`、`POST .../package/complete`、`POST .../package/reset` 四个路由，沿用作者鉴权、`game-distribution:publish` 灰度开关与 `Idempotency-Key` 约定；
+ - 分片大小 `PACKAGE_UPLOAD_CHUNK_BYTES = 8 MiB`，分片请求体放行量为分片大小 + 1 KiB；
+ - 从整包 `PUT` 抽出共享收口 `confirm_validated_package`（声明比对 → 确认 → 结构化事件），两种入口共用；
+ - 新增 `game_distribution_oss_client` / `game_distribution_package_object_key` / `staged_package_bytes` / `require_octet_stream_content_type` / `package_upload_offset` 辅助函数；偏移不一致返回 `409 PACKAGE_UPLOAD_OFFSET_MISMATCH` 与权威偏移；未收齐返回 `409 PACKAGE_UPLOAD_INCOMPLETE`；校验失败删除半包并落 `upload_failed`。
+3. **AGC 原生上传器（已完成）**：新增 `apps/ai-game-creator-shell/src-tauri/src/game_package_upload.rs`：内容寻址暂存（`/game-package-staging/.zip`，重启后同包复用同一文件）、`upload-state → chunk → complete` 循环、409 权威偏移续传（响应丢失后按服务端已收字节对齐，不重放不跳段）、仅对传输/超时/408/429/5xx 退避重试（默认 4 次尝试）、`game-package-upload-progress` 进度事件；暂存路径必须落在暂存目录内。命令 `prepare_local_project_game_package` / `upload_local_project_game_package` 已注册，整包回传命令 `read_local_project_export_package` 退役（`read_local_project_export_package_at` 仍供暂存使用）。
+4. **渲染进程接线（已完成）**：`apps/ai-game-creator-shell/src/services/gameDistributionPublish.ts` 改为 `prepare`（拿摘要与暂存路径）→ 创建游戏 → 创建版本 → 原生分片上传 → 送审；`LocalProjectExportPackagePayload` 整包类型退役，改为 `StagedGamePackage` / `GamePackageUploadOutcome`；不再有任何整包字节进 IPC。
+5. **真实栈 smoke（已完成）**：本地 api-server + 真实 OSS bucket 上跑通「中断 → 续传 → 确认」。做法与证据：
+ - 先用 `npm run dev:spacetime` 把当前模块发布到本地库（`genarrative-game-creator-dev`，自动迁移完成），再用 `npm run dev:api-server` 起 `127.0.0.1:8082`；
+ - 本地库的 `feature_gate_config` 原本为空（发布开关默认关闭），用 `spacetime call … upsert_feature_gate_config` 写入 `game-distribution:publish enabled=true rollout=100`；
+ - `GENARRATIVE_AGC_PUBLISH_E2E_BASE_URL=http://127.0.0.1:8082 npx vitest run apps/ai-game-creator-shell/tests/gameDistributionPublishLive.test.ts` → **1 passed / 3.9s**（发行包 9.0 MiB，跨 8 MiB 分片边界）；
+ - 用例断言实际发送过的分片偏移序列等于 `[0, 8388608]`：第一片只发一次，中断后的续传从权威偏移开始，不重放也不跳段；
+ - api-server 侧同一轮日志：`package_chunk_stored offset=0 chunk_bytes=8388608 received_bytes=8388608 elapsed_ms=201`、`package_chunk_stored offset=8388608 chunk_bytes=1049210 received_bytes=9437818 elapsed_ms=82`、`package_confirmed package_bytes=9437818 file_count=3 oss_put_skipped=true elapsed_ms=884`。
+ - 为了能指向本地栈，用例还补了两处基础设施修正：把客户端平台基址切到传入的 base URL（`setClientServerSelection({preset:'custom'})`），以及桥接层把 jsdom realm 的 `Headers` / `Blob` / `FormData` 降级成 Node 侧原生值（`FormData` 手工序列化为 multipart 字节，否则 OSS 直传回 405）。
+
+## 不改的部分
+
+- 网页端发布路径与整包 `PUT` 语义不变；`MAX_PACKAGE_BYTES`、展开量、单文件与文件数上限不变。
+- 未新增 SpacetimeDB 表或字段：已收字节的事实来源是 OSS 对象长度，版本状态机沿用既有 `awaiting_upload → uploaded → …`。
+- 未引入半包定时清理任务。
+
+## 验证命令
+
+- `cargo test -p platform-oss`（74 passed）
+- `cargo test -p api-server game_distribution`（23 passed，含新增 `package_chunk_size_stays_inside_declared_limits`、`package_upload_offset_requires_non_negative_integer`、`package_chunk_content_type_must_be_octet_stream`）
+- `cargo fmt --all -- --check`、`npm run check:encoding`、`npm run check:doc-index`、`git diff --check`
+- `cargo test game_package_upload`（AGC 原生侧 4 passed：分片规划无缝无重叠、409 权威偏移解析、URL 拼接、内容寻址暂存与路径校验）
+- `npx tsc -p apps/ai-game-creator-shell/tsconfig.json --noEmit`、`npm run --workspace apps/ai-game-creator-shell typecheck`（含 `check-config.mjs` 的命令登记门禁）
+- `npx vitest run`（发布函数 6 passed、发布面板 9 passed、发布反馈 5 passed；真实链路用例在无 `GENARRATIVE_AGC_PUBLISH_E2E_BASE_URL` 时按设计跳过）
+- 待做：真实栈 smoke（本地 api-server + 真实 OSS bucket 上跑「中断 → 续传 → 完成」，含 `x-oss-next-append-position` 语义确认）
+
+## 风险与回滚点
+
+- **对象可追加性**：`platform-oss` 之前没有追加写，首次真实调用需要在真实 bucket 上确认 `x-oss-next-append-position` 语义；失败时回滚点是 `platform-oss` 新增函数与四条路由（整包 `PUT` 不受影响，可独立回退）。
+- **半包对象**：分片写入直接落在版本键上，未完成时是半包。它不进公开目录、不服务发行网关；失败或作者重置时删除。若删除失败会记录 `package_staging_delete_failed` 告警，需要人工确认对象键状态。
+- **重置语义**：只有 `awaiting_upload` / `upload_failed` 允许重置，避免破坏已确认事实。
+- **内存**：完成动作按 200 MiB 上限回读整包再校验，峰值与整包 `PUT` 同量级；分片路径不再让整包驻留客户端。
diff --git a/docs/project-memory/plans/【实施计划】AGC渠道安装身份隔离-2026-09-21.md b/docs/project-memory/plans/【实施计划】AGC渠道安装身份隔离-2026-09-21.md
index a8f468584..982d7cb08 100644
--- a/docs/project-memory/plans/【实施计划】AGC渠道安装身份隔离-2026-09-21.md
+++ b/docs/project-memory/plans/【实施计划】AGC渠道安装身份隔离-2026-09-21.md
@@ -47,3 +47,10 @@
- 风险：非默认渠道首次以新身份安装，老 `dev` 用户不会自动迁移本地数据。回滚点：渠道身份只影响非默认渠道构建，撤销该渠道的构建产物即可，仓库侧无数据迁移。
- 风险：窗口标题改为构建期产品名后，标题不再等于配置里的字面量。回滚点：去掉 `main.rs` 的标题覆盖调用，行为回到配置标题。
- 风险：ACL managed 识别放宽到前缀族。回滚点：`is_game_creator_packaged_app_data_leaf` 收紧回单一直线值，但非默认渠道的提权修复会重新失败关闭。
+
+## 2026-09-23 追加：dev 渠道展示名统一
+
+- `dev` 渠道继续复用 `world.genarrative.ai-game-creator`，保证既有安装、升级链和 AppData 路径不变；展示名统一为 `陶泥儿开发版`。
+- `channel-identity.mjs` 是展示名单一来源。发布构建将同一 `productName` 同时注入 Tauri 安装配置、原生窗口标题和 `VITE_AGC_PRODUCT_NAME`；React 自绘标题栏及关于/运行时配置展示从该注入值读取。
+- 因此 Windows NSIS 默认生成的快捷方式、开始菜单/卸载注册表展示名随 Tauri `productName` 变为 `陶泥儿开发版`；未新增自定义注册表或快捷方式实现。
+- 静态 Tauri 基线配置同步为 `陶泥儿开发版`，本地壳与正式 `dev` 包的显示名保持一致。
diff --git a/docs/project-memory/plans/【实施计划】引用粘贴解析-2026-09-22.md b/docs/project-memory/plans/【实施计划】引用粘贴解析-2026-09-22.md
new file mode 100644
index 000000000..c90010981
--- /dev/null
+++ b/docs/project-memory/plans/【实施计划】引用粘贴解析-2026-09-22.md
@@ -0,0 +1,63 @@
+# 引用粘贴解析实施计划
+
+对应：[引用候选由宿主注入](../../adr/【ADR】引用候选由宿主注入-2026-09-22.md)（含 2026-09-22 修订节）；决策记录见 `docs/project-memory/shared-memory/decision-log.md` 的 2026-09-22 条目。上一步的重构计划见 [引用输入区重构与宿主注入](【实施计划】引用输入区重构与宿主注入-2026-09-22.md)，那份明确不含本项。
+
+## 一句话交付与验收判据
+
+把从用户消息气泡（或任何同口径文本）复制出来的 `@显示名` / `$名称` 粘贴进引用输入区时，原位重建同顺序的引用芯片；其余文字逐字保留。
+
+验收判据：
+
+1. 粘贴文本 → 引用：`@显示名` 与 `$名称` 逐字命中当前宿主注入的 provider 候选时原位换成芯片，一次 Ctrl+Z 整体回退，token 之外的每个字符（含换行与空白）原样保留。
+2. 逐字一致、不做兼容别名：不认 `@hero.png`、`resourceId`、大小写变体、全角 `＠`；token 前后必须是行首 / 行尾或空白。
+3. 宁可不成芯片也不能认错：同名多候选（同一个 token 对应多条引用身份）一律按文本保留；未命中的 token 静默保留，不提示、不猜路径或文件名。
+4. 只有真的解析出引用时才接管：同 namespace 的 `application/x-lexical-editor` 负载、不含 token 的纯文本、图片文件粘贴一律放行编辑器默认导入，现有粘贴行为逐字不变。
+5. 附件与运行画面区域不参与粘贴解析（静默 provider 没有候选），它们的 token 粘贴时按文本保留。
+6. Skill 目录冷启动不阻塞粘贴：`lookup()` 是纯函数，目录没到就是空数组——冷启动时粘贴 `$名称` 保留为文本（不等待、不补读），用户敲过一次 `$` 后即可解析。
+
+## 流程判定
+
+本次是共享组件的一处行为增量 + provider 契约加两个可选能力，不动 schema、不动公开 API/DTO、不动后端；按轻量流程只建本实施计划，不新建主规范与里程碑规范（与上一步重构同一判定）。
+
+## 提交切分
+
+1. **反解析口径**：`resourceReferences.ts` 新增 `buildContentFromPastedText(text, references)`（粘贴侧唯一反解析；与 `buildContentFromTextTokens` 同一套边界规则），配规则矩阵单测。
+2. **provider 契约**：`reference-source/types.ts` 把菜单查询改名为 `fuzzyLookup(query)`、新增精确查找 `lookup()`（两者共用同一份候选来源）；`resourceReferenceProvider` 给全量可提及候选，`skillReferenceProvider` 给去重后的 Skill 候选。
+3. **输入区接管**：`ResourceReferenceInput` 注册 `COMMAND_PRIORITY_CRITICAL` 的 `PASTE_COMMAND`，只在解析出引用时 `preventDefault` 并在一次 `editor.update`（`PASTE_TAG`）内按选区插入；配集成用例。
+4. **文档**：`CONTEXT.md` 术语、本计划、ADR 修订节、`docs/【功能说明】AGC聊天素材引用-2026-09-08.md` 与决策记录。
+
+## 验证
+
+定向：`npx vitest run apps/ai-game-creator-shell/tests/resourceReferences.test.ts apps/ai-game-creator-shell/tests/referenceSourceProviders.test.ts apps/ai-game-creator-shell/tests/resourceReferenceInput.test.tsx`；全量：`npm run typecheck`、`npm run check:encoding`、`npm run check:doc-index`、`git diff --check`。真实客户端手感（粘贴时的候选菜单位置、大段文本粘贴观感、Tauri 剪贴板只带图片时的行为）留待真机验收。
+
+## 风险与回滚
+
+- 解析接管会绕过 Lexical 的 `text/html` 富文本导入：只在文本里真的解析出引用时接管，取舍已在上一条判据里限定；要完全避开富文本场景可以后续按 `clipboardData.types` 再收窄。
+- 气泡里若出现与素材同名的 `@区域标签` / `@附件名`，粘贴会被认成素材引用——纯文本无法区分，属已知取舍。
+- 回滚按提交粒度 revert；canonical content 形状、provider 的既有能力与出站文本口径都不变。
+
+## 执行状态（2026-09-22）
+
+已完成：`buildContentFromPastedText` 与规则矩阵单测（命中 / 未命中 / 相邻中文 / 扩展名 / 大小写 / 全角 / 同名歧义 / 重复出现 / 换行 / 与显示口径互为逆运算）；provider 的 `fuzzyLookup` / `lookup` 及用例；输入区 `PASTE_COMMAND` 接管与 5 条集成用例（粘贴重建芯片、未命中保持字面、纯文本走默认导入、Lexical 负载让位、Skill 冷启动保持字面且敲过 `$` 后可解析）；文档同步。
+
+未做（本次范围外）：斜杠命令 `/` 解析、拖拽文本（drop）、附件 / 运行画面区域 / 文件路径 / URL / 剪贴板图片的解析、复制侧 `text/plain` 形态调整、扩展安装卸载后的目录即时失效。
+
+## 追加执行状态（2026-09-23）：前缀重叠按「引用名无空白」收口
+
+自动评审留下的唯一破坏性项（`@hero` 与 `@hero v2` 互为前缀时粘贴会多插一枚短名芯片）不改反解析，改为把不变量前移到引用名：
+
+- `resourceReferences.ts` 新增共享 `normalizeMentionName(value)`（内部空白折 `-`、裁首尾），素材显示名（`resourceDisplayName`）、Skill 名（目录读入与 `toReference` / `mentionToken`）、附件名（导入映射与 `toReference` / `mentionToken`）与两个 token 投影（`chatReferenceMentionToken`、`directCodexContentToPromptText`）统一过这一份；token 层重复归一化是幂等的。
+- 名称里不做 `resourceId` 兜底这一条按评审校正：词干为空（`.env` / `.gitignore` 这类整名就是扩展名的文件）时 `resourceDisplayName` 回退 `asset.id`，回退值同样过 `normalizeMentionName`；`normalizeMentionName` 自己仍只做归一化。
+- 代价与取舍：`hero v2` 与 `hero-v2` 归一化后同名时走既有的「同名多候选按文本保留」；改动前生成的旧文本里的 `@hero v2` 不再解析。
+- 验证：`normalizeMentionName` / 显示名 / token 口径单测 + 前缀重叠回归用例（归一化后粘贴只剩正确的那一枚芯片）+ provider 两处用例；把 `normalizeMentionName` 变异成恒等后新增用例全红。
+
+## 追加执行状态（2026-09-23 第二轮自动评审）：空名字与插入兜底收口
+
+第二轮自动评审的四个问题逐个提交处理，落点都在 `apps/ai-game-creator-shell`：
+
+- 显示名不再可能为空：`resourceDisplayName` 在文件名词干为空（`.env` / `.gitignore`）时回退 `asset.id`，回退值同样过 `normalizeMentionName`（提交 `4e90465c4`）。这条校正了上一节「不做兜底」的写法，决策记录与功能说明同步。
+- 粘贴解析跳过退化 token：`buildContentFromPastedText` 组装候选时跳过 `token.length <= 1` 的条目，裸 `@` / `$` 不再认领正文里的触发符（提交 `3f9c698a6`）。
+- 粘贴接管改成「插入真的发生之后」才 `preventDefault`：`$insertContentAtSelection` 返回「插进去没有」，插入为空时放行默认粘贴；编辑器已在更新中（回调被排队）时按原口径先接管（提交 `3391ecf7d`）。
+- 插入兜底不再留空：provider 的 `toReference` 与 `mentionToken` 都答不出来的 part 退到新增的 `contentPartText`（通用文本形态，资源落 `@resourceId`）。此前这一支会什么都不插，是「粘贴内容逐字保留」唯一的例外分支；现在没有例外。新增单测覆盖四类 part 的文本形态，新增输入区集成用例证明被破坏的 provider 契约下这段粘贴仍按文本落下，去掉兜底即变红。
+- 归一化撞名（`hero v2` 与 `hero-v2` 折成同一个 token）只在解析侧兜住、候选菜单不提示冲突，这一条涉及「哪些素材能被 @ 到」的产品取舍，未改代码，留给下一轮决定。
+- 润色回写与粘贴共用同一条落点兜底：新增 `mentionTokenOrText`（provider 的 `mentionToken`，拿不到就退 `contentPartText` 的通用文本形态），润色回写的候选扫描、整根替换的落点与粘贴插入的兜底都走它。由此润色回写不再有「provider 答不出 token 的 part 直接消失」和「整根替换时 part 解析不出引用就整条吃掉」两条静默丢弃路径；初始草稿（`applyContent`）与润色回写（`applyPolishedTextToRoot`）共用 `applyContentToRoot`，所以恢复出来的草稿里已解析不出的引用现在落成 `@resourceId` 文本而不是被吃掉。
diff --git a/docs/project-memory/plans/【里程碑】AGC发行包分片续传上传-2026-09-23.md b/docs/project-memory/plans/【里程碑】AGC发行包分片续传上传-2026-09-23.md
new file mode 100644
index 000000000..a881e7e88
--- /dev/null
+++ b/docs/project-memory/plans/【里程碑】AGC发行包分片续传上传-2026-09-23.md
@@ -0,0 +1,58 @@
+# AGC 发行包分片续传上传
+
+| 字段 | 值 |
+| --- | --- |
+| Version | 1.0 |
+| Status | runtime-smoke-passed（真实栈「中断 → 续传 → 确认」已通过；AGC 真机一键发布与 200 MiB 档容量数据未验证） |
+| Date | 2026-09-23 |
+| Parent Spec | `docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`（真实发行包与资料合同第 10 条、幂等并发与恢复） |
+
+## 背景与触发
+
+AGC 一键发布今天把整包字节从 WebView 侧送出：`read_local_project_export_package` 先把 `packageBytes` 整包过一遍 IPC 回到渲染进程，渲染进程再用 `@tauri-apps/plugin-http` 发整包 `PUT`，而该插件会把 body 序列化成 `Array.from(new Uint8Array(buffer))` 再走一次 IPC。两次整包 IPC 决定了 AGC 实际可发布的包远小于服务端 200 MiB 上限，失败时表现为客户端侧传输错误（例如「无法连接登录服务」），服务端访问日志里没有这次请求；断流后也只能整包白传。本里程碑把上传下沉到原生侧并支持分片续传。
+
+## 目标
+
+1. AGC 一键发布由原生进程直接读取本地试玩包、按服务端下发的固定分片大小上传，整包字节不再经过 WebView IPC。
+2. 传输中断、网络失败、客户端进程退出或应用重启后，同一 `versionId` 只补传缺失字节，不白传整包。
+3. 分片入口与现役整包 `PUT` 共用同一版本状态机、摘要口径、幂等键与包校验；网页端发布路径不变。
+
+## 不在本里程碑内
+
+- 不改网页端发布路径（继续整包 `PUT`），不为浏览器实现续传。
+- 不做并行分片上传、不做客户端直传 OSS（分片仍经 `api-server` 转发，与今天整包路径同一出口）。
+- 不做「后台自动续传」：续传只在下一次发布动作或应用重启后的重试里发生，不引入常驻重传任务。
+- 不做未完成分片会话的定时清理任务；半包对象的回收单独开里程碑。
+- 不改发行包上限、展开量、单文件与文件数上限。
+
+## 合同要点
+
+- **入口与状态**：分片续传对既有 `versionId` 生效，版本状态沿用 `awaiting_upload → uploaded → …`；分片入口与整包入口互斥，同一版本同时只能有一个写入者，第二个写入返回 `409 UPLOAD_IN_PROGRESS`。
+- **权威偏移**：服务端记录的已收字节是唯一权威。客户端分片偏移与之不符时返回 `409` 与权威偏移，客户端按权威偏移续传；重复分片不得造成重复写入。
+- **完成动作**：全部字节到齐后才执行校验与确认；校验失败删除半包对象并把版本落到 `upload_failed`（`recoveryAction=reupload`）。重新上传同一版本前必须显式重置分片会话，重置后偏移归零，不允许在半包之上续写不同字节。
+- **可见性**：半包对象不进入公开目录、不服务发行网关、不改变当前公开版本；与既有「未通过审核不改变 `activeVersionId`」口径一致。
+- **原生侧边界**：原生上传只读本地试玩包并逐片发送，进度以事件回传渲染进程；渲染进程不再持有整包字节。
+
+## 依赖
+
+- `platform-oss`：需要一组可续写的对象写入原语（追加语义或等价的分片会话），以及读取已收字节的探测能力；现役只有整对象 `PUT`。
+- `api-server`：`modules/game_distribution.rs` 新增分片入口与完成动作，复用既有 `validate_release_zip`、OSS 上传重试分类、`package_confirmed` / `package_rejected` 可观测事件。
+- AGC：`src-tauri` 新增原生上传命令与进度事件，`src/services/gameDistributionPublish.ts` 改为调用原生命令；`read_local_project_export_package` 不再为发布回传整包字节。
+- 反代/网关：分片请求体远小于现役 210 MiB 放行量，沿用现有配置，不改限额。
+
+## 验收标准
+
+1. **不再整包过 IPC**：发布 200 MiB 档包时，渲染进程侧不出现整包字节（对照 `read_local_project_export_package` 的返回体与 IPC 报文大小），上传由原生进程完成。
+2. **续传生效**：上传中途断开传输后重发同一版本，只补传缺失分片；分片请求数、已传字节与最终包摘要三项均可复核。
+3. **跨重启续传**：上传中断时退出应用并重启，重新发布时服务端返回权威已收字节，客户端从该偏移继续，最终确认成功。
+4. **偏移与重复**：分片偏移不符返回 `409` 与权威偏移；重复提交同一分片不产生重复写入；同版本第二个写入者返回 `409 UPLOAD_IN_PROGRESS`。
+5. **失败关闭**：完成动作里校验失败（非法 ZIP、超限、压缩比越界等）删除半包对象、版本落 `upload_failed`，半包不出现在公开目录，也不影响当前公开版本。
+6. **兼容与回归**：整包 `PUT` 路径与既有测试保持绿；`npm run check:doc-index`、`npm run check:encoding`、`git diff --check` 通过；`check:spacetime-schema` 按是否新增持久字段决定是否纳入。
+7. **运行时证据（已获得）**：本地 api-server（`127.0.0.1:8082`，库 `genarrative-game-creator-dev`）+ 真实 OSS bucket 上跑通 `gameDistributionPublishLive.test.ts`：9.0 MiB 发行包跨 8 MiB 分片边界，第一片只发送一次，中断后续传从权威偏移 `8388608` 继续、第二片 `received_bytes=9437818`，最后 `package_confirmed`（`oss_put_skipped=true`）；整轮 3.9s。**未获得**：AGC 真机（Tauri 运行时）一键发布的端到端运行，以及 200 MiB 档的耗时 / 内存容量数据。
+
+## 待评审的决策点
+
+1. **续写原语**：OSS 追加写（顺序、单对象、续传只需回读当前长度）对比 OSS Multipart（可并行、更通用但需要多组新操作）。建议追加写，顺序续传已满足本里程碑目标。
+2. **分片大小**：建议 8 MiB（200 MiB 上限 → 最多 25 片，单片请求体远低于现役放行量）。
+3. **重置语义**：建议只有显式重置（作者点「重新上传」或 `reupload` 恢复动作）才删除半包并归零；其余情况一律按权威偏移续传。
+4. **半包回收**：本里程碑只标记未完成会话，不做定时清理；回收另立里程碑（涉及「不得删除仍被公开版本引用的对象」口径）。
diff --git a/docs/project-memory/plans/【里程碑】游戏分发目录详情与在线游玩-2026-09-18.md b/docs/project-memory/plans/【里程碑】游戏分发目录详情与在线游玩-2026-09-18.md
index 226855815..e55f03b43 100644
--- a/docs/project-memory/plans/【里程碑】游戏分发目录详情与在线游玩-2026-09-18.md
+++ b/docs/project-memory/plans/【里程碑】游戏分发目录详情与在线游玩-2026-09-18.md
@@ -120,7 +120,7 @@
### 行为与验收
- [ ] 真实环境中完整跑通“首次上传 → 校验 → 审核 → 公开 → 游客游玩 → 更新待审旧版在线 → 新版切换 → 下架撤销”。
-- [ ] 100 MiB 包与获批文件数/展开量边界有可复核耗时、内存和失败证据；校验不会执行上传代码，服务资源有界。
+- [ ] 200 MiB 包（现行上限，见 2026-09-23 决策记录）与获批文件数/展开量边界有可复核耗时、内存和失败证据；校验不会执行上传代码，服务资源有界。已有证据覆盖 100 MiB 档，上限提升后的档位待复跑。
- [ ] 校验执行器重启可恢复，审核积压与失败可观测，清理不删除仍被公开版本引用的文件。
- [ ] CDN purge 失败时仍在获批缓存 TTL 内拒绝新资源；明确已下载脚本无法远程抹除的边界。
- [ ] 发布/回滚步骤保留当前公开版本，能关闭新提交和新版本激活；部署路由、缓存、响应头、日志脱敏和告警完成检查。
diff --git a/docs/project-memory/shared-memory/decision-log.md b/docs/project-memory/shared-memory/decision-log.md
index 669807b1d..4dfa2d28e 100644
--- a/docs/project-memory/shared-memory/decision-log.md
+++ b/docs/project-memory/shared-memory/decision-log.md
@@ -1,5 +1,44 @@
# 决策记录
+## 2026-09-23 自绘标题栏是窗口边框：弹层从它下方开始，焦点陷阱放行它
+
+- 背景：AGC 打开任意一个 `ThemedModal` 弹窗（发布面板、发布进度、资源预览、账本、错误报告等）后，右上角「最小化 / 最大化 / 关闭」点击没有任何反应，标题栏拖拽也不能移动窗口；关掉弹窗立刻恢复。原因是标题栏在模态之外，而 `focus-trap-react` 在 document 捕获阶段监听 `mousedown`/`touchstart`/`click`，模态外的点击被 `preventDefault()` 且 `click` 直接 `stopImmediatePropagation()` —— React 的监听在更内层，事件到不了它，所以表现是「点了没反应」而不是报错。另有 `.app-update-overlay` 用 `inset: 0` 真的把标题栏盖住了。
+- 决策：把自绘标题栏定为**窗口边框**，不属于弹层内容：① portal 到 body 的全屏弹层一律 `top: var(--window-chrome-height)`，禁止用 `inset: 0` 盖住标题栏；② `ThemedModal` 的焦点陷阱用 `allowOutsideClick` 只放行落在 `[data-window-chrome-bar]` 内的目标，工作区内容的点击继续被拦住；③ `WindowChrome` 的标题栏加 `data-window-chrome-bar` 标记，作为这条约定的唯一契约点。
+- 影响范围：`apps/ai-game-creator-shell/src/components/modal/ThemedModal.tsx`、`apps/ai-game-creator-shell/src/components/WindowChrome.tsx`、`apps/ai-game-creator-shell/src/styles.css`（`:root` 注释、`.app-update-overlay`、`.game-publish-progress-overlay`）。
+- 验证方式：`tests/themedModal.test.tsx`（标题栏点击放行、工作区点击仍被拦）、`tests/WindowChrome.test.tsx`（弹窗打开时三个窗口按钮仍调用原生窗口 API）、`tests/windowChromeOverlayContract.test.ts`（7 个全屏弹层都从标题栏下方开始）、`tests/gamePublishFeedback.test.tsx` 与 appSurface（208 passed）；两处新增用例都做过「去掉修复即失败」的反向确认。`npm run --workspace apps/ai-game-creator-shell typecheck`、eslint、`npm run check:encoding`、`git diff --check` 通过。
+
+## 2026-09-23 游戏发行包上限提升到 200 MiB（反代放行量与发行缓存同步）
+
+- 背景：游戏广场发行包上限原为 100 MiB（`module-game-distribution` 的 `MAX_PACKAGE_BYTES` 与网页端 `GAME_PACKAGE_MAX_BYTES`），而 Nginx 三份模板与 Pingora 网关的通用 `/api` 放行量是 64 MiB。上限只改一层没有意义：包体超过 100 MiB 时先在反代层被 413，`api-server` 的 ZIP 校验根本不会执行。
+- 决策：发行包上限 100 MiB → 200 MiB；展开总量 250 MiB → 500 MiB（保持 2.5 倍余量）；单文件 64 MiB、最多 10,000 个文件、展开/压缩比 100 三条内容规则不变；发行包路由请求体上限继续从包上限派生（200 MiB + 1 KiB）。反代放行量统一放宽到 210 MiB：`deploy/nginx/genarrative.conf`、`deploy/nginx/genarrative-dev-http.conf`、`deploy/container/nginx.conf` 使用 `client_max_body_size 210m`，Pingora `DEFAULT_MAX_API_BODY_BYTES` 改为 `220200960` 并同步 `deploy/pingora/pingora-gateway.env.example`。发行静态资源进程内缓存字节预算 200 MiB → 256 MiB，让 200 MiB 档发行包仍能进缓存、且不独占整份预算。
+- 边界：包内单个文件仍不得超过 64 MiB；线上 Pingora 环境文件若仍写 `67108864`，必须在重启网关前同步改值，否则发行包 PUT 会在网关层被 413。AGC 一键发布经 `@tauri-apps/plugin-http` 传整包字节，实际可发布体积还受该传输方式限制，200 MiB 档的客户端容量需要单独验证。
+- 影响范围：`server-rs/crates/module-game-distribution/src/package.rs`、`server-rs/crates/api-server/src/modules/game_distribution.rs`、`server-rs/crates/pingora-gateway/src/main.rs`、`src/components/game-distribution/gameZipPackage.ts`、`deploy/{nginx,container,pingora}`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`、`docs/technical/【开发运维】Pingora独立网关试点-2026-06-11.md`。
+- 验证方式：`cargo test -p module-game-distribution`（13 passed，其中 `accepts_package_above_the_previous_hundred_mib_limit` 用两个 50 MiB 存储型条目构造 100 MiB 出头的包；把上限临时改回 100 MiB 时该用例确实失败，证明它能守住新上限）、`cargo test -p api-server game_distribution`（20 passed，含新增的请求体上限覆盖包上限断言）、`cargo test -p pingora-gateway`（38 passed，含 `matches_nginx_route_parity_matrix`）、`npx vitest run src/components/game-distribution`（46 passed）、`cargo fmt --all -- --check`、`npm run check:encoding`、`npm run check:doc-index`、`git diff --check` 通过。`npm run check:pingora-route-parity` 仍在 dev-http / 容器模板缺少 `/games` 等 SPA 路由处失败，改动前同样失败，与本次口径无关。200 MiB 档真实栈容量证据（上传耗时、api-server 峰值内存、超限 413 口径）尚未复跑，发布前需按阶段 D 脚本重跑一轮。
+
+## 2026-09-23 引用名不允许空白：素材 / Skill / 附件共用 `normalizeMentionName`
+
+- 背景：自动评审发现 `buildContentFromTextTokens` 在前缀重叠时会多插一枚芯片——素材显示名 `hero` 与 `hero v2` 并存时，粘贴 `看 @hero v2 这一版` 得到 `[chip hero]` + `[chip hero-v2]`（短名先按 index 平局抢位，长名成了补到末尾的孤儿）。根因不是匹配算法，而是**引用名自己带空白**：token 的边界规则是「前后为空白或行首行尾」，`@hero␠` 在 `@hero v2` 内部也算一次合法命中。
+- 决策：把不变量前移到引用名——`@显示名` / `$名称` / `@附件名` 的名字内部不允许空白，统一经共享 `normalizeMentionName(value)`（内部空白折成 `-`、裁掉首尾）处理。落点是名字的产生处：`resourceDisplayName()`、Skill 目录读入与 `toReference` / `mentionToken`、附件导入映射与 `toReference` / `mentionToken`，外加两个 token 投影（`chatReferenceMentionToken`、`directCodexContentToPromptText`）——token 层幂等再折一次，「token 里没有空白」就是不变量本身的性质，不依赖上游数据干净。
+- 决策（不兜底）：引用名假定非空，不做 `resourceId` 之类的兜底；`resourceDisplayName` 原来的 `|| asset.id` 一并去掉。
+- 校正（2026-09-23，评审项）：`resourceDisplayName` 的空名字兜底不能一并去掉——整名就是扩展名时（`.env` / `.gitignore`）去掉扩展名得到空串，显示名成了空串，token 退化成只有触发符的裸 `@`（候选菜单里是空芯片，粘贴解析还会认领正文里任何一处裸 `@`）。改为词干为空时回退 `asset.id`（仍过 `normalizeMentionName`）；`normalizeMentionName` 自己没有兜底、只做归一化这条不变。
+- 落点兜底（2026-09-23，评审项）：part 落进正文的兜底链统一为 `mentionTokenOrText`（provider 的 `mentionToken`，拿不到就退 `contentPartText` 的通用文本形态，即 `@resourceId` / `$名称` / `@附件名` / `@区域标签`）。粘贴插入、润色回写的候选扫描与整根替换共用它，删掉两处静默丢弃路径（provider 答不出 token 的 part 在润色翻译里消失；整根替换时解析不出引用的 part 被吃掉）。副作用是恢复出来的初始草稿里已解析不出的引用落成 `@resourceId` 文本而不是消失——宁可留文本，也不让内容凭空少一段。
+- 原因：不改反解析是因为粘贴解析与润色回包共用 `buildContentFromTextTokens`，改匹配算法要冒回归润色的风险；而「名字里带空白的 token」本来就无法手敲（候选触发器 `allowWhitespace: false`，空格处菜单就关），显示口径与输入口径早就不一致。折成 `-` 之后 token 自带边界：`@hero` 不会命中 `@hero-v2`（后一个字符是 `-`，不是空白），前缀重叠不可能再发生。
+- 影响范围：`apps/ai-game-creator-shell/src/features/project-workspace/{resourceReferences.ts,reference-source/{skillReferenceProvider.ts,attachmentReferenceProvider.ts}}`、`apps/ai-game-creator-shell/src/view/project-development/chat/conversation/directCodexTurnAttachments.ts`、`apps/ai-game-creator-shell/tests/{resourceReferences.test.ts,referenceSourceProviders.test.ts}`、`CONTEXT.md`、`docs/【功能说明】AGC聊天素材引用-2026-09-08.md`、`docs/project-memory/plans/【实施计划】引用粘贴解析-2026-09-22.md`。
+- 代价（已接受）：归一化可能撞名（`hero v2` 与 `hero-v2` 同名），走既有的「同名多候选一律按文本保留」——不认错，但两者都成不了芯片；改动前生成的旧文本（历史回合 prompt、旧气泡）里的 `@hero v2` 不再解析，重试 / 润色回填时那条引用会退化成末尾孤儿（内容不丢、位置可能不对）。
+- 验证方式：`normalizeMentionName`、`resourceDisplayName`、`chatReferenceMentionToken` 的口径单测；「空白折 `-` 后 token 自带边界、前缀重叠只剩正确芯片」的回归用例；Skill 目录名带空白与附件名带空白的 provider 用例；把 `normalizeMentionName` 变异成恒等函数后以上新增用例全部变红。另跑受影响用例、`npm run typecheck`、`npm run check:encoding`、`git diff --check`。
+
+## 2026-09-22 引用粘贴解析：只认显示口径的 token，宁可不成芯片也不能认错
+
+- 背景：引用输入区的 `@` / `$` 只由 `LexicalTypeaheadMenuPlugin` 的逐字敲击触发，粘贴走 Lexical 默认路径（`text/plain` → 纯文本），所以从用户消息气泡复制回来的 `@显示名` / `$名称` 粘进来就是死文本；同时 chip 的 `text/plain` 是占位符，复制出去再粘回来必然丢引用（气泡显示文本才是完整 token 的形态）。
+- 决策（口径）：新增粘贴侧唯一反解析 `buildContentFromPastedText(text, references)`（`apps/ai-game-creator-shell/src/features/project-workspace/resourceReferences.ts`），候选由宿主注入的 provider 枚举，token 就是 `chatReferenceMentionToken`——与出站显示逐字同一个字符串，所以**不做任何兼容别名**：不认 `@hero.png`、`resourceId`、大小写变体、全角 `＠`；边界仍是「行首 / 行尾或空白」（显示侧 token 前后补空白，两端自洽）。
+- 决策（宁可不成芯片也不能认错）：同一个 token 对应多条引用身份（同名素材）时一律按文本保留；未命中的 token 静默保留、不提示、不猜文件名或路径；附件与运行画面区域不参与（静默 provider 没有候选，`@附件名` / `@区域标签` 按文本保留）。
+- 决策（provider 契约按「模糊 / 精确」分两个口）：上一条里的 `match(query)` 改名 `fuzzyLookup(query)`（名字写明它是包含匹配 + 截断的模糊菜单查询），`candidates()` 改名 `lookup()`（精确查找用的、就绪的全量候选，不模糊不截断），两者共用同一份候选来源。粘贴解析只用 `lookup()` 此刻就绪的候选：不等待、不补读，也不为了解析去提前读盘；Skill 目录仍是「用户第一次敲出 `$` 才读」，冷启动时粘贴 `$名称` 保持字面文本，敲过一次 `$` 后即可重建芯片。曾一度加过的 `onPasteText` 补读钩子已删除——它既不改变本次粘贴的结果，又让输入区反过来关心 provider 的触发符。
+- 决策（接管范围）：输入区在 `COMMAND_PRIORITY_CRITICAL` 注册 `PASTE_COMMAND`，**只在真的解析出引用时**接管（同 namespace 的 `application/x-lexical-editor` 负载、无 token 纯文本、图片文件一律 `return false` 走默认导入）；接管时一次 `editor.update(..., { tag: PASTE_TAG })` 内按选区插入，所以一次 Ctrl+Z 整体回退，token 之外逐字保留。
+- 原因：粘贴是用户此刻的编辑，事后回头改写他的输入（例如清单到齐后再把文本改成芯片）等于前端替用户重写内容；而任何「多候选取其一」「按文件名猜资源」的启发式都会制造看不出错的错引用。
+- 影响范围：`apps/ai-game-creator-shell/src/features/project-workspace/{resourceReferences.ts,ResourceReferenceInput.tsx,reference-source/{types.ts,resourceReferenceProvider.ts,skillReferenceProvider.ts}}`、`apps/ai-game-creator-shell/tests/{resourceReferences.test.ts,referenceSourceProviders.test.ts,resourceReferenceInput.test.tsx}`、`CONTEXT.md`、`docs/adr/【ADR】引用候选由宿主注入-2026-09-22.md`（修订节）、`docs/【功能说明】AGC聊天素材引用-2026-09-08.md`、本文件。
+- 未纳入本次：斜杠命令 `/` 解析、拖拽文本（drop）、附件 / 运行画面区域 / 文件路径 / URL / 剪贴板图片、复制侧 `text/plain` 形态调整、扩展安装卸载后的目录即时失效。
+- 验证方式：`buildContentFromPastedText` 规则矩阵单测（含「显示文本再粘贴回来得到同一份 content」这条逆运算）、provider 的 `fuzzyLookup` / `lookup` 用例、输入区集成用例（真 Lexical `paste` 事件 → 芯片、未命中等价于默认粘贴、Skill 冷启动保持字面且敲过 `$` 后可解析）；另跑 `npm run typecheck`、`npm run check:encoding`、`npm run check:doc-index`、`git diff --check`。
+
## 2026-09-23 最近项目检查失败不进终态
- 背景：最近项目列表把一次性的目录检查失败当成终态——5s 超时被吞成 `null`，增量投影又把上一轮的 `null` 原样搬进下一轮，且没有重试或重查入口。AGC 一次 IPC 停顿之后，整张列表会永久停在「检查失败 + 待识别」，首页「最近项目」同时因 `canOpen` 过滤变空，只能重启客户端恢复（issue #490）。
@@ -9229,3 +9268,22 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在
- 影响面：`apps/ai-game-creator-shell/src/view/project-development/chat/{conversation/directThreadChat.ts,controller/useDirectThreadChatSubscription.ts,controller/useDirectProjectChatController.ts}` 与 `apps/ai-game-creator-shell/tests/{directThreadChat.test.ts,appSurface/chat-composer.suite.ts}`。
- 验证：reducer 新增 2 条用例（兜底收口后同名 `turn.started` 不复活且真终态仍能补上结束时间；身份不同的回合不动），appSurface 新增 `stops claiming the turn is running when a failed send left turn.started open`；变异验证：拿掉 controller 里的兜底收口调用后该用例变红（界面仍显示「陶泥儿正在处理」），恢复即绿。
- 边界（未做）：根因仍在宿主侧——要在进程内保证开闭配对，应由 Rust 在回合函数退出（含 panic / 任务中止）时补一条终态事件（drop 守卫）；本次只做到前端不再跟着说谎。另：兜底收口的回合没有终态时间，仍会落进「`finished` 但拿不到终态时间」那个已知缺口（终态文案要不要藏，见 `DirectProjectTurn.tsx` 与 `DirectChatTurnState` 注释里的 A 项）。
+
+## 2026-09-23 后台 Dashboard「消耗泥点」改为对冲退还后的净消耗
+
+- 背景：Dashboard 的「消耗泥点数」只累计负向消费流水，生成失败退还、精选审核返还和 LLM Router 正向冲正都不参与抵扣，运营看到的「总消耗」明显高于用户实际花费（用户现场反馈）。
+- 决策：`GET /admin/api/dashboard` 的 `consumedMudPoints` 改为净消耗。先按北京时间业务日累计 `asset_operation_consume` / `llm_router_consume` 的负向流水绝对值，再用同期 `asset_operation_refund` 正向流水和 `llm_router_consume` 正向冲正流水按日抵扣：先抵当日消耗，不足再回溯抵扣最近仍有净额的业务日，抵扣不完的退还丢弃。因此每日净额非负，区间合计严格等于「消耗 − 退还」。新增 `refundedMudPoints` 与「退还泥点」趋势图，前台「消耗泥点数」卡旁并列「退还泥点数」卡，毛消耗可由「消耗 + 退还」核出，不把退还金额藏进净额。
+- 边界（本次不改）：用户详情「历史花费」（`profile_wallet_consumption_total` 投影与手动对账）维持既有「退款不冲减」决策，仍只累计负向消费流水；若要改成净额，必须单独走投影语义 + 对账口径变更，不能顺手改这一处。充值退款追回、余额重置、赠送和 hold 继续不计入消耗。
+- 影响范围：`server-rs/crates/api-server/src/admin.rs`、`server-rs/crates/shared-contracts/src/admin.rs`、`apps/admin-web/src/api/adminApiTypes.ts`、`apps/admin-web/src/pages/AdminDashboardPage.tsx`、对应用例与 `docs/technical/【后台管理】Dashboard运营看板方案-2026-06-23.md`。
+- 验证方式：`cargo test -p api-server --manifest-path server-rs/Cargo.toml --bin api-server dashboard_consumption`（新增 4 条净额用例全绿）；`cargo test -p api-server --manifest-path server-rs/Cargo.toml --bin api-server admin`（136 passed / 0 failed / 1 ignored）；`npm run admin-web:typecheck`；`npx vitest run apps/admin-web/src`（218 passed）；`npm run check:encoding`、`git diff --check`。
+
+## 2026-09-23 后台充值订单实付口径、发放泥点列、用户累计充值与兑换码单位
+
+- 背景：充值管理列表与用户详情把订单金额当实付展示，未支付订单也显示非 0 实付；发放泥点挤在「金额 / 泥点」一格或商品列小字里；用户详情看不到该用户累计充值额度；兑换码页的奖励数字没有单位，运营无法判断是元还是泥点。
+- 决策（实付只有支付过的订单才有）：`AdminRechargeOrderEntryPayload` 新增 `paidAmountCents`，由 api-server 按订单 `paid_at` 是否存在判定——存在才等于订单金额，未支付 / 已关闭 / 已过期固定为 0。后台前端实付列显示 `未支付`（并附订单金额小字），退款面板「订单实付」读同一字段；订单金额 `amountCents` 不再被当作实付。
+- 决策（发放泥点独立成列）：充值管理列表的表头由「金额 / 泥点」拆成「实付」与「发放泥点」两列，用户详情充值订单表同样新增「发放泥点」列，商品列只保留商品名；未支付订单发放为 0 泥点，与实付口径一致。
+- 决策（累计充值由后端算）：用户详情新增 `cumulativeRechargedCents`，api-server 按 `user_id` 读取 `profile_recharge_order`、只累加 `paid_at` 存在的订单金额（退款不回减），单次读取上限 500 行；读取失败或命中上限返回 `null`，前端显示「读取失败」，不用用户详情最多 20 条订单在 BFF 或前端近似重算。此次只新增 BFF 字段，未改 SpacetimeDB 表结构与 procedure。
+- 决策（兑换码奖励是泥点）：兑换码 `rewardPoints` 是奖励泥点（兑换成功按 `redeem_code_reward` 流水进钱包），后台输入标签改为「奖励泥点」、列表列头与单元格都带「泥点」单位。
+- 影响范围：`server-rs/crates/api-server/src/{admin.rs,admin_recharge.rs}`、`server-rs/crates/shared-contracts/src/admin.rs`、`apps/admin-web/src/api/adminApiTypes.ts`、`apps/admin-web/src/pages/{AdminRechargeOrderPage.tsx,AdminRedeemCodePage.tsx}`、`apps/admin-web/src/components/AdminUserDetailDialog.tsx`、对应三个用例文件与后端架构数据契约文档。
+- 验证方式：`cargo test -p api-server --manifest-path server-rs/Cargo.toml --bin api-server cumulative_recharge`（2 条新用例）与 `cargo check -p api-server`；`npm run admin-web:typecheck`；`npx vitest run apps/admin-web/src`（220 passed），其中三个定向文件 33 passed（新增「未支付订单不显示实付金额，发放泥点单独成列」与「累计充值读取不到时展示未知，不用订单列表近似」）。
+- 边界（未验证）：未连真实生产库核对历史订单的累计充值数值，也未跑真实栈 API smoke。
diff --git a/docs/project-memory/shared-memory/pitfalls.md b/docs/project-memory/shared-memory/pitfalls.md
index 56fa9611a..2efa4c511 100644
--- a/docs/project-memory/shared-memory/pitfalls.md
+++ b/docs/project-memory/shared-memory/pitfalls.md
@@ -1,5 +1,17 @@
# 踩坑与排障记录
+## 策划回复的重复终态不能重新启动伪流式
+
+策划 Runtime 会通过状态事件与命令返回交付同一份最终视图。若前端清空临时正文后再拿“最后一条非用户历史消息”回填动画，就会出现正式回复旁又播放一遍、播放后消失的假重试。正文应按 `messageId` 保存显示进度，与正式消息共用一个气泡；请求完成不清动画，不延迟正式业务状态。Provider 自动重试复用消息 ID 并发送空文本，只允许重置未持久化的该条回复。正文、工具状态和 reasoning 分开；事件与异步命令收尾均检查项目及活动回合，旧请求不能覆盖新回合。详见 [AGC 实施计划](../../technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md)。
+
+## 2026-09-23 弹窗打开时自绘标题栏的最小化 / 最大化 / 关闭静默失效
+
+- **现象**：AGC 打开「发布到游戏广场」面板（以及其它任何弹窗）后，右上角三个窗口按钮点了没有任何反应，拖拽标题栏也不能移动窗口；关掉弹窗立刻恢复。标题栏看着完全正常，遮罩也明显只压住了下面的工作区，所以很容易误判成「按钮自己坏了」或 Tauri 窗口 API 挂了。
+- **原因**：标题栏在模态之外，但它是窗口边框。`ThemedModal` 用的 `focus-trap-react` 在 **document 捕获阶段**监听 `mousedown`/`touchstart`/`click`：模态外的点击一律 `preventDefault()`，`click` 还会 `stopImmediatePropagation()`。React 的监听挂在 document 内的根容器上，捕获阶段就被掐掉的 `click` 永远到不了 React，于是既不报错也不执行 —— 与「焦点陷阱吞掉模态外点击」是同一类问题（见 2026-09-20 发布面板焦点陷阱那条）。另有一条独立的同类缺陷：`.app-update-overlay` 用 `inset: 0`，把标题栏真的盖住了，更新弹窗期间按钮被遮罩挡住。
+- **处理（现行口径）**：① 全屏弹层一律从标题栏下方开始（`top: var(--window-chrome-height)`），不得用 `inset: 0` 盖住标题栏；② `ThemedModal` 的焦点陷阱用 `allowOutsideClick` 只放行落在 `[data-window-chrome-bar]` 内的目标，工作区内容点击继续被拦；③ 新增全屏弹层时把类名补进 `apps/ai-game-creator-shell/tests/windowChromeOverlayContract.test.ts` 的清单。
+- **验证**：`npx vitest run apps/ai-game-creator-shell/tests/themedModal.test.tsx apps/ai-game-creator-shell/tests/WindowChrome.test.tsx apps/ai-game-creator-shell/tests/windowChromeOverlayContract.test.ts`（标题栏点击放行、工作区点击仍被拦、7 个全屏弹层都在标题栏下方）；两个新增用例去掉修复后确实失败，确认能守住这条约定。
+- **关联**：`apps/ai-game-creator-shell/src/components/modal/ThemedModal.tsx`、`apps/ai-game-creator-shell/src/components/WindowChrome.tsx`、`apps/ai-game-creator-shell/src/styles.css`。
+
## Direct 宿主继续请求不能重发原始用户条目
原始 `direct_user_item` 同时参与历史持久化和模型输入转换；验收或错误反馈更新了 prompt 后，如果发送层仍优先转换原始条目，模型会收到重复的用户输入，而本地历史按 itemId 去重后只显示一次。首次请求与宿主继续必须显式区分：首次保留结构化输入，继续发送当次反馈，原始条目只保留历史与事件关联职责。GUI、CLI 的两条循环都要覆盖；只改反馈文本或清空原始条目不完整。见 [Direct 宿主继续请求输入修复](../../technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md#2026-09-23-direct-宿主继续请求输入修复)。
@@ -5927,3 +5939,11 @@ Cocos Creator 根目录由 `package.json.creator.version` 与普通 `assets/`
- **现象**：模板清单里的封面 URL 失效（或离线）时，卡片封面上出现浏览器的破碎图片图标，比没有封面更难看。
- **处理**：`TemplateCard` 的 `img` 加 `onError` 直接把自身 `visibility` 设为 `hidden`（不进 state，卡片是 memo 的纯展示组件），留下封面容器本身的中性底色；单测用 `fireEvent.error(cover)` 钉住。
- **关联**：`apps/ai-game-creator-shell/src/view/template-library/TemplateCard.tsx`、`apps/ai-game-creator-shell/tests/templateLibraryView.test.tsx`。
+
+## 2026-09-23 渠道 `--config` 只写窗口标题，打包产物系统标题栏回来了且登录请求被 ACL 拒绝
+
+- **现象**：dev 渠道 0.1.129 安装包启动后，窗口顶部同时出现系统标题栏（浅蓝条 + 原生最小化/最大化/关闭）与前端自绘 `WindowChrome`；窗口缩到 816x639（约 800x600 客户区）；登录页常驻「无法连接登录服务，请确认配套后端或 API 代理已启动后重试」。应用日志同一秒出现 `startup.window-title.failed: 缺少 client 主窗口`，而 `https://dev.genarrative.world` 在浏览器/curl 下可正常响应。
+- **原因**：`ebb288a6a`（2026-09-23 18:49）为统一渠道产品名，在渠道配置里加了 `app: { windows: [{ title: productName }] }`。Tauri 的 `--config` 合并是 JSON Merge Patch（`tauri-utils/build.rs` 用 `json_patch::merge`）：对象递归合并、**数组整体替换**。基线窗口数组被整条换掉后，`label` 回落到默认 `main`（不是 `client`）、`decorations` 回落到 `true`、尺寸回落到 800x600。三条症状同源：① `decorations: true` → 系统标题栏；② 尺寸回落 → 816x639；③ label 不再是 `client` → `capabilities/main.json`（`windows: ["client"]`，承载 `http:default` 与平台 API scope、dialog/opener/updater/剪贴板权限）整条不命中，前端 `fetchClientHttp` 走 `@tauri-apps/plugin-http` 时被 ACL 拒绝并抛错，登录状态检查就报成"连不上服务器"。判断关键：**这类"连不上服务"是权限拒绝，不是网络故障——先看窗口 label 与 capability 的 `windows` 是否还对得上，别去查后端与代理**。
+- **处理（现行口径）**：`createChannelConfig()` 从基线 `src-tauri/tauri.conf.json` 读完整 client 窗口对象后展开、只覆盖 `title`（`readBaseClientWindow()`），渠道配置不得再出现"只写 `title`"的窗口对象。新增守卫：`build-release.test.mjs` 用同语义的 merge patch 复现 Tauri 合并并断言 `label=client` / `decorations=false` / 1280x800 / min 1280x720 且承载 `http:default` 的 capability 必须包含该 label；`check-config.mjs` 增补基线 `decorations !== false` 失败关闭。
+- **验证**：`node --test apps/ai-game-creator-shell/scripts/build-release.test.mjs scripts/cargo-features.test.mjs scripts/release-oss.test.mjs scripts/prepare-macos-codex.test.mjs`（60/60）、`node apps/ai-game-creator-shell/scripts/check-config.mjs` 通过；`createChannelConfig('dev', …)` 实测输出含 `label: client` 与 `decorations: false`。修复后的安装包尚未重新构建与安装，真机观感与登录链未复核。
+- **关联**：`apps/ai-game-creator-shell/scripts/build-release.mjs`、`apps/ai-game-creator-shell/scripts/build-release.test.mjs`、`apps/ai-game-creator-shell/scripts/check-config.mjs`、`apps/ai-game-creator-shell/src-tauri/capabilities/main.json`、`docs/technical/【技术方案】AGC客户端更新检查与下载-2026-08-31.md`。
diff --git a/docs/technical/【后台管理】Dashboard运营看板方案-2026-06-23.md b/docs/technical/【后台管理】Dashboard运营看板方案-2026-06-23.md
index 0c951c3d2..b26f58358 100644
--- a/docs/technical/【后台管理】Dashboard运营看板方案-2026-06-23.md
+++ b/docs/technical/【后台管理】Dashboard运营看板方案-2026-06-23.md
@@ -22,7 +22,8 @@
## 指标口径
- 生产素材数：`editor_project_resource` 中 `source_type = 'generated'` 的资源，按 `created_at` 映射到北京时间业务日。
-- 消耗泥点数：`profile_wallet_ledger` 中 `source_type = asset_operation_consume` 且 `amount_delta < 0` 的流水绝对值，按 `created_at` 映射到北京时间业务日。
+- 消耗泥点数（净消耗）：`profile_wallet_ledger` 中 `source_type` 为 `asset_operation_consume` / `llm_router_consume` 且 `amount_delta < 0` 的流水绝对值，按 `created_at` 映射到北京时间业务日后，再按日对冲同期退还泥点——先抵当日消耗，不足再回溯抵扣最近仍有净额的业务日，抵扣不完的退还丢弃，因此每日净额非负，区间合计严格等于「消耗 − 退还」。充值退款追回、余额重置、赠送和 hold 都不计入。
+- 退还泥点数：`source_type = asset_operation_refund` 的正向流水（生成失败退还、精选审核返还）与 `llm_router_consume` 的正向冲正流水，按 `created_at` 映射到北京时间业务日。它只对冲本看板的消耗口径，不改变用户详情「历史花费」按既有决策的退款不冲减口径。
- 总注册用户：`profile_dashboard_state` 行数。
- 新增用户数：`profile_dashboard_state` 中 `created_at` 落在当前筛选时间窗内的账号数，按北京时间业务日归属，支持本日 / 本周 / 本月快捷日期范围。
- 新增用户付费率：分母为当前筛选时间窗内的新增用户，分子为这些用户中截至本次查询时已至少完成一次真实支付的去重人数。真实支付以 `profile_recharge_order.paid_at` 存在且不晚于本次查询时刻为准；只创建订单或未支付订单不计，已退款订单仍表示曾经发生过付费转化，因此保留在分子。返回付费人数、新增用户数和四舍五入后的基点率；分母为 0 时 DTO 返回 0，前端百分比显示 `-`。
@@ -33,6 +34,7 @@
- 留存活跃：用户在注册日恰好 `D+1` / `D+7` 的 `tracking_daily_stat` 中存在上述有效 user scope 行；同一用户同日多个事件只计一次，不按“1 / 7 天内累计回访”计算。筛选范围约束注册 cohort，观察日允许晚于筛选结束日。
- 留存成熟条件：目标观察日必须早于当前北京时间业务日；观察日为今天时因当天尚未完整结束而排除。D1、D7 的可观察人数通常不同，分别返回 `eligibleUsers`、`retainedUsers` 与 `rateBasisPoints = round(retainedUsers * 10000 / eligibleUsers)`；分母为 0 时 DTO 返回 0，前端百分比显示 `-`。汇总率按总人数加权，不平均每日百分比。
- 运营汇总页签：复用同一时间窗，展示运营指标卡、素材类型分布和访问模块分布。
+- 趋势图：`消耗泥点` 图展示按日对冲之后的净额，区间合计与「消耗泥点数」指标一致；`退还泥点` 图展示同期退还金额，毛消耗可由「消耗 + 退还」核出，避免把退还金额藏进净额里。
## 前后端文件
diff --git a/docs/technical/【开发运维】Pingora独立网关试点-2026-06-11.md b/docs/technical/【开发运维】Pingora独立网关试点-2026-06-11.md
index 74b666676..d5d5e3f34 100644
--- a/docs/technical/【开发运维】Pingora独立网关试点-2026-06-11.md
+++ b/docs/technical/【开发运维】Pingora独立网关试点-2026-06-11.md
@@ -488,7 +488,7 @@ dev 根盘空间在安装后曾接近满盘；2026-06-17 进入 canary 前已清
| `GENARRATIVE_PINGORA_GATEWAY_ACME_ROOT` | `/var/www/html` | ACME challenge 静态目录。 |
| `GENARRATIVE_PINGORA_GATEWAY_MAINTENANCE_FILE` | `/var/lib/genarrative/maintenance/enabled` | 存在即进入维护模式。 |
| `GENARRATIVE_PINGORA_GATEWAY_FORWARDED_PROTO` | `http` | 写入 `X-Forwarded-Proto` 的值。 |
-| `GENARRATIVE_PINGORA_GATEWAY_MAX_API_BODY_BYTES` | `67108864` | `/api` 通用路由的 `Content-Length` 上限。 |
+| `GENARRATIVE_PINGORA_GATEWAY_MAX_API_BODY_BYTES` | `220200960` | `/api` 通用路由的 `Content-Length` 上限（210 MiB，覆盖游戏发行包 PUT 的 200 MiB + 1 KiB 路由上限）。 |
| `GENARRATIVE_PINGORA_GATEWAY_COMPRESSION_ALGORITHMS` | `gzip` | 当前唯一允许的压缩算法白名单；Pingora 正式化口径固定为 gzip-only，Brotli 继续由 Nginx / 前置代理承担。 |
| `GENARRATIVE_PINGORA_GATEWAY_GZIP_ENABLED` | `true` | 是否启用 gzip 响应压缩。 |
| `GENARRATIVE_PINGORA_GATEWAY_GZIP_LEVEL` | `5` | gzip 压缩等级，必须在 `0..=9`。 |
diff --git a/docs/technical/【技术方案】AGC客户端更新检查与下载-2026-08-31.md b/docs/technical/【技术方案】AGC客户端更新检查与下载-2026-08-31.md
index 66fe3e5cb..8bbdbe95a 100644
--- a/docs/technical/【技术方案】AGC客户端更新检查与下载-2026-08-31.md
+++ b/docs/technical/【技术方案】AGC客户端更新检查与下载-2026-08-31.md
@@ -136,7 +136,8 @@
- 发布入口：`npm run ai-game-creator-shell:release:upload`（构建 + 按渠道上传）；仅构建不发布的 smoke 使用 `--no-bundle` 分支，不读远端版本、不改版本、不生成清单。
- 发布入口只解析一次目标，优先级为 CLI `--target value` / `--target=value` / `-t value`、`AGC_BUILD_TARGET`、Windows 默认值；重复/空目标与不支持目标失败关闭。版本高水位、构建 feature/渠道端点、bundle 路径、产物后缀、清单平台键及摘要必须消费同一个发布上下文，不能分别回读默认目标。
- 渠道由 `AGC_UPDATE_CHANNEL` 显式指定，默认 dev；Windows 与 macOS 目标均支持 dev、release 和自定义渠道，目标校验独立进行。
-- 渠道 `--config` 在 Tauri 构建前最后合并，同时注入 `productName`、`identifier` 与 updater 端点：安装身份与更新端点必须来自同一个渠道，不能各自回读默认值。macOS 发布入口构建 `*.app`、updater 归档与 DMG 前先按发布渠道解析产品名，产物名一律派生而不写死。
+- 渠道 `--config` 在 Tauri 构建前最后合并，同时注入 `productName`、`identifier`、updater 端点与窗口标题：安装身份与更新端点必须来自同一个渠道，不能各自回读默认值。macOS 发布入口构建 `*.app`、updater 归档与 DMG 前先按发布渠道解析产品名，产物名一律派生而不写死。
+- 渠道配置走 Tauri 的 JSON Merge Patch 语义：对象递归合并，**数组整体替换**。因此 `app.windows` 必须按基线 `tauri.conf.json` 的完整 client 窗口对象下发、只覆盖 `title`（脚本从基线读取后展开）；任何"只写 `{ title }`"的写法都会让 `label` / `decorations` / 尺寸回落成 Tauri 默认值（`label=main`、`decorations=true`、800x600），表现为打包产物重新出现系统标题栏，并按 label 连带失效承载平台 HTTP 权限等 capability。守卫用例：`build-release.test.mjs` 的渠道配置合并用例与 `check-config.mjs` 的 `decorations` 门禁。
- 定时调度分别判断服务端与客户端 scope：dev 小时调度在提交含 AGC 相关路径时发布对应渠道，纯文档或流水线自身的提交仍只跑 Full Build；release 每日调度在服务端相关路径变化时发布正式 Full Build，在 AGC 相关路径变化时发布 release 客户端，并在同一调度内等待、汇总各 lane 结果，失败 lane 下一轮补发。判定失败或勾选强制触发时按"需要发布"处理。
- 更新摘要不再自动生成：发布脚本不读取提交记录生成 `notes`；只有 `AGC_UPDATE_RELEASE_NOTES` 非空时，才把显式手动文案写入渠道清单和旧协议清单的 `releaseNotes`。未设置时清单不携带更新说明，归档文件 `release-notes.txt` 记录“本次没有可用的更新摘要”。
- 清单里的 `commit` 是非标准字段：更新插件忽略未知字段；发布脚本只为线上排障保留源码 revision，不驱动更新摘要。
diff --git a/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md b/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md
index 2ddfeb4ae..dbe77e802 100644
--- a/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md
+++ b/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md
@@ -255,6 +255,11 @@ Rust 分片日志在失败时输出有界 stdout 尾部中的失败段，保留
- 工作区状态条复用现有聊天状态条的字号、间距和状态点。长项目名允许换行，不能撑宽面板；长错误、澄清和批量文件导入结果在受限区域内完整可读，不能挤走输入框。输入编辑器保留原有高度上限，模型/推理菜单继续允许弹出面板。
- 已在消息底部时，实时正文与思考增高后继续跟随；用户主动上滚阅读历史后不自动抢回底部，发送新消息后恢复跟随。阶段/待处理卡片改变消息可用高度时，仍遵守同一跟随意图。滚动仅为临时 UI 状态，不写入正式会话。
- 历史消息只有收到真实发送时间才能显示时间。现有策划持久消息不含逐消息时间，读取或刷新时保持未知，不以当前时刻补造。当前会话刚提交的乐观消息可以显示已知发送时间；正式快照覆盖后不补造或猜配旧消息时间。
+- 策划正文保留伪流式，实时文本与正式消息按后端 `messageId` 共用一个显示位置；事件归属由项目与 `clientTurnId` 约束。同一消息的重复状态事件及命令返回只更新正文目标，不重置播放进度，不能从最后一条历史消息猜测本轮回复。没有流事件的整块新回复也逐步显示；已加载历史不重播。
+- 请求完成立即应用正式视图、释放业务忙碌状态，未完成的正文动画继续播放；动画完成只改变显示状态。一个回合内多条正文分别保留身份；工具状态独立显示，不能覆盖正文。真实 Provider 重试的空文本事件仅清空尚未持久化的对应消息；已经持久化的消息不受迟到文本重置。新回合开始时收起上轮动画并显示完整历史，切换项目清理临时显示；重置聊天作用域时同时清空活动回合与忙碌态，不依赖旧请求返回或新会话恢复来解锁输入。上轮迟到事件和命令返回不得污染新回合。
+- 终态以正式视图为准，丢弃没有进入正式消息的失败尝试文本，错误继续由既有错误区显示。正文呈现回归使用模拟原生事件与真实 React 组件，覆盖动画已追平/未追平时的重复终态、命令先返回、整块输出、工具间多条正文、重试清空、历史恢复和迟到回合。此项不改 Provider 重试、后端协议或持久数据，无迁移要求。
+
+正文呈现验收由 `appSurface/design-agent.suite.ts` 与 `designReplyAnimation.test.tsx` 覆盖：整块返回仍播放、同 ID 气泡原位接管、重复终态与命令返回幂等、多正文与重试空串、工具提示不覆盖正文、上轮请求不能结束新回合。重复终态复现用例在修复前实现上失败；`appSurface.test.ts`、动画 hook 和会话恢复测试合计 217 项通过、9 项原有跳过。App typecheck（含配置检查）、定向 ESLint、编码和文档索引检查通过。本次使用模拟原生事件及 React/jsdom，不含真实 Provider 或安装包 GUI 演练。
- ≤760px 时资源区与对话区单列排列，策划工作台在固定外壳内纵向滚动，用户向下滚动可到达输入区。布局使用内容高度，并以同等或更高选择器优先级覆盖外壳的 `height: 100%`；资源区明确为 560px，对话区高度为 `clamp(560px, calc(100dvh - 154px), 900px)`。文件树与消息列表各自内部滚动，长内容不增加两块面板高度。>760px 继续共用外壳剩余高度，不启用工作台整体滚动。正式主窗最小宽度不变，窄屏验收覆盖浏览器响应式布局。
- 审批、澄清、导入期间禁用、错误重试、项目归属和发送权限沿用现有行为。此次调整不改变 Runtime、API、持久协议或数据库，无数据迁移；不重做开发 Agent 的对话布局。
diff --git a/docs/【功能说明】AGC聊天素材引用-2026-09-08.md b/docs/【功能说明】AGC聊天素材引用-2026-09-08.md
index 940c49ff5..fcff22137 100644
--- a/docs/【功能说明】AGC聊天素材引用-2026-09-08.md
+++ b/docs/【功能说明】AGC聊天素材引用-2026-09-08.md
@@ -1,6 +1,6 @@
# AGC 聊天素材引用
-更新时间：2026-09-22
+更新时间：2026-09-23
AGC 聊天输入框支持以结构化引用标记当前项目已登记素材，并提供 Codex 风格的 Skill 提及。输入 `@` 会按素材名称、资源 ID 和类型过滤候选项；输入 `$` 会按当前 DirectProject 可用 Skill 名称过滤候选项；也可以点击输入框右侧的 `@` 按钮打开素材选择面板。
@@ -9,7 +9,7 @@ AGC 聊天输入框支持以结构化引用标记当前项目已登记素材，
`ResourceReferenceInput` 只接受宿主注入的一组「引用 provider」（`ReferenceProvider`，每种引用一个独立工厂）：
- `createResourceReferenceProvider({ assets })` → `@` 素材候选；
-- `useSkillReferenceProvider()` → `$` Skill 候选（读取应用级 Skill 目录，只在用户第一次敲出 `$` 时发生——输入区在 effect 里回调 provider 的 `onMenuQueryChange`，`match` 本身是纯函数；失败会放开重试）；
+- `useSkillReferenceProvider()` → `$` Skill 候选（读取应用级 Skill 目录，只在用户第一次敲出 `$` 时发生——输入区在 effect 里回调 provider 的 `onMenuQueryChange`，`fuzzyLookup` 本身是纯函数；失败会放开重试）；
- 附件与运行画面区域是**静默 provider**（无触发符、无候选），只参与正文 part 的身份解析、改名刷新与文本形态。
输入区按 `providers` 数组顺序取第一个非空回答，不判断任何引用种类，也没有总装 builder。**没注入就没有这类引用**：只有 DirectProject 回合会把 `agc_skill_reference` 解析成真 Skill（Rust `direct_codex_user_item_to_codex_turn_input`），所以只有它注入 Skill provider；策划输入盒、画布生成面板、资源卡快速编辑与画布生成浮层只注入资源 + 两个静默 provider，不再出现退化成正文文本的 `$` 误导入口（已裁决的缺陷修复）。
@@ -31,6 +31,29 @@ AGC 聊天输入框支持以结构化引用标记当前项目已登记素材，
输入校验按整条消息判断是否有内容：每个 `input_text` 片段都允许是空字符串、空格或换行，不逐片段拒绝，也不合并、删除或改写片段；原始文字、分段和 `content[]` 顺序保持不变。整条消息必须至少包含一段非空白文字，或至少一个非文本 part（素材引用 / 运行画面引用 / Skill 引用 / 附件引用），否则返回“聊天内容不能为空”。各类引用继续执行原有字段、数量、manifest 归属和路径安全校验；即使消息同时带有正文，非法引用也必须拒绝，不能由正文绕过。
+## 粘贴解析（2026-09-22）
+
+把含引用 token 的纯文本粘进输入区时，可以逐字命中的 token 会原位变回引用芯片：
+
+- 只认与显示口径逐字一致的 token：`@显示名`（素材）与 `$名称`（Skill）。`@hero.png`、资源 ID、大小写变体、全角 `＠` 都不解析；token 前后必须是行首 / 行尾或空白（与出站文本「token 前后各留一个空白」自洽），所以从用户消息气泡复制出来的那段文字粘回来会重建同一批芯片。
+- 宁可不成芯片也不能认错：同名多候选（同一个 token 对应多条引用身份）一律按文本保留；未命中的 token 静默保留，不提示、也不猜文件名或路径。
+- 名字为空的引用（token 只剩一个裸触发符）同样不参与解析：裸 `@` / `$` 会在正文里匹配到任何一处触发符，认下来就是把无关文字错认成引用。显示名一侧另有兜底（见下节「词干为空的素材名回退 `asset.id`」），这条是解析侧的最后一道。
+- 附件与运行画面区域的 token（`@附件名` / `@区域标签`）不参与解析——这两类引用没有候选，身份来自文件与运行记录，纯文本重建不出来，所以粘贴时按文本保留。
+- 只有真的解析出引用、并且这一整段真的插进了正文时才接管粘贴：同 namespace 的 Lexical 负载（跨输入区复制芯片）、不含 token 的纯文本、图片文件粘贴都继续走编辑器默认导入，现有行为不变。取不到选区时插入为空，这时也放行默认粘贴，粘贴的文字不会「两边都不管」。接管时整段文本在一次编辑更新内插入，一次 Ctrl+Z 就是一次撤销。
+- part 落进正文时解析不出引用也不留空：先退回 provider 的 `mentionToken`（`@显示名` / `$名称`），provider 连 token 都答不出来（契约被破坏）时退到 `contentPartText` 的通用文本形态——资源拿不到显示名就落 `@resourceId`，Skill / 附件 / 运行区域各落自己的名字或标签。粘贴就地插入与润色回写的整根替换共用这一条兜底链（`mentionTokenOrText`），所以「认不出的引用走文本、绝不静默丢」没有例外分支。
+- 候选来源按「模糊 / 精确」分两个口：菜单走 `fuzzyLookup(query)`（包含匹配 + 截断到候选上限），粘贴解析走 `lookup()`（就绪的全量候选，不模糊、不截断）。
+- Skill 目录是应用级异步读取，仍然只在用户第一次敲出 `$` 时读：冷启动时粘贴 `$名称` 就按字面文本保留（粘贴不会为了解析去提前读盘，也不会等待目录），用户敲过一次 `$` 之后粘贴即可重建芯片。
+
+## 引用名的空白不变量（2026-09-23）
+
+引用的名字（素材显示名、Skill 名、附件名）同时就是它在正文里的 token，所以**名字内部不允许出现空白**：内部空白统一经共享的 `normalizeMentionName` 折成 `-`（`hero v2.png` → `@hero-v2`、`my skill` → `$my-skill`），首尾空白照旧裁掉。
+
+- 归一化落在名字的产生处：`resourceDisplayName()`（素材显示名由文件名派生）、Skill 目录读入与 `toReference` / `mentionToken`、附件导入映射与 `toReference` / `mentionToken`、以及两个 token 投影（`chatReferenceMentionToken`、`directCodexContentToPromptText`）。token 层再折一次是幂等的，因此「token 里绝不会有空白」是这一层的性质，不依赖上游数据干净。
+- 为什么必须有这条不变量：token 的边界规则是「前后为空白或行首行尾」。名字里带空白时，`@hero v2` 会被反解析切成 `@hero` + 文本 `v2`，短名字抢先命中，真正的引用反而被当成孤儿补到正文末尾（粘贴回填会多出一枚错芯片）。折成 `-` 之后 token 自带边界，`@hero` 不会命中 `@hero-v2`（后一个字符是 `-`）。
+- 词干为空的素材名回退 `asset.id`：整名就是扩展名时（`.env` / `.gitignore`）文件名去掉扩展名会得到空串，空名字会让 token 退化成只有触发符的裸 `@`——候选菜单里是一枚空芯片，粘贴解析还会拿它认领正文里任何一处裸 `@`。所以 `resourceDisplayName()` 在这一种情况下回退 `asset.id`，回退值同样过一遍 `normalizeMentionName`；`normalizeMentionName` 自身仍然只做归一化、不做兜底。
+- 归一化不保证名字唯一：`hero v2` 与 `hero-v2` 会折成同一个 token，候选菜单里两条候选显示同一个标签，从气泡复制出来的那段文字也重建不成芯片（解析侧按「同名多候选一律按文本保留」处理，不认错）。菜单侧目前不做冲突检测，这是这条不变量的已知残留。
+- 已存在的老文本（本次改动前生成的回合 prompt、历史气泡）里的 `@hero v2` 不再解析——粘贴时按字面保留，重试 / 润色回填时该引用会退化成末尾孤儿。内容不丢，位置可能不对。
+
## 拖拽引用（2026-09-21）
除了 `@` 输入与「引用」按钮，资源卡还支持**拖到对话**：在资源画布上按住一张卡拖到右侧 Agent 对话栏，松手即把这次拖动真正参与位移的那批素材整批 `@` 进输入框（框选多选后拖任意一张 = 整批引用；拖未选中的卡 = 只引用它自己）。
diff --git a/docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md b/docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md
index 8c77b20fe..925580bd1 100644
--- a/docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md
+++ b/docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md
@@ -176,7 +176,7 @@ npm run check:server-rs-ddd
22. 后台主动退款只支持 `wechat_mp`、`wechat_jsapi`、`wechat_h5`、`wechat_native` 普通 V3 泥点订单。`api-server` 必须先按正式支付渠道和商品类型拦截不支持的订单，再做微信支付订单查单预检，然后调用 SpacetimeDB procedure 原子创建退款 hold；只有 hold 成功才允许调用微信退款。`wechat_mp_virtual`、历史非正式渠道值、会员、未支付、对账未完成、退款已满额、人工冻结、退款欠账或永久泥点不足必须在调用普通 V3 provider 前 fail-closed。
23. `profile_recharge_refund_hold` 以稳定 `out_refund_no` 为主键，保存订单、用户、本次退款金额、占用永久泥点、管理员、原因和 `active / settled / released` 状态。重试只有在订单、`out_refund_no`、退款金额、管理员和归一化原因全部与原 hold 一致时才可复用，任一不一致都按幂等内容冲突 fail-closed，不能用新原因调用微信后保留旧审计。部分退款的 hold 在累计应追回增量之外额外保留 1 泥点并发舍入缓冲，全额退款不加缓冲；活动 hold 不改变钱包总额，但普通钱包消费必须预留全部活动 hold；成功退款 observation 扣款并结算匹配 hold，关闭退款释放 hold，外部退款追回不得消耗其他活动 hold。
24. 退款欠账继续以 `profile_recharge_order_refund_settlement.unrecovered_points` 为唯一真相；不新增平行 debt 累计。`profile_wallet_manual_restriction` 只保存人工冻结，普通消费同时检查人工冻结与退款欠账。后续永久泥点到账后继续偿还欠账，每日免费与会员周期泥点不参与；解除人工冻结不得清除退款欠账限制。
-25. 管理员充值订单、用户详情、历史花费手动对账、退款预检/执行、应急退款号登记、退款人工复核和钱包冻结接口只留在 `api-server` 管理员鉴权路由。用户详情中的历史花费泥点数读取 `profile_wallet_consumption_total` 投影；已有投影时，每次 `asset_operation_consume` 负向流水落账在同一事务内按主键 O(1) 原子累加，退款不回减，充值退款追回、余额重置、赠送和 hold 均不计入。首次上线必须在停止业务写入的维护窗口内，由 owner 调用 `POST /admin/api/profile/users/initialize-consumption-projections`，一次扫描全部权威钱包流水，为每个已有钱包流水的用户初始化存量投影；接口成功后才能恢复流量。维护遗漏或新用户缺行时，首次消费按该用户索引一次性重建（当前消费流水已经在同一事务中，不能重复加本次金额）；钱包详情首次读取也保留同一按用户兜底。`POST /admin/api/profile/users/reconcile-consumption` 是显式手动对账入口：owner 始终可用，member 必须单独持有 `profile-wallet-consumption-reconcile` 操作权限，任何一级 Tab 都不自动附带；用户详情只在后端返回 `canReconcileConsumption=true` 时展示按钮。操作经二次确认后扫描该用户全部权威钱包流水、比较并校准投影，同时记录管理员和对账时间。退款人工复核 BFF 必须从管理员会话写入操作人，要求非空原因，返回微信退款交易号、订单总额以及获批错误码等正式审计字段，并调用 runtime service identity 受限 procedure；后台确认面板必须展示这些后端事实，前端不得自行改 settlement、钱包冻结或消费累计。外部微信副作用由 `platform-wechat` 执行，退款/hold/钱包事务留在 `spacetime-module`，后台前端只展示 BFF 返回的正式状态。
+25. 管理员充值订单、用户详情、历史花费手动对账、退款预检/执行、应急退款号登记、退款人工复核和钱包冻结接口只留在 `api-server` 管理员鉴权路由。用户详情中的历史花费泥点数读取 `profile_wallet_consumption_total` 投影；已有投影时，每次 `asset_operation_consume` 负向流水落账在同一事务内按主键 O(1) 原子累加，退款不回减，充值退款追回、余额重置、赠送和 hold 均不计入。首次上线必须在停止业务写入的维护窗口内，由 owner 调用 `POST /admin/api/profile/users/initialize-consumption-projections`，一次扫描全部权威钱包流水，为每个已有钱包流水的用户初始化存量投影；接口成功后才能恢复流量。维护遗漏或新用户缺行时，首次消费按该用户索引一次性重建（当前消费流水已经在同一事务中，不能重复加本次金额）；钱包详情首次读取也保留同一按用户兜底。`POST /admin/api/profile/users/reconcile-consumption` 是显式手动对账入口：owner 始终可用，member 必须单独持有 `profile-wallet-consumption-reconcile` 操作权限，任何一级 Tab 都不自动附带；用户详情只在后端返回 `canReconcileConsumption=true` 时展示按钮。操作经二次确认后扫描该用户全部权威钱包流水、比较并校准投影，同时记录管理员和对账时间。退款人工复核 BFF 必须从管理员会话写入操作人，要求非空原因，返回微信退款交易号、订单总额以及获批错误码等正式审计字段，并调用 runtime service identity 受限 procedure；后台确认面板必须展示这些后端事实，前端不得自行改 settlement、钱包冻结或消费累计。外部微信副作用由 `platform-wechat` 执行，退款/hold/钱包事务留在 `spacetime-module`，后台前端只展示 BFF 返回的正式状态。充值订单实付金额（`paidAmountCents`）同样由后端判定：只有 `paid_at` 存在的订单才有实付，未支付、已关闭、已过期订单固定为 `0`，后台前端不得拿订单金额（`amountCents`）顶替实付；订单发放泥点（`pointsDelta`）必须与实付分开成列展示。用户详情的累计充值金额（`cumulativeRechargedCents`）由 api-server 按 `user_id` 受控读取 `profile_recharge_order`、只累加 `paid_at` 存在的订单 `amount_cents`（退款不回减）得出；读取失败或命中单次读取上限时返回 `null`，前端按未知展示，不得用用户详情最多 20 条订单在 BFF 或前端近似重算。
## 用户钱包与编辑器生成扣费契约
@@ -767,7 +767,7 @@ Responses 的终态载荷既是工具调用的恢复源，也是正文的恢复
- Rust 结构体：`ProfileRedeemCode`
- 源码：`server-rs/crates/spacetime-module/src/runtime/profile.rs`
- 生效时间：复用邀请码时间窗口语义，`starts_at` / `expires_at` 均可为空；两者同时存在时必须满足 `starts_at < expires_at`。开始时刻计入有效区间，截止时刻不计入有效区间。用户兑换时以后端接收的 `redeemed_at_micros` 判定：未到开始时间拒绝为“兑换码未生效”，到达或超过截止时间拒绝为“兑换码已过期”。
-- 后台契约：`AdminUpsertProfileRedeemCodeRequest` 通过可空 `startsAt` / `expiresAt` 接收 RFC3339 时间，列表与保存响应同步返回这两个字段；后台页只负责输入、回填和显示，真正兑换判定留在后端事务路径。
+- 后台契约：`AdminUpsertProfileRedeemCodeRequest` 通过可空 `startsAt` / `expiresAt` 接收 RFC3339 时间，列表与保存响应同步返回这两个字段；后台页只负责输入、回填和显示，真正兑换判定留在后端事务路径。`reward_points` 是奖励泥点（兑换成功后按 `redeem_code_reward` 流水进入泥点钱包），不是金额；后台奖励输入与列表必须带泥点单位。
### `profile_redeem_code_usage`
diff --git a/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md b/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md
index 4c9529a08..f38316f86 100644
--- a/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md
+++ b/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md
@@ -895,7 +895,7 @@ worker 被硬杀或断电后，lease 过期任务只有尚未耗尽 `max_attempt
- Server provision 不再通过 Windows helper 下载，也不再通过 Linux build 节点中转 SpacetimeDB / otelcol 工具包；Linux build 节点只负责从内网 Git 源准备 provision 脚本和配置并上传给目标 agent。`Prepare Provision Tools` 在目标 dev / release agent 工作区内先检查 `/usr/local/bin/otelcol-contrib` 与 `${SPACETIME_ROOT}/bin/current`：SpacetimeDB 必须同时匹配运行版本 `2.8.3` 和 commit `8e410d28...` 才能复用；只有缺失或版本 / commit 不匹配时才使用 `PROVISION_DOWNLOADS_DIR` 里的本地包或从配置的下载源准备官方 `v2.8.3` 资产。`SPACETIME_EXPECTED_COMMIT` 与下载根必须成对调整，安装结果也执行同一 commit 门禁。otelcol-contrib 当前锁定 `0.151.0`；如果目标服务器下载需要代理，在 `PROVISION_DOWNLOAD_PROXY` 配置目标机可访问的 HTTP 代理。
- 除 `Genarrative-Server-Provision` 外，`Genarrative-Stdb-Module-Build`、`Genarrative-Web-Build`、`Genarrative-Api-Build`、`Genarrative-*Deploy`、`Genarrative-Database-Import/Export`、`Genarrative-Full-Build-And-Deploy` 和 `Genarrative-Notify-Email` 的生产流水线现都以 Linux agent 为主，仍按各自 Jenkinsfile 的 checkout 口径执行。Server provision 不使用公网备用 Git 源，目标部署 agent 也不再需要访问源码 Git remote。
- `otelcol-contrib.service` 作为可选系统服务加入 provision，默认监听 `127.0.0.1:4317/4318` 并使用 `deploy/otelcol/genarrative-debug.yaml`。api-server 是否发送 OTLP 仍由 `GENARRATIVE_OTEL_ENABLED` 控制，服务 unit 见 `deploy/systemd/otelcol-contrib.service`。该服务必须存在系统用户 / 组 `otelcol`，并且 `/etc/otelcol/genarrative-debug.yaml` 已安装到目标机；若看到 `status=217/USER` 或 `Failed to determine user credentials`，优先检查 `getent passwd otelcol`，再补齐 `/etc/otelcol` 配置目录并重启服务。
-- Nginx `/api/` 与 `/admin/api/` 通过 `genarrative_api` upstream 代理到 `127.0.0.1:8082`，upstream keepalive 为 64；通用 API 使用 `genarrative_api_rps`，后台 API 使用 `genarrative_admin_rps`。通用 `/api` location 保留 `client_max_body_size 64m` 作为编辑器图片、视频和文档请求的反代兜底，真实大小仍由路由与业务校验负责。若线上出现 `413 Request Entity Too Large` 且 access log 中 `request_time=0.000`、`upstream_status=-`，说明请求在 Nginx 层被拦截，先核对 release 模板与实际媒体大小。`limit_conn_status 429` 和 `limit_req_status 429` 必须在 HTTP 与 HTTPS server 中同时生效。
+- Nginx `/api/` 与 `/admin/api/` 通过 `genarrative_api` upstream 代理到 `127.0.0.1:8082`，upstream keepalive 为 64；通用 API 使用 `genarrative_api_rps`，后台 API 使用 `genarrative_admin_rps`。通用 `/api` location 保留 `client_max_body_size 210m` 作为编辑器图片、视频、文档请求与游戏发行包 PUT（路由上限 200 MiB + 1 KiB）的反代兜底，真实大小仍由路由与业务校验负责；使用 Pingora 网关时 `GENARRATIVE_PINGORA_GATEWAY_MAX_API_BODY_BYTES` 必须同步不低于该值，否则网关侧会先返回 413。若线上出现 `413 Request Entity Too Large` 且 access log 中 `request_time=0.000`、`upstream_status=-`，说明请求在 Nginx 层被拦截，先核对 release 模板与实际媒体大小。`limit_conn_status 429` 和 `limit_req_status 429` 必须在 HTTP 与 HTTPS server 中同时生效。
容器化隔离部署方案单独放在 `deploy/container/`，用于本机或预发模拟现有的 Linux release + Nginx + OTLP Collector 非 BgFilter 拓扑，不替换当前生产 `systemd + Nginx + Jenkins` 发布路径。当前 compose 没有 `bgfilter-worker`，不构成完整 BgFilter 预发拓扑，也不覆盖任何会触发 BgFilter 的现役任务；它只用于非 BgFilter 路径，或通过下述 unsupported job smoke 验证外部生成队列的 claim / fail 回写和 API-only 更新。当前容器模拟参数保留 `genarrative-release` 的 CPU、`nofile=4096` 与 `worker_connections=768` 采样口径，并在 compose 里落实到 `spacetimedb cpus=1.0 mem_limit=2g`、`api-server cpus=2.0 mem_limit=1g`、`external-generation-worker cpus=2.0 mem_limit=1g`、`nginx cpus=0.5 mem_limit=128m`、`otelcol cpus=0.25 mem_limit=128m`。完整模块首次实例化会超过旧 `896m` cgroup 上限，因此 SpacetimeDB 必须使用 `2g`；这不改变生产服务资源合同。容器 `api-server` 默认 `GENARRATIVE_API_WORKER_THREADS=4`，只增加 Tokio worker 调度并发，不突破 `api-server cpus=2.0` 的 CPU 配额；容器默认 `GENARRATIVE_EXTERNAL_GENERATION_MODE=queue`，可用 `npm run container:up -- --scale external-generation-worker=N external-generation-worker` 验证不经过 BgFilter 的外部生成 worker 动态扩缩容，`inline` 模式不参与该验证：
diff --git a/docs/【玩法创作】平台入口与玩法链路-2026-05-15.md b/docs/【玩法创作】平台入口与玩法链路-2026-05-15.md
index accee82c1..e30e1e175 100644
--- a/docs/【玩法创作】平台入口与玩法链路-2026-05-15.md
+++ b/docs/【玩法创作】平台入口与玩法链路-2026-05-15.md
@@ -84,13 +84,14 @@
1. AGC 发布取当前 npm 工程已成功构建的 `dist/` 内容，重新检查入口和实际字节；ZIP 内部必须把 `dist/index.html` 归一化为根 `index.html`，其余路径相对发行根保持不变。不得上传整个项目、源码快照或仅发送本地路径。网页 ZIP 同样要求根 `index.html`，不猜测并自动剥离多层目录。
2. 所有运行依赖都必须在发行包内。资源 URL 使用与发行版本目录兼容的相对地址；前导 `/assets`、本地文件 URL、外部脚本/样式/媒体/字体地址均不属于可接受发行合同。客户端给出可操作错误，服务器仍独立校验；静态校验不能代替运行时 CSP 阻断。
-3. 建议首版限额：压缩包 100 MiB、展开总量 250 MiB、单文件 64 MiB、最多 10,000 个文件、展开/压缩比不超过 100。服务端拒绝加密 ZIP、重复或大小写冲突路径、绝对路径、`..`、符号链接/重解析点、设备文件和嵌套压缩包；拒绝 `.agent`、版本控制目录、`node_modules`、凭据文件与源码映射文件。超限返回明确错误，不截断后继续发布。
+3. 现行限额：压缩包 200 MiB、展开总量 500 MiB、单文件 64 MiB、最多 10,000 个文件、展开/压缩比不超过 100。压缩包上限同时决定 `api-server` 的发行包路由请求体上限（200 MiB + 1 KiB）与反代放行量：Nginx 通用 `/api` location 为 `client_max_body_size 210m`，Pingora 网关为 `GENARRATIVE_PINGORA_GATEWAY_MAX_API_BODY_BYTES=220200960`；三者必须同时满足，否则合法包会在反代或路由层被 413。服务端拒绝加密 ZIP、重复或大小写冲突路径、绝对路径、`..`、符号链接/重解析点、设备文件和嵌套压缩包；拒绝 `.agent`、版本控制目录、`node_modules`、凭据文件与源码映射文件。超限返回明确错误，不截断后继续发布。超过约 100 MiB 的包在 `api-server` 会带来数百 MB 的瞬时内存占用，发布窗口与实例规格需按容量验证基线预留。
4. 提交声明 ZIP 的 SHA-256 与字节数，服务端对收到的真实 ZIP 重新计算，再对展开文件建立相对路径、字节数和 SHA-256 清单。摘要不一致、缺文件或入口损坏时停止；只有 metadata 而没有已确认完整对象的提交必须失败。
5. 游戏资料随发行版本冻结：标题 2–40 字、短简介不超过 120 字、详细介绍不超过 2,000 字、一个分类、最多 5 个标签（每个不超过 20 字）、必需封面、最多 6 张截图、操作方式不超过 240 字。分类首版为休闲、益智、动作、冒险、模拟、策略、其他；封面/截图复用平台图片上传与归属校验，不接受任意外链作为审核图片。作者不需要自己构建或打 ZIP：AGC 发布时对 `game/` 子工程按需执行 `npm install`（复用 `project.bootstrap`）与 `npm run build`（复用 `project.verify` 的受控 npm 运行器，脚本白名单含 `build`、禁止项目级 `.npmrc` 改写语义），再把 `game/dist` 归一化成根 `index.html` 的发行包上传；已有可玩入口（`game/index.html` 或 `dist/index.html`）时跳过构建。Phaser 4 + Vite 已按此口径端到端验证（构建产物、发行网关与网页沙箱播放）。发布入口按灰度下发：后端灰度配置键固定为 `game-distribution:publish`（后台「灰度发布配置」可改，支持 `enabled` / `rolloutPercent` / `allowUserIds` / `allowUserTags`）。灰度默认关闭：未配置该键、或 `enabled=false` 时，未登录与已登录作者都拿到不开放（发布入口不渲染、写入口 503）；运营在后台创建该键并 `enabled=true` 后，只有白名单 / 灰度比例 / 用户标签命中的作者拿到开放状态。发布入口的开放状态随 `/api/runtime/frontend-config` 的 `gameDistributionPublishEnabled` 下发，网页广场/我的游戏入口与 AGC 聊天头「发布到游戏广场」按钮据此显示或隐藏；写入口仍独立校验，收紧期间提交返回 503 与可读文案，读接口、目录、详情、发行网关与安全下架不受影响。作者续发时按版本冻结快照回填封面与截图并复用同一批素材；公开投影只暴露对象键，素材 ID 只在作者与管理员回读时返回，快照里缺素材 ID 的旧版本必须要求作者重新选择封面。AGC 发布面板不展示 ZIP 路径、文件数或体积等技术摘要；一句话简介与分类可根据有界、脱敏的创作上下文免费生成（不扣用户泥点，仍可编辑），分类必须收敛到上述白名单；游戏封面支持基于项目上下文生成，生成走现役图片生成与泥点扣费链路，产物必须登记为当前账号平台素材后才能作为 `coverAssetId` 提交。
6. `supportedDevices` 至少包含 `desktop` 或 `mobile`；`inputModes` 来自 `keyboard`、`mouse`、`touch`；声明移动端必须包含 `touch`。`orientation` 为 `landscape`、`portrait` 或 `responsive`。这些是待人工复核的作者声明，目录只显示已经随版本审核通过的值。
7. 原始 ZIP、未审核展开目录、审核资料均为私有对象；公开版本不暴露源码镜像键、本地路径、访问凭据或私有账号元数据。运行文件只能由发行网关按游戏、版本和文件白名单读取，不能绕过网关访问公开 OSS bucket。
8. 现役发行网关由 `api-server` 提供：`GET /api/game-distribution/releases/{gameId}`（含尾斜杠）等价于该游戏的 `index.html`，`GET /api/game-distribution/releases/{gameId}/{assetPath}` 只服务当前已公开版本包内的文件，私有 ZIP 与未公开版本不因知道 ID 而可读。响应按扩展名白名单设定内容类型，未知扩展名返回 404；全部响应带 `X-Content-Type-Options: nosniff`、`Cross-Origin-Resource-Policy: cross-origin` 与不带 credentials 的 `Access-Control-Allow-Origin: *`（发行文档运行在 `allow-scripts` 的 opaque origin 沙箱里，`same-origin` 会让游戏自己的脚本被浏览器拦下），HTML 追加最小权限 CSP。带平台 `Cookie` 的请求一律 `403`，避免发行文件被主站同源读取；发行网关必须部署在独立来源。发行包按对象键在进程内做有界缓存，单个超预算包不进入缓存。
9. 审核通过时必须提交绝对 HTTPS `entryUrl`，且不接受凭据、query 和 fragment；服务端不根据请求 Host 或本地路径拼默认发行地址，避免把内网地址或主站来源写进公开投影。 非生产环境额外允许 http 回环地址（`127.0.0.1` / `localhost` / `[::1]`），口径与前端 `normalizeGameEntryUrl` 一致，便于本地在没有 TLS 的情况下验证内嵌游玩；生产环境只接受 HTTPS。
+10. 上传有两条等价入口，共用同一版本状态机、摘要口径、幂等键与校验规则：① 整包入口——网页端与旧客户端对 `versionId` 直接 `PUT` 整包字节，原子、不可续传，仍受发行包上限与请求体限制约束；② 分片续传入口——AGC 原生一键发布对同一 `versionId` 顺序上传固定大小的分片，再以单独的完成动作收口。分片大小由服务端下发且固定（现为 8 MiB，随发行包上限 200 MiB 取整到 25 片以内），客户端不得自行改变；分片续传入口只补传缺失字节，任何分片重复或乱序都不得造成重复写入。AGC 侧必须由原生进程直接读取本地试玩包并按分片发送，整包字节不得经过 WebView IPC 往返，也不得整包驻留宿主内存。
### 身份、状态、审核与更新
@@ -106,7 +107,9 @@
### 幂等、并发与恢复
- 所有创建、提交、审核、撤销和下架动作携带 `Idempotency-Key`。服务端以认证主体、动作和 key 保存请求摘要与结果；同 key 同请求返回原结果，同 key 不同请求返回 `409 IDEMPOTENCY_CONFLICT`。至少保留 30 天；客户端超出恢复窗口先回读记录，不能把未知结果自动当作失败重发。
-- 同一个版本只能确认一份 ZIP：中断重传仍使用同 `versionId` 和摘要，已确认相同字节直接返回成功，不同摘要返回 409。上传中同版本第二个写入返回 `409 UPLOAD_IN_PROGRESS`；未确认半包不会进入校验。首版整包重传，不宣称支持分片断点续传。
+- 同一个版本只能确认一份 ZIP：中断重传仍使用同 `versionId` 和摘要，已确认相同字节直接返回成功，不同摘要返回 409。上传中同版本第二个写入返回 `409 UPLOAD_IN_PROGRESS`；未确认半包不会进入校验。
+- 分片续传以「服务端已收字节」为唯一权威偏移：客户端带上自己认为的偏移上传分片，与服务端记录不一致时服务端返回 `409` 与权威偏移，客户端按权威偏移继续，不重放也不跳段。传输失败、网络中断、客户端进程退出或应用重启后，同一 `versionId` 重新发布只补传缺失分片；已收字节数由服务端持久化事实决定，不依赖客户端本地记录。
+- 分片会话在全部字节到齐并执行完成动作之前，不进入包校验、不确认版本、不改变任何公开可见性，半包对象也不服务给发行网关。完成动作里校验失败时删除该半包对象并把版本落到 `upload_failed`（`recoveryAction=reupload`）；作者要重新上传同一版本时必须先显式重置分片会话，重置后已收字节归零，不允许在半包之上续写不同字节。
- 重复提交同一次 AGC 操作不得创建第二个游戏或版本；原生端持久保存操作 ID、目标游戏/版本和 key，网页保存恢复标识并以服务端回读为准。相同 ZIP 用于不同资料修订时允许新版本，不能仅按包摘要吞掉新的发布意图。
- 公开版本切换、作者下架和管理员审核必须带 `expectedPublicationRevision`，在持久化事务中比较并推进。并发变化返回 `409 PUBLICATION_CONFLICT`；旧送审版本不能在用户已发布更新或下架之后静默覆盖状态。审核员重新查看现状后才能提交新的明确动作。
- 网络中断或响应丢失后先查询原操作/版本；服务端恢复 `validating` 的在途任务并按版本身份幂等续作，不另建版本。登录失效保留私有草稿和恢复标识，重新登录同账号后继续；换账号不能读取或接管原账号操作。
diff --git a/server-rs/crates/api-server/src/admin.rs b/server-rs/crates/api-server/src/admin.rs
index 2f9838531..572ed19aa 100644
--- a/server-rs/crates/api-server/src/admin.rs
+++ b/server-rs/crates/api-server/src/admin.rs
@@ -70,6 +70,7 @@ use spacetime_client::{
};
use time::{OffsetDateTime, format_description::well_known::Rfc3339};
use tokio::sync::{OnceCell, Semaphore};
+use tracing::warn;
use crate::{
admin_accounts::normalize_admin_account_username,
@@ -2383,6 +2384,7 @@ struct AdminDashboardAssetStats {
#[derive(Default)]
struct AdminDashboardWalletStats {
consumed_mud_points: AdminDashboardSeries,
+ refunded_mud_points: AdminDashboardSeries,
recharged_mud_points: u64,
warnings: Vec,
}
@@ -2419,12 +2421,22 @@ async fn build_admin_dashboard(
let user_stats = fetch_admin_dashboard_user_stats(state, &range, now_micros).await?;
+ let day_keys = range.day_keys();
+ // 消耗泥点按日对冲退还：每日净额不为负，区间合计等于「消耗 − 退还」。
+ let net_consumed_mud_points = net_admin_dashboard_consumed_mud_points(
+ &wallet_stats.consumed_mud_points,
+ &wallet_stats.refunded_mud_points,
+ &day_keys,
+ );
+
let generated_assets = asset_stats.generated_assets.total();
- let consumed_mud_points = wallet_stats.consumed_mud_points.total();
+ let consumed_mud_points = net_consumed_mud_points.total();
+ let refunded_mud_points = wallet_stats.refunded_mud_points.total();
let new_registered_users = user_stats.new_registered_users.total();
let metrics = AdminDashboardMetricsPayload {
generated_assets,
consumed_mud_points,
+ refunded_mud_points,
total_registered_users: user_stats.total_registered_users,
new_registered_users,
day1_retention: user_stats.day1_retention.clone(),
@@ -2450,8 +2462,16 @@ async fn build_admin_dashboard(
"consumed-mud-points",
"消耗泥点",
"泥点",
- &wallet_stats.consumed_mud_points,
- wallet_stats.consumed_mud_points.total(),
+ &net_consumed_mud_points,
+ net_consumed_mud_points.total(),
+ &range,
+ ),
+ build_admin_dashboard_chart(
+ "refunded-mud-points",
+ "退还泥点",
+ "泥点",
+ &wallet_stats.refunded_mud_points,
+ refunded_mud_points,
&range,
),
build_admin_dashboard_chart(
@@ -2719,6 +2739,10 @@ async fn fetch_admin_dashboard_wallet_stats(
.consumed_mud_points
.add(day_key, amount_delta.unsigned_abs());
}
+ // 生成失败 / 精选审核返还，以及 LLM Router 的正向冲正流水，都按退还对冲消耗。
+ "asset_operation_refund" | "llm_router_consume" if amount_delta > 0 => {
+ stats.refunded_mud_points.add(day_key, amount_delta as u64);
+ }
"points_recharge" if amount_delta > 0 => {
stats.recharged_mud_points = stats
.recharged_mud_points
@@ -2809,6 +2833,61 @@ async fn fetch_admin_dashboard_rows(state: &AppState, sql: &str) -> Result Option {
+ let sql = format!(
+ "SELECT amount_cents, paid_at FROM profile_recharge_order WHERE user_id = {} LIMIT {}",
+ quote_sql_string(user_id),
+ ADMIN_USER_RECHARGE_SUMMARY_ROW_LIMIT
+ );
+ let rows = match fetch_admin_dashboard_rows(state, &sql).await {
+ Ok(rows) => rows,
+ Err(message) => {
+ warn!(user_id, error = %message, "读取用户累计充值失败");
+ return None;
+ }
+ };
+ if rows.len() >= ADMIN_USER_RECHARGE_SUMMARY_ROW_LIMIT as usize {
+ warn!(
+ user_id,
+ limit = ADMIN_USER_RECHARGE_SUMMARY_ROW_LIMIT,
+ "用户累计充值命中单次读取上限，按未知处理"
+ );
+ return None;
+ }
+ Some(sum_admin_user_recharged_cents(&rows))
+}
+
+/// 汇总 `profile_recharge_order` 查询行：只累加 `paid_at` 存在（真实支付过）的订单金额。
+/// SpacetimeDB HTTP SQL 会把 `Option` 返回成 `[micros]`、`[0, micros]` 或 `[1, []]` 等 SATS 形态。
+fn sum_admin_user_recharged_cents(rows: &[Value]) -> u64 {
+ let mut total = 0_u64;
+ for row in rows {
+ let Some(columns) = row.as_array() else {
+ continue;
+ };
+ let Some(amount_cents) = columns.first().and_then(value_to_i64) else {
+ continue;
+ };
+ let paid = columns
+ .get(1)
+ .is_some_and(|value| timestamp_value_to_micros(value).is_some());
+ if paid && amount_cents > 0 {
+ total = total.saturating_add(amount_cents as u64);
+ }
+ }
+ total
+}
+
fn build_admin_dashboard_chart(
id: &str,
title: &str,
@@ -2982,6 +3061,40 @@ impl AdminDashboardSeries {
}
}
+/// 消耗泥点按日对冲退还：先抵当日消耗，不足再回溯抵扣最近仍有净额的业务日。
+/// 抵扣不完的退还直接丢弃，保证每日净额非负，且区间合计等于「消耗 − 退还」。
+fn net_admin_dashboard_consumed_mud_points(
+ consumed: &AdminDashboardSeries,
+ refunded: &AdminDashboardSeries,
+ day_keys: &[i64],
+) -> AdminDashboardSeries {
+ let mut remaining: Vec = day_keys
+ .iter()
+ .map(|day_key| consumed.value(*day_key))
+ .collect();
+ for (index, day_key) in day_keys.iter().enumerate() {
+ let mut pending = refunded.value(*day_key);
+ if pending == 0 {
+ continue;
+ }
+ for back in (0..=index).rev() {
+ if pending == 0 {
+ break;
+ }
+ let applied = remaining[back].min(pending);
+ remaining[back] -= applied;
+ pending -= applied;
+ }
+ }
+ let mut series = AdminDashboardSeries::default();
+ for (index, day_key) in day_keys.iter().enumerate() {
+ if remaining[index] > 0 {
+ series.add(*day_key, remaining[index]);
+ }
+ }
+ series
+}
+
fn build_spacetime_schema_url(server_root: &str, database: &str) -> String {
format!("{server_root}/v1/database/{database}/schema?{SPACETIME_SCHEMA_VERSION_QUERY}")
}
@@ -4786,26 +4899,27 @@ fn build_admin_session_payload(session: crate::state::AdminSession) -> AdminSess
#[cfg(test)]
mod tests {
use super::{
- AdminDashboardGranularity, AdminDisplayNameDirectory, EditorShowcaseAssetRecord,
- admin_dashboard_user_stats_from_record, admin_dashboard_user_stats_from_result,
- admin_editor_asset_group_payload, admin_editor_asset_payload_from_record,
- admin_editor_showcase_asset_payload_from_record, append_spacetime_sql_response_chunk,
- apply_admin_database_table_filters, build_admin_asset_read_url_audit,
- build_admin_dashboard_chart, build_admin_database_table_row,
- build_admin_editor_showcase_campaign_image_confirm_request,
+ AdminDashboardGranularity, AdminDashboardSeries, AdminDisplayNameDirectory,
+ EditorShowcaseAssetRecord, admin_dashboard_user_stats_from_record,
+ admin_dashboard_user_stats_from_result, admin_editor_asset_group_payload,
+ admin_editor_asset_payload_from_record, admin_editor_showcase_asset_payload_from_record,
+ append_spacetime_sql_response_chunk, apply_admin_database_table_filters,
+ build_admin_asset_read_url_audit, build_admin_dashboard_chart,
+ build_admin_database_table_row, build_admin_editor_showcase_campaign_image_confirm_request,
build_admin_external_api_key_sql, build_admin_tracking_event_keys_sql,
build_admin_tracking_events_sql, build_body_preview, build_debug_base_url,
build_spacetime_schema_url, clamp_admin_database_table_limit,
clamp_admin_tracking_event_limit, enforce_admin_request_permission,
fetch_admin_database_table_rows, finalize_admin_database_table_rows_response,
group_admin_editor_asset_records, hash_admin_password, is_admin_account_not_found,
- is_safe_spacetime_table_name, normalize_debug_path, normalize_table_count_error,
- paginate_admin_editor_asset_records, parse_admin_database_table_rows_sql_response,
- parse_admin_external_api_key_row, parse_admin_tracking_event_keys_sql_response,
- parse_admin_tracking_events_sql_response, parse_spacetime_sql_count_response,
- parse_timestamp_text_to_micros, resolve_admin_dashboard_range,
- resolve_admin_dashboard_range_at, resolve_admin_database_table_sql_limit,
- resolve_admin_editor_asset_filters, timestamp_value_to_micros, trim_preview,
+ is_safe_spacetime_table_name, net_admin_dashboard_consumed_mud_points,
+ normalize_debug_path, normalize_table_count_error, paginate_admin_editor_asset_records,
+ parse_admin_database_table_rows_sql_response, parse_admin_external_api_key_row,
+ parse_admin_tracking_event_keys_sql_response, parse_admin_tracking_events_sql_response,
+ parse_spacetime_sql_count_response, parse_timestamp_text_to_micros,
+ resolve_admin_dashboard_range, resolve_admin_dashboard_range_at,
+ resolve_admin_database_table_sql_limit, resolve_admin_editor_asset_filters,
+ sum_admin_user_recharged_cents, timestamp_value_to_micros, trim_preview,
validate_admin_editor_asset_cursor, validate_admin_external_api_key_query,
verify_admin_password, wallet_ledger_source_type_to_string,
};
@@ -5732,6 +5846,97 @@ mod tests {
);
}
+ /// 消耗泥点必须按退还对冲，且每日净额非负、区间合计等于「消耗 − 退还」。
+ #[test]
+ fn dashboard_consumption_offsets_refunds_in_the_same_day() {
+ let mut consumed = AdminDashboardSeries::default();
+ consumed.add(100, 40);
+ let mut refunded = AdminDashboardSeries::default();
+ refunded.add(100, 15);
+
+ let net = net_admin_dashboard_consumed_mud_points(&consumed, &refunded, &[100, 101]);
+
+ assert_eq!(net.value(100), 25);
+ assert_eq!(net.total(), 25);
+ }
+
+ #[test]
+ fn dashboard_consumption_refund_offsets_earlier_consumption_day() {
+ let mut consumed = AdminDashboardSeries::default();
+ consumed.add(100, 40);
+ consumed.add(101, 10);
+ // 精选审核返还发生在消耗之后的业务日，必须回溯抵扣仍有净额的最近一天。
+ let mut refunded = AdminDashboardSeries::default();
+ refunded.add(102, 30);
+
+ let net = net_admin_dashboard_consumed_mud_points(&consumed, &refunded, &[100, 101, 102]);
+
+ assert_eq!(net.value(100), 20);
+ assert_eq!(net.value(101), 0);
+ assert_eq!(net.value(102), 0);
+ assert_eq!(net.total(), 20);
+ }
+
+ #[test]
+ fn dashboard_consumption_refund_beyond_consumption_stops_at_zero() {
+ let mut consumed = AdminDashboardSeries::default();
+ consumed.add(100, 6);
+ consumed.add(101, 4);
+ let mut refunded = AdminDashboardSeries::default();
+ refunded.add(101, 40);
+
+ let net = net_admin_dashboard_consumed_mud_points(&consumed, &refunded, &[100, 101]);
+
+ assert_eq!(net.value(100), 0);
+ assert_eq!(net.value(101), 0);
+ assert_eq!(net.total(), 0);
+ }
+
+ #[test]
+ fn dashboard_consumption_without_refunds_keeps_daily_values() {
+ let mut consumed = AdminDashboardSeries::default();
+ consumed.add(100, 40);
+ consumed.add(101, 8);
+
+ let net = net_admin_dashboard_consumed_mud_points(
+ &consumed,
+ &AdminDashboardSeries::default(),
+ &[100, 101, 102],
+ );
+
+ assert_eq!(net.value(100), 40);
+ assert_eq!(net.value(101), 8);
+ assert_eq!(net.value(102), 0);
+ assert_eq!(net.total(), 48);
+ }
+
+ /// 累计充值只累加真实支付过的订单：未支付订单的 paid_at 是 SATS None，不能计入。
+ #[test]
+ fn cumulative_recharge_counts_only_paid_orders() {
+ let rows = vec![
+ json!([6000, [1778207451731746_i64]]),
+ json!([1200, [0, [1778207451731746_i64]]]),
+ json!([9900, [1, []]]),
+ json!([8800, null]),
+ json!([300, "2026-05-07T08:30:51.731746Z"]),
+ json!([1000, [1, []]]),
+ ];
+
+ assert_eq!(sum_admin_user_recharged_cents(&rows), 7500);
+ }
+
+ #[test]
+ fn cumulative_recharge_ignores_malformed_rows() {
+ let rows = vec![
+ json!("not-a-row"),
+ json!(["abc", [123]]),
+ json!([]),
+ json!([0, [123]]),
+ ];
+
+ assert_eq!(sum_admin_user_recharged_cents(&rows), 0);
+ }
+
#[test]
fn timestamp_value_to_micros_accepts_sql_shapes() {
assert_eq!(
diff --git a/server-rs/crates/api-server/src/admin_recharge.rs b/server-rs/crates/api-server/src/admin_recharge.rs
index 28492509e..950e53d50 100644
--- a/server-rs/crates/api-server/src/admin_recharge.rs
+++ b/server-rs/crates/api-server/src/admin_recharge.rs
@@ -45,7 +45,10 @@ use shared_contracts::admin::{
use spacetime_client::SpacetimeClientError;
use crate::{
- admin::{AdminDisplayNameDirectory, AuthenticatedAdmin, load_admin_display_name_directory},
+ admin::{
+ AdminDisplayNameDirectory, AuthenticatedAdmin, fetch_admin_user_cumulative_recharged_cents,
+ load_admin_display_name_directory,
+ },
api_response::json_success_body,
http_error::AppError,
request_context::RequestContext,
@@ -153,6 +156,8 @@ pub async fn admin_get_user_detail(
let admin_display_names = load_admin_display_name_directory(&state)
.await
.map_err(|error| spacetime_error_response(&request_context, error))?;
+ let cumulative_recharged_cents =
+ fetch_admin_user_cumulative_recharged_cents(&state, &user.id).await;
Ok(json_success_body(
Some(&request_context),
@@ -167,6 +172,7 @@ pub async fn admin_get_user_detail(
phone_bound: user.phone_number_masked.is_some(),
wechat_bound: user.wechat_bound,
historical_consumed_points: wallet_detail.historical_consumed_points,
+ cumulative_recharged_cents,
can_reconcile_consumption: admin.can(ADMIN_ACTION_PROFILE_WALLET_CONSUMPTION_RECONCILE),
wallet: map_wallet(wallet_detail.wallet, Some(&admin_display_names)),
recharge_orders: orders
@@ -935,6 +941,12 @@ fn map_order_entry(
let settlement = entry.settlement.as_ref();
let remaining_refundable_cents = remaining_refundable_cents(&entry);
let block_reason = order_refund_block_reason(&entry).map(str::to_string);
+ // 未支付订单不能拿订单金额当实付；只有 paid_at 存在的订单才有实付金额。
+ let paid_amount_cents = if entry.order.paid_at_micros.is_some() {
+ entry.order.amount_cents
+ } else {
+ 0
+ };
AdminRechargeOrderEntryPayload {
order_id: entry.order.order_id,
user_id: entry.order.user_id,
@@ -943,6 +955,7 @@ fn map_order_entry(
product_title: entry.order.product_title,
product_kind: entry.order.kind.as_str().to_string(),
amount_cents: entry.order.amount_cents,
+ paid_amount_cents,
status: entry.order.status.as_str().to_string(),
payment_channel: entry.order.payment_channel,
paid_at_micros: entry.order.paid_at_micros,
diff --git a/server-rs/crates/api-server/src/modules/game_distribution.rs b/server-rs/crates/api-server/src/modules/game_distribution.rs
index 108f29425..ac56a40c2 100644
--- a/server-rs/crates/api-server/src/modules/game_distribution.rs
+++ b/server-rs/crates/api-server/src/modules/game_distribution.rs
@@ -19,7 +19,10 @@ use module_game_distribution::{
validate_release_zip,
};
use platform_llm::{EDITOR_AGENT_GPT5_MODEL, LlmMessage, LlmRunRequest};
-use platform_oss::{OssGetObjectRequest, OssInternalPutObjectRequest, OssObjectAccess};
+use platform_oss::{
+ OssAppendInternalObjectRequest, OssDeleteObjectRequest, OssGetObjectRequest,
+ OssInternalPutObjectRequest, OssObjectAccess,
+};
use serde::Deserialize;
use serde_json::{Value, json};
use shared_contracts::game_distribution::{
@@ -49,6 +52,13 @@ use crate::{
};
pub(crate) const MAX_PACKAGE_REQUEST_BODY_BYTES: usize = MAX_PACKAGE_BYTES as usize + 1024;
+/// 分片续传的固定分片大小：200 MiB 上限下最多 25 片，单片远低于反代放行量。
+/// 客户端只能使用服务端下发的值，不得自行改变分片边界，否则权威偏移会立刻对不上。
+pub(crate) const PACKAGE_UPLOAD_CHUNK_BYTES: usize = 8 * 1024 * 1024;
+/// 分片路由的请求体放行量：分片大小 + 1 KiB 头部余量。
+pub(crate) const MAX_PACKAGE_CHUNK_REQUEST_BODY_BYTES: usize = PACKAGE_UPLOAD_CHUNK_BYTES + 1024;
+/// 分片偏移由客户端显式声明，服务端以对象当前长度为唯一权威。
+const PACKAGE_UPLOAD_OFFSET_HEADER: &str = "x-genarrative-upload-offset";
const MAX_LIST_LIMIT: u32 = 48;
const MAX_IDEMPOTENCY_KEY_CHARS: usize = 128;
const MAX_PACKAGE_MANIFEST_JSON_BYTES: usize = 2 * 1024 * 1024;
@@ -60,7 +70,9 @@ const GAME_DISTRIBUTION_PUBLISHED_STATUS: &str = "published";
const GAME_DISTRIBUTION_OSS_PUT_MAX_ATTEMPTS: usize = 3;
const GAME_DISTRIBUTION_OSS_PUT_RETRY_DELAYS_MS: [u64; 2] = [250, 500];
const RELEASE_PACKAGE_CACHE_MAX_ENTRIES: usize = 4;
-const RELEASE_PACKAGE_CACHE_MAX_BYTES: usize = 200 * 1024 * 1024;
+/// 缓存字节预算必须比单个发行包上限大出一档，否则 200 MiB 档的包只能刚好自占整份预算，
+/// 任何并发的小包都会被立刻挤掉。
+const RELEASE_PACKAGE_CACHE_MAX_BYTES: usize = 256 * 1024 * 1024;
/// 发行静态资源的进程内缓存。
///
@@ -179,6 +191,23 @@ pub fn router(state: AppState) -> Router {
"/api/game-distribution/versions/{version_id}/package",
put(upload_package).layer(DefaultBodyLimit::max(MAX_PACKAGE_REQUEST_BODY_BYTES)),
)
+ .route(
+ "/api/game-distribution/versions/{version_id}/package/upload-state",
+ get(package_upload_state),
+ )
+ .route(
+ "/api/game-distribution/versions/{version_id}/package/chunk",
+ put(upload_package_chunk)
+ .layer(DefaultBodyLimit::max(MAX_PACKAGE_CHUNK_REQUEST_BODY_BYTES)),
+ )
+ .route(
+ "/api/game-distribution/versions/{version_id}/package/complete",
+ post(complete_package_upload),
+ )
+ .route(
+ "/api/game-distribution/versions/{version_id}/package/reset",
+ post(reset_package_upload),
+ )
.route(
"/api/game-distribution/versions/{version_id}/submit",
post(submit_version),
@@ -630,46 +659,10 @@ async fn upload_package(
return Err(mapped);
}
};
- if manifest.package_sha256 != expected.package_sha256
- || manifest.package_bytes != expected.package_bytes
- || u32::try_from(manifest.files.len()).unwrap_or(u32::MAX) != expected.package_file_count
- || expected.package_entry_path != "index.html"
- {
- warn!(
- request_id = ctx.request_id(),
- operation = "package_rejected",
- game_id = %expected.game_id,
- version_id = %version_id,
- code = "PACKAGE_MISMATCH",
- declared_bytes = expected.package_bytes,
- actual_bytes = manifest.package_bytes,
- declared_file_count = expected.package_file_count,
- actual_file_count = u32::try_from(manifest.files.len()).unwrap_or(u32::MAX),
- elapsed_ms = ctx.elapsed(),
- "发行包与版本声明不一致"
- );
- let error = AppError::from_status(StatusCode::CONFLICT)
- .with_code("PACKAGE_MISMATCH")
- .with_details(json!({
- "provider": "game-distribution",
- "message": "发行包摘要、体积、文件数或入口与版本声明不一致",
- }));
- record_upload_failure(
- &state,
- &owner_user_id,
- &version_id,
- &idempotency_key,
- "PACKAGE_MISMATCH",
- "发行包摘要、体积、文件数或入口与版本声明不一致".to_string(),
- )
- .await;
- return Err(error);
- }
let package_object_key = format!(
"{GAME_DISTRIBUTION_OBJECT_PREFIX}{}/{version_id}.zip",
expected.game_id
);
- let package_manifest_json = package_manifest_json(&manifest)?;
let oss = state.project_snapshot_oss_client().ok_or_else(|| {
AppError::from_status(StatusCode::SERVICE_UNAVAILABLE).with_message("游戏发行包 OSS 未配置")
})?;
@@ -697,7 +690,8 @@ async fn upload_package(
None => false,
};
if !skipped {
- // 单次 100 MiB PUT 在本机实测 12 秒上下，偶发传输失败会让作者白传一次；
+ // 单次 100 MiB 档 PUT 在本机实测 12 秒上下（上限提升到 200 MiB 后单次耗时与失败
+ // 暴露面同步放大），偶发传输失败会让作者白传一次；
// 这里按 platform-oss 既有的可重试分类做受控重试（只重试传输/超时/408/429/5xx）。
oss.put_internal_object_with_retry(
state.editor_oss_http_client(),
@@ -714,28 +708,93 @@ async fn upload_package(
.await
.map_err(|error| map_oss_error(error, "aliyun-oss"))?;
}
+ confirm_validated_package(
+ &state,
+ &ctx,
+ &owner_user_id,
+ &version_id,
+ &expected,
+ &manifest,
+ package_object_key,
+ &idempotency_key,
+ skipped,
+ )
+ .await
+}
+
+/// 校验通过后的共同收口：声明比对 → 确认 → 结构化事件。
+///
+/// 整包 `PUT` 与分片续传的完成动作共用这条路径，两种入口的校验、幂等与事件口径必须一致；
+/// 任何入口都不得绕过它直接写版本状态。
+#[allow(clippy::too_many_arguments)]
+async fn confirm_validated_package(
+ state: &AppState,
+ ctx: &RequestContext,
+ owner_user_id: &str,
+ version_id: &str,
+ expected: &GameDistributionVersionRecord,
+ manifest: &ReleasePackageManifest,
+ package_object_key: String,
+ idempotency_key: &str,
+ oss_put_skipped: bool,
+) -> Result, AppError> {
+ if manifest.package_sha256 != expected.package_sha256
+ || manifest.package_bytes != expected.package_bytes
+ || u32::try_from(manifest.files.len()).unwrap_or(u32::MAX) != expected.package_file_count
+ || expected.package_entry_path != "index.html"
+ {
+ warn!(
+ request_id = ctx.request_id(),
+ operation = "package_rejected",
+ game_id = %expected.game_id,
+ version_id = %version_id,
+ code = "PACKAGE_MISMATCH",
+ declared_bytes = expected.package_bytes,
+ actual_bytes = manifest.package_bytes,
+ declared_file_count = expected.package_file_count,
+ actual_file_count = u32::try_from(manifest.files.len()).unwrap_or(u32::MAX),
+ elapsed_ms = ctx.elapsed(),
+ "发行包与版本声明不一致"
+ );
+ let error = AppError::from_status(StatusCode::CONFLICT)
+ .with_code("PACKAGE_MISMATCH")
+ .with_details(json!({
+ "provider": "game-distribution",
+ "message": "发行包摘要、体积、文件数或入口与版本声明不一致",
+ }));
+ record_upload_failure(
+ state,
+ owner_user_id,
+ version_id,
+ idempotency_key,
+ "PACKAGE_MISMATCH",
+ "发行包摘要、体积、文件数或入口与版本声明不一致".to_string(),
+ )
+ .await;
+ return Err(error);
+ }
+ let package_manifest_json = package_manifest_json(manifest)?;
let request_digest = compute_request_digest(
- &serde_json::to_vec(&(version_id.as_str(), manifest.package_sha256.as_str()))
+ &serde_json::to_vec(&(version_id, manifest.package_sha256.as_str()))
.map_err(|error| internal(error.to_string()))?,
);
let log_game_id = expected.game_id.clone();
let log_package_bytes = manifest.package_bytes;
let log_file_count = u32::try_from(manifest.files.len()).unwrap_or(u32::MAX);
let log_sha_prefix = manifest.package_sha256.chars().take(12).collect::();
- let log_oss_put_skipped = skipped;
let confirmed = state
.spacetime_client()
.confirm_game_distribution_package(
spacetime_client::GameDistributionConfirmPackageRecordInput {
- version_id,
- owner_user_id,
- package_sha256: manifest.package_sha256,
+ version_id: version_id.to_string(),
+ owner_user_id: owner_user_id.to_string(),
+ package_sha256: manifest.package_sha256.clone(),
package_bytes: manifest.package_bytes,
package_file_count: u32::try_from(manifest.files.len()).unwrap_or(u32::MAX),
package_entry_path: "index.html".to_string(),
package_object_key,
package_manifest_json,
- idempotency_key,
+ idempotency_key: idempotency_key.to_string(),
request_digest,
updated_at_micros: now_micros(),
},
@@ -750,16 +809,341 @@ async fn upload_package(
package_bytes = log_package_bytes,
file_count = log_file_count,
sha256_prefix = %log_sha_prefix,
- oss_put_skipped = log_oss_put_skipped,
+ oss_put_skipped,
elapsed_ms = ctx.elapsed(),
"发行包已确认"
);
Ok(json_success_body(
- Some(&ctx),
+ Some(ctx),
json!({ "versionId": confirmed.0.version_id, "status": confirmed.0.status }),
))
}
+/// 分片续传的状态查询：客户端拿到的「已收字节」来自 OSS 对象事实，不依赖本地记录，
+/// 因此进程重启、换机器或换网络后都能从权威偏移继续。
+async fn package_upload_state(
+ State(state): State,
+ Extension(ctx): Extension,
+ Extension(auth): Extension,
+ Path(version_id): Path,
+) -> Result, AppError> {
+ let owner_user_id = auth.claims().user_id().to_string();
+ ensure_publish_enabled(&state, Some(owner_user_id.as_str())).await?;
+ let version = load_owner_version_or_404(&state, owner_user_id, version_id.clone()).await?;
+ let oss = game_distribution_oss_client(&state)?;
+ let object_key = game_distribution_package_object_key(&version.game_id, &version_id);
+ let received_bytes = staged_package_bytes(&state, oss, &object_key).await?;
+ Ok(json_success_body(
+ Some(&ctx),
+ json!({
+ "versionId": version_id,
+ "status": version.status,
+ "chunkBytes": PACKAGE_UPLOAD_CHUNK_BYTES,
+ "declaredPackageBytes": version.package_bytes,
+ "receivedBytes": received_bytes,
+ }),
+ ))
+}
+
+/// 分片写入。
+///
+/// 客户端声明的偏移必须等于服务端已收字节；不一致时返回 409 与权威偏移，
+/// 由客户端按权威偏移续传 —— 这样重放与乱序都不会造成重复写入。
+async fn upload_package_chunk(
+ State(state): State,
+ Extension(ctx): Extension,
+ Extension(auth): Extension,
+ headers: HeaderMap,
+ Path(version_id): Path,
+ body: Bytes,
+) -> Result, AppError> {
+ require_octet_stream_content_type(&headers)?;
+ let owner_user_id = auth.claims().user_id().to_string();
+ ensure_publish_enabled(&state, Some(owner_user_id.as_str())).await?;
+ // 分片级重放由偏移语义保证，这里仍要求幂等键，保持与其它写入口一致的调用约定。
+ let _idempotency_key = idempotency_key(&headers)?;
+ let offset = package_upload_offset(&headers)?;
+ if body.is_empty() {
+ return Err(bad_request("发行包分片内容不能为空"));
+ }
+ if body.len() > PACKAGE_UPLOAD_CHUNK_BYTES {
+ return Err(AppError::from_status(StatusCode::PAYLOAD_TOO_LARGE)
+ .with_code("PACKAGE_CHUNK_TOO_LARGE")
+ .with_message("发行包分片超过服务端下发的大小"));
+ }
+ let version = load_owner_version_or_404(&state, owner_user_id, version_id.clone()).await?;
+ let chunk_bytes = u64::try_from(body.len()).unwrap_or(u64::MAX);
+ let end = offset
+ .checked_add(chunk_bytes)
+ .ok_or_else(|| bad_request("发行包分片偏移溢出"))?;
+ if end > version.package_bytes {
+ return Err(AppError::from_status(StatusCode::CONFLICT)
+ .with_code("PACKAGE_UPLOAD_EXCEEDS_DECLARED")
+ .with_details(json!({
+ "provider": "game-distribution",
+ "declaredPackageBytes": version.package_bytes,
+ "receivedBytes": offset,
+ "message": "分片写入会超过版本声明的发行包大小",
+ })));
+ }
+ let oss = game_distribution_oss_client(&state)?;
+ let object_key = game_distribution_package_object_key(&version.game_id, &version_id);
+ let received_bytes = staged_package_bytes(&state, oss, &object_key).await?;
+ if offset != received_bytes {
+ warn!(
+ request_id = ctx.request_id(),
+ operation = "package_chunk_offset_mismatch",
+ game_id = %version.game_id,
+ version_id = %version_id,
+ declared_offset = offset,
+ received_bytes,
+ "发行包分片偏移与服务端已收字节不一致"
+ );
+ return Err(AppError::from_status(StatusCode::CONFLICT)
+ .with_code("PACKAGE_UPLOAD_OFFSET_MISMATCH")
+ .with_message("分片偏移与服务端已收字节不一致，请按权威偏移续传")
+ .with_details(json!({
+ "provider": "game-distribution",
+ "receivedBytes": received_bytes,
+ })));
+ }
+ let appended = oss
+ .append_internal_object_with_retry(
+ state.editor_oss_http_client(),
+ OssAppendInternalObjectRequest {
+ object_key,
+ content_type: Some("application/zip".to_string()),
+ position: offset,
+ body: body.to_vec(),
+ },
+ GAME_DISTRIBUTION_OSS_PUT_MAX_ATTEMPTS,
+ &GAME_DISTRIBUTION_OSS_PUT_RETRY_DELAYS_MS,
+ )
+ .await
+ .map_err(|error| map_oss_error(error, "aliyun-oss"))?;
+ info!(
+ request_id = ctx.request_id(),
+ operation = "package_chunk_stored",
+ game_id = %version.game_id,
+ version_id = %version_id,
+ offset,
+ chunk_bytes = appended.appended_bytes,
+ received_bytes = appended.next_position,
+ elapsed_ms = ctx.elapsed(),
+ "发行包分片已写入"
+ );
+ Ok(json_success_body(
+ Some(&ctx),
+ json!({
+ "versionId": version_id,
+ "chunkBytes": PACKAGE_UPLOAD_CHUNK_BYTES,
+ "receivedBytes": appended.next_position,
+ }),
+ ))
+}
+
+/// 分片续传的完成动作：全部字节到齐后才回读整包、校验并确认。
+///
+/// 校验失败时删除半包对象并把版本落到 `upload_failed`，避免半包留在对象键上拖住后续重传。
+async fn complete_package_upload(
+ State(state): State,
+ Extension(ctx): Extension,
+ Extension(auth): Extension,
+ headers: HeaderMap,
+ Path(version_id): Path,
+) -> Result, AppError> {
+ let owner_user_id = auth.claims().user_id().to_string();
+ ensure_publish_enabled(&state, Some(owner_user_id.as_str())).await?;
+ let idempotency_key = idempotency_key(&headers)?;
+ let version =
+ load_owner_version_or_404(&state, owner_user_id.clone(), version_id.clone()).await?;
+ let oss = game_distribution_oss_client(&state)?;
+ let object_key = game_distribution_package_object_key(&version.game_id, &version_id);
+ let received_bytes = staged_package_bytes(&state, oss, &object_key).await?;
+ if received_bytes == 0 {
+ return Err(AppError::from_status(StatusCode::CONFLICT)
+ .with_code("PACKAGE_UPLOAD_NOT_STARTED")
+ .with_details(json!({
+ "provider": "game-distribution",
+ "declaredPackageBytes": version.package_bytes,
+ "receivedBytes": 0,
+ "message": "该版本还没有任何已收分片",
+ })));
+ }
+ if received_bytes != version.package_bytes {
+ return Err(AppError::from_status(StatusCode::CONFLICT)
+ .with_code("PACKAGE_UPLOAD_INCOMPLETE")
+ .with_message("发行包分片尚未收齐")
+ .with_details(json!({
+ "provider": "game-distribution",
+ "declaredPackageBytes": version.package_bytes,
+ "receivedBytes": received_bytes,
+ })));
+ }
+ let body = oss
+ .get_object(
+ state.editor_oss_http_client(),
+ OssGetObjectRequest {
+ object_key: object_key.clone(),
+ max_bytes: MAX_PACKAGE_BYTES as usize,
+ },
+ )
+ .await
+ .map_err(|error| map_oss_error(error, "aliyun-oss"))?;
+ let manifest = match validate_release_zip(&body) {
+ Ok(manifest) => manifest,
+ Err(error) => {
+ let reason = format!("{error:?}");
+ warn!(
+ request_id = ctx.request_id(),
+ operation = "package_rejected",
+ game_id = %version.game_id,
+ version_id = %version_id,
+ code = "PACKAGE_VALIDATION_FAILED",
+ reason = %reason,
+ uploaded_bytes = body.len(),
+ elapsed_ms = ctx.elapsed(),
+ "发行包校验失败"
+ );
+ let mapped = map_package_error(error);
+ if let Err(delete_error) = oss
+ .delete_object(
+ state.editor_oss_http_client(),
+ OssDeleteObjectRequest {
+ object_key: object_key.clone(),
+ },
+ )
+ .await
+ {
+ warn!(
+ request_id = ctx.request_id(),
+ operation = "package_staging_delete_failed",
+ version_id = %version_id,
+ error = %delete_error,
+ "校验失败的半包对象删除失败，需要人工确认对象键状态"
+ );
+ }
+ record_upload_failure(
+ &state,
+ &owner_user_id,
+ &version_id,
+ &idempotency_key,
+ "PACKAGE_VALIDATION_FAILED",
+ reason,
+ )
+ .await;
+ return Err(mapped);
+ }
+ };
+ confirm_validated_package(
+ &state,
+ &ctx,
+ &owner_user_id,
+ &version_id,
+ &version,
+ &manifest,
+ object_key,
+ &idempotency_key,
+ true,
+ )
+ .await
+}
+
+/// 显式重置分片会话：删除半包对象并把已收字节归零。
+///
+/// 只有尚未确认过发行包的版本能重置；已确认的版本必须新建版本，不能在半包之上续写不同字节。
+async fn reset_package_upload(
+ State(state): State,
+ Extension(ctx): Extension,
+ Extension(auth): Extension,
+ headers: HeaderMap,
+ Path(version_id): Path,
+) -> Result, AppError> {
+ let owner_user_id = auth.claims().user_id().to_string();
+ ensure_publish_enabled(&state, Some(owner_user_id.as_str())).await?;
+ let _idempotency_key = idempotency_key(&headers)?;
+ let version = load_owner_version_or_404(&state, owner_user_id, version_id.clone()).await?;
+ if !matches!(version.status.as_str(), "awaiting_upload" | "upload_failed") {
+ return Err(AppError::from_status(StatusCode::CONFLICT)
+ .with_code("PACKAGE_UPLOAD_RESET_NOT_ALLOWED")
+ .with_message("该版本已经确认过发行包，重新上传请新建版本"));
+ }
+ let oss = game_distribution_oss_client(&state)?;
+ let object_key = game_distribution_package_object_key(&version.game_id, &version_id);
+ oss.delete_object(
+ state.editor_oss_http_client(),
+ OssDeleteObjectRequest {
+ object_key: object_key.clone(),
+ },
+ )
+ .await
+ .map_err(|error| map_oss_error(error, "aliyun-oss"))?;
+ info!(
+ request_id = ctx.request_id(),
+ operation = "package_upload_reset",
+ game_id = %version.game_id,
+ version_id = %version_id,
+ elapsed_ms = ctx.elapsed(),
+ "发行包分片会话已重置"
+ );
+ Ok(json_success_body(
+ Some(&ctx),
+ json!({ "versionId": version_id, "receivedBytes": 0 }),
+ ))
+}
+
+fn game_distribution_oss_client(state: &AppState) -> Result<&platform_oss::OssClient, AppError> {
+ state.project_snapshot_oss_client().ok_or_else(|| {
+ AppError::from_status(StatusCode::SERVICE_UNAVAILABLE).with_message("游戏发行包 OSS 未配置")
+ })
+}
+
+fn game_distribution_package_object_key(game_id: &str, version_id: &str) -> String {
+ format!("{GAME_DISTRIBUTION_OBJECT_PREFIX}{game_id}/{version_id}.zip")
+}
+
+/// 已收字节的权威来源：对象存在时的长度；确定不存在时是 0，其它失败按上游错误上报。
+async fn staged_package_bytes(
+ state: &AppState,
+ oss: &platform_oss::OssClient,
+ object_key: &str,
+) -> Result {
+ let head = oss
+ .head_internal_object(state.editor_oss_http_client(), object_key)
+ .await
+ .map_err(|error| map_oss_error(error, "aliyun-oss"))?;
+ Ok(head.map(|object| object.content_length).unwrap_or(0))
+}
+
+fn require_octet_stream_content_type(headers: &HeaderMap) -> Result<(), AppError> {
+ let content_type = headers
+ .get(header::CONTENT_TYPE)
+ .and_then(|value| value.to_str().ok())
+ .map(|value| {
+ value
+ .split(';')
+ .next()
+ .unwrap_or_default()
+ .trim()
+ .to_ascii_lowercase()
+ });
+ if content_type.as_deref() != Some("application/octet-stream") {
+ return Err(bad_request("发行包分片必须使用 application/octet-stream"));
+ }
+ Ok(())
+}
+
+fn package_upload_offset(headers: &HeaderMap) -> Result {
+ let raw = headers
+ .get(PACKAGE_UPLOAD_OFFSET_HEADER)
+ .and_then(|value| value.to_str().ok())
+ .map(str::trim)
+ .filter(|value| !value.is_empty())
+ .ok_or_else(|| bad_request("缺少发行包分片偏移"))?;
+ raw.parse::()
+ .map_err(|_| bad_request("发行包分片偏移必须是非负整数"))
+}
+
async fn submit_version(
State(state): State,
Extension(ctx): Extension,
@@ -1969,6 +2353,64 @@ mod tests {
}
}
+ #[test]
+ fn package_request_body_limit_covers_max_package_bytes() {
+ // 口径约束：发行包路由的请求体放行量必须覆盖包体上限，否则合法包会在
+ // `DefaultBodyLimit` 处被 413，而 ZIP 校验根本没机会执行。
+ assert!(MAX_PACKAGE_REQUEST_BODY_BYTES > MAX_PACKAGE_BYTES as usize);
+ }
+
+ #[test]
+ fn package_chunk_size_stays_inside_declared_limits() {
+ // 分片必须能整除式地覆盖 200 MiB 档发行包（最多 25 片），且分片放行量要留出头部余量。
+ assert_eq!(PACKAGE_UPLOAD_CHUNK_BYTES, 8 * 1024 * 1024);
+ assert!(PACKAGE_UPLOAD_CHUNK_BYTES < MAX_PACKAGE_BYTES as usize);
+ assert!(MAX_PACKAGE_CHUNK_REQUEST_BODY_BYTES > PACKAGE_UPLOAD_CHUNK_BYTES);
+ assert!(
+ (MAX_PACKAGE_BYTES as usize).div_ceil(PACKAGE_UPLOAD_CHUNK_BYTES) <= 25,
+ "200 MiB 档发行包的分片数必须不超过 25 片"
+ );
+ }
+
+ #[test]
+ fn package_upload_offset_requires_non_negative_integer() {
+ let mut headers = HeaderMap::new();
+ assert!(package_upload_offset(&headers).is_err());
+
+ headers.insert(PACKAGE_UPLOAD_OFFSET_HEADER, HeaderValue::from_static(" "));
+ assert!(package_upload_offset(&headers).is_err());
+
+ headers.insert(PACKAGE_UPLOAD_OFFSET_HEADER, HeaderValue::from_static("-1"));
+ assert!(package_upload_offset(&headers).is_err());
+
+ headers.insert(
+ PACKAGE_UPLOAD_OFFSET_HEADER,
+ HeaderValue::from_static("8388608"),
+ );
+ assert_eq!(
+ package_upload_offset(&headers).expect("合法偏移"),
+ PACKAGE_UPLOAD_CHUNK_BYTES as u64
+ );
+ }
+
+ #[test]
+ fn package_chunk_content_type_must_be_octet_stream() {
+ let mut headers = HeaderMap::new();
+ assert!(require_octet_stream_content_type(&headers).is_err());
+
+ headers.insert(
+ header::CONTENT_TYPE,
+ HeaderValue::from_static("application/zip"),
+ );
+ assert!(require_octet_stream_content_type(&headers).is_err());
+
+ headers.insert(
+ header::CONTENT_TYPE,
+ HeaderValue::from_static("application/octet-stream"),
+ );
+ assert!(require_octet_stream_content_type(&headers).is_ok());
+ }
+
#[test]
fn metadata_rejects_mobile_games_without_touch_support() {
let mut payload = metadata();
diff --git a/server-rs/crates/module-game-distribution/src/package.rs b/server-rs/crates/module-game-distribution/src/package.rs
index 5e8faf9f5..feb85a54e 100644
--- a/server-rs/crates/module-game-distribution/src/package.rs
+++ b/server-rs/crates/module-game-distribution/src/package.rs
@@ -6,8 +6,13 @@ use std::{
use sha2::{Digest, Sha256};
-pub const MAX_PACKAGE_BYTES: u64 = 100 * 1024 * 1024;
-pub const MAX_EXPANDED_BYTES: u64 = 250 * 1024 * 1024;
+/// 发行包体积上限。反代放行量与路由请求体上限都从它派生：Nginx
+/// `client_max_body_size`、Pingora `MAX_API_BODY_BYTES` 必须同步放宽，否则合法包会在
+/// 到达 `api-server` 之前被拒。
+pub const MAX_PACKAGE_BYTES: u64 = 200 * 1024 * 1024;
+/// 展开总量上限保持压缩包上限的 2.5 倍余量：包体本身基本不可再压时展开量约等于包体，
+/// 纯文本 / JSON 资源占比高的包仍要有足够空间。
+pub const MAX_EXPANDED_BYTES: u64 = 500 * 1024 * 1024;
pub const MAX_FILE_BYTES: u64 = 64 * 1024 * 1024;
pub const MAX_FILE_COUNT: usize = 10_000;
pub const MAX_COMPRESSION_RATIO: u64 = 100;
@@ -187,6 +192,23 @@ mod tests {
output.into_inner()
}
+ /// 存储型条目的压缩包；用于构造体积可控且不参与 deflate 的大包。
+ fn stored_archive(files: &[(&str, &[u8])]) -> Vec {
+ let mut output = Cursor::new(Vec::new());
+ let mut writer = ZipWriter::new(&mut output);
+ for (path, content) in files {
+ writer
+ .start_file(
+ *path,
+ SimpleFileOptions::default().compression_method(zip::CompressionMethod::Stored),
+ )
+ .expect("zip entry");
+ writer.write_all(content).expect("zip content");
+ }
+ writer.finish().expect("finish zip");
+ output.into_inner()
+ }
+
#[test]
fn accepts_root_entry_and_returns_file_manifest() {
let bytes = archive(&[("index.html", b""), ("assets/a.txt", b"a")]);
@@ -222,4 +244,27 @@ mod tests {
Err(ReleasePackageError::InvalidPath)
);
}
+
+ #[test]
+ fn keeps_expansion_headroom_over_package_limit() {
+ // 口径约束：发行包上限调整时，展开总量至少要留出两倍余量，
+ // 否则高文本占比的合法包会在展开量检查处被误拒。
+ assert!(MAX_EXPANDED_BYTES >= MAX_PACKAGE_BYTES.saturating_mul(2));
+ }
+
+ #[test]
+ fn accepts_package_above_the_previous_hundred_mib_limit() {
+ // 上限从 100 MiB 提到 200 MiB 的回归防护：两个 50 MiB 存储型条目组成 100 MiB
+ // 出头的包，旧上限会在这里判 PackageTooLarge，新上限必须放行并给出完整清单。
+ let chunk = vec![0_u8; 50 * 1024 * 1024];
+ let bytes = stored_archive(&[
+ ("index.html", b""),
+ ("assets/a.bin", chunk.as_slice()),
+ ("assets/b.bin", chunk.as_slice()),
+ ]);
+ assert!(bytes.len() as u64 > 100 * 1024 * 1024);
+ let manifest = validate_release_zip(&bytes).expect("package above 100 MiB");
+ assert_eq!(manifest.package_bytes, bytes.len() as u64);
+ assert_eq!(manifest.files.len(), 3);
+ }
}
diff --git a/server-rs/crates/pingora-gateway/src/main.rs b/server-rs/crates/pingora-gateway/src/main.rs
index 88af466f2..9c1a6e877 100644
--- a/server-rs/crates/pingora-gateway/src/main.rs
+++ b/server-rs/crates/pingora-gateway/src/main.rs
@@ -37,7 +37,9 @@ const DEFAULT_WEB_ROOT: &str = "/srv/genarrative/web";
const DEFAULT_ACME_ROOT: &str = "/var/www/html";
const DEFAULT_MAINTENANCE_FILE: &str = "/var/lib/genarrative/maintenance/enabled";
const DEFAULT_MAINTENANCE_PAGE_FILE: &str = "/var/lib/genarrative/maintenance/page.html";
-const DEFAULT_MAX_API_BODY_BYTES: u64 = 64 * 1024 * 1024;
+// 通用 /api 路由的放行上限；必须覆盖游戏发行包 PUT（路由 `DefaultBodyLimit` 200 MiB + 1 KiB），
+// 具体接口的真实上限仍由 api-server 逐路由校验。
+const DEFAULT_MAX_API_BODY_BYTES: u64 = 210 * 1024 * 1024;
const DEFAULT_GZIP_LEVEL: u32 = 5;
const DEFAULT_GZIP_MIN_LENGTH_BYTES: u64 = 1024;
const DEFAULT_UPSTREAM_CONNECT_TIMEOUT_MS: u64 = 3_000;
diff --git a/server-rs/crates/platform-oss/src/lib.rs b/server-rs/crates/platform-oss/src/lib.rs
index 32b3d02f6..4cce2d31a 100644
--- a/server-rs/crates/platform-oss/src/lib.rs
+++ b/server-rs/crates/platform-oss/src/lib.rs
@@ -132,6 +132,29 @@ pub struct OssInternalPutObjectRequest {
pub body: Vec,
}
+/// 内部对象的追加写请求（OSS AppendObject）。
+///
+/// `position = 0` 表示追加到当前末尾；`position > 0` 必须等于对象当前长度，
+/// 否则上游直接失败 —— 分片续传依赖这条语义保证重放不会重复写入。
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct OssAppendInternalObjectRequest {
+ pub object_key: String,
+ pub content_type: Option,
+ pub position: u64,
+ pub body: Vec,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct OssAppendInternalObjectResponse {
+ pub provider: &'static str,
+ pub bucket: String,
+ pub endpoint: String,
+ pub object_key: String,
+ pub appended_bytes: u64,
+ /// 下一次可写位置，由 OSS 返回，是「已收字节」的权威值。
+ pub next_position: u64,
+}
+
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct OssPutObjectRequest {
pub prefix: LegacyAssetPrefix,
@@ -1018,6 +1041,105 @@ impl OssClient {
.await
}
+ /// 内部对象追加写，返回 OSS 给出的下一次可写位置（已收字节的权威值）。
+ ///
+ /// 与整对象 PUT 的区别是「可续写」：`position = 0` 追加到当前末尾，
+ /// `position > 0` 必须与对象当前长度一致（不一致时 OSS 判失败，不会重复写入）。
+ /// 因此续传只需要回读对象长度，再从未写位置继续。
+ pub async fn append_internal_object(
+ &self,
+ client: &reqwest::Client,
+ request: OssAppendInternalObjectRequest,
+ ) -> Result {
+ let object_key = normalize_internal_object_key(&request.object_key)?;
+ if request.body.is_empty() {
+ return Err(OssError::InvalidRequest(
+ "服务端内部对象追加内容不能为空".to_string(),
+ ));
+ }
+ let content_type = normalize_optional_value(request.content_type);
+ let mut target_url =
+ build_object_url(&self.config.bucket, &self.config.endpoint, &object_key).map_err(
+ |error| {
+ request_error(
+ OssRequestOperation::Put,
+ &format!("构造 OSS 对象 URL 失败：{error}"),
+ )
+ },
+ )?;
+ target_url
+ .query_pairs_mut()
+ .append_pair("append", "")
+ .append_pair("position", &request.position.to_string());
+ let appended_bytes = u64::try_from(request.body.len())
+ .map_err(|_| OssError::InvalidRequest("追加内容大小超出可支持范围".to_string()))?;
+ let headers = BTreeMap::new();
+ let builder = signed_request_builder(
+ client,
+ &self.config,
+ Method::POST,
+ Some(&object_key),
+ target_url,
+ content_type.as_deref(),
+ &headers,
+ )?
+ .header(reqwest::header::CONTENT_LENGTH, appended_bytes)
+ .body(request.body);
+ let response = builder
+ .send()
+ .await
+ .map_err(|error| request_error_from_reqwest(OssRequestOperation::Put, error))?;
+ if !response.status().is_success() {
+ return Err(request_status_error(
+ OssRequestOperation::Put,
+ response.status().as_u16(),
+ format!("OSS AppendObject 失败，状态码：{}", response.status()),
+ ));
+ }
+ let next_position = response
+ .headers()
+ .get("x-oss-next-append-position")
+ .and_then(|value| value.to_str().ok())
+ .and_then(|value| value.trim().parse::().ok())
+ .ok_or_else(|| {
+ OssError::InvalidRequest("OSS AppendObject 未返回 next-append-position".to_string())
+ })?;
+ Ok(OssAppendInternalObjectResponse {
+ provider: OSS_PROVIDER,
+ bucket: self.config.bucket.clone(),
+ endpoint: self.config.endpoint.clone(),
+ object_key,
+ appended_bytes,
+ next_position,
+ })
+ }
+
+ /// 内部对象追加写的受控重试，判定与退避口径和 `put_internal_object_with_retry` 一致。
+ pub async fn append_internal_object_with_retry(
+ &self,
+ client: &reqwest::Client,
+ request: OssAppendInternalObjectRequest,
+ max_attempts: usize,
+ retry_delays_ms: &[u64],
+ ) -> Result {
+ if max_attempts == 0 {
+ return Err(OssError::InvalidConfig(
+ "内部对象追加重试次数至少为 1".to_string(),
+ ));
+ }
+ if retry_delays_ms.len() < max_attempts.saturating_sub(1) {
+ return Err(OssError::InvalidConfig(
+ "内部对象追加重试缺少退避配置".to_string(),
+ ));
+ }
+ let log_key = request.object_key.clone();
+ run_internal_put_with_retry(max_attempts, retry_delays_ms, &log_key, move || {
+ let request = request.clone();
+ async move { self.append_internal_object(client, request).await }
+ })
+ .await
+ }
+
async fn put_internal_object_bytes(
&self,
client: &reqwest::Client,
@@ -1709,7 +1831,7 @@ where
max_attempts,
retry_delay_ms = delay_ms,
error = %error,
- "OSS 内部对象 PUT 失败，按退避重试"
+ "OSS 内部对象写入失败，按退避重试"
);
sleep(std::time::Duration::from_millis(delay_ms)).await;
attempt += 1;
diff --git a/server-rs/crates/shared-contracts/src/admin.rs b/server-rs/crates/shared-contracts/src/admin.rs
index f9730feb4..19ed5f06b 100644
--- a/server-rs/crates/shared-contracts/src/admin.rs
+++ b/server-rs/crates/shared-contracts/src/admin.rs
@@ -731,7 +731,10 @@ pub struct AdminDashboardRangePayload {
#[serde(rename_all = "camelCase")]
pub struct AdminDashboardMetricsPayload {
pub generated_assets: u64,
+ /// 已对冲退还（生成失败 / 精选审核返还 / LLM Router 冲正）的净消耗泥点。
pub consumed_mud_points: u64,
+ /// 同期退还泥点，用于核对「消耗 + 退还」的毛消耗口径。
+ pub refunded_mud_points: u64,
pub total_registered_users: u64,
pub new_registered_users: u64,
pub day1_retention: AdminDashboardRetentionPayload,
@@ -1127,6 +1130,8 @@ pub struct AdminRechargeOrderEntryPayload {
pub product_title: String,
pub product_kind: String,
pub amount_cents: u64,
+ /// 真实支付金额（分）：只有支付过的订单才有实付，未支付 / 已关闭 / 已过期订单固定为 0。
+ pub paid_amount_cents: u64,
pub status: String,
pub payment_channel: String,
pub paid_at_micros: Option,
@@ -1172,6 +1177,8 @@ pub struct AdminUserDetailResponse {
pub phone_bound: bool,
pub wechat_bound: bool,
pub historical_consumed_points: u64,
+ /// 累计充值金额（分）：该用户全部支付过的充值订单金额之和；读取失败或命中读取上限时为 None。
+ pub cumulative_recharged_cents: Option,
pub can_reconcile_consumption: bool,
pub wallet: AdminProfileWalletPayload,
pub recharge_orders: Vec,
diff --git a/src/components/game-distribution/gameZipPackage.test.ts b/src/components/game-distribution/gameZipPackage.test.ts
index d4f4181a0..ca2a4a826 100644
--- a/src/components/game-distribution/gameZipPackage.test.ts
+++ b/src/components/game-distribution/gameZipPackage.test.ts
@@ -3,7 +3,7 @@
import JSZip from 'jszip';
import { describe, expect, it } from 'vitest';
-import { prepareGamePackage } from './gameZipPackage';
+import { GAME_PACKAGE_MAX_BYTES, prepareGamePackage } from './gameZipPackage';
async function buildZip(files: Record) {
const zip = new JSZip();
@@ -52,4 +52,12 @@ describe('prepareGamePackage', () => {
),
).rejects.toThrow('发行包不是有效的 ZIP');
});
+
+ it('超过上限时在读取字节之前就失败关闭', async () => {
+ // 只伪造体积，不真的分配 200 MiB；预检必须在读字节之前拦下。
+ const oversized = { size: GAME_PACKAGE_MAX_BYTES + 1 } as unknown as File;
+ await expect(prepareGamePackage(oversized)).rejects.toThrow(
+ '发行包不能超过 200 MiB',
+ );
+ });
});
diff --git a/src/components/game-distribution/gameZipPackage.ts b/src/components/game-distribution/gameZipPackage.ts
index eb8497f18..fcc25c8da 100644
--- a/src/components/game-distribution/gameZipPackage.ts
+++ b/src/components/game-distribution/gameZipPackage.ts
@@ -1,6 +1,6 @@
import JSZip from 'jszip';
-export const GAME_PACKAGE_MAX_BYTES = 100 * 1024 * 1024;
+export const GAME_PACKAGE_MAX_BYTES = 200 * 1024 * 1024;
export const GAME_PACKAGE_MAX_FILE_COUNT = 10_000;
export type PreparedGamePackage = {
@@ -59,7 +59,7 @@ export async function prepareGamePackage(
throw new Error('请选择非空的发行包 ZIP');
}
if (file.size > GAME_PACKAGE_MAX_BYTES) {
- throw new Error('发行包不能超过 100 MiB');
+ throw new Error('发行包不能超过 200 MiB');
}
const bytes = await readGamePackageBytes(file);
let archive: JSZip;
void;
onEditorStateChange?: (editorState: EditorState) => void;
@@ -226,6 +237,20 @@ function mentionTokenFromPart(
return null;
}
+/**
+ * part 落进正文时用的文本：provider 的 `mentionToken`，它答不出来（provider 契约被破坏）时退到
+ * `contentPartText` 的通用文本形态。文本 part 自己就是文本，返回 `null`。
+ *
+ * 粘贴插入、润色回写的候选扫描与落点都走这一条：只要 part 不是文本，就一定有一段正常文本可落，
+ * 「认不出的引用走文本、绝不静默丢」在几个入口是同一份实现，不是各写一遍兜底。
+ */
+function mentionTokenOrText(
+ providers: readonly ReferenceProvider[],
+ part: DirectCodexUserContentPart,
+): string | null {
+ return mentionTokenFromPart(providers, part) ?? contentPartText(part);
+}
+
/**
* 草稿的展示文本：把每个引用 part 按注入的 provider 展开成它的 token，其余文本逐字保留。
*
@@ -256,8 +281,10 @@ function applyPolishedTextToRoot(
) {
// 候选按 canonical content 原顺序取：引用、Skill、runtime 区域与附件共用一套 token 扫描，
// 与出站给润色服务的文本口径一致，因此回包保留下来的 token 能原位换回真 part。
+ // provider 答不出 token 的 part 也照样进候选（token 退到 `mentionTokenOrText` 的通用文本形态）：
+ // 它在回包里没被提到时会作为末尾孤儿补回来，而不是从这门翻译里直接消失。
const candidates = current.content.flatMap((part) => {
- const token = mentionTokenFromPart(providers, part);
+ const token = mentionTokenOrText(providers, part);
return token ? [{ token, part }] : [];
});
applyContentToRoot(buildContentFromTextTokens(value, candidates), providers);
@@ -286,8 +313,81 @@ function applyContentToRoot(
const reference = referenceFromPart(providers, part);
if (reference) {
paragraph.append($createResourceReferenceNode(reference));
+ return;
+ }
+ // 解析不出引用的 part 落它的文本（与粘贴同一条兜底链），整根替换同样不许把内容吃掉。
+ const token = mentionTokenOrText(providers, part);
+ if (token) paragraph.append($createTextNode(token));
+ });
+}
+
+/**
+ * 取当前可用的选区：选区缺失、或指向已被重建掉的节点时（跨会话恢复草稿后就是这种），
+ * 统一回落到草稿末尾，避免把内容插到一个已经不存在的位置。取不到时返回 `null`。
+ */
+function $selectionOrRootEnd() {
+ let selection = $getSelection();
+ if (
+ !$isRangeSelection(selection) ||
+ !selection.anchor.getNode().isAttached()
+ ) {
+ $getRoot().selectEnd();
+ selection = $getSelection();
+ }
+ return $isRangeSelection(selection) ? selection : null;
+}
+
+/**
+ * 粘贴插入：在光标处就地插入 content 对应的节点，正文其余部分逐字不动。
+ *
+ * 与 `applyContentToRoot`（整根替换，供初始草稿与润色回写使用）的区别只在替换范围：
+ * 文本 part 的 `\n` 落成真正的段落分隔（与编辑器默认的纯文本粘贴同一形状），引用 part 落成
+ * chip；不加任何补白，token 原位替换、token 之外的每个字符照原样保留。
+ *
+ * 认不出的引用 part（provider 的 `toReference` 解析不出来）退回它的 token 文本；连 provider 的
+ * `mentionToken` 都答不出来时退到 `contentPartText` 的通用文本形态。两条兜底合起来保证
+ * 「粘贴进来的内容一个字符都不会凭空消失」，这个分支不存在什么都不插的出路。
+ *
+ * 返回「这次到底插进去没有」：调用方据此决定要不要接管这次粘贴，插入为空时必须放行
+ * 编辑器的默认粘贴，否则这段文字两边都不管。
+ */
+function $insertContentAtSelection(
+ content: readonly DirectCodexUserContentPart[],
+ providers: readonly ReferenceProvider[],
+): boolean {
+ // 每插一段都重新取一次选区：插入会移动光标，上一轮拿到的那个 RangeSelection 会过期。
+ if (!$selectionOrRootEnd()) return false;
+ let inserted = false;
+ content.forEach((part) => {
+ if (part.type === 'input_text') {
+ part.text.split('\n').forEach((line, index) => {
+ if (index > 0) {
+ $selectionOrRootEnd()?.insertParagraph();
+ inserted = true;
+ }
+ if (line) {
+ $selectionOrRootEnd()?.insertText(line);
+ inserted = true;
+ }
+ });
+ return;
+ }
+ const reference = referenceFromPart(providers, part);
+ if (reference) {
+ $selectionOrRootEnd()?.insertNodes([
+ $createResourceReferenceNode(reference),
+ ]);
+ inserted = true;
+ return;
+ }
+ // 解析不出的 part 已经在上游被摘掉了 token，这里必须把文本补回去，否则这段内容会静默消失。
+ const token = mentionTokenOrText(providers, part);
+ if (token) {
+ $selectionOrRootEnd()?.insertText(token);
+ inserted = true;
}
});
+ return inserted;
}
/**
@@ -361,24 +461,14 @@ function ResourceReferenceEditor({
(nextReferences: ChatReference[]) => {
if (nextReferences.length === 0) return;
editor.update(() => {
- let selection = $getSelection();
- // 跨会话恢复草稿后选区可能仍指向已被重建掉的节点，这里统一回落到草稿末尾，
- // 避免把引用插到一个已经不存在的位置。
- if (
- !$isRangeSelection(selection) ||
- !selection.anchor.getNode().isAttached()
- ) {
- $getRoot().selectEnd();
- selection = $getSelection();
- }
- if ($isRangeSelection(selection)) {
- selection.insertNodes(
- nextReferences.flatMap((reference) => [
- $createResourceReferenceNode(reference),
- $createTextNode(' '),
- ]),
- );
- }
+ const selection = $selectionOrRootEnd();
+ if (!selection) return;
+ selection.insertNodes(
+ nextReferences.flatMap((reference) => [
+ $createResourceReferenceNode(reference),
+ $createTextNode(' '),
+ ]),
+ );
});
editor.focus();
},
@@ -390,19 +480,11 @@ function ResourceReferenceEditor({
const insert = text.replace(/\s+$/u, '');
if (!insert.trim()) return;
editor.update(() => {
- let selection = $getSelection();
- if (
- !$isRangeSelection(selection) ||
- !selection.anchor.getNode().isAttached()
- ) {
- $getRoot().selectEnd();
- selection = $getSelection();
- }
- if ($isRangeSelection(selection)) {
- const rootText = $getRoot().getTextContent();
- if (rootText && !/\s$/u.test(rootText)) selection.insertText(' ');
- selection.insertText(insert);
- }
+ const selection = $selectionOrRootEnd();
+ if (!selection) return;
+ const rootText = $getRoot().getTextContent();
+ if (rootText && !/\s$/u.test(rootText)) selection.insertText(' ');
+ selection.insertText(insert);
});
editor.focus();
},
@@ -522,6 +604,53 @@ function ResourceReferenceEditor({
);
}, [editor, multiline]);
+ // 粘贴解析：只有「粘贴文本里真的解析出了引用 token」且「这一整段真的插进了正文」时才接管，
+ // 其余一律返回 false 放行 Lexical 的默认导入——同 namespace 复制出来的 Lexical payload
+ // 本来就能还原真 chip，不含 token 的纯文本、图片文件粘贴也都保持原行为。
+ //
+ // 接管时整段文本在一次 update 内插入（与默认粘贴同样打 PASTE_TAG），所以一次 Ctrl+Z 就整体
+ // 回退；token 之外的每个字符逐字保留（换行落成段落分隔，与默认纯文本粘贴同形状）。
+ useEffect(() => {
+ return editor.registerCommand(
+ PASTE_COMMAND,
+ (event) => {
+ const clipboardData = (event as ClipboardEvent | null)?.clipboardData;
+ if (!clipboardData || typeof clipboardData.getData !== 'function') {
+ return false;
+ }
+ // 同 namespace 的 Lexical payload 自带真 chip，不抢它的默认导入。
+ if (clipboardData.getData(LEXICAL_EDITOR_CLIPBOARD_TYPE)) return false;
+ const text = clipboardData.getData('text/plain');
+ if (!text.trim()) return false;
+ const providers = providersRef.current;
+ // 只认「此刻就绪」的候选：数据还没到的种类本次按文本保留，输入区不等待也不补读。
+ const references = providers.flatMap(
+ (provider) => provider.lookup?.() ?? [],
+ );
+ const content = buildContentFromPastedText(text, references);
+ if (!content) return false;
+ // 先真的插进去，再决定接管这次粘贴：插入为空（取不到选区）时必须放行默认粘贴，
+ // 否则这段文字既没进我们的插入、又被 preventDefault 挡掉了默认导入，静默消失。
+ // 编辑器已经在一次更新里时 `editor.update` 会把回调排队，这时 `ranSync` 仍是 false，
+ // 按原口径先接管，等队列里的那次插入落地。
+ let ranSync = false;
+ let inserted = false;
+ editor.update(
+ () => {
+ ranSync = true;
+ inserted = $insertContentAtSelection(content, providersRef.current);
+ },
+ // 与编辑器默认粘贴同一口径：粘贴是它自己的一条撤销记录。
+ { tag: PASTE_TAG },
+ );
+ if (ranSync && !inserted) return false;
+ event.preventDefault();
+ return true;
+ },
+ COMMAND_PRIORITY_CRITICAL,
+ );
+ }, [editor]);
+
// —— C8 AI 润色与发送前提醒 ——
// 润色状态机抽到 `usePromptPolish`（资源侧两处入口共用同一份）；这里只剩下
// 聊天特有的「发送前提醒」：提醒偏好、本轮已确认草稿指纹与表单拦截。
@@ -796,16 +925,16 @@ function ProviderMentionMenu({
[onOpenChange, trigger],
);
- // 懒加载的唯一入口：菜单开合/查询变化经 effect 回调给 provider，`match` 始终保持纯函数，
+ // 懒加载的唯一入口：菜单开合/查询变化经 effect 回调给 provider，`fuzzyLookup` 始终保持纯函数，
// 渲染阶段（下面的 useMemo）不会替 provider 发起请求、写 ref 或读清单。
useEffect(() => {
provider.onMenuQueryChange?.(query);
}, [provider, query]);
const options = useMemo(() => {
- if (query === null || !provider.match) return [];
+ if (query === null || !provider.fuzzyLookup) return [];
return provider
- .match(query)
+ .fuzzyLookup(query)
.map((reference) => new ReferenceMentionOption(reference));
}, [provider, query]);
diff --git a/apps/ai-game-creator-shell/src/features/project-workspace/reference-source/attachmentReferenceProvider.ts b/apps/ai-game-creator-shell/src/features/project-workspace/reference-source/attachmentReferenceProvider.ts
index 762ef2657..b0b9a0afb 100644
--- a/apps/ai-game-creator-shell/src/features/project-workspace/reference-source/attachmentReferenceProvider.ts
+++ b/apps/ai-game-creator-shell/src/features/project-workspace/reference-source/attachmentReferenceProvider.ts
@@ -1,5 +1,8 @@
import type { DirectCodexUserContentPart } from '../../../view/project-development/chat/generated/DirectCodexUserContentPart';
-import type { ChatReference } from '../resourceReferences';
+import {
+ type ChatReference,
+ normalizeMentionName,
+} from '../resourceReferences';
import type { ReferenceProvider } from './types';
/** canonical 附件 part → `ChatReference` 的附件成员（字段逐字对齐）。 */
@@ -8,7 +11,7 @@ export function attachmentReferenceFromPart(
): ChatReference {
return {
type: 'attachment',
- name: part.name,
+ name: normalizeMentionName(part.name),
mediaType: part.mediaType,
size: part.size,
localPath: part.localPath,
@@ -32,7 +35,9 @@ export function createAttachmentReferenceProvider(): ReferenceProvider {
refresh: (reference: ChatReference): ChatReference | null =>
reference.type === 'attachment' ? reference : null,
mentionToken: (part) =>
- part.type === 'agc_attachment_reference' ? `@${part.name}` : null,
+ part.type === 'agc_attachment_reference'
+ ? `@${normalizeMentionName(part.name)}`
+ : null,
};
}
diff --git a/apps/ai-game-creator-shell/src/features/project-workspace/reference-source/resourceReferenceProvider.ts b/apps/ai-game-creator-shell/src/features/project-workspace/reference-source/resourceReferenceProvider.ts
index cf7c9b5be..7f724c365 100644
--- a/apps/ai-game-creator-shell/src/features/project-workspace/reference-source/resourceReferenceProvider.ts
+++ b/apps/ai-game-creator-shell/src/features/project-workspace/reference-source/resourceReferenceProvider.ts
@@ -49,12 +49,14 @@ export function createResourceReferenceProvider({
}): ReferenceProvider {
return {
trigger: '@',
- match: (query) =>
+ fuzzyLookup: (query) =>
resourceProviderData(assets)
.references.filter((reference) =>
resourceReferenceMatchesQuery(reference, query),
)
.slice(0, MENTION_OPTION_LIMIT),
+ // 精确查找用的全量候选：与菜单同一份「可提及」清单，只去掉模糊过滤与截断。
+ lookup: () => resourceProviderData(assets).references,
toReference: (part: DirectCodexUserContentPart): ChatReference | null => {
if (part.type !== 'agc_resource_reference') return null;
const asset = resourceProviderData(assets).byId.get(part.resourceId);
diff --git a/apps/ai-game-creator-shell/src/features/project-workspace/reference-source/skillReferenceProvider.ts b/apps/ai-game-creator-shell/src/features/project-workspace/reference-source/skillReferenceProvider.ts
index e3c34da47..e99648c42 100644
--- a/apps/ai-game-creator-shell/src/features/project-workspace/reference-source/skillReferenceProvider.ts
+++ b/apps/ai-game-creator-shell/src/features/project-workspace/reference-source/skillReferenceProvider.ts
@@ -2,7 +2,10 @@ import { useCallback, useMemo, useRef, useState } from 'react';
import { resolveTauriInvoke } from '../../../app/tauri';
import type { DirectCodexUserContentPart } from '../../../view/project-development/chat/generated/DirectCodexUserContentPart';
-import type { ChatReference } from '../resourceReferences';
+import {
+ type ChatReference,
+ normalizeMentionName,
+} from '../resourceReferences';
import type { ReferenceProvider } from './types';
/** 候选菜单最多展示多少条：与资源候选同一上限。 */
@@ -25,7 +28,7 @@ function loadSkillCatalog(): Promise {
'list_agc_skill_catalog',
).then((items) =>
items.map((item) => ({
- name: item.name,
+ name: normalizeMentionName(item.name),
description: item.description,
})),
),
@@ -44,12 +47,15 @@ function loadSkillCatalog(): Promise {
item.enabled &&
item.status === 'enabled',
)
- .map((item) => ({ name: item.name })),
+ .map((item) => ({ name: normalizeMentionName(item.name) })),
),
]).then(([builtin, client]) => [...builtin, ...client]);
}
-function matchesSkillQuery(skill: SkillCatalogItem, query: string) {
+function matchesSkillQuery(
+ skill: { name: string; description?: string },
+ query: string,
+) {
const normalized = query.trim().toLowerCase();
if (!normalized) return true;
return (
@@ -58,13 +64,29 @@ function matchesSkillQuery(skill: SkillCatalogItem, query: string) {
);
}
+/** 目录项 → 引用：同名只留第一条（与 `fuzzyLookup` 同一份去重口径）。 */
+function skillReferences(skills: readonly SkillCatalogItem[]) {
+ const seen = new Set();
+ const references: ChatReference[] = [];
+ for (const skill of skills) {
+ if (seen.has(skill.name)) continue;
+ seen.add(skill.name);
+ references.push({
+ type: 'skill',
+ name: skill.name,
+ description: skill.description,
+ });
+ }
+ return references;
+}
+
/**
* Skill 引用的 provider（宿主 hook）。
*
* 与资源 provider 不同，Skill 候选是**异步**的应用级读取，所以它必须是一份 React 状态：
* 用户敲出 `$` 打开候选菜单时（`onMenuQueryChange` 收到非 `null`，由输入区在 effect 里回调）
* 发起读取，结果到了之后宿主重渲染，输入区随之拿到新的候选。
- * `match` 保持纯函数，候选只从已就绪的状态里过滤——渲染阶段不产生任何副作用。
+ * `fuzzyLookup` 保持纯函数，候选只从已就绪的状态里过滤——渲染阶段不产生任何副作用。
* 读取本身不进输入区，只有宿主才知道这条路该不该存在——
* 目前只有 DirectProject 回合会把 `agc_skill_reference` 解析成真 Skill。
*/
@@ -96,31 +118,26 @@ export function useSkillReferenceProvider(): ReferenceProvider {
onMenuQueryChange: (query) => {
if (query !== null) ensureCatalog();
},
- match: (query) => {
- const seen = new Set();
- return skills
- .filter((skill) => {
- if (seen.has(skill.name)) return false;
- seen.add(skill.name);
- return matchesSkillQuery(skill, query);
- })
- .slice(0, MENTION_OPTION_LIMIT)
- .map(
- (skill): ChatReference => ({
- type: 'skill',
- name: skill.name,
- description: skill.description,
- }),
- );
+ // 精确查找：目录还没就绪（用户还没敲过 `$`）时返回空数组，本次 `$名称` 逐字保留。
+ lookup: () => skillReferences(skills),
+ fuzzyLookup: (query) => {
+ return skillReferences(skills)
+ .filter(
+ (reference) =>
+ reference.type === 'skill' && matchesSkillQuery(reference, query),
+ )
+ .slice(0, MENTION_OPTION_LIMIT);
},
toReference: (part: DirectCodexUserContentPart): ChatReference | null =>
part.type === 'agc_skill_reference'
- ? { type: 'skill', name: part.name }
+ ? { type: 'skill', name: normalizeMentionName(part.name) }
: null,
refresh: (reference: ChatReference): ChatReference | null =>
reference.type === 'skill' ? reference : null,
mentionToken: (part) =>
- part.type === 'agc_skill_reference' ? `$${part.name}` : null,
+ part.type === 'agc_skill_reference'
+ ? `$${normalizeMentionName(part.name)}`
+ : null,
}),
[ensureCatalog, skills],
);
diff --git a/apps/ai-game-creator-shell/src/features/project-workspace/reference-source/types.ts b/apps/ai-game-creator-shell/src/features/project-workspace/reference-source/types.ts
index ca138d75f..bf78a4901 100644
--- a/apps/ai-game-creator-shell/src/features/project-workspace/reference-source/types.ts
+++ b/apps/ai-game-creator-shell/src/features/project-workspace/reference-source/types.ts
@@ -19,12 +19,25 @@ export type ReferenceProvider = {
*/
trigger: string | null;
/**
- * 候选项：过滤、排序与截断都在 provider 内部完成。静默 provider 不实现。
+ * 模糊查询：候选菜单的过滤。名字写明它是模糊的——按 query 做包含匹配、大小写不敏感，
+ * 并在 provider 内部截断到候选上限。静默 provider 不实现。
*
* **必须是纯函数**：输入区在渲染阶段（`useMemo`）调用它，读清单、写 ref、发请求都会
* 在渲染期生效。需要为「菜单打开」拉一次数据时，用下面的 `onMenuQueryChange`。
+ * 精确查找用 `lookup`，不要拿它反查 token。
*/
- match?: (query: string) => ChatReference[];
+ fuzzyLookup?: (query: string) => ChatReference[];
+ /**
+ * 精确查找用的全量候选：某一刻 provider 真正能解析出的所有引用，不做模糊过滤、不截断。
+ *
+ * 与 `fuzzyLookup` 的区别只有「模糊与截断」，两者共用同一份候选来源。没有触发符的静默
+ * provider 不实现。
+ *
+ * **同样是纯函数**：输入区在粘贴事件里同步调用它；只返回已就绪的快照，不发起任何读取。
+ * 数据还没到时返回空数组（或省略不实现），解析不出的 token 逐字保留——例如 Skill 目录的就绪
+ * 时机仍是用户第一次敲出 `$`，冷启动时粘贴 `$名称` 就是字面文本，不会被猜成别的引用。
+ */
+ lookup?: () => ChatReference[];
/**
* 候选菜单的查询变化（菜单关闭时收到 `null`）；输入区在 `useEffect` 里调它，**只在
* 带触发符的 provider 上调用**。
diff --git a/apps/ai-game-creator-shell/src/features/project-workspace/resourceReferences.ts b/apps/ai-game-creator-shell/src/features/project-workspace/resourceReferences.ts
index 85f814c3f..adc78ecba 100644
--- a/apps/ai-game-creator-shell/src/features/project-workspace/resourceReferences.ts
+++ b/apps/ai-game-creator-shell/src/features/project-workspace/resourceReferences.ts
@@ -154,6 +154,26 @@ export function resourceLabelResolver(
};
}
+/**
+ * 引用名（资源显示名 / Skill 名 / 附件名）的空白不变量：`@显示名`、`$名称`、`@附件名` 里
+ * 不允许出现空白，内部空白统一折成 `-`。
+ *
+ * 引用的名字同时就是它在正文里的 token，而 token 的边界规则是「前后为空白或行首行尾」
+ * （`isMentionTokenBoundary`）。名字里一旦有空白，`@hero v2` 在反解析时会被切成 `@hero` +
+ * 文本 `v2`：短名字抢先命中，真正的引用反而变成补在末尾的孤儿。空白折成 `-` 之后 token 自带
+ * 边界，`@hero` 不会再命中 `@hero-v2`（后一个字符是 `-`，不是空白）。
+ *
+ * 这里只做归一化、不做 `resourceId` 之类的兜底：兜底属于名字的来源侧（例如
+ * `resourceDisplayName` 在文件名词干为空时回退 `asset.id`），归一化本身保持是个纯函数。
+ *
+ * 归一化不保证名字唯一：`hero v2` 与 `hero-v2` 会折成同一个 token，两条引用因此在候选菜单里
+ * 显示同一个标签。归一化后的碰撞由 `buildContentFromPastedText` 的「同名多候选一律按文本保留」
+ * 兜住（不认错，但两者都成不了 chip）；候选菜单侧不做冲突检测，标签重复是这条取舍的可见残留。
+ */
+export function normalizeMentionName(value: string) {
+ return value.trim().replace(/\s+/gu, '-');
+}
+
/**
* canonical content → 可读文本；每个引用 part 经 `tokenOf` 展开，文本 part 逐字保留。
*
@@ -207,13 +227,44 @@ export function directCodexContentToPromptText(
content: readonly DirectCodexUserContentPart[],
resolveResourceLabel: ResourceLabelResolver,
) {
- return joinMentionText(content, (part) => {
- if (part.type === 'input_text') return null;
- if (part.type === 'agc_attachment_reference') return `@${part.name}`;
- if (part.type === 'agc_skill_reference') return `$${part.name}`;
- if (part.type === 'agc_runtime_region_reference') return `@${part.label}`;
- return `@${resolveResourceLabel(part.resourceId) ?? part.resourceId}`;
- });
+ return joinMentionText(content, (part) =>
+ contentPartToken(part, resolveResourceLabel),
+ );
+}
+
+/**
+ * 一个 part 在正文文本里的 token（`@显示名` / `$名称` / `@附件名` / `@区域标签`）；文本 part
+ * 没有 token，返回 `null`。
+ *
+ * 逐字返回 token 本身：不带补白、不裁剪——补白是 `joinMentionText` 在拼整段文本时加的，
+ * 什么时候需要留白由那里的上下文决定，token 的投影不替它决定。
+ */
+function contentPartToken(
+ part: DirectCodexUserContentPart,
+ resolveResourceLabel: ResourceLabelResolver,
+): string | null {
+ if (part.type === 'input_text') return null;
+ if (part.type === 'agc_attachment_reference')
+ return `@${normalizeMentionName(part.name)}`;
+ if (part.type === 'agc_skill_reference')
+ return `$${normalizeMentionName(part.name)}`;
+ if (part.type === 'agc_runtime_region_reference') return `@${part.label}`;
+ return `@${normalizeMentionName(
+ resolveResourceLabel(part.resourceId) ?? part.resourceId,
+ )}`;
+}
+
+/**
+ * 单个非文本 part 的文本形态，就是它的 token（见 `contentPartToken`）：资源拿不到显示名时
+ * 退回 `resourceId`。文本 part 没有文本形态，返回 `null`。
+ *
+ * 只给「插入那一刻解析不出引用、也拿不到 provider 的 token」兜底：粘贴过来的字必须落下去，
+ * 哪怕落成一段文本。它不参与解析，也不是解析依据——扫描一律用 `chatReferenceMentionToken`。
+ */
+export function contentPartText(
+ part: DirectCodexUserContentPart,
+): string | null {
+ return contentPartToken(part, () => undefined);
}
/** 只在整条 content 上判定有效性；单个纯空白文本 part 合法。 */
@@ -290,8 +341,12 @@ export function chatReferenceToContentPart(
* 资源与运行画面区域 `@显示名`。资源引用自带显示名，所以这里不必再查 manifest。
*/
export function chatReferenceMentionToken(reference: ChatReference): string {
- if (reference.type === 'skill') return `$${reference.name}`;
- if (reference.type === 'attachment') return `@${reference.name}`;
+ if (reference.type === 'skill')
+ return `$${normalizeMentionName(reference.name)}`;
+ if (reference.type === 'attachment')
+ return `@${normalizeMentionName(reference.name)}`;
+ if (reference.type === 'resource')
+ return `@${normalizeMentionName(reference.label)}`;
return `@${reference.label}`;
}
@@ -417,6 +472,74 @@ export function buildContentFromTextTokens(
return content;
}
+/** token 在整段文本里出现的次数：与 `findMentionToken` 同一套边界规则，按行统计。 */
+function countMentionTokenOccurrences(value: string, token: string) {
+ let count = 0;
+ for (const line of value.split(/\r?\n/u)) {
+ let from = 0;
+ for (;;) {
+ const index = findMentionToken(line, token, from);
+ if (index < 0) break;
+ count += 1;
+ from = index + token.length;
+ }
+ }
+ return count;
+}
+
+/**
+ * 粘贴文本 → canonical content（粘贴侧的唯一解析口径）。
+ *
+ * 候选来自调用方传入的引用清单（输入区给的是 `ReferenceProvider.lookup()` 此刻就绪的全量
+ * 候选），token 就是
+ * `chatReferenceMentionToken`——与显示口径逐字同一个字符串，所以「从气泡复制再粘贴」不需要
+ * 任何兼容别名：`@显示名` / `$名称` 认得出，`@hero.png`、resourceId、大小写变体一律不认。
+ *
+ * 三条保守规则：
+ *
+ * - 同名多候选（同一个 token 对应多条引用身份）一律按文本保留——宁可不成 chip，也不能认错引用。
+ * - 退化 token（只有触发符的裸 `@` / `$`，即引用名为空）不参与解析：边界规则会把正文里
+ * 任何一处裸 `@` 当成它，等于把无关文字错认成一条引用。
+ * - 只把正文里真的出现过的 token 交给 `buildContentFromTextTokens`，不做「未命中候选补到末尾」
+ * （那是润色回包的语义，照搬会把整份清单追加到粘贴文本后面）。同一 token 出现几次就展开几条
+ * 候选，所以重复出现的引用会各自原位成 chip。
+ *
+ * 返回 `null` 表示这段文本里没有任何可解析的 token，调用方应放行编辑器的默认粘贴。
+ */
+export function buildContentFromPastedText(
+ value: string,
+ references: readonly ChatReference[],
+): DirectCodexUserContentPart[] | null {
+ const referencesByToken = new Map();
+ for (const reference of references) {
+ const token = chatReferenceMentionToken(reference);
+ const bucket = referencesByToken.get(token);
+ if (!bucket) {
+ referencesByToken.set(token, [reference]);
+ continue;
+ }
+ const key = chatReferenceKey(reference);
+ if (!bucket.some((item) => chatReferenceKey(item) === key)) {
+ bucket.push(reference);
+ }
+ }
+ const candidates: ContentTokenCandidate[] = [];
+ for (const [token, bucket] of referencesByToken) {
+ // 名字为空的引用只会给出一个裸触发符：它能在正文里匹配到任何一处 `@` / `$`，
+ // 认下来就是错认。空名字是上游数据问题，这里按「宁可不成 chip」的同一口径跳过。
+ if (token.length <= 1) continue;
+ if (bucket.length !== 1) continue;
+ const reference = bucket[0]!;
+ const part = chatReferenceToContentPart(reference);
+ const occurrences = countMentionTokenOccurrences(value, token);
+ for (let index = 0; index < occurrences; index += 1) {
+ candidates.push({ token, part });
+ }
+ }
+ if (candidates.length === 0) return null;
+ return buildContentFromTextTokens(value, candidates);
+}
+
/**
* legacy「text + references + attachments」DTO → canonical content：旧调用方继续吐双轨
* 形状，这里按 token 扫回真 part，不另立第二份事实源。
@@ -540,9 +663,18 @@ export function directCodexContentToLegacyContentDto(
};
}
+/**
+ * 素材显示名：文件名去掉扩展名，再过一遍引用名口径（见 `normalizeMentionName`）。
+ *
+ * 整名就是扩展名时（`.env`、`.gitignore`）去扩展名会得到空串，这里回退 `asset.id`：
+ * 显示名同时是正文里的 token，空名字会退化成只有触发符的裸 `@`——候选菜单里是一枚空芯片，
+ * 粘贴解析还会拿它认领正文里任何一处裸 `@`（见 `buildContentFromPastedText`）。
+ * 与渲染侧「显示名解析不到就用 `resourceId`」是同一口径。
+ */
export function resourceDisplayName(asset: GameCreationAppAssetManifestEntry) {
const fileName = asset.localPath.split(/[\\/]/u).pop() ?? asset.id;
- return fileName.replace(/\.[^.]+$/u, '').trim() || asset.id;
+ const stem = fileName.replace(/\.[^.]+$/u, '');
+ return normalizeMentionName(stem || asset.id);
}
export function resourceReferenceFromAsset(
diff --git a/apps/ai-game-creator-shell/src/services/gameDistributionPublish.ts b/apps/ai-game-creator-shell/src/services/gameDistributionPublish.ts
index 5e1a96402..993ccd754 100644
--- a/apps/ai-game-creator-shell/src/services/gameDistributionPublish.ts
+++ b/apps/ai-game-creator-shell/src/services/gameDistributionPublish.ts
@@ -7,10 +7,12 @@ import type {
GameDistributionOrientation,
} from '../../../../packages/shared/src/contracts/gameDistribution';
import type {
- LocalProjectExportPackagePayload,
+ GamePackageUploadOutcome,
+ StagedGamePackage,
TauriInvoke,
} from '../app/types';
-import { requestClientApi } from './clientApi';
+import { getStoredAuthAccessToken, requestClientApi } from './clientApi';
+import { getClientServerBaseUrl } from './clientHttp';
export type GameDistributionPublishMetadata = {
title: string;
@@ -328,20 +330,20 @@ export async function publishLocalProjectGame(args: {
if (!projectPath || !packageRelativePath) {
throw new Error('发布需要绑定本地项目和试玩包');
}
- const payload = await args.invoke(
- 'read_local_project_export_package',
+ // 整包字节只留在原生进程：这里拿到的是归一化后的摘要与内容寻址暂存路径，
+ // 上传由原生侧按服务端分片大小完成，中断后同一暂存文件可直接续传。
+ const staged = await args.invoke(
+ 'prepare_local_project_game_package',
{ projectPath, packageRelativePath },
);
if (
- !payload.packageBytes.length ||
- payload.packageSizeBytes !== payload.packageBytes.length ||
- payload.files.length === 0
+ !staged.stagingPath.trim() ||
+ staged.packageSha256.length !== 64 ||
+ staged.packageSizeBytes <= 0 ||
+ staged.packageFileCount <= 0
) {
throw new Error('本地发行包摘要无效，请重新导出试玩包');
}
- if (payload.packageRelativePath !== packageRelativePath) {
- throw new Error('本地发行包路径已变化，请重新导出试玩包');
- }
const metadata = normalizeMetadata(args.manifest, args.metadata);
const localProjectId = args.manifest.projectId.trim();
@@ -369,9 +371,9 @@ export async function publishLocalProjectGame(args: {
const versionRequest: GameDistributionCreateVersionRequest = {
localProjectId,
- packageSha256: payload.packageSha256,
- packageBytes: payload.packageSizeBytes,
- packageFileCount: payload.files.length,
+ packageSha256: staged.packageSha256,
+ packageBytes: staged.packageSizeBytes,
+ packageFileCount: staged.packageFileCount,
packageEntryPath: 'index.html',
gameMetadata,
};
@@ -391,23 +393,19 @@ export async function publishLocalProjectGame(args: {
throw new Error('创建发行版本未返回版本 ID');
}
- const packageBody = new Blob([new Uint8Array(payload.packageBytes)], {
- type: 'application/zip',
- });
- const uploaded = await requestClientApi<{
- versionId: string;
- status: string;
- }>(
- `/api/game-distribution/versions/${encodeURIComponent(version.versionId)}/package`,
+ const accessToken = getStoredAuthAccessToken();
+ if (!accessToken) {
+ throw new Error('陶泥儿登录凭据缺失，请重新登录');
+ }
+ const uploaded = await args.invoke(
+ 'upload_local_project_game_package',
{
- method: 'PUT',
- headers: {
- 'Content-Type': 'application/zip',
- 'Idempotency-Key': `${rootKey}:upload`,
- },
- body: packageBody,
+ stagingPath: staged.stagingPath,
+ versionId: version.versionId,
+ apiBaseUrl: getClientServerBaseUrl(),
+ accessToken,
+ idempotencyKey: `${rootKey}:upload`,
},
- '上传游戏发行包失败',
);
const submitted = await requestClientApi<{
game?: { publicationRevision?: number };
@@ -431,8 +429,8 @@ export async function publishLocalProjectGame(args: {
versionId: version.versionId,
versionNumber: version.versionNumber,
status: submitted?.version?.status ?? uploaded?.status ?? 'pending_review',
- packageSha256: payload.packageSha256,
- packageSizeBytes: payload.packageSizeBytes,
- fileCount: payload.files.length,
+ packageSha256: staged.packageSha256,
+ packageSizeBytes: staged.packageSizeBytes,
+ fileCount: staged.packageFileCount,
};
}
diff --git a/apps/ai-game-creator-shell/src/styles.css b/apps/ai-game-creator-shell/src/styles.css
index f811ada71..d567a5a77 100644
--- a/apps/ai-game-creator-shell/src/styles.css
+++ b/apps/ai-game-creator-shell/src/styles.css
@@ -117,7 +117,11 @@ body {
.app-update-overlay {
position: fixed;
z-index: 260;
- inset: 0;
+ /* 中文注释：全屏弹层一律从自绘标题栏下方开始，标题栏的最小化 / 最大化 / 关闭必须始终可用。 */
+ top: var(--window-chrome-height);
+ right: 0;
+ bottom: 0;
+ left: 0;
display: grid;
padding: 24px;
background: rgb(35 20 12 / 48%);
@@ -209,7 +213,13 @@ body {
}
:root {
- /* 网页内自绘标题栏占用的顶部高度；portal 到 body 的固定弹层也要从它下方开始。 */
+ /*
+ * 网页内自绘标题栏占用的顶部高度。
+ *
+ * 约定：portal 到 body 的全屏固定弹层一律从标题栏下方开始（`top: var(--window-chrome-height)`）。
+ * 标题栏是窗口边框，不是弹层内容 —— 弹出任何面板时「最小化 / 最大化 / 关闭」和拖拽都必须
+ * 保持可用；模态内部的焦点陷阱也必须放行落在标题栏上的点击（见 `ThemedModal`）。
+ */
--window-chrome-height: 50px;
}
@@ -9744,7 +9754,11 @@ iframe.preview-frame {
.game-publish-progress-overlay {
position: fixed;
z-index: 500;
- inset: 0;
+ /* 中文注释：发布进行中仍然要能最小化 / 关闭窗口，遮罩只压住工作区。 */
+ top: var(--window-chrome-height);
+ right: 0;
+ bottom: 0;
+ left: 0;
background: rgb(35 24 19 / 62%);
backdrop-filter: blur(3px);
pointer-events: auto;
diff --git a/apps/ai-game-creator-shell/src/view/project-development/chat/conversation/directCodexTurnAttachments.ts b/apps/ai-game-creator-shell/src/view/project-development/chat/conversation/directCodexTurnAttachments.ts
index aee761531..c5c7ec553 100644
--- a/apps/ai-game-creator-shell/src/view/project-development/chat/conversation/directCodexTurnAttachments.ts
+++ b/apps/ai-game-creator-shell/src/view/project-development/chat/conversation/directCodexTurnAttachments.ts
@@ -1,4 +1,5 @@
import type { LauncherImportedAttachment } from '../../../../app/types';
+import { normalizeMentionName } from '../../../../features/project-workspace/resourceReferences';
export type DirectCodexTurnAttachment = {
name: string;
@@ -16,7 +17,8 @@ export function toDirectCodexTurnAttachments(
}
return imported.map((item) => {
const attachment: DirectCodexTurnAttachment = {
- name: item.fileName,
+ // 附件名同时是正文里的 `@附件名` token，所以和其它引用名一样不允许空白（见 normalizeMentionName）。
+ name: normalizeMentionName(item.fileName),
mediaType: item.mediaType,
};
if (
diff --git a/apps/ai-game-creator-shell/src/view/project-development/planning/PlanningChatView.tsx b/apps/ai-game-creator-shell/src/view/project-development/planning/PlanningChatView.tsx
index d0b7d74d4..645a8e957 100644
--- a/apps/ai-game-creator-shell/src/view/project-development/planning/PlanningChatView.tsx
+++ b/apps/ai-game-creator-shell/src/view/project-development/planning/PlanningChatView.tsx
@@ -31,6 +31,7 @@ import {
DesignAgentPendingActions,
DesignAgentPhaseStatus,
} from './DesignAgentSurface';
+import type { DesignReplyAnimation } from './useDesignReplyAnimation';
/** 后台任务失败文案要过一遍运行态错误解释器再给用户看。 */
function planningMessageText(message: Pick) {
@@ -80,7 +81,8 @@ type PlanningChatViewProps = {
onSubmit: FormEventHandler;
pendingConfirmation: PendingUiConfirmation | null;
projectPath: string;
- transientReply: string;
+ replyAnimations?: DesignReplyAnimation[];
+ designStatus?: string;
showDesignReasoning?: boolean;
designReasoning?: string;
designReasoningEntries?: DesignReasoningEntry[];
@@ -117,7 +119,8 @@ export function PlanningChatView({
onSubmit,
pendingConfirmation,
projectPath,
- transientReply,
+ replyAnimations = [],
+ designStatus = '',
showDesignReasoning = false,
designReasoning = '',
designReasoningEntries = [],
@@ -169,34 +172,67 @@ export function PlanningChatView({
const handleDesignClarify = onDesignClarify ?? (() => undefined);
const handleDesignRetry = onDesignRetry ?? (() => undefined);
- const renderMessage = (message: ChatMessage, index: number) => (
-
@@ -251,7 +287,7 @@ export function PlanningChatView({
) : null}
- {visibleMessages.map(renderMessage)}
+ {displayedMessages.map(renderMessage)}
{showDesignReasoning
? designReasoningEntries
.filter((entry) => !entry.messageId)
@@ -269,20 +305,9 @@ export function PlanningChatView({
label="策划 Agent 思考过程"
/>
) : null}
- {transientReply ? (
-
-
-
- {showDesignReasoning && message.reasoningText ? (
-
+ const animationsById = new Map(
+ replyAnimations.map((reply) => [reply.messageId, reply]),
);
+ const displayedMessages = [...visibleMessages];
+ const conversationIds = new Set(
+ conversationMessages.map((message) => message.messageId),
+ );
+ for (const reply of replyAnimations) {
+ if (
+ !reply.persisted &&
+ reply.target &&
+ !conversationIds.has(reply.messageId)
+ ) {
+ displayedMessages.push({
+ role: 'assistant',
+ messageId: reply.messageId,
+ text: reply.target,
+ });
+ }
+ }
+ const renderMessage = (message: ChatMessage, index: number) => {
+ const animation = message.messageId
+ ? animationsById.get(message.messageId)
+ : undefined;
+ const streaming = Boolean(
+ animation &&
+ (!animation.persisted || animation.visible !== animation.target),
+ );
+ return (
+
+
+
+ {showDesignReasoning && message.reasoningText ? (
+
+ );
+ };
return (
-
-
+ {designStatus ? (
+
diff --git a/apps/ai-game-creator-shell/src/view/project-development/planning/useDesignReplyAnimation.ts b/apps/ai-game-creator-shell/src/view/project-development/planning/useDesignReplyAnimation.ts
new file mode 100644
index 000000000..d8c6ef578
--- /dev/null
+++ b/apps/ai-game-creator-shell/src/view/project-development/planning/useDesignReplyAnimation.ts
@@ -0,0 +1,113 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+
+import type { DesignView } from '../../../app/types';
+
+export type DesignReplyAnimation = {
+ messageId: string;
+ target: string;
+ visible: string;
+ persisted: boolean;
+};
+
+/** 正文动画只管理显示进度，不延迟正式会话状态或参与请求收尾。 */
+export function useDesignReplyAnimation() {
+ const entriesRef = useRef
+ {designStatus}
) : null}
+
+
+
+