ABS Data (observed)

ABS Data API — 制图与前门

本项目通过逐一检索，测量了澳大利亚统计局数据 API 实际提供的内容——涵盖每个数据流—— 并将结果作为类型化前门开放：一个 MCP 服务和一个 HTTP API， 只提供实际存在的内容。

前门	https://abs-data-front-door.aicolab.workers.dev
添加到 claude.ai / 任何 MCP 客户端，作为连接器	https://abs-data-front-door.aicolab.workers.dev/mcp（注册表名称 io.github.AI-CoLab/abs-data）
MCP（2026-07-28，无状态）——4 个固定动词 + Code Mode search/execute、资源、提示词	https://abs-data-front-door.aicolab.workers.dev/mcp
RPC 门（Cap'n Web；@abs/sdk 使用的协议——HTTP 批处理或 WebSocket）	https://abs-data-front-door.aicolab.workers.dev/rpc
HTTP API	https://abs-data-front-door.aicolab.workers.dev/api/tables
Scalar 参考文档	https://abs-data-front-door.aicolab.workers.dev/api/docs
修正后的 OpenAPI	https://abs-data-front-door.aicolab.workers.dev/api/openapi.json
汇总为单个文档的菜单	https://abs-data-front-door.aicolab.workers.dev/api/catalogue.json
可实时浏览的目录	https://abs-data-front-door.aicolab.workers.dev/catalogue
静态快照（claude.ai artifact）	https://claude.ai/code/artifact/d0635dee-5cce-40dd-bfa2-7ab7dd03e5bd

发现结果

• 1,227 个数据流中共有 621,536,714 个序列。ABS 的元数据推算为 14,761,557,818 个——密度仅为 4.21%，高估了 23.8 倍。
• 各维度的元数据完全准确：所有标注的选项都确实存在，也没有未标注的实际选项。全部高估都来自组合计算。
• 81.0% 的序列位于稀疏性有明确依据、且已通过键值验证的数据流中——几乎全是通过独立维度编码的分层地理信息（在 664 个数据流中，STATE 是 REGION 的函数）。其余 19% 无法简化为单维度依赖。
• detail=serieskeysonly——本应回答“哪些内容存在”的端点——已损坏（HTTP 200，但 JSON 格式错误）。15 项有文档记录的行为中，有 8 项不符合预期。详见 reports/。

DESIGN.md 记录了完整内容：经过验证的 API 发现结果、每项决策及其原因，以及过程中所做的修正。

目录结构

packages/schema      Drizzle schema (declared vs observed, never joined), shared CSV/period parsing
packages/crawler     structural crawl, observed probe, conformance suite, sizing
packages/catalogue   delta report, sparsity analysis, contract generator, OpenAPI emitter, artifact
packages/contract    the corrected contract: stable Zod verbs + generated tables/options (per crawl)
packages/worker      the front door: MCP door (SDK v2) + HTTP door (oRPC + Scalar) + RPC door (Cap'n Web) on one Worker
packages/sdk         @abs/sdk — typed TypeScript client over the RPC door (connect(), invalidSelectionFromError())
reports/             delta.md/json, sparsity.md/json, openapi.json, abs-report-draft.md
data/                local SQLite catalogue (~400GB), raw archive, D1 import SQL — not committed

运行

pnpm install
pnpm db:migrate                       # local SQLite at data/abs-catalogue.sqlite

pnpm crawl:structural                 # 7 bulk requests, ~1 minute
pnpm crawl:probe -- '--key-values=*'  # every dataflow by retrieval; ~24h, 20GB heap for the giants
pnpm report:delta && pnpm report:sparsity
pnpm generate:contract                # -> packages/contract/src/generated, data/d1/*.sql
pnpm --filter @abs/catalogue emit:openapi

cd packages/worker
npx wrangler d1 execute abs-catalogue --local --file=../../data/d1/00-schema.sql   # then each data file
npx wrangler dev
ABS_MCP_URL=http://localhost:8787/mcp npx tsx test/protocol.ts                     # ~50 checks, all doors
pnpm --filter @abs/sdk example                                                     # the SDK against production
ABS_URL=http://localhost:8787 npx tsx test/limits.ts                               # rate limits (spends a minute's budget)

速率限制按客户端地址计算：整体每分钟 600 个请求；数据拉取每分钟 120 个请求（每次都会实时调用 ABS）；Code Mode execute 每分钟 20 个请求。超出限制时，HTTP 接口会返回 429 和 Retry-After；MCP 工具调用则会返回工具错误。

使用 TypeScript SDK：

import { connect, invalidSelectionFromError } from "@abs/sdk";

const abs = connect(); // https://abs-data-front-door.aicolab.workers.dev/rpc
const [hits, cpi] = await Promise.all([          // one HTTP batch
  abs.searchTables({ query: "cpi rent", limit: 3 }),
  abs.describeTable("CPI"),
]);
try {
  const data = await abs.getData({ table: "CPI", select: { REGION: "Sydney", INDEX: "10001" }, lastN: 4 });
} catch (err) {
  const invalid = invalidSelectionFromError(err); // typed: reason, dimension, validOptions from observation
}

探测过程支持断点续跑：重新运行时会跳过已记录为完成的数据流。对最大的 census 数据流运行时，请使用 NODE_OPTIONS=--max-old-space-size=20480。

注意：wrangler 会根据 database_id 标识本地 D1 状态。更改 wrangler.toml 中的 ID（例如在 d1 create 之后）会让 wrangler dev 创建一个全新、空的本地数据库——请重新执行本地导入。

原则

• 仅依据观测结果。 声明的元数据用于引导爬虫并生成缺陷报告；绝不会进入调用方看到的内容。可用性以实测为准：选项来自目录中的观测结果，精确组合则实时通过 ABS 的 availableconstraint 检查（该检查在每个数据流的每个维度上都与探测结果一致）。
• 一份契约，派生出多个入口。 每次爬取都会重新生成一份契约；MCP 动词、HTTP 路由、OpenAPI 文档和文档内容都会读取或呈现这份契约。没有任何入口是硬编码的，因此不会出现偏差。
• 只调用能返回数据的内容。 转发前会验证所选内容；无效选择会返回观测到的有效选项——在 MCP 上作为 MRTR input_required 返回，在 HTTP 上作为类型化 422 返回。