压缩命令输出

构建日志、测试运行、编译器诊断是 agent 上下文膨胀的另一半。ctxctl exec 运行一条命令， 只返回真正重要的行：带 file:line 位置的关键错误/警告行，加上头尾摘要，其余全部折叠成 一行标记。

默认流水线已经够用

不带参数时，exec 保留匹配 error、warning、failed、panic、fatal （大小写不敏感）的行，保留诊断位置行（--> src/foo.rs:12:34，rustc/cargo 风格）让错误 带着上下文，并显示头尾各 5 行：

ctxctl exec "cargo build"

$ cargo build
error[E0308]: mismatched types --> src/main.rs:12
... [34 lines omitted]
warning: unused variable: `x` --> src/server.rs:88
   = note: 2 warnings emitted
Saved ~70% (1,240 -> 372 tokens)

输出超过 20 行（折叠阈值）才会触发折叠，短命令原样通过。被包裹命令的退出码透传——0 就是 成功，与压缩无关；Unix 下子进程被信号杀死时退出码为 128 + 信号。

选好 –keep 模式

--keep 向配置的默认模式追加一个正则（rg 语法），而不是替换它们：

# 测试结论与错误一起浮出
ctxctl exec "cargo test" --keep 'FAILED|passed'

# Go 构建：暴露包级失败
ctxctl exec "go build ./..." --keep 'cannot|undefined'

挑选匹配结论行而非噪音的模式：

• 好： 状态词（FAILED、passed）、你所用框架的失败标签（E0308）、断言标记 （AssertionError）。
• 危险： test、run、文件名这类泛化词——它们会命中大多数行，让压缩失效 （见下文警告）。

调优头部与尾部

头部保住命令回显；尾部承载最终摘要（“N tests passed”、“N warnings emitted”）。按调用调整：

ctxctl exec "cargo test" --head 10 --tail 15

或在项目的 .ctxctl/config.toml 中改默认值：

[exec]
keep = ["error", "warning", "failed", "panic", "fatal"]
head_lines = 5
tail_lines = 5
collapse_threshold = 20

设 collapse_threshold = 0 可以只要有可折叠内容就折叠；空 keep 列表 （keep = []）表示彻底关闭中段保留，而不是保留每一行——位置行的隐式保留在两种情况下都生效。

过宽的模式会被点名

如果折叠执行了却只省下不到 10%——--keep 模式几乎命中每一行的典型症状——ctxctl 会在文本 输出末尾追加一条确定性的 warning: 行。输出仍然字节稳定；警告只是确定性结果的一部分。 把它当作收紧模式的提示，不是错误。JSON 模式（--json）下它变成顶层的 warning 字段。

exec 里没有 shell

exec 按 shell 分词方式拆分命令后直接执行——没有交互式 shell，因此管道、重定向、通配符、 && 链都不能直接使用。复合命令要显式交给 shell 包裹。另一个要知道的流行为：子进程的 stdout 先于 stderr 输出，两条流的时间交错不会被保留。

# 错误：管道会被当成普通参数拆开
ctxctl exec "cargo build 2>&1 | tee build.log"

# 正确：把整个字符串交给 shell
ctxctl exec 'sh -c "cargo build 2>&1 | tee build.log"'

这是第一天最常踩的坑——agent 尤其倾向于假设存在完整 shell。如果输出像一锅参数汤，原因就在这。

CI 日志工作流

日志分诊是 exec 的高光场景：输入无上限，而有趣的内容极小。脚本化 agent 基准中，分析一份 1,914 行确定性构建日志的任务相对原始读取拿到 −84% 任务成本：

# 本地：当场压缩任何命令的输出
ctxctl exec "npm run build" --keep 'error|warn'

# CI：让失败步骤经 shell 重跑或回放，只浮出关键行
ctxctl exec "sh -c './ci.sh 2>&1 | tee ci.log'" --keep 'FAIL|error'
ctxctl exec "sh -c 'grep -nE \"(error|failed)\" ci.log'"

实践中最简单的 CI 模式是让失败步骤跑在 exec 下，压缩后的记录直接进 issue 报告或 agent 的 上下文。压缩增量流式进行且内存有界，GB 级日志也安全。

脚本化使用：JSON 模式

在 shell 脚本或流水线里编排时，加 --json（等价于 --format json）拿到机器契约：固定信封、 稳定 schema 版本。文本模式下错误走 stderr，而 JSON 模式下错误信封 {"error": {"code": <exit-code>, "message": "<text>"}} 打印到 stdout——机器消费者始终只有 一个可解析的流。退出码语义不变：exec 透传被包裹命令的退出码。不需要节省统计时， 全局参数 --no-saved 可以隐藏 saved N% 输出。

想以同样的纪律读源码文件，见探索陌生代码；想把这套命令作为工具暴露给 agent， 见接入编程代理。完整参数列表见命令。