proxycast/docs/content/06.development/5.plugin-development.md

插件开发指南

本文档描述 ProxyCast 插件系统的规范和开发指南，为插件市场做准备。

插件类型

ProxyCast 支持两种类型的插件：

1. 脚本插件 (Script Plugin)

纯 JavaScript/TypeScript 插件，通过 Hook 机制扩展功能。

{
  "plugin_type": "script",
  "entry": "main.js",
  "hooks": ["on_request", "on_response"]
}

2. 二进制插件 (Binary Plugin)

独立的可执行文件，通过 CLI 接口与 ProxyCast 通信。适合需要系统级操作的工具。

{
  "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 规范

{
  "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	设置页	设置页扩展区域（规划中）

示例：工具类插件

{
  "ui": {
    "surfaces": ["tools"],
    "icon": "Cpu",
    "title": "机器码管理工具"
  }
}

安装后，插件会出现在「工具箱」页面，用户点击即可打开。

图标规范

使用 Lucide Icons 图标名称：

{
  "ui": {
    "icon": "Cpu"
  }
}

常用图标：

• Cpu - 系统/硬件工具
• Globe - 网络工具
• Database - 数据工具
• Shield - 安全工具
• Wrench - 通用工具
• Terminal - 命令行工具

二进制插件 CLI 接口规范

二进制插件通过 CLI 与 ProxyCast 通信，必须遵循以下规范：

输出格式

所有输出必须是 JSON 格式：

# 成功
$ my-tool-cli get
{"machine_id": "550e8400-e29b-41d4-a716-446655440000"}

# 错误
$ my-tool-cli invalid-command
{"error": "未知命令: invalid-command"}

退出码

• 0 - 成功
• 1 - 错误

命令结构

my-tool-cli <command> [arguments]

建议实现 help 命令：

$ 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

- 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 作为二进制插件的完整示例。

开发调试

本地安装测试

1. 打包插件 ZIP
2. 在「插件中心」点击「安装插件」
3. 选择本地 ZIP 文件安装

日志调试

插件执行日志保存在：

• macOS: ~/Library/Application Support/proxycast/logs/
• Windows: %APPDATA%/proxycast/logs/
• Linux: ~/.local/share/proxycast/logs/