✨ feat(sidebar): 表新建查询展开全部字段而非 select *

- 新建查询时通过 DBGetColumns 拉取字段并生成 SELECT 列表
- 元数据不可用时回退 SELECT *，消息队列仍保持 LIMIT 预览
- 覆盖 V2/旧版右键菜单与表总览入口，补充模板单测

Refs #710

.containerignore

@@ -0,0 +1,18 @@
+.git
+.github
+.idea
+.ace-tool
+.playwright-mcp
+.superpowers
+.worktrees
+bin
+build
+dist
+frontend/dist
+node_modules
+frontend/node_modules
+tools/__pycache__
+GoNavi-Wails
+GoNavi-Wails.exe
+optional-driver-agent
+optional-driver-agent.exe

.dockerignore

@@ -0,0 +1,18 @@
+.git
+.github
+.idea
+.ace-tool
+.playwright-mcp
+.superpowers
+.worktrees
+bin
+build
+dist
+frontend/dist
+node_modules
+frontend/node_modules
+tools/__pycache__
+GoNavi-Wails
+GoNavi-Wails.exe
+optional-driver-agent
+optional-driver-agent.exe

.github/actions/publish-vps-mirror/action.yml

@@ -0,0 +1,213 @@
+name: Publish VPS download mirror
+description: Verify, upload, and atomically publish a GoNavi release to the VPS mirror
+
+inputs:
+  channel:
+    description: stable or dev
+    required: true
+  app-tag:
+    description: Physical application release directory name
+    required: true
+  app-dir:
+    description: Directory containing application release assets
+    required: true
+  app-manifest:
+    description: Application latest manifest path
+    required: true
+  driver-enabled:
+    description: Whether this deployment must publish driver assets
+    required: true
+  driver-tag:
+    description: Physical driver release directory name
+    required: false
+    default: ''
+  driver-dir:
+    description: Directory containing driver release assets
+    required: false
+    default: ''
+  driver-version-index:
+    description: Versioned driver index path
+    required: false
+    default: ''
+  driver-latest-index:
+    description: Mutable latest driver index path
+    required: false
+    default: ''
+  ssh-host:
+    description: Mirror origin SSH host
+    required: true
+  ssh-port:
+    description: Mirror origin SSH port
+    required: true
+  ssh-user:
+    description: Unprivileged mirror deployment user
+    required: true
+  ssh-private-key:
+    description: SSH private key for the deployment user
+    required: true
+  ssh-known-hosts:
+    description: Pinned known_hosts entry for the mirror origin
+    required: true
+
+runs:
+  using: composite
+  steps:
+    - name: Prepare, upload, and commit mirror payload
+      shell: bash
+      env:
+        MIRROR_CHANNEL: ${{ inputs.channel }}
+        MIRROR_APP_TAG: ${{ inputs.app-tag }}
+        MIRROR_APP_DIR: ${{ inputs.app-dir }}
+        MIRROR_APP_MANIFEST: ${{ inputs.app-manifest }}
+        MIRROR_DRIVER_ENABLED: ${{ inputs.driver-enabled }}
+        MIRROR_DRIVER_TAG: ${{ inputs.driver-tag }}
+        MIRROR_DRIVER_DIR: ${{ inputs.driver-dir }}
+        MIRROR_DRIVER_VERSION_INDEX: ${{ inputs.driver-version-index }}
+        MIRROR_DRIVER_LATEST_INDEX: ${{ inputs.driver-latest-index }}
+        MIRROR_SSH_HOST: ${{ inputs.ssh-host }}
+        MIRROR_SSH_PORT: ${{ inputs.ssh-port }}
+        MIRROR_SSH_USER: ${{ inputs.ssh-user }}
+        MIRROR_SSH_PRIVATE_KEY: ${{ inputs.ssh-private-key }}
+        MIRROR_SSH_KNOWN_HOSTS: ${{ inputs.ssh-known-hosts }}
+      run: |
+        set -euo pipefail
+        mirror_root="/srv/gonavi-downloads"
+        [[ "${MIRROR_CHANNEL}" == "stable" || "${MIRROR_CHANNEL}" == "dev" ]] || {
+          echo "Invalid mirror channel: ${MIRROR_CHANNEL}" >&2
+          exit 1
+        }
+        [[ "${GITHUB_RUN_ID:-}" =~ ^[0-9]+$ && "${GITHUB_RUN_ATTEMPT:-}" =~ ^[0-9]+$ ]] || {
+          echo "Invalid GitHub run identity" >&2
+          exit 1
+        }
+        deployment_id="${MIRROR_CHANNEL}-${GITHUB_RUN_ID}-${GITHUB_RUN_ATTEMPT}"
+        stage_dir="${RUNNER_TEMP}/gonavi-vps-mirror-${deployment_id}"
+        ssh_dir="${RUNNER_TEMP}/gonavi-vps-ssh-${deployment_id}"
+        remote_stage="${mirror_root}/.incoming/${deployment_id}"
+        effective_driver_tag=""
+        remote=""
+        remote_cleanup_enabled=false
+        ssh_options=()
+
+        cleanup() {
+          local exit_code=$?
+          local cleanup_remote_command=""
+          trap - EXIT
+          set +e
+          if [[ "${remote_cleanup_enabled}" == true && -n "${remote}" ]]; then
+            printf -v cleanup_remote_command 'rm -rf -- %q' "${remote_stage}"
+            ssh "${ssh_options[@]}" "${remote}" "${cleanup_remote_command}" >/dev/null 2>&1 || true
+          fi
+          rm -rf -- "${ssh_dir}" "${stage_dir}"
+          exit "${exit_code}"
+        }
+        trap cleanup EXIT
+
+        [[ "${MIRROR_SSH_PORT}" =~ ^[0-9]+$ ]] || {
+          echo "Invalid mirror SSH port" >&2
+          exit 1
+        }
+        mkdir -p "${ssh_dir}"
+        chmod 0700 "${ssh_dir}"
+        printf '%s\n' "${MIRROR_SSH_PRIVATE_KEY}" > "${ssh_dir}/id_ed25519"
+        printf '%s\n' "${MIRROR_SSH_KNOWN_HOSTS}" > "${ssh_dir}/known_hosts"
+        chmod 0600 "${ssh_dir}/id_ed25519" "${ssh_dir}/known_hosts"
+        ssh-keygen -y -f "${ssh_dir}/id_ed25519" >/dev/null
+
+        prepare_args=(
+          --channel "${MIRROR_CHANNEL}"
+          --app-tag "${MIRROR_APP_TAG}"
+          --app-dir "${MIRROR_APP_DIR}"
+          --app-manifest "${MIRROR_APP_MANIFEST}"
+          --output "${stage_dir}"
+        )
+        case "${MIRROR_DRIVER_ENABLED}" in
+          true)
+            [[ -n "${MIRROR_DRIVER_TAG}" ]] || {
+              echo "Driver mirror publication is enabled but driver-tag is empty" >&2
+              exit 1
+            }
+            [[ -n "${MIRROR_DRIVER_DIR}" && -d "${MIRROR_DRIVER_DIR}" ]] || {
+              echo "Driver mirror publication is enabled but driver-dir is missing" >&2
+              exit 1
+            }
+            [[ -n "$(find "${MIRROR_DRIVER_DIR}" -maxdepth 1 -type f -print -quit)" ]] || {
+              echo "Driver mirror publication is enabled but driver-dir is empty" >&2
+              exit 1
+            }
+            [[ -n "${MIRROR_DRIVER_VERSION_INDEX}" && -s "${MIRROR_DRIVER_VERSION_INDEX}" ]] || {
+              echo "Driver mirror publication is enabled but driver-version-index is missing or empty" >&2
+              exit 1
+            }
+            [[ -n "${MIRROR_DRIVER_LATEST_INDEX}" && -s "${MIRROR_DRIVER_LATEST_INDEX}" ]] || {
+              echo "Driver mirror publication is enabled but driver-latest-index is missing or empty" >&2
+              exit 1
+            }
+            effective_driver_tag="${MIRROR_DRIVER_TAG}"
+            prepare_args+=(
+              --driver-tag "${effective_driver_tag}"
+              --driver-dir "${MIRROR_DRIVER_DIR}"
+              --driver-version-index "${MIRROR_DRIVER_VERSION_INDEX}"
+              --driver-latest-index "${MIRROR_DRIVER_LATEST_INDEX}"
+            )
+            ;;
+          false)
+            echo "Driver mirror publication explicitly disabled"
+            ;;
+          *)
+            echo "Invalid driver-enabled value: ${MIRROR_DRIVER_ENABLED}" >&2
+            exit 1
+            ;;
+        esac
+        python3 "${GITHUB_WORKSPACE}/tools/prepare-vps-release-payload.py" "${prepare_args[@]}"
+        cp "${GITHUB_WORKSPACE}/tools/vps-release-commit.sh" "${stage_dir}/vps-release-commit.sh"
+        chmod 0755 "${stage_dir}/vps-release-commit.sh"
+
+        ssh_options=(
+          -i "${ssh_dir}/id_ed25519"
+          -p "${MIRROR_SSH_PORT}"
+          -o BatchMode=yes
+          -o IdentitiesOnly=yes
+          -o StrictHostKeyChecking=yes
+          -o "UserKnownHostsFile=${ssh_dir}/known_hosts"
+        )
+        remote="${MIRROR_SSH_USER}@${MIRROR_SSH_HOST}"
+        printf -v stale_cleanup_script '%s\n' \
+          'set -euo pipefail' \
+          "root=$(printf '%q' "${mirror_root}")" \
+          'marker="$(cat "${root}/.gonavi-mirror-root" 2>/dev/null || true)"' \
+          '[[ "${marker}" == "gonavi-download-mirror-v1" ]] || { echo "mirror root marker is missing or invalid" >&2; exit 1; }' \
+          'incoming="${root}/.incoming"' \
+          'mkdir -p "${incoming}"' \
+          'find "${incoming}" -mindepth 1 -maxdepth 1 -type d -mmin +1440 -exec rm -rf -- {} +'
+        printf -v stale_cleanup_command 'bash -c %q' "${stale_cleanup_script}"
+        ssh "${ssh_options[@]}" "${remote}" "${stale_cleanup_command}"
+
+        payload_bytes="$(python3 -c 'import json,sys; print(json.load(open(sys.argv[1]))["payloadBytes"])' "${stage_dir}/deployment.json")"
+        available_kib="$(ssh "${ssh_options[@]}" "${remote}" "LC_ALL=C df -Pk '${mirror_root}' | awk 'NR == 2 { print \$4 }'")"
+        [[ "${available_kib}" =~ ^[0-9]+$ ]] || {
+          echo "Mirror origin returned an invalid free space value: ${available_kib:-<empty>}" >&2
+          exit 1
+        }
+        available_bytes="$((available_kib * 1024))"
+        required_bytes="$((payload_bytes + 2000000000))"
+        if (( available_bytes < required_bytes )); then
+          echo "Mirror origin has insufficient free space: available=${available_bytes} required=${required_bytes}" >&2
+          exit 1
+        fi
+
+        remote_cleanup_enabled=true
+        ssh "${ssh_options[@]}" "${remote}" "mkdir -p '${remote_stage}'"
+        rsync -rlt --delete --partial \
+          --chmod=Du=rwx,Dgo=rx,Fu=rw,Fgo=r \
+          -e "ssh -i ${ssh_dir}/id_ed25519 -p ${MIRROR_SSH_PORT} -o BatchMode=yes -o IdentitiesOnly=yes -o StrictHostKeyChecking=yes -o UserKnownHostsFile=${ssh_dir}/known_hosts" \
+          "${stage_dir}/" "${remote}:${remote_stage}/"
+
+        printf -v remote_command 'bash %q %q %q %q %q %q' \
+          "${remote_stage}/vps-release-commit.sh" \
+          "${mirror_root}" \
+          "${remote_stage}" \
+          "${MIRROR_CHANNEL}" \
+          "${MIRROR_APP_TAG}" \
+          "${effective_driver_tag}"
+        ssh "${ssh_options[@]}" "${remote}" "${remote_command}"

.github/workflows/docker-images.yml

@@ -0,0 +1,260 @@
+name: Docker Images
+
+on:
+  push:
+    branches:
+      - dev
+    tags:
+      - 'v*'
+
+concurrency:
+  group: docker-images-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+  packages: write
+
+jobs:
+  build:
+    name: Build ${{ matrix.image_name }} (${{ matrix.platform }})
+    runs-on: ${{ matrix.runner }}
+    strategy:
+      fail-fast: false
+      matrix:
+        image_name:
+          - gonavi-mcp-server
+          - gonavi-web-server
+          - gonavi-build-env
+        platform:
+          - linux/amd64
+          - linux/arm64
+        include:
+          - image_name: gonavi-mcp-server
+            dockerfile: Dockerfile.mcp-server
+            description: GoNavi MCP Server container image
+          - image_name: gonavi-web-server
+            dockerfile: Dockerfile.web-server
+            description: GoNavi Web Server (browser UI) container image
+          - image_name: gonavi-build-env
+            dockerfile: Dockerfile.build-env
+            description: GoNavi Linux build environment image
+          - platform: linux/amd64
+            runner: ubuntu-latest
+          - platform: linux/arm64
+            runner: ubuntu-24.04-arm
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v5
+
+      - name: Validate runtime Dockerfiles
+        if: matrix.image_name == 'gonavi-web-server'
+        shell: bash
+        run: |
+          set -euo pipefail
+          bash tools/validate-web-server-dockerfile.test.sh
+          env_file="$(mktemp)"
+          trap 'rm -f "$env_file"' EXIT
+          printf 'GONAVI_HOST_DATA_ROOT=%s\nGONAVI_WEB_PASSWORD=123456\n' "${RUNNER_TEMP}/gonavi-data" >"$env_file"
+          rendered="$(docker compose --env-file "$env_file" -f docker-compose.web-server.yml config)"
+          grep -Eq "GONAVI_WEB_PASSWORD: ['\"]?123456['\"]?$" <<<"$rendered"
+
+      - name: Prepare build variables
+        id: prep
+        shell: bash
+        run: |
+          set -euo pipefail
+          echo "owner_lc=$(printf '%s' "${GITHUB_REPOSITORY_OWNER}" | tr '[:upper:]' '[:lower:]')" >> "$GITHUB_OUTPUT"
+          echo "platform_pair=$(printf '%s' "${{ matrix.platform }}" | tr '/' '-')" >> "$GITHUB_OUTPUT"
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Log in to GHCR
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Extract Docker metadata
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ghcr.io/${{ steps.prep.outputs.owner_lc }}/${{ matrix.image_name }}
+          labels: |
+            org.opencontainers.image.title=${{ matrix.image_name }}
+            org.opencontainers.image.description=${{ matrix.description }}
+            org.opencontainers.image.licenses=Apache-2.0
+
+      - name: Build smoke image
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          file: ${{ matrix.dockerfile }}
+          platforms: ${{ matrix.platform }}
+          load: true
+          tags: codex-smoke/${{ matrix.image_name }}:local
+          cache-from: type=gha,scope=${{ matrix.image_name }}-${{ steps.prep.outputs.platform_pair }}
+
+      - name: Smoke test MCP Server image
+        if: matrix.image_name == 'gonavi-mcp-server'
+        shell: bash
+        run: |
+          set -euo pipefail
+          cid="$(docker run -d -p 8765:8765 -e GONAVI_MCP_HTTP_TOKEN=smoke-token codex-smoke/${{ matrix.image_name }}:local http)"
+          trap 'docker rm -f "$cid" >/dev/null 2>&1 || true' EXIT
+          for _ in 1 2 3 4 5 6 7 8 9 10; do
+            if curl --fail --silent http://127.0.0.1:8765/healthz >/dev/null; then
+              exit 0
+            fi
+            sleep 1
+          done
+          docker logs "$cid"
+          echo "MCP Server image smoke test failed" >&2
+          exit 1
+
+      - name: Smoke test Web Server image
+        if: matrix.image_name == 'gonavi-web-server'
+        shell: bash
+        run: |
+          set -euo pipefail
+          cookie_jar="$(mktemp)"
+          cid=""
+          trap 'rm -f "$cookie_jar"; if [[ -n "$cid" ]]; then docker rm -f "$cid" >/dev/null 2>&1 || true; fi' EXIT
+          cid="$(docker run -d -p 127.0.0.1::34116 -e GONAVI_WEB_ADDR=0.0.0.0:34116 -e GONAVI_WEB_PASSWORD=123456 codex-smoke/${{ matrix.image_name }}:local web-server)"
+          host_port="$(docker port "$cid" 34116/tcp | awk -F: 'NR == 1 { print $NF }')"
+          if [[ ! "$host_port" =~ ^[0-9]+$ ]]; then
+            docker logs "$cid"
+            echo "Failed to resolve the Web Server smoke-test port" >&2
+            exit 1
+          fi
+          base_url="http://127.0.0.1:${host_port}"
+          ready=false
+          for _ in 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20; do
+            if curl --fail --silent "${base_url}/__gonavi/healthz" >/dev/null; then
+              ready=true
+              break
+            fi
+            sleep 1
+          done
+          if [[ "$ready" != "true" ]]; then
+            docker logs "$cid"
+            echo "Web Server image smoke test failed" >&2
+            exit 1
+          fi
+          status="$(curl --fail --silent --show-error "${base_url}/__gonavi/auth/status")"
+          grep -Fq '"configured":true' <<<"$status"
+          login="$(curl --fail --silent --show-error -c "$cookie_jar" -H 'Content-Type: application/json' -d '{"password":"123456","code":""}' "${base_url}/__gonavi/auth/login")"
+          grep -Fq '"success":true' <<<"$login"
+          app_status="$(curl --silent --show-error -o /dev/null -w '%{http_code}' -b "$cookie_jar" "${base_url}/")"
+          [[ "$app_status" == "200" ]]
+
+      - name: Smoke test build environment image
+        if: matrix.image_name == 'gonavi-build-env'
+        shell: bash
+        run: |
+          set -euo pipefail
+          docker run --rm codex-smoke/${{ matrix.image_name }}:local \
+            bash -lc 'go version && node -v && npm -v && wails version'
+
+      - name: Push by digest
+        id: push
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          file: ${{ matrix.dockerfile }}
+          platforms: ${{ matrix.platform }}
+          labels: ${{ steps.meta.outputs.labels }}
+          tags: ghcr.io/${{ steps.prep.outputs.owner_lc }}/${{ matrix.image_name }}
+          outputs: type=image,push-by-digest=true,name-canonical=true,push=true
+          cache-from: type=gha,scope=${{ matrix.image_name }}-${{ steps.prep.outputs.platform_pair }}
+          cache-to: type=gha,mode=max,scope=${{ matrix.image_name }}-${{ steps.prep.outputs.platform_pair }}
+
+      - name: Export digest
+        shell: bash
+        run: |
+          set -euo pipefail
+          mkdir -p "${{ runner.temp }}/digests"
+          digest="${{ steps.push.outputs.digest }}"
+          touch "${{ runner.temp }}/digests/${digest#sha256:}"
+
+      - name: Upload digest
+        uses: actions/upload-artifact@v4
+        with:
+          name: digests-${{ matrix.image_name }}-${{ steps.prep.outputs.platform_pair }}
+          path: ${{ runner.temp }}/digests/*
+          if-no-files-found: error
+          retention-days: 1
+
+  merge:
+    name: Publish ${{ matrix.image_name }}
+    runs-on: ubuntu-latest
+    needs: build
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - image_name: gonavi-mcp-server
+            description: GoNavi MCP Server container image
+          - image_name: gonavi-web-server
+            description: GoNavi Web Server (browser UI) container image
+          - image_name: gonavi-build-env
+            description: GoNavi Linux build environment image
+    steps:
+      - name: Normalize image namespace
+        id: vars
+        shell: bash
+        run: |
+          set -euo pipefail
+          echo "owner_lc=$(printf '%s' "${GITHUB_REPOSITORY_OWNER}" | tr '[:upper:]' '[:lower:]')" >> "$GITHUB_OUTPUT"
+
+      - name: Download digests
+        uses: actions/download-artifact@v4
+        with:
+          path: ${{ runner.temp }}/digests
+          pattern: digests-${{ matrix.image_name }}-*
+          merge-multiple: true
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Log in to GHCR
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Extract Docker metadata
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ghcr.io/${{ steps.vars.outputs.owner_lc }}/${{ matrix.image_name }}
+          flavor: |
+            latest=false
+          tags: |
+            type=raw,value=dev-latest,enable=${{ github.ref == 'refs/heads/dev' }}
+            type=sha,format=short,prefix=dev-,enable=${{ github.ref == 'refs/heads/dev' }}
+            type=semver,pattern={{version}},enable=${{ startsWith(github.ref, 'refs/tags/v') }}
+            type=semver,pattern={{major}}.{{minor}},enable=${{ startsWith(github.ref, 'refs/tags/v') }}
+            type=raw,value=latest,enable=${{ startsWith(github.ref, 'refs/tags/v') }}
+          labels: |
+            org.opencontainers.image.title=${{ matrix.image_name }}
+            org.opencontainers.image.description=${{ matrix.description }}
+            org.opencontainers.image.licenses=Apache-2.0
+
+      - name: Create manifest list and push
+        working-directory: ${{ runner.temp }}/digests
+        shell: bash
+        run: |
+          set -euo pipefail
+          docker buildx imagetools create \
+            $(jq -cr '.tags | map("-t " + .) | join(" ")' <<< "$DOCKER_METADATA_OUTPUT_JSON") \
+            $(printf 'ghcr.io/${{ steps.vars.outputs.owner_lc }}/${{ matrix.image_name }}@sha256:%s ' *)
+
+      - name: Inspect image
+        shell: bash
+        run: |
+          set -euo pipefail
+          docker buildx imagetools inspect "ghcr.io/${{ steps.vars.outputs.owner_lc }}/${{ matrix.image_name }}:${{ steps.meta.outputs.version }}"

.github/workflows/issue-claim.yml

@@ -0,0 +1,293 @@
+# 评论认领：在 Issue 下评论「我想做」等关键词后，自动指派/标记认领人。
+# 说明：
+# - 仓库协作者（write 及以上）可成功写入 Assignees
+# - 外部贡献者若无写权限，GitHub 不允许设为 assignee；此时会打 claimed 标签并回复确认
+# - 支持取消认领：取消认领 / /unclaim
+name: Issue Claim
+
+on:
+  issue_comment:
+    types: [created]
+
+permissions:
+  issues: write
+  contents: read
+
+jobs:
+  claim:
+    name: Auto claim or unclaim
+    if: ${{ !github.event.issue.pull_request }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Process claim / unclaim comment
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const issue = context.payload.issue;
+            const comment = context.payload.comment;
+            const actor = comment.user.login;
+            const actorType = comment.user.type;
+
+            // 忽略机器人自己的评论，避免循环
+            if (actorType === 'Bot') {
+              core.info('Skip bot comment');
+              return;
+            }
+
+            const raw = (comment.body || '').replace(/\r\n/g, '\n').trim();
+            if (!raw) {
+              return;
+            }
+
+            // 仅认领短指令：整段或首行匹配，避免长讨论误触发
+            const firstLine = raw.split('\n').map((l) => l.trim()).find(Boolean) || '';
+            const normalize = (s) =>
+              s
+                .replace(/^[@/]/g, '')
+                .replace(/[！!。．.、,，\s]+$/g, '')
+                .trim()
+                .toLowerCase();
+
+            const claimPhrases = new Set([
+              '我想做',
+              '我来做',
+              '我来',
+              '认领',
+              '我认领',
+              'claim',
+              'i claim',
+              'i want this',
+              'i will take this',
+              'assign me',
+            ]);
+            const unclaimPhrases = new Set([
+              '取消认领',
+              '不认领了',
+              '放弃认领',
+              'unclaim',
+              'release',
+            ]);
+
+            const nFull = normalize(raw);
+            const nFirst = normalize(firstLine);
+            // 允许 /claim /unclaim 形式
+            const slash = firstLine.match(/^\/(claim|unclaim)\b/i);
+            const isClaim =
+              claimPhrases.has(nFull) ||
+              claimPhrases.has(nFirst) ||
+              (slash && slash[1].toLowerCase() === 'claim');
+            const isUnclaim =
+              unclaimPhrases.has(nFull) ||
+              unclaimPhrases.has(nFirst) ||
+              (slash && slash[1].toLowerCase() === 'unclaim');
+
+            if (!isClaim && !isUnclaim) {
+              core.info('Comment is not a claim/unclaim command');
+              return;
+            }
+
+            const owner = context.repo.owner;
+            const repo = context.repo.repo;
+            const issue_number = issue.number;
+            const CLAIMED_LABEL = 'claimed';
+
+            async function ensureClaimedLabel() {
+              try {
+                await github.rest.issues.getLabel({ owner, repo, name: CLAIMED_LABEL });
+              } catch (e) {
+                if (e.status !== 404) throw e;
+                await github.rest.issues.createLabel({
+                  owner,
+                  repo,
+                  name: CLAIMED_LABEL,
+                  color: '0E8A16',
+                  description: '已被社区认领，进行中',
+                });
+              }
+            }
+
+            async function ensureLabels(names) {
+              const current = new Set((issue.labels || []).map((l) => (typeof l === 'string' ? l : l.name)));
+              const toAdd = names.filter((n) => !current.has(n));
+              if (toAdd.length) {
+                await github.rest.issues.addLabels({ owner, repo, issue_number, labels: toAdd });
+              }
+            }
+
+            async function removeLabels(names) {
+              for (const name of names) {
+                try {
+                  await github.rest.issues.removeLabel({ owner, repo, issue_number, name });
+                } catch (e) {
+                  if (e.status !== 404) throw e;
+                }
+              }
+            }
+
+            async function tryAssign(login) {
+              try {
+                await github.rest.issues.addAssignees({
+                  owner,
+                  repo,
+                  issue_number,
+                  assignees: [login],
+                });
+                return { ok: true };
+              } catch (e) {
+                const msg = e.message || String(e);
+                core.warning(`assign failed for ${login}: ${msg}`);
+                return { ok: false, message: msg };
+              }
+            }
+
+            async function tryUnassign(login) {
+              try {
+                await github.rest.issues.removeAssignees({
+                  owner,
+                  repo,
+                  issue_number,
+                  assignees: [login],
+                });
+                return { ok: true };
+              } catch (e) {
+                core.warning(`unassign failed for ${login}: ${e.message || e}`);
+                return { ok: false };
+              }
+            }
+
+            // 从 issue 正文底部的认领锚点解析当前认领人
+            const CLAIM_MARKER_RE =
+              /<!--\s*gonavi-claim\s*:\s*([A-Za-z0-9-]+)\s*-->/;
+            const body = issue.body || '';
+            const markerMatch = body.match(CLAIM_MARKER_RE);
+            const markerClaimer = markerMatch ? markerMatch[1] : null;
+            const assignees = (issue.assignees || []).map((a) => a.login);
+            const currentClaimer = assignees[0] || markerClaimer || null;
+            const hasClaimedLabel = (issue.labels || []).some(
+              (l) => (typeof l === 'string' ? l : l.name) === CLAIMED_LABEL
+            );
+
+            if (isUnclaim) {
+              if (!currentClaimer && !hasClaimedLabel) {
+                await github.rest.issues.createComment({
+                  owner,
+                  repo,
+                  issue_number,
+                  body: `ℹ️ @${actor} 当前无人认领，无需取消。`,
+                });
+                return;
+              }
+              if (currentClaimer && currentClaimer.toLowerCase() !== actor.toLowerCase()) {
+                // 仅认领人本人可取消；维护者可强制取消
+                const isMaintainer = ['OWNER', 'MEMBER', 'COLLABORATOR'].includes(
+                  context.payload.comment.author_association
+                );
+                if (!isMaintainer) {
+                  await github.rest.issues.createComment({
+                    owner,
+                    repo,
+                    issue_number,
+                    body: `⚠️ @${actor} 本 Issue 当前由 @${currentClaimer} 认领。请对方评论 \`取消认领\`，或联系维护者。`,
+                  });
+                  return;
+                }
+              }
+
+              const who = currentClaimer || actor;
+              await tryUnassign(who);
+              await removeLabels([CLAIMED_LABEL]);
+
+              let newBody = body;
+              if (CLAIM_MARKER_RE.test(newBody)) {
+                newBody = newBody
+                  .replace(/\n?<!--\s*gonavi-claim\s*:\s*[A-Za-z0-9-]+\s*-->\s*/g, '\n')
+                  .replace(/\n?### 🔐 认领状态[\s\S]*?(?=\n## |\n# |$)/, '\n')
+                  .trimEnd();
+                await github.rest.issues.update({ owner, repo, issue_number, body: newBody });
+              }
+
+              await github.rest.issues.createComment({
+                owner,
+                repo,
+                issue_number,
+                body: `🔓 @${actor} 已取消认领${who !== actor ? `（原认领人 @${who}）` : ''}。其他人可评论 \`我想做\` 重新认领。`,
+              });
+              return;
+            }
+
+            // —— claim ——
+            if (currentClaimer && currentClaimer.toLowerCase() !== actor.toLowerCase()) {
+              await github.rest.issues.createComment({
+                owner,
+                repo,
+                issue_number,
+                body: `⚠️ @${actor} 本 Issue 已由 @${currentClaimer} 认领。\n\n- 若对方长期无进展，可评论提醒，或由维护者 \`取消认领\` 后重开\n- 你也可以先在本线程说明想做的方向，维护者可协助拆分子任务`,
+              });
+              return;
+            }
+
+            if (currentClaimer && currentClaimer.toLowerCase() === actor.toLowerCase()) {
+              await github.rest.issues.createComment({
+                owner,
+                repo,
+                issue_number,
+                body: `✅ @${actor} 你已经是本 Issue 的认领人，无需重复认领。开干吧 💪`,
+              });
+              return;
+            }
+
+            await ensureClaimedLabel();
+            const assignResult = await tryAssign(actor);
+            await ensureLabels([CLAIMED_LABEL]);
+
+            // 在正文写入可机读认领锚点（assignee 失败时仍可防双认领）
+            const stamp = new Date().toISOString().slice(0, 10);
+            const claimBlock =
+              `\n\n### 🔐 认领状态\n\n` +
+              `- 认领人：@${actor}\n` +
+              `- 认领日期：${stamp}\n` +
+              `- 取消方式：评论 \`取消认领\` 或 \`/unclaim\`\n` +
+              `<!-- gonavi-claim: ${actor} -->\n`;
+
+            let newBody = body;
+            if (CLAIM_MARKER_RE.test(newBody)) {
+              newBody = newBody.replace(
+                CLAIM_MARKER_RE,
+                `<!-- gonavi-claim: ${actor} -->`
+              );
+              if (!/### 🔐 认领状态/.test(newBody)) {
+                newBody = newBody.trimEnd() + claimBlock;
+              }
+            } else {
+              newBody = newBody.trimEnd() + claimBlock;
+            }
+            await github.rest.issues.update({ owner, repo, issue_number, body: newBody });
+
+            if (assignResult.ok) {
+              await github.rest.issues.createComment({
+                owner,
+                repo,
+                issue_number,
+                body:
+                  `✅ @${actor} 已认领本 Issue，并已加入 **Assignees**。\n\n` +
+                  `建议下一步：\n` +
+                  `1. 从 \`dev\` 拉分支：\`fix/*\` 或 \`feature/*\`\n` +
+                  `2. 完成后向 **\`dev\`** 提 PR\n` +
+                  `3. 若暂无法继续，请评论 \`取消认领\`\n\n` +
+                  `贡献指南：https://github.com/Syngnat/GoNavi/blob/dev/CONTRIBUTING.zh-CN.md`,
+              });
+            } else {
+              await github.rest.issues.createComment({
+                owner,
+                repo,
+                issue_number,
+                body:
+                  `✅ @${actor} 已认领本 Issue（已标记 \`claimed\`）。\n\n` +
+                  `> 说明：GitHub 仅允许将**仓库协作者**设为正式 Assignee。你目前可能还没有写权限，因此无法写入 Assignees 字段；**社区认领仍然有效**，其他人再评论「我想做」会被拦截。\n\n` +
+                  `建议下一步：\n` +
+                  `1. Fork 仓库，从 \`dev\` 拉分支开发\n` +
+                  `2. 向 **\`dev\`** 提 PR，并在 PR 描述里写 \`Fixes #${issue_number}\`\n` +
+                  `3. 若暂无法继续，请评论 \`取消认领\`\n\n` +
+                  `贡献指南：https://github.com/Syngnat/GoNavi/blob/dev/CONTRIBUTING.zh-CN.md`,
+              });
+            }

.github/workflows/publish-release.yml

@@ -0,0 +1,339 @@
+name: Publish Draft Release
+
+on:
+  push:
+    branches:
+      - 'publish/v*'
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: Release tag to publish (for example, v0.8.7)
+        required: true
+        type: string
+
+permissions:
+  actions: read
+  contents: write
+
+concurrency:
+  # Stable and dev publications share the same mirror targets.
+  group: gonavi-release-publication
+  cancel-in-progress: false
+
+jobs:
+  publish:
+    name: Validate, mirror, and publish release
+    runs-on: ubuntu-latest
+    env:
+      RELEASE_TAG: ${{ inputs.tag || github.ref_name }}
+    steps:
+      - name: Validate release
+        id: validate
+        uses: actions/github-script@v8
+        with:
+          script: |
+            const requestedTag = String(process.env.RELEASE_TAG || '').trim();
+            const tag = requestedTag.startsWith('publish/')
+              ? requestedTag.slice('publish/'.length)
+              : requestedTag;
+            if (!/^v\d+\.\d+\.\d+$/.test(tag)) {
+              core.setFailed(`Invalid release tag: ${tag}`);
+              return;
+            }
+
+            const { owner, repo } = context.repo;
+            const tagRef = await github.rest.git.getRef({
+              owner,
+              repo,
+              ref: `tags/${tag}`,
+            });
+
+            let commitSha = tagRef.data.object.sha;
+            if (tagRef.data.object.type === 'tag') {
+              const annotatedTag = await github.rest.git.getTag({
+                owner,
+                repo,
+                tag_sha: tagRef.data.object.sha,
+              });
+              commitSha = annotatedTag.data.object.sha;
+            }
+
+            const workflowRuns = await github.rest.actions.listWorkflowRuns({
+              owner,
+              repo,
+              workflow_id: 'release.yml',
+              event: 'push',
+              branch: tag,
+              per_page: 100,
+            });
+            const runs = workflowRuns.data.workflow_runs;
+            const successfulRun = runs.find((run) => (
+              run.head_sha === commitSha
+              && run.status === 'completed'
+              && run.conclusion === 'success'
+            ));
+            if (!successfulRun) {
+              core.setFailed(`No successful Release workflow found for ${tag} at ${commitSha}`);
+              return;
+            }
+
+            const releaseList = await github.rest.repos.listReleases({
+              owner,
+              repo,
+              per_page: 100,
+            });
+            const releases = releaseList.data;
+            const release = releases.find((item) => item.tag_name === tag);
+            if (!release) {
+              core.setFailed(`Release not found for ${tag}`);
+              return;
+            }
+
+            let latestRelease = null;
+            try {
+              latestRelease = (await github.rest.repos.getLatestRelease({ owner, repo })).data;
+            } catch (error) {
+              if (error.status !== 404) {
+                throw error;
+              }
+            }
+            const semverParts = (value) => value.slice(1).split('.').map(Number);
+            const compareSemver = (left, right) => {
+              const a = semverParts(left);
+              const b = semverParts(right);
+              for (let index = 0; index < 3; index += 1) {
+                if (a[index] !== b[index]) {
+                  return a[index] - b[index];
+                }
+              }
+              return 0;
+            };
+            let shouldPublish = release.draft;
+            if (release.draft) {
+              const latestTag = String(latestRelease?.tag_name || '').trim();
+              if (latestTag && /^v\d+\.\d+\.\d+$/.test(latestTag) && compareSemver(tag, latestTag) <= 0) {
+                core.setFailed(`Refusing to publish ${tag} over current latest ${latestTag}`);
+                return;
+              }
+            } else if (!latestRelease || latestRelease.id !== release.id) {
+              core.setFailed(`Published release ${tag} is not the current GitHub latest release`);
+              return;
+            } else {
+              shouldPublish = false;
+            }
+
+            const version = tag.slice(1);
+            const expectedAssets = [
+              'LICENSE',
+              'NOTICE',
+              'SHA256SUMS',
+              'latest.json',
+              `GoNavi-${version}-Linux-Amd64-WebKit41.tar.gz`,
+              `GoNavi-${version}-Linux-Amd64.tar.gz`,
+              `GoNavi-${version}-Linux-Arm64.tar.gz`,
+              `GoNavi-${version}-MacOS-Amd64.dmg`,
+              `GoNavi-${version}-MacOS-Arm64.dmg`,
+              `GoNavi-${version}-Windows-Amd64-Installer.msi`,
+              `GoNavi-${version}-Windows-Amd64-Portable.exe`,
+              `GoNavi-${version}-Windows-Amd64-Portable.zip`,
+              `GoNavi-${version}-Windows-Arm64-Installer.msi`,
+              `GoNavi-${version}-Windows-Arm64-Portable.exe`,
+              `GoNavi-${version}-Windows-Arm64-Portable.zip`,
+            ];
+            const assetsByName = new Map(release.assets.map((asset) => [asset.name, asset]));
+            const missingAssets = expectedAssets.filter((name) => {
+              const asset = assetsByName.get(name);
+              return !asset || asset.state !== 'uploaded' || asset.size <= 0;
+            });
+            if (missingAssets.length > 0) {
+              core.setFailed(`Release assets are incomplete: ${missingAssets.join(', ')}`);
+              return;
+            }
+
+            core.setOutput('tag', tag);
+            core.setOutput('release_id', String(release.id));
+            core.setOutput('should_publish', String(shouldPublish));
+            core.notice(`Validated ${release.draft ? 'draft' : 'published'} release ${tag} and its assets`);
+
+      - name: Checkout release tooling
+        uses: actions/checkout@v5
+
+      - name: Prepare and verify stable mirror payload
+        id: mirror_payload
+        env:
+          GH_TOKEN: ${{ github.token }}
+          DRIVER_RELEASE_TOKEN: ${{ secrets.DRIVER_RELEASE_TOKEN }}
+          RELEASE_TAG: ${{ steps.validate.outputs.tag }}
+        shell: bash
+        run: |
+          set -euo pipefail
+          if [[ -z "${DRIVER_RELEASE_TOKEN}" ]]; then
+            echo "DriverAgents release credentials are not configured" >&2
+            exit 1
+          fi
+
+          app_dir="${RUNNER_TEMP}/gonavi-release"
+          driver_dir="${RUNNER_TEMP}/driver-release"
+          mkdir -p "${app_dir}" "${driver_dir}"
+          gh release download "${RELEASE_TAG}" --repo "${GITHUB_REPOSITORY}" --dir "${app_dir}"
+
+          driver_release_json="${RUNNER_TEMP}/driver-release.json"
+          driver_status="$(curl --silent --show-error \
+            --output "${driver_release_json}" \
+            --write-out '%{http_code}' \
+            --header "Authorization: Bearer ${DRIVER_RELEASE_TOKEN}" \
+            --header 'Accept: application/vnd.github+json' \
+            --header 'X-GitHub-Api-Version: 2022-11-28' \
+            "https://api.github.com/repos/Syngnat/GoNavi-DriverAgents/releases/tags/${RELEASE_TAG}")"
+          has_driver_release=false
+          case "${driver_status}" in
+            200)
+              jq -e --arg tag "${RELEASE_TAG}" \
+                '.tag_name == $tag and .draft == false' "${driver_release_json}" >/dev/null
+              GH_TOKEN="${DRIVER_RELEASE_TOKEN}" gh release download "${RELEASE_TAG}" \
+                --repo Syngnat/GoNavi-DriverAgents --dir "${driver_dir}"
+              has_driver_release=true
+              ;;
+            404)
+              echo "No DriverAgents release for ${RELEASE_TAG}; skipping driver mirror"
+              ;;
+            *)
+              echo "DriverAgents release lookup failed with HTTP ${driver_status}" >&2
+              exit 1
+              ;;
+          esac
+          echo "has_driver_release=${has_driver_release}" >> "$GITHUB_OUTPUT"
+
+          jq -e \
+            --arg tag "${RELEASE_TAG}" \
+            --arg mirror_base "https://download.syngnat.top/gonavi/releases/download" \
+            --arg github_base "https://github.com/${GITHUB_REPOSITORY}/releases/download" \
+            '
+              .tagName == $tag
+              and (.assets | type == "array" and length > 0)
+              and all(.assets[];
+                (.url | type == "string" and startswith($mirror_base + "/" + $tag + "/"))
+                and (.apiUrl | type == "string" and startswith($github_base + "/" + $tag + "/"))
+                and (.sha256 | type == "string" and test("^[0-9a-fA-F]{64}$"))
+              )
+            ' "${app_dir}/latest.json" >/dev/null
+          if [[ "${has_driver_release}" == true ]]; then
+            jq -e '.assets | type == "object" and length > 0' \
+              "${driver_dir}/GoNavi-DriverAgents-Index.json" >/dev/null
+            [[ -s "${driver_dir}/SHA256SUMS" ]] || {
+              echo "DriverAgents SHA256SUMS is missing" >&2
+              exit 1
+            }
+            (cd "${driver_dir}" && sha256sum --check SHA256SUMS)
+            jq --arg tag "${RELEASE_TAG}" \
+              '.tagName = $tag' \
+              "${driver_dir}/GoNavi-DriverAgents-Index.json" \
+              > "${RUNNER_TEMP}/driver-latest-index.json"
+          fi
+
+          while IFS=$'\t' read -r name expected_size expected_sha; do
+            [[ "${name}" == "$(basename "${name}")" ]] || {
+              echo "Invalid app asset name in latest.json: ${name}" >&2
+              exit 1
+            }
+            file="${app_dir}/${name}"
+            [[ -f "${file}" ]] || {
+              echo "App asset referenced by latest.json is missing: ${name}" >&2
+              exit 1
+            }
+            actual_size="$(stat -c '%s' "${file}")"
+            actual_sha="$(sha256sum "${file}" | awk '{print $1}')"
+            if [[ "${actual_size}" != "${expected_size}" || "${actual_sha}" != "${expected_sha,,}" ]]; then
+              echo "App asset does not match latest.json: ${name}" >&2
+              exit 1
+            fi
+          done < <(jq -r '.assets[] | [.name, (.size | tostring), .sha256] | @tsv' "${app_dir}/latest.json")
+
+          if [[ "${has_driver_release}" == true ]]; then
+            while IFS=$'\t' read -r name expected_size; do
+              [[ "${name}" == "$(basename "${name}")" ]] || {
+                echo "Invalid driver asset name in index: ${name}" >&2
+                exit 1
+              }
+              file="${driver_dir}/${name}"
+              [[ -f "${file}" ]] || {
+                echo "Driver asset referenced by index is missing: ${name}" >&2
+                exit 1
+              }
+              actual_size="$(stat -c '%s' "${file}")"
+              if [[ "${actual_size}" != "${expected_size}" ]]; then
+                echo "Driver asset size does not match index: ${name}" >&2
+                exit 1
+              fi
+            done < <(jq -r '.assets | to_entries[] | [.key, (.value | tostring)] | @tsv' \
+              "${driver_dir}/GoNavi-DriverAgents-Index.json")
+          fi
+
+      - name: Publish validated draft
+        if: steps.validate.outputs.should_publish == 'true'
+        uses: actions/github-script@v8
+        env:
+          RELEASE_TAG: ${{ steps.validate.outputs.tag }}
+          RELEASE_ID: ${{ steps.validate.outputs.release_id }}
+        with:
+          script: |
+            const tag = String(process.env.RELEASE_TAG || '').trim();
+            const releaseId = Number(process.env.RELEASE_ID || 0);
+            if (!/^v\d+\.\d+\.\d+$/.test(tag) || !Number.isSafeInteger(releaseId) || releaseId <= 0) {
+              core.setFailed(`Invalid validated release: tag=${tag} id=${releaseId}`);
+              return;
+            }
+            const { owner, repo } = context.repo;
+            const published = await github.rest.repos.updateRelease({
+              owner,
+              repo,
+              release_id: releaseId,
+              draft: false,
+              prerelease: false,
+              make_latest: 'true',
+            });
+            if (published.data.draft || !published.data.published_at) {
+              core.setFailed(`Release ${tag} was not published successfully`);
+              return;
+            }
+            core.notice(`Published ${tag}: ${published.data.html_url}`);
+
+      - name: Verify GitHub release is published and latest
+        uses: actions/github-script@v8
+        env:
+          RELEASE_TAG: ${{ steps.validate.outputs.tag }}
+          RELEASE_ID: ${{ steps.validate.outputs.release_id }}
+        with:
+          script: |
+            const tag = String(process.env.RELEASE_TAG || '').trim();
+            const releaseId = Number(process.env.RELEASE_ID || 0);
+            const { owner, repo } = context.repo;
+            const [releaseResult, latestResult] = await Promise.all([
+              github.rest.repos.getRelease({ owner, repo, release_id: releaseId }),
+              github.rest.repos.getLatestRelease({ owner, repo }),
+            ]);
+            const release = releaseResult.data;
+            const latest = latestResult.data;
+            if (release.draft || !release.published_at || release.tag_name !== tag || latest.id !== release.id) {
+              core.setFailed(`Release ${tag} is not the current published GitHub latest release`);
+              return;
+            }
+            core.notice(`Verified GitHub latest release ${tag}`);
+
+      - name: Mirror stable release to Gatewaysentry
+        uses: ./.github/actions/publish-vps-mirror
+        with:
+          channel: stable
+          app-tag: ${{ steps.validate.outputs.tag }}
+          app-dir: ${{ runner.temp }}/gonavi-release
+          app-manifest: ${{ runner.temp }}/gonavi-release/latest.json
+          driver-enabled: ${{ steps.mirror_payload.outputs.has_driver_release }}
+          driver-tag: ${{ steps.validate.outputs.tag }}
+          driver-dir: ${{ runner.temp }}/driver-release
+          driver-version-index: ${{ runner.temp }}/driver-release/GoNavi-DriverAgents-Index.json
+          driver-latest-index: ${{ runner.temp }}/driver-latest-index.json
+          ssh-host: ${{ secrets.MIRROR_SSH_HOST }}
+          ssh-port: ${{ secrets.MIRROR_SSH_PORT }}
+          ssh-user: ${{ secrets.MIRROR_SSH_USER }}
+          ssh-private-key: ${{ secrets.MIRROR_SSH_PRIVATE_KEY }}
+          ssh-known-hosts: ${{ secrets.MIRROR_SSH_KNOWN_HOSTS }}

.github/workflows/release-winget.yml

@@ -1,25 +0,0 @@
-name: Publish to WinGet
-on:
-  push:
-    tags:
-      - 'v*'
-  workflow_dispatch:
-    inputs:
-      release_tag:
-        required: true
-        description: 'Tag of release you want to publish'
-        type: string
-
-env:
-  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true"
-
-jobs:
-  publish:
-    runs-on: windows-latest
-    steps:
-      - uses: vedantmgoyal9/winget-releaser@v2
-        with:
-          identifier: Syngnat.GoNavi
-          installers-regex: 'GoNavi-windows-(amd64|arm64)\.exe$'
-          release-tag: ${{ inputs.release_tag || github.ref_name }}
-          token: ${{ secrets.WINGET_TOKEN }}

.github/workflows/star-history.yml

@@ -0,0 +1,183 @@
+# After GitHub restricted public stargazers API (2026-06-30), live api.star-history.com
+# embeds need a collaborator token. Official guidance for README:
+# render with a token that can read THIS repo, do not put a raw PAT in the public file.
+#
+# This workflow uses the repo GITHUB_TOKEN + star-history's chart renderer (via
+# narayann7/star-history-action, which star-history maintainers point to when you
+# prefer not to hand a fine-grained token to the public star-history API).
+# Ref: https://github.com/marketplace/actions/star-history-action
+#      https://www.star-history.com/blog/github-stargazer-api-restriction
+#
+# Commit throttle: only refresh + commit when stargazers_count has grown by
+# STAR_GROWTH_THRESHOLD (default 50) since the last committed baseline
+# (assets/star-history/last-star-count.txt). workflow_dispatch always refreshes.
+
+name: Star History
+
+on:
+  schedule:
+    - cron: "0 */6 * * *"
+  watch:
+    types: [started]
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+concurrency:
+  group: star-history
+  cancel-in-progress: true
+
+env:
+  STAR_GROWTH_THRESHOLD: "50"
+  STAR_BASELINE_FILE: assets/star-history/last-star-count.txt
+
+jobs:
+  star-history:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Decide whether to refresh
+        id: gate
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          set -euo pipefail
+          current="$(gh api "repos/${{ github.repository }}" --jq '.stargazers_count')"
+          if [[ ! "$current" =~ ^[0-9]+$ ]]; then
+            echo "Unexpected stargazers_count: $current" >&2
+            exit 1
+          fi
+
+          seed_baseline=false
+          if [[ -f "$STAR_BASELINE_FILE" ]]; then
+            last="$(tr -d '[:space:]' < "$STAR_BASELINE_FILE" || true)"
+          else
+            last=""
+          fi
+          if [[ ! "$last" =~ ^[0-9]+$ ]]; then
+            # No baseline in repo yet: record current count and skip chart refresh
+            # until the next +N growth (avoids a burst commit on throttle rollout).
+            mkdir -p "$(dirname "$STAR_BASELINE_FILE")"
+            printf '%s\n' "$current" > "$STAR_BASELINE_FILE"
+            last="$current"
+            seed_baseline=true
+            echo "Seeded baseline at $current (no prior file)"
+          fi
+
+          delta=$((current - last))
+          force=false
+          if [[ "${{ github.event_name }}" == "workflow_dispatch" ]]; then
+            force=true
+          fi
+
+          should_refresh=false
+          if [[ "$force" == "true" ]]; then
+            should_refresh=true
+            reason="manual workflow_dispatch"
+          elif (( delta >= STAR_GROWTH_THRESHOLD )); then
+            should_refresh=true
+            reason="star growth ${delta} >= ${STAR_GROWTH_THRESHOLD} (last=${last}, current=${current})"
+          else
+            reason="star growth ${delta} < ${STAR_GROWTH_THRESHOLD} (last=${last}, current=${current})"
+          fi
+
+          # Seeding still needs a tiny commit so the baseline survives checkouts.
+          should_commit=false
+          if [[ "$should_refresh" == "true" || "$seed_baseline" == "true" ]]; then
+            should_commit=true
+          fi
+
+          {
+            echo "current=$current"
+            echo "last=$last"
+            echo "delta=$delta"
+            echo "should_refresh=$should_refresh"
+            echo "seed_baseline=$seed_baseline"
+            echo "should_commit=$should_commit"
+          } >> "$GITHUB_OUTPUT"
+          echo "Gate: should_refresh=$should_refresh seed_baseline=$seed_baseline — $reason"
+
+      - name: Render star history chart
+        if: steps.gate.outputs.should_refresh == 'true'
+        uses: narayann7/star-history-action@v1
+        with:
+          repos: ${{ github.repository }}
+          token: ${{ github.token }}
+          type: Date
+          themes: light,dark
+          output-dir: assets/star-history
+          update-readme: true
+          readme: README.md
+          readme-format: picture
+          commit: false
+
+      - name: Sync chart block into README.zh-CN.md
+        if: steps.gate.outputs.should_refresh == 'true'
+        run: |
+          set -euo pipefail
+          python3 <<'PY'
+          from pathlib import Path
+          import re
+
+          start = "<!-- star-history:start -->"
+          end = "<!-- star-history:end -->"
+
+          def extract_block(text: str) -> str:
+              m = re.search(
+                  re.escape(start) + r"(.*?)" + re.escape(end),
+                  text,
+                  flags=re.S,
+              )
+              if not m:
+                  raise SystemExit("star-history markers missing in README.md")
+              return m.group(0)
+
+          def replace_block(text: str, block: str) -> str:
+              if start not in text or end not in text:
+                  raise SystemExit("star-history markers missing in README.zh-CN.md")
+              return re.sub(
+                  re.escape(start) + r".*?" + re.escape(end),
+                  block,
+                  text,
+                  count=1,
+                  flags=re.S,
+              )
+
+          en = Path("README.md").read_text(encoding="utf-8")
+          zh_path = Path("README.zh-CN.md")
+          zh = zh_path.read_text(encoding="utf-8")
+          block = extract_block(en)
+          zh_path.write_text(replace_block(zh, block), encoding="utf-8")
+          print("synced star-history block into README.zh-CN.md")
+          PY
+
+      - name: Update baseline star count
+        if: steps.gate.outputs.should_refresh == 'true'
+        run: |
+          set -euo pipefail
+          mkdir -p "$(dirname "$STAR_BASELINE_FILE")"
+          printf '%s\n' "${{ steps.gate.outputs.current }}" > "$STAR_BASELINE_FILE"
+          echo "Updated baseline -> ${{ steps.gate.outputs.current }}"
+
+      - name: Commit if changed
+        if: steps.gate.outputs.should_commit == 'true'
+        run: |
+          set -euo pipefail
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          if [[ "${{ steps.gate.outputs.should_refresh }}" == "true" ]]; then
+            git add assets/star-history README.md README.zh-CN.md
+            msg="chore(docs): refresh star history chart [skip ci]"
+          else
+            git add "$STAR_BASELINE_FILE"
+            msg="chore(docs): seed star history baseline [skip ci]"
+          fi
+          if git diff --staged --quiet; then
+            echo "No star-history changes"
+            exit 0
+          fi
+          git commit -m "$msg"
+          git push

.gitignore

@@ -10,16 +10,24 @@ build/bin/
 
 # wails / node artifacts (按需)
 node_modules/
+frontend/wailsjs/tsconfig.json
+__pycache__/
+*.py[cod]
 
 dist/
 .DS_Store
 .gemini-clipboard
+.env
+docker.*.env
 GoNavi-Wails
 GoNavi-Wails.exe
+optional-driver-agent
+optional-driver-agent.exe
 .ace-tool/
 .superpowers/
 .claude/
 .gemini/
+.playwright-mcp/
 **/tmpclaude-*
 docs/superpowers/
 docs/需求追踪/
@@ -28,4 +36,4 @@ CLAUDE.md
 **/CLAUDE.md
 .worktrees
 docs
-.tmp_superpowers_edit
+.tmp_superpowers_edit

AI_EXTENSIONS_ROADMAP.md

@@ -0,0 +1,106 @@
+# AI 扩展能力路线
+
+当前 GoNavi 的 AI 链路是：
+
+1. 前端 `AIChatPanel` 组装 system messages。
+2. 前端声明本地固定工具 `LOCAL_TOOLS`。
+3. 后端 `aiservice.Service` 只负责 Provider 配置、安全级别与模型转发。
+
+这套结构已经足够承接“用户级提示词”，但要继续承接 MCP 和 Skills，需要先把“提示词 / 工具 / 技能”三层职责拆开。
+
+## 1. 用户级自定义提示词
+
+已落地的方向：
+
+- 配置存储在 `ai_config.json` 的 `userPromptSettings`。
+- 由 `AISettingsModal` 提供编辑入口。
+- 由 `AIChatPanel` 在运行时追加为 system message。
+
+建议长期保持 4 个层级：
+
+- `global`: 所有 AI 会话统一追加。
+- `database`: 数据库 / SQL 场景追加。
+- `jvm`: JVM 资源浏览与分析场景追加。
+- `jvmDiagnostic`: JVM 诊断命令规划场景追加。
+
+这样既能满足“个人习惯”定制，也不会把所有场景揉成一条超长总提示词。
+
+## 2. MCP 能力开放
+
+目标不是把 MCP 做成新的聊天面板，而是把它变成“外部工具源”。
+
+建议后续拆成三层：
+
+1. `tool registry`
+   - 统一收口内置工具、本地扩展工具、MCP 工具。
+   - 对模型只暴露统一的 `tools[]`。
+2. `mcp server config`
+   - 保存 server 名称、transport、启动命令或 URL、超时、启用状态。
+   - 由后端维护生命周期与连通性。
+3. `mcp runtime bridge`
+   - 负责 `list tools / call tool / errors / timeout / auth`。
+
+### MCP 是否需要单独 GitHub 仓库
+
+不需要把“GoNavi 对 MCP 的支持”单独拆仓库。
+
+更合理的边界是：
+
+- `GoNavi 主仓库`
+  - 维护 MCP client、配置、UI、工具注册和运行时桥接。
+- `单独仓库（可选）`
+  - 只在你要发布一个可复用的 MCP Server 时才有价值。
+  - 例如 `gonavi-mcp-sql-tools`、`gonavi-mcp-jvm-agent` 这类独立 server。
+
+结论：
+
+- “客户端支持 MCP” 不需要新仓库。
+- “某个独立 MCP Server” 是否拆仓库，取决于它要不要单独发布、复用或部署。
+
+## 3. Skills 设计
+
+Skills 不建议直接等同于“另一种提示词”。
+
+更合适的定义是：
+
+- `skill manifest`
+  - 名称、说明、适用场景、是否默认启用。
+- `skill prompt`
+  - 该技能追加的 system prompt / few-shot / 输出约束。
+- `skill tool requirements`
+  - 该技能依赖哪些内置工具或 MCP 工具。
+- `skill shortcuts`
+  - 可选地给欢迎卡片、斜杠命令或快速动作提供入口。
+
+一个 Skill 本质上应该是“提示词 + 工具依赖 + 使用入口”的组合，而不是单独一段文案。
+
+### Skills 是否需要单独 GitHub 仓库
+
+第一阶段不需要。
+
+建议顺序：
+
+1. 先在 GoNavi 主仓库内把 Skills manifest/runtime 跑通。
+2. 等格式稳定后，再考虑增加“本地目录导入”或“Git 仓库导入”。
+
+只有当你明确要做下面两件事时，独立仓库才值得：
+
+- 把 Skills 当作社区共享资产分发。
+- 让不同团队独立维护自己的 skill pack。
+
+## 建议的下一步实现顺序
+
+1. 抽出统一 `ToolRegistry`，让 `LOCAL_TOOLS` 不再硬编码在聊天面板内部。
+2. 在 AI 设置中新增 `MCP Servers` 配置页。
+3. 后端先支持最小 transport：
+   - `stdio`
+   - `http/sse`（如果后续确认需要）
+4. 在 AI 设置中新增 `Skills` 配置页。
+5. 让 Skill 以 manifest 形式声明：
+   - `id`
+   - `name`
+   - `description`
+   - `systemPrompt`
+   - `requiredTools`
+   - `scopes`
+6. 再决定是否增加“从 Git 仓库同步 MCP/Skills 包”的分发能力。

Dockerfile.build-env

@@ -0,0 +1,58 @@
+# syntax=docker/dockerfile:1.7
+
+ARG GO_IMAGE=golang:1.25-bookworm
+ARG NODE_IMAGE=node:20-bookworm
+
+FROM ${NODE_IMAGE} AS node
+
+FROM ${GO_IMAGE}
+
+ARG WEBKIT_API=4.0
+ARG WAILS_VERSION=v2.11.0
+
+ENV DEBIAN_FRONTEND=noninteractive
+ENV PATH=/go/bin:/usr/local/go/bin:${PATH}
+
+# Debian's /etc/profile resets PATH in login shells (bash -l), dropping the Go
+# toolchain; restore it via profile.d which is sourced after that reset.
+RUN printf 'export PATH=/go/bin:/usr/local/go/bin:$PATH\n' > /etc/profile.d/10-gonavi-build-env.sh
+
+# Copy only Node.js runtime assets so the Go toolchain from the base image
+# stays intact for smoke tests and interactive build shells.
+COPY --from=node /usr/local/bin/node /usr/local/bin/node
+COPY --from=node /usr/local/lib/node_modules /usr/local/lib/node_modules
+
+# npm/npx/corepack are symlinks in the node image; COPY dereferences them into
+# standalone scripts whose relative requires break, so recreate the symlinks.
+RUN ln -sf ../lib/node_modules/npm/bin/npm-cli.js /usr/local/bin/npm \
+    && ln -sf ../lib/node_modules/npm/bin/npx-cli.js /usr/local/bin/npx \
+    && ln -sf ../lib/node_modules/corepack/dist/corepack.js /usr/local/bin/corepack
+
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends \
+        bash \
+        build-essential \
+        ca-certificates \
+        curl \
+        file \
+        git \
+        make \
+        pkg-config \
+        python3 \
+        unzip \
+        zip \
+        libgtk-3-dev \
+    && if [ "${WEBKIT_API}" = "4.1" ]; then \
+        apt-get install -y --no-install-recommends libwebkit2gtk-4.1-dev libsoup-3.0-dev; \
+    else \
+        apt-get install -y --no-install-recommends libwebkit2gtk-4.0-dev; \
+    fi \
+    && go install github.com/wailsapp/wails/v2/cmd/wails@${WAILS_VERSION} \
+    && rm -rf /var/lib/apt/lists/*
+
+RUN mkdir -p /usr/share/doc/gonavi
+COPY LICENSE NOTICE /usr/share/doc/gonavi/
+
+WORKDIR /workspace
+
+CMD ["bash"]

Dockerfile.mcp-server

@@ -0,0 +1,49 @@
+# syntax=docker/dockerfile:1.7
+
+FROM --platform=$BUILDPLATFORM golang:1.25-bookworm AS builder
+
+# Declared without defaults so BuildKit injects the real target platform;
+# a default like TARGETARCH=amd64 would win and ship amd64 binaries to arm64.
+ARG TARGETOS
+ARG TARGETARCH
+
+WORKDIR /src
+
+COPY go.mod go.sum ./
+COPY third_party/highgo-pq/go.mod ./third_party/highgo-pq/go.mod
+COPY third_party/go-irisnative/go.mod third_party/go-irisnative/go.sum ./third_party/go-irisnative/
+RUN go mod download
+
+COPY . .
+RUN ./tools/generate-driver-agent-revisions.sh --platform "${TARGETOS}/${TARGETARCH}"
+
+RUN CGO_ENABLED=0 GOOS=${TARGETOS} GOARCH=${TARGETARCH} \
+    go build -trimpath -ldflags="-s -w" -o /out/gonavi-mcp-server ./cmd/gonavi-mcp-server
+
+FROM debian:bookworm-slim
+
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends ca-certificates tzdata \
+    && rm -rf /var/lib/apt/lists/* \
+    && useradd --system --create-home --home-dir /var/lib/gonavi --uid 10001 gonavi \
+    && mkdir -p /data /var/lib/gonavi/logs /usr/share/doc/gonavi \
+    && chown -R gonavi:gonavi /data /var/lib/gonavi
+
+COPY --from=builder /out/gonavi-mcp-server /usr/local/bin/gonavi-mcp-server
+COPY --from=builder /src/LICENSE /usr/share/doc/gonavi/LICENSE
+COPY --from=builder /src/NOTICE /usr/share/doc/gonavi/NOTICE
+
+ENV HOME=/var/lib/gonavi \
+    GONAVI_DATA_ROOT=/data \
+    GONAVI_LOG_DIR=/var/lib/gonavi/logs \
+    GONAVI_MCP_HTTP_ADDR=0.0.0.0:8765 \
+    GONAVI_MCP_HTTP_PATH=/mcp \
+    GONAVI_MCP_SCHEMA_ONLY=true
+
+VOLUME ["/data"]
+EXPOSE 8765
+
+USER gonavi
+
+ENTRYPOINT ["/usr/local/bin/gonavi-mcp-server"]
+CMD ["http"]

Dockerfile.web-server

@@ -0,0 +1,65 @@
+# syntax=docker/dockerfile:1.7
+#
+# GoNavi Web Server（浏览器访问版）镜像。
+# 复用主程序 web-server 模式 + 嵌入 frontend/dist，不依赖桌面 WebView/CGO。
+
+FROM --platform=$BUILDPLATFORM node:20-bookworm AS frontend
+
+# 使用 monorepo 布局：frontend 源码通过相对路径 ../../../shared/i18n 引用仓库 shared/
+# （见 frontend/src/i18n/catalog.ts、shared/i18n/messages.ts、shared/i18n/translate.ts）。
+# 仅 COPY frontend/ 会导致 tsc 报 Cannot find module '../../../shared/i18n/*'。
+WORKDIR /src/frontend
+COPY frontend/package.json frontend/package-lock.json ./
+COPY frontend/patches ./patches
+RUN npm ci --no-audit --no-fund
+COPY frontend/ ./
+COPY shared/ /src/shared/
+# wailsjs 绑定已入库；容器内只构建静态前端
+RUN npm run build
+
+FROM --platform=$BUILDPLATFORM golang:1.25-bookworm AS builder
+
+ARG TARGETOS
+ARG TARGETARCH
+
+WORKDIR /src
+
+COPY go.mod go.sum ./
+COPY third_party/highgo-pq/go.mod ./third_party/highgo-pq/go.mod
+COPY third_party/go-irisnative/go.mod third_party/go-irisnative/go.sum ./third_party/go-irisnative/
+RUN go mod download
+
+COPY . .
+RUN ./tools/generate-driver-agent-revisions.sh --platform "${TARGETOS}/${TARGETARCH}"
+COPY --from=frontend /src/frontend/dist ./frontend/dist
+
+# 纯 Go 构建主程序（web-server 模式不需要 Wails WebView / CGO）
+RUN CGO_ENABLED=0 GOOS=${TARGETOS} GOARCH=${TARGETARCH} \
+    go build -trimpath -ldflags="-s -w" -o /out/gonavi .
+
+FROM debian:bookworm-slim
+
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends ca-certificates tzdata curl \
+    && rm -rf /var/lib/apt/lists/* \
+    && useradd --system --create-home --home-dir /var/lib/gonavi --uid 10001 gonavi \
+    && mkdir -p /data /var/lib/gonavi/logs /usr/share/doc/gonavi \
+    && chown -R gonavi:gonavi /data /var/lib/gonavi
+
+COPY --from=builder /out/gonavi /usr/local/bin/gonavi
+COPY --from=builder /src/LICENSE /usr/share/doc/gonavi/LICENSE
+COPY --from=builder /src/NOTICE /usr/share/doc/gonavi/NOTICE
+
+ENV HOME=/var/lib/gonavi \
+    GONAVI_DATA_ROOT=/data \
+    GONAVI_LOG_DIR=/var/lib/gonavi/logs \
+    GONAVI_WEB_ADDR=0.0.0.0:34116
+
+VOLUME ["/data"]
+EXPOSE 34116
+
+USER gonavi
+
+# 未通过环境变量配置密码时，首次访问 /setup 初始化；认证状态落在数据目录 web_auth.json
+ENTRYPOINT ["/usr/local/bin/gonavi"]
+CMD ["web-server"]

NOTICE

@@ -0,0 +1,212 @@
+GoNavi
+Copyright 2026 Syngnat
+
+This product includes software developed by the following projects.
+
+Apache RocketMQ
+Copyright 2016-2022 The Apache Software Foundation
+
+This product includes software developed at
+The Apache Software Foundation (http://www.apache.org/).
+
+Apache IoTDB
+Copyright 2018-2020 The Apache Software Foundation.
+
+This product includes software developed at
+The Apache Software Foundation (http://www.apache.org/).
+
+============================================================================
+
+IoTDB project uses 4 Chinese Patents:
+* 201711384490X
+* 201810111712.9
+* 201711322631.5
+* 201711319331.1
+
+According to the Apache 2.0 License. The owner of the patents, Tsinghua University,
+grant the users the right to the use of patent under the requirement of Apache 2.0 License.
+
+============================================================================
+
+Apache Thrift
+Copyright (C) 2006 - 2019, The Apache Software Foundation
+
+This product includes software developed at
+The Apache Software Foundation (http://www.apache.org/).
+
+go-yaml
+Copyright 2011-2016 Canonical Ltd.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+Eclipse Paho MQTT Go
+
+This content is produced and maintained by the Eclipse Paho project.
+
+* Project home: https://www.eclipse.org/paho/
+
+Note that a separate mqtt v5 client (https://github.com/eclipse/paho.golang) also
+exists. It is a full rewrite and deliberately incompatible with this library.
+
+Eclipse Mosquitto trademarks of the Eclipse Foundation. Eclipse, and the
+Eclipse Logo are registered trademarks of the Eclipse Foundation.
+
+Paho is a trademark of the Eclipse Foundation. Eclipse, and the Eclipse Logo are
+registered trademarks of the Eclipse Foundation.
+
+All content is the property of the respective authors or their employers.
+For more information regarding authorship of content, please consult the
+listed source code repository logs.
+
+This program and the accompanying materials are made available under the terms of the
+Eclipse Public License v2.0 and Eclipse Distribution License v1.0 which accompany this
+distribution.
+
+The Eclipse Public License is available at
+https://www.eclipse.org/legal/epl-2.0/
+and the Eclipse Distribution License is available at
+http://www.eclipse.org/org/documents/edl-v10.php.
+
+For an explanation of what dual-licensing means to you, see:
+https://www.eclipse.org/legal/eplfaq.php#DUALLIC
+
+SPDX-License-Identifier: EPL-2.0 or BSD-3-Clause
+
+The project maintains the following source code repository:
+
+* https://github.com/eclipse/paho.mqtt.golang
+
+This project makes use of the following third-party projects:
+
+Go Programming Language and Standard Library
+* License: BSD-style license (https://golang.org/LICENSE)
+
+Go Networking
+* License: BSD 3-Clause style license and patent grant.
+* Project: https://cs.opensource.google/go/x/net
+
+Go Sync
+* License: BSD 3-Clause style license and patent grant.
+* Project: https://cs.opensource.google/go/x/sync/
+
+Gorilla Websockets v1.4.2
+* License: BSD 2-Clause "Simplified" License
+* Project: https://github.com/gorilla/websocket
+
+Content may contain encryption software. The country in which you are currently
+may have restrictions on the import, possession, and use, and/or re-export to
+another country. BEFORE using any encryption software, please check the country's
+laws, regulations and policies concerning the import, possession, and use, and/or
+re-export of encryption software, to see if this is permitted.
+
+Vendored HighGo pq-sm3 (derived from lib/pq)
+Copyright (c) 2011-2013, 'pq' Contributors
+Portions Copyright (C) 2011 Blake Mizerany
+
+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.
+
+The vendored SCRAM implementation includes the following BSD 3-Clause notice:
+
+Copyright (c) 2014 - Gustavo Niemeyer <gustavo@niemeyer.net>
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+3. Neither the name of the copyright holder nor the names of its contributors
+   may be used to endorse or promote products derived from this software without
+   specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+Tailscale hujson
+Project: https://github.com/tailscale/hujson
+
+Copyright (c) 2019 Tailscale Inc. All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+   * Redistributions of source code must retain the above copyright
+notice, this list of conditions and the following disclaimer.
+   * Redistributions in binary form must reproduce the above
+copyright notice, this list of conditions and the following disclaimer
+in the documentation and/or other materials provided with the
+distribution.
+   * Neither the name of Google Inc. nor the names of its
+contributors may be used to endorse or promote products derived from
+this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+Vendored InterSystems IRIS native driver
+Copyright (c) 2025 Dmitry Maslennikov
+
+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.

README.md

@@ -1,194 +1,422 @@
-# GoNavi - A Modern Lightweight Database Client
+<p align="center">
+  <img src="assets/readme-logo.png" width="128" alt="GoNavi Logo" />
+</p>
 
-[![Go Version](https://img.shields.io/github/go-mod/go-version/Syngnat/GoNavi)](https://go.dev/)
-[![Wails Version](https://img.shields.io/badge/Wails-v2-red)](https://wails.io)
-[![React Version](https://img.shields.io/badge/React-v18-blue)](https://reactjs.org/)
-[![License](https://img.shields.io/badge/License-Apache%202.0-green.svg)](LICENSE)
-[![Build Status](https://img.shields.io/github/actions/workflow/status/Syngnat/GoNavi/release.yml?label=Build)](https://github.com/Syngnat/GoNavi/actions)
-[![Stars](https://img.shields.io/github/stars/Syngnat/GoNavi?style=social)](https://github.com/Syngnat/GoNavi/stargazers)
-[![Downloads](https://img.shields.io/github/downloads/Syngnat/GoNavi/total?color=blue&label=downloads)](https://github.com/Syngnat/GoNavi/releases)
+<h1 align="center">GoNavi</h1>
 
-**Language**: English | [简体中文](README.zh-CN.md)
+<p align="center">
+  <b>Navigate every data source — native speed, agent-ready, zero Electron bloat.</b>
+</p>
 
-GoNavi is a modern, high-performance, cross-platform database client built with **Wails (Go)** and **React**.
-It delivers native-like responsiveness with low resource usage.
+<p align="center">
+  A high-performance cross-platform database client built with
+  <a href="https://wails.io">Wails</a> (Go) + <a href="https://react.dev">React</a>.
+  Desktop-first. MCP-ready. ~30MB class binaries.
+</p>
 
-Compared with many Electron-based clients, GoNavi is typically smaller in binary size (around 10MB class), starts faster, and uses less memory.
+<p align="center">
+  <a href="https://github.com/Syngnat/GoNavi/releases"><img src="https://img.shields.io/github/v/release/Syngnat/GoNavi?style=for-the-badge&color=8B5CF6" alt="Release" /></a>
+  <a href="https://github.com/Syngnat/GoNavi/releases"><img src="https://img.shields.io/github/downloads/Syngnat/GoNavi/total?style=for-the-badge&color=6366F1&label=downloads" alt="Downloads" /></a>
+  <a href="https://github.com/Syngnat/GoNavi/stargazers"><img src="https://img.shields.io/github/stars/Syngnat/GoNavi?style=for-the-badge&color=F59E0B" alt="Stars" /></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/License-Apache%202.0-22C55E?style=for-the-badge" alt="License" /></a>
+</p>
+
+<p align="center">
+  <a href="https://go.dev"><img src="https://img.shields.io/github/go-mod/go-version/Syngnat/GoNavi?style=flat-square&logo=go&logoColor=white&label=Go" alt="Go" /></a>
+  <a href="https://wails.io"><img src="https://img.shields.io/badge/Wails-v2-red?style=flat-square" alt="Wails" /></a>
+  <a href="https://reactjs.org"><img src="https://img.shields.io/badge/React-18-61DAFB?style=flat-square&logo=react&logoColor=white" alt="React" /></a>
+  <a href="https://github.com/Syngnat/GoNavi/actions"><img src="https://img.shields.io/github/actions/workflow/status/Syngnat/GoNavi/release.yml?style=flat-square&label=Build" alt="Build" /></a>
+</p>
+
+<p align="center">
+  <b>Language</b>: English · <a href="README.zh-CN.md">简体中文</a>
+  &nbsp;·&nbsp;
+  <a href="https://github.com/Syngnat/GoNavi/releases"><b>⬇ Download</b></a>
+  ·
+  <a href="#-quick-start"><b>⚡ Quick Start</b></a>
+  ·
+  <a href="#-key-features"><b>✨ Features</b></a>
+  ·
+  <a href="#-mcp--agents"><b>🤖 MCP</b></a>
+</p>
+
+<p align="center">
+  <sub>Sponsored by
+  <a href="#-sponsors"><b>华龙中转站 / Hualong Transfer Station</b></a></sub>
+</p>
 
 ---
 
-## Project Overview
+## Why GoNavi?
 
-GoNavi is designed for developers and DBAs who need a unified desktop experience across multiple databases.
+Most database GUIs are Electron shells with megabytes of tax. GoNavi takes a different path:
 
-- **Native-performance architecture**: Wails (Go + WebView) with lightweight runtime overhead.
-- **Large dataset usability**: virtualized rendering and optimized DataGrid workflows for high-volume tables.
-- **Unified connectivity**: URI build/parse, SSH tunnel, proxy support, and on-demand driver activation.
-- **Production-oriented workflow**: SQL editor, object management, batch export/backup, sync tools, execution logs, and update checks.
+| | Typical Electron client | **GoNavi** |
+|---|---|---|
+| Runtime | Chromium + Node | **Go + native WebView** |
+| Binary size | Hundreds of MB | **~30MB class** |
+| Startup | Heavy | **Fast** |
+| Memory | High baseline | **Lean** |
+| AI / Agents | Bolt-on or absent | **First-class MCP + multi-provider AI** |
+| Data sources | Mostly RDBMS | **SQL · Cache · Vector · MQ · Search · Time-series · Domestic DBs** |
 
-## Supported Data Sources
+> **One cockpit for MySQL, Postgres, Redis, Kafka, Milvus, OceanBase, ClickHouse…**  
+> Query, edit, audit, sync — and hand structured context to coding agents without leaking passwords off-host.
 
-> `Built-in`: available out of the box.  
-> `Optional driver agent`: install/enable via Driver Manager first.
+---
+
+## At a Glance
+
+```text
+┌──────────────────────────────────────────────────────────────────────┐
+│  GoNavi Workbench                                                    │
+│  ┌─────────────┐  ┌──────────────────┐  ┌─────────────────────────┐  │
+│  │ Connections │  │ Monaco SQL + AI  │  │ Virtualized DataGrid    │  │
+│  │ SSH / Proxy │  │ Schema context   │  │ Batch edit · Export     │  │
+│  │ Drivers     │  │ Slash commands   │  │ Txn submit / rollback   │  │
+│  └─────────────┘  └────────┬─────────┘  └─────────────────────────┘  │
+│                            │                                         │
+│              ┌─────────────▼─────────────┐                           │
+│              │  Go core · Audit · Sync   │                           │
+│              │  MCP HTTP · Web Server    │                           │
+│              └───────────────────────────┘                           │
+└──────────────────────────────────────────────────────────────────────┘
+```
+
+### Product screenshots
+
+Each image is a **full GoNavi application window**, scaled proportionally for README display.
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/Syngnat/GoNavi/dev/assets/screenshots/01-home-workbench.png" alt="GoNavi full window — connections, queries, and workbench" width="560" />
+  &nbsp;
+  <img src="https://raw.githubusercontent.com/Syngnat/GoNavi/dev/assets/screenshots/04-ai-assistant.png" alt="GoNavi full window — AI assistant with schema context" width="560" />
+</p>
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/Syngnat/GoNavi/dev/assets/screenshots/06-new-connection.png" alt="GoNavi full window — new connection data-source selector" width="560" />
+</p>
+
+<p align="center"><sub>Real desktop captures · full window</sub></p>
+
+---
+
+## ✨ Key Features
+
+<table>
+<tr>
+<td width="50%" valign="top">
+
+### 🤖 AI that knows your schema
+- OpenAI · Gemini · Claude · custom OpenAI-compatible APIs  
+- Attach live table schemas as context  
+- Slash commands: generate SQL, explain, optimize, review  
+- **MCP**: install into Claude Code / Codex, or Streamable HTTP for remote agents  
+- Secrets stay on the GoNavi host — agents get tools, not raw passwords  
+
+</td>
+<td width="50%" valign="top">
+
+### ⚡ Built for large data
+- Virtualized DataGrid for heavy result sets  
+- In-place cell edit · batch CRUD · transaction submit/rollback  
+- Large-field popup editor · smart read/write modes  
+- Export: CSV · XLSX · JSON · Markdown  
+- Monaco editor with context-aware completion  
+
+</td>
+</tr>
+<tr>
+<td width="50%" valign="top">
+
+### 🔌 Connectivity without drama
+- URI generate / parse  
+- SSH tunnel · proxy  
+- Connection JSON import / export  
+- On-demand optional driver agents  
+- Custom Driver + DSN extensibility  
+
+</td>
+<td width="50%" valign="top">
+
+### 🛡️ Observable & shippable
+- SQL execution logs with timing  
+- Audit center (redacted by default, retention, export)  
+- Desktop + experimental **Web Server** mode  
+- Docker / K8s / Helm / Podman packaging  
+- Auto update checks · multi-arch releases  
+
+</td>
+</tr>
+</table>
+
+### 🧩 Stack
+
+`Go 1.24` · `Wails v2` · `React 18` · `TypeScript` · `Vite` · `Ant Design 5` · `Zustand` · `Monaco`
+
+---
+
+## 🗄 Supported Data Sources
+
+> **Built-in** — ready out of the box · **Optional agent** — install via Driver Manager
+
+| | |
+|---|---|
+| **Built-in** | MySQL · GoldenDB · PostgreSQL · Oracle · Redis · Chroma · Qdrant · Milvus · RocketMQ · MQTT · Kafka · RabbitMQ |
+| **Optional** | MariaDB · Doris · StarRocks · Sphinx · SQL Server · SQLite · DuckDB · OceanBase · Dameng · Kingbase · HighGo · Vastbase · OpenGauss · GaussDB · IRIS · MongoDB · TDengine · IoTDB · ClickHouse · Trino · Elasticsearch · Custom Driver/DSN |
+
+<details>
+<summary><b>Full capability matrix</b></summary>
 
 | Category | Data Source | Driver Mode | Typical Capabilities |
 |---|---|---|---|
 | Relational | MySQL | Built-in | Schema browsing, SQL query, data editing, export/backup |
+| Domestic DB | GoldenDB | Built-in | MySQL-compatible query workflow and distributed transaction scenarios |
 | Relational | PostgreSQL | Built-in | Schema browsing, SQL query, data editing, object management |
 | Relational | Oracle | Built-in | Query execution, object browsing, data editing |
 | Cache | Redis | Built-in | Key browsing, command execution, encoding/view switch |
+| Vector Database | Chroma | Built-in | Collection browsing, vector retrieval, metadata filtering |
+| Vector Database | Qdrant | Built-in | Collection browsing, vector search, payload filtering |
+| Vector Database | Milvus | Built-in | Collection browsing, vector search, scalar filtering |
+| Message Queue | RocketMQ | Built-in | Topic browsing, consumer-group inspection, message-oriented workflow |
+| Message Queue | MQTT | Built-in | Broker and topic-filter workflow with QoS-aware connection settings |
+| Message Queue | Kafka | Built-in | Topic browsing, broker metadata, consumer-group workflow |
+| Message Queue | RabbitMQ | Built-in | Queue/exchange browsing, virtual host inspection, management API workflow |
 | Relational | MariaDB | Optional driver agent | Querying, object management, data editing |
 | Relational | Doris | Optional driver agent | Querying, object browsing, SQL execution |
+| Columnar Analytics | StarRocks | Optional driver agent | Querying, object browsing, SQL execution |
 | Search | Sphinx | Optional driver agent | SphinxQL querying and object browsing |
 | Relational | SQL Server | Optional driver agent | Schema browsing, SQL query, object management |
 | File-based | SQLite | Optional driver agent | Local DB browsing, editing, export |
 | File-based | DuckDB | Optional driver agent | Large-table query, pagination, file-DB workflow |
+| Domestic DB | OceanBase | Optional driver agent | MySQL / Oracle tenant access, object browsing, query workflow |
 | Domestic DB | Dameng | Optional driver agent | Querying, object browsing, data editing |
 | Domestic DB | Kingbase | Optional driver agent | Querying, object browsing, data editing |
 | Domestic DB | HighGo | Optional driver agent | Querying, object browsing, data editing |
 | Domestic DB | Vastbase | Optional driver agent | Querying, object browsing, data editing |
+| Domestic DB | OpenGauss | Optional driver agent | PostgreSQL-like schema browsing, SQL query, object management |
+| Domestic DB | GaussDB | Optional driver agent | PostgreSQL-like schema browsing, SQL query, object management |
+| Multi-model | InterSystems IRIS | Optional driver agent | Namespace browsing, SQL query, object management |
 | Document | MongoDB | Optional driver agent | Document query, collection browsing, connection management |
 | Time-series | TDengine | Optional driver agent | Time-series schema browsing and querying |
+| Time-series | Apache IoTDB | Optional driver agent | Storage group / device / timeseries browsing and querying |
 | Columnar Analytics | ClickHouse | Optional driver agent | Analytical query, object browsing, SQL execution |
+| Federated Query | Trino | Optional driver agent | Cross-source SQL via multiple catalogs, `catalog.schema` browsing, SQL execution |
+| Search | Elasticsearch | Optional driver agent | Index browsing, mapping inspection, JSON DSL / query_string search |
 | Extensibility | Custom Driver/DSN | Custom | Extend to more data sources via Driver + DSN |
 
-<h2 align="center">📸 Screenshots</h2>
-
-<div align="center">
-    <img width="25%" alt="image" src="https://github.com/user-attachments/assets/0eefe07f-2836-44fa-9ddf-a0d2124b90e2" />
-    <img width="25%" alt="image" src="https://github.com/user-attachments/assets/6765e539-83ea-4cd6-9c9e-f42790fa05b5" />
-    <img width="25%" alt="image" src="https://github.com/user-attachments/assets/60e3d187-171a-4248-94e0-c6b08736e235" />
-    <br />
-    <img width="25%" alt="image" src="https://github.com/user-attachments/assets/7a478602-0f08-4b30-8f6a-879f4a60ae32" />
-    <img width="14%" alt="image" src="https://github.com/user-attachments/assets/6442ca7d-ce9e-46d9-aecd-405ba88f5a5e" />
-    <img width="25%" alt="image" src="https://github.com/user-attachments/assets/bc17895e-02a4-4cc5-b471-c3803cf25a2b" />
-</div>
+</details>
 
 ---
 
-## Key Features
-
-### AI Assistant (New)
-- **Multi-provider Support**: OpenAI, Google Gemini, Anthropic Claude, and custom API support.
-- **Context-Aware Chat**: Attach table schemas to the AI context for accurate SQL generation and assistance.
-- **Slash Commands**: Quick commands for generating SQL, explaining queries, optimizing performance, and reviewing schema designs.
-
-### Performance
-- **Smooth interaction under load**: optimized table interaction (including column resize workflow on large datasets).
-- **Virtualized rendering**: keeps large result sets responsive.
-
-### Data Management (DataGrid)
-- In-place cell editing.
-- Batch insert/update/delete with transaction-oriented submit/rollback.
-- Large-field popup editor.
-- Context actions (set NULL, copy/export, etc.).
-- Smart read/write mode switching based on query context.
-- Export formats: CSV, Excel (XLSX), JSON, Markdown.
-
-### SQL Editor
-- Monaco Editor core.
-- Context-aware completion for databases/tables/columns.
-- Multi-tab query workflow.
-
-### Batch Export / Backup
-- Database-level and table-level batch export/backup.
-- Scope-aware operation flow to reduce mistakes.
-
-### Connectivity
-- URI generation/parsing.
-- SSH tunnel support.
-- Proxy support.
-- Config import/export (JSON).
-- Optional driver management and activation.
-
-### Redis Tools
-- Multi-view value rendering (auto/raw text/UTF-8/hex).
-- Built-in command execution panel.
-
-### Observability and Update
-- SQL execution logs with timing information.
-- Startup/scheduled/manual update checks.
-
-### UI/UX
-- Ant Design 5 based interface.
-- Light/Dark themes.
-- Flexible sidebar and layout behavior.
-
----
-
-## Tech Stack
-
-- **Backend**: Go 1.24 + Wails v2
-- **Frontend**: React 18 + TypeScript + Vite
-- **UI**: Ant Design 5
-- **State Management**: Zustand
-- **Editor**: Monaco Editor
-
----
-
-## Installation and Run
+## 🚀 Quick Start
 
 ### Prerequisites
+
 - [Go](https://go.dev/dl/) 1.21+
 - [Node.js](https://nodejs.org/) 18+
-- [Wails CLI](https://wails.io/docs/gettingstarted/installation):
-  `go install github.com/wailsapp/wails/v2/cmd/wails@latest`
-
-### Development Mode
+- [Wails CLI](https://wails.io/docs/gettingstarted/installation)
+
+```bash
+go install github.com/wailsapp/wails/v2/cmd/wails@v2.11.0
+```
+
+### Develop
 
 ```bash
-# Clone
 git clone https://github.com/Syngnat/GoNavi.git
 cd GoNavi
 
-# Start development with hot reload
-wails dev
+wails dev                          # full hot reload
+node tools/wails-fast-dev.mjs      # faster when Go exports unchanged
+node tools/wails-fast-dev.mjs --refresh-bindings  # after Go export signature changes
 ```
 
 ### Build
 
 ```bash
-# Build for current platform
 wails build
-
-# Clean build (recommended before release)
-wails build -clean
+wails build -clean   # clean build before release
 ```
 
-Artifacts are generated in `build/bin`.
+Artifacts → `build/bin`.
 
-### Cross-Platform Release (GitHub Actions)
+### Prefer a binary?
 
-The repository includes a release workflow.
-Push a `v*` tag to trigger automated build and release.
-Release notes are generated automatically from merged pull requests and categorized by `.github/release.yaml`.
-
-Target artifacts include:
-- macOS (AMD64 / ARM64)
-- Windows (AMD64)
-- Linux (AMD64, WebKitGTK 4.0 and 4.1 variants)
+Grab the latest build from **[Releases](https://github.com/Syngnat/GoNavi/releases)**  
+(macOS AMD64/ARM64 · Windows AMD64 · Linux WebKitGTK 4.0/4.1).
 
 ---
 
-## Troubleshooting
+## 🌐 Web Server (Experimental)
 
-### macOS: "App is damaged and can’t be opened"
+Same Go backend + React UI over HTTP — **not** a containerized Wails window.
 
-Without Apple notarization, Gatekeeper may block startup.
+```powershell
+go build .
+.\GoNavi-Wails.exe web-server --addr 127.0.0.1:34116
+```
 
-1. Move `GoNavi.app` to **Applications**.
-2. Open **Terminal**.
-3. Run:
+- First visit → `/setup` (admin password; optional Google Authenticator)
+- Bridge: `window.go.*` / `window.runtime.*` → HTTP / SSE
+- Sessions, recovery codes, login rate limits
+
+#### Docker / Podman
+
+```bash
+cp docker.web-server.env.example docker.web-server.env
+# set GONAVI_HOST_DATA_ROOT (absolute path)
+# optional: GONAVI_WEB_PASSWORD (min 6 chars)
+docker compose --env-file docker.web-server.env -f docker-compose.web-server.yml up -d
+```
+
+Open `http://127.0.0.1:34116`. Mount the active data root at `/data`  
+(`connections.json`, `daily_secrets.json`, optional `drivers/`).  
+Auth state → `web_auth.json`.
+
+> **Do not expose an unhardened web entry to the public internet.** Use reverse proxy + HTTPS in production.
+
+Health: `GET /__gonavi/healthz`  
+Local source build: add `-f docker-compose.web-server.local.yml --build`.
+
+After changing env passwords:
+
+```bash
+docker compose --env-file docker.web-server.env -f docker-compose.web-server.yml up -d --force-recreate
+```
+
+(`docker restart` does **not** reload env files.)
+
+---
+
+## 🤖 MCP & Agents
+
+Ship schema tools to agents without shipping your vault:
+
+```bash
+cp docker.mcp-server.env.example docker.mcp-server.env
+docker compose --env-file docker.mcp-server.env -f docker-compose.mcp-server.yml up -d
+```
+
+| Surface | Entry |
+|---|---|
+| MCP container | `docker-compose.mcp-server.yml` → `ghcr.io/syngnat/gonavi-mcp-server` |
+| Web UI container | `docker-compose.web-server.yml` → `ghcr.io/syngnat/gonavi-web-server` |
+| Podman / Quadlet | [deploy/podman/gonavi-mcp-server](deploy/podman/gonavi-mcp-server) |
+| Kubernetes | [deploy/k8s/gonavi-mcp-server](deploy/k8s/gonavi-mcp-server) |
+| Helm | [deploy/helm/gonavi-mcp-server](deploy/helm/gonavi-mcp-server) |
+| Build-only image | `Dockerfile.build-env` → `ghcr.io/syngnat/gonavi-build-env` |
+
+Safety defaults: remote `schema-only` omits `execute_sql`; mutating SQL requires explicit `allowMutating=true`.  
+Details: [cmd/gonavi-mcp-server/README.md](cmd/gonavi-mcp-server/README.md).
+
+### Linux build environment only
+
+```bash
+docker build -f Dockerfile.build-env -t gonavi-build-env:local .
+docker run --rm -it -v "$PWD:/workspace" -w /workspace gonavi-build-env:local bash
+```
+
+---
+
+## 📦 Release Pipeline
+
+Push a `v*` tag → GitHub Actions builds multi-arch releases.  
+Notes auto-generated from merged PRs via `.github/release.yaml`.
+
+---
+
+## 🛠 Troubleshooting
+
+<details>
+<summary><b>Windows: missing Microsoft Edge WebView2 Runtime (common on intranet images)</b></summary>
+
+The GoNavi desktop app on Windows depends on the **Microsoft Edge WebView2 Runtime** (a system component, not full Chrome).  
+Some intranet / thin / Server / LTSC images ship without it. Symptoms:
+
+- Process exits immediately, blank/white window
+- Errors about missing WebView2 / WebView2 Runtime
+- Installer blocked by AV or group policy
+
+### 1. Check whether Runtime is installed
+
+In **PowerShell**:
+
+```powershell
+# Common Evergreen install path (64-bit Windows)
+Test-Path "${env:ProgramFiles(x86)}\Microsoft\EdgeWebView\Application"
+
+# Registry (a `pv` version usually means installed)
+Get-ItemProperty -Path "HKLM:\SOFTWARE\WOW6432Node\Microsoft\EdgeUpdate\Clients\{F3017226-FE2A-4295-8BDF-00C3A9A7E4C5}" `
+  -ErrorAction SilentlyContinue |
+  Select-Object pv, name
+```
+
+If the path is missing and registry has no `pv`, install the Runtime.
+
+### 2. Online install (simplest)
+
+1. Open the official download page:  
+   [Microsoft Edge WebView2](https://developer.microsoft.com/microsoft-edge/webview2/)
+2. Download the **Evergreen Bootstrapper** (small; needs network during install)
+3. Run as Administrator, then **restart GoNavi**
+
+### 3. Offline / intranet: Standalone installer (recommended for IT)
+
+The Bootstrapper fails on fully air-gapped machines. Use the **Evergreen Standalone Installer** instead:
+
+1. On a machine with internet, download the matching architecture package, e.g.:
+   - `MicrosoftEdgeWebView2RuntimeInstallerX64.exe` (most 64-bit PCs)
+   - `…X86.exe` / `…ARM64.exe` as needed
+2. Copy the installer into the intranet (USB, software center, share)
+3. Install **as Administrator** on the target PC:
+
+```powershell
+# Interactive
+.\MicrosoftEdgeWebView2RuntimeInstallerX64.exe
+
+# Silent (batch / SCCM friendly)
+.\MicrosoftEdgeWebView2RuntimeInstallerX64.exe /silent /install
+```
+
+4. Start GoNavi again. If it still fails, sign out or reboot Windows once.
+
+### 4. Group policy / locked-down PCs
+
+- Needs local admin, or IT push via SCCM / software center  
+- Ensure policies do not block Edge/WebView2 install or updates  
+- Enterprises may pin a [Fixed Version](https://developer.microsoft.com/microsoft-edge/webview2/) Runtime (most users should prefer Evergreen)
+
+### 5. Temporary workaround: Web Server mode
+
+If the desktop WebView cannot be installed yet, run the experimental Web Server and use a normal browser:
+
+```powershell
+.\GoNavi.exe web-server --addr 127.0.0.1:34116
+```
+
+Open `http://127.0.0.1:34116`. See the **Web Server** section above.  
+Do **not** expose an unhardened Web endpoint to the public internet.
+
+Tracker / discussion: [#672](https://github.com/Syngnat/GoNavi/issues/672).
+
+</details>
+
+<details>
+<summary><b>macOS: “App is damaged and can’t be opened”</b></summary>
+
+Without Apple notarization, Gatekeeper may block the app:
 
 ```bash
 sudo xattr -rd com.apple.quarantine /Applications/GoNavi.app
 ```
 
-Or right-click the app in Finder and choose **Open** with Control key flow.
+Or right-click → Open (Control-click flow). Move the app to **Applications** first.
 
-### Linux: missing `libwebkit2gtk` / `libjavascriptcoregtk`
+</details>
 
-GoNavi depends on WebKitGTK runtime libraries.
+<details>
+<summary><b>Linux: missing WebKitGTK</b></summary>
 
 ```bash
 # Debian 13 / Ubuntu 24.04+
@@ -200,34 +428,92 @@ sudo apt-get update
 sudo apt-get install -y libgtk-3-0 libwebkit2gtk-4.0-37 libjavascriptcoregtk-4.0-18
 ```
 
-If you use Linux artifacts with the `-WebKit41` suffix, prefer Debian 13 / Ubuntu 24.04+.
+Artifacts with `-WebKit41` prefer Debian 13 / Ubuntu 24.04+.
+
+</details>
+
+<details>
+<summary><b>Linux: Chinese glyphs as tofu boxes</b></summary>
+
+```bash
+sudo apt-get update
+sudo apt-get install -y fonts-noto-cjk fonts-wqy-microhei
+fc-cache -fv
+```
+
+</details>
 
 ---
 
-## Contributing
+## 💖 Sponsors
 
-Issues and pull requests are welcome.
+<p align="center">
+  <a href="https://api-fast.hualong.online/">
+    <img src="assets/sponsors/hualong-mark.png" width="120" alt="华龙中转站 Hualong Transfer Station" />
+  </a>
+</p>
 
-For the full workflow, branch model, and maintainer sync rules, see:
+<p align="center">
+  <b><a href="https://api-fast.hualong.online/">华龙中转站 · Hualong Transfer Station</a></b><br/>
+  <sub>AI API Gateway · multi-model routing · domestic high-speed endpoint</sub>
+</p>
+
+Special thanks to **[华龙中转站 (Hualong Transfer Station)](https://api-fast.hualong.online/)** for sponsoring GoNavi open-source development.
+
+| | |
+|---|---|
+| **What they are** | An **AI API Gateway** that unifies multi-model access behind an OpenAI-compatible surface — so you can ship LLM features without fighting provider fragmentation and network friction. |
+| **What you get** | Multi-model routing · OpenAI-compatible API · **domestic high-speed direct endpoint** · practical for indie devs and open-source projects that need reliable LLM access |
+| **Why we recommend them** | GoNavi is AI/MCP-first. Stable model access is core infrastructure for coding agents, schema-aware assistants, and day-to-day development. |
+
+**Looking for a solid LLM relay?**  
+👉 [https://api-fast.hualong.online/](https://api-fast.hualong.online/) — console, docs, and the domestic high-speed endpoint.
+
+> Hualong also sponsored a **shared 50B token pool** for GoNavi **co-maintainers**, used via **API Key** (not 50B per person). Rules and how to apply: [Issue #671](https://github.com/Syngnat/GoNavi/issues/671).
+
+---
+
+## 🤝 Contributing
+
+Issues and PRs welcome. Branch from **`dev`**, PR against **`dev`**.
 
 - [CONTRIBUTING.md](CONTRIBUTING.md)
+- Call for contributors (incl. sponsored token pool): [Issue #671](https://github.com/Syngnat/GoNavi/issues/671)
 
-External contributors should branch from `dev` and open pull requests against `dev`.
+---
 
-## Star History
-<a href="https://www.star-history.com/?repos=Syngnat%2FGoNavi&type=date&legend=top-left">
- <picture>
-   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/image?repos=Syngnat/GoNavi&type=date&theme=dark&legend=top-left" />
-   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/image?repos=Syngnat/GoNavi&type=date&legend=top-left" />
-   <img alt="Star History Chart" src="https://api.star-history.com/image?repos=Syngnat/GoNavi&type=date&legend=top-left" />
- </picture>
-</a>
+## 💬 Contact & Feedback
+
+| Channel | Notes |
+|---|---|
+| **GitHub Issues** | Preferred for bugs, feature requests, and docs — easier to track and reproduce |
+| **WeChat** | `ygf1140302783` (note “GoNavi”) — maintainer can invite you to the community group for discussion |
+
+> For technical reports, include version, OS, and repro steps when possible. Windows blank/crash on intranet images: [WebView2 guide](https://github.com/Syngnat/GoNavi/issues/672).
+
+---
+
+## ⭐ Star History
+
+<!-- star-history:start -->
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="assets/star-history/star-history-dark.svg">
+  <img alt="Star history" src="assets/star-history/star-history-light.svg">
+</picture>
+<!-- star-history:end -->
+
+---
 
 ## Links
 
+- [华龙中转站 · Hualong Transfer Station](https://api-fast.hualong.online/) — AI API Gateway (GoNavi sponsor)
 - [linux.do](https://linux.do/)
 - [AIBook](https://aibook.ren/)
 
 ## License
 
-Licensed under [Apache-2.0](LICENSE).
+[Apache-2.0](LICENSE)
+
+<p align="center">
+  <sub>Built for people who live in SQL, schemas, and agent loops.</sub>
+</p>

README.zh-CN.md

@@ -1,179 +1,422 @@
-# GoNavi - 现代化轻量级数据库客户端
+<p align="center">
+  <img src="assets/readme-logo.png" width="128" alt="GoNavi Logo" />
+</p>
 
-[![Go Version](https://img.shields.io/github/go-mod/go-version/Syngnat/GoNavi)](https://go.dev/)
-[![Wails Version](https://img.shields.io/badge/Wails-v2-red)](https://wails.io)
-[![React Version](https://img.shields.io/badge/React-v18-blue)](https://reactjs.org/)
-[![License](https://img.shields.io/badge/License-Apache%202.0-green.svg)](LICENSE)
-[![Build Status](https://img.shields.io/github/actions/workflow/status/Syngnat/GoNavi/release.yml?label=Build)](https://github.com/Syngnat/GoNavi/actions)
-[![Stars](https://img.shields.io/github/stars/Syngnat/GoNavi?style=social)](https://github.com/Syngnat/GoNavi/stargazers)
-[![Downloads](https://img.shields.io/github/downloads/Syngnat/GoNavi/total?color=blue&label=downloads)](https://github.com/Syngnat/GoNavi/releases)
+<h1 align="center">GoNavi</h1>
 
-**语言**: [English](README.md) | 简体中文
+<p align="center">
+  <b>一套客户端，航行全部数据源 — 原生性能 · Agent 就绪 · 告别 Electron 膨胀。</b>
+</p>
 
-GoNavi 是基于 **Wails (Go)** 与 **React** 构建的跨平台数据库管理工具，强调原生性能、低资源占用与多数据源统一工作流。
+<p align="center">
+  基于 <a href="https://wails.io">Wails</a>（Go）+ <a href="https://react.dev">React</a> 的跨平台数据库工作台。
+  桌面优先，MCP 原生，二进制约 <b>30MB</b> 量级。
+</p>
 
-相比常见 Electron 客户端，GoNavi 在体积、启动速度和内存占用上更轻量。
+<p align="center">
+  <a href="https://github.com/Syngnat/GoNavi/releases"><img src="https://img.shields.io/github/v/release/Syngnat/GoNavi?style=for-the-badge&color=8B5CF6" alt="Release" /></a>
+  <a href="https://github.com/Syngnat/GoNavi/releases"><img src="https://img.shields.io/github/downloads/Syngnat/GoNavi/total?style=for-the-badge&color=6366F1&label=downloads" alt="Downloads" /></a>
+  <a href="https://github.com/Syngnat/GoNavi/stargazers"><img src="https://img.shields.io/github/stars/Syngnat/GoNavi?style=for-the-badge&color=F59E0B" alt="Stars" /></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/License-Apache%202.0-22C55E?style=for-the-badge" alt="License" /></a>
+</p>
+
+<p align="center">
+  <a href="https://go.dev"><img src="https://img.shields.io/github/go-mod/go-version/Syngnat/GoNavi?style=flat-square&logo=go&logoColor=white&label=Go" alt="Go" /></a>
+  <a href="https://wails.io"><img src="https://img.shields.io/badge/Wails-v2-red?style=flat-square" alt="Wails" /></a>
+  <a href="https://reactjs.org"><img src="https://img.shields.io/badge/React-18-61DAFB?style=flat-square&logo=react&logoColor=white" alt="React" /></a>
+  <a href="https://github.com/Syngnat/GoNavi/actions"><img src="https://img.shields.io/github/actions/workflow/status/Syngnat/GoNavi/release.yml?style=flat-square&label=Build" alt="Build" /></a>
+</p>
+
+<p align="center">
+  <b>语言</b>：<a href="README.md">English</a> · 简体中文
+  &nbsp;·&nbsp;
+  <a href="https://github.com/Syngnat/GoNavi/releases"><b>⬇ 下载</b></a>
+  ·
+  <a href="#-快速开始"><b>⚡ 快速开始</b></a>
+  ·
+  <a href="#-核心能力"><b>✨ 特性</b></a>
+  ·
+  <a href="#-mcp--agents"><b>🤖 MCP</b></a>
+</p>
+
+<p align="center">
+  <sub>赞助商 ·
+  <a href="#-赞助商"><b>华龙中转站</b></a></sub>
+</p>
 
 ---
 
-## 项目简介
+## 为什么是 GoNavi？
 
-GoNavi 面向开发者与 DBA，核心目标是让数据库操作在桌面端做到“快、稳、统一”。
+市面上大量数据库 GUI 仍是 Electron 壳：体积大、启动慢、内存高。GoNavi 换了一条路：
 
-- **原生性能架构**：Wails（Go + WebView），降低运行时开销。
-- **大数据可用性**：虚拟滚动 + DataGrid 交互优化，提升大结果集可操作性。
-- **统一连接能力**：支持 URI 生成/解析、SSH 隧道、代理、驱动按需安装。
-- **工程化能力完整**：覆盖 SQL 编辑、对象管理、批量导出/备份、数据同步、执行日志、在线更新。
+| | 常见 Electron 客户端 | **GoNavi** |
+|---|---|---|
+| 运行时 | Chromium + Node | **Go + 系统 WebView** |
+| 体积 | 动辄数百 MB | **约 30MB 量级** |
+| 启动 | 偏重 | **更快** |
+| 内存 | 基线高 | **更轻** |
+| AI / Agent | 外挂或缺失 | **MCP + 多模型一等公民** |
+| 数据源 | 以 RDBMS 为主 | **SQL · 缓存 · 向量 · 消息 · 搜索 · 时序 · 国产库** |
 
-## 支持的数据源
+> **MySQL、Postgres、Redis、Kafka、Milvus、OceanBase、ClickHouse… 一个工作台打通。**  
+> 查询、编辑、审计、同步；把结构化上下文交给编码 Agent，密码仍留在本机。
 
-> `内置`：主程序开箱即用。  
-> `可选驱动代理`：需在驱动管理中安装启用后可用。
+---
+
+## 一眼看懂
+
+```text
+┌──────────────────────────────────────────────────────────────────────┐
+│  GoNavi 工作台                                                       │
+│  ┌─────────────┐  ┌──────────────────┐  ┌─────────────────────────┐  │
+│  │ 连接管理    │  │ Monaco SQL + AI  │  │ 虚拟滚动 DataGrid       │  │
+│  │ SSH / 代理  │  │ 表结构上下文     │  │ 批量编辑 · 导出         │  │
+│  │ 驱动代理    │  │ 快捷指令         │  │ 事务提交 / 回滚         │  │
+│  └─────────────┘  └────────┬─────────┘  └─────────────────────────┘  │
+│                            │                                         │
+│              ┌─────────────▼─────────────┐                           │
+│              │  Go 核心 · 审计 · 同步    │                           │
+│              │  MCP HTTP · Web Server    │                           │
+│              └───────────────────────────┘                           │
+└──────────────────────────────────────────────────────────────────────┘
+```
+
+### 产品截图
+
+每张均为 **完整 GoNavi 应用窗口**，再通过 README 宽度控件等比例缩小展示。
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/Syngnat/GoNavi/dev/assets/screenshots/01-home-workbench.png" alt="GoNavi 全窗口 — 连接、查询与工作台" width="560" />
+  &nbsp;
+  <img src="https://raw.githubusercontent.com/Syngnat/GoNavi/dev/assets/screenshots/04-ai-assistant.png" alt="GoNavi 全窗口 — 带表结构上下文的 AI 助手" width="560" />
+</p>
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/Syngnat/GoNavi/dev/assets/screenshots/06-new-connection.png" alt="GoNavi 全窗口 — 新建连接的数据源选择器" width="560" />
+</p>
+
+<p align="center"><sub>真实桌面全窗口截图</sub></p>
+
+---
+
+## ✨ 核心能力
+
+<table>
+<tr>
+<td width="50%" valign="top">
+
+### 🤖 懂表结构的 AI
+- OpenAI · Gemini · Claude · 自定义 OpenAI 兼容 API  
+- 将当前库表结构注入对话上下文  
+- 快捷指令：生成 SQL、解释、优化、表设计评审  
+- **MCP**：一键装到 Claude Code / Codex，或 Streamable HTTP 给远端 Agent  
+- 连接与密码留在运行 GoNavi 的主机上  
+
+</td>
+<td width="50%" valign="top">
+
+### ⚡ 大数据仍流畅
+- 虚拟滚动 DataGrid，扛住大结果集  
+- 单元格编辑 · 批量增删改 · 事务提交/回滚  
+- 大字段弹窗 · 按查询智能切换读写  
+- 导出：CSV · XLSX · JSON · Markdown  
+- Monaco + 库/表/字段上下文补全  
+
+</td>
+</tr>
+<tr>
+<td width="50%" valign="top">
+
+### 🔌 连接与驱动
+- URI 生成 / 解析  
+- SSH 隧道 · 代理  
+- 连接配置 JSON 导入导出  
+- 可选驱动代理按需安装  
+- Custom Driver + DSN 扩展  
+
+</td>
+<td width="50%" valign="top">
+
+### 🛡️ 可观测 & 可交付
+- SQL 执行日志（含耗时）  
+- 审计中心（默认脱敏、保留策略、导出）  
+- 桌面端 + 实验性 **Web Server**  
+- Docker / K8s / Helm / Podman  
+- 更新检查 · 多架构发布  
+
+</td>
+</tr>
+</table>
+
+### 🧩 技术栈
+
+`Go 1.24` · `Wails v2` · `React 18` · `TypeScript` · `Vite` · `Ant Design 5` · `Zustand` · `Monaco`
+
+---
+
+## 🗄 支持的数据源
+
+> **内置**：开箱即用 · **可选驱动代理**：在驱动管理中安装启用
+
+| | |
+|---|---|
+| **内置** | MySQL · GoldenDB · PostgreSQL · Oracle · Redis · Chroma · Qdrant · Milvus · RocketMQ · MQTT · Kafka · RabbitMQ |
+| **可选** | MariaDB · Doris · StarRocks · Sphinx · SQL Server · SQLite · DuckDB · OceanBase · 达梦 · 人大金仓 · 瀚高 · 海量 · openGauss · GaussDB · IRIS · MongoDB · TDengine · IoTDB · ClickHouse · Trino · Elasticsearch · Custom Driver/DSN |
+
+<details>
+<summary><b>完整能力矩阵</b></summary>
 
 | 类别 | 数据源 | 驱动模式 | 典型能力 |
 |---|---|---|---|
 | 关系型 | MySQL | 内置 | 库表浏览、SQL 查询、数据编辑、导出/备份 |
+| 国产数据库 | GoldenDB | 内置 | MySQL 兼容查询工作流、分布式事务场景 |
 | 关系型 | PostgreSQL | 内置 | 库表浏览、SQL 查询、数据编辑、对象管理 |
 | 关系型 | Oracle | 内置 | 连接查询、对象浏览、数据编辑 |
 | 缓存 | Redis | 内置 | Key 浏览、命令执行、编码/视图切换 |
+| 向量数据库 | Chroma | 内置 | Collection 浏览、向量检索、元数据过滤 |
+| 向量数据库 | Qdrant | 内置 | Collection 浏览、向量搜索、Payload 过滤 |
+| 向量数据库 | Milvus | 内置 | Collection 浏览、向量搜索、标量过滤 |
+| 消息队列 | RocketMQ | 内置 | Topic 浏览、消费组检查、消息型工作流 |
+| 消息队列 | MQTT | 内置 | Broker / Topic Filter 工作流与 QoS 连接配置 |
+| 消息队列 | Kafka | 内置 | Topic 浏览、Broker 元数据、消费组工作流 |
+| 消息队列 | RabbitMQ | 内置 | Queue / Exchange 浏览、Virtual Host 检查、Management API 工作流 |
 | 关系型 | MariaDB | 可选驱动代理 | 连接查询、对象管理、数据编辑 |
 | 关系型 | Doris | 可选驱动代理 | 连接查询、对象浏览、SQL 执行 |
+| 列式分析 | StarRocks | 可选驱动代理 | 连接查询、对象浏览、SQL 执行 |
 | 搜索 | Sphinx | 可选驱动代理 | SphinxQL 查询与对象浏览 |
 | 关系型 | SQL Server | 可选驱动代理 | 库表浏览、SQL 查询、对象管理 |
 | 文件型 | SQLite | 可选驱动代理 | 本地文件库浏览、编辑、导出 |
 | 文件型 | DuckDB | 可选驱动代理 | 大表查询、分页浏览、文件库管理 |
+| 国产数据库 | OceanBase | 可选驱动代理 | MySQL / Oracle 租户接入、对象浏览、查询工作流 |
 | 国产数据库 | Dameng | 可选驱动代理 | 连接查询、对象浏览、数据编辑 |
 | 国产数据库 | Kingbase | 可选驱动代理 | 连接查询、对象浏览、数据编辑 |
 | 国产数据库 | HighGo | 可选驱动代理 | 连接查询、对象浏览、数据编辑 |
 | 国产数据库 | Vastbase | 可选驱动代理 | 连接查询、对象浏览、数据编辑 |
+| 国产数据库 | OpenGauss | 可选驱动代理 | 类 PostgreSQL 的库表浏览、SQL 查询、对象管理 |
+| 国产数据库 | GaussDB | 可选驱动代理 | 类 PostgreSQL 的库表浏览、SQL 查询、对象管理 |
+| 多模型数据库 | InterSystems IRIS | 可选驱动代理 | Namespace 浏览、SQL 查询、对象管理 |
 | 文档型 | MongoDB | 可选驱动代理 | 文档查询、集合浏览、连接管理 |
 | 时序 | TDengine | 可选驱动代理 | 时序库表浏览、查询分析 |
+| 时序 | Apache IoTDB | 可选驱动代理 | Storage Group / Device / Timeseries 浏览与查询 |
 | 列式分析 | ClickHouse | 可选驱动代理 | 分析查询、对象浏览、SQL 执行 |
+| 联邦查询 | Trino | 可选驱动代理 | 跨多数据源联邦 SQL、`catalog.schema` 浏览、SQL 执行 |
+| 搜索 | Elasticsearch | 可选驱动代理 | 索引浏览、Mapping 检查、JSON DSL / query_string 查询 |
 | 扩展接入 | Custom Driver/DSN | 自定义 | 通过 Driver + DSN 接入更多数据源 |
 
-<h2 align="center">📸 项目截图</h2>
-
-<div align="center">
-    <img width="25%" alt="image" src="https://github.com/user-attachments/assets/0eefe07f-2836-44fa-9ddf-a0d2124b90e2" />
-    <img width="25%" alt="image" src="https://github.com/user-attachments/assets/6765e539-83ea-4cd6-9c9e-f42790fa05b5" />
-    <img width="25%" alt="image" src="https://github.com/user-attachments/assets/60e3d187-171a-4248-94e0-c6b08736e235" />
-    <br />
-    <img width="25%" alt="image" src="https://github.com/user-attachments/assets/7a478602-0f08-4b30-8f6a-879f4a60ae32" />
-    <img width="14%" alt="image" src="https://github.com/user-attachments/assets/6442ca7d-ce9e-46d9-aecd-405ba88f5a5e" />
-    <img width="25%" alt="image" src="https://github.com/user-attachments/assets/bc17895e-02a4-4cc5-b471-c3803cf25a2b" />
-</div>
+</details>
 
 ---
 
-## 核心特性
-
-### AI 智能助手 (New)
-- **多模型服务商支持**：内置跨平台接入 OpenAI, Google Gemini, Anthropic Claude，同时支持任意自定义兼容 OpenAI 格式的 API。
-- **关联表结构上下文**：原生支持将当前数据库表结构直接提取作为上下文发送给 AI，让 SQL 生成、分析变得更精准。
-- **快捷指令**：内置多种快捷对话指（如一键生成 SQL、解释执行逻辑、分析性能优化、表字段代码评审等）。
-
-### 性能与交互
-- 大数据场景下保持流畅交互（含 DataGrid 列宽拖拽、批量编辑流程优化）。
-- 虚拟滚动渲染，降低大结果集卡顿风险。
-
-### 数据管理（DataGrid）
-- 单元格所见即所得编辑。
-- 批量新增/修改/删除，支持事务提交与回滚。
-- 大字段弹窗编辑。
-- 右键上下文操作（NULL、复制、导出等）。
-- 根据查询上下文智能切换读写模式。
-- 支持 CSV / XLSX / JSON / Markdown 导出。
-
-### SQL 编辑器
-- 基于 Monaco Editor。
-- 上下文补全（数据库/表/字段）。
-- 多标签查询工作流。
-
-### 连接与驱动
-- URI 生成与解析。
-- SSH 隧道、代理支持。
-- 连接配置 JSON 导入/导出。
-- 可选驱动安装与启用管理。
-
-### Redis 工具
-- 自动/原始文本/UTF-8/十六进制等视图模式。
-- 内置命令执行面板。
-
-### 可观测性与更新
-- SQL 执行日志（含耗时）。
-- 启动/定时/手动更新检查。
-
-### UI 体验
-- Ant Design 5 体系。
-- 深色/浅色主题切换。
-- 灵活布局与侧边栏行为。
-
----
-
-## 技术栈
-
-- **后端**: Go 1.24 + Wails v2
-- **前端**: React 18 + TypeScript + Vite
-- **UI 框架**: Ant Design 5
-- **状态管理**: Zustand
-- **编辑器**: Monaco Editor
-
----
-
-## 安装与运行
+## 🚀 快速开始
 
 ### 前置要求
+
 - [Go](https://go.dev/dl/) 1.21+
 - [Node.js](https://nodejs.org/) 18+
-- [Wails CLI](https://wails.io/docs/gettingstarted/installation):
-  `go install github.com/wailsapp/wails/v2/cmd/wails@latest`
-
-### 开发模式
+- [Wails CLI](https://wails.io/docs/gettingstarted/installation)
+
+```bash
+go install github.com/wailsapp/wails/v2/cmd/wails@v2.11.0
+```
+
+### 开发
 
 ```bash
-# 克隆项目
 git clone https://github.com/Syngnat/GoNavi.git
 cd GoNavi
 
-# 启动开发（热重载）
-wails dev
+wails dev                          # 完整热重载
+node tools/wails-fast-dev.mjs      # Go 导出签名未变时更快
+node tools/wails-fast-dev.mjs --refresh-bindings  # 修改导出方法签名后刷新绑定
 ```
 
-### 编译构建
+### 构建
 
 ```bash
-# 构建当前平台
 wails build
-
-# 清理后构建（发布前推荐）
-wails build -clean
+wails build -clean   # 发布前推荐
 ```
 
-构建产物位于 `build/bin`。
+产物位于 `build/bin`。
 
-### 跨平台发布（GitHub Actions）
+### 只想直接用？
 
-仓库内置发布流水线，推送 `v*` Tag 可自动构建并发布 Release。
-Release 更新说明会基于已合并 Pull Request 自动生成，并按 `.github/release.yaml` 分类。
-
-支持目标：
-- macOS (AMD64 / ARM64)
-- Windows (AMD64)
-- Linux (AMD64，含 WebKitGTK 4.0 / 4.1 变体)
+前往 **[Releases](https://github.com/Syngnat/GoNavi/releases)** 下载  
+（macOS AMD64/ARM64 · Windows AMD64 · Linux WebKitGTK 4.0/4.1）。
 
 ---
 
-## 常见问题
+## 🌐 Web Server（实验中）
 
-### macOS 提示“应用已损坏，无法打开”
+同一套 Go 后端 + React 前端提供浏览器访问（**不是**把 Wails 桌面窗口容器化）。
 
-在未进行 Apple Notarization 时，Gatekeeper 可能拦截应用。
+```powershell
+go build .
+.\GoNavi-Wails.exe web-server --addr 127.0.0.1:34116
+```
+
+- 首次访问进入 `/setup`（管理员密码；可选 Google Authenticator）
+- 桥接：`window.go.*` / `window.runtime.*` → HTTP / SSE
+- Session、恢复码、登录限流
+
+#### Docker / Podman
+
+```bash
+cp docker.web-server.env.example docker.web-server.env
+# 设置 GONAVI_HOST_DATA_ROOT 为绝对路径
+# 可选：GONAVI_WEB_PASSWORD（至少 6 位）
+docker compose --env-file docker.web-server.env -f docker-compose.web-server.yml up -d
+```
+
+打开 `http://127.0.0.1:34116`。将活动数据目录挂载到 `/data`  
+（`connections.json`、`daily_secrets.json`，可选 `drivers/`）。  
+认证状态写入 `web_auth.json`。
+
+> **不要把未加固的 Web 入口直接暴露到公网。** 生产环境请配合反向代理与 HTTPS。
+
+健康检查：`GET /__gonavi/healthz`  
+本地源码构建：叠加 `-f docker-compose.web-server.local.yml --build`。
+
+修改 env 密码后需重建容器：
+
+```bash
+docker compose --env-file docker.web-server.env -f docker-compose.web-server.yml up -d --force-recreate
+```
+
+（`docker restart` **不会**重新加载 env 文件。）
+
+---
+
+## 🤖 MCP & Agents
+
+把结构工具交给 Agent，而不是把密钥交出去：
+
+```bash
+cp docker.mcp-server.env.example docker.mcp-server.env
+docker compose --env-file docker.mcp-server.env -f docker-compose.mcp-server.yml up -d
+```
+
+| 形态 | 入口 |
+|---|---|
+| MCP 容器 | `docker-compose.mcp-server.yml` → `ghcr.io/syngnat/gonavi-mcp-server` |
+| Web UI 容器 | `docker-compose.web-server.yml` → `ghcr.io/syngnat/gonavi-web-server` |
+| Podman / Quadlet | [deploy/podman/gonavi-mcp-server](deploy/podman/gonavi-mcp-server) |
+| Kubernetes | [deploy/k8s/gonavi-mcp-server](deploy/k8s/gonavi-mcp-server) |
+| Helm | [deploy/helm/gonavi-mcp-server](deploy/helm/gonavi-mcp-server) |
+| 仅构建镜像 | `Dockerfile.build-env` → `ghcr.io/syngnat/gonavi-build-env` |
+
+安全默认：远端 `schema-only` 不暴露 `execute_sql`；变更类 SQL 需显式 `allowMutating=true`。  
+详见：[cmd/gonavi-mcp-server/README.md](cmd/gonavi-mcp-server/README.md)。
+
+### 仅 Linux 构建环境
+
+```bash
+docker build -f Dockerfile.build-env -t gonavi-build-env:local .
+docker run --rm -it -v "$PWD:/workspace" -w /workspace gonavi-build-env:local bash
+```
+
+---
+
+## 📦 发布流水线
+
+推送 `v*` Tag → GitHub Actions 自动多架构构建。  
+Release 说明按 `.github/release.yaml` 从已合并 PR 生成。
+
+---
+
+## 🛠 常见问题
+
+<details>
+<summary><b>Windows：缺少 Microsoft Edge WebView2 运行时（内网常见）</b></summary>
+
+GoNavi 桌面版在 Windows 上依赖 **Microsoft Edge WebView2 Runtime**（系统级组件，不是完整 Chrome）。  
+部分内网 / 精简镜像 / Windows Server / LTSC 机器未预装，会出现：
+
+- 双击后窗口一闪即关、白屏、空白窗口
+- 提示找不到 WebView2 / WebView2 Runtime
+- 杀软或组策略拦截了运行时安装
+
+### 1. 先确认是否已安装
+
+在 **PowerShell** 中执行：
+
+```powershell
+# Evergreen Runtime 常见安装目录（64 位系统）
+Test-Path "${env:ProgramFiles(x86)}\Microsoft\EdgeWebView\Application"
+
+# 注册表（有显示名称通常表示已安装）
+Get-ItemProperty -Path "HKLM:\SOFTWARE\WOW6432Node\Microsoft\EdgeUpdate\Clients\{F3017226-FE2A-4295-8BDF-00C3A9A7E4C5}" `
+  -ErrorAction SilentlyContinue |
+  Select-Object pv, name
+```
+
+若路径不存在且注册表无 `pv` 版本号，需要安装运行时。
+
+### 2. 有外网：在线安装（最简单）
+
+1. 打开微软官方下载页：  
+   [Microsoft Edge WebView2](https://developer.microsoft.com/microsoft-edge/webview2/)
+2. 下载 **Evergreen Bootstrapper**（体积小，安装时联网拉完整运行时）
+3. 右键「以管理员身份运行」安装完成后，**重新打开 GoNavi**
+
+### 3. 内网 / 离线：独立安装包（推荐企业分发）
+
+Bootstrapper 在完全断网环境会失败。请改用 **Evergreen Standalone Installer**：
+
+1. 在一台能上网的电脑打开同一下载页，下载对应架构的独立安装包，例如：
+   - `MicrosoftEdgeWebView2RuntimeInstallerX64.exe`（绝大多数 64 位 Windows）
+   - `…X86.exe` / `…ARM64.exe`（按机器架构选择）
+2. 将安装包拷贝到内网（U 盘、软件中心、文件共享均可）
+3. 在目标机 **管理员权限** 安装：
+
+```powershell
+# 交互安装
+.\MicrosoftEdgeWebView2RuntimeInstallerX64.exe
+
+# 静默安装（便于 IT 批量推送）
+.\MicrosoftEdgeWebView2RuntimeInstallerX64.exe /silent /install
+```
+
+4. 安装完成后重新启动 GoNavi。若仍异常，注销/重启一次 Windows 再试。
+
+### 4. 组策略 / 权限受限时
+
+- 需要本地管理员或由 IT 通过 SCCM / 软件中心推送 Standalone 安装包  
+- 确认未禁用 Edge / WebView2 相关更新与安装策略  
+- 企业可固定使用 [Fixed Version](https://developer.microsoft.com/microsoft-edge/webview2/) 运行时并由管理员统一维护（一般用户优先 Evergreen）
+
+### 5. 临时绕过：Web Server 模式（仍需能跑 GoNavi 后端）
+
+若桌面 WebView 短期无法装上，可在本机用浏览器访问实验性 Web Server（**不是**把桌面窗口容器化）：
+
+```powershell
+# 以发布包中的可执行文件为例
+.\GoNavi.exe web-server --addr 127.0.0.1:34116
+```
+
+浏览器打开 `http://127.0.0.1:34116`。详见上文「Web Server」章节。  
+注意：未加固的 Web 入口不要直接暴露到公网。
+
+更多说明与反馈入口见 Issue：[#672](https://github.com/Syngnat/GoNavi/issues/672)。
+
+</details>
+
+<details>
+<summary><b>macOS：提示「应用已损坏，无法打开」</b></summary>
+
+未做 Apple Notarization 时，Gatekeeper 可能拦截：
 
 ```bash
 sudo xattr -rd com.apple.quarantine /Applications/GoNavi.app
 ```
 
-### Linux 缺少 `libwebkit2gtk` / `libjavascriptcoregtk`
+也可在 Finder 中右键打开。建议先移到「应用程序」。
+
+</details>
+
+<details>
+<summary><b>Linux：缺少 WebKitGTK</b></summary>
 
 ```bash
 # Debian 13 / Ubuntu 24.04+
@@ -185,33 +428,92 @@ sudo apt-get update
 sudo apt-get install -y libgtk-3-0 libwebkit2gtk-4.0-37 libjavascriptcoregtk-4.0-18
 ```
 
+带 `-WebKit41` 后缀的产物更适配 Debian 13 / Ubuntu 24.04+。
+
+</details>
+
+<details>
+<summary><b>Linux：中文显示为方框</b></summary>
+
+```bash
+sudo apt-get update
+sudo apt-get install -y fonts-noto-cjk fonts-wqy-microhei
+fc-cache -fv
+```
+
+</details>
+
 ---
 
-## 贡献指南
+## 💖 赞助商
 
-欢迎提交 Issue 与 Pull Request。
+<p align="center">
+  <a href="https://api-fast.hualong.online/">
+    <img src="assets/sponsors/hualong-mark.png" width="120" alt="华龙中转站" />
+  </a>
+</p>
 
-完整流程、分支模型与维护者同步规则请查看：
+<p align="center">
+  <b><a href="https://api-fast.hualong.online/">华龙中转站 · Hualong Transfer Station</a></b><br/>
+  <sub>AI API Gateway · 多模型统一接入 · 国内直连高速端点</sub>
+</p>
+
+特别感谢 **[华龙中转站](https://api-fast.hualong.online/)** 赞助 GoNavi 开源开发。
+
+| | |
+|---|---|
+| **他们是谁** | **AI API 中转 / Gateway**：以 OpenAI 兼容接口统一多模型接入，帮你少踩「渠道碎片化 + 网络不稳定」的坑。 |
+| **核心能力** | 多模型统一路由 · OpenAI 兼容 · **国内直连高速端点** · 适合个人开发者与开源项目快速接通 LLM |
+| **为什么推荐** | GoNavi 自身是 AI / MCP 一等公民产品；稳定、好用的模型通道，是写代码、做 Agent、联调多 Provider 的基础设施。 |
+
+**需要靠谱的 LLM 中转？**  
+👉 [https://api-fast.hualong.online/](https://api-fast.hualong.online/) — 控制台、文档与国内高速端点。
+
+> 华龙另向本仓库赞助了 **共享 500 亿（50B）token** 额度，供 GoNavi **共建者** 以 **API Key** 方式协作开发使用（非整库人均 50B）。申请与规则见共建入口：[Issue #671](https://github.com/Syngnat/GoNavi/issues/671)。
+
+---
+
+## 🤝 贡献
+
+欢迎 Issue 与 PR。请从 **`dev`** 拉分支，并向 **`dev`** 提 PR。
 
 - [CONTRIBUTING.zh-CN.md](CONTRIBUTING.zh-CN.md)
+- 共建邀请（含赞助 token 池说明）：[Issue #671](https://github.com/Syngnat/GoNavi/issues/671)
 
-外部贡献者应从 `dev` 拉出分支，并统一向 `dev` 发起 Pull Request。
+---
 
-## Star History (Star 增长趋势)
+## 💬 联系与反馈
 
-<a href="https://www.star-history.com/?repos=Syngnat%2FGoNavi&type=date&legend=top-left">
- <picture>
-   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/image?repos=Syngnat/GoNavi&type=date&theme=dark&legend=top-left" />
-   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/image?repos=Syngnat/GoNavi&type=date&legend=top-left" />
-   <img alt="Star History Chart" src="https://api.star-history.com/image?repos=Syngnat/GoNavi&type=date&legend=top-left" />
- </picture>
-</a>
+| 渠道 | 说明 |
+|---|---|
+| **GitHub Issues** | Bug、功能建议、文档问题优先在此提交，便于跟踪与复现 |
+| **微信** | `ygf1140302783`（备注「GoNavi」）— 可拉交流群，适合使用讨论与快速沟通 |
+
+> 技术问题尽量附版本号、系统与复现步骤；内网 Windows 启动白屏/闪退见 [WebView2 说明](https://github.com/Syngnat/GoNavi/issues/672)。
+
+---
+
+## ⭐ Star History
+
+<!-- star-history:start -->
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="assets/star-history/star-history-dark.svg">
+  <img alt="Star history" src="assets/star-history/star-history-light.svg">
+</picture>
+<!-- star-history:end -->
+
+---
 
 ## 友情链接
 
+- [华龙中转站](https://api-fast.hualong.online/) — AI API Gateway（GoNavi 赞助商）
 - [linux.do](https://linux.do/)
 - [AI全书](https://aibook.ren/)
 
 ## 开源协议
 
-本项目采用 [Apache-2.0 协议](LICENSE)。
+[Apache-2.0](LICENSE)
+
+<p align="center">
+  <sub>为泡在 SQL、表结构与 Agent 循环里的人而造。</sub>
+</p>

assets/star-history/.star-history.sig

@@ -0,0 +1 @@
+144ec2c9ab4c0a69c453fea4e33549fdd8342757b406b614f300f9819122fd01

assets/star-history/last-star-count.txt

@@ -0,0 +1 @@
+1778

build-driver-agents.sh

@@ -5,7 +5,11 @@ set -euo pipefail
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 cd "$SCRIPT_DIR"
 
-DEFAULT_DRIVERS=(mariadb doris sphinx sqlserver sqlite duckdb dameng kingbase highgo vastbase mongodb tdengine clickhouse)
+DEFAULT_DRIVERS=(mariadb oceanbase doris starrocks sphinx sqlserver sqlite duckdb dameng kingbase highgo vastbase opengauss gaussdb iris mongodb tdengine iotdb clickhouse elasticsearch trino)
+DEFAULT_PLATFORMS=(darwin/amd64 darwin/arm64 windows/amd64 windows/arm64 linux/amd64 linux/arm64)
+DUCKDB_WINDOWS_LIBRARY_VERSION="v1.4.4"
+DUCKDB_WINDOWS_LIBRARY_URL="https://github.com/duckdb/duckdb/releases/download/${DUCKDB_WINDOWS_LIBRARY_VERSION}/libduckdb-windows-amd64.zip"
+DUCKDB_WINDOWS_SUPPORT_DLL="duckdb.dll"
 
 usage() {
   cat <<'EOF'
@@ -14,17 +18,21 @@ usage() {
 
 选项：
   --drivers <列表>      指定驱动列表（逗号分隔），例如：kingbase,mongodb
-  --platform <GOOS/GOARCH>
-                        目标平台，默认使用当前 Go 环境（go env GOOS/GOARCH）
+  --platform <目标>      目标平台：current、all、GOOS/GOARCH，或逗号分隔列表
+                        默认 current（当前 Go 环境）
   --out-dir <目录>      输出目录根路径，默认：dist/driver-agents
   --bundle-name <文件名> 驱动总包 zip 名称，默认：GoNavi-DriverAgents.zip
   --strict              任一驱动构建失败即中断（默认失败后继续，最后汇总）
+  --upx                 要求使用 UPX 压缩支持的平台产物（默认 auto：有 upx 则压缩）
+  --no-upx              禁用 UPX 压缩
   -h, --help            显示帮助
 
 示例：
   ./build-driver-agents.sh
   ./build-driver-agents.sh --drivers kingbase
   ./build-driver-agents.sh --platform windows/amd64 --drivers kingbase,mongodb
+  ./build-driver-agents.sh --platform all
+  ./build-driver-agents.sh --platform darwin/arm64,windows/amd64,linux/amd64
 EOF
 }
 
@@ -33,7 +41,10 @@ normalize_driver() {
   name="$(echo "${1:-}" | tr '[:upper:]' '[:lower:]' | xargs)"
   case "$name" in
     doris|diros) echo "doris" ;;
-    mariadb|sphinx|sqlserver|sqlite|duckdb|dameng|kingbase|highgo|vastbase|mongodb|tdengine|clickhouse)
+    open_gauss|open-gauss) echo "opengauss" ;;
+    gaussdb|gauss_db|gauss-db) echo "gaussdb" ;;
+    elasticsearch|elastic) echo "elasticsearch" ;;
+    mariadb|oceanbase|starrocks|sphinx|sqlserver|sqlite|duckdb|dameng|kingbase|highgo|vastbase|opengauss|gaussdb|iris|mongodb|tdengine|iotdb|clickhouse|trino)
       echo "$name"
       ;;
     *)
@@ -58,11 +69,177 @@ platform_dir_name() {
   esac
 }
 
+current_platform() {
+  echo "$(go env GOOS)/$(go env GOARCH)"
+}
+
+append_platform() {
+  local candidate
+  candidate="$1"
+  if [[ "$platform_seen" == *"|$candidate|"* ]]; then
+    return 0
+  fi
+  platforms+=("$candidate")
+  platform_seen="${platform_seen}${candidate}|"
+}
+
+normalize_platform() {
+  local value goos goarch platform_dir
+  value="$(printf '%s' "${1:-}" | tr '[:upper:]' '[:lower:]' | tr -d '[:space:]')"
+  case "$value" in
+    current|"")
+      current_platform
+      ;;
+    */*)
+      goos="${value%%/*}"
+      goarch="${value##*/}"
+      platform_dir="$(platform_dir_name "$goos")"
+      if [[ -z "$goos" || -z "$goarch" || "$platform_dir" == "Unknown" ]]; then
+        return 1
+      fi
+      echo "$goos/$goarch"
+      ;;
+    *)
+      return 1
+      ;;
+  esac
+}
+
+zip_bundle() {
+  local bundle_zip_path="$1"
+  local bundle_stage_dir="$2"
+  local -a bundle_dirs=()
+  local dir
+
+  for dir in "$bundle_stage_dir"/*; do
+    [[ -d "$dir" ]] || continue
+    bundle_dirs+=("$(basename "$dir")")
+  done
+
+  if [[ ${#bundle_dirs[@]} -eq 0 ]]; then
+    echo "❌ 驱动总包 staging 目录为空。"
+    exit 1
+  fi
+
+  rm -f "$bundle_zip_path"
+  if command -v zip >/dev/null 2>&1; then
+    (
+      cd "$bundle_stage_dir"
+      zip -qry "$bundle_zip_path" "${bundle_dirs[@]}"
+    )
+  elif command -v python3 >/dev/null 2>&1; then
+    BUNDLE_STAGE_DIR="$bundle_stage_dir" BUNDLE_ZIP_PATH="$bundle_zip_path" python3 - <<'PY'
+import os
+import zipfile
+from pathlib import Path
+
+stage = Path(os.environ["BUNDLE_STAGE_DIR"])
+target = Path(os.environ["BUNDLE_ZIP_PATH"])
+with zipfile.ZipFile(target, "w", compression=zipfile.ZIP_DEFLATED) as zf:
+    for path in stage.rglob("*"):
+        if path.is_file():
+            zf.write(path, path.relative_to(stage).as_posix())
+PY
+  else
+    echo "❌ 未找到 zip 或 python3，无法生成驱动总包 zip。"
+    exit 1
+  fi
+}
+
+zip_duckdb_windows_package() {
+  local bundle_stage_dir="$1"
+  local zip_path="$2"
+
+  rm -f "$zip_path"
+  if command -v python3 >/dev/null 2>&1; then
+    BUNDLE_STAGE_DIR="$bundle_stage_dir" BUNDLE_ZIP_PATH="$zip_path" python3 - <<'PY'
+import os
+import zipfile
+
+stage_dir = os.environ["BUNDLE_STAGE_DIR"]
+zip_path = os.environ["BUNDLE_ZIP_PATH"]
+entries = [
+    ("Windows/duckdb-driver-agent-windows-amd64.exe", os.path.join(stage_dir, "Windows", "duckdb-driver-agent-windows-amd64.exe")),
+    ("Windows/duckdb.dll", os.path.join(stage_dir, "Windows", "duckdb.dll")),
+]
+
+with zipfile.ZipFile(zip_path, "w", compression=zipfile.ZIP_DEFLATED) as zf:
+    for arcname, src in entries:
+        if not os.path.isfile(src):
+            raise FileNotFoundError(src)
+        zf.write(src, arcname)
+PY
+  elif command -v zip >/dev/null 2>&1; then
+    (
+      cd "$bundle_stage_dir"
+      zip -qry "$zip_path" "Windows/duckdb-driver-agent-windows-amd64.exe" "Windows/duckdb.dll"
+    )
+  else
+    echo "❌ 未找到 python3 或 zip，无法生成 DuckDB Windows 专属驱动包。"
+    exit 1
+  fi
+}
+
+prepare_duckdb_windows_library() {
+  local cache_root="$1"
+  local lib_dir="$cache_root/duckdb-windows-${DUCKDB_WINDOWS_LIBRARY_VERSION}"
+  local zip_path="$cache_root/libduckdb-windows-amd64.zip"
+
+  if [[ -f "$lib_dir/duckdb.dll" && -f "$lib_dir/duckdb.lib" ]]; then
+    printf '%s\n' "$lib_dir"
+    return 0
+  fi
+
+  mkdir -p "$lib_dir"
+  echo "⬇️  下载 DuckDB Windows 官方动态库：$DUCKDB_WINDOWS_LIBRARY_URL" >&2
+  if command -v curl >/dev/null 2>&1; then
+    curl -fsSL "$DUCKDB_WINDOWS_LIBRARY_URL" -o "$zip_path"
+  elif command -v wget >/dev/null 2>&1; then
+    wget -q "$DUCKDB_WINDOWS_LIBRARY_URL" -O "$zip_path"
+  else
+    echo "❌ 未找到 curl 或 wget，无法下载 DuckDB Windows 动态库。" >&2
+    return 1
+  fi
+
+  if command -v unzip >/dev/null 2>&1; then
+    unzip -qo "$zip_path" -d "$lib_dir"
+  elif command -v python3 >/dev/null 2>&1; then
+    DUCKDB_LIB_ZIP="$zip_path" DUCKDB_LIB_DIR="$lib_dir" python3 - <<'PY'
+import os
+import zipfile
+
+zip_path = os.environ["DUCKDB_LIB_ZIP"]
+target = os.environ["DUCKDB_LIB_DIR"]
+with zipfile.ZipFile(zip_path) as zf:
+    zf.extractall(target)
+PY
+  else
+    echo "❌ 未找到 unzip 或 python3，无法解压 DuckDB Windows 动态库。" >&2
+    return 1
+  fi
+
+  if [[ ! -f "$lib_dir/duckdb.dll" || ! -f "$lib_dir/duckdb.lib" ]]; then
+    echo "❌ DuckDB Windows 动态库包缺少 duckdb.dll 或 duckdb.lib。" >&2
+    return 1
+  fi
+
+  cp "$lib_dir/duckdb.lib" "$lib_dir/libduckdb.dll.a"
+  cp "$lib_dir/duckdb.lib" "$lib_dir/libduckdb.a"
+  printf '%s\n' "$lib_dir"
+}
+
+join_by_comma() {
+  local IFS=,
+  echo "$*"
+}
+
 driver_csv=""
 target_platform=""
 out_root="dist/driver-agents"
 bundle_name="GoNavi-DriverAgents.zip"
+duckdb_windows_zip_name="duckdb-driver.zip"
 strict_mode="false"
+upx_mode="${GONAVI_DRIVER_AGENT_UPX:-auto}"
 
 while [[ $# -gt 0 ]]; do
   case "$1" in
@@ -86,6 +263,14 @@ while [[ $# -gt 0 ]]; do
       strict_mode="true"
       shift
       ;;
+    --upx)
+      upx_mode="required"
+      shift
+      ;;
+    --no-upx)
+      upx_mode="off"
+      shift
+      ;;
     -h|--help)
       usage
       exit 0
@@ -103,20 +288,6 @@ if ! command -v go >/dev/null 2>&1; then
   exit 1
 fi
 
-if [[ -z "$target_platform" ]]; then
-  target_platform="$(go env GOOS)/$(go env GOARCH)"
-fi
-
-if [[ "$target_platform" != */* ]]; then
-  echo "❌ --platform 参数格式错误，应为 GOOS/GOARCH，例如 darwin/arm64"
-  exit 1
-fi
-
-goos="${target_platform%%/*}"
-goarch="${target_platform##*/}"
-platform_key="${goos}-${goarch}"
-platform_dir="$(platform_dir_name "$goos")"
-
 declare -a drivers=()
 if [[ -n "$driver_csv" ]]; then
   IFS=',' read -r -a raw_drivers <<<"$driver_csv"
@@ -130,67 +301,135 @@ if [[ -n "$driver_csv" ]]; then
 else
   drivers=("${DEFAULT_DRIVERS[@]}")
 fi
+revision_driver_csv="$(join_by_comma "${drivers[@]}")"
 
-output_dir="${out_root%/}/${platform_key}"
+declare -a platforms=()
+platform_seen="|"
+if [[ -z "$target_platform" ]]; then
+  target_platform="current"
+fi
+IFS=',' read -r -a raw_platforms <<<"$target_platform"
+for item in "${raw_platforms[@]}"; do
+  normalized_platform="$(printf '%s' "$item" | tr '[:upper:]' '[:lower:]' | tr -d '[:space:]')"
+  if [[ "$normalized_platform" == "all" ]]; then
+    for default_platform in "${DEFAULT_PLATFORMS[@]}"; do
+      append_platform "$default_platform"
+    done
+    continue
+  fi
+  normalized_platform="$(normalize_platform "$item")" || {
+    echo "❌ --platform 参数格式错误，应为 current、all、GOOS/GOARCH 或逗号分隔列表，例如 darwin/arm64,windows/amd64"
+    exit 1
+  }
+  append_platform "$normalized_platform"
+done
+
+if [[ ${#platforms[@]} -eq 0 ]]; then
+  echo "❌ 未指定有效目标平台。"
+  exit 1
+fi
+
+mkdir -p "$out_root"
+out_root_abs="$(cd "$out_root" && pwd)"
 bundle_stage_dir="$(mktemp -d "${TMPDIR:-/tmp}/gonavi-driver-bundle.XXXXXX")"
-bundle_platform_dir="$bundle_stage_dir/$platform_dir"
 
 cleanup() {
   rm -rf "$bundle_stage_dir"
 }
 trap cleanup EXIT
 
-mkdir -p "$output_dir" "$bundle_platform_dir"
-output_dir_abs="$(cd "$output_dir" && pwd)"
-bundle_zip_path="$output_dir_abs/$bundle_name"
+if [[ ${#platforms[@]} -eq 1 ]]; then
+  single_platform="${platforms[0]}"
+  single_platform_key="${single_platform/\//-}"
+  single_output_dir="${out_root%/}/$single_platform_key"
+  mkdir -p "$single_output_dir"
+  bundle_zip_path="$(cd "$single_output_dir" && pwd)/$bundle_name"
+else
+  bundle_zip_path="$out_root_abs/$bundle_name"
+fi
 
 declare -a built_assets=()
 declare -a failed_drivers=()
 declare -a skipped_drivers=()
 
 echo "🚀 开始构建 optional-driver-agent"
-echo "   平台：$goos/$goarch"
-echo "   输出目录：$output_dir_abs"
+echo "   平台：${platforms[*]}"
+echo "   输出根目录：$out_root_abs"
 echo "   驱动列表：${drivers[*]}"
 
-for driver in "${drivers[@]}"; do
-  if [[ "$driver" == "duckdb" && "$goos" == "windows" && "$goarch" != "amd64" ]]; then
-    echo "⚠️  跳过 duckdb（仅支持 windows/amd64）"
-    skipped_drivers+=("$driver")
-    continue
-  fi
+for platform in "${platforms[@]}"; do
+  goos="${platform%%/*}"
+  goarch="${platform##*/}"
+  platform_key="${goos}-${goarch}"
+  platform_dir="$(platform_dir_name "$goos")"
+  output_dir="${out_root%/}/${platform_key}"
+  bundle_platform_dir="$bundle_stage_dir/$platform_dir"
 
-  build_driver="$(build_driver_name "$driver")"
-  tag="gonavi_${build_driver}_driver"
-  asset_name="${driver}-driver-agent-${goos}-${goarch}"
-  if [[ "$goos" == "windows" ]]; then
-    asset_name="${asset_name}.exe"
-  fi
-  output_path="$output_dir_abs/$asset_name"
+  mkdir -p "$output_dir" "$bundle_platform_dir"
+  output_dir_abs="$(cd "$output_dir" && pwd)"
 
-  cgo_enabled=0
-  if [[ "$driver" == "duckdb" ]]; then
-    cgo_enabled=1
-  fi
+  echo ""
+  echo "🧭 生成 driver-agent revision 指纹：$platform"
+  "$SCRIPT_DIR/tools/generate-driver-agent-revisions.sh" --platform "$platform" --drivers "$revision_driver_csv"
 
-  echo "🔧 构建 $driver -> $asset_name (tag=$tag, CGO_ENABLED=$cgo_enabled)"
-  set +e
-  CGO_ENABLED="$cgo_enabled" GOOS="$goos" GOARCH="$goarch" GOTOOLCHAIN=auto \
-    go build -tags "$tag" -trimpath -ldflags "-s -w" -o "$output_path" ./cmd/optional-driver-agent
-  build_exit=$?
-  set -e
-
-  if [[ $build_exit -ne 0 ]]; then
-    echo "❌ 构建失败：$driver"
-    failed_drivers+=("$driver")
-    if [[ "$strict_mode" == "true" ]]; then
-      exit $build_exit
+  for driver in "${drivers[@]}"; do
+    if [[ "$driver" == "duckdb" && "$goos" == "windows" && "$goarch" != "amd64" ]]; then
+      echo "⚠️  跳过 duckdb（$platform 仅支持 windows/amd64）"
+      skipped_drivers+=("duckdb($platform)")
+      continue
     fi
-    continue
-  fi
 
-  cp "$output_path" "$bundle_platform_dir/$asset_name"
-  built_assets+=("$asset_name")
+    build_driver="$(build_driver_name "$driver")"
+    tag="gonavi_${build_driver}_driver"
+    build_tags="$tag"
+    asset_name="${driver}-driver-agent-${goos}-${goarch}"
+    if [[ "$goos" == "windows" ]]; then
+      asset_name="${asset_name}.exe"
+    fi
+    output_path="$output_dir_abs/$asset_name"
+
+    cgo_enabled=0
+    if [[ "$driver" == "duckdb" ]]; then
+      cgo_enabled=1
+    fi
+    duckdb_lib_dir=""
+    if [[ "$driver" == "duckdb" && "$goos" == "windows" && "$goarch" == "amd64" ]]; then
+      duckdb_lib_dir="$(prepare_duckdb_windows_library "$bundle_stage_dir")"
+      build_tags="$build_tags duckdb_use_lib"
+    fi
+
+    echo "🔧 构建 $driver -> $asset_name (platform=$platform, tags=$build_tags, CGO_ENABLED=$cgo_enabled)"
+    set +e
+    if [[ -n "$duckdb_lib_dir" ]]; then
+      CGO_ENABLED="$cgo_enabled" GOOS="$goos" GOARCH="$goarch" GOTOOLCHAIN=auto \
+        CGO_LDFLAGS="-L${duckdb_lib_dir} -lduckdb" PATH="${duckdb_lib_dir}:$PATH" \
+        go build -tags "$build_tags" -trimpath -ldflags "-s -w" -o "$output_path" ./cmd/optional-driver-agent
+    else
+      CGO_ENABLED="$cgo_enabled" GOOS="$goos" GOARCH="$goarch" GOTOOLCHAIN=auto \
+        go build -tags "$build_tags" -trimpath -ldflags "-s -w" -o "$output_path" ./cmd/optional-driver-agent
+    fi
+    build_exit=$?
+    set -e
+
+    if [[ $build_exit -ne 0 ]]; then
+      echo "❌ 构建失败：$driver ($platform)"
+      failed_drivers+=("$driver($platform)")
+      if [[ "$strict_mode" == "true" ]]; then
+        exit $build_exit
+      fi
+      continue
+    fi
+
+    GONAVI_DRIVER_AGENT_UPX="$upx_mode" "$SCRIPT_DIR/tools/compress-driver-artifact.sh" "$output_path" "$platform" "$platform_dir/$asset_name"
+    cp "$output_path" "$bundle_platform_dir/$asset_name"
+    if [[ -n "$duckdb_lib_dir" ]]; then
+      cp "$duckdb_lib_dir/$DUCKDB_WINDOWS_SUPPORT_DLL" "$output_dir_abs/$DUCKDB_WINDOWS_SUPPORT_DLL"
+      GONAVI_DRIVER_AGENT_UPX="$upx_mode" "$SCRIPT_DIR/tools/compress-driver-artifact.sh" "$output_dir_abs/$DUCKDB_WINDOWS_SUPPORT_DLL" "$platform" "$platform_dir/$DUCKDB_WINDOWS_SUPPORT_DLL"
+      cp "$output_dir_abs/$DUCKDB_WINDOWS_SUPPORT_DLL" "$bundle_platform_dir/$DUCKDB_WINDOWS_SUPPORT_DLL"
+      built_assets+=("$platform_dir/$DUCKDB_WINDOWS_SUPPORT_DLL")
+    fi
+    built_assets+=("$platform_dir/$asset_name")
+  done
 done
 
 if [[ ${#built_assets[@]} -eq 0 ]]; then
@@ -198,25 +437,19 @@ if [[ ${#built_assets[@]} -eq 0 ]]; then
   exit 1
 fi
 
-rm -f "$bundle_zip_path"
-if command -v zip >/dev/null 2>&1; then
-  (
-    cd "$bundle_stage_dir"
-    zip -qry "$bundle_zip_path" "$platform_dir"
-  )
-elif command -v ditto >/dev/null 2>&1; then
-  (
-    cd "$bundle_stage_dir"
-    ditto -c -k --sequesterRsrc --keepParent "$platform_dir" "$bundle_zip_path"
-  )
-else
-  echo "❌ 未找到 zip/ditto，无法生成驱动总包 zip。"
-  exit 1
+zip_bundle "$bundle_zip_path" "$bundle_stage_dir"
+
+duckdb_asset_path="$out_root_abs/windows-amd64/duckdb-driver-agent-windows-amd64.exe"
+duckdb_dll_path="$out_root_abs/windows-amd64/$DUCKDB_WINDOWS_SUPPORT_DLL"
+if [[ -f "$duckdb_asset_path" && -f "$duckdb_dll_path" ]]; then
+  duckdb_zip_path="$out_root_abs/windows-amd64/$duckdb_windows_zip_name"
+  zip_duckdb_windows_package "$bundle_stage_dir" "$duckdb_zip_path"
+  built_assets+=("Windows/$duckdb_windows_zip_name")
 fi
 
 echo ""
 echo "✅ 构建完成"
-echo "   单文件输出目录：$output_dir_abs"
+echo "   单文件输出根目录：$out_root_abs"
 echo "   驱动总包：$bundle_zip_path"
 echo "   已构建：${built_assets[*]}"
 if [[ ${#skipped_drivers[@]} -gt 0 ]]; then

build-release.sh

@@ -1,16 +1,42 @@
 #!/bin/bash
 
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+cd "$SCRIPT_DIR"
+
 # 配置
 APP_NAME="GoNavi"
 DIST_DIR="dist"
 BUILD_BIN_DIR="build/bin"
 DEFAULT_BINARY_NAME="GoNavi" # 对应 wails.json 中的 outputfilename
+DEV_VERSION_FILE="version/dev-version.txt"
+DEFAULT_DEV_VERSION="0.0.1-test"
 
-# 提取版本号
-VERSION=$(grep '"version":' frontend/package.json | head -1 | awk -F: '{ print $2 }' | sed 's/[",]//g' | tr -d '[[:space:]]')
-if [ -z "$VERSION" ]; then
-    VERSION="0.0.0"
-fi
+resolve_build_version() {
+    if [ -n "${GONAVI_VERSION:-}" ]; then
+        printf '%s\n' "${GONAVI_VERSION}"
+        return
+    fi
+
+    if [ -f "$DEV_VERSION_FILE" ]; then
+        local dev_version
+        dev_version=$(head -n 1 "$DEV_VERSION_FILE" | tr -d '\r' | tr -d '[:space:]')
+        if [ -n "$dev_version" ]; then
+            printf '%s\n' "$dev_version"
+            return
+        fi
+    fi
+
+    local package_version
+    package_version=$(grep '"version":' frontend/package.json | head -1 | awk -F: '{ print $2 }' | sed 's/[",]//g' | tr -d '[:space:]')
+    if [ -n "$package_version" ]; then
+        printf '%s\n' "$package_version"
+        return
+    fi
+
+    printf '%s\n' "$DEFAULT_DEV_VERSION"
+}
+
+VERSION="$(resolve_build_version)"
 echo "ℹ️  检测到版本号: $VERSION"
 LDFLAGS="-s -w -X GoNavi-Wails/internal/app.AppVersion=$VERSION"
 
@@ -20,6 +46,13 @@ RED='\033[0;31m'
 YELLOW='\033[1;33m'
 NC='\033[0m'
 
+BUILD_FAILURES=()
+
+record_build_failure() {
+    local target="$1"
+    BUILD_FAILURES+=("$target")
+}
+
 get_file_size_bytes() {
     local target="$1"
     if [ ! -f "$target" ]; then
@@ -84,237 +117,110 @@ try_compress_binary_with_upx() {
     fi
 }
 
-MAC_VOLICON_PATH="build/darwin/icon.icns"
-if [ ! -f "$MAC_VOLICON_PATH" ]; then
-    MAC_VOLICON_PATH=""
-fi
+clear_macos_bundle_xattrs() {
+    local bundle_path="$1"
+    if [ -z "$bundle_path" ] || [ ! -e "$bundle_path" ]; then
+        return
+    fi
+    if command -v xattr >/dev/null 2>&1; then
+        xattr -cr "$bundle_path" >/dev/null 2>&1 || true
+    fi
+}
+
+package_macos_bundle_zip() {
+    local app_path="$1"
+    local archive_path="$2"
+    local archive_abs
+
+    if [ ! -d "$app_path" ]; then
+        echo -e "${RED}   ❌ 未找到 macOS 应用包：$app_path${NC}"
+        exit 1
+    fi
+
+    archive_abs="$(cd "$(dirname "$archive_path")" && pwd)/$(basename "$archive_path")"
+    rm -f "$archive_path"
+    if command -v ditto >/dev/null 2>&1; then
+        ditto -c -k --sequesterRsrc --keepParent "$app_path" "$archive_abs"
+    elif command -v zip >/dev/null 2>&1; then
+        (
+            cd "$(dirname "$app_path")" && \
+            zip -qry "$archive_abs" "$(basename "$app_path")"
+        )
+    else
+        echo -e "${RED}   ❌ 未找到 ditto/zip，无法打包 macOS 应用。${NC}"
+        exit 1
+    fi
+
+    if [ ! -f "$archive_abs" ]; then
+        echo -e "${RED}   ❌ macOS 应用归档失败：$archive_abs${NC}"
+        exit 1
+    fi
+}
+
+package_macos_release() {
+    local platform="$1"
+    local archive_suffix="$2"
+
+    echo -e "${GREEN}🍎 正在构建 macOS (${platform})...${NC}"
+    generate_driver_agent_revisions "darwin/${platform}"
+    wails build -trimpath -platform "darwin/${platform}" -clean -ldflags "$LDFLAGS"
+    if [ $? -ne 0 ]; then
+        echo -e "${RED}   ❌ macOS ${platform} 构建失败。${NC}"
+        record_build_failure "macOS ${platform}"
+        return
+    fi
+
+    local app_src="$BUILD_BIN_DIR/$DEFAULT_BINARY_NAME.app"
+    local app_dest_name="${APP_NAME}-${VERSION}-${archive_suffix}.app"
+    local zip_name="${APP_NAME}-${VERSION}-${archive_suffix}.zip"
+
+    mv "$app_src" "$DIST_DIR/$app_dest_name"
+
+    local app_bin_path
+    app_bin_path=$(find "$DIST_DIR/$app_dest_name/Contents/MacOS" -maxdepth 1 -type f -print -quit)
+    if [ -z "$app_bin_path" ] || [ ! -f "$app_bin_path" ]; then
+        echo -e "${RED}   ❌ 未找到 macOS ${platform} 主程序文件。${NC}"
+        exit 1
+    fi
+
+    echo -e "${YELLOW}   ⚠️  macOS ${platform} 改为无交互 ZIP 打包，不再生成 DMG。${NC}"
+    echo "   🔏 正在对 .app 进行 ad-hoc 签名 (${platform})..."
+    clear_macos_bundle_xattrs "$DIST_DIR/$app_dest_name"
+    codesign --force --deep --sign - "$DIST_DIR/$app_dest_name"
+
+    echo "   📦 正在打包 macOS 应用归档 (${platform})..."
+    package_macos_bundle_zip "$DIST_DIR/$app_dest_name" "$DIST_DIR/$zip_name"
+    rm -rf "$DIST_DIR/$app_dest_name"
+    echo "   ✅ 已生成 $zip_name"
+}
+
+generate_driver_agent_revisions() {
+    local platform="$1"
+    echo "   🧭 正在生成 driver-agent revision 指纹 (${platform})..."
+    ./tools/generate-driver-agent-revisions.sh --platform "$platform"
+}
 
 echo -e "${GREEN}🚀 开始构建 $APP_NAME $VERSION...${NC}"
 
 # 清理并创建输出目录
-rm -rf $DIST_DIR
-mkdir -p $DIST_DIR
+rm -rf "$DIST_DIR"
+mkdir -p "$DIST_DIR"
 
-# --- macOS ARM64 构建 ---
-echo -e "${GREEN}🍎 正在构建 macOS (arm64)...${NC}"
-wails build -platform darwin/arm64 -clean -ldflags "$LDFLAGS"
-if [ $? -eq 0 ]; then
-    APP_SRC="$BUILD_BIN_DIR/$DEFAULT_BINARY_NAME.app"
-    APP_DEST_NAME="${APP_NAME}-${VERSION}-mac-arm64.app"
-    DMG_NAME="${APP_NAME}-${VERSION}-mac-arm64.dmg"
-    
-    # 移动 .app 到 dist
-    mv "$APP_SRC" "$DIST_DIR/$APP_DEST_NAME"
-
-    APP_BIN_PATH=$(find "$DIST_DIR/$APP_DEST_NAME/Contents/MacOS" -maxdepth 1 -type f -print -quit)
-    if [ -n "$APP_BIN_PATH" ] && [ -f "$APP_BIN_PATH" ]; then
-        echo -e "${YELLOW}   ⚠️  macOS arm64 不再执行 UPX 压缩，保留原始主程序。${NC}"
-    else
-        echo -e "${RED}   ❌ 未找到 macOS arm64 主程序文件。${NC}"
-        exit 1
-    fi
-    
-	    # Ad-hoc 代码签名（无 Apple Developer 账号时防止 Gatekeeper 报已损坏）
-	    echo "   🔏 正在对 .app 进行 ad-hoc 签名 (arm64)..."
-	    codesign --force --deep --sign - "$DIST_DIR/$APP_DEST_NAME"
-
-	    # 创建 DMG
-	    if command -v create-dmg &> /dev/null; then
-	        echo "   📦 正在打包 DMG (arm64)..."
-	        # 移除已存在的 DMG (以防万一)
-	        rm -f "$DIST_DIR/$DMG_NAME"
-	        # create-dmg 的 source 需要是“包含 .app 的目录”，不能直接传 .app 路径。
-	        STAGE_DIR=$(mktemp -d "$DIST_DIR/.dmg-stage-${APP_NAME}-${VERSION}-arm64.XXXXXX")
-	        if [ -z "$STAGE_DIR" ] || [ ! -d "$STAGE_DIR" ]; then
-	            echo -e "${RED}   ❌ 创建 DMG 临时目录失败，跳过 DMG 打包。${NC}"
-	        else
-	            if command -v ditto &> /dev/null; then
-	                ditto "$DIST_DIR/$APP_DEST_NAME" "$STAGE_DIR/$APP_DEST_NAME"
-	            else
-	                cp -R "$DIST_DIR/$APP_DEST_NAME" "$STAGE_DIR/$APP_DEST_NAME"
-	            fi
-
-	        # --sandbox-safe 会跳过 Finder 的 AppleScript 排版，避免打包过程中弹出/打开挂载窗口（CI/本地静默打包更友好）。
-	        CREATE_DMG_ARGS=(--volname "${APP_NAME} ${VERSION}" --format UDZO --sandbox-safe)
-	        if [ -n "$MAC_VOLICON_PATH" ]; then
-	            CREATE_DMG_ARGS+=(--volicon "$MAC_VOLICON_PATH")
-        else
-            echo -e "${YELLOW}   ⚠️  未找到 macOS 卷图标 (build/darwin/icon.icns)，跳过 --volicon。${NC}"
-        fi
-
-	        create-dmg "${CREATE_DMG_ARGS[@]}" \
-	            --window-pos 200 120 \
-	            --window-size 800 400 \
-	            --icon-size 100 \
-	            --icon "$APP_DEST_NAME" 200 190 \
-	            --hide-extension "$APP_DEST_NAME" \
-	            --app-drop-link 600 185 \
-	            "$DIST_DIR/$DMG_NAME" \
-	            "$STAGE_DIR"
-
-	        CREATE_DMG_EXIT_CODE=$?
-	        rm -rf "$STAGE_DIR"
-	        
-	        if [ $CREATE_DMG_EXIT_CODE -ne 0 ]; then
-	            echo -e "${RED}   ❌ create-dmg 执行失败 (exit=$CREATE_DMG_EXIT_CODE)，保留 .app 以便排查。${NC}"
-	        else
-            # create-dmg 可能会在失败时遗留 rw.*.dmg 中间产物；不要直接当作最终产物使用
-            if [ ! -f "$DIST_DIR/$DMG_NAME" ]; then
-                RW_FILE=$(find "$DIST_DIR" -maxdepth 1 -name "rw.*.dmg" -print -quit)
-                if [ -n "$RW_FILE" ]; then
-                    echo -e "${YELLOW}   ⚠️  检测到 create-dmg 中间产物: $(basename "$RW_FILE")，正在转换为可分发 DMG...${NC}"
-                    hdiutil convert "$RW_FILE" -format UDZO -o "$DIST_DIR/$DMG_NAME" >/dev/null 2>&1
-                    rm -f "$RW_FILE"
-                fi
-            fi
-
-            # 防御性：即使生成了目标文件，也要确保不是 UDRW（UDRW 在 Finder 下可能表现为“已损坏/无法打开”）
-            if [ -f "$DIST_DIR/$DMG_NAME" ] && command -v hdiutil &> /dev/null; then
-                DMG_FORMAT=$(hdiutil imageinfo "$DIST_DIR/$DMG_NAME" 2>/dev/null | awk -F': ' '/^Format:/{print $2; exit}')
-                if [ "$DMG_FORMAT" = "UDRW" ]; then
-                    echo -e "${YELLOW}   ⚠️  检测到 UDRW（可写原始映像），正在转换为 UDZO...${NC}"
-                    TMP_UDZO="$DIST_DIR/.tmp.$DMG_NAME"
-                    rm -f "$TMP_UDZO"
-                    hdiutil convert "$DIST_DIR/$DMG_NAME" -format UDZO -o "$TMP_UDZO" >/dev/null 2>&1 && mv "$TMP_UDZO" "$DIST_DIR/$DMG_NAME"
-                fi
-            fi
-
-            if [ -f "$DIST_DIR/$DMG_NAME" ] && command -v hdiutil &> /dev/null; then
-                hdiutil verify "$DIST_DIR/$DMG_NAME" >/dev/null 2>&1
-                if [ $? -ne 0 ]; then
-                    echo -e "${RED}   ❌ DMG 校验失败，保留 .app 以便排查。${NC}"
-                else
-                    # 删除中间的 .app 文件，保持目录整洁
-                    rm -rf "$DIST_DIR/$APP_DEST_NAME"
-                    echo "   ✅ 已生成 $DMG_NAME"
-                fi
-            fi
-        fi
-
-	        if [ ! -f "$DIST_DIR/$DMG_NAME" ]; then
-	            echo -e "${RED}   ❌ DMG 生成失败，请检查 create-dmg 输出。${NC}"
-	        fi
-	        fi
-	    else
-	        echo -e "${YELLOW}   ⚠️  未找到 create-dmg 工具，跳过 DMG 打包，仅保留 .app。${NC}"
-	        echo "      安装命令: brew install create-dmg"
-	    fi
-	else
-    echo -e "${RED}   ❌ macOS arm64 构建失败。${NC}"
-fi
-
-# --- macOS AMD64 构建 ---
-echo -e "${GREEN}🍎 正在构建 macOS (amd64)...${NC}"
-wails build -platform darwin/amd64 -clean -ldflags "$LDFLAGS"
-if [ $? -eq 0 ]; then
-    APP_SRC="$BUILD_BIN_DIR/$DEFAULT_BINARY_NAME.app"
-    APP_DEST_NAME="${APP_NAME}-${VERSION}-mac-amd64.app"
-    DMG_NAME="${APP_NAME}-${VERSION}-mac-amd64.dmg"
-    
-    mv "$APP_SRC" "$DIST_DIR/$APP_DEST_NAME"
-
-    APP_BIN_PATH=$(find "$DIST_DIR/$APP_DEST_NAME/Contents/MacOS" -maxdepth 1 -type f -print -quit)
-    if [ -n "$APP_BIN_PATH" ] && [ -f "$APP_BIN_PATH" ]; then
-        echo -e "${YELLOW}   ⚠️  macOS amd64 不再执行 UPX 压缩，保留原始主程序。${NC}"
-    else
-        echo -e "${RED}   ❌ 未找到 macOS amd64 主程序文件。${NC}"
-        exit 1
-    fi
-    
-	    # Ad-hoc 代码签名
-	    echo "   🔏 正在对 .app 进行 ad-hoc 签名 (amd64)..."
-	    codesign --force --deep --sign - "$DIST_DIR/$APP_DEST_NAME"
-
-	    if command -v create-dmg &> /dev/null; then
-	        echo "   📦 正在打包 DMG (amd64)..."
-	        rm -f "$DIST_DIR/$DMG_NAME"
-	        # create-dmg 的 source 需要是“包含 .app 的目录”，不能直接传 .app 路径。
-	        STAGE_DIR=$(mktemp -d "$DIST_DIR/.dmg-stage-${APP_NAME}-${VERSION}-amd64.XXXXXX")
-	        if [ -z "$STAGE_DIR" ] || [ ! -d "$STAGE_DIR" ]; then
-	            echo -e "${RED}   ❌ 创建 DMG 临时目录失败，跳过 DMG 打包。${NC}"
-	        else
-	            if command -v ditto &> /dev/null; then
-	                ditto "$DIST_DIR/$APP_DEST_NAME" "$STAGE_DIR/$APP_DEST_NAME"
-	            else
-	                cp -R "$DIST_DIR/$APP_DEST_NAME" "$STAGE_DIR/$APP_DEST_NAME"
-	            fi
-
-	        # --sandbox-safe 会跳过 Finder 的 AppleScript 排版，避免打包过程中弹出/打开挂载窗口（CI/本地静默打包更友好）。
-	        CREATE_DMG_ARGS=(--volname "${APP_NAME} ${VERSION}" --format UDZO --sandbox-safe)
-	        if [ -n "$MAC_VOLICON_PATH" ]; then
-	            CREATE_DMG_ARGS+=(--volicon "$MAC_VOLICON_PATH")
-        else
-            echo -e "${YELLOW}   ⚠️  未找到 macOS 卷图标 (build/darwin/icon.icns)，跳过 --volicon。${NC}"
-        fi
-
-	        create-dmg "${CREATE_DMG_ARGS[@]}" \
-	            --window-pos 200 120 \
-	            --window-size 800 400 \
-	            --icon-size 100 \
-	            --icon "$APP_DEST_NAME" 200 190 \
-	            --hide-extension "$APP_DEST_NAME" \
-	            --app-drop-link 600 185 \
-	            "$DIST_DIR/$DMG_NAME" \
-	            "$STAGE_DIR"
-
-	        CREATE_DMG_EXIT_CODE=$?
-	        rm -rf "$STAGE_DIR"
-
-	        if [ $CREATE_DMG_EXIT_CODE -ne 0 ]; then
-	            echo -e "${RED}   ❌ create-dmg 执行失败 (exit=$CREATE_DMG_EXIT_CODE)，保留 .app 以便排查。${NC}"
-	        else
-            if [ ! -f "$DIST_DIR/$DMG_NAME" ]; then
-                RW_FILE=$(find "$DIST_DIR" -maxdepth 1 -name "rw.*.dmg" -print -quit)
-                if [ -n "$RW_FILE" ]; then
-                    echo -e "${YELLOW}   ⚠️  检测到 create-dmg 中间产物: $(basename "$RW_FILE")，正在转换为可分发 DMG...${NC}"
-                    hdiutil convert "$RW_FILE" -format UDZO -o "$DIST_DIR/$DMG_NAME" >/dev/null 2>&1
-                    rm -f "$RW_FILE"
-                fi
-            fi
-
-            if [ -f "$DIST_DIR/$DMG_NAME" ] && command -v hdiutil &> /dev/null; then
-                DMG_FORMAT=$(hdiutil imageinfo "$DIST_DIR/$DMG_NAME" 2>/dev/null | awk -F': ' '/^Format:/{print $2; exit}')
-                if [ "$DMG_FORMAT" = "UDRW" ]; then
-                    echo -e "${YELLOW}   ⚠️  检测到 UDRW（可写原始映像），正在转换为 UDZO...${NC}"
-                    TMP_UDZO="$DIST_DIR/.tmp.$DMG_NAME"
-                    rm -f "$TMP_UDZO"
-                    hdiutil convert "$DIST_DIR/$DMG_NAME" -format UDZO -o "$TMP_UDZO" >/dev/null 2>&1 && mv "$TMP_UDZO" "$DIST_DIR/$DMG_NAME"
-                fi
-            fi
-
-            if [ -f "$DIST_DIR/$DMG_NAME" ] && command -v hdiutil &> /dev/null; then
-                hdiutil verify "$DIST_DIR/$DMG_NAME" >/dev/null 2>&1
-                if [ $? -ne 0 ]; then
-                    echo -e "${RED}   ❌ DMG 校验失败，保留 .app 以便排查。${NC}"
-                else
-                    rm -rf "$DIST_DIR/$APP_DEST_NAME"
-                    echo "   ✅ 已生成 $DMG_NAME"
-                fi
-            fi
-        fi
-        
-	        if [ ! -f "$DIST_DIR/$DMG_NAME" ]; then
-	            echo -e "${RED}   ❌ DMG 生成失败。${NC}"
-	        fi
-	        fi
-	    else
-	        echo -e "${YELLOW}   ⚠️  未找到 create-dmg 工具。${NC}"
-	    fi
-	else
-	    echo -e "${RED}   ❌ macOS amd64 构建失败。${NC}"
-fi
+package_macos_release "arm64" "mac-arm64"
+package_macos_release "amd64" "mac-amd64"
 
 # --- Windows AMD64 构建 ---
 echo -e "${GREEN}🪟 正在构建 Windows (amd64)...${NC}"
 if command -v x86_64-w64-mingw32-gcc &> /dev/null; then
-    wails build -platform windows/amd64 -clean -ldflags "$LDFLAGS"
+    generate_driver_agent_revisions "windows/amd64"
+    wails build -trimpath -platform windows/amd64 -clean -ldflags "$LDFLAGS"
     if [ $? -eq 0 ]; then
         TARGET_EXE="$DIST_DIR/${APP_NAME}-${VERSION}-windows-amd64.exe"
         mv "$BUILD_BIN_DIR/${DEFAULT_BINARY_NAME}.exe" "$TARGET_EXE"
-        try_compress_binary_with_upx "$TARGET_EXE" "Windows amd64 可执行文件"
         echo "   ✅ 已生成 ${APP_NAME}-${VERSION}-windows-amd64.exe"
     else
         echo -e "${RED}   ❌ Windows amd64 构建失败。${NC}"
+        record_build_failure "Windows amd64"
     fi
 else
     echo -e "${YELLOW}   ⚠️  未找到 MinGW 工具 (x86_64-w64-mingw32-gcc)，跳过 Windows amd64 构建。${NC}"
@@ -323,14 +229,15 @@ fi
 # --- Windows ARM64 构建 ---
 echo -e "${GREEN}🪟 正在构建 Windows (arm64)...${NC}"
 if command -v aarch64-w64-mingw32-gcc &> /dev/null; then
-    wails build -platform windows/arm64 -clean -ldflags "$LDFLAGS"
+    generate_driver_agent_revisions "windows/arm64"
+    wails build -trimpath -platform windows/arm64 -clean -ldflags "$LDFLAGS"
     if [ $? -eq 0 ]; then
         TARGET_EXE="$DIST_DIR/${APP_NAME}-${VERSION}-windows-arm64.exe"
         mv "$BUILD_BIN_DIR/${DEFAULT_BINARY_NAME}.exe" "$TARGET_EXE"
-        echo -e "${YELLOW}   ⚠️  当前 UPX 不支持 win64/arm64，跳过 Windows arm64 压缩。${NC}"
         echo "   ✅ 已生成 ${APP_NAME}-${VERSION}-windows-arm64.exe"
     else
         echo -e "${RED}   ❌ Windows arm64 构建失败。${NC}"
+        record_build_failure "Windows arm64"
     fi
 else
     echo -e "${YELLOW}   ⚠️  未找到 MinGW ARM64 工具 (aarch64-w64-mingw32-gcc)，跳过 Windows arm64 构建。${NC}"
@@ -345,7 +252,8 @@ CURRENT_ARCH=$(uname -m)
 
 if [ "$CURRENT_OS" = "Linux" ] && [ "$CURRENT_ARCH" = "x86_64" ]; then
     # 本机 Linux amd64，直接构建
-    wails build -platform linux/amd64 -clean -ldflags "$LDFLAGS"
+    generate_driver_agent_revisions "linux/amd64"
+    wails build -trimpath -platform linux/amd64 -clean -ldflags "$LDFLAGS"
     if [ $? -eq 0 ]; then
         TARGET_LINUX_BIN="$DIST_DIR/${APP_NAME}-${VERSION}-linux-amd64"
         mv "$BUILD_BIN_DIR/${DEFAULT_BINARY_NAME}" "$TARGET_LINUX_BIN"
@@ -359,13 +267,15 @@ if [ "$CURRENT_OS" = "Linux" ] && [ "$CURRENT_ARCH" = "x86_64" ]; then
         echo "   ✅ 已生成 ${APP_NAME}-${VERSION}-linux-amd64.tar.gz"
     else
         echo -e "${RED}   ❌ Linux amd64 构建失败。${NC}"
+        record_build_failure "Linux amd64"
     fi
 elif command -v x86_64-linux-gnu-gcc &> /dev/null; then
     # macOS 或其他系统，尝试交叉编译
     export CC=x86_64-linux-gnu-gcc
     export CXX=x86_64-linux-gnu-g++
     export CGO_ENABLED=1
-    wails build -platform linux/amd64 -clean -ldflags "$LDFLAGS"
+    generate_driver_agent_revisions "linux/amd64"
+    wails build -trimpath -platform linux/amd64 -clean -ldflags "$LDFLAGS"
     if [ $? -eq 0 ]; then
         TARGET_LINUX_BIN="$DIST_DIR/${APP_NAME}-${VERSION}-linux-amd64"
         mv "$BUILD_BIN_DIR/${DEFAULT_BINARY_NAME}" "$TARGET_LINUX_BIN"
@@ -378,6 +288,7 @@ elif command -v x86_64-linux-gnu-gcc &> /dev/null; then
         echo "   ✅ 已生成 ${APP_NAME}-${VERSION}-linux-amd64.tar.gz"
     else
         echo -e "${RED}   ❌ Linux amd64 交叉编译失败。${NC}"
+        record_build_failure "Linux amd64"
     fi
     unset CC CXX CGO_ENABLED
 else
@@ -389,7 +300,8 @@ fi
 echo -e "${GREEN}🐧 正在构建 Linux (arm64)...${NC}"
 if [ "$CURRENT_OS" = "Linux" ] && [ "$CURRENT_ARCH" = "aarch64" ]; then
     # 本机 Linux arm64，直接构建
-    wails build -platform linux/arm64 -clean -ldflags "$LDFLAGS"
+    generate_driver_agent_revisions "linux/arm64"
+    wails build -trimpath -platform linux/arm64 -clean -ldflags "$LDFLAGS"
     if [ $? -eq 0 ]; then
         TARGET_LINUX_BIN="$DIST_DIR/${APP_NAME}-${VERSION}-linux-arm64"
         mv "$BUILD_BIN_DIR/${DEFAULT_BINARY_NAME}" "$TARGET_LINUX_BIN"
@@ -402,13 +314,15 @@ if [ "$CURRENT_OS" = "Linux" ] && [ "$CURRENT_ARCH" = "aarch64" ]; then
         echo "   ✅ 已生成 ${APP_NAME}-${VERSION}-linux-arm64.tar.gz"
     else
         echo -e "${RED}   ❌ Linux arm64 构建失败。${NC}"
+        record_build_failure "Linux arm64"
     fi
 elif command -v aarch64-linux-gnu-gcc &> /dev/null; then
     # 交叉编译
     export CC=aarch64-linux-gnu-gcc
     export CXX=aarch64-linux-gnu-g++
     export CGO_ENABLED=1
-    wails build -platform linux/arm64 -clean -ldflags "$LDFLAGS"
+    generate_driver_agent_revisions "linux/arm64"
+    wails build -trimpath -platform linux/arm64 -clean -ldflags "$LDFLAGS"
     if [ $? -eq 0 ]; then
         TARGET_LINUX_BIN="$DIST_DIR/${APP_NAME}-${VERSION}-linux-arm64"
         mv "$BUILD_BIN_DIR/${DEFAULT_BINARY_NAME}" "$TARGET_LINUX_BIN"
@@ -421,6 +335,7 @@ elif command -v aarch64-linux-gnu-gcc &> /dev/null; then
         echo "   ✅ 已生成 ${APP_NAME}-${VERSION}-linux-arm64.tar.gz"
     else
         echo -e "${RED}   ❌ Linux arm64 交叉编译失败。${NC}"
+        record_build_failure "Linux arm64"
     fi
     unset CC CXX CGO_ENABLED
 else
@@ -438,6 +353,9 @@ if command -v sha256sum &> /dev/null; then
     : > SHA256SUMS
     for f in *; do
         [ -f "$f" ] || continue
+        case "$f" in
+            SHA256SUMS|latest.json|latest-dev.json) continue ;;
+        esac
         sha256sum "$f" >> SHA256SUMS
     done
     cd ..
@@ -446,6 +364,9 @@ elif command -v shasum &> /dev/null; then
     : > SHA256SUMS
     for f in *; do
         [ -f "$f" ] || continue
+        case "$f" in
+            SHA256SUMS|latest.json|latest-dev.json) continue ;;
+        esac
         shasum -a 256 "$f" >> SHA256SUMS
     done
     cd ..
@@ -453,13 +374,51 @@ else
     echo -e "${YELLOW}   ⚠️  未找到 sha256sum/shasum，跳过校验文件生成。${NC}"
 fi
 
+echo -e "${GREEN}📄 生成静态更新清单...${NC}"
+if command -v python3 &> /dev/null; then
+    # 正式版：latest.json；dev/test 版本：latest-dev.json（对应客户端 dev 通道）
+    case "$VERSION" in
+        dev-*|*-dev*|*dev*|*test*)
+            TAG_FOR_MANIFEST="dev-latest"
+            CHANNEL_FOR_MANIFEST="dev"
+            OUT_MANIFEST="$DIST_DIR/latest-dev.json"
+            ;;
+        *)
+            TAG_FOR_MANIFEST="v${VERSION#v}"
+            CHANNEL_FOR_MANIFEST="latest"
+            OUT_MANIFEST="$DIST_DIR/latest.json"
+            ;;
+    esac
+    if python3 tools/generate-update-latest-manifest.py \
+        --assets-dir "$DIST_DIR" \
+        --version "$VERSION" \
+        --tag "$TAG_FOR_MANIFEST" \
+        --channel "$CHANNEL_FOR_MANIFEST" \
+        --output "$OUT_MANIFEST"; then
+        echo -e "${GREEN}   ✅ 已生成 $OUT_MANIFEST (channel=${CHANNEL_FOR_MANIFEST})${NC}"
+    else
+        echo -e "${YELLOW}   ⚠️  生成更新清单失败（不影响本地产物，正式/dev 发版由 CI 生成）${NC}"
+    fi
+else
+    echo -e "${YELLOW}   ⚠️  未找到 python3，跳过更新清单${NC}"
+fi
+
 echo ""
-echo -e "${GREEN}🎉 所有任务完成！构建产物在 'dist/' 目录下：${NC}"
+if [ "${#BUILD_FAILURES[@]}" -gt 0 ]; then
+    echo -e "${RED}❌ 构建未完全成功，失败平台：${BUILD_FAILURES[*]}${NC}"
+    echo -e "${YELLOW}📦 已成功生成的产物在 'dist/' 目录下：${NC}"
+else
+    echo -e "${GREEN}🎉 所有任务完成！构建产物在 'dist/' 目录下：${NC}"
+fi
 ls -lh "$DIST_DIR"
 echo ""
 echo -e "${GREEN}📋 支持的平台：${NC}"
-echo "   • macOS (Intel/Apple Silicon): .dmg"
+echo "   • macOS (Intel/Apple Silicon): .zip"
 echo "   • Windows (x64/ARM64): .exe"
 echo "   • Linux (x64/ARM64): .tar.gz"
 echo ""
 echo -e "${YELLOW}💡 提示：Linux AppImage 包请使用 GitHub Actions CI/CD 构建。${NC}"
+
+if [ "${#BUILD_FAILURES[@]}" -gt 0 ]; then
+    exit 1
+fi

build/windows/installer.wxs

@@ -0,0 +1,100 @@
+<Wix xmlns="http://wixtoolset.org/schemas/v4/wxs"
+     xmlns:ui="http://wixtoolset.org/schemas/v4/wxs/ui">
+  <Package Name="$(var.ProductName)"
+           Manufacturer="Syngnat"
+           Language="1033"
+           Version="$(var.ProductVersion)"
+           ProductCode="*"
+           UpgradeCode="$(var.UpgradeCode)"
+           Scope="perMachine"
+           InstallerVersion="500"
+           Compressed="yes">
+    <MajorUpgrade AllowDowngrades="yes"
+                  Schedule="afterInstallInitialize" />
+    <MediaTemplate EmbedCab="yes" CompressionLevel="high" />
+
+    <Icon Id="GoNaviIcon" SourceFile="$(var.IconPath)" />
+    <Property Id="ARPPRODUCTICON" Value="GoNaviIcon" />
+    <Property Id="ARPURLINFOABOUT" Value="https://github.com/Syngnat/GoNavi" />
+    <Property Id="INSTALLDESKTOPSHORTCUT" Value="1" Secure="yes" />
+    <SetProperty Id="ARPINSTALLLOCATION" Value="[INSTALLFOLDER]" After="CostFinalize" />
+    <WixVariable Id="WixUILicenseRtf" Value="$(var.LicenseRtf)" />
+
+    <Feature Id="MainFeature" Title="$(var.ProductName)" Level="1">
+      <ComponentRef Id="MainExecutable" />
+      <ComponentRef Id="DesktopShortcutComponent" />
+    </Feature>
+
+    <Component Id="MainExecutable"
+               Directory="INSTALLFOLDER"
+               Guid="$(var.ComponentGuid)"
+               Bitness="always64">
+      <File Id="GoNaviExe"
+            Source="$(var.SourceExe)"
+            Name="GoNavi.exe"
+            KeyPath="yes">
+        <!-- Keep shortcut icons bound to the stable executable path. Referencing the MSI Icon table
+             can leave Windows shell caches pointing at the removed product cache after a major upgrade. -->
+        <Shortcut Id="StartMenuShortcut"
+                  Directory="ProgramMenuFolder"
+                  Name="$(var.ProductName)"
+                  WorkingDirectory="INSTALLFOLDER"
+                  Advertise="no" />
+      </File>
+      <File Id="GoNaviMsiInstallMarker"
+            Source="$(var.InstallMarker)"
+            Name=".gonavi-msi-install" />
+      <File Id="GoNaviLicense"
+            Source="$(var.LicenseFile)"
+            Name="LICENSE.txt" />
+      <File Id="GoNaviNotice"
+            Source="$(var.NoticeFile)"
+            Name="NOTICE.txt" />
+      <RegistryValue Root="HKLM"
+                     Key="Software\Syngnat\$(var.RegistryKeyName)"
+                     Name="InstallType"
+                     Value="MSI"
+                     Type="string"
+                     KeyPath="no" />
+      <RegistryValue Root="HKLM"
+                     Key="Software\Syngnat\$(var.RegistryKeyName)"
+                     Name="InstallPath"
+                     Value="[INSTALLFOLDER]GoNavi.exe"
+                     Type="string"
+                     KeyPath="no" />
+    </Component>
+
+    <!-- Online updates pass the user's pre-update desktop shortcut state. Keeping this resource
+         in its own component lets a major upgrade remove an unwanted old shortcut without
+         recreating it, while first-time and manual installs retain the existing default. -->
+    <Component Id="DesktopShortcutComponent"
+               Directory="DesktopFolder"
+               Guid="$(var.DesktopShortcutComponentGuid)"
+               Bitness="always64"
+               Condition="INSTALLDESKTOPSHORTCUT = 1">
+      <Shortcut Id="DesktopShortcut"
+                Name="$(var.ProductName)"
+                Target="[#GoNaviExe]"
+                WorkingDirectory="INSTALLFOLDER"
+                Advertise="no" />
+      <RegistryValue Root="HKLM"
+                     Key="Software\Syngnat\$(var.RegistryKeyName)"
+                     Name="DesktopShortcutInstalled"
+                     Value="1"
+                     Type="integer"
+                     KeyPath="yes" />
+    </Component>
+
+    <ui:WixUI Id="WixUI_InstallDir"
+              InstallDirectory="INSTALLFOLDER"
+              ExtendedPathValidation="yes" />
+  </Package>
+
+  <Fragment>
+    <StandardDirectory Id="ProgramFiles6432Folder">
+      <Directory Id="INSTALLFOLDER" Name="$(var.InstallFolderName)" />
+    </StandardDirectory>
+    <StandardDirectory Id="ProgramMenuFolder" />
+    <StandardDirectory Id="DesktopFolder" />
+  </Fragment>
+</Wix>

cmd/gonavi-mcp-server/README.md

@@ -0,0 +1,381 @@
+# GoNavi MCP Server
+
+`gonavi-mcp-server` 会把 GoNavi 已保存连接背后的数据库能力通过 MCP 暴露给外部客户端。本机客户端默认使用 `stdio`；云端 Agent 可使用显式开启的 Streamable HTTP 模式。
+
+## 当前提供的 tools
+
+- `get_connections`
+  - 返回 GoNavi 已保存连接的 `id/name/type/target/defaultDatabase` 等摘要信息
+- `get_databases`
+  - 入参：`connectionId`
+- `get_tables`
+  - 入参：`connectionId`、可选 `dbName`
+  - 返回表列表，并在 `views` 字段附带视图列表，兼容旧客户端只调用 `get_tables` 的场景
+- `get_views`
+  - 入参：`connectionId`、可选 `dbName`
+  - 返回视图列表
+- `get_objects`
+  - 入参：`connectionId`、可选 `dbName`、可选 `objectTypes`
+  - 返回表、视图、触发器、函数、过程、序列、包、事件，以及消息队列类 `topic/queue/exchange` 等对象清单
+- `get_columns`
+  - 入参：`connectionId`、可选 `dbName`、`tableName`
+- `get_table_ddl`
+  - 入参：`connectionId`、可选 `dbName`、`tableName`
+- `execute_sql`
+  - 入参：`connectionId`、可选 `dbName`、`sql`
+  - 默认只允许只读 SQL
+  - 如果 SQL 包含 DDL/DML，必须显式传 `allowMutating=true`
+  - `maxRowsPerResult` 用来限制单个结果集返回的行数，默认 `200`
+
+远程 Agent 只需要结构元数据时，启动 HTTP 模式请加 `--schema-only`。该模式不注册 `execute_sql`，只保留连接摘要、对象清单、表/视图、字段、索引、外键、触发器和 DDL 工具。
+
+## 运行方式
+
+开发态直接运行：
+
+```powershell
+go run ./cmd/gonavi-mcp-server
+```
+
+显式运行本机 `stdio`：
+
+```powershell
+go run ./cmd/gonavi-mcp-server stdio
+```
+
+也可以先编译：
+
+```powershell
+go build -o .\bin\gonavi-mcp-server.exe .\cmd\gonavi-mcp-server
+```
+
+## Docker / Podman / Compose
+
+当前容器化支持仅覆盖 `gonavi-mcp-server`，不包含 Wails 桌面 GUI。
+
+当前支持矩阵：
+
+- Docker Desktop / Linux 服务器 / NAS：直接使用 Compose 或 `docker run`
+- Podman / Quadlet：使用 `deploy/podman/gonavi-mcp-server`
+- Kubernetes：使用 `deploy/k8s/gonavi-mcp-server`
+- Helm：使用 `deploy/helm/gonavi-mcp-server`
+- 仅构建环境：使用仓库根目录 `Dockerfile.build-env`
+- 桌面 GUI 浏览器访问版：当前不提供，此仓库主应用仍是 Wails 桌面程序，不是现成的 Web 服务
+
+仓库根目录已提供以下文件：
+
+- `Dockerfile.mcp-server`
+- `docker-compose.mcp-server.yml`
+- `docker.mcp-server.env.example`
+- `deploy/podman/gonavi-mcp-server/*`
+
+推荐流程：
+
+```bash
+cp docker.mcp-server.env.example docker.mcp-server.env
+docker compose --env-file docker.mcp-server.env -f docker-compose.mcp-server.yml up -d
+```
+
+默认 Compose 会拉取 GHCR 预构建镜像。如果你要基于当前工作区源码本地构建，再叠加：
+
+```bash
+docker compose --env-file docker.mcp-server.env \
+  -f docker-compose.mcp-server.yml \
+  -f docker-compose.mcp-server.local.yml \
+  up -d --build
+```
+
+其中 `GONAVI_HOST_DATA_ROOT` 必须指向 GoNavi 当前活动数据目录。该目录内至少应包含：
+
+- `connections.json`
+- `daily_secrets.json`
+- `drivers/`（如果目标连接依赖可选 driver agent）
+
+容器内默认会设置：
+
+- `GONAVI_DATA_ROOT=/data`
+- `GONAVI_MCP_HTTP_ADDR=0.0.0.0:8765`
+- `GONAVI_MCP_HTTP_PATH=/mcp`
+
+`GONAVI_DATA_ROOT` 会覆盖默认活动数据目录解析逻辑，避免宿主机路径与容器内路径不一致时依赖 `storage_root.json` 的绝对路径。
+
+如果你只想手动构建镜像：
+
+```bash
+docker build -f Dockerfile.mcp-server -t gonavi-mcp-server:local .
+docker run --rm -p 8765:8765 \
+  -e GONAVI_MCP_HTTP_TOKEN=replace-with-a-random-token \
+  -e GONAVI_MCP_SCHEMA_ONLY=true \
+  -e GONAVI_DATA_ROOT=/data \
+  -v /absolute/path/to/gonavi-data:/data \
+  gonavi-mcp-server:local http
+```
+
+如果你直接使用已发布镜像：
+
+```bash
+docker run --rm -p 8765:8765 \
+  -e GONAVI_MCP_HTTP_TOKEN=replace-with-a-random-token \
+  -e GONAVI_MCP_SCHEMA_ONLY=true \
+  -e GONAVI_DATA_ROOT=/data \
+  -v /absolute/path/to/gonavi-data:/data \
+  ghcr.io/syngnat/gonavi-mcp-server:latest http
+```
+
+### Podman
+
+仓库内还提供了 Podman 原生部署样例：
+
+- `deploy/podman/gonavi-mcp-server/gonavi-mcp-server.env.example`
+- `deploy/podman/gonavi-mcp-server/gonavi-mcp-server.container`
+- `deploy/podman/gonavi-mcp-server/README.md`
+
+直接运行已发布镜像：
+
+```bash
+cp deploy/podman/gonavi-mcp-server/gonavi-mcp-server.env.example ./gonavi-mcp-server.env
+podman run -d --name gonavi-mcp-server --replace \
+  -p 8765:8765 \
+  --env-file ./gonavi-mcp-server.env \
+  -v /absolute/path/to/gonavi-data:/data:Z \
+  ghcr.io/syngnat/gonavi-mcp-server:latest http
+```
+
+如果你要基于当前源码本地构建：
+
+```bash
+podman build -f Dockerfile.mcp-server -t localhost/gonavi-mcp-server:local .
+podman run -d --name gonavi-mcp-server --replace \
+  -p 8765:8765 \
+  --env-file ./gonavi-mcp-server.env \
+  -v /absolute/path/to/gonavi-data:/data:Z \
+  localhost/gonavi-mcp-server:local http
+```
+
+其中：
+
+- `gonavi-mcp-server.env` 用 `deploy/podman/gonavi-mcp-server/gonavi-mcp-server.env.example` 初始化
+- `:Z` 适用于开启 SELinux 的宿主机；未启用 SELinux 可去掉
+- 更适合长期运行的方式见 [deploy/podman/gonavi-mcp-server/README.md](../../deploy/podman/gonavi-mcp-server/README.md) 中的 Quadlet 示例
+
+`podman compose` 本身依赖外部 compose provider，所以仓库对 Podman 的主支持路径是 `podman run` 与 Quadlet，而不是假设所有环境都能直接复用 Compose。
+
+## Kubernetes
+
+仓库内置了最小 K8s 示例：
+
+- `deploy/k8s/gonavi-mcp-server/kustomization.yaml`
+- `deploy/k8s/gonavi-mcp-server/base/deployment.yaml`
+- `deploy/k8s/gonavi-mcp-server/base/service.yaml`
+- `deploy/k8s/gonavi-mcp-server/README.md`
+- `deploy/k8s/gonavi-mcp-server/overlays/*`
+
+推荐先从现有 GoNavi 数据目录生成 Secret：
+
+```bash
+kubectl create namespace gonavi
+kubectl -n gonavi create secret generic gonavi-mcp-server-data \
+  --from-file=connections.json=/absolute/path/to/gonavi-data/connections.json \
+  --from-file=daily_secrets.json=/absolute/path/to/gonavi-data/daily_secrets.json \
+  --from-literal=GONAVI_MCP_HTTP_TOKEN=replace-with-a-random-token
+kubectl apply -k deploy/k8s/gonavi-mcp-server
+```
+
+如果需要 NAS hostPath、可选 driver agent PVC、Ingress，或两者组合，可直接使用 `overlays/nas-hostpath`、`overlays/drivers-pvc`、`overlays/ingress`、`overlays/ingress-with-drivers-pvc`。
+
+更完整的说明见 [deploy/k8s/gonavi-mcp-server/README.md](../../deploy/k8s/gonavi-mcp-server/README.md)。
+
+## Helm
+
+如果你希望把镜像、Secret、Ingress、hostPath / PVC 挂载做成参数化部署，而不是维护多份 Kustomize overlay，可直接使用：
+
+- `deploy/helm/gonavi-mcp-server`
+
+快速安装：
+
+```bash
+helm upgrade --install gonavi-mcp-server deploy/helm/gonavi-mcp-server -n gonavi --create-namespace
+```
+
+Chart 详细说明见 [deploy/helm/gonavi-mcp-server/README.md](../../deploy/helm/gonavi-mcp-server/README.md)。
+
+## Docker / Podman Build Environment
+
+如果你的目标不是运行 MCP，而是给 Linux 服务器 / NAS / CI 准备一套可重复的 Wails 构建环境，可直接使用仓库根目录的 `Dockerfile.build-env`：
+
+```bash
+docker build -f Dockerfile.build-env -t gonavi-build-env:local .
+docker run --rm -it -v "$PWD:/workspace" -w /workspace gonavi-build-env:local bash
+```
+
+如果你使用 Podman，也可以直接执行：
+
+```bash
+podman build -f Dockerfile.build-env -t localhost/gonavi-build-env:local .
+podman run --rm -it -v "$PWD:/workspace" -w /workspace localhost/gonavi-build-env:local bash
+```
+
+镜像内已预装 Go、Node、Wails CLI、GTK3 与 WebKitGTK 开发依赖，适合执行：
+
+```bash
+wails build
+```
+
+这个镜像默认安装 WebKitGTK 4.0 构建依赖，适合作为通用 Linux / NAS 构建环境。镜像基座支持多架构，`amd64` / `arm64` 会跟随容器平台。
+
+预构建镜像会发布到 GHCR：
+
+- `ghcr.io/syngnat/gonavi-mcp-server:latest`
+- `ghcr.io/syngnat/gonavi-build-env:latest`
+
+它只负责构建 Linux 产物，不会把 Wails 主程序变成浏览器版服务。
+
+远程 Agent 使用 Streamable HTTP 时必须设置 bearer token：
+
+```powershell
+$env:GONAVI_MCP_HTTP_TOKEN = "<随机token>"
+go run ./cmd/gonavi-mcp-server http --addr 127.0.0.1:8765 --path /mcp --schema-only
+```
+
+安装包主程序也支持同样模式：
+
+```powershell
+& "C:\Program Files\GoNavi\GoNavi.exe" mcp-server http --addr 127.0.0.1:8765 --path /mcp --token "<随机token>" --schema-only
+```
+
+默认建议只监听 `127.0.0.1`，再通过 SSH 隧道、反向代理或内网网关暴露给云端 Agent。不要在没有 TLS、防火墙和鉴权的情况下直接监听公网地址。
+
+无图形界面或需要把配置交给云端 Agent 时，可直接生成 OpenClaw / Hermans 等远程 MCP 配置：
+
+```powershell
+& "C:\Program Files\GoNavi\GoNavi.exe" mcp-server remote-config --client openclaw --url "https://<你的域名或隧道地址>/mcp" --token "<随机token>" --schema-only
+```
+
+独立 server 开发态也支持同样能力：
+
+```powershell
+go run ./cmd/gonavi-mcp-server remote-config --client hermans --url "https://<你的域名或隧道地址>/mcp" --token "<随机token>" --schema-only
+```
+
+## Claude Code / Codex / OpenClaw / Hermans
+
+正式安装包场景，推荐直接在 GoNavi 里使用“AI 设置 -> MCP 服务 -> 安装到 Claude Code / 安装到 Codex”。
+
+它会自动把当前安装的 `GoNavi.exe` 写入 Claude Code 的用户级 `~/.claude.json`，命令形态类似：
+
+```json
+{
+  "mcpServers": {
+    "gonavi": {
+      "type": "stdio",
+      "command": "C:\\Program Files\\GoNavi\\GoNavi.exe",
+      "args": ["mcp-server"],
+      "env": {}
+    }
+  }
+}
+```
+
+这样用户不需要自己找本机 `gonavi-mcp-server.exe` 路径，安装包本体就能直接作为 MCP 入口。
+
+Codex 当前使用 `~/.codex/config.toml`，GoNavi 会写入类似下面这段：
+
+```toml
+[mcp_servers.gonavi]
+command = 'C:\Program Files\GoNavi\GoNavi.exe'
+args = ['mcp-server']
+startup_timeout_sec = 60
+```
+
+仓库开发态如果要在本机 `Claude Code CLI` 里稳定使用这个 MCP，仍然推荐走仓库内包装脚本：
+
+```powershell
+.\tools\claude-gonavi-mcp.ps1 -p "必须调用 gonavi MCP 的 get_connections 工具"
+```
+
+或者：
+
+```cmd
+tools\claude-gonavi-mcp.cmd -p "必须调用 gonavi MCP 的 get_connections 工具"
+```
+
+这个脚本会先构建 `bin\gonavi-mcp-server.exe`，再通过 `--mcp-config` 和 `--strict-mcp-config` 把 GoNavi MCP 单独注入当前 Claude 会话，避免默认混合 MCP 加载时序导致的首轮工具未挂载问题。
+
+OpenClaw、Hermans 这类部署在云端或远端 Linux 的 Agent，不能直接使用 Windows 本机的 `stdio` 命令。GoNavi 的连接信息和数据库密码仍应留在 Windows 本机，由 GoNavi MCP 读取保存连接和系统凭据；远端 Agent 只拿到 MCP tools 和 `connectionId`。
+
+推荐接入形态：
+
+1. Windows 本机运行 GoNavi，并保持能访问已保存的数据库连接。
+2. 在 Windows 本机启动 `GoNavi.exe mcp-server http --addr 127.0.0.1:8765 --path /mcp --token <随机token> --schema-only`。
+3. 通过 SSH 隧道、反向代理或内网网关把 `http://127.0.0.1:8765/mcp` 暴露为云端 Agent 可访问的 HTTPS 地址。
+4. 在 OpenClaw / Hermans 中添加远程 MCP Server，transport 选择 Streamable HTTP，URL 指向 `/mcp` 地址，并设置请求头 `Authorization: Bearer <随机token>`。
+5. 先调用 `get_connections` 获取 `connectionId`，再调用 `get_databases`、`get_objects`、`get_tables`、`get_views`、`get_columns`、`get_table_ddl` 等工具读取结构。
+
+如果目标 Agent 支持 `mcpServers` JSON，可按下面的通用片段配置：
+
+```json
+{
+  "mcpServers": {
+    "gonavi": {
+      "type": "streamable-http",
+      "url": "https://<你的域名或隧道地址>/mcp",
+      "headers": {
+        "Authorization": "Bearer <随机token>"
+      }
+    }
+  }
+}
+```
+
+不要把数据库 `host/user/password` 写入云端 Agent 的配置文件。默认 `--schema-only` 不暴露 `execute_sql`；如果你明确需要远程执行 SQL，可以去掉该参数，此时 `execute_sql` 仍受 GoNavi AI 安全设置控制，写操作必须显式传 `allowMutating=true`。
+
+## MCP 客户端配置示例
+
+开发态：
+
+```json
+{
+  "mcpServers": {
+    "gonavi": {
+      "command": "go",
+      "args": ["run", "./cmd/gonavi-mcp-server"]
+    }
+  }
+}
+```
+
+Windows 独立 server 编译产物（开发态）：
+
+```json
+{
+  "mcpServers": {
+    "gonavi": {
+      "command": "D:\\Work\\CodeRepos\\GoNavi\\bin\\gonavi-mcp-server.exe",
+      "args": []
+    }
+  }
+}
+```
+
+Windows 已安装 GoNavi（推荐给最终用户）：
+
+```json
+{
+  "mcpServers": {
+    "gonavi": {
+      "type": "stdio",
+      "command": "C:\\Program Files\\GoNavi\\GoNavi.exe",
+      "args": ["mcp-server"],
+      "env": {}
+    }
+  }
+}
+```
+
+## 使用说明
+
+- 先调用 `get_connections`，拿到 `connectionId`
+- 之后所有数据库工具都只传 `connectionId`，由 GoNavi 服务端内部解析保存连接和密钥
+- 如果 `dbName` 为空，会优先使用该保存连接里的默认数据库
+- Server 会读取 GoNavi 当前活动数据目录里的连接配置，并通过系统 keyring/凭据管理器解析密文
+- 如果本机凭据存储不可用，依赖密钥的连接会返回对应错误

cmd/gonavi-mcp-server/main.go

@@ -0,0 +1,42 @@
+package main
+
+import (
+	"context"
+	"fmt"
+	"log"
+	"os"
+	"strings"
+
+	"GoNavi-Wails/internal/mcpserver"
+)
+
+func main() {
+	ctx := context.Background()
+	err := run(ctx, os.Args[1:])
+	if err != nil {
+		log.Printf("GoNavi MCP Server 退出: %v", err)
+	}
+}
+
+func run(ctx context.Context, args []string) error {
+	if len(args) == 0 {
+		return mcpserver.RunAppStdioServer(ctx)
+	}
+
+	mode := strings.ToLower(strings.TrimSpace(args[0]))
+	switch mode {
+	case "stdio", "--stdio":
+		return mcpserver.RunAppStdioServer(ctx)
+	case "http", "--http", "streamable-http", "--streamable-http":
+		options, err := mcpserver.ParseHTTPServerOptions(args[1:])
+		if err != nil {
+			return err
+		}
+		log.Printf("GoNavi MCP Streamable HTTP Server 启动：addr=%s path=%s schemaOnly=%v", options.Addr, options.Path, options.SchemaOnly)
+		return mcpserver.RunAppStreamableHTTPServer(ctx, options)
+	case "remote-config", "--remote-config":
+		return mcpserver.WriteRemoteMCPClientConfig(os.Stdout, args[1:])
+	default:
+		return fmt.Errorf("未知 MCP server 模式: %s（支持 stdio/http/remote-config）", args[0])
+	}
+}

cmd/mingw-import-lib/main.go

@@ -0,0 +1,27 @@
+package main
+
+import (
+	"flag"
+	"fmt"
+	"os"
+
+	"GoNavi-Wails/internal/buildutil"
+)
+
+func main() {
+	var (
+		dllPath     string
+		dlltoolPath string
+		outputLib   string
+	)
+
+	flag.StringVar(&dllPath, "dll", "", "Path to the source DLL")
+	flag.StringVar(&dlltoolPath, "dlltool", "", "Optional path to dlltool executable")
+	flag.StringVar(&outputLib, "output-lib", "", "Output import library path")
+	flag.Parse()
+
+	if err := buildutil.GenerateWindowsImportLibraryFromDLL(dllPath, dlltoolPath, outputLib); err != nil {
+		fmt.Fprintf(os.Stderr, "generate mingw import library failed: %v\n", err)
+		os.Exit(1)
+	}
+}

cmd/optional-driver-agent/main.go

@@ -7,7 +7,11 @@ import (
 	"fmt"
 	"os"
 	"reflect"
+	"runtime"
+	"runtime/debug"
+	"strconv"
 	"strings"
+	"sync/atomic"
 	"time"
 
 	"GoNavi-Wails/internal/connection"
@@ -17,6 +21,7 @@ import (
 type agentRequest struct {
 	ID        int64                        `json:"id"`
 	Method    string                       `json:"method"`
+	SessionID string                       `json:"sessionId,omitempty"`
 	Config    *connection.ConnectionConfig `json:"config,omitempty"`
 	Query     string                       `json:"query,omitempty"`
 	TimeoutMs int64                        `json:"timeoutMs,omitempty"`
@@ -31,45 +36,99 @@ type agentResponse struct {
 	Error        string      `json:"error,omitempty"`
 	Data         interface{} `json:"data,omitempty"`
 	Fields       []string    `json:"fields,omitempty"`
+	Messages     []string    `json:"messages,omitempty"`
+	ChunkType    string      `json:"chunkType,omitempty"`
 	RowsAffected int64       `json:"rowsAffected,omitempty"`
 }
 
 const (
-	agentMethodConnect       = "connect"
-	agentMethodClose         = "close"
-	agentMethodPing          = "ping"
-	agentMethodQuery         = "query"
-	agentMethodExec          = "exec"
-	agentMethodGetDatabases  = "getDatabases"
-	agentMethodGetTables     = "getTables"
-	agentMethodGetCreateStmt = "getCreateStatement"
-	agentMethodGetColumns    = "getColumns"
-	agentMethodGetAllColumns = "getAllColumns"
-	agentMethodGetIndexes    = "getIndexes"
-	agentMethodGetForeignKey = "getForeignKeys"
-	agentMethodGetTriggers   = "getTriggers"
-	agentMethodApplyChanges  = "applyChanges"
+	agentMethodConnect             = "connect"
+	agentMethodClose               = "close"
+	agentMethodMetadata            = "metadata"
+	agentMethodPing                = "ping"
+	agentMethodOpenSession         = "openSession"
+	agentMethodCloseSession        = "closeSession"
+	agentMethodOpenTransaction     = "openTransaction"
+	agentMethodCommitTransaction   = "commitTransaction"
+	agentMethodRollbackTransaction = "rollbackTransaction"
+	agentMethodQuery               = "query"
+	agentMethodQueryMulti          = "queryMulti"
+	agentMethodStreamQuery         = "streamQuery"
+	agentMethodExec                = "exec"
+	agentMethodGetDatabases        = "getDatabases"
+	agentMethodGetTables           = "getTables"
+	agentMethodGetCreateStmt       = "getCreateStatement"
+	agentMethodGetColumns          = "getColumns"
+	agentMethodGetAllColumns       = "getAllColumns"
+	agentMethodGetIndexes          = "getIndexes"
+	agentMethodGetForeignKey       = "getForeignKeys"
+	agentMethodGetTriggers         = "getTriggers"
+	agentMethodApplyChanges        = "applyChanges"
 )
 
 const legacyClickHouseDefaultTimeout = 2 * time.Hour
 
-var (
-	agentDriverType      string
-	agentDatabaseFactory func() db.Database
+const (
+	agentChunkColumns = "columns"
+	agentChunkRows    = "rows"
+	agentChunkDone    = "done"
+	// agentStreamBatchSize 控制 driver-agent 向主进程发送 row chunk 的批次大小。
+	// 调小到 64：单批 JSON 编码 + 主进程解码的瞬时内存峰值降为原来的 1/4，
+	// 代价是 IPC 次数变为 4 倍，但每批仅一次 stdin/stdout 行读写，整体影响可忽略。
+	// 重要：减小批次不能根除内存峰值，仍需配合 SetGCPercent + 周期 GC（见 main）。
+	agentStreamBatchSize         = 64
+	agentMemoryTrimRowsThreshold = 100000
+	agentMemoryTrimMinInterval   = 3 * time.Second
 )
 
+var (
+	agentDriverType         string
+	agentDatabaseFactory    func() db.Database
+	agentMemoryTrimRunning  atomic.Bool
+	agentMemoryTrimLastAt   atomic.Int64
+	runAgentMemoryTrimAsync = func(fn func()) {
+		go fn()
+	}
+	agentMemoryTrimFn = func() {
+		runtime.GC()
+		debug.FreeOSMemory()
+	}
+)
+
+type agentRuntime struct {
+	inst          db.Database
+	sessions      map[string]db.StatementExecer
+	nextSessionID int64
+}
+
 func main() {
 	if agentDatabaseFactory == nil || strings.TrimSpace(agentDriverType) == "" {
 		fmt.Fprintf(os.Stderr, "未配置驱动代理 provider，请使用 gonavi_<driver>_driver 标签构建\n")
 		os.Exit(2)
 	}
 
+	// driver-agent 是独立进程，主进程无法控制其 GC 行为。
+	// 大结果集（88W+ 行）通过 JSON-lines 跨进程传输时，每行有 5-8 倍内存副本；
+	// Go 默认 GOGC=100 + Windows MADV_FREE 不归还 RSS，会导致 driver-agent 进程
+	// 内存峰值达到数据总量的 10+ 倍（用户实测 88W 普通业务表撑到 8G+）。
+	//
+	// GC 策略组合：
+	//   - SetGCPercent(50)：堆增长 50% 即触发 GC，比默认 100 更早收敛
+	//   - InitMemorySoftLimit：起始 2GB，运行时由 MaybeGrowMemoryLimit 自适应抬升到最多 8GB
+	//     （起步保守 + 按需扩张，避免静态 2GB 限制在大表场景触发 GC 硬模式降速 15-25%）
+	//
+	// 代价：CPU 开销增加约 5-10%。导出场景是 I/O 密集型，可忽略。
+	debug.SetGCPercent(50)
+	db.InitMemorySoftLimit(db.MemorySoftLimitInitialBytes)
+
 	scanner := bufio.NewScanner(os.Stdin)
 	scanner.Buffer(make([]byte, 0, 16<<10), 8<<20)
 	writer := bufio.NewWriter(os.Stdout)
 	defer writer.Flush()
 
-	var inst db.Database
+	runtimeState := &agentRuntime{
+		sessions: make(map[string]db.StatementExecer),
+	}
 	for scanner.Scan() {
 		line := strings.TrimSpace(scanner.Text())
 		if line == "" {
@@ -86,23 +145,32 @@ func main() {
 			continue
 		}
 
-		resp := handleRequest(&inst, req)
+		if strings.TrimSpace(req.Method) == agentMethodStreamQuery {
+			if err := handleStreamRequest(runtimeState, req, writer); err != nil {
+				fmt.Fprintf(os.Stderr, "写入流式响应失败：%v\n", err)
+				break
+			}
+			continue
+		}
+
+		resp := handleRequest(runtimeState, req)
 		if err := writeResponse(writer, resp); err != nil {
 			fmt.Fprintf(os.Stderr, "写入响应失败：%v\n", err)
 			break
 		}
+		if strings.TrimSpace(req.Method) == agentMethodQuery {
+			maybeReleaseAgentMemory("query-response", countAgentResponseRows(resp.Data))
+		}
 	}
 
-	if inst != nil {
-		_ = inst.Close()
-	}
+	runtimeState.close()
 
 	if err := scanner.Err(); err != nil {
 		fmt.Fprintf(os.Stderr, "读取请求失败：%v\n", err)
 	}
 }
 
-func handleRequest(inst *db.Database, req agentRequest) agentResponse {
+func handleRequest(runtimeState *agentRuntime, req agentRequest) agentResponse {
 	resp := agentResponse{ID: req.ID, Success: true}
 	method := strings.TrimSpace(req.Method)
 
@@ -111,9 +179,7 @@ func handleRequest(inst *db.Database, req agentRequest) agentResponse {
 		if req.Config == nil {
 			return fail(resp, "连接配置为空")
 		}
-		if *inst != nil {
-			_ = (*inst).Close()
-		}
+		runtimeState.close()
 		next := agentDatabaseFactory()
 		if next == nil {
 			return fail(resp, "驱动代理初始化失败")
@@ -121,84 +187,193 @@ func handleRequest(inst *db.Database, req agentRequest) agentResponse {
 		if err := next.Connect(*req.Config); err != nil {
 			return fail(resp, err.Error())
 		}
-		*inst = next
+		runtimeState.inst = next
 		return resp
 	case agentMethodClose:
-		if *inst != nil {
-			if err := (*inst).Close(); err != nil {
+		if runtimeState.inst != nil {
+			if err := runtimeState.close(); err != nil {
 				return fail(resp, err.Error())
 			}
-			*inst = nil
+		}
+		return resp
+	case agentMethodMetadata:
+		resp.Data = map[string]string{
+			"driverType":     strings.TrimSpace(agentDriverType),
+			"agentRevision":  db.OptionalDriverAgentRevision(agentDriverType),
+			"protocolSchema": "json-lines-v1",
+		}
+		return resp
+	case agentMethodOpenSession:
+		if runtimeState.inst == nil {
+			return fail(resp, "connection not open")
+		}
+		provider, ok := runtimeState.inst.(db.SessionExecerProvider)
+		if !ok {
+			return fail(resp, fmt.Sprintf("当前数据源（%s）不支持 SQL 编辑器托管事务", strings.TrimSpace(agentDriverType)))
+		}
+		openCtx := context.Background()
+		var cancel context.CancelFunc
+		if req.TimeoutMs > 0 {
+			openCtx, cancel = context.WithTimeout(context.Background(), time.Duration(req.TimeoutMs)*time.Millisecond)
+			defer cancel()
+		}
+		session, err := provider.OpenSessionExecer(openCtx)
+		if err != nil {
+			return fail(resp, err.Error())
+		}
+		sessionID := runtimeState.nextID()
+		runtimeState.sessions[sessionID] = session
+		resp.Data = sessionID
+		return resp
+	case agentMethodOpenTransaction:
+		if runtimeState.inst == nil {
+			return fail(resp, "connection not open")
+		}
+		provider, ok := runtimeState.inst.(db.TransactionExecerProvider)
+		if !ok {
+			return fail(resp, fmt.Sprintf("当前数据源（%s）不支持 SQL 编辑器托管事务", strings.TrimSpace(agentDriverType)))
+		}
+		// The transaction must outlive this request and be finished by a later RPC.
+		transaction, err := provider.OpenTransactionExecer(context.Background())
+		if err != nil {
+			return fail(resp, err.Error())
+		}
+		sessionID := runtimeState.nextID()
+		runtimeState.sessions[sessionID] = transaction
+		resp.Data = sessionID
+		return resp
+	case agentMethodCloseSession:
+		if err := runtimeState.closeSession(req.SessionID); err != nil {
+			return fail(resp, err.Error())
 		}
 		return resp
 	}
 
-	if *inst == nil {
+	if runtimeState.inst == nil {
 		return fail(resp, "connection not open")
 	}
 
+	if session, ok, err := runtimeState.session(req.SessionID); err != nil {
+		return fail(resp, err.Error())
+	} else if ok {
+		switch method {
+		case agentMethodQuery:
+			data, fields, messages, err := queryStatementWithMessagesOptionalTimeout(session, req.Query, req.TimeoutMs)
+			if err != nil {
+				return fail(resp, err.Error())
+			}
+			resp.Data = data
+			resp.Fields = fields
+			resp.Messages = messages
+		case agentMethodQueryMulti:
+			data, messages, supported, err := queryMultiStatementWithMessagesOptionalTimeout(session, req.Query, req.TimeoutMs)
+			if err != nil {
+				return fail(resp, err.Error())
+			}
+			if !supported {
+				return fail(resp, "当前事务会话不支持多结果集查询")
+			}
+			resp.Data = data
+			resp.Messages = messages
+		case agentMethodExec:
+			affected, err := execStatementWithOptionalTimeout(session, req.Query, req.TimeoutMs)
+			if err != nil {
+				return fail(resp, err.Error())
+			}
+			resp.RowsAffected = affected
+		case agentMethodCommitTransaction, agentMethodRollbackTransaction:
+			transaction, ok := session.(db.TransactionExecer)
+			if !ok {
+				return fail(resp, "当前会话不是托管事务")
+			}
+			var err error
+			if method == agentMethodCommitTransaction {
+				err = transaction.Commit()
+			} else {
+				err = transaction.Rollback()
+			}
+			if err != nil {
+				return fail(resp, err.Error())
+			}
+		default:
+			return fail(resp, "当前事务会话不支持该方法")
+		}
+		return resp
+	}
+
 	switch method {
 	case agentMethodPing:
-		if err := (*inst).Ping(); err != nil {
+		if err := runtimeState.inst.Ping(); err != nil {
 			return fail(resp, err.Error())
 		}
 	case agentMethodQuery:
-		data, fields, err := queryWithOptionalTimeout(*inst, req.Query, req.TimeoutMs)
+		data, fields, messages, err := queryWithMessagesOptionalTimeout(runtimeState.inst, req.Query, req.TimeoutMs)
 		if err != nil {
 			return fail(resp, err.Error())
 		}
 		resp.Data = data
 		resp.Fields = fields
+		resp.Messages = messages
+	case agentMethodQueryMulti:
+		data, messages, supported, err := queryMultiWithMessagesOptionalTimeout(runtimeState.inst, req.Query, req.TimeoutMs)
+		if err != nil {
+			return fail(resp, err.Error())
+		}
+		if !supported {
+			return fail(resp, "当前驱动不支持原生多结果集查询")
+		}
+		resp.Data = data
+		resp.Messages = messages
 	case agentMethodExec:
-		affected, err := execWithOptionalTimeout(*inst, req.Query, req.TimeoutMs)
+		affected, err := execWithOptionalTimeout(runtimeState.inst, req.Query, req.TimeoutMs)
 		if err != nil {
 			return fail(resp, err.Error())
 		}
 		resp.RowsAffected = affected
 	case agentMethodGetDatabases:
-		data, err := (*inst).GetDatabases()
+		data, err := runtimeState.inst.GetDatabases()
 		if err != nil {
 			return fail(resp, err.Error())
 		}
 		resp.Data = data
 	case agentMethodGetTables:
-		data, err := (*inst).GetTables(req.DBName)
+		data, err := runtimeState.inst.GetTables(req.DBName)
 		if err != nil {
 			return fail(resp, err.Error())
 		}
 		resp.Data = data
 	case agentMethodGetCreateStmt:
-		data, err := (*inst).GetCreateStatement(req.DBName, req.TableName)
+		data, err := runtimeState.inst.GetCreateStatement(req.DBName, req.TableName)
 		if err != nil {
 			return fail(resp, err.Error())
 		}
 		resp.Data = data
 	case agentMethodGetColumns:
-		data, err := (*inst).GetColumns(req.DBName, req.TableName)
+		data, err := runtimeState.inst.GetColumns(req.DBName, req.TableName)
 		if err != nil {
 			return fail(resp, err.Error())
 		}
 		resp.Data = data
 	case agentMethodGetAllColumns:
-		data, err := (*inst).GetAllColumns(req.DBName)
+		data, err := runtimeState.inst.GetAllColumns(req.DBName)
 		if err != nil {
 			return fail(resp, err.Error())
 		}
 		resp.Data = data
 	case agentMethodGetIndexes:
-		data, err := (*inst).GetIndexes(req.DBName, req.TableName)
+		data, err := runtimeState.inst.GetIndexes(req.DBName, req.TableName)
 		if err != nil {
 			return fail(resp, err.Error())
 		}
 		resp.Data = data
 	case agentMethodGetForeignKey:
-		data, err := (*inst).GetForeignKeys(req.DBName, req.TableName)
+		data, err := runtimeState.inst.GetForeignKeys(req.DBName, req.TableName)
 		if err != nil {
 			return fail(resp, err.Error())
 		}
 		resp.Data = data
 	case agentMethodGetTriggers:
-		data, err := (*inst).GetTriggers(req.DBName, req.TableName)
+		data, err := runtimeState.inst.GetTriggers(req.DBName, req.TableName)
 		if err != nil {
 			return fail(resp, err.Error())
 		}
@@ -207,7 +382,7 @@ func handleRequest(inst *db.Database, req agentRequest) agentResponse {
 		if req.Changes == nil {
 			return fail(resp, "变更集为空")
 		}
-		applier, ok := (*inst).(interface {
+		applier, ok := runtimeState.inst.(interface {
 			ApplyChanges(tableName string, changes connection.ChangeSet) error
 		})
 		if !ok {
@@ -223,6 +398,169 @@ func handleRequest(inst *db.Database, req agentRequest) agentResponse {
 	return resp
 }
 
+type agentStreamResponseWriter struct {
+	writer    *bufio.Writer
+	requestID int64
+	columns   []string
+	rows      [][]interface{}
+	rowCount  int64
+}
+
+func newAgentStreamResponseWriter(writer *bufio.Writer, requestID int64) *agentStreamResponseWriter {
+	return &agentStreamResponseWriter{
+		writer:    writer,
+		requestID: requestID,
+	}
+}
+
+func (w *agentStreamResponseWriter) SetColumns(columns []string) error {
+	w.columns = append([]string(nil), columns...)
+	return writeResponse(w.writer, agentResponse{
+		ID:        w.requestID,
+		Success:   true,
+		ChunkType: agentChunkColumns,
+		Fields:    w.columns,
+	})
+}
+
+func (w *agentStreamResponseWriter) ConsumeRow(row map[string]interface{}) error {
+	if len(w.columns) == 0 {
+		return fmt.Errorf("流式查询缺少列定义")
+	}
+	values := make([]interface{}, len(w.columns))
+	for idx, column := range w.columns {
+		values[idx] = row[column]
+	}
+	return w.ConsumeRowValues(values)
+}
+
+func (w *agentStreamResponseWriter) ConsumeRowValues(values []interface{}) error {
+	row := append([]interface{}(nil), values...)
+	w.rows = append(w.rows, row)
+	w.rowCount++
+	if len(w.rows) < agentStreamBatchSize {
+		return nil
+	}
+	return w.flushRows()
+}
+
+func (w *agentStreamResponseWriter) flushRows() error {
+	if len(w.rows) == 0 {
+		return nil
+	}
+	rows := w.rows
+	w.rows = nil
+	return writeResponse(w.writer, agentResponse{
+		ID:        w.requestID,
+		Success:   true,
+		ChunkType: agentChunkRows,
+		Data:      rows,
+	})
+}
+
+func (w *agentStreamResponseWriter) finish() error {
+	return w.flushRows()
+}
+
+func handleStreamRequest(runtimeState *agentRuntime, req agentRequest, writer *bufio.Writer) error {
+	resp := agentResponse{ID: req.ID, Success: true}
+	if runtimeState.inst == nil {
+		return writeResponse(writer, fail(resp, "connection not open"))
+	}
+
+	streamWriter := newAgentStreamResponseWriter(writer, req.ID)
+	if session, ok, err := runtimeState.session(req.SessionID); err != nil {
+		return writeResponse(writer, fail(resp, err.Error()))
+	} else if ok {
+		if err := streamStatementWithOptionalTimeout(session, req.Query, req.TimeoutMs, streamWriter); err != nil {
+			_ = streamWriter.finish()
+			return writeResponse(writer, fail(resp, err.Error()))
+		}
+		if err := streamWriter.finish(); err != nil {
+			return err
+		}
+		if err := writeResponse(writer, agentResponse{ID: req.ID, Success: true, ChunkType: agentChunkDone}); err != nil {
+			return err
+		}
+		maybeReleaseAgentMemory("stream-query-session", streamWriter.rowCount)
+		return nil
+	}
+
+	if err := streamDatabaseWithOptionalTimeout(runtimeState.inst, req.Query, req.TimeoutMs, streamWriter); err != nil {
+		_ = streamWriter.finish()
+		return writeResponse(writer, fail(resp, err.Error()))
+	}
+	if err := streamWriter.finish(); err != nil {
+		return err
+	}
+	if err := writeResponse(writer, agentResponse{ID: req.ID, Success: true, ChunkType: agentChunkDone}); err != nil {
+		return err
+	}
+	maybeReleaseAgentMemory("stream-query-db", streamWriter.rowCount)
+	return nil
+}
+
+func (r *agentRuntime) nextID() string {
+	r.ensureSessionMap()
+	r.nextSessionID++
+	return "session-" + strconv.FormatInt(r.nextSessionID, 10)
+}
+
+func (r *agentRuntime) session(sessionID string) (db.StatementExecer, bool, error) {
+	r.ensureSessionMap()
+	sessionID = strings.TrimSpace(sessionID)
+	if sessionID == "" {
+		return nil, false, nil
+	}
+	session, ok := r.sessions[sessionID]
+	if !ok || session == nil {
+		return nil, false, fmt.Errorf("事务会话不存在或已结束")
+	}
+	return session, true, nil
+}
+
+func (r *agentRuntime) closeSession(sessionID string) error {
+	r.ensureSessionMap()
+	sessionID = strings.TrimSpace(sessionID)
+	if sessionID == "" {
+		return fmt.Errorf("事务会话 ID 不能为空")
+	}
+	session, ok := r.sessions[sessionID]
+	if ok {
+		delete(r.sessions, sessionID)
+	}
+	if !ok || session == nil {
+		return fmt.Errorf("事务会话不存在或已结束")
+	}
+	return session.Close()
+}
+
+func (r *agentRuntime) close() error {
+	var closeErr error
+	r.ensureSessionMap()
+	for sessionID, session := range r.sessions {
+		delete(r.sessions, sessionID)
+		if session != nil {
+			if err := session.Close(); err != nil && closeErr == nil {
+				closeErr = err
+			}
+		}
+	}
+	if r.inst != nil {
+		if err := r.inst.Close(); err != nil && closeErr == nil {
+			closeErr = err
+		}
+		r.inst = nil
+	}
+	return closeErr
+}
+
+func (r *agentRuntime) ensureSessionMap() {
+	if r.sessions == nil {
+		r.sessions = make(map[string]db.StatementExecer)
+	}
+}
+
 func writeResponse(writer *bufio.Writer, resp agentResponse) error {
 	// 对响应数据做统一 JSON 安全归一化：
 	// 将 map[any]any（如 duckdb.Map）递归转换为 map[string]any，避免序列化失败导致代理进程退出。
@@ -293,25 +631,234 @@ func normalizeAgentResponseData(v interface{}) interface{} {
 	}
 }
 
-func queryWithOptionalTimeout(inst db.Database, query string, timeoutMs int64) ([]map[string]interface{}, []string, error) {
+type agentQueryRunner interface {
+	Query(string) ([]map[string]interface{}, []string, error)
+}
+
+type agentQueryContextRunner interface {
+	QueryContext(context.Context, string) ([]map[string]interface{}, []string, error)
+}
+
+type agentQueryMessageRunner interface {
+	QueryWithMessages(query string) ([]map[string]interface{}, []string, []string, error)
+}
+
+type agentQueryMessageContextRunner interface {
+	QueryContextWithMessages(context.Context, string) ([]map[string]interface{}, []string, []string, error)
+}
+
+type agentMultiResultMessageRunner interface {
+	QueryMultiWithMessages(query string) ([]connection.ResultSetData, []string, error)
+}
+
+type agentMultiResultMessageContextRunner interface {
+	QueryMultiContextWithMessages(context.Context, string) ([]connection.ResultSetData, []string, error)
+}
+
+type agentMultiResultRunner interface {
+	QueryMulti(query string) ([]connection.ResultSetData, error)
+}
+
+type agentMultiResultContextRunner interface {
+	QueryMultiContext(context.Context, string) ([]connection.ResultSetData, error)
+}
+
+type agentExecRunner interface {
+	Exec(string) (int64, error)
+}
+
+type agentExecContextRunner interface {
+	ExecContext(context.Context, string) (int64, error)
+}
+
+func queryWithMessagesOptionalTimeout(inst agentQueryRunner, query string, timeoutMs int64) ([]map[string]interface{}, []string, []string, error) {
 	effectiveTimeoutMs := timeoutMs
 	if effectiveTimeoutMs <= 0 && strings.EqualFold(strings.TrimSpace(agentDriverType), "clickhouse") {
 		effectiveTimeoutMs = int64(legacyClickHouseDefaultTimeout / time.Millisecond)
 	}
 	if effectiveTimeoutMs <= 0 {
-		return inst.Query(query)
+		if q, ok := inst.(agentQueryMessageRunner); ok {
+			return q.QueryWithMessages(query)
+		}
+		data, fields, err := inst.Query(query)
+		return data, fields, nil, err
 	}
-	if q, ok := inst.(interface {
-		QueryContext(context.Context, string) ([]map[string]interface{}, []string, error)
-	}); ok {
+	if q, ok := inst.(agentQueryMessageContextRunner); ok {
 		ctx, cancel := context.WithTimeout(context.Background(), time.Duration(effectiveTimeoutMs)*time.Millisecond)
 		defer cancel()
-		return q.QueryContext(ctx, query)
+		return q.QueryContextWithMessages(ctx, query)
 	}
-	return inst.Query(query)
+	if q, ok := inst.(agentQueryContextRunner); ok {
+		ctx, cancel := context.WithTimeout(context.Background(), time.Duration(effectiveTimeoutMs)*time.Millisecond)
+		defer cancel()
+		data, fields, err := q.QueryContext(ctx, query)
+		return data, fields, nil, err
+	}
+	if q, ok := inst.(agentQueryMessageRunner); ok {
+		return q.QueryWithMessages(query)
+	}
+	data, fields, err := inst.Query(query)
+	return data, fields, nil, err
 }
 
-func execWithOptionalTimeout(inst db.Database, query string, timeoutMs int64) (int64, error) {
+func queryWithOptionalTimeout(inst agentQueryRunner, query string, timeoutMs int64) ([]map[string]interface{}, []string, error) {
+	data, fields, _, err := queryWithMessagesOptionalTimeout(inst, query, timeoutMs)
+	return data, fields, err
+}
+
+func queryStatementWithOptionalTimeout(inst db.StatementExecer, query string, timeoutMs int64) ([]map[string]interface{}, []string, error) {
+	queryRunner, ok := inst.(agentQueryRunner)
+	if !ok {
+		return nil, nil, fmt.Errorf("当前事务会话不支持查询语句")
+	}
+	return queryWithOptionalTimeout(queryRunner, query, timeoutMs)
+}
+
+func queryStatementWithMessagesOptionalTimeout(inst db.StatementExecer, query string, timeoutMs int64) ([]map[string]interface{}, []string, []string, error) {
+	queryRunner, ok := inst.(agentQueryRunner)
+	if !ok {
+		return nil, nil, nil, fmt.Errorf("当前事务会话不支持查询语句")
+	}
+	return queryWithMessagesOptionalTimeout(queryRunner, query, timeoutMs)
+}
+
+func queryMultiWithMessagesOptionalTimeout(inst db.Database, query string, timeoutMs int64) ([]connection.ResultSetData, []string, bool, error) {
+	effectiveTimeoutMs := timeoutMs
+	if effectiveTimeoutMs <= 0 && strings.EqualFold(strings.TrimSpace(agentDriverType), "clickhouse") {
+		effectiveTimeoutMs = int64(legacyClickHouseDefaultTimeout / time.Millisecond)
+	}
+	if effectiveTimeoutMs > 0 {
+		if q, ok := inst.(agentMultiResultMessageContextRunner); ok {
+			ctx, cancel := context.WithTimeout(context.Background(), time.Duration(effectiveTimeoutMs)*time.Millisecond)
+			defer cancel()
+			data, messages, err := q.QueryMultiContextWithMessages(ctx, query)
+			return data, messages, true, err
+		}
+		if q, ok := inst.(agentMultiResultContextRunner); ok {
+			ctx, cancel := context.WithTimeout(context.Background(), time.Duration(effectiveTimeoutMs)*time.Millisecond)
+			defer cancel()
+			data, err := q.QueryMultiContext(ctx, query)
+			return data, nil, true, err
+		}
+	}
+	if q, ok := inst.(agentMultiResultMessageRunner); ok {
+		data, messages, err := q.QueryMultiWithMessages(query)
+		return data, messages, true, err
+	}
+	if q, ok := inst.(agentMultiResultRunner); ok {
+		data, err := q.QueryMulti(query)
+		return data, nil, true, err
+	}
+	return nil, nil, false, nil
+}
+
+func queryMultiStatementWithMessagesOptionalTimeout(inst db.StatementExecer, query string, timeoutMs int64) ([]connection.ResultSetData, []string, bool, error) {
+	effectiveTimeoutMs := timeoutMs
+	if effectiveTimeoutMs <= 0 && strings.EqualFold(strings.TrimSpace(agentDriverType), "clickhouse") {
+		effectiveTimeoutMs = int64(legacyClickHouseDefaultTimeout / time.Millisecond)
+	}
+	if effectiveTimeoutMs > 0 {
+		if q, ok := inst.(agentMultiResultMessageContextRunner); ok {
+			ctx, cancel := context.WithTimeout(context.Background(), time.Duration(effectiveTimeoutMs)*time.Millisecond)
+			defer cancel()
+			data, messages, err := q.QueryMultiContextWithMessages(ctx, query)
+			return data, messages, true, err
+		}
+		if q, ok := inst.(agentMultiResultContextRunner); ok {
+			ctx, cancel := context.WithTimeout(context.Background(), time.Duration(effectiveTimeoutMs)*time.Millisecond)
+			defer cancel()
+			data, err := q.QueryMultiContext(ctx, query)
+			return data, nil, true, err
+		}
+	}
+	if q, ok := inst.(agentMultiResultMessageRunner); ok {
+		data, messages, err := q.QueryMultiWithMessages(query)
+		return data, messages, true, err
+	}
+	if q, ok := inst.(agentMultiResultRunner); ok {
+		data, err := q.QueryMulti(query)
+		return data, nil, true, err
+	}
+	return nil, nil, false, nil
+}
+
+func streamWithOptionalTimeout(inst db.StreamQueryExecer, query string, timeoutMs int64, consumer db.QueryStreamConsumer) error {
+	effectiveTimeoutMs := timeoutMs
+	if effectiveTimeoutMs <= 0 && strings.EqualFold(strings.TrimSpace(agentDriverType), "clickhouse") {
+		effectiveTimeoutMs = int64(legacyClickHouseDefaultTimeout / time.Millisecond)
+	}
+	if effectiveTimeoutMs <= 0 {
+		return inst.StreamQuery(query, consumer)
+	}
+	ctx, cancel := context.WithTimeout(context.Background(), time.Duration(effectiveTimeoutMs)*time.Millisecond)
+	defer cancel()
+	return inst.StreamQueryContext(ctx, query, consumer)
+}
+
+func streamBufferedQueryResult(fields []string, data []map[string]interface{}, consumer db.QueryStreamConsumer) error {
+	if err := consumer.SetColumns(fields); err != nil {
+		return err
+	}
+	if valueConsumer, ok := consumer.(db.QueryStreamValueConsumer); ok {
+		for _, row := range data {
+			values := make([]interface{}, len(fields))
+			for idx, field := range fields {
+				values[idx] = row[field]
+			}
+			if err := valueConsumer.ConsumeRowValues(values); err != nil {
+				return err
+			}
+		}
+		return nil
+	}
+	for _, row := range data {
+		if err := consumer.ConsumeRow(row); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+func streamStatementWithOptionalTimeout(inst db.StatementExecer, query string, timeoutMs int64, consumer db.QueryStreamConsumer) error {
+	if streamer, ok := inst.(db.StreamQueryExecer); ok {
+		return streamWithOptionalTimeout(streamer, query, timeoutMs, consumer)
+	}
+	data, fields, err := queryStatementWithOptionalTimeout(inst, query, timeoutMs)
+	if err != nil {
+		return err
+	}
+	return streamBufferedQueryResult(fields, data, consumer)
+}
+
+func streamDatabaseWithOptionalTimeout(inst db.Database, query string, timeoutMs int64, consumer db.QueryStreamConsumer) error {
+	if streamer, ok := inst.(db.StreamQueryExecer); ok {
+		return streamWithOptionalTimeout(streamer, query, timeoutMs, consumer)
+	}
+	if provider, ok := inst.(db.SessionExecerProvider); ok {
+		openCtx := context.Background()
+		var cancel context.CancelFunc
+		effectiveTimeoutMs := timeoutMs
+		if effectiveTimeoutMs <= 0 && strings.EqualFold(strings.TrimSpace(agentDriverType), "clickhouse") {
+			effectiveTimeoutMs = int64(legacyClickHouseDefaultTimeout / time.Millisecond)
+		}
+		if effectiveTimeoutMs > 0 {
+			openCtx, cancel = context.WithTimeout(context.Background(), time.Duration(effectiveTimeoutMs)*time.Millisecond)
+			defer cancel()
+		}
+		session, err := provider.OpenSessionExecer(openCtx)
+		if err == nil {
+			defer session.Close()
+			return streamStatementWithOptionalTimeout(session, query, timeoutMs, consumer)
+		}
+	}
+	data, fields, err := queryWithOptionalTimeout(inst, query, timeoutMs)
+	if err != nil {
+		return err
+	}
+	return streamBufferedQueryResult(fields, data, consumer)
+}
+
+func execWithOptionalTimeout(inst agentExecRunner, query string, timeoutMs int64) (int64, error) {
 	effectiveTimeoutMs := timeoutMs
 	if effectiveTimeoutMs <= 0 && strings.EqualFold(strings.TrimSpace(agentDriverType), "clickhouse") {
 		effectiveTimeoutMs = int64(legacyClickHouseDefaultTimeout / time.Millisecond)
@@ -319,12 +866,52 @@ func execWithOptionalTimeout(inst db.Database, query string, timeoutMs int64) (i
 	if effectiveTimeoutMs <= 0 {
 		return inst.Exec(query)
 	}
-	if e, ok := inst.(interface {
-		ExecContext(context.Context, string) (int64, error)
-	}); ok {
+	if e, ok := inst.(agentExecContextRunner); ok {
 		ctx, cancel := context.WithTimeout(context.Background(), time.Duration(effectiveTimeoutMs)*time.Millisecond)
 		defer cancel()
 		return e.ExecContext(ctx, query)
 	}
 	return inst.Exec(query)
 }
+
+func execStatementWithOptionalTimeout(inst db.StatementExecer, query string, timeoutMs int64) (int64, error) {
+	return execWithOptionalTimeout(inst, query, timeoutMs)
+}
+
+func countAgentResponseRows(data interface{}) int64 {
+	rows, ok := data.([]map[string]interface{})
+	if !ok {
+		return 0
+	}
+	return int64(len(rows))
+}
+
+func maybeReleaseAgentMemory(reason string, rows int64) {
+	if rows < agentMemoryTrimRowsThreshold {
+		return
+	}
+	if !agentMemoryTrimRunning.CompareAndSwap(false, true) {
+		return
+	}
+
+	runAgentMemoryTrimAsync(func() {
+		defer agentMemoryTrimRunning.Store(false)
+		if delay := nextAgentMemoryTrimDelay(); delay > 0 {
+			time.Sleep(delay)
+		}
+		agentMemoryTrimFn()
+		agentMemoryTrimLastAt.Store(time.Now().UnixNano())
+	})
+}
+
+func nextAgentMemoryTrimDelay() time.Duration {
+	lastUnixNano := agentMemoryTrimLastAt.Load()
+	if lastUnixNano <= 0 {
+		return 0
+	}
+	elapsed := time.Since(time.Unix(0, lastUnixNano))
+	if elapsed >= agentMemoryTrimMinInterval {
+		return 0
+	}
+	return agentMemoryTrimMinInterval - elapsed
+}

cmd/optional-driver-agent/main_test.go

@@ -6,10 +6,12 @@ import (
 	"context"
 	"encoding/json"
 	"errors"
+	"strings"
 	"testing"
 	"time"
 
 	"GoNavi-Wails/internal/connection"
+	"GoNavi-Wails/internal/db"
 )
 
 type duckMapLike map[any]any
@@ -66,12 +68,42 @@ func TestNormalizeAgentResponseData_KeepByteSlice(t *testing.T) {
 	}
 }
 
+func TestHandleRequestMetadataReportsAgentRevision(t *testing.T) {
+	previousDriverType := agentDriverType
+	previousFactory := agentDatabaseFactory
+	t.Cleanup(func() {
+		agentDriverType = previousDriverType
+		agentDatabaseFactory = previousFactory
+	})
+	agentDriverType = "clickhouse"
+	agentDatabaseFactory = func() db.Database { return nil }
+
+	runtimeState := &agentRuntime{sessions: make(map[string]db.StatementExecer)}
+	resp := handleRequest(runtimeState, agentRequest{ID: 7, Method: agentMethodMetadata})
+	if !resp.Success {
+		t.Fatalf("metadata request failed: %s", resp.Error)
+	}
+	data, ok := resp.Data.(map[string]string)
+	if !ok {
+		t.Fatalf("metadata response data type = %T", resp.Data)
+	}
+	if data["driverType"] != "clickhouse" {
+		t.Fatalf("unexpected driver type: %q", data["driverType"])
+	}
+	if data["agentRevision"] != db.OptionalDriverAgentRevision("clickhouse") {
+		t.Fatalf("unexpected agent revision: %q", data["agentRevision"])
+	}
+}
+
 type fakeAgentTimeoutDB struct {
 	queryCalled        bool
 	queryContextCalled bool
 	execCalled         bool
 	execContextCalled  bool
 	deadlineSet        bool
+	queryMessages      []string
+	multiResults       []connection.ResultSetData
+	multiMessages      []string
 }
 
 func (f *fakeAgentTimeoutDB) Connect(config connection.ConnectionConfig) error { return nil }
@@ -88,6 +120,14 @@ func (f *fakeAgentTimeoutDB) QueryContext(ctx context.Context, query string) ([]
 	}
 	return []map[string]interface{}{{"ok": 1}}, []string{"ok"}, nil
 }
+func (f *fakeAgentTimeoutDB) QueryWithMessages(query string) ([]map[string]interface{}, []string, []string, error) {
+	data, fields, err := f.QueryContext(context.Background(), query)
+	return data, fields, append([]string(nil), f.queryMessages...), err
+}
+func (f *fakeAgentTimeoutDB) QueryContextWithMessages(ctx context.Context, query string) ([]map[string]interface{}, []string, []string, error) {
+	data, fields, err := f.QueryContext(ctx, query)
+	return data, fields, append([]string(nil), f.queryMessages...), err
+}
 func (f *fakeAgentTimeoutDB) Exec(query string) (int64, error) {
 	f.execCalled = true
 	return 0, errors.New("exec should not be called")
@@ -121,6 +161,147 @@ func (f *fakeAgentTimeoutDB) GetForeignKeys(dbName, tableName string) ([]connect
 func (f *fakeAgentTimeoutDB) GetTriggers(dbName, tableName string) ([]connection.TriggerDefinition, error) {
 	return nil, nil
 }
+func (f *fakeAgentTimeoutDB) QueryMultiWithMessages(query string) ([]connection.ResultSetData, []string, error) {
+	return append([]connection.ResultSetData(nil), f.multiResults...), append([]string(nil), f.multiMessages...), nil
+}
+func (f *fakeAgentTimeoutDB) QueryMultiContextWithMessages(ctx context.Context, query string) ([]connection.ResultSetData, []string, error) {
+	if _, ok := ctx.Deadline(); ok {
+		f.deadlineSet = true
+	}
+	return f.QueryMultiWithMessages(query)
+}
+
+type fakeAgentSessionDB struct {
+	fakeAgentTimeoutDB
+	session *fakeAgentStatementSession
+}
+
+type fakeAgentTransactionDB struct {
+	fakeAgentTimeoutDB
+	transaction *fakeAgentTransactionSession
+}
+
+func (f *fakeAgentTransactionDB) OpenTransactionExecer(context.Context) (db.TransactionExecer, error) {
+	f.transaction = &fakeAgentTransactionSession{}
+	return f.transaction, nil
+}
+
+type fakeAgentTransactionSession struct {
+	fakeAgentStatementSession
+	commitCalls   int
+	rollbackCalls int
+}
+
+func (f *fakeAgentTransactionSession) Commit() error {
+	f.commitCalls++
+	return nil
+}
+
+func (f *fakeAgentTransactionSession) Rollback() error {
+	f.rollbackCalls++
+	return nil
+}
+
+func (f *fakeAgentSessionDB) OpenSessionExecer(ctx context.Context) (db.StatementExecer, error) {
+	f.session = &fakeAgentStatementSession{}
+	return f.session, nil
+}
+
+type fakeAgentStatementSession struct {
+	queryCalls int
+	execCalls  int
+	closed     bool
+	messages   []string
+}
+
+func (f *fakeAgentStatementSession) Query(query string) ([]map[string]interface{}, []string, error) {
+	return f.QueryContext(context.Background(), query)
+}
+
+func (f *fakeAgentStatementSession) QueryContext(ctx context.Context, query string) ([]map[string]interface{}, []string, error) {
+	f.queryCalls++
+	return []map[string]interface{}{{"session_ok": 1}}, []string{"session_ok"}, nil
+}
+func (f *fakeAgentStatementSession) QueryWithMessages(query string) ([]map[string]interface{}, []string, []string, error) {
+	data, fields, err := f.QueryContext(context.Background(), query)
+	return data, fields, append([]string(nil), f.messages...), err
+}
+func (f *fakeAgentStatementSession) QueryContextWithMessages(ctx context.Context, query string) ([]map[string]interface{}, []string, []string, error) {
+	data, fields, err := f.QueryContext(ctx, query)
+	return data, fields, append([]string(nil), f.messages...), err
+}
+
+func (f *fakeAgentStatementSession) Exec(query string) (int64, error) {
+	return f.ExecContext(context.Background(), query)
+}
+
+func (f *fakeAgentStatementSession) ExecContext(ctx context.Context, query string) (int64, error) {
+	f.execCalls++
+	return 9, nil
+}
+
+func (f *fakeAgentStatementSession) Close() error {
+	f.closed = true
+	return nil
+}
+
+type fakeAgentStreamSession struct {
+	closed      bool
+	streamCalls int
+	deadlineSet bool
+}
+
+func (f *fakeAgentStreamSession) Exec(query string) (int64, error) {
+	return 0, nil
+}
+
+func (f *fakeAgentStreamSession) ExecContext(ctx context.Context, query string) (int64, error) {
+	return 0, nil
+}
+
+func (f *fakeAgentStreamSession) Close() error {
+	f.closed = true
+	return nil
+}
+
+func (f *fakeAgentStreamSession) StreamQuery(query string, consumer db.QueryStreamConsumer) error {
+	return f.StreamQueryContext(context.Background(), query, consumer)
+}
+
+func (f *fakeAgentStreamSession) StreamQueryContext(ctx context.Context, query string, consumer db.QueryStreamConsumer) error {
+	f.streamCalls++
+	if _, ok := ctx.Deadline(); ok {
+		f.deadlineSet = true
+	}
+	if err := consumer.SetColumns([]string{"id", "name"}); err != nil {
+		return err
+	}
+	if valueConsumer, ok := consumer.(db.QueryStreamValueConsumer); ok {
+		if err := valueConsumer.ConsumeRowValues([]interface{}{1, "alice"}); err != nil {
+			return err
+		}
+		if err := valueConsumer.ConsumeRowValues([]interface{}{2, "bob"}); err != nil {
+			return err
+		}
+		return nil
+	}
+	if err := consumer.ConsumeRow(map[string]interface{}{"id": 1, "name": "alice"}); err != nil {
+		return err
+	}
+	return consumer.ConsumeRow(map[string]interface{}{"id": 2, "name": "bob"})
+}
+
+type fakeAgentSessionStreamDB struct {
+	fakeAgentTimeoutDB
+	session   *fakeAgentStreamSession
+	openCalls int
+}
+
+func (f *fakeAgentSessionStreamDB) OpenSessionExecer(ctx context.Context) (db.StatementExecer, error) {
+	f.openCalls++
+	f.session = &fakeAgentStreamSession{}
+	return f.session, nil
+}
 
 func TestQueryWithOptionalTimeout_UsesQueryContext(t *testing.T) {
 	fake := &fakeAgentTimeoutDB{}
@@ -170,3 +351,343 @@ func TestQueryWithOptionalTimeout_ClickHouseLegacyModeUsesQueryContext(t *testin
 		t.Fatalf("clickhouse legacy query 调用路径异常，QueryContext=%v Query=%v", fake.queryContextCalled, fake.queryCalled)
 	}
 }
+
+func TestHandleRequest_QueryIncludesServerMessages(t *testing.T) {
+	old := agentDriverType
+	defer func() { agentDriverType = old }()
+	agentDriverType = "sqlserver"
+
+	fake := &fakeAgentTimeoutDB{
+		queryMessages: []string{"PRINT sql line 1", "PRINT sql line 2"},
+	}
+	runtimeState := &agentRuntime{inst: fake, sessions: make(map[string]db.StatementExecer)}
+
+	resp := handleRequest(runtimeState, agentRequest{
+		ID:        11,
+		Method:    agentMethodQuery,
+		Query:     "exec dbo.p_get_select",
+		TimeoutMs: int64((2 * time.Second).Milliseconds()),
+	})
+	if !resp.Success {
+		t.Fatalf("query request failed: %s", resp.Error)
+	}
+	if len(resp.Messages) != 2 || resp.Messages[0] != "PRINT sql line 1" {
+		t.Fatalf("expected query messages to be preserved, got %#v", resp.Messages)
+	}
+}
+
+func TestHandleRequest_QueryMultiIncludesResultSetsAndMessages(t *testing.T) {
+	old := agentDriverType
+	defer func() { agentDriverType = old }()
+	agentDriverType = "sqlserver"
+
+	fake := &fakeAgentTimeoutDB{
+		multiResults: []connection.ResultSetData{
+			{
+				StatementIndex: 1,
+				Rows:           []map[string]interface{}{{"name": "master"}},
+				Columns:        []string{"name"},
+			},
+			{
+				StatementIndex: 1,
+				Rows:           []map[string]interface{}{},
+				Columns:        []string{},
+				Messages:       []string{"PRINT generated sql"},
+			},
+		},
+		multiMessages: []string{"batch top-level message"},
+	}
+	runtimeState := &agentRuntime{inst: fake, sessions: make(map[string]db.StatementExecer)}
+
+	resp := handleRequest(runtimeState, agentRequest{
+		ID:        12,
+		Method:    agentMethodQueryMulti,
+		Query:     "exec dbo.p_get_select",
+		TimeoutMs: int64((2 * time.Second).Milliseconds()),
+	})
+	if !resp.Success {
+		t.Fatalf("queryMulti request failed: %s", resp.Error)
+	}
+	if len(resp.Messages) != 1 || resp.Messages[0] != "batch top-level message" {
+		t.Fatalf("expected top-level messages to be preserved, got %#v", resp.Messages)
+	}
+	resultSets, ok := resp.Data.([]connection.ResultSetData)
+	if !ok {
+		t.Fatalf("expected []connection.ResultSetData, got %T", resp.Data)
+	}
+	if len(resultSets) != 2 {
+		t.Fatalf("expected 2 result sets, got %#v", resultSets)
+	}
+	if len(resultSets[1].Messages) != 1 || resultSets[1].Messages[0] != "PRINT generated sql" {
+		t.Fatalf("expected message-only result set to be preserved, got %#v", resultSets[1])
+	}
+}
+
+func TestHandleRequest_UsesPinnedSessionForSessionScopedQueryAndExec(t *testing.T) {
+	old := agentDriverType
+	defer func() { agentDriverType = old }()
+	agentDriverType = "sqlserver"
+
+	fake := &fakeAgentSessionDB{}
+	runtimeState := &agentRuntime{
+		inst:     fake,
+		sessions: make(map[string]db.StatementExecer),
+	}
+
+	openResp := handleRequest(runtimeState, agentRequest{ID: 1, Method: agentMethodOpenSession})
+	if !openResp.Success {
+		t.Fatalf("openSession failed: %s", openResp.Error)
+	}
+	sessionID, ok := openResp.Data.(string)
+	if !ok || strings.TrimSpace(sessionID) == "" {
+		t.Fatalf("unexpected session id payload: %#v", openResp.Data)
+	}
+	if fake.session == nil {
+		t.Fatal("expected OpenSessionExecer to create a pinned session")
+	}
+
+	queryResp := handleRequest(runtimeState, agentRequest{
+		ID:        2,
+		Method:    agentMethodQuery,
+		SessionID: sessionID,
+		Query:     "SELECT 1",
+	})
+	if !queryResp.Success {
+		t.Fatalf("session query failed: %s", queryResp.Error)
+	}
+	if len(queryResp.Messages) != 0 {
+		t.Fatalf("expected empty default session messages, got %#v", queryResp.Messages)
+	}
+	if fake.queryCalled || fake.queryContextCalled {
+		t.Fatalf("expected session query to bypass database-level query path, got Query=%v QueryContext=%v", fake.queryCalled, fake.queryContextCalled)
+	}
+	if fake.session.queryCalls != 1 {
+		t.Fatalf("expected pinned session queryCalls=1, got %d", fake.session.queryCalls)
+	}
+
+	execResp := handleRequest(runtimeState, agentRequest{
+		ID:        3,
+		Method:    agentMethodExec,
+		SessionID: sessionID,
+		Query:     "UPDATE t SET v = 1",
+	})
+	if !execResp.Success {
+		t.Fatalf("session exec failed: %s", execResp.Error)
+	}
+	if fake.execCalled || fake.execContextCalled {
+		t.Fatalf("expected session exec to bypass database-level exec path, got Exec=%v ExecContext=%v", fake.execCalled, fake.execContextCalled)
+	}
+	if fake.session.execCalls != 1 {
+		t.Fatalf("expected pinned session execCalls=1, got %d", fake.session.execCalls)
+	}
+
+	closeResp := handleRequest(runtimeState, agentRequest{
+		ID:        4,
+		Method:    agentMethodCloseSession,
+		SessionID: sessionID,
+	})
+	if !closeResp.Success {
+		t.Fatalf("closeSession failed: %s", closeResp.Error)
+	}
+	if !fake.session.closed {
+		t.Fatal("expected pinned session to close")
+	}
+}
+
+func TestHandleRequest_UsesManagedTransactionSession(t *testing.T) {
+	for _, tc := range []struct {
+		name          string
+		finishMethod  string
+		wantCommits   int
+		wantRollbacks int
+	}{
+		{name: "commit", finishMethod: "commitTransaction", wantCommits: 1},
+		{name: "rollback", finishMethod: "rollbackTransaction", wantRollbacks: 1},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			fake := &fakeAgentTransactionDB{}
+			runtimeState := &agentRuntime{
+				inst:     fake,
+				sessions: make(map[string]db.StatementExecer),
+			}
+
+			openResp := handleRequest(runtimeState, agentRequest{ID: 1, Method: "openTransaction"})
+			if !openResp.Success {
+				t.Fatalf("openTransaction failed: %s", openResp.Error)
+			}
+			sessionID, ok := openResp.Data.(string)
+			if !ok || strings.TrimSpace(sessionID) == "" {
+				t.Fatalf("unexpected transaction id payload: %#v", openResp.Data)
+			}
+
+			execResp := handleRequest(runtimeState, agentRequest{
+				ID:        2,
+				Method:    agentMethodExec,
+				SessionID: sessionID,
+				Query:     "UPDATE t SET v = 1",
+			})
+			if !execResp.Success {
+				t.Fatalf("transaction exec failed: %s", execResp.Error)
+			}
+
+			finishResp := handleRequest(runtimeState, agentRequest{
+				ID:        3,
+				Method:    tc.finishMethod,
+				SessionID: sessionID,
+			})
+			if !finishResp.Success {
+				t.Fatalf("%s failed: %s", tc.finishMethod, finishResp.Error)
+			}
+			closeResp := handleRequest(runtimeState, agentRequest{
+				ID:        4,
+				Method:    agentMethodCloseSession,
+				SessionID: sessionID,
+			})
+			if !closeResp.Success {
+				t.Fatalf("closeSession failed: %s", closeResp.Error)
+			}
+			if fake.transaction == nil || !fake.transaction.closed {
+				t.Fatal("expected managed transaction session to close")
+			}
+			if fake.transaction.commitCalls != tc.wantCommits || fake.transaction.rollbackCalls != tc.wantRollbacks {
+				t.Fatalf(
+					"unexpected finish calls: commit=%d rollback=%d",
+					fake.transaction.commitCalls,
+					fake.transaction.rollbackCalls,
+				)
+			}
+		})
+	}
+}
+
+func TestHandleStreamRequest_UsesSessionStreamerAndWritesChunks(t *testing.T) {
+	old := agentDriverType
+	originalAsync := runAgentMemoryTrimAsync
+	originalTrim := agentMemoryTrimFn
+	originalLastAt := agentMemoryTrimLastAt.Load()
+	defer func() { agentDriverType = old }()
+	defer func() {
+		runAgentMemoryTrimAsync = originalAsync
+		agentMemoryTrimFn = originalTrim
+		agentMemoryTrimRunning.Store(false)
+		agentMemoryTrimLastAt.Store(originalLastAt)
+	}()
+	agentDriverType = "oceanbase"
+	agentMemoryTrimRunning.Store(false)
+	agentMemoryTrimLastAt.Store(0)
+
+	fake := &fakeAgentSessionStreamDB{}
+	runtimeState := &agentRuntime{
+		inst:     fake,
+		sessions: make(map[string]db.StatementExecer),
+	}
+
+	trimmed := 0
+	runAgentMemoryTrimAsync = func(fn func()) {
+		fn()
+	}
+	agentMemoryTrimFn = func() {
+		trimmed++
+	}
+
+	var out bytes.Buffer
+	writer := bufio.NewWriter(&out)
+	if err := handleStreamRequest(runtimeState, agentRequest{
+		ID:        9,
+		Method:    agentMethodStreamQuery,
+		Query:     "SELECT * FROM person_info",
+		TimeoutMs: int64((2 * time.Second).Milliseconds()),
+	}, writer); err != nil {
+		t.Fatalf("handleStreamRequest 返回错误: %v", err)
+	}
+
+	if fake.openCalls != 1 {
+		t.Fatalf("expected OpenSessionExecer called once, got %d", fake.openCalls)
+	}
+	if fake.session == nil || fake.session.streamCalls != 1 {
+		t.Fatalf("expected session streamer used once, session=%#v", fake.session)
+	}
+	if !fake.session.deadlineSet {
+		t.Fatal("expected stream query context deadline to be set")
+	}
+	if !fake.session.closed {
+		t.Fatal("expected session to close after streaming")
+	}
+	if fake.queryCalled || fake.queryContextCalled {
+		t.Fatalf("unexpected fallback query path, Query=%v QueryContext=%v", fake.queryCalled, fake.queryContextCalled)
+	}
+
+	lines := strings.Split(strings.TrimSpace(out.String()), "\n")
+	if len(lines) != 3 {
+		t.Fatalf("expected 3 stream responses, got %d: %q", len(lines), out.String())
+	}
+
+	var columnsResp struct {
+		Success   bool     `json:"success"`
+		ChunkType string   `json:"chunkType"`
+		Fields    []string `json:"fields"`
+	}
+	if err := json.Unmarshal([]byte(lines[0]), &columnsResp); err != nil {
+		t.Fatalf("decode columns response failed: %v", err)
+	}
+	if !columnsResp.Success || columnsResp.ChunkType != agentChunkColumns || len(columnsResp.Fields) != 2 {
+		t.Fatalf("unexpected columns response: %#v", columnsResp)
+	}
+
+	var rowsResp struct {
+		Success   bool            `json:"success"`
+		ChunkType string          `json:"chunkType"`
+		Data      [][]interface{} `json:"data"`
+	}
+	if err := json.Unmarshal([]byte(lines[1]), &rowsResp); err != nil {
+		t.Fatalf("decode rows response failed: %v", err)
+	}
+	if !rowsResp.Success || rowsResp.ChunkType != agentChunkRows || len(rowsResp.Data) != 2 {
+		t.Fatalf("unexpected rows response: %#v", rowsResp)
+	}
+	if got := rowsResp.Data[1][1]; got != "bob" {
+		t.Fatalf("unexpected streamed row payload: %v", rowsResp.Data)
+	}
+
+	var doneResp struct {
+		Success   bool   `json:"success"`
+		ChunkType string `json:"chunkType"`
+	}
+	if err := json.Unmarshal([]byte(lines[2]), &doneResp); err != nil {
+		t.Fatalf("decode done response failed: %v", err)
+	}
+	if !doneResp.Success || doneResp.ChunkType != agentChunkDone {
+		t.Fatalf("unexpected done response: %#v", doneResp)
+	}
+	if trimmed != 0 {
+		t.Fatalf("小流式任务不应触发内存回收，got=%d", trimmed)
+	}
+}
+
+func TestMaybeReleaseAgentMemory_TriggersTrimForLargeJobs(t *testing.T) {
+	originalAsync := runAgentMemoryTrimAsync
+	originalTrim := agentMemoryTrimFn
+	originalLastAt := agentMemoryTrimLastAt.Load()
+	t.Cleanup(func() {
+		runAgentMemoryTrimAsync = originalAsync
+		agentMemoryTrimFn = originalTrim
+		agentMemoryTrimRunning.Store(false)
+		agentMemoryTrimLastAt.Store(originalLastAt)
+	})
+
+	agentMemoryTrimRunning.Store(false)
+	agentMemoryTrimLastAt.Store(0)
+	triggered := 0
+	runAgentMemoryTrimAsync = func(fn func()) {
+		fn()
+	}
+	agentMemoryTrimFn = func() {
+		triggered++
+	}
+
+	maybeReleaseAgentMemory("test-large-query", agentMemoryTrimRowsThreshold)
+
+	if triggered != 1 {
+		t.Fatalf("大查询完成后应触发一次内存回收，got=%d", triggered)
+	}
+}

cmd/optional-driver-agent/provider_elasticsearch.go

@@ -0,0 +1,12 @@
+//go:build gonavi_elasticsearch_driver
+
+package main
+
+import "GoNavi-Wails/internal/db"
+
+func init() {
+	agentDriverType = "elasticsearch"
+	agentDatabaseFactory = func() db.Database {
+		return &db.ElasticsearchDB{}
+	}
+}

cmd/optional-driver-agent/provider_gaussdb.go

@@ -0,0 +1,12 @@
+//go:build gonavi_gaussdb_driver
+
+package main
+
+import "GoNavi-Wails/internal/db"
+
+func init() {
+	agentDriverType = "gaussdb"
+	agentDatabaseFactory = func() db.Database {
+		return &db.GaussDB{}
+	}
+}

cmd/optional-driver-agent/provider_iotdb.go

@@ -0,0 +1,12 @@
+//go:build gonavi_iotdb_driver
+
+package main
+
+import "GoNavi-Wails/internal/db"
+
+func init() {
+	agentDriverType = "iotdb"
+	agentDatabaseFactory = func() db.Database {
+		return &db.IoTDBDB{}
+	}
+}

cmd/optional-driver-agent/provider_iris.go

@@ -0,0 +1,12 @@
+//go:build gonavi_iris_driver
+
+package main
+
+import "GoNavi-Wails/internal/db"
+
+func init() {
+	agentDriverType = "iris"
+	agentDatabaseFactory = func() db.Database {
+		return &db.IrisDB{}
+	}
+}

cmd/optional-driver-agent/provider_oceanbase.go

@@ -0,0 +1,12 @@
+//go:build gonavi_oceanbase_driver
+
+package main
+
+import "GoNavi-Wails/internal/db"
+
+func init() {
+	agentDriverType = "oceanbase"
+	agentDatabaseFactory = func() db.Database {
+		return &db.OceanBaseDB{}
+	}
+}

cmd/optional-driver-agent/provider_opengauss.go

@@ -0,0 +1,12 @@
+//go:build gonavi_opengauss_driver
+
+package main
+
+import "GoNavi-Wails/internal/db"
+
+func init() {
+	agentDriverType = "opengauss"
+	agentDatabaseFactory = func() db.Database {
+		return &db.OpenGaussDB{}
+	}
+}

cmd/optional-driver-agent/provider_starrocks.go

@@ -0,0 +1,12 @@
+//go:build gonavi_starrocks_driver
+
+package main
+
+import "GoNavi-Wails/internal/db"
+
+func init() {
+	agentDriverType = "starrocks"
+	agentDatabaseFactory = func() db.Database {
+		return &db.StarRocksDB{}
+	}
+}

cmd/optional-driver-agent/provider_trino.go

@@ -0,0 +1,12 @@
+//go:build gonavi_trino_driver
+
+package main
+
+import "GoNavi-Wails/internal/db"
+
+func init() {
+	agentDriverType = "trino"
+	agentDatabaseFactory = func() db.Database {
+		return &db.TrinoDB{}
+	}
+}

deploy/download-mirror/gatewaysentry-nginx.conf

@@ -0,0 +1,87 @@
+server {
+    listen 80;
+    listen [::]:80;
+    server_name download.syngnat.top;
+
+    root /srv/gonavi-downloads;
+    access_log /var/log/nginx/gonavi-download-access.log;
+    error_log /var/log/nginx/gonavi-download-error.log warn;
+
+    client_max_body_size 1m;
+    autoindex off;
+    etag on;
+    max_ranges 8;
+
+    location = /health.txt {
+        try_files $uri =404;
+        default_type text/plain;
+        add_header Cache-Control "no-store" always;
+        add_header X-Content-Type-Options "nosniff" always;
+    }
+
+    location ~ ^/(?:gonavi|drivers)/(?:dev/)?releases/latest/ {
+        try_files $uri =404;
+        limit_except GET { deny all; }
+        add_header Cache-Control "no-store, no-cache, must-revalidate" always;
+        add_header Pragma "no-cache" always;
+        add_header X-Content-Type-Options "nosniff" always;
+    }
+
+    location ~ ^/(?:gonavi|drivers)/(?:dev/)?releases/download/ {
+        try_files $uri =404;
+        limit_except GET { deny all; }
+        add_header Cache-Control "public, max-age=31536000, immutable" always;
+        add_header X-Content-Type-Options "nosniff" always;
+    }
+
+    location / {
+        add_header Cache-Control "no-store" always;
+        return 404;
+    }
+}
+
+server {
+    listen 127.0.0.1:9443 ssl;
+    listen [::1]:9443 ssl;
+    server_name download.syngnat.top;
+
+    ssl_certificate /etc/nginx/certs/download.syngnat.top.crt;
+    ssl_certificate_key /etc/nginx/certs/download.syngnat.top.key;
+    ssl_protocols TLSv1.2 TLSv1.3;
+
+    root /srv/gonavi-downloads;
+    access_log /var/log/nginx/gonavi-download-access.log;
+    error_log /var/log/nginx/gonavi-download-error.log warn;
+
+    client_max_body_size 1m;
+    autoindex off;
+    etag on;
+    max_ranges 8;
+
+    location = /health.txt {
+        try_files $uri =404;
+        default_type text/plain;
+        add_header Cache-Control "no-store" always;
+        add_header X-Content-Type-Options "nosniff" always;
+    }
+
+    location ~ ^/(?:gonavi|drivers)/(?:dev/)?releases/latest/ {
+        try_files $uri =404;
+        limit_except GET { deny all; }
+        add_header Cache-Control "no-store, no-cache, must-revalidate" always;
+        add_header Pragma "no-cache" always;
+        add_header X-Content-Type-Options "nosniff" always;
+    }
+
+    location ~ ^/(?:gonavi|drivers)/(?:dev/)?releases/download/ {
+        try_files $uri =404;
+        limit_except GET { deny all; }
+        add_header Cache-Control "public, max-age=31536000, immutable" always;
+        add_header X-Content-Type-Options "nosniff" always;
+    }
+
+    location / {
+        add_header Cache-Control "no-store" always;
+        return 404;
+    }
+}

deploy/download-mirror/install-gatewaysentry.sh

@@ -0,0 +1,49 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if [[ "$(id -u)" -ne 0 ]]; then
+    echo "this installer must run as root" >&2
+    exit 1
+fi
+if [[ $# -ne 1 || ! -f "$1" ]]; then
+    echo "usage: $0 PATH_TO_NGINX_CONFIG" >&2
+    exit 2
+fi
+
+nginx_source="$1"
+mirror_user="gonavi-deploy"
+mirror_root="/srv/gonavi-downloads"
+certificate="/etc/nginx/certs/download.syngnat.top.crt"
+private_key="/etc/nginx/certs/download.syngnat.top.key"
+site_available="/etc/nginx/sites-available/download.syngnat.top.conf"
+site_enabled="/etc/nginx/sites-enabled/download.syngnat.top.conf"
+
+if ! id "${mirror_user}" >/dev/null 2>&1; then
+    useradd --create-home --shell /bin/bash "${mirror_user}"
+fi
+install -d -m 0755 -o "${mirror_user}" -g www-data "${mirror_root}"
+install -d -m 0755 -o "${mirror_user}" -g www-data "${mirror_root}/.incoming"
+printf '%s\n' 'gonavi-download-mirror-v1' > "${mirror_root}/.gonavi-mirror-root"
+printf '%s\n' 'GoNavi download mirror' > "${mirror_root}/health.txt"
+chown "${mirror_user}:www-data" \
+    "${mirror_root}/.gonavi-mirror-root" \
+    "${mirror_root}/health.txt"
+chmod 0644 "${mirror_root}/.gonavi-mirror-root" "${mirror_root}/health.txt"
+
+install -d -m 0755 /etc/nginx/certs
+if [[ ! -s "${certificate}" || ! -s "${private_key}" ]]; then
+    openssl req -x509 -newkey rsa:2048 -sha256 -nodes -days 3650 \
+        -subj '/CN=download.syngnat.top' \
+        -addext 'subjectAltName=DNS:download.syngnat.top' \
+        -keyout "${private_key}" \
+        -out "${certificate}"
+fi
+chmod 0600 "${private_key}"
+chmod 0644 "${certificate}"
+
+install -m 0644 "${nginx_source}" "${site_available}"
+ln -sfn "${site_available}" "${site_enabled}"
+nginx -t
+systemctl reload nginx
+
+echo "Gatewaysentry download mirror origin installed"

deploy/download-mirror/seed-from-public-mirror.py

@@ -0,0 +1,291 @@
+#!/usr/bin/env python3
+"""Seed a VPS mirror from the currently published public mirror."""
+
+from __future__ import annotations
+
+import argparse
+import concurrent.futures
+import hashlib
+import json
+import os
+import re
+import shutil
+import subprocess
+import sys
+import tempfile
+import threading
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from pathlib import Path
+from typing import Any
+
+
+TAG_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$")
+USER_AGENT = "GoNavi-VPS-Mirror-Seeder/1"
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--source-base-url", required=True)
+    parser.add_argument("--mirror-root", type=Path, required=True)
+    parser.add_argument("--prepare-script", type=Path, required=True)
+    parser.add_argument("--commit-script", type=Path, required=True)
+    parser.add_argument("--workers", type=int, default=4)
+    return parser.parse_args()
+
+
+def fetch_json(url: str) -> tuple[dict[str, Any], bytes]:
+    separator = "&" if "?" in url else "?"
+    request = urllib.request.Request(
+        f"{url}{separator}seed={int(time.time())}",
+        headers={"User-Agent": USER_AGENT, "Cache-Control": "no-cache"},
+    )
+    with urllib.request.urlopen(request, timeout=60) as response:
+        raw = response.read()
+    value = json.loads(raw)
+    if not isinstance(value, dict):
+        raise ValueError(f"expected JSON object from {url}")
+    return value, raw
+
+
+def validate_tag(value: Any, label: str) -> str:
+    if not isinstance(value, str) or not TAG_RE.fullmatch(value):
+        raise ValueError(f"invalid {label}: {value!r}")
+    return value
+
+
+def validate_name(value: Any) -> str:
+    if not isinstance(value, str) or not value or Path(value).name != value:
+        raise ValueError(f"invalid asset name: {value!r}")
+    if value in {".", ".."} or "/" in value or "\\" in value:
+        raise ValueError(f"invalid asset name: {value!r}")
+    return value
+
+
+def sha256_file(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as handle:
+        for chunk in iter(lambda: handle.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def download_file(
+    url: str,
+    destination: Path,
+    expected_size: int,
+    expected_sha256: str | None,
+) -> int:
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    partial = destination.with_name(destination.name + ".part")
+    if destination.is_file() and destination.stat().st_size == expected_size:
+        if expected_sha256 is None or sha256_file(destination) == expected_sha256:
+            return expected_size
+
+    for attempt in range(1, 4):
+        offset = partial.stat().st_size if partial.exists() else 0
+        if offset > expected_size:
+            partial.unlink()
+            offset = 0
+        headers = {"User-Agent": USER_AGENT}
+        if offset:
+            headers["Range"] = f"bytes={offset}-"
+        request = urllib.request.Request(url, headers=headers)
+        try:
+            with urllib.request.urlopen(request, timeout=120) as response:
+                append = offset > 0 and response.status == 206
+                mode = "ab" if append else "wb"
+                with partial.open(mode) as output:
+                    shutil.copyfileobj(response, output, length=1024 * 1024)
+        except (OSError, urllib.error.URLError) as exc:
+            if attempt == 3:
+                raise RuntimeError(f"download failed after 3 attempts: {url}: {exc}") from exc
+            time.sleep(attempt * 2)
+            continue
+
+        if partial.stat().st_size != expected_size:
+            if attempt == 3:
+                raise ValueError(
+                    f"download size mismatch for {destination.name}: "
+                    f"expected {expected_size}, got {partial.stat().st_size}"
+                )
+            time.sleep(attempt * 2)
+            continue
+        if expected_sha256 is not None and sha256_file(partial) != expected_sha256:
+            partial.unlink()
+            if attempt == 3:
+                raise ValueError(f"download sha256 mismatch for {destination.name}")
+            continue
+        partial.replace(destination)
+        os.chmod(destination, 0o644)
+        return expected_size
+    raise AssertionError("unreachable")
+
+
+def download_many(
+    items: list[tuple[str, Path, int, str | None]],
+    workers: int,
+    label: str,
+) -> None:
+    completed_files = 0
+    completed_bytes = 0
+    lock = threading.Lock()
+
+    def run(item: tuple[str, Path, int, str | None]) -> None:
+        nonlocal completed_files, completed_bytes
+        size = download_file(*item)
+        with lock:
+            completed_files += 1
+            completed_bytes += size
+            if completed_files == len(items) or completed_files % 10 == 0:
+                print(
+                    f"{label}: {completed_files}/{len(items)} files, "
+                    f"{completed_bytes / (1024 ** 3):.2f} GiB",
+                    flush=True,
+                )
+
+    with concurrent.futures.ThreadPoolExecutor(max_workers=workers) as executor:
+        futures = [executor.submit(run, item) for item in items]
+        for future in concurrent.futures.as_completed(futures):
+            future.result()
+
+
+def seed_channel(
+    source_base_url: str,
+    mirror_root: Path,
+    prepare_script: Path,
+    commit_script: Path,
+    workers: int,
+    channel: str,
+) -> None:
+    if channel == "stable":
+        app_latest_path = "gonavi/releases/latest/latest.json"
+        driver_latest_path = "drivers/releases/latest/GoNavi-DriverAgents-Index.json"
+        app_download_root = "gonavi/releases/download"
+        driver_download_root = "drivers/releases/download"
+    else:
+        app_latest_path = "gonavi/dev/releases/latest/latest-dev.json"
+        driver_latest_path = "drivers/dev/releases/latest/GoNavi-DriverAgents-Index.json"
+        app_download_root = "gonavi/dev/releases/download"
+        driver_download_root = "drivers/dev/releases/download"
+
+    app_manifest, app_manifest_raw = fetch_json(f"{source_base_url}/{app_latest_path}")
+    driver_index, driver_index_raw = fetch_json(f"{source_base_url}/{driver_latest_path}")
+    if channel == "stable":
+        app_tag = validate_tag(app_manifest.get("tagName"), "stable app tag")
+        driver_tag = validate_tag(driver_index.get("tagName"), "stable driver tag")
+    else:
+        app_tag = validate_tag(app_manifest.get("version"), "dev app tag")
+        driver_tag = validate_tag(driver_index.get("mirrorTagName"), "dev driver tag")
+
+    source_dir = Path(tempfile.mkdtemp(prefix=f".seed-{channel}-", dir=mirror_root))
+    app_dir = source_dir / "app"
+    driver_dir = source_dir / "driver"
+    app_dir.mkdir()
+    driver_dir.mkdir()
+    app_manifest_path = app_dir / Path(app_latest_path).name
+    driver_index_path = driver_dir / "GoNavi-DriverAgents-Index.json"
+    app_manifest_path.write_bytes(app_manifest_raw)
+    driver_index_path.write_bytes(driver_index_raw)
+
+    app_assets = app_manifest.get("assets")
+    if not isinstance(app_assets, list) or not app_assets:
+        raise ValueError(f"{channel} app manifest has no assets")
+    app_items: list[tuple[str, Path, int, str | None]] = []
+    for entry in app_assets:
+        if not isinstance(entry, dict):
+            raise ValueError("app asset entry must be an object")
+        name = validate_name(entry.get("name"))
+        size = entry.get("size")
+        checksum = entry.get("sha256")
+        if not isinstance(size, int) or size < 0:
+            raise ValueError(f"invalid app asset size for {name}")
+        if not isinstance(checksum, str) or not re.fullmatch(r"[0-9a-fA-F]{64}", checksum):
+            raise ValueError(f"invalid app asset sha256 for {name}")
+        url = f"{source_base_url}/{app_download_root}/{app_tag}/{urllib.parse.quote(name)}"
+        app_items.append((url, app_dir / name, size, checksum.lower()))
+
+    driver_assets = driver_index.get("assets")
+    if not isinstance(driver_assets, dict) or not driver_assets:
+        raise ValueError(f"{channel} driver index has no assets")
+    driver_items: list[tuple[str, Path, int, str | None]] = []
+    for raw_name, size in sorted(driver_assets.items()):
+        name = validate_name(raw_name)
+        if not isinstance(size, int) or size < 0:
+            raise ValueError(f"invalid driver asset size for {name}")
+        url = f"{source_base_url}/{driver_download_root}/{driver_tag}/{urllib.parse.quote(name)}"
+        driver_items.append((url, driver_dir / name, size, None))
+
+    print(f"Seeding {channel} app {app_tag}", flush=True)
+    download_many(app_items, workers, f"{channel} app")
+    print(f"Seeding {channel} drivers {driver_tag}", flush=True)
+    download_many(driver_items, workers, f"{channel} drivers")
+
+    deployment_id = f"seed-{channel}-{int(time.time())}"
+    staging_dir = mirror_root / ".incoming" / deployment_id
+    subprocess.run(
+        [
+            sys.executable,
+            str(prepare_script),
+            "--channel",
+            channel,
+            "--app-tag",
+            app_tag,
+            "--app-dir",
+            str(app_dir),
+            "--app-manifest",
+            str(app_manifest_path),
+            "--driver-tag",
+            driver_tag,
+            "--driver-dir",
+            str(driver_dir),
+            "--driver-version-index",
+            str(driver_index_path),
+            "--driver-latest-index",
+            str(driver_index_path),
+            "--output",
+            str(staging_dir),
+        ],
+        check=True,
+    )
+    subprocess.run(
+        [
+            "bash",
+            str(commit_script),
+            str(mirror_root),
+            str(staging_dir),
+            channel,
+            app_tag,
+            driver_tag,
+        ],
+        check=True,
+    )
+    shutil.rmtree(source_dir)
+
+
+def main() -> int:
+    args = parse_args()
+    if args.workers < 1 or args.workers > 8:
+        print("error: --workers must be between 1 and 8", file=sys.stderr)
+        return 2
+    source_base_url = args.source_base_url.rstrip("/")
+    try:
+        for channel in ("stable", "dev"):
+            seed_channel(
+                source_base_url,
+                args.mirror_root,
+                args.prepare_script,
+                args.commit_script,
+                args.workers,
+                channel,
+            )
+    except (OSError, ValueError, RuntimeError, subprocess.CalledProcessError) as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

deploy/helm/gonavi-mcp-server/Chart.yaml

@@ -0,0 +1,7 @@
+apiVersion: v2
+name: gonavi-mcp-server
+description: Helm chart for deploying GoNavi MCP Server
+type: application
+version: 0.1.0
+appVersion: "latest"
+kubeVersion: ">=1.24.0-0"

deploy/helm/gonavi-mcp-server/README.md

@@ -0,0 +1,94 @@
+# GoNavi MCP Server Helm Chart
+
+这个 Chart 用来部署 `gonavi-mcp-server`，覆盖当前仓库 K8s 示例里的几类常见场景：
+
+- 基于现有 Secret 直接部署
+- 通过 Helm values 内联创建测试用 Secret
+- 启用 Ingress
+- 追加 `drivers/` PVC
+- NAS / k3s 单机节点直接挂宿主机数据目录
+
+Chart 目录：
+
+- `Chart.yaml`
+- `values.yaml`
+- `values-examples/*.yaml`
+- `templates/*.yaml`
+
+## 1. 默认安装
+
+默认值假设你已经有一个现成 Secret：
+
+- 名称：`gonavi-mcp-server-data`
+- 至少包含：
+  - `connections.json`
+  - `daily_secrets.json`
+  - `GONAVI_MCP_HTTP_TOKEN`
+
+安装命令：
+
+```bash
+helm upgrade --install gonavi-mcp-server deploy/helm/gonavi-mcp-server -n gonavi --create-namespace
+```
+
+## 2. 直接创建测试用 Secret
+
+如果只是本地验证模板或快速试跑，可以使用示例 values：
+
+```bash
+helm upgrade --install gonavi-mcp-server deploy/helm/gonavi-mcp-server \
+  -n gonavi --create-namespace \
+  -f deploy/helm/gonavi-mcp-server/values-examples/inline-secret.yaml
+```
+
+这个示例只适合最小联调，不适合真实生产连接数据。
+
+## 3. 常用示例
+
+启用 Ingress：
+
+```bash
+helm upgrade --install gonavi-mcp-server deploy/helm/gonavi-mcp-server \
+  -n gonavi --create-namespace \
+  -f deploy/helm/gonavi-mcp-server/values-examples/ingress.yaml
+```
+
+挂载 drivers PVC：
+
+```bash
+helm upgrade --install gonavi-mcp-server deploy/helm/gonavi-mcp-server \
+  -n gonavi --create-namespace \
+  -f deploy/helm/gonavi-mcp-server/values-examples/drivers-pvc.yaml
+```
+
+同时启用 Ingress 与 drivers PVC：
+
+```bash
+helm upgrade --install gonavi-mcp-server deploy/helm/gonavi-mcp-server \
+  -n gonavi --create-namespace \
+  -f deploy/helm/gonavi-mcp-server/values-examples/ingress-with-drivers-pvc.yaml
+```
+
+NAS / k3s hostPath：
+
+```bash
+helm upgrade --install gonavi-mcp-server deploy/helm/gonavi-mcp-server \
+  -n gonavi --create-namespace \
+  -f deploy/helm/gonavi-mcp-server/values-examples/nas-hostpath.yaml
+```
+
+## 4. 关键参数
+
+- `image.repository` / `image.tag`
+- `secret.create`
+- `secret.name`
+- `data.mode=secret|hostPath|pvc`
+- `drivers.mode=none|pvc|hostPath`
+- `ingress.enabled`
+
+## 5. 约束
+
+- `data.mode=secret` 时，Secret 必须能提供 `connections.json` 和 `daily_secrets.json`
+- `data.mode=hostPath` 时，宿主机目录需要包含 GoNavi 活动数据目录内容
+- `drivers.mode!=none` 时，会在 `/data/drivers` 追加独立挂载
+- Chart 默认只部署 MCP Server，不部署桌面 GUI

deploy/helm/gonavi-mcp-server/templates/_helpers.tpl

@@ -0,0 +1,49 @@
+{{- define "gonavi-mcp-server.name" -}}
+{{- default .Chart.Name .Values.nameOverride | trunc 63 | trimSuffix "-" -}}
+{{- end -}}
+
+{{- define "gonavi-mcp-server.fullname" -}}
+{{- if .Values.fullnameOverride -}}
+{{- .Values.fullnameOverride | trunc 63 | trimSuffix "-" -}}
+{{- else -}}
+{{- $name := include "gonavi-mcp-server.name" . -}}
+{{- if contains $name .Release.Name -}}
+{{- .Release.Name | trunc 63 | trimSuffix "-" -}}
+{{- else -}}
+{{- printf "%s-%s" .Release.Name $name | trunc 63 | trimSuffix "-" -}}
+{{- end -}}
+{{- end -}}
+{{- end -}}
+
+{{- define "gonavi-mcp-server.chart" -}}
+{{- printf "%s-%s" .Chart.Name .Chart.Version | replace "+" "_" -}}
+{{- end -}}
+
+{{- define "gonavi-mcp-server.labels" -}}
+helm.sh/chart: {{ include "gonavi-mcp-server.chart" . }}
+app.kubernetes.io/name: {{ include "gonavi-mcp-server.name" . }}
+app.kubernetes.io/instance: {{ .Release.Name }}
+app.kubernetes.io/version: {{ .Chart.AppVersion | quote }}
+app.kubernetes.io/managed-by: {{ .Release.Service }}
+{{- end -}}
+
+{{- define "gonavi-mcp-server.selectorLabels" -}}
+app.kubernetes.io/name: {{ include "gonavi-mcp-server.name" . }}
+app.kubernetes.io/instance: {{ .Release.Name }}
+{{- end -}}
+
+{{- define "gonavi-mcp-server.namespace" -}}
+{{- default .Release.Namespace .Values.namespaceOverride -}}
+{{- end -}}
+
+{{- define "gonavi-mcp-server.secretName" -}}
+{{- if .Values.secret.name -}}
+{{- .Values.secret.name -}}
+{{- else -}}
+{{- include "gonavi-mcp-server.fullname" . -}}
+{{- end -}}
+{{- end -}}
+
+{{- define "gonavi-mcp-server.serviceName" -}}
+{{- include "gonavi-mcp-server.fullname" . -}}
+{{- end -}}

deploy/helm/gonavi-mcp-server/templates/deployment.yaml

@@ -0,0 +1,130 @@
+{{- $dataMode := .Values.data.mode -}}
+{{- $driversMode := .Values.drivers.mode -}}
+{{- if not (or (eq $dataMode "secret") (eq $dataMode "hostPath") (eq $dataMode "pvc")) -}}
+{{- fail "data.mode must be one of: secret, hostPath, pvc" -}}
+{{- end -}}
+{{- if not (or (eq $driversMode "none") (eq $driversMode "pvc") (eq $driversMode "hostPath")) -}}
+{{- fail "drivers.mode must be one of: none, pvc, hostPath" -}}
+{{- end -}}
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: {{ include "gonavi-mcp-server.fullname" . }}
+  namespace: {{ include "gonavi-mcp-server.namespace" . }}
+  labels:
+    {{- include "gonavi-mcp-server.labels" . | nindent 4 }}
+spec:
+  replicas: {{ .Values.replicaCount }}
+  selector:
+    matchLabels:
+      {{- include "gonavi-mcp-server.selectorLabels" . | nindent 6 }}
+  template:
+    metadata:
+      labels:
+        {{- include "gonavi-mcp-server.selectorLabels" . | nindent 8 }}
+      {{- with .Values.podAnnotations }}
+      annotations:
+        {{- toYaml . | nindent 8 }}
+      {{- end }}
+    spec:
+      securityContext:
+        {{- toYaml .Values.podSecurityContext | nindent 8 }}
+      containers:
+        - name: gonavi-mcp-server
+          image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}"
+          imagePullPolicy: {{ .Values.image.pullPolicy }}
+          args:
+            - http
+            {{- range .Values.mcp.extraArgs }}
+            - {{ . | quote }}
+            {{- end }}
+          ports:
+            - name: http
+              containerPort: {{ .Values.service.port }}
+              protocol: TCP
+          env:
+            - name: GONAVI_DATA_ROOT
+              value: {{ .Values.mcp.dataRoot | quote }}
+            - name: GONAVI_LOG_DIR
+              value: {{ .Values.mcp.logDir | quote }}
+            - name: GONAVI_MCP_HTTP_ADDR
+              value: {{ .Values.mcp.httpAddr | quote }}
+            - name: GONAVI_MCP_HTTP_PATH
+              value: {{ .Values.mcp.httpPath | quote }}
+            - name: GONAVI_MCP_SCHEMA_ONLY
+              value: {{ ternary "true" "false" .Values.mcp.schemaOnly | quote }}
+            - name: GONAVI_MCP_HTTP_TOKEN
+              valueFrom:
+                secretKeyRef:
+                  name: {{ include "gonavi-mcp-server.secretName" . }}
+                  key: {{ .Values.secret.tokenKey }}
+            {{- with .Values.mcp.extraEnv }}
+            {{- toYaml . | nindent 12 }}
+            {{- end }}
+          volumeMounts:
+            - name: gonavi-data
+              mountPath: {{ .Values.data.mountPath | quote }}
+              readOnly: true
+            {{- if ne $driversMode "none" }}
+            - name: gonavi-drivers
+              mountPath: {{ .Values.drivers.mountPath | quote }}
+              readOnly: true
+            {{- end }}
+          readinessProbe:
+            httpGet:
+              path: /healthz
+              port: http
+            initialDelaySeconds: 3
+            periodSeconds: 10
+          livenessProbe:
+            httpGet:
+              path: /healthz
+              port: http
+            initialDelaySeconds: 10
+            periodSeconds: 20
+          resources:
+            {{- toYaml .Values.resources | nindent 12 }}
+          securityContext:
+            {{- toYaml .Values.containerSecurityContext | nindent 12 }}
+      volumes:
+        - name: gonavi-data
+          {{- if eq $dataMode "secret" }}
+          projected:
+            sources:
+              - secret:
+                  name: {{ include "gonavi-mcp-server.secretName" . }}
+                  items:
+                    - key: {{ .Values.secret.connectionsJsonKey }}
+                      path: connections.json
+                    - key: {{ .Values.secret.dailySecretsJsonKey }}
+                      path: daily_secrets.json
+          {{- else if eq $dataMode "hostPath" }}
+          hostPath:
+            path: {{ required "data.hostPath.path is required when data.mode=hostPath" .Values.data.hostPath.path | quote }}
+            type: {{ default "Directory" .Values.data.hostPath.type | quote }}
+          {{- else if eq $dataMode "pvc" }}
+          persistentVolumeClaim:
+            claimName: {{ required "data.pvc.claimName is required when data.mode=pvc" .Values.data.pvc.claimName | quote }}
+          {{- end }}
+        {{- if eq $driversMode "pvc" }}
+        - name: gonavi-drivers
+          persistentVolumeClaim:
+            claimName: {{ required "drivers.pvc.claimName is required when drivers.mode=pvc" .Values.drivers.pvc.claimName | quote }}
+        {{- else if eq $driversMode "hostPath" }}
+        - name: gonavi-drivers
+          hostPath:
+            path: {{ required "drivers.hostPath.path is required when drivers.mode=hostPath" .Values.drivers.hostPath.path | quote }}
+            type: {{ default "Directory" .Values.drivers.hostPath.type | quote }}
+        {{- end }}
+      {{- with .Values.nodeSelector }}
+      nodeSelector:
+        {{- toYaml . | nindent 8 }}
+      {{- end }}
+      {{- with .Values.affinity }}
+      affinity:
+        {{- toYaml . | nindent 8 }}
+      {{- end }}
+      {{- with .Values.tolerations }}
+      tolerations:
+        {{- toYaml . | nindent 8 }}
+      {{- end }}

deploy/helm/gonavi-mcp-server/templates/ingress.yaml

@@ -0,0 +1,34 @@
+{{- if .Values.ingress.enabled }}
+apiVersion: networking.k8s.io/v1
+kind: Ingress
+metadata:
+  name: {{ include "gonavi-mcp-server.fullname" . }}
+  namespace: {{ include "gonavi-mcp-server.namespace" . }}
+  labels:
+    {{- include "gonavi-mcp-server.labels" . | nindent 4 }}
+  {{- with .Values.ingress.annotations }}
+  annotations:
+    {{- toYaml . | nindent 4 }}
+  {{- end }}
+spec:
+  ingressClassName: {{ .Values.ingress.className | quote }}
+  {{- with .Values.ingress.tls }}
+  tls:
+    {{- toYaml . | nindent 4 }}
+  {{- end }}
+  rules:
+    {{- range .Values.ingress.hosts }}
+    - host: {{ .host | quote }}
+      http:
+        paths:
+          {{- range .paths }}
+          - path: {{ .path | quote }}
+            pathType: {{ .pathType | quote }}
+            backend:
+              service:
+                name: {{ include "gonavi-mcp-server.serviceName" $ }}
+                port:
+                  number: {{ $.Values.service.port }}
+          {{- end }}
+    {{- end }}
+{{- end }}

deploy/helm/gonavi-mcp-server/templates/secret.yaml

@@ -0,0 +1,27 @@
+{{- if .Values.secret.create }}
+apiVersion: v1
+kind: Secret
+metadata:
+  name: {{ include "gonavi-mcp-server.secretName" . }}
+  namespace: {{ include "gonavi-mcp-server.namespace" . }}
+  labels:
+    {{- include "gonavi-mcp-server.labels" . | nindent 4 }}
+type: Opaque
+stringData:
+  {{ .Values.secret.tokenKey }}: {{ required "secret.stringData.token is required when secret.create=true" .Values.secret.stringData.token | quote }}
+  {{- if eq .Values.data.mode "secret" }}
+  {{ .Values.secret.connectionsJsonKey }}: |
+{{ required "secret.stringData.connectionsJson is required when data.mode=secret and secret.create=true" .Values.secret.stringData.connectionsJson | nindent 4 }}
+  {{ .Values.secret.dailySecretsJsonKey }}: |
+{{ required "secret.stringData.dailySecretsJson is required when data.mode=secret and secret.create=true" .Values.secret.stringData.dailySecretsJson | nindent 4 }}
+  {{- else }}
+  {{- if .Values.secret.stringData.connectionsJson }}
+  {{ .Values.secret.connectionsJsonKey }}: |
+{{ .Values.secret.stringData.connectionsJson | nindent 4 }}
+  {{- end }}
+  {{- if .Values.secret.stringData.dailySecretsJson }}
+  {{ .Values.secret.dailySecretsJsonKey }}: |
+{{ .Values.secret.stringData.dailySecretsJson | nindent 4 }}
+  {{- end }}
+  {{- end }}
+{{- end }}

deploy/helm/gonavi-mcp-server/templates/service.yaml

@@ -0,0 +1,20 @@
+apiVersion: v1
+kind: Service
+metadata:
+  name: {{ include "gonavi-mcp-server.serviceName" . }}
+  namespace: {{ include "gonavi-mcp-server.namespace" . }}
+  labels:
+    {{- include "gonavi-mcp-server.labels" . | nindent 4 }}
+  {{- with .Values.service.annotations }}
+  annotations:
+    {{- toYaml . | nindent 4 }}
+  {{- end }}
+spec:
+  type: {{ .Values.service.type }}
+  selector:
+    {{- include "gonavi-mcp-server.selectorLabels" . | nindent 4 }}
+  ports:
+    - name: http
+      port: {{ .Values.service.port }}
+      targetPort: http
+      protocol: TCP

deploy/helm/gonavi-mcp-server/values-examples/drivers-pvc.yaml

@@ -0,0 +1,4 @@
+drivers:
+  mode: pvc
+  pvc:
+    claimName: gonavi-drivers

deploy/helm/gonavi-mcp-server/values-examples/ingress-with-drivers-pvc.yaml

@@ -0,0 +1,19 @@
+ingress:
+  enabled: true
+  className: nginx
+  hosts:
+    - host: gonavi-mcp.example.com
+      paths:
+        - path: /mcp
+          pathType: Prefix
+        - path: /healthz
+          pathType: Prefix
+  tls:
+    - secretName: gonavi-mcp-server-tls
+      hosts:
+        - gonavi-mcp.example.com
+
+drivers:
+  mode: pvc
+  pvc:
+    claimName: gonavi-drivers

deploy/helm/gonavi-mcp-server/values-examples/ingress.yaml

@@ -0,0 +1,14 @@
+ingress:
+  enabled: true
+  className: nginx
+  hosts:
+    - host: gonavi-mcp.example.com
+      paths:
+        - path: /mcp
+          pathType: Prefix
+        - path: /healthz
+          pathType: Prefix
+  tls:
+    - secretName: gonavi-mcp-server-tls
+      hosts:
+        - gonavi-mcp.example.com

deploy/helm/gonavi-mcp-server/values-examples/inline-secret.yaml

@@ -0,0 +1,13 @@
+secret:
+  create: true
+  stringData:
+    token: replace-with-a-random-token
+    connectionsJson: |
+      {
+        "connections": []
+      }
+    dailySecretsJson: |
+      {
+        "schemaVersion": 1,
+        "connections": {}
+      }

deploy/helm/gonavi-mcp-server/values-examples/nas-hostpath.yaml

@@ -0,0 +1,10 @@
+data:
+  mode: hostPath
+  hostPath:
+    path: /volume1/docker/gonavi/data
+    type: Directory
+
+secret:
+  create: true
+  stringData:
+    token: replace-with-a-random-token

deploy/helm/gonavi-mcp-server/values.yaml

@@ -0,0 +1,99 @@
+nameOverride: ""
+fullnameOverride: ""
+namespaceOverride: ""
+
+replicaCount: 1
+
+image:
+  repository: ghcr.io/syngnat/gonavi-mcp-server
+  tag: latest
+  pullPolicy: IfNotPresent
+
+service:
+  type: ClusterIP
+  port: 8765
+  annotations: {}
+
+mcp:
+  dataRoot: /data
+  logDir: /var/lib/gonavi/logs
+  httpAddr: 0.0.0.0:8765
+  httpPath: /mcp
+  schemaOnly: true
+  extraArgs: []
+  extraEnv: []
+
+secret:
+  create: false
+  name: gonavi-mcp-server-data
+  tokenKey: GONAVI_MCP_HTTP_TOKEN
+  connectionsJsonKey: connections.json
+  dailySecretsJsonKey: daily_secrets.json
+  stringData:
+    token: ""
+    connectionsJson: ""
+    dailySecretsJson: ""
+
+data:
+  mode: secret
+  mountPath: /data
+  hostPath:
+    path: /volume1/docker/gonavi/data
+    type: Directory
+  pvc:
+    claimName: ""
+
+drivers:
+  mode: none
+  mountPath: /data/drivers
+  pvc:
+    claimName: gonavi-drivers
+  hostPath:
+    path: /volume1/docker/gonavi/drivers
+    type: Directory
+
+ingress:
+  enabled: false
+  className: nginx
+  annotations:
+    nginx.ingress.kubernetes.io/backend-protocol: "HTTP"
+    nginx.ingress.kubernetes.io/proxy-read-timeout: "3600"
+    nginx.ingress.kubernetes.io/proxy-send-timeout: "3600"
+  hosts:
+    - host: gonavi-mcp.example.com
+      paths:
+        - path: /mcp
+          pathType: Prefix
+        - path: /healthz
+          pathType: Prefix
+  tls:
+    - secretName: gonavi-mcp-server-tls
+      hosts:
+        - gonavi-mcp.example.com
+
+resources:
+  requests:
+    cpu: 100m
+    memory: 128Mi
+  limits:
+    cpu: 500m
+    memory: 512Mi
+
+podAnnotations: {}
+
+podSecurityContext:
+  runAsNonRoot: true
+  runAsUser: 10001
+  runAsGroup: 10001
+  seccompProfile:
+    type: RuntimeDefault
+
+containerSecurityContext:
+  allowPrivilegeEscalation: false
+  capabilities:
+    drop:
+      - ALL
+
+nodeSelector: {}
+tolerations: []
+affinity: {}

deploy/k8s/gonavi-mcp-server/README.md

@@ -0,0 +1,151 @@
+# GoNavi MCP Server Kubernetes 示例
+
+这个目录提供 `gonavi-mcp-server` 的最小 K8s 部署清单，适合：
+
+- Linux 服务器上的单集群部署
+- NAS 自带 K8s / k3s / k8s-lite 环境
+- 需要把 GoNavi MCP 通过 Ingress / Gateway 暴露给远端 Agent 的场景
+
+如果你希望通过 values 参数统一控制镜像、Secret、Ingress、PVC/hostPath，而不是维护多份 overlay，请直接使用 [deploy/helm/gonavi-mcp-server](../../helm/gonavi-mcp-server)。
+
+目录结构：
+
+- `kustomization.yaml`：基础部署入口
+- `base/kustomization.yaml`：基础资源集合
+- `overlays/nas-hostpath`：直接挂 NAS / 单机节点上的 GoNavi 数据目录
+- `base/deployment.yaml` / `base/service.yaml`：基础资源
+- `overlays/drivers-pvc`：为 `/data/drivers` 增加 PVC 挂载
+- `overlays/ingress`：增加 Ingress 暴露 `/mcp`
+- `overlays/ingress-with-drivers-pvc`：同时启用 Ingress 和 drivers PVC
+
+## 前提
+
+容器仍然依赖 GoNavi 的活动数据目录。至少要准备：
+
+- `connections.json`
+- `daily_secrets.json`
+
+如果目标连接依赖可选 driver agent，还需要额外挂载 `/data/drivers`。
+
+`base/deployment.yaml` 默认镜像指向：
+
+```text
+ghcr.io/syngnat/gonavi-mcp-server:latest
+```
+
+如果你要跟随 `dev` 分支，可以改成：
+
+```text
+ghcr.io/syngnat/gonavi-mcp-server:dev-latest
+```
+
+如果你要使用自建镜像，再按下面方式覆盖 `image`：
+
+- 在当前节点可访问的 Docker / Podman / containerd 环境中构建并导入这个镜像
+- 把镜像推送到你的私有仓库，并同步修改 `base/deployment.yaml` 里的 `image`
+
+例如：
+
+```bash
+docker build -f Dockerfile.mcp-server -t gonavi-mcp-server:local .
+# or
+podman build -f Dockerfile.mcp-server -t localhost/gonavi-mcp-server:local .
+```
+
+## 1. 创建 Secret
+
+推荐直接从现有 GoNavi 数据文件生成：
+
+```bash
+kubectl create secret generic gonavi-mcp-server-data \
+  --from-file=connections.json=/absolute/path/to/gonavi-data/connections.json \
+  --from-file=daily_secrets.json=/absolute/path/to/gonavi-data/daily_secrets.json \
+  --from-literal=GONAVI_MCP_HTTP_TOKEN=replace-with-a-random-token
+```
+
+如需单独 namespace，请先执行：
+
+```bash
+kubectl create namespace gonavi
+kubectl -n gonavi create secret generic gonavi-mcp-server-data \
+  --from-file=connections.json=/absolute/path/to/gonavi-data/connections.json \
+  --from-file=daily_secrets.json=/absolute/path/to/gonavi-data/daily_secrets.json \
+  --from-literal=GONAVI_MCP_HTTP_TOKEN=replace-with-a-random-token
+```
+
+## 2. 应用清单
+
+```bash
+kubectl apply -k deploy/k8s/gonavi-mcp-server
+```
+
+如果使用独立 namespace，请先把 YAML 里的 `namespace` 改成你的目标值，或自行用 `kustomize` / Helm 做二次封装。
+
+清单内已经带了基础安全上下文和默认资源配额；如果你的连接数量、对象规模或并发访问更高，建议按实际负载调整 `resources`。
+
+### 常用 Overlay
+
+仅基础部署：
+
+```bash
+kubectl apply -k deploy/k8s/gonavi-mcp-server
+```
+
+需要可选 driver agent：
+
+```bash
+kubectl apply -k deploy/k8s/gonavi-mcp-server/overlays/drivers-pvc
+```
+
+NAS / k3s 单机节点直接挂宿主机目录：
+
+```bash
+kubectl apply -k deploy/k8s/gonavi-mcp-server/overlays/nas-hostpath
+```
+
+需要对外暴露 `/mcp`：
+
+```bash
+kubectl apply -k deploy/k8s/gonavi-mcp-server/overlays/ingress
+```
+
+同时需要 Ingress 与 drivers PVC：
+
+```bash
+kubectl apply -k deploy/k8s/gonavi-mcp-server/overlays/ingress-with-drivers-pvc
+```
+
+应用 overlay 前，记得先改里面的占位值，例如：
+
+- `overlays/ingress/ingress.yaml` 里的域名、TLS Secret、`ingressClassName`
+- `overlays/drivers-pvc/patch-deployment.yaml` 里的 PVC 名称 `gonavi-drivers`
+- `overlays/nas-hostpath/patch-deployment.yaml` 里的宿主机目录 `/volume1/docker/gonavi/data`
+
+`nas-hostpath` overlay 会直接把整个 GoNavi 数据目录挂到 `/data`，因此 `connections.json`、`daily_secrets.json`、`drivers/` 都从宿主机目录读取；此时仍建议保留 `GONAVI_MCP_HTTP_TOKEN` 的 Secret 注入，不要把 token 直接硬编码进 Deployment。
+
+## 3. 校验
+
+```bash
+kubectl get pods -n gonavi
+kubectl get svc -n gonavi
+kubectl port-forward -n gonavi svc/gonavi-mcp-server 8765:8765
+curl -H "Authorization: Bearer replace-with-a-random-token" http://127.0.0.1:8765/healthz
+```
+
+`/healthz` 返回 `ok` 说明 Pod 已对外提供 HTTP 服务。
+
+## 4. 暴露给远端 Agent
+
+- 集群内使用：直接访问 `http://gonavi-mcp-server.gonavi.svc.cluster.local:8765/mcp`
+- 集群外使用：通过 Ingress / Gateway / 反向代理暴露 `/mcp`
+- 远端 Agent 请求头：`Authorization: Bearer <你的 token>`
+
+## 5. drivers 挂载
+
+当前示例默认只挂载 `connections.json` 与 `daily_secrets.json`。如果保存连接里包含 Dameng、ClickHouse、DuckDB 等依赖 driver agent 的数据源，请在 Deployment 中额外补一个卷，把宿主机或 PVC 中的 `drivers/` 目录挂载到：
+
+```text
+/data/drivers
+```
+
+否则对应连接会因为缺少 driver agent 无法使用。

deploy/k8s/gonavi-mcp-server/base/deployment.yaml

@@ -0,0 +1,89 @@
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: gonavi-mcp-server
+  namespace: gonavi
+  labels:
+    app.kubernetes.io/name: gonavi-mcp-server
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app.kubernetes.io/name: gonavi-mcp-server
+  template:
+    metadata:
+      labels:
+        app.kubernetes.io/name: gonavi-mcp-server
+    spec:
+      securityContext:
+        runAsNonRoot: true
+        runAsUser: 10001
+        runAsGroup: 10001
+        seccompProfile:
+          type: RuntimeDefault
+      containers:
+        - name: gonavi-mcp-server
+          # 如需跟随 dev 分支，可改成 ghcr.io/syngnat/gonavi-mcp-server:dev-latest
+          image: ghcr.io/syngnat/gonavi-mcp-server:latest
+          imagePullPolicy: IfNotPresent
+          args:
+            - http
+          ports:
+            - name: http
+              containerPort: 8765
+              protocol: TCP
+          env:
+            - name: GONAVI_DATA_ROOT
+              value: /data
+            - name: GONAVI_LOG_DIR
+              value: /var/lib/gonavi/logs
+            - name: GONAVI_MCP_HTTP_ADDR
+              value: 0.0.0.0:8765
+            - name: GONAVI_MCP_HTTP_PATH
+              value: /mcp
+            - name: GONAVI_MCP_SCHEMA_ONLY
+              value: "true"
+            - name: GONAVI_MCP_HTTP_TOKEN
+              valueFrom:
+                secretKeyRef:
+                  name: gonavi-mcp-server-data
+                  key: GONAVI_MCP_HTTP_TOKEN
+          volumeMounts:
+            - name: gonavi-data
+              mountPath: /data
+              readOnly: true
+          readinessProbe:
+            httpGet:
+              path: /healthz
+              port: http
+            initialDelaySeconds: 3
+            periodSeconds: 10
+          livenessProbe:
+            httpGet:
+              path: /healthz
+              port: http
+            initialDelaySeconds: 10
+            periodSeconds: 20
+          resources:
+            requests:
+              cpu: 100m
+              memory: 128Mi
+            limits:
+              cpu: 500m
+              memory: 512Mi
+          securityContext:
+            allowPrivilegeEscalation: false
+            capabilities:
+              drop:
+                - ALL
+      volumes:
+        - name: gonavi-data
+          projected:
+            sources:
+              - secret:
+                  name: gonavi-mcp-server-data
+                  items:
+                    - key: connections.json
+                      path: connections.json
+                    - key: daily_secrets.json
+                      path: daily_secrets.json

deploy/k8s/gonavi-mcp-server/base/kustomization.yaml

@@ -0,0 +1,6 @@
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+
+resources:
+  - deployment.yaml
+  - service.yaml

deploy/k8s/gonavi-mcp-server/base/service.yaml

@@ -0,0 +1,15 @@
+apiVersion: v1
+kind: Service
+metadata:
+  name: gonavi-mcp-server
+  namespace: gonavi
+  labels:
+    app.kubernetes.io/name: gonavi-mcp-server
+spec:
+  selector:
+    app.kubernetes.io/name: gonavi-mcp-server
+  ports:
+    - name: http
+      port: 8765
+      targetPort: http
+      protocol: TCP

deploy/k8s/gonavi-mcp-server/kustomization.yaml

@@ -0,0 +1,5 @@
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+
+resources:
+  - base

deploy/k8s/gonavi-mcp-server/overlays/drivers-pvc/kustomization.yaml

@@ -0,0 +1,8 @@
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+
+resources:
+  - ../../base
+
+patches:
+  - path: patch-deployment.yaml

deploy/k8s/gonavi-mcp-server/overlays/drivers-pvc/patch-deployment.yaml

@@ -0,0 +1,18 @@
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: gonavi-mcp-server
+  namespace: gonavi
+spec:
+  template:
+    spec:
+      containers:
+        - name: gonavi-mcp-server
+          volumeMounts:
+            - name: gonavi-drivers
+              mountPath: /data/drivers
+              readOnly: true
+      volumes:
+        - name: gonavi-drivers
+          persistentVolumeClaim:
+            claimName: gonavi-drivers

deploy/k8s/gonavi-mcp-server/overlays/ingress-with-drivers-pvc/ingress.yaml

@@ -0,0 +1,33 @@
+apiVersion: networking.k8s.io/v1
+kind: Ingress
+metadata:
+  name: gonavi-mcp-server
+  namespace: gonavi
+  annotations:
+    nginx.ingress.kubernetes.io/backend-protocol: "HTTP"
+    nginx.ingress.kubernetes.io/proxy-read-timeout: "3600"
+    nginx.ingress.kubernetes.io/proxy-send-timeout: "3600"
+spec:
+  ingressClassName: nginx
+  tls:
+    - hosts:
+        - gonavi-mcp.example.com
+      secretName: gonavi-mcp-server-tls
+  rules:
+    - host: gonavi-mcp.example.com
+      http:
+        paths:
+          - path: /mcp
+            pathType: Prefix
+            backend:
+              service:
+                name: gonavi-mcp-server
+                port:
+                  number: 8765
+          - path: /healthz
+            pathType: Prefix
+            backend:
+              service:
+                name: gonavi-mcp-server
+                port:
+                  number: 8765

deploy/k8s/gonavi-mcp-server/overlays/ingress-with-drivers-pvc/kustomization.yaml

@@ -0,0 +1,9 @@
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+
+resources:
+  - ../../base
+  - ingress.yaml
+
+patches:
+  - path: patch-deployment.yaml

deploy/k8s/gonavi-mcp-server/overlays/ingress-with-drivers-pvc/patch-deployment.yaml

@@ -0,0 +1,18 @@
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: gonavi-mcp-server
+  namespace: gonavi
+spec:
+  template:
+    spec:
+      containers:
+        - name: gonavi-mcp-server
+          volumeMounts:
+            - name: gonavi-drivers
+              mountPath: /data/drivers
+              readOnly: true
+      volumes:
+        - name: gonavi-drivers
+          persistentVolumeClaim:
+            claimName: gonavi-drivers

deploy/k8s/gonavi-mcp-server/overlays/ingress/ingress.yaml

@@ -0,0 +1,33 @@
+apiVersion: networking.k8s.io/v1
+kind: Ingress
+metadata:
+  name: gonavi-mcp-server
+  namespace: gonavi
+  annotations:
+    nginx.ingress.kubernetes.io/backend-protocol: "HTTP"
+    nginx.ingress.kubernetes.io/proxy-read-timeout: "3600"
+    nginx.ingress.kubernetes.io/proxy-send-timeout: "3600"
+spec:
+  ingressClassName: nginx
+  tls:
+    - hosts:
+        - gonavi-mcp.example.com
+      secretName: gonavi-mcp-server-tls
+  rules:
+    - host: gonavi-mcp.example.com
+      http:
+        paths:
+          - path: /mcp
+            pathType: Prefix
+            backend:
+              service:
+                name: gonavi-mcp-server
+                port:
+                  number: 8765
+          - path: /healthz
+            pathType: Prefix
+            backend:
+              service:
+                name: gonavi-mcp-server
+                port:
+                  number: 8765

deploy/k8s/gonavi-mcp-server/overlays/ingress/kustomization.yaml

@@ -0,0 +1,6 @@
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+
+resources:
+  - ../../base
+  - ingress.yaml

deploy/k8s/gonavi-mcp-server/overlays/nas-hostpath/kustomization.yaml

@@ -0,0 +1,8 @@
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+
+resources:
+  - ../../base
+
+patches:
+  - path: patch-deployment.yaml

deploy/k8s/gonavi-mcp-server/overlays/nas-hostpath/patch-deployment.yaml

@@ -0,0 +1,14 @@
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: gonavi-mcp-server
+  namespace: gonavi
+spec:
+  template:
+    spec:
+      volumes:
+        - $patch: replace
+          name: gonavi-data
+          hostPath:
+            path: /volume1/docker/gonavi/data
+            type: Directory

deploy/podman/gonavi-mcp-server/README.md

@@ -0,0 +1,101 @@
+# GoNavi MCP Server Podman 示例
+
+这个目录提供 `gonavi-mcp-server` 的 Podman 原生部署入口，覆盖两类常见场景：
+
+- 直接用 `podman run` 在 Linux 服务器 / NAS 上启动
+- 用 rootless Quadlet + systemd 做常驻服务
+
+目录内容：
+
+- `gonavi-mcp-server.env.example`：给 `podman run` / Quadlet 共用的容器环境变量示例
+- `gonavi-mcp-server.container`：Quadlet 示例
+
+前提仍然一样：宿主机 GoNavi 活动数据目录内至少应包含：
+
+- `connections.json`
+- `daily_secrets.json`
+
+如果目标连接依赖可选 driver agent，还要保证同一数据目录下已有 `drivers/`。
+
+## 1. 直接运行已发布镜像
+
+```bash
+cp deploy/podman/gonavi-mcp-server/gonavi-mcp-server.env.example ./gonavi-mcp-server.env
+```
+
+把 `GONAVI_MCP_HTTP_TOKEN` 改成随机值后运行：
+
+```bash
+podman run -d --name gonavi-mcp-server --replace \
+  -p 8765:8765 \
+  --env-file ./gonavi-mcp-server.env \
+  -v /absolute/path/to/gonavi-data:/data:Z \
+  ghcr.io/syngnat/gonavi-mcp-server:latest http
+```
+
+查看状态：
+
+```bash
+podman ps
+podman logs -f gonavi-mcp-server
+```
+
+如果你的宿主机没有启用 SELinux，可把挂载参数末尾的 `:Z` 去掉；如果启用了 SELinux，建议保留它。
+
+## 2. 本地源码构建镜像
+
+仓库根目录已经提供 `.containerignore`，Podman 会优先读取它来裁剪构建上下文。
+
+```bash
+podman build -f Dockerfile.mcp-server -t localhost/gonavi-mcp-server:local .
+podman run -d --name gonavi-mcp-server --replace \
+  -p 8765:8765 \
+  --env-file ./gonavi-mcp-server.env \
+  -v /absolute/path/to/gonavi-data:/data:Z \
+  localhost/gonavi-mcp-server:local http
+```
+
+## 3. Rootless Quadlet 常驻服务
+
+Podman Quadlet 适合 Linux 服务器 / NAS 上做 rootless 常驻服务。
+
+把文件放到用户级目录：
+
+```bash
+mkdir -p ~/.config/containers/systemd
+cp deploy/podman/gonavi-mcp-server/gonavi-mcp-server.container ~/.config/containers/systemd/
+cp deploy/podman/gonavi-mcp-server/gonavi-mcp-server.env.example ~/.config/containers/systemd/gonavi-mcp-server.env
+```
+
+然后修改两处：
+
+- `~/.config/containers/systemd/gonavi-mcp-server.container` 里的 `Volume=/absolute/path/to/gonavi-data:/data:Z`
+- `~/.config/containers/systemd/gonavi-mcp-server.env` 里的 `GONAVI_MCP_HTTP_TOKEN`
+
+启动服务：
+
+```bash
+systemctl --user daemon-reload
+systemctl --user enable --now gonavi-mcp-server.service
+systemctl --user status gonavi-mcp-server.service
+journalctl --user -u gonavi-mcp-server.service -f
+```
+
+如果你希望用户退出登录后服务仍然保持运行，再执行：
+
+```bash
+loginctl enable-linger "$USER"
+```
+
+Rootless Quadlet 默认搜索路径是 `~/.config/containers/systemd/`；如果你要做系统级 rootful 部署，可改放到 `/etc/containers/systemd/`。
+
+## 4. 关于 Compose
+
+Podman 的 `podman compose` 依赖外部 compose provider。也就是说，是否能直接复用仓库根目录的 `docker-compose.mcp-server.yml`，取决于你的 Podman 环境是否已经安装并配置了对应 provider。
+
+因此，这个仓库对 Podman 的主支持路径是：
+
+- `podman run`
+- Quadlet（推荐长期运行）
+
+如果你的环境已经有可用的 compose provider，再去复用根目录 Compose 文件即可。

deploy/podman/gonavi-mcp-server/gonavi-mcp-server.container

@@ -0,0 +1,22 @@
+[Unit]
+Description=GoNavi MCP Server (rootless Podman)
+Wants=network-online.target
+After=network-online.target
+
+[Container]
+ContainerName=gonavi-mcp-server
+Image=ghcr.io/syngnat/gonavi-mcp-server:latest
+Pull=newer
+EnvironmentFile=./gonavi-mcp-server.env
+# 修改成你的 GoNavi 活动数据目录；SELinux 主机建议保留 :Z
+Volume=/absolute/path/to/gonavi-data:/data:Z
+PublishPort=8765:8765
+Exec=http
+LogDriver=journald
+
+[Service]
+Restart=always
+TimeoutStartSec=900
+
+[Install]
+WantedBy=default.target

deploy/podman/gonavi-mcp-server/gonavi-mcp-server.env.example

@@ -0,0 +1,15 @@
+# 容器内 GoNavi 活动数据根目录。通常不需要修改；Volume= 已把宿主机目录挂到 /data。
+GONAVI_DATA_ROOT=/data
+
+# 日志目录。默认与镜像内目录保持一致。
+GONAVI_LOG_DIR=/var/lib/gonavi/logs
+
+# MCP HTTP 监听地址与路径。
+GONAVI_MCP_HTTP_ADDR=0.0.0.0:8765
+GONAVI_MCP_HTTP_PATH=/mcp
+
+# 远程 MCP 客户端访问时必须携带的 Bearer Token
+GONAVI_MCP_HTTP_TOKEN=replace-with-a-random-token
+
+# true = 只暴露结构查询工具，不注册 execute_sql
+GONAVI_MCP_SCHEMA_ONLY=true

docker-compose.mcp-server.local.yml

@@ -0,0 +1,7 @@
+services:
+  gonavi-mcp-server:
+    build:
+      context: .
+      dockerfile: Dockerfile.mcp-server
+    image: ${GONAVI_MCP_IMAGE_LOCAL:-gonavi-mcp-server:local}
+    pull_policy: never

docker-compose.mcp-server.yml

@@ -0,0 +1,20 @@
+services:
+  gonavi-mcp-server:
+    image: ${GONAVI_MCP_IMAGE:-ghcr.io/syngnat/gonavi-mcp-server:latest}
+    pull_policy: ${GONAVI_MCP_PULL_POLICY:-missing}
+    container_name: gonavi-mcp-server
+    restart: unless-stopped
+    ports:
+      - "${GONAVI_MCP_HTTP_PORT:-8765}:8765"
+    environment:
+      GONAVI_DATA_ROOT: /data
+      GONAVI_LOG_DIR: /var/lib/gonavi/logs
+      GONAVI_MCP_HTTP_ADDR: 0.0.0.0:8765
+      GONAVI_MCP_HTTP_PATH: ${GONAVI_MCP_HTTP_PATH:-/mcp}
+      GONAVI_MCP_HTTP_TOKEN: ${GONAVI_MCP_HTTP_TOKEN}
+      GONAVI_MCP_SCHEMA_ONLY: ${GONAVI_MCP_SCHEMA_ONLY:-true}
+    volumes:
+      - type: bind
+        source: ${GONAVI_HOST_DATA_ROOT}
+        target: /data
+    command: ["http"]

docker-compose.web-server.local.yml

@@ -0,0 +1,7 @@
+services:
+  gonavi-web-server:
+    build:
+      context: .
+      dockerfile: Dockerfile.web-server
+    image: ${GONAVI_WEB_IMAGE_LOCAL:-gonavi-web-server:local}
+    pull_policy: never

docker-compose.web-server.yml

@@ -0,0 +1,24 @@
+services:
+  gonavi-web-server:
+    image: ${GONAVI_WEB_IMAGE:-ghcr.io/syngnat/gonavi-web-server:latest}
+    pull_policy: ${GONAVI_WEB_PULL_POLICY:-missing}
+    container_name: gonavi-web-server
+    restart: unless-stopped
+    ports:
+      - "${GONAVI_WEB_HTTP_PORT:-34116}:34116"
+    environment:
+      GONAVI_DATA_ROOT: /data
+      GONAVI_LOG_DIR: /var/lib/gonavi/logs
+      GONAVI_WEB_ADDR: 0.0.0.0:34116
+      GONAVI_WEB_PASSWORD: ${GONAVI_WEB_PASSWORD:-}
+    volumes:
+      - type: bind
+        source: ${GONAVI_HOST_DATA_ROOT}
+        target: /data
+    healthcheck:
+      test: ["CMD", "curl", "-fsS", "http://127.0.0.1:34116/__gonavi/healthz"]
+      interval: 15s
+      timeout: 5s
+      retries: 5
+      start_period: 20s
+    command: ["web-server"]

docker.mcp-server.env.example

@@ -0,0 +1,20 @@
+# 宿主机 GoNavi 活动数据目录，目录内至少应包含 connections.json 与 daily_secrets.json
+GONAVI_HOST_DATA_ROOT=/absolute/path/to/gonavi-data
+
+# 预构建镜像地址。稳定版通常使用 latest，跟随 dev 分支可改成 ghcr.io/syngnat/gonavi-mcp-server:dev-latest
+GONAVI_MCP_IMAGE=ghcr.io/syngnat/gonavi-mcp-server:latest
+
+# 预构建镜像拉取策略：always / missing / never
+GONAVI_MCP_PULL_POLICY=missing
+
+# 远程 MCP 客户端访问时必须携带的 Bearer Token
+GONAVI_MCP_HTTP_TOKEN=replace-with-a-random-token
+
+# 宿主机暴露端口
+GONAVI_MCP_HTTP_PORT=8765
+
+# MCP HTTP 路径
+GONAVI_MCP_HTTP_PATH=/mcp
+
+# true = 只暴露结构查询工具，不注册 execute_sql
+GONAVI_MCP_SCHEMA_ONLY=true

docker.web-server.env.example

@@ -0,0 +1,19 @@
+# 宿主机 GoNavi 活动数据目录。
+# 建议至少包含：connections.json、daily_secrets.json；
+# 如需可选驱动代理，一并挂载 drivers/。
+# Web 认证状态会写入 web_auth.json；未设置环境密码时首次访问 /setup 初始化。
+GONAVI_HOST_DATA_ROOT=/absolute/path/to/gonavi-data
+
+# 预构建镜像地址。稳定版通常使用 latest，跟随 dev 分支可改成 ghcr.io/syngnat/gonavi-web-server:dev-latest
+GONAVI_WEB_IMAGE=ghcr.io/syngnat/gonavi-web-server:latest
+
+# 预构建镜像拉取策略：always / missing / never
+GONAVI_WEB_PULL_POLICY=missing
+
+# 宿主机暴露端口（映射到容器 34116）
+GONAVI_WEB_HTTP_PORT=34116
+
+# Web 管理员密码（至少 6 位）。留空时首次访问 /setup 初始化；公网部署请使用更强密码。
+# 设置或修改后请执行 docker compose up -d --force-recreate；请限制本文件的读取权限。
+# 新部署如需启用 2FA，请先留空并通过 /setup 初始化，再设置为同一密码并重新创建容器。
+GONAVI_WEB_PASSWORD=

docs/driver-manifest.json

@@ -7,6 +7,12 @@
       "checksumPolicy": "off",
       "downloadUrl": "builtin://activate/mariadb"
     },
+    "oceanbase": {
+      "engine": "go",
+      "version": "1.9.3",
+      "checksumPolicy": "off",
+      "downloadUrl": "builtin://activate/oceanbase"
+    },
     "doris": {
       "engine": "go",
       "version": "1.9.3",
@@ -61,6 +67,12 @@
       "checksumPolicy": "off",
       "downloadUrl": "builtin://activate/vastbase"
     },
+    "opengauss": {
+      "engine": "go",
+      "version": "1.11.1",
+      "checksumPolicy": "off",
+      "downloadUrl": "builtin://activate/opengauss"
+    },
     "mongodb": {
       "engine": "go",
       "version": "2.5.0",
@@ -84,6 +96,12 @@
       "version": "1.11.1",
       "checksumPolicy": "off",
       "downloadUrl": "builtin://activate/postgres"
+    },
+    "elasticsearch": {
+      "engine": "go",
+      "version": "8.19.0",
+      "checksumPolicy": "off",
+      "downloadUrl": "builtin://activate/elasticsearch"
     }
   }
 }

docs/issues/2026-04-11-issue-backlog-tracking.md

@@ -1,111 +0,0 @@
-# 2026-04-11 Issue Backlog Tracking
-
-## Scope
-
-- 分支：`codex/issue-242-data-root`
-- 策略：按 GitHub issue 创建时间从早到晚逐条处理
-- 提交要求：每条 issue 单独本地提交，提交信息使用 `Fixes #<issue>`
-
-## Progress
-
-| Issue | Title | Status | Commit |
-| --- | --- | --- | --- |
-| #242 | 希望有自定义数据存储位置功能 | Fixed | `1f617f9` |
-| #287 | 建议补充 Sql Server 数据库图标 | Fixed | `60b63d7` |
-| #305 | 金仓数据库设计表新增字段保存失败 | Fixed | `f696f52` |
-| #306 | 驱动下载 | Fixed | `8297829` |
-| #308 | clickhouse 获取数据库列表失败 | Fixed | `5d86ee7` |
-| #310 | 选择库后，右侧行显示各个表 | Fixed | `808c773` |
-| #311 | WIN 系统的执行 500 多条 insert 语句要几分钟 | Fixed | `83fe3d4` |
-| #315 | 窗体内缩放异常 | Fixed | `5038ae5` |
-| #316 | 人大金仓数据库驱动版本过低 | Fixed | `aa1bb5b` |
-| #317 | 驱动管理增加导入 jar 功能 | Blocked | - |
-| #318 | mysql,bit 列，修改成 1 失败 | Fixed | `89d79ff` |
-| #319 | 关于运行外部 sql 文件的一些建议 | Deferred | - |
-| #320 | 无法连接达梦数据库 | Fixed | `1c2377b` |
-| #322 | 【拖选复制】希望添加 查询结果表格可以拖选复制，效果就如操作excel表格的选择复制一样 | Fixed | Pending |
-| #325 | 有没有考虑对数据库的驱动版本进行选择或者自定义？ | Fixed | `af5e842` |
-| #327 | SHOW DATABASES 报错 | Fixed | `fb500ee` |
-| #328 | [Bug] 安装更新失败 | Fixed | `426ef3b` |
-| #329 | 如果调整了左侧导航栏的宽度后，建议左侧导航栏内增加横向滚动查看 | Fixed | `fcade0f` |
-| #330 | 建议在查询结果表格中增加自适应内容列宽的功能 | Fixed | `632e57e` |
-| #331 | 重复连接 DB，一分钟重试了 60 多次 | Fixed | `ca76440` |
-| #351 | 为什么没有截断和清空表的功能呀？ | Fixed | Pending |
-
-## Notes
-
-### #317
-
-- 当前驱动管理只支持内置 Go 驱动和可选 Go 驱动代理包。
-- 仓库内不存在 JDBC/JAR 装载、Java 运行时探测、classpath 管理或桥接执行链路。
-- 在现有架构下直接增加 “导入 jar” 入口会形成假功能，因此暂记为架构阻塞，不做伪实现。
-
-### #318
-
-- 根因：MySQL 写入归一化只覆盖时间列，`bit` 列提交时会把前端传来的 `"1"`/`"0"` 原样透传给驱动。
-- 处理：为 MySQL `bit` 列补充写入值归一化，将常见文本/布尔/数值输入转换为驱动可接受的 `[]byte`。
-- 验证：补充 `internal/db/mysql_value_test.go` 回归测试，覆盖 `bit(1)` 的 insert/update 写入路径。
-
-### #319
-
-- 现有应用已支持“运行外部 SQL 文件”，但 issue 诉求包含目录树、目录加载、双击文件打开等整组工作区能力。
-- 该项已超出单点缺陷修复范围，暂按功能增强项顺延，避免在逐条修 bug 流程中引入大范围 UI/状态管理重构。
-
-### #320
-
-- 达梦当前走可选 Go 驱动代理安装链路，不支持 JAR 导入属于既有架构边界。
-- 根因：驱动 release 资产缓存把 `GoNavi-DriverAgents.zip` 里的 bundle 条目也混进了“顶层已发布 asset”集合，导致安装链路误以为存在单独的 `dameng-driver-agent-*.exe` 下载地址。
-- 处理：缓存层区分真实 release 顶层 asset 与 bundle index 条目，安装 URL 解析仅在真实顶层 asset 存在时才走直链；bundle-only 驱动改为直接进入总包提取回退，不再先卡在 20% 试无效 URL。
-- 验证：补充 `internal/app/methods_driver_version_test.go` 回归测试，覆盖 bundle-only 达梦驱动跳过伪直链，并回归 Mongo 历史版本与本地导入链路。
-
-### #327
-
-- 根因：低权限 MySQL 账号执行 `SHOW DATABASES` 会直接报错，当前实现没有回退路径。
-- 处理：为数据库列表查询增加 `SELECT DATABASE()` 回退，仅保留当前连接库时也能正常展示。
-- 验证：补充 `internal/db/mysql_metadata_test.go` 回归测试，覆盖有权限、多库和低权限回退场景。
-
-### #328
-
-- 根因：Windows 更新脚本在批处理执行、错误码读取和重启命令上不够稳，`cmd /C start`、LF 行尾和块内 `%ERRORLEVEL%` 在实际环境下容易引发安装失败。
-- 处理：更新脚本统一输出为 CRLF，块内错误码改为延迟展开，旧文件回退路径统一为 `TARGET_OLD`，并将脚本启动方式收敛为 `cmd.exe /D /C call <script>`。
-- 验证：补充 `internal/app/methods_update_windows_script_test.go`，覆盖批处理语法、Win10 回退路径、CRLF 行尾、延迟展开和启动命令构造。
-
-### #325
-
-- 根因：TDengine 的版本列表虽然支持下拉选择，但后端在抓取与缓存 Go 模块版本时只保留最近 5 个版本，导致 `3.5.x / 3.3.x / 3.0.x` 这类旧版根本不会进入选择列表。
-- 处理：放宽 TDengine 的历史版本窗口，并补充离线 fallback 版本矩阵；同时扩大模块版本缓存上限，确保旧版不会在抓取阶段就被截断。
-- 验证：补充 `internal/app/methods_driver_version_test.go` 回归测试，覆盖缓存命中与 fallback 两条路径，并回归 Mongo 版本约束逻辑。
-
-### #329
-
-- 根因：侧边栏连接树被全局 Tree 样式固定为 `width: 100%`，标题同时启用了省略截断，导致缩窄侧栏后长节点无法形成横向溢出。
-- 处理：为 Sidebar 树增加专用横向滚动容器，并在 Sidebar 作用域内覆写 Tree 宽度与标题截断规则，让节点宽度随内容扩展且保留最小占满。
-- 验证：执行 `frontend` 下 `npm run build`，确认 TS/CSS 改动编译通过且仅作用于 Sidebar 树。
-
-### #331
-
-- 根因：连接失败时存在双层重试叠加。`DBGetDatabases / DBGetTables / DBQuery` 在缓存失效后本来就会主动重建连接一次，而 `connectDatabaseWithStartupRetry` 在稳定期仍会额外放行一次瞬时错误自动重试，导致一次后台探测会被放大成多次真实建连。
-- 处理：将连接自动重试范围收敛到应用启动保护窗口内；稳定期下所有连接探测与重建都只执行一次，避免后台挂起场景持续放大失败流量。
-- 验证：补充并更新 `internal/app/app_startup_connect_retry_test.go`，覆盖稳定期瞬时失败不重试、不再输出重试提示，以及启动期仍保留完整重试预算。
-
-### #330
-
-- 根因：查询结果表格已经支持拖拽调整列宽，但 resize handle 没有提供双击自适应逻辑，导致用户只能靠手工拖拽慢慢试宽度。
-- 处理：为 `DataGrid` 的列宽拖拽手柄增加双击入口，按当前表头与已加载结果集内容估算目标宽度，并直接复用现有 `columnWidths` 状态更新布局。
-- 验证：新增 `frontend/src/components/dataGridAutoWidth.test.ts` 覆盖列宽估算规则，并执行 `frontend` 下 `npm run build` 确认 TS 与打包通过。
-
-### #322
-
-- 根因：`DataGrid` 已经具备拖选单元格和选区状态维护能力，但当前复制能力只支持把同一行选中的列值暂存为内部 patch，用于“粘贴到选中行”，没有把矩形选区真正导出到系统剪贴板。
-- 处理：新增选区复制 helper，将矩形选区按当前可见行列顺序导出为制表符文本；同时补上工具栏“复制选区”按钮和 `Ctrl/Cmd+C` 快捷键，让拖选后的复制行为更接近 Excel。
-- 验证：新增 `frontend/src/components/dataGridSelectionCopy.test.ts` 覆盖选区排序与剪贴板文本规整规则，并执行 `frontend` 下 `npm run build` 确认功能接线通过。
-
-### #351
-
-- 根因：后端已有批量清空表能力，但前端单表危险操作菜单只暴露了“删除表”，没有把“截断表 / 清空表”作为显式入口提供给用户；同时批量“清空”动作底层语义也混用了 `TRUNCATE/DELETE`。
-- 处理：后端将“截断表”和“清空表”拆分为显式能力，统一通过 helper 生成多数据库 SQL；前端为 Sidebar 和 TableOverview 的表菜单补上两个危险操作入口，并仅在明确支持 `TRUNCATE TABLE` 的数据库类型上显示“截断表”。
-- 验证：新增 `internal/app/methods_file_clear_test.go` 与 `frontend/src/components/tableDataDangerActions.test.ts`，并执行 `go test ./...`、`frontend` 下 `npm run build` 确认全量通过。
-
-## Next
-
-- 继续处理下一个最早且可直接落地的开放 issue。

docs/superpowers/specs/2026-07-20-tab-close-shortcut-design.md

@@ -0,0 +1,355 @@
+# Cmd/Ctrl+W 标签关闭快捷键设计
+
+- 日期：2026-07-20
+- 状态：已确认，待实施
+- 适用范围：GoNavi 主窗口的工作区标签和 SQL 查询结果区标签
+
+## 1. 背景
+
+GoNavi 当前没有统一的 `Cmd+W` / `Ctrl+W` 应用内关闭语义。工作区标签由
+`TabManager` 管理，查询结果标签由每个 `QueryEditor` 的本地状态管理，两套关闭
+流程拥有不同的保护规则。若分别注册全局键盘监听，同一次按键可能同时关闭结果
+标签和工作区标签。
+
+本设计增加一个可配置动作 `closeActiveTab`，由唯一的全局入口根据用户最后一次
+明确交互的区域，将关闭请求路由到结果区或工作区。
+
+## 2. 目标
+
+1. macOS 默认使用 `Meta+W`，Windows/Linux 默认使用 `Ctrl+W`。
+2. 快捷键在设置中心可修改、启用或禁用。
+3. 同一次按键最多执行一个关闭动作，结果区与工作区之间不允许穿透。
+4. 复用现有关闭流程，保留未保存 SQL、运行中导入任务等保护。
+5. 结果区日志标签保持常驻；日志标签活跃时，快捷键隐藏整个结果区。
+6. 结果区被快捷键隐藏后，连续按键不得继续关闭工作区标签。
+
+## 3. 非目标
+
+1. 不新增“分别关闭结果标签”和“分别关闭工作区标签”两个可配置动作。
+2. 不改变鼠标关闭按钮、中键关闭或右键批量关闭的产品语义。
+3. 不关闭或清空 SQL 日志数据。
+4. 不改变后台导出、同步任务在工作区标签关闭后的运行方式。
+5. 不统一重构所有历史浮动窗口的关闭入口。
+6. 不让主窗口快捷键关闭已经拆出的独立窗口标签或独立结果窗口。
+
+## 4. 方案选择
+
+### 4.1 采用方案：单一全局路由器
+
+`App` 保持唯一的全局 `keydown` capture 监听入口，维护最后一次明确交互区域，
+并向目标组件派发单一、明确的关闭命令。
+
+采用该方案的原因：
+
+- 键盘事件只匹配和消费一次，天然避免双重关闭。
+- `TabManager` 和 `QueryEditor` 继续拥有各自的状态与保护逻辑。
+- 路由状态可以独立测试，不需要把查询结果状态上移到全局 store。
+- 后续自定义快捷键仍复用现有快捷键设置与冲突检测体系。
+
+### 4.2 未采用方案
+
+- 分区独立监听：工作区和结果区分别监听 `window.keydown`。该方案存在监听顺序、
+  冒泡阻断和同一 `window` 多监听器重复执行问题。
+- 完全依赖 DOM 焦点：Monaco、DataGrid、Ant Design Portal 和 `body` 级事件目标会
+  让焦点不足以可靠表达用户的区域意图。
+
+## 5. 快捷键配置
+
+### 5.1 动作定义
+
+新增动作 `closeActiveTab`，纳入：
+
+- `ShortcutAction`
+- `SHORTCUT_ACTION_ORDER`
+- `SHORTCUT_ACTION_META`
+- `DEFAULT_SHORTCUT_OPTIONS`
+- 快捷键设置界面和全部语言目录
+
+动作允许在 Monaco、输入框和 DataGrid 等可编辑目标中触发，因为焦点位于编辑器
+时仍应能关闭当前工作区标签。
+
+默认绑定：
+
+| 平台 | 组合键 | 默认状态 |
+| --- | --- | --- |
+| macOS | `Meta+W` | 启用 |
+| Windows/Linux | `Ctrl+W` | 启用 |
+
+GoNavi 正式接管该组合键，因此删除现有“浏览器关闭标签页”的 `Ctrl+W` 保留项；
+其他浏览器、Monaco 和 DataGrid 保留项不变。
+
+### 5.2 旧配置迁移
+
+旧持久化配置中不存在 `closeActiveTab` 时，按平台分别迁移：
+
+1. 若该平台没有任何已启用动作占用新默认组合键，补入启用的新动作。
+2. 若已有动作占用 `Meta+W` 或 `Ctrl+W`，保留原动作及绑定，补入组合键相同但
+   `enabled: false` 的新动作。
+3. 用户可在快捷键设置中修改冲突绑定并重新启用新动作。
+4. “恢复默认值”和全新安装始终得到启用的默认绑定。
+
+迁移只处理缺少新动作的旧配置，不覆盖用户已经保存的 `closeActiveTab` 设置。
+
+禁用动作或把动作改绑到其他组合键后，默认 `Meta+W` / `Ctrl+W` 不再执行标签
+关闭，但主窗口仍必须消费该平台原生关闭组合键，防止 WebView 把它解释为关闭应用
+窗口或浏览器标签。
+
+## 6. 路由状态模型
+
+全局路由器维护 `CloseShortcutScope`：
+
+```ts
+type CloseShortcutScope = 'workspace' | 'result' | 'blocked';
+```
+
+初始状态为 `workspace`。
+
+| 当前/触发条件 | 下一状态 | 含义 |
+| --- | --- | --- |
+| 用户点击或聚焦结果区 | `result` | 关闭请求只发送给当前查询结果区 |
+| 用户点击或聚焦编辑器、工作区标签栏或侧边栏 | `workspace` | 关闭请求只发送给主工作区 |
+| 快捷键在日志标签上隐藏结果区 | `blocked` | 后续重复按键只消费，不关闭任何标签 |
+| `blocked` 后用户明确交互工作区 | `workspace` | 允许重新关闭工作区标签 |
+| `blocked` 后用户明确交互重新显示的结果区 | `result` | 允许关闭结果标签或再次隐藏结果区 |
+| 用户点击或聚焦独立结果窗口 | `blocked` | 独立窗口交互不得沿用后台工作区归属 |
+
+SQL 执行后程序化展示结果、程序化切换结果标签、store 激活标签等行为不得修改
+该状态。只有真实的 `pointerdown` 或 `focusin` 才能改变区域归属。
+
+结果区根节点增加 `data-gonavi-close-shortcut-scope="result"`。路由器在 document
+capture 阶段监听 `pointerdown` 和 `focusin`，通过该标记识别结果区；编辑器、
+工作区标签栏和侧边栏归入工作区。
+
+交互浮层与独立结果窗口使用稳定的
+`data-gonavi-close-shortcut-guard="true"` 标记或统一 guard class。guard 包含当前可见
+的模态框、抽屉、Dropdown、上下文菜单、Select/Picker 弹层、自建交互 Portal 和
+`.gn-detached-result-window`。标记仅在浮层打开时处于 active 状态；若组件会保留
+隐藏 DOM，公共 helper 还必须检查元素的可见性。Tooltip、拖拽预览等不可获得输入
+焦点的纯展示 Portal 不属于 guard。
+
+普通浮层 guard 内的 `pointerdown` 和 `focusin` 不改变后台区域归属。关闭快捷键
+来自 guard 内部时，只消费事件，不向工作区或结果区派发命令。
+
+独立结果窗口是例外：其根节点同时标记
+`data-gonavi-close-shortcut-scope="blocked"`。可信的 `pointerdown` 或 `focusin`
+发生在窗口内部时，立即把路由 ref 写为 `blocked`。这覆盖标题栏拖动等不会夺取
+后台 Monaco 焦点的交互；之后即使 `keydown.target` 仍是 Monaco，也不得关闭主
+工作区。只有用户再次明确交互主工作区或主结果区才恢复对应归属。
+
+会遮挡后台交互的浮层另加
+`data-gonavi-close-shortcut-blocks-background="true"`；只要此标记的节点当前可见，
+即使键盘事件目标落在 `body`，也只消费、不关闭后台标签。模态框、抽屉、交互
+Dropdown/上下文菜单、Select/Picker 弹层使用该标记。独立结果窗口只使用普通
+guard，不使用 background blocker，避免窗口存在时永久禁用主工作区快捷键。
+
+## 7. 键盘事件流
+
+```text
+全局 keydown capture
+  -> 不受 IME 过滤的底层组合键解析
+  -> 是否命中平台原生关闭键，或已启用的 closeActiveTab 绑定
+  -> 快捷键录制器优先接管
+  -> 命中平台原生关闭键时无条件 preventDefault
+  -> IME/guard 命中时只消费，不派发
+  -> 解析当前组合键的已启用动作 owner
+       其他动作 -> 交给原动作处理一次
+       closeActiveTab -> 读取 CloseShortcutScope 并路由
+       无 owner 且为平台原生关闭键 -> 消费为 no-op
+```
+
+事件处理约束：
+
+1. `App` 是主窗口唯一的全局关闭快捷键入口。
+2. 增加一个只做键位与修饰键比较、不会因 IME 状态返回 false 的底层 matcher。
+   它仅用于判断事件是否需要被应用接管；正常动作执行仍使用现有
+   `isShortcutMatch` 语义。
+3. 路由器分别计算“平台原生关闭组合键”和“当前已启用动作绑定”的底层匹配，
+   同时按 `SHORTCUT_ACTION_ORDER` 解析当前组合键的已启用 owner。快捷键设置继续
+   保证同一平台不会新增多个启用 owner；遇到历史重复数据时按现有动作顺序只取
+   第一个。
+4. 快捷键录制器拥有优先权。录制期间全局路由器直接退出，由录制器负责
+   `preventDefault` 和保存绑定，不执行关闭动作。
+5. 除录制器分支外，底层 matcher 一旦命中平台原生关闭组合键，必须立即
+   `preventDefault`，再判断 owner 和当前上下文。绑定 owner 存在但因可编辑目标、
+   当前标签类型或组件未挂载而无法执行时，动作可以 no-op，WebView 默认关闭仍然
+   必须被抑制。
+6. IME composing、全局 composition 状态或 keyCode/which 229 命中时，底层 matcher
+   仍能识别组合键并消费，但不得派发关闭。
+7. 事件目标位于 guard 内，或存在可见的 background blocker 时，只消费、不关闭
+   后台标签。
+8. 若 owner 是 `closeActiveTab`，才进入本设计的工作区/结果区路由。若 owner 是
+   其他历史动作，关闭路由不得抢占或改成 no-op：全局动作继续由 App switch 执行，
+   查询编辑器动作继续交给其现有 owner，并且整条链路只执行该动作一次。
+9. 只有平台原生关闭键没有任何已启用 owner 时，才由保护分支消费为 no-op。
+10. 关闭路由、IME/guard 保护和无 owner 的平台 no-op 在 `preventDefault` 后使用
+   `stopImmediatePropagation`，避免 WebView 或同一 `window` 上的其他监听器再次
+   处理。交给其他 owner 的事件不得在 owner 执行前被关闭路由
+   `stopImmediatePropagation`，但第 5 条的 `preventDefault` 仍已生效。
+11. 一次事件只允许派发一个目标命令，不允许在目标无效时回退到另一区域。
+12. `document.body`、`document.documentElement` 等文档级目标按已记录状态路由。
+13. `closeActiveTab` 禁用或改绑，且没有其他已启用 owner 时，平台原生
+    `Meta+W` / `Ctrl+W` 仍被消费为 no-op；自定义绑定只有在动作启用时才被接管。
+14. 若真机验证发现 WebView 不向前端交付 `Cmd/Ctrl+W`，才增加 Wails 原生事件
+   fallback；fallback 必须汇入同一路由器并具备单次事件去重，不能形成第二套关闭
+   流程。
+
+## 8. 工作区关闭契约
+
+工作区命令由 `TabManager` 处理，目标必须是 `dockedActiveTabId`，不得使用全局
+`activeTabId`。不存在主窗口活动标签时，命令为 no-op。
+
+关闭必须复用：
+
+```ts
+closeTabsWithSQLFilePrompt(
+  [dockedActiveTabId],
+  () => closeTab(dockedActiveTabId),
+);
+```
+
+由此保留：
+
+- 外部 SQL 文件未保存时的保存、丢弃、取消确认。
+- 外部 SQL 文件被移动或删除时的确认。
+- 防止重复打开关闭确认。
+- 运行中的 `data-import` 工作台关闭保护。
+- store 已有的关闭后活动标签选择和关联资源清理。
+
+`table-export` 与 `data-sync` 的任务状态独立于标签组件，仍允许关闭工作区标签并
+在后台继续运行。
+
+## 9. 结果区关闭契约
+
+结果区命令只发送给主窗口当前活动的 `QueryEditor`，由它读取本地
+`activeResultKey` 和 `resultSets`。组件提取一个共享的纯函数
+`resolveEffectiveActiveResultKey`，供结果区渲染和快捷键命令共同使用，不能一方
+读取原始 key、另一方使用视觉回退 key。
+
+在支持嵌入 SQL 日志标签的结果区中，日志标签只要结果区可见就无条件存在，日志
+数量为 0 时也显示；其 key 统一使用 `QUERY_EDITOR_SQL_LOG_TAB_KEY`。
+
+具体行为：
+
+1. 当前键对应真实结果标签时，调用现有 `handleCloseResult`。
+2. 关闭后由现有逻辑选择相邻结果标签，不在路由器中重复计算。
+3. 关闭最后一个真实结果标签后，活动状态明确切到日志 key，结果区继续显示常驻
+   日志标签；即使历史状态中原始 key 为空，共享 resolver 也必须得到同一日志 key。
+4. 当前键为日志标签时，不删除日志；隐藏整个结果区，并向路由器回报
+   `hidden`，使路由状态进入 `blocked`。
+5. 当前键缺失、过期或不属于真实结果与日志时，消费请求并回报 `ignored`，不得
+   回退关闭工作区。
+6. 结果区已经隐藏时，结果命令为 no-op，仍不得穿透到工作区。
+
+结果命令需要一个明确的完成回报 `closed | hidden | ignored`。命令派发和回报必须
+在当前 `keydown` 调用栈内同步完成，不使用 Promise 或等待 React render。可通过
+同步 `dispatchEvent` 的可变 request detail 或等价的同步命令注册表返回 outcome。
+
+路由状态以 ref/原子值为准，键盘监听不得读取可能滞后的 React state。收到
+`hidden` 后，必须在监听器返回前写入 `scopeRef.current = 'blocked'`；`closed` 和
+`ignored` 保持 `result`。因此即使同一 task 内连续派发两个 `keydown`，第二次也会
+读到 `blocked`。
+
+结果命令同样读取 `resultSetsRef` 与 `activeResultKeyRef`。关闭动作在提交 React
+state 更新的同时同步写入这两个 ref，使同一 task 内的下一次命令能看到相邻结果
+或日志 key，而不是重复处理已经关闭的结果。
+
+独立结果窗口不向主窗口发送工作区关闭命令。主窗口路由器也不控制独立结果窗口
+的生命周期。
+
+## 10. 错误与竞态处理
+
+- 快速重复按键：工作区沿用关闭确认的互斥保护；结果区每次根据最新本地状态
+  处理。日志隐藏后立即切换为 `blocked`。
+- 结果标签关闭与查询完成并发：以命令处理时的最新 `activeResultKey` 为准；无效
+  key 返回 `ignored`。
+- 活动工作区标签在事件间切换：`TabManager` 在命令处理时读取最新
+  `dockedActiveTabId`。
+- 组件卸载：命令没有有效接收者时 no-op，不向另一区域补发。
+- 自定义绑定冲突：继续使用现有冲突提示；运行时不同时执行两个动作。
+
+## 11. 测试设计
+
+### 11.1 快捷键工具测试
+
+- 新动作默认绑定、动作顺序、元信息和平台显示。
+- 新动作允许在可编辑目标触发。
+- `Ctrl+W` 不再报告浏览器保留冲突。
+- 自定义绑定、禁用和恢复默认值。
+- 动作禁用或改绑后，平台原生关闭组合键仍被消费但不关闭标签或窗口。
+- 旧配置无冲突时自动启用新动作。
+- 旧配置占用默认组合键时保留旧动作并禁用新动作，且按平台隔离。
+- 迁移后按原生关闭组合键仍只执行原动作一次，不执行关闭动作，WebView 也不关闭。
+- 历史 owner 因可编辑目标、非查询标签或组件未挂载而无法执行时，不执行任何动作，
+  但仍阻止 WebView 原生关闭。
+- 所有语言包含新动作的 label/description。
+
+### 11.2 路由器测试
+
+- 初始状态关闭工作区，不触发结果区。
+- 明确点击结果区后只关闭结果标签。
+- 点击 Monaco、工作区标签栏或侧边栏后只关闭工作区标签。
+- SQL 执行后程序化激活结果不抢占归属。
+- 日志标签隐藏结果区并进入 `blocked`。
+- `blocked` 状态连续按键不关闭工作区；明确交互工作区后才恢复。
+- 无效结果状态只消费，不穿透工作区。
+- `body` 和 `documentElement` 目标使用最后明确区域。
+- 快捷键录制期间不执行关闭。
+- IME composing / keyCode 229 下，底层 matcher 仍消费默认或自定义关闭组合键，但
+  不执行关闭。
+- 模态框、抽屉、下拉菜单和 Portal 活跃时不关闭后台标签。
+- Tooltip 和拖拽预览等纯展示 Portal 不触发 guard。
+- 保持后台 Monaco 焦点，初始状态为 `workspace` 时点击不可聚焦的独立结果窗口
+  标题栏，再按快捷键也不得关闭主工作区。
+- 独立结果窗口仅仅存在时，不阻止主工作区内正常使用关闭快捷键。
+- 可见 background blocker 存在且事件目标为 `body` 时也不得关闭后台标签。
+- 同一个键盘事件最多派发一个关闭命令。
+- `hidden` 回报后不等待重渲染，立即连续派发第二个事件仍保持 blocked。
+
+### 11.3 工作区集成测试
+
+- 使用 `dockedActiveTabId`，独立窗口处于全局 active 时也不关错标签。
+- 外部 SQL 脏文件保留保存/丢弃/取消流程。
+- 外部 SQL 文件丢失确认仍生效。
+- 运行中数据导入工作台无法被快捷键关闭。
+- 导出、同步工作台标签允许关闭，后台任务继续。
+- 没有 docked 标签时 no-op。
+
+### 11.4 结果区集成测试
+
+- 关闭真实结果标签并正确选择相邻标签。
+- 关闭最后一个真实结果后显示日志标签。
+- 关闭最后一个真实结果后，命令和渲染共同解析为日志 key；下一次快捷键隐藏
+  结果区。
+- 日志标签不会被删除，结果区整体隐藏。
+- 计数请求等现有清理逻辑仍由 `handleCloseResult` 执行。
+- 结果区隐藏、active key 过期、组件卸载时均不关闭工作区。
+- 独立结果窗口不会把命令路由回主工作区。
+
+### 11.5 真机验收
+
+- macOS 触摸板、Monaco、DataGrid 和普通面板焦点下验证 `Cmd+W`。
+- Windows/Linux 对应验证 `Ctrl+W`。
+- 验证 WebView 不执行原生窗口或浏览器标签关闭。
+- 验证自定义组合键、完全禁用状态及 IME 组合输入；改绑或禁用后默认平台关闭键
+  仍是应用内 no-op。
+
+## 12. 验收标准
+
+1. 默认快捷键、自定义和禁用均按平台生效。
+2. 结果区、工作区和 `blocked` 三种状态的路由符合本设计。
+3. 一次按键不会同时关闭结果标签和工作区标签。
+4. 日志标签始终保留；日志活跃时隐藏的是整个结果区。
+5. 隐藏结果区后连续按键不会误关工作区标签。
+6. 现有 SQL 文件和数据导入保护没有被绕过。
+7. 旧用户配置不会因升级被静默覆盖或产生双动作。
+8. 自动化测试和 macOS/Windows 真机验证通过。
+
+## 13. 预计影响文件
+
+- `frontend/src/utils/shortcuts.ts`
+- `frontend/src/App.tsx`
+- `frontend/src/components/TabManager.tsx`
+- `frontend/src/components/QueryEditor.tsx`
+- `frontend/src/components/QueryEditorResultsPanel.tsx`
+- `frontend/src/i18n/catalog.ts` 及目录完整性测试
+- 快捷键、App、TabManager、QueryEditor 相关测试文件

docs/需求追踪/需求进度追踪-Oracle对象跳转与存储过程修改执行-20260625.md

@@ -0,0 +1,45 @@
+# 需求进度追踪 - Oracle对象跳转与存储过程修改执行
+
+## 1. 需求摘要
+- 需求名称：Oracle对象跳转与存储过程修改执行
+- 提出日期：2026-06-25
+- 负责人：Codex
+- 目标：SQL编辑器支持 Oracle 序列、存储包 Ctrl/Cmd 点击跳转；对象编辑执行 Oracle 存储过程时不再生成非法第二条语句。
+- 非目标：不调整 Oracle 连接驱动、不改数据库 schema、不重构侧栏对象树。
+
+## 2. 范围与验收
+- 范围：QueryEditor 对象元数据、hover/跳转逻辑、DefinitionViewer 对象编辑 SQL 生成、相关 i18n 和回归测试。
+- 验收标准：序列/存储包在 SQL 编辑器可出现链接提示并打开定义页；带 SQLPlus `/` 的 Oracle PL/SQL 编辑 SQL 不生成 `/;`，执行时保留完整定义交给后端拆分。
+- 依赖与约束：复用现有侧栏 sequence/package tab 类型；不混入 `frontend/wailsjs/go/models.ts` 既有未提交改动。
+
+## 3. 里程碑与进度
+- [x] 阶段 1（需求澄清）：确认序列/存储包侧栏已可打开，但 SQL 编辑器跳转缺失；存储过程修改仍报 ORA-00900。
+- [x] 阶段 2（影响分析）：影响前端 QueryEditor、DefinitionViewer、i18n、测试；后端拆分已有基础保护。
+- [x] 阶段 3（方案设计）：补齐元数据与跳转类型；对象编辑 SQL 保留 SQLPlus `/` 语义。
+- [x] 阶段 4（实施计划）：先补导航闭环，再修 PL/SQL 生成/执行，最后跑定向测试。
+- [x] 阶段 5（实现与自检）：已完成定向测试、QueryEditor 全文件测试、前端 build、后端 Oracle 拆分测试。
+- [ ] 阶段 6（评审与交付）：待提交推送。
+- [ ] 阶段 7（发布与观察）：发布后验证 Oracle 对象编辑与 SQL 编辑器跳转。
+
+## 4. 变更清单
+- 已完成：补齐 QueryEditor sequence/package 元数据、hover、点击打开定义页；修复对象编辑 SQLPlus `/;`；执行路径兼容旧编辑页 `/;`。
+- 进行中：提交并推送。
+- 待处理：发布后验证 Oracle 实库。
+
+## 5. 风险与阻塞
+- 风险：三段名称 `schema.package.proc` 与 `db.schema.table` 存在歧义。
+- 阻塞：无。
+- 缓解措施：仅当第一段不是可见数据库时，将三段名称按 Oracle schema-qualified sequence/package 解析。
+
+## 6. 决策记录
+- 决策 1：序列和存储包复用侧栏现有 `sequence-def` / `package-def` tab 结构。
+- 决策 2：Oracle PL/SQL 定义执行时保留 SQLPlus `/` 分隔符，由后端拆分器去掉 delimiter，避免前端用分号重组造成 ORA-00900。
+
+## 7. 验证记录
+- 验证项：QueryEditor 导航回归测试、DefinitionViewer 对象编辑测试、SQL 语句拆分测试、i18n catalog 测试、前端 build、后端 Oracle 拆分测试。
+- 结果：通过。
+- 证据（日志/截图/链接）：`npm test -- src/components/QueryEditor.external-sql-save.test.tsx`；`npm test -- src/components/DefinitionViewer.object-edit.test.tsx src/i18n/catalog.test.ts src/utils/sqlStatementSelection.test.ts`；`go test ./internal/app -run 'TestDBQueryMultiKeepsOracle|TestDBQueryMultiSkipsOracle'`；`npm run build`。
+
+## 8. 下一步
+- 下一步行动：提交并推送到 dev。
+- 负责人：Codex

docs/需求追踪/需求进度追踪-生产连接只读保护-20260623.md

@@ -0,0 +1,74 @@
+# 需求进度追踪 - 生产连接只读保护
+
+## 1. 需求摘要
+- 需求名称：生产连接只读保护
+- 提出日期：2026-06-23
+- 负责人：Codex
+- 目标：为 SQL 类数据库与 MongoDB 连接增加连接级只读保护，启用后仅允许查询，阻止写入、DDL、导入和同步目标操作
+- 非目标：不为所有侧栏写操作都新增前端隐藏逻辑；不引入新的环境分级体系；不改造 JVM 只读能力
+
+## 2. 范围与验收
+- 范围：
+- 连接配置模型、保存/回填与 RPC 序列化链路
+- 连接弹窗只读开关、查询编辑器本地拦截、DataGrid 导入入口收口
+- 后端 SQL/Mongo 查询判定与写操作统一守卫
+- 验收标准：
+- 支持的数据源出现“生产连接/只允许查询”开关
+- 启用后普通查询仍可执行，非查询 SQL / Mongo 写命令被前后端阻止
+- 导入、结构变更、清表、同步目标等关键写入口被后端拒绝
+- 依赖与约束：
+- 保持现有数据源能力判定与 QueryEditor 执行链路
+- MongoDB 前端判定以保守拦截为主，最终正确性由后端守卫兜底
+
+## 3. 里程碑与进度
+- [x] 阶段 1（需求澄清）：确认采用连接级 `readOnly` 布尔字段，不新建环境系统
+- [x] 阶段 2（影响分析）：梳理前端能力面板、查询执行、导入与后端写入口
+- [x] 阶段 3（方案设计）：确定“前端预拦截 + 后端最终守卫”双层保护
+- [x] 阶段 4（实施计划）：接入配置链路、能力判定、查询判定与写入口守卫
+- [x] 阶段 5（实现与自检）：补文案、测试与定向验证
+- [x] 阶段 6（评审与交付）：确认范围、风险、回滚点和验证命令
+- [ ] 阶段 7（发布与观察）：待体验验证
+
+## 4. 变更清单
+- 已完成：
+- 新增连接级 `readOnly` 配置字段及前后端序列化支持
+- 连接弹窗为 SQL 类数据库与 MongoDB 增加生产连接保护开关
+- QueryEditor 增加本地非查询拦截，DataGrid 导入入口在只读连接下禁用
+- 后端为查询、DDL、导入、清表、同步等写入口增加统一只读守卫
+- MongoDB 查询判定改为命令级白名单，不再把所有 JSON 命令都视为只读
+- 补充前端/后端定向测试与需求追踪文档
+- 进行中：
+- 等待体验包验证连接弹窗、查询拦截和写操作拒绝文案
+- 待处理：
+- 如需进一步优化体验，再补侧栏对象级写菜单的前端隐藏/禁用
+
+## 5. 风险与阻塞
+- 风险：
+- 前端 SQL/Mongo 只读判定是保守策略，边界命令可能仍需后端兜底
+- 现有部分侧栏写菜单仍可能显示，但执行时会被后端拒绝
+- 阻塞：
+- 暂无
+- 缓解措施：
+- 关键写入口统一走后端守卫；前端只负责提前反馈与减少误操作
+
+## 6. 决策记录
+- 决策 1：只对 SQL 类数据库和 MongoDB 支持连接级生产保护，其他数据源忽略 `readOnly`
+- 决策 2：采用顶层 `readOnly` 布尔字段，避免新增环境枚举和迁移成本
+- 决策 3：MongoDB 只读判定按命令白名单处理，防止把写命令误放行
+
+## 7. 验证记录
+- 验证项：
+- 前端数据源能力判定、RPC 配置、连接配置测试
+- 后端只读连接守卫与 SQL/Mongo 查询判定测试
+- 结果：
+- 通过
+- 证据（日志/截图/链接）：
+- `go test ./internal/app -run 'Test(EnsureReadOnlyConnectionAllows|SupportsConnectionReadOnlyMode|IsReadOnlySQLQuery)'`
+- `npm --prefix frontend test -- src/utils/dataSourceCapabilities.test.ts src/utils/connectionRpcConfig.test.ts src/components/connectionModal/connectionModalConfig.keepalive.test.ts`
+
+## 8. 下一步
+- 下一步行动：
+- 用体验包回归验证生产连接下的查询、导入、建库删库、同步目标和 Mongo 命令拦截
+- 如需更完整 UX，再补侧栏写菜单的只读态收口
+- 负责人：
+- Codex

frontend/index.html

@@ -25,6 +25,6 @@
   </head>
   <body>
     <div id="root"></div>
-    <script type="module" src="/src/main.tsx"></script>
+    <script type="module" src="/src/bootstrap.ts"></script>
   </body>
 </html>

frontend/package.json

@@ -2,12 +2,15 @@
   "name": "gonavi-client",
   "private": true,
   "version": "0.6.5",
+  "license": "Apache-2.0",
   "type": "module",
   "scripts": {
     "dev": "vite",
     "build": "tsc && vite build",
     "preview": "vite preview",
-    "test": "vitest run"
+    "test": "vitest run",
+    "postinstall": "patch-package --error-on-fail",
+    "i18n:scan": "go run ../tools/i18n-scan --root .."
   },
   "dependencies": {
     "@ant-design/icons": "^5.2.6",
@@ -16,15 +19,19 @@
     "@dnd-kit/sortable": "^10.0.0",
     "@dnd-kit/utilities": "^3.2.2",
     "@monaco-editor/react": "^4.6.0",
+    "@types/dagre": "^0.7.54",
     "@types/react-syntax-highlighter": "^15.5.13",
     "antd": "^5.12.0",
     "clsx": "^2.1.0",
+    "dagre": "^0.8.5",
+    "fflate": "^0.8.3",
     "mermaid": "^11.13.0",
     "react": "^18.2.0",
     "react-dom": "^18.2.0",
     "react-markdown": "^10.1.0",
     "react-resizable": "^3.1.3",
     "react-syntax-highlighter": "^16.1.1",
+    "reactflow": "^11.11.4",
     "recharts": "^3.8.1",
     "remark-gfm": "^4.0.1",
     "sql-formatter": "^15.7.0",
@@ -35,8 +42,11 @@
     "@types/react": "^18.2.43",
     "@types/react-dom": "^18.2.17",
     "@types/react-resizable": "^3.0.8",
+    "@types/react-test-renderer": "^18.0.7",
     "@types/uuid": "^9.0.7",
     "@vitejs/plugin-react": "^4.2.1",
+    "patch-package": "^8.0.1",
+    "react-test-renderer": "^18.2.0",
     "typescript": "^5.2.2",
     "vite": "^5.0.8",
     "vitest": "^3.2.4"

frontend/package.json.md5

@@ -1 +1 @@
-8cc5d6401a6ce7dd0f500c66ce8bb4a9
+83b4b7d166ed9172beba2d6236382c0b

frontend/patches/rc-table+7.54.0.patch

@@ -0,0 +1,461 @@
+diff --git a/node_modules/rc-table/es/VirtualTable/BodyGrid.js b/node_modules/rc-table/es/VirtualTable/BodyGrid.js
+index 42dcde8..2cca743 100644
+--- a/node_modules/rc-table/es/VirtualTable/BodyGrid.js
++++ b/node_modules/rc-table/es/VirtualTable/BodyGrid.js
+@@ -23,6 +23,8 @@ var Grid = /*#__PURE__*/React.forwardRef(function (props, ref) {
+     sticky = _useContext2.sticky,
+     scrollY = _useContext2.scrollY,
+     listItemHeight = _useContext2.listItemHeight,
++    listItemHeightFixed = _useContext2.listItemHeightFixed,
++    listItemColumnVirtual = _useContext2.listItemColumnVirtual,
+     getComponent = _useContext2.getComponent,
+     onTablePropScroll = _useContext2.onScroll;
+
+@@ -113,8 +115,14 @@ var Grid = /*#__PURE__*/React.forwardRef(function (props, ref) {
+   var extraRender = function extraRender(info) {
++    // The column-window fast path explicitly requires rows without spans.
++    // Avoid scanning every column on each vertical window update.
++    if (listItemColumnVirtual) {
++      return null;
++    }
+     var start = info.start,
+       end = info.end,
+       getSize = info.getSize,
+-      offsetY = info.offsetY;
++      offsetY = info.offsetY,
++      offsetX = info.offsetX;
+
+     // Do nothing if no data
+     if (end < 0) {
+@@ -198,6 +200,7 @@ var Grid = /*#__PURE__*/React.forwardRef(function (props, ref) {
+         style: {
+           top: -offsetY + sizeInfo.top
+         },
++        offsetX: offsetX,
+         extra: true,
+         getHeight: getHeight
+       });
+@@ -239,6 +242,7 @@ var Grid = /*#__PURE__*/React.forwardRef(function (props, ref) {
+     className: tblPrefixCls,
+     height: scrollY,
+     itemHeight: listItemHeight || 24,
++    itemHeightFixed: listItemHeightFixed,
+     data: flattenData,
+     itemKey: function itemKey(item) {
+       return getRowKey(item.record);
+@@ -262,6 +266,7 @@ var Grid = /*#__PURE__*/React.forwardRef(function (props, ref) {
+       data: item,
+       rowKey: rowKey,
+       index: index,
++      offsetX: itemProps.offsetX,
+       style: itemProps.style
+     });
+   }));
+diff --git a/node_modules/rc-table/es/VirtualTable/BodyLine.js b/node_modules/rc-table/es/VirtualTable/BodyLine.js
+index c760819..1a6c396 100644
+--- a/node_modules/rc-table/es/VirtualTable/BodyLine.js
++++ b/node_modules/rc-table/es/VirtualTable/BodyLine.js
+@@ -2,7 +2,7 @@ import _extends from "@babel/runtime/helpers/esm/extends";
+ import _objectSpread from "@babel/runtime/helpers/esm/objectSpread2";
+ import _defineProperty from "@babel/runtime/helpers/esm/defineProperty";
+ import _objectWithoutProperties from "@babel/runtime/helpers/esm/objectWithoutProperties";
+-var _excluded = ["data", "index", "className", "rowKey", "style", "extra", "getHeight"];
++var _excluded = ["data", "index", "className", "rowKey", "style", "offsetX", "extra", "getHeight"];
+ import { useContext } from '@rc-component/context';
+ import classNames from 'classnames';
+ import * as React from 'react';
+@@ -10,7 +10,7 @@ import Cell from "../Cell";
+ import TableContext, { responseImmutable } from "../context/TableContext";
+ import useRowInfo from "../hooks/useRowInfo";
+ import VirtualCell from "./VirtualCell";
+-import { StaticContext } from "./context";
++import { GridContext, StaticContext } from "./context";
+ import { computedExpandedClassName } from "../utils/expandUtil";
+ var BodyLine = /*#__PURE__*/React.forwardRef(function (props, ref) {
+   var data = props.data,
+@@ -18,20 +18,25 @@ var BodyLine = /*#__PURE__*/React.forwardRef(function (props, ref) {
+     className = props.className,
+     rowKey = props.rowKey,
+     style = props.style,
++    offsetX = props.offsetX,
+     extra = props.extra,
+     getHeight = props.getHeight,
+     restProps = _objectWithoutProperties(props, _excluded);
+   var record = data.record,
+     indent = data.indent,
+     renderIndex = data.index;
+-  var _useContext = useContext(TableContext, ['prefixCls', 'flattenColumns', 'fixColumn', 'componentWidth', 'scrollX']),
++  var _useContext = useContext(TableContext, ['prefixCls', 'flattenColumns', 'fixColumn', 'componentWidth', 'scrollX', 'direction']),
+     scrollX = _useContext.scrollX,
+     flattenColumns = _useContext.flattenColumns,
+     prefixCls = _useContext.prefixCls,
+     fixColumn = _useContext.fixColumn,
+-    componentWidth = _useContext.componentWidth;
+-  var _useContext2 = useContext(StaticContext, ['getComponent']),
+-    getComponent = _useContext2.getComponent;
++    componentWidth = _useContext.componentWidth,
++    direction = _useContext.direction;
++  var _useContext2 = useContext(StaticContext, ['getComponent', 'listItemColumnVirtual']),
++    getComponent = _useContext2.getComponent,
++    listItemColumnVirtual = _useContext2.listItemColumnVirtual;
++  var _useContext3 = useContext(GridContext, ['columnsOffset']),
++    columnsOffset = _useContext3.columnsOffset;
+   var rowInfo = useRowInfo(record, rowKey, index, indent);
+   var RowComponent = getComponent(['body', 'row'], 'div');
+   var cellComponent = getComponent(['body', 'cell'], 'div');
+@@ -71,12 +76,7 @@ var BodyLine = /*#__PURE__*/React.forwardRef(function (props, ref) {
+     rowStyle.position = 'absolute';
+     rowStyle.pointerEvents = 'none';
+   }
+-  var rowNode = /*#__PURE__*/React.createElement(RowComponent, _extends({}, rowProps, restProps, {
+-    "data-row-key": rowKey,
+-    ref: rowSupportExpand ? null : ref,
+-    className: classNames(className, "".concat(prefixCls, "-row"), rowProps === null || rowProps === void 0 ? void 0 : rowProps.className, _defineProperty({}, "".concat(prefixCls, "-row-extra"), extra)),
+-    style: _objectSpread(_objectSpread({}, rowStyle), rowProps === null || rowProps === void 0 ? void 0 : rowProps.style)
+-  }), flattenColumns.map(function (column, colIndex) {
++  var renderVirtualCell = function renderVirtualCell(column, colIndex) {
+     return /*#__PURE__*/React.createElement(VirtualCell, {
+       key: colIndex,
+       component: cellComponent,
+@@ -90,7 +90,60 @@ var BodyLine = /*#__PURE__*/React.forwardRef(function (props, ref) {
+       inverse: extra,
+       getHeight: getHeight
+     });
+-  }));
++  };
++  var columnNodes;
++  if (listItemColumnVirtual && direction !== 'rtl' && !extra && columnsOffset && columnsOffset.length === flattenColumns.length) {
++    var mergedOffsetX = Math.max(0, offsetX || 0);
++    var viewportWidth = Math.max(0, componentWidth || 0);
++    var overscanWidth = Math.max(320, viewportWidth);
++    var visibleStart = Math.max(0, mergedOffsetX - overscanWidth);
++    var visibleEnd = mergedOffsetX + viewportWidth + overscanWidth;
++    var nodes = [];
++    var spacerStart = -1;
++    var spacerWidth = 0;
++    var flushSpacer = function flushSpacer() {
++      if (spacerWidth <= 0) return;
++      nodes.push(/*#__PURE__*/React.createElement(cellComponent, {
++        "aria-hidden": true,
++        className: "".concat(prefixCls, "-cell-virtual-spacer"),
++        key: "virtual-spacer-".concat(spacerStart),
++        style: {
++          border: 0,
++          flex: "0 0 ".concat(spacerWidth, "px"),
++          minWidth: 0,
++          padding: 0,
++          pointerEvents: 'none',
++          visibility: 'hidden',
++          width: "".concat(spacerWidth, "px")
++        }
++      }));
++      spacerStart = -1;
++      spacerWidth = 0;
++    };
++    flattenColumns.forEach(function (column, colIndex) {
++      var columnStart = colIndex > 0 ? columnsOffset[colIndex - 1] : 0;
++      var columnEnd = columnsOffset[colIndex] || columnStart;
++      var fixedColumn = column.fixed === true || column.fixed === 'left' || column.fixed === 'right';
++      var visibleColumn = fixedColumn || columnEnd >= visibleStart && columnStart <= visibleEnd;
++      if (visibleColumn) {
++        flushSpacer();
++        nodes.push(renderVirtualCell(column, colIndex));
++      } else {
++        if (spacerStart < 0) spacerStart = colIndex;
++        spacerWidth += Math.max(0, columnEnd - columnStart);
++      }
++    });
++    flushSpacer();
++    columnNodes = nodes;
++  } else {
++    columnNodes = flattenColumns.map(renderVirtualCell);
++  }
++  var rowNode = /*#__PURE__*/React.createElement(RowComponent, _extends({}, rowProps, restProps, {
++    "data-row-key": rowKey,
++    ref: rowSupportExpand ? null : ref,
++    className: classNames(className, "".concat(prefixCls, "-row"), rowProps === null || rowProps === void 0 ? void 0 : rowProps.className, _defineProperty({}, "".concat(prefixCls, "-row-extra"), extra)),
++    style: _objectSpread(_objectSpread({}, rowStyle), rowProps === null || rowProps === void 0 ? void 0 : rowProps.style)
++  }), columnNodes);
+   if (rowSupportExpand) {
+     return /*#__PURE__*/React.createElement("div", {
+       ref: ref
+diff --git a/node_modules/rc-table/es/VirtualTable/context.d.ts b/node_modules/rc-table/es/VirtualTable/context.d.ts
+index e558165..ccd74fc 100644
+--- a/node_modules/rc-table/es/VirtualTable/context.d.ts
++++ b/node_modules/rc-table/es/VirtualTable/context.d.ts
+@@ -3,6 +3,8 @@ import type { GetComponent, TableSticky } from '../interface';
+ export interface StaticContextProps {
+     scrollY: number;
+     listItemHeight: number;
++    listItemHeightFixed?: boolean;
++    listItemColumnVirtual?: boolean;
+     sticky: boolean | TableSticky;
+     getComponent: GetComponent;
+     onScroll?: React.UIEventHandler<HTMLDivElement>;
+diff --git a/node_modules/rc-table/es/VirtualTable/index.d.ts b/node_modules/rc-table/es/VirtualTable/index.d.ts
+index 31fe8e0..c5097b2 100644
+--- a/node_modules/rc-table/es/VirtualTable/index.d.ts
++++ b/node_modules/rc-table/es/VirtualTable/index.d.ts
+@@ -8,6 +8,9 @@ export interface VirtualTableProps<RecordType> extends Omit<TableProps<RecordTyp
+         y: number;
+     };
+     listItemHeight?: number;
++    listItemHeightFixed?: boolean;
++    /** LTR-only fast path; requires body cells without colSpan/rowSpan. */
++    listItemColumnVirtual?: boolean;
+ }
+ export type ForwardGenericVirtualTable = (<RecordType>(props: TableProps<RecordType> & React.RefAttributes<Reference>) => React.ReactElement) & {
+     displayName?: string;
+diff --git a/node_modules/rc-table/es/VirtualTable/index.js b/node_modules/rc-table/es/VirtualTable/index.js
+index fb00e9b..a778aa6 100644
+--- a/node_modules/rc-table/es/VirtualTable/index.js
++++ b/node_modules/rc-table/es/VirtualTable/index.js
+@@ -27,6 +27,8 @@ function VirtualTable(props, ref) {
+     prefixCls = _props$prefixCls === void 0 ? DEFAULT_PREFIX : _props$prefixCls,
+     className = props.className,
+     listItemHeight = props.listItemHeight,
++    listItemHeightFixed = props.listItemHeightFixed,
++    listItemColumnVirtual = props.listItemColumnVirtual,
+     components = props.components,
+     onScroll = props.onScroll;
+   var _ref = scroll || {},
+@@ -61,10 +63,12 @@ function VirtualTable(props, ref) {
+       sticky: sticky,
+       scrollY: scrollY,
+       listItemHeight: listItemHeight,
++      listItemHeightFixed: listItemHeightFixed,
++      listItemColumnVirtual: listItemColumnVirtual,
+       getComponent: getComponent,
+       onScroll: onInternalScroll
+     };
+-  }, [sticky, scrollY, listItemHeight, getComponent, onInternalScroll]);
++  }, [sticky, scrollY, listItemHeight, listItemHeightFixed, listItemColumnVirtual, getComponent, onInternalScroll]);
+
+   // ========================== Render ==========================
+   return /*#__PURE__*/React.createElement(StaticContext.Provider, {
+diff --git a/node_modules/rc-table/lib/VirtualTable/BodyGrid.js b/node_modules/rc-table/lib/VirtualTable/BodyGrid.js
+index dee2539..b077789 100644
+--- a/node_modules/rc-table/lib/VirtualTable/BodyGrid.js
++++ b/node_modules/rc-table/lib/VirtualTable/BodyGrid.js
+@@ -33,6 +33,8 @@ var Grid = /*#__PURE__*/React.forwardRef(function (props, ref) {
+     sticky = _useContext2.sticky,
+     scrollY = _useContext2.scrollY,
+     listItemHeight = _useContext2.listItemHeight,
++    listItemHeightFixed = _useContext2.listItemHeightFixed,
++    listItemColumnVirtual = _useContext2.listItemColumnVirtual,
+     getComponent = _useContext2.getComponent,
+     onTablePropScroll = _useContext2.onScroll;
+
+@@ -123,8 +125,14 @@ var Grid = /*#__PURE__*/React.forwardRef(function (props, ref) {
+   var extraRender = function extraRender(info) {
++    // The column-window fast path explicitly requires rows without spans.
++    // Avoid scanning every column on each vertical window update.
++    if (listItemColumnVirtual) {
++      return null;
++    }
+     var start = info.start,
+       end = info.end,
+       getSize = info.getSize,
+-      offsetY = info.offsetY;
++      offsetY = info.offsetY,
++      offsetX = info.offsetX;
+
+     // Do nothing if no data
+     if (end < 0) {
+@@ -208,6 +210,7 @@ var Grid = /*#__PURE__*/React.forwardRef(function (props, ref) {
+         style: {
+           top: -offsetY + sizeInfo.top
+         },
++        offsetX: offsetX,
+         extra: true,
+         getHeight: getHeight
+       });
+@@ -249,6 +252,7 @@ var Grid = /*#__PURE__*/React.forwardRef(function (props, ref) {
+     className: tblPrefixCls,
+     height: scrollY,
+     itemHeight: listItemHeight || 24,
++    itemHeightFixed: listItemHeightFixed,
+     data: flattenData,
+     itemKey: function itemKey(item) {
+       return getRowKey(item.record);
+@@ -272,6 +276,7 @@ var Grid = /*#__PURE__*/React.forwardRef(function (props, ref) {
+       data: item,
+       rowKey: rowKey,
+       index: index,
++      offsetX: itemProps.offsetX,
+       style: itemProps.style
+     });
+   }));
+diff --git a/node_modules/rc-table/lib/VirtualTable/BodyLine.js b/node_modules/rc-table/lib/VirtualTable/BodyLine.js
+index e1275fb..d962380 100644
+--- a/node_modules/rc-table/lib/VirtualTable/BodyLine.js
++++ b/node_modules/rc-table/lib/VirtualTable/BodyLine.js
+@@ -19,7 +19,7 @@ var _useRowInfo = _interopRequireDefault(require("../hooks/useRowInfo"));
+ var _VirtualCell = _interopRequireDefault(require("./VirtualCell"));
+ var _context2 = require("./context");
+ var _expandUtil = require("../utils/expandUtil");
+-var _excluded = ["data", "index", "className", "rowKey", "style", "extra", "getHeight"];
++var _excluded = ["data", "index", "className", "rowKey", "style", "offsetX", "extra", "getHeight"];
+ function _getRequireWildcardCache(e) { if ("function" != typeof WeakMap) return null; var r = new WeakMap(), t = new WeakMap(); return (_getRequireWildcardCache = function _getRequireWildcardCache(e) { return e ? t : r; })(e); }
+ function _interopRequireWildcard(e, r) { if (!r && e && e.__esModule) return e; if (null === e || "object" != _typeof(e) && "function" != typeof e) return { default: e }; var t = _getRequireWildcardCache(r); if (t && t.has(e)) return t.get(e); var n = { __proto__: null }, a = Object.defineProperty && Object.getOwnPropertyDescriptor; for (var u in e) if ("default" !== u && Object.prototype.hasOwnProperty.call(e, u)) { var i = a ? Object.getOwnPropertyDescriptor(e, u) : null; i && (i.get || i.set) ? Object.defineProperty(n, u, i) : n[u] = e[u]; } return n.default = e, t && t.set(e, n), n; }
+ var BodyLine = /*#__PURE__*/React.forwardRef(function (props, ref) {
+@@ -28,20 +28,25 @@ var BodyLine = /*#__PURE__*/React.forwardRef(function (props, ref) {
+     className = props.className,
+     rowKey = props.rowKey,
+     style = props.style,
++    offsetX = props.offsetX,
+     extra = props.extra,
+     getHeight = props.getHeight,
+     restProps = (0, _objectWithoutProperties2.default)(props, _excluded);
+   var record = data.record,
+     indent = data.indent,
+     renderIndex = data.index;
+-  var _useContext = (0, _context.useContext)(_TableContext.default, ['prefixCls', 'flattenColumns', 'fixColumn', 'componentWidth', 'scrollX']),
++  var _useContext = (0, _context.useContext)(_TableContext.default, ['prefixCls', 'flattenColumns', 'fixColumn', 'componentWidth', 'scrollX', 'direction']),
+     scrollX = _useContext.scrollX,
+     flattenColumns = _useContext.flattenColumns,
+     prefixCls = _useContext.prefixCls,
+     fixColumn = _useContext.fixColumn,
+-    componentWidth = _useContext.componentWidth;
+-  var _useContext2 = (0, _context.useContext)(_context2.StaticContext, ['getComponent']),
+-    getComponent = _useContext2.getComponent;
++    componentWidth = _useContext.componentWidth,
++    direction = _useContext.direction;
++  var _useContext2 = (0, _context.useContext)(_context2.StaticContext, ['getComponent', 'listItemColumnVirtual']),
++    getComponent = _useContext2.getComponent,
++    listItemColumnVirtual = _useContext2.listItemColumnVirtual;
++  var _useContext3 = (0, _context.useContext)(_context2.GridContext, ['columnsOffset']),
++    columnsOffset = _useContext3.columnsOffset;
+   var rowInfo = (0, _useRowInfo.default)(record, rowKey, index, indent);
+   var RowComponent = getComponent(['body', 'row'], 'div');
+   var cellComponent = getComponent(['body', 'cell'], 'div');
+@@ -81,12 +86,7 @@ var BodyLine = /*#__PURE__*/React.forwardRef(function (props, ref) {
+     rowStyle.position = 'absolute';
+     rowStyle.pointerEvents = 'none';
+   }
+-  var rowNode = /*#__PURE__*/React.createElement(RowComponent, (0, _extends2.default)({}, rowProps, restProps, {
+-    "data-row-key": rowKey,
+-    ref: rowSupportExpand ? null : ref,
+-    className: (0, _classnames.default)(className, "".concat(prefixCls, "-row"), rowProps === null || rowProps === void 0 ? void 0 : rowProps.className, (0, _defineProperty2.default)({}, "".concat(prefixCls, "-row-extra"), extra)),
+-    style: (0, _objectSpread2.default)((0, _objectSpread2.default)({}, rowStyle), rowProps === null || rowProps === void 0 ? void 0 : rowProps.style)
+-  }), flattenColumns.map(function (column, colIndex) {
++  var renderVirtualCell = function renderVirtualCell(column, colIndex) {
+     return /*#__PURE__*/React.createElement(_VirtualCell.default, {
+       key: colIndex,
+       component: cellComponent,
+@@ -100,7 +100,60 @@ var BodyLine = /*#__PURE__*/React.forwardRef(function (props, ref) {
+       inverse: extra,
+       getHeight: getHeight
+     });
+-  }));
++  };
++  var columnNodes;
++  if (listItemColumnVirtual && direction !== 'rtl' && !extra && columnsOffset && columnsOffset.length === flattenColumns.length) {
++    var mergedOffsetX = Math.max(0, offsetX || 0);
++    var viewportWidth = Math.max(0, componentWidth || 0);
++    var overscanWidth = Math.max(320, viewportWidth);
++    var visibleStart = Math.max(0, mergedOffsetX - overscanWidth);
++    var visibleEnd = mergedOffsetX + viewportWidth + overscanWidth;
++    var nodes = [];
++    var spacerStart = -1;
++    var spacerWidth = 0;
++    var flushSpacer = function flushSpacer() {
++      if (spacerWidth <= 0) return;
++      nodes.push(/*#__PURE__*/React.createElement(cellComponent, {
++        "aria-hidden": true,
++        className: "".concat(prefixCls, "-cell-virtual-spacer"),
++        key: "virtual-spacer-".concat(spacerStart),
++        style: {
++          border: 0,
++          flex: "0 0 ".concat(spacerWidth, "px"),
++          minWidth: 0,
++          padding: 0,
++          pointerEvents: 'none',
++          visibility: 'hidden',
++          width: "".concat(spacerWidth, "px")
++        }
++      }));
++      spacerStart = -1;
++      spacerWidth = 0;
++    };
++    flattenColumns.forEach(function (column, colIndex) {
++      var columnStart = colIndex > 0 ? columnsOffset[colIndex - 1] : 0;
++      var columnEnd = columnsOffset[colIndex] || columnStart;
++      var fixedColumn = column.fixed === true || column.fixed === 'left' || column.fixed === 'right';
++      var visibleColumn = fixedColumn || columnEnd >= visibleStart && columnStart <= visibleEnd;
++      if (visibleColumn) {
++        flushSpacer();
++        nodes.push(renderVirtualCell(column, colIndex));
++      } else {
++        if (spacerStart < 0) spacerStart = colIndex;
++        spacerWidth += Math.max(0, columnEnd - columnStart);
++      }
++    });
++    flushSpacer();
++    columnNodes = nodes;
++  } else {
++    columnNodes = flattenColumns.map(renderVirtualCell);
++  }
++  var rowNode = /*#__PURE__*/React.createElement(RowComponent, (0, _extends2.default)({}, rowProps, restProps, {
++    "data-row-key": rowKey,
++    ref: rowSupportExpand ? null : ref,
++    className: (0, _classnames.default)(className, "".concat(prefixCls, "-row"), rowProps === null || rowProps === void 0 ? void 0 : rowProps.className, (0, _defineProperty2.default)({}, "".concat(prefixCls, "-row-extra"), extra)),
++    style: (0, _objectSpread2.default)((0, _objectSpread2.default)({}, rowStyle), rowProps === null || rowProps === void 0 ? void 0 : rowProps.style)
++  }), columnNodes);
+   if (rowSupportExpand) {
+     return /*#__PURE__*/React.createElement("div", {
+       ref: ref
+diff --git a/node_modules/rc-table/lib/VirtualTable/context.d.ts b/node_modules/rc-table/lib/VirtualTable/context.d.ts
+index e558165..ccd74fc 100644
+--- a/node_modules/rc-table/lib/VirtualTable/context.d.ts
++++ b/node_modules/rc-table/lib/VirtualTable/context.d.ts
+@@ -3,6 +3,8 @@ import type { GetComponent, TableSticky } from '../interface';
+ export interface StaticContextProps {
+     scrollY: number;
+     listItemHeight: number;
++    listItemHeightFixed?: boolean;
++    listItemColumnVirtual?: boolean;
+     sticky: boolean | TableSticky;
+     getComponent: GetComponent;
+     onScroll?: React.UIEventHandler<HTMLDivElement>;
+diff --git a/node_modules/rc-table/lib/VirtualTable/index.d.ts b/node_modules/rc-table/lib/VirtualTable/index.d.ts
+index 31fe8e0..c5097b2 100644
+--- a/node_modules/rc-table/lib/VirtualTable/index.d.ts
++++ b/node_modules/rc-table/lib/VirtualTable/index.d.ts
+@@ -8,6 +8,9 @@ export interface VirtualTableProps<RecordType> extends Omit<TableProps<RecordTyp
+         y: number;
+     };
+     listItemHeight?: number;
++    listItemHeightFixed?: boolean;
++    /** LTR-only fast path; requires body cells without colSpan/rowSpan. */
++    listItemColumnVirtual?: boolean;
+ }
+ export type ForwardGenericVirtualTable = (<RecordType>(props: TableProps<RecordType> & React.RefAttributes<Reference>) => React.ReactElement) & {
+     displayName?: string;
+diff --git a/node_modules/rc-table/lib/VirtualTable/index.js b/node_modules/rc-table/lib/VirtualTable/index.js
+index 8e31a9b..24ab161 100644
+--- a/node_modules/rc-table/lib/VirtualTable/index.js
++++ b/node_modules/rc-table/lib/VirtualTable/index.js
+@@ -38,6 +38,8 @@ function VirtualTable(props, ref) {
+     prefixCls = _props$prefixCls === void 0 ? _Table.DEFAULT_PREFIX : _props$prefixCls,
+     className = props.className,
+     listItemHeight = props.listItemHeight,
++    listItemHeightFixed = props.listItemHeightFixed,
++    listItemColumnVirtual = props.listItemColumnVirtual,
+     components = props.components,
+     onScroll = props.onScroll;
+   var _ref = scroll || {},
+@@ -72,10 +74,12 @@ function VirtualTable(props, ref) {
+       sticky: sticky,
+       scrollY: scrollY,
+       listItemHeight: listItemHeight,
++      listItemHeightFixed: listItemHeightFixed,
++      listItemColumnVirtual: listItemColumnVirtual,
+       getComponent: getComponent,
+       onScroll: onInternalScroll
+     };
+-  }, [sticky, scrollY, listItemHeight, getComponent, onInternalScroll]);
++  }, [sticky, scrollY, listItemHeight, listItemHeightFixed, listItemColumnVirtual, getComponent, onInternalScroll]);
+
+   // ========================== Render ==========================
+   return /*#__PURE__*/React.createElement(_context.StaticContext.Provider, {

frontend/patches/rc-virtual-list+3.19.2.patch

@@ -0,0 +1,336 @@
+diff --git a/node_modules/rc-virtual-list/es/List.d.ts b/node_modules/rc-virtual-list/es/List.d.ts
+index c517366..e414513 100644
+--- a/node_modules/rc-virtual-list/es/List.d.ts
++++ b/node_modules/rc-virtual-list/es/List.d.ts
+@@ -20,6 +20,8 @@ export interface ListProps<T> extends Omit<React.HTMLAttributes<any>, 'children'
+     data: T[];
+     height?: number;
+     itemHeight?: number;
++    /** Treat every item as exactly itemHeight and calculate the visible range in O(1). */
++    itemHeightFixed?: boolean;
+     /** If not match virtual scroll condition, Set List still use height of container. */
+     fullHeight?: boolean;
+     itemKey: React.Key | ((item: T) => React.Key);
+diff --git a/node_modules/rc-virtual-list/es/List.js b/node_modules/rc-virtual-list/es/List.js
+index 2926056..e917ba1 100644
+--- a/node_modules/rc-virtual-list/es/List.js
++++ b/node_modules/rc-virtual-list/es/List.js
+@@ -4,7 +4,7 @@ import _objectSpread from "@babel/runtime/helpers/esm/objectSpread2";
+ import _defineProperty from "@babel/runtime/helpers/esm/defineProperty";
+ import _slicedToArray from "@babel/runtime/helpers/esm/slicedToArray";
+ import _objectWithoutProperties from "@babel/runtime/helpers/esm/objectWithoutProperties";
+-var _excluded = ["prefixCls", "className", "height", "itemHeight", "fullHeight", "style", "data", "children", "itemKey", "virtual", "direction", "scrollWidth", "component", "onScroll", "onVirtualScroll", "onVisibleChange", "innerProps", "extraRender", "styles", "showScrollBar"];
++var _excluded = ["prefixCls", "className", "height", "itemHeight", "itemHeightFixed", "fullHeight", "style", "data", "children", "itemKey", "virtual", "direction", "scrollWidth", "component", "onScroll", "onVirtualScroll", "onVisibleChange", "innerProps", "extraRender", "styles", "showScrollBar"];
+ import classNames from 'classnames';
+ import ResizeObserver from 'rc-resize-observer';
+ import { useEvent } from 'rc-util';
+@@ -35,6 +35,7 @@ export function RawList(props, ref) {
+     className = props.className,
+     height = props.height,
+     itemHeight = props.itemHeight,
++    itemHeightFixed = props.itemHeightFixed,
+     _props$fullHeight = props.fullHeight,
+     fullHeight = _props$fullHeight === void 0 ? true : _props$fullHeight,
+     style = props.style,
+@@ -65,7 +66,7 @@ export function RawList(props, ref) {
+   }, [itemKey]);
+
+   // ================================ Height ================================
+-  var _useHeights = useHeights(getKey, null, null),
++  var _useHeights = useHeights(getKey, null, null, itemHeightFixed),
+     _useHeights2 = _slicedToArray(_useHeights, 4),
+     setInstanceRef = _useHeights2[0],
+     collectHeight = _useHeights2[1],
+@@ -74,11 +75,12 @@ export function RawList(props, ref) {
+
+   // ================================= MISC =================================
+   var useVirtual = !!(virtual !== false && height && itemHeight);
+-  var containerHeight = React.useMemo(function () {
++  var measuredContainerHeight = React.useMemo(function () {
+     return Object.values(heights.maps).reduce(function (total, curr) {
+       return total + curr;
+     }, 0);
+   }, [heights.id, heights.maps]);
++  var containerHeight = itemHeightFixed ? itemHeight * (data || EMPTY_DATA).length : measuredContainerHeight;
+   var inVirtual = useVirtual && data && (Math.max(itemHeight * data.length, containerHeight) > height || !!scrollWidth);
+   var isRTL = direction === 'rtl';
+   var mergedClassName = classNames(prefixCls, _defineProperty({}, "".concat(prefixCls, "-rtl"), isRTL), className);
+@@ -159,6 +161,28 @@ export function RawList(props, ref) {
+           offset: undefined
+         };
+       }
++      if (itemHeightFixed && itemHeight > 0) {
++        var fixedDataLen = mergedData.length;
++        var fixedScrollHeight = fixedDataLen * itemHeight;
++        if (fixedDataLen === 0) {
++          return {
++            scrollHeight: 0,
++            start: 0,
++            end: -1,
++            offset: 0
++          };
++        }
++        var fixedMaxScrollTop = Math.max(0, fixedScrollHeight - height);
++        var fixedOffsetTop = Math.max(0, Math.min(fixedMaxScrollTop, offsetTop));
++        var fixedStartIndex = Math.min(fixedDataLen - 1, Math.max(0, Math.ceil(fixedOffsetTop / itemHeight) - 1));
++        var fixedEndIndex = Math.min(fixedDataLen - 1, Math.floor((fixedOffsetTop + height) / itemHeight) + 1);
++        return {
++          scrollHeight: fixedScrollHeight,
++          start: fixedStartIndex,
++          end: fixedEndIndex,
++          offset: fixedStartIndex * itemHeight
++        };
++      }
+       var itemTop = 0;
+       var startIndex;
+       var startOffset;
+@@ -201,7 +225,7 @@ export function RawList(props, ref) {
+         end: endIndex,
+         offset: startOffset
+       };
+-    }, [inVirtual, useVirtual, offsetTop, mergedData, heightUpdatedMark, height]),
++    }, [inVirtual, useVirtual, offsetTop, mergedData, heightUpdatedMark, height, itemHeightFixed, itemHeight]),
+     scrollHeight = _React$useMemo.scrollHeight,
+     start = _React$useMemo.start,
+     end = _React$useMemo.end,
+@@ -213,6 +237,10 @@ export function RawList(props, ref) {
+   // Which will make scroll jump.
+   // Let's sync scroll top to avoid jump
+   React.useLayoutEffect(function () {
++    if (itemHeightFixed) {
++      heights.resetRecord();
++      return;
++    }
+     var changedRecord = heights.getRecord();
+     if (changedRecord.size === 1) {
+       var recordKey = Array.from(changedRecord.keys())[0];
+@@ -232,7 +260,7 @@ export function RawList(props, ref) {
+       }
+     }
+     heights.resetRecord();
+-  }, [scrollHeight]);
++  }, [scrollHeight, itemHeightFixed, heightUpdatedMark]);
+
+   // ================================= Size =================================
+   var _React$useState = React.useState({
+diff --git a/node_modules/rc-virtual-list/es/hooks/useHeights.d.ts b/node_modules/rc-virtual-list/es/hooks/useHeights.d.ts
+--- a/node_modules/rc-virtual-list/es/hooks/useHeights.d.ts
++++ b/node_modules/rc-virtual-list/es/hooks/useHeights.d.ts
+@@ -1,6 +1,6 @@
+ import type { GetKey } from '../interface';
+ import CacheMap from '../utils/CacheMap';
+-export default function useHeights<T>(getKey: GetKey<T>, onItemAdd?: (item: T) => void, onItemRemove?: (item: T) => void): [
++export default function useHeights<T>(getKey: GetKey<T>, onItemAdd?: (item: T) => void, onItemRemove?: (item: T) => void, disabled?: boolean): [
+     setInstanceRef: (item: T, instance: HTMLElement) => void,
+     collectHeight: (sync?: boolean) => void,
+     cacheMap: CacheMap,
+diff --git a/node_modules/rc-virtual-list/es/hooks/useHeights.js b/node_modules/rc-virtual-list/es/hooks/useHeights.js
+index 0323aae..38e6e75 100644
+--- a/node_modules/rc-virtual-list/es/hooks/useHeights.js
++++ b/node_modules/rc-virtual-list/es/hooks/useHeights.js
+@@ -6,7 +6,7 @@ function parseNumber(value) {
+   var num = parseFloat(value);
+   return isNaN(num) ? 0 : num;
+ }
+-export default function useHeights(getKey, onItemAdd, onItemRemove) {
++export default function useHeights(getKey, onItemAdd, onItemRemove, disabled) {
+   var _React$useState = React.useState(0),
+     _React$useState2 = _slicedToArray(_React$useState, 2),
+     updatedMark = _React$useState2[0],
+@@ -14,12 +14,17 @@ export default function useHeights(getKey, onItemAdd, onItemRemove) {
+   var instanceRef = useRef(new Map());
+   var heightsRef = useRef(new CacheMap());
+   var promiseIdRef = useRef(0);
++  var disabledRef = useRef(disabled);
++  disabledRef.current = disabled;
+   function cancelRaf() {
+     promiseIdRef.current += 1;
+   }
+   function collectHeight() {
+     var sync = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : false;
+     cancelRaf();
++    if (disabledRef.current) {
++      return;
++    }
+     var doCollect = function doCollect() {
+       var changed = false;
+       instanceRef.current.forEach(function (element, key) {
+@@ -79,5 +84,10 @@ export default function useHeights(getKey, onItemAdd, onItemRemove) {
+   useEffect(function () {
+     return cancelRaf;
+   }, []);
++  useEffect(function () {
++    if (!disabled) {
++      collectHeight(true);
++    }
++  }, [disabled]);
+   return [setInstanceRef, collectHeight, heightsRef.current, updatedMark];
+ }
+diff --git a/node_modules/rc-virtual-list/lib/List.d.ts b/node_modules/rc-virtual-list/lib/List.d.ts
+index c517366..e414513 100644
+--- a/node_modules/rc-virtual-list/lib/List.d.ts
++++ b/node_modules/rc-virtual-list/lib/List.d.ts
+@@ -20,6 +20,8 @@ export interface ListProps<T> extends Omit<React.HTMLAttributes<any>, 'children'
+     data: T[];
+     height?: number;
+     itemHeight?: number;
++    /** Treat every item as exactly itemHeight and calculate the visible range in O(1). */
++    itemHeightFixed?: boolean;
+     /** If not match virtual scroll condition, Set List still use height of container. */
+     fullHeight?: boolean;
+     itemKey: React.Key | ((item: T) => React.Key);
+diff --git a/node_modules/rc-virtual-list/lib/List.js b/node_modules/rc-virtual-list/lib/List.js
+index f0cb64d..d24a9ad 100644
+--- a/node_modules/rc-virtual-list/lib/List.js
++++ b/node_modules/rc-virtual-list/lib/List.js
+@@ -32,7 +32,7 @@ var _useScrollDrag = _interopRequireDefault(require("./hooks/useScrollDrag"));
+ var _useScrollTo = _interopRequireDefault(require("./hooks/useScrollTo"));
+ var _ScrollBar = _interopRequireDefault(require("./ScrollBar"));
+ var _scrollbarUtil = require("./utils/scrollbarUtil");
+-var _excluded = ["prefixCls", "className", "height", "itemHeight", "fullHeight", "style", "data", "children", "itemKey", "virtual", "direction", "scrollWidth", "component", "onScroll", "onVirtualScroll", "onVisibleChange", "innerProps", "extraRender", "styles", "showScrollBar"];
++var _excluded = ["prefixCls", "className", "height", "itemHeight", "itemHeightFixed", "fullHeight", "style", "data", "children", "itemKey", "virtual", "direction", "scrollWidth", "component", "onScroll", "onVirtualScroll", "onVisibleChange", "innerProps", "extraRender", "styles", "showScrollBar"];
+ var EMPTY_DATA = [];
+ var ScrollStyle = {
+   overflowY: 'auto',
+@@ -44,6 +44,7 @@ function RawList(props, ref) {
+     className = props.className,
+     height = props.height,
+     itemHeight = props.itemHeight,
++    itemHeightFixed = props.itemHeightFixed,
+     _props$fullHeight = props.fullHeight,
+     fullHeight = _props$fullHeight === void 0 ? true : _props$fullHeight,
+     style = props.style,
+@@ -74,7 +75,7 @@ function RawList(props, ref) {
+   }, [itemKey]);
+
+   // ================================ Height ================================
+-  var _useHeights = (0, _useHeights3.default)(getKey, null, null),
++  var _useHeights = (0, _useHeights3.default)(getKey, null, null, itemHeightFixed),
+     _useHeights2 = (0, _slicedToArray2.default)(_useHeights, 4),
+     setInstanceRef = _useHeights2[0],
+     collectHeight = _useHeights2[1],
+@@ -83,11 +84,12 @@ function RawList(props, ref) {
+
+   // ================================= MISC =================================
+   var useVirtual = !!(virtual !== false && height && itemHeight);
+-  var containerHeight = React.useMemo(function () {
++  var measuredContainerHeight = React.useMemo(function () {
+     return Object.values(heights.maps).reduce(function (total, curr) {
+       return total + curr;
+     }, 0);
+   }, [heights.id, heights.maps]);
++  var containerHeight = itemHeightFixed ? itemHeight * (data || EMPTY_DATA).length : measuredContainerHeight;
+   var inVirtual = useVirtual && data && (Math.max(itemHeight * data.length, containerHeight) > height || !!scrollWidth);
+   var isRTL = direction === 'rtl';
+   var mergedClassName = (0, _classnames.default)(prefixCls, (0, _defineProperty2.default)({}, "".concat(prefixCls, "-rtl"), isRTL), className);
+@@ -168,6 +170,28 @@ function RawList(props, ref) {
+           offset: undefined
+         };
+       }
++      if (itemHeightFixed && itemHeight > 0) {
++        var fixedDataLen = mergedData.length;
++        var fixedScrollHeight = fixedDataLen * itemHeight;
++        if (fixedDataLen === 0) {
++          return {
++            scrollHeight: 0,
++            start: 0,
++            end: -1,
++            offset: 0
++          };
++        }
++        var fixedMaxScrollTop = Math.max(0, fixedScrollHeight - height);
++        var fixedOffsetTop = Math.max(0, Math.min(fixedMaxScrollTop, offsetTop));
++        var fixedStartIndex = Math.min(fixedDataLen - 1, Math.max(0, Math.ceil(fixedOffsetTop / itemHeight) - 1));
++        var fixedEndIndex = Math.min(fixedDataLen - 1, Math.floor((fixedOffsetTop + height) / itemHeight) + 1);
++        return {
++          scrollHeight: fixedScrollHeight,
++          start: fixedStartIndex,
++          end: fixedEndIndex,
++          offset: fixedStartIndex * itemHeight
++        };
++      }
+       var itemTop = 0;
+       var startIndex;
+       var startOffset;
+@@ -210,7 +234,7 @@ function RawList(props, ref) {
+         end: endIndex,
+         offset: startOffset
+       };
+-    }, [inVirtual, useVirtual, offsetTop, mergedData, heightUpdatedMark, height]),
++    }, [inVirtual, useVirtual, offsetTop, mergedData, heightUpdatedMark, height, itemHeightFixed, itemHeight]),
+     scrollHeight = _React$useMemo.scrollHeight,
+     start = _React$useMemo.start,
+     end = _React$useMemo.end,
+@@ -222,6 +246,10 @@ function RawList(props, ref) {
+   // Which will make scroll jump.
+   // Let's sync scroll top to avoid jump
+   React.useLayoutEffect(function () {
++    if (itemHeightFixed) {
++      heights.resetRecord();
++      return;
++    }
+     var changedRecord = heights.getRecord();
+     if (changedRecord.size === 1) {
+       var recordKey = Array.from(changedRecord.keys())[0];
+@@ -241,7 +269,7 @@ function RawList(props, ref) {
+       }
+     }
+     heights.resetRecord();
+-  }, [scrollHeight]);
++  }, [scrollHeight, itemHeightFixed, heightUpdatedMark]);
+
+   // ================================= Size =================================
+   var _React$useState = React.useState({
+diff --git a/node_modules/rc-virtual-list/lib/hooks/useHeights.d.ts b/node_modules/rc-virtual-list/lib/hooks/useHeights.d.ts
+--- a/node_modules/rc-virtual-list/lib/hooks/useHeights.d.ts
++++ b/node_modules/rc-virtual-list/lib/hooks/useHeights.d.ts
+@@ -1,6 +1,6 @@
+ import type { GetKey } from '../interface';
+ import CacheMap from '../utils/CacheMap';
+-export default function useHeights<T>(getKey: GetKey<T>, onItemAdd?: (item: T) => void, onItemRemove?: (item: T) => void): [
++export default function useHeights<T>(getKey: GetKey<T>, onItemAdd?: (item: T) => void, onItemRemove?: (item: T) => void, disabled?: boolean): [
+     setInstanceRef: (item: T, instance: HTMLElement) => void,
+     collectHeight: (sync?: boolean) => void,
+     cacheMap: CacheMap,
+diff --git a/node_modules/rc-virtual-list/lib/hooks/useHeights.js b/node_modules/rc-virtual-list/lib/hooks/useHeights.js
+index 471ffc6..a6d2ce5 100644
+--- a/node_modules/rc-virtual-list/lib/hooks/useHeights.js
++++ b/node_modules/rc-virtual-list/lib/hooks/useHeights.js
+@@ -14,7 +14,7 @@ function parseNumber(value) {
+   var num = parseFloat(value);
+   return isNaN(num) ? 0 : num;
+ }
+-function useHeights(getKey, onItemAdd, onItemRemove) {
++function useHeights(getKey, onItemAdd, onItemRemove, disabled) {
+   var _React$useState = React.useState(0),
+     _React$useState2 = (0, _slicedToArray2.default)(_React$useState, 2),
+     updatedMark = _React$useState2[0],
+@@ -22,12 +22,17 @@ function useHeights(getKey, onItemAdd, onItemRemove) {
+   var instanceRef = (0, _react.useRef)(new Map());
+   var heightsRef = (0, _react.useRef)(new _CacheMap.default());
+   var promiseIdRef = (0, _react.useRef)(0);
++  var disabledRef = (0, _react.useRef)(disabled);
++  disabledRef.current = disabled;
+   function cancelRaf() {
+     promiseIdRef.current += 1;
+   }
+   function collectHeight() {
+     var sync = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : false;
+     cancelRaf();
++    if (disabledRef.current) {
++      return;
++    }
+     var doCollect = function doCollect() {
+       var changed = false;
+       instanceRef.current.forEach(function (element, key) {
+@@ -87,5 +92,10 @@ function useHeights(getKey, onItemAdd, onItemRemove) {
+   (0, _react.useEffect)(function () {
+     return cancelRaf;
+   }, []);
++  (0, _react.useEffect)(function () {
++    if (!disabled) {
++      collectHeight(true);
++    }
++  }, [disabled]);
+   return [setInstanceRef, collectHeight, heightsRef.current, updatedMark];
+ }