API 概览

WQuake API 提供版本检查、服务状态查询等接口。所有接口均需要 API Key 认证，返回 JSON 格式数据。

API 基础路径为 /api，当前版本为 v1。

// 基础 URL
https://your-domain.com/api/v1

// 认证方式
Header: X-API-Key: your-api-key

API 接口规范

请求格式

所有请求需携带 API Key 头部。未认证请求将返回 401 状态码。

响应格式

{
  "success": true,
  "code": 200,
  "data": { ... },
  "timestamp": 1719000000
}

错误响应

{
  "success": false,
  "code": 401,
  "error": "Unauthorized: Invalid API key",
  "timestamp": 1719000000
}

版本检查

客户端可通过此接口检查是否有新版本可用。请求携带当前版本号，服务端返回版本信息及更新状态。

方法路径说明
GET /api/v1/version 检查版本更新

请求参数

参数类型说明
current string 当前客户端版本号，如 "2.9.0"
type string 检查类型: "frontend" 或 "cpp" (可选)

响应示例

{
  "success": true,
  "data": {
    "latest": "2.9.0",
    "current": "2.8.0",
    "hasUpdate": true,
    "minVersion": "2.5.0",
    "forceUpdate": false,
    "changelog": "- 新增巴西圣保罗大学数据源\n- 修复测站震度音频"
  }
}

权限认证

所有 API 请求必须在 HTTP Header 中携带有效的 API Key 进行认证。

认证方式

// 在请求头中携带
X-API-Key: your-api-key-here

// 或者通过 Authorization 头
Authorization: Bearer your-api-key-here

认证错误码

状态码说明
401未提供 API Key 或 Key 无效
403API Key 已过期或被禁用
429请求频率超限 (60次/分钟)

端点列表

方法路径认证说明
GET /api/v1/version 需要 版本检查
GET /api/v1/status 需要 服务状态
POST /api/v1/auth/verify 需要 验证 API Key 有效性
GET /api/v1/plugins?action=list 公开 已发布插件列表（可带 q 搜索）
GET /api/v1/plugins?action=detail&id= 公开 单个插件详情
GET /api/v1/plugins?action=download&id= 公开 下载 .wqplugin 包（JSON）

插件开发

WQuake 支持前端插件：运行在沙箱 iframe 内的 JS 插件，以及由宿主注入主文档的声明式 CSS 主题贡献。插件以单文件 .wqplugin 分发，可在 插件共创 上传、审核发布后进入插件商城，用户在 WQuake「设置 → 高级 → 插件管理」中一键安装。

1. 包格式（.wqplugin）

.wqplugin 本质是一个 JSON 文件，自包含 manifest 与所有文本资源：

{
  "manifest": { /* manifest.json 内容 */ },
  "files": {
    "entry.js": "function onLoad(wq){ ... }",
    "theme.css": ":root{ --accent: #2f9bff; }"
  }
}

2. manifest.json 字段

字段必填说明
id是唯一标识，建议反向域名，如 com.you.myplugin
name是显示名称
version是语义化版本，如 1.0.0
author否作者
description否简介
type否"js"（默认）。"native" 暂不支持
apiVersion否所需插件 API 版本，当前宿主为 1.0
minAppVersion否最低 WQuake 版本
entry否JS 入口文件名（导出 onLoad）
permissions否权限数组，见下表
contributes.styles否注入主文档的 CSS 文件名数组（需 ui:theme）

3. 权限

权限能力
ui:toast弹出消息提示
ui:theme注入 CSS 主题贡献
sound播放提示音
storage插件私有持久化存储
stations注入自定义测站 / 读取震度指标
data:eew / data:earthquake / data:tsunami向宿主注入对应数据

4. 入口脚本与 wq API

入口文件需定义全局函数 onLoad(wq)，启用时被调用。wq 为按权限裁剪的受限 API：

// entry.js
function onLoad(wq) {
  // 订阅事件：'eew' | 'earthquake' | 'tsunami'
  const off = wq.events.on('eew', (data) => {
    wq.ui.toast('收到预警', 'warning');
    wq.sound.play('/audio/eew0.ogg');
  });
  wq.storage.set('k', 1);  // Promise
  wq.onUnload(() => off()); // 禁用时清理
}

可用命名空间：wq.events.on、wq.ui.toast、wq.sound.play、wq.storage.get/set、wq.settings.getAll/get/onChange、wq.stations.setBatch/clear/getMetrics、wq.data.emitEew/emitEarthquake/emitTsunami、wq.log.info/warn/error、wq.onUnload。所有涉及宿主的调用均返回 Promise，且受权限校验。

5. 打包（编译）

源码仓库位于 WQuake/plugins-sdk，内含示例插件 hello-eew 与打包脚本 pack.mjs（仅需 Node.js，无第三方依赖）。目录结构：

plugins-sdk/
  pack.mjs       // 打包器
  hello-eew/
    manifest.json
    entry.js
    theme.css

在 plugins-sdk 目录执行：

# 用法: node pack.mjs <源码目录> [输出目录]
node pack.mjs ./hello-eew ./dist

# 产物: dist/com.wquake.example.helloeew-1.0.0.wqplugin

打包器会校验必填字段、拒绝 native 类型、并确认 entry 与 contributes.styles 声明的文件均已包含。生成的 .wqplugin 即可上传到插件共创页面，审核发布后自动进入商城。

6. 约束与安全

  • 包体积上限 5 MB，示例图上限 2 MB（png/jpg/webp/gif）。
  • 仅支持文本资源；二进制素材请引用外链 URL。
  • JS 运行在 sandbox="allow-scripts" 的不透明源 iframe 中，只能通过 wq 与宿主通信，无法直接访问主文档 DOM、Cookie 或宿主全局变量。
  • 宿主仅授予 manifest 声明且用户可见的权限；未声明权限的调用会被拒绝。
  • CSS 主题贡献会注入主文档，请谨慎使用 !important，优先覆盖 CSS 变量。