mirror of
https://github.com/aiclientproxy/proxycast.git
synced 2026-10-29 18:16:06 +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,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/`
|
||||
Reference in New Issue
Block a user