From cd13335b4aedc0db16300c21f7c6dc2b81509917 Mon Sep 17 00:00:00 2001
From: mediabot-pt <295750538+mediabot-pt@users.noreply.github.com>
Date: Wed, 1 Jul 2026 14:39:03 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20API.md=E6=96=B0=E5=A2=9EGroovy=E8=84=9A?=
 =?UTF-8?q?=E6=9C=AC=E9=9B=86=E6=88=90=E7=AB=A0=E8=8A=82=EF=BC=8C=E5=90=AB?=
 =?UTF-8?q?mediabot=E5=AF=B9=E6=8E=A5=E6=B5=81=E7=A8=8B?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/API.md | 59 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 59 insertions(+)

diff --git a/docs/API.md b/docs/API.md
index 7ad7b27..73da596 100644
--- a/docs/API.md
+++ b/docs/API.md
@@ -147,6 +147,7 @@ curl -H "If-None-Match: a1b2c3d4..." http://par:9012/api/v1/manifest
         "status": "active",
         "latestVersion": "1.2.0",
         "configHash": "a1b2c3d4...",
+        "hasScript": false,
         "updatedAt": "2026-06-29T14:00:00"
       }
     ]
@@ -254,6 +255,64 @@ curl -H "If-None-Match: a1b2c3d4..." http://par:9012/api/v1/manifest
 }
 ```
 
+### 2.6 Groovy 适配脚本
+
+| 方法 | 路径 | 认证 | 说明 |
+|------|------|------|------|
+| GET | `/api/v1/configs/{siteId}/{version}/script` | 无 | 下载 Groovy 脚本 |
+
+#### GET /api/v1/configs/{siteId}/{version}/script
+
+返回 `Content-Type: text/plain;charset=UTF-8`，原始 Groovy 脚本内容。
+
+```bash
+# 下载 mteam v1 的 Groovy 脚本
+curl http://par:9012/api/v1/configs/mteam/1/script
+```
+
+#### 集成流程
+
+```
+mediabot 启动
+  │
+  ▼
+GET /api/v1/manifest                     ← 获取站点列表
+  │  { "siteId":"mteam","latestVersion":"1","hasScript":true }
+  │
+  ├─ hasScript == true
+  │   └─ GET /api/v1/configs/{siteId}/{latestVersion}/script    ← 下载 Groovy 脚本
+  │      → 编译并执行 parse/sync/search/sign 方法
+  │
+  └─ hasScript == false
+      └─ GET /api/v1/configs/{siteId}/{latestVersion}            ← 下载 JSON 配置
+         → 按 JSON 配置中的选择器规则执行
+```
+
+#### Manifest 新增字段
+
+```json
+{
+  "siteId": "mteam",
+  "latestVersion": "1",
+  "hasScript": true,       // 新增：是否有 Groovy 脚本
+  "configHash": "abc...",  // JSON 配置 hash（可能为 null）
+  "updatedAt": "2026-07-01T10:00:00"
+}
+```
+
+#### 脚本入口
+
+Groovy 脚本定义以下方法，mediabot 按需调用：
+
+| 方法 | 参数 | 返回值 | 说明 |
+|------|------|--------|------|
+| `parse(content, url)` | content=页面内容, url=访问URL | Map{pageName,fields,extracted} | PAR 校验用（mediabot 不调） |
+| `sync(ctx)` | ctx=PluginContext | Map{upload,download,bonus,seeding,...} | 同步站点数据 |
+| `search(ctx, params)` | ctx=PluginContext, params={keyword,page} | List[Map] | 搜索种子 |
+| `sign(ctx)` | ctx=PluginContext | Map{success,message} | 签到 |
+
+> `PluginContext` 由 mediabot 提供，包含 `site.auth`（认证信息）、`siteUrl`、`httpClient` 等。
+
 ---
 
 ## 3. 数据结构