- Update AGENTS.md, backend/AGENTS.md, backend/tests/AGENTS.md, and PR template to fold regressions into owning module suites, prune superseded tests, and forbid inspect.getsource assertions. - Align CONTRIBUTING.md, backend/tests/AGENTS.md, backend/Makefile, and test_make_test_parallel.py with the 6-shard CI configuration.
4.2 KiB
Backend (backend/)
The Python backend: the publishable harness in packages/harness/deerflow/, the
public extension contract in packages/extension-api/, and the unpublished
Gateway and IM channels in app/. In every deployment the agent runtime runs
inside the Gateway. Design docs are in docs/; start with
ARCHITECTURE.md and API.md.
Guides by area
Read the guide for an area before you change it.
| Area | Guide |
|---|---|
| Run streaming, checkpoints, run ownership | runtime |
| Repositories, leases, scheduled tasks, schema changes | persistence, migrations |
| Scheduler failure isolation | design conventions |
config.yaml, extensions_config.json |
config |
| Lead agent, prompt, thread state, middleware chain | agents, middlewares |
| Memory, subagents, skills, tools | memory, subagents, skills, tools |
| Sandbox, uploads, MCP, models, extensions | sandbox, uploads, mcp, models, extensions |
| Trace ID, embedded client, other root modules | harness package |
| Search, fetch and sandbox providers | community, then the provider's own guide |
| Gateway, routers, IM channels | gateway, routers, channels |
| Tests, benchmarks | tests, benchmarks |
Verify
make test # offline suite in parallel shards
make test-blocking-io # strict blocking-I/O suite
make test-bundled-extensions # behavior suites of bundled examples (not in make test)
make lint
make format
make test-live # calls real APIs; needs DEER_FLOW_RUN_LIVE_TESTS=1
Run make test and make test-blocking-io before and after a change. Cover
behavior changes in the owning module's existing suite under tests/ rather
than opening a new file per fix, and update or delete superseded tests in the
same change. Live tests stay opt-in, so the default suite needs no network and
no API key.
Rules
-
The harness never imports
app.app.*importsdeerflow.*, and not the reverse, because the harness is published on its own.tests/test_harness_boundary.pyenforces this in CI. -
Start the Gateway with
make devormake gateway.make devexcludesDEER_FLOW_HOMEandbackend/sandboxfrom the reload watcher. A bareuvicorn --reloadrestarts the Gateway during a run, because agent tasks write Python files belowDEER_FLOW_HOME. -
From the repository root, run backend tools with
uv run --no-sync --project backend.--projectkeeps the caller's working directory, so relative config paths still resolve.--no-synckeeps installed extras such as the PostgreSQL drivers. -
Run Python through
uv runinsidebackend/, without--no-sync, so the environment matches the lock. -
Guard POSIX-only test markers with
os.name. Windows collects the same files. -
Tool approvals need addressable calls. Strip missing, empty and duplicate tool-call IDs before creating a pause or a tool result. See the run interaction policy.
-
Add a schema change with
make migrate-rev MSG="..."and follow the migrations guide. -
Notification preferences are a send-time trust boundary. Malformed provider or per-event resolver output must fail closed and remain retryable without consuming an attempt; never treat malformed data as opt-in.