AGENTS.md

1# AGENTS.md
2 
3This file provides guidance to AI coding agents (Claude Code, Codex, and others) when working with code in this repository. It is the source of truth; the sibling `CLAUDE.md` imports it via `@AGENTS.md`.
4 
5It is the **monorepo orientation layer**: it maps the whole repo and points to the
6module guides that own the depth. For anything inside a module, read that module's
7guide rather than expecting full detail here:
8 
9- **[backend/AGENTS.md](backend/AGENTS.md)** — backend depth: harness/app split, agent &
10  middleware chain, sandbox, MCP, skills, memory, IM channels, persistence/migrations,
11  config system, test layout.
12- **[frontend/AGENTS.md](frontend/AGENTS.md)** — frontend depth: Next.js App Router layout,
13  thread/streaming data flow, code style, commands.
14 
15## What is DeerFlow
16 
17DeerFlow is a LangGraph-based AI super-agent system with a full-stack architecture. The
18backend runs a "super agent" with sandboxed execution, persistent memory, subagent
19delegation, and extensible tools (built-in, MCP, community), all per-thread isolated. The
20frontend is a Next.js chat UI. External IM platforms (Feishu, Slack, Telegram, Discord,
21DingTalk) bridge into the same agent through the Gateway.
22 
23## Service Topology
24 
25A single `make dev` / Docker stack runs four cooperating services:
26 
27| Service         | Port   | Role                                                                 |
28| --------------- | ------ | ------------------------------------------------------------------- |
29| **Nginx**       | `2026` | Unified reverse-proxy entry point — open this in the browser        |
30| **Gateway API** | `8001` | FastAPI REST API + embedded LangGraph-compatible agent runtime      |
31| **Frontend**    | `3000` | Next.js web interface                                               |
32| **Provisioner** | `8002` | Optional — only when sandbox is configured for provisioner/K8s mode |
33 
34Nginx is the single public entry: it serves the frontend and proxies `/api/langgraph/*`
35to the Gateway's LangGraph runtime, rewriting it to Gateway's native `/api/*` routes; all
36other `/api/*` go straight to the Gateway REST routers. See
37[backend/AGENTS.md](backend/AGENTS.md) for the runtime and router detail.
38It compresses HTML and configured textual assets, while deliberately leaving SSE,
39fonts, images, audio, and video uncompressed at the proxy layer.
40 
41Both compose files publish that entry as `"${BIND_HOST:-127.0.0.1}:${PORT:-2026}:2026"`
42— **loopback by default**, matching the README's documented deployment model. A bare
43`"${PORT}:2026"` binds `0.0.0.0`, which does not.
44Nginx itself listens `default_server` on IPv4+IPv6 and the
45Gateway binds `0.0.0.0:8001` inside the container on purpose — both are container-
46internal; the published nginx port is the entire external surface, and the Gateway's
47`8001` is deliberately not published. Any new published port needs an explicit bind
48address; `backend/tests/test_compose_default_bind_host.py` pins this for every service
49in both compose files.
50 
51## Repository Map
52 
53```
54deer-flow/
55├── Makefile                        # Root orchestration: drives the full stack (dev/start/stop, docker, setup)
56├── config.example.yaml             # Template → copy to config.yaml (gitignored) at repo root
57├── extensions_config.example.json  # Template → copy to extensions_config.json (gitignored): MCP servers + skills
58├── backend/                        # Python backend — see backend/AGENTS.md
59│   ├── Makefile                    # Per-module backend commands (dev, gateway, test, lint, migrate-rev)
60│   ├── packages/harness/           # deerflow-harness package (import: deerflow.*) — agent framework
61│   └── app/                        # FastAPI Gateway + IM channels (import: app.*)
62├── frontend/                       # Next.js frontend (pnpm) — see frontend/AGENTS.md
63├── docker/                         # docker-compose files, nginx config, provisioner
64├── skills/                         # Agent skills: public/ (committed), custom/ (gitignored)
65│                                    # Managed integration skill packs are global at .deer-flow/integrations/skills/{provider}/
66│                                    # Integration credentials and enabled state remain per-user
67├── contracts/                      # Cross-component JSON contracts (e.g. subagent status, skill review)
68├── scripts/                        # Root orchestration scripts invoked by the Makefile (check, configure, doctor, support_bundle, serve, nginx, docker, deploy, setup_wizard)
69├── tests/                          # Root-level tests (currently tests/skills/ — public skill tests)
70└── docs/                           # Cross-cutting docs, plans, and design notes
71```
72 
73Runtime config lives at the **repo root**: copy `config.example.yaml` → `config.yaml`
74(main app config) and `extensions_config.example.json` → `extensions_config.json` (MCP
75servers + skills). Both real files are gitignored and may be edited at runtime via the
76Gateway API. Config schema and resolution order are documented in
77[backend/AGENTS.md](backend/AGENTS.md).
78 
79Skill quality review note:
80- `skills/public/skill-reviewer/` is the built-in read-only skill quality reviewer.
81  It uses the harness-layer `review_skill_package` tool and contracts in
82  `contracts/skill_review/`. Model-visible review data is compact and
83  tag-neutralized; full raw payloads stay in tool artifacts. See
84  [backend/AGENTS.md](backend/AGENTS.md) for the non-activation, SkillScan, and
85  `skill-creator` ownership boundaries.
86 
87Scheduled-task note:
88- The scheduled-task MVP adds a workspace page at `/workspace/scheduled-tasks` plus a background scheduler service gated by `config.yaml -> scheduler.enabled`.
89- Scheduled background runs are intentionally non-interactive: they execute through the normal run lifecycle, but the lead-agent toolset excludes `ask_clarification` when `context.non_interactive=true`. The key is honored only for internally-authenticated callers (the scheduler launch path); client-supplied `context.non_interactive` is dropped.
90 
91## Commands: Root vs. Module
92 
93**Root `make` targets drive the whole stack** (run from the repo root):
94 
95```bash
96make setup       # Interactive setup wizard (recommended for new users)
97make doctor      # Check configuration and system requirements
98make support-bundle  # Generate redacted troubleshooting summary, AI issue draft, and optional zip
99make config      # Generate local config files from the examples
100make check       # Check that required tools are installed
101make install     # Install all dependencies (frontend + backend + pre-commit hooks)
102make dev         # Start all services with hot-reload (Gateway + Frontend + Nginx)
103make start       # Start all services in production mode (local, optimized)
104make stop        # Stop all running services
105make up / down   # Build/stop the production Docker stack (browser at localhost:2026)
106make docker-start / docker-stop / docker-logs   # Docker development environment
107```
108 
109Run `make help` for the full list.
110 
111**Per-module commands drive a single module** (run inside that module):
112 
113```bash
114# Backend (see backend/AGENTS.md for the full set)
115cd backend && make dev        # Gateway API with reload (port 8001)
116cd backend && make test       # Backend test suite
117cd backend && make lint       # ruff check
118cd backend && make format     # ruff format
119 
120# Frontend (see frontend/AGENTS.md for the full set)
121cd frontend && pnpm dev       # Dev server with Turbopack (port 3000)
122cd frontend && pnpm check     # Lint + type check (run before committing)
123cd frontend && pnpm test      # Unit tests
124```
125 
126Rule of thumb: **root `make` = the full application**; **`backend/Makefile` and `frontend/`
127(`pnpm`) = per-module work.**
128 
129Host-side pnpm consumers, including the root/frontend Makefiles and local diagnostic scripts, must run through `scripts/pnpm.py`. The runner preserves direct `pnpm`/`pnpm.cmd` priority, falls back to `corepack pnpm`, and is invoked from `frontend/` so Corepack honors the package-manager version pinned by that project.
130 
131## Where to Go Next
132 
133- Backend work → **[backend/AGENTS.md](backend/AGENTS.md)**
134- Frontend work → **[frontend/AGENTS.md](frontend/AGENTS.md)**
135- Setup & install → **[Install.md](Install.md)**, **[CONTRIBUTING.md](CONTRIBUTING.md)**
136- Project overview & usage → **[README.md](README.md)** (translations: `README_zh.md`,
137  `README_ja.md`, `README_fr.md`, `README_ru.md`)
138- Security policy → **[SECURITY.md](SECURITY.md)**
139- Changes → **[CHANGELOG.md](CHANGELOG.md)**
140- Cutting a release → **[RELEASING.md](RELEASING.md)**
141 
142## Cross-Cutting Conventions
143 
144These apply repo-wide; module guides own the module-specific detail.
145 
146- **Documentation update policy** — keep docs in sync with code: update `README.md` for
147  user-facing changes and the relevant `AGENTS.md` for development/architecture changes in
148  the same change set.
149- **Test-driven development** — features and bug fixes ship with tests. Backend tests live
150  in `backend/tests/` (TDD is mandatory there; see [backend/AGENTS.md](backend/AGENTS.md));
151  frontend tests live in `frontend/tests/`.
152- **Format before pushing** — run `make format` (backend) / `pnpm check` (frontend). Backend
153  CI enforces `ruff format --check`, so formatting must be clean before a push.
154