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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: amap-cli
-Version: 0.1.0
+Version: 0.1.2
 Summary: Pure command-line CLI for Amap APIs.
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
@@ -94,6 +94,24 @@ amap-cli search-poi --keyword 星巴克 --city 北京
 - `distance` 命令在起终点都为坐标时可直接本地计算，不依赖 API Key
 - 建议 Agent 直接解析命令返回的 JSON 结果
 
+如果需要将内置 skill 安装到指定目录，例如 Agent 的 skills 根目录，可以执行：
+
+```bash
+amap-cli install-skill --dir ~/.agents/skills
+```
+
+执行后会在目标目录下生成：
+
+```text
+~/.agents/skills/amap-cli/SKILL.md
+```
+
+如果目标目录中已存在同名 skill，可追加 `--force` 覆盖：
+
+```bash
+amap-cli install-skill --dir ~/.agents/skills --force
+```
+
 ## 命令说明
 
 ### 配置
@@ -116,6 +134,24 @@ amap-cli config show
 ~/Library/Application Support/amap-cli/config.json
 ```
 
+### 安装 Skill
+
+基础格式：
+
+```bash
+amap-cli install-skill --dir <skills目录>
+```
+
+可选参数：
+
+- `--force`
+
+说明：
+
+- 会将内置的 `amap-cli` skill 安装到目标目录下的 `amap-cli/` 子目录
+- 当目标目录不存在时会自动创建
+- 当目标目录中已存在同名 skill 时，默认报错；追加 `--force` 后会覆盖
+
 ### 路径规划
 
 基础格式：
@@ -268,7 +304,7 @@ uv publish \
 如果只是验证包能否被安装，可以执行：
 
 ```bash
-uvx --index-url https://test.pypi.org/simple/ amap-cli --help
+uvx --index https://test.pypi.org/simple/ amap-cli --help
 ```
 
 ### 5. 发布到正式 PyPI

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

@@ -87,6 +87,24 @@ amap-cli search-poi --keyword 星巴克 --city 北京
 - `distance` 命令在起终点都为坐标时可直接本地计算，不依赖 API Key
 - 建议 Agent 直接解析命令返回的 JSON 结果
 
+如果需要将内置 skill 安装到指定目录，例如 Agent 的 skills 根目录，可以执行：
+
+```bash
+amap-cli install-skill --dir ~/.agents/skills
+```
+
+执行后会在目标目录下生成：
+
+```text
+~/.agents/skills/amap-cli/SKILL.md
+```
+
+如果目标目录中已存在同名 skill，可追加 `--force` 覆盖：
+
+```bash
+amap-cli install-skill --dir ~/.agents/skills --force
+```
+
 ## 命令说明
 
 ### 配置
@@ -109,6 +127,24 @@ amap-cli config show
 ~/Library/Application Support/amap-cli/config.json
 ```
 
+### 安装 Skill
+
+基础格式：
+
+```bash
+amap-cli install-skill --dir <skills目录>
+```
+
+可选参数：
+
+- `--force`
+
+说明：
+
+- 会将内置的 `amap-cli` skill 安装到目标目录下的 `amap-cli/` 子目录
+- 当目标目录不存在时会自动创建
+- 当目标目录中已存在同名 skill 时，默认报错；追加 `--force` 后会覆盖
+
 ### 路径规划
 
 基础格式：
@@ -261,7 +297,7 @@ uv publish \
 如果只是验证包能否被安装，可以执行：
 
 ```bash
-uvx --index-url https://test.pypi.org/simple/ amap-cli --help
+uvx --index https://test.pypi.org/simple/ amap-cli --help
 ```
 
 ### 5. 发布到正式 PyPI

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "amap-cli"
-version = "0.1.0"
+version = "0.1.2"
 description = "Pure command-line CLI for Amap APIs."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -16,5 +16,8 @@ amap-cli = "amap_cli.cli:main"
 [tool.hatch.build.targets.wheel]
 packages = ["src/amap_cli"]
 
+[tool.hatch.build.targets.wheel.force-include]
+"skills" = "amap_cli/skills"
+
 [tool.uv]
 package = true

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

@@ -11,6 +11,7 @@ from amap_cli.errors import AmapCliError, ValidationError
 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
+from amap_cli.skill import register_install_skill_command
 
 
 class JsonArgumentParser(argparse.ArgumentParser):
@@ -29,6 +30,7 @@ def build_parser() -> JsonArgumentParser:
     subparsers = parser.add_subparsers(dest="command")
 
     _register_config_command(subparsers)
+    register_install_skill_command(subparsers)
     register_distance_command(subparsers)
     register_route_command(subparsers)
     register_search_poi_command(subparsers)

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

@@ -81,27 +81,67 @@ def get_config_path() -> Path:
     return get_config_dir() / CONFIG_FILE_NAME
 
 
+def _merge_error_details(
+    current: Any | None,
+    *,
+    path: Path,
+    operation: str | None = None,
+    exc: BaseException | None = None,
+) -> dict[str, Any]:
+    """Attach config file context to an error payload."""
+    details = current.copy() if isinstance(current, dict) else {}
+    details["path"] = str(path)
+    if operation is not None:
+        details["operation"] = operation
+    if exc is not None:
+        details["type"] = type(exc).__name__
+        details["reason"] = str(exc)
+    return details
+
+
 def load_config(*, required: bool = False) -> AmapConfig | None:
     """Load config from disk, optionally requiring it to exist."""
     path = get_config_path()
-    if not path.exists():
+    try:
+        exists = path.exists()
+    except OSError as exc:
+        raise ConfigError(
+            "检查配置文件状态失败。",
+            details=_merge_error_details(None, path=path, operation="stat", exc=exc),
+        ) from exc
+
+    if not exists:
         if required:
             raise MissingConfigError(
-                "未找到高德 API 配置，请先执行 `amap-cli config set --api-key <KEY>`。"
+                "未找到高德 API 配置，请先执行 `amap-cli config set --api-key <KEY>`。",
+                details=_merge_error_details(None, path=path),
             )
         return None
 
     try:
         raw = json.loads(path.read_text(encoding="utf-8"))
     except json.JSONDecodeError as exc:
-        raise ConfigError("配置文件不是合法的 JSON。", details={"path": str(path)}) from exc
+        raise ConfigError(
+            "配置文件不是合法的 JSON。",
+            details=_merge_error_details(None, path=path, operation="read", exc=exc),
+        ) from exc
     except OSError as exc:
-        raise ConfigError("读取配置文件失败。", details={"path": str(path)}) from exc
+        raise ConfigError(
+            "读取配置文件失败。",
+            details=_merge_error_details(None, path=path, operation="read", exc=exc),
+        ) from exc
 
     if not isinstance(raw, dict):
-        raise ConfigError("配置文件内容格式无效。", details={"path": str(path)})
+        raise ConfigError(
+            "配置文件内容格式无效。",
+            details=_merge_error_details(None, path=path),
+        )
 
-    return AmapConfig.from_dict(raw)
+    try:
+        return AmapConfig.from_dict(raw)
+    except ConfigError as exc:
+        exc.details = _merge_error_details(exc.details, path=path)
+        raise
 
 
 def save_config(
@@ -131,11 +171,29 @@ def save_config(
         config.timeout_seconds = float(timeout_seconds)
 
     path = get_config_path()
-    path.parent.mkdir(parents=True, exist_ok=True)
-    path.write_text(
-        json.dumps(config.to_dict(), ensure_ascii=False, indent=2) + "\n",
-        encoding="utf-8",
-    )
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+    except OSError as exc:
+        raise ConfigError(
+            "创建配置目录失败。",
+            details=_merge_error_details(
+                None,
+                path=path.parent,
+                operation="create_dir",
+                exc=exc,
+            ),
+        ) from exc
+
+    try:
+        path.write_text(
+            json.dumps(config.to_dict(), ensure_ascii=False, indent=2) + "\n",
+            encoding="utf-8",
+        )
+    except OSError as exc:
+        raise ConfigError(
+            "写入配置文件失败。",
+            details=_merge_error_details(None, path=path, operation="write", exc=exc),
+        ) from exc
 
     if os.name != "nt":
         try:

amap_cli-0.1.2/src/amap_cli/skill.py

@@ -0,0 +1,102 @@
+"""Skill installation commands."""
+
+from __future__ import annotations
+
+import argparse
+import shutil
+from importlib import resources
+from pathlib import Path
+from typing import Any
+
+from amap_cli.errors import AmapCliError
+
+
+def register_install_skill_command(
+    subparsers: argparse._SubParsersAction[argparse.ArgumentParser],
+) -> None:
+    """Register the bundled skill installation command."""
+    parser = subparsers.add_parser(
+        "install-skill",
+        help="安装内置 skill 到指定目录",
+    )
+    parser.add_argument(
+        "--dir",
+        dest="target_dir",
+        required=True,
+        help="skill 安装根目录，例如 ~/.agents/skills",
+    )
+    parser.add_argument(
+        "--force",
+        action="store_true",
+        help="目标 skill 已存在时覆盖",
+    )
+    parser.set_defaults(handler=_handle_install_skill)
+
+
+def _handle_install_skill(args: argparse.Namespace) -> dict[str, Any]:
+    """Install the bundled skill into the requested directory."""
+    skill_name = "amap-cli"
+    source_dir = _resolve_bundled_skill_dir()
+    target_root = Path(args.target_dir).expanduser().resolve()
+    target_skill_dir = target_root / skill_name
+
+    overwritten = False
+    if target_skill_dir.exists():
+        if not args.force:
+            raise AmapCliError(
+                f"目标目录已存在 skill：{target_skill_dir}",
+                code="SKILL_ALREADY_EXISTS",
+                details={
+                    "skill_path": str(target_skill_dir),
+                    "hint": "如需覆盖，请追加 --force。",
+                },
+                exit_code=1,
+            )
+        if target_skill_dir.is_dir():
+            shutil.rmtree(target_skill_dir)
+        else:
+            target_skill_dir.unlink()
+        overwritten = True
+
+    target_root.mkdir(parents=True, exist_ok=True)
+    _copy_tree(source_dir, target_skill_dir)
+
+    return {
+        "message": "skill 安装完成。",
+        "skill_name": skill_name,
+        "source": str(source_dir),
+        "target_dir": str(target_root),
+        "skill_path": str(target_skill_dir),
+        "overwritten": overwritten,
+    }
+
+
+def _resolve_bundled_skill_dir() -> Any:
+    """Locate the bundled skill directory in installed or source layouts."""
+    packaged_skill_dir = resources.files("amap_cli").joinpath("skills", "amap-cli")
+    packaged_skill_file = packaged_skill_dir.joinpath("SKILL.md")
+    if packaged_skill_file.is_file():
+        return packaged_skill_dir
+
+    repo_skill_dir = Path(__file__).resolve().parents[2] / "skills" / "amap-cli"
+    if repo_skill_dir.is_dir():
+        return repo_skill_dir
+
+    raise AmapCliError(
+        "未找到内置 skill 资源。",
+        code="SKILL_RESOURCE_NOT_FOUND",
+        details={"skill_name": "amap-cli"},
+        exit_code=1,
+    )
+
+
+def _copy_tree(source_dir: Any, target_dir: Path) -> None:
+    """Recursively copy the skill directory into the target path."""
+    target_dir.mkdir(parents=True, exist_ok=True)
+    for source_path in source_dir.iterdir():
+        target_path = target_dir / source_path.name
+        if source_path.is_dir():
+            _copy_tree(source_path, target_path)
+            continue
+        with source_path.open("rb") as source_file, target_path.open("wb") as target_file:
+            shutil.copyfileobj(source_file, target_file)

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

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