{"_id":"@opentiny/next-remoter","_rev":"73-fd5f3c857d8d62ea1d7efd0062b6642e","name":"@opentiny/next-remoter","dist-tags":{"beta":"0.0.10-beta.7","alpha":"0.3.3-alpha.1","latest":"0.4.11"},"versions":{"0.0.1-alpha.0":{"name":"@opentiny/next-remoter","version":"0.0.1-alpha.0","_id":"@opentiny/next-remoter@0.0.1-alpha.0","maintainers":[{"name":"opentiny","email":"opentiny@sina.com"}],"dist":{"shasum":"1953372ac8891f963aae1c94fd4dc68234b37414","tarball":"https://registry.npmjs.org/@opentiny/next-remoter/-/next-remoter-0.0.1-alpha.0.tgz","fileCount":5,"integrity":"sha512-4XLfHTeXy9VFKUi6bCgjFc6S1lBuqx6nFeX61XxOrWEx6oW3mhn9G0gIejagtBbew56nXmGgC5EAdkmqbxUVFA==","signatures":[{"sig":"MEQCIHwQ7ItNaSs854WQXkkkuXm5vqoiZGvJ/0Wx0XMnMhYEAiA4gzROjj9KSJRGvqgwzqP3wYPVMi8y2qSeieBfNqrgoA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":8632704},"type":"module","gitHead":"7d8c2ead8df9c05cdb27baacdf6b8b22bc60d273","scripts":{"dev":"vite","build":"vite build","preview":"vite preview"},"_npmUser":{"name":"opentiny","email":"opentiny@sina.com"},"_npmVersion":"10.9.2","description":"This template should help get you started developing with Vue 3 and TypeScript in Vite. The template uses Vue 3 `\n```\n\n### 完整使用示例\n\n```vue\n\n\n\n```\n\n## 📖 使用场景\n\n### 场景一：创建 WebMCP 连接\n\n```typescript\nimport { WebMcpClient, WebMcpServer, createMessageChannelPairTransport } from '@opentiny/next-sdk'\n\n// 1. 创建消息通道\nconst [serverTransport, clientTransport] = createMessageChannelPairTransport()\n\n// 2. 创建并连接 MCP 服务端\nconst server = new WebMcpServer({ name: 'demo-server', version: '1.0.0' })\nawait server.connect(serverTransport)\n\n// 3. 创建并连接 MCP 客户端\nconst client = new WebMcpClient({ name: 'demo-client', version: '1.0.0' })\nawait client.connect(clientTransport)\n\n// 4. 连接到远程 MCP 服务\nconst { sessionId } = await client.connect({\n url: 'https://agent.opentiny.design/api/v1/webmcp-trial/mcp',\n agent: true\n})\n```\n\n### 场景二：创建页面浮动遥控器\n\n```typescript\nimport { createRemoter } from '@opentiny/next-sdk'\n\n// 创建页面右下角的浮动遥控器\ncreateRemoter({\n sessionId,\n qrCodeUrl: 'https://ai.opentiny.design/next-remoter',\n onShowAIChat: () => {\n showAiChat.value = true\n }\n})\n```\n\n## ⚙️ 组件属性\n\n### 基础属性\n\n| 属性 | 类型 | 必填 | 默认值 | 说明 |\n|------|------|------|--------|------|\n| `v-model:show` | `boolean` | 是 | - | 双向绑定是否显示对话框 |\n| `sessionId` | `string` | 是 | - | 会话 ID |\n| `title` | `string` | 否 | - | 对话框左上角标题 |\n| `v-model:fullscreen` | `boolean` | 否 | `false` | 双向绑定是否全屏 |\n| `agentRoot` | `string` | 否 | - | 后端代理地址 |\n| `locale` | `'zh-CN' \\| 'en-US'` | 否 | `'zh-CN'` | 国际化语言 |\n| `mode` | `'remoter' \\| 'chat-dialog'` | 否 | `'chat-dialog'` | 展示模式 |\n| `systemPrompt` | `string` | 否 | - | 系统提示词 |\n| `llmConfig` | `object` | 否 | - | 大语言模型配置 |\n| `llmConfigs` | `array` | 否 | - | 多模型配置数组 |\n| `v-model:selectedModelId` | `string` | 否 | - | 当前选中的模型 ID |\n| `customMarketMcpServers` | `array` | 否 | - | 自定义 MCP 市场服务列表 |\n| `skills` | `array` | 否 | - | 技能配置数组 |\n| `inBrowserExt` | `boolean` | 否 | `false` | 是否运行在浏览器扩展中 |\n| `genUiAble` | `boolean` | 否 | `false` | 是否支持生成式 UI |\n| `genUiComponents` | `object` | 否 | - | 生成式 UI 组件 |\n\n### LLM 配置（llmConfig）\n\nTinyRemoter 组件支持自定义大语言模型配置，统一通过 `llmConfig` 传入：\n\n#### 方式一：使用 providerType 配置\n\n```typescript\nconst llmConfig = {\n apiKey: 'your-api-key',\n baseURL: 'https://api.openai.com/v1',\n providerType: 'openai', // 支持 'openai' | 'deepseek'\n model: 'gpt-4o',\n maxSteps: 10\n}\n```\n\n#### 方式二：使用自定义 Provider 实例\n\n```typescript\nimport { createOpenAI } from '@ai-sdk/openai'\n\nconst llmConfig = {\n llm: createOpenAI({\n apiKey: process.env.OPENAI_API_KEY,\n baseURL: 'https://api.openai.com/v1'\n }),\n model: 'gpt-4o'\n}\n```\n\n#### 支持的 LLM 提供商\n\n- ✅ OpenAI (`providerType: 'openai'`)\n- ✅ DeepSeek (`providerType: 'deepseek'`)\n- ✅ Anthropic Claude（通过自定义 Provider）\n- ✅ 其他 ai-sdk 兼容的提供商\n\n### 插槽\n\n| 插槽名 | 说明 |\n|--------|------|\n| `#welcome` | 无对话消息时展示的欢迎界面，可自定义标题、图标、预设提示词等 |\n| `#suggestions` | 输入框上方的提示建议区域 |\n| `#operations` | 容器头部右侧的操作区域（新建会话、历史会话等） |\n| `#header-actions` | MCP 插件市场头部的操作区域 |\n\n### 导出方法和属性\n\n```typescript\ndefineExpose({\n agent, // 大模型代理实例\n welcomeIcon, // 欢迎图标\n messages, // 对话消息列表\n messageState, // 对话消息状态\n roles, // 对话角色配置\n inputMessage, // 输入框文本\n senderRef, // 输入框组件实例\n abortRequest, // 取消发送函数\n sendMessage, // 发送消息函数\n loadMcpServerToPlugin, // 加载 MCP 服务到插件\n handleClientDisconnected, // 处理客户端断开\n addMessage // 添加消息函数\n})\n```\n\n## 💡 使用示例\n\n### 示例 1：使用 OpenAI\n\n```vue\n\n\n\n```\n\n### 示例 2：使用 DeepSeek\n\n```vue\n\n\n\n```\n\n### 示例 3：使用 Anthropic Claude\n\n```vue\n\n\n\n```\n\n### 示例 4：多模型切换\n\n```vue\n\n\n\n```\n\n### 示例 5：配置技能列表\n\n```vue\n\n\n\n```\n\n### 示例 6：自定义插槽\n\n```vue\n\n\n\n\n\n```\n\n## 🔌 自定义 MCP 插件\n\n`TinyRemoter` 通过 `customMarketMcpServers` 属性支持自定义 MCP 插件。传入的插件会与组件内置的 `DEFAULT_SERVERS` 合并，显示在插件市场中。\n\n### 插件配置说明\n\n```typescript\ninterface PluginInfo {\n id: string // 插件唯一标识（最终会拼成 plugin-${id}）\n name: string // 插件名称\n description: string // 插件描述\n icon?: string // 插件图标 URL\n url: string // MCP 服务器地址\n type: 'sse' | 'StreamableHTTP' // 协议类型\n enabled: boolean // 是否已启用\n addState: 'idle' | 'adding' | 'added' | 'error' // 添加状态\n tools: any[] // 工具列表\n}\n```\n\n### 使用示例\n\n```vue\n\n\n\n```\n\n### 字段说明\n\n- **id**：插件唯一标识，需保持全局唯一性\n- **type**：需与后端 MCP 服务器协议类型保持一致（`sse` 或 `StreamableHTTP`）\n- **enabled**：标记插件是否已启用，用于 UI 状态显示\n- **addState**：插件添加状态，驱动 UI 按钮和进度显示\n - `idle`：未添加\n - `adding`：添加中\n - `added`：已添加\n - `error`：添加失败\n- **tools**：MCP 服务提供的工具列表，连接成功后自动填充\n\n### 在浏览器扩展中使用\n\n在浏览器扩展场景中，可以通过配置文件自动聚合自定义插件：\n\n```typescript\n// packages/next-wxt/entrypoints/sidepanel/useCustomMarketMcpServers.ts\nimport { customServers } from './meta'\n\nconst customMarketMcpServers = useCustomMarketMcpServers(customServers)\n```\n\n## 🛠️ 参与开发\n\n### 环境要求\n\n- **Node.js** >= 18\n- **pnpm** >= 8\n- **Vue** 3.x\n\n### 开发流程\n\n#### 1. 克隆项目\n\n```bash\ngit clone https://github.com/opentiny/next-sdk.git\ncd next-sdk\n```\n\n#### 2. 安装依赖\n\n```bash\npnpm install\n```\n\n#### 3. 开发模式\n\n```bash\n# 进入 next-remoter 包目录\ncd packages/next-remoter\n\n# 启动开发服务器\npnpm dev\n\n# 浏览器访问 http://localhost:5173\n```\n\n#### 4. 构建项目\n\n```bash\n# 构建生产版本\npnpm build\n\n# 构建运行时版本\npnpm build:runtime\n\n# 构建站点版本\npnpm build:site\n```\n\n### 项目结构详解\n\n```\npackages/next-remoter/\n├── src/\n│ ├── components/ # 组件目录\n│ │ ├── TinyRobotChat.vue # 核心对话组件（689 行）\n│ │ └── QrCodeScan.vue # 二维码扫描组件\n│ ├── composable/ # 组合式函数\n│ │ └── usePlugin.ts # 插件管理逻辑（418 行）\n│ ├── index.ts # 组件导出入口\n│ └── App.vue # 独立部署页面\n├── vite.config.ts # Vite 配置\n├── vite.runtime.config.ts # 运行时构建配置\n├── vite.remoter.config.ts # Remoter 构建配置\n├── package.json # 包配置\n└── README.md # 本文档\n```\n\n### 核心文件说明\n\n#### TinyRobotChat.vue\n\n- 核心对话组件实现\n- 包含消息展示、输入处理、工具调用等核心功能\n- 支持插槽自定义和主题配置\n\n#### usePlugin.ts\n\n- MCP 插件管理的核心逻辑\n- 处理插件的添加、删除、启用/禁用\n- 管理工具列表和调用\n\n#### index.ts\n\n- 导出 `TinyRemoter` 组件\n- 作为 npm 包的入口文件\n\n#### App.vue\n\n- 可独立部署的扫码访问页面\n- 用于移动端或独立部署场景\n\n### 构建脚本说明\n\n```json\n{\n \"scripts\": {\n \"dev\": \"vite\", // 开发服务器\n \"build\": \"vite build\", // 构建 npm 包\n \"build:runtime\": \"vite build --config vite.runtime.config.ts\", // 构建运行时\n \"build:site\": \"vite build --config vite.remoter.config.ts\", // 构建站点\n \"build:visualizer\": \"vite build --config vite.remoter.config.ts --mode visualizer\", // 构建分析\n \"preview\": \"vite preview\" // 预览构建结果\n }\n}\n```\n\n### 发布流程\n\n```bash\n# 1. 更新版本号\n# 编辑 packages/next-remoter/package.json 中的 version 字段\n\n# 2. 安装依赖（如果还没安装）\npnpm install\n\n# 3. 构建项目\npnpm -F @opentiny/next-remoter build\n\n# 4. 进入包目录\ncd packages/next-remoter\n\n# 5. 发布到 npm（需要 npm 登录）\nnpm publish\n```\n\n### 调试技巧\n\n#### 1. 使用开发工具\n\n```bash\n# 启动开发服务器，支持热重载\npnpm dev\n```\n\n#### 2. 查看构建产物\n\n```bash\n# 使用 visualizer 模式查看打包分析\npnpm build:visualizer\n```\n\n#### 3. 本地测试 npm 包\n\n```bash\n# 在 next-remoter 目录下创建本地链接\npnpm link\n\n# 在测试项目中使用\ncd /path/to/test-project\npnpm link @opentiny/next-remoter\n```\n\n### 贡献指南\n\n我们欢迎所有形式的贡献！以下是参与贡献的方式：\n\n#### 报告问题\n\n- 在 [GitHub Issues](https://github.com/opentiny/next-sdk/issues) 提交 Bug 报告\n- 提供详细的复现步骤和环境信息\n\n#### 提交代码\n\n1. Fork 项目到你的 GitHub 账号\n2. 创建特性分支：`git checkout -b feature/amazing-feature`\n3. 提交改动：`git commit -m 'Add some amazing feature'`\n4. 推送到分支：`git push origin feature/amazing-feature`\n5. 提交 Pull Request\n\n#### 代码规范\n\n- 遵循 Vue3 组合式 API 最佳实践\n- 使用 TypeScript 编写类型安全的代码\n- 添加必要的注释和文档\n- 确保代码通过 ESLint 检查\n\n## 📚 文档和资源\n\n- [官方文档](https://docs.opentiny.design/next-sdk/guide/tiny-robot-remoter.html)\n- [GitHub 仓库](https://github.com/opentiny/next-sdk)\n- [问题反馈](https://github.com/opentiny/next-sdk/issues)\n- [OpenTiny 官网](https://opentiny.design)\n\n## ❓ 常见问题\n\n### 1. 如何获取 sessionId？\n\n```typescript\nimport { WebMcpClient } from '@opentiny/next-sdk'\n\nconst client = new WebMcpClient({ name: 'my-client', version: '1.0.0' })\nconst { sessionId } = await client.connect({\n url: 'https://your-mcp-server.com/mcp',\n agent: true\n})\n```\n\n### 2. 如何切换大语言模型？\n\n使用 `llmConfigs` 属性配置多个模型，通过 `v-model:selectedModelId` 切换：\n\n```vue\n\n```\n\n### 3. 如何自定义欢迎界面？\n\n使用 `#welcome` 插槽：\n\n```vue\n\n \n\n```\n\n### 4. 如何调用组件方法？\n\n通过 ref 引用组件实例：\n\n```vue\n\n```\n\n## 📄 许可证\n\nMIT\n\n## 🙏 致谢\n\n感谢所有为本项目做出贡献的开发者！\n\n---\n\n如有任何问题或建议，欢迎提交 [Issue](https://github.com/opentiny/next-sdk/issues) 或 [Pull Request](https://github.com/opentiny/next-sdk/pulls)。\n","readmeFilename":"README.md"}