### 功能描述 新增 `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. **与 #138 衔接**:#138 完成前,help 提示写「在支持的子命令上优先使用 `--json`」,示例必须符合当前能力;全命令 JSON 指引在 #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 示例与当前命令能力一致(按 #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
codeasier commentedon Sep 17, 2026
支持新增
pt-snap-helper作为统一导航入口。现有技能覆盖 setup、Ascend NPU 采集、泄漏、碎片和峰值拆解,但仍缺少根据用户目标和输入类型选择下一步的统一指引。建议补充以下实现与验收要求:
同步打包,确保 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会校验两份目录及文件内容一致;仅新增仓库技能不能完成分发。明确与 [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 完成后验收。提供技能未安装时的可执行指引。
安装 Python 包不等于宿主 Agent 已加载技能。helper 应复用
pt-snap skill list --json检查可用性,并说明缺失时的安装方式与安装后重启 Agent 的要求。helper 本身保持只读导航,使用现有五个技能的准确名称;只有 pickle 时说明独立的可信输入导入步骤,不自动安装、导入或修改 focus。help 提示使用明确的 help/epilog 配置,并验证渲染结果。
src/pt_snap_cli/cli.py:65已显式设置应用级help,只改main的 docstring 可能不会显示。本地 CliRunner 探针已确认该现象。建议在根帮助末尾放简短提示,不在回调中直接打印,以免污染普通命令或 JSON 输出。提示例如:补齐验收覆盖。
除
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 的交付范围衔接。
codeasier commentedon Sep 17, 2026
正文已按评审意见更新:补入 bundled_skills 双目录同步与 test_bundled_skills 校验、与 #138 的分阶段衔接(先「在支持的子命令上优先 --json」)、技能未安装时用 pt-snap skill list --json 的可执行指引、应用级 help 已显式设置因此提示须走 epilog 的实现约束。
feat: add pt-snap-helper skill and agent help epilog