### Key Logging Points Examples

Source: https://github.com/fish2018/pansou/blob/main/plugin/hdr4k/设计文档.md

Illustrates common logging scenarios, such as starting a search, completing a search, recording errors, and logging cache status.

```go
// 搜索开始
log.Info("开始搜索", "keyword", keyword, "plugin", "hdr4k")

// 性能统计
log.Info("搜索完成", "keyword", keyword, "结果数", len(results), "耗时", duration)

// 错误记录
log.Error("详情页获取失败", "postID", postID, "error", err)

// 缓存状态
log.Debug("缓存命中", "key", cacheKey, "type", "detail_page")
```

--------------------------------

### Plugin Web Access Examples

Source: https://github.com/fish2018/pansou/blob/main/docs/插件开发指南.md

Illustrates how to access the web endpoints registered by plugins, including examples for QQPD and custom plugins.

```bash
# QQPD 插件管理页面
GET  http://localhost:8888/qqpd/user123

# QQPD 插件配置接口
POST http://localhost:8888/qqpd/user123
Content-Type: application/json
{
  "action": "set_channels",
  "channels": ["pd97631607", "kuake12345"]
}

# 自定义插件接口
GET  http://localhost:8888/myplugin/status
POST http://localhost:8888/myplugin/config
GET  http://localhost:8888/myplugin/resource123
```

--------------------------------

### Pansou Search API GET Request Example (With Auth)

Source: https://github.com/fish2018/pansou/blob/main/README.md

Example of a GET request to the search API when authentication is enabled. Requires an 'Authorization' header with a Bearer token.

```bash
curl "http://localhost:8888/api/search?kw=速度与激情&res=merge" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
```

--------------------------------

### Download Link Format Examples

Source: https://github.com/fish2018/pansou/blob/main/plugin/wanou/json结构分析.md

Examples of how download links are formatted for different cloud storage providers.

```text
百度网盘: https://pan.baidu.com/s/13milLJZV5_7DCzGDQu-fcA?pwd=8888
夸克网盘: https://pan.quark.cn/s/0fe46ed6eefc
UC网盘:   https://drive.uc.cn/s/d83caf5d4fb74
```

--------------------------------

### Bixin Plugin Initialization Example

Source: https://github.com/fish2018/pansou/blob/main/plugin/bixin/json结构分析.md

Example of how to initialize the Bixin plugin, setting its name, priority, and filter behavior. This implementation skips Service layer filtering.

```go
// 基于pan666插件进行修改
func NewBixinAsyncPlugin() *BixinAsyncPlugin {
    return &BixinAsyncPlugin{
        BaseAsyncPlugin: plugin.NewBaseAsyncPluginWithFilter("bixin", 3, true), // 跳过Service层过滤
        retries:         MaxRetries,
    }
}

// 主要修改点：
// 1. 更改API URL: "https://www.bixbiy.com/api/discussions"
// 2. 更改插件名称: "bixin"
// 3. 简化链接提取：只处理移动云盘（caiyun.139.com）
// 4. 简化密码匹配：只匹配"访问码"和"密码"关键词
// 5. 保持相同的HTML解析逻辑

```

--------------------------------

### Bixin API Search Request Example

Source: https://github.com/fish2018/pansou/blob/main/plugin/bixin/json结构分析.md

Example of how to make a search request to the Bixin API, including necessary headers.

```bash
curl "https://www.bixbiy.com/api/discussions?filter[q]=凡人修仙传&page[limit]=3&include=mostRelevantPost" \
  -H "Referer: https://www.bixbiy.com/" \
  -H "User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"
```

--------------------------------

### Quarksoo Search Request Example

Source: https://github.com/fish2018/pansou/blob/main/plugin/quarksoo/html结构分析.md

Example of how to make a search request to the Quarksoo API, including necessary headers.

```bash
curl "https://quarksoo.cc/search.php?q=华山论剑" \
  -H "Referer: https://quarksoo.cc/" \
  -H "User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"
```

--------------------------------

### Example of Cloud Drive Tags in Go

Source: https://github.com/fish2018/pansou/blob/main/plugin/discourse/json结构分析.md

An example slice of strings in Go representing tags associated with cloud drive resources, such as '夸克网盘' (Quark Drive) and '百度网盘' (Baidu Drive).

```go
tags := []string{"夸克网盘", "百度网盘", "动漫"}
```

--------------------------------

### Example Search Result Ranking Scenario

Source: https://github.com/fish2018/pansou/blob/main/docs/系统开发设计文档.md

Provides a practical example demonstrating how different combinations of plugin level, time, and keywords result in varying total scores and final rankings. This illustrates the algorithm's application.

```plaintext
场景 | 插件等级 | 时间 | 关键词 | 总分 | 排序
------|---------|------|--------|------|------
等级1 + 1天内 + "合集" | 1000 | 500 | 420 | **1920** | 🥇 第1
等级1 + 1天内 + "系列" | 1000 | 500 | 350 | **1850** | 🥈 第2
等级1 + 1月内 + "合集" | 1000 | 200 | 420 | **1620** | 🥉 第3
等级2 + 1天内 + "合集" | 500 | 500 | 420 | **1420** | 第4
等级1 + 1天内 + 无关键词 | 1000 | 500 | 0 | **1500** | 第5
```

--------------------------------

### Example Scraping Workflow

Source: https://github.com/fish2018/pansou/blob/main/plugin/kkmao/html结构分析.md

An example workflow demonstrating the process of searching for a keyword, parsing search results, visiting detail pages, and extracting Quark Drive links.

```text
关键词: 物
↓
搜索页: https://www.kuakemao.com/?s=物
  - 解析 article.excerpt
  - 取得标题「某种物质 (2024)...」、详情链接 https://www.kuakemao.com/653.html
↓
详情页: https://www.kuakemao.com/653.html
  - 在 .article-content 中找到 <a href="https://pan.quark.cn/s/631243a6189a">
↓
结果:
  UniqueID: kkmao-653
  Title: 某种物质 (2024) 夸克网盘 法国 恐怖 4K 豆瓣7.5
  Content: 搜索结果页的摘要
  Links: [{Type:"quark", URL:"https://pan.quark.cn/s/631243a6189a", Password:""}]
  Tags: ["电影"]
  Datetime: 2025-11-26
```

--------------------------------

### API Request Example

Source: https://github.com/fish2018/pansou/blob/main/plugin/nyaa/html结构分析.md

Example of how to make a search request to the API using curl. Specify the search keyword and the plugins to use.

```bash
curl "http://localhost:8888/api/search?kw=神墓&plugins=nyaa"
```

--------------------------------

### Plugin Management Page Initialization

Source: https://github.com/fish2018/pansou/blob/main/plugin/gying/html结构分析.md

The initial setup logic for the management page frontend, which includes updating status, loading configuration, and starting periodic status polling.

```javascript
window.onload = function() {
    updateStatus();
    loadConfig();
    startStatusPolling();
};

// startStatusPolling() calls updateStatus() every 5 seconds.
```

--------------------------------

### API Call Example

Source: https://github.com/fish2018/pansou/blob/main/plugin/wanou/json结构分析.md

Example of how to make a search request to the Wanou API.

```APIDOC
## API Call Example

### Search Request
This shows a sample GET request to search for "凡人修仙传".

```
Search Request: https://woog.nxog.eu.org/api.php/provide/vod?ac=detail&wd=%E5%87%A1%E4%BA%BA%E4%BF%AE%E4%BB%99%E4%BC%A0
Request Method: GET
Response Format: application/json
Encoding Format: UTF-8
```
```

--------------------------------

### Huban Download Link Parsing Example

Source: https://github.com/fish2018/pansou/blob/main/plugin/huban/json结构分析.md

This example demonstrates the complex download link format used by the Huban API, including separators for different cloud providers and individual links. It shows the raw API fields and the expected parsed output.

```text
原始格式:
"vod_down_from": "UCWP$$$KKWP$$$ALWP$$$bdWP$$$123WP$$$115WP"
"vod_down_url": "小虎斑$https://drive.uc.cn/s/3544ba9f8ac64#凡人修仙传$https://drive.uc.cn/s/3c3b890905a14?public=1#$$$小虎斑$https://pan.quark.cn/s/409afef6d77c#凡人修仙传$https://pan.quark.cn/s/c6a8281edf6b#$$$小虎斑$#凡人修仙传$https://www.alipan.com/s/7Ks9ccmdNcv#凡人修仙传$https://www.alipan.com/s/7Ks9ccmdNcv#$$$小虎斑$#凡人修仙传$https://pan.baidu.com/s/1nSz0-zft_h0Vg7rRhyJvxg?pwd=39qu#$$$小虎斑$#凡人修仙传$https://www.123912.com/s/gXCjTd-pVObv#$$$小虎斑$#凡人修仙传$https://115cdn.com/s/swhqwhw36c8?password=bc57#凡人修仙传$https://115cdn.com/s/swhqwhw36c8?password=bc57#"

解析后:
UC网盘: 
  - https://drive.uc.cn/s/3544ba9f8ac64 (凡人修仙传)
  - https://drive.uc.cn/s/3c3b890905a14?public=1
夸克网盘:
  - https://pan.quark.cn/s/409afef6d77c (凡人修仙传)
  - https://pan.quark.cn/s/c6a8281edf6b
阿里云盘:
  - https://www.alipan.com/s/7Ks9ccmdNcv (凡人修仙传, 重复)
百度网盘:
  - https://pan.baidu.com/s/1nSz0-zft_h0Vg7rRhyJvxg?pwd=39qu (凡人修仙传)
123网盘:
  - https://www.123912.com/s/gXCjTd-pVObv (凡人修仙传)
115网盘:
  - https://115cdn.com/s/swhqwhw36c8?password=bc57 (凡人修仙传, 重复)
```

--------------------------------

### ypfxw Download Link Example

Source: https://github.com/fish2018/pansou/blob/main/plugin/ypfxw/html结构分析.md

An example of how a download link might appear within the detail page content, often prefixed with '链接：'.

```text
链接：https://pan.quark.cn/s/08211da2cb83
```

--------------------------------

### ahhhhfs Download Link Format Examples

Source: https://github.com/fish2018/pansou/blob/main/plugin/ahhhhfs/html结构分析.md

Examples of how download links are formatted within the post content, including links to various cloud storage services and extraction codes.

```HTML
<p>
    学习地址：
    <a title="..." 
       href="https://pan.quark.cn/s/c16a5ae18ea0" 
       target="_blank" 
       rel="nofollow noopener noreferrer">夸克</a>
</p>

或者

<p>
    下载地址：
    <a href="https://pan.baidu.com/s/xxxxx" 
       target="_blank" 
       rel="nofollow noopener noreferrer">百度网盘</a>
    提取码: xxxx
</p>

或者多个网盘链接：
<p>
    阿里云盘：<a href="...">链接</a><br>
    夸克网盘：<a href="...">链接</a><br>
    百度网盘：<a href="...">链接</a> 提取码: xxxx
</p>

提取要素:
- 网盘链接: .post-content 中包含网盘域名的 a 标签的 href 属性
- 提取码/密码: 链接附近的文本内容，可能包含 "提取码"、"密码"、"pwd" 等关键词
```

--------------------------------

### Pansou Search API POST Request Example (With Auth)

Source: https://github.com/fish2018/pansou/blob/main/README.md

Example of a POST request to the search API when authentication is enabled. Requires an 'Authorization' header with a Bearer token.

```bash
curl -X POST http://localhost:8888/api/search \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -d '{
    "kw": "速度与激情",
    "res": "merge"
  }'
```

--------------------------------

### Pansou Search API GET Request Example (No Auth)

Source: https://github.com/fish2018/pansou/blob/main/README.md

Example of a GET request to the search API without authentication. Parameters are appended to the URL.

```bash
curl "http://localhost:8888/api/search?kw=速度与激情&res=merge&src=tg"
```

--------------------------------

### Start Gying Service

Source: https://github.com/fish2018/pansou/blob/main/plugin/gying/README.md

Run the Gying plugin service. You can either run it directly using 'go run' or compile it into an executable first.

```bash
cd /Users/macbookpro/Desktop/fish2018/pansou
go run main.go

# 或者编译后运行
go build -o pansou main.go
./pansou
```

--------------------------------

### Quarksoo Search Request Example

Source: https://github.com/fish2018/pansou/blob/main/plugin/quarksoo/html结构分析.md

Example of a GET request to search for a keyword on Quarksoo.

```http
GET https://quarksoo.cc/search.php?q=华山论剑
```

--------------------------------

### Wanou API Search Request Example

Source: https://github.com/fish2018/pansou/blob/main/plugin/wanou/json结构分析.md

Example of an HTTP GET request to search for video details using the Wanou API.

```text
搜索请求: https://woog.nxog.eu.org/api.php/provide/vod?ac=detail&wd=%E5%87%A1%E4%BA%BA%E4%BF%AE%E4%BB%99%E4%BC%A0
请求方法: GET
响应格式: application/json
编码格式: UTF-8
```

--------------------------------

### Miaoso API Request Example

Source: https://github.com/fish2018/pansou/blob/main/plugin/miaoso/json结构分析.md

Example of an HTTP GET request to the Miaoso API for searching content. Ensure keywords are URL-encoded.

```http
GET /api/secendsearch?name=%E5%87%A1%E4%BA%BA%E4%BF%AE%E4%BB%99%E4%BC%A0&pageNo=1 HTTP/1.1
Host: miaosou.fun
Referer: https://miaosou.fun/info?searchKey=%E5%87%A1%E4%BA%BA%E4%BF%AE%E4%BB%99%E4%BC%A0
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/138.0.0.0 Safari/537.36
```

--------------------------------

### Extension Parameters Example (JSON)

Source: https://github.com/fish2018/pansou/blob/main/docs/系统开发设计文档.md

Illustrates the structure of the 'ext' parameter, used for passing plugin-specific options in a JSON format.

```json
{
  "title_en": "English Title",
  "is_all": true,
  "year": 2023
}
```

--------------------------------

### NSGame API Request Example

Source: https://github.com/fish2018/pansou/blob/main/plugin/nsgame/json结构分析.md

Example GET request to the NSGame API for searching game resources. Ensure queryName is URL encoded.

```http
GET https://nsthwj.com/thwj/game/query?pageNum=1&pageSize=100&type=&queryName=%E9%A9%AC%E9%87%8C%E5%A5%A5
```

--------------------------------

### 插件初始化与注册

Source: https://github.com/fish2018/pansou/blob/main/plugin/panta/panta插件设计文档.md

插件通过`init`函数自动注册到全局插件管理器。`NewPantaPlugin`函数负责创建优化的HTTP客户端、启动后台任务（缓存清理、并发调整）并返回插件实例。

```go
func init() {
    plugin.RegisterGlobalPlugin(NewPantaPlugin())
}

func NewPantaPlugin() *PantaPlugin {
    // 创建优化的HTTP传输层
    transport := &http.Transport{...}
    
    // 创建HTTP客户端
    client := &http.Client{...}
    
    // 启动定期清理缓存的goroutine
    go startCacheCleaner()
    
    // 创建插件实例
    plugin := &PantaPlugin{...}
    
    // 启动自适应并发控制
    go plugin.startConcurrencyAdjuster()
    
    return plugin
}
```

--------------------------------

### Discourse Detail API Request Example

Source: https://github.com/fish2018/pansou/blob/main/plugin/discourse/json结构分析.md

Example GET request to the Discourse detail API to fetch full post information, including `link_counts`. The `track_visit` and `forceLoad` parameters are included.

```http
GET https://linux.do/t/1067663.json?track_visit=true&forceLoad=true
```

--------------------------------

### Registering a Plugin with `main.go`

Source: https://context7.com/fish2018/pansou/llms.txt

Import the plugin package in `main.go` to trigger its `init()` function for automatic registration. Ensure the import path is correct.

```go
// main.go
import (
    _ "pansou/plugin/myplugin" // 触发 init() 完成自动注册
)
```

--------------------------------

### Write Unit Tests for Plugins in Go

Source: https://github.com/fish2018/pansou/blob/main/docs/插件开发指南.md

Provides an example of a unit test for a plugin's `Search` method using Go's testing package. It initializes the plugin, calls the `Search` method, and asserts the results and error.

```go
func TestMyPlugin_Search(t *testing.T) {
    plugin := &MyPlugin{
        BaseAsyncPlugin: plugin.NewBaseAsyncPlugin("test", 3),
    }
    
    results, err := plugin.Search("测试关键词", nil)
    assert.NoError(t, err)
    assert.NotEmpty(t, results)
}
```

--------------------------------

### Discourse Topic Detail API Request Example

Source: https://github.com/fish2018/pansou/blob/main/plugin/discourse/json结构分析.md

Example of a GET request to the Discourse API to fetch detailed information about a specific topic. Includes query parameters for tracking visits and forcing load.

```http
GET https://linux.do/t/{topic_id}.json?track_visit=true&forceLoad=true
```

--------------------------------

### Discourse Search API Request Example

Source: https://github.com/fish2018/pansou/blob/main/plugin/discourse/json结构分析.md

Example GET request to the Discourse search API. Ensure the query parameter 'q' is URL-encoded and includes keywords and filters like '#resource:cloud-asset in:title'.

```http
GET https://linux.do/search.json?q={keyword}%20%23resource%3Acloud-asset%20in%3Atitle&page={page}
```

--------------------------------

### Gying API: Get Status Response (Not Logged In)

Source: https://github.com/fish2018/pansou/blob/main/plugin/gying/README.md

Example JSON response when a Gying user is not logged in.

```json
{
  "success": true,
  "message": "获取成功",
  "data": {
    "hash": "abc123...",
    "logged_in": false,
    "status": "pending"
  }
}
```

--------------------------------

### Discourse Search API Request Example

Source: https://github.com/fish2018/pansou/blob/main/plugin/discourse/json结构分析.md

Example GET request to the Discourse search API to find posts related to cloud assets. The response includes a simplified list of posts with basic information and blurbs.

```http
GET https://linux.do/search.json?q=%E9%81%AE%E5%A4%A9%20%23resource%3Acloud-asset%20in%3Atitle&page=1
```

--------------------------------

### Gying API: Get Status Response (Logged In)

Source: https://github.com/fish2018/pansou/blob/main/plugin/gying/README.md

Example JSON response when a Gying user is successfully logged in and active.

```json
{
  "success": true,
  "message": "获取成功",
  "data": {
    "hash": "abc123...",
    "logged_in": true,
    "status": "active",
    "username": "pansou",
    "login_time": "2025-10-28 12:00:00",
    "expire_time": "2026-02-26 12:00:00",
    "expires_in_days": 121
  }
}
```

--------------------------------

### API Request Examples with and without Authentication

Source: https://github.com/fish2018/pansou/blob/main/README.md

Demonstrates how to make API requests to the search endpoint, showing the difference between requests with and without JWT authentication.

```bash
# 未启用认证时
curl -X POST http://localhost:8888/api/search \
  -H "Content-Type: application/json" \
  -d '{"kw":"速度与激情"}'

# 启用认证时
curl -X POST http://localhost:8888/api/search \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGc..." \
  -d '{"kw":"速度与激情"}'

```

--------------------------------

### Get Status Response (Not Logged In)

Source: https://github.com/fish2018/pansou/blob/main/plugin/weibo/README.md

Example JSON response when the account is not logged in. Includes a base64 encoded QR code for login.

```json
{
  "success": true,
  "message": "获取成功",
  "data": {
    "hash": "abc123...",
    "logged_in": false,
    "status": "pending",
    "username_masked": "",
    "weibo_users": [],
    "user_count": 0,
    "qrcode_base64": "data:image/png;base64,iVBORw0KGgo..."
  }
}
```

--------------------------------

### Start QQPD Service

Source: https://github.com/fish2018/pansou/blob/main/plugin/qqpd/README.md

Run the PanSou service with the QQPD plugin enabled. This can be done by setting the ENABLED_PLUGINS environment variable or by compiling the project first.

```bash
cd /Users/macbookpro/Desktop/fish2018/pansou
ENABLED_PLUGINS=qqpd go run main.go
```

```bash
go build -o pansou main.go
ENABLED_PLUGINS=qqpd ./pansou
```

--------------------------------

### Global Plugin Registration Mechanism

Source: https://github.com/fish2018/pansou/blob/main/docs/系统开发设计文档.md

Illustrates the global plugin registry and how plugins are automatically registered using the init() function. This ensures plugins are available when the system starts.

```go
// 全局插件注册表（plugin/plugin.go）
var globalRegistry = make(map[string]AsyncSearchPlugin)

// 插件通过init()函数自动注册
func init() {
    p := &MyPlugin{
        BaseAsyncPlugin: plugin.NewBaseAsyncPlugin("myplugin", 3),
    }
    plugin.RegisterGlobalPlugin(p)
}
```

--------------------------------

### Gying API: Get Config Response

Source: https://github.com/fish2018/pansou/blob/main/plugin/gying/README.md

Example JSON response when retrieving the current Gying site configuration (base URL).

```json
{
  "success": true,
  "message": "获取成功",
  "data": {
    "base_url": "https://www.gying.net"
  }
}
```

--------------------------------

### Go Package Naming Convention

Source: https://github.com/fish2018/pansou/blob/main/plugin/hdr4k/设计文档.md

Demonstrates the convention for naming Go packages, which should be lowercase and concise.

```go
// 1. 包名：小写，简洁
package hdr4k
```

--------------------------------

### Get Status Response (Logged In)

Source: https://github.com/fish2018/pansou/blob/main/plugin/weibo/README.md

Example JSON response when the account is successfully logged in. Includes user details, login times, and configured Weibo users.

```json
{
  "success": true,
  "message": "获取成功",
  "data": {
    "hash": "abc123...",
    "logged_in": true,
    "status": "active",
    "username_masked": "pa****ou",
    "login_time": "2025-10-28 12:00:00",
    "expire_time": "2026-10-28 12:00:00",
    "expires_in_days": 365,
    "weibo_users": ["1234567890", "2345678901"],
    "user_count": 2,
    "qrcode_base64": ""
  }
}
```

--------------------------------

### Go Commenting Convention for Structs and Methods

Source: https://github.com/fish2018/pansou/blob/main/plugin/hdr4k/设计文档.md

Provides an example of Go documentation comments for a struct and its method, explaining their purpose and parameters.

```go
// Hdr4kAsyncPlugin 4KHDR网站搜索异步插件
// 
// 该插件实现了对4KHDR.CN网站的高效搜索功能，支持：
// - 并发搜索处理
// - 智能缓存机制
// - 自动重试功能
// - 求片帖智能过滤
type Hdr4kAsyncPlugin struct {
    *plugin.BaseAsyncPlugin
}

// Search 执行搜索并返回结果
//
// 参数：
//   keyword: 搜索关键词
//   ext: 扩展参数，可包含title_en等字段
//
// 返回值：
//   []model.SearchResult: 搜索结果列表
//   error: 错误信息
func (p *Hdr4kAsyncPlugin) Search(keyword string, ext map[string]interface{}) ([]model.SearchResult, error) {
    // 实现逻辑...
}
```

--------------------------------

### Enabling a New Plugin

Source: https://context7.com/fish2018/pansou/llms.txt

This command demonstrates how to enable a newly developed plugin. Replace 'myplugin' with the actual name of your plugin.

```bash
pansou --plugin myplugin
```

--------------------------------

### Pansou Search API POST Request Example (With Filter)

Source: https://github.com/fish2018/pansou/blob/main/README.md

Example of a POST request to the search API demonstrating the use of the 'filter' parameter. This specific example filters results to include terms like '合集' or '全集' while excluding '预告' or '花絮'.

```bash
curl -X POST http://localhost:8888/api/search \
  -H "Content-Type: application/json" \
  -d '{
    "kw": "唐朝诡事录",
    "filter": {
      "include": ["合集", "全集"],
      "exclude": ["预告", "花絮"]
    }
  }'
```

--------------------------------

### Multi-User Support Scenario

Source: https://github.com/fish2018/pansou/blob/main/plugin/qqpd/README.md

This scenario demonstrates how the plugin supports multiple users, each with their own configured channels. During search, channels are de-duplicated and load-balanced across users.

```text
用户A (QQ: 111111111)
  ↓
配置频道: [频道1, 频道2, 频道3]

用户B (QQ: 222222222)
  ↓
配置频道: [频道2, 频道4, 频道5]

用户C (QQ: 333333333)
  ↓
配置频道: [频道3, 频道5, 频道6]

搜索时:
  ↓
去重后的频道: [频道1, 频道2, 频道3, 频道4, 频道5, 频道6]
  ↓
负载均衡分配:
  - 用户A: 搜索频道1, 频道4
  - 用户B: 搜索频道2, 频道5
  - 用户C: 搜索频道3, 频道6
```

--------------------------------

### Basic Plugin Development Template (Go)

Source: https://github.com/fish2018/pansou/blob/main/docs/系统开发设计文档.md

Provides a template for developing asynchronous plugins in Go. It includes necessary imports, plugin registration, and the structure for implementing search functionality with asynchronous processing and keyword filtering.

```go
package myplugin

import (
    "net/http"
    "pansou/model"
    "pansou/plugin"
)

type MyPlugin struct {
    *plugin.BaseAsyncPlugin
}

func init() {
    p := &MyPlugin{
        BaseAsyncPlugin: plugin.NewBaseAsyncPlugin("myplugin", 3),
    }
    plugin.RegisterGlobalPlugin(p)
}

func (p *MyPlugin) Search(keyword string, ext map[string]interface{}) ([]model.SearchResult, error) {
    return p.AsyncSearch(keyword, p.searchImpl, p.GetMainCacheKey(), ext)
}

func (p *MyPlugin) searchImpl(client *http.Client, keyword string, ext map[string]interface{}) ([]model.SearchResult, error) {
    // 实现具体搜索逻辑
    // 1. 构建请求URL
    // 2. 发送HTTP请求  
    // 3. 解析响应数据
    // 4. 转换为标准格式
    // 5. 关键词过滤
    return plugin.FilterResultsByKeyword(results, keyword), nil
}
```

--------------------------------

### 插件基础结构和注册

Source: https://github.com/fish2018/pansou/blob/main/docs/插件开发指南.md

展示了开发新插件的基础 Go 代码结构，包括插件结构体定义、初始化函数以及插件注册。`NewBaseAsyncPlugin` 用于创建基础插件实例，`RegisterGlobalPlugin` 用于向系统注册插件。

```go
package myplugin

import (
    "context"
    "io"
    "net/http"
    "time"
    "pansou/model"
    "pansou/plugin"
    "pansou/util/json"  // 使用项目统一的高性能JSON工具
)

type MyPlugin struct {
    *plugin.BaseAsyncPlugin
}

func init() {
    p := &MyPlugin{
        BaseAsyncPlugin: plugin.NewBaseAsyncPlugin("myplugin", 3), // 优先级3 = 普通质量数据源
    }
    plugin.RegisterGlobalPlugin(p)
}

// 对于需要跳过Service层过滤的插件（如磁力搜索插件）
func init() {
    p := &MyMagnetPlugin{
        BaseAsyncPlugin: plugin.NewBaseAsyncPluginWithFilter("mymagnet", 4, true), // 跳过Service层过滤
    }
    plugin.RegisterGlobalPlugin(p)
}

// Search 执行搜索并返回结果（兼容性方法）
func (p *MyPlugin) Search(keyword string, ext map[string]interface{}) ([]model.SearchResult, error) {
    result, err := p.SearchWithResult(keyword, ext)
    if err != nil {
        return nil, err
    }
    return result.Results, nil
}

// SearchWithResult 执行搜索并返回包含IsFinal标记的结果（推荐方法）
func (p *MyPlugin) SearchWithResult(keyword string, ext map[string]interface{}) (model.PluginSearchResult, error) {
    return p.AsyncSearchWithResult(keyword, p.searchImpl, p.MainCacheKey, ext)
}
```

--------------------------------

### API Search Request Example

Source: https://github.com/fish2018/pansou/blob/main/plugin/xinjuc/html结构分析.md

Demonstrates how to make a search request to the local API endpoint for the 'xinjuc' plugin, searching for '凡人修仙传'.

```bash
curl "http://localhost:8888/api/search?kw=凡人修仙传&plugins=xinjuc"
```

--------------------------------

### Go Configuration for Authentication

Source: https://github.com/fish2018/pansou/blob/main/docs/系统开发设计文档.md

Shows how to define and load authentication-related configurations from environment variables in Go. Includes settings for enabling authentication, user mapping, token expiry, and JWT secret.

```go
type Config struct {
    // ... 现有配置 ...
    
    // 认证相关配置
    AuthEnabled      bool              // 是否启用认证
    AuthUsers        map[string]string // 用户名:密码哈希映射
    AuthTokenExpiry  time.Duration     // Token有效期
    AuthJWTSecret    string            // JWT签名密钥
}

// 从环境变量读取认证配置
func getAuthEnabled() bool {
    enabled := os.Getenv("AUTH_ENABLED")
    return enabled == "true" || enabled == "1"
}

func getAuthUsers() map[string]string {
    usersEnv := os.Getenv("AUTH_USERS")
    if usersEnv == "" {
        return nil
    }
    
    users := make(map[string]string)
    pairs := strings.Split(usersEnv, ",")
    for _, pair := range pairs {
        parts := strings.SplitN(pair, ":", 2)
        if len(parts) == 2 {
            username := strings.TrimSpace(parts[0])
            password := strings.TrimSpace(parts[1])
            // 实际使用时应该对密码进行哈希处理
            users[username] = password
        }
    }
    return users
}
```

--------------------------------

### Session Keep-Alive Log Example

Source: https://github.com/fish2018/pansou/blob/main/plugin/qqpd/README.md

Example log output when the debug log is enabled, showing the session keep-alive process for active users.

```text
[QQPD] 💓 Session保活: 已为 2 个用户执行保活任务
[QQPD] 💓 Session保活成功: 1851****32 (状态码: 200)
[QQPD] 💓 Session保活成功: 1234****56 (状态码: 200)
```

--------------------------------

### Start Cache Cleaner

Source: https://github.com/fish2018/pansou/blob/main/plugin/panta/panta插件设计文档.md

Starts a background goroutine that periodically cleans the cache. It uses a ticker to trigger the cleaning process every hour.

```go
func startCacheCleaner() {
    ticker := time.NewTicker(1 * time.Hour)
    defer ticker.Stop()
    
    for range ticker.C {
        // 清空所有缓存
    }
}
```

--------------------------------

### Start Concurrency Adjuster

Source: https://github.com/fish2018/pansou/blob/main/plugin/panta/panta插件设计文档.md

Starts a goroutine that periodically adjusts concurrency based on system performance. It uses a ticker to trigger the adjustment process.

```go
func (p *PantaPlugin) startConcurrencyAdjuster() {
    ticker := time.NewTicker(concurrencyAdjustInterval * time.Second)
    defer ticker.Stop()
    
    for range ticker.C {
        p.adjustConcurrency()
    }
}
```

```go
func (p *PantaPlugin) adjustConcurrency() {
    // 计算平均响应时间
    // 根据响应时间调整并发数
}
```

```go
func (p *PantaPlugin) recordResponseTime(d time.Duration) {
    // 记录响应时间
}
```

--------------------------------

### Build PanSou System with SuSu Plugin

Source: https://github.com/fish2018/pansou/blob/main/plugin/susu/susu插件设计文档.md

Command to compile and package the PanSou system, including the SuSu plugin, from the project root directory.

```bash
# 在项目根目录下执行
go build -o pansou main.go
```

--------------------------------

### ypfxw Extracted Data Example

Source: https://github.com/fish2018/pansou/blob/main/plugin/ypfxw/html结构分析.md

An example of the structured data that can be extracted from a ypfxw.com post, including unique ID, title, links, tags, and datetime.

```json
UniqueID: ypfxw-103580
Title: 凡人修仙传 ... 重返天南 ...
Links: [{Type:"quark", URL:"https://pan.quark.cn/s/08211da2cb83", Password:""}]
Tags: ["影视资源","夸克网盘","2025","免费下载"]
Datetime: 2025-11-25
```

--------------------------------

### Feikuai Magnet Link Format Example

Source: https://github.com/fish2018/pansou/blob/main/plugin/feikuai/json结构分析.md

This is an example of a standard magnet link format, including the info hash, URL-encoded filename, and file size.

```text
magnet:?xt=urn:btih:C3A3A53C2408396D64450046361F00650CB9E53E&dn=Strange.Tales.of.Tang.Dynasty.S03E07.2025.2160p.IQ.WEB-DL.H265.DDP5.1-BlackTV.mkv&xl=2458041664
```

--------------------------------

### Weibo Load Balancing Example

Source: https://github.com/fish2018/pansou/blob/main/plugin/weibo/README.md

Illustrates how user assignments are distributed across different accounts for load balancing, ensuring efficient resource utilization.

```text
账户A配置: [用户1, 用户2, 用户3, 用户4]
账户B配置: [用户2, 用户3, 用户5, 用户6]
账户C配置: [用户1, 用户5, 用户7]

去重后要搜索的微博用户:
  [用户1, 用户2, 用户3, 用户4, 用户5, 用户6, 用户7]

任务分配（轮询）:
  用户1 → 账户A
  用户2 → 账户B
  用户3 → 账户C
  用户4 → 账户A
  用户5 → 账户B
  用户6 → 账户C
  用户7 → 账户A
```