增强 Gitea CI 网络稳定性

为所有 npm ci 增加整命令级有界重试。

补齐 AI 游戏创作 npm 与 Cargo 依赖缓存闭合验证。

更新可信 CI 镜像、缓存漂移告警和 Runner 运维文档。

记录 Actions Gateway CONNECT 断连崩溃的处理与验证边界。

scripts/check-gitea-ci-job-image.sh

@@ -36,6 +36,7 @@ verify_cache_lock() {
   fi
   if [[ "${GENARRATIVE_GITEA_CI_CHECK_RUNTIME:-0}" == '1' ]]; then
     printf '%s_cache_lock=partial\n' "${cache_name}"
+    printf '::warning title=CI dependency cache is partial::%s lock differs from the prebuilt image; refresh the trusted CI image after this lock change lands.\n' "${cache_name}"
     return
   fi
   echo "${cache_name} cache lock does not match the verification checkout." >&2
@@ -43,22 +44,34 @@ verify_cache_lock() {
 }
 
 npm_lock_path="${repo_root}/package-lock.json"
+agc_npm_lock_path="${repo_root}/apps/ai-game-creator-shell/package-lock.json"
 server_rust_lock_path="${repo_root}/server-rs/Cargo.lock"
 desktop_rust_lock_path="${repo_root}/apps/desktop-shell/src-tauri/Cargo.lock"
+agc_rust_lock_path="${repo_root}/apps/ai-game-creator-shell/src-tauri/Cargo.lock"
 if [[ ! -f "${npm_lock_path}" ]]; then
   npm_lock_path='/usr/local/share/genarrative-ci/npm/package-lock.json'
 fi
+if [[ ! -f "${agc_npm_lock_path}" ]]; then
+  agc_npm_lock_path='/usr/local/share/genarrative-ci/agc-npm/package-lock.json'
+fi
 if [[ ! -f "${server_rust_lock_path}" ]]; then
   server_rust_lock_path='/usr/local/share/genarrative-ci/locks/server-rs.Cargo.lock'
 fi
 if [[ ! -f "${desktop_rust_lock_path}" ]]; then
   desktop_rust_lock_path='/usr/local/share/genarrative-ci/locks/desktop-shell.Cargo.lock'
 fi
+if [[ ! -f "${agc_rust_lock_path}" ]]; then
+  agc_rust_lock_path='/usr/local/share/genarrative-ci/locks/ai-game-creator-shell.Cargo.lock'
+fi
 
 verify_cache_lock \
   npm \
   "${GENARRATIVE_GITEA_CI_NPM_LOCK_SHA256:-}" \
   "${npm_lock_path}"
+verify_cache_lock \
+  agc_npm \
+  "${GENARRATIVE_GITEA_CI_AGC_NPM_LOCK_SHA256:-}" \
+  "${agc_npm_lock_path}"
 verify_cache_lock \
   server_rust \
   "${GENARRATIVE_GITEA_CI_SERVER_RUST_LOCK_SHA256:-}" \
@@ -67,6 +80,10 @@ verify_cache_lock \
   desktop_rust \
   "${GENARRATIVE_GITEA_CI_DESKTOP_RUST_LOCK_SHA256:-}" \
   "${desktop_rust_lock_path}"
+verify_cache_lock \
+  agc_rust \
+  "${GENARRATIVE_GITEA_CI_AGC_RUST_LOCK_SHA256:-}" \
+  "${agc_rust_lock_path}"
 
 for command_name in \
   bwrap \

scripts/ci-npm-ci-with-retry.sh

@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+max_attempts="${GENARRATIVE_CI_NPM_CI_ATTEMPTS:-3}"
+base_delay_seconds="${GENARRATIVE_CI_NPM_CI_RETRY_DELAY_SECONDS:-5}"
+
+if [[ ! "${max_attempts}" =~ ^[1-9][0-9]*$ ]]; then
+  echo 'GENARRATIVE_CI_NPM_CI_ATTEMPTS must be a positive integer.' >&2
+  exit 2
+fi
+if [[ ! "${base_delay_seconds}" =~ ^[0-9]+$ ]]; then
+  echo 'GENARRATIVE_CI_NPM_CI_RETRY_DELAY_SECONDS must be a non-negative integer.' >&2
+  exit 2
+fi
+
+for attempt in $(seq 1 "${max_attempts}"); do
+  if npm ci "$@"; then
+    exit 0
+  fi
+  if [[ "${attempt}" -eq "${max_attempts}" ]]; then
+    echo "npm ci failed after ${max_attempts} attempts." >&2
+    exit 1
+  fi
+  sleep "$((attempt * base_delay_seconds))"
+done

scripts/gitea-ci-job-image.sh

@@ -4,7 +4,7 @@ set -euo pipefail
 
 repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd -P)"
 dockerfile_context_path="deploy/container/gitea-ci-job.Dockerfile"
-image_tag="${GENARRATIVE_GITEA_CI_IMAGE_TAG:-genarrative/gitea-project-ci:20260723.1}"
+image_tag="${GENARRATIVE_GITEA_CI_IMAGE_TAG:-genarrative/gitea-project-ci:20260807.1}"
 runner_container="${GENARRATIVE_GITEA_RUNNER_CONTAINER:-gitea-runner}"
 
 write_build_context_file_list() {
@@ -14,6 +14,10 @@ write_build_context_file_list() {
     deploy/container/gitea-ci-checkout.sh \
     package.json \
     package-lock.json \
+    apps/ai-game-creator-shell/package.json \
+    apps/ai-game-creator-shell/package-lock.json \
+    apps/ai-game-creator-shell/src-tauri/Cargo.toml \
+    apps/ai-game-creator-shell/src-tauri/Cargo.lock \
     server-rs/Cargo.toml \
     server-rs/Cargo.lock \
     apps/desktop-shell/src-tauri/Cargo.toml \
@@ -61,6 +65,10 @@ case "${command_name}" in
           deploy/container/gitea-ci-checkout.sh \
           package.json \
           package-lock.json \
+          apps/ai-game-creator-shell/package.json \
+          apps/ai-game-creator-shell/package-lock.json \
+          apps/ai-game-creator-shell/src-tauri/Cargo.toml \
+          apps/ai-game-creator-shell/src-tauri/Cargo.lock \
           server-rs/Cargo.toml \
           server-rs/Cargo.lock \
           apps/desktop-shell/src-tauri/Cargo.toml \
@@ -74,10 +82,14 @@ case "${command_name}" in
     )"
     npm_lock_sha256="$(sha256sum "${repo_root}/package-lock.json")"
     npm_lock_sha256="${npm_lock_sha256%% *}"
+    agc_npm_lock_sha256="$(sha256sum "${repo_root}/apps/ai-game-creator-shell/package-lock.json")"
+    agc_npm_lock_sha256="${agc_npm_lock_sha256%% *}"
     server_rust_lock_sha256="$(sha256sum "${repo_root}/server-rs/Cargo.lock")"
     server_rust_lock_sha256="${server_rust_lock_sha256%% *}"
     desktop_rust_lock_sha256="$(sha256sum "${repo_root}/apps/desktop-shell/src-tauri/Cargo.lock")"
     desktop_rust_lock_sha256="${desktop_rust_lock_sha256%% *}"
+    agc_rust_lock_sha256="$(sha256sum "${repo_root}/apps/ai-game-creator-shell/src-tauri/Cargo.lock")"
+    agc_rust_lock_sha256="${agc_rust_lock_sha256%% *}"
     (
       cd "${repo_root}"
       write_build_context_file_list \
@@ -86,8 +98,10 @@ case "${command_name}" in
           --pull=false \
           --build-arg "IMAGE_REVISION=${image_revision}" \
           --build-arg "NPM_LOCK_SHA256=${npm_lock_sha256}" \
+          --build-arg "AGC_NPM_LOCK_SHA256=${agc_npm_lock_sha256}" \
           --build-arg "SERVER_RUST_LOCK_SHA256=${server_rust_lock_sha256}" \
           --build-arg "DESKTOP_RUST_LOCK_SHA256=${desktop_rust_lock_sha256}" \
+          --build-arg "AGC_RUST_LOCK_SHA256=${agc_rust_lock_sha256}" \
           --file "${dockerfile_context_path}" \
           --tag "${image_tag}" \
           -

scripts/project-ci-workflow.test.ts

@@ -7,6 +7,61 @@ const workflow = readFileSync(
   resolve(process.cwd(), '.gitea/workflows/project-ci.yml'),
   'utf8',
 );
+const imageBuildScript = readFileSync(
+  resolve(process.cwd(), 'scripts/gitea-ci-job-image.sh'),
+  'utf8',
+);
+const imageCheckScript = readFileSync(
+  resolve(process.cwd(), 'scripts/check-gitea-ci-job-image.sh'),
+  'utf8',
+);
+const npmCiRetryScript = readFileSync(
+  resolve(process.cwd(), 'scripts/ci-npm-ci-with-retry.sh'),
+  'utf8',
+);
+const imageDockerfile = readFileSync(
+  resolve(process.cwd(), 'deploy/container/gitea-ci-job.Dockerfile'),
+  'utf8',
+);
+const imageDockerignore = readFileSync(
+  resolve(
+    process.cwd(),
+    'deploy/container/gitea-ci-job.Dockerfile.dockerignore',
+  ),
+  'utf8',
+);
+
+const jobNames = [
+  'repository-checks',
+  'frontend-tests',
+  'backend-tests',
+  'native-shell-tests',
+] as const;
+
+function jobSection(jobName: (typeof jobNames)[number]) {
+  const jobStart = workflow.indexOf(`  ${jobName}:`);
+  expect(jobStart).toBeGreaterThanOrEqual(0);
+
+  const nextJobOffset = workflow
+    .slice(jobStart + 1)
+    .search(/^  [a-z][a-z0-9-]+:$/m);
+  return workflow.slice(
+    jobStart,
+    nextJobOffset < 0 ? undefined : jobStart + 1 + nextJobOffset,
+  );
+}
+
+function stepSection(jobName: (typeof jobNames)[number], stepName: string) {
+  const job = jobSection(jobName);
+  const stepStart = job.indexOf(`      - name: ${stepName}`);
+  expect(stepStart).toBeGreaterThanOrEqual(0);
+
+  const nextStepOffset = job.slice(stepStart + 1).search(/^      - name: /m);
+  return job.slice(
+    stepStart,
+    nextStepOffset < 0 ? undefined : stepStart + 1 + nextStepOffset,
+  );
+}
 
 function backendStepIndex(stepName: string) {
   const backendJobStart = workflow.indexOf('  backend-tests:');
@@ -20,6 +75,122 @@ function backendStepIndex(stepName: string) {
 }
 
 describe('project CI workflow', () => {
+  it('keeps every job on the isolated preinstalled CI image boundary', () => {
+    expect(workflow.match(/^    runs-on: genarrative-ci$/gm)).toHaveLength(4);
+    expect(workflow).not.toContain('actions/checkout');
+    expect(workflow).not.toContain('actions/setup-node');
+    expect(workflow).not.toMatch(/^\s+run: .*\b(?:apt|rustup)\b/m);
+
+    for (const jobName of jobNames) {
+      const job = jobSection(jobName);
+      const checkout = job.indexOf('genarrative-gitea-checkout');
+      const validateImage = job.indexOf(
+        'GENARRATIVE_GITEA_CI_CHECK_RUNTIME=1 bash scripts/check-gitea-ci-job-image.sh',
+      );
+      const installDependencies = job.indexOf(
+        '- name: Install npm dependencies',
+      );
+
+      expect(checkout).toBeGreaterThanOrEqual(0);
+      expect(validateImage).toBeGreaterThan(checkout);
+      expect(installDependencies).toBeGreaterThan(validateImage);
+    }
+
+    expect(imageDockerfile).toMatch(
+      /^ARG RUST_IMAGE=[^\s]+@sha256:[a-f0-9]{64}$/m,
+    );
+    expect(imageDockerfile).toMatch(
+      /^ARG RUNNER_IMAGE=[^\s]+@sha256:[a-f0-9]{64}$/m,
+    );
+  });
+
+  it('retries every root and AI game creator npm clean install as a bounded whole command', () => {
+    for (const jobName of jobNames) {
+      const install = stepSection(jobName, 'Install npm dependencies');
+      expect(install).toContain('bash scripts/ci-npm-ci-with-retry.sh');
+      expect(install).not.toContain('--prefix');
+    }
+
+    for (const jobName of ['frontend-tests', 'native-shell-tests'] as const) {
+      const install = stepSection(
+        jobName,
+        'Install AI game creator dependencies',
+      );
+      expect(install).toContain(
+        'bash scripts/ci-npm-ci-with-retry.sh --prefix apps/ai-game-creator-shell',
+      );
+    }
+
+    expect(npmCiRetryScript).toContain(
+      'max_attempts="${GENARRATIVE_CI_NPM_CI_ATTEMPTS:-3}"',
+    );
+    expect(npmCiRetryScript).toContain(
+      'base_delay_seconds="${GENARRATIVE_CI_NPM_CI_RETRY_DELAY_SECONDS:-5}"',
+    );
+    expect(npmCiRetryScript).toContain(
+      'for attempt in $(seq 1 "${max_attempts}"); do',
+    );
+    expect(npmCiRetryScript).toContain('if npm ci "$@"; then');
+    expect(npmCiRetryScript).toContain(
+      'if [[ "${attempt}" -eq "${max_attempts}" ]]; then',
+    );
+  });
+
+  it('builds and verifies image caches against both AI game creator locks', () => {
+    const npmManifest = 'apps/ai-game-creator-shell/package.json';
+    const npmLock = 'apps/ai-game-creator-shell/package-lock.json';
+    const rustManifest = 'apps/ai-game-creator-shell/src-tauri/Cargo.toml';
+    const rustLock = 'apps/ai-game-creator-shell/src-tauri/Cargo.lock';
+
+    for (const [path, expectedCount] of [
+      [npmManifest, 2],
+      [npmLock, 3],
+      [rustManifest, 2],
+      [rustLock, 3],
+    ] as const) {
+      expect(imageBuildScript.split(path)).toHaveLength(expectedCount + 1);
+      expect(imageDockerignore).toContain(`!${path}`);
+    }
+
+    expect(imageBuildScript).toContain(
+      '--build-arg "AGC_NPM_LOCK_SHA256=${agc_npm_lock_sha256}"',
+    );
+    expect(imageBuildScript).toContain(
+      '--build-arg "AGC_RUST_LOCK_SHA256=${agc_rust_lock_sha256}"',
+    );
+    expect(imageDockerfile).toContain('ARG AGC_NPM_LOCK_SHA256');
+    expect(imageDockerfile).toContain('ARG AGC_RUST_LOCK_SHA256');
+    expect(imageDockerfile).toContain(
+      '--prefix /usr/local/share/genarrative-ci/agc-npm',
+    );
+    expect(
+      imageDockerfile.match(
+        /--manifest-path \/tmp\/genarrative-cargo-cache\/apps\/ai-game-creator-shell\/src-tauri\/Cargo\.toml/g,
+      ),
+    ).toHaveLength(1);
+    expect(imageDockerfile).toContain(
+      'cargo_fetch_with_retry /tmp/genarrative-cargo-cache/apps/ai-game-creator-shell/src-tauri/Cargo.toml',
+    );
+    expect(imageDockerfile).toContain(
+      'GENARRATIVE_GITEA_CI_AGC_NPM_LOCK_SHA256=${AGC_NPM_LOCK_SHA256}',
+    );
+    expect(imageDockerfile).toContain(
+      'GENARRATIVE_GITEA_CI_AGC_RUST_LOCK_SHA256=${AGC_RUST_LOCK_SHA256}',
+    );
+
+    expect(imageCheckScript).toContain(npmLock);
+    expect(imageCheckScript).toContain(rustLock);
+    expect(imageCheckScript).toContain(
+      '${GENARRATIVE_GITEA_CI_AGC_NPM_LOCK_SHA256:-}',
+    );
+    expect(imageCheckScript).toContain(
+      '${GENARRATIVE_GITEA_CI_AGC_RUST_LOCK_SHA256:-}',
+    );
+    expect(imageCheckScript).toContain(
+      '::warning title=CI dependency cache is partial::',
+    );
+  });
+
   it('prepares locked server-rs dependencies before the first Cargo build gate', () => {
     const prepareDependencies = backendStepIndex(
       'Prepare server-rs Rust dependencies',