mirror of
https://github.com/LiteyukiStudio/nonebot-plugin-marshoai.git
synced 2025-08-03 03:30:20 +00:00
Deploying to docs from @ LiteyukiStudio/nonebot-plugin-marshoai@c54b0cda3c 🚀
This commit is contained in:
Asankilp
29
assets/dev_extension.md.DfIbM0Ke.js
Normal file
29
assets/dev_extension.md.DfIbM0Ke.js
Normal file
@ -0,0 +1,29 @@
|
||||
import{_ as i,c as a,o as n,ae as t}from"./chunks/framework.CTVYQtO4.js";const E=JSON.parse('{"title":"扩展开发","description":"","frontmatter":{"order":2},"headers":[],"relativePath":"dev/extension.md","filePath":"zh/dev/extension.md","lastUpdated":1735455670000}'),h={name:"dev/extension.md"};function l(p,s,k,e,d,r){return n(),a("div",null,s[0]||(s[0]=[t(`<h1 id="扩展开发" tabindex="-1">扩展开发 <a class="header-anchor" href="#扩展开发" aria-label="Permalink to "扩展开发""></a></h1><h2 id="说明" tabindex="-1">说明 <a class="header-anchor" href="#说明" aria-label="Permalink to "说明""></a></h2><p>扩展分为两类，一类为插件，一类为工具。</p><ul><li>插件</li><li>工具(由于开发的不便利性，已经停止维护，未来可能会放弃支持，如有需求请看README中的内容，我们不推荐再使用此功能)</li></ul><p><strong><code>v1.0.0</code>之前的版本不支持小棉插件。</strong></p><h2 id="插件" tabindex="-1">插件 <a class="header-anchor" href="#插件" aria-label="Permalink to "插件""></a></h2><p>为什么要有插件呢，插件可以编写function call供AI调用，语言大模型本身不具备一些信息获取能力，可以使用该功能进行扩展。</p><p>可以借助这个功能实现获取天气、获取股票信息、获取新闻等等，然后将这些信息传递给AI，AI可以根据这些信息进行正确的整合与回答。</p><p>插件很简单，一个Python文件，一个Python包都可以是插件，插件组成也很简单：</p><ul><li>元数据：包含插件的信息，如名称、版本、作者等</li><li>function call：供AI调用的函数</li></ul><div class="tip custom-block"><p class="custom-block-title">TIP</p><p>如果你编写过NoneBot插件，那么你会发现插件的编写方式和NoneBot插件的编写方式几乎一样。</p></div><h2 id="编写第一个插件" tabindex="-1">编写第一个插件 <a class="header-anchor" href="#编写第一个插件" aria-label="Permalink to "编写第一个插件""></a></h2><p>我们编写一个用于查询天气的插件，首先创建<code>weather.py</code>文件，然后编写如下内容：</p><div class="language-python vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">python</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> nonebot_plugin_marshoai.plugin </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> PluginMetadata, on_function_call, String</span></span>
|
||||
<span class="line"></span>
|
||||
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">__marsho_meta__ </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> PluginMetadata(</span></span>
|
||||
<span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;"> name</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"天气查询"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
||||
<span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;"> author</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"MarshoAI"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
||||
<span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;"> description</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"一个简单的查询天气的插件"</span></span>
|
||||
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span></span>
|
||||
<span class="line"></span>
|
||||
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">@on_function_call</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">description</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"可以用于查询天气"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span><span style="--shiki-light:#B31D28;--shiki-light-font-style:italic;--shiki-dark:#FDAEB7;--shiki-dark-font-style:italic;">.params(</span></span>
|
||||
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> location</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">String(</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">description</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"地点"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span></span>
|
||||
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span></span>
|
||||
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">async</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> def</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> weather</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(location: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">str</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) -> </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">str</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
|
||||
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # 这里可以调用天气API查询天气，这里只是一个简单的示例</span></span>
|
||||
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> return</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> f</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">{</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">location</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">}</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">的天气是晴天, 温度是25°C"</span></span></code></pre></div><p>然后将<code>weather.py</code>文件放到<code>$LOCAL_STORE/plugins</code>目录下，重启机器人实例即可。</p><p>接下来AI会根据你的发送的提示词和<code>description</code>来决定调用函数，如<code>查询北京的天气</code>，<code>告诉我东京明天会下雨吗</code>，AI会调用<code>weather</code>函数并传递<code>location</code>参数为<code>北京</code>。</p><h2 id="插件元数据" tabindex="-1">插件元数据 <a class="header-anchor" href="#插件元数据" aria-label="Permalink to "插件元数据""></a></h2><p>元数据是一个名为<code>__marsho_meta__</code>的全局变量，它是一个<code>PluginMetadata</code>对象，至于包含什么熟悉可以查看<code>PluginMetadata</code>类的定义或IDE提示，这里不再赘述。</p><h2 id="函数调用参数" tabindex="-1">函数调用参数 <a class="header-anchor" href="#函数调用参数" aria-label="Permalink to "函数调用参数""></a></h2><p><code>on_function_call</code>装饰器用于标记一个函数为function call，<code>description</code>参数用于描述这个函数的作用，<code>params</code>方法用于定义函数的参数，<code>String</code>、<code>Integer</code>等是OpenAI API接受的参数的类型，<code>description</code>是参数的描述。这些都是给AI看的，AI会根据这些信息来调用函数。</p><div class="warning custom-block"><p class="custom-block-title">WARNING</p><p>参数名不得为<code>placeholder</code>。此参数名是Marsho内部保留的用于保证兼容性的占位参数。</p></div><div class="language-python vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">python</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">@on_function_call</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">description</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"可以用于算命"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span><span style="--shiki-light:#B31D28;--shiki-light-font-style:italic;--shiki-dark:#FDAEB7;--shiki-dark-font-style:italic;">.params(</span></span>
|
||||
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> name</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">String(</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">description</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"姓名"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">),</span></span>
|
||||
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> age</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">Integer(</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">description</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"年龄"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span></span>
|
||||
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span></span>
|
||||
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">def</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> fortune_telling</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(name: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">str</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, age: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">int</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) -> </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">str</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
|
||||
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> return</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> f</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">{</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">name</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">}</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">，你的年龄是</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">{</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">age</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">}</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">岁"</span></span></code></pre></div><h2 id="权限及规则" tabindex="-1">权限及规则 <a class="header-anchor" href="#权限及规则" aria-label="Permalink to "权限及规则""></a></h2><p>插件的调用权限和规则与NoneBot插件一样，使用Caller的permission和rule函数来设置。</p><div class="language-python vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">python</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">@on_function_call</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">description</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"在设备上执行命令"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span><span style="--shiki-light:#B31D28;--shiki-light-font-style:italic;--shiki-dark:#FDAEB7;--shiki-dark-font-style:italic;">.params(</span></span>
|
||||
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> command</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">String(</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">description</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"命令内容"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span></span>
|
||||
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">).permission(</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">SUPERUSER</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span></span>
|
||||
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">def</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> execute_command</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(command: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">str</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) -> </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">str</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
|
||||
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> return</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> eval</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(command)</span></span></code></pre></div><h2 id="依赖注入" tabindex="-1">依赖注入 <a class="header-anchor" href="#依赖注入" aria-label="Permalink to "依赖注入""></a></h2><p>function call支持NoneBot2原生的会话上下文依赖注入</p><ul><li>Event 及其子类实例</li><li>Bot 及其子类实例</li><li>Matcher 及其子类实例</li><li>T_State</li></ul><div class="language-python vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">python</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">@on_function_call</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">description</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"获取个人信息"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span></span>
|
||||
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">async</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> def</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> get_user_info</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(e: Event) -> </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">str</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
|
||||
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> return</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> f</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"用户ID: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">{</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">e.user_id</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">}</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"</span></span>
|
||||
<span class="line"></span>
|
||||
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">@on_function_call</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">description</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"获取机器人信息"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span></span>
|
||||
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">async</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> def</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> get_bot_info</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(b: Bot) -> </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">str</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
|
||||
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> return</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> f</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"机器人ID: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">{</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">b.self_id</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">}</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"</span></span></code></pre></div><h2 id="兼容性" tabindex="-1">兼容性 <a class="header-anchor" href="#兼容性" aria-label="Permalink to "兼容性""></a></h2><p>插件可以编写NoneBot或者轻雪插件的内容，可作为NoneBot插件或者轻雪插件单独发布</p><p>不过，所编写功能仅会在对应的实例上加载对应的功能，如果通过marshoai加载混合插件，那么插件中NoneBot的功能将会依附于marshoai插件， 若通过NoneBot加载包含marshoai功能的NoneBot插件，那么marshoai功能将会依附于NoneBot插件。</p><p><strong>我们建议</strong>：若插件中包含了NoneBot功能，仍然使用marshoai进行加载，这样更符合逻辑。若你想发布为NoneBot插件，请注意<code>require("nonebot_plugin_marshoai")</code>，这是老生常谈了。</p><div class="tip custom-block"><p class="custom-block-title">TIP</p><p>本质上都是动态导入和注册声明加载，运行时把这些东西塞到一起</p></div><h2 id="插件热重载" tabindex="-1">插件热重载 <a class="header-anchor" href="#插件热重载" aria-label="Permalink to "插件热重载""></a></h2><p>插件热重载是一个实验性功能，可以在不重启机器人的情况下更新插件</p><div class="warning custom-block"><p class="custom-block-title">WARNING</p><p>框架无法完全消除之前插件带来的副作用，当开发测试中效果不符合预期时请重启机器人实例</p><p>为了更好地让热重载功能正常工作，尽可能使用函数式的编程风格，以减少副作用的影响</p></div><p>将<code>MARSHOAI_DEVMODE</code>环境变量设置为<code>true</code>，然后在配置的插件目录<code>MARSHOAI_PLUGIN_DIRS</code>下开发插件，当插件发生变化时，机器人会自动变动的插件。</p><h2 id="aigc-自举" tabindex="-1">AIGC 自举 <a class="header-anchor" href="#aigc-自举" aria-label="Permalink to "AIGC 自举""></a></h2><div class="warning custom-block"><p class="custom-block-title">WARNING</p><p>该功能为实验性功能，请注意甄别AI的行为，不要让AI执行危险的操作。</p></div><p>function call为AI赋能，实现了文件io操作，AI可以调用function call来读取文档然后给自己编写代码，实现自举。</p><h2 id="其他" tabindex="-1">其他 <a class="header-anchor" href="#其他" aria-label="Permalink to "其他""></a></h2><ul><li>function call支持同步和异步函数</li><li>本文是一个引导，要查看具体功能请查阅<a href="./api/plugin/index">插件 API 文档</a></li></ul>`,43)]))}const c=i(h,[["render",l]]);export{E as __pageData,c as default};
|
||||
Reference in New Issue
Block a user