| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 0 | 14 | 4 | 0% |
| Commands | 0 | 16 | 0 | 0% |
| Section tags | 5 | 4 | 0 | 56% |
What each file covers
Sections
0 shared · 14 only in A · 4 only in B- − RAGFlow Instructions
- − Core Stance
- − Current stack
- − Code Layout to Expect
- − Go-Specific Rules
- − Go Test Tiers
- − Working Rules
- − Commands
- − Backend
- − Frontend
- − Go
- − or build specific binaries:
- − Validation Preference
- − Default review checklist
- + Project instructions for Copilot
- + How to run (minimum)
- + Project layout (what matters)
- + Conventions
Commands
0 shared · 16 only in A · 0 only in B- − uv sync --python 3.13 --all-extras
- − uv run python3 ragflow_deps/download_deps.py
- − docker compose -f docker/docker-compose-base.yml up -d
- − uv run pytest
- − ruff check
- − ruff format
- − npm install
- − npm run dev
- − npm run build
- − npm run lint
- − npm run test
- − npm run type-check
- − uv run ragflow_deps/download_deps.py
- − docker/
- − go test
- − go build
Section tags
5 shared · 4 only in A · 0 only in B- − build
- − lint-format
- − git-pr
- − do-not
- setup
- test
- code-style
- architecture
- agent-behaviour
Line diff
infiniflow/ragflow · AGENTS.md
@@ −1 @@
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
infiniflow/ragflow · .github/copilot-instructions.md
@@ +1 @@
1# Project instructions for Copilot
2
3## How to run (minimum)
4- Install:
5 - python -m venv .venv && source .venv/bin/activate
6 - pip install -r requirements.txt
7- Run:
8 - (fill) e.g. uvicorn app.main:app --reload
9- Verify:
10 - (fill) curl http://127.0.0.1:8000/health
11
12## Project layout (what matters)
13- app/: API entrypoints + routers
14- services/: business logic
15- configs/: config loading (.env)
16- docs/: documents
17- tests/: pytest
18
19## Conventions
20- Prefer small, incremental changes.
21- Add logging for new flows.
22- Add/adjust tests for behavior changes.
23
@@ −1 +1 @@
1−# RAGFlow Instructions
1+# Project instructions for Copilot
22
3−Use 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.
3+## How to run (minimum)
4+- Install:
5+ - python -m venv .venv && source .venv/bin/activate
6+ - pip install -r requirements.txt
7+- Run:
8+ - (fill) e.g. uvicorn app.main:app --reload
9+- Verify:
10+ - (fill) curl http://127.0.0.1:8000/health
411
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+## Project layout (what matters)
13+- app/: API entrypoints + routers
14+- services/: business logic
15+- configs/: config loading (.env)
16+- docs/: documents
17+- tests/: pytest
1218
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
55−Go 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−
65−Run tiers locally via `build.sh`:
66−```bash
67−bash build.sh --test # unit tier (no tags)
68−bash build.sh --test-integration ./... # integration tier
69−bash build.sh --test-e2e # e2e tier
70−bash build.sh --test-manual # manual tier (very slow)
71−bash build.sh --test-all # integration + e2e (never includes manual)
72−```
73−Rules:
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
90−uv sync --python 3.13 --all-extras
91−uv run python3 ragflow_deps/download_deps.py
92−docker compose -f docker/docker-compose-base.yml up -d
93−source .venv/bin/activate
94−export PYTHONPATH=$(pwd)
95−bash docker/launch_backend_service.sh
96−uv run pytest
97−ruff check
98−ruff format
99−```
100−
101−### Frontend
102−```bash
103−cd web
104−npm install
105−npm run dev
106−npm run build
107−npm run lint
108−npm run test
109−npm run type-check
110−```
111−
112−### Go
113−```bash
114−uv run ragflow_deps/download_deps.py
115−bash build.sh --test ./path/to/package/...
116−bash build.sh --go
117−# or build specific binaries:
118−bash 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.
19+## Conventions
20+- Prefer small, incremental changes.
21+- Add logging for new flows.
22+- Add/adjust tests for behavior changes.
13423
