ChelseaKR/gtfs-scorecard

# GTFS Scorecard [](https://github.com/ChelseaKR/gtfs-scorecard/actions/workflows/ci.yml) [](LICENSE) [](https://github.com/marketplace/actions/gtfs-scorecard-gate) [](https://gtfsscorecard.org) [](https://gtfsscorecard.org) 面向小型公共交通机构的数据质量记分卡。它会获取交通机构的 **GTFS Schedule** 数据源，并在已发布和配置的情况下获取其 **GTFS-Realtime** 数据源；运行标准的 MobilityData 验证器，并将结果转化为字母评级以及一份简明的具体修复清单（包含 NTD GTFS 就绪度）。该记分卡专为从供应商处接手数据源的交通机构管理者编写，而非面向开发者。 试点机构：[Unitrans](https://unitrans.ucdavis.edu)（ASUCD / 戴维斯市）和 [Yolobus](https://yolobus.com)（Yolo 县交通局）。除试点外，注册表现在包含美国和加拿大各地的约 1,140 条数据源记录（约 1,450 个已发布的记分卡页面），每日刷新。一条数据源记录并不总是代表一家独立的交通机构：在进行身份注册表对账时，区域性数据源、交通模式变体以及已废弃的别名会被单独计算。 **在线演示：** [gtfsscorecard.org](https://gtfsscorecard.org/) — 每日通过计划中的 pipeline 运行进行刷新。 **状态：** Beta 版。三个排期类别会对所有已发布的记分卡进行评分。实时质量仅在配置并测量到可用的实时数据源时才会进行评分；否则将以中立的方式显示为“尚未测量”。任何机构都可以通过 `agencies.yaml` 进行添加。 ## 机构将获得什么 - 根据可测量的类别（准确性、新鲜度、乘客体验完整度，以及实时可用时的实时质量）得出的总体评级。 - “最需修复的 3 个问题”，采用通俗易懂的语言并提供工作量提示。所有发现均以“修复”的形式提出，绝不视为“失败”。 - NTD GTFS 就绪度评估（已发布、有效、最新），以及标识该数据源的 `agency_id` 是否与机构的 NTD ID 匹配的标记。 - 历史趋势记录，每个机构每天生成一份 JSON 构件。 - 一个可嵌入的评级徽章 (`/badge.svg`)，机构可以将其放置在自己的开发者页面上。 评分方法及其对《加利福尼亚州交通数据指南 v4.0》和验证器规则分类体系的引用，详见 [docs/rubric.md](docs/rubric.md)。方法论的变更受到严格管控：验证器版本升级在合并前必须附上来自 `scorecard canary` 的影子运行影响报告（详见 rubric.md 中的“受管控的升级”）。 数据源及其许可证信息详见 [docs/feeds.md](docs/feeds.md)。后续规划分为两部分：基础设施与扩展计划详见 [docs/roadmap.md](docs/roadmap.md)，面向用户的产品发展路线详见 [docs/product-roadmap.md](docs/product-roadmap.md)。 ## 网站包含哪些内容 每个机构都会获得一个记分卡页面，以及为机构会议中不同角色编写的三个配套页面：面向董事会的一页纸摘要 (`/agency//board/`)、会议准备简报 (`/brief/`) 和修复日志 (`/fixes/`)。围绕这些内容，还有： - **全国视图** — 全国概览 (`/pulse/`)、最常见的问题 (`/problems/`)、实时可靠性 (`/realtime/`)、新能力采用与无障碍数据覆盖情况 (`/adoption/`)、NTD 就绪度 (`/ntd/`)、美国与加拿大的公平性叠加图层 (`/equity/`)，以及全国路线图 (`/map/`, `/routes/`)。 - **项目页面** (`/program//`)，涵盖 46 个州及哥伦比亚特区，以及来自 [`rollups.yaml`](rollups.yaml) 的命名群组，每个页面都列出了该群组共有的修复项。 - **从业者工具** — 即时评估任何数据源 (`/try.html`)、在发布前检查数据源 (`/check/`)、对比两家机构 (`/compare/`)、在浏览器中使用 SQL 查询数据集 (`/query/`)，以及将数据源质量写入供应商合同 (`/procurement/`)。 - **修复知识库** (`/fix//`，每种常见的验证器发现对应一页通俗易懂的说明) 以及标准交叉参考表 (`/crosswalk/`)。 - **机器可读接口** — 版本化的只读 API（[docs/api.md](docs/api.md)）、用于批量 SQL 查询的 Parquet 表、每个机构独立的徽章和合规标志、Atom 更新订阅源、每月可引用的数据集发布，以及只读 MCP 服务器（[docs/mcp.md](docs/mcp.md)）。 ## 快速开始 要求安装 Python 3.12+、[uv](https://docs.astral.sh/uv/) 和 Java 17+（验证器 jar 包会在首次运行时自动下载）。 ``` cd pipeline uv sync uv run scorecard run --all ``` 此命令会获取每个试点数据源的当日快照，进行验证和评分，并将结果写入 `data/artifacts//.json`，同时生成一个 `latest.json` 和跨机构的 `index.json`。同一天重复执行是幂等的。检查（在仓库根目录运行，与 CI 门禁逻辑一致）： ``` make verify ``` ### 在本地运行 Web 应用 前端通过 HTTP 读取 JSON 构件。请托管仓库根目录并通过 `http://` 访问页面，不要直接双击文件打开： ``` cd .. # repo root, so data/artifacts/ is reachable python3 -m http.server 8000 # 然后打开 http://localhost:8000/web/index.html ``` 如果将 `web/index.html` 作为 `file://` URL 打开，页面会一直卡在“Loading scorecards…”：因为浏览器会阻止 ES module 加载和针对 `file://` 的 `fetch` 请求，导致应用无法运行。任何静态服务器都可以；唯一的要求是 `data/artifacts/` 必须位于 `web/` 的上一级目录，这也是 `web/src/app.js` 中的 `../data/artifacts` 回退逻辑所期望的路径。 ## 在 CI 中使用 使用已发布的 Action 将你自己的 pipeline 门禁设置为基于数据源质量。它会对数据源进行评分，在任务日志中打印评级和首要修复项，并在数据源评级低于 `min-grade` 或在 `min-days-to-expiry` 内过期时使构建失败： ``` - uses: ChelseaKR/gtfs-scorecard@v1 with: feed-url: https://your-agency.example/google_transit.zip min-grade: C min-days-to-expiry: 14 ``` 这两个阈值都是可选的；留空则跳过相应检查。完整的输入参数说明和完整的工作流详见 [docs/ci-action.md](docs/ci-action.md)。 ## 规模化运营 除了 `run` 之外，CLI 还包含了推广计划所需的各项命令： ``` scorecard sync --country US --state California # propose agencies.yaml entries # from the Mobility Database scorecard shards --count 4 # JSON fan-out plan for CI scorecard reindex # rebuild index.json from disk scorecard rollups # publish program rollup artifacts scorecard render-site # crawlable static pages + sitemap scorecard alerts --out digest.md # expiry/regression digest scorecard notify # per-subscriber digest (dry run) ``` `notify` 会为 [`subscriptions.yaml`](subscriptions.yaml) 中每位开启订阅的用户生成一封数据源健康邮件，仅在他们关注的机构需要关注时发送，且只包含这些机构的信息。默认情况下，它会打印出邮件内容；当操作员验证了发件人、应用了 `infra/artifacts` 中的 SES 授权，并设置了 `SES_FROM` 仓库变量后，每日工作流即可通过 SES 发送这些邮件。 每日工作流会将机构分散到一个并行矩阵中，并且在应用 `infra/artifacts` 后，可以将构件镜像同步到由 CloudFront 支持的 S3 存储桶（参见 ADR 0002）。项目汇总在 [`rollups.yaml`](rollups.yaml) 中配置为命名群组（如联络员负责的机构、某个地区或整个州），并展示在 `#/programs` 页面；只有当某机构的数据源即将过期或评级倒退时，才被标记为“需要关注”，而不仅仅是因为评级低于 B。已发布的 JSON 提供了公开的只读 API（详见 [docs/api.md](docs/api.md)）；系统在 `/catalog.json` 和 `/catalog.csv` 提供了包含每个机构的目录（评级、得分、数据源 URL、剩余有效天数、首要修复项），这样使用者只需一次请求即可获取所有信息，而无需逐个机构请求。 ### 路线图状态：已构建与已部署 [路线图](docs/roadmap.md) 规划了从两个试点数据源发展为全国性服务的路径。第一年的软件已经构建、测试并基本部署完毕；[部署手册](docs/deploy.md) 介绍了 AWS 技术栈并提供了当前的部署状态。 | 路线图模块 | 仓库内位置 | 状态 | | --- | --- | --- | | Mobility Database 同步 | `scorecard sync` (`mobilitydb.py`) | 按需运行 | | 分片每日运行 | `scorecard shards` + CI matrix | Actions 中实时运行 | | 过期/倒退告警 | `scorecard alerts`, `notify --send`, `infra/alerts` | 已应用并生效；SES 发件人已验证，摘要每日发送 | | S3 + CloudFront 构件 | `infra/artifacts` | 已应用并生效；每日镜像已开启，站点仍通过 Pages 提供服务 | | 自助提交表单 | `web/submit.html`, `infra/submit` | 已构建；endpoint 需要执行 `terraform apply` | | 即时评分 | `web/try.html`, `infra/instant-score` | 已构建；在应用前回退到 issue-form 路径 (ADR 0029) | | 扇出计算 (第二年) | `infra/compute` (SQS + worker) | 已构建；在每日运行超出 Actions 矩阵承受能力时再应用 | 从 Mobility Database 初步提取的机构群组早已远超第一次加利福尼亚州评估的范围：[`agencies.yaml`](agencies.yaml) 现在包含了美国和加拿大各地约 1,140 家经过筛选的机构，每日进行评分（2026 年 7 月的一次去重操作移除了约 350 条与已收录数据源重复的记录）。 ## 添加你的机构 任何拥有公开 GTFS 数据源的机构，只需在 [`agencies.yaml`](agencies.yaml) 中添加一个 YAML 代码块并提交 pull request 即可被收录；具体操作流程详见 [docs/add-your-agency.md](docs/add-your-agency.md)。一旦部署了 [`web/submit.html`](web/submit.html) 的 Serverless endpoint (`infra/submit`)，你也可以通过该 Web 表单完成同样的操作，无需编写 YAML。 ## 标准合规性 本仓库受 [`docs/standards/`](docs/standards/) 中引入的共享项目集标准管辖（锁定到特定 tag — 绝不在本地直接修改；请参阅该目录历史记录中的完整性说明）。根据 `docs/standards/README.md` 中的合规性规则，所有适用的标准都在此声明；没有任何标准会被静默忽略。 | 标准 | 是否适用？ | |---|---| | [CODE-QUALITY](docs/standards/CODE-QUALITY-STANDARD.md) | 适用 (Python；TS/Node 不适用 — `web/` 为无构建的纯 JS) | | [SECURITY & SUPPLY-CHAIN](docs/standards/SECURITY-AND-SUPPLY-CHAIN-STANDARD.md) | 适用 (ASVS L1 形态：无身份验证，无 PII 存储) | | [CI/CD](docs/standards/CI-CD-STANDARD.md) | 适用 | | [OBSERVABILITY](docs/standards/OBSERVABILITY-STANDARD.md) | 适用 — Tier B (前端) + Tier C (批处理 pipeline)；参见 [ADR 0031](docs/decisions/0031-observability-tier.md) | | [ACCESSIBILITY](docs/standards/ACCESSIBILITY-STANDARD.md) | 完全适用 — 公共内容，自我声明符合 WCAG 2.2 AAA (参见 [docs/accessibility.md](docs/accessibility.md), [docs/vpat.md](docs/vpat.md)) | | [INTERNATIONALIZATION](docs/standards/INTERNATIONALIZATION-STANDARD.md) | 适用 — 公共交通数据，面向公众；不存在不适用的路径 | | AI-EVALUATION | **不适用** — 在任何面向用户或决策环节中均无模型推理 (`AI-EVALUATION-STANDARD` §0)；MCP server (`server.json`) 仅用于只读数据检索，未使用 LLM SDK。一旦首次使用 LLM SDK，状态将切换为“适用”。 | | [QUALITY & METRICS](docs/standards/QUALITY-AND-METRICS-STANDARD.md) | 适用 (专门为该仓库指明了数据质量/血缘) | | [DOCUMENTATION](docs/standards/DOCUMENTATION-STANDARD.md) | 适用 | | [RELEASE & VERSIONING](docs/standards/RELEASE-AND-VERSIONING-STANDARD.md) | 适用 — marketplace action tags (`v1`/`v1.0.0`)，月度数据集发布，MCP registry entry | | [RESPONSIBLE-TECH](docs/standards/RESPONSIBLE-TECH-FRAMEWORK.md) | 适用 (审计 A-F；AI 治理相关项不适用 — 无 AI 系统) | 根据最近的合规性审计，各标准对应的未解决问题详见 [docs/standards-conformance-gaps.md](docs/standards-conformance-gaps.md)，不再赘述。 ## 可观测性 **Tier B (前端) + Tier C (批处理 pipeline)** — 并非 `OBSERVABILITY-STANDARD` 针对本仓库类别默认映射的 Tier-A；具体原因请参见 [ADR 0031](docs/decisions/0031-observability-tier.md)。简而言之：已部署的系统是一个定期的 Actions 批处理任务加上一个静态站点，而不是一个长期托管的服务（`infra/compute` 是能让本系统达到 Tier A 的部分，已构建但尚未应用）。Tier C 的健康/追踪/SLO 控制项不适用（没有需要探测的网络接口）；Tier B 的 Core Web Vitals 实验室门禁适用，并作为待办事项进行跟踪（目前 Lighthouse 仅断言无障碍性）。真实用户监控信标被刻意禁用 — 详见该 ADR。 ## 版本控制 采用 SemVer。公开的 API 表面包括已发布的 JSON schema (`schema_version`)、GitHub Action 的输入 (`action.yml`) 以及 CLI (`docs/api.md`)。`pipeline/pyproject.toml` 中的 `[project].version` 是唯一的真理来源；`CITATION.cff` 和 `server.json` 会与之保持同步，一旦出现偏差，`pipeline/scripts/check_versions.py` 将导致 `make verify` 失败。 支持版本策略：仅支持最新的主版本 — 这是一个单一部署的公共服务工具，而不是一个有多个使用者依赖旧主版本的库。 本仓库还**负责生成发布版本**：marketplace GitHub Action (标记为 `v1`)、每月可引用的数据集发布 (`dataset-release.yml`) 以及 MCP registry entry (`server.json`)。 ## 运行你自己的实例 州级 DOT、国家 RTAP 或国家级项目可以 fork 本仓库，并通过配置和部署建立拥有自己品牌标识的实例 — 独立的域名、独立的机构注册表、独立的组织名称 — 无需修改代码：[docs/fork-quickstart.md](docs/fork-quickstart.md)。 ## 布局 ``` agencies.yaml the agencies the scorecard tracks; add yours here instance.example.yaml fork branding template; copy to instance.yaml to rebrand rollups.yaml program rollups (portfolio views across many agencies) pipeline/ Python pipeline: fetch -> validate -> score -> publish web/ static frontend; reads only published JSON infra/ Terraform: artifacts CDN, submission function, fan-out compute docs/ feeds, rubric, roadmap, api, fixes/ (KB), decisions/ (ADRs) data/ raw snapshots (ignored) and published artifacts (committed) ``` ## 面向 Claude Code `CLAUDE.md` 是构建规范：产品定位、评分细则和质量标准。最初的四个构建阶段已交付；当前的方向见各项路线图和 [docs/ideation/](docs/ideation/)。硬性规定：每一个指标在推出时都必须附带通俗语言的解释；Web 应用中的无障碍性 (WCAG 2.2 AAA) 是不可妥协的底线；对于没有实时数据源的机构，展示时必须保持中立，绝不能进行贬低。 ## 维护者 由 [Chelsea Kelly-Reif](https://chelseakr.com) 构建并维护，起步于加利福尼亚州戴维斯的交通系统。欢迎贡献代码和提出修改意见；机构可以根据[列表收录与移除政策](docs/listing-policy.md)申请加入或移出。

标签：GTFS, JS文件枚举, MCP, 公共交通, 后端开发, 数据可视化, 数据校验, 数据质量, 自动化CI, 逆向工具