volcengine-knowledge-search

volcengine-knowledge-search Volcano Engine documentation search

Search official documentation via ve docs search and retrieve 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 volcengine-cli 's caller identity rules. Every invocation must carry the following 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 which skill the operation belongs to.

This requirement covers --help checks, the first search, rewritten searches, body text retrieval, pagination continuation, and retries. Each tool call may start a new shell, so the three variables must be passed again and must not rely on the previous export. In the examples 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 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 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 is missing subcommands, load the volcengine-cli skill, install the latest version per its "Install or upgrade the ve CLI" section, and then check capabilities. Documentation commands access public services,no login, AK/SK, profile, or region configuration required; use them directly after installation, with no identity initialization process for resource management.

Choosing a workflow

1. The user provides a specific article link: directly fetch, and read the body text relevant to the question.
2. The user asks a question: complete the product name and specific direction, then search, with no product filter on the first search. Judge relevance by title, summary, and product code.
3. Results are too broad or irrelevant: rewrite the query; only when the ServiceCodes of the target product has been confirmed in the results should a second search be performed using that code. Do not use codes from irrelevant hits as filter conditions.
4. Complete steps, constraints, precise billing rules, or a full-text summary are needed: run fetchon the URLs of relevant results and 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, so enclose the complete question in quotes. Use --output text to get directly readable Markdown: each entry includes the title, clean URL,ServiceCodes , and body text summary. The CLI outputs JSON by default; for programmatic processing explicitly use --output json, with results in the documents array, and fields title、url、service_codes、snippet。

Parameter	Purpose
--limit N	Number of documents to return, a positive integer; generally start with 3
--service-code CODE	Restricted product; the code is taken from the confirmed relevant result; pass this option repeatedly for multiple products
--snippet-length N	Maximum number of Unicode characters per summary, a positive integer; use it to control the context size

Rewrite the query

Semantic retrieval 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 the 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, synonymous descriptions, or feature descriptions 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 the relevant results' ServiceCodes 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; text output is, in order, the title, the clean URL, the current page body, and the 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 shown. Usethe same URL and the returned indexto continue reading, avoiding missed or repeated reads. 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 bodies

• /docs/{产品编号}/{文档ID} is a specific article path.
• /docs/{产品编号} is a product documentation navigation page with no single-article body. When such a link is identified, search 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, an expired, or an incorrect address, then use search to locate alternative documentation.

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. Partial pages must not be described as having read the full article.
• Cite sources: use the clean URL returned by the CLI, in the format [文档标题](URL). Show at most the 3 most relevant sources, and every conclusion must correspond to content that has been read.
• Control output: for search use --limit and --snippet-length; for fetch use --max-length and --start-index. The CLI does not provide the old script's temporary file preview mechanism; continuation relies on pagination parameters.
• Normal empty result: when the exit code is 0 and documents is empty, rewrite the query or relax the product filter; this does not indicate a service failure.
• Parameter error: fix 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: on a non-zero exit, read stderr to distinguish network issues from upstream business errors. Timeout or DownstreamError Temporary failures such as these can be retried once or twice; if they persist, explain the reason for the failure and do not treat the failure as no result. Requests for public documentation that fail do not require supplementing cloud account credentials.