Two files, one repository
infiniflow/ragflow ships 3 formats across 3 indexed files. The question worth asking is whether the second one says anything the first does not.
| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 0 | 14 | 4 | 0% |
| Commands | 0 | 6 | 0 | 0% |
| Section tags | 5 | 4 | 0 | 56% |
What each file covers
Sections
0 shared · 14 only in A · 4 only in B- − CLAUDE.md
- − Project Overview
- − Common Commands
- − Development Conventions
- − CSS and Layout Debugging
- − Color Tokens
- − Scope and Boundaries
- − Internationalization (i18n)
- − React Component Refactoring
- − State Management and Data Fetching
- − Network Request Layering
- − Shared UI Component Lock
- − React Patterns and Conventions
- − Utility Libraries and Reuse
- + Project instructions for Copilot
- + How to run (minimum)
- + Project layout (what matters)
- + Conventions
Commands
0 shared · 6 only in A · 0 only in B- − npm install
- − npm run dev
- − npm run build
- − npm run lint
- − npm run format
- − npm run test
Section tags
5 shared · 4 only in A · 0 only in B- − build
- − dependencies
- − ui
- − do-not
- setup
- test
- code-style
- architecture
- agent-behaviour
Line diff
infiniflow/ragflow · web/CLAUDE.md
@@ −1 @@
1# CLAUDE.md
2
3This file provides guidance to Claude Code (claude.ai/code) when working with the RAGFlow frontend (`web/`).
4
5## Project Overview
6
7RAGFlow frontend is a React/TypeScript application built with UmiJS:
8
9- **Components**: shadcn/ui
10- **Styling**: Tailwind CSS
11- **State**: Zustand
12- **Data Fetching**: TanStack Query (React Query)
13- **i18n**: react-i18next
14
15## Common Commands
16
17```bash
18npm install
19npm run dev # Development server
20npm run build # Production build
21npm run lint # oxlint
22npm run format # oxfmt
23npm run test # Jest tests
24```
25
26## Development Conventions
27
28### CSS and Layout Debugging
29
30When fixing CSS/layout issues (especially flex truncation, ellipsis, or element sizing), **always inspect the full parent hierarchy** for `flex-shrink`, `min-width`, and `overflow` constraints before applying fixes like `min-w-0`. Do not repeatedly apply the same fix without verifying the root cause.
31
32- Before editing, explain: (1) the full flex/container hierarchy from the target element up to the nearest non-flex ancestor, (2) what constraint is actually causing the bug, and (3) how the proposed fix addresses that root cause.
33
34### Color Tokens
35
36When writing or modifying styles, **use the project-defined color tokens from `src/tailwind.css`** (e.g., `bg-bg-base`, `text-text-primary`, `text-text-secondary`, `text-text-disabled`, `border-border-button`, `bg-bg-card`). Do not use arbitrary hex/RGB values or Tailwind's default palette colors (e.g., `emerald-500`, `blue-400`) directly in component class names. These tokens are defined for both light and dark modes and keep the UI consistent with the design system.
37
38### Scope and Boundaries
39
40Respect explicit boundaries from the user. If the user says **"only fix the selected line"** or **"do not touch shared types/files"**, follow that instruction exactly. Do not investigate unrelated errors, modify shared schemas (e.g., `LlmSettingFieldSchema`), or refactor other files without confirmation. If a change outside the described scope seems necessary, ask for permission first.
41
42### Internationalization (i18n)
43
44For translation tasks, add keys **only to the explicitly requested language files** (commonly `src/locales/zh.ts` and `src/locales/en.ts`). Do not auto-propagate changes to all language files unless the user explicitly asks.
45
46- **Style for `en.ts`**: Sentence case — first word capitalized, rest lowercase (e.g., `referenceAnswer: 'Reference answer'`). Proper nouns remain as-is.
47
48### React Component Refactoring
49
50When refactoring or extracting components, **verify layout behavior after each structural change** (especially `flex-1`, conditional rendering, or flex direction changes). Check that existing buttons, alignment, and responsive behavior remain intact. After extraction, verify: (1) all original props and behavior are preserved, (2) layout in parent contexts is identical, and (3) no syntax or type errors were introduced.
51
52### State Management and Data Fetching
53
54#### Query Key Factory (Mandatory)
55
56**Never write raw `queryKey` arrays inline.** Always use a query key factory object that returns `as const` tuples. Raw arrays duplicated across `useQuery` and `invalidateQueries` are brittle, unreadable, and cause stale-cache bugs when key structures drift.
57
58```ts
59// ❌ Bad — raw array, hard to match with useQuery
60queryClient.invalidateQueries({
61 queryKey: [
62 LLMApiAction.AddedProviders,
63 params.provider_name,
64 params.instance_name,
65 'models',
66 ],
67});
68
69// ✅ Good — factory reference, self-documenting
70queryClient.invalidateQueries({
71 queryKey: LlmKeys.instanceModels(params.provider_name, params.instance_name),
72});
73```
74
75- Place the factory in the same file as the hooks, named `{Domain}Keys` (e.g., `LlmKeys`, `DatasetKeys`).
76- Every `useQuery` and every `invalidateQueries` must reference the same factory function.
77- Use `as const` on each factory return value for type-safe readonly tuples.
78
79#### Cache Debugging
80
81For React Query / cache invalidation bugs, **carefully compare query keys across all consuming components and mutation hooks**. Mismatched keys (e.g., with/without `refreshCount`) are a common root cause of stale data or duplicate requests.
82
83- Systematically: (1) list every component/hook that calls `useQuery` for this data, (2) compare their query keys character-for-character, (3) check every mutation's `onSuccess` for cache invalidation, and (4) verify no parent re-renders are remounting the observer.
84
85#### Colocate Queries with the Consuming View
86
87**Fire a query in the component that renders its data — not in a parent page.** When a page switches between mutually exclusive views (tabs, view modes), extract each view into its own component that issues its own requests on mount. Conditional rendering then provides lazy loading for free.
88
89- Do not hoist child-view queries into the page component — it fires requests the user may never need (e.g., fetching the skill tree on page entry while the default view is the LLM wiki).
90- Do not thread `enabled` flags or view-mode props through hooks to gate a hoisted query; that is a sign the query lives at the wrong level. Split the view instead.
91- Remember the trade-off: with `gcTime: 0`, unmounting a view drops its cache, so switching back refetches. That is usually desirable for always-fresh data — do not reintroduce eager hoisting just to avoid the refetch.
92
93### Network Request Layering
94
95HTTP requests are organized in three layers. **Never import `@/utils/request`, `@/utils/next-request`, or `@/utils/api` directly inside a hook**:
96
971. `src/hooks/use-xx-request.ts(x)` — React Query hooks; only call the service layer.
982. `src/services/xx-service.ts` — Register endpoints via `registerNextServer`, all going through `@/utils/next-request`.
993. `src/utils/next-request.ts` — The single axios instance; handles token, 401 redirects, and error notifications.
100
101Interface types are split between two folders:
102
103- Response/data shape → `src/interfaces/database/xx.ts`
104- Request params/body → `src/interfaces/request/xx.ts`
105
106Model-related endpoints (LLM provider / factory / my LLM, etc.) are consolidated in `src/services/llm-service.ts` rather than scattered across hooks. For GET endpoints, register with `method: 'get'` in the service, and on the call site pass `true` as the second argument to use the native axios config (e.g., `service.listProviders({ params: { available: true } }, true)`).
107
108### Shared UI Component Lock
109
110The folder `src/components/ui/` is the project's **shared UI library** — it contains both official shadcn/ui primitives and project-authored common components built on top of shadcn. Both kinds are intended to be reused across the app and **must not be modified casually**.
111
112- **Do not modify, refactor, restyle, or "improve"** any file under `src/components/ui/` (including subfolders), even if it seems like the most direct fix.
113- If a component does not meet requirements, **wrap or compose it** in a new component **outside** `src/components/ui/` (e.g., under `src/components/` or a feature folder), and customize via `className`, `props`, or composition.
114- Exceptions require **explicit user approval** in the same conversation. When in doubt, ask first and propose a wrapper-based alternative.
115- Adding a new shared component to `src/components/ui/`, or upgrading a shadcn primitive via the official `shadcn` CLI, is allowed only when the user explicitly requests it.
116
117### React Patterns and Conventions
118
119- **Avoid inline event handlers.** Do not define arrow functions directly on JSX event props like `onClick={() => ...}` or `onChange={(e) => ...}`. Instead, extract the handler and reference it by name (e.g., `onClick={handleClick}`). Inline handlers are recreated on every render, which can break `React.memo` optimizations and make stack traces harder to read.
120- **Prefer `requestAnimationFrame` or `useLayoutEffect`** over `setTimeout(..., 0)` for focus or DOM measurement operations.
121- **Prefer `useTranslation` from `react-i18next`** over project-wrapped utilities like `useTranslate`.
122- Extract complex logic into hooks or utils; keep components lean.
123- Use **PascalCase** for constants and component names.
124 - Components: `EditableTextarea`, `RAGFlowFormItem`
125 - Constants: `InitialMockData`, `DefaultPlaceholder`
126- Avoid camelCase or SCREAMING_SNAKE_CASE for components and top-level constants.
127- Avoid duplicating component structures in JSX; favor render props or reusable components.
128
129### Utility Libraries and Reuse
130
131- **Time/date handling**: Use `dayjs` for all date/time formatting, parsing, and manipulation.
132- **Utility hooks**: Prefer `ahooks` for common reusable hooks (e.g., `useDebounce`, `useSetState`).
133- **General utilities**: Lodash is available for utility functions when needed.
134- **Project utilities first**: Before reaching for a third-party library, check if the project already has an existing utility or hook that covers the need.
135- **Extract and share**: If repeated logic cannot be satisfied by an existing project utility or a third-party library, extract it into an appropriate shared hook (`src/hooks/`) or utility file (`src/utils/`).
136- **Check for duplicate patterns before adding**: When asked to add logic (validation, existence checks, API calls, etc.), first search for existing hooks/functions that do the same or similar thing — especially in the same file or sibling hooks. If a hook already does X, call it instead of re-implementing X inline. This applies to mutations calling mutations, utility wrappers, and boilerplate around API calls.
137
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−# CLAUDE.md
1+# Project instructions for Copilot
22
3−This file provides guidance to Claude Code (claude.ai/code) when working with the RAGFlow frontend (`web/`).
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−## Project Overview
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
618
7−RAGFlow frontend is a React/TypeScript application built with UmiJS:
8−
9−- **Components**: shadcn/ui
10−- **Styling**: Tailwind CSS
11−- **State**: Zustand
12−- **Data Fetching**: TanStack Query (React Query)
13−- **i18n**: react-i18next
14−
15−## Common Commands
16−
17−```bash
18−npm install
19−npm run dev # Development server
20−npm run build # Production build
21−npm run lint # oxlint
22−npm run format # oxfmt
23−npm run test # Jest tests
24−```
25−
26−## Development Conventions
27−
28−### CSS and Layout Debugging
29−
30−When fixing CSS/layout issues (especially flex truncation, ellipsis, or element sizing), **always inspect the full parent hierarchy** for `flex-shrink`, `min-width`, and `overflow` constraints before applying fixes like `min-w-0`. Do not repeatedly apply the same fix without verifying the root cause.
31−
32−- Before editing, explain: (1) the full flex/container hierarchy from the target element up to the nearest non-flex ancestor, (2) what constraint is actually causing the bug, and (3) how the proposed fix addresses that root cause.
33−
34−### Color Tokens
35−
36−When writing or modifying styles, **use the project-defined color tokens from `src/tailwind.css`** (e.g., `bg-bg-base`, `text-text-primary`, `text-text-secondary`, `text-text-disabled`, `border-border-button`, `bg-bg-card`). Do not use arbitrary hex/RGB values or Tailwind's default palette colors (e.g., `emerald-500`, `blue-400`) directly in component class names. These tokens are defined for both light and dark modes and keep the UI consistent with the design system.
37−
38−### Scope and Boundaries
39−
40−Respect explicit boundaries from the user. If the user says **"only fix the selected line"** or **"do not touch shared types/files"**, follow that instruction exactly. Do not investigate unrelated errors, modify shared schemas (e.g., `LlmSettingFieldSchema`), or refactor other files without confirmation. If a change outside the described scope seems necessary, ask for permission first.
41−
42−### Internationalization (i18n)
43−
44−For translation tasks, add keys **only to the explicitly requested language files** (commonly `src/locales/zh.ts` and `src/locales/en.ts`). Do not auto-propagate changes to all language files unless the user explicitly asks.
45−
46−- **Style for `en.ts`**: Sentence case — first word capitalized, rest lowercase (e.g., `referenceAnswer: 'Reference answer'`). Proper nouns remain as-is.
47−
48−### React Component Refactoring
49−
50−When refactoring or extracting components, **verify layout behavior after each structural change** (especially `flex-1`, conditional rendering, or flex direction changes). Check that existing buttons, alignment, and responsive behavior remain intact. After extraction, verify: (1) all original props and behavior are preserved, (2) layout in parent contexts is identical, and (3) no syntax or type errors were introduced.
51−
52−### State Management and Data Fetching
53−
54−#### Query Key Factory (Mandatory)
55−
56−**Never write raw `queryKey` arrays inline.** Always use a query key factory object that returns `as const` tuples. Raw arrays duplicated across `useQuery` and `invalidateQueries` are brittle, unreadable, and cause stale-cache bugs when key structures drift.
57−
58−```ts
59−// ❌ Bad — raw array, hard to match with useQuery
60−queryClient.invalidateQueries({
61− queryKey: [
62− LLMApiAction.AddedProviders,
63− params.provider_name,
64− params.instance_name,
65− 'models',
66− ],
67−});
68−
69−// ✅ Good — factory reference, self-documenting
70−queryClient.invalidateQueries({
71− queryKey: LlmKeys.instanceModels(params.provider_name, params.instance_name),
72−});
73−```
74−
75−- Place the factory in the same file as the hooks, named `{Domain}Keys` (e.g., `LlmKeys`, `DatasetKeys`).
76−- Every `useQuery` and every `invalidateQueries` must reference the same factory function.
77−- Use `as const` on each factory return value for type-safe readonly tuples.
78−
79−#### Cache Debugging
80−
81−For React Query / cache invalidation bugs, **carefully compare query keys across all consuming components and mutation hooks**. Mismatched keys (e.g., with/without `refreshCount`) are a common root cause of stale data or duplicate requests.
82−
83−- Systematically: (1) list every component/hook that calls `useQuery` for this data, (2) compare their query keys character-for-character, (3) check every mutation's `onSuccess` for cache invalidation, and (4) verify no parent re-renders are remounting the observer.
84−
85−#### Colocate Queries with the Consuming View
86−
87−**Fire a query in the component that renders its data — not in a parent page.** When a page switches between mutually exclusive views (tabs, view modes), extract each view into its own component that issues its own requests on mount. Conditional rendering then provides lazy loading for free.
88−
89−- Do not hoist child-view queries into the page component — it fires requests the user may never need (e.g., fetching the skill tree on page entry while the default view is the LLM wiki).
90−- Do not thread `enabled` flags or view-mode props through hooks to gate a hoisted query; that is a sign the query lives at the wrong level. Split the view instead.
91−- Remember the trade-off: with `gcTime: 0`, unmounting a view drops its cache, so switching back refetches. That is usually desirable for always-fresh data — do not reintroduce eager hoisting just to avoid the refetch.
92−
93−### Network Request Layering
94−
95−HTTP requests are organized in three layers. **Never import `@/utils/request`, `@/utils/next-request`, or `@/utils/api` directly inside a hook**:
96−
97−1. `src/hooks/use-xx-request.ts(x)` — React Query hooks; only call the service layer.
98−2. `src/services/xx-service.ts` — Register endpoints via `registerNextServer`, all going through `@/utils/next-request`.
99−3. `src/utils/next-request.ts` — The single axios instance; handles token, 401 redirects, and error notifications.
100−
101−Interface types are split between two folders:
102−
103−- Response/data shape → `src/interfaces/database/xx.ts`
104−- Request params/body → `src/interfaces/request/xx.ts`
105−
106−Model-related endpoints (LLM provider / factory / my LLM, etc.) are consolidated in `src/services/llm-service.ts` rather than scattered across hooks. For GET endpoints, register with `method: 'get'` in the service, and on the call site pass `true` as the second argument to use the native axios config (e.g., `service.listProviders({ params: { available: true } }, true)`).
107−
108−### Shared UI Component Lock
109−
110−The folder `src/components/ui/` is the project's **shared UI library** — it contains both official shadcn/ui primitives and project-authored common components built on top of shadcn. Both kinds are intended to be reused across the app and **must not be modified casually**.
111−
112−- **Do not modify, refactor, restyle, or "improve"** any file under `src/components/ui/` (including subfolders), even if it seems like the most direct fix.
113−- If a component does not meet requirements, **wrap or compose it** in a new component **outside** `src/components/ui/` (e.g., under `src/components/` or a feature folder), and customize via `className`, `props`, or composition.
114−- Exceptions require **explicit user approval** in the same conversation. When in doubt, ask first and propose a wrapper-based alternative.
115−- Adding a new shared component to `src/components/ui/`, or upgrading a shadcn primitive via the official `shadcn` CLI, is allowed only when the user explicitly requests it.
116−
117−### React Patterns and Conventions
118−
119−- **Avoid inline event handlers.** Do not define arrow functions directly on JSX event props like `onClick={() => ...}` or `onChange={(e) => ...}`. Instead, extract the handler and reference it by name (e.g., `onClick={handleClick}`). Inline handlers are recreated on every render, which can break `React.memo` optimizations and make stack traces harder to read.
120−- **Prefer `requestAnimationFrame` or `useLayoutEffect`** over `setTimeout(..., 0)` for focus or DOM measurement operations.
121−- **Prefer `useTranslation` from `react-i18next`** over project-wrapped utilities like `useTranslate`.
122−- Extract complex logic into hooks or utils; keep components lean.
123−- Use **PascalCase** for constants and component names.
124− - Components: `EditableTextarea`, `RAGFlowFormItem`
125− - Constants: `InitialMockData`, `DefaultPlaceholder`
126−- Avoid camelCase or SCREAMING_SNAKE_CASE for components and top-level constants.
127−- Avoid duplicating component structures in JSX; favor render props or reusable components.
128−
129−### Utility Libraries and Reuse
130−
131−- **Time/date handling**: Use `dayjs` for all date/time formatting, parsing, and manipulation.
132−- **Utility hooks**: Prefer `ahooks` for common reusable hooks (e.g., `useDebounce`, `useSetState`).
133−- **General utilities**: Lodash is available for utility functions when needed.
134−- **Project utilities first**: Before reaching for a third-party library, check if the project already has an existing utility or hook that covers the need.
135−- **Extract and share**: If repeated logic cannot be satisfied by an existing project utility or a third-party library, extract it into an appropriate shared hook (`src/hooks/`) or utility file (`src/utils/`).
136−- **Check for duplicate patterns before adding**: When asked to add logic (validation, existence checks, API calls, etc.), first search for existing hooks/functions that do the same or similar thing — especially in the same file or sibling hooks. If a hook already does X, call it instead of re-implementing X inline. This applies to mutations calling mutations, utility wrappers, and boilerplate around API calls.
19+## Conventions
20+- Prefer small, incremental changes.
21+- Add logging for new flows.
22+- Add/adjust tests for behavior changes.
13723
