volcengine-tls

Volcengine TLS (volclog)

Adapted from 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 , 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
   • volclog workflow list
3. Read the contract.
   • volclog tool describe
   • use volclog tool describe --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
4. Execute with structured input.
   • volclog tool exec --input '{...}'
   • volclog workflow exec --input '{...}'
   • volclog raw --method --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 only when the surface is still unclear after describe or list.
• Read references/sops.md only when the task clearly spans multiple calls and you need stop conditions.
• Read 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 or volclog workflow list 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.

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 for exact outputMode, deliveryMode, file delivery, and --jmes-filter semantics instead of duplicating them here.

Quick Map