ArkClaw知识库检索

ArkClaw 命令入口

本 Skill 面向 ArkClaw 暴露用户可直接调用的 slash command：

/qa <问题>：直接把 <问题> 作为知识库查询词执行检索

当用户通过 /qa 直接调用本 Skill 时，必须遵守以下规则：

将 /qa 后的全部文本视为本次检索的原始 query，不要要求用户重复表达
若 /qa 后没有任何内容，先提示用户补充问题，再执行检索
优先执行单轮检索；仅在明确存在上下文追问时才启用 rewrite
回答时仍然遵守本文件中“知识库优先、证据不足需标注、无结果可降级”的全部规范

强制调用规则（最高优先级）

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.

功能概述

本 Skill 封装了火山引擎 ArkClaw 知识库的cli工具，用于从知识库中检索与用户问题相关的文档片段，将检索结果作为 Agent 回答的事实依据，避免凭空杜撰（幻觉）。

支持多轮改写、rerank 重排、文本聚合等高级能力。

决策逻辑（何时调用）

以下任一情况，必须调用本 Skill：

场景	调用策略	说明
任何产品/平台/业务相关问题	必须调用	包括概念、使用方式、限制
如何做 / 怎么处理 / 怎么排查	必须调用	售后/运维/支持场景
出现报错 / 错误码 / 日志	必须调用	排障类
多轮追问	必须调用 + rewrite
不确定答案是否准确	必须调用	禁止猜
用户提到文档/知识库/资料	必须调用

以下情况可以不调用：

闲聊
通用常识（天气、数学等）

回答路径

检索后按以下优先级处理：

若知识库结果可直接回答问题：
- 使用知识库结果作答
- 标注来源
若知识库结果为空：
- 明确告知未在知识库中找到相关内容
- 回退到本地诊断 / 通用建议
- 标注"以下内容未经知识库验证"
若知识库结果存在但证据不足：
- 先说明"知识库返回了部分相关内容，但不足以直接回答您的问题"
- 再回退到本地诊断 / 通用建议
- 标注"以下内容未经知识库验证"

禁止行为

以下行为严格禁止：

未调用 Skill 直接回答业务问题
在知识库已提供明确答案时，忽略知识库结果并改用模型记忆作答
在知识库无结果或结果不足时，编造"知识库里有此结论"
未标注来源就把本地诊断结果伪装成知识库结论
因"问题简单"跳过 Skill

全局约定

路径约定

{skill_dir}：当前 Skill 的根目录路径，运行时由框架自动注入
脚本入口：{skill_dir}/scripts/search_knowledge.py

依赖文件

文件路径	作用
`scripts/search_knowledge.py`	检索脚本主入口，自动检查并下载cli工具可执行文件，封装搜索调用，同时集成 AGENTS.md 写入逻辑

前置条件

依赖工具

工具	作用
`python3`	脚本执行环境

工具使用方法

基本语法

python3 {skill_dir}/scripts/search_knowledge.py -query "<查询问题>" [选项参数]

脚本会自动检查 search_client 可执行文件是否存在，若不存在则自动下载并赋予执行权限。同时，脚本会自动检查 AGENTS.md 文件，若不存在 Viking KB First Policy 内容则自动写入。

参数说明

必需参数

参数	类型	必填	说明
`-query`	string	是	搜索查询内容

可选参数

参数	类型	默认值	说明
`-chunk-diffusion`	int	`0`	返回命中切片的上下邻近切片数，范围 [0, 5]
`-chunk-group`	flag	关闭	开启文本聚合排序
`-dense-weight`	float	`0.5`	稠密向量权重，范围 [0.2, 1.0]
`-doc-filter-conds`	string	—	文档过滤条件值（JSON 数组格式）
`-doc-filter-field`	string	—	文档过滤条件字段
`-doc-filter-op`	string	—	文档过滤条件操作符（must, must_not, range, range_out, and, or）
`-limit`	int	`10`	返回结果条数，范围 [1, 1000]
`-messages`	string	—	多轮对话历史（JSON 数组格式，开启改写时使用）
`-need-instruction`	flag	关闭	拼接 instruction 增强检索语义
`-rerank`	flag	关闭	是否开启重排序
`-rerank-model`	string	`base-multilingual-rerank`	重排序模型（doubao-seed-rerank, base-multilingual-rerank, m3-v2-rerank）
`-retrieve-count`	int	`25`	进入重排的切片数量
`-return-token-usage`	flag	关闭	返回 token 消耗量
`-rewrite`	flag	关闭	开启 query 改写

调用示例

1. 最简检索

python3 {skill_dir}/scripts/search_knowledge.py -query "ArkClaw计费规则"

2. 自定义返回条数和稠密向量权重

python3 {skill_dir}/scripts/search_knowledge.py -query "ArkClaw计费规则" -limit 5 -dense-weight 0.7

3. 开启重排序

python3 {skill_dir}/scripts/search_knowledge.py -query "ArkClaw计费规则" -rerank -rerank-model base-multilingual-rerank

4. 多轮对话改写

python3 {skill_dir}/scripts/search_knowledge.py -query "那大小呢？" -rewrite -messages '[{"role":"user","content":"支持哪些格式？"},{"role":"assistant","content":"支持 pdf、docx 等"},{"role":"user","content":"那大小呢？"}]'

返回结果格式

cli工具会返回结构化的搜索结果，包含以下主要信息：

搜索查询内容
命中的文档切片列表
每个切片的标题、内容、得分等信息
调试信息（如 request_id、token 消耗等）

错误处理

脚本错误

错误场景	错误信息	建议处理
缺少 python3 工具	`错误：需要 python3 但未找到。`	安装 python3 工具

Agent 结果使用规范

核心原则

知识库优先：优先基于检索结果回答；若知识库已有直接答案或足够证据，必须优先采纳知识库结果。
整合而非粘贴：基于检索结果进行理解、整理和总结，用自然语言组织回答。引用规范见下方。
无结果时允许回退：若搜索结果为空或未找到相关内容，必须先明确告知用户：

"在知识库中未找到与您问题直接相关的内容。"

此时允许 Agent 回退到本地诊断、通用排障经验或模型自身知识，给出补充建议。但必须显式标注：

"以下内容未经知识库验证，属于本地诊断/通用建议。"
证据不足时允许回退：若检索有结果，但内容与问题弱相关、无法形成明确结论，Agent 不应强行套用检索结果。 Agent 应先说明：

"知识库返回了部分相关内容，但不足以直接回答您的问题。"

然后可补充本地诊断建议，并标注"以下内容未经知识库验证"。
冲突处理：当知识库返回的信息与 Agent 自身知识冲突时，以知识库结果为准，并在回答中说明：

"根据内部知识库的资料，..."
异常降级：调用失败时，向用户说明"当前无法检索内部知识库"，可基于自身知识给出通用建议并标注"以下内容未经知识库验证"。

引用规范

引用类型	规则	示例
短引用（≤ 50 字）	引号包裹，内联标注来源	根据《产品使用指南》，"开通服务需要先完成实名认证"。
长引用（> 50 字）	用自己的语言概括要点，末尾附来源	开通服务的流程主要包含实名认证、控制台申请、审核三个步骤（来源：《产品使用指南》）。
严禁	直接粘贴超过 100 字的原文片段	—
来源标注	标注 `doc_title`；若 `source_link` 可用，附上链接	—

安全与脱敏

当检索结果包含敏感信息时，必须在回答中过滤或脱敏：

敏感类型	处理方式	判定标准
内部系统地址（IP / 内网域名）	替换为"内部系统"	含 `10.x`/`172.x`/`192.168.x` 或 `.internal`/`.corp` 域名
账号 / 密钥 / Token	完全隐去	含 `ak_`/`sk_`/`token`/`password` 等模式
员工姓名、工号、邮箱	替换为角色称呼（如"相关负责人"）	含 `@company.com` 或明确的人名+工号组合
未公开的内部信息	只输出概念性说明，不暴露细节	文档标注为"内部"或"机密"级别

组合规则：当一段文本同时包含多种敏感信息时，逐项分别处理；若脱敏后剩余内容失去可读性，则整段替换为概念性说明。

参考文档

Viking 知识库产品介绍
工具使用说明：运行 python3 {skill_dir}/scripts/search_knowledge.py -h 查看详细帮助

byted-util-arkclaw-kb