### Example Skill Installation Response

Source: https://github.com/bytedance/deer-flow/blob/main/skills/public/find-skills/SKILL.md

This is an example of how to present found skills to the user, including the skill name, its purpose, the installation command, and a link for more information.

```text
I found a skill that might help! The "vercel-react-best-practices" skill provides
React and Next.js performance optimization guidelines from Vercel Engineering.

To install it:
bash /path/to/skill/scripts/install-skill.sh vercel-labs/agent-skills@vercel-react-best-practices

Learn more: https://skills.sh/vercel-labs/agent-skills/vercel-react-best-practices
```

--------------------------------

### Copy Example Configuration

Source: https://github.com/bytedance/deer-flow/blob/main/backend/docs/MCP_SERVER.md

Copy the example configuration file to start customizing your MCP server setup.

```bash
# Copy example configuration
cp extensions_config.example.json extensions_config.json
```

--------------------------------

### Install and Start Apple Container

Source: https://github.com/bytedance/deer-flow/blob/main/backend/docs/APPLE_CONTAINER.md

Commands to verify the installation and start the Apple Container service.

```bash
# Download from GitHub releases
# https://github.com/apple/container/releases

# Verify installation
container --version

# Start the service
container system start
```

--------------------------------

### Upgrade and Start Service

Source: https://github.com/bytedance/deer-flow/blob/main/backend/docs/AUTH_TEST_PLAN.md

This command switches to the authentication module branch, installs dependencies, and starts the service. It's the next step after preparing old data for an upgrade.

```bash
git checkout feat/rfc-001-auth-module && git stash pop
make install
make dev
```

--------------------------------

### Build and Start Production Server

Source: https://github.com/bytedance/deer-flow/blob/main/frontend/README.md

Commands to build the project for production and start the production server.

```bash
# Build for production
pnpm build

# Start production server
pnpm start
```

--------------------------------

### Initialize Docker Environment

Source: https://github.com/bytedance/deer-flow/blob/main/CONTRIBUTING.md

Build Docker images, install frontend and backend dependencies, and share the pnpm cache with the host for faster builds. This command is for the first-time setup.

```bash
make docker-init
```

--------------------------------

### Start Production Server

Source: https://github.com/bytedance/deer-flow/blob/main/frontend/CLAUDE.md

Starts the application server in production mode.

```bash
pnpm start
```

--------------------------------

### Install Backend Dependencies

Source: https://github.com/bytedance/deer-flow/blob/main/backend/README.md

Installs the necessary backend dependencies using the make install command. Ensure you are in the backend directory.

```bash
cd deer-flow

# Copy configuration files
cp config.example.yaml config.yaml

# Install backend dependencies
cd backend
make install
```

--------------------------------

### Start Nginx

Source: https://github.com/bytedance/deer-flow/blob/main/CONTRIBUTING.md

Starts the nginx server for local development. Can also be started directly.

```bash
make nginx
```

```bash
nginx -c $(pwd)/docker/nginx/nginx.local.conf -g 'daemon off;'
```

--------------------------------

### Tool Configuration Example

Source: https://github.com/bytedance/deer-flow/blob/main/backend/docs/CONFIGURATION.md

Configure specific tools available to the agent. This example shows how to set up the 'web_search' tool.

```yaml
tools:
  - name: web_search
    group: web
    use: deerflow.community.tavily.tools:web_search_tool
    max_results: 5
    # api_key: $TAVILY_API_KEY  # Optional
```

--------------------------------

### Clean Database and Start Development Mode

Source: https://github.com/bytedance/deer-flow/blob/main/backend/docs/AUTH_TEST_PLAN.md

Removes existing database file and starts the application in development mode. Verifies initial setup prompts and API responses.

```bash
# Clear existing data
rm -f backend/.deer-flow/data/deerflow.db

# Start standard mode (Gateway embedded runtime)
make dev
```

--------------------------------

### Admin Login and Setup Completion

Source: https://github.com/bytedance/deer-flow/blob/main/backend/docs/AUTH_TEST_PLAN.md

Tests the process of an admin logging in, verifying the initial setup status, and then completing the setup by changing the password and email. Verifies the final state of the admin user.

```bash
curl -s -X POST $BASE/api/v1/auth/login/local \
  -d "username=admin@example.com&password=<凭据文件密码>" \
  -c admin.txt | jq .needs_setup
```

```bash
# 完成 setup
CSRF=$(grep csrf_token admin.txt | awk '{print $NF}')
curl -s -X POST $BASE/api/v1/auth/change-password \
  -b admin.txt \
  -H "Content-Type: application/json" \
  -H "X-CSRF-Token: $CSRF" \
  -d '{"current_password":"<凭据文件密码>","new_password":"AdminFinal1!","new_email":"admin@real.com"}' \
  -c admin.txt
```

```bash
# 验证
curl -s $BASE/api/v1/auth/me -b admin.txt | jq '{email, needs_setup}'
```

--------------------------------

### Install Dependencies and Hooks

Source: https://github.com/bytedance/deer-flow/blob/main/CONTRIBUTING.md

Installs project dependencies and sets up pre-commit hooks.

```bash
make install
```

--------------------------------

### Install a Skill

Source: https://github.com/bytedance/deer-flow/blob/main/backend/docs/API.md

Install a new skill by uploading a `.skill` file. The request must be multipart/form-data and include the file.

```http
POST /api/skills/install
Content-Type: multipart/form-data
```

```json
{
  "success": true,
  "message": "Skill 'my-skill' installed successfully",
  "skill": {
    "name": "my-skill",
    "display_name": "My Skill",
    "path": "custom/my-skill"
  }
}
```

--------------------------------

### Class Documentation Example

Source: https://github.com/bytedance/deer-flow/blob/main/skills/public/code-documentation/SKILL.md

Example of how to document a class with its constructor, methods, and properties.

```APIDOC
### `ClassName`

Brief description of the class and its purpose.

**Constructor:**

```javascript
new ClassName(config)
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `config.option1` | `string` | Description |
| `config.option2` | `boolean` | Description |

**Methods:**

- [`method1()`](#method1) — Brief description
- [`method2(param)`](#method2) — Brief description

**Properties:**

| Property | Type | Description |
|----------|------|-------------|
| `property1` | `string` | Description |
| `property2` | `number` | Read-only. Description |
```

--------------------------------

### Install Skill

Source: https://github.com/bytedance/deer-flow/blob/main/backend/docs/API.md

Installs a new skill from a provided `.skill` file.

```APIDOC
## POST /api/skills/install

### Description
Install a skill from a `.skill` file.

### Method
POST

### Endpoint
/api/skills/install

### Request Body
- **file** (file) - Required - The `.skill` file to install.

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the operation was successful.
- **message** (string) - A confirmation message.
- **skill** (object) - Details of the installed skill.
  - **name** (string) - The name of the installed skill.
  - **display_name** (string) - The display name of the installed skill.
  - **path** (string) - The file path where the skill is stored.

#### Response Example
{
  "success": true,
  "message": "Skill 'my-skill' installed successfully",
  "skill": {
    "name": "my-skill",
    "display_name": "My Skill",
    "path": "custom/my-skill"
  }
}
```

--------------------------------

### Register New User API Call

Source: https://github.com/bytedance/deer-flow/blob/main/backend/docs/AUTH_DESIGN.md

Example of a frontend registering a new regular user. This endpoint allows user creation even before an admin is initialized, though the setup status may still indicate pending setup.

```JavaScript
POST /api/v1/auth/register
```

--------------------------------

### Install Backend Dependencies

Source: https://github.com/bytedance/deer-flow/blob/main/backend/CONTRIBUTING.md

Install backend dependencies using the provided Makefile after copying the configuration file. Navigate to the backend directory first.

```bash
cp config.example.yaml config.yaml
cd backend
make install
```

--------------------------------

### Run DeerFlow Setup Wizard

Source: https://github.com/bytedance/deer-flow/blob/main/README.md

Executes the setup wizard for DeerFlow, which guides users through LLM provider selection, web search configuration, and execution preferences. It generates a config.yaml and writes keys to .env.

```bash
make setup
```

--------------------------------

### Setup Status Query

Source: https://github.com/bytedance/deer-flow/blob/main/backend/docs/AUTH_TEST_PLAN.md

Checks the current setup status of the authentication system. It indicates whether an administrator account needs to be initialized.

```APIDOC
## GET /api/v1/auth/setup-status

### Description
Retrieves the authentication setup status. Returns `{"needs_setup": true}` if an admin account needs to be created, and `{"needs_setup": false}` if an admin account already exists.

### Method
GET

### Endpoint
/api/v1/auth/setup-status

### Response
#### Success Response (200)
- **needs_setup** (boolean) - Indicates if the system requires initial administrator setup.
```

--------------------------------

### Check Setup Status API

Source: https://github.com/bytedance/deer-flow/blob/main/backend/docs/AUTH_TEST_PLAN.md

Queries the API to determine if initial administrator setup is required. Used after database initialization or reset.

```bash
curl -s $BASE/api/v1/auth/setup-status | jq .
```

--------------------------------

### Test Uninitialized Admin Restart

Source: https://github.com/bytedance/deer-flow/blob/main/backend/docs/AUTH_TEST_PLAN.md

This test case involves removing the database file, starting the service twice, and then checking the setup status. It verifies that the system does not create a default admin or output credentials upon restart if not initialized.

```bash
rm -f backend/.deer-flow/data/deerflow.db
make dev
make stop

make dev
curl -s $BASE/api/v1/auth/setup-status | jq .
```

--------------------------------

### Start Provisioner Service

Source: https://github.com/bytedance/deer-flow/blob/main/docker/provisioner/README.md

Start only the provisioner service using Docker Compose.

```bash
docker compose -p deer-flow-dev -f docker/docker-compose-dev.yaml up -d provisioner
```

--------------------------------

### Install Dependencies

Source: https://github.com/bytedance/deer-flow/blob/main/README.md

Installs backend and frontend dependencies, along with pre-commit hooks. This step is crucial for a functional development environment.

```bash
make install  # Install backend + frontend dependencies + pre-commit hooks
```

--------------------------------

### API User Creation Example

Source: https://github.com/bytedance/deer-flow/blob/main/skills/public/podcast-generation/templates/tech-explainer.md

This example shows a POST request to create a user with name and email, and the expected 201 Created response.

```markdown
# Using the API

POST /api/v1/users
{
  "name": "John",
  "email": "john@example.com"
}

Response: 201 Created
```

--------------------------------

### Install Skill

Source: https://github.com/bytedance/deer-flow/blob/main/docs/SKILL_NAME_CONFLICT_FIX.md

Handles the installation of a new skill. It checks for existing skill directories and names to prevent conflicts.

```APIDOC
## POST /api/skills/install

### Description
Installs a new skill into the system. This endpoint checks for existing skill directories and names to prevent conflicts.

### Method
POST

### Endpoint
/api/skills/install

### Parameters
#### Request Body
- **skill_name** (string) - Required - The name of the skill to install.
- **skill_data** (object) - Required - The data associated with the skill to be installed.

### Request Example
```json
{
  "skill_name": "new_skill",
  "skill_data": {
    "description": "A newly installed skill.",
    "enabled": true
  }
}
```

### Response
#### Success Response (200)
- **message** (string) - A success message indicating the skill was installed.

#### Response Example
```json
{
  "message": "Skill 'new_skill' installed successfully."
}
```
```

--------------------------------

### Start Development Services with Docker

Source: https://github.com/bytedance/deer-flow/blob/main/CONTRIBUTING.md

Start development services, including the frontend, gateway, and provisioner (if in sandbox mode). Services will run with hot-reload enabled.

```bash
make docker-start
```

--------------------------------

### Function Documentation Example

Source: https://github.com/bytedance/deer-flow/blob/main/skills/public/code-documentation/SKILL.md

Example of how to document a function with parameters, return values, and potential errors.

```APIDOC
### `functionName(param1, param2, options?)`

Brief description of what this function does.

**Parameters:**

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `param1` | `string` | Yes | — | Description of param1 |
| `param2` | `number` | Yes | — | Description of param2 |
| `options` | `Object` | No | `{}` | Configuration options |
| `options.timeout` | `number` | No | `5000` | Timeout in milliseconds |

**Returns:** `Promise<Result>` — Description of return value

**Throws:**
- `ValidationError` — When param1 is empty
- `TimeoutError` — When the operation exceeds the timeout

**Example:**

```javascript
const result = await functionName("hello", 42, { timeout: 10000 });
console.log(result.data);
```
```

--------------------------------

### Start Backend Services

Source: https://github.com/bytedance/deer-flow/blob/main/CONTRIBUTING.md

Starts the backend gateway API and the frontend development server in separate terminals.

```bash
cd backend
make dev
```

```bash
cd frontend
pnpm dev
```

--------------------------------

### Copy Example Configuration

Source: https://github.com/bytedance/deer-flow/blob/main/backend/docs/SETUP.md

Copy the example configuration file to a new file named 'config.yaml'. This file will be used to customize DeerFlow's settings.

```bash
cp config.example.yaml config.yaml
```

--------------------------------

### Summarization Configuration Example

Source: https://github.com/bytedance/deer-flow/blob/main/frontend/src/content/en/harness/middlewares.mdx

Example YAML configuration for the SummarizationMiddleware, detailing options for enabling, model selection, trigger conditions, history retention, and summarization prompts.

```yaml
summarization:
  enabled: true

  # Model to use for summarization (null = use default model)
  # A lightweight model like gpt-4o-mini is recommended to reduce cost.
  model_name: null

  # Trigger conditions — summarization runs when ANY threshold is met
  trigger:
    - type: tokens # trigger when context exceeds N tokens
      value: 32000
    # - type: messages  # trigger when there are more than N messages
    #   value: 50
    # - type: fraction  # trigger when context exceeds X% of model max
    #   value: 0.8

  # How much recent history to keep after summarization
  keep:
    type: messages
    value: 10 # keep the 10 most recent messages
    # Alternative: keep by tokens
    # type: tokens
    # value: 3000

  # Maximum tokens to trim when preparing messages for the summarizer
  trim_tokens_to_summarize: 15564

  # Custom summary prompt (null = use default LangChain prompt)
  summary_prompt: null
```

--------------------------------

### Install Dependencies

Source: https://github.com/bytedance/deer-flow/blob/main/frontend/README.md

Installs project dependencies using pnpm. Also copies and prompts to edit the environment variables file.

```bash
pnpm install

cp .env.example .env
# Edit .env with your configuration
```

--------------------------------

### Setup, Testing, and Building

Source: https://github.com/bytedance/deer-flow/blob/main/skills/public/code-documentation/SKILL.md

Instructions for setting up the development environment, running tests, and building the project.

```APIDOC
## Setup

[How to set up a development environment]

## Testing

[How to run tests]

## Building

[How to build the project]
```

--------------------------------

### Install Dependencies

Source: https://github.com/bytedance/deer-flow/blob/main/frontend/src/content/en/harness/quick-start.mdx

Navigate to the backend directory and synchronize dependencies using uv.

```bash
cd backend
uv sync
```

--------------------------------

### README.md Structure Template

Source: https://github.com/bytedance/deer-flow/blob/main/skills/public/code-documentation/SKILL.md

A template for generating a comprehensive README.md file, including sections for project name, description, features, quick start, installation, usage, API reference, configuration, examples, and development.

```markdown
# Project Name

[One-line project description — what it does and why it matters]

[![Badge](link)](#) [![Badge](link)](#)

## Features

- [Key feature 1 — brief description]
- [Key feature 2 — brief description]
- [Key feature 3 — brief description]

## Quick Start

### Prerequisites

- [Prerequisite 1 with version requirement]
- [Prerequisite 2 with version requirement]

### Installation

[Installation commands with copy-paste-ready code blocks]

### Basic Usage

[Minimal working example that demonstrates core functionality]

## Documentation

- [Link to full API reference if separate]
- [Link to architecture docs if separate]
- [Link to examples directory if applicable]

## API Reference

[Inline API reference for smaller projects OR link to generated docs]

## Configuration

[Environment variables, config files, or runtime options]

## Examples

[2-3 practical examples covering common use cases]

## Development

```

--------------------------------

### Configure Application with Docker

Source: https://github.com/bytedance/deer-flow/blob/main/CONTRIBUTING.md

Copy the example configuration file and set your API keys. This is a prerequisite for initializing the Docker environment.

```bash
cp config.example.yaml config.yaml

export OPENAI_API_API_KEY="your-key-here"
# or edit config.yaml directly
```

--------------------------------

### Install and Setup APort Guardrails

Source: https://github.com/bytedance/deer-flow/blob/main/backend/docs/GUARDRAILS.md

Command to install the APort agent guardrails library and set it up for use with DeerFlow.

```bash
pip install aport-agent-guardrails
aport setup --framework deerflow
```

--------------------------------

### Start Docker Development Services

Source: https://github.com/bytedance/deer-flow/blob/main/README.md

Starts the DeerFlow development services within Docker containers. This command initiates the Docker-based development setup.

```bash
./scripts/docker.sh start
```

--------------------------------

### Create and Configure `config.yaml`

Source: https://github.com/bytedance/deer-flow/blob/main/frontend/src/content/en/application/quick-start.mdx

Copy the example configuration file and edit it to include your model providers and API keys. Ensure at least one model is defined.

```yaml
models:
  - name: gpt-4o
    use: langchain_openai:ChatOpenAI
    model: gpt-4o
    api_key: $OPENAI_API_KEY
    request_timeout: 600.0
    max_retries: 2
    supports_vision: true
```

--------------------------------

### Compare Container Startup Commands

Source: https://github.com/bytedance/deer-flow/blob/main/backend/docs/APPLE_CONTAINER.md

Syntax comparison for starting containers between Apple Container and Docker.

```bash
# Apple Container
container run --rm -d -p 8080:8080 -v /host:/container -e KEY=value image

# Docker
docker run --rm -d -p 8080:8080 -v /host:/container -e KEY=value image
```

--------------------------------

### Configure Message-Based Summarization Trigger

Source: https://github.com/bytedance/deer-flow/blob/main/backend/docs/summarization.md

Set up a message-based trigger to start summarization once a certain number of messages have been exchanged. This example uses 50 messages.

```yaml
trigger:
  - type: messages
    value: 50
```

--------------------------------

### Configure Message Retention Policy

Source: https://github.com/bytedance/deer-flow/blob/main/backend/docs/summarization.md

Set a conservative message retention policy to start, and reduce it based on observed performance. This example preserves 25 messages.

```yaml
keep:
  type: messages
  value: 25  # Start higher, reduce if needed
```

--------------------------------

### Initialize Admin User API Call

Source: https://github.com/bytedance/deer-flow/blob/main/backend/docs/AUTH_DESIGN.md

Example of a frontend calling the API to initialize the admin user during the first setup. This endpoint is only available when no admin user exists.

```JavaScript
POST /api/v1/auth/initialize
```

--------------------------------

### Launch Evaluation Viewer

Source: https://github.com/bytedance/deer-flow/blob/main/skills/public/skill-creator/SKILL.md

Start the evaluation viewer server to display qualitative outputs and quantitative benchmark data.

```bash
nohup python <skill-creator-path>/eval-viewer/generate_review.py \
  <workspace>/iteration-N \
  --skill-name "my-skill" \
  --benchmark <workspace>/iteration-N/benchmark.json \
  > /dev/null 2>&1 &
VIEWER_PID=$!
```

--------------------------------

### JavaScript/TypeScript Fetch for Streaming SSE Events

Source: https://github.com/bytedance/deer-flow/blob/main/backend/docs/API.md

Create a run and stream SSE events using the fetch API. This example shows how to set up the POST request for streaming and how to get a reader for the response body.

```typescript
// Create a run and stream SSE events
const streamResponse = await fetch(`/api/langgraph/threads/${threadId}/runs/stream`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Accept: "text/event-stream",
  },
  body: JSON.stringify({
    input: { messages: [{ role: "user", content: "Hello" }] },
    stream_mode: ["values", "messages-tuple", "custom"],
  }),
});

const reader = streamResponse.body?.getReader();
// Decode and parse SSE frames from reader in your client code.
```

--------------------------------

### Install a Skill using `install-skill.sh`

Source: https://github.com/bytedance/deer-flow/blob/main/skills/public/find-skills/SKILL.md

Use the provided bash script to install a skill. This command automatically links the skill to your project. Ensure you have the correct owner/repo@skill-name.

```bash
bash /path/to/skill/scripts/install-skill.sh <owner/repo@skill-name>
```

```bash
bash /path/to/skill/scripts/install-skill.sh vercel-labs/agent-skills@vercel-react-best-practices
```

--------------------------------

### Manual Model Configuration Examples

Source: https://github.com/bytedance/deer-flow/blob/main/README.md

Provides examples of how to manually configure different LLM models within the config.yaml file, including OpenAI-compatible gateways, response APIs, and vLLM deployments.

```yaml
models:
  - name: gpt-4o
    display_name: GPT-4o
    use: langchain_openai:ChatOpenAI
    model: gpt-4o
    api_key: $OPENAI_API_KEY

  - name: openrouter-gemini-2.5-flash
    display_name: Gemini 2.5 Flash (OpenRouter)
    use: langchain_openai:ChatOpenAI
    model: google/gemini-2.5-flash-preview
    api_key: $ROUTER_API_KEY
    base_url: https://openrouter.ai/api/v1

  - name: gpt-5-responses
    display_name: GPT-5 (Responses API)
    use: langchain_openai:ChatOpenAI
    model: gpt-5
    api_key: $OPENAI_API_KEY
    use_responses_api: true
    output_version: responses/v1

  - name: qwen3-32b-vllm
    display_name: Qwen3 32B (vLLM)
    use: deerflow.models.vllm_provider:VllmChatModel
    model: Qwen/Qwen3-32B
    api_key: $VLLM_API_KEY
    base_url: http://localhost:8000/v1
    supports_thinking: true
    when_thinking_enabled:
      extra_body:
        chat_template_kwargs:
          enable_thinking: true
```

```yaml
models:
  - name: gpt-5.4
    display_name: GPT-5.4 (Codex CLI)
    use: deerflow.models.openai_codex_provider:CodexChatModel
    model: gpt-5.4
    supports_thinking: true
    supports_reasoning_effort: true

  - name: claude-sonnet-4.6
    display_name: Claude Sonnet 4.6 (Claude Code OAuth)
    use: deerflow.models.claude_provider:ClaudeChatModel
    model: claude-sonnet-4-6
    max_tokens: 4096
    supports_thinking: true
```

--------------------------------

### Install Skill

Source: https://github.com/bytedance/deer-flow/blob/main/backend/README.md

Installs a new skill into the DeerFlow system from a specified `.skill` archive.

```APIDOC
## POST /api/skills/install

### Description
Installs a skill from a `.skill` archive.

### Method
POST

### Endpoint
/api/skills/install

### Parameters
#### Request Body
- **archive** (file) - The `.skill` archive file to install.
```

--------------------------------

### Run Development Server

Source: https://github.com/bytedance/deer-flow/blob/main/frontend/CLAUDE.md

Starts the development server with Turbopack. Accessible at http://localhost:3000.

```bash
pnpm dev
```

--------------------------------

### TypeScript Inline Code Documentation Example

Source: https://github.com/bytedance/deer-flow/blob/main/skills/public/code-documentation/SKILL.md

Example of TypeScript JSDoc/TSDoc for function documentation.

```APIDOC
```typescript
/**
 * Fetches user data from the API and transforms it for display.
 *
 * @param userId - The unique identifier of the user
 * @param options - Configuration options for the fetch operation
 * @param options.includeProfile - Whether to include the full profile. Defaults to `false`.
 * @param options.cache - Cache duration in seconds. Set to `0` to disable.
 * @returns The transformed user data ready for rendering
 * @throws {NotFoundError} When the user ID does not exist
 * @throws {NetworkError} When the API is unreachable
 *
 * @example
 * ```ts
 * const user = await fetchUser("usr_123", { includeProfile: true });
 * console.log(user.displayName);
 * ```
 */
```
```

--------------------------------

### Start DeerFlow Services

Source: https://github.com/bytedance/deer-flow/blob/main/frontend/src/content/en/tutorials/deploy-your-own-deerflow.mdx

Start the DeerFlow services in detached mode using Docker Compose.

```bash
docker compose -f docker/docker-compose-dev.yaml up -d
```

--------------------------------

### MCP Server Configuration Example

Source: https://github.com/bytedance/deer-flow/blob/main/backend/docs/ARCHITECTURE.md

Configuration for enabling and setting up an MCP server, specifying its type, command, arguments, and environment variables.

```json
{
  "mcpServers": {
    "github": {
      "enabled": true,
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {"GITHUB_TOKEN": "$GITHUB_TOKEN"}
    }
  }
}
```

--------------------------------

### Install Ollama Provider

Source: https://github.com/bytedance/deer-flow/blob/main/frontend/src/content/en/application/configuration.mdx

Command to install the necessary package for using Ollama models with DeerFlow.

```bash
cd backend && uv add 'deerflow-harness[ollama]'
```

--------------------------------

### Extensions Configuration Example

Source: https://github.com/bytedance/deer-flow/blob/main/backend/README.md

Configuration for MCP servers and skill states. This JSON file defines how to enable and configure different MCP servers (like GitHub and secure HTTP) and skills.

```json
{
  "mcpServers": {
    "github": {
      "enabled": true,
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {"GITHUB_TOKEN": "$GITHUB_TOKEN"}
    },
    "secure-http": {
      "enabled": true,
      "type": "http",
      "url": "https://api.example.com/mcp",
      "oauth": {
        "enabled": true,
        "token_url": "https://auth.example.com/oauth/token",
        "grant_type": "client_credentials",
        "client_id": "$MCP_OAUTH_CLIENT_ID",
        "client_secret": "$MCP_OAUTH_CLIENT_SECRET"
      }
    }
  },
  "skills": {
    "pdf-processing": {"enabled": true}
  }
}
```

--------------------------------

### Prepare Old Version Data for Upgrade

Source: https://github.com/bytedance/deer-flow/blob/main/backend/docs/AUTH_TEST_PLAN.md

This snippet prepares the environment by checking out the main branch, starting the service, creating initial thread data, and then stopping the service. It's used before upgrading to a version with authentication.

```bash
git stash && git checkout main
make dev

# 2. 创建一些对话数据（无 auth，直接访问）
curl -s -X POST http://localhost:2026/api/langgraph/threads \
  -H "Content-Type: application/json" \
  -d '{"metadata":{"title":"old-thread-1"}}' | jq .thread_id

curl -s -X POST http://localhost:2026/api/langgraph/threads \
  -H "Content-Type: application/json" \
  -d '{"metadata":{"title":"old-thread-2"}}' | jq .thread_id

# 3. 记录 thread 数量
curl -s http://localhost:2026/api/langgraph/threads | jq length
# 预期: 2+

# 4. 停止服务
make stop
```

--------------------------------

### Read Key Project Files

Source: https://github.com/bytedance/deer-flow/blob/main/skills/public/code-documentation/SKILL.md

Read and inspect essential project configuration files to understand project setup and dependencies. Ensure the file paths are accurate.

```bash
# Read key files
read_file /mnt/user-data/uploads/project-dir/package.json
```

```bash
read_file /mnt/user-data/uploads/project-dir/pyproject.toml
```

--------------------------------

### Install DeerFlow Dependencies

Source: https://github.com/bytedance/deer-flow/blob/main/frontend/src/content/en/tutorials/create-your-first-harness.mdx

Navigate to the deer-flow/backend directory and install the project dependencies using uv sync.

```bash
cd deer-flow/backend
uv sync
```

--------------------------------

### Install Docker Sandbox Provider

Source: https://github.com/bytedance/deer-flow/blob/main/frontend/src/content/en/application/configuration.mdx

Command to install the necessary package for using the Docker sandbox with DeerFlow.

```bash
cd backend && uv add 'deerflow-harness[aio-sandbox]'
```

--------------------------------

### Backend Skill Installation Validation

Source: https://github.com/bytedance/deer-flow/blob/main/docs/SKILL_NAME_CONFLICT_FIX.md

Validates that a skill with the same name does not already exist in the 'custom' category before installation.

```python
try:
    existing_skills = load_skills(enabled_only=False)
    duplicate_skill = next(
        (s for s in existing_skills if s.name == skill_name and s.category == "custom"),
        None
    )
    if duplicate_skill:
        raise HTTPException(
            status_code=409,
            detail=f"Skill with name '{skill_name}' already exists in custom category "
                   f"(located at: {duplicate_skill.skill_dir}). Please remove it first or use a different name."
        )
except ValueError as e:
    # ValueError indicates duplicate skill names in configuration
    # This should not happen during installation, but handle it gracefully
    logger.warning(f"Skills configuration issue detected during installation: {e}")
    raise HTTPException(
        status_code=500,
        detail=f"Cannot install skill: {str(e)}"
    )
```

--------------------------------

### Initialize Admin Account

Source: https://github.com/bytedance/deer-flow/blob/main/backend/docs/AUTH_TEST_PLAN.md

Initializes the administrator account with provided email and password. Sets up the initial state for a new deployment.

```bash
curl -s -X POST $BASE/api/v1/auth/initialize \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@example.com","password":"AdminPass1!"}' \
  -c cookies.txt | jq .
```

--------------------------------

### Install Skill Endpoint Validation

Source: https://github.com/bytedance/deer-flow/blob/main/docs/SKILL_NAME_CONFLICT_FIX.md

Updates the skill installation check to verify directory existence before proceeding.

```python
# Check if skill already exists
target_dir = custom_skills_dir / skill_name
if target_dir.exists():
    raise HTTPException(status_code=409, detail=f"Skill '{skill_name}' already exists. Please remove it first or use a different name.")
```

```python
# Check if skill directory already exists
target_dir = custom_skills_dir / skill_name
if target_dir.exists():
    raise HTTPException(status_code=409, detail=f"Skill directory '{skill_name}' already exists. Please remove it first or use a different name.")

# Check if a skill with the same name already exists in custom category
```

--------------------------------

### Check Prerequisites

Source: https://github.com/bytedance/deer-flow/blob/main/CONTRIBUTING.md

Run this command to verify that all required tools for development are installed.

```bash
make check
```

--------------------------------

### Verify Prerequisites

Source: https://github.com/bytedance/deer-flow/blob/main/README.md

Checks for necessary tools like Node.js, pnpm, uv, and nginx. Ensure these are installed and accessible before proceeding.

```bash
make check  # Verifies Node.js 22+, pnpm, uv, nginx
```

--------------------------------

### Python Inline Code Documentation Example

Source: https://github.com/bytedance/deer-flow/blob/main/skills/public/code-documentation/SKILL.md

Example of Python docstrings using Google style for function documentation.

```APIDOC
```python
def process_data(input_path: str, options: dict | None = None) -> ProcessResult:
    """Process data from the given file path.

    Reads the input file, applies transformations based on the provided
    options, and returns a structured result object.

    Args:
        input_path: Absolute path to the input data file.
            Supports CSV, JSON, and Parquet formats.
        options: Optional configuration dictionary.
            - "validate" (bool): Enable input validation. Defaults to True.
            - "format" (str): Output format ("json" or "csv"). Defaults to "json".

    Returns:
        A ProcessResult containing the transformed data and metadata.

    Raises:
        FileNotFoundError: If input_path does not exist.
        ValidationError: If validation is enabled and data is malformed.

    Example:
        >>> result = process_data("/data/input.csv", {"validate": True})
        >>> print(result.row_count)
        1500
    """
```
```

--------------------------------

### Provider Initialization with Framework and Config

Source: https://github.com/bytedance/deer-flow/blob/main/backend/docs/GUARDRAILS.md

Example of how a DeerFlow provider is initialized, accepting a `framework` argument and arbitrary keyword arguments for configuration. It demonstrates forward-compatibility by accepting `**kwargs`.

```python
class YourProvider:
    def __init__(self, framework: str = "generic", **kwargs):
        # framework="deerflow" tells you which config dir to use
        ...

```