生成清单
用下方在线生成器配置图标、页面与动作，导出 <id>.json；或直接下载示例插件改字段。
返回首页
一份 JSON，
Plugins
一份 JSON，
手表上多一个轻应用
MaciWatch 插件是纯声明式清单：元信息、页面组件、设置与 HTTP 动作写进一个 JSON 文件，导入即用，不需要写任何代码。
声明式 JSON
HTTP + JSONPath
状态本地持久化
{{模板}} 变量
快速开始
三步跑起第一个插件
导入 MaciWatch
表冠点击打开蜂窝 → 插件管理 → 右上角导入：选择 JSON 文件，或粘贴清单文本。同 id 重复导入会覆盖重装。
蜂窝里打开
插件出现在 Honeycomb 蜂窝中，点按即进入；打开时自动执行首个 HTTP 动作拉取数据，也可配置定时刷新。
Plugin Builder
在线插件生成器
左侧配置、右侧实时预览清单 JSON。完成后复制或下载，直接导入 MaciWatch。
Reference
清单格式参考
字段与行为和 MaciWatch 内置的解析器一一对应；示例中的 · 表示可选字段缺省时的取值。
1. 顶层字段
一个插件是一份 JSON 对象，包含元信息、页面、动作、初始状态与刷新策略：
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
id | String | 是 | 唯一标识。字母/数字开头，仅限 A-Z a-z 0-9 . _ -，≤ 100 字符；建议反向域名，如 com.example.stock |
name | String | 是 | 蜂窝与页面标题的显示名 |
version | Int | 是 | 整数版本号，从 1 开始 |
icon | String | 是 | SF Symbol 名称；导入时逐个校验，非法即拒绝 |
colors | [String] | 否 | 蜂窝图标渐变，两个 hex 色；缺省灰色。支持 #RGB / #RRGGBB / #RRGGBBAA |
background | Object | 否 | 页面背景：solid / gradient / image；缺省用 App 默认背景 |
state | Object | 否 | 初始状态键值（字符串 / 数字 / 布尔），修改后持久化到本机 |
refreshInterval | Double | 否 | 定时刷新秒数，≥ 5 生效；缺省不定时 |
loadOnStart | Bool | 否 | 打开插件即执行默认刷新动作 · 缺省 true；设 false 后仅手动触发 |
pages | Object | 是 | 页面表，键为页面 id；main 是入口页，其余为 navigate 子页 |
actions | Object | 是 | 动作表，键为动作 id，供按钮 / 头部控件 / 自动刷新引用 |
2. 页面与头部
每个页面（PluginPage）由四部分组成：头部、内容组件数组、可选设置区、可选底部按钮。整页按「头 / 主区 / 附加区 / 底钮」滚动布局渲染。
| 字段 | 类型 | 说明 |
|---|---|---|
header | Object | title（必填）、icon（可选）、trailing[]（可选，右侧控件） |
body | Array | 内容组件，见下一节；可为空 |
settings | Array | 设置区控件，改动即写回 state；可省略 |
bottom | Array | 底部按钮；可省略 |
头部右侧控件 trailing 有三种：
| type | 字段 | 行为 |
|---|---|---|
button | icon、action | 点按执行动作；命中默认刷新动作时显示加载态 |
toggle | bind、iconOn、iconOff | 开关绑定 state 键，随值切换图标 |
text | bind | 只读显示 state 值 |
3. 内容组件
body 是组件数组，每个组件以 type 区分。除 icon、list、divider 外，文本类组件用 value（字面量，支持 {{key}} 模板）或 bind（读 state）二选一。
| type | 字段 | 说明 |
|---|---|---|
text | value / bind、style、color | 文本。style：normal · hero（大字）· caption（小字）；color：default · accent · warning |
metric | value / bind、unit、style | 大数值（汇率 / 计数），unit 追加单位后缀 · style 缺省 hero |
icon | value | 大号 SF Symbol |
list | bind、titleKey、subtitleKey、valueKey、emptyText | 读 state 数组渲染列表行；键取每个元素的字段，空数组显示 emptyText |
progress | value / bind | 进度条，取值 0–1 |
divider | — | 分隔线 |
4. 设置区
设置区常驻在附加区，控件通过 bind 直接读写 state 键，改动立即持久化；HTTP 动作的 {{key}} 模板会读到最新值。
| type | 字段 | 说明 |
|---|---|---|
picker | label、bind、options[] | 下拉单选，选项为字符串数组 |
stepper | label、bind、min · 0、max · 100、step · 1 | 数字步进器 |
toggle | label、bind | 布尔开关 |
6. 动作
| type | 字段 | 行为 |
|---|---|---|
http | method · GET、url、headers{}、body、extract{} | 发请求（15 秒超时）；url / headers / body 支持 {{key}} 模板；extract 把响应按 JSONPath 写入 state |
set | values{} | 就地写入若干 state 键值 |
copy | text | 渲染模板后复制到剪贴板 |
open-url | url | 渲染模板后用系统浏览器打开 · 仅 http/https |
navigate | page | 页内导航到 pages 中的另一页，头部出现返回箭头 |
JSONPath：extract 的值是点路径加数组下标，例如 $.rates.CNY、$.list[1].n；取不到时该键写入 null。
7. 运行时语义
- 默认刷新动作：第一个
http动作（没有则第一个动作）。打开插件且loadOnStart≠false时执行一次；refreshInterval≥ 5 秒则按周期重复。 - 模板变量：
{{key}}会替换成 state 当前值（数字、布尔直接转文字）；state 中不存在的键原样保留，方便分步调试。 - 状态持久化：state 首次修改后写入本机 UserDefaults（键
plugin.state.<id>），重启 App 保留；插件管理里可重置回初始值。 - 反馈：请求进行中显示玻璃加载态；失败在头部下方给出提示文案，成功后自动清除。
8. 安装与管理
- 存放位置：
~/Library/Application Support/MaciWatch/plugins/<id>.json，也可以手动放文件，插件管理会自动扫描。 - 导入方式：插件管理 → 右上角导入 → 选择 JSON 文件，或粘贴清单文本；文件名不影响 id，落盘以清单内
id为准。 - 覆盖与卸载：同 id 重复导入即覆盖重装；插件管理支持删除与在蜂窝中隐藏（显隐只记「隐藏」名单）。
- 内置示例：首次启动自动种入「汇率」与「一言」两个示例插件，可随意修改或删除。
9. 安全与校验
- id 白名单：仅字母/数字开头 +
A-Z a-z 0-9 . _ -，长度 ≤ 100，拒绝路径穿越（如../evil）与纯符号。 - 仅限 Web 协议：HTTP 与
open-url只放行http/https，file://等本地协议一律拒绝。 - 图标校验：清单内全部 SF Symbol 引用（含头部、trailing、body、底钮）都必须在当前系统符号集内，否则拒绝导入。
- 数据边界：state 只存本机，不上传；请求超时 15 秒，失败不影响其他插件。
Examples
示例插件
两个内置示例的完整清单。可以下载后直接导入，或载入生成器改造。
汇率 · demo.exchange
GET 请求 + JSONPath 提取：picker 切换基准货币，metric 主显汇率，trailing 刷新按钮与底部主按钮共用同一个动作。
查看清单
一言 · demo.hitokoto
极简结构：无设置区，渐变背景 + hero 文本，打开即从 hitokoto API 拉取一句话，点「换一句」重新请求。