大地测量工具箱TYEclipse/dsh-geodesy

dsh-geodesy

面向 DeepSeek Harness（dsh）的大地测量数学工具箱：大圆距离、方位角、目的地推算、DMS 解析、恒向线、路径交点以及球面多边形面积——全部为本地、确定性的工具，且零运行时依赖。

中文简介：dsh 插件「大地测量工具箱」——大圆距离、方位角、目的地推算、DMS 坐标解析、恒向线（罗盘等角航线）距离、两条大圆路径交点、球面多边形面积共七个纯计算工具，零运行时依赖。专治大模型手算球面几何的常见错误（弧度与角度混用、经纬度顺序颠倒、忘记地球半径、把球面多边形当平面算等）。

为什么需要它

大语言模型在球面几何计算上总是稳定地出错：它们会弄混纬度/经度的顺序、用错地球半径、忘记角度转弧度、搞砸 DMS 转换，还会把球面多边形当作平面来处理。本插件把这类计算从模型的脑子里拿出来，交给精确的球面三角学：

- geo_distance —— 两点之间的大圆距离（haversine 公式），附带起始/终点方位角以及 16 方位罗盘方向；结果以 km、m、mi 或 nmi 为单位
- geo_bearing —— 两点的起始与终点大圆方位角，以及两点的大圆中点
- geo_destination —— 正算大地测量问题：给定起点、方位角和距离，计算目的地（附带往返距离校验）
- coord_parse —— 解析并校验坐标字符串（十进制、DMS、后缀、坐标对），并将其转换为十进制度数 + 格式化 DMS
- geo_rhumb —— 两点之间的恒向线（等角航线 / loxodrome）距离与方位角，并附带大圆距离以供对比
- geo_intersection —— 两条大圆路径（各自由起点 + 起始方位角定义）的交点；报告最近的交点、对跖交点，以及距两个起点的距离
- geo_area —— 通过球面角盈（Girard 定理）计算球面多边形的面积与周长，并始终包含互补区域的面积

所有计算均使用 IUGG 平均地球半径 6371.0088 km（可通过插件 radiusKm 选项配置，例如用于月球或行星计算）。

安装

dsh plugin --profile web add github:TYEclipse/dsh-geodesy

需要 PATH 中有 pnpm。然后重启该 profile 的服务（或执行 dsh restart web）。

用法

向 agent 提出涉及地球表面数学的问题；它会自动调用这些工具：

- “北京到上海的大圆距离是多少？”
- “从伦敦看纽约在哪个方向，中点在哪里？”
- “我在巴黎正东 200 km 处——我在哪里？”
- “把 37°46′30″N, 122°25′8.4″W 解析为十进制度数。”
- “从 (45°N, 0°) 以恒定航向航行到 (45°N, 90°) 有多远，比大圆远多少？”
- “从 (0, 0) 出发向正东的飞行走廊与从 (0, 90) 出发向正北的飞行走廊在哪里相交？”
- “球面上三角形 (0,0)、(0,90)、(90,0) 的面积是多少？”

示例

geo_rhumb —— (45°N, 0°) → (45°N, 90°)，恒定航向：

{
"valid": true,
"unit": "km",
"distance": 7076.411574,
"kilometers": 7076.411574,
"miles": 4397.078297,json
"nauticalMiles": 3820.956573,
"bearing": 90,
"compass": "E",
"greatCircleKm": 6671.704814
}

geo_intersection —— 赤道（从 (0,0) 向东）× 子午线（从 (0,90) 向北）：
json
{
"valid": true,
"lat": 0,
"lon": 90,
"distanceFromStart1Km": 10007.557221,
"distanceFromStart2Km": 0,
"antipodeLat": 0,
"antipodeLon": -90,
"antipodeDistanceFromStart1Km": 10007.557221,
"antipodeDistanceFromStart2Km": 20015.114442
}

geo_area —— 八分之一球面三角形 (0,0)、(0,90)、(90,0)：恰好是球面的八分之一：
json
{
"valid": true,
"vertices": 3,
"areaKm2": 63758235.121609,
"perimeterKm": 30022.671663,
"excessRadians": 1.5707963268,
"complementKm2": 446307645.851263
}

geo_distance —— 北京 (39.9042, 116.4074) → 上海 (31.2304, 121.4737)：
json
{
"valid": true,
"unit": "km",
"distance": 1067.311645,
"kilometers": 1067.311645,
"miles": 663.196709,
"nauticalMiles": 576.302184,
"initialBearing": 153.072675,
"finalBearing": 156.029266,
"compass": "SSE"
}

语义说明

- geo_area 环绕方向：报告的面积是有向边左侧的区域。逆时针顶点顺序（从球外看）给出多边形本身；顺时针顺序给出其补集。complementKm2 始终包含在内，因此任一区域都只差一个字段。多边形必须是简单多边形（不自交）；最多 100 个顶点。
- geo_intersection 报告最靠近第一条路径起点的交点；当该交点位于路径 1 的反向侧（从起点 1 出发的方位角相差约 180°）时，会有一条 note 说明，此时前方的交点是其对跖交点。
- geo_rhumb 对零长度线返回方位角 0（不存在唯一航向）。

坐标输入格式

coord_parse 确定性地接受：

| 输入 | 含义 |
|---|---|
| 39.9042, 116.4074 | 十进制对，lat, lon 顺序 |
| 116.4074E, 39.9042N | 带后缀的对——顺序无关，轴由后缀决定 |
| 39°54′15″N 116°23′27″E | DMS 对（带后缀时逗号可选） |
| 37°46′30″N / 37d46m30sN / 37:46:30N / 37 46 30 N | 单个 DMS 坐标 |
| 37.775N / -122.419 | 单个十进制值（负值 = 南/西） |
| 37.775，kind: "lat" | 无后缀的单个值，并带有明确的轴提示 |

无效输入返回 valid: false 并附原因——绝不静默猜测。

工具

| 工具 | 用途 |
|---|---|
| geo_distance | haversine 距离，km/m/mi/nmi，初始与最终方位角，罗盘方位点 |
| geo_bearing | 初始/最终方位角 + 大圆中点 |
| geo_destination | 由起点 + 方位角 + 距离求目标点，并带往返校验 |
| coord_parse | 解析/验证十进制与 DMS 坐标字符串 → 十进制度数 + DMS |
| geo_rhumb | 等角航线距离 + 方位角（恒向线），与大圆比较 |
| geo_intersection | 两条大圆路径的交点（+ 对跖交点，距起点的距离） |
| geo_area | 球面多边形面积 + 周长（球面角超），补面积 |

配置
yaml
plugins:
dsh-geodesy:
radiusKm: 6371.0088   # 球体半径；月球使用 1737.4，火星使用 3389.5

开发
sh
pnpm install
pnpm build
pnpm test     # 154 个测试，锚定到独立计算的闭式解
pnpm lint

许可证

MIT © TYEclipse