mirror of
https://github.com/bytedance/deer-flow.git
synced 2026-11-13 06:31:47 +00:00
3d826c6d95
* feat(hitl): add human-in-the-loop approval for high-risk tool calls * fix(hitl): address approval review findings * docs(hitl): keep agent guidance under size limit * fix(hitl): guard approval pause recovery * docs(hitl): shrink inherited guidance * fix(hitl): harden approval admission and recovery * fix(approvals): address review safety and reconciliation gaps * ci: retry approval checks after runner timeout --------- Co-authored-by: wangzeren <1004695029@qq.com>
62 lines
3.7 KiB
Markdown
62 lines
3.7 KiB
Markdown
# 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/](docs/); start with
|
|
[ARCHITECTURE.md](docs/ARCHITECTURE.md) and [API.md](docs/API.md).
|
|
|
|
## Guides by area
|
|
|
|
Read the guide for an area before you change it.
|
|
|
|
| Area | Guide |
|
|
| --- | --- |
|
|
| Run streaming, checkpoints, run ownership | [runtime](packages/harness/deerflow/runtime/AGENTS.md) |
|
|
| Repositories, leases, scheduled tasks, schema changes | [persistence](packages/harness/deerflow/persistence/AGENTS.md), [migrations](packages/harness/deerflow/persistence/migrations/AGENTS.md) |
|
|
| `config.yaml`, `extensions_config.json` | [config](packages/harness/deerflow/config/AGENTS.md) |
|
|
| Lead agent, prompt, thread state, middleware chain | [agents](packages/harness/deerflow/agents/AGENTS.md), [middlewares](packages/harness/deerflow/agents/middlewares/AGENTS.md) |
|
|
| Memory, subagents, skills, tools | [memory](packages/harness/deerflow/agents/memory/AGENTS.md), [subagents](packages/harness/deerflow/subagents/AGENTS.md), [skills](packages/harness/deerflow/skills/AGENTS.md), [tools](packages/harness/deerflow/tools/AGENTS.md) |
|
|
| Sandbox, uploads, MCP, models, extensions | [sandbox](packages/harness/deerflow/sandbox/AGENTS.md), [uploads](packages/harness/deerflow/uploads/AGENTS.md), [mcp](packages/harness/deerflow/mcp/AGENTS.md), [models](packages/harness/deerflow/models/AGENTS.md), [extensions](packages/harness/deerflow/extensions/AGENTS.md) |
|
|
| Trace ID, embedded client, other root modules | [harness package](packages/harness/deerflow/AGENTS.md) |
|
|
| Search, fetch and sandbox providers | [community](packages/harness/deerflow/community/AGENTS.md), then the provider's own guide |
|
|
| Gateway, routers, IM channels | [gateway](app/gateway/AGENTS.md), [routers](app/gateway/routers/AGENTS.md), [channels](app/channels/AGENTS.md) |
|
|
| Tests, benchmarks | [tests](tests/AGENTS.md), [benchmarks](scripts/benchmark/AGENTS.md) |
|
|
|
|
## Verify
|
|
|
|
```bash
|
|
make test # offline suite in parallel shards
|
|
make test-blocking-io # strict blocking-I/O suite
|
|
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. Every
|
|
feature and bug fix ships with a test in `tests/`. Live tests stay opt-in, so the
|
|
default suite needs no network and no API key.
|
|
|
|
## Rules
|
|
|
|
- **The harness never imports `app`.** `app.*` imports `deerflow.*`, and not the
|
|
reverse, because the harness is published on its own.
|
|
`tests/test_harness_boundary.py` enforces this in CI.
|
|
- **Start the Gateway with `make dev` or `make gateway`.** `make dev` excludes
|
|
`DEER_FLOW_HOME` and `backend/sandbox` from the reload watcher. A bare
|
|
`uvicorn --reload` restarts the Gateway during a run, because agent tasks write
|
|
Python files below `DEER_FLOW_HOME`.
|
|
- **From the repository root, run backend tools with
|
|
`uv run --no-sync --project backend`.** `--project` keeps the caller's working
|
|
directory, so relative config paths still resolve. `--no-sync` keeps installed
|
|
extras such as the PostgreSQL drivers.
|
|
- **Run Python through `uv run` inside `backend/`**, 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](docs/RUN_INTERACTION_POLICY.md#hitl-tool-approval).
|
|
- **Add a schema change with `make migrate-rev MSG="..."`** and follow the
|
|
migrations guide.
|