proxycast-docs
Open Platform

插件开发指南

本文档描述 ProxyCast 插件系统的规范和开发指南。

插件开发指南

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

字段说明

字段类型必需说明
namestring✅插件唯一标识符，小写字母和连字符
versionstring✅语义化版本号 (semver)
descriptionstring✅插件描述
authorstring❌作者名称
homepagestring❌项目主页 URL
licensestring❌开源许可证
plugin_typestring✅script 或 binary
entrystring✅入口文件/二进制名称
hooksarray❌注册的 Hook 列表
min_proxycast_versionstring❌最低 ProxyCast 版本要求
binaryobject❌二进制插件配置
uiobject❌UI 配置

UI 展示位置 (Surfaces)

插件可以在以下位置显示 UI：

Surface说明入口位置
tools工具箱导航栏「工具」页面
sidebar侧边栏主侧边栏（规划中）
settings设置页设置页扩展区域（规划中）

示例：工具类插件

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

图标规范

使用 Lucide Icons 图标名称：

常用图标：

  • 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

开发调试

本地安装测试

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

日志调试

插件执行日志保存在：

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

示例插件

参考 MachineIdTool 作为二进制插件的完整示例。

插件中心

ProxyCast 支持通过插件扩展功能。插件中心提供插件的安装、管理和配置。

ProxyCast Connect

ProxyCast Connect 是一套中转商生态合作方案，通过 Deep Link 协议实现一键配置功能。

Copyright © 2026