maxc-cli 0.4.7__tar.gz → 0.5.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {maxc_cli-0.4.7 → maxc_cli-0.5.0}/MANIFEST.in +0 -1
- maxc_cli-0.5.0/PKG-INFO +253 -0
- maxc_cli-0.5.0/README.md +231 -0
- {maxc_cli-0.4.7 → maxc_cli-0.5.0}/pyproject.toml +1 -1
- {maxc_cli-0.4.7 → maxc_cli-0.5.0}/scripts/regression_test.py +0 -1
- {maxc_cli-0.4.7 → maxc_cli-0.5.0}/setup.py +7 -3
- {maxc_cli-0.4.7 → maxc_cli-0.5.0}/src/maxc_cli/__init__.py +1 -1
- {maxc_cli-0.4.7 → maxc_cli-0.5.0}/src/maxc_cli/_samples.py +51 -38
- {maxc_cli-0.4.7 → maxc_cli-0.5.0}/src/maxc_cli/agent_platforms.py +8 -6
- {maxc_cli-0.4.7 → maxc_cli-0.5.0}/src/maxc_cli/app.py +3178 -580
- maxc_cli-0.5.0/src/maxc_cli/audit.py +111 -0
- maxc_cli-0.5.0/src/maxc_cli/auth_continuation.py +218 -0
- {maxc_cli-0.4.7 → maxc_cli-0.5.0}/src/maxc_cli/auth_providers.py +149 -11
- maxc_cli-0.5.0/src/maxc_cli/backend/auth.py +308 -0
- {maxc_cli-0.4.7 → maxc_cli-0.5.0}/src/maxc_cli/backend/catalog.py +9 -0
- maxc_cli-0.5.0/src/maxc_cli/backend/data.py +1122 -0
- maxc_cli-0.5.0/src/maxc_cli/backend/job.py +788 -0
- {maxc_cli-0.4.7 → maxc_cli-0.5.0}/src/maxc_cli/backend/meta.py +40 -3
- {maxc_cli-0.4.7 → maxc_cli-0.5.0}/src/maxc_cli/backend/odps.py +78 -56
- {maxc_cli-0.4.7 → maxc_cli-0.5.0}/src/maxc_cli/backend/query.py +164 -49
- maxc_cli-0.5.0/src/maxc_cli/cache.py +1546 -0
- {maxc_cli-0.4.7 → maxc_cli-0.5.0}/src/maxc_cli/catalog_bootstrap.py +9 -1
- maxc_cli-0.5.0/src/maxc_cli/cli.py +4720 -0
- {maxc_cli-0.4.7 → maxc_cli-0.5.0}/src/maxc_cli/config.py +361 -52
- {maxc_cli-0.4.7 → maxc_cli-0.5.0}/src/maxc_cli/exceptions.py +85 -4
- {maxc_cli-0.4.7 → maxc_cli-0.5.0}/src/maxc_cli/helpers.py +60 -12
- maxc_cli-0.5.0/src/maxc_cli/job_ids.py +48 -0
- {maxc_cli-0.4.7 → maxc_cli-0.5.0}/src/maxc_cli/models.py +338 -44
- maxc_cli-0.5.0/src/maxc_cli/oauth.py +648 -0
- maxc_cli-0.5.0/src/maxc_cli/odps_runtime.py +37 -0
- {maxc_cli-0.4.7 → maxc_cli-0.5.0}/src/maxc_cli/output.py +113 -30
- maxc_cli-0.5.0/src/maxc_cli/skills/SKILL.md +290 -0
- maxc_cli-0.5.0/src/maxc_cli/skills/agents/openai.yaml +4 -0
- maxc_cli-0.5.0/src/maxc_cli/skills/references/bootstrap-auth.md +137 -0
- maxc_cli-0.5.0/src/maxc_cli/skills/references/bootstrap-flow.md +68 -0
- {maxc_cli-0.4.7 → maxc_cli-0.5.0}/src/maxc_cli/skills/references/command-patterns.md +107 -17
- {maxc_cli-0.4.7 → maxc_cli-0.5.0}/src/maxc_cli/skills/references/json-output-format.md +26 -14
- {maxc_cli-0.4.7 → maxc_cli-0.5.0}/src/maxc_cli/skills/references/maxcompute-select-guide.md +1 -1
- {maxc_cli-0.4.7 → maxc_cli-0.5.0}/src/maxc_cli/skills/references/maxcompute-sql-notes.md +11 -3
- {maxc_cli-0.4.7 → maxc_cli-0.5.0}/src/maxc_cli/skills/references/red-lines.md +19 -19
- maxc_cli-0.5.0/src/maxc_cli/skills/references/setup-install.md +79 -0
- {maxc_cli-0.4.7 → maxc_cli-0.5.0}/src/maxc_cli/skills/references/sql-common-errors.md +11 -11
- maxc_cli-0.5.0/src/maxc_cli/state_permissions.py +403 -0
- maxc_cli-0.5.0/src/maxc_cli/store.py +252 -0
- maxc_cli-0.5.0/src/maxc_cli/utils.py +795 -0
- maxc_cli-0.5.0/src/maxc_cli.egg-info/PKG-INFO +253 -0
- {maxc_cli-0.4.7 → maxc_cli-0.5.0}/src/maxc_cli.egg-info/SOURCES.txt +24 -1
- maxc_cli-0.5.0/tests/test_agent_hints_and_cli.py +750 -0
- {maxc_cli-0.4.7 → maxc_cli-0.5.0}/tests/test_agent_platforms.py +12 -15
- {maxc_cli-0.4.7 → maxc_cli-0.5.0}/tests/test_agent_skill_commands.py +132 -0
- {maxc_cli-0.4.7 → maxc_cli-0.5.0}/tests/test_agent_skill_commands_context.py +222 -44
- maxc_cli-0.5.0/tests/test_ai_native_contract_regressions.py +773 -0
- maxc_cli-0.5.0/tests/test_auth_logout.py +184 -0
- maxc_cli-0.5.0/tests/test_backend_auth.py +149 -0
- maxc_cli-0.5.0/tests/test_backend_data.py +60 -0
- maxc_cli-0.5.0/tests/test_backend_data_serialization.py +783 -0
- {maxc_cli-0.4.7 → maxc_cli-0.5.0}/tests/test_backend_meta.py +40 -0
- maxc_cli-0.5.0/tests/test_build_release_archive_compat.py +96 -0
- {maxc_cli-0.4.7 → maxc_cli-0.5.0}/tests/test_build_release_script.py +8 -1
- maxc_cli-0.5.0/tests/test_cache.py +796 -0
- {maxc_cli-0.4.7 → maxc_cli-0.5.0}/tests/test_cli_arg_validation.py +22 -0
- maxc_cli-0.5.0/tests/test_cli_mock.py +5750 -0
- maxc_cli-0.5.0/tests/test_config_atomic_write.py +110 -0
- {maxc_cli-0.4.7 → maxc_cli-0.5.0}/tests/test_error_translation.py +10 -0
- {maxc_cli-0.4.7 → maxc_cli-0.5.0}/tests/test_exit_codes.py +26 -0
- {maxc_cli-0.4.7 → maxc_cli-0.5.0}/tests/test_external_auth.py +234 -5
- {maxc_cli-0.4.7 → maxc_cli-0.5.0}/tests/test_flag_hoist.py +22 -6
- {maxc_cli-0.4.7 → maxc_cli-0.5.0}/tests/test_help_format.py +2 -0
- {maxc_cli-0.4.7 → maxc_cli-0.5.0}/tests/test_help_version_e2e.py +49 -17
- maxc_cli-0.5.0/tests/test_installer_contracts.py +218 -0
- {maxc_cli-0.4.7 → maxc_cli-0.5.0}/tests/test_integration_real.py +99 -37
- {maxc_cli-0.4.7 → maxc_cli-0.5.0}/tests/test_job_improvements.py +64 -7
- maxc_cli-0.5.0/tests/test_job_store_durability.py +194 -0
- maxc_cli-0.5.0/tests/test_manifest_runtime_contract.py +473 -0
- maxc_cli-0.5.0/tests/test_meta_schema_and_partition_cols.py +565 -0
- maxc_cli-0.5.0/tests/test_oauth.py +873 -0
- maxc_cli-0.5.0/tests/test_odps_runtime.py +66 -0
- maxc_cli-0.5.0/tests/test_output_action_safety.py +203 -0
- maxc_cli-0.5.0/tests/test_output_format_contract.py +847 -0
- maxc_cli-0.5.0/tests/test_packaging_metadata.py +68 -0
- {maxc_cli-0.4.7 → maxc_cli-0.5.0}/tests/test_phase1_improvements.py +181 -4
- {maxc_cli-0.4.7 → maxc_cli-0.5.0}/tests/test_pyinstaller_bundle.py +16 -0
- maxc_cli-0.5.0/tests/test_python39_compat.py +98 -0
- {maxc_cli-0.4.7 → maxc_cli-0.5.0}/tests/test_query_auto_promote.py +182 -4
- maxc_cli-0.5.0/tests/test_query_result_csv_fallback.py +487 -0
- maxc_cli-0.5.0/tests/test_semantic_scope.py +323 -0
- {maxc_cli-0.4.7 → maxc_cli-0.5.0}/tests/test_setting_parser.py +159 -3
- {maxc_cli-0.4.7 → maxc_cli-0.5.0}/tests/test_skill_renderer.py +1 -1
- maxc_cli-0.5.0/tests/test_startup_imports.py +115 -0
- maxc_cli-0.5.0/tests/test_state_permissions.py +456 -0
- maxc_cli-0.5.0/tests/test_state_portability.py +95 -0
- maxc_cli-0.4.7/PKG-INFO +0 -195
- maxc_cli-0.4.7/README.md +0 -173
- maxc_cli-0.4.7/src/maxc_cli/audit.py +0 -18
- maxc_cli-0.4.7/src/maxc_cli/backend/auth.py +0 -164
- maxc_cli-0.4.7/src/maxc_cli/backend/data.py +0 -615
- maxc_cli-0.4.7/src/maxc_cli/backend/job.py +0 -411
- maxc_cli-0.4.7/src/maxc_cli/cache.py +0 -717
- maxc_cli-0.4.7/src/maxc_cli/cli.py +0 -2154
- maxc_cli-0.4.7/src/maxc_cli/skills/SKILL.md +0 -269
- maxc_cli-0.4.7/src/maxc_cli/skills/agents/openai.yaml +0 -4
- maxc_cli-0.4.7/src/maxc_cli/skills/references/bootstrap-auth.md +0 -299
- maxc_cli-0.4.7/src/maxc_cli/skills/references/bootstrap-flow.md +0 -97
- maxc_cli-0.4.7/src/maxc_cli/skills/references/setup-install.md +0 -108
- maxc_cli-0.4.7/src/maxc_cli/store.py +0 -123
- maxc_cli-0.4.7/src/maxc_cli/utils.py +0 -165
- maxc_cli-0.4.7/src/maxc_cli.egg-info/PKG-INFO +0 -195
- maxc_cli-0.4.7/tests/test_agent_hints_and_cli.py +0 -342
- maxc_cli-0.4.7/tests/test_backend_data.py +0 -29
- maxc_cli-0.4.7/tests/test_backend_data_serialization.py +0 -247
- maxc_cli-0.4.7/tests/test_cache.py +0 -121
- maxc_cli-0.4.7/tests/test_cli_mock.py +0 -2585
- maxc_cli-0.4.7/tests/test_meta_schema_and_partition_cols.py +0 -232
- maxc_cli-0.4.7/tests/test_query_result_csv_fallback.py +0 -235
- {maxc_cli-0.4.7 → maxc_cli-0.5.0}/scripts/pyinstaller_entry.py +0 -0
- {maxc_cli-0.4.7 → maxc_cli-0.5.0}/setup.cfg +0 -0
- {maxc_cli-0.4.7 → maxc_cli-0.5.0}/src/maxc_cli/__main__.py +0 -0
- {maxc_cli-0.4.7 → maxc_cli-0.5.0}/src/maxc_cli/backend/__init__.py +0 -0
- {maxc_cli-0.4.7 → maxc_cli-0.5.0}/src/maxc_cli/help_format.py +0 -0
- {maxc_cli-0.4.7 → maxc_cli-0.5.0}/src/maxc_cli/masking.py +0 -0
- {maxc_cli-0.4.7 → maxc_cli-0.5.0}/src/maxc_cli/setting_parser.py +0 -0
- {maxc_cli-0.4.7 → maxc_cli-0.5.0}/src/maxc_cli/skills/references/partition-guide.md +0 -0
- {maxc_cli-0.4.7 → maxc_cli-0.5.0}/src/maxc_cli/skills/references/sql-query-patterns.md +0 -0
- {maxc_cli-0.4.7 → maxc_cli-0.5.0}/src/maxc_cli/skills/references/text2sql-principles.md +0 -0
- {maxc_cli-0.4.7 → maxc_cli-0.5.0}/src/maxc_cli.egg-info/dependency_links.txt +0 -0
- {maxc_cli-0.4.7 → maxc_cli-0.5.0}/src/maxc_cli.egg-info/entry_points.txt +0 -0
- {maxc_cli-0.4.7 → maxc_cli-0.5.0}/src/maxc_cli.egg-info/requires.txt +0 -0
- {maxc_cli-0.4.7 → maxc_cli-0.5.0}/src/maxc_cli.egg-info/top_level.txt +0 -0
- {maxc_cli-0.4.7 → maxc_cli-0.5.0}/tests/test_catalog.py +0 -0
- {maxc_cli-0.4.7 → maxc_cli-0.5.0}/tests/test_catalog_bootstrap.py +0 -0
- {maxc_cli-0.4.7 → maxc_cli-0.5.0}/tests/test_cli_query_parse_and_sanitize.py +0 -0
- {maxc_cli-0.4.7 → maxc_cli-0.5.0}/tests/test_compat.py +0 -0
- {maxc_cli-0.4.7 → maxc_cli-0.5.0}/tests/test_e2e_smoke.py +0 -0
- {maxc_cli-0.4.7 → maxc_cli-0.5.0}/tests/test_envelope_shape.py +0 -0
- {maxc_cli-0.4.7 → maxc_cli-0.5.0}/tests/test_error_self_correction.py +0 -0
- {maxc_cli-0.4.7 → maxc_cli-0.5.0}/tests/test_helpers.py +0 -0
- {maxc_cli-0.4.7 → maxc_cli-0.5.0}/tests/test_helpers_csv.py +0 -0
- {maxc_cli-0.4.7 → maxc_cli-0.5.0}/tests/test_integration.py +0 -0
- {maxc_cli-0.4.7 → maxc_cli-0.5.0}/tests/test_masking.py +0 -0
- {maxc_cli-0.4.7 → maxc_cli-0.5.0}/tests/test_skill_cli_consistency.py +0 -0
- {maxc_cli-0.4.7 → maxc_cli-0.5.0}/tests/test_skill_eval.py +0 -0
maxc_cli-0.5.0/PKG-INFO
ADDED
|
@@ -0,0 +1,253 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: maxc-cli
|
|
3
|
+
Version: 0.5.0
|
|
4
|
+
Summary: Agent-native MaxCompute CLI for external coding agents
|
|
5
|
+
Classifier: Programming Language :: Python :: 3
|
|
6
|
+
Classifier: Programming Language :: Python :: 3.9
|
|
7
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
8
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
9
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
10
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
11
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
12
|
+
Requires-Python: >=3.9
|
|
13
|
+
Description-Content-Type: text/markdown
|
|
14
|
+
Requires-Dist: PyYAML>=5.4
|
|
15
|
+
Requires-Dist: pyodps>=0.12.0
|
|
16
|
+
Dynamic: classifier
|
|
17
|
+
Dynamic: description
|
|
18
|
+
Dynamic: description-content-type
|
|
19
|
+
Dynamic: requires-dist
|
|
20
|
+
Dynamic: requires-python
|
|
21
|
+
Dynamic: summary
|
|
22
|
+
|
|
23
|
+
# maxc-cli
|
|
24
|
+
|
|
25
|
+
使用 Alibaba Cloud CLI 控制 MaxCompute 云产品。`aliyun maxc` 提供
|
|
26
|
+
MaxCompute 元数据、SQL、作业、权限和数据传输等数据面操作。公共云 Skill
|
|
27
|
+
名称为 `alibabacloud-maxcompute-cli`。
|
|
28
|
+
|
|
29
|
+
## 快速开始
|
|
30
|
+
|
|
31
|
+
### 公共云(推荐)
|
|
32
|
+
|
|
33
|
+
```bash
|
|
34
|
+
# Alibaba Cloud CLI 需要 >= 3.3.3;旧版本先运行 aliyun upgrade
|
|
35
|
+
aliyun version
|
|
36
|
+
|
|
37
|
+
# OAuth 是交互式登录的首选方式,不需要把长期 AK/SK 放进命令行
|
|
38
|
+
aliyun maxc auth login --oauth --json
|
|
39
|
+
|
|
40
|
+
# 本地检查与在线就绪检查是两个独立步骤
|
|
41
|
+
aliyun maxc agent context --json
|
|
42
|
+
aliyun maxc agent manifest --json
|
|
43
|
+
aliyun maxc agent doctor --online --json
|
|
44
|
+
|
|
45
|
+
# 发现并查询数据
|
|
46
|
+
aliyun maxc meta search "销售" --json
|
|
47
|
+
aliyun maxc meta describe schema.table --json
|
|
48
|
+
aliyun maxc query cost "SELECT * FROM schema.table WHERE ds='20260415'" --json
|
|
49
|
+
aliyun maxc query "SELECT * FROM schema.table WHERE ds='20260415'" --json
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
如果 Alibaba Cloud CLI 扩展不可用,或明确需要 PyPI 版本,可使用独立入口。
|
|
53
|
+
独立入口要求 Python 3.9 或更高版本:
|
|
54
|
+
|
|
55
|
+
```bash
|
|
56
|
+
python3 -m pip install --upgrade maxc-cli
|
|
57
|
+
maxc auth login --oauth --json
|
|
58
|
+
maxc agent doctor --online --json
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
已有 Alibaba Cloud CLI OAuth profile、环境变量、STS 或外部凭证进程时,
|
|
62
|
+
先运行 `auth whoami --json` 验证当前身份,不要无故覆盖现有认证。
|
|
63
|
+
|
|
64
|
+
## 命令一览
|
|
65
|
+
|
|
66
|
+
| 家族 | 命令 | 说明 |
|
|
67
|
+
|------|------|------|
|
|
68
|
+
| **query** | `query [run]`, `query cost`, `query explain` | SQL 执行、成本估算、执行计划 |
|
|
69
|
+
| **job** | `submit`, `status`, `wait`, `result`, `cancel`, `diagnose`, `list` | 异步任务全生命周期 |
|
|
70
|
+
| **meta** | `list-tables`, `describe`, `search`, `search-columns`, `partitions`, `latest-partition`, `freshness`, `list-projects`, `list-schemas`, `semantic set/get/clear/list-missing` | 元数据发现与语义管理 |
|
|
71
|
+
| **data** | `sample`, `profile`, `upload`, `download` | 数据采样、画像与 CSV/TSV 传输 |
|
|
72
|
+
| **auth** | `login`, `login-external`, `logout`, `whoami`, `can-i` | 认证与权限 |
|
|
73
|
+
| **session** | `set`, `show`, `unset` | 项目/Schema 切换 |
|
|
74
|
+
| **cache** | `build`, `build-status`, `status`, `clear` | 元数据缓存管理 |
|
|
75
|
+
| **agent** | `context`, `doctor`, `manifest`, `skill install/update/uninstall/list/diff/path` | Agent 就绪检查、命令发现与 Skill 管理 |
|
|
76
|
+
|
|
77
|
+
普通命令支持 `--json` 输出 Envelope v2.0 结构化响应。对 Agent 而言应优先
|
|
78
|
+
使用 `--json`;CSV/NDJSON 行流和 `job wait --stream` 生命周期流是明确例外,
|
|
79
|
+
不会为每条记录重复封装 Envelope。
|
|
80
|
+
|
|
81
|
+
## Agent 集成
|
|
82
|
+
|
|
83
|
+
### 方式 1:公共 Skill(主路径)
|
|
84
|
+
|
|
85
|
+
安装名为 `alibabacloud-maxcompute-cli` 的公共 Skill。Skill 会先检查
|
|
86
|
+
`aliyun maxc`,仅在该入口不可用且用户选择独立发行版时才使用 PyPI 入口。
|
|
87
|
+
|
|
88
|
+
### 方式 2:从 CLI 注册
|
|
89
|
+
|
|
90
|
+
当前 CLI 包内含同一份 Skill 源,可以注册到 Agent 平台的标准目录:
|
|
91
|
+
|
|
92
|
+
```bash
|
|
93
|
+
# 公共云入口会把 Skill 内的命令渲染为 aliyun maxc
|
|
94
|
+
aliyun maxc agent skill install codex --invocation aliyun-maxc --json
|
|
95
|
+
|
|
96
|
+
# 独立入口
|
|
97
|
+
maxc agent skill install codex --invocation maxc --json
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
安装目录名统一为 `alibabacloud-maxcompute-cli`。支持的平台以
|
|
101
|
+
`agent skill install --help` 的实时输出为准。
|
|
102
|
+
后续执行 `agent skill update <platform>` 或 `agent skill update --all` 时,
|
|
103
|
+
未显式传 `--invocation` 会分别保留每个已安装 Skill 的原入口;只有显式参数才会覆盖。
|
|
104
|
+
|
|
105
|
+
### preflight 检查
|
|
106
|
+
|
|
107
|
+
Agent 启动时生成一次 32 位小写十六进制 session ID,并在整个会话中复用:
|
|
108
|
+
|
|
109
|
+
```bash
|
|
110
|
+
UA="AlibabaCloud-Agent-Skills/alibabacloud-maxcompute-cli/<session-id>"
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
每条 `aliyun maxc` 命令都追加 `--user-agent "$UA"`。然后依次运行:
|
|
114
|
+
|
|
115
|
+
```bash
|
|
116
|
+
aliyun maxc agent context --user-agent "$UA" --json # 仅检查本地版本、配置和能力;不访问网络
|
|
117
|
+
aliyun maxc agent manifest --user-agent "$UA" --json # 从实时 parser 生成命令、参数和副作用清单
|
|
118
|
+
aliyun maxc agent doctor --online --user-agent "$UA" --json # 验证身份与后端可达性
|
|
119
|
+
aliyun maxc agent skill --user-agent "$UA" --json # Skill 路径、名称与 min_cli_version
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
只有 `agent doctor --online` 能证明远端已就绪;不要把 `agent context` 中的
|
|
123
|
+
`auth_status=configured` 解读成已经通过在线认证。
|
|
124
|
+
|
|
125
|
+
## Envelope v2.0
|
|
126
|
+
|
|
127
|
+
普通 `--json` 响应遵循统一结构:
|
|
128
|
+
|
|
129
|
+
```json
|
|
130
|
+
{
|
|
131
|
+
"version": "2.0",
|
|
132
|
+
"command": "meta describe",
|
|
133
|
+
"status": "success | pending | failure",
|
|
134
|
+
"data": { ... },
|
|
135
|
+
"metadata": { ... },
|
|
136
|
+
"error": null | { "code": "...", "message": "...", "recovery_steps": [...] },
|
|
137
|
+
"agent_hints": {
|
|
138
|
+
"actions": [
|
|
139
|
+
{
|
|
140
|
+
"id": "meta.search",
|
|
141
|
+
"title": "Search tables",
|
|
142
|
+
"command": "maxc meta search <keyword> --json",
|
|
143
|
+
"executable": false,
|
|
144
|
+
"placeholders": {"keyword": "search keyword"},
|
|
145
|
+
"args_schema": {},
|
|
146
|
+
"effect": "read",
|
|
147
|
+
"confirmation_required": false,
|
|
148
|
+
"agent_allowed": true
|
|
149
|
+
}
|
|
150
|
+
],
|
|
151
|
+
"action_ids": ["meta.search"],
|
|
152
|
+
"insights": [...],
|
|
153
|
+
"warnings": [...]
|
|
154
|
+
}
|
|
155
|
+
}
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
- `agent_hints.actions[]`:权威的结构化 `SuggestedAction` 对象数组
|
|
159
|
+
- `action_ids`:全部结构化动作的稳定 dot-notation ID
|
|
160
|
+
- `next_actions`:兼容字段,只包含 `executable=true`、`agent_allowed=true`
|
|
161
|
+
且无需确认的命令;模板或有副作用动作可能只出现在 `actions[]`
|
|
162
|
+
- `error.recovery_steps`:错误码对应的恢复步骤
|
|
163
|
+
|
|
164
|
+
### 输出格式
|
|
165
|
+
|
|
166
|
+
对 Agent,统一使用 `--json`:
|
|
167
|
+
|
|
168
|
+
```bash
|
|
169
|
+
maxc meta describe my_table --json
|
|
170
|
+
```
|
|
171
|
+
|
|
172
|
+
### safety 块
|
|
173
|
+
|
|
174
|
+
`query` 和 `job` 命令的 `data` 中包含 `safety` 字段,描述安全策略决策:
|
|
175
|
+
|
|
176
|
+
```json
|
|
177
|
+
"safety": {
|
|
178
|
+
"mode": "read_only",
|
|
179
|
+
"force": false,
|
|
180
|
+
"allowed_operations": ["SELECT"],
|
|
181
|
+
"effective_hints": {"odps.sql.read.only": "true"},
|
|
182
|
+
"policy_decision": "allowed"
|
|
183
|
+
}
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
详见 [`docs/ENVELOPE_SPEC.md`](docs/ENVELOPE_SPEC.md)。
|
|
187
|
+
|
|
188
|
+
## 项目结构
|
|
189
|
+
|
|
190
|
+
```
|
|
191
|
+
src/maxc_cli/
|
|
192
|
+
├── cli.py # argparse 命令注册
|
|
193
|
+
├── app.py # MaxCApp 业务逻辑
|
|
194
|
+
├── models.py # Envelope / AgentHints / QueryResult
|
|
195
|
+
├── exceptions.py # ErrorPayload + 类型化异常 + recovery_steps
|
|
196
|
+
├── config.py # YAML 配置加载
|
|
197
|
+
├── cache.py # LocalCache (SQLite)
|
|
198
|
+
├── store.py # JobStore(加锁、原子写入的本地 JSON)
|
|
199
|
+
├── output.py # JSON / Markdown / brief / 人类可读渲染
|
|
200
|
+
├── auth_providers.py # OAuth / AK-SK / STS / 外部进程 / 环境变量认证
|
|
201
|
+
├── backend/ # ODPS 后端(query / job / meta / catalog / data / auth mixin)
|
|
202
|
+
└── skills/ # alibabacloud-maxcompute-cli 的包内源文件与 references
|
|
203
|
+
```
|
|
204
|
+
|
|
205
|
+
## 文档
|
|
206
|
+
|
|
207
|
+
| 文档 | 内容 |
|
|
208
|
+
|------|------|
|
|
209
|
+
| [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) | 三层架构、核心数据流、缓存/认证架构 |
|
|
210
|
+
| [`docs/ENVELOPE_SPEC.md`](docs/ENVELOPE_SPEC.md) | Envelope v2.0 规范、pagination、error codes |
|
|
211
|
+
| [`docs/ODPS_BACKEND.md`](docs/ODPS_BACKEND.md) | ODPS 后端 API 映射、限制与回退行为 |
|
|
212
|
+
| [`docs/design.md`](docs/design.md) | 产品定位与命令体系 |
|
|
213
|
+
| [`docs/implementation.md`](docs/implementation.md) | 当前代码的真实行为和输出契约 |
|
|
214
|
+
| [`docs/roadmap.md`](docs/roadmap.md) | 路线图 |
|
|
215
|
+
|
|
216
|
+
运行时命令和参数以当前版本的 `agent manifest` 与 `--help` 输出为准。
|
|
217
|
+
`CHANGELOG.md` 和 `docs/superpowers/` 用于追溯历史版本与设计过程,不作为
|
|
218
|
+
当前运行时契约。
|
|
219
|
+
|
|
220
|
+
## 限制
|
|
221
|
+
|
|
222
|
+
- **查询安全**:公共 Agent Skill 的 SQL 契约只支持 `SELECT`,不通过
|
|
223
|
+
`query` 或 `job submit` 执行 DDL/DML。`data upload`、
|
|
224
|
+
`data download --overwrite` 和 `job cancel` 是独立的有副作用操作,仍需
|
|
225
|
+
与影响相匹配的明确授权。
|
|
226
|
+
- **OAuth 优先**:公共云交互式登录优先 OAuth。只有运行环境明确要求时才用
|
|
227
|
+
AK/SK、STS、环境变量或外部凭证进程。直接 AK/SK 会写入
|
|
228
|
+
`~/.maxc/config.yaml`(文件权限 0600)。OAuth 需要账号/组织已分配官方
|
|
229
|
+
`official-cli` OAuth 应用。
|
|
230
|
+
省略 `--project` 时通过 Catalog API 弹交互式 project picker(需 TTY,仅支持中国区 project)。
|
|
231
|
+
CI 用 `--no-picker`;想重选已保存的 project 用 `--reselect`;非中国区用 `--catalog-endpoint` 覆盖。
|
|
232
|
+
OAuth 回调始终监听 CLI 所在主机的 `127.0.0.1`;`--no-browser` 只是不自动
|
|
233
|
+
打开浏览器,并不是 device-code/headless flow。SSH 场景需配置端口转发,或
|
|
234
|
+
在 CLI 同机浏览器完成授权。
|
|
235
|
+
- **远程查询重试**:可恢复远程执行拒绝 `--retry-on`、`--max-retries` 和非默认
|
|
236
|
+
`--retry-backoff`。保留首次返回的 `metadata.job_id`,先检查原任务,再人工
|
|
237
|
+
判断是否重新提交。
|
|
238
|
+
- **上传分区**:普通 `data upload` 不创建缺失分区。只有显式
|
|
239
|
+
`--create-partition` 才允许创建 `--partition` 指定的分区;这是独立元数据
|
|
240
|
+
副作用,后续上传失败时可能留下空分区。
|
|
241
|
+
- **外部凭证进程**:只能来自可信用户级配置或用户显式选择的 `--config`;自动
|
|
242
|
+
发现的 workspace 配置不得定义 `auth`。命令按 executable + argv 运行,不经
|
|
243
|
+
shell,不支持管道、重定向或命令替换。
|
|
244
|
+
- **安全下载**:`data download` 默认拒绝覆盖已有本地文件;只有显式传入
|
|
245
|
+
`--overwrite` 才会原子替换目标文件。
|
|
246
|
+
- **list-tables 分页**:CLI 侧 offset token,非服务端游标
|
|
247
|
+
|
|
248
|
+
## 开发
|
|
249
|
+
|
|
250
|
+
```bash
|
|
251
|
+
pip install -e .
|
|
252
|
+
pytest tests/ -m unit
|
|
253
|
+
```
|
maxc_cli-0.5.0/README.md
ADDED
|
@@ -0,0 +1,231 @@
|
|
|
1
|
+
# maxc-cli
|
|
2
|
+
|
|
3
|
+
使用 Alibaba Cloud CLI 控制 MaxCompute 云产品。`aliyun maxc` 提供
|
|
4
|
+
MaxCompute 元数据、SQL、作业、权限和数据传输等数据面操作。公共云 Skill
|
|
5
|
+
名称为 `alibabacloud-maxcompute-cli`。
|
|
6
|
+
|
|
7
|
+
## 快速开始
|
|
8
|
+
|
|
9
|
+
### 公共云(推荐)
|
|
10
|
+
|
|
11
|
+
```bash
|
|
12
|
+
# Alibaba Cloud CLI 需要 >= 3.3.3;旧版本先运行 aliyun upgrade
|
|
13
|
+
aliyun version
|
|
14
|
+
|
|
15
|
+
# OAuth 是交互式登录的首选方式,不需要把长期 AK/SK 放进命令行
|
|
16
|
+
aliyun maxc auth login --oauth --json
|
|
17
|
+
|
|
18
|
+
# 本地检查与在线就绪检查是两个独立步骤
|
|
19
|
+
aliyun maxc agent context --json
|
|
20
|
+
aliyun maxc agent manifest --json
|
|
21
|
+
aliyun maxc agent doctor --online --json
|
|
22
|
+
|
|
23
|
+
# 发现并查询数据
|
|
24
|
+
aliyun maxc meta search "销售" --json
|
|
25
|
+
aliyun maxc meta describe schema.table --json
|
|
26
|
+
aliyun maxc query cost "SELECT * FROM schema.table WHERE ds='20260415'" --json
|
|
27
|
+
aliyun maxc query "SELECT * FROM schema.table WHERE ds='20260415'" --json
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
如果 Alibaba Cloud CLI 扩展不可用,或明确需要 PyPI 版本,可使用独立入口。
|
|
31
|
+
独立入口要求 Python 3.9 或更高版本:
|
|
32
|
+
|
|
33
|
+
```bash
|
|
34
|
+
python3 -m pip install --upgrade maxc-cli
|
|
35
|
+
maxc auth login --oauth --json
|
|
36
|
+
maxc agent doctor --online --json
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
已有 Alibaba Cloud CLI OAuth profile、环境变量、STS 或外部凭证进程时,
|
|
40
|
+
先运行 `auth whoami --json` 验证当前身份,不要无故覆盖现有认证。
|
|
41
|
+
|
|
42
|
+
## 命令一览
|
|
43
|
+
|
|
44
|
+
| 家族 | 命令 | 说明 |
|
|
45
|
+
|------|------|------|
|
|
46
|
+
| **query** | `query [run]`, `query cost`, `query explain` | SQL 执行、成本估算、执行计划 |
|
|
47
|
+
| **job** | `submit`, `status`, `wait`, `result`, `cancel`, `diagnose`, `list` | 异步任务全生命周期 |
|
|
48
|
+
| **meta** | `list-tables`, `describe`, `search`, `search-columns`, `partitions`, `latest-partition`, `freshness`, `list-projects`, `list-schemas`, `semantic set/get/clear/list-missing` | 元数据发现与语义管理 |
|
|
49
|
+
| **data** | `sample`, `profile`, `upload`, `download` | 数据采样、画像与 CSV/TSV 传输 |
|
|
50
|
+
| **auth** | `login`, `login-external`, `logout`, `whoami`, `can-i` | 认证与权限 |
|
|
51
|
+
| **session** | `set`, `show`, `unset` | 项目/Schema 切换 |
|
|
52
|
+
| **cache** | `build`, `build-status`, `status`, `clear` | 元数据缓存管理 |
|
|
53
|
+
| **agent** | `context`, `doctor`, `manifest`, `skill install/update/uninstall/list/diff/path` | Agent 就绪检查、命令发现与 Skill 管理 |
|
|
54
|
+
|
|
55
|
+
普通命令支持 `--json` 输出 Envelope v2.0 结构化响应。对 Agent 而言应优先
|
|
56
|
+
使用 `--json`;CSV/NDJSON 行流和 `job wait --stream` 生命周期流是明确例外,
|
|
57
|
+
不会为每条记录重复封装 Envelope。
|
|
58
|
+
|
|
59
|
+
## Agent 集成
|
|
60
|
+
|
|
61
|
+
### 方式 1:公共 Skill(主路径)
|
|
62
|
+
|
|
63
|
+
安装名为 `alibabacloud-maxcompute-cli` 的公共 Skill。Skill 会先检查
|
|
64
|
+
`aliyun maxc`,仅在该入口不可用且用户选择独立发行版时才使用 PyPI 入口。
|
|
65
|
+
|
|
66
|
+
### 方式 2:从 CLI 注册
|
|
67
|
+
|
|
68
|
+
当前 CLI 包内含同一份 Skill 源,可以注册到 Agent 平台的标准目录:
|
|
69
|
+
|
|
70
|
+
```bash
|
|
71
|
+
# 公共云入口会把 Skill 内的命令渲染为 aliyun maxc
|
|
72
|
+
aliyun maxc agent skill install codex --invocation aliyun-maxc --json
|
|
73
|
+
|
|
74
|
+
# 独立入口
|
|
75
|
+
maxc agent skill install codex --invocation maxc --json
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
安装目录名统一为 `alibabacloud-maxcompute-cli`。支持的平台以
|
|
79
|
+
`agent skill install --help` 的实时输出为准。
|
|
80
|
+
后续执行 `agent skill update <platform>` 或 `agent skill update --all` 时,
|
|
81
|
+
未显式传 `--invocation` 会分别保留每个已安装 Skill 的原入口;只有显式参数才会覆盖。
|
|
82
|
+
|
|
83
|
+
### preflight 检查
|
|
84
|
+
|
|
85
|
+
Agent 启动时生成一次 32 位小写十六进制 session ID,并在整个会话中复用:
|
|
86
|
+
|
|
87
|
+
```bash
|
|
88
|
+
UA="AlibabaCloud-Agent-Skills/alibabacloud-maxcompute-cli/<session-id>"
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
每条 `aliyun maxc` 命令都追加 `--user-agent "$UA"`。然后依次运行:
|
|
92
|
+
|
|
93
|
+
```bash
|
|
94
|
+
aliyun maxc agent context --user-agent "$UA" --json # 仅检查本地版本、配置和能力;不访问网络
|
|
95
|
+
aliyun maxc agent manifest --user-agent "$UA" --json # 从实时 parser 生成命令、参数和副作用清单
|
|
96
|
+
aliyun maxc agent doctor --online --user-agent "$UA" --json # 验证身份与后端可达性
|
|
97
|
+
aliyun maxc agent skill --user-agent "$UA" --json # Skill 路径、名称与 min_cli_version
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
只有 `agent doctor --online` 能证明远端已就绪;不要把 `agent context` 中的
|
|
101
|
+
`auth_status=configured` 解读成已经通过在线认证。
|
|
102
|
+
|
|
103
|
+
## Envelope v2.0
|
|
104
|
+
|
|
105
|
+
普通 `--json` 响应遵循统一结构:
|
|
106
|
+
|
|
107
|
+
```json
|
|
108
|
+
{
|
|
109
|
+
"version": "2.0",
|
|
110
|
+
"command": "meta describe",
|
|
111
|
+
"status": "success | pending | failure",
|
|
112
|
+
"data": { ... },
|
|
113
|
+
"metadata": { ... },
|
|
114
|
+
"error": null | { "code": "...", "message": "...", "recovery_steps": [...] },
|
|
115
|
+
"agent_hints": {
|
|
116
|
+
"actions": [
|
|
117
|
+
{
|
|
118
|
+
"id": "meta.search",
|
|
119
|
+
"title": "Search tables",
|
|
120
|
+
"command": "maxc meta search <keyword> --json",
|
|
121
|
+
"executable": false,
|
|
122
|
+
"placeholders": {"keyword": "search keyword"},
|
|
123
|
+
"args_schema": {},
|
|
124
|
+
"effect": "read",
|
|
125
|
+
"confirmation_required": false,
|
|
126
|
+
"agent_allowed": true
|
|
127
|
+
}
|
|
128
|
+
],
|
|
129
|
+
"action_ids": ["meta.search"],
|
|
130
|
+
"insights": [...],
|
|
131
|
+
"warnings": [...]
|
|
132
|
+
}
|
|
133
|
+
}
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
- `agent_hints.actions[]`:权威的结构化 `SuggestedAction` 对象数组
|
|
137
|
+
- `action_ids`:全部结构化动作的稳定 dot-notation ID
|
|
138
|
+
- `next_actions`:兼容字段,只包含 `executable=true`、`agent_allowed=true`
|
|
139
|
+
且无需确认的命令;模板或有副作用动作可能只出现在 `actions[]`
|
|
140
|
+
- `error.recovery_steps`:错误码对应的恢复步骤
|
|
141
|
+
|
|
142
|
+
### 输出格式
|
|
143
|
+
|
|
144
|
+
对 Agent,统一使用 `--json`:
|
|
145
|
+
|
|
146
|
+
```bash
|
|
147
|
+
maxc meta describe my_table --json
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
### safety 块
|
|
151
|
+
|
|
152
|
+
`query` 和 `job` 命令的 `data` 中包含 `safety` 字段,描述安全策略决策:
|
|
153
|
+
|
|
154
|
+
```json
|
|
155
|
+
"safety": {
|
|
156
|
+
"mode": "read_only",
|
|
157
|
+
"force": false,
|
|
158
|
+
"allowed_operations": ["SELECT"],
|
|
159
|
+
"effective_hints": {"odps.sql.read.only": "true"},
|
|
160
|
+
"policy_decision": "allowed"
|
|
161
|
+
}
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
详见 [`docs/ENVELOPE_SPEC.md`](docs/ENVELOPE_SPEC.md)。
|
|
165
|
+
|
|
166
|
+
## 项目结构
|
|
167
|
+
|
|
168
|
+
```
|
|
169
|
+
src/maxc_cli/
|
|
170
|
+
├── cli.py # argparse 命令注册
|
|
171
|
+
├── app.py # MaxCApp 业务逻辑
|
|
172
|
+
├── models.py # Envelope / AgentHints / QueryResult
|
|
173
|
+
├── exceptions.py # ErrorPayload + 类型化异常 + recovery_steps
|
|
174
|
+
├── config.py # YAML 配置加载
|
|
175
|
+
├── cache.py # LocalCache (SQLite)
|
|
176
|
+
├── store.py # JobStore(加锁、原子写入的本地 JSON)
|
|
177
|
+
├── output.py # JSON / Markdown / brief / 人类可读渲染
|
|
178
|
+
├── auth_providers.py # OAuth / AK-SK / STS / 外部进程 / 环境变量认证
|
|
179
|
+
├── backend/ # ODPS 后端(query / job / meta / catalog / data / auth mixin)
|
|
180
|
+
└── skills/ # alibabacloud-maxcompute-cli 的包内源文件与 references
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
## 文档
|
|
184
|
+
|
|
185
|
+
| 文档 | 内容 |
|
|
186
|
+
|------|------|
|
|
187
|
+
| [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) | 三层架构、核心数据流、缓存/认证架构 |
|
|
188
|
+
| [`docs/ENVELOPE_SPEC.md`](docs/ENVELOPE_SPEC.md) | Envelope v2.0 规范、pagination、error codes |
|
|
189
|
+
| [`docs/ODPS_BACKEND.md`](docs/ODPS_BACKEND.md) | ODPS 后端 API 映射、限制与回退行为 |
|
|
190
|
+
| [`docs/design.md`](docs/design.md) | 产品定位与命令体系 |
|
|
191
|
+
| [`docs/implementation.md`](docs/implementation.md) | 当前代码的真实行为和输出契约 |
|
|
192
|
+
| [`docs/roadmap.md`](docs/roadmap.md) | 路线图 |
|
|
193
|
+
|
|
194
|
+
运行时命令和参数以当前版本的 `agent manifest` 与 `--help` 输出为准。
|
|
195
|
+
`CHANGELOG.md` 和 `docs/superpowers/` 用于追溯历史版本与设计过程,不作为
|
|
196
|
+
当前运行时契约。
|
|
197
|
+
|
|
198
|
+
## 限制
|
|
199
|
+
|
|
200
|
+
- **查询安全**:公共 Agent Skill 的 SQL 契约只支持 `SELECT`,不通过
|
|
201
|
+
`query` 或 `job submit` 执行 DDL/DML。`data upload`、
|
|
202
|
+
`data download --overwrite` 和 `job cancel` 是独立的有副作用操作,仍需
|
|
203
|
+
与影响相匹配的明确授权。
|
|
204
|
+
- **OAuth 优先**:公共云交互式登录优先 OAuth。只有运行环境明确要求时才用
|
|
205
|
+
AK/SK、STS、环境变量或外部凭证进程。直接 AK/SK 会写入
|
|
206
|
+
`~/.maxc/config.yaml`(文件权限 0600)。OAuth 需要账号/组织已分配官方
|
|
207
|
+
`official-cli` OAuth 应用。
|
|
208
|
+
省略 `--project` 时通过 Catalog API 弹交互式 project picker(需 TTY,仅支持中国区 project)。
|
|
209
|
+
CI 用 `--no-picker`;想重选已保存的 project 用 `--reselect`;非中国区用 `--catalog-endpoint` 覆盖。
|
|
210
|
+
OAuth 回调始终监听 CLI 所在主机的 `127.0.0.1`;`--no-browser` 只是不自动
|
|
211
|
+
打开浏览器,并不是 device-code/headless flow。SSH 场景需配置端口转发,或
|
|
212
|
+
在 CLI 同机浏览器完成授权。
|
|
213
|
+
- **远程查询重试**:可恢复远程执行拒绝 `--retry-on`、`--max-retries` 和非默认
|
|
214
|
+
`--retry-backoff`。保留首次返回的 `metadata.job_id`,先检查原任务,再人工
|
|
215
|
+
判断是否重新提交。
|
|
216
|
+
- **上传分区**:普通 `data upload` 不创建缺失分区。只有显式
|
|
217
|
+
`--create-partition` 才允许创建 `--partition` 指定的分区;这是独立元数据
|
|
218
|
+
副作用,后续上传失败时可能留下空分区。
|
|
219
|
+
- **外部凭证进程**:只能来自可信用户级配置或用户显式选择的 `--config`;自动
|
|
220
|
+
发现的 workspace 配置不得定义 `auth`。命令按 executable + argv 运行,不经
|
|
221
|
+
shell,不支持管道、重定向或命令替换。
|
|
222
|
+
- **安全下载**:`data download` 默认拒绝覆盖已有本地文件;只有显式传入
|
|
223
|
+
`--overwrite` 才会原子替换目标文件。
|
|
224
|
+
- **list-tables 分页**:CLI 侧 offset token,非服务端游标
|
|
225
|
+
|
|
226
|
+
## 开发
|
|
227
|
+
|
|
228
|
+
```bash
|
|
229
|
+
pip install -e .
|
|
230
|
+
pytest tests/ -m unit
|
|
231
|
+
```
|
|
@@ -1,22 +1,26 @@
|
|
|
1
1
|
from pathlib import Path
|
|
2
|
+
from runpy import run_path
|
|
2
3
|
|
|
3
4
|
from setuptools import find_packages, setup
|
|
4
5
|
|
|
5
|
-
|
|
6
6
|
ROOT = Path(__file__).resolve().parent
|
|
7
7
|
README = ROOT / "README.md"
|
|
8
|
+
VERSION = run_path(str(ROOT / "src" / "maxc_cli" / "__init__.py"))["__version__"]
|
|
8
9
|
|
|
9
10
|
|
|
10
11
|
setup(
|
|
11
12
|
name="maxc-cli",
|
|
12
|
-
version=
|
|
13
|
+
version=VERSION,
|
|
13
14
|
description="Agent-native MaxCompute CLI for external coding agents",
|
|
14
15
|
long_description=README.read_text(encoding="utf-8"),
|
|
15
16
|
long_description_content_type="text/markdown",
|
|
16
17
|
python_requires=">=3.9",
|
|
17
18
|
package_dir={"": "src"},
|
|
18
19
|
packages=find_packages(where="src"),
|
|
19
|
-
|
|
20
|
+
# Skill files are runtime resources, not part of the public Python package
|
|
21
|
+
# API. Keep the install surface explicit so setuptools does not auto-discover
|
|
22
|
+
# the resource-only directories as namespace packages.
|
|
23
|
+
include_package_data=False,
|
|
20
24
|
package_data={
|
|
21
25
|
"maxc_cli": [
|
|
22
26
|
"skills/SKILL.md",
|