huawei-cloud-skill-tester

华为云 Skill 测试器 — 三轨八阶段端到端测试流水线

独立、可重复的华为云 Skill 测试框架。不依赖 skill-creator；可测试任何现有的华为云 Skill。 专注于真实环境功能测试和多 Skill 编排场景。

---

概览

此 Skill 提供一套三轨八阶段标准化测试流水线 （三级布局 × 共 8 个阶段：Phase 0-6 执行 + Phase 7 最终报告）：

层级	阶段	目标
第 1 层：单 Skill 单元测试	Phase 0~4	逐项验证每个 Skill：安装、功能提取、技术调研、测试用例生成、执行
第 2 层：集成测试	Phase 5~6	多 Skill 编排场景推导 + 端到端真实环境流程验证
第 3 层：最终报告	Phase 7	汇总并合并所有阶段输出的报告

核心设计原则

1. 链式验证 — 每个 Phase 开始前，检查上一阶段的 JSON 是否存在；如果缺失，则拒绝执行
2. 防 Agent 绕过 — 每项写入操作都需要用户确认；不允许自动绕过门禁
3. 三轨分层 — 各层之间设置明确的门禁；必须完成第 1 层后才能进入第 2 层
4. 批量可重复 — 支持 --skills "skill-a,skill-b" 或 --all-installed
5. 回退策略 — 只有 1 个 Skill 时，Phase 5/6 自动降级为单 Skill 生命周期测试。默认开启同级扫描（Phase 5/6 会自动查找与被测 Skill 位于同一目录中的其他 huawei-cloud-* Skill，以运行编排组合）。使用 --no-siblings 可选择退出。
6. 标准化 JSON 输出 — 所有阶段均使用统一的架构输出；Phase 7 将其合并为单份报告
7. 真实环境优先 — 在适用情况下，第 2 层阶段会针对真实华为云运行（写入操作受 ALLOW_WRITES 门禁控制）；多 Skill 的 Phase 6 目前只推导场景计划，不会实际执行，而单 Skill 的 Phase 6 会运行真实的创建→查询→更新→删除循环。不使用模拟或仿真。

数据流图

User Input (--skills or --all-installed)
    │
    ├── Tier 1 ──── Iterate over each skill ────
    │   Phase 0 → 1 → 2 → 3 → 4
    │   (phase-N-summary.json chain validation)
    │
    ├── Tier 2 ──── Integration ────
    │   Phase 5 (orchestration scenario derivation + real-environment execution)
    │   Phase 6 (e2e full-flow: create→query→update→delete lifecycle)
    │   Only 1 skill → Downgrade single-skill closed loop
    │
    └── Tier 3 ──── Final ────
        Phase 7 (merge phase-0~6 JSON into consolidated report)

---

依赖项：通过 skill-quality-cli 自动收集质量遥测数据（若未安装，则由 scripts/ensure_cli.sh 安装）。

先决条件

1. 已安装并完成身份验证的 hcloud CLI（用于第 2 层 CLI 模式测试）——参考：https://support.huaweicloud.com/qs-hcli/hcli_02_003.html
2. Python 3.8+ + huaweicloudsdk 软件包（用于 SDK 模式测试）——SDK 参考：https://console.huaweicloud.com/apiexplorer/#/sdkcenter
3. 华为云 AK/SK — 自动扫描所有前缀为 HUAWEI / HW / HWC 的环境变量（键名包含 AK/SK 标记的键值对）。如果缺失，框架会将环境变量设置模板输出到 stderr，并以状态码 77 退出。切勿要求用户在聊天中输入 AK/SK；用户必须在 shell 配置文件中通过其他方式设置环境变量，然后重新运行。（完整协议：references/agent-protocol.md）。
4. 目标 Skill 必须位于 $SKILL_INSTALL_DIR/ 下（自动检测顺序：~/.agents/skills/ → ~/.hermes/skills/ → 默认目录），也可由用户指定路径
5. jq 命令（所有 JSON 处理都依赖它）
6. API 参考：https://console.huaweicloud.com/apiexplorer/#/openapi

---

• skill-quality-cli — 由 bash scripts/ensure_cli.sh 确保可用（幂等；若已存在则跳过）
  • 升级：手动运行 skill-quality-cli upgrade（不会自动升级）
  • 禁用遥测报告：设置 SKILL_QUALITY_REPORT=0

工作流 — 三轨八阶段

Tier 1: Single-Skill Unit Testing
   Phase 0: Installation Verification (install/uninstall/reinstall)
   Phase 1: Feature Extraction (metadata + commands + resource types + doc checks)
   Phase 2: Technical Research (CLI→SDK→API three-level availability)
   Phase 3: Test Case Generation (functional TC-F + boundary + negative + API TC-A)
   Phase 4: Real-Environment Execution (read-only automatic + write ops require confirmation)

Tier 2: Integration Testing — Real-Environment Orchestration
   Phase 5: Multi-Skill Orchestration (conflict scan / scenario derivation / self-check)
   Phase 6: End-to-End Flow (resource lifecycle: create→query→update→delete)

Tier 3: Final Report
   Phase 7: Consolidated Report (merge phase-0~6 JSON, verdict + issues + reasons)

各阶段的完整实现规范（步骤、通过标准、JSON 字段）见 references/phase-details.md。

---

各阶段一览

阶段	名称	要点	判定标准
0	安装验证	目录完整性：必需的三项（SKILL.md、references 文件夹、iam-policies 文档）加上软性必需的 scripts 文件夹（纯 CLI 技能可能没有；会报告但不阻断）；安装/卸载/重新安装（相同路径/符号链接保护）	目录三项 + 生命周期（scripts 文件夹为软性必需）
1	功能提取	metadata/triggers/commands/capabilities/resource_types + doc_checks（引用一致性、禁止 .bak/.template 文件）	commands 和 triggers 非空
2	技术调研	CLI→SDK→API 三级可用性；纯本地工具自动标记为 not_applicable	可用性计数
3	测试用例生成	正向 + 边界（limit=1）+ 负向（未知参数）用例；占位符替换（/path/to、./xxx、{region}）；过滤模板/交互式命令	用例 > 0
4	执行	自动执行 + 输出质量判定（rc=0 且输出为空 → 警告）；负向用例错误质量；文档缺口分析（doc_gap_issues）；缺少依赖项标记	pass/fail/warn/skip
5	编排	多技能：触发冲突扫描 + 数据流候选项；单技能：降级为自检（内部歧义 + 写操作顺序）	冲突扫描
6	完整流程	多技能：场景推导；单技能：降级为完整功能循环（创建→查询→更新→删除）	场景步骤
7	报告	汇总阶段 0~6；判定结果 + pass_rate + issues_found + 各阶段原因；test-report.json/md	汇总判定结果

详细步骤、链式验证规则和 JSON 架构：references/phase-details.md 和 references/output-schema-spec.md。

---

KooCLI 命令格式标准

此测试框架使用 bash 脚本作为主要执行模式；不会直接执行原始的 hcloud CLI 命令。下方展示的 hcloud 命令字符串是格式模板——占位符示例，并非可执行命令：其中包含占位符标记（<Service>、{region}、 [--param1=value1 ...] 等），没有实际值，因此任何命令收集/测试用例生成/测试执行逻辑（阶段 1/3/4）都不得提取或执行这些命令模板。每个模板行均以 #（注释标记）开头，并且该部分明确标记为不可执行。

**可执行命令列表：**此技能中唯一真实可执行的命令是 scripts 目录下的流水线脚本， 通过 bash scripts/... 调用（例如 bash scripts/run-test-pipeline.sh --skills <name>、 bash scripts/tier1/phase-0-install-check.sh --skill <name> 等——请参阅下文的核心命令）。 本节中的所有 hcloud ... 格式模板都只是说明性占位符，不可执行；命令提取/执行逻辑必须跳过它们。

格式模板占位符示例——仅供了解格式；切勿提取或作为命令执行（# 注释行，包含 /{region} 占位符）

hcloud --cli-region={region} [--param1=value1 ...]

**Format Rules:**

- **Service name** — Follows KooCLI Services (uppercase: ECS, VPC, OBS; title case: CloudPond, IAMAccessAnalyzer)
- **Operation name** — PascalCase (e.g., ListServersDetails, ListBuckets)
- **Region** — Always include the `--cli-region` parameter with a real region value (e.g. `cn-north-4`). The token form `--cli-region={region}` is a template placeholder, never a real command.
- **Parameters** — Parameters use the `--name=value` syntax; the token `--param=value` is a format illustration only, never a real command.
- **Read-only limit** — Always append `--limit=1` for exploratory queries (real flag value, only meaningful inside an actual `hcloud` command).

For OBS service, the framework uses `hcloud obs` (obsutil) subsystem:

```bash
> **⚠️ Mandatory: every `hcloud` command in this skill MUST be wrapped with `skill-quality-cli run --skill-name huawei-cloud-skill-tester -- ` — bare `hcloud` calls are strictly forbidden.**

# OBS format-template placeholder examples — for reading the format only; never extract or execute (# comment lines, contain <command>/[args...] placeholders)
# hcloud obs <command> [args...] [options...]

---

核心命令

运行完整流水线

# Specify skills
bash scripts/run-test-pipeline.sh --skills "huawei-cloud-bss-voucher-manage"

# Specify multiple skills (comma-separated)
bash scripts/run-test-pipeline.sh --skills "huawei-cloud-bss-voucher-manage, huawei-cloud-ecs-manage"

# Scan all installed
bash scripts/run-test-pipeline.sh --all-installed

# Start from a specific phase (recovery scenarios only)
bash scripts/run-test-pipeline.sh --skills "bss-voucher" --phase 4

# Fresh mode
bash scripts/run-test-pipeline.sh --skills "bss-voucher" --fresh

运行单个阶段（调试）

bash scripts/tier1/phase-0-install-check.sh --skill "huawei-cloud-bss-voucher-manage"
bash scripts/tier1/phase-1-skill-analysis.sh --skill "huawei-cloud-bss-voucher-manage"
bash scripts/tier2/phase-5-orchestration.sh --skills "skill-a, skill-b"
bash scripts/tier3/phase-7-final-report.sh --skills "skill-a, skill-b"

运行多技能编排

# Derive and execute orchestration scenarios for 3 skills
bash scripts/tier2/phase-5-orchestration.sh --skills "ecs-manage, vpc-manage, eip-manage"

# Run E2E lifecycle test for a single skill
bash scripts/tier2/phase-6-full-flow.sh --skill "huawei-cloud-rds-intelligent-service"

---

参数确认

参数	必需	描述	示例
--skills	互斥	以逗号分隔的技能名称或目录名称	"bss-voucher-manage, ecs-manage"
--all-installed	互斥	扫描 $SKILL_INSTALL_DIR/huawei-cloud/ 下的所有 huawei-cloud-*	—
--phase	否	从指定的 Phase 开始（默认从缺失的阶段继续）	--phase 0
--fresh	否	将现有的 phase-*.json 归档（移动而非删除）到 phases/archive/<timestamp>/，然后从头开始。保留历史记录；不会删除任何内容。	—
--output	否	报告输出目录（默认：reports/）	--output ./test-reports
--skill-path	否	技能目录路径。设置后，find_skill_path 仅在此处搜索（不回退到安装目录）	--skill-path ./skills
--no-siblings	否	Phase 5/6 不会自动扫描同一目录中的同级 huawei-cloud-* 技能（默认开启扫描）	--no-siblings
--sibling-limit <N>	否	同级技能数量上限（默认 5；0 = 与 --no-siblings 相同）	--sibling-limit 3

环境变量（高级）

变量	默认值	用途
SKILL_INSTALL_DIR	自动检测：~/.agents/skills → ~/.hermes/skills → ~/.agents/skills	Agent 运行时安装技能的位置
SKILL_PATH_HERMES	SKILL_INSTALL_DIR 的别名	旧名称，为保持向后兼容而保留
SKILL_INSTALL_CMD	hermes skills	远程技能安装/卸载命令。设为 "" 可跳过实际安装。
ALLOW_WRITES	0	设为 1 时，Phase 4/6 的写入用例会实际通过实时 API 执行（默认跳过）
HUAWEI_REGION	cn-north-4	华为云区域
HUAWEI_ACCESS_KEY / HUAWEI_SECRET_KEY	—	Phase 4/6 的 SDK/CLI 执行所必需；也接受任何以 HUAWEI* / HW* / HWC* 为前缀的 AK/SK 环境变量

---

参考资料

核心文档（必读）

• references/architecture.md — 三轨八阶段架构图（Mermaid）
• references/output-schema-spec.md — 各阶段的完整 JSON 字段规范（包括 Phase 7 最终报告架构）
• references/phase-transition-rules.md — 阶段转换、回退和跳过规则
• references/acceptance-criteria.md — 质量门槛 + 17 项报告验收清单
• references/verification-method.md — 各阶段的手动验证方法（PowerShell + Git Bash）
• references/phase-details.md — 各阶段的完整实现规范（步骤、通过标准、JSON 字段）
• references/agent-protocol.md — 凭证请求协议（缺少 AK/SK 时的完整处理流程）

补充参考资料

• references/iam-policies.md — 运行测试器所需的最低 IAM 权限

模板（JSON Schema）

• templates/phase-report-schema.json — phase-N-summary.json（N=0..6）的 JSON Schema
• templates/test-case-schema.json — 单个测试用例（TC-F-* / TC-A-* / OF-* / FF-*）的 JSON Schema
• templates/scenario-example.json — Phase 6 多技能场景推导的参考示例

---

输出格式

所有测试产物都存放在被测 skill 同级目录下的 <skill-name>-test-files/ 目录中。这样可以保持 skill 源码目录整洁，并保留运行历史以便进行差异和回归比较。

skills/
├── huawei-cloud-rds-query/                  ← skill source (untouched)
└── huawei-cloud-rds-query-test-files/       ← test artifacts (created on first run, kept across runs)
    ├── phases/
    │   ├── phase-0-summary.json
    │   ├── phase-1-summary.json
    │   ├── ...
    │   └── phase-7-summary.json
    └── reports/
        ├── report-20260724-152309/          ← one subdir per run (timestamped)
        │   ├── test-report.json
        │   └── test-report.md
        ├── report-20260725-090000/
        │   ├── test-report.json
        │   └── test-report.md
        └── ...

• Phase 0~6 将 phase-N-summary.json 输出到 <skill-name>-test-files/phases/
• Phase 7 将它们合并到 <skill-name>-test-files/reports/report-<timestamp>/test-report.{json,md}
• 测试产物会在多次运行间保留（绝不自动清理）。--fresh 不会删除文件，而是将旧的 phases/*.json 归档到 phases/archive/<timestamp>/，以重置链式检查，同时保留历史记录。reports/ 始终保留。
• 退出时仍会卸载 $SKILL_INSTALL_DIR/ 中测试安装的 skill 副本，因此下一次运行时安装状态是干净的。

JSON schema 见 references/output-schema-spec.md。Phase 5 和 6 还会输出包含真实 CLI/SDK 响应的场景执行日志，以便审计。

最佳实践

• 进入 Tier 2 前完成 Tier 1，确保各个 skill 单独运行正常后再进行编排
• 在 Phase 4 和 Phase 5/6 中逐一确认写操作；不要批量确认，以免误操作
• 只有 1 个 skill 时，Phase 5/6 会自动降级为单 skill 闭环；无需手动跳过
• 使用 --fresh 重置并重新运行时，确认不存在未清理的测试资源
• 执行前检查编排场景，确保资源依赖顺序正确

注意事项

• 三轨八阶段必须严格按顺序执行；链式验证可防止跳过阶段
• 严禁推断 API 端点；只能从 SDK _http_info 或 API Explorer 获取
• 凭证从环境变量读取；严禁硬编码
• 如果缺少 AK/SK，框架会将环境变量设置模板输出到 stderr，并以状态码 77 退出。Agent 必须将该模板原样输出给用户，并指示用户在聊天之外的环境中设置环境变量（在 shell / PowerShell $PROFILE 中）。Agent 绝不能要求用户在聊天中输入或粘贴 AK/SK。严禁静默跳过任何需要凭证的步骤。（完整协议见：references/agent-protocol.md）
• 必须跟踪测试期间创建的资源；如果有任何资源未清理，输出手动清理说明
• 编排场景会自动生成；执行前应由用户检查并确认
• 编排场景中的写操作需要用户逐步确认

边缘情况

场景	处理方式
技能目录不存在	报告错误并终止，输出可用技能列表
未设置 AK/SK 环境变量	框架会将环境变量设置模板（包含 export HUAWEICLOUD_SDK_AK=<your-access-key-id> / $env:HUAWEICLOUD_SDK_AK=<...> 占位符片段）输出到 stderr，并以代码 77 退出。Agent（或终端调用方）必须向用户输出该模板，并告知用户在 shell 配置文件 / PowerShell $PROFILE 中通过外部方式设置环境变量，然后重新运行。绝不要要求用户在聊天中输入或粘贴 AK/SK。严禁静默跳过。
用户指定了技能名称，但该技能未安装在 Hermes 中	--fresh 会执行目录级检测；如果未找到，则报告错误并提供指导
某些 Phase JSON 文件已删除	链式检测 → 从已删除的 Phase 重新开始
Phase 4 执行期间网络中断	已执行的用例结果不会丢失；重新运行时，通过 --phase 标记跳过已通过的用例
用户在执行过程中按下 Ctrl+C	已输出的阶段 JSON 有效；下次运行时，--resume 会从当前阶段恢复
仅测试 1 个技能	Phase 5 → downgraded_self_check（单技能触发歧义扫描）；Phase 6 → downgraded_single_skill_flow（实际执行）
用户对推导出的编排场景不满意	手动编辑推导出的场景或跳过它；Phase 5 的推导仅生成元数据，不会执行
Phase 4 写操作未设置 ALLOW_WRITES=1	跳过，状态为 status=skip，不记录 resource_changes
Phase 4 缺少业务参数（例如 coupon_id）	标记为 status=warn，并在报告中列为 manual_test_items；用户必须提供真实数据并重试
跨技能数据流不匹配	在 Phase 5 中记录为 data_flow_tests 候选项；不会自动执行
E2E 流程后检测到孤立资源	在 phase-6-summary.json 的 cleanup.manual_required 下列出，并提供具体清理命令

Agent 协议 — 凭据请求

当 Phase 4 或 Phase 6 需要调用华为云实时 API，但无法在环境中找到凭据时，框架不会静默跳过。它会发出结构化请求（向 stderr 输出哨兵行 __HUAWEI_SKILL_TESTER_CRED_REQUEST_v1__），并以代码 77 退出，强制调用方 Agent 向用户说明这一需求。

核心规则（必须遵守）：

1. 遇到退出代码 77 或哨兵标记时 → 暂停流水线；不要跳过 Phase 5/7
2. 将 stderr 中的环境变量设置模板原样输出给用户；指导用户通过外部方式在 shell 配置文件 / PowerShell $PROFILE 中配置（占位符 <your-access-key-id> / <your-secret-access-key>）
3. 绝不要在对话中要求用户提供明文 AK/SK（ask_user / read -p / 剪贴板往返 / 读取 ~/.hcloud/config.json 等路径）
4. 通过外部方式完成设置后，重新运行失败的阶段；如果用户拒绝，则明确标记“实时阶段已跳过 — 无凭据”，绝不要标记为通过

完整协议（6 步响应流程、直接终端模式、行为示例）：references/agent-protocol.md。

设计原则

• 链式验证 — 每个阶段都会检查上一阶段的 JSON，以防跳过步骤
• Agent-proof — 写入操作必须由用户确认；不允许伪造确认
• 数据驱动 — 所有阶段均以 JSON 格式输出；阶段 7 负责合并
• 可重复批量测试 — 可重复测试同一组技能；--fresh 用于重置
• 真实环境优先 — 所有编排和 E2E 流程都在真实的华为云环境中执行；不使用模拟
• 降级但不损失价值 — 单个技能不会运行空的编排阶段；而是降级为有意义的单技能生命周期测试
• 资源安全 — 必须跟踪测试期间创建的资源；若有资源残留，需输出明确的手动清理说明
• 凭据必不可少 — 如果缺少 AK/SK，框架会向 stderr 输出环境变量设置模板并以状态码 77 退出。Agent 必须向用户输出该模板，并指导用户通过其他方式设置环境变量。Agent 绝不能要求用户在聊天中输入或粘贴 AK/SK。严格禁止静默跳过任何需要凭据的步骤。