脚本长到有五个子命令后，光给出一串参数名不够。调用者需要知道 UTF-8 输入的四列、空结果状态、服务名规范化和报表是否写文件；如果帮助只说明“按日志统计”，运维程序可能把空查询与解析失败当成一回事。

CLI 在 __END__ 后保留 NAME、SYNOPSIS、DESCRIPTION 三段 POD；--help 由随 Perl 安装的 Pod::Usage 2.03 读取同一文件生成文本。实际运行 perl examples/perl-language/bin/logtool.pl --help：STDOUT 从 NAME 开始并列出 report-csv FILE 与空集的状态 0 等契约，STDERR 空、退出码 0。起初直接要求 verbose 2 时，环境里的 perldoc 命令提示没有安装 perl-doc 包，虽有输出却污染 STDERR；改为 -noperldoc => 1 后用内置解析器生成同一份 POD，不靠关闭警告假装无故障。

反例 --help unexpected 不会静默忽略多余参数：STDOUT 空，累计版本的 STDERR 是 usage: perl bin/logtool.pl import|parse|query|report|report-csv|report-file|probe FILE [ARG]，退出码 2。这个故障只是命令参数合同，并非文件内容错误。累计帮助分别描述 STDOUT 报表和 report-file 文件替换，不能继续把早期阶段的“仅输出到 STDOUT”当作当前接口。

POD 示例也是接口调用

新版 bin/logtool 同样把帮助保存在文件末尾 POD，通过 Pod::Usage 的内置解析链生成 --help，不依赖外部 perldoc 程序。SYNOPSIS 给出五字段导入、JSONL 查询、最低耗时零、字面查询及保存报表。CONTRACT 明确 UTF-8、字段类型、两个输出并非共同事务、失败退出码和 STDOUT close；实现变更必须检查这几段是否仍一致。

示例写成 /tmp/accepted.jsonl 是为了展示独立交换文件；正式回归使用 File::Temp 创建的目录，不复用同一个固定路径，避免一份旧文件让下一次示例错误地“成功”。t/course-cli.t 对帮助中实际选项和真实导入/查询/报表分别断言。tools/replay.pl --case all 保存每次参数数组、状态、两个输出流及摘要，它补足单看渲染后的代码块无法获得的执行证据。

POD 成功转换成文字只证明文档语法可读取。若例子拼错字段格式、引用不存在文件或使用被删除参数，它仍可能渲染正常。因此文档例子与命令测试要共享真实接口，而不是共享一份人工假定的输出。课程的故意破坏金标实验另行证明 harness 能把错误报告为失败。

[PATTERN] 文档的命令是可执行契约。把示例放进隔离回归，并区分“文档可解析”与“示例行为正确”。

练习：若 report-csv 增加一个目标路径参数，能否只改 SYNOPSIS？不能；CLI 参数验证、拒绝分支、使用说明和金标必须共同更新。第二题：为什么正确显示帮助不能证明 SQLite 事务回滚？帮助不运行数据库行为，依赖实验必须独立执行。

文档检查 证明范围
POD 解析 语法与帮助输出
CLI 示例回归 参数与结果行为
页面代码可见 网站交付

examples/perl-language/evidence/24-help.stdout 保存历史帮助，当前帮助与重放在补全证据；参考官方 Perl 5.38.2 pod/perlpod.pod（Command Paragraph、Embedding Pods in Perl Modules）和 Pod::Usage 2.03 文档。