amap-cli 0.1.0__tar.gz

amap_cli-0.1.0/.gitignore

@@ -0,0 +1,4 @@
+.venv/
+__pycache__/
+*.pyc
+dist/

amap_cli-0.1.0/.trae/specs/build-amap-cli/checklist.md

@@ -0,0 +1,9 @@
+# Checklist
+
+- [x] 已定义可本地安装的纯命令行工具形态，并明确使用 `uv` 管理项目
+- [x] 已定义命令行配置高德 API Key 的能力，并明确配置按操作系统规范持久化保存
+- [x] 已定义缺少配置时的错误反馈行为，确保用户知道如何补全配置
+- [x] 已定义 `route` 命令的核心参数与输出要求，接口风格对齐官方 CLI，且不包含 `--json` 输入支持
+- [x] 已定义 `search-poi` 命令的核心参数与输出要求，接口风格对齐官方 CLI，且不包含 `--json` 输入支持
+- [x] 已定义统一的 JSON 输出结构，便于 Agent 解析成功和失败结果
+- [x] 已定义 Agent 配套 skill 文档的交付要求

amap_cli-0.1.0/.trae/specs/build-amap-cli/spec.md

@@ -0,0 +1,111 @@
+# 纯命令行高德地图 CLI Spec
+
+## Why
+
+高德官方 CLI 依赖 GUI 容器，不适合 AI Agent 在纯终端或无界面环境下稳定调用。我们需要一个基于高德地图 API 的纯命令行工具，支持本地安装、命令行配置密钥、路径规划和 POI 搜索，并提供配套 skill 文档供 Agent 使用。
+
+## What Changes
+
+- 新建一个使用 Python 开发、可作为本地 CLI 安装的高德地图工具，依赖与项目管理使用 `uv`
+- 新增配置命令，支持通过命令行写入并读取高德 API 所需配置，按当前操作系统的用户配置目录规范保存
+- 新增 `route` 子命令，接口设计尽量对齐官方 CLI 的路径规划参数风格，但不支持 `--json` 输入
+- 新增 `search-poi` 子命令，接口设计尽量对齐官方 CLI 的 POI 搜索参数风格，但不支持 `--json` 输入
+- 统一所有命令的机器可读输出格式，便于 Agent 解析和处理错误
+- 提供配套的 skill 文档，说明 Agent 如何安装、配置并调用该 CLI
+
+## Impact
+
+- Affected specs: CLI 安装能力、配置管理、路径规划、POI 搜索、Agent 集成
+- Affected code: `pyproject.toml`、`src/amap_cli/` 包结构、CLI 入口、配置读写模块、高德 API 客户端、skill 文档
+
+## ADDED Requirements
+
+### Requirement: 本地可安装的纯命令行工具
+
+系统 SHALL 提供一个可在本地安装和调用的纯命令行工具，安装后可直接通过统一命令名执行，不依赖 GUI 进程或浏览器容器。
+
+#### Scenario: 安装后可直接调用
+
+- **WHEN** 用户在本地通过 `uv` 完成项目安装
+- **THEN** 终端中可以直接调用 CLI 命令查看帮助信息
+- **AND** 工具在执行时不要求额外启动 GUI 服务
+
+### Requirement: 按操作系统规范保存高德 API 配置
+
+系统 SHALL 提供命令行配置能力，用于保存高德 API 配置项，并按当前操作系统的用户配置目录规范持久化保存，在后续请求中自动读取。
+
+#### Scenario: 保存并复用配置
+
+- **WHEN** 用户通过 CLI 写入高德 API Key 与相关配置项
+- **THEN** 工具将配置保存到当前操作系统推荐的用户配置目录
+- **AND** 后续执行路径规划或 POI 搜索命令时会自动读取该配置
+
+#### Scenario: 缺少配置时返回可读错误
+
+- **WHEN** 用户尚未完成配置就直接调用高德 API 相关命令
+- **THEN** CLI 返回明确的错误信息
+- **AND** 错误信息提示用户先执行配置命令
+
+### Requirement: 路径规划命令接口对齐官方 CLI 风格
+
+系统 SHALL 提供 `route` 子命令，并尽量复用官方 CLI 的核心参数设计，包括 `--from`、`--from-name`、`--to`、`--to-name`、`--type`、`--waypoints`、`--policy`、`--strategy`、`--city`，但不支持 `--json` 输入。
+
+#### Scenario: 使用地名进行路径规划
+
+- **WHEN** 用户调用 `route --from 北京南站 --to 天安门 --type driving`
+- **THEN** CLI 调用高德地图 API 完成路径规划
+- **AND** 返回包含起终点、出行方式、距离、预计时间和步骤摘要的 JSON 结果
+
+#### Scenario: 使用坐标进行路径规划
+
+- **WHEN** 用户调用 `route --from 116.397,39.909 --to 116.407,39.904 --type walking`
+- **THEN** CLI 可以正确识别坐标输入并完成路径规划
+
+### Requirement: POI 搜索命令接口对齐官方 CLI 风格
+
+系统 SHALL 提供 `search-poi` 子命令，并尽量复用官方 CLI 的核心参数设计，包括 `--keyword`、`--city`、`--center`、`--radius`、`--pageSize`、`--pageIndex`，但不支持 `--json` 输入。
+
+#### Scenario: 按城市关键词搜索 POI
+
+- **WHEN** 用户调用 `search-poi --keyword 星巴克 --city 北京 --pageSize 1`
+- **THEN** CLI 调用高德地图 API 执行搜索
+- **AND** 返回包含查询状态、POI 列表、分页信息的 JSON 结果
+
+#### Scenario: 按周边范围搜索 POI
+
+- **WHEN** 用户调用 `search-poi --keyword 咖啡 --center 120.155,30.274 --radius 1000`
+- **THEN** CLI 可以基于坐标与半径执行周边搜索
+
+### Requirement: 面向 Agent 的稳定 JSON 输出
+
+系统 SHALL 为成功与失败结果提供稳定、可机读的 JSON 输出格式，至少包含 `success`、`data`、`error` 字段，便于 Agent 可靠解析。
+
+#### Scenario: 请求成功时返回统一结构
+
+- **WHEN** 任一业务命令执行成功
+- **THEN** CLI 返回 `success=true`
+- **AND** 业务结果位于 `data` 字段中
+- **AND** `error` 为 `null`
+
+#### Scenario: 请求失败时返回统一结构
+
+- **WHEN** 参数校验失败、配置缺失或高德 API 返回异常
+- **THEN** CLI 返回 `success=false`
+- **AND** `error` 字段中包含明确错误原因
+
+### Requirement: 提供 Agent 使用说明
+
+系统 SHALL 提供配套的 skill 文档，说明 CLI 的安装方式、配置方式、命令用法、输出约定与常见错误处理方式，便于 AI Agent 直接集成。
+
+#### Scenario: Agent 按文档完成调用
+
+- **WHEN** Agent 按 skill 文档执行安装、配置与命令调用
+- **THEN** Agent 可以在无需 GUI 的前提下完成路径规划与 POI 搜索
+
+## MODIFIED Requirements
+
+无
+
+## REMOVED Requirements
+
+无

amap_cli-0.1.0/.trae/specs/build-amap-cli/tasks.md

@@ -0,0 +1,46 @@
+# Tasks
+
+- [x] Task 1: 搭建基于 `uv` 的 Python CLI 项目骨架
+  - [x] SubTask 1.1: 初始化 `pyproject.toml`、源码目录与 CLI 入口
+  - [x] SubTask 1.2: 配置本地可安装的命令名与依赖管理方式
+  - [x] SubTask 1.3: 确认安装后可通过帮助命令看到基础用法
+
+- [x] Task 2: 实现高德 API 配置管理
+  - [x] SubTask 2.1: 设计配置文件结构与操作系统路径解析策略
+  - [x] SubTask 2.2: 实现配置写入、读取与缺失校验
+  - [x] SubTask 2.3: 提供命令行配置入口，并输出可读结果
+
+- [x] Task 3: 实现统一请求与输出基础能力
+  - [x] SubTask 3.1: 封装高德 API 请求客户端与公共错误处理
+  - [x] SubTask 3.2: 实现统一的 JSON 输出结构
+  - [x] SubTask 3.3: 处理坐标、地名等公共参数逻辑
+
+- [x] Task 4: 实现路径规划命令
+  - [x] SubTask 4.1: 按官方 CLI 风格定义 `route` 参数接口
+  - [x] SubTask 4.2: 对接高德路径规划相关 API
+  - [x] SubTask 4.3: 输出包含摘要与步骤信息的结果结构
+
+- [x] Task 5: 实现 POI 搜索命令
+  - [x] SubTask 5.1: 按官方 CLI 风格定义 `search-poi` 参数接口
+  - [x] SubTask 5.2: 对接高德 POI 搜索相关 API
+  - [x] SubTask 5.3: 输出包含 POI 列表与分页信息的结果结构
+
+- [x] Task 6: 编写 Agent 配套使用文档
+  - [x] SubTask 6.1: 编写 skill 文档中的安装与配置说明
+  - [x] SubTask 6.2: 编写路径规划与 POI 搜索的调用示例
+  - [x] SubTask 6.3: 补充统一输出格式与常见错误说明
+
+- [x] Task 7: 完成命令行手动验证
+  - [x] SubTask 7.1: 验证本地安装与帮助命令
+  - [x] SubTask 7.2: 验证配置写入与自动读取
+  - [x] SubTask 7.3: 验证路径规划命令的典型输入
+  - [x] SubTask 7.4: 验证 POI 搜索命令的典型输入
+
+## Task Dependencies
+
+- Task 2 depends on Task 1
+- Task 3 depends on Task 1 and Task 2
+- Task 4 depends on Task 3
+- Task 5 depends on Task 3
+- Task 6 depends on Task 4 and Task 5
+- Task 7 depends on Task 2, Task 4, Task 5, and Task 6

amap_cli-0.1.0/PKG-INFO

@@ -0,0 +1,290 @@
+Metadata-Version: 2.5
+Name: amap-cli
+Version: 0.1.0
+Summary: Pure command-line CLI for Amap APIs.
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# amap-cli
+
+`amap-cli` 是一个基于高德开放平台 Web API 的纯命令行工具，面向终端环境和 AI Agent 使用。
+
+## 功能特性
+
+- 纯命令行调用高德地图 API
+- 支持命令行写入和读取高德 API Key
+- 支持两点直线距离计算
+- 支持路径规划
+- 支持 POI 搜索
+- 所有命令统一返回机器可读 JSON
+- 提供配套的 Agent skill，便于在智能体环境中直接调用
+
+## 安装与使用
+
+### 方式一：直接使用 `uvx` 运行
+
+项目发布到 PyPI 后，可以直接执行：
+
+```bash
+uvx amap-cli --help
+```
+
+配置高德 API Key：
+
+```bash
+uvx amap-cli config set --api-key <YOUR_AMAP_KEY>
+```
+
+路径规划示例：
+
+```bash
+uvx amap-cli route \
+  --from 北京南站 \
+  --to 天安门 \
+  --type driving
+```
+
+直线距离示例：
+
+```bash
+uvx amap-cli distance \
+  --from 116.397,39.909 \
+  --to 116.407,39.904
+```
+
+POI 搜索示例：
+
+```bash
+uvx amap-cli search-poi \
+  --keyword 星巴克 \
+  --city 北京 \
+  --pageSize 5
+```
+
+### 方式二：安装后使用
+
+如果希望安装到本机工具目录，执行：
+
+```bash
+uv tool install amap-cli
+```
+
+安装完成后可直接调用：
+
+```bash
+amap-cli --help
+```
+
+配置和业务命令示例：
+
+```bash
+amap-cli config set --api-key <YOUR_AMAP_KEY>
+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 北京
+```
+
+## Skill 使用说明
+
+本项目提供了配套的 `amap-cli` skill，适合在支持 skill 的 Agent 环境中使用。
+
+- skill 的目标是让 Agent 直接通过 `uvx amap-cli` 调用本工具
+- 使用方式与上面的“直接使用 `uvx` 运行”一致
+- 使用前先配置高德 API Key，之后即可发起路径规划和 POI 搜索
+- `distance` 命令在起终点都为坐标时可直接本地计算，不依赖 API Key
+- 建议 Agent 直接解析命令返回的 JSON 结果
+
+## 命令说明
+
+### 配置
+
+写入 API Key：
+
+```bash
+amap-cli config set --api-key <YOUR_AMAP_KEY>
+```
+
+查看当前配置：
+
+```bash
+amap-cli config show
+```
+
+配置会按照当前操作系统规范保存在用户配置目录中。macOS 下默认路径为：
+
+```text
+~/Library/Application Support/amap-cli/config.json
+```
+
+### 路径规划
+
+基础格式：
+
+```bash
+amap-cli route \
+  --from <结构化地址|地标名称|经度,纬度> \
+  --to <结构化地址|地标名称|经度,纬度> \
+  --type <driving|walking|riding|transit>
+```
+
+可选参数：
+
+- `--from-name`
+- `--to-name`
+- `--waypoints`
+- `--policy`
+- `--strategy`
+- `--city`
+
+说明：
+
+- `--waypoints` 和 `--policy` 仅 `driving` 支持
+- `--strategy` 和 `--city` 仅 `transit` 支持
+- 地理编码仅支持详细的结构化地址，以及地标性名胜景区、建筑物名称
+- 当起点、终点或途经点使用上述名称并解析成功时，返回结果中的对应节点会附带 `formattedAddress`
+- 对于其他较模糊的名称，建议先通过 `search-poi` 获取目标地点坐标，再调用 `route`
+- 不支持 `--json` 输入
+
+### 直线距离
+
+基础格式：
+
+```bash
+amap-cli distance \
+  --from <结构化地址|地标名称|经度,纬度> \
+  --to <结构化地址|地标名称|经度,纬度>
+```
+
+可选参数：
+
+- `--from-name`
+- `--to-name`
+
+说明：
+
+- 当 `--from` 和 `--to` 都是坐标时，直接在本地计算直线距离
+- 当任一输入为结构化地址或地标性名胜景区、建筑物名称时，会先调用高德地理编码接口解析坐标，再做本地计算
+- 当输入为上述名称时，返回结果中的 `state.from.formattedAddress` / `state.to.formattedAddress` 会带上高德解析出的完整地址
+- 对于其他较模糊的名称，建议先通过 `search-poi` 获取目标地点坐标，再调用 `distance`
+- 结果中的 `summary.distance` 单位为米
+- 不支持 `--json` 输入
+
+### POI 搜索
+
+基础格式：
+
+```bash
+amap-cli search-poi --keyword <关键词>
+```
+
+可选参数：
+
+- `--city`
+- `--center`
+- `--radius`
+- `--pageSize`
+- `--pageIndex`
+
+说明：
+
+- 传入 `--center` 时执行周边搜索
+- 未传入 `--center` 时执行关键词搜索
+- 不支持 `--json` 输入
+
+## 输出格式
+
+成功时：
+
+```json
+{
+  "success": true,
+  "data": {},
+  "error": null
+}
+```
+
+失败时：
+
+```json
+{
+  "success": false,
+  "data": null,
+  "error": {
+    "code": "INVALID_ARGUMENT",
+    "message": "错误说明",
+    "details": {}
+  }
+}
+```
+
+## 本地开发
+
+安装项目依赖：
+
+```bash
+uv sync
+```
+
+本地运行：
+
+```bash
+uv run amap-cli --help
+```
+
+## PyPI 发布
+
+### 1. 确认版本号
+
+每次发布前，先更新 `pyproject.toml` 中的 `version`。  
+PyPI 不允许重复上传同一个版本号的分发包。
+
+### 2. 构建分发包
+
+```bash
+uv build
+```
+
+构建成功后会在 `dist/` 目录下生成：
+
+- `*.tar.gz`
+- `*.whl`
+
+### 3. 准备 PyPI Token
+
+登录 PyPI 后创建 API Token，推荐通过环境变量传入：
+
+```bash
+export UV_PUBLISH_TOKEN="pypi-你的token"
+```
+
+### 4. 先发布到 TestPyPI 验证（推荐）
+
+```bash
+uv publish \
+  --publish-url https://test.pypi.org/legacy/ \
+  --check-url https://test.pypi.org/simple/
+```
+
+如果只是验证包能否被安装，可以执行：
+
+```bash
+uvx --index-url https://test.pypi.org/simple/ amap-cli --help
+```
+
+### 5. 发布到正式 PyPI
+
+确认 TestPyPI 验证通过后，执行：
+
+```bash
+uv publish
+```
+
+### 6. 发布后验证
+
+发布完成后，推荐优先使用 `uvx` 做一次快速验证：
+
+```bash
+uvx amap-cli --help
+```
+
+发布后，推荐优先使用 `uvx amap-cli` 进行一次性调用，或使用 `uv tool install amap-cli` 安装到本地。