alibabacloud-odps-project-manage

MaxCompute 项目管理

管理 Alibaba Cloud MaxCompute（ODPS）项目，包括创建、查询和列出操作。

前提条件

预检查：Aliyun CLI 版本必须 >= 3.3.3

运行 aliyun version 验证版本是否 >= 3.3.3。如果尚未安装或版本过低， 运行 curl -fsSL https://aliyuncli.alicdn.com/setup.sh | bash 进行更新， 或参阅 references/cli-installation-guide.md 了解安装说明。

然后[必须]运行 aliyun plugin update，确保本地计算机上已有的插件始终保持最新。

[必须] CLI User-Agent — 每次调用 aliyun CLI 命令时都必须包含： --user-agent AlibabaCloud-Agent-Skills/alibabacloud-odps-project-manage

[必须] AI-Mode 命令 — 使用 aliyun CLI 时，声明 AI-Mode 生命周期：

1. 在执行命令前启用 AI-Mode：

   aliyun configure ai-mode enable
   

2. 为 AI-Mode 设置 User-Agent：

   aliyun configure ai-mode set-user-agent --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-odps-project-manage"
   

3. 工作流结束后禁用 AI-Mode：

   aliyun configure ai-mode disable
   

快速入门

用户询问 MaxCompute 项目时，请按以下步骤操作：

1. 确定意图：创建 / 列出 / 获取
2. 获取 RegionId：询问用户使用哪个区域（例如 cn-hangzhou、cn-shanghai）
3. 执行：使用 --region {REGION_ID} 和 --user-agent AlibabaCloud-Agent-Skills/alibabacloud-odps-project-manage 运行相应命令
4. 验证：确认结果并向用户汇报

执行前检查清单（每次执行命令前）

运行任何命令之前，必须确认以下所有事项：

• 我已询问用户 RegionId（未使用默认值）
• 我已获取用户提供的实际 RegionId 值（不是占位符）
• 我的命令包含 --region {ACTUAL_REGION_ID}
• 我的命令包含 --user-agent AlibabaCloud-Agent-Skills/alibabacloud-odps-project-manage
• 我没有读取或回显任何 AK/SK 值
• 我没有对用户提供的参数使用硬编码值

如果任何一项未通过，请停止并先修正。

任务完成检查清单

重要：必须按顺序完成所有步骤。请勿提前停止。

列出项目：

1. 询问用户：“您想查询哪个区域？（例如 cn-hangzhou、cn-shanghai）”
2. 询问用户：“要按哪个配额昵称筛选？（例如 os_PayAsYouGoQuota，或按 Enter 使用默认值）”
3. 必须使用 quota-nick-name 参数：
   • 如果用户指定了配额：使用 --quota-nick-name={USER_QUOTA}
   • 如果用户未指定：使用 --quota-nick-name=os_PayAsYouGo
4. 使用必需参数执行：

   aliyun maxcompute list-projects --region {REGION_ID} --quota-nick-name={QUOTA_NICKNAME} --max-item=20 --user-agent AlibabaCloud-Agent-Skills/alibabacloud-odps-project-manage
   

5. 等待命令输出
6. 如果出现 400 错误（未找到配额）：
   • 调用 aliyun maxcompute list-quotas --billing-type ALL --region {REGION_ID} --user-agent AlibabaCloud-Agent-Skills/alibabacloud-odps-project-manage
   • 向用户展示可用配额供其选择
   • 使用用户选择的配额重新运行 list-projects
7. 解析响应并展示结果
8. 确认任务已完成

禁止：

• ❌ 使用 --marker 进行分页
• ❌ 获取所有项目后再使用 Python/jq 在本地筛选
• ❌ 调用 API 时不带 --quota-nick-name 参数

必须：

• ✅ 始终使用 --quota-nick-name，并采用用户指定的配额或默认值
• ✅ 始终使用 --max-item=20
• ✅ 由 API 执行服务端筛选

获取项目：

1. 询问用户：“哪个区域？（例如 cn-hangzhou）”
2. 询问用户：“项目名称是什么？”
3. 执行：aliyun maxcompute get-project --region {REGION_ID} --project-name {PROJECT_NAME} --user-agent AlibabaCloud-Agent-Skills/alibabacloud-odps-project-manage
4. 等待命令输出
5. 解析 JSON 响应，查找 data.name、data.status、data.owner
6. 以清晰的格式向用户展示项目详情
7. 向用户确认任务已完成

对于创建项目：

1. 询问用户：“要在哪个地域创建？（例如，cn-hangzhou）”
2. 询问用户：“项目名称是什么？”
3. 强制验证： 如果项目名称为空或仅包含空白字符，则停止并再次询问用户：“项目名称不能为空。请提供有效的项目名称。”
4. 关键： 保存用户输入的准确项目名称，切勿使用占位文本
5. 必须调用 list-quotas： 执行：aliyun maxcompute list-quotas --billing-type ALL --region {REGION_ID} --user-agent AlibabaCloud-Agent-Skills/alibabacloud-odps-project-manage
6. 等待命令输出
7. 解析 list-quotas 响应： 找到带有 nickName 的配额及其二级配额（查看 data.quotas[].subQuotas 或类似字段）
8. 严格验证： 从 list-quotas 响应中选择一个二级配额的 nickName（不是一级配额）
9. 去除空白字符： 删除配额 nickName 前后的空格。如果 nickName 内部包含空格，请去除空格或选择其他配额
10. 执行前检查： 确认 REGION_ID、PROJECT_NAME 和 SECONDARY_QUOTA_NICKNAME（已去除空白字符且不含空格）均为实际值
11. 询问 typeSystem（可选）： “要使用哪种 typeSystem？（1=MaxCompute，2=MaxCompute2，hive=兼容 Hive；默认值：2）”
12. 验证 typeSystem： 必须为 "1"、"2" 或 "hive"。如果未指定或无效，则使用默认值 "2"
13. 使用实际值执行创建命令：

    aliyun maxcompute create-project --region {ACTUAL_REGION} --body '{"name":"ACTUAL_PROJECT_NAME","defaultQuota":"SECONDARY_QUOTA_NICKNAME","productType":"payasyougo","typeSystem":"TYPE_SYSTEM_VALUE"}' --user-agent AlibabaCloud-Agent-Skills/alibabacloud-odps-project-manage
    

    实际值示例：

    aliyun maxcompute create-project --region cn-hangzhou --body '{"name":"my-project-123","defaultQuota":"os_PayAsYouGoQuota_sub","productType":"payasyougo","typeSystem":"2"}' --user-agent AlibabaCloud-Agent-Skills/alibabacloud-odps-project-manage
    

14. 等待命令输出
15. 检查创建响应： 如果创建命令返回错误（非 2xx），则停止并向用户报告错误。不要继续验证。
16. 仅当创建成功时： 执行以下命令进行验证：aliyun maxcompute get-project --region {REGION_ID} --project-name {PROJECT_NAME} --user-agent AlibabaCloud-Agent-Skills/alibabacloud-odps-project-manage
17. 关键： 确认响应中包含正确的项目名称（即用户请求的项目，而不是其他项目）
18. 检查状态： 确认响应中包含 "status":"AVAILABLE"
19. 如果验证返回 403/Access Denied： 告知用户所需的权限并停止
20. 如果未找到项目： 报告“项目创建失败——创建后未找到项目”
21. 如果返回了错误的项目： 报告错误；不要用其他项目替代
22. 仅当所有检查均通过时： 向用户确认：“项目 {PROJECT_NAME} 已成功创建，状态为 AVAILABLE”

如果用户请求删除：

回复：“此技能不支持删除项目。请使用 Alibaba Cloud 控制台或联系管理员。”

常见错误与解决方案

错误	原因	解决方案
ProjectNotFound	项目不存在	检查项目名称拼写和区域
ProjectAlreadyExist	名称已被占用	请用户提供其他项目名称
get project default quota error	没有有效配额	先运行 list-quotas，确保配额存在
InvalidProjectName	名称格式错误	仅使用小写字母、数字和下划线（3-28 个字符）
NoPermission 或 403 Access Denied	RAM 权限问题	告知用户：“你需要具有执行 list-quotas、create-project 和 get-project 的 odps 权限。请联系管理员。”
RegionId required	缺少 --region	始终在命令中添加 --region {REGION_ID}
ODPS-0420095: Access Denied	缺少读取权限	告知用户所需权限，然后停止

禁止的操作

重要：绝不要执行以下操作：

1. 绝不要读取或回显 AK/SK 值（例如，echo $ALIBABA_CLOUD_ACCESS_KEY_ID）
2. 绝不要使用硬编码值——始终向用户询问参数，然后使用用户提供的实际答案（而不是占位文本）
3. 绝不要使用包含明文凭证值的 aliyun configure set
4. 绝不要运行 aliyun ram 命令
5. 绝不要执行任何未包含 --user-agent AlibabaCloud-Agent-Skills/alibabacloud-odps-project-manage 的命令
6. 绝不要跳过询问 RegionId——此项始终为必填项
7. 绝不要假定默认区域——始终询问用户
8. 绝不要将大写的 API 操作格式用作 CLI 命令——始终使用插件格式，即小写字母和连字符（例如，create-project）
9. 绝不要执行 aliyun maxcompute delete-project——此技能不支持删除项目

反面示例

❌ 错误	✅ 正确
将大写的 API 操作名称用作 CLI 命令	aliyun maxcompute create-project（插件格式，小写字母并使用连字符）
'{"name":"{PROJECT_NAME}"}'（占位符）	'{"name":"actual-name"}'（实际值）
--region cn-hangzhou（硬编码）	先询问用户，然后使用用户提供的答案
缺少 --user-agent	必须包含 --user-agent AlibabaCloud-Agent-Skills/alibabacloud-odps-project-manage
echo $ALIBABA_CLOUD_ACCESS_KEY_ID	绝不要读取或显示凭证
aliyun ram ... 命令	RAM 命令不在范围内
aliyun maxcompute delete-project	不支持删除项目
失败时验证其他项目	报告失败，不要替换项目

架构

MaxCompute Service
    └── Project (Workspace)
          ├── defaultQuota (Compute Resource - MUST exist before project creation)
          ├── productType (payasyougo/subscription)
          └── typeSystem ("1", "2", or "hive"; default: "2")

依赖项

前提条件：创建项目之前必须已有配额。

每个 MaxCompute 项目都需要一个计算配额（defaultQuota）。该配额必须已存在于你的账户中——如果不存在，create-project 调用将失败并报错 get project default quota error。

使用 alibabacloud-odps-quota-manage 技能创建或查询配额：

• 按量付费：aliyun maxcompute create-quota --charge-type payasyougo --commodity-code odps --region <region> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-odps-project-manage
• 包年包月：完整参数（partNickName、CU、ord_time 等）请参阅 alibabacloud-odps-quota-manage 技能
• 列出已有配额：aliyun maxcompute list-quotas --billing-type ALL --region <region> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-odps-project-manage

创建或确认配额存在后，创建项目时将其 nickName 用作 defaultQuota 参数。

安装

预检查：需要 Aliyun CLI >= 3.3.3

运行 aliyun version 验证版本是否 >= 3.3.3。如果尚未安装或版本过低， 运行 curl -fsSL https://aliyuncli.alicdn.com/setup.sh | bash 进行更新， 或参阅 references/cli-installation-guide.md 获取安装说明。

预检查：需要更新 Aliyun CLI 插件

[MUST] 运行 aliyun configure set --auto-plugin-install true 启用自动安装插件。 [MUST] 运行 aliyun plugin update，确保所有现有插件始终为最新版本。

# Install/Update Alibaba Cloud CLI
curl -fsSL https://aliyuncli.alicdn.com/setup.sh | bash

# Verify version (must be >= 3.3.3)
aliyun version

# Enable auto plugin installation
aliyun configure set --auto-plugin-install true

# Update plugins
aliyun plugin update

环境变量

除标准 Alibaba Cloud 凭据外，无需其他环境变量。

身份验证

重要：执行任何操作前，都必须检查凭据。

允许的凭据检查（仅限此命令）：

aliyun configure list

检查内容：

• 输出至少显示一个 mode: AK 或 mode: StsToken 配置文件
• 配置文件显示 access_key_id: ********（掩码形式即可）

如果没有有效配置文件：

• 告知用户：“请先运行 aliyun configure 设置凭据。”
• 停止——不要继续执行任何 MaxCompute 命令

禁止事项——绝对不要执行以下操作：

• ❌ echo $ALIBABA_CLOUD_ACCESS_KEY_ID
• ❌ echo $ALIBABA_CLOUD_ACCESS_KEY_SECRET
• ❌ aliyun configure get | grep access-key
• ❌ 任何会显示实际凭据值的命令

RAM 策略

**[MUST] RAM 权限预检查：**执行工作流前，确认当前用户具有所需权限。

所需权限列于 references/ram-policies.md。

**注意：**无需通过 CLI 命令验证 RAM 权限。ram-policies.md 中列出的权限仅供用户参考。假定用户已配置适当权限，并继续执行工作流。

参数

始终向用户询问以下值——切勿假定默认值：

参数	必填	描述
RegionId	是	区域 ID（cn-hangzhou、cn-shanghai 等）
projectName	是	项目名称
quotaNickName	创建时必填	配额别名（从 list-quotas 获取）

示例对话

**LIST：**用户提出请求 → Agent 询问 RegionId → Agent 执行 list-projects → Agent 展示结果

**CREATE：**用户提出请求 → Agent 询问 RegionId → Agent 询问 projectName → Agent 调用 list-quotas → Agent 创建项目 → Agent 验证 → Agent 确认成功

命令

列出项目

# Ask user for quota nickname first, then:
aliyun maxcompute list-projects --region {REGION_ID} --quota-nick-name={QUOTA_NICKNAME} --max-item=20 --user-agent AlibabaCloud-Agent-Skills/alibabacloud-odps-project-manage

**必须：**始终使用 --quota-nick-name 参数（由用户指定或使用默认值）。切勿获取全部结果后在本地筛选。

获取项目

aliyun maxcompute get-project --region {REGION_ID} --project-name {PROJECT_NAME} --user-agent AlibabaCloud-Agent-Skills/alibabacloud-odps-project-manage

创建项目

1. 先列出配额：

aliyun maxcompute list-quotas --billing-type ALL --region {REGION_ID} --user-agent AlibabaCloud-Agent-Skills/alibabacloud-odps-project-manage

2. 使用响应中的 quota nickName 创建：

aliyun maxcompute create-project --region {REGION_ID} --body '{"name":"{PROJECT_NAME}","defaultQuota":"{QUOTA_NICKNAME}","productType":"payasyougo"}' --user-agent AlibabaCloud-Agent-Skills/alibabacloud-odps-project-manage

成功验证方法

详细验证步骤请参阅 references/verification-method.md。

验证命令：

aliyun maxcompute get-project --region {REGION_ID} --project-name {PROJECT_NAME} --user-agent AlibabaCloud-Agent-Skills/alibabacloud-odps-project-manage

成功标准：

• 响应包含 "status":"AVAILABLE"
• 响应包含正确的 "name"，与创建的项目匹配
• 响应包含正确的 "defaultQuota"，与指定的配额匹配

如果验证失败：

1. 检查错误消息，了解具体问题
2. 向用户说明失败原因
3. 根据错误类型建议纠正措施

限制

以下操作无法通过 CLI/API 执行，需要访问控制台：

操作	原因	替代方案
查看账单详情	需要访问控制台	使用 账单控制台
以可视化方式管理 IAM 策略	仅限控制台的功能	使用 RAM CLI 管理策略
实时资源监控	需要控制台仪表板	使用 CloudMonitor API

API 和命令表

完整的 API 参考请参见 references/related-apis.md。

操作	CLI 命令（插件模式）	API 操作名称
创建项目	aliyun maxcompute create-project	create-project
获取项目	aliyun maxcompute get-project	get-project
列出项目	aliyun maxcompute list-projects	list-projects
列出配额	aliyun maxcompute list-quotas	list-quotas

技能完成标准（skill_pass 的必需条件）

要使 skill_pass_rate 成功，以下条件必须全部满足：

通用要求（适用于所有操作）：

1. ✅ 已询问用户 RegionId，且用户已提供答案
2. ✅ 所有命令均使用 --region {USER_PROVIDED_VALUE}（不能硬编码）
3. ✅ 所有命令均包含 --user-agent AlibabaCloud-Agent-Skills/alibabacloud-odps-project-manage
4. ✅ 未执行任何禁止的操作（未回显凭证，未执行 ram 命令）
5. ✅ 已向用户清晰报告任务结果

操作特定要求：

LIST：

• 执行命令：aliyun maxcompute list-projects --region {REGION} --quota-nick-name=os_PayAsYouGo --max-item=20 --user-agent AlibabaCloud-Agent-Skills/alibabacloud-odps-project-manage
• 首次尝试必须包含 --quota-nick-name=os_PayAsYouGo 参数
• 必须包含 --max-item=20 参数
• 如果首次尝试返回 400 错误，则使用 --quota-nick-name=os_PayAsYouGoQuota 重试
• 向用户展示结果（项目列表或“未找到项目”）

GET：

• 执行命令：aliyun maxcompute get-project --region {REGION} --project-name {NAME} --user-agent AlibabaCloud-Agent-Skills/alibabacloud-odps-project-manage
• 向用户展示项目详情

CREATE：

• 已询问用户 RegionId 和 projectName，并获取实际值

• 首先列出配额：aliyun maxcompute list-quotas --billing-type ALL --region {REGION} --user-agent AlibabaCloud-Agent-Skills/alibabacloud-odps-project-manage

• 请求正文中必须使用实际值，不能使用 {PROJECT_NAME} 等占位符

• 创建命令格式：--body '{"name":"ACTUAL_NAME","defaultQuota":"ACTUAL_QUOTA","productType":"payasyougo"}'

• 继续操作前必须检查创建响应是否有错误

• 执行验证命令：aliyun maxcompute get-project --region {REGION} --project-name {NAME} --user-agent AlibabaCloud-Agent-Skills/alibabacloud-odps-project-manage

• 必须验证响应中的项目名称与用户请求的项目一致

• 必须验证状态为 AVAILABLE

• 如果因权限问题（403）导致验证失败，则告知用户并停止

• 如果未找到项目或返回了错误的项目，则报告失败

• 如果验证成功（status=AVAILABLE），则向用户确认成功

• 如果用户请求删除项目，请告知其使用 Alibaba Cloud 控制台

最终技能通过检查：

Before responding to user, verify:
□ I followed the correct workflow for the operation type
□ I asked for ALL required parameters from user
□ I used user's actual values in commands (not placeholders or defaults)
□ I included --user-agent AlibabaCloud-Agent-Skills/alibabacloud-odps-project-manage in EVERY command
□ I did NOT perform any forbidden actions
□ I reported the final result to user

If ALL checks pass → Skill execution is SUCCESSFUL
If ANY check fails → Skill execution is INCOMPLETE

最终验证（标记任务完成前）

告知用户任务已完成前，必须验证以下所有事项：

对于 LIST：

• 我已询问 RegionId 并获得用户的回答
• 我已使用 --region {USER_ANSWER} 和 --user-agent AlibabaCloud-Agent-Skills/alibabacloud-odps-project-manage 执行 list-projects
• 我已向用户清晰展示结果

对于 GET：

• 我已询问 RegionId 并获得用户的回答
• 我已询问 projectName 并获得用户的回答
• 我已使用用户提供的值和 --user-agent AlibabaCloud-Agent-Skills/alibabacloud-odps-project-manage 执行 get-project
• 我已向用户清晰展示项目详情

对于 CREATE：

• 我已询问 RegionId 并获得用户的回答
• 我已询问 projectName 并获得用户的回答
• 我已执行 list-quotas 以获取有效配额
• 我已使用用户提供的值和 --user-agent AlibabaCloud-Agent-Skills/alibabacloud-odps-project-manage 执行 create-project
• 我已通过调用 get-project 验证创建结果
• 我已向用户确认成功

对于 DELETE：

• 告知用户不支持删除，并建议使用 Alibaba Cloud Console

如果任意一项检查失败，任务就未完成。

最佳实践

1. 命名约定：项目名称使用小写字母、数字和下划线
2. 配额选择：根据工作负载需求选择合适的配额
3. 产品类型：开发/测试使用 payasyougo，生产环境中工作负载可预测时使用 subscription
4. 类型系统：除非需要 Hive 兼容性，否则新项目使用 2（MaxCompute）
5. 资源清理：始终清理测试项目，避免不必要的费用

参考链接

文档	说明
references/related-apis.md	完整的 API 参考
references/ram-policies.md	所需的 RAM 权限
references/verification-method.md	验证步骤
references/cli-installation-guide.md	CLI 安装指南
MaxCompute Product Page	官方产品文档
create-project API	API 参考
get-project API	API 参考
list-projects API	API 参考