mirror of https://github.com/bytedance/deer-flow.git synced 2026-11-12 14:00:35 +00:00

docs: turn README into an index and move reference detail to docs/guide (#8113 )

* docs: turn README into an index and move reference detail to docs/guide

The README had grown to 393 KB because every change appended its notes there. The text moves verbatim into 18 topic guides under docs/guide/; only headings are re-leveled and relative links re-pointed. The README keeps the introduction, a quick start and a guide index. Contributor test notes move to CONTRIBUTING.md.

* docs: send user docs to topic guides and budget the root README

The rule 'update README.md for user-facing changes' is what grew the README. Guidance now points to docs/guide/, and check_agent_guidance.py fails when the root README exceeds 16 KiB (AG003).

* chore: remove unreferenced screenshots and finished plan notes

pr-build/ holds two PR screenshots (3 MB) from #1986. plans/ holds the plan for the merged #4049. docs/SKILL_NAME_CONFLICT_FIX.md is a February change note. Nothing references them.

* docs: route always-loaded AGENTS.md files to scoped guides

* docs(agents): cut scoped guides to scope, verify, traps, decisions

Each AGENTS.md keeps four kinds of content: the scope of the directory, the
verification commands, traps a local test run does not show, and decisions the
code cannot state. Values, field lists, function inventories, test names, issue
numbers and history are deleted, because the code, the tests and git state them.

Search and fetch providers share one community guide. Four guides with no
remaining content are removed. The size check now allows 6 KiB per file (hard
limit 8 KiB) and 24 KiB per chain (hard limit 32 KiB).

* style: format frontend guide table and guidance test imports

---------

Co-authored-by: Willem Jiang <willem.jiang@gmail.com>

2026-11-11 13:26:17 +08:00

4.8 KiB

Raw Blame History

Frontend (`frontend/`)

The Next.js web interface: threads, streamed runs, artifacts, the workspace and its settings, and the documentation site. The directory map is in README.md. Visual and accessibility rules are in DESIGN.md; read it before UI work.

Feature rules live next to the code. Read the guide for the area you change:

Area	Guide
Data flow, threads, streaming	src
Model picker, artifact previews, Capability Center, plugin UI, composer	workspace, browser view
Model catalog and settings	core/models
Authentication, admin user management	core/auth
Memory, background tasks	core/memory, core/background-tasks
End-to-end tests	tests/e2e

Verify

cd frontend
pnpm check                    # ESLint and TypeScript; run before you commit
pnpm test                     # Rstest unit tests
pnpm rstest run <pattern>     # one unit test file
pnpm test:e2e                 # Playwright, Chromium

Other scripts are in package.json. From the repository root, host pnpm calls go through scripts/pnpm.py.

Tests

The file name selects the environment. *.test.* runs in Node and is for logic. *.dom.test.* runs in happy-dom and is for components and hooks. Keep logic out of the DOM suite, which is about three times slower.
Test effect order, unmount cleanup and store re-renders with real React and a DOM, not with a mocked hook.
Real animation is tested in Playwright. happy-dom rejects a cancelled animation's finished promise, and rejection reporting stays enabled.
E2E tests mock the backend with page.route() and drive real navigation, input and streaming.
A new permission is registered in two contract tests: tests/e2e-real-backend/auth-disabled-contract.spec.ts and backend/tests/test_auth_me_permissions.py. Both hold the complete list.

Conventions the tools do not enforce

src/components/ui/ and src/components/ai-elements/ are generated from component registries. Change them by regenerating, because a manual edit is lost on the next update.
Webpack is the development bundler. DEER_FLOW_DEV_BUNDLER=turbo pnpm dev is for diagnosis.
Use cn() from @/lib/utils for conditional class names, and inline type imports (import { type Foo }).

Environment

Leave NEXT_PUBLIC_BACKEND_BASE_URL and NEXT_PUBLIC_LANGGRAPH_BASE_URL unset for make dev and Docker. Nginx serves /api/langgraph/* and rewrites it to the Gateway routes. Set them only to reach a Gateway directly.
Development access from another host needs DEER_FLOW_DEV_ALLOWED_ORIGINS. Without it Next.js answers /_next/* with 403, the page does not hydrate, and login appears broken. Production ignores the setting.
Windows development binds 127.0.0.1, because Hyper-V port reservations make the wildcard bind fail. For LAN access run pnpm dev -- --hostname 0.0.0.0.
make build-static produces a read-only demo. Gateway reads come from bundled fixtures, and writes fail locally.

This is NOT the Next.js you know

This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in node_modules/next/dist/docs/ (resolved from this file's directory; in monorepos the next package may not be visible from the repo root) before writing any code. Heed deprecation notices.

This block is written and re-added by next dev — verify at node_modules/next/dist/server/lib/generate-agent-files.js. Removing it from a diff only re-creates the uncommitted change; committing it with your work keeps the tree clean.

4.8 KiB Raw Blame History

Frontend (frontend/)