API Reference · Planning · v0.1

XiVST API 规范（规划版）

插件 SDK + Marketplace 服务端 + 鉴权 + 事件回调

文档版本：v0.1 规划版 · 文档编号：D2-P10-TECH-002 · 发布日期：2026-05-05

Stable ABI · Open REST · Event-Driven

4

API 域

v0.1

规划阶段

OAuth 2.0

鉴权标准

XiVST API 规范（规划版）

摘要

本规划版定义 XiVST v0.1 四大 API 域：① 插件开发 SDK（C++ / C）· ② Marketplace REST API · ③ OAuth 2.0 鉴权 · ④ Webhook 事件回调。 所有接口签名、字段、错误码均为 v0.1 规划，以 Seed 阶段（2026 Q1–Q2）原型实现为准。GA 版本（v1.0）发布前保留调整空间。

规划版约束

• 接口签名可能在 Seed 阶段因原型反馈而调整
• 错误码编号目前是规划占位，正式版将统一编排
• 本文不代表对任何客户的商务承诺

---

1. API 域总览

graph LR
  DEV[开发者] --> SDK[① SDK API<br/>C++/C Header]
  DEV --> REST[② REST API<br/>Marketplace]
  REST --> OAUTH[③ OAuth 2.0]
  REST -->|发布后| HOOK[④ Webhook]
  HOOK --> DEV

  class DEV xyEnd
  class SDK xyL3
  class REST xyL4
  class OAUTH xyWarn
  class HOOK xyL2

域	面向	语言 / 协议	稳定性（规划）
① SDK	插件开发者	C++ 17 / C 99	ABI 在 0.x 内保持二进制兼容
② REST	IDE / CI / 第三方工具	HTTPS + JSON	v0.1 接口加 v0 前缀版本路径
③ OAuth 2.0	开发者 / Tier1	标准协议	基于 RFC 6749 / RFC 8252
④ Webhook	开发者后台	HTTPS POST	支持重试 + 签名校验

---

2. 子域 ① · SDK API（C++）

2.1 头文件分层（规划）

xvst/
├── plugin.h        # Plugin 基类 + 生命周期
├── types.h         # 基础类型（AudioBuffer / Params / ParamId ...）
├── log.h           # 统一日志接口
├── meta.h          # 清单注册宏（与 manifest.json 对齐）
└── version.h       # SDK 版本宏（XVST_SDK_VERSION）

2.2 Plugin 基类（规划）

// xvst/plugin.h · 规划版
#include <xvst/types.h>

namespace xvst {

class Plugin {
public:
  virtual ~Plugin() = default;

  // ─── 生命周期（规划） ───
  virtual Status on_load(const LoadContext& ctx) = 0;
  virtual void   on_unload() = 0;

  // ─── 音频处理（规划 · block-based） ───
  virtual Status process(const AudioBuffer& in, AudioBuffer& out) = 0;

  // ─── 参数热更新（规划 · lock-free） ───
  virtual void set_param(ParamId id, float value) = 0;
  virtual float get_param(ParamId id) const = 0;

  // ─── 可选：状态查询（规划） ───
  virtual void get_meter(MeterData& out) const {}
};

// 规划 · 导出宏
#define XVST_EXPORT_PLUGIN(ClassName) \
  extern "C" XVST_API xvst::Plugin* xvst_create() { return new ClassName(); } \
  extern "C" XVST_API void xvst_destroy(xvst::Plugin* p) { delete p; }

}  // namespace xvst

2.3 核心数据类型（规划）

// xvst/types.h · 规划版（节选）
namespace xvst {

using ParamId = uint32_t;

struct AudioBuffer {
  float** channels;     // channels[ch][sample]
  uint32_t num_channels;
  uint32_t num_samples; // 规划默认 block_size = 128
  double   sample_rate; // 规划支持 44.1 / 48 / 96 kHz
};

struct LoadContext {
  uint32_t xvst_runtime_version;
  uint32_t max_block_size;
  double   sample_rate;
  const char* plugin_data_dir;  // 规划 · 插件数据目录（只读）
};

struct MeterData {
  float rms_in[8];
  float rms_out[8];
  float peak_in[8];
  float peak_out[8];
};

enum class Status : int32_t {
  OK              = 0,
  ERR_VERSION     = 1001,  // 规划占位
  ERR_SAMPLE_RATE = 1002,
  ERR_CHANNELS    = 1003,
  ERR_INTERNAL    = 1999,
};

}  // namespace xvst

2.4 SDK 使用范例（规划）

// examples/warmth_tuning.cpp · 规划版
#include <xvst/plugin.h>

class WarmthTuning : public xvst::Plugin {
public:
  xvst::Status on_load(const xvst::LoadContext& ctx) override {
    sr_ = ctx.sample_rate;
    return xvst::Status::OK;
  }

  void on_unload() override {}

  xvst::Status process(const xvst::AudioBuffer& in,
                       xvst::AudioBuffer& out) override {
    for (uint32_t ch = 0; ch < in.num_channels; ++ch) {
      for (uint32_t n = 0; n < in.num_samples; ++n) {
        out.channels[ch][n] = std::tanh(drive_ * in.channels[ch][n]);
      }
    }
    return xvst::Status::OK;
  }

  void  set_param(xvst::ParamId id, float v) override {
    if (id == kParamDrive) drive_.store(v);
  }
  float get_param(xvst::ParamId id) const override {
    return id == kParamDrive ? drive_.load() : 0.0f;
  }

private:
  static constexpr xvst::ParamId kParamDrive = 1;
  std::atomic<float> drive_{0.3f};
  double sr_{48000.0};
};

XVST_EXPORT_PLUGIN(WarmthTuning)

2.5 C 接口桥（规划）

纯 C 场景（xidsp 芯片 native 目标）通过如下桥接头使用：

// xvst/c_api.h · 规划版
#include <stdint.h>

typedef struct xvst_plugin xvst_plugin_t;

xvst_plugin_t* xvst_create(void);
void           xvst_destroy(xvst_plugin_t*);
int32_t        xvst_process(xvst_plugin_t*,
                            const float* const* in, uint32_t in_ch,
                            float* const* out,      uint32_t out_ch,
                            uint32_t n_samples);
void           xvst_set_param(xvst_plugin_t*, uint32_t id, float v);

---

3. 子域 ② · Marketplace REST API

3.1 Base URL 与版本路径（规划）

Production : https://api.market.xisound.com/v0
Staging    : https://api.staging.market.xisound.com/v0

所有接口前缀 /v0，进入 GA 后规划切到 /v1。新旧版本规划并行 ≥ 12 个月。

3.2 接口索引（规划 · v0.1 MVP）

分类	Method	Path	说明
检索	GET	/v0/plugins	插件列表（分页 / 过滤）
检索	GET	/v0/plugins/{id}	插件详情
检索	GET	/v0/plugins/{id}/versions	版本列表
发布	POST	/v0/plugins	创建新插件（首版）
发布	POST	/v0/plugins/{id}/versions	发布新版本 · 上传 .xvst
认证	GET	/v0/plugins/{id}/cert-status	查询认证进度
评价	GET	/v0/plugins/{id}/reviews	评论列表
评价	POST	/v0/plugins/{id}/reviews	提交评价
账户	GET	/v0/me	当前开发者账户
账户	GET	/v0/me/earnings	分成收入

3.3 插件列表（GET /v0/plugins）

Query 参数：

参数	类型	默认	说明
q	string	—	全文检索（名称 / 标签 / 描述）
category	string	—	tuning / fx / nr / ai 等
cert_level	string	—	community / verified / official
target	string	—	xidsp-d3 / x86_64-linux 等
page	int	1	分页页码
page_size	int	20	规划上限 100

响应示例：

{
  "page": 1,
  "page_size": 20,
  "total": 137,
  "items": [
    {
      "id": "com.example.tuning.warmth",
      "name": "Warmth Tuning",
      "version_latest": "1.2.0",
      "author": "Example Studio",
      "cert_level": "verified",
      "category": "tuning",
      "tags": ["eq", "warmth"],
      "price": { "type": "indie", "amount": 999, "currency": "CNY" },
      "rating": 4.6,
      "downloads": 2380
    }
  ]
}

3.4 发布新版本（POST /v0/plugins/{id}/versions）

请求形态（规划）

Content-Type: multipart/form-data

字段： - file · .xvst 二进制包（必选） - changelog · 版本变更说明（必选） - target_cert_level · 目标认证等级（可选 · community / verified / official）

成功响应（202 Accepted）：

{
  "plugin_id": "com.example.tuning.warmth",
  "version": "1.3.0",
  "status": "scanning",
  "cert_level": "pending",
  "queue_position": 3,
  "estimated_review_minutes": 15
}

3.5 统一错误响应（规划）

所有 4xx / 5xx 响应遵循统一结构：

{
  "error": {
    "code": "XVST_4001_INVALID_MANIFEST",
    "message": "manifest.json missing required field 'xvst_version'",
    "request_id": "req_01J5...",
    "docs": "https://docs.xisound.com/xivst/errors#XVST_4001"
  }
}

规划错误码段：

码段	域	示例
XVST_1xxx	SDK / Runtime	XVST_1001_VERSION_MISMATCH
XVST_4xxx	请求合法性	XVST_4001_INVALID_MANIFEST
XVST_4xx9	认证 / 授权	XVST_4019_UNAUTHORIZED
XVST_5xxx	服务端	XVST_5001_INTERNAL

---

4. 子域 ③ · OAuth 2.0 鉴权

4.1 支持的 Grant Types（规划）

Grant	适用场景	规划支持度
Authorization Code + PKCE	IDE / CLI 桌面应用	✅ 首选
Client Credentials	CI / Server 间调用	✅
Device Code	车机 / 嵌入式	规划 Growth 阶段启用
Refresh Token	长周期令牌续期	✅

4.2 授权端点（规划）

Authorization : https://auth.xisound.com/oauth2/authorize
Token         : https://auth.xisound.com/oauth2/token
JWKS          : https://auth.xisound.com/.well-known/jwks.json
UserInfo      : https://auth.xisound.com/oauth2/userinfo

4.3 Scope 规划列表

Scope	权限
xvst.read	读取公开插件目录 · 查看自己账户
xvst.publish	发布 / 更新插件
xvst.review.write	提交评价
xvst.earnings.read	查看分成收入
xvst.admin	平台内部管理（不开放给第三方）

4.4 访问令牌（JWT · 规划 claim）

{
  "iss": "https://auth.xisound.com",
  "sub": "dev_01J5ABC...",
  "aud": "market.xisound.com",
  "scope": "xvst.read xvst.publish",
  "exp": 1735660800,
  "iat": 1735657200,
  "dev_role": "developer",
  "cert_verified": true
}

---

5. 子域 ④ · Webhook 事件

5.1 事件类型（规划）

事件	触发时机
plugin.scan.completed	自动扫描完成
plugin.review.approved	人工审核通过
plugin.review.rejected	人工审核驳回（附意见）
plugin.published	新版本正式上架
plugin.sale.created	产生一笔购买（规划字段含金额 · 用户脱敏 ID）
plugin.earnings.settled	月度分成结算完成

5.2 事件包 schema（规划）

{
  "event_id": "evt_01J5XYZ...",
  "event_type": "plugin.review.approved",
  "occurred_at": "2026-11-05T12:00:00Z",
  "data": {
    "plugin_id": "com.example.tuning.warmth",
    "version": "1.3.0",
    "cert_level": "verified"
  }
}

5.3 签名校验（规划）

平台以 HMAC-SHA256 签名头 X-XVST-Signature 携带。开发者以订阅时配置的 webhook_secret 校验：

X-XVST-Signature: t=1735660800, v1=hex(hmac_sha256(secret, t + "." + body))

5.4 重试策略（规划）

• 非 2xx 响应视为失败
• 规划重试 5 次 · 间隔：30s / 2m / 10m / 1h / 6h
• 超过最大重试后事件进入「待人工处理队列」并发通知邮件

---

6. 版本策略与向后兼容

6.1 SDK ABI 策略（规划）

• XVST_SDK_VERSION 宏三段 MAJOR.MINOR.PATCH
• 0.x.y 系列内保证 ABI 二进制兼容
• 升 1.0 需提前 6 个月公告 + 迁移工具 + 双版本并行期 ≥ 12 个月

6.2 REST 版本策略（规划）

• 通过 URL 路径版本（/v0 → /v1）
• 已发布版本字段只加不删；字段废弃需公告 + Deprecation 响应头
• 破坏性变更仅在主版本号升级时出现

6.3 Webhook 版本策略（规划）

• 事件 schema 添加字段向后兼容
• 重命名事件 / 调整嵌套结构视为主版本升级 · 以新事件名并行发布

---

7. Rate Limit（规划）

维度	匿名（未登录）	开发者账户	企业客户
每分钟请求数	规划 60	规划 600	规划 6000
并发上传 .xvst	—	规划 2	规划 10
Webhook 推送频率	—	无额外限流	无额外限流

超限响应 429 Too Many Requests，携带 Retry-After 秒数提示。

---

8. SDK 下载与版本矩阵（规划）

平台	构建产物（规划）
Linux x86_64	libxvst-sdk-<ver>-linux-x86_64.tar.gz
Linux aarch64	libxvst-sdk-<ver>-linux-aarch64.tar.gz
macOS universal	libxvst-sdk-<ver>-macos-universal.tar.gz
Windows x86_64	libxvst-sdk-<ver>-windows-x86_64.zip
xidsp-d3 native	libxvst-sdk-<ver>-xidsp-d3.tar.gz（规划 Seed 阶段提供）

---

9. 变更记录（规划视图）

版本	状态	主要变化
v0.1	规划	首次对外规划 · 四域 API 轮廓
v0.2	规划	Seed 阶段反馈修正（待）
v0.9	规划	RC 候选（Growth 阶段前）
v1.0	规划	GA · ABI 锁定

---

10. 验收

• 四 API 域边界清晰（SDK / REST / OAuth / Webhook）
• 核心 C++ 基类签名 + REST 主路径定义
• 错误码、签名、Rate Limit 规划占位
• Seed 阶段原型验证（2026 Q1–Q2）
• Growth 阶段开放 SDK 下载
• v1.0 发布时本文升级为 API Reference 正式版

---

附录 A · 参考

• XiVST 产品概述（规划版）
• XiVST PRD v0.1（规划版）
• XiVST 产品规格书 Spec（规划版）
• XiVST 技术架构（规划版）
• 标准：RFC 6749（OAuth 2.0）· RFC 8252（OAuth 2.0 for Native Apps）· RFC 7519（JWT）

---

api.md · D2-P10-TECH-002 · v0.1 规划版 · 2026-05-05 · Xisound AlgoDepartment