Andorra public sources

安道尔公共数据源

用于查找和查询安道尔公共数据源的教育目录和小型 Python 客户端。本文档介绍各数据源的 endpoint、重用条件、经验证的行为和实际使用中的注意事项，并通过 Python、MCP 服务和会引用数据来源的助手，展示部分实时数据。

独立教育项目。与安道尔政府或文中提及的任何机构均无关联。

数据源

ID	数据源	领域	访问方式
afa-feeds	安道尔金融管理局信息源	金融与监管	信息源
bopa	安道尔公国官方公报	法律与官方公报	api, downloads
carburants	加油站和参考价格	能源与燃油	arcgis-rest
cass-estadistiques	CASS 统计数据下载	社会保障	downloads
consell-general-feeds	安道尔总理事会新闻源	议会与公民信息	信息源
e-tramits	e-tramits 办理事项	公共服务与办事	html
estadistica-api	安道尔统计局 API	官方统计	api
govern-ad	安道尔政府信息页面	公共服务与办事	html
meteo-ad	meteo.ad 气象站图表	气象与气候	html
sig-arcgis	安道尔政府 ArcGIS Enterprise	地理与制图	arcgis-rest
transparencia	透明度门户	透明度与公共管理	html, downloads

各数据源的重用条件详见源数据的使用条件以及 sources/ 中的各数据源说明。

快速开始

需要 Python 3.10 或更高版本：

python -m venv .venv
.venv/bin/pip install -e ".[dev]"
.venv/bin/fonts-andorra-mcp

MCP 服务通过 stdio 通信。使用已安装的命令配置 Claude Desktop、Claude Code 或 Cursor：

{
  "mcpServers": {
    "andorra-fonts-publiques": {
      "command": "/absolute/path/to/andorra-fonts-publiques/.venv/bin/fonts-andorra-mcp"
    }
  }
}

安装 MCP 服务

使用 uvx 运行已发布的服务：

uvx fonts-andorra

Claude Desktop 配置：

{
  "mcpServers": {
    "andorra": {
      "command": "uvx",
      "args": ["fonts-andorra"]
    }
  }
}

带引用的助手

使用 Gemini REST API 提出带引用的问题。在环境中设置 GEMINI_API_KEY；此密钥不会保存在本仓库中：

GEMINI_API_KEY=... .venv/bin/fonts-andorra-ask "Quant triga l'autorització inicial de residència i treball?"
.venv/bin/fonts-andorra-ask "Where can I find official unemployment statistics?" --lang en --json

也可以直接导入客户端：

from fonts_andorra.clients.estadistica import data, search

tables = search("atur")
rows = data(1070)  # Per defecte, startDate=1900 i endDate=2100.

源数据条件

本仓库的代码和目录依据 CC0-1.0 贡献至公有领域。这不会改变源材料的许可：

• BOPA 允许复制、改编、提取和重新分发内容，但须满足以下条件：保留来源和更新元数据，不歪曲其含义，也不得暗示获得任何认可。
• Estadística 所有、由统计部提供的数据采用 CC BY 4.0 许可；第三方数据可能有自己的条件。
• govern.ad、e-tràmits 和 Transparència 是政府内容，保留所有权利。项目会实时下载网页正文、引用并链接到这些页面，但不会重新分发其内容。重新发布需要获得书面同意。本地政府索引仅包含标题、URL 和章节标题。
• ArcGIS 和燃油图层 按保留所有权利的政府内容处理，因为没有注明单项许可；项目会实时查询并链接到其来源，不会重新分发其内容。
• Feeds、meteo.ad 和 CASS：尚未提供或审查单项条件；重新分发数据前，请查阅发布方的条件。

目录会逐项列出来源和条件。商业使用或重新发布前，请核实每一项的条件。

目录文件

• sources/<id>.yaml 包含来源条目。
• schema/source.schema.json 和 schema/vocab.yaml 定义条目规范和封闭词汇表。
• indices/dead-routes.yaml 列出了无响应的域名，已于 2026-10-02 检查。
• catalog.json、llms.txt 和 llms-full.txt 使用 python scripts/build.py 生成。
• python scripts/validate.py 会检查来源架构、词汇表和相关来源标识符。

本地搜索索引

fonts_andorra/data/index.json 包含 e-tràmits 的标题和 URL；对于政府内容，则仅包含标题、URL 和章节标题。由于源内容保留所有权利，所有页面正文都会实时下载并引用。助手使用 BM25 在本地搜索手续和政府页面，并实时下载搜索到的页面；它不会使用政府网站的搜索引擎，该搜索引擎禁止使用。 若要根据 e-tràmits 和政府的加泰罗尼亚语站点地图重建索引，请运行 .venv/bin/python scripts/build_index.py；此生成器需要网络，因此不属于 CI 的一部分。

测试

测试可在离线状态下运行，并使用已保存的公开响应：

.venv/bin/ruff check .
.venv/bin/pytest -q
python scripts/validate.py
python scripts/build.py

CI

ci.yml 会在每次推送和拉取请求时运行 lint、离线测试、验证以及生成文件检查；live.yml 每周进行实时检查并上传报告。 live.yml 中的助手检查需要在仓库中设置密钥 GEMINI_API_KEY。

助手评估

evals/procedures.yaml 包含 10 项真实手续及其参考答案（费用、最长处理期限、申请期限以及是否需要亲自前往），这些答案取自 2026-10-02 的 e-tràmits 页面。运行方式如下：

GEMINI_API_KEY=... .venv/bin/python evals/run.py --baseline

最新结果（evals/results-2026-10-03.md，gemini-2.5-flash）：10/10 个案例均通过，引用了正确的手续，且 18/18 项数据正确。同一模型在没有来源的情况下答对 3/18 项。这 10 个案例也用于调整搜索，因此应将其视为回归测试集，而非独立评估。

保留集

evals/heldout.yaml 包含另外 20 个案例，均在调整完成后编写：15 个未用于调整的办事流程（ca/es/fr/en），以及 5 个任何此处的来源都无法回答的问题（天气、滑雪通票价格、边境排队情况、一位部长的私人电话号码，以及用户的休假日期）。助手必须拒绝回答，且不得给出任何数字。

GEMINI_API_KEY=... .venv/bin/python evals/run.py --cases evals/heldout.yaml --baseline

• 首次运行（evals/results-heldout-2026-10-03-first-run.md）：评分器给出 15/20。其中三处错误来自评分器（无法读取写成 [1, 2] 的引用，也不识别 “no se encontró” 是拒答）。对相同回答重新评分后，结果为 18/20。两个真正的错误：
  • 个人数据过滤器把 23-09-2026 这样的日期误认为电话号码，导致助手无法提供申请期限。现已修复。
  • 对于 “I'm selling my flat and need the habitability certificate”，助手根据 cèdula d'habitabilitat（2 个月）作答，而不是根据 certificat d'habitabilitat（72 小时）。这个问题有歧义，因为出售房屋需要的是 cèdula。
• 修正后（evals/results-heldout-2026-10-03.md）：20/20，23/23 项事实正确，5/5 个无法回答的问题均已拒答，且 0 条引用错误。同一个模型在没有来源的情况下只答对 6/23 项事实。关于居住适用证明的案例之所以通过，是因为搜索返回了其他办事流程，并非由于任何修正。关键词生成并非完全确定，因此这个案例可能会变化。

从此以后，这组案例就不再严格属于保留集：我们曾根据它发现并实施一项修正。新的失败必须用新的案例来修正。

面向政府的单页提案位于 docs/pitch.md。