背景

在 PR #220(gc precommit check)的评审中,有几条建议经评估后暂缓到后续 PR 处理(非阻塞),本 issue 用于跟踪。

来源:PR #220 6-agent 评审的 P2 / 行内建议项。

待办项

1. precommit check --json 增加结构化失败原因字段(原 P2 #10)

当前通过 ok + run_result + run_output + stderr 提示区分失败,但没有单独的 error / reason 机器可读字段。

• 期望:为消费者(脚本/agent)提供稳定的失败分类字段,例如 reason: "no_config" | "tool_missing" | "hook_missing" | "run_failed" | "not_in_repo"。
• 影响:扩展 pkg/precommit.Result 的 JSON 契约,需同步 docs/COMMANDS.md。

2. 安装失败按错误类型细分(原 P2 #17)

EnsureTool 当前聚合各 installer 的失败详情为一条错误,但不区分"权限不足 / 网络失败 / 工具链缺失"。

• 期望:对常见失败做分类与更有针对性的修复指引。
• 影响:pkg/precommit/install.go;注意保持跨平台与可测试性(经 CommandRunner 注入)。

3. ToolVersion 版本探测改用 stdout-only(原行内建议 / detect.go L26)

当前经 CommandRunner.Run 使用 CombinedOutput()(混 stdout+stderr)。若未来 pre-commit --version 在 stderr 输出 warning,可能干扰版本解析。

• 期望:版本探测仅读取 stdout(cmd.Output())。
• 影响:需要扩展 CommandRunner 接口以区分 stdout/stderr(改动面相对较大),故与上面两项一并排期。

验收

• 上述各项实现并补单元测试(沿用 fake CommandRunner,不依赖真实 pre-commit)。
• 同步更新 docs/COMMANDS.md 与设计文档 docs/superpowers/specs/2026-06-03-precommit-check-design.md。

关联

• 功能 PR: #220
• 原始需求: #258