---

name: ragflow-workbench

description: "RAGFlow Workbench — end-to-end RAG platform on Windows: Docker install check, admin bootstrap and API key generation, default model setup (Embedding/Chat/Rerank), knowledge base CRUD, document upload-parse lifecycle, retrieval/search, chat creation. Triggers when the user mentions: RAGFlow installation or deployment, setting up a local RAG instance on Windows, creating a knowledge base, configuring models for RAG, managing documents in datasets, searching across knowledge bases."

RAGFlow Workbench（原全流程 Skill）

前置依赖: 本 skill 需要 uv（Python 包管理器）和 docker（容器运行时）。

优先使用 scripts/ 中的脚本。默认使用 --json 保证字段可回传且可自动化。

用户输出格式遵循 references/output-format.md。

智能执行流程

根据 .env 文件判断当前 RAGFlow 环境的就绪状态，避免重复检查：

┌─ 检查 .env 是否包含有效的 RAGFLOW_API_KEY？
│
├─ ✅ 是（已建立连接）
│    跳过环境检查，直接使用 API
│    bootstrap_admin.py / configure_default_models.py 无需再次执行
│    从 datasets.py / upload.py / search.py 等 API 工作流开始
│
├─ ❌ 否（首次使用）
│    ⚠️ 注意：以下操作涉及环境检测和权限操作，必须先与用户确认，不可直接执行。
│
│    1. 询问用户意图（给出这两种选项，更多选项也可根据上下文补充）：
│       a. "您是否还没有下载安装本地知识库 RAGFlow，是否需要我帮您下载安装？"
│       b. "您已经安装部署了本地知识库 RAGFlow 吗？请告诉我地址和登录账号密码或者现有的API Key ，
│          我将自动测试连接，成功后会告知您。"
│
│    2. 根据用户回答执行：
│       ┌─ 用户选择全新安装（a）
│       │   引导用户下载 Docker Desktop → 部署 RAGFlow → 等待就绪
│       │   然后继续执行 check → bootstrap → configure 流程
│       │
│       ├─ 用户提供已有实例信息（b1）
│       │   1. 用用户提供的地址/凭证测试连接
│       │   2. 连接成功 → 写入 .env，后续会话自动跳过环境检查
│       │   3. 连接失败 → 反馈具体错误，引导排查
│       │
│       ├─ 用户提供现有 API Key（b2）
│       │   1. 测试 Key 有效性
│       │   2. 有效 → 写入 .env，跳过所有引导步骤
│       │
│       └─ 其他情况 → 根据用户实际回答灵活处理
│
│    3. 确认后的自动执行（根据情况选择）：
│       - check_windows_install.py --json    环境检查（全新安装后）
│       - bootstrap_admin.py --json          引导 + API Key
│       - configure_default_models.py --json 配置默认模型
│       → 至此 .env 已写入 RAGFLOW_API_KEY，后续会话自动跳过环境检查
│
└─ 🚀 进入 API 工作流

工作原理: bootstrap_admin.py 成功后会把 RAGFLOW_API_URL 和 RAGFLOW_API_KEY 写入 .env。后续只要这两个值存在且非空，就认为环境已验证通过，不再执行 check_windows_install.py 等安装/引导脚本。

适用场景

• 首次在 Windows 上搭建 RAGFlow，开箱可用
• 自动创建管理员并拿到 API Key
• 配置默认 Embedding / Chat / Rerank 模型
• 创建知识库、上传文件、触发解析、查看解析状态
• 对知识库执行检索、管理数据集/文档、创建对话

全生命周期流程

check_windows_install.py  →  bootstrap_admin.py  →  configure_default_models.py
                                                         ↓
                         datasets.py / upload.py / parse.py / parse_status.py
                                                         ↓
                         search.py / create_chat.py

快速开始

uv venv
.\.venv\Scripts\Activate.ps1
copy .env.example .env

uv run python scripts/check_windows_install.py --json
uv run python scripts/bootstrap_admin.py --json
uv run python scripts/configure_default_models.py --json

知识库与文档管理

uv run python scripts/datasets.py create "示例知识库" --json
uv run python scripts/upload.py DATASET_ID /path/to/file.pdf --json
uv run python scripts/parse.py DATASET_ID DOC_ID --json
uv run python scripts/parse_status.py DATASET_ID --json

检索与对话

uv run python scripts/search.py "查询文本" DATASET_ID --json
uv run python scripts/create_chat.py "对话名称" --dataset-ids DATASET_ID --llm-id qwen2-7b-instruct --json

完整命令参考

所有可用命令和参数详见 references/command-reference.md。包括：

• datasets.py list / info / create / delete
• upload.py list / delete + 上传文件
• parse.py / parse_status.py / stop_parse_documents.py
• search.py 全部检索参数
• update_dataset.py / update_document.py
• list_models.py / create_chat.py

执行约束

• 删除动作必须先列出候选对象，并获得用户明确确认
• 仅允许使用明确的 dataset_id / document_id 执行删除
• 上传不会自动触发解析，只有用户要求时才运行 parse.py
• parse.py 只发起任务，进度必须通过 parse_status.py 获取
• parse_status.py 中若含 progress_msg，需原样反馈；状态为 FAIL 时作为主错误信息，并引导用户参考 references/troubleshooting.md
• bootstrap_admin.py 与 configure_default_models.py 依赖 Docker 容器可执行 docker exec

输出规则

• 遵循 references/output-format.md
• 3 条以上结构化数据尽量使用表格
• api_error、error、message 等字段保持原值
• 不得编造进度百分比、失败原因或模型配置结果