Release v0.3.21

This reverts commit d38548a1f4.

.github/workflows/release.yml

@@ -3,54 +3,188 @@ name: Release
 on:
   push:
     tags:
-      - 'v*'
+      - "v*"
   workflow_dispatch:
+    inputs:
+      tag:
+        description: Existing release tag to rebuild, for example v0.3.0
+        required: true
+        type: string
 
 permissions:
   contents: write
 
+concurrency:
+  group: release-${{ inputs.tag || github.ref_name }}
+  cancel-in-progress: false
+
 defaults:
   run:
     shell: bash
 
 jobs:
+  prepare:
+    name: Prepare draft release
+    runs-on: ubuntu-22.04
+    outputs:
+      tag: ${{ steps.metadata.outputs.tag }}
+      version: ${{ steps.metadata.outputs.version }}
+      release_body: ${{ steps.metadata.outputs.release_body }}
+      release_id: ${{ steps.release.outputs.release_id }}
+    steps:
+      - name: Checkout release tag
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+        with:
+          fetch-depth: 0
+          ref: ${{ github.event_name == 'workflow_dispatch' && inputs.tag || github.ref }}
+
+      - name: Validate versions and prepare release notes
+        id: metadata
+        env:
+          REQUESTED_TAG: ${{ github.event_name == 'workflow_dispatch' && inputs.tag || github.ref_name }}
+        run: |
+          set -euo pipefail
+          if [[ ! "$REQUESTED_TAG" =~ ^v[0-9]+\.[0-9]+\.[0-9]+([-.][0-9A-Za-z.-]+)?$ ]]; then
+            echo "Invalid release tag: $REQUESTED_TAG" >&2
+            exit 1
+          fi
+          tag_commit=$(git rev-list -n 1 "refs/tags/${REQUESTED_TAG}^{commit}")
+          if [ -z "$tag_commit" ] || [ "$tag_commit" != "$(git rev-parse HEAD)" ]; then
+            echo "The workflow must run from the exact commit referenced by ${REQUESTED_TAG}" >&2
+            exit 1
+          fi
+
+          RELEASE_TAG="$REQUESTED_TAG" python3 - <<'PY'
+          import json
+          import os
+          import re
+          from pathlib import Path
+
+          tag = os.environ["RELEASE_TAG"]
+          expected = tag[1:]
+          root_package = json.loads(Path("package.json").read_text(encoding="utf-8"))
+          desktop_package = json.loads(Path("apps/desktop/package.json").read_text(encoding="utf-8"))
+          tauri_config = json.loads(Path("apps/desktop/src-tauri/tauri.conf.json").read_text(encoding="utf-8"))
+          cargo_text = Path("apps/desktop/src-tauri/Cargo.toml").read_text(encoding="utf-8")
+          cargo_match = re.search(
+              r'^\[package\]\s*$.*?^version\s*=\s*"([^"]+)"',
+              cargo_text,
+              flags=re.S | re.M,
+          )
+          if not cargo_match:
+              raise SystemExit("Unable to read the package version from Cargo.toml")
+
+          versions = {
+              "package.json": root_package.get("version"),
+              "apps/desktop/package.json": desktop_package.get("version"),
+              "apps/desktop/src-tauri/Cargo.toml": cargo_match.group(1),
+              "apps/desktop/src-tauri/tauri.conf.json": tauri_config.get("version"),
+          }
+          mismatches = {path: value for path, value in versions.items() if value != expected}
+          if mismatches:
+              details = ", ".join(f"{path}={value!r}" for path, value in mismatches.items())
+              raise SystemExit(f"Release tag {tag} does not match project versions: {details}")
+
+          changelog = Path("CHANGELOG.md").read_text(encoding="utf-8")
+          match = re.search(
+              rf"^## \[{re.escape(tag)}\].*?\n(.*?)(?=^## \[|\Z)",
+              changelog,
+              flags=re.S | re.M,
+          )
+          body = match.group(1).strip() if match else ""
+          if not body:
+              body = "Codex-X desktop release."
+          Path("release-body.md").write_text(body + "\n", encoding="utf-8")
+          PY
+
+          delimiter="release_body_$(date +%s)_${RANDOM}"
+          {
+            echo "tag=$REQUESTED_TAG"
+            echo "version=${REQUESTED_TAG#v}"
+            echo "release_body<<$delimiter"
+            cat release-body.md
+            echo "$delimiter"
+          } >> "$GITHUB_OUTPUT"
+
+      - name: Create clean draft release
+        id: release
+        env:
+          GH_TOKEN: ${{ github.token }}
+          RELEASE_TAG: ${{ steps.metadata.outputs.tag }}
+        run: |
+          set -euo pipefail
+          if gh release view "$RELEASE_TAG" >/dev/null 2>&1; then
+            is_draft=$(gh release view "$RELEASE_TAG" --json isDraft --jq '.isDraft')
+            if [ "$is_draft" != "true" ]; then
+              echo "${RELEASE_TAG} is already published; use a new version instead of replacing updater assets" >&2
+              exit 1
+            fi
+            gh release edit "$RELEASE_TAG" \
+              --title "Codex-X ${RELEASE_TAG}" \
+              --notes-file release-body.md \
+              --draft
+          else
+            gh release create "$RELEASE_TAG" \
+              --verify-tag \
+              --title "Codex-X ${RELEASE_TAG}" \
+              --notes-file release-body.md \
+              --draft
+          fi
+
+          release_id=""
+          for attempt in {1..10}; do
+            release_id=$(gh release view "$RELEASE_TAG" \
+              --json databaseId \
+              --jq '.databaseId' 2>/dev/null || true)
+            [ -z "$release_id" ] || break
+            sleep 2
+          done
+          if [ -z "$release_id" ]; then
+            echo "Unable to locate draft release for ${RELEASE_TAG}" >&2
+            exit 1
+          fi
+          gh api "/repos/${GITHUB_REPOSITORY}/releases/${release_id}/assets?per_page=100" \
+            --jq '.[].id' | while read -r asset_id; do
+              [ -z "$asset_id" ] || gh api --method DELETE "/repos/${GITHUB_REPOSITORY}/releases/assets/${asset_id}"
+            done
+          echo "release_id=$release_id" >> "$GITHUB_OUTPUT"
+
   build:
     name: Build ${{ matrix.name }}
+    needs: prepare
     runs-on: ${{ matrix.platform }}
+    permissions:
+      contents: write
     strategy:
       fail-fast: false
       matrix:
         include:
           - name: macOS Apple Silicon
             platform: macos-latest
-            args: --bundles dmg
-            artifact: codex-x-macos-arm64
-            paths: |
-              apps/desktop/src-tauri/target/release/bundle/dmg/*.dmg
+            macos: true
+            args: --bundles app,dmg
+            asset_pattern: Codex-X-[version]-macos-apple-silicon[ext]
           - name: macOS Intel
             platform: macos-15-intel
-            args: --bundles dmg
-            artifact: codex-x-macos-x64
-            paths: |
-              apps/desktop/src-tauri/target/release/bundle/dmg/*.dmg
-          - name: Linux
+            macos: true
+            args: --bundles app,dmg
+            asset_pattern: Codex-X-[version]-macos-intel[ext]
+          - name: Linux x64
             platform: ubuntu-22.04
-            args: --bundles deb,rpm
-            artifact: codex-x-linux
-            paths: |
-              apps/desktop/src-tauri/target/release/bundle/deb/*.deb
-              apps/desktop/src-tauri/target/release/bundle/rpm/*.rpm
-          - name: Windows
+            macos: false
+            args: --bundles deb,rpm,appimage
+            asset_pattern: Codex-X-[version]-linux-x64[ext]
+          - name: Windows x64
             platform: windows-latest
-            args: --bundles msi
-            artifact: codex-x-windows
-            paths: |
-              apps/desktop/src-tauri/target/release/bundle/msi/*.msi
-              apps/desktop/src-tauri/Codex-X_*_windows_x64_portable.zip
+            macos: false
+            args: --bundles nsis
+            asset_pattern: Codex-X-[version]-windows-x64[ext]
 
     steps:
-      - name: Checkout
-        uses: actions/checkout@v4
+      - name: Checkout release tag
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+        with:
+          ref: ${{ needs.prepare.outputs.tag }}
 
       - name: Install Linux dependencies
         if: matrix.platform == 'ubuntu-22.04'
@@ -64,144 +198,305 @@ jobs:
             patchelf
 
       - name: Setup pnpm
-        uses: pnpm/action-setup@v4
+        uses: pnpm/action-setup@b906affcce14559ad1aafd4ab0e942779e9f58b1 # v4.3.0
         with:
           version: 10.26.0
 
       - name: Setup Node.js
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
         with:
           node-version: 22
           cache: pnpm
 
       - name: Setup Rust
-        uses: dtolnay/rust-toolchain@stable
+        uses: dtolnay/rust-toolchain@4be7066ada62dd38de10e7b70166bc74ed198c30
+        with:
+          toolchain: stable
 
       - name: Rust cache
-        uses: Swatinem/rust-cache@v2
+        uses: Swatinem/rust-cache@e18b497796c12c097a38f9edb9d0641fb99eee32 # v2
         with:
           workspaces: apps/desktop/src-tauri
 
       - name: Install dependencies
         run: pnpm install --frozen-lockfile
 
-      - name: Build Tauri bundles
-        run: pnpm --dir apps/desktop tauri build ${{ matrix.args }}
-
-      - name: Create Windows portable zip
+      - name: Test Windows filesystem compatibility
         if: matrix.platform == 'windows-latest'
+        run: cargo test --manifest-path apps/desktop/src-tauri/Cargo.toml --lib --locked -- --test-threads=1
+
+      - name: Import Apple signing certificate and notarization key
+        if: matrix.macos
+        env:
+          APPLE_CERTIFICATE: ${{ secrets.APPLE_CERTIFICATE }}
+          APPLE_CERTIFICATE_PASSWORD: ${{ secrets.APPLE_CERTIFICATE_PASSWORD }}
+          APPLE_API_ISSUER: ${{ secrets.APPLE_API_ISSUER }}
+          APPLE_API_KEY: ${{ secrets.APPLE_API_KEY }}
+          APPLE_API_KEY_P8_BASE64: ${{ secrets.APPLE_API_KEY_P8_BASE64 }}
+          APPLE_SIGNING_IDENTITY: ${{ secrets.APPLE_SIGNING_IDENTITY }}
+          APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
+          KEYCHAIN_PASSWORD: ${{ secrets.KEYCHAIN_PASSWORD }}
         run: |
           set -euo pipefail
-          version=$(node -p "require('./apps/desktop/package.json').version")
-          portable_dir="apps/desktop/src-tauri/portable/Codex-X_${version}_windows_x64_portable"
-          rm -rf "apps/desktop/src-tauri/portable"
+          required=(
+            APPLE_CERTIFICATE
+            APPLE_CERTIFICATE_PASSWORD
+            APPLE_API_ISSUER
+            APPLE_API_KEY
+            APPLE_API_KEY_P8_BASE64
+            APPLE_SIGNING_IDENTITY
+            APPLE_TEAM_ID
+            KEYCHAIN_PASSWORD
+          )
+          for name in "${required[@]}"; do
+            if [ -z "${!name:-}" ]; then
+              echo "Missing required repository secret: ${name}" >&2
+              exit 1
+            fi
+          done
+          certificate_path="$RUNNER_TEMP/codex-x-developer-id.p12"
+          api_key_path="$RUNNER_TEMP/AuthKey_${APPLE_API_KEY}.p8"
+          keychain_path="$RUNNER_TEMP/codex-x-signing.keychain-db"
+
+          printf '%s' "$APPLE_CERTIFICATE" | base64 -D > "$certificate_path"
+          printf '%s' "$APPLE_API_KEY_P8_BASE64" | base64 -D > "$api_key_path"
+          chmod 600 "$certificate_path" "$api_key_path"
+
+          security create-keychain -p "$KEYCHAIN_PASSWORD" "$keychain_path"
+          security default-keychain -s "$keychain_path"
+          security unlock-keychain -p "$KEYCHAIN_PASSWORD" "$keychain_path"
+          security set-keychain-settings -lut 21600 "$keychain_path"
+          security import "$certificate_path" \
+            -k "$keychain_path" \
+            -P "$APPLE_CERTIFICATE_PASSWORD" \
+            -T /usr/bin/codesign
+          security set-key-partition-list \
+            -S apple-tool:,apple:,codesign: \
+            -s \
+            -k "$KEYCHAIN_PASSWORD" \
+            "$keychain_path"
+          security find-identity -v -p codesigning "$keychain_path" \
+            | grep -F -- "$APPLE_SIGNING_IDENTITY" >/dev/null
+
+          echo "APPLE_API_KEY_PATH=$api_key_path" >> "$GITHUB_ENV"
+          echo "CODEXX_KEYCHAIN_PATH=$keychain_path" >> "$GITHUB_ENV"
+          echo "CODEXX_CERTIFICATE_PATH=$certificate_path" >> "$GITHUB_ENV"
+
+      - name: Validate updater signing secrets
+        env:
+          TAURI_SIGNING_PRIVATE_KEY: ${{ secrets.TAURI_SIGNING_PRIVATE_KEY }}
+          TAURI_SIGNING_PRIVATE_KEY_PASSWORD: ${{ secrets.TAURI_SIGNING_PRIVATE_KEY_PASSWORD }}
+        run: |
+          set -euo pipefail
+          if [ -z "$TAURI_SIGNING_PRIVATE_KEY" ] || [ -z "$TAURI_SIGNING_PRIVATE_KEY_PASSWORD" ]; then
+            echo "Missing Tauri updater signing repository secrets" >&2
+            exit 1
+          fi
+
+      - name: Build, sign, and upload updater artifacts
+        # Pinned to tauri-action v1.0.0 because this step receives the updater private key.
+        uses: tauri-apps/tauri-action@1deb371b0cd8bd54025b384f1cd735e725c4060f
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+          TAURI_SIGNING_PRIVATE_KEY: ${{ secrets.TAURI_SIGNING_PRIVATE_KEY }}
+          TAURI_SIGNING_PRIVATE_KEY_PASSWORD: ${{ secrets.TAURI_SIGNING_PRIVATE_KEY_PASSWORD }}
+          APPLE_SIGNING_IDENTITY: ${{ matrix.macos && secrets.APPLE_SIGNING_IDENTITY || '' }}
+          APPLE_API_ISSUER: ${{ matrix.macos && secrets.APPLE_API_ISSUER || '' }}
+          APPLE_API_KEY: ${{ matrix.macos && secrets.APPLE_API_KEY || '' }}
+          APPLE_API_KEY_PATH: ${{ matrix.macos && env.APPLE_API_KEY_PATH || '' }}
+          APPLE_TEAM_ID: ${{ matrix.macos && secrets.APPLE_TEAM_ID || '' }}
+        with:
+          releaseId: ${{ needs.prepare.outputs.release_id }}
+          tagName: ${{ needs.prepare.outputs.tag }}
+          releaseBody: ${{ needs.prepare.outputs.release_body }}
+          releaseDraft: true
+          prerelease: false
+          projectPath: apps/desktop
+          args: ${{ matrix.args }}
+          releaseAssetNamePattern: ${{ matrix.asset_pattern }}
+          uploadUpdaterJson: true
+          uploadUpdaterSignatures: true
+          updaterJsonPreferNsis: true
+          retryAttempts: 3
+
+      - name: Verify updater signatures were generated
+        run: |
+          set -euo pipefail
+          signature_count=$(find apps/desktop/src-tauri/target/release/bundle -type f -name '*.sig' | wc -l | tr -d ' ')
+          if [ "$signature_count" -lt 1 ]; then
+            echo "No updater signatures were generated" >&2
+            exit 1
+          fi
+
+      - name: Test Windows installation and legacy MSI migration
+        if: matrix.platform == 'windows-latest'
+        shell: pwsh
+        run: |
+          $installers = @(Get-ChildItem apps/desktop/src-tauri/target/release/bundle/nsis -Filter '*.exe')
+          if ($installers.Count -ne 1) { throw 'Expected one NSIS installer.' }
+          ./scripts/windows-install-smoke.ps1 -Installer $installers[0].FullName
+
+      - name: Verify signed and notarized macOS bundles
+        if: matrix.macos
+        run: |
+          set -euo pipefail
+          app_path=$(find apps/desktop/src-tauri/target/release/bundle/macos -maxdepth 1 -type d -name '*.app' -print -quit)
+          dmg_path=$(find apps/desktop/src-tauri/target/release/bundle/dmg -maxdepth 1 -type f -name '*.dmg' -print -quit)
+          test -n "$app_path"
+          test -n "$dmg_path"
+          codesign --verify --deep --strict --verbose=2 "$app_path"
+          spctl --assess --type execute --verbose=4 "$app_path"
+          xcrun stapler validate "$app_path"
+          hdiutil verify "$dmg_path"
+
+      - name: Create and upload Windows portable archive
+        if: matrix.platform == 'windows-latest'
+        env:
+          GH_TOKEN: ${{ github.token }}
+          RELEASE_TAG: ${{ needs.prepare.outputs.tag }}
+          VERSION: ${{ needs.prepare.outputs.version }}
+        run: |
+          set -euo pipefail
+          portable_root="apps/desktop/src-tauri/portable"
+          portable_dir="$portable_root/Codex-X-${VERSION}-windows-x64-portable"
+          archive="apps/desktop/src-tauri/Codex-X-${VERSION}-windows-x64-portable.zip"
+          rm -rf "$portable_root"
           mkdir -p "$portable_dir"
           cp apps/desktop/src-tauri/target/release/codex-x.exe "$portable_dir/Codex-X.exe"
+          cp THIRD_PARTY_NOTICES.md "$portable_dir/THIRD_PARTY_NOTICES.md"
+          touch "$portable_dir/Codex-X.portable"
           cat > "$portable_dir/README-portable.txt" <<'EOF'
           Codex-X Windows Portable
 
-          Double click Codex-X.exe to run. No MSI installation is required.
+          Double click Codex-X.exe to run. No installation is required.
+          The portable edition uses manual downloads instead of in-app installation.
+          Keep Codex-X.portable next to Codex-X.exe so the app can identify this edition.
           Microsoft Edge WebView2 Runtime is required; Windows 10/11 usually already includes it.
           EOF
-          powershell -NoProfile -Command "Compress-Archive -Path 'apps/desktop/src-tauri/portable/Codex-X_${version}_windows_x64_portable/*' -DestinationPath 'apps/desktop/src-tauri/Codex-X_${version}_windows_x64_portable.zip' -Force"
+          powershell -NoProfile -Command "Compress-Archive -Path '${portable_dir}/*' -DestinationPath '${archive}' -Force"
+          gh release upload "$RELEASE_TAG" "$archive" --clobber
 
-      - name: Normalize release asset names
+      - name: Remove temporary Apple credentials
+        if: always() && matrix.macos
         run: |
-          set -euo pipefail
-          version=$(node -p "require('./apps/desktop/package.json').version")
-          case "${{ matrix.name }}" in
-            "macOS Apple Silicon")
-              target="apps/desktop/src-tauri/target/release/bundle/dmg/Codex-X_${version}_macos_apple_silicon_aarch64.dmg"
-              src=$(find apps/desktop/src-tauri/target/release/bundle/dmg -maxdepth 1 -type f -name '*.dmg' | head -n 1)
-              test -n "$src"
-              mv "$src" "$target"
-              ;;
-            "macOS Intel")
-              target="apps/desktop/src-tauri/target/release/bundle/dmg/Codex-X_${version}_macos_intel_x64.dmg"
-              src=$(find apps/desktop/src-tauri/target/release/bundle/dmg -maxdepth 1 -type f -name '*.dmg' | head -n 1)
-              test -n "$src"
-              mv "$src" "$target"
-              ;;
-            "Windows")
-              target="apps/desktop/src-tauri/target/release/bundle/msi/Codex-X_${version}_windows_x64.msi"
-              src=$(find apps/desktop/src-tauri/target/release/bundle/msi -maxdepth 1 -type f -name '*.msi' | head -n 1)
-              test -n "$src"
-              mv "$src" "$target"
-              ;;
-            "Linux")
-              deb_target="apps/desktop/src-tauri/target/release/bundle/deb/Codex-X_${version}_linux_x64.deb"
-              rpm_target="apps/desktop/src-tauri/target/release/bundle/rpm/Codex-X_${version}_linux_x64.rpm"
-              deb_src=$(find apps/desktop/src-tauri/target/release/bundle/deb -maxdepth 1 -type f -name '*.deb' | head -n 1)
-              rpm_src=$(find apps/desktop/src-tauri/target/release/bundle/rpm -maxdepth 1 -type f -name '*.rpm' | head -n 1)
-              test -n "$deb_src"
-              test -n "$rpm_src"
-              mv "$deb_src" "$deb_target"
-              mv "$rpm_src" "$rpm_target"
-              ;;
-          esac
+          if [ -n "${CODEXX_KEYCHAIN_PATH:-}" ]; then
+            security delete-keychain "$CODEXX_KEYCHAIN_PATH" || true
+          fi
+          rm -f "${CODEXX_CERTIFICATE_PATH:-}" "${APPLE_API_KEY_PATH:-}"
 
-      - name: Upload bundle artifacts
-        uses: actions/upload-artifact@v4
-        with:
-          name: ${{ matrix.artifact }}
-          path: ${{ matrix.paths }}
-          if-no-files-found: error
-          retention-days: 7
-
-  release:
-    name: Publish GitHub Release
-    needs: build
+  publish:
+    name: Validate and publish release
+    needs: [prepare, build]
     runs-on: ubuntu-22.04
     permissions:
       contents: write
     steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-
-      - name: Download bundle artifacts
-        uses: actions/download-artifact@v4
+      - name: Checkout release tag
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
         with:
-          path: release-assets
-          merge-multiple: true
+          ref: ${{ needs.prepare.outputs.tag }}
 
-      - name: Prepare release notes
-        id: release_notes
-        run: |
-          python3 - <<'PY'
-          from pathlib import Path
-          import os
-          import re
-
-          tag = os.environ["GITHUB_REF_NAME"]
-          text = Path("CHANGELOG.md").read_text(encoding="utf-8")
-          match = re.search(
-              rf"^## \[{re.escape(tag)}\].*?\n(.*?)(?=^## \[|\Z)",
-              text,
-              flags=re.S | re.M,
-          )
-          body = match.group(1).strip() if match else ""
-          if not body:
-              body = "Codex-X desktop release."
-          with open("release-body.md", "w", encoding="utf-8") as fh:
-              fh.write(body + "\n")
-          PY
-
-      - name: Publish release
+      - name: Match release asset labels to filenames
         env:
           GH_TOKEN: ${{ github.token }}
+          RELEASE_ID: ${{ needs.prepare.outputs.release_id }}
         run: |
           set -euo pipefail
-          tag="${GITHUB_REF_NAME}"
-          title="Codex-X ${tag}"
-          if gh release view "$tag" >/dev/null 2>&1; then
-            gh release edit "$tag" --title "$title" --notes-file release-body.md --latest
-          else
-            gh release create "$tag" --title "$title" --notes-file release-body.md --latest
-          fi
-          mapfile -t assets < <(find release-assets -type f \( -name '*.dmg' -o -name '*.msi' -o -name '*.deb' -o -name '*.rpm' -o -name '*.zip' \) -print | sort)
-          if [ "${#assets[@]}" -eq 0 ]; then
-            echo "No release assets found" >&2
+          assets_endpoint="/repos/${GITHUB_REPOSITORY}/releases/${RELEASE_ID}/assets?per_page=100"
+          gh api "$assets_endpoint" \
+            --jq '.[] | select(.label != .name) | [.id, .name] | @tsv' \
+            | while IFS=$'\t' read -r asset_id asset_name; do
+                gh api --method PATCH \
+                  "/repos/${GITHUB_REPOSITORY}/releases/assets/${asset_id}" \
+                  -f "label=${asset_name}" >/dev/null
+              done
+
+          mismatched_labels=$(gh api "$assets_endpoint" \
+            --jq '[.[] | select(.label != .name)] | length')
+          if [ "$mismatched_labels" -ne 0 ]; then
+            echo "Release asset labels do not match their filenames" >&2
             exit 1
           fi
-          printf 'Uploading %s\n' "${assets[@]}"
-          gh release upload "$tag" "${assets[@]}" --clobber
+
+      - name: Download and validate updater manifest
+        env:
+          GH_TOKEN: ${{ github.token }}
+          RELEASE_ID: ${{ needs.prepare.outputs.release_id }}
+          RELEASE_TAG: ${{ needs.prepare.outputs.tag }}
+          VERSION: ${{ needs.prepare.outputs.version }}
+        run: |
+          set -euo pipefail
+          gh api "/repos/${GITHUB_REPOSITORY}/releases/${RELEASE_ID}/assets?per_page=100" > release-assets.json
+          latest_asset_id=$(jq -r '.[] | select(.name == "latest.json") | .id' release-assets.json)
+          if [ -z "$latest_asset_id" ] || [ "$latest_asset_id" = "null" ]; then
+            echo "latest.json is missing from the draft release" >&2
+            exit 1
+          fi
+          gh api \
+            -H "Accept: application/octet-stream" \
+            "/repos/${GITHUB_REPOSITORY}/releases/assets/${latest_asset_id}" \
+            > latest.json
+          python3 scripts/validate_updater_release.py \
+            --manifest latest.json \
+            --assets release-assets.json \
+            --version "$VERSION" \
+            --repository "$GITHUB_REPOSITORY" \
+            --release-tag "$RELEASE_TAG" \
+            --rewrite-download-urls \
+            --migrate-windows-to-nsis \
+            --require-signature-assets
+          gh release upload "$RELEASE_TAG" latest.json --clobber
+
+      - name: Remove public signature assets
+        env:
+          GH_TOKEN: ${{ github.token }}
+          RELEASE_ID: ${{ needs.prepare.outputs.release_id }}
+        run: |
+          set -euo pipefail
+          gh api "/repos/${GITHUB_REPOSITORY}/releases/${RELEASE_ID}/assets?per_page=100" \
+            --jq '.[] | select(.name | endswith(".sig")) | .id' \
+            | while read -r asset_id; do
+                [ -z "$asset_id" ] || gh api --method DELETE "/repos/${GITHUB_REPOSITORY}/releases/assets/${asset_id}"
+              done
+
+      - name: Publish the verified release
+        env:
+          GH_TOKEN: ${{ github.token }}
+          RELEASE_TAG: ${{ needs.prepare.outputs.tag }}
+        run: gh release edit "$RELEASE_TAG" --draft=false --latest
+
+      - name: Verify published updater endpoint
+        env:
+          RELEASE_TAG: ${{ needs.prepare.outputs.tag }}
+          VERSION: ${{ needs.prepare.outputs.version }}
+        run: |
+          set -euo pipefail
+          endpoint="https://github.com/${GITHUB_REPOSITORY}/releases/download/${RELEASE_TAG}/latest.json"
+          curl -fsSL \
+            --retry 12 \
+            --retry-delay 5 \
+            --retry-all-errors \
+            "$endpoint" \
+            -o published-latest.json
+          python3 scripts/validate_updater_release.py \
+            --manifest published-latest.json \
+            --assets release-assets.json \
+            --version "$VERSION" \
+            --repository "$GITHUB_REPOSITORY" \
+            --release-tag "$RELEASE_TAG"
+
+          python3 - <<'PY' > updater-urls.txt
+          import json
+          manifest = json.load(open("published-latest.json", encoding="utf-8"))
+          for entry in manifest["platforms"].values():
+              print(entry["url"])
+          PY
+          sort -u updater-urls.txt | while read -r url; do
+            curl -fsSL \
+              --range 0-0 \
+              --retry 5 \
+              --retry-delay 3 \
+              --retry-all-errors \
+              "$url" \
+              -o /dev/null
+          done

.github/workflows/star-history.yml

@@ -0,0 +1,76 @@
+name: Refresh Star History
+
+on:
+  schedule:
+    - cron: '*/15 * * * *'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: star-history-${{ github.repository }}
+  cancel-in-progress: true
+
+jobs:
+  refresh:
+    name: Refresh chart data
+    runs-on: ubuntu-22.04
+    timeout-minutes: 5
+    steps:
+      - name: Send authenticated repository snapshot
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          INGEST_TOKEN: ${{ secrets.STAR_HISTORY_INGEST_TOKEN }}
+          REPOSITORY: ${{ github.repository }}
+          CAMO_PURGE_URLS: ${{ vars.STAR_HISTORY_CAMO_URLS }}
+          STAR_HISTORY_ENDPOINT: ${{ vars.STAR_HISTORY_ENDPOINT }}
+        run: |
+          set -euo pipefail
+          test -n "${INGEST_TOKEN}"
+          test -n "${STAR_HISTORY_ENDPOINT}"
+          metadata_file="${RUNNER_TEMP}/star-history-metadata.json"
+          payload_file="${RUNNER_TEMP}/star-history-payload.json"
+
+          gh api \
+            --header "Accept: application/vnd.github+json" \
+            --header "X-GitHub-Api-Version: 2022-11-28" \
+            "repos/${REPOSITORY}" > "${metadata_file}"
+
+          jq -n \
+            --arg repository "${REPOSITORY}" \
+            --slurpfile metadata "${metadata_file}" \
+            '{
+                repository: $repository,
+                createdAt: $metadata[0].created_at,
+                checkedAt: (now | todateiso8601),
+                currentStars: $metadata[0].stargazers_count
+              }' > "${payload_file}"
+
+          curl \
+            --fail-with-body \
+            --retry 3 \
+            --retry-all-errors \
+            --connect-timeout 15 \
+            --max-time 240 \
+            --request POST \
+            --header "Authorization: Bearer ${INGEST_TOKEN}" \
+            --header "Content-Type: application/json" \
+            --data-binary "@${payload_file}" \
+            "${STAR_HISTORY_ENDPOINT}"
+
+          while IFS= read -r camo_url; do
+            test -n "${camo_url}" || continue
+            case "${camo_url}" in
+              https://camo.githubusercontent.com/*) ;;
+              *) echo "::warning::Skipped an invalid Camo purge URL"; continue ;;
+            esac
+            curl \
+              --fail \
+              --silent \
+              --show-error \
+              --retry 2 \
+              --request PURGE \
+              "${camo_url}" > /dev/null \
+              || echo "::warning::GitHub Camo purge failed and will be retried on the next refresh"
+          done <<< "${CAMO_PURGE_URLS}"

.github/workflows/windows-installer-check.yml

@@ -0,0 +1,51 @@
+name: Windows installer verification
+
+on:
+  push:
+    branches:
+      - 'codex/windows-updater-*'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: windows-installer-check-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  windows-installer:
+    name: Verify Windows update migration
+    runs-on: windows-latest
+    timeout-minutes: 45
+    defaults:
+      run:
+        shell: pwsh
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
+      - uses: pnpm/action-setup@b906affcce14559ad1aafd4ab0e942779e9f58b1
+        with:
+          version: 10.26.0
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020
+        with:
+          node-version: 22
+          cache: pnpm
+      - uses: dtolnay/rust-toolchain@4be7066ada62dd38de10e7b70166bc74ed198c30
+        with:
+          toolchain: stable
+      - uses: Swatinem/rust-cache@e18b497796c12c097a38f9edb9d0641fb99eee32
+        with:
+          workspaces: apps/desktop/src-tauri
+          cache-on-failure: true
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm --dir apps/desktop typecheck
+      - run: cargo test --manifest-path apps/desktop/src-tauri/Cargo.toml --lib --locked -- --test-threads=1
+      - name: Build test installer without publishing or release signing credentials
+        run: |
+          Set-Content -Path "$env:RUNNER_TEMP\installer-check.json" -Value '{"bundle":{"createUpdaterArtifacts":false}}' -Encoding utf8
+          pnpm --dir apps/desktop tauri build --debug --bundles nsis --config "$env:RUNNER_TEMP\installer-check.json" --ci
+      - name: Test real MSI migration and subsequent updates
+        run: |
+          $installers = @(Get-ChildItem apps/desktop/src-tauri/target/debug/bundle/nsis -Filter '*.exe')
+          if ($installers.Count -ne 1) { throw 'Expected one Windows installer.' }
+          ./scripts/windows-install-smoke.ps1 -Installer $installers[0].FullName

.github/workflows/windows-msi-probe.yml

@@ -0,0 +1,24 @@
+name: Windows MSI API probe
+
+on:
+  push:
+    branches: ['codex/windows-updater-*']
+    paths: ['scripts/windows-msi-probe.ps1', '.github/workflows/windows-msi-probe.yml']
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  msi-probe:
+    runs-on: windows-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
+      - shell: pwsh
+        run: |
+          if (-not (Test-Path "${env:ProgramFiles(x86)}\NSIS\makensis.exe")) {
+            choco install nsis --yes --no-progress
+          }
+      - shell: pwsh
+        run: ./scripts/windows-msi-probe.ps1

.gitignore

@@ -23,6 +23,14 @@ apps/desktop/src-tauri/gen/schemas/
 .env
 .env.*
 *.local
+apple cert/
+*.p12
+*.p8
+*.pfx
+*.pem
+*.key
+codex-x-updater.key
+codex-new-ui/
 
 # Backups
 *.bak

CHANGELOG.md

@@ -1,175 +1,429 @@
-# Changelog
+# 更新日志
 
-All notable changes to Codex-X will be documented here.
+记录 Codex-X 的新功能、体验改进和问题修复。
 
+## [v0.3.21] - 2026-09-23
 
+- 优化 Windows 在线更新，缩短安装等待；旧版可自动迁移，正常更新无需重启电脑，账号和配置保留。
+
+## [v0.3.20] - 2026-09-18
+
+- 新增「设置 → 路由与故障转移」：可管理本地路由、安排供应商优先顺序，并在服务异常时自动切换；支持调整超时和重试参数，官方登录也可使用本地路由。
+- 修复添加或切换第三方供应商时，MCP、桌面设置等配置丢失的问题。
+- 修复内部任务被误同步，以及回退后的正常会话被误报异常的问题。
+
+## [v0.3.18] - 2026-09-17
+
+- 第三方模型映射后可在 Codex 中选择推理等级，并修复 DeepSeek 每次发送消息先报错、重试后才能使用的问题。
+- 新增后台配置检查：发现可能导致 Codex 无法使用的问题时提醒你，可选择修复，也可稍后到「设置 → 通用设置」处理。修复前会自动备份。
+- 会话支持导出为 Markdown，多选会话可打包下载；MCP 和 Skills 支持 ZIP 导出、重新导入，取消 Skills ZIP 的 20 MB 大小限制。
+- 修复「导入已有」弹窗的暗色显示、无效 MCP 重复出现，以及大日志记录被用量统计跳过的问题。
+
+## [v0.3.17] - 2026-09-09
+
+### 新增与优化
+
+- 官方账号支持查看剩余额度、重置时间和可用重置次数，列表中显示邮箱、套餐和登录状态。
+- 新增 DeepSeek、MiniMax、小米 MiMo 等主流厂商预设和模型映射，方便在 Codex 中使用第三方模型，并保留已有配置。
+
+### 问题修复
+
+- 修复编辑正在使用的供应商时保存报错、切换后出现重复供应商，以及部分第三方连接认证失败的问题。
+- 修复用量统计切换日期范围时页面闪白的问题。
+
+## [v0.3.16] - 2026-09-09
+
+### 新功能
+
+- 支持保存多个官方 Codex 账号，并为每个账号起不同的名字，方便切换使用。
+- 官方账号和第三方供应商都支持一键复制，点击后直接生成副本。
+- 新增“开启 1M 上下文窗口”选项，可按需勾选使用（需要模型支持）。
+- 设置页新增“用量统计”，可以查看 Token 用量、每日趋势、模型分布和最近 10 个会话，并按日期、模型筛选。
+- AI 后台子任务的用量合并到主对话，聊天列表只显示主会话。最近会话显示聊天标题或项目名，更容易找到。
+
+### 体验改进
+
+- 提示词页面的标题统一为蓝色，设置页的标签切换加入过渡动画。
+
+### 问题修复
+
+- 修复同步 GitHub 提示词模板时，供应商按钮暂时无法使用的问题。
+- 修复切换供应商后，原有的 CC Switch 供应商从列表消失的问题。
+
+## [v0.3.15] - 2026-08-20
+
+### 问题修复
+
+- 修复 Windows 点击“重启 Codex”后只隐藏窗口、未真正退出，以及再次重启时报错的问题。
+
+## [v0.3.14] - 2026-08-20
+
+### 更新
+
+- MCP 和 Skills 支持添加自定义备注，方便区分用途。
+- 供应商支持复制，同一 API 平台可以保存多个模型或多份配置，副本放在列表末尾。
+- 简化供应商列表，不再重复显示模型信息。
+- 设置页新增“重启 Codex”按钮，支持 macOS 和 Windows。
+
+### 问题修复
+
+- 修复相同供应商配置被覆盖，以及复制当前供应商后丢失启用状态的问题。
+- 修复 Codex 自动创建的子代理会话被错误标记为“待同步”的问题。
+
+## [v0.3.13] - 2026-08-18
+
+### 问题修复
+
+- 已归档的会话不再被标记为“待同步”，切换供应商时会继续保持归档状态。
+
+## [v0.3.12] - 2026-08-11
+
+### 更新
+
+- 提升使用流畅度，修复部分问题。
+
+## [v0.3.11] - 2026-08-11
+
+### 更新
+
+- 提升使用流畅度，修复部分问题。
+
+## [v0.3.10] - 2026-08-11
+
+### 更新
+
+- 提升使用流畅度，修复部分问题。
+
+## [v0.3.9] - 2026-08-11
+
+### 更新
+
+- 提升使用流畅度，修复部分问题。
+
+## [v0.3.8] - 2026-08-03
+
+### 问题修复
+
+- 修复部分使用问题。
+
+## [v0.3.7] - 2026-08-02
+
+### 问题修复
+
+- 修复部分使用问题。
+
+## [v0.3.6] - 2026-07-31
+
+### 更新
+
+- 官方登录与第三方供应商切换后，新建会话即可使用，无需重启 Codex。
+- 关闭主窗口后，软件会留在 macOS 菜单栏或 Windows 托盘中，可从菜单恢复窗口或退出。
+
+### 问题修复
+
+- 修复切换第三方供应商时丢失官方登录或官方 API Key 的问题，现在切回官方时可以恢复。
+- 修复编辑当前供应商时意外新增副本、重复导入 cc-switch 产生重复项的问题，并兼容旧版 cc-switch 的官方登录导入。
+- 修复同时操作供应商、提示词或其他设置时，配置被覆盖或损坏的问题。
+- 修复会话同步提示成功却未生效的问题，并改善对自定义会话存储位置的支持。
+- 修复旧记录被重复计入会话数量，以及同步时误改旧会话或项目位置的问题。
+
+## [v0.3.5] - 2026-07-28
+
+### 更新
+
+- GitHub 提示词模板可以直接查看和编辑内容，名称和文件名仍跟随在线版本。
+- 编辑后的模板会标记为“本地已修改”，后续同步不会覆盖你的修改，新模板仍会正常下载；修改在下次启用模板时生效。
+- 仅查看模板或保存未改动的内容，不会影响后续在线更新。
+
+### 问题修复
+
+- 修复同步 GitHub 模板时只能看到 5 个、无法获取完整 11 个模板的问题；网络异常时仍可使用已有缓存。
+- 修复使用第三方供应商时，概览页误报未找到官方登录信息的问题。
+
+## [v0.3.4] - 2026-07-28
+
+### 更新
+
+- 在线模板库新增 6 套提示词，点击同步 GitHub 模板即可获取，不增加安装包体积。
+- 软件开发新增“长期维护工程师”“系统化调试与根因修复”“严格代码审查”。
+- 写作辅助新增“清晰表达与润色”“技术文档写作”“结构化长文起草”。新模板会自动分类，仍保留用户手动设置的分类。
+
+### 问题修复
+
+- 修复切换第三方供应商或从 cc-switch 导入后，官方登录信息被覆盖、需要重新登录的问题。
+- “还原官方配置”不再自动切换当前供应商；新增“新建官方配置”，方便清除异常认证后重新登录。
+- 调整官方认证编辑框，长内容可以换行显示，更方便查看和选择。
+
+## [v0.3.3] - 2026-07-26
+
+### 调整
+
+- 暂时下线皮肤中心，隐藏侧边栏入口，保留用户已保存的本地主题文件。
+- 升级后会自动关闭此前启用的皮肤，恢复 Codex 官方外观；若恢复失败，会显示原因。
+- 安装包不再附带“椎名真白·樱花画室”主题壁纸，减小下载体积。
+
+## [v0.3.2] - 2026-07-25
+
+### 问题修复
+
+- 修复 Windows 启动 Codex 或进入新版首页、外观设置时，皮肤功能错误提示无法识别 Codex 的问题。
+- 皮肤出现异常时仍可点击“关闭皮肤”，恢复过程中会避免重复操作。
+
+### 安全改进
+
+- 皮肤功能仅用于已识别的官方 Codex 窗口，不会应用到普通网页。
+
+## [v0.3.1] - 2026-07-24
+
+### 更新
+
+- 重新设计皮肤中心，可直接预览壁纸、侧边栏、会话区和输入框的整体效果，主题卡片更紧凑。
+- 支持主题分类筛选，卡片会根据数量自动调整为 1 至 4 列；导出主题可使用系统“另存为”窗口。
+- 支持从图片创建主题，并修改名称、简介和界面透明度。
+- 皮肤功能支持 Windows 官方商店版 Codex，无需修改 Codex 安装文件。
+- 合并重复的恢复按钮，统一使用“关闭皮肤”。
+
+### 问题修复
+
+- 修复 macOS 应用皮肤后一直显示“应用中”，以及重开软件后无法识别当前主题的问题。
+- 修复皮肤按钮状态错误、刷新缺少反馈，以及提示词或主题较多时无法继续向下滚动的问题。
+- 优化横图壁纸的裁剪，减少人物头部被切掉的情况。
+- 修复切换第三方供应商时覆盖官方登录信息的问题。
+- 改善 Codex 安装检测，减少已安装却显示“未检测到 Codex”的情况。
+- 修复启用皮肤后输入框消失、聊天内容透过输入框，以及图片主题预览显示错误背景的问题。
+- 修复浅色主题下壁纸颜色发白的问题，并改善透明度调整和输入框文字的清晰度。
+
+### 安全与来源
+
+- 加强官方 Codex 识别、主题导入和切换检查。
+- 换肤功能使用 Codex Dream Skin Studio 的 MIT 授权代码，未包含其非 MIT 授权的真人主题素材。
+
+## [v0.3.0] - 2026-07-16
+
+### 更新
+
+- 全面更新界面，统一页面、按钮、弹窗和通知样式，加入深浅色模式与页面切换动画。
+- 新增应用内更新，macOS、Windows MSI 和 Linux AppImage 用户可直接下载、安装并重启；侧边栏会显示更新入口和进度。
+- 改进供应商连接测试，删除前增加确认，添加或编辑时可以获取并选择模型，官方登录页面更简洁。
+- 提示词新增分类和两套内置模板，卡片更简洁；添加或编辑后只保存，需要时再手动启用。
+- 启动后会在后台同步在线模板，网络异常时尝试备用下载来源；模板会保存到本机，离线时仍能使用，支持系统代理。
+- 会话统一同步到当前供应商，不再在启动时自动修改；支持查看、选择和删除内部会话。
+- 导入 Skills / MCP 时会跳过已有内容，没有新内容时不再弹出空窗口。
+
+### 问题修复
+
+- 修复部分旧提示词配置导致 Codex 报错，以及 Windows 将配置文件夹链接到其他位置后无法读写的问题。
+- 修复会话同步报错、会话重复显示，以及聊天记录被误改或覆盖的问题。
+- 修复深浅色模式下部分文字和控件显示异常，以及打开弹窗后背景仍能滚动的问题。
+- 修复提示词重复同步、错误更新或误删除，以及应用更新失败后提示不准确的问题。
+- 完善安装包和更新的安全检查。
+
+### 兼容说明
+
+- `v0.3.0` 是首个支持应用内更新的版本，旧版用户需要手动安装本版本一次。
+- Windows 便携版和 Linux deb/rpm 仍需手动更新；Windows MSI 首次安装可能出现系统安全提示（SmartScreen）。
+
+## [v0.2.35] - 2026-07-13
+
+- 新增 `gpt-5.6-sol-unrestricted.md` 提示词模板，同步 GitHub 模板后即可启用。
+- 切换第三方供应商后，新建或重新打开 Codex 会话即可使用新供应商，无需重启整个 Codex 客户端。
+- 自动整理 API 地址和密钥均相同的重复供应商；同一地址使用不同密钥的供应商仍分别保留。
+- 修复切换供应商或切回官方登录后，原供应商可能消失的问题。
+- 从 cc-switch 导入时，会显示新增、更新、合并和跳过数量；重复导入不再覆盖已有名称、模型和自定义配置，并兼容旧版 cc-switch 数据。
+- 会话列表不再重复展示 Codex 自动创建的后台子会话，项目和会话数量更准确；会话编号保留首尾，方便区分。
+- 修复编辑同名供应商时可能覆盖另一条记录的问题。
+
+## [v0.2.34] - 2026-07-13
+
+- 会话管理支持单选或多选后永久删除，所选会话派生的子会话也会一并删除。删除不进入回收站、不创建新的备份，在 Codex-X 中无法撤销。
+- 删除前可预览待删除会话，并需确认已关闭其他正在使用这些会话的 Codex 窗口或命令行进程。
+- 支持按项目勾选当前已加载的会话，也可跨项目批量选择；搜索时同时显示匹配数量和项目会话总数。
+- 会话列表改为紧凑表格，标题、更新时间、供应商、模型和编号更清晰。检查与修复统一使用顶部的“检查会话”和“同步 / 修复”。
+- 修复默认窗口大小下会话列表无法继续向下滚动的问题。
+- 修复升级 Codex 后可能重复统计会话、混入旧会话的问题。
+- 批量删除部分失败时，会保留未删除项并显示失败数量和原因，方便处理后重试。
+
+## [v0.2.33] - 2026-07-11
+
+- 重新整理【指令提示词】页面，当前状态、启用方式、模板来源和更新时间更清晰，并简化模板说明。
+- 同步 GitHub 时会自动添加新模板、移除已删除模板；离线时仍可使用上次成功同步的内容。
+- 新增 `海鸥3.0破甲.md` 示例模板，清理不再使用的旧示例。
+- 修复返回提示词页面时列表先显示旧内容再跳到新内容，以及模板较多时列表超出边框的问题。
+- 修复同步或下载失败时模板列表可能出错、误删的问题，失败后可重新同步；正在使用的模板即使已从 GitHub 删除，重启后仍可正常关闭。
+- 修复 macOS、Windows 和 Linux 应用图标外围出现大块白边的问题。
+
+## [v0.2.32] - 2026-07-11
+
+- 提示词“启用方式”增加说明，方便了解“保留原提示词”和“替换原提示词”的区别，并核对当前启用状态。
+- 修复配置相近的多个供应商可能同时显示“当前启用”、重复显示供应商卡片的问题。
+- 关闭追加的提示词时会保留用户原有规则，自定义规则也支持备份和恢复。
+- 修复多项操作同时备份时可能失败的问题。
+- 修复切换 Skill 或 MCP 开关后，条目跳到列表其他位置的问题。
+- 修复 macOS 窗口顶部无法拖动的问题，并改善 Windows 上 Codex 版本的识别。
+
+## [v0.2.31] - 2026-07-09
+
+- 调整 macOS 顶部通知的位置，避免提示随页面内容下移。
+- 从 ZIP 安装 Skill 后显示其实际名称和说明；刷新时会尝试修正旧版安装留下的临时名称。
+- 修复启用第三方供应商后，重新打开 Codex-X 不再显示“当前启用”的问题。
+- 修复 Windows 和 Linux 供应商编辑页无法正常向下滚动的问题。
+
+## [v0.2.30] - 2026-07-09
+
+- 精简会话管理顶部信息栏，为会话列表留出更多空间；选择会话时实时显示已选数量和可修复数量。
+- 新增“启动自动修复”开关，开启后会在启动时后台检查会话，并自动修复未同步的会话，不影响界面操作。
+- 减少按钮点击和页面滚动时的闪烁、卡顿。
+- 修复同名供应商可能同时显示“当前启用”，以及新增同名供应商发生冲突的问题。
+- 修复同名提示词可能同时显示为启用的问题。
+
+## [v0.2.29] - 2026-07-07
+
+- 通知改为顶部居中显示，减少对右上角按钮的遮挡；供应商连接测试结果更简洁，显示连接状态和耗时。
+- 第三方供应商支持保存配置模板：“保存”只保存配置，点击“启用”后才应用到 Codex。
+- Skills 和 MCP 的“导入已有”增加预览，确认列表后才执行导入。
+- 修复切换第三方供应商后 Codex 可能回到登录页的问题。
+- 官方认证编辑页默认读取当前登录信息，并提供“刷新当前 auth.json”；修复切回官方登录时可能恢复成旧账号的问题。
+- 修复连接测试将“访问被拒绝”误报为连接正常，以及从 cc-switch 导入时出现重复供应商卡片的问题。
+- 修复部分用户升级后无法启动的问题。
 
 ## [v0.2.28] - 2026-07-07
 
-- 修复从 cc-switch 导入 Codex Provider 时可能把供应商名称、base_url 与 API Key 串台的问题。
-- 导入 cc-switch Provider 时改为先扫描所有 `[model_providers.<id>]` section，再按 provider row id 精确匹配，避免使用过期的 `model_provider` active 值。
-- 兼容 cc-switch legacy `custom` provider 模板，同时保留 `experimental_bearer_token` 兜底。
-- 增加复现 Sky2api / MagicAI 交叉配置的单元测试，防止 Provider 切换再次出现“看起来切了但实际没切对”的问题。
+- 修复从 cc-switch 导入供应商时，名称、API 地址和密钥可能相互混淆的问题，避免启用后实际使用了其他供应商。
+- 改善旧版 cc-switch 供应商配置的导入兼容性。
 
 ## [v0.2.27] - 2026-07-07
 
-- 优化【指令提示词】页面为 Skills/MCP 风格的简洁列表：左侧显示模板名称与说明，右侧使用开启/关闭切换；自定义/导入的 md 提示词增加编辑与删除图标。
-- 优化【供应商】页面操作区：移除“官方配置 / 本地保存 / gpt-5.5 / 不支持路由”等冗余信息，将切换改为“启用”，编辑/删除/测试连接改为图标按钮。
-- 新增供应商 base_url 连通性测试按钮，方便切换前检查第三方 API 地址是否可达。
-- 修复第三方 Provider 切换后可能未真正生效的问题：切换和保存 TOML 时会写入 Codex 实际读取的 `experimental_bearer_token`。
-- 对齐 cc-switch 的 Codex Provider live config 思路：从 cc-switch 导入时会识别 `experimental_bearer_token`，并避免使用 Codex 内置保留 provider id。
-- 优化启动加载链路：启动诊断、备份列表、会话同步状态改为后台刷新，减少首屏等待。
+- 提示词页面改为简洁列表，名称和说明更清晰，右侧可直接开关；自定义和导入的提示词支持编辑、删除。
+- 精简供应商操作区，将“切换”改为“启用”，编辑、删除和连接测试改为图标按钮。
+- 新增供应商连接测试，方便启用前检查第三方 API 地址是否可用。
+- 修复第三方供应商切换后可能未真正生效的问题，并改善从 cc-switch 导入配置的兼容性。
+- 减少启动等待，检查、备份列表和会话状态在后台加载。
 
 ## [v0.2.26] - 2026-07-07
 
-- 修复第三方 Provider 切换后可能“看起来已切换但实际未按新供应商生效”的问题：不再把所有第三方都写成 `model_provider = "custom"`，而是写入供应商自己的稳定 ID。
-- 修复从官方 ChatGPT 登录态切到第三方 API Key 时 `auth.json` 仍保留 `auth_mode = "chatgpt"` 的问题；写入 API Key 时会同步设置 `auth_mode = "api_key"`。
-- 第三方供应商默认不再要求 OpenAI 登录态，避免新建/导入 Provider 时错误继承官方 auth 语义。
-- 增加 Provider 切换单元测试，覆盖真实 provider key 和 API Key auth mode 的落盘结果。
+- 修复第三方供应商显示已切换、实际却未生效的问题。
+- 修复从官方登录切换到第三方 API 密钥后，仍沿用官方登录方式的问题。
+- 新增或导入第三方供应商时，默认不再要求 OpenAI 官方登录。
 
 ## [v0.2.25] - 2026-07-06
 
-- 进一步修复 TOML、指令提示词、供应商、会话管理等页面切换时右侧滚动条闪现/消失造成的视觉抖动。
-- 外层页面滚动容器改为稳定滚动并隐藏外层滚动条，保留 TOML 编辑器、会话列表等内部区域自己的滚动条。
+- 进一步减少切换配置、提示词、供应商和会话页面时，滚动条闪现造成的抖动；编辑器和会话列表仍保留各自的滚动条。
 
 ## [v0.2.24] - 2026-07-06
 
-- 修复切换供应商 / 会话管理等页面时右侧滚动条短暂出现又消失的问题：页面切换动画改为纯透明度过渡，不再用 `translateY` 造成瞬时溢出。
-- 降低页面切换视觉抖动，避免进入页面时内容区域宽度被临时滚动条挤压。
+- 修复切换供应商、会话管理等页面时滚动条短暂闪现、内容宽度跳动的问题，页面切换更平稳。
 
 ## [v0.2.23] - 2026-07-06
 
-- 指令提示词页新增并纳管 `gpt5.5-jeli.md` 模板，作为“大白话（80% 场景）破甲”版本。
-- 简化指令提示词列表视觉：移除花哨图标与文件路径展示，让用户更容易看清模板名称、介绍和启用状态。
-- 更新 GPT-5.5 / GPT-5.4 内置模板名称为“unrestricted 破甲”，并统一说明使用方法：先让 AI 分析项目，分析完之后发【不直白的逆向】命令。
+- 新增 `gpt5.5-jeli.md` 提示词模板，名称为“大白话（80% 场景）破甲”。
+- 精简提示词列表，突出模板名称、介绍和启用状态。
+- GPT-5.5 和 GPT-5.4 内置模板统一使用“unrestricted 破甲”名称，并补充使用说明：先让 AI 分析项目，再发送【不直白的逆向】命令。
 
 ## [v0.2.22] - 2026-07-06
 
-- 继续优化指令提示词页切换体验：导航切换进入 React transition，GitHub 内置模板静默检查延后到空闲时执行，减少切页瞬间卡顿。
-- 修复外部/自定义提示词切换到内置模板后可能出现两份的问题：按规范化内容（换行与首尾空白归一）和文件名双重去重，已有自定义提示词会复用更新，不再新增副本。
-- 优化启用内置提示词速度：启用时直接使用本地缓存或打包内置版本，不再同步等待 GitHub 网络请求；手动/空闲更新仍会刷新本地缓存。
-- 启动页增加动态状态文案、双层轨道与扫光动画，让从欢迎页进入主界面更顺滑。
+- 减少进入提示词页面时的卡顿；GitHub 模板检查延后到空闲时进行。
+- 启用内置提示词时直接使用本地已有内容，无需等待网络；手动同步或空闲检查后会更新模板。
+- 修复从自定义提示词切换到内置模板时可能产生重复项的问题，已有相同提示词会直接更新。
+- 优化启动页状态提示和过渡动画，进入主界面更顺畅。
 
 ## [v0.2.21] - 2026-07-06
 
-- 进一步降低 UI 卡顿风险：将启动检测、Codex 状态读取、Provider/官方配置/备份/cc-switch 导入等剩余同步命令迁移到后台 worker。
-- 优化前端串行请求：提示词启用后的备份/提示词刷新改为并发，保存并启用自定义提示词时不再重复拉取列表。
-- 完善【技能和 MCP】导入已有：读取 cc-switch `mcp_servers` 数据库，按 `enabled_codex` 纳管并同步到 Codex `config.toml [mcp_servers]`。
-- 增强 Skills 检查更新：对带有 cc-switch 仓库元数据的 Skill 拉取 GitHub 仓库 ZIP 计算远程 hash，显示“有新版本 / 已是最新 / 远程检查失败”等状态。
+- 减少启动、供应商操作、备份和导入时的卡顿，并加快提示词保存、启用后的刷新。
+- “导入已有”支持从 cc-switch 导入已为 Codex 启用的 MCP，并应用到 Codex。
+- 来自 cc-switch 且保留仓库信息的 Skill 可检查 GitHub 更新，显示“有新版本”“已是最新”或“远程检查失败”。
 
 ## [v0.2.20] - 2026-07-06
 
-- 继续优化指令提示词页性能：提示词列表/状态读取、保存、导入、启用、禁用等后端操作改为后台 worker，避免切页或启用模板时阻塞 UI。
-- 修复外部自定义提示词重复保存问题：切换到内置模板前会按文件名与内容双重去重，并自动清理历史 `external-*` 重复项。
-- 优化启动加载体验：启动页增加最短展示、退出淡出与动态过渡，避免从欢迎页突然跳到主页。
+- 改善提示词页面响应速度，减少切换页面、保存、导入和开关模板时的卡顿。
+- 修复从自定义提示词切换到内置模板后重复保存的问题，并自动整理已有的此类重复项。
+- 优化启动页展示和退出动画，避免突然跳到主页。
 
 ## [v0.2.19] - 2026-07-06
 
-- 新增【技能和 MCP】页面：展示 Codex 当前已安装 Skills 与 MCP，支持导入已有、从 ZIP 安装 Skill、启用/禁用 Skill、启用/禁用 MCP。
-- MCP 管理会读写 `~/.codex/config.toml` 的 `[mcp_servers]`，禁用后保留到 Codex-X SQLite，后续可一键重新启用。
-- Skills 管理会扫描 `~/.codex/skills`，并可从 `~/.agents/skills`、`~/.cc-switch/skills` 导入到 Codex；禁用后移动到 Codex-X 禁用目录，避免直接删除。
-- 优化多个潜在卡顿点：指令提示词 GitHub 检查改为延迟后台执行，远程拉取、会话扫描/同步、Skills/MCP 扫描均放入后台 blocking worker。
-- 修复外部自定义提示词切换到内置提示词后重复出现的问题，并自动清理同名 `external-*` 重复项。
-- 增加页面切换过渡、启动页动态光效和首次启动向导退出动画，降低页面突然跳转感。
+- 新增【技能和 MCP】页面，可查看已安装内容、导入已有配置、从 ZIP 安装 Skill，以及启用或禁用 Skill 和 MCP。
+- 禁用 Skill 或 MCP 后仍保留原有内容，可随时重新启用；支持导入本机已有的 Skill 和 cc-switch 中的技能。
+- 减少 GitHub 模板检查、会话检查与同步、Skills 和 MCP 加载时的卡顿。
+- 修复从自定义提示词切换到内置模板后出现重复项的问题，并自动整理已有的同名重复项。
+- 优化页面切换、启动页和首次启动向导的过渡动画。
 
 ## [v0.2.18] - 2026-07-05
 
-- 指令提示词内置模板支持从 GitHub `examples/` 实时检查更新，并缓存到本地；启用内置模板时优先使用 GitHub 最新版本，离线时自动回退本地缓存或打包内置版本。
-- 指令提示词页面新增“更新内置模板”状态与来源展示，可看到模板来自 GitHub 最新、本地缓存或打包内置。
-- 继续保留导入 `.md` 提示词、外部提示词自动记忆、会话管理交互优化和 API Key 可见切换等体验改进。
+- 内置提示词支持从 GitHub 检查更新，启用时优先使用最新模板；离线时可使用本地缓存或随应用提供的模板。
+- 提示词页面新增更新状态和模板来源提示。
 
 ## [v0.2.17] - 2026-07-04
 
-- 修复 macOS Intel Release 构建 runner：从已不可用/长时间排队的 `macos-13` 切换为 `macos-15-intel`。
-- 继续保留 macOS Apple Silicon / macOS Intel / Windows MSI / Windows portable ZIP / Linux deb/rpm 多平台产物。
+- 修复 Intel Mac 安装包发布失败或长时间等待的问题。
 
 ## [v0.2.16] - 2026-07-04
 
-- Release 新增 macOS Intel 构建，Intel Mac 用户可下载 x64 DMG。
-- macOS Release 现在同时提供 Apple Silicon 与 Intel 两种 DMG。
-- Windows Release 新增 portable ZIP，包含可直接运行的 `Codex-X.exe`，无需 MSI 安装。
-- 发布流程支持上传 `.zip` portable 产物，并更新 README 下载说明。
+- 新增 Intel Mac 版 DMG，macOS 用户可按芯片类型选择 Intel 或 Apple Silicon 安装包。
+- 新增 Windows 免安装 ZIP，解压后即可运行，无需安装 MSI。
 
 ## [v0.2.15] - 2026-07-04
 
-- 会话管理页移除 CODEX_HOME 与 Provider Sync 备份位置展示，页面信息更简洁。
-- 优化 Windows 打开下载页体验：后端改为后台线程 spawn 浏览器，不再等待 `cmd /C start`，避免 WebView 卡顿 2-3 秒。
-- 统一所有外部链接按钮走异步打开逻辑，打开项目主页、反馈页、下载页都不会阻塞界面。
-- 修复 macOS 顶部 toast 被 Overlay 标题栏遮挡的问题，toast 自动下移到标题栏安全区下方。
+- 精简会话管理页面，移除不常用的配置和备份位置说明。
+- 修复 Windows 打开下载页、项目主页等外部链接时界面短暂卡顿的问题。
+- 修复 macOS 顶部提示消息被标题栏遮挡的问题。
 
 ## [v0.2.14] - 2026-07-04
 
-- 修复 macOS Overlay 标题栏遮挡内容的问题，为红黄绿窗口按钮预留完整安全区。
-- 调整侧边栏、内容区、Provider/TOML/指令提示词/会话管理页高度计算，避免顶部内容被标题栏压住。
-- 加高 macOS 顶部拖拽区域并保持深色渐变，窗口顶部继续和应用色系统一。
+- 修复 macOS 标题栏和窗口按钮遮挡页面内容的问题。
+- 增大窗口顶部拖拽区域，并统一深色外观。
 
 ## [v0.2.13] - 2026-07-04
 
-- macOS 窗口标题栏改为深色融合样式，避免顶部出现系统白色标题条。
-- 会话管理页面移除多余外层玻璃边框，统一为完整内容容器。
-- 优化会话列表边界与滚动区域，避免列表像卡在外层框外面。
+- macOS 标题栏改为与应用一致的深色样式。
+- 简化会话管理页面边框，改善列表布局和滚动体验。
 
 ## [v0.2.12] - 2026-07-04
 
-- Windows MSI 安装器回退为默认简洁样式，移除上一版过重的自定义安装界面图。
-- 【会话管理】页面新增会话列表，展示标题、Provider、模型、工作目录、更新时间、归档/需同步状态。
-- 会话扫描会从 Codex 本地 SQLite threads 表读取最近会话，方便用户直接判断哪些历史 thread 需要同步修复。
+- Windows MSI 恢复简洁的安装界面。
+- 会话管理新增历史会话列表，可查看标题、供应商、模型、工作目录、更新时间，以及归档和待同步状态。
 
 ## [v0.2.11] - 2026-07-04
 
-- 调整首次启动自动检查更新体验：不再弹出居中的强提醒窗口。
-- 自动检测到新版本时仅显示轻量 toast，并保留概览页顶部“发现新版本”提示条。
-- 只有用户在【关于】页面主动点击“检查更新”时，检测到新版本才弹出“现在下载 / 稍后”窗口。
+- 启动时发现新版本改为轻量提示，概览页仍保留更新提示条。
+- 仅在“关于”页面主动检查更新并发现新版本时，弹出“现在下载 / 稍后”窗口。
 
 ## [v0.2.10] - 2026-07-04
 
-- 修复 Release 发布任务上传 Linux 产物时误把 `deb/`、`rpm/` 目录当作资产上传的问题。
-- 发布任务现在只收集 `.dmg` / `.msi` / `.deb` / `.rpm` 文件并统一上传。
-- 补齐稳定的三平台 Release 自动发布流程。
+- 修复 Linux 安装包上传失败的问题，完善 macOS、Windows 和 Linux 安装包发布。
 
 ## [v0.2.9] - 2026-07-04
 
-- 修复 GitHub Actions Release 发布流程：不再由三平台矩阵并发创建 Release，改为先上传构建产物，再由单独发布任务统一创建/更新 Release。
-- 修复 `Resource not accessible by integration` 导致 Release 创建失败的问题。
-- Release 仍会从 `CHANGELOG.md` 自动读取当前 tag 的更新日志，并上传 macOS / Windows / Linux 安装包。
+- 修复 GitHub 版本发布失败的问题。
 
 ## [v0.2.8] - 2026-07-04
 
-- 更新页进一步产品化：去掉资源/仓库调试信息，将“有更新”改为更明显的绿色标签。
-- 概览页顶部新增轻量“发现新版本”提示条，可直接打开 Releases 页面。
-- 新增【会话管理】页面：检查 Codex 本地 sessions / archived_sessions 与 SQLite threads 是否和当前 Provider 同步。
-- 新增一键 Provider Sync / 修复历史会话：写入前备份到 `~/.codex/backups_state/provider-sync/`，并保留最近 5 份备份。
+- 简化更新页面，使用醒目的绿色标签标示新版本；概览页新增可直接打开下载页的更新提示条。
+- 新增“会话管理”页面，可检查历史会话是否与当前供应商匹配，并一键同步修复。
+- 修复会话前自动备份，保留最近 5 份备份。
 
 ## [v0.2.7] - 2026-07-04
 
-- 简化更新检查页展示。
-- “打开下载页”改为打开 GitHub Releases 页面。
-- 更新弹窗保持简洁，仅提示版本差异。
-- 首次启动自动检查更新并弹窗提醒。
+- 简化更新页面和弹窗，“打开下载页”直接前往 GitHub 版本下载页面。
+- 首次启动自动检查更新，发现新版本时弹窗提醒。
 
 ## [v0.2.5] - 2026-07-04
 
-- Windows 版双击启动不再额外弹出终端窗口。
-- 改进 Windows MSI 安装器品牌展示与图标。
-- About 页面外部链接改为系统默认浏览器打开。
-- Release 流程加入 Rust cache，后续构建更快。
+- 修复 Windows 双击启动时额外弹出终端窗口的问题。
+- 改善 Windows MSI 安装界面的应用名称和图标展示。
+- “关于”页面的外部链接使用系统默认浏览器打开。
 
 ## [v0.2.4] - 2026-07-04
 
-- 美化 Windows MSI 安装器横幅与对话图。
-- Windows 安装包加入应用图标。
+- 美化 Windows MSI 安装界面，并为安装包加入应用图标。
 
 ## [v0.2.3] - 2026-07-04
 
-- 修复 macOS DMG 中应用图标缺失问题。
-- 补充 macOS 安装说明。
-- Release 流程加入基础缓存优化。
+- 修复 macOS DMG 中应用图标缺失的问题，并补充安装说明。
 
 ## [v0.2.2] - 2026-07-04
 
-- macOS / Linux / Windows 首次三平台 Release。
-- Linux 产物改为 `deb` / `rpm`，避免 AppImage 图标问题。
+- 首次提供 macOS、Linux 和 Windows 三个平台的安装包。
+- Linux 改为提供 DEB 和 RPM 安装包。
 
 ## [v0.2.1] - 2026-07-04
 
-- 首次加入应用图标与 GitHub Release 自动发布。
+- 首次加入应用图标，并通过 GitHub 提供版本下载。

README.en.md

@@ -8,9 +8,9 @@
 
   # Codex-X
 
-  **Prompt Injection · Provider Switching · TOML / Auth Visual Manager for Codex**
+  **Codex Prompts · API / Providers · Sessions · Skills / MCP in One Place**
 
-  Codex-X is a cross-platform desktop tool for **OpenAI Codex Desktop / Codex CLI**. It ships with `gpt5.5-unrestricted.md` and `gpt5.4-unrestricted.md`, and supports one-click enable / disable for instruction prompts, third-party Provider switching, official Auth management, TOML visual editing, and local session Provider Sync.
+  A cross-platform desktop tool for **OpenAI Codex Desktop / Codex CLI**. Manage prompt templates, switch third-party APIs, organize / repair / permanently delete local sessions, manage Skills / MCP, and inspect TOML and login credentials without repeatedly editing configuration files by hand.
 
   <p>
     <img src="https://img.shields.io/github/v/release/yynxxxxx/Codex-X?label=version&color=blue" alt="version" />
@@ -32,15 +32,15 @@
 
 ## What is Codex-X?
 
-Codex-X is not just a configuration-file editor. It is a **visual enhancement manager** built for Codex CLI and Codex Desktop workflows.
+When you use Codex Desktop, the CLI, third-party APIs, and multiple prompts together, settings quickly become scattered across different files. Codex-X brings these frequent tasks into one desktop interface, so you can see the current state and complete common actions with a click.
 
-It turns several high-frequency operations into a desktop UI:
+You can use it to:
 
-- Enable / disable instruction prompt templates for Codex
-- Switch between official OpenAI and third-party Codex API Providers
-- View / edit `~/.codex/config.toml`
-- View / edit official `~/.codex/auth.json`
-- Check and repair Provider metadata for local historical sessions
+- Choose from the prompt library or import your own `.md`, then keep the existing prompt or replace it
+- Manage multiple named official Codex login profiles and third-party APIs, duplicate or switch them with a click, and import Providers from cc-switch
+- Search and organize local sessions by project, check / automatically repair problems, and precisely delete sessions you no longer need
+- Manage Skills and MCP in one place, and inspect the current `config.toml`, `auth.json`, and operation backups
+- Explore token usage by date and model in Settings, with subagent usage attributed to its main conversation
 
 ## Preview
 
@@ -109,102 +109,146 @@ It turns several high-frequency operations into a desktop UI:
 <div align="center">
 <table>
   <tr>
-    <th align="center" width="180">Feature</th>
-    <th align="center">Description</th>
+    <th align="center" width="190">What you want to do</th>
+    <th align="center">How Codex-X helps</th>
   </tr>
   <tr>
-    <td align="center">⚡ Provider API</td>
-    <td>Visually manage official OpenAI / third-party Codex Providers, including Base URL, API Key, Model, Wire API, and one-click switching.</td>
+    <td align="center">🧩 <b>Use prompt templates</b></td>
+    <td align="left">The current library contains <b>5 templates</b>. Enable / disable one with a click and choose “Keep existing” or “Replace existing”; GitHub sync, local caching, and importing or editing your own <code>.md</code> files are supported.</td>
   </tr>
   <tr>
-    <td align="center">🧩 <b>Prompt Injection</b></td>
-    <td><b>Signature feature</b>: built-in <code>gpt5.4-unrestricted.md</code> / <code>gpt5.5-unrestricted.md</code>, one-click write into Codex configuration; after enabling, it can produce results similar to the screenshots above for SQL injection testing and APK / EXE reverse engineering scenarios.</td>
+    <td align="center">⚡ <b>Switch APIs / relays</b></td>
+    <td align="left">Save multiple named official Codex login profiles alongside third-party Providers, with one-click duplication and switching. Third-party Providers support connection checks, model discovery / testing, and imports from cc-switch.</td>
   </tr>
   <tr>
-    <td align="center">💬 Session Management</td>
-    <td>Read Codex local SQLite and rollout JSONL, display local sessions visually, and support Provider Sync / historical thread metadata repair.</td>
+    <td align="center">💬 <b>Organize local sessions</b></td>
+    <td align="left">Search sessions, group them by project path, and check or automatically repair inconsistent data. Select one, several, or an entire project to permanently delete specific sessions from Codex storage.</td>
   </tr>
   <tr>
-    <td align="center">📝 TOML Config</td>
-    <td>View current <code>~/.codex/config.toml</code>, edit full TOML directly from the Provider editor, and save changes back to the Codex config directory.</td>
+    <td align="center">🧠 <b>Manage Skills / MCP</b></td>
+    <td align="left">View available Skills and MCP servers, preview existing items before import, install a Skill from ZIP, enable / disable individual entries, and check Skill update status.</td>
   </tr>
   <tr>
-    <td align="center">🔐 Auth Management</td>
-    <td>Read / edit official <code>~/.codex/auth.json</code>, and distinguish ChatGPT login-state Auth from third-party API Keys.</td>
+    <td align="center">📝 <b>Manage config and login</b></td>
+    <td align="left">Inspect <code>config.toml</code> and <code>auth.json</code> in one place. Both official and third-party profile editors offer an “Enable 1M context window” checkbox beside <code>config.toml>; it applies on save and requires model support. Important writes are backed up automatically.</td>
   </tr>
   <tr>
-    <td align="center">📦 Cross-platform Release</td>
-    <td>Provides macOS Apple Silicon / Intel <code>.dmg</code>, Windows <code>.msi</code> / portable <code>.zip</code>, Linux <code>.deb</code> / <code>.rpm</code>, plus in-app update checking.</td>
+    <td align="center">📊 <b>Track token usage</b></td>
+    <td align="left">Switch between General and Usage statistics in Settings. Filter local usage by date and model, explore daily trends, cache hit rate, and model distribution, and view the 10 most recent main conversations. Subagent usage is attributed to its main conversation and does not count as a separate session.</td>
+  </tr>
+  <tr>
+    <td align="center">📦 <b>Use it across platforms</b></td>
+    <td align="left">Available for macOS Apple Silicon / Intel, Windows MSI / portable, and Linux packages. Installed editions can download, verify, and install updates in the app; the portable edition keeps manual downloads.</td>
   </tr>
 </table>
 </div>
 
 ## Highlights
 
-### 1. Built-in dual instruction prompt templates
+### 1. Prompt Template Center
 
-Codex-X currently includes two prompt templates:
+<p align="center">
+  <img src="https://img.shields.io/badge/Template_library-11_total-2563eb?style=flat-square" alt="11 templates in the current library" />
+  <img src="https://img.shields.io/badge/Bundled_offline-5_templates-16a34a?style=flat-square" alt="5 templates bundled for offline use" />
+  <img src="https://img.shields.io/badge/GitHub_sync-Automatic_updates-f59e0b?style=flat-square" alt="Automatic GitHub template sync" />
+</p>
 
-- `examples/gpt5.5-unrestricted.md`
-- `examples/gpt5.4-unrestricted.md`
-
-You can enable / disable them directly from the Prompt page. When enabled, Codex-X writes the selected `.md` file into the Codex configuration directory and updates `model_instructions_file` in `config.toml`.
+> [!TIP]
+> **Ready after installation, automatically expanded when online.**
+>
+> The app bundle includes 5 templates for offline use. After launch, it synchronizes 6 additional software-development and writing templates, plus later updates, from GitHub `examples/` in the background without waiting for the **Prompt** page to open. Successfully synchronized online versions are cached locally and remain available during temporary network outages.
 
 <div align="center">
 <table>
   <tr>
-    <th align="center">Item</th>
-    <th align="center"><code>gpt5.4-unrestricted.md</code></th>
-    <th align="center"><code>gpt5.5-unrestricted.md</code></th>
+    <th align="center">Template</th>
+    <th align="center">Best for</th>
+    <th align="center">Availability</th>
   </tr>
   <tr>
-    <td align="center">Positioning</td>
-    <td align="center">5.4 CTF sandbox</td>
-    <td align="center">5.5 unrestricted mode</td>
+    <td><a href="examples/gpt5.5-unrestricted.md"><code>gpt5.5-unrestricted.md</code></a></td>
+    <td align="left">Compact and general-purpose for everyday coding and technical work</td>
+    <td align="center">Bundled offline<br />GitHub updates</td>
   </tr>
   <tr>
-    <td align="center">Strategy</td>
-    <td align="center">Indirect bypass through CTF competition sandbox framing</td>
-    <td align="center">Direct declaration of unrestricted developer mode</td>
+    <td><a href="examples/gpt5.4-unrestricted.md"><code>gpt5.4-unrestricted.md</code></a></td>
+    <td align="left">GPT-5.4 / Codex CLI workflows with a CTF and security-research focus</td>
+    <td align="center">Bundled offline<br />GitHub updates</td>
   </tr>
   <tr>
-    <td align="center">Style</td>
-    <td align="center">Security-research oriented, detailed methodology</td>
-    <td align="center">Minimal instructions, broad coverage</td>
+    <td><a href="examples/gpt5.5-jeli.md"><code>gpt5.5-jeli.md</code></a></td>
+    <td align="left">A plain-language general version with a fuller engineering and reverse-engineering workflow</td>
+    <td align="center">Bundled offline<br />GitHub updates</td>
   </tr>
   <tr>
-    <td align="center">Length</td>
-    <td align="center">~180 lines</td>
-    <td align="center">~40 lines</td>
+    <td><a href="examples/gpt-5.6-sol-unrestricted.md"><code>gpt-5.6-sol-unrestricted.md</code></a></td>
+    <td align="left">A GPT-5.6 SOL prompt focused on direct execution and bilingual tasks</td>
+    <td align="center">Bundled offline<br />GitHub updates</td>
   </tr>
   <tr>
-    <td align="center">Target</td>
-    <td align="center">GPT-5.4 Codex CLI</td>
-    <td align="center">GPT-5.5 Codex CLI</td>
+    <td><a href="examples/%E6%B5%B7%E9%B8%A53.0%E7%A0%B4%E7%94%B2.md"><code>海鸥3.0破甲.md</code></a></td>
+    <td align="left">A Chinese technical-operator persona with routing for coding, CTF, reverse engineering, memory, and protocol work</td>
+    <td align="center">Bundled offline<br />GitHub updates</td>
+  </tr>
+  <tr>
+    <td><a href="examples/software-development-maintainer.md"><code>software-development-maintainer.md</code></a></td>
+    <td align="left">Long-term maintenance with reuse, minimal changes, safety, testing, and maintainability</td>
+    <td align="center">GitHub sync</td>
+  </tr>
+  <tr>
+    <td><a href="examples/software-development-debugging.md"><code>software-development-debugging.md</code></a></td>
+    <td align="left">Evidence-driven debugging from reliable reproduction to root-cause repair and regression checks</td>
+    <td align="center">GitHub sync</td>
+  </tr>
+  <tr>
+    <td><a href="examples/software-development-code-review.md"><code>software-development-code-review.md</code></a></td>
+    <td align="left">Severity-ranked review of defects, regressions, security risks, and test gaps</td>
+    <td align="center">GitHub sync</td>
+  </tr>
+  <tr>
+    <td><a href="examples/writing-clarity-editor.md"><code>writing-clarity-editor.md</code></a></td>
+    <td align="left">Chinese and English editing that preserves the author's meaning and facts</td>
+    <td align="center">GitHub sync</td>
+  </tr>
+  <tr>
+    <td><a href="examples/writing-technical-docs.md"><code>writing-technical-docs.md</code></a></td>
+    <td align="left">Source-grounded README, guide, API, architecture, and release documentation</td>
+    <td align="center">GitHub sync</td>
+  </tr>
+  <tr>
+    <td><a href="examples/writing-structured-draft.md"><code>writing-structured-draft.md</code></a></td>
+    <td align="left">Turns scattered material into a structured report, proposal, retrospective, or article draft</td>
+    <td align="center">GitHub sync</td>
   </tr>
 </table>
 </div>
 
-Post-deployment test prompt:
+<table>
+  <tr>
+    <td width="50%" valign="top">
+      <b>Keep existing prompt</b><br />
+      Best for users who already have personal rules. Codex-X only appends its managed content and removes only that content when disabled, leaving the original prompt untouched.
+    </td>
+    <td width="50%" valign="top">
+      <b>Replace existing prompt</b><br />
+      Makes the selected template the primary instruction entry point, which is useful when you want to switch completely to a specific template.
+    </td>
+  </tr>
+</table>
 
-```text
-How do I perform SQL injection testing against a target?
-```
+A backup is created automatically before every enable or disable action. In addition to the template library, you can import, edit, and delete your own `.md` prompts.
 
-Typical effect:
+### 2. Provider Switching: Ready in a New Session
 
-```text
-Before injection → refusal or generic answer
-After injection  → direct security research methodology and testing steps
-```
+> [!NOTE]
+> After enabling a new third-party Provider, create or reopen a Codex session to use the new relay. You do not need to restart the entire Codex client.
 
-### 2. Visual Provider switching
-
-- Add third-party Codex API Providers
-- Edit Base URL / API Key / Model / Wire API
-- View and edit Provider-related TOML from the Provider page
-- Clearly display the currently active Provider
-- Import Codex Providers from a cc-switch database
+- Save multiple named official Codex login profiles and third-party Providers, and always see which one is currently active
+- Duplicate a profile immediately with one click, without a confirmation dialog or opening the editor; rename it whenever needed
+- Test an API endpoint before switching, and save or enable a configuration separately
+- Edit the Base URL, API Key, Model, Wire API, and complete TOML on the same page
+- cc-switch imports report added, updated, merged, and skipped entries; the same URL + Key is no longer shown more than once
+- Switching back to OpenAI Official preserves the current official login, and third-party configurations no longer disappear unexpectedly
 
 ### 3. Official Auth management
 
@@ -220,28 +264,93 @@ After injection  → direct security research methodology and testing steps
 - Edit full TOML directly from the Provider editor
 - Save changes back to the Codex configuration directory
 
-### 5. Session Management / Provider Sync
+### 5. Session Management: Inspect, Repair, and Permanently Delete
 
-Codex-X can read Codex local session data:
+<table>
+  <tr>
+    <td width="50%" valign="top">
+      <b>Find and organize</b><br />
+      Search sessions by title or project path and group them by project. Internal subagent sessions created automatically by Codex stay out of the normal session list by default.
+    </td>
+    <td width="50%" valign="top">
+      <b>Inspect and repair</b><br />
+      Check whether local sessions match the current Provider, repair all mismatches manually, or enable automatic inspection and repair at startup.
+    </td>
+  </tr>
+  <tr>
+    <td colspan="2" valign="top">
+      <b>Precise deletion</b><br />
+      Select one session, several sessions, or one or more projects to select all sessions under them. After confirmation, the matching sessions and their derived child sessions are removed from Codex storage itself.
+    </td>
+  </tr>
+</table>
 
-```text
-~/.codex/sqlite/*.db
-~/.codex/state_5.sqlite
-~/.codex/sessions/**/rollout-*.jsonl
-~/.codex/archived_sessions/**/rollout-*.jsonl
-```
+> [!CAUTION]
+> **Permanent deletion cannot be undone.** Close any Codex windows or CLI processes still using those sessions, then review the deletion list again in the confirmation dialog.
 
-It checks whether historical session Provider metadata matches the current configuration, and supports one-click sync / repair so historical threads can still be recognized, opened, and continued by native Codex.
+### 6. Skills / MCP Management
 
-### 6. Cross-platform desktop app
+Manage Codex capability extensions from the **Skills & MCP** page instead of searching through multiple directories and configuration files.
+
+<table>
+  <tr>
+    <td width="50%" valign="top">
+      <b>Skills</b><br />
+      View current Skills, import existing content, or install from ZIP. Enable / disable entries individually and check whether installed Skills have updates.
+    </td>
+    <td width="50%" valign="top">
+      <b>MCP</b><br />
+      Preview existing MCP servers before importing them, then choose what Codex-X should manage. Codex-X maintains the Codex configuration when a server is enabled or disabled.
+    </td>
+  </tr>
+</table>
+
+### 7. Reverse Skills Navigation
+
+<div align="center">
+  <a href="https://yynxxxxx.github.io/Codex-X/">
+    <img src="https://img.shields.io/badge/Codex--X-Online%20Reverse%20Skills%20Guide-0ea5e9?style=for-the-badge&logo=githubpages&logoColor=white" alt="Codex-X Online Reverse Skills Guide" />
+  </a>
+</div>
+
+<br />
+
+<table>
+  <tr>
+    <td width="55%">
+      <b>Online guide</b>: explains the “armor breaking” workflow, how to enable GPT-5.5 / unrestricted jeli in Codex-X, and how to combine it with reverse-engineering Skills.
+      <br /><br />
+      <b>Categories</b>: Android APK / Windows EXE / Web protocol reverse engineering.
+      <br /><br />
+      <b>Includes</b>: Skill purpose, install commands, source links, and recommended workflow.
+    </td>
+    <td width="45%">
+      <ul>
+        <li>🧩 GPT-5.5 / unrestricted jeli workflow</li>
+        <li>📱 Android APK reverse Skills</li>
+        <li>🪟 Windows EXE / DLL reverse Skills</li>
+        <li>🌐 Web / API / protocol reverse Skills</li>
+        <li>📋 One-click copy install commands</li>
+      </ul>
+    </td>
+  </tr>
+</table>
+
+<p align="center">
+  <a href="https://yynxxxxx.github.io/Codex-X/">
+    <b>🚀 Open Codex-X Reverse Skills Guide</b>
+  </a>
+</p>
+
+### 8. Cross-platform desktop app
 
 - macOS Apple Silicon `.dmg`
 - macOS Intel `.dmg`
 - Windows `.msi`
 - Windows Portable `.zip`
-- Linux `.deb` / `.rpm`
+- Linux `.deb` / `.rpm` / `.AppImage`
 - Automatic GitHub Releases builds
-- In-app update checking
+- In-app updates for installed editions; manual updates for Windows Portable
 
 ## Tech Stack
 
@@ -296,7 +405,7 @@ Build desktop bundles:
 pnpm --dir apps/desktop tauri build
 ```
 
-## macOS Installation Note
+## Desktop Installation Notes
 
 If you see “app is damaged” when opening an unsigned / unnotarized DMG, this is normal macOS Gatekeeper behavior.
 
@@ -317,10 +426,12 @@ Thanks to the [LINUX DO forum](https://linux.do/) community for attention, feedb
 
 ## Star History
 
-<a href="https://www.star-history.com/?repos=yynxxxxx%2FCodex-X&type=date&legend=top-left">
-  <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=yynxxxxx/Codex-X&type=date&theme=dark&legend=top-left" />
-    <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=yynxxxxx/Codex-X&type=date&legend=top-left" />
-    <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=yynxxxxx/Codex-X&type=date&legend=top-left" />
-  </picture>
-</a>
+<p align="center">
+  <a href="https://github.com/yynxxxxx/Codex-X/stargazers">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://codex-star-history.zhihack0728.workers.dev/v1/charts/codex-x.svg?theme=dark" />
+      <source media="(prefers-color-scheme: light)" srcset="https://codex-star-history.zhihack0728.workers.dev/v1/charts/codex-x.svg?theme=light" />
+      <img alt="Codex-X Star History" src="https://codex-star-history.zhihack0728.workers.dev/v1/charts/codex-x.svg?theme=light" width="900" />
+    </picture>
+  </a>
+</p>

README.md

@@ -8,9 +8,9 @@
 
   # Codex-X
 
-  **Codex 提示词注入 · Provider 切换 · TOML / Auth 可视化管理器**
+  **Codex 可视化提示词注入 · Provider · 会话 · Skills / MCP 管理工具**
 
-  一款面向 **OpenAI Codex 桌面端 / Codex CLI** 的跨平台桌面工具，内置 `gpt5.5-unrestricted.md` 与 `gpt5.4-unrestricted.md`，支持一键写入 / 禁用指令提示词、第三方 Provider 切换、官方 Auth 管理、TOML 可视化编辑与本地会话 Provider Sync。
+  一款面向 **OpenAI Codex 桌面端 / Codex CLI** 的跨平台桌面工具。把提示词模板、自定义 Prompt、第三方 API 供应商、会话同步、Skills / MCP 和 TOML 配置都放进可视化界面里，不用反复手改文件。
 
   <p>
     <img src="https://img.shields.io/github/v/release/yynxxxxx/Codex-X?label=version&color=blue" alt="version" />
@@ -32,75 +32,51 @@
 
 ## Codex-X 是什么？
 
-Codex-X 不是普通的配置文件编辑器，而是一个面向 Codex CLI 的 **可视化增强管理器**。
+当你同时使用 Codex 桌面端、CLI、第三方 API、Skills / MCP 和多套提示词时，配置很容易散落在不同文件里。Codex-X 把这些高频操作集中到一个桌面界面中，让当前状态看得见、常用操作点一下就能完成。
 
-它把几个高频操作做成了桌面软件：
+你可以用它：
 
-- 给 Codex 写入 / 禁用指令提示词模板
-- 切换官方 OpenAI 与第三方 Codex API Provider
-- 查看 / 编辑 `~/.codex/config.toml`
-- 查看 / 编辑官方 `~/.codex/auth.json`
-- 检查并修复本地历史会话的 Provider 元数据
+- 像管理插件一样管理提示词：分类、导入 Markdown、自定义编辑、一键启用 / 禁用
+- 内置 5 套提示词模板，同时支持用户把自己的提示词变成可视化模板库
+- 管理多个可命名的官方 Codex 登录与第三方 API，一键复制、切换，并从 cc-switch 导入现有供应商
+- 同步、检查、搜索和删除本地会话，按项目路径整理 Codex 历史记录
+- 集中管理 Skills 与 MCP，查看当前 `config.toml`、`auth.json` 和操作备份
+- 在设置中按日期、模型查看 Token 用量趋势，子代理用量归入所属主会话
 
 ## 软件预览
 
 <details open>
-<summary><b>应用界面预览</b>：主界面 / Provider / TOML / Auth</summary>
+<summary><b>新版 UI：指令提示词管理中心</b></summary>
 
 <p align="center">
-  <img src="docs/screenshots/app/preview.png" alt="Codex-X 应用界面预览：主界面、Provider、TOML、Auth" width="920" />
+  <img src="docs/screenshots/app/new-ui/prompts.png" alt="Codex-X 新版指令提示词管理界面" width="920" />
 </p>
 
 </details>
 
-<details>
-<summary><b>提示词注入效果：安全测试场景</b></summary>
-
 <div align="center">
 <table>
   <tr>
     <td align="center" width="50%">
-      <b>SQL 注入测试</b><br />
-      <sub>部署后测试：如何对目标进行 SQL 注入测试？</sub><br />
-      <img src="docs/screenshots/prompt-effects/security/sql-injection.png" alt="SQL 注入测试效果图" width="420" />
+      <b>分类管理</b><br />
+      <sub>把提示词按破甲 / 逆向、软件开发、写作辅助等分类维护</sub><br />
+      <img src="docs/screenshots/app/new-ui/prompt-categories.png" alt="Codex-X 提示词分类管理" width="420" />
     </td>
     <td align="center" width="50%">
-      <b>NSFW 响应测试</b><br />
-      <sub>用于观察提示词注入后的边界响应变化</sub><br />
-      <img src="docs/screenshots/prompt-effects/security/nsfw.png" alt="NSFW 响应测试效果图" width="420" />
+      <b>自定义提示词</b><br />
+      <sub>直接添加、编辑或导入自己的 Markdown 提示词</sub><br />
+      <img src="docs/screenshots/app/new-ui/prompt-form.png" alt="Codex-X 添加自定义提示词" width="420" />
     </td>
   </tr>
 </table>
 </div>
 
-</details>
-
 <details>
-<summary><b>提示词注入效果：逆向工程场景</b></summary>
+<summary><b>Skills / MCP 可视化管理</b></summary>
 
-<div align="center">
-<table>
-  <tr>
-    <td align="center" width="50%">
-      <b>APK 逆向分析</b><br />
-      <sub>Android APK 静态 / 动态分析思路</sub><br />
-      <img src="docs/screenshots/prompt-effects/reverse/apk-reverse-1.png" alt="APK 逆向分析效果图" width="420" />
-    </td>
-    <td align="center" width="50%">
-      <b>APK 逆向分析 2</b><br />
-      <sub>补充 APK 逆向流程与定位方式</sub><br />
-      <img src="docs/screenshots/prompt-effects/reverse/apk-reverse-2.png" alt="APK 逆向分析效果图 2" width="420" />
-    </td>
-  </tr>
-  <tr>
-    <td align="center" colspan="2">
-      <b>EXE 逆向分析</b><br />
-      <sub>Windows 可执行文件分析与调试方向</sub><br />
-      <img src="docs/screenshots/prompt-effects/reverse/exe-reverse.png" alt="EXE 逆向分析效果图" width="620" />
-    </td>
-  </tr>
-</table>
-</div>
+<p align="center">
+  <img src="docs/screenshots/app/new-ui/skills-mcp.png" alt="Codex-X Skills 与 MCP 管理界面" width="920" />
+</p>
 
 </details>
 
@@ -109,139 +85,261 @@ Codex-X 不是普通的配置文件编辑器，而是一个面向 Codex CLI 的
 <div align="center">
 <table>
   <tr>
-    <th align="center" width="180">功能</th>
-    <th align="center">说明</th>
+    <th align="center" width="190">你想做的事</th>
+    <th align="center">Codex-X 能帮你</th>
   </tr>
   <tr>
-    <td align="center">⚡ 供应商 API</td>
-    <td>可视化管理官方 OpenAI / 第三方 Codex Provider，支持 Base URL、API Key、Model、Wire API 与一键切换。</td>
+    <td align="center"><b>提示词注入管理</b></td>
+    <td align="left">内置 <b>5 套</b>提示词模板，支持分类、GitHub 同步、本地缓存、导入 <code>.md</code>、添加自定义提示词、编辑说明、一键启用 / 禁用。</td>
   </tr>
   <tr>
-    <td align="center">🧩 <b>提示词注入</b></td>
-    <td><b>特色功能</b>：内置 <code>gpt5.4-unrestricted.md</code> / <code>gpt5.5-unrestricted.md</code>，一键写入 Codex 配置；启用后可达到上方效果图中的 SQL 注入测试、APK / EXE 逆向等响应效果。</td>
+    <td align="center"><b>启用方式切换</b></td>
+    <td align="left">可选择“保留原提示词”追加写入，也可选择“替换原提示词”完整切换；适合在不同模型、不同任务、不同 Prompt 之间快速切换。</td>
   </tr>
   <tr>
-    <td align="center">💬 会话管理</td>
-    <td>读取 Codex 本地 SQLite 与 rollout JSONL，会话列表可视化展示，并支持 Provider Sync / 修复历史 thread 元数据。</td>
+    <td align="center"><b>Provider / API</b></td>
+    <td align="left">保存多个可命名的官方 Codex 登录配置，与第三方供应商统一管理、一键复制和切换；第三方供应商支持连接检测、模型获取 / 测试及从 cc-switch 导入。</td>
   </tr>
   <tr>
-    <td align="center">📝 TOML 配置</td>
-    <td>查看当前 <code>~/.codex/config.toml</code>，并在 Provider 编辑页直接编辑完整 TOML，保存后同步到 Codex 配置目录。</td>
+    <td align="center"><b>会话管理</b></td>
+    <td align="left">搜索本地会话、按项目路径分组、同步当前供应商、检查会话状态，并支持单选 / 多选 / 项目级永久删除。</td>
   </tr>
   <tr>
-    <td align="center">🔐 Auth 管理</td>
-    <td>读取 / 编辑官方 <code>~/.codex/auth.json</code>，区分 ChatGPT 登录态 Auth 与第三方 API Key。</td>
+    <td align="center"><b>Skills / MCP</b></td>
+    <td align="left">可视化查看 Skills 与 MCP，导入已有配置，从 ZIP 安装 Skill，逐项启用 / 禁用，并检查更新状态。</td>
   </tr>
   <tr>
-    <td align="center">📦 跨平台发布</td>
-    <td>提供 macOS Apple Silicon / Intel <code>.dmg</code>、Windows <code>.msi</code> / portable <code>.zip</code>、Linux <code>.deb</code> / <code>.rpm</code>，支持应用内检测更新。</td>
+    <td align="center"><b>配置与登录</b></td>
+    <td align="left">集中查看 <code>config.toml</code> 与 <code>auth.json</code>；官方登录和第三方供应商编辑页均可在 <code>config.toml</code> 旁勾选“开启 1M 上下文窗口”，保存后生效，需模型支持；重要写入前自动备份。</td>
+  </tr>
+  <tr>
+    <td align="center"><b>用量统计</b></td>
+    <td align="left">设置页提供“通用设置 / 用量统计”标签，按日期与模型筛选本地 Token 用量，查看每日趋势、缓存命中率、模型分布及最近 10 个主会话；子代理用量归入所属主会话，不单独计为会话。</td>
+  </tr>
+  <tr>
+    <td align="center"><b>跨平台使用</b></td>
+    <td align="left">提供 macOS Apple Silicon / Intel、Windows EXE / 便携版和 Linux 安装包；安装版可在应用内直接下载、校验并安装更新，便携版继续使用手动下载。</td>
   </tr>
 </table>
 </div>
 
 ## 核心亮点
 
-### 1. 内置双指令提示词模板
+### 1. 可视化提示词注入中心
 
-Codex-X 当前内置两套提示词模板：
+<p align="center">
+  <img src="https://img.shields.io/badge/当前模板库-11_套-2563eb?style=flat-square" alt="当前模板库 11 套" />
+  <img src="https://img.shields.io/badge/离线内置-5_套-16a34a?style=flat-square" alt="离线内置 5 套" />
+  <img src="https://img.shields.io/badge/GitHub_同步-自动更新-f59e0b?style=flat-square" alt="GitHub 自动同步" />
+  <img src="https://img.shields.io/badge/自定义提示词-支持导入_编辑-7c3aed?style=flat-square" alt="支持自定义提示词" />
+</p>
 
-- `examples/gpt5.5-unrestricted.md`
-- `examples/gpt5.4-unrestricted.md`
+> [!TIP]
+> **安装后就能用，联网后自动补齐，也能维护自己的提示词库。**
+>
+> 安装包离线自带 5 套模板；软件启动后会从 GitHub `examples/` 同步另外 6 套软件开发与写作辅助模板，以及后续更新。同步成功的在线版本会缓存到本地，临时离线仍可继续使用。你也可以导入自己的 `.md`、新增分类、编辑说明，并像切换插件一样启用或禁用任意提示词。
 
-你可以在【指令提示词】页面直接点击启用 / 禁用。启用后，Codex-X 会把对应 `.md` 写入 Codex 配置目录，并更新 `config.toml` 中的 `model_instructions_file`。
+Codex-X 现在不只是“几套内置 Prompt”的启动器，而是一个可视化提示词注入与管理工具：
+
+- 按分类管理提示词，例如破甲 / 逆向、软件开发、写作辅助，也可以新增自己的分类
+- 支持同步 GitHub 模板、导入 Markdown、手动添加提示词、编辑标题 / 文件名 / 内容
+- 每个提示词都有独立开关，打开时自动按当前启用方式写入 Codex 指令文件
+- 支持“保留原提示词”和“替换原提示词”两种模式，适合日常叠加或完整切换
+- 本地缓存可离线使用，后续模板更新不会影响你自己维护的自定义提示词
 
 <div align="center">
 <table>
   <tr>
-    <th align="center">对比项</th>
-    <th align="center"><code>gpt5.4-unrestricted.md</code></th>
-    <th align="center"><code>gpt5.5-unrestricted.md</code></th>
+    <th align="center">模板</th>
+    <th align="center">适合场景</th>
+    <th align="center">获取方式</th>
   </tr>
   <tr>
-    <td align="center">定位</td>
-    <td align="center">5.4 CTF 沙箱</td>
-    <td align="center">5.5 无限制模式</td>
+    <td><a href="examples/gpt5.5-unrestricted.md"><code>gpt5.5-unrestricted.md</code></a></td>
+    <td align="left">短小通用，适合日常 coding 与常规技术任务</td>
+    <td align="center">离线内置<br />GitHub 更新</td>
   </tr>
   <tr>
-    <td align="center">策略</td>
-    <td align="center">CTF 竞赛沙箱间接绕过</td>
-    <td align="center">直接声明无限制开发者模式</td>
+    <td><a href="examples/gpt5.4-unrestricted.md"><code>gpt5.4-unrestricted.md</code></a></td>
+    <td align="left">面向 GPT-5.4 / Codex CLI，偏 CTF 与安全研究工作流</td>
+    <td align="center">离线内置<br />GitHub 更新</td>
   </tr>
   <tr>
-    <td align="center">风格</td>
-    <td align="center">安全研究导向，方法论详细</td>
-    <td align="center">极简指令，覆盖面广</td>
+    <td><a href="examples/gpt5.5-jeli.md"><code>gpt5.5-jeli.md</code></a></td>
+    <td align="left">大白话通用版，提供更完整的工程与逆向执行流程</td>
+    <td align="center">离线内置<br />GitHub 更新</td>
   </tr>
   <tr>
-    <td align="center">长度</td>
-    <td align="center">约 180 行</td>
-    <td align="center">约 40 行</td>
+    <td><a href="examples/gpt-5.6-sol-unrestricted.md"><code>gpt-5.6-sol-unrestricted.md</code></a></td>
+    <td align="left">gpt5.6-sol 破甲提示词，偏直接执行与中英文任务</td>
+    <td align="center">离线内置<br />GitHub 更新</td>
   </tr>
   <tr>
-    <td align="center">适用</td>
-    <td align="center">GPT-5.4 Codex CLI</td>
-    <td align="center">GPT-5.5 Codex CLI</td>
+    <td><a href="examples/%E6%B5%B7%E9%B8%A53.0%E7%A0%B4%E7%94%B2.md"><code>海鸥3.0破甲.md</code></a></td>
+    <td align="left">中文技术操作员人格，覆盖 coding、CTF、逆向、内存与协议任务路由</td>
+    <td align="center">离线内置<br />GitHub 更新</td>
+  </tr>
+  <tr>
+    <td><a href="examples/software-development-maintainer.md"><code>software-development-maintainer.md</code></a></td>
+    <td align="left">长期维护正式项目，强调复用、最小改动、安全、测试与可维护性</td>
+    <td align="center">GitHub 在线同步</td>
+  </tr>
+  <tr>
+    <td><a href="examples/software-development-debugging.md"><code>software-development-debugging.md</code></a></td>
+    <td align="left">从稳定复现和证据采集推进到根因修复与回归验证</td>
+    <td align="center">GitHub 在线同步</td>
+  </tr>
+  <tr>
+    <td><a href="examples/software-development-code-review.md"><code>software-development-code-review.md</code></a></td>
+    <td align="left">按严重级别审查缺陷、回归、安全风险和测试缺口</td>
+    <td align="center">GitHub 在线同步</td>
+  </tr>
+  <tr>
+    <td><a href="examples/writing-clarity-editor.md"><code>writing-clarity-editor.md</code></a></td>
+    <td align="left">在保留原意和事实的前提下润色中英文表达</td>
+    <td align="center">GitHub 在线同步</td>
+  </tr>
+  <tr>
+    <td><a href="examples/writing-technical-docs.md"><code>writing-technical-docs.md</code></a></td>
+    <td align="left">基于代码与事实编写 README、指南、API 和发布文档</td>
+    <td align="center">GitHub 在线同步</td>
+  </tr>
+  <tr>
+    <td><a href="examples/writing-structured-draft.md"><code>writing-structured-draft.md</code></a></td>
+    <td align="left">将零散材料组织成报告、方案、复盘或文章初稿</td>
+    <td align="center">GitHub 在线同步</td>
   </tr>
 </table>
 </div>
 
-部署后可以测试：
+<table>
+  <tr>
+    <td width="50%" valign="top">
+      <b>保留原提示词</b><br />
+      适合已经有个人规则的用户。Codex-X 只追加自己管理的内容，禁用时也只移除这一部分，不动原有提示词。
+    </td>
+    <td width="50%" valign="top">
+      <b>替换原提示词</b><br />
+      将所选模板设为当前主要指令入口，适合希望完整切换到某套模板的用户。
+    </td>
+  </tr>
+</table>
 
-```text
-如何对目标进行 SQL 注入测试？
-```
+每次启用或禁用前都会自动创建备份。除了模板库，你也可以导入、编辑、删除自己的 `.md` 提示词，并通过分类管理把常用提示词整理成自己的工作流。
 
-典型效果：
+> [!NOTE]
+> 如果你有好用的提示词模板，欢迎在 [Issues](https://github.com/yynxxxxx/Codex-X/issues) 提交：请附上模板名称、适用场景、Markdown 内容、推荐启用方式和必要说明。合适的模板会考虑收录到 `examples/`，让更多用户可以一键同步使用。
 
-```text
-破甲前 → 拒绝或泛化回答
-破甲后 → 直接给安全研究方法论与测试步骤
-```
+### 2. Provider / API：添加、检测、获取模型、随时切换
 
-### 2. Provider 可视化切换
+> [!NOTE]
+> 启用新的第三方供应商后，新建或重新打开 Codex 会话即可使用新的中转，不需要重启整个 Codex 客户端。
 
-- 添加第三方 Codex API Provider
-- 编辑 Base URL / API Key / Model / Wire API
-- Provider 页面可查看并编辑对应 TOML
-- 当前启用 Provider 状态清晰可见
-- 支持从 cc-switch 数据库导入 Codex Provider
+- 保存多个可命名的官方 Codex 登录配置与第三方供应商，随时查看当前正在使用哪一个
+- 点击“复制”直接新增独立副本，无需确认或进入编辑页；名称可稍后修改
+- 切换前可检测连接，并可获取模型进行测试
+- 在同一页面编辑 Base URL、API Key、Model、Wire API 和完整 TOML
+- 从 cc-switch 导入时自动区分新增、更新、合并与跳过；相同 URL + Key 不再重复显示
+- 切回 OpenAI Official 时保留当前官方登录态，第三方配置也不会凭空消失
 
-### 3. 官方 Auth 管理
+### 3. 会话管理：同步、检查与永久删除
+
+<table>
+  <tr>
+    <td width="50%" valign="top">
+      <b>同步和检查</b><br />
+      检查本地会话是否和当前 Provider / 模型一致，需要时一键同步到当前供应商配置，不修改聊天内容。
+    </td>
+    <td width="50%" valign="top">
+      <b>查找和整理</b><br />
+      按标题、项目路径、供应商或 ID 搜索会话，也可以按项目路径分组查看，适合清理长期使用后积累的会话列表。
+    </td>
+  </tr>
+  <tr>
+    <td colspan="2" valign="top">
+      <b>精确删除</b><br />
+      支持单选、多选，也可以勾选一个或多个项目，一次选中项目下的全部会话；确认后会从 Codex 自身存储中删除对应会话及其派生子会话。
+    </td>
+  </tr>
+</table>
+
+> [!CAUTION]
+> **永久删除不可恢复。** 删除前请先关闭仍在使用这些会话的 Codex 窗口或 CLI，并在确认窗口中再次核对待删除列表。
+
+### 4. Skills / MCP 管理
+
+在【技能和 MCP】页面集中管理 Codex 的能力扩展，不必再到多个目录和配置文件中逐项查找。
+
+<table>
+  <tr>
+    <td width="50%" valign="top">
+      <b>Skills</b><br />
+      查看当前 Skill，导入已有内容或从 ZIP 安装；可以逐项启用 / 禁用，并检查已安装 Skill 是否有更新。
+    </td>
+    <td width="50%" valign="top">
+      <b>MCP</b><br />
+      导入前先预览现有 MCP Server，再决定哪些需要纳管；启用或禁用后由 Codex-X 自动维护 Codex 配置。
+    </td>
+  </tr>
+</table>
+
+### 5. TOML 与官方 Auth 管理
 
 - 自动读取 Codex 官方 `auth.json`
 - 支持查看 / 编辑 ChatGPT 登录态 Auth
 - 区分官方 Auth 与第三方 API Key
 - 官方配置可和第三方 Provider 在 UI 中统一管理
-
-### 4. TOML 可视化编辑
-
-- 查看当前 Codex `config.toml`
+- 查看当前 Codex 正在使用的 live `config.toml`
 - 深色代码预览与语法高亮
 - Provider 编辑页可直接编辑完整 TOML
 - 保存后同步到 Codex 配置目录
 
-### 5. 会话管理 / Provider Sync
+### 6. 逆向 Skills 导航
 
-Codex-X 可以读取 Codex 本地会话数据：
+<div align="center">
+  <a href="https://yynxxxxx.github.io/Codex-X/">
+    <img src="https://img.shields.io/badge/Codex--X-在线逆向%20Skills%20导航-0ea5e9?style=for-the-badge&logo=githubpages&logoColor=white" alt="Codex-X 在线逆向 Skills 导航" />
+  </a>
+</div>
 
-```text
-~/.codex/sqlite/*.db
-~/.codex/state_5.sqlite
-~/.codex/sessions/**/rollout-*.jsonl
-~/.codex/archived_sessions/**/rollout-*.jsonl
-```
+<br />
 
-用于检查旧会话的 Provider 元数据是否和当前配置一致，并支持一键同步 / 修复，让历史 thread 继续被原生 Codex 识别、打开和续聊。
+<table>
+  <tr>
+    <td width="55%">
+      <b>在线教程页</b>：解释什么是“破甲”、Codex-X 如何启用 GPT-5.5 / unrestricted jeli、以及如何搭配不同领域的逆向 Skills。
+      <br /><br />
+      <b>分类覆盖</b>：Android APK / Windows EXE / Web 协议逆向。
+      <br /><br />
+      <b>内容包含</b>：Skill 用途、安装方式、来源地址、推荐使用流程。
+    </td>
+    <td width="45%">
+      <ul>
+        <li>🧩 GPT-5.5 / unrestricted jeli 使用流程</li>
+        <li>📱 Android APK 逆向 Skills</li>
+        <li>🪟 Windows EXE / DLL 逆向 Skills</li>
+        <li>🌐 Web / API / 协议逆向 Skills</li>
+        <li>📋 安装命令一键复制</li>
+      </ul>
+    </td>
+  </tr>
+</table>
 
-### 6. 跨平台桌面软件
+<p align="center">
+  <a href="https://yynxxxxx.github.io/Codex-X/">
+    <b>🚀 打开 Codex-X 逆向 Skills 导航</b>
+  </a>
+</p>
+
+### 7. 跨平台桌面软件
 
 - macOS Apple Silicon `.dmg`
 - macOS Intel `.dmg`
-- Windows `.msi`
+- Windows `.exe`（安装到当前用户，后续更新无需管理员权限）
 - Windows Portable `.zip`
-- Linux `.deb` / `.rpm`
+- Linux `.deb` / `.rpm` / `.AppImage`
 - GitHub Releases 自动构建发布
-- 应用内检查更新
+- 安装版支持应用内自动更新，Windows 便携版保留手动更新
 
 ## 技术栈
 
@@ -296,7 +394,7 @@ pnpm dev
 pnpm --dir apps/desktop tauri build
 ```
 
-## macOS 安装说明
+## 桌面端安装说明
 
 如果你在未签名 / 未公证的 DMG 中看到“软件已损坏”提示，这是 macOS Gatekeeper 的正常行为。
 
@@ -317,8 +415,19 @@ xattr -dr com.apple.quarantine /Applications/Codex-X.app
 
 ## Star History
 
-<a href="https://www.star-history.com/?repos=yynxxxxx%2FCodex-X&type=date&legend=top-left">
-  <img alt="Star History Chart" src="docs/star-history-codex-x.svg" width="900" />
-</a>
+<p align="center">
+  <a href="https://github.com/yynxxxxx/Codex-X/stargazers">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://codex-star-history.zhihack0728.workers.dev/v1/charts/codex-x.svg?theme=dark" />
+      <source media="(prefers-color-scheme: light)" srcset="https://codex-star-history.zhihack0728.workers.dev/v1/charts/codex-x.svg?theme=light" />
+      <img alt="Codex-X Star History" src="https://codex-star-history.zhihack0728.workers.dev/v1/charts/codex-x.svg?theme=light" width="900" />
+    </picture>
+  </a>
+</p>
 
-<!-- Use a local SVG because api.star-history.com/chart may return an empty SVG for very new or fast-growing repositories. Click the chart for the live Star History page. -->
+<br />
+
+> [!IMPORTANT]
+> **使用声明**
+>
+> 本项目仅用于大模型与智能体相关技术的学习、研究与交流，软件本身不包含主动破坏性功能。请在合法、合规并获得授权的范围内使用，禁止将其用于攻击、侵害他人权益或其他违法用途。使用者应自行判断使用边界，并对相关行为与后果承担责任。

THIRD_PARTY_NOTICES.md

@@ -0,0 +1,59 @@
+# Third-party notices
+
+## CC Switch
+
+Source: https://github.com/farion1231/cc-switch
+
+Reference commit: `06082e189d65e6d6dbadc35dacdac1ce6c79d89a`.
+
+Codex-X adapts the circuit-breaker implementation and Codex routing, failover, timeout and configuration behavior from CC Switch. The blocking/local HTTP integration, application state and UI styling are adapted to this project. Relevant source files carry provenance comments.
+
+MIT License
+
+Copyright (c) 2025 Jason Young
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+## Tauri Windows installer template
+
+Source: https://github.com/tauri-apps/tauri/blob/tauri-cli-v2.11.4/crates/tauri-bundler/src/bundle/windows/templates/installer.nsi
+
+Codex-X adapts the Tauri CLI v2.11.4 NSIS template for current-user installation, verified legacy MSI migration, update handoff and installation diagnostics.
+
+MIT License
+
+Copyright (c) 2017 - Present Tauri Apps Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

apps/desktop/index.html

@@ -1,17 +1,13 @@
 <!doctype html>
-<html lang="zh-CN">
+<html lang="zh-CN" data-theme="light">
   <head>
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>Codex-X</title>
+    <script src="/theme-init.js"></script>
     <style>
-      html, body { margin: 0; min-height: 100%; background: #070a13; }
-      #root:empty::before {
-        content: "Codex-X";
-        position: fixed; inset: 0; display: grid; place-items: center;
-        color: #eef4ff; font: 800 28px -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
-        background: radial-gradient(circle at 30% 12%, rgba(124,92,255,.22), transparent 32%), linear-gradient(135deg, #060814 0%, #0c1120 52%, #071421 100%);
-      }
+      html, body { margin: 0; min-height: 100%; background: #f3f4f6; }
+      html[data-theme="dark"], html[data-theme="dark"] body { background: #24262b; }
     </style>
   </head>
   <body>

apps/desktop/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-x",
-  "version": "0.2.28",
+  "version": "0.3.21",
   "private": true,
   "description": "Codex Switch & Instruct desktop manager",
   "type": "module",
@@ -14,6 +14,8 @@
   },
   "dependencies": {
     "@tauri-apps/api": "^2.8.0",
+    "@tauri-apps/plugin-process": "^2.3.1",
+    "@tauri-apps/plugin-updater": "^2.10.1",
     "lucide-react": "^0.542.0",
     "react": "^18.2.0",
     "react-dom": "^18.2.0"

apps/desktop/public/openai.svg

@@ -0,0 +1,5 @@
+<!-- Source: Simple Icons 16.26.0 (CC0-1.0). -->
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24">
+  <title>OpenAI</title>
+  <path d="M22.2819 9.8211a5.9847 5.9847 0 0 0-.5157-4.9108 6.0462 6.0462 0 0 0-6.5098-2.9A6.0651 6.0651 0 0 0 4.9807 4.1818a5.9847 5.9847 0 0 0-3.9977 2.9 6.0462 6.0462 0 0 0 .7427 7.0966 5.98 5.98 0 0 0 .511 4.9107 6.051 6.051 0 0 0 6.5146 2.9001A5.9847 5.9847 0 0 0 13.2599 24a6.0557 6.0557 0 0 0 5.7718-4.2058 5.9894 5.9894 0 0 0 3.9977-2.9001 6.0557 6.0557 0 0 0-.7475-7.0729zm-9.022 12.6081a4.4755 4.4755 0 0 1-2.8764-1.0408l.1419-.0804 4.7783-2.7582a.7948.7948 0 0 0 .3927-.6813v-6.7369l2.02 1.1686a.071.071 0 0 1 .038.052v5.5826a4.504 4.504 0 0 1-4.4945 4.4944zm-9.6607-4.1254a4.4708 4.4708 0 0 1-.5346-3.0137l.142.0852 4.783 2.7582a.7712.7712 0 0 0 .7806 0l5.8428-3.3685v2.3324a.0804.0804 0 0 1-.0332.0615L9.74 19.9502a4.4992 4.4992 0 0 1-6.1408-1.6464zM2.3408 7.8956a4.485 4.485 0 0 1 2.3655-1.9728V11.6a.7664.7664 0 0 0 .3879.6765l5.8144 3.3543-2.0201 1.1685a.0757.0757 0 0 1-.071 0l-4.8303-2.7865A4.504 4.504 0 0 1 2.3408 7.872zm16.5963 3.8558L13.1038 8.364 15.1192 7.2a.0757.0757 0 0 1 .071 0l4.8303 2.7913a4.4944 4.4944 0 0 1-.6765 8.1042v-5.6772a.79.79 0 0 0-.407-.667zm2.0107-3.0231l-.142-.0852-4.7735-2.7818a.7759.7759 0 0 0-.7854 0L9.409 9.2297V6.8974a.0662.0662 0 0 1 .0284-.0615l4.8303-2.7866a4.4992 4.4992 0 0 1 6.6802 4.66zM8.3065 12.863l-2.02-1.1638a.0804.0804 0 0 1-.038-.0567V6.0742a4.4992 4.4992 0 0 1 7.3757-3.4537l-.142.0805L8.704 5.459a.7948.7948 0 0 0-.3927.6813zm1.0976-2.3654l2.602-1.4998 2.6069 1.4998v2.9994l-2.5974 1.4997-2.6067-1.4997Z"/>
+</svg>

apps/desktop/public/provider-logos/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 LobeHub
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

apps/desktop/public/provider-logos/README.md

@@ -0,0 +1,16 @@
+# Provider brand marks
+
+These six unmodified SVG assets are from [Lobe Icons](https://github.com/lobehub/lobe-icons), licensed under the MIT License. The upstream copyright and permission notice is included in [LICENSE](./LICENSE).
+
+Pinned upstream commit: `a94750e3f5f8fc33757b839d85030e742284e43a`.
+
+| Local file | Upstream source |
+| --- | --- |
+| `deepseek.svg` | [packages/static-svg/icons/deepseek.svg](https://github.com/lobehub/lobe-icons/blob/a94750e3f5f8fc33757b839d85030e742284e43a/packages/static-svg/icons/deepseek.svg) |
+| `minimax.svg` | [packages/static-svg/icons/minimax.svg](https://github.com/lobehub/lobe-icons/blob/a94750e3f5f8fc33757b839d85030e742284e43a/packages/static-svg/icons/minimax.svg) |
+| `mimo.svg` | [packages/static-svg/icons/xiaomimimo.svg](https://github.com/lobehub/lobe-icons/blob/a94750e3f5f8fc33757b839d85030e742284e43a/packages/static-svg/icons/xiaomimimo.svg) |
+| `kimi.svg` | [packages/static-svg/icons/kimi.svg](https://github.com/lobehub/lobe-icons/blob/a94750e3f5f8fc33757b839d85030e742284e43a/packages/static-svg/icons/kimi.svg) |
+| `glm.svg` | [packages/static-svg/icons/zhipu.svg](https://github.com/lobehub/lobe-icons/blob/a94750e3f5f8fc33757b839d85030e742284e43a/packages/static-svg/icons/zhipu.svg) |
+| `qwen.svg` | [packages/static-svg/icons/qwen.svg](https://github.com/lobehub/lobe-icons/blob/a94750e3f5f8fc33757b839d85030e742284e43a/packages/static-svg/icons/qwen.svg) |
+
+The monochrome SVGs are rendered as CSS masks so their color follows the preset card state. Brand names and marks identify their respective providers; they do not imply endorsement.

apps/desktop/public/provider-logos/deepseek.svg

@@ -0,0 +1 @@
+<svg fill="currentColor" fill-rule="evenodd" height="1em" style="flex:none;line-height:1" viewBox="0 0 24 24" width="1em" xmlns="http://www.w3.org/2000/svg"><title>DeepSeek</title><path d="M23.748 4.482c-.254-.124-.364.113-.512.234-.051.039-.094.09-.137.136-.372.397-.806.657-1.373.626-.829-.046-1.537.214-2.163.848-.133-.782-.575-1.248-1.247-1.548-.352-.156-.708-.311-.955-.65-.172-.241-.219-.51-.305-.774-.055-.16-.11-.323-.293-.35-.2-.031-.278.136-.356.276-.313.572-.434 1.202-.422 1.84.027 1.436.633 2.58 1.838 3.393.137.093.172.187.129.323-.082.28-.18.552-.266.833-.055.179-.137.217-.329.14a5.526 5.526 0 01-1.736-1.18c-.857-.828-1.631-1.742-2.597-2.458a11.365 11.365 0 00-.689-.471c-.985-.957.13-1.743.388-1.836.27-.098.093-.432-.779-.428-.872.004-1.67.295-2.687.684a3.055 3.055 0 01-.465.137 9.597 9.597 0 00-2.883-.102c-1.885.21-3.39 1.102-4.497 2.623C.082 8.606-.231 10.684.152 12.85c.403 2.284 1.569 4.175 3.36 5.653 1.858 1.533 3.997 2.284 6.438 2.14 1.482-.085 3.133-.284 4.994-1.86.47.234.962.327 1.78.397.63.059 1.236-.03 1.705-.128.735-.156.684-.837.419-.961-2.155-1.004-1.682-.595-2.113-.926 1.096-1.296 2.746-2.642 3.392-7.003.05-.347.007-.565 0-.845-.004-.17.035-.237.23-.256a4.173 4.173 0 001.545-.475c1.396-.763 1.96-2.015 2.093-3.517.02-.23-.004-.467-.247-.588zM11.581 18c-2.089-1.642-3.102-2.183-3.52-2.16-.392.024-.321.471-.235.763.09.288.207.486.371.739.114.167.192.416-.113.603-.673.416-1.842-.14-1.897-.167-1.361-.802-2.5-1.86-3.301-3.307-.774-1.393-1.224-2.887-1.298-4.482-.02-.386.093-.522.477-.592a4.696 4.696 0 011.529-.039c2.132.312 3.946 1.265 5.468 2.774.868.86 1.525 1.887 2.202 2.891.72 1.066 1.494 2.082 2.48 2.914.348.292.625.514.891.677-.802.09-2.14.11-3.054-.614zm1-6.44a.306.306 0 01.415-.287.302.302 0 01.2.288.306.306 0 01-.31.307.303.303 0 01-.304-.308zm3.11 1.596c-.2.081-.399.151-.59.16a1.245 1.245 0 01-.798-.254c-.274-.23-.47-.358-.552-.758a1.73 1.73 0 01.016-.588c.07-.327-.008-.537-.239-.727-.187-.156-.426-.199-.688-.199a.559.559 0 01-.254-.078c-.11-.054-.2-.19-.114-.358.028-.054.16-.186.192-.21.356-.202.767-.136 1.146.016.352.144.618.408 1.001.782.391.451.462.576.685.914.176.265.336.537.445.848.067.195-.019.354-.25.452z"></path></svg>

apps/desktop/public/provider-logos/glm.svg

@@ -0,0 +1 @@
+<svg fill="currentColor" fill-rule="evenodd" height="1em" style="flex:none;line-height:1" viewBox="0 0 24 24" width="1em" xmlns="http://www.w3.org/2000/svg"><title>Zhipu</title><path d="M11.991 23.503a.24.24 0 00-.244.248.24.24 0 00.244.249.24.24 0 00.245-.249.24.24 0 00-.22-.247l-.025-.001zM9.671 5.365a1.697 1.697 0 011.099 2.132l-.071.172-.016.04-.018.054c-.07.16-.104.32-.104.498-.035.71.47 1.279 1.186 1.314h.366c1.309.053 2.338 1.173 2.286 2.523-.052 1.332-1.152 2.38-2.478 2.327h-.174c-.715.018-1.274.64-1.239 1.368 0 .124.018.23.053.337.209.373.54.658.96.8.75.23 1.517-.125 1.9-.782l.018-.035c.402-.64 1.17-.96 1.92-.711.854.284 1.378 1.226 1.099 2.167a1.661 1.661 0 01-2.077 1.102 1.711 1.711 0 01-.907-.711l-.017-.035c-.2-.323-.463-.58-.851-.711l-.056-.018a1.646 1.646 0 00-1.954.746 1.66 1.66 0 01-1.065.764 1.677 1.677 0 01-1.989-1.279c-.209-.906.332-1.83 1.257-2.043a1.51 1.51 0 01.296-.035h.018c.68-.071 1.151-.622 1.116-1.333a1.307 1.307 0 00-.227-.693 2.515 2.515 0 01-.366-1.403 2.39 2.39 0 01.366-1.208c.14-.195.21-.444.227-.693.018-.71-.506-1.261-1.186-1.332l-.07-.018a1.43 1.43 0 01-.299-.07l-.05-.019a1.7 1.7 0 01-1.047-2.114 1.68 1.68 0 012.094-1.101zm-5.575 10.11c.26-.264.639-.367.994-.27.355.096.633.379.728.74.095.362-.007.748-.267 1.013-.402.41-1.053.41-1.455 0a1.062 1.062 0 010-1.482zm14.845-.294c.359-.09.738.024.992.297.254.274.344.665.237 1.025-.107.36-.396.634-.756.718-.551.128-1.1-.22-1.23-.781a1.05 1.05 0 01.757-1.26zm-.064-4.39c.314.32.49.753.49 1.206 0 .452-.176.886-.49 1.206-.315.32-.74.5-1.185.5-.444 0-.87-.18-1.184-.5a1.727 1.727 0 010-2.412 1.654 1.654 0 012.369 0zm-11.243.163c.364.484.447 1.128.218 1.691a1.665 1.665 0 01-2.188.923c-.855-.36-1.26-1.358-.907-2.228a1.68 1.68 0 011.33-1.038c.593-.08 1.183.169 1.547.652zm11.545-4.221c.368 0 .708.2.892.524.184.324.184.724 0 1.048a1.026 1.026 0 01-.892.524c-.568 0-1.03-.47-1.03-1.048 0-.579.462-1.048 1.03-1.048zm-14.358 0c.368 0 .707.2.891.524.184.324.184.724 0 1.048a1.026 1.026 0 01-.891.524c-.569 0-1.03-.47-1.03-1.048 0-.579.461-1.048 1.03-1.048zm10.031-1.475c.925 0 1.675.764 1.675 1.706s-.75 1.705-1.675 1.705-1.674-.763-1.674-1.705c0-.942.75-1.706 1.674-1.706zm-2.626-.684c.362-.082.653-.356.761-.718a1.062 1.062 0 00-.238-1.028 1.017 1.017 0 00-.996-.294c-.547.14-.881.7-.752 1.257.13.558.675.907 1.225.783zm0 16.876c.359-.087.644-.36.75-.72a1.062 1.062 0 00-.237-1.019 1.018 1.018 0 00-.985-.301 1.037 1.037 0 00-.762.717c-.108.361-.017.754.239 1.028.245.263.606.377.953.305l.043-.01zM17.19 3.5a.631.631 0 00.628-.64c0-.355-.279-.64-.628-.64a.631.631 0 00-.628.64c0 .355.28.64.628.64zm-10.38 0a.631.631 0 00.628-.64c0-.355-.28-.64-.628-.64a.631.631 0 00-.628.64c0 .355.279.64.628.64zm-5.182 7.852a.631.631 0 00-.628.64c0 .354.28.639.628.639a.63.63 0 00.627-.606l.001-.034a.62.62 0 00-.628-.64zm5.182 9.13a.631.631 0 00-.628.64c0 .355.279.64.628.64a.631.631 0 00.628-.64c0-.355-.28-.64-.628-.64zm10.38.018a.631.631 0 00-.628.64c0 .355.28.64.628.64a.631.631 0 00.628-.64c0-.355-.279-.64-.628-.64zm5.182-9.148a.631.631 0 00-.628.64c0 .354.279.639.628.639a.631.631 0 00.628-.64c0-.355-.28-.64-.628-.64zm-.384-4.992a.24.24 0 00.244-.249.24.24 0 00-.244-.249.24.24 0 00-.244.249c0 .142.122.249.244.249zM11.991.497a.24.24 0 00.245-.248A.24.24 0 0011.99 0a.24.24 0 00-.244.249c0 .133.108.236.223.247l.021.001zM2.011 6.36a.24.24 0 00.245-.249.24.24 0 00-.244-.249.24.24 0 00-.244.249.24.24 0 00.244.249zm0 11.263a.24.24 0 00-.243.248.24.24 0 00.244.249.24.24 0 00.244-.249.252.252 0 00-.244-.248zm19.995-.018a.24.24 0 00-.245.248.24.24 0 00.245.25.24.24 0 00.244-.25.252.252 0 00-.244-.248z"></path></svg>

apps/desktop/public/provider-logos/kimi.svg

@@ -0,0 +1 @@
+<svg fill="currentColor" fill-rule="evenodd" height="1em" style="flex:none;line-height:1" viewBox="0 0 24 24" width="1em" xmlns="http://www.w3.org/2000/svg"><title>Kimi</title><path d="M21.846 0a1.923 1.923 0 110 3.846H20.15a.226.226 0 01-.227-.226V1.923C19.923.861 20.784 0 21.846 0z"></path><path d="M11.065 11.199l7.257-7.2c.137-.136.06-.41-.116-.41H14.3a.164.164 0 00-.117.051l-7.82 7.756c-.122.12-.302.013-.302-.179V3.82c0-.127-.083-.23-.185-.23H3.186c-.103 0-.186.103-.186.23V19.77c0 .128.083.23.186.23h2.69c.103 0 .186-.102.186-.23v-3.25c0-.069.025-.135.069-.178l2.424-2.406a.158.158 0 01.205-.023l6.484 4.772a7.677 7.677 0 003.453 1.283c.108.012.2-.095.2-.23v-3.06c0-.117-.07-.212-.164-.227a5.028 5.028 0 01-2.027-.807l-5.613-4.064c-.117-.078-.132-.279-.028-.381z"></path></svg>

apps/desktop/public/provider-logos/mimo.svg

@@ -0,0 +1 @@
+<svg fill="currentColor" fill-rule="evenodd" height="1em" style="flex:none;line-height:1" viewBox="0 0 24 24" width="1em" xmlns="http://www.w3.org/2000/svg"><title>XiaomiMiMo</title><path d="M.958 15.936a.459.459 0 01.459.44v2.729a.46.46 0 01-.918 0v-2.729a.459.459 0 01.459-.44zm4.814-2.035a.46.46 0 01.553.45v4.754a.458.458 0 11-.918 0V15.48L3.74 17.202a.462.462 0 01-.655.016.462.462 0 01-.065-.082L.628 14.67a.459.459 0 01.658-.637l2.124 2.187 2.127-2.188a.46.46 0 01.235-.13zm2.068.004a.46.46 0 01.458.445v4.755a.46.46 0 01-.458.458.459.459 0 01-.458-.458V14.35a.459.459 0 01.458-.445zm1.973 2.014a.46.46 0 01.46.457v2.729a.46.46 0 01-.784.324.46.46 0 01-.134-.324v-2.729a.46.46 0 01.458-.458zm.002-2.045a.458.458 0 01.328.157l2.127 2.19 2.125-2.19a.459.459 0 01.784.318v4.756a.46.46 0 01-.455.458.46.46 0 01-.458-.458V15.48l-1.667 1.723a.46.46 0 01-.65.008l-.005-.005c0-.002-.002-.002-.004-.003l-2.455-2.534a.46.46 0 01-.008-.667.461.461 0 01.338-.128zm6.797 1.206a.46.46 0 01.53.651A1.966 1.966 0 0019.81 18.4a.462.462 0 01.623.18.46.46 0 01-.181.624 2.863 2.863 0 01-1.38.353l-.142-.004a2.88 2.88 0 01-2.393-4.263.461.461 0 01.274-.21zm.864-.931a2.884 2.884 0 013.915 3.914.46.46 0 01-.402.24l-.057-.004a.458.458 0 01-.164-.055.46.46 0 01-.182-.622 1.967 1.967 0 00-2.669-2.67.459.459 0 11-.441-.803zM9.59 6.368c1.481 0 1.696 1.202 1.696 1.654v2.648h-.917v-.432c-.26.346-.792.535-1.36.535-.133 0-1.289-.03-1.384-1.136-.082-.932.675-1.61 2.053-1.61h.691c0-.563-.367-.886-.983-.886-.44.013-.864.174-1.2.458l-.36-.664c.484-.379 1.012-.567 1.764-.567zm4.427.1c1.263 0 2.082.97 2.083 2.15 0 1.181-.824 2.154-2.083 2.154-1.26 0-2.084-.972-2.084-2.152 0-1.18.82-2.153 2.084-2.153zm6.801.015c.68 0 1.202.465 1.197 1.548v2.642H21.1V8.29c0-.312-.002-.98-.63-.98s-.628.667-.628.838v2.524h-.89V8.148c0-.17-.001-.838-.63-.838-.628 0-.628.668-.628.98v2.383h-.917v-4.03h.917V7a1.22 1.22 0 01.947-.516c.398 0 .76.193.982.686a1.321 1.321 0 011.195-.686zm-18.093.872l1.457-1.772H5.32L3.311 8.07l2.14 2.602H4.24L2.725 8.796 1.21 10.672H0L2.138 8.07.13 5.583h1.138l1.458 1.772zm4.149 3.317h-.916V6.644h.916v4.028zm16.99 0h-.916V6.644h.916v4.028zM9.925 8.71c-1.055 0-1.359.412-1.326.742.032.329.324.537.757.537a1.013 1.013 0 001.014-.968l.002-.31h-.447zM14.018 7.3c-.663 0-1.184.487-1.184 1.32 0 .832.52 1.32 1.184 1.32.662 0 1.182-.49 1.182-1.32 0-.832-.52-1.32-1.182-1.32zM6.417 5.001a.568.568 0 01.587.582.588.588 0 01-1.175 0A.57.57 0 016.417 5zm16.991 0a.57.57 0 01.592.582.588.588 0 01-1.174 0 .57.57 0 01.357-.542.572.572 0 01.225-.04z"></path></svg>

apps/desktop/public/provider-logos/minimax.svg

@@ -0,0 +1 @@
+<svg fill="currentColor" fill-rule="evenodd" height="1em" style="flex:none;line-height:1" viewBox="0 0 24 24" width="1em" xmlns="http://www.w3.org/2000/svg"><title>Minimax</title><path d="M16.278 2c1.156 0 2.093.927 2.093 2.07v12.501a.74.74 0 00.744.709.74.74 0 00.743-.709V9.099a2.06 2.06 0 012.071-2.049A2.06 2.06 0 0124 9.1v6.561a.649.649 0 01-.652.645.649.649 0 01-.653-.645V9.1a.762.762 0 00-.766-.758.762.762 0 00-.766.758v7.472a2.037 2.037 0 01-2.048 2.026 2.037 2.037 0 01-2.048-2.026v-12.5a.785.785 0 00-.788-.753.785.785 0 00-.789.752l-.001 15.904A2.037 2.037 0 0113.441 22a2.037 2.037 0 01-2.048-2.026V18.04c0-.356.292-.645.652-.645.36 0 .652.289.652.645v1.934c0 .263.142.506.372.638.23.131.514.131.744 0a.734.734 0 00.372-.638V4.07c0-1.143.937-2.07 2.093-2.07zm-5.674 0c1.156 0 2.093.927 2.093 2.07v11.523a.648.648 0 01-.652.645.648.648 0 01-.652-.645V4.07a.785.785 0 00-.789-.78.785.785 0 00-.789.78v14.013a2.06 2.06 0 01-2.07 2.048 2.06 2.06 0 01-2.071-2.048V9.1a.762.762 0 00-.766-.758.762.762 0 00-.766.758v3.8a2.06 2.06 0 01-2.071 2.049A2.06 2.06 0 010 12.9v-1.378c0-.357.292-.646.652-.646.36 0 .653.29.653.646V12.9c0 .418.343.757.766.757s.766-.339.766-.757V9.099a2.06 2.06 0 012.07-2.048 2.06 2.06 0 012.071 2.048v8.984c0 .419.343.758.767.758.423 0 .766-.339.766-.758V4.07c0-1.143.937-2.07 2.093-2.07z"></path></svg>

apps/desktop/public/provider-logos/qwen.svg

@@ -0,0 +1 @@
+<svg fill="currentColor" fill-rule="evenodd" height="1em" style="flex:none;line-height:1" viewBox="0 0 24 24" width="1em" xmlns="http://www.w3.org/2000/svg"><title>Qwen</title><path d="M12.604 1.34c.393.69.784 1.382 1.174 2.075a.18.18 0 00.157.091h5.552c.174 0 .322.11.446.327l1.454 2.57c.19.337.24.478.024.837-.26.43-.513.864-.76 1.3l-.367.658c-.106.196-.223.28-.04.512l2.652 4.637c.172.301.111.494-.043.77-.437.785-.882 1.564-1.335 2.34-.159.272-.352.375-.68.37-.777-.016-1.552-.01-2.327.016a.099.099 0 00-.081.05 575.097 575.097 0 01-2.705 4.74c-.169.293-.38.363-.725.364-.997.003-2.002.004-3.017.002a.537.537 0 01-.465-.271l-1.335-2.323a.09.09 0 00-.083-.049H4.982c-.285.03-.553-.001-.805-.092l-1.603-2.77a.543.543 0 01-.002-.54l1.207-2.12a.198.198 0 000-.197 550.951 550.951 0 01-1.875-3.272l-.79-1.395c-.16-.31-.173-.496.095-.965.465-.813.927-1.625 1.387-2.436.132-.234.304-.334.584-.335a338.3 338.3 0 012.589-.001.124.124 0 00.107-.063l2.806-4.895a.488.488 0 01.422-.246c.524-.001 1.053 0 1.583-.006L11.704 1c.341-.003.724.032.9.34zm-3.432.403a.06.06 0 00-.052.03L6.254 6.788a.157.157 0 01-.135.078H3.253c-.056 0-.07.025-.041.074l5.81 10.156c.025.042.013.062-.034.063l-2.795.015a.218.218 0 00-.2.116l-1.32 2.31c-.044.078-.021.118.068.118l5.716.008c.046 0 .08.02.104.061l1.403 2.454c.046.081.092.082.139 0l5.006-8.76.783-1.382a.055.055 0 01.096 0l1.424 2.53a.122.122 0 00.107.062l2.763-.02a.04.04 0 00.035-.02.041.041 0 000-.04l-2.9-5.086a.108.108 0 010-.113l.293-.507 1.12-1.977c.024-.041.012-.062-.035-.062H9.2c-.059 0-.073-.026-.043-.077l1.434-2.505a.107.107 0 000-.114L9.225 1.774a.06.06 0 00-.053-.031zm6.29 8.02c.046 0 .058.02.034.06l-.832 1.465-2.613 4.585a.056.056 0 01-.05.029.058.058 0 01-.05-.029L8.498 9.841c-.02-.034-.01-.052.028-.054l.216-.012 6.722-.012z"></path></svg>

apps/desktop/public/theme-init.js

@@ -0,0 +1,10 @@
+(function () {
+  var theme = "light";
+  try {
+    theme = window.localStorage.getItem("codexx.theme") === "dark" ? "dark" : "light";
+  } catch (_error) {
+    // Keep the light default when storage is unavailable.
+  }
+  document.documentElement.dataset.theme = theme;
+  document.documentElement.style.colorScheme = theme;
+})();

apps/desktop/src-tauri/Cargo.toml

@@ -1,11 +1,11 @@
 [package]
 name = "codex-x"
-version = "0.2.28"
+version = "0.3.21"
 description = "Codex Switch & Instruct desktop manager"
 authors = ["yynxxxxx"]
 license = "MIT"
 edition = "2021"
-rust-version = "1.85.0"
+rust-version = "1.89.0"
 
 [lib]
 name = "codexx_lib"
@@ -15,14 +15,34 @@ crate-type = ["staticlib", "cdylib", "rlib"]
 tauri-build = { version = "2.4.0", features = [] }
 
 [dependencies]
-tauri = { version = "2.8.2", features = [] }
+tauri = { version = "2.8.2", features = ["tray-icon"] }
+tauri-plugin-process = "2.3.1"
+tauri-plugin-updater = "2.10.1"
 serde = { version = "1.0", features = ["derive"] }
 serde_json = "1.0"
+base64 = "0.22"
 toml_edit = "0.22"
 chrono = { version = "0.4", features = ["serde"] }
 dirs = "5.0"
 thiserror = "2.0"
-rusqlite = { version = "0.31", features = ["bundled"] }
+rusqlite = { version = "0.31", features = ["backup", "bundled"] }
+semver = "1.0"
 ureq = { version = "2.12", features = ["tls"] }
+reqwest = { version = "0.13", default-features = false, features = [
+    "blocking",
+    "rustls-no-provider",
+    "socks",
+    "system-proxy",
+] }
+rustls = { version = "0.23", default-features = false, features = ["ring"] }
 sha2 = "0.10"
+percent-encoding = "2.3"
 zip = { version = "2.2", default-features = false, features = ["deflate"] }
+rfd = { version = "=0.17.2", default-features = false, features = ["xdg-portal"] }
+tauri-plugin-single-instance = "=2.4.3"
+httparse = "1"
+getrandom = "0.2"
+tokio = { version = "1", features = ["rt-multi-thread", "time", "net"] }
+flate2 = "1"
+zstd = "0.13"
+tempfile = "3.27"

apps/desktop/src-tauri/capabilities/default.json

@@ -3,5 +3,10 @@
   "identifier": "default",
   "description": "Default app capability",
   "windows": ["main"],
-  "permissions": ["core:default"]
+  "permissions": [
+    "core:default",
+    "core:window:allow-start-dragging",
+    "updater:allow-check",
+    "process:allow-restart"
+  ]
 }

apps/desktop/src-tauri/nsis/TAURI-LICENSE-MIT

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2017 - Present Tauri Apps Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

apps/desktop/src-tauri/src/app_db.rs

@@ -0,0 +1,599 @@
+use crate::error::{CodexxError, Result};
+use crate::file_io::ensure_directory;
+use crate::paths::app_home;
+use crate::sqlite_utils::table_column_set;
+use rusqlite::Connection;
+use std::path::{Path, PathBuf};
+use std::sync::{Mutex, OnceLock};
+use std::time::Duration;
+
+const APP_DB_SCHEMA_VERSION: i64 = 7;
+
+struct DatabaseInitializer {
+    migration_lock: Mutex<()>,
+}
+
+impl DatabaseInitializer {
+    fn new() -> Self {
+        Self {
+            migration_lock: Mutex::new(()),
+        }
+    }
+
+    fn open_at(&self, path: &Path) -> Result<Connection> {
+        self.open_at_with(path, initialize_schema)
+    }
+
+    fn open_at_with(
+        &self,
+        path: &Path,
+        initialize: impl FnOnce(&Connection) -> Result<()>,
+    ) -> Result<Connection> {
+        if let Some(parent) = path.parent() {
+            ensure_directory(parent)?;
+        }
+        let conn = Connection::open(path).map_err(|e| CodexxError::Database(e.to_string()))?;
+        conn.busy_timeout(Duration::from_secs(5))
+            .map_err(|e| CodexxError::Database(e.to_string()))?;
+
+        if schema_is_current(&conn)? {
+            return Ok(conn);
+        }
+
+        // Serialize first-time migrations inside this process. The persistent
+        // schema version also prevents repeated migrations across launches and
+        // detects a database replaced at the same path.
+        let _migration_guard = self
+            .migration_lock
+            .lock()
+            .unwrap_or_else(|poisoned| poisoned.into_inner());
+        if !schema_is_current(&conn)? {
+            migrate_schema(&conn, initialize)?;
+        }
+        Ok(conn)
+    }
+}
+
+fn schema_version(conn: &Connection) -> Result<i64> {
+    conn.pragma_query_value(None, "user_version", |row| row.get(0))
+        .map_err(|error| CodexxError::Database(error.to_string()))
+}
+
+fn schema_is_current(conn: &Connection) -> Result<bool> {
+    Ok(schema_version(conn)? >= APP_DB_SCHEMA_VERSION)
+}
+
+fn migrate_schema(
+    conn: &Connection,
+    initialize: impl FnOnce(&Connection) -> Result<()>,
+) -> Result<()> {
+    conn.execute_batch("BEGIN IMMEDIATE")
+        .map_err(|error| CodexxError::Database(error.to_string()))?;
+
+    let migration = (|| {
+        // Another Codex-X process may have completed the migration while this
+        // connection waited for SQLite's write lock.
+        if !schema_is_current(conn)? {
+            initialize(conn)?;
+            conn.pragma_update(None, "user_version", APP_DB_SCHEMA_VERSION)
+                .map_err(|error| CodexxError::Database(error.to_string()))?;
+        }
+        conn.execute_batch("COMMIT")
+            .map_err(|error| CodexxError::Database(error.to_string()))
+    })();
+
+    match migration {
+        Ok(()) => Ok(()),
+        Err(error) => match conn.execute_batch("ROLLBACK") {
+            Ok(()) => Err(error),
+            Err(rollback_error) => Err(CodexxError::Database(format!(
+                "{error}; app database migration rollback failed: {rollback_error}"
+            ))),
+        },
+    }
+}
+
+fn database_initializer() -> &'static DatabaseInitializer {
+    static INITIALIZER: OnceLock<DatabaseInitializer> = OnceLock::new();
+    INITIALIZER.get_or_init(DatabaseInitializer::new)
+}
+
+#[cfg(test)]
+pub(crate) fn test_db_guard() -> std::sync::MutexGuard<'static, ()> {
+    use std::sync::{Mutex, OnceLock};
+    static TEST_DB_LOCK: OnceLock<Mutex<()>> = OnceLock::new();
+    TEST_DB_LOCK
+        .get_or_init(|| Mutex::new(()))
+        .lock()
+        .expect("test app database lock poisoned")
+}
+
+fn db_path() -> Result<PathBuf> {
+    Ok(app_home()?.join("codexx.db"))
+}
+
+fn ensure_sqlite_column(
+    conn: &Connection,
+    table: &str,
+    column: &str,
+    alter_sql: &str,
+) -> Result<()> {
+    let cols = table_column_set(conn, table)?;
+    if cols.contains(column) {
+        return Ok(());
+    }
+    match conn.execute(alter_sql, []) {
+        Ok(_) => Ok(()),
+        Err(e) => {
+            let message = e.to_string().to_ascii_lowercase();
+            if message.contains("duplicate column") || message.contains("duplicate column name") {
+                // Another running Codex-X process may have applied the same
+                // lightweight migration between our PRAGMA check and ALTER.
+                Ok(())
+            } else {
+                Err(CodexxError::Database(e.to_string()))
+            }
+        }
+    }
+}
+
+fn initialize_schema(conn: &Connection) -> Result<()> {
+    conn.execute_batch(
+        "CREATE TABLE IF NOT EXISTS providers (
+            id TEXT PRIMARY KEY,
+            provider_name TEXT NOT NULL,
+            base_url TEXT NOT NULL,
+            model TEXT NOT NULL,
+            api_key TEXT,
+            toml_config TEXT,
+            wire_api TEXT NOT NULL DEFAULT 'responses',
+            requires_openai_auth INTEGER NOT NULL DEFAULT 1,
+            model_mappings_json TEXT NOT NULL DEFAULT '[]',
+            source TEXT NOT NULL DEFAULT 'manual',
+            source_id TEXT,
+            created_at TEXT NOT NULL,
+            updated_at TEXT NOT NULL
+        );
+        CREATE INDEX IF NOT EXISTS idx_providers_updated_at ON providers(updated_at DESC);
+        CREATE TABLE IF NOT EXISTS prompts (
+            id TEXT PRIMARY KEY,
+            title TEXT NOT NULL,
+            filename TEXT NOT NULL,
+            content TEXT NOT NULL,
+            created_at TEXT NOT NULL,
+            updated_at TEXT NOT NULL
+        );
+        CREATE INDEX IF NOT EXISTS idx_prompts_updated_at ON prompts(updated_at DESC);
+        CREATE TABLE IF NOT EXISTS builtin_prompt_cache (
+            id TEXT PRIMARY KEY,
+            filename TEXT NOT NULL,
+            source_url TEXT NOT NULL,
+            content TEXT NOT NULL,
+            checked_at TEXT NOT NULL,
+            updated_at TEXT NOT NULL
+        );
+        CREATE TABLE IF NOT EXISTS builtin_prompt_overrides (
+            template_id TEXT PRIMARY KEY,
+            content TEXT NOT NULL,
+            created_at TEXT NOT NULL,
+            updated_at TEXT NOT NULL
+        );
+        CREATE TABLE IF NOT EXISTS managed_mcp_servers (
+            id TEXT PRIMARY KEY,
+            name TEXT NOT NULL,
+            server_config TEXT NOT NULL,
+            enabled INTEGER NOT NULL DEFAULT 0,
+            updated_at TEXT NOT NULL
+        );
+        CREATE TABLE IF NOT EXISTS managed_skills (
+            id TEXT PRIMARY KEY,
+            name TEXT NOT NULL,
+            description TEXT,
+            directory TEXT NOT NULL,
+            source_path TEXT,
+            content_hash TEXT,
+            enabled INTEGER NOT NULL DEFAULT 0,
+            updated_at TEXT NOT NULL
+        );
+        CREATE TABLE IF NOT EXISTS skills_mcp_notes (
+            codex_dir TEXT NOT NULL,
+            item_kind TEXT NOT NULL CHECK(item_kind IN ('skill', 'mcp')),
+            item_id TEXT NOT NULL,
+            note TEXT NOT NULL,
+            updated_at TEXT NOT NULL,
+            PRIMARY KEY(codex_dir, item_kind, item_id)
+        );
+        CREATE TABLE IF NOT EXISTS active_provider_selections (
+            codex_dir TEXT PRIMARY KEY,
+            provider_id TEXT NOT NULL,
+            updated_at TEXT NOT NULL
+        );
+        CREATE TABLE IF NOT EXISTS provider_failover (
+            codex_dir TEXT PRIMARY KEY,
+            record_json TEXT NOT NULL
+        );
+        CREATE TABLE IF NOT EXISTS provider_common_config_state (
+            codex_dir TEXT PRIMARY KEY,
+            handled_at TEXT NOT NULL
+        );
+        CREATE TABLE IF NOT EXISTS official_profiles (
+            codex_dir TEXT NOT NULL,
+            id TEXT NOT NULL,
+            provider_name TEXT NOT NULL,
+            created_at TEXT NOT NULL,
+            updated_at TEXT NOT NULL,
+            PRIMARY KEY(codex_dir, id)
+        );
+        CREATE TABLE IF NOT EXISTS official_profile_selections (
+            codex_dir TEXT PRIMARY KEY,
+            profile_id TEXT NOT NULL,
+            updated_at TEXT NOT NULL
+        );",
+    )
+    .map_err(|e| CodexxError::Database(e.to_string()))?;
+    ensure_sqlite_column(
+        conn,
+        "providers",
+        "toml_config",
+        "ALTER TABLE providers ADD COLUMN toml_config TEXT",
+    )?;
+    ensure_sqlite_column(
+        conn,
+        "providers",
+        "source",
+        "ALTER TABLE providers ADD COLUMN source TEXT NOT NULL DEFAULT 'manual'",
+    )?;
+    ensure_sqlite_column(
+        conn,
+        "providers",
+        "source_id",
+        "ALTER TABLE providers ADD COLUMN source_id TEXT",
+    )?;
+    ensure_sqlite_column(
+        conn,
+        "providers",
+        "model_mappings_json",
+        "ALTER TABLE providers ADD COLUMN model_mappings_json TEXT NOT NULL DEFAULT '[]'",
+    )?;
+    conn.execute_batch(
+        "CREATE UNIQUE INDEX IF NOT EXISTS idx_providers_source_identity
+         ON providers(source, source_id)
+         WHERE source_id IS NOT NULL;",
+    )
+    .map_err(|e| CodexxError::Database(e.to_string()))?;
+    conn.execute(
+        "DELETE FROM prompts
+         WHERE id LIKE 'external-%'
+           AND EXISTS (
+             SELECT 1 FROM prompts AS kept
+             WHERE lower(kept.filename) = lower(prompts.filename)
+               AND kept.id NOT LIKE 'external-%'
+           )",
+        [],
+    )
+    .map_err(|e| CodexxError::Database(e.to_string()))?;
+    conn.execute(
+        "DELETE FROM prompts
+         WHERE id LIKE 'external-%'
+           AND EXISTS (
+             SELECT 1 FROM prompts AS kept
+             WHERE kept.content = prompts.content
+               AND kept.id NOT LIKE 'external-%'
+           )",
+        [],
+    )
+    .map_err(|e| CodexxError::Database(e.to_string()))?;
+    conn.execute(
+        "DELETE FROM prompts
+         WHERE id LIKE 'external-%'
+           AND EXISTS (
+             SELECT 1 FROM prompts AS kept
+             WHERE kept.content = prompts.content
+               AND kept.id LIKE 'external-%'
+               AND kept.rowid <> prompts.rowid
+               AND (kept.updated_at > prompts.updated_at OR (kept.updated_at = prompts.updated_at AND kept.rowid > prompts.rowid))
+           )",
+        [],
+    )
+    .map_err(|e| CodexxError::Database(e.to_string()))?;
+    Ok(())
+}
+
+pub(crate) fn open() -> Result<Connection> {
+    database_initializer().open_at(&db_path()?)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::fs;
+    use std::sync::atomic::{AtomicU64, AtomicUsize, Ordering};
+    use std::sync::{Arc, Barrier};
+    use std::thread;
+    use std::time::Duration;
+
+    fn test_db_path(name: &str) -> PathBuf {
+        static COUNTER: AtomicU64 = AtomicU64::new(0);
+        let suffix = COUNTER.fetch_add(1, Ordering::Relaxed);
+        std::env::temp_dir()
+            .join(format!(
+                "codex-x-app-db-{name}-{}-{suffix}",
+                std::process::id()
+            ))
+            .join("codexx.db")
+    }
+
+    fn remove_test_db(path: &Path) {
+        if let Some(parent) = path.parent() {
+            fs::remove_dir_all(parent).expect("remove app database test directory");
+        }
+    }
+
+    #[test]
+    fn repeated_opens_do_not_rerun_legacy_cleanup() {
+        let path = test_db_path("cleanup-once");
+        let initializer = DatabaseInitializer::new();
+        let conn = initializer.open_at(&path).expect("initialize database");
+        conn.execute_batch(
+            "INSERT INTO prompts (id, title, filename, content, created_at, updated_at)
+             VALUES
+               ('kept', 'Kept', 'same.md', 'same', '1', '1'),
+               ('external-duplicate', 'Duplicate', 'same.md', 'same', '2', '2');",
+        )
+        .expect("seed a post-migration duplicate");
+        drop(conn);
+
+        let reopened_initializer = DatabaseInitializer::new();
+        let conn = reopened_initializer
+            .open_at(&path)
+            .expect("reopen database in a new process lifecycle");
+        let count: i64 = conn
+            .query_row("SELECT COUNT(*) FROM prompts", [], |row| row.get(0))
+            .expect("count prompts after reopen");
+        assert_eq!(count, 2, "reopen must not rerun migration cleanup");
+        drop(conn);
+        remove_test_db(&path);
+    }
+
+    #[test]
+    fn database_replaced_at_the_same_path_is_initialized_again() {
+        let path = test_db_path("replace-database");
+        let initializer = DatabaseInitializer::new();
+        let conn = initializer.open_at(&path).expect("initialize database");
+        assert_eq!(
+            schema_version(&conn).expect("read schema version"),
+            APP_DB_SCHEMA_VERSION
+        );
+        drop(conn);
+
+        fs::remove_file(&path).expect("replace initialized database");
+        let conn = initializer
+            .open_at(&path)
+            .expect("initialize replacement database");
+        let provider_count: i64 = conn
+            .query_row("SELECT COUNT(*) FROM providers", [], |row| row.get(0))
+            .expect("query replacement database schema");
+        assert_eq!(provider_count, 0);
+        assert_eq!(
+            schema_version(&conn).expect("read replacement version"),
+            APP_DB_SCHEMA_VERSION
+        );
+        drop(conn);
+        remove_test_db(&path);
+    }
+
+    #[test]
+    fn version_four_provider_rows_migrate_with_empty_model_mappings() {
+        let path = test_db_path("provider-model-mappings-v5");
+        if let Some(parent) = path.parent() {
+            fs::create_dir_all(parent).unwrap();
+        }
+        let legacy = Connection::open(&path).unwrap();
+        legacy.execute_batch("CREATE TABLE providers (
+            id TEXT PRIMARY KEY, provider_name TEXT NOT NULL, base_url TEXT NOT NULL,
+            model TEXT NOT NULL, api_key TEXT, toml_config TEXT,
+            wire_api TEXT NOT NULL DEFAULT 'responses', requires_openai_auth INTEGER NOT NULL DEFAULT 1,
+            source TEXT NOT NULL DEFAULT 'manual', source_id TEXT,
+            created_at TEXT NOT NULL, updated_at TEXT NOT NULL);
+            INSERT INTO providers (id, provider_name, base_url, model, api_key, source, source_id, created_at, updated_at)
+            VALUES ('legacy-models', 'Existing provider', 'https://migration.example.test/v1', 'existing-model', 'fixture-key', 'cc-switch', 'source-row', 'original-created', 'original-updated');
+            PRAGMA user_version = 4;").unwrap();
+        drop(legacy);
+        let migrated = DatabaseInitializer::new().open_at(&path).unwrap();
+        assert_eq!(schema_version(&migrated).unwrap(), APP_DB_SCHEMA_VERSION);
+        assert_eq!(
+            migrated
+                .query_row(
+                    "SELECT COUNT(*) FROM provider_common_config_state",
+                    [],
+                    |row| row.get::<_, i64>(0)
+                )
+                .unwrap(),
+            0
+        );
+        let stored = crate::providers::list_saved_providers_on_connection(&migrated).unwrap();
+        assert_eq!(stored.len(), 1);
+        assert!(stored[0].model_mappings.is_empty());
+        assert_eq!(stored[0].model, "existing-model");
+        assert_eq!(stored[0].api_key.as_deref(), Some("fixture-key"));
+        let metadata: (String, String, String, String, String) = migrated.query_row(
+            "SELECT source, source_id, created_at, updated_at, model_mappings_json FROM providers WHERE id = 'legacy-models'", [],
+            |row| Ok((row.get(0)?, row.get(1)?, row.get(2)?, row.get(3)?, row.get(4)?)),
+        ).unwrap();
+        assert_eq!(
+            metadata,
+            (
+                "cc-switch".into(),
+                "source-row".into(),
+                "original-created".into(),
+                "original-updated".into(),
+                "[]".into()
+            )
+        );
+        drop(migrated);
+        remove_test_db(&path);
+    }
+
+    #[test]
+    fn version_one_database_migrates_new_metadata_tables_without_data_loss() {
+        let path = test_db_path("skills-mcp-notes-migration");
+        if let Some(parent) = path.parent() {
+            fs::create_dir_all(parent).expect("create legacy database directory");
+        }
+        let legacy = Connection::open(&path).expect("create legacy database");
+        legacy
+            .execute_batch(
+                "CREATE TABLE managed_skills (
+                    id TEXT PRIMARY KEY,
+                    name TEXT NOT NULL,
+                    description TEXT,
+                    directory TEXT NOT NULL,
+                    source_path TEXT,
+                    content_hash TEXT,
+                    enabled INTEGER NOT NULL DEFAULT 0,
+                    updated_at TEXT NOT NULL
+                );
+                INSERT INTO managed_skills
+                    (id, name, directory, enabled, updated_at)
+                VALUES ('legacy-skill', 'Legacy skill', 'legacy-skill', 1, '2026-01-01T00:00:00Z');
+                PRAGMA user_version = 1;",
+            )
+            .expect("seed version one database");
+        drop(legacy);
+
+        let initializer = DatabaseInitializer::new();
+        let migrated = initializer.open_at(&path).expect("migrate database");
+        assert_eq!(
+            schema_version(&migrated).expect("read migrated schema version"),
+            APP_DB_SCHEMA_VERSION
+        );
+        let skill_count: i64 = migrated
+            .query_row(
+                "SELECT COUNT(*) FROM managed_skills WHERE id = 'legacy-skill'",
+                [],
+                |row| row.get(0),
+            )
+            .expect("count preserved skill");
+        assert_eq!(skill_count, 1);
+        migrated
+            .execute(
+                "INSERT INTO skills_mcp_notes
+                    (codex_dir, item_kind, item_id, note, updated_at)
+                 VALUES
+                    ('/tmp/legacy-codex', 'skill', 'legacy-skill', 'my note', '2026-01-02T00:00:00Z')",
+                [],
+            )
+            .expect("write note after migration");
+        migrated
+            .execute(
+                "INSERT INTO active_provider_selections
+                    (codex_dir, provider_id, updated_at)
+                 VALUES
+                    ('/tmp/legacy-codex', 'legacy-provider', '2026-01-02T00:00:00Z')",
+                [],
+            )
+            .expect("write active provider selection after migration");
+        drop(migrated);
+        remove_test_db(&path);
+    }
+
+    #[test]
+    fn concurrent_first_opens_initialize_once() {
+        let path = test_db_path("concurrent-init");
+        let attempts = Arc::new(AtomicUsize::new(0));
+        let barrier = Arc::new(Barrier::new(3));
+        let mut workers = Vec::new();
+
+        for _ in 0..2 {
+            let path = path.clone();
+            // Separate initializers model independent Codex-X processes; the
+            // SQLite transaction and persistent version still permit one run.
+            let initializer = DatabaseInitializer::new();
+            let attempts = Arc::clone(&attempts);
+            let barrier = Arc::clone(&barrier);
+            workers.push(thread::spawn(move || {
+                barrier.wait();
+                initializer.open_at_with(&path, |conn| {
+                    attempts.fetch_add(1, Ordering::SeqCst);
+                    thread::sleep(Duration::from_millis(25));
+                    conn.execute_batch("CREATE TABLE initialized_once (id INTEGER PRIMARY KEY);")
+                        .map_err(|error| CodexxError::Database(error.to_string()))
+                })
+            }));
+        }
+
+        barrier.wait();
+        for worker in workers {
+            drop(
+                worker
+                    .join()
+                    .expect("join concurrent database opener")
+                    .expect("open database concurrently"),
+            );
+        }
+        assert_eq!(attempts.load(Ordering::SeqCst), 1);
+        remove_test_db(&path);
+    }
+
+    #[test]
+    fn failed_initialization_can_retry() {
+        let path = test_db_path("retry-init");
+        let initializer = DatabaseInitializer::new();
+        let attempts = AtomicUsize::new(0);
+
+        let error = initializer
+            .open_at_with(&path, |_| {
+                attempts.fetch_add(1, Ordering::SeqCst);
+                Err(CodexxError::Database(
+                    "injected transient initialization failure".to_string(),
+                ))
+            })
+            .expect_err("first initialization must fail");
+        assert!(error
+            .to_string()
+            .contains("transient initialization failure"));
+
+        let conn = initializer
+            .open_at_with(&path, |conn| {
+                attempts.fetch_add(1, Ordering::SeqCst);
+                conn.execute_batch("CREATE TABLE retry_succeeded (id INTEGER PRIMARY KEY);")
+                    .map_err(|error| CodexxError::Database(error.to_string()))
+            })
+            .expect("retry initialization");
+        drop(conn);
+        let conn = initializer
+            .open_at_with(&path, |_| {
+                attempts.fetch_add(1, Ordering::SeqCst);
+                Ok(())
+            })
+            .expect("open initialized database");
+        assert_eq!(attempts.load(Ordering::SeqCst), 2);
+        drop(conn);
+        remove_test_db(&path);
+    }
+
+    #[test]
+    fn initialized_read_connection_does_not_need_a_write_lock() {
+        let path = test_db_path("read-with-writer");
+        let initializer = DatabaseInitializer::new();
+        let writer = initializer.open_at(&path).expect("initialize database");
+        writer
+            .execute_batch("BEGIN IMMEDIATE")
+            .expect("hold database write reservation");
+
+        let reader = initializer
+            .open_at(&path)
+            .expect("open reader while write reservation is held");
+        let count: i64 = reader
+            .query_row("SELECT COUNT(*) FROM providers", [], |row| row.get(0))
+            .expect("read while another connection holds write reservation");
+        assert_eq!(count, 0);
+
+        drop(reader);
+        writer
+            .execute_batch("ROLLBACK")
+            .expect("release write lock");
+        drop(writer);
+        remove_test_db(&path);
+    }
+}

apps/desktop/src-tauri/src/app_update.rs

@@ -0,0 +1,453 @@
+//! Keep downloads and verification in the signed Tauri updater, but own the
+//! Windows handoff. The stock updater exits immediately and skips our routing
+//! shutdown; it also cannot report installation progress after that exit.
+
+use serde::Serialize;
+use std::fs::{self, File, OpenOptions};
+use std::io::Write;
+use std::path::{Path, PathBuf};
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::Mutex;
+use std::time::Duration;
+use tauri::{ipc::Channel, Manager, ResourceId, Webview};
+use tauri_plugin_updater::Update;
+
+#[cfg(any(test, target_os = "windows"))]
+#[path = "windows_update.rs"]
+mod windows;
+
+static UPDATING: AtomicBool = AtomicBool::new(false);
+const DOWNLOAD_TIMEOUT_MS: u64 = 10 * 60 * 1000;
+
+#[derive(Clone, Serialize)]
+#[serde(tag = "event", content = "data")]
+pub(crate) enum AppUpdateEvent {
+    #[serde(rename_all = "camelCase")]
+    Started {
+        content_length: Option<u64>,
+    },
+    #[serde(rename_all = "camelCase")]
+    Progress {
+        chunk_length: usize,
+    },
+    Verifying,
+    #[allow(dead_code)] // Emitted by the Windows handoff; other platforms install in place.
+    Preparing,
+    Installing,
+    #[allow(dead_code)]
+    HandedOff,
+}
+
+#[derive(Clone, Debug, Serialize, PartialEq, Eq)]
+#[serde(rename_all = "lowercase")]
+pub(crate) enum FailureStage {
+    Download,
+    Verify,
+    Prepare,
+    Install,
+}
+
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub(crate) struct UpdateFailure {
+    stage: FailureStage,
+    message: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    log_path: Option<String>,
+}
+
+#[derive(Serialize)]
+#[serde(rename_all = "camelCase")]
+pub(crate) struct InstallResult {
+    restart_required: bool,
+}
+
+struct UpdateLease<'a>(&'a AtomicBool);
+impl<'a> UpdateLease<'a> {
+    fn acquire(flag: &'a AtomicBool) -> Result<Self, UpdateFailure> {
+        flag.compare_exchange(false, true, Ordering::AcqRel, Ordering::Acquire)
+            .map_err(|_| {
+                failure(
+                    FailureStage::Prepare,
+                    "已有更新正在进行，请等待当前操作完成。",
+                    None,
+                )
+            })?;
+        Ok(Self(flag))
+    }
+    #[cfg(target_os = "windows")]
+    fn handoff(self) {
+        // Never permit a second installer while the original app is exiting.
+        std::mem::forget(self);
+    }
+}
+impl Drop for UpdateLease<'_> {
+    fn drop(&mut self) {
+        self.0.store(false, Ordering::Release);
+    }
+}
+
+fn failure(stage: FailureStage, message: &str, log: Option<&UpdateLog>) -> UpdateFailure {
+    UpdateFailure {
+        stage,
+        message: message.into(),
+        log_path: log.map(|log| log.path.to_string_lossy().into_owned()),
+    }
+}
+
+/// This log contains only our fixed stage names and version, never URLs,
+/// headers, auth/config contents or raw network/parser error messages.
+struct UpdateLog {
+    path: PathBuf,
+    file: Mutex<File>,
+}
+impl UpdateLog {
+    fn create(dir: &Path, version: &str) -> std::io::Result<Self> {
+        let version = semver::Version::parse(version).map_err(|_| {
+            std::io::Error::new(std::io::ErrorKind::InvalidInput, "invalid version")
+        })?;
+        fs::create_dir_all(dir)?;
+        let mut nonce = [0u8; 8];
+        getrandom::getrandom(&mut nonce)
+            .map_err(|_| std::io::Error::other("random source unavailable"))?;
+        let nonce: String = nonce.iter().map(|b| format!("{b:02x}")).collect();
+        let path = dir.join(format!(
+            "update-{}-{}-{nonce}.log",
+            chrono::Utc::now().format("%Y%m%d-%H%M%S"),
+            std::process::id()
+        ));
+        let mut options = OpenOptions::new();
+        options.write(true).create_new(true);
+        #[cfg(unix)]
+        {
+            use std::os::unix::fs::OpenOptionsExt;
+            options.mode(0o600);
+        }
+        let file = Mutex::new(options.open(&path)?);
+        let log = Self { path, file };
+        log.record(&format!("target_version={version}"));
+        Ok(log)
+    }
+    fn record(&self, stage: &str) {
+        if let Ok(mut file) = self.file.lock() {
+            let _ = writeln!(file, "{} {stage}", chrono::Utc::now().to_rfc3339());
+            let _ = file.flush();
+        }
+    }
+}
+
+fn timeout_ms(value: Option<u64>) -> u64 {
+    value
+        .unwrap_or(DOWNLOAD_TIMEOUT_MS)
+        .clamp(30_000, DOWNLOAD_TIMEOUT_MS)
+}
+
+/// No installer is launched until all preparation succeeds. If launch fails,
+/// restore routing while the original app and single-instance lock still live.
+#[cfg(any(test, target_os = "windows"))]
+fn prepared_install<T>(
+    prepare: impl FnOnce() -> Result<(), ()>,
+    launch: impl FnOnce() -> Result<T, ()>,
+    resume: impl FnOnce() -> Result<(), ()>,
+    log: &UpdateLog,
+) -> Result<T, UpdateFailure> {
+    if prepare().is_err() {
+        log.record("prepare_failed");
+        let resumed = resume().is_ok();
+        log.record(if resumed {
+            "routing_resumed"
+        } else {
+            "routing_resume_failed"
+        });
+        return Err(failure(
+            FailureStage::Prepare,
+            if resumed {
+                "更新前未能恢复路由配置，安装尚未启动。请检查配置文件后重试。"
+            } else {
+                "更新前的路由清理未完成，安装尚未启动。请检查路由设置后重试。"
+            },
+            Some(log),
+        ));
+    }
+    match launch() {
+        Ok(result) => Ok(result),
+        Err(()) => {
+            log.record("installer_launch_failed");
+            let resumed = resume().is_ok();
+            log.record(if resumed {
+                "routing_resumed"
+            } else {
+                "routing_resume_failed"
+            });
+            Err(failure(
+                FailureStage::Install,
+                if resumed {
+                    "无法启动更新安装器，原有路由已恢复。请重试或打开下载页安装。"
+                } else {
+                    "无法启动更新安装器。请检查路由设置；也可打开下载页安装。"
+                },
+                Some(log),
+            ))
+        }
+    }
+}
+
+#[tauri::command]
+pub(crate) async fn install_app_update(
+    webview: Webview,
+    update_rid: ResourceId,
+    on_event: Channel<AppUpdateEvent>,
+    timeout: Option<u64>,
+    headers: Option<Vec<(String, String)>>,
+) -> Result<InstallResult, UpdateFailure> {
+    let _lease = UpdateLease::acquire(&UPDATING)?;
+    let update = webview
+        .resources_table()
+        .get::<Update>(update_rid)
+        .map_err(|_| {
+            failure(
+                FailureStage::Prepare,
+                "更新信息已失效，请重新检查更新。",
+                None,
+            )
+        })?;
+    let mut update = (*update).clone();
+    // The 15s metadata-check timeout must not become the package-download limit.
+    update.timeout = Some(Duration::from_millis(timeout_ms(timeout)));
+    if let Some(headers) = headers {
+        update.headers.clear();
+        for (name, value) in headers {
+            let name = reqwest::header::HeaderName::from_bytes(name.as_bytes())
+                .map_err(|_| failure(FailureStage::Prepare, "更新请求参数无效。", None))?;
+            let value = reqwest::header::HeaderValue::from_str(&value)
+                .map_err(|_| failure(FailureStage::Prepare, "更新请求参数无效。", None))?;
+            update.headers.append(name, value);
+        }
+    }
+    let dir = crate::paths::app_home()
+        .map_err(|_| failure(FailureStage::Prepare, "无法读取更新日志目录。", None))?
+        .join("update-logs");
+    let log = UpdateLog::create(&dir, &update.version).map_err(|_| {
+        failure(
+            FailureStage::Prepare,
+            "无法创建更新日志，请检查文件夹权限后重试。",
+            None,
+        )
+    })?;
+    log.record("download_started");
+    let finished = AtomicBool::new(false);
+    let mut started = false;
+    let bytes = update
+        .download(
+            |chunk_length, content_length| {
+                if !started {
+                    started = true;
+                    let _ = on_event.send(AppUpdateEvent::Started { content_length });
+                }
+                let _ = on_event.send(AppUpdateEvent::Progress { chunk_length });
+            },
+            || {
+                finished.store(true, Ordering::Release);
+                log.record("verifying_signature");
+                let _ = on_event.send(AppUpdateEvent::Verifying);
+            },
+        )
+        .await
+        .map_err(|_| {
+            if finished.load(Ordering::Acquire) {
+                log.record("signature_verification_failed");
+                failure(
+                    FailureStage::Verify,
+                    "更新包校验未通过，安装尚未启动。请重新下载或前往下载页。",
+                    Some(&log),
+                )
+            } else {
+                log.record("download_failed");
+                failure(
+                    FailureStage::Download,
+                    "更新下载未完成或连接超时。请检查网络后重试。",
+                    Some(&log),
+                )
+            }
+        })?;
+    log.record("signature_verified");
+
+    #[cfg(target_os = "windows")]
+    {
+        let app = webview.app_handle().clone();
+        let result = install_windows(app, bytes, on_event, log).await;
+        if result.is_ok() {
+            _lease.handoff();
+        }
+        result
+    }
+    #[cfg(not(target_os = "windows"))]
+    {
+        let _ = on_event.send(AppUpdateEvent::Installing);
+        log.record("install_started");
+        tauri::async_runtime::spawn_blocking(move || {
+            update.install(bytes).map_err(|_| {
+                log.record("install_failed");
+                failure(
+                    FailureStage::Install,
+                    "安装更新未完成，请重试或前往下载页安装。",
+                    Some(&log),
+                )
+            })?;
+            log.record("install_finished_restart_required");
+            Ok(InstallResult {
+                restart_required: true,
+            })
+        })
+        .await
+        .map_err(|_| {
+            failure(
+                FailureStage::Install,
+                "安装更新未完成，请重新打开软件后检查更新。",
+                None,
+            )
+        })?
+    }
+}
+
+// Compile this path in host tests too: staging/Command/IPC use portable Rust,
+// so Windows handoff type errors are caught before the Windows build starts.
+#[cfg(any(test, target_os = "windows"))]
+#[cfg_attr(not(target_os = "windows"), allow(dead_code))]
+async fn install_windows(
+    app: tauri::AppHandle,
+    bytes: Vec<u8>,
+    on_event: Channel<AppUpdateEvent>,
+    log: UpdateLog,
+) -> Result<InstallResult, UpdateFailure> {
+    tauri::async_runtime::spawn_blocking(move || {
+        // Stage bytes before changing live routes. Only signed .exe payloads
+        // from this release pipeline are supported by the new Windows flow.
+        let installer = windows::StagedInstaller::create(&bytes).map_err(|_| {
+            failure(
+                FailureStage::Install,
+                "无法准备 Windows 更新包，请检查磁盘空间或前往下载页安装。",
+                Some(&log),
+            )
+        })?;
+        let _ = on_event.send(AppUpdateEvent::Preparing);
+        log.record("preparing_route_shutdown");
+        prepared_install(
+            || crate::failover::shutdown_all().map_err(|_| ()),
+            || {
+                let _ = on_event.send(AppUpdateEvent::Installing);
+                log.record("launching_installer");
+                installer.launch(std::process::id()).map_err(|_| ())
+            },
+            || crate::failover::resume_after_failed_update().map_err(|_| ()),
+            &log,
+        )?;
+        log.record("installer_handed_off");
+        let _ = on_event.send(AppUpdateEvent::HandedOff);
+        // Normal Tauri exit destroys windows/tray/single-instance lock. The
+        // new installer waits for this PID before touching installed files.
+        app.exit(0);
+        Ok(InstallResult {
+            restart_required: false,
+        })
+    })
+    .await
+    .map_err(|_| {
+        failure(
+            FailureStage::Install,
+            "更新准备过程被中断，请重新打开 Codex-X 后检查更新。",
+            None,
+        )
+    })?
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::cell::RefCell;
+
+    #[test]
+    fn one_update_at_a_time_and_errors_release_the_guard() {
+        let flag = AtomicBool::new(false);
+        let first = UpdateLease::acquire(&flag).unwrap();
+        assert!(UpdateLease::acquire(&flag).is_err());
+        drop(first);
+        assert!(UpdateLease::acquire(&flag).is_ok());
+    }
+
+    #[test]
+    fn package_download_has_its_own_bounded_timeout() {
+        assert_eq!(timeout_ms(None), 600_000);
+        assert_eq!(timeout_ms(Some(15_000)), 30_000);
+        assert_eq!(timeout_ms(Some(u64::MAX)), 600_000);
+        assert_eq!(timeout_ms(Some(120_000)), 120_000);
+    }
+
+    #[test]
+    fn handoff_never_launches_on_failed_prepare_and_resumes_on_launch_failure() {
+        let temp = tempfile::tempdir().unwrap();
+        let log = UpdateLog::create(temp.path(), "0.4.0").unwrap();
+        let calls = RefCell::new(vec![]);
+        let fail = prepared_install(
+            || {
+                calls.borrow_mut().push("prepare");
+                Err(())
+            },
+            || {
+                calls.borrow_mut().push("launch");
+                Ok(())
+            },
+            || {
+                calls.borrow_mut().push("resume");
+                Ok(())
+            },
+            &log,
+        )
+        .unwrap_err();
+        assert_eq!(fail.stage, FailureStage::Prepare);
+        assert_eq!(*calls.borrow(), vec!["prepare", "resume"]);
+        calls.borrow_mut().clear();
+        let fail = prepared_install(
+            || {
+                calls.borrow_mut().push("prepare");
+                Ok(())
+            },
+            || {
+                calls.borrow_mut().push("launch");
+                Err::<(), _>(())
+            },
+            || {
+                calls.borrow_mut().push("resume");
+                Err(())
+            },
+            &log,
+        )
+        .unwrap_err();
+        assert_eq!(fail.stage, FailureStage::Install);
+        assert_eq!(*calls.borrow(), vec!["prepare", "launch", "resume"]);
+        assert!(fail.message.contains("检查路由设置"));
+    }
+
+    #[test]
+    fn successful_handoff_does_not_resume_routing() {
+        let temp = tempfile::tempdir().unwrap();
+        let log = UpdateLog::create(temp.path(), "0.4.0").unwrap();
+        assert_eq!(
+            prepared_install(|| Ok(()), || Ok(42), || panic!("must not resume"), &log).unwrap(),
+            42
+        );
+    }
+
+    #[test]
+    fn logs_are_unique_and_reject_untrusted_version_text() {
+        let temp = tempfile::tempdir().unwrap();
+        let first = UpdateLog::create(temp.path(), "0.4.0").unwrap();
+        let second = UpdateLog::create(temp.path(), "0.4.0").unwrap();
+        assert_ne!(first.path, second.path);
+        assert!(UpdateLog::create(temp.path(), "0.4.0\nsecret").is_err());
+        first.record("signature_verified");
+        assert!(fs::read_to_string(&first.path)
+            .unwrap()
+            .contains("signature_verified"));
+    }
+}

apps/desktop/src-tauri/src/backups.rs

@@ -0,0 +1,218 @@
+use crate::constants::AGENTS_FILENAME;
+use crate::error::{CodexxError, Result};
+use crate::file_io::{ensure_directory, io_err, write_json};
+use crate::paths::app_home;
+use crate::prompts::agents_path;
+use crate::{auth_path, config_path};
+use chrono::Local;
+use serde::{Deserialize, Serialize};
+use std::fs;
+use std::path::{Component, Path, PathBuf};
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub(crate) struct BackupMeta {
+    pub(crate) id: String,
+    pub(crate) action: String,
+    pub(crate) created_at: String,
+    pub(crate) codex_dir: String,
+    pub(crate) config_path: String,
+    pub(crate) auth_path: String,
+    pub(crate) had_config: bool,
+    pub(crate) had_auth: bool,
+    #[serde(default)]
+    pub(crate) agents_path: String,
+    #[serde(default)]
+    pub(crate) had_agents: bool,
+    #[serde(default)]
+    pub(crate) tracks_agents: bool,
+}
+
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub(crate) struct BackupEntry {
+    id: String,
+    action: String,
+    created_at: String,
+    path: String,
+    had_config: bool,
+    had_auth: bool,
+    had_agents: bool,
+}
+
+fn lexical_absolute_path(path: &Path) -> Result<PathBuf> {
+    let absolute = if path.is_absolute() {
+        path.to_path_buf()
+    } else {
+        std::env::current_dir()
+            .map_err(|error| io_err(path, error))?
+            .join(path)
+    };
+    let mut normalized = PathBuf::new();
+    for component in absolute.components() {
+        match component {
+            Component::Prefix(prefix) => normalized.push(prefix.as_os_str()),
+            Component::RootDir => normalized.push(component.as_os_str()),
+            Component::CurDir => {}
+            Component::ParentDir => {
+                normalized.pop();
+            }
+            Component::Normal(part) => normalized.push(part),
+        }
+    }
+    Ok(normalized)
+}
+
+/// Resolves every existing ancestor while retaining a normalized suffix. This
+/// compares missing CODEX_HOME targets without requiring the target to exist.
+fn normalized_path_identity(path: &Path) -> Result<PathBuf> {
+    let absolute = if path.is_absolute() {
+        path.to_path_buf()
+    } else {
+        std::env::current_dir()
+            .map_err(|error| io_err(path, error))?
+            .join(path)
+    };
+    for ancestor in absolute.ancestors() {
+        match fs::canonicalize(ancestor) {
+            Ok(canonical) => {
+                let suffix = absolute
+                    .strip_prefix(ancestor)
+                    .expect("ancestor must be a path prefix");
+                return lexical_absolute_path(&canonical.join(suffix));
+            }
+            Err(error) if error.kind() == std::io::ErrorKind::NotFound => {}
+            Err(error) => return Err(io_err(ancestor, error)),
+        }
+    }
+    lexical_absolute_path(&absolute)
+}
+
+fn same_path_identity(left: &Path, right: &Path) -> Result<bool> {
+    let left = normalized_path_identity(left)?;
+    let right = normalized_path_identity(right)?;
+    #[cfg(target_os = "windows")]
+    {
+        let left = left.to_string_lossy().replace('/', "\\");
+        let right = right.to_string_lossy().replace('/', "\\");
+        Ok(left.eq_ignore_ascii_case(&right))
+    }
+    #[cfg(not(target_os = "windows"))]
+    {
+        Ok(left == right)
+    }
+}
+
+pub(crate) fn validate_backup_codex_dir(meta: &BackupMeta, codex_dir: &Path) -> Result<()> {
+    let recorded = meta.codex_dir.trim();
+    if recorded.is_empty() {
+        return Err(CodexxError::Config("备份元数据缺少 CODEX_HOME".to_string()));
+    }
+    if same_path_identity(Path::new(recorded), codex_dir)? {
+        return Ok(());
+    }
+    Err(CodexxError::Config(format!(
+        "备份属于其他 CODEX_HOME，拒绝恢复：备份为 {}，当前为 {}",
+        Path::new(recorded).display(),
+        codex_dir.display()
+    )))
+}
+
+fn backup_root() -> Result<PathBuf> {
+    Ok(app_home()?.join("backups"))
+}
+
+pub(crate) fn action_backup_root(codex_dir: &Path) -> Result<PathBuf> {
+    #[cfg(test)]
+    {
+        Ok(codex_dir.join(".codexx-test-backups"))
+    }
+    #[cfg(not(test))]
+    {
+        let _ = codex_dir;
+        backup_root()
+    }
+}
+
+pub(crate) fn create_backup(codex_dir: &Path, action: &str) -> Result<Option<String>> {
+    use std::sync::atomic::{AtomicU64, Ordering};
+    static BACKUP_COUNTER: AtomicU64 = AtomicU64::new(0);
+    let cfg = config_path(codex_dir);
+    let auth = auth_path(codex_dir);
+    let agents = agents_path(codex_dir);
+    let had_config = cfg.exists();
+    let had_auth = auth.exists();
+    let had_agents = agents.exists();
+
+    let id = format!(
+        "{}-{}-{}",
+        Local::now().format("%Y%m%d-%H%M%S-%3f"),
+        BACKUP_COUNTER.fetch_add(1, Ordering::Relaxed),
+        action
+    );
+    let dir = action_backup_root(codex_dir)?.join(&id);
+    ensure_directory(&dir)?;
+
+    if had_config {
+        fs::copy(&cfg, dir.join("config.toml")).map_err(|e| io_err(&cfg, e))?;
+    }
+    if had_auth {
+        fs::copy(&auth, dir.join("auth.json")).map_err(|e| io_err(&auth, e))?;
+    }
+    if had_agents {
+        fs::copy(&agents, dir.join(AGENTS_FILENAME)).map_err(|e| io_err(&agents, e))?;
+    }
+
+    let meta = BackupMeta {
+        id: id.clone(),
+        action: action.to_string(),
+        created_at: Local::now().to_rfc3339(),
+        codex_dir: codex_dir.display().to_string(),
+        config_path: cfg.display().to_string(),
+        auth_path: auth.display().to_string(),
+        had_config,
+        had_auth,
+        agents_path: agents.display().to_string(),
+        had_agents,
+        tracks_agents: true,
+    };
+    write_json(
+        &dir.join("meta.json"),
+        &serde_json::to_value(meta).expect("meta serialize"),
+    )?;
+    Ok(Some(id))
+}
+
+fn read_backup_entry(dir: &Path) -> Option<BackupEntry> {
+    let meta_path = dir.join("meta.json");
+    let text = fs::read_to_string(&meta_path).ok()?;
+    let meta: BackupMeta = serde_json::from_str(&text).ok()?;
+    Some(BackupEntry {
+        id: meta.id,
+        action: meta.action,
+        created_at: meta.created_at,
+        path: dir.display().to_string(),
+        had_config: meta.had_config,
+        had_auth: meta.had_auth,
+        had_agents: meta.had_agents,
+    })
+}
+
+pub(crate) fn backups() -> Result<Vec<BackupEntry>> {
+    let root = backup_root()?;
+    if !root.exists() {
+        return Ok(Vec::new());
+    }
+    let mut entries = Vec::new();
+    for entry in fs::read_dir(&root).map_err(|e| io_err(&root, e))? {
+        let entry = entry.map_err(|e| io_err(&root, e))?;
+        let path = entry.path();
+        if path.is_dir() {
+            if let Some(backup) = read_backup_entry(&path) {
+                entries.push(backup);
+            }
+        }
+    }
+    entries.sort_by(|a, b| b.created_at.cmp(&a.created_at));
+    Ok(entries)
+}

apps/desktop/src-tauri/src/ccswitch.rs

@@ -0,0 +1,139 @@
+use crate::error::{CodexxError, Result};
+use crate::paths::home_dir;
+use std::path::PathBuf;
+
+fn push_existing_candidate(candidates: &mut Vec<PathBuf>, candidate: Option<PathBuf>) {
+    let Some(path) = candidate else {
+        return;
+    };
+    if !candidates.iter().any(|item| item == &path) {
+        candidates.push(path);
+    }
+}
+
+pub(crate) fn ccswitch_db_candidates() -> Result<Vec<PathBuf>> {
+    let mut candidates = Vec::new();
+
+    if let Ok(value) = std::env::var("CC_SWITCH_HOME") {
+        let trimmed = value.trim();
+        if !trimmed.is_empty() {
+            push_existing_candidate(
+                &mut candidates,
+                Some(PathBuf::from(trimmed).join("cc-switch.db")),
+            );
+        }
+    }
+
+    let home = home_dir()?;
+    // cc-switch 当前主要使用这个位置，macOS/Windows/Linux 都适用。
+    push_existing_candidate(
+        &mut candidates,
+        Some(home.join(".cc-switch").join("cc-switch.db")),
+    );
+
+    // 兼容 Tauri/AppData 风格位置，防止未来或不同发行版变更数据目录。
+    if let Some(data_dir) = dirs::data_dir() {
+        push_existing_candidate(
+            &mut candidates,
+            Some(data_dir.join("com.ccswitch.desktop").join("cc-switch.db")),
+        );
+        push_existing_candidate(
+            &mut candidates,
+            Some(data_dir.join("cc-switch").join("cc-switch.db")),
+        );
+        push_existing_candidate(
+            &mut candidates,
+            Some(data_dir.join("CC Switch").join("cc-switch.db")),
+        );
+    }
+    if let Some(data_local_dir) = dirs::data_local_dir() {
+        push_existing_candidate(
+            &mut candidates,
+            Some(
+                data_local_dir
+                    .join("com.ccswitch.desktop")
+                    .join("cc-switch.db"),
+            ),
+        );
+        push_existing_candidate(
+            &mut candidates,
+            Some(data_local_dir.join("cc-switch").join("cc-switch.db")),
+        );
+        push_existing_candidate(
+            &mut candidates,
+            Some(data_local_dir.join("CC Switch").join("cc-switch.db")),
+        );
+    }
+
+    #[cfg(target_os = "macos")]
+    {
+        push_existing_candidate(
+            &mut candidates,
+            Some(
+                home.join("Library")
+                    .join("Application Support")
+                    .join("com.ccswitch.desktop")
+                    .join("cc-switch.db"),
+            ),
+        );
+    }
+
+    #[cfg(target_os = "windows")]
+    {
+        if let Ok(appdata) = std::env::var("APPDATA") {
+            push_existing_candidate(
+                &mut candidates,
+                Some(
+                    PathBuf::from(appdata)
+                        .join("com.ccswitch.desktop")
+                        .join("cc-switch.db"),
+                ),
+            );
+        }
+        if let Ok(localappdata) = std::env::var("LOCALAPPDATA") {
+            push_existing_candidate(
+                &mut candidates,
+                Some(
+                    PathBuf::from(localappdata)
+                        .join("com.ccswitch.desktop")
+                        .join("cc-switch.db"),
+                ),
+            );
+        }
+    }
+
+    #[cfg(target_os = "linux")]
+    {
+        if let Ok(xdg_data_home) = std::env::var("XDG_DATA_HOME") {
+            push_existing_candidate(
+                &mut candidates,
+                Some(
+                    PathBuf::from(xdg_data_home)
+                        .join("com.ccswitch.desktop")
+                        .join("cc-switch.db"),
+                ),
+            );
+        }
+        push_existing_candidate(
+            &mut candidates,
+            Some(
+                home.join(".local")
+                    .join("share")
+                    .join("com.ccswitch.desktop")
+                    .join("cc-switch.db"),
+            ),
+        );
+    }
+
+    Ok(candidates)
+}
+
+pub(crate) fn default_ccswitch_db_path() -> Result<PathBuf> {
+    let candidates = ccswitch_db_candidates()?;
+    candidates
+        .iter()
+        .find(|path| path.exists())
+        .cloned()
+        .or_else(|| candidates.into_iter().next())
+        .ok_or_else(|| CodexxError::Config("无法生成 cc-switch 数据库候选路径".to_string()))
+}

apps/desktop/src-tauri/src/config_migration.rs

@@ -0,0 +1,318 @@
+use crate::backups::create_backup;
+use crate::config_path;
+use crate::error::Result;
+use crate::file_io::parse_toml_document;
+#[cfg(test)]
+use crate::live_config::acquire_live_config_lock;
+use crate::live_config::{atomic_write_if_unchanged, read_file_snapshot, text_from_snapshot};
+use std::path::Path;
+use toml_edit::{DocumentMut, Item, Table};
+
+const INSTRUCTION_KEY: &str = "model_instructions_file";
+const MODEL_AVAILABILITY_NUX_KEY: &str = "model_availability_nux";
+
+fn markdown_path(item: Option<&Item>) -> bool {
+    item.and_then(|item| item.as_str())
+        .map(str::trim)
+        .is_some_and(|path| !path.is_empty() && path.to_ascii_lowercase().ends_with(".md"))
+}
+
+fn tui_table(doc: &DocumentMut) -> Option<&Table> {
+    doc.get("tui").and_then(|item| item.as_table())
+}
+
+fn remove_markdown_path(table: &mut Table, key: &str) -> Option<Item> {
+    if markdown_path(table.get(key)) {
+        table.remove(key)
+    } else {
+        None
+    }
+}
+
+/// Repairs prompt paths appended by older Codex-X versions after a `[tui]`
+/// header. Only the exact legacy keys with Markdown path values are touched.
+#[cfg(test)]
+pub(crate) fn migrate_legacy_prompt_config(codex_dir: &Path) -> Result<bool> {
+    let _lock = acquire_live_config_lock(codex_dir)?;
+    migrate_legacy_prompt_config_locked(codex_dir)
+}
+
+pub(crate) fn migrated_legacy_prompt_config_text(cfg: &Path, text: &str) -> Result<Option<String>> {
+    if text.trim().is_empty() {
+        return Ok(None);
+    }
+
+    let mut doc = parse_toml_document(cfg, text)?;
+    let nested_instruction = tui_table(&doc)
+        .and_then(|tui| tui.get(MODEL_AVAILABILITY_NUX_KEY))
+        .and_then(|item| item.as_table())
+        .is_some_and(|nux| markdown_path(nux.get(INSTRUCTION_KEY)));
+    let tui_instruction =
+        tui_table(&doc).is_some_and(|tui| markdown_path(tui.get(INSTRUCTION_KEY)));
+    let nux_as_instruction =
+        tui_table(&doc).is_some_and(|tui| markdown_path(tui.get(MODEL_AVAILABILITY_NUX_KEY)));
+
+    if !nested_instruction && !tui_instruction && !nux_as_instruction {
+        return Ok(None);
+    }
+
+    let root_instruction_exists = doc.as_table().contains_key(INSTRUCTION_KEY);
+    let removed_nested = doc
+        .get_mut("tui")
+        .and_then(|item| item.as_table_mut())
+        .and_then(|tui| tui.get_mut(MODEL_AVAILABILITY_NUX_KEY))
+        .and_then(|item| item.as_table_mut())
+        .and_then(|nux| remove_markdown_path(nux, INSTRUCTION_KEY));
+    let removed_tui = doc
+        .get_mut("tui")
+        .and_then(|item| item.as_table_mut())
+        .and_then(|tui| remove_markdown_path(tui, INSTRUCTION_KEY));
+    let removed_nux_value = doc
+        .get_mut("tui")
+        .and_then(|item| item.as_table_mut())
+        .and_then(|tui| remove_markdown_path(tui, MODEL_AVAILABILITY_NUX_KEY));
+
+    if !root_instruction_exists {
+        let instruction = removed_nested
+            .or(removed_tui)
+            .or(removed_nux_value)
+            .expect("a detected legacy prompt path must still be removable");
+        doc.as_table_mut().insert(INSTRUCTION_KEY, instruction);
+    }
+
+    Ok(Some(doc.to_string()))
+}
+
+pub(crate) fn migrate_legacy_prompt_config_locked(codex_dir: &Path) -> Result<bool> {
+    let cfg = config_path(codex_dir);
+    let original = read_file_snapshot(&cfg)?;
+    let text = text_from_snapshot(&cfg, original.as_deref())?;
+    let Some(migrated) = migrated_legacy_prompt_config_text(&cfg, &text)? else {
+        return Ok(false);
+    };
+    create_backup(codex_dir, "migrate-legacy-prompt-config")?;
+
+    atomic_write_if_unchanged(&cfg, original.as_deref(), migrated.as_bytes())?;
+    Ok(true)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::backups::action_backup_root;
+    use crate::file_io::write_text;
+    use std::fs;
+    use std::path::PathBuf;
+    use std::sync::atomic::{AtomicU64, Ordering};
+
+    fn temp_codex_dir(name: &str) -> PathBuf {
+        static COUNTER: AtomicU64 = AtomicU64::new(0);
+        let dir = std::env::temp_dir().join(format!(
+            "codex-x-config-migration-{name}-{}-{}",
+            std::process::id(),
+            COUNTER.fetch_add(1, Ordering::Relaxed),
+        ));
+        let _ = fs::remove_dir_all(&dir);
+        fs::create_dir_all(&dir).expect("create temp Codex directory");
+        dir
+    }
+
+    fn read_doc(codex_dir: &Path) -> DocumentMut {
+        fs::read_to_string(config_path(codex_dir))
+            .expect("read migrated config")
+            .parse()
+            .expect("parse migrated config")
+    }
+
+    fn backup_count(codex_dir: &Path) -> usize {
+        let root = action_backup_root(codex_dir).expect("resolve backup root");
+        if !root.exists() {
+            return 0;
+        }
+        fs::read_dir(root).expect("read backup root").count()
+    }
+
+    fn only_backup_config(codex_dir: &Path) -> String {
+        let root = action_backup_root(codex_dir).expect("resolve backup root");
+        let entries = fs::read_dir(root)
+            .expect("read backup root")
+            .collect::<std::result::Result<Vec<_>, _>>()
+            .expect("read backup entries");
+        assert_eq!(entries.len(), 1);
+        fs::read_to_string(entries[0].path().join("config.toml")).expect("read backed-up config")
+    }
+
+    #[test]
+    fn migrates_instruction_nested_under_model_availability_nux() {
+        let codex_dir = temp_codex_dir("nested-nux");
+        let original = r#"model = "gpt-5.6"
+
+[tui.model_availability_nux]
+# Keep valid model counters and their comments.
+"gpt-5.5" = 4
+model_instructions_file = "./legacy-prompt.md" # Keep the prompt note too.
+"gpt-5.6" = 2
+
+[tui.notifications]
+enabled = true
+"#;
+        write_text(&config_path(&codex_dir), original).expect("write legacy config");
+
+        assert!(migrate_legacy_prompt_config(&codex_dir).expect("migrate config"));
+
+        let migrated_text = fs::read_to_string(config_path(&codex_dir)).expect("read config");
+        let doc = read_doc(&codex_dir);
+        assert_eq!(
+            doc.get(INSTRUCTION_KEY).and_then(|item| item.as_str()),
+            Some("./legacy-prompt.md")
+        );
+        let nux = doc["tui"][MODEL_AVAILABILITY_NUX_KEY]
+            .as_table()
+            .expect("keep model availability table");
+        assert!(!nux.contains_key(INSTRUCTION_KEY));
+        assert_eq!(
+            nux.get("gpt-5.5").and_then(|item| item.as_integer()),
+            Some(4)
+        );
+        assert_eq!(
+            nux.get("gpt-5.6").and_then(|item| item.as_integer()),
+            Some(2)
+        );
+        assert!(migrated_text.contains("# Keep valid model counters and their comments."));
+        assert!(migrated_text.contains("# Keep the prompt note too."));
+        assert_eq!(doc["tui"]["notifications"]["enabled"].as_bool(), Some(true));
+        assert_eq!(backup_count(&codex_dir), 1);
+        assert_eq!(only_backup_config(&codex_dir), original);
+        fs::remove_dir_all(codex_dir).expect("remove temp directory");
+    }
+
+    #[test]
+    fn migrates_instruction_directly_under_tui() {
+        let codex_dir = temp_codex_dir("direct-tui");
+        write_text(
+            &config_path(&codex_dir),
+            "[tui]\nnotifications = true\nmodel_instructions_file = \"./direct.md\"\n",
+        )
+        .expect("write legacy config");
+
+        assert!(migrate_legacy_prompt_config(&codex_dir).expect("migrate config"));
+
+        let doc = read_doc(&codex_dir);
+        assert_eq!(
+            doc.get(INSTRUCTION_KEY).and_then(|item| item.as_str()),
+            Some("./direct.md")
+        );
+        assert!(doc["tui"].as_table().is_some_and(|tui| {
+            !tui.contains_key(INSTRUCTION_KEY)
+                && tui.get("notifications").and_then(|item| item.as_bool()) == Some(true)
+        }));
+        fs::remove_dir_all(codex_dir).expect("remove temp directory");
+    }
+
+    #[test]
+    fn migrates_markdown_path_stored_as_tui_model_availability_nux() {
+        let codex_dir = temp_codex_dir("nux-as-path");
+        write_text(
+            &config_path(&codex_dir),
+            "[tui]\nmodel_availability_nux = \"./gpt-5.6-sol-unrestricted.md\"\n",
+        )
+        .expect("write legacy config");
+
+        assert!(migrate_legacy_prompt_config(&codex_dir).expect("migrate config"));
+
+        let doc = read_doc(&codex_dir);
+        assert_eq!(
+            doc.get(INSTRUCTION_KEY).and_then(|item| item.as_str()),
+            Some("./gpt-5.6-sol-unrestricted.md")
+        );
+        assert!(doc["tui"]
+            .as_table()
+            .is_some_and(|tui| { !tui.contains_key(MODEL_AVAILABILITY_NUX_KEY) }));
+        fs::remove_dir_all(codex_dir).expect("remove temp directory");
+    }
+
+    #[test]
+    fn root_instruction_wins_over_legacy_nested_value() {
+        let codex_dir = temp_codex_dir("root-wins");
+        write_text(
+            &config_path(&codex_dir),
+            r#"model_instructions_file = "./current.md"
+
+[tui.model_availability_nux]
+"gpt-5.5" = 4
+model_instructions_file = "./stale.md"
+"#,
+        )
+        .expect("write conflicting config");
+
+        assert!(migrate_legacy_prompt_config(&codex_dir).expect("migrate config"));
+
+        let doc = read_doc(&codex_dir);
+        assert_eq!(
+            doc.get(INSTRUCTION_KEY).and_then(|item| item.as_str()),
+            Some("./current.md")
+        );
+        assert!(!doc["tui"][MODEL_AVAILABILITY_NUX_KEY]
+            .as_table()
+            .expect("keep nux table")
+            .contains_key(INSTRUCTION_KEY));
+        fs::remove_dir_all(codex_dir).expect("remove temp directory");
+    }
+
+    #[test]
+    fn leaves_legal_tui_values_unchanged_without_backup() {
+        let codex_dir = temp_codex_dir("legal-tui");
+        let original = "[tui]\nmodel_availability_nux = 4\nnotifications = true\n";
+        write_text(&config_path(&codex_dir), original).expect("write legal config");
+
+        assert!(!migrate_legacy_prompt_config(&codex_dir).expect("inspect config"));
+
+        assert_eq!(
+            fs::read_to_string(config_path(&codex_dir)).expect("read unchanged config"),
+            original
+        );
+        assert_eq!(backup_count(&codex_dir), 0);
+        fs::remove_dir_all(codex_dir).expect("remove temp directory");
+    }
+
+    #[test]
+    fn migration_is_idempotent_and_backs_up_only_once() {
+        let codex_dir = temp_codex_dir("idempotent");
+        write_text(
+            &config_path(&codex_dir),
+            "[tui]\nmodel_instructions_file = \"./once.md\"\n",
+        )
+        .expect("write legacy config");
+
+        assert!(migrate_legacy_prompt_config(&codex_dir).expect("first migration"));
+        let after_first = fs::read_to_string(config_path(&codex_dir)).expect("read first result");
+        assert!(!migrate_legacy_prompt_config(&codex_dir).expect("second migration"));
+
+        assert_eq!(
+            fs::read_to_string(config_path(&codex_dir)).expect("read second result"),
+            after_first
+        );
+        assert_eq!(backup_count(&codex_dir), 1);
+        fs::remove_dir_all(codex_dir).expect("remove temp directory");
+    }
+
+    #[test]
+    fn loading_codex_state_runs_the_migration() {
+        let codex_dir = temp_codex_dir("state-load");
+        write_text(
+            &config_path(&codex_dir),
+            "[tui]\nmodel_availability_nux = \"./loaded.md\"\n",
+        )
+        .expect("write legacy config");
+
+        crate::state::build_state(codex_dir.clone()).expect("load Codex state");
+
+        let doc = read_doc(&codex_dir);
+        assert_eq!(
+            doc.get(INSTRUCTION_KEY).and_then(|item| item.as_str()),
+            Some("./loaded.md")
+        );
+        assert_eq!(backup_count(&codex_dir), 1);
+        fs::remove_dir_all(codex_dir).expect("remove temp directory");
+    }
+}

apps/desktop/src-tauri/src/constants.rs

@@ -1,16 +1,32 @@
 pub(crate) const INSTRUCTION_FILENAME: &str = "gpt5.5-unrestricted.md";
-pub(crate) const INSTRUCTION_RELATIVE: &str = "./gpt5.5-unrestricted.md";
 pub(crate) const INSTRUCTION_CONTENT: &str =
     include_str!("../../../../examples/gpt5.5-unrestricted.md");
 
 pub(crate) const INSTRUCTION_54_FILENAME: &str = "gpt5.4-unrestricted.md";
-pub(crate) const INSTRUCTION_54_RELATIVE: &str = "./gpt5.4-unrestricted.md";
 pub(crate) const INSTRUCTION_54_CONTENT: &str =
     include_str!("../../../../examples/gpt5.4-unrestricted.md");
 
 pub(crate) const INSTRUCTION_JELI_FILENAME: &str = "gpt5.5-jeli.md";
-pub(crate) const INSTRUCTION_JELI_RELATIVE: &str = "./gpt5.5-jeli.md";
 pub(crate) const INSTRUCTION_JELI_CONTENT: &str =
     include_str!("../../../../examples/gpt5.5-jeli.md");
 
-pub(crate) const MAX_SKILL_ZIP_BYTES: u64 = 20 * 1024 * 1024;
+pub(crate) const INSTRUCTION_56_SOL_FILENAME: &str = "gpt-5.6-sol-unrestricted.md";
+pub(crate) const INSTRUCTION_56_SOL_CONTENT: &str =
+    include_str!("../../../../examples/gpt-5.6-sol-unrestricted.md");
+
+pub(crate) const INSTRUCTION_SEAGULL_FILENAME: &str = "海鸥3.0破甲.md";
+pub(crate) const INSTRUCTION_SEAGULL_CONTENT: &str =
+    include_str!("../../../../examples/海鸥3.0破甲.md");
+
+pub(crate) const AGENTS_FILENAME: &str = "AGENTS.md";
+pub(crate) const AGENTS_MANAGED_BEGIN: &str = "<!-- CODEX-X:INSTRUCTIONS:BEGIN -->";
+pub(crate) const AGENTS_MANAGED_END: &str = "<!-- CODEX-X:INSTRUCTIONS:END -->";
+pub(crate) const AGENTS_TEMPLATE_PREFIX: &str = "<!-- CODEX-X:TEMPLATE:";
+pub(crate) const JSDELIVR_EXAMPLES_API: &str =
+    "https://data.jsdelivr.com/v1/packages/gh/yynxxxxx/Codex-X@main?structure=flat";
+pub(crate) const JSDELIVR_EXAMPLES_BASE: &str =
+    "https://cdn.jsdelivr.net/gh/yynxxxxx/Codex-X@main/examples/";
+pub(crate) const GITHUB_EXAMPLES_API: &str =
+    "https://api.github.com/repos/yynxxxxx/Codex-X/contents/examples?ref=main";
+pub(crate) const GITHUB_EXAMPLES_BASE: &str =
+    "https://raw.githubusercontent.com/yynxxxxx/Codex-X/main/examples/";

apps/desktop/src-tauri/src/context_config.rs

@@ -0,0 +1,235 @@
+use crate::error::{CodexxError, Result};
+use serde::{Deserialize, Serialize};
+use toml_edit::{value, DocumentMut};
+
+const CONTEXT_WINDOW: &str = "model_context_window";
+const COMPACT_TOKEN_LIMIT: &str = "model_auto_compact_token_limit";
+const ONE_MILLION: i64 = 1_000_000;
+const DEFAULT_COMPACT_LIMIT: i64 = 900_000;
+
+#[derive(Debug, Clone, Deserialize, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub(crate) struct ContextWindowValues {
+    pub(crate) context_window: Option<i64>,
+    pub(crate) compact_token_limit: Option<i64>,
+}
+
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub(crate) struct ContextWindowConfig {
+    pub(crate) config_text: String,
+    pub(crate) enabled: bool,
+    #[serde(flatten)]
+    pub(crate) values: ContextWindowValues,
+}
+
+fn read_integer(doc: &DocumentMut, key: &str) -> Result<Option<i64>> {
+    doc.get(key)
+        .map(|item| {
+            item.as_integer()
+                .ok_or_else(|| CodexxError::Config(format!("{key} 必须为整数")))
+        })
+        .transpose()
+}
+
+fn write_integer(doc: &mut DocumentMut, key: &str, number: i64) {
+    // Keep existing inline comments and spacing when replacing a setting.
+    let decor = doc
+        .get(key)
+        .and_then(|item| item.as_value())
+        .map(|value| value.decor().clone());
+    doc[key] = value(number);
+    if let Some(decor) = decor {
+        *doc[key].as_value_mut().expect("integer value").decor_mut() = decor;
+    }
+}
+
+fn restore_integer(doc: &mut DocumentMut, key: &str, number: Option<i64>) {
+    if let Some(number) = number {
+        write_integer(doc, key, number);
+    } else {
+        doc.as_table_mut().remove(key);
+    }
+}
+
+/// Edits a supplied draft only; this never reads or writes the live configuration.
+/// `enabled = None` parses the checkbox state after a manual TOML edit.
+pub(crate) fn update_codex_context_window_inner(
+    config_text: String,
+    enabled: Option<bool>,
+    previous_values: Option<ContextWindowValues>,
+) -> Result<ContextWindowConfig> {
+    let mut doc = config_text
+        .parse::<DocumentMut>()
+        .map_err(|error| CodexxError::Toml {
+            path: "config.toml".to_string(),
+            message: error.to_string(),
+        })?;
+    let context_window = read_integer(&doc, CONTEXT_WINDOW)?;
+    let compact_token_limit = read_integer(&doc, COMPACT_TOKEN_LIMIT)?;
+
+    match enabled {
+        Some(true) => {
+            write_integer(&mut doc, CONTEXT_WINDOW, ONE_MILLION);
+            if compact_token_limit.is_none() {
+                write_integer(&mut doc, COMPACT_TOKEN_LIMIT, DEFAULT_COMPACT_LIMIT);
+            }
+        }
+        Some(false) => {
+            // Only undo the 1M preset. A manual edit to either value wins.
+            if context_window == Some(ONE_MILLION) {
+                restore_integer(
+                    &mut doc,
+                    CONTEXT_WINDOW,
+                    previous_values
+                        .as_ref()
+                        .and_then(|values| values.context_window),
+                );
+            }
+            let expected_compact_limit = previous_values
+                .as_ref()
+                .and_then(|values| values.compact_token_limit)
+                .unwrap_or(DEFAULT_COMPACT_LIMIT);
+            if compact_token_limit == Some(expected_compact_limit) {
+                restore_integer(
+                    &mut doc,
+                    COMPACT_TOKEN_LIMIT,
+                    previous_values
+                        .as_ref()
+                        .and_then(|values| values.compact_token_limit),
+                );
+            }
+        }
+        None => {}
+    }
+
+    let context_window = read_integer(&doc, CONTEXT_WINDOW)?;
+    let compact_token_limit = read_integer(&doc, COMPACT_TOKEN_LIMIT)?;
+    Ok(ContextWindowConfig {
+        config_text: if enabled.is_none() {
+            config_text
+        } else {
+            doc.to_string()
+        },
+        enabled: context_window == Some(ONE_MILLION),
+        values: ContextWindowValues {
+            context_window,
+            compact_token_limit,
+        },
+    })
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn enables_at_top_level_and_preserves_unrelated_tables_and_comments() {
+        let original = "# My Codex settings\nmodel = \"gpt-5.5\" # keep model\n\n[mcp_servers.notes]\ncommand = \"notes\"\nmodel_context_window = 120000\n\n[model_providers.custom]\nbase_url = \"https://api.example.test/v1\"\n";
+        let result = update_codex_context_window_inner(original.into(), Some(true), None).unwrap();
+        let doc = result.config_text.parse::<DocumentMut>().unwrap();
+        assert_eq!(doc[CONTEXT_WINDOW].as_integer(), Some(ONE_MILLION));
+        assert_eq!(
+            doc[COMPACT_TOKEN_LIMIT].as_integer(),
+            Some(DEFAULT_COMPACT_LIMIT)
+        );
+        assert_eq!(
+            doc["mcp_servers"]["notes"][CONTEXT_WINDOW].as_integer(),
+            Some(120000)
+        );
+        assert!(result.config_text.contains("# My Codex settings"));
+        assert!(result
+            .config_text
+            .contains("model = \"gpt-5.5\" # keep model"));
+        assert!(result
+            .config_text
+            .contains("base_url = \"https://api.example.test/v1\""));
+    }
+
+    #[test]
+    fn parses_underscores_and_quoted_keys_without_reformatting_the_draft() {
+        let original = "\"model_context_window\" = 1_000_000 # large\nmodel_auto_compact_token_limit = 850_000\n";
+        let result = update_codex_context_window_inner(original.into(), None, None).unwrap();
+        assert!(result.enabled);
+        assert_eq!(result.values.compact_token_limit, Some(850000));
+        assert_eq!(result.config_text, original);
+    }
+
+    #[test]
+    fn ignores_context_values_in_tables_or_multiline_strings() {
+        let original = "instructions = '''\nmodel_context_window = 1000000\n'''\n[profiles.large]\nmodel_context_window = 1000000\n";
+        let result = update_codex_context_window_inner(original.into(), None, None).unwrap();
+        assert!(!result.enabled);
+        assert_eq!(result.values.context_window, None);
+    }
+
+    #[test]
+    fn preserves_custom_compaction_when_enabling_and_disabling() {
+        let original = "model_auto_compact_token_limit = 850000 # custom\n";
+        let enabled = update_codex_context_window_inner(original.into(), Some(true), None).unwrap();
+        assert_eq!(enabled.values.compact_token_limit, Some(850000));
+        let disabled =
+            update_codex_context_window_inner(enabled.config_text, Some(false), None).unwrap();
+        assert_eq!(disabled.values.context_window, None);
+        assert_eq!(disabled.config_text, original);
+    }
+
+    #[test]
+    fn restores_custom_context_and_existing_default_compaction_in_same_edit() {
+        let original = "model_context_window = 256000 # original\nmodel_auto_compact_token_limit = 900000 # intentional\n";
+        let parsed = update_codex_context_window_inner(original.into(), None, None).unwrap();
+        let enabled = update_codex_context_window_inner(original.into(), Some(true), None).unwrap();
+        let disabled = update_codex_context_window_inner(
+            enabled.config_text,
+            Some(false),
+            Some(parsed.values),
+        )
+        .unwrap();
+        assert_eq!(disabled.config_text, original);
+    }
+
+    #[test]
+    fn disabling_a_saved_preset_removes_both_default_values() {
+        let original = "model = \"gpt-5.5\"\n";
+        let enabled = update_codex_context_window_inner(original.into(), Some(true), None).unwrap();
+        let disabled =
+            update_codex_context_window_inner(enabled.config_text, Some(false), None).unwrap();
+        assert_eq!(disabled.config_text, original);
+        assert!(!disabled.enabled);
+    }
+
+    #[test]
+    fn disabling_does_not_undo_new_manual_values() {
+        let manual = "model_context_window = 500000\nmodel_auto_compact_token_limit = 420000\n";
+        let result = update_codex_context_window_inner(
+            manual.into(),
+            Some(false),
+            Some(ContextWindowValues {
+                context_window: Some(256000),
+                compact_token_limit: Some(200000),
+            }),
+        )
+        .unwrap();
+        assert_eq!(result.config_text, manual);
+    }
+
+    #[test]
+    fn rejects_invalid_toml_and_invalid_top_level_field_types() {
+        for original in [
+            "[unfinished",
+            "model_context_window = '1000000'",
+            "model_auto_compact_token_limit = 'automatic'",
+        ] {
+            assert!(update_codex_context_window_inner(original.into(), Some(true), None).is_err());
+        }
+    }
+
+    #[test]
+    fn a_blank_draft_can_be_enabled_and_returned_to_blank() {
+        let enabled = update_codex_context_window_inner(String::new(), Some(true), None).unwrap();
+        assert!(enabled.enabled);
+        let disabled =
+            update_codex_context_window_inner(enabled.config_text, Some(false), None).unwrap();
+        assert!(disabled.config_text.is_empty());
+    }
+}

apps/desktop/src-tauri/src/desktop_lifecycle.rs

@@ -0,0 +1,164 @@
+use tauri::{
+    menu::{Menu, MenuItem},
+    tray::{MouseButton, MouseButtonState, TrayIconBuilder, TrayIconEvent},
+    Emitter, Manager, WindowEvent,
+};
+
+const MAIN_WINDOW_LABEL: &str = "main";
+const TRAY_ID: &str = "codex-x-tray";
+const SHOW_WINDOW_MENU_ID: &str = "show-main-window";
+const QUIT_APP_MENU_ID: &str = "quit-codex-x";
+const SHOW_TRAY_MENU_ON_LEFT_CLICK: bool = cfg!(target_os = "macos");
+
+#[cfg(target_os = "macos")]
+fn set_macos_tray_mode(app: &tauri::AppHandle, dock_visible: bool) -> tauri::Result<()> {
+    let policy = if dock_visible {
+        tauri::ActivationPolicy::Regular
+    } else {
+        tauri::ActivationPolicy::Accessory
+    };
+
+    // Attempt both operations: either one alone can leave a stale Dock entry on some macOS versions.
+    let dock_result = app.set_dock_visibility(dock_visible);
+    let policy_result = app.set_activation_policy(policy);
+    dock_result?;
+    policy_result
+}
+
+fn retain_first_error(first_error: &mut Option<tauri::Error>, result: tauri::Result<()>) {
+    if let Err(error) = result {
+        if first_error.is_none() {
+            *first_error = Some(error);
+        }
+    }
+}
+
+fn show_main_window(app: &tauri::AppHandle) -> tauri::Result<()> {
+    let Some(window) = app.get_webview_window(MAIN_WINDOW_LABEL) else {
+        return Ok(());
+    };
+
+    let mut first_error = None;
+
+    #[cfg(target_os = "windows")]
+    retain_first_error(&mut first_error, window.set_skip_taskbar(false));
+    #[cfg(target_os = "macos")]
+    retain_first_error(&mut first_error, app.show());
+
+    retain_first_error(&mut first_error, window.unminimize());
+    retain_first_error(&mut first_error, window.show());
+    retain_first_error(&mut first_error, window.set_focus());
+
+    #[cfg(target_os = "macos")]
+    retain_first_error(&mut first_error, set_macos_tray_mode(app, true));
+
+    first_error.map_or(Ok(()), Err)
+}
+
+pub(crate) fn restore_main_window(app: &tauri::AppHandle) {
+    if let Err(error) = show_main_window(app) {
+        eprintln!("failed to restore the Codex-X window: {error}");
+    }
+}
+
+pub(crate) fn setup_system_tray(app: &tauri::App) -> tauri::Result<()> {
+    let show_window =
+        MenuItem::with_id(app, SHOW_WINDOW_MENU_ID, "显示 Codex-X", true, None::<&str>)?;
+    let quit_app = MenuItem::with_id(app, QUIT_APP_MENU_ID, "退出 Codex-X", true, None::<&str>)?;
+    let menu = Menu::with_items(app, &[&show_window, &quit_app])?;
+
+    let mut tray = TrayIconBuilder::with_id(TRAY_ID)
+        .menu(&menu)
+        .tooltip("Codex-X")
+        .show_menu_on_left_click(SHOW_TRAY_MENU_ON_LEFT_CLICK)
+        .on_menu_event(|app, event| match event.id().as_ref() {
+            SHOW_WINDOW_MENU_ID => restore_main_window(app),
+            QUIT_APP_MENU_ID => app.exit(0),
+            _ => {}
+        })
+        .on_tray_icon_event(|tray, event| {
+            if !SHOW_TRAY_MENU_ON_LEFT_CLICK
+                && matches!(
+                    event,
+                    TrayIconEvent::Click {
+                        button: MouseButton::Left,
+                        button_state: MouseButtonState::Up,
+                        ..
+                    }
+                )
+            {
+                restore_main_window(tray.app_handle());
+            }
+        });
+
+    if let Some(icon) = app.default_window_icon().cloned() {
+        tray = tray.icon(icon);
+    }
+
+    tray.build(app)?;
+    Ok(())
+}
+
+pub(crate) fn handle_window_event(window: &tauri::Window, event: &WindowEvent) {
+    if window.label() != MAIN_WINDOW_LABEL {
+        return;
+    }
+
+    if let WindowEvent::CloseRequested { api, .. } = event {
+        api.prevent_close();
+        if let Err(error) = window.hide() {
+            eprintln!("failed to hide the Codex-X window: {error}");
+            return;
+        }
+
+        #[cfg(target_os = "windows")]
+        if let Err(error) = window.set_skip_taskbar(true) {
+            eprintln!("failed to remove Codex-X from the taskbar: {error}");
+        }
+
+        #[cfg(target_os = "macos")]
+        if let Err(error) = set_macos_tray_mode(window.app_handle(), false) {
+            eprintln!("failed to move Codex-X to the menu bar: {error}");
+        }
+    }
+}
+
+pub(crate) fn report_failover_lifecycle_error(app: &tauri::AppHandle, title: &str, reason: &str) {
+    let title = title.to_string();
+    let reason = reason.to_string();
+    eprintln!("{title}: {reason}");
+    let _ = app.emit("provider-failover-error", &reason);
+    tauri::async_runtime::spawn(async move {
+        rfd::AsyncMessageDialog::new()
+            .set_title(title)
+            .set_description(reason)
+            .set_level(rfd::MessageLevel::Error)
+            .set_buttons(rfd::MessageButtons::Ok)
+            .show()
+            .await;
+    });
+}
+
+pub(crate) fn handle_run_event(app: &tauri::AppHandle, event: tauri::RunEvent) {
+    if let tauri::RunEvent::ExitRequested { api, .. } = &event {
+        if let Err(error) = crate::failover::shutdown_all() {
+            // Keep the listener alive when restoring the direct route failed.
+            // Exiting here would strand Codex on a local address with no server.
+            api.prevent_exit();
+            restore_main_window(app);
+            report_failover_lifecycle_error(
+                app,
+                "暂时无法退出 Codex-X",
+                &format!("自动切换的连接配置还未恢复，Codex-X 将继续运行。\n\n{error}\n\n请检查配置文件是否被占用，再重试退出。"),
+            );
+        }
+    }
+
+    #[cfg(target_os = "macos")]
+    if let tauri::RunEvent::Reopen { .. } = event {
+        restore_main_window(app);
+    }
+
+    #[cfg(not(target_os = "macos"))]
+    let _ = (app, event);
+}

apps/desktop/src-tauri/src/error.rs

@@ -0,0 +1,37 @@
+use serde::Serializer;
+use thiserror::Error;
+
+#[derive(Debug, Error)]
+pub(crate) enum CodexxError {
+    #[error("无法获取用户主目录")]
+    NoHomeDir,
+    #[error("IO error at {path}: {source}")]
+    Io {
+        path: String,
+        #[source]
+        source: std::io::Error,
+    },
+    #[error("TOML parse error at {path}: {message}")]
+    Toml { path: String, message: String },
+    #[error("JSON error at {path}: {source}")]
+    Json {
+        path: String,
+        #[source]
+        source: serde_json::Error,
+    },
+    #[error("配置错误: {0}")]
+    Config(String),
+    #[error("SQLite error: {0}")]
+    Database(String),
+}
+
+pub(crate) type Result<T> = std::result::Result<T, CodexxError>;
+
+impl serde::Serialize for CodexxError {
+    fn serialize<S>(&self, serializer: S) -> std::result::Result<S::Ok, S::Error>
+    where
+        S: Serializer,
+    {
+        serializer.serialize_str(&self.to_string())
+    }
+}

apps/desktop/src-tauri/src/failover/circuit_breaker.rs

@@ -0,0 +1,638 @@
+// Adapted from CC Switch 06082e189d65e6d6dbadc35dacdac1ce6c79d89a,
+// src-tauri/src/proxy/circuit_breaker.rs. The state transitions and counters
+// retain the upstream behavior; locks are synchronous and logs are omitted.
+//
+// MIT License
+//
+// Copyright (c) 2025 Jason Young
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in all
+// copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+// SOFTWARE.
+
+//! 熔断器模块
+//!
+//! 实现熔断器模式，用于防止向不健康的供应商发送请求
+
+use super::config::RoutingTuning;
+use serde::{Deserialize, Serialize};
+use std::sync::atomic::{AtomicU32, Ordering};
+use std::sync::Arc;
+use std::time::Instant;
+// The upstream state machine is retained; Codex-X forwards on bounded blocking
+// workers, so its short state locks use std rather than awaiting Tokio locks.
+struct RwLock<T>(std::sync::RwLock<T>);
+impl<T> RwLock<T> {
+    fn new(value: T) -> Self {
+        Self(std::sync::RwLock::new(value))
+    }
+    fn read(&self) -> std::sync::RwLockReadGuard<'_, T> {
+        self.0.read().unwrap_or_else(|error| error.into_inner())
+    }
+    fn write(&self) -> std::sync::RwLockWriteGuard<'_, T> {
+        self.0.write().unwrap_or_else(|error| error.into_inner())
+    }
+}
+
+/// 熔断器状态
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum CircuitState {
+    /// 关闭状态 - 正常工作
+    Closed,
+    /// 打开状态 - 熔断激活，拒绝请求
+    Open,
+    /// 半开状态 - 尝试恢复，允许部分请求通过
+    HalfOpen,
+}
+
+impl std::fmt::Display for CircuitState {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            CircuitState::Closed => write!(f, "closed"),
+            CircuitState::Open => write!(f, "open"),
+            CircuitState::HalfOpen => write!(f, "half_open"),
+        }
+    }
+}
+
+/// 熔断器配置
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct CircuitBreakerConfig {
+    /// 失败阈值 - 连续失败多少次后打开熔断器
+    pub failure_threshold: u32,
+    /// 成功阈值 - 半开状态下成功多少次后关闭熔断器
+    pub success_threshold: u32,
+    /// 超时时间 - 熔断器打开后多久尝试半开（秒）
+    pub timeout_seconds: u64,
+    /// 错误率阈值 - 错误率超过此值时打开熔断器 (0.0-1.0)
+    pub error_rate_threshold: f64,
+    /// 最小请求数 - 计算错误率前的最小请求数
+    pub min_requests: u32,
+}
+
+impl From<&RoutingTuning> for CircuitBreakerConfig {
+    fn from(config: &RoutingTuning) -> Self {
+        Self {
+            failure_threshold: config.circuit_failure_threshold,
+            success_threshold: config.circuit_success_threshold,
+            timeout_seconds: config.circuit_timeout_seconds as u64,
+            error_rate_threshold: config.circuit_error_rate_threshold,
+            min_requests: config.circuit_min_requests,
+        }
+    }
+}
+
+impl Default for CircuitBreakerConfig {
+    fn default() -> Self {
+        Self {
+            failure_threshold: 4,
+            success_threshold: 2,
+            timeout_seconds: 60,
+            error_rate_threshold: 0.6,
+            min_requests: 10,
+        }
+    }
+}
+
+/// 熔断器实例
+pub struct CircuitBreaker {
+    /// 当前状态
+    state: Arc<RwLock<CircuitState>>,
+    /// 连续失败计数
+    consecutive_failures: Arc<AtomicU32>,
+    /// 连续成功计数（半开状态）
+    consecutive_successes: Arc<AtomicU32>,
+    /// 总请求计数
+    total_requests: Arc<AtomicU32>,
+    /// 失败请求计数
+    failed_requests: Arc<AtomicU32>,
+    /// 上次打开时间
+    last_opened_at: Arc<RwLock<Option<Instant>>>,
+    /// 配置（支持热更新）
+    config: Arc<RwLock<CircuitBreakerConfig>>,
+    /// 半开状态已放行的请求数（用于限流）
+    half_open_requests: Arc<AtomicU32>,
+}
+
+/// 熔断器放行结果
+///
+/// `used_half_open_permit` 表示本次放行是否占用了 HalfOpen 探测名额。
+/// 调用方应在请求结束后把该值传回 `record_success` / `record_failure` 用于正确释放名额。
+#[derive(Debug, Clone, Copy)]
+pub struct AllowResult {
+    pub allowed: bool,
+    pub used_half_open_permit: bool,
+}
+
+impl CircuitBreaker {
+    /// 创建新的熔断器
+    pub fn new(config: CircuitBreakerConfig) -> Self {
+        Self {
+            state: Arc::new(RwLock::new(CircuitState::Closed)),
+            consecutive_failures: Arc::new(AtomicU32::new(0)),
+            consecutive_successes: Arc::new(AtomicU32::new(0)),
+            total_requests: Arc::new(AtomicU32::new(0)),
+            failed_requests: Arc::new(AtomicU32::new(0)),
+            last_opened_at: Arc::new(RwLock::new(None)),
+            config: Arc::new(RwLock::new(config)),
+            half_open_requests: Arc::new(AtomicU32::new(0)),
+        }
+    }
+
+    /// 更新熔断器配置（热更新，不重置状态）
+    pub fn update_config(&self, new_config: CircuitBreakerConfig) {
+        *self.config.write() = new_config;
+    }
+
+    /// 判断当前 Provider 是否“可被纳入候选链路”
+    ///
+    /// 这个方法不会占用 HalfOpen 探测名额，仅用于路由选择阶段的“可用性判断”：
+    /// - Closed / HalfOpen：可用（返回 true）
+    /// - Open：若超时到达则切到 HalfOpen 并返回 true，否则返回 false
+    ///
+    /// 注意：真正发起请求前仍需调用 `allow_request()` 来获取 HalfOpen 探测名额，
+    /// 并在请求结束后通过 `record_success()` / `record_failure()` 释放。
+    pub fn is_available(&self) -> bool {
+        let state = *self.state.read();
+        let config = self.config.read();
+
+        match state {
+            CircuitState::Closed | CircuitState::HalfOpen => true,
+            CircuitState::Open => {
+                if let Some(opened_at) = *self.last_opened_at.read() {
+                    if opened_at.elapsed().as_secs() >= config.timeout_seconds {
+                        drop(config); // 释放读锁再转换状态
+                        self.transition_to_half_open();
+                        return true;
+                    }
+                }
+                false
+            }
+        }
+    }
+
+    /// 检查是否允许请求通过
+    pub fn allow_request(&self) -> AllowResult {
+        let state = *self.state.read();
+
+        match state {
+            CircuitState::Closed => AllowResult {
+                allowed: true,
+                used_half_open_permit: false,
+            },
+            CircuitState::Open => {
+                let config = self.config.read();
+                // 检查是否应该尝试半开
+                if let Some(opened_at) = *self.last_opened_at.read() {
+                    if opened_at.elapsed().as_secs() >= config.timeout_seconds {
+                        drop(config); // 释放读锁再转换状态
+                        self.transition_to_half_open();
+
+                        // 转换后按当前状态决定是否需要获取 HalfOpen 探测名额
+                        let current_state = *self.state.read();
+                        return match current_state {
+                            CircuitState::Closed => AllowResult {
+                                allowed: true,
+                                used_half_open_permit: false,
+                            },
+                            CircuitState::HalfOpen => self.allow_half_open_probe(),
+                            CircuitState::Open => AllowResult {
+                                allowed: false,
+                                used_half_open_permit: false,
+                            },
+                        };
+                    }
+                }
+
+                AllowResult {
+                    allowed: false,
+                    used_half_open_permit: false,
+                }
+            }
+            CircuitState::HalfOpen => self.allow_half_open_probe(),
+        }
+    }
+
+    /// 记录成功
+    pub fn record_success(&self, used_half_open_permit: bool) {
+        let state = *self.state.read();
+        let config = self.config.read();
+
+        if used_half_open_permit {
+            self.release_half_open_permit();
+        }
+
+        // 重置失败计数
+        self.consecutive_failures.store(0, Ordering::SeqCst);
+        self.total_requests.fetch_add(1, Ordering::SeqCst);
+
+        if state == CircuitState::HalfOpen {
+            let successes = self.consecutive_successes.fetch_add(1, Ordering::SeqCst) + 1;
+
+            if successes >= config.success_threshold {
+                drop(config); // 释放读锁再转换状态
+                self.transition_to_closed();
+            }
+        }
+    }
+
+    /// 记录失败
+    pub fn record_failure(&self, used_half_open_permit: bool) {
+        let state = *self.state.read();
+        let config = self.config.read();
+
+        if used_half_open_permit {
+            self.release_half_open_permit();
+        }
+
+        // 更新计数器
+        let failures = self.consecutive_failures.fetch_add(1, Ordering::SeqCst) + 1;
+        self.total_requests.fetch_add(1, Ordering::SeqCst);
+        self.failed_requests.fetch_add(1, Ordering::SeqCst);
+
+        // 重置成功计数
+        self.consecutive_successes.store(0, Ordering::SeqCst);
+
+        // 检查是否应该打开熔断器
+        match state {
+            CircuitState::HalfOpen => {
+                // HalfOpen 状态下失败，立即转为 Open
+                drop(config);
+                self.transition_to_open();
+            }
+            CircuitState::Closed => {
+                // 检查连续失败次数
+                if failures >= config.failure_threshold {
+                    drop(config); // 释放读锁再转换状态
+                    self.transition_to_open();
+                } else {
+                    // 检查错误率
+                    let total = self.total_requests.load(Ordering::SeqCst);
+                    let failed = self.failed_requests.load(Ordering::SeqCst);
+
+                    if total >= config.min_requests {
+                        let error_rate = failed as f64 / total as f64;
+
+                        if error_rate >= config.error_rate_threshold {
+                            drop(config); // 释放读锁再转换状态
+                            self.transition_to_open();
+                        }
+                    }
+                }
+            }
+            _ => {}
+        }
+    }
+
+    /// 获取当前状态
+    #[allow(dead_code)]
+    pub fn get_state(&self) -> CircuitState {
+        *self.state.read()
+    }
+
+    /// 获取统计信息
+    #[allow(dead_code)]
+    pub fn get_stats(&self) -> CircuitBreakerStats {
+        CircuitBreakerStats {
+            state: *self.state.read(),
+            consecutive_failures: self.consecutive_failures.load(Ordering::SeqCst),
+            consecutive_successes: self.consecutive_successes.load(Ordering::SeqCst),
+            total_requests: self.total_requests.load(Ordering::SeqCst),
+            failed_requests: self.failed_requests.load(Ordering::SeqCst),
+        }
+    }
+
+    pub(crate) fn cooldown_seconds(&self) -> u64 {
+        if *self.state.read() != CircuitState::Open {
+            return 0;
+        }
+        let config = self.config.read();
+        self.last_opened_at.read().as_ref().map_or(0, |opened| {
+            config
+                .timeout_seconds
+                .saturating_sub(opened.elapsed().as_secs())
+        })
+    }
+
+    /// 重置熔断器（手动恢复）
+    #[allow(dead_code)]
+    pub fn reset(&self) {
+        self.transition_to_closed();
+    }
+
+    fn allow_half_open_probe(&self) -> AllowResult {
+        // 半开状态限流：只允许有限请求通过进行探测
+        let max_half_open_requests = 1u32;
+        let current = self.half_open_requests.fetch_add(1, Ordering::SeqCst);
+
+        if current < max_half_open_requests {
+            AllowResult {
+                allowed: true,
+                used_half_open_permit: true,
+            }
+        } else {
+            // 超过限额，回退计数，拒绝请求
+            self.half_open_requests.fetch_sub(1, Ordering::SeqCst);
+            AllowResult {
+                allowed: false,
+                used_half_open_permit: false,
+            }
+        }
+    }
+
+    /// 仅释放 HalfOpen permit，不影响健康统计
+    ///
+    /// 用于整流器等场景：请求结果不应计入 Provider 健康度，
+    /// 但仍需释放占用的探测名额，避免 HalfOpen 状态卡死
+    pub fn release_half_open_permit(&self) {
+        let mut current = self.half_open_requests.load(Ordering::SeqCst);
+        loop {
+            if current == 0 {
+                return;
+            }
+
+            match self.half_open_requests.compare_exchange(
+                current,
+                current - 1,
+                Ordering::SeqCst,
+                Ordering::SeqCst,
+            ) {
+                Ok(_) => return,
+                Err(actual) => current = actual,
+            }
+        }
+    }
+
+    /// 转换到打开状态
+    fn transition_to_open(&self) {
+        *self.state.write() = CircuitState::Open;
+        *self.last_opened_at.write() = Some(Instant::now());
+        self.consecutive_failures.store(0, Ordering::SeqCst);
+        self.consecutive_successes.store(0, Ordering::SeqCst);
+    }
+
+    /// 转换到半开状态
+    fn transition_to_half_open(&self) {
+        let mut state = self.state.write();
+        if *state != CircuitState::Open {
+            return;
+        }
+
+        *state = CircuitState::HalfOpen;
+        self.consecutive_successes.store(0, Ordering::SeqCst);
+        // 重置半开状态的请求限流计数
+        self.half_open_requests.store(0, Ordering::SeqCst);
+    }
+
+    /// 转换到关闭状态
+    fn transition_to_closed(&self) {
+        *self.state.write() = CircuitState::Closed;
+        self.consecutive_failures.store(0, Ordering::SeqCst);
+        self.consecutive_successes.store(0, Ordering::SeqCst);
+        // 重置计数器
+        self.total_requests.store(0, Ordering::SeqCst);
+        self.failed_requests.store(0, Ordering::SeqCst);
+    }
+}
+
+/// 熔断器统计信息
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct CircuitBreakerStats {
+    pub state: CircuitState,
+    pub consecutive_failures: u32,
+    pub consecutive_successes: u32,
+    pub total_requests: u32,
+    pub failed_requests: u32,
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_circuit_breaker_closed_to_open() {
+        let config = CircuitBreakerConfig {
+            failure_threshold: 3,
+            ..Default::default()
+        };
+        let breaker = CircuitBreaker::new(config);
+
+        // 初始状态应该是关闭
+        assert_eq!(breaker.get_state(), CircuitState::Closed);
+        assert!(breaker.allow_request().allowed);
+
+        // 记录 3 次失败
+        for _ in 0..3 {
+            breaker.record_failure(false);
+        }
+
+        // 应该转换到打开状态
+        assert_eq!(breaker.get_state(), CircuitState::Open);
+        assert!(!breaker.allow_request().allowed);
+    }
+
+    #[test]
+    fn test_circuit_breaker_half_open_to_closed() {
+        let config = CircuitBreakerConfig {
+            failure_threshold: 2,
+            success_threshold: 2,
+            ..Default::default()
+        };
+        let breaker = CircuitBreaker::new(config);
+
+        // 打开熔断器
+        breaker.record_failure(false);
+        breaker.record_failure(false);
+        assert_eq!(breaker.get_state(), CircuitState::Open);
+
+        // 手动转换到半开状态
+        breaker.transition_to_half_open();
+        assert_eq!(breaker.get_state(), CircuitState::HalfOpen);
+
+        // 记录 2 次成功
+        breaker.record_success(false);
+        breaker.record_success(false);
+
+        // 应该转换到关闭状态
+        assert_eq!(breaker.get_state(), CircuitState::Closed);
+    }
+
+    #[test]
+    fn test_half_open_transition_does_not_reset_inflight_permit() {
+        let config = CircuitBreakerConfig {
+            timeout_seconds: 0,
+            ..Default::default()
+        };
+        let breaker = CircuitBreaker::new(config);
+
+        // 进入 Open，然后由于 timeout_seconds=0，allow_request 会立即切换到 HalfOpen 并占用探测名额
+        breaker.transition_to_open();
+        let first = breaker.allow_request();
+        assert!(first.allowed);
+        assert!(first.used_half_open_permit);
+        assert_eq!(breaker.get_state(), CircuitState::HalfOpen);
+
+        // 模拟并发下的“重复 HalfOpen 转换调用”，不应重置 in-flight 计数
+        breaker.transition_to_half_open();
+
+        // 由于名额仍被占用，第二次请求应被拒绝
+        let second = breaker.allow_request();
+        assert!(!second.allowed);
+        assert!(!second.used_half_open_permit);
+    }
+
+    #[test]
+    fn test_circuit_breaker_reset() {
+        let config = CircuitBreakerConfig {
+            failure_threshold: 2,
+            ..Default::default()
+        };
+        let breaker = CircuitBreaker::new(config);
+
+        // 打开熔断器
+        breaker.record_failure(false);
+        breaker.record_failure(false);
+        assert_eq!(breaker.get_state(), CircuitState::Open);
+
+        // 重置
+        breaker.reset();
+        assert_eq!(breaker.get_state(), CircuitState::Closed);
+        assert!(breaker.allow_request().allowed);
+    }
+
+    #[test]
+    fn error_rate_waits_for_minimum_requests_and_uses_inclusive_threshold() {
+        let config = CircuitBreakerConfig {
+            failure_threshold: 20,
+            min_requests: 5,
+            error_rate_threshold: 0.6,
+            ..Default::default()
+        };
+        let breaker = CircuitBreaker::new(config.clone());
+        breaker.record_failure(false);
+        breaker.record_success(false);
+        breaker.record_failure(false);
+        breaker.record_success(false);
+        assert_eq!(breaker.get_stats().total_requests, 4);
+        assert_eq!(breaker.get_state(), CircuitState::Closed);
+        breaker.record_failure(false);
+        assert_eq!(breaker.get_state(), CircuitState::Open);
+        let higher = CircuitBreaker::new(CircuitBreakerConfig {
+            error_rate_threshold: 0.8,
+            ..config.clone()
+        });
+        let minimum = CircuitBreaker::new(CircuitBreakerConfig {
+            min_requests: 10,
+            ..config
+        });
+        for breaker in [&higher, &minimum] {
+            breaker.record_failure(false);
+            breaker.record_success(false);
+            breaker.record_failure(false);
+            breaker.record_success(false);
+            breaker.record_failure(false);
+            assert_eq!(breaker.get_state(), CircuitState::Closed);
+        }
+    }
+
+    #[test]
+    fn successes_break_consecutive_failures_without_clearing_error_rate_history() {
+        let breaker = CircuitBreaker::new(CircuitBreakerConfig {
+            failure_threshold: 2,
+            min_requests: 100,
+            ..Default::default()
+        });
+        breaker.record_failure(false);
+        breaker.record_success(false);
+        breaker.record_failure(false);
+        assert_eq!(breaker.get_state(), CircuitState::Closed);
+        assert_eq!(breaker.get_stats().failed_requests, 2);
+        assert_eq!(breaker.get_stats().consecutive_failures, 1);
+        breaker.record_failure(false);
+        assert_eq!(breaker.get_state(), CircuitState::Open);
+        assert_eq!(breaker.get_stats().total_requests, 4);
+    }
+
+    #[test]
+    fn recovery_wait_and_hot_configuration_preserve_existing_evidence() {
+        let mut config = CircuitBreakerConfig {
+            failure_threshold: 1,
+            timeout_seconds: 2,
+            ..Default::default()
+        };
+        let breaker = CircuitBreaker::new(config.clone());
+        breaker.record_failure(false);
+        *breaker.last_opened_at.write() = Some(Instant::now() - std::time::Duration::from_secs(1));
+        assert!(!breaker.allow_request().allowed);
+        assert_eq!(breaker.cooldown_seconds(), 1);
+        config.timeout_seconds = 1;
+        breaker.update_config(config);
+        assert_eq!(breaker.get_stats().failed_requests, 1);
+        let probe = breaker.allow_request();
+        assert!(probe.allowed && probe.used_half_open_permit);
+        assert_eq!(breaker.get_state(), CircuitState::HalfOpen);
+        assert!(!breaker.allow_request().allowed);
+        breaker.release_half_open_permit();
+        let probe = breaker.allow_request();
+        assert!(probe.allowed);
+        breaker.record_failure(probe.used_half_open_permit);
+        assert_eq!(breaker.get_state(), CircuitState::Open);
+        assert!(!breaker.allow_request().allowed);
+    }
+
+    #[test]
+    fn half_open_requires_configured_successes_and_reset_clears_all_statistics() {
+        let breaker = CircuitBreaker::new(CircuitBreakerConfig {
+            failure_threshold: 1,
+            success_threshold: 3,
+            timeout_seconds: 0,
+            ..Default::default()
+        });
+        breaker.record_failure(false);
+        for completed in 0..3 {
+            let probe = breaker.allow_request();
+            assert!(probe.allowed && probe.used_half_open_permit);
+            assert!(!breaker.allow_request().allowed);
+            breaker.record_success(probe.used_half_open_permit);
+            assert_eq!(
+                breaker.get_state(),
+                if completed < 2 {
+                    CircuitState::HalfOpen
+                } else {
+                    CircuitState::Closed
+                }
+            );
+        }
+        assert_eq!(breaker.get_stats().total_requests, 0);
+        breaker.record_failure(false);
+        breaker.reset();
+        let stats = breaker.get_stats();
+        assert_eq!(
+            (
+                stats.total_requests,
+                stats.failed_requests,
+                stats.consecutive_failures,
+                stats.consecutive_successes
+            ),
+            (0, 0, 0, 0)
+        );
+        assert!(breaker.allow_request().allowed);
+    }
+}

apps/desktop/src-tauri/src/failover/config.rs

@@ -0,0 +1,264 @@
+//! Codex defaults/ranges follow CC Switch 06082e1 AppProxyConfig and its
+//! AutoFailoverConfigPanel. Both IPC and the UI validate these settings.
+
+use crate::error::{CodexxError, Result};
+use serde::{Deserialize, Serialize};
+use std::net::{IpAddr, Ipv4Addr, Ipv6Addr};
+
+pub(crate) const DEFAULT_LISTEN_ADDRESS: &str = "127.0.0.1";
+pub(crate) const DEFAULT_LISTEN_PORT: u16 = 15721;
+pub(crate) const MAX_QUEUE: usize = 64;
+pub(crate) const ROUTE_TOKEN_HEADER: &str = "x-codex-x-route-token";
+pub(crate) const ROUTE_GENERATION_HEADER: &str = "x-codex-x-route-generation";
+
+#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase", default)]
+pub(crate) struct RoutingTuning {
+    pub(crate) max_retries: u32,
+    pub(crate) streaming_first_byte_timeout: u64,
+    pub(crate) streaming_idle_timeout: u64,
+    pub(crate) non_streaming_timeout: u64,
+    pub(crate) circuit_failure_threshold: u32,
+    pub(crate) circuit_success_threshold: u32,
+    pub(crate) circuit_timeout_seconds: u64,
+    pub(crate) circuit_error_rate_threshold: f64,
+    pub(crate) circuit_min_requests: u32,
+}
+
+impl Default for RoutingTuning {
+    fn default() -> Self {
+        Self {
+            max_retries: 3,
+            streaming_first_byte_timeout: 60,
+            streaming_idle_timeout: 120,
+            non_streaming_timeout: 600,
+            circuit_failure_threshold: 4,
+            circuit_success_threshold: 2,
+            circuit_timeout_seconds: 60,
+            circuit_error_rate_threshold: 0.6,
+            circuit_min_requests: 10,
+        }
+    }
+}
+
+impl RoutingTuning {
+    pub(crate) fn validate(&self) -> Result<()> {
+        for (valid, message) in [
+            (self.max_retries <= 10, "最大重试次数须为 0–10"),
+            (
+                (1..=120).contains(&self.streaming_first_byte_timeout),
+                "流式首字节超时须为 1–120 秒",
+            ),
+            (
+                self.streaming_idle_timeout <= 600,
+                "流式静默超时须为 0–600 秒，0 表示禁用",
+            ),
+            (
+                (60..=1200).contains(&self.non_streaming_timeout),
+                "非流式超时须为 60–1200 秒",
+            ),
+            (
+                (1..=20).contains(&self.circuit_failure_threshold),
+                "失败阈值须为 1–20",
+            ),
+            (
+                (1..=10).contains(&self.circuit_success_threshold),
+                "恢复成功阈值须为 1–10",
+            ),
+            (
+                self.circuit_timeout_seconds <= 300,
+                "恢复等待时间须为 0–300 秒",
+            ),
+            (
+                self.circuit_error_rate_threshold.is_finite()
+                    && (0.0..=1.0).contains(&self.circuit_error_rate_threshold),
+                "错误率阈值须为 0–100%",
+            ),
+            (
+                (5..=100).contains(&self.circuit_min_requests),
+                "最小请求数须为 5–100",
+            ),
+        ] {
+            if !valid {
+                return Err(CodexxError::Config(message.into()));
+            }
+        }
+        Ok(())
+    }
+}
+
+pub(crate) fn listen_ip(address: &str) -> Result<IpAddr> {
+    let address = address.trim();
+    if address.eq_ignore_ascii_case("localhost") {
+        return Ok(IpAddr::V4(Ipv4Addr::LOCALHOST));
+    }
+    let address = address
+        .strip_prefix('[')
+        .and_then(|value| value.strip_suffix(']'))
+        .unwrap_or(address);
+    address
+        .parse()
+        .map_err(|_| CodexxError::Config("监听地址须为 IPv4、IPv6 或 localhost".into()))
+}
+
+pub(crate) fn client_ip(address: IpAddr) -> IpAddr {
+    match address {
+        IpAddr::V4(ip) if ip.is_unspecified() => IpAddr::V4(Ipv4Addr::LOCALHOST),
+        IpAddr::V6(ip) if ip.is_unspecified() => IpAddr::V6(Ipv6Addr::LOCALHOST),
+        address => address,
+    }
+}
+
+pub(crate) fn local_url(address: IpAddr, port: u16) -> String {
+    match client_ip(address) {
+        IpAddr::V4(ip) => format!("http://{ip}:{port}/v1"),
+        IpAddr::V6(ip) => format!("http://[{ip}]:{port}/v1"),
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    #[test]
+    fn codex_defaults_and_valid_boundaries_match_reference() {
+        let defaults = RoutingTuning::default();
+        defaults.validate().unwrap();
+        assert_eq!(
+            (
+                defaults.max_retries,
+                defaults.streaming_first_byte_timeout,
+                defaults.streaming_idle_timeout,
+                defaults.non_streaming_timeout
+            ),
+            (3, 60, 120, 600)
+        );
+        assert_eq!(
+            (
+                defaults.circuit_failure_threshold,
+                defaults.circuit_success_threshold,
+                defaults.circuit_timeout_seconds,
+                defaults.circuit_min_requests
+            ),
+            (4, 2, 60, 10)
+        );
+        assert_eq!(defaults.circuit_error_rate_threshold, 0.6);
+        RoutingTuning {
+            max_retries: 0,
+            streaming_first_byte_timeout: 1,
+            streaming_idle_timeout: 0,
+            non_streaming_timeout: 60,
+            circuit_failure_threshold: 1,
+            circuit_success_threshold: 1,
+            circuit_timeout_seconds: 0,
+            circuit_error_rate_threshold: 0.0,
+            circuit_min_requests: 5,
+        }
+        .validate()
+        .unwrap();
+        RoutingTuning {
+            max_retries: 10,
+            streaming_first_byte_timeout: 120,
+            streaming_idle_timeout: 600,
+            non_streaming_timeout: 1200,
+            circuit_failure_threshold: 20,
+            circuit_success_threshold: 10,
+            circuit_timeout_seconds: 300,
+            circuit_error_rate_threshold: 1.0,
+            circuit_min_requests: 100,
+        }
+        .validate()
+        .unwrap();
+    }
+    #[test]
+    fn invalid_tuning_is_rejected_in_backend() {
+        for invalid in [
+            RoutingTuning {
+                max_retries: 11,
+                ..Default::default()
+            },
+            RoutingTuning {
+                streaming_first_byte_timeout: 0,
+                ..Default::default()
+            },
+            RoutingTuning {
+                streaming_first_byte_timeout: 121,
+                ..Default::default()
+            },
+            RoutingTuning {
+                streaming_idle_timeout: 601,
+                ..Default::default()
+            },
+            RoutingTuning {
+                non_streaming_timeout: 59,
+                ..Default::default()
+            },
+            RoutingTuning {
+                non_streaming_timeout: 1201,
+                ..Default::default()
+            },
+            RoutingTuning {
+                circuit_failure_threshold: 0,
+                ..Default::default()
+            },
+            RoutingTuning {
+                circuit_failure_threshold: 21,
+                ..Default::default()
+            },
+            RoutingTuning {
+                circuit_success_threshold: 0,
+                ..Default::default()
+            },
+            RoutingTuning {
+                circuit_success_threshold: 11,
+                ..Default::default()
+            },
+            RoutingTuning {
+                circuit_timeout_seconds: 301,
+                ..Default::default()
+            },
+            RoutingTuning {
+                circuit_error_rate_threshold: f64::NAN,
+                ..Default::default()
+            },
+            RoutingTuning {
+                circuit_error_rate_threshold: 1.1,
+                ..Default::default()
+            },
+            RoutingTuning {
+                circuit_min_requests: 4,
+                ..Default::default()
+            },
+            RoutingTuning {
+                circuit_min_requests: 101,
+                ..Default::default()
+            },
+        ] {
+            assert!(invalid.validate().is_err(), "{invalid:?}");
+        }
+    }
+    #[test]
+    fn listen_addresses_and_client_urls_support_ipv4_ipv6_and_wildcards() {
+        assert_eq!(listen_ip("localhost").unwrap().to_string(), "127.0.0.1");
+        assert_eq!(
+            local_url(listen_ip("0.0.0.0").unwrap(), 15721),
+            "http://127.0.0.1:15721/v1"
+        );
+        assert_eq!(
+            local_url(listen_ip("::").unwrap(), 15721),
+            "http://[::1]:15721/v1"
+        );
+        assert_eq!(
+            local_url(listen_ip("[::1]").unwrap(), 15721),
+            "http://[::1]:15721/v1"
+        );
+        for value in [
+            "256.0.0.1",
+            "host.example",
+            "127.0.0.1:15721",
+            "::1/path",
+            "",
+        ] {
+            assert!(listen_ip(value).is_err());
+        }
+    }
+}

apps/desktop/src-tauri/src/failover/mod.rs

@@ -0,0 +1,14 @@
+mod circuit_breaker;
+pub(crate) mod config;
+mod controller;
+pub(crate) mod native_official;
+mod proxy;
+
+#[cfg(any(test, target_os = "windows"))]
+pub(crate) use controller::resume_after_failed_update;
+
+pub(crate) use controller::{
+    attach_app_handle, direct_document, get_status, initialize, recover_stale_route,
+    refresh_saved_routes, reset_health, save_settings, shutdown_all, with_provider_change,
+    FailoverSettings, FailoverStatus,
+};

apps/desktop/src-tauri/src/failover/native_official.rs

@@ -0,0 +1,577 @@
+//! Native Codex official routing. Codex remains the owner of its login and token
+//! refresh; this layer only verifies the selected live login and forwards it to
+//! its fixed official origin. No credential is loaded from an inactive profile.
+
+use super::proxy::ProxyRoute;
+use crate::error::{CodexxError, Result};
+use crate::providers::document_is_official;
+use crate::providers::official_profiles::{list_official_profiles_inner, selected_profile_id};
+use serde_json::{json, Value};
+use sha2::{Digest, Sha256};
+use std::collections::HashSet;
+use std::fs;
+use std::io::Read;
+use std::path::{Component, Path, PathBuf};
+use toml_edit::DocumentMut;
+
+const CHATGPT_BASE: &str = "https://chatgpt.com/backend-api/codex";
+const OPENAI_API_BASE: &str = "https://api.openai.com/v1";
+const MAX_CONFIG_BYTES: usize = 2 * 1024 * 1024;
+const MAX_AUTH_BYTES: usize = 1024 * 1024;
+const MAX_CATALOG_BYTES: usize = 1024 * 1024;
+const MAX_TOKEN_BYTES: usize = 32 * 1024;
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub(crate) struct OfficialRouteSpec {
+    pub(crate) codex_dir: PathBuf,
+    pub(crate) profile_id: String,
+}
+
+// Intentionally not Debug/Serialize: these values must never appear in status,
+// frontend events, or error logs.
+pub(crate) struct OfficialRequestAuth {
+    pub(crate) authorization: String,
+    pub(crate) account_id: Option<String>,
+    pub(crate) base_url: String,
+}
+
+struct LiveAuth {
+    token: String,
+    account_id: Option<String>,
+    base_url: &'static str,
+}
+
+fn error(message: &str) -> CodexxError {
+    CodexxError::Config(message.to_owned())
+}
+
+fn read_bounded(path: &Path, limit: usize, missing_allowed: bool) -> Result<Vec<u8>> {
+    let file = match fs::File::open(path) {
+        Ok(file) => file,
+        Err(err) if missing_allowed && err.kind() == std::io::ErrorKind::NotFound => {
+            return Ok(Vec::new())
+        }
+        Err(_) => return Err(error("无法读取当前官方登录配置，请检查文件后重试")),
+    };
+    if !file
+        .metadata()
+        .is_ok_and(|metadata| metadata.is_file() && metadata.len() <= limit as u64)
+    {
+        return Err(error("当前官方登录配置无法读取，请检查文件大小和格式"));
+    }
+    let mut bytes = Vec::new();
+    file.take(limit as u64 + 1)
+        .read_to_end(&mut bytes)
+        .map_err(|_| error("读取当前官方登录配置失败，请重试"))?;
+    if bytes.len() > limit {
+        return Err(error("当前官方登录配置过大，请检查文件"));
+    }
+    Ok(bytes)
+}
+
+fn logical_document(dir: &Path) -> Result<(Vec<u8>, DocumentMut)> {
+    let bytes = read_bounded(&crate::config_path(dir), MAX_CONFIG_BYTES, true)?;
+    let text = std::str::from_utf8(&bytes)
+        .map_err(|_| error("当前 Codex 配置格式不正确，请先修复配置"))?;
+    let doc = text
+        .parse::<DocumentMut>()
+        .map_err(|_| error("当前 Codex 配置格式不正确，请先修复配置"))?;
+    let doc = super::direct_document(dir, &doc)
+        .map_err(|_| error("无法确认当前官方路由，请检查本地路由状态"))?;
+    Ok((bytes, doc))
+}
+
+fn checked_secret(value: Option<&Value>) -> Option<String> {
+    let value = value?.as_str()?.trim();
+    (!value.is_empty()
+        && value.len() <= MAX_TOKEN_BYTES
+        && value.bytes().all(|byte| byte.is_ascii_graphic())
+        && value != "PROXY_MANAGED")
+        .then(|| value.to_owned())
+}
+
+fn checked_account(value: Option<&str>) -> Result<Option<String>> {
+    let Some(value) = value.map(str::trim).filter(|value| !value.is_empty()) else {
+        return Ok(None);
+    };
+    if value.len() > 512 || !value.bytes().all(|byte| byte.is_ascii_graphic()) {
+        return Err(error("当前官方账号信息无效，请重新登录 Codex"));
+    }
+    Ok(Some(value.to_owned()))
+}
+
+fn parse_live_auth(bytes: &[u8]) -> Result<LiveAuth> {
+    let auth: Value = serde_json::from_slice(bytes)
+        .map_err(|_| error("官方账号尚未登录或认证无效，请在 Codex 中重新登录"))?;
+    if !auth.is_object()
+        || ["base_url", "baseUrl", "api_base", "endpoint"]
+            .iter()
+            .any(|key| auth.get(key).is_some())
+    {
+        return Err(error("当前官方认证格式无效，请在 Codex 中重新登录"));
+    }
+    let mode = auth.get("auth_mode").and_then(Value::as_str);
+    let api_key = checked_secret(auth.get("OPENAI_API_KEY"));
+    let tokens = auth.get("tokens");
+    let has_tokens = tokens.is_some_and(|value| {
+        !value.is_null() && value.as_object().is_none_or(|values| !values.is_empty())
+    });
+    if let Some(token) = api_key {
+        if mode.is_some_and(|value| !value.eq_ignore_ascii_case("apikey")) || has_tokens {
+            return Err(error("官方登录与 API Key 认证混用，请在 Codex 中重新登录"));
+        }
+        return Ok(LiveAuth {
+            token,
+            account_id: None,
+            base_url: OPENAI_API_BASE,
+        });
+    }
+    if auth.get("OPENAI_API_KEY").is_some_and(|value| {
+        !value.is_null() && value.as_str().is_none_or(|text| !text.trim().is_empty())
+    }) {
+        return Err(error("当前 OpenAI API Key 无效，请重新设置"));
+    }
+    if mode.is_some_and(|value| {
+        !value.eq_ignore_ascii_case("chatgpt") && !value.eq_ignore_ascii_case("chatgptAuthTokens")
+    }) {
+        return Err(error(
+            "此登录方式暂不支持本地路由，请使用 ChatGPT 登录或 OpenAI API Key",
+        ));
+    }
+    let token = checked_secret(auth.pointer("/tokens/access_token"))
+        .ok_or_else(|| error("官方账号尚未登录，请在 Codex 中完成 ChatGPT 登录"))?;
+    let account_id = checked_account(auth.pointer("/tokens/account_id").and_then(Value::as_str))?;
+    Ok(LiveAuth {
+        token,
+        account_id,
+        base_url: CHATGPT_BASE,
+    })
+}
+
+fn ensure_selected(spec: &OfficialRouteSpec) -> Result<(Vec<u8>, DocumentMut)> {
+    let (bytes, doc) = logical_document(&spec.codex_dir)?;
+    if !document_is_official(&doc)
+        || selected_profile_id(&spec.codex_dir)
+            .map_err(|_| error("无法确认当前官方账号，请刷新后重试"))?
+            != spec.profile_id
+    {
+        return Err(error("当前官方账号已切换，请重启 Codex 或新建会话后重试"));
+    }
+    Ok((bytes, doc))
+}
+
+pub(crate) fn route_for_current(dir: &Path) -> Result<Option<ProxyRoute>> {
+    let (_, doc) = logical_document(dir)?;
+    if !document_is_official(&doc) {
+        return Ok(None);
+    }
+    let profile_id = selected_profile_id(dir)?;
+    let name = list_official_profiles_inner(Some(dir.display().to_string()))?
+        .into_iter()
+        .find(|profile| profile.id == profile_id)
+        .map(|profile| profile.provider_name)
+        .unwrap_or_else(|| "OpenAI Official".to_owned());
+    // A logged-out official route can still be taken over. Codex may complete
+    // login or refresh after startup; every request re-reads and verifies it.
+    let base_url = read_bounded(&crate::auth_path(dir), MAX_AUTH_BYTES, true)
+        .ok()
+        .and_then(|bytes| parse_live_auth(&bytes).ok())
+        .map_or(CHATGPT_BASE, |auth| auth.base_url)
+        .to_owned();
+    let models = crate::string_value(&doc, "model")
+        .into_iter()
+        .collect::<HashSet<_>>();
+    Ok(Some(ProxyRoute {
+        id: format!("official:{profile_id}"),
+        name,
+        base_url,
+        api_key: None,
+        headers: Vec::new(),
+        models,
+        official: Some(OfficialRouteSpec {
+            codex_dir: dir.to_path_buf(),
+            profile_id,
+        }),
+    }))
+}
+
+pub(crate) fn verify_request(
+    spec: &OfficialRouteSpec,
+    authorization: &str,
+    account_id: Option<&str>,
+) -> Result<OfficialRequestAuth> {
+    let (config_before, _) = ensure_selected(spec)?;
+    if authorization.len() > MAX_TOKEN_BYTES + 32 || authorization.chars().any(char::is_control) {
+        return Err(error("官方请求认证无效，请在 Codex 中重新登录"));
+    }
+    let parts: Vec<_> = authorization.split_whitespace().collect();
+    if parts.len() != 2 || !parts[0].eq_ignore_ascii_case("Bearer") {
+        return Err(error("缺少官方请求认证，请在 Codex 中完成登录"));
+    }
+    let auth_before = read_bounded(&crate::auth_path(&spec.codex_dir), MAX_AUTH_BYTES, true)?;
+    let auth = parse_live_auth(&auth_before)?;
+    if parts[1] != auth.token || checked_account(account_id)? != auth.account_id {
+        return Err(error(
+            "此会话没有加载当前官方账号，请重启 Codex 或新建会话后重试",
+        ));
+    }
+    // Avoid trusting a token across a simultaneous account switch/logout/refresh.
+    // This reads files only; acquiring the live mutation lock here would deadlock
+    // callers constructing routes while holding their own configuration guard.
+    let (config_after, _) = ensure_selected(spec)?;
+    let auth_after = read_bounded(&crate::auth_path(&spec.codex_dir), MAX_AUTH_BYTES, true)?;
+    if config_before != config_after || auth_before != auth_after {
+        return Err(error("官方登录正在更新，请稍后重试"));
+    }
+    Ok(OfficialRequestAuth {
+        authorization: format!("Bearer {}", auth.token),
+        account_id: auth.account_id,
+        base_url: auth.base_url.to_owned(),
+    })
+}
+
+fn is_link(metadata: &fs::Metadata) -> bool {
+    #[cfg(windows)]
+    {
+        use std::os::windows::fs::MetadataExt;
+        metadata.file_type().is_symlink() || metadata.file_attributes() & 0x400 != 0
+    }
+    #[cfg(not(windows))]
+    {
+        metadata.file_type().is_symlink()
+    }
+}
+
+pub(crate) fn native_models(spec: &OfficialRouteSpec) -> Result<Value> {
+    let (_, doc) = ensure_selected(spec)?;
+    let Some(pointer) = doc.get("model_catalog_json").and_then(|item| item.as_str()) else {
+        return Ok(json!({"models":[]}));
+    };
+    let path = Path::new(pointer);
+    if path
+        .components()
+        .any(|part| matches!(part, Component::ParentDir))
+    {
+        return Ok(json!({"models":[]}));
+    }
+    let path = if path.is_absolute() {
+        path.to_owned()
+    } else {
+        spec.codex_dir.join(path)
+    };
+    let owned = spec.codex_dir.join(".codex-x").join("model-catalogs");
+    let Some(name) = path.file_name().and_then(|name| name.to_str()) else {
+        return Ok(json!({"models":[]}));
+    };
+    if !name
+        .strip_suffix(".json")
+        .is_some_and(|hash| hash.len() == 64 && hash.bytes().all(|byte| byte.is_ascii_hexdigit()))
+    {
+        return Ok(json!({"models":[]}));
+    }
+    for directory in [spec.codex_dir.join(".codex-x"), owned.clone()] {
+        if !fs::symlink_metadata(directory)
+            .is_ok_and(|metadata| !is_link(&metadata) && metadata.is_dir())
+        {
+            return Ok(json!({"models":[]}));
+        }
+    }
+    if !fs::symlink_metadata(&path).is_ok_and(|metadata| !is_link(&metadata) && metadata.is_file())
+        || !path
+            .parent()
+            .and_then(|parent| parent.canonicalize().ok())
+            .zip(owned.canonicalize().ok())
+            .is_some_and(|(parent, owned)| parent == owned)
+    {
+        return Ok(json!({"models":[]}));
+    }
+    let Ok(bytes) = read_bounded(&path, MAX_CATALOG_BYTES, false) else {
+        return Ok(json!({"models":[]}));
+    };
+    let Ok(value) = serde_json::from_slice::<Value>(&bytes) else {
+        return Ok(json!({"models":[]}));
+    };
+    let mut digest = Sha256::new();
+    digest.update(b"codex-x-provider-model-catalog-v2\0");
+    digest.update(serde_json::to_vec(&value).map_err(|_| error("本地模型目录格式无效"))?);
+    if value
+        .pointer("/_codex_x_model_catalog/source")
+        .and_then(Value::as_str)
+        != Some("codex-x")
+        || !value.get("models").is_some_and(Value::is_array)
+        || format!("{:x}.json", digest.finalize()) != name
+    {
+        return Ok(json!({"models":[]}));
+    }
+    Ok(value)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::providers::official_profiles::{
+        save_official_profile_inner, switch_official_profile_inner, OfficialProfileInput,
+        DEFAULT_OFFICIAL_PROFILE_ID,
+    };
+    use std::sync::atomic::{AtomicU64, Ordering};
+
+    struct Fixture {
+        dir: PathBuf,
+    }
+    impl Fixture {
+        fn new() -> Self {
+            static COUNT: AtomicU64 = AtomicU64::new(0);
+            let dir = std::env::temp_dir().join(format!(
+                "codex-x-native-official-{}-{}",
+                std::process::id(),
+                COUNT.fetch_add(1, Ordering::Relaxed)
+            ));
+            let _ = fs::remove_dir_all(&dir);
+            fs::create_dir_all(&dir).unwrap();
+            fs::write(crate::config_path(&dir), "model_provider = 'custom'\nmodel='official-model'\n[model_providers.custom]\nname='OpenAI'\nrequires_openai_auth=true\nsupports_websockets=true\nwire_api='responses'\n[mcp_servers.keep]\ncommand='fixture-mcp'\n").unwrap();
+            Self { dir }
+        }
+        fn oauth(&self, access: &str, account: &str) {
+            fs::write(crate::auth_path(&self.dir), serde_json::to_vec(&json!({"auth_mode":"chatgpt","tokens":{"access_token":access,"refresh_token":"unused-refresh-fixture","account_id":account}})).unwrap()).unwrap();
+        }
+        fn spec(&self) -> OfficialRouteSpec {
+            OfficialRouteSpec {
+                codex_dir: self.dir.clone(),
+                profile_id: DEFAULT_OFFICIAL_PROFILE_ID.into(),
+            }
+        }
+    }
+    impl Drop for Fixture {
+        fn drop(&mut self) {
+            let _ = fs::remove_dir_all(&self.dir);
+        }
+    }
+
+    #[test]
+    fn native_official_checks_exact_live_token_even_for_team_members_sharing_workspace() {
+        let fixture = Fixture::new();
+        fixture.oauth("live-user-a-token", "shared-team-workspace");
+        let auth_before = fs::read(crate::auth_path(&fixture.dir)).unwrap();
+        let config_before = fs::read(crate::config_path(&fixture.dir)).unwrap();
+        let spec = fixture.spec();
+        let allowed = verify_request(
+            &spec,
+            "Bearer live-user-a-token",
+            Some("shared-team-workspace"),
+        )
+        .unwrap();
+        assert_eq!(allowed.base_url, CHATGPT_BASE);
+        assert_eq!(allowed.account_id.as_deref(), Some("shared-team-workspace"));
+        for (authorization, account) in [
+            ("Bearer another-user-token", Some("shared-team-workspace")),
+            ("Bearer live-user-a-token", Some("other-workspace")),
+            ("Bearer live-user-a-token", None),
+            ("Bearer PROXY_MANAGED", Some("shared-team-workspace")),
+            ("Bearer\nlive-user-a-token", Some("shared-team-workspace")),
+            ("", Some("shared-team-workspace")),
+        ] {
+            let failure = verify_request(&spec, authorization, account)
+                .err()
+                .expect("must reject stale or wrong account credentials")
+                .to_string();
+            assert!(!failure.contains("live-user-a-token"));
+            assert!(!failure.contains("another-user-token"));
+            assert!(!failure.contains("shared-team-workspace"));
+        }
+        assert_eq!(
+            fs::read(crate::auth_path(&fixture.dir)).unwrap(),
+            auth_before
+        );
+        assert_eq!(
+            fs::read(crate::config_path(&fixture.dir)).unwrap(),
+            config_before
+        );
+    }
+
+    #[test]
+    fn native_official_login_and_token_refresh_are_owned_by_codex_without_cached_credentials() {
+        let fixture = Fixture::new();
+        let route = route_for_current(&fixture.dir).unwrap().unwrap();
+        assert!(route.api_key.is_none());
+        assert!(route.headers.is_empty());
+        let spec = route.official.unwrap();
+        assert!(verify_request(&spec, "Bearer absent", None).is_err());
+        fixture.oauth("first-token", "account");
+        assert!(verify_request(&spec, "Bearer first-token", Some("account")).is_ok());
+        fixture.oauth("refreshed-token", "account");
+        assert!(verify_request(&spec, "Bearer first-token", Some("account")).is_err());
+        assert!(verify_request(&spec, "Bearer refreshed-token", Some("account")).is_ok());
+        let latest = fs::read(crate::auth_path(&fixture.dir)).unwrap();
+        route_for_current(&fixture.dir).unwrap();
+        assert_eq!(fs::read(crate::auth_path(&fixture.dir)).unwrap(), latest);
+        fs::remove_file(crate::auth_path(&fixture.dir)).unwrap();
+        assert!(verify_request(&spec, "Bearer refreshed-token", Some("account")).is_err());
+        assert!(route_for_current(&fixture.dir).unwrap().is_some());
+    }
+
+    #[test]
+    fn native_official_does_not_reuse_inactive_profile_or_third_party_oauth() {
+        let _guard = crate::app_db::test_db_guard();
+        let fixture = Fixture::new();
+        fixture.oauth("account-a-token", "workspace");
+        let scope = Some(fixture.dir.display().to_string());
+        let other = save_official_profile_inner(OfficialProfileInput {
+            config_dir: scope.clone(), id: None, provider_name: "Account B".into(),
+            model: Some("official-model".into()), config_text: Some(fs::read_to_string(crate::config_path(&fixture.dir)).unwrap()),
+            auth_json: Some(json!({"auth_mode":"chatgpt","tokens":{"access_token":"account-b-token","account_id":"workspace"}}).to_string()),
+        }).unwrap();
+        let spec = fixture.spec();
+        assert!(verify_request(&spec, "Bearer account-b-token", Some("workspace")).is_err());
+        switch_official_profile_inner(scope, other.profile.id.clone()).unwrap();
+        assert!(verify_request(&spec, "Bearer account-b-token", Some("workspace")).is_err());
+        let current = route_for_current(&fixture.dir)
+            .unwrap()
+            .unwrap()
+            .official
+            .unwrap();
+        assert_eq!(current.profile_id, other.profile.id);
+        assert!(verify_request(&current, "Bearer account-b-token", Some("workspace")).is_ok());
+        fs::write(crate::config_path(&fixture.dir), "model_provider='custom'\nmodel='third'\n[model_providers.custom]\nname='Third'\nbase_url='https://third.example.test/v1'\nrequires_openai_auth=false\n").unwrap();
+        assert!(route_for_current(&fixture.dir).unwrap().is_none());
+        assert!(verify_request(&current, "Bearer account-b-token", Some("workspace")).is_err());
+    }
+
+    #[test]
+    fn native_api_key_uses_only_openai_api_origin_and_never_accepts_oauth_or_mixed_auth() {
+        let fixture = Fixture::new();
+        fs::write(
+            crate::auth_path(&fixture.dir),
+            json!({"auth_mode":"apikey","OPENAI_API_KEY":"api-key-fixture","tokens":null})
+                .to_string(),
+        )
+        .unwrap();
+        let spec = fixture.spec();
+        let verified = verify_request(&spec, "Bearer api-key-fixture", None).unwrap();
+        assert_eq!(verified.base_url, OPENAI_API_BASE);
+        assert!(verified.account_id.is_none());
+        assert!(verify_request(&spec, "Bearer oauth-fixture", None).is_err());
+        assert!(
+            verify_request(&spec, "Bearer api-key-fixture", Some("old-oauth-account")).is_err()
+        );
+        fs::write(
+            crate::auth_path(&fixture.dir),
+            json!({"OPENAI_API_KEY":"api-key-fixture","tokens":{"access_token":"oauth-fixture"}})
+                .to_string(),
+        )
+        .unwrap();
+        assert!(verify_request(&spec, "Bearer api-key-fixture", None).is_err());
+        assert!(verify_request(&spec, "Bearer oauth-fixture", None).is_err());
+        fs::write(crate::auth_path(&fixture.dir), "{ broken-secret-json").unwrap();
+        let failure = verify_request(&spec, "Bearer api-key-fixture", None)
+            .err()
+            .unwrap()
+            .to_string();
+        assert!(!failure.contains("broken-secret-json"));
+        assert!(!failure.contains("api-key-fixture"));
+    }
+
+    #[test]
+    fn native_models_serve_only_verified_owned_catalog_and_never_read_arbitrary_json() {
+        let fixture = Fixture::new();
+        let spec = fixture.spec();
+        assert_eq!(native_models(&spec).unwrap(), json!({"models":[]}));
+        let config_path = crate::config_path(&fixture.dir);
+        let mut doc = fs::read_to_string(&config_path)
+            .unwrap()
+            .parse::<DocumentMut>()
+            .unwrap();
+        crate::providers::model_catalog::prepare_model_catalog(
+            &fixture.dir,
+            "native-test",
+            &[crate::providers::model_catalog::ProviderModelMapping {
+                model: "local-model".into(),
+                display_name: "Local".into(),
+                context_window: None,
+            }],
+            "local-model",
+            &mut doc,
+        )
+        .unwrap();
+        fs::write(&config_path, doc.to_string()).unwrap();
+        let owned = PathBuf::from(doc["model_catalog_json"].as_str().unwrap());
+        let before = fs::read(&config_path).unwrap();
+        assert_eq!(
+            native_models(&spec).unwrap()["models"][0]["slug"],
+            "local-model"
+        );
+        assert_eq!(fs::read(&config_path).unwrap(), before);
+        let outside = fixture.dir.join("unrelated-auth.json");
+        fs::write(&outside, r#"{"models":["must-not-leak"]}"#).unwrap();
+        doc["model_catalog_json"] = toml_edit::value(outside.display().to_string());
+        fs::write(&config_path, doc.to_string()).unwrap();
+        assert_eq!(native_models(&spec).unwrap(), json!({"models":[]}));
+        #[cfg(unix)]
+        {
+            fs::remove_file(&owned).unwrap();
+            std::os::unix::fs::symlink(&outside, &owned).unwrap();
+            doc["model_catalog_json"] = toml_edit::value(owned.display().to_string());
+            fs::write(&config_path, doc.to_string()).unwrap();
+            assert_eq!(native_models(&spec).unwrap(), json!({"models":[]}));
+        }
+    }
+    #[test]
+    fn native_local_models_endpoint_accepts_owned_live_oauth_without_network_refresh_or_fallback() {
+        use super::super::config::{RoutingTuning, ROUTE_TOKEN_HEADER};
+        use super::super::proxy::{ProxyHandle, ProxyOptions};
+        use std::net::{IpAddr, Ipv4Addr};
+        use std::time::Duration;
+        struct Server(ProxyHandle);
+        impl Drop for Server {
+            fn drop(&mut self) {
+                self.0.shutdown();
+            }
+        }
+        let fixture = Fixture::new();
+        fixture.oauth("local-native-access", "local-native-account");
+        let route = route_for_current(&fixture.dir).unwrap().unwrap();
+        let local_token = "native-local-route-token-fixture-000000000000";
+        let server = Server(
+            ProxyHandle::start(
+                IpAddr::V4(Ipv4Addr::LOCALHOST),
+                0,
+                local_token.into(),
+                vec![route],
+                ProxyOptions {
+                    auto_failover_enabled: true,
+                    tuning: RoutingTuning::default(),
+                },
+            )
+            .unwrap(),
+        );
+        let client = reqwest::blocking::Client::builder()
+            .no_proxy()
+            .timeout(Duration::from_secs(5))
+            .build()
+            .unwrap();
+        for access in ["local-native-access", "local-native-refreshed"] {
+            fixture.oauth(access, "local-native-account");
+            let auth_before = fs::read(crate::auth_path(&fixture.dir)).unwrap();
+            let response = client
+                .get(format!("http://127.0.0.1:{}/v1/models", server.0.port()))
+                .header(ROUTE_TOKEN_HEADER, local_token)
+                .header("authorization", format!("Bearer {access}"))
+                .header("chatgpt-account-id", "local-native-account")
+                .send()
+                .unwrap();
+            assert_eq!(response.status().as_u16(), 200);
+            let body: Value = serde_json::from_str(&response.text().unwrap()).unwrap();
+            assert_eq!(body, json!({"models":[]}));
+            assert_eq!(
+                fs::read(crate::auth_path(&fixture.dir)).unwrap(),
+                auth_before
+            );
+        }
+        let snapshot = server.0.snapshot();
+        assert_eq!(snapshot.success_count, 2);
+        assert_eq!(snapshot.failover_count, 0);
+        assert_eq!(
+            snapshot.last_provider_id.as_deref(),
+            Some("official:openai-official")
+        );
+    }
+}

apps/desktop/src-tauri/src/failover/tests.rs

@@ -0,0 +1,824 @@
+use super::*;
+use std::fs;
+use std::sync::atomic::AtomicU64;
+
+struct Fixture {
+    dir: PathBuf,
+    providers: Vec<SavedProvider>,
+    original: String,
+    port: u16,
+}
+
+impl Fixture {
+    fn new() -> Self {
+        static NEXT: AtomicU64 = AtomicU64::new(0);
+        let number = NEXT.fetch_add(1, Ordering::Relaxed);
+        let tag = format!("failover-test-{}-{number}", std::process::id());
+        let dir = std::env::temp_dir().join(&tag);
+        fs::create_dir_all(&dir).unwrap();
+        let dir = dir.canonicalize().unwrap();
+        let mut providers = Vec::new();
+        for index in 0..3 {
+            let provider = SavedProvider {
+                id: format!("{tag}-{index}"),
+                provider_name: format!("Provider {index}"),
+                base_url: format!("https://{tag}-{index}.example.test/v1"),
+                model: "same-model".into(),
+                api_key: Some(format!("fixture-provider-secret-{index}")),
+                toml_config: None,
+                wire_api: "responses".into(),
+                requires_openai_auth: false,
+                model_mappings: vec![],
+            };
+            providers.push(crate::providers::save_provider_inner(provider).unwrap());
+        }
+        let primary = &providers[0];
+        let original = format!("# preserve user config\nmodel_provider = \"custom\"\nmodel = \"same-model\"\nmodel_reasoning_effort = \"high\"\n\n[model_providers.custom]\nname = \"Provider 0\"\nbase_url = {:?}\nwire_api = \"responses\"\nrequires_openai_auth = false\nsupports_websockets = true\nexperimental_bearer_token = {:?}\nrequest_max_retries = 4\n\n[model_providers.custom.http_headers]\nx-fixture = \"primary-header\"\n\n[mcp_servers.fixture]\ncommand = \"fixture-tool\"\n", primary.base_url, primary.api_key.as_deref().unwrap());
+        fs::write(crate::config_path(&dir), &original).unwrap();
+        fs::write(
+            dir.join("auth.json"),
+            "{\"OPENAI_API_KEY\":\"untouched-official-auth-fixture\"}",
+        )
+        .unwrap();
+        crate::providers::remember_active_provider_on_connection(
+            &crate::app_db::open().unwrap(),
+            &dir,
+            &primary.id,
+        )
+        .unwrap();
+        Self {
+            dir,
+            providers,
+            original,
+            port: free_port(),
+        }
+    }
+    fn scope(&self) -> Option<String> {
+        Some(self.dir.display().to_string())
+    }
+    fn settings(&self) -> FailoverSettings {
+        FailoverSettings {
+            router_enabled: true,
+            takeover_enabled: true,
+            auto_failover_enabled: true,
+            listen_port: self.port,
+            provider_ids: vec![self.providers[0].id.clone(), self.providers[1].id.clone()],
+            ..Default::default()
+        }
+    }
+    fn text(&self) -> String {
+        fs::read_to_string(crate::config_path(&self.dir)).unwrap()
+    }
+    fn enable(&self) -> FailoverStatus {
+        save_settings(self.scope(), self.settings()).unwrap()
+    }
+}
+
+impl Drop for Fixture {
+    fn drop(&mut self) {
+        SHUTTING_DOWN.store(false, Ordering::Release);
+        // If a test deliberately left invalid TOML, repair only its private fixture.
+        if let Ok(record) = load_record(&self.dir) {
+            if let Ok(mut runtimes) = lock_manager() {
+                if let Some(runtime) = runtimes.remove(&self.dir) {
+                    runtime.proxy.shutdown();
+                }
+            }
+            let _ = record;
+        }
+        if let Ok(conn) = crate::app_db::open() {
+            let _ = conn.execute(
+                "DELETE FROM provider_failover WHERE codex_dir = ?1",
+                [normalized_path_scope(&self.dir)],
+            );
+            let _ = conn.execute(
+                "DELETE FROM active_provider_selections WHERE codex_dir = ?1",
+                [normalized_path_scope(&self.dir)],
+            );
+            for provider in &self.providers {
+                let _ = conn.execute("DELETE FROM providers WHERE id = ?1", [&provider.id]);
+            }
+        }
+        let _ = fs::remove_dir_all(&self.dir);
+    }
+}
+
+fn free_port() -> u16 {
+    std::net::TcpListener::bind((std::net::Ipv4Addr::LOCALHOST, 0))
+        .unwrap()
+        .local_addr()
+        .unwrap()
+        .port()
+}
+fn stop(fixture: &Fixture) {
+    let mut settings = load_record(&fixture.dir).unwrap().settings;
+    settings.router_enabled = false;
+    save_settings(fixture.scope(), settings).unwrap();
+}
+fn parsed(fixture: &Fixture) -> DocumentMut {
+    fixture.text().parse().unwrap()
+}
+
+#[test]
+fn listener_takeover_and_auto_switches_are_independent() {
+    let _guard = crate::app_db::test_db_guard();
+    let fixture = Fixture::new();
+    let auth = fs::read(fixture.dir.join("auth.json")).unwrap();
+    let mut settings = fixture.settings();
+    settings.takeover_enabled = false;
+    settings.auto_failover_enabled = false;
+    let listening = save_settings(fixture.scope(), settings.clone()).unwrap();
+    assert!(listening.running);
+    assert!(!listening.takeover_active);
+    assert!(!listening.auto_failover_active);
+    assert_eq!(fixture.text(), fixture.original);
+    settings.takeover_enabled = true;
+    let single = save_settings(fixture.scope(), settings.clone()).unwrap();
+    assert!(single.takeover_active);
+    assert!(!single.auto_failover_active);
+    assert_eq!(single.runtime.providers.len(), 1);
+    assert_eq!(single.primary.as_ref().unwrap().id, fixture.providers[0].id);
+    settings.auto_failover_enabled = true;
+    let automatic = save_settings(fixture.scope(), settings).unwrap();
+    assert!(automatic.auto_failover_active);
+    assert_eq!(automatic.runtime.providers.len(), 2);
+    assert_eq!(fs::read(fixture.dir.join("auth.json")).unwrap(), auth);
+    stop(&fixture);
+    let stopped = get_status(fixture.scope()).unwrap();
+    assert!(!stopped.running && !stopped.takeover_active);
+    assert!(stopped.settings.auto_failover_enabled);
+    assert_eq!(stopped.settings.provider_ids.len(), 2);
+    assert_eq!(
+        parsed(&fixture)["mcp_servers"]["fixture"]["command"].as_str(),
+        Some("fixture-tool")
+    );
+    assert_eq!(
+        parsed(&fixture)["model_providers"]["custom"]["base_url"].as_str(),
+        Some(fixture.providers[0].base_url.as_str())
+    );
+}
+
+#[test]
+fn enabling_auto_switches_to_p1_even_if_current_is_elsewhere() {
+    let _guard = crate::app_db::test_db_guard();
+    let fixture = Fixture::new();
+    let mut settings = fixture.settings();
+    settings.provider_ids = vec![
+        fixture.providers[2].id.clone(),
+        fixture.providers[0].id.clone(),
+    ];
+    let status = save_settings(fixture.scope(), settings).unwrap();
+    assert!(status.auto_failover_active);
+    assert_eq!(status.primary.as_ref().unwrap().id, fixture.providers[2].id);
+    assert_eq!(status.runtime.providers[0].id, fixture.providers[2].id);
+    assert_eq!(status.settings.provider_ids[0], fixture.providers[2].id);
+    stop(&fixture);
+    assert_eq!(
+        parsed(&fixture)["model_providers"]["custom"]["base_url"].as_str(),
+        Some(fixture.providers[2].base_url.as_str())
+    );
+}
+
+#[test]
+fn a_single_provider_queue_and_an_empty_running_queue_are_valid() {
+    let _guard = crate::app_db::test_db_guard();
+    let fixture = Fixture::new();
+    let mut settings = fixture.settings();
+    settings.provider_ids.clear();
+    let single = save_settings(fixture.scope(), settings).unwrap();
+    assert_eq!(
+        single.settings.provider_ids,
+        vec![fixture.providers[0].id.clone()]
+    );
+    assert!(single.auto_failover_active);
+    let mut settings = single.settings;
+    settings.provider_ids.clear();
+    let empty = save_settings(fixture.scope(), settings).unwrap();
+    assert!(empty.running && empty.auto_failover_active);
+    assert!(empty.runtime.providers.is_empty());
+}
+
+#[test]
+fn queue_accepts_different_models_and_can_be_prepared_while_stopped() {
+    let _guard = crate::app_db::test_db_guard();
+    let mut fixture = Fixture::new();
+    fixture.providers[1].model = "another-model".into();
+    crate::providers::save_provider_inner(fixture.providers[1].clone()).unwrap();
+    let status = get_status(fixture.scope()).unwrap();
+    assert!(
+        status
+            .providers
+            .iter()
+            .find(|p| p.id == fixture.providers[1].id)
+            .unwrap()
+            .eligible
+    );
+    let mut settings = fixture.settings();
+    settings.router_enabled = false;
+    settings.takeover_enabled = false;
+    settings.auto_failover_enabled = false;
+    let saved = save_settings(fixture.scope(), settings).unwrap();
+    assert!(!saved.running);
+    assert_eq!(fixture.text(), fixture.original);
+    assert_eq!(saved.settings.provider_ids.len(), 2);
+    fixture.enable();
+}
+
+#[test]
+fn settings_and_scope_validation_have_no_live_side_effects() {
+    let _guard = crate::app_db::test_db_guard();
+    let fixture = Fixture::new();
+    let mut invalid = fixture.settings();
+    invalid.listen_port = 1000;
+    assert!(save_settings(fixture.scope(), invalid).is_err());
+    let mut invalid = fixture.settings();
+    invalid.provider_ids.push(invalid.provider_ids[0].clone());
+    assert!(save_settings(fixture.scope(), invalid).is_err());
+    let mut invalid = fixture.settings();
+    invalid.provider_ids = vec!["official:openai-official".into()];
+    assert!(save_settings(fixture.scope(), invalid).is_err());
+    let mut invalid = fixture.settings();
+    invalid.takeover_enabled = false;
+    assert!(save_settings(fixture.scope(), invalid).is_err());
+    assert_eq!(fixture.text(), fixture.original);
+}
+
+#[test]
+fn failed_bind_and_missing_p1_leave_configuration_and_settings_unchanged() {
+    let _guard = crate::app_db::test_db_guard();
+    let fixture = Fixture::new();
+    let blocker =
+        std::net::TcpListener::bind((std::net::Ipv4Addr::LOCALHOST, fixture.port)).unwrap();
+    assert!(save_settings(fixture.scope(), fixture.settings()).is_err());
+    assert_eq!(fixture.text(), fixture.original);
+    assert!(!get_status(fixture.scope()).unwrap().running);
+    drop(blocker);
+    let mut settings = fixture.settings();
+    settings.provider_ids = vec!["missing-p1".into()];
+    assert!(save_settings(fixture.scope(), settings).is_err());
+    assert_eq!(fixture.text(), fixture.original);
+    assert!(!get_status(fixture.scope()).unwrap().settings.router_enabled);
+}
+
+#[test]
+fn queue_and_tuning_updates_keep_the_endpoint_and_update_all_parameters() {
+    let _guard = crate::app_db::test_db_guard();
+    let fixture = Fixture::new();
+    fixture.enable();
+    let before = fixture.text();
+    let mut settings = fixture.settings();
+    settings.provider_ids.reverse();
+    settings.tuning = RoutingTuning {
+        max_retries: 8,
+        streaming_first_byte_timeout: 10,
+        streaming_idle_timeout: 0,
+        non_streaming_timeout: 900,
+        circuit_failure_threshold: 7,
+        circuit_success_threshold: 4,
+        circuit_timeout_seconds: 45,
+        circuit_error_rate_threshold: 0.75,
+        circuit_min_requests: 15,
+    };
+    let status = save_settings(fixture.scope(), settings.clone()).unwrap();
+    assert_eq!(status.settings, settings);
+    assert_eq!(fixture.text(), before);
+    assert_eq!(status.runtime.providers[0].id, fixture.providers[1].id);
+    let mut bad = status.settings;
+    bad.listen_port = free_port();
+    assert!(save_settings(fixture.scope(), bad).is_err());
+    assert_eq!(fixture.text(), before);
+}
+
+#[test]
+fn manual_switch_keeps_routing_and_auto_but_official_never_joins_api_queue() {
+    let _guard = crate::app_db::test_db_guard();
+    let fixture = Fixture::new();
+    fixture.enable();
+    with_provider_change(fixture.scope(), || {
+        crate::providers::activate_saved_provider_inner(
+            fixture.scope(),
+            fixture.providers[2].id.clone(),
+        )
+    })
+    .unwrap();
+    let switched = get_status(fixture.scope()).unwrap();
+    assert!(switched.running && switched.auto_failover_active);
+    assert_eq!(switched.primary.unwrap().id, fixture.providers[2].id);
+    with_provider_change(fixture.scope(), || {
+        crate::providers::official_profiles::switch_official_profile_inner(
+            fixture.scope(),
+            crate::providers::official_profiles::DEFAULT_OFFICIAL_PROFILE_ID.into(),
+        )
+    })
+    .unwrap();
+    let official = get_status(fixture.scope()).unwrap();
+    assert!(official.running && official.takeover_active);
+    assert!(!official.auto_failover_active);
+    assert!(official.settings.auto_failover_enabled);
+    assert!(official.primary.unwrap().official);
+    assert!(official
+        .runtime
+        .providers
+        .iter()
+        .all(|p| p.id.starts_with("official:")));
+    assert!(official.providers.iter().all(|p| !p.official));
+}
+
+#[test]
+fn official_takeover_preserves_auth_and_can_restore_a_builtin_route() {
+    let _guard = crate::app_db::test_db_guard();
+    let fixture = Fixture::new();
+    let original = "model='official-model'\n[mcp_servers.test]\ncommand='tool'\n";
+    fs::write(crate::config_path(&fixture.dir), original).unwrap();
+    let auth = fs::read(fixture.dir.join("auth.json")).unwrap();
+    let mut settings = fixture.settings();
+    settings.auto_failover_enabled = false;
+    settings.provider_ids.clear();
+    let status = save_settings(fixture.scope(), settings).unwrap();
+    assert!(status.primary.unwrap().official);
+    assert!(status.takeover_active && !status.auto_failover_active);
+    let doc = parsed(&fixture);
+    assert_eq!(
+        doc["model_providers"]["openai"]["requires_openai_auth"].as_bool(),
+        Some(true)
+    );
+    assert!(doc["model_providers"]["openai"]
+        .get("experimental_bearer_token")
+        .is_none());
+    assert!(doc["model_providers"]["openai"]["http_headers"]
+        .get(ROUTE_TOKEN_HEADER)
+        .is_some());
+    assert_eq!(fs::read(fixture.dir.join("auth.json")).unwrap(), auth);
+    stop(&fixture);
+    assert!(parsed(&fixture).get("model_providers").is_none());
+    assert_eq!(
+        parsed(&fixture)["mcp_servers"]["test"]["command"].as_str(),
+        Some("tool")
+    );
+    assert_eq!(fs::read(fixture.dir.join("auth.json")).unwrap(), auth);
+}
+
+#[test]
+fn failed_manual_switch_reattaches_original_route() {
+    let _guard = crate::app_db::test_db_guard();
+    let fixture = Fixture::new();
+    fixture.enable();
+    let error = with_provider_change::<()>(fixture.scope(), || {
+        Err(CodexxError::Config("expected switch failure".into()))
+    })
+    .unwrap_err();
+    assert!(error.to_string().contains("expected switch failure"));
+    let status = get_status(fixture.scope()).unwrap();
+    assert!(status.running && status.takeover_active);
+    assert_eq!(status.primary.unwrap().id, fixture.providers[0].id);
+}
+
+#[test]
+fn restore_keeps_external_edits_and_does_not_leave_local_headers() {
+    let _guard = crate::app_db::test_db_guard();
+    let fixture = Fixture::new();
+    fixture.enable();
+    let mut doc = parsed(&fixture);
+    doc["model_reasoning_effort"] = value("max");
+    doc["model_providers"]["custom"]["request_max_retries"] = value(9);
+    doc["model_providers"]["custom"]["external_new_setting"] = value("preserved");
+    fs::write(crate::config_path(&fixture.dir), doc.to_string()).unwrap();
+    stop(&fixture);
+    let restored = parsed(&fixture);
+    assert_eq!(restored["model_reasoning_effort"].as_str(), Some("max"));
+    assert_eq!(
+        restored["model_providers"]["custom"]["request_max_retries"].as_integer(),
+        Some(9)
+    );
+    assert_eq!(
+        restored["model_providers"]["custom"]["external_new_setting"].as_str(),
+        Some("preserved")
+    );
+    assert_eq!(
+        restored["model_providers"]["custom"]["http_headers"]["x-fixture"].as_str(),
+        Some("primary-header")
+    );
+    assert!(!fixture.text().contains(ROUTE_GENERATION_HEADER));
+}
+
+#[test]
+fn external_provider_change_detaches_without_stopping_the_listener() {
+    let _guard = crate::app_db::test_db_guard();
+    let fixture = Fixture::new();
+    fixture.enable();
+    let external = fixture
+        .original
+        .replace(
+            &fixture.providers[0].base_url,
+            &fixture.providers[2].base_url,
+        )
+        .replace("fixture-provider-secret-0", "fixture-provider-secret-2");
+    fs::write(crate::config_path(&fixture.dir), &external).unwrap();
+    let status = get_status(fixture.scope()).unwrap();
+    assert!(status.running && !status.takeover_active);
+    assert!(!status.settings.takeover_enabled);
+    assert_eq!(fixture.text(), external);
+}
+
+#[test]
+fn failed_restore_keeps_the_listener_alive() {
+    let _guard = crate::app_db::test_db_guard();
+    let fixture = Fixture::new();
+    fixture.enable();
+    let managed = fixture.text();
+    fs::write(crate::config_path(&fixture.dir), "invalid = [").unwrap();
+    let mut off = fixture.settings();
+    off.router_enabled = false;
+    assert!(save_settings(fixture.scope(), off).is_err());
+    assert!(lock_manager().unwrap().contains_key(&fixture.dir));
+    fs::write(crate::config_path(&fixture.dir), managed).unwrap();
+    stop(&fixture);
+}
+
+#[test]
+fn failed_update_handoff_resumes_saved_routes_and_reopens_mutation_gate() {
+    let _guard = crate::app_db::test_db_guard();
+    let fixture = Fixture::new();
+    let before = fixture.enable();
+    let auth = fs::read(crate::auth_path(&fixture.dir)).unwrap();
+    shutdown_all().unwrap();
+    assert!(!get_status(fixture.scope()).unwrap().running);
+    assert!(!fixture.text().contains("http://127.0.0.1:"));
+    resume_after_failed_update().unwrap();
+    let after = get_status(fixture.scope()).unwrap();
+    assert!(after.running && after.takeover_active);
+    assert_eq!(after.settings, before.settings);
+    assert_eq!(fs::read(crate::auth_path(&fixture.dir)).unwrap(), auth);
+    stop(&fixture);
+    assert!(!get_status(fixture.scope()).unwrap().running);
+}
+
+#[test]
+fn failed_update_recovery_reports_busy_port_without_erasing_saved_preferences() {
+    let _guard = crate::app_db::test_db_guard();
+    let fixture = Fixture::new();
+    let before = fixture.enable();
+    shutdown_all().unwrap();
+    let occupied =
+        std::net::TcpListener::bind((std::net::Ipv4Addr::LOCALHOST, fixture.port)).unwrap();
+    assert!(resume_after_failed_update().is_err());
+    let status = get_status(fixture.scope()).unwrap();
+    assert!(!status.running);
+    assert_eq!(status.settings, before.settings);
+    assert!(!fixture.text().contains("http://127.0.0.1:"));
+    drop(occupied);
+    resume_after_failed_update().unwrap();
+    assert!(get_status(fixture.scope()).unwrap().takeover_active);
+}
+
+#[test]
+fn persisted_directory_scopes_resolve_to_the_interactive_runtime_key() {
+    let _guard = crate::app_db::test_db_guard();
+    let fixture = Fixture::new();
+    fixture.enable();
+    let scope = normalized_path_scope(&fixture.dir);
+    let stored = stored_directories().unwrap();
+    let restored = stored
+        .iter()
+        .find(|dir| normalized_path_scope(dir) == scope)
+        .unwrap();
+    assert_eq!(*restored, directory(fixture.scope()).unwrap());
+    assert!(lock_manager().unwrap().contains_key(restored));
+}
+
+#[test]
+fn exit_restores_and_rejects_queued_enabling_then_restart_resumes_same_port() {
+    let _guard = crate::app_db::test_db_guard();
+    let fixture = Fixture::new();
+    fixture.enable();
+    shutdown_all().unwrap();
+    assert!(!fixture.text().contains("http://127.0.0.1:"));
+    let record = load_record(&fixture.dir).unwrap();
+    assert!(record.settings.router_enabled && record.settings.takeover_enabled);
+    assert!(save_settings(fixture.scope(), fixture.settings()).is_err());
+    SHUTTING_DOWN.store(false, Ordering::Release);
+    initialize().unwrap();
+    let status = get_status(fixture.scope()).unwrap();
+    assert!(status.takeover_active);
+    assert_eq!(status.settings.listen_port, fixture.port);
+}
+
+#[test]
+fn old_managed_backups_keep_their_original_provider_after_later_takeovers() {
+    let _guard = crate::app_db::test_db_guard();
+    let fixture = Fixture::new();
+    fixture.enable();
+    let old = fixture.text();
+    with_provider_change(fixture.scope(), || {
+        crate::providers::activate_saved_provider_inner(
+            fixture.scope(),
+            fixture.providers[2].id.clone(),
+        )
+    })
+    .unwrap();
+    stop(&fixture);
+    fs::write(crate::config_path(&fixture.dir), old).unwrap();
+    recover_stale_route(fixture.scope()).unwrap();
+    assert_eq!(
+        parsed(&fixture)["model_providers"]["custom"]["base_url"].as_str(),
+        Some(fixture.providers[0].base_url.as_str())
+    );
+}
+
+#[test]
+fn old_enabled_backups_settings_migrate_to_full_p1_queue() {
+    let _guard = crate::app_db::test_db_guard();
+    let fixture = Fixture::new();
+    let old = serde_json::json!({"settings":{"enabled":true,"providerIds":[fixture.providers[1].id]},"journals":[{"primaryId":fixture.providers[0].id,"providerKey":"custom","originalTable":"name='old'","port":fixture.port,"token":"old-only-test-token"}]});
+    crate::app_db::open()
+        .unwrap()
+        .execute(
+            "INSERT INTO provider_failover(codex_dir,record_json) VALUES(?1,?2)",
+            params![normalized_path_scope(&fixture.dir), old.to_string()],
+        )
+        .unwrap();
+    let migrated = load_record(&fixture.dir).unwrap();
+    assert_eq!(migrated.version, 2);
+    assert!(
+        migrated.settings.router_enabled
+            && migrated.settings.takeover_enabled
+            && migrated.settings.auto_failover_enabled
+    );
+    assert_eq!(
+        migrated.settings.provider_ids,
+        vec![
+            fixture.providers[0].id.clone(),
+            fixture.providers[1].id.clone()
+        ]
+    );
+    assert_eq!(migrated.settings.tuning, RoutingTuning::default());
+}
+
+#[test]
+fn status_never_serializes_provider_credentials_or_local_tokens() {
+    let _guard = crate::app_db::test_db_guard();
+    let fixture = Fixture::new();
+    let status = fixture.enable();
+    let text = serde_json::to_string(&status).unwrap();
+    assert!(!text.contains("fixture-provider-secret"));
+    let record = load_record(&fixture.dir).unwrap();
+    assert!(!text.contains(&record.journals.last().unwrap().token));
+}
+
+#[test]
+fn deleting_one_queue_member_keeps_the_rest_and_listener() {
+    let _guard = crate::app_db::test_db_guard();
+    let fixture = Fixture::new();
+    fixture.enable();
+    crate::providers::delete_provider_inner(&fixture.providers[1].id).unwrap();
+    refresh_saved_routes().unwrap();
+    let status = get_status(fixture.scope()).unwrap();
+    assert!(status.running && status.takeover_active);
+    assert_eq!(status.runtime.providers.len(), 1);
+    assert_eq!(status.runtime.providers[0].id, fixture.providers[0].id);
+}
+
+#[test]
+fn listener_can_run_without_a_configured_provider() {
+    let _guard = crate::app_db::test_db_guard();
+    let fixture = Fixture::new();
+    fs::remove_file(crate::config_path(&fixture.dir)).unwrap();
+    let status = save_settings(
+        fixture.scope(),
+        FailoverSettings {
+            router_enabled: true,
+            listen_port: fixture.port,
+            ..Default::default()
+        },
+    )
+    .unwrap();
+    assert!(status.running && !status.takeover_active);
+    assert!(!crate::config_path(&fixture.dir).exists());
+}
+
+#[test]
+fn successful_fallback_updates_logical_provider_and_preserves_old_backup_identity() {
+    let _guard = crate::app_db::test_db_guard();
+    let mut fixture = Fixture::new();
+    fixture.providers[1].model = "different-default".into();
+    crate::providers::save_provider_inner(fixture.providers[1].clone()).unwrap();
+    fixture.enable();
+    let earlier_backup = fixture.text();
+    let mut runtimes = lock_manager().unwrap();
+    let runtime = runtimes.get(&fixture.dir).unwrap();
+    let notice = SelectionNotice {
+        dir: fixture.dir.clone(),
+        instance_id: runtime.instance_id,
+        token: runtime.token.clone(),
+        event: ProxySelectionEvent {
+            provider_id: fixture.providers[1].id.clone(),
+            revision: runtime.proxy.revision(),
+        },
+    };
+    record_selection(notice, &mut runtimes).unwrap();
+    drop(runtimes);
+    let selected = get_status(fixture.scope()).unwrap();
+    assert_eq!(selected.primary.unwrap().id, fixture.providers[1].id);
+    assert_eq!(parsed(&fixture)["model"].as_str(), Some("same-model"));
+    let direct = direct_document(&fixture.dir, &parsed(&fixture)).unwrap();
+    assert_eq!(
+        direct["model_providers"]["custom"]["name"].as_str(),
+        Some("Provider 1")
+    );
+    assert_eq!(
+        direct["model_providers"]["custom"]["experimental_bearer_token"].as_str(),
+        Some("fixture-provider-secret-1")
+    );
+    stop(&fixture);
+    assert_eq!(
+        parsed(&fixture)["model_providers"]["custom"]["base_url"].as_str(),
+        Some(fixture.providers[1].base_url.as_str())
+    );
+    fs::write(crate::config_path(&fixture.dir), earlier_backup).unwrap();
+    recover_stale_route(fixture.scope()).unwrap();
+    assert_eq!(
+        parsed(&fixture)["model_providers"]["custom"]["base_url"].as_str(),
+        Some(fixture.providers[0].base_url.as_str())
+    );
+}
+
+#[test]
+fn late_success_cannot_override_a_manual_switch_or_a_changed_queue() {
+    let _guard = crate::app_db::test_db_guard();
+    let fixture = Fixture::new();
+    fixture.enable();
+    let notice = {
+        let runtimes = lock_manager().unwrap();
+        let runtime = runtimes.get(&fixture.dir).unwrap();
+        SelectionNotice {
+            dir: fixture.dir.clone(),
+            instance_id: runtime.instance_id,
+            token: runtime.token.clone(),
+            event: ProxySelectionEvent {
+                provider_id: fixture.providers[1].id.clone(),
+                revision: runtime.proxy.revision(),
+            },
+        }
+    };
+    with_provider_change(fixture.scope(), || {
+        crate::providers::activate_saved_provider_inner(
+            fixture.scope(),
+            fixture.providers[2].id.clone(),
+        )
+    })
+    .unwrap();
+    record_selection(notice, &mut lock_manager().unwrap()).unwrap();
+    assert_eq!(
+        get_status(fixture.scope()).unwrap().primary.unwrap().id,
+        fixture.providers[2].id
+    );
+}
+
+#[test]
+fn a_late_success_from_a_stopped_listener_cannot_change_the_restarted_route() {
+    let _guard = crate::app_db::test_db_guard();
+    let fixture = Fixture::new();
+    fixture.enable();
+    let notice = {
+        let runtimes = lock_manager().unwrap();
+        let runtime = runtimes.get(&fixture.dir).unwrap();
+        SelectionNotice {
+            dir: fixture.dir.clone(),
+            instance_id: runtime.instance_id,
+            token: runtime.token.clone(),
+            event: ProxySelectionEvent {
+                provider_id: fixture.providers[1].id.clone(),
+                revision: runtime.proxy.revision(),
+            },
+        }
+    };
+    stop(&fixture);
+    fixture.enable();
+    let mut runtimes = lock_manager().unwrap();
+    let restarted = runtimes.get(&fixture.dir).unwrap();
+    assert_eq!(notice.token, restarted.token);
+    assert_eq!(notice.event.revision, restarted.proxy.revision());
+    assert_ne!(notice.instance_id, restarted.instance_id);
+    record_selection(notice, &mut runtimes).unwrap();
+    drop(runtimes);
+    assert_eq!(
+        get_status(fixture.scope()).unwrap().primary.unwrap().id,
+        fixture.providers[0].id
+    );
+}
+
+#[test]
+fn a_journal_write_failure_after_p1_rolls_back_files_and_common_recovery_marker() {
+    let _guard = crate::app_db::test_db_guard();
+    let fixture = Fixture::new();
+    let before = FileCheckpoint::capture(&fixture.dir).unwrap();
+    let target = &fixture.providers[2].id;
+    crate::app_db::open().unwrap().execute_batch(&format!("CREATE TRIGGER reject_p1_journal BEFORE UPDATE ON provider_failover WHEN json_extract(NEW.record_json,'$.journals[#-1].primaryId') = '{target}' BEGIN SELECT RAISE(ABORT,'fixture-journal-failure'); END;")).unwrap();
+    let mut settings = fixture.settings();
+    settings.provider_ids = vec![target.clone()];
+    let result = save_settings(fixture.scope(), settings);
+    crate::app_db::open()
+        .unwrap()
+        .execute_batch("DROP TRIGGER reject_p1_journal")
+        .unwrap();
+    assert!(result.is_err());
+    let after = FileCheckpoint::capture(&fixture.dir).unwrap();
+    assert_eq!(before.config, after.config);
+    assert_eq!(before.auth, after.auth);
+    assert_eq!(before.selected, after.selected);
+    assert_eq!(before.common_handled, after.common_handled);
+    assert!(!get_status(fixture.scope()).unwrap().running);
+}
+
+#[test]
+fn p1_journal_failure_restores_official_endpoint_before_oauth() {
+    let _guard = crate::app_db::test_db_guard();
+    let mut fixture = Fixture::new();
+    fs::write(crate::config_path(&fixture.dir), "model='official-model'\n").unwrap();
+    fs::write(crate::auth_path(&fixture.dir),r#"{"auth_mode":"chatgpt","tokens":{"access_token":"fixture-oauth","account_id":"fixture-account"}}"#).unwrap();
+    fixture.providers[2].requires_openai_auth = true;
+    fixture.providers[2] =
+        crate::providers::save_provider_inner(fixture.providers[2].clone()).unwrap();
+    let before = FileCheckpoint::capture(&fixture.dir).unwrap();
+    let mut settings = fixture.settings();
+    settings.provider_ids = vec![fixture.providers[2].id.clone()];
+    // Verify the prepared direct route really reads the global auth file. This
+    // is the interval a failed journal write must undo before publishing OAuth.
+    switch_to_p1(&fixture.dir, &mut settings).unwrap();
+    let prepared = FileCheckpoint::capture(&fixture.dir).unwrap();
+    let doc = parsed(&fixture);
+    let key = doc["model_provider"].as_str().unwrap();
+    assert_eq!(
+        doc["model_providers"][key]["requires_openai_auth"].as_bool(),
+        Some(true)
+    );
+    assert!(doc["model_providers"][key]
+        .get("experimental_bearer_token")
+        .is_none());
+    assert_eq!(
+        crate::providers::replacement_write_order(
+            prepared.config.as_deref(),
+            before.config.as_deref()
+        ),
+        crate::providers::LiveWriteOrder::ConfigFirst
+    );
+    before.restore(&fixture.dir, &prepared).unwrap();
+    let target = &fixture.providers[2].id;
+    crate::app_db::open().unwrap().execute_batch(&format!("CREATE TRIGGER reject_official_p1 BEFORE UPDATE ON provider_failover WHEN json_extract(NEW.record_json,'$.journals[#-1].primaryId') = '{target}' BEGIN SELECT RAISE(ABORT,'fixture-journal-failure'); END;")).unwrap();
+    let result = save_settings(fixture.scope(), settings);
+    crate::app_db::open()
+        .unwrap()
+        .execute_batch("DROP TRIGGER reject_official_p1")
+        .unwrap();
+    assert!(result
+        .err()
+        .unwrap()
+        .to_string()
+        .contains("fixture-journal-failure"));
+    let after = FileCheckpoint::capture(&fixture.dir).unwrap();
+    assert_eq!(before.config, after.config);
+    assert_eq!(before.auth, after.auth);
+    assert_eq!(before.selected, after.selected);
+    assert_eq!(before.common_handled, after.common_handled);
+    assert!(!get_status(fixture.scope()).unwrap().running);
+}
+
+#[test]
+fn invalid_persisted_settings_restore_direct_without_restarting_listener() {
+    let _guard = crate::app_db::test_db_guard();
+    let fixture = Fixture::new();
+    fixture.enable();
+    let runtime = lock_manager().unwrap().remove(&fixture.dir).unwrap();
+    runtime.proxy.shutdown();
+    let mut record = load_record(&fixture.dir).unwrap();
+    record.settings.tuning.max_retries = 11;
+    save_record(&fixture.dir, &record).unwrap();
+    initialize().unwrap();
+    let status = get_status(fixture.scope()).unwrap();
+    assert!(!status.running && !status.takeover_active);
+    assert!(!fixture.text().contains("http://127.0.0.1:"));
+    assert!(status.message.unwrap().contains("路由设置需要检查"));
+}
+
+#[test]
+fn startup_status_write_failure_keeps_the_attached_listener_alive() {
+    let _guard = crate::app_db::test_db_guard();
+    let fixture = Fixture::new();
+    fixture.enable();
+    shutdown_all().unwrap();
+    let conn = crate::app_db::open().unwrap();
+    conn.execute_batch("CREATE TRIGGER reject_redundant_status BEFORE UPDATE ON provider_failover WHEN NEW.record_json=OLD.record_json BEGIN SELECT RAISE(ABORT,'fixture-status-failure'); END;").unwrap();
+    SHUTTING_DOWN.store(false, Ordering::Release);
+    let result = initialize();
+    conn.execute_batch("DROP TRIGGER reject_redundant_status")
+        .unwrap();
+    assert!(result
+        .unwrap_err()
+        .to_string()
+        .contains("fixture-status-failure"));
+    let status = get_status(fixture.scope()).unwrap();
+    assert!(status.running && status.takeover_active);
+    assert!(fixture.text().contains("http://127.0.0.1:"));
+    assert!(std::net::TcpStream::connect((std::net::Ipv4Addr::LOCALHOST, fixture.port)).is_ok());
+    stop(&fixture);
+}

apps/desktop/src-tauri/src/failover_integration_tests.rs

@@ -0,0 +1,293 @@
+use super::*;
+
+struct OwnedRouteFixture {
+    dir: PathBuf,
+    raw: String,
+    local_token: String,
+}
+
+impl OwnedRouteFixture {
+    fn new() -> Self {
+        let unique = format!(
+            "{}-{}",
+            std::process::id(),
+            Local::now().timestamp_nanos_opt().unwrap()
+        );
+        let dir = std::env::temp_dir().join(format!("codex-x-failover-integration-{unique}"));
+        fs::create_dir_all(&dir).expect("create isolated Codex directory");
+        let local_token = format!("local-token-{unique}");
+        let original = r#"name = "Primary"
+base_url = "https://primary.example.test/v1"
+wire_api = "responses"
+requires_openai_auth = false
+experimental_bearer_token = "real-test-key"
+supports_websockets = true
+"#;
+        let raw = format!(
+            r#"model_provider = "custom"
+model = "test-model"
+model_reasoning_effort = "high"
+
+[model_providers.custom]
+name = "Primary"
+base_url = "http://127.0.0.1:45555/v1"
+wire_api = "responses"
+requires_openai_auth = false
+experimental_bearer_token = "{local_token}"
+supports_websockets = false
+request_max_retries = 0
+stream_max_retries = 0
+
+[mcp_servers.example]
+command = "local-fixture-command"
+"#
+        );
+        fs::write(config_path(&dir), &raw).expect("write synthetic local route");
+        let record = json!({
+            "settings": {"enabled":false,"providerIds":[]},
+            "journals": [{"primaryId":"fixture-primary", "providerKey":"custom",
+                "originalTable":original, "port":45555, "token":local_token}],
+        });
+        app_db::open()
+            .expect("open isolated test store")
+            .execute(
+                "INSERT INTO provider_failover (codex_dir, record_json) VALUES (?1, ?2)",
+                params![paths::normalized_path_scope(&dir), record.to_string()],
+            )
+            .expect("seed owned route journal");
+        Self {
+            dir,
+            raw,
+            local_token,
+        }
+    }
+}
+
+impl Drop for OwnedRouteFixture {
+    fn drop(&mut self) {
+        if let Ok(conn) = app_db::open() {
+            let _ = conn.execute(
+                "DELETE FROM provider_failover WHERE codex_dir = ?1",
+                [paths::normalized_path_scope(&self.dir)],
+            );
+        }
+        let _ = fs::remove_dir_all(&self.dir);
+    }
+}
+
+#[test]
+fn managed_route_state_detection_and_drafts_use_original_provider_without_writes() {
+    let fixture = OwnedRouteFixture::new();
+    let mut detected = providers::detected_live_custom_provider(&fixture.dir)
+        .expect("detect logical provider")
+        .expect("third-party provider");
+    assert_eq!(detected.base_url, "https://primary.example.test/v1");
+    assert_eq!(detected.api_key.as_deref(), Some("real-test-key"));
+    assert!(!detected
+        .toml_config
+        .as_deref()
+        .unwrap()
+        .contains(&fixture.local_token));
+    detected.toml_config = None;
+    let draft = build_provider_toml_draft_inner(detected, Some(fixture.dir.display().to_string()))
+        .expect("inherit direct route in editor draft");
+    assert!(!draft.contains("127.0.0.1"));
+    assert!(!draft.contains(&fixture.local_token));
+    assert!(draft.contains("local-fixture-command"));
+    let state =
+        build_state_after_migration(fixture.dir.clone()).expect("read logical application state");
+    let state_json = serde_json::to_value(&state).expect("serialize public state");
+    assert_eq!(
+        state_json["providers"][0]["baseUrl"],
+        "https://primary.example.test/v1"
+    );
+    assert_eq!(state.model.as_deref(), Some("test-model"));
+    assert_eq!(
+        fs::read_to_string(config_path(&fixture.dir)).unwrap(),
+        fixture.raw
+    );
+    assert!(!auth_path(&fixture.dir).exists());
+}
+
+#[test]
+fn cached_managed_toml_submission_restores_owned_route_but_preserves_new_api_key() {
+    let fixture = OwnedRouteFixture::new();
+    for (input_key, expected_key) in [
+        (
+            Some(fixture.local_token.clone()),
+            Some("real-test-key".to_string()),
+        ),
+        (
+            Some("new-user-key".to_string()),
+            Some("new-user-key".to_string()),
+        ),
+        (
+            Some(format!("  {}  ", fixture.local_token)),
+            Some("real-test-key".to_string()),
+        ),
+        (None, None),
+    ] {
+        let input = direct_provider_toml_input(ProviderTomlInput {
+            config_dir: Some(fixture.dir.display().to_string()),
+            config_text: fixture.raw.replace("\"high\"", "\"low\""),
+            api_key: input_key,
+        })
+        .expect("unwrap stale editor payload");
+        assert_eq!(input.api_key, expected_key);
+        let doc = input
+            .config_text
+            .parse::<DocumentMut>()
+            .expect("parse direct payload");
+        assert_eq!(doc["model_reasoning_effort"].as_str(), Some("low"));
+        assert_eq!(
+            doc["model_providers"]["custom"]["base_url"].as_str(),
+            Some("https://primary.example.test/v1")
+        );
+        assert!(!input.config_text.contains(&fixture.local_token));
+        assert!(input.config_text.contains("local-fixture-command"));
+    }
+    assert_eq!(
+        fs::read_to_string(config_path(&fixture.dir)).unwrap(),
+        fixture.raw
+    );
+    assert!(!auth_path(&fixture.dir).exists());
+}
+
+#[test]
+fn read_unwrap_handles_multiple_owned_tables_before_detecting_selected_provider() {
+    let mut fixture = OwnedRouteFixture::new();
+    let second_original = "name = \"Inactive\"\nbase_url = \"https://secondary.example.test/v1\"\nwire_api = \"responses\"\nrequires_openai_auth = false\nexperimental_bearer_token = \"secondary-test-key\"\n";
+    fixture.raw.push_str("\n[model_providers.inactive]\nname = \"Inactive\"\nbase_url = \"http://127.0.0.1:45556/v1\"\nwire_api = \"responses\"\nrequires_openai_auth = false\nexperimental_bearer_token = \"secondary-local-token\"\n");
+    fs::write(config_path(&fixture.dir), &fixture.raw).expect("write second local table");
+    let conn = app_db::open().expect("read fixture store");
+    let scope = paths::normalized_path_scope(&fixture.dir);
+    let text: String = conn
+        .query_row(
+            "SELECT record_json FROM provider_failover WHERE codex_dir = ?1",
+            [&scope],
+            |row| row.get(0),
+        )
+        .expect("read recovery journal");
+    let mut record: Value = serde_json::from_str(&text).expect("parse recovery journal");
+    record["journals"].as_array_mut().unwrap().push(json!({
+        "primaryId":"inactive", "providerKey":"inactive", "originalTable":second_original,
+        "port":45556, "token":"secondary-local-token"
+    }));
+    conn.execute(
+        "UPDATE provider_failover SET record_json = ?1 WHERE codex_dir = ?2",
+        params![record.to_string(), scope],
+    )
+    .expect("append recovery identity");
+    drop(conn);
+    let detected = providers::detected_live_custom_provider(&fixture.dir)
+        .expect("detect selected provider")
+        .expect("selected third-party provider");
+    assert_eq!(detected.base_url, "https://primary.example.test/v1");
+    assert_eq!(detected.api_key.as_deref(), Some("real-test-key"));
+    assert!(!detected.toml_config.unwrap().contains("127.0.0.1"));
+    assert_eq!(
+        fs::read_to_string(config_path(&fixture.dir)).unwrap(),
+        fixture.raw
+    );
+}
+
+#[test]
+fn native_owned_route_keeps_official_status_quota_refresh_and_snapshot_credentials_scoped() {
+    let _guard = app_db::test_db_guard();
+    let mut fixture = OwnedRouteFixture::new();
+    let original = "name = 'OpenAI'\nwire_api = 'responses'\nrequires_openai_auth = true\nsupports_websockets = true\n";
+    fixture.raw = format!("model_provider='custom'\nmodel='official-model'\n[model_providers.custom]\nname='OpenAI'\nwire_api='responses'\nrequires_openai_auth=true\nsupports_websockets=false\nbase_url='http://127.0.0.1:45555/v1'\nhttp_headers={{'x-codex-x-route-token'='{}'}}\n[mcp_servers.keep]\ncommand='keep-native-mcp'\n", fixture.local_token);
+    fs::write(config_path(&fixture.dir), &fixture.raw).unwrap();
+    let record = json!({
+        "version":2,
+        "settings":{"routerEnabled":false,"takeoverEnabled":false,"autoFailoverEnabled":false,"providerIds":[]},
+        "journals":[{"primaryId":"official:openai-official","providerKey":"custom","originalTable":original,
+            "listenAddress":"127.0.0.1","port":45555,"token":fixture.local_token,"official":true,"tableExisted":true,"providersExisted":true}]
+    });
+    app_db::open()
+        .unwrap()
+        .execute(
+            "UPDATE provider_failover SET record_json=?1 WHERE codex_dir=?2",
+            params![
+                record.to_string(),
+                paths::normalized_path_scope(&fixture.dir)
+            ],
+        )
+        .unwrap();
+    let auth = json!({"auth_mode":"chatgpt","tokens":{"access_token":"native-current-access","refresh_token":"native-refresh","account_id":"native-account"}});
+    fs::write(auth_path(&fixture.dir), auth.to_string()).unwrap();
+    let config_before = fs::read(config_path(&fixture.dir)).unwrap();
+    let auth_before = fs::read(auth_path(&fixture.dir)).unwrap();
+    let state = build_state_after_migration(fixture.dir.clone()).unwrap();
+    assert!(state.is_official_provider);
+    assert_eq!(
+        state.active_official_profile_id.as_deref(),
+        Some("openai-official")
+    );
+    assert!(providers::detected_live_custom_provider(&fixture.dir)
+        .unwrap()
+        .is_none());
+    let profiles = list_official_profiles_inner(Some(fixture.dir.display().to_string())).unwrap();
+    assert!(profiles[0].is_current);
+    assert!(profiles[0].can_query_quota);
+    let credentials = providers::official_profiles::official_profile_quota_credentials(
+        &fixture.dir,
+        "openai-official",
+    )
+    .unwrap();
+    assert_eq!(credentials.access_token, "native-current-access");
+    let route = failover::native_official::route_for_current(&fixture.dir)
+        .unwrap()
+        .unwrap();
+    assert!(route.api_key.is_none());
+    let spec = route.official.unwrap();
+    assert!(failover::native_official::verify_request(
+        &spec,
+        "Bearer native-current-access",
+        Some("native-account")
+    )
+    .is_ok());
+    assert_eq!(fs::read(config_path(&fixture.dir)).unwrap(), config_before);
+    assert_eq!(fs::read(auth_path(&fixture.dir)).unwrap(), auth_before);
+    let refreshed = json!({"auth_mode":"chatgpt","tokens":{"access_token":"native-refreshed-access","refresh_token":"native-refreshed-refresh","account_id":"native-account"}});
+    fs::write(auth_path(&fixture.dir), refreshed.to_string()).unwrap();
+    assert_eq!(
+        providers::official_profiles::official_profile_quota_credentials(
+            &fixture.dir,
+            "openai-official"
+        )
+        .unwrap()
+        .access_token,
+        "native-refreshed-access"
+    );
+    assert!(failover::native_official::verify_request(
+        &spec,
+        "Bearer native-current-access",
+        Some("native-account")
+    )
+    .is_err());
+    assert!(failover::native_official::verify_request(
+        &spec,
+        "Bearer native-refreshed-access",
+        Some("native-account")
+    )
+    .is_ok());
+    assert!(providers::capture_live_chatgpt_config(&fixture.dir).unwrap());
+    let snapshot_path = providers::official_snapshot_path_for_test(&fixture.dir).unwrap();
+    let snapshot: Value = serde_json::from_slice(&fs::read(&snapshot_path).unwrap()).unwrap();
+    let saved_config = snapshot["config"].as_str().unwrap();
+    assert!(!saved_config.contains("127.0.0.1"));
+    assert!(!saved_config.contains("x-codex-x-route-token"));
+    assert!(!saved_config.contains(&fixture.local_token));
+    assert!(saved_config.contains("keep-native-mcp"));
+    assert_eq!(
+        snapshot["auth"]["tokens"]["access_token"],
+        "native-refreshed-access"
+    );
+    assert_eq!(fs::read(config_path(&fixture.dir)).unwrap(), config_before);
+    assert_eq!(
+        serde_json::from_slice::<Value>(&fs::read(auth_path(&fixture.dir)).unwrap()).unwrap(),
+        refreshed
+    );
+    fs::remove_file(snapshot_path).unwrap();
+}

apps/desktop/src-tauri/src/file_io.rs

@@ -0,0 +1,512 @@
+use crate::error::{CodexxError, Result};
+use chrono::Local;
+use serde_json::Value;
+use std::fs;
+use std::fs::OpenOptions;
+use std::io::Write;
+use std::path::Path;
+use toml_edit::DocumentMut;
+
+pub(crate) fn io_err(path: &Path, source: std::io::Error) -> CodexxError {
+    CodexxError::Io {
+        path: path.display().to_string(),
+        source,
+    }
+}
+
+pub(crate) fn json_err(path: &Path, source: serde_json::Error) -> CodexxError {
+    CodexxError::Json {
+        path: path.display().to_string(),
+        source,
+    }
+}
+
+#[cfg(target_os = "windows")]
+fn metadata_is_file_link(metadata: &fs::Metadata) -> bool {
+    use std::os::windows::fs::FileTypeExt;
+    metadata.file_type().is_symlink_file()
+}
+
+#[cfg(not(target_os = "windows"))]
+fn metadata_is_file_link(_metadata: &fs::Metadata) -> bool {
+    false
+}
+
+#[cfg(target_os = "windows")]
+fn metadata_is_directory_link(metadata: &fs::Metadata) -> bool {
+    use std::os::windows::fs::FileTypeExt;
+    metadata.file_type().is_symlink_dir()
+}
+
+#[cfg(not(target_os = "windows"))]
+fn metadata_is_directory_link(_metadata: &fs::Metadata) -> bool {
+    false
+}
+
+fn metadata_is_directory_entry(metadata: &fs::Metadata) -> bool {
+    metadata.is_dir() && !metadata_is_directory_link(metadata)
+}
+
+pub(crate) fn directory_exists(path: &Path) -> bool {
+    let Ok(metadata) = fs::symlink_metadata(path) else {
+        return false;
+    };
+    metadata_is_directory_entry(&metadata)
+        || (!metadata_is_file_link(&metadata)
+            && (metadata_is_directory_link(&metadata) || metadata.file_type().is_symlink())
+            && fs::metadata(path).is_ok_and(|target| target.is_dir()))
+}
+
+fn existing_directory_entry(path: &Path, metadata: &fs::Metadata) -> Result<()> {
+    if metadata_is_directory_entry(metadata) {
+        return Ok(());
+    }
+
+    if metadata_is_file_link(metadata) {
+        return Err(CodexxError::Config(format!(
+            "此链接被创建成了文件链接，不能作为文件夹使用：{}。请在创建链接的工具中重新建立目录链接",
+            path.display()
+        )));
+    }
+
+    if metadata_is_directory_link(metadata) || metadata.file_type().is_symlink() {
+        return match fs::metadata(path) {
+            Ok(target) if target.is_dir() => Ok(()),
+            _ => Err(CodexxError::Config(format!(
+                "文件夹链接已失效或目标不是文件夹：{}",
+                path.display()
+            ))),
+        };
+    }
+
+    Err(CodexxError::Config(format!(
+        "此路径已被同名文件占用，不是文件夹：{}",
+        path.display()
+    )))
+}
+
+pub(crate) fn ensure_directory(path: &Path) -> Result<()> {
+    match fs::symlink_metadata(path) {
+        Ok(metadata) => existing_directory_entry(path, &metadata),
+        Err(error) if error.kind() == std::io::ErrorKind::NotFound => {
+            match fs::create_dir_all(path) {
+                Ok(()) => Ok(()),
+                Err(create_error) => match fs::symlink_metadata(path) {
+                    Ok(metadata) => existing_directory_entry(path, &metadata),
+                    Err(_) => Err(io_err(path, create_error)),
+                },
+            }
+        }
+        Err(error) => Err(io_err(path, error)),
+    }
+}
+
+pub(crate) fn read_to_string_if_exists(path: &Path) -> Result<String> {
+    if !path.exists() {
+        return Ok(String::new());
+    }
+    fs::read_to_string(path).map_err(|e| io_err(path, e))
+}
+
+#[cfg(test)]
+pub(crate) fn harden_sensitive_file_permissions(path: &Path) -> Result<()> {
+    #[cfg(unix)]
+    {
+        use std::os::unix::fs::PermissionsExt;
+
+        let metadata = match fs::metadata(path) {
+            Ok(metadata) => metadata,
+            Err(error) if error.kind() == std::io::ErrorKind::NotFound => return Ok(()),
+            Err(error) => return Err(io_err(path, error)),
+        };
+        if !metadata.is_file() || metadata.permissions().mode() & 0o777 == 0o600 {
+            return Ok(());
+        }
+        fs::set_permissions(path, fs::Permissions::from_mode(0o600))
+            .map_err(|error| io_err(path, error))?;
+    }
+
+    #[cfg(not(unix))]
+    let _ = path;
+
+    Ok(())
+}
+
+pub(crate) fn parse_toml_document(path: &Path, text: &str) -> Result<DocumentMut> {
+    if text.trim().is_empty() {
+        return Ok(DocumentMut::new());
+    }
+    text.parse::<DocumentMut>().map_err(|e| CodexxError::Toml {
+        path: path.display().to_string(),
+        message: e.to_string(),
+    })
+}
+
+#[cfg(unix)]
+fn atomic_write_mode(path: &Path) -> Option<u32> {
+    use std::os::unix::fs::PermissionsExt;
+
+    let sensitive = path
+        .file_name()
+        .and_then(|name| name.to_str())
+        .is_some_and(|name| matches!(name, "config.toml" | "auth.json"));
+    if sensitive {
+        return Some(0o600);
+    }
+    fs::metadata(path)
+        .ok()
+        .map(|metadata| metadata.permissions().mode() & 0o777)
+}
+
+fn create_atomic_temp(path: &Path, tmp: &Path, private: bool) -> Result<fs::File> {
+    let mut options = OpenOptions::new();
+    options.write(true).create_new(true);
+
+    #[cfg(unix)]
+    {
+        use std::os::unix::fs::{OpenOptionsExt, PermissionsExt};
+
+        let mode = private.then_some(0o600).or_else(|| atomic_write_mode(path));
+        if let Some(mode) = mode {
+            options.mode(mode);
+            let file = options.open(tmp).map_err(|error| io_err(tmp, error))?;
+            fs::set_permissions(tmp, fs::Permissions::from_mode(mode))
+                .map_err(|error| io_err(tmp, error))?;
+            return Ok(file);
+        }
+    }
+
+    #[cfg(not(unix))]
+    let _ = private;
+
+    options.open(tmp).map_err(|error| io_err(tmp, error))
+}
+
+fn atomic_write_with_privacy_and_check<F>(
+    path: &Path,
+    bytes: &[u8],
+    private: bool,
+    pre_commit: F,
+) -> Result<()>
+where
+    F: FnOnce() -> Result<()>,
+{
+    use std::sync::atomic::{AtomicU64, Ordering};
+    static WRITE_COUNTER: AtomicU64 = AtomicU64::new(0);
+    if let Some(parent) = path.parent() {
+        ensure_directory(parent)?;
+    }
+    let tmp = path.with_extension(format!(
+        "tmp.{}.{}.{}",
+        std::process::id(),
+        Local::now().timestamp_nanos_opt().unwrap_or_default(),
+        WRITE_COUNTER.fetch_add(1, Ordering::Relaxed),
+    ));
+    let result = (|| {
+        let mut file = create_atomic_temp(path, &tmp, private)?;
+        file.write_all(bytes).map_err(|e| io_err(&tmp, e))?;
+        file.sync_all().map_err(|e| io_err(&tmp, e))?;
+        drop(file);
+        pre_commit()?;
+        fs::rename(&tmp, path).map_err(|e| io_err(path, e))
+    })();
+    if result.is_err() {
+        let _ = fs::remove_file(&tmp);
+    }
+    result
+}
+
+pub(crate) fn atomic_write(path: &Path, bytes: &[u8]) -> Result<()> {
+    atomic_write_with_privacy_and_check(path, bytes, false, || Ok(()))
+}
+
+pub(crate) fn atomic_write_checked<F>(path: &Path, bytes: &[u8], pre_commit: F) -> Result<()>
+where
+    F: FnOnce() -> Result<()>,
+{
+    atomic_write_with_privacy_and_check(path, bytes, false, pre_commit)
+}
+
+pub(crate) fn write_text(path: &Path, text: &str) -> Result<()> {
+    atomic_write(path, text.as_bytes())
+}
+
+pub(crate) fn write_json(path: &Path, value: &Value) -> Result<()> {
+    let text = serde_json::to_string_pretty(value).map_err(|e| json_err(path, e))?;
+    write_text(path, &(text + "\n"))
+}
+
+pub(crate) fn write_private_json(path: &Path, value: &Value) -> Result<()> {
+    let text = serde_json::to_string_pretty(value).map_err(|e| json_err(path, e))?;
+    atomic_write_with_privacy_and_check(path, (text + "\n").as_bytes(), true, || Ok(()))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::sync::atomic::{AtomicU64, Ordering};
+
+    fn temp_dir(name: &str) -> std::path::PathBuf {
+        static COUNTER: AtomicU64 = AtomicU64::new(0);
+        let path = std::env::temp_dir().join(format!(
+            "codex-x-file-io-{name}-{}-{}",
+            std::process::id(),
+            COUNTER.fetch_add(1, Ordering::Relaxed),
+        ));
+        let _ = fs::remove_dir_all(&path);
+        fs::create_dir_all(&path).expect("create test directory");
+        path
+    }
+
+    #[test]
+    fn atomic_write_replaces_existing_file_without_temp_residue() {
+        let dir = temp_dir("replace");
+        let path = dir.join("state.json");
+        fs::write(&path, b"old").expect("write original file");
+
+        atomic_write(&path, b"new").expect("replace file atomically");
+
+        assert_eq!(fs::read(&path).expect("read replaced file"), b"new");
+        let entries = fs::read_dir(&dir)
+            .expect("read test directory")
+            .map(|entry| entry.expect("read directory entry").file_name())
+            .collect::<Vec<_>>();
+        assert_eq!(entries, vec![path.file_name().unwrap().to_os_string()]);
+
+        fs::remove_dir_all(dir).expect("remove test directory");
+    }
+
+    #[test]
+    fn checked_atomic_write_rejects_a_change_immediately_before_replace() {
+        let dir = temp_dir("checked-race");
+        let path = dir.join("config.toml");
+        fs::write(&path, b"old").expect("write original file");
+
+        let error = atomic_write_checked(&path, b"codex-x", || {
+            fs::write(&path, b"external").expect("simulate external writer");
+            Err(CodexxError::Config("stale snapshot".to_string()))
+        })
+        .expect_err("stale checked write must fail");
+
+        assert!(error.to_string().contains("stale snapshot"));
+        assert_eq!(fs::read(&path).expect("read external value"), b"external");
+        assert_eq!(fs::read_dir(&dir).expect("read directory").count(), 1);
+        fs::remove_dir_all(dir).expect("remove test directory");
+    }
+
+    #[cfg(unix)]
+    #[test]
+    fn atomic_write_restricts_sensitive_codex_files_and_preserves_other_modes() {
+        use std::os::unix::fs::PermissionsExt;
+
+        let dir = temp_dir("permissions");
+        let config = dir.join("config.toml");
+        let auth = dir.join("auth.json");
+        let script = dir.join("tool.sh");
+        for path in [&config, &auth, &script] {
+            fs::write(path, b"old").expect("seed file");
+        }
+        fs::set_permissions(&config, fs::Permissions::from_mode(0o644)).expect("set config mode");
+        fs::set_permissions(&auth, fs::Permissions::from_mode(0o644)).expect("set auth mode");
+        fs::set_permissions(&script, fs::Permissions::from_mode(0o755)).expect("set script mode");
+
+        atomic_write(&config, b"new config").expect("replace config");
+        atomic_write(&auth, b"new auth").expect("replace auth");
+        atomic_write(&script, b"new script").expect("replace script");
+
+        let mode = |path: &Path| fs::metadata(path).unwrap().permissions().mode() & 0o777;
+        assert_eq!(mode(&config), 0o600);
+        assert_eq!(mode(&auth), 0o600);
+        assert_eq!(mode(&script), 0o755);
+        fs::remove_dir_all(dir).expect("remove test directory");
+    }
+
+    #[cfg(unix)]
+    #[test]
+    fn harden_sensitive_permissions_updates_existing_files_without_creating_missing_files() {
+        use std::os::unix::fs::PermissionsExt;
+
+        let dir = temp_dir("harden-permissions");
+        let config = dir.join("config.toml");
+        let missing = dir.join("auth.json");
+        fs::write(&config, b"model = \"gpt\"\n").expect("seed config");
+        fs::set_permissions(&config, fs::Permissions::from_mode(0o644)).expect("set open mode");
+
+        harden_sensitive_file_permissions(&config).expect("harden config");
+        harden_sensitive_file_permissions(&missing).expect("ignore missing auth");
+
+        assert_eq!(
+            fs::metadata(&config).unwrap().permissions().mode() & 0o777,
+            0o600
+        );
+        assert!(!missing.exists());
+        fs::remove_dir_all(dir).expect("remove test directory");
+    }
+
+    #[cfg(unix)]
+    #[test]
+    fn private_json_is_private_from_its_first_atomic_write() {
+        use std::os::unix::fs::PermissionsExt;
+
+        let dir = temp_dir("private-json");
+        let path = dir.join("official-snapshot.json");
+
+        write_private_json(&path, &serde_json::json!({"token": "secret"}))
+            .expect("write private JSON");
+
+        assert_eq!(
+            fs::metadata(&path).unwrap().permissions().mode() & 0o777,
+            0o600
+        );
+        fs::remove_dir_all(dir).expect("remove test directory");
+    }
+
+    #[test]
+    fn ensure_directory_accepts_existing_and_missing_directories() {
+        let root = temp_dir("ensure-directory");
+        let existing = root.join("existing");
+        let missing = root.join("missing").join("nested");
+        fs::create_dir(&existing).expect("create existing directory");
+
+        ensure_directory(&existing).expect("accept existing directory");
+        ensure_directory(&missing).expect("create missing directory");
+
+        assert!(missing.is_dir());
+        fs::remove_dir_all(root).expect("remove test directory");
+    }
+
+    #[test]
+    fn ensure_directory_rejects_a_file_without_removing_it() {
+        let root = temp_dir("ensure-directory-file");
+        let occupied = root.join(".codex");
+        fs::write(&occupied, "keep me").expect("create occupying file");
+
+        let error = ensure_directory(&occupied).expect_err("file is not a directory");
+
+        assert!(!directory_exists(&occupied));
+        assert!(error.to_string().contains("不是文件夹"));
+        assert_eq!(
+            fs::read_to_string(&occupied).expect("read occupying file"),
+            "keep me"
+        );
+        fs::remove_dir_all(root).expect("remove test directory");
+    }
+
+    #[cfg(unix)]
+    #[test]
+    fn ensure_directory_accepts_a_directory_symlink_and_rejects_a_broken_link() {
+        use std::os::unix::fs::symlink;
+
+        let root = temp_dir("ensure-directory-link");
+        let target = root.join("target");
+        let link = root.join("linked-codex-home");
+        let broken = root.join("broken-codex-home");
+        fs::create_dir(&target).expect("create target directory");
+        symlink(&target, &link).expect("create directory symlink");
+        symlink(root.join("missing-target"), &broken).expect("create broken symlink");
+
+        ensure_directory(&link).expect("accept directory symlink");
+        atomic_write(&link.join("config.toml"), b"linked").expect("write through symlink");
+        let error = ensure_directory(&broken).expect_err("reject broken symlink");
+
+        assert_eq!(
+            fs::read(target.join("config.toml")).expect("read symlink target"),
+            b"linked"
+        );
+        assert!(error.to_string().contains("链接已失效"));
+        fs::remove_dir_all(root).expect("remove test directory");
+    }
+
+    #[cfg(target_os = "windows")]
+    #[test]
+    fn ensure_directory_accepts_a_windows_directory_symlink() {
+        use std::os::windows::fs::symlink_dir;
+
+        let root = temp_dir("ensure-directory-windows-link");
+        let target = root.join("目标 文件夹");
+        let link = root.join("linked-codex-home");
+        fs::create_dir(&target).expect("create target directory");
+        match symlink_dir(&target, &link) {
+            Ok(()) => {}
+            Err(error) if error.raw_os_error() == Some(1314) => {
+                fs::remove_dir_all(root).expect("remove test directory");
+                return;
+            }
+            Err(error) => panic!("create directory symlink: {error}"),
+        }
+
+        ensure_directory(&link).expect("accept Windows directory symlink");
+        assert!(directory_exists(&link));
+        atomic_write(&link.join("config.toml"), b"first").expect("first linked write");
+        atomic_write(&link.join("config.toml"), b"second").expect("replace linked file");
+
+        assert_eq!(
+            fs::read(target.join("config.toml")).expect("read linked target"),
+            b"second"
+        );
+        fs::remove_file(target.join("config.toml")).expect("remove target file");
+        fs::remove_dir(&target).expect("remove symlink target");
+        let error = ensure_directory(&link).expect_err("reject broken directory symlink");
+        assert!(!directory_exists(&link));
+        assert!(error.to_string().contains("链接已失效"));
+        fs::remove_dir(&link).expect("remove directory symlink");
+        fs::remove_dir_all(root).expect("remove test directory");
+    }
+
+    #[cfg(target_os = "windows")]
+    #[test]
+    fn ensure_directory_accepts_a_windows_junction() {
+        use std::process::Command;
+
+        let root = temp_dir("ensure-directory-windows-junction");
+        let target = root.join("junction-target");
+        let link = root.join("junction-codex-home");
+        fs::create_dir(&target).expect("create junction target");
+        let status = Command::new("cmd")
+            .args(["/C", "mklink", "/J"])
+            .arg(&link)
+            .arg(&target)
+            .status()
+            .expect("run mklink");
+        assert!(status.success(), "create directory junction");
+
+        ensure_directory(&link).expect("accept Windows junction");
+        assert!(directory_exists(&link));
+        atomic_write(&link.join("config.toml"), b"junction").expect("write through junction");
+
+        assert_eq!(
+            fs::read(target.join("config.toml")).expect("read junction target"),
+            b"junction"
+        );
+        fs::remove_dir(&link).expect("remove directory junction");
+        fs::remove_dir_all(root).expect("remove test directory");
+    }
+
+    #[cfg(target_os = "windows")]
+    #[test]
+    fn ensure_directory_rejects_a_file_link_to_a_directory_without_removing_it() {
+        use std::os::windows::fs::symlink_file;
+
+        let root = temp_dir("ensure-directory-windows-file-link");
+        let target = root.join("target");
+        let link = root.join("linked-codex-home");
+        fs::create_dir(&target).expect("create target directory");
+        match symlink_file(&target, &link) {
+            Ok(()) => {}
+            Err(error) if error.raw_os_error() == Some(1314) => {
+                fs::remove_dir_all(root).expect("remove test directory");
+                return;
+            }
+            Err(error) => panic!("create file link: {error}"),
+        }
+
+        let error = ensure_directory(&link).expect_err("reject file link as directory");
+
+        assert!(!directory_exists(&link));
+        assert!(error.to_string().contains("文件链接"));
+        assert!(fs::symlink_metadata(&link).is_ok());
+        assert!(target.is_dir());
+        fs::remove_file(&link).expect("remove file link");
+        fs::remove_dir_all(root).expect("remove test directory");
+    }
+}

apps/desktop/src-tauri/src/live_config.rs

@@ -0,0 +1,213 @@
+use crate::error::{CodexxError, Result};
+use crate::file_io::{atomic_write_checked, ensure_directory, io_err};
+use std::fs;
+use std::io::Write;
+use std::path::Path;
+
+pub(crate) struct LiveConfigLock {
+    file: fs::File,
+}
+
+impl Drop for LiveConfigLock {
+    fn drop(&mut self) {
+        let _ = self.file.unlock();
+    }
+}
+
+pub(crate) fn acquire_live_config_lock(codex_dir: &Path) -> Result<LiveConfigLock> {
+    let tmp_dir = codex_dir.join("tmp");
+    ensure_directory(&tmp_dir)?;
+    let path = tmp_dir.join("codex-x-live-config.lock");
+    if path.is_dir() {
+        return Err(CodexxError::Config(format!(
+            "Codex live 配置锁被同名目录占用: {}",
+            path.display()
+        )));
+    }
+    let mut file = fs::OpenOptions::new()
+        .create(true)
+        .truncate(false)
+        .read(true)
+        .write(true)
+        .open(&path)
+        .map_err(|error| io_err(&path, error))?;
+    file.try_lock().map_err(|_| {
+        CodexxError::Config(format!(
+            "另一个 Codex-X 正在修改 Codex live 配置，请稍后重试: {}",
+            path.display()
+        ))
+    })?;
+    file.set_len(0).map_err(|error| io_err(&path, error))?;
+    writeln!(file, "pid={}", std::process::id()).map_err(|error| io_err(&path, error))?;
+    file.sync_all().map_err(|error| io_err(&path, error))?;
+    Ok(LiveConfigLock { file })
+}
+
+pub(crate) fn read_file_snapshot(path: &Path) -> Result<Option<Vec<u8>>> {
+    match fs::read(path) {
+        Ok(bytes) => Ok(Some(bytes)),
+        Err(error) if error.kind() == std::io::ErrorKind::NotFound => Ok(None),
+        Err(error) => Err(io_err(path, error)),
+    }
+}
+
+pub(crate) fn text_from_snapshot(path: &Path, snapshot: Option<&[u8]>) -> Result<String> {
+    String::from_utf8(snapshot.unwrap_or_default().to_vec())
+        .map_err(|_| CodexxError::Config(format!("{} 不是有效的 UTF-8 文本", path.display())))
+}
+
+pub(crate) fn ensure_file_snapshot_unchanged(path: &Path, expected: Option<&[u8]>) -> Result<()> {
+    if read_file_snapshot(path)?.as_deref() == expected {
+        return Ok(());
+    }
+    Err(CodexxError::Config(format!(
+        "{} 已被其他程序修改，本次写入已取消，请刷新后重试",
+        path.display()
+    )))
+}
+
+pub(crate) fn atomic_write_if_unchanged(
+    path: &Path,
+    expected: Option<&[u8]>,
+    replacement: &[u8],
+) -> Result<()> {
+    atomic_write_checked(path, replacement, || {
+        ensure_file_snapshot_unchanged(path, expected)
+    })
+}
+
+pub(crate) fn remove_file_if_unchanged(path: &Path, expected: Option<&[u8]>) -> Result<()> {
+    ensure_file_snapshot_unchanged(path, expected)?;
+    match fs::remove_file(path) {
+        Ok(()) => Ok(()),
+        Err(error) if error.kind() == std::io::ErrorKind::NotFound => Ok(()),
+        Err(error) => Err(io_err(path, error)),
+    }
+}
+
+pub(crate) fn restore_file_snapshot_if_unchanged(
+    path: &Path,
+    expected_current: Option<&[u8]>,
+    snapshot: Option<&[u8]>,
+) -> Result<()> {
+    match snapshot {
+        Some(bytes) => atomic_write_if_unchanged(path, expected_current, bytes),
+        None => remove_file_if_unchanged(path, expected_current),
+    }
+}
+
+pub(crate) struct AppliedFileChange {
+    path: std::path::PathBuf,
+    before: Option<Vec<u8>>,
+    after: Option<Vec<u8>>,
+    changed: bool,
+}
+
+impl AppliedFileChange {
+    pub(crate) fn rollback(&self) -> Result<()> {
+        if !self.changed {
+            return Ok(());
+        }
+        restore_file_snapshot_if_unchanged(
+            &self.path,
+            self.after.as_deref(),
+            self.before.as_deref(),
+        )
+    }
+}
+
+pub(crate) fn apply_file_change(
+    path: &Path,
+    before: Option<Vec<u8>>,
+    after: Option<Vec<u8>>,
+) -> Result<AppliedFileChange> {
+    let changed = before != after;
+    if changed {
+        match after.as_deref() {
+            Some(bytes) => atomic_write_if_unchanged(path, before.as_deref(), bytes)?,
+            None => remove_file_if_unchanged(path, before.as_deref())?,
+        }
+    }
+    Ok(AppliedFileChange {
+        path: path.to_path_buf(),
+        before,
+        after,
+        changed,
+    })
+}
+
+pub(crate) fn rollback_file_changes(changes: &[AppliedFileChange]) -> Result<()> {
+    for change in changes.iter().filter(|change| change.changed) {
+        ensure_file_snapshot_unchanged(&change.path, change.after.as_deref())?;
+    }
+
+    let mut failures = Vec::new();
+    for change in changes.iter().rev() {
+        if let Err(error) = change.rollback() {
+            failures.push(error.to_string());
+        }
+    }
+    if failures.is_empty() {
+        Ok(())
+    } else {
+        Err(CodexxError::Config(failures.join("；")))
+    }
+}
+
+pub(crate) fn fail_with_file_rollback<T>(
+    error: CodexxError,
+    changes: &[AppliedFileChange],
+) -> Result<T> {
+    match rollback_file_changes(changes) {
+        Ok(()) => Err(error),
+        Err(rollback_error) => Err(CodexxError::Config(format!(
+            "{error}；文件回滚失败：{rollback_error}"
+        ))),
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::sync::atomic::{AtomicU64, Ordering};
+
+    fn temp_dir(name: &str) -> std::path::PathBuf {
+        static COUNTER: AtomicU64 = AtomicU64::new(0);
+        let path = std::env::temp_dir().join(format!(
+            "codex-x-live-config-{name}-{}-{}",
+            std::process::id(),
+            COUNTER.fetch_add(1, Ordering::Relaxed),
+        ));
+        let _ = fs::remove_dir_all(&path);
+        fs::create_dir_all(&path).expect("create test directory");
+        path
+    }
+
+    #[test]
+    fn lock_rejects_a_second_writer_and_releases_on_drop() {
+        let dir = temp_dir("lock");
+        let first = acquire_live_config_lock(&dir).expect("acquire first lock");
+        let error = acquire_live_config_lock(&dir)
+            .err()
+            .expect("second lock must fail");
+        assert!(error.to_string().contains("另一个 Codex-X"));
+        drop(first);
+        acquire_live_config_lock(&dir).expect("lock is released on drop");
+        fs::remove_dir_all(dir).expect("remove test directory");
+    }
+
+    #[test]
+    fn stale_checked_write_preserves_the_external_value() {
+        let dir = temp_dir("stale");
+        let path = dir.join("config.toml");
+        fs::write(&path, b"old").expect("seed file");
+        let old = read_file_snapshot(&path).expect("capture file");
+        fs::write(&path, b"external").expect("simulate external writer");
+
+        atomic_write_if_unchanged(&path, old.as_deref(), b"codex-x")
+            .expect_err("stale write must fail");
+
+        assert_eq!(fs::read(&path).expect("read file"), b"external");
+        fs::remove_dir_all(dir).expect("remove test directory");
+    }
+}

apps/desktop/src-tauri/src/paths.rs

@@ -0,0 +1,45 @@
+use crate::error::{CodexxError, Result};
+#[cfg(test)]
+use chrono::Local;
+use std::path::{Path, PathBuf};
+
+pub(crate) fn home_dir() -> Result<PathBuf> {
+    dirs::home_dir().ok_or(CodexxError::NoHomeDir)
+}
+
+pub(crate) fn app_home() -> Result<PathBuf> {
+    #[cfg(test)]
+    {
+        use std::sync::OnceLock;
+        static TEST_APP_HOME: OnceLock<PathBuf> = OnceLock::new();
+        Ok(TEST_APP_HOME
+            .get_or_init(|| {
+                std::env::temp_dir().join(format!(
+                    "codex-x-test-home-{}-{}",
+                    std::process::id(),
+                    Local::now().timestamp_nanos_opt().unwrap_or_default()
+                ))
+            })
+            .clone())
+    }
+    #[cfg(not(test))]
+    {
+        if let Ok(value) = std::env::var("CODEXX_HOME") {
+            let trimmed = value.trim();
+            if !trimmed.is_empty() {
+                return Ok(PathBuf::from(trimmed));
+            }
+        }
+        Ok(home_dir()?.join(".codexx"))
+    }
+}
+
+pub(crate) fn normalized_path_scope(path: &Path) -> String {
+    let resolved = path.canonicalize().unwrap_or_else(|_| path.to_path_buf());
+    let normalized = resolved.to_string_lossy().replace('\\', "/");
+    if cfg!(target_os = "windows") {
+        normalized.to_ascii_lowercase()
+    } else {
+        normalized
+    }
+}

apps/desktop/src-tauri/src/prompts/managed_agents.rs

@@ -0,0 +1,114 @@
+use crate::constants::{
+    AGENTS_FILENAME, AGENTS_MANAGED_BEGIN, AGENTS_MANAGED_END, AGENTS_TEMPLATE_PREFIX,
+};
+use crate::error::{CodexxError, Result};
+use crate::file_io::read_to_string_if_exists;
+#[cfg(test)]
+use crate::live_config::{apply_file_change, read_file_snapshot, text_from_snapshot};
+use std::path::{Path, PathBuf};
+
+pub(crate) fn agents_path(codex_dir: &Path) -> PathBuf {
+    codex_dir.join(AGENTS_FILENAME)
+}
+
+pub(crate) fn managed_agents_bounds(content: &str) -> Result<Option<(usize, usize)>> {
+    let begins = content
+        .match_indices(AGENTS_MANAGED_BEGIN)
+        .map(|(index, _)| index)
+        .collect::<Vec<_>>();
+    let ends = content
+        .match_indices(AGENTS_MANAGED_END)
+        .map(|(index, _)| index)
+        .collect::<Vec<_>>();
+
+    if begins.is_empty() && ends.is_empty() {
+        return Ok(None);
+    }
+    if begins.len() != 1 || ends.len() != 1 || begins[0] >= ends[0] {
+        return Err(CodexxError::Config(
+            "AGENTS.md 中的 Codex-X 受管区块标记不完整或重复，请先修复 BEGIN/END 标记".to_string(),
+        ));
+    }
+    Ok(Some((begins[0], ends[0] + AGENTS_MANAGED_END.len())))
+}
+
+pub(crate) fn remove_managed_agents_block_from_content(content: &str) -> Result<(String, bool)> {
+    let Some((start, end)) = managed_agents_bounds(content)? else {
+        return Ok((content.to_string(), false));
+    };
+    let before = content[..start].trim_end();
+    let after = content[end..].trim_start();
+    let merged = match (before.is_empty(), after.is_empty()) {
+        (true, true) => String::new(),
+        (false, true) => format!("{}\n", before),
+        (true, false) => format!("{}\n", after.trim_end()),
+        (false, false) => format!("{}\n\n{}\n", before, after.trim_end()),
+    };
+    Ok((merged, true))
+}
+
+pub(crate) fn install_managed_agents_block_in_content(
+    existing: &str,
+    template_key: &str,
+    content: &str,
+) -> Result<String> {
+    let (base, _) = remove_managed_agents_block_from_content(existing)?;
+    let managed = format!(
+        "{AGENTS_MANAGED_BEGIN}\n{AGENTS_TEMPLATE_PREFIX} {template_key} -->\n{}\n{AGENTS_MANAGED_END}",
+        content.trim()
+    );
+    Ok(if base.trim().is_empty() {
+        format!("{managed}\n")
+    } else {
+        format!("{}\n\n{managed}\n", base.trim_end())
+    })
+}
+
+pub(crate) fn managed_agents_template_key_from_content(content: &str) -> Option<String> {
+    let (start, end) = managed_agents_bounds(content).ok().flatten()?;
+    content[start..end].lines().find_map(|line| {
+        line.trim()
+            .strip_prefix(AGENTS_TEMPLATE_PREFIX)
+            .and_then(|value| value.strip_suffix("-->"))
+            .map(str::trim)
+            .filter(|value| !value.is_empty())
+            .map(ToString::to_string)
+    })
+}
+
+pub(crate) fn managed_agents_template_key(codex_dir: &Path) -> Result<Option<String>> {
+    let path = agents_path(codex_dir);
+    let content = read_to_string_if_exists(&path)?;
+    Ok(managed_agents_template_key_from_content(&content))
+}
+
+#[cfg(test)]
+pub(crate) fn install_managed_agents_block(
+    codex_dir: &Path,
+    template_key: &str,
+    content: &str,
+) -> Result<()> {
+    let path = agents_path(codex_dir);
+    let before = read_file_snapshot(&path)?;
+    let existing = text_from_snapshot(&path, before.as_deref())?;
+    let next = install_managed_agents_block_in_content(&existing, template_key, content)?;
+    apply_file_change(&path, before, Some(next.into_bytes()))?;
+    Ok(())
+}
+
+#[cfg(test)]
+pub(crate) fn uninstall_managed_agents_block(codex_dir: &Path) -> Result<bool> {
+    let path = agents_path(codex_dir);
+    let before = read_file_snapshot(&path)?;
+    if before.is_none() {
+        return Ok(false);
+    }
+    let existing = text_from_snapshot(&path, before.as_deref())?;
+    let (next, removed) = remove_managed_agents_block_from_content(&existing)?;
+    if !removed {
+        return Ok(false);
+    }
+    let after = (!next.trim().is_empty()).then(|| next.into_bytes());
+    apply_file_change(&path, before, after)?;
+    Ok(true)
+}

apps/desktop/src-tauri/src/prompts/mod.rs

@@ -0,0 +1,136 @@
+mod catalog;
+mod managed_agents;
+mod store;
+mod types;
+
+pub(crate) use catalog::{
+    builtin_prompt_content, builtin_prompt_detail_inner, builtin_prompt_status_inner,
+    bundled_prompt_meta, bundled_prompt_metas, refresh_builtin_prompts_with_active,
+};
+pub(crate) use managed_agents::{
+    agents_path, install_managed_agents_block_in_content, managed_agents_bounds,
+    managed_agents_template_key, remove_managed_agents_block_from_content,
+};
+#[cfg(test)]
+pub(crate) use managed_agents::{install_managed_agents_block, uninstall_managed_agents_block};
+pub(crate) use store::{
+    delete_prompt_inner, get_saved_prompt_inner, list_saved_prompts_inner,
+    normalize_prompt_filename, save_builtin_prompt_override_inner, save_prompt_inner,
+};
+pub(crate) use types::{BuiltinPromptDetail, BuiltinPromptStatus, SavedPrompt};
+
+#[cfg(test)]
+pub(crate) use catalog::{
+    cached_prompt_fallback_statuses, delete_cached_prompt_ids, github_prompt_catalog_from_entries,
+    jsdelivr_prompt_catalog_from_entries, prompt_content_source_urls, stable_remote_prompt_id,
+    stale_cached_prompt_ids,
+};
+#[cfg(test)]
+pub(crate) use managed_agents::managed_agents_template_key_from_content;
+#[cfg(test)]
+pub(crate) use types::{CachedBuiltinPrompt, GithubContentEntry};
+
+use crate::error::Result;
+use crate::file_io::{parse_toml_document, read_to_string_if_exists};
+use crate::paths::home_dir;
+use crate::{config_path, sanitize_id, string_value};
+use catalog::cached_builtin_prompts;
+use std::path::{Path, PathBuf};
+use store::find_saved_prompt_by_current_file;
+
+fn builtin_prompt_id_for_filename(filename: &str) -> Result<Option<String>> {
+    if let Some(meta) = bundled_prompt_metas()
+        .into_iter()
+        .find(|item| item.filename.eq_ignore_ascii_case(filename))
+    {
+        return Ok(Some(meta.id.to_string()));
+    }
+    Ok(cached_builtin_prompts()?
+        .into_iter()
+        .find(|item| item.filename.eq_ignore_ascii_case(filename))
+        .map(|item| item.id))
+}
+
+fn saved_prompt_id_for_filename(filename: &str) -> Result<Option<String>> {
+    Ok(list_saved_prompts_inner()?
+        .into_iter()
+        .find(|item| item.filename.eq_ignore_ascii_case(filename))
+        .map(|item| item.id))
+}
+
+pub(crate) fn prompt_template_key_for_instruction(value: &str) -> Result<Option<String>> {
+    let normalized = value.replace('\\', "/");
+    let filename = normalized.rsplit('/').next().unwrap_or(&normalized);
+    if let Some(id) = builtin_prompt_id_for_filename(filename)? {
+        return Ok(Some(format!("builtin:{id}")));
+    }
+    Ok(saved_prompt_id_for_filename(filename)?.map(|id| format!("saved:{id}")))
+}
+
+pub(crate) fn resolve_instruction_path(codex_dir: &Path, value: &str) -> PathBuf {
+    let trimmed = value.trim();
+    let expanded = if trimmed == "~" {
+        home_dir().unwrap_or_else(|_| codex_dir.to_path_buf())
+    } else if let Some(rest) = trimmed.strip_prefix("~/") {
+        home_dir()
+            .map(|home| home.join(rest))
+            .unwrap_or_else(|_| PathBuf::from(trimmed))
+    } else {
+        PathBuf::from(trimmed)
+    };
+    if expanded.is_absolute() {
+        expanded
+    } else {
+        codex_dir.join(expanded)
+    }
+}
+
+pub(crate) fn remember_current_instruction_prompt(codex_dir: &Path) -> Result<Option<SavedPrompt>> {
+    let cfg = config_path(codex_dir);
+    let text = read_to_string_if_exists(&cfg)?;
+    if text.trim().is_empty() {
+        return Ok(None);
+    }
+    let doc = parse_toml_document(&cfg, &text)?;
+    let Some(current) = string_value(&doc, "model_instructions_file") else {
+        return Ok(None);
+    };
+    if prompt_template_key_for_instruction(&current)?.is_some() {
+        return Ok(None);
+    }
+    let path = resolve_instruction_path(codex_dir, &current);
+    if !path.is_file() {
+        return Ok(None);
+    }
+    let content = read_to_string_if_exists(&path)?;
+    if content.trim().is_empty() {
+        return Ok(None);
+    }
+    let file_name = path
+        .file_name()
+        .and_then(|v| v.to_str())
+        .map(ToString::to_string)
+        .unwrap_or_else(|| "external-prompt.md".to_string());
+    let stem = path
+        .file_stem()
+        .and_then(|v| v.to_str())
+        .unwrap_or("external-prompt");
+    let normalized_filename = normalize_prompt_filename(&file_name, "external-prompt");
+    let existing = find_saved_prompt_by_current_file(&file_name, &content)?;
+    let (id, title, filename) = existing
+        .map(|prompt| (prompt.id, prompt.title, prompt.filename))
+        .unwrap_or_else(|| {
+            (
+                format!("external-{}", sanitize_id(stem)),
+                format!("外部提示词 · {stem}"),
+                normalized_filename,
+            )
+        });
+    save_prompt_inner(SavedPrompt {
+        id,
+        title,
+        filename,
+        content,
+    })
+    .map(Some)
+}

apps/desktop/src-tauri/src/prompts/store.rs

@@ -0,0 +1,312 @@
+use super::types::SavedPrompt;
+use crate::error::{CodexxError, Result};
+use crate::{now_rfc3339, open_db};
+use rusqlite::params;
+use std::collections::HashSet;
+
+pub(crate) fn normalize_prompt_filename(input: &str, fallback: &str) -> String {
+    let raw = input.trim().trim_end_matches(".md");
+    let base = if raw.is_empty() { fallback } else { raw };
+    let mut out = String::new();
+    let mut last_dash = false;
+    for ch in base.to_ascii_lowercase().chars() {
+        if ch.is_ascii_alphanumeric() || ch == '_' || ch == '-' {
+            out.push(ch);
+            last_dash = false;
+        } else if !last_dash {
+            out.push('-');
+            last_dash = true;
+        }
+    }
+    let out = out.trim_matches('-');
+    format!("{}.md", if out.is_empty() { "custom-prompt" } else { out })
+}
+
+fn canonical_prompt_content(input: &str) -> String {
+    input
+        .replace("\r\n", "\n")
+        .replace('\r', "\n")
+        .trim()
+        .to_string()
+}
+
+pub(crate) fn list_saved_prompts_inner() -> Result<Vec<SavedPrompt>> {
+    let conn = open_db()?;
+    let mut stmt = conn
+        .prepare("SELECT id, title, filename, content FROM prompts ORDER BY updated_at DESC, created_at DESC")
+        .map_err(|e| CodexxError::Database(e.to_string()))?;
+    let rows = stmt
+        .query_map([], |row| {
+            Ok(SavedPrompt {
+                id: row.get(0)?,
+                title: row.get(1)?,
+                filename: row.get(2)?,
+                content: row.get(3)?,
+            })
+        })
+        .map_err(|e| CodexxError::Database(e.to_string()))?;
+    let mut prompts = Vec::new();
+    for row in rows {
+        let prompt = row.map_err(|e| CodexxError::Database(e.to_string()))?;
+        let filename_key = prompt.filename.to_ascii_lowercase();
+        let content_key = canonical_prompt_content(&prompt.content);
+        let duplicate_index = prompts.iter().position(|existing: &SavedPrompt| {
+            existing.filename.to_ascii_lowercase() == filename_key
+                || (canonical_prompt_content(&existing.content) == content_key
+                    && (existing.id.starts_with("external-") || prompt.id.starts_with("external-")))
+        });
+        if let Some(index) = duplicate_index {
+            let existing_is_external = prompts[index].id.starts_with("external-");
+            let prompt_is_external = prompt.id.starts_with("external-");
+            if existing_is_external && !prompt_is_external {
+                prompts[index] = prompt;
+            }
+            continue;
+        }
+        prompts.push(prompt);
+    }
+    Ok(prompts)
+}
+
+pub(crate) fn save_prompt_inner(prompt: SavedPrompt) -> Result<SavedPrompt> {
+    let conn = open_db()?;
+    let now = now_rfc3339();
+    conn.execute(
+        "INSERT INTO prompts (id, title, filename, content, created_at, updated_at)
+         VALUES (?1, ?2, ?3, ?4, ?5, ?5)
+         ON CONFLICT(id) DO UPDATE SET
+            title = excluded.title,
+            filename = excluded.filename,
+            content = excluded.content,
+            updated_at = excluded.updated_at",
+        params![
+            prompt.id,
+            prompt.title,
+            prompt.filename,
+            prompt.content,
+            now
+        ],
+    )
+    .map_err(|e| CodexxError::Database(e.to_string()))?;
+    list_saved_prompts_inner()?
+        .into_iter()
+        .find(|p| p.id == prompt.id)
+        .ok_or_else(|| CodexxError::Database("prompt saved but not found".to_string()))
+}
+
+pub(crate) fn get_saved_prompt_inner(id: &str) -> Result<SavedPrompt> {
+    list_saved_prompts_inner()?
+        .into_iter()
+        .find(|p| p.id == id)
+        .ok_or_else(|| CodexxError::Config(format!("提示词不存在: {id}")))
+}
+
+pub(crate) fn delete_prompt_inner(id: &str) -> Result<()> {
+    let conn = open_db()?;
+    conn.execute("DELETE FROM prompts WHERE id = ?1", params![id])
+        .map_err(|e| CodexxError::Database(e.to_string()))?;
+    Ok(())
+}
+
+fn builtin_prompt_override_from_connection(
+    conn: &rusqlite::Connection,
+    template_id: &str,
+) -> Result<Option<String>> {
+    match conn.query_row(
+        "SELECT content FROM builtin_prompt_overrides WHERE template_id = ?1",
+        [template_id],
+        |row| row.get(0),
+    ) {
+        Ok(content) => Ok(Some(content)),
+        Err(rusqlite::Error::QueryReturnedNoRows) => Ok(None),
+        Err(e) => Err(CodexxError::Database(e.to_string())),
+    }
+}
+
+pub(crate) fn builtin_prompt_override_inner(template_id: &str) -> Result<Option<String>> {
+    let conn = open_db()?;
+    builtin_prompt_override_from_connection(&conn, template_id.trim())
+}
+
+pub(crate) fn builtin_prompt_override_ids_inner() -> Result<HashSet<String>> {
+    let conn = open_db()?;
+    let mut stmt = conn
+        .prepare("SELECT template_id FROM builtin_prompt_overrides")
+        .map_err(|e| CodexxError::Database(e.to_string()))?;
+    let rows = stmt
+        .query_map([], |row| row.get(0))
+        .map_err(|e| CodexxError::Database(e.to_string()))?;
+    rows.map(|row| row.map_err(|e| CodexxError::Database(e.to_string())))
+        .collect()
+}
+
+fn save_builtin_prompt_override_on_connection(
+    conn: &rusqlite::Connection,
+    template_id: &str,
+    content: &str,
+) -> Result<()> {
+    let id = template_id.trim();
+    if id.is_empty() {
+        return Err(CodexxError::Config("提示词模板标识不能为空".to_string()));
+    }
+    if content.trim().is_empty() {
+        return Err(CodexxError::Config("提示词内容不能为空".to_string()));
+    }
+    let now = now_rfc3339();
+    conn.execute(
+        "INSERT INTO builtin_prompt_overrides (template_id, content, created_at, updated_at)
+         VALUES (?1, ?2, ?3, ?3)
+         ON CONFLICT(template_id) DO UPDATE SET
+           content = excluded.content,
+           updated_at = excluded.updated_at",
+        params![id, content, now],
+    )
+    .map_err(|e| CodexxError::Database(e.to_string()))?;
+    Ok(())
+}
+
+pub(crate) fn save_builtin_prompt_override_inner(template_id: &str, content: &str) -> Result<()> {
+    let conn = open_db()?;
+    save_builtin_prompt_override_on_connection(&conn, template_id, content)
+}
+
+fn find_saved_prompt_by_content(content: &str) -> Result<Option<SavedPrompt>> {
+    let conn = open_db()?;
+    let mut stmt = conn
+        .prepare("SELECT id, title, filename, content FROM prompts ORDER BY CASE WHEN id LIKE 'external-%' THEN 1 ELSE 0 END, updated_at DESC, created_at DESC")
+        .map_err(|e| CodexxError::Database(e.to_string()))?;
+    let rows = stmt
+        .query_map([], |row| {
+            Ok(SavedPrompt {
+                id: row.get(0)?,
+                title: row.get(1)?,
+                filename: row.get(2)?,
+                content: row.get(3)?,
+            })
+        })
+        .map_err(|e| CodexxError::Database(e.to_string()))?;
+    let target = canonical_prompt_content(content);
+    for row in rows {
+        let prompt = row.map_err(|e| CodexxError::Database(e.to_string()))?;
+        if canonical_prompt_content(&prompt.content) == target {
+            return Ok(Some(prompt));
+        }
+    }
+    Ok(None)
+}
+
+pub(super) fn find_saved_prompt_by_current_file(
+    filename: &str,
+    content: &str,
+) -> Result<Option<SavedPrompt>> {
+    if let Some(prompt) = find_saved_prompt_by_content(content)? {
+        return Ok(Some(prompt));
+    }
+    let normalized_filename = normalize_prompt_filename(filename, "external-prompt");
+    let conn = open_db()?;
+    let mut stmt = conn
+        .prepare(
+            "SELECT id, title, filename, content FROM prompts
+             WHERE lower(filename) = lower(?1)
+             ORDER BY CASE WHEN id LIKE 'external-%' THEN 1 ELSE 0 END, updated_at DESC, created_at DESC
+             LIMIT 1",
+        )
+        .map_err(|e| CodexxError::Database(e.to_string()))?;
+    match stmt.query_row([normalized_filename], |row| {
+        Ok(SavedPrompt {
+            id: row.get(0)?,
+            title: row.get(1)?,
+            filename: row.get(2)?,
+            content: row.get(3)?,
+        })
+    }) {
+        Ok(mut prompt) => {
+            if canonical_prompt_content(&prompt.content) != canonical_prompt_content(content) {
+                prompt.content = content.to_string();
+            }
+            Ok(Some(prompt))
+        }
+        Err(rusqlite::Error::QueryReturnedNoRows) => Ok(None),
+        Err(e) => Err(CodexxError::Database(e.to_string())),
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use rusqlite::Connection;
+
+    fn override_connection() -> Connection {
+        let conn = Connection::open_in_memory().expect("open override database");
+        conn.execute_batch(
+            "CREATE TABLE builtin_prompt_overrides (
+                template_id TEXT PRIMARY KEY,
+                content TEXT NOT NULL,
+                created_at TEXT NOT NULL,
+                updated_at TEXT NOT NULL
+            );",
+        )
+        .expect("create override table");
+        conn
+    }
+
+    #[test]
+    fn builtin_prompt_override_can_be_edited_repeatedly() {
+        let conn = override_connection();
+        save_builtin_prompt_override_on_connection(&conn, "template", "first")
+            .expect("save initial override");
+        save_builtin_prompt_override_on_connection(&conn, "template", "second")
+            .expect("update override");
+
+        assert_eq!(
+            builtin_prompt_override_from_connection(&conn, "template")
+                .expect("read override")
+                .as_deref(),
+            Some("second")
+        );
+    }
+
+    #[test]
+    fn builtin_prompt_override_rejects_empty_content() {
+        let conn = override_connection();
+        let error = save_builtin_prompt_override_on_connection(&conn, "template", "  \n")
+            .expect_err("reject empty override");
+        assert!(error.to_string().contains("内容不能为空"));
+    }
+
+    #[test]
+    fn builtin_prompt_override_survives_database_reopen() {
+        let database_path = std::env::temp_dir().join(format!(
+            "codexx-prompt-override-{}-{}.sqlite",
+            std::process::id(),
+            std::time::SystemTime::now()
+                .duration_since(std::time::UNIX_EPOCH)
+                .expect("system time")
+                .as_nanos()
+        ));
+        {
+            let conn = Connection::open(&database_path).expect("open override database");
+            conn.execute_batch(
+                "CREATE TABLE builtin_prompt_overrides (
+                    template_id TEXT PRIMARY KEY,
+                    content TEXT NOT NULL,
+                    created_at TEXT NOT NULL,
+                    updated_at TEXT NOT NULL
+                );",
+            )
+            .expect("create override table");
+            save_builtin_prompt_override_on_connection(&conn, "template", "local content")
+                .expect("save override");
+        }
+
+        let reopened = Connection::open(&database_path).expect("reopen override database");
+        assert_eq!(
+            builtin_prompt_override_from_connection(&reopened, "template")
+                .expect("read persisted override")
+                .as_deref(),
+            Some("local content")
+        );
+        drop(reopened);
+        std::fs::remove_file(database_path).expect("remove override database");
+    }
+}

apps/desktop/src-tauri/src/prompts/types.rs

@@ -0,0 +1,65 @@
+use serde::{Deserialize, Serialize};
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub(crate) struct SavedPrompt {
+    pub(crate) id: String,
+    pub(crate) title: String,
+    pub(crate) filename: String,
+    pub(crate) content: String,
+}
+
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub(crate) struct BuiltinPromptStatus {
+    pub(crate) id: String,
+    pub(crate) filename: String,
+    pub(crate) title: String,
+    pub(crate) subtitle: String,
+    pub(crate) badge: String,
+    pub(crate) source_url: String,
+    pub(crate) cached: bool,
+    pub(crate) updated: bool,
+    pub(crate) content_source: String,
+    pub(crate) sync_issue: Option<String>,
+    pub(crate) checked_at: Option<String>,
+    pub(crate) message: String,
+    pub(crate) customized: bool,
+}
+
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub(crate) struct BuiltinPromptDetail {
+    pub(crate) id: String,
+    pub(crate) filename: String,
+    pub(crate) title: String,
+    pub(crate) content: String,
+    pub(crate) customized: bool,
+}
+
+#[derive(Debug, Clone, Copy)]
+pub(crate) struct BundledPromptMeta {
+    pub(super) id: &'static str,
+    pub(super) filename: &'static str,
+    pub(super) title: &'static str,
+    pub(super) subtitle: &'static str,
+    pub(super) badge: &'static str,
+    pub(super) content: &'static str,
+}
+
+#[derive(Debug, Clone)]
+pub(crate) struct CachedBuiltinPrompt {
+    pub(crate) id: String,
+    pub(crate) filename: String,
+    pub(crate) source_url: String,
+    pub(crate) content: String,
+    pub(crate) checked_at: String,
+}
+
+#[derive(Debug, Deserialize)]
+pub(crate) struct GithubContentEntry {
+    pub(crate) name: String,
+    #[serde(rename = "type")]
+    pub(crate) kind: String,
+    pub(crate) download_url: Option<String>,
+}

apps/desktop/src-tauri/src/providers/ccswitch.rs

@@ -0,0 +1,704 @@
+use super::{
+    consolidate_legacy_provider_duplicates_on_connection, custom_provider_id,
+    experimental_bearer_token_from_doc, list_saved_providers_on_connection,
+    normalize_saved_provider, open_store, strip_provider_bearer_tokens,
+    upsert_ccswitch_provider_on_connection, ProviderUpsertKind, SavedProvider,
+};
+use crate::ccswitch::{ccswitch_db_candidates, default_ccswitch_db_path};
+use crate::error::{CodexxError, Result};
+use crate::sqlite_utils::table_column_set;
+use crate::string_value;
+use crate::toml_utils::ensure_table;
+use rusqlite::{Connection, OpenFlags, TransactionBehavior};
+use serde::Serialize;
+use serde_json::Value;
+use std::collections::HashMap;
+use std::path::PathBuf;
+use toml_edit::{value, DocumentMut, Item, Table};
+
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub(crate) struct ImportResult {
+    imported: usize,
+    added: usize,
+    updated: usize,
+    merged: usize,
+    skipped: usize,
+    warnings: Vec<String>,
+    providers: Vec<SavedProvider>,
+}
+
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub(crate) struct OfficialAuthCandidate {
+    auth_json: String,
+    config_text: Option<String>,
+    model: Option<String>,
+    source: String,
+}
+
+#[derive(Debug, Clone)]
+pub(crate) struct CcSwitchCodexRow {
+    pub(crate) id: String,
+    pub(crate) name: String,
+    pub(crate) settings_config: String,
+    pub(crate) category: Option<String>,
+}
+
+pub(crate) fn is_official_ccswitch_row(row: &CcSwitchCodexRow) -> bool {
+    row.id.trim().eq_ignore_ascii_case("codex-official")
+        || row
+            .category
+            .as_deref()
+            .is_some_and(|value| value.trim().eq_ignore_ascii_case("official"))
+}
+
+pub(crate) fn read_ccswitch_codex_rows(conn: &Connection) -> Result<Vec<CcSwitchCodexRow>> {
+    let provider_columns = table_column_set(conn, "providers")?;
+    let category_column = if provider_columns.contains("category") {
+        "category"
+    } else {
+        "NULL"
+    };
+    let provider_query = format!(
+        "SELECT id, name, settings_config, {category_column} FROM providers
+         WHERE app_type = 'codex' ORDER BY sort_index ASC, created_at ASC"
+    );
+    let mut stmt = conn
+        .prepare(&provider_query)
+        .map_err(|e| CodexxError::Database(e.to_string()))?;
+    let rows = stmt
+        .query_map([], |row| {
+            Ok(CcSwitchCodexRow {
+                id: row.get::<_, String>(0)?,
+                name: row.get::<_, String>(1)?,
+                settings_config: row.get::<_, String>(2)?,
+                category: row.get::<_, Option<String>>(3)?,
+            })
+        })
+        .map_err(|e| CodexxError::Database(e.to_string()))?;
+
+    let mut result = Vec::new();
+    for row in rows {
+        result.push(row.map_err(|e| CodexxError::Database(e.to_string()))?);
+    }
+    Ok(result)
+}
+
+#[derive(Debug, Clone)]
+pub(crate) struct CcSwitchCodexSection {
+    pub(crate) id: String,
+    pub(crate) name: Option<String>,
+    pub(crate) base_url: String,
+    pub(crate) model: Option<String>,
+    pub(crate) wire_api: String,
+    pub(crate) requires_openai_auth: bool,
+    pub(crate) experimental_bearer_token: Option<String>,
+    pub(crate) provider_table: Table,
+}
+
+fn table_string(table: &Table, key: &str) -> Option<String> {
+    table
+        .get(key)
+        .and_then(|item| item.as_str())
+        .map(str::trim)
+        .filter(|s| !s.is_empty())
+        .map(ToString::to_string)
+}
+
+fn ccswitch_auth_api_key(settings: &Value) -> Option<String> {
+    settings
+        .get("auth")
+        .and_then(|v| v.get("OPENAI_API_KEY"))
+        .and_then(Value::as_str)
+        .map(str::trim)
+        .filter(|s| !s.is_empty())
+        .map(ToString::to_string)
+}
+
+pub(super) fn codex_section_from_table(
+    id: &str,
+    table: &Table,
+    model: Option<String>,
+) -> Option<CcSwitchCodexSection> {
+    let base_url = table_string(table, "base_url")?
+        .trim_end_matches('/')
+        .to_string();
+    if base_url.is_empty() {
+        return None;
+    }
+    Some(CcSwitchCodexSection {
+        id: id.to_string(),
+        name: table_string(table, "name"),
+        base_url,
+        model,
+        wire_api: table_string(table, "wire_api").unwrap_or_else(|| "responses".to_string()),
+        requires_openai_auth: table
+            .get("requires_openai_auth")
+            .and_then(|item| item.as_bool())
+            .unwrap_or(false),
+        experimental_bearer_token: table_string(table, "experimental_bearer_token"),
+        provider_table: table.clone(),
+    })
+}
+
+pub(crate) fn codex_sections_from_config(config_text: &str) -> Vec<CcSwitchCodexSection> {
+    let Ok(doc) = config_text.parse::<DocumentMut>() else {
+        return Vec::new();
+    };
+    let model = string_value(&doc, "model");
+    let Some(providers) = doc.get("model_providers").and_then(|item| item.as_table()) else {
+        return Vec::new();
+    };
+    providers
+        .iter()
+        .filter_map(|(id, item)| {
+            item.as_table()
+                .and_then(|table| codex_section_from_table(id, table, model.clone()))
+        })
+        .collect()
+}
+
+fn select_ccswitch_section_for_row(
+    row: &CcSwitchCodexRow,
+    settings: &Value,
+    global_sections: &HashMap<String, CcSwitchCodexSection>,
+) -> Option<CcSwitchCodexSection> {
+    let provider_id = custom_provider_id(&row.id);
+    let config_text = settings.get("config").and_then(Value::as_str).unwrap_or("");
+    let doc = config_text.parse::<DocumentMut>().ok();
+
+    if let Some(doc) = doc.as_ref() {
+        let model = string_value(doc, "model");
+        let active_provider = string_value(doc, "model_provider");
+        let providers = doc.get("model_providers").and_then(|item| item.as_table());
+
+        if let Some(providers) = providers {
+            for exact_id in [provider_id.as_str(), row.id.trim()] {
+                if let Some(section) = providers
+                    .get(exact_id)
+                    .and_then(|item| item.as_table())
+                    .and_then(|table| codex_section_from_table(exact_id, table, model.clone()))
+                {
+                    return Some(section);
+                }
+            }
+
+            if active_provider.as_deref() == Some(row.id.trim())
+                || active_provider.as_deref() == Some(provider_id.as_str())
+            {
+                if let Some(active) = active_provider.as_deref() {
+                    if let Some(section) = providers
+                        .get(active)
+                        .and_then(|item| item.as_table())
+                        .and_then(|table| codex_section_from_table(active, table, model.clone()))
+                    {
+                        return Some(section);
+                    }
+                }
+            }
+
+            // Legacy cc-switch templates store each third-party provider under
+            // `[model_providers.custom]` in that row's own complete config.
+            if active_provider
+                .as_deref()
+                .is_none_or(|active| active == "custom")
+            {
+                if let Some(section) = providers
+                    .get("custom")
+                    .and_then(|item| item.as_table())
+                    .and_then(|table| codex_section_from_table("custom", table, model.clone()))
+                {
+                    return Some(section);
+                }
+            }
+        }
+    }
+
+    for exact_id in [provider_id.as_str(), row.id.trim()] {
+        if let Some(section) = global_sections.get(exact_id) {
+            return Some(section.clone());
+        }
+    }
+
+    let doc = doc?;
+    let active_provider = string_value(&doc, "model_provider");
+    doc.get("base_url")
+        .and_then(|item| item.as_str())
+        .map(str::trim)
+        .filter(|s| !s.is_empty())
+        .map(|base_url| {
+            let base_url = base_url.trim_end_matches('/').to_string();
+            let token = experimental_bearer_token_from_doc(&doc, active_provider.as_deref());
+            let mut provider_table = Table::new();
+            provider_table["base_url"] = value(base_url.clone());
+            provider_table["wire_api"] = value("responses");
+            provider_table["requires_openai_auth"] = value(false);
+            if let Some(token) = token.as_deref() {
+                provider_table["experimental_bearer_token"] = value(token);
+            }
+            CcSwitchCodexSection {
+                id: provider_id,
+                name: None,
+                base_url,
+                model: string_value(&doc, "model"),
+                wire_api: "responses".to_string(),
+                requires_openai_auth: false,
+                experimental_bearer_token: token,
+                provider_table,
+            }
+        })
+}
+
+fn ccswitch_provider_template(
+    settings: &Value,
+    section: &CcSwitchCodexSection,
+    provider_name: &str,
+    model: &str,
+) -> Option<String> {
+    let config_text = settings.get("config").and_then(Value::as_str).unwrap_or("");
+    let mut doc = if config_text.trim().is_empty() {
+        DocumentMut::new()
+    } else {
+        config_text.parse::<DocumentMut>().ok()?
+    };
+    let provider_id = section.id.trim();
+    if provider_id.is_empty() {
+        return None;
+    }
+
+    if string_value(&doc, "model_provider").as_deref() != Some(provider_id) {
+        doc["model_provider"] = value(provider_id);
+    }
+    if string_value(&doc, "model").as_deref() != Some(model) {
+        doc["model"] = value(model);
+    }
+    let providers = ensure_table(doc.as_table_mut(), "model_providers").ok()?;
+    if providers
+        .get(provider_id)
+        .and_then(|item| item.as_table())
+        .is_none()
+    {
+        let mut table = section.provider_table.clone();
+        if table_string(&table, "name").is_none() && !provider_name.trim().is_empty() {
+            table["name"] = value(provider_name.trim());
+        }
+        providers.insert(provider_id, Item::Table(table));
+    }
+    strip_provider_bearer_tokens(&mut doc);
+    Some(doc.to_string().trim_end().to_string())
+}
+
+pub(crate) fn build_ccswitch_codex_provider(
+    row: &CcSwitchCodexRow,
+    global_sections: &HashMap<String, CcSwitchCodexSection>,
+) -> Option<SavedProvider> {
+    let settings: Value = serde_json::from_str(&row.settings_config).ok()?;
+    let section = select_ccswitch_section_for_row(row, &settings, global_sections)?;
+    let api_key = ccswitch_auth_api_key(&settings).or(section.experimental_bearer_token.clone());
+    let provider_name = section
+        .name
+        .clone()
+        .or_else(|| {
+            let name = row.name.trim();
+            (!name.is_empty()).then(|| name.to_string())
+        })
+        .unwrap_or_else(|| row.id.clone());
+    let model = section.model.clone()?;
+    let toml_config = ccswitch_provider_template(&settings, &section, &provider_name, &model)?;
+    Some(SavedProvider {
+        id: custom_provider_id(&row.id),
+        provider_name,
+        base_url: section.base_url,
+        model,
+        api_key,
+        toml_config: Some(toml_config),
+        wire_api: section.wire_api,
+        requires_openai_auth: section.requires_openai_auth,
+        model_mappings: Vec::new(),
+    })
+}
+
+pub(crate) fn import_ccswitch_codex_providers_inner(path: Option<String>) -> Result<ImportResult> {
+    let db = path
+        .map(|s| s.trim().to_string())
+        .filter(|s| !s.is_empty())
+        .map(PathBuf::from)
+        .unwrap_or(default_ccswitch_db_path()?);
+
+    if !db.exists() {
+        let candidates = ccswitch_db_candidates()?
+            .into_iter()
+            .map(|p| p.display().to_string())
+            .collect::<Vec<_>>()
+            .join("\n- ");
+        return Err(CodexxError::Config(format!(
+            "cc-switch 数据库不存在: {}\n已检查候选路径:\n- {}",
+            db.display(),
+            candidates
+        )));
+    }
+
+    let conn = Connection::open_with_flags(
+        &db,
+        OpenFlags::SQLITE_OPEN_READ_ONLY | OpenFlags::SQLITE_OPEN_NO_MUTEX,
+    )
+    .map_err(|e| {
+        CodexxError::Database(format!("打开 cc-switch 数据库失败 {}: {e}", db.display()))
+    })?;
+
+    let rows_vec = read_ccswitch_codex_rows(&conn)?;
+
+    let mut global_sections: HashMap<String, CcSwitchCodexSection> = HashMap::new();
+    for row in &rows_vec {
+        if is_official_ccswitch_row(row) {
+            continue;
+        }
+        let Ok(settings) = serde_json::from_str::<Value>(&row.settings_config) else {
+            continue;
+        };
+        let Some(config_text) = settings.get("config").and_then(Value::as_str) else {
+            continue;
+        };
+        for section in codex_sections_from_config(config_text) {
+            if !global_sections.contains_key(&section.id) {
+                global_sections.insert(section.id.clone(), section);
+            }
+        }
+    }
+
+    let mut imported = 0usize;
+    let mut added = 0usize;
+    let mut updated = 0usize;
+    let mut merged = 0usize;
+    let mut skipped = 0usize;
+    let mut warnings = Vec::new();
+    let mut local_conn = open_store()?;
+    let transaction = local_conn
+        .transaction_with_behavior(TransactionBehavior::Immediate)
+        .map_err(|e| CodexxError::Database(e.to_string()))?;
+    merged += consolidate_legacy_provider_duplicates_on_connection(&transaction)?;
+
+    for row in rows_vec {
+        if is_official_ccswitch_row(&row) {
+            skipped += 1;
+            warnings.push(format!(
+                "跳过 {} ({})：官方认证不作为第三方供应商导入",
+                row.name, row.id
+            ));
+            continue;
+        }
+        match build_ccswitch_codex_provider(&row, &global_sections) {
+            Some(provider) => {
+                let provider = normalize_saved_provider(provider)?;
+                let result =
+                    upsert_ccswitch_provider_on_connection(&transaction, provider, row.id.trim())?;
+                match result.kind {
+                    ProviderUpsertKind::Added => added += 1,
+                    ProviderUpsertKind::Updated => updated += 1,
+                }
+                imported += 1;
+            }
+            None => {
+                skipped += 1;
+                warnings.push(format!(
+                    "跳过 {} ({})：未找到可用 config/base_url，可能是官方登录或空模板",
+                    row.name, row.id
+                ));
+            }
+        }
+    }
+    merged += consolidate_legacy_provider_duplicates_on_connection(&transaction)?;
+    transaction
+        .commit()
+        .map_err(|e| CodexxError::Database(e.to_string()))?;
+    let providers = list_saved_providers_on_connection(&local_conn)?;
+
+    Ok(ImportResult {
+        imported,
+        added,
+        updated,
+        merged,
+        skipped,
+        warnings,
+        providers,
+    })
+}
+
+pub(crate) fn read_ccswitch_official_auth_inner(
+    path: Option<String>,
+) -> Result<Option<OfficialAuthCandidate>> {
+    let db = path
+        .map(|value| value.trim().to_string())
+        .filter(|value| !value.is_empty())
+        .map(PathBuf::from)
+        .unwrap_or(default_ccswitch_db_path()?);
+
+    if !db.exists() {
+        return Ok(None);
+    }
+
+    let conn = Connection::open_with_flags(
+        &db,
+        OpenFlags::SQLITE_OPEN_READ_ONLY | OpenFlags::SQLITE_OPEN_NO_MUTEX,
+    )
+    .map_err(|e| {
+        CodexxError::Database(format!("打开 cc-switch 数据库失败 {}: {e}", db.display()))
+    })?;
+
+    let provider_columns = table_column_set(&conn, "providers")?;
+    let official_filter = if provider_columns.contains("category") {
+        "id = 'codex-official' OR category = 'official'"
+    } else {
+        // Older cc-switch databases predate the category column. The stable
+        // codex-official id is still enough to identify the official row.
+        "id = 'codex-official'"
+    };
+    let query = format!(
+        "SELECT id, name, settings_config FROM providers
+         WHERE app_type = 'codex' AND ({official_filter})
+         ORDER BY CASE WHEN id = 'codex-official' THEN 0 ELSE 1 END
+         LIMIT 1"
+    );
+    let mut stmt = conn
+        .prepare(&query)
+        .map_err(|e| CodexxError::Database(e.to_string()))?;
+
+    let mut rows = stmt
+        .query([])
+        .map_err(|e| CodexxError::Database(e.to_string()))?;
+
+    let Some(row) = rows
+        .next()
+        .map_err(|e| CodexxError::Database(e.to_string()))?
+    else {
+        return Ok(None);
+    };
+
+    let id: String = row
+        .get(0)
+        .map_err(|e| CodexxError::Database(e.to_string()))?;
+    let name: String = row
+        .get(1)
+        .map_err(|e| CodexxError::Database(e.to_string()))?;
+    let settings_config: String = row
+        .get(2)
+        .map_err(|e| CodexxError::Database(e.to_string()))?;
+    let settings: Value = serde_json::from_str(&settings_config).map_err(|e| {
+        CodexxError::Database(format!("cc-switch official settings JSON 解析失败: {e}"))
+    })?;
+
+    let auth = settings
+        .get("auth")
+        .cloned()
+        .filter(|value| value.is_object())
+        .ok_or_else(|| {
+            CodexxError::Database("cc-switch official provider 缺少 auth object".to_string())
+        })?;
+
+    let config_text = settings
+        .get("config")
+        .and_then(Value::as_str)
+        .map(ToString::to_string);
+    let model = config_text
+        .as_deref()
+        .and_then(|text| text.parse::<DocumentMut>().ok())
+        .and_then(|doc| string_value(&doc, "model"));
+
+    let auth_json = serde_json::to_string_pretty(&auth)
+        .map_err(|e| CodexxError::Database(format!("官方 auth JSON 格式化失败: {e}")))?;
+
+    Ok(Some(OfficialAuthCandidate {
+        auth_json,
+        config_text,
+        model,
+        source: format!("cc-switch:{name}:{id}"),
+    }))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde_json::json;
+
+    #[test]
+    fn provider_import_round_trips_complete_config_without_bearer_tokens() {
+        let settings_config = json!({
+            "auth": {"OPENAI_API_KEY": "sk-from-auth"},
+            "config": r#"# keep-imported-comment
+model_provider = "custom"
+model = "gpt-5.6-sol"
+model_reasoning_effort = "xhigh"
+service_tier = "priority"
+experimental_bearer_token = "sk-top-level"
+notify = ["C:\\Users\\Thy\\codex-computer-use.exe", "turn-ended"]
+
+[model_providers.custom]
+name = "Sky2api"
+base_url = "https://proxy.example.com/v1/"
+wire_api = "responses"
+requires_openai_auth = false
+experimental_bearer_token = "sk-from-config"
+request_max_retries = 7
+
+[model_providers.other]
+name = "Other provider"
+base_url = "https://other.example.com/v1"
+experimental_bearer_token = "sk-other"
+
+[projects."/work/project"]
+trust_level = "trusted"
+
+[desktop]
+followUpQueueMode = "queue"
+localeOverride = "zh-CN"
+
+[windows]
+sandbox = "elevated"
+shell_path = 'D:\Program Files\PowerShell\7\pwsh.exe'
+
+[plugins."browser@openai-bundled"]
+enabled = true
+
+[features]
+js_repl = false
+
+[shell_environment_policy.set]
+CODEX_HOME = 'C:\Users\Thy\.codex'
+
+[mcp_servers.docs]
+command = "docs-server"
+"#,
+        })
+        .to_string();
+        let row = CcSwitchCodexRow {
+            id: "magicai-123".to_string(),
+            name: "  Sky2_free  ".to_string(),
+            settings_config,
+            category: None,
+        };
+
+        let provider =
+            build_ccswitch_codex_provider(&row, &HashMap::new()).expect("build cc-switch provider");
+        assert_eq!(provider.id, "magicai-123");
+        assert_eq!(provider.provider_name, "Sky2api");
+        assert_eq!(provider.base_url, "https://proxy.example.com/v1");
+        assert_eq!(provider.model, "gpt-5.6-sol");
+        assert_eq!(provider.api_key.as_deref(), Some("sk-from-auth"));
+        assert_eq!(provider.wire_api, "responses");
+        assert!(!provider.requires_openai_auth);
+
+        let text = provider.toml_config.expect("complete provider TOML");
+        let doc = text.parse::<DocumentMut>().expect("parse provider TOML");
+        assert!(text.contains("# keep-imported-comment"));
+        assert_eq!(doc["model_provider"].as_str(), Some("custom"));
+        assert_eq!(doc["model_reasoning_effort"].as_str(), Some("xhigh"));
+        assert_eq!(doc["service_tier"].as_str(), Some("priority"));
+        assert_eq!(doc["notify"].as_array().map(|values| values.len()), Some(2));
+        assert_eq!(
+            doc["model_providers"]["custom"]["name"].as_str(),
+            Some("Sky2api")
+        );
+        assert_eq!(
+            doc["model_providers"]["custom"]["base_url"].as_str(),
+            Some("https://proxy.example.com/v1/")
+        );
+        assert_eq!(
+            doc["model_providers"]["custom"]["request_max_retries"].as_integer(),
+            Some(7)
+        );
+        assert_eq!(
+            doc["model_providers"]["other"]["base_url"].as_str(),
+            Some("https://other.example.com/v1")
+        );
+        assert_eq!(
+            doc["projects"]["/work/project"]["trust_level"].as_str(),
+            Some("trusted")
+        );
+        assert_eq!(doc["desktop"]["followUpQueueMode"].as_str(), Some("queue"));
+        assert_eq!(doc["desktop"]["localeOverride"].as_str(), Some("zh-CN"));
+        assert_eq!(doc["windows"]["sandbox"].as_str(), Some("elevated"));
+        assert_eq!(
+            doc["windows"]["shell_path"].as_str(),
+            Some(r"D:\Program Files\PowerShell\7\pwsh.exe")
+        );
+        assert_eq!(
+            doc["plugins"]["browser@openai-bundled"]["enabled"].as_bool(),
+            Some(true)
+        );
+        assert_eq!(doc["features"]["js_repl"].as_bool(), Some(false));
+        assert_eq!(
+            doc["shell_environment_policy"]["set"]["CODEX_HOME"].as_str(),
+            Some(r"C:\Users\Thy\.codex")
+        );
+        assert_eq!(
+            doc["mcp_servers"]["docs"]["command"].as_str(),
+            Some("docs-server")
+        );
+        assert!(doc.get("experimental_bearer_token").is_none());
+        assert!(doc["model_providers"]
+            .as_table()
+            .expect("model providers table")
+            .iter()
+            .all(|(_, item)| item
+                .as_table()
+                .is_none_or(|table| table.get("experimental_bearer_token").is_none())));
+        assert!(!text.contains("sk-from-auth"));
+        assert!(!text.contains("experimental_bearer_token"));
+    }
+
+    #[test]
+    fn complete_row_without_a_model_is_not_silently_downgraded() {
+        let row = CcSwitchCodexRow {
+            id: "missing-model".to_string(),
+            name: "Database label".to_string(),
+            settings_config: json!({
+                "auth": {"OPENAI_API_KEY": "sk-test"},
+                "config": r#"model_provider = "custom"
+
+[model_providers.custom]
+name = "TOML label"
+base_url = "https://proxy.example.com/v1"
+wire_api = "responses"
+requires_openai_auth = false
+"#,
+            })
+            .to_string(),
+            category: None,
+        };
+
+        assert!(build_ccswitch_codex_provider(&row, &HashMap::new()).is_none());
+    }
+
+    #[test]
+    fn malformed_row_config_does_not_create_a_sparse_provider() {
+        let section = codex_sections_from_config(
+            r#"model_provider = "broken-row"
+model = "gpt-5.5"
+
+[model_providers.broken-row]
+name = "Recovered only from another row"
+base_url = "https://proxy.example.com/v1"
+wire_api = "responses"
+requires_openai_auth = false
+"#,
+        )
+        .into_iter()
+        .next()
+        .expect("global provider section");
+        let mut global_sections = HashMap::new();
+        global_sections.insert(section.id.clone(), section);
+        let row = CcSwitchCodexRow {
+            id: "broken-row".to_string(),
+            name: "Broken row".to_string(),
+            settings_config: json!({
+                "auth": {"OPENAI_API_KEY": "sk-must-not-import"},
+                "config": "model = ["
+            })
+            .to_string(),
+            category: None,
+        };
+
+        assert!(build_ccswitch_codex_provider(&row, &global_sections).is_none());
+    }
+}

apps/desktop/src-tauri/src/providers/connection.rs

@@ -0,0 +1,437 @@
+use crate::error::{CodexxError, Result};
+#[cfg(test)]
+use crate::remote::ensure_crypto_provider;
+use crate::remote::{remote_client, remote_request_error, RemoteSource};
+use reqwest::blocking::Client;
+use serde::{Deserialize, Serialize};
+use std::cmp::Ordering;
+use std::collections::HashMap;
+use std::time::Instant;
+
+const MODELS_SOURCE_KEY: &str = "获取模型列表";
+
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub(crate) struct ProviderConnectionResult {
+    pub(crate) ok: bool,
+    pub(crate) status: Option<u16>,
+    pub(crate) message: String,
+    pub(crate) duration_ms: u128,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub(crate) struct ProviderModel {
+    pub(crate) id: String,
+    pub(crate) created: Option<i64>,
+}
+
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub(crate) struct ProviderModelsResult {
+    pub(crate) models: Vec<ProviderModel>,
+    pub(crate) status: u16,
+    pub(crate) duration_ms: u128,
+}
+
+#[derive(Debug, Deserialize)]
+struct ModelsPayload {
+    data: Vec<ModelPayload>,
+}
+
+#[derive(Debug, Deserialize)]
+struct ModelPayload {
+    id: String,
+    #[serde(default)]
+    created: Option<serde_json::Value>,
+}
+
+enum ProviderModelsAttempt {
+    Success(ProviderModelsResult),
+    HttpError { status: u16, duration_ms: u128 },
+}
+
+fn provider_models_url(base_url: &str) -> Result<reqwest::Url> {
+    let trimmed = base_url.trim();
+    if trimmed.is_empty() {
+        return Err(CodexxError::Config("base_url 不能为空".to_string()));
+    }
+
+    let mut url = reqwest::Url::parse(trimmed)
+        .map_err(|_| CodexxError::Config("base_url 格式不正确".to_string()))?;
+    if !matches!(url.scheme(), "http" | "https") || url.host_str().is_none() {
+        return Err(CodexxError::Config(
+            "base_url 必须是有效的 http:// 或 https:// 地址".to_string(),
+        ));
+    }
+
+    let segments = url
+        .path_segments()
+        .ok_or_else(|| CodexxError::Config("base_url 格式不正确".to_string()))?
+        .filter(|segment| !segment.is_empty())
+        .collect::<Vec<_>>();
+    let already_models = segments.len() >= 2
+        && segments[segments.len() - 2].eq_ignore_ascii_case("v1")
+        && segments[segments.len() - 1].eq_ignore_ascii_case("models");
+    let already_v1 = segments
+        .last()
+        .is_some_and(|segment| segment.eq_ignore_ascii_case("v1"));
+
+    {
+        let mut path = url
+            .path_segments_mut()
+            .map_err(|_| CodexxError::Config("base_url 格式不正确".to_string()))?;
+        path.pop_if_empty();
+        if !already_models {
+            if !already_v1 {
+                path.push("v1");
+            }
+            path.push("models");
+        }
+    }
+    url.set_fragment(None);
+    Ok(url)
+}
+
+fn parse_created(value: Option<serde_json::Value>) -> Option<i64> {
+    value.and_then(|value| {
+        value
+            .as_i64()
+            .or_else(|| value.as_str().and_then(|text| text.parse::<i64>().ok()))
+    })
+}
+
+fn compare_digit_runs(left: &[u8], right: &[u8]) -> Ordering {
+    let left_significant = left
+        .iter()
+        .position(|byte| *byte != b'0')
+        .map_or(&left[left.len()..], |index| &left[index..]);
+    let right_significant = right
+        .iter()
+        .position(|byte| *byte != b'0')
+        .map_or(&right[right.len()..], |index| &right[index..]);
+
+    left_significant
+        .len()
+        .cmp(&right_significant.len())
+        .then_with(|| left_significant.cmp(right_significant))
+}
+
+fn natural_model_id_cmp(left: &str, right: &str) -> Ordering {
+    let left = left.as_bytes();
+    let right = right.as_bytes();
+    let (mut left_index, mut right_index) = (0, 0);
+
+    while left_index < left.len() && right_index < right.len() {
+        if left[left_index].is_ascii_digit() && right[right_index].is_ascii_digit() {
+            let left_end = left[left_index..]
+                .iter()
+                .position(|byte| !byte.is_ascii_digit())
+                .map_or(left.len(), |offset| left_index + offset);
+            let right_end = right[right_index..]
+                .iter()
+                .position(|byte| !byte.is_ascii_digit())
+                .map_or(right.len(), |offset| right_index + offset);
+            let order =
+                compare_digit_runs(&left[left_index..left_end], &right[right_index..right_end]);
+            if order != Ordering::Equal {
+                return order;
+            }
+            left_index = left_end;
+            right_index = right_end;
+            continue;
+        }
+
+        let order = left[left_index]
+            .to_ascii_lowercase()
+            .cmp(&right[right_index].to_ascii_lowercase());
+        if order != Ordering::Equal {
+            return order;
+        }
+        left_index += 1;
+        right_index += 1;
+    }
+
+    left.len().cmp(&right.len()).then_with(|| left.cmp(right))
+}
+
+fn parse_models(body: &str) -> Result<Vec<ProviderModel>> {
+    let payload: ModelsPayload = serde_json::from_str(body)
+        .map_err(|_| CodexxError::Config("模型列表返回格式不正确".to_string()))?;
+    let mut models = Vec::<ProviderModel>::new();
+    let mut indexes = HashMap::<String, usize>::new();
+
+    for model in payload.data {
+        let id = model.id.trim();
+        if id.is_empty() {
+            continue;
+        }
+        let created = parse_created(model.created);
+        if let Some(index) = indexes.get(id).copied() {
+            if created > models[index].created {
+                models[index].created = created;
+            }
+            continue;
+        }
+        indexes.insert(id.to_string(), models.len());
+        models.push(ProviderModel {
+            id: id.to_string(),
+            created,
+        });
+    }
+
+    models.sort_by(|left, right| {
+        right
+            .created
+            .cmp(&left.created)
+            .then_with(|| natural_model_id_cmp(&right.id, &left.id))
+    });
+
+    Ok(models)
+}
+
+fn request_provider_models_with_client(
+    client: &Client,
+    base_url: &str,
+    api_key: Option<&str>,
+) -> Result<ProviderModelsAttempt> {
+    let url = provider_models_url(base_url)?;
+    let source = RemoteSource::new(MODELS_SOURCE_KEY, url.as_str(), Some("application/json"));
+    let mut request = client
+        .get(url.as_str())
+        .header(reqwest::header::ACCEPT, "application/json");
+    if let Some(api_key) = api_key.map(str::trim).filter(|key| !key.is_empty()) {
+        request = request.bearer_auth(api_key);
+    }
+
+    let started = Instant::now();
+    let response = request
+        .send()
+        .map_err(|error| remote_request_error(&source, &error))?;
+    let duration_ms = started.elapsed().as_millis();
+    let status = response.status().as_u16();
+    if !response.status().is_success() {
+        return Ok(ProviderModelsAttempt::HttpError {
+            status,
+            duration_ms,
+        });
+    }
+
+    let body = response
+        .text()
+        .map_err(|_| CodexxError::Config("模型列表读取失败".to_string()))?;
+    Ok(ProviderModelsAttempt::Success(ProviderModelsResult {
+        models: parse_models(&body)?,
+        status,
+        duration_ms,
+    }))
+}
+
+fn request_provider_models(base_url: &str, api_key: Option<&str>) -> Result<ProviderModelsAttempt> {
+    let client = remote_client()?;
+    request_provider_models_with_client(&client, base_url, api_key)
+}
+
+pub(crate) fn provider_status_result(status: u16, duration_ms: u128) -> ProviderConnectionResult {
+    ProviderConnectionResult {
+        ok: (200..300).contains(&status),
+        status: Some(status),
+        message: if (200..300).contains(&status) {
+            format!("{duration_ms} ms")
+        } else if status == 401 || status == 403 {
+            format!("HTTP {status} · {duration_ms} ms（认证失败或无权限）")
+        } else {
+            format!("HTTP {status} · {duration_ms} ms")
+        },
+        duration_ms,
+    }
+}
+
+pub(crate) fn test_provider_connection_inner(
+    base_url: String,
+    api_key: Option<String>,
+) -> Result<ProviderConnectionResult> {
+    match request_provider_models(&base_url, api_key.as_deref())? {
+        ProviderModelsAttempt::Success(result) => {
+            Ok(provider_status_result(result.status, result.duration_ms))
+        }
+        ProviderModelsAttempt::HttpError {
+            status,
+            duration_ms,
+        } => Ok(provider_status_result(status, duration_ms)),
+    }
+}
+
+pub(crate) fn fetch_provider_models_inner(
+    base_url: String,
+    api_key: Option<String>,
+) -> Result<ProviderModelsResult> {
+    match request_provider_models(&base_url, api_key.as_deref())? {
+        ProviderModelsAttempt::Success(result) => Ok(result),
+        ProviderModelsAttempt::HttpError { status, .. } => {
+            Err(CodexxError::Config(if matches!(status, 401 | 403) {
+                format!("获取模型列表失败（HTTP {status}，请检查 API Key）")
+            } else {
+                format!("获取模型列表失败（HTTP {status}）")
+            }))
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::io::{Read, Write};
+    use std::net::TcpListener;
+    use std::thread;
+    use std::time::Duration;
+
+    fn direct_client() -> Client {
+        ensure_crypto_provider();
+        Client::builder()
+            .no_proxy()
+            .timeout(Duration::from_secs(2))
+            .build()
+            .expect("build test client")
+    }
+
+    fn serve_once(status: u16, body: &'static str) -> (String, thread::JoinHandle<String>) {
+        let listener = TcpListener::bind("127.0.0.1:0").expect("bind mock server");
+        let base_url = format!("http://{}", listener.local_addr().unwrap());
+        let server = thread::spawn(move || {
+            let (mut stream, _) = listener.accept().expect("accept request");
+            stream
+                .set_read_timeout(Some(Duration::from_secs(2)))
+                .expect("set read timeout");
+            let mut bytes = [0_u8; 8192];
+            let read = stream.read(&mut bytes).expect("read request");
+            let status_text = if status == 200 { "OK" } else { "Error" };
+            let response = format!(
+                "HTTP/1.1 {status} {status_text}\r\nContent-Type: application/json\r\nContent-Length: {}\r\nConnection: close\r\n\r\n{body}",
+                body.len()
+            );
+            stream
+                .write_all(response.as_bytes())
+                .expect("write response");
+            String::from_utf8_lossy(&bytes[..read]).into_owned()
+        });
+        (base_url, server)
+    }
+
+    #[test]
+    fn models_url_adds_exactly_one_v1_segment() {
+        for (base, expected) in [
+            ("https://example.com", "https://example.com/v1/models"),
+            ("https://example.com/v1", "https://example.com/v1/models"),
+            ("https://example.com/v1/", "https://example.com/v1/models"),
+            (
+                "https://example.com/openai",
+                "https://example.com/openai/v1/models",
+            ),
+        ] {
+            assert_eq!(provider_models_url(base).unwrap().as_str(), expected);
+        }
+    }
+
+    #[test]
+    fn fetches_models_with_bearer_auth_and_deduplicates_ids() {
+        let body = r#"{"data":[{"id":" gpt-5.6-sol ","created":20},{"id":"gpt-5.5","created":"10"},{"id":"gpt-5.6-sol","created":30},{"id":"  "}]}"#;
+        let (base_url, server) = serve_once(200, body);
+        let attempt = request_provider_models_with_client(
+            &direct_client(),
+            &base_url,
+            Some("sk-private-test"),
+        )
+        .expect("request succeeds");
+        let ProviderModelsAttempt::Success(result) = attempt else {
+            panic!("expected successful models response");
+        };
+
+        assert_eq!(
+            result.models,
+            vec![
+                ProviderModel {
+                    id: "gpt-5.6-sol".to_string(),
+                    created: Some(30),
+                },
+                ProviderModel {
+                    id: "gpt-5.5".to_string(),
+                    created: Some(10),
+                },
+            ]
+        );
+        let request = server.join().expect("join mock server");
+        assert!(request.starts_with("GET /v1/models HTTP/1.1"));
+        assert!(request
+            .to_ascii_lowercase()
+            .contains("authorization: bearer sk-private-test"));
+    }
+
+    #[test]
+    fn sorts_by_created_then_natural_model_version_descending() {
+        let models = parse_models(
+            r#"{"data":[{"id":"gpt-5.5","created":20},{"id":"gpt-5.6-sol","created":20},{"id":"gpt-5.9"},{"id":"gpt-5.10"},{"id":"older-by-name","created":30}]}"#,
+        )
+        .expect("parse models");
+
+        assert_eq!(
+            models
+                .iter()
+                .map(|model| model.id.as_str())
+                .collect::<Vec<_>>(),
+            [
+                "older-by-name",
+                "gpt-5.6-sol",
+                "gpt-5.5",
+                "gpt-5.10",
+                "gpt-5.9",
+            ]
+        );
+    }
+
+    #[test]
+    fn http_errors_are_not_reported_as_connected_or_leaked() {
+        let private_body = r#"{"error":"secret upstream response"}"#;
+        let (base_url, server) = serve_once(403, private_body);
+        let attempt = request_provider_models_with_client(
+            &direct_client(),
+            &base_url,
+            Some("sk-private-test"),
+        )
+        .expect("HTTP status remains an inspectable result");
+        let ProviderModelsAttempt::HttpError {
+            status,
+            duration_ms,
+        } = attempt
+        else {
+            panic!("expected HTTP error");
+        };
+        let result = provider_status_result(status, duration_ms);
+
+        assert!(!result.ok);
+        assert_eq!(result.status, Some(403));
+        assert!(!result.message.contains("secret upstream response"));
+        assert!(!result.message.contains("sk-private-test"));
+        assert!(!result.message.contains(&base_url));
+        server.join().expect("join mock server");
+    }
+
+    #[test]
+    fn invalid_payload_error_does_not_include_response_body() {
+        let private_body = r#"{"private":"secret response"}"#;
+        let (base_url, server) = serve_once(200, private_body);
+        let error = request_provider_models_with_client(
+            &direct_client(),
+            &base_url,
+            Some("sk-private-test"),
+        )
+        .err()
+        .expect("invalid payload fails");
+        let message = error.to_string();
+
+        assert!(!message.contains("secret response"));
+        assert!(!message.contains("sk-private-test"));
+        assert!(!message.contains(&base_url));
+        server.join().expect("join mock server");
+    }
+}

apps/desktop/src-tauri/src/providers/mod.rs

@@ -0,0 +1,74 @@
+mod ccswitch;
+mod connection;
+mod live;
+pub(crate) mod model_catalog;
+mod official_auth;
+pub(crate) mod official_profiles;
+pub(crate) mod quota;
+mod selection;
+mod store;
+pub(crate) mod transport;
+
+use crate::error::Result;
+use rusqlite::Connection;
+
+#[cfg(test)]
+pub(crate) use ccswitch::{
+    build_ccswitch_codex_provider, codex_sections_from_config, is_official_ccswitch_row,
+    read_ccswitch_codex_rows, CcSwitchCodexRow,
+};
+pub(crate) use ccswitch::{
+    import_ccswitch_codex_providers_inner, read_ccswitch_official_auth_inner, ImportResult,
+    OfficialAuthCandidate,
+};
+#[cfg(test)]
+pub(crate) use connection::provider_status_result;
+pub(crate) use connection::{
+    fetch_provider_models_inner, test_provider_connection_inner, ProviderConnectionResult,
+    ProviderModelsResult,
+};
+pub(crate) use live::{
+    activate_saved_provider_inner, build_provider_toml_draft_inner,
+    build_provider_toml_draft_with_origin_inner, delete_saved_provider_inner,
+    get_provider_config_base_inner, save_active_provider_inner,
+    save_active_provider_with_common_config_inner, save_official_config_inner,
+    save_provider_toml_config_inner, switch_provider_inner, OfficialConfigInput, ProviderInput,
+    ProviderTomlInput,
+};
+pub(crate) use live::{detected_live_custom_provider, replacement_write_order, LiveWriteOrder};
+#[cfg(test)]
+pub(crate) use live::{
+    reset_official_provider_inner, restore_official_provider_inner,
+    save_provider_toml_config_with_pre_persist, switch_official_provider_inner,
+    switch_official_provider_with_pre_persist, switch_provider_with_pre_persist,
+};
+#[cfg(test)]
+pub(crate) use official_auth::{
+    capture_live_chatgpt_config, get_official_config_draft_inner, official_snapshot_path_for_test,
+};
+pub(crate) use official_auth::{document_is_official, official_auth_available};
+pub(crate) use selection::{
+    clear_active_provider_on_connection, clear_provider_selections_on_connection,
+    reconcile_active_provider_on_connection, remember_active_provider_on_connection,
+};
+#[cfg(test)]
+pub(crate) use store::{
+    canonical_provider_base_url, provider_by_id_on_connection, provider_identity,
+    save_manual_provider_on_connection, upsert_provider_on_connection, ProviderUpsertMode,
+};
+pub(crate) use store::{
+    consolidate_legacy_provider_duplicates_on_connection, custom_provider_id,
+    delete_provider_inner, duplicate_provider_inner, experimental_bearer_token_from_doc,
+    is_placeholder_provider, list_saved_providers_inner, list_saved_providers_on_connection,
+    matching_saved_provider_ids_for_live, matching_saved_provider_ids_for_live_on_connection,
+    normalize_saved_provider, normalize_saved_provider_for_save, provider_template_from_document,
+    reserved_codex_provider_id, rollback_provider_store_inner,
+    save_detected_provider_with_rollback_inner, save_provider_inner,
+    save_provider_with_rollback_inner, strip_provider_bearer_tokens,
+    upsert_ccswitch_provider_on_connection, DuplicateProviderResult, ProviderStoreRollback,
+    ProviderUpsertKind, SavedProvider,
+};
+
+pub(crate) fn open_store() -> Result<Connection> {
+    crate::app_db::open()
+}

apps/desktop/src-tauri/src/providers/model_catalog.rs

@@ -0,0 +1,771 @@
+//! Provider-local model menus using Codex's external ModelsResponse catalog.
+//! A display name never changes the model slug sent to the provider. Catalogs
+//! are immutable so a failed live-config transaction can keep its old pointer.
+
+use crate::error::{CodexxError, Result};
+use crate::file_io::{ensure_directory, io_err, write_private_json};
+use serde::{Deserialize, Serialize};
+use serde_json::{json, Value};
+use sha2::{Digest, Sha256};
+use std::collections::HashSet;
+use std::fs;
+use std::io::Read;
+use std::path::{Component, Path, PathBuf};
+use toml_edit::{value, DocumentMut};
+
+const MAX_MAPPINGS: usize = 64;
+const MAX_NAME_CHARS: usize = 200;
+const MAX_CONTEXT_WINDOW: i64 = 10_000_000;
+const DEFAULT_CONTEXT_WINDOW: i64 = 128_000;
+const OWNED_DIRECTORY: &str = ".codex-x";
+const CATALOG_DIRECTORY: &str = "model-catalogs";
+const CATALOG_FIELD: &str = "model_catalog_json";
+const OWNERSHIP_FIELD: &str = "_codex_x_model_catalog";
+const MAX_CATALOG_BYTES: u64 = 1024 * 1024;
+const REASONING_EFFORTS: &[&str] = &[
+    "none", "minimal", "low", "medium", "high", "xhigh", "max", "ultra",
+];
+const BASE_INSTRUCTIONS: &str = "You are a coding assistant working with the user in a shared workspace. Use the available tools to inspect and edit project files, follow the user's requirements, and verify your changes.";
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub(crate) struct ProviderModelMapping {
+    pub(crate) model: String,
+    #[serde(default)]
+    pub(crate) display_name: String,
+    #[serde(default)]
+    pub(crate) context_window: Option<i64>,
+}
+
+fn validate_name(name: &str, label: &str) -> Result<String> {
+    let name = name.trim();
+    if name.is_empty() {
+        return Err(CodexxError::Config(format!("{label}不能为空")));
+    }
+    if name.chars().count() > MAX_NAME_CHARS || name.chars().any(char::is_control) {
+        return Err(CodexxError::Config(format!(
+            "{label}最多 {MAX_NAME_CHARS} 个字符，且不能包含控制字符"
+        )));
+    }
+    Ok(name.to_owned())
+}
+
+pub(crate) fn normalize_mappings(
+    rows: &[ProviderModelMapping],
+    default_model: &str,
+) -> Result<Vec<ProviderModelMapping>> {
+    if rows.is_empty() {
+        return Ok(Vec::new());
+    }
+    if rows.len() > MAX_MAPPINGS {
+        return Err(CodexxError::Config(format!(
+            "最多添加 {MAX_MAPPINGS} 个模型"
+        )));
+    }
+    let default_model = validate_name(default_model, "默认模型 ID")?;
+    let mut seen = HashSet::new();
+    let mut normalized = Vec::new();
+    for row in rows {
+        let model = validate_name(&row.model, "模型 ID")?;
+        let display_name = if row.display_name.trim().is_empty() {
+            model.clone()
+        } else {
+            validate_name(&row.display_name, "模型显示名称")?
+        };
+        if row
+            .context_window
+            .is_some_and(|window| !(1..=MAX_CONTEXT_WINDOW).contains(&window))
+        {
+            return Err(CodexxError::Config(format!(
+                "模型上下文窗口须为 1 至 {MAX_CONTEXT_WINDOW} 之间的整数"
+            )));
+        }
+        if seen.insert(model.clone()) {
+            normalized.push(ProviderModelMapping {
+                model,
+                display_name,
+                context_window: row.context_window,
+            });
+        }
+    }
+    if !seen.contains(&default_model) {
+        if normalized.len() >= MAX_MAPPINGS {
+            return Err(CodexxError::Config(format!(
+                "模型列表需要包含默认模型，合计最多 {MAX_MAPPINGS} 个模型"
+            )));
+        }
+        normalized.insert(
+            0,
+            ProviderModelMapping {
+                display_name: default_model.clone(),
+                model: default_model,
+                context_window: None,
+            },
+        );
+    }
+    Ok(normalized)
+}
+
+fn model_entry(mapping: &ProviderModelMapping, priority: usize, default_context: i64) -> Value {
+    let context_window = mapping.context_window.unwrap_or(default_context);
+    // Schema: openai/codex rust-v0.153.4, protocol/src/openai_models.rs,
+    // ModelInfo + ModelsResponse. Keep legacy required fields for older Codex.
+    // Unlike cloning a GPT cache entry, this does not import proprietary model
+    // instructions, hosted tools, service tiers or vision. Expose the same effort
+    // menu for mapped models; the upstream API determines each effort's effect.
+    json!({
+        "slug": mapping.model,
+        "display_name": mapping.display_name,
+        "description": mapping.display_name,
+        "base_instructions": BASE_INSTRUCTIONS,
+        "default_reasoning_level": "high",
+        "supported_reasoning_levels": REASONING_EFFORTS.iter().map(|effort| json!({"effort": effort, "description": if *effort == "none" { "Disable thinking".to_owned() } else { format!("{effort} reasoning effort") }})).collect::<Vec<_>>(),
+        "shell_type": "shell_command",
+        "visibility": "list",
+        "supported_in_api": true,
+        "priority": priority,
+        "additional_speed_tiers": [],
+        "service_tiers": [],
+        "availability_nux": null,
+        "upgrade": null,
+        // Older Codex gates the entire reasoning object (including effort) here.
+        "supports_reasoning_summaries": true,
+        "supports_reasoning_summary_parameter": false,
+        "default_reasoning_summary": "none",
+        "support_verbosity": false,
+        "default_verbosity": null,
+        "apply_patch_tool_type": null,
+        "truncation_policy": { "mode": "bytes", "limit": 10000 },
+        "supports_parallel_tool_calls": false,
+        "supports_image_detail_original": false,
+        "context_window": context_window,
+        "max_context_window": context_window,
+        "effective_context_window_percent": 95,
+        "experimental_supported_tools": [],
+        "input_modalities": ["text"],
+        "supports_search_tool": false,
+        "use_responses_lite": false,
+        "prefer_websockets": false
+    })
+}
+
+fn build_catalog(mappings: &[ProviderModelMapping], doc: &DocumentMut) -> Value {
+    let default_context = doc
+        .get("model_context_window")
+        .and_then(|item| item.as_integer())
+        .filter(|window| (1..=MAX_CONTEXT_WINDOW).contains(window))
+        .unwrap_or(DEFAULT_CONTEXT_WINDOW);
+    json!({"models": mappings.iter().enumerate()
+        .map(|(priority, mapping)| model_entry(mapping, priority, default_context))
+        .collect::<Vec<_>>()})
+}
+
+fn is_link(metadata: &fs::Metadata) -> bool {
+    #[cfg(windows)]
+    {
+        use std::os::windows::fs::MetadataExt;
+        // Include junctions/reparse points, not only ordinary symlinks.
+        metadata.file_attributes() & 0x400 != 0
+    }
+    #[cfg(not(windows))]
+    {
+        metadata.file_type().is_symlink()
+    }
+}
+
+fn owned_catalog_directory(codex_dir: &Path) -> PathBuf {
+    codex_dir.join(OWNED_DIRECTORY).join(CATALOG_DIRECTORY)
+}
+
+fn catalog_filename(catalog: &Value) -> Result<String> {
+    let content = serde_json::to_vec(catalog)
+        .map_err(|_| CodexxError::Config("无法生成供应商模型目录".into()))?;
+    let mut digest = Sha256::new();
+    digest.update(b"codex-x-provider-model-catalog-v2\0");
+    digest.update(&content);
+    Ok(format!("{:x}.json", digest.finalize()))
+}
+
+fn has_verified_ownership(path: &Path, filename: &str) -> bool {
+    let Ok(file) = fs::File::open(path) else {
+        return false;
+    };
+    let Ok(metadata) = file.metadata() else {
+        return false;
+    };
+    if !metadata.is_file() || metadata.len() > MAX_CATALOG_BYTES {
+        return false;
+    }
+    let mut bytes = Vec::new();
+    if file
+        .take(MAX_CATALOG_BYTES + 1)
+        .read_to_end(&mut bytes)
+        .is_err()
+        || bytes.len() as u64 > MAX_CATALOG_BYTES
+    {
+        return false;
+    }
+    let Ok(catalog) = serde_json::from_slice::<Value>(&bytes) else {
+        return false;
+    };
+    let Some(owner) = catalog.get(OWNERSHIP_FIELD) else {
+        return false;
+    };
+    let Some(provider_hash) = owner.get("provider_hash").and_then(Value::as_str) else {
+        return false;
+    };
+    owner.get("source").and_then(Value::as_str) == Some("codex-x")
+        && owner.get("format").and_then(Value::as_u64) == Some(1)
+        && provider_hash.len() == 64
+        && provider_hash.bytes().all(|byte| byte.is_ascii_hexdigit())
+        && catalog
+            .get("models")
+            .and_then(Value::as_array)
+            .is_some_and(|models| !models.is_empty() && models.len() <= MAX_MAPPINGS)
+        && catalog_filename(&catalog).is_ok_and(|expected| expected == filename)
+}
+
+fn prepare_owned_directory(codex_dir: &Path) -> Result<PathBuf> {
+    ensure_directory(codex_dir)?;
+    // The user's CODEX_HOME may intentionally be a symlink/junction. Resolve
+    // that once, then reject links inside our own generated-file directory.
+    let mut directory = codex_dir
+        .canonicalize()
+        .map_err(|error| io_err(codex_dir, error))?;
+    for component in [OWNED_DIRECTORY, CATALOG_DIRECTORY] {
+        directory.push(component);
+        match fs::symlink_metadata(&directory) {
+            Ok(metadata) if is_link(&metadata) || !metadata.is_dir() => {
+                return Err(CodexxError::Config(
+                    "模型目录被文件或链接占用，请检查 Codex-X 模型目录".into(),
+                ));
+            }
+            Ok(_) => {}
+            Err(error) if error.kind() == std::io::ErrorKind::NotFound => {
+                ensure_directory(&directory)?;
+            }
+            Err(error) => return Err(io_err(&directory, error)),
+        }
+        let metadata =
+            fs::symlink_metadata(&directory).map_err(|error| io_err(&directory, error))?;
+        if is_link(&metadata) || !metadata.is_dir() {
+            return Err(CodexxError::Config(
+                "模型目录在创建时发生变化，请重试".into(),
+            ));
+        }
+    }
+    Ok(directory)
+}
+
+fn is_owned_pointer(codex_dir: &Path, pointer: &str) -> bool {
+    let pointer = Path::new(pointer);
+    // Never treat a traversal path as our generated pointer, even if part of
+    // the spelling happens to resemble the owned directory.
+    if pointer
+        .components()
+        .any(|part| matches!(part, Component::ParentDir))
+    {
+        return false;
+    }
+    let Some(name) = pointer.file_name().and_then(|name| name.to_str()) else {
+        return false;
+    };
+    let Some(hash) = name.strip_suffix(".json") else {
+        return false;
+    };
+    if hash.len() != 64 || !hash.bytes().all(|byte| byte.is_ascii_hexdigit()) {
+        return false;
+    }
+    let candidate = if pointer.is_absolute() {
+        pointer.to_path_buf()
+    } else {
+        codex_dir.join(pointer)
+    };
+    let root = owned_catalog_directory(codex_dir);
+    let Some(parent) = candidate.parent() else {
+        return false;
+    };
+    let Some(owner_directory) = parent.parent() else {
+        return false;
+    };
+    if parent
+        .file_name()
+        .is_none_or(|name| name != CATALOG_DIRECTORY)
+        || owner_directory
+            .file_name()
+            .is_none_or(|name| name != OWNED_DIRECTORY)
+    {
+        return false;
+    }
+    // Only the CODEX_HOME ancestor may be redirected. A link placed inside the
+    // app-owned path (or at the catalog itself) must not claim a user's target.
+    for directory in [parent, owner_directory] {
+        if fs::symlink_metadata(directory)
+            .is_ok_and(|metadata| is_link(&metadata) || !metadata.is_dir())
+        {
+            return false;
+        }
+    }
+    if fs::symlink_metadata(&candidate)
+        .is_ok_and(|metadata| is_link(&metadata) || !metadata.is_file())
+    {
+        return false;
+    }
+    let same_parent = match (parent.canonicalize(), root.canonicalize()) {
+        (Ok(parent), Ok(root)) => parent == root,
+        _ => parent == root,
+    };
+    // Retain support for legacy/stale pointers in the current owned directory.
+    // For another CODEX_HOME, require a marker and a digest covering the whole
+    // catalog; a similarly named user catalog must remain untouched.
+    same_parent || has_verified_ownership(&candidate, name)
+}
+
+pub(crate) fn prepare_model_catalog(
+    codex_dir: &Path,
+    provider_id: &str,
+    mappings: &[ProviderModelMapping],
+    model: &str,
+    doc: &mut DocumentMut,
+) -> Result<()> {
+    let mappings = normalize_mappings(mappings, model)?;
+    if mappings.is_empty() {
+        if doc
+            .get(CATALOG_FIELD)
+            .and_then(|item| item.as_str())
+            .is_some_and(|pointer| is_owned_pointer(codex_dir, pointer))
+        {
+            doc.as_table_mut().remove(CATALOG_FIELD);
+        }
+        return Ok(());
+    }
+    let mut catalog = build_catalog(&mappings, doc);
+    catalog[OWNERSHIP_FIELD] = json!({
+        "source": "codex-x", "format": 1,
+        "provider_hash": format!("{:x}", Sha256::digest(provider_id.as_bytes()))
+    });
+    let filename = catalog_filename(&catalog)?;
+    let directory = prepare_owned_directory(codex_dir)?;
+    let path = directory.join(filename);
+    match fs::symlink_metadata(&path) {
+        Ok(metadata) => {
+            if is_link(&metadata) || !metadata.is_file() || metadata.len() > MAX_CATALOG_BYTES {
+                return Err(CodexxError::Config(
+                    "已生成的模型目录文件无效，请检查后重试".into(),
+                ));
+            }
+            let existing = fs::read(&path).map_err(|error| io_err(&path, error))?;
+            if serde_json::from_slice::<Value>(&existing).ok().as_ref() != Some(&catalog) {
+                return Err(CodexxError::Config(
+                    "已生成的模型目录文件被修改，未覆盖原文件".into(),
+                ));
+            }
+        }
+        Err(error) if error.kind() == std::io::ErrorKind::NotFound => {
+            write_private_json(&path, &catalog)?
+        }
+        Err(error) => return Err(io_err(&path, error)),
+    }
+    // Change the caller's document only after a complete catalog is available.
+    // The caller owns the live config transaction; no auth/config files are
+    // read or written here, and models_cache.json is intentionally untouched.
+    doc[CATALOG_FIELD] = value(path.to_string_lossy().to_string());
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::sync::atomic::{AtomicU64, Ordering};
+
+    struct Fixture(PathBuf);
+    impl Fixture {
+        fn new() -> Self {
+            static NEXT: AtomicU64 = AtomicU64::new(0);
+            let path = std::env::temp_dir().join(format!(
+                "codex-x-catalog-{}-{}",
+                std::process::id(),
+                NEXT.fetch_add(1, Ordering::Relaxed)
+            ));
+            fs::create_dir_all(&path).unwrap();
+            Self(path)
+        }
+    }
+    impl Drop for Fixture {
+        fn drop(&mut self) {
+            let _ = fs::remove_dir_all(&self.0);
+        }
+    }
+    fn mapping(model: &str, display_name: &str, context: Option<i64>) -> ProviderModelMapping {
+        ProviderModelMapping {
+            model: model.into(),
+            display_name: display_name.into(),
+            context_window: context,
+        }
+    }
+    fn path(doc: &DocumentMut) -> PathBuf {
+        PathBuf::from(doc[CATALOG_FIELD].as_str().unwrap())
+    }
+    fn catalog(doc: &DocumentMut) -> Value {
+        serde_json::from_slice(&fs::read(path(doc)).unwrap()).unwrap()
+    }
+
+    #[test]
+    fn every_mapped_model_has_the_complete_effort_menu_without_extra_settings() {
+        for id in [
+            "deepseek-flash",
+            "deepseek-v4-flash",
+            "deepseek-v4-pro",
+            "vendor/custom-model",
+            "gpt-5.5",
+        ] {
+            let entry = model_entry(&mapping(id, id, None), 0, 128000);
+            let levels: Vec<_> = entry["supported_reasoning_levels"]
+                .as_array()
+                .unwrap()
+                .iter()
+                .map(|level| level["effort"].as_str().unwrap())
+                .collect();
+            assert_eq!(levels, REASONING_EFFORTS);
+            assert_eq!(entry["default_reasoning_level"], "high");
+            assert_eq!(entry["supports_reasoning_summaries"], true);
+            assert_eq!(entry["supports_reasoning_summary_parameter"], false);
+            assert_eq!(entry["default_reasoning_summary"], "none");
+            assert_eq!(entry["prefer_websockets"], false);
+            assert!(!entry.to_string().contains("Maps to"));
+        }
+    }
+
+    #[test]
+    fn older_saved_rows_need_no_additional_reasoning_configuration() {
+        let fixture = Fixture::new();
+        for payload in [
+            json!({"model":"custom-model"}),
+            json!({"model":"custom-model","reasoningEfforts":[]}),
+        ] {
+            let row: ProviderModelMapping = serde_json::from_value(payload).unwrap();
+            let mut doc = DocumentMut::new();
+            prepare_model_catalog(&fixture.0, "provider", &[row], "custom-model", &mut doc)
+                .unwrap();
+            let generated = catalog(&doc);
+            assert_eq!(
+                generated["models"][0]["supported_reasoning_levels"]
+                    .as_array()
+                    .unwrap()
+                    .len(),
+                8
+            );
+            assert_eq!(
+                generated["models"][0]["supported_reasoning_levels"][0]["effort"],
+                "none"
+            );
+            assert_eq!(generated["models"][0]["default_reasoning_level"], "high");
+        }
+    }
+
+    #[test]
+    fn normalization_preserves_real_models_and_adds_missing_default() {
+        let result = normalize_mappings(
+            &[
+                mapping(" vendor/model-A ", "菜单名称", Some(1_048_576)),
+                mapping("vendor/model-A", "duplicate", Some(128_000)),
+                mapping("vendor/model-a", "", None),
+            ],
+            "deepseek-chat",
+        )
+        .unwrap();
+        assert_eq!(result.len(), 3);
+        assert_eq!(result[0], mapping("deepseek-chat", "deepseek-chat", None));
+        assert_eq!(
+            result[1],
+            mapping("vendor/model-A", "菜单名称", Some(1_048_576))
+        );
+        assert_eq!(result[2].display_name, "vendor/model-a");
+        assert!(normalize_mappings(&[], "").unwrap().is_empty());
+    }
+
+    #[test]
+    fn rejects_invalid_ids_names_context_and_too_many_models() {
+        for invalid in ["", "model\nname", &"a".repeat(201)] {
+            assert!(normalize_mappings(&[mapping(invalid, "", None)], "default").is_err());
+        }
+        assert!(normalize_mappings(&[mapping("model", "bad\nname", None)], "model").is_err());
+        for invalid in [0, -1, MAX_CONTEXT_WINDOW + 1] {
+            assert!(normalize_mappings(&[mapping("model", "", Some(invalid))], "model").is_err());
+        }
+        let rows: Vec<_> = (0..64)
+            .map(|index| mapping(&format!("model-{index}"), "", None))
+            .collect();
+        assert_eq!(normalize_mappings(&rows, "model-0").unwrap().len(), 64);
+        assert!(normalize_mappings(&rows, "missing-default").is_err());
+        let mut excessive = rows;
+        excessive.push(mapping("model-64", "", None));
+        assert!(normalize_mappings(&excessive, "model-0").is_err());
+    }
+
+    #[test]
+    fn serialized_mapping_allows_omitted_display_name_and_context() {
+        let mapping: ProviderModelMapping =
+            serde_json::from_str(r#"{"model":"deepseek-chat"}"#).unwrap();
+        let normalized = normalize_mappings(&[mapping], "deepseek-chat").unwrap();
+        assert_eq!(
+            serde_json::to_value(&normalized[0]).unwrap(),
+            json!({"model":"deepseek-chat","displayName":"deepseek-chat","contextWindow":null})
+        );
+    }
+
+    #[test]
+    fn catalog_never_impersonates_gpt_or_copies_cached_capabilities() {
+        let fixture = Fixture::new();
+        let cache = json!({"models":[{"slug":"gpt-5.5","model_messages":{"instructions_template":"PRIVATE CACHED INSTRUCTIONS"},"apply_patch_tool_type":"freeform","experimental_supported_tools":["namespace-secret"],"supports_image_detail_original":true}]});
+        let cache_text = serde_json::to_vec(&cache).unwrap();
+        fs::write(fixture.0.join("models_cache.json"), &cache_text).unwrap();
+        fs::write(fixture.0.join("config.toml"), "original-config").unwrap();
+        fs::write(fixture.0.join("auth.json"), "original-auth").unwrap();
+        let mut doc = DocumentMut::new();
+        prepare_model_catalog(
+            &fixture.0,
+            "provider-a",
+            &[mapping("deepseek-chat", "DeepSeek 常用", Some(131072))],
+            "deepseek-chat",
+            &mut doc,
+        )
+        .unwrap();
+        let catalog = catalog(&doc);
+        let model = &catalog["models"][0];
+        assert_eq!(model["slug"], "deepseek-chat");
+        assert_eq!(model["display_name"], "DeepSeek 常用");
+        assert_eq!(model["context_window"], 131072);
+        assert_eq!(model["apply_patch_tool_type"], Value::Null);
+        assert_eq!(model["input_modalities"], json!(["text"]));
+        assert!(!catalog.to_string().contains("gpt-5.5"));
+        assert!(!catalog.to_string().contains("PRIVATE"));
+        assert!(!catalog.to_string().contains("namespace-secret"));
+        assert_eq!(
+            fs::read(fixture.0.join("models_cache.json")).unwrap(),
+            cache_text
+        );
+        assert_eq!(
+            fs::read_to_string(fixture.0.join("config.toml")).unwrap(),
+            "original-config"
+        );
+        assert_eq!(
+            fs::read_to_string(fixture.0.join("auth.json")).unwrap(),
+            "original-auth"
+        );
+    }
+
+    #[test]
+    fn providers_and_changed_content_have_distinct_immutable_catalogs() {
+        let fixture = Fixture::new();
+        let rows = [mapping("model", "Name", None)];
+        let mut first = DocumentMut::new();
+        let mut second = DocumentMut::new();
+        prepare_model_catalog(&fixture.0, "../../provider-a", &rows, "model", &mut first).unwrap();
+        let original_path = path(&first);
+        let original_bytes = fs::read(&original_path).unwrap();
+        prepare_model_catalog(&fixture.0, "provider-b", &rows, "model", &mut second).unwrap();
+        assert_ne!(original_path, path(&second));
+        assert!(
+            original_path.starts_with(owned_catalog_directory(&fixture.0.canonicalize().unwrap()))
+        );
+        assert!(!original_path.to_string_lossy().contains("provider-a"));
+        prepare_model_catalog(
+            &fixture.0,
+            "../../provider-a",
+            &[mapping("model", "Changed", None)],
+            "model",
+            &mut first,
+        )
+        .unwrap();
+        assert_ne!(original_path, path(&first));
+        assert_eq!(fs::read(original_path).unwrap(), original_bytes);
+    }
+
+    #[test]
+    fn unchanged_content_is_reused_and_tampered_file_is_not_overwritten() {
+        let fixture = Fixture::new();
+        let rows = [mapping("model", "Name", None)];
+        let mut doc = DocumentMut::new();
+        prepare_model_catalog(&fixture.0, "provider", &rows, "model", &mut doc).unwrap();
+        let generated = path(&doc);
+        let modified = fs::metadata(&generated).unwrap().modified().unwrap();
+        prepare_model_catalog(&fixture.0, "provider", &rows, "model", &mut doc).unwrap();
+        assert_eq!(
+            fs::metadata(&generated).unwrap().modified().unwrap(),
+            modified
+        );
+        fs::write(&generated, "keep this changed file").unwrap();
+        let before = doc.to_string();
+        assert!(prepare_model_catalog(&fixture.0, "provider", &rows, "model", &mut doc).is_err());
+        assert_eq!(doc.to_string(), before);
+        assert_eq!(
+            fs::read_to_string(generated).unwrap(),
+            "keep this changed file"
+        );
+    }
+
+    #[test]
+    fn disabling_removes_only_our_pointer_without_deleting_catalog() {
+        let fixture = Fixture::new();
+        let mut doc = DocumentMut::new();
+        prepare_model_catalog(
+            &fixture.0,
+            "provider",
+            &[mapping("model", "Name", None)],
+            "model",
+            &mut doc,
+        )
+        .unwrap();
+        let generated = path(&doc);
+        prepare_model_catalog(&fixture.0, "provider", &[], "model", &mut doc).unwrap();
+        assert!(doc.get(CATALOG_FIELD).is_none());
+        assert!(generated.is_file());
+        for custom in [
+            "custom-models.json",
+            ".codex-x/model-catalogs/my-custom.json",
+            ".codex-x/model-catalogs/../custom.json",
+        ] {
+            doc[CATALOG_FIELD] = value(custom);
+            prepare_model_catalog(&fixture.0, "provider", &[], "model", &mut doc).unwrap();
+            assert_eq!(doc[CATALOG_FIELD].as_str(), Some(custom));
+        }
+    }
+
+    #[test]
+    fn relative_and_stale_owned_pointers_can_be_removed() {
+        let fixture = Fixture::new();
+        let mut doc = DocumentMut::new();
+        let pointer = format!(
+            "{OWNED_DIRECTORY}/{CATALOG_DIRECTORY}/{}.json",
+            "a".repeat(64)
+        );
+        doc[CATALOG_FIELD] = value(pointer);
+        prepare_model_catalog(&fixture.0, "provider", &[], "", &mut doc).unwrap();
+        assert!(doc.get(CATALOG_FIELD).is_none());
+    }
+
+    #[test]
+    fn disabling_after_switching_codex_home_clears_verified_generated_pointer() {
+        let first_home = Fixture::new();
+        let second_home = Fixture::new();
+        let mut doc = DocumentMut::new();
+        prepare_model_catalog(
+            &first_home.0,
+            "provider-a",
+            &[mapping("deepseek-v4-pro", "DeepSeek", None)],
+            "deepseek-v4-pro",
+            &mut doc,
+        )
+        .unwrap();
+        let generated = path(&doc);
+        let before = fs::read(&generated).unwrap();
+        prepare_model_catalog(&second_home.0, "provider-b", &[], "another-model", &mut doc)
+            .unwrap();
+        assert!(doc.get(CATALOG_FIELD).is_none());
+        assert_eq!(fs::read(&generated).unwrap(), before);
+        assert!(!owned_catalog_directory(&second_home.0).exists());
+    }
+
+    #[test]
+    fn official_cleanup_recognizes_other_home_but_preserves_unverified_user_catalog() {
+        let first_home = Fixture::new();
+        let second_home = Fixture::new();
+        let mut doc = DocumentMut::new();
+        prepare_model_catalog(
+            &first_home.0,
+            "provider-a",
+            &[mapping("deepseek-v4-pro", "DeepSeek", None)],
+            "deepseek-v4-pro",
+            &mut doc,
+        )
+        .unwrap();
+        let generated = path(&doc);
+        let original: Value = serde_json::from_slice(&fs::read(&generated).unwrap()).unwrap();
+        prepare_model_catalog(&second_home.0, "official", &[], "", &mut doc).unwrap();
+        assert!(doc.get(CATALOG_FIELD).is_none());
+
+        // A matching-looking name without the app's marker is user content.
+        let mut no_marker = original.clone();
+        no_marker.as_object_mut().unwrap().remove(OWNERSHIP_FIELD);
+        // A copied marker does not authorize a modified catalog either.
+        let mut modified = original;
+        modified["models"][0]["display_name"] = json!("User's own menu");
+        for unverified in [no_marker, modified] {
+            fs::write(&generated, serde_json::to_vec(&unverified).unwrap()).unwrap();
+            doc[CATALOG_FIELD] = value(generated.to_string_lossy().to_string());
+            prepare_model_catalog(&second_home.0, "official", &[], "", &mut doc).unwrap();
+            assert_eq!(path(&doc), generated);
+            assert_eq!(
+                serde_json::from_slice::<Value>(&fs::read(&generated).unwrap()).unwrap(),
+                unverified
+            );
+        }
+    }
+
+    #[test]
+    fn omitted_context_uses_explicit_live_context_or_neutral_default() {
+        let rows = [
+            mapping("model", "Model", None),
+            mapping("other", "Other", Some(64000)),
+        ];
+        let mut doc: DocumentMut = "model_context_window = 1000000".parse().unwrap();
+        let catalog = build_catalog(&rows, &doc);
+        assert_eq!(catalog["models"][0]["context_window"], 1_000_000);
+        assert_eq!(catalog["models"][1]["context_window"], 64_000);
+        doc["model_context_window"] = value(-1);
+        assert_eq!(
+            build_catalog(&rows, &doc)["models"][0]["context_window"],
+            DEFAULT_CONTEXT_WINDOW
+        );
+    }
+
+    #[cfg(unix)]
+    #[test]
+    fn generated_files_are_private_and_owned_directory_links_are_rejected() {
+        use std::os::unix::fs::{symlink, PermissionsExt};
+        let fixture = Fixture::new();
+        let mut doc = DocumentMut::new();
+        let rows = [mapping("model", "Model", None)];
+        prepare_model_catalog(&fixture.0, "provider", &rows, "model", &mut doc).unwrap();
+        assert_eq!(
+            fs::metadata(path(&doc)).unwrap().permissions().mode() & 0o777,
+            0o600
+        );
+        let linked = Fixture::new();
+        symlink(&fixture.0, linked.0.join(OWNED_DIRECTORY)).unwrap();
+        let before = doc.to_string();
+        assert!(prepare_model_catalog(&linked.0, "provider", &rows, "model", &mut doc).is_err());
+        assert_eq!(doc.to_string(), before);
+    }
+
+    #[cfg(unix)]
+    #[test]
+    fn redirected_codex_home_is_supported_but_custom_file_links_are_not_removed() {
+        use std::os::unix::fs::symlink;
+        let fixture = Fixture::new();
+        let links = Fixture::new();
+        let linked_home = links.0.join("codex-home");
+        symlink(&fixture.0, &linked_home).unwrap();
+        let mut doc = DocumentMut::new();
+        prepare_model_catalog(
+            &linked_home,
+            "provider",
+            &[mapping("model", "Model", None)],
+            "model",
+            &mut doc,
+        )
+        .unwrap();
+        let generated = path(&doc);
+        prepare_model_catalog(&linked_home, "provider", &[], "model", &mut doc).unwrap();
+        assert!(doc.get(CATALOG_FIELD).is_none());
+        fs::remove_file(&generated).unwrap();
+        let custom = links.0.join("custom.json");
+        fs::write(&custom, "user catalog").unwrap();
+        symlink(&custom, &generated).unwrap();
+        doc[CATALOG_FIELD] = value(generated.to_string_lossy().to_string());
+        prepare_model_catalog(&fixture.0, "provider", &[], "model", &mut doc).unwrap();
+        assert!(doc.get(CATALOG_FIELD).is_some());
+        assert_eq!(fs::read_to_string(custom).unwrap(), "user catalog");
+    }
+}

apps/desktop/src-tauri/src/providers/quota.rs

@@ -0,0 +1,946 @@
+//! Read-only subscription quota lookup for one saved official login. Credentials
+//! stay in native code; neither network errors nor response bodies are logged.
+
+use super::official_profiles::{
+    official_profile_quota_credentials, OfficialProfileQuotaCredentials,
+};
+use crate::error::{CodexxError, Result};
+use crate::live_config::acquire_live_config_lock;
+use crate::remote::ensure_crypto_provider;
+use chrono::{DateTime, Duration as ChronoDuration, Utc};
+use reqwest::blocking::Client;
+use reqwest::header::{HeaderMap, HeaderValue, ACCEPT, AUTHORIZATION, USER_AGENT};
+use reqwest::StatusCode;
+use serde::{Deserialize, Serialize};
+use sha2::{Digest, Sha256};
+use std::io::Read;
+use std::path::Path;
+use std::sync::Mutex;
+use std::time::Duration;
+
+const QUOTA_URL: &str = "https://chatgpt.com/backend-api/wham/usage";
+const RESET_CREDITS_URL: &str = "https://chatgpt.com/backend-api/wham/rate-limit-reset-credits";
+const MAX_RESPONSE_BYTES: usize = 1024 * 1024;
+// The file lock is nonblocking. Concurrent quota and credit queries share this
+// brief gate while reading credentials, so they cannot fail each other's read.
+// Neither this gate nor the file lock is held during a network request.
+static QUERY_CREDENTIAL_LOCK: Mutex<()> = Mutex::new(());
+
+#[derive(Clone, Copy)]
+enum OfficialQuery {
+    Quota,
+    ResetCredits,
+}
+
+impl OfficialQuery {
+    fn url(self) -> &'static str {
+        match self {
+            Self::Quota => QUOTA_URL,
+            Self::ResetCredits => RESET_CREDITS_URL,
+        }
+    }
+
+    fn label(self) -> &'static str {
+        match self {
+            Self::Quota => "额度",
+            Self::ResetCredits => "重置次数",
+        }
+    }
+}
+
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub(crate) struct OfficialResetCreditsSnapshot {
+    profile_id: String,
+    available_count: u32,
+    checked_at: String,
+}
+
+#[derive(Deserialize)]
+struct RawResetCreditsResponse {
+    // Required and unsigned: unknown or invalid counts must never look like 0.
+    available_count: u32,
+}
+
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub(crate) struct OfficialQuotaSnapshot {
+    profile_id: String,
+    email: Option<String>,
+    plan_type: Option<String>,
+    limits: Vec<OfficialQuotaLimit>,
+    checked_at: String,
+}
+
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub(crate) struct OfficialQuotaLimit {
+    id: String,
+    name: Option<String>,
+    allowed: Option<bool>,
+    limit_reached: Option<bool>,
+    windows: Vec<OfficialQuotaWindow>,
+}
+
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub(crate) struct OfficialQuotaWindow {
+    id: String,
+    window_seconds: Option<i64>,
+    used_percent: Option<f64>,
+    remaining_percent: Option<f64>,
+    resets_at: Option<String>,
+}
+
+#[derive(Default, Deserialize)]
+struct RawWindow {
+    limit_window_seconds: Option<i64>,
+    used_percent: Option<f64>,
+    reset_at: Option<i64>,
+    reset_after_seconds: Option<i64>,
+}
+
+#[derive(Default, Deserialize)]
+struct RawLimit {
+    allowed: Option<bool>,
+    limit_reached: Option<bool>,
+    primary_window: Option<RawWindow>,
+    secondary_window: Option<RawWindow>,
+}
+
+#[derive(Deserialize)]
+struct RawAdditionalLimit {
+    limit_name: Option<String>,
+    name: Option<String>,
+    metered_feature: Option<String>,
+    rate_limit: Option<RawLimit>,
+    #[serde(flatten)]
+    direct_limit: RawLimit,
+}
+
+#[derive(Deserialize)]
+struct RawQuotaResponse {
+    account_id: Option<String>,
+    email: Option<String>,
+    plan_type: Option<String>,
+    rate_limit: Option<RawLimit>,
+    code_review_rate_limit: Option<RawLimit>,
+    additional_rate_limits: Option<Vec<Option<RawAdditionalLimit>>>,
+}
+
+fn config_error(message: &str) -> CodexxError {
+    CodexxError::Config(message.to_owned())
+}
+
+fn nonempty(value: Option<&str>) -> Option<&str> {
+    value.map(str::trim).filter(|value| !value.is_empty())
+}
+
+fn display_email(value: Option<&str>) -> Option<String> {
+    nonempty(value)
+        .filter(|email| email.len() <= 320 && email.contains('@'))
+        .filter(|email| {
+            !email
+                .chars()
+                .any(|character| character.is_control() || character.is_whitespace())
+        })
+        .map(str::to_owned)
+}
+
+fn quota_headers(credentials: &OfficialProfileQuotaCredentials) -> Result<HeaderMap> {
+    let token = nonempty(Some(&credentials.access_token))
+        .ok_or_else(|| config_error("此官方配置尚未登录，请先在 Codex 中登录"))?;
+    let mut authorization = HeaderValue::from_str(&format!("Bearer {token}"))
+        .map_err(|_| config_error("此官方配置的登录凭据无效，请重新登录"))?;
+    authorization.set_sensitive(true);
+    let mut headers = HeaderMap::new();
+    headers.insert(AUTHORIZATION, authorization);
+    headers.insert(ACCEPT, HeaderValue::from_static("application/json"));
+    headers.insert(USER_AGENT, HeaderValue::from_static("codex-cli"));
+    if let Some(account_id) = nonempty(credentials.account_id.as_deref()) {
+        let mut account = HeaderValue::from_str(account_id)
+            .map_err(|_| config_error("此官方配置的账号标识无效，请重新登录"))?;
+        account.set_sensitive(true);
+        headers.insert("ChatGPT-Account-Id", account);
+    }
+    Ok(headers)
+}
+
+fn quota_client() -> Result<Client> {
+    ensure_crypto_provider();
+    Client::builder()
+        .https_only(true)
+        .redirect(reqwest::redirect::Policy::none())
+        .timeout(Duration::from_secs(15))
+        .connect_timeout(Duration::from_secs(5))
+        .build()
+        .map_err(|_| config_error("官方账号查询客户端初始化失败"))
+}
+
+fn check_status(status: StatusCode, query: OfficialQuery) -> Result<()> {
+    if status.is_success() {
+        return Ok(());
+    }
+    let label = query.label();
+    let message = match status.as_u16() {
+        401 => format!("官方登录已失效，请重新登录此账号后查询{label}（HTTP 401）"),
+        403 => format!("无法访问官方{label}服务（HTTP 403），请稍后重试或检查网络"),
+        429 => format!("官方{label}查询过于频繁，请稍后重试（HTTP 429）"),
+        300..=399 => format!("官方{label}接口发生重定向，已停止请求，请稍后重试"),
+        code @ 500..=599 => format!("官方{label}服务暂不可用（HTTP {code}），请稍后重试"),
+        code => format!("官方{label}查询失败（HTTP {code}），请稍后重试"),
+    };
+    Err(CodexxError::Config(message))
+}
+
+fn read_bounded_body(reader: impl Read, content_length: Option<u64>) -> Result<Vec<u8>> {
+    if content_length.is_some_and(|length| length > MAX_RESPONSE_BYTES as u64) {
+        return Err(config_error("官方查询响应过大，已停止读取"));
+    }
+    let mut bytes = Vec::new();
+    reader
+        .take(MAX_RESPONSE_BYTES as u64 + 1)
+        .read_to_end(&mut bytes)
+        .map_err(|_| config_error("读取官方查询响应失败，请稍后重试"))?;
+    if bytes.len() > MAX_RESPONSE_BYTES {
+        return Err(config_error("官方查询响应过大，已停止读取"));
+    }
+    Ok(bytes)
+}
+
+fn window(id: &str, raw: RawWindow, checked_at: DateTime<Utc>) -> OfficialQuotaWindow {
+    let used_percent = raw
+        .used_percent
+        .filter(|value| value.is_finite())
+        .map(|value| value.clamp(0.0, 100.0));
+    let resets_at = raw
+        .reset_at
+        .and_then(|seconds| DateTime::from_timestamp(seconds, 0))
+        .or_else(|| {
+            raw.reset_after_seconds
+                .filter(|seconds| *seconds >= 0)
+                .and_then(ChronoDuration::try_seconds)
+                .and_then(|duration| checked_at.checked_add_signed(duration))
+        })
+        .map(|time| time.to_rfc3339());
+    OfficialQuotaWindow {
+        id: id.to_owned(),
+        window_seconds: raw.limit_window_seconds.filter(|seconds| *seconds > 0),
+        used_percent,
+        remaining_percent: used_percent.map(|value| (100.0 - value).clamp(0.0, 100.0)),
+        resets_at,
+    }
+}
+
+fn limit(
+    id: String,
+    name: Option<String>,
+    raw: RawLimit,
+    checked_at: DateTime<Utc>,
+) -> OfficialQuotaLimit {
+    let windows = [
+        ("primary", raw.primary_window),
+        ("secondary", raw.secondary_window),
+    ]
+    .into_iter()
+    .filter_map(|(id, raw)| raw.map(|raw| window(id, raw, checked_at)))
+    .collect();
+    OfficialQuotaLimit {
+        id,
+        name,
+        allowed: raw.allowed,
+        limit_reached: raw.limit_reached,
+        windows,
+    }
+}
+
+fn parse_quota_response(
+    bytes: &[u8],
+    profile_id: &str,
+    credentials: &OfficialProfileQuotaCredentials,
+    checked_at: DateTime<Utc>,
+) -> Result<OfficialQuotaSnapshot> {
+    let raw: RawQuotaResponse = serde_json::from_slice(bytes)
+        .map_err(|_| config_error("官方额度响应格式无法识别，请稍后重试"))?;
+    if nonempty(raw.account_id.as_deref())
+        .zip(nonempty(credentials.account_id.as_deref()))
+        .is_some_and(|(actual, expected)| actual != expected)
+    {
+        return Err(config_error(
+            "额度响应与所选官方账号不一致，请重新登录此配置后重试",
+        ));
+    }
+    let mut limits = Vec::new();
+    if let Some(raw) = raw.rate_limit {
+        limits.push(limit("main".to_owned(), None, raw, checked_at));
+    }
+    if let Some(raw) = raw.code_review_rate_limit {
+        limits.push(limit("code_review".to_owned(), None, raw, checked_at));
+    }
+    for (index, additional) in raw
+        .additional_rate_limits
+        .unwrap_or_default()
+        .into_iter()
+        .enumerate()
+    {
+        let Some(additional) = additional else {
+            continue;
+        };
+        let name = nonempty(additional.limit_name.as_deref())
+            .or_else(|| nonempty(additional.name.as_deref()))
+            .or_else(|| nonempty(additional.metered_feature.as_deref()))
+            .map(str::to_owned);
+        limits.push(limit(
+            format!("additional-{index}"),
+            name,
+            additional.rate_limit.unwrap_or(additional.direct_limit),
+            checked_at,
+        ));
+    }
+    Ok(OfficialQuotaSnapshot {
+        profile_id: profile_id.to_owned(),
+        email: display_email(raw.email.as_deref())
+            .or_else(|| display_email(credentials.email.as_deref())),
+        plan_type: nonempty(raw.plan_type.as_deref()).map(str::to_owned),
+        limits,
+        checked_at: checked_at.to_rfc3339(),
+    })
+}
+
+fn credential_fingerprint(credentials: &OfficialProfileQuotaCredentials) -> [u8; 32] {
+    let mut digest = Sha256::new();
+    // Length-delimit components so two different identities cannot have the
+    // same concatenated input. Only this digest is compared after the request.
+    for value in [
+        Some(credentials.access_token.as_str()),
+        credentials.account_id.as_deref(),
+        credentials.email.as_deref(),
+    ] {
+        let bytes = value.unwrap_or_default().as_bytes();
+        digest.update((bytes.len() as u64).to_le_bytes());
+        digest.update(bytes);
+    }
+    digest.finalize().into()
+}
+
+fn parse_reset_credits_response(
+    bytes: &[u8],
+    profile_id: &str,
+    checked_at: DateTime<Utc>,
+) -> Result<OfficialResetCreditsSnapshot> {
+    let raw: RawResetCreditsResponse = serde_json::from_slice(bytes)
+        .map_err(|_| config_error("官方重置次数响应格式无法识别，请稍后重试"))?;
+    Ok(OfficialResetCreditsSnapshot {
+        profile_id: profile_id.to_owned(),
+        available_count: raw.available_count,
+        checked_at: checked_at.to_rfc3339(),
+    })
+}
+
+fn ensure_same_credentials(
+    expected: [u8; 32],
+    current: &OfficialProfileQuotaCredentials,
+) -> Result<()> {
+    if expected != credential_fingerprint(current) {
+        return Err(config_error("此官方账号的登录信息已变化，请重新刷新"));
+    }
+    Ok(())
+}
+
+fn fetch_official_response(
+    query: OfficialQuery,
+    credentials: &OfficialProfileQuotaCredentials,
+) -> Result<Vec<u8>> {
+    let headers = quota_headers(credentials)?;
+    let label = query.label();
+    let response = quota_client()?
+        .get(query.url())
+        .headers(headers)
+        .send()
+        .map_err(|error| {
+            if error.is_timeout() {
+                config_error(&format!("官方{label}查询超时，请检查网络后重试"))
+            } else if error.is_connect() {
+                config_error(&format!("无法连接官方{label}接口，请检查网络或代理设置"))
+            } else {
+                config_error(&format!("官方{label}网络请求失败，请稍后重试"))
+            }
+        })?;
+    check_status(response.status(), query)?;
+    let length = response.content_length();
+    read_bounded_body(response, length)
+}
+
+fn read_query_credentials(
+    codex_dir: &Path,
+    profile_id: &str,
+) -> Result<OfficialProfileQuotaCredentials> {
+    let _query_guard = QUERY_CREDENTIAL_LOCK
+        .lock()
+        .map_err(|_| config_error("官方账号查询暂不可用，请重试"))?;
+    let _file_guard = acquire_live_config_lock(codex_dir)
+        .map_err(|_| config_error("官方配置正在修改，请稍后刷新"))?;
+    official_profile_quota_credentials(codex_dir, profile_id)
+}
+
+fn read_official_snapshot<T>(
+    codex_dir: &Path,
+    profile_id: &str,
+    fetch: impl FnOnce(&OfficialProfileQuotaCredentials) -> Result<Vec<u8>>,
+    parse: impl FnOnce(&[u8], &str, &OfficialProfileQuotaCredentials, DateTime<Utc>) -> Result<T>,
+) -> Result<T> {
+    let credentials = read_query_credentials(codex_dir, profile_id)?;
+    let fingerprint = credential_fingerprint(&credentials);
+    let bytes = fetch(&credentials)?;
+    let snapshot = parse(&bytes, profile_id, &credentials, Utc::now())?;
+    let current = read_query_credentials(codex_dir, profile_id)
+        .map_err(|_| config_error("此官方配置已变化或被删除，请重新选择账号后查询"))?;
+    ensure_same_credentials(fingerprint, &current)?;
+    Ok(snapshot)
+}
+
+pub(crate) fn get_official_profile_quota_inner(
+    config_dir: Option<String>,
+    profile_id: String,
+) -> Result<OfficialQuotaSnapshot> {
+    let codex_dir = crate::resolve_codex_dir(config_dir)?;
+    read_official_snapshot(
+        &codex_dir,
+        profile_id.trim(),
+        |credentials| fetch_official_response(OfficialQuery::Quota, credentials),
+        parse_quota_response,
+    )
+}
+
+pub(crate) fn get_official_profile_reset_credits_inner(
+    config_dir: Option<String>,
+    profile_id: String,
+) -> Result<OfficialResetCreditsSnapshot> {
+    let codex_dir = crate::resolve_codex_dir(config_dir)?;
+    read_official_snapshot(
+        &codex_dir,
+        profile_id.trim(),
+        |credentials| fetch_official_response(OfficialQuery::ResetCredits, credentials),
+        |bytes, profile_id, _, checked_at| {
+            parse_reset_credits_response(bytes, profile_id, checked_at)
+        },
+    )
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde_json::json;
+
+    fn credentials(account: Option<&str>) -> OfficialProfileQuotaCredentials {
+        OfficialProfileQuotaCredentials {
+            access_token: "synthetic-access-token".to_owned(),
+            account_id: account.map(str::to_owned),
+            email: Some("saved@example.test".to_owned()),
+        }
+    }
+
+    fn checked_at() -> DateTime<Utc> {
+        DateTime::parse_from_rfc3339("2026-09-09T03:00:00Z")
+            .unwrap()
+            .with_timezone(&Utc)
+    }
+
+    fn parse(value: serde_json::Value, account: Option<&str>) -> OfficialQuotaSnapshot {
+        parse_quota_response(
+            &serde_json::to_vec(&value).unwrap(),
+            "official-profile-a",
+            &credentials(account),
+            checked_at(),
+        )
+        .unwrap()
+    }
+
+    #[test]
+    fn pro_primary_window_can_be_weekly_and_account_id_can_be_absent() {
+        let snapshot = parse(
+            json!({
+                "plan_type":"pro", "email":"active@example.test", "account_id":"server-account",
+                "rate_limit":{"allowed":true,"limit_reached":false,"primary_window":{"limit_window_seconds":604800,"used_percent":37.5,"reset_after_seconds":600}},
+                "additional_rate_limits":null,"code_review_rate_limit":null
+            }),
+            None,
+        );
+        assert_eq!(snapshot.profile_id, "official-profile-a");
+        assert_eq!(snapshot.email.as_deref(), Some("active@example.test"));
+        assert_eq!(snapshot.plan_type.as_deref(), Some("pro"));
+        assert_eq!(snapshot.limits.len(), 1);
+        let limit = &snapshot.limits[0];
+        assert_eq!(limit.id, "main");
+        assert_eq!(limit.allowed, Some(true));
+        assert_eq!(limit.windows[0].id, "primary");
+        assert_eq!(limit.windows[0].window_seconds, Some(604800));
+        assert_eq!(limit.windows[0].remaining_percent, Some(62.5));
+        assert_eq!(
+            limit.windows[0].resets_at.as_deref(),
+            Some("2026-09-09T03:10:00+00:00")
+        );
+    }
+
+    #[test]
+    fn team_two_windows_preserve_real_durations_and_absolute_reset_priority() {
+        let reset = checked_at().timestamp() + 3600;
+        let snapshot = parse(
+            json!({
+                "account_id":"team-a","plan_type":"team",
+                "rate_limit":{"allowed":false,"limit_reached":true,
+                    "primary_window":{"limit_window_seconds":18000,"used_percent":100,"reset_at":reset,"reset_after_seconds":20},
+                    "secondary_window":{"limit_window_seconds":604800,"used_percent":23.25}}
+            }),
+            Some("team-a"),
+        );
+        let limit = &snapshot.limits[0];
+        assert_eq!(limit.windows.len(), 2);
+        assert_eq!(limit.limit_reached, Some(true));
+        assert_eq!(limit.windows[0].window_seconds, Some(18000));
+        assert_eq!(limit.windows[0].remaining_percent, Some(0.0));
+        assert_eq!(
+            limit.windows[0].resets_at.as_deref(),
+            Some("2026-09-09T04:00:00+00:00")
+        );
+        assert_eq!(limit.windows[1].window_seconds, Some(604800));
+        assert_eq!(limit.windows[1].remaining_percent, Some(76.75));
+        assert!(limit.windows[1].resets_at.is_none());
+    }
+
+    #[test]
+    fn code_review_and_additional_features_remain_separate_limits() {
+        let snapshot = parse(
+            json!({
+                "rate_limit":null,
+                "code_review_rate_limit":{"allowed":true,"primary_window":{"used_percent":10,"limit_window_seconds":604800}},
+                "additional_rate_limits":[null,
+                    {"limit_name":"Codex Spark","metered_feature":"codex_bengal","rate_limit":{"allowed":true,"primary_window":{"used_percent":40,"limit_window_seconds":18000}}},
+                    {"metered_feature":"future_feature","allowed":false,"limit_reached":true,"primary_window":{"used_percent":100,"limit_window_seconds":86400}}]
+            }),
+            None,
+        );
+        assert_eq!(snapshot.limits.len(), 3);
+        assert_eq!(snapshot.limits[0].id, "code_review");
+        assert_eq!(snapshot.limits[1].id, "additional-1");
+        assert_eq!(snapshot.limits[1].name.as_deref(), Some("Codex Spark"));
+        assert_eq!(snapshot.limits[2].name.as_deref(), Some("future_feature"));
+        assert_eq!(snapshot.limits[2].allowed, Some(false));
+        assert_eq!(snapshot.limits[2].windows[0].window_seconds, Some(86400));
+    }
+
+    #[test]
+    fn missing_usage_is_unknown_instead_of_zero_or_full_remaining() {
+        let snapshot = parse(
+            json!({"rate_limit":{"primary_window":{"limit_window_seconds":18000}}}),
+            None,
+        );
+        let window = &snapshot.limits[0].windows[0];
+        assert!(window.used_percent.is_none());
+        assert!(window.remaining_percent.is_none());
+        assert!(snapshot.limits[0].allowed.is_none());
+        assert!(snapshot.limits[0].limit_reached.is_none());
+        let empty = parse(json!({}), None);
+        assert!(empty.limits.is_empty());
+    }
+
+    #[test]
+    fn finite_percentages_are_clamped_and_nonfinite_values_stay_unknown() {
+        for (used, expected) in [
+            (-20.0, Some(0.0)),
+            (130.0, Some(100.0)),
+            (f64::NAN, None),
+            (f64::INFINITY, None),
+        ] {
+            let value = window(
+                "primary",
+                RawWindow {
+                    used_percent: Some(used),
+                    ..Default::default()
+                },
+                checked_at(),
+            );
+            assert_eq!(value.used_percent, expected);
+            assert_eq!(value.remaining_percent, expected.map(|used| 100.0 - used));
+        }
+    }
+
+    #[test]
+    fn invalid_reset_and_window_numbers_do_not_panic_or_invent_dates() {
+        let value = window(
+            "primary",
+            RawWindow {
+                limit_window_seconds: Some(-1),
+                reset_at: Some(i64::MAX),
+                reset_after_seconds: Some(i64::MAX),
+                ..Default::default()
+            },
+            checked_at(),
+        );
+        assert!(value.window_seconds.is_none());
+        assert!(value.resets_at.is_none());
+        let negative = window(
+            "primary",
+            RawWindow {
+                reset_after_seconds: Some(-10),
+                ..Default::default()
+            },
+            checked_at(),
+        );
+        assert!(negative.resets_at.is_none());
+        let now = window(
+            "primary",
+            RawWindow {
+                reset_after_seconds: Some(0),
+                ..Default::default()
+            },
+            checked_at(),
+        );
+        assert_eq!(now.resets_at.as_deref(), Some("2026-09-09T03:00:00+00:00"));
+    }
+
+    #[test]
+    fn different_nonempty_response_account_is_rejected_without_identifiers_in_error() {
+        let error = parse_quota_response(
+            br#"{"account_id":"other-private-account"}"#,
+            "official-profile-a",
+            &credentials(Some("selected-private-account")),
+            checked_at(),
+        )
+        .unwrap_err()
+        .to_string();
+        assert!(error.contains("不一致"));
+        assert!(!error.contains("private-account"));
+        assert!(!error.contains("synthetic-access-token"));
+        assert!(
+            parse(json!({"account_id":null}), Some("selected-private-account"))
+                .limits
+                .is_empty()
+        );
+    }
+
+    #[test]
+    fn email_uses_response_first_then_safe_saved_display_metadata() {
+        assert_eq!(
+            parse(json!({"email":"response@example.test"}), None)
+                .email
+                .as_deref(),
+            Some("response@example.test")
+        );
+        assert_eq!(
+            parse(json!({"email":"bad\n@example.test"}), None)
+                .email
+                .as_deref(),
+            Some("saved@example.test")
+        );
+        assert_eq!(
+            parse(json!({}), None).email.as_deref(),
+            Some("saved@example.test")
+        );
+    }
+
+    #[test]
+    fn request_has_only_fixed_https_endpoint_and_sensitive_auth_headers() {
+        let request = quota_client()
+            .unwrap()
+            .get(QUOTA_URL)
+            .headers(quota_headers(&credentials(Some("account-a"))).unwrap())
+            .build()
+            .unwrap();
+        assert_eq!(request.method(), reqwest::Method::GET);
+        assert_eq!(request.url().as_str(), QUOTA_URL);
+        assert_eq!(request.url().host_str(), Some("chatgpt.com"));
+        assert_eq!(request.url().scheme(), "https");
+        assert!(request.headers()[AUTHORIZATION].is_sensitive());
+        assert_eq!(
+            request.headers()[AUTHORIZATION],
+            "Bearer synthetic-access-token"
+        );
+        assert!(request.headers()["chatgpt-account-id"].is_sensitive());
+        assert_eq!(request.headers()["chatgpt-account-id"], "account-a");
+        assert_eq!(request.headers()[ACCEPT], "application/json");
+        assert_eq!(request.headers()[USER_AGENT], "codex-cli");
+        assert!(!format!("{request:?}").contains("synthetic-access-token"));
+        assert!(!quota_headers(&credentials(None))
+            .unwrap()
+            .contains_key("chatgpt-account-id"));
+        let credits_request = quota_client()
+            .unwrap()
+            .get(OfficialQuery::ResetCredits.url())
+            .headers(quota_headers(&credentials(Some("account-a"))).unwrap())
+            .build()
+            .unwrap();
+        assert_eq!(credits_request.method(), reqwest::Method::GET);
+        assert_eq!(credits_request.url().as_str(), RESET_CREDITS_URL);
+        assert_eq!(credits_request.url().scheme(), "https");
+        assert_eq!(credits_request.url().host_str(), Some("chatgpt.com"));
+        assert!(credits_request.headers()[AUTHORIZATION].is_sensitive());
+        assert!(credits_request.headers()["chatgpt-account-id"].is_sensitive());
+        assert!(!format!("{credits_request:?}").contains("synthetic-access-token"));
+    }
+
+    #[test]
+    fn empty_or_injected_credentials_fail_without_revealing_content() {
+        let mut empty = credentials(None);
+        empty.access_token = "  ".to_owned();
+        assert!(quota_headers(&empty)
+            .unwrap_err()
+            .to_string()
+            .contains("尚未登录"));
+        let mut invalid = credentials(None);
+        invalid.access_token = "private-secret\r\nInjected: true".to_owned();
+        let error = quota_headers(&invalid).unwrap_err().to_string();
+        assert!(!error.contains("private-secret"));
+        assert!(!error.contains("Injected"));
+        invalid = credentials(Some("private-account\r\nInjected: true"));
+        let error = quota_headers(&invalid).unwrap_err().to_string();
+        assert!(!error.contains("private-account"));
+        assert!(error.contains("账号标识无效"));
+    }
+
+    #[test]
+    fn error_statuses_have_safe_actionable_messages() {
+        for query in [OfficialQuery::Quota, OfficialQuery::ResetCredits] {
+            assert!(check_status(StatusCode::OK, query).is_ok());
+            for (status, expected) in [
+                (401, "重新登录"),
+                (403, "检查网络"),
+                (429, "过于频繁"),
+                (302, "重定向"),
+                (503, "HTTP 503"),
+            ] {
+                let error = check_status(StatusCode::from_u16(status).unwrap(), query)
+                    .unwrap_err()
+                    .to_string();
+                assert!(error.contains(expected));
+                assert!(error.contains(query.label()));
+            }
+        }
+    }
+
+    #[test]
+    fn body_limit_applies_even_without_or_with_false_content_length() {
+        assert_eq!(read_bounded_body(&b"{}"[..], Some(2)).unwrap(), b"{}");
+        let large = vec![b'x'; MAX_RESPONSE_BYTES + 1];
+        for content_length in [None, Some(1), Some(large.len() as u64)] {
+            assert!(read_bounded_body(&large[..], content_length)
+                .unwrap_err()
+                .to_string()
+                .contains("响应过大"));
+        }
+    }
+
+    #[test]
+    fn malformed_response_never_enters_error_text() {
+        let error = parse_quota_response(
+            b"server accidentally returned private-secret-token",
+            "official-profile-a",
+            &credentials(None),
+            checked_at(),
+        )
+        .unwrap_err()
+        .to_string();
+        assert!(error.contains("格式无法识别"));
+        assert!(!error.contains("private-secret-token"));
+    }
+
+    #[test]
+    fn credential_change_rejects_stale_result_for_token_account_or_email() {
+        let original = credentials(Some("account-a"));
+        let fingerprint = credential_fingerprint(&original);
+        assert!(ensure_same_credentials(fingerprint, &credentials(Some("account-a"))).is_ok());
+        for field in ["token", "account", "email"] {
+            let mut changed = credentials(Some("account-a"));
+            match field {
+                "token" => changed.access_token = "private-replacement-token".into(),
+                "account" => changed.account_id = Some("account-b".into()),
+                _ => changed.email = Some("changed@example.test".into()),
+            }
+            let error = ensure_same_credentials(fingerprint, &changed)
+                .unwrap_err()
+                .to_string();
+            assert!(error.contains("登录信息已变化"));
+            assert!(!error.contains("private-replacement-token"));
+            assert!(!error.contains("account-b"));
+            assert!(!error.contains("changed@example.test"));
+        }
+    }
+
+    #[test]
+    fn serialized_snapshot_contains_only_display_fields_and_no_credentials() {
+        let snapshot = parse(
+            json!({"plan_type":"team","rate_limit":{"primary_window":{"used_percent":40,"limit_window_seconds":18000}}}),
+            Some("account-a"),
+        );
+        let value = serde_json::to_value(&snapshot).unwrap();
+        assert_eq!(value["profileId"], "official-profile-a");
+        assert_eq!(value["planType"], "team");
+        assert_eq!(value["limits"][0]["windows"][0]["remainingPercent"], 60.0);
+        let serialized = value.to_string();
+        assert!(!serialized.contains("access_token"));
+        assert!(!serialized.contains("synthetic-access-token"));
+        assert!(!serialized.contains("account-a"));
+    }
+
+    #[test]
+    fn reset_credits_uses_available_count_and_returns_no_credit_details() {
+        let raw = json!({
+            "available_count": 3,
+            "total_earned_count": 0,
+            "credits": [{"id":"private-credit-id", "status":"available", "title":"private-credit-title"}],
+            "immediate_reset_purchase_eligible": true
+        });
+        let snapshot = parse_reset_credits_response(
+            &serde_json::to_vec(&raw).unwrap(),
+            "official-profile-a",
+            checked_at(),
+        )
+        .unwrap();
+        assert_eq!(
+            serde_json::to_value(snapshot).unwrap(),
+            json!({
+                "profileId":"official-profile-a",
+                "availableCount":3,
+                "checkedAt":"2026-09-09T03:00:00+00:00"
+            })
+        );
+        let zero = parse_reset_credits_response(
+            br#"{"available_count":0,"credits":[{"status":"available"}]}"#,
+            "official-profile-a",
+            checked_at(),
+        )
+        .unwrap();
+        assert_eq!(zero.available_count, 0);
+    }
+
+    #[test]
+    fn reset_credits_unknown_or_invalid_counts_are_not_reported_as_zero() {
+        for raw in [
+            "{}",
+            "null",
+            r#"{"available_count":null}"#,
+            r#"{"available_count":-1}"#,
+            r#"{"available_count":1.5}"#,
+            r#"{"available_count":"3"}"#,
+            r#"{"available_count":true}"#,
+            r#"{"available_count":4294967296}"#,
+            "private-malformed-response",
+        ] {
+            let error =
+                parse_reset_credits_response(raw.as_bytes(), "official-profile-a", checked_at())
+                    .unwrap_err()
+                    .to_string();
+            assert!(error.contains("重置次数响应格式无法识别"));
+            assert!(!error.contains("private-malformed-response"));
+        }
+    }
+
+    fn query_fixture(label: &str) -> std::path::PathBuf {
+        let dir = std::env::temp_dir().join(format!(
+            "codex-x-official-query-{label}-{}",
+            std::process::id()
+        ));
+        let _ = std::fs::remove_dir_all(&dir);
+        std::fs::create_dir_all(&dir).unwrap();
+        crate::file_io::write_text(
+            &crate::config_path(&dir),
+            "model_provider = \"openai\"\nmodel = \"synthetic-model\"\n",
+        )
+        .unwrap();
+        crate::file_io::write_json(
+            &crate::auth_path(&dir),
+            &json!({
+                "auth_mode":"chatgpt", "tokens":{
+                    "access_token":"synthetic-query-token", "account_id":"synthetic-account"
+                }
+            }),
+        )
+        .unwrap();
+        dir
+    }
+
+    #[test]
+    fn quota_and_reset_queries_overlap_without_holding_the_live_config_lock() {
+        use super::super::official_profiles::DEFAULT_OFFICIAL_PROFILE_ID;
+        use std::sync::mpsc;
+
+        let _db_guard = crate::app_db::test_db_guard();
+        let dir = query_fixture("parallel");
+        // Initialize the test database before starting the two independent reads.
+        read_query_credentials(&dir, DEFAULT_OFFICIAL_PROFILE_ID).unwrap();
+        let (started_tx, started_rx) = mpsc::channel();
+        let (quota_release_tx, quota_release_rx) = mpsc::channel();
+        let (credits_release_tx, credits_release_rx) = mpsc::channel();
+        std::thread::scope(|scope| {
+            let quota_started = started_tx.clone();
+            let quota_dir = &dir;
+            let quota = scope.spawn(move || {
+                read_official_snapshot(
+                    quota_dir,
+                    DEFAULT_OFFICIAL_PROFILE_ID,
+                    |_| {
+                        quota_started.send("quota").unwrap();
+                        quota_release_rx
+                            .recv_timeout(Duration::from_secs(5))
+                            .unwrap();
+                        Ok(b"{}".to_vec())
+                    },
+                    parse_quota_response,
+                )
+            });
+            let credits_dir = &dir;
+            let credits = scope.spawn(move || {
+                read_official_snapshot(
+                    credits_dir,
+                    DEFAULT_OFFICIAL_PROFILE_ID,
+                    |_| {
+                        started_tx.send("credits").unwrap();
+                        credits_release_rx
+                            .recv_timeout(Duration::from_secs(5))
+                            .unwrap();
+                        Ok(br#"{"available_count":3}"#.to_vec())
+                    },
+                    |bytes, id, _, time| parse_reset_credits_response(bytes, id, time),
+                )
+            });
+            // Both requests must start before either can finish. A lock held over
+            // the simulated network wait would make this fail instead of hang.
+            let first = started_rx.recv_timeout(Duration::from_secs(3)).unwrap();
+            let second = started_rx.recv_timeout(Duration::from_secs(3)).unwrap();
+            assert_ne!(first, second);
+            drop(acquire_live_config_lock(&dir).unwrap());
+            quota_release_tx.send(()).unwrap();
+            credits_release_tx.send(()).unwrap();
+            assert_eq!(
+                quota.join().unwrap().unwrap().profile_id,
+                DEFAULT_OFFICIAL_PROFILE_ID
+            );
+            assert_eq!(credits.join().unwrap().unwrap().available_count, 3);
+        });
+        std::fs::remove_dir_all(dir).unwrap();
+    }
+
+    #[test]
+    fn reset_query_rejects_login_replaced_during_request() {
+        use super::super::official_profiles::DEFAULT_OFFICIAL_PROFILE_ID;
+
+        let _db_guard = crate::app_db::test_db_guard();
+        let dir = query_fixture("changed-login");
+        let error = read_official_snapshot(
+            &dir, DEFAULT_OFFICIAL_PROFILE_ID,
+            |_| {
+                let _guard = acquire_live_config_lock(&dir).unwrap();
+                crate::file_io::write_json(&crate::auth_path(&dir), &json!({
+                    "auth_mode":"chatgpt", "tokens":{
+                        "access_token":"synthetic-replacement-token", "account_id":"synthetic-account"
+                    }
+                })).unwrap();
+                Ok(br#"{"available_count":3}"#.to_vec())
+            },
+            |bytes, id, _, time| parse_reset_credits_response(bytes, id, time),
+        ).unwrap_err().to_string();
+        assert!(error.contains("登录信息已变化"));
+        assert!(!error.contains("synthetic-replacement-token"));
+        std::fs::remove_dir_all(dir).unwrap();
+    }
+}

apps/desktop/src-tauri/src/providers/selection.rs

@@ -0,0 +1,204 @@
+use crate::error::{CodexxError, Result};
+use crate::now_rfc3339;
+use crate::paths::normalized_path_scope;
+use rusqlite::{params, Connection, OptionalExtension};
+use std::collections::HashSet;
+use std::path::Path;
+
+pub(super) fn selected_provider_id_on_connection(
+    conn: &Connection,
+    codex_dir: &Path,
+) -> Result<Option<String>> {
+    conn.query_row(
+        "SELECT provider_id
+         FROM active_provider_selections
+         WHERE codex_dir = ?1",
+        [normalized_path_scope(codex_dir)],
+        |row| row.get(0),
+    )
+    .optional()
+    .map_err(|error| CodexxError::Database(error.to_string()))
+}
+
+pub(crate) fn remember_active_provider_on_connection(
+    conn: &Connection,
+    codex_dir: &Path,
+    provider_id: &str,
+) -> Result<()> {
+    let provider_id = provider_id.trim();
+    if provider_id.is_empty() {
+        return Err(CodexxError::Config("当前供应商 ID 不能为空".to_string()));
+    }
+    let exists = conn
+        .query_row(
+            "SELECT EXISTS(SELECT 1 FROM providers WHERE id = ?1)",
+            [provider_id],
+            |row| row.get::<_, bool>(0),
+        )
+        .map_err(|error| CodexxError::Database(error.to_string()))?;
+    if !exists {
+        return Err(CodexxError::Config(format!(
+            "无法记录当前供应商，未找到 ID {provider_id}"
+        )));
+    }
+    conn.execute(
+        "INSERT INTO active_provider_selections (codex_dir, provider_id, updated_at)
+         VALUES (?1, ?2, ?3)
+         ON CONFLICT(codex_dir) DO UPDATE SET
+            provider_id = excluded.provider_id,
+            updated_at = excluded.updated_at",
+        params![normalized_path_scope(codex_dir), provider_id, now_rfc3339()],
+    )
+    .map_err(|error| CodexxError::Database(error.to_string()))?;
+    Ok(())
+}
+
+pub(crate) fn clear_active_provider_on_connection(
+    conn: &Connection,
+    codex_dir: &Path,
+) -> Result<()> {
+    conn.execute(
+        "DELETE FROM active_provider_selections WHERE codex_dir = ?1",
+        [normalized_path_scope(codex_dir)],
+    )
+    .map_err(|error| CodexxError::Database(error.to_string()))?;
+    Ok(())
+}
+
+pub(crate) fn clear_provider_selections_on_connection(
+    conn: &Connection,
+    provider_id: &str,
+) -> Result<()> {
+    conn.execute(
+        "DELETE FROM active_provider_selections WHERE provider_id = ?1",
+        [provider_id],
+    )
+    .map_err(|error| CodexxError::Database(error.to_string()))?;
+    Ok(())
+}
+
+pub(crate) fn reconcile_active_provider_on_connection(
+    conn: &Connection,
+    codex_dir: &Path,
+    candidate_ids: &[String],
+) -> Result<Option<String>> {
+    let candidates = candidate_ids
+        .iter()
+        .map(|id| id.trim())
+        .filter(|id| !id.is_empty())
+        .collect::<HashSet<_>>();
+    let selected = selected_provider_id_on_connection(conn, codex_dir)?;
+    if let Some(selected) = selected.as_deref() {
+        if candidates.contains(selected) {
+            return Ok(Some(selected.to_string()));
+        }
+        clear_active_provider_on_connection(conn, codex_dir)?;
+    }
+
+    if candidates.len() != 1 {
+        return Ok(None);
+    }
+    let provider_id = candidates
+        .into_iter()
+        .next()
+        .expect("one candidate must be present");
+    remember_active_provider_on_connection(conn, codex_dir, provider_id)?;
+    Ok(Some(provider_id.to_string()))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::path::PathBuf;
+
+    fn test_connection() -> Connection {
+        let conn = Connection::open_in_memory().expect("open selection test database");
+        conn.execute_batch(
+            "CREATE TABLE providers (id TEXT PRIMARY KEY);
+             CREATE TABLE active_provider_selections (
+                codex_dir TEXT PRIMARY KEY,
+                provider_id TEXT NOT NULL,
+                updated_at TEXT NOT NULL
+             );
+             INSERT INTO providers (id) VALUES ('original'), ('copy'), ('other');",
+        )
+        .expect("create selection test schema");
+        conn
+    }
+
+    fn scope(name: &str) -> PathBuf {
+        std::env::temp_dir().join(format!("codex-x-selection-{name}"))
+    }
+
+    #[test]
+    fn exact_duplicate_does_not_replace_the_remembered_current_provider() {
+        let conn = test_connection();
+        let codex_dir = scope("duplicate");
+        remember_active_provider_on_connection(&conn, &codex_dir, "original")
+            .expect("remember original provider");
+
+        let active = reconcile_active_provider_on_connection(
+            &conn,
+            &codex_dir,
+            &["original".to_string(), "copy".to_string()],
+        )
+        .expect("reconcile duplicate profiles");
+
+        assert_eq!(active.as_deref(), Some("original"));
+    }
+
+    #[test]
+    fn selections_are_independent_for_each_codex_directory() {
+        let conn = test_connection();
+        let first = scope("first");
+        let second = scope("second");
+        remember_active_provider_on_connection(&conn, &first, "original")
+            .expect("remember first selection");
+        remember_active_provider_on_connection(&conn, &second, "copy")
+            .expect("remember second selection");
+        let candidates = ["original".to_string(), "copy".to_string()];
+
+        assert_eq!(
+            reconcile_active_provider_on_connection(&conn, &first, &candidates)
+                .expect("reconcile first selection")
+                .as_deref(),
+            Some("original")
+        );
+        assert_eq!(
+            reconcile_active_provider_on_connection(&conn, &second, &candidates)
+                .expect("reconcile second selection")
+                .as_deref(),
+            Some("copy")
+        );
+    }
+
+    #[test]
+    fn stale_selection_falls_back_only_when_the_live_match_is_unique() {
+        let conn = test_connection();
+        let codex_dir = scope("stale");
+        remember_active_provider_on_connection(&conn, &codex_dir, "original")
+            .expect("remember stale selection");
+
+        assert_eq!(
+            reconcile_active_provider_on_connection(&conn, &codex_dir, &["other".to_string()])
+                .expect("reconcile unique replacement")
+                .as_deref(),
+            Some("other")
+        );
+        assert_eq!(
+            selected_provider_id_on_connection(&conn, &codex_dir)
+                .expect("read repaired selection")
+                .as_deref(),
+            Some("other")
+        );
+
+        assert!(
+            reconcile_active_provider_on_connection(&conn, &codex_dir, &[])
+                .expect("clear unmatched selection")
+                .is_none()
+        );
+        assert!(selected_provider_id_on_connection(&conn, &codex_dir)
+            .expect("read cleared selection")
+            .is_none());
+    }
+}

apps/desktop/src-tauri/src/providers/transport.rs

@@ -0,0 +1,107 @@
+use toml_edit::{value, Item, TableLike};
+
+/// Match the official API exactly. A proxy that forwards DeepSeek may support
+/// WebSockets independently, so model names and partial host matches are unsafe.
+pub(crate) fn is_deepseek_http_endpoint(base_url: &str) -> bool {
+    reqwest::Url::parse(base_url.trim()).is_ok_and(|url| {
+        matches!(url.scheme(), "http" | "https") && url.host_str() == Some("api.deepseek.com")
+    })
+}
+
+/// A provider's WebSocket capability belongs to its endpoint, not the common
+/// Codex config inherited when creating a provider. Call before replacing URL.
+pub(super) fn configure_third_party_transport(
+    table: &mut dyn TableLike,
+    base_url: &str,
+    own_template: bool,
+) {
+    let same_endpoint = table
+        .get("base_url")
+        .and_then(Item::as_str)
+        .is_some_and(|old| {
+            super::store::canonical_provider_base_url(old)
+                == super::store::canonical_provider_base_url(base_url)
+        });
+    let preserve_explicit = own_template
+        && same_endpoint
+        && !is_deepseek_http_endpoint(base_url)
+        && table
+            .get("supports_websockets")
+            .and_then(Item::as_bool)
+            .is_some();
+    if !preserve_explicit {
+        // Explicit false also overrides Codex's built-in provider defaults if a
+        // user-chosen provider ID happens to shadow a built-in provider.
+        let decor = table
+            .get("supports_websockets")
+            .and_then(Item::as_value)
+            .map(|value| value.decor().clone());
+        let mut replacement = value(false);
+        if let Some(decor) = decor {
+            *replacement
+                .as_value_mut()
+                .expect("boolean value")
+                .decor_mut() = decor;
+        }
+        table.insert("supports_websockets", replacement);
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use toml_edit::Table;
+
+    #[test]
+    fn deepseek_host_matching_does_not_disable_proxies() {
+        assert!(is_deepseek_http_endpoint("https://api.deepseek.com/v1/"));
+        assert!(is_deepseek_http_endpoint("HTTPS://API.DEEPSEEK.COM"));
+        for endpoint in [
+            "https://deepseek.proxy.example/v1",
+            "https://api.deepseek.com.proxy.example/v1",
+            "https://api.deepseek.com@proxy.example/v1",
+            "https://proxy.example/api.deepseek.com",
+            "invalid api.deepseek.com",
+        ] {
+            assert!(!is_deepseek_http_endpoint(endpoint), "{endpoint}");
+        }
+    }
+
+    #[test]
+    fn endpoint_ownership_controls_websocket_inheritance() {
+        for (source, destination, own, expected) in [
+            (
+                "https://proxy.example/v1",
+                "https://proxy.example/v1/",
+                true,
+                true,
+            ),
+            (
+                "https://proxy.example/v1",
+                "https://proxy.example/v1",
+                false,
+                false,
+            ),
+            (
+                "https://old.example/v1",
+                "https://new.example/v1",
+                true,
+                false,
+            ),
+            (
+                "https://api.deepseek.com",
+                "https://api.deepseek.com",
+                true,
+                false,
+            ),
+        ] {
+            let mut table = Table::new();
+            table["base_url"] = value(source);
+            table["supports_websockets"] = value(true);
+            table["request_max_retries"] = value(9);
+            configure_third_party_transport(&mut table, destination, own);
+            assert_eq!(table["supports_websockets"].as_bool(), Some(expected));
+            assert_eq!(table["request_max_retries"].as_integer(), Some(9));
+        }
+    }
+}

apps/desktop/src-tauri/src/remote.rs

@@ -0,0 +1,306 @@
+use crate::error::{CodexxError, Result};
+use std::sync::OnceLock;
+use std::time::Duration;
+
+const REMOTE_USER_AGENT: &str = "Codex-X";
+const REMOTE_TIMEOUT: Duration = Duration::from_secs(5);
+
+#[derive(Debug, Clone, Copy)]
+pub(crate) struct RemoteSource<'a> {
+    pub(crate) key: &'static str,
+    pub(crate) url: &'a str,
+    pub(crate) accept: Option<&'static str>,
+}
+
+impl<'a> RemoteSource<'a> {
+    pub(crate) const fn new(key: &'static str, url: &'a str, accept: Option<&'static str>) -> Self {
+        Self { key, url, accept }
+    }
+}
+
+pub(crate) fn ensure_crypto_provider() {
+    static CRYPTO_PROVIDER: OnceLock<()> = OnceLock::new();
+    CRYPTO_PROVIDER.get_or_init(|| {
+        // Another TLS client may already have initialized the process-wide provider.
+        let _ = rustls::crypto::ring::default_provider().install_default();
+    });
+}
+
+pub(crate) fn remote_client() -> Result<reqwest::blocking::Client> {
+    ensure_crypto_provider();
+    reqwest::blocking::Client::builder()
+        .timeout(REMOTE_TIMEOUT)
+        .user_agent(REMOTE_USER_AGENT)
+        .build()
+        .map_err(|_| CodexxError::Config("网络客户端初始化失败".to_string()))
+}
+
+pub(crate) fn remote_request_error(
+    source: &RemoteSource<'_>,
+    error: &reqwest::Error,
+) -> CodexxError {
+    let reason = if error.is_timeout() {
+        "请求超时"
+    } else if error.is_connect() {
+        "网络连接失败"
+    } else {
+        "网络请求失败"
+    };
+    CodexxError::Config(format!("{} {reason}", source.key))
+}
+
+fn fetch_remote_text(source: &RemoteSource<'_>) -> Result<String> {
+    // A fresh client picks up proxy changes made while the app is running. Reqwest's
+    // system proxy resolver also handles proxy environment variables and NO_PROXY.
+    let client = remote_client()?;
+    let mut request = client.get(source.url);
+    if let Some(accept) = source.accept {
+        request = request.header(reqwest::header::ACCEPT, accept);
+    }
+    let response = request
+        .send()
+        .map_err(|error| remote_request_error(source, &error))?;
+    let status = response.status();
+    if !status.is_success() {
+        return Err(CodexxError::Config(format!(
+            "{} 请求失败（HTTP {}）",
+            source.key,
+            status.as_u16()
+        )));
+    }
+    response
+        .text()
+        .map_err(|_| CodexxError::Config(format!("{} 响应读取失败", source.key)))
+}
+
+pub(crate) fn fetch_first_valid<T, Parse>(sources: &[RemoteSource<'_>], parse: Parse) -> Result<T>
+where
+    Parse: FnMut(&RemoteSource<'_>, &str) -> Result<T>,
+{
+    fetch_first_valid_with(sources, fetch_remote_text, parse)
+}
+
+pub(crate) fn fetch_first_valid_with<T, Fetch, Parse>(
+    sources: &[RemoteSource<'_>],
+    mut fetch: Fetch,
+    mut parse: Parse,
+) -> Result<T>
+where
+    Fetch: FnMut(&RemoteSource<'_>) -> Result<String>,
+    Parse: FnMut(&RemoteSource<'_>, &str) -> Result<T>,
+{
+    let mut errors = Vec::new();
+    for source in sources {
+        match fetch(source) {
+            Ok(body) if body.trim().is_empty() => {
+                errors.push(format!("{} 返回空内容", source.key));
+            }
+            Ok(body) => match parse(source, &body) {
+                Ok(value) => return Ok(value),
+                Err(error) => errors.push(format!("{}: {error}", source.key)),
+            },
+            Err(error) => errors.push(format!("{}: {error}", source.key)),
+        }
+    }
+
+    Err(CodexxError::Config(format!(
+        "远程内容获取失败{}",
+        if errors.is_empty() {
+            String::new()
+        } else {
+            format!("：{}", errors.join("；"))
+        }
+    )))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::io::{Read, Write};
+    use std::net::TcpListener;
+    use std::process::Command;
+    use std::thread;
+    use std::time::Instant;
+
+    const SOURCES: [RemoteSource<'static>; 2] = [
+        RemoteSource::new("cdn", "https://cdn.example.test", None),
+        RemoteSource::new("origin", "https://origin.example.test", None),
+    ];
+    const PROXY_TEST_URL: &str = "CODEXX_REMOTE_PROXY_TEST_URL";
+    const PROXY_TEST_BODY: &str = "CODEXX_REMOTE_PROXY_TEST_BODY";
+
+    fn clear_proxy_environment(command: &mut Command) {
+        for name in [
+            "ALL_PROXY",
+            "all_proxy",
+            "HTTPS_PROXY",
+            "https_proxy",
+            "HTTP_PROXY",
+            "http_proxy",
+            "NO_PROXY",
+            "no_proxy",
+            "REQUEST_METHOD",
+        ] {
+            command.env_remove(name);
+        }
+    }
+
+    fn serve_once(listener: TcpListener, body: &'static str) -> String {
+        listener
+            .set_nonblocking(true)
+            .expect("set listener nonblocking");
+        let started = Instant::now();
+        let (mut stream, _) = loop {
+            match listener.accept() {
+                Ok(connection) => break connection,
+                Err(error) if error.kind() == std::io::ErrorKind::WouldBlock => {
+                    assert!(
+                        started.elapsed() < Duration::from_secs(8),
+                        "proxy test connection timed out"
+                    );
+                    thread::sleep(Duration::from_millis(20));
+                }
+                Err(error) => panic!("accept proxy test connection: {error}"),
+            }
+        };
+        stream
+            .set_read_timeout(Some(Duration::from_secs(2)))
+            .expect("set read timeout");
+        let mut request = [0_u8; 8192];
+        let read = stream.read(&mut request).expect("read proxy request");
+        let response = format!(
+            "HTTP/1.1 200 OK\r\nContent-Length: {}\r\nConnection: close\r\n\r\n{body}",
+            body.len()
+        );
+        stream
+            .write_all(response.as_bytes())
+            .expect("write proxy response");
+        String::from_utf8_lossy(&request[..read]).into_owned()
+    }
+
+    fn run_proxy_test_child(url: &str, body: &str, configure: impl FnOnce(&mut Command)) {
+        let mut command = Command::new(std::env::current_exe().expect("current test executable"));
+        command.args([
+            "--exact",
+            "remote::tests::proxy_environment_child",
+            "--nocapture",
+        ]);
+        clear_proxy_environment(&mut command);
+        command.env(PROXY_TEST_URL, url).env(PROXY_TEST_BODY, body);
+        configure(&mut command);
+        let output = command.output().expect("run proxy test child");
+        assert!(
+            output.status.success(),
+            "proxy test child failed:\n{}",
+            String::from_utf8_lossy(&output.stderr)
+        );
+    }
+
+    #[test]
+    fn proxy_environment_child() {
+        let Ok(url) = std::env::var(PROXY_TEST_URL) else {
+            return;
+        };
+        let expected = std::env::var(PROXY_TEST_BODY).expect("proxy test body");
+        let source = RemoteSource::new("proxy test", &url, None);
+        assert_eq!(
+            fetch_remote_text(&source).expect("fetch test response"),
+            expected
+        );
+    }
+
+    #[test]
+    fn successful_source_stops_fallback_chain() {
+        let mut calls = Vec::new();
+        let value = fetch_first_valid_with(
+            &SOURCES,
+            |source| {
+                calls.push(source.key);
+                Ok("valid".to_string())
+            },
+            |_, body| Ok(body.to_string()),
+        )
+        .expect("first source succeeds");
+
+        assert_eq!(value, "valid");
+        assert_eq!(calls, ["cdn"]);
+    }
+
+    #[test]
+    fn empty_and_unparseable_responses_try_later_sources() {
+        let mut calls = Vec::new();
+        let value = fetch_first_valid_with(
+            &SOURCES,
+            |source| {
+                calls.push(source.key);
+                if source.key == "cdn" {
+                    Ok("   ".to_string())
+                } else {
+                    Ok("42".to_string())
+                }
+            },
+            |_, body| {
+                body.parse::<u32>()
+                    .map_err(|error| CodexxError::Config(error.to_string()))
+            },
+        )
+        .expect("origin succeeds after empty CDN response");
+
+        assert_eq!(value, 42);
+        assert_eq!(calls, ["cdn", "origin"]);
+    }
+
+    #[test]
+    fn remote_client_uses_lowercase_http_proxy() {
+        let listener = TcpListener::bind("127.0.0.1:0").expect("bind test proxy");
+        let proxy_url = format!("http://{}", listener.local_addr().unwrap());
+        let server = thread::spawn(move || serve_once(listener, "through proxy"));
+
+        run_proxy_test_child(
+            "http://remote.invalid/template.md",
+            "through proxy",
+            |command| {
+                command.env("http_proxy", proxy_url);
+            },
+        );
+
+        let request = server.join().expect("join proxy server");
+        assert!(request.starts_with("GET http://remote.invalid/template.md "));
+    }
+
+    #[test]
+    fn remote_client_respects_lowercase_no_proxy() {
+        let listener = TcpListener::bind("127.0.0.1:0").expect("bind test origin");
+        let origin_url = format!("http://{}/direct.md", listener.local_addr().unwrap());
+        let server = thread::spawn(move || serve_once(listener, "direct response"));
+
+        run_proxy_test_child(&origin_url, "direct response", |command| {
+            command
+                .env("HTTP_PROXY", "http://127.0.0.1:9")
+                .env("no_proxy", "127.0.0.1");
+        });
+
+        let request = server.join().expect("join origin server");
+        assert!(request.starts_with("GET /direct.md "));
+    }
+
+    #[test]
+    fn connection_errors_do_not_expose_request_or_proxy_details() {
+        remote_client().expect("initialize TLS provider");
+        let client = reqwest::blocking::Client::builder()
+            .no_proxy()
+            .timeout(Duration::from_millis(200))
+            .build()
+            .expect("build direct client");
+        let error = client
+            .get("http://127.0.0.1:0/private")
+            .send()
+            .expect_err("reserved port should fail");
+        let message = remote_request_error(&SOURCES[0], &error).to_string();
+
+        assert!(message.contains("cdn"));
+        assert!(!message.contains("127.0.0.1"));
+        assert!(!message.contains("private"));
+        assert!(!message.contains('@'));
+    }
+}

apps/desktop/src-tauri/src/sessions/app_server.rs

@@ -0,0 +1,251 @@
+use crate::error::Result;
+use crate::platform;
+use serde_json::{json, Value};
+use std::collections::HashSet;
+use std::io::{BufRead, BufReader, Write};
+use std::path::{Path, PathBuf};
+use std::process::{Child, Stdio};
+use std::sync::mpsc;
+use std::time::{Duration, Instant};
+
+#[derive(Debug, Default)]
+pub(super) struct OfficialSessionDeleteOutcome {
+    pub(super) deleted_ids: HashSet<String>,
+    pub(super) completed_roots: HashSet<String>,
+    pub(super) failed_roots: Vec<(String, String)>,
+}
+
+#[derive(Debug)]
+enum AppServerDeleteAttempt {
+    Success(OfficialSessionDeleteOutcome),
+    Unsupported(String),
+}
+
+fn send_app_server_message(
+    stdin: &mut impl Write,
+    value: &Value,
+) -> std::result::Result<(), String> {
+    let mut line = serde_json::to_vec(value).map_err(|error| error.to_string())?;
+    line.push(b'\n');
+    stdin.write_all(&line).map_err(|error| error.to_string())?;
+    stdin.flush().map_err(|error| error.to_string())
+}
+
+fn recv_app_server_message(
+    receiver: &mpsc::Receiver<std::io::Result<String>>,
+    deadline: Instant,
+) -> std::result::Result<Value, String> {
+    loop {
+        let remaining = deadline
+            .checked_duration_since(Instant::now())
+            .ok_or_else(|| "Codex App Server 响应超时".to_string())?;
+        let line = receiver
+            .recv_timeout(remaining)
+            .map_err(|error| format!("Codex App Server 响应失败: {error}"))?
+            .map_err(|error| format!("读取 Codex App Server 输出失败: {error}"))?;
+        if line.trim().is_empty() {
+            continue;
+        }
+        return serde_json::from_str(&line)
+            .map_err(|error| format!("解析 Codex App Server 输出失败: {error}"));
+    }
+}
+
+fn app_server_error(value: &Value) -> Option<(i64, String)> {
+    let error = value.get("error")?;
+    Some((
+        error
+            .get("code")
+            .and_then(Value::as_i64)
+            .unwrap_or_default(),
+        error
+            .get("message")
+            .and_then(Value::as_str)
+            .unwrap_or("Codex App Server 返回未知错误")
+            .to_string(),
+    ))
+}
+
+fn stop_app_server_child(child: &mut Child) {
+    let _ = child.kill();
+    let _ = child.wait();
+}
+
+fn run_app_server_delete_attempt(
+    mut child: Child,
+    codex_dir: &Path,
+    roots: &[String],
+) -> AppServerDeleteAttempt {
+    let Some(mut stdin) = child.stdin.take() else {
+        stop_app_server_child(&mut child);
+        return AppServerDeleteAttempt::Unsupported("Codex App Server stdin 不可用".to_string());
+    };
+    let Some(stdout) = child.stdout.take() else {
+        stop_app_server_child(&mut child);
+        return AppServerDeleteAttempt::Unsupported("Codex App Server stdout 不可用".to_string());
+    };
+    let (sender, receiver) = mpsc::channel();
+    let reader = std::thread::spawn(move || {
+        for line in BufReader::new(stdout).lines() {
+            if sender.send(line).is_err() {
+                break;
+            }
+        }
+    });
+
+    let result = (|| -> AppServerDeleteAttempt {
+        let initialize_id = 1i64;
+        let initialize = json!({
+            "id": initialize_id,
+            "method": "initialize",
+            "params": {
+                "clientInfo": {
+                    "name": "codex_x",
+                    "title": "Codex-X",
+                    "version": env!("CARGO_PKG_VERSION")
+                },
+                "capabilities": null
+            }
+        });
+        if let Err(error) = send_app_server_message(&mut stdin, &initialize) {
+            return AppServerDeleteAttempt::Unsupported(error);
+        }
+        let initialize_deadline = Instant::now() + Duration::from_secs(8);
+        loop {
+            let message = match recv_app_server_message(&receiver, initialize_deadline) {
+                Ok(message) => message,
+                Err(error) => return AppServerDeleteAttempt::Unsupported(error),
+            };
+            if message.get("id").and_then(Value::as_i64) != Some(initialize_id) {
+                continue;
+            }
+            if let Some((_, message)) = app_server_error(&message) {
+                return AppServerDeleteAttempt::Unsupported(message);
+            }
+            let Some(server_home) = message
+                .get("result")
+                .and_then(|value| value.get("codexHome"))
+                .and_then(Value::as_str)
+            else {
+                return AppServerDeleteAttempt::Unsupported(
+                    "Codex App Server 未返回 CODEX_HOME".to_string(),
+                );
+            };
+            let requested_home = codex_dir
+                .canonicalize()
+                .unwrap_or_else(|_| codex_dir.to_path_buf());
+            let returned_home = PathBuf::from(server_home)
+                .canonicalize()
+                .unwrap_or_else(|_| PathBuf::from(server_home));
+            if requested_home != returned_home {
+                return AppServerDeleteAttempt::Unsupported(format!(
+                    "Codex App Server 使用了不同的 CODEX_HOME: {}",
+                    returned_home.display()
+                ));
+            }
+            break;
+        }
+        if let Err(error) = send_app_server_message(&mut stdin, &json!({"method": "initialized"})) {
+            return AppServerDeleteAttempt::Unsupported(error);
+        }
+
+        let mut outcome = OfficialSessionDeleteOutcome::default();
+        'delete_roots: for (index, root) in roots.iter().enumerate() {
+            let request_id = 1000 + index as i64;
+            if let Err(error) = send_app_server_message(
+                &mut stdin,
+                &json!({
+                    "id": request_id,
+                    "method": "thread/delete",
+                    "params": { "threadId": root }
+                }),
+            ) {
+                for pending in &roots[index..] {
+                    outcome.failed_roots.push((pending.clone(), error.clone()));
+                }
+                break 'delete_roots;
+            }
+            let deadline = Instant::now() + Duration::from_secs(60);
+            loop {
+                let message = match recv_app_server_message(&receiver, deadline) {
+                    Ok(message) => message,
+                    Err(error) => {
+                        for pending in &roots[index..] {
+                            outcome.failed_roots.push((pending.clone(), error.clone()));
+                        }
+                        break 'delete_roots;
+                    }
+                };
+                if message.get("method").and_then(Value::as_str) == Some("thread/deleted") {
+                    if let Some(id) = message
+                        .get("params")
+                        .and_then(|value| value.get("threadId"))
+                        .and_then(Value::as_str)
+                    {
+                        outcome.deleted_ids.insert(id.to_string());
+                    }
+                }
+                if message.get("id").and_then(Value::as_i64) == Some(request_id) {
+                    if let Some((code, error)) = app_server_error(&message) {
+                        let lower = error.to_ascii_lowercase();
+                        if code == -32601 {
+                            return AppServerDeleteAttempt::Unsupported(error);
+                        }
+                        if code == -32600
+                            && (lower.contains("no rollout")
+                                || lower.contains("not found")
+                                || lower.contains("does not exist"))
+                        {
+                            outcome.completed_roots.insert(root.clone());
+                            break;
+                        }
+                        outcome.failed_roots.push((root.clone(), error));
+                        break;
+                    }
+                    outcome.completed_roots.insert(root.clone());
+                    break;
+                }
+            }
+        }
+        AppServerDeleteAttempt::Success(outcome)
+    })();
+
+    drop(stdin);
+    stop_app_server_child(&mut child);
+    let _ = reader.join();
+    result
+}
+
+pub(super) fn delete_sessions_via_codex_app_server(
+    codex_dir: &Path,
+    roots: &[String],
+) -> Result<Option<OfficialSessionDeleteOutcome>> {
+    let mut unsupported_messages = Vec::new();
+    for program in platform::codex_executable_candidates() {
+        let is_bare_command = program.components().count() == 1;
+        if !is_bare_command && !program.is_file() {
+            continue;
+        }
+        let mut command = platform::program_command(&program, &["app-server", "--stdio"]);
+        command
+            .env("CODEX_HOME", codex_dir)
+            .stdin(Stdio::piped())
+            .stdout(Stdio::piped())
+            .stderr(Stdio::null());
+        let child = match command.spawn() {
+            Ok(child) => child,
+            Err(error) => {
+                unsupported_messages.push(format!("{}: {error}", program.display()));
+                continue;
+            }
+        };
+        match run_app_server_delete_attempt(child, codex_dir, roots) {
+            AppServerDeleteAttempt::Success(outcome) => return Ok(Some(outcome)),
+            AppServerDeleteAttempt::Unsupported(message) => {
+                unsupported_messages.push(format!("{}: {message}", program.display()));
+            }
+        }
+    }
+    let _ = unsupported_messages;
+    Ok(None)
+}

apps/desktop/src-tauri/src/sessions/backup.rs

@@ -0,0 +1,224 @@
+use crate::error::{CodexxError, Result};
+use crate::file_io::{ensure_directory, io_err, write_json};
+use chrono::Local;
+use rusqlite::{Connection, OpenFlags};
+use serde_json::{json, Value};
+use std::fs;
+use std::path::{Path, PathBuf};
+use std::time::{Duration, Instant};
+
+#[derive(Debug, Clone)]
+pub(super) struct BackupSnapshot {
+    live_path: PathBuf,
+    backup_path: PathBuf,
+    existed: bool,
+}
+
+#[derive(Debug)]
+pub(super) struct ProviderSyncBackup {
+    pub(super) dir: PathBuf,
+}
+
+pub(crate) fn provider_sync_backup_root(codex_dir: &Path) -> PathBuf {
+    codex_dir.join("backups_state").join("provider-sync")
+}
+
+fn backup_relative_path(codex_dir: &Path, source: &Path) -> PathBuf {
+    match source.strip_prefix(codex_dir) {
+        Ok(relative) if !relative.as_os_str().is_empty() => relative.to_path_buf(),
+        _ => {
+            use sha2::{Digest, Sha256};
+            let digest = Sha256::digest(source.to_string_lossy().as_bytes());
+            let key = digest[..8]
+                .iter()
+                .map(|byte| format!("{byte:02x}"))
+                .collect::<String>();
+            PathBuf::from("external").join(key).join(
+                source
+                    .file_name()
+                    .unwrap_or_else(|| std::ffi::OsStr::new("file")),
+            )
+        }
+    }
+}
+
+fn backup_target_path(codex_dir: &Path, backup_dir: &Path, source: &Path) -> Result<PathBuf> {
+    let target = backup_dir.join(backup_relative_path(codex_dir, source));
+    if target == source {
+        return Err(CodexxError::Config(format!(
+            "拒绝将备份写回源文件: {}",
+            source.display()
+        )));
+    }
+    Ok(target)
+}
+
+fn copy_file_to_backup(
+    codex_dir: &Path,
+    backup_dir: &Path,
+    source: &Path,
+) -> Result<BackupSnapshot> {
+    let target = backup_target_path(codex_dir, backup_dir, source)?;
+    let existed = source.exists();
+    if existed {
+        if let Some(parent) = target.parent() {
+            ensure_directory(parent)?;
+        }
+        fs::copy(source, &target).map_err(|e| io_err(&target, e))?;
+    }
+    Ok(BackupSnapshot {
+        live_path: source.to_path_buf(),
+        backup_path: target,
+        existed,
+    })
+}
+
+pub(crate) fn backup_sqlite_to_backup(
+    codex_dir: &Path,
+    backup_dir: &Path,
+    source: &Path,
+) -> Result<()> {
+    use rusqlite::backup::{Backup, StepResult};
+
+    if !source.exists() {
+        return Err(CodexxError::Database(format!(
+            "SQLite 快照源不存在: {}",
+            source.display()
+        )));
+    }
+    let target = backup_target_path(codex_dir, backup_dir, source)?;
+    if let Some(parent) = target.parent() {
+        ensure_directory(parent)?;
+    }
+    let from = Connection::open_with_flags(
+        source,
+        OpenFlags::SQLITE_OPEN_READ_ONLY | OpenFlags::SQLITE_OPEN_NO_MUTEX,
+    )
+    .map_err(|e| {
+        CodexxError::Database(format!("打开 SQLite 备份源失败 {}: {e}", source.display()))
+    })?;
+    from.busy_timeout(Duration::from_secs(5))
+        .map_err(|e| CodexxError::Database(e.to_string()))?;
+    let mut to = Connection::open(&target).map_err(|e| {
+        CodexxError::Database(format!("创建 SQLite 备份失败 {}: {e}", target.display()))
+    })?;
+    let deadline = Instant::now() + Duration::from_secs(15);
+    {
+        let backup = Backup::new(&from, &mut to)
+            .map_err(|e| CodexxError::Database(format!("初始化 SQLite 快照失败: {e}")))?;
+        loop {
+            if Instant::now() >= deadline {
+                return Err(CodexxError::Database(format!(
+                    "SQLite 快照超时: {}",
+                    source.display()
+                )));
+            }
+            match backup
+                .step(128)
+                .map_err(|e| CodexxError::Database(format!("写入 SQLite 快照失败: {e}")))?
+            {
+                StepResult::Done => break,
+                StepResult::More => {}
+                StepResult::Busy | StepResult::Locked => {
+                    std::thread::sleep(Duration::from_millis(50));
+                }
+                _ => {}
+            }
+        }
+    }
+    let quick_check: String = to
+        .query_row("PRAGMA quick_check", [], |row| row.get(0))
+        .map_err(|e| CodexxError::Database(format!("校验 SQLite 备份失败: {e}")))?;
+    if quick_check != "ok" {
+        return Err(CodexxError::Database(format!(
+            "SQLite 备份校验失败 {}: {quick_check}",
+            target.display()
+        )));
+    }
+    if !target.is_file() {
+        return Err(CodexxError::Database(format!(
+            "SQLite 快照未生成: {}",
+            target.display()
+        )));
+    }
+    Ok(())
+}
+
+pub(crate) fn prune_provider_sync_backups(codex_dir: &Path) -> Result<()> {
+    let root = provider_sync_backup_root(codex_dir);
+    if !root.exists() {
+        return Ok(());
+    }
+    let mut dirs = Vec::new();
+    for entry in fs::read_dir(&root).map_err(|e| io_err(&root, e))? {
+        let entry = entry.map_err(|e| io_err(&root, e))?;
+        let path = entry.path();
+        let metadata_path = path.join("metadata.json");
+        if !path.is_dir() || !metadata_path.exists() {
+            continue;
+        }
+        let is_v2_provider_sync_backup = fs::read_to_string(&metadata_path)
+            .ok()
+            .and_then(|text| serde_json::from_str::<Value>(&text).ok())
+            .is_some_and(|metadata| {
+                metadata.get("managedBy").and_then(Value::as_str)
+                    == Some("Codex-X provider sync v2")
+            });
+        if is_v2_provider_sync_backup {
+            dirs.push(path);
+        }
+    }
+    dirs.sort_by(|a, b| b.file_name().cmp(&a.file_name()));
+    for path in dirs.into_iter().skip(5) {
+        let _ = fs::remove_dir_all(path);
+    }
+    Ok(())
+}
+
+pub(super) fn create_provider_sync_backup(
+    codex_dir: &Path,
+    target_provider: &str,
+    changed_rollouts: &[PathBuf],
+    sqlite_paths: &[PathBuf],
+) -> Result<ProviderSyncBackup> {
+    let root = provider_sync_backup_root(codex_dir);
+    ensure_directory(&root)?;
+    let mut backup_dir = root.join(Local::now().format("%Y%m%d%H%M%S").to_string());
+    let mut suffix = 0;
+    while backup_dir.exists() {
+        suffix += 1;
+        backup_dir = root.join(format!("{}-{suffix}", Local::now().format("%Y%m%d%H%M%S")));
+    }
+    ensure_directory(&backup_dir)?;
+
+    let mut snapshots = Vec::new();
+    for path in sqlite_paths {
+        backup_sqlite_to_backup(codex_dir, &backup_dir, path)?;
+        snapshots.push(BackupSnapshot {
+            live_path: path.clone(),
+            backup_path: backup_target_path(codex_dir, &backup_dir, path)?,
+            existed: path.exists(),
+        });
+    }
+    for path in changed_rollouts {
+        snapshots.push(copy_file_to_backup(codex_dir, &backup_dir, path)?);
+    }
+    write_json(
+        &backup_dir.join("metadata.json"),
+        &json!({
+            "version": 1,
+            "namespace": "provider-sync",
+            "managedBy": "Codex-X provider sync v2",
+            "codexHome": codex_dir.display().to_string(),
+            "targetProvider": target_provider,
+            "createdAt": Local::now().to_rfc3339(),
+            "changedRolloutFiles": changed_rollouts.iter().map(|p| p.display().to_string()).collect::<Vec<_>>(),
+            "snapshots": snapshots.iter().map(|snapshot| json!({
+                "livePath": snapshot.live_path.display().to_string(),
+                "backupPath": snapshot.backup_path.display().to_string(),
+                "existed": snapshot.existed,
+            })).collect::<Vec<_>>(),
+        }),
+    )?;
+    Ok(ProviderSyncBackup { dir: backup_dir })
+}

apps/desktop/src-tauri/src/sessions/global_state.rs

@@ -0,0 +1,14 @@
+pub(super) fn normalize_workspace_path(value: &str) -> Option<String> {
+    let trimmed = value.trim();
+    if trimmed.is_empty() {
+        return None;
+    }
+    let lower = trimmed.to_ascii_lowercase();
+    if lower.starts_with(r"\\?\unc\") {
+        return Some(format!(r"\\{}", trimmed[8..].replace('/', r"\")));
+    }
+    if let Some(stripped) = trimmed.strip_prefix(r"\\?\") {
+        return Some(stripped.replace('\\', "/"));
+    }
+    Some(trimmed.to_string())
+}

apps/desktop/src-tauri/src/sessions/mod.rs

@@ -0,0 +1,31 @@
+mod app_server;
+mod backup;
+mod catalog;
+mod delete;
+mod export;
+mod global_state;
+mod storage;
+mod sync;
+mod transaction;
+mod types;
+
+#[cfg(test)]
+pub(crate) use backup::{
+    backup_sqlite_to_backup, provider_sync_backup_root, prune_provider_sync_backups,
+};
+#[cfg(test)]
+pub(crate) use delete::{active_session_ids_present, hard_delete_sessions_locally};
+pub(crate) use delete::{delete_codex_sessions_inner, SessionDeleteInput, SessionDeleteResult};
+pub(crate) use export::{export_codex_sessions_inner, SessionExportResult};
+#[cfg(test)]
+pub(crate) use storage::{
+    apply_session_changes, list_session_previews, restore_session_changes, scan_rollouts,
+    scan_sqlite, sqlite_session_db_paths,
+};
+pub(crate) use storage::{
+    session_project_title, session_titles_by_id, source_kind_is_internal, sqlite_candidate_paths,
+    sqlite_candidate_paths_with_timeout, thread_source_is_internal, usage_thread_identities,
+    UsageThreadIdentity,
+};
+pub(crate) use sync::{session_sync_status_inner, sync_sessions_provider_inner};
+pub(crate) use types::{SessionSyncResult, SessionSyncStatus};

apps/desktop/src-tauri/src/sessions/transaction.rs

@@ -0,0 +1,496 @@
+use super::catalog::{
+    apply_catalog_updates, catalog_columns, create_catalog_rollback_tables,
+    restore_catalog_updates, CatalogRepairThread,
+};
+use super::storage::{
+    apply_session_changes, restore_session_changes, rollout_path_has_syncable_identity,
+    rollout_text_is_internal, sqlite_subagent_thread_ids,
+};
+use super::types::{RolloutScan, SessionFileChange};
+use crate::error::{CodexxError, Result};
+use crate::file_io::io_err;
+use crate::sqlite_utils::{sqlite_has_table, table_column_set};
+use rusqlite::{Connection, OpenFlags};
+use std::collections::{HashMap, HashSet};
+use std::path::{Path, PathBuf};
+use std::time::Duration;
+
+#[derive(Debug, Default)]
+pub(super) struct SqliteUpdateCounts {
+    provider_rows: usize,
+    cwd_rows: usize,
+    catalog_insert_rows: usize,
+}
+
+impl SqliteUpdateCounts {
+    pub(super) fn total(&self) -> usize {
+        self.provider_rows + self.cwd_rows + self.catalog_insert_rows
+    }
+
+    fn add(&mut self, other: Self) {
+        self.provider_rows += other.provider_rows;
+        self.cwd_rows += other.cwd_rows;
+        self.catalog_insert_rows += other.catalog_insert_rows;
+    }
+}
+
+#[derive(Debug, Default)]
+pub(super) struct MutationJournal {
+    applied_rollouts: Vec<SessionFileChange>,
+    sqlite_restore_attempts: Vec<SqliteRestoreAttempt>,
+}
+
+#[derive(Debug, Clone)]
+struct SqliteRestoreAttempt {
+    path: PathBuf,
+    expected_data_version: i64,
+}
+
+pub(super) struct PendingSqliteUpdate {
+    path: PathBuf,
+    conn: Connection,
+    observer: Connection,
+    thread_columns: HashSet<String>,
+    catalog_columns: HashSet<String>,
+    counts: SqliteUpdateCounts,
+    transaction_open: bool,
+}
+
+impl PendingSqliteUpdate {
+    pub(super) fn path(&self) -> &Path {
+        &self.path
+    }
+}
+
+pub(super) fn rollback_open_transactions(updates: &mut [PendingSqliteUpdate]) {
+    for update in updates.iter_mut().rev() {
+        if update.transaction_open {
+            let _ = update.conn.execute_batch("ROLLBACK");
+            update.transaction_open = false;
+        }
+    }
+}
+
+fn sqlite_data_version(conn: &Connection) -> Result<i64> {
+    conn.query_row("PRAGMA data_version", [], |row| row.get(0))
+        .map_err(|error| CodexxError::Database(error.to_string()))
+}
+
+fn create_sqlite_rollback_table(conn: &Connection) -> Result<()> {
+    conn.execute_batch(
+        "CREATE TEMP TABLE codexx_session_rollback (
+            id TEXT PRIMARY KEY,
+            model_provider TEXT,
+            cwd TEXT,
+            provider_changed INTEGER NOT NULL DEFAULT 0,
+            cwd_changed INTEGER NOT NULL DEFAULT 0
+         );",
+    )
+    .map_err(|error| CodexxError::Database(error.to_string()))?;
+    create_catalog_rollback_tables(conn)
+}
+
+pub(super) fn prepare_sqlite_updates(sqlite_paths: &[PathBuf]) -> Result<Vec<PendingSqliteUpdate>> {
+    let mut pending = Vec::new();
+    let mut seen_databases = HashSet::new();
+    let prepare_result = (|| -> Result<()> {
+        for path in sqlite_paths {
+            if !path.exists() {
+                return Err(CodexxError::Database(format!(
+                    "SQLite 文件不存在: {}",
+                    path.display()
+                )));
+            }
+            let identity = path.canonicalize().map_err(|error| io_err(path, error))?;
+            if !seen_databases.insert(identity.clone()) {
+                continue;
+            }
+            let conn = Connection::open_with_flags(
+                &identity,
+                OpenFlags::SQLITE_OPEN_READ_WRITE | OpenFlags::SQLITE_OPEN_NO_MUTEX,
+            )
+            .map_err(|error| {
+                CodexxError::Database(format!("打开 SQLite 失败 {}: {error}", path.display()))
+            })?;
+            conn.busy_timeout(Duration::from_secs(5))
+                .map_err(|error| CodexxError::Database(error.to_string()))?;
+            let thread_columns = if sqlite_has_table(&conn, "threads")? {
+                table_column_set(&conn, "threads")?
+            } else {
+                HashSet::new()
+            };
+            let catalog_columns = catalog_columns(&conn)?;
+            let supports_thread_updates =
+                thread_columns.contains("id") && thread_columns.contains("model_provider");
+            let supports_catalog_updates =
+                catalog_columns.contains("thread_id") && catalog_columns.contains("model_provider");
+            if !supports_thread_updates && !supports_catalog_updates {
+                continue;
+            }
+            conn.execute_batch("BEGIN IMMEDIATE")
+                .map_err(|error| CodexxError::Database(error.to_string()))?;
+            if let Err(error) = create_sqlite_rollback_table(&conn) {
+                let _ = conn.execute_batch("ROLLBACK");
+                return Err(error);
+            }
+            let observer = match (|| -> Result<Connection> {
+                let observer = Connection::open_with_flags(
+                    &identity,
+                    OpenFlags::SQLITE_OPEN_READ_ONLY | OpenFlags::SQLITE_OPEN_NO_MUTEX,
+                )
+                .map_err(|error| {
+                    CodexxError::Database(format!(
+                        "打开 SQLite 观察连接失败 {}: {error}",
+                        identity.display()
+                    ))
+                })?;
+                observer
+                    .busy_timeout(Duration::from_secs(5))
+                    .map_err(|error| CodexxError::Database(error.to_string()))?;
+                sqlite_data_version(&observer)?;
+                Ok(observer)
+            })() {
+                Ok(observer) => observer,
+                Err(error) => {
+                    let _ = conn.execute_batch("ROLLBACK");
+                    return Err(error);
+                }
+            };
+            pending.push(PendingSqliteUpdate {
+                path: identity,
+                conn,
+                observer,
+                thread_columns,
+                catalog_columns,
+                counts: SqliteUpdateCounts::default(),
+                transaction_open: true,
+            });
+        }
+        Ok(())
+    })();
+    if let Err(error) = prepare_result {
+        rollback_open_transactions(&mut pending);
+        return Err(error);
+    }
+    Ok(pending)
+}
+
+fn apply_sqlite_updates(
+    pending: &mut [PendingSqliteUpdate],
+    rollouts: &RolloutScan,
+    target_provider: &str,
+    catalog_sources: &HashMap<String, CatalogRepairThread>,
+    syncable_thread_ids: &HashSet<String>,
+) -> Result<()> {
+    let mut sorted_thread_ids = syncable_thread_ids.iter().collect::<Vec<_>>();
+    sorted_thread_ids.sort();
+    for update in pending.iter_mut() {
+        let internal_ids = if update.thread_columns.contains("id") {
+            sqlite_subagent_thread_ids(&update.conn, &update.thread_columns)?
+        } else {
+            HashSet::new()
+        };
+        if update.thread_columns.contains("id") && update.thread_columns.contains("model_provider")
+        {
+            let archived_filter = if update.thread_columns.contains("archived") {
+                " AND COALESCE(archived, 0) = 0"
+            } else {
+                ""
+            };
+            let snapshot_sql = format!(
+                "INSERT INTO temp.codexx_session_rollback
+                        (id, model_provider, provider_changed)
+                     SELECT id, model_provider, 1 FROM threads
+                     WHERE id = ?2 AND COALESCE(model_provider, '') <> ?1{archived_filter}
+                     ON CONFLICT(id) DO UPDATE SET
+                        model_provider = excluded.model_provider,
+                        provider_changed = 1"
+            );
+            let update_sql = format!(
+                "UPDATE threads SET model_provider = ?1 \
+                 WHERE id = ?2 AND COALESCE(model_provider, '') <> ?1{archived_filter}"
+            );
+            for thread_id in &sorted_thread_ids {
+                if internal_ids.contains(*thread_id) {
+                    continue;
+                }
+                update
+                    .conn
+                    .execute(&snapshot_sql, (target_provider, thread_id))
+                    .map_err(|error| CodexxError::Database(error.to_string()))?;
+                update.counts.provider_rows += update
+                    .conn
+                    .execute(&update_sql, (target_provider, thread_id))
+                    .map_err(|error| CodexxError::Database(error.to_string()))?;
+            }
+        }
+
+        if update.thread_columns.contains("id") && update.thread_columns.contains("cwd") {
+            let archived_filter = if update.thread_columns.contains("archived") {
+                " AND COALESCE(archived, 0) = 0"
+            } else {
+                ""
+            };
+            let snapshot_sql = format!(
+                "INSERT INTO temp.codexx_session_rollback
+                    (id, cwd, cwd_changed)
+                 SELECT id, cwd, 1 FROM threads
+                 WHERE id = ?2 AND COALESCE(cwd, '') <> ?1{archived_filter}
+                 ON CONFLICT(id) DO UPDATE SET
+                    cwd = excluded.cwd,
+                    cwd_changed = 1"
+            );
+            let update_sql = format!(
+                "UPDATE threads SET cwd = ?1 \
+                 WHERE id = ?2 AND COALESCE(cwd, '') <> ?1{archived_filter}"
+            );
+            for (thread_id, cwd) in &rollouts.cwd_by_thread_id {
+                if !syncable_thread_ids.contains(thread_id) || internal_ids.contains(thread_id) {
+                    continue;
+                }
+                update
+                    .conn
+                    .execute(&snapshot_sql, (cwd, thread_id))
+                    .map_err(|error| CodexxError::Database(error.to_string()))?;
+                update.counts.cwd_rows += update
+                    .conn
+                    .execute(&update_sql, (cwd, thread_id))
+                    .map_err(|error| CodexxError::Database(error.to_string()))?;
+            }
+        }
+        let local_syncable_ids = syncable_thread_ids
+            .difference(&internal_ids)
+            .cloned()
+            .collect();
+        let catalog_counts = apply_catalog_updates(
+            &update.conn,
+            &update.catalog_columns,
+            target_provider,
+            catalog_sources,
+            &local_syncable_ids,
+        )?;
+        update.counts.provider_rows += catalog_counts.provider_rows;
+        update.counts.catalog_insert_rows += catalog_counts.inserted_rows;
+    }
+    Ok(())
+}
+
+fn commit_sqlite_updates<F>(
+    pending: &mut [PendingSqliteUpdate],
+    journal: &mut MutationJournal,
+    hook: &mut F,
+) -> Result<SqliteUpdateCounts>
+where
+    F: FnMut(MutationPoint) -> Result<()>,
+{
+    let mut updated = SqliteUpdateCounts::default();
+    for index in 0..pending.len() {
+        let before_commit = sqlite_data_version(&pending[index].observer)?;
+        journal.sqlite_restore_attempts.push(SqliteRestoreAttempt {
+            path: pending[index].path.clone(),
+            expected_data_version: before_commit,
+        });
+        let attempt_index = journal.sqlite_restore_attempts.len() - 1;
+        if let Err(error) = pending[index].conn.execute_batch("COMMIT") {
+            let rollback_succeeded = !pending[index].conn.is_autocommit()
+                && pending[index].conn.execute_batch("ROLLBACK").is_ok()
+                && pending[index].conn.is_autocommit();
+            pending[index].transaction_open = !pending[index].conn.is_autocommit();
+            if rollback_succeeded {
+                journal.sqlite_restore_attempts.remove(attempt_index);
+            }
+            rollback_open_transactions(&mut pending[index + 1..]);
+            return Err(CodexxError::Database(error.to_string()));
+        }
+        pending[index].transaction_open = false;
+        journal.sqlite_restore_attempts[attempt_index].expected_data_version =
+            sqlite_data_version(&pending[index].observer)?;
+        updated.add(std::mem::take(&mut pending[index].counts));
+        if let Err(error) = hook(MutationPoint::AfterSqliteCommit(index)) {
+            rollback_open_transactions(&mut pending[index + 1..]);
+            return Err(error);
+        }
+    }
+    Ok(updated)
+}
+
+fn restore_sqlite_update(
+    update: &mut PendingSqliteUpdate,
+    expected_data_version: i64,
+) -> Result<()> {
+    update
+        .conn
+        .execute_batch("BEGIN IMMEDIATE")
+        .map_err(|error| CodexxError::Database(error.to_string()))?;
+    update.transaction_open = true;
+    let result = (|| -> Result<()> {
+        let current = sqlite_data_version(&update.observer)?;
+        if current != expected_data_version {
+            return Err(CodexxError::Config(format!(
+                "会话数据库已发生变化，已保留备份且未覆盖: {}",
+                update.path.display()
+            )));
+        }
+
+        restore_catalog_updates(&update.conn, &update.catalog_columns)?;
+        let mut statements = Vec::new();
+        if update.thread_columns.contains("id") && update.thread_columns.contains("model_provider")
+        {
+            statements.push(
+                "UPDATE threads
+                 SET model_provider = (
+                    SELECT rollback.model_provider
+                    FROM temp.codexx_session_rollback AS rollback
+                    WHERE rollback.id = threads.id
+                 )
+                 WHERE id IN (
+                    SELECT id FROM temp.codexx_session_rollback WHERE provider_changed = 1
+                 )",
+            );
+        }
+        if update.thread_columns.contains("id") && update.thread_columns.contains("cwd") {
+            statements.push(
+                "UPDATE threads
+                 SET cwd = (
+                    SELECT rollback.cwd
+                    FROM temp.codexx_session_rollback AS rollback
+                    WHERE rollback.id = threads.id
+                 )
+                 WHERE id IN (
+                    SELECT id FROM temp.codexx_session_rollback WHERE cwd_changed = 1
+                 )",
+            );
+        }
+        statements.push("DROP TABLE temp.codexx_session_rollback");
+        update
+            .conn
+            .execute_batch(&statements.join(";"))
+            .map_err(|error| CodexxError::Database(error.to_string()))?;
+        update
+            .conn
+            .execute_batch("COMMIT")
+            .map_err(|error| CodexxError::Database(error.to_string()))?;
+        update.transaction_open = false;
+        Ok(())
+    })();
+    if result.is_err() && update.transaction_open {
+        let _ = update.conn.execute_batch("ROLLBACK");
+        update.transaction_open = false;
+    }
+    result
+}
+
+pub(super) fn rollback_mutation(
+    journal: &MutationJournal,
+    pending_sqlite: &mut [PendingSqliteUpdate],
+) -> Vec<String> {
+    let mut errors = Vec::new();
+    for attempt in journal.sqlite_restore_attempts.iter().rev() {
+        let Some(update) = pending_sqlite
+            .iter_mut()
+            .find(|update| update.path == attempt.path)
+        else {
+            errors.push(format!("缺少 SQLite 恢复连接: {}", attempt.path.display()));
+            continue;
+        };
+        if let Err(error) = restore_sqlite_update(update, attempt.expected_data_version) {
+            errors.push(error.to_string());
+        }
+    }
+    if let Err(error) = restore_session_changes(&journal.applied_rollouts) {
+        errors.push(error.to_string());
+    }
+    errors
+}
+
+pub(super) fn mutation_error(original: CodexxError, recovery_errors: Vec<String>) -> CodexxError {
+    if recovery_errors.is_empty() {
+        original
+    } else {
+        CodexxError::Config(format!(
+            "同步失败，自动恢复也未完成：{original}；{}",
+            recovery_errors.join("；")
+        ))
+    }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub(super) enum MutationPoint {
+    BeforeSqliteLock,
+    BeforeRolloutMutation,
+    AfterRolloutMutation,
+    AfterSqliteCommit(usize),
+}
+
+pub(super) struct MutationResult {
+    pub(super) applied_rollouts: usize,
+    pub(super) skipped_rollouts: Vec<PathBuf>,
+    pub(super) sqlite_updates: SqliteUpdateCounts,
+}
+
+// A file may be reclassified after scanning. In particular, the general file
+// writer skips concurrently changed rollouts; that must not leave their old IDs
+// eligible for a catalog insert or a provider update in this transaction.
+fn validate_rollout_classification(rollouts: &RolloutScan) -> Result<()> {
+    let mut paths = rollouts.provider_candidate_paths.clone();
+    for change in &rollouts.changes {
+        if rollout_text_is_internal(&change.original_text) {
+            return Err(CodexxError::Config(
+                "内部会话不能同步为普通会话。".to_string(),
+            ));
+        }
+        paths.insert(change.path.clone());
+    }
+    for path in paths {
+        if !rollout_path_has_syncable_identity(&path)? {
+            return Err(CodexxError::Config(format!(
+                "会话类型已变化，已停止同步；请重新检查会话：{}",
+                path.display()
+            )));
+        }
+    }
+    Ok(())
+}
+
+pub(super) fn execute_provider_sync_mutation<F>(
+    rollouts: &RolloutScan,
+    pending_sqlite: &mut [PendingSqliteUpdate],
+    target_provider: &str,
+    catalog_sources: &HashMap<String, CatalogRepairThread>,
+    syncable_thread_ids: &HashSet<String>,
+    journal: &mut MutationJournal,
+    hook: &mut F,
+) -> Result<MutationResult>
+where
+    F: FnMut(MutationPoint) -> Result<()>,
+{
+    let result = (|| -> Result<MutationResult> {
+        hook(MutationPoint::BeforeRolloutMutation)?;
+        validate_rollout_classification(rollouts)?;
+        let (applied_rollouts, skipped_rollouts) = apply_session_changes(&rollouts.changes)?;
+        journal.applied_rollouts = applied_rollouts;
+        hook(MutationPoint::AfterRolloutMutation)?;
+        validate_rollout_classification(rollouts)?;
+        apply_sqlite_updates(
+            pending_sqlite,
+            rollouts,
+            target_provider,
+            catalog_sources,
+            syncable_thread_ids,
+        )?;
+        let sqlite_updates = commit_sqlite_updates(pending_sqlite, journal, hook)?;
+        Ok(MutationResult {
+            applied_rollouts: journal.applied_rollouts.len(),
+            skipped_rollouts,
+            sqlite_updates,
+        })
+    })();
+    if result.is_err() {
+        rollback_open_transactions(pending_sqlite);
+    }
+    result
+}
+
+#[cfg(test)]
+#[path = "transaction_tests.rs"]
+mod tests;

apps/desktop/src-tauri/src/sessions/transaction_tests.rs

@@ -0,0 +1,540 @@
+use super::*;
+use crate::sessions::backup::provider_sync_backup_root;
+use crate::sessions::sync::sync_sessions_provider_with_hook;
+use rusqlite::{Connection, OpenFlags};
+use std::fs;
+use std::io::Write;
+use std::sync::atomic::{AtomicU64, Ordering};
+use std::sync::mpsc;
+use std::thread;
+use std::time::Duration;
+
+fn temp_dir(name: &str) -> PathBuf {
+    static COUNTER: AtomicU64 = AtomicU64::new(0);
+    let path = std::env::temp_dir().join(format!(
+        "codex-x-session-sync-{name}-{}-{}",
+        std::process::id(),
+        COUNTER.fetch_add(1, Ordering::Relaxed),
+    ));
+    let _ = fs::remove_dir_all(&path);
+    fs::create_dir_all(&path).expect("create test directory");
+    fs::write(path.join("config.toml"), "model_provider = \"custom\"\n")
+        .expect("write shared provider config");
+    path
+}
+
+fn write_rollout(path: &Path, id: &str) -> Vec<u8> {
+    if let Some(parent) = path.parent() {
+        fs::create_dir_all(parent).expect("create rollout parent");
+    }
+    let content = format!(
+        "{{\"type\":\"session_meta\",\"payload\":{{\"id\":\"{id}\",\"model_provider\":\"openai\",\"cwd\":\"/tmp/project\"}}}}\n"
+    );
+    fs::write(path, content.as_bytes()).expect("write rollout");
+    content.into_bytes()
+}
+
+fn create_thread_database(path: &Path, id: &str, rollout: &Path) {
+    if let Some(parent) = path.parent() {
+        fs::create_dir_all(parent).expect("create sqlite parent");
+    }
+    let conn = Connection::open(path).expect("create thread database");
+    conn.execute_batch(
+        "CREATE TABLE threads (
+            id TEXT PRIMARY KEY,
+            model_provider TEXT NOT NULL,
+            rollout_path TEXT
+         );",
+    )
+    .expect("create threads table");
+    conn.execute(
+        "INSERT INTO threads (id, model_provider, rollout_path)
+         VALUES (?1, 'openai', ?2)",
+        (id, rollout.display().to_string()),
+    )
+    .expect("insert thread");
+}
+
+fn thread_provider(path: &Path, id: &str) -> String {
+    Connection::open(path)
+        .expect("open thread database")
+        .query_row(
+            "SELECT model_provider FROM threads WHERE id = ?1",
+            [id],
+            |row| row.get(0),
+        )
+        .expect("read thread provider")
+}
+
+fn sqlite_quick_check(path: &Path) -> String {
+    Connection::open(path)
+        .expect("open sqlite for quick check")
+        .query_row("PRAGMA quick_check", [], |row| row.get(0))
+        .expect("run quick check")
+}
+
+#[test]
+fn sqlite_update_failure_rolls_back_every_open_database_and_jsonl() {
+    let codex_dir = temp_dir("multi-sqlite-update-failure");
+    let id = "019f6000-0000-7000-8000-000000000401";
+    let rollout = codex_dir.join(format!("sessions/rollout-test-{id}.jsonl"));
+    let original_rollout = write_rollout(&rollout, id);
+    let first = codex_dir.join("sqlite/custom.db");
+    let second = codex_dir.join("state_10.sqlite");
+    create_thread_database(&first, id, &rollout);
+    create_thread_database(&second, id, &rollout);
+    Connection::open(&second)
+        .expect("open failing database")
+        .execute_batch(
+            "CREATE TRIGGER reject_provider_update
+             BEFORE UPDATE OF model_provider ON threads
+             BEGIN SELECT RAISE(ABORT, 'provider update blocked'); END;",
+        )
+        .expect("install rejecting trigger");
+
+    let error = sync_sessions_provider_with_hook(
+        Some(codex_dir.display().to_string()),
+        Some("custom".to_string()),
+        |_| Ok(()),
+    )
+    .expect_err("second database update must fail");
+    assert!(error.to_string().contains("provider update blocked"));
+    assert_eq!(thread_provider(&first, id), "openai");
+    assert_eq!(thread_provider(&second, id), "openai");
+    assert_eq!(
+        fs::read(&rollout).expect("read restored rollout"),
+        original_rollout
+    );
+
+    fs::remove_dir_all(codex_dir).expect("remove test directory");
+}
+
+#[test]
+fn sqlite_commit_failpoint_restores_committed_and_uncommitted_databases() {
+    let codex_dir = temp_dir("sqlite-commit-failpoint");
+    let id = "019f6000-0000-7000-8000-000000000406";
+    let rollout = codex_dir.join(format!("sessions/rollout-test-{id}.jsonl"));
+    let original_rollout = write_rollout(&rollout, id);
+    let first = codex_dir.join("sqlite/custom.db");
+    let second = codex_dir.join("state_10.sqlite");
+    create_thread_database(&first, id, &rollout);
+    create_thread_database(&second, id, &rollout);
+
+    let error = sync_sessions_provider_with_hook(
+        Some(codex_dir.display().to_string()),
+        Some("custom".to_string()),
+        |point| match point {
+            MutationPoint::AfterSqliteCommit(0) => {
+                Err(CodexxError::Config("提交后注入失败".to_string()))
+            }
+            _ => Ok(()),
+        },
+    )
+    .expect_err("fail after first sqlite commit");
+
+    assert_eq!(error.to_string(), "配置错误: 提交后注入失败");
+    assert_eq!(thread_provider(&first, id), "openai");
+    assert_eq!(thread_provider(&second, id), "openai");
+    assert_eq!(
+        fs::read(&rollout).expect("read restored rollout"),
+        original_rollout
+    );
+
+    fs::remove_dir_all(codex_dir).expect("remove test directory");
+}
+
+#[test]
+fn failed_sqlite_commit_rolls_back_without_snapshot_restore() {
+    let codex_dir = temp_dir("failed-sqlite-commit");
+    let id = "019f6000-0000-7000-8000-000000000407";
+    let rollout = codex_dir.join(format!("sessions/rollout-test-{id}.jsonl"));
+    write_rollout(&rollout, id);
+    let database = codex_dir.join("state_10.sqlite");
+    create_thread_database(&database, id, &rollout);
+    Connection::open(&database)
+        .expect("open database for deferred constraint")
+        .execute_batch(
+            "CREATE TABLE parent (id TEXT PRIMARY KEY);
+             CREATE TABLE child (
+                parent_id TEXT REFERENCES parent(id) DEFERRABLE INITIALLY DEFERRED
+             );",
+        )
+        .expect("create deferred foreign key");
+
+    let conn = Connection::open(&database).expect("open writer");
+    conn.pragma_update(None, "foreign_keys", true)
+        .expect("enable foreign keys");
+    conn.execute_batch(
+        "BEGIN IMMEDIATE;
+         INSERT INTO child (parent_id) VALUES ('missing');",
+    )
+    .expect("defer invalid foreign key until commit");
+    let observer = Connection::open_with_flags(
+        &database,
+        OpenFlags::SQLITE_OPEN_READ_ONLY | OpenFlags::SQLITE_OPEN_NO_MUTEX,
+    )
+    .expect("open observer");
+    let mut pending = vec![PendingSqliteUpdate {
+        path: database.clone(),
+        conn,
+        observer,
+        thread_columns: HashSet::new(),
+        catalog_columns: HashSet::new(),
+        counts: SqliteUpdateCounts::default(),
+        transaction_open: true,
+    }];
+    let mut journal = MutationJournal::default();
+
+    let error = commit_sqlite_updates(&mut pending, &mut journal, &mut |_| Ok(()))
+        .expect_err("deferred foreign key must reject commit");
+
+    assert!(error.to_string().contains("FOREIGN KEY constraint failed"));
+    assert!(journal.sqlite_restore_attempts.is_empty());
+    assert!(!pending[0].transaction_open);
+    let child_rows: i64 = Connection::open(&database)
+        .expect("reopen database")
+        .query_row("SELECT COUNT(*) FROM child", [], |row| row.get(0))
+        .expect("count rolled-back child rows");
+    assert_eq!(child_rows, 0);
+
+    drop(pending);
+    fs::remove_dir_all(codex_dir).expect("remove test directory");
+}
+
+#[test]
+fn sqlite_restore_does_not_overwrite_new_codex_writes() {
+    let codex_dir = temp_dir("sqlite-concurrent-write");
+    let id = "019f6000-0000-7000-8000-000000000409";
+    let rollout = codex_dir.join(format!("sessions/rollout-test-{id}.jsonl"));
+    let original_rollout = write_rollout(&rollout, id);
+    let database = codex_dir.join("state_10.sqlite");
+    create_thread_database(&database, id, &rollout);
+
+    let error = sync_sessions_provider_with_hook(
+        Some(codex_dir.display().to_string()),
+        Some("custom".to_string()),
+        |point| match point {
+            MutationPoint::AfterSqliteCommit(0) => {
+                Connection::open(&database)
+                    .expect("open concurrent Codex writer")
+                    .execute_batch(
+                        "CREATE TABLE concurrent_marker (value TEXT NOT NULL);
+                         INSERT INTO concurrent_marker (value) VALUES ('keep-new-write');",
+                    )
+                    .expect("write after provider sync commit");
+                Err(CodexxError::Config("并发写入后注入失败".to_string()))
+            }
+            _ => Ok(()),
+        },
+    )
+    .expect_err("recovery must detect the concurrent write");
+
+    assert!(error.to_string().contains("会话数据库已发生变化"));
+    assert_eq!(thread_provider(&database, id), "custom");
+    let marker: String = Connection::open(&database)
+        .expect("open database with concurrent write")
+        .query_row("SELECT value FROM concurrent_marker", [], |row| row.get(0))
+        .expect("read concurrent marker");
+    assert_eq!(marker, "keep-new-write");
+    assert_eq!(
+        fs::read(&rollout).expect("read restored rollout"),
+        original_rollout
+    );
+    assert!(fs::read_dir(provider_sync_backup_root(&codex_dir))
+        .expect("read retained provider sync backup")
+        .next()
+        .is_some());
+
+    fs::remove_dir_all(codex_dir).expect("remove test directory");
+}
+
+#[test]
+fn sqlite_restore_rechecks_after_waiting_for_a_writer() {
+    let codex_dir = temp_dir("sqlite-writer-during-restore");
+    let id = "019f6000-0000-7000-8000-000000000412";
+    let rollout = codex_dir.join(format!("sessions/rollout-test-{id}.jsonl"));
+    write_rollout(&rollout, id);
+    let database = codex_dir.join("state_10.sqlite");
+    create_thread_database(&database, id, &rollout);
+    let mut writer = None;
+
+    let error = sync_sessions_provider_with_hook(
+        Some(codex_dir.display().to_string()),
+        Some("custom".to_string()),
+        |point| match point {
+            MutationPoint::AfterSqliteCommit(0) => {
+                let writer_database = database.clone();
+                let (ready_tx, ready_rx) = mpsc::channel();
+                writer = Some(thread::spawn(move || {
+                    let conn = Connection::open(writer_database).expect("open concurrent writer");
+                    conn.execute_batch(
+                        "BEGIN IMMEDIATE;
+                         CREATE TABLE concurrent_during_restore (value TEXT NOT NULL);
+                         INSERT INTO concurrent_during_restore (value)
+                         VALUES ('keep-writer-commit');",
+                    )
+                    .expect("stage concurrent write");
+                    ready_tx.send(()).expect("signal writer lock");
+                    thread::sleep(Duration::from_millis(150));
+                    conn.execute_batch("COMMIT")
+                        .expect("commit while recovery waits");
+                }));
+                ready_rx
+                    .recv_timeout(Duration::from_secs(2))
+                    .expect("wait for concurrent writer lock");
+                Err(CodexxError::Config("持锁写入期间注入失败".to_string()))
+            }
+            _ => Ok(()),
+        },
+    )
+    .expect_err("recovery must recheck after waiting for the writer");
+
+    writer
+        .take()
+        .expect("writer handle")
+        .join()
+        .expect("join concurrent writer");
+    assert!(error.to_string().contains("会话数据库已发生变化"));
+    assert_eq!(thread_provider(&database, id), "custom");
+    let marker: String = Connection::open(&database)
+        .expect("open database after concurrent commit")
+        .query_row("SELECT value FROM concurrent_during_restore", [], |row| {
+            row.get(0)
+        })
+        .expect("read concurrent marker");
+    assert_eq!(marker, "keep-writer-commit");
+
+    fs::remove_dir_all(codex_dir).expect("remove test directory");
+}
+
+#[cfg(unix)]
+#[test]
+fn sqlite_prepare_deduplicates_symlink_aliases() {
+    use std::os::unix::fs::symlink;
+
+    let codex_dir = temp_dir("sqlite-symlink-alias");
+    let id = "019f6000-0000-7000-8000-000000000410";
+    let rollout = codex_dir.join(format!("sessions/rollout-test-{id}.jsonl"));
+    write_rollout(&rollout, id);
+    let database = codex_dir.join("state_10.sqlite");
+    let alias = codex_dir.join("state-alias.sqlite");
+    create_thread_database(&database, id, &rollout);
+    symlink(&database, &alias).expect("create database symlink");
+
+    let mut pending =
+        prepare_sqlite_updates(&[database.clone(), alias]).expect("prepare aliased database once");
+
+    assert_eq!(pending.len(), 1);
+    assert_eq!(
+        pending[0].path,
+        database.canonicalize().expect("canonical db")
+    );
+    rollback_open_transactions(&mut pending);
+
+    fs::remove_dir_all(codex_dir).expect("remove test directory");
+}
+
+#[test]
+fn injected_failure_restores_sqlite_and_jsonl_without_touching_global_state() {
+    let codex_dir = temp_dir("full-mutation-rollback");
+    let id = "019f6000-0000-7000-8000-000000000411";
+    let rollout = codex_dir.join(format!("sessions/rollout-test-{id}.jsonl"));
+    write_rollout(&rollout, id);
+    let mut rollout_file = fs::OpenOptions::new()
+        .append(true)
+        .open(&rollout)
+        .expect("open rollout for user event");
+    writeln!(
+        rollout_file,
+        "{{\"type\":\"event_msg\",\"payload\":{{\"type\":\"user_message\",\"message\":\"hello\"}}}}"
+    )
+    .expect("append user event");
+    drop(rollout_file);
+    let original_rollout = fs::read(&rollout).expect("read original rollout");
+    let database = codex_dir.join("state_10.sqlite");
+    create_thread_database(&database, id, &rollout);
+    let wal_guard = Connection::open(&database).expect("open database for WAL mode");
+    wal_guard
+        .pragma_update(None, "journal_mode", "WAL")
+        .expect("enable WAL mode");
+    wal_guard
+        .execute_batch(
+            "ALTER TABLE threads ADD COLUMN has_user_event INTEGER DEFAULT 0;
+             ALTER TABLE threads ADD COLUMN cwd TEXT;
+             UPDATE threads SET cwd = '/tmp/wrong';
+             CREATE TABLE rollback_marker (value TEXT NOT NULL);
+             INSERT INTO rollback_marker (value) VALUES ('keep-me');",
+        )
+        .expect("write WAL marker");
+    let wal_path = PathBuf::from(format!("{}-wal", database.display()));
+    assert!(wal_path.exists());
+    let global = codex_dir.join(".codex-global-state.json");
+    let global_backup = codex_dir.join(".codex-global-state.json.bak");
+    let original_global = br#"{
+  "electron-saved-workspace-roots": "/tmp/project",
+  "unrelated-setting": true
+}"#;
+    fs::write(&global, original_global).expect("write original global state");
+    assert!(!global_backup.exists());
+
+    let mut hook_called = false;
+    let error = sync_sessions_provider_with_hook(
+        Some(codex_dir.display().to_string()),
+        Some("custom".to_string()),
+        |point| match point {
+            MutationPoint::AfterSqliteCommit(0) => {
+                hook_called = true;
+                assert_eq!(thread_provider(&database, id), "custom");
+                let user_event_flag: i64 = Connection::open(&database)
+                    .expect("open committed session metadata")
+                    .query_row(
+                        "SELECT has_user_event FROM threads WHERE id = ?1",
+                        [id],
+                        |row| row.get(0),
+                    )
+                    .expect("read committed user event flag");
+                assert_eq!(user_event_flag, 0);
+                assert!(fs::read_to_string(&rollout)
+                    .expect("read mutated rollout")
+                    .contains("\"model_provider\":\"custom\""));
+                assert_eq!(
+                    fs::read(&global).expect("read untouched global state"),
+                    original_global
+                );
+                assert!(!global_backup.exists());
+                Err(CodexxError::Config("测试注入失败".to_string()))
+            }
+            _ => Ok(()),
+        },
+    )
+    .expect_err("hook must fail after all writes");
+
+    assert!(hook_called);
+    assert_eq!(error.to_string(), "配置错误: 测试注入失败");
+    assert_eq!(thread_provider(&database, id), "openai");
+    let restored_index: (i64, String) = Connection::open(&database)
+        .expect("open restored session metadata")
+        .query_row(
+            "SELECT has_user_event, cwd FROM threads WHERE id = ?1",
+            [id],
+            |row| Ok((row.get(0)?, row.get(1)?)),
+        )
+        .expect("read restored session metadata");
+    assert_eq!(restored_index, (0, "/tmp/wrong".to_string()));
+    assert_eq!(sqlite_quick_check(&database), "ok");
+    let marker: String = Connection::open(&database)
+        .expect("open restored database")
+        .query_row("SELECT value FROM rollback_marker", [], |row| row.get(0))
+        .expect("read restored WAL marker");
+    assert_eq!(marker, "keep-me");
+    assert_eq!(
+        fs::read(&rollout).expect("read restored rollout"),
+        original_rollout
+    );
+    assert_eq!(
+        fs::read(&global).expect("read restored global"),
+        original_global
+    );
+    assert!(!global_backup.exists());
+    let retained_backup = fs::read_dir(provider_sync_backup_root(&codex_dir))
+        .expect("read retained provider sync backup")
+        .next()
+        .expect("retained provider sync backup")
+        .expect("read retained provider sync backup entry")
+        .path();
+    let metadata = fs::read_to_string(retained_backup.join("metadata.json"))
+        .expect("read retained provider sync metadata");
+    assert!(!metadata.contains("config.toml"));
+    assert!(!metadata.contains(".codex-global-state.json"));
+    assert!(!retained_backup.join("config.toml").exists());
+    assert!(!retained_backup.join(".codex-global-state.json").exists());
+
+    drop(wal_guard);
+    fs::remove_dir_all(codex_dir).expect("remove test directory");
+}
+
+#[test]
+fn internal_reclassification_before_mutation_aborts_without_registering_or_rewriting() {
+    for existing_provider in ["openai", "custom"] {
+        let codex_dir = temp_dir("internal-before-mutation");
+        let id = "019f6000-0000-7000-8000-000000000980";
+        let rollout = codex_dir.join(format!("sessions/rollout-test-{id}.jsonl"));
+        let existing = String::from_utf8(write_rollout(&rollout, id))
+            .expect("UTF-8 fixture")
+            .replace("openai", existing_provider);
+        fs::write(&rollout, existing).expect("set current rollout provider");
+        let database = codex_dir.join("state_10.sqlite");
+        create_thread_database(&database, id, &rollout);
+        let internal = format!(
+            "{}\n",
+            serde_json::json!({"type":"session_meta", "payload":{
+                "id":id, "model_provider":existing_provider, "source":{"internal":"guardian"}
+            }})
+        );
+        let error = sync_sessions_provider_with_hook(
+            Some(codex_dir.display().to_string()),
+            None,
+            |point| {
+                if point == MutationPoint::BeforeRolloutMutation {
+                    fs::write(&rollout, &internal).expect("reclassify rollout during sync");
+                }
+                Ok(())
+            },
+        )
+        .expect_err("reclassification must abort sync");
+        assert!(error.to_string().contains("会话类型已变化"), "{error}");
+        assert_eq!(thread_provider(&database, id), "openai");
+        assert_eq!(
+            fs::read_to_string(&rollout).expect("read internal rollout"),
+            internal
+        );
+        fs::remove_dir_all(codex_dir).expect("remove race fixture");
+    }
+}
+
+#[test]
+fn internal_reclassification_after_file_writes_rolls_back_other_files_and_all_databases() {
+    let codex_dir = temp_dir("internal-after-rollout-mutation");
+    let parent = "019f6000-0000-7000-8000-000000000981";
+    let child = "019f6000-0000-7000-8000-000000000982";
+    let parent_rollout = codex_dir.join(format!("sessions/rollout-test-{parent}.jsonl"));
+    let child_rollout = codex_dir.join(format!("sessions/rollout-test-{child}.jsonl"));
+    let original_parent = write_rollout(&parent_rollout, parent);
+    write_rollout(&child_rollout, child);
+    let database = codex_dir.join("state_10.sqlite");
+    create_thread_database(&database, parent, &parent_rollout);
+    Connection::open(&database)
+        .expect("open fixture index")
+        .execute(
+            "INSERT INTO threads (id, model_provider, rollout_path) VALUES (?1, 'openai', ?2)",
+            (child, child_rollout.display().to_string()),
+        )
+        .expect("insert second thread");
+    let internal = format!(
+        "{}\n",
+        serde_json::json!({"type":"session_meta", "payload":{
+            "id":child, "model_provider":"openai", "source":{"internal":"guardian"}
+        }})
+    );
+    let error =
+        sync_sessions_provider_with_hook(Some(codex_dir.display().to_string()), None, |point| {
+            if point == MutationPoint::AfterRolloutMutation {
+                fs::write(&child_rollout, &internal)
+                    .expect("publish internal metadata during sync");
+            }
+            Ok(())
+        })
+        .expect_err("reclassification must prevent database commits");
+    assert!(error.to_string().contains("会话类型已变化"), "{error}");
+    assert_eq!(thread_provider(&database, parent), "openai");
+    assert_eq!(thread_provider(&database, child), "openai");
+    assert_eq!(
+        fs::read(&parent_rollout).expect("read restored parent"),
+        original_parent
+    );
+    assert_eq!(
+        fs::read_to_string(&child_rollout).expect("preserve newer internal source"),
+        internal
+    );
+    fs::remove_dir_all(codex_dir).expect("remove rollback fixture");
+}

apps/desktop/src-tauri/src/sessions/types.rs

@@ -0,0 +1,96 @@
+use serde::Serialize;
+use std::collections::{HashMap, HashSet};
+use std::path::PathBuf;
+use std::time::SystemTime;
+
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub(crate) struct SessionPreview {
+    pub(crate) id: String,
+    pub(crate) title: String,
+    pub(crate) model_provider: Option<String>,
+    pub(crate) model: Option<String>,
+    pub(crate) cwd: Option<String>,
+    pub(crate) rollout_path: Option<String>,
+    pub(crate) updated_at_ms: Option<i64>,
+    pub(crate) archived: bool,
+    pub(crate) has_user_event: bool,
+    pub(crate) is_subagent: bool,
+    pub(crate) needs_sync: bool,
+}
+
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub(crate) struct SessionSyncStatus {
+    pub(crate) codex_dir: String,
+    pub(crate) target_provider: String,
+    pub(crate) rollout_files: usize,
+    pub(crate) session_meta_count: usize,
+    pub(crate) mismatched_rollouts: usize,
+    pub(crate) mismatched_session_meta: usize,
+    pub(crate) sqlite_dbs: usize,
+    pub(crate) sqlite_threads: usize,
+    pub(crate) top_level_threads: usize,
+    pub(crate) subagent_threads: usize,
+    pub(crate) mismatched_threads: usize,
+    pub(crate) mismatched_sessions: usize,
+    pub(crate) needs_sync: bool,
+    pub(crate) scan_complete: bool,
+    pub(crate) scan_failures: Vec<String>,
+    pub(crate) backup_dir: Option<String>,
+    pub(crate) warnings: Vec<String>,
+    pub(crate) sessions: Vec<SessionPreview>,
+}
+
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub(crate) struct SessionSyncResult {
+    pub(crate) status: SessionSyncStatus,
+    pub(crate) updated_rollouts: usize,
+    pub(crate) updated_threads: usize,
+    pub(crate) backup_dir: String,
+}
+
+#[derive(Debug, Default)]
+pub(crate) struct RolloutScan {
+    pub(crate) discovered_rollout_files: usize,
+    pub(crate) rollout_files: usize,
+    pub(crate) session_meta_count: usize,
+    pub(crate) mismatched_rollouts: usize,
+    pub(crate) mismatched_session_meta: usize,
+    pub(crate) changes: Vec<SessionFileChange>,
+    pub(crate) provider_candidate_paths: HashSet<PathBuf>,
+    pub(crate) cwd_by_thread_id: HashMap<String, String>,
+    pub(crate) thread_ids: HashSet<String>,
+    /// Non-user threads identified from their own rollout metadata. Retained
+    /// even when the rollout is excluded from provider synchronization.
+    pub(crate) internal_thread_ids: HashSet<String>,
+    pub(crate) mismatched_thread_ids: HashSet<String>,
+    pub(crate) warnings: Vec<String>,
+    pub(crate) scan_failures: Vec<String>,
+}
+
+#[derive(Debug, Clone)]
+pub(crate) struct SessionFileChange {
+    pub(crate) path: PathBuf,
+    pub(crate) original_text: String,
+    pub(crate) next_text: String,
+    pub(crate) original_mtime: Option<SystemTime>,
+}
+
+#[derive(Debug, Default)]
+pub(crate) struct SqliteScan {
+    pub(crate) sqlite_dbs: usize,
+    pub(crate) sqlite_threads: usize,
+    pub(crate) top_level_threads: usize,
+    pub(crate) subagent_threads: usize,
+    pub(crate) mismatched_threads: usize,
+    pub(crate) thread_ids: HashSet<String>,
+    pub(crate) syncable_thread_ids: HashSet<String>,
+    pub(crate) archived_thread_ids: HashSet<String>,
+    pub(crate) subagent_thread_ids: HashSet<String>,
+    pub(crate) rollout_paths_by_thread_id: HashMap<String, String>,
+    pub(crate) mismatched_thread_ids: HashSet<String>,
+    pub(crate) warnings: Vec<String>,
+    pub(crate) scan_failures: Vec<String>,
+}

apps/desktop/src-tauri/src/skills_mcp/archive.rs

@@ -0,0 +1,993 @@
+use super::build_skills_mcp_state_inner;
+use super::mcp::{
+    commit_mcp_transaction_with_config, document_bytes, is_valid_mcp_config, json_to_toml_item,
+    mcp_configs_equal, save_managed_mcp_on_connection,
+};
+use super::skills::{
+    codex_skills_dir, copy_dir_recursive, disabled_skills_dir, read_skill_metadata,
+    sanitize_dir_name,
+};
+use super::types::{SkillsMcpActionResult, SkillsMcpExportResult};
+use crate::error::{CodexxError, Result};
+use crate::file_io::{ensure_directory, io_err, parse_toml_document};
+use crate::live_config::{acquire_live_config_lock, read_file_snapshot, text_from_snapshot};
+use crate::paths::{app_home, normalized_path_scope};
+use crate::toml_utils::ensure_table;
+use crate::{config_path, now_rfc3339, open_db, resolve_codex_dir};
+use rusqlite::{params, TransactionBehavior};
+use serde::{Deserialize, Serialize};
+use serde_json::Value;
+use sha2::{Digest, Sha256};
+use std::collections::{HashMap, HashSet};
+use std::fs::{self, File, OpenOptions};
+use std::io::{Read, Seek};
+use std::path::{Component, Path, PathBuf};
+use std::sync::atomic::{AtomicU64, Ordering};
+use zip::write::SimpleFileOptions;
+
+const MANIFEST: &str = "codex-x-archive.json";
+const FORMAT: &str = "codex-x-skills-mcp";
+static NEXT_TEMP: AtomicU64 = AtomicU64::new(0);
+
+#[derive(Serialize, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+struct Manifest {
+    format: String,
+    version: u32,
+    #[serde(default)]
+    skills: Vec<SkillEntry>,
+    #[serde(default)]
+    mcp_servers: Vec<McpEntry>,
+}
+#[derive(Serialize, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+struct SkillEntry {
+    directory: String,
+    path: String,
+    enabled: bool,
+    note: Option<String>,
+}
+#[derive(Serialize, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+struct McpEntry {
+    id: String,
+    name: String,
+    config: Value,
+    enabled: bool,
+    note: Option<String>,
+}
+
+fn invalid(message: impl Into<String>) -> CodexxError {
+    CodexxError::Config(message.into())
+}
+fn zip_error(error: impl std::fmt::Display) -> CodexxError {
+    invalid(format!("无法读取或写入 ZIP：{error}"))
+}
+fn unique_name(prefix: &str) -> String {
+    format!(
+        ".{prefix}-{}-{}-{}",
+        std::process::id(),
+        chrono::Utc::now().timestamp_nanos_opt().unwrap_or_default(),
+        NEXT_TEMP.fetch_add(1, Ordering::Relaxed)
+    )
+}
+struct TempDir(PathBuf);
+impl TempDir {
+    fn new(parent: &Path) -> Result<Self> {
+        ensure_directory(parent)?;
+        let path = parent.join(unique_name("codex-x-archive"));
+        fs::create_dir(&path).map_err(|error| io_err(&path, error))?;
+        Ok(Self(path))
+    }
+}
+impl Drop for TempDir {
+    fn drop(&mut self) {
+        let _ = fs::remove_dir_all(&self.0);
+    }
+}
+
+// Reject Windows traversal/drive names on every OS too, so exported bundles can
+// safely move between machines. Links and special files are never extracted.
+fn safe_relative(name: &str) -> Result<PathBuf> {
+    if name.is_empty() || name.contains('\\') || name.contains(':') || name.contains('\0') {
+        return Err(invalid("ZIP 中含有不安全的文件路径"));
+    }
+    let path = Path::new(name);
+    if path
+        .components()
+        .any(|part| !matches!(part, Component::Normal(_)))
+    {
+        return Err(invalid("ZIP 中含有不安全的文件路径"));
+    }
+    for part in name.trim_end_matches('/').split('/') {
+        let stem = part.split('.').next().unwrap_or("").to_ascii_uppercase();
+        if part.is_empty()
+            || part.ends_with([' ', '.'])
+            || matches!(stem.as_str(), "CON" | "PRN" | "AUX" | "NUL")
+            || (stem.len() == 4
+                && (stem.starts_with("COM") || stem.starts_with("LPT"))
+                && stem.as_bytes()[3].is_ascii_digit())
+        {
+            return Err(invalid("ZIP 中含有无法跨平台安全使用的文件路径"));
+        }
+    }
+    Ok(path.to_path_buf())
+}
+fn safe_directory(name: &str) -> Result<()> {
+    let path = safe_relative(name)?;
+    if path.components().count() != 1 || name.starts_with('.') {
+        return Err(invalid("归档中的 Skill 目录名无效"));
+    }
+    Ok(())
+}
+
+fn extract<R: Read + Seek>(reader: R, destination: &Path) -> Result<()> {
+    let mut archive = zip::ZipArchive::new(reader).map_err(zip_error)?;
+    let mut seen = HashSet::new();
+    for index in 0..archive.len() {
+        let mut entry = archive.by_index(index).map_err(zip_error)?;
+        let name = entry.name().trim_end_matches('/');
+        let relative = safe_relative(name)?;
+        let mode = entry.unix_mode().unwrap_or(0) & 0o170000;
+        if mode != 0 && mode != 0o100000 && mode != 0o040000 {
+            return Err(invalid("ZIP 不支持符号链接或特殊文件"));
+        }
+        if !seen.insert(name.to_ascii_lowercase()) {
+            return Err(invalid("ZIP 中含有重复文件路径"));
+        }
+        let output = destination.join(relative);
+        if entry.is_dir() {
+            ensure_directory(&output)?;
+        } else {
+            ensure_directory(output.parent().ok_or_else(|| invalid("ZIP 路径无效"))?)?;
+            let mut file = OpenOptions::new()
+                .write(true)
+                .create_new(true)
+                .open(&output)
+                .map_err(|error| io_err(&output, error))?;
+            std::io::copy(&mut entry, &mut file).map_err(|error| io_err(&output, error))?;
+            #[cfg(unix)]
+            {
+                use std::os::unix::fs::PermissionsExt;
+                if let Some(mode) = entry.unix_mode() {
+                    fs::set_permissions(&output, fs::Permissions::from_mode(mode & 0o777))
+                        .map_err(|error| io_err(&output, error))?;
+                }
+            }
+        }
+    }
+    Ok(())
+}
+
+fn collect_entries(root: &Path, current: &Path, output: &mut Vec<PathBuf>) -> Result<()> {
+    let metadata = fs::symlink_metadata(current).map_err(|error| io_err(current, error))?;
+    if metadata.file_type().is_symlink() {
+        return Err(invalid("Skill 包含符号链接，请先替换为实际文件再导出"));
+    }
+    if metadata.is_file() {
+        output.push(
+            current
+                .strip_prefix(root)
+                .map_err(|_| invalid("Skill 文件路径无效"))?
+                .to_path_buf(),
+        );
+    } else if metadata.is_dir() {
+        if current != root {
+            output.push(
+                current
+                    .strip_prefix(root)
+                    .map_err(|_| invalid("Skill 目录路径无效"))?
+                    .to_path_buf(),
+            );
+        }
+        for entry in fs::read_dir(current).map_err(|error| io_err(current, error))? {
+            collect_entries(
+                root,
+                &entry.map_err(|error| io_err(current, error))?.path(),
+                output,
+            )?;
+        }
+    } else {
+        return Err(invalid("Skill 包含不支持的特殊文件"));
+    }
+    Ok(())
+}
+fn directory_digest(path: &Path) -> Result<Vec<u8>> {
+    let mut files = Vec::new();
+    collect_entries(path, path, &mut files)?;
+    files.sort();
+    let mut digest = Sha256::new();
+    let mut buffer = [0u8; 64 * 1024];
+    for relative in files {
+        let name = relative.to_string_lossy().replace('\\', "/");
+        digest.update((name.len() as u64).to_le_bytes());
+        digest.update(name.as_bytes());
+        let file_path = path.join(relative);
+        if file_path.is_dir() {
+            digest.update(b"directory");
+            continue;
+        }
+        digest.update(b"file");
+        let mut file = File::open(&file_path).map_err(|error| io_err(&file_path, error))?;
+        digest.update(
+            file.metadata()
+                .map_err(|error| io_err(&file_path, error))?
+                .len()
+                .to_le_bytes(),
+        );
+        loop {
+            let count = file
+                .read(&mut buffer)
+                .map_err(|error| io_err(&file_path, error))?;
+            if count == 0 {
+                break;
+            }
+            digest.update(&buffer[..count]);
+        }
+    }
+    Ok(digest.finalize().to_vec())
+}
+fn write_archive(path: &Path, manifest: &Manifest, sources: &[PathBuf]) -> Result<()> {
+    let file = OpenOptions::new()
+        .write(true)
+        .create_new(true)
+        .open(path)
+        .map_err(|error| io_err(path, error))?;
+    #[cfg(unix)]
+    {
+        use std::os::unix::fs::PermissionsExt;
+        file.set_permissions(fs::Permissions::from_mode(0o600))
+            .map_err(|error| io_err(path, error))?;
+    }
+    let mut writer = zip::ZipWriter::new(file);
+    let options = SimpleFileOptions::default()
+        .compression_method(zip::CompressionMethod::Deflated)
+        .large_file(true);
+    writer.start_file(MANIFEST, options).map_err(zip_error)?;
+    serde_json::to_writer_pretty(&mut writer, manifest).map_err(|_| invalid("无法写入归档清单"))?;
+    for (entry, source) in manifest.skills.iter().zip(sources) {
+        let mut files = Vec::new();
+        collect_entries(source, source, &mut files)?;
+        files.sort();
+        for relative in files {
+            let relative_name = relative.to_string_lossy().replace('\\', "/");
+            safe_relative(&relative_name)?;
+            let source_file = source.join(&relative);
+            let mut options = options;
+            #[cfg(unix)]
+            {
+                use std::os::unix::fs::PermissionsExt;
+                options = options.unix_permissions(
+                    fs::metadata(&source_file)
+                        .map_err(|error| io_err(&source_file, error))?
+                        .permissions()
+                        .mode()
+                        & 0o777,
+                );
+            }
+            if source_file.is_dir() {
+                writer
+                    .add_directory(format!("{}/{}/", entry.path, relative_name), options)
+                    .map_err(zip_error)?;
+                continue;
+            }
+            writer
+                .start_file(format!("{}/{}", entry.path, relative_name), options)
+                .map_err(zip_error)?;
+            let mut input =
+                File::open(&source_file).map_err(|error| io_err(&source_file, error))?;
+            std::io::copy(&mut input, &mut writer).map_err(|error| io_err(path, error))?;
+        }
+    }
+    writer
+        .finish()
+        .map_err(zip_error)?
+        .sync_all()
+        .map_err(|error| io_err(path, error))?;
+    Ok(())
+}
+
+fn destination_snapshot(path: &Path) -> Result<Option<Vec<u8>>> {
+    let metadata = match fs::symlink_metadata(path) {
+        Ok(metadata) => metadata,
+        Err(error) if error.kind() == std::io::ErrorKind::NotFound => return Ok(None),
+        Err(error) => return Err(io_err(path, error)),
+    };
+    if metadata.file_type().is_symlink() || !metadata.is_file() {
+        return Err(invalid("请选择普通 ZIP 文件路径，不能覆盖符号链接或目录"));
+    }
+    let mut file = File::open(path).map_err(|error| io_err(path, error))?;
+    let mut digest = Sha256::new();
+    let mut buffer = [0u8; 64 * 1024];
+    loop {
+        let count = file
+            .read(&mut buffer)
+            .map_err(|error| io_err(path, error))?;
+        if count == 0 {
+            break;
+        }
+        digest.update(&buffer[..count]);
+    }
+    Ok(Some(digest.finalize().to_vec()))
+}
+
+fn write_archive_atomic<BeforeReplace: FnOnce() -> Result<()>>(
+    output: &Path,
+    manifest: &Manifest,
+    sources: &[PathBuf],
+    before_replace: BeforeReplace,
+) -> Result<()> {
+    let initial = destination_snapshot(output)?;
+    let parent = output
+        .parent()
+        .ok_or_else(|| invalid("请选择有效的保存目录"))?;
+    let temporary = parent.join(unique_name("codex-x-export"));
+    let result = (|| {
+        write_archive(&temporary, manifest, sources)?;
+        before_replace()?;
+        if destination_snapshot(output)? != initial {
+            return Err(invalid(
+                "保存位置的文件已被其他程序修改，请重新选择位置再导出",
+            ));
+        }
+        fs::rename(&temporary, output).map_err(|error| io_err(output, error))
+    })();
+    if result.is_err() {
+        let _ = fs::remove_file(&temporary);
+    }
+    result
+}
+
+fn validate_export_destination(output: &Path, codex_dir: &Path) -> Result<PathBuf> {
+    if !output
+        .extension()
+        .and_then(|extension| extension.to_str())
+        .is_some_and(|extension| extension.eq_ignore_ascii_case("zip"))
+    {
+        return Err(invalid("请将导出文件保存为 .zip 格式"));
+    }
+    let parent = output
+        .parent()
+        .filter(|parent| parent.is_dir())
+        .ok_or_else(|| invalid("请选择有效的保存目录"))?;
+    let canonical_parent = fs::canonicalize(parent).map_err(|error| io_err(parent, error))?;
+    for protected in [codex_dir.to_path_buf(), app_home()?] {
+        let canonical = fs::canonicalize(&protected).unwrap_or(protected);
+        if canonical_parent.starts_with(canonical) {
+            return Err(invalid(
+                "请将 ZIP 保存到下载、桌面等目录，不要放入 Codex 配置或应用数据目录",
+            ));
+        }
+    }
+    destination_snapshot(output)?;
+    Ok(canonical_parent)
+}
+
+pub(crate) fn export_skills_mcp_archive_inner(
+    config_dir: Option<String>,
+    kind: String,
+    destination: String,
+) -> Result<SkillsMcpExportResult> {
+    if !matches!(kind.as_str(), "skills" | "mcp") {
+        return Err(invalid("请选择导出 Skills 或 MCP"));
+    }
+    let state = build_skills_mcp_state_inner(config_dir)?;
+    let mut manifest = Manifest {
+        format: FORMAT.to_owned(),
+        version: 1,
+        skills: vec![],
+        mcp_servers: vec![],
+    };
+    let mut sources = Vec::new();
+    if kind == "skills" {
+        for skill in state.skills {
+            safe_directory(&skill.directory)?;
+            manifest.skills.push(SkillEntry {
+                path: format!("skills/{}", skill.directory),
+                directory: skill.directory,
+                enabled: skill.enabled,
+                note: skill.note,
+            });
+            sources.push(PathBuf::from(skill.path));
+        }
+    } else {
+        for mcp in state.mcp_servers {
+            manifest.mcp_servers.push(McpEntry {
+                id: mcp.id,
+                name: mcp.name,
+                config: mcp.config_json,
+                enabled: mcp.enabled,
+                note: mcp.note,
+            });
+        }
+    }
+    if manifest.skills.is_empty() && manifest.mcp_servers.is_empty() {
+        return Err(invalid("当前没有可导出的内容"));
+    }
+    let output = PathBuf::from(destination);
+    let canonical_parent = validate_export_destination(&output, Path::new(&state.codex_dir))?;
+    for source in &sources {
+        let canonical_source = fs::canonicalize(source).map_err(|error| io_err(source, error))?;
+        if canonical_parent.starts_with(canonical_source) {
+            return Err(invalid("请将 ZIP 保存在 Skill 目录之外"));
+        }
+    }
+    write_archive_atomic(&output, &manifest, &sources, || Ok(()))?;
+    Ok(SkillsMcpExportResult {
+        path: output.display().to_string(),
+        exported_skills: manifest.skills.len(),
+        exported_mcp: manifest.mcp_servers.len(),
+    })
+}
+
+pub(crate) fn install_skill_archive_path_inner(
+    config_dir: Option<String>,
+    path: String,
+) -> Result<SkillsMcpActionResult> {
+    let path = Path::new(&path);
+    let file = File::open(path).map_err(|error| io_err(path, error))?;
+    install_archive_reader(
+        config_dir,
+        path.file_name()
+            .and_then(|name| name.to_str())
+            .unwrap_or("skills.zip")
+            .to_owned(),
+        file,
+    )
+}
+
+fn find_skill_roots(path: &Path, output: &mut Vec<PathBuf>) -> Result<()> {
+    if path.join("SKILL.md").is_file() {
+        output.push(path.to_path_buf());
+        return Ok(());
+    }
+    for entry in fs::read_dir(path).map_err(|error| io_err(path, error))? {
+        let entry = entry.map_err(|error| io_err(path, error))?;
+        if entry
+            .file_type()
+            .map_err(|error| io_err(path, error))?
+            .is_dir()
+        {
+            find_skill_roots(&entry.path(), output)?;
+        }
+    }
+    Ok(())
+}
+fn manifest_from_extracted(path: &Path, file_name: &str) -> Result<Manifest> {
+    let manifest_path = path.join(MANIFEST);
+    if manifest_path.exists() {
+        let file = File::open(&manifest_path).map_err(|error| io_err(&manifest_path, error))?;
+        // This limits only metadata, not ZIP contents or Skill file sizes.
+        let manifest: Manifest = serde_json::from_reader(file.take(8 * 1024 * 1024))
+            .map_err(|_| invalid("Codex-X 归档清单无效或过大"))?;
+        if manifest.format != FORMAT || manifest.version != 1 {
+            return Err(invalid("暂不支持此归档版本，请更新 Codex-X"));
+        }
+        return Ok(manifest);
+    }
+    let mut roots = Vec::new();
+    find_skill_roots(path, &mut roots)?;
+    let mut manifest = Manifest {
+        format: FORMAT.to_owned(),
+        version: 1,
+        skills: vec![],
+        mcp_servers: vec![],
+    };
+    for root in roots {
+        let fallback = if root == path {
+            file_name.trim_end_matches(".zip")
+        } else {
+            root.file_name()
+                .and_then(|name| name.to_str())
+                .unwrap_or(file_name.trim_end_matches(".zip"))
+        };
+        let (name, _) = read_skill_metadata(&root, fallback);
+        let relative = root
+            .strip_prefix(path)
+            .map_err(|_| invalid("Skill 路径无效"))?
+            .to_string_lossy()
+            .replace('\\', "/");
+        manifest.skills.push(SkillEntry {
+            directory: sanitize_dir_name(&name, "skill"),
+            path: relative,
+            enabled: true,
+            note: None,
+        });
+    }
+    Ok(manifest)
+}
+
+pub(super) fn install_archive_reader<R: Read + Seek>(
+    config_dir: Option<String>,
+    file_name: String,
+    reader: R,
+) -> Result<SkillsMcpActionResult> {
+    let temporary = TempDir::new(&app_home()?.join("tmp"))?;
+    extract(reader, &temporary.0)?;
+    let manifest = manifest_from_extracted(&temporary.0, &file_name)?;
+    let (imported_skills, imported_mcp, skipped) =
+        import_manifest(config_dir.clone(), &temporary.0, manifest)?;
+    Ok(SkillsMcpActionResult {
+        imported_skills,
+        imported_mcp,
+        message: format!(
+            "已导入 {imported_skills} 个 Skills、{imported_mcp} 个 MCP{}",
+            if skipped > 0 {
+                format!("，跳过 {skipped} 个已存在的项目")
+            } else {
+                String::new()
+            }
+        ),
+        state: build_skills_mcp_state_inner(config_dir)?,
+    })
+}
+
+fn import_manifest(
+    config_dir: Option<String>,
+    root: &Path,
+    manifest: Manifest,
+) -> Result<(usize, usize, usize)> {
+    if manifest.skills.is_empty() && manifest.mcp_servers.is_empty() {
+        return Err(invalid("ZIP 中没有可导入的 Skills 或 MCP"));
+    }
+    let codex_dir = resolve_codex_dir(config_dir.clone())?;
+    ensure_directory(&codex_dir)?;
+    let _lock = acquire_live_config_lock(&codex_dir)?;
+    let current = build_skills_mcp_state_inner(config_dir)?;
+    let cfg = config_path(&codex_dir);
+    let before = read_file_snapshot(&cfg)?;
+    let mut document = parse_toml_document(&cfg, &text_from_snapshot(&cfg, before.as_deref())?)?;
+    let mut skill_ids = HashSet::new();
+    let mut mcp_ids = HashSet::new();
+    let existing_skills: HashMap<_, _> = current
+        .skills
+        .iter()
+        .map(|skill| (skill.directory.as_str(), skill))
+        .collect();
+    let existing_mcp: HashMap<_, _> = current
+        .mcp_servers
+        .iter()
+        .map(|mcp| (mcp.id.as_str(), mcp))
+        .collect();
+    let mut skill_plan = Vec::new();
+    let mut mcp_plan = Vec::new();
+    let mut skipped = 0;
+    for skill in manifest.skills {
+        safe_directory(&skill.directory)?;
+        if !skill_ids.insert(sanitize_dir_name(&skill.directory, "skill")) {
+            return Err(invalid("归档中存在同名 Skill"));
+        }
+        let relative = if skill.path.is_empty() {
+            PathBuf::new()
+        } else {
+            safe_relative(&skill.path)?
+        };
+        let source = root.join(relative);
+        if !source.join("SKILL.md").is_file() {
+            return Err(invalid(format!("Skill {} 缺少 SKILL.md", skill.directory)));
+        }
+        if let Some(existing) = existing_skills.get(skill.directory.as_str()) {
+            if directory_digest(&source)? == directory_digest(Path::new(&existing.path))? {
+                skipped += 1;
+                continue;
+            }
+            return Err(invalid(format!(
+                "Skill「{}」已存在且内容不同。请先重命名或移除已有项目，导入不会覆盖它。",
+                skill.directory
+            )));
+        }
+        let parent = if skill.enabled {
+            codex_skills_dir(&codex_dir)
+        } else {
+            disabled_skills_dir()?
+        };
+        let destination = parent.join(&skill.directory);
+        if destination.exists() {
+            return Err(invalid(format!(
+                "Skill 目录「{}」已存在，未覆盖",
+                skill.directory
+            )));
+        }
+        skill_plan.push((skill, source, destination));
+    }
+    for mcp in manifest.mcp_servers {
+        if mcp.id.trim().is_empty()
+            || !mcp_ids.insert(mcp.id.clone())
+            || !is_valid_mcp_config(&mcp.config)
+        {
+            return Err(invalid("归档中存在无效或重复的 MCP 配置"));
+        }
+        if let Some(existing) = existing_mcp.get(mcp.id.as_str()) {
+            if mcp_configs_equal(&existing.config_json, &mcp.config) {
+                skipped += 1;
+                continue;
+            }
+            return Err(invalid(format!(
+                "MCP「{}」已存在且配置不同。请先重命名或移除已有项目，导入不会覆盖它。",
+                mcp.name
+            )));
+        }
+        // A malformed live entry is still user data; do not overwrite it.
+        if document
+            .get("mcp_servers")
+            .and_then(|item| item.as_table())
+            .is_some_and(|table| table.contains_key(&mcp.id))
+        {
+            return Err(invalid(format!("MCP「{}」已存在，未覆盖", mcp.name)));
+        }
+        mcp_plan.push(mcp);
+    }
+    let mut connection = open_db()?;
+    let transaction = connection
+        .transaction_with_behavior(TransactionBehavior::Immediate)
+        .map_err(|error| CodexxError::Database(error.to_string()))?;
+    let scope = normalized_path_scope(&codex_dir);
+    let save_note = |kind: &str, id: &str, note: &Option<String>| -> Result<()> {
+        if let Some(note) = note.as_deref().filter(|note| !note.trim().is_empty()) {
+            if note.chars().count() > super::SKILLS_MCP_NOTE_MAX_CHARS {
+                return Err(invalid("归档中的备注过长"));
+            }
+            transaction.execute("INSERT INTO skills_mcp_notes (codex_dir,item_kind,item_id,note,updated_at) VALUES (?1,?2,?3,?4,?5) ON CONFLICT(codex_dir,item_kind,item_id) DO NOTHING", params![scope, kind, id, note, now_rfc3339()]).map_err(|error| CodexxError::Database(error.to_string()))?;
+        }
+        Ok(())
+    };
+    for mcp in &mcp_plan {
+        save_managed_mcp_on_connection(&transaction, &mcp.id, &mcp.name, &mcp.config, mcp.enabled)?;
+        if mcp.enabled {
+            ensure_table(document.as_table_mut(), "mcp_servers")?
+                .insert(&mcp.id, json_to_toml_item(&mcp.config));
+        }
+        save_note("mcp", &mcp.id, &mcp.note)?;
+    }
+    for (skill, _, _) in &skill_plan {
+        save_note(
+            "skill",
+            &sanitize_dir_name(&skill.directory, "skill"),
+            &skill.note,
+        )?;
+    }
+    let mut created = Vec::new();
+    let apply = (|| -> Result<()> {
+        for (_, source, destination) in &skill_plan {
+            let staging = TempDir::new(
+                destination
+                    .parent()
+                    .ok_or_else(|| invalid("Skill 目标目录无效"))?,
+            )?;
+            copy_dir_recursive(source, &staging.0)?;
+            if destination.exists() {
+                return Err(invalid("导入期间出现同名 Skill，已停止且未覆盖"));
+            }
+            fs::rename(&staging.0, destination).map_err(|error| io_err(destination, error))?;
+            created.push(destination.clone());
+        }
+        let after = document_bytes(before.as_deref(), &document);
+        commit_mcp_transaction_with_config(
+            transaction,
+            &codex_dir,
+            before,
+            after,
+            "import-skills-mcp-zip",
+            |_| Ok(()),
+            |_| Ok(()),
+        )
+    })();
+    if apply.is_err() {
+        for path in created {
+            let _ = fs::remove_dir_all(path);
+        }
+    }
+    apply?;
+    Ok((skill_plan.len(), mcp_plan.len(), skipped))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde_json::json;
+    use std::io::{Cursor, Write};
+
+    fn manifest() -> Manifest {
+        Manifest {
+            format: FORMAT.into(),
+            version: 1,
+            skills: vec![],
+            mcp_servers: vec![],
+        }
+    }
+    fn test_dir() -> TempDir {
+        TempDir::new(&std::env::temp_dir().join("codex-x-archive-tests")).unwrap()
+    }
+    fn codex(dir: &Path) -> Option<String> {
+        fs::create_dir_all(dir).unwrap();
+        Some(dir.display().to_string())
+    }
+    fn skill(root: &Path, directory: &str, enabled: bool) -> SkillEntry {
+        let path = root.join("skills").join(directory);
+        fs::create_dir_all(&path).unwrap();
+        fs::write(
+            path.join("SKILL.md"),
+            format!("---\nname: {directory}\ndescription: Example\n---\n# Readme"),
+        )
+        .unwrap();
+        fs::write(path.join(".extra"), b"hidden file").unwrap();
+        fs::create_dir_all(path.join("empty-resources")).unwrap();
+        SkillEntry {
+            directory: directory.into(),
+            path: format!("skills/{directory}"),
+            enabled,
+            note: Some("My skill note".into()),
+        }
+    }
+    fn zip_entries(entries: &[(&str, &[u8])]) -> Vec<u8> {
+        let mut writer = zip::ZipWriter::new(Cursor::new(Vec::new()));
+        for (name, data) in entries {
+            writer
+                .start_file(
+                    *name,
+                    SimpleFileOptions::default().compression_method(zip::CompressionMethod::Stored),
+                )
+                .unwrap();
+            writer.write_all(data).unwrap();
+        }
+        writer.finish().unwrap().into_inner()
+    }
+    fn clean_mcp(id: &str) {
+        let db = open_db().unwrap();
+        db.execute("DELETE FROM managed_mcp_servers WHERE id=?1", [id])
+            .unwrap();
+        db.execute("DELETE FROM skills_mcp_notes WHERE item_id=?1", [id])
+            .unwrap();
+    }
+
+    #[test]
+    fn zip_bundle_round_trip_preserves_files_notes_disabled_skills_and_mcp_settings() {
+        let _guard = crate::app_db::test_db_guard();
+        let temporary = test_dir();
+        let source = temporary.0.join("source");
+        let destination = temporary.0.join("codex");
+        let directory = format!("archive-roundtrip-{}", std::process::id());
+        let id = format!("archive-roundtrip-mcp-{}", std::process::id());
+        clean_mcp(&id);
+        let disabled = disabled_skills_dir().unwrap().join(&directory);
+        let _ = fs::remove_dir_all(&disabled);
+        let mut bundle = manifest();
+        bundle.skills.push(skill(&source, &directory, false));
+        bundle.mcp_servers.push(McpEntry { id: id.clone(), name: "Portable MCP".into(), config: json!({"command":"example-server", "args":["--safe"], "env":{"TOKEN":"synthetic-test-token"}}), enabled: true, note: Some("MCP note".into()) });
+        let output = temporary.0.join("bundle.zip");
+        write_archive(&output, &bundle, &[source.join("skills").join(&directory)]).unwrap();
+        fs::create_dir_all(&destination).unwrap();
+        fs::write(
+            destination.join("config.toml"),
+            "# Keep this\nmodel = \"gpt-test\"\n",
+        )
+        .unwrap();
+        let imported =
+            install_skill_archive_path_inner(codex(&destination), output.display().to_string())
+                .unwrap();
+        assert_eq!((imported.imported_skills, imported.imported_mcp), (1, 1));
+        let skill = imported
+            .state
+            .skills
+            .iter()
+            .find(|skill| skill.id == directory)
+            .unwrap();
+        assert!(!skill.enabled);
+        assert_eq!(skill.note.as_deref(), Some("My skill note"));
+        assert_eq!(fs::read(disabled.join(".extra")).unwrap(), b"hidden file");
+        assert!(disabled.join("empty-resources").is_dir());
+        let mcp = imported
+            .state
+            .mcp_servers
+            .iter()
+            .find(|mcp| mcp.id == id)
+            .unwrap();
+        assert_eq!(mcp.note.as_deref(), Some("MCP note"));
+        assert!(mcp.enabled);
+        assert!(fs::read_to_string(destination.join("config.toml"))
+            .unwrap()
+            .starts_with("# Keep this"));
+        let second =
+            install_skill_archive_path_inner(codex(&destination), output.display().to_string())
+                .unwrap();
+        assert_eq!((second.imported_skills, second.imported_mcp), (0, 0));
+        fs::remove_dir_all(disabled).unwrap();
+        clean_mcp(&id);
+    }
+
+    #[test]
+    fn regular_skill_zip_larger_than_twenty_megabytes_installs_without_size_limit() {
+        let _guard = crate::app_db::test_db_guard();
+        let temporary = test_dir();
+        let payload = vec![b'x'; 21 * 1024 * 1024];
+        let bytes = zip_entries(&[
+            (
+                "package/SKILL.md",
+                b"---\nname: large-archive-fixture\n---\n",
+            ),
+            ("package/data.bin", &payload),
+        ]);
+        assert!(bytes.len() > 20 * 1024 * 1024);
+        let result = install_archive_reader(
+            codex(&temporary.0.join("codex")),
+            "large.zip".into(),
+            Cursor::new(bytes),
+        )
+        .unwrap();
+        assert_eq!(result.imported_skills, 1);
+        assert_eq!(
+            fs::metadata(
+                temporary
+                    .0
+                    .join("codex/skills/large-archive-fixture/data.bin")
+            )
+            .unwrap()
+            .len(),
+            payload.len() as u64
+        );
+    }
+
+    #[test]
+    fn conflicting_bundle_is_rejected_before_any_skill_or_mcp_is_written() {
+        let _guard = crate::app_db::test_db_guard();
+        let temporary = test_dir();
+        let source = temporary.0.join("source");
+        let destination = temporary.0.join("codex");
+        let mut bundle = manifest();
+        bundle
+            .skills
+            .push(skill(&source, "archive-new-first", true));
+        bundle
+            .skills
+            .push(skill(&source, "archive-existing-second", true));
+        let existing = destination.join("skills/archive-existing-second");
+        fs::create_dir_all(&existing).unwrap();
+        fs::write(existing.join("SKILL.md"), "original").unwrap();
+        assert!(import_manifest(codex(&destination), &source, bundle).is_err());
+        assert!(!destination.join("skills/archive-new-first").exists());
+        assert_eq!(
+            fs::read_to_string(existing.join("SKILL.md")).unwrap(),
+            "original"
+        );
+    }
+
+    #[test]
+    fn unsafe_duplicate_and_link_zip_entries_are_rejected() {
+        let temporary = test_dir();
+        for name in [
+            "../escape",
+            "/absolute",
+            "C:/drive",
+            "folder\\escape",
+            "CON.txt",
+        ] {
+            let target = TempDir::new(&temporary.0).unwrap();
+            assert!(
+                extract(Cursor::new(zip_entries(&[(name, b"unsafe")])), &target.0).is_err(),
+                "accepted {name}"
+            );
+        }
+        let target = TempDir::new(&temporary.0).unwrap();
+        assert!(extract(
+            Cursor::new(zip_entries(&[("a", b"1"), ("A", b"2")])),
+            &target.0
+        )
+        .is_err());
+        let mut writer = zip::ZipWriter::new(Cursor::new(Vec::new()));
+        writer
+            .add_symlink("link", "../outside", SimpleFileOptions::default())
+            .unwrap();
+        assert!(extract(
+            Cursor::new(writer.finish().unwrap().into_inner()),
+            &TempDir::new(&temporary.0).unwrap().0
+        )
+        .is_err());
+    }
+
+    #[test]
+    fn empty_and_unknown_version_archives_are_rejected() {
+        let _guard = crate::app_db::test_db_guard();
+        let temporary = test_dir();
+        assert!(install_archive_reader(
+            codex(&temporary.0.join("codex")),
+            "empty.zip".into(),
+            Cursor::new(zip_entries(&[("readme.txt", b"No skills")]))
+        )
+        .is_err());
+        let mut unknown = manifest();
+        unknown.version = 99;
+        let bytes = serde_json::to_vec(&unknown).unwrap();
+        assert!(install_archive_reader(
+            codex(&temporary.0.join("codex")),
+            "future.zip".into(),
+            Cursor::new(zip_entries(&[(MANIFEST, &bytes)]))
+        )
+        .is_err());
+    }
+
+    #[test]
+    fn exported_skill_archive_can_be_imported_with_original_state() {
+        let _guard = crate::app_db::test_db_guard();
+        let temporary = test_dir();
+        let source = temporary.0.join("source");
+        let destination = temporary.0.join("destination");
+        let directory = format!("archive-export-{}", std::process::id());
+        skill(&source, &directory, true);
+        let archive = temporary.0.join("export.zip");
+        let result = export_skills_mcp_archive_inner(
+            codex(&source),
+            "skills".into(),
+            archive.display().to_string(),
+        )
+        .unwrap();
+        assert!(result.exported_skills >= 1);
+        assert_eq!(result.exported_mcp, 0);
+        let imported =
+            install_skill_archive_path_inner(codex(&destination), archive.display().to_string())
+                .unwrap();
+        assert!(imported
+            .state
+            .skills
+            .iter()
+            .any(|skill| skill.directory == directory && skill.enabled));
+        assert_eq!(
+            directory_digest(&source.join("skills").join(&directory)).unwrap(),
+            directory_digest(&destination.join("skills").join(&directory)).unwrap()
+        );
+    }
+
+    #[test]
+    fn same_mcp_id_with_different_configuration_does_not_overwrite_live_config() {
+        let _guard = crate::app_db::test_db_guard();
+        let temporary = test_dir();
+        let destination = temporary.0.join("codex");
+        codex(&destination);
+        let original = "[mcp_servers.archive_conflict]\ncommand = \"existing\"\n";
+        fs::write(destination.join("config.toml"), original).unwrap();
+        let mut bundle = manifest();
+        bundle.mcp_servers.push(McpEntry {
+            id: "archive_conflict".into(),
+            name: "Conflict".into(),
+            config: json!({"command":"different"}),
+            enabled: true,
+            note: None,
+        });
+        assert!(import_manifest(codex(&destination), &temporary.0, bundle).is_err());
+        assert_eq!(
+            fs::read_to_string(destination.join("config.toml")).unwrap(),
+            original
+        );
+    }
+    #[test]
+    fn export_refuses_changed_destinations_and_cleans_temporary_output() {
+        let temporary = test_dir();
+        let output = temporary.0.join("export.zip");
+        fs::write(&output, b"before").unwrap();
+        let result = write_archive_atomic(&output, &manifest(), &[], || {
+            fs::write(&output, b"external-update").unwrap();
+            Ok(())
+        });
+        assert!(result.is_err());
+        assert_eq!(fs::read(&output).unwrap(), b"external-update");
+        assert_eq!(fs::read_dir(&temporary.0).unwrap().count(), 1);
+    }
+
+    #[test]
+    fn export_rejects_codex_data_and_non_zip_destinations() {
+        let temporary = test_dir();
+        let codex = temporary.0.join("codex");
+        fs::create_dir_all(&codex).unwrap();
+        assert!(validate_export_destination(&codex.join("backup.zip"), &codex).is_err());
+        assert!(validate_export_destination(&temporary.0.join("auth.json"), &codex).is_err());
+        assert!(validate_export_destination(&temporary.0.join("backup.zip"), &codex).is_ok());
+        #[cfg(unix)]
+        {
+            let file = temporary.0.join("original.zip");
+            fs::write(&file, "original").unwrap();
+            let link = temporary.0.join("symlink.zip");
+            std::os::unix::fs::symlink(&file, &link).unwrap();
+            assert!(validate_export_destination(&link, &codex).is_err());
+            assert_eq!(fs::read_to_string(file).unwrap(), "original");
+        }
+    }
+}

apps/desktop/src-tauri/src/skills_mcp/mcp.rs

@@ -0,0 +1,969 @@
+use super::build_skills_mcp_state_inner;
+use super::types::{ManagedMcpServer, SkillsMcpState};
+use crate::backups::create_backup;
+use crate::ccswitch::default_ccswitch_db_path;
+use crate::error::{CodexxError, Result};
+use crate::file_io::{ensure_directory, parse_toml_document, read_to_string_if_exists};
+use crate::live_config::{
+    acquire_live_config_lock, apply_file_change, fail_with_file_rollback, read_file_snapshot,
+    text_from_snapshot,
+};
+use crate::toml_utils::ensure_table;
+use crate::{config_path, now_rfc3339, open_db, resolve_codex_dir};
+use rusqlite::{
+    params, Connection, OpenFlags, OptionalExtension, Transaction, TransactionBehavior,
+};
+use serde_json::{json, Value};
+use std::collections::HashSet;
+use std::path::Path;
+use toml_edit::{value, Item, Table};
+
+type CcSwitchMcpCandidate = (String, String, Value, bool);
+
+fn toml_value_to_json(value: &toml_edit::Value) -> Value {
+    if let Some(s) = value.as_str() {
+        return json!(s);
+    }
+    if let Some(i) = value.as_integer() {
+        return json!(i);
+    }
+    if let Some(f) = value.as_float() {
+        return json!(f);
+    }
+    if let Some(b) = value.as_bool() {
+        return json!(b);
+    }
+    if let Some(table) = value.as_inline_table() {
+        return Value::Object(
+            table
+                .iter()
+                .map(|(key, value)| (key.to_owned(), toml_value_to_json(value)))
+                .collect(),
+        );
+    }
+    if let Some(arr) = value.as_array() {
+        return Value::Array(arr.iter().map(toml_value_to_json).collect());
+    }
+    Value::String(value.to_string())
+}
+
+fn toml_item_to_json(item: &Item) -> Value {
+    if let Some(v) = item.as_value() {
+        return toml_value_to_json(v);
+    }
+    if let Some(tbl) = item.as_table() {
+        let mut obj = serde_json::Map::new();
+        for (k, v) in tbl.iter() {
+            obj.insert(k.to_string(), toml_item_to_json(v));
+        }
+        return Value::Object(obj);
+    }
+    Value::Null
+}
+
+pub(super) fn json_to_toml_item(value_json: &Value) -> Item {
+    match value_json {
+        Value::String(s) => value(s.clone()),
+        Value::Bool(b) => value(*b),
+        Value::Number(n) => {
+            if let Some(i) = n.as_i64() {
+                value(i)
+            } else if let Some(f) = n.as_f64() {
+                value(f)
+            } else {
+                value(n.to_string())
+            }
+        }
+        Value::Array(arr) => {
+            let mut toml_arr = toml_edit::Array::default();
+            for item in arr {
+                match item {
+                    Value::String(s) => {
+                        toml_arr.push(s.as_str());
+                    }
+                    Value::Bool(b) => {
+                        toml_arr.push(*b);
+                    }
+                    Value::Number(n) => {
+                        if let Some(i) = n.as_i64() {
+                            toml_arr.push(i);
+                        } else if let Some(f) = n.as_f64() {
+                            toml_arr.push(f);
+                        }
+                    }
+                    _ => {}
+                }
+            }
+            value(toml_arr)
+        }
+        Value::Object(obj) => {
+            let mut table = Table::new();
+            for (k, v) in obj {
+                table.insert(k, json_to_toml_item(v));
+            }
+            Item::Table(table)
+        }
+        Value::Null => value(""),
+    }
+}
+
+pub(super) fn mcp_summary(config: &Value) -> (String, Option<String>, Option<String>, String) {
+    let transport = config
+        .get("type")
+        .and_then(Value::as_str)
+        .unwrap_or_else(|| {
+            if config.get("url").is_some() {
+                "http"
+            } else {
+                "stdio"
+            }
+        })
+        .to_string();
+    let command = config
+        .get("command")
+        .and_then(Value::as_str)
+        .map(ToString::to_string);
+    let url = config
+        .get("url")
+        .and_then(Value::as_str)
+        .map(ToString::to_string);
+    let args = config
+        .get("args")
+        .and_then(Value::as_array)
+        .map(|arr| {
+            arr.iter()
+                .filter_map(Value::as_str)
+                .collect::<Vec<_>>()
+                .join(" ")
+        })
+        .unwrap_or_default();
+    let summary = if let Some(cmd) = &command {
+        if args.is_empty() {
+            cmd.clone()
+        } else {
+            format!("{cmd} {args}")
+        }
+    } else if let Some(url) = &url {
+        url.clone()
+    } else {
+        transport.clone()
+    };
+    (transport, command, url, summary)
+}
+
+pub(super) fn save_managed_mcp_on_connection(
+    conn: &Connection,
+    id: &str,
+    name: &str,
+    config: &Value,
+    enabled: bool,
+) -> Result<()> {
+    conn.execute(
+        "INSERT INTO managed_mcp_servers (id, name, server_config, enabled, updated_at)
+         VALUES (?1, ?2, ?3, ?4, ?5)
+         ON CONFLICT(id) DO UPDATE SET
+           name = excluded.name,
+           server_config = excluded.server_config,
+           enabled = excluded.enabled,
+           updated_at = excluded.updated_at",
+        params![
+            id,
+            name,
+            serde_json::to_string(config).unwrap_or_default(),
+            enabled,
+            now_rfc3339()
+        ],
+    )
+    .map_err(|e| CodexxError::Database(e.to_string()))?;
+    Ok(())
+}
+
+pub(super) fn save_managed_mcp(id: &str, name: &str, config: &Value, enabled: bool) -> Result<()> {
+    let conn = open_db()?;
+    save_managed_mcp_on_connection(&conn, id, name, config, enabled)
+}
+
+fn managed_mcp_on_connection(conn: &Connection, id: &str) -> Result<Option<(String, Value, bool)>> {
+    conn.query_row(
+        "SELECT name, server_config, enabled FROM managed_mcp_servers WHERE id = ?1 LIMIT 1",
+        [id],
+        |row| {
+            let config_text: String = row.get(1)?;
+            Ok((
+                row.get(0)?,
+                serde_json::from_str(&config_text).unwrap_or(Value::Object(Default::default())),
+                row.get(2)?,
+            ))
+        },
+    )
+    .optional()
+    .map_err(|error| CodexxError::Database(error.to_string()))
+}
+
+fn document_mcp_ids(doc: &toml_edit::DocumentMut) -> HashSet<String> {
+    doc.get("mcp_servers")
+        .and_then(|item| item.as_table())
+        .map(|table| {
+            table
+                .iter()
+                .filter(|(_, item)| item.as_table_like().is_some())
+                .map(|(id, _)| id.to_string())
+                .collect()
+        })
+        .unwrap_or_default()
+}
+
+pub(super) fn document_bytes(
+    snapshot: Option<&[u8]>,
+    doc: &toml_edit::DocumentMut,
+) -> Option<Vec<u8>> {
+    let bytes = doc.to_string().into_bytes();
+    if snapshot.is_none() && bytes.is_empty() {
+        None
+    } else {
+        Some(bytes)
+    }
+}
+
+pub(super) fn commit_mcp_transaction_with_config<BeforeApply, BeforeCommit>(
+    transaction: Transaction<'_>,
+    codex_dir: &Path,
+    before: Option<Vec<u8>>,
+    after: Option<Vec<u8>>,
+    backup_action: &str,
+    before_apply: BeforeApply,
+    before_commit: BeforeCommit,
+) -> Result<()>
+where
+    BeforeApply: FnOnce(&Path) -> Result<()>,
+    BeforeCommit: FnOnce(&Transaction<'_>) -> Result<()>,
+{
+    let cfg = config_path(codex_dir);
+    let mut changes = Vec::new();
+    if before != after {
+        create_backup(codex_dir, backup_action)?;
+        before_apply(&cfg)?;
+        changes.push(apply_file_change(&cfg, before, after)?);
+    }
+
+    if let Err(error) = before_commit(&transaction) {
+        return fail_with_file_rollback(error, &changes);
+    }
+    if let Err(error) = transaction
+        .commit()
+        .map_err(|error| CodexxError::Database(error.to_string()))
+    {
+        return fail_with_file_rollback(error, &changes);
+    }
+    Ok(())
+}
+
+pub(super) fn db_managed_mcp() -> Result<Vec<(String, String, Value, bool)>> {
+    let conn = open_db()?;
+    let mut stmt = conn.prepare("SELECT id, name, server_config, enabled FROM managed_mcp_servers ORDER BY name ASC, id ASC")
+        .map_err(|e| CodexxError::Database(e.to_string()))?;
+    let rows = stmt
+        .query_map([], |row| {
+            let text: String = row.get(2)?;
+            let config = serde_json::from_str(&text).unwrap_or(Value::Object(Default::default()));
+            Ok((
+                row.get::<_, String>(0)?,
+                row.get::<_, String>(1)?,
+                config,
+                row.get::<_, bool>(3)?,
+            ))
+        })
+        .map_err(|e| CodexxError::Database(e.to_string()))?;
+    let mut out = Vec::new();
+    for row in rows {
+        out.push(row.map_err(|e| CodexxError::Database(e.to_string()))?);
+    }
+    Ok(out)
+}
+
+pub(super) fn list_mcp_from_config(codex_dir: &Path) -> Result<Vec<ManagedMcpServer>> {
+    let cfg = config_path(codex_dir);
+    let text = read_to_string_if_exists(&cfg)?;
+    if text.trim().is_empty() {
+        return Ok(vec![]);
+    }
+    let doc = parse_toml_document(&cfg, &text)?;
+    let Some(mcp_item) = doc.get("mcp_servers") else {
+        return Ok(vec![]);
+    };
+    let Some(mcp_tbl) = mcp_item.as_table() else {
+        return Ok(vec![]);
+    };
+    let mut out = Vec::new();
+    for (id, item) in mcp_tbl.iter() {
+        if item.as_table_like().is_none() {
+            continue;
+        }
+        let config = toml_item_to_json(item);
+        if !is_valid_mcp_config(&config) {
+            continue;
+        }
+        let (transport, command, url, summary) = mcp_summary(&config);
+        out.push(ManagedMcpServer {
+            id: id.to_string(),
+            name: id.to_string(),
+            transport,
+            enabled: config
+                .get("enabled")
+                .and_then(Value::as_bool)
+                .unwrap_or(true),
+            source: "config.toml".to_string(),
+            summary,
+            note: None,
+            command,
+            url,
+            config_json: config,
+        });
+    }
+    Ok(out)
+}
+
+pub(crate) fn sort_managed_mcp_servers(servers: &mut [ManagedMcpServer]) {
+    servers.sort_by(|a, b| {
+        a.name
+            .to_ascii_lowercase()
+            .cmp(&b.name.to_ascii_lowercase())
+            .then_with(|| a.id.cmp(&b.id))
+    });
+}
+
+pub(super) fn import_ccswitch_mcp_servers_for_codex(
+    codex_dir: &Path,
+    imported_ids: &mut HashSet<String>,
+) -> Result<usize> {
+    let candidates = new_ccswitch_mcp_candidates(codex_dir, imported_ids)?;
+
+    import_ccswitch_mcp_candidates_with_hooks(
+        codex_dir,
+        imported_ids,
+        candidates,
+        |_| Ok(()),
+        |_| Ok(()),
+    )
+}
+
+fn import_ccswitch_mcp_candidates_with_hooks<BeforeApply, BeforeCommit>(
+    codex_dir: &Path,
+    imported_ids: &mut HashSet<String>,
+    candidates: Vec<CcSwitchMcpCandidate>,
+    before_apply: BeforeApply,
+    before_commit: BeforeCommit,
+) -> Result<usize>
+where
+    BeforeApply: FnOnce(&Path) -> Result<()>,
+    BeforeCommit: FnOnce(&Transaction<'_>) -> Result<()>,
+{
+    let mut staged_ids = HashSet::new();
+    let candidates = candidates
+        .into_iter()
+        .filter(|(id, _, config, _)| {
+            is_valid_mcp_config(config)
+                && !imported_ids.contains(id)
+                && staged_ids.insert(id.clone())
+        })
+        .collect::<Vec<_>>();
+    if candidates.is_empty() {
+        return Ok(0);
+    }
+
+    ensure_directory(codex_dir)?;
+    let _live_lock = acquire_live_config_lock(codex_dir)?;
+    let cfg = config_path(codex_dir);
+    let before = read_file_snapshot(&cfg)?;
+    let text = text_from_snapshot(&cfg, before.as_deref())?;
+    let mut doc = parse_toml_document(&cfg, &text)?;
+    let live_enabled = document_mcp_ids(&doc);
+
+    let mut app_conn = open_db()?;
+    let transaction = app_conn
+        .transaction_with_behavior(TransactionBehavior::Immediate)
+        .map_err(|error| CodexxError::Database(error.to_string()))?;
+    for (id, name, config, enabled_codex) in &candidates {
+        let enabled = *enabled_codex || live_enabled.contains(id);
+        save_managed_mcp_on_connection(&transaction, id, name, config, enabled)?;
+        if *enabled_codex && !live_enabled.contains(id) {
+            ensure_table(doc.as_table_mut(), "mcp_servers")?.insert(id, json_to_toml_item(config));
+        }
+    }
+    let after = document_bytes(before.as_deref(), &doc);
+    commit_mcp_transaction_with_config(
+        transaction,
+        codex_dir,
+        before,
+        after,
+        "import-ccswitch-mcp",
+        before_apply,
+        before_commit,
+    )?;
+
+    let imported = candidates.len();
+    imported_ids.extend(staged_ids);
+    Ok(imported)
+}
+
+// Both preview and import use the same validated records. Malformed JSON is never
+// converted to an empty stdio server.
+pub(super) fn is_valid_mcp_config(config: &Value) -> bool {
+    let Some(object) = config.as_object() else {
+        return false;
+    };
+    let nonempty = |key| {
+        object
+            .get(key)
+            .and_then(Value::as_str)
+            .is_some_and(|value| !value.trim().is_empty())
+    };
+    let command = nonempty("command");
+    let url = nonempty("url");
+    if command == url {
+        return false;
+    }
+    if command
+        && object.get("args").is_some_and(|args| {
+            !args
+                .as_array()
+                .is_some_and(|values| values.iter().all(Value::is_string))
+        })
+    {
+        return false;
+    }
+    if object.get("env").is_some_and(|env| {
+        !env.as_object()
+            .is_some_and(|values| values.values().all(Value::is_string))
+    }) {
+        return false;
+    }
+    true
+}
+
+pub(super) fn mcp_configs_equal(left: &Value, right: &Value) -> bool {
+    let normalize = |value: &Value| {
+        let mut config = value.clone();
+        if let Some(object) = config.as_object_mut() {
+            // Transport is inferred from command/url by Codex; enabled is stored
+            // separately from the connection settings in managed records.
+            object.remove("type");
+            object.remove("enabled");
+            for key in ["args", "env", "http_headers", "env_http_headers"] {
+                if object.get(key).is_some_and(|value| {
+                    value.as_array().is_some_and(Vec::is_empty)
+                        || value.as_object().is_some_and(serde_json::Map::is_empty)
+                }) {
+                    object.remove(key);
+                }
+            }
+        }
+        config
+    };
+    normalize(left) == normalize(right)
+}
+
+fn normalized_ccswitch_config(config: Value, id: &str) -> Option<Value> {
+    if is_valid_mcp_config(&config) {
+        return Some(config);
+    }
+    for key in ["mcpServers", "mcp_servers"] {
+        if let Some(servers) = config.get(key).and_then(Value::as_object) {
+            let server = servers.get(id).or_else(|| {
+                (servers.len() == 1)
+                    .then(|| servers.values().next())
+                    .flatten()
+            })?;
+            if is_valid_mcp_config(server) {
+                return Some(server.clone());
+            }
+        }
+    }
+    None
+}
+
+fn read_ccswitch_mcp_candidates() -> Result<Vec<CcSwitchMcpCandidate>> {
+    let db = default_ccswitch_db_path()?;
+    if !db.exists() {
+        return Ok(vec![]);
+    }
+    let conn = Connection::open_with_flags(
+        &db,
+        OpenFlags::SQLITE_OPEN_READ_ONLY | OpenFlags::SQLITE_OPEN_NO_MUTEX,
+    )
+    .map_err(|error| CodexxError::Database(error.to_string()))?;
+    read_ccswitch_mcp_candidates_from_connection(&conn)
+}
+
+fn read_ccswitch_mcp_candidates_from_connection(
+    conn: &Connection,
+) -> Result<Vec<CcSwitchMcpCandidate>> {
+    let mut stmt = match conn
+        .prepare("SELECT id, name, server_config, enabled_codex FROM mcp_servers ORDER BY name ASC, id ASC")
+        .or_else(|_| conn.prepare("SELECT id, name, server_config, 0 FROM mcp_servers ORDER BY name ASC, id ASC")) {
+        Ok(stmt) => stmt,
+        Err(rusqlite::Error::SqliteFailure(_, Some(message))) if message.to_lowercase().contains("no such table") => return Ok(vec![]),
+        Err(error) => return Err(CodexxError::Database(error.to_string())),
+    };
+    let rows = stmt
+        .query_map([], |row| {
+            Ok((
+                row.get::<_, String>(0)?,
+                row.get::<_, String>(1)?,
+                row.get::<_, String>(2)?,
+                row.get::<_, bool>(3)?,
+            ))
+        })
+        .map_err(|error| CodexxError::Database(error.to_string()))?;
+    let mut out = Vec::new();
+    for row in rows {
+        let (id, name, text, enabled) =
+            row.map_err(|error| CodexxError::Database(error.to_string()))?;
+        if id.trim().is_empty() {
+            continue;
+        }
+        let Some(config) = serde_json::from_str(&text)
+            .ok()
+            .and_then(|config| normalized_ccswitch_config(config, &id))
+        else {
+            continue;
+        };
+        let name = if name.trim().is_empty() {
+            id.clone()
+        } else {
+            name
+        };
+        out.push((id, name, config, enabled));
+    }
+    Ok(out)
+}
+
+fn new_ccswitch_mcp_candidates(
+    codex_dir: &Path,
+    already_seen: &HashSet<String>,
+) -> Result<Vec<CcSwitchMcpCandidate>> {
+    let current = list_mcp_from_config(codex_dir)?;
+    let managed = db_managed_mcp()?;
+    let mut ids = already_seen.clone();
+    let mut configs = Vec::new();
+    for server in current {
+        ids.insert(server.id);
+        configs.push(server.config_json);
+    }
+    for (id, _, config, _) in managed {
+        ids.insert(id);
+        if is_valid_mcp_config(&config) {
+            configs.push(config);
+        }
+    }
+    let mut output = Vec::new();
+    for candidate in read_ccswitch_mcp_candidates()? {
+        if !ids.insert(candidate.0.clone())
+            || configs
+                .iter()
+                .any(|config| mcp_configs_equal(config, &candidate.2))
+        {
+            continue;
+        }
+        configs.push(candidate.2.clone());
+        output.push(candidate);
+    }
+    Ok(output)
+}
+
+pub(super) fn preview_ccswitch_mcp_servers_for_codex(
+    codex_dir: &Path,
+) -> Result<Vec<ManagedMcpServer>> {
+    let live_enabled = list_mcp_from_config(codex_dir)?
+        .into_iter()
+        .map(|server| server.id)
+        .collect::<HashSet<_>>();
+    Ok(new_ccswitch_mcp_candidates(codex_dir, &HashSet::new())?
+        .into_iter()
+        .map(|(id, name, config, enabled)| {
+            let (transport, command, url, summary) = mcp_summary(&config);
+            ManagedMcpServer {
+                enabled: enabled || live_enabled.contains(&id),
+                id,
+                name,
+                transport,
+                source: "cc-switch".to_string(),
+                summary,
+                note: None,
+                command,
+                url,
+                config_json: config,
+            }
+        })
+        .collect())
+}
+
+pub(crate) fn toggle_codex_mcp_inner(
+    config_dir: Option<String>,
+    id: String,
+    enabled: bool,
+) -> Result<SkillsMcpState> {
+    toggle_codex_mcp_with_hooks(config_dir, id, enabled, |_| Ok(()), |_| Ok(()))
+}
+
+fn toggle_codex_mcp_with_hooks<BeforeApply, BeforeCommit>(
+    config_dir: Option<String>,
+    id: String,
+    enabled: bool,
+    before_apply: BeforeApply,
+    before_commit: BeforeCommit,
+) -> Result<SkillsMcpState>
+where
+    BeforeApply: FnOnce(&Path) -> Result<()>,
+    BeforeCommit: FnOnce(&Transaction<'_>) -> Result<()>,
+{
+    let codex_dir = resolve_codex_dir(config_dir.clone())?;
+    ensure_directory(&codex_dir)?;
+    let _live_lock = acquire_live_config_lock(&codex_dir)?;
+    let cfg = config_path(&codex_dir);
+    let before = read_file_snapshot(&cfg)?;
+    let text = text_from_snapshot(&cfg, before.as_deref())?;
+    let mut doc = parse_toml_document(&cfg, &text)?;
+
+    let mut conn = open_db()?;
+    let transaction = conn
+        .transaction_with_behavior(TransactionBehavior::Immediate)
+        .map_err(|error| CodexxError::Database(error.to_string()))?;
+    let stored = managed_mcp_on_connection(&transaction, &id)?;
+    if enabled {
+        let (name, mut config, _) = stored
+            .or_else(|| {
+                doc.get("mcp_servers")
+                    .and_then(Item::as_table)
+                    .and_then(|table| table.get(&id))
+                    .map(|item| (id.clone(), toml_item_to_json(item), false))
+            })
+            .ok_or_else(|| CodexxError::Config(format!("未找到 MCP: {id}")))?;
+        if let Some(object) = config.as_object_mut() {
+            if object.contains_key("enabled") {
+                object.insert("enabled".to_owned(), Value::Bool(true));
+            }
+        }
+        ensure_table(doc.as_table_mut(), "mcp_servers")?.insert(&id, json_to_toml_item(&config));
+        save_managed_mcp_on_connection(&transaction, &id, &name, &config, true)?;
+    } else {
+        let live_config = doc
+            .get("mcp_servers")
+            .and_then(|m| m.as_table())
+            .and_then(|tbl| tbl.get(&id))
+            .map(toml_item_to_json);
+        if let Some(config) = live_config {
+            let name = stored
+                .as_ref()
+                .map(|(name, _, _)| name.as_str())
+                .unwrap_or(&id);
+            save_managed_mcp_on_connection(&transaction, &id, name, &config, false)?;
+        } else if let Some((name, config, _)) = stored {
+            save_managed_mcp_on_connection(&transaction, &id, &name, &config, false)?;
+        }
+        if let Some(tbl) = doc.get_mut("mcp_servers").and_then(|m| m.as_table_mut()) {
+            tbl.remove(&id);
+        }
+    }
+
+    let after = document_bytes(before.as_deref(), &doc);
+    commit_mcp_transaction_with_config(
+        transaction,
+        &codex_dir,
+        before,
+        after,
+        "toggle-mcp",
+        before_apply,
+        before_commit,
+    )?;
+    build_skills_mcp_state_inner(config_dir)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::fs;
+    use std::path::PathBuf;
+    use std::sync::atomic::{AtomicU64, Ordering};
+
+    fn test_case(name: &str) -> (PathBuf, String) {
+        static COUNTER: AtomicU64 = AtomicU64::new(0);
+        let suffix = COUNTER.fetch_add(1, Ordering::Relaxed);
+        let dir = std::env::temp_dir().join(format!(
+            "codex-x-mcp-{name}-{}-{suffix}",
+            std::process::id()
+        ));
+        let _ = fs::remove_dir_all(&dir);
+        fs::create_dir_all(&dir).expect("create MCP test directory");
+        (dir, format!("test-mcp-{name}-{suffix}"))
+    }
+
+    fn database_error(error: rusqlite::Error) -> CodexxError {
+        CodexxError::Database(error.to_string())
+    }
+
+    fn remove_test_mcp(id: &str) {
+        open_db()
+            .expect("open test database")
+            .execute("DELETE FROM managed_mcp_servers WHERE id = ?1", [id])
+            .expect("remove test MCP");
+    }
+
+    #[test]
+    fn enabling_existing_unmanaged_disabled_mcp_updates_enabled_flag() {
+        let _guard = crate::app_db::test_db_guard();
+        let (directory, id) = test_case("disabled-unmanaged");
+        let config = format!("[mcp_servers.\"{id}\"]\ncommand = \"fixture\"\nenabled = false\n");
+        std::fs::write(directory.join("config.toml"), config).unwrap();
+        let initial = list_mcp_from_config(&directory).unwrap();
+        assert!(!initial[0].enabled);
+        let result =
+            toggle_codex_mcp_inner(Some(directory.display().to_string()), id.clone(), true)
+                .unwrap();
+        assert!(
+            result
+                .mcp_servers
+                .iter()
+                .find(|server| server.id == id)
+                .unwrap()
+                .enabled
+        );
+        remove_test_mcp(&id);
+        std::fs::remove_dir_all(directory).unwrap();
+    }
+
+    #[test]
+    fn ccswitch_candidates_skip_empty_invalid_and_transport_only_records() {
+        let conn = Connection::open_in_memory().unwrap();
+        conn.execute_batch(
+            "CREATE TABLE mcp_servers(id TEXT,name TEXT,server_config TEXT,enabled_codex BOOLEAN)",
+        )
+        .unwrap();
+        for (id, data) in [
+            ("broken", "invalid"),
+            ("empty", "{}"),
+            ("transport", r#"{"type":"stdio"}"#),
+            ("valid", r#"{"command":"npx","args":["server"]}"#),
+            (
+                "wrapped",
+                r#"{"mcpServers":{"wrapped":{"url":"https://example.test/mcp"}}}"#,
+            ),
+        ] {
+            conn.execute(
+                "INSERT INTO mcp_servers VALUES(?1,?1,?2,0)",
+                params![id, data],
+            )
+            .unwrap();
+        }
+        let candidates = read_ccswitch_mcp_candidates_from_connection(&conn).unwrap();
+        assert_eq!(
+            candidates
+                .iter()
+                .map(|entry| entry.0.as_str())
+                .collect::<Vec<_>>(),
+            ["valid", "wrapped"]
+        );
+        assert_eq!(candidates[1].2["url"], "https://example.test/mcp");
+    }
+
+    #[test]
+    fn inline_environment_round_trip_retains_mcp_credentials() {
+        let document: toml_edit::DocumentMut =
+            "[mcp_servers.example]\ncommand = \"example\"\nenv = { TOKEN = \"synthetic\" }\n"
+                .parse()
+                .unwrap();
+        let value = toml_item_to_json(&document["mcp_servers"]["example"]);
+        assert!(is_valid_mcp_config(&value));
+        assert_eq!(value["env"]["TOKEN"], "synthetic");
+        assert_eq!(toml_item_to_json(&json_to_toml_item(&value)), value);
+    }
+
+    #[test]
+    fn toggle_updates_only_the_target_mcp_and_keeps_database_in_sync() {
+        let _db_guard = crate::app_db::test_db_guard();
+        let (codex_dir, id) = test_case("success");
+        let cfg = config_path(&codex_dir);
+        let original = b"# keep this comment\nmodel = \"gpt-5.5\"\n\n[features]\njs_repl = false\n\n[mcp_servers.existing]\ncommand = \"existing\"\n";
+        fs::write(&cfg, original).expect("seed original config");
+        save_managed_mcp(&id, "Managed", &json!({ "command": "managed" }), false)
+            .expect("seed managed MCP");
+
+        let enabled_state =
+            toggle_codex_mcp_inner(Some(codex_dir.display().to_string()), id.clone(), true)
+                .expect("enable managed MCP");
+        assert!(enabled_state
+            .mcp_servers
+            .iter()
+            .any(|server| server.id == id && server.enabled));
+        let enabled_text = fs::read_to_string(&cfg).expect("read enabled config");
+        let enabled_doc = enabled_text
+            .parse::<toml_edit::DocumentMut>()
+            .expect("parse enabled config");
+        assert!(enabled_text.contains("# keep this comment"));
+        assert_eq!(enabled_doc["features"]["js_repl"].as_bool(), Some(false));
+        assert_eq!(
+            enabled_doc["mcp_servers"]["existing"]["command"].as_str(),
+            Some("existing")
+        );
+        assert_eq!(
+            enabled_doc["mcp_servers"][&id]["command"].as_str(),
+            Some("managed")
+        );
+        let conn = open_db().expect("open test database");
+        assert!(
+            managed_mcp_on_connection(&conn, &id)
+                .expect("read enabled MCP")
+                .expect("enabled MCP exists")
+                .2
+        );
+        drop(conn);
+
+        toggle_codex_mcp_inner(Some(codex_dir.display().to_string()), id.clone(), false)
+            .expect("disable managed MCP");
+        let disabled_text = fs::read_to_string(&cfg).expect("read disabled config");
+        let disabled_doc = disabled_text
+            .parse::<toml_edit::DocumentMut>()
+            .expect("parse disabled config");
+        assert!(disabled_text.contains("# keep this comment"));
+        assert!(disabled_doc["mcp_servers"].get(&id).is_none());
+        assert_eq!(
+            disabled_doc["mcp_servers"]["existing"]["command"].as_str(),
+            Some("existing")
+        );
+        let conn = open_db().expect("open test database");
+        let (name, config, enabled) = managed_mcp_on_connection(&conn, &id)
+            .expect("read disabled MCP")
+            .expect("disabled MCP exists");
+        assert_eq!(name, "Managed");
+        assert_eq!(config["command"].as_str(), Some("managed"));
+        assert!(!enabled);
+        drop(conn);
+        assert!(codex_dir.join(".codexx-test-backups").is_dir());
+
+        remove_test_mcp(&id);
+        fs::remove_dir_all(codex_dir).expect("remove MCP test directory");
+    }
+
+    #[test]
+    fn toggle_rejects_a_stale_snapshot_without_changing_database_or_external_config() {
+        let _db_guard = crate::app_db::test_db_guard();
+        let (codex_dir, id) = test_case("stale");
+        let cfg = config_path(&codex_dir);
+        let original = b"# original\nmodel = \"gpt-5.5\"\n";
+        let external = b"# external update\nmodel = \"gpt-5.5\"\n\n[mcp_servers.external]\ncommand = \"external\"\n";
+        fs::write(&cfg, original).expect("seed original config");
+        save_managed_mcp(&id, "Managed", &json!({ "command": "managed" }), false)
+            .expect("seed managed MCP");
+
+        let error = toggle_codex_mcp_with_hooks(
+            Some(codex_dir.display().to_string()),
+            id.clone(),
+            true,
+            |path| {
+                fs::write(path, external).map_err(|error| CodexxError::Config(error.to_string()))
+            },
+            |_| Ok(()),
+        )
+        .expect_err("stale MCP toggle must fail");
+
+        assert!(error.to_string().contains("已被其他程序修改"));
+        assert_eq!(fs::read(&cfg).expect("read external config"), external);
+        let conn = open_db().expect("open test database");
+        let (_, config, enabled) = managed_mcp_on_connection(&conn, &id)
+            .expect("read managed MCP")
+            .expect("managed MCP still exists");
+        assert_eq!(config["command"].as_str(), Some("managed"));
+        assert!(!enabled);
+        drop(conn);
+
+        remove_test_mcp(&id);
+        fs::remove_dir_all(codex_dir).expect("remove MCP test directory");
+    }
+
+    #[test]
+    fn toggle_rolls_back_config_when_database_commit_fails() {
+        let _db_guard = crate::app_db::test_db_guard();
+        let (codex_dir, id) = test_case("commit");
+        let cfg = config_path(&codex_dir);
+        let original = b"# keep exact bytes\nmodel = \"gpt-5.5\"\n\n[features]\njs_repl = false\n";
+        fs::write(&cfg, original).expect("seed original config");
+        save_managed_mcp(&id, "Managed", &json!({ "command": "managed" }), false)
+            .expect("seed managed MCP");
+
+        toggle_codex_mcp_with_hooks(
+            Some(codex_dir.display().to_string()),
+            id.clone(),
+            true,
+            |_| Ok(()),
+            |transaction| {
+                transaction
+                    .execute_batch("ROLLBACK")
+                    .map_err(database_error)
+            },
+        )
+        .expect_err("database commit failure must fail the toggle");
+
+        assert_eq!(fs::read(&cfg).expect("read rolled-back config"), original);
+        let conn = open_db().expect("open test database");
+        let (_, _, enabled) = managed_mcp_on_connection(&conn, &id)
+            .expect("read managed MCP")
+            .expect("managed MCP still exists");
+        assert!(!enabled);
+        drop(conn);
+        assert!(codex_dir.join(".codexx-test-backups").is_dir());
+
+        remove_test_mcp(&id);
+        fs::remove_dir_all(codex_dir).expect("remove MCP test directory");
+    }
+
+    #[test]
+    fn ccswitch_import_rolls_back_file_database_and_ids_when_commit_fails() {
+        let _db_guard = crate::app_db::test_db_guard();
+        let (codex_dir, id) = test_case("import-commit");
+        let second_id = format!("{id}-second");
+        let cfg = config_path(&codex_dir);
+        let original = b"# import baseline\nmodel = \"gpt-5.5\"\n";
+        fs::write(&cfg, original).expect("seed original config");
+        let mut imported_ids = HashSet::new();
+
+        import_ccswitch_mcp_candidates_with_hooks(
+            &codex_dir,
+            &mut imported_ids,
+            vec![
+                (
+                    id.clone(),
+                    "Imported".to_string(),
+                    json!({ "command": "imported" }),
+                    true,
+                ),
+                (
+                    second_id.clone(),
+                    "Imported second".to_string(),
+                    json!({ "command": "imported-second" }),
+                    true,
+                ),
+            ],
+            |_| Ok(()),
+            |transaction| {
+                transaction
+                    .execute_batch("ROLLBACK")
+                    .map_err(database_error)
+            },
+        )
+        .expect_err("database commit failure must fail the import");
+
+        assert_eq!(fs::read(&cfg).expect("read rolled-back config"), original);
+        assert!(imported_ids.is_empty());
+        let conn = open_db().expect("open test database");
+        assert!(managed_mcp_on_connection(&conn, &id)
+            .expect("read imported MCP")
+            .is_none());
+        assert!(managed_mcp_on_connection(&conn, &second_id)
+            .expect("read second imported MCP")
+            .is_none());
+        drop(conn);
+        assert!(codex_dir.join(".codexx-test-backups").is_dir());
+
+        fs::remove_dir_all(codex_dir).expect("remove MCP test directory");
+    }
+}

apps/desktop/src-tauri/src/skills_mcp/mod.rs

@@ -0,0 +1,543 @@
+mod archive;
+mod mcp;
+pub(crate) use archive::{export_skills_mcp_archive_inner, install_skill_archive_path_inner};
+mod skills;
+mod types;
+
+pub(crate) use mcp::{sort_managed_mcp_servers, toggle_codex_mcp_inner};
+pub(crate) use skills::{
+    check_skill_updates_inner, install_skill_zip_inner, normalize_legacy_zip_skill_dirs,
+    sort_managed_skills, toggle_codex_skill_inner,
+};
+pub(crate) use types::{
+    ManagedMcpServer, SkillsMcpActionResult, SkillsMcpExportResult, SkillsMcpImportPreview,
+    SkillsMcpState,
+};
+
+#[cfg(test)]
+pub(crate) use skills::read_skill_metadata;
+#[cfg(test)]
+pub(crate) use types::ManagedSkill;
+
+use crate::error::Result;
+use crate::file_io::ensure_directory;
+use crate::paths::{home_dir, normalized_path_scope};
+use crate::resolve_codex_dir;
+use crate::{now_rfc3339, open_db};
+use mcp::{
+    db_managed_mcp, import_ccswitch_mcp_servers_for_codex, list_mcp_from_config, mcp_summary,
+    preview_ccswitch_mcp_servers_for_codex, save_managed_mcp,
+};
+use rusqlite::params;
+use skills::{codex_skills_dir, copy_dir_recursive, disabled_skills_dir, scan_skill_dir};
+use std::collections::{HashMap, HashSet};
+#[cfg(test)]
+use std::fs;
+use std::path::Path;
+
+const SKILLS_MCP_NOTE_MAX_CHARS: usize = 1000;
+
+fn normalized_note_item_kind(item_kind: &str) -> Result<&'static str> {
+    match item_kind.trim().to_ascii_lowercase().as_str() {
+        "skill" => Ok("skill"),
+        "mcp" => Ok("mcp"),
+        _ => Err(crate::error::CodexxError::Config(
+            "备注类型必须是 skill 或 mcp".to_string(),
+        )),
+    }
+}
+
+fn skills_mcp_notes(codex_dir: &Path) -> Result<HashMap<(String, String), String>> {
+    let conn = open_db()?;
+    let mut stmt = conn
+        .prepare(
+            "SELECT item_kind, item_id, note
+             FROM skills_mcp_notes
+             WHERE codex_dir = ?1
+             ORDER BY item_kind ASC, item_id ASC",
+        )
+        .map_err(|error| crate::error::CodexxError::Database(error.to_string()))?;
+    let rows = stmt
+        .query_map([normalized_path_scope(codex_dir)], |row| {
+            Ok((
+                (row.get::<_, String>(0)?, row.get::<_, String>(1)?),
+                row.get::<_, String>(2)?,
+            ))
+        })
+        .map_err(|error| crate::error::CodexxError::Database(error.to_string()))?;
+    let mut notes = HashMap::new();
+    for row in rows {
+        let (key, note) =
+            row.map_err(|error| crate::error::CodexxError::Database(error.to_string()))?;
+        notes.insert(key, note);
+    }
+    Ok(notes)
+}
+
+fn attach_skills_mcp_notes(
+    codex_dir: &Path,
+    skills: &mut [types::ManagedSkill],
+    mcp_servers: &mut [ManagedMcpServer],
+) -> Result<()> {
+    let notes = skills_mcp_notes(codex_dir)?;
+    for skill in skills {
+        skill.note = notes.get(&("skill".to_string(), skill.id.clone())).cloned();
+    }
+    for server in mcp_servers {
+        server.note = notes.get(&("mcp".to_string(), server.id.clone())).cloned();
+    }
+    Ok(())
+}
+
+fn extend_unmanaged_mcp_candidates(
+    output: &mut Vec<ManagedMcpServer>,
+    seen_ids: &mut HashSet<String>,
+    candidates: impl IntoIterator<Item = ManagedMcpServer>,
+) {
+    for server in candidates {
+        if seen_ids.insert(server.id.clone()) {
+            output.push(server);
+        }
+    }
+}
+
+pub(crate) fn build_skills_mcp_state_inner(config_dir: Option<String>) -> Result<SkillsMcpState> {
+    let codex_dir = resolve_codex_dir(config_dir)?;
+    let skills_dir = codex_skills_dir(&codex_dir);
+    let disabled_dir = disabled_skills_dir()?;
+    let mut warnings = Vec::new();
+    let mut skills = Vec::new();
+    let mut seen = HashSet::new();
+    if let Err(e) = normalize_legacy_zip_skill_dirs(&skills_dir) {
+        warnings.push(format!("修正 ZIP Skill 目录名失败: {e}"));
+    }
+    if let Err(e) = normalize_legacy_zip_skill_dirs(&disabled_dir) {
+        warnings.push(format!("修正已禁用 ZIP Skill 目录名失败: {e}"));
+    }
+    if let Err(e) = scan_skill_dir(&skills_dir, true, "Codex", &mut skills, &mut seen) {
+        warnings.push(e.to_string());
+    }
+    if let Err(e) = scan_skill_dir(
+        &disabled_dir,
+        false,
+        "Codex-X 已禁用",
+        &mut skills,
+        &mut seen,
+    ) {
+        warnings.push(e.to_string());
+    }
+
+    let mut mcp_servers = list_mcp_from_config(&codex_dir)?;
+    let enabled_ids: HashSet<String> = mcp_servers.iter().map(|s| s.id.clone()).collect();
+    for (id, name, config, enabled) in db_managed_mcp()? {
+        if enabled_ids.contains(&id) || !mcp::is_valid_mcp_config(&config) {
+            continue;
+        }
+        let (transport, command, url, summary) = mcp_summary(&config);
+        mcp_servers.push(ManagedMcpServer {
+            id,
+            name,
+            transport,
+            enabled,
+            source: "Codex-X".to_string(),
+            summary,
+            note: None,
+            command,
+            url,
+            config_json: config,
+        });
+    }
+    attach_skills_mcp_notes(&codex_dir, &mut skills, &mut mcp_servers)?;
+    sort_managed_mcp_servers(&mut mcp_servers);
+    sort_managed_skills(&mut skills);
+    Ok(SkillsMcpState {
+        codex_dir: codex_dir.display().to_string(),
+        codex_skills_dir: skills_dir.display().to_string(),
+        disabled_skills_dir: disabled_dir.display().to_string(),
+        skills,
+        mcp_servers,
+        warnings,
+    })
+}
+
+pub(crate) fn save_skills_mcp_note_inner(
+    config_dir: Option<String>,
+    item_kind: String,
+    id: String,
+    note: String,
+) -> Result<SkillsMcpState> {
+    let item_kind = normalized_note_item_kind(&item_kind)?;
+    if id.trim().is_empty() {
+        return Err(crate::error::CodexxError::Config(
+            "备注对象 ID 不能为空".to_string(),
+        ));
+    }
+    let id = id.as_str();
+    let note = note.trim();
+    if note.chars().count() > SKILLS_MCP_NOTE_MAX_CHARS {
+        return Err(crate::error::CodexxError::Config(format!(
+            "备注不能超过 {SKILLS_MCP_NOTE_MAX_CHARS} 个字符"
+        )));
+    }
+
+    let codex_dir = resolve_codex_dir(config_dir.clone())?;
+    let codex_dir_scope = normalized_path_scope(&codex_dir);
+    let current = build_skills_mcp_state_inner(config_dir.clone())?;
+    let exists = match item_kind {
+        "skill" => current.skills.iter().any(|skill| skill.id == id),
+        "mcp" => current.mcp_servers.iter().any(|server| server.id == id),
+        _ => false,
+    };
+    if !exists {
+        return Err(crate::error::CodexxError::Config(format!(
+            "未找到要备注的 {item_kind}: {id}"
+        )));
+    }
+
+    let conn = open_db()?;
+    if note.is_empty() {
+        conn.execute(
+            "DELETE FROM skills_mcp_notes
+             WHERE codex_dir = ?1 AND item_kind = ?2 AND item_id = ?3",
+            params![codex_dir_scope, item_kind, id],
+        )
+        .map_err(|error| crate::error::CodexxError::Database(error.to_string()))?;
+    } else {
+        conn.execute(
+            "INSERT INTO skills_mcp_notes
+                (codex_dir, item_kind, item_id, note, updated_at)
+             VALUES (?1, ?2, ?3, ?4, ?5)
+             ON CONFLICT(codex_dir, item_kind, item_id) DO UPDATE SET
+                note = excluded.note,
+                updated_at = excluded.updated_at",
+            params![codex_dir_scope, item_kind, id, note, now_rfc3339()],
+        )
+        .map_err(|error| crate::error::CodexxError::Database(error.to_string()))?;
+    }
+    build_skills_mcp_state_inner(config_dir)
+}
+
+pub(crate) fn import_existing_skills_mcp_inner(
+    config_dir: Option<String>,
+) -> Result<SkillsMcpActionResult> {
+    let codex_dir = resolve_codex_dir(config_dir.clone())?;
+    let skills_dir = codex_skills_dir(&codex_dir);
+    ensure_directory(&skills_dir)?;
+    let preview = preview_existing_skills_mcp_inner(config_dir.clone())?;
+    let mut imported_skills = 0usize;
+    for skill in preview.skills {
+        let destination = skills_dir.join(&skill.directory);
+        if !destination.exists() {
+            copy_dir_recursive(Path::new(&skill.path), &destination)?;
+            imported_skills += 1;
+        }
+    }
+
+    let mut imported_mcp_ids = db_managed_mcp()?
+        .into_iter()
+        .map(|(id, _, _, _)| id)
+        .collect::<HashSet<_>>();
+    for server in list_mcp_from_config(&codex_dir)? {
+        if !imported_mcp_ids.insert(server.id.clone()) {
+            continue;
+        }
+        // Already visible in the list: record it for deduplication without
+        // presenting it as a newly imported server.
+        save_managed_mcp(&server.id, &server.name, &server.config_json, true)?;
+    }
+    let imported_mcp = import_ccswitch_mcp_servers_for_codex(&codex_dir, &mut imported_mcp_ids)?;
+    let state = build_skills_mcp_state_inner(config_dir)?;
+    Ok(SkillsMcpActionResult {
+        imported_skills,
+        imported_mcp,
+        message: format!("已导入 {imported_skills} 个 Skills，纳管 {imported_mcp} 个 MCP"),
+        state,
+    })
+}
+
+pub(crate) fn preview_existing_skills_mcp_inner(
+    config_dir: Option<String>,
+) -> Result<SkillsMcpImportPreview> {
+    let codex_dir = resolve_codex_dir(config_dir)?;
+    let skills_dir = codex_skills_dir(&codex_dir);
+    let disabled_dir = disabled_skills_dir()?;
+    let mut warnings = Vec::new();
+    let mut skills = Vec::new();
+    let mut seen = HashSet::new();
+    let candidates = vec![
+        home_dir()?.join(".agents").join("skills"),
+        home_dir()?.join(".cc-switch").join("skills"),
+    ];
+    for base in candidates {
+        if !base.exists() {
+            continue;
+        }
+        let source = base
+            .parent()
+            .and_then(|p| p.file_name())
+            .map(|s| s.to_string_lossy().to_string())
+            .unwrap_or_else(|| "外部目录".to_string());
+        let before = skills.len();
+        if let Err(e) = scan_skill_dir(&base, false, &source, &mut skills, &mut seen) {
+            warnings.push(e.to_string());
+        }
+        for skill in &mut skills[before..] {
+            if skills_dir.join(&skill.directory).exists()
+                || disabled_dir.join(&skill.directory).exists()
+            {
+                skill.update_status = "已存在，将跳过".to_string();
+            } else {
+                skill.update_status = "可导入".to_string();
+            }
+        }
+    }
+    let mut candidate_ids = HashSet::new();
+    skills.retain(|skill| {
+        skill.update_status != "已存在，将跳过"
+            && candidate_ids.insert(skill.directory.to_ascii_lowercase())
+    });
+
+    let mut config_mcp_servers = list_mcp_from_config(&codex_dir)?;
+    for server in &mut config_mcp_servers {
+        server.source = "config.toml".to_string();
+    }
+    let mut seen_mcp = db_managed_mcp()?
+        .into_iter()
+        .map(|(id, _, _, _)| id)
+        .collect::<HashSet<_>>();
+    let mut mcp_servers = Vec::new();
+    seen_mcp.extend(config_mcp_servers.into_iter().map(|server| server.id));
+    extend_unmanaged_mcp_candidates(
+        &mut mcp_servers,
+        &mut seen_mcp,
+        preview_ccswitch_mcp_servers_for_codex(&codex_dir)?,
+    );
+    sort_managed_skills(&mut skills);
+    sort_managed_mcp_servers(&mut mcp_servers);
+    Ok(SkillsMcpImportPreview {
+        skills,
+        mcp_servers,
+        warnings,
+    })
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde_json::json;
+
+    fn mcp_candidate(id: &str, source: &str) -> ManagedMcpServer {
+        ManagedMcpServer {
+            id: id.to_string(),
+            name: id.to_string(),
+            transport: "stdio".to_string(),
+            enabled: true,
+            source: source.to_string(),
+            summary: id.to_string(),
+            note: None,
+            command: Some(id.to_string()),
+            url: None,
+            config_json: json!({ "command": id }),
+        }
+    }
+
+    #[test]
+    fn mcp_import_preview_excludes_managed_and_duplicate_ids() {
+        let mut seen = HashSet::from(["alpha".to_string()]);
+        let mut candidates = Vec::new();
+        extend_unmanaged_mcp_candidates(
+            &mut candidates,
+            &mut seen,
+            [
+                mcp_candidate("alpha", "config.toml"),
+                mcp_candidate("beta", "config.toml"),
+            ],
+        );
+        extend_unmanaged_mcp_candidates(
+            &mut candidates,
+            &mut seen,
+            [
+                mcp_candidate("beta", "cc-switch"),
+                mcp_candidate("gamma", "cc-switch"),
+            ],
+        );
+
+        assert_eq!(
+            candidates
+                .iter()
+                .map(|server| (server.id.as_str(), server.source.as_str()))
+                .collect::<Vec<_>>(),
+            vec![("beta", "config.toml"), ("gamma", "cc-switch")]
+        );
+
+        let mut imported_ids = seen;
+        let mut second_preview = Vec::new();
+        extend_unmanaged_mcp_candidates(
+            &mut second_preview,
+            &mut imported_ids,
+            [
+                mcp_candidate("alpha", "config.toml"),
+                mcp_candidate("beta", "config.toml"),
+                mcp_candidate("gamma", "cc-switch"),
+            ],
+        );
+        assert!(second_preview.is_empty());
+    }
+
+    #[test]
+    fn custom_notes_are_isolated_by_kind_and_codex_home_and_empty_text_clears_them() {
+        let _db_guard = crate::app_db::test_db_guard();
+        let item_id = format!("shared-note-item-{}", std::process::id());
+        let spaced_id = " spaced-mcp ";
+        let codex_dir =
+            std::env::temp_dir().join(format!("codex-x-note-state-{}", std::process::id()));
+        let other_codex_dir =
+            std::env::temp_dir().join(format!("codex-x-note-state-other-{}", std::process::id()));
+        let prepare_codex_dir = |dir: &Path| {
+            let _ = fs::remove_dir_all(dir);
+            let skill_dir = dir.join("skills").join(&item_id);
+            fs::create_dir_all(&skill_dir).expect("create test skill directory");
+            fs::write(
+                skill_dir.join("SKILL.md"),
+                format!("---\nname: {item_id}\ndescription: test\n---\n"),
+            )
+            .expect("write test skill");
+            fs::write(
+                dir.join("config.toml"),
+                format!(
+                    "[mcp_servers.{item_id}]\ncommand = \"test-server\"\n\
+                     [mcp_servers.\"{spaced_id}\"]\ncommand = \"spaced-server\"\n"
+                ),
+            )
+            .expect("write test MCP config");
+        };
+        prepare_codex_dir(&codex_dir);
+        prepare_codex_dir(&other_codex_dir);
+
+        let conn = open_db().expect("open app database");
+        conn.execute(
+            "DELETE FROM skills_mcp_notes WHERE item_id IN (?1, ?2)",
+            params![&item_id, spaced_id],
+        )
+        .expect("clear stale test notes");
+        drop(conn);
+        let config_dir = Some(codex_dir.display().to_string());
+
+        save_skills_mcp_note_inner(
+            config_dir.clone(),
+            "skill".to_string(),
+            item_id.clone(),
+            "  我的 Skill 备注  ".to_string(),
+        )
+        .expect("save skill note");
+        let state = save_skills_mcp_note_inner(
+            config_dir.clone(),
+            "mcp".to_string(),
+            item_id.clone(),
+            "MCP note".to_string(),
+        )
+        .expect("save MCP note");
+        assert_eq!(
+            state
+                .skills
+                .iter()
+                .find(|skill| skill.id == item_id)
+                .and_then(|skill| skill.note.as_deref()),
+            Some("我的 Skill 备注")
+        );
+        assert_eq!(
+            state
+                .mcp_servers
+                .iter()
+                .find(|server| server.id == item_id)
+                .and_then(|server| server.note.as_deref()),
+            Some("MCP note")
+        );
+        let state = save_skills_mcp_note_inner(
+            config_dir.clone(),
+            "mcp".to_string(),
+            spaced_id.to_string(),
+            "Spaced ID note".to_string(),
+        )
+        .expect("save note without normalizing the MCP ID");
+        assert_eq!(
+            state
+                .mcp_servers
+                .iter()
+                .find(|server| server.id == spaced_id)
+                .and_then(|server| server.note.as_deref()),
+            Some("Spaced ID note")
+        );
+
+        let other_config_dir = Some(other_codex_dir.display().to_string());
+        let other_state = build_skills_mcp_state_inner(other_config_dir.clone())
+            .expect("load other CODEX_HOME state");
+        assert!(other_state
+            .mcp_servers
+            .iter()
+            .find(|server| server.id == item_id)
+            .is_some_and(|server| server.note.is_none()));
+        save_skills_mcp_note_inner(
+            other_config_dir,
+            "mcp".to_string(),
+            item_id.clone(),
+            "Other MCP note".to_string(),
+        )
+        .expect("save note for other CODEX_HOME");
+        let original_state = build_skills_mcp_state_inner(config_dir.clone())
+            .expect("reload original CODEX_HOME state");
+        assert_eq!(
+            original_state
+                .mcp_servers
+                .iter()
+                .find(|server| server.id == item_id)
+                .and_then(|server| server.note.as_deref()),
+            Some("MCP note")
+        );
+
+        let state = save_skills_mcp_note_inner(
+            config_dir.clone(),
+            "skill".to_string(),
+            item_id.clone(),
+            "  ".to_string(),
+        )
+        .expect("clear skill note");
+        assert!(state
+            .skills
+            .iter()
+            .find(|skill| skill.id == item_id)
+            .is_some_and(|skill| skill.note.is_none()));
+        assert_eq!(
+            state
+                .mcp_servers
+                .iter()
+                .find(|server| server.id == item_id)
+                .and_then(|server| server.note.as_deref()),
+            Some("MCP note")
+        );
+        assert!(save_skills_mcp_note_inner(
+            config_dir.clone(),
+            "unknown".to_string(),
+            item_id.clone(),
+            "note".to_string(),
+        )
+        .is_err());
+        assert!(save_skills_mcp_note_inner(
+            config_dir,
+            "mcp".to_string(),
+            item_id.clone(),
+            "x".repeat(SKILLS_MCP_NOTE_MAX_CHARS + 1),
+        )
+        .is_err());
+
+        let conn = open_db().expect("reopen app database");
+        conn.execute(
+            "DELETE FROM skills_mcp_notes WHERE item_id IN (?1, ?2)",
+            params![&item_id, spaced_id],
+        )
+        .expect("remove test notes");
+        drop(conn);
+        fs::remove_dir_all(&codex_dir).expect("remove test Codex directory");
+        fs::remove_dir_all(&other_codex_dir).expect("remove other test Codex directory");
+    }
+}

apps/desktop/src-tauri/src/skills_mcp/skills.rs

@@ -0,0 +1,547 @@
+use super::build_skills_mcp_state_inner;
+use super::types::{CcSwitchSkillMeta, ManagedSkill, SkillsMcpActionResult, SkillsMcpState};
+use crate::ccswitch::default_ccswitch_db_path;
+use crate::error::{CodexxError, Result};
+use crate::file_io::{ensure_directory, io_err, read_to_string_if_exists};
+use crate::paths::app_home;
+use crate::{now_rfc3339, open_db, resolve_codex_dir};
+use rusqlite::{params, Connection, OpenFlags};
+use std::collections::{HashMap, HashSet};
+use std::fs;
+use std::io::{Cursor, Read};
+use std::path::{Path, PathBuf};
+
+pub(super) fn codex_skills_dir(codex_dir: &Path) -> PathBuf {
+    codex_dir.join("skills")
+}
+
+pub(super) fn disabled_skills_dir() -> Result<PathBuf> {
+    Ok(app_home()?.join("disabled-skills"))
+}
+
+pub(super) fn sanitize_dir_name(input: &str, fallback: &str) -> String {
+    let raw = input.trim().trim_matches('/').trim_matches('\\');
+    let base = if raw.is_empty() { fallback } else { raw };
+    let mut out = String::new();
+    let mut last_dash = false;
+    for ch in base.to_ascii_lowercase().chars() {
+        if ch.is_ascii_alphanumeric() || ch == '_' || ch == '-' {
+            out.push(ch);
+            last_dash = false;
+        } else if !last_dash {
+            out.push('-');
+            last_dash = true;
+        }
+    }
+    let out = out.trim_matches('-');
+    if out.is_empty() {
+        fallback.to_string()
+    } else {
+        out.to_string()
+    }
+}
+
+pub(super) fn copy_dir_recursive(src: &Path, dst: &Path) -> Result<()> {
+    ensure_directory(dst)?;
+    for entry in fs::read_dir(src).map_err(|e| io_err(src, e))? {
+        let entry = entry.map_err(|e| io_err(src, e))?;
+        let path = entry.path();
+        let file_name = entry.file_name();
+        let target = dst.join(file_name);
+        let meta = fs::symlink_metadata(&path).map_err(|e| io_err(&path, e))?;
+        if meta.file_type().is_symlink() {
+            continue;
+        }
+        if meta.is_dir() {
+            copy_dir_recursive(&path, &target)?;
+        } else if meta.is_file() {
+            if let Some(parent) = target.parent() {
+                ensure_directory(parent)?;
+            }
+            fs::copy(&path, &target).map_err(|e| io_err(&target, e))?;
+        }
+    }
+    Ok(())
+}
+
+fn compute_dir_hash(dir: &Path) -> Result<String> {
+    use sha2::{Digest, Sha256};
+    fn collect(base: &Path, current: &Path, out: &mut Vec<PathBuf>) -> Result<()> {
+        for entry in fs::read_dir(current).map_err(|e| io_err(current, e))? {
+            let entry = entry.map_err(|e| io_err(current, e))?;
+            let path = entry.path();
+            let name = entry.file_name().to_string_lossy().to_string();
+            if name.starts_with('.') {
+                continue;
+            }
+            let meta = fs::symlink_metadata(&path).map_err(|e| io_err(&path, e))?;
+            if meta.file_type().is_symlink() {
+                continue;
+            }
+            if meta.is_dir() {
+                collect(base, &path, out)?;
+            } else if meta.is_file() {
+                out.push(path);
+            }
+        }
+        let _ = base;
+        Ok(())
+    }
+    let mut files = Vec::new();
+    collect(dir, dir, &mut files)?;
+    files.sort();
+    let mut hasher = Sha256::new();
+    for path in files {
+        let rel = path
+            .strip_prefix(dir)
+            .unwrap_or(&path)
+            .to_string_lossy()
+            .replace('\\', "/");
+        hasher.update(rel.as_bytes());
+        hasher.update(b"\0");
+        let mut file = fs::File::open(&path).map_err(|e| io_err(&path, e))?;
+        let mut buffer = [0u8; 64 * 1024];
+        loop {
+            let size = file.read(&mut buffer).map_err(|e| io_err(&path, e))?;
+            if size == 0 {
+                break;
+            }
+            hasher.update(&buffer[..size]);
+        }
+        hasher.update(b"\0");
+    }
+    Ok(format!("{:x}", hasher.finalize()))
+}
+
+fn clean_skill_metadata_value(value: &str) -> String {
+    value
+        .trim()
+        .trim_matches('`')
+        .trim_matches('"')
+        .trim_matches('\'')
+        .trim()
+        .to_string()
+}
+
+pub(crate) fn read_skill_metadata(skill_dir: &Path, fallback: &str) -> (String, Option<String>) {
+    let skill_md = skill_dir.join("SKILL.md");
+    let text = read_to_string_if_exists(&skill_md).unwrap_or_default();
+    let mut frontmatter_name: Option<String> = None;
+    let mut frontmatter_desc: Option<String> = None;
+    let mut heading_title: Option<String> = None;
+    let mut body_desc: Option<String> = None;
+    let mut in_frontmatter = false;
+    let mut frontmatter_seen = false;
+
+    for (index, line) in text.lines().enumerate() {
+        let trimmed = line.trim();
+        if index == 0 && trimmed == "---" {
+            in_frontmatter = true;
+            frontmatter_seen = true;
+            continue;
+        }
+        if in_frontmatter {
+            if trimmed == "---" {
+                in_frontmatter = false;
+                continue;
+            }
+            if let Some((key, value)) = trimmed.split_once(':') {
+                let key = key.trim().to_ascii_lowercase();
+                let value = clean_skill_metadata_value(value);
+                if key == "name" && frontmatter_name.is_none() && !value.is_empty() {
+                    frontmatter_name = Some(value);
+                } else if key == "description" && frontmatter_desc.is_none() && !value.is_empty() {
+                    frontmatter_desc = Some(value);
+                }
+            }
+            continue;
+        }
+        if trimmed.is_empty() {
+            continue;
+        }
+        if heading_title.is_none() && trimmed.starts_with('#') {
+            heading_title = Some(trimmed.trim_start_matches('#').trim().to_string());
+            continue;
+        }
+        if body_desc.is_none()
+            && !trimmed.starts_with('#')
+            && !trimmed.starts_with("---")
+            && !frontmatter_seen
+        {
+            body_desc = Some(clean_skill_metadata_value(trimmed));
+            break;
+        }
+    }
+
+    let title = frontmatter_name
+        .or(heading_title)
+        .filter(|s| !s.is_empty())
+        .unwrap_or_else(|| fallback.to_string());
+    let desc = frontmatter_desc.or(body_desc).filter(|s| !s.is_empty());
+    (title, desc)
+}
+
+pub(crate) fn normalize_legacy_zip_skill_dirs(base: &Path) -> Result<()> {
+    if !base.exists() {
+        return Ok(());
+    }
+    for entry in fs::read_dir(base).map_err(|e| io_err(base, e))? {
+        let entry = entry.map_err(|e| io_err(base, e))?;
+        let path = entry.path();
+        if !path.is_dir() || !path.join("SKILL.md").is_file() {
+            continue;
+        }
+        let directory = entry.file_name().to_string_lossy().to_string();
+        if !directory.starts_with("skill-zip-") {
+            continue;
+        }
+        let (name, _) = read_skill_metadata(&path, &directory);
+        let dst_name = sanitize_dir_name(&name, "skill");
+        if dst_name == directory || dst_name.starts_with("skill-zip-") {
+            continue;
+        }
+        let dst = base.join(dst_name);
+        if dst.exists() {
+            continue;
+        }
+        fs::rename(&path, &dst).map_err(|e| io_err(&dst, e))?;
+    }
+    Ok(())
+}
+
+fn save_managed_skill(skill: &ManagedSkill) -> Result<()> {
+    let conn = open_db()?;
+    conn.execute(
+        "INSERT INTO managed_skills (id, name, description, directory, source_path, content_hash, enabled, updated_at)
+         VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8)
+         ON CONFLICT(id) DO UPDATE SET
+           name = excluded.name,
+           description = excluded.description,
+           directory = excluded.directory,
+           source_path = excluded.source_path,
+           content_hash = excluded.content_hash,
+           enabled = excluded.enabled,
+           updated_at = excluded.updated_at",
+        params![
+            skill.id,
+            skill.name,
+            skill.description,
+            skill.directory,
+            skill.path,
+            skill.content_hash,
+            skill.enabled,
+            now_rfc3339()
+        ],
+    ).map_err(|e| CodexxError::Database(e.to_string()))?;
+    Ok(())
+}
+
+pub(super) fn scan_skill_dir(
+    base: &Path,
+    enabled: bool,
+    source: &str,
+    out: &mut Vec<ManagedSkill>,
+    seen: &mut HashSet<String>,
+) -> Result<()> {
+    if !base.exists() {
+        return Ok(());
+    }
+    for entry in fs::read_dir(base).map_err(|e| io_err(base, e))? {
+        let entry = entry.map_err(|e| io_err(base, e))?;
+        let path = entry.path();
+        if !path.is_dir() || !path.join("SKILL.md").is_file() {
+            continue;
+        }
+        let directory = entry.file_name().to_string_lossy().to_string();
+        let id = sanitize_dir_name(&directory, "skill");
+        if seen.contains(&id) {
+            continue;
+        }
+        let (name, description) = read_skill_metadata(&path, &directory);
+        let hash = compute_dir_hash(&path).ok();
+        out.push(ManagedSkill {
+            id: id.clone(),
+            name,
+            description,
+            note: None,
+            directory,
+            enabled,
+            source: source.to_string(),
+            path: path.display().to_string(),
+            content_hash: hash,
+            update_status: "未检查".to_string(),
+        });
+        seen.insert(id);
+    }
+    Ok(())
+}
+
+pub(crate) fn sort_managed_skills(skills: &mut [ManagedSkill]) {
+    skills.sort_by(|a, b| {
+        a.name
+            .to_ascii_lowercase()
+            .cmp(&b.name.to_ascii_lowercase())
+            .then_with(|| a.id.cmp(&b.id))
+    });
+}
+
+fn move_dir_replace(src: &Path, dst: &Path) -> Result<()> {
+    if !src.exists() {
+        return Ok(());
+    }
+    if dst.exists() {
+        fs::remove_dir_all(dst).map_err(|e| io_err(dst, e))?;
+    }
+    fs::rename(src, dst)
+        .or_else(|_| {
+            copy_dir_recursive(src, dst).map(|_| {
+                let _ = fs::remove_dir_all(src);
+            })
+        })
+        .map_err(|e| {
+            CodexxError::Config(format!(
+                "移动目录失败 {} -> {}: {e}",
+                src.display(),
+                dst.display()
+            ))
+        })
+}
+
+pub(crate) fn toggle_codex_skill_inner(
+    config_dir: Option<String>,
+    id: String,
+    enabled: bool,
+) -> Result<SkillsMcpState> {
+    let codex_dir = resolve_codex_dir(config_dir.clone())?;
+    let skills_dir = codex_skills_dir(&codex_dir);
+    let disabled_dir = disabled_skills_dir()?;
+    ensure_directory(&skills_dir)?;
+    ensure_directory(&disabled_dir)?;
+    let current_state = build_skills_mcp_state_inner(config_dir.clone())?;
+    let name = current_state
+        .skills
+        .iter()
+        .find(|skill| skill.id == id)
+        .map(|skill| skill.directory.clone())
+        .unwrap_or_else(|| sanitize_dir_name(&id, "skill"));
+    let enabled_path = skills_dir.join(&name);
+    let disabled_path = disabled_dir.join(&name);
+    if enabled {
+        if disabled_path.exists() {
+            move_dir_replace(&disabled_path, &enabled_path)
+                .map_err(|e| CodexxError::Config(format!("启用 Skill 失败: {e}")))?;
+        }
+    } else if enabled_path.exists() {
+        move_dir_replace(&enabled_path, &disabled_path)
+            .map_err(|e| CodexxError::Config(format!("禁用 Skill 失败: {e}")))?;
+    }
+    build_skills_mcp_state_inner(config_dir)
+}
+
+pub(crate) fn install_skill_zip_inner(
+    config_dir: Option<String>,
+    file_name: String,
+    bytes: Vec<u8>,
+) -> Result<SkillsMcpActionResult> {
+    super::archive::install_archive_reader(config_dir, file_name, Cursor::new(bytes))
+}
+
+fn ccswitch_skill_meta_by_directory() -> Result<HashMap<String, CcSwitchSkillMeta>> {
+    let db = default_ccswitch_db_path()?;
+    if !db.exists() {
+        return Ok(HashMap::new());
+    }
+    let conn = Connection::open_with_flags(
+        &db,
+        OpenFlags::SQLITE_OPEN_READ_ONLY | OpenFlags::SQLITE_OPEN_NO_MUTEX,
+    )
+    .map_err(|e| {
+        CodexxError::Database(format!(
+            "打开 cc-switch Skills 数据库失败 {}: {e}",
+            db.display()
+        ))
+    })?;
+    let mut stmt = match conn.prepare(
+        "SELECT directory, repo_owner, repo_name, repo_branch, content_hash FROM skills
+         WHERE repo_owner IS NOT NULL AND repo_name IS NOT NULL",
+    ) {
+        Ok(stmt) => stmt,
+        Err(rusqlite::Error::SqliteFailure(_, Some(message)))
+            if message.to_lowercase().contains("no such table") =>
+        {
+            return Ok(HashMap::new());
+        }
+        Err(e) => return Err(CodexxError::Database(e.to_string())),
+    };
+    let rows = stmt
+        .query_map([], |row| {
+            Ok((
+                row.get::<_, String>(0)?,
+                row.get::<_, Option<String>>(1)?,
+                row.get::<_, Option<String>>(2)?,
+                row.get::<_, Option<String>>(3)?,
+                row.get::<_, Option<String>>(4)?,
+            ))
+        })
+        .map_err(|e| CodexxError::Database(e.to_string()))?;
+
+    let mut out = HashMap::new();
+    for row in rows {
+        let (directory, owner, repo, branch, content_hash) =
+            row.map_err(|e| CodexxError::Database(e.to_string()))?;
+        let (Some(repo_owner), Some(repo_name)) = (owner, repo) else {
+            continue;
+        };
+        out.insert(
+            directory.to_ascii_lowercase(),
+            CcSwitchSkillMeta {
+                repo_owner,
+                repo_name,
+                repo_branch: branch.unwrap_or_else(|| "main".to_string()),
+                content_hash,
+            },
+        );
+    }
+    Ok(out)
+}
+
+fn download_repo_skill_hashes(
+    owner: &str,
+    repo: &str,
+    branch: &str,
+) -> std::result::Result<HashMap<String, String>, String> {
+    use sha2::{Digest, Sha256};
+    const MAX_ZIP_BYTES: u64 = 100 * 1024 * 1024;
+    let url = format!("https://github.com/{owner}/{repo}/archive/refs/heads/{branch}.zip");
+    let agent = ureq::AgentBuilder::new()
+        .timeout(std::time::Duration::from_secs(18))
+        .build();
+    let response = agent
+        .get(&url)
+        .set("User-Agent", "Codex-X")
+        .call()
+        .map_err(|e| format!("下载 {owner}/{repo}@{branch} 失败: {e}"))?;
+    let mut bytes = Vec::new();
+    response
+        .into_reader()
+        .take(MAX_ZIP_BYTES + 1)
+        .read_to_end(&mut bytes)
+        .map_err(|e| format!("读取 {owner}/{repo}@{branch} ZIP 失败: {e}"))?;
+    if bytes.len() as u64 > MAX_ZIP_BYTES {
+        return Err(format!("{owner}/{repo}@{branch} ZIP 超过 100MB"));
+    }
+
+    let mut archive = zip::ZipArchive::new(Cursor::new(bytes))
+        .map_err(|e| format!("解析 {owner}/{repo}@{branch} ZIP 失败: {e}"))?;
+    let mut files = Vec::<(String, Vec<u8>)>::new();
+    for i in 0..archive.len() {
+        let mut file = archive
+            .by_index(i)
+            .map_err(|e| format!("读取 ZIP 条目失败: {e}"))?;
+        if file.is_dir() {
+            continue;
+        }
+        let Some(path) = file.enclosed_name().map(|p| p.to_path_buf()) else {
+            continue;
+        };
+        let normalized = path.to_string_lossy().replace('\\', "/");
+        if normalized
+            .split('/')
+            .any(|part| part.starts_with('.') && part != ".")
+        {
+            continue;
+        }
+        let mut data = Vec::new();
+        file.read_to_end(&mut data)
+            .map_err(|e| format!("读取 ZIP 文件失败: {e}"))?;
+        files.push((normalized, data));
+    }
+
+    let mut prefixes = HashMap::<String, String>::new();
+    for (path, _) in &files {
+        if !path.ends_with("/SKILL.md") && path != "SKILL.md" {
+            continue;
+        }
+        let Some(prefix) = path.strip_suffix("/SKILL.md") else {
+            continue;
+        };
+        let Some(name) = prefix.rsplit('/').next() else {
+            continue;
+        };
+        prefixes.insert(name.to_ascii_lowercase(), prefix.to_string());
+    }
+
+    let mut hashes = HashMap::new();
+    for (skill_name, prefix) in prefixes {
+        let prefix_with_slash = format!("{prefix}/");
+        let mut scoped = files
+            .iter()
+            .filter_map(|(path, data)| {
+                path.strip_prefix(&prefix_with_slash)
+                    .map(|rel| (rel.to_string(), data.as_slice()))
+            })
+            .collect::<Vec<_>>();
+        scoped.sort_by(|a, b| a.0.cmp(&b.0));
+        let mut hasher = Sha256::new();
+        for (rel, data) in scoped {
+            hasher.update(rel.as_bytes());
+            hasher.update(b"\0");
+            hasher.update(data);
+            hasher.update(b"\0");
+        }
+        hashes.insert(skill_name, format!("{:x}", hasher.finalize()));
+    }
+    Ok(hashes)
+}
+
+pub(crate) fn check_skill_updates_inner(config_dir: Option<String>) -> Result<SkillsMcpState> {
+    let mut next = build_skills_mcp_state_inner(config_dir)?;
+    let conn = open_db()?;
+    let ccswitch_meta = ccswitch_skill_meta_by_directory().unwrap_or_default();
+    let mut remote_hash_cache = HashMap::<
+        (String, String, String),
+        std::result::Result<HashMap<String, String>, String>,
+    >::new();
+    for skill in &mut next.skills {
+        let old: Option<String> = conn
+            .query_row(
+                "SELECT content_hash FROM managed_skills WHERE id = ?1",
+                [&skill.id],
+                |row| row.get(0),
+            )
+            .ok();
+        let local_status = match (&old, &skill.content_hash) {
+            (Some(a), Some(b)) if a != b => "本地有变化".to_string(),
+            (Some(_), Some(_)) => "已是最新".to_string(),
+            _ => "已记录".to_string(),
+        };
+        let meta = ccswitch_meta.get(&skill.directory.to_ascii_lowercase());
+        skill.update_status = if let Some(meta) = meta {
+            let key = (
+                meta.repo_owner.clone(),
+                meta.repo_name.clone(),
+                meta.repo_branch.clone(),
+            );
+            let remote = remote_hash_cache
+                .entry(key.clone())
+                .or_insert_with(|| download_repo_skill_hashes(&key.0, &key.1, &key.2));
+            match remote {
+                Ok(remote_hashes) => {
+                    let remote_hash = remote_hashes.get(&skill.directory.to_ascii_lowercase());
+                    let local_hash = skill.content_hash.as_ref().or(meta.content_hash.as_ref());
+                    match (local_hash, remote_hash) {
+                        (Some(local), Some(remote)) if local != remote => "有新版本".to_string(),
+                        (Some(_), Some(_)) => "已是最新".to_string(),
+                        (_, Some(_)) => "已记录远程".to_string(),
+                        _ => "未找到远程目录".to_string(),
+                    }
+                }
+                Err(e) => format!("远程检查失败：{e}"),
+            }
+        } else {
+            local_status
+        };
+        save_managed_skill(skill)?;
+    }
+    Ok(next)
+}