RisuAI插件开发指南从零开始构建自定义功能【免费下载链接】RisuAIMake your own story. Frontend for ai roleplaying.项目地址: https://gitcode.com/gh_mirrors/ri/RisuAIRisuAI是一款强大的AI角色扮演前端工具通过插件系统可以轻松扩展其功能。本指南将帮助你从零开始创建自己的RisuAI插件即使你没有丰富的开发经验也能快速上手并构建出实用的自定义功能。什么是RisuAI插件RisuAI插件是JavaScript扩展可以添加新功能、自定义行为并与外部服务集成。插件运行在安全的沙箱环境中保护用户数据和隐私。通过插件你可以扩展RisuAI的能力使其更好地满足个人或特定场景的需求。RisuAI主界面展示插件可以无缝集成到这样的界面中插件开发准备工作环境准备首先克隆RisuAI仓库git clone https://gitcode.com/gh_mirrors/ri/RisuAI推荐使用Visual Studio Code作为开发IDE以获得良好的TypeScript支持和代码提示。从RisuAI应用中获取插件模板打开RisuAI应用进入Plugin Settings点击/菜单选择Download plugin template插件基础结构每个插件都以元数据注释和主脚本开始//name my_awesome_plugin //display-name My Awesome Plugin //api 3.0 //arg api_key string Your API key //arg max_retries int Maximum retry attempts //link https://example.com/docs Documentation // Your plugin code here (async () { try { console.log(Plugin initialized); // 初始化代码 } catch (error) { console.log(Error: ${error.message}); } })();插件元数据详解元数据注释定义了插件的身份和配置必须放在插件脚本的最顶部。必需元数据//name- 内部插件名称必须唯一//name my_plugin发布后不建议更改可能会破坏现有安装。//api- API版本新插件使用3.0//api 3.0可选元数据//display-name- 用户友好的显示名称//display-name My Awesome Plugin//arg- 定义插件参数//arg setting_name string Description of the setting //arg max_items int Maximum number of items//link- 添加自定义链接//link https://example.com/docs Documentation //link https://example.com/support Get Support//update-url- 检查更新的URL//update-url https://raw.githubusercontent.com/username/repo/branch/plugin.js//version- 插件版本//version 1.0.0API v3.0架构iframe沙箱模型API v3.0插件在沙箱化的iframe中运行提供隔离性每个插件在自己的隔离上下文中运行安全性限制对主应用的访问防止数据泄露自定义UIiframe可以显示自定义界面结构化通信使用结构化克隆安全传递数据RisuAI插件系统架构示意图重要提示所有操作都是异步的关键v3.0中的所有API方法都返回Promises即使代码中看起来是同步的。调用API方法时务必使用await或.then()。// 错误示例 - 不会按预期工作 const character Risuai.getCharacter(); // 正确示例 - 始终使用await const character await Risuai.getCharacter(); // 另一种正确方式 - 使用.then() Risuai.getCharacter().then(character { // 使用character });核心概念访问API所有API v3.0功能都通过全局Risuai对象提供// 获取角色数据 const character await Risuai.getCharacter(); // 访问主文档 const rootDoc await Risuai.getRootDocument();Risuai对象Risuai全局对象是访问所有插件功能的入口// 版本信息 console.log(Risuai.apiVersion); // 3.0 // 日志记录 console.log(这将显示为: [Risuai Plugin: PluginName] 这...); // 容器管理 await Risuai.showContainer(fullscreen); // 显示iframe UI await Risuai.hideContainer(); // 隐藏iframe UI // DOM访问 const doc await Risuai.getRootDocument(); // 安全访问主文档开发你的第一个插件简单设置面板示例下面是一个完整的简单插件示例创建一个主题设置面板//name settings_example //display-name Settings Example //api 3.0 //arg theme string Color theme (light/dark) (async () { try { // 注册设置按钮 Risuai.registerSetting( Theme Settings, async () { const theme await Risuai.getArgument(theme); document.body.innerHTML div stylepadding: 20px; background: #2d2d2d; color: white; font-family: sans-serif; h1Theme Settings/h1 pCurrent theme: strong${theme}/strong/p button idlight-btnLight Theme/button button iddark-btnDark Theme/button button idclose-btnClose/button /div ; document.getElementById(light-btn).addEventListener(click, async () { await Risuai.setArgument(theme, light); console.log(Theme set to light); }); document.getElementById(dark-btn).addEventListener(click, async () { await Risuai.setArgument(theme, dark); console.log(Theme set to dark); }); document.getElementById(close-btn).addEventListener(click, () { Risuai.hideContainer(); }); Risuai.showContainer(fullscreen); }, https://example.com/icon_src_here.png, img ); console.log(Settings panel registered); } catch (error) { console.log(Error: ${error.message}); } })();插件安装与测试在Risuai应用中进入Plugin Settings点击Import Plugin导入你的插件脚本对于开发阶段推荐使用热重载功能进入Plugin Settings点击/菜单选择Import plugin with hot reload选择你的插件文件RisuAI插件设置界面可在此导入和管理插件数据存储插件参数使用参数获取用户可配置的设置// 在元数据中定义 //arg api_key string Your API key //arg max_retries int Maximum retry attempts // 在代码中访问记得使用async! const apiKey await Risuai.getArgument(api_key); const maxRetries await Risuai.getArgument(max_retries); // 更新值 await Risuai.setArgument(max_retries, 5);插件存储推荐pluginStorage是特定于保存文件且在设备间同步的存储// 所有操作都是异步的包装在同步存储周围 await Risuai.pluginStorage.setItem(user_preference, dark_mode); await Risuai.pluginStorage.setItem(last_sync, Date.now().toString()); const preference await Risuai.pluginStorage.getItem(user_preference); const allKeys await Risuai.pluginStorage.keys(); const count await Risuai.pluginStorage.length(); await Risuai.pluginStorage.removeItem(last_sync); await Risuai.pluginStorage.clear(); // 移除所有项目使用pluginStorage的场景希望数据在设备间同步数据特定于某个保存文件存储用户偏好或插件状态高级功能自定义UI元素向Risuai界面添加按钮和菜单项注册设置菜单项Risuai.registerSetting( My Plugin Settings, async () { // 用户点击菜单项时调用 await Risuai.showContainer(fullscreen); }, svg width24 height24.../svg, // 可选图标 html // 图标类型: html, img, 或 none );注册浮动操作按钮Risuai.registerButton({ name: Quick Action, icon: https://example.com/icon.png, // 可选图标URL iconType: img, // 图标类型: html, img, 或 none location: action // 也可以使用chat或hamburger }, async () { // 用户点击按钮时调用 const char await Risuai.getCharacter(); await console.log(Current character: ${char.name}); });文本处理添加文本处理器来修改输入或输出内容// 处理AI输出以转换markdown样式的粗体 Risuai.addRisuScriptHandler(output, async (content) { // **粗体** 转换为 strong粗体/strong content content.replace(/\*\*(.?)\*\*/g, strong$1/strong); // *斜体* 转换为 em斜体/em content content.replace(/\*(.?)\*/g, em$1/em); return content; }); // 处理用户输入以添加时间戳 Risuai.addRisuScriptHandler(input, async (content) { const timestamp new Date().toLocaleTimeString(); Risuai.pluginStorage.setItem(last_input_time, timestamp); return content; });最佳实践1. 始终使用Async/Await所有RisuaiAPI方法都是异步的 - 永远不要忘记await// 错误示例 const char Risuai.getCharacter(); console.log(char.name); // undefined或Promise // 正确示例 const char await Risuai.getCharacter(); console.log(char.name); // 正常工作!2. 使用Try-Catch包装代码始终优雅地处理错误(async () { try { const data await Risuai.getDatabase(); // 处理数据 } catch (error) { console.log(Error: ${error.message}); } })();3. 清理资源完成后移除事件监听器const listeners []; // 存储监听器ID listeners.push(await element.addEventListener(click, handler)); // 清理 for (const id of listeners) { await element.removeEventListener(click, id); }故障排除API调用返回undefined问题没有在异步方法上使用await。// 错误 const char Risuai.getCharacter(); console.log(char); // Promise或undefined // 正确 const char await Risuai.getCharacter(); console.log(char); // 实际的角色对象无法设置元素属性问题尝试设置非x-前缀的属性。// 错误 - 会抛出错误 await element.setAttribute(onclick, alert()); // 正确 - 对自定义属性使用x-前缀 await element.setAttribute(x-custom-id, my-id); // 或者使用专用方法 await element.setStyle(color, red); await element.setInnerHTML(divSafe content/div);总结通过本指南你已经了解了RisuAI插件开发的基础知识。从简单的设置面板到复杂的文本处理插件系统为你提供了无限可能来扩展RisuAI的功能。开始创建你自己的插件为RisuAI添加独特的功能提升AI角色扮演体验更多高级功能和API细节请参考完整的插件开发文档。祝你开发顺利【免费下载链接】RisuAIMake your own story. Frontend for ai roleplaying.项目地址: https://gitcode.com/gh_mirrors/ri/RisuAI创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考