# 插件开发指南

本文档描述 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/`