hk101-living-rag

核心用法

claw-rag 是一个极简的本地文档 RAG（检索增强生成）工具，专为处理本地文本和 Markdown 文件设计。用户只需提供查询问题（query），即可在指定文档目录（docsPath，默认为 ./docs）中检索相关内容，并返回综合答案。支持通过 k 参数控制返回的匹配片段数量（默认 3 条）。该技能依赖 OpenAI API 进行语义理解和答案生成，需要用户自行配置 OPENAI_API_KEY 环境变量。

显著优点

1. 零代码风险：纯文档型技能，无可执行代码，无动态加载，安全性极高
2. 极简设计：参数清晰，开箱即用，无需复杂配置即可实现 RAG 功能
3. 透明可控：数据来源完全本地化，用户明确知道哪些文档被检索
4. 轻量依赖：仅依赖 OpenAI API，无额外第三方库或复杂依赖链
5. 输出结构化：返回包含答案、匹配路径、相关度分数和原文片段的完整信息

潜在缺点与局限性

1. 云端依赖：必须联网并调用 OpenAI API，无法离线使用，存在服务中断风险
2. 隐私顾虑：文档内容需发送至 OpenAI 服务器，不适合处理机密或敏感数据
3. 成本因素：依赖 OpenAI API 调用，高频使用会产生费用
4. 功能单一：仅支持基础 RAG，无高级功能如重排序、多轮对话记忆、多模态支持
5. 格式限制：仅支持文本/Markdown，不支持 PDF、Word 等富格式文档的直接解析

适合的目标群体

• 个人开发者和技术写作者，需要快速搭建本地知识库问答
• 小型团队进行内部文档检索和知识管理
• 对安全性要求高、希望避免执行不可信代码的用户
• RAG 技术初学者，希望理解基础 RAG 流程
• 非敏感领域的知识管理场景（如公开技术文档、学习笔记）

使用风险

1. API 密钥泄露风险：OPENAI_API_KEY 需妥善保管，避免硬编码或误提交至版本控制
2. 数据出境合规：文档内容传输至 OpenAI 服务器，需符合当地数据跨境法规
3. 模型幻觉：RAG 虽能降低幻觉，但 OpenAI 模型仍可能生成不准确信息
4. 检索质量依赖：文档分块和嵌入质量直接影响答案准确性，需自行优化文档结构
5. 无访问控制：本地文档路径需自行管理权限，避免误检索敏感目录