00概述与交付物

像素播放器插件是「声明 + 可执行体 + 可选界面」的扩展包。第三方开发者交付一个 zip，用户在 App 内导入并授权后启用；插件通过宿主开放的 Host API 访问播放、曲库、投屏、外设、存储、分享与 AI 能力，不需要也不允许修改宿主源码。

交付物

五分钟闭环

cd 插件中心
node tooling/xs-pack.js validate plugins/my-plugin   # 校验 manifest / 权限 / 界面入口
node tooling/xs-pack.js test plugins/my-plugin       # 本地跑通注册与 onEnable
node tooling/xs-pack.js pack plugins/my-plugin -o out/my-plugin-1.0.0.zip

# 上传到自有商店（可选）
cp out/my-plugin-1.0.0.zip server/zips/
cp plugins/my-plugin/manifest.json server/zips/my-plugin-1.0.0.json
node server/update-index.js

01运行时与生命周期

两套运行时

生命周期与状态机

installed ──同意协议──▶ agreed ──启用──▶ enabled
   │                                    │
   │                                    ├─ onEnable()  一次
   │                                    ├─ onAction(id) 每次点击
   │                                    └─ onDisable()  禁用时一次
   └─ 卸载：删除安装包快照、界面资产、WASM 模块、私有 KV

• 安装即持久化：导入成功后，宿主把原始 zip 保存为安装快照；下次冷启动按同一路径重建，不依赖临时目录。
• 重启提示：导入/下载完成后，App 内会提示「插件已部署 · 请重启 App 以启用」。新插件的运行时与指令坞在冷启动时完整挂载。
• 幂等：onEnable 可能因恢复、重新启用而被多次调用，必须可重入（不要假设只执行一次）。
• 失败可见：恢复失败不会静默删除，会在插件中心控制台记录；用户可卸载后重新导入。

执行环境约束

• 脚本运行在隔离沙箱：无文件系统、无网络直连、无进程派生；唯一 I/O 是 xs.host.*。
• 单次调用有超时预算；长任务要拆分，避免阻塞主线程。
• 禁止 eval / Function 动态构造（宿主在加载阶段拦截）。

02manifest 规范（schema v3）

完整示例

{
  "schemaVersion": 3,
  "id": "com.example.awesome",
  "name": "AWESOME 调度器",
  "version": "1.0.0",
  "type": "capability",
  "apiLevel": 3,
  "runtime": "script",
  "author": { "name": "Your Name", "email": "dev@example.com" },
  "description": "一句话说明插件解决什么问题",
  "icon": "bolt.horizontal.circle",
  "capabilities": [
    { "id": "media",   "version": 1, "permissions": ["media.info", "media.control", "queue.manage"] },
    { "id": "library", "version": 1, "permissions": ["library.read"] },
    { "id": "storage", "version": 1, "permissions": ["storage.read", "storage.write"] },
    { "id": "notification", "version": 1, "permissions": ["notification.send"] }
  ],
  "playerActions": [
    { "id": "open",  "icon": "rectangle.3.group", "title": "面板" },
    { "id": "run",   "icon": "play.circle",        "title": "执行" }
  ],
  "ui": { "entry": "ui/index.html", "title": "AWESOME 面板" },
  "agreement": "agreements/terms.md",
  "networkDomains": ["api.example.com"]
}

字段与校验

• zip ≤ 30MB；main.js ≤ 2MB；ui/ 单文件 ≤ 2MB；.wasm ≤ 8MB；
• 禁止 .so / .dylib / .dll 等原生库；允许 .wasm；
• 条目名禁止 ../、绝对路径、符号链接；
• 宿主必须忽略未知字段（向前兼容）。

03能力与权限

14 项能力

22 项权限与授权流

权限必须挂在某个 capability 的 permissions 下（无独立 lyrics 能力，歌词权限挂 media）。授权三级门槛：协议 → 配置 → 启用，任一失败不进入下一步。未授权调用一律返回 { "error": "permission_denied" }。

04Host API 契约

调用约定

• 全部异步，返回 Promise；参数与返回均为 JSON 兼容类型；
• 失败返回 { error: "code" }，不抛异常；统一先判 res && !res.error；
• 未实现 → not_implemented；未授权 → permission_denied；写错方法名 → no_such_method；
• 单位约定：播放进度/时长/歌词时间为 毫秒；投屏 seek 为 秒。

模块总览

错误码

05插件界面与设计规范

WebView 容器

• manifest 声明 ui 后，宿主以 WebView 加载 ui/index.html，资产解包到应用私有目录；
• 注入与脚本插件完全相同的 __xsHost__ 桥，可直接用 xs.host.*；
• CSP：script-src 'self' file: 'unsafe-inline' 'unsafe-eval' 'wasm-unsafe-eval'，connect-src 'self' file:；远程网络必须走 xs.host.network；
• 导航只允许插件目录内 file://；
• 首次进入宿主会显示一次「插件独立界面」引导条，插件内不必重复大段教学。

双页面：原生控制台 + 插件界面

声明 ui 的插件，详情页会同时保留两套页面，顶部用分段控件切换，两套页面共享同一份权限与运行时：

"ui": {
  "entry": "ui/index.html",
  "title": "MY 面板",
  "defaultPage": "plugin"   // plugin（缺省）| native
}

• 原生页用于兜底与排障：插件界面白屏、CSP 配置错误、运行时异常时，用户仍可执行指令、查看回执；
• 插件页必须可独立完成核心流程，不得只提供「去原生页点按钮」的说明；
• 双端一致：Android 必须实现同样的两页与分段切换，默认页读取同一字段。

视觉与交互规范（摘要）

完整规范见仓库 插件中心/spec/ui-guidelines.md。硬性要求：

• 深色底 #161B1A，强调色 var(--xs-accent, #2DB95A) —— 由宿主注入、跟随 App 主题，插件禁止硬编码主色；
• 左右内边距 16pt，底部 76 + env(safe-area-inset-bottom)；不覆盖宿主导航与迷你播放条；
• 卡片圆角 18、细描边 + 顶部主题色高光；中文正文 15pt / 行高 1.65，不用等宽；时间统一 mm:ss，数据用等宽；
• 一屏只有一个主按钮；危险操作必须二次确认；按钮 ≥ 46pt 高、触控区 ≥ 44pt；
• 四态齐全（加载 / 空 / 错误 / 成功），错误文案三段式：发生了什么 + 错误码 + 下一步；
• 禁止 emoji、彩色阴影、远程字体与外部脚本；禁止自绘返回按钮。

// 宿主每 500ms 推送：{ song, state:{state,position,duration}, queue }
window.xsOn('playback', function (p) {
  bar.style.width = (p.state.duration ? p.state.position / p.state.duration : 0) * 100 + '%';
  title.textContent = (p.song && p.song.title) || '未播放';
  queue.textContent = p.queue + ' 首';
});

页面骨架

<div class="hdr"><span class="sq"></span><span class="t">MY // SUBSYSTEM</span><span class="n">01</span></div>
<div class="kicker">PANEL // 中文小标</div>
<div class="title" id="title">--</div>
<div class="sub">▸ 一句话状态</div>
<div class="rule"></div>

<div class="rows">
  <div class="row"><span class="i">01</span><span class="k">FIELD</span><span class="v" id="v1">--</span></div>
</div>

<div class="grid">
  <button class="btn" id="run"><b>执行</b><span class="tag">RUN</span></button>
</div>

<div class="out" id="out">待命</div>
<div class="foot"><span>XIANGSU PLAYER</span><span>MY · V1.0.0</span></div>

06声明式海报（sharePoster）

任何插件都能用 share.sharePoster 生成竖版 1080×1920 海报。版式由插件声明 blocks，宿主统一渲染：插件不写坐标、不做 UI 特权。配文只写入剪贴板，分享面板只提交图片。

await xs.host.share.sharePoster({
  title: song.title, artist: song.artist, album: song.album,
  position: st.position, duration: st.duration, queue: queue.length,
  state: String(st.state), source: song.source, accent: '#FF5A1F', sig: 'A1B2C3D4',
  blocks: [
    { type: 'header', left: 'MY // POSTER', right: '01' },
    { type: 'kicker', accentText: 'NOW PLAYING', dimText: '// 简报' },
    { type: 'title', text: song.title, size: 104, maxLines: 2 },
    { type: 'sub', text: '▸ ' + song.artist },
    { type: 'spacer' }, { type: 'barcode' },
    { type: 'ticker', accentText: 'XIANGSU PLAYER', dimText: '// POSTER' }
  ]
});

07WASM 插件

两条路径

runtime=wasm 的 ABI

模块不得声明 import，导出（参数/返回均为 i32）：xs_action(ptr,len)（必需）、xs_alloc 或 buf_ptr/buf_cap、xs_result_ptr/xs_result_len、可选 xs_init / xs_enable / xs_disable。

#[no_mangle] pub extern "C" fn xs_action(ptr: usize, len: usize) -> i32 {
    let data = unsafe { core::slice::from_raw_parts(ptr as *const u8, len) };
    // data = {"action":"signal","context":{"song":{...},"state":{...},"queue":[...]}}
    emit(b"{\"toast\":\"SIG 5FF20A64\"}");
    0
}

• 结果 JSON 可含 toast / notify / shareText / addQueue / ui，由宿主按权限执行；
• 内存上限 64MB，指令预算 5000 万；解释执行，约为原生 1/10–1/30，适合一次性计算；
• 构建：rustc --target wasm32-unknown-unknown --crate-type cdylib -O -C panic=abort -C strip=debuginfo（不 strip 会膨胀到数百 KB）；
• 参考实现：wasm-src/plugin_probe.rs 与官方样例 com.xiangsu.wasmcore。

Rust SDK（xs-plugin v0.1）

官方提供 xs-plugin crate：不手写 ABI、不拼 JSON、不管缓冲区，只写业务逻辑。样例 com.xiangsu.rustcore（4.6KB wasm）可直接拆包对照。

#![no_std]
use core::panic::PanicInfo;
use xs_plugin::{xs_main, Out, Request};

#[panic_handler]
fn panic(_: &PanicInfo) -> ! { loop {} }

fn handle(req: Request, out: &mut Out) {
    match req.action() {
        "signal" => out.toast_hex("SIG ", fnv(req.raw().as_bytes())),
        "song"   => out.toast(req.str("title").unwrap_or("UNKNOWN")),
        _        => out.error("unknown_action"),
    }
}

xs_main!(handle);

node tooling/xs-rust.cjs plugins/my-plugin --pack
# cargo 编译 → 校验 ABI → 写入 plugin.wasm → xs-pack 打包

• Request：action() / str(key) / num(key) / count(key) / len()；Out：toast / toast_hex / notify / share_text / add_queue / skin / error；
• 宿主注入 context.library（声明 library.read 时，最多 2000 首）与 libraryTotal；addQueue 支持数组批量入队；
• 必须 strip = "debuginfo"，否则体积从 4–6KB 膨胀到 600KB+；
• 完整规范：仓库 `插件中心/spec/rust-sdk.md`。

08打包、商店与发布

zip 结构

my-plugin/
├── manifest.json
├── main.js            # script 插件必需
├── plugin.wasm        # wasm 插件必需
├── ui/index.html      # 可选，自带界面
├── agreements/terms.md
└── assets/            # 可选，图标等

根目录直接是 manifest.json，不要多包一层文件夹。打包后 zip ≤ 30MB。

商店协议

默认商店：https://xiangsudev.cn/plugin-store。客户端下载后必须校验 sha256；索引字段变更需向后兼容。

审核与更新

提交入口：/publish.html（开发者入驻）。必填项包含：开发者信息、插件介绍、权限理由、隐私政策、用户协议 / 单独协议、数据流向说明。隐私政策可粘贴 Markdown 全文，也可填公开可访问的 https 链接；同时建议在插件包内提供 agreements/terms.md，并让 manifest 的 agreement 指向它。

• 提交：作者信息、功能说明、权限用途、隐私政策、用户协议、数据流向说明、两张界面截图；
• 更新：version 递增 → 重新打包 → 替换 zips/ 同名版本文件 → 重建索引；
• 已安装用户下次打开商店可看到「更新」，覆盖安装保留启用与授权状态；
• 下架：索引移除后不可再下载，已安装插件不自动删除。

09安全、隐私与合规

• 数据最小化：只读取功能必需的数据；曲库、歌词、播放信息不得外发；
• 凭据：不得上传用户 Cookie / 账号凭据；第三方凭据只存本地，且必须有单独协议；
• 网络：只能通过 xs.host.network，域名必须写进 networkDomains；
• 可执行体：允许 .wasm，禁止原生动态库；WASM 不得用于绕过 DRM、挖矿、代理；
• 文案红线：不得宣称破解、非授权音源；仅可表述为「本地 / 自建 NAS 曲库」；
• 通知：不得伪造系统样式或冒充其他应用；
• 协议：敏感能力必须提供 agreements/terms.md，启用前全文展示，禁止默认勾选；
• 上架必填：开发者入驻表单中的《隐私政策》《用户协议》《数据流向说明》三项；审核后台会与 manifest 权限逐项对照，缺失或与权限不符直接驳回。
• 卸载：必须能彻底清除私有 KV、回执、安装快照与资产。

10版本与兼容

11提交前验收清单

• manifest 通过 xs-pack validate；能力与权限一一对应，无多余声明；
• 指令坞入口 ≤ 4 个，含 open（有面板时）；标题 ≤ 6 字；
• 每个指令都有 toast / 通知反馈；错误走三段式文案与稳定错误码；
• 面板符合《UI 设计规范》：安全区、四态、主按钮唯一、无 emoji、无远程资源；
• 断网 / 空曲库 / 未授权 / 无设备 四种异常路径均不崩溃、不静默失败；
• WASM：模块无 import、导出齐全、无 JS 兜底缺失（如需跨端）；
• 协议文本与权限清单一致；隐私说明覆盖所有外发数据；
• 卸载后私有 KV、资产、安装包全部清除；
• 升级路径：旧版本安装后可被新版本覆盖，启用状态与授权保留。