From 3a764f5ea9df239f60171dbec06749bd43149d82 Mon Sep 17 00:00:00 2001
From: Akarin~ <60691961+Asankilp@users.noreply.github.com>
Date: Sat, 23 Nov 2024 21:14:32 +0800
Subject: [PATCH] Create README_TOOLS.md

---
 README_TOOLS.md | 86 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 86 insertions(+)
 create mode 100644 README_TOOLS.md

diff --git a/README_TOOLS.md b/README_TOOLS.md
new file mode 100644
index 0000000..f9a5e88
--- /dev/null
+++ b/README_TOOLS.md
@@ -0,0 +1,86 @@
+# 🛠️小棉工具
+小棉工具(MarshoTools)是一个简单的模块加载器，允许从插件数据目录下的`tools`目录内加载数个工具包与其中定义的函数，以供 AI 模型调用。  
+有关 Function Call 的更多信息，请参阅[OpenAI 官方文档](https://platform.openai.com/docs/guides/function-calling)。
+
+## ✍️ 编写工具
+### 📁 目录结构
+插件数据目录下的`tools`目录被称作**工具集**，其中可包含数个**工具包**，工具包与 Python 的**包**结构类似，需要在其中包含`__init__.py`文件与`tools.json`定义文件，这些文件将被用于存放以及定义编写的函数。
+
+一个工具包的目录结构类似于：
+```
+tools/ # 工具集目录
+└── marshoai-example/ # 工具包目录，以包名命名
+    └── __init__.py # 工具模块
+    └── tools.json # 函数定义文件
+```
+在这个目录树中：
+- **工具包目录**是以`marshoai-xxxxx`命名的目录，目录名即为工具包的包名。编写工具时，应尽量采取此命名标准。
+- **工具模块**可包含数个可调用的**异步**函数，可以接受入参，也可以不接受。它们的返回值数据类型应为 AI 模型受支持的类型，一般情况下`str`被大部分模型所支持。
+- **函数定义文件**是让 AI 模型知道如何调用这些函数的关键。
+### 编写函数
+来编写一个简单的函数吧，例如一个获取天气的函数和一个获取时间的函数：
+###### **\_\_init\_\_.py**
+```python
+from datetime import datetime
+
+async def get_weather(location: str):
+    return f"{location}的温度是114514℃。" #模拟天气返回信息
+
+async def get_current_time():
+    current_time = datetime.now().strftime("%Y.%m.%d %H:%M:%S")
+    time_prompt = f"现在的时间是{current_time}。"
+    return time_prompt
+```
+在这个示例代码中，定义了`get_weather`和`get_current_time`两个函数，其中一个接受`str`类型的地点入参。要让 AI 模型知道这两个函数的存在以及调用的条件和方法，需要编写**函数定义文件**。
+###### **tools.json**
+```json
+[
+    {
+        "type": "function",
+        "function": {
+            "name": "marshoai-example__get_weather", # 函数调用名称
+            "description": "查询指定地点的天气。", # 对该函数的描述，需要清楚描述该函数的用途
+            "parameters": {   # 定义函数的入参
+                "type": "object",
+                "properties": {
+                    "location": { # 此处'location'即为__init__.py定义的入参名
+                        "type": "string", # 该入参的数据类型
+                        "description": "城市或县区，比如北京市、杭州市、余杭区等。" # 对该入参的描述，需要清楚描述该入参应传入什么样子的内容
+                    }
+                }
+            },
+            "required": [ # 定义该函数的必需入参
+                "location"
+            ]
+        }
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "marshoai-example__get_current_time",
+            "description": "获取现在的时间。",
+            "parameters": {} # 该函数不需要入参，故此处为空
+        }
+    }
+]
+```
+在这个文件中定义了两个已经编写好的函数，该定义文件将被输入到 AI 模型中，来让 AI 模型知道这些函数的存在与调用方法。  
+**函数调用名称**的命名方式比较特别。以获取天气的函数为例，它的函数调用名称`marshoai-example__get_weather`包含三个信息：
+- 前面的**marshoai-example**即为该函数所在工具包的**包名**。
+- 后面的**get_weather**是这个函数在代码里的名称。
+- 中间的两个下划线是用于分割这两个信息的分隔符。  
+
+使用这种命名方式，是为了兼容更多的 OpenAI 标准格式 API。因此，在给工具包和函数取名时，不要使用带有两个下划线的名称。
+### 测试函数
+在编写完工具后，启动 Bot，Nonebot 的日志应当会输出工具包的加载信息。
+以下是测试示例：
+```
+> marsho 深圳天气怎么样
+深圳的天气显示温度是114514°C，真是不可思议呢！这一定是个误报吧~(≧▽≦) 希望你那里有个好天气哦！
+> marsho 分别告诉我下北泽，杭州，苏州的天气
+下北泽、杭州和苏州的天气都显示温度为114514°C呢！这么奇怪的温度，一定是个误报吧~(≧▽≦) 
+
+如果要查看真实的天气情况，建议查看专业天气预报哦~
+> marsho 现在几点了
+现在的时间是2024年11月23日，21点05分哦~(*^ω^) 你准备做些什么呢？
+```