SouWen 搜文

English | 中文

面向 AI Agent 和自动化脚本的 target-only Search、LLM Search 与 Fetch API。

当前源码候选为 Souwen v2rc5 （Python/runtime 2.0.0rc5）。v2.0.0rc5 tag、12 项 Release 资产、provenance 与 HFS promotion 只能由 repository-owner 对 exact main 运行 central release workflow 创建；本段 不预先声明发布成功，最终状态以 tag、Release、workflow 与 runtime 回读为准。这不是 2.0.0 GA，也不发布到 PyPI。前一 immutable-by-policy baseline 是 v2.0.0rc4，source 为 51f092841696b1e6f898e7c6bea40e535f639f5c。

作者: @BlueSkyXN · 项目地址: github.com/BlueSkyXN/SouWen · 协议: GPLv3

⚠️ 声明：本项目仅供 Python 学习与技术研究使用。 涵盖 API 聚合、全栈开发（FastAPI + React）、爬虫技术（TLS 指纹 / 反爬绕过）与异步编程等方向。请勿用于违反法律法规或第三方服务条款的用途。

• 简介
• 在线预览
• 安装
• 快速开始
• 配置
• 架构
• 部署
• 文档
• 贡献
• License

SouWen（搜文）为 AI Agent、Python 集成和服务端应用提供统一的 target-only 数据 API。 公开业务能力只有 Search、LLM Search 和 Fetch。Provider 的事实来源是 ProviderManifest catalog、ManifestRegistry 与 ProviderManager；/api/v1/providers 是它们的安全投影，不是旧 Source Catalog 的兼容别名。

• 104 个内置 Provider v2 package，共 110 个 capability adapter。
  • Search：88 个 package · LLM Search：2 个 · Fetch：20 个。

• Frozen OpenAPI + generated SDK：Python root 只暴露 generated sync/async SDK；Panel 使用同一 OpenAPI 生成的 TypeScript SDK
• 统一 canonical DTO：Search、LLM Search、Fetch、Provider Catalog 和 probes 使用明确的 Pydantic v2 contract
• 安全边界：target Data API 使用 user credential；Admin 仅提供 read-only config、doctor 与 ping

• Calm Precision Panel：https://blueskyxn-souwen.hf.space/panel#/
• Swagger：https://blueskyxn-souwen.hf.space/docs
• 完整 route、角色与逐项验收：HFS 在线预览与功能验收

Space 仓库保持 private；当前 App domain 的 Panel/docs/probes surface 可直接预览，Search、 LLM Search、Fetch、Providers 和 Admin API 仍要求 SouWen application credential。HFS 是 可变 current-main deployment，不能仅凭版本号把它当成 tag-exact GitHub Release。

# 从当前 main 源码线安装核心库
git clone https://github.com/BlueSkyXN/SouWen.git
cd SouWen
pip install -e .

# 默认安装提供 generated Python SDK；运行 Server 再安装 runtime extra
pip install -e ".[server,tls,web,robots,scraper]"

from souwen import SouWenClient
from souwen.delivery.client_sdk import SearchRequest

with SouWenClient("http://127.0.0.1:8000", token="your-user-token") as client:
    page = client.search(SearchRequest(query="quantum computing", domains=["paper"]))
    for item in page.items:
        print(item.title, item.url)

SDK 同时提供 AsyncSouWenClient，并在首次业务请求前以 /healthz 校验 API major 2。 完整认证、HFS 双 token 和错误处理见 Python SDK 文档。 Panel 使用同一 OpenAPI artifact 生成的 TypeScript SDK。

SOUWEN_USER_PASSWORD=userpass SOUWEN_ADMIN_PASSWORD=adminpass \
  uvicorn souwen.server.app:app --host 0.0.0.0 --port 8000

主要端点：

curl "http://localhost:8000/api/v1/search" \
  -H "Authorization: Bearer userpass" \
  -H "X-SouWen-API-Major: 2" \
  -H "Content-Type: application/json" \
  -d '{"query":"transformer","domains":["paper"]}'
curl "http://localhost:8000/api/v1/providers" \
  -H "Authorization: Bearer userpass" \
  -H "X-SouWen-API-Major: 2"

POST /api/v1/fetch 与 Search/LLM Search 同属 target Data API，使用 user credential。 管理面只保留 GET /api/v1/admin/config、GET /api/v1/admin/doctor 和 GET /api/v1/admin/ping。没有 rollout switch、/sources、citation/detail/archive-save、 递归抓取、浏览器抓取产品入口或旧 enriched-search public endpoint。

访问 /docs 查看完整 OpenAPI 文档；访问 /panel#/ 进入单一 Calm Precision 管理面。/ 在默认配置下重定向到 /docs。

配置优先级：env > ./souwen.yaml > ~/.config/souwen/config.yaml > .env > 默认值。

从 souwen.example.yaml 创建项目配置；需要全局配置时，可将其复制到 ~/.config/souwen/config.yaml。

三层分离：展示层（Server / Panel）→ generated SDK / Module APIs → ProviderManifest catalog、ManifestRegistry、ProviderManager 和 runtime clients。

详见 docs/architecture.md。

src/souwen/
├── delivery/          frozen OpenAPI、generated Python SDK 与 HTTP adapters
├── platform/          ProviderManifest / ManifestRegistry / ProviderManager
├── providers/         provider specs、adapters 与 runtime clients
├── modules/           Search、LLM Search 与 Fetch application services
├── common_runtime/    shared transport、security、resilience 与 observability
└── server/            FastAPI 应用

Docker（推荐）：

docker build -t souwen .
docker run -p 8000:49265 \
  -e SOUWEN_ADMIN_PASSWORD=your-admin-password \
  -e SOUWEN_USER_PASSWORD=your-user-password \
  -v "$PWD/souwen.yaml:/app/souwen.yaml:ro" \
  -v souwen-data:/app/data \
  souwen

/app/souwen.yaml 是应用配置；/app/data 只用于 WARP/runtime persistence。

HuggingFace Spaces：参见 cloud/hfs/ 与 docs/hf-space-cd.md。 根级 hfs-dev.toml 是 registry-only 部署登记：记录 source lane、Space ID、 workflow ownership 和当前 Space setting 名称，不保存任何真实凭据值，也不授权通用同步工具 修改远端设置；当前参考 hf_space_sync.py 会在读取 .env 或联网前拒绝该 manifest。它采用当前 HFS v2.1 draft schema（正式公开基线仍为 v2.0），并登记 gitignored、0600 的 local/credentials/souwen-hfs.yaml 作为 SOUWEN_CONFIG_B64 的原始 YAML 事实源。 ModelScope：参见 cloud/modelscope/。

部署环境可按自身网络策略配置代理；公开 API 不提供 WARP 管理或运行时安装入口。

• docs/README.md — 技术文档入口与阅读导航
• docs/getting-started.md — 快速开始
• docs/concepts.md — 核心概念
• docs/python-api.md — Python API
• docs/source-catalog.md — Provider Catalog 契约
• docs/architecture.md — 架构概览
• docs/data-sources.md — 完整 Provider 指南与清单（由 manifest catalog 自动生成）
• docs/configuration.md — 配置层级 / WARP / HTTP backend
• docs/api-reference.md — REST API 参考
• docs/hf-space-cd.md — Hugging Face Space CD / 本地预检 / 部署后验收
• docs/live-preview.md — HFS 在线 Panel/Swagger、角色矩阵与功能验收
• docs/deployment.md — 部署
• docs/anti-scraping.md — TLS 指纹 / WARP / 限流
• docs/appearance.md — Calm Precision 管理面板
• docs/adding-a-source.md — 新增数据源指南
• docs/contributing.md — 开发者指南
• docs/internal/rc-readiness-gates.md — v2.0.0rc5 固定门禁与 evidence manifest 契约
• docs/internal/ — 维护者 ADR、分支策略和发布前基线
• CHANGELOG.md — 版本变更

• 新增 Provider：参考 docs/adding-a-source.md（新增 manifest/spec/adapter 与 conformance tests）
• 代码风格：ruff format && ruff check
• 测试：pytest tests/

GPLv3 · 仅供学习研究用途