核心用法
RAGFlow Skill 是一个面向 RAGFlow v0.25.2 部署的 Node.js CLI 封装工具，通过 scripts/ragflow.js 暴露完整的 REST API 能力。用户需配置 RAGFLOW_URL 和 RAGFLOW_API_KEY 环境变量即可操作所有功能模块。
主要功能模块：
- 知识库管理：数据集创建、更新、删除及元数据配置
- 文档处理：多文件上传、分块解析（支持 naive/manual/qa 等方法）、解析状态监控
- 检索与对话：直接检索、对话助手管理、多轮会话、流式/非流式聊天
- Agent 工作流：基于 DSL 的智能体创建、迭代节点、结构化输出处理
- 嵌入式集成：生成 iframe 代码、系统令牌管理、外部网站嵌入
- 系统运维：模型发现、日志级别调整、版本诊断
典型工作流：
1. 创建数据集 → 上传文档 → 启动解析 → 等待完成 → 执行检索
2. 创建对话助手 → 创建会话 → 多轮对话
3. 创建 Agent → 会话初始化 → 流式对话
显著优点
- API 完整覆盖：v0.25.2 全部端点封装，无功能缺口
- 流式支持：Agent 和对话默认流式输出，支持
--stream false切换 - 嵌入自动化：自动处理 beta 令牌获取、会话引导、auth 参数注入
- 生产级安全：强制 HTTPS 建议、最小权限 API 密钥原则、敏感数据脱敏输出
- 故障自愈：分块删除内置重试机制，针对文档存储延迟优化
- 引用文档完备：AGENT_GUIDE.md、COMMANDS.md、API.md、TROUBLESHOOTING.md 四层参考体系
潜在缺点与局限性
- Node.js 依赖：运行环境必须预装 Node，无法纯 Shell 执行
- 版本锁定：明确绑定 v0.25.2，升级需验证兼容性
- 无自动解析：上传后需显式调用解析，增加步骤复杂度
- 模型标识繁琐：需使用
model@provider完整格式，非友好名称 - 嵌入令牌管理：beta 令牌自动复用逻辑隐藏，多环境切换时可能混淆
- 重试参数调优门槛：
RAGFLOW_DELETE_CHUNK_RETRIES等参数仅故障时暴露
适合人群
- RAGFlow 运维工程师：日常部署管理、故障排查
- AI 应用开发者：快速验证 RAG pipeline、调试 Agent DSL
- 企业集成团队：嵌入式对话、网站集成、API 对接
- 数据工程师：大规模文档入库、分块策略调优
常规风险
| 风险类别 | 说明 | 缓解措施 |
|---------|------|---------|
| 密钥泄露 | API key 在日志/聊天中暴露 | 强制环境变量注入，输出脱敏 |
| 传输安全 | 生产环境未启用 HTTPS | 文档明确警告，localhost 仅测试可用 |
| 误删数据 | 删除操作不可逆无回收站 | 强制确认流程，临时资源自动清理 |
| 权限过大 | 使用 admin key 执行细粒度操作 | 建议最小权限密钥策略 |
| 嵌入令牌滥用 | beta/token 包含在生成的 URL/HTML | 按需展示，明确标注敏感 |
| 版本漂移 | 服务端升级后 API 形状变化 | 严格匹配 v0.25.2 参考文档 |
安全等级评估依据
- S 级：强制 HTTPS 建议、密钥保护规范、敏感输出脱敏、最小权限原则
- 扣分项：beta 令牌自动复用逻辑透明度不足、嵌入 auth 参数生成后难以轮换