内容
# 产生的废水地图
**一个包含超过 113,000 个 USGS 产生的废水样本的交互式地图，内置 Claude 数据分析师。**
用简单的英语提问 — *"哪个地区的样本在 USGS 数据库中最多，平均 TDS 是多少？ "* — 内置的 Claude 代理会编写 SQL，实时查询数据，并解释答案。所有 113,131 个样本都在浏览器中实时渲染和过滤。
## 为什么
产生的废水 — 即在开采石油和天然气过程中产生的咸水 — 是像 Permian 这样的盆地中一个主要的环保挑战，如果经过处理，也可以成为一种潜在的资源。USGS 发布了一个优秀的地球化学数据库，但它是一个包含 113,000 行和 209 列的电子表格。需要这个数据库的人（水资源研究人员、处理工程师、监管机构）大多并不擅长 SQL。因此，这个项目最初是一个数据可视化工具，后来添加了一个 AI 分析师，允许领域专家以对话方式查询数据。
## 功能
**地图** — 美国大陆的每个样本，使用 deck.gl 和 MapLibre 渲染，按播放类型着色，按区域/盆地/播放过滤，具有暗色、街道和卫星底图。整个数据集作为 25 MB 的 SQLite 数据库传输到浏览器，并在 WebAssembly 工作线程中进行客户端查询 — 平移、缩放和过滤都是即时的，并且在热路径中没有服务器。
**分析师** — 一个 Claude 代理（Claude Agent SDK），嵌入在地图旁边的聊天窗口中，带有两个工具服务器：
- **井数据上的 SQL** （MCP）：模式检查、查询规划、针对 USGS 数据库的只读 SELECT
- **Jupyter 笔记本** （MCP）：代理可以构建和执行笔记本进行深入分析，并将执行结果交给您
代理在锁定的工具策略下运行 — 仅限于该应用的 MCP 工具，无 shell，无文件写入，无网络获取，与主机上的任何 Claude 设置隔离。
## 架构
```
apps/frontend SvelteKit + Svelte 5 · MapLibre GL + deck.gl · SQLite WASM worker
apps/backend FastAPI · Claude Agent SDK · SSE streaming chat
├── MCP: query_wells (read-only SQL over USGS data)
└── MCP: jupyter (notebook build + execute)
data/ USGS 国家产生的废水地球化学数据库 v3.0（CC0）
转换为优化的 SQLite（精简版：25 MB / 完整版：43 MB）
```
## 运行
```bash
# 先决条件：node + pnpm，python + uv，Anthropic API 密钥（或 Claude Code 授权）
pnpm install
# 前端（地图独立运行）
pnpm dev # → http://localhost:5173
# 全栈（地图 + AI 分析师）
export ANTHROPIC_API_KEY=sk-ant-...
pnpm dev:full
```
## 数据
**USGS 国家产生的废水地球化学数据库 v3.0** （2023 年 12 月）— 113,131 个样本，209 个字段，2002–2022 年覆盖范围，CC0 公共领域。转换脚本位于 `scripts/` 和 `data/README.md` 中。
## 诚实状态 & 我会做得不同
这是一个可用的原型，而不是产品。目前状态：
- 地图、过滤、客户端 SQL、带有 SQL 工具的流式代理聊天：**正常工作**
- 笔记本生成：有效，但 Jupyter 服务是最脆弱的部分
- 一个正在进行的模式迁移（`play_type` → 多值 `play_types`）存在于自己的分支中；主线在稳定模式完成之前保持不变
如果我再次构建，我会做得不同：
- **后端优先，尽早。** 闪亮的地图是首先出现的；有价值的是干净的、可查询的数据集和代理对其的 SQL 访问。如果我再次构建，我会颠倒这个顺序。
- **从第一天起就固定代理 SDK 并锁定工具策略。** 未固定的 SDK 加上不断演变的 CLI 在项目被搁置期间破坏了流媒体，而默认工具配置对于面向 Web 端点的东西来说过于宽松。两者都已修复，但它们不应该成为默认值。
- **减少活动部件。** 前端代码生成（OpenAPI → 客户端）加上 monorepo 和窗口化 UI，对于原型来说是一个很大的表面。20% 的有趣部分并不需要其他 80%。
## 许可证 / 致谢
数据：USGS，CC0 1.0。地图瓦片 © 其各自提供商。代码：由 [Matt Dicataldo](https://github.com/matthewdicataldo) 提供的个人项目。
