内容
# 公民超级代理 — 数据湖 + 公开数据公民地图
公民技能AI Commons和**数据湖**，包含意大利公开数据，**以市镇为单位**，具有一个智能层（MCP），使得每个市镇都可以用自然语言阅读 — 每个数据都源自**可引用的来源**。
> 公共摘要 → [`civic-superagents.md`](civic-superagents.md) · **已验证的数据源地图** → [`notes/mappa-open-data-civici.md`](notes/mappa-open-data-civici.md).
## 状态
基于 **Supabase** 的数据湖（Postgres + 存储 + PostGIS）。**16个源系统 / 17个数据集**，**超过190万行**，主要为**全国性**数据（空气质量覆盖了约有中央监测站的市镇）。通过 **MCP** 提供服务层，包含 **11种工具**（可在本地执行或部署为HTTP服务器 — 参见 [`mcp/`](mcp/README.md)）。每个数据的出处（`meta.fonti` → 存储中不可变文件 `raw/`）。
## 数据湖中包含的内容
| 主题 | 来源 | 表 `mart.*` | 覆盖范围 |
|---|---|---|---|
| 山体滑坡/洪水风险 | ISPRA IdroGEO | `idrogeo_comune` | 🇮🇹 7,896个市镇 |
| 垃圾/分类垃圾 | ISPRA Catasto Rifiuti | `rifiuti_comune_anno` | 🇮🇹 2020-24 |
| 土地利用 | ISPRA | `consumo_suolo_comune` | 🇮🇹 7,890个市镇 |
| 空气质量（PM10） | EEA（年度总结） · ARPA Lombardia（试点） | `aria_comune_anno` · `aria_misure` | 有中央监测站的市镇 |
| 学校建筑 | MIUR | `scuola_edificio` | 🇮🇹 39,331栋建筑 |
| 人口/人口统计 | ISTAT SDMX | `geo.comuni.popolazione` | 🇮🇹 7,890个市镇 |
| **任务支出** | BDAP FET Rendiconto | `bilancio_comune` | 🇮🇹 2024（99%） |
| 招标（中标者） | ANAC | `appalto` | 🇮🇹 2024, ~313k（≥ €40k） |
| 凝聚力基金 | OpenCoesione | `progetto_coesione` (+`_comune`) | 🇮🇹 2021-27, 171k项目 |
| 国家恢复和韧性计划 | OpenPNRR | `pnrr_progetto` (+`_comune`) | 🇮🇹 291k项目 |
| 谁在执政 | 内政部 DAIT | `amministratore_comune` | 🇮🇹 115k |
| 文化 — 图书馆 | ICCU | `biblioteca_comune` | 🇮🇹 19,598个图书馆 |
| 水 — 海水浴 | EEA/WISE（EMODnet） | `balneazione_sito` | 🇮🇹 沿海/湖泊站点 |
| 能源 — 社区可再生能源 | GSE | `cer_comune` | 🇮🇹 751个市镇 |
| 福利 — 托儿所 | ISTAT SDMX | `welfare_comune` | 🇮🇹 7,898个市镇 |
## 智能层
`mcp/` 将数据湖暴露为 **11种公民工具**（参见 [`mcp/README.md`](mcp/README.md)）— 由代理进行公民叙述，数据层返回引用数据：
- **`cerca_comune`** / **`leggi_comune`** — 解析一个市镇并提供完整的公民资料（环境 · 学校 · 文化 · 福利 · 能源 · **任务预算** · 招标 · 凝聚力基金+国家恢复和韧性计划 · **财务副本** · 谁在执政），每个数字都有其 **来源**。
- **`progetti_comune`**，**`confronta_comuni`**，**`classifica`**，**`appalti_comune`** — 针对mart的查询。
- **`helper_foia`** — 公民访问请求的草稿，附有法规参考。
- **`domande_da_verificare`/`firma_risposta`** 和 **`fonti_da_verificare`/`verifica_licenza`** — 测试集和许可证的人工审查。
```bash
npm run mcp # MCP服务器（stdio，本地）
npm run start:http # MCP服务器（Streamable HTTP）— 使用MCP_AUTH_TOKEN保护/mcp
```
在Claude Code中本地注册：
```bash
claude mcp add civic-superagents -- npx tsx /ABS/PATH/civic-superagents/mcp/stdio.ts
```
## 来源许可证
每个来源都已验证（附有测试URL）。**引用来源**可自由重用；两个来源为 **共享相似**。
| 来源 | 许可证 |
|---|---|
| ISPRA — IdroGEO, Catasto Rifiuti, Consumo di suolo | CC-BY-4.0 |
| ISTAT — 人口，早期儿童服务 | CC-BY-4.0 |
| ANAC — 招标 | CC-BY-4.0 |
| 内政部 DAIT — 行政人员 | CC-BY-4.0 |
| OpenCoesione — 凝聚力项目 | CC-BY-4.0 |
| EEA — PM10空气质量，海水浴（通过EMODnet） | CC-BY-4.0 |
| Openpolis geojson-italy — 边界（来自ISTAT） | CC-BY-4.0 |
| MIUR — 学校建筑 | IODL-2.0（≈ CC-BY） |
| BDAP / MEF-RGS — 账户 | CC-BY-3.0 |
| dati.lombardia（ARPA）— 空气 · ICCU — 图书馆 | CC0-1.0 |
| **OpenPNRR** — 国家恢复和韧性计划项目 | **ODbL-1.0** ⚠️ *共享相似* |
| **GSE** — 社区可再生能源 | **CC-BY-SA-3.0-IT** ⚠️ *共享相似* |
> ⚠️ **组合数据集** 包含两个 **共享相似** 来源（OpenPNRR ODbL-1.0，GSE CC-BY-SA-3.0-IT）：派生作品应以相同许可证共享，数据湖 **不能作为CC0重新分发**。应始终归因于使用的所有来源（`leggi_comune` 公开每个资料的 `fonti`）。
>
> **此仓库**：代码 **EUPL-1.2**，提示和文档 **CC-BY-SA-4.0**（参见 [`LICENSE`](LICENSE) 和 [`LICENSES/`](LICENSES/)）。**数据** 仍然在各自来源的许可证下，如上。
## 结构
```
supabase/ Supabase项目：config.toml + migrations/（geo · meta · glossary · mart）
ingestors/ 每个来源的模块（fetch → land 存储 → load → upsert mart → 注释）+ manifest.yaml
_framework/ 下载 · 存储 · 来源 · 实用程序（IT解析器，规范名称，批量Upsert）
mcp/ MCP服务器（11种工具）— 通过SUPABASE_DB_URL_READONLY只读（civic_serve角色）
glossary/ 精心整理的JSON查找表
notes/ 巩固的地图 + 每个来源的注释（操作技巧）
tests/ questions.jsonl — 16个公民问题，附有手动验证的答案
rfc/ · LICENSE · CONTRIBUTING.md · LICENSES/ 治理RFC样式，EUPL-1.2 + CC-BY-SA-4.0
```
## 不可妥协的原则
- **严格的引用政策**：每个数字 → 行 `meta.fonti` → 存储中不可变文件 `raw/`。无来源不回答。
- **市镇是关键**：所有内容都与 `geo.comuni`（ISTAT / pro_com / 地籍 / PostGIS）连接。
- **声明的陷阱**：候补名单，可饮用水，火车延误，市镇犯罪率 → *"未发布"*，永不承诺。
- **意大利API在沉默中更改** → 在每次发布前重新验证来源的活跃度。
## 设置
从 [`.env.example`](.env.example) 复制 `.env`（Supabase：URL，服务角色密钥，**连接池** `SUPABASE_DB_URL`）。然后 `supabase db push`，`npm run ingest:wedges` / `ingest:money`，`npm run verify`，`npm run mcp`。详见 `ingestors/README.md`。
> ⚠️ 意大利公共API经常在沉默中更改：在任何重新分发之前，请重新验证来源的活跃度。空气值是操作的，不是认证的。
