外部上下文感知系统

开放式外部数据接入与网页内容获取底座，用于把公开网页、外部 API、第三方采集工具、手动导入数据统一接入为可存证、可调度、可告警、可被 API / CLI / MCP 调用的数据源。

本项目不是重型爬虫平台。它更接近一个可组合的数据接入网关：

• source 负责描述一个信息源
• provider 负责描述数据来自哪个工具或供应商
• raw payload 保存原始证据
• web snapshot 保存网页抓取证据
• extracted item 保存标准化结果
• scheduler 负责 source 级周期更新
• alerts 负责失败告警
• API / CLI / MCP 负责对外调用

适用场景

当前适合：

• 固定 URL 的官网公告、政策页、文档页监测
• 招聘页、企业 career page、校招页的岗位信息采集
• SPA 页面识别、工具路由和 fallback
• 公开 JSON 接口发现后转结构化 source
• 网页快照、HTML / Markdown / clean text 存证
• 外部采集工具通过 API 推送原始数据或标准化数据
• 每个 source 独立调度、失败告警和后续复查

当前不承诺：

• 全网无遗漏采集
• 账号自动化和敏感操作自动化
• 强反爬平台的稳定采集 SLA
• 分布式高并发爬虫平台
• 无人工审核的自动业务决策

快速启动

推荐在项目目录内运行，避免把本项目测试依赖写入全局环境。

python3 -m venv .venv
. .venv/bin/activate
pip install -e .
uvicorn app.main:app --reload --port 8545

打开后台：

http://127.0.0.1:8545/

运行 smoke：

python scripts/smoke.py

如果使用本项目已有专用环境，优先通过项目守卫运行：

scripts/project_tool_guard.py -- .venv312/bin/python -m pytest
scripts/project_tool_guard.py -- .venv312/bin/python scripts/run_web_tool_probe_suite.py --mode readiness

核心能力

1. 数据接入

• POST /api/v1/ingest/raw：接收外部工具推送的原始数据
• POST /api/v1/ingest/items：接收标准化数据
• GET /api/v1/raw-payloads：查询原始数据
• GET /api/v1/items：查询标准化结果

2. 平台、供应商和信息源

• POST /api/v1/platforms：注册自定义平台
• POST /api/v1/providers：注册自定义供应商
• POST /api/v1/sources：创建信息源
• PUT /api/v1/sources/{source_id}/fields：配置字段抽取规则

首版 provider 类型包括：

• REST API provider
• Webhook ingest provider
• Manual/import provider
• Web crawler provider

3. 网页 source

• POST /api/v1/web/sources：创建公开网页信息源
• POST /api/v1/web/sources/{source_id}/route：识别网页技术形态并选择工具链
• POST /api/v1/web/sources/{source_id}/run：执行网页抓取、证据保存和字段提取
• GET /api/v1/web/snapshots：查询网页 HTML / Markdown / clean text 证据快照

当前网页链路按页面类型选择工具：

静态抽取/Scrapy -> changedetection.io/RSSHub -> Playwright/Crawlee -> Crawl4AI/Firecrawl

国聘类公开职位页面会优先走结构化职位 API：

structured_job_api -> firecrawl_self_host -> playwright -> crawlee_playwright

工具评估、测试报告和分层见：

• docs/WEB_SOURCE_TOOL_REGISTRY.md
• docs/web-source-probe-suite-report-2026-06-26.md
• docs/web-source-scheduler-and-alerts.md

4. 调度与告警

• POST /api/v1/scheduler/tick：执行一次到期 source 调度
• GET /api/v1/scheduler/status：查询每个 source 的调度状态
• GET /api/v1/alerts：查询失败告警

每个 source 都有独立 schedule 和 source_run_state。首版支持：

• manual
• daily
• hourly
• every_5_minutes
• interval:60
• config.schedule_interval_seconds

手动 tick：

curl -X POST 'http://127.0.0.1:8545/api/v1/scheduler/tick?limit=20'

开启后台轮询：

CONTEXT_GATEWAY_SCHEDULER_ENABLED=1 uvicorn app.main:app --reload --port 8545

失败会写入 alerts，连续失败 3 次后升级为 critical，成功运行会自动关闭该 source 的 open 告警。

MCP

启动 MCP server：

context-gateway-mcp

主要工具：

• find_sources
• describe_source
• create_source
• create_web_source
• route_web_source
• run_web_source
• get_web_snapshots
• run_scheduler_tick
• get_scheduler_status
• get_alerts
• create_provider
• update_field_config
• estimate_cost
• run_source
• ingest_items
• get_raw_payload
• get_extracted_items
• list_provider_health

项目结构

app/
  main.py          FastAPI 入口
  database.py      SQLite 表结构初始化
  repository.py    数据访问层
  web_sources.py   网页 source、路由、抓取和结构化职位处理
  scheduler.py     source 级调度与告警联动
  extraction.py    字段抽取与 normalized item
  mcp_server.py    MCP 工具入口
context_gateway/
  cli.py           CLI 入口
static/
  app.js           通用后台页面
  web-content.js   网页内容获取工作台
docs/
  ARCHITECTURE.md  架构说明
  API.md           API 协议
  WEB_SOURCE_TOOL_REGISTRY.md  网页工具评估与分层
  web-source-scheduler-and-alerts.md  调度与告警说明
scripts/
  project_tool_guard.py  项目工具守卫
  *_probe.*             网页工具探针
tests/
  test_*.py             单元测试

关键文档

• docs/ARCHITECTURE.md：系统分层和核心设计。
• docs/API.md：API 请求和响应约定。
• docs/web-content-acquisition-frontend-spec.md：网页内容获取工作台规格。
• docs/web-source-scheduler-and-alerts.md：source 级调度与失败告警。
• docs/WEB_SOURCE_TOOL_REGISTRY.md：网页工具评估、优先级和使用边界。
• docs/PROJECT_ONLY_TEST_TOOLS.md：项目专用测试工具边界。

开发与验证

运行测试：

scripts/project_tool_guard.py -- .venv312/bin/python -m pytest

如果没有 .venv312/，可使用普通开发环境：

python -m pytest

注意：

• 不要提交 .env、data/、storage/、.services/**/.env、node_modules/、.venv*
• 不要把本项目 probe 脚本、Docker 服务和虚拟环境复制到其他项目作为默认工具链
• 新增外部供应商前，需要说明成本、权限、失败模式和兜底方案
• 数据模型变更必须补测试

后续路线

优先级建议：

1. 完善条目生命周期：新增、更新、仍有效、失效、重新出现。
2. 增强批量调度：小并发 worker pool、per-domain 限流、retry/backoff、batch summary。
3. 增强前端：source 运行历史、告警处理、快照对比、结构化条目查看。
4. 增强对外集成：导出、webhook、外部系统推送。
5. 按需接入托管供应商：Apify、Zyte、Bright Data、Browserbase 等作为兜底。