插件与主题开发文档

面向 ClearLove 表白墙 2.0 的扩展开发者。写好作品后，在本社区注册账号即可发布，全球任意 ClearLove 站点都能一键安装你的作品。

一、发布流程

1. 准备好插件/主题的 zip 包（结构见下文）
2. 在插件社区注册开发者账号（邮箱验证）
3. 进入插件市场，点击「发布插件」，上传 zip 并填写图标与简介
4. 发布成功后立即上架，站长可在自己的表白墙后台「插件管理 → 插件市场」一键安装

更新作品：使用相同 slug 再次上传即可，版本号自动更新、历史下载量保留。

二、插件包结构（manifest.json）

my-plugin.zip
├── manifest.json      # 必需
├── main.js            # 插件逻辑（纯资源插件可省略）
└── assets/            # 静态资源，安装后经 /plugins/<slug>/assets/... 访问

{
  "slug": "my-plugin",        // 全局唯一：小写字母数字中划线
  "name": "我的插件",
  "version": "1.0.0",
  "author": "你的昵称",
  "description": "功能简介",
  "config": [                  // 可选：后台自动渲染的配置表单
    { "key": "apikey", "label": "API 密钥", "type": "text", "default": "" },
    { "key": "count",  "label": "数量",     "type": "number", "default": 10 },
    { "key": "switch", "label": "开关",     "type": "switch", "default": true }
  ]
}

三、插件 JavaScript API

main.js 通过全局对象 clearlove 获得宿主能力：

clearlove.site                    // { name, version } 站点信息
clearlove.config                  // manifest 声明的配置（含默认值）
clearlove.on(event, fn)           // 监听站点事件
clearlove.route(method, path, fn) // 注册路由（挂载 /plugins/<slug>/ 下）
  // 回调 ctx: { query, body, ip }；返回对象=JSON，返回字符串=HTML
clearlove.injectHead(html)        // 注入前台 <head>
clearlove.injectFooter(html)      // 注入前台页尾
clearlove.panel(html)             // 注入站长后台面板
clearlove.kv.get(k) / set(k, v)   // 插件专属持久化 KV 存储
clearlove.fetch(url, opts)        // 外部 HTTP 请求 => { status, body }
clearlove.log(...)                // 服务端控制台日志

四、可监听事件

事件	触发时机	data 字段
`postCreate`	新帖发布	`id, content, nickname, user_id, topic`
`postDelete`	帖子删除	`id`
`commentCreate`	新评论	`id, post_id, content, nickname, user_id`
`userRegister`	用户注册	`id, email, nickname`
`reportCreate`	用户举报	`id, post_id, reason`

最小示例 —— 监听新帖并推送外部通知：

clearlove.on("postCreate", function(d){
  clearlove.log("新帖:", d.id)
  clearlove.kv.set("last_post", d.id)
  if (clearlove.config.webhook) {
    clearlove.fetch(clearlove.config.webhook, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ text: "新帖: " + d.content.slice(0, 50) })
    })
  }
})

五、主题开发（theme.json）

主题包更简单：根目录放 theme.json 与可选的页面文件。最小主题只有两个文件：

my-theme.zip
├── theme.json     # 必需
├── style.css      # 注入全站的附加样式
└── index.html     # 可选：覆盖前台页面（index/post/publish/login/profile）

{
  "slug": "my-theme",
  "name": "我的主题",
  "version": "1.0.0",
  "author": "你的昵称",
  "description": "主题简介"
}

一份 style.css 即可换肤，直接覆盖内置 CSS 变量：

:root{
  --primary:#4f7cff;        /* 主色 */
  --primary-dark:#3a62d9;
  --primary-light:#e9efff;
  --bg:#f2f5ff; --line:#dfe7ff;
}
body{background:linear-gradient(160deg,#eef2ff,#f8faff)!important}

主题类型由包内是否含 theme.json 自动判定，上传时无需手动选择。

六、社区规范

· 插件 slug 全局唯一，先到先得；建议加作者前缀避免冲突（如 alice-tools）
· 禁止上传包含恶意代码、后门、垃圾广告的作品，违规将被下架并封禁账号
· 包大小不超过 50MB；请如实填写简介，方便站长甄选
· 更新作品请保持 slug 不变，避免用户重复安装产生多份副本