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.
Files changed (141) hide show
  1. {maxc_cli-0.4.7 → maxc_cli-0.5.0}/MANIFEST.in +0 -1
  2. maxc_cli-0.5.0/PKG-INFO +253 -0
  3. maxc_cli-0.5.0/README.md +231 -0
  4. {maxc_cli-0.4.7 → maxc_cli-0.5.0}/pyproject.toml +1 -1
  5. {maxc_cli-0.4.7 → maxc_cli-0.5.0}/scripts/regression_test.py +0 -1
  6. {maxc_cli-0.4.7 → maxc_cli-0.5.0}/setup.py +7 -3
  7. {maxc_cli-0.4.7 → maxc_cli-0.5.0}/src/maxc_cli/__init__.py +1 -1
  8. {maxc_cli-0.4.7 → maxc_cli-0.5.0}/src/maxc_cli/_samples.py +51 -38
  9. {maxc_cli-0.4.7 → maxc_cli-0.5.0}/src/maxc_cli/agent_platforms.py +8 -6
  10. {maxc_cli-0.4.7 → maxc_cli-0.5.0}/src/maxc_cli/app.py +3178 -580
  11. maxc_cli-0.5.0/src/maxc_cli/audit.py +111 -0
  12. maxc_cli-0.5.0/src/maxc_cli/auth_continuation.py +218 -0
  13. {maxc_cli-0.4.7 → maxc_cli-0.5.0}/src/maxc_cli/auth_providers.py +149 -11
  14. maxc_cli-0.5.0/src/maxc_cli/backend/auth.py +308 -0
  15. {maxc_cli-0.4.7 → maxc_cli-0.5.0}/src/maxc_cli/backend/catalog.py +9 -0
  16. maxc_cli-0.5.0/src/maxc_cli/backend/data.py +1122 -0
  17. maxc_cli-0.5.0/src/maxc_cli/backend/job.py +788 -0
  18. {maxc_cli-0.4.7 → maxc_cli-0.5.0}/src/maxc_cli/backend/meta.py +40 -3
  19. {maxc_cli-0.4.7 → maxc_cli-0.5.0}/src/maxc_cli/backend/odps.py +78 -56
  20. {maxc_cli-0.4.7 → maxc_cli-0.5.0}/src/maxc_cli/backend/query.py +164 -49
  21. maxc_cli-0.5.0/src/maxc_cli/cache.py +1546 -0
  22. {maxc_cli-0.4.7 → maxc_cli-0.5.0}/src/maxc_cli/catalog_bootstrap.py +9 -1
  23. maxc_cli-0.5.0/src/maxc_cli/cli.py +4720 -0
  24. {maxc_cli-0.4.7 → maxc_cli-0.5.0}/src/maxc_cli/config.py +361 -52
  25. {maxc_cli-0.4.7 → maxc_cli-0.5.0}/src/maxc_cli/exceptions.py +85 -4
  26. {maxc_cli-0.4.7 → maxc_cli-0.5.0}/src/maxc_cli/helpers.py +60 -12
  27. maxc_cli-0.5.0/src/maxc_cli/job_ids.py +48 -0
  28. {maxc_cli-0.4.7 → maxc_cli-0.5.0}/src/maxc_cli/models.py +338 -44
  29. maxc_cli-0.5.0/src/maxc_cli/oauth.py +648 -0
  30. maxc_cli-0.5.0/src/maxc_cli/odps_runtime.py +37 -0
  31. {maxc_cli-0.4.7 → maxc_cli-0.5.0}/src/maxc_cli/output.py +113 -30
  32. maxc_cli-0.5.0/src/maxc_cli/skills/SKILL.md +290 -0
  33. maxc_cli-0.5.0/src/maxc_cli/skills/agents/openai.yaml +4 -0
  34. maxc_cli-0.5.0/src/maxc_cli/skills/references/bootstrap-auth.md +137 -0
  35. maxc_cli-0.5.0/src/maxc_cli/skills/references/bootstrap-flow.md +68 -0
  36. {maxc_cli-0.4.7 → maxc_cli-0.5.0}/src/maxc_cli/skills/references/command-patterns.md +107 -17
  37. {maxc_cli-0.4.7 → maxc_cli-0.5.0}/src/maxc_cli/skills/references/json-output-format.md +26 -14
  38. {maxc_cli-0.4.7 → maxc_cli-0.5.0}/src/maxc_cli/skills/references/maxcompute-select-guide.md +1 -1
  39. {maxc_cli-0.4.7 → maxc_cli-0.5.0}/src/maxc_cli/skills/references/maxcompute-sql-notes.md +11 -3
  40. {maxc_cli-0.4.7 → maxc_cli-0.5.0}/src/maxc_cli/skills/references/red-lines.md +19 -19
  41. maxc_cli-0.5.0/src/maxc_cli/skills/references/setup-install.md +79 -0
  42. {maxc_cli-0.4.7 → maxc_cli-0.5.0}/src/maxc_cli/skills/references/sql-common-errors.md +11 -11
  43. maxc_cli-0.5.0/src/maxc_cli/state_permissions.py +403 -0
  44. maxc_cli-0.5.0/src/maxc_cli/store.py +252 -0
  45. maxc_cli-0.5.0/src/maxc_cli/utils.py +795 -0
  46. maxc_cli-0.5.0/src/maxc_cli.egg-info/PKG-INFO +253 -0
  47. {maxc_cli-0.4.7 → maxc_cli-0.5.0}/src/maxc_cli.egg-info/SOURCES.txt +24 -1
  48. maxc_cli-0.5.0/tests/test_agent_hints_and_cli.py +750 -0
  49. {maxc_cli-0.4.7 → maxc_cli-0.5.0}/tests/test_agent_platforms.py +12 -15
  50. {maxc_cli-0.4.7 → maxc_cli-0.5.0}/tests/test_agent_skill_commands.py +132 -0
  51. {maxc_cli-0.4.7 → maxc_cli-0.5.0}/tests/test_agent_skill_commands_context.py +222 -44
  52. maxc_cli-0.5.0/tests/test_ai_native_contract_regressions.py +773 -0
  53. maxc_cli-0.5.0/tests/test_auth_logout.py +184 -0
  54. maxc_cli-0.5.0/tests/test_backend_auth.py +149 -0
  55. maxc_cli-0.5.0/tests/test_backend_data.py +60 -0
  56. maxc_cli-0.5.0/tests/test_backend_data_serialization.py +783 -0
  57. {maxc_cli-0.4.7 → maxc_cli-0.5.0}/tests/test_backend_meta.py +40 -0
  58. maxc_cli-0.5.0/tests/test_build_release_archive_compat.py +96 -0
  59. {maxc_cli-0.4.7 → maxc_cli-0.5.0}/tests/test_build_release_script.py +8 -1
  60. maxc_cli-0.5.0/tests/test_cache.py +796 -0
  61. {maxc_cli-0.4.7 → maxc_cli-0.5.0}/tests/test_cli_arg_validation.py +22 -0
  62. maxc_cli-0.5.0/tests/test_cli_mock.py +5750 -0
  63. maxc_cli-0.5.0/tests/test_config_atomic_write.py +110 -0
  64. {maxc_cli-0.4.7 → maxc_cli-0.5.0}/tests/test_error_translation.py +10 -0
  65. {maxc_cli-0.4.7 → maxc_cli-0.5.0}/tests/test_exit_codes.py +26 -0
  66. {maxc_cli-0.4.7 → maxc_cli-0.5.0}/tests/test_external_auth.py +234 -5
  67. {maxc_cli-0.4.7 → maxc_cli-0.5.0}/tests/test_flag_hoist.py +22 -6
  68. {maxc_cli-0.4.7 → maxc_cli-0.5.0}/tests/test_help_format.py +2 -0
  69. {maxc_cli-0.4.7 → maxc_cli-0.5.0}/tests/test_help_version_e2e.py +49 -17
  70. maxc_cli-0.5.0/tests/test_installer_contracts.py +218 -0
  71. {maxc_cli-0.4.7 → maxc_cli-0.5.0}/tests/test_integration_real.py +99 -37
  72. {maxc_cli-0.4.7 → maxc_cli-0.5.0}/tests/test_job_improvements.py +64 -7
  73. maxc_cli-0.5.0/tests/test_job_store_durability.py +194 -0
  74. maxc_cli-0.5.0/tests/test_manifest_runtime_contract.py +473 -0
  75. maxc_cli-0.5.0/tests/test_meta_schema_and_partition_cols.py +565 -0
  76. maxc_cli-0.5.0/tests/test_oauth.py +873 -0
  77. maxc_cli-0.5.0/tests/test_odps_runtime.py +66 -0
  78. maxc_cli-0.5.0/tests/test_output_action_safety.py +203 -0
  79. maxc_cli-0.5.0/tests/test_output_format_contract.py +847 -0
  80. maxc_cli-0.5.0/tests/test_packaging_metadata.py +68 -0
  81. {maxc_cli-0.4.7 → maxc_cli-0.5.0}/tests/test_phase1_improvements.py +181 -4
  82. {maxc_cli-0.4.7 → maxc_cli-0.5.0}/tests/test_pyinstaller_bundle.py +16 -0
  83. maxc_cli-0.5.0/tests/test_python39_compat.py +98 -0
  84. {maxc_cli-0.4.7 → maxc_cli-0.5.0}/tests/test_query_auto_promote.py +182 -4
  85. maxc_cli-0.5.0/tests/test_query_result_csv_fallback.py +487 -0
  86. maxc_cli-0.5.0/tests/test_semantic_scope.py +323 -0
  87. {maxc_cli-0.4.7 → maxc_cli-0.5.0}/tests/test_setting_parser.py +159 -3
  88. {maxc_cli-0.4.7 → maxc_cli-0.5.0}/tests/test_skill_renderer.py +1 -1
  89. maxc_cli-0.5.0/tests/test_startup_imports.py +115 -0
  90. maxc_cli-0.5.0/tests/test_state_permissions.py +456 -0
  91. maxc_cli-0.5.0/tests/test_state_portability.py +95 -0
  92. maxc_cli-0.4.7/PKG-INFO +0 -195
  93. maxc_cli-0.4.7/README.md +0 -173
  94. maxc_cli-0.4.7/src/maxc_cli/audit.py +0 -18
  95. maxc_cli-0.4.7/src/maxc_cli/backend/auth.py +0 -164
  96. maxc_cli-0.4.7/src/maxc_cli/backend/data.py +0 -615
  97. maxc_cli-0.4.7/src/maxc_cli/backend/job.py +0 -411
  98. maxc_cli-0.4.7/src/maxc_cli/cache.py +0 -717
  99. maxc_cli-0.4.7/src/maxc_cli/cli.py +0 -2154
  100. maxc_cli-0.4.7/src/maxc_cli/skills/SKILL.md +0 -269
  101. maxc_cli-0.4.7/src/maxc_cli/skills/agents/openai.yaml +0 -4
  102. maxc_cli-0.4.7/src/maxc_cli/skills/references/bootstrap-auth.md +0 -299
  103. maxc_cli-0.4.7/src/maxc_cli/skills/references/bootstrap-flow.md +0 -97
  104. maxc_cli-0.4.7/src/maxc_cli/skills/references/setup-install.md +0 -108
  105. maxc_cli-0.4.7/src/maxc_cli/store.py +0 -123
  106. maxc_cli-0.4.7/src/maxc_cli/utils.py +0 -165
  107. maxc_cli-0.4.7/src/maxc_cli.egg-info/PKG-INFO +0 -195
  108. maxc_cli-0.4.7/tests/test_agent_hints_and_cli.py +0 -342
  109. maxc_cli-0.4.7/tests/test_backend_data.py +0 -29
  110. maxc_cli-0.4.7/tests/test_backend_data_serialization.py +0 -247
  111. maxc_cli-0.4.7/tests/test_cache.py +0 -121
  112. maxc_cli-0.4.7/tests/test_cli_mock.py +0 -2585
  113. maxc_cli-0.4.7/tests/test_meta_schema_and_partition_cols.py +0 -232
  114. maxc_cli-0.4.7/tests/test_query_result_csv_fallback.py +0 -235
  115. {maxc_cli-0.4.7 → maxc_cli-0.5.0}/scripts/pyinstaller_entry.py +0 -0
  116. {maxc_cli-0.4.7 → maxc_cli-0.5.0}/setup.cfg +0 -0
  117. {maxc_cli-0.4.7 → maxc_cli-0.5.0}/src/maxc_cli/__main__.py +0 -0
  118. {maxc_cli-0.4.7 → maxc_cli-0.5.0}/src/maxc_cli/backend/__init__.py +0 -0
  119. {maxc_cli-0.4.7 → maxc_cli-0.5.0}/src/maxc_cli/help_format.py +0 -0
  120. {maxc_cli-0.4.7 → maxc_cli-0.5.0}/src/maxc_cli/masking.py +0 -0
  121. {maxc_cli-0.4.7 → maxc_cli-0.5.0}/src/maxc_cli/setting_parser.py +0 -0
  122. {maxc_cli-0.4.7 → maxc_cli-0.5.0}/src/maxc_cli/skills/references/partition-guide.md +0 -0
  123. {maxc_cli-0.4.7 → maxc_cli-0.5.0}/src/maxc_cli/skills/references/sql-query-patterns.md +0 -0
  124. {maxc_cli-0.4.7 → maxc_cli-0.5.0}/src/maxc_cli/skills/references/text2sql-principles.md +0 -0
  125. {maxc_cli-0.4.7 → maxc_cli-0.5.0}/src/maxc_cli.egg-info/dependency_links.txt +0 -0
  126. {maxc_cli-0.4.7 → maxc_cli-0.5.0}/src/maxc_cli.egg-info/entry_points.txt +0 -0
  127. {maxc_cli-0.4.7 → maxc_cli-0.5.0}/src/maxc_cli.egg-info/requires.txt +0 -0
  128. {maxc_cli-0.4.7 → maxc_cli-0.5.0}/src/maxc_cli.egg-info/top_level.txt +0 -0
  129. {maxc_cli-0.4.7 → maxc_cli-0.5.0}/tests/test_catalog.py +0 -0
  130. {maxc_cli-0.4.7 → maxc_cli-0.5.0}/tests/test_catalog_bootstrap.py +0 -0
  131. {maxc_cli-0.4.7 → maxc_cli-0.5.0}/tests/test_cli_query_parse_and_sanitize.py +0 -0
  132. {maxc_cli-0.4.7 → maxc_cli-0.5.0}/tests/test_compat.py +0 -0
  133. {maxc_cli-0.4.7 → maxc_cli-0.5.0}/tests/test_e2e_smoke.py +0 -0
  134. {maxc_cli-0.4.7 → maxc_cli-0.5.0}/tests/test_envelope_shape.py +0 -0
  135. {maxc_cli-0.4.7 → maxc_cli-0.5.0}/tests/test_error_self_correction.py +0 -0
  136. {maxc_cli-0.4.7 → maxc_cli-0.5.0}/tests/test_helpers.py +0 -0
  137. {maxc_cli-0.4.7 → maxc_cli-0.5.0}/tests/test_helpers_csv.py +0 -0
  138. {maxc_cli-0.4.7 → maxc_cli-0.5.0}/tests/test_integration.py +0 -0
  139. {maxc_cli-0.4.7 → maxc_cli-0.5.0}/tests/test_masking.py +0 -0
  140. {maxc_cli-0.4.7 → maxc_cli-0.5.0}/tests/test_skill_cli_consistency.py +0 -0
  141. {maxc_cli-0.4.7 → maxc_cli-0.5.0}/tests/test_skill_eval.py +0 -0
@@ -1,3 +1,2 @@
1
1
  recursive-include src/maxc_cli/skills *
2
- recursive-include skills/use-maxc-cli *
3
2
  recursive-include scripts *.py
@@ -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
+ ```
@@ -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
+ ```
@@ -7,7 +7,7 @@ pythonpath = ["src"]
7
7
  testpaths = ["tests"]
8
8
 
9
9
  [tool.ruff]
10
- target-version = "py38"
10
+ target-version = "py39"
11
11
  line-length = 100
12
12
 
13
13
  [tool.ruff.lint]
@@ -1,7 +1,6 @@
1
1
  #!/usr/bin/env python3
2
2
  """Pre-release regression test - runs all CLI commands against real MaxCompute backend."""
3
3
  import json
4
- import os
5
4
  import sys
6
5
  import tempfile
7
6
  from io import StringIO
@@ -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="0.4.7",
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
- include_package_data=True,
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",
@@ -2,4 +2,4 @@
2
2
 
3
3
  __all__ = ["__version__"]
4
4
 
5
- __version__ = "0.4.7"
5
+ __version__ = "0.5.0"