Release/0.8.6

合并 release/0.8.6，发布 GoNavi v0.8.6。

.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/release.yaml

@@ -0,0 +1,26 @@
+changelog:
+  categories:
+    - title: 新功能
+      labels:
+        - feature
+        - enhancement
+        - feat
+    - title: 问题修复
+      labels:
+        - bug
+        - fix
+    - title: 文档与流程
+      labels:
+        - docs
+        - documentation
+        - ci
+        - workflow
+        - chore
+    - title: 重构与优化
+      labels:
+        - refactor
+        - perf
+        - optimization
+    - title: 其他更新
+      labels:
+        - '*'

.github/workflows/docker-images.yml

@@ -0,0 +1,251 @@
+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 }}
+
+      - 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 34116:34116 -e GONAVI_WEB_ADDR=0.0.0.0:34116 -e GONAVI_WEB_PASSWORD=123456 codex-smoke/${{ matrix.image_name }}:local web-server)"
+          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 http://127.0.0.1:34116/__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 http://127.0.0.1:34116/__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":""}' http://127.0.0.1:34116/__gonavi/auth/login)"
+          grep -Fq '"success":true' <<<"$login"
+          app_status="$(curl --silent --show-error -o /dev/null -w '%{http_code}' -b "$cookie_jar" http://127.0.0.1:34116/)"
+          [[ "$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 }}
+
+      - 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/release-winget.yml

@@ -1,22 +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
-
-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 }}

.gitignore

@@ -1,19 +1,37 @@
 # IDE
 .idea/
 *.iml
-
+.gitignore
 # build / release artifacts
 frontend/release/
 **/release/
 **/dist/
-**/build/
+build/bin/
 
 # wails / node artifacts (按需)
 node_modules/
+frontend/wailsjs/tsconfig.json
 
 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/需求追踪/
+
+CLAUDE.md
+**/CLAUDE.md
+.worktrees
+docs
+.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 包”的分发能力。

CONTRIBUTING.md

@@ -0,0 +1,143 @@
+# Contributing Guide
+
+Thank you for contributing to this project.
+
+This repository uses `dev` as the default integration branch, while stable releases are published from `main` through `release/*` branches.
+
+---
+
+## Branch Model
+
+- `dev`: default branch and day-to-day integration branch
+- `main`: stable release branch
+- `release/*`: release preparation branches for maintainers
+- Recommended branch names for external contributors:
+  - `fix/*`: bug fixes
+  - `feature/*`: new features or enhancements
+
+Maintainer release flow:
+
+```text
+feature/* / fix/* -> dev -> release/* -> main -> tag(vX.Y.Z)
+```
+
+---
+
+## How External Contributors Should Open Pull Requests
+
+Whether your branch is `fix/*` or `feature/*`, external contributors should **open pull requests directly against `dev`**.
+
+Reasons:
+
+- `dev` is the active integration branch, so changes can be reviewed in the same lane as ongoing work
+- contributors align with the branch that triggers day-to-day validation and dev builds
+- maintainers can cut `release/*` branches from `dev` without re-syncing external changes first
+
+Recommended flow:
+
+1. Fork this repository
+2. Sync your fork with `dev` and create a branch from `dev` (`fix/*` or `feature/*` is recommended)
+3. Make your changes and perform basic self-checks
+4. Push the branch to your fork
+5. Open a pull request against the `dev` branch of this repository
+
+---
+
+## Pull Request Requirements
+
+Please keep each pull request focused, reviewable, and easy to validate.
+
+Recommended expectations:
+
+- one pull request should address one logical change
+- use a clear title that explains the purpose
+- include the following in the description:
+  - background and problem statement
+  - key changes
+  - impact scope
+  - validation method
+- include screenshots or recordings for UI changes when helpful
+- explicitly mention risk and rollback notes for compatibility, data, or build-chain changes
+
+---
+
+## Merge Strategy for Maintainers
+
+Pull requests merged into `dev` should generally use **Squash and merge**.
+
+Reasons:
+
+- keeps `dev` history readable and easier to audit during active iteration
+- maps each PR to a single integration commit on `dev`
+- reduces cherry-pick and conflict cost before creating `release/*`
+
+---
+
+## Maintainer Sync Rules
+
+Because external pull requests are merged directly into `dev`, maintainers should treat `dev` as the source branch for daily collaboration and release preparation.
+
+### 1. Create `release/*` from `dev`
+
+Before a release, create a release branch from `dev`, for example:
+
+```bash
+git checkout dev
+git pull
+git checkout -b release/v0.6.0
+git push -u origin release/v0.6.0
+```
+
+### 2. Release from `release/*` back to `main`
+
+When release preparation is complete, merge the release branch back into `main` and create a tag:
+
+```bash
+git checkout main
+git pull
+git merge release/v0.6.0
+git push
+git tag v0.6.0
+git push origin v0.6.0
+```
+
+### 3. Sync `main` back to `dev` after release
+
+After the release, sync `main` back into `dev` so the next iteration starts from the released code line:
+
+```bash
+git checkout dev
+git pull
+git merge main
+git push
+```
+
+---
+
+## Commit Message Recommendation
+
+Keep commit messages clear and easy to audit.
+
+Recommended format:
+
+```text
+emoji type(scope): concise description
+```
+
+Examples:
+
+```text
+🔧 fix(ci): fix DuckDB driver toolchain on Windows AMD64
+✨ feat(redis): add Stream data browsing support
+♻️ refactor(datagrid): optimize large-table horizontal scrolling and rendering
+```
+
+---
+
+## Additional Notes
+
+- Please include validation results for documentation, build-chain, or driver compatibility changes
+- For larger changes, opening an issue or draft PR first is recommended
+- Maintainers may ask contributors to narrow the scope if the change conflicts with the current project direction
+
+Thank you for contributing.

CONTRIBUTING.zh-CN.md

@@ -0,0 +1,143 @@
+# 贡献指南
+
+感谢你对本项目的贡献。
+
+本项目当前采用“`dev` 作为默认集成分支，`main` 作为稳定发布分支，`release/*` 负责发版准备”的协作模型。为减少分支漂移与 PR 处理成本，请在提交贡献前先阅读本指南。
+
+---
+
+## 分支模型
+
+- `dev`：默认分支，也是日常开发集成分支
+- `main`：稳定发布分支
+- `release/*`：发布准备分支，主要供维护者使用
+- 外部贡献者建议使用以下分支命名：
+  - `fix/*`：问题修复
+  - `feature/*`：功能新增或增强
+
+维护者发布流转如下：
+
+```text
+feature/* / fix/* -> dev -> release/* -> main -> tag(vX.Y.Z)
+```
+
+---
+
+## 外部贡献者如何提 Pull Request
+
+无论是 `fix/*` 还是 `feature/*`，**外部贡献者统一直接向 `dev` 发起 Pull Request**。
+
+这样做的原因：
+
+- `dev` 是当前日常集成分支，评审与合入路径和维护者开发流程一致
+- 外部贡献会直接进入触发日常校验和 dev 构建的分支
+- 维护者可以直接从 `dev` 切 `release/*`，减少额外同步步骤
+
+建议流程：
+
+1. Fork 本仓库
+2. 先同步你 fork 中的 `dev`，再从 `dev` 创建分支（建议命名为 `fix/*` 或 `feature/*`）
+3. 完成代码修改，并进行必要自检
+4. 推送到你的远程分支
+5. 向本仓库的 `dev` 分支发起 Pull Request
+
+---
+
+## Pull Request 要求
+
+请尽量保证 PR 单一、清晰、可审核。
+
+建议遵循以下要求：
+
+- 一个 PR 只解决一类问题，避免混入无关改动
+- 标题清晰说明改动目的
+- 描述中说明：
+  - 背景与问题
+  - 变更点
+  - 影响范围
+  - 验证方式
+- 如涉及 UI 调整，建议附截图或录屏
+- 如涉及兼容性、数据变更或构建链路调整，请明确说明风险和回滚方式
+
+---
+
+## PR 合并策略（维护者）
+
+`dev` 分支上的 PR 建议使用 **Squash and merge**。
+
+原因：
+
+- 保持 `dev` 集成历史清晰、便于审查
+- 每个 PR 在 `dev` 上对应一个明确的集成提交
+- 降低发版前整理与冲突处理成本
+
+---
+
+## 维护者同步规则
+
+由于外部 PR 会直接合入 `dev`，维护者应将 `dev` 作为日常协作与发版准备的主线分支。
+
+### 1. 发版前从 dev 切 release/*
+
+发布前由维护者基于 `dev` 创建发布分支，例如：
+
+```bash
+git checkout dev
+git pull
+git checkout -b release/v0.6.0
+git push -u origin release/v0.6.0
+```
+
+### 2. release/* → main 发版
+
+发布准备完成后，将 `release/*` 合并回 `main`，并打标签发布：
+
+```bash
+git checkout main
+git pull
+git merge release/v0.6.0
+git push
+git tag v0.6.0
+git push origin v0.6.0
+```
+
+### 3. main 回流到 dev（发版后必做）
+
+发布完成后，需要将 `main` 回流到 `dev`，确保下一轮开发从已发布代码线继续推进：
+
+```bash
+git checkout dev
+git pull
+git merge main
+git push
+```
+
+---
+
+## 提交建议
+
+建议保持提交信息简洁、明确，便于维护者审查与后续追踪。
+
+推荐格式：
+
+```text
+emoji type(scope): 中文描述
+```
+
+示例：
+
+```text
+🔧 fix(ci): 修复 Windows AMD64 下 DuckDB 驱动构建工具链
+✨ feat(redis): 新增 Stream 类型数据浏览支持
+♻️ refactor(datagrid): 优化大表横向滚动与渲染结构
+```
+
+---
+
+## 其他说明
+
+- 文档、构建链路、驱动兼容性相关改动，请尽量附带验证结果
+- 若改动较大，建议先提 Issue 或 Draft PR，先对齐方案再实施
+- 如提交内容与项目当前架构方向冲突，维护者可能要求收敛范围后再合并
+
+感谢你的贡献。

Dockerfile.build-env

@@ -0,0 +1,55 @@
+# 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/*
+
+WORKDIR /workspace
+
+CMD ["bash"]

Dockerfile.mcp-server

@@ -0,0 +1,47 @@
+# 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 \
+    && chown -R gonavi:gonavi /data /var/lib/gonavi
+
+COPY --from=builder /out/gonavi-mcp-server /usr/local/bin/gonavi-mcp-server
+
+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,62 @@
+# 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 ./
+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 \
+    && chown -R gonavi:gonavi /data /var/lib/gonavi
+
+COPY --from=builder /out/gonavi /usr/local/bin/gonavi
+
+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"]

README.md

@@ -1,162 +1,391 @@
-# GoNavi - 现代化的轻量级数据库管理工具
+# GoNavi - A Modern Lightweight Database Client
 
 [![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)
 
-**GoNavi** 是一款基于 **Wails (Go)** 和 **React** 构建的现代化、高性能、跨平台数据库管理客户端。它旨在提供如原生应用般流畅的用户体验，同时保持极低的资源占用。
+**Language**: English | [简体中文](README.zh-CN.md)
 
-相比于 Electron 应用，GoNavi 的体积更小（~10MB），启动速度更快，内存占用更低。
+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.
 
-<h2 align="center">📸 项目截图</h2>
+Compared with many Electron-based clients, GoNavi is typically smaller in binary size (around 10MB class), starts faster, and uses less memory.
+
+---
+
+## Project Overview
+
+GoNavi is designed for developers and DBAs who need a unified desktop experience across multiple databases.
+
+- **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.
+
+## Supported Data Sources
+
+> `Built-in`: available out of the box.  
+> `Optional driver agent`: install/enable via Driver Manager first.
+
+| 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/341cda98-79a5-4198-90f3-1335131ccde0" />
-    <img width="25%" alt="image" src="https://github.com/user-attachments/assets/224a74e7-65df-4aef-9710-d8e82e3a70c1" />
-    <img width="25%" alt="image" src="https://github.com/user-attachments/assets/ec522145-5ceb-4481-ae46-a9251c89bdfc" />
+    <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/330ce49b-45f1-4919-ae14-75f7d47e5f73" />
-    <img width="14%" alt="image" src="https://github.com/user-attachments/assets/d15fa9e9-5486-423b-a0e9-53b467e45432" />
-    <img width="25%" alt="image" src="https://github.com/user-attachments/assets/f0c57590-d987-4ecf-89b2-64efad60b6d7" />
+    <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>
 
 ---
 
-## ✨ 核心特性
+## Key Features
 
-### 🚀 极致性能
-- **零卡顿交互**：采用独创的 "幽灵拖拽" (Ghost Resizing) 技术，在包含数万行数据的表格中调整列宽，依然保持 60fps+ 的丝滑体验。
-- **虚拟滚动**：轻松处理海量数据展示，拒绝卡顿。
+### 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.
+- **Built-in MCP Workflow**: Manage MCP servers in AI Settings, install GoNavi MCP to Claude Code / Codex, or expose Streamable HTTP for remote Agents.
+- **Remote-Agent Boundary**: Keep saved connections and database passwords on the host running GoNavi while cloud Agents consume schema tools over MCP.
+- **Safety Guardrails**: Remote `schema-only` mode omits `execute_sql`; when SQL execution is enabled, non-read-only statements still require explicit `allowMutating=true`.
 
-### 🔌 多数据库支持
-- **MySQL**：完整支持，涵盖数据编辑、结构管理与导入导出。
-- **PostgreSQL**：数据查看与编辑支持，事务提交能力持续完善。
-- **SQLite**：本地文件数据库支持。
-- **Oracle**：基础数据访问与编辑支持。
-- **Dameng（达梦）**：基础数据访问与编辑支持。
-- **Kingbase（人大金仓）**：基础数据访问与编辑支持。
-- **Redis**：Key/Value 浏览、命令执行、视图与编码切换。
-- **自定义驱动**：支持配置 Driver/DSN 接入更多数据源。
-- **SSH 隧道**：内置 SSH 隧道支持，安全连接内网数据库。
+### Performance
+- **Smooth interaction under load**: optimized table interaction (including column resize workflow on large datasets).
+- **Virtualized rendering**: keeps large result sets responsive.
 
-### 📊 强大的数据管理 (DataGrid)
-- **所见即所得编辑**：直接在表格中双击单元格修改数据。
-- **批量事务操作**：支持批量新增、修改、删除，一键提交或回滚事务。
-- **大字段编辑**：双击大字段自动打开弹窗编辑器，避免卡顿。
-- **右键上下文菜单**：快速设置 NULL、复制/导出等操作。
-- **智能上下文**：自动识别单表查询，解锁编辑功能；复杂查询自动切换为只读模式。
-- **批量导出/备份**：支持表与数据库的批量导出/备份。
-- **数据导出**：支持 CSV、Excel (XLSX)、JSON、Markdown 等格式。
+### 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.
 
-### 🧩 Redis 视图与编码
-- **视图模式切换**：自动/原始文本/UTF-8/十六进制多模式显示。
-- **智能解码**：针对二进制值进行 UTF-8 质量判定与中文字符识别。
-- **命令执行**：内置命令面板快速操作。
+### Batch Export / Backup
+- Database-level and table-level batch export/backup.
+- Scope-aware operation flow to reduce mistakes.
 
-### 🔄 数据同步与导入导出
-- **连接配置导入/导出**：支持配置 JSON 导入导出，便于团队共享。
-- **数据同步**：内置数据同步面板，支持跨库同步任务配置。
+### 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.
 
-### 🧾 可观测性
-- **SQL 执行日志**：实时查看 SQL 与执行耗时，便于排障与优化。
+### Observability and Update
+- SQL execution logs with timing information.
+- Startup/scheduled/manual update checks.
 
-### 📝 智能 SQL 编辑器
-- **Monaco Editor 内核**：集成 VS Code 同款编辑器，体验极佳。
-- **智能补全**：自动感知当前连接上下文，提供数据库、表名、字段名的实时补全。
-- **多标签页**：支持多窗口并行操作，像浏览器一样管理你的查询会话。
-
-### 🎨 现代化 UI
-- **Ant Design 5**：企业级 UI 设计语言。
-- **暗黑模式**：内置深色/浅色主题切换，适应不同光照环境。
-- **响应式布局**：灵活的侧边栏与布局调整。
+### 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
-*   **状态管理**: Zustand
-*   **编辑器**: Monaco Editor
+- **Backend**: Go 1.24 + Wails v2
+- **Frontend**: React 18 + TypeScript + Vite
+- **UI**: Ant Design 5
+- **State Management**: Zustand
+- **Editor**: Monaco Editor
 
 ---
 
-## 📦 安装与运行
+## Installation and Run
 
-### 前置要求
-*   [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`
+### 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@v2.11.0`
 
-### 开发模式
+### Development Mode
 
-```bash
-# 克隆项目
+```shell
+# Clone
 git clone https://github.com/Syngnat/GoNavi.git
 cd GoNavi
 
-# 启动开发服务器 (支持热重载)
+# Start development with hot reload
 wails dev
+
+# Faster local startup when exported Go method signatures are unchanged
+node tools/wails-fast-dev.mjs
+
+# Refresh Wails JS bindings after changing exported Go method signatures
+node tools/wails-fast-dev.mjs --refresh-bindings
+
+# Windows desktop builds use an opaque WebView without an Acrylic backdrop by default.
 ```
 
-### 编译构建
+### Build
 
 ```bash
-# 构建当前平台的可执行文件
+# Build for current platform
 wails build
 
-# 清理并构建 (推荐发布前使用)
+# Clean build (recommended before release)
 wails build -clean
 ```
 
-构建产物将位于 `build/bin` 目录下。
+Artifacts are generated in `build/bin`.
 
-### 跨平台编译 (GitHub Actions)
+### Browser Access Mode (Web Server, Experimental)
 
-本项目内置了 GitHub Actions 流水线，Push `v*` 格式的 Tag 即可自动触发构建并发布 Release。
-支持构建：
-*   macOS (AMD64 / ARM64)
-*   Windows (AMD64)
+GoNavi provides a `web-server` mode that reuses the same Go backend and React frontend for browser access (**not** a containerized desktop Wails window).
+
+#### Run locally
+
+```powershell
+go build .
+.\GoNavi-Wails.exe web-server --addr 127.0.0.1:34116
+```
+
+Without a configured password, the first browser visit is redirected to `/setup` to create the web admin password. Google Authenticator is optional but supported out of the box, together with `web_auth.json`, session cookies, recovery codes, and login rate limiting.
+
+Current scope already includes:
+
+- Browser-side Wails bridge (`window.go.*` / `window.runtime.*` -> HTTP / SSE)
+- First-run setup page, login page, and logout endpoint
+- Session idle timeout / absolute timeout / remember-login window
+- Google Authenticator TOTP plus recovery codes
+- Docker / Compose packaging (below)
+
+Still in progress:
+
+- Browser upload/download workbenches for external SQL and connection-package flows
+- More web capability gating for desktop-only features
+- Reverse-proxy / HTTPS / zero-trust deployment guidance
+
+#### Docker / Podman (Web Server)
+
+```bash
+cp docker.web-server.env.example docker.web-server.env
+# set GONAVI_HOST_DATA_ROOT to an absolute path
+# optionally set GONAVI_WEB_PASSWORD to at least 6 characters
+docker compose --env-file docker.web-server.env -f docker-compose.web-server.yml up -d
+```
+
+You can alternatively put the same variables in the project-level `.env` file and omit `--env-file docker.web-server.env`.
+
+Open `http://127.0.0.1:34116` (or the mapped host port). When `GONAVI_WEB_PASSWORD` is set, a newly created container synchronizes it and opens the login page directly. Otherwise, complete `/setup` on first visit.
+
+Mount the GoNavi active data root at `/data`. Prefer including `connections.json`, `daily_secrets.json`, and optional `drivers/`. Web auth state is stored as `web_auth.json` in that directory.
+
+`GONAVI_WEB_PASSWORD` takes precedence over the password hash already stored in `web_auth.json`, while preserving 2FA and session settings. Removing the variable leaves the last synchronized password active. Treat the env file as a secret because the plaintext value is visible to users who can inspect the container; restrict its file permissions.
+
+After changing the env password, recreate the container so Compose reloads the env file:
+
+```bash
+docker compose --env-file docker.web-server.env -f docker-compose.web-server.yml up -d --force-recreate
+```
+
+Docker Desktop Restart and `docker restart` keep the old container environment and do not reload the env file.
+
+On a new deployment, an environment password starts password-only authentication. To enable 2FA, leave `GONAVI_WEB_PASSWORD` empty for the initial `/setup`, then set it to the same password before recreating the container.
+
+The container listens on `0.0.0.0:34116` by default (`GONAVI_WEB_ADDR`). **Do not expose an unhardened Web entrypoint to the public internet**; use a reverse proxy and HTTPS for production.
+
+Default Compose pulls the GHCR image. For a local source build, add the override:
+
+```bash
+docker compose --env-file docker.web-server.env \
+  -f docker-compose.web-server.yml \
+  -f docker-compose.web-server.local.yml \
+  up -d --build
+```
+
+Health check: `GET /__gonavi/healthz`.
+
+### Docker / Podman (MCP Server)
+
+Container packaging also provides `gonavi-mcp-server` (MCP HTTP only; no desktop GUI / Web UI).
+
+```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
+```
+
+Mount the GoNavi active data root into the container. The mounted directory should contain `connections.json`, `daily_secrets.json`, and optional `drivers/` assets when optional driver agents are required.
+
+The default Compose file pulls the published GHCR image. For local source builds, add the override file:
+
+```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
+```
+
+For Podman, use the same published OCI image with `podman run`, or the native Quadlet example under [deploy/podman/gonavi-mcp-server](deploy/podman/gonavi-mcp-server). That path is intended for Linux servers / NAS hosts where rootless systemd services are preferred.
+
+Deployment matrix:
+
+- Web UI: `docker-compose.web-server.yml` (`ghcr.io/syngnat/gonavi-web-server`)
+- MCP: `docker-compose.mcp-server.yml` (`ghcr.io/syngnat/gonavi-mcp-server`)
+- Podman / Quadlet: [deploy/podman/gonavi-mcp-server](deploy/podman/gonavi-mcp-server)
+- Kubernetes: [deploy/k8s/gonavi-mcp-server](deploy/k8s/gonavi-mcp-server) (`kustomization.yaml` + overlays)
+- Helm chart: [deploy/helm/gonavi-mcp-server](deploy/helm/gonavi-mcp-server)
+- Build-only Linux environment: `Dockerfile.build-env`
+
+See [cmd/gonavi-mcp-server/README.md](cmd/gonavi-mcp-server/README.md) for deployment details and security boundaries.
+
+### Docker / Podman (Build Environment Only)
+
+If you only need a reproducible Linux build environment for Wails, use `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
+```
+
+The same Dockerfile also works with Podman, for example `podman build -f Dockerfile.build-env -t localhost/gonavi-build-env:local .` and `podman run --rm -it -v "$PWD:/workspace" -w /workspace localhost/gonavi-build-env:local bash`.
+
+The default image installs the WebKitGTK 4.0 build toolchain for broader Linux/NAS compatibility. The image bases are multi-arch, so `amd64` and `arm64` follow the target container platform.
+
+Published images are pushed to GHCR:
+
+- `ghcr.io/syngnat/gonavi-web-server:latest`
+- `ghcr.io/syngnat/gonavi-mcp-server:latest`
+- `ghcr.io/syngnat/gonavi-build-env:latest`
+
+This image is for building Linux artifacts only. It does not turn the Wails desktop GUI into a browser-accessible web application.
+
+### Cross-Platform Release (GitHub Actions)
+
+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)
 
 ---
 
-## ❓ 常见问题 (Troubleshooting)
+## Troubleshooting
 
-### macOS 提示 "应用已损坏，无法打开"
+### macOS: "App is damaged and can’t be opened"
 
-由于本项目尚未购买 Apple 开发者证书进行签名（Notarization），macOS 的 Gatekeeper 安全机制可能会拦截应用的运行。请按照以下步骤解决：
+Without Apple notarization, Gatekeeper may block startup.
 
-1.  将下载的 `GoNavi.app` 拖入 **应用程序** 文件夹。
-2.  打开 **终端 (Terminal)**。
-3.  复制并执行以下命令（输入密码时不会显示）：
-    ```bash
-    sudo xattr -rd com.apple.quarantine /Applications/GoNavi.app
-    ```
-4.  或者：在 Finder 中右键点击应用图标，按住 `Control` 键选择 **打开**，然后在弹出的窗口中再次点击 **打开**。
+1. Move `GoNavi.app` to **Applications**.
+2. Open **Terminal**.
+3. Run:
+
+```bash
+sudo xattr -rd com.apple.quarantine /Applications/GoNavi.app
+```
+
+Or right-click the app in Finder and choose **Open** with Control key flow.
+
+### Linux: missing `libwebkit2gtk` / `libjavascriptcoregtk`
+
+GoNavi depends on WebKitGTK runtime libraries.
+
+```bash
+# Debian 13 / Ubuntu 24.04+
+sudo apt-get update
+sudo apt-get install -y libgtk-3-0 libwebkit2gtk-4.1-0 libjavascriptcoregtk-4.1-0
+
+# Ubuntu 22.04 / Debian 12
+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+.
+
+### Linux: Chinese text appears as square boxes
+
+Minimal Ubuntu 24.04 LTS desktop/server environments may not include Chinese CJK fonts. Install Noto / WenQuanYi fonts and restart GoNavi:
+
+```bash
+sudo apt-get update
+sudo apt-get install -y fonts-noto-cjk fonts-wqy-microhei
+fc-cache -fv
+```
 
 ---
 
-## 🤝 贡献指南
+## Contributing
 
-欢迎提交 Issue 和 Pull Request！
+Issues and pull requests are welcome.
 
-1.  Fork 本仓库
-2.  创建你的特性分支 (`git checkout -b feature/AmazingFeature`)
-3.  提交你的改动 (`git commit -m 'feat: Add some AmazingFeature'`)
-4.  推送到分支 (`git push origin feature/AmazingFeature`)
-5.  开启一个 Pull Request
+For the full workflow, branch model, and maintainer sync rules, see:
 
-## 📄 开源协议
+- [CONTRIBUTING.md](CONTRIBUTING.md)
 
-本项目采用 [Apache-2.0 协议](LICENSE) 开源。
+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>
+
+## Links
+
+- [linux.do](https://linux.do/)
+- [AIBook](https://aibook.ren/)
+
+## License
+
+Licensed under [Apache-2.0](LICENSE).

README.zh-CN.md

@@ -0,0 +1,377 @@
+# GoNavi - 现代化轻量级数据库客户端
+
+[![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)
+
+**语言**: [English](README.md) | 简体中文
+
+GoNavi 是基于 **Wails (Go)** 与 **React** 构建的跨平台数据库管理工具，强调原生性能、低资源占用与多数据源统一工作流。
+
+相比常见 Electron 客户端，GoNavi 在体积、启动速度和内存占用上更轻量。
+
+---
+
+## 项目简介
+
+GoNavi 面向开发者与 DBA，核心目标是让数据库操作在桌面端做到“快、稳、统一”。
+
+- **原生性能架构**：Wails（Go + WebView），降低运行时开销。
+- **大数据可用性**：虚拟滚动 + DataGrid 交互优化，提升大结果集可操作性。
+- **统一连接能力**：支持 URI 生成/解析、SSH 隧道、代理、驱动按需安装。
+- **工程化能力完整**：覆盖 SQL 编辑、对象管理、批量导出/备份、数据同步、执行日志、在线更新。
+
+## 支持的数据源
+
+> `内置`：主程序开箱即用。  
+> `可选驱动代理`：需在驱动管理中安装启用后可用。
+
+| 类别 | 数据源 | 驱动模式 | 典型能力 |
+|---|---|---|---|
+| 关系型 | 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>
+
+---
+
+## 核心特性
+
+### AI 智能助手 (New)
+- **多模型服务商支持**：内置跨平台接入 OpenAI, Google Gemini, Anthropic Claude，同时支持任意自定义兼容 OpenAI 格式的 API。
+- **关联表结构上下文**：原生支持将当前数据库表结构直接提取作为上下文发送给 AI，让 SQL 生成、分析变得更精准。
+- **快捷指令**：内置多种快捷对话指（如一键生成 SQL、解释执行逻辑、分析性能优化、表字段代码评审等）。
+- **内置 MCP 工作流**：可在 AI 设置里管理 MCP 服务，一键安装 GoNavi MCP 到 Claude Code / Codex，或开启 Streamable HTTP 供远端 Agent 使用。
+- **远端 Agent 边界清晰**：数据库连接与密码继续保留在运行 GoNavi 的主机上，云端 Agent 通过 MCP 读取结构与上下文。
+- **安全控制可追溯**：远端 `schema-only` 模式默认不暴露 `execute_sql`；如开启 SQL 执行，非只读语句仍需显式传入 `allowMutating=true`。
+
+### 性能与交互
+- 大数据场景下保持流畅交互（含 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@v2.11.0`
+
+### 开发模式
+
+```shell
+# 克隆项目
+git clone https://github.com/Syngnat/GoNavi.git
+cd GoNavi
+
+# 启动开发（热重载）
+wails dev
+
+# 本地快速启动：未修改 Go 导出方法签名时使用
+node tools/wails-fast-dev.mjs
+
+# 修改 Go 导出方法签名后刷新 Wails JS 绑定
+node tools/wails-fast-dev.mjs --refresh-bindings
+
+# Windows 桌面端默认使用不透明 WebView，并关闭 Acrylic 背景
+```
+
+### 编译构建
+
+```bash
+# 构建当前平台
+wails build
+
+# 清理后构建（发布前推荐）
+wails build -clean
+```
+
+构建产物位于 `build/bin`。
+
+### 浏览器访问版（Web Server，实验中）
+
+仓库主程序提供 `web-server` 运行模式，用同一套 Go 后端 + React 前端提供浏览器访问入口（**不是**桌面 Wails 窗口容器化）。
+
+#### 本机直接启动
+
+```powershell
+go build .
+.\GoNavi-Wails.exe web-server --addr 127.0.0.1:34116
+```
+
+未配置密码时，首次访问会进入 `/setup` 完成 Web 管理员密码初始化；可选启用 Google Authenticator，服务端会落地 `web_auth.json`、Session Cookie、恢复码与登录失败限流。
+
+当前阶段已具备：
+
+- 浏览器端 Wails bridge（`window.go.*` / `window.runtime.*` -> HTTP / SSE）
+- 首次初始化页、登录页、登出接口
+- Session 空闲超时 / 绝对超时 / 记住登录时长
+- Google Authenticator TOTP 与恢复码
+- Docker / Compose 部署入口（见下方）
+
+当前仍在继续收口：
+
+- 外部 SQL / 连接包导入导出等文件型能力的浏览器上传下载工作台
+- 更多桌面专属能力的 Web 门禁与替代交互
+- 反向代理 / HTTPS / 零信任部署说明
+
+#### Docker / Podman（Web Server）
+
+```bash
+cp docker.web-server.env.example docker.web-server.env
+# 编辑 GONAVI_HOST_DATA_ROOT 为绝对路径
+# 可选设置至少 6 位的 GONAVI_WEB_PASSWORD
+docker compose --env-file docker.web-server.env -f docker-compose.web-server.yml up -d
+```
+
+也可以把相同变量写入项目目录下的标准 `.env` 文件，此时可省略 `--env-file docker.web-server.env`。
+
+浏览器打开 `http://127.0.0.1:34116`（或宿主机映射端口）。设置 `GONAVI_WEB_PASSWORD` 后，新创建的容器会同步该密码并直接进入登录页；未设置时首次访问完成 `/setup`。
+
+Web 工具中心支持通过浏览器上传/下载连接恢复包；数据目录页显示当前容器挂载目录。Docker 的数据根目录由 `GONAVI_HOST_DATA_ROOT` 挂载控制，如需切换请修改 env 后重新创建容器，避免在容器内迁移到未持久化路径。
+
+请把 GoNavi 活动数据目录挂载为 `/data`。建议至少包含 `connections.json`、`daily_secrets.json`；如需可选驱动代理应包含 `drivers/`。Web 认证状态写入同目录下的 `web_auth.json`。
+
+`GONAVI_WEB_PASSWORD` 会覆盖 `web_auth.json` 中已有的密码哈希，但保留 2FA 和会话策略；移除环境变量后继续使用最后一次同步的密码。env 文件包含明文密码，可被有容器检查权限的用户看到，请限制文件读取权限。
+
+修改 env 密码后，需要重新创建容器，让 Compose 重新读取 env 文件：
+
+```bash
+docker compose --env-file docker.web-server.env -f docker-compose.web-server.yml up -d --force-recreate
+```
+
+Docker Desktop 的 Restart 和 `docker restart` 会沿用旧容器环境，不会重新读取 env 文件。
+
+新部署直接设置环境密码时会启用纯密码认证。如需启用 2FA，请先留空 `GONAVI_WEB_PASSWORD` 并通过 `/setup` 初始化，再将它设置为同一密码后重新创建容器。
+
+容器内默认监听 `0.0.0.0:34116`（`GONAVI_WEB_ADDR`）。**不要把未加固的 Web 入口直接暴露到公网**；生产环境请配合反向代理与 HTTPS。
+
+默认 Compose 拉取 GHCR 预构建镜像。本地源码构建叠加 override：
+
+```bash
+docker compose --env-file docker.web-server.env \
+  -f docker-compose.web-server.yml \
+  -f docker-compose.web-server.local.yml \
+  up -d --build
+```
+
+健康检查：`GET /__gonavi/healthz`。
+
+### Docker / Podman（MCP Server）
+
+容器化另提供 `gonavi-mcp-server`（仅 MCP HTTP，不含桌面 GUI / Web UI）。
+
+```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
+```
+
+请把 GoNavi 的活动数据目录挂载进容器。该目录内至少应包含 `connections.json`、`daily_secrets.json`，如需可选驱动代理还应包含 `drivers/`。
+
+默认 Compose 会直接拉取 GHCR 预构建镜像。如果你要用当前仓库源码本地构建，再叠加一个 override：
+
+```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
+```
+
+如果你使用 Podman，可直接复用同一套 OCI 镜像，走 `podman run` 或 Quadlet。仓库内已经提供 [deploy/podman/gonavi-mcp-server](deploy/podman/gonavi-mcp-server) 作为 Podman 原生部署入口，适合 Linux 服务器 / NAS 的 rootless systemd 常驻服务。
+
+部署矩阵：
+
+- Web UI：`docker-compose.web-server.yml`（镜像 `ghcr.io/syngnat/gonavi-web-server`）
+- MCP：`docker-compose.mcp-server.yml`（镜像 `ghcr.io/syngnat/gonavi-mcp-server`）
+- Podman / Quadlet：[deploy/podman/gonavi-mcp-server](deploy/podman/gonavi-mcp-server)
+- Kubernetes：[deploy/k8s/gonavi-mcp-server](deploy/k8s/gonavi-mcp-server)（`kustomization.yaml` + overlays）
+- Helm Chart：[deploy/helm/gonavi-mcp-server](deploy/helm/gonavi-mcp-server)
+- 仅构建环境：`Dockerfile.build-env`
+
+完整部署方式与安全边界见 [cmd/gonavi-mcp-server/README.md](cmd/gonavi-mcp-server/README.md)。
+
+### Docker / Podman（仅构建环境）
+
+如果只是想要一套稳定的 Linux 构建环境来编译 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
+```
+
+同一个 Dockerfile 也可以直接给 Podman 使用，例如 `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`。
+
+这个镜像默认安装 WebKitGTK 4.0 构建依赖，兼容面更适合常见 Linux / NAS 场景。镜像底座本身支持多架构，`amd64` / `arm64` 会跟随容器平台。
+
+仓库会把预构建镜像推送到 GHCR：
+
+- `ghcr.io/syngnat/gonavi-web-server:latest`
+- `ghcr.io/syngnat/gonavi-mcp-server:latest`
+- `ghcr.io/syngnat/gonavi-build-env:latest`
+
+这个镜像只负责构建 Linux 产物，不会把 Wails 桌面 GUI 变成可浏览器访问的 Web 服务。
+
+### 跨平台发布（GitHub Actions）
+
+仓库内置发布流水线，推送 `v*` Tag 可自动构建并发布 Release。
+Release 更新说明会基于已合并 Pull Request 自动生成，并按 `.github/release.yaml` 分类。
+
+支持目标：
+- macOS (AMD64 / ARM64)
+- Windows (AMD64)
+- Linux (AMD64，含 WebKitGTK 4.0 / 4.1 变体)
+
+---
+
+## 常见问题
+
+### macOS 提示“应用已损坏，无法打开”
+
+在未进行 Apple Notarization 时，Gatekeeper 可能拦截应用。
+
+```bash
+sudo xattr -rd com.apple.quarantine /Applications/GoNavi.app
+```
+
+### Linux 缺少 `libwebkit2gtk` / `libjavascriptcoregtk`
+
+```bash
+# Debian 13 / Ubuntu 24.04+
+sudo apt-get update
+sudo apt-get install -y libgtk-3-0 libwebkit2gtk-4.1-0 libjavascriptcoregtk-4.1-0
+
+# Ubuntu 22.04 / Debian 12
+sudo apt-get update
+sudo apt-get install -y libgtk-3-0 libwebkit2gtk-4.0-37 libjavascriptcoregtk-4.0-18
+```
+
+### Linux 中文显示为方框
+
+Ubuntu 24.04 LTS 的最小化桌面或服务器环境可能没有安装中文 CJK 字体，GoNavi 打开后中文会显示为方框。安装 Noto / 文泉驿字体后重启 GoNavi：
+
+```bash
+sudo apt-get update
+sudo apt-get install -y fonts-noto-cjk fonts-wqy-microhei
+fc-cache -fv
+```
+
+---
+
+## 贡献指南
+
+欢迎提交 Issue 与 Pull Request。
+
+完整流程、分支模型与维护者同步规则请查看：
+
+- [CONTRIBUTING.zh-CN.md](CONTRIBUTING.zh-CN.md)
+
+外部贡献者应从 `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>
+
+## 友情链接
+
+- [linux.do](https://linux.do/)
+- [AI全书](https://aibook.ren/)
+
+## 开源协议
+
+本项目采用 [Apache-2.0 协议](LICENSE)。

assets_dev.go

@@ -0,0 +1,9 @@
+//go:build dev
+
+package main
+
+import "os"
+
+// 开发模式下由 Wails DevServer 提供前端资源，这里只提供一个稳定的占位 FS，
+// 避免编译时依赖 frontend/dist 被并发重建。
+var assets = os.DirFS(".")

assets_prod.go

@@ -0,0 +1,13 @@
+//go:build !dev
+
+package main
+
+import (
+	"embed"
+	"io/fs"
+)
+
+//go:embed all:frontend/dist
+var embeddedAssets embed.FS
+
+var assets fs.FS = embeddedAssets

build-driver-agents.sh

@@ -0,0 +1,461 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+cd "$SCRIPT_DIR"
+
+DEFAULT_DRIVERS=(mariadb oceanbase doris starrocks sphinx sqlserver sqlite duckdb dameng kingbase highgo vastbase opengauss gaussdb iris mongodb tdengine iotdb clickhouse elasticsearch)
+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'
+用法：
+  ./build-driver-agents.sh [选项]
+
+选项：
+  --drivers <列表>      指定驱动列表（逗号分隔），例如：kingbase,mongodb
+  --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
+}
+
+normalize_driver() {
+  local name
+  name="$(echo "${1:-}" | tr '[:upper:]' '[:lower:]' | xargs)"
+  case "$name" in
+    doris|diros) echo "doris" ;;
+    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)
+      echo "$name"
+      ;;
+    *)
+      return 1
+      ;;
+  esac
+}
+
+build_driver_name() {
+  case "$1" in
+    doris) echo "diros" ;;
+    *) echo "$1" ;;
+  esac
+}
+
+platform_dir_name() {
+  case "$1" in
+    windows) echo "Windows" ;;
+    darwin) echo "MacOS" ;;
+    linux) echo "Linux" ;;
+    *) echo "Unknown" ;;
+  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
+    --drivers)
+      driver_csv="${2:-}"
+      shift 2
+      ;;
+    --platform)
+      target_platform="${2:-}"
+      shift 2
+      ;;
+    --out-dir)
+      out_root="${2:-}"
+      shift 2
+      ;;
+    --bundle-name)
+      bundle_name="${2:-}"
+      shift 2
+      ;;
+    --strict)
+      strict_mode="true"
+      shift
+      ;;
+    --upx)
+      upx_mode="required"
+      shift
+      ;;
+    --no-upx)
+      upx_mode="off"
+      shift
+      ;;
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    *)
+      echo "❌ 未知参数：$1"
+      usage
+      exit 1
+      ;;
+  esac
+done
+
+if ! command -v go >/dev/null 2>&1; then
+  echo "❌ 未找到 Go，请先安装 Go 并确保 go 在 PATH 中。"
+  exit 1
+fi
+
+declare -a drivers=()
+if [[ -n "$driver_csv" ]]; then
+  IFS=',' read -r -a raw_drivers <<<"$driver_csv"
+  for item in "${raw_drivers[@]}"; do
+    normalized="$(normalize_driver "$item")" || {
+      echo "❌ 不支持的驱动：$item"
+      exit 1
+    }
+    drivers+=("$normalized")
+  done
+else
+  drivers=("${DEFAULT_DRIVERS[@]}")
+fi
+revision_driver_csv="$(join_by_comma "${drivers[@]}")"
+
+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")"
+
+cleanup() {
+  rm -rf "$bundle_stage_dir"
+}
+trap cleanup EXIT
+
+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 "   平台：${platforms[*]}"
+echo "   输出根目录：$out_root_abs"
+echo "   驱动列表：${drivers[*]}"
+
+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"
+
+  mkdir -p "$output_dir" "$bundle_platform_dir"
+  output_dir_abs="$(cd "$output_dir" && pwd)"
+
+  echo ""
+  echo "🧭 生成 driver-agent revision 指纹：$platform"
+  "$SCRIPT_DIR/tools/generate-driver-agent-revisions.sh" --platform "$platform" --drivers "$revision_driver_csv"
+
+  for driver in "${drivers[@]}"; do
+    if [[ "$driver" == "duckdb" && "$goos" == "windows" && "$goarch" != "amd64" ]]; then
+      echo "⚠️  跳过 duckdb（$platform 仅支持 windows/amd64）"
+      skipped_drivers+=("duckdb($platform)")
+      continue
+    fi
+
+    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
+  echo "❌ 未成功构建任何驱动代理。"
+  exit 1
+fi
+
+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 "   单文件输出根目录：$out_root_abs"
+echo "   驱动总包：$bundle_zip_path"
+echo "   已构建：${built_assets[*]}"
+if [[ ${#skipped_drivers[@]} -gt 0 ]]; then
+  echo "   已跳过：${skipped_drivers[*]}"
+fi
+if [[ ${#failed_drivers[@]} -gt 0 ]]; then
+  echo "⚠️  构建失败驱动：${failed_drivers[*]}"
+  exit 2
+fi

build-release.sh

@@ -1,18 +1,44 @@
 #!/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="-X GoNavi-Wails/internal/app.AppVersion=$VERSION"
+LDFLAGS="-s -w -X GoNavi-Wails/internal/app.AppVersion=$VERSION"
 
 # 颜色配置
 GREEN='\033[0;32m'
@@ -20,124 +46,182 @@ 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
+        echo 0
+        return
+    fi
+    if stat -f%z "$target" >/dev/null 2>&1; then
+        stat -f%z "$target"
+        return
+    fi
+    if stat -c%s "$target" >/dev/null 2>&1; then
+        stat -c%s "$target"
+        return
+    fi
+    wc -c <"$target" | tr -d '[:space:]'
+}
+
+format_size_mb() {
+    local bytes="${1:-0}"
+    awk -v b="$bytes" 'BEGIN { printf "%.2fMB", b / 1024 / 1024 }'
+}
+
+try_compress_binary_with_upx() {
+    local exe_path="$1"
+    local label="$2"
+    if [ ! -f "$exe_path" ]; then
+        echo -e "${RED}   ❌ 未找到 ${label} 文件：$exe_path${NC}"
+        exit 1
+    fi
+
+    if ! command -v upx >/dev/null 2>&1; then
+        echo -e "${RED}   ❌ 未找到 upx，${label} 必须进行压缩后才能继续打包。${NC}"
+        case "$(uname -s)" in
+            Darwin)
+                echo "      安装命令: brew install upx"
+                ;;
+            Linux)
+                echo "      安装命令: sudo apt-get install -y upx-ucl  (或对应发行版包管理器)"
+                ;;
+        esac
+        exit 1
+    fi
+
+    local before_bytes after_bytes
+    before_bytes=$(get_file_size_bytes "$exe_path")
+    echo "   🗜️  正在使用 UPX 压缩 ${label}..."
+    if upx --best --lzma --force "$exe_path" >/dev/null 2>&1; then
+        if ! upx -t "$exe_path" >/dev/null 2>&1; then
+            echo -e "${RED}   ❌ UPX 校验失败：${label}${NC}"
+            exit 1
+        fi
+        after_bytes=$(get_file_size_bytes "$exe_path")
+        if [ "$after_bytes" -lt "$before_bytes" ]; then
+            local saved_bytes=$((before_bytes - after_bytes))
+            echo "   ✅ UPX 压缩完成: $(format_size_mb "$before_bytes") -> $(format_size_mb "$after_bytes")，减少 $(format_size_mb "$saved_bytes")"
+        else
+            echo "   ℹ️  UPX 压缩完成: $(format_size_mb "$before_bytes") -> $(format_size_mb "$after_bytes")"
+        fi
+    else
+        echo -e "${RED}   ❌ UPX 压缩失败：${label}${NC}"
+        exit 1
+    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 -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"
-    
-    # 创建 DMG
-    if command -v create-dmg &> /dev/null; then
-        echo "   📦 正在打包 DMG (arm64)..."
-        # 移除已存在的 DMG (以防万一)
-        rm -f "$DIST_DIR/$DMG_NAME"
-        
-        create-dmg \
-            --volname "${APP_NAME} ${VERSION}" \
-            --volicon "build/appicon.icns" \
-            --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" \
-            "$DIST_DIR/$APP_DEST_NAME"
-        
-        # 检查是否生成了 rw.* 的临时文件并重命名 (create-dmg 有时会有此行为)
-        if [ ! -f "$DIST_DIR/$DMG_NAME" ]; then
-             RW_FILE=$(find "$DIST_DIR" -name "rw.*.dmg" -print -quit)
-             if [ -n "$RW_FILE" ]; then
-                 echo -e "${YELLOW}   ⚠️  检测到临时文件名，正在重命名...${NC}"
-                 mv "$RW_FILE" "$DIST_DIR/$DMG_NAME"
-             fi
-        fi
-
-        # 删除中间的 .app 文件，保持目录整洁
-        rm -rf "$DIST_DIR/$APP_DEST_NAME"
-        
-        if [ -f "$DIST_DIR/$DMG_NAME" ]; then
-             echo "   ✅ 已生成 $DMG_NAME"
-        else
-             echo -e "${RED}   ❌ DMG 生成失败，请检查 create-dmg 输出。${NC}"
-        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"
-    
-    if command -v create-dmg &> /dev/null; then
-        echo "   📦 正在打包 DMG (amd64)..."
-        rm -f "$DIST_DIR/$DMG_NAME"
-        
-        create-dmg \
-            --volname "${APP_NAME} ${VERSION}" \
-            --volicon "build/appicon.icns" \
-            --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" \
-            "$DIST_DIR/$APP_DEST_NAME"
-
-        # 检查是否生成了 rw.* 的临时文件并重命名
-        if [ ! -f "$DIST_DIR/$DMG_NAME" ]; then
-             RW_FILE=$(find "$DIST_DIR" -name "rw.*.dmg" -print -quit)
-             if [ -n "$RW_FILE" ]; then
-                 echo -e "${YELLOW}   ⚠️  检测到临时文件名，正在重命名...${NC}"
-                 mv "$RW_FILE" "$DIST_DIR/$DMG_NAME"
-             fi
-        fi
-        
-        rm -rf "$DIST_DIR/$APP_DEST_NAME"
-        
-        if [ -f "$DIST_DIR/$DMG_NAME" ]; then
-             echo "   ✅ 已生成 $DMG_NAME"
-        else
-             echo -e "${RED}   ❌ DMG 生成失败。${NC}"
-        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
+    generate_driver_agent_revisions "windows/amd64"
     wails build -platform windows/amd64 -clean -ldflags "$LDFLAGS"
     if [ $? -eq 0 ]; then
-        mv "$BUILD_BIN_DIR/${DEFAULT_BINARY_NAME}.exe" "$DIST_DIR/${APP_NAME}-${VERSION}-windows-amd64.exe"
+        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}"
@@ -146,12 +230,16 @@ fi
 # --- Windows ARM64 构建 ---
 echo -e "${GREEN}🪟 正在构建 Windows (arm64)...${NC}"
 if command -v aarch64-w64-mingw32-gcc &> /dev/null; then
+    generate_driver_agent_revisions "windows/arm64"
     wails build -platform windows/arm64 -clean -ldflags "$LDFLAGS"
     if [ $? -eq 0 ]; then
-        mv "$BUILD_BIN_DIR/${DEFAULT_BINARY_NAME}.exe" "$DIST_DIR/${APP_NAME}-${VERSION}-windows-arm64.exe"
+        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}"
@@ -166,10 +254,13 @@ CURRENT_ARCH=$(uname -m)
 
 if [ "$CURRENT_OS" = "Linux" ] && [ "$CURRENT_ARCH" = "x86_64" ]; then
     # 本机 Linux amd64，直接构建
+    generate_driver_agent_revisions "linux/amd64"
     wails build -platform linux/amd64 -clean -ldflags "$LDFLAGS"
     if [ $? -eq 0 ]; then
-        mv "$BUILD_BIN_DIR/${DEFAULT_BINARY_NAME}" "$DIST_DIR/${APP_NAME}-${VERSION}-linux-amd64"
-        chmod +x "$DIST_DIR/${APP_NAME}-${VERSION}-linux-amd64"
+        TARGET_LINUX_BIN="$DIST_DIR/${APP_NAME}-${VERSION}-linux-amd64"
+        mv "$BUILD_BIN_DIR/${DEFAULT_BINARY_NAME}" "$TARGET_LINUX_BIN"
+        chmod +x "$TARGET_LINUX_BIN"
+        try_compress_binary_with_upx "$TARGET_LINUX_BIN" "Linux amd64 可执行文件"
         # 打包为 tar.gz
         cd "$DIST_DIR"
         tar -czvf "${APP_NAME}-${VERSION}-linux-amd64.tar.gz" "${APP_NAME}-${VERSION}-linux-amd64"
@@ -178,16 +269,20 @@ 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
+    generate_driver_agent_revisions "linux/amd64"
     wails build -platform linux/amd64 -clean -ldflags "$LDFLAGS"
     if [ $? -eq 0 ]; then
-        mv "$BUILD_BIN_DIR/${DEFAULT_BINARY_NAME}" "$DIST_DIR/${APP_NAME}-${VERSION}-linux-amd64"
-        chmod +x "$DIST_DIR/${APP_NAME}-${VERSION}-linux-amd64"
+        TARGET_LINUX_BIN="$DIST_DIR/${APP_NAME}-${VERSION}-linux-amd64"
+        mv "$BUILD_BIN_DIR/${DEFAULT_BINARY_NAME}" "$TARGET_LINUX_BIN"
+        chmod +x "$TARGET_LINUX_BIN"
+        try_compress_binary_with_upx "$TARGET_LINUX_BIN" "Linux amd64 可执行文件"
         cd "$DIST_DIR"
         tar -czvf "${APP_NAME}-${VERSION}-linux-amd64.tar.gz" "${APP_NAME}-${VERSION}-linux-amd64"
         rm "${APP_NAME}-${VERSION}-linux-amd64"
@@ -195,6 +290,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
@@ -206,10 +302,13 @@ fi
 echo -e "${GREEN}🐧 正在构建 Linux (arm64)...${NC}"
 if [ "$CURRENT_OS" = "Linux" ] && [ "$CURRENT_ARCH" = "aarch64" ]; then
     # 本机 Linux arm64，直接构建
+    generate_driver_agent_revisions "linux/arm64"
     wails build -platform linux/arm64 -clean -ldflags "$LDFLAGS"
     if [ $? -eq 0 ]; then
-        mv "$BUILD_BIN_DIR/${DEFAULT_BINARY_NAME}" "$DIST_DIR/${APP_NAME}-${VERSION}-linux-arm64"
-        chmod +x "$DIST_DIR/${APP_NAME}-${VERSION}-linux-arm64"
+        TARGET_LINUX_BIN="$DIST_DIR/${APP_NAME}-${VERSION}-linux-arm64"
+        mv "$BUILD_BIN_DIR/${DEFAULT_BINARY_NAME}" "$TARGET_LINUX_BIN"
+        chmod +x "$TARGET_LINUX_BIN"
+        try_compress_binary_with_upx "$TARGET_LINUX_BIN" "Linux arm64 可执行文件"
         cd "$DIST_DIR"
         tar -czvf "${APP_NAME}-${VERSION}-linux-arm64.tar.gz" "${APP_NAME}-${VERSION}-linux-arm64"
         rm "${APP_NAME}-${VERSION}-linux-arm64"
@@ -217,16 +316,20 @@ 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
+    generate_driver_agent_revisions "linux/arm64"
     wails build -platform linux/arm64 -clean -ldflags "$LDFLAGS"
     if [ $? -eq 0 ]; then
-        mv "$BUILD_BIN_DIR/${DEFAULT_BINARY_NAME}" "$DIST_DIR/${APP_NAME}-${VERSION}-linux-arm64"
-        chmod +x "$DIST_DIR/${APP_NAME}-${VERSION}-linux-arm64"
+        TARGET_LINUX_BIN="$DIST_DIR/${APP_NAME}-${VERSION}-linux-arm64"
+        mv "$BUILD_BIN_DIR/${DEFAULT_BINARY_NAME}" "$TARGET_LINUX_BIN"
+        chmod +x "$TARGET_LINUX_BIN"
+        try_compress_binary_with_upx "$TARGET_LINUX_BIN" "Linux arm64 可执行文件"
         cd "$DIST_DIR"
         tar -czvf "${APP_NAME}-${VERSION}-linux-arm64.tar.gz" "${APP_NAME}-${VERSION}-linux-arm64"
         rm "${APP_NAME}-${VERSION}-linux-arm64"
@@ -234,6 +337,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
@@ -251,6 +355,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 ..
@@ -259,6 +366,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 ..
@@ -266,13 +376,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/darwin/Info.dev.plist

@@ -0,0 +1,68 @@
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+    <dict>
+        <key>CFBundlePackageType</key>
+        <string>APPL</string>
+        <key>CFBundleName</key>
+        <string>{{.Info.ProductName}}</string>
+        <key>CFBundleExecutable</key>
+        <string>{{.OutputFilename}}</string>
+        <key>CFBundleIdentifier</key>
+        <string>com.wails.{{.Name}}.dev</string>
+        <key>CFBundleVersion</key>
+        <string>{{.Info.ProductVersion}}</string>
+        <key>CFBundleGetInfoString</key>
+        <string>{{.Info.Comments}}</string>
+        <key>CFBundleShortVersionString</key>
+        <string>{{.Info.ProductVersion}}</string>
+        <key>CFBundleIconFile</key>
+        <string>iconfile</string>
+        <key>LSMinimumSystemVersion</key>
+        <string>10.13.0</string>
+        <key>NSHighResolutionCapable</key>
+        <string>true</string>
+        <key>NSHumanReadableCopyright</key>
+        <string>{{.Info.Copyright}}</string>
+        {{if .Info.FileAssociations}}
+        <key>CFBundleDocumentTypes</key>
+        <array>
+          {{range .Info.FileAssociations}}
+          <dict>
+            <key>CFBundleTypeExtensions</key>
+            <array>
+              <string>{{.Ext}}</string>
+            </array>
+            <key>CFBundleTypeName</key>
+            <string>{{.Name}}</string>
+            <key>CFBundleTypeRole</key>
+            <string>{{.Role}}</string>
+            <key>CFBundleTypeIconFile</key>
+            <string>{{.IconName}}</string>
+          </dict>
+          {{end}}
+        </array>
+        {{end}}
+        {{if .Info.Protocols}}
+        <key>CFBundleURLTypes</key>
+        <array>
+          {{range .Info.Protocols}}
+            <dict>
+                <key>CFBundleURLName</key>
+                <string>com.wails.{{.Scheme}}</string>
+                <key>CFBundleURLSchemes</key>
+                <array>
+                    <string>{{.Scheme}}</string>
+                </array>
+                <key>CFBundleTypeRole</key>
+                <string>{{.Role}}</string>
+            </dict>
+          {{end}}
+        </array>
+        {{end}}
+        <key>NSAppTransportSecurity</key>
+        <dict>
+            <key>NSAllowsLocalNetworking</key>
+            <true/>
+        </dict>
+    </dict>
+</plist>

build/darwin/Info.plist

@@ -0,0 +1,63 @@
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+    <dict>
+        <key>CFBundlePackageType</key>
+        <string>APPL</string>
+        <key>CFBundleName</key>
+        <string>{{.Info.ProductName}}</string>
+        <key>CFBundleExecutable</key>
+        <string>{{.OutputFilename}}</string>
+        <key>CFBundleIdentifier</key>
+        <string>com.wails.{{.Name}}</string>
+        <key>CFBundleVersion</key>
+        <string>{{.Info.ProductVersion}}</string>
+        <key>CFBundleGetInfoString</key>
+        <string>{{.Info.Comments}}</string>
+        <key>CFBundleShortVersionString</key>
+        <string>{{.Info.ProductVersion}}</string>
+        <key>CFBundleIconFile</key>
+        <string>iconfile</string>
+        <key>LSMinimumSystemVersion</key>
+        <string>10.13.0</string>
+        <key>NSHighResolutionCapable</key>
+        <string>true</string>
+        <key>NSHumanReadableCopyright</key>
+        <string>{{.Info.Copyright}}</string>
+        {{if .Info.FileAssociations}}
+        <key>CFBundleDocumentTypes</key>
+        <array>
+          {{range .Info.FileAssociations}}
+          <dict>
+            <key>CFBundleTypeExtensions</key>
+            <array>
+              <string>{{.Ext}}</string>
+            </array>
+            <key>CFBundleTypeName</key>
+            <string>{{.Name}}</string>
+            <key>CFBundleTypeRole</key>
+            <string>{{.Role}}</string>
+            <key>CFBundleTypeIconFile</key>
+            <string>{{.IconName}}</string>
+          </dict>
+          {{end}}
+        </array>
+        {{end}}
+        {{if .Info.Protocols}}
+        <key>CFBundleURLTypes</key>
+        <array>
+          {{range .Info.Protocols}}
+            <dict>
+                <key>CFBundleURLName</key>
+                <string>com.wails.{{.Scheme}}</string>
+                <key>CFBundleURLSchemes</key>
+                <array>
+                    <string>{{.Scheme}}</string>
+                </array>
+                <key>CFBundleTypeRole</key>
+                <string>{{.Role}}</string>
+            </dict>
+          {{end}}
+        </array>
+        {{end}}
+    </dict>
+</plist>

build/windows/info.json

@@ -0,0 +1,15 @@
+{
+	"fixed": {
+		"file_version": "{{.Info.ProductVersion}}"
+	},
+	"info": {
+		"0000": {
+			"ProductVersion": "{{.Info.ProductVersion}}",
+			"CompanyName": "{{.Info.CompanyName}}",
+			"FileDescription": "{{.Info.ProductName}}",
+			"LegalCopyright": "{{.Info.Copyright}}",
+			"ProductName": "{{.Info.ProductName}}",
+			"Comments": "{{.Info.Comments}}"
+		}
+	}
+}

build/windows/wails.exe.manifest

@@ -0,0 +1,15 @@
+<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<assembly manifestVersion="1.0" xmlns="urn:schemas-microsoft-com:asm.v1" xmlns:asmv3="urn:schemas-microsoft-com:asm.v3">
+    <assemblyIdentity type="win32" name="com.wails.{{.Name}}" version="{{.Info.ProductVersion}}.0" processorArchitecture="*"/>
+    <dependency>
+        <dependentAssembly>
+            <assemblyIdentity type="win32" name="Microsoft.Windows.Common-Controls" version="6.0.0.0" processorArchitecture="*" publicKeyToken="6595b64144ccf1df" language="*"/>
+        </dependentAssembly>
+    </dependency>
+    <asmv3:application>
+        <asmv3:windowsSettings>
+            <dpiAware xmlns="http://schemas.microsoft.com/SMI/2005/WindowsSettings">true/pm</dpiAware> <!-- fallback for Windows 7 and 8 -->
+            <dpiAwareness xmlns="http://schemas.microsoft.com/SMI/2016/WindowsSettings">permonitorv2,permonitor</dpiAwareness> <!-- falls back to per-monitor if per-monitor v2 is not supported -->
+        </asmv3:windowsSettings>
+    </asmv3:application>
+</assembly>

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/manualtestseed/main.go

@@ -0,0 +1,339 @@
+package main
+
+import (
+	"encoding/json"
+	"flag"
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+	"time"
+
+	"GoNavi-Wails/internal/ai"
+	aiservice "GoNavi-Wails/internal/ai/service"
+	"GoNavi-Wails/internal/app"
+	"GoNavi-Wails/internal/connection"
+	"GoNavi-Wails/internal/secretstore"
+)
+
+const (
+	modeSeedSecureStorage = "seed-secure-storage"
+	modeSeedAIUpdate      = "seed-ai-update"
+)
+
+const (
+	testConnectionID       = "manualtest-postgres"
+	testSecureProviderID   = "manualtest-secure-provider"
+	testPendingProviderID  = "manualtest-pending-provider"
+	testBackupDirName      = "manual-test-backups"
+	connectionsFileName    = "connections.json"
+	globalProxyFileName    = "global_proxy.json"
+	aiConfigFileName       = "ai_config.json"
+	securityUpdateFileName = "config-security-update.json"
+)
+
+type backupManifest struct {
+	CreatedAt string               `json:"createdAt"`
+	ConfigDir string               `json:"configDir"`
+	Files     []backupManifestFile `json:"files"`
+}
+
+type backupManifestFile struct {
+	RelativePath string `json:"relativePath"`
+	Existed      bool   `json:"existed"`
+}
+
+type storedAIConfig struct {
+	SchemaVersion  int                 `json:"schemaVersion,omitempty"`
+	Providers      []ai.ProviderConfig `json:"providers"`
+	ActiveProvider string              `json:"activeProvider"`
+	SafetyLevel    string              `json:"safetyLevel"`
+	ContextLevel   string              `json:"contextLevel"`
+}
+
+func main() {
+	mode := flag.String("mode", modeSeedSecureStorage, "seed mode: seed-secure-storage | seed-ai-update")
+	flag.Parse()
+
+	configDir, err := resolveConfigDir()
+	if err != nil {
+		fatalf("resolve config dir failed: %v", err)
+	}
+
+	store := secretstore.NewKeyringStore()
+	if err := store.HealthCheck(); err != nil {
+		fatalf("secret store unavailable: %v", err)
+	}
+
+	backupDir, err := backupConfigFiles(configDir)
+	if err != nil {
+		fatalf("backup config files failed: %v", err)
+	}
+
+	switch strings.TrimSpace(*mode) {
+	case modeSeedSecureStorage:
+		if err := seedSecureStorage(configDir, store); err != nil {
+			fatalf("seed secure storage failed: %v", err)
+		}
+		fmt.Printf("mode=%s\nbackup=%s\nconnectionId=%s\nproviderId=%s\n", modeSeedSecureStorage, backupDir, testConnectionID, testSecureProviderID)
+	case modeSeedAIUpdate:
+		if err := seedAIUpdate(configDir, store); err != nil {
+			fatalf("seed ai update failed: %v", err)
+		}
+		fmt.Printf("mode=%s\nbackup=%s\npendingProviderId=%s\n", modeSeedAIUpdate, backupDir, testPendingProviderID)
+	default:
+		fatalf("unsupported mode: %s", *mode)
+	}
+}
+
+func fatalf(format string, args ...any) {
+	fmt.Fprintf(os.Stderr, format+"\n", args...)
+	os.Exit(1)
+}
+
+func resolveConfigDir() (string, error) {
+	homeDir, err := os.UserHomeDir()
+	if err != nil {
+		return "", err
+	}
+	return filepath.Join(homeDir, ".gonavi"), nil
+}
+
+func backupConfigFiles(configDir string) (string, error) {
+	backupDir := filepath.Join(configDir, testBackupDirName, time.Now().Format("20060102-150405"))
+	files := []string{
+		connectionsFileName,
+		globalProxyFileName,
+		aiConfigFileName,
+		filepath.Join("migrations", securityUpdateFileName),
+	}
+
+	manifest := backupManifest{
+		CreatedAt: time.Now().Format(time.RFC3339),
+		ConfigDir: configDir,
+		Files:     make([]backupManifestFile, 0, len(files)),
+	}
+
+	for _, relativePath := range files {
+		srcPath := filepath.Join(configDir, relativePath)
+		info, err := os.Stat(srcPath)
+		if err != nil {
+			if os.IsNotExist(err) {
+				manifest.Files = append(manifest.Files, backupManifestFile{
+					RelativePath: relativePath,
+					Existed:      false,
+				})
+				continue
+			}
+			return "", err
+		}
+		if info.IsDir() {
+			continue
+		}
+
+		dstPath := filepath.Join(backupDir, relativePath)
+		if err := os.MkdirAll(filepath.Dir(dstPath), 0o755); err != nil {
+			return "", err
+		}
+		data, err := os.ReadFile(srcPath)
+		if err != nil {
+			return "", err
+		}
+		if err := os.WriteFile(dstPath, data, 0o644); err != nil {
+			return "", err
+		}
+		manifest.Files = append(manifest.Files, backupManifestFile{
+			RelativePath: relativePath,
+			Existed:      true,
+		})
+	}
+
+	if err := os.MkdirAll(backupDir, 0o755); err != nil {
+		return "", err
+	}
+	manifestData, err := json.MarshalIndent(manifest, "", "  ")
+	if err != nil {
+		return "", err
+	}
+	if err := os.WriteFile(filepath.Join(backupDir, "manifest.json"), manifestData, 0o644); err != nil {
+		return "", err
+	}
+	return backupDir, nil
+}
+
+func seedSecureStorage(configDir string, store secretstore.SecretStore) error {
+	if err := cleanupKnownTestSecrets(store); err != nil {
+		return err
+	}
+
+	appService := app.NewAppWithSecretStore(store)
+	_ = appService.DeleteConnection(testConnectionID)
+
+	if _, err := appService.SaveConnection(connection.SavedConnectionInput{
+		ID:   testConnectionID,
+		Name: "手工测试 PostgreSQL",
+		Config: connection.ConnectionConfig{
+			ID:       testConnectionID,
+			Type:     "postgres",
+			Host:     "127.0.0.1",
+			Port:     5432,
+			User:     "postgres",
+			Password: "manualtest-pg-secret",
+			Database: "postgres",
+		},
+	}); err != nil {
+		return err
+	}
+
+	if _, err := appService.SaveGlobalProxy(connection.SaveGlobalProxyInput{
+		Enabled:  true,
+		Type:     "http",
+		Host:     "127.0.0.1",
+		Port:     7890,
+		User:     "manual-test",
+		Password: "manualtest-proxy-secret",
+	}); err != nil {
+		return err
+	}
+
+	storeConfig := aiservice.NewProviderConfigStore(configDir, store)
+	snapshot, err := storeConfig.LoadRuntime()
+	if err != nil {
+		return err
+	}
+	snapshot.Providers = filterProviders(snapshot.Providers, testSecureProviderID, testPendingProviderID)
+	snapshot.Providers = append(snapshot.Providers, ai.ProviderConfig{
+		ID:        testSecureProviderID,
+		Type:      "custom",
+		Name:      "手工测试 Secure Provider",
+		APIKey:    "manualtest-ai-secret",
+		BaseURL:   "https://api.openai.com/v1",
+		Model:     "gpt-4o-mini",
+		APIFormat: "openai",
+		Headers: map[string]string{
+			"Authorization": "Bearer manualtest-header-secret",
+			"X-Trace-Id":    "manualtest-visible",
+		},
+		MaxTokens:   2048,
+		Temperature: 0.2,
+	})
+	if snapshot.SafetyLevel == "" {
+		snapshot.SafetyLevel = ai.PermissionReadOnly
+	}
+	if snapshot.ContextLevel == "" {
+		snapshot.ContextLevel = ai.ContextSchemaOnly
+	}
+	return storeConfig.Save(snapshot)
+}
+
+func seedAIUpdate(configDir string, store secretstore.SecretStore) error {
+	if err := cleanupKnownTestSecrets(store); err != nil {
+		return err
+	}
+
+	configPath := filepath.Join(configDir, aiConfigFileName)
+	cfg, err := readStoredAIConfig(configPath)
+	if err != nil {
+		return err
+	}
+
+	cfg.Providers = filterProviders(cfg.Providers, testSecureProviderID, testPendingProviderID)
+	cfg.Providers = append(cfg.Providers, ai.ProviderConfig{
+		ID:        testPendingProviderID,
+		Type:      "custom",
+		Name:      "手工测试 待迁移 AI",
+		APIKey:    "manualtest-ai-update-secret",
+		BaseURL:   "https://api.openai.com/v1",
+		Model:     "gpt-4o-mini",
+		APIFormat: "openai",
+		MaxTokens: 1024,
+	})
+	if cfg.SchemaVersion == 0 {
+		cfg.SchemaVersion = 2
+	}
+	if cfg.Providers == nil {
+		cfg.Providers = []ai.ProviderConfig{}
+	}
+	if err := os.MkdirAll(configDir, 0o755); err != nil {
+		return err
+	}
+	data, err := json.MarshalIndent(cfg, "", "  ")
+	if err != nil {
+		return err
+	}
+	return os.WriteFile(configPath, data, 0o644)
+}
+
+func readStoredAIConfig(configPath string) (storedAIConfig, error) {
+	cfg := storedAIConfig{
+		Providers:      []ai.ProviderConfig{},
+		SafetyLevel:    string(ai.PermissionReadOnly),
+		ContextLevel:   string(ai.ContextSchemaOnly),
+		SchemaVersion:  2,
+		ActiveProvider: "",
+	}
+
+	data, err := os.ReadFile(configPath)
+	if err != nil {
+		if os.IsNotExist(err) {
+			return cfg, nil
+		}
+		return storedAIConfig{}, err
+	}
+	if err := json.Unmarshal(data, &cfg); err != nil {
+		return storedAIConfig{}, err
+	}
+	if cfg.Providers == nil {
+		cfg.Providers = []ai.ProviderConfig{}
+	}
+	return cfg, nil
+}
+
+func filterProviders(providers []ai.ProviderConfig, excludedIDs ...string) []ai.ProviderConfig {
+	excluded := make(map[string]struct{}, len(excludedIDs))
+	for _, id := range excludedIDs {
+		excluded[strings.TrimSpace(id)] = struct{}{}
+	}
+	filtered := make([]ai.ProviderConfig, 0, len(providers))
+	for _, provider := range providers {
+		if _, skip := excluded[strings.TrimSpace(provider.ID)]; skip {
+			continue
+		}
+		filtered = append(filtered, provider)
+	}
+	return filtered
+}
+
+func cleanupKnownTestSecrets(store secretstore.SecretStore) error {
+	type secretRef struct {
+		kind string
+		id   string
+	}
+	refs := []secretRef{
+		{kind: "connection", id: testConnectionID},
+		{kind: "global-proxy", id: "default"},
+		{kind: "ai-provider", id: testSecureProviderID},
+		{kind: "ai-provider", id: testPendingProviderID},
+	}
+
+	for _, item := range refs {
+		ref, err := secretstore.BuildRef(item.kind, item.id)
+		if err != nil {
+			return err
+		}
+		if err := store.Delete(ref); err != nil && !isIgnorableDeleteError(err) {
+			return err
+		}
+	}
+	return nil
+}
+
+func isIgnorableDeleteError(err error) bool {
+	if err == nil || os.IsNotExist(err) {
+		return true
+	}
+	message := strings.ToLower(strings.TrimSpace(err.Error()))
+	return strings.Contains(message, "could not be found") ||
+		strings.Contains(message, "not be found in the keyring") ||
+		strings.Contains(message, "element not found")
+}

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/mysql-driver-agent/main.go

@@ -0,0 +1,227 @@
+//go:build gonavi_mysql_driver
+
+package main
+
+import (
+	"bufio"
+	"encoding/json"
+	"fmt"
+	"os"
+	"strings"
+
+	"GoNavi-Wails/internal/connection"
+	"GoNavi-Wails/internal/db"
+)
+
+type mysqlAgentRequest struct {
+	ID        int64                        `json:"id"`
+	Method    string                       `json:"method"`
+	Config    *connection.ConnectionConfig `json:"config,omitempty"`
+	Query     string                       `json:"query,omitempty"`
+	DBName    string                       `json:"dbName,omitempty"`
+	TableName string                       `json:"tableName,omitempty"`
+	Changes   *connection.ChangeSet        `json:"changes,omitempty"`
+}
+
+type mysqlAgentResponse struct {
+	ID           int64       `json:"id"`
+	Success      bool        `json:"success"`
+	Error        string      `json:"error,omitempty"`
+	Data         interface{} `json:"data,omitempty"`
+	Fields       []string    `json:"fields,omitempty"`
+	RowsAffected int64       `json:"rowsAffected,omitempty"`
+}
+
+const (
+	mysqlAgentMethodConnect       = "connect"
+	mysqlAgentMethodClose         = "close"
+	mysqlAgentMethodPing          = "ping"
+	mysqlAgentMethodQuery         = "query"
+	mysqlAgentMethodExec          = "exec"
+	mysqlAgentMethodGetDatabases  = "getDatabases"
+	mysqlAgentMethodGetTables     = "getTables"
+	mysqlAgentMethodGetCreateStmt = "getCreateStatement"
+	mysqlAgentMethodGetColumns    = "getColumns"
+	mysqlAgentMethodGetAllColumns = "getAllColumns"
+	mysqlAgentMethodGetIndexes    = "getIndexes"
+	mysqlAgentMethodGetForeignKey = "getForeignKeys"
+	mysqlAgentMethodGetTriggers   = "getTriggers"
+	mysqlAgentMethodApplyChanges  = "applyChanges"
+)
+
+func main() {
+	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.MySQLDB
+	for scanner.Scan() {
+		line := strings.TrimSpace(scanner.Text())
+		if line == "" {
+			continue
+		}
+
+		var req mysqlAgentRequest
+		if err := json.Unmarshal([]byte(line), &req); err != nil {
+			_ = writeResponse(writer, mysqlAgentResponse{
+				ID:      req.ID,
+				Success: false,
+				Error:   fmt.Sprintf("解析请求失败：%v", err),
+			})
+			continue
+		}
+
+		resp := handleRequest(&inst, req)
+		if err := writeResponse(writer, resp); err != nil {
+			fmt.Fprintf(os.Stderr, "写入响应失败：%v\n", err)
+			break
+		}
+	}
+
+	if inst != nil {
+		_ = inst.Close()
+	}
+
+	if err := scanner.Err(); err != nil {
+		fmt.Fprintf(os.Stderr, "读取请求失败：%v\n", err)
+	}
+}
+
+func handleRequest(inst **db.MySQLDB, req mysqlAgentRequest) mysqlAgentResponse {
+	resp := mysqlAgentResponse{
+		ID:      req.ID,
+		Success: true,
+	}
+
+	switch strings.TrimSpace(req.Method) {
+	case mysqlAgentMethodConnect:
+		if req.Config == nil {
+			return fail(resp, "连接配置为空")
+		}
+		if *inst != nil {
+			_ = (*inst).Close()
+		}
+		next := &db.MySQLDB{}
+		if err := next.Connect(*req.Config); err != nil {
+			return fail(resp, err.Error())
+		}
+		*inst = next
+		return resp
+	case mysqlAgentMethodClose:
+		if *inst != nil {
+			if err := (*inst).Close(); err != nil {
+				return fail(resp, err.Error())
+			}
+			*inst = nil
+		}
+		return resp
+	}
+
+	if *inst == nil {
+		return fail(resp, "connection not open")
+	}
+
+	switch strings.TrimSpace(req.Method) {
+	case mysqlAgentMethodPing:
+		if err := (*inst).Ping(); err != nil {
+			return fail(resp, err.Error())
+		}
+	case mysqlAgentMethodQuery:
+		data, fields, err := (*inst).Query(req.Query)
+		if err != nil {
+			return fail(resp, err.Error())
+		}
+		resp.Data = data
+		resp.Fields = fields
+	case mysqlAgentMethodExec:
+		affected, err := (*inst).Exec(req.Query)
+		if err != nil {
+			return fail(resp, err.Error())
+		}
+		resp.RowsAffected = affected
+	case mysqlAgentMethodGetDatabases:
+		data, err := (*inst).GetDatabases()
+		if err != nil {
+			return fail(resp, err.Error())
+		}
+		resp.Data = data
+	case mysqlAgentMethodGetTables:
+		data, err := (*inst).GetTables(req.DBName)
+		if err != nil {
+			return fail(resp, err.Error())
+		}
+		resp.Data = data
+	case mysqlAgentMethodGetCreateStmt:
+		data, err := (*inst).GetCreateStatement(req.DBName, req.TableName)
+		if err != nil {
+			return fail(resp, err.Error())
+		}
+		resp.Data = data
+	case mysqlAgentMethodGetColumns:
+		data, err := (*inst).GetColumns(req.DBName, req.TableName)
+		if err != nil {
+			return fail(resp, err.Error())
+		}
+		resp.Data = data
+	case mysqlAgentMethodGetAllColumns:
+		data, err := (*inst).GetAllColumns(req.DBName)
+		if err != nil {
+			return fail(resp, err.Error())
+		}
+		resp.Data = data
+	case mysqlAgentMethodGetIndexes:
+		data, err := (*inst).GetIndexes(req.DBName, req.TableName)
+		if err != nil {
+			return fail(resp, err.Error())
+		}
+		resp.Data = data
+	case mysqlAgentMethodGetForeignKey:
+		data, err := (*inst).GetForeignKeys(req.DBName, req.TableName)
+		if err != nil {
+			return fail(resp, err.Error())
+		}
+		resp.Data = data
+	case mysqlAgentMethodGetTriggers:
+		data, err := (*inst).GetTriggers(req.DBName, req.TableName)
+		if err != nil {
+			return fail(resp, err.Error())
+		}
+		resp.Data = data
+	case mysqlAgentMethodApplyChanges:
+		if req.Changes == nil {
+			return fail(resp, "变更集为空")
+		}
+		applier, ok := interface{}(*inst).(interface {
+			ApplyChanges(tableName string, changes connection.ChangeSet) error
+		})
+		if !ok {
+			return fail(resp, "当前驱动不支持 ApplyChanges")
+		}
+		if err := applier.ApplyChanges(req.TableName, *req.Changes); err != nil {
+			return fail(resp, err.Error())
+		}
+	default:
+		return fail(resp, "不支持的方法")
+	}
+
+	return resp
+}
+
+func writeResponse(writer *bufio.Writer, resp mysqlAgentResponse) error {
+	payload, err := json.Marshal(resp)
+	if err != nil {
+		return err
+	}
+	payload = append(payload, '\n')
+	if _, err := writer.Write(payload); err != nil {
+		return err
+	}
+	return writer.Flush()
+}
+
+func fail(resp mysqlAgentResponse, errText string) mysqlAgentResponse {
+	resp.Success = false
+	resp.Error = strings.TrimSpace(errText)
+	return resp
+}

cmd/optional-driver-agent/main.go

@@ -0,0 +1,883 @@
+package main
+
+import (
+	"bufio"
+	"context"
+	"encoding/json"
+	"fmt"
+	"os"
+	"reflect"
+	"runtime"
+	"runtime/debug"
+	"strconv"
+	"strings"
+	"sync/atomic"
+	"time"
+
+	"GoNavi-Wails/internal/connection"
+	"GoNavi-Wails/internal/db"
+)
+
+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"`
+	DBName    string                       `json:"dbName,omitempty"`
+	TableName string                       `json:"tableName,omitempty"`
+	Changes   *connection.ChangeSet        `json:"changes,omitempty"`
+}
+
+type agentResponse struct {
+	ID           int64       `json:"id"`
+	Success      bool        `json:"success"`
+	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"
+	agentMethodMetadata      = "metadata"
+	agentMethodPing          = "ping"
+	agentMethodOpenSession   = "openSession"
+	agentMethodCloseSession  = "closeSession"
+	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
+
+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()
+
+	runtimeState := &agentRuntime{
+		sessions: make(map[string]db.StatementExecer),
+	}
+	for scanner.Scan() {
+		line := strings.TrimSpace(scanner.Text())
+		if line == "" {
+			continue
+		}
+
+		var req agentRequest
+		if err := json.Unmarshal([]byte(line), &req); err != nil {
+			_ = writeResponse(writer, agentResponse{
+				ID:      req.ID,
+				Success: false,
+				Error:   fmt.Sprintf("解析请求失败：%v", err),
+			})
+			continue
+		}
+
+		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))
+		}
+	}
+
+	runtimeState.close()
+
+	if err := scanner.Err(); err != nil {
+		fmt.Fprintf(os.Stderr, "读取请求失败：%v\n", err)
+	}
+}
+
+func handleRequest(runtimeState *agentRuntime, req agentRequest) agentResponse {
+	resp := agentResponse{ID: req.ID, Success: true}
+	method := strings.TrimSpace(req.Method)
+
+	switch method {
+	case agentMethodConnect:
+		if req.Config == nil {
+			return fail(resp, "连接配置为空")
+		}
+		runtimeState.close()
+		next := agentDatabaseFactory()
+		if next == nil {
+			return fail(resp, "驱动代理初始化失败")
+		}
+		if err := next.Connect(*req.Config); err != nil {
+			return fail(resp, err.Error())
+		}
+		runtimeState.inst = next
+		return resp
+	case agentMethodClose:
+		if runtimeState.inst != nil {
+			if err := runtimeState.close(); err != nil {
+				return fail(resp, err.Error())
+			}
+		}
+		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 agentMethodCloseSession:
+		if err := runtimeState.closeSession(req.SessionID); err != nil {
+			return fail(resp, err.Error())
+		}
+		return resp
+	}
+
+	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
+		default:
+			return fail(resp, "当前事务会话不支持该方法")
+		}
+		return resp
+	}
+
+	switch method {
+	case agentMethodPing:
+		if err := runtimeState.inst.Ping(); err != nil {
+			return fail(resp, err.Error())
+		}
+	case agentMethodQuery:
+		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(runtimeState.inst, req.Query, req.TimeoutMs)
+		if err != nil {
+			return fail(resp, err.Error())
+		}
+		resp.RowsAffected = affected
+	case agentMethodGetDatabases:
+		data, err := runtimeState.inst.GetDatabases()
+		if err != nil {
+			return fail(resp, err.Error())
+		}
+		resp.Data = data
+	case agentMethodGetTables:
+		data, err := runtimeState.inst.GetTables(req.DBName)
+		if err != nil {
+			return fail(resp, err.Error())
+		}
+		resp.Data = data
+	case agentMethodGetCreateStmt:
+		data, err := runtimeState.inst.GetCreateStatement(req.DBName, req.TableName)
+		if err != nil {
+			return fail(resp, err.Error())
+		}
+		resp.Data = data
+	case agentMethodGetColumns:
+		data, err := runtimeState.inst.GetColumns(req.DBName, req.TableName)
+		if err != nil {
+			return fail(resp, err.Error())
+		}
+		resp.Data = data
+	case agentMethodGetAllColumns:
+		data, err := runtimeState.inst.GetAllColumns(req.DBName)
+		if err != nil {
+			return fail(resp, err.Error())
+		}
+		resp.Data = data
+	case agentMethodGetIndexes:
+		data, err := runtimeState.inst.GetIndexes(req.DBName, req.TableName)
+		if err != nil {
+			return fail(resp, err.Error())
+		}
+		resp.Data = data
+	case agentMethodGetForeignKey:
+		data, err := runtimeState.inst.GetForeignKeys(req.DBName, req.TableName)
+		if err != nil {
+			return fail(resp, err.Error())
+		}
+		resp.Data = data
+	case agentMethodGetTriggers:
+		data, err := runtimeState.inst.GetTriggers(req.DBName, req.TableName)
+		if err != nil {
+			return fail(resp, err.Error())
+		}
+		resp.Data = data
+	case agentMethodApplyChanges:
+		if req.Changes == nil {
+			return fail(resp, "变更集为空")
+		}
+		applier, ok := runtimeState.inst.(interface {
+			ApplyChanges(tableName string, changes connection.ChangeSet) error
+		})
+		if !ok {
+			return fail(resp, "当前驱动不支持 ApplyChanges")
+		}
+		if err := applier.ApplyChanges(req.TableName, *req.Changes); err != nil {
+			return fail(resp, err.Error())
+		}
+	default:
+		return fail(resp, "不支持的方法")
+	}
+
+	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，避免序列化失败导致代理进程退出。
+	safeResp := resp
+	safeResp.Data = normalizeAgentResponseData(resp.Data)
+	payload, err := json.Marshal(safeResp)
+	if err != nil {
+		return err
+	}
+	payload = append(payload, '\n')
+	if _, err := writer.Write(payload); err != nil {
+		return err
+	}
+	return writer.Flush()
+}
+
+func fail(resp agentResponse, errText string) agentResponse {
+	resp.Success = false
+	resp.Error = strings.TrimSpace(errText)
+	return resp
+}
+
+func normalizeAgentResponseData(v interface{}) interface{} {
+	if v == nil {
+		return nil
+	}
+
+	rv := reflect.ValueOf(v)
+	switch rv.Kind() {
+	case reflect.Pointer, reflect.Interface:
+		if rv.IsNil() {
+			return nil
+		}
+		return normalizeAgentResponseData(rv.Elem().Interface())
+	case reflect.Map:
+		if rv.IsNil() {
+			return nil
+		}
+		out := make(map[string]interface{}, rv.Len())
+		iter := rv.MapRange()
+		for iter.Next() {
+			out[fmt.Sprint(iter.Key().Interface())] = normalizeAgentResponseData(iter.Value().Interface())
+		}
+		return out
+	case reflect.Slice:
+		if rv.IsNil() {
+			return nil
+		}
+		// 保持 []byte 原样，避免改变现有二进制列的 JSON 编码行为（base64）。
+		if rv.Type().Elem().Kind() == reflect.Uint8 {
+			return v
+		}
+		size := rv.Len()
+		items := make([]interface{}, size)
+		for i := 0; i < size; i++ {
+			items[i] = normalizeAgentResponseData(rv.Index(i).Interface())
+		}
+		return items
+	case reflect.Array:
+		size := rv.Len()
+		items := make([]interface{}, size)
+		for i := 0; i < size; i++ {
+			items[i] = normalizeAgentResponseData(rv.Index(i).Interface())
+		}
+		return items
+	default:
+		return v
+	}
+}
+
+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 {
+		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.(agentQueryMessageContextRunner); ok {
+		ctx, cancel := context.WithTimeout(context.Background(), time.Duration(effectiveTimeoutMs)*time.Millisecond)
+		defer cancel()
+		return q.QueryContextWithMessages(ctx, 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 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)
+	}
+	if effectiveTimeoutMs <= 0 {
+		return inst.Exec(query)
+	}
+	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

@@ -0,0 +1,601 @@
+package main
+
+import (
+	"bufio"
+	"bytes"
+	"context"
+	"encoding/json"
+	"errors"
+	"strings"
+	"testing"
+	"time"
+
+	"GoNavi-Wails/internal/connection"
+	"GoNavi-Wails/internal/db"
+)
+
+type duckMapLike map[any]any
+
+func TestWriteResponse_NormalizesMapAnyAny(t *testing.T) {
+	resp := agentResponse{
+		ID:      1,
+		Success: true,
+		Data: []map[string]interface{}{
+			{
+				"id":   int64(7),
+				"meta": duckMapLike{"k": "v", 2: "two"},
+			},
+		},
+	}
+
+	var out bytes.Buffer
+	writer := bufio.NewWriter(&out)
+	if err := writeResponse(writer, resp); err != nil {
+		t.Fatalf("writeResponse 返回错误: %v", err)
+	}
+
+	var decoded struct {
+		Data []map[string]interface{} `json:"data"`
+	}
+	if err := json.Unmarshal(bytes.TrimSpace(out.Bytes()), &decoded); err != nil {
+		t.Fatalf("解码响应失败: %v", err)
+	}
+
+	if len(decoded.Data) != 1 {
+		t.Fatalf("期望 1 行数据，实际 %d", len(decoded.Data))
+	}
+	meta, ok := decoded.Data[0]["meta"].(map[string]interface{})
+	if !ok {
+		t.Fatalf("meta 字段类型异常: %T", decoded.Data[0]["meta"])
+	}
+	if meta["k"] != "v" {
+		t.Fatalf("字符串 key 转换异常: %v", meta["k"])
+	}
+	if meta["2"] != "two" {
+		t.Fatalf("数字 key 未字符串化: %v", meta["2"])
+	}
+}
+
+func TestNormalizeAgentResponseData_KeepByteSlice(t *testing.T) {
+	raw := []byte{0x61, 0x62, 0x63}
+	normalized := normalizeAgentResponseData(raw)
+	out, ok := normalized.([]byte)
+	if !ok {
+		t.Fatalf("期望 []byte，实际 %T", normalized)
+	}
+	if !bytes.Equal(out, raw) {
+		t.Fatalf("[]byte 内容被意外改写: %v", out)
+	}
+}
+
+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 }
+func (f *fakeAgentTimeoutDB) Close() error                                     { return nil }
+func (f *fakeAgentTimeoutDB) Ping() error                                      { return nil }
+func (f *fakeAgentTimeoutDB) Query(query string) ([]map[string]interface{}, []string, error) {
+	f.queryCalled = true
+	return nil, nil, errors.New("query should not be called")
+}
+func (f *fakeAgentTimeoutDB) QueryContext(ctx context.Context, query string) ([]map[string]interface{}, []string, error) {
+	f.queryContextCalled = true
+	if _, ok := ctx.Deadline(); ok {
+		f.deadlineSet = true
+	}
+	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")
+}
+func (f *fakeAgentTimeoutDB) ExecContext(ctx context.Context, query string) (int64, error) {
+	f.execContextCalled = true
+	if _, ok := ctx.Deadline(); ok {
+		f.deadlineSet = true
+	}
+	return 3, nil
+}
+func (f *fakeAgentTimeoutDB) GetDatabases() ([]string, error) { return nil, nil }
+func (f *fakeAgentTimeoutDB) GetTables(dbName string) ([]string, error) {
+	return nil, nil
+}
+func (f *fakeAgentTimeoutDB) GetCreateStatement(dbName, tableName string) (string, error) {
+	return "", nil
+}
+func (f *fakeAgentTimeoutDB) GetColumns(dbName, tableName string) ([]connection.ColumnDefinition, error) {
+	return nil, nil
+}
+func (f *fakeAgentTimeoutDB) GetAllColumns(dbName string) ([]connection.ColumnDefinitionWithTable, error) {
+	return nil, nil
+}
+func (f *fakeAgentTimeoutDB) GetIndexes(dbName, tableName string) ([]connection.IndexDefinition, error) {
+	return nil, nil
+}
+func (f *fakeAgentTimeoutDB) GetForeignKeys(dbName, tableName string) ([]connection.ForeignKeyDefinition, error) {
+	return nil, nil
+}
+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
+}
+
+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{}
+	data, fields, err := queryWithOptionalTimeout(fake, "SELECT 1", int64((2 * time.Second).Milliseconds()))
+	if err != nil {
+		t.Fatalf("queryWithOptionalTimeout 返回错误: %v", err)
+	}
+	if !fake.queryContextCalled || fake.queryCalled {
+		t.Fatalf("query 调用路径异常，QueryContext=%v Query=%v", fake.queryContextCalled, fake.queryCalled)
+	}
+	if !fake.deadlineSet {
+		t.Fatal("queryWithOptionalTimeout 未设置 deadline")
+	}
+	if len(data) != 1 || len(fields) != 1 || fields[0] != "ok" {
+		t.Fatalf("queryWithOptionalTimeout 返回数据异常: data=%v fields=%v", data, fields)
+	}
+}
+
+func TestExecWithOptionalTimeout_UsesExecContext(t *testing.T) {
+	fake := &fakeAgentTimeoutDB{}
+	affected, err := execWithOptionalTimeout(fake, "DELETE FROM t", int64((2 * time.Second).Milliseconds()))
+	if err != nil {
+		t.Fatalf("execWithOptionalTimeout 返回错误: %v", err)
+	}
+	if !fake.execContextCalled || fake.execCalled {
+		t.Fatalf("exec 调用路径异常，ExecContext=%v Exec=%v", fake.execContextCalled, fake.execCalled)
+	}
+	if !fake.deadlineSet {
+		t.Fatal("execWithOptionalTimeout 未设置 deadline")
+	}
+	if affected != 3 {
+		t.Fatalf("受影响行数异常，want=3 got=%d", affected)
+	}
+}
+
+func TestQueryWithOptionalTimeout_ClickHouseLegacyModeUsesQueryContext(t *testing.T) {
+	old := agentDriverType
+	agentDriverType = "clickhouse"
+	defer func() { agentDriverType = old }()
+
+	fake := &fakeAgentTimeoutDB{}
+	_, _, err := queryWithOptionalTimeout(fake, "SELECT 1", 0)
+	if err != nil {
+		t.Fatalf("queryWithOptionalTimeout 返回错误: %v", err)
+	}
+	if !fake.queryContextCalled || fake.queryCalled {
+		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 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_clickhouse.go

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

cmd/optional-driver-agent/provider_dameng.go

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

cmd/optional-driver-agent/provider_diros.go

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

cmd/optional-driver-agent/provider_duckdb.go

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

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_highgo.go

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

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_kingbase.go

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

cmd/optional-driver-agent/provider_mariadb.go

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

cmd/optional-driver-agent/provider_mongodb.go

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

cmd/optional-driver-agent/provider_mongodb_v1.go

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

cmd/optional-driver-agent/provider_mysql.go

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

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_sphinx.go

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

cmd/optional-driver-agent/provider_sqlite.go

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

cmd/optional-driver-agent/provider_sqlserver.go

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

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_tdengine.go

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

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{}
+	}
+}

cmd/optional-driver-agent/provider_vastbase.go

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

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

@@ -0,0 +1,107 @@
+{
+  "engine": "go",
+  "drivers": {
+    "mariadb": {
+      "engine": "go",
+      "version": "1.9.3",
+      "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",
+      "checksumPolicy": "off",
+      "downloadUrl": "builtin://activate/doris"
+    },
+    "sphinx": {
+      "engine": "go",
+      "version": "1.9.3",
+      "checksumPolicy": "off",
+      "downloadUrl": "builtin://activate/sphinx"
+    },
+    "sqlserver": {
+      "engine": "go",
+      "version": "1.9.6",
+      "checksumPolicy": "off",
+      "downloadUrl": "builtin://activate/sqlserver"
+    },
+    "sqlite": {
+      "engine": "go",
+      "version": "1.44.3",
+      "checksumPolicy": "off",
+      "downloadUrl": "builtin://activate/sqlite"
+    },
+    "duckdb": {
+      "engine": "go",
+      "version": "2.5.6",
+      "checksumPolicy": "off",
+      "downloadUrl": "builtin://activate/duckdb"
+    },
+    "dameng": {
+      "engine": "go",
+      "version": "1.8.22",
+      "checksumPolicy": "off",
+      "downloadUrl": "builtin://activate/dameng"
+    },
+    "kingbase": {
+      "engine": "go",
+      "version": "0.0.0-20201021123113-29bd62a876c3",
+      "checksumPolicy": "off",
+      "downloadUrl": "builtin://activate/kingbase"
+    },
+    "highgo": {
+      "engine": "go",
+      "version": "0.0.0-local",
+      "checksumPolicy": "off",
+      "downloadUrl": "builtin://activate/highgo"
+    },
+    "vastbase": {
+      "engine": "go",
+      "version": "1.11.1",
+      "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",
+      "checksumPolicy": "off",
+      "downloadUrl": "builtin://activate/mongodb"
+    },
+    "tdengine": {
+      "engine": "go",
+      "version": "3.7.8",
+      "checksumPolicy": "off",
+      "downloadUrl": "builtin://activate/tdengine"
+    },
+    "clickhouse": {
+      "engine": "go",
+      "version": "2.43.1",
+      "checksumPolicy": "off",
+      "downloadUrl": "builtin://activate/clickhouse"
+    },
+    "postgres": {
+      "engine": "go",
+      "version": "1.11.1",
+      "checksumPolicy": "off",
+      "downloadUrl": "builtin://activate/postgres"
+    },
+    "elasticsearch": {
+      "engine": "go",
+      "version": "8.19.0",
+      "checksumPolicy": "off",
+      "downloadUrl": "builtin://activate/elasticsearch"
+    }
+  }
+}

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/.gitignore

@@ -0,0 +1 @@
+.ace-tool/

frontend/ai_ui_mockups_wip.html

@@ -0,0 +1,182 @@
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+    <meta charset="UTF-8">
+    <title>AI UI Brainstorming Prototypes</title>
+    <!-- React & ReactDOM -->
+    <script crossorigin src="https://unpkg.com/react@18/umd/react.development.js"></script>
+    <script crossorigin src="https://unpkg.com/react-dom@18/umd/react-dom.development.js"></script>
+    <!-- Babel -->
+    <script src="https://unpkg.com/@babel/standalone/babel.min.js"></script>
+    <!-- Ant Design -->
+    <script src="https://unpkg.com/dayjs/dayjs.min.js"></script>
+    <script src="https://unpkg.com/antd/dist/antd.min.js"></script>
+    <link rel="stylesheet" href="https://unpkg.com/antd/dist/reset.css" />
+    <!-- Icons -->
+    <script src="https://unpkg.com/@ant-design/icons/dist/index.umd.js"></script>
+    <style>
+        body { padding: 40px; background: #f0f2f5; font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial; }
+        .prototype-container { display: flex; gap: 40px; }
+        .prototype-column { flex: 1; max-width: 600px; background: white; border-radius: 12px; box-shadow: 0 4px 12px rgba(0,0,0,0.05); overflow: hidden; }
+        .prototype-header { padding: 16px 24px; border-bottom: 1px solid #f0f0f0; background: #fafafa; font-weight: bold; }
+        .prototype-body { padding: 24px; }
+        
+        /* Default App Theme Colors (Light Mode) */
+        :root {
+            --gn-border: rgba(16,24,40,0.08);
+            --gn-bg: rgba(255,255,255,0.84);
+            --gn-text: #162033;
+            --gn-muted: rgba(16,24,40,0.55);
+            --gn-primary: #1677ff;
+            --gn-primary-bg: rgba(24,144,255,0.1);
+        }
+
+        /* V1 Styles: Professional List */
+        .v1-list-item {
+            display: flex; align-items: center; justify-content: space-between;
+            padding: 12px 16px; margin-bottom: 8px; border-radius: 8px;
+            border: 1px solid transparent; cursor: pointer; transition: all 0.2s;
+        }
+        .v1-list-item:hover { background: #f5f5f5; }
+        .v1-list-item.selected {
+            background: var(--gn-primary-bg); border-color: var(--gn-primary);
+        }
+        
+        /* V2 Styles: Refined Cards (ConnectionModal Style) */
+        .v2-card-grid {
+            display: grid; grid-template-columns: 1fr 1fr; gap: 12px;
+        }
+        .v2-card {
+            padding: 16px; border-radius: 12px; border: 1px solid var(--gn-border);
+            cursor: pointer; transition: all 0.2s; background: white;
+            box-shadow: inset 0 0 0 1px rgba(16,24,40,0.01);
+        }
+        .v2-card:hover { border-color: #d9d9d9; background: #fafafa; }
+        .v2-card.selected {
+            border-color: var(--gn-primary); box-shadow: 0 0 0 1px var(--gn-primary) inset;
+        }
+        
+        .section-title { font-size: 13px; font-weight: 600; color: var(--gn-muted); margin-bottom: 12px; text-transform: uppercase; letter-spacing: 0.5px; }
+    </style>
+</head>
+<body>
+    <div id="root"></div>
+    <script type="text/babel">
+        const { useState } = React;
+        const { Input, Slider, Select, Button, Form, ConfigProvider } = antd;
+        const { ThunderboltOutlined, CloudOutlined, ExperimentOutlined, AppstoreOutlined, SettingOutlined, LinkOutlined, KeyOutlined } = icons;
+
+        const PROVIDERS = [
+            { key: 'openai', label: 'OpenAI', icon: <ThunderboltOutlined />, desc: 'GPT-4o / o1' },
+            { key: 'deepseek', label: 'DeepSeek', icon: <ThunderboltOutlined />, desc: 'V3 / R1' },
+            { key: 'anthropic', label: 'Claude', icon: <ExperimentOutlined />, desc: 'Sonnet 3.5' },
+            { key: 'custom', label: '自定义', icon: <AppstoreOutlined />, desc: '通用 API' },
+        ];
+
+        const V1ListDesign = () => {
+            const [selected, setSelected] = useState('openai');
+            return (
+                <div className="prototype-column">
+                    <div className="prototype-header">方案一：IDE 专业列表风格 (更克制、无彩色渐变)</div>
+                    <div className="prototype-body">
+                        <div className="section-title">提供商选择</div>
+                        <div style={{ marginBottom: 24, padding: 8, background: '#fafafa', borderRadius: 10, border: '1px solid #f0f0f0' }}>
+                            {PROVIDERS.map(p => (
+                                <div key={p.key} className={`v1-list-item ${selected === p.key ? 'selected' : ''}`} onClick={() => setSelected(p.key)}>
+                                    <div style={{ display: 'flex', alignItems: 'center', gap: 12 }}>
+                                        <div style={{ 
+                                            width: 32, height: 32, borderRadius: 6, display: 'grid', placeItems: 'center',
+                                            background: selected === p.key ? '#1677ff' : '#e6f4ff', 
+                                            color: selected === p.key ? '#fff' : '#1677ff', fontSize: 16
+                                        }}>
+                                            {p.icon}
+                                        </div>
+                                        <div>
+                                            <div style={{ fontWeight: 500, color: 'var(--gn-text)', fontSize: 14 }}>{p.label}</div>
+                                            <div style={{ fontSize: 12, color: 'var(--gn-muted)' }}>{p.desc}</div>
+                                        </div>
+                                    </div>
+                                    <div style={{ width: 16, height: 16, borderRadius: '50%', border: `2px solid ${selected === p.key ? 'var(--gn-primary)' : '#d9d9d9'}`, padding: 2 }}>
+                                        {selected === p.key && <div style={{ width: '100%', height: '100%', background: 'var(--gn-primary)', borderRadius: '50%' }} />}
+                                    </div>
+                                </div>
+                            ))}
+                        </div>
+                        
+                        <div className="section-title">连接配置 (紧凑表单)</div>
+                        <Form layout="vertical" size="middle">
+                            <Form.Item label="API Endpoint">
+                                <Input placeholder="https://api.openai.com/v1" prefix={<LinkOutlined style={{color: 'var(--gn-muted)'}}/>} />
+                            </Form.Item>
+                            <Form.Item label="API Key">
+                                <Input.Password placeholder="sk-..." prefix={<KeyOutlined style={{color: 'var(--gn-muted)'}}/>} />
+                            </Form.Item>
+                            <Form.Item label="Model Name">
+                                <Input placeholder="gpt-4o" prefix={<AppstoreOutlined style={{color: 'var(--gn-muted)'}}/>} />
+                            </Form.Item>
+                        </Form>
+                    </div>
+                </div>
+            );
+        };
+
+        const V2CardDesign = () => {
+            const [selected, setSelected] = useState('openai');
+            return (
+                <div className="prototype-column">
+                    <div className="prototype-header">方案二：GoNavi 统一卡片风格 (类似 ConnectionModal)</div>
+                    <div className="prototype-body">
+                        <div className="section-title">选择服务提供商</div>
+                        <div className="v2-card-grid" style={{ marginBottom: 24 }}>
+                            {PROVIDERS.map(p => (
+                                <div key={p.key} className={`v2-card ${selected === p.key ? 'selected' : ''}`} onClick={() => setSelected(p.key)}>
+                                    <div style={{ display: 'flex', alignItems: 'flex-start', gap: 12 }}>
+                                        <div style={{ color: selected === p.key ? 'var(--gn-primary)' : 'var(--gn-muted)', fontSize: 20, marginTop: 2 }}>
+                                            {p.icon}
+                                        </div>
+                                        <div>
+                                            <div style={{ fontWeight: 600, color: 'var(--gn-text)', fontSize: 14 }}>{p.label}</div>
+                                            <div style={{ fontSize: 12, color: 'var(--gn-muted)', marginTop: 4 }}>{p.desc}</div>
+                                        </div>
+                                    </div>
+                                </div>
+                            ))}
+                        </div>
+
+                        <div style={{ padding: 20, borderRadius: 12, border: '1px solid var(--gn-border)', background: '#fafafa' }}>
+                            <div className="section-title" style={{ marginTop: 0 }}>认证与设置</div>
+                            <Form layout="horizontal" labelCol={{ span: 6 }} wrapperCol={{ span: 18 }} size="middle">
+                                <Form.Item label="Endpoint" style={{ marginBottom: 16 }}>
+                                    <Input placeholder="https://api..." />
+                                </Form.Item>
+                                <Form.Item label="API Key" style={{ marginBottom: 16 }}>
+                                    <Input.Password placeholder="sk-..." />
+                                </Form.Item>
+                                <Form.Item label="模型名称" style={{ marginBottom: 0 }}>
+                                    <Input placeholder="例如 gpt-4o" />
+                                </Form.Item>
+                            </Form>
+                        </div>
+                    </div>
+                </div>
+            );
+        };
+
+        const App = () => (
+            <ConfigProvider theme={{ token: { colorPrimary: '#1677ff', borderRadius: 6 } }}>
+                <div style={{ marginBottom: 24 }}>
+                    <h1 style={{ fontSize: 24, margin: 0 }}>AI 设置 UI 重构探讨</h1>
+                    <p style={{ color: 'var(--gn-muted)' }}>当前设计带有太多渐变和鲜艳色彩（"AI 味"）。以下是遵循 GoNavi 本身设计规范（克制、专业）的两个方案：</p>
+                </div>
+                <div className="prototype-container">
+                    <V1ListDesign />
+                    <V2CardDesign />
+                </div>
+            </ConfigProvider>
+        );
+
+        const root = ReactDOM.createRoot(document.getElementById('root'));
+        root.render(<App />);
+    </script>
+</body>
+</html>

frontend/index.html

@@ -5,6 +5,23 @@
     <link rel="icon" type="image/svg+xml" href="/logo.svg" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>GoNavi</title>
+    <script>
+      if (typeof window !== 'undefined' && !window.go) {
+        window.go = {
+          app: {
+            App: new Proxy({}, { get: () => async () => ({ success: false }) })
+          }
+        };
+      }
+      if (typeof window !== 'undefined' && !window.runtime) {
+        window.runtime = new Proxy({}, { 
+            get: (target, prop) => {
+                if (prop === 'Environment') return async () => ({ platform: 'darwin' });
+                return typeof prop === 'string' && prop.startsWith('WindowIs') ? () => false : () => {};
+            }
+        });
+      }
+    </script>
   </head>
   <body>
     <div id="root"></div>