cartoon 是一个命令行包装二进制工具，目标是通过压缩 CLI 输出为 TOON 格式来节省输入 token。TOON 是专为 LLM 消费设计的紧凑格式：测试通过项折叠为计数，失败项保留完整可操作细节（位置、消息、用户代码回溯）。典型测试运行输出可缩减约 70% 以上，退出码与行为保持不变。
用途
cartoon 用于包装会产生大量输出的开发命令，尤其是测试套件（pytest、jest、unittest）、输出 JSON 的 CLI（aws、gh、kubectl 等）以及构建等嘈杂命令。它不改变被包装命令的参数与行为，只重新渲染输出。
主要能力
- 前缀式使用：所有标志和参数原样保留，例如 cartoon pytest、cartoon npx jest src/、cartoon aws ec2 describe-instances --output json、cartoon make。
- 专用适配器：pytest、jest、vitest、swift test/build、xcodebuild test/build、ruff、eslint、tsc 等有专门适配器，应直接裸跑以便自动包装钩子捕获，不要放在管道后面。
- 无适配器命令仍可压缩：安全层（ANSI、进度、重复、空行折叠）自动应用；--compress=aggressive 可启用有损规则（日志级别过滤、诊断表、错误窗口化）。净节省保护意味着最坏情况输出与原始字节一致，包装不会更差。
- 结果阅读方式类似测试报告：摘要包含计数；若 failed > 0，failures[...] 行和 traces 部分包含修复代码所需的一切，无需重跑未包装命令。
- 原始输出存档：每次包装运行会把完整原始 stdout/stderr 存到磁盘，并在报告最后一行打印位置，例如 raw_log: ~/.local/state/cartoon/runs/20260611-051415-342d。需要检索时用 cartoon logs grep "ERROR" --last -C 2，而不是 cat 整个文件。
- 统计：cartoon stats 显示累计节省的 token。
使用方式
先检查是否安装：command -v cartoon。若缺失或想设置自动包装（PreToolUse 钩子或 shell shims），需阅读 install.md；若无法安装则跳过包装，不要因此阻塞用户任务。
基本用法是加前缀，例如 cartoon pytest、cartoon make、cartoon ingest build.log、some-cmd | cartoon -。不要预先截断嘈杂命令：不要用 head/tail/grep 缩小输出，因为那会保留任意切片（常常是错误切片），且钩子不会包装管道命令，从而完全失去 cartoon。正确做法是先包装，若仍需原始日志切片，再用 cartoon logs grep … --last。
安全性与退出码
退出码始终镜像：cartoon pytest && deploy 的行为与 pytest && deploy 完全一致。若解析失败或压缩形式实际不节省 token，原始输出原样通过，信息不会静默丢失。用户提供的参数不会被移除或重排。
不适用场景
- 交互式或依赖 TTY 的命令（REPL、watch 模式、git rebase -i）。
- 用户明确要求查看完整原始输出时。
- 短命令（git status、ls），没有节省空间。
- 只需一次原始输出时，可用 cartoon --raw <cmd> 或去掉前缀。
- 加速标志如 --fast 会改变测试执行方式，仅在用户明确要求更快运行时使用，调试任何失败前应不带该标志重跑。
自动包装
钩子或 shell shims 可能已自动包装嘈杂开发命令，因此裸跑的命令可能返回 TOON。非嘈杂命令（git、ls、docker 等）原样通过，包装输出是缓冲的（命令完成后才打印报告，而非实时）。需要关闭时：export CARTOON_NO_WRAP=1（钩子）或 CARTOON_NO_SHIM=1（shims），或对单条命令用 cartoon --raw <cmd>。设置、范围与卸载见 install.md。
当前完整标志、子命令（stats、logs 等）和适配器列表以二进制为准，可运行 cartoon --help 查看。