diff --git a/AGENTS.md b/AGENTS.md index 686a194..b164f8d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -119,7 +119,15 @@ templates under category subdirectories are included by Agent Skills hosts) plus Claude's independent `~/.claude/skills` or `$CLAUDE_CONFIG_DIR/skills`. `--target cursor` and `--target codex` keep the host-native extras; `--dir` covers anything else. List reports - `installed`, `outdated`, or `missing`. Skill management is CLI-only. + `installed`, `outdated`, or `missing`. Unfiltered `pt-snap skill uninstall` + (no `--target`, `--project`, or `--dir`) removes every installed or outdated + copy that list would report and that contains `SKILL.md`, across all + built-in hosts and both scopes. A same-named path without `SKILL.md` + aborts the whole unfiltered uninstall before any deletion. + `uninstall_skills(all_locations=True)` rejects dest_dir, hosts, and + scope other than `user`. `--target` / `--project` / `--dir` keep the + narrower mutation destinations. + Skill management is CLI-only. ### Snapshot import and split diff --git a/CHANGELOG.md b/CHANGELOG.md index 71f45a6..21e8cca 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -19,6 +19,7 @@ ### 修复 +- `pt-snap skill uninstall` 在不带 `--target` / `--project` / `--dir` 时,会删除 `skill list` 报告的、且含有 `SKILL.md` 的每一份已安装或过期副本(全部内置宿主、用户级与项目级)。此前只检查默认的用户级 `agents` 与 `claude` 目录,因此 `cursor:user` 或 `--project` 副本会留下并继续显示为 `installed`。`--target` / `--project` / `--dir` 仍只作用于指定目标。同名但缺少 `SKILL.md` 的路径不会删除,并且会让整次卸载在动手前失败。部分名称未安装时,会在默认用户级 `agents` 与 `claude` 上报告 `not_installed`。 - `query --template-info` 在模板不存在时走与其他 CLI 失败相同的 `_error()` 路径,退出码为 1(此前 `typer.Exit()` 默认 0)。 - 未声明的 `--params` 键不再静默进入渲染上下文(例如 `min_sze` 不再当成未过滤结果);查询在渲染 SQL 前失败,并列出已接受参数名。 - `allocation` / `block` / `event` / `active_blocks_at_event` 的 `order_by`、`order_dir` 不再接受任意 SQL 片段;非法取值在进数据库前被拒绝,而不再以 SQLite syntax error 暴露。 @@ -38,6 +39,7 @@ - 依赖 `pt-snap-cli[rag]` 的安装命令会失败;该 extra 从未启用任何功能。 - 拼错或多余的查询参数、以及不在 `choices` 内的 `order_by` / `order_dir` 现在会报错,而不再静默得到错误结果或 SQLite 语法错误。 - 用户自写查询模板若在 `output_schema` 列上使用未登记键,加载会失败;仅含 `column`/`type` 的旧模板仍然有效。`execute_query()` 返回字典新增 `template`、`semantics_version` 键。 +- 不带 `--target` / `--project` / `--dir` 的 `pt-snap skill uninstall` 现在会删除 `skill list` 看到的、含有 `SKILL.md` 的全部已安装副本,而不再只检查默认的用户级 `agents` 与 `claude` 目录。需要窄范围卸载时请显式传这些选项。同名但缺少 `SKILL.md` 的路径会让整次卸载失败且零删除。 - 本版本未扩展 `--json` 覆盖面。当前支持 `--json` 的是 `metadata`、`report peak-memory`,以及 `skill list` / `install` / `upgrade` / `uninstall`。`query`、`focus`、`import`、`split`、`config` 仍无 `--json`;`--template-info` 的机器可读形态仍是结构化 API dict 与 CLI 文本。 ## [0.3.0] - 2026-09-17 diff --git a/docs/en/skills.md b/docs/en/skills.md index 20b047e..da7f933 100644 --- a/docs/en/skills.md +++ b/docs/en/skills.md @@ -15,7 +15,7 @@ pt-snap skill list --target claude --user Each bundled skill is shown as its own block: name, status, install locations, and a short description. Status is one of: - `installed` — a matching copy is present in at least one inspected location -- `outdated` — a copy exists but differs from the bundled skill +- `outdated` — a copy exists but differs from the bundled skill, or the path exists without `SKILL.md` - `missing` — no copy was found `--target` accepts a comma-separated list of `agents`, `claude`, `cursor`, and `codex`. `--user` and `--project` limit the scan to user-level or project-local directories. Without those flags, `list` inspects both scopes. @@ -67,11 +67,16 @@ pt-snap skill upgrade pt-snap-setup --target claude ```bash pt-snap skill uninstall +pt-snap skill uninstall pt-snap-setup pt-snap skill uninstall pt-snap-setup --target claude pt-snap skill uninstall --project --target cursor ``` -`uninstall` removes bundled skill directories that contain `SKILL.md`. Skills that are not installed are reported as `not_installed`. A same-named path that exists without `SKILL.md` is left untouched. +Without `--target`, `--project`, or `--dir`, `uninstall` removes every bundled-skill copy that contains `SKILL.md` and that `list` would report as installed or outdated, across all built-in hosts and both user and project scopes. Each requested name with no removable copy is reported as `not_installed` at the default user-level `agents` and `claude` destinations. Omitting names requests every bundled skill. + +`--target`, `--project`, and `--dir` keep narrower destinations: `--project` uses the default `agents` and `claude` project directories unless `--target` selects hosts, and `--dir` only touches that folder. + +`uninstall` only deletes directories that contain `SKILL.md`. `list` also marks a same-named path without `SKILL.md` as `outdated`. Uninstall leaves that path untouched and, if any such path is among the destinations, refuses the whole operation before deleting anything. Remove or replace the stray path, then re-run uninstall. After an install, upgrade, or uninstall that changes skill files, restart the agent so it picks up the change. diff --git a/docs/zh/skills.md b/docs/zh/skills.md index 1174c2b..3b57a25 100644 --- a/docs/zh/skills.md +++ b/docs/zh/skills.md @@ -15,7 +15,7 @@ pt-snap skill list --target claude --user 每个随包 skill 单独一块显示:名称、状态、安装位置,以及一句简短说明。状态为以下之一: - `installed` — 至少一个检查位置存在内容匹配的副本 -- `outdated` — 已有副本,但与随包版本不同 +- `outdated` — 已有副本但与随包版本不同,或路径存在但没有 `SKILL.md` - `missing` — 未找到副本 `--target` 接受逗号分隔的 `agents`、`claude`、`cursor`、`codex`。`--user` 和 `--project` 分别只检查用户级或当前项目目录。不传这些选项时,`list` 会同时检查两个范围。 @@ -67,11 +67,16 @@ pt-snap skill upgrade pt-snap-setup --target claude ```bash pt-snap skill uninstall +pt-snap skill uninstall pt-snap-setup pt-snap skill uninstall pt-snap-setup --target claude pt-snap skill uninstall --project --target cursor ``` -`uninstall` 会删除已经包含 `SKILL.md` 的随包 skill 目录。未安装的 skill 会报告为 `not_installed`。同名路径存在但没有 `SKILL.md` 时不会删除。 +不带 `--target`、`--project` 或 `--dir` 时,`uninstall` 会删除 `list` 会报告为已安装或过期、且含有 `SKILL.md` 的每一份随包 skill 副本,覆盖全部内置宿主以及用户级和项目级目录。每个没有可删除副本的请求名称,会在默认的用户级 `agents` 和 `claude` 目录上报告 `not_installed`。省略名称表示请求全部随包 skill。 + +`--target`、`--project` 和 `--dir` 仍只作用于更窄的目标:`--project` 默认使用 `agents` 和 `claude` 项目目录,可用 `--target` 改宿主;`--dir` 只处理该文件夹。 + +`uninstall` 只删除已经包含 `SKILL.md` 的目录。`list` 也会把同名但没有 `SKILL.md` 的路径标为 `outdated`。卸载不会删除这类路径;只要目标中出现任何一处,就会在删除任何副本之前整次拒绝。先自行移除或替换该杂散路径,再重新卸载。 仅在 install、upgrade 或 uninstall 实际改动 skill 之后,才需要重启 agent 让变更生效。`list` 不会提示重启。 diff --git a/skills/AGENTS.md b/skills/AGENTS.md index c1e73ef..7d2a7e7 100644 --- a/skills/AGENTS.md +++ b/skills/AGENTS.md @@ -45,8 +45,12 @@ Repository `skills/*/SKILL.md` is the authoring source. Wheel installs read same `SKILL.md` into that packaged tree. `pt-snap skill list`, `install`, `upgrade`, and `uninstall` manage copies in the shared `.agents/skills` tree, Claude's independent directories, optional Cursor/Codex extras, or -an explicit `--dir`. After install or upgrade, the host agent must be -restarted. +an explicit `--dir`. Unfiltered `uninstall` (no `--target`, `--project`, +or `--dir`) removes every installed copy that `list` would report and +that contains `SKILL.md`. A same-named path without `SKILL.md` aborts +the whole unfiltered uninstall before any deletion. +`--target` / `--project` / `--dir` keep narrower destinations. After +install or upgrade, the host agent must be restarted. ## Focused Tests - Run `pytest tests/skills/test_helper_contract.py` after helper-skill changes. diff --git a/src/pt_snap_cli/cli.py b/src/pt_snap_cli/cli.py index a6d8671..a51d8b5 100644 --- a/src/pt_snap_cli/cli.py +++ b/src/pt_snap_cli/cli.py @@ -889,7 +889,10 @@ def skill_uninstall( typer.Option( "--target", "-t", - help="Comma-separated hosts: agents,claude,cursor,codex (default: agents,claude)", + help=( + "Comma-separated hosts: agents,claude,cursor,codex. " + "Defaults to agents,claude when --project is set" + ), autocompletion=complete_skill_targets, ), ] = None, @@ -905,15 +908,22 @@ def skill_uninstall( ] = None, json_output: Annotated[bool, typer.Option("--json", help="Emit machine-readable JSON")] = False, ) -> None: - """Remove bundled agent skills from shared agent, Claude, Cursor, Codex, or custom directories.""" + """Remove bundled agent skills. + + Without --target, --project, or --dir, remove every SKILL.md copy that + `pt-snap skill list` would report. A same-named path without SKILL.md + aborts the whole uninstall. Use those flags to limit destinations. + """ custom_dir = _skill_dest_dir(dest_dir, target, project=project) service = _skill_service() try: + unfiltered = custom_dir is None and target is None and not project report = service.uninstall_skills( names, hosts=None if custom_dir is not None else parse_host_option(target), scope="project" if project else "user", dest_dir=custom_dir, + all_locations=unfiltered, ) except ( SkillCatalogError, diff --git a/src/pt_snap_cli/core/skill_service.py b/src/pt_snap_cli/core/skill_service.py index b495620..069348a 100644 --- a/src/pt_snap_cli/core/skill_service.py +++ b/src/pt_snap_cli/core/skill_service.py @@ -155,8 +155,20 @@ def uninstall_skills( hosts: Iterable[str] | None = None, scope: str = "user", dest_dir: Path | str | None = None, + all_locations: bool = False, ) -> SkillInstallReport: - jobs = self._mutation_jobs(names, hosts, scope, dest_dir) + if all_locations: + if dest_dir is not None or hosts is not None or self._resolve_scope(scope) != "user": + raise InvalidSkillTargetError( + "Removing every installed copy cannot be combined with " + "--target, --project, or --dir." + ) + jobs = self._discovered_uninstall_jobs(names) + missing = self._undiscovered_uninstall_names(names, jobs) + if missing: + jobs.extend(self._mutation_jobs(missing, None, "user", None)) + else: + jobs = self._mutation_jobs(names, hosts, scope, dest_dir) for spec, _host, _selected_scope, dest in jobs: if _non_skill_destination(dest): raise SkillInstallError(_non_skill_delete_message(spec.name, dest)) @@ -251,6 +263,34 @@ def _mutation_targets( for host in selected_hosts ] + def _discovered_uninstall_jobs( + self, names: Iterable[str] | None + ) -> list[tuple[SkillSpec, SkillHost, SkillScope, Path]]: + catalog = {spec.name: spec for spec in self.list_catalog()} + requested = self._resolve_names(names, catalog) + jobs: list[tuple[SkillSpec, SkillHost, SkillScope, Path]] = [] + seen: set[Path] = set() + for name in requested: + spec = catalog[name] + for selected_scope in SKILL_SCOPES: + for host in SKILL_HOSTS: + dest = self._host_root(host, selected_scope) / name + if dest in seen or not (dest.exists() or dest.is_symlink()): + continue + seen.add(dest) + jobs.append((spec, host, selected_scope, dest)) + return jobs + + def _undiscovered_uninstall_names( + self, + names: Iterable[str] | None, + jobs: list[tuple[SkillSpec, SkillHost, SkillScope, Path]], + ) -> list[str]: + catalog = {spec.name: spec for spec in self.list_catalog()} + requested = self._resolve_names(names, catalog) + discovered = {spec.name for spec, _host, _selected_scope, _dest in jobs} + return [name for name in requested if name not in discovered] + def _location_status( self, spec: SkillSpec, host: SkillHost, scope: SkillScope ) -> SkillLocationStatus: diff --git a/tests/core/test_skill_service.py b/tests/core/test_skill_service.py index 977ea69..445c987 100644 --- a/tests/core/test_skill_service.py +++ b/tests/core/test_skill_service.py @@ -142,6 +142,103 @@ def test_uninstall_removes_installed_skill(service: SkillService) -> None: assert again.results[0].action == "not_installed" +def test_all_locations_uninstall_removes_every_listed_copy( + service: SkillService, +) -> None: + service.install_skills(["pt-snap-demo"], hosts=("cursor",), scope="user") + service.install_skills(["pt-snap-demo"], hosts=("agents", "claude"), scope="project") + cursor = service.skill_destination("cursor", "user", "pt-snap-demo") + agents_project = service.skill_destination("agents", "project", "pt-snap-demo") + claude_project = service.skill_destination("claude", "project", "pt-snap-demo") + + report = service.uninstall_skills(["pt-snap-demo"], all_locations=True) + actions = {(item.host, item.scope, item.action) for item in report.results} + assert actions == { + ("cursor", "user", "uninstalled"), + ("agents", "project", "uninstalled"), + ("claude", "project", "uninstalled"), + } + assert not cursor.exists() + assert not agents_project.exists() + assert not claude_project.exists() + + +def test_all_locations_uninstall_reports_default_not_installed( + service: SkillService, +) -> None: + report = service.uninstall_skills(["pt-snap-demo"], all_locations=True) + actions = {(item.host, item.scope, item.action) for item in report.results} + assert actions == { + ("agents", "user", "not_installed"), + ("claude", "user", "not_installed"), + } + + +def test_all_locations_uninstall_reports_missing_names_among_discovered( + service: SkillService, +) -> None: + service.install_skills(["pt-snap-demo"], hosts=("cursor",), scope="user") + + report = service.uninstall_skills(["pt-snap-demo", "pt-snap-other"], all_locations=True) + actions = {(item.name, item.host, item.scope, item.action) for item in report.results} + assert actions == { + ("pt-snap-demo", "cursor", "user", "uninstalled"), + ("pt-snap-other", "agents", "user", "not_installed"), + ("pt-snap-other", "claude", "user", "not_installed"), + } + assert not service.skill_destination("cursor", "user", "pt-snap-demo").exists() + + +def test_default_python_uninstall_stays_on_install_destinations( + service: SkillService, +) -> None: + service.install_skills(["pt-snap-demo"], hosts=("cursor",), scope="user") + service.install_skills(["pt-snap-demo"], hosts=("agents",), scope="project") + + report = service.uninstall_skills(["pt-snap-demo"]) + actions = {(item.host, item.scope, item.action) for item in report.results} + assert actions == { + ("agents", "user", "not_installed"), + ("claude", "user", "not_installed"), + } + assert ( + service.skill_destination("cursor", "user", "pt-snap-demo").joinpath("SKILL.md").is_file() + ) + assert ( + service.skill_destination("agents", "project", "pt-snap-demo") + .joinpath("SKILL.md") + .is_file() + ) + + +def test_all_locations_uninstall_rejects_target_project_or_dir( + service: SkillService, tmp_path: Path +) -> None: + with pytest.raises(InvalidSkillTargetError, match="--target, --project, or --dir"): + service.uninstall_skills(["pt-snap-demo"], hosts=("claude",), all_locations=True) + with pytest.raises(InvalidSkillTargetError, match="--target, --project, or --dir"): + service.uninstall_skills(["pt-snap-demo"], dest_dir=tmp_path / "skills", all_locations=True) + with pytest.raises(InvalidSkillTargetError, match="--target, --project, or --dir"): + service.uninstall_skills(["pt-snap-demo"], scope="project", all_locations=True) + + +def test_all_locations_uninstall_refuses_before_mutating_conflict( + service: SkillService, +) -> None: + service.install_skills(["pt-snap-demo"], hosts=("cursor",), scope="user") + dest = service.skill_destination("claude", "project", "pt-snap-demo") + dest.mkdir(parents=True) + notes = dest / "notes.txt" + notes.write_text("keep me\n", encoding="utf-8") + + with pytest.raises(SkillInstallError, match="Refusing to delete"): + service.uninstall_skills(["pt-snap-demo"], all_locations=True) + assert ( + service.skill_destination("cursor", "user", "pt-snap-demo").joinpath("SKILL.md").is_file() + ) + assert notes.is_file() + + def test_human_skill_summary_keeps_first_sentence() -> None: text = ( "Collect a snapshot by dumping a `.pkl` file. Not for diagnosing an " diff --git a/tests/test_cli.py b/tests/test_cli.py index 0ae693f..1b0aae8 100644 --- a/tests/test_cli.py +++ b/tests/test_cli.py @@ -1519,6 +1519,100 @@ def test_skill_upgrade_and_uninstall(self, tmp_path: Path) -> None: assert missing_payload["restart_required"] is False assert missing_payload["restart_hint"] is None + def test_skill_uninstall_without_flags_removes_all_listed_copies(self, tmp_path: Path) -> None: + home = tmp_path / "home" + home.mkdir() + with patch.object(Path, "home", return_value=home): + cursor_install = runner.invoke( + app, ["skill", "install", "pt-snap-setup", "--target", "cursor"] + ) + project_install = runner.invoke(app, ["skill", "install", "pt-snap-setup", "--project"]) + assert cursor_install.exit_code == 0 + assert project_install.exit_code == 0 + cursor = home / ".cursor" / "skills" / "pt-snap-setup" + project_agents = tmp_path / ".agents" / "skills" / "pt-snap-setup" + project_claude = tmp_path / ".claude" / "skills" / "pt-snap-setup" + assert cursor.joinpath("SKILL.md").is_file() + assert project_agents.joinpath("SKILL.md").is_file() + assert project_claude.joinpath("SKILL.md").is_file() + assert cursor != project_agents + + removed = runner.invoke(app, ["skill", "uninstall", "pt-snap-setup", "--json"]) + assert removed.exit_code == 0 + payload = json.loads(removed.stdout) + actions = {(item["host"], item["scope"], item["action"]) for item in payload["results"]} + assert actions == { + ("cursor", "user", "uninstalled"), + ("agents", "project", "uninstalled"), + ("claude", "project", "uninstalled"), + } + assert not cursor.exists() + assert not project_agents.exists() + assert not project_claude.exists() + + listed = runner.invoke(app, ["skill", "list", "--json"]) + setup = next( + item + for item in json.loads(listed.stdout)["skills"] + if item["name"] == "pt-snap-setup" + ) + assert setup["status"] == "missing" + + def test_skill_uninstall_project_stays_narrow(self, tmp_path: Path) -> None: + home = tmp_path / "home" + home.mkdir() + with patch.object(Path, "home", return_value=home): + user_install = runner.invoke( + app, ["skill", "install", "pt-snap-setup", "--target", "cursor"] + ) + project_install = runner.invoke(app, ["skill", "install", "pt-snap-setup", "--project"]) + assert user_install.exit_code == 0 + assert project_install.exit_code == 0 + cursor = home / ".cursor" / "skills" / "pt-snap-setup" + project_agents = tmp_path / ".agents" / "skills" / "pt-snap-setup" + project_claude = tmp_path / ".claude" / "skills" / "pt-snap-setup" + + removed = runner.invoke( + app, ["skill", "uninstall", "pt-snap-setup", "--project", "--json"] + ) + assert removed.exit_code == 0 + payload = json.loads(removed.stdout) + actions = {(item["host"], item["scope"], item["action"]) for item in payload["results"]} + assert actions == { + ("agents", "project", "uninstalled"), + ("claude", "project", "uninstalled"), + } + assert not project_agents.exists() + assert not project_claude.exists() + assert cursor.joinpath("SKILL.md").is_file() + + def test_skill_uninstall_dir_stays_narrow(self, tmp_path: Path) -> None: + dest = tmp_path / "other-agent" / "skills" + custom_install = runner.invoke( + app, ["skill", "install", "pt-snap-setup", "--dir", str(dest)] + ) + cursor_install = runner.invoke( + app, ["skill", "install", "pt-snap-setup", "--target", "cursor"] + ) + assert custom_install.exit_code == 0 + assert cursor_install.exit_code == 0 + custom = dest / "pt-snap-setup" + cursor = tmp_path / ".cursor" / "skills" / "pt-snap-setup" + assert custom.joinpath("SKILL.md").is_file() + assert cursor.joinpath("SKILL.md").is_file() + + removed = runner.invoke( + app, + ["skill", "uninstall", "pt-snap-setup", "--dir", str(dest), "--json"], + ) + assert removed.exit_code == 0 + payload = json.loads(removed.stdout) + assert len(payload["results"]) == 1 + assert payload["results"][0]["host"] == "custom" + assert payload["results"][0]["action"] == "uninstalled" + assert not custom.exists() + assert cursor.joinpath("SKILL.md").is_file() + def test_skill_dir_install_and_list(self, tmp_path: Path) -> None: dest = tmp_path / "other-agent" / "skills" installed = runner.invoke(