AGENTS.md

1# RAGFlow Instructions
2 
3Use this file as the local operating guide for the current codebase. Prefer the code and the current CLAUDE.md over any older convention or remembered project shape.
4 
5## Core Stance
6- Treat legacy code as liability, not as a compatibility target.
7- Prefer deletion over shims, deprecated branches, wrapper APIs, and dual-track migration notes.
8- If old and new implementations coexist, converge to one path unless an external contract forces compatibility.
9- Remove dead tests, commented-out code, stale docs, and "move later" notes instead of preserving them.
10- Reduce public surface area when a helper can be made private or internal.
11- Keep refactors centered on the owning abstraction, not on adjacent compatibility layers.
12 
13## Current stack
14- Backend: Python 3.13+, Quart-based API server, Peewee ORM, async workers.
15- Frontend: React + TypeScript + Vite in `web/`.
16- Go: the repository also has a substantial Go module for servers, ingestion, parser/runtime, CLI, and supporting services.
17- Runtime services commonly include MySQL/PostgreSQL, Redis, MinIO, and Elasticsearch/Infinity/OpenSearch depending on configuration.
18 
19## Code Layout to Expect
20- `api/`: Python API server entrypoints, blueprints, services, and database code.
21- `rag/`: ingestion, retrieval, LLM integration, and graph RAG logic.
22- `deepdoc/`: parsing and OCR.
23- `agent/`: workflow canvas, components, tools, and templates.
24- `cmd/`: Go entrypoints. `ragflow_main` is the main server/admin/ingestor binary surface; `ragflow-cli` is the CLI entrypoint.
25- `internal/`: main Go application code. Important subtrees:
26- `internal/agent/`: Go agent runtime, canvas execution, components, tool bindings, workflow helpers.
27- `internal/cli/`: CLI parsing, HTTP transport, command execution, response formatting.
28- `internal/dao/`: Go data-access layer and persistence-facing helpers.
29- `internal/deepdoc/`: Go DeepDOC integrations, especially native-backed PDF/DOCX parsing.
30- `internal/engine/`: search/index backends such as Elasticsearch and Infinity.
31- `internal/entity/`: shared Go entities and model definitions.
32- `internal/handler/`: HTTP handlers and route-facing request logic.
33- `internal/ingestion/`: Go ingestion pipeline, canvas adapter, components, wiring, service orchestration.
34- `internal/ingestion/component/`: stage implementations such as file/parser/chunker/tokenizer/extractor.
35- `internal/ingestion/pipeline/`: DSL translation, canvas-driven execution, checkpoints, resume/run logic.
36- `internal/parser/`: parser and chunk libraries used by ingestion and other Go paths.
37- `internal/parser/parser/`: typed parse-result parsers for markdown/html/pdf/docx/xlsx/text and related families.
38- `internal/parser/chunk/`: chunk operator library and DSL/typed execution helpers.
39- `internal/service/`: higher-level business services used by handlers and server flows.
40- `internal/storage/`: storage backends and in-memory test doubles.
41- `internal/router/`: HTTP route registration.
42- `internal/server/`: server bootstrap/config wiring.
43- `internal/cpp/`: C++ sources used by native-backed Go features.
44- `web/`: frontend application.
45- `docker/`: local and production compose files.
46- `sdk/` and `test/`: SDK and automated tests.
47 
48## Go-Specific Rules
49- Treat `internal/ingestion`, `internal/parser`, and `internal/deepdoc` as actively refactored code. Prefer collapsing duplicate paths over preserving transitional wrappers.
50- Do not add or preserve deprecated Go APIs just to ease migration inside the repo.
51- Remove commented-out Go code instead of leaving recovery notes in place.
52- Keep package comments and doc comments aligned with the current runtime path, not with migration history.
53 
54## Go Test Tiers
55Go tests are classified by build tag so the default `go test ./...` run stays self-contained. Tag a test file with `//go:build <tier>` placed before the `package` clause.
56 
57| Tier | Build tag | Runs by default? | Needs |
58|---|---|---|---|
59| Unit | (none) | Yes (`go test ./...`) | Native CGO static libs (wired by `build.sh --test`); no external services — uses in-memory SQLite, miniredis, or `httptest` stubs. |
60| Integration | `integration` | No (`-tags integration`) | A real service: MySQL/MinIO/Elasticsearch/Infinity/LLM. Single component, reasonably fast. |
61| E2E | `e2e` | No (`-tags e2e`) | Full cross-component pipeline (ingest → index → retrieve) against real services; heavy/slow. |
62| Manual | `manual` | No (`-tags manual`) | Very slow/expensive (deepdoc render/parity/snapshot/bench). **Local opt-in ONLY — never run in CI.** |
63| Native (orthogonal) | `cgo` / `!cgo` | `cgo` auto-satisfies under CGO_ENABLED=1 | Native static libs (`office_oxide`/`pdfium`/`pdf_oxide`). Combine with tiers, e.g. `//go:build cgo && integration`. |
64 
65Run tiers locally via `build.sh`:
66```bash
67bash build.sh --test                      # unit tier (no tags)
68bash build.sh --test-integration ./...    # integration tier
69bash build.sh --test-e2e                  # e2e tier
70bash build.sh --test-manual               # manual tier (very slow)
71bash build.sh --test-all                  # integration + e2e (never includes manual)
72```
73Rules:
74- New tests that touch a real external service MUST carry `integration`/`e2e`/`manual` — do not rely on `t.Skip` + env vars to soft-isolate them in the default unit run. Keep an env guard as a harmless secondary safety net if desired.
75- `manual` is never wired into CI or any automated pipeline.
76- `unit` (no tag) must stay free of external-service dependencies so `go test ./...` passes without MySQL/MinIO/ES/Infinity/LLM. The native CGO static libraries (`office_oxide`/`pdfium`/`pdf_oxide`) are still required at build time and are wired automatically by `build.sh --test`; that is expected, not an external service.
77 
78## Working Rules
79- Before editing, inspect the nearest code path that actually owns the behavior.
80- Keep changes small and local unless the task is explicitly a broader refactor.
81- Prefer one implementation path instead of preserving old and new versions side by side.
82- Preserve behavior with focused tests when the behavior is still valid; do not keep tests that protect obsolete behavior.
83- If a surface is only there for compatibility, remove it unless the user asks to keep it.
84- Do not add new compatibility wording in comments or docs.
85- When a maintainer takes over a community PR, a new commit generated by rewriting history (e.g. `merge`, `rebase -i`) must preserve the original author and add the maintainer as co-author (via a `Co-authored-by:` trailer) instead of overwriting the author with the maintainer alone.
86 
87## Commands
88### Backend
89```bash
90uv sync --python 3.13 --all-extras
91uv run python3 ragflow_deps/download_deps.py
92docker compose -f docker/docker-compose-base.yml up -d
93source .venv/bin/activate
94export PYTHONPATH=$(pwd)
95bash docker/launch_backend_service.sh
96uv run pytest
97ruff check
98ruff format
99```
100 
101### Frontend
102```bash
103cd web
104npm install
105npm run dev
106npm run build
107npm run lint
108npm run test
109npm run type-check
110```
111 
112### Go
113```bash
114uv run ragflow_deps/download_deps.py
115bash build.sh --test ./path/to/package/...
116bash build.sh --go
117# or build specific binaries:
118bash build.sh --all
119```
120 
121## Validation Preference
122- Run the narrowest relevant test, lint, or build command after a change.
123- For backend changes, prefer targeted pytest or ruff checks over full-suite runs.
124- For frontend changes, prefer the touched-package lint, type-check, or test command.
125- For Go changes, prefer package-scoped `bash build.sh --test ...` first.
126- Do not default to raw `go test`, `go build`, or IDE Run/Debug for Go in this repo. They often miss the required CGO flags and native static libraries (`office_oxide`, `pdfium-static`, `pdf_oxide`) that `build.sh` wires correctly.
127- If Go native builds fail, inspect `build.sh` and `internal/development.md` before changing code. Common environment issues are missing downloaded native deps and missing `lld` on Linux.
128 
129## Default review checklist
130- Remove instead of retaining `deprecated`, `legacy`, or compatibility-only code.
131- Collapse duplicate implementations to one path.
132- Drop stale comments and documentation that describe a superseded design.
133- Keep exported APIs only when the current code actually needs them.
134