mirror of
https://github.com/bytedance/deer-flow.git
synced 2026-08-10 23:08:45 +00:00
cf02646489
* feat(scripts): add redacted community support bundle generator Add `make support-bundle` (scripts/support_bundle.py) to help users file high-signal, privacy-safe GitHub issues for local setup/config/runtime problems. The command produces: - `*-issue-summary.md` to paste into the issue body - `*-issue-draft.md` scaffold for AI-assisted filing (REQUIRED placeholders, never invents repro/expected/summary facts) - an optional evidence zip under `.deer-flow/support-bundles/` containing a stable `triage.json` plus redacted environment/config/extensions/git/doctor evidence Privacy: secrets are redacted across config values, URL userinfo, query strings, CLI flags, custom headers, bearer/sk- tokens, and home paths. The bundle never includes `.env`, raw conversation messages, or user file contents; optional `--thread-id` adds file manifests only. `thread_id` input is validated against path traversal. Wire it into the Makefile, AGENTS.md, README/README_zh, CONTRIBUTING, and the bug-report issue template. Covered by backend/tests/test_support_bundle.py. * fix(scripts): redact MCP env values by default in support bundle Address PR #3886 review (willem-bd, P2): the key-name allowlist let literal secrets under non-standard env keys (e.g. SUPABASE_SERVICE_ROLE_KEY, R2_ACCESS_KEY, hardcoded AIza… keys) leak verbatim into the bundle that users are told is safe to share publicly. Mask all MCP `env` values by default, keeping only `$VAR`/`${VAR}` references visible, and broaden SECRET_KEY_RE (access_key, pwd, private_key). Add tests for non-keyword env secrets, broadened key names, and end-to-end zip redaction.
125 lines
6.8 KiB
Markdown
125 lines
6.8 KiB
Markdown
# AGENTS.md
|
|
|
|
This 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`.
|
|
|
|
It is the **monorepo orientation layer**: it maps the whole repo and points to the
|
|
module guides that own the depth. For anything inside a module, read that module's
|
|
guide rather than expecting full detail here:
|
|
|
|
- **[backend/AGENTS.md](backend/AGENTS.md)** — backend depth: harness/app split, agent &
|
|
middleware chain, sandbox, MCP, skills, memory, IM channels, persistence/migrations,
|
|
config system, test layout.
|
|
- **[frontend/AGENTS.md](frontend/AGENTS.md)** — frontend depth: Next.js App Router layout,
|
|
thread/streaming data flow, code style, commands.
|
|
|
|
## What is DeerFlow
|
|
|
|
DeerFlow is a LangGraph-based AI super-agent system with a full-stack architecture. The
|
|
backend runs a "super agent" with sandboxed execution, persistent memory, subagent
|
|
delegation, and extensible tools (built-in, MCP, community), all per-thread isolated. The
|
|
frontend is a Next.js chat UI. External IM platforms (Feishu, Slack, Telegram, Discord,
|
|
DingTalk) bridge into the same agent through the Gateway.
|
|
|
|
## Service Topology
|
|
|
|
A single `make dev` / Docker stack runs four cooperating services:
|
|
|
|
| Service | Port | Role |
|
|
| --------------- | ------ | ------------------------------------------------------------------- |
|
|
| **Nginx** | `2026` | Unified reverse-proxy entry point — open this in the browser |
|
|
| **Gateway API** | `8001` | FastAPI REST API + embedded LangGraph-compatible agent runtime |
|
|
| **Frontend** | `3000` | Next.js web interface |
|
|
| **Provisioner** | `8002` | Optional — only when sandbox is configured for provisioner/K8s mode |
|
|
|
|
Nginx is the single public entry: it serves the frontend and proxies `/api/langgraph/*`
|
|
to the Gateway's LangGraph runtime, rewriting it to Gateway's native `/api/*` routes; all
|
|
other `/api/*` go straight to the Gateway REST routers. See
|
|
[backend/AGENTS.md](backend/AGENTS.md) for the runtime and router detail.
|
|
|
|
## Repository Map
|
|
|
|
```
|
|
deer-flow/
|
|
├── Makefile # Root orchestration: drives the full stack (dev/start/stop, docker, setup)
|
|
├── config.example.yaml # Template → copy to config.yaml (gitignored) at repo root
|
|
├── extensions_config.example.json # Template → copy to extensions_config.json (gitignored): MCP servers + skills
|
|
├── backend/ # Python backend — see backend/AGENTS.md
|
|
│ ├── Makefile # Per-module backend commands (dev, gateway, test, lint, migrate-rev)
|
|
│ ├── packages/harness/ # deerflow-harness package (import: deerflow.*) — agent framework
|
|
│ └── app/ # FastAPI Gateway + IM channels (import: app.*)
|
|
├── frontend/ # Next.js frontend (pnpm) — see frontend/AGENTS.md
|
|
├── docker/ # docker-compose files, nginx config, provisioner
|
|
├── skills/ # Agent skills: public/ (committed), custom/ (gitignored)
|
|
├── contracts/ # Cross-component JSON contracts (e.g. subagent status)
|
|
├── scripts/ # Root orchestration scripts invoked by the Makefile (check, configure, doctor, support_bundle, serve, docker, deploy, setup_wizard)
|
|
├── tests/ # Root-level tests (currently tests/skills/ — public skill tests)
|
|
└── docs/ # Cross-cutting docs, plans, and design notes
|
|
```
|
|
|
|
Runtime config lives at the **repo root**: copy `config.example.yaml` → `config.yaml`
|
|
(main app config) and `extensions_config.example.json` → `extensions_config.json` (MCP
|
|
servers + skills). Both real files are gitignored and may be edited at runtime via the
|
|
Gateway API. Config schema and resolution order are documented in
|
|
[backend/AGENTS.md](backend/AGENTS.md).
|
|
|
|
## Commands: Root vs. Module
|
|
|
|
**Root `make` targets drive the whole stack** (run from the repo root):
|
|
|
|
```bash
|
|
make setup # Interactive setup wizard (recommended for new users)
|
|
make doctor # Check configuration and system requirements
|
|
make support-bundle # Generate redacted troubleshooting summary, AI issue draft, and optional zip
|
|
make config # Generate local config files from the examples
|
|
make check # Check that required tools are installed
|
|
make install # Install all dependencies (frontend + backend + pre-commit hooks)
|
|
make dev # Start all services with hot-reload (Gateway + Frontend + Nginx)
|
|
make start # Start all services in production mode (local, optimized)
|
|
make stop # Stop all running services
|
|
make up / down # Build/stop the production Docker stack (browser at localhost:2026)
|
|
make docker-start / docker-stop / docker-logs # Docker development environment
|
|
```
|
|
|
|
Run `make help` for the full list.
|
|
|
|
**Per-module commands drive a single module** (run inside that module):
|
|
|
|
```bash
|
|
# Backend (see backend/AGENTS.md for the full set)
|
|
cd backend && make dev # Gateway API with reload (port 8001)
|
|
cd backend && make test # Backend test suite
|
|
cd backend && make lint # ruff check
|
|
cd backend && make format # ruff format
|
|
|
|
# Frontend (see frontend/AGENTS.md for the full set)
|
|
cd frontend && pnpm dev # Dev server with Turbopack (port 3000)
|
|
cd frontend && pnpm check # Lint + type check (run before committing)
|
|
cd frontend && pnpm test # Unit tests
|
|
```
|
|
|
|
Rule of thumb: **root `make` = the full application**; **`backend/Makefile` and `frontend/`
|
|
(`pnpm`) = per-module work.**
|
|
|
|
## Where to Go Next
|
|
|
|
- Backend work → **[backend/AGENTS.md](backend/AGENTS.md)**
|
|
- Frontend work → **[frontend/AGENTS.md](frontend/AGENTS.md)**
|
|
- Setup & install → **[Install.md](Install.md)**, **[CONTRIBUTING.md](CONTRIBUTING.md)**
|
|
- Project overview & usage → **[README.md](README.md)** (translations: `README_zh.md`,
|
|
`README_ja.md`, `README_fr.md`, `README_ru.md`)
|
|
- Security policy → **[SECURITY.md](SECURITY.md)**
|
|
- Changes → **[CHANGELOG.md](CHANGELOG.md)**
|
|
|
|
## Cross-Cutting Conventions
|
|
|
|
These apply repo-wide; module guides own the module-specific detail.
|
|
|
|
- **Documentation update policy** — keep docs in sync with code: update `README.md` for
|
|
user-facing changes and the relevant `AGENTS.md` for development/architecture changes in
|
|
the same change set.
|
|
- **Test-driven development** — features and bug fixes ship with tests. Backend tests live
|
|
in `backend/tests/` (TDD is mandatory there; see [backend/AGENTS.md](backend/AGENTS.md));
|
|
frontend tests live in `frontend/tests/`.
|
|
- **Format before pushing** — run `make format` (backend) / `pnpm check` (frontend). Backend
|
|
CI enforces `ruff format --check`, so formatting must be clean before a push.
|