@clickzetta/cz-cli-darwin-x64 0.3.1

package/bin/skills/lakehouse-doc/references/LoggingIn.md

@@ -0,0 +1,67 @@
+# 开通使用
+
+本指南将帮助您完成云器账号注册、开通服务实例和实例初始化操作，助您顺利开启云器之旅。
+
+## 账号注册
+
+在使用云器服务前，您需要注册一个云器账户。
+
+1. **访问账户注册地址**：[accounts.clickzetta.com](https://accounts.clickzetta.com/register)，点击“注册”按钮，在注册页面按照提示填写信息。
+
+:-: ![](.topwrite/assets/image_1736314854109.png =734)
+
+2. **填写手机号**：在云器注册页面，请输入一个可以正常接收短信的手机号，然后点击“获取验证码”按钮。系统将发送一条验证码短信至您的手机，请将收到的4位验证码填入“验证码”输入框，并点击“下一步”。![](.topwrite/assets/image_1739260609977.png =762)
+
+3. **创建用户**：在此步骤中，您需要为您的账户创建第一个用户。请填写“用户名”、“密码”和“确认密码”。用户名长度需在5-32个字符之间，支持英文、数字和下划线，且需以字母开头。密码长度需在8-32个字符之间，必须包含大写字母、小写字母、数字和特殊符号。
+
+4. **完成注册**：点击“完成”按钮后，您将看到注册成功提示，并收到账户登录地址。请妥善保存此地址，以便日后登录。注册时创建的用户将自动成为该账户的管理员。点击提示窗口的“去登录”按钮，使用注册时的用户名和密码登录您的账户。
+
+## 登录账户
+
+注册账户后，您可使用账户及您在此账户下的用户名、密码进行登录。
+
+1. **使用账户登录地址**：使用您的<账户名>.accounts.clickzetta.com URL进行登录。在登录提示框中输入正确的用户名和密码，点击“登录”按钮。如忘记用户名或密码，请点击“忘记用户名？”或“忘记密码？”按钮，使用注册时的手机号进行验证后找回。
+
+:-: ![](.topwrite/assets/image_1736314906745.png =776)
+
+2. **使用通用登录地址**：访问[accounts.clickzetta.com](https://accounts.clickzetta.com/login)进行登录。输入您的8位账户名（完成注册时显示），点击“登录”后，进入账户的登录页面。在登录提示框中输入正确的用户名和密码，点击“登录”按钮。如忘记账户名，请在账户登录页面点击“找回账户”，输入注册时的手机号进行验证后找回。
+
+## 创建Lakehouse服务实例
+
+登录您的云器账户后，您将进入管理中心首页。您可以在管理中心开通Lakehouse服务实例。请按照以下步骤操作：
+
+* 在管理中心“首页”中找到Lakehouse产品卡片，点击“免费开通”按钮。![](.topwrite/assets/20250211-191828.jpeg)
+* 在弹出窗口中选择云服务商和开通地域，点击“确认”按钮，完成Lakehouse服务实例的创建。目前云器Lakehouse支持在阿里云上海、腾讯云上海和亚马逊云科技（中国）北京三个区域开通Lakehouse服务实例。
+
+:-: ![](.topwrite/assets/create_instance.png =616)
+
+* 请注意，目前限制每个账户只能创建一个Lakehouse服务实例。
+
+## 实例初始化
+
+创建Lakehouse服务实例后，您可以在管理中心的“我的订阅”中找到并进入该服务实例。系统将自动进行初始化，包括：
+
+1. 创建第一个名为“quick\_start”的工作空间。
+2. 创建“quick\_start”工作空间内的第一个虚拟计算集群（Virtual Cluster），默认处于停止状态。
+3. 创建系统服务用户`sysservice_clickzetta`和`sysservice_auto_mv`。
+4. 将创建Lakehouse服务实例的用户设置为服务实例的管理员角色以及工作空间“quick\_start”的空间管理员（workspace\_admin）角色。此时，您将具备Lakehouse服务实例及“quick_start”工作空间的所有操作权限。后续，您可以通过用户和权限管理功能添加更多用户并分配相应权限。
+
+现在，您已经完成了使用云器Lakehouse的准备工作。您可以查看其它快速开始文档，了解如何快速上手使用Lakehouse。如需更详细的操作指导，请参考“[操作指南](studio_manual.md)”章节。
+
+## 开通 DataGPT 服务
+
+DataGPT 服务现已在阿里云华东2（上海）区域上线。系统将与同区域（华东2（上海））的阿里云 Lakehouse 实例实现默认对接。对于未在阿里云华东2（上海）开通的 Lakehouse 实例，您可以直接在 DataGPT 的数据源页面中手动添加，无需进行勾选操作。
+
+* 在管理中心“首页”中找到 DataGPT 产品卡片，点击“免费开通”按钮。
+
+&#x20;      ![](.topwrite/assets/20250211-192212.jpeg =731)
+
+* 弹出窗口中会默认指定**云服务商**阿里云和**地域**华东2（上海）。系统提供了“**同时开通阿里云-华东2（上海）的 Lakehouse 实例作为默认数据源**”选项：
+  * **勾选（推荐新用户）**：将自动开通阿里云-华东2（上海）的 Lakehouse 实例作为默认数据源，无需手动配置。
+  * **不勾选**：系统不会自动开通华东2（上海）地区的 Lakehouse 实例，您可以在服务开通后，在数据源管理页面手动添加。请注意，此情况下 **DataGPT 不会包含预置的样例数据**。
+
+&#x20;      ![](.topwrite/assets/20250211-192304.jpeg =618)
+
+* 点击“开通”，稍等片刻后即可进入使用界面。
+
+&#x20;      ![](.topwrite/assets/20250211-193618.jpeg =787)

package/bin/skills/lakehouse-doc/references/Logstash.md

@@ -0,0 +1,172 @@
+Logstash 是一个开源的数据处理管道，它能够同时从多个来源采集数据，对数据进行处理，并将其发送到您选择的目的地。Logstash 是 Elastic Stack（以前称为 ELK Stack）的一部分，该技术栈还包括 Elasticsearch 和 Kibana。这三个工具通常一起使用，以提供强大的搜索、分析和可视化功能。Lakehouse 提供了 Logstash Connector，可以直接连接 Lakehouse。
+
+
+# 部署
+
+```JSON
+# 卸载插件
+./bin/logstash-plugin uninstall logstash-output-clickzetta && rm -rf ./vendor/local_gems/
+
+# 安装插件
+./bin/logstash-plugin install --no-verify --local logstash-output-clickzetta-0.0.1.gem 
+
+# 查看插件
+./bin/logstash-plugin list --verbose
+```
+
+> 安装插件时，虽然指定了 `--no-verify --local`，但仍似乎会去远程服务器上下载或校验某些包。所以安装时如果碰到长时间卡在 `installing ...` 环节，可以直接按 `Ctrl+C` 强制终止。此时插件可能已经安装成功，可以通过查看插件列表来验证。
+
+# 测试
+
+```JSON
+cd /logstash-data
+/usr/share/logstash/bin/logstash -f data/logstash.conf.5 --log.level error
+# 默认worker数为机器核数（-w），默认batch size为125(-b)，可通过 -w 16 -b 200 进行调整对应参数
+```
+
+**File input**
+
+参考 [file input 插件](https://www.elastic.co/guide/en/logstash/7.17/plugins-inputs-file.html#plugins-inputs-file-sincedb_clean_after)
+
+```JSON
+input {
+  file {
+                path => "/logstash-data/data/igs_worker_full_log.log"
+                codec => json
+                start_position => "beginning"
+                mode => "read"
+                file_completed_action => log
+                file_completed_log_path => "/logstash-data/data/temp_log/"
+                exit_after_read => true
+                sincedb_clean_after => "1 second"
+        }
+  file {
+                path => "/logstash-data/data/igs_worker_full_log_1.log"
+                codec => json
+                start_position => "beginning"
+                mode => "read"
+                file_completed_action => log
+                file_completed_log_path => "/logstash-data/data/temp_log/"
+                exit_after_read => true
+                sincedb_clean_after => "1 second"
+        }
+  file {
+                path => "/logstash-data/data/igs_worker_full_log_2.log"
+                codec => json
+                start_position => "beginning"
+                mode => "read"
+                file_completed_action => log
+                file_completed_log_path => "/logstash-data/data/temp_log/"
+                exit_after_read => true
+                sincedb_clean_after => "1 second"
+        }
+  file {
+                path => "/logstash-data/data/igs_worker_full_log_3.log"
+                codec => json
+                start_position => "beginning"
+                mode => "read"
+                file_completed_action => log
+                file_completed_log_path => "/logstash-data/data/temp_log/"
+                exit_after_read => true
+                sincedb_clean_after => "1 second"
+        }
+  file {
+                path => "/logstash-data/data/igs_worker_full_log_4.log"
+                codec => json
+                start_position => "beginning"
+                mode => "read"
+                file_completed_action => log
+                file_completed_log_path => "/logstash-data/data/temp_log/"
+                exit_after_read => true
+                sincedb_clean_after => "1 second"
+        }
+}
+
+output {
+    clickzetta {
+            jdbcUrl => "jdbc:clickzetta://9a310b9b.<region\_id>.api.clickzetta.com/quick_start?schema=public&username=index_test&password=password&virtualCluster=YETING_TEST_AP"
+            username => "index_test"
+            password => "password"
+            schema => "public"
+            table => "test_simple_data-%{+YYYY.MM.dd}"
+            internalMode => false
+            directMode => false
+        }
+}
+```
+
+**Kafka input**
+
+Kafka input 配置参考 \[[kafka作为input接入](https://help.aliyun.com/zh/apsaramq-for-kafka/connect-an-apsaramq-for-kafka-instance-to-logstash-as-an-input-over-the-internet)]
+
+> 由于本测试用例是阿里云的 Kafka 组件，需要配置相关 SSL 证书，其他云环境可能有所区别，需要按照其他云服务商官方文档操作。
+>
+> ssl\_truststore\_location 配置需要使用 \[[这里](https://github.com/AliwareMQ/aliware-kafka-demos/blob/master/kafka-java-demo/vpc-ssl/src/main/resources/only.4096.client.truststore.jks)] 下载的证书
+
+```JSON
+input {
+    kafka {
+                bootstrap_servers => "alikafka-pre-cn-co92y9d22001-1.alikafka.aliyuncs.com:9093,alikafka-pre-cn-co92y9d22001-2.alikafka.aliyuncs.com:9093,alikafka-pre-cn-co92y9d22001-3.alikafka.aliyuncs.com:9093"
+                group_id => "logstash-test-group"
+                decorate_events => true
+                topics => ["igs-worker-log-for-sla"]
+                security_protocol => "SASL_SSL"
+                sasl_mechanism => "PLAIN"
+                sasl_jaas_config => "org.apache.kafka.common.security.plain.PlainLoginModule required username='username' password='password';"
+                ssl_truststore_password => "KafkaOnsClient"
+                ssl_truststore_location => "/logstash-data/only.4096.client.truststore.jks"
+                ssl_endpoint_identification_algorithm => ""
+                consumer_threads => 3
+                codec => json {
+                    charset => "UTF-8"
+                }
+        }
+}
+
+filter {
+mutate {
+    add_field => {
+        "kafka_topic_name" => "%{[fields][log_topic]}"
+    }
+}
+grok {
+    match => { "message" => "\[%{TIMESTAMP_ISO8601:@timestamp}\] \[%{NUMBER:thread_id}\] \[%{LOGLEVEL:log_level}\] \[%{DATA:source_file}\] \[%{DATA:function_name}\]%{GREEDYDATA:log_content}" }
+}
+ruby {
+        code => "
+            if event.get('thread_id').to_i % 2 == 0
+                event.tag('even')
+            else
+                event.tag('odd')
+            end
+        "
+    }
+}
+output {
+    if "odd" in [tags] {
+        clickzetta {
+            jdbcUrl => "jdbc:clickzetta://9a310b9b.<region\_id>.api.clickzetta.com/quick_start?schema=public&username=index_test&password=password&virtualCluster=YETING_TEST_AP"
+            username => "index_test"
+            password => "password"
+            schema => "public"
+            table => "liuwei_log_data-odd-%{kafka_topic_name}-%{+YYYY.MM.dd}"
+            tablet => 16
+            debug => true
+            internalMode => false
+            directMode => false
+        }
+    } else {
+        clickzetta {
+            jdbcUrl => "jdbc:clickzetta://9a310b9b.<region\_id>.api.clickzetta.com/quick_start?schema=public&username=index_test&password=password&virtualCluster=YETING_TEST_AP"
+            username => "index_test"
+            password => "password"
+            schema => "public"
+            table => "liuwei_log_data-even-%{kafka_topic_name}-%{+YYYY.MM.dd}"
+            tablet => 16
+            debug => true
+            internalMode => false
+            directMode => false
+        }
+    }
+}
+```

package/bin/skills/lakehouse-doc/references/MAP.md

@@ -0,0 +1,42 @@
+# MAP
+
+`MAP` 函数用于创建一个键值对映射表，其中每个键都与一个值相对应。这种数据结构可以方便地存储和检索与特定键关联的数据。
+
+## 语法
+
+```sql
+MAP <keyType, valueType> (key1, value1, key2, value2, ...)
+```
+
+## 参数
+
+* `keyType`：键的类型，可以是任何基本数据类型，如整数、字符串等。
+* `valueType`：值的类型，可以是任何基本数据类型，如整数、字符串等。
+* `(key1, value1, key2, value2, ...)`：一个或多个键值对，用逗号分隔。
+
+## 示例
+
+1. 将颜色名称映射到对应的数字：
+
+```sql
+CREATE TABLE MAP_TABLE(COL MAP<STRING,INT>);
+
+SELECT MAP('red', 1, 'green', 2);
+ +---------------------------+
+ | MAP('red', 1, 'green', 2) |
+ +---------------------------+
+ | {"red":1,"green":2}       |
+ +---------------------------+
+```
+
+2. 将员工姓名映射到对应的部门：
+
+```sql
+ SELECT MAP('Alice', 'HR', 'Bob', 'Sales', 'Charlie', 'IT');
+  +-----------------------------------------------------+
+  | MAP('Alice', 'HR', 'Bob', 'Sales', 'Charlie', 'IT') |
+  +-----------------------------------------------------+
+  | {"Alice":"HR","Bob":"Sales","Charlie":"IT"}         |
+  +-----------------------------------------------------+
+
+ ```

package/bin/skills/lakehouse-doc/references/MATERIALIZEDVIEW.md

@@ -0,0 +1,112 @@
+# MATERIALIZED VIEW（物化视图）
+
+物化视图是一种特殊的数据库对象，它可以定期缓存查询结果以提高性能和效率。由于物化视图中的数据是预先计算好的，因此查询物化视图通常比直接查询基表更快。当查询频繁运行或足够复杂时，这种性能差异可能会非常明显。因此，物化视图可以加速昂贵的聚合、投影和选择操作，尤其是那些频繁运行在大型数据集上的操作。
+
+## 物化视图
+
+* 物化视图可以提高重复使用相同子查询结果的查询的性能，并支持查询改写。
+* 当物化视图的基础表发生插入、覆写、更新、删除等操作时，物化视图会自动失效，无法用于查询改写。
+
+## 何时创建物化视图
+
+物化视图特别适用于以下情况：
+
+* 查询结果包含与基础表相比少量的行和/或列。
+* 查询结果需要大量处理，包括半结构化数据分析、长时间计算的聚合等。
+* 物化视图的基础表不经常变化。
+
+## 云器Lakehouse物化视图特点
+
+* 物化视图可以提高重复使用相同子查询结果的查询的性能。
+* 物化视图支持定时刷新功能。通过SQL语法创建定时刷新任务，与在应用程序级别手动维护物化视图相比，这种方式更有效且更不容易出错。
+
+## 物化视图与普通视图的选择
+
+通常，当决定创建物化视图还是普通视图时，可以使用以下标准：
+
+* 如果视图的查询结果不经常变化、结果使用频繁且查询消耗大量资源，则创建物化视图。
+* 如果视图的结果经常变化、结果不经常使用或查询不消耗太多资源，则创建普通视图。
+
+## 物化视图与表、普通视图和缓存结果的比较
+
+物化视图与表在某些方面相似，与普通（非物化）视图在其他方面相似。此外，物化视图与缓存结果有一些相似之处，特别是两者都允许存储查询结果以供将来重用。
+
+
+## 物化视图管理
+
+云器Lakehouse提供了以下DDL命令来创建和维护物化视图：
+* [创建物化视图](CREATEMATERIALIZEDVIEW.md)：创建物化视图需要指定基表、查询语句以及其他相关参数。创建成功后，物化视图将存储在数据库中，以便后续查询使用。
+* [删除物化视图](DROPMATERIALIZEDVIEW.md)：当物化视图不再需要时，可以通过执行删除操作来释放相关资源。
+* [刷新物化视图](REFRESH.md)：当物化视图中的数据需要更新时，可以通过执行刷新操作来更新物化视图的数据。
+
+更多操作请参考[物化视图命令详情](<materialized_ddl.md>)。
+
+## 应用场景
+
+以下使用场景重点介绍了物化视图的价值。如果您的应用场景符合以下条件，那么物化视图可以提高查询性能：
+
+* **预汇总数据**：如果您需要对大量数据进行汇总分析，物化视图可以利用定时任务进行预先汇总，从而提高查询性能。
+* **预过滤数据**：如果您的查询只需要读取表的特定部分，物化视图可以预先过滤数据，从而减少查询时的数据量。
+* **预联接数据**：如果您的查询需要联接多个表，尤其是大型表和小型表之间的联接，物化视图可以预先进行联接操作，从而提高查询性能。
+
+## Materialized View和Dynamic Table区别
+
+从Lakehouse的实现机制上来看，动态表是基于传统的物化视图演进而来，虽然两者有一些共性，但在定位上存在很大区别。
+
+**物化视图：性能优化利器** 物化视图是一种预计算并存储查询结果的特殊视图，它能够显著提升查询效率。与传统视图不同，物化视图将计算结果保存在类似表的结构中，使得后续相似查询能够被优化器自动识别并直接使用预存结果，从而减少重复计算，加快查询速度。
+
+**动态表：数据加工的高效工具** 动态表专注于数据加工，虽然也能提升查询性能，但它并不依赖于查询优化器的自动重写。物化视图只有保持数据是最新的才能用于查询改写；而动态表面向加工场景，其数据可能并不是最新的。
+
+**传统物化视图在某些产品中具有以下限制，目前Lakehouse没有这些限制**：
+
+1. 只能使用单个基表。物化视图不能基于复杂查询（即具有联接或嵌套视图的查询）。
+
+2. 物化视图不一定是增量刷新，每个系统的实现不同。少量系统为了节省计算资源、加快加工速度，在部分算子中实现了增量计算。
+
+**动态表的先进特性**：
+
+1. **增量识别与优化**：支持大数据环境下的文件粒度增量识别，实现实时增量读取和计算优化，以及写入优化。
+2. **智能决策**：通过基于成本的优化器(Cost-Based Optimizer)智能选择全量、增量或部分增量计算，以适应不同查询需求。
+3. **实时任务运维**：提供数据版本管理、回退和重跑等机制，为实时任务的运维提供全面支持。
+
+**数据时效性考量**：
+
+* 物化视图要求数据的即时更新，以确保查询改写的准确性。在基表数据变更时，Lakehouse采用定时刷新机制，确保物化视图的数据始终保持最新。
+* 动态表则更注重数据加工的灵活性，根据业务定义来调整数据的滞后性，而不强制要求数据必须实时更新。
+
+## 查询改写功能
+
+目前Lakehouse的查询改写功能处于Preview阶段。如果您需要使用该功能，在提交SQL查询时请使用以下配置：
+`set cz.optimizer.enable.mv.rewrite=true;`
+
+具体案例
+
+```SQL
+
+create table product_sales(sale_id int, product_name string, sale_date string, quantity_sold int);
+INSERT INTO product_sales (sale_id, product_name, sale_date, quantity_sold)
+VALUES
+(1, 'Widget', '2024-05-01', 10),
+(2, 'Widget', '2024-05-02', 20),
+(3, 'Gadget', '2024-05-01', 15),
+(4, 'Widget', '2024-05-03', 5);
+CREATE MATERIALIZED VIEW product_sales_filter AS
+SELECT    sale_id,
+          product_name,
+          sale_date
+FROM      product_sales
+WHERE     sale_id < 3;
+
+set cz.optimizer.enable.mv.rewrite=true;
+SELECT    sale_id,
+          product_name,
+          sale_date
+FROM      product_sales
+WHERE     sale_id < 2;
+
+set cz.optimizer.enable.mv.rewrite=true;
+SELECT    sale_id,
+          product_name
+FROM      product_sales
+WHERE     sale_id < 2;
+```

package/bin/skills/lakehouse-doc/references/MCPServers.md

@@ -0,0 +1,267 @@
+## 简介
+
+在数据工程和 AI 驱动的自动化时代，Model Context Protocol（MCP）正在改变我们与数据平台交互的方式。云器 MCP-Server 作为一个强大的集成方案，让 AI Agent 能够直接操作数据湖仓、创建任务、管理调度，实现真正的"对话式数据工程"。
+
+本文将深入解析 云器Lakehouse MCP-Server 的架构设计、核心能力，并提供详尽的实战指南，帮助数据工程师和 AI 开发者快速上手这一创新工具。
+
+## 一、什么是 MCP Server？
+
+### 1.1 MCP 协议简介
+
+Model Context Protocol（MCP）是 Anthropic 推出的开放协议，旨在标准化 AI 模型与外部工具、数据源之间的交互方式。通过 MCP，AI Agent 可以：
+
+* **访问外部数据源**：数据库、API、文件系统等
+* **执行操作**：创建任务、运行查询、管理资源
+* **获取上下文**：理解业务逻辑、表结构、依赖关系
+
+### 1.2 云器 Lakehouse MCP-Server 的定位
+
+云器Lakehouse MCP-Server 是专为云器Lakehouse数据平台设计的 MCP服务。 接入该服务后，您可以直接在第三方AI Agent内通过输入自然语言的方式，直接操作产品功能，而无需关注过多的产品操作细节。
+
+目前该服务提供了**40+ 专业工具**：覆盖 SQL 查询、任务创建、运维管理、数据质量多个场景。
+
+## 二、快速开始：配置你的第一个 MCP Server
+
+### 2.1 环境准备
+
+**推荐工具**：
+
+* **Claude Desktop**：原生支持 MCP
+* **Cherry Studio**：开源 AI 客户端，支持 MCP 配置
+
+**前置要求**：
+
+* 云器lakehouse 账号及 Personal Access Token（PAT）
+* 目标工作空间（Workspace）和项目（Project）的访问权限
+* Node.js 环境（用于运行 `mcp-remote`）
+
+### 2.2 Claude Desktop 配置详解
+
+#### 步骤 1：定位配置文件
+
+在 Claude Desktop 的 Settings 中找到 **Local MCP servers** 配置入口，点击 **Edit Config** 打开 `claude_desktop_config.json` 文件。
+
+配置文件路径通常为：
+
+* **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+* **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+
+#### 步骤 2：配置MCP
+
+* 在产品内，点击左下角个人信息「Lakehouse MCP」
+* 在下图页面中生成个人的token，并配置该token对应的连接环境信息。
+
+注意：使用该token时具备此用户身份的全部权限。因此请妥善保管token，避免泄露造成安全风险。
+
+
+![](/.topwrite/assets/image_1766485071003.png)
+
+^
+
+* 生成token后，在右侧的连接配置可看到mcp的配置json，复制后粘贴至`claude_desktop_config.json文件中。`
+
+```SQL
+{  "clickzetta-http": {   
+ "command": "npx",   
+ "args":  [     
+ "-y", "mcp-remote",   
+   "https://cn-shanghai-alicloud-mcp.clickzetta.com/mcp",   
+   "--allow-http",  
+    "--transport", "http",    
+  "--header", "x-Lakehouse-Token: Bearer <your_token>"    ]  }}
+```
+
+### 2.3 Cherry Studio 配置
+
+如果使用 Cherry Studio：
+
+1. 打开 **设置** → **MCP** → 点击 **添加服务器**
+
+2. 配置如下：
+
+   1. **名称**：`Clickzetta MCP`
+   2. **类型**：`可流式传输的 HTTP (streamableHttp)`
+   3. **URL**：`https://cn-shanghai-alicloud-mcp.clickzetta.com/mcp`
+   4. **请求头**（每行一个）：
+
+```Plain
+ x-Lakehouse-Token=Bearer <your_pat>
+x-Lakehouse-Region= cn-shanghai-alicloud
+```
+
+### 2.4 验证配置
+
+重启 Claude Desktop 或 Cherry Studio，在对话框中输入：
+
+```Plain
+列出当前工作空间中的所有文件夹
+```
+
+如果返回文件夹列表，说明配置成功！
+
+## 三、工具列表介绍
+
+### 一、查询工具
+
+| 工具名称                     | 功能描述                                                                                                          |
+| ------------------------ | ------------------------------------------------------------------------------------------------------------- |
+| LH-execute\_read\_query  | 执行只读SQL查询并返回结果，支持自动结果限制。支持SELECT、DESCRIBE/DESC、SHOW、EXPLAIN等语句。适合临时查询、数据探索、快速验证等场景                            |
+| LH-execute\_write\_query | 执行写操作SQL语句（INSERT/UPDATE/DELETE/CREATE/DROP等）。支持数据修改、对象创建删除、权限管理等操作。写操作不可逆，需谨慎使用                              |
+| LH-show\_object\_list    | 列出Lakehouse数据库对象，无需构造SQL，避免SQL方言问题。支持智能过滤、统计分析和过滤建议。可列出WORKSPACES、TABLES、VIEWS、SCHEMAS、FUNCTIONS、VCLUSTERS等对象 |
+
+### 二、Studio任务管理工具
+
+| 工具名称                                  | 功能描述                                                                                       |
+| ------------------------------------- | ------------------------------------------------------------------------------------------ |
+| create\_task                          | 在Clickzetta Studio项目中创建新任务，支持SQL、Shell、Python、数据集成、Notebook等多种任务类型，返回可直接打开任务的studio\_url链接 |
+| get\_task\_detail                     | 获取任务的详细信息，包括任务名称、类型、所有者、描述、内容、版本和配置等元数据，返回studio\_url供用户打开                                 |
+| list\_clickzetta\_tasks               | 列出任务列表，支持按文件夹、名称、类型筛选。返回草稿任务、已提交任务等所有状态的任务                                                 |
+| save\_non\_integration\_task\_content | 保存非数据集成任务的内容（SQL脚本、Shell脚本、Python代码等），支持参数化配置，返回studio\_url                                |
+| save\_integration\_task               | 保存完整的数据集成任务配置，自动处理表检查、元数据获取、自动建表等流程，返回studio\_url                                          |
+| get\_file\_configuration\_detail      | 获取任务的配置详情，返回完整配置信息和可用于save\_task\_configuration的输入参数块                                      |
+| save\_task\_configuration             | 保存任务的调度配置，包括Cron表达式、重试策略、有效期、依赖关系等。对集成任务会自动检查Sync VCluster                                 |
+| publish\_task                         | 将任务发布到调度器，使其可以按计划执行。发布前必须保存任务内容和配置。需用户确认后才执行                                               |
+| execute\_task                         | 异步执行数据任务，支持数据集成和Lakehouse SQL任务。自动解析任务内容、处理变量、选择VC、提交执行并轮询状态                               |
+
+### 三、任务运行与监控工具
+
+| 工具名称                        | 功能描述                                                            |
+| --------------------------- | --------------------------------------------------------------- |
+| list\_task\_run             | 列出符合条件的任务运行记录（支持分页）。支持按项目、任务类型、任务名、运行类型、计划时间、状态等筛选              |
+| get\_task\_run\_stats       | 获取任务运行统计信息（按任务聚合）。支持按项目、任务类型、运行类型、时间范围、状态等筛选。适合回答"执行情况如何"等统计类问题 |
+| list\_executions            | 列出特定任务运行下的执行记录（支持分页）。每个任务运行可能有多次执行                              |
+| get\_execution\_log         | 获取特定执行的日志内容，支持从头部、尾部或指定偏移位置查询日志                                 |
+| get\_task\_instance\_detail | 获取任务实例的执行状态和详细信息，包括状态、时间、错误信息等，用于调试和状态检查                        |
+
+### 四、任务依赖与统计工具
+
+| 工具名称                               | 功能描述                                                  |
+| ---------------------------------- | ----------------------------------------------------- |
+| get\_published\_task\_dependencies | 获取已发布任务的上下游依赖关系树，支持配置上游和下游的层级深度                       |
+| get\_task\_run\_dependencies       | 获取任务运行实例的上下游依赖关系树，支持配置上游和下游的层级深度                      |
+| get\_task\_statistics              | 获取按任务聚合的统计信息，支持按项目、任务类型、编辑状态、所有者等筛选。适合回答"有多少任务"等统计类问题 |
+
+### 五、数据源与元数据工具
+
+| 工具名称                    | 功能描述                                                                            |
+| ----------------------- | ------------------------------------------------------------------------------- |
+| list\_data\_sources     | 列出项目中所有可用的数据源配置，包括MySQL、PostgreSQL、Kafka、Hive、ClickHouse等。支持按名称和类型筛选，强烈建议使用过滤参数 |
+| list\_namespaces        | 列出指定数据源中的命名空间（Schema/Database）列表，支持模糊匹配过滤                                       |
+| list\_metadata\_objects | 列出指定命名空间中的数据对象（表/视图/集合），支持模糊匹配过滤                                                |
+| get\_metadata\_detail   | 获取指定数据对象的详细元数据信息，包括列名、数据类型、约束等                                                  |
+
+### 六、文件夹管理工具
+
+| 工具名称           | 功能描述                                       |
+| -------------- | ------------------------------------------ |
+| create\_folder | 在指定父文件夹下创建新文件夹，用于组织任务结构                    |
+| list\_folders  | 列出文件夹，支持按父文件夹、名称、类型筛选和分页。需递归查询所有层级才能发现全部任务 |
+
+### 七、补数据管理工具
+
+| 工具名称                        | 功能描述                                             |
+| --------------------------- | ------------------------------------------------ |
+| list\_backfill\_tasks       | 列出补数据（complement）任务，支持按项目、时间范围、状态、提交者、任务名筛选，支持分页 |
+| get\_backfill\_task\_detail | 获取补数据任务的完整元数据和配置信息                               |
+| list\_backfill\_instances   | 列出特定补数据任务下的实例列表，支持按状态和任务名筛选，支持分页                 |
+
+### 八、数据质量检查工具
+
+| 工具名称              | 功能描述                                                           |
+| ----------------- | -------------------------------------------------------------- |
+| create\_dqc\_rule | 创建并可选执行数据质量检查规则。支持内置指标（行数、空值、均值等）和自定义SQL。支持手动触发、定时调度、任务关联等触发方式 |
+
+### 九、CDC实时同步工具
+
+|                           |                                                                                           |
+| ------------------------- | ----------------------------------------------------------------------------------------- |
+| 工具名称                      | 功能描述                                                                                      |
+| save\_cdc\_realtime\_task | 保存多表实时CDC（变更数据捕获）任务配置。支持MySQL、PostgreSQL、SQL Server等源到Lakehouse/Kafka的实时同步，自动建表，支持全量+增量模式 |
+
+### 十、语义视图工具
+
+| 工具名称                         | 功能描述                                                        |
+| ---------------------------- | ----------------------------------------------------------- |
+| LH-desc-logical-table        | 获取语义视图中逻辑表的定义，包括关联的物理表和维度信息                                 |
+| LH-desc-semantic-view        | 返回语义视图的YAML格式定义（Snowflake Cortex Analyst格式）                 |
+| LH-create-semantic-view      | 从YAML定义创建语义视图（Snowflake Cortex Analyst格式），支持IF NOT EXISTS选项 |
+| LH-brief-semantic-view       | 以简洁格式描述语义视图的字段信息                                            |
+| LH-semantic-view-dim-add     | 向语义视图添加维度字段                                                 |
+| LH-semantic-view-dim-del     | 从语义视图删除维度字段                                                 |
+| LH-get\_semantic\_view\_dims | 获取语义视图的所有维度信息                                               |
+| LH-query-semantic-value      | 基于自然语言查询语义视图数据，通过指定维度、指标和过滤条件来获取数据                          |
+
+### 十一、知识库与技能工具
+
+| 工具名称                    | 功能描述                                                  |
+| ----------------------- | ----------------------------------------------------- |
+| find\_helpful\_skills   | 【最高优先级】搜索远程技能库，返回排序的候选技能及分步指导。处理任何请求时必须首先调用此工具        |
+| read\_skill\_document   | 读取技能中的特定文档（脚本、参考、示例）。不带路径调用时列出所有可用文件                  |
+| list\_skills            | 列出知识库中所有可用的Clickzetta公司技能，用于探索或验证已加载的技能               |
+| get\_product\_knowledge | 搜索Clickzetta产品文档（Lakehouse和Studio规范知识库），用于获取技术文档和产品知识 |
+| put\_knowledge          | 向知识库存入文本知识条目并创建索引，支持向量和标量索引                           |
+| search\_knowledge       | 从知识库搜索文本知识条目（仅限手动输入和标注的知识，包括成功案例和反馈）                  |
+
+^
+
+### Q\&A
+
+#### 1. Claude Desktop 提示找不到 npx / Failed to spawn process
+
+Q1：Claude Desktop 配好 MCP Server 后连不上，日志里出现 `Failed to spawn process: No such file or directory`
+
+**A**：这通常表示 Claude Desktop 在启动本地 MCP 连接时，需要执行你配置里的 `command`（常见是 `npx`），但在 Claude Desktop 的运行环境里找不到该可执行文件（或无法在 PATH 中定位）。
+在本文的 HTTP(streamable) 示例中，`command` 默认是 `npx`，而 `mcp-remote` 依赖 Node.js/npm 环境。
+
+**修复方式为**：
+
+**在macOS系统中**：
+
+**1）确认本机是否安装了 Node.js（含 npx**）
+打开 Terminal 执行：
+
+* `node -v`
+* `npx -v`
+* `which npx`
+
+若 `npx -v` 报错或 `which npx` 无输出，说明 Node.js/npm 未安装或不可用。
+
+**2）安装 Node.js（推荐让 GUI 应用也能找到 npx**）
+
+* \*\*推荐方式：\*\*使用 Homebrew 安装 Node.js（npx 路径更稳定、GUI 应用更容易识别）。
+
+  * 若提示 `brew: command not found`，先安装 Homebrew，再 `brew install node`。
+
+* \*\*替代方式：\*\*使用 Node.js 官方 macOS Installer 安装（同样可用）。
+
+**3）处理 GUI App 的 PATH 和 Terminal 不一致**
+即使 Terminal 里 `npx` 正常，Claude Desktop 仍可能找不到。此时建议：
+
+* 在 `claude_desktop_config.json` 里把 `"command": "npx"` 改为 **npx 的绝对路径**（以 `which npx` 输出为准），例如：
+
+  * Apple Silicon 常见：`/opt/homebrew/bin/npx`
+  * Intel 常见：`/usr/local/bin/npx`
+
+**4）重启 Claude Desktop 再验证**
+
+****
+
+**在windows系统中**：
+
+**1）确认 Node.js 是否安装并已加入 PATH**
+打开 PowerShell 或 CMD，执行：
+
+* `node -v`
+* `npx -v`
+* `where npx`
+
+若找不到，安装 Node.js（建议 LTS），安装时勾选 **Add to PATH**（或安装后手动把 Node 安装目录加入系统 PATH）。
+
+**2）如果 Claude Desktop 仍找不到 npx：用绝对路径指定命令**
+在 `claude_desktop_config.json` 中把 `"command": "npx"` 改为 `npx.cmd` 的绝对路径（以 `where npx` 输出为准），例如常见路径类似：
+
+* `C:\Program Files\nodejs\npx.cmd`
+
+**3）重启 Claude Desktop 再验证**
+
+^