ArkClaw command entry
This Skill exposes to ArkClaw users a slash command that can be called directly:
/qa <问题>: directly use<问题>as the knowledge base query term to perform retrieval
When the user, through /qa , directly calls this Skill, the following rules must be followed:
- Treat all text after
/qaas the originalqueryfor this retrieval, do not ask the user to repeat it - If
/qahas no content after it, first prompt the user to supplement the question, then perform retrieval - Prioritize single-turn retrieval; only enable when there is clearly a contextual follow-up
rewrite - When answering, still follow all the specifications in this document of "knowledge base first, mark when evidence is insufficient, degrade when there are no results"
Mandatory invocation rules (highest priority)
This skill is the preferred knowledge retrieval gateway.
For ANY business-related, product-related, troubleshooting, SOP, FAQ, or internal knowledge question:
- The Agent MUST call this skill BEFORE answering
- The Agent MUST use knowledge-base results as the first-priority evidence source
- If the knowledge base contains a direct or sufficiently relevant answer, the Agent MUST answer based on the retrieved results
- If the knowledge base returns no relevant result, insufficient evidence, or only weakly related content, the Agent MAY fall back to local diagnosis or general troubleshooting knowledge
- Any fallback answer MUST be clearly labeled as not verified by the knowledge base
- If uncertain whether to call → MUST call
Failure to call this skill before answering is considered incorrect behavior.
Feature overview
This Skill encapsulates the cli tool of the Volcengine ArkClaw knowledge base, used to retrieve document fragments related to the user's question from the knowledge base, and use the retrieval results as the factual basis for the Agent's answer,avoiding fabrication out of thin air (hallucination)。
Supports advanced capabilities such as multi-turn rewriting, rerank reordering, and text aggregation.
Decision logic (when to invoke)
In any of the following situations,this Skill must be invoked：
| Scenario | Invocation strategy | Description |
|---|---|---|
| Any product/platform/business-related question | Must invoke | Including concepts, usage methods, limits |
| How to do / how to handle / how to troubleshoot | Must invoke | After-sales/operations/maintenance/support scenarios |
| Error / error code / log appears | Must invoke | Troubleshooting type |
| Multi-turn follow-up | Must invoke + rewrite | |
| Unsure whether the answer is accurate | Must invoke | Guessing is prohibited |
| User mentions documentation/knowledge base/materials | Must invoke |
In the following situations, it may not be invoked:
- Small talk
- General common sense (weather, math, etc.)
Answer path
After retrieval, handle according to the following priorities:
-
If the knowledge base results can directly answer the question:
- Use the knowledge base results to answer
- Mark the source
-
If the knowledge base results are empty:
- Clearly inform that no related content was found in the knowledge base
- Fall back to local diagnosis / general suggestions
- Mark "the following content has not been verified by the knowledge base"
-
If the knowledge base results exist but the evidence is insufficient:
- First state "the knowledge base returned some related content, but it is insufficient to directly answer your question"
- Then fall back to local diagnosis / general suggestions
- Mark "the following content has not been verified by the knowledge base"
Prohibited actions
The following actions are strictly prohibited:
- Answering business questions directly without invoking the Skill
- When the knowledge base already provides a clear answer, ignore the knowledge base results and answer using model memory instead
- When the knowledge base has no results or insufficient results, fabricate "this conclusion exists in the knowledge base"
- Disguise local diagnostic results as knowledge base conclusions without citing sources
- Skip the Skill because the "question is simple"
Global conventions
Path conventions
{skill_dir}: the root directory path of the current Skill, automatically injected by the framework at runtime- Script entry:
{skill_dir}/scripts/search_knowledge.py
Dependency files
| File path | Purpose |
|---|---|
scripts/search_knowledge.py |
Main entry point of the retrieval script, automatically checks for and downloads the cli tool executable, encapsulates search calls, and also integrates AGENTS.md writing logic |
Prerequisites
Dependency tools
| Tool | Purpose |
|---|---|
python3 |
Script execution environment |
Tool usage
Basic syntax
python3 {skill_dir}/scripts/search_knowledge.py -query "<查询问题>" [选项参数]
The script will automatically check whether the search_client executable file exists; if not, it will automatically download it and grant execute permission. At the same time, the script will automatically check the AGENTS.md file; if the Viking KB First Policy content does not exist, it will automatically write it in.
Parameter description
Required parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
-query |
string | Yes | Search query content |
Optional parameters
| Parameter | Type | Default value | Description |
|---|---|---|---|
-chunk-diffusion |
int | 0 |
Number of adjacent slices above and below the hit slice to return, range [0, 5] |
-chunk-group |
flag | Off | Enable text aggregation ranking |
-dense-weight |
float | 0.5 |
Dense vector weight, range [0.2, 1.0] |
-doc-filter-conds |
string | — | Document filter condition values (JSON array format) |
-doc-filter-field |
string | — | Document filter condition field |
-doc-filter-op |
string | — | Document filter condition operator (must, must_not, range, range_out, and, or) |
-limit |
int | 10 |
Number of results to return, range [1, 1000] |
-messages |
string | — | Multi-turn dialogue history (JSON array format, used when rewriting is enabled) |
-need-instruction |
flag | Off | Concatenate instruction to enhance retrieval semantics |
-rerank |
flag | Off | Whether to enable reranking |
-rerank-model |
string | base-multilingual-rerank |
Reranking model (doubao-seed-rerank, base-multilingual-rerank, m3-v2-rerank) |
-retrieve-count |
int | 25 |
Number of slices entering reranking |
-return-token-usage |
flag | Off | Return token consumption |
-rewrite |
flag | Off | Enable query rewriting |
Call examples
1. Minimal retrieval
python3 {skill_dir}/scripts/search_knowledge.py -query "ArkClaw计费规则"
2. Custom number of returned results and dense vector weight
python3 {skill_dir}/scripts/search_knowledge.py -query "ArkClaw计费规则" -limit 5 -dense-weight 0.7
3. Enable reranking
python3 {skill_dir}/scripts/search_knowledge.py -query "ArkClaw计费规则" -rerank -rerank-model base-multilingual-rerank
4. Multi-turn dialogue rewriting
python3 {skill_dir}/scripts/search_knowledge.py -query "那大小呢？" -rewrite -messages '[{"role":"user","content":"支持哪些格式？"},{"role":"assistant","content":"支持 pdf、docx 等"},{"role":"user","content":"那大小呢？"}]'
Return result format
The cli tool will return structured search results, containing the following main information:
- Search query content
- List of hit document slices
- Information such as the title, content, and score of each slice
- Debug information (such as request_id, token consumption, etc.)
Error handling
Script errors
| Error scenario | Error message | Suggested handling |
|---|---|---|
| Missing python3 tool | 错误：需要 python3 但未找到。 |
Install python3 tools |
Agent Result Usage Guidelines
Core Principles
-
Knowledge Base First: Prioritize answers based on retrieval results; if the knowledge base already has a direct answer or sufficient evidence, the knowledge base result must be adopted first.
-
Integrate Rather Than Paste: Understand, organize, and summarize based on retrieval results, and compose the answer in natural language. See the citation guidelines below.
-
Fallback Allowed When No Results: If the search results are empty or no relevant content is found, you must first clearly inform the user:
"No content directly related to your question was found in the knowledge base."
At this point, the Agent is allowed to fall back to local diagnostics, general troubleshooting experience, or the model's own knowledge to provide supplementary suggestions. But it must explicitly label:
"The following content has not been verified by the knowledge base and constitutes local diagnostics/general advice."
-
Fallback Allowed When Evidence Is Insufficient: If the retrieval has results, but the content is weakly related to the question and cannot form a clear conclusion, the Agent should not force the application of the retrieval results. The Agent should first state:
"The knowledge base returned some related content, but it is insufficient to directly answer your question."
Then it may supplement with local diagnostic suggestions and label them as "the following content has not been verified by the knowledge base".
-
Conflict Handling: When the information returned by the knowledge base conflicts with the Agent's own knowledge,the knowledge base result shall prevail, and state in the answer:
"According to the internal knowledge base materials, ..."
-
Abnormal Degradation: When the call fails, inform the user that "the internal knowledge base cannot currently be retrieved", and general suggestions may be given based on your own knowledge with the label "the following content has not been verified by the knowledge base".
Citation Guidelines
| Citation Type | Rule | Example |
|---|---|---|
| Short citation(≤ 50 characters) | Enclose in quotation marks, with the source noted inline | According to the Product Usage Guide, "activating the service requires completing real-name verification first". |
| Long citation(> 50 characters) | Summarize the key points in your own words, with the source appended at the end | The process for activating the service mainly includes three steps: real-name verification, console application, and review (Source: Product Usage Guide). |
| Strictly Prohibited | Directly pasting original text excerpts exceeding 100 characters | — |
| Source Annotation | Annotate doc_title; if source_link is available, append the link |
— |
Security and Desensitization
When retrieval results contain sensitive information,it must be filtered or desensitized in the answer：
| Sensitive Type | Handling Method | Judgment Criteria |
|---|---|---|
| Internal system addresses (IP / intranet domain) | Replace with "internal system" | Contains 10.x/172.x/192.168.x or .internal/.corp domain |
| Account / key / Token | Completely remove | Contains ak_/sk_/token/password and other patterns |
| Employee names, employee IDs, email addresses | Replace with a role designation (e.g., "relevant person in charge") | Contains @company.com or an explicit name + employee ID combination |
| Undisclosed internal information | Output only a conceptual explanation, without exposing details | The document is marked as "internal" or "confidential" level |
Combination rules: When a piece of text contains multiple types of sensitive information at the same time, handle each item separately; if the remaining content after redaction loses readability, replace the entire passage with a conceptual explanation.
Reference documents
- Viking knowledge base product introduction
- Tool usage instructions: run
python3 {skill_dir}/scripts/search_knowledge.py -hto view detailed help