volcengine-knowledge-search

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

volcengine-knowledge-search 火山引擎文档检索

volcengine-knowledge-search Volcengine Documentation Retrieval

通过

ve docs search

检索官方文档，通过

ve docs fetch

获取正文。请求、响应解析、正文清洗和分页由 CLI 处理；本 skill 负责场景判断、query 改写、二次检索和来源引用。

Search official documentation with

ve docs search

and retrieve body text with

ve docs fetch

. The CLI handles requests, response parsing, body-text cleaning, and pagination; this skill handles scenario selection, query rewriting, secondary searches, and source citations.

CLI 调用约定

CLI Invocation Conventions

执行

ve

前，遵循

volcengine-cli

的调用方标识规则。每次调用都必须在进程环境中携带：

```
VE_CALLER_TYPE=ai_agent
```
。
```
VE_CALLER_NAME
```
：由 Agent 根据当前实际宿主环境确定，不使用固定默认值。
```
VE_SKILL_NAME
```
：取当前执行操作的 skill 的 frontmatter
```
name
```
。本 skill 执行文档检索或正文读取时，该值为
```
volcengine-knowledge-search
```
；引用 CLI 的调用规则不改变操作所属 skill。

该要求覆盖

--help

检查、首次检索、改写后的检索、正文读取、分页续读及重试。每次工具调用可能启动新的 shell，必须重新传入三项变量，不依赖上一次的

export

。下面示例中的

<agent-id>

与

<current-volcengine-skill>

均由 Agent 根据当前环境和 skill 元数据替换，不得原样传入。这些变量仅用于调用来源标识，不改变公开文档命令无需登录的约定。

Before running

ve

, follow the caller identification rules in

volcengine-cli

(Caller Identification 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 actual current host environment; do not use a fixed default.
```
VE_SKILL_NAME
```
: Use the
```
name
```
from the frontmatter of the skill currently performing the operation. When this skill performs documentation retrieval or body-text reading, the value is
```
volcengine-knowledge-search
```
; referencing the CLI invocation rules does not change the skill to which the operation belongs.

This requirement applies to

--help

checks, the initial search, rewritten searches, body-text retrieval, paginated continuation, and retries. Each tool invocation may start a new shell, so all three variables must be passed again rather than relying on a previous

export

. In the following examples, the Agent must replace

<agent-id>

and

<current-volcengine-skill>

based on the current environment and skill metadata; they must not be passed literally. These variables are used only to identify the invocation source and do not alter the convention that public documentation commands require no login.

准备

Preparation

首次使用时确认本机具备两个子命令：

bash

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

若

ve

未安装或缺少子命令，加载

volcengine-cli

skill，按其「Install or upgrade the ve CLI」章节安装最新版，再检查能力。文档命令访问公开服务，无需登录、AK/SK、profile 或地域配置；安装后直接使用，无需执行资源管理的身份初始化流程。

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

bash

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

ve

is not installed or the subcommands are unavailable, load the

volcengine-cli

skill, install the latest version according to its “Install or upgrade the ve CLI” section, and then check the capabilities again. Documentation commands access public services and require no login, AK/SK, profile, or region configuration; use them directly after installation without running the resource-management identity initialization process.

选择流程

Decision Flow

用户提供具体文章链接：直接
```
fetch
```
，读取与问题相关的正文。
用户提出问题：补全产品名和具体方向后
```
search
```
，首次检索不带产品过滤。根据标题、摘要和产品编码判断相关性。
结果过宽或不相关：改写 query；只有结果中已确认目标产品的
```
ServiceCodes
```
时，才使用该编码二次检索。不要把无关命中的编码用作过滤条件。
需要完整步骤、限制条件、精确计费规则或全文总结：对相关结果的 URL 执行
```
fetch
```
，按需续读；用户要求全文时，读到没有续读提示或
```
has_more=false
```
。

The user provides a specific article link: Directly
```
fetch
```
it and read the body text relevant to the question.
The user asks a question: Complete the product name and specific area of interest, then
```
search
```
. Do not apply a product filter to the initial search. Determine relevance from the title, snippet, and product code.
The results are too broad or irrelevant: Rewrite the query. Use a
```
ServiceCodes
```
value for a secondary search only after the target product has been confirmed in the results. Never use a code from an irrelevant match as a filter.
Complete steps, constraints, exact billing rules, or a full-text summary are required: Run
```
fetch
```
on the URLs of relevant results and continue reading as needed. When the user requests the full text, keep reading until there is no continuation prompt or
```
has_more=false
```
.

search：检索文档

search: Search Documentation

bash

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

搜索文本是位置参数，用引号包住完整问题。用

--output text

获取可直接阅读的 Markdown：每条包含标题、纯净 URL、

ServiceCodes

和正文摘要。CLI 默认输出 JSON；需要程序化处理时显式用

--output json

，结果在

documents

数组中，字段为

title

、

url

、

service_codes

、

snippet

。

参数	用途
`--limit N`	返回文档数，正整数；一般先取 3 条
`--service-code CODE`	限定产品，编码取自已确认相关的结果；多个产品重复传此选项
`--snippet-length N`	每条摘要的最大 Unicode 字符数，正整数；用它控制上下文体积

bash

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 a positional argument; enclose the complete question in quotation marks. Use

--output text

to obtain directly readable Markdown: each result includes the title, clean URL,

ServiceCodes

, and body-text snippet. The CLI outputs JSON by default; explicitly use

--output json

when programmatic processing is required. Results are placed in the

documents

array, with the fields

title

url

service_codes

, and

snippet

Parameter	Purpose
`--limit N`	Number of documents to return; must be a positive integer. Generally, start with 3.
`--service-code CODE`	Restricts results to a product. Use a code confirmed from relevant results; repeat this option for multiple products.
`--snippet-length N`	Maximum number of Unicode characters in each snippet; must be a positive integer. Use it to control context size.

改写 query

Query Rewriting

语义检索需要贴近文档表述。将口语、简称或营销名补成产品全称 + 能力描述 + 具体问题，例如把「Coding Plan 多少钱」改写为「火山方舟 Coding Plan AI 编程订阅套餐如何计费」。首搜跑偏时，换全称、近义描述或功能描述再搜。

bash

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

先宽搜，确认相关结果的

ServiceCodes

为

tos

后，按产品精搜：

bash

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

多个产品编码使用

--service-code <code-a> --service-code <code-b>

，每个编码单独传递。

Semantic retrieval should closely match the documentation's wording. Expand colloquial terms, abbreviations, or marketing names into a full product name + capability description + specific question. For example, rewrite “How much does Coding Plan cost?” as “How is the Volcengine Ark Coding Plan AI programming subscription package priced?” If the initial search misses the target, try the full name, a synonymous description, or a functional description.

bash

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

First run a broad search. After confirming that the

ServiceCodes

value of a relevant result is

tos

, run a product-specific search:

bash

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：获取正文

fetch: Retrieve Body Text

支持

https://www.volcengine.com/docs/...

和

https://docs.volcengine.com/docs/...

。CLI 会去掉 URL 的 query 和 fragment，text 输出依次为标题、纯净 URL、当前页正文及续读提示。

bash

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

参数	用途
`--start-index N`	从第 N 个 Unicode 字符开始，索引从 0 起
`--max-length N`	当前页最多返回的 Unicode 字符数，正整数；默认 5000

长文末尾会提示下一页的

--start-index

。用同一个 URL 和返回的索引继续读，避免漏读或重复。以下示例先取 300 字，若续读提示为

--start-index 300

，再读取下一页：

bash

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

程序化分页使用

--output json

，读取

content

、

start_index

、

next_start_index

、

remaining_characters

、

has_more

和

has_content

。

has_more=true

时用

next_start_index

续读；结束时该字段为

null

。

Both

https://www.volcengine.com/docs/...

and

https://docs.volcengine.com/docs/...

are supported. The CLI removes the query string and fragment from the URL. In text output mode, the title, clean URL, current page body text, and continuation prompt are returned in that order.

bash

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`	Starts at the Nth Unicode character; the index begins at 0.
`--max-length N`	Maximum number of Unicode characters returned for the current page; must be a positive integer. The default is 5000.

At the end of a long document, the CLI indicates the next page's

--start-index

. Continue reading with the same URL and returned index to avoid omissions or duplicates. The following example first retrieves 300 characters. If the continuation prompt says

--start-index 300

, retrieve the next page:

bash

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 read

content

start_index

next_start_index

remaining_characters

has_more

, and

has_content

. When

has_more=true

, continue reading with

next_start_index

. At the end, this field is

null

导航页与空正文

Navigation Pages and Empty Body Text

```
/docs/{产品编号}/{文档ID}
```
是具体文章路径。
```
/docs/{产品编号}
```
是产品文档导航页，没有单篇文章正文。识别到这种链接时，按产品名和用户关心的方向
```
search
```
，从结果定位具体文章再
```
fetch
```
，并向用户说明链接类型。
```
has_content=false
```
表示没有取得正文，不能据此编造内容。检查链接是否为导航页、过期或错误地址，再用
```
search
```
定位替代文档。

```
/docs/{product-id}/{document-id}
```
is a specific article path.
```
/docs/{product-id}
```
is a product documentation navigation page and has no body text for a single article. When this type of link is detected, use
```
search
```
with the product name and the user's area of interest, locate a specific article in the results, then
```
fetch
```
it. Explain the link type to the user.
```
has_content=false
```
means that no body text was retrieved; do not fabricate content based on it. Check whether the link is a navigation page, an expired address, or an incorrect URL, and then use
```
search
```
to locate an alternative document.

结果与错误处理

Results and Error Handling

按证据回答：摘要足以支撑的概念问题可以直接回答；精确规则和完整步骤先取正文。部分页面不能表述为已读完整篇。
引用来源：使用 CLI 返回的纯净 URL，格式为
```
[文档标题](URL)
```
。优先展示最多 3 条最相关来源，每个结论都能对应到已读取的内容。
控制输出：search 用
```
--limit
```
和
```
--snippet-length
```
，fetch 用
```
--max-length
```
和
```
--start-index
```
。CLI 不提供旧脚本的临时文件预览机制，续读依赖分页参数。
正常空结果：退出码为 0 且
```
documents
```
为空时，改写 query 或放宽产品过滤；这不代表服务故障。
参数错误：按对应子命令的
```
--help
```
修正参数；数量和长度必须为正数，起始索引非负。
请求失败：非零退出时读取 stderr，区分网络问题和上游业务错误。超时或
```
DownstreamError
```
等暂时性故障可重试一两次；持续失败时说明失败原因，不把失败当成无结果。公开文档请求失败无需补充云账号凭据。

Answer based on evidence: Conceptual questions sufficiently supported by a snippet can be answered directly. Retrieve the body text first when exact rules or complete steps are needed. Do not describe a partially read page as having been read in full.
Cite sources: Use the clean URL returned by the CLI in the format
```
[Document Title](URL)
```
. Prefer displaying at most 3 of the most relevant sources, and ensure that every conclusion corresponds to content that has been read.
Control output: Use
```
--limit
```
and
```
--snippet-length
```
for
```
search
```
, and use
```
--max-length
```
and
```
--start-index
```
for
```
fetch
```
. The CLI does not provide the temporary-file preview mechanism used by older scripts; continuation depends on pagination parameters.
Normal empty result: If the exit code is 0 and
```
documents
```
is empty, rewrite the query or relax the product filter. This does not indicate a service failure.
Argument error: Correct the arguments according to the corresponding subcommand's
```
--help
```
. Counts and lengths must be positive, and the starting index must be non-negative.
Request failure: When the exit code is non-zero, read stderr and distinguish network issues from upstream business errors. Temporary failures such as timeouts or
```
DownstreamError
```
may be retried once or twice. If the failure persists, explain the cause and do not treat it as an empty result. Failed public documentation requests do not require cloud account credentials.