Use for RAGFlow dataset and retrieval tasks: create, list, inspect, update, or delete datasets; list, upload, update, or delete documents in a dataset; start...
--- name: ragflow-dataset-ingest description: "Use for RAGFlow dataset and retrieval tasks: create, list, inspect, update, or delete datasets; list, upload, update, or delete documents in a dataset; start or stop parsing uploaded documents; check parser status through `parse_status.py`; and retrieve relevant chunks from RAGFlow datasets with `search.py`." --- # RAGFlow Dataset And Retrieval Use only the bundled scripts in `scripts/`. Prefer `--json` for script execution so the returned fields can be relayed exactly. ## Trigger Phrases Use this skill when the user intent matches any of these actions, in either Chinese or English, even if the wording is informal. - List datasets Trigger phrases: "list datasets", "show datasets", "show all datasets", "what datasets do I have" "列出数据集", "查看数据集", "显示所有数据集", "我有哪些数据集" - Show dataset details Trigger phrases: "dataset details", "show dataset info", "inspect dataset", "describe this dataset" "数据集详情", "查看数据集信息", "检查数据集", "显示这个数据集的信息" - Create dataset Trigger phrases: "create dataset", "new dataset", "add a dataset" "创建数据集", "新建数据集", "添加数据集" - Update dataset Trigger phrases: "rename dataset", "update dataset", "change dataset description", "modify dataset" "重命名数据集", "更新数据集", "修改数据集描述", "编辑数据集" - Delete dataset Trigger phrases: "delete dataset", "remove dataset", "drop dataset" "删除数据集", "移除数据集", "清理数据集" - Upload documents Trigger phrases: "upload file", "upload document", "add file to dataset", "import files" "上传文件", "上传文档", "把文件加到数据集", "导入文件" - List documents Trigger phrases: "list documents", "show files", "show documents in dataset", "what files are in this dataset" "列出文档", "列出文件", "查看数据集里的文件", "这个数据集里有哪些文件" - Update document Trigger phrases: "rename document", "update document", "edit document metadata" "重命名文档", "更新文档", "修改文档元数据" - Delete document Trigger phrases: "delete document", "remove file", "delete file from dataset" "删除文档", "删除文件", "从数据集删除文件" - Start parsing Trigger phrases: "parse document", "start parsing", "run parsing", "re-parse document" "解析文档", "开始解析", "执行解析", "重新解析文档" - Stop parsing Trigger phrases: "stop parsing", "cancel parsing", "stop parse job" "停止解析", "取消解析", "停止解析任务" - Check parsing status or progress Trigger phrases: "check parsing status", "show progress", "what is still running", "parsing progress" "查看解析状态", "查看进度", "还有哪些在运行", "解析进度" - Search / retrieve Trigger phrases: "search knowledge base", "search dataset", "retrieve chunks", "find relevant content" "搜索知识库", "搜索数据集", "检索内容", "查找相关内容" - List models Trigger phrases: "list models", "show models", "available models", "what models are available", "list llms", "show llms", "model providers" "列出模型", "查看模型", "可用模型", "有哪些模型", "列出大模型", "查看大模型", "模型供应商" - Show model details or provider grouping Trigger phrases: "model details", "show model details", "group models by provider", "list all models including unavailable ones" "模型详情", "查看模型详情", "按供应商查看模型", "列出所有模型包括不可用模型" ## Workflow ```bash python scripts/datasets.py create "My Dataset" --description "Optional description" python scripts/datasets.py list python scripts/datasets.py info DATASET_ID python scripts/update_dataset.py DATASET_ID --name "Renamed Dataset" ``` 1. Create a dataset or confirm the target dataset. 2. Upload files. When asking the user to provide files, prefer explicit local file paths. If the user's client supports drag-and-drop, they may also drop files into the conversation, but local paths work best and large drag-and-drop uploads may fail. ```bash python scripts/upload.py list DATASET_ID --json python scripts/upload.py DATASET_ID /path/to/file1 [/path/to/file2 ...] python scripts/update_document.py DATASET_ID DOC_ID --name "Renamed Document" ``` Upload output returns `document_ids`. Pass those IDs into the next step. Use delete commands when the task is cleanup instead of ingest: ```bash python scripts/datasets.py delete --ids DATASET_ID1,DATASET_ID2 python scripts/upload.py delete DATASET_ID --ids DOC_ID1,DOC_ID2 ``` ⚠️ **DELETION REQUIRES CONFIRMATION**: Before executing any delete operation (datasets or documents): 1. List items to be deleted with details (names, IDs, counts) 2. Ask user for explicit confirmation (e.g., "yes", "confirm", "proceed") 3. Only proceed after user confirms For dataset deletion, execute only against explicit dataset IDs. For document deletion, execute only against explicit document IDs. If the user gives filenames or a fuzzy description, list documents first, resolve exact IDs, get confirmation, and only then run the delete command. Do not perform fuzzy batch delete operations. 3. Start parsing, or stop parsing when explicitly requested. ```bash python scripts/parse.py DATASET_ID DOC_ID1 [DOC_ID2 ...] python scripts/stop_parse_documents.py DATASET_ID DOC_ID1 [DOC_ID2 ...] ``` `parse.py` only sends the parse request and returns immediately. `stop_parse_documents.py` sends a stop request for explicit document IDs, then returns one current status snapshot for those documents. Use `parse_status.py` when the user asks to check progress or current parser status. If `parse_status.py` returns an error, return the error message directly and do not guess the cause. If a document status includes `progress_msg`, surface it automatically. For `FAIL` documents, treat `progress_msg` as the primary error detail. For later requests like "Check the progress" or "Which files are currently being parsed", resolve scope by specificity: - no dataset specified: inspect all datasets and all documents - dataset specified: inspect all documents in that dataset - document IDs specified: inspect only those documents 4. Retrieve chunks from one or more datasets when the user asks knowledge questions against RAGFlow. ```bash python scripts/search.py "What does the warranty policy say?" python scripts/search.py "What does the warranty policy say?" DATASET_ID python scripts/search.py --dataset-ids DATASET_ID1,DATASET_ID2 --doc-ids DOC_ID1,DOC_ID2 "What does the warranty policy say?" python scripts/search.py --threshold 0.7 --top-k 10 "query" python scripts/search.py --retrieval-test --kb-id DATASET_ID "query" ``` 5. Inspect configured LLM factories and models when the user asks what models are available. ```bash python scripts/list_models.py --json python scripts/list_models.py --include-details --json python scripts/list_models.py --group-by factory --json python scripts/list_models.py --all --group-by factory --include-details --json ``` ## Model Listing - default to listing only available models - default to grouping by model `type` - if multiple model groups or models are shown, prefer a table - if the user asks for details, provider grouping, or unavailable models, expand the output accordingly - prefer the grouped result in `groups` instead of reintroducing the raw server response shape ## Progress And Status Output - summarize `RUNNING` items first when reporting progress - status reporting should reflect the dataset document list API as-is; do not fabricate percentage progress ## Error Output - when returning raw script output, preserve error fields exactly as returned - if JSON output contains `api_error`, present that object directly rather than replacing it with a guessed explanation ## Scope Support only: - create datasets - list datasets - inspect datasets - update datasets - delete datasets - upload documents to a dataset - list documents in a dataset - update documents in a dataset - delete documents from a dataset - start parsing documents in a dataset - stop parsing documents in a dataset - list all currently parsing documents in a dataset for broad progress requests - aggregate parse progress across all datasets for broad progress requests - retrieve relevant chunks from one or more datasets - limit retrieval to specific dataset IDs or document IDs - use `retrieval_test` for single-dataset debugging when needed - list configured LLM factories and models through the web API Do not use this skill for chunk editing, memory APIs, or other RAGFlow capabilities outside dataset operations and retrieval. ## Environment Configure `.env` with: ```bash RAGFLOW_API_URL=http://127.0.0.1:9380 RAGFLOW_API_KEY=ragflow-your-api-key-here RAGFLOW_DATASET_IDS=["dataset-id-1", "dataset-id-2"] ``` `RAGFLOW_API_URL` is the primary base URL setting. `RAGFLOW_BASE_URL` is accepted as a legacy fallback for compatibility, but new setups should use `RAGFLOW_API_URL`. When loading the repository `.env`, the bundled scripts only import `RAGFLOW_` variables into the process environment. ## Endpoints - `GET /api/v1/datasets` - `POST /api/v1/datasets` - `PUT /api/v1/datasets/<dataset_id>` - `DELETE /api/v1/datasets` - `GET /api/v1/datasets/<dataset_id>/documents` - `POST /api/v1/datasets/<dataset_id>/documents` - `PUT /api/v1/datasets/<dataset_id>/documents/<document_id>` - `DELETE /api/v1/datasets/<dataset_id>/documents` - `POST /api/v1/datasets/<dataset_id>/chunks` - `DELETE /api/v1/datasets/<dataset_id>/chunks` - `POST /api/v1/retrieval` - `POST /api/v1/chunk/retrieval_test` - `GET /v1/llm/my_llms` ## Commands ```bash python scripts/datasets.py create "Example Dataset" --description "Quarterly reports" python scripts/datasets.py create "Example Dataset" --embedding-model bge-m3 --chunk-method naive --permission me python scripts/datasets.py list python scripts/datasets.py info DATASET_ID python scripts/update_dataset.py DATASET_ID --name "Updated Dataset" --description "Updated description" python scripts/datasets.py delete --ids DATASET_ID1,DATASET_ID2 --json python scripts/upload.py list DATASET_ID --json python scripts/upload.py DATASET_ID ./example.pdf --json python scripts/update_document.py DATASET_ID DOC_ID --name "Updated Document" --enabled 1 --json python scripts/upload.py delete DATASET_ID --ids DOC_ID1,DOC_ID2 --json python scripts/datasets.py list --json python scripts/parse.py DATASET_ID DOC_ID1 --json python scripts/stop_parse_documents.py DATASET_ID DOC_ID1 --json python scripts/parse_status.py DATASET_ID --json python scripts/search.py "query" python scripts/search.py "query" DATASET_ID --json python scripts/search.py --dataset-ids DATASET_ID1,DATASET_ID2 --doc-ids DOC_ID1,DOC_ID2 "query" --json python scripts/search.py --retrieval-test --kb-id DATASET_ID "query" --json python scripts/list_models.py --json python scripts/list_models.py --include-details --json ``` ## Notes - Dataset creation supports `--avatar`, `--description`, `--embedding-model`, `--permission`, `--chunk-method`, and `--language`. - Dataset update supports explicit flags or `--data` JSON payloads through `scripts/update_dataset.py`. - Upload does not start parsing by itself. - Prefer local file paths for uploads. Drag-and-drop is acceptable only when the client's UI supports it, and it may fail for large files. - Document update supports explicit flags or `--data` JSON payloads through `scripts/update_document.py`. - Parsing is asynchronous. - `parse.py` returns immediately after the start request. Do not wait for parse status in this command. - When a script returns an error, proactively include the error message in the same reply. Do not wait for the user to ask for the error details. - If JSON output contains `api_error`, return that API error object directly instead of replacing it with a guessed explanation. - If JSON output contains `error`, `api_error.message`, `status_error.message`, or `error_detail.message`, surface that message to the user immediately. - A stop request may not flip the document to `CANCEL` immediately. Use the returned snapshot or `scripts/parse_status.py` to confirm the terminal state. - For broad status/progress requests with no dataset specified, list datasets first and aggregate `scripts/parse_status.py DATASET_ID` across all datasets. - If a dataset is specified, prefer `scripts/parse_status.py DATASET_ID` without `--doc-ids`. - If document IDs are specified, pass `--doc-ids`. - Retrieval defaults to `POST /api/v1/retrieval`. - `scripts/search.py` accepts `RAGFLOW_DATASET_IDS` from `.env` as the default dataset scope when the user does not specify dataset IDs explicitly. - Use `--retrieval-test` only when the user wants single-dataset debugging or specifically asks for that endpoint. - `scripts/list_models.py` calls `GET /v1/llm/my_llms` and uses `RAGFLOW_API_KEY` Bearer auth only.
don't have the plugin yet? install it then click "run inline in claude" again.