Skip to content

[FEATURE] 为 pt-snap 所有命令增加 --json 选项,实现 Agent 友好输出 #138

Closed

Description

@codeasier

功能描述

metadata 与 report peak-memory 已支持 --json,但 focus、import、split、query、config 仍只有人类可读文本。除格式缺口外,当前错误路径还有两个与 Agent 可靠性直接相关的缺陷(已复现):

使用场景

Agent 需要稳定解析成功与失败两种状态:不能依赖错误文本猜测原因,也不能把执行失败当作「没有发现问题」。

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

  1. JSON 模式错误契约:失败时 stdout 为空、诊断写 stderr、退出码非零;结构化错误包含稳定错误码(如 TEMPLATE_NOT_FOUND / INVALID_PARAMETER / DATABASE_NOT_FOUND / DEVICE_NOT_FOUND)与可操作的修正提示。文本模式是否同步修正错误流与退出码需明确兼容策略(关联 [BUG] query --template-info 对缺失模板仍返回退出码 0 #112),不能笼统承诺「所有行为不变」。
  2. 共享 JSON 序列化辅助:FocusState / ImportResult / SplitResult 含 Path,需统一处理路径字符串、嵌套模型、数组及 None → null,保留数值与布尔类型;沿用 QueryResult 的 total / returned / device_id / rows,保留现有 -n 语义;已有 metadata、report peak-memory 的 JSON 字段保持兼容。
  3. 结果信封(扩展项):JSON 输出携带执行上下文元数据(schema_version、db_path、focus_source、device_id、template、effective_params),使多轮分析可追溯、可复现。
  4. 逐命令分支覆盖:
    • focus:读取 / 设置 / 仅修改设备 / --global / --session;--session --json 返回验证结果及环境变量赋值信息,不混入 shell 文本,也不暗示已修改父 shell
    • config:读取 / --path / --clear,维持其仅管理 legacy global config 的语义
    • query:执行 / --list / 分类筛选 / --template-info
    • split:--json 控制 stdout 结果清单,--format json 控制分片文件格式,两者相互独立
  5. 测试:对完整 stdout 执行 json.loads(),覆盖正常结果、空结果、未配置 focus、导入缓存复用、分片清单与查询限行;错误路径分别断言 stdout、stderr 与退出码,并检查 ANSI / 日志污染;契约测试增加 JSON 语义对齐断言;保留文本输出回归测试;中英文文档同步字段与组合选项说明。

验收标准

  • focus / import / split / query / config 全部支持 --json,且各分支有测试
  • JSON 模式失败:stdout 为空、诊断在 stderr、退出码非零、含稳定错误码
  • query --template-info 缺失模板时退出码非零(协同 [BUG] query --template-info 对缺失模板仍返回退出码 0 #112)
  • 人类可读输出保持不变(错误流 / 退出码的兼容策略单独说明并测试)
  • 已有 metadata / report peak-memory JSON 字段兼容
  • 文档(docs/en/、docs/zh/)补充 --json 说明
  • JSON 输出无 ANSI、无多余日志污染 stdout

Activity

  1. codeasier commented on Sep 17, 2026

    @codeasier
    OwnerAuthor

    评审结论:需求真实,复用 core service 结果模型提供 JSON 输出的方向合理。建议补充以下实现与验收边界:

    1. 错误输出要求需要修正现状描述

    "错误输出保持 stderr + 非零退出码"目前并非既有行为:

    • src/pt_snap_cli/cli.py:648 的 _error() 默认写入 stdout。
    • src/pt_snap_cli/cli.py:364 的 query --template-info 在模板不存在时输出错误,却返回退出码 0;tests/test_contract_cli_mcp.py:374 还明确断言了该行为。
    • 部分 query/report 错误分支也直接写入 stdout。

    已通过 CliRunner 复现上述前两项。建议明确:JSON 模式失败时 stdout 为空,诊断写 stderr,退出码非零;是否同步修正文本模式的错误流和退出码,需要明确兼容策略,不能同时笼统承诺"所有行为不变"。

    2. 复用结果模型,但补齐 JSON 序列化契约

    FocusState、ImportResult、SplitResult 包含 Path,直接 json.dumps(asdict(...)) 无法序列化。建议共享辅助函数统一处理路径字符串、嵌套模型、数组及 None → null,保留数值和布尔类型。

    查询结果建议沿用 QueryResult 的 total / returned / device_id / rows,保留现有 -n 语义。已有 metadata、report peak-memory 的 JSON 字段应保持兼容。

    3. 明确各命令分支的输出

    • focus:覆盖读取、设置、仅修改设备、--global、--session。其中 --session --json 应明确返回验证结果及环境变量赋值信息,不应混入 shell 文本,也不能暗示已修改父 shell。
    • config:覆盖读取、--path、--clear,维持其仅管理 legacy global config 的语义。
    • query:覆盖执行、--list、分类筛选及 --template-info。
    • split:--json 控制 stdout 结果清单,--format json 控制分片文件格式,两者应独立。

    4. 补充验收测试

    建议直接对完整 stdout 执行 json.loads(),覆盖正常结果、空结果、未配置 focus、导入缓存复用、分片清单和查询限行;错误路径分别断言 stdout、stderr 和退出码,并检查 ANSI/日志污染。

    同步增加 tests/test_contract_cli_mcp.py 的 JSON 语义对齐断言,保留文本输出回归测试,并更新中英文文档中的字段及组合选项说明。

  2. codeasier commented on Sep 17, 2026

    @codeasier
    OwnerAuthor

    正文已按评审意见更新:修正现状描述(错误当前写入 stdout、缺失模板退出码 0);明确 JSON 模式失败契约(stdout 空 / stderr / 非零退出码 / 稳定错误码)、共享序列化辅助(Path 处理)、逐命令分支覆盖、split --json 与 --format 独立;补充结果信封(执行上下文元数据)作为扩展项,兼容既有 metadata / report JSON 字段。关联 #112。

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