# R4 任务报告：改进 web-probe screenshot 参数纠错

## 任务回链

- MDTODO：`docs/MDTODO/web-observe-runtime-reliability.md#R4`。
- GitHub Issue：`pikasTech/unidesk#2425`。
- 交付类型：`pr-lightweight`。
- rollout：`not-applicable`。

## 问题与根因

- `web-probe screenshot --url <custom-url> --path <path>` 会正确拒绝互斥参数，但只返回普通字符串错误。
- `web-probe screenshot --help` 被顶层帮助提前接管，没有 screenshot 专属的 semantic、custom 和 local 完整示例。
- 错误输出没有 typed reason、`mutation=false` 和可直接执行的修正命令，用户需要自行推断应删除哪个参数。

## 修改

- 新增 `web-probe screenshot` scoped help：
  - semantic origin 使用 `--origin internal --path /workbench`；
  - custom URL 和 localhost URL 直接包含完整路径；
  - 明确 `--url` 与 `--path` 互斥。
- 将互斥校验改为 `CliInputError`：
  - `code=web-probe-screenshot-url-path-mutually-exclusive`；
  - `reason=custom-url-already-includes-full-path-remove-path`；
  - `mutation=false`；
  - `correctionCommands` 保留原调用参数并移除 `--path`。
- 同步 `unidesk-webdev` 高频 semantic、custom 和 local 示例。
- 不修改浏览器能力、资源门禁、CI/CD、YAML semantic origin 或运行面。

## 验证

- 运行 screenshot scoped help 合同，确认输出非空并包含三类完整示例。
- 运行互斥参数 JSON 合同，确认 typed reason、`mutation=false` 和修正命令。
- 运行相关 Bun 定向测试与轻量语法检查。

## 结论

- R4 已完成源码、合同和文档收敛。
- 该修改只影响 CLI 帮助与输入错误可见性，`rollout=not-applicable`。
