feat: Add metadata and descriptions to various documentation pages in Chinese

- Added titles and descriptions to workspace usage, configuration, customization, design principles, installation, integration guide, lead agent, MCP integration, memory system, middleware, quick start, sandbox, skills, subagents, and tools documentation. - Removed outdated API/Gateway reference and concepts glossary pages. - Updated configuration reference to reflect current structure and removed unnecessary sections. - Introduced new model provider documentation for Ark and updated the index page for model providers. - Enhanced tutorials with titles and descriptions for better clarity and navigation.
2026-05-21 15:36:48 +00:00 · 2026-04-12 11:16:08 +08:00
parent 56d5fa3337
commit 44d9953e2e
81 changed files with 528 additions and 1027 deletions
@@ -25,6 +25,15 @@ const meta: MetaRecord = {
  blog: {
    type: "page",
  },
+  posts: {
+    type: "page",
+  },
+  login: {
+    type: "page",
+  },
+  setup: {
+    type: "page",
+  },
 };

 export default meta;
@@ -1,3 +1,8 @@
+---
+title: Agent 与线程
+description: 了解 DeerFlow 中 Agent 与线程的关系，以及如何管理自定义 Agent 和对话线程。
+---
+
 import { Callout, Cards, Steps } from "nextra/components";

 # Agent 与线程
@@ -1,3 +1,8 @@
+---
+title: 配置
+description: 本页面涵盖 DeerFlow 应用的所有配置层——`config.yaml`、前端环境变量、`extensions_config.json` 和运行时环境变量。
+---
+
 import { Callout, Cards, Tabs } from "nextra/components";

 # 配置
@@ -1,3 +1,8 @@
+---
+title: 部署指南
+description: 本指南涵盖 DeerFlow 应用所有支持的部署方式：本地开发、Docker Compose 以及使用 Kubernetes 管理沙箱的生产环境。
+---
+
 import { Callout, Cards, Steps, Tabs } from "nextra/components";

 # 部署指南
@@ -1,3 +1,8 @@
+---
+title: DeerFlow 应用
+description: DeerFlow 应用是 DeerFlow 生产体验的参考实现。它将 Harness 运行时、基于 Web 的对话工作区、API Gateway 和反向代理组合成一个可部署的完整系统。
+---
+
 import { Callout, Cards } from "nextra/components";

 # DeerFlow 应用
@@ -1,3 +1,8 @@
+---
+title: 运维与排障
+description: 本页面涵盖运行 DeerFlow 应用的操作信息：日志记录、常见问题和维护任务。
+---
+
 import { Callout, Cards } from "nextra/components";

 # 运维与排障
@@ -1,3 +1,8 @@
+---
+title: 快速上手
+description: 本指南引导你使用 `make dev` 工作流在本地机器上启动 DeerFlow 应用。所有四个服务（LangGraph、Gateway、前端、nginx）一起启动，通过单个 URL 访问。
+---
+
 import { Callout, Cards, Steps } from "nextra/components";

 # 快速上手
@@ -1,3 +1,8 @@
+---
+title: 工作区使用
+description: DeerFlow 工作区是一个基于浏览器的对话界面，你可以在其中向 Agent 发送消息、上传文件、查看中间步骤，以及下载生成的产出物。
+---
+
 import { Callout, Cards } from "nextra/components";

 # 工作区使用
@@ -1,3 +1,8 @@
+---
+title: 配置
+description: DeerFlow 的配置系统围绕一个目标设计：每一个有意义的行为都应该可以在配置文件中表达，而不是硬编码在应用程序中。这使部署可重现、可审计，并且易于按环境定制。
+---
+
 import { Callout, Cards } from "nextra/components";

 # 配置
@@ -1,3 +1,8 @@
+---
+title: 自定义与扩展
+description: DeerFlow 的可插拔架构意味着系统的大多数部分都可以在不 fork 核心的情况下被替换或扩展。本页面列举了扩展点，并解释如何使用每一个。
+---
+
 import { Callout, Cards } from "nextra/components";

 # 自定义与扩展
@@ -1,3 +1,8 @@
+---
+title: 设计理念
+description: 了解 DeerFlow Harness 背后的设计理念，有助于你有效地使用它、自信地扩展它，并推断 Agent 在生产环境中的行为方式。
+---
+
 import { Callout, Cards } from "nextra/components";

 # 设计理念
@@ -1,3 +1,8 @@
+---
+title: 安装 DeerFlow Harness
+description: DeerFlow Harness 是构建自己 Super Agent 系统的 Python SDK 和运行时基础。
+---
+
 import { Callout, Cards } from "nextra/components";

 # 安装 DeerFlow Harness
@@ -1,3 +1,8 @@
+---
+title: 集成指南
+description: DeerFlow Harness 不仅仅是一个独立应用程序——它是一个可以导入并在你自己的后端、API 服务器、自动化系统或多 Agent 协调器中使用的 Python 库。
+---
+
 import { Callout, Cards } from "nextra/components";

 # 集成指南
@@ -1,3 +1,8 @@
+---
+title: Lead Agent
+description: Lead Agent 是 DeerFlow 线程中的核心执行者。每个对话、任务和工作流都通过它进行。理解它的工作方式有助于你有效地配置它，并在需要时扩展它。
+---
+
 import { Callout, Cards, Steps } from "nextra/components";

 # Lead Agent
@@ -1,9 +1,15 @@
+---
+title: MCP 集成
+description: Model Context Protocol（MCP） 是连接语言模型与外部工具和数据源的开放标准。DeerFlow 的 MCP 集成允许你用任何实现了 MCP 协议的工具服务器扩展 Agent——无需修改 Harness 本身。
+---
+
 import { Callout, Cards, Steps } from "nextra/components";

 # MCP 集成

 <Callout type="info" emoji="🔌">
-  Model Context Protocol（MCP）让 DeerFlow 能够连接任何外部工具服务器。连接后，MCP 工具与内置工具一样对 Lead Agent 可用。
+  Model Context Protocol（MCP）让 DeerFlow
+  能够连接任何外部工具服务器。连接后，MCP 工具与内置工具一样对 Lead Agent 可用。
 </Callout>

 **Model Context Protocol（MCP）** 是连接语言模型与外部工具和数据源的开放标准。DeerFlow 的 MCP 集成允许你用任何实现了 MCP 协议的工具服务器扩展 Agent——无需修改 Harness 本身。
@@ -37,6 +43,7 @@ MCP 服务器在 `extensions_config.json` 中配置，这个文件独立于 `con
 ```

 每个服务器条目支持：
+
 - `command`：要运行的可执行文件（如 `npx`、`uvx`、`python`）
 - `args`：命令参数数组
 - `enabled`：服务器是否激活（可切换而无需删除条目）
@@ -81,6 +88,7 @@ tool_search:
 某些 MCP 服务器需要 OAuth 认证。DeerFlow 的 `mcp/oauth.py` 处理声明了 OAuth 需求的服务器的 OAuth 流程。

 当连接到受 OAuth 保护的 MCP 服务器时，DeerFlow 会：
+
 1. 从服务器能力头中检测 OAuth 需求
 2. 使用 `get_initial_oauth_headers()` 构建适当的授权头
 3. 通过 `build_oauth_tool_interceptor()` 用 OAuth 拦截器包装工具调用
@@ -1,3 +1,8 @@
+---
+title: 记忆系统
+description: 记忆是 DeerFlow Harness 的一个运行时功能。它不是简单的对话日志，而是跨多个独立会话持久化、在未来对话中影响 Agent 行为的结构化事实和上下文摘要存储。
+---
+
 import { Callout, Cards } from "nextra/components";

 # 记忆系统
@@ -1,3 +1,8 @@
+---
+title: 中间件
+description: 每次 Lead Agent 调用 LLM 时，都会先后执行一条**中间件链**。中间件可以读取和修改 Agent 的状态、向系统提示注入内容、拦截工具调用，并对模型输出做出反应。
+---
+
 import { Callout } from "nextra/components";

 # 中间件
@@ -1,12 +1,18 @@
+---
+title: 快速上手
+description: 学习如何使用 create_deerflow_agent 创建并运行 DeerFlow Agent，从模型初始化到流式响应。
+---
+
 import { Callout, Cards, Steps } from "nextra/components";

 # 快速上手

 <Callout type="info" emoji="🚀">
-  本指南介绍如何以编程方式使用 DeerFlow Harness——不是通过应用界面，而是直接在 Python 中导入和调用 Harness。
+  本指南介绍如何在 Python 中通过 <code>create_deerflow_agent</code>
+  创建并运行一个 DeerFlow Agent。
 </Callout>

-DeerFlow Harness 是 Python SDK 和运行时基础。本快速上手指南将带你了解运行 Agent、流式传输输出和使用线程的核心 API。
+理解 DeerFlow Harness 的最快方式，是直接在代码里创建一个 Agent。本快速上手指南将带你完成模型初始化、Agent 创建，以及响应流式输出。

 ## 前置条件

@@ -19,130 +25,86 @@ cd backend
 uv sync
 ```

-## 配置
+你还需要准备一个来自对应 LangChain Provider 包的聊天模型实例。

-所有 Harness 行为由 `config.yaml` 驱动。至少需要配置一个模型：
-
-```yaml
-# config.yaml
-config_version: 6
-
-models:
-  - name: gpt-4o
-    use: langchain_openai:ChatOpenAI
-    model: gpt-4o
-    api_key: $OPENAI_API_KEY
-    request_timeout: 600.0
-    max_retries: 2
-
-sandbox:
-  use: deerflow.sandbox.local:LocalSandboxProvider
-
-tools:
-  - use: deerflow.community.ddg_search.tools:web_search_tool
-  - use: deerflow.community.jina_ai.tools:web_fetch_tool
-  - use: deerflow.sandbox.tools:ls_tool
-  - use: deerflow.sandbox.tools:read_file_tool
-  - use: deerflow.sandbox.tools:write_file_tool
-  - use: deerflow.sandbox.tools:bash_tool
-```
-
-将 `config.example.yaml` 复制到 `config.yaml` 并填写你的 API Key。
-
-## 运行 Harness
-
-DeerFlow Harness 的主要入口是 `DeerFlowClient`。它管理线程状态、调用 Lead Agent，并流式传输响应。
+## 创建第一个 Agent

 <Steps>

-### 导入并配置
+### 导入工厂函数与模型类

 ```python
-import asyncio
-from deerflow.client import DeerFlowClient
-from deerflow.config import load_config
-
-# 从当前目录或 DEER_FLOW_CONFIG_PATH 加载 config.yaml
-load_config()
-
-client = DeerFlowClient()
+from deerflow.agents import create_deerflow_agent
+from langchain_openai import ChatOpenAI
 ```

-### 创建线程
+### 创建模型

 ```python
-thread_id = "my-thread-001"
+model = ChatOpenAI(
+    model="gpt-4o",
+    api_key="YOUR_OPENAI_API_KEY",
+)
 ```

-线程 ID 是任意字符串。使用相同 ID 可以继续已有对话（需要配置检查点）。
-
-### 发送消息并流式传输响应
+### 创建 Agent

 ```python
-async def run():
-    async for event in client.astream(
-        thread_id=thread_id,
-        message="研究前三大开源 LLM 框架并进行总结。",
-        config={
-            "configurable": {
-                "model_name": "gpt-4o",
-                "thinking_enabled": False,
-                "is_plan_mode": True,
-                "subagent_enabled": True,
-            }
-        },
-    ):
-        print(event)
+agent = create_deerflow_agent(model)
+```

-asyncio.run(run())
+这会返回一个已经编译好的 LangGraph Agent，并带有 DeerFlow 默认的中间件链。
+
+### 流式获取响应
+
+```python
+for event in agent.stream(
+    {"messages": [{"role": "user", "content": "解释一下 DeerFlow Harness 是什么。"}]},
+    stream_mode=["messages", "values"],
+):
+    print(event)
 ```

 </Steps>

-## 可配置选项
+## 添加工具或行为

-`config.configurable` 字典控制每次请求的行为：
-
-| 键 | 类型 | 默认值 | 说明 |
-|---|---|---|---|
-| `model_name` | `str \| None` | 配置中第一个模型 | 本次请求使用的模型 |
-| `thinking_enabled` | `bool` | `True` | 启用扩展思考模式（如果支持） |
-| `reasoning_effort` | `str \| None` | `None` | 推理努力程度（特定模型参数） |
-| `is_plan_mode` | `bool` | `False` | 启用 TodoList 中间件进行任务跟踪 |
-| `subagent_enabled` | `bool` | `False` | 允许 Agent 委派子任务 |
-| `max_concurrent_subagents` | `int` | `3` | 每轮最大并行子 Agent 调用数 |
-| `agent_name` | `str \| None` | `None` | 要加载的自定义 Agent 名称 |
-
-## 流式事件类型
-
-`client.astream()` 从 LangGraph 运行时产生事件，主要事件类型如下：
-
-| 事件类型 | 说明 |
-|---|---|
-| `messages` | 消息块（文本、思考过程、工具调用） |
-| `thread_state` | 线程状态更新（标题、产出物、待办列表） |
-
-消息块包含 Agent 生成响应时的 token 流。
-
-## 使用自定义 Agent
-
-如果已定义自定义 Agent，在 configurable 中传入其 `name`：
+你可以通过传入工具、系统提示词、运行时特性、中间件或 checkpointer 来自定义 Agent。

 ```python
-async for event in client.astream(
-    thread_id="thread-002",
-    message="分析上传的 CSV 并生成摘要图表。",
-    config={
-        "configurable": {
-            "agent_name": "data-analyst",
-            "subagent_enabled": True,
-        }
-    },
-):
-    ...
+from deerflow.agents import RuntimeFeatures, create_deerflow_agent
+
+agent = create_deerflow_agent(
+    model,
+    system_prompt="你是一个简洁的研究助手。",
+    features=RuntimeFeatures(subagent=True, memory=False),
+    plan_mode=True,
+    name="research-agent",
+)
 ```

-自定义 Agent 的配置（模型、技能、工具组）将从 `agents/data-analyst/config.yaml` 自动加载。
+常用参数：
+
+| 参数 | 说明 |
+|---|---|
+| `tools` | 提供给 Agent 的额外工具 |
+| `system_prompt` | 自定义系统提示词 |
+| `features` | 启用或替换内置运行时能力 |
+| `extra_middleware` | 将自定义中间件插入默认链路 |
+| `plan_mode` | 启用 Todo 风格的任务跟踪 |
+| `checkpointer` | 为多轮运行持久化状态 |
+| `name` | Agent 的逻辑名称 |
+
+## 什么时候使用 DeerFlowClient
+
+如果你想直接操作底层的编译后 Agent 图，使用 `create_deerflow_agent()`。
+
+如果你想使用更高层的嵌入式应用接口，则应使用 `DeerFlowClient`，例如：
+
+- 面向线程的对话封装，
+- 模型 / 技能 / 记忆管理 API，
+- 文件上传与 artifacts，
+- 与 Gateway 一致的返回格式。

 <Cards num={3}>
  <Cards.Card title="设计理念" href="/docs/harness/design-principles" />
@@ -1,3 +1,8 @@
+---
+title: 沙箱
+description: 沙箱为 Lead Agent 提供一个受控环境，在其中可以读取文件、写入输出、运行 Shell 命令并生成产出物。没有沙箱，Agent 只能生成文本；有了沙箱，它可以编写和执行代码、处理数据文件、生成图表并构建交付物。
+---
+
 import { Callout, Cards, Tabs } from "nextra/components";

 # 沙箱
@@ -1,3 +1,8 @@
+---
+title: 技能
+description: 技能不仅仅是提示词。它是一个自包含的能力包，可以包含结构化指令、分步工作流、领域最佳实践、支撑资源和工具配置。技能按需加载——在任务需要时注入内容，否则不影响上下文。
+---
+
 import { Callout, Cards, FileTree, Steps } from "nextra/components";

 # 技能
@@ -1,3 +1,8 @@
+---
+title: 子 Agent
+description: 当一个任务对单个推理线程来说太宽泛，或者部分任务可以并行完成时，Lead Agent 将工作委派给**子 Agent**。子 Agent 是一个独立的 Agent 调用，接收特定任务、执行并返回结果。
+---
+
 import { Callout, Cards } from "nextra/components";

 # 子 Agent
@@ -1,3 +1,8 @@
+---
+title: 工具
+description: Lead Agent 是一个工具调用 Agent。工具是它与世界交互的方式：搜索网络、读写文件、运行命令、委派任务以及向用户呈现输出。
+---
+
 import { Callout, Cards, Tabs } from "nextra/components";

 # 工具
@@ -1,3 +1,8 @@
+---
+title: 核心概念
+description: 在深入了解 DeerFlow 之前，先建立一些贯穿整个系统的核心概念。这些概念解释了 DeerFlow 的优化目标以及其架构设计的原因。
+---
+
 import { Callout, Cards } from "nextra/components";

 # 核心概念
@@ -1,3 +1,8 @@
+---
+title: Harness 与应用
+description: DeerFlow 有两个紧密相关但服务于不同目的的层次：.
+---
+
 import { Callout, Cards } from "nextra/components";

 # Harness 与应用
@@ -1,3 +1,8 @@
+---
+title: 为什么选择 DeerFlow
+description: DeerFlow 的诞生是因为现代 Agent 系统需要的不仅仅是一个聊天循环。一个真正有用的 Agent 必须能够进行长时序规划、将任务拆解为子任务、使用工具、操作文件、安全地运行代码，并在复杂任务中保持足够的上下文连贯性。DeerFlow 正是为提供这样的运行时基础而构建的。
+---
+
 import { Callout, Cards } from "nextra/components";

 # 为什么选择 DeerFlow
@@ -1,20 +1,8 @@
 import type { MetaRecord } from "nextra";

 const meta: MetaRecord = {
-  "concepts-glossary": {
-    title: "概念词汇表",
-  },
-  "configuration-reference": {
-    title: "配置参考",
-  },
-  "api-gateway-reference": {
-    title: "API / Gateway 参考",
-  },
-  "runtime-flags-and-modes": {
-    title: "运行时标志与模式",
-  },
-  "source-map": {
-    title: "代码映射",
+  "model-providers": {
+    title: "模型接入",
  },
 };

@@ -1,68 +0,0 @@
-import { Callout } from "nextra/components";
-
-# API / Gateway 参考
-
-<Callout type="info">
-  DeerFlow Gateway 是基于 FastAPI 构建的，提供交互式 API 文档，可通过 <code>http://localhost:8001/docs</code> 访问。
-</Callout>
-
-## 基础 URL
-
-```
-http://localhost:8001
-```
-
-通过 nginx 代理：
-
-```
-http://localhost:2026/api
-```
-
-## 核心端点
-
-### 系统
-
-| 方法 | 路径 | 描述 |
-|---|---|---|
-| `GET` | `/health` | 服务健康检查 |
-| `GET` | `/api/models` | 获取已配置的模型列表 |
-
-### Agent 管理
-
-| 方法 | 路径 | 描述 |
-|---|---|---|
-| `GET` | `/api/agents` | 列出所有 Agent |
-| `POST` | `/api/agents` | 创建自定义 Agent |
-| `GET` | `/api/agents/{name}` | 获取 Agent 配置 |
-| `PUT` | `/api/agents/{name}` | 更新 Agent 配置 |
-| `DELETE` | `/api/agents/{name}` | 删除 Agent |
-| `POST` | `/api/agents/check` | 检查/建议 Agent slug 唯一性 |
-
-### 线程和记忆
-
-| 方法 | 路径 | 描述 |
-|---|---|---|
-| `GET` | `/api/threads` | 列出线程 |
-| `DELETE` | `/api/threads/{thread_id}` | 删除线程 |
-| `GET` | `/api/memory` | 获取全局记忆 |
-| `GET` | `/api/memory/{agent_name}` | 获取 Agent 特定记忆 |
-| `DELETE` | `/api/memory` | 清除全局记忆 |
-
-### 扩展
-
-| 方法 | 路径 | 描述 |
-|---|---|---|
-| `GET` | `/api/extensions` | 列出所有扩展（MCP 服务器和技能） |
-| `POST` | `/api/extensions/mcp/{name}/enable` | 启用 MCP 服务器 |
-| `POST` | `/api/extensions/mcp/{name}/disable` | 禁用 MCP 服务器 |
-| `POST` | `/api/extensions/skills/{name}/enable` | 启用技能 |
-| `POST` | `/api/extensions/skills/{name}/disable` | 禁用技能 |
-
-### 文件上传
-
-| 方法 | 路径 | 描述 |
-|---|---|---|
-| `POST` | `/api/uploads/{thread_id}` | 上传文件到线程工作区 |
-| `GET` | `/api/uploads/{thread_id}/{filename}` | 获取上传的文件 |
-
-完整的交互式 API 文档请访问 `http://localhost:8001/docs`（Swagger UI）。
@@ -1,67 +0,0 @@
-import { Callout } from "nextra/components";
-
-# 概念词汇表
-
-本词汇表定义了 DeerFlow 文档中使用的核心术语。
-
---
-
-## Agent
-
-在 DeerFlow 中，Agent 是接收用户消息、决定采取什么行动（工具调用或直接响应），并生成输出的主要处理单元。DeerFlow 使用 **Lead Agent** 和**子 Agent** 两级架构。
-
-## Artifact（产出物）
-
-Agent 生成的文件——报告、图表、代码或其他交付物。产出物通过 `present_files` 工具暴露，并持久化存储在线程的用户数据目录中。
-
-## Checkpoint（检查点）
-
-线程状态的持久化快照，在每次 Agent 轮次后保存。检查点允许服务器重启后恢复对话，并支持长时序任务的状态管理。
-
-## Context Engineering（上下文工程）
-
-通过控制 Agent 在每个步骤可见的内容（通过摘要压缩、子 Agent 上下文隔离和外部文件记忆）来保持 Agent 在长时序任务中有效的实践。
-
-## Harness
-
-带有主张的 Agent 运行时，打包了工具访问、技能加载、沙箱执行、记忆、子 Agent 协调和上下文管理——而不仅仅是暴露抽象接口。
-
-## Lead Agent
-
-每个 DeerFlow 线程中的主要执行者，负责规划、工具调用和响应生成。基于 LangGraph + LangChain Agent 构建，由中间件链增强。
-
-## Long-horizon Agent（长时序 Agent）
-
-在一系列动作中保持有效的 Agent——进行规划、多次调用工具、管理中间文件，并生成最终产出物——而不是只产生单一答案。
-
-## Memory（记忆）
-
-跨多个独立对话会话持久化的结构化事实和用户上下文存储，在后续会话中注入到 Agent 的系统提示中。
-
-## Middleware（中间件）
-
-包裹每次 LLM 调用的插件，可以在模型调用前后读取和修改 Agent 状态。DeerFlow 使用中间件实现记忆、摘要压缩、标题生成等跨领域行为。
-
-## MCP（Model Context Protocol）
-
-连接语言模型与外部工具和数据源的开放标准。DeerFlow 的 MCP 集成允许连接任何兼容的工具服务器。
-
-## Sandbox（沙箱）
-
-Agent 进行文件和命令操作的隔离执行环境。DeerFlow 支持本地（`LocalSandboxProvider`）和基于容器（`AioSandboxProvider`）两种沙箱模式。
-
-## Skill（技能）
-
-面向任务的能力包，包含结构化指令、工作流程和最佳实践，按需加载到 Agent 上下文中。技能提供专业化而不污染通用 Agent 上下文。
-
-## Subagent（子 Agent）
-
-接受委派子任务的专注执行者，以隔离上下文运行，仅接收完成其分配任务所需的信息。
-
-## Thread（线程）
-
-对话及其所有相关状态——消息历史、产出物、待办列表和检查点数据——的完整封装。
-
-## ThreadState
-
-DeerFlow 中 LangGraph 管理的状态对象，包含 `messages`、`artifacts`、`todo_list` 和运行时元数据。
@@ -1,122 +0,0 @@
-import { Callout } from "nextra/components";
-
-# 配置参考
-
-本页面提供 `config.yaml` 中所有顶层字段的完整参考。
-
-<Callout type="info">
-  查看仓库根目录中的 <code>config.example.yaml</code> 获取带注释的完整配置示例。
-</Callout>
-
-## 顶层字段
-
-| 字段 | 类型 | 说明 |
-|---|---|---|
-| `config_version` | `int` | 配置 schema 版本（当前：6） |
-| `log_level` | `str` | 日志级别：`debug`/`info`/`warning`/`error` |
-| `models` | `list` | 可用的 LLM 模型配置 |
-| `image_generate_model` | `str \| list` | 图像生成使用的模型名称 |
-| `token_usage` | `object` | Token 使用追踪配置 |
-| `tools` | `list` | 可用工具配置 |
-| `tool_groups` | `list` | 工具的命名分组 |
-| `tool_search` | `object` | 延迟工具加载配置 |
-| `sandbox` | `object` | 沙箱提供者配置 |
-| `skills` | `object` | 技能目录和容器路径 |
-| `skill_evolution` | `object` | Agent 管理的技能创建 |
-| `subagents` | `object` | 子 Agent 超时和最大轮次 |
-| `acp_agents` | `dict` | 外部 ACP Agent 配置 |
-| `memory` | `object` | 跨会话记忆存储 |
-| `summarization` | `object` | 对话摘要压缩 |
-| `title` | `object` | 自动线程标题生成 |
-| `checkpointer` | `object` | 线程状态持久化 |
-| `guardrails` | `object` | 工具调用授权 |
-| `uploads` | `object` | 文件上传配置 |
-| `channels` | `list` | IM 频道集成 |
-
-## models
-
-```yaml
-models:
-  - name: gpt-4o                    # 模型标识符（在请求中引用）
-    use: langchain_openai:ChatOpenAI # Python 类路径
-    model: gpt-4o                   # 传给 LLM 的模型名称
-    api_key: $OPENAI_API_KEY        # API 密钥（支持环境变量）
-    base_url: null                  # 可选：自定义端点
-    request_timeout: 600.0         # 请求超时（秒）
-    max_retries: 2                  # 重试次数
-    supports_vision: true           # 是否启用视觉功能
-    thinking_enabled: false         # 是否启用扩展思考
-    # 任何其他字段都会传递给模型构造函数
-```
-
-## sandbox
-
-```yaml
-sandbox:
-  # 本地（默认，无容器隔离）
-  use: deerflow.sandbox.local:LocalSandboxProvider
-  allow_host_bash: false
-  bash_output_max_chars: 20000
-  read_file_output_max_chars: 50000
-  ls_output_max_chars: 20000
-
-  # 基于容器
-  # use: deerflow.community.aio_sandbox:AioSandboxProvider
-  # image: enterprise-public-cn-beijing.cr.volces.com/vefaas-public/all-in-one-sandbox:latest
-  # replicas: 3
-  # idle_timeout: 600
-```
-
-## memory
-
-```yaml
-memory:
-  enabled: true
-  storage_path: memory.json
-  debounce_seconds: 30
-  max_facts: 100
-  fact_confidence_threshold: 0.7
-  injection_enabled: true
-  max_injection_tokens: 2000
-  model_name: null
-```
-
-## summarization
-
-```yaml
-summarization:
-  enabled: true
-  model_name: null
-  trigger:
-    - type: tokens
-      value: 15564
-  keep:
-    type: messages
-    value: 10
-  trim_tokens_to_summarize: 15564
-  summary_prompt: null
-```
-
-## checkpointer
-
-```yaml
-checkpointer:
-  type: sqlite                    # sqlite | redis | postgres
-  connection_string: .deer-flow/checkpoints.db
-```
-
-## subagents
-
-```yaml
-subagents:
-  timeout_seconds: 900
-  agents:
-    general-purpose:
-      timeout_seconds: 1800
-      max_turns: 160
-    bash:
-      timeout_seconds: 300
-      max_turns: 80
-```
-
-参见各功能的文档页面了解所有字段的详细说明。
@@ -0,0 +1,9 @@
+import type { MetaRecord } from "nextra";
+
+const meta: MetaRecord = {
+  ark: {
+    title: "火山方舟",
+  },
+};
+
+export default meta;
@@ -0,0 +1,8 @@
+---
+title: 火山方舟
+description: 火山方舟模型接入指南。
+---
+
+# 火山方舟
+
+## Coding Plan
@@ -0,0 +1,7 @@
+---
+title: 模型厂商服务接入
+description: 已支持模型厂商服务的接入参考文档。
+asIndexPage: true
+---
+
+# 更多模型厂商服务接入
@@ -1,36 +0,0 @@
-# 运行时标志与模式
-
-本页面记录影响 DeerFlow Harness 和 Agent 运行时行为的运行时标志和模式。
-
-## 每次请求的可配置选项
-
-这些选项通过 `config.configurable` 字典传递（用于程序化使用）或在 Web UI 中选择（用于应用使用）：
-
-| 标志 | 类型 | 默认值 | 描述 |
-|---|---|---|---|
-| `model_name` | `str \| None` | 配置的第一个模型 | 请求使用的模型 |
-| `agent_name` | `str \| None` | `None` | 加载自定义 Agent 配置 |
-| `thinking_enabled` | `bool` | `True` | 启用扩展思考（模型必须支持） |
-| `reasoning_effort` | `str \| None` | `None` | 推理努力程度（模型特定） |
-| `is_plan_mode` | `bool` | `False` | 启用 TodoList 中间件 |
-| `subagent_enabled` | `bool` | `False` | 允许子 Agent 委派 |
-| `max_concurrent_subagents` | `int` | `3` | 最大并行子 Agent 调用数 |
-
-## 环境变量
-
-| 变量 | 默认值 | 描述 |
-|---|---|---|
-| `DEER_FLOW_CONFIG_PATH` | 自动发现 | `config.yaml` 的绝对路径 |
-| `LOG_LEVEL` | `info` | 日志级别覆盖 |
-| `DEER_FLOW_ROOT` | 仓库根目录 | Docker 挂载的基础路径 |
-| `BETTER_AUTH_SECRET` | — | 前端会话密钥（生产必须设置） |
-| `BETTER_AUTH_URL` | — | 公开 URL（用于回调和 CORS） |
-
-## 模型能力标志
-
-在 `config.yaml` 中的模型配置里设置：
-
-| 标志 | 类型 | 描述 |
-|---|---|---|
-| `supports_vision` | `bool` | 模型接受图像输入 |
-| `thinking_enabled` | `bool` | 模型支持扩展思考模式 |
@@ -1,88 +0,0 @@
-# 代码映射
-
-本页面将 DeerFlow 的核心概念映射到其在代码库中的实现位置，帮助你快速定位特定功能的代码。
-
-## 后端核心路径
-
-```
-backend/
-├── app/
-│   └── gateway/              # FastAPI Gateway API
-│       ├── routers/
-│       │   ├── agents.py     # 自定义 Agent CRUD
-│       │   ├── extensions.py # MCP/技能启用禁用
-│       │   ├── memory.py     # 记忆读取/清除
-│       │   ├── threads.py    # 线程管理
-│       │   └── uploads.py    # 文件上传
-│       └── main.py           # FastAPI 应用入口
-│
-└── packages/harness/deerflow/
-    ├── agents/
-    │   ├── lead_agent/
-    │   │   ├── agent.py      # make_lead_agent() 工厂
-    │   │   └── prompt.py     # 系统提示模板
-    │   ├── middlewares/      # 所有中间件实现
-    │   ├── memory/
-    │   │   ├── middleware.py # MemoryMiddleware
-    │   │   └── storage.py    # 记忆文件存储
-    │   └── thread_state.py   # ThreadState 数据类
-    │
-    ├── config/
-    │   ├── app_config.py     # AppConfig（顶层配置）
-    │   ├── model_config.py   # ModelConfig
-    │   ├── paths.py          # 路径解析工具
-    │   └── *.py              # 各模块配置类
-    │
-    ├── mcp/
-    │   ├── cache.py          # 基于 mtime 的工具缓存
-    │   └── oauth.py          # MCP OAuth 支持
-    │
-    ├── models/
-    │   └── factory.py        # create_chat_model() LLM 工厂
-    │
-    ├── sandbox/
-    │   ├── local/            # LocalSandboxProvider
-    │   └── sandbox.py        # Sandbox 基类
-    │
-    ├── skills/
-    │   ├── loader.py         # load_skills()（热重载）
-    │   ├── parser.py         # SKILL.md 解析
-    │   ├── installer.py      # 依赖安装
-    │   └── manager.py        # 技能生命周期
-    │
-    ├── subagents/
-    │   └── registry.py       # 子 Agent 查找与配置覆盖
-    │
-    └── tools/
-        └── builtins/         # 内置工具实现
-```
-
-## 前端核心路径
-
-```
-frontend/src/
-├── app/                      # Next.js 路由
-├── components/
-│   └── workspace/            # 工作区 UI 组件
-├── core/
-│   ├── agents/               # Agent 类型和 API 客户端
-│   ├── messages/             # 消息类型和工具调用处理
-│   └── threads/              # 线程状态管理
-└── content/                  # 文档内容（MDX）
-    ├── en/                   # 英文文档
-    └── zh/                   # 中文文档
-```
-
-## 关键文件快速索引
-
-| 目标 | 文件 |
-|---|---|
-| Lead Agent 创建 | `agents/lead_agent/agent.py` |
-| 系统提示模板 | `agents/lead_agent/prompt.py` |
-| 所有中间件 | `agents/middlewares/` |
-| 配置加载 | `config/app_config.py` |
-| 模型工厂 | `models/factory.py` |
-| 技能加载（热重载） | `skills/loader.py` |
-| MCP 工具缓存 | `mcp/cache.py` |
-| 文件上传处理 | `uploads/manager.py` |
-| Gateway 主路由器 | `app/gateway/main.py` |
@@ -1,3 +1,8 @@
+---
+title: 创建你的第一个 Harness
+description: 本教程介绍如何以编程方式使用 DeerFlow Harness Python SDK——直接在你的 Python 代码中导入和使用 DeerFlow，而不是通过 Web 界面。
+---
+
 # 创建你的第一个 Harness

 本教程介绍如何以编程方式使用 DeerFlow Harness Python SDK——直接在你的 Python 代码中导入和使用 DeerFlow，而不是通过 Web 界面。
@@ -1,3 +1,8 @@
+---
+title: 部署你的 DeerFlow
+description: 本教程引导你将 DeerFlow 部署到生产环境，使用 Docker Compose 进行多用户访问。
+---
+
 # 部署你的 DeerFlow

 本教程引导你将 DeerFlow 部署到生产环境，使用 Docker Compose 进行多用户访问。
@@ -1,3 +1,8 @@
+---
+title: 第一次对话
+description: 本教程引导你在 DeerFlow 中完成第一次完整的 Agent 对话，从启动应用到与 Agent 进行实质性任务交互。
+---
+
 # 第一次对话

 本教程引导你在 DeerFlow 中完成第一次完整的 Agent 对话，从启动应用到与 Agent 进行实质性任务交互。
@@ -1,3 +1,8 @@
+---
+title: 使用工具和技能
+description: 本教程介绍如何在 DeerFlow 中配置和使用工具（Tools）与技能（Skills），让 Agent 能够访问搜索、文件操作和特定领域能力。
+---
+
 # 使用工具和技能

 本教程介绍如何在 DeerFlow 中配置和使用工具（Tools）与技能（Skills），让 Agent 能够访问搜索、文件操作和特定领域能力。
@@ -1,3 +1,8 @@
+---
+title: 使用记忆系统
+description: 本教程介绍如何在 DeerFlow 中启用和使用记忆系统，让 Agent 在多次会话中记住关于你的重要信息。
+---
+
 # 使用记忆系统

 本教程介绍如何在 DeerFlow 中启用和使用记忆系统，让 Agent 在多次会话中记住关于你的重要信息。