shipcli 0.0.1__py3-none-any.whl

shipcli/__init__.py

@@ -0,0 +1,5 @@
+"""shipcli 包入口。"""
+
+__all__ = ["__version__"]
+
+__version__ = "0.0.1"

shipcli/__main__.py

@@ -0,0 +1,11 @@
+"""shipcli 模块入口。"""
+
+from __future__ import annotations
+
+import sys
+
+from shipcli.cli import main
+
+
+if __name__ == "__main__":
+    sys.exit(main())

shipcli/builder.py

@@ -0,0 +1,220 @@
+"""shipcli 纯 Python 构建流程。
+
+方向 A：build 产出标准的 wheel/sdist（去掉 PyInstaller 二进制）。
+- debug 构建（`shipcli build`）产 dev 版 wheel，版本号 `<base>.devN`。
+- release 构建（`shipcli build --release`）产 release 版 wheel/sdist。
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import json
+import re
+import subprocess
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+from shipcli.config import BuildConfig, config_path, load_config
+
+
+@dataclass(frozen=True)
+class BuildPlan:
+    """描述一次构建的关键路径与版本信息。"""
+
+    app_name: str
+    build_root: Path
+    dist_root: Path
+    product_dir: Path
+    dist_dir: Path
+    product_version: str
+    base_version: str
+    build_number: int
+    release: bool
+
+
+def bump_version(version: str, part: str) -> str:
+    """把语义版本号的指定位 +1，低位归零。"""
+    if part not in {"major", "minor", "patch"}:
+        raise ValueError("版本位仅支持 major / minor / patch")
+    segments = version.split(".")
+    if len(segments) != 3 or not all(seg.isdigit() for seg in segments):
+        raise ValueError(f"版本号不是标准的三段语义版本：{version}")
+    major, minor, patch = (int(seg) for seg in segments)
+    if part == "major":
+        major, minor, patch = major + 1, 0, 0
+    elif part == "minor":
+        minor, patch = minor + 1, 0
+    else:
+        patch += 1
+    return f"{major}.{minor}.{patch}"
+
+
+def resolve_build_plan(
+    project_root: Path,
+    config: BuildConfig,
+    release: bool = False,
+    increase: str | None = None,
+) -> BuildPlan:
+    """根据配置和参数生成本次构建计划。"""
+    if increase is not None:
+        base_version = bump_version(config["version"], increase)
+    else:
+        base_version = config["version"]
+
+    build_root = project_root / config["build_root"]
+    dist_root = build_root / "dist"
+    if release:
+        build_number = config["build"]
+        product_version = base_version
+    else:
+        build_number = config["build"] + 1
+        # PEP 440 规范的 dev 版本号：`<base>.devN`（可被 pip/PyPI 接受）。
+        product_version = f"{base_version}.dev{build_number}"
+
+    product_dir = dist_root / product_version
+    dist_dir = product_dir / "dist"
+    return BuildPlan(
+        app_name=config["app_name"],
+        build_root=build_root,
+        dist_root=dist_root,
+        product_dir=product_dir,
+        dist_dir=dist_dir,
+        product_version=product_version,
+        base_version=base_version,
+        build_number=build_number,
+        release=release,
+    )
+
+
+def run_build(
+    project_root: Path,
+    release: bool = False,
+    increase: str | None = None,
+) -> BuildPlan:
+    """生成本次构建的 wheel/sdist，并在 debug 构建成功后回写 build。"""
+    config = load_config(project_root)
+    if not (project_root / "pyproject.toml").is_file():
+        raise FileNotFoundError("未找到 pyproject.toml，无法构建分发文件")
+    if shutil_is_missing_python():
+        raise RuntimeError("未找到可用的 Python 解释器")
+
+    # --increase 先把 bump 后的版本与重置的 build=0 回写配置，再据此生成计划，
+    # 保证后续 dev 号、产物目录都基于新版本与新 build 号。
+    if increase is not None:
+        config["version"] = bump_version(config["version"], increase)
+        config["build"] = 0
+        _write_version_and_build(project_root, config["version"], config["build"])
+
+    plan = resolve_build_plan(project_root, config, release=release, increase=None)
+
+    plan.build_root.mkdir(parents=True, exist_ok=True)
+    if plan.product_dir.exists():
+        import shutil
+
+        shutil.rmtree(plan.product_dir)
+    plan.product_dir.mkdir(parents=True, exist_ok=True)
+
+    # release 构建需把版本同步到 pyproject.toml，再产 wheel/sdist；
+    # dev 构建也要把 dev 版号同步进 pyproject.toml，否则 wheel 版本号不对。
+    target_version = plan.base_version if plan.release else plan.product_version
+    _sync_pyproject_version(project_root, target_version)
+    _write_package_version(project_root, config, plan.product_version)
+    _build_distributions(project_root, plan)
+
+    if not plan.release:
+        _write_build_number(project_root, plan.build_number)
+    else:
+        # release 构建会改写版本相关文件，git 仓库下自动提交，
+        # 保证后续 publish 打的 tag 落在「版本号已更新」的完整 commit 上。
+        _maybe_commit_release(project_root, plan.base_version)
+    return plan
+
+
+def _maybe_commit_release(project_root: Path, version: str) -> None:
+    """release 构建后，若为 git 仓库且有改动，自动提交版本发布点。"""
+    from shipcli.publisher import git_commit_all, git_working_tree_clean, is_git_repo
+
+    if not is_git_repo(project_root):
+        return
+    if git_working_tree_clean(project_root):
+        return
+    git_commit_all(project_root, f"release v{version}")
+
+
+def shutil_is_missing_python() -> bool:
+    """检测当前解释器是否可用（保留可测试的薄封装）。"""
+    import shutil
+
+    return shutil.which(sys.executable) is None
+
+
+def _build_distributions(project_root: Path, plan: BuildPlan) -> None:
+    """调用 `python -m build` 生成 wheel/sdist 到 plan.dist_dir。"""
+    if importlib.util.find_spec("build") is None:
+        raise RuntimeError("未安装 build，请先执行 `python3 -m pip install build`")
+
+    plan.dist_dir.mkdir(parents=True, exist_ok=True)
+    command = [
+        sys.executable,
+        "-m",
+        "build",
+        "--outdir",
+        str(plan.dist_dir),
+        str(project_root),
+    ]
+    subprocess.run(command, check=True, cwd=project_root)
+    if not any(plan.dist_dir.glob("*.whl")):
+        raise RuntimeError(f"分发文件构建失败：{plan.dist_dir}")
+
+
+def _package_init_path(project_root: Path, config: BuildConfig) -> Path:
+    """根据构建入口推导包根目录下的 __init__.py 路径。"""
+    entry = config["entry"]
+    package = entry.split("/__main__.py", 1)[0] if entry.endswith("/__main__.py") else entry.rsplit("/", 1)[0]
+    return project_root / package / "__init__.py"
+
+
+def _write_package_version(project_root: Path, config: BuildConfig, version: str) -> None:
+    """把本次构建版本写入包 __init__.py 的 __version__，供打包后运行时读取。"""
+    path = _package_init_path(project_root, config)
+    if not path.is_file():
+        raise FileNotFoundError(f"包入口文件不存在：{path}")
+    text = path.read_text(encoding="utf-8")
+    pattern = re.compile(r'(?m)^(__version__\s*=\s*")([^"]*)("\s*)$')
+    if not pattern.search(text):
+        raise RuntimeError(f"{path} 缺少 __version__ 定义，无法写入版本号")
+    synced = pattern.sub(lambda m: f'{m.group(1)}{version}{m.group(3)}', text)
+    if synced != text:
+        path.write_text(synced, encoding="utf-8")
+
+
+def _sync_pyproject_version(project_root: Path, version: str) -> None:
+    """把目标版本同步到 pyproject.toml，保证 wheel 版本号正确。"""
+    path = project_root / "pyproject.toml"
+    if not path.is_file():
+        return
+    text = path.read_text(encoding="utf-8")
+    pattern = re.compile(r'(?m)^(\s*version\s*=\s*")([^"]*)("\s*)$')
+    if not pattern.search(text):
+        return  # 静态版本号缺失时跳过（可能用了动态版本，不强行改写）
+    synced = pattern.sub(lambda m: f'{m.group(1)}{version}{m.group(3)}', text)
+    if synced != text:
+        path.write_text(synced, encoding="utf-8")
+
+
+def _write_version_and_build(project_root: Path, version: str, build: int) -> None:
+    """更新 build.config.json 中的 version 与 build 字段。"""
+    path = config_path(project_root)
+    payload = json.loads(path.read_text(encoding="utf-8"))
+    payload["version"] = version
+    payload["build"] = build
+    path.write_text(json.dumps(payload, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+
+
+def _write_build_number(project_root: Path, build_number: int) -> None:
+    """只更新 build.config.json 中的 build 字段。"""
+    path = config_path(project_root)
+    payload = json.loads(path.read_text(encoding="utf-8"))
+    payload["build"] = build_number
+    path.write_text(json.dumps(payload, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")

shipcli/cli.py

@@ -0,0 +1,185 @@
+"""shipcli argparse 主入口。"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from typing import Optional
+
+from shipcli.commands import (
+    run_build_command,
+    run_init,
+    run_install,
+    run_publish,
+    run_uninstall,
+    run_upgrade,
+)
+from shipcli.console import Console, TerminalConsole
+from shipcli.version import display_version_with_mode, install_mode
+
+
+class HelpFormatter(argparse.RawTextHelpFormatter):
+    """保持帮助文案换行，并稳定子命令列表排版。"""
+
+    def __init__(self, prog: str) -> None:
+        """固定帮助列位置，避免短说明被意外换到下一行。"""
+        super().__init__(prog, max_help_position=28)
+
+    def _format_action(self, action: argparse.Action) -> str:
+        """对子命令列表使用稳定的一行式排版。"""
+        if isinstance(action, argparse._SubParsersAction):
+            parts = [f"{self._current_indent * ' '}{self._format_action_invocation(action)}\n"]
+            subactions = action._get_subactions()
+            if not subactions:
+                return "".join(parts)
+
+            self._indent()
+            width = max(len(self._format_action_invocation(subaction)) for subaction in subactions)
+            for subaction in subactions:
+                command = self._format_action_invocation(subaction)
+                help_text = self._expand_help(subaction) if subaction.help else ""
+                parts.append(f"{self._current_indent * ' '}{command.ljust(width)}  {help_text}\n")
+            self._dedent()
+            return "".join(parts)
+        return super()._format_action(action)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """构造顶层参数解析器。"""
+    parser = argparse.ArgumentParser(
+        prog="shipcli",
+        description=(
+            f"纯 Python CLI 脚手架工具。\n"
+            f"安装形态：{install_mode()}\n\n"
+        ),
+        epilog=(
+            "示例:\n"
+            "  shipcli init demo-cli\n"
+            "  cd demo-cli && shipcli build\n"
+            "  cd demo-cli && shipcli build --release\n"
+            "  cd demo-cli && shipcli publish --github\n"
+            "  cd demo-cli && shipcli install\n"
+            "  shipcli build --project ./demo-cli\n"
+            "  shipcli upgrade                 # 升级 shipcli 自身\n"
+            "  shipcli uninstall               # 卸载 shipcli 自身\n"
+            "  demo-cli upgrade                # 升级已安装的 demo-cli\n"
+            "  demo-cli uninstall              # 卸载已安装的 demo-cli"
+        ),
+        formatter_class=HelpFormatter,
+    )
+    parser.add_argument("--version", action="store_true", help="显示版本号")
+    sub = parser.add_subparsers(dest="command", metavar="<command>")
+
+    init = sub.add_parser(
+        "init",
+        help="初始化一个新的 CLI 项目",
+        description="生成新的 Python CLI 项目目录、配置文件和基础命令。操作目标项目。",
+        formatter_class=HelpFormatter,
+    )
+    init.add_argument("path", help="目标目录路径")
+    init.add_argument("--app-name", default=None, help="命令名，如 demo")
+    init.add_argument("--package", default=None, help="Python 包名，如 demo_cli")
+    init.add_argument("--force", action="store_true", help="目标目录非空时也继续写入")
+
+    build = sub.add_parser(
+        "build",
+        help="构建目标项目",
+        description=(
+            "生成本项目的 wheel/sdist 分发文件；操作当前目录或 --project 指定的项目。\n\n"
+            "默认 dev 构建（版本号 <base>.devN）；--release 产出 release 版本。"
+        ),
+        formatter_class=HelpFormatter,
+    )
+    build.add_argument("--project", default=".", help="项目根目录；默认当前目录")
+    build.add_argument("--release", action="store_true", help="执行 release 构建")
+    build.add_argument(
+        "--increase",
+        choices=["major", "minor", "patch"],
+        default=None,
+        help="构建前把版本号指定位 +1（低位归零）并重置 build；可与 --release 同用",
+    )
+
+    publish = sub.add_parser(
+        "publish",
+        help="发布目标项目的 release 版本",
+        description="发布目标项目 build 已生成的 release 版本；不会在该命令中触发构建。",
+        formatter_class=HelpFormatter,
+    )
+    publish.add_argument("--project", default=".", help="项目根目录；默认当前目录")
+    publish.add_argument("--version", default=None, help="要发布的 release 版本；默认取配置中的 version")
+    publish.add_argument("--github", action="store_true", help="发布到 GitHub Release")
+    publish.add_argument("--pypi", action="store_true", help="发布到 PyPI 仓库")
+    publish.add_argument("--github-repo", default=None, help="GitHub 仓库，格式 owner/repo")
+    publish.add_argument("--tag", default=None, help="GitHub tag；默认 v<version>")
+    publish.add_argument("--title", default=None, help="GitHub Release 标题")
+    publish.add_argument("--notes-file", default=None, help="GitHub Release 说明文件路径")
+    publish.add_argument("--draft", action="store_true", help="创建草稿 GitHub Release")
+    publish.add_argument("--prerelease", action="store_true", help="标记为 GitHub 预发布")
+    publish.add_argument("--repository-url", default=None, help="PyPI 仓库地址；默认使用 twine 默认配置")
+    publish.add_argument("--dist-dir", default=None, help="PyPI 分发目录；默认当前项目下的 dist")
+    publish.add_argument("--skip-existing", action="store_true", help="PyPI 上传时跳过已存在文件")
+    publish.add_argument("--no-tag", action="store_true", help="发布成功后不打 git tag")
+    publish.add_argument("--no-push-tag", action="store_true", help="只创建本地 git tag，不推送到远程")
+
+    install = sub.add_parser(
+        "install",
+        help="安装目标项目",
+        description="安装目标项目：默认 editable 安装源码；--version 安装指定 build 产物。",
+        formatter_class=HelpFormatter,
+    )
+    install.add_argument("--project", default=".", help="项目根目录；默认当前目录")
+    install.add_argument("--version", default=None, help="安装指定版本 build 产物；默认 editable 安装")
+
+    upgrade = sub.add_parser(
+        "upgrade",
+        help="升级 shipcli 自身",
+        description=(
+            "升级 shipcli 自身：\n"
+            "  默认从 PyPI 拉最新发布版（--version 指定版本）\n"
+            "  --local <path> 从本地项目 build 产物升级（--version 指定版本，缺省取最新）\n\n"
+            "此命令只管 shipcli 自己。项目 CLI（如 demo-cli）用其自带命令：demo-cli upgrade。"
+        ),
+        formatter_class=HelpFormatter,
+    )
+    upgrade.add_argument("--version", default=None, help="升级到指定版本；PyPI 为发布版，--local 为 build 产物版本")
+    upgrade.add_argument("--local", default=None, help="从本地项目路径的 build 产物升级")
+
+    uninstall = sub.add_parser(
+        "uninstall",
+        help="卸载 shipcli 自身",
+        description=(
+            "卸载 shipcli 自身：pip 卸载发布版包，并清理本地安装目录与符号链接。\n\n"
+            "此命令只管 shipcli 自己。项目 CLI（如 demo-cli）用其自带命令：demo-cli uninstall。"
+        ),
+        formatter_class=HelpFormatter,
+    )
+    return parser
+
+
+def main(argv: Optional[list[str]] = None, console: Optional[Console] = None) -> int:
+    """解析命令并分发到子命令。"""
+    console = console or TerminalConsole()
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    if args.version and not args.command:
+        console.print(f"shipcli {display_version_with_mode()}")
+        return 0
+    if args.command == "init":
+        return run_init(args, console)
+    if args.command == "build":
+        return run_build_command(args, console)
+    if args.command == "publish":
+        return run_publish(args, console)
+    if args.command == "install":
+        return run_install(args, console)
+    if args.command == "upgrade":
+        return run_upgrade(args, console)
+    if args.command == "uninstall":
+        return run_uninstall(args, console)
+    parser.print_help()
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

shipcli/commands/__init__.py

@@ -0,0 +1,17 @@
+"""shipcli 子命令导出。"""
+
+from shipcli.commands.build import run_build_command
+from shipcli.commands.init import run_init
+from shipcli.commands.install import run_install
+from shipcli.commands.publish import run_publish
+from shipcli.commands.uninstall import run_uninstall
+from shipcli.commands.upgrade import run_upgrade
+
+__all__ = [
+    "run_init",
+    "run_build_command",
+    "run_install",
+    "run_publish",
+    "run_upgrade",
+    "run_uninstall",
+]

shipcli/commands/build.py

@@ -0,0 +1,30 @@
+"""shipcli build 子命令。"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from shipcli.builder import run_build
+from shipcli.console import Console
+
+
+def run_build_command(args: Any, console: Console) -> int:
+    """执行当前项目或指定项目的构建，产出 wheel/sdist。"""
+    project_root = Path(args.project).resolve()
+    try:
+        plan = run_build(
+            project_root,
+            release=args.release,
+            increase=args.increase,
+        )
+    except Exception as exc:  # noqa: BLE001 - CLI 统一兜底输出错误信息
+        console.print(f"错误: {exc}")
+        return 1
+    kind = "release" if plan.release else "dev"
+    console.print(f"构建完成（{kind}）：{plan.product_version}")
+    console.print(f"分发目录：{plan.dist_dir}")
+    # 打印现成的安装/升级命令，方便复制。
+    console.print(f"  pip install {plan.dist_dir}/*.whl")
+    console.print(f"  shipcli upgrade --local {project_root} --version {plan.product_version}")
+    return 0

shipcli/commands/init.py

@@ -0,0 +1,30 @@
+"""shipcli init 子命令。"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from shipcli.console import Console
+from shipcli.scaffold import create_project, default_package_name
+
+
+def run_init(args: Any, console: Console) -> int:
+    """初始化一个新的 CLI 项目目录。"""
+    target_dir = Path(args.path).resolve()
+    app_name = args.app_name or target_dir.name
+    package_name = args.package or default_package_name(app_name)
+    try:
+        create_project(
+            target_dir,
+            app_name=app_name,
+            package_name=package_name,
+            force=args.force,
+        )
+    except FileExistsError as exc:
+        console.print(f"错误: {exc}")
+        return 1
+    console.print(f"已初始化项目：{target_dir}")
+    console.print(f"应用名：{app_name}")
+    console.print(f"包名：{package_name}")
+    return 0

shipcli/commands/install.py

@@ -0,0 +1,22 @@
+"""shipcli install 子命令。"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from shipcli.console import Console
+from shipcli.installer import install_project
+
+
+def run_install(args: Any, console: Console) -> int:
+    """安装源码入口或指定版本产物。"""
+    project_root = Path(args.project).resolve()
+    try:
+        plan = install_project(project_root, version=args.version)
+    except Exception as exc:  # noqa: BLE001 - CLI 统一兜底输出错误信息
+        console.print(f"错误: {exc}")
+        return 1
+    console.print(f"已安装：{plan.exec_path}")
+    console.print(f"符号链接：{plan.link_path}")
+    return 0

shipcli/commands/publish.py

@@ -0,0 +1,83 @@
+"""shipcli publish 子命令。"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from shipcli.console import Console
+from shipcli.publisher import (
+    create_git_tag,
+    git_working_tree_clean,
+    is_git_repo,
+    publish_to_github_release,
+    publish_to_pypi,
+    resolve_release_version,
+)
+
+
+def run_publish(args: Any, console: Console) -> int:
+    """发布当前项目或指定项目的既有 release 产物，并按需打 git tag。"""
+    if not args.github and not args.pypi:
+        console.print("错误: 请至少指定一个发布目标：`--github` 或 `--pypi`")
+        return 1
+
+    project_root = Path(args.project).resolve()
+    try:
+        version = resolve_release_version(project_root, args.version)
+        console.print(f"准备发布版本：{version}")
+
+        # 打 tag 前先检查工作区：release 构建应在 build 阶段已自动提交版本号，
+        # 此处若有改动说明源码尚未提交，打 tag 会落在不完整的 commit 上，必须拦下。
+        if not args.no_tag and is_git_repo(project_root) and not git_working_tree_clean(project_root):
+            raise RuntimeError(
+                "工作区有未提交改动，打 tag 会落在不完整的 commit 上；"
+                "请先 commit 改动（或重新 `shipcli build --release` 自动提交版本号）再发布，"
+                "或加 --no-tag 跳过打 tag。"
+            )
+
+        if args.github:
+            github_result = publish_to_github_release(
+                project_root=project_root,
+                version=version,
+                repo=args.github_repo,
+                tag=args.tag,
+                title=args.title,
+                notes=_load_release_notes(args.notes_file),
+                draft=args.draft,
+                prerelease=args.prerelease,
+            )
+            console.print(f"GitHub Release 已发布：{github_result.release_url}")
+            for asset_path in github_result.asset_paths:
+                console.print(f"GitHub 资产：{asset_path}")
+        if args.pypi:
+            pypi_result = publish_to_pypi(
+                project_root=project_root,
+                version=version,
+                repository_url=args.repository_url,
+                dist_dir=Path(args.dist_dir).resolve() if args.dist_dir else None,
+                skip_existing=args.skip_existing,
+            )
+            console.print("PyPI 分发文件已上传：")
+            for distribution_path in pypi_result.distribution_paths:
+                console.print(f"  {distribution_path}")
+
+        # 发布都成功后，若项目是 git 仓库则打 v<version> tag（已存在则跳过）。
+        if not args.no_tag and is_git_repo(project_root):
+            tag = args.tag or f"v{version}"
+            created = create_git_tag(project_root, tag, push=not args.no_push_tag)
+            if created:
+                console.print(f"已创建 git tag：{tag}")
+            else:
+                console.print(f"git tag 已存在，跳过：{tag}")
+    except Exception as exc:  # noqa: BLE001 - CLI 统一兜底输出错误信息
+        console.print(f"错误: {exc}")
+        return 1
+    return 0
+
+
+def _load_release_notes(notes_file: str | None) -> str | None:
+    """读取 GitHub Release 说明文件。"""
+    if not notes_file:
+        return None
+    return Path(notes_file).read_text(encoding="utf-8")

shipcli/commands/uninstall.py

@@ -0,0 +1,47 @@
+"""shipcli uninstall 子命令。"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+from typing import Any
+
+from shipcli.console import Console
+
+
+PACKAGE_NAME = "shipcli"
+
+
+def run_uninstall(args: Any, console: Console) -> int:
+    """卸载 shipcli 自身：pip 卸载包，并清理本地安装目录与符号链接。"""
+    try:
+        # pip 卸载发布版包（-y 跳过确认）。
+        subprocess.run(
+            [sys.executable, "-m", "pip", "uninstall", "-y", PACKAGE_NAME, "--disable-pip-version-check"],
+            check=False,
+        )
+        # 清理 ~/.shipcli-cli/ 与符号链接（与发布无关的本地安装痕迹）。
+        install_dir = Path.home() / f".{PACKAGE_NAME}-cli"
+        link_dirs = [
+            Path("/usr/local/bin"),
+            Path.home() / ".local" / "bin",
+        ]
+        removed_links = []
+        for link_dir in link_dirs:
+            link_path = link_dir / PACKAGE_NAME
+            if link_path.exists() or link_path.is_symlink():
+                link_path.unlink(missing_ok=True)
+                removed_links.append(link_path)
+        if install_dir.exists():
+            shutil.rmtree(install_dir)
+    except Exception as exc:  # noqa: BLE001 - CLI 统一兜底输出错误信息
+        console.print(f"错误: {exc}")
+        return 1
+    console.print(f"已卸载 pip 包：{PACKAGE_NAME}")
+    console.print(f"已清理安装目录：{Path.home() / f'.{PACKAGE_NAME}-cli'}")
+    for link in removed_links:
+        console.print(f"已移除链接：{link}")
+    console.print("此命令只管 shipcli 自己；项目 CLI（如 demo-cli）用其自带命令卸载。")
+    return 0