@clickzetta/cz-cli-darwin-x64 0.3.19 → 0.3.20

package/bin/skills/clickzetta-lakehouse-connect/SKILL.md

@@ -0,0 +1,218 @@
+---
+name: clickzetta-lakehouse-connect
+description: |
+  Guide for connecting to ClickZetta Lakehouse via SDK/JDBC. Covers Python SDK (clickzetta.connect), ZettaPark Session (DataFrame API), SQLAlchemy (ORM/BI tools), and JDBC (Java). Use this skill when user needs to configure a connection from external tools or code. Trigger for: "Python SDK 连接", "JDBC 连接", "SQLAlchemy 配置", "ZettaPark 怎么用", "连接报错", "clickzetta-connector-python", "clickzetta-sqlalchemy".
+  Keywords: connection, Python SDK, JDBC, SQLAlchemy, ZettaPark, driver, connect
+---
+
+# ClickZetta Lakehouse 连接指南
+
+## 指令
+
+### 步骤 0：自动获取连接参数（优先）
+
+**在询问用户之前，先尝试从本地配置文件自动读取连接参数。**
+
+按以下优先级查找配置文件（找到第一个即停止）：
+1. `/app/.clickzetta/lakehouse_connection/connections.json`
+2. `config/lakehouse_connection/connections.json`
+3. `~/.clickzetta/connections.json`
+4. `/app/.clickzetta/connections.json`
+
+找到配置文件后：
+- 解析 JSON，提取 `connections` 数组
+- 根据用户描述的区域/环境匹配对应连接（如"阿里云上海"匹配 `service` 含 `cn-shanghai-alicloud` 的连接）
+- 若有 `is_default: true` 且用户未指定区域，使用默认连接
+- **不要将密码或完整配置输出到对话中**，仅内部使用
+
+若配置文件不存在或无匹配连接，再向用户询问：service、instance、workspace、username、password、schema、vcluster。
+
+### 步骤 1：确认连接方式
+
+根据用户场景选择连接方式，阅读对应参考文件：
+
+| 用户需求 | 参考文件 |
+|:--|:--|
+| Python 脚本 / 自动化 / 执行 SQL | [references/python-sdk.md](references/python-sdk.md) |
+| DataFrame / 数据工程 | [references/zettapark-session.md](references/zettapark-session.md) |
+| ORM / Web 应用 / BI 工具（Superset） | [references/sqlalchemy.md](references/sqlalchemy.md) |
+| Java 应用 / BI 工具（DBeaver） | [references/jdbc.md](references/jdbc.md) |
+| 多环境配置文件管理 | [references/config-file.md](references/config-file.md) |
+
+不确定时参考决策树：
+- 需要 DataFrame 操作 → ZettaPark Session
+- 需要 ORM / SQLAlchemy 集成 → SQLAlchemy
+- Java 应用 → JDBC
+- 其他 Python 场景（含直接执行 SQL）→ Python SDK
+
+### 步骤 2：确认 service 地址
+
+`service` 参数必须包含区域前缀，根据实例所在区域选择：
+
+**云器 Lakehouse（国内版，`clickzetta.com`）**
+
+| 云厂商 | 区域 | service 地址 |
+|:--|:--|:--|
+| 阿里云 | 华东2（上海） | `cn-shanghai-alicloud.api.clickzetta.com` |
+| 腾讯云 | 华东（上海） | `ap-shanghai-tencentcloud.api.clickzetta.com` |
+| 腾讯云 | 华北（北京） | `ap-beijing-tencentcloud.api.clickzetta.com` |
+| 腾讯云 | 华南（广州） | `ap-guangzhou-tencentcloud.api.clickzetta.com` |
+| AWS | 中国（北京） | `cn-north-1-aws.api.clickzetta.com` |
+
+**Singdata Lakehouse（国际版，`singdata.com`）**
+
+| 云厂商 | 区域 | service 地址 |
+|:--|:--|:--|
+| 阿里云 | 亚太东南1（新加坡） | `ap-southeast-1-alicloud.api.singdata.com` |
+| AWS | 亚太（新加坡） | `ap-southeast-1-aws.api.singdata.com` |
+
+控制台：`https://{instance}.{region}.app.clickzetta.com`
+
+### 步骤 3：执行查询或提供可运行代码
+
+**若用户要求执行查询（如 SHOW SCHEMAS、SELECT、SHOW TABLES 等）：**
+
+1. 确认 `clickzetta-connector-python` 已安装：
+   ```bash
+   pip3 show clickzetta-connector-python
+   ```
+   若未安装，执行：`pip3 install clickzetta-connector-python --user`
+
+2. 使用步骤 0 获取的连接参数直接执行查询，将结果格式化后展示给用户。
+
+**若用户要求生成代码：**
+
+阅读对应参考文件后，根据参数生成完整可运行代码。所有参数均为必填，`vcluster` 默认值为 `default_ap`。
+
+密码含特殊字符时（SQLAlchemy URI），提醒用户用 `urllib.parse.quote_plus()` 编码。
+
+## 示例
+
+### 示例 0：自动读取配置并执行查询
+
+```python
+import json, os, clickzetta
+
+# 按优先级查找配置文件
+config_paths = [
+    "/app/.clickzetta/lakehouse_connection/connections.json",
+    "config/lakehouse_connection/connections.json",
+    os.path.expanduser("~/.clickzetta/connections.json"),
+    "/app/.clickzetta/connections.json",
+]
+config = None
+for path in config_paths:
+    if os.path.exists(path):
+        with open(path) as f:
+            config = json.load(f)
+        break
+
+# 选择目标连接（示例：匹配阿里云上海）
+conn_cfg = next(
+    (c for c in config["connections"] if "cn-shanghai-alicloud" in c.get("service", "")),
+    None
+) or next((c for c in config["connections"] if c.get("is_default")), config["connections"][0])
+
+conn = clickzetta.connect(
+    service=conn_cfg["service"],
+    instance=conn_cfg["instance"],
+    workspace=conn_cfg["workspace"],
+    schema=conn_cfg.get("schema", "public"),
+    username=conn_cfg["username"],
+    password=conn_cfg["password"],
+    vcluster=conn_cfg.get("vcluster", "default_ap")
+)
+cursor = conn.cursor()
+cursor.execute("SHOW SCHEMAS")
+for row in cursor.fetchall():
+    print(row[0])
+cursor.close()
+conn.close()
+```
+
+### 示例 1：Python SDK 连接并查询
+
+```python
+import clickzetta
+
+conn = clickzetta.connect(
+    service="cn-shanghai-alicloud.api.clickzetta.com",
+    instance="my_instance",
+    workspace="my_workspace",
+    schema="public",
+    username="my_user",
+    password="my_password",
+    vcluster="default_ap"
+)
+cursor = conn.cursor()
+cursor.execute("SELECT * FROM orders LIMIT 10")
+for row in cursor.fetchall():
+    print(row)
+cursor.close()
+conn.close()
+```
+
+### 示例 2：ZettaPark 按 region 汇总 revenue
+
+```python
+from clickzetta.zettapark.session import Session
+from clickzetta.zettapark import functions as F
+
+session = Session.builder.configs({
+    "service": "cn-shanghai-alicloud.api.clickzetta.com",
+    "instance": "my_instance", "workspace": "my_workspace",
+    "schema": "public", "username": "my_user",
+    "password": "my_password", "vcluster": "default_ap"
+}).create()
+
+session.table("sales") \
+    .group_by(F.col("region")) \
+    .agg(F.sum("revenue").as_("total_revenue")) \
+    .write.save_as_table("sales_summary", mode="overwrite")
+session.close()
+```
+
+## 故障排除
+
+| 错误信息 | 原因 | 解决方案 |
+|:--|:--|:--|
+| `Connection refused` | service 地址不正确或网络不通 | 检查 service 是否匹配区域（参见步骤 2 区域表） |
+| `Authentication failed` | 用户名或密码错误 | 核实 username 和 password |
+| `Workspace not found` | 工作空间名称不存在 | 在控制台确认 workspace 拼写 |
+| `Instance not found` | 实例名称不存在 | 在控制台确认 instance 拼写 |
+| `Timeout` | 查询超时 | 增大 `hints` 中的 `sdk.job.timeout`（默认 300 秒） |
+| `VCluster not available` | 虚拟集群未启动或名称错误 | 确认 vcluster 名称，检查集群状态 |
+| SQLAlchemy URL 解析错误 | 密码含特殊字符 | 用 `urllib.parse.quote_plus()` 对密码 URL 编码 |
+| `ClassNotFoundException` | JDBC 驱动未在 classpath | 确保 `clickzetta-java` JAR 已加入 classpath |
+
+## 安装
+
+> ⚠️ **Python 版本要求**：推荐 **Python 3.12**（最低 3.10）。Python 3.9 及以下不支持。
+
+| 连接方式 | 安装命令 |
+|:--|:--|
+| Python SDK | `pip install clickzetta-connector-python -i https://pypi.tuna.tsinghua.edu.cn/simple` |
+| ZettaPark | `pip install clickzetta-zettapark-python -i https://pypi.tuna.tsinghua.edu.cn/simple` |
+| SQLAlchemy | `pip install clickzetta-connector-python clickzetta-sqlalchemy -i https://pypi.tuna.tsinghua.edu.cn/simple` |
+| JDBC | Maven: `com.clickzetta:clickzetta-java` |
+
+```bash
+# 方式 1：venv（Python 内置，推荐）
+python3.12 -m venv .venv
+source .venv/bin/activate          # macOS/Linux
+# .venv\Scripts\activate           # Windows
+pip install clickzetta-connector-python clickzetta-zettapark-python \
+    -i https://pypi.tuna.tsinghua.edu.cn/simple
+
+# 方式 2：pyenv（需要切换 Python 版本时）
+pyenv install 3.12.9
+pyenv local 3.12.9
+python -m venv .venv && source .venv/bin/activate
+pip install clickzetta-connector-python clickzetta-zettapark-python \
+    -i https://pypi.tuna.tsinghua.edu.cn/simple
+
+# 方式 3：conda（数据科学环境）
+conda create -n lakehouse python=3.12 -y && conda activate lakehouse
+pip install clickzetta-connector-python clickzetta-zettapark-python \
+    -i https://pypi.tuna.tsinghua.edu.cn/simple
+```

package/bin/skills/clickzetta-lakehouse-connect/eval_cases.jsonl

@@ -0,0 +1,3 @@
+{"case_id":"001","type":"should_call","user_input":"Python SDK 怎么连接 ClickZetta Lakehouse？连接参数有哪些？","expected_skill":"clickzetta-lakehouse-connect","expected_output_contains":["clickzetta","connect"]}
+{"case_id":"002","type":"should_call","user_input":"JDBC 连接 ClickZetta 的 URL 格式是什么？","expected_skill":"clickzetta-lakehouse-connect","expected_output_contains":["jdbc","clickzetta"]}
+{"case_id":"003","type":"should_call","user_input":"SQLAlchemy 怎么配置连接 ClickZetta？","expected_skill":"clickzetta-lakehouse-connect","expected_output_contains":["sqlalchemy","clickzetta"]}

package/bin/skills/clickzetta-lakehouse-connect/evals/evals.json

@@ -0,0 +1,35 @@
+{
+  "skill_name": "clickzetta-lakehouse-connect",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "我需要用 Python 连接 ClickZetta，实例名是 my_instance，工作空间是 analytics，region 是上海阿里云，用户名 alice，密码 secret123。帮我写一段查询 orders 表前 10 行的代码。",
+      "expected_output": "使用 clickzetta.connect() 或 clickzetta-connector-python，包含所有必填参数（service/instance/workspace/schema/username/password/vcluster），并演示 cursor.execute + fetchall 查询",
+      "files": []
+    },
+    {
+      "id": 2,
+      "prompt": "我想用 ZettaPark 做数据工程，需要读取 sales 表，按 region 分组求 revenue 总和，然后写回到 sales_summary 表。帮我写完整代码。",
+      "expected_output": "使用 Session.builder.configs().create()，展示 session.table() + group_by + agg + write.save_as_table()，包含连接参数配置",
+      "files": []
+    },
+    {
+      "id": 3,
+      "prompt": "我在用 Apache Superset 连接 ClickZetta，SQLAlchemy URI 应该怎么填？密码是 P@ss#2024，需要注意什么？",
+      "expected_output": "提供正确的 clickzetta:// URI 格式，指出密码特殊字符需要 quote_plus 编码，给出编码后的示例",
+      "files": []
+    },
+    {
+      "id": 4,
+      "prompt": "连接云器 Lakehouse 报错 Connection refused，我的 service 填的是 api.clickzetta.com，实例在上海腾讯云，怎么排查？",
+      "expected_output": "识别 service 地址填错，给出正确的上海腾讯云地址 ap-shanghai-tencentcloud.api.clickzetta.com，并提供排查步骤",
+      "files": []
+    },
+    {
+      "id": 5,
+      "prompt": "我有三个环境：dev/staging/prod，都在同一个 ClickZetta 实例上但不同 workspace。想用 connections.json 统一管理，并在代码里切换。怎么配置？",
+      "expected_output": "提供 connections.json 多连接配置示例（含 is_default），展示 switch_connection() 用法，说明文件放置路径",
+      "files": []
+    }
+  ]
+}

package/bin/skills/clickzetta-lakehouse-connect/references/config-file.md

@@ -0,0 +1,435 @@
+# 配置文件管理 — connections.json 详细参考
+
+本文档详细说明 ClickZetta Lakehouse 的连接配置文件格式、搜索路径、多连接管理以及 Docker 部署方式。所有内容基于 `mcp-clickzetta-server` 项目中的真实代码。
+
+## 目录
+
+- [JSON 配置文件格式](#json-配置文件格式)
+- [五级搜索路径](#五级搜索路径)
+- [多连接管理](#多连接管理)
+- [环境变量备选](#环境变量备选)
+- [Docker / Kubernetes 部署配置](#docker--kubernetes-部署配置)
+- [system_config 参数说明](#system_config-参数说明)
+- [适用场景](#适用场景)
+- [常见问题排查](#常见问题排查)
+- [完整配置模板](#完整配置模板)
+
+---
+
+## JSON 配置文件格式
+
+配置文件 `connections.json` 包含两个顶层对象：`connections`（连接数组）和 `system_config`（系统级配置）。
+
+### 基本结构
+
+```json
+{
+  "connections": [
+    {
+      "is_default": true,
+      "connection_name": "dev",
+      "service": "cn-shanghai-alicloud.api.clickzetta.com",
+      "username": "my_user",
+      "password": "my_password",
+      "instance": "my_instance",
+      "workspace": "my_workspace",
+      "schema": "public",
+      "vcluster": "default_ap",
+      "description": "开发环境",
+      "hints": {
+        "sdk.job.timeout": 300,
+        "query_tag": "dev-queries"
+      }
+    }
+  ],
+  "system_config": {
+    "allow_write": true,
+    "prefetch": false,
+    "log_level": "INFO",
+    "exclude_tools": []
+  }
+}
+```
+
+### 连接字段说明
+
+| 字段 | 类型 | 必填 | 默认值 | 说明 |
+|:--|:--|:--|:--|:--|
+| `connection_name` | string | ✅ | — | 连接名称，用于在多连接中唯一标识 |
+| `service` | string | ✅ | — | API 服务地址，如 `cn-shanghai-alicloud.api.clickzetta.com` |
+| `username` | string | ✅ | — | 登录用户名 |
+| `password` | string | ✅ | — | 登录密码 |
+| `instance` | string | ✅ | — | 实例名称 |
+| `workspace` | string | ✅ | — | 工作空间名称 |
+| `schema` | string | ✅ | — | 默认 Schema |
+| `vcluster` | string | ❌ | `"default_ap"` | 虚拟集群名称 |
+| `is_default` | boolean | ❌ | `false` | 是否为默认连接 |
+| `description` | string | ❌ | `""` | 连接描述信息 |
+| `hints` | object | ❌ | 见下方 | SDK 运行时参数 |
+
+### hints 默认值
+
+当 `hints` 未配置时，系统自动使用以下默认值：
+
+```json
+{
+  "sdk.job.timeout": 300,
+  "query_tag": "Query from MCP Server",
+  "cz.storage.parquet.vector.index.read.memory.cache": "true",
+  "cz.storage.parquet.vector.index.read.local.cache": "false",
+  "cz.sql.table.scan.push.down.filter": "true",
+  "cz.sql.table.scan.enable.ensure.filter": "true",
+  "cz.storage.always.prefetch.internal": "true",
+  "cz.optimizer.generate.columns.always.valid": "true",
+  "cz.sql.index.prewhere.enabled": "true",
+  "cz.storage.parquet.enable.io.prefetch": "false"
+}
+```
+
+---
+
+## 五级搜索路径
+
+`ConnectionManager` 按以下优先级（从高到低）搜索配置文件，找到第一个可访问的文件即停止：
+
+| 优先级 | 路径 | 适用场景 |
+|:--|:--|:--|
+| 1（最高） | `/app/.clickzetta/lakehouse_connection/connections.json` | Docker 统一路径（推荐） |
+| 2 | `/app/config/lakehouse_connection/connections.json` | 旧版 Docker 兼容路径 |
+| 3 | `config/lakehouse_connection/connections.json` | 项目目录相对路径（本地开发） |
+| 4 | `~/.clickzetta/connections.json` | 用户主目录（仅非 Docker 环境） |
+| 5（最低） | `/app/.clickzetta/connections.json` | 简化 Docker 路径 |
+
+> **Windows Docker 环境**：系统会自动检测并添加额外的 Windows Docker 友好路径。
+
+### 搜索逻辑源码参考
+
+```python
+# 来自 connection_manager.py
+class ConnectionManager:
+    UNIFIED_CONFIG_FILE = "/app/.clickzetta/lakehouse_connection/connections.json"
+    DOCKER_CONFIG_FILE = "/app/config/lakehouse_connection/connections.json"
+    DEFAULT_CONFIG_FILE = "config/lakehouse_connection/connections.json"
+    USER_CONFIG_FILE = os.path.expanduser("~/.clickzetta/connections.json")
+    SIMPLE_CONFIG_FILE = "/app/.clickzetta/connections.json"
+```
+
+### 指定配置文件路径
+
+也可以在初始化时直接指定配置文件路径，跳过搜索逻辑：
+
+```python
+from mcp_clickzetta_server.connection_manager import ConnectionManager
+
+# 使用指定路径
+conn_manager = ConnectionManager(config_file="/path/to/my/connections.json")
+```
+
+---
+
+## 多连接管理
+
+### 配置多个连接
+
+在 `connections` 数组中定义多个连接，通过 `is_default` 标记默认连接：
+
+```json
+{
+  "connections": [
+    {
+      "is_default": true,
+      "connection_name": "dev",
+      "service": "cn-shanghai-alicloud.api.clickzetta.com",
+      "username": "dev_user",
+      "password": "dev_password",
+      "instance": "dev_instance",
+      "workspace": "dev_workspace",
+      "schema": "public",
+      "vcluster": "default_ap",
+      "description": "开发环境"
+    },
+    {
+      "connection_name": "staging",
+      "service": "cn-shanghai-alicloud.api.clickzetta.com",
+      "username": "staging_user",
+      "password": "staging_password",
+      "instance": "staging_instance",
+      "workspace": "staging_workspace",
+      "schema": "public",
+      "vcluster": "default_ap",
+      "description": "预发布环境"
+    },
+    {
+      "connection_name": "prod",
+      "service": "cn-shanghai-alicloud.api.clickzetta.com",
+      "username": "prod_user",
+      "password": "prod_password",
+      "instance": "prod_instance",
+      "workspace": "prod_workspace",
+      "schema": "public",
+      "vcluster": "default_ap",
+      "description": "生产环境",
+      "hints": {
+        "sdk.job.timeout": 600,
+        "query_tag": "production-queries"
+      }
+    }
+  ],
+  "system_config": {
+    "allow_write": false,
+    "log_level": "WARNING"
+  }
+}
+```
+
+### 连接选择规则
+
+1. 如果有 `is_default: true` 的连接，自动设为活跃连接
+2. 如果有多个 `is_default: true`，使用最后一个
+3. 如果没有默认连接，使用第一个有效连接
+4. `service` 为 `"not_configured"` 的占位配置会被自动跳过
+
+### 代码中切换连接
+
+```python
+from mcp_clickzetta_server.connection_manager import ConnectionManager
+
+conn_manager = ConnectionManager()
+
+# 列出所有可用连接
+connections = conn_manager.list_connections()
+for conn in connections:
+    print(f"  {conn['name']}: {conn.get('description', '')}")
+
+# 切换到指定连接
+result = conn_manager.switch_connection("prod")
+print(f"已切换到: {result}")
+
+# 获取当前活跃连接配置
+active_config = conn_manager.get_active_config()
+print(f"当前连接: {active_config.connection_name}")
+print(f"工作空间: {active_config.workspace}")
+
+# 设置新的默认连接
+conn_manager.set_default_connection("staging")
+
+# 验证连接配置是否完整
+validation = conn_manager.validate_connection("dev")
+print(f"验证结果: {validation}")
+```
+
+---
+
+## 环境变量备选
+
+当没有找到配置文件时，系统会创建占位配置并启动。以下环境变量可用于配置连接参数：
+
+### 连接参数环境变量
+
+| 环境变量 | 对应字段 | 说明 |
+|:--|:--|:--|
+| `CLICKZETTA_SERVICE` | `service` | API 服务地址 |
+| `CLICKZETTA_USERNAME` | `username` | 用户名 |
+| `CLICKZETTA_PASSWORD` | `password` | 密码 |
+| `CLICKZETTA_INSTANCE` | `instance` | 实例名称 |
+| `CLICKZETTA_WORKSPACE` | `workspace` | 工作空间 |
+| `CLICKZETTA_SCHEMA` | `schema` | 默认 Schema |
+| `CLICKZETTA_VCLUSTER` | `vcluster` | 虚拟集群（默认 `default_ap`） |
+
+### 系统配置环境变量覆盖
+
+以下环境变量可覆盖 `system_config` 中的对应配置（优先级最高）：
+
+| 环境变量 | 对应配置 | 示例值 |
+|:--|:--|:--|
+| `MCP_ALLOW_WRITE` | `allow_write` | `"true"` / `"false"` |
+| `MCP_PREFETCH` | `prefetch` | `"true"` / `"false"` |
+| `MCP_LOG_LEVEL` | `log_level` | `"DEBUG"` / `"INFO"` / `"WARNING"` / `"ERROR"` |
+| `MCP_EXCLUDE_TOOLS` | `exclude_tools` | `"tool1,tool2,tool3"` |
+
+### 相似度搜索环境变量
+
+| 环境变量 | 对应配置 |
+|:--|:--|
+| `Similar_table_name` | `similar_search.table_name` |
+| `Similar_embedding_column_name` | `similar_search.embedding_column_name` |
+| `Similar_content_column_name` | `similar_search.content_column_name` |
+| `Similar_other_columns_name` | `similar_search.other_columns_name` |
+| `Similar_partition_scope` | `similar_search.partition_scope` |
+
+### 云存储环境变量
+
+| 环境变量 | 对应配置 |
+|:--|:--|
+| `AWS_ACCESS_KEY_ID` | `cloud_storage.aws_access_key_id` |
+| `AWS_SECRET_ACCESS_KEY` | `cloud_storage.aws_secret_access_key` |
+| `AWS_REGION` | `cloud_storage.aws_region` |
+
+### 配置优先级
+
+系统配置的加载优先级（从高到低）：
+
+1. **环境变量**（最高优先级）
+2. **配置文件中的 `system_config`**
+3. **内置默认值**（最低优先级）
+
+---
+
+## Docker / Kubernetes 部署配置
+
+### docker-compose.yml
+
+```yaml
+services:
+  mcp-server:
+    image: mcp-clickzetta-server:latest
+    volumes:
+      # 推荐：挂载到统一路径（优先级 1）
+      - ./config/connections.json:/app/.clickzetta/lakehouse_connection/connections.json:ro
+    environment:
+      # 可选：通过环境变量覆盖系统配置
+      - MCP_ALLOW_WRITE=false
+      - MCP_LOG_LEVEL=INFO
+```
+
+### 使用旧版路径
+
+```yaml
+services:
+  mcp-server:
+    image: mcp-clickzetta-server:latest
+    volumes:
+      # 旧版兼容路径（优先级 2）
+      - ./config/connections.json:/app/config/lakehouse_connection/connections.json:ro
+```
+
+### Kubernetes ConfigMap
+
+```yaml
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: clickzetta-config
+data:
+  connections.json: |
+    {
+      "connections": [
+        {
+          "is_default": true,
+          "connection_name": "prod",
+          "service": "cn-shanghai-alicloud.api.clickzetta.com",
+          "username": "prod_user",
+          "password": "prod_password",
+          "instance": "prod_instance",
+          "workspace": "prod_workspace",
+          "schema": "public",
+          "vcluster": "default_ap"
+        }
+      ],
+      "system_config": {
+        "allow_write": false,
+        "log_level": "WARNING"
+      }
+    }
+---
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: mcp-server
+spec:
+  template:
+    spec:
+      containers:
+        - name: mcp-server
+          volumeMounts:
+            - name: config
+              mountPath: /app/.clickzetta/lakehouse_connection/connections.json
+              subPath: connections.json
+              readOnly: true
+      volumes:
+        - name: config
+          configMap:
+            name: clickzetta-config
+```
+
+> **安全提示**：生产环境建议使用 Kubernetes Secret 替代 ConfigMap 存储密码。
+
+---
+
+## system_config 参数说明
+
+### 核心参数
+
+| 参数 | 类型 | 默认值 | 说明 |
+|:--|:--|:--|:--|
+| `allow_write` | boolean | `false` | 是否允许写操作（INSERT/UPDATE/DELETE） |
+| `prefetch` | boolean | `true` | 是否启用数据预取 |
+| `log_level` | string | `"INFO"` | 日志级别：`DEBUG` / `INFO` / `WARNING` / `ERROR` |
+| `exclude_tools` | array | `[]` | 需要排除的工具列表 |
+
+---
+
+## 适用场景
+
+| 场景 | 推荐配置方式 | 说明 |
+|:--|:--|:--|
+| 本地开发 | `~/.clickzetta/connections.json` | 用户主目录，个人配置 |
+| 团队共享 | `config/lakehouse_connection/connections.json` | 项目目录，可纳入版本管理 |
+| Docker 部署 | 挂载到 `/app/.clickzetta/lakehouse_connection/` | 统一路径，推荐方式 |
+| Kubernetes | ConfigMap / Secret | 声明式配置管理 |
+| CI/CD 流水线 | 环境变量 | 无需配置文件，适合自动化 |
+| 多环境切换 | 多连接 + `switch_connection()` | 在同一配置文件中管理多个环境 |
+
+---
+
+## 常见问题排查
+
+### 配置文件未找到
+
+```
+WARNING: 未找到任何可用的配置文件
+```
+
+**解决方案**：
+1. 确认文件存在于五级搜索路径之一
+2. 检查文件权限：`chmod 600 connections.json`
+3. Docker 环境检查挂载是否正确
+
+### JSON 格式错误
+
+```
+ERROR: 配置文件JSON格式错误
+```
+
+**解决方案**：
+1. 使用 JSON 验证工具检查格式
+2. 确保所有字符串使用双引号
+3. 检查是否有多余的逗号
+4. 确保中文字符使用 UTF-8 编码保存
+
+### 连接配置缺少必需字段
+
+每个连接必须包含以下 7 个必需字段：
+
+```
+connection_name, service, username, password, instance, workspace, schema
+```
+
+### 占位配置被跳过
+
+`service` 设置为 `"not_configured"` 的连接会被自动跳过。确保所有生产连接都配置了正确的 `service` 地址。
+
+---
+
+## 完整配置模板
+
+参考项目中的模板文件：`config/connections-template.json`
+
+```bash
+# 复制模板并修改
+cp config/connections-template.json ~/.clickzetta/connections.json
+# 编辑配置
+vim ~/.clickzetta/connections.json
+# 设置文件权限（保护密码）
+chmod 600 ~/.clickzetta/connections.json
+```