Skip to content

[FEATURE] 新增 pt-snap-helper 引导技能,并在 --help 输出中加入 Agent 提示 #139

Closed

Description

@codeasier

功能描述

新增 skills/pt-snap-helper 技能作为统一入口:按用户目标与输入类型(已有 SnapshotDB / 只有 pickle / 未安装 / NPU 采集)路由到现有五个技能(setup / ascend-npu-collect / leak / fragmentation / peak-breakdown),并引导 Agent 优先使用 --json 输出。同时在 pt-snap --help 输出中加入 Agent 提示。

main 分支已有 pt-snap skill list/install/upgrade/uninstall 命令与 src/pt_snap_cli/bundled_skills/ 分发机制,helper 必须同步进入该分发链路,PyPI 用户才能获取。

使用场景

Agent 首次接触 pt-snap 时不知道有哪些技能、该用哪个命令;help 主动引导 + helper 提供路由决策入口,减少试错。

期望的实现方式(已并入评审意见)

  1. 同步打包:skills/pt-snap-helper/SKILL.md 与 src/pt_snap_cli/bundled_skills/pt-snap-helper/SKILL.md 保持一致,tests/test_bundled_skills.py 校验两份目录及内容一致;仅新增仓库技能不能完成分发。
  2. 与 [FEATURE] 为 pt-snap 所有命令增加 --json 选项,实现 Agent 友好输出 #138 衔接:[FEATURE] 为 pt-snap 所有命令增加 --json 选项,实现 Agent 友好输出 #138 完成前,help 提示写「在支持的子命令上优先使用 --json」,示例必须符合当前能力;全命令 JSON 指引在 [FEATURE] 为 pt-snap 所有命令增加 --json 选项,实现 Agent 友好输出 #138 完成后再验收。
  3. 技能未安装时的可执行指引:helper 复用 pt-snap skill list --json 检查可用性,说明缺失时的安装方式与安装后重启 Agent 的要求;helper 保持只读导航,使用现有五个技能的准确名称;用户只有 pickle 时说明独立的可信输入导入步骤,不自动安装、导入或修改 focus。
  4. help 提示配置:应用级 help 已显式设置(cli.py 的 typer.Typer(help=...)),只改 main docstring 不会显示(已用 CliRunner 探针确认);提示放根帮助末尾(epilog / rich panel),不在回调中直接打印,避免污染普通命令或 JSON 输出。提示示例:

    Agents: prefer --json where supported. Start with the pt-snap-helper skill; check availability with pt-snap skill list --json.

  5. 路由内容:以「用户目标 × 输入类型」矩阵组织,指向五个技能的准确名称与入口命令。

验收标准

  • skills/ 与 bundled_skills/ 两份 SKILL.md 一致,tests/test_bundled_skills.py 通过
  • pt-snap --help / -h 含 Agent 提示(epilog 渲染结果验证),JSON 输出无提示污染
  • helper 示例与当前命令能力一致(按 [FEATURE] 为 pt-snap 所有命令增加 --json 选项,实现 Agent 友好输出 #138 进度分阶段验收)
  • helper 说明技能未安装时的检查与安装方式(pt-snap skill list --json)
  • pytest tests/skills 通过;tests/test_cli.py 增加 help 提示断言
  • README.md、README_zh.md、docs/{en,zh}/skills.md 与技能索引同步更新

Activity

  1. codeasier commented on Sep 17, 2026

    @codeasier
    OwnerAuthor

    支持新增 pt-snap-helper 作为统一导航入口。现有技能覆盖 setup、Ascend NPU 采集、泄漏、碎片和峰值拆解,但仍缺少根据用户目标和输入类型选择下一步的统一指引。

    建议补充以下实现与验收要求:

    1. 同步打包,确保 PyPI 用户能发现和安装。
      最新 main 已有 pt-snap skill list/install/upgrade/uninstall。根据 skills/AGENTS.md,新增技能除了 skills/pt-snap-helper/SKILL.md,还需同步到 src/pt_snap_cli/bundled_skills/pt-snap-helper/SKILL.md。tests/test_bundled_skills.py 会校验两份目录及文件内容一致;仅新增仓库技能不能完成分发。

    2. 明确与 [FEATURE] 为 pt-snap 所有命令增加 --json 选项,实现 Agent 友好输出 #138 的依赖。
      当前 metadata、report peak-memory 和技能管理子命令支持 --json,但 query/focus/import/split/config 尚不支持,且根命令没有全局 --json。如果本 issue 先落地,提示应写为"在支持的子命令上优先使用 --json",示例必须符合当前能力;全命令 JSON 指引应在 [FEATURE] 为 pt-snap 所有命令增加 --json 选项,实现 Agent 友好输出 #138 完成后验收。

    3. 提供技能未安装时的可执行指引。
      安装 Python 包不等于宿主 Agent 已加载技能。helper 应复用 pt-snap skill list --json 检查可用性,并说明缺失时的安装方式与安装后重启 Agent 的要求。helper 本身保持只读导航,使用现有五个技能的准确名称;只有 pickle 时说明独立的可信输入导入步骤,不自动安装、导入或修改 focus。

    4. help 提示使用明确的 help/epilog 配置,并验证渲染结果。
      src/pt_snap_cli/cli.py:65 已显式设置应用级 help,只改 main 的 docstring 可能不会显示。本地 CliRunner 探针已确认该现象。建议在根帮助末尾放简短提示,不在回调中直接打印,以免污染普通命令或 JSON 输出。提示例如:

      Agents: prefer --json where supported. Start with the pt-snap-helper skill; check availability with pt-snap skill list --json.

    5. 补齐验收覆盖。
      除 pytest tests/skills 外,补充 tests/test_cli.py 的 --help/-h 提示断言及 JSON 输出无提示污染检查,运行 tests/test_bundled_skills.py 和相关技能管理测试。静态契约覆盖技能路由、准确命令与只读边界;文档同步更新 README.md、README_zh.md、docs/en/skills.md、docs/zh/skills.md 和技能索引。

    这样可以同时保证入口可发现、技能可获取、示例可执行,并与 #138 的交付范围衔接。

  2. codeasier commented on Sep 17, 2026

    @codeasier
    OwnerAuthor

    正文已按评审意见更新:补入 bundled_skills 双目录同步与 test_bundled_skills 校验、与 #138 的分阶段衔接(先「在支持的子命令上优先 --json」)、技能未安装时用 pt-snap skill list --json 的可执行指引、应用级 help 已显式设置因此提示须走 epilog 的实现约束。

  3. added a commit that references this issue on Sep 18, 2026
    1def036
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions