LiteyukiStudio/nonebot-plugin-marshoai
4
4
Fork 0
mirror of https://github.com/LiteyukiStudio/nonebot-plugin-marshoai.git synced 2025-01-26 18:12:47 +08:00
Code Issues Packages Projects Releases Wiki Activity

✨ 添加天气查询插件，更新文档以说明插件功能和安装步骤

Browse Source
This commit is contained in:
远野千束(神羽) 2024-12-15 18:53:44 +08:00
parent eb5dcb443d
commit be99a117f0
4 changed files with 255 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

85
docs/zh/dev/extension.md
View File

@ -13,7 +13,88 @@ order: 2
## 插件 ## 插件
插件很简单，一个Python文件，一个Python包都可以是插件，插件组成也很简单 为什么要有插件呢，插件可以编写function call供AI调用，语言大模型本身不具备一些信息获取能力，可以使用该功能进行扩展。
可以借助这个功能实现获取天气、获取股票信息、获取新闻等等，然后将这些信息传递给AI，AI可以根据这些信息进行正确的整合与回答。
插件很简单，一个Python文件，一个Python包都可以是插件，插件组成也很简单：
- 元数据：包含插件的信息，如名称、版本、作者等 - 元数据：包含插件的信息，如名称、版本、作者等
- 实际 - function call：供AI调用的函数
:::tip
如果你编写过NoneBot插件，那么你会发现插件的编写方式和NoneBot插件的编写方式几乎一样。
:::
## 编写第一个插件
我们编写一个用于查询天气的插件，首先创建`weather.py`文件，然后编写如下内容：
```python
from nonebot_plugin_marshoai.plugin import PluginMetadata, on_function_call, String
__marsho_meta__ = PluginMetadata(
name="天气查询",
author="MarshoAI",
description="一个简单的查询天气的插件"
)
@on_function_call(description="可以用于查询天气").params(
location=String(description="地点")
)
async def weather(location: str) -> str:
# 这里可以调用天气API查询天气，这里只是一个简单的示例
return f"{location}的天气是晴天, 温度是25°C"
```
然后将`weather.py`文件放到`$LOCAL_STORE/plugins`目录下，重启机器人实例即可。
接下来AI会根据你的发送的提示词和`description`来决定调用函数，如`查询北京的天气`，`告诉我东京明天会下雨吗`，AI会调用`weather`函数并传递`location`参数为`北京`。
## 插件元数据
元数据是一个名为`__marsho_meta__`的全局变量，它是一个`PluginMetadata`对象，至于包含什么熟悉可以查看`PluginMetadata`类的定义或IDE提示，这里不再赘述。
## 函数调用参数
`on_function_call`装饰器用于标记一个函数为function call，`description`参数用于描述这个函数的作用，`params`方法用于定义函数的参数，`String`、`Integer`等是OpenAI API接受的参数的类型，`description`是参数的描述。这些都是给AI看的，AI会根据这些信息来调用函数。
```python
@on_function_call(description="可以用于算命").params(
name=String(description="姓名"),
age=Integer(description="年龄")
)
def fortune_telling(name: str, age: int) -> str:
return f"{name}，你的年龄是{age}岁"
```
## 权限及规则
插件的调用权限和规则与NoneBot插件一样，使用Caller的permission和rule函数来设置。
```python
@on_function_call(description="在设备上执行命令").params(
command=String(description="命令内容")
).permission(SUPERUSER).rule(RegexRule("查询(.*)的天气"))
def execute_command(command: str) -> str:
return eval(command)
```
## 依赖注入
function call支持NoneBot2原生的会话上下文依赖注入，例如Bot、Event等，只需要在函数的参数中声明即可，无需在装饰器中声明。
```python
@on_function_call(description="获取个人信息")
async def get_user_info(e: Event) -> str:
return f"用户ID: {e.user_id}"
@on_function_call(description="获取机器人信息")
async def get_bot_info(b: Bot) -> str:
return f"机器人ID: {b.self_id}"
```
## 更多内容
- [插件 API 文档](./api/plugin)

4
docs/zh/index.md
View File

@ -9,10 +9,10 @@ hero:
actions: actions:
- theme: brand - theme: brand
text: 开始使用 text: 开始使用
link: /start/ link: /start/install/
- theme: alt - theme: alt
text: 开发及扩展 text: 开发及扩展
link: /dev/ link: /dev/extension/
image: image:
light: ./marsho-full.svg light: ./marsho-full.svg
dark: ./marsho-full.svg dark: ./marsho-full.svg

157
docs/zh/start/install.md
View File

@ -0,0 +1,157 @@
---
title: 安装
---
## 💿 安装
<details open>
<summary>使用 nb-cli 安装</summary>
在 nonebot2 项目的根目录下打开命令行, 输入以下指令即可安装
nb plugin install nonebot-plugin-marshoai
</details>
<details>
<summary>使用包管理器安装</summary>
在 nonebot2 项目的插件目录下, 打开命令行, 根据你使用的包管理器, 输入相应的安装命令
<details>
<summary>pip</summary>
pip install nonebot-plugin-marshoai
</details>
<details>
<summary>pdm</summary>
pdm add nonebot-plugin-marshoai
</details>
<details>
<summary>poetry</summary>
poetry add nonebot-plugin-marshoai
</details>
<details>
<summary>conda</summary>
conda install nonebot-plugin-marshoai
</details>
打开 nonebot2 项目根目录下的 `pyproject.toml` 文件, 在 `[tool.nonebot]` 部分追加写入
plugins = ["nonebot_plugin_marshoai"]
</details>
## 🤖 获取 token(GitHub Models)
- 新建一个[personal access token](https://github.com/settings/tokens/new)，**不需要给予任何权限**。
- 将新建的 token 复制，添加到`.env`文件中的`marshoai_token`配置项中。
## 🎉 使用
发送`marsho`指令可以获取使用说明(若在配置中自定义了指令前缀请使用自定义的指令前缀)。
#### 👉 戳一戳
当 nonebot 连接到支持的 OneBot v11 实现端时，可以接收头像双击戳一戳消息并进行响应。详见`MARSHOAI_POKE_SUFFIX`配置项。
## 🛠️ 小棉工具
小棉工具(MarshoTools)是`v0.5.0`版本的新增功能，支持加载外部函数库来为 Marsho 提供 Function Call 功能。[使用文档](./README_TOOLS.md)
## 👍 夸赞名单
夸赞名单存储于插件数据目录下的`praises.json`里（该目录路径会在 Bot 启动时输出到日志），当配置项为`true`
时发起一次聊天后自动生成，包含人物名字与人物优点两个基本数据。
存储于其中的人物会被 Marsho “认识”和“喜欢”。
其结构类似于：
```json
{
"like": [
{
"name": "Asankilp",
"advantages": "赋予了Marsho猫娘人格，使用vim与vscode为Marsho写了许多代码，使Marsho更加可爱"
},
{
"name": "神羽(snowykami)",
"advantages": "人脉很广，经常找小伙伴们开银趴，很会写后端代码"
},
...
]
}
```
## ⚙️ 可配置项
在 nonebot2 项目的`.env`文件中添加下表中的配置
#### 插件行为
| 配置项 | 类型 | 默认值 | 说明 |
| ------------------------ | ------ | ------- | ---------------- |
| MARSHOAI_USE_YAML_CONFIG | `bool` | `false` | 是否使用 YAML 配置文件格式 |
#### Marsho 使用方式
| 配置项 | 类型 | 默认值 | 说明 |
| --------------------- | ---------- | ----------- | ----------------- |
| MARSHOAI_DEFAULT_NAME | `str` | `marsho` | 调用 Marsho 默认的命令前缀 |
| MARSHOAI_ALIASES | `set[str]` | `set{"小棉"}` | 调用 Marsho 的命令别名 |
| MARSHOAI_AT | `bool` | `false` | 决定是否使用at触发 |
| MARSHOAI_MAIN_COLOUR | `str` | `FFAAAA` | 主题色，部分工具和功能可用 |
#### AI 调用
| 配置项 | 类型 | 默认值 | 说明 |
| -------------------------------- | ------- | --------------------------------------- | --------------------------------------------------------------------------------------------- |
| MARSHOAI_TOKEN | `str` | | 调用 AI API 所需的 token |
| MARSHOAI_DEFAULT_MODEL | `str` | `gpt-4o-mini` | Marsho 默认调用的模型 |
| MARSHOAI_PROMPT | `str` | 猫娘 Marsho 人设提示词 | Marsho 的基本系统提示词 **※部分模型(o1等)不支持系统提示词。** |
| MARSHOAI_ADDITIONAL_PROMPT | `str` | | Marsho 的扩展系统提示词 |
| MARSHOAI_POKE_SUFFIX | `str` | `揉了揉你的猫耳` | 对 Marsho 所连接的 OneBot 用户进行双击戳一戳时，构建的聊天内容。此配置项为空字符串时，戳一戳响应功能会被禁用。例如，默认值构建的聊天内容将为`*[昵称]揉了揉你的猫耳。` |
| MARSHOAI_AZURE_ENDPOINT | `str` | `https://models.inference.ai.azure.com` | OpenAI 标准格式 API 端点 |
| MARSHOAI_TEMPERATURE | `float` | `null` | 推理生成多样性（温度）参数 |
| MARSHOAI_TOP_P | `float` | `null` | 推理核采样参数 |
| MARSHOAI_MAX_TOKENS | `int` | `null` | 最大生成 token 数 |
| MARSHOAI_ADDITIONAL_IMAGE_MODELS | `list` | `[]` | 额外添加的支持图片的模型列表，例如`hunyuan-vision` |
#### 功能开关
| 配置项 | 类型 | 默认值 | 说明 |
| --------------------------------- | ------ | ------ | -------------------------- |
| MARSHOAI_ENABLE_SUPPORT_IMAGE_TIP | `bool` | `true` | 启用后用户发送带图请求时若模型不支持图片，则提示用户 |
| MARSHOAI_ENABLE_NICKNAME_TIP | `bool` | `true` | 启用后用户未设置昵称时提示用户设置 |
| MARSHOAI_ENABLE_PRAISES | `bool` | `true` | 是否启用夸赞名单功能 |
| MARSHOAI_ENABLE_TOOLS | `bool` | `true` | 是否启用小棉工具 |
| MARSHOAI_LOAD_BUILTIN_TOOLS | `bool` | `true` | 是否加载内置工具包 |
| MARSHOAI_TOOLSET_DIR | `list` | `[]` | 外部工具集路径列表 |
| MARSHOAI_DISABLED_TOOLKITS | `list` | `[]` | 禁用的工具包包名列表 |
| MARSHOAI_ENABLE_RICHTEXT_PARSE | `bool` | `true` | 是否启用自动解析消息（若包含图片链接则发送图片、若包含LaTeX公式则发送公式图） |
| MARSHOAI_SINGLE_LATEX_PARSE | `bool` | `false` | 单行公式是否渲染（当消息富文本解析启用时可用）（如果单行也渲……只能说不好看） |
## ❤ 鸣谢&版权说明
本项目使用了以下项目的代码：
- [nonebot-plugin-latex](https://github.com/EillesWan/nonebot-plugin-latex)
"Marsho" logo 由 [@Asankilp](https://github.com/Asankilp)
绘制，基于 [CC BY-NC-SA 4.0](http://creativecommons.org/licenses/by-nc-sa/4.0/) 许可下提供。
"nonebot-plugin-marshoai" 基于 [MIT](./LICENSE-MIT) 许可下提供。
部分指定的代码基于 [Mulan PSL v2](./LICENSE-MULAN) 许可下提供。
## 开发
- 请阅读[开发规范](./README_DEV.md)
## 🕊️ TODO
- [x] [Melobot](https://github.com/Meloland/melobot) 实现
- [x] 对聊天发起者的认知（认出是谁在问 Marsho）（初步实现）
- [ ] 自定义 API 接入点的适配（不局限于GitHub Models）
- [ ] 上下文通过数据库持久化存储

13
nonebot_plugin_marshoai/plugins/weather_demo.py Normal file
View File

@ -0,0 +1,13 @@
from nonebot_plugin_marshoai.plugin import PluginMetadata, String, on_function_call
metadata = PluginMetadata(
name="天气查询", author="MarshoAI", description="一个简单的查询天气的插件"
)
@on_function_call(description="可以用于查询天气").params(
location=String(description="地点")
)
async def weather(location: str) -> str:
# 这里可以调用天气API查询天气，这里只是一个简单的示例
return f"{location}的天气是晴天, 温度是25°C"