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

5.1 KiB

Raw Blame History

DeerFlow

DeerFlow is an agent harness: a LangGraph-based backend with thread-isolated sandboxes, memory, subagents, skills and MCP tools, and a Next.js frontend. IM channels connect through the Gateway. CLAUDE.md imports this file; edit guidance here, not in the shim.

How guidance is organized

Rules live in the AGENTS.md nearest to the code. Before you edit a directory, read every AGENTS.md from that directory up to this file. Some coding agents do not load the nested files on their own.

Area	Guide
Backend: harness, Gateway, channels, tests	backend/AGENTS.md
Frontend	frontend/AGENTS.md
nginx, Compose, provisioner	docker/AGENTS.md
Orchestration scripts, `scripts/pnpm.py`	scripts/AGENTS.md
Skill review, skill tests	skills/AGENTS.md
Extension examples	`examples/*/AGENTS.md`

Humans start at README.md, CONTRIBUTING.md and docs/guide/.

Service topology

Service	Port	Role
Nginx	2026	The single entry point; open this in the browser
Gateway	8001	FastAPI REST API and the embedded agent runtime
Frontend	3000	Next.js web interface
Provisioner	8002	Optional; only for provisioner or Kubernetes sandboxes

Nginx serves the frontend, proxies /api/* to the Gateway and rewrites /api/langgraph/* to the Gateway's native routes.

Repository map

Path	Content
`backend/packages/harness/`	`deerflow-harness`, import `deerflow.*`: the agent framework
`backend/packages/extension-api/`	`deerflow-extension-api`: the public extension contract
`backend/app/`	The Gateway and the IM channels, import `app.*`
`frontend/`	The Next.js app (pnpm)
`docker/`, `deploy/helm/`	Compose files, nginx config, provisioner, Helm chart
`skills/public/`, `skills/custom/`	Committed skills and local, gitignored skills
`contracts/`	JSON contracts shared across components
`examples/`	Installable extension examples
`scripts/`, `tests/`	Root orchestration scripts, and tests for public skills

config.yaml and extensions_config.json are copied from the example files at the repository root. Both are gitignored and the Gateway can write them. Do not commit them.

Commands

make help lists the root targets. First setup is make config, then make install, then make dev, which serves the stack on localhost:2026 and writes logs/gateway.log and logs/frontend.log.

cd backend && make test && make test-blocking-io   # offline suites
cd backend && make format                          # CI runs ruff format --check
cd backend && python -m pytest tests/path/test_x.py::test_name -q
cd frontend && pnpm check && pnpm test
cd frontend && pnpm rstest run <pattern>
make check-agent-guidance                          # size budget of these guides

Rules for every change

Evaluate an extension first. Before you add a feature to core code, check whether it can ship as a packaged extension. Core is the place for bug fixes and for changes to the agent loop, memory, context compaction and authentication. When the existing hooks cannot express a feature, add a generic hook to the extension contract and an extension that uses it; business logic is not hard-coded into core. Contract and examples: extensions guide, examples/.
Extensions are operator-controlled code. They load from plugins: in config.yaml. The list stays out of the API-writable extensions_config.json, because loading an extension imports code with Gateway privileges. Install from trusted sources only, and restart the Gateway after every extension change.
Ship tests with every feature and bug fix.
Document behavior next to its topic, in the same change: user-facing behavior in docs/guide/ or backend/docs/. README.md is an index; change it only to add or re-point a link.
Keep the version fields identical: backend/pyproject.toml, backend/packages/harness/pyproject.toml, frontend/package.json, and version and appVersion in deploy/helm/deer-flow/Chart.yaml. scripts/bump_version.sh <ver> updates them and backend/uv.lock, and scripts/verify_versions.sh <ver> checks the result. Tag CI blocks publishing on drift. See RELEASING.md.

What belongs in an `AGENTS.md`

An agent reads these files on every task, so each line costs attention. A guide holds four kinds of content:

Scope: what the directory owns, in one or two sentences.
Verification: the exact commands.
Traps: where the code misleads, or where a plausible change breaks something that a local test run does not show.
Decisions and their reasons that the code cannot state, and links to docs.

Values, defaults, field lists, function inventories, test names, issue numbers and history stay in the code, the tests and git. Write full sentences in the positive form and give the reason. make check-agent-guidance enforces the size budget.

5.1 KiB Raw Blame History