插件 SDK 手册

① 什么是插件？

插件是一块「不改动平台核心、却能为平台加功能」的代码。装了插件，你的微国家就能拥有新的卡片、主题、背景或工具——就像给手机装 App。

插件在平台预留的「插座」（扩展点）上接东西，安全又灵活。写插件 = 写一个清单（manifest，说明你是谁、要什么权限）+ 一段代码（plugin.js，干活的逻辑）。

② 平台全貌（插件能碰到哪些模块）

插件不是孤立的小工具，它能接入平台的这些模块——每一条都对应一个或多个扩展点：

简言之：一切「看得到」的默认展示方式（动画、卡片外观、菜单、按钮、弹窗、布局、图标……）都能自定义或增加；「看不到」的核心功能与结构（登录、数据、业务规则……）不能改。

③ 平台实体速查（本平台「什么对应什么」）

这是关键的一节——插件里用到的每个 ID / 值，都对应平台里真实存在的实体：

🃏 卡型（cardType）——现有卡，插件能注册新卡型加入资产面板

✂️ 边缘主题（edgeTheme）——现有边缘，插件能注册新边缘

注：内置边缘共 14 个主题，上表列出最常用的；插件注册新边缘用 edgeTheme 扩展点。

👑 订阅等级（tier）——插件门槛用的值

📄 主要页面（页面级扩展点的宿主）

🔤 字体（font）——插件能挂接字体

平台内置 451 款字体，分 10 个语言组（拉丁 / 中文 / 日文 / 韩文 / 阿拉伯文 / 西里尔文等）。插件通过 ui.theme 能力覆盖字体变量，或注册新字体包。

✨ 动画（animation）——插件能加开启动画

平台自带页面打开 / 切换动画（transitions.js）。插件通过 ui.animation 能力，为网页添加或替换自定义的开启动画、入场特效。

④ 一个插件 = 两份东西

1. manifest（清单）：插件的「身份证」，告诉平台它叫什么、能干什么、需要什么权限。

2. 代码（plugin.js）：真正干活的逻辑，按 manifest 里声明的能力去接扩展点。

⑤ manifest 完整参考

manifest 是一个 JSON 对象。完整示例：

{
  "id": "my-weather-card",
  "name": "天气卡",
  "version": "1.0.0",
  "author": "USR-000101",
  "description": "在画布里添加实时天气卡片，支持多城市切换",
  "icon": "⛅",
  "preview": "linear-gradient(135deg,#4648d4,#7b7ff0)",
  "category": "card",
  "capabilities": ["cardType", "ui.menu", "storage"],
  "minTier": "premium",
  "tags": ["天气", "卡片"],
  "license": "MIT"
}

⑥ capabilities 详解（能力 → 平台具体位置）

每个能力都对应平台里的一个或多个具体位置：

⚠️ 能力沙箱：插件只能调用自己声明过的能力，声明之外的调用会被平台直接拦下。

⑦ API 完整参考

插件代码里通过全局 plugin 对象调用平台 API。以下是完整 API（规划，随执行引擎逐步开放）：

// 注册插件主体（一个插件只调一次）
plugin.register({
  id: 'my-weather-card',           // 与 manifest.id 一致
  cardType: { /* 见下方 */ },
  menuItem: { /* 见下方 */ },
  edgeTheme: { /* 见下方 */ },
  tool: { /* 见下方 */ },
  on: { /* 事件处理，见第 ⑧ 节 */ }
});

// 读写插件专属存储（需 storage 能力）
plugin.storage.set('defaultCity', 'Singapore');   // 存（键值均可为字符串/JSON）
var city = plugin.storage.get('defaultCity');      // 取
plugin.storage.remove('defaultCity');              // 删

// 订阅事件（需 hook 能力）
plugin.on('card.create', function (card) { /* ... */ });

// 发站内通知（需 notification 能力）
plugin.notify({ title: '天气已更新', body: '新加坡已更新为 32°' });

⑧ 事件钩子完整参考

订阅这些事件，在对应动作发生时自动执行你的代码：

示例：建卡时自动打标签——

plugin.on('card.create', function (card) {
  card.tags = (card.tags || []).concat(['待整理']);
});

⑨ 完整示例

示例 A：天气卡（注册新卡型 + 菜单）

{
  "id": "my-weather-card",
  "name": "天气卡",
  "version": "1.0.0",
  "author": "USR-000101",
  "description": "在画布里添加实时天气卡片",
  "icon": "⛅",
  "capabilities": ["cardType", "ui.menu"],
  "minTier": "premium"
}

plugin.register({
  id: 'my-weather-card',
  cardType: {
    id: 'weather',
    label: '天气卡',
    render(data) {
      return '' + data.city + ' ' + data.temp + '°';
    }
  },
  menuItem: { title: '天气', icon: '⛅', after: '地图' }
});

示例 B：极简主题（换肤 + 背景）

{
  "id": "my-minimal-theme",
  "name": "极简主题",
  "version": "1.0.0",
  "author": "USR-000101",
  "description": "一套更清爽的 UI 配色与画布背景",
  "icon": "🎨",
  "capabilities": ["ui.theme", "ui.background"],
  "minTier": "free"
}

plugin.register({
  id: 'my-minimal-theme',
  theme: {
    '--color-primary': '#7b7ff0',
    '--color-background': '#0f2027'
  },
  background: { canvas: 'linear-gradient(135deg,#0f2027,#2c5364)' }
});

示例 C：事件钩子（建卡自动归档）

plugin.register({
  id: 'my-auto-archive',
  on: {
    'card.create': function (card) {
      card.tags = (card.tags || []).concat(['待整理']);
    }
  }
});

⑩ 开发与测试

⑪ 版本管理（语义化版本）

每次更新写 changelog（更新说明）。用户能在插件详情页「版本」标签看到全部历代版本。

⑫ 提交与审核

提交前自检清单：✅ id 唯一 · ✅ 最小权限 · ✅ 代码能跑 · ✅ 不碰隐私 · ✅ 写了 changelog

什么会被拒：恶意代码、越权调用、偷传用户数据、抄袭、与平台功能重复。

⑬ 订阅等级与「下放」

premium → 新插件默认门槛，只有高级订阅用户能装。

basic → 使用量上来了，官方「下放」到基础订阅。

free（平台内置） → 特别优秀的插件被官方「收编」成平台自带，无需手动安装；官方通知作者并打赏资金感谢贡献。

⑭ 沙箱与安全边界

沙箱 + AI 检查 + 官方审核，三重保障。

⑮ 命名与图标规范

⑯ 最佳实践

⑰ 常见问题