SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsvolcengine-knowledge-search

volcengine-knowledge-search

Writing & research

View repository

Updated 10-16 02:56

About this skill

volcengine-knowledge-search Volcengine documentation search

Search official documentation via ve docs search and retrieve the body text via ve docs fetch . Request and response parsing, body text cleaning, and pagination are handled by the CLI; this skill is responsible for scenario judgment, query rewriting, secondary searches, and source citation.

CLI invocation conventions

Before executing ve , follow the volcengine-cli of caller identification rules. Every invocation must carry in the process environment:

  • VE_CALLER_TYPE=ai_agent。
  • VE_CALLER_NAME: determined by the Agent based on the current actual host environment; do not use a fixed default value.
  • VE_SKILL_NAME: take the frontmatter nameof the skill currently performing the operation. When this skill performs documentation search or body text retrieval, this value is volcengine-knowledge-search; citing the CLI's invocation rules does not change the skill to which the operation belongs.

This requirement covers --help checks, the first search, rewritten searches, body text retrieval, pagination continuation, and retries. Each tool invocation may start a new shell, so the three variables must be passed again and must not rely on the previous export. In the example below, <agent-id> and <current-volcengine-skill> are both replaced by the Agent based on the current environment and skill metadata and must not be passed in as-is. These variables are only used to identify the invocation source and do not change the convention that public documentation commands require no login.

Preparation

On first use, confirm that the local machine has the two subcommands:

VE_CALLER_TYPE=ai_agent VE_CALLER_NAME="<agent-id>" VE_SKILL_NAME="<current-volcengine-skill>" \
  ve docs search --help
VE_CALLER_TYPE=ai_agent VE_CALLER_NAME="<agent-id>" VE_SKILL_NAME="<current-volcengine-skill>" \
  ve docs fetch --help

If ve is not installed or lacks subcommands, load the volcengine-cli skill, install the latest version according to its "Install or upgrade the ve CLI" section, and then check the capabilities. Documentation commands access public services,with no need for login, AK/SK, profile, or region configuration; use them directly after installation, with no need to perform the identity initialization process for resource management.

Choose a flow

  1. The user provides a specific article link: directly fetch, read the body text relevant to the question.
  2. The user asks a question: after completing the product name and specific direction, search, with no product filter on the first search. Judge relevance based on the title, summary, and product code.
  3. Results are too broad or irrelevant: rewrite the query; only when the results already confirm the target product's ServiceCodes may you use that code for a secondary search. Do not use the codes of unrelated hits as filter conditions.
  4. Need complete steps, constraints, precise billing rules, or a full-text summary: run fetchon the URL of relevant results, continue reading as needed; when the user requests the full text, read until there is no continuation prompt or has_more=false。

search: search documentation

VE_CALLER_TYPE=ai_agent VE_CALLER_NAME="<agent-id>" VE_SKILL_NAME="<current-volcengine-skill>" \
  ve docs search "对象存储 TOS 如何计费" --limit 3 --output text

The search text is apositional argument, enclose the complete question in quotes. Use --output text to get directly readable Markdown: each entry includes the title, a clean URL,ServiceCodes and the body text summary. The CLI outputs JSON by default; when programmatic processing is needed, explicitly use --output json, and the results are in the documents array with fields title、url、service_codes、snippet。

Parameter Purpose
--limit N Number of documents to return, a positive integer; generally take 3 entries first
--service-code CODE Specified product, with the code taken from confirmed relevant results; repeat this option for multiple products
--snippet-length N Maximum number of Unicode characters per summary, a positive integer; use it to control context size

Rewrite the query

Semantic search needs to stay close to the document wording. Expand colloquial terms, abbreviations, or marketing names intofull product name + capability description + specific question, for example rewrite "How much does Coding Plan cost" as "How is the Volcano Ark Coding Plan AI programming subscription package billed". If the first search goes off track, switch to the full name, a synonymous description, or a functional description and search again.

VE_CALLER_TYPE=ai_agent VE_CALLER_NAME="<agent-id>" VE_SKILL_NAME="<current-volcengine-skill>" \
  ve docs search "火山方舟 Coding Plan AI 编程订阅套餐如何计费" --limit 3 --output text

Search broadly first, and after confirming that the ServiceCodes of relevant results is tos , search precisely by product:

VE_CALLER_TYPE=ai_agent VE_CALLER_NAME="<agent-id>" VE_SKILL_NAME="<current-volcengine-skill>" \
  ve docs search "跨区域复制如何配置" --limit 5 --snippet-length 300 --output text
VE_CALLER_TYPE=ai_agent VE_CALLER_NAME="<agent-id>" VE_SKILL_NAME="<current-volcengine-skill>" \
  ve docs search "对象存储 TOS 跨区域复制如何配置" --limit 3 --service-code tos --output text

For multiple product codes, use --service-code <code-a> --service-code <code-b>, passing each code separately.

fetch: retrieve the body text

Supports https://www.volcengine.com/docs/... and https://docs.volcengine.com/docs/.... The CLI removes the URL's query and fragment, and the text output is, in order, the title, the clean URL, the current page body text, and a continuation hint.

VE_CALLER_TYPE=ai_agent VE_CALLER_NAME="<agent-id>" VE_SKILL_NAME="<current-volcengine-skill>" \
  ve docs fetch "https://www.volcengine.com/docs/6349/162514?lang=zh" --output text
Parameter Purpose
--start-index N Start from the Nth Unicode character, with the index starting at 0
--max-length N Maximum number of Unicode characters returned for the current page, a positive integer; default 5000

At the end of a long document, the next page's --start-indexis indicated. Usethe same URL and the returned indexto continue reading, avoiding missed or repeated content. The following example first retrieves 300 characters; if the continuation hint is --start-index 300, then read the next page:

VE_CALLER_TYPE=ai_agent VE_CALLER_NAME="<agent-id>" VE_SKILL_NAME="<current-volcengine-skill>" \
  ve docs fetch "https://www.volcengine.com/docs/6349/162514" --max-length 300 --output text
VE_CALLER_TYPE=ai_agent VE_CALLER_NAME="<agent-id>" VE_SKILL_NAME="<current-volcengine-skill>" \
  ve docs fetch "https://www.volcengine.com/docs/6349/162514" --start-index 300 --max-length 300 --output text

For programmatic pagination, use --output json, and when reading content、start_index、next_start_index、remaining_characters、has_more and has_content。has_more=true , use next_start_index to continue reading; when finished, this field is null。

Navigation pages and empty body text

  • /docs/{产品编号}/{文档ID} is a specific article path.
  • /docs/{产品编号} is a product documentation navigation page and has no single article body text. When such a link is detected, by product name and the direction the user cares about search, locate the specific article from the results, then fetch, and explain the link type to the user.
  • has_content=false indicates that no body text was obtained, and content must not be fabricated based on it. Check whether the link is a navigation page, expired, or an incorrect address, then use search to locate an alternative document.

Results and error handling

  • Answer based on evidence: conceptual questions that the summary sufficiently supports can be answered directly; for precise rules and complete steps, retrieve the body text first. Some pages cannot be described as having been read in full.
  • Cite sources: use the clean URL returned by the CLI, in the format [文档标题](URL). Prefer showing at most the 3 most relevant sources, and every conclusion should correspond to content that has been read.
  • Control output: for search use --limit and --snippet-length, and for fetch use --max-length and --start-index. The CLI does not provide the old script's temporary file preview mechanism; continuation reading depends on pagination parameters.
  • Normal empty result: when the exit code is 0 and documents is empty, rewrite the query or loosen the product filter; this does not indicate a service failure.
  • Parameter error: correct the parameters according to the corresponding subcommand's --help ; counts and lengths must be positive numbers, and the start index must be non-negative.
  • Request failure: when the exit code is non-zero, read stderr to distinguish network problems from upstream business errors. Timeout or DownstreamError Temporary failures such as these may be retried once or twice; if they persist, explain the reason for the failure and do not treat the failure as no result. Failed requests for public documentation do not require adding cloud account credentials.