核心用法
rag-query 是一款面向 Qdrant 向量数据库的语义检索技能，通过 Node.js 脚本实现对知识库的智能查询。用户可通过自然语言查询字符串，结合可选的标签过滤和结果数量控制，快速获取与查询语义最相关的文档片段。该技能支持两种传参方式：直接以位置参数传入查询字符串，或使用 --query 等显式参数进行精细化配置。
显著优点
1. 语义检索能力：基于向量嵌入技术，能够理解查询的深层语义，而非简单的关键词匹配，显著提升检索准确率和召回率。
2. 灵活过滤机制：支持通过 --topic-tags 按预定义标签筛选结果，便于在大型知识库中快速定位特定领域内容。
3. 输出结构化：返回标准 JSON 格式，包含文本内容、文档来源、类型标签等完整元信息，便于下游 Agent 直接消费和上下文注入。
4. 参数简洁直观：CLI 接口设计友好，必需参数仅查询字符串，降低使用门槛；同时提供 --top-k、--collection 等扩展选项满足进阶需求。
潜在缺点与局限性
1. 环境依赖较重：运行需预先配置 QDRANT_URL 和 EMBED_API_KEY 环境变量，且依赖本地 Node.js 环境，部署成本高于纯云端方案。
2. 无内置重排序：当前仅返回向量相似度 Top-K 结果，缺乏对结果相关性的二次精排，可能在边界查询场景下返回次优结果。
3. 标签体系依赖：topic-tags 过滤效果高度依赖知识库的标签标注质量，若标签体系不完善或标注不一致，过滤功能将大打折扣。
4. 输出无摘要生成：返回原始文本片段，未提供自动摘要或答案生成能力，需下游处理。
适合人群
- 需要为 AI Agent 提供外部知识检索能力的开发者
- 拥有结构化向量知识库、希望实现语义搜索功能的技术团队
- 熟悉 Node.js 和 CLI 工具、能够配置环境变量的运维或安全研究人员
常规风险
- 环境变量泄露风险：
EMBED_API_KEY和QDRANT_URL涉及外部服务凭证，若在共享环境或日志中暴露，可能导致未授权访问或 API 滥用。 - 检索结果偏差：向量检索依赖嵌入模型的训练分布，对于领域外或新兴概念的查询可能返回不相关结果，需结合业务逻辑校验。
- 数据权限边界：技能本身不实施细粒度权限控制，若知识库包含敏感信息，需确保通过 collection 隔离或外部鉴权机制限制访问范围。