amap-cli 0.1.2__tar.gz → 0.1.3__tar.gz

{amap_cli-0.1.2 → amap_cli-0.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: amap-cli
-Version: 0.1.2
+Version: 0.1.3
 Summary: Pure command-line CLI for Amap APIs.
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
@@ -13,6 +13,7 @@ Description-Content-Type: text/markdown
 
 - 纯命令行调用高德地图 API
 - 支持命令行写入和读取高德 API Key
+- 支持地理编码
 - 支持两点直线距离计算
 - 支持路径规划
 - 支持 POI 搜索
@@ -35,6 +36,12 @@ uvx amap-cli --help
 uvx amap-cli config set --api-key <YOUR_AMAP_KEY>
 ```
 
+地理编码示例：
+
+```bash
+uvx amap-cli geocode --address 北京南站
+```
+
 路径规划示例：
 
 ```bash
@@ -79,6 +86,7 @@ amap-cli --help
 
 ```bash
 amap-cli config set --api-key <YOUR_AMAP_KEY>
+amap-cli geocode --address 北京南站
 amap-cli distance --from 116.397,39.909 --to 116.407,39.904
 amap-cli route --from 北京南站 --to 天安门 --type driving
 amap-cli search-poi --keyword 星巴克 --city 北京
@@ -90,7 +98,7 @@ amap-cli search-poi --keyword 星巴克 --city 北京
 
 - skill 的目标是让 Agent 直接通过 `uvx amap-cli` 调用本工具
 - 使用方式与上面的“直接使用 `uvx` 运行”一致
-- 使用前先配置高德 API Key，之后即可发起路径规划和 POI 搜索
+- 使用前先配置高德 API Key，之后即可发起地理编码、路径规划和 POI 搜索
 - `distance` 命令在起终点都为坐标时可直接本地计算，不依赖 API Key
 - 建议 Agent 直接解析命令返回的 JSON 结果
 
@@ -152,6 +160,26 @@ amap-cli install-skill --dir <skills目录>
 - 当目标目录不存在时会自动创建
 - 当目标目录中已存在同名 skill 时，默认报错；追加 `--force` 后会覆盖
 
+### 地理编码
+
+基础格式：
+
+```bash
+amap-cli geocode --address <结构化地址|地标名称>
+```
+
+可选参数：
+
+- `--city`
+
+说明：
+
+- 调用高德地理编码接口，将结构化地址或地标性名胜景区、建筑物名称解析为坐标
+- 传入 `--city` 时，会优先在对应城市范围内解析
+- 返回结果中的 `geocode.location` 为 `[经度, 纬度]`
+- 返回结果中的 `geocode.formattedAddress` 为高德返回的标准化地址
+- 对于较模糊的名称，建议补充更完整地址或增加 `--city`
+
 ### 路径规划
 
 基础格式：

{amap_cli-0.1.2 → amap_cli-0.1.3}/README.md

@@ -6,6 +6,7 @@
 
 - 纯命令行调用高德地图 API
 - 支持命令行写入和读取高德 API Key
+- 支持地理编码
 - 支持两点直线距离计算
 - 支持路径规划
 - 支持 POI 搜索
@@ -28,6 +29,12 @@ uvx amap-cli --help
 uvx amap-cli config set --api-key <YOUR_AMAP_KEY>
 ```
 
+地理编码示例：
+
+```bash
+uvx amap-cli geocode --address 北京南站
+```
+
 路径规划示例：
 
 ```bash
@@ -72,6 +79,7 @@ amap-cli --help
 
 ```bash
 amap-cli config set --api-key <YOUR_AMAP_KEY>
+amap-cli geocode --address 北京南站
 amap-cli distance --from 116.397,39.909 --to 116.407,39.904
 amap-cli route --from 北京南站 --to 天安门 --type driving
 amap-cli search-poi --keyword 星巴克 --city 北京
@@ -83,7 +91,7 @@ amap-cli search-poi --keyword 星巴克 --city 北京
 
 - skill 的目标是让 Agent 直接通过 `uvx amap-cli` 调用本工具
 - 使用方式与上面的“直接使用 `uvx` 运行”一致
-- 使用前先配置高德 API Key，之后即可发起路径规划和 POI 搜索
+- 使用前先配置高德 API Key，之后即可发起地理编码、路径规划和 POI 搜索
 - `distance` 命令在起终点都为坐标时可直接本地计算，不依赖 API Key
 - 建议 Agent 直接解析命令返回的 JSON 结果
 
@@ -145,6 +153,26 @@ amap-cli install-skill --dir <skills目录>
 - 当目标目录不存在时会自动创建
 - 当目标目录中已存在同名 skill 时，默认报错；追加 `--force` 后会覆盖
 
+### 地理编码
+
+基础格式：
+
+```bash
+amap-cli geocode --address <结构化地址|地标名称>
+```
+
+可选参数：
+
+- `--city`
+
+说明：
+
+- 调用高德地理编码接口，将结构化地址或地标性名胜景区、建筑物名称解析为坐标
+- 传入 `--city` 时，会优先在对应城市范围内解析
+- 返回结果中的 `geocode.location` 为 `[经度, 纬度]`
+- 返回结果中的 `geocode.formattedAddress` 为高德返回的标准化地址
+- 对于较模糊的名称，建议补充更完整地址或增加 `--city`
+
 ### 路径规划
 
 基础格式：

{amap_cli-0.1.2 → amap_cli-0.1.3}/docs/manual-verification.md

@@ -24,10 +24,35 @@ uv run python -m amap_cli --help
 结果：
 
 - `uv sync` 成功完成本地安装
-- `amap-cli --help` 正确显示 `config`、`distance`、`route`、`search-poi` 四个子命令
+- `amap-cli --help` 正确显示 `config`、`geocode`、`distance`、`route`、`search-poi` 五个子命令
 - `python -m amap_cli --help` 与脚本入口行为一致
 
-### 2. `distance` 坐标输入走本地直线距离计算
+### 2. `geocode` 典型输入通过 CLI 主入口走通到 handler
+
+说明：
+
+- 使用 `amap_cli.cli.main(...)` 作为 CLI 主入口
+- 通过 monkeypatch 将 `amap_cli.geocode_command.AmapApiClient` 替换为假 client
+- 仍然走真实参数解析、handler 与统一 JSON 输出
+
+验证输入：
+
+```bash
+geocode --address 北京南站
+```
+
+假 client 返回：
+
+- `/v3/geocode/geo`：北京南站的坐标与标准化地址
+
+结果：
+
+- CLI 返回 `success=true`
+- `state.address` 正确保留原始查询
+- `geocode.location` 返回坐标数组
+- `geocode.formattedAddress` 正确透传
+
+### 3. `distance` 坐标输入走本地直线距离计算
 
 执行：
 
@@ -42,7 +67,7 @@ uv run amap-cli distance --from 116.397,39.909 --to 116.407,39.904
 - `state.mode=straight_line`
 - `summary.distance` 返回两点之间的直线距离（米）
 
-### 3. 配置写入与自动读取
+### 4. 配置写入与自动读取
 
 为避免污染真实用户配置，验证时使用隔离 `HOME`：
 
@@ -59,7 +84,7 @@ HOME="$TMP_HOME" uv run amap-cli config show
 - 再次执行 `config show` 时可自动读取刚写入的配置
 - `api_key` 输出已脱敏
 
-### 4. `route` 典型输入通过 CLI 主入口走通到 handler
+### 5. `route` 典型输入通过 CLI 主入口走通到 handler
 
 说明：
 
@@ -85,7 +110,7 @@ route --from 北京南站 --to 天安门 --type driving
 - 起终点地名与坐标正确进入输出
 - `summary.distance`、`summary.time`、`summary.steps` 正常生成
 
-### 5. `search-poi` 典型输入通过 CLI 主入口走通到 handler
+### 6. `search-poi` 典型输入通过 CLI 主入口走通到 handler
 
 说明：
 
@@ -130,5 +155,5 @@ search-poi --keyword 星巴克 --city 北京 --pageSize 1
 
 结论：
 
-- 当前五项手动验证均已通过
-- CLI 主入口已完成 `distance`、`route`、`search-poi` 整合
+- 当前六项手动验证均已通过
+- CLI 主入口已完成 `geocode`、`distance`、`route`、`search-poi` 整合

{amap_cli-0.1.2 → amap_cli-0.1.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "amap-cli"
-version = "0.1.2"
+version = "0.1.3"
 description = "Pure command-line CLI for Amap APIs."
 readme = "README.md"
 requires-python = ">=3.11"

{amap_cli-0.1.2 → amap_cli-0.1.3}/skills/amap-cli/SKILL.md

@@ -1,18 +1,20 @@
 ---
 name: amap-cli
-description: Use amap-cli for terminal-based Amap distance calculation, route planning, and POI search. Use when the user needs machine-readable map results in this project. Do not use for GUI-based map interaction.
+description: Use amap-cli for terminal-based Amap geocoding, distance calculation, route planning, and POI search. Use when the user needs machine-readable map results in this project. Do not use for GUI-based map interaction.
 ---
 
 # Amap CLI
 
-在需要高德地图直线距离计算、路径规划或 POI 搜索时，直接调用 `amap-cli`。
+在需要高德地图地理编码、直线距离计算、路径规划或 POI 搜索时，直接调用 `amap-cli`。
 
 ## 操作规则
 
 - 统一使用 `uvx amap-cli` 调用命令
 - 优先返回和解析 JSON 结果，不依赖自然语言输出
-- 在执行 `route` 或 `search-poi` 前，先确认高德 API Key 已配置
+- 在执行 `geocode`、`route` 或 `search-poi` 前，先确认高德 API Key 已配置
 - 在执行 `distance` 前，若起终点包含地名，也需要先确认高德 API Key 已配置
+- 如果同一个地点后续还要重复用于 `distance`、`route` 或 `search-poi` 周边搜索，先调用 `geocode` 或 `search-poi` 获取坐标，后续优先传 `经度,纬度`，不要重复传地名，以减少地理编码 API 调用量
+- 结构化地址、地标性名胜景区或建筑物名称优先使用 `geocode` 获取坐标；较模糊的地点名称优先使用 `search-poi` 获取目标坐标
 - 如果返回 `MISSING_CONFIG`，先执行配置命令，再继续业务调用
 
 ## 初始化
@@ -35,6 +37,32 @@ uvx amap-cli config set --api-key <YOUR_AMAP_KEY>
 uvx amap-cli config show
 ```
 
+## Geocode
+
+需要将结构化地址或地标名称解析为坐标时，使用 `geocode`：
+
+```bash
+uvx amap-cli geocode --address 北京南站
+```
+
+如果需要缩小解析范围，可追加城市：
+
+```bash
+uvx amap-cli geocode --address 软件园二期 --city 厦门
+```
+
+关键参数：
+
+- `--address`：必填，结构化地址、地标性名胜景区或建筑物名称
+- `--city`：可选，用于缩小地理编码范围
+
+关键约束：
+
+- 地理编码仅支持详细的结构化地址，以及地标性名胜景区、建筑物名称
+- 返回结果中的 `geocode.location` 为 `[经度, 纬度]`
+- 返回结果中的 `geocode.formattedAddress` 可用于判断解析是否符合预期
+- 对于较模糊的名称，优先补充更完整的地址信息或追加 `--city`
+
 ## Route
 
 需要路径规划时，使用 `route`：
@@ -71,10 +99,17 @@ uvx amap-cli route \
 - `--type transit` 必须显式传 `--city`
 - `--waypoints` 和 `--policy` 只能和 `--type driving` 一起使用
 - `--strategy` 只能和 `--type transit` 一起使用
+- 如果起点、终点或途经点后续会复用，先用 `geocode` 或 `search-poi` 拿到坐标，再将坐标传给 `--from`、`--to`、`--waypoints`
 - 地理编码仅支持详细的结构化地址，以及地标性名胜景区、建筑物名称
 - 当输入为上述名称时，可从 `state.from.formattedAddress`、`state.to.formattedAddress` 以及 `state.waypoints[*].formattedAddress` 判断解析是否符合预期
 - 对于其他较模糊的名称，先使用 `search-poi` 获取目标坐标，再调用 `route`
 
+推荐流程：
+
+1. 首次解析地点时，使用 `geocode` 或 `search-poi` 获取坐标
+2. 后续多次规划路线时，统一复用坐标
+3. 如需保留地点语义，可配合 `--from-name` / `--to-name`
+
 ## Distance
 
 需要计算两个地点之间的直线距离时，使用 `distance`：
@@ -103,6 +138,7 @@ uvx amap-cli distance \
 
 - 当 `--from` 和 `--to` 都是坐标时，直接本地计算，不依赖 API Key
 - 任一输入为结构化地址或地标性名胜景区、建筑物名称时，会先调用地理编码接口解析坐标
+- 如果某个地点后续还会继续参与其他计算，首次解析后应复用坐标，避免再次以地名触发地理编码
 - 当输入为上述名称时，可从 `state.from.formattedAddress` / `state.to.formattedAddress` 判断地理编码是否符合预期
 - 对于其他较模糊的名称，先使用 `search-poi` 获取目标坐标，再调用 `distance`
 - 结果中的 `summary.distance` 单位为米
@@ -141,6 +177,7 @@ uvx amap-cli search-poi \
 - 传入 `--center` 时执行周边搜索
 - 未传入 `--center` 时执行关键词搜索
 - `--radius` 只有在传入 `--center` 时才应该使用
+- 如果要围绕某个地点反复做周边搜索，先使用 `geocode` 或 `search-poi` 获取该地点坐标，再持续复用 `--center`，不要每次都传地点名称重新解析
 
 ## 输出约定
 

{amap_cli-0.1.2 → amap_cli-0.1.3}/src/amap_cli/cli.py

@@ -8,6 +8,7 @@ from typing import Any, Sequence
 from amap_cli.config import get_config_path, load_config, save_config
 from amap_cli.distance import register_distance_command
 from amap_cli.errors import AmapCliError, ValidationError
+from amap_cli.geocode_command import register_geocode_command
 from amap_cli.output import emit_error, emit_success
 from amap_cli.route import register_route_command
 from amap_cli.search_poi import register_search_poi_command
@@ -31,6 +32,7 @@ def build_parser() -> JsonArgumentParser:
 
     _register_config_command(subparsers)
     register_install_skill_command(subparsers)
+    register_geocode_command(subparsers)
     register_distance_command(subparsers)
     register_route_command(subparsers)
     register_search_poi_command(subparsers)

amap_cli-0.1.3/src/amap_cli/geocode_command.py

@@ -0,0 +1,91 @@
+"""Geocode command registration and handlers."""
+
+from __future__ import annotations
+
+import argparse
+from dataclasses import dataclass
+from typing import Any
+
+from amap_cli.api import AmapApiClient
+from amap_cli.geocode import GeocodeResult, geocode_text
+from amap_cli.params import normalize_text_argument
+
+
+@dataclass(frozen=True, slots=True)
+class GeocodeRequest:
+    """Validated geocode command input."""
+
+    address: str
+    city: str | None
+
+    @classmethod
+    def from_args(cls, args: argparse.Namespace) -> "GeocodeRequest":
+        """Build a validated geocode request from parsed CLI arguments."""
+        return cls(
+            address=normalize_text_argument(args.address, "address"),
+            city=(
+                normalize_text_argument(args.city, "city")
+                if args.city is not None
+                else None
+            ),
+        )
+
+    def build_state(self) -> dict[str, Any]:
+        """Build CLI-facing state metadata."""
+        state: dict[str, Any] = {"address": self.address}
+        if self.city is not None:
+            state["city"] = self.city
+        return state
+
+
+def register_geocode_command(
+    subparsers: argparse._SubParsersAction[argparse.ArgumentParser],
+) -> argparse.ArgumentParser:
+    """Register the `geocode` command on a subparser collection."""
+    parser = subparsers.add_parser(
+        "geocode",
+        help="将地点名称解析为坐标",
+        description="调用高德地理编码接口，将结构化地址或地标名称解析为坐标。",
+    )
+    parser.add_argument(
+        "--address",
+        required=True,
+        help="待解析的结构化地址或地标名称",
+    )
+    parser.add_argument(
+        "--city",
+        help="可选城市，用于缩小地理编码范围",
+    )
+    parser.set_defaults(handler=handle_geocode_command)
+    return parser
+
+
+def handle_geocode_command(
+    args: argparse.Namespace,
+    *,
+    client: AmapApiClient | None = None,
+) -> dict[str, Any]:
+    """Handle the `geocode` command and normalize the response."""
+    request = GeocodeRequest.from_args(args)
+    result = geocode_text(
+        request.address,
+        client=client or AmapApiClient(),
+        city=request.city,
+    )
+    return {
+        "state": request.build_state(),
+        "geocode": _normalize_geocode_result(result),
+    }
+
+
+def _normalize_geocode_result(result: GeocodeResult) -> dict[str, Any]:
+    """Normalize the geocode result to the CLI output shape."""
+    payload: dict[str, Any] = {
+        "location": [
+            round(result.coordinate.longitude, 6),
+            round(result.coordinate.latitude, 6),
+        ]
+    }
+    if result.formatted_address is not None:
+        payload["formattedAddress"] = result.formatted_address
+    return payload

{amap_cli-0.1.2 → amap_cli-0.1.3}/uv.lock

@@ -4,5 +4,5 @@ requires-python = ">=3.11"
 
 [[package]]
 name = "amap-cli"
-version = "0.1.2"
+version = "0.1.3"
 source = { editable = "." }