API 参考

落地页

产品介绍、能力说明与数据源声明，首屏统计数字由 /api/stats 实时填充。

示例

curl -s "$BASE/?lang=en"

数据看板

看板主界面：智能查询、指标总表、自定义分析、统计公报、图表五个工作台。

示例

curl -s "$BASE/app?lang=zh"

本页

API 参考。内容按 ?lang= 服务端渲染，无需 JavaScript。

示例

curl -s "$BASE/docs?lang=en" | less

隐私与数据声明

对外分发后最常被问的三件事（收集什么 / 数据从哪来 / AI 会不会把问题发出去）的固定答案。同样服务端渲染、零 JS。

示例

curl -s "$BASE/privacy?lang=en"

前端资源

十二份前端资源：主题令牌 / 看板样式 / 落地页样式 / 看板逻辑 / 图表分块 / 命令面板分块 / 指标总分块 / 自定义分析分块 / 统计公报分块 / 双语运行时 / 全量词表 / 落地页词表。页面引用时每个资产各带自己的 内容哈希版本号 ?v=<sha256 前 12 位>，因此可以放心长缓存；改一个资产只换它自己的 URL，不会连带把别的资产也顶失效。/app.charts.js、/app.palette.js、/app.indicators.js、/app.custom.js 与 /app.bulletin.js 是 按需加载的分块：core（/app.js）只在首次用到时才动态拉取，首屏不下发。

无请求参数。

示例

curl -sI "$BASE/style.css" | grep -i cache-control

图标与分享卡片

og-image.png 为 1200×630 社交分享卡片（由 scripts/make_og_image.py 生成后 base64 内嵌，见 src/pages.py）。/favicon.ico 301 跳到 /favicon.svg：部分浏览器与爬机不看 <link rel=icon> 声明仍会直接要它，仓库里只有 SVG 图标，不重定向 就等于每次首访白吃一个 404。

无请求参数。

示例

curl -sI "$BASE/og-image.png" | grep -i content-type

SEO 资源

爬虫协议与站点地图，缓存 1 小时。

无请求参数。

示例

curl -s "$BASE/robots.txt"

数据规模

公开只读的聚合计数（记录数、知识条目数、覆盖经济体与年份），供落地页与看板侧栏展示。不含库路径等环境细节——那些在管理端点 /api/db。

无请求参数。

示例

curl -s "$BASE/api/stats"

概览卡片

按年份 + 维度返回关键指标卡片，每张卡片含本地化展示值、*_key（中文规范键）与 *_slug（ASCII 稳定键）；同时返回下拉框可选项。

示例

curl -s "$BASE/api/overview?year=2024&dimension=china&lang=en"

数据洞察

从本地公开数据算出可复算的年度变化：该维度同比变化最大的指标、覆盖最广指标上名次变动最大的经济体，以及本年度真实覆盖规模。每条洞察都带两年数值，可用 /api/indicators 复核；上一年缺失或为 0 的指标不进榜单，不给误导性百分比。

示例

curl -s "$BASE/api/insights?year=2024&dimension=china&lang=en"

指标宽表

面向程序消费的主要数据接口。每行的 category / indicator / dimension / unit 按 lang 本地化，并并列给出 *_key 与 *_slug——英文消费方无需任何中文词表即可使用。

示例

curl -s "$BASE/api/indicators?indicator=GDP&year=2024&lang=en"
# 或按关键词搜索（中英均可）
curl -s "$BASE/api/indicators?q=retail" | head -40

CSV 导出

把当前筛选结果导出为 CSV。列固定为 year,category,indicator,dimension,value,unit,note，内容带 BOM（utf-8-sig）以便 Excel 直接打开；文件名含年份、维度 slug 与语言。

示例

curl -s "$BASE/api/export.csv?year=2024&dimension=china&lang=en" \
  -o indicators_2024_china_en.csv

可绑定指标键

返回全部可绑定指标的三元组（专业 / 指标 / 维度），供「新建自定义分析」的变量下拉选择使用。

示例

curl -s "$BASE/api/indicator_keys?lang=en"

自定义分析（查询）

不带 name 时返回分析列表（含中英名称）；带 name 时求值并返回结果，compare 为真时附同比 yoy。名称中英皆可命中。

示例

curl -s "$BASE/api/custom?name=GDP&lang=en"

自定义分析（新增）

追加一条分析到配置文件。表达式在占位值上预校验可求值，且不允许重复名称；变量取值失败时返回 error 字段而不抛异常。

无请求参数。

请求体

JSON 请求体：
{
  "name": "第三产业占比",          // 必填，中文规范名
  "name_en": "Tertiary share",      // 可选，英文展示名
  "unit": "%",
  "description": "…",
  "description_en": "…",
  "variables": {                    // 必填，变量名 -> [专业, 指标, 维度(可选)]
    "x": ["国民经济", "第三产业增加值", "中国"],
    "y": ["国民经济", "GDP", "中国"]
  },
  "expr": "x / y * 100",            // 必填，安全求值
  "compare": true                   // 可选，是否计算同比
}

示例

curl -s -X POST "$BASE/api/custom" \
  -H 'Content-Type: application/json' \
  -d '{"name":"Tertiary share","variables":{"x":["国民经济","第三产业增加值","中国"]},"expr":"x"}'

统计公报

按年份 + 维度生成公报。format=json 返回结构化数据（标识符已由服务端本地化，交前端渲染）；缺省返回纯文本 Markdown。cloud=1 时附云端 AI 解读。

示例

curl -s "$BASE/api/report?year=2024&format=json&lang=en"

自然语言查询

把一句自然语言问题解析为指标查询并返回统计结果。cloud=1 时，本地统计结果先作为事实上下文再交给云端模型（提示词中明确要求只依据给定数字），避免模型编造数据；云端不可用时退回本地统计并在 注 字段说明。

示例

curl -s "$BASE/api/ask?text=2024%20GDP&lang=en&cloud=0"

集成自检

按 agent_infini Skill 规范返回推荐工作流与资源预检结果；只读、不触发任何云端调用，CLI 不可用时优雅降级。

示例

curl -s "$BASE/api/infini_skill"

解读缓存指标

AI 解读缓存的运行指标：命中 / 未命中计数、L1 容量、Redis 是否可用。只读、无副作用，用来验证「重复提问真的没有重复打云端」。

无请求参数。

示例

curl -s "$BASE/api/ai-cache"

知识库（查询）

列出或搜索知识条目；命中结果会作为本地统计的补充上下文出现在问答结果中。

示例

curl -s "$BASE/api/knowledge?q=GDP"

知识库（新增）

新增一条知识条目，title 与 content 必填。

无请求参数。

请求体

JSON 请求体：{"title": "…", "content": "…", "category": "通用", "tags": "gdp,trade", "source": "…"}

示例

curl -s -X POST "$BASE/api/knowledge" \
  -H 'Content-Type: application/json' \
  -d '{"title":"GDP 口径","content":"…"}'

知识库（删除）

按 id 删除条目。

示例

curl -s -X DELETE "$BASE/api/knowledge?id=1"

库状态

返回数据库路径、引擎、体积与各表行数。含环境细节，故列入管理端点。

无请求参数。

示例

curl -s "$BASE/api/db" -H "X-Admin-Token: $ADMIN_TOKEN"

重新播种

清空指标表后重新载入内嵌的真实公开数据种子集，并清除 KV 旧快照。会覆盖库内数据。

无请求参数。

示例

curl -s -X POST "$BASE/api/reseed" -H "X-Admin-Token: $ADMIN_TOKEN"

KV 状态

检查 Redis / Vercel KV 持久化连接：环境变量存在性（已脱敏）、写入与回读。

无请求参数。

示例

curl -s "$BASE/api/kv-status" -H "X-Admin-Token: $ADMIN_TOKEN"

数据采集

从世界银行 Open Data 拉取指定指标并入库（公开数据源，无需鉴权）。需要可写磁盘，故线上默认关闭。

无请求参数。

请求体

JSON 请求体：{"source": "worldbank" | "global", "year": 2024, "country": "CN", "indicators": "NY.GDP.MKTP.CD"}

示例

curl -s -X POST "$BASE/api/collect" \
  -H 'Content-Type: application/json' -H "X-Admin-Token: $ADMIN_TOKEN" \
  -d '{"source":"worldbank","year":2024,"indicators":"NY.GDP.MKTP.CD"}'

健康检查

探活端点：始终返回 200，用 status 区分健康与降级。不播种、不鉴权，适合部署平台的存活探针与外部监控；version 用来确认线上跑的是哪一版，uptime_s 则暴露「刚刚重启过」这个排查线索。

无请求参数。

示例

curl -s "$BASE/healthz"