新增后台 AGC 模板管理与模板库内容寻址落库

- 后台新增「模板管理」页：按权限查看并编辑模板名称/简介/标签/封面，支持上架与下架；路由、侧栏、tab 权限、API 客户端与 DTO 同步接入
- api-server 新增 /admin/api/agc-templates 读取与更新路由，复用现有后台鉴权与 tab 权限校验，权限不足按既有失败关闭口径拒绝
- module-assets 收敛模板库纯规则（active/inactive 投影、索引 schema 与重复项校验、ZIP 大小与摘要核对），platform-oss 承担对象存储读写、不可变对象复用与发布互斥锁
- shared-contracts 补后台模板 DTO；spacetime-module 账号存储适配保持既有 schema 不变
- AGC 壳内置模板索引与建项读取改为内容寻址对象，补模板安装、越界归档、索引不匹配等用例
- 模板库发布脚本支持定向发布与上架/下架合并、内容地址复用与锁语义，CLI 守卫用例同步；jenkins 两条客户端打包管线统一触发邮件通知 Job 并传递首装包链接
- 内置 5 个 Cocos 官方模板载荷与索引 fixture（内容地址对象，共 90 个文件）
- 补「后台模板管理」里程碑与实施计划，更新模板库技术方案、开发运维文档与共享记忆
- 验证：admin-web 39 项用例与 typecheck、发布脚本 25 项用例、api-server 与 AGC 壳编译、模板库定向 Rust 用例（AGC 壳 18 项、module-assets/platform-oss 16 项、后台权限 1 项）、check:encoding / check:doc-index / check:production-ops / rustfmt 全部通过

apps/admin-web/src/api/adminApiClient.test.ts

@@ -3,12 +3,14 @@ import { afterEach, expect, test, vi } from 'vitest';
 import {
   createAdminAccount,
   executeAdminRechargeRefund,
+  getAdminAgcTemplates,
   getAdminFeatureGateConfig,
   getAdminUserDetail,
   listAdminRechargeOrders,
   reconcileAdminUserConsumption,
   resolveAdminRechargeRefundManualReview,
   updateAdminAccount,
+  updateAdminAgcTemplate,
   uploadAdminEditorShowcaseCampaignImage,
   upsertAdminFeatureGateConfig,
   upsertProfileWalletConfig,
@@ -18,6 +20,51 @@ afterEach(() => {
   vi.unstubAllGlobals();
 });
 
+test('模板管理读取和更新复用认证封装，提交 revision 和封面但不提交 ZIP 或版本', async () => {
+  const library = { revision: 'revision-new', writable: true, templates: [] };
+  const fetchMock = vi.fn().mockImplementation(
+    async () =>
+      new Response(JSON.stringify({ ok: true, data: library }), {
+        status: 200,
+      }),
+  );
+  vi.stubGlobal('fetch', fetchMock);
+  const controller = new AbortController();
+  expect(await getAdminAgcTemplates('admin-token', controller.signal)).toEqual(
+    library,
+  );
+  const update = {
+    expectedRevision: 'revision-old',
+    title: '空白模板',
+    summary: '简介',
+    tags: ['2D'],
+    enabled: true,
+    cover: { contentType: 'image/png', dataBase64: 'aW1hZ2U=' },
+  };
+  expect(
+    await updateAdminAgcTemplate('admin-token', 'template/1', update),
+  ).toEqual(library);
+  expect(fetchMock.mock.calls[0]).toEqual([
+    '/admin/api/agc-templates',
+    expect.objectContaining({
+      method: 'GET',
+      signal: controller.signal,
+      headers: expect.objectContaining({ Authorization: 'Bearer admin-token' }),
+    }),
+  ]);
+  expect(fetchMock.mock.calls[1]).toEqual([
+    '/admin/api/agc-templates/template%2F1',
+    expect.objectContaining({
+      method: 'PUT',
+      headers: expect.objectContaining({
+        Authorization: 'Bearer admin-token',
+        'Content-Type': 'application/json',
+      }),
+      body: JSON.stringify(update),
+    }),
+  ]);
+});
+
 test('后台账号创建和更新同时携带 Tab 与独立操作权限', async () => {
   const fetchMock = vi.fn().mockImplementation(() =>
     Promise.resolve(

apps/admin-web/src/api/adminApiClient.ts

@@ -1,5 +1,6 @@
 import type {
   AdminAccountListResponse,
+  AdminAgcTemplateLibraryResponse,
   AdminConfirmEditorShowcaseCampaignImageUploadRequest,
   AdminCreateAccountRequest,
   AdminCreateAccountResponse,
@@ -47,6 +48,7 @@ import type {
   AdminTrackingEventListResponse,
   AdminUpdateAccountRequest,
   AdminUpdateAccountResponse,
+  AdminUpdateAgcTemplateRequest,
   AdminUploadedEditorShowcaseCampaignImage,
   AdminUpsertEditorShowcaseCampaignRequest,
   AdminUpsertFeatureGateConfigRequest,
@@ -1176,3 +1178,21 @@ export function saveAgcModelCatalog(
     { token, method: 'PUT', body },
   );
 }
+
+export function getAdminAgcTemplates(token: string, signal?: AbortSignal) {
+  return request<AdminAgcTemplateLibraryResponse>('/admin/api/agc-templates', {
+    token,
+    signal,
+  });
+}
+
+export function updateAdminAgcTemplate(
+  token: string,
+  id: string,
+  body: AdminUpdateAgcTemplateRequest,
+) {
+  return request<AdminAgcTemplateLibraryResponse>(
+    `/admin/api/agc-templates/${encodeURIComponent(id)}`,
+    { token, method: 'PUT', body },
+  );
+}

apps/admin-web/src/api/adminApiTypes.ts

@@ -1033,3 +1033,35 @@ export interface AdminAgcModelCatalog {
   defaultModelId: string;
   models: AdminAgcModel[];
 }
+
+export interface AdminAgcTemplatePayload {
+  id: string;
+  title: string;
+  summary: string;
+  tags: string[];
+  runtime: string;
+  engine: string;
+  engineVersion: string;
+  templateVersion: string;
+  enabled: boolean;
+  coverUrl: string;
+  zipSizeBytes: number;
+}
+
+export interface AdminAgcTemplateLibraryResponse {
+  revision: string;
+  writable: boolean;
+  templates: AdminAgcTemplatePayload[];
+}
+
+export interface AdminUpdateAgcTemplateRequest {
+  expectedRevision: string;
+  title: string;
+  summary: string;
+  tags: string[];
+  enabled: boolean;
+  cover?: {
+    contentType: string;
+    dataBase64: string;
+  };
+}

apps/admin-web/src/app/AdminApp.tsx

@@ -19,6 +19,7 @@ import {
 } from '../auth/adminAuthStore';
 import { AdminAccountsPage } from '../pages/AdminAccountsPage';
 import { AdminAgcModelsPage } from '../pages/AdminAgcModelsPage';
+import { AdminAgcTemplatesPage } from '../pages/AdminAgcTemplatesPage';
 import { AdminDashboardPage } from '../pages/AdminDashboardPage';
 import { AdminDatabaseTablesPage } from '../pages/AdminDatabaseTablesPage';
 import { AdminDebugHttpPage } from '../pages/AdminDebugHttpPage';
@@ -294,6 +295,12 @@ export function AdminApp() {
       {activeRouteId === 'agc-models' ? (
         <AdminAgcModelsPage token={token} onUnauthorized={handleUnauthorized} />
       ) : null}
+      {activeRouteId === 'agc-templates' ? (
+        <AdminAgcTemplatesPage
+          token={token}
+          onUnauthorized={handleUnauthorized}
+        />
+      ) : null}
       {activeRouteId === 'editor-showcase' ? (
         <AdminEditorShowcaseReviewPage
           token={token}

apps/admin-web/src/app/AdminShell.tsx

@@ -53,6 +53,7 @@ const routeIcons = {
   'project-snapshots': FolderArchive,
   accounts: Users,
   'agc-models': ListChecks,
+  'agc-templates': Images,
 } satisfies Record<AdminRouteId, typeof LayoutDashboard>;
 
 export function AdminShell({

apps/admin-web/src/app/adminRoutes.test.ts

@@ -147,3 +147,30 @@ test('项目工程入口对 owner 与已授权 member 开放且可分配权限',
     }),
   ).not.toContainEqual(route);
 });
+
+test('模板管理只对 owner 或具有 agc-templates 权限的 member 可见', () => {
+  expect(adminRoutes).toContainEqual({
+    id: 'agc-templates',
+    label: '模板管理',
+    hash: '#agc-templates',
+  });
+  expect(resolveAdminRoute('#agc-templates')).toBe('agc-templates');
+  expect(routeHash('agc-templates')).toBe('#agc-templates');
+  expect(
+    getAccessibleAdminRoutes({ accountRole: 'owner', tabPermissions: [] }).some(
+      (route) => route.id === 'agc-templates',
+    ),
+  ).toBe(true);
+  expect(
+    getAccessibleAdminRoutes({
+      accountRole: 'member',
+      tabPermissions: ['agc-templates'],
+    }).map((route) => route.id),
+  ).toEqual(['agc-templates']);
+  expect(
+    getAccessibleAdminRoutes({
+      accountRole: 'member',
+      tabPermissions: ['editor-assets'],
+    }).some((route) => route.id === 'agc-templates'),
+  ).toBe(false);
+});

apps/admin-web/src/app/adminRoutes.ts

@@ -18,6 +18,7 @@ export type AdminRouteId =
   | 'editor-assets'
   | 'project-snapshots'
   | 'agc-models'
+  | 'agc-templates'
   | 'accounts';
 
 export type AdminTabPermission = Exclude<
@@ -53,6 +54,7 @@ export const adminRoutes: AdminRouteDefinition[] = [
     hash: '#editor-generation-pricing',
   },
   { id: 'agc-models', label: 'AGC 模型', hash: '#agc-models', ownerOnly: true },
+  { id: 'agc-templates', label: '模板管理', hash: '#agc-templates' },
   { id: 'editor-showcase', label: '精选审核', hash: '#editor-showcase' },
   { id: 'editor-assets', label: '素材查询', hash: '#editor-assets' },
   { id: 'project-snapshots', label: '项目工程', hash: '#project-snapshots' },

apps/admin-web/src/main.tsx

@@ -1,3 +1,4 @@
+import '@genarrative/shared/styles.css';
 import './styles/admin.css';
 
 import { StrictMode } from 'react';

apps/admin-web/src/pages/AdminAgcTemplatesPage.test.tsx

@@ -0,0 +1,498 @@
+// @vitest-environment jsdom
+import {
+  act,
+  cleanup,
+  fireEvent,
+  render,
+  screen,
+  waitFor,
+  within,
+} from '@testing-library/react';
+import { afterEach, beforeEach, expect, test, vi } from 'vitest';
+
+import {
+  AdminApiError,
+  getAdminAgcTemplates,
+  updateAdminAgcTemplate,
+} from '../api/adminApiClient';
+import type {
+  AdminAgcTemplateLibraryResponse,
+  AdminAgcTemplatePayload,
+} from '../api/adminApiTypes';
+import { AdminAgcTemplatesPage } from './AdminAgcTemplatesPage';
+
+vi.mock('../api/adminApiClient', async (importOriginal) => ({
+  ...(await importOriginal<typeof import('../api/adminApiClient')>()),
+  getAdminAgcTemplates: vi.fn(),
+  updateAdminAgcTemplate: vi.fn(),
+}));
+
+const template: AdminAgcTemplatePayload = {
+  id: 'cocos-empty-2d',
+  title: '空白 2D',
+  summary: '二维项目',
+  tags: ['2D', '入门'],
+  runtime: 'cocos',
+  engine: 'Cocos Creator',
+  engineVersion: '3.8.8',
+  templateVersion: '1',
+  enabled: true,
+  coverUrl: 'https://example.test/cover.png',
+  zipSizeBytes: 2048,
+};
+const library: AdminAgcTemplateLibraryResponse = {
+  revision: 'rev-1',
+  writable: true,
+  templates: [
+    template,
+    {
+      ...template,
+      id: 'godot-starter',
+      title: 'Godot 起步',
+      runtime: 'godot',
+      engine: 'Godot',
+      engineVersion: '4',
+      tags: ['3D'],
+      enabled: false,
+    },
+  ],
+};
+
+beforeEach(() => {
+  vi.mocked(getAdminAgcTemplates)
+    .mockReset()
+    .mockImplementation(async () => structuredClone(library));
+  vi.mocked(updateAdminAgcTemplate)
+    .mockReset()
+    .mockImplementation(async (_token, id, update) => ({
+      ...structuredClone(library),
+      revision: 'rev-2',
+      templates: library.templates.map((entry) =>
+        entry.id === id
+          ? {
+              ...entry,
+              title: update.title,
+              summary: update.summary,
+              tags: update.tags,
+              enabled: update.enabled,
+            }
+          : entry,
+      ),
+    }));
+  vi.stubGlobal(
+    'URL',
+    Object.assign(class extends URL {}, {
+      createObjectURL: vi.fn(() => 'blob:template-cover'),
+      revokeObjectURL: vi.fn(),
+    }),
+  );
+});
+
+afterEach(() => {
+  cleanup();
+  vi.unstubAllGlobals();
+  vi.restoreAllMocks();
+});
+
+async function openEditor() {
+  fireEvent.click(await screen.findByRole('button', { name: '编辑 空白 2D' }));
+  return screen.getByRole('dialog', { name: '编辑模板' });
+}
+
+async function confirmWrite() {
+  const confirmation = await screen.findByRole('dialog', { name: '确认操作' });
+  fireEvent.click(within(confirmation).getByRole('button', { name: '确认' }));
+}
+
+function deferred<T>() {
+  let resolve!: (value: T) => void;
+  let reject!: (reason: unknown) => void;
+  const promise = new Promise<T>((next, fail) => {
+    resolve = next;
+    reject = fail;
+  });
+  return { promise, resolve, reject };
+}
+
+test('按名称、ID、标签、运行时和上下架状态筛选，展示版本与封面', async () => {
+  render(<AdminAgcTemplatesPage token="token" onUnauthorized={vi.fn()} />);
+  await screen.findByText('空白 2D');
+  expect(screen.getByText('Cocos Creator 3.8.8')).not.toBeNull();
+  expect(screen.getAllByText('模板 1')).toHaveLength(2);
+  expect(screen.getAllByText('2.0 KiB')).toHaveLength(2);
+  expect(
+    screen.getByRole('img', { name: '空白 2D封面' }).getAttribute('src'),
+  ).toBe(template.coverUrl);
+  for (const value of ['空白', 'cocos-empty-2d', '入门']) {
+    fireEvent.change(screen.getByLabelText('搜索模板'), { target: { value } });
+    expect(screen.getByText('空白 2D')).not.toBeNull();
+    expect(screen.queryByText('Godot 起步')).toBeNull();
+  }
+  fireEvent.change(screen.getByLabelText('搜索模板'), {
+    target: { value: '' },
+  });
+  fireEvent.change(screen.getByLabelText('运行时'), {
+    target: { value: 'godot' },
+  });
+  expect(screen.queryByText('空白 2D')).toBeNull();
+  fireEvent.change(screen.getByLabelText('上架状态'), {
+    target: { value: 'enabled' },
+  });
+  expect(screen.getByText('没有符合筛选条件的模板')).not.toBeNull();
+});
+
+test('独立弹窗保存经写确认，只提交展示字段和冻结 revision', async () => {
+  render(<AdminAgcTemplatesPage token="token" onUnauthorized={vi.fn()} />);
+  const editor = await openEditor();
+  expect(editor.closest('.admin-agc-templates')).toBeNull();
+  fireEvent.change(within(editor).getByLabelText('名称'), {
+    target: { value: ' 新名称 ' },
+  });
+  fireEvent.change(within(editor).getByLabelText('简介'), {
+    target: { value: '新简介' },
+  });
+  fireEvent.change(within(editor).getByLabelText('标签'), {
+    target: { value: '2D, 新手，2D' },
+  });
+  fireEvent.click(within(editor).getByRole('button', { name: '保存' }));
+  expect(updateAdminAgcTemplate).not.toHaveBeenCalled();
+  await confirmWrite();
+  await waitFor(() =>
+    expect(updateAdminAgcTemplate).toHaveBeenCalledWith('token', template.id, {
+      expectedRevision: 'rev-1',
+      title: '新名称',
+      summary: '新简介',
+      tags: ['2D', '新手'],
+      enabled: true,
+    }),
+  );
+  await waitFor(() =>
+    expect(screen.queryByRole('dialog', { name: '编辑模板' })).toBeNull(),
+  );
+  expect(screen.getByText('新名称')).not.toBeNull();
+  expect(screen.getByText('已保存')).not.toBeNull();
+});
+
+test('上下架复用确认且只用服务端结果更新列表', async () => {
+  render(<AdminAgcTemplatesPage token="token" onUnauthorized={vi.fn()} />);
+  fireEvent.click(await screen.findByRole('button', { name: '下架 空白 2D' }));
+  await confirmWrite();
+  await waitFor(() =>
+    expect(updateAdminAgcTemplate).toHaveBeenCalledWith('token', template.id, {
+      expectedRevision: 'rev-1',
+      title: template.title,
+      summary: template.summary,
+      tags: template.tags,
+      enabled: false,
+    }),
+  );
+  expect(
+    await screen.findByRole('button', { name: '上架 空白 2D' }),
+  ).not.toBeNull();
+});
+
+test('只读模式禁用字段、保存与上下架', async () => {
+  vi.mocked(getAdminAgcTemplates).mockResolvedValue({
+    ...library,
+    writable: false,
+  });
+  render(<AdminAgcTemplatesPage token="token" onUnauthorized={vi.fn()} />);
+  expect(
+    await screen.findByText('当前为只读模式，无法保存或上下架'),
+  ).not.toBeNull();
+  expect(
+    (screen.getByRole('button', { name: '下架 空白 2D' }) as HTMLButtonElement)
+      .disabled,
+  ).toBe(true);
+  const editor = await openEditor();
+  expect(
+    (within(editor).getByLabelText('名称') as HTMLInputElement).disabled,
+  ).toBe(true);
+  expect(
+    (within(editor).getByRole('button', { name: '保存' }) as HTMLButtonElement)
+      .disabled,
+  ).toBe(true);
+  expect(updateAdminAgcTemplate).not.toHaveBeenCalled();
+});
+
+test('409 保留草稿，显式刷新后重新编辑才采用新 revision，不自动重试', async () => {
+  vi.mocked(updateAdminAgcTemplate).mockRejectedValueOnce(
+    new AdminApiError({ message: '模板库已被修改', status: 409 }),
+  );
+  render(<AdminAgcTemplatesPage token="token" onUnauthorized={vi.fn()} />);
+  let editor = await openEditor();
+  fireEvent.change(within(editor).getByLabelText('名称'), {
+    target: { value: '未保存草稿' },
+  });
+  fireEvent.click(within(editor).getByRole('button', { name: '保存' }));
+  await confirmWrite();
+  await screen.findByText('模板库已被修改');
+  expect((screen.getByLabelText('名称') as HTMLInputElement).value).toBe(
+    '未保存草稿',
+  );
+  expect(updateAdminAgcTemplate).toHaveBeenCalledTimes(1);
+  expect(
+    (screen.getByRole('button', { name: '保存' }) as HTMLButtonElement)
+      .disabled,
+  ).toBe(true);
+  vi.mocked(getAdminAgcTemplates).mockResolvedValueOnce({
+    ...library,
+    revision: 'rev-3',
+    templates: [{ ...template, title: '最新名称' }],
+  });
+  fireEvent.click(screen.getByRole('button', { name: '刷新后重新编辑' }));
+  await screen.findByDisplayValue('最新名称');
+  editor = screen.getByRole('dialog', { name: '编辑模板' });
+  fireEvent.change(within(editor).getByLabelText('名称'), {
+    target: { value: '重新编辑' },
+  });
+  fireEvent.click(within(editor).getByRole('button', { name: '保存' }));
+  await confirmWrite();
+  await waitFor(() =>
+    expect(updateAdminAgcTemplate).toHaveBeenLastCalledWith(
+      'token',
+      template.id,
+      expect.objectContaining({ expectedRevision: 'rev-3', title: '重新编辑' }),
+    ),
+  );
+});
+
+test('防止重复确认和保存中重复提交', async () => {
+  const pending = deferred<AdminAgcTemplateLibraryResponse>();
+  vi.mocked(updateAdminAgcTemplate).mockReturnValue(pending.promise);
+  render(<AdminAgcTemplatesPage token="token" onUnauthorized={vi.fn()} />);
+  const editor = await openEditor();
+  const form = within(editor).getByLabelText('名称').closest('form')!;
+  fireEvent.submit(form);
+  fireEvent.submit(form);
+  expect(screen.getAllByRole('dialog', { name: '确认操作' })).toHaveLength(1);
+  await confirmWrite();
+  await waitFor(() => expect(updateAdminAgcTemplate).toHaveBeenCalledTimes(1));
+  fireEvent.submit(form);
+  expect(updateAdminAgcTemplate).toHaveBeenCalledTimes(1);
+  await act(async () => pending.resolve(library));
+});
+
+test.each([409, 503])(
+  '滚到表单底部后出现 HTTP %s 写入错误，聚焦并仅滚动弹窗到提示区',
+  async (status) => {
+    vi.mocked(updateAdminAgcTemplate).mockRejectedValueOnce(
+      new AdminApiError({ message: '本次保存失败', status }),
+    );
+    render(
+      <div data-testid="background-page">
+        <AdminAgcTemplatesPage token="token" onUnauthorized={vi.fn()} />
+      </div>,
+    );
+    const background = screen.getByTestId('background-page');
+    background.scrollTop = 240;
+    const editor = await openEditor();
+    const viewport = editor.querySelector<HTMLElement>(
+      '.genarrative-ui-modal__body',
+    )!;
+    viewport.scrollTop = 400;
+    const bounds = (top: number, bottom: number) =>
+      ({
+        top,
+        bottom,
+        height: bottom - top,
+        left: 0,
+        right: 300,
+        width: 300,
+        x: 0,
+        y: top,
+        toJSON: () => ({}),
+      }) as DOMRect;
+    vi.spyOn(viewport, 'getBoundingClientRect').mockReturnValue(
+      bounds(100, 450),
+    );
+    const originalBounds = HTMLElement.prototype.getBoundingClientRect;
+    vi.spyOn(HTMLElement.prototype, 'getBoundingClientRect').mockImplementation(
+      function (this: HTMLElement) {
+        return this.classList.contains('admin-agc-template-feedback')
+          ? bounds(-280, -120)
+          : originalBounds.call(this);
+      },
+    );
+    const windowScroll = vi
+      .spyOn(window, 'scrollTo')
+      .mockImplementation(() => {});
+    const focus = vi.spyOn(HTMLElement.prototype, 'focus');
+    fireEvent.click(within(editor).getByRole('button', { name: '保存' }));
+    await confirmWrite();
+    const message = await screen.findByRole('alert');
+    const feedback = message.parentElement!;
+    expect(document.activeElement).toBe(feedback);
+    expect(feedback.tabIndex).toBe(-1);
+    expect(focus).toHaveBeenCalledWith({ preventScroll: true });
+    expect(viewport.scrollTop).toBe(20);
+    expect(background.scrollTop).toBe(240);
+    expect(windowScroll).not.toHaveBeenCalled();
+    if (status === 409) {
+      expect(
+        within(feedback).getByRole('button', { name: '刷新后重新编辑' }),
+      ).not.toBeNull();
+    }
+  },
+);
+
+test('token 切换后忽略旧列表和未确认写操作', async () => {
+  const pending = deferred<AdminAgcTemplateLibraryResponse>();
+  vi.mocked(getAdminAgcTemplates).mockReturnValueOnce(pending.promise);
+  const props = { onUnauthorized: vi.fn() };
+  const view = render(<AdminAgcTemplatesPage token="old" {...props} />);
+  view.rerender(<AdminAgcTemplatesPage token="new" {...props} />);
+  await screen.findByText('空白 2D');
+  await act(async () =>
+    pending.resolve({
+      ...library,
+      templates: [{ ...template, title: '过期列表' }],
+    }),
+  );
+  expect(screen.queryByText('过期列表')).toBeNull();
+  const editor = await openEditor();
+  fireEvent.click(within(editor).getByRole('button', { name: '保存' }));
+  view.rerender(<AdminAgcTemplatesPage token="third" {...props} />);
+  await screen.findByText('空白 2D');
+  expect(screen.queryByRole('dialog')).toBeNull();
+  expect(updateAdminAgcTemplate).not.toHaveBeenCalled();
+});
+
+test.each(['success', 'unauthorized'])(
+  'token 切换后忽略旧保存 %s，不污染新会话',
+  async (result) => {
+    const pending = deferred<AdminAgcTemplateLibraryResponse>();
+    vi.mocked(updateAdminAgcTemplate).mockReturnValueOnce(pending.promise);
+    const onUnauthorized = vi.fn();
+    const view = render(
+      <AdminAgcTemplatesPage token="old" onUnauthorized={onUnauthorized} />,
+    );
+    const editor = await openEditor();
+    fireEvent.click(within(editor).getByRole('button', { name: '保存' }));
+    await confirmWrite();
+    await waitFor(() =>
+      expect(updateAdminAgcTemplate).toHaveBeenCalledTimes(1),
+    );
+    view.rerender(
+      <AdminAgcTemplatesPage token="new" onUnauthorized={onUnauthorized} />,
+    );
+    await screen.findByText('空白 2D');
+    await act(async () => {
+      if (result === 'success') {
+        pending.resolve({
+          ...library,
+          templates: [{ ...template, title: '旧保存结果' }],
+        });
+      } else {
+        pending.reject(
+          new AdminApiError({ status: 401, message: '旧会话失效' }),
+        );
+      }
+    });
+    expect(onUnauthorized).not.toHaveBeenCalled();
+    expect(screen.queryByText('旧会话失效')).toBeNull();
+    expect(screen.queryByText('旧保存结果')).toBeNull();
+    expect(screen.queryByText('已保存')).toBeNull();
+  },
+);
+
+test('封面在草稿中转 base64，保存携带，取消释放预览 URL 且不串到下一条', async () => {
+  render(<AdminAgcTemplatesPage token="token" onUnauthorized={vi.fn()} />);
+  let editor = await openEditor();
+  const file = new File(['cover'], 'cover.png', { type: 'image/png' });
+  fireEvent.change(within(editor).getByLabelText('更换封面'), {
+    target: { files: [file] },
+  });
+  await waitFor(() => expect(screen.queryByText('正在读取封面')).toBeNull());
+  fireEvent.click(within(editor).getByRole('button', { name: '保存' }));
+  await confirmWrite();
+  await waitFor(() =>
+    expect(updateAdminAgcTemplate).toHaveBeenCalledWith(
+      'token',
+      template.id,
+      expect.objectContaining({
+        cover: { contentType: 'image/png', dataBase64: 'Y292ZXI=' },
+      }),
+    ),
+  );
+  await waitFor(() =>
+    expect(URL.revokeObjectURL).toHaveBeenCalledWith('blob:template-cover'),
+  );
+  editor = await openEditor();
+  fireEvent.change(within(editor).getByLabelText('更换封面'), {
+    target: { files: [file] },
+  });
+  fireEvent.click(within(editor).getByRole('button', { name: '取消' }));
+  fireEvent.click(screen.getByRole('button', { name: '编辑 Godot 起步' }));
+  expect(
+    screen.getByRole('img', { name: '模板封面预览' }).getAttribute('src'),
+  ).toBe(template.coverUrl);
+  expect(URL.revokeObjectURL).toHaveBeenCalledTimes(2);
+});
+
+test.each([
+  ['bad.svg', 'image/svg+xml', 1, '封面仅支持 PNG、JPEG 或 WebP'],
+  [
+    'large.png',
+    'image/png',
+    5 * 1024 * 1024 + 1,
+    '封面文件须大于 0 且不超过 5 MiB',
+  ],
+])('拒绝无效封面 %s，不上传', async (name, type, size, message) => {
+  render(<AdminAgcTemplatesPage token="token" onUnauthorized={vi.fn()} />);
+  const editor = await openEditor();
+  const file = new File(['x'], name, { type });
+  Object.defineProperty(file, 'size', { value: size });
+  fireEvent.change(within(editor).getByLabelText('更换封面'), {
+    target: { files: [file] },
+  });
+  expect(screen.getByText(message)).not.toBeNull();
+  expect(
+    (screen.getByRole('button', { name: '保存' }) as HTMLButtonElement)
+      .disabled,
+  ).toBe(true);
+  expect(URL.createObjectURL).not.toHaveBeenCalled();
+  expect(updateAdminAgcTemplate).not.toHaveBeenCalled();
+});
+
+test('名称和标签校验失败时不进入写确认', async () => {
+  render(<AdminAgcTemplatesPage token="token" onUnauthorized={vi.fn()} />);
+  const editor = await openEditor();
+  fireEvent.change(within(editor).getByLabelText('名称'), {
+    target: { value: ' ' },
+  });
+  fireEvent.click(within(editor).getByRole('button', { name: '保存' }));
+  expect(screen.getByText('名称须为 1–80 个字符')).not.toBeNull();
+  fireEvent.change(within(editor).getByLabelText('名称'), {
+    target: { value: '有效名称' },
+  });
+  fireEvent.change(within(editor).getByLabelText('标签'), {
+    target: {
+      value: Array.from({ length: 17 }, (_, index) => `标签${index}`).join(','),
+    },
+  });
+  fireEvent.click(within(editor).getByRole('button', { name: '保存' }));
+  expect(
+    screen.getByText('最多 16 个标签，每个标签不超过 32 个字符'),
+  ).not.toBeNull();
+  expect(updateAdminAgcTemplate).not.toHaveBeenCalled();
+});
+
+test('读取失败显示真实错误，401 交给会话处理且不显示空库', async () => {
+  const onUnauthorized = vi.fn();
+  vi.mocked(getAdminAgcTemplates).mockRejectedValueOnce(
+    new AdminApiError({ status: 503, message: '模板服务不可用' }),
+  );
+  render(
+    <AdminAgcTemplatesPage token="token" onUnauthorized={onUnauthorized} />,
+  );
+  await screen.findByText('模板服务不可用');
+  expect(screen.queryByText('暂无模板')).toBeNull();
+  vi.mocked(getAdminAgcTemplates).mockRejectedValueOnce(
+    new AdminApiError({ status: 401, message: '会话失效' }),
+  );
+  fireEvent.click(screen.getByRole('button', { name: '刷新' }));
+  await waitFor(() =>
+    expect(onUnauthorized).toHaveBeenCalledWith('登录状态已失效'),
+  );
+});

apps/admin-web/src/styles/admin.css

@@ -13,6 +13,87 @@
   text-rendering: optimizeLegibility;
 }
 
+.admin-agc-templates {
+  min-width: 0;
+}
+
+.admin-agc-template-filters {
+  display: grid;
+  grid-template-columns: minmax(180px, 1fr) repeat(2, minmax(130px, 190px));
+  gap: 14px;
+}
+
+.admin-agc-template-table {
+  min-width: 850px;
+}
+
+.admin-agc-template-table td:nth-child(2) {
+  min-width: 230px;
+  max-width: 380px;
+}
+
+.admin-agc-template-cover {
+  display: block;
+  width: 88px;
+  height: 62px;
+  border-radius: 8px;
+  object-fit: cover;
+  background: #f8efe7;
+}
+
+.admin-agc-template-summary {
+  display: -webkit-box;
+  overflow: hidden;
+  margin: 8px 0;
+  color: #866954;
+  -webkit-line-clamp: 2;
+  -webkit-box-orient: vertical;
+}
+
+.admin-agc-template-tags,
+.admin-agc-template-actions {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 8px;
+}
+
+.admin-agc-template-tags span {
+  padding: 3px 7px;
+  border-radius: 5px;
+  background: #f8efe7;
+  font-size: 12px;
+}
+
+.admin-agc-template-dialog {
+  border-radius: 10px;
+}
+
+.admin-agc-template-editor,
+.admin-agc-template-conflict {
+  display: grid;
+  gap: 14px;
+}
+
+.admin-agc-template-cover-preview {
+  display: block;
+  width: min(100%, 300px);
+  max-height: 180px;
+  border-radius: 8px;
+  object-fit: contain;
+  background: #f8efe7;
+}
+
+.admin-agc-template-dialog .admin-confirm-backdrop {
+  z-index: 1100;
+}
+
+@media (max-width: 680px) {
+  .admin-agc-template-filters {
+    grid-template-columns: minmax(0, 1fr);
+  }
+}
+
 * {
   box-sizing: border-box;
 }