┌──────────────────────────────────────────┐
  调用方 ──HTTP/MCP─▶│ ① Go 网关面(传输与调度)                │
                    │   路由 · 元数据 · 缓存 · 限速 · 预算      │
                    │   109 源 / 154 端点 / ≤500ms 硬预算       │
                    └───────────────────┬──────────────────────┘
                                        │ 原始字节
                    ┌───────────────────▼──────────────────────┐
                    │ ② Python 解析面(内容与结构)             │
                    │   JSON · XML · CSV · TSV · JSONL         │
                    └───────────────────┬──────────────────────┘
                                        ▼
                       上游官方 API(声明 UA + 按站限速)

make up                       # docker compose up -d --build
curl -s http://127.0.0.1:8848/livez

# Python 解析面(网关会把它作为子进程拉起)
python3 -m venv .venv && source .venv/bin/activate
pip install -e .

# Go 网关
make gateway-run              # http://127.0.0.1:8848

pip install -e ".[mcp]"
a-source-gateway serve

# 看看有哪些源
curl -s "http://127.0.0.1:8848/v1/sources?q=制裁" | python3 -m json.tool | head -30

# 看某个端点要传什么参数、返回什么结构
curl -s http://127.0.0.1:8848/v1/sources/crossref/endpoints/works | python3 -m json.tool

# 执行查询
curl -s -X POST http://127.0.0.1:8848/v1/query \
  -H 'Content-Type: application/json' \
  -d '{"source":"crossref","endpoint":"works",
       "params":{"filter":"from-index-date:2026-10-21"},"limit":3}' | python3 -m json.tool

{
  "mcpServers": {
    "a-source-gateway": {
      "command": "a-source-gateway-mcp",
      "args": []
    }
  }
}

a-source-gateway list --family 医药          # 列源
a-source-gateway show crossref               # 看一个源的完整 meta
a-source-gateway show ctgov --json           # JSON 输出
a-source-gateway validate                    # 校验数据文件
a-source-gateway build-registry -o r.json     # 导出注册表
a-source-gateway bench                       # 跑延迟基准

from a_source_gateway import Resolver, QueryRequest, build_registry

r = Resolver(build_registry())
await r.startup()
env = await r.query(QueryRequest(source="openalex", endpoint="works",
                                  params={"filter": "from_publication_date:2026-09-22"}))
print(env.meta.total, env.meta.latency_ms, env.meta.cached)

① 侦察   python3 scripts/recon.py <url> -o /tmp/recon.json     探测可达性/认证/限速/响应结构
② 补语义  (智能体判断)                                          族/机构/限速口径/规模口径/增量策略
③ 草稿   python3 scripts/scaffold_source.py --recon ...         生成 CSV 行 + 端点定义
④ 校验   make validate                                          数据文件结构与一致性
⑤ 验证   python3 scripts/verify_source.py "<源名>"              真实请求 + 断言(证据关卡)
⑥ 部署   make up                                                重建并重启
⑦ 交付   python3 scripts/demo.py "<源名>"                       调用示例 + 真实数据

{
  "meta": {
    "request_id": "6921f879dc47",
    "schema_version": "1.0",
    "source": "crossref",
    "endpoint": "works",
    "upstream": {
      "url": "https://api.crossref.org/works?filter=from-index-date%3A2026-10-21&rows=25",
      "method": "GET", "status": 200, "latency_ms": 812
    },
    "latency_ms": 3,            // 客户端可见总耗时
    "budget_ms": 500,           // 本次预算(≤500)
    "cached": true,             // 是否命中缓存
    "cache_age_s": 42,
    "degraded": false,          // 是否降级
    "offline": false,
    "count": 3,                 // 本次返回条数
    "total": 1734280,           // 上游记录总数
    "truncated": true,          // 是否被 limit 截断
    "next_cursor": null,
    "parser": "python",         // 实际解析引擎(python | go)
    "trace_id": "9f2c…",        // 链路追踪 id
    "rate_limit": {},
    "fallback": {},             // 降级时的直连兜底信息
    "errors": []                // [{type, message, status}]
  },
  "data": [ ... ],
  "fields": ["DOI", "publisher"]
}

a-source-gateway/
├── pyproject.toml              Python 项目根(= 仓库根)
├── python/src/a_source_gateway/  Python 解析面 + MCP + CLI
├── python/tests/                 Python 测试
├── gateway/                      Go 网关(独立 go.mod,只用标准库)
├── data/                         四份事实源(两平面共享)
├── scripts/                      智能体接入工具链
├── docs/  deploy/  examples/
└── AGENTS.md  CLAUDE.md  GOVERNANCE.md

pip install -e ".[dev]"

make test              # 单元测试(默认不联网)
make network-test      # 需要访问真实上游的用例
make lint  type        # ruff / mypy
make gateway-test      # Go 单元测试
make parity            # 校验 Go 与 Python 构建出的注册表一致
make validate          # 校验 data/ 下的数据文件
make bench             # 延迟基准
make check             # 提交前全量检查