内容
# geolibre-cli
基于命令行的地理空间数据智能工具。
`geolibre-cli` 允许人类和 AI 代理在无需 GUI 或云订阅的情况下，检查、查询、转换和轻度处理地理空间数据。它在底层使用 DuckDB Spatial，并保持输出足够小，以便代理可以读取。
## GEO-001 解决的问题
在 `geolibre-cli` 之前，快速的地理空间健全性检查通常意味着打开桌面 GIS 工具，编写一次性的 Python 脚本，或将大型几何负载复制到代理聊天中。这减缓了传输控制塔的工作，通常第一个问题是：文件是什么，大小是多少，我可以查询它吗？
在使用 GEO-001 之后，相同的交接可以从终端发生：
- 检查 GeoJSON、Parquet、CSV 和远程 URL 输入。
- 使用 DuckDB SQL 查询本地或远程数据集。
- 将支持的矢量输入转换为 Parquet 或 GeoJSON。
- 返回紧凑的 JSON 或表格输出，适用于代理、CI 日志和问题评论。
## 快速开始
```bash
npm install
npm run build
```
针对包含的演示 fixtures 运行：
```bash
node dist/cli.js inspect test/fixtures/points.geojson
node dist/cli.js sql "SELECT * FROM test/fixtures/data.csv LIMIT 2" --format table
node dist/cli.js convert test/fixtures/points.geojson --to parquet --output /tmp/geolibre-points.parquet
```
在开发过程中全局使用本地命令：
```bash
npm link
geolibre inspect test/fixtures/points.geojson
```
## 演示输出
截图友好的终端输出捕获在 [docs/demo/terminal-transcript.md](docs/demo/terminal-transcript.md) 中。简要版本：
```console
$ node dist/cli.js inspect test/fixtures/points.geojson --format table
geom_wkt id name
POINT (55.2708 25.2048) 1 迪拜
POINT (46.6753 24.7136) 2 利雅得
POINT (51.531 25.2854) 3 多哈
```
## 常用命令
检查文件或 URL：
```bash
geolibre inspect https://data.source.coop/giswqs/opengeos/countries.parquet
```
运行带有自动包装的文件路径和 URL 的 SQL：
```bash
geolibre sql "SELECT NAME, POP_EST FROM https://data.source.coop/giswqs/opengeos/countries.parquet WHERE POP_EST > 50000000"
```
在不打开 GIS 应用程序的情况下，对本地 fixture 运行 SQL：
```bash
node dist/cli.js sql "SELECT name, shipments FROM test/fixtures/data.csv ORDER BY shipments DESC LIMIT 3" --format table
```
转换格式：
```bash
geolibre convert test/fixtures/points.geojson --to parquet --output /tmp/points.parquet
```
运行小型复合进程：
```bash
geolibre process https://data.source.coop/giswqs/opengeos/countries.parquet \
--sql "SELECT * FROM input WHERE CONTINENT = 'Europe'" \
--buffer 50km \
--output /tmp/europe-buffered.geojson
```
## 输出理念
默认 JSON 输出限制在 2048 字节内。对于大型行、几何体、宽模式和长字符串，会进行汇总，以便代理不会浪费上下文在原始坐标或大型模式上。
常见标志：
- `--max-bytes 2048`
- `--sample-rows 3`
- `--no-sample`
- `--limit 10`
- `--format json|table`
## MCP 服务器
构建和运行：
```bash
npm run build
node dist/mcp/server.js
```
公开的工具：
- `geolibre_inspect`
- `geolibre_sql`
- `geolibre_convert`
- `geolibre_vector` 占位符
- `geolibre_compound` 占位符
## 验证
```bash
npm run build
npm audit --audit-level=high
npm test
node scripts/attack.mjs
node scripts/mcp-smoke.mjs
```
GitHub CI 运行相同的审计、构建、CLI 烟雾测试、攻击测试和 MCP 烟雾测试。
## 数据说明
公共的 `countries.parquet` 示例是上游数据集，可能会随时间变化。在 2026-06-14 的 GEO-001 验证期间，它返回了 176 个观察到的要素。测试断言成功的结构化输出和字节限制，而不是固定的要素计数。
## 安全说明
`npm audit` 在高严重性关卡下是干净的。项目当前使用 npm 覆盖强制 `tar@7.5.16`，因为当前的 `duckdb` 安装时依赖链仍然通过 `node-gyp` 拉取较旧的易受攻击的 `tar`。参见 `docs/security-audit.md`。
## 限制
- v0.1 不是完整的 GIS 引擎。
- CRS 检测是尽力而为的，通常报告为 `unknown`。
- Shapefile 支持取决于 DuckDB Spatial/GDAL 行为，尚不一流。
- 光栅操作被推迟。
- 矢量操作超出缓冲区演示被推迟。
- SQL 支持仅限于 `SELECT` 和 `WITH` 读取查询。
- 远程演示数据集可能会更改或消失；本地 fixtures 是稳定的演示路径。
- 输出上限故意汇总大值，因此当需要更多原始详细信息时，请使用更高的 `--max-bytes`。
