# Byted Util Volcengine Cloud Detect

> 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.

- Skill: `bytedance/byted-util-volcengine-cloud-detect` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add bytedance/byted-util-volcengine-cloud-detect`
- Raw SKILL.md: https://api.skillmd.com/api/skills/bytedance/byted-util-volcengine-cloud-detect/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: bytedance (https://skillmd.com/u/bytedance)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/bytedance/byted-util-volcengine-cloud-detect

---


# 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:

```bash
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:

```bash
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`:

```bash
# 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_detect.py get-result \
  --task-id 12345 \
  --start-time 1672531200 \
  --end-time 1672534800 \
  --page-size 500

# List nodes
python scripts/volc_detect.py list-nodes --is-mainland true

# Fuzzy search nodes
python scripts/volc_detect.py fuzzy-search-nodes "北京 电信 IDC"

# Generate report
python scripts/volc_detect.py generate-report \
  --task-id 12345 \
  --start-time 1672531200 \
  --end-time 1672534800

# Task management
python scripts/volc_detect.py list-tasks --page-size 20
python scripts/volc_detect.py stop-task --task-id 12345
python scripts/volc_detect.py restart-task --task-id 12345
python scripts/volc_detect.py delete-task --task-id 12345
python scripts/volc_detect.py get-task --task-id 12345
```

## Key API Notes

- **Time constraints**: GetTaskResult time range must be <= 1 hour
- **Page size limit**: GetTaskResult max PageSize is 500
- **Node naming format**: `国家-省份-城市-运营商（类型）`, e.g., `中国-北京-北京市-中国电信（IDC）`
- **Task status**: 2=Running, 4=Paused, 6=Ended
- **Project scoping**: All task-scoped commands (`create-task`, `get-result`, `get-task`, `list-tasks`, `stop-task`, `restart-task`, `delete-task`, `generate-report`, `list-nodes`) accept an optional `--project-name`. `create-task` defaults to `default`; the others default to the account's default project when omitted.

## Resources

- **scripts/volc_detect.py**: Complete API client with auth, all API operations, fuzzy search, and report generation
- **references/api_docs.md**: Detailed API parameter reference for all 8 endpoints