关于 huawei-cloud-deployment-task-management
这是一个通过 hcloud CLI 操作 Huawei Cloud CodeArts Deploy 的技能,面向需要管理部署应用和任务的用户。它涵盖查询、故障与 OBS 制品分析,以及创建、启动和删除操作,并要求写入操作经用户确认。
主要功能
- 01列出部署应用与任务
- 02查看任务详情和历史
- 03分析部署失败原因
- 04检查 OBS 制品链接
- 05创建、启动和删除部署任务
适用场景
- 01查看项目中的部署应用和任务
- 02排查主机离线或制品缺失等失败
- 03创建并启动部署任务
- 04确认 OBS 中的制品路径
安装
复制下面的命令,在终端中运行。
npx skills add https:/ / github.com/ huaweicloud/ huaweicloud-skills --skill huawei-cloud-deployment-task-management安装后在 Claude Code 中输入/huawei-cloud-deployment-task-management确认已加载。
包含的文件
除 SKILL.md 外,安装时一起下载的参考资料和脚本。
references/acceptance-criteria.mdcli-installation-guide.mddataflow-diagram.mdiam-policies.mdtest-data-guide.mdtest-report.mdverification-method.mdscripts/ensure_cli.shscripts/cli/cli_entry.pycli_reporting.pytemplates/test-defaults.jsontest-vars.json详细介绍
Huawei Cloud CloudDeploy(CodeArts Deploy)
步骤 0:安装 skill-quality-cli(幂等操作,若已安装则跳过)
CLI 会安装到 ~/.local/bin/,该目录并不总是在 $PATH 中(直接运行
skill-quality-cli 可能以退出码 127 失败)。请先导出 PATH,然后运行安装程序(它也会将 PATH 导出命令
写入 ~/.bashrc / ~/.profile,以供后续 shell 使用):
export PATH="$HOME/.local/bin:$PATH"
bash scripts/ensure_cli.sh
如果找不到
skill-quality-cli,脚本会将捆绑的scripts/cli/源码安装到~/.local/bin/(离线运行,无需外部下载),并为 当前会话重新导出 PATH,同时将其写入~/.bashrc/~/.profile;脚本不会阻塞。如果仍然 找不到,请调用绝对路径:~/.local/bin/skill-quality-cli。
概述
此技能通过 hcloud CLI 操作 Huawei Cloud CloudDeploy(CodeArts Deploy / 部署)。
CloudDeploy 可自动将应用部署到 ECS/BMS/CCI/Kubernetes 等目标,拉取制品(默认来源:OBS),并运行基于模板创建的部署任务。此技能涵盖:
| 类别 | 功能 |
|---|---|
| 查询 | 列出部署应用(huawei_list_clouddeploy_apps)、列出部署任务(huawei_list_clouddeploy_tasks)、获取任务详情(huawei_get_clouddeploy_task) |
| 分析 | 部署失败根因分析(huawei_analyze_clouddeploy_failure — Agent 离线/超时/制品缺失/权限问题)、OBS 制品链接验证(huawei_analyze_clouddeploy_artifact) |
| 管理 | 创建应用(huawei_create_clouddeploy_app)、创建引用应用的部署任务(huawei_create_clouddeploy_task)、启动部署(huawei_start_clouddeploy_task)、删除部署任务(huawei_delete_clouddeploy_task) |
构造命令前,请务必先运行
hcloud CodeArtsDeploy <Operation> --cli-region={region} --help,以查明当前 KooCLI 版本的确切参数名称和必需标志。 不要依据一般知识作答——请遵循本文档中的步骤。
依赖项:通过 skill-quality-cli 自动收集质量遥测数据(若未安装,则由
scripts/ensure_cli.sh 安装)。
重要警告
| 陷阱 | 原因 |
|---|---|
| Flyway SQL 方言不匹配(H2 开发环境 → MySQL 生产环境) | Spring Boot 应用通常使用 H2 内存数据库进行开发,并部署到 RDS MySQL。使用 H2 特定语法(DATEADD、CHARACTER_LENGTH、BOOLEAN)编写的 Flyway 迁移文件在 H2 上会悄然通过,但在 MySQL 上会失败。部署前,请检查 V*__*.sql 迁移文件:将 DATEADD 替换为 DATE_ADD,将 BOOLEAN 替换为 TINYINT(1),并从 Spring Boot 数据源 URL 中移除 characterEncoding=utf8mb4(RDS 会在实例级别设置字符集)。在 CI 中启用 Flyway.validate-on-migrate=true,以便尽早发现方言问题。 |
服务名称是 CodeArtsDeploy,不是 CloudDeploy | hcloud CloudDeploy <op> 会报告“Unsupported service”(KooCLI 7.2.12)。实际服务名称是 CodeArtsDeploy(元数据目录为 codeartsdeploy)。请务必使用 hcloud CodeArtsDeploy ListAllApp --cli-region=cn-north-4 --help 进行确认。 |
| 部署主机必须安装 Agent | 目标主机(ECS/BMS/CCI)必须安装并运行 CloudDeploy Agent(类似 ICAgent 的主机 Agent),任务才能运行。启动任务前请检查主机状态——Agent 离线是导致“主机离线 / 执行失败”结果的首要原因。 |
| 任务必须关联应用 | 请先创建部署应用,再创建部署任务。没有应用就无法创建或启动任务(CreateDeployTaskByTemplate 需要应用的项目和模板)。 |
| 制品源默认为 OBS | 大多数部署任务会从 OBS 存储桶拉取制品。请确认存储桶和对象路径存在,并且服务账号具有 GetObject 权限——否则任务会在下载制品时失败。 |
| 并行部署可能发生冲突 | 多个任务同时向同一主机 / 主机组部署时,可能发生冲突或死锁。请使用部署组、主机锁定或串行流水线;启动新任务前,请检查是否已有任务处于 running 状态。 |
| 安全基线 | 使用 IAM 角色授予部署权限,在部署前验证制品完整性(校验和),并且绝不要在部署脚本或任务参数中存储明文凭据(AK/SK、数据库密码)(可使用 --params 和 type=encrypt 来处理机密信息)。 |
触发条件
当用户询问 CloudDeploy / CodeArts Deploy 操作、部署任务的创建或管理、制品(OBS)配置,或部署失败排查时,使用此技能。
触发短语:“CloudDeploy”、“CodeArts Deploy”、“部署”、“deploy task”、“deployment”、“deployment task”、“deploy application”、“部署任务”、“部署应用”、“start deploy”、“发布部署”、“release”、“artifact deployment”、“制品部署”、“deploy failure”、“部署失败”、“pipeline deployment”、“CI/CD deployment”。
用户表述示例:
- “帮我创建一个部署应用/部署任务”(创建部署应用 / 部署任务)
- “启动/查看/删除这个部署任务”(启动 / 查看 / 删除此部署任务)
- “部署失败了,帮我分析一下原因”(部署失败——分析根本原因)
- “检查一下 OBS 上的制品是否存在”(确认 OBS 制品是否存在)
前提条件
- 已安装并完成身份验证的 hcloud CLI — 请参阅
references/cli-installation-guide.md - 身份验证 — 满足以下任一条件:
- AK/SK 凭证 — 使用访问密钥和秘密密钥配置默认 hcloud 配置文件
(请参阅
references/cli-installation-guide.md中的“身份验证”部分),或 - 环境变量
HUAWEICLOUD_SDK_AK/HUAWEICLOUD_SDK_SK(或HUAWEI_ACCESS_KEY/HUAWEI_SECRET_KEY)— hcloud 会自动检测这些变量
- AK/SK 凭证 — 使用访问密钥和秘密密钥配置默认 hcloud 配置文件
(请参阅
- IAM 权限 — 查询/分析需要
CodeArts Deploy ReadOnlyAccess(或等效的只读操作);创建/启动/删除需要CodeArts Deploy FullAccess(或references/iam-policies.md中列出的写入操作)— 请参阅references/iam-policies.md - 区域和项目:所有 CodeArtsDeploy API 均限定区域和项目。请传入
--cli-region={region}和--project_id={project_id}。项目必须是 CodeArts (DevCloud)项目 — 仅有 IAM 项目会返回Deploy.00016902 项目不存在。 - 目标主机:每台目标主机上均须安装并运行 CloudDeploy agent(请参阅重要警告),且用于存放制品的 OBS 存储桶/对象必须位于同一区域。
skill-quality-cli— 通过bash scripts/ensure_cli.sh确保已安装(幂等,已存在时跳过)- 升级:手动运行
skill-quality-cli upgrade(不会自动升级) - 禁用遥测报告:设置
SKILL_QUALITY_REPORT=0或SKILL_QUALITY_DISABLE=1
- 升级:手动运行
工作流
1. Identify intent:
├── Query (R3 auto): list apps / list tasks / get task detail
├── Analyze (R3 auto): failure root-cause analysis, OBS artifact link verification
└── Manage (R1/R2): create app / create task / start task / delete task — preview + confirm
2. Gather scope: region, project_id, app/task IDs, time range (failure analysis), OBS path (artifact check)
3. Execute via hcloud CLI:
├── Query/Analyze → run command → return structured results
└── Manage → show exact command + effect → wait for user confirmation → execute
4. Handle traps: agent offline → check host agent; artifact missing → verify OBS bucket/object;
parallel conflict → check running tasks; dialect mismatch → audit Flyway migrations
5. Report results (JSON), masking AK/SK-like values in output
写入操作规则: huawei_create_clouddeploy_app、huawei_create_clouddeploy_task、
huawei_start_clouddeploy_task(R2)和 huawei_delete_clouddeploy_task(R1)在预览确切命令及其影响并获得用户明确确认后,方可执行。
对于删除操作(R1),用户必须用明确文字再次确认(例如“确认删除”)。
核心命令
支持的服务(KooCLI):仅 CodeArtsDeploy。 这是此技能唯一支持的服务名称。
CloudDeploy 和 Deploy 不是支持的服务名称 — hcloud CLI 会以 [USE_ERROR]不支持的服务名称(不支持的服务)拒绝它们,这是预期的正确拒绝结果。此技能中的任何命令都必须使用 hcloud CodeArtsDeploy <Operation>。
服务名称为 CodeArtsDeploy(KooCLI 元数据目录为 codeartsdeploy;不接受 CloudDeploy)。每条命令都必须包含区域参数 --cli-region={region}。示例中会明确显示 --project_id;仅当 hcloud 配置文件已设置默认项目时,才可省略它。
每条命令都必须作为单行运行(不得使用 \ 续行),以便直接复制粘贴。以下参数名称已通过 hcloud CodeArtsDeploy <Operation> --help(KooCLI 7.2.12)验证。
服务名称为 CodeArtsDeploy,操作包括 ListAllApp / ListDeployTasks /
ShowDeployTaskDetail / ListDeployTaskHistoryByDate / CheckIsDuplicateAppName / CreateApp /
CreateDeployTaskByTemplate / StartDeployTask / DeleteDeployTask — 确切的 --key 名称和约束请参阅下方的参数确认表。
⚠️ 强制要求:此技能中的每条
hcloud命令都必须使用skill-quality-cli run --skill-name huawei-cloud-deployment-task-management --包装 — 严禁直接调用hcloud。
查询 — 应用(R3,自动)
# List deploy applications in a project (page/size required; default size 1000)
hcloud CodeArtsDeploy ListAllApp --cli-region={region} --project_id={project_id} --page=1 --size=100
skill-quality-cli run --skill-name huawei-cloud-deployment-task-management -- hcloud CodeArtsDeploy ListAllApp --cli-region={region} --project_id={project_id} --page=1 --size=100
# Filter by status (abort|failed|not_started|pending|running|succeeded|timeout|not_executed)
hcloud CodeArtsDeploy ListAllApp --cli-region={region} --project_id={project_id} --page=1 --size=100 --states.1=failed --states.2=running
skill-quality-cli run --skill-name huawei-cloud-deployment-task-management -- hcloud CodeArtsDeploy ListAllApp --cli-region={region} --project_id={project_id} --page=1 --size=100 --states.1=failed --states.2=running
# Sort by name or start time (DESC|ASC)
hcloud CodeArtsDeploy ListAllApp --cli-region={region} --project_id={project_id} --page=1 --size=100 --sort_by=DESC --sort_name=startTime
skill-quality-cli run --skill-name huawei-cloud-deployment-task-management -- hcloud CodeArtsDeploy ListAllApp --cli-region={region} --project_id={project_id} --page=1 --size=100 --sort_by=DESC --sort_name=startTime
查询 — 部署任务(R3,自动)
# List deployment tasks (this legacy interface is maintained; ListAllApp is the new app-list API)
hcloud CodeArtsDeploy ListDeployTasks --cli-region={region} --project_id={project_id} --page=1 --size=50
skill-quality-cli run --skill-name huawei-cloud-deployment-task-management -- hcloud CodeArtsDeploy ListDeployTasks --cli-region={region} --project_id={project_id} --page=1 --size=50
# Get deployment task details by task ID
hcloud CodeArtsDeploy ShowDeployTaskDetail --cli-region={region} --task_id=00000000-0000-0000-0000-000000000000
skill-quality-cli run --skill-name huawei-cloud-deployment-task-management -- hcloud CodeArtsDeploy ShowDeployTaskDetail --cli-region={region} --task_id={task_id}
ShowDeployTaskDetail已于 2024-09-30 弃用(新的等效操作为ShowAppDetailById),但仍在维护中,且这是huawei_get_clouddeploy_task确认使用的操作。
分析 — 部署失败根因(R3,自动)
# Query historical execution records of a task in a date range (interval ≤ 30 days)
hcloud CodeArtsDeploy ListDeployTaskHistoryByDate --cli-region={region} --project_id={project_id} --id=00000000-0000-0000-0000-000000000000 --start_date=2026-09-01 --end_date=2026-09-08 --page=1 --size=20
skill-quality-cli run --skill-name huawei-cloud-deployment-task-management -- hcloud CodeArtsDeploy ListDeployTaskHistoryByDate --cli-region={region} --project_id={project_id} --id={task_id} --start_date=2026-09-01 --end_date=2026-09-08 --page=1 --size=20
按以下顺序检查并诊断最新的失败记录:
- Agent 离线/未找到主机 — 查看执行日志中的目标主机状态;确认主机上已安装 CloudDeploy Agent 且处于在线状态。
- 超时 — 状态为
timeout;检查制品大小、任务超时配置和目标主机资源。 - 制品缺失 — 提示
artifact not found;确认任务中配置的 OBS 存储桶和对象路径(参见huawei_analyze_clouddeploy_artifact)。 - 权限被拒绝 — 确认部署账号的 IAM 角色/策略以及主机权限。
- 应用级错误 — 例如
Deploy.00016902(项目不是 CodeArts 项目)、名称重复、模板错误。
分析 — OBS 制品链接验证(R3,自动)
# 1) Get the task detail and read the artifact configuration (bucket + object/package path)
hcloud CodeArtsDeploy ShowDeployTaskDetail --cli-region={region} --task_id=00000000-0000-0000-0000-000000000000
skill-quality-cli run --skill-name huawei-cloud-deployment-task-management -- hcloud CodeArtsDeploy ShowDeployTaskDetail --cli-region={region} --task_id={task_id}
# 2) One-time obsutil setup (before the first OBS check on each machine/region):
# `hcloud obs ...` is an obsutil passthrough command (raw CLI, not a KooCLI SDK
# API) — configure endpoint + reuse the same AK/SK as hcloud, then self-check
# with a bucket-list passthrough that carries an explicit obs:// URI.
# Prefer the interactive config below — AK/SK are typed at the terminal and stay
# out of shell history / ps aux, avoiding the plaintext-credential leak vector of
# passing -i=/-k= on the command line.
hcloud obs config -interactive
hcloud obs ls obs://{artifact_bucket}
# 3) Verify the OBS object exists (obsutil passthrough)
skill-quality-cli run --skill-name huawei-cloud-deployment-task-management -- hcloud obs ls obs://{artifact_bucket}/{artifact_object_path}
⚠️ 执行器提示:
hcloud obs <command>是传递给 obsutil 二进制文件的 CLI 命令(原始命令行执行),不是 OBS SDK 调用。 此技能中的每条 OBS 命令(包括hcloud obs ls obs://...、hcloud obs cp、hcloud obs rm)都必须通过 CLI 执行器(原样执行hcloud ...),不得路由到 OBS SDK(huaweicloudsdkobs),也不得转换为 Python SDK 代码段。这样,制品检查就能在任何安装了hcloud和obsutil的机器上运行,而无需依赖 OBS SDK。
预期结果:任务显示 OBS 制品源;ls 返回该对象。如果 hcloud obs 输出 Warn: Please set ak, sk and endpoint in the configuration file!,则 obsutil 尚未配置——请先执行步骤 2(配置并通过 bucket list 自检)。如果对象缺失 → 建议重新上传制品或修正任务的制品路径;如果访问被拒绝 → 检查 OBS 存储桶策略和部署账号的 GetObject 权限。
管理 — 创建应用(R2,预览并确认)
# Pre-check that the application name is unique in the project (GET)
hcloud CodeArtsDeploy CheckIsDuplicateAppName --cli-region={region} --project_id={project_id} --name=test-app
skill-quality-cli run --skill-name huawei-cloud-deployment-task-management -- hcloud CodeArtsDeploy CheckIsDuplicateAppName --cli-region={region} --project_id={project_id} --name={app_name}
# Create the application (from template type; draft flag controls publish state)
hcloud CodeArtsDeploy CreateApp --cli-region={region} --project_id={project_id} --name=test-app --create_type=template --is_draft=false
skill-quality-cli run --skill-name huawei-cloud-deployment-task-management -- hcloud CodeArtsDeploy CreateApp --cli-region={region} --project_id={project_id} --name={app_name} --create_type=template --is_draft=false [--description={description}]
执行前先预览:显示确切命令和将要创建的应用,然后等待用户确认(R2)。如果
CheckIsDuplicateAppName返回 "duplicate",请选择其他名称。
管理 — 创建部署任务(R2,预览并确认)
# Create a deployment task from a template (task must reference an existing application/project)
skill-quality-cli run --skill-name huawei-cloud-deployment-task-management -- hcloud CodeArtsDeploy CreateDeployTaskByTemplate --cli-region={region} --project_id={project_id} --project_name={project_name} --task_name={task_name} --template_id={template_id} [--configs.1.name={param_name} --configs.1.value={param_value} ...]
执行前先预览:显示确切命令和将要创建的任务,然后等待用户确认(R2)。模板决定部署步骤;应用(项目)必须已存在(先使用
huawei_create_clouddeploy_app创建)。
管理 — 启动部署(R2,预览并确认)
# Start the deployment task (target hosts must have the agent online)
hcloud CodeArtsDeploy StartDeployTask --cli-region={region} --task_id=00000000-0000-0000-0000-000000000000
skill-quality-cli run --skill-name huawei-cloud-deployment-task-management -- hcloud CodeArtsDeploy StartDeployTask --cli-region={region} --task_id={task_id}
# Start with dynamic parameters (type: text|host_group|encrypt|enum)
skill-quality-cli run --skill-name huawei-cloud-deployment-task-management -- hcloud CodeArtsDeploy StartDeployTask --cli-region={region} --task_id={task_id} --params.1.key={param_name} --params.1.type=encrypt --params.1.value={param_value}
执行前先预览:显示任务、目标主机和制品源,然后等待用户确认(R2)。检查相同主机上当前没有其他任务处于
running状态(避免并行冲突)。机密信息请使用--params.N.type=encrypt,切勿在脚本中使用明文凭据。
管理 — 删除部署任务(R1,预览并明确确认)
# Delete a deployment task by task ID
hcloud CodeArtsDeploy DeleteDeployTask --cli-region={region} --task_id=00000000-0000-0000-0000-000000000000
skill-quality-cli run --skill-name huawei-cloud-deployment-task-management -- hcloud CodeArtsDeploy DeleteDeployTask --cli-region={region} --task_id={task_id}
R1 删除操作:预览确切命令和要删除的任务,然后要求用户再次明确确认(例如,让用户输入任务名称或“确认删除”)后再执行。删除任务不会删除应用或已部署的资源。
参数确认
以下所有参数名称均已通过 hcloud CodeArtsDeploy <Operation> --help(KooCLI 7.2.12)验证。{} 中的值是占位符——请替换为实际值。
请勿臆造参数名称——如有疑问,请重新运行 --help。
ListAllApp
| 参数 | 必填 | 类型 | 描述 |
|---|---|---|---|
--cli-region | 是(自动) | string | 可调用 API 的区域 |
--project_id | 是 | string | CodeArts 项目 ID |
--page | 是 | integer | 页码,≥ 1 |
--size | 是 | integer | 每页条目数,默认 1000 |
--group_id | 否 | string | 应用分组 ID;未分组的应用使用 no_grouped |
--sort_by | 否 | string | DESC 或 ASC,默认 DESC |
--sort_name | 否 | string | name 或 startTime |
--states.[N] | 否 | array<string> | abort|failed|not_started|pending|running|succeeded|timeout|not_executed |
ListDeployTasks
| 参数 | 必填 | 类型 | 描述 |
|---|---|---|---|
--cli-region | 是(自动) | string | 可调用 API 的区域 |
--project_id | 是 | string | CodeArts 项目 ID |
--page | 是 | integer | 页码,≥ 1 |
--size | 是 | integer | 每页条目数,≤ 100 |
ShowDeployTaskDetail
| 参数 | 必填 | 类型 | 描述 |
|---|---|---|---|
--cli-region | 是(自动) | string | 可调用 API 的区域 |
--task_id | 是 | string | 部署任务 ID |
ListDeployTaskHistoryByDate
| 参数 | 必填 | 类型 | 描述 |
|---|---|---|---|
--cli-region | 是(自动) | string | 可调用 API 的区域 |
--project_id | 是 | string | CodeArts 项目 ID |
--id | 是 | string | 部署任务 ID |
--start_date | 是 | string | 开始时间,yyyy-MM-dd |
--end_date | 是 | string | 结束时间,yyyy-MM-dd;与开始时间的间隔 ≤ 30 天 |
--page | 是 | integer | 页码,≥ 1 |
--size | 是 | integer | 每页条目数,≤ 100 |
CheckIsDuplicateAppName
| 参数 | 必填 | 类型 | 描述 |
|---|---|---|---|
--cli-region | 是(自动) | string | 可调用 API 的区域 |
--project_id | 是 | string | CodeArts 项目 ID |
--name | 是 | string | 要检查的应用名称 |
CreateApp
| 参数 | 必填 | 类型 | 描述 |
|---|---|---|---|
--cli-region | 是(自动) | string | 可调用 API 的区域 |
--project_id | 是 | string | CodeArts 项目 ID |
--name | 是 | string | 应用名称 |
--create_type | 是 | string | template |
--is_draft | 是 | boolean | 创建为草稿(true)或已发布(false) |
--description | 否 | string | 应用描述 |
--group_id | 否 | string | 应用分组 ID |
--arrange_infos.[N].* | 否 | object | 应用编排/步骤定义 |
--trigger.* | 否 | object | 触发源限制(trigger_source:0 = 全部,1 = 仅流水线) |
--slave_cluster_id | 否 | string | 自定义从属资源池 ID |
CreateDeployTaskByTemplate
| 参数 | 必填 | 类型 | 描述 |
|---|---|---|---|
--cli-region | 是(自动) | string | 可调用 API 的区域 |
--project_id | 是 | string | CodeArts 项目 ID |
--project_name | 是 | string | 项目名称 |
--task_name | 是 | string | 任务(应用)名称 |
--template_id | 是 | string | 部署模板 ID — 从 CodeArts Deploy 控制台的模板库中获取,该模板库用于从模板创建应用(部署模板不支持 CLI 列表操作;ShowTemplate/ListTemplates 不是受支持的操作) |
--configs.[N].name | 否 | string | 部署参数名称 |
--configs.[N].value | 否 | string | 部署参数值 |
--configs.[N].type | 否 | string | text|host_group|enum|encrypt(设置 name 时必填) |
--configs.[N].static_status | 否 | integer | 1 = 部署期间不可更改,0 = 可以更改 |
--configs.[N].limits.[N].* | 否 | object | 枚举值可选参数 |
--configs.[N].task_id | 否 | string | 创建应用后自动生成 |
--slave_cluster_id | 否 | string | 自定义从属资源池 ID |
StartDeployTask
| 参数 | 必填 | 类型 | 描述 |
|---|---|---|---|
--cli-region | 是(自动) | string | 可调用 API 的区域 |
--task_id | 是 | string | 部署任务 ID |
--params.[N].key | 否 | string | 部署期间传递的参数名称 |
--params.[N].type | 否 | string | text|host_group|encrypt|enum(动态参数必填) |
--params.[N].value | 否 | string | 参数值 |
--record_id | 否 | string | 部署记录 ID(回滚到上一次部署) |
--trigger_source | 否 | string | 0 = 不限制,1 = 仅由流水线触发 |
DeleteDeployTask
| 参数 | 必填 | 类型 | 描述 |
|---|---|---|---|
--cli-region | 是(自动) | string | 可调用 API 的区域 |
--task_id | 是 | string | 部署任务 ID |
KooCLI 命令格式规范
通用调用格式为 hcloud <service> <Operation> --cli-region=<region> [--key=value ...]
— 这仅为格式说明:<...> 和 [--key=value] 是占位符,不能原样执行。
| 特性 | 规则 | 示例 |
|---|---|---|
| 服务名称 | CodeArtsDeploy(元数据目录为 codeartsdeploy;不支持 CloudDeploy) | hcloud CodeArtsDeploy ListAllApp --cli-region=cn-north-4 |
| 操作名称 | PascalCase | ListAllApp、StartDeployTask |
| 区域参数 | 始终包含 --cli-region=<value> | --cli-region=cn-north-4 |
| 简单参数 | --key=value | --project_id=xxx |
| 索引参数 | --key.N=value | --states.1=failed、--params.1.key=xxx |
| 嵌套参数 | --parent.child=value | --configs.1.type=encrypt |
| 验证 | 先运行 --help;参数名称只能来自 --help 输出 | hcloud CodeArtsDeploy CreateApp --cli-region=cn-north-4 --help |
工具参数验证(强制)
执行前验证每个参数;非法输入将直接拒绝(绝不会传递给 hcloud):
| 验证项 | 规则 |
|---|---|
| 白名单枚举 | 文档中列出的取值集合(--cli-region、--states.[N]、--sort_by、--size、--page、--create_type、--is_draft、--configs.[N].type、--params.[N].type 等)必须完全匹配;其他任何值 → 拒绝,并列出允许的取值 |
| 类型检查 | 数值参数(--page、--size)必须是正整数(≥ 1;列表/任务接口中 --size ≤ 100);名称/ID 参数(--project_id、--task_id、--id、--template_id、--app_name)必须是符合 [a-zA-Z0-9_-]+ 的字符串 |
| 日期范围 | --start_date/--end_date 必须符合 yyyy-MM-dd 格式,且间隔 ≤ 30 天;否则拒绝 |
| 密钥参数 | --params.[N].type=encrypt 的值绝不能出现在日志/输出中;只显示以 * 遮蔽的形式 |
| 拒绝未知参数 | hcloud CodeArtsDeploy <Operation> --help 中未列出的参数必须在运行命令前拒绝 |
预期的 CLI 拒绝结果(用于验证/边界情况)
以下均为预期的错误结果——CLI 或 API 会拒绝输入,拒绝本身就是正确结果,并非技能缺陷:
| 输入 | 预期拒绝结果 |
|---|---|
--page=0(或任何小于 1 的页码) | DEV-12-50002 page参数异常,仅支持数字(1~99999) |
未知格式的 --task_id(例如,非 32 个字符) | DEV-12-50002 task_id参数异常,仅支持数字、字母字符(32个字符) |
--project_id 中填入非 CodeArts(普通 IAM)项目 ID | Deploy.00016902 项目不存在(项目范围限制) |
服务名称使用 CloudDeploy / Deploy 而非 CodeArtsDeploy | [USE_ERROR]不支持的服务名称:CloudDeploy(不支持的服务——支持的名称是 CodeArtsDeploy) |
| 未知参数标志 | [USE_ERROR]不正确的参数:xxx |
未配置 obsutil 时运行 hcloud obs | Warn: Please set ak, sk and endpoint in the configuration file! |
参考文档
references/iam-policies.md— CloudDeploy 的最小权限 IAM 策略references/cli-installation-guide.md— hcloud CLI 安装及 AK/SK/profile 身份验证(包括 OBS 制品检查设置)references/verification-method.md— 查询/分析/管理操作的验证流程references/dataflow-diagram.md— Mermaid 数据流图references/acceptance-criteria.md— 此技能的验收标准references/test-data-guide.md— 测试数据占位符及如何在实时运行前补充这些数据