MySearch

统一检索服务 — search.msw.mba

MySearch API 接口文档

Base URL: https://search.msw.mba

认证方式

MySearch 现在区分三类调用面，并统一使用同一套服务端鉴权逻辑：

Web 页面搜索：浏览器访问 /oauth/login 跳转到 Casdoor 登录，回调由服务端完成 code exchange，并写入 HttpOnly 会话 Cookie。页面搜索、Provider 检测和管理接口都复用该 Cookie。

Skills / Agent 调用：推荐使用静态 API Key，通过 Authorization: Bearer <api-key> 或 X-API-Key 发送。适合 OpenClaw Skill、定时任务、服务间调用。

直接 API 调用：支持 Casdoor JWT 或 API Key。受保护范围包括 /api/*（除 /api/health 与 /api/auth/session）以及 SearXNG 兼容搜索端点 /search。/config 仍保持公开，仅提供实例元信息。

JWT 示例：

TOKEN="<casdoor-access-token>"

curl -H "Authorization: Bearer $TOKEN" \
  "https://search.msw.mba/api/search?q=test&compact=true"

API Key 示例：

curl -H "X-API-Key: sk-search-xxxxx" \
  "https://search.msw.mba/api/search?q=test&compact=true"

GET /api/search — 聚合搜索

多后端聚合搜索，自动去重，结果按时间降序排列。支持 compact 模式，适合 LLM / Agent 调用。

auto 模式下统一偏重国际结果：普通查询约 40% 国内 / 60% 国际，技术查询约 20% 国内 / 80% 国际，与输入语言无关。

参数	类型	默认	说明
`q`	string	—	搜索关键词（必填）
`region`	string	auto	`auto` \| `cn` \| `global`
`max_results`	int	30	返回结果数量上限 (1-50)
`time_range`	string	""	时间范围: `day` \| `week` \| `month` \| `year` \| 空=不限
`compact`	bool	false	精简模式，截断 content 节省 token
`max_content_len`	int	300	每条结果 content 最大字符数

示例（Agent / LLM 推荐）:

curl -H "X-API-Key: sk-search-xxxxx" \
  "https://search.msw.mba/api/search?q=kubernetes&compact=true&max_results=10&time_range=week"

响应:

{
  "query": "kubernetes",
  "region": "auto",
  "number_of_results": 10,
  "quotas": {"cn": 2, "global": 8},
  "results": [
    {"url": "...", "title": "...", "content": "...", "publishedDate": "2026-04-04T...", "source": "global"}
  ],
  "backends": [
    {"name": "global", "count": 21, "elapsed_ms": 2100, "error": null}
  ]
}

GET /api/search/raw — 原始调试

返回各后端的原始结果（不合并），用于调试。参数与 /api/search 相同（无 compact）。

POST /api/fetch — 抓取网页内容

抓取指定 URL 的文本内容，自动去 HTML 标签，适合 LLM 阅读。

curl -X POST "https://search.msw.mba/api/fetch" \
  -H "X-API-Key: sk-search-xxxxx" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com","max_length":4000,"strip_html":true}'

Body 参数	类型	默认	说明
`url`	string	—	目标 URL（必填）
`max_length`	int	24000	返回文本最大字符数
`strip_html`	bool	true	是否去除 HTML 标签
`timeout`	int	10	超时秒数（上限 30）

GET /api/providers — 后端状态

检测各搜索后端（cn / global）的可用性和延迟。

GET /api/health — 健康检查

返回 {"status": "ok"}。

OpenAPI / Swagger

交互式文档: /api/docs