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