clearlove2.1
1# 插件开发文档
2
3ClearLove 表白墙采用 **钩子（Hook）模式** 插件系统。插件以 zip 包上传，
4解压后安装于 `data/plugins/<插件名>/`，可在后台 **插件管理** 中启用 / 禁用 / 卸载。
5
6## 1. 插件包结构
7
8```
9my-plugin.zip
10└── plugin.json # 插件清单（必须）
11```
12
13（可附带自定义资源文件，服务端会一并解压到插件目录。）
14
15## 2. plugin.json 清单
16
17```json
18{
19 "name": "anti-ad",
20 "version": "1.0.0",
21 "author": "夏日之瓜",
22 "description": "自动过滤广告关键词并推送到审核机器人",
23 "hooks": [
24 {
25 "hook": "content_filter",
26 "type": "filter",
27 "match": "(加微信|代购|刷单)",
28 "replace": "***"
29 },
30 {
31 "hook": "post_created",
32 "type": "http",
33 "url": "https://your-bot.example.com/webhook"
34 },
35 {
36 "hook": "footer_html",
37 "type": "html",
38 "html": "<div style=\"text-align:center;font-size:12px\">由 anti-ad 插件提供支持</div>"
39 }
40 ]
41}
42```
43
44| 字段 | 说明 |
45|---|---|
46| name | 插件唯一名（安装目录名，必填） |
47| version / author / description | 展示信息 |
48| hooks[].hook | 钩子名（见下表） |
49| hooks[].type | `html` / `filter` / `http` 三种类型 |
50
51## 3. 钩子一览
52
53### 3.1 html 类型 —— 页面注入
54
55| 钩子名 | 注入位置 |
56|---|---|
57| `header_html` | `<body>` 顶部（全站，含后台） |
58| `footer_html` | 页脚区域 |
59
60`html` 字段为注入的 HTML 片段（**不会**被模板转义，请勿注入脚本恶意代码）。
61
62### 3.2 filter 类型 —— 内容过滤
63
64| 钩子名 | 触发时机 |
65|---|---|
66| `content_filter` | 发帖（前台与 API）时对内容执行正则替换 |
67
68- `match`：Go 正则表达式；`replace`：替换文本（支持 `$1` 分组引用）。
69- 多条规则按插件加载顺序依次执行，规则缓存 30 秒。
70
71### 3.3 http 类型 —— 事件 Webhook
72
73| 钩子名 | 触发时机 | 载荷字段 |
74|---|---|---|
75| `post_created` | 帖子发布成功 | post_id, nickname, content |
76| `comment_created` | 评论发布成功 | post_id, content |
77| `report_created` | 收到举报 | post_id, reason |
78
79服务端以 `POST` 方式异步请求 `url`，`Content-Type: application/json`，
80请求头带 `X-ClearLove-Event: <钩子名>`，载荷中额外包含 `event` 与 `time` 字段。
81超时 10 秒，失败仅记录日志、不影响主流程。
82
83## 4. 示例：投稿同步到企业微信机器人
84
85```json
86{
87 "name": "wecom-notify",
88 "version": "1.0.0",
89 "hooks": [
90 { "hook": "post_created", "type": "http", "url": "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxx" }
91 ]
92}
93```
94
95## 5. 安装与管理
96
971. 后台 → 插件管理 → 选择 zip → 上传并安装；
982. 在列表中「启用」，即刻生效（无需重启，规则缓存最长 30 秒）；
993. 「禁用」暂停全部钩子，「卸载」删除插件目录并从启用列表移除。
100
101## 6. 限制与安全
102
103- 单个 zip 不超过 50MB；路径穿越（`../`）文件会被忽略。
104- Webhook 为异步执行，不会阻塞用户请求；请勿在钩子中依赖同步返回。
105- 插件为「配置式」钩子，不加载第三方二进制代码，天然隔离运行风险。