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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: amap-cli
-Version: 0.1.2
+Version: 0.1.4
 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,19 @@ uvx amap-cli --help
 uvx amap-cli config set --api-key <YOUR_AMAP_KEY>
 ```
 
+高德免费账号默认限流较严，工具默认会在每次 API 调用结束后 sleep `0.34` 秒；如需调整或关闭，可配置：
+
+```bash
+uvx amap-cli config set --request-sleep-seconds 0.34
+uvx amap-cli config set --request-sleep-seconds 0
+```
+
+地理编码示例：
+
+```bash
+uvx amap-cli geocode --address 北京南站
+```
+
 路径规划示例：
 
 ```bash
@@ -79,6 +93,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 +105,7 @@ amap-cli search-poi --keyword 星巴克 --city 北京
 
 - skill 的目标是让 Agent 直接通过 `uvx amap-cli` 调用本工具
 - 使用方式与上面的“直接使用 `uvx` 运行”一致
-- 使用前先配置高德 API Key，之后即可发起路径规划和 POI 搜索
+- 使用前先配置高德 API Key，之后即可发起地理编码、路径规划和 POI 搜索
 - `distance` 命令在起终点都为坐标时可直接本地计算，不依赖 API Key
 - 建议 Agent 直接解析命令返回的 JSON 结果
 
@@ -122,6 +137,18 @@ amap-cli install-skill --dir ~/.agents/skills --force
 amap-cli config set --api-key <YOUR_AMAP_KEY>
 ```
 
+设置每次高德 API 调用结束后的 sleep 时间：
+
+```bash
+amap-cli config set --request-sleep-seconds 0.34
+```
+
+关闭该 sleep：
+
+```bash
+amap-cli config set --request-sleep-seconds 0
+```
+
 查看当前配置：
 
 ```bash
@@ -134,6 +161,12 @@ amap-cli config show
 ~/Library/Application Support/amap-cli/config.json
 ```
 
+说明：
+
+- `request_sleep_seconds` 默认为 `0.34`
+- 该配置会在每次真实的高德 API 调用结束后执行一次 sleep
+- 设置为 `0` 表示关闭节流等待
+
 ### 安装 Skill
 
 基础格式：
@@ -152,6 +185,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.4}/README.md

@@ -6,6 +6,7 @@
 
 - 纯命令行调用高德地图 API
 - 支持命令行写入和读取高德 API Key
+- 支持地理编码
 - 支持两点直线距离计算
 - 支持路径规划
 - 支持 POI 搜索
@@ -28,6 +29,19 @@ uvx amap-cli --help
 uvx amap-cli config set --api-key <YOUR_AMAP_KEY>
 ```
 
+高德免费账号默认限流较严，工具默认会在每次 API 调用结束后 sleep `0.34` 秒；如需调整或关闭，可配置：
+
+```bash
+uvx amap-cli config set --request-sleep-seconds 0.34
+uvx amap-cli config set --request-sleep-seconds 0
+```
+
+地理编码示例：
+
+```bash
+uvx amap-cli geocode --address 北京南站
+```
+
 路径规划示例：
 
 ```bash
@@ -72,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 北京
@@ -83,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 结果
 
@@ -115,6 +130,18 @@ amap-cli install-skill --dir ~/.agents/skills --force
 amap-cli config set --api-key <YOUR_AMAP_KEY>
 ```
 
+设置每次高德 API 调用结束后的 sleep 时间：
+
+```bash
+amap-cli config set --request-sleep-seconds 0.34
+```
+
+关闭该 sleep：
+
+```bash
+amap-cli config set --request-sleep-seconds 0
+```
+
 查看当前配置：
 
 ```bash
@@ -127,6 +154,12 @@ amap-cli config show
 ~/Library/Application Support/amap-cli/config.json
 ```
 
+说明：
+
+- `request_sleep_seconds` 默认为 `0.34`
+- 该配置会在每次真实的高德 API 调用结束后执行一次 sleep
+- 设置为 `0` 表示关闭节流等待
+
 ### 安装 Skill
 
 基础格式：
@@ -145,6 +178,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.4}/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,13 +67,14 @@ uv run amap-cli distance --from 116.397,39.909 --to 116.407,39.904
 - `state.mode=straight_line`
 - `summary.distance` 返回两点之间的直线距离（米）
 
-### 3. 配置写入与自动读取
+### 4. 配置写入与自动读取
 
 为避免污染真实用户配置，验证时使用隔离 `HOME`：
 
 ```bash
 TMP_HOME=$(mktemp -d)
 HOME="$TMP_HOME" uv run amap-cli config set --api-key test-demo-key --timeout-seconds 12
+HOME="$TMP_HOME" uv run amap-cli config set --request-sleep-seconds 0
 HOME="$TMP_HOME" uv run amap-cli config show
 ```
 
@@ -58,8 +84,9 @@ HOME="$TMP_HOME" uv run amap-cli config show
 - macOS 下配置落在 `~/Library/Application Support/amap-cli/config.json`
 - 再次执行 `config show` 时可自动读取刚写入的配置
 - `api_key` 输出已脱敏
+- `request_sleep_seconds` 可写入为 `0`，用于关闭默认的请求后 sleep
 
-### 4. `route` 典型输入通过 CLI 主入口走通到 handler
+### 5. `route` 典型输入通过 CLI 主入口走通到 handler
 
 说明：
 
@@ -85,7 +112,7 @@ route --from 北京南站 --to 天安门 --type driving
 - 起终点地名与坐标正确进入输出
 - `summary.distance`、`summary.time`、`summary.steps` 正常生成
 
-### 5. `search-poi` 典型输入通过 CLI 主入口走通到 handler
+### 6. `search-poi` 典型输入通过 CLI 主入口走通到 handler
 
 说明：
 
@@ -130,5 +157,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.4}/pyproject.toml

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

{amap_cli-0.1.2 → amap_cli-0.1.4}/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.4}/src/amap_cli/api.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import json
+import time
 from typing import Any
 from urllib.error import HTTPError, URLError
 from urllib.parse import urlencode
@@ -39,32 +40,36 @@ class AmapApiClient:
         )
 
         try:
-            with urlopen(request, timeout=self.config.timeout_seconds) as response:
-                body = response.read().decode("utf-8")
-        except HTTPError as exc:
-            response_body = exc.read().decode("utf-8", errors="ignore")
-            raise ApiRequestError(
-                f"高德 API HTTP 请求失败：{exc.code}",
-                details={"status": exc.code, "body": response_body},
-            ) from exc
-        except URLError as exc:
-            raise ApiRequestError(
-                "无法连接高德 API。",
-                details={"reason": str(exc.reason)},
-            ) from exc
-        except TimeoutError as exc:
-            raise ApiRequestError("请求高德 API 超时。") from exc
+            try:
+                with urlopen(request, timeout=self.config.timeout_seconds) as response:
+                    body = response.read().decode("utf-8")
+            except HTTPError as exc:
+                response_body = exc.read().decode("utf-8", errors="ignore")
+                raise ApiRequestError(
+                    f"高德 API HTTP 请求失败：{exc.code}",
+                    details={"status": exc.code, "body": response_body},
+                ) from exc
+            except URLError as exc:
+                raise ApiRequestError(
+                    "无法连接高德 API。",
+                    details={"reason": str(exc.reason)},
+                ) from exc
+            except TimeoutError as exc:
+                raise ApiRequestError("请求高德 API 超时。") from exc
 
-        try:
-            payload = json.loads(body)
-        except json.JSONDecodeError as exc:
-            raise ApiRequestError(
-                "高德 API 返回了非 JSON 响应。",
-                details={"body": body[:500]},
-            ) from exc
+            try:
+                payload = json.loads(body)
+            except json.JSONDecodeError as exc:
+                raise ApiRequestError(
+                    "高德 API 返回了非 JSON 响应。",
+                    details={"body": body[:500]},
+                ) from exc
 
-        self._raise_for_amap_error(payload)
-        return payload
+            self._raise_for_amap_error(payload)
+            return payload
+        finally:
+            if self.config.request_sleep_seconds > 0:
+                time.sleep(self.config.request_sleep_seconds)
 
     def _build_url(self, path: str, params: dict[str, Any]) -> str:
         """Build a full request URL from config and query params."""

{amap_cli-0.1.2 → amap_cli-0.1.4}/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)
@@ -54,6 +56,11 @@ def _register_config_command(
         type=float,
         help="请求超时时间（秒）",
     )
+    set_parser.add_argument(
+        "--request-sleep-seconds",
+        type=float,
+        help="每次高德 API 调用结束后的 sleep 时间（秒，0 表示关闭）",
+    )
     set_parser.set_defaults(handler=_handle_config_set)
 
     show_parser = config_subparsers.add_parser("show", help="查看当前配置（敏感信息脱敏）")
@@ -71,15 +78,17 @@ def _handle_config_set(args: argparse.Namespace) -> dict[str, Any]:
         args.api_key is None
         and args.base_url is None
         and args.timeout_seconds is None
+        and args.request_sleep_seconds is None
     ):
         raise ValidationError(
-            "请至少提供一个配置项，例如 `--api-key`、`--base-url` 或 `--timeout-seconds`。"
+            "请至少提供一个配置项，例如 `--api-key`、`--base-url`、`--timeout-seconds` 或 `--request-sleep-seconds`。"
         )
 
     config = save_config(
         api_key=args.api_key,
         base_url=args.base_url,
         timeout_seconds=args.timeout_seconds,
+        request_sleep_seconds=args.request_sleep_seconds,
     )
     return {
         "message": "配置已保存。",

{amap_cli-0.1.2 → amap_cli-0.1.4}/src/amap_cli/config.py

@@ -15,6 +15,7 @@ APP_NAME = "amap-cli"
 CONFIG_FILE_NAME = "config.json"
 DEFAULT_BASE_URL = "https://restapi.amap.com"
 DEFAULT_TIMEOUT_SECONDS = 10.0
+DEFAULT_REQUEST_SLEEP_SECONDS = 0.34
 
 
 @dataclass(slots=True)
@@ -24,6 +25,7 @@ class AmapConfig:
     api_key: str | None = None
     base_url: str = DEFAULT_BASE_URL
     timeout_seconds: float = DEFAULT_TIMEOUT_SECONDS
+    request_sleep_seconds: float = DEFAULT_REQUEST_SLEEP_SECONDS
 
     @classmethod
     def from_dict(cls, raw: dict[str, Any]) -> "AmapConfig":
@@ -31,6 +33,10 @@ class AmapConfig:
         api_key = raw.get("api_key")
         base_url = raw.get("base_url", DEFAULT_BASE_URL)
         timeout_seconds = raw.get("timeout_seconds", DEFAULT_TIMEOUT_SECONDS)
+        request_sleep_seconds = raw.get(
+            "request_sleep_seconds",
+            DEFAULT_REQUEST_SLEEP_SECONDS,
+        )
 
         if api_key is not None and not isinstance(api_key, str):
             raise ConfigError("配置文件中的 api_key 格式无效。")
@@ -38,6 +44,11 @@ class AmapConfig:
             raise ConfigError("配置文件中的 base_url 格式无效。")
         if not isinstance(timeout_seconds, (int, float)) or timeout_seconds <= 0:
             raise ConfigError("配置文件中的 timeout_seconds 格式无效。")
+        if (
+            not isinstance(request_sleep_seconds, (int, float))
+            or request_sleep_seconds < 0
+        ):
+            raise ConfigError("配置文件中的 request_sleep_seconds 格式无效。")
 
         normalized_api_key = None
         if api_key is not None:
@@ -47,6 +58,7 @@ class AmapConfig:
             api_key=normalized_api_key,
             base_url=base_url.strip(),
             timeout_seconds=float(timeout_seconds),
+            request_sleep_seconds=float(request_sleep_seconds),
         )
 
     def to_dict(self, *, mask_secrets: bool = False) -> dict[str, Any]:
@@ -149,6 +161,7 @@ def save_config(
     api_key: str | None = None,
     base_url: str | None = None,
     timeout_seconds: float | None = None,
+    request_sleep_seconds: float | None = None,
 ) -> AmapConfig:
     """Persist config updates to the OS-specific config path."""
     config = load_config(required=False) or AmapConfig()
@@ -170,6 +183,11 @@ def save_config(
             raise ValidationError("`--timeout-seconds` 必须大于 0。")
         config.timeout_seconds = float(timeout_seconds)
 
+    if request_sleep_seconds is not None:
+        if request_sleep_seconds < 0:
+            raise ValidationError("`--request-sleep-seconds` 不能小于 0。")
+        config.request_sleep_seconds = float(request_sleep_seconds)
+
     path = get_config_path()
     try:
         path.parent.mkdir(parents=True, exist_ok=True)

amap_cli-0.1.4/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.4}/uv.lock

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