From bfc70505d5e8cfb5084443c45eac6e3edc5120d9 Mon Sep 17 00:00:00 2001 From: coso Date: Tue, 30 Dec 2025 01:31:42 +0800 Subject: [PATCH] =?UTF-8?q?feat:=20=E6=8F=92=E4=BB=B6=E4=B8=AD=E5=BF=83?= =?UTF-8?q?=E8=BF=81=E7=A7=BB=E5=88=B0=E5=AF=BC=E8=88=AA=E6=A0=8F=20+=20?= =?UTF-8?q?=E6=8F=92=E4=BB=B6=E5=BC=80=E5=8F=91=E8=A7=84=E8=8C=83=E6=96=87?= =?UTF-8?q?=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 添加插件中心到导航栏 - 从设置页扩展管理移除 Plugins tab - 添加插件开发指南文档 (docs/content/06.development/5.plugin-development.md) - 添加插件使用说明文档 (docs/content/02.user-guide/13.plugins.md) --- docs/content/02.user-guide/13.plugins.md | 112 ++++++++ .../06.development/5.plugin-development.md | 245 ++++++++++++++++++ src/App.tsx | 4 + src/components/Sidebar.tsx | 3 + src/components/plugins/PluginsPage.tsx | 23 ++ src/components/plugins/README.md | 1 + .../settings/ExtensionsSettings.tsx | 7 +- 7 files changed, 390 insertions(+), 5 deletions(-) create mode 100644 docs/content/02.user-guide/13.plugins.md create mode 100644 docs/content/06.development/5.plugin-development.md create mode 100644 src/components/plugins/PluginsPage.tsx diff --git a/docs/content/02.user-guide/13.plugins.md b/docs/content/02.user-guide/13.plugins.md new file mode 100644 index 000000000..e99879771 --- /dev/null +++ b/docs/content/02.user-guide/13.plugins.md @@ -0,0 +1,112 @@ +# 插件中心 + +ProxyCast 支持通过插件扩展功能。插件中心提供插件的安装、管理和配置。 + +## 访问插件中心 + +点击左侧导航栏的「插件中心」进入插件管理页面。 + +## 功能概览 + +### 推荐插件 + +插件中心会显示推荐的插件列表，点击「一键安装」即可快速安装。 + +### 已安装插件 + +显示所有已安装的插件，包括： +- 插件名称和版本 +- 安装来源（本地/URL/GitHub） +- 启用/禁用状态 +- 卸载按钮 + +### 已加载插件 + +显示当前运行中的插件状态： +- 执行次数 +- 错误次数 +- 最后执行时间 + +## 安装插件 + +### 方式一：推荐插件一键安装 + +1. 在「推荐插件」区域找到想要的插件 +2. 点击「一键安装」 +3. 等待下载和安装完成 + +### 方式二：从 URL 安装 + +1. 点击「安装插件」按钮 +2. 输入插件 ZIP 包的下载 URL +3. 点击「安装」 + +支持的 URL 格式： +- GitHub Release: `https://github.com/org/repo/releases/latest/download/plugin.zip` +- 直接下载链接: `https://example.com/plugin.zip` + +### 方式三：从本地文件安装 + +1. 点击「安装插件」按钮 +2. 点击「选择文件」 +3. 选择本地的 `.zip` 文件 +4. 点击「安装」 + +## 使用插件 + +安装完成后，插件会根据类型出现在不同位置： + +### 工具类插件 + +工具类插件会出现在「工具箱」页面： + +1. 点击左侧导航栏的「工具」 +2. 在工具列表中找到已安装的插件 +3. 点击「打开工具」使用 + +### 其他类型插件 + +- **Hook 插件**: 自动在请求/响应时执行 +- **侧边栏插件**: 出现在主侧边栏（规划中） + +## 管理插件 + +### 启用/禁用 + +在已加载插件列表中，点击电源图标可以启用或禁用插件。 + +### 卸载 + +1. 在「已安装插件包」列表中找到要卸载的插件 +2. 点击红色的删除按钮 +3. 确认卸载 + +卸载会删除插件文件和配置，但不会删除插件产生的数据。 + +## 二进制组件 + +部分功能需要安装额外的二进制组件： + +- **aster-server**: AI Agent 框架，提供 Agent 对话能力 + +在「二进制组件」区域可以查看和管理这些组件。 + +## 常见问题 + +### 插件安装失败 + +1. 检查网络连接 +2. 确认 URL 正确且可访问 +3. 检查 ZIP 包格式是否正确 + +### 插件无法加载 + +1. 检查 ProxyCast 版本是否满足插件要求 +2. 查看日志了解详细错误信息 +3. 尝试重新安装插件 + +### 二进制插件权限问题 + +部分二进制插件需要管理员权限： +- **Windows**: 以管理员身份运行 ProxyCast +- **macOS/Linux**: 插件会提示需要的权限 diff --git a/docs/content/06.development/5.plugin-development.md b/docs/content/06.development/5.plugin-development.md new file mode 100644 index 000000000..0539b4375 --- /dev/null +++ b/docs/content/06.development/5.plugin-development.md @@ -0,0 +1,245 @@ +# 插件开发指南 + +本文档描述 ProxyCast 插件系统的规范和开发指南，为插件市场做准备。 + +## 插件类型 + +ProxyCast 支持两种类型的插件： + +### 1. 脚本插件 (Script Plugin) + +纯 JavaScript/TypeScript 插件，通过 Hook 机制扩展功能。 + +```json +{ + "plugin_type": "script", + "entry": "main.js", + "hooks": ["on_request", "on_response"] +} +``` + +### 2. 二进制插件 (Binary Plugin) + +独立的可执行文件，通过 CLI 接口与 ProxyCast 通信。适合需要系统级操作的工具。 + +```json +{ + "plugin_type": "binary", + "entry": "my-tool-cli", + "binary": { + "binary_name": "my-tool-cli", + "github_owner": "your-org", + "github_repo": "your-repo", + "platform_binaries": { + "macos-arm64": "my-tool-aarch64-apple-darwin", + "macos-x64": "my-tool-x86_64-apple-darwin", + "linux-x64": "my-tool-x86_64-unknown-linux-gnu", + "linux-arm64": "my-tool-aarch64-unknown-linux-gnu", + "windows-x64": "my-tool-x86_64-pc-windows-msvc.exe" + }, + "checksum_file": "checksums.txt" + } +} +``` + +## 插件包结构 + +插件以 ZIP 包形式分发，包含以下文件： + +``` +my-plugin.zip +├── plugin.json # 插件元数据（必需） +└── config.json # 默认配置（可选） +``` + +### plugin.json 规范 + +```json +{ + "name": "my-plugin", + "version": "1.0.0", + "description": "插件描述", + "author": "作者名", + "homepage": "https://github.com/org/repo", + "license": "MIT", + "plugin_type": "binary", + "entry": "my-tool-cli", + "hooks": [], + "min_proxycast_version": "1.0.0", + "binary": { ... }, + "ui": { + "surfaces": ["tools"], + "icon": "Cpu", + "title": "我的工具", + "default_width": 800, + "default_height": 600 + } +} +``` + +#### 字段说明 + +| 字段 | 类型 | 必需 | 说明 | +|------|------|------|------| +| `name` | string | ✅ | 插件唯一标识符，小写字母和连字符 | +| `version` | string | ✅ | 语义化版本号 (semver) | +| `description` | string | ✅ | 插件描述 | +| `author` | string | ❌ | 作者名称 | +| `homepage` | string | ❌ | 项目主页 URL | +| `license` | string | ❌ | 开源许可证 | +| `plugin_type` | string | ✅ | `script` 或 `binary` | +| `entry` | string | ✅ | 入口文件/二进制名称 | +| `hooks` | array | ❌ | 注册的 Hook 列表 | +| `min_proxycast_version` | string | ❌ | 最低 ProxyCast 版本要求 | +| `binary` | object | ❌ | 二进制插件配置 | +| `ui` | object | ❌ | UI 配置 | + +## UI 展示位置 (Surfaces) + +插件可以在以下位置显示 UI： + +| Surface | 说明 | 入口位置 | +|---------|------|----------| +| `tools` | 工具箱 | 导航栏「工具」页面 | +| `sidebar` | 侧边栏 | 主侧边栏（规划中） | +| `settings` | 设置页 | 设置页扩展区域（规划中） | + +### 示例：工具类插件 + +```json +{ + "ui": { + "surfaces": ["tools"], + "icon": "Cpu", + "title": "机器码管理工具" + } +} +``` + +安装后，插件会出现在「工具箱」页面，用户点击即可打开。 + +## 图标规范 + +使用 [Lucide Icons](https://lucide.dev/icons/) 图标名称： + +```json +{ + "ui": { + "icon": "Cpu" + } +} +``` + +常用图标： +- `Cpu` - 系统/硬件工具 +- `Globe` - 网络工具 +- `Database` - 数据工具 +- `Shield` - 安全工具 +- `Wrench` - 通用工具 +- `Terminal` - 命令行工具 + +## 二进制插件 CLI 接口规范 + +二进制插件通过 CLI 与 ProxyCast 通信，必须遵循以下规范： + +### 输出格式 + +所有输出必须是 JSON 格式： + +```bash +# 成功 +$ my-tool-cli get +{"machine_id": "550e8400-e29b-41d4-a716-446655440000"} + +# 错误 +$ my-tool-cli invalid-command +{"error": "未知命令: invalid-command"} +``` + +### 退出码 + +- `0` - 成功 +- `1` - 错误 + +### 命令结构 + +```bash +my-tool-cli [arguments] +``` + +建议实现 `help` 命令： + +```bash +$ my-tool-cli help +MachineIdTool CLI v1.0.0 +用法: my-tool-cli <命令> [参数] + +命令: + get 获取当前值 + set 设置新值 + help 显示帮助 +``` + +## 插件安装流程 + +1. **下载插件包** - 从 URL 或本地文件获取 ZIP +2. **解压验证** - 解压并验证 plugin.json +3. **下载二进制** - 如果是二进制插件，根据当前平台下载对应二进制 +4. **校验完整性** - 验证 checksum +5. **注册插件** - 将插件信息写入数据库 +6. **加载插件** - 启用插件功能 + +## 插件发布 + +### GitHub Release 发布 + +推荐通过 GitHub Release 发布插件： + +1. 创建 `plugin/` 目录，包含 `plugin.json` 和 `config.json` +2. 在 GitHub Actions 中打包 ZIP +3. 上传到 Release Assets + +```yaml +- name: Package plugin + run: | + mkdir -p plugin-package + cp plugin/plugin.json plugin-package/ + cp plugin/config.json plugin-package/ + cd plugin-package + zip -j ../release/my-plugin.zip plugin.json config.json +``` + +### 插件市场（规划中） + +未来将支持： +- 插件市场浏览和搜索 +- 一键安装 +- 自动更新 +- 评分和评论 + +## 推荐插件 + +ProxyCast 内置推荐插件列表，在「工具箱」和「插件中心」显示未安装的推荐插件。 + +要将插件添加到推荐列表，请提交 PR 修改： +- `src/components/tools/ToolsPage.tsx` - `recommendedPlugins` +- `src/components/plugins/PluginManager.tsx` - `recommendedPlugins` + +## 示例插件 + +参考 [MachineIdTool](https://github.com/aiclientproxy/MachineIdTool) 作为二进制插件的完整示例。 + +## 开发调试 + +### 本地安装测试 + +1. 打包插件 ZIP +2. 在「插件中心」点击「安装插件」 +3. 选择本地 ZIP 文件安装 + +### 日志调试 + +插件执行日志保存在： +- macOS: `~/Library/Application Support/proxycast/logs/` +- Windows: `%APPDATA%/proxycast/logs/` +- Linux: `~/.local/share/proxycast/logs/` diff --git a/src/App.tsx b/src/App.tsx index a8129fa08..904641f08 100644 --- a/src/App.tsx +++ b/src/App.tsx @@ -18,6 +18,7 @@ import { ToolsPage } from "./components/tools/ToolsPage"; import { BrowserInterceptorTool } from "./components/tools/browser-interceptor/BrowserInterceptorTool"; import { AgentChatPage } from "./components/agent"; import { PluginUIRenderer } from "./components/plugins/PluginUIRenderer"; +import { PluginsPage } from "./components/plugins/PluginsPage"; import { Toaster } from "./components/ui/sonner"; import { flowEventManager } from "./lib/flowEventManager"; @@ -37,6 +38,7 @@ type Page = | "flow-monitor" | "agent" | "tools" + | "plugins" | "browser-interceptor" | "settings" | `plugin:${string}`; @@ -90,6 +92,8 @@ function App() { return ; case "tools": return ; + case "plugins": + return ; case "browser-interceptor": return ; case "settings": diff --git a/src/components/Sidebar.tsx b/src/components/Sidebar.tsx index 21a00bc6d..d97961eba 100644 --- a/src/components/Sidebar.tsx +++ b/src/components/Sidebar.tsx @@ -6,6 +6,7 @@ import { Activity, Wrench, Bot, + Puzzle, } from "lucide-react"; import { cn } from "@/lib/utils"; @@ -25,6 +26,7 @@ type Page = | "flow-monitor" | "agent" | "tools" + | "plugins" | "browser-interceptor" | "settings" | `plugin:${string}`; @@ -41,6 +43,7 @@ const navItems = [ { id: "flow-monitor" as Page, label: "Flow Monitor", icon: Activity }, { id: "agent" as Page, label: "AI Agent", icon: Bot }, { id: "tools" as Page, label: "工具", icon: Wrench }, + { id: "plugins" as Page, label: "插件中心", icon: Puzzle }, { id: "settings" as Page, label: "设置", icon: Settings }, ]; diff --git a/src/components/plugins/PluginsPage.tsx b/src/components/plugins/PluginsPage.tsx new file mode 100644 index 000000000..bf623aea7 --- /dev/null +++ b/src/components/plugins/PluginsPage.tsx @@ -0,0 +1,23 @@ +/** + * 插件中心页面 + * + * 独立的插件管理页面，从设置页迁移到导航栏 + * 提供插件安装、卸载、启用/禁用等功能 + * + * @module components/plugins/PluginsPage + */ + +import { PluginManager } from "./PluginManager"; + +export function PluginsPage() { + return ( +
+
+

插件中心

+

管理和配置 ProxyCast 插件

+
+ + +
+ ); +} diff --git a/src/components/plugins/README.md b/src/components/plugins/README.md index 58bc74855..a748926a0 100644 --- a/src/components/plugins/README.md +++ b/src/components/plugins/README.md @@ -6,6 +6,7 @@ | 文件 | 说明 | |------|------| +| `PluginsPage.tsx` | 插件中心页面，独立的导航栏入口 | | `PluginManager.tsx` | 插件管理主组件，显示插件列表和状态 | | `PluginInstallDialog.tsx` | 插件安装对话框，支持本地文件和 URL 安装 | | `PluginUninstallDialog.tsx` | 插件卸载确认对话框 | diff --git a/src/components/settings/ExtensionsSettings.tsx b/src/components/settings/ExtensionsSettings.tsx index f38306dd8..79eccac6d 100644 --- a/src/components/settings/ExtensionsSettings.tsx +++ b/src/components/settings/ExtensionsSettings.tsx @@ -1,18 +1,16 @@ import { useState } from "react"; -import { Plug, MessageSquare, Boxes, Puzzle } from "lucide-react"; +import { Plug, MessageSquare, Boxes } from "lucide-react"; import { cn } from "@/lib/utils"; import { McpPage } from "../mcp/McpPage"; import { PromptsPage } from "../prompts/PromptsPage"; import { SkillsPage } from "../skills/SkillsPage"; -import { PluginManager } from "../plugins/PluginManager"; -type Tab = "mcp" | "prompts" | "skills" | "plugins"; +type Tab = "mcp" | "prompts" | "skills"; const tabs = [ { id: "mcp" as Tab, label: "MCP", icon: Plug }, { id: "prompts" as Tab, label: "Prompts", icon: MessageSquare }, { id: "skills" as Tab, label: "Skills", icon: Boxes }, - { id: "plugins" as Tab, label: "Plugins", icon: Puzzle }, ]; export function ExtensionsSettings() { @@ -59,7 +57,6 @@ export function ExtensionsSettings() { {activeTab === "mcp" && } {activeTab === "prompts" && } {activeTab === "skills" && } - {activeTab === "plugins" && } );