volcengine-tls — скилл для Claude Code: установка и работа
Скилл для Claude Code помогает агенту выполнять операции с Volcengine TLS через volclog. Он включается для поиска и анализа логов, а также работы с проектами и темами логов.
Apache-2.0 118 установок ★ 37 обновлён 2026-11-16
npx skills add volcengine/volcengine-agent-toolkit --skill volcengine-tls -a claude-codeЧто делает volcengine-tls
Скилл задаёт порядок работы с volclog: сначала агент выясняет доступные команды и читает их описание, затем запускает операцию со структурированным JSON-вводом и разбирает ответ. Для запросов к публичным API используется tool, для сценариев, которыми управляет CLI, — workflow; raw подходит, когда метод и путь уже известны.
Перед запуском нужен ve версии 1.1.11 или выше. Скилл помогает выбрать профиль, файл секретов или учётные данные из окружения, но запрещает выводить значения ключей и токенов. При записи или разрушительном изменении предлагается сначала выполнить --dry-run; после неоднозначного результата рискованной операции повторный запуск не считается безопасным.
Какие задачи решает
- найти команду для поиска логов
- проверить поля запроса перед запуском операции
- разобрать статус и данные в ответе
volclog - восстановить работу после ошибки операции
Примеры запросов агенту
- Найди логи ошибок в проекте Volcengine TLS за указанный период.
- Покажи, какие поля нужны для запроса к теме логов.
- Проверь план изменения настроек логирования перед записью.
Как установить volcengine-tls
1Через Skills CLI (Vercel)
npx skills add volcengine/volcengine-agent-toolkit --skill volcengine-tls -a claude-code2Вручную: положить файлы
~/.claude/skills/volcengine-tls/SKILL.mdПапка скилла целиком; для одного проекта — .claude/skills/volcengine-tls/
1Через Skills CLI (Vercel)
npx skills add volcengine/volcengine-agent-toolkit --skill volcengine-tls -a codex2Вручную: положить файлы
.agents/skills/volcengine-tls/SKILL.mdДля всех проектов — ~/.agents/skills/
1Через Skills CLI (Vercel)
npx skills add volcengine/volcengine-agent-toolkit --skill volcengine-tls -a cursor2Вручную: положить файлы
.cursor/skills/volcengine-tls/SKILL.mdCursor читает и .agents/skills/, и .claude/skills/
1GitHub CLI
gh skill install volcengine/volcengine-agent-toolkit plugins/volcengine-storage/skills/volcengine-tls2Вручную: положить файлы
.github/skills/volcengine-tls/SKILL.md1Через Skills CLI (Vercel)
npx skills add volcengine/volcengine-agent-toolkit --skill volcengine-tls -a gemini-cli2Командой платформы
gemini skills install https://github.com/volcengine/volcengine-agent-toolkit --path plugins/volcengine-storage/skills/volcengine-tlsВручную: положить файлы
.devin/skills/volcengine-tls/SKILL.mdСтарый путь .windsurf/skills/ тоже читается
Через Skills CLI (Vercel)
npx skills add volcengine/volcengine-agent-toolkit --skill volcengine-tls -a opencodeClaude.ai
Упакуйте папку в zip и загрузите в Settings → Capabilities → Skills
По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов
Вопросы о volcengine-tls
Как установить volcengine-tls в Claude Code?
Выполни npx skills add volcengine/volcengine-agent-toolkit --skill volcengine-tls -a claude-code. Файл скилла появится по пути ~/.claude/skills/volcengine-tls/SKILL.md.
Что делает volcengine-tls?
Скилл задаёт последовательность поиска и описания операций volclog, их запуска и чтения результата. Он также описывает выбор учётных данных и действия после ошибки.
Что нужно для работы volcengine-tls?
Нужен ve версии 1.1.11 или выше. Для доступа CLI использует профиль, файл секретов или учётные данные из переменных окружения.
Исходный текст
SKILL.md · Apache-2.0
---
name: volcengine-tls
description: >-
Use when operating Volcengine TLS (日志服务) through volclog in agent or CI sessions and you
need a contract-first workflow for runtime selector resolution, discover/describe/exec routing, App
resource or Topic resolution, envelope reading, large-result delivery, and error recovery without
guessing commands, fields, or shortcut flows. 当用户提到火山引擎日志服务 TLS、volclog、日志检索/分析/导入/导出、
日志项目或日志主题等操作时调用。
license: Apache-2.0
metadata:
openclaw:
emoji: "🪵"
homepage: "https://github.com/volcengine-tls/ve-tls-cli"
requires:
bins:
- ve
install:
- kind: node
package: "@volcengine/cli"
bins: [ve]
---
# Volcengine TLS (volclog)
> Adapted from [`volclog-core`](https://github.com/volcengine-tls/ve-tls-cli/tree/b451c506f24573dc0e71220e7ad15339ed7f04e4/skills/volclog-core) in `volcengine-tls/ve-tls-cli` (Apache-2.0). Command examples keep the upstream native `volclog ...` form; run them as `ve volclog ...` (requires `ve >= 1.1.11`) with all later arguments unchanged.
## Overview
Use this skill only for agent-only incremental knowledge.
Treat this file as the dominant generic operating model for `volclog`, not as an environment-specific bootstrap note and not as an API reference. This file is the behavior summary; references are the authoritative detail. If `volclog tool describe ...` or `volclog workflow describe ...` already answers the question, stop and follow that contract instead of adding duplicate guidance here.
## Operating Stance
- Treat `tool describe` or `workflow describe` as the contract truth source. Read `tool describe` or `workflow describe` first.
- Treat profile configuration as a runtime-selector problem, not a region-discovery ritual.
- Think in runtime selectors: active profile, explicit `--profile <name>`, one-shot `--secrets-file`, `context.secrets_file`, or process-scoped environment credentials.
- Use `tool` for published public APIs, `workflow` for CLI-owned orchestration, and `raw` only when method/path is already known.
- Keep one-call App, LogApp, Trace, and TraceScore capabilities on `tool`; use `workflow app.resolve-resources` or `app.resolve-topic-ids` only for CLI-owned cross-call expansion.
- Prefer structured JSON input such as `--input '{...}'` when `tool exec` or `workflow exec` already supports it.
## Runtime Selector Model
- Treat the execution environment as unknown until the available runtime selectors are confirmed.
- Do not assume the active or default profile is the right selector for the task.
- Run `volclog configure list` only when local profile discovery is actually relevant.
- Use `region` only when the contract or task explicitly requires an override. Do not infer it from endpoint or domain.
- `--profile`/`context.profile` and `--secrets-file`/`context.secrets_file` are runtime selectors, not business input fields.
- Never read, print, export, or persist AK/SK or token values in prompts, memory, request artifacts, or skill content.
## Canonical Agent Loop
Discover -> Describe -> Exec -> Read Result
1. Resolve runtime selectors.
- decide whether this run is using profile, secrets file, or environment credentials
- if local profile discovery matters, run `volclog configure list`
- keep the chosen selector explicit in the command or context
2. Discover the callable surface.
- `volclog tool list`
- `volclog tool list <group>`
- `volclog workflow list <group>`
3. Read the contract.
- `volclog tool describe <group.action>`
- use `volclog tool describe <group.action> --view full` when authoring a nested request or when compact output omits an expected optional field
- treat compact view as the discovery summary and full view as the request-authoring contract
- `volclog workflow describe <group.command>`
4. Execute with structured input.
- `volclog tool exec <group.action> --input '{...}'`
- `volclog workflow exec <group.command> --input '{...}'`
- `volclog raw --method <METHOD> --path <PATH> --body '{...}'`
5. Read result in this order.
- `status` (`"success"` or `"failed"`)
- `summary.deliveryMode`
- the flat `error` object (when `status` is `"failed"`)
- business fields under `data` (when `status` is `"success"`)
## Reference Escalation
- Do not read every reference file by default.
- Read `tool describe` or `workflow describe` first.
- Read [references/routing.md](references/routing.md) only when the surface is still unclear after describe or list.
- Read [references/sops.md](references/sops.md) only when the task clearly spans multiple calls and you need stop conditions.
- Read [references/best-practices.md](references/best-practices.md) only when runtime semantics, delivery mode, or recovery posture are still unclear after the contract is known.
- `contract_cache_hint` and `contract_digest` come from `tool describe` or `workflow describe` output. Read `contract_cache_hint.safe_scope` and `contract_cache_hint.refresh_when`, and reuse cached results only while the same CLI build still reports the same `contract_digest`.
- Stop after one reference resolves the current uncertainty; do not keep browsing all references “just in case”.
## Key Rules
- Do not guess command names, tool ids, workflow ids, JSON fields, or output shape.
- If the action id is still unknown, run `volclog tool list <group>` or `volclog workflow list <group>` before guessing.
- Let the operation's `risk`, `recovery`, and `usage_constraints` override the generic recovery map below.
- Treat `high-risk-retry` as a warning that retrying is high risk. After an ambiguous result, reconcile only through a get/describe/list action named by the contract; otherwise stop and escalate instead of retrying automatically.
- Do not use human shortcut commands as the primary agent flow.
- Do not repeat schema details that already exist in `tool describe` or `workflow describe`.
- Do not rebuild a valid `tool exec` or `workflow exec` request into flag-heavy shortcut form just because the shell path looks shorter.
- Do not pipe `volclog` output into `jq` or `grep` just to rediscover schema or field paths.
- Read the full JSON envelope first; use `--jmes-filter` only when you already know the envelope path you want.
- Prefer `--dry-run` before any write or destructive change, but only on `raw`, `tool exec`, or `workflow exec`.
- Treat `--dry-run` as contract or plan validation, not proof that the business query is correct.
- If fields are uniquely named, prefer flat JSON input before manual nesting.
## Error Recovery Quick Map
Use this table as the default first response after a failed envelope only after reading the operation's `risk`, `recovery`, and `usage_constraints`. The operation contract takes precedence. Read `references/best-practices.md` only when you need runtime-specific detail beyond the quick action below.
| Signal | Next action |
| --- | --- |
| `error.kind=validation` | Go back to `describe` and fix shape or selector problems first. |
| `error.kind=auth` or `401` | Re-check runtime selector, then credentials, then endpoint or region override. |
| `403 Forbidden` | Re-check tenant or profile alignment before widening the permission search. |
| `error.kind=usage` | Re-run `tool list` or `workflow list`; do not invent aliases. |
| `error.kind=unsupported_feature` | Read `error.hint`, then remove the unsupported flag or switch to the named surface; non-LogApp Topic resolution should switch to `app.resolve-resources`. |
| `error.kind=incompatible_flags` | Remove one conflicting flag and rerun. |
| `error.kind=filesystem` | Fix `--output-dir`, local path, or permissions before retrying. |
| `error.kind=decode` | Read `error.hint`, remove the wrong filter or projection if present, then rerun unfiltered or with `--trace-dir`. |
| `error.kind=server` | Read `error.code` and `error.requestId`; retry with backoff only when the operation contract permits it and the failure is clearly transient. |
| `error.kind=config` | Run `volclog doctor` for host-side configuration checks, then inspect the reported runtime issue. |
| `error.kind=unknown` | Read `error.hint` first, then `error.message` or `error.details`, and rerun with `--dry-run` or `--trace-dir` only if more detail is still needed. |
| `ResultStatus=incomplete` | Narrow the time window and rerun before trusting counts or emptiness. |
`volclog doctor` checks host/runtime configuration such as credentials, endpoint, and local setup. It does not replace `describe`, and it does not validate business query semantics.
## Large Result Handling
- Keep surface choice and delivery choice separate.
- When a result may be large, provide a writable `--output-dir`.
- Let `summary.deliveryMode` tell you what actually happened at runtime.
- Read [references/best-practices.md](references/best-practices.md) for exact `outputMode`, `deliveryMode`, file delivery, and `--jmes-filter` semantics instead of duplicating them here.
## Quick Map
| Need | Prefer |
| --- | --- |
| Public API contract already chosen | `volclog tool describe <group.action>` / `volclog tool exec <group.action>` |
| CLI workflow already chosen | `volclog workflow describe <group.command>` / `volclog workflow exec <group.command>` |
| Need to discover action or workflow ids | `volclog tool list <group>` / `volclog workflow list <group>` |
| Need help choosing the surface | read `references/routing.md` |
| Need multi-step execution order | read `references/sops.md` |
| Resolve an App resource graph | `volclog workflow describe app.resolve-resources` / `volclog workflow exec app.resolve-resources` |
| Resolve Topic IDs for a LogApp App | `volclog workflow describe app.resolve-topic-ids` / `volclog workflow exec app.resolve-topic-ids` |
| Need runtime/error/recovery semantics | read `references/best-practices.md` |
| Use an exact method/path | `volclog raw --method ... --path ...` |
| Authenticate a stateless run | host-selected local profile -> one-shot `--secrets-file` or `context.secrets_file` |
| Need contract reuse safety | reuse cached results only while the same CLI build still reports the same `contract_digest` |
© volcengine · Apache-2.0 · volcengine/volcengine-agent-toolkit