Repository navigation
Closed
6 / 66 of 6 issues completed
Copy link
Labels
enhancementNew feature or requestNew feature or request
Description
功能描述
把 pt-snap-cli 当作 Agent 的一等用户来设计。Agent 友好化不等于「给命令加 --json」,而是覆盖完整调用链:
发现能力 → 构造正确调用 → 判断结果完整性 → 正确解释数据 → 失败可恢复 → 产物可追溯
本 issue 是总纲与路线图,不限于当前三个子任务;具体交付以 sub-issue 跟踪,按优先级推进。
使用场景
Agent(加载或不加载技能)通过 CLI 完成 PyTorch 内存快照分析:从 help / helper 发现能力,用结构化输出准确调用与修正,能判断证据是否完整、字段语义是否被误读,并追溯每次分析实际使用的数据库与设备。
路线图
P0 — 调用契约(决定其余改造能否被 Agent 用起来)
- [FEATURE] 移除 MCP 支持,剥离 mcp 依赖 #137 移除 MCP 支持,Agent 集成入口收敛到 skills + CLI(减依赖、缩维护面)— feat: remove MCP support and drop the mcp dependency #146
- [FEATURE] 为 pt-snap 所有命令增加 --json 选项,实现 Agent 友好输出 #138 全命令
--json+ JSON 错误协议 + 结果信封(关联 [BUG] query --template-info 对缺失模板仍返回退出码 0 #112 退出码问题;--template-info --json在此落地)— feat(cli): add --json to remaining commands with a stable error contract #152 - [FEATURE] 新增 pt-snap-helper 引导技能,并在 --help 输出中加入 Agent 提示 #139
pt-snap-helper引导技能 +--helpAgent 提示(分发走pt-snap skill命令族)— feat: add pt-snap-helper skill and agent help epilog #144;阶段 2 措辞随 feat(cli): add --json to remaining commands with a stable error contract #152 - [FEATURE] 收紧查询模板参数校验:拒绝未声明参数,为 str 型 SQL 片段参数(order_by/order_dir)增加白名单 #120 收紧查询模板参数校验(已有独立 issue,此处仅关联跟踪:拒绝未声明参数、白名单校验)— feat(query): reject undeclared parameters and bound SQL-fragment parameters with choices #126
P1 — 结果完整性与语义
- [FEATURE] 查询结果完整性与分页协议:has_more/total 语义/超时保护 #140 查询结果完整性与分页协议:
has_more/total语义 / 超时保护 — feat(query): distinguish truncated pages without a default COUNT #153 - [FEATURE] 查询模板语义元数据:字段单位、统计口径与解释限制 #141 查询模板语义元数据:字段单位、统计口径与解释限制(把技能文档中的误读警示下沉为元数据)— feat(query): expose field units and interpretation limits on templates #147
- [FEATURE] 能力清单与数据库概览:减少 Agent 前置探测调用 #142 能力清单与数据库概览:减少前置探测调用,收编技能中的 SQLite 回退 — feat: add capabilities and overview commands to cut agent probe calls #154
P2 — 后续迭代(本 issue 只登记方向,不立子任务)
- 组合证据的结构化 report(多步证据采集产物,而非让程序自动宣布结论)
- [FEATURE] 收紧查询模板参数校验:拒绝未声明参数,为 str 型 SQL 片段参数(order_by/order_dir)增加白名单 #120 与 [FEATURE] 查询模板语义元数据:字段单位、统计口径与解释限制 #141 已共用 YAML → config → registry 路径;若还需再收紧为更严的单一契约 schema,另开迭代
横切验收:Agent 端到端评估
评估基线已由 #145 落入 tests/skills/suites/pt-snap-agent-e2e(含 pre-change 记录)。产品改完后用同一套件对比,不要用 #145 关闭本总纲。
在 tests/skills 既有评估框架上增加端到端场景(各子 issue 的验收也应支持以下行为):
| 场景 | 验证行为 |
|---|---|
| 无预装技能,仅 CLI | 能从 --help 找到 helper 并获取引导 |
| 模板名 / 参数拼错 | 依据结构化错误码修正调用 |
| 多数据库 / 多设备并存 | 明确使用用户指定目标,结果信封可追溯 |
| 查询返回截断结果 | 主动分页或注明证据不完整 |
| trace 末尾存在存活块 | 不直接断言「确认泄漏」 |
| 数据库缺失 / 无设备 | 不把失败当作空结果 |
| import 成功 | 从结构化结果获得产物路径与 focus 变更 |
评估指标:任务成功率、调用次数、输出大小、错误结论率(改造前后对比)。
验收标准
- P0 四项完成([FEATURE] 移除 MCP 支持,剥离 mcp 依赖 #137、[FEATURE] 为 pt-snap 所有命令增加 --json 选项,实现 Agent 友好输出 #138、[FEATURE] 新增 pt-snap-helper 引导技能,并在 --help 输出中加入 Agent 提示 #139、[FEATURE] 收紧查询模板参数校验:拒绝未声明参数,为 str 型 SQL 片段参数(order_by/order_dir)增加白名单 #120)
- P1 三项完成([FEATURE] 查询结果完整性与分页协议:has_more/total 语义/超时保护 #140、[FEATURE] 查询模板语义元数据:字段单位、统计口径与解释限制 #141、[FEATURE] 能力清单与数据库概览:减少 Agent 前置探测调用 #142)
- 上述端到端场景全部有评估覆盖且指标优于基线
-
pip install pt-snap-cli后,Agent 仅凭--json输出与pt-snap-helper技能可完成一次端到端快照分析
Metadata
Metadata
Assignees
Labels
enhancementNew feature or requestNew feature or request
Activity
feat(tests): add Agent CLI end-to-end evaluation baseline (#145)
codeasier commentedon Sep 18, 2026
#145 only landed the Agent CLI evaluation baseline. It must not close this parent issue: remaining product work is still on #137, #138, #140, #141, #142. P0 items already done elsewhere: #139 via #144, #120 via #126, plus tracked #112 via #143.
codeasier commentedon Sep 18, 2026
阶段性进度(2026-09-18,
origin/maind5b7b51)P0 已完成 3/4,P1 已完成 1/3。总纲保持 OPEN。
已合入
pt-snap-helper+--helpepilogchoices任务图(剩余)
合入时记下的约束
Fixes/Closes关本总纲(feat(tests): add Agent CLI end-to-end evaluation baseline #145 曾误关,已重开)。trace_entry.allocated是瞬时占用,峰值标instantaneous_occupancy,不是累计分配。--template-info --json仍归 [FEATURE] 为 pt-snap 所有命令增加 --json 选项,实现 Agent 友好输出 #138;feat(query): expose field units and interpretation limits on templates #147 只提供文本--template-info与 API dict。下一步:从最新
main开 #138。codeasier commentedon Sep 19, 2026
进度:P0 与 P1 的产品切片都已合入
main。--json792672f)a84598a,rebase 到 feat(query): distinguish truncated pages without a default COUNT #153 之后合入)本总纲仍保持 OPEN。剩下是 #145
pt-snap-agent-e2e对比pre-change,以及可选的 0.4.0 / 0.5.0 发布节奏。不要用切片 PR 自动关掉本 issue。feat(agent): complete #136 CLI acceptance (#157)
codeasier commentedon Sep 24, 2026
v0.4.0 已发布:PyPI
pt-snap-cli==0.4.0与 GitHub Release 均成功(workflow https://github.com/codeasier/pt-snap-cli/actions/runs/35952928649)。验收确认:
pip install pt-snap-cli==0.4.0,pt-snap --version输出 0.4.0,--help提供pt-snap skill install pt-snap-helper --json引导。关闭本总纲。