Home

SouWen 用户手册

事实来源：主仓 BlueSkyXN/SouWen pr-88 (commit a312645) 的 registry/sources.py、config/models.py、CLI/API 路由与 docs/。Wiki 在 2026-05-04 校准。

SouWen（搜文） 是面向 AI Agent 的统一搜索与内容获取库——把学术论文、专利、网页、社交、视频、百科、开发者社区、中文技术、企业办公、网页归档和内容抓取通过一个注册表统一暴露给 CLI、Python、HTTP API 和 MCP。

---

30 秒理解 SouWen

import asyncio
from souwen.facade import search, fetch_content

async def main():
    papers = await search("transformer", domain="paper", limit=5)
    web    = await search("python asyncio", domain="web", limit=5)
    page   = await fetch_content(["https://example.com"], provider="builtin")

asyncio.run(main())

• 一个注册表——93 个内置数据源由 SourceAdapter 集中声明，新增一个源只改 1-2 处。
• 一个门面——facade.search / fetch / archive 按 (domain, capability) 派发，调用方不需要关心 Client 细节。
• 多种入口——pip install souwen 直接得到 CLI、Python 库、FastAPI Server、Web Panel、MCP Server。
• 生产侧能力——Token Bucket + 滑动窗口限流、curl_cffi TLS 指纹、五模式 WARP 代理、SSRF 防护、三角色认证。

---

我想做什么？

目标	5 分钟入口	深入阅读
跑一次搜索看看	Quick Start	Tutorials/First Search
给 AI Agent 装一个搜索/抓取工具	MCP 集成	Feature MCP
选哪个数据源	Data Source Guide	Sources Index
配置 API Key 和环境	Config API Keys	Config Reference
启动 HTTP API 服务	Quick Start#API	HTTP API · Authentication and Roles
用 Web 面板管理	Web Panel	—
反爬/限流被卡	Network and WARP	Troubleshooting
部署到 Docker / HF Space / ModelScope	Deployment Guide	—
加一个自己的数据源	Plugin Development	插件对接规范（主仓）
排查"这条 API 为什么 401/429/504"	Troubleshooting	FAQ

---

三种用法

flowchart LR
    A[CLI<br/>souwen search/fetch] --> R[Registry<br/>93 个 SourceAdapter]
    B[Python<br/>souwen.facade.*] --> R
    C[HTTP API<br/>FastAPI :8000] --> R
    D[MCP Server<br/>Claude/Cursor 直连] --> R
    E[Web Panel<br/>:8000/panel] --> C
    R --> X[(Domain Clients<br/>paper/patent/web/...)]
    X --> Y[(curl_cffi · httpx · WARP · Proxy Pool)]

Loading

任意一种入口背后都是同一个 registry → facade → domain client → core platform 路径，行为完全一致。

---

数据源全景

领域	数量	入口	代表源
学术论文	19	souwen search paper	arxiv · openalex · crossref · pubmed · semantic_scholar
专利	8	souwen search patent	google_patents · uspto_odp · epo_ops · cnipa · the_lens
通用网页搜索	29	souwen search web	duckduckgo · bing · tavily · exa · serpapi · perplexity
内容抓取	16 fetch + 5 跨域	souwen fetch	builtin · jina_reader · firecrawl · crawl4ai · scraperapi
中文技术社区	9	souwen search web --engines csdn,...	csdn · juejin · v2ex · linuxdo · nodeseek
社交平台	5	souwen search social	twitter · reddit · weibo · zhihu · facebook
视频平台	2	souwen youtube · souwen bilibili	youtube · bilibili
开发者平台	2	souwen search developer	github · stackoverflow
知识与百科	1	souwen search knowledge	wikipedia
企业办公	1	—	feishu_drive
网页归档	1	souwen wayback ...	wayback

更详细的"何时选谁"对比见 Data Source Guide。完整 93 篇单源页见 Sources Index。

---

文档边界

位置	用途	更新方
README	项目简介、安装、5 分钟跑通、入口导航	主仓 PR
主仓 docs/	技术事实源：架构、API、配置、生成的数据源清单、插件规范	主仓 PR + CI
本 Wiki	用户手册：怎么用、怎么选、怎么配、怎么排障	Wiki 仓库 + tools/generate_wiki.py
CHANGELOG	版本变更与不兼容公告	主仓 PR

Wiki 不复制 docs/ 的字段表和 OpenAPI；遇到字段细节会反向链回主仓。

---

维护原则

1. 事实可追溯 — 每页 frontmatter 标注事实来源 commit；数字（93 / 103 / 61 等）以 registry 派生为准。
2. 场景导向 — 每页解决一个问题，不当百科。
3. 示例可拷贝 — 所有 bash / python / yaml 块直接复制就能跑。
4. 半自动生成 — 单源页面、配置参考、API 路由表由 tools/generate_wiki.py 从主仓 registry/CLI/Server 派生。
5. 不写未公布的承诺 — 任何 benchmark / smoke 数据只作为某次实测，不当长期保证。

更多信息：Wiki Coverage Manifest · Contributing to Wiki。