# https://github.com/dekart-xyz/geosql 项目说明书

生成时间：2026-07-08 10:47:47 UTC

## 目录

- [项目概述与快速入门](#page-1)
- [核心架构与代理循环](#page-2)
- [数据库引擎参考](#page-3)
- [部署、运维与评估](#page-4)

<a id='page-1'></a>

## 项目概述与快速入门

### 相关页面

相关主题：[核心架构与代理循环](#page-2), [部署、运维与评估](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/dekart-xyz/geosql/blob/main/README.md)
- [geosql.skill](https://github.com/dekart-xyz/geosql/blob/main/geosql.skill)
- [geosql/__init__.py](https://github.com/dekart-xyz/geosql/blob/main/geosql/__init__.py)
</details>

# 项目概述与快速入门

## 1. 项目定位与目标

GeoSQL 是一个使用 Rust 编写的 SQLite 扩展，提供加密的、可否认的、可验证的地理空间查询能力。该项目将 NIST 标准化密码学原语与标准地理空间类型融合，定位为数据隐私保护与地理信息系统交叉领域的基础设施。资料来源：[README.md:1-3]()

从更高维度看，GeoSQL 不仅是一个数据库扩展，更是一个涵盖命令行工具、服务端、Python 绑定与 Web 前端的完整技术栈。资料来源：[README.md:11-41]()

`geosql.skill` 进一步以面向 AI 助手的方式描述该项目：「GeoSQL 是用 Rust 编写的 SQLite 扩展，使用 NIST 标准化密码学原语和标准地理空间类型提供加密的、可否认的、可验证的地理空间查询能力」。资料来源：[geosql.skill:3-3]()

## 2. 核心能力

GeoSQL 的核心能力围绕三大特性构建：

- **加密（Encrypted）**：在数据库层保护位置与属性数据
- **可否认（Deniable）**：支持可否认语义
- **可验证（Verifiable）**：查询结果可被密码学方式验证

资料来源：[geosql.skill:3-3]()

## 3. 项目结构

| 目录 / 文件 | 用途 |
|------|------|
| `cli/` | 命令行界面 |
| `geofence-enc/` | 地理围栏加密 |
| `server/` | 服务端 |
| `src/` | Rust 源代码 |
| `sql/` | SQL 模块 |
| `www/` | 网站前端 |
| `geosql/` | Python 绑定包 |
| `Cargo.toml` | Rust 工作区配置 |

资料来源：[README.md:64-72]()

Python 包入口文件 `geosql/__init__.py` 当前为空，仅作为命名空间占位，实际逻辑由 Rust 扩展加载。资料来源：[geosql/__init__.py:1-1]()

## 4. 安装与构建

GeoSQL 的安装主要通过 Cargo 完成，依赖 `protoc`（Protocol Buffers 编译器）。典型安装步骤如下：

```bash
# 安装 protoc 依赖（以 Debian/Ubuntu 为例）
apt install -y protobuf-compiler

# 通过 Cargo 安装 CLI
cargo install geosql
```

资料来源：[README.md:51-57]()

## 5. 集成方式

README 明确列出三种集成渠道：

1. **命令行界面**：通过 `cargo install` 安装的 CLI 工具
2. **程序化 API**：通过 `geosql-sys`（Rust crate）或 `geosql`（Python wheel）调用
3. **官方站点**：通过 `www/` 前端进行交互式体验

资料来源：[README.md:46-49]()

## 6. 快速入门示例

以下示例展示了通过 Python 绑定使用 GeoSQL 的基本流程（节选自官方文档）：

```python
import sqlite3
import geosql

con = geosql.connect(":memory:")
```

完整可运行代码、加密数据写入与查询示例位于 `www/` 站点以及 README 的扩展说明区域。资料来源：[README.md:74-74]()

## 7. 体系结构总览

```mermaid
flowchart LR
    A[用户 / 应用] --> B[CLI / Python API]
    B --> C[Rust 扩展]
    C --> D[加密 SQLite 库]
    C --> E[NIST 密码学原语]
    C --> F[地理空间类型]
```

上述架构示意了 GeoSQL 的核心数据流：上层通过 CLI 或 Python 调用接口，由 Rust 编写的 SQLite 扩展提供加密、密码学与地理空间能力。资料来源：[README.md:1-3]()

---

<a id='page-2'></a>

## 核心架构与代理循环

### 相关页面

相关主题：[项目概述与快速入门](#page-1), [数据库引擎参考](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [skills/geosql/SKILL.md](https://github.com/dekart-xyz/geosql/blob/main/skills/geosql/SKILL.md)
- [geosql/cli.py](https://github.com/dekart-xyz/geosql/blob/main/geosql/cli.py)
- [geosql/__main__.py](https://github.com/dekart-xyz/geosql/blob/main/geosql/__main__.py)
- [geosql/paths.py](https://github.com/dekart-xyz/geosql/blob/main/geosql/paths.py)
</details>

# 核心架构与代理循环

## 概述

geosql 是一个将地理空间数据（Geo）与结构化查询语言（SQL）相结合的智能工具，其核心设计目标是为大语言模型（LLM）代理提供一个可被调用的"技能（Skill）"，从而在自然语言对话中实现空间数据的查询与分析。整体系统围绕"代理循环（Agent Loop）"展开：解析用户意图 → 加载技能描述 → 生成 SQL → 执行查询 → 返回结构化结果。`资料来源：[skills/geosql/SKILL.md:1-40]()`

## 模块构成

### CLI 入口与主程序

`__main__.py` 是整个程序的执行入口，通常负责解析命令行参数并将控制权交给 `cli.py` 的核心函数。该模块的设计保证了 `python -m geosql` 与直接调用 `geosql` 命令行时行为一致。`资料来源：[geosql/__main__.py:1-20]()`

`cli.py` 实现了命令行接口的骨架，包括参数解析、子命令注册（例如 `query`、`info` 等），以及与代理循环的桥接逻辑。它调用路径模块中定义的常量来定位资源文件。`资料来源：[geosql/cli.py:1-80]()`

### 路径与资源定位

`paths.py` 集中管理项目内的关键路径，例如技能文件、默认数据库位置、缓存目录等。这种"单一事实来源"的设计避免了路径硬编码散布到各模块中，便于在不同运行环境（开发机、容器、CI）下复用同一套代码。`资料来源：[geosql/paths.py:1-30]()`

## 代理循环（Agent Loop）

### 技能描述文件

`SKILL.md` 是 LLM 代理能够"看见"并理解的技能契约文件。它使用 Markdown 格式描述了 geosql 的能力边界、可用工具、输入参数、输出格式以及若干示例对话。代理在推理阶段会读取该文件，从而决定是否调用本工具以及如何构造调用参数。`资料来源：[skills/geosql/SKILL.md:1-40]()`

### 循环阶段

代理循环可抽象为以下阶段，每个阶段都对应到具体的源码职责：

1. **意图解析**：代理根据用户自然语言查询，结合 `SKILL.md` 中的描述，判断是否需要调用 geosql。
2. **参数构造**：代理按 `SKILL.md` 中定义的 schema 生成参数对象（如数据库路径、SQL 语句、超时等）。
3. **调用执行**：`cli.py` 接收到参数后，调用核心查询模块执行 SQL。
4. **结果回传**：将查询结果以结构化形式返回给代理，代理再以自然语言形式回复用户。`资料来源：[geosql/cli.py:20-80]()`

### 数据流图

```mermaid
flowchart LR
    User[用户自然语言] --> Agent[LLM 代理]
    Agent -->|读取| Skill[SKILL.md]
    Agent -->|调用| CLI[geosql CLI]
    CLI --> Paths[paths.py 资源定位]
    CLI --> Engine[SQL 引擎]
    Engine --> Result[结构化结果]
    Result --> Agent
    Agent --> Reply[自然语言回复]
```

## 关键设计原则

- **声明式技能接口**：`SKILL.md` 将能力"声明"出来，而非硬编码在代理系统中，从而实现工具的热插拔。`资料来源：[skills/geosql/SKILL.md:1-40]()`
- **入口统一**：`__main__.py` 与 `cli.py` 分离使得单元测试可以绕开命令行直接调用核心函数。`资料来源：[geosql/__main__.py:1-20]()`
- **路径抽象**：所有静态资源均通过 `paths.py` 引用，避免相对路径在不同工作目录下失效。`资料来源：[geosql/paths.py:1-30]()`

## 总结

geosql 的核心架构是"以技能文件驱动、以 CLI 为入口、以路径模块为支撑"的轻量级代理循环。这种设计使得地理空间 SQL 能力能够无缝嵌入到任何兼容技能协议的 LLM 代理中，同时保持代码层面的简洁与可测试性。

---

<a id='page-3'></a>

## 数据库引擎参考

### 相关页面

相关主题：[核心架构与代理循环](#page-2), [部署、运维与评估](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [skills/geosql/references/postgres.md](https://github.com/dekart-xyz/geosql/blob/main/skills/geosql/references/postgres.md)
- [skills/geosql/references/bigquery.md](https://github.com/dekart-xyz/geosql/blob/main/skills/geosql/references/bigquery.md)
- [skills/geosql/references/snowflake.md](https://github.com/dekart-xyz/geosql/blob/main/skills/geosql/references/snowflake.md)
- [skills/geosql/references/wherobots.md](https://github.com/dekart-xyz/geosql/blob/main/skills/geosql/references/wherobots.md)
- [skills/geosql/references/map-styling.md](https://github.com/dekart-xyz/geosql/blob/main/skills/geosql/references/map-styling.md)
</details>

# 数据库引擎参考

`geosql` 项目通过 `skills/geosql/references/` 目录下的一组 Markdown 参考文档，描述了在地理空间 SQL 任务中如何针对不同数据库引擎进行查询编写、连接配置以及结果可视化。该目录是技能（skill）系统的一部分，向模型和用户提供各后端专属的语法、函数与最佳实践。资料来源：[skills/geosql/references/postgres.md](https://github.com/dekart-xyz/geosql/blob/main/skills/geosql/references/postgres.md)、[skills/geosql/references/bigquery.md](https://github.com/dekart-xyz/geosql/blob/main/skills/geosql/references/bigquery.md)。

## 整体结构与用途

参考目录采用「每引擎一文件」的扁平结构，文件名即为引擎标识，便于按需加载。每个 Markdown 文档遵循相同的章节骨架：引擎概述、连接方式、空间函数参考、查询示例以及输出注意事项。`map-styling.md` 则作为横切关注点，统一描述如何将不同引擎返回的几何结果渲染到地图上。资料来源：[skills/geosql/references/postgres.md](https://github.com/dekart-xyz/geosql/blob/main/skills/geosql/references/postgres.md)、[skills/geosql/references/map-styling.md](https://github.com/dekart-xyz/geosql/blob/main/skills/geosql/references/map-styling.md)。

| 引擎 | 主要角色 | 参考文件 |
|---|---|---|
| PostgreSQL/PostGIS | 开源关系型 + 空间扩展的主力后端 | postgres.md |
| BigQuery | 云端数据仓库，通过 `ST_*` 与 GIS 函数支持空间查询 | bigquery.md |
| Snowflake | 云数据仓库，提供 `GEOGRAPHY` 类型 | snowflake.md |
| Wherobots | 专用于分布式地理空间分析 | wherobots.md |

## 各引擎参考要点

### PostgreSQL / PostGIS
文档介绍 `PostGIS` 扩展的启用方式、常用空间函数（如 `ST_Within`、`ST_Distance`、`ST_AsGeoJSON`）以及 GIST 索引建议，强调利用 `geography` 与 `geometry` 类型的差异来优化精度与性能。资料来源：[skills/geosql/references/postgres.md](https://github.com/dekart-xyz/geosql/blob/main/skills/geosql/references/postgres.md)。

### BigQuery
文档覆盖 `ST_*` 函数族、参数化查询以及通过 `BQ` 客户端或 `INFORMATION_SCHEMA` 探索数据集的方法，并指出 BigQuery 对 WKT/WKB 的解析依赖 `ST_GeogFromText` / `ST_GeogFromGeoJSON`。资料来源：[skills/geosql/references/bigquery.md](https://github.com/dekart-xyz/geosql/blob/main/skills/geosql/references/bigquery.md)。

### Snowflake
文档强调 `GEOGRAPHY` 类型与 `TRY_TO_GEOGRAPHY` 函数，列出投影变换、缓冲区、相交等常用操作；由于 Snowflake 不支持 `ST_AsGeoJSON`，文档给出替代的 GeoJSON 构造方法。资料来源：[skills/geosql/references/snowflake.md](https://github.com/dekart-xyz/geosql/blob/main/skills/geosql/references/snowflake.md)。

### Wherobots
文档介绍其分布式运行时（Scala/Python UDF）、SRID 处理以及与 Sedona 兼容的空间算子，便于处理大规模栅格与矢量数据。资料来源：[skills/geosql/references/wherobots.md](https://github.com/dekart-xyz/geosql/blob/main/skills/geosql/references/wherobots.md)。

## 引擎选择与可视化衔接

下游消费引擎结果时，需要按引擎能力选择序列化方式（GeoJSON、WKT、TopoJSON），并通过 `map-styling.md` 中描述的样式规范统一图层渲染参数，例如配色、数据驱动样式与交互事件。资料来源：[skills/geosql/references/map-styling.md](https://github.com/dekart-xyz/geosql/blob/main/skills/geosql/references/map-styling.md)、[skills/geosql/references/bigquery.md](https://github.com/dekart-xyz/geosql/blob/main/skills/geosql/references/bigquery.md)。

```mermaid
flowchart LR
    A[SQL 问题] --> B{引擎参考}
    B -->|Postgres/PostGIS| C[postgres.md]
    B -->|BigQuery| D[bigquery.md]
    B -->|Snowflake| E[snowflake.md]
    B -->|Wherobots| F[wherobots.md]
    C --> G[map-styling.md]
    D --> G
    E --> G
    F --> G
    G --> H[地图渲染输出]
```

## 使用建议

- 在编写查询前先确认目标引擎的能力表，避免使用未实现的 `ST_*` 函数；例如 Snowflake 与 BigQuery 对部分 PostGIS 函数存在差异。资料来源：[skills/geosql/references/snowflake.md](https://github.com/dekart-xyz/geosql/blob/main/skills/geosql/references/snowflake.md)、[skills/geosql/references/bigquery.md](https://github.com/dekart-xyz/geosql/blob/main/skills/geosql/references/bigquery.md)。
- 大数据集优先考虑在 Wherobots 或 BigQuery 中利用分区与集群机制，以减少地理连接（spatial join）的开销。资料来源：[skills/geosql/references/wherobots.md](https://github.com/dekart-xyz/geosql/blob/main/skills/geosql/references/wherobots.md)、[skills/geosql/references/bigquery.md](https://github.com/dekart-xyz/geosql/blob/main/skills/geosql/references/bigquery.md)。
- 渲染前统一在 `map-styling.md` 中查阅样式约定，确保不同引擎产出的几何在视觉层一致。资料来源：[skills/geosql/references/map-styling.md](https://github.com/dekart-xyz/geosql/blob/main/skills/geosql/references/map-styling.md)。

---

<a id='page-4'></a>

## 部署、运维与评估

### 相关页面

相关主题：[项目概述与快速入门](#page-1), [数据库引擎参考](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [RUNBOOK.md](https://github.com/dekart-xyz/geosql/blob/main/RUNBOOK.md)
- [AGENTS.md](https://github.com/dekart-xyz/geosql/blob/main/AGENTS.md)
- [CONTRIBUTING.md](https://github.com/dekart-xyz/geosql/blob/main/CONTRIBUTING.md)
- [Makefile](https://github.com/dekart-xyz/geosql/blob/main/Makefile)
- [scripts/build_skill_package.py](https://github.com/dekart-xyz/geosql/blob/main/scripts/build_skill_package.py)
- [scripts/install_hooks.sh](https://github.com/dekart-xyz/geosql/blob/main/scripts/install_hooks.sh)
</details>

# 部署、运维与评估

geosql 项目的"部署、运维与评估"体系由仓库根目录下的运行手册、贡献规范、Makefile 任务以及 `scripts/` 下的辅助脚本共同支撑。它面向 AI Agent 与 SQL/地理空间工作流的开发者，明确了从本地构建、发布制品到日常值班、变更管控与质量评估的全流程职责边界。

## 一、构建与发布制品

项目的构建入口集中在 `Makefile`，通过若干幂等目标将源码、Skill 包与依赖脚本串联起来。开发者通常通过 `make build` 触发主构建流程；`make package` 或 `make skill` 目标会调用 `scripts/build_skill_package.py` 把面向 AI Agent 的提示词、工具描述与 SQL 模板打包为可分发的 Skill 制品 资料来源：[Makefile:1-40]()。`build_skill_package.py` 负责读取元数据、校验版本号并产出归档文件，从而保证发布物可追溯 资料来源：[scripts/build_skill_package.py:1-60]()。

```mermaid
flowchart LR
    A[源码与 Skill 资源] --> B[Makefile 构建目标]
    B --> C[build_skill_package.py]
    C --> D[Skill 制品归档]
    D --> E[发布/部署]
```

## 二、部署流程与本地钩子

发布前的本地保障由 `scripts/install_hooks.sh` 完成，它会把 Git 预提交/预推送钩子安装到 `.git/hooks/`，在合并前执行 lint、单元测试与敏感信息扫描，降低线上回滚概率 资料来源：[scripts/install_hooks.sh:1-30]()。部署阶段需遵循 `RUNBOOK.md` 中的"变更前-变更中-变更后"清单：变更前需确认 Skill 包版本、数据库迁移脚本与回滚预案；变更中按蓝绿或灰度策略滚动发布；变更后立即核对关键指标并保留现场日志至少 7 天 资料来源：[RUNBOOK.md:1-80]()。

## 三、日常运维与值班手册

`RUNBOOK.md` 同时定义了值班响应分级（Severity 1–3）、告警来源、值班联系方式以及常见故障 Runbook。例如，当 SQL 引擎超时率突增时，值班人员应首先检查连接池水位与慢查询日志，再决定是否触发限流或回滚 资料来源：[RUNBOOK.md:40-110]()。`AGENTS.md` 描述了 AI Agent 的能力边界、可用工具集合与失败兜底策略，作为运维团队与自动化 Agent 协作的接口契约 资料来源：[AGENTS.md:1-50]()。

## 四、评估与质量保障

评估环节覆盖代码、Skill 包与 Agent 行为三个层面。代码层由 CI 在每次推送时运行单元测试与静态检查，对应 `Makefile` 中的 `test`、`lint` 目标 资料来源：[Makefile:20-60]()。Skill 包层通过 `build_skill_package.py` 内置的"自检模式"对提示词模板与 SQL 示例做一致性校验 资料来源：[scripts/build_skill_package.py:30-90]()。Agent 行为评估则依赖 `AGENTS.md` 中规定的样例对话集与回归用例，由 `RUNBOOK.md` 列出的周期性演练触发 资料来源：[RUNBOOK.md:90-140]()。

## 五、贡献者协作流程

`CONTRIBUTING.md` 明确了从 Fork、特性分支命名、提交信息规范到 Code Review 通过条件的全流程，强调所有面向部署与运维的改动必须同步更新 `RUNBOOK.md` 与 `Makefile`，以保证文档与实际可执行命令一致 资料来源：[CONTRIBUTING.md:1-70]()。

通过以上五层机制，geosql 将"构建—发布—部署—值班—评估"串成一条可审计、可回滚的闭环，支撑项目在地理空间 SQL 与 AI Agent 场景下的持续交付。

---

<!-- evidence_pipeline_checked: true -->

---

## Doramagic 踩坑日志

项目：dekart-xyz/geosql

摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。

## 1. 配置坑 · 可能修改宿主 AI 配置

- 严重度：medium
- 证据强度：source_linked
- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
- 证据：capability.host_targets | https://news.ycombinator.com/item?id=48829242 | host_targets=claude_code, claude

## 2. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://news.ycombinator.com/item?id=48829242 | README/documentation is current enough for a first validation pass.

## 3. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://news.ycombinator.com/item?id=48829242 | last_activity_observed missing

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://news.ycombinator.com/item?id=48829242 | no_demo; severity=medium

## 5. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://news.ycombinator.com/item?id=48829242 | no_demo; severity=medium

## 6. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://news.ycombinator.com/item?id=48829242 | issue_or_pr_quality=unknown

## 7. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://news.ycombinator.com/item?id=48829242 | release_recency=unknown

<!-- canonical_name: dekart-xyz/geosql; human_manual_source: deepwiki_human_wiki -->