| name | byted-util-arkclaw-kb |
| version | 3.0.0 |
| description | ArkClaw知识库问答技能, 从火山引擎ArkClaw公开知识库检索有关ArkClaw企业版相关文档, 用于解决ArkClaw企业版使用相关问题, 指令触发方式`/qa <问题描述>` |
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 {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 查看详细帮助
