/byted-util-volcengine-cloud-detect

name: byted-util-volcengine-cloud-detect
description: Volcengine Cloud Detect (云拨测) API integration for creating detection tasks, retrieving results, generating reports, and managing detection nodes. Use when the user wants to (1) create network detection/dialing tasks (拨测任务), (2) check task results or generate detection reports, (3) list or search detection nodes (拨测节点), (4) manage existing tasks (list/stop/restart/delete). Triggers include natural language requests about website monitoring, network latency testing, HTTP detection, ping tests, DNS tests, node queries, or report generation for Volcengine cloud detect service.

Volcengine Cloud Detect

Interact with Volcengine Cloud Detect API (云拨测) through natural language. All API calls are handled via `scripts/volc_detect.py`. For detailed API parameters, read `references/api_docs.md`.

Prerequisites

Volcengine credentials are required:

• `VOLC_ACCESSKEY`: Access Key
• `VOLC_SECRETKEY`: Secret Key

Before executing any command, check whether both credentials exist in environment variables:

test -n "$VOLC_ACCESSKEY" && test -n "$VOLC_SECRETKEY"

If either value is missing, ask the user to provide the missing AK/SK, then write them to the current shell environment and persist them to the user's shell profile:

export VOLC_ACCESSKEY="USER_PROVIDED_ACCESS_KEY"
export VOLC_SECRETKEY="USER_PROVIDED_SECRET_KEY"

SHELL_PROFILE="${ZDOTDIR:-$HOME}/.zshrc"
grep -q '^export VOLC_ACCESSKEY=' "$SHELL_PROFILE" 2>/dev/null \
  && sed -i '' 's|^export VOLC_ACCESSKEY=.*|export VOLC_ACCESSKEY="USER_PROVIDED_ACCESS_KEY"|' "$SHELL_PROFILE" \
  || printf '\nexport VOLC_ACCESSKEY="USER_PROVIDED_ACCESS_KEY"\n' >> "$SHELL_PROFILE"
grep -q '^export VOLC_SECRETKEY=' "$SHELL_PROFILE" 2>/dev/null \
  && sed -i '' 's|^export VOLC_SECRETKEY=.*|export VOLC_SECRETKEY="USER_PROVIDED_SECRET_KEY"|' "$SHELL_PROFILE" \
  || printf 'export VOLC_SECRETKEY="USER_PROVIDED_SECRET_KEY"\n' >> "$SHELL_PROFILE"

Never run `scripts/volc_detect.py` until both `VOLC_ACCESSKEY` and `VOLC_SECRETKEY` are available.

Default Parameters for CreateTask

When user creates a task without specifying all parameters, use these defaults:

| Parameter | Default Value | Notes | |-----------|--------------|-------| | ProjectName | `default` | Always use unless user specifies | | Type | `1` (HTTP(S)) | Task type | | Name | `{current_time}_claw_detect` | Format: YYYYMMDD_HHMMSS_claw_detect | | Address | **(required)** | Must ask user if not provided | | NodeCount | `5` | Samples per line | | IntervalSeconds | `60` | Detection frequency | | FinishTime | `current_time + 90 seconds` | 1.5 minutes after creation | | LineIdList | **(required)** | Must obtain from ListNodes |

**Task Type Mapping**: 1=HTTP(S), 2=DNS, 3=PING, 5=UDP, 6=TCP, 8=Upload, 9=Download, 11=PageElement

**Interval Options** (seconds): 60, 120, 180, 300, 600, 900, 1200, 1800, 3600, 7200, 10800, 21600, 43200, 86400

Workflow: Creating a Detection Task

1. **Collect required info**: Ask user for `Address` (target URL). If not provided, prompt for it. 2. **Determine node selection**: Before creating task, ask user about detection requirements to filter nodes:

• Target region? (e.g., mainland China, specific provinces/cities)
• ISP preference? (e.g., China Telecom, China Mobile, China Unicom)
• Node type? (IDC = data center, LastMile = end user)

3. **Fetch and filter nodes**: Run `list-nodes`, then fuzzy-search based on user requirements. 4. **Confirm LineIdList**: Show matched nodes to user and confirm selection. 5. **Create task**: Run `create-task` with all parameters including confirmed LineIdList. 6. **Return TaskId**: Present the created task ID to user.

Node Selection Conversation Guide

When user says "create a detection task for baidu.com", respond by: 1. Confirming the target address 2. Asking about geographic/ISP requirements 3. Running `list-nodes` to show available options 4. Using `fuzzy-search-nodes` to filter based on user's description

Example user requirements to node filters:

• "mainland China + Telecom" → `--is-mainland true` + search "电信"
• "Beijing IDC nodes" → search "北京 IDC"
• "Shanghai and Guangzhou Mobile" → search "上海 移动" and "广州 移动"
• "all over the country" → `--is-mainland true`, select diverse nodes

Workflow: Getting Results & Reports

1. **Get task results**: Run `get-result` with TaskId and time range (must be <= 1 hour). 2. **Generate report**: Run `generate-report` to produce summary statistics. 3. **Present findings**: Show key metrics in a concise format.

Report Format

Present reports using this structure:

## Detection Report for {TaskName} (ID: {TaskId})

**Time Range**: {start} ~ {end}
**Total Samples**: {N}
**Success Rate**: {X}%

### Latency Statistics (ms)
| Metric | Value |
|--------|-------|
| Avg | {avg} |
| Min | {min} |
| Max | {max} |
| P90 | {p90} |

### Status Code Distribution
| Code | Count |
|------|-------|
| ... | ... |

### Issues
- {N} failures from {region-isp} nodes
- Top error: {error_code} ({count} occurrences)

Workflow: Managing Tasks

• **List tasks**: `list-tasks` with optional filters (--name, --address)
• **Stop task**: `stop-task --task-id ID`
• **Restart task**: `restart-task --task-id ID`
• **Delete task**: `delete-task --task-id ID` (confirm with user first)
• **Get task details**: `get-task --task-id ID`

Workflow: Node Discovery

• **List all nodes**: `list-nodes [--is-mainland true|false]`
• **Filter by type**: `list-nodes --line-types 1,2` (1=LastMile, 2=IDC)
• **Fuzzy search**: `fuzzy-search-nodes "search query"`

Script Commands Reference

All commands use `python scripts/volc_detect.py`:

# Create task
python scripts/volc_detect.py create-task \
  --address "https://example.com" \
  --name "task_name" \
  --type 1 \
  --node-count 5 \
  --interval-seconds 60 \
  --finish-time TIMESTAMP \
  --line-ids 228,229,230 \
  --http-method 1

# Get results
python scripts/volc_det