mirror of
https://github.com/aiclientproxy/proxycast.git
synced 2026-09-24 23:10:56 +08:00
feat: 插件中心迁移到导航栏 + 插件开发规范文档
- 添加插件中心到导航栏 - 从设置页扩展管理移除 Plugins tab - 添加插件开发指南文档 (docs/content/06.development/5.plugin-development.md) - 添加插件使用说明文档 (docs/content/02.user-guide/13.plugins.md)
This commit is contained in:
coso
@@ -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**: 插件会提示需要的权限
|
||||
@@ -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 <command> [arguments]
|
||||
```
|
||||
|
||||
建议实现 `help` 命令：
|
||||
|
||||
```bash
|
||||
$ my-tool-cli help
|
||||
MachineIdTool CLI v1.0.0
|
||||
用法: my-tool-cli <命令> [参数]
|
||||
|
||||
命令:
|
||||
get 获取当前值
|
||||
set <value> 设置新值
|
||||
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/`
|
||||
@@ -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 <AgentChatPage />;
|
||||
case "tools":
|
||||
return <ToolsPage onNavigate={setCurrentPage} />;
|
||||
case "plugins":
|
||||
return <PluginsPage />;
|
||||
case "browser-interceptor":
|
||||
return <BrowserInterceptorTool onNavigate={setCurrentPage} />;
|
||||
case "settings":
|
||||
|
||||
@@ -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 },
|
||||
];
|
||||
|
||||
|
||||
@@ -0,0 +1,23 @@
|
||||
/**
|
||||
* 插件中心页面
|
||||
*
|
||||
* 独立的插件管理页面，从设置页迁移到导航栏
|
||||
* 提供插件安装、卸载、启用/禁用等功能
|
||||
*
|
||||
* @module components/plugins/PluginsPage
|
||||
*/
|
||||
|
||||
import { PluginManager } from "./PluginManager";
|
||||
|
||||
export function PluginsPage() {
|
||||
return (
|
||||
<div className="space-y-6">
|
||||
<div>
|
||||
<h1 className="text-3xl font-bold">插件中心</h1>
|
||||
<p className="text-muted-foreground mt-1">管理和配置 ProxyCast 插件</p>
|
||||
</div>
|
||||
|
||||
<PluginManager />
|
||||
</div>
|
||||
);
|
||||
}
|
||||
@@ -6,6 +6,7 @@
|
||||
|
||||
| 文件 | 说明 |
|
||||
|------|------|
|
||||
| `PluginsPage.tsx` | 插件中心页面，独立的导航栏入口 |
|
||||
| `PluginManager.tsx` | 插件管理主组件，显示插件列表和状态 |
|
||||
| `PluginInstallDialog.tsx` | 插件安装对话框，支持本地文件和 URL 安装 |
|
||||
| `PluginUninstallDialog.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" && <McpPage hideHeader />}
|
||||
{activeTab === "prompts" && <PromptsPage hideHeader />}
|
||||
{activeTab === "skills" && <SkillsPage hideHeader />}
|
||||
{activeTab === "plugins" && <PluginManager />}
|
||||
</div>
|
||||
</div>
|
||||
);
|
||||
|
||||
Reference in New Issue
Block a user