chore: update the tool's doc (#6167)

api/core/tools/docs/en_US/advanced_scale_out.md

@@ -8,7 +8,7 @@ We have defined a series of helper methods in the `Tool` class to help developer
 
 ### Message Return
 
-Dify supports various message types such as `text`, `link`, `image`, and `file BLOB`. You can return different types of messages to the LLM and users through the following interfaces.
+Dify supports various message types such as `text`, `link`, `json`, `image`, and `file BLOB`. You can return different types of messages to the LLM and users through the following interfaces.
 
 Please note, some parameters in the following interfaces will be introduced in later sections.
 
@@ -67,6 +67,18 @@ If you need to return the raw data of a file, such as images, audio, video, PPT,
         """
 ```
 
+#### JSON
+If you need to return a formatted JSON, you can use the following interface. This is commonly used for data transmission between nodes in a workflow, of course, in agent mode, most LLM are also able to read and understand JSON.
+
+- `object` A Python dictionary object will be automatically serialized into JSON
+
+```python
+    def create_json_message(self, object: dict) -> ToolInvokeMessage:
+        """
+            create a json message
+        """
+```
+
 ### Shortcut Tools
 
 In large model applications, we have two common needs:

api/core/tools/docs/en_US/tool_scale_out.md

@@ -145,19 +145,25 @@ parameters: # Parameter list
 
 - The `identity` field is mandatory, it contains the basic information of the tool, including name, author, label, description, etc.
 - `parameters` Parameter list
-  - `name` Parameter name, unique, no duplication with other parameters
-  - `type` Parameter type, currently supports `string`, `number`, `boolean`, `select`, `secret-input` four types, corresponding to string, number, boolean, drop-down box, and encrypted input box, respectively. For sensitive information, we recommend using `secret-input` type
-  - `required` Required or not
+  - `name` (Mandatory) Parameter name, must be unique and not duplicate with other parameters.
+  - `type` (Mandatory) Parameter type, currently supports `string`, `number`, `boolean`, `select`, `secret-input` five types, corresponding to string, number, boolean, drop-down box, and encrypted input box, respectively. For sensitive information, we recommend using the `secret-input` type
+  - `label` (Mandatory) Parameter label, for frontend display
+  - `form` (Mandatory) Form type, currently supports `llm`, `form` two types.
+    - In an agent app, `llm` indicates that the parameter is inferred by the LLM itself, while `form` indicates that the parameter can be pre-set for the tool.
+    - In a workflow app, both `llm` and `form` need to be filled out by the front end, but the parameters of `llm` will be used as input variables for the tool node.
+  - `required` Indicates whether the parameter is required or not
     - In `llm` mode, if the parameter is required, the Agent is required to infer this parameter
     - In `form` mode, if the parameter is required, the user is required to fill in this parameter on the frontend before the conversation starts
   - `options` Parameter options
     - In `llm` mode, Dify will pass all options to LLM, LLM can infer based on these options
     - In `form` mode, when `type` is `select`, the frontend will display these options
   - `default` Default value
-  - `label` Parameter label, for frontend display
+  - `min` Minimum value, can be set when the parameter type is `number`.
+  - `max` Maximum value, can be set when the parameter type is `number`.
+  - `placeholder` The prompt text for input boxes. It can be set when the form type is `form`, and the parameter type is `string`, `number`, or `secret-input`. It supports multiple languages.
   - `human_description` Introduction for frontend display, supports multiple languages
   - `llm_description` Introduction passed to LLM, in order to make LLM better understand this parameter, we suggest to write as detailed information about this parameter as possible here, so that LLM can understand this parameter
-  - `form` Form type, currently supports `llm`, `form` two types, corresponding to Agent self-inference and frontend filling
+
 
 ## 4. Add Tool Logic
 
@@ -196,7 +202,7 @@ The overall logic of the tool is in the `_invoke` method, this method accepts tw
 
 ### Return Data
 
-When the tool returns, you can choose to return one message or multiple messages, here we return one message, using `create_text_message` and `create_link_message` can create a text message or a link message.
+When the tool returns, you can choose to return one message or multiple messages, here we return one message, using `create_text_message` and `create_link_message` can create a text message or a link message. If you want to return multiple messages, you can use `[self.create_text_message('msg1'), self.create_text_message('msg2')]` to create a list of messages.
 
 ## 5. Add Provider Code
 
@@ -205,8 +211,6 @@ Finally, we need to create a provider class under the provider module to impleme
 Create `google.py` under the `google` module, the content is as follows.
 
 ```python
-from core.tools.entities.tool_entities import ToolInvokeMessage, ToolProviderType
-from core.tools.tool.tool import Tool
 from core.tools.provider.builtin_tool_provider import BuiltinToolProviderController
 from core.tools.errors import ToolProviderCredentialValidationError
 

api/core/tools/docs/zh_Hans/advanced_scale_out.md

@@ -8,7 +8,7 @@
 
 ### 消息返回
 
-Dify支持`文本` `链接` `图片` `文件BLOB` 等多种消息类型，你可以通过以下几个接口返回不同类型的消息给LLM和用户。
+Dify支持`文本` `链接` `图片` `文件BLOB` `JSON` 等多种消息类型，你可以通过以下几个接口返回不同类型的消息给LLM和用户。
 
 注意，在下面的接口中的部分参数将在后面的章节中介绍。
 
@@ -67,6 +67,18 @@ Dify支持`文本` `链接` `图片` `文件BLOB` 等多种消息类型，你可
         """
 ```
 
+#### JSON
+如果你需要返回一个格式化的JSON，可以使用以下接口。这通常用于workflow中的节点间的数据传递，当然agent模式中，大部分大模型也都能够阅读和理解JSON。
+
+- `object` 一个Python的字典对象，会被自动序列化为JSON
+
+```python
+    def create_json_message(self, object: dict) -> ToolInvokeMessage:
+        """
+            create a json message
+        """
+```
+
 ### 快捷工具
 
 在大模型应用中，我们有两种常见的需求：
@@ -97,8 +109,8 @@ Dify支持`文本` `链接` `图片` `文件BLOB` 等多种消息类型，你可
 ```python
     def get_url(self, url: str, user_agent: str = None) -> str:
         """
-            get url
-        """ the crawled result
+            get url from the crawled result
+        """ 
 ```
 
 ### 变量池

api/core/tools/docs/zh_Hans/tool_scale_out.md

@@ -140,19 +140,25 @@ parameters: # 参数列表
 
 - `identity` 字段是必须的，它包含了工具的基本信息，包括名称、作者、标签、描述等
 - `parameters` 参数列表
-    - `name` 参数名称，唯一，不允许和其他参数重名
-    - `type` 参数类型，目前支持`string`、`number`、`boolean`、`select`、`secret-input` 五种类型，分别对应字符串、数字、布尔值、下拉框、加密输入框，对于敏感信息，我们建议使用`secret-input`类型
+    - `name` （必填）参数名称，唯一，不允许和其他参数重名
+    - `type` （必填）参数类型，目前支持`string`、`number`、`boolean`、`select`、`secret-input` 五种类型，分别对应字符串、数字、布尔值、下拉框、加密输入框，对于敏感信息，我们建议使用`secret-input`类型
+    - `label`（必填）参数标签，用于前端展示
+    - `form` （必填）表单类型，目前支持`llm`、`form`两种类型
+        - 在Agent应用中，`llm`表示该参数LLM自行推理，`form`表示要使用该工具可提前设定的参数
+        - 在workflow应用中，`llm`和`form`均需要前端填写，但`llm`的参数会做为工具节点的输入变量
     - `required` 是否必填
         - 在`llm`模式下，如果参数为必填，则会要求Agent必须要推理出这个参数
         - 在`form`模式下，如果参数为必填，则会要求用户在对话开始前在前端填写这个参数
     - `options` 参数选项
         - 在`llm`模式下，Dify会将所有选项传递给LLM，LLM可以根据这些选项进行推理
         - 在`form`模式下，`type`为`select`时，前端会展示这些选项
     - `default` 默认值
-    - `label` 参数标签，用于前端展示
+    - `min` 最小值，当参数类型为`number`时可以设定
+    - `max` 最大值，当参数类型为`number`时可以设定
     - `human_description` 用于前端展示的介绍，支持多语言
+    - `placeholder` 字段输入框的提示文字，在表单类型为`form`，参数类型为`string`、`number`、`secret-input`时，可以设定，支持多语言
     - `llm_description` 传递给LLM的介绍，为了使得LLM更好理解这个参数，我们建议在这里写上关于这个参数尽可能详细的信息，让LLM能够理解这个参数
-    - `form` 表单类型，目前支持`llm`、`form`两种类型，分别对应Agent自行推理和前端填写
+
 
 ## 4. 准备工具代码
 当完成工具的配置以后，我们就可以开始编写工具代码了，主要用于实现工具的逻辑。
@@ -176,7 +182,6 @@ class GoogleSearchTool(BuiltinTool):
         query = tool_parameters['query']
         result_type = tool_parameters['result_type']
         api_key = self.runtime.credentials['serpapi_api_key']
-        # TODO: search with serpapi
         result = SerpAPI(api_key).run(query, result_type=result_type)
 
         if result_type == 'text':
@@ -188,16 +193,14 @@ class GoogleSearchTool(BuiltinTool):
 工具的整体逻辑都在`_invoke`方法中，这个方法接收两个参数：`user_id`和`tool_parameters`，分别表示用户ID和工具参数
 
 ### 返回数据
-在工具返回时，你可以选择返回一个消息或者多个消息，这里我们返回一个消息，使用`create_text_message`和`create_link_message`可以创建一个文本消息或者一个链接消息。
+在工具返回时，你可以选择返回一条消息或者多个消息，这里我们返回一条消息，使用`create_text_message`和`create_link_message`可以创建一条文本消息或者一条链接消息。如需返回多条消息，可以使用列表构建，例如`[self.create_text_message('msg1'), self.create_text_message('msg2')]`
 
 ## 5. 准备供应商代码
 最后，我们需要在供应商模块下创建一个供应商类，用于实现供应商的凭据验证逻辑，如果凭据验证失败，将会抛出`ToolProviderCredentialValidationError`异常。
 
 在`google`模块下创建`google.py`，内容如下。
 
 ```python
-from core.tools.entities.tool_entities import ToolInvokeMessage, ToolProviderType
-from core.tools.tool.tool import Tool
 from core.tools.provider.builtin_tool_provider import BuiltinToolProviderController
 from core.tools.errors import ToolProviderCredentialValidationError
 

api/core/tools/entities/tool_entities.py

@@ -142,7 +142,8 @@ class ToolParameterForm(Enum):
 
     name: str = Field(..., description="The name of the parameter")
     label: I18nObject = Field(..., description="The label presented to the user")
-    human_description: I18nObject = Field(..., description="The description presented to the user")
+    human_description: Optional[I18nObject] = Field(None, description="The description presented to the user")
+    placeholder: Optional[I18nObject] = Field(None, description="The placeholder presented to the user")
     type: ToolParameterType = Field(..., description="The type of the parameter")
     form: ToolParameterForm = Field(..., description="The form of the parameter, schema/form/llm")
     llm_description: Optional[str] = None