docs(tutorials): add required tool names and groups (#7922)

* docs: complete tool configuration examples in tutorials Signed-off-by: ZKDplz <2646995705@qq.com> * test(docs): validate tutorial tool configuration examples Signed-off-by: ZKDplz <2646995705@qq.com> * docs: complete tool configuration examples in related guides --------- Signed-off-by: ZKDplz <2646995705@qq.com> Co-authored-by: Willem Jiang <willem.jiang@gmail.com>
2026-11-07 19:20:34 +00:00 · 2026-11-06 22:10:30 +09:00 · 2026-11-06 22:10:30 +09:00 · f9e05c24ea
commit f9e05c24ea
parent 07b4e06697
11 changed files with 352 additions and 107 deletions
--- a/backend/tests/test_tool_documentation.py
+++ b/backend/tests/test_tool_documentation.py
@ -0,0 +1,35 @@
+"""Keep documented tool examples aligned with the configuration schema."""
+
+import re
+from pathlib import Path
+
+import pytest
+import yaml
+from pydantic import TypeAdapter
+
+from deerflow.config.tool_config import ToolConfig
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+TOOL_GUIDES = (
+    "application/configuration.mdx",
+    "harness/configuration.mdx",
+    "harness/tools.mdx",
+    "tutorials/create-your-first-harness.mdx",
+    "tutorials/use-tools-and-skills.mdx",
+)
+
+
+@pytest.mark.parametrize("language", ("en", "zh"))
+@pytest.mark.parametrize("guide", TOOL_GUIDES)
+def test_tool_examples_are_valid(language: str, guide: str) -> None:
+    path = REPO_ROOT / "frontend" / "src" / "content" / language / guide
+    content = path.read_text(encoding="utf-8")
+    blocks = re.findall(r"```yaml\n(.*?)\n```", content, flags=re.DOTALL)
+    examples = [yaml.safe_load(block) for block in blocks]
+    tool_examples = [example["tools"] for example in examples if isinstance(example, dict) and "tools" in example]
+    assert tool_examples, f"no tool configuration example in {path}"
+
+    adapter = TypeAdapter(list[ToolConfig])
+    for tools in tool_examples:
+        assert tools, f"empty tool configuration example in {path}"
+        adapter.validate_python(tools)
--- a/frontend/src/content/en/application/configuration.mdx
+++ b/frontend/src/content/en/application/configuration.mdx
@ -216,24 +216,46 @@ 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.tavily.tools:web_search_tool
+  - name: web_search
+    group: web
+    use: deerflow.community.ddg_search.tools:web_search_tool # default, no key required
+  # - name: web_search
+  #   group: web
+  #   use: deerflow.community.tavily.tools:web_search_tool
  #   api_key: $TAVILY_API_KEY

  # Web fetch (choose one)
-  - use: deerflow.community.jina_ai.tools:web_fetch_tool
+  - name: web_fetch
+    group: web
+    use: deerflow.community.jina_ai.tools:web_fetch_tool

  # Image search
-  - use: deerflow.community.image_search.tools:image_search_tool
+  - name: image_search
+    group: web
+    use: deerflow.community.image_search.tools:image_search_tool

  # File operations
-  - use: deerflow.sandbox.tools:ls_tool
-  - use: deerflow.sandbox.tools:read_file_tool
-  - use: deerflow.sandbox.tools:glob_tool
-  - 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
+  - name: ls
+    group: file:read
+    use: deerflow.sandbox.tools:ls_tool
+  - name: read_file
+    group: file:read
+    use: deerflow.sandbox.tools:read_file_tool
+  - name: glob
+    group: file:read
+    use: deerflow.sandbox.tools:glob_tool
+  - name: grep
+    group: file:read
+    use: deerflow.sandbox.tools:grep_tool
+  - name: write_file
+    group: file:write
+    use: deerflow.sandbox.tools:write_file_tool
+  - name: str_replace
+    group: file:write
+    use: deerflow.sandbox.tools:str_replace_tool
+  - name: bash
+    group: bash
+    use: deerflow.sandbox.tools:bash_tool
 ```

 ### Database backend
--- a/frontend/src/content/en/harness/configuration.mdx
+++ b/frontend/src/content/en/harness/configuration.mdx
@ -65,7 +65,9 @@ sandbox:
  use: deerflow.sandbox.local:LocalSandboxProvider

 tools:
-  - use: deerflow.community.tavily.tools:web_search_tool
+  - name: web_search
+    group: web
+    use: deerflow.community.tavily.tools:web_search_tool
    api_key: $TAVILY_API_KEY
 ```

@ -147,12 +149,24 @@ 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
+  - name: web_search
+    group: web
+    use: deerflow.community.ddg_search.tools:web_search_tool
+  - name: web_fetch
+    group: web
+    use: deerflow.community.jina_ai.tools:web_fetch_tool
+  - name: ls
+    group: file:read
+    use: deerflow.sandbox.tools:ls_tool
+  - name: read_file
+    group: file:read
+    use: deerflow.sandbox.tools:read_file_tool
+  - name: write_file
+    group: file:write
+    use: deerflow.sandbox.tools:write_file_tool
+  - name: bash
+    group: bash
+    use: deerflow.sandbox.tools:bash_tool
 ```

 Start from `config.example.yaml` in the repository root and uncomment the sections you need.
--- a/frontend/src/content/en/harness/tools.mdx
+++ b/frontend/src/content/en/harness/tools.mdx
@ -98,18 +98,32 @@ These are configured in `config.yaml` under `tools:`:

 ```yaml
 tools:
-  - use: deerflow.sandbox.tools:ls_tool
-  - use: deerflow.sandbox.tools:read_file_tool
-  - use: deerflow.sandbox.tools:glob_tool
-  - 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
+  - name: ls
+    group: file:read
+    use: deerflow.sandbox.tools:ls_tool
+  - name: read_file
+    group: file:read
+    use: deerflow.sandbox.tools:read_file_tool
+  - name: glob
+    group: file:read
+    use: deerflow.sandbox.tools:glob_tool
+  - name: grep
+    group: file:read
+    use: deerflow.sandbox.tools:grep_tool
+  - name: write_file
+    group: file:write
+    use: deerflow.sandbox.tools:write_file_tool
+  - name: str_replace
+    group: file:write
+    use: deerflow.sandbox.tools:str_replace_tool
+  - name: bash
+    group: bash
+    use: deerflow.sandbox.tools:bash_tool # requires host bash or container sandbox
 ```

 ## Community tools

-Community tools connect the agent to external services. They are configured in `config.yaml` under `tools:` using the `use:` field to specify the implementation.
+Community tools connect the agent to external services. Each `tools:` entry in `config.yaml` requires `name`, `group`, and `use`. The `use` field points to the tool implementation.

 ### Web search

@ -117,14 +131,18 @@ Community tools connect the agent to external services. They are configured in `
  <Tabs.Tab>
 ```yaml
 tools:
-  - use: deerflow.community.ddg_search.tools:web_search_tool
+  - name: web_search
+    group: web
+    use: deerflow.community.ddg_search.tools:web_search_tool
 ```
 No API key required. Default configuration. Suitable for development and general use.
  </Tabs.Tab>
  <Tabs.Tab>
 ```yaml
 tools:
-  - use: deerflow.community.tavily.tools:web_search_tool
+  - name: web_search
+    group: web
+    use: deerflow.community.tavily.tools:web_search_tool
    api_key: $TAVILY_API_KEY
 ```
 High-quality search with structured results. Requires a [Tavily](https://tavily.com) API key.
@ -135,7 +153,9 @@ No extra dependency required.
  <Tabs.Tab>
 ```yaml
 tools:
-  - use: deerflow.community.brave.tools:web_search_tool
+  - name: web_search
+    group: web
+    use: deerflow.community.brave.tools:web_search_tool
    api_key: $BRAVE_SEARCH_API_KEY
 ```
 Results from Brave's independent index via the official [Brave Search API](https://brave.com/search/api/). Requires an API key. `max_results` is capped at 20.
@ -146,7 +166,9 @@ No extra dependency required.
  <Tabs.Tab>
 ```yaml
 tools:
-  - use: deerflow.community.serply.tools:web_search_tool
+  - name: web_search
+    group: web
+    use: deerflow.community.serply.tools:web_search_tool
    api_key: $SERPLY_API_KEY
    # vertical: news   # or scholar; defaults to regular Google Search
 ```
@ -158,7 +180,9 @@ No extra dependency required.
  <Tabs.Tab>
 ```yaml
 tools:
-  - use: deerflow.community.exa.tools:web_search_tool
+  - name: web_search
+    group: web
+    use: deerflow.community.exa.tools:web_search_tool
    api_key: $EXA_API_KEY
 ```
 Semantic search with neural retrieval. Requires an [Exa](https://exa.ai) API key. Set `base_url` (or `EXA_BASE_URL`) to use an Exa-compatible endpoint.
@ -169,7 +193,9 @@ No extra dependency required.
  <Tabs.Tab>
 ```yaml
 tools:
-  - use: deerflow.community.infoquest.tools:web_search_tool
+  - name: web_search
+    group: web
+    use: deerflow.community.infoquest.tools:web_search_tool
    api_key: $INFOQUEST_API_KEY
 ```
 InfoQuest search integration.
@ -177,7 +203,9 @@ InfoQuest search integration.
  <Tabs.Tab>
 ```yaml
 tools:
-  - use: deerflow.community.firecrawl.tools:web_search_tool
+  - name: web_search
+    group: web
+    use: deerflow.community.firecrawl.tools:web_search_tool
    api_key: $FIRECRAWL_API_KEY
 ```
 Firecrawl-powered search and crawl. Requires a [Firecrawl](https://firecrawl.dev) API key.
@ -188,7 +216,9 @@ No extra dependency required.
  <Tabs.Tab>
 ```yaml
 tools:
-  - use: deerflow.community.groundroute.tools:web_search_tool
+  - name: web_search
+    group: web
+    use: deerflow.community.groundroute.tools:web_search_tool
    api_key: $GROUNDROUTE_API_KEY
 ```
 GroundRoute is a meta search layer: one API in front of six engines (Serper, Brave, Exa, Tavily, Firecrawl, Perplexity). Routes each query to the cheapest engine that clears a quality bar and fails over if one is down. Pricing is gain-share, you keep about half of any cache savings.
@ -201,7 +231,9 @@ Install: `cd backend && uv add 'deerflow-harness[groundroute]'`
  <Tabs.Tab>
 ```yaml
 tools:
-  - use: deerflow.community.sofya.tools:web_search_tool
+  - name: web_search
+    group: web
+    use: deerflow.community.sofya.tools:web_search_tool
    api_key: $SOFYA_API_KEY
 ```
 Results include the content of each page, not only a snippet. Requires a [Sofya](https://sofya.co) API key. `max_results` is capped at 20, and each result's content is capped at `contents_max_characters` (default 2000, set 0 for no cap). Also supports `web_fetch`.
@ -209,7 +241,9 @@ Results include the content of each page, not only a snippet. Requires a [Sofya]
  <Tabs.Tab>
 ```yaml
 tools:
-  - use: deerflow.community.youcom.tools:web_search_tool
+  - name: web_search
+    group: web
+    use: deerflow.community.youcom.tools:web_search_tool
    # api_key: $YDC_API_KEY # optional; omit to use the keyless free tier
 ```
 Results from You.com's own index, each carrying extracted page snippets rather than a
@ -230,7 +264,9 @@ No extra dependency required.
  <Tabs.Tab>
 ```yaml
 tools:
-  - use: deerflow.community.jina_ai.tools:web_fetch_tool
+  - name: web_fetch
+    group: web
+    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
@ -250,35 +286,45 @@ Renders JavaScript-heavy pages with headless Chrome, then extracts readable Mark
  <Tabs.Tab>
 ```yaml
 tools:
-  - use: deerflow.community.exa.tools:web_fetch_tool
+  - name: web_fetch
+    group: web
+    use: deerflow.community.exa.tools:web_fetch_tool
    api_key: $EXA_API_KEY
 ```
  </Tabs.Tab>
  <Tabs.Tab>
 ```yaml
 tools:
-  - use: deerflow.community.infoquest.tools:web_fetch_tool
+  - name: web_fetch
+    group: web
+    use: deerflow.community.infoquest.tools:web_fetch_tool
    api_key: $INFOQUEST_API_KEY
 ```
  </Tabs.Tab>
  <Tabs.Tab>
 ```yaml
 tools:
-  - use: deerflow.community.firecrawl.tools:web_fetch_tool
+  - name: web_fetch
+    group: web
+    use: deerflow.community.firecrawl.tools:web_fetch_tool
    api_key: $FIRECRAWL_API_KEY
 ```
  </Tabs.Tab>
  <Tabs.Tab>
 ```yaml
 tools:
-  - use: deerflow.community.groundroute.tools:web_fetch_tool
+  - name: web_fetch
+    group: web
+    use: deerflow.community.groundroute.tools:web_fetch_tool
    api_key: $GROUNDROUTE_API_KEY
 ```
  </Tabs.Tab>
  <Tabs.Tab>
 ```yaml
 tools:
-  - use: deerflow.community.sofya.tools:web_fetch_tool
+  - name: web_fetch
+    group: web
+    use: deerflow.community.sofya.tools:web_fetch_tool
    api_key: $SOFYA_API_KEY
 ```
 Returns the page as markdown. Requires a [Sofya](https://sofya.co) API key.
@ -286,7 +332,9 @@ Returns the page as markdown. Requires a [Sofya](https://sofya.co) API key.
  <Tabs.Tab>
 ```yaml
 tools:
-  - use: deerflow.community.unbrowse.tools:web_fetch_tool
+  - name: web_fetch
+    group: web
+    use: deerflow.community.unbrowse.tools:web_fetch_tool
    api_key: $UNBROWSE_API_KEY
    # render: auto # auto | never (plain HTTP only) | always (cloud browser)
 ```
@ -323,14 +371,18 @@ set `allow_private_addresses: true` only when you intentionally target an intern
  <Tabs.Tab>
 ```yaml
 tools:
-  - use: deerflow.community.image_search.tools:image_search_tool
+  - name: image_search
+    group: web
+    use: deerflow.community.image_search.tools:image_search_tool
 ```
 No API key required. Default configuration, good for development and general use.
  </Tabs.Tab>
  <Tabs.Tab>
 ```yaml
 tools:
-  - use: deerflow.community.infoquest.tools:image_search_tool
+  - name: image_search
+    group: web
+    use: deerflow.community.infoquest.tools:image_search_tool
    api_key: $INFOQUEST_API_KEY
 ```
 Requires an InfoQuest API key.
@ -338,7 +390,9 @@ Requires an InfoQuest API key.
  <Tabs.Tab>
 ```yaml
 tools:
-  - use: deerflow.community.serper.tools:image_search_tool
+  - name: image_search
+    group: web
+    use: deerflow.community.serper.tools:image_search_tool
    api_key: $SERPER_API_KEY
 ```
 Google Images results via Serper. Requires a [Serper](https://serper.dev) API key. Reuses `SERPER_API_KEY` with the Serper `web_search` tool.
@ -346,7 +400,9 @@ Google Images results via Serper. Requires a [Serper](https://serper.dev) API ke
  <Tabs.Tab>
 ```yaml
 tools:
-  - use: deerflow.community.brave.tools:image_search_tool
+  - name: image_search
+    group: web
+    use: deerflow.community.brave.tools:image_search_tool
    api_key: $BRAVE_SEARCH_API_KEY
 ```
 Independent image results via Brave Image Search. Requires a [Brave Search API](https://brave.com/search/api/) key. Reuses `BRAVE_SEARCH_API_KEY` with the Brave `web_search` tool.
--- a/frontend/src/content/en/tutorials/create-your-first-harness.mdx
+++ b/frontend/src/content/en/tutorials/create-your-first-harness.mdx
@ -39,9 +39,15 @@ sandbox:
  use: deerflow.sandbox.local:LocalSandboxProvider

 tools:
-  - use: deerflow.community.ddg_search.tools:web_search_tool
-  - use: deerflow.sandbox.tools:read_file_tool
-  - use: deerflow.sandbox.tools:write_file_tool
+  - name: web_search
+    group: web
+    use: deerflow.community.ddg_search.tools:web_search_tool
+  - name: read_file
+    group: file:read
+    use: deerflow.sandbox.tools:read_file_tool
+  - name: write_file
+    group: file:write
+    use: deerflow.sandbox.tools:write_file_tool
 ```

 ## Write the code
--- a/frontend/src/content/en/tutorials/use-tools-and-skills.mdx
+++ b/frontend/src/content/en/tutorials/use-tools-and-skills.mdx
@ -16,16 +16,28 @@ Add tools to `config.yaml`:
 ```yaml
 tools:
  # Web search
-  - use: deerflow.community.ddg_search.tools:web_search_tool
+  - name: web_search
+    group: web
+    use: deerflow.community.ddg_search.tools:web_search_tool

  # Web content fetching
-  - use: deerflow.community.jina_ai.tools:web_fetch_tool
+  - name: web_fetch
+    group: web
+    use: deerflow.community.jina_ai.tools:web_fetch_tool

  # Sandbox file operations
-  - 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
+  - name: ls
+    group: file:read
+    use: deerflow.sandbox.tools:ls_tool
+  - name: read_file
+    group: file:read
+    use: deerflow.sandbox.tools:read_file_tool
+  - name: write_file
+    group: file:write
+    use: deerflow.sandbox.tools:write_file_tool
+  - name: bash
+    group: bash
+    use: deerflow.sandbox.tools:bash_tool
 ```

 ## Enabling skills
--- a/frontend/src/content/zh/application/configuration.mdx
+++ b/frontend/src/content/zh/application/configuration.mdx
@ -189,12 +189,24 @@ sandbox:

 ```yaml
 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
+  - name: web_search
+    group: web
+    use: deerflow.community.ddg_search.tools:web_search_tool
+  - name: web_fetch
+    group: web
+    use: deerflow.community.jina_ai.tools:web_fetch_tool
+  - name: ls
+    group: file:read
+    use: deerflow.sandbox.tools:ls_tool
+  - name: read_file
+    group: file:read
+    use: deerflow.sandbox.tools:read_file_tool
+  - name: write_file
+    group: file:write
+    use: deerflow.sandbox.tools:write_file_tool
+  - name: bash
+    group: bash
+    use: deerflow.sandbox.tools:bash_tool
 ```

 ### 技能
--- a/frontend/src/content/zh/harness/configuration.mdx
+++ b/frontend/src/content/zh/harness/configuration.mdx
@ -64,7 +64,9 @@ sandbox:
  use: deerflow.sandbox.local:LocalSandboxProvider

 tools:
-  - use: deerflow.community.tavily.tools:web_search_tool
+  - name: web_search
+    group: web
+    use: deerflow.community.tavily.tools:web_search_tool
    api_key: $TAVILY_API_KEY
 ```

@ -145,12 +147,24 @@ 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
+  - name: web_search
+    group: web
+    use: deerflow.community.ddg_search.tools:web_search_tool
+  - name: web_fetch
+    group: web
+    use: deerflow.community.jina_ai.tools:web_fetch_tool
+  - name: ls
+    group: file:read
+    use: deerflow.sandbox.tools:ls_tool
+  - name: read_file
+    group: file:read
+    use: deerflow.sandbox.tools:read_file_tool
+  - name: write_file
+    group: file:write
+    use: deerflow.sandbox.tools:write_file_tool
+  - name: bash
+    group: bash
+    use: deerflow.sandbox.tools:bash_tool
 ```

 从仓库根目录的 `config.example.yaml` 开始，取消注释你需要的章节。
--- a/frontend/src/content/zh/harness/tools.mdx
+++ b/frontend/src/content/zh/harness/tools.mdx
@ -95,18 +95,32 @@ task(agent="general-purpose", task="...", context="...")

 ```yaml
 tools:
-  - use: deerflow.sandbox.tools:ls_tool
-  - use: deerflow.sandbox.tools:read_file_tool
-  - use: deerflow.sandbox.tools:glob_tool
-  - 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
+  - name: ls
+    group: file:read
+    use: deerflow.sandbox.tools:ls_tool
+  - name: read_file
+    group: file:read
+    use: deerflow.sandbox.tools:read_file_tool
+  - name: glob
+    group: file:read
+    use: deerflow.sandbox.tools:glob_tool
+  - name: grep
+    group: file:read
+    use: deerflow.sandbox.tools:grep_tool
+  - name: write_file
+    group: file:write
+    use: deerflow.sandbox.tools:write_file_tool
+  - name: str_replace
+    group: file:write
+    use: deerflow.sandbox.tools:str_replace_tool
+  - name: bash
+    group: bash
+    use: deerflow.sandbox.tools:bash_tool
 ```

 ## 社区工具

-社区工具将 Agent 连接到外部服务。在 `config.yaml` 的 `tools:` 下使用 `use:` 字段指定实现来配置。
+社区工具将 Agent 连接到外部服务。`config.yaml` 的 `tools:` 下每个条目都必须包含 `name`、`group` 和 `use`。`use` 指向工具实现。

 ### 网络搜索

@ -114,14 +128,18 @@ tools:
  <Tabs.Tab>
 ```yaml
 tools:
-  - use: deerflow.community.ddg_search.tools:web_search_tool
+  - name: web_search
+    group: web
+    use: deerflow.community.ddg_search.tools:web_search_tool
 ```
 无需 API Key。默认配置，适合开发和通用用途。
  </Tabs.Tab>
  <Tabs.Tab>
 ```yaml
 tools:
-  - use: deerflow.community.tavily.tools:web_search_tool
+  - name: web_search
+    group: web
+    use: deerflow.community.tavily.tools:web_search_tool
    api_key: $TAVILY_API_KEY
 ```
 高质量搜索，带结构化结果。需要 [Tavily](https://tavily.com) API Key。
@ -132,7 +150,9 @@ tools:
  <Tabs.Tab>
 ```yaml
 tools:
-  - use: deerflow.community.brave.tools:web_search_tool
+  - name: web_search
+    group: web
+    use: deerflow.community.brave.tools:web_search_tool
    api_key: $BRAVE_SEARCH_API_KEY
 ```
 通过官方 [Brave Search API](https://brave.com/search/api/) 返回 Brave 独立索引的结果。需要 API Key，`max_results` 上限为 20。
@ -143,7 +163,9 @@ tools:
  <Tabs.Tab>
 ```yaml
 tools:
-  - use: deerflow.community.serply.tools:web_search_tool
+  - name: web_search
+    group: web
+    use: deerflow.community.serply.tools:web_search_tool
    api_key: $SERPLY_API_KEY
    # vertical: news   # 或 scholar；默认为普通 Google 搜索
 ```
@ -155,7 +177,9 @@ tools:
  <Tabs.Tab>
 ```yaml
 tools:
-  - use: deerflow.community.exa.tools:web_search_tool
+  - name: web_search
+    group: web
+    use: deerflow.community.exa.tools:web_search_tool
    api_key: $EXA_API_KEY
 ```
 带神经检索的语义搜索。需要 [Exa](https://exa.ai) API Key。设置 `base_url`（或 `EXA_BASE_URL`）可使用兼容 Exa 的端点。
@ -166,7 +190,9 @@ tools:
  <Tabs.Tab>
 ```yaml
 tools:
-  - use: deerflow.community.infoquest.tools:web_search_tool
+  - name: web_search
+    group: web
+    use: deerflow.community.infoquest.tools:web_search_tool
    api_key: $INFOQUEST_API_KEY
 ```
 InfoQuest 搜索集成。
@ -174,7 +200,9 @@ InfoQuest 搜索集成。
  <Tabs.Tab>
 ```yaml
 tools:
-  - use: deerflow.community.firecrawl.tools:web_search_tool
+  - name: web_search
+    group: web
+    use: deerflow.community.firecrawl.tools:web_search_tool
    api_key: $FIRECRAWL_API_KEY
 ```
 Firecrawl 驱动的搜索和爬取。需要 [Firecrawl](https://firecrawl.dev) API Key。
@ -182,7 +210,9 @@ Firecrawl 驱动的搜索和爬取。需要 [Firecrawl](https://firecrawl.dev) A
  <Tabs.Tab>
 ```yaml
 tools:
-  - use: deerflow.community.groundroute.tools:web_search_tool
+  - name: web_search
+    group: web
+    use: deerflow.community.groundroute.tools:web_search_tool
    api_key: $GROUNDROUTE_API_KEY
 ```
 GroundRoute 是一个元搜索层：一个 API 接入六个搜索引擎（Serper、Brave、Exa、Tavily、Firecrawl、Perplexity）。为每个查询路由到满足质量门槛的最低成本引擎，并在引擎故障时自动切换。定价采用收益分成模式，您可保留约一半的缓存节省。
@ -195,7 +225,9 @@ GroundRoute 是一个元搜索层：一个 API 接入六个搜索引擎（Serper
  <Tabs.Tab>
 ```yaml
 tools:
-  - use: deerflow.community.sofya.tools:web_search_tool
+  - name: web_search
+    group: web
+    use: deerflow.community.sofya.tools:web_search_tool
    api_key: $SOFYA_API_KEY
 ```
 搜索结果包含每个页面的正文内容，而不仅是摘要。需要 [Sofya](https://sofya.co) API Key，`max_results` 上限为 20，每条结果的正文长度上限由 `contents_max_characters` 控制（默认 2000，设为 0 则不限制）。同时支持 `web_fetch`。
@ -203,7 +235,9 @@ tools:
  <Tabs.Tab>
 ```yaml
 tools:
-  - use: deerflow.community.youcom.tools:web_search_tool
+  - name: web_search
+    group: web
+    use: deerflow.community.youcom.tools:web_search_tool
    # api_key: $YDC_API_KEY # 可选；不填则使用免密钥的免费额度
 ```
 返回 You.com 自有索引的结果，每条结果附带从页面提取的片段，而不只是一段元描述。未配置 Key 时使用免密钥端点（免费额度，目前为每天 100 次搜索）；配置 `YDC_API_KEY` 后自动切换到额度更高的完整 Search API。`max_results` 上限为 100。
@ -221,7 +255,9 @@ API Key 可选，可在 [You.com](https://you.com/platform) 获取。
  <Tabs.Tab>
 ```yaml
 tools:
-  - use: deerflow.community.jina_ai.tools:web_fetch_tool
+  - name: web_fetch
+    group: web
+    use: deerflow.community.jina_ai.tools:web_fetch_tool
    api_key: $JINA_API_KEY # 可选；匿名使用有速率限制
 ```
 将网页转换为干净的 Markdown。无 API Key 也可使用，但有更严格的速率限制。
@ -240,35 +276,45 @@ tools:
  <Tabs.Tab>
 ```yaml
 tools:
-  - use: deerflow.community.exa.tools:web_fetch_tool
+  - name: web_fetch
+    group: web
+    use: deerflow.community.exa.tools:web_fetch_tool
    api_key: $EXA_API_KEY
 ```
  </Tabs.Tab>
  <Tabs.Tab>
 ```yaml
 tools:
-  - use: deerflow.community.infoquest.tools:web_fetch_tool
+  - name: web_fetch
+    group: web
+    use: deerflow.community.infoquest.tools:web_fetch_tool
    api_key: $INFOQUEST_API_KEY
 ```
  </Tabs.Tab>
  <Tabs.Tab>
 ```yaml
 tools:
-  - use: deerflow.community.firecrawl.tools:web_fetch_tool
+  - name: web_fetch
+    group: web
+    use: deerflow.community.firecrawl.tools:web_fetch_tool
    api_key: $FIRECRAWL_API_KEY
 ```
  </Tabs.Tab>
  <Tabs.Tab>
 ```yaml
 tools:
-  - use: deerflow.community.groundroute.tools:web_fetch_tool
+  - name: web_fetch
+    group: web
+    use: deerflow.community.groundroute.tools:web_fetch_tool
    api_key: $GROUNDROUTE_API_KEY
 ```
  </Tabs.Tab>
  <Tabs.Tab>
 ```yaml
 tools:
-  - use: deerflow.community.sofya.tools:web_fetch_tool
+  - name: web_fetch
+    group: web
+    use: deerflow.community.sofya.tools:web_fetch_tool
    api_key: $SOFYA_API_KEY
 ```
 以 Markdown 形式返回页面内容。需要 [Sofya](https://sofya.co) API Key。
@ -276,7 +322,9 @@ tools:
  <Tabs.Tab>
 ```yaml
 tools:
-  - use: deerflow.community.unbrowse.tools:web_fetch_tool
+  - name: web_fetch
+    group: web
+    use: deerflow.community.unbrowse.tools:web_fetch_tool
    api_key: $UNBROWSE_API_KEY
    # render: auto # auto | never（仅普通 HTTP）| always（云端浏览器）
 ```
@ -312,14 +360,18 @@ Tailscale 使用）、其他非全局或云元数据地址的 URL；仅在确实
  <Tabs.Tab>
 ```yaml
 tools:
-  - use: deerflow.community.image_search.tools:image_search_tool
+  - name: image_search
+    group: web
+    use: deerflow.community.image_search.tools:image_search_tool
 ```
 无需 API Key。默认配置，适合开发和通用用途。
  </Tabs.Tab>
  <Tabs.Tab>
 ```yaml
 tools:
-  - use: deerflow.community.infoquest.tools:image_search_tool
+  - name: image_search
+    group: web
+    use: deerflow.community.infoquest.tools:image_search_tool
    api_key: $INFOQUEST_API_KEY
 ```
 需要 InfoQuest API Key。
@ -327,7 +379,9 @@ tools:
  <Tabs.Tab>
 ```yaml
 tools:
-  - use: deerflow.community.serper.tools:image_search_tool
+  - name: image_search
+    group: web
+    use: deerflow.community.serper.tools:image_search_tool
    api_key: $SERPER_API_KEY
 ```
 通过 Serper 获取 Google 图片结果。需要 [Serper](https://serper.dev) API Key，与 Serper `web_search` 工具复用同一个 `SERPER_API_KEY`。
@ -335,7 +389,9 @@ tools:
  <Tabs.Tab>
 ```yaml
 tools:
-  - use: deerflow.community.brave.tools:image_search_tool
+  - name: image_search
+    group: web
+    use: deerflow.community.brave.tools:image_search_tool
    api_key: $BRAVE_SEARCH_API_KEY
 ```
 通过 Brave Image Search 获取独立图片结果。需要 [Brave Search API](https://brave.com/search/api/) Key，与 Brave `web_search` 工具复用同一个 `BRAVE_SEARCH_API_KEY`。
--- a/frontend/src/content/zh/tutorials/create-your-first-harness.mdx
+++ b/frontend/src/content/zh/tutorials/create-your-first-harness.mdx
@ -37,9 +37,15 @@ sandbox:
  use: deerflow.sandbox.local:LocalSandboxProvider

 tools:
-  - use: deerflow.community.ddg_search.tools:web_search_tool
-  - use: deerflow.sandbox.tools:read_file_tool
-  - use: deerflow.sandbox.tools:write_file_tool
+  - name: web_search
+    group: web
+    use: deerflow.community.ddg_search.tools:web_search_tool
+  - name: read_file
+    group: file:read
+    use: deerflow.sandbox.tools:read_file_tool
+  - name: write_file
+    group: file:write
+    use: deerflow.sandbox.tools:write_file_tool
 ```

 ## 编写代码
--- a/frontend/src/content/zh/tutorials/use-tools-and-skills.mdx
+++ b/frontend/src/content/zh/tutorials/use-tools-and-skills.mdx
@ -14,16 +14,28 @@ description: 本教程介绍如何在 DeerFlow 中配置和使用工具（Tools
 ```yaml
 tools:
  # 网络搜索
-  - use: deerflow.community.ddg_search.tools:web_search_tool
+  - name: web_search
+    group: web
+    use: deerflow.community.ddg_search.tools:web_search_tool

  # 网页内容抓取
-  - use: deerflow.community.jina_ai.tools:web_fetch_tool
+  - name: web_fetch
+    group: web
+    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
+  - name: ls
+    group: file:read
+    use: deerflow.sandbox.tools:ls_tool
+  - name: read_file
+    group: file:read
+    use: deerflow.sandbox.tools:read_file_tool
+  - name: write_file
+    group: file:write
+    use: deerflow.sandbox.tools:write_file_tool
+  - name: bash
+    group: bash
+    use: deerflow.sandbox.tools:bash_tool
 ```

 ## 启用技能