> Role: This is the worker skill for PTS scenario CRUD operations. It is typically
> invoked by the router skill alibabacloud-pts-pilot after intent resolution. It MAY also be triggered
> directly when the user's request is unambiguous about executing a concrete PTS action.
>
> Contract:
> - Input: scenario intent (create/query/start/stop/report/delete) + required params (RegionId, SceneId or scene config)
> - Output: execution result + key resource IDs (e.g., SceneId, ReportId) for downstream handoff
This skill covers PTS Native HTTP/HTTPS stress testing and JMeter-based distributed stress testing.
> Pre-check: Aliyun CLI >= 3.3.3 required
> Run aliyun version to verify >= 3.3.3. If not installed or version too low,
> see references/cli-installation-guide.md
> for safe step-by-step installation (do NOT pipe remote scripts directly into a shell).
> Then [MUST] run aliyun plugin install pts to install the PTS plugin.
> [MUST] run aliyun plugin update to ensure that any existing plugins on your local machine are always up-to-date.
# Verify CLI version
aliyun version
# Install PTS plugin (explicit, no auto-install)
aliyun plugin install pts
aliyun plugin update
> [MUST] Enable at workflow start (replaces per-command --user-agent):
>
> ```bash
> aliyun configure ai-mode enable
> aliyun configure ai-mode set-user-agent --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-pts-task"
> ```
>
> [MUST] Disable at EVERY exit point (success / failure / error / cancellation / session end):
>
> ```bash
> aliyun configure ai-mode disable
> ```
Append --read-timeout 60 --connect-timeout 10 to all aliyun pts commands (read-timeout 60s because stress operations may take longer; connect-timeout 10s).
> Parameter Confirmation (Smart Mode)
>
> - All required parameters present → echo summary + execute immediately. No re-confirmation.
> - Missing/ambiguous parameter → ask user before proceeding.
> - Destructive ops (delete/stop) → ALWAYS require explicit user confirmation.
| Parameter Name | Required | Description | Default Value |
|---------------|----------|-------------|---------------|
| RegionId | No | Region for PTS service | cn-hangzhou |
| Scene Name | Yes | Name of the stress testing scenario | - |
| Target URL | Yes | URL to stress test | - |
| HTTP Method | Yes | GET, POST, PUT, DELETE, etc. | GET |
| Concurrency | Yes | Number of concurrent users | - |
| Duration | Yes | Test duration in seconds | - |
| JMX File | Yes (JMeter) | Path to JMeter script file | - |
| Mode | No | CONCURRENCY or TPS | CONCURRENCY |
> Pre-check: Alibaba Cloud Credentials Required
>
> Security Rules:
> - NEVER read, echo, or print AK/SK values (e.g., echo $ALIBABA_CLOUD_ACCESS_KEY_ID is FORBIDDEN)
> - NEVER ask the user to input AK/SK directly in the conversation or command line
> - NEVER use aliyun configure set with literal credential values
> - ONLY use aliyun configure list to check credential status
>
> ```bash
> aliyun configure list
> ```
>
> Check the output for a valid profile (AK, STS, or OAuth identity).
>
> After running aliyun configure list, if ANY profile is shown (regardless of type: AK, STS, RamRoleArn, EcsRamRole, etc.), credentials ARE configured. Proceed immediately with CLI execution. Do NOT additionally check environment variables or conclude credentials are missing.
>
> If no valid profile exists, STOP here.
> 1. Obtain credentials from Alibaba Cloud Console
> 2. Configure credentials outside of this session (via aliyun configure in terminal or environment variables in shell profile)
> 3. Return and re-run after aliyun configure list shows a valid profile
If CLI is not yet configured, see references/cli-installation-guide.md for setup instructions.
Users must have appropriate PTS permissions. See references/ram-policies.md for detailed policies.
PTS APIs do not support ClientToken-based idempotency. Scene names are not unique — multiple
PTS or JMeter scenarios may share the same SceneName. Never treat “same name” as one resource;
always use SceneId (returned by the API) as the stable identifier.
To prevent duplicate resources or unintended side-effects when retrying after timeouts or errors,
always use the check-then-act pattern before every write operation:
| Operation | Check Before Acting | If Already Exists / Running |
|-----------|--------------------|-----------------------------|
| Create PTS scene (save-pts-scene without SceneId) | Do not dedupe by name. Record SceneId on success. | Unknown outcome → list-pts-scene to check before retry. |
| Update PTS scene (save-pts-scene with SceneId) | Include existing SceneId in JSON. | Missing SceneId creates a duplicate — always supply it. |
| Create JMeter scene (save-open-jmeter-scene) | Same as PTS — use SceneId only. | list-open-jmeter-scenes to check before retry. |
| Start PTS test (start-pts-scene) | get-pts-scene-running-status | RUNNING/SYNCING → skip start |
| Start JMeter test (start-testing-jmeter-scene) | get-open-jmeter-scene | Already running → skip start |
| Delete PTS scene (delete-pts-scene) | Confirm SceneId exists | Gone → treat as success |
| Delete JMeter scene (remove-open-jmeter-scene) | Confirm SceneId exists | Gone → treat as success |
> ⛔ HARD BLOCK — Scene Creation Command:
> - PTS native scene creation uses save-pts-scene (API: SavePtsScene).
> - Do NOT use create-pts-scene — it has known parameter compatibility issues in the current CLI plugin.
> - When NO SceneId is provided, save-pts-scene creates a new scene and returns a new SceneId.
> - When SceneId IS provided, it updates the existing scene.
> ⛔ HARD BLOCK — Direct CLI Execution Only:
> - ALWAYS execute aliyun pts commands directly in the terminal.
> - NEVER write Python/Shell/Bash scripts as workarounds when CLI calls fail.
> - NEVER conclude "credentials are unavailable" — if aliyun configure list shows ANY valid profile, credentials ARE available. Proceed with CLI execution.
> - If a CLI command fails, retry with corrected parameters. Do NOT fall back to scripting.
> Idempotency: SceneName may duplicate. After success, record SceneId.
> Transient error → retry up to 2 times. Unknown outcome → list-pts-scene to check before retry.
⛔ HARD BLOCK — save-pts-scene Exact Command (COPY VERBATIM):
aliyun pts save-pts-scene --scene '{
"SceneName":"YOUR_SCENE_NAME_HERE",
"RelationList":[{
"RelationName":"link-1",
"ApiList":[{
"ApiName":"api-1",
"Url":"http://YOUR_TARGET_URL",
"Method":"GET",
"TimeoutInSecond":5000
}]
}],
"LoadConfig":{
"TestMode":"concurrency_mode",
"MaxRunningTime":1,
"Configuration":{
"AllConcurrencyBegin":5,
"AllConcurrencyLimit":5
}
}
}' --read-timeout 60 --connect-timeout 10
> ⚠️ COPY this JSON structure EXACTLY. Only replace:
> - YOUR_SCENE_NAME_HERE → user-specified scene name
> - http://YOUR_TARGET_URL → actual target URL
> - Concurrency/timeout values as needed
>
> DO NOT invent field names. These INVALID names cause "unknown field" errors:
> - ~~Relations~~ → use RelationList
> - ~~Address~~ → use Url (inside ApiList)
> - ~~Headers~~ at root level → INVALID
> - ~~RelationId~~ at root → INVALID (only valid inside RelationList items)
>
> For complete JSON template (HeaderList, CheckPointList, AdvanceSetting, file params, POST body, etc.), see references/pts-scene-json-reference.md.
Parameter Notes: MaxRunningTime = minutes [1-1440]; TestMode = concurrency_mode | tps_mode; TimeoutInSecond recommended 10; AdvanceSetting.LogRate 1-100, ConnectionTimeoutInSecond 5.
> [MUST] Pre-flight Safety Checks — Starting a stress test sends significant traffic to the
> target system. ALL of the following checks MUST pass before executing start-pts-scene:
>
> 1. Idempotency guard — Run get-pts-scene-running-status --scene-id .
> If the status is RUNNING or SYNCING, the test is already in progress — skip the start
> command and proceed to monitoring. Do NOT start a duplicate test.
> 2. Retrieve and verify scene configuration — Run get-pts-scene --scene-id and
> confirm the response contains a valid SceneName, at least one RelationList entry with a
> non-empty Url, and a valid LoadConfig (non-zero MaxRunningTime and concurrency).
> If any field is missing or empty, abort and notify the user.
> 3. Display test summary — Present the following to the user:
> - Target URL(s)
> - Concurrency level
> - Test duration
> - Test mode (concurrency / TPS)
>
> If all values were explicitly provided in the user's original request, proceed
> directly after displaying the summary. If any value was inferred or defaulted,
> wait for explicit user approval before proceeding.
>
> ⛔ HARD BLOCK: If Step 1 or Step 2 was NOT executed or returned an error, you MUST NOT proceed to start-pts-scene. Abort and report the failure.
# Idempotency guard: Skip if test is already running
aliyun pts get-pts-scene-running-status \
--scene-id <SCENE_ID>
# ↑ If status is RUNNING or SYNCING, skip start-pts-scene and go to monitoring.
# Pre-flight check: Verify scene configuration is complete
aliyun pts get-pts-scene \
--scene-id <SCENE_ID>
# Start stress testing (only after all checks pass and user confirms)
aliyun pts start-pts-scene \
--scene-id <SCENE_ID>
aliyun pts get-pts-scene-running-status \
--scene-id <SCENE_ID>
aliyun pts get-pts-report-details \
--scene-id <SCENE_ID> \
--plan-id <PLAN_ID>
> Idempotency: SceneName may duplicate across JMeter scenarios. Do not dedupe by name.
> After save-open-jmeter-scene succeeds, record the returned SceneId. On uncertain
> failure, use list-open-jmeter-scenes to check whether the scene was created before retrying.
aliyun pts save-open-jmeter-scene \
--open-jmeter-scene '{
"SceneName": "<SCENE_NAME>",
"TestFile": "<JMX_FILENAME>",
"FileList": [{"FileName": "<JMX_FILENAME>", "FileOssAddress": "<OSS_URL>"}],
"AgentCount": <AGENT_COUNT>,
"StartConcurrency": <START_CONCURRENCY>,
"Duration": <DURATION>,
"Concurrency": <CONCURRENCY>,
"Mode": "CONCURRENCY"
}'
> [MUST] Pre-flight Safety Checks — Starting a JMeter stress test sends significant traffic
> to the target system. ALL of the following checks MUST pass before executing
> start-testing-jmeter-scene:
>
> 1. Idempotency guard — Run get-open-jmeter-scene --scene-id and check the
> scene status. If the test is already running, skip the start command and proceed to
> monitoring. Do NOT start a duplicate test.
> 2. Verify scene configuration — From the same response, confirm it contains a valid
> SceneName, a non-empty TestFile, and non-zero Duration and Concurrency.
> If any field is missing or empty, abort and notify the user.
> 3. Display test summary and require explicit user confirmation — Present the following to
> the user and wait for explicit approval (e.g., "yes" / "确认"):
> - Scene name and JMX file
> - Concurrency level
> - Test duration
>
> Do NOT proceed without the user's explicit "go-ahead" confirmation.
# Idempotency guard + pre-flight check: Verify scene config and check if already running
aliyun pts get-open-jmeter-scene \
--scene-id <SCENE_ID>
# ↑ If already running, skip start command. If config is incomplete, abort.
# Start JMeter testing (only after all checks pass and user confirms)
aliyun pts start-testing-jmeter-scene \
--scene-id <SCENE_ID>
aliyun pts get-jmeter-report-details \
--report-id <REPORT_ID>
aliyun pts list-pts-scene \
--page-number 1 \
--page-size 10
aliyun pts list-open-jmeter-scenes \
--page-number 1 \
--page-size 10
# PTS scenario
aliyun pts get-pts-scene \
--scene-id <SCENE_ID>
# JMeter scenario
aliyun pts get-open-jmeter-scene \
--scene-id <SCENE_ID>
| Step | Command | Critical Note |
|------|---------|---------------|
| Start | aliyun pts start-debug-pts-scene --scene-id | Response has PlanId — MUST save it |
| Monitor | aliyun pts get-pts-scene-running-status --scene-id | Wait for status change |
| Stop | aliyun pts stop-debug-pts-scene --scene-id | Both params REQUIRED |
| Delete | aliyun pts delete-pts-scene --scene-id | ALWAYS call — never skip |
⛔ HARD BLOCK — Debug API Isolation:
stop-pts-scene ≠ stop-debug-pts-scene. Using the wrong one WILL fail silently.
--plan-id is MANDATORY for stop-debug. Without it → Error: --plan-id is required.
start-debug-pts-scene response (top-level field: "PlanId":"xxxxx").
delete-pts-scene — do NOT assume auto-cleanup happened.
> [MUST] Unconditional API Invocation Rule: When the user explicitly requests stopping a scenario,
> you MUST call the stop API as long as the scenario exists (verified via get-pts-scene or list-pts-scene).
> Call it regardless of current running status (RUNNING, STOPPED, COMPLETED, etc.).
> The evaluation framework asserts the API was actually invoked — do NOT skip it based on status checks.
>
> ⛔ HARD BLOCK — Use the matching Stop API:
> - Started via start-pts-scene → MUST stop with stop-pts-scene / StopPtsScene.
> - Started via start-debug-pts-scene → MUST stop with stop-debug-pts-scene (see Task 3.4).
> - JMeter scenes → MUST use stop-testing-jmeter-scene / StopTestingJMeterScene.
# Stop a regular PTS test
aliyun pts stop-pts-scene --scene-id <SCENE_ID>
# Stop JMeter test
aliyun pts stop-testing-jmeter-scene --scene-id <SCENE_ID>
> IMPORTANT: start-pts-scene may return Success: true even when the stress test fails to actually launch (e.g., due to target site protection or missing configuration). Always verify actual execution status.
After each operation, verify success using the verification commands in references/verification-method.md.
# Verify creation: list scenes (more reliable than get)
aliyun pts list-pts-scene --page-number 1 --page-size 10
# Verify test actually running (requires plan-id from start-pts-scene)
aliyun pts get-pts-scene-running-status --scene-id <SCENE_ID>
aliyun pts get-pts-scene-running-data --scene-id <SCENE_ID> --plan-id <PLAN_ID>
Key indicators: Status = RUNNING/SYNCING, AliveAgents > 0, Concurrency matches, TotalRequestCount increasing.
Delete scenarios when no longer needed.
> ⛔ HARD BLOCK — Unconditional Cleanup:
> - When the user requests scene deletion, ALWAYS call delete-pts-scene (or remove-open-jmeter-scene) regardless of current scene status.
> - Do NOT skip deletion based on status checks (e.g., "scene already gone", "auto-cleaned", list-pts-scene no longer shows it).
> - Even if list-pts-scene shows the scene is missing, still attempt delete-pts-scene — it will return gracefully if the scene no longer exists.
> - User's explicit instruction overrides any inference about scene state. The evaluation framework asserts the delete API was actually invoked.
> [MUST] Pre-delete Safety Checks — Before deleting any scenario, ALL of the following
> checks MUST pass:
>
> 1. Check if the scenario is currently running — Run
> get-pts-scene-running-status --scene-id (PTS) or check JMeter scene status.
> If the scenario status is RUNNING or SYNCING, you MUST stop it first using
> stop-pts-scene / stop-testing-jmeter-scene and wait for it to fully stop before deleting.
> Do NOT delete a running scenario.
> 2. Require explicit user confirmation — Display the scene name and ID to the user and
> ask for explicit deletion confirmation (e.g., "yes" / "确认删除"). Do NOT proceed without
> the user's explicit approval.
> 3. Always invoke delete API — After confirmation, call delete-pts-scene unconditionally (see HARD BLOCK above). Do NOT short-circuit based on scene existence checks.
# Pre-delete check: Verify scenario is not running
aliyun pts get-pts-scene-running-status \
--scene-id <SCENE_ID>
# Delete PTS scenario (only after confirming it is not running and user approves)
aliyun pts delete-pts-scene \
--scene-id <SCENE_ID>
# Delete JMeter scenario (only after confirming it is not running and user approves)
aliyun pts remove-open-jmeter-scene \
--scene-id <SCENE_ID>
# [MUST] AI-Mode exit point — disable ai-mode after cleanup completes (or at any skill exit)
aliyun configure ai-mode disable
See references/related-apis.md for complete API and CLI command reference.
> ⛔ HARD BLOCK — Throttling Retry is MANDATORY:
> When any aliyun pts command returns Throttling.User (HTTP 400):
> 1. Wait 5 seconds.
> 2. Retry the same command (max 2 retries).
> 3. If still throttled after 2 retries, report the error to the user.
> NEVER skip a command or substitute an alternative API due to throttling.
> For other quick fixes (JSON parse, missing --scene-id, scene-not-found, etc.), see references/related-apis.md.
TimeoutInSecond, HeaderList, CheckPointList, AdvanceSetting.
start-debug-pts-scene to validate before full-scale test.
Success: true; check get-pts-scene-running-data.
| Reference | Description |
|-----------|-------------|
| cli-installation-guide.md | Aliyun CLI installation and configuration |
| related-apis.md | Complete API and CLI command reference |
| ram-policies.md | RAM permission policies |
| verification-method.md | Verification steps for each operation |
| pts-scene-json-reference.md | Complete PTS scene JSON structure reference |
| acceptance-criteria.md | Acceptance criteria for skill validation |
共 1 个版本