1. 架构定位与双域三层数据流向拓扑
明确国内 SPARK 企业服务器（第二层）向下游局方专用研判座舱（第三层）供给成品情报的数据流向与权责划分
依据《双域协同三层系统架构与数据流向拓扑方案》，整个系统严格执行“第一层海外感知采集 ➔ 第二层国内 SPARK 汇聚清洗 ➔ 第三层局端座舱单向订阅”的三层拓扑架构。 国内 SPARK 企业服务器（本中心）处于第二层算力中枢，调度本地 14B 大模型完成海量多模态数据深度清洗、经纬度时空初标与热点动态聚类，通过本 Hub OpenAPI 网关向第三层局端研判座舱提供纯净成品情报流。
2. 严正安全隔离红线 (CRITICAL SAFETY BOUNDARIES)
第三方托管服务器与局方涉密内网交互的核心安全守则
严格遵循单向主动拉取原则 (Client-Pull Only)。所有网络连接必须由第三层局方笔记本电脑主动向 SPARK 发起 HTTP 请求。SPARK 服务器绝不保存局方内网 IP，绝不向局方内网发起反向探测或回调。
SPARK 属于第三方企业托管服务器，定位仅为“开源数据清洗中心与算力底座”。局方五 Agent 闭环推演、红蓝博弈、涉密反制举措与长篇战略专报，100% 在局端本地离线生成，严禁回传至 SPARK。
3. 局端鉴权与安全接入机制
第三层局端研判座舱调取所有数据端点必须携带授权凭据
平台采用行业标准的 HTTP Bearer API Key 鉴权机制。SPARK 数据库中采用哈希摘要存储接入密钥，严格执行访问频次限制 (Rate Limit) 与审计流水追溯。 第三层局端笔记本发起 HTTP GET 请求时，必须在 Header 中携带授权凭证：
Authorization: Bearer sk-hub-bureau-seat-2026-demo
X-API-Key: sk-hub-bureau-seat-2026-demo
4. 游标水位增量拉取机制 (Watermark Cursor)
基于自增 ID 游标的高性能增量拉取，确保零漏单、零重复处理
局端 16G 研判笔记本采用单向主动拉取 (Client-Pull) 架构。SPARK 作为服务端常驻运行，局端无需暴露任何端口即可穿透复杂网络；同时局端可根据自身大模型推理算力负荷自主调节拉取速率，实现完美的流速自适应。
- 心跳探测：局端 Client 周期性（如每 15 秒）调用
GET /stats，获取 SPARK 中枢最新情报自增 ID（latest_intel_id）。 - 水位比对：若 SPARK 当前最高 ID 大于局端本地保存的
intel_cursor，则发起增量拉取。 - 增量拉取：请求
GET /intels?since_id={cursor}&limit=50&risk_min=1，获取已由 14B 大模型清洗初标的成品情报。 - 驱动五 Agent 并推进游标：局端本地将数据投递至 Agent 1（实体挖掘）和 Agent 3（威胁仲裁），并将本地游标更新为拉取批次中的最大 ID。
- 直接订阅 Top 10 热点：定期调取
GET /top10-events，直接驱动 Agent 4（红蓝博弈）和 Agent 5（专报撰写），免去局端昂贵聚类开销。
5. 局端专属 6 大核心开放接口规范
详细列出各端点 HTTP 方法、路径、请求参数与标准响应 JSON 结构体（需携带 Bearer API Key）
业务说明：轻量级心跳与情报水位探针端点。局端研判座舱可高频定时轮询此端点（每 10~30 秒一次）。
返回 SPARK 当前已清洗情报最高 ID（latest_intel_id）、智库长文总数、Top 10 聚类事件数与服务运行时长，供局端计算拉取 Lag 差值并决定是否触发增量拉取。
{
"code": 200,
"message": "success",
"data": {
"service": "spark-intelligence-server",
"node_role": "国内企业级汇聚中枢与开源大模型算力底座 (第二层)",
"target_consumer": "局端研判座舱 (第三层 16G 显存笔记本)",
"uptime_sec": 128400,
"latest_intel_id": 1347,
"total_intels": 1347,
"total_articles": 48,
"top10_events_count": 10,
"ai_model": "qwen2.5:14b",
"timestamp": 1790226000
}
}
业务说明：增量调取经 SPARK 本地 14B 大模型深度清洗初标后的成品情报。
包含时空经纬度（latitude, longitude）、基础波及半径（blast_radius_km）、涉事国家与核心实体、双语翻译与两句话客观事实摘要。供给局端 Agent 1 (实体挖掘) 与 Agent 3 (威胁仲裁)。
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
| since_id | int64 | 否 | 0 | 游标起始自增 ID。仅返回 ID > since_id 的增量成品情报 |
| limit | int | 否 | 50 | 单次拉取最大条数，范围 1~100 |
| risk_min | int | 否 | 1 | 最低威胁等级过滤 (1:普通, 2:关注, 3:警告, 4:高危, 5:紧急) |
| country | string | 否 | 空 | 涉事国家代码过滤（如 "PHL", "VNM", "MYS"） |
{
"code": 200,
"message": "success",
"data": [
{
"id": 1347,
"source_id": "1893821039841029",
"author_handle": "SecBlinken",
"author_name": "Antony Blinken",
"title_cn": "美菲在南海争议海域展开联合巡逻磋商",
"summary_cn": "美方重申美菲共同防御条约适用于南海。菲律宾海岸警卫队近期将增派两艘巡逻艇参与常态化护航。",
"country": "PHL",
"city": "Manila",
"latitude": 14.5995,
"longitude": 120.9842,
"blast_radius_km": 150.0,
"risk_level": 3,
"entities": ["菲律宾海岸警卫队", "马尼拉", "仁爱礁"],
"created_at": "2026-09-24T12:00:00Z"
}
]
}
业务说明：拉取海外 40+ 智库机构（如兰德 RAND、CSIS、外交政策 Foreign Policy）的长篇深度报告与国际外媒专栏。 包含报告正文段落、发布机构、核心观点与实体抽取，供给局端 Agent 2 (意图解构) 进行跨文本深度研判。
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
| since_id | int64 | 否 | 0 | 仅拉取 ID > since_id 的增量长文 |
| limit | int | 否 | 20 | 单次拉取条数，范围 1~100 |
| source_org | string | 否 | 空 | 智库机构筛选（如 "RAND", "CSIS", "MINDEF"） |
{
"code": 200,
"message": "success",
"data": [
{
"id": 48,
"source_org": "RAND Corporation",
"title": "Assessing Regional Deterrence Capabilities in Southeast Asia",
"published_at": "2026-09-23T10:00:00Z",
"content": "This report examines emerging defense posture alignments...",
"entities": ["印太战略", "南海", "东盟防长扩大会"],
"created_at": "2026-09-23T10:15:22Z"
}
]
}
业务说明：局方 16G 研判笔记本极度推荐首选接口！ 由 SPARK 在第二层汇聚海量情报，全自动完成事件聚类、客观脉络提炼、热度打分与基础波及半径计算。 局端笔记本免除重复聚类的海量算力消耗，直接将成品 Top 10 热点事实输入 Agent 4 (红蓝博弈) 与 Agent 5 (专报生成) 展开深度推演。
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
| date | string | 否 | 当日 | 聚类日期，格式 YYYY-MM-DD（如 "2026-09-24"） |
{
"code": 200,
"message": "success",
"data": [
{
"rank": 1,
"event_title": "美菲联演与仁爱礁补给态势升级",
"summary": "菲海警船只在多艘外军舰艇伴航下向仁爱礁非法坐滩军舰实施加固物资运送，中方依法依规采取管控措施。",
"heat_score": 96.5,
"risk_level": 4,
"involved_countries": ["PHL", "USA", "CHN"],
"latitude": 9.88,
"longitude": 115.52,
"blast_radius_km": 200.0,
"intel_count": 42
}
]
}
业务说明：供给局端座舱的态势大屏与 2.5D 战术沙盘。 返回东盟十国社会稳定性客观指数 (0~100) 以及沙盘时空打点事件（经纬度、辐射圈半径、涉事国与影响等级）。
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
| limit | int | 否 | 100 | 返回打点事件条数上限 |
{
"code": 200,
"message": "success",
"data": {
"stability_indexes": {
"PHL": 62.4,
"VNM": 78.1,
"MYS": 81.5,
"IDN": 74.0,
"THA": 69.8
},
"events": [
{
"id": 1347,
"title": "美菲联演与仁爱礁补给态势升级",
"latitude": 9.88,
"longitude": 115.52,
"blast_radius_km": 200.0,
"risk_level": 4,
"country": "PHL"
}
]
}
}
业务说明：SPARK 汇聚中心向下游局方研判座舱发布的单向风险通报与态势指令。 局端 Client 轮询获取到新通报后，以高优先级系统级弹窗呈现，用于突发国家安全重大态势即时预警。
{
"code": 200,
"message": "success",
"data": [
{
"id": 7,
"level": "urgent",
"title": "南海方向重大演训动态特别通报",
"content": "监测到多型外军电子侦察机在巴士海峡及南海北侧空域高频活动，请局端相关研判组重点强化电磁频谱与兵力布势交叉分析。",
"publisher": "SPARK-态势分析中枢",
"created_at": "2026-09-24T12:30:00Z"
}
]
}
6. 局端研判座舱生产级 Client 客户端源码实现
开箱即用的局端主动拉取守护进程，支持游标断点续传、五 Agent 数据分发与异常重试
7. HTTP 响应状态码与故障排查指南
标准化 HTTP 错误响应说明与快速诊断流程
| HTTP 状态码 | 含义说明 | 排查与处置方案 |
|---|---|---|
| 200 OK | 拉取成功 | 成品数据正常返回，局端将最大 ID 写入本地游标记忆并分发五 Agent |
| 401 Unauthorized | 缺失 API Key 或密钥无效 | 检查 HTTP 请求头是否正确设置 Authorization: Bearer <KEY> |
| 403 Forbidden | 局端密钥已禁用或数据权限受限 | 联系 SPARK 中枢管理员在后台【局端主动订阅开放网关】确认 Key 状态为 active |
| 429 Too Many Requests | 触发访问频控限流 | 局端拉取过于高频，建议主动轮询间隔设置为 15~30 秒，并采用指数退避重试 |
| 502 / 504 Timeout | 专线网络抖动或中枢服务重载 | 局端 Client 捕获异常并等待 5 秒后自动重试，勿立即并发重发 |