mirror of
https://github.com/aiclientproxy/proxycast.git
synced 2026-10-16 15:34:08 +08:00
220 lines
5.0 KiB
Markdown
220 lines
5.0 KiB
Markdown
# 插件开发指南
|
||
|
||
本文档描述 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/) 图标名称：
|
||
|
||
常用图标：
|
||
- `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
|
||
```
|
||
|
||
## 开发调试
|
||
|
||
### 本地安装测试
|
||
|
||
1. 打包插件 ZIP
|
||
2. 在「插件中心」点击「安装插件」
|
||
3. 选择本地 ZIP 文件安装
|
||
|
||
### 日志调试
|
||
|
||
插件执行日志保存在：
|
||
- macOS: `~/Library/Application Support/proxycast/logs/`
|
||
- Windows: `%APPDATA%/proxycast/logs/`
|
||
- Linux: `~/.local/share/proxycast/logs/`
|
||
|
||
## 示例插件
|
||
|
||
参考 [MachineIdTool](https://github.com/aiclientproxy/MachineIdTool) 作为二进制插件的完整示例。
|