MaxCompute 语义增强 CLI（MaxCompute-semantic）

安装 mcs

uv tool install maxcompute-semantic
mcs --version

curl -fsSL https://raw.githubusercontent.com/aliyun/maxcompute-semantic/main/scripts/install.md

如果 ~/.local/bin 不在 PATH 中，安装完成后可能无法直接找到 mcs。可将下面配置加入当前 shell 配置文件：

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

安装 Agent Skill

安装完成后，将 mcs 的 Skill 注册到本机 Agent：

mcs skill install --detect -g

--detect 表示只安装到当前机器上已检测到的 Agent 平台。也可以使用：

mcs skill install --all -g

该命令会把 Skill 安装到所有支持的平台。常见平台包括 Claude Code、Cursor、Codex、Gemini CLI、Qwen Code 和 OpenCode。

创建 profile 并绑定目录

mcs profile create
mcs link bind <profile-name>

mcs profile spec-template > profile.yaml
mcs profile create --from-file @profile.yaml

运行以下命令确认数据源范围已配置：

mcs profile show <profile-name>

如果 Sources 显示 (none yet)，可以运行 mcs profile update <profile-name> 添加数据源，然后再执行构建。

构建语义包并诊断

创建 profile 后，构建本地语义包：

mcs build
mcs doctor

• mcs build 会根据 profile 中的数据源范围读取 MaxCompute 元数据，并生成本地语义包。

• mcs doctor 会检查 profile、认证、MaxCompute 连通性、构建数据和 Skill 安装状态。

如果只想刷新已构建过的 profile，可以使用：

mcs build --refresh

如果只想构建部分表，可以使用：

mcs build --tables table_a,table_b

通过 Agent 提问

Skill 安装并构建语义包后，打开已安装 Skill 的 Agent（如 Claude Code），进入绑定了 profile 的目录，用自然语言提问，例如：

default schema 里有哪些表？

Agent 会自动读取语义包，生成 SQL，执行审查和成本预估，确认安全后执行查询并返回结果。无需要手动运行 mcs 命令。

当查询结果确认正确后，可以让 Agent 记录已验证 SQL：

mcs memory verify \
  --question "上个月订单 GMV 同比怎么样？" \
  --sql "SELECT ..." \
  --tables your_project.your_schema.orders

后续遇到相似问题时，Agent 可以通过查询记忆召回历史 SQL 和相关说明。

Profile 与连接管理

profile 是 mcs 的连接和语义上下文单位。一个 profile 通常对应一个业务分析场景，包含MaxCompute endpoint 或 Region、认证方式和凭证引用、默认计算project、数据源范围（project/schema/table）、成本确认阈值和阻断阈值。构建完成后，profile目录下还会保存语义包、查询记忆和 proposal 状态。

常用命令如下：

认证方式

mcs 支持 AK 和 process auth 两种 profile 认证配置：

• AK：在 profile 中配置 AccessKey ID 和 AccessKey Secret。建议使用 ${env:ALIBABA_CLOUD_ACCESS_KEY_ID}、${env:ALIBABA_CLOUD_ACCESS_KEY_SECRET} 这类环境变量引用，避免把明文凭证写入文件。

• process auth：在 profile 中配置一个本地命令。mcs 需要访问 MaxCompute 时会执行该命令，并从标准输出读取 STS 临时凭证 JSON。

  process auth 的 profile 配置示例如下：

  auth:
    type: process
    command: your-credential-helper --format sts-json
    timeout: 60

  其中，command 可以是任意符合组织规范的本地凭证命令，但必须在标准输出返回 JSON。JSON 字段使用 Alibaba Cloud STS AssumeRole 凭证格式：

  {
    "AccessKeyId": "STS.xxxxx",
    "AccessKeySecret": "xxxxxx",
    "SecurityToken": "xxxxxx",
    "Expiration": "2026-07-01T12:00:00Z"
  }

  • 必填字段：AccessKeyId、AccessKeySecret、SecurityToken

  • 可选字段：Expiration

  mcs 也兼容 access_key_id、access_key_secret、security_token、expiration 这类 snake_case 字段名。

语义包构建与维护

mcs build 是需要定期维护的本地构建操作。它会读取 profile 中声明的数据源范围，构建可供 Agent 读取的本地语义包。默认构建内容包括：

• 表、字段、分区等 schema 信息。

• 字段值采样和枚举值提示。

• JOIN 候选关系。

• UDF 信息。

• 表级和字段级语义建议。

• 已验证 SQL 和相关查询记忆索引。

常用构建参数如下：

构建后可以查看当前语义包：

mcs show
mcs show --table <table-name>
mcs status --tables

构建完成后，mcs 可能会对表描述、字段含义等生成语义建议，建议通过 proposal 流程审查后再写入语义包：

mcs package propose --from-suggestions
mcs package list-proposals
mcs package show-proposal <id>
mcs package apply <id>

Agent工作方式

安装 Skill 后，Agent 会根据任务加载不同的运行时 workflow。例如：

回答数据问题时，Agent 不会主动运行 mcs build 或 mcs package propose。构建和 proposal是维护操作，只在用户明确要求时才执行。

如果当前没有语义包，Agent 会自动改用实时元数据模式：通过 mcs meta 读取 MaxCompute元数据，再完成 SQL 审查、成本预估和查询执行。不需要提前构建语义包也能正常提问，只是回答质量会低于有语义包时。

SQL 审查、成本预估与执行

mcs sql 命令提供从 SQL 审查到执行的完整链路：

默认情况下，mcs sql execute 和 mcs sql submit 是只读的，会拒绝 INSERT、UPDATE、DELETE、MERGE、CREATE、DROP、ALTER、TRUNCATE、GRANT、REVOKE 等写操作。只有用户明确要求写操作时，才应使用 --allow-write。

成本门禁会在提交前执行：

• 成本低于确认阈值：允许执行。

• 成本超过确认阈值：交互式终端会要求用户确认；非交互环境会拒绝并返回需要确认的信息。

• 成本超过阻断阈值：直接拒绝执行。

执行耗时较长的分析查询时，建议使用异步流程：

mcs -f json sql submit -y '<SQL>'
mcs -f json sql wait <instance_id>
mcs -f json sql result <instance_id>

同步执行超时时，查询不会被取消。命令会返回 instance_id 和下一步命令，后续应继续使用 mcs sql wait/mcs sql result 获取结果，不要重复提交同一 SQL。

查询记忆与业务指标

查询结果经用户确认正确后，可以记录为查询记忆：

mcs memory verify --question "<自然语言问题>" --sql '<SQL>' --tables table_a,table_b

失败的查询也可以记录，用于避免重复错误：

mcs memory fail --question "<自然语言问题>" --sql '<SQL>' --error-msg '<错误信息>' --remediation '<修复方式>'

后续可通过下面命令召回：

mcs memory recall "<关键词或问题>"

对于有固定业务口径的指标，建议使用 mcs metric 维护 profile 级指标：

mcs metric add gmv \
  --expression "SUM(pay_amount)" \
  --description "成交金额" \
  --ai-context "GMV 使用订单支付金额求和，排除取消订单。"

Agent 生成 SQL 前应优先检查是否已有同名或相近指标，避免重复实现不同口径。

安全与隐私

• 本地数据保护

  profile、语义包和查询记忆默认保存在本地文件系统，请按企业数据安全要求管理这些文件。不要将以下内容提交到公开仓库：profile 配置、语义包、查询结果、Logview、错误日志、包含业务敏感信息的 SQL。

• 凭证安全

  • 建议在 profile 中使用环境变量引用 AK，不要把 AccessKey 明文写入文件。

  • 使用 process auth 时，profile 中只保存凭证命令；该命令输出的 STS 临时凭证同样属于敏感信息，不要写入日志、文档或代码仓库。

• 权限与操作边界

  • 为 mcs 使用的 MaxCompute 身份配置最小必要权限。

  • mcs build 只读取 profile 中声明的数据源范围；如启用采样，采样也只作用于这些表。

  • 写操作默认被拒绝。只有用户明确要求时，才使用 --allow-write。

  • 成本门禁不能替代人工判断。大表扫描、跨 project JOIN 或无分区过滤的查询，应先缩小范围或改用异步流程。

安装后找不到 mcs 命令

通常是 uv tool install 的脚本目录不在 PATH 中。macOS/Linux 默认位置一般为 ~/.local/bin。可执行：

export PATH="$HOME/.local/bin:$PATH"
mcs --version

确认可用后，再把 PATH 配置写入 shell 配置文件。

profile 创建后连接失败

请依次检查：

1. Endpoint 与 MaxCompute project 所在 Region 是否匹配。

2. AK 是否有效；如果使用 process auth，确认凭证命令可执行，并且标准输出是包含 AccessKeyId、AccessKeySecret、SecurityToken 的 STS 临时凭证 JSON。

3. 当前网络是否可以访问对应 MaxCompute endpoint。

4. 当前身份是否有目标 project 和表的访问权限。

5. 如果使用环境变量引用凭证，变量名和值是否在当前 shell 中可见。

可以运行：

mcs doctor
mcs profile whoami <profile-name>

Agent 回答问题时提示没有语义包

说明当前 profile 尚未构建或当前目录没有绑定到正确 profile。可以先检查：

mcs link status
mcs show
mcs status

如果用户明确希望构建语义包，再执行 mcs build。

回答单次数据问题时，不建议让 Agent 自动运行 mcs build。没有语义包时，Agent 可以通过 mcs meta 走 cold-start 查询流程。

SQL写操作被拒绝

mcs sql execute 和 mcs sql submit 默认只允许只读查询。如果用户确实要执行写 SQL，需要显式使用：

mcs sql execute --allow-write '<SQL>'

执行前请确认目标 project、schema、table、SQL 影响范围和回滚方案。

查询成本过高被阻断

请先缩小查询范围，例如：

• 增加分区过滤。

• 增加更明确的 WHERE 条件。

• 使用预览 LIMIT。

• 先按小范围样本验证 SQL。

• 对长时间分析查询使用异步流程。

成本超过 profile 的阻断阈值时，mcs 会拒绝提交查询。需要调整 SQL 或由 profile 管理者修改成本阈值。

构建语义包耗时较长

语义包构建会读取元数据、采样字段值并推断 JOIN 候选，数据源范围较大时可能耗时较长。可以使用：

mcs build --tables table_a,table_b
mcs build --no-sampling
mcs build --no-joins

也可以先构建核心业务表，待验证效果后再扩大范围。