文档

[00]概念：profile、语义包、业务场景

用 mcs 之前先认这三个名词，后面所有命令都围着它们转。

• profile —— 一份配置，回答两个问题：我是谁（AK 还是免密、解析成哪个 RAM 主体）+ 我看哪些表（一个或多个 source，每个 source 是一组 project.schema.tables）。一台机器可以有任意多个 profile。
• 语义包 —— mcs build 把 profile 圈起来的所有表扫一遍，采样几行、推 JOIN 关系、发现 UDF，落到本地一个文件夹。agent 写 SQL 之前先读这个包，不用每次现去翻 MaxCompute meta。
• 业务场景 —— 不是 mcs 里的实体，是用法约定：一个业务边界对应一个 profile（数仓 A 一个、营销 B 一个、跨域口径再一个）。同一个 profile 下累积的语义标注（通过 proposal 队列写入）和 memory（验证过的 SQL）都跟着这条业务线走。

[01]快速入门

5 分钟，从 0 到第一条 SQL。

1.装 mcs

让 agent 装是最快的路径，它会顺手把 skill 也装好。把下面这段话发给 agent：

copyagent> 帮我安装 mcs，先读完这个指南再逐步执行：curl -fsSL https://raw.githubusercontent.com/aliyun/maxcompute-semantic/main/scripts/install.md

或者自己装：

copy$ uv tool install maxcompute-semantic

装好以后跑 mcs --version 确认。如果 ~/.local/bin 不在 PATH 里，需要加上（见 README）。

2.创建 profile

copy$ mcs profile create

向导会问：profile 名字、要接的 MaxCompute project、AK 还是免密、endpoint 区域。所有字段都能后改（mcs profile update）。

For AK auth, prefer environment-variable references or ProcessAuth/ncs. For non-interactive literal-AK setup, pass --ak-literal with --ak-id and pipe one secret line with --ak-secret-stdin; avoid --ak-secret unless shell-history exposure is acceptable.

3.把当前目录绑到 profile

copy$ cd ~/work/my-data-project
$ mcs link bind <profile-name>

查看 / 解绑：mcs link status、mcs link unlink。

4.跑一次 build（生成语义包）

copy$ mcs build

跑完后 mcs status --tables 看采到的表 / 列 / JOIN 数量。表结构变了重跑 mcs build --refresh 只更新变过的表。不是必须步骤：跳过也行，agent 没语义包时走 cold-start（mcs meta list-tables / describe-table）现问元数据——能用但每次更慢。

5.开始问

copyagent> 用 mcs 查一下上个月 orders 表的 GMV

agent 会自动调 mcs sql cost 估价、mcs sql execute 执行、再用人话总结结果给你。如果不放心可以直接终端跑 mcs sql execute "..."。

[02]Profile：身份、组织与版本

profile 是 mcs 的"我是谁、我连哪儿"的单一抽象。一份 profile 包含：MaxCompute 计算 project、endpoint、认证方式（AK / 免密）、要扫描的 source 列表（每个 source 是一组 project.schema.tables）、成本阈值。

profile ──build──▶ 语义包 ──reads──▶ agent 写 SQL
   │
   └─ 圈起一个业务场景（一组 source + 一份身份 + 配套语义标注/memory）

2.1解析链：当前是哪个 profile？

每个 mcs 命令按这个顺序找 profile，命中即用：

1. 显式 --profile X 标志
2. 环境变量 MCS_PROFILE
3. 当前目录的 mcs link bind 绑定
4. 标准 ODPS 环境变量四元组（ALIBABA_CLOUD_ACCESS_KEY_ID 等）—— 构造一个内存里的临时 profile

想知道当下是哪个：mcs profile show。

2.2创建：wizard 与多源 DataSource

copy$ mcs profile create

交互向导一步步问：名字、compute project、endpoint、auth、要纳入语义包的 sources。一个 profile 可以挂多个 source（比如同时扫数仓的 dwd 和 ads，或者跨两个 project），mcs build 会一次走完所有 source。对 agent 流程，向导会先问你这个语义包要解决什么场景（业务问题、领域、关心的指标），把它记成 profile 的 description；选表时 agent 会根据这个场景描述从 mcs meta list-tables 的结果里推荐候选表，你在候选基础上增删即可，不用从几百张表里盲选。mcs build 会把这段描述写进语义包的 _overview.md。

For AK auth, prefer environment-variable references or ProcessAuth/ncs. For non-interactive literal-AK setup, pass --ak-literal with --ak-id and pipe one secret line with --ak-secret-stdin; avoid --ak-secret unless shell-history exposure is acceptable.

复用 maxc / odpscmd 配置时用 mcs profile import-creds。如果外部配置里是非 ncs 的 ProcessAuth helper，CLI 会先显示完整命令并要求显式信任；确认这条本地命令可信后， 再用 --trust-process-command 导入。

已经创建过、想后改字段：

copy$ mcs profile update <name>

会进多级 picker：compute_project / endpoint / auth / cost_thresholds / tags / sources，选哪行改哪行。

2.3cwd 绑定：mcs link bind

把一个目录绑到一个 profile，之后这个目录里 mcs 命令默认认这个 profile：

copy$ cd ~/work/biz-A
$ mcs link bind biz-A-prod
# 之后在这个目录跑任何 mcs 命令都默认 biz-A-prod profile

查看 / 解绑：mcs link status、mcs link unlink。绑定存的是当前目录到 profile 名字的映射，跟着工作目录走，shell 重启不丢。

2.4查看与切换：show / whoami

调试"我的 AK 到底解析到了谁"用 whoami；只是看配置用 show。

2.5版本管理：log / diff / fork / reset

每个 profile 的数据目录是一个独立 git 仓库。mcs build / package apply/reject / memory / udf / profile import 每写一次都自动 commit 一笔。

copy$ mcs profile log -n 10           # 最近 10 次写入
$ mcs profile diff HEAD~1 HEAD     # 上一次写入改了啥
$ mcs profile reset --to HEAD~1    # 误操作回滚
$ mcs profile fork exp --from HEAD # 拉个分支做 A/B

不想要这套自动版本（比如 CI 跑批），设环境变量 MCS_NO_VERSIONING=1，写入照常但不 commit。

2.6导出与分享：profile export

把一份 profile 的语义包打包成一个文件，方便发给同事或迁机。默认产物是 mcs 自己的 tar.gz 归档，可以用 mcs profile import 原样还原。

copy$ mcs profile export <name>                  # 默认写到 ./<name>.tar.gz
$ mcs profile export <name> --osi            # 改写 OSI YAML

With --osi, the same command emits OSI (Open Semantic Interchange) YAML instead of a tar.gz archive — useful for feeding the profile's semantic model into external OSI-aware tooling. Output conforms to OSI core schema v0.2.0.dev0. The mcs-native tar.gz export is still the default; --osi opts into the YAML path.

[03]主流查询：build · package · sql

使用 mcs 的主路径：先 build 出语义包；build 证据生成的语义建议进 package proposal 队列审核后 apply 写入；最后用 sql 跑、估价、看计划。

3.1mcs build：什么时候跑、--refresh / --fresh / --parallel

把 profile 里 sources 列表覆盖的所有表 scan 一遍，采样几行，推断 JOIN 关系，发现 UDF，落地到本地语义包。后续 agent 写 SQL 之前先读这个包，少走弯路。

copy$ mcs build                  # 第一次全量；被中断后再跑会自动续传，跳过已建好的表
$ mcs build --fresh          # 强制从头全量重建，忽略续传状态
$ mcs build --refresh        # 增量：rebuild schema 或数据变了的表（也补齐被中断遗留的未完成表）
$ mcs build --refresh --refresh-min-age-hours 6  # 数据变了就重采的节流：上次采样超 N 小时才重采（默认 24，0 = 不节流）
$ mcs build --parallel 8     # 并发 8 个表同时采样（默认 auto = min(表数, 32)）

3.2mcs package：审核 build 生成的语义建议

build / refresh 之后，agent 可以把采样、历史 SQL、字段分布里推出来的高置信建议放进 proposal 队列，也可以把自己审过的 ai_context、列描述和列角色修正作为 YAML proposal 提交。proposal 是"待审核补丁"：看得到目标列、建议内容、证据和置信度；只有 apply 后才会写进语义包，reject 会把决策也记录下来。

copy$ mcs package propose --from-suggestions
$ mcs package propose --from-stdin      # 从 YAML 创建 ai_context / column_description / column_semantics proposals
$ mcs package list-proposals
$ mcs package show-proposal <id>
$ mcs package apply <id>
$ mcs package reject <id> --reason "not correct for this domain"

这是生成式语义建议的默认路径：先 propose --from-suggestions，再用 propose --from-stdin 补 agent 审过的表语义、列描述或 role 修正；如果同一轮 enrich 里需要纠正早先 reject 的 agent YAML proposal，--from-stdin 会把它重新放回 suggested 队列。然后逐条 show-proposal 看证据，正确的 apply，不符合业务口径的 reject 并写原因。agent 的 enrich runtime skill 也走这条链路。

3.3语义标注：全部通过 proposal 队列

所有语义标注写入都通过 mcs package propose → 审核 → mcs package apply，没有直写入口。可以标注的业务语义包括：

• ai_context —— 这张表是干嘛的（一段自然语言描述）
• dimensions / measures / identifiers —— 列的角色分类
• 每列的 semantic_description —— 这列是啥（语义解释，不是字段名重述）

copy$ mcs package propose --from-stdin # 提交待审核的语义标注 proposal
$ mcs package list-proposals # 查看待审核队列
$ mcs package apply <id> # 审核通过后写入

看哪些表标了哪些没标：mcs status --tables，最后一列是 Annotated: yes/no/partial。

3.4mcs metric：自上而下命名业务指标

把"用户每月已支付订单总金额"这类有业务名字、会反复用的算法 显式登记下来，下次问到直接复用，不用每次重新拼 SQL。 metric 是 profile 全局的 UNIQUE(name)，跨 source 也只能有一个 total_revenue。

copy$ mcs metric add total_revenue --expression "SUM(orders.amount)"
$ mcs metric list
$ mcs metric show total_revenue
$ mcs metric edit total_revenue --description "..."
$ mcs metric remove total_revenue

批量导入也支持：mcs package propose --from-stdin 接受顶层的 metrics: 列表（和 tables: 并列），通过 proposal 队列审核后写入。

OSI 导出（mcs profile export --osi）会把这些 metric 写到 semantic_model.metrics[]，下游 OSI 工具直接读得到。

3.5mcs sql：review / execute / async / cost / explain

这些动词覆盖"跑 SQL"的全部场景：

copy$ mcs sql review  "SELECT IIF(x > 0, 1, 0) FROM orders"
# → issues[0].rule = dialect.sqlite-iif · 建议改写成 CASE WHEN
$ mcs sql execute "SELECT COUNT(*) FROM orders WHERE ds = '20260520'"
$ mcs sql submit -y "SELECT * FROM big_a JOIN big_b ON big_a.id = big_b.id"
$ mcs sql wait <instance_id>   # 看 lifecycle_state / successful
$ mcs sql result <instance_id> # lifecycle_state == "success" 后再取 rows
$ mcs sql result --offset 10000 <instance_id> # has_more=true 时取下一页
$ mcs sql cost    "SELECT * FROM orders"
# → verdict: confirm · cost 12.4 CNY · 大表全扫，建议加分区
$ mcs sql explain "SELECT ds, SUM(amount) FROM orders GROUP BY ds"

注意：mcs sql cost 即使 blocked 也以 exit code 0 返回 —— verdict 在 JSON 输出的 verdict 字段里，写脚本要读字段不要读 exit code。

3.6--project / --schema / --profile 的传法

三个标志意思完全不同，最容易记混：

2 级 project（没开 schema）跟 3 级 project 的差别 mcs 自动处理，你写 orders 它会变成 my_proj.orders 或 my_proj.default.orders，不用记。

[04]进阶：memory · udf · meta

这一节是给已经走完主路径、想让 mcs 越用越准的人。

4.1memory：verify / fail / note / recall

memory 是查询经验库。每问一次 / 每错一次，都可以记下来，下次类似问题就有了参考。三个写入动词 + 一个读取动词：

copy$ mcs memory verify \
    --question "上个月 GMV" \
    --sql "SELECT SUM(amount) FROM orders WHERE ds BETWEEN '20260401' AND '20260430'" \
    --tables orders
$ mcs memory recall "GMV"

管理：memory list 看全部，memory show <id> 看单条，memory remove <id> 删一条，memory clear 清空（默认只清用户写入，不清自动生成的）。

4.2udf：list / show / search / create / test / remove

读侧（任何人可跑）：

copy$ mcs udf list
$ mcs udf show parse_user_agent
$ mcs udf search "json"

写侧（要确认 / 需要写权限）：

copy$ mcs udf create my_fn --inline-python my_fn.py --description "解析订单号前缀"
$ mcs udf test   my_fn --args '1, "abc"'
$ mcs udf remove my_fn --delete-resources

udf test --args 只接受 literal：数字、NULL、TRUE/FALSE 和带引号字符串；不会把裸标识符、表达式或分号片段拼进 SQL。当前 create 只支持 inline Python；要挂 jar / resource 的 UDF 走 mcs sql execute --allow-write 'CREATE FUNCTION ...'，仍需用户确认且仍过 cost gate。

4.3meta：list-tables / describe-table

不依赖语义包、直接打 MaxCompute 元数据的"原始"接口。冷启动（还没 build）、临时查不在 sources 里的表时用：

copy$ mcs meta list-tables --project my_proj
$ mcs meta describe-table --project my_proj orders

已经 build 过的表，用 mcs show --table orders 更好 —— 带样例 SQL、JOIN 关系、注释，是语义包里"凝固"的版本。

[05]运维与排查

遇到错的时候、装到新机器的时候、想知道环境啥状态的时候看这里。

5.1mcs doctor：一键自检 + JSON 输出

一条命令把 profile / 认证 / 网络 / 语义包 / skill 装得对不对全部检查一遍：

copy$ mcs doctor                # 全部检查，含网络
$ mcs doctor --offline      # 不打 ODPS，只看本地配置 / 包 / skill
$ mcs -f json doctor        # 给 agent 解析的 JSON 输出，含每条 remediation

典型用法：装完一遍 mcs doctor 看绿；出错时第一反应 mcs -f json doctor 看哪条红了。agent 调用 doctor 后会按 JSON 里的 remediation 字段一步步引导你修。

5.2skill install：55 平台、--all / --detect

把 SKILL.md 软链到你的 agent 工具的 skills 目录。软链而不是拷贝，所以 mcs 升级时 skill 自动同步，不会版本漂移。

copy$ mcs skill install                       # 默认装到 .agents/skills/ (项目级)
$ mcs skill install -g                    # 装到全局 (~/.agents/skills/)
$ mcs skill install -p claude-code -g     # 指定 Claude Code 全局
$ mcs skill install --all                 # 装到全部 55+ 平台
$ mcs skill install --detect              # 只装到本机检测到的 agent

常用平台对应表：

完整 55+ 平台清单：mcs skill list。其它操作：mcs skill update / uninstall / path / diff。

copy$ mcs skill catalog
$ mcs skill get query
$ mcs skill get query --full
$ mcs skill get build

5.32 级 vs 3 级 tier 自动探测

MaxCompute project 有两种寻址：2 级（project.table）和 3 级（project.schema.table）。mcs 第一次访问一个 project 时自动探一次，结果缓存到 tier_cache/<project>，之后无需 SET odps.namespace.schema，也不用 --schema。

探错了想强制重测：删掉 ~/.local/share/maxcompute-semantic/data/<profile>/tier_cache/<project> 这个一字节小文件即可。极端兜底：所有 mcs 命令都接受 --schema S 显式覆盖。

5.4常用环境变量

truthy 值大小写不敏感：1 / true / yes / on。

[06]给 Agent 的"对话脚本"

mcs 装上 skill 之后，你跟 agent 说话就够了 —— agent 会自动调 mcs 命令。这一节给的是"该说什么"的范本。

6.1唤起 skill 的话术

大多数 agent 见到下面这类关键词会自动加载 maxcompute-semantic skill：

• 明说品牌名："用 mcs"、"用 maxcompute"、"用 ODPS"
• 显式调 skill："/maxcompute-semantic ..."（Claude Code / Codex 等支持斜杠的 agent）
• 动词触发："查一下"、"建表"、"算个"、"统计一下" + 一张你的 MaxCompute 表名

如果 agent 没唤起 skill（直接生成了不能跑的 SQL），最稳的兜底是显式提："请加载 maxcompute-semantic skill 再回答"。

6.2常见任务示例

copyagent> 用 mcs 查一下上个月 orders 表的 GMV
agent> ODPS 上 products 这张表是干嘛的？字段都什么意思？
agent> 上次问过的 DAU 算法还记得吗？把那条 SQL 重跑一下
agent> 这条 SQL 估一下要花多少钱：<贴 SQL>
agent> 把刚才这条跑通的 SQL 记到 mcs memory 里，问题叫 "月度活跃用户"

agent 会按需调 sql cost 估价，用 sql execute 跑探针/小结果查询，或用 sql submit / sql wait / sql result 跑正式分析、confirm 成本和可能超时的查询；也会用 show --table 查结构、memory recall 找历史、memory verify 沉淀新经验。

6.3让 agent 报 bug / 自检

copyagent> 帮我报一个 mcs 的 bug：<描述现象>
agent> mcs 环境检查一下

报 bug 时 skill 会按 Aone 工单规范走 —— 自动加 [maxcompute-semantic] 前缀、设关联项目 2155299、把版本号和 doctor 输出附进去。环境检查会跑 mcs -f json doctor 并把红条目用人话讲给你听。