Manifest

目录结构

.moss/plugins/my-plugin/
├── manifest.json      插件元数据和配置
├── main.bundle.js     构建后的 JavaScript 入口
├── config.json        运行时配置（覆盖默认值）
└── icon.svg           插件图标（可选）

插件位于每个项目的 .moss/plugins// 目录下。

必填字段

字段类型说明
namestring插件标识符（用作文件夹名）
versionsemver插件版本
descriptionstring简短描述
authorstring作者名称
entrystringJavaScript 包文件名
capabilitiesstring[]钩子类型："process"、"generate"、"enhance"、"deploy"、"syndicate"
global_namestringJavaScript 全局对象名（如 "MyPlugin"）

可选字段

字段类型说明
domainstring主要服务域名（如 "matters.town"）
iconstring图标文件名（依次回退到 icon.svg、icon.png、logo.svg、logo.png）
display_namestring设置界面中显示的名称

示例清单

{
  "name": "my-deploy",
  "version": "1.0.0",
  "description": "Deploy to My Hosting",
  "author": "Your Name",
  "entry": "main.bundle.js",
  "capabilities": ["deploy"],
  "global_name": "MyDeployPlugin",
  "domain": "myhost.example",
  "icon": "icon.svg",
  "config": {
    "auto_deploy": false,
    "region": "us-east"
  },
  "config_schema": {
    "auto_deploy": "boolean",
    "region": "string"
  },
  "config_labels": {
    "auto_deploy": "Auto Deploy",
    "region": "Server Region"
  },
  "config_descriptions": {
    "auto_deploy": "Automatically deploy after each build",
    "region": "Hosting region for your site"
  }
}

配置

默认值和类型声明

config 设置默认值。config_schema 声明每个字段的类型（"boolean"、"number"、"string"）。moss 据此自动生成设置界面。

清单字段用途
config默认值
config_schema字段类型，用于 UI 生成
config_labels设置界面中的显示标签
config_descriptions设置界面中的帮助说明
config_placeholders输入框的占位文字

配置优先级

插件配置按以下优先级解析：

  1. .moss/plugins//config.json — 最高优先
  2. .moss/plugins//config.toml
  3. .moss/config.toml 中的 [plugins.] 节 — 最低

配置验证

config_verify 在用户保存配置后探测一个端点进行验证：

"config_verify": {
  "api_key": {
    "probe": "https://api.example.com/verify/{value}",
    "expect": "ok"
  }
}

替换为用户输入的值。探测请求发出后检查响应。

Schema 贡献

插件可以通过 contributes.frontmatter.fields 添加 frontmatter 字段：

"contributes": {
  "frontmatter": {
    "fields": {
      "syndicated_url": {
        "type": "string",
        "description": "URL where this article was syndicated"
      }
    }
  }
}

贡献的字段在运行时合并到活动 schema 中，并出现在编辑器中。

moss-api SDK

moss-api 包提供插件开发用的类型和工具函数。

npm install moss-api

类型

导出说明
DeployContext传给 deploy 钩子的上下文
SyndicateContext传给 syndicate 钩子的上下文
EnhanceContext传给 enhance 钩子的上下文
HookResult所有钩子的返回类型
PluginManifest清单结构定义

工具函数

导出说明
reportProgress在界面中显示进度信息
reportError报告非致命错误
log / warn / error结构化日志输出

浏览器

导出说明
openBrowser在系统浏览器中打开 URL
closeBrowser关闭之前打开的浏览器标签页

构建

用 esbuild 打包为 IIFE 格式：

esbuild src/main.ts --bundle --format=iife --global-name=MyPlugin --outfile=dist/main.bundle.js

测试

使用 vitest 配合 moss-api 提供的 mock Tauri 环境：

import { describe, it, expect } from 'vitest';

describe('deploy', () => {
  it('returns success', async () => {
    const result = await MyPlugin.deploy(mockContext);
    expect(result.success).toBe(true);
  });
});

npx vitest run
Published with moss