### 功能描述 `metadata` 与 `report peak-memory` 已支持 `--json`,但 `focus`、`import`、`split`、`query`、`config` 仍只有人类可读文本。除格式缺口外,当前错误路径还有两个与 Agent 可靠性直接相关的缺陷(已复现): - `_error()`(`cli.py:648`)默认写入 stdout; - `query --template-info` 模板不存在时输出错误却返回退出码 0(#112,且 `tests/test_contract_cli_mcp.py:374` 明确断言了该行为)。 ### 使用场景 Agent 需要稳定解析成功与失败两种状态:不能依赖错误文本猜测原因,也不能把执行失败当作「没有发现问题」。 ### 期望的实现方式(已并入评审意见) 1. **JSON 模式错误契约**:失败时 stdout 为空、诊断写 stderr、退出码非零;结构化错误包含稳定错误码(如 `TEMPLATE_NOT_FOUND` / `INVALID_PARAMETER` / `DATABASE_NOT_FOUND` / `DEVICE_NOT_FOUND`)与可操作的修正提示。文本模式是否同步修正错误流与退出码需明确兼容策略(关联 #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` 缺失模板时退出码非零(协同 #112) - [ ] 人类可读输出保持不变(错误流 / 退出码的兼容策略单独说明并测试) - [ ] 已有 `metadata` / `report peak-memory` JSON 字段兼容 - [ ] 文档(`docs/en/`、`docs/zh/`)补充 `--json` 说明 - [ ] JSON 输出无 ANSI、无多余日志污染 stdout
Activity
codeasier commentedon Sep 17, 2026
评审结论:需求真实,复用 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还明确断言了该行为。已通过 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 语义对齐断言,保留文本输出回归测试,并更新中英文文档中的字段及组合选项说明。codeasier commentedon Sep 17, 2026
正文已按评审意见更新:修正现状描述(错误当前写入 stdout、缺失模板退出码 0);明确 JSON 模式失败契约(stdout 空 / stderr / 非零退出码 / 稳定错误码)、共享序列化辅助(Path 处理)、逐命令分支覆盖、split --json 与 --format 独立;补充结果信封(执行上下文元数据)作为扩展项,兼容既有 metadata / report JSON 字段。关联 #112。
fix: keep capabilities/overview failures in the JSON envelope
fix: keep capabilities/overview failures in the JSON envelope
feat: add capabilities and overview commands to cut agent probe calls (…