---
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.mdbootstrap_admin.py与configure_default_models.py依赖 Docker 容器可执行docker exec
输出规则
- 遵循
references/output-format.md - 3 条以上结构化数据尽量使用表格
api_error、error、message等字段保持原值- 不得编造进度百分比、失败原因或模型配置结果
