byted-util-volcengine-cloud-detect

Files (4)

• SKILL.md
• api_docs.md · references/
• api_reference.md · references/
• volc_detect.py · scripts/

SKILL.md (first lines)

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

From bytedance/agentkit-samples, Apache-2.0.

More from bytedance/agentkit-samples