\r \r

RAGFlow Workbench\r

\r Prerequisites: This skill requires uv (Python package manager) and docker (container runtime).\r \r Prefer using scripts from scripts/. Use --json by default to ensure structured output for automation.\r User-facing output follows references/output-format.md.\r \r ---\r \r

Smart Execution Flow\r

\r Determine the RAGFlow environment readiness from the .env file to avoid redundant checks:\r \r

┌─ Check if .env contains a valid RAGFLOW_API_KEY?\r
│\r
├─ ✅ Yes (connection established)\r
│    Skip environment checks, use API directly\r
│    bootstrap_admin.py / configure_default_models.py do not need re-execution\r
│    Start from API workflows: datasets.py / upload.py / search.py etc.\r
│\r
├─ ❌ No (first-time use)\r
│    ⚠️ Note: The following steps involve environment detection and privileged operations;\r
│       you MUST confirm with the user before executing.\r
│\r
│    1. Ask the user for their intent (present these options; add more as context allows):\r
│       a. "Have you not yet downloaded and installed RAGFlow locally? Would you like me to help you download and install it?"\r
│       b. "Do you already have a local RAGFlow instance running? Please provide the address and login credentials, or an existing API Key — I will test the connection automatically and let you know the result."\r
│\r
│    2. Execute based on user response:\r
│       ┌─ User chooses fresh install (a)\r
│       │   Guide user to download Docker Desktop → deploy RAGFlow → wait for readiness\r
│       │   Then continue with check → bootstrap → configure workflow\r
│       │\r
│       ├─ User provides existing instance info (b1)\r
│       │   1. Test connection with provided address/credentials\r
│       │   2. Success → write to .env, skip env checks in future sessions\r
│       │   3. Failure → report specific error, guide troubleshooting\r
│       │\r
│       ├─ User provides existing API Key (b2)\r
│       │   1. Test key validity\r
│       │   2. Valid → write to .env, skip all bootstrap steps\r
│       │\r
│       └─ Other cases → handle flexibly based on actual user response\r
│\r
│    3. Automated execution after confirmation (choose as appropriate):\r
│       - check_windows_install.py --json    Environment check (after fresh install)\r
│       - bootstrap_admin.py --json          Bootstrap + API Key\r
│       - configure_default_models.py --json Configure default models\r
│       → .env now contains RAGFLOW_API_KEY; future sessions skip env checks\r
│\r
└─ 🚀 Enter API Workflow\r
```\r
\r
**How it works**: After `bootstrap_admin.py` succeeds, it writes `RAGFLOW_API_URL` and `RAGFLOW_API_KEY` to `.env`. As long as these values exist and are non-empty, the environment is considered validated and `check_windows_install.py` and other setup scripts will not be re-run.\r
\r
---\r
\r
## Use Cases\r
\r
- First-time RAGFlow setup on Windows, ready out of the box\r
- Auto-create admin user and obtain API Key\r
- Configure default Embedding / Chat / Rerank models\r
- Create knowledge bases, upload files, trigger parsing, check parse status\r
- Search knowledge bases, manage datasets/documents, create chat sessions\r
\r
## Full Lifecycle Workflow\r
\r
```\r
check_windows_install.py  →  bootstrap_admin.py  →  configure_default_models.py\r
                                                          ↓\r
                          datasets.py / upload.py / parse.py / parse_status.py\r
                                                          ↓\r
                          search.py / create_chat.py\r
```\r
\r
### Quick Start\r
\r
```bash\r
uv venv\r
.\.venv\Scripts\Activate.ps1\r
copy .env.example .env\r
\r
uv run python scripts/check_windows_install.py --json\r
uv run python scripts/bootstrap_admin.py --json\r
uv run python scripts/configure_default_models.py --json\r
```\r
\r
### Knowledge Base & Document Management\r
\r
```bash\r
uv run python scripts/datasets.py create "Sample Knowledge Base" --json\r
uv run python scripts/upload.py DATASET_ID /path/to/file.pdf --json\r
uv run python scripts/parse.py DATASET_ID DOC_ID --json\r
uv run python scripts/parse_status.py DATASET_ID --json\r
```\r
\r
### Search & Chat\r
\r
```bash\r
uv run python scripts/search.py "query text" DATASET_ID --json\r
uv run python scripts/create_chat.py "Chat Name" --dataset-ids DATASET_ID --llm-id qwen2-7b-instruct --json\r
```\r
\r
## Full Command Reference\r
\r
See [`references/command-reference.md`](references/command-reference.md) for all commands and parameters, including:\r
- `datasets.py` list / info / create / delete\r
- `upload.py` list / delete + file upload\r
- `parse.py` / `parse_status.py` / `stop_parse_documents.py`\r
- `search.py` full retrieval parameters\r
- `update_dataset.py` / `update_document.py`\r
- `list_models.py` / `create_chat.py`\r
\r
## Execution Constraints\r
\r
- **Delete operations** must first list candidates and obtain explicit user confirmation\r
- Only delete using explicit `dataset_id` / `document_id`\r
- Upload does not automatically trigger parsing; only run `parse.py` when the user requests it\r
- `parse.py` only initiates tasks; progress must be checked via `parse_status.py`\r
- If `parse_status.py` returns a `progress_msg`, echo it verbatim; when status is `FAIL`, treat it as the primary error and guide the user to [`references/troubleshooting.md`](references/troubleshooting.md)\r
- `bootstrap_admin.py` and `configure_default_models.py` require Docker containers accessible via `docker exec`\r
\r
## Output Rules\r
\r
- Follow `references/output-format.md`\r
- Use tables for 3+ structured data items\r
- Preserve `api_error`, `error`, `message` and similar fields as-is\r
- Do not fabricate progress percentages, failure reasons, or model configuration results
\r
\r