From 28381e1383cdd1a4ec57a659e965c46c1cd7cf6d Mon Sep 17 00:00:00 2001 From: Willem Jiang Date: Sun, 26 Apr 2026 15:11:22 +0800 Subject: [PATCH] fix the lint errors in frontend --- .../content/en/application/configuration.mdx | 35 +++++++----- .../en/application/deployment-guide.mdx | 2 +- frontend/src/content/en/application/index.mdx | 35 ++++++------ .../operations-and-troubleshooting.mdx | 17 +++--- .../content/en/application/quick-start.mdx | 30 ++++++----- .../en/application/workspace-usage.mdx | 5 +- .../src/content/en/harness/configuration.mdx | 54 ++++++++++--------- .../src/content/en/harness/customization.mdx | 5 +- .../content/en/harness/design-principles.mdx | 18 +++---- .../src/content/en/harness/lead-agent.mdx | 6 +-- frontend/src/content/en/harness/mcp.mdx | 2 + .../src/content/en/harness/middlewares.mdx | 8 +-- .../src/content/en/harness/quick-start.mdx | 21 ++++---- frontend/src/content/en/harness/sandbox.mdx | 16 +++--- frontend/src/content/en/harness/skills.mdx | 38 ++++++------- frontend/src/content/en/harness/subagents.mdx | 8 +-- frontend/src/content/en/harness/tools.mdx | 54 ++++++++----------- .../en/tutorials/first-conversation.mdx | 3 ++ .../en/tutorials/use-tools-and-skills.mdx | 1 + .../content/en/tutorials/work-with-memory.mdx | 2 + .../zh/application/agents-and-threads.mdx | 8 ++- .../content/zh/application/configuration.mdx | 47 ++++++++-------- .../zh/application/deployment-guide.mdx | 52 ++++++++++-------- frontend/src/content/zh/application/index.mdx | 36 +++++++------ .../operations-and-troubleshooting.mdx | 21 +++++--- .../content/zh/application/quick-start.mdx | 32 ++++++----- .../zh/application/workspace-usage.mdx | 18 +++++-- .../src/content/zh/harness/configuration.mdx | 45 ++++++++-------- .../src/content/zh/harness/customization.mdx | 4 +- .../content/zh/harness/design-principles.mdx | 19 +++---- frontend/src/content/zh/harness/index.mdx | 3 +- .../content/zh/harness/integration-guide.mdx | 3 +- .../src/content/zh/harness/lead-agent.mdx | 7 ++- frontend/src/content/zh/harness/memory.mdx | 3 +- .../src/content/zh/harness/middlewares.mdx | 12 +++-- .../src/content/zh/harness/quick-start.mdx | 16 +++--- frontend/src/content/zh/harness/sandbox.mdx | 18 ++++--- frontend/src/content/zh/harness/skills.mdx | 45 ++++++++-------- frontend/src/content/zh/harness/subagents.mdx | 11 ++-- frontend/src/content/zh/harness/tools.mdx | 39 +++++++------- frontend/src/content/zh/index.mdx | 1 - .../content/zh/introduction/core-concepts.mdx | 3 +- .../zh/introduction/harness-vs-app.mdx | 3 +- .../content/zh/introduction/why-deerflow.mdx | 3 +- .../zh/tutorials/first-conversation.mdx | 2 + .../content/zh/tutorials/work-with-memory.mdx | 2 + 46 files changed, 456 insertions(+), 357 deletions(-) diff --git a/frontend/src/content/en/application/configuration.mdx b/frontend/src/content/en/application/configuration.mdx index fb0fedc89..3eeca52a1 100644 --- a/frontend/src/content/en/application/configuration.mdx +++ b/frontend/src/content/en/application/configuration.mdx @@ -11,10 +11,10 @@ DeerFlow App is configured through two files and a set of environment variables. ## Configuration files -| File | Purpose | -|---|---| -| `config.yaml` | Backend configuration: models, sandbox, tools, skills, memory, and all Harness settings | -| `extensions_config.json` | MCP servers and skill enable/disable state (managed by the App UI and Gateway API) | +| File | Purpose | +| ------------------------ | --------------------------------------------------------------------------------------- | +| `config.yaml` | Backend configuration: models, sandbox, tools, skills, memory, and all Harness settings | +| `extensions_config.json` | MCP servers and skill enable/disable state (managed by the App UI and Gateway API) | Frontend environment variables control the Next.js build and runtime behavior. @@ -144,6 +144,7 @@ sandbox: ``` Install: `cd backend && uv add 'deerflow-harness[aio-sandbox]'` + ```yaml @@ -161,7 +162,7 @@ Configure which tools the agent has access to. The defaults use DuckDuckGo (no A ```yaml tools: # Web search (choose one) - - use: deerflow.community.ddg_search.tools:web_search_tool # default, no key required + - use: deerflow.community.ddg_search.tools:web_search_tool # default, no key required # - use: deerflow.community.tavily.tools:web_search_tool # api_key: $TAVILY_API_KEY @@ -188,7 +189,7 @@ By default, DeerFlow uses an SQLite checkpointer for thread state persistence: ```yaml checkpointer: type: sqlite - connection_string: checkpoints.db # stored in backend/.deer-flow/ + connection_string: checkpoints.db # stored in backend/.deer-flow/ ``` For production deployments with multiple processes: @@ -224,12 +225,12 @@ memory: Set these before running `pnpm build` or starting the frontend in production: -| Variable | Required | Description | -|---|---|---| -| `BETTER_AUTH_SECRET` | **Required** in production | Secret for session signing. Use `openssl rand -base64 32`. | -| `BETTER_AUTH_URL` | Recommended | Public-facing base URL (e.g., `https://your-domain.com`) | -| `SKIP_ENV_VALIDATION` | Optional | Set to `1` to skip env validation during build (not recommended) | -| `NEXT_PUBLIC_API_URL` | Optional | Override the API base URL for the frontend | +| Variable | Required | Description | +| --------------------- | -------------------------- | ---------------------------------------------------------------- | +| `BETTER_AUTH_SECRET` | **Required** in production | Secret for session signing. Use `openssl rand -base64 32`. | +| `BETTER_AUTH_URL` | Recommended | Public-facing base URL (e.g., `https://your-domain.com`) | +| `SKIP_ENV_VALIDATION` | Optional | Set to `1` to skip env validation during build (not recommended) | +| `NEXT_PUBLIC_API_URL` | Optional | Override the API base URL for the frontend | In development, set these in a `.env` file at the repo root: @@ -268,6 +269,12 @@ make config-upgrade ``` - - + + diff --git a/frontend/src/content/en/application/deployment-guide.mdx b/frontend/src/content/en/application/deployment-guide.mdx index 8d5542dbb..04b3599c0 100644 --- a/frontend/src/content/en/application/deployment-guide.mdx +++ b/frontend/src/content/en/application/deployment-guide.mdx @@ -1,5 +1,5 @@ --- -title: Deployment Guide +title: Deployment Guide description: "This guide covers all supported deployment methods for DeerFlow App: local development, Docker Compose, and production with Kubernetes-managed sandboxes." --- diff --git a/frontend/src/content/en/application/index.mdx b/frontend/src/content/en/application/index.mdx index f61f18775..2cb15a911 100644 --- a/frontend/src/content/en/application/index.mdx +++ b/frontend/src/content/en/application/index.mdx @@ -17,15 +17,15 @@ DeerFlow App is the reference implementation of what a production DeerFlow exper ## What the App provides -| Capability | Description | -|---|---| -| **Web workspace** | Browser-based conversation UI with support for threads, artifacts, file uploads, and skill selection | -| **Custom agents** | Create and manage named agents with different models, skills, and tool sets | -| **Thread management** | Persistent conversation threads with checkpointing and history | -| **Streaming responses** | Real-time token streaming with thinking steps and tool call visibility | -| **Artifact viewer** | In-browser preview and download of files and outputs produced by the agent | -| **Extensions UI** | Enable/disable MCP servers and skills without editing config files | -| **Gateway API** | FastAPI-based REST API that bridges the frontend and the LangGraph runtime | +| Capability | Description | +| ----------------------- | ---------------------------------------------------------------------------------------------------- | +| **Web workspace** | Browser-based conversation UI with support for threads, artifacts, file uploads, and skill selection | +| **Custom agents** | Create and manage named agents with different models, skills, and tool sets | +| **Thread management** | Persistent conversation threads with checkpointing and history | +| **Streaming responses** | Real-time token streaming with thinking steps and tool call visibility | +| **Artifact viewer** | In-browser preview and download of files and outputs produced by the agent | +| **Extensions UI** | Enable/disable MCP servers and skills without editing config files | +| **Gateway API** | FastAPI-based REST API that bridges the frontend and the LangGraph runtime | ## Architecture @@ -58,15 +58,18 @@ The DeerFlow App runs as four services behind a single nginx reverse proxy: ## Technology stack -| Layer | Technology | -|---|---| -| Frontend | Next.js 16, React 19, TypeScript, pnpm | -| Gateway | FastAPI, Python 3.12, uvicorn | -| Agent runtime | LangGraph, LangChain, DeerFlow Harness | -| Reverse proxy | nginx | +| Layer | Technology | +| ----------------- | -------------------------------------------------------------------- | +| Frontend | Next.js 16, React 19, TypeScript, pnpm | +| Gateway | FastAPI, Python 3.12, uvicorn | +| Agent runtime | LangGraph, LangChain, DeerFlow Harness | +| Reverse proxy | nginx | | State persistence | LangGraph Server (default) + optional SQLite/PostgreSQL checkpointer | - + diff --git a/frontend/src/content/en/application/operations-and-troubleshooting.mdx b/frontend/src/content/en/application/operations-and-troubleshooting.mdx index e12f4d4f1..8b21cf4b4 100644 --- a/frontend/src/content/en/application/operations-and-troubleshooting.mdx +++ b/frontend/src/content/en/application/operations-and-troubleshooting.mdx @@ -13,12 +13,12 @@ This page covers day-to-day operational tasks and solutions to common problems w All services write logs to the `logs/` directory when started with `make dev`: -| File | Service | -|---|---| +| File | Service | +| -------------------- | ------------------------------------ | | `logs/langgraph.log` | LangGraph / DeerFlow Harness runtime | -| `logs/gateway.log` | FastAPI Gateway API | -| `logs/frontend.log` | Next.js frontend dev server | -| `logs/nginx.log` | nginx reverse proxy | +| `logs/gateway.log` | FastAPI Gateway API | +| `logs/frontend.log` | Next.js frontend dev server | +| `logs/nginx.log` | nginx reverse proxy | Tail logs in real time: @@ -30,7 +30,7 @@ tail -f logs/gateway.log Adjust the runtime log level in `config.yaml`: ```yaml -log_level: debug # debug | info | warning | error +log_level: debug # debug | info | warning | error ``` ## Health checks @@ -171,6 +171,9 @@ make dev Individual service restart scripts are in `scripts/`. For targeted restarts, you can kill and relaunch individual processes manually using the PIDs in the log files. - + diff --git a/frontend/src/content/en/application/quick-start.mdx b/frontend/src/content/en/application/quick-start.mdx index d9b4a3e7d..5ecfb3a26 100644 --- a/frontend/src/content/en/application/quick-start.mdx +++ b/frontend/src/content/en/application/quick-start.mdx @@ -24,13 +24,13 @@ make check Required: -| Tool | Minimum version | -|---|---| -| Python | 3.12 | -| uv | latest | -| Node.js | 22 | -| pnpm | 10 | -| nginx | any recent version | +| Tool | Minimum version | +| ------- | ------------------ | +| Python | 3.12 | +| uv | latest | +| Node.js | 22 | +| pnpm | 10 | +| nginx | any recent version | On macOS, install with `brew install python uv node pnpm nginx`. On Linux, use your distribution's package manager. @@ -87,6 +87,7 @@ make dev ``` This starts: + - LangGraph server on port `2024` - Gateway API on port `8001` - Frontend on port `3000` @@ -110,12 +111,12 @@ make stop Log files: -| Service | Log file | -|---|---| +| Service | Log file | +| --------- | -------------------- | | LangGraph | `logs/langgraph.log` | -| Gateway | `logs/gateway.log` | -| Frontend | `logs/frontend.log` | -| nginx | `logs/nginx.log` | +| Gateway | `logs/gateway.log` | +| Frontend | `logs/frontend.log` | +| nginx | `logs/nginx.log` | If something is not working, check the log files first. Most startup errors @@ -124,6 +125,9 @@ Log files: - + diff --git a/frontend/src/content/en/application/workspace-usage.mdx b/frontend/src/content/en/application/workspace-usage.mdx index 8589c624c..686614aa7 100644 --- a/frontend/src/content/en/application/workspace-usage.mdx +++ b/frontend/src/content/en/application/workspace-usage.mdx @@ -74,6 +74,9 @@ If you have created custom agents, use the **Agent** selector in the input bar t Custom agents may have different models, skills, tool sets, and system prompts. See [Agents and Threads](/docs/application/agents-and-threads) for how to create and manage custom agents. - + diff --git a/frontend/src/content/en/harness/configuration.mdx b/frontend/src/content/en/harness/configuration.mdx index 8043e2beb..89de12716 100644 --- a/frontend/src/content/en/harness/configuration.mdx +++ b/frontend/src/content/en/harness/configuration.mdx @@ -81,7 +81,7 @@ models: use: langchain_openai:ChatOpenAI model: gpt-4o api_key: $OPENAI_API_KEY - some_provider_specific_option: value # passed through to ChatOpenAI constructor + some_provider_specific_option: value # passed through to ChatOpenAI constructor ``` ## Configuration version @@ -104,27 +104,27 @@ This merges new fields from `config.example.yaml` into your existing `config.yam The following table maps each top-level `config.yaml` section to its documentation page: -| Section | Description | Documentation | -|---|---|---| -| `log_level` | Logging level (`debug`/`info`/`warning`/`error`) | — | -| `models` | Available LLM models | [Lead Agent](/docs/harness/lead-agent) | -| `token_usage` | Token tracking per model call | [Middlewares](/docs/harness/middlewares) | -| `tools` | Available agent tools | [Tools](/docs/harness/tools) | -| `tool_groups` | Named groups of tools | [Tools](/docs/harness/tools) | -| `tool_search` | Deferred/on-demand tool loading | [Tools](/docs/harness/tools) | -| `sandbox` | Sandbox provider and options | [Sandbox](/docs/harness/sandbox) | -| `skills` | Skills directory and container path | [Skills](/docs/harness/skills) | -| `skill_evolution` | Agent-managed skill creation | [Skills](/docs/harness/skills) | -| `subagents` | Subagent timeouts and max turns | [Subagents](/docs/harness/subagents) | -| `acp_agents` | External ACP agent integrations | [Subagents](/docs/harness/subagents) | -| `memory` | Cross-session memory storage | [Memory](/docs/harness/memory) | -| `summarization` | Conversation summarization | [Middlewares](/docs/harness/middlewares) | -| `title` | Automatic thread title generation | [Middlewares](/docs/harness/middlewares) | -| `checkpointer` | Thread state persistence | [Agents & Threads](/docs/application/agents-and-threads) | -| `guardrails` | Tool call authorization | — | -| `stream_bridge` | Streaming configuration | — | -| `uploads` | File upload settings (PDF converter) | — | -| `channels` | IM channel integrations (Feishu, Slack, etc.) | — | +| Section | Description | Documentation | +| ----------------- | ------------------------------------------------ | -------------------------------------------------------- | +| `log_level` | Logging level (`debug`/`info`/`warning`/`error`) | — | +| `models` | Available LLM models | [Lead Agent](/docs/harness/lead-agent) | +| `token_usage` | Token tracking per model call | [Middlewares](/docs/harness/middlewares) | +| `tools` | Available agent tools | [Tools](/docs/harness/tools) | +| `tool_groups` | Named groups of tools | [Tools](/docs/harness/tools) | +| `tool_search` | Deferred/on-demand tool loading | [Tools](/docs/harness/tools) | +| `sandbox` | Sandbox provider and options | [Sandbox](/docs/harness/sandbox) | +| `skills` | Skills directory and container path | [Skills](/docs/harness/skills) | +| `skill_evolution` | Agent-managed skill creation | [Skills](/docs/harness/skills) | +| `subagents` | Subagent timeouts and max turns | [Subagents](/docs/harness/subagents) | +| `acp_agents` | External ACP agent integrations | [Subagents](/docs/harness/subagents) | +| `memory` | Cross-session memory storage | [Memory](/docs/harness/memory) | +| `summarization` | Conversation summarization | [Middlewares](/docs/harness/middlewares) | +| `title` | Automatic thread title generation | [Middlewares](/docs/harness/middlewares) | +| `checkpointer` | Thread state persistence | [Agents & Threads](/docs/application/agents-and-threads) | +| `guardrails` | Tool call authorization | — | +| `stream_bridge` | Streaming configuration | — | +| `uploads` | File upload settings (PDF converter) | — | +| `channels` | IM channel integrations (Feishu, Slack, etc.) | — | ## Minimal config to get started @@ -157,6 +157,12 @@ tools: Start from `config.example.yaml` in the repository root and uncomment the sections you need. - - + + diff --git a/frontend/src/content/en/harness/customization.mdx b/frontend/src/content/en/harness/customization.mdx index 9d8c6b934..2f538aeb6 100644 --- a/frontend/src/content/en/harness/customization.mdx +++ b/frontend/src/content/en/harness/customization.mdx @@ -170,6 +170,9 @@ guardrails: For custom guardrail logic, implement a class with `evaluate()` and `aevaluate()` methods and reference it via `use:`. - + diff --git a/frontend/src/content/en/harness/design-principles.mdx b/frontend/src/content/en/harness/design-principles.mdx index bda534217..e741f6d74 100644 --- a/frontend/src/content/en/harness/design-principles.mdx +++ b/frontend/src/content/en/harness/design-principles.mdx @@ -110,15 +110,15 @@ Environment variable interpolation (`api_key: $OPENAI_API_KEY`) keeps secrets ou ## Summary -| Principle | What it means in practice | -|---|---| -| Harness, not framework | Ready-to-run runtime with all the infrastructure already wired | -| Long-horizon first | Architecture assumes multi-step, multi-tool, multi-turn tasks | -| Middleware over inheritance | Behavior is composed from small, isolated plugins | -| Skills for specialization | Domain capability injected on demand, keeping the base clean | -| Sandbox for execution | Isolated workspace for real file and command work | -| Context engineering | Active management of what the agent sees to stay effective | -| Config-driven | All key behaviors are controlled through `config.yaml` | +| Principle | What it means in practice | +| --------------------------- | -------------------------------------------------------------- | +| Harness, not framework | Ready-to-run runtime with all the infrastructure already wired | +| Long-horizon first | Architecture assumes multi-step, multi-tool, multi-turn tasks | +| Middleware over inheritance | Behavior is composed from small, isolated plugins | +| Skills for specialization | Domain capability injected on demand, keeping the base clean | +| Sandbox for execution | Isolated workspace for real file and command work | +| Context engineering | Active management of what the agent sees to stay effective | +| Config-driven | All key behaviors are controlled through `config.yaml` | diff --git a/frontend/src/content/en/harness/lead-agent.mdx b/frontend/src/content/en/harness/lead-agent.mdx index 4aafa80a1..ee89888c0 100644 --- a/frontend/src/content/en/harness/lead-agent.mdx +++ b/frontend/src/content/en/harness/lead-agent.mdx @@ -141,9 +141,9 @@ The same Lead Agent runtime powers both the default agent and any custom agents Custom agents are created through the DeerFlow App UI or via the `/api/agents` endpoint. Their configuration is stored in `agents/{name}/config.yaml` relative to the backend directory. - When a custom agent is selected in a thread, the Lead Agent loads that - agent's config at runtime. Switching models or skills for a specific agent - does not require restarting the server. + When a custom agent is selected in a thread, the Lead Agent loads that agent's + config at runtime. Switching models or skills for a specific agent does not + require restarting the server. ## Bootstrap mode diff --git a/frontend/src/content/en/harness/mcp.mdx b/frontend/src/content/en/harness/mcp.mdx index 0ea0f186d..0e43aa235 100644 --- a/frontend/src/content/en/harness/mcp.mdx +++ b/frontend/src/content/en/harness/mcp.mdx @@ -44,6 +44,7 @@ The default location is the project root (same directory as `config.yaml`). The ``` Each server entry supports: + - `command`: the executable to run (e.g., `npx`, `uvx`, `python`) - `args`: command arguments as an array - `enabled`: whether the server is active (can be toggled without removing the entry) @@ -92,6 +93,7 @@ With tool search enabled, MCP tools are listed by name in the system prompt but Some MCP servers require OAuth authentication. DeerFlow's `mcp/oauth.py` handles the OAuth flow for servers that declare OAuth requirements in their capability headers. When an OAuth-protected MCP server is connected, DeerFlow will: + 1. Detect the OAuth requirement from the server's capability headers 2. Build the appropriate authorization headers using `get_initial_oauth_headers()` 3. Wrap tool calls with an OAuth interceptor via `build_oauth_tool_interceptor()` diff --git a/frontend/src/content/en/harness/middlewares.mdx b/frontend/src/content/en/harness/middlewares.mdx index fca391cf3..70c499925 100644 --- a/frontend/src/content/en/harness/middlewares.mdx +++ b/frontend/src/content/en/harness/middlewares.mdx @@ -89,7 +89,7 @@ title: enabled: true max_words: 6 max_chars: 60 - model_name: null # use default model + model_name: null # use default model ``` --- @@ -159,7 +159,7 @@ summarization: # Trigger conditions — summarization runs when ANY threshold is met trigger: - - type: tokens # trigger when context exceeds N tokens + - type: tokens # trigger when context exceeds N tokens value: 15564 # - type: messages # trigger when there are more than N messages # value: 50 @@ -169,7 +169,7 @@ summarization: # How much recent history to keep after summarization keep: type: messages - value: 10 # keep the 10 most recent messages + value: 10 # keep the 10 most recent messages # Alternative: keep by tokens # type: tokens # value: 3000 @@ -182,6 +182,7 @@ summarization: ``` **Trigger types**: + - `tokens`: triggers when the total token count in the conversation exceeds `value`. - `messages`: triggers when the number of messages exceeds `value`. - `fraction`: triggers when the context reaches `value` fraction of the model's maximum input token limit. @@ -189,6 +190,7 @@ summarization: Multiple triggers can be listed; summarization runs when **any** of them fires. **Keep types**: + - `messages`: keep the last `value` messages after summarization. - `tokens`: keep up to `value` tokens of recent history. - `fraction`: keep up to `value` fraction of the model's max input token limit. diff --git a/frontend/src/content/en/harness/quick-start.mdx b/frontend/src/content/en/harness/quick-start.mdx index 5327e6773..b253a122c 100644 --- a/frontend/src/content/en/harness/quick-start.mdx +++ b/frontend/src/content/en/harness/quick-start.mdx @@ -85,15 +85,15 @@ agent = create_deerflow_agent( Common parameters: -| Parameter | Description | -|---|---| -| `tools` | Additional tools available to the agent | -| `system_prompt` | Custom system prompt | -| `features` | Enable or replace built-in runtime features | +| Parameter | Description | +| ------------------ | ----------------------------------------------- | +| `tools` | Additional tools available to the agent | +| `system_prompt` | Custom system prompt | +| `features` | Enable or replace built-in runtime features | | `extra_middleware` | Insert custom middleware into the default chain | -| `plan_mode` | Enable Todo-style task tracking | -| `checkpointer` | Persist agent state across runs | -| `name` | Logical agent name | +| `plan_mode` | Enable Todo-style task tracking | +| `checkpointer` | Persist agent state across runs | +| `name` | Logical agent name | ## When to use DeerFlowClient instead @@ -109,7 +109,10 @@ Use `DeerFlowClient` when you want the higher-level embedded app interface, such ## Next steps - + diff --git a/frontend/src/content/en/harness/sandbox.mdx b/frontend/src/content/en/harness/sandbox.mdx index 203e5c44d..b1ba74b13 100644 --- a/frontend/src/content/en/harness/sandbox.mdx +++ b/frontend/src/content/en/harness/sandbox.mdx @@ -9,8 +9,8 @@ import { Callout, Cards, Tabs } from "nextra/components"; The sandbox is the isolated workspace where the agent does file and - command-based work. It is what makes DeerFlow capable of real action, not - just conversation. + command-based work. It is what makes DeerFlow capable of real action, not just + conversation. The sandbox gives the Lead Agent a controlled environment where it can read files, write outputs, run shell commands, and produce artifacts. Without a sandbox, the agent can only generate text. With a sandbox, it can write and execute code, process data files, generate charts, and build deliverables. @@ -29,7 +29,7 @@ Commands run directly on the host machine's filesystem. There is no container is ```yaml sandbox: use: deerflow.sandbox.local:LocalSandboxProvider - allow_host_bash: false # default; set to true only for fully trusted workflows + allow_host_bash: false # default; set to true only for fully trusted workflows ``` ### Container-based AIO Sandbox @@ -83,10 +83,10 @@ The provisioner service is included in `docker/docker-compose-dev.yaml` and mana The sandbox uses path mappings to bridge the host filesystem and the container's virtual filesystem. Two key mappings are always configured: -| Host path | Container path | Access | -|---|---|---| -| `skills/` (from `skills.path`) | `/mnt/skills` (from `skills.container_path`) | Read-only | -| `.deer-flow/threads/{thread_id}/user-data/` | `/mnt/user-data/` | Read-write | +| Host path | Container path | Access | +| ------------------------------------------- | -------------------------------------------- | ---------- | +| `skills/` (from `skills.path`) | `/mnt/skills` (from `skills.container_path`) | Read-only | +| `.deer-flow/threads/{thread_id}/user-data/` | `/mnt/user-data/` | Read-write | The skills directory is always mounted read-only. Threads write their working data (uploads, outputs, intermediate files) to `/mnt/user-data/`. @@ -136,7 +136,7 @@ The `LocalSandbox` runs commands directly on the host. By default, the `bash` to ```yaml sandbox: - allow_host_bash: true # Dangerous: grants the agent shell access to your machine + allow_host_bash: true # Dangerous: grants the agent shell access to your machine ``` Even without `bash`, the agent can still read and write files through the dedicated file tools. diff --git a/frontend/src/content/en/harness/skills.mdx b/frontend/src/content/en/harness/skills.mdx index 45f232b37..09f8b0d43 100644 --- a/frontend/src/content/en/harness/skills.mdx +++ b/frontend/src/content/en/harness/skills.mdx @@ -44,23 +44,23 @@ The `SKILL.md` file is the authoritative definition of the skill. It is parsed b DeerFlow ships with the following public skills: -| Skill | Description | -|---|---| -| `deep-research` | Multi-step research with source gathering, cross-checking, and structured output | -| `data-analysis` | Data exploration, statistical analysis, and insight generation | -| `chart-visualization` | Chart and graph creation from data | -| `ppt-generation` | Presentation slide generation | -| `image-generation` | AI image generation workflows | -| `code-documentation` | Automated code documentation generation | -| `newsletter-generation` | Newsletter content creation | -| `podcast-generation` | Podcast script and outline generation | -| `academic-paper-review` | Structured academic paper analysis | -| `consulting-analysis` | Business consulting frameworks and analysis | -| `systematic-literature-review` | Literature review methodology and synthesis | -| `github-deep-research` | Repository and code deep-dive research | -| `frontend-design` | Frontend design and UI workflow | -| `web-design-guidelines` | Web design standards and review | -| `video-generation` | Video content planning and generation | +| Skill | Description | +| ------------------------------ | -------------------------------------------------------------------------------- | +| `deep-research` | Multi-step research with source gathering, cross-checking, and structured output | +| `data-analysis` | Data exploration, statistical analysis, and insight generation | +| `chart-visualization` | Chart and graph creation from data | +| `ppt-generation` | Presentation slide generation | +| `image-generation` | AI image generation workflows | +| `code-documentation` | Automated code documentation generation | +| `newsletter-generation` | Newsletter content creation | +| `podcast-generation` | Podcast script and outline generation | +| `academic-paper-review` | Structured academic paper analysis | +| `consulting-analysis` | Business consulting frameworks and analysis | +| `systematic-literature-review` | Literature review methodology and synthesis | +| `github-deep-research` | Repository and code deep-dive research | +| `frontend-design` | Frontend design and UI workflow | +| `web-design-guidelines` | Web design standards and review | +| `video-generation` | Video content planning and generation | ## Skill lifecycle @@ -139,8 +139,8 @@ DeerFlow includes an optional **skill evolution** feature that allows the agent ```yaml skill_evolution: - enabled: false # Set to true to allow agent-managed skill creation - moderation_model_name: null # Model for security scanning (null = use default) + enabled: false # Set to true to allow agent-managed skill creation + moderation_model_name: null # Model for security scanning (null = use default) ``` diff --git a/frontend/src/content/en/harness/subagents.mdx b/frontend/src/content/en/harness/subagents.mdx index 193f1aa0c..6da63cf00 100644 --- a/frontend/src/content/en/harness/subagents.mdx +++ b/frontend/src/content/en/harness/subagents.mdx @@ -75,10 +75,10 @@ subagents: # Optional: per-agent overrides agents: general-purpose: - timeout_seconds: 1800 # 30 minutes for complex tasks + timeout_seconds: 1800 # 30 minutes for complex tasks max_turns: 160 bash: - timeout_seconds: 300 # 5 minutes for quick commands + timeout_seconds: 300 # 5 minutes for quick commands max_turns: 80 ``` @@ -122,8 +122,8 @@ The Lead Agent invokes ACP agents through the `invoke_acp_agent` built-in tool. ACP agents run as child processes managed by DeerFlow. They communicate over the ACP wire protocol. The standard CLI tools (like the plain `claude` or - `codex` commands) are not ACP-compatible by default — use the adapter - packages listed above or a compatible ACP wrapper. + `codex` commands) are not ACP-compatible by default — use the adapter packages + listed above or a compatible ACP wrapper. ## Custom agents as subagents diff --git a/frontend/src/content/en/harness/tools.mdx b/frontend/src/content/en/harness/tools.mdx index 005fa3ed3..f9c3dd901 100644 --- a/frontend/src/content/en/harness/tools.mdx +++ b/frontend/src/content/en/harness/tools.mdx @@ -78,15 +78,15 @@ Searches for tools by name or description and loads them into the agent's contex The following tools interact with the sandbox filesystem. They require a sandbox to be configured and active. -| Tool | Description | -|---|---| -| `ls` | List files in a directory | -| `read_file` | Read file contents | -| `glob` | Find files matching a pattern | -| `grep` | Search file contents | -| `write_file` | Write content to a file | -| `str_replace` | Replace a string in a file | -| `bash` | Execute a shell command (requires `allow_host_bash: true` or a container sandbox) | +| Tool | Description | +| ------------- | --------------------------------------------------------------------------------- | +| `ls` | List files in a directory | +| `read_file` | Read file contents | +| `glob` | Find files matching a pattern | +| `grep` | Search file contents | +| `write_file` | Write content to a file | +| `str_replace` | Replace a string in a file | +| `bash` | Execute a shell command (requires `allow_host_bash: true` or a container sandbox) | These are configured in `config.yaml` under `tools:`: @@ -98,7 +98,7 @@ tools: - use: deerflow.sandbox.tools:grep_tool - use: deerflow.sandbox.tools:write_file_tool - use: deerflow.sandbox.tools:str_replace_tool - - use: deerflow.sandbox.tools:bash_tool # requires host bash or container sandbox + - use: deerflow.sandbox.tools:bash_tool # requires host bash or container sandbox ``` ## Community tools @@ -124,6 +124,7 @@ tools: High-quality search with structured results. Requires a [Tavily](https://tavily.com) API key. Install: `cd backend && uv add 'deerflow-harness[tavily]'` + ```yaml @@ -134,6 +135,7 @@ tools: Semantic search with neural retrieval. Requires an [Exa](https://exa.ai) API key. Install: `cd backend && uv add 'deerflow-harness[exa]'` + ```yaml @@ -152,6 +154,7 @@ tools: Firecrawl-powered search and crawl. Requires a [Firecrawl](https://firecrawl.dev) API key. Install: `cd backend && uv add 'deerflow-harness[firecrawl]'` + @@ -159,33 +162,22 @@ Install: `cd backend && uv add 'deerflow-harness[firecrawl]'` -```yaml -tools: - - use: deerflow.community.jina_ai.tools:web_fetch_tool - api_key: $JINA_API_KEY # optional; anonymous usage has rate limits -``` -Converts web pages to clean Markdown. Works without an API key at reduced rate limits. + ```yaml tools: - use: deerflow.community.jina_ai.tools:web_fetch_tool + api_key: $JINA_API_KEY # optional; anonymous usage has rate limits ``` + Converts web pages to clean Markdown. Works without an API key at reduced + rate limits. -```yaml -tools: - - use: deerflow.community.exa.tools:web_fetch_tool - api_key: $EXA_API_KEY -``` + ```yaml tools: - use: deerflow.community.exa.tools:web_fetch_tool api_key: + $EXA_API_KEY ``` -```yaml -tools: - - use: deerflow.community.infoquest.tools:web_fetch_tool - api_key: $INFOQUEST_API_KEY -``` + ```yaml tools: - use: deerflow.community.infoquest.tools:web_fetch_tool + api_key: $INFOQUEST_API_KEY ``` -```yaml -tools: - - use: deerflow.community.firecrawl.tools:web_fetch_tool - api_key: $FIRECRAWL_API_KEY -``` + ```yaml tools: - use: deerflow.community.firecrawl.tools:web_fetch_tool + api_key: $FIRECRAWL_API_KEY ``` diff --git a/frontend/src/content/en/tutorials/first-conversation.mdx b/frontend/src/content/en/tutorials/first-conversation.mdx index 271e806d2..64776fd42 100644 --- a/frontend/src/content/en/tutorials/first-conversation.mdx +++ b/frontend/src/content/en/tutorials/first-conversation.mdx @@ -35,6 +35,7 @@ Press Enter to send. ### Watch the agent work You will see the agent start working: + - Expand the **thinking steps** to see which tools it is calling - Watch search results stream in - Wait for the final report to be generated @@ -42,6 +43,7 @@ You will see the agent start working: ### Interact with the result Once the report is generated, you can: + - Ask for more detail on a specific section - Ask to export the report as a file (the agent will use the `present_files` tool) - Ask to create a chart based on the research findings @@ -51,6 +53,7 @@ Once the report is generated, you can: ## What just happened The agent used the DeerFlow Harness to: + 1. Receive your message and add it to the thread state 2. Run the middleware chain (memory injection, title generation) 3. Call the LLM, which decided to search the web diff --git a/frontend/src/content/en/tutorials/use-tools-and-skills.mdx b/frontend/src/content/en/tutorials/use-tools-and-skills.mdx index dc84a6317..2a12051f4 100644 --- a/frontend/src/content/en/tutorials/use-tools-and-skills.mdx +++ b/frontend/src/content/en/tutorials/use-tools-and-skills.mdx @@ -33,6 +33,7 @@ tools: Enable skills through the DeerFlow app's extensions panel, or edit `extensions_config.json` directly. **Via the app UI:** + 1. Open the DeerFlow app 2. Click the Extensions/Skills icon in the sidebar 3. Find `deep-research` and toggle it on diff --git a/frontend/src/content/en/tutorials/work-with-memory.mdx b/frontend/src/content/en/tutorials/work-with-memory.mdx index 8b101aaf4..c7aa047db 100644 --- a/frontend/src/content/en/tutorials/work-with-memory.mdx +++ b/frontend/src/content/en/tutorials/work-with-memory.mdx @@ -32,6 +32,7 @@ Memory works automatically through `MemoryMiddleware`: ## Example **First conversation:** + ``` I am a Python backend developer primarily using FastAPI and PostgreSQL. My team follows PEP 8 and prefers type annotations everywhere. @@ -39,6 +40,7 @@ Please remember this for future code suggestions. ``` **Later conversation** (no need to repeat background): + ``` Help me write a user authentication module ``` diff --git a/frontend/src/content/zh/application/agents-and-threads.mdx b/frontend/src/content/zh/application/agents-and-threads.mdx index 0900c733a..6ad982fed 100644 --- a/frontend/src/content/zh/application/agents-and-threads.mdx +++ b/frontend/src/content/zh/application/agents-and-threads.mdx @@ -8,7 +8,8 @@ import { Callout, Cards, Steps } from "nextra/components"; # Agent 与线程 - Agent 是配置单元——它们定义了一组能力。线程是对话实例，带有持久化状态和历史记录。 + Agent + 是配置单元——它们定义了一组能力。线程是对话实例，带有持久化状态和历史记录。 ## 自定义 Agent @@ -115,5 +116,8 @@ checkpointer: - + diff --git a/frontend/src/content/zh/application/configuration.mdx b/frontend/src/content/zh/application/configuration.mdx index a0cb9c7cc..639eeaec5 100644 --- a/frontend/src/content/zh/application/configuration.mdx +++ b/frontend/src/content/zh/application/configuration.mdx @@ -46,17 +46,18 @@ models: 启用扩展思考： ```yaml - - name: claude-extended-thinking - use: langchain_anthropic:ChatAnthropic - model: claude-sonnet-4-5 - api_key: $ANTHROPIC_API_KEY - max_tokens: 16000 - thinking_enabled: true - extra_body: - thinking: - type: enabled - budget_tokens: 10000 +- name: claude-extended-thinking + use: langchain_anthropic:ChatAnthropic + model: claude-sonnet-4-5 + api_key: $ANTHROPIC_API_KEY + max_tokens: 16000 + thinking_enabled: true + extra_body: + thinking: + type: enabled + budget_tokens: 10000 ``` + ```yaml @@ -103,6 +104,7 @@ models: ```bash ollama pull llama3.3 ``` + @@ -162,11 +164,11 @@ checkpointer: 前端通过 `.env.local`（本地开发）或 Docker Compose 环境中的环境变量配置。 -| 变量 | 必需 | 描述 | -|---|---|---| -| `BETTER_AUTH_SECRET` | 是（生产） | 会话管理的密钥（最少 32 个字符） | -| `BETTER_AUTH_URL` | 推荐 | 你的应用公开 URL（例如 `https://your-domain.com`） | -| `SKIP_ENV_VALIDATION` | 否 | 设为 `1` 跳过构建时环境变量验证 | +| 变量 | 必需 | 描述 | +| --------------------- | ---------- | -------------------------------------------------- | +| `BETTER_AUTH_SECRET` | 是（生产） | 会话管理的密钥（最少 32 个字符） | +| `BETTER_AUTH_URL` | 推荐 | 你的应用公开 URL（例如 `https://your-domain.com`） | +| `SKIP_ENV_VALIDATION` | 否 | 设为 `1` 跳过构建时环境变量验证 | 本地开发： @@ -176,7 +178,8 @@ BETTER_AUTH_SECRET=local-dev-secret-at-least-32-chars ``` - 不要在生产中使用 SKIP_ENV_VALIDATION=1。为 BETTER_AUTH_SECRET 设置一个真实值。 + 不要在生产中使用 SKIP_ENV_VALIDATION=1。为{" "} + BETTER_AUTH_SECRET 设置一个真实值。 ## extensions_config.json @@ -207,12 +210,12 @@ BETTER_AUTH_SECRET=local-dev-secret-at-least-32-chars 这些变量在 DeerFlow 进程中设置（通过 `.env`、Docker 环境或 shell）： -| 变量 | 默认值 | 描述 | -|---|---|---| -| `DEER_FLOW_CONFIG_PATH` | 自动发现 | `config.yaml` 的绝对路径 | -| `LOG_LEVEL` | `info` | 日志详细程度（`debug`/`info`/`warning`/`error`） | -| `DEER_FLOW_ROOT` | 仓库根目录 | 用于 Docker 中的技能和线程挂载 | -| `LANGGRAPH_UPSTREAM` | `langgraph:2024` | nginx 代理的 LangGraph 地址 | +| 变量 | 默认值 | 描述 | +| ----------------------- | ---------------- | ------------------------------------------------ | +| `DEER_FLOW_CONFIG_PATH` | 自动发现 | `config.yaml` 的绝对路径 | +| `LOG_LEVEL` | `info` | 日志详细程度（`debug`/`info`/`warning`/`error`） | +| `DEER_FLOW_ROOT` | 仓库根目录 | 用于 Docker 中的技能和线程挂载 | +| `LANGGRAPH_UPSTREAM` | `langgraph:2024` | nginx 代理的 LangGraph 地址 | diff --git a/frontend/src/content/zh/application/deployment-guide.mdx b/frontend/src/content/zh/application/deployment-guide.mdx index ff75c21b0..59eceece2 100644 --- a/frontend/src/content/zh/application/deployment-guide.mdx +++ b/frontend/src/content/zh/application/deployment-guide.mdx @@ -21,14 +21,15 @@ make dev 启动的服务： -| 服务 | 端口 | 描述 | -|---|---|---| -| LangGraph | 2024 | DeerFlow Harness 运行时 | -| Gateway API | 8001 | FastAPI 后端 | -| 前端 | 3000 | Next.js 界面 | -| nginx | 2026 | 统一反向代理 | +| 服务 | 端口 | 描述 | +| ----------- | ---- | ----------------------- | +| LangGraph | 2024 | DeerFlow Harness 运行时 | +| Gateway API | 8001 | FastAPI 后端 | +| 前端 | 3000 | Next.js 界面 | +| nginx | 2026 | 统一反向代理 | 访问地址：**http://localhost:2026** + ```bash @@ -36,6 +37,7 @@ make stop ``` 停止所有四个服务。即使某个服务没有运行也可以安全执行。 + ``` @@ -46,9 +48,11 @@ logs/nginx.log # nginx 访问/错误日志 ``` 实时追踪日志： + ```bash tail -f logs/langgraph.log ``` + @@ -86,7 +90,8 @@ BETTER_AUTH_SECRET=your-secret-here-min-32-chars `docker-compose*.yaml` 文件包含 `env_file: ../.env` 指令，会自动加载该文件。 - 在部署前始终将 BETTER_AUTH_SECRET 设置为强随机字符串。没有它，前端构建会使用一个公开已知的默认值。 + 在部署前始终将 BETTER_AUTH_SECRET{" "} + 设置为强随机字符串。没有它，前端构建会使用一个公开已知的默认值。 ### 数据持久化 @@ -104,11 +109,11 @@ BETTER_AUTH_SECRET=your-secret-here-min-32-chars ### 沙箱模式选择 -| 沙箱 | 使用场景 | -|---|---| -| `LocalSandboxProvider` | 单用户、受信任的本地工作流 | -| `AioSandboxProvider`（Docker） | 多用户、中等隔离需求 | -| `AioSandboxProvider` + K8s Provisioner | 生产环境、强隔离、多用户 | +| 沙箱 | 使用场景 | +| -------------------------------------- | -------------------------- | +| `LocalSandboxProvider` | 单用户、受信任的本地工作流 | +| `AioSandboxProvider`（Docker） | 多用户、中等隔离需求 | +| `AioSandboxProvider` + K8s Provisioner | 生产环境、强隔离、多用户 | 对于有多个并发用户的任何部署，使用基于容器的沙箱，防止用户之间的执行环境相互干扰。 @@ -153,10 +158,10 @@ SKILLS_PVC_NAME=deer-flow-skills-pvc nginx 路由所有流量，控制路由的关键环境变量： -| 变量 | 默认值 | 描述 | -|---|---|---| -| `LANGGRAPH_UPSTREAM` | `langgraph:2024` | LangGraph 服务地址 | -| `LANGGRAPH_REWRITE` | `/` | LangGraph 路由的 URL 重写前缀 | +| 变量 | 默认值 | 描述 | +| -------------------- | ---------------- | ----------------------------- | +| `LANGGRAPH_UPSTREAM` | `langgraph:2024` | LangGraph 服务地址 | +| `LANGGRAPH_REWRITE` | `/` | LangGraph 路由的 URL 重写前缀 | 这些在 Docker Compose 环境中设置，并在容器启动时由 `envsubst` 处理。 @@ -174,12 +179,12 @@ openssl rand -base64 32 ### 资源建议 -| 服务 | 最低配置 | 推荐配置 | -|---|---|---| +| 服务 | 最低配置 | 推荐配置 | +| ------------------------- | ---------------- | ---------------- | | LangGraph（Agent 运行时） | 2 vCPU、4 GB RAM | 4 vCPU、8 GB RAM | -| Gateway | 0.5 vCPU、512 MB | 1 vCPU、1 GB | -| 前端 | 0.5 vCPU、512 MB | 1 vCPU、1 GB | -| 沙箱容器（每会话） | 1 vCPU、1 GB | 2 vCPU、2 GB | +| Gateway | 0.5 vCPU、512 MB | 1 vCPU、1 GB | +| 前端 | 0.5 vCPU、512 MB | 1 vCPU、1 GB | +| 沙箱容器（每会话） | 1 vCPU、1 GB | 2 vCPU、2 GB | ## 部署后验证 @@ -200,5 +205,8 @@ curl http://localhost:2026/api/models - + diff --git a/frontend/src/content/zh/application/index.mdx b/frontend/src/content/zh/application/index.mdx index d8c06d0c4..81e7113e2 100644 --- a/frontend/src/content/zh/application/index.mdx +++ b/frontend/src/content/zh/application/index.mdx @@ -8,22 +8,24 @@ import { Callout, Cards } from "nextra/components"; # DeerFlow 应用 - DeerFlow 应用是构建在 DeerFlow Harness 之上的完整 Super Agent 应用。它将运行时能力打包成一个可部署的产品，包含 Web 界面、API Gateway 和运维工具。 + DeerFlow 应用是构建在 DeerFlow Harness 之上的完整 Super Agent + 应用。它将运行时能力打包成一个可部署的产品，包含 Web 界面、API Gateway + 和运维工具。 DeerFlow 应用是 DeerFlow 生产体验的参考实现。它将 Harness 运行时、基于 Web 的对话工作区、API Gateway 和反向代理组合成一个可部署的完整系统。 ## 应用提供什么 -| 能力 | 描述 | -|---|---| -| **Web 工作区** | 浏览器对话界面，支持线程、产出物、文件上传和技能选择 | -| **自定义 Agent** | 创建和管理具有不同模型、技能和工具集的命名 Agent | -| **线程管理** | 带检查点和历史记录的持久化对话线程 | -| **流式响应** | 实时 token 流式传输，带思考步骤和工具调用可见性 | -| **产出物查看器** | Agent 生成文件和输出的浏览器内预览和下载 | -| **扩展界面** | 无需编辑配置文件即可启用/禁用 MCP 服务器和技能 | -| **Gateway API** | 桥接前端和 LangGraph 运行时的基于 FastAPI 的 REST API | +| 能力 | 描述 | +| ---------------- | ----------------------------------------------------- | +| **Web 工作区** | 浏览器对话界面，支持线程、产出物、文件上传和技能选择 | +| **自定义 Agent** | 创建和管理具有不同模型、技能和工具集的命名 Agent | +| **线程管理** | 带检查点和历史记录的持久化对话线程 | +| **流式响应** | 实时 token 流式传输，带思考步骤和工具调用可见性 | +| **产出物查看器** | Agent 生成文件和输出的浏览器内预览和下载 | +| **扩展界面** | 无需编辑配置文件即可启用/禁用 MCP 服务器和技能 | +| **Gateway API** | 桥接前端和 LangGraph 运行时的基于 FastAPI 的 REST API | ## 架构 @@ -56,13 +58,13 @@ DeerFlow 应用以四个服务的形式运行，通过单个 nginx 反向代理 ## 技术栈 -| 层次 | 技术 | -|---|---| -| 前端 | Next.js 16、React 19、TypeScript、pnpm | -| Gateway | FastAPI、Python 3.12、uvicorn | -| Agent 运行时 | LangGraph、LangChain、DeerFlow Harness | -| 反向代理 | nginx | -| 状态持久化 | LangGraph Server（默认）+ 可选 SQLite/PostgreSQL 检查点 | +| 层次 | 技术 | +| ------------ | ------------------------------------------------------- | +| 前端 | Next.js 16、React 19、TypeScript、pnpm | +| Gateway | FastAPI、Python 3.12、uvicorn | +| Agent 运行时 | LangGraph、LangChain、DeerFlow Harness | +| 反向代理 | nginx | +| 状态持久化 | LangGraph Server（默认）+ 可选 SQLite/PostgreSQL 检查点 | diff --git a/frontend/src/content/zh/application/operations-and-troubleshooting.mdx b/frontend/src/content/zh/application/operations-and-troubleshooting.mdx index 3b4157d4f..c047bbd5c 100644 --- a/frontend/src/content/zh/application/operations-and-troubleshooting.mdx +++ b/frontend/src/content/zh/application/operations-and-troubleshooting.mdx @@ -13,12 +13,12 @@ import { Callout, Cards } from "nextra/components"; DeerFlow 应用在 `logs/` 目录中写入每个服务的日志： -| 文件 | 内容 | -|---|---| +| 文件 | 内容 | +| -------------------- | -------------------------------------- | | `logs/langgraph.log` | Agent 运行时、工具调用、LangGraph 错误 | -| `logs/gateway.log` | API 请求/响应、Gateway 错误 | -| `logs/frontend.log` | Next.js 服务器日志 | -| `logs/nginx.log` | 代理访问和错误日志 | +| `logs/gateway.log` | API 请求/响应、Gateway 错误 | +| `logs/frontend.log` | Next.js 服务器日志 | +| `logs/nginx.log` | 代理访问和错误日志 | **实时追踪日志**： @@ -31,7 +31,7 @@ tail -f logs/gateway.log # 查看 API 请求 ```yaml # config.yaml -log_level: debug # debug | info | warning | error +log_level: debug # debug | info | warning | error ``` ## 健康检查 @@ -66,12 +66,14 @@ make config-upgrade **症状**：Agent 在响应第一条消息时报错，日志中有 API 认证错误。 **诊断**： + ```bash # 检查 LangGraph 日志中的模型错误 grep -i "error\|apikey\|unauthorized" logs/langgraph.log | tail -20 ``` **解决**： + 1. 验证 `config.yaml` 中 API key 字段名称正确（例如 `$OPENAI_API_KEY`）。 2. 确认对应的环境变量已设置（`echo $OPENAI_API_KEY`）。 3. 检查 `base_url`（如有）是否与提供商的实际端点匹配。 @@ -83,12 +85,14 @@ grep -i "error\|apikey\|unauthorized" logs/langgraph.log | tail -20 **症状**：工具报"文件未找到"或权限错误，即使 Agent 声称已创建文件。 **诊断**： + ```bash # 检查线程用户数据目录是否存在且可写 ls -la backend/.deer-flow/threads/ ``` **解决**： + 1. 确保 `backend/.deer-flow/` 对运行 DeerFlow 的进程可写。 2. 在 Docker 部署中，验证卷挂载路径正确（`DEER_FLOW_ROOT` 设置为绝对路径）。 3. 如果使用基于容器的沙箱，确认 Docker 已运行并且容器镜像已拉取。 @@ -100,6 +104,7 @@ ls -la backend/.deer-flow/threads/ **症状**：`make install` 或前端构建步骤失败，提示 `BETTER_AUTH_SECRET` 错误。 **解决**： + ```bash # 选项 1：设置环境变量（推荐） export BETTER_AUTH_SECRET=your-secret-here-at-least-32-chars @@ -116,12 +121,14 @@ SKIP_ENV_VALIDATION=1 pnpm build **症状**：MCP 工具未出现，`logs/langgraph.log` 中有超时错误。 **诊断**： + ```bash # 检查 MCP 相关错误 grep -i "mcp\|timeout" logs/langgraph.log | tail -20 ``` **解决**： + 1. 验证 `extensions_config.json` 中 MCP 服务器的 `command` 和 `args` 在服务器外部正常工作（手动运行命令）。 2. 确认 MCP 服务器的依赖（如 `npx`、`uvx`）已安装并在 PATH 中。 3. 检查 MCP 服务器是否需要网络访问或特定环境变量。 @@ -133,6 +140,7 @@ grep -i "mcp\|timeout" logs/langgraph.log | tail -20 **症状**：沙箱工具请求挂起，日志中有连接拒绝错误。 **解决**： + 1. 验证 `config.yaml` 中 `provisioner_url` 正确且 Provisioner Pod 运行正常。 2. 检查 `K8S_NAMESPACE` 和 RBAC 配置是否允许 Provisioner 创建 Pod。 3. 验证 `SANDBOX_IMAGE` 可以从 K8s 节点拉取。 @@ -140,6 +148,7 @@ grep -i "mcp\|timeout" logs/langgraph.log | tail -20 ## 数据备份 DeerFlow 将持久化数据存储在： + - **线程数据**：`backend/.deer-flow/threads/` — 每个线程的上传文件、输出和工作区文件 - **检查点**：取决于检查点器配置（SQLite：`backend/.deer-flow/checkpoints.db`，Redis：外部存储） - **记忆**：`backend/.deer-flow/memory.json`（以及 `agents/*/memory.json`） diff --git a/frontend/src/content/zh/application/quick-start.mdx b/frontend/src/content/zh/application/quick-start.mdx index a531a6430..5ccf117ad 100644 --- a/frontend/src/content/zh/application/quick-start.mdx +++ b/frontend/src/content/zh/application/quick-start.mdx @@ -8,7 +8,8 @@ import { Callout, Cards, Steps } from "nextra/components"; # 快速上手 - 大约 10 分钟即可在本地运行 DeerFlow 应用。你需要一台安装了 Python 3.12+、Node.js 22+ 的机器，以及至少一个 LLM API Key。 + 大约 10 分钟即可在本地运行 DeerFlow 应用。你需要一台安装了 Python + 3.12+、Node.js 22+ 的机器，以及至少一个 LLM API Key。 本指南引导你使用 `make dev` 工作流在本地机器上启动 DeerFlow 应用。所有四个服务（LangGraph、Gateway、前端、nginx）一起启动，通过单个 URL 访问。 @@ -23,13 +24,13 @@ make check 必需工具： -| 工具 | 最低版本 | -|---|---| -| Python | 3.12 | -| uv | 最新版 | -| Node.js | 22 | -| pnpm | 10 | -| nginx | 任何近期版本 | +| 工具 | 最低版本 | +| ------- | ------------ | +| Python | 3.12 | +| uv | 最新版 | +| Node.js | 22 | +| pnpm | 10 | +| nginx | 任何近期版本 | 在 macOS 上，使用 `brew install python uv node pnpm nginx` 安装。在 Linux 上，使用你的发行版包管理器。 @@ -86,6 +87,7 @@ make dev ``` 这会启动： + - LangGraph 服务，端口 `2024` - Gateway API，端口 `8001` - 前端，端口 `3000` @@ -109,15 +111,17 @@ make stop 日志文件： -| 服务 | 日志文件 | -|---|---| +| 服务 | 日志文件 | +| --------- | -------------------- | | LangGraph | `logs/langgraph.log` | -| Gateway | `logs/gateway.log` | -| 前端 | `logs/frontend.log` | -| nginx | `logs/nginx.log` | +| Gateway | `logs/gateway.log` | +| 前端 | `logs/frontend.log` | +| nginx | `logs/nginx.log` | - 如果有问题，先检查日志文件。大多数启动错误（缺失 API Key、配置解析失败）会出现在 logs/langgraph.log 或 logs/gateway.log 中。 + 如果有问题，先检查日志文件。大多数启动错误（缺失 API + Key、配置解析失败）会出现在 logs/langgraph.log 或{" "} + logs/gateway.log 中。 diff --git a/frontend/src/content/zh/application/workspace-usage.mdx b/frontend/src/content/zh/application/workspace-usage.mdx index 5ade5cc13..e4e3fb541 100644 --- a/frontend/src/content/zh/application/workspace-usage.mdx +++ b/frontend/src/content/zh/application/workspace-usage.mdx @@ -8,7 +8,8 @@ import { Callout, Cards } from "nextra/components"; # 工作区使用 - DeerFlow 工作区是你与 Agent 交互的地方。本页面涵盖主要用户界面工作流——创建对话、上传文件、查看产出物和使用技能。 + DeerFlow 工作区是你与 Agent + 交互的地方。本页面涵盖主要用户界面工作流——创建对话、上传文件、查看产出物和使用技能。 DeerFlow 工作区是一个基于浏览器的对话界面，你可以在其中向 Agent 发送消息、上传文件、查看中间步骤，以及下载生成的产出物。 @@ -41,13 +42,15 @@ DeerFlow 工作区是一个基于浏览器的对话界面，你可以在其中 拖放文件到消息输入区域，或点击附件图标上传。上传的文件挂载在沙箱的 `/mnt/user-data/uploads/` 路径下，Agent 可以直接读取和处理。 **支持的操作**： + - 读取和分析文件内容 - 处理数据文件（CSV、JSON、Excel） - 提取 PDF 内容 - 分析图像（需要支持视觉的模型） - 上传大文件时，告诉 Agent 文件的具体内容，以便获得更好的结果（例如"分析这个包含季度销售数据的 CSV"）。 + 上传大文件时，告诉 Agent + 文件的具体内容，以便获得更好的结果（例如"分析这个包含季度销售数据的 CSV"）。 ## 使用技能 @@ -72,6 +75,7 @@ DeerFlow 工作区是一个基于浏览器的对话界面，你可以在其中 当 Agent 生成文件（报告、图表、代码文件、演示文稿）时，它们会以**产出物**的形式出现在对话中。 点击产出物卡片： + - 在浏览器中预览文件。 - 下载文件到本地机器。 - 复制文件内容。 @@ -87,6 +91,12 @@ DeerFlow 工作区是一个基于浏览器的对话界面，你可以在其中 **删除线程**：从线程侧边栏菜单中选择删除。这会移除线程状态和所有相关的用户数据文件。 - - + + diff --git a/frontend/src/content/zh/harness/configuration.mdx b/frontend/src/content/zh/harness/configuration.mdx index eda2370dc..1b5cf0207 100644 --- a/frontend/src/content/zh/harness/configuration.mdx +++ b/frontend/src/content/zh/harness/configuration.mdx @@ -8,7 +8,8 @@ import { Callout, Cards } from "nextra/components"; # 配置 - 所有 DeerFlow Harness 行为都由 config.yaml 驱动。一个文件控制哪些模型可用、沙箱如何运行、加载哪些工具，以及每个子系统的行为。 + 所有 DeerFlow Harness 行为都由 config.yaml{" "} + 驱动。一个文件控制哪些模型可用、沙箱如何运行、加载哪些工具，以及每个子系统的行为。 DeerFlow 的配置系统围绕一个目标设计：每一个有意义的行为都应该可以在配置文件中表达，而不是硬编码在应用程序中。这使部署可重现、可审计，并且易于按环境定制。 @@ -79,7 +80,7 @@ models: use: langchain_openai:ChatOpenAI model: gpt-4o api_key: $OPENAI_API_KEY - some_provider_specific_option: value # 传递给 ChatOpenAI 构造函数 + some_provider_specific_option: value # 传递给 ChatOpenAI 构造函数 ``` ## 配置版本 @@ -102,26 +103,26 @@ make config-upgrade 下表将 `config.yaml` 中的每个顶层章节映射到其文档页面： -| 章节 | 描述 | 文档 | -|---|---|---| -| `log_level` | 日志级别（`debug`/`info`/`warning`/`error`） | — | -| `models` | 可用的 LLM 模型 | [Lead Agent](/docs/harness/lead-agent) | -| `token_usage` | 每次模型调用的 token 追踪 | [中间件](/docs/harness/middlewares) | -| `tools` | 可用的 Agent 工具 | [工具](/docs/harness/tools) | -| `tool_groups` | 工具的命名分组 | [工具](/docs/harness/tools) | -| `tool_search` | 延迟/按需工具加载 | [工具](/docs/harness/tools) | -| `sandbox` | 沙箱提供者和选项 | [沙箱](/docs/harness/sandbox) | -| `skills` | 技能目录和容器路径 | [技能](/docs/harness/skills) | -| `skill_evolution` | Agent 管理的技能创建 | [技能](/docs/harness/skills) | -| `subagents` | 子 Agent 超时和最大轮次 | [子 Agent](/docs/harness/subagents) | -| `acp_agents` | 外部 ACP Agent 集成 | [子 Agent](/docs/harness/subagents) | -| `memory` | 跨会话记忆存储 | [记忆系统](/docs/harness/memory) | -| `summarization` | 对话摘要压缩 | [中间件](/docs/harness/middlewares) | -| `title` | 自动生成线程标题 | [中间件](/docs/harness/middlewares) | -| `checkpointer` | 线程状态持久化 | [Agent 与线程](/docs/application/agents-and-threads) | -| `guardrails` | 工具调用授权 | — | -| `uploads` | 文件上传设置（PDF 转换器） | — | -| `channels` | IM 频道集成（飞书、Slack 等） | — | +| 章节 | 描述 | 文档 | +| ----------------- | -------------------------------------------- | ---------------------------------------------------- | +| `log_level` | 日志级别（`debug`/`info`/`warning`/`error`） | — | +| `models` | 可用的 LLM 模型 | [Lead Agent](/docs/harness/lead-agent) | +| `token_usage` | 每次模型调用的 token 追踪 | [中间件](/docs/harness/middlewares) | +| `tools` | 可用的 Agent 工具 | [工具](/docs/harness/tools) | +| `tool_groups` | 工具的命名分组 | [工具](/docs/harness/tools) | +| `tool_search` | 延迟/按需工具加载 | [工具](/docs/harness/tools) | +| `sandbox` | 沙箱提供者和选项 | [沙箱](/docs/harness/sandbox) | +| `skills` | 技能目录和容器路径 | [技能](/docs/harness/skills) | +| `skill_evolution` | Agent 管理的技能创建 | [技能](/docs/harness/skills) | +| `subagents` | 子 Agent 超时和最大轮次 | [子 Agent](/docs/harness/subagents) | +| `acp_agents` | 外部 ACP Agent 集成 | [子 Agent](/docs/harness/subagents) | +| `memory` | 跨会话记忆存储 | [记忆系统](/docs/harness/memory) | +| `summarization` | 对话摘要压缩 | [中间件](/docs/harness/middlewares) | +| `title` | 自动生成线程标题 | [中间件](/docs/harness/middlewares) | +| `checkpointer` | 线程状态持久化 | [Agent 与线程](/docs/application/agents-and-threads) | +| `guardrails` | 工具调用授权 | — | +| `uploads` | 文件上传设置（PDF 转换器） | — | +| `channels` | IM 频道集成（飞书、Slack 等） | — | ## 最小配置示例 diff --git a/frontend/src/content/zh/harness/customization.mdx b/frontend/src/content/zh/harness/customization.mdx index 25f902acd..3b77c0394 100644 --- a/frontend/src/content/zh/harness/customization.mdx +++ b/frontend/src/content/zh/harness/customization.mdx @@ -8,7 +8,9 @@ import { Callout, Cards } from "nextra/components"; # 自定义与扩展 - DeerFlow 设计为可适配的。你可以通过编写自定义中间件、添加新工具、构建技能包以及通过 config.yaml 的 use: 字段替换任何内置组件来扩展 Agent 行为。 + DeerFlow + 设计为可适配的。你可以通过编写自定义中间件、添加新工具、构建技能包以及通过 + config.yaml 的 use: 字段替换任何内置组件来扩展 Agent 行为。 DeerFlow 的可插拔架构意味着系统的大多数部分都可以在不 fork 核心的情况下被替换或扩展。本页面列举了扩展点，并解释如何使用每一个。 diff --git a/frontend/src/content/zh/harness/design-principles.mdx b/frontend/src/content/zh/harness/design-principles.mdx index c25931d14..97498a91c 100644 --- a/frontend/src/content/zh/harness/design-principles.mdx +++ b/frontend/src/content/zh/harness/design-principles.mdx @@ -8,7 +8,8 @@ import { Callout, Cards } from "nextra/components"; # 设计理念 - DeerFlow 围绕一个核心思想构建：Agent 行为应该由小型、可观察、可替换的组件组合而成——而不是硬编码到固定的工作流图中。 + DeerFlow 围绕一个核心思想构建：Agent + 行为应该由小型、可观察、可替换的组件组合而成——而不是硬编码到固定的工作流图中。 了解 DeerFlow Harness 背后的设计理念，有助于你有效地使用它、自信地扩展它，并推断 Agent 在生产环境中的行为方式。 @@ -101,15 +102,15 @@ DeerFlow 中所有有意义的行为都通过 `config.yaml` 控制。系统的 ## 总结 -| 设计原则 | 实践含义 | -|---|---| +| 设计原则 | 实践含义 | +| ---------------------- | ---------------------------------------- | | Harness 而非 Framework | 开箱即用的运行时，所有基础设施已预先连接 | -| 长时序优先 | 架构假设多步骤、多工具、多轮次任务 | -| 中间件优于继承 | 行为由小型、隔离的插件组合而成 | -| 技能提供专业化 | 领域能力按需注入，保持基础干净 | -| 沙箱用于执行 | 真实文件和命令操作的隔离工作区 | -| 上下文工程 | 主动管理 Agent 所见内容以保持有效性 | -| 配置驱动 | 所有关键行为通过 `config.yaml` 控制 | +| 长时序优先 | 架构假设多步骤、多工具、多轮次任务 | +| 中间件优于继承 | 行为由小型、隔离的插件组合而成 | +| 技能提供专业化 | 领域能力按需注入，保持基础干净 | +| 沙箱用于执行 | 真实文件和命令操作的隔离工作区 | +| 上下文工程 | 主动管理 Agent 所见内容以保持有效性 | +| 配置驱动 | 所有关键行为通过 `config.yaml` 控制 | diff --git a/frontend/src/content/zh/harness/index.mdx b/frontend/src/content/zh/harness/index.mdx index ea8712487..6c57cd010 100644 --- a/frontend/src/content/zh/harness/index.mdx +++ b/frontend/src/content/zh/harness/index.mdx @@ -8,7 +8,8 @@ import { Callout, Cards } from "nextra/components"; # 安装 DeerFlow Harness - DeerFlow Harness Python 包将以 deerflow 名称发布。目前尚未正式发布，安装方式即将推出。 + DeerFlow Harness Python 包将以 deerflow{" "} + 名称发布。目前尚未正式发布，安装方式即将推出。 DeerFlow Harness 是构建自己 Super Agent 系统的 Python SDK 和运行时基础。 diff --git a/frontend/src/content/zh/harness/integration-guide.mdx b/frontend/src/content/zh/harness/integration-guide.mdx index 2d2e389a8..ea0a58c3f 100644 --- a/frontend/src/content/zh/harness/integration-guide.mdx +++ b/frontend/src/content/zh/harness/integration-guide.mdx @@ -8,7 +8,8 @@ import { Callout, Cards } from "nextra/components"; # 集成指南 - DeerFlow Harness 可以嵌入任何 Python 应用程序。本指南涵盖在你自己的系统中将 DeerFlow 作为库使用的集成模式。 + DeerFlow Harness 可以嵌入任何 Python 应用程序。本指南涵盖在你自己的系统中将 + DeerFlow 作为库使用的集成模式。 DeerFlow Harness 不仅仅是一个独立应用程序——它是一个可以导入并在你自己的后端、API 服务器、自动化系统或多 Agent 协调器中使用的 Python 库。 diff --git a/frontend/src/content/zh/harness/lead-agent.mdx b/frontend/src/content/zh/harness/lead-agent.mdx index c6f16a413..5e298a809 100644 --- a/frontend/src/content/zh/harness/lead-agent.mdx +++ b/frontend/src/content/zh/harness/lead-agent.mdx @@ -8,7 +8,9 @@ import { Callout, Cards, Steps } from "nextra/components"; # Lead Agent - Lead Agent 是每个 DeerFlow 线程中的主要推理和编排单元。它决定要做什么、调用工具、委派子 Agent，并返回产出物。 + Lead Agent 是每个 DeerFlow + 线程中的主要推理和编排单元。它决定要做什么、调用工具、委派子 + Agent，并返回产出物。 Lead Agent 是 DeerFlow 线程中的核心执行者。每个对话、任务和工作流都通过它进行。理解它的工作方式有助于你有效地配置它，并在需要时扩展它。 @@ -122,7 +124,8 @@ models: 自定义 Agent 通过 DeerFlow 应用界面或 `/api/agents` 端点创建。其配置存储在后端目录的 `agents/{name}/config.yaml` 中。 - 当在线程中选择自定义 Agent 时，Lead Agent 在运行时加载该 Agent 的配置。为特定 Agent 切换模型或技能不需要重启服务器。 + 当在线程中选择自定义 Agent 时，Lead Agent 在运行时加载该 Agent 的配置。为特定 + Agent 切换模型或技能不需要重启服务器。 diff --git a/frontend/src/content/zh/harness/memory.mdx b/frontend/src/content/zh/harness/memory.mdx index 71de258ad..edf2a0e26 100644 --- a/frontend/src/content/zh/harness/memory.mdx +++ b/frontend/src/content/zh/harness/memory.mdx @@ -8,7 +8,8 @@ import { Callout, Cards } from "nextra/components"; # 记忆系统 - 记忆让 DeerFlow 在多个会话中保留有用信息。Agent 记住用户偏好、项目背景和反复出现的事实，这样它可以在不每次从零开始的情况下给出更好的响应。 + 记忆让 DeerFlow 在多个会话中保留有用信息。Agent + 记住用户偏好、项目背景和反复出现的事实，这样它可以在不每次从零开始的情况下给出更好的响应。 记忆是 DeerFlow Harness 的一个运行时功能。它不是简单的对话日志，而是跨多个独立会话持久化、在未来对话中影响 Agent 行为的结构化事实和上下文摘要存储。 diff --git a/frontend/src/content/zh/harness/middlewares.mdx b/frontend/src/content/zh/harness/middlewares.mdx index 94b3571c7..abdcfb3fe 100644 --- a/frontend/src/content/zh/harness/middlewares.mdx +++ b/frontend/src/content/zh/harness/middlewares.mdx @@ -8,7 +8,9 @@ import { Callout } from "nextra/components"; # 中间件 - 中间件包裹 Lead Agent 中的每次 LLM 调用。它们是添加跨领域行为（如记忆、摘要压缩、澄清和 token 追踪）的主要扩展点。 + 中间件包裹 Lead Agent 中的每次 LLM + 调用。它们是添加跨领域行为（如记忆、摘要压缩、澄清和 token + 追踪）的主要扩展点。 每次 Lead Agent 调用 LLM 时，都会先后执行一条**中间件链**。中间件可以读取和修改 Agent 的状态、向系统提示注入内容、拦截工具调用，并对模型输出做出反应。 @@ -87,7 +89,7 @@ title: enabled: true max_words: 6 max_chars: 60 - model_name: null # 使用默认模型 + model_name: null # 使用默认模型 ``` --- @@ -149,7 +151,7 @@ summarization: # 触发条件——满足任意一个条件时运行摘要 trigger: - - type: tokens # 当上下文超过 N 个 token 时触发 + - type: tokens # 当上下文超过 N 个 token 时触发 value: 15564 # - type: messages # 当消息数超过 N 时触发 # value: 50 @@ -159,7 +161,7 @@ summarization: # 摘要后保留多少最近历史 keep: type: messages - value: 10 # 保留最近 10 条消息 + value: 10 # 保留最近 10 条消息 # 或者按 token 保留： # type: tokens # value: 3000 @@ -172,11 +174,13 @@ summarization: ``` **触发类型**： + - `tokens`：当对话中总 token 数超过 `value` 时触发。 - `messages`：当消息数超过 `value` 时触发。 - `fraction`：当上下文达到模型最大输入 token 限制的 `value` 比例时触发。 **保留类型**： + - `messages`：摘要后保留最后 `value` 条消息。 - `tokens`：保留最近 `value` 个 token 的历史。 - `fraction`：保留模型最大输入 token 限制的 `value` 比例的最近历史。 diff --git a/frontend/src/content/zh/harness/quick-start.mdx b/frontend/src/content/zh/harness/quick-start.mdx index bf335e392..3da8c7b3f 100644 --- a/frontend/src/content/zh/harness/quick-start.mdx +++ b/frontend/src/content/zh/harness/quick-start.mdx @@ -85,15 +85,15 @@ agent = create_deerflow_agent( 常用参数： -| 参数 | 说明 | -|---|---| -| `tools` | 提供给 Agent 的额外工具 | -| `system_prompt` | 自定义系统提示词 | -| `features` | 启用或替换内置运行时能力 | +| 参数 | 说明 | +| ------------------ | -------------------------- | +| `tools` | 提供给 Agent 的额外工具 | +| `system_prompt` | 自定义系统提示词 | +| `features` | 启用或替换内置运行时能力 | | `extra_middleware` | 将自定义中间件插入默认链路 | -| `plan_mode` | 启用 Todo 风格的任务跟踪 | -| `checkpointer` | 为多轮运行持久化状态 | -| `name` | Agent 的逻辑名称 | +| `plan_mode` | 启用 Todo 风格的任务跟踪 | +| `checkpointer` | 为多轮运行持久化状态 | +| `name` | Agent 的逻辑名称 | ## 什么时候使用 DeerFlowClient diff --git a/frontend/src/content/zh/harness/sandbox.mdx b/frontend/src/content/zh/harness/sandbox.mdx index 16a05f9e7..2b01718d6 100644 --- a/frontend/src/content/zh/harness/sandbox.mdx +++ b/frontend/src/content/zh/harness/sandbox.mdx @@ -8,7 +8,8 @@ import { Callout, Cards, Tabs } from "nextra/components"; # 沙箱 - 沙箱是 Agent 进行文件和命令操作的隔离工作区。它让 DeerFlow 能够采取真实行动，而不仅仅是对话。 + 沙箱是 Agent 进行文件和命令操作的隔离工作区。它让 DeerFlow + 能够采取真实行动，而不仅仅是对话。 沙箱为 Lead Agent 提供一个受控环境，在其中可以读取文件、写入输出、运行 Shell 命令并生成产出物。没有沙箱，Agent 只能生成文本；有了沙箱，它可以编写和执行代码、处理数据文件、生成图表并构建交付物。 @@ -27,7 +28,7 @@ DeerFlow 支持三种沙箱模式，选择适合你部署的一种： ```yaml sandbox: use: deerflow.sandbox.local:LocalSandboxProvider - allow_host_bash: false # 默认；仅对完全受信任的工作流设置为 true + allow_host_bash: false # 默认；仅对完全受信任的工作流设置为 true ``` ### 基于容器的 AIO 沙箱 @@ -72,10 +73,10 @@ sandbox: 沙箱使用路径映射来桥接主机文件系统和容器的虚拟文件系统。始终配置两个关键映射： -| 主机路径 | 容器路径 | 访问权限 | -|---|---|---| -| `skills/`（来自 `skills.path`） | `/mnt/skills`（来自 `skills.container_path`） | 只读 | -| `.deer-flow/threads/{thread_id}/user-data/` | `/mnt/user-data/` | 读写 | +| 主机路径 | 容器路径 | 访问权限 | +| ------------------------------------------- | --------------------------------------------- | -------- | +| `skills/`（来自 `skills.path`） | `/mnt/skills`（来自 `skills.container_path`） | 只读 | +| `.deer-flow/threads/{thread_id}/user-data/` | `/mnt/user-data/` | 读写 | 技能目录始终以只读方式挂载。线程将其工作数据（上传文件、输出、中间文件）写入 `/mnt/user-data/`。 @@ -94,7 +95,8 @@ sandbox: 自定义挂载的 container_path 不能与保留前缀冲突： - /mnt/skills、/mnt/acp-workspace 或 /mnt/user-data。 + /mnt/skills、/mnt/acp-workspace 或{" "} + /mnt/user-data。 ## 输出截断 @@ -125,7 +127,7 @@ sandbox: ```yaml sandbox: - allow_host_bash: true # 危险：授予 Agent 对你机器的 Shell 访问权限 + allow_host_bash: true # 危险：授予 Agent 对你机器的 Shell 访问权限 ``` 即使没有 `bash`，Agent 也可以通过专用文件工具读写文件。 diff --git a/frontend/src/content/zh/harness/skills.mdx b/frontend/src/content/zh/harness/skills.mdx index f0f0aa659..9b578da01 100644 --- a/frontend/src/content/zh/harness/skills.mdx +++ b/frontend/src/content/zh/harness/skills.mdx @@ -8,7 +8,8 @@ import { Callout, Cards, FileTree, Steps } from "nextra/components"; # 技能 - 技能是面向任务的能力包，教会 Agent 如何完成特定类型的工作。基础 Agent 保持通用；技能在需要时提供专业化。 + 技能是面向任务的能力包，教会 Agent 如何完成特定类型的工作。基础 Agent + 保持通用；技能在需要时提供专业化。 技能不仅仅是提示词。它是一个自包含的能力包，可以包含结构化指令、分步工作流、领域最佳实践、支撑资源和工具配置。技能按需加载——在任务需要时注入内容，否则不影响上下文。 @@ -39,23 +40,23 @@ import { Callout, Cards, FileTree, Steps } from "nextra/components"; DeerFlow 内置以下公共技能： -| 技能 | 描述 | -|---|---| -| `deep-research` | 带来源收集、交叉验证和结构化输出的多步骤研究 | -| `data-analysis` | 数据探索、统计分析和洞察生成 | -| `chart-visualization` | 从数据创建图表和可视化 | -| `ppt-generation` | 演示文稿幻灯片生成 | -| `image-generation` | AI 图像生成工作流 | -| `code-documentation` | 自动化代码文档生成 | -| `newsletter-generation` | 新闻简报内容创作 | -| `podcast-generation` | 播客脚本和大纲生成 | -| `academic-paper-review` | 结构化学术论文分析 | -| `consulting-analysis` | 商业咨询框架和分析 | -| `systematic-literature-review` | 文献综述方法论和综合 | -| `github-deep-research` | 仓库和代码深度研究 | -| `frontend-design` | 前端设计和 UI 工作流 | -| `web-design-guidelines` | 网页设计标准和审查 | -| `video-generation` | 视频内容规划和生成 | +| 技能 | 描述 | +| ------------------------------ | -------------------------------------------- | +| `deep-research` | 带来源收集、交叉验证和结构化输出的多步骤研究 | +| `data-analysis` | 数据探索、统计分析和洞察生成 | +| `chart-visualization` | 从数据创建图表和可视化 | +| `ppt-generation` | 演示文稿幻灯片生成 | +| `image-generation` | AI 图像生成工作流 | +| `code-documentation` | 自动化代码文档生成 | +| `newsletter-generation` | 新闻简报内容创作 | +| `podcast-generation` | 播客脚本和大纲生成 | +| `academic-paper-review` | 结构化学术论文分析 | +| `consulting-analysis` | 商业咨询框架和分析 | +| `systematic-literature-review` | 文献综述方法论和综合 | +| `github-deep-research` | 仓库和代码深度研究 | +| `frontend-design` | 前端设计和 UI 工作流 | +| `web-design-guidelines` | 网页设计标准和审查 | +| `video-generation` | 视频内容规划和生成 | ## 技能生命周期 @@ -132,12 +133,14 @@ DeerFlow 包含一个可选的**技能进化**功能，允许 Agent 在 `skills/ ```yaml skill_evolution: - enabled: false # 设为 true 允许 Agent 管理技能创建 - moderation_model_name: null # 安全扫描模型（null = 使用默认模型） + enabled: false # 设为 true 允许 Agent 管理技能创建 + moderation_model_name: null # 安全扫描模型（null = 使用默认模型） ``` - 只在你信任 Agent 输出的环境中启用技能进化。新创建的技能在加载前会经过安全扫描，但该功能给予 Agent 对技能目录的写访问权限。 + 只在你信任 Agent + 输出的环境中启用技能进化。新创建的技能在加载前会经过安全扫描，但该功能给予 + Agent 对技能目录的写访问权限。 ## 编写自定义技能 diff --git a/frontend/src/content/zh/harness/subagents.mdx b/frontend/src/content/zh/harness/subagents.mdx index 929dfccd4..0f99a398a 100644 --- a/frontend/src/content/zh/harness/subagents.mdx +++ b/frontend/src/content/zh/harness/subagents.mdx @@ -8,7 +8,8 @@ import { Callout, Cards } from "nextra/components"; # 子 Agent - 子 Agent 是 Lead Agent 委派子任务的专注执行者。它们以隔离的上下文运行，在处理并行或专业工作的同时保持主对话清晰。 + 子 Agent 是 Lead Agent + 委派子任务的专注执行者。它们以隔离的上下文运行，在处理并行或专业工作的同时保持主对话清晰。 当一个任务对单个推理线程来说太宽泛，或者部分任务可以并行完成时，Lead Agent 将工作委派给**子 Agent**。子 Agent 是一个独立的 Agent 调用，接收特定任务、执行并返回结果。 @@ -73,10 +74,10 @@ subagents: # 可选：按 Agent 覆盖 agents: general-purpose: - timeout_seconds: 1800 # 复杂任务 30 分钟 + timeout_seconds: 1800 # 复杂任务 30 分钟 max_turns: 160 bash: - timeout_seconds: 300 # 快速命令 5 分钟 + timeout_seconds: 300 # 快速命令 5 分钟 max_turns: 80 ``` @@ -115,7 +116,9 @@ acp_agents: Lead Agent 通过 `invoke_acp_agent` 内置工具调用 ACP Agent。 - ACP Agent 作为 DeerFlow 管理的子进程运行，通过 ACP 协议通信。标准 CLI 工具（如原始的 `claude` 或 `codex` 命令）默认不兼容 ACP——请使用上面列出的适配器包或兼容的 ACP 封装器。 + ACP Agent 作为 DeerFlow 管理的子进程运行，通过 ACP 协议通信。标准 CLI + 工具（如原始的 `claude` 或 `codex` 命令）默认不兼容 + ACP——请使用上面列出的适配器包或兼容的 ACP 封装器。 diff --git a/frontend/src/content/zh/harness/tools.mdx b/frontend/src/content/zh/harness/tools.mdx index b23d25f87..1b25cc55b 100644 --- a/frontend/src/content/zh/harness/tools.mdx +++ b/frontend/src/content/zh/harness/tools.mdx @@ -8,7 +8,8 @@ import { Callout, Cards, Tabs } from "nextra/components"; # 工具 - 工具是 Lead Agent 可以采取的行动。DeerFlow 提供内置工具、社区集成、MCP 工具和技能工具——全部通过 config.yaml 控制。 + 工具是 Lead Agent 可以采取的行动。DeerFlow 提供内置工具、社区集成、MCP + 工具和技能工具——全部通过 config.yaml 控制。 Lead Agent 是一个工具调用 Agent。工具是它与世界交互的方式：搜索网络、读写文件、运行命令、委派任务以及向用户呈现输出。 @@ -74,15 +75,15 @@ task(agent="general-purpose", task="...", context="...") 以下工具与沙箱文件系统交互，需要配置并激活沙箱。 -| 工具 | 描述 | -|---|---| -| `ls` | 列出目录中的文件 | -| `read_file` | 读取文件内容 | -| `glob` | 查找匹配模式的文件 | -| `grep` | 搜索文件内容 | -| `write_file` | 向文件写入内容 | -| `str_replace` | 替换文件中的字符串 | -| `bash` | 执行 Shell 命令（需要 `allow_host_bash: true` 或容器沙箱） | +| 工具 | 描述 | +| ------------- | ---------------------------------------------------------- | +| `ls` | 列出目录中的文件 | +| `read_file` | 读取文件内容 | +| `glob` | 查找匹配模式的文件 | +| `grep` | 搜索文件内容 | +| `write_file` | 向文件写入内容 | +| `str_replace` | 替换文件中的字符串 | +| `bash` | 执行 Shell 命令（需要 `allow_host_bash: true` 或容器沙箱） | 在 `config.yaml` 的 `tools:` 下配置： @@ -120,6 +121,7 @@ tools: 高质量搜索，带结构化结果。需要 [Tavily](https://tavily.com) API Key。 安装：`cd backend && uv add 'deerflow-harness[tavily]'` + ```yaml @@ -130,6 +132,7 @@ tools: 带神经检索的语义搜索。需要 [Exa](https://exa.ai) API Key。 安装：`cd backend && uv add 'deerflow-harness[exa]'` + ```yaml @@ -145,19 +148,13 @@ Firecrawl 驱动的搜索和爬取。需要 [Firecrawl](https://firecrawl.dev) A -```yaml -tools: - - use: deerflow.community.jina_ai.tools:web_fetch_tool - api_key: $JINA_API_KEY # 可选；匿名使用有速率限制 -``` -将网页转换为干净的 Markdown。无 API Key 也可使用，但有更严格的速率限制。 + ```yaml tools: - use: deerflow.community.jina_ai.tools:web_fetch_tool + api_key: $JINA_API_KEY # 可选；匿名使用有速率限制 ``` 将网页转换为干净的 + Markdown。无 API Key 也可使用，但有更严格的速率限制。 -```yaml -tools: - - use: deerflow.community.exa.tools:web_fetch_tool - api_key: $EXA_API_KEY -``` + ```yaml tools: - use: deerflow.community.exa.tools:web_fetch_tool api_key: + $EXA_API_KEY ``` diff --git a/frontend/src/content/zh/index.mdx b/frontend/src/content/zh/index.mdx index 55ea93007..5f2a18deb 100644 --- a/frontend/src/content/zh/index.mdx +++ b/frontend/src/content/zh/index.mdx @@ -63,4 +63,3 @@ Harness 章节是技术文档的核心，面向想要构建基于 DeerFlow 系 ### 参考 参考章节提供详细的查阅资料，包括配置、运行时模式、API 和代码映射。 - diff --git a/frontend/src/content/zh/introduction/core-concepts.mdx b/frontend/src/content/zh/introduction/core-concepts.mdx index fd85ab875..df3bfe4ad 100644 --- a/frontend/src/content/zh/introduction/core-concepts.mdx +++ b/frontend/src/content/zh/introduction/core-concepts.mdx @@ -8,7 +8,8 @@ import { Callout, Cards } from "nextra/components"; # 核心概念 - 如果你将 DeerFlow 理解为一个长时序 Agent 的运行时，而不仅仅是聊天界面或工作流图，它将最易于理解。 + 如果你将 DeerFlow 理解为一个长时序 Agent + 的运行时，而不仅仅是聊天界面或工作流图，它将最易于理解。 在深入了解 DeerFlow 之前，先建立一些贯穿整个系统的核心概念。这些概念解释了 DeerFlow 的优化目标以及其架构设计的原因。 diff --git a/frontend/src/content/zh/introduction/harness-vs-app.mdx b/frontend/src/content/zh/introduction/harness-vs-app.mdx index 7333b6ef7..bd31b4bad 100644 --- a/frontend/src/content/zh/introduction/harness-vs-app.mdx +++ b/frontend/src/content/zh/introduction/harness-vs-app.mdx @@ -8,7 +8,8 @@ import { Callout, Cards } from "nextra/components"; # Harness 与应用 - DeerFlow 应用是构建在 DeerFlow Harness 之上的最佳实践 Super Agent 应用，而 DeerFlow Harness 是构建自己 Agent 系统的 Python SDK 和运行时基础。 + DeerFlow 应用是构建在 DeerFlow Harness 之上的最佳实践 Super Agent 应用，而 + DeerFlow Harness 是构建自己 Agent 系统的 Python SDK 和运行时基础。 DeerFlow 有两个紧密相关但服务于不同目的的层次： diff --git a/frontend/src/content/zh/introduction/why-deerflow.mdx b/frontend/src/content/zh/introduction/why-deerflow.mdx index dd59fc2d5..945d844f8 100644 --- a/frontend/src/content/zh/introduction/why-deerflow.mdx +++ b/frontend/src/content/zh/introduction/why-deerflow.mdx @@ -8,7 +8,8 @@ import { Callout, Cards } from "nextra/components"; # 为什么选择 DeerFlow - DeerFlow 起源于深度研究，但逐渐演化为一个通用的长时序 Agent 运行时——支持技能、记忆、工具和协作调度。 + DeerFlow 起源于深度研究，但逐渐演化为一个通用的长时序 Agent + 运行时——支持技能、记忆、工具和协作调度。 DeerFlow 的诞生是因为现代 Agent 系统需要的不仅仅是一个聊天循环。一个真正有用的 Agent 必须能够进行长时序规划、将任务拆解为子任务、使用工具、操作文件、安全地运行代码，并在复杂任务中保持足够的上下文连贯性。DeerFlow 正是为提供这样的运行时基础而构建的。 diff --git a/frontend/src/content/zh/tutorials/first-conversation.mdx b/frontend/src/content/zh/tutorials/first-conversation.mdx index 1e1a9d387..7c92eaf5e 100644 --- a/frontend/src/content/zh/tutorials/first-conversation.mdx +++ b/frontend/src/content/zh/tutorials/first-conversation.mdx @@ -31,6 +31,7 @@ description: 本教程引导你在 DeerFlow 中完成第一次完整的 Agent ### 3. 观察 Agent 的工作过程 你将看到 Agent 进入工作状态： + - 展开**思考步骤**查看它调用了哪些工具 - 观察网络搜索结果的流入 - 等待最终报告生成 @@ -38,6 +39,7 @@ description: 本教程引导你在 DeerFlow 中完成第一次完整的 Agent ### 4. 与结果互动 报告生成后，你可以： + - 要求对某部分进行详细说明 - 要求将报告导出为文件（Agent 会使用 `present_files` 工具） - 要求基于研究结果创建图表 diff --git a/frontend/src/content/zh/tutorials/work-with-memory.mdx b/frontend/src/content/zh/tutorials/work-with-memory.mdx index 64ae09640..ac3667af8 100644 --- a/frontend/src/content/zh/tutorials/work-with-memory.mdx +++ b/frontend/src/content/zh/tutorials/work-with-memory.mdx @@ -30,6 +30,7 @@ memory: ## 示例 **第一次对话**： + ``` 我是一名 Python 后端开发者，主要使用 FastAPI 和 PostgreSQL。 我的团队遵循 PEP 8 代码规范，偏好类型注解。 @@ -37,6 +38,7 @@ memory: ``` **后续对话**（无需重复背景）： + ``` 帮我写一个用户认证模块 ```